projmux 0.16.0 → 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.
@@ -272,10 +284,19 @@ 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"}`
+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
@@ -298,16 +319,17 @@ reader accepts and labels it, but no command or web route creates it yet.
   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"}`
+- **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 web client; projmux did not verify the person.", and
+  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 (web)` in a trailing text column and prints
+  `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`.