projmux 0.15.2 → 0.16.0

package/docs/claude-coordination-endpoints.md

@@ -107,8 +107,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
@@ -127,6 +130,22 @@ failure before any byte is a non-ambiguous `provider-write-zero`; partial bytes,
 a write error after bytes, or a lost helper response is ambiguous and has
 `autoResend=false`. A complete write plus helper return is only a transport
 handoff, not proof that Claude parsed, displayed, processed, or answered it.
+Push content has no length cap of its own: only the 8192-byte serialized
+auth+user frame bounds it, and a size excess ends as
+`provider-frame-too-large: frameBytes=N limitBytes=8192` with zero provider
+bytes; the reply tool argv body stays at 4096 bytes.
+
+`agent message send` applies the same budget to a Claude target before
+acceptance, for plain sends and `--reply-to` alike. The sender renders the
+content with the helper's renderer, once with its own executable and once with
+the fixed executable phrase, keeps the longer frame, and counts an assumed
+48-byte auth token; it never reads a messaging token. A frame over 8192 bytes
+exits nonzero with `provider-frame-too-large: frameBytes=N limitBytes=8192`
+before any receipt is stored or the helper is called. Codex targets are not
+pre-checked. A helper started before this rule still caps push content at 4096
+bytes and fails a larger body with `provider-frame-invalid-content`; the
+sender's receipt then names the rendered content bytes and asks to re-activate
+(restart) the target Agent.
 
 The frozen frame is closed to Claude Code `2.1.263`. A different provider
 version, helper replacement, provider restart, registration replacement, or
@@ -152,10 +171,153 @@ 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
+the projmux web client, which is not an Agent. It is represented, and every
+reader accepts and labels it, but no command or web route creates it yet.
+
+- **Envelope.** Operator input carries `"origin":{"kind":"operator","client":"web"}`
+  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":"web"}`
+  in place of an Agent route, `sourceNotice` is "Operator input that arrived
+  through the projmux web client; projmux did not verify the person.", 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 (web)` 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
@@ -171,9 +333,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
@@ -212,16 +374,21 @@ independently.
 validator's verdict on preserved real frame shapes. Neither it nor L20 proves
 installed-provider compatibility, value drift (the corpus keeps top-level key
 shape with placeholder values), or acceptance of unknown frames and fields (the
-closed vocabulary rejects them by design). The L20 fixture emits none of the
-corpus's dropped side frames. Two recorded real shapes are rejected today:
+closed vocabulary rejects them by design). L20 replays every corpus item whose
+verdict is `drop` through the production reply-only validator: the Claude
+fixture reads the corpus at run time from `PROJMUX_FAKE_CLAUDE_OBSERVED_FRAMES`,
+emits each dropped side frame with its key set unchanged after init and before
+its startup result, and the scenario requires the emitted names to equal the
+corpus drop set. Those frames are key-shape placeholders, not model output. L20
+does not emit the two recorded real shapes that are rejected today:
 `result-success-25-keys` (the result allowlist lacks `origin`) and
 `system-init-allowlist-diff` (the init allowlist lacks `memory_paths` and
 `terminal_slash_commands`). Shapes without preserved evidence are gaps, not
-items: `command_lifecycle` keys and values, a non-null assistant
-`context_management`, `system` `thinking_tokens`, hook and user `tool_result`
-frames, the exact real init key set, every nested value, `rate_limit_event`
-envelope keys beyond `type` and `rate_limit_info`, and the lost earlier shape
-inventories.
+items, so neither the corpus nor L20 exercises them: `command_lifecycle` keys
+and values, a non-null assistant `context_management`, `system`
+`thinking_tokens`, hook and user `tool_result` frames, the exact real init key
+set, every nested value, `rate_limit_event` envelope keys beyond `type` and
+`rate_limit_info`, and the lost earlier shape inventories.
 
 Provider sources: [SessionStart and Stop hooks](https://code.claude.com/docs/en/hooks)
 and [cross-session messaging](https://code.claude.com/docs/en/cross-session-messaging).
@@ -229,17 +396,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