projmux 0.15.3 → 0.16.1

package/docs/claude-coordination-endpoints.md

@@ -17,15 +17,27 @@ Managed Agent/Pane names and Claude session titles are not route authority.
 Renaming an unchanged UID/activation preserves its registration. Phase 1 does
 not discover unmanaged provider names or observe live Claude `/rename` events.
 Competing session/process/helper claims for an exact activation are refused;
-the exact child's next SessionStart atomically claims a new registration
-generation before launching its helper. Delayed admission and cleanup from an
-older generation cannot overwrite or clear that newer registration.
+the helper launched by the exact child's next SessionStart claims a new
+registration generation and records it Ready in one Registry transaction, so
+no claimed-but-not-Ready registration is ever published. The claim is a
+compare-and-set on the registration generation the hook observed, so delayed
+admission and cleanup from an older generation cannot overwrite or clear a
+newer registration.
 
 The activation gate records the actual child PID and kernel birth identity
 before replacing itself with Claude. The separate managed SessionStart hook
-uses `exec`, making the registered provider its direct parent. The helper
-verifies the complete helper → hook → provider process chain while the hook
-waits for a bounded startup acknowledgement. A nested unmanaged Claude cannot
+uses `exec`, making the registered provider its direct parent. The hook never
+takes or waits on the Registry lock: it reads the Registry lock-free, starts
+the helper, and waits only for a bounded startup acknowledgement, all inside
+Claude's hook timeout. The helper verifies the complete helper → hook →
+provider process chain, then claims and records the registration in its own
+lifetime, bounded by the Registry lock acquisition timeout. The hook's wait
+bounds only the hook: when it ends without the acknowledgement, the hook
+releases the helper instead of killing it, and a helper whose acknowledgement
+nobody reads still records and keeps its registration. A released helper that
+cannot record, or whose generation is no longer current, exits without writing
+and removes its lease files by itself.
+A nested unmanaged Claude cannot
 register its own endpoint through inherited activation environment variables.
 The creator-selected Registry path travels only in private Claude activation
 context, independent of a tmux server's older XDG environment.
@@ -107,8 +119,11 @@ the same lease. Its address is derived from the exact `AgentRouteRef`; names,
 tmux `%N`, the provider socket, and the provider token do not enter that address
 or its protocol. Every operation revalidates Agent UID, Pane UID, activation
 generation, provider/helper process births, registration generation, and route
-incarnation. Normal exit and cleanup unlink only the exact owned coord socket
-inode. Projmux never creates a replacement provider listener or relay.
+incarnation. The route incarnation follows the provider conversation (the
+Claude session), so a same-session SessionStart keeps it; the process birth
+and registration generation checks are what fence a replaced helper. Normal
+exit and cleanup unlink only the exact owned coord socket inode. Projmux never
+creates a replacement provider listener or relay.
 
 Claude ingress is immediate push. There is no receiver waiter, pending ingress
 queue, `asyncRewake`, `begin-handoff`, or `no-waiter` state. The helper retains
@@ -168,10 +183,163 @@ a new explicit command. A version string supplied by the caller is never proof.
 After qualification, `agent message send` persists the exact immutable broker
 handoff before any provider byte. A missing, mismatched, or unwritable durable
 record therefore writes zero. The pushed content is a structured
-`projmux-coordination` object with `untrusted-coordination-only` authority and
-the exact source/target routes, `messageRef`, `conversationRef`, `replyTo`, and
-payload. It cannot start or steer a user turn, answer an approval, interrupt a
-turn, execute a tool, call a connector, or write Codex app-server/model history.
+`projmux-coordination` object with `untrusted-coordination-only` authority,
+the source and target `agentUID` and `provider`, `messageRef`,
+`conversationRef`, `replyTo`, payload, a `sourceNotice`, and a `replyAction`.
+It cannot start or steer a user turn, answer an approval, interrupt a turn,
+execute a tool, call a connector, or write Codex app-server/model history.
+
+The frame route is deliberately narrower than the durable one. The delivery
+fences (`paneUID`, `activationGeneration`, `incarnation`) stay on the durable
+envelope: no frame reader uses them, and a reply re-resolves its route from the
+durable record, not from the frame. `sourceNotice` says the source is a claim
+and the payload untrusted peer coordination; it stays on every frame, including
+one whose source and target are the same Agent, because `--source` is an
+unverified claim. That self-anchored frame has the same keys with an empty
+`replyAction`, since there is no peer to answer. The Codex turn body follows
+the same route, notice, and self rules.
+
+The object also carries the integer `schemaVersion`, currently `2`. Version 2
+narrowed the routes, shortened `sourceNotice`, and emptied a self-anchored
+frame's `replyAction`; for an Agent frame it only removed keys and changed
+values. Version 2 also has the operator-input variant described below, which
+a reader tells apart by its `source` fields, not by the version. The target's
+helper renders the frame, so a helper started before an upgrade keeps sending
+the older shape until that Agent is activated again. `schemaVersion` names
+that object's shape only and moves independently of the durable envelope
+version and the message store's on-disk version. A missing `schemaVersion`, or
+an explicit `0`, reads as `1`: every frame written before the field existed has
+that shape. A reader meeting a higher `schemaVersion` reads the fields it knows
+and still surfaces the message; an unknown version is never a drop and never an
+error, because a peer message that silently disappears is worse than one read
+by a slightly stale reader. The append-only eviction history log record uses
+the same field name, the same default, and the same higher-version rule.
+
+### Held while the target awaits its operator
+
+A push frame reaching Claude while it shows its operator an `AskUserQuestion`
+question, a permission dialog, or an MCP elicitation renders as pending input
+and can push that widget off a narrow screen. So `agent message send` does not
+call the target's helper while the target Agent's effective interaction is
+`approval_required` or `input_required`. It keeps the accepted record in the
+existing `held` state with reason `target-awaiting-operator`, prints
+
+```text
+<messageRef>	held	target-awaiting-operator	delivery resumes automatically when the target Agent's dialog closes; check projmux agent message status <messageRef>; do not resend
+```
+
+and exits 0. Plain sends and a Claude source's `--reply-to` behave the same.
+A send to a target that is not blocked is also held while that target still has
+an earlier held message, so a later message never overtakes an earlier one.
+Codex targets are never held. An observation older than the 30-minute
+interaction freshness window reads as `unknown` and does not block.
+
+The hold ends when the target's interaction leaves `approval_required` or
+`input_required`: `UserPromptSubmit`, `Stop`, `StopFailure`, and the events that
+follow an operator answer (`PostToolUse`, `PostToolUseFailure`,
+`PermissionDenied`, `ElicitationResult`) move it on. The last four change the
+interaction to `in_progress` only when it was blocked; otherwise they stay quiet
+and write nothing. That transition starts a detached
+`projmux internal agent-message-release --agent uid:<agent>` process, which
+holds a per-Agent lock and delivers that Agent's held messages one at a time in
+acceptance order through the ordinary push. Before each message it reads the
+Registry again: a removed Agent or a route that no longer accepts the message
+makes it `stale`, a passed deadline makes it `expired`, and a target that
+awaits its operator again is watched as below, with the rest still held behind
+that message. Every send that writes a hold also starts the same release, so a
+hold never depends on a hook arriving later.
+
+A denied permission sends no hook in current Claude Code, so the release
+watches a target that awaits its operator instead of stopping. It keeps its
+lock and reads the Registry and the tail of the Agent's own recorded
+`transcript_path` again at a fixed interval of at most 2 seconds, for at most
+10 minutes or until the earliest deadline still ahead among the held messages,
+whichever comes first. A hook that moves the interaction on lets the message go
+out on the next read. A `turn_duration` line stamped after the blocking
+observation, with no assistant `tool_use` after it, means that turn has ended
+and its dialog is gone: the release records the `response_complete` interaction
+the `Stop` hook would have written, Registry state only and only if that same
+observation is still current, and delivers at once. A missing path, an
+unreadable file or line, or any other doubt keeps the message held; when the
+window ends the message stays held as below.
+
+When the target's helper does not answer the release's route probe and the
+target is not awaiting its operator, or when the Registry cannot be read, the
+release cannot judge that message yet. It keeps its lock and judges the same
+message again after 2 seconds, doubling the wait up to 30 seconds, for at most
+10 minutes or until the earliest deadline still ahead among the held
+messages, whichever comes first. Each attempt checks the deadline and the
+blocking interaction again, a message whose deadline has passed becomes
+`expired` instead of being waited for, and later messages still wait behind
+this one. When that window ends the release stops and the message stays held;
+it becomes `expired` at its deadline unless a later release delivers it first.
+
+The TTL still applies: a held message is not extended, and one still held at
+its deadline becomes `expired` with reason `deadline-expired`.
+`agent message status <messageRef>` answers a held message from the durable
+store, never from the target's helper, which has not seen it; it prints the
+same held line, `expired` once the deadline has passed, and the delivered or
+other terminal result once the release has run.
+
+### Operator input
+
+A durable envelope can also carry operator input: text a person wrote through
+an in-process projmux operator client, which is not an Agent. It is
+represented, and every reader accepts and labels it, but no command creates
+it: only an operator client's own in-process sender can, and an audit test pins
+those senders.
+
+The client is a name value, never a list projmux keeps: 1-32 bytes of lowercase
+ASCII letters, digits, and `-`, starting with a letter (`internal/core/operatorclient`).
+Operator input is `"kind":"operator"` with a client name under that rule; a
+name outside it is not operator input and is refused as
+`operator-client-invalid` where one is built. Records an earlier build wrote
+with its fixed client name stay operator input under the same rule.
+
+- **Envelope.** Operator input carries `"origin":{"kind":"operator","client":"<client>"}`
+  and no `source` key; its authority is
+  `{"kind":"operator","trust":"untrusted","permission":"coordination-only"}`,
+  which grants none of the turn, steer, or config permissions a person at the
+  terminal has. Its target must be a Claude Agent (refused otherwise with
+  `operator-origin-target-not-claude`), and it is never a reply. An Agent
+  message has no `origin` key at all: an absent origin is the Agent origin,
+  there is no explicit `"kind":"agent"` encoding, and an Agent envelope's bytes
+  are unchanged. A mixed shape (an origin with any source field, or no origin
+  and no valid source route) is invalid. The durable envelope `version` stays
+  `2`.
+- **Replies.** Operator input has no Agent route to reverse, so a reply to it
+  is refused with `explicit-reply-operator-origin`, whether it comes from
+  `agent message send --reply-to`, the Claude reply tool, or the store.
+- **Store.** The message store's on-disk version is `3` only while at least one
+  stored record is operator input; otherwise every write is version `2`,
+  including the first write after the last operator record is reclaimed. A
+  version `1` or `2` file that contains an `origin` is malformed. A Claude
+  helper started from an older build shares the store file and refuses any
+  version but `1` and `2` and any unknown field, and an activation keeps its
+  helper across an install, so this rule keeps a store of Agent messages
+  readable by those helpers, and keeps a rollback to such a build safe until
+  operator input is written.
+- **Frame.** The operator frame's `source` is `{"kind":"operator","client":"<client>"}`
+  in place of an Agent route, `sourceNotice` is "Operator input that arrived
+  through the projmux <client> client; projmux did not verify the person."
+  with the origin's client name, and
+  `replyAction` is empty. The other keys are those of an Agent frame. The
+  helper proves only the target current, since there is no source route.
+- **Readers.** The web transcript reader shows operator input as a `user`
+  turn with `via` `projmux-web` and no `from`, judged by the `source` fields
+  alone. A frame without an origin keeps its existing reading: one whose
+  source and target are the same Agent is the operator's own `user` turn.
+  `agent message status` labels operator input `source=operator (<client>)` in a trailing text column and prints
+  an `origin` object and no `source` in JSON; an Agent message's output is
+  unchanged. A reclaimed operator record's history line carries `origin` and
+  no `source`.
+
+Why operator input needs a durable envelope at all: a Claude session has no
+path for user-turn input other than typing into its terminal, and projmux
+forbids sending keys on the Agent input path. The coordination push is the
+only channel that reaches a Claude session without keys, so operator input
+travels as an envelope and is labelled for what it is. Codex needs none of
+this: it already takes web input as a native user turn.
 
 Reply egress uses only documented official `Stop.last_assistant_message` plus
 one delivered Projmux-owned pending record at the same boundary. Push ingress
@@ -187,9 +355,9 @@ Codex Agent self-claims it.
 | Ready and idle | Immediate one-frame push; model visibility is separate evidence |
 | Active tool/turn | Push never interrupts; next official human boundary makes reply correlation ambiguous |
 | Provider exit or activation restart | Old generation writes and claims zero |
-| Same-generation registration/helper replacement | Old incarnation writes zero; fresh exact-version qualification required |
+| Same-generation registration/helper replacement | Incarnation unchanged within the same Claude session; the old helper still writes zero, enforced by the lease authority; fresh exact-version qualification still required |
 | Provider version replacement | Old qualification is cleared; unqualified writes zero |
-| Codex endpoint replacement | Old incarnation self-claim zero; exact new incarnation may claim |
+| Codex endpoint replacement | Incarnation unchanged; the old endpoint's self-claim is still zero by the exact authority check; the exact new endpoint may claim |
 
 Message state is receipt-only. It performs no Registry Agent-interaction or
 tmux badge write, so it cannot overwrite `in_progress`, approval-required, or
@@ -250,17 +418,21 @@ and [cross-session messaging](https://code.claude.com/docs/en/cross-session-mess
 Once a delivered message has unresolved reply ambiguity (an overlapping human
 turn, multiple pending messages, expiry, or an uncertain write/reply outcome),
 a later idle Stop cannot restore automatic reply correlation. The helper keeps
-push ingress available but refuses automatic replies for that incarnation.
-Use the documented public recovery on the same Agent UID and qualify its new
-activation before resuming automatic dialogue. Source and target routes are
-revalidated after durable handoff and immediately before the provider write.
+push ingress available but refuses automatic replies for the rest of its
+lifetime. Use the documented public recovery on the same Agent UID and qualify
+its new activation before resuming automatic dialogue. Source and target
+routes are revalidated after durable handoff and immediately before the
+provider write.
 
 The final source check also asks the existing Codex broker to verify the exact
 runtime, connection and binding lease. This read-only IPC observation binds
 nothing and sends no provider request. An older broker that does not support
 this observation refuses coordination; it is never restarted implicitly.
-Helper store lock contention fails immediately. Concurrent official hooks
-invalidate reply correlation without waiting for another hook to finish.
+Helper store lock contention fails a reply commit immediately, before any
+durable write. The handoff and delivery records wait up to two seconds for the
+lock first, so a brief holder cannot report a delivered message as failed.
+Concurrent official hooks invalidate reply correlation without waiting for
+another hook to finish.
 
 The live harness begins with the benign `Reply READY.` control. The later broker
 payload contains its own exact acknowledgement request; the initial user turn