Security hardening: replace message-text lifecycle commands with typed, authorized controls

[yui-stingray]

Problem

ctrl:despawn is currently an ordinary message body with privileged lifecycle side effects. despawn.sh sends it through send.sh; watch.sh branches on exact body equality and, for an exclusive watcher, drops the target role and can close its tmux pane or a matching recorded herdr pane.

In normal mode, send.sh verifies that the supplied from_agent and to_agent names exist in the team roster. Its --force option can bypass that membership check. Neither path proves that the caller owns the claimed sender session or is authorized to control the target.

The messages table stores a team, sender label, recipient label, body, timestamps, and read state. It has no record type, operation, issuer session, target generation, authorization proof, expiry, or replay key.

This creates data/control-plane confusion: a path permitted to submit an ordinary message under a registered logical sender can cause an exclusive target watcher to interpret message text as lifecycle authority. Existing broad-watcher and placement guards validate the receiver and placement, not the issuer. Current placement metadata also has no owner/session authority to validate.

The immediate impact is control integrity and availability inside an agent team: a watcher-backed role can be unregistered and its session terminated. This is not a local privilege-escalation claim.

Evidence on current main

The behavior introduced by #129 remains present on main at commit c1415e9ea571069d5bae5692d0da9424aabf71dc (VERSION 1.1.11).

• scripts/despawn.sh sends the magic body through the normal message API.
• scripts/send.sh performs roster membership checks and then persists the caller-supplied sender label and body.
• scripts/watch.sh executes the lifecycle branch from body == "ctrl:despawn" without authorizing the sender before resetting the role.
• The schema in scripts/internal/init-db.sh gives ordinary messages no typed-control or authorization fields.
• tests/test_watch.bats uses an ordinary registered peer to deliver the control text that drives watcher teardown. This pins the current mechanism; it is not evidence that the peer has lifecycle authority.

I reviewed this revision and its existing regression tests statically. I did not execute teardown against a live pane or session.

Security boundary

This issue protects the control dispatcher from treating untrusted inbound data, caller-selected sender labels, stale controls, or misrouted controls as lifecycle authority. A message body remains untrusted data even when another registered role sent it.

This does not claim isolation from a hostile process or user that can edit agmsg's database or run state, replace scripts, invoke local teardown commands directly, or signal sibling processes under the same OS account. A fully compromised peer with arbitrary same-user shell access is outside this boundary.

Local OS-user access remains the ultimate trust boundary. Any future remote-to-local lifecycle operation requires an explicit local authorization decision; it must not become local process-control authority merely because a remote credential was accepted.

Proposed contract

1. Separate data from control. Ordinary rows in messages are always data. A watcher must never perform lifecycle actions from a body prefix or exact body value. Introduce a dedicated typed control API and storage separate from ordinary message bodies.

2. Start with one closed operation. Version 1 supports only lifecycle.despawn. Future operations such as spawn, drop, monitor stop, or rebind require an explicit operation definition and authorization policy. Unknown versions and operations fail closed.

3. Bind issuer and target. At spawn time, record the controller identity/session, a unique target generation, and authority material for that generation. A control identifies its team, operation, issuer identity/session, target role, exact target generation, issuance and expiry times, and idempotency/replay key.

4. Use application-level proof, not a sender label. Bind the controller through a per-spawn capability or equivalent verifier. Do not treat a caller-supplied from_agent as proof of authority. Reusable authorization material must not enter messages.body, history output, or normal logs.

5. Authorize before side effects. Graceful despawn is accepted only from the recorded controller or another explicitly defined local authority, and only for the current target generation. Liveness and placement matching are necessary checks, but neither is authority.

6. Make results durable and idempotent. Persist accepted, rejected, and completed state. Re-delivery does not repeat teardown. Expired, replayed, wrong-controller, wrong-target, unknown, or malformed controls produce no lifecycle side effect and expose only a bounded status result.

7. Keep force recovery separate. despawn --force remains an explicit local recovery command outside inbound message/control ingestion. It validates the recorded placement before signalling and cannot be triggered by an inbound record. This does not protect against a same-user process bypassing agmsg and signalling the target directly.

8. Migrate safely. Add and test the typed path before disabling the legacy magic-body branch. End state: literal ctrl:despawn text in an ordinary message is data and never tears down a role.

Non-goals

• General encryption or mutually hostile multi-user isolation on one OS account.
• Containment of a peer with arbitrary same-user shell or process-control access.
• Fixing Monitor が同一プロジェクトの全 claude-code セッションに特定 team-agent 宛メッセージを配送する（identity が project + agent_type だけで解決される） #300's broad message fan-out.
• Replacing Atomic message consumption: prevent duplicate delivery and inject-failure loss with claim/ack #373/Add claim/ack API + PID sentinel helper for atomic delivery #372's data-delivery claim/lease/ack work.
• Adding a background worker, wake mechanism, or arbitrary-command control type.

Acceptance criteria

• An ordinary message whose body is ctrl:despawn cannot drop a role, release its lock, or close a pane, regardless of its claimed sender label.
• A valid, authorized lifecycle.despawn for the current target generation performs graceful teardown once and records one durable terminal result.
• Missing or invalid authority, spoofed issuer, wrong target generation, expiry, replay, duplicate delivery, unknown operation/version, and malformed records fail closed without lifecycle side effects.
• A broad watcher or unrelated session cannot execute a control for an exclusive target even if it observes the record.
• No capability or reusable secret appears in the message table, history output, normal logs, or test snapshots.
• Existing installations upgrade without losing message history, with an explicit compatibility/deprecation path.
• despawn --force remains a separate local recovery path unreachable through inbound control ingestion.

Tests

Add deterministic coverage for ordinary-body regression, authorized graceful despawn, unauthorized/spoofed senders, wrong generation/stale placement, expiry/replay/duplicates/malformed/unknown versions, broad versus exclusive watchers, crash/restart, tmux/herdr placement mismatch without a real host pane, schema migration, and secret absence.

Related work

• feat(spawn): despawn — graceful crew teardown (ctrl:despawn) with --force fallback #109/feat(despawn): tear down spawned crew members (#109) #129 introduced despawn.
• Monitor が同一プロジェクトの全 claude-code セッションに特定 team-agent 宛メッセージを配送する（identity が project + agent_type だけで解決される） #300 concerns recipient fan-out and is not resolved by this change.
• Atomic message consumption: prevent duplicate delivery and inject-failure loss with claim/ack #373/Add claim/ack API + PID sentinel helper for atomic delivery #372 concern data claim/ack, not lifecycle authorization.
• fix(liveness): a process you cannot signal is not a process that is gone #505 concerns liveness, not sender authorization.
• Codex monitor: persist actas role and require visible handling across restarts #365/fix(codex): persist visible monitor delivery across restarts #366 and Codex Desktop: opt-in inbox monitor with thread wake and watchdog #374/Codex Desktop: add native Scheduled inbox monitor #375 provide Codex monitor delivery context, but do not authenticate lifecycle controls.
• feat(watch): opt-in catch-up drain of unread inbox on fresh attach (#229) #476 explicitly excludes ctrl:* from catch-up because stale controls are unsafe to replay.
• feat(app): launch a member pane from outside the GUI (external / scripted spawn) #340/feat(app): external-spawn via single-instance args (reference impl for #340) #341 explore external spawn and should use an explicit authorization contract if they later gain lifecycle-control capabilities.

These items are related context; none currently authenticates local lifecycle controls.

[yui-stingray]

Design-convergence checkpoint — this is not an implementation-complete claim.

I rechecked main@c1415e9, open/unmerged PR #518 at 1883581, open issue #519, and its orphan-mutex prerequisite #68. I did not find a competing implementation PR or a second lifecycle-control umbrella. #514 remains the right place to converge the architecture.

I compared three boundaries:

1. Process-instance provenance only. This can narrow a stale/misrouted watcher case, but ordinary message text and caller-controlled labels remain authority, and it does not imply fix(despawn): never invoke placement providers from graceful teardown #518 containment.
2. A session-seat capability boundary. This keeps the current local/no-daemon model while moving lifecycle authority, target lifetime, readiness, revocation, and durable outcome into typed state.
3. A protected broker or explicit user confirmation. This may be appropriate for a future hostile-same-UID or remote-authority threat model, but it adds a new trusted service/interaction surface and does not repair the current path by itself.

I conditionally recommend option 2, but implementation should remain stopped at Gate 0 until maintainers confirm the canonical lifecycle namespace. The current candidate is a separate fixed $SKILL_DIR/db/lifecycle.db for one install/registry domain. Existing messages.db and per-process AGMSG_STORAGE_PATH resolution should not own lifecycle protocol state. The unresolved question is how one domain is discovered across multiple --cmd installs, symlinks, Windows path normalization, and a future app; hidden, unverifiable, or independent roots must block typed cutover rather than create split authority.

After Gate 0, the proposed contract is:

• Phase A is additive and dormant only: one singleton containing schema_version, mode, protocol_epoch, and updated_at, plus at most a read-only snapshot helper. It adds no activation API, authority rows, requests, executors, effects, or capabilities.
• Controller authority is bound to a trusted (controller_driver, stable_seat_id), an explicitly selected registration key (team, agent, type, canonical_project), that registration's exact lifecycle generation, and a monotonic authority fence. A seat with multiple registrations gets no implicit default. Leave/rebind revokes the exact controller row before JSON removal. A target respawn does not revoke an otherwise-valid controller row; it revokes only the old grant bound to (team, agent, type, canonical_project, target_generation) and rotates a new grant under the still-valid controller fence. Admission, request commit, and final effect recheck the still-unrevoked controller fence and exact unrevoked target grant.
• Existing registration fields, including type and canonical project, remain compatible. Nested lifecycle state is limited to provisioning|active|terminating; retirement removes the exact JSON registration and retains only target-level journal observations.
• Cross-store work is an explicit saga, not an atomicity claim: prepared -> vault_published -> registration_provisioning -> runtime_staged -> registration_active -> committed -> ready_published -> operational. runtime_staged is non-admissible placement/bootstrap material. Normal work requires committed + exact active registration + immutable exact ready/placement + operational state.
• For lifecycle.despawn, the final-effect authorization CAS is the physical effect's linearization point. With the exact fix(actas-lock): make release and stale GC generation-fenced compare-and-delete #519 actas mutex already owned, it rechecks the lifecycle-DB active-registration receipt/fence and current request, runtime, epoch, controller, and target predicates. In the same transaction it writes one durable effect_authorization_id and reserves the target-scoped slot keyed by the full target tuple plus exact registration generation/fence; it does not claim an atomic SQLite+JSON read. Only afterward may code take the registry lock, reread the exact active tuple, and CAS it active -> terminating; after releasing the registry lock, teardown may run under the still-owned actas mutex. Revocation-first produces no effect; authorization-first may finish after later revocation. Any unknown outcome after authorization keeps the target reserved and becomes indeterminate plus target-level recovery_required, with no automatic retry.
• Request state is pending|claimed|applying|completed|rejected|expired|failed|indeterminate. Only expired claimed work may be reclaimed. A lost applying actor becomes indeterminate; recovery_required is a separate target-level observation, never a request state.
• Phase B creates the initially-open launch-gate row and lease store, then makes every known launcher/effect path acquire a durable dormant/open legacy_intent_lease; any Phase-B drain is preliminary. Phase C atomically closes the gate and moves dormant -> preparing, serializing against new leases. An exact bounded lease acquired before that CAS may finish under its fence; expiry, partial failure, or unknown liveness never counts as terminal absence. Typed activation requires authoritative fenced terminal receipts, a pre-Phase-B process drain, immutable versioned bundles selected by a holder-fenced pointer, quiescence of all current-holder filesystem writers, and a final digest/state re-audit. Preparing takeover requires proven quiescence of the prior holder and every external helper, child, and legacy lease. Later typed maintenance uses a separate fenced CAS that atomically closes the launch gate and suspends admission: it denies new request commits and new claims, leaves existing pending rows pending and unclaimable except for normal expiry, and denies claimed -> applying. Neither path silently returns to dormant.
• Retention is unbounded before Phase D. Write failure denies new admission/effect, but complete physical exhaustion may also degrade status and recovery; no stronger readability guarantee should be made before reserve/quota/GC behavior is approved and tested.

Implementation prerequisites remain explicit: #518 is containment only and is still unmerged. #519 must first provide owner-plus-actas_claim_token compare/delete and stale-liveness revalidation. #68's age-only cleanup does not by itself prove that the mutex holder is stale; its recovery and rollout contract needs separate review before #519 can depend on it. The later #514 integration must additionally bind target_generation and the controller fence for conditional release, rebind, and stale cleanup. None of these should be inferred complete from this design. The validation plan uses focused local tests and proposes no CI/workflow edit.

Could a maintainer confirm (1) the canonical lifecycle root/registry-domain scope and (2) the trusted stable-seat source plus explicit controller-registration selection policy? Keep Phase A stopped until the canonical lifecycle root is settled, and resolve the stable-seat source and registration-selection policy before controller authority or typed admission is implemented. Until then, retain manual recovery.