projmux 0.14.2 → 0.15.0

package/docs/architecture.md

@@ -313,29 +313,42 @@ Identity and naming:
 - `metadata.uid` is opaque, immutable, and independent of tmux lifecycle. It
   survives snapshot/restore, runtime creation, and root rebind.
 - `metadata.name` is the stable unique-within-scope query key. Project names
-  are unique across the registry; Window, Pane, and Agent names are unique
-  within their `ownerRef` scope.
-- `metadata.displayName` may duplicate and is never a selector, an ownerRef, or
-  identity. `metadata.labels` is key/value classification;
-  `metadata.annotations` is non-identifying metadata such as an AI topic.
-- Name bases are assigned once, at create or migration time, and are never
-  re-derived. A declared Window create uses explicit name → initial command
-  basename → configured shell basename → `window`; a Window newly imported
-  from tmux always uses the literal `window` allocator base. Its observed
-  `window_name`, Pane label, provider, command, shell, topic, and title are all
-  excluded from stable identity. Shell Pane uses command basename → shell
-  basename → `pane`; a Pane managed by an Agent uses `<agent-name>-pane`; Agent
-  uses explicit `--name` → normalized provider id → `agent`.
-- For a Window, the observed tmux `window_name` is
-  `metadata.displayName`: duplicate-allowed, visible in `describe window`, and
-  never a selector, ownerRef, or identity input. Existing Window uids, names,
-  owners, and name reservations are preserved; there is no bulk naming
-  migration.
-- Automatic collisions take the lowest free suffix (`Projmux-1`, `codex-1`)
-  from the persisted `nameReservations` table, scanning integer suffixes rather
-  than resource or map iteration order. An **explicit** `--name` or rename
-  collision never receives an implicit suffix: it fails with exit code 2 and
-  zero mutations.
+  and ControlSession names are unique within their own root kind across the
+  registry. Window, Pane, and Agent names are unique by
+  `(rootOwnerUID, kind, name)`, where the root is the Project or ControlSession
+  reached through the direct `ownerRef` chain. Different roots and different
+  kinds may use the same spelling.
+- Automatic creation mints the opaque UID first and stores that exact full UID,
+  including its kind prefix and complete payload, as `metadata.name`. If that
+  name slot is already occupied, the unpublished UID is discarded and reminted
+  up to 100 times. There is no semantic stem, prefix truncation, sibling scan,
+  or numeric suffix allocator. An explicit `--name` keeps its original spelling
+  after validation; explicit create and rename collisions fail with exit code 2
+  and zero Registry, tmux, or provider writes.
+- `create agent` supplies an **explicit** name for the Pane its Agent owns:
+  `<agent-name>-pane`, derived from the Agent's own name. That used to be a
+  documented follow-up `rename pane` a launcher had to remember, so a caller
+  that did not know the convention left the managed Pane addressed by a raw
+  UID. It is not a new automatic-name rule -- it goes through the same explicit
+  name path an operator's `--name` does, so a Pane with no Agent still gets its
+  exact full UID. Length is the only fallback: an Agent name may be the full 128
+  bytes, and `<agent-name>-pane` would then be 133 and invalid, so the Pane
+  falls back to automatic naming rather than refusing a create that works today.
+  A *collision* on the derived name never falls back; it is the same typed exit
+  2 with zero writes an explicit `--name` collision produces, because the whole
+  metadata phase runs before the first tmux or provider call.
+- The derivation runs once, at create, and is deliberately not an invariant.
+  `rename agent` does not follow the Pane and `rename pane` is neither forbidden
+  nor restricted, so the Pane name keeps exactly one owner and `rename agent`
+  keeps its `cardinality=exact-one` effect tuple. A launcher that still issues
+  the old follow-up `rename pane <agent-name>-pane` gets a successful no-op,
+  because a reservation slot the same uid already holds is not a conflict.
+- Schema v4 stores no `metadata.displayName`, `status.displayTitle`, or renamed
+  presentation replacement. Human context is projected for one invocation from
+  the Project root, topic/provider/command, and exact live tmux title. That
+  context may duplicate and is never a selector, reservation, ownerRef, or
+  durable identity input. `metadata.labels` remains key/value classification;
+  `metadata.annotations` remains non-identifying metadata such as an AI topic.
 
 Root lifecycle:
 
@@ -656,10 +669,9 @@ Registry file and schema:
   bounded retry and stale-lock breaking, matching the notify queue and
   recent-windows stores. Explicit Registry repair uses its own recovery lock;
   see the recovery boundary below.
-- The envelope carries `schemaVersion: 3`. Version 1 is the first Registry
-  envelope projmux wrote; this build migrates v1 through v2 and then performs
-  the lossless v2 → v3 envelope advance that admits Project-stop
-  `interrupted/control-action` evidence.
+- The envelope carries `schemaVersion: 4`. Version 1 is the first Registry
+  envelope projmux wrote; this build migrates v1 through v2 and v3 before the
+  v3 → v4 root-scoped naming and presentation-field cutover.
 - Everything else fails closed: the file is refused as unreadable and **no
   write happens at all** — no rewrite, no backup, no staged temp file. This
   covers a **newer** schemaVersion (which would destroy state a newer build
@@ -673,9 +685,9 @@ Registry file and schema:
   registry yet" case **only before the first successful write**; see the durable
   envelope below. Only a file with actual content and no usable `schemaVersion`
   is refused as unknown.
-- A normal locked `Load` of v1 or v2 runs the production migration chain,
+- A normal locked `Load` of v1, v2, or v3 runs the production migration chain,
   validates the repaired graph, writes the versioned backup, and publishes the
-  v3 bytes through the existing temp-file atomic replace. A failed migration
+  v4 bytes through the existing temp-file atomic replace. A failed migration
   leaves the source bytes unchanged. Every successful first migrator (`Load`,
   `Update`, `UpdateConvergent`, or explicit `Migrate`) also atomically publishes
   a 0600 `<exact-backup>.migration-report.json` beside the versioned backup
@@ -685,11 +697,21 @@ Registry file and schema:
   A failed migration removes any staged/published report before returning while
   leaving the source bytes unchanged. `LoadWithMigrationResult` and `Migrate`
   additionally return both exact paths from the same locked transaction. A
-  second pass sees v3 and writes neither Registry, backup, nor report bytes. An
-  existing invalid v3 document is validated and refused byte-identically even
+  second pass sees v4 and writes neither Registry, backup, nor report bytes. An
+  existing invalid v4 document is validated and refused byte-identically even
   when explicit `Migrate` has no version step to run.
   Explicit read-only inspection migrates only its returned in-memory view and
   never publishes it.
+- The v3 → v4 step validates the UID/direct-owner graph, rebuilds reservations
+  from that graph, and changes descendant scope to the owning Project or
+  ControlSession. Every member of a root-wide same-kind duplicate group moves
+  to its exact UID name. If one of those destinations is held by a resource
+  outside the set, the holder is added until destination closure reaches a
+  fixed point; every unique name outside that closure is preserved. The sorted
+  name mapping and content-free receipts for removed `metadata.displayName` and
+  `status.displayTitle` keys are recorded beside the exact-byte v3 backup. A
+  present empty key records zero bytes and SHA-256 of empty content without
+  being counted as information loss.
 - The v1 repair is deterministic over Registry order apart from injected opaque
   uid generation. It preserves every existing uid, ownerRef, reserved name, and
   Agent conversation/session pointer. A valid Project anchor is never
@@ -717,8 +739,8 @@ Registry file and schema:
   Mixed legacy/final authority is refused; the final writer emits no
   `primaryPaneRef`; and a second final-v2 pass writes zero bytes.
 - **Field spelling:** the registry file intentionally uses the resource-model
-  camelCase spelling (`apiVersion`, `schemaVersion`, `metadata`, `displayName`,
-  `ownerRef`, `anchorPaneRef`, `defaultShellPaneRef`, `spec`, `status`) rather than the snake_case
+  camelCase spelling (`apiVersion`, `schemaVersion`, `metadata`, `ownerRef`,
+  `anchorPaneRef`, `defaultShellPaneRef`, `spec`, `status`) rather than the snake_case
   used by the older projmux on-disk JSON. The two spellings coexist on purpose:
   existing snake_case files are **not** retro-changed, and the resource registry
   follows the resource-model contract.
@@ -831,11 +853,14 @@ Registry recovery boundary (`projmux reconcile registry`):
   `ownerRef`, or a broken name reservation are all refused. Restoring an
   unverified source would replace a known-damaged registry with an
   unknown-damaged one, and the second state is worse because it looks healthy.
-- **Byte-semantic restore.** The verified bytes are published verbatim rather than
-  re-encoded, so uids, owner relations, and name reservations are preserved
-  exactly, a repeat restore is a byte comparison instead of a normalization
-  argument, and an older-but-known schema stays readable through the existing safe
-  read and migrates on the next semantic write.
+- **Byte-semantic current restore and canonical v3 import.** A verified v4
+  source is published verbatim. A verified v3 source is never made live in its
+  legacy form: its exact bytes are first written to a versioned backup, a
+  checksum-bearing content-free migration report is published beside that
+  backup, and the same deterministic v3 → v4 migration used by normal Registry
+  loading supplies the staged live bytes. Repeat restore compares the live
+  Registry with that canonical publish checksum, so it writes no new Registry,
+  backup, or report bytes.
 - **The bytes being replaced are kept.** A restore copies the current registry to
   `recovery/replaced-<stamp>-<seq>.json` before replacing it, and unlike the
   write-side copy it keeps content that does **not** verify — that damaged
@@ -974,15 +999,15 @@ tmux transport mirror:
 - `rename pane` changes `Pane.metadata.name` and its `@projmux_pane_label`
   mirror only. It never writes the raw tmux `pane_title`.
 - `rename window` is the explicit stable-identity path: it changes only
-  `Window.metadata.name`, its scoped name reservation, and the exact live
-  `@projmux_window_name` transport mirror. It does not
-  change `metadata.displayName` or tmux `window_name`.
+  `Window.metadata.name`, its root-scoped same-kind name reservation, and the
+  exact live `@projmux_window_name` transport mirror. It does not change tmux
+  `window_name`.
 - `rename project` likewise writes only `Project.metadata.name` and the exact
   live session's `@projmux_project_name`; it never renames the tmux session.
   `rebind project` preserves the Project uid and session name while updating
   `spec.root` and the exact live session's `@projmux_project_path`. Neither
   operation moves files.
-- `rename agent` changes only the Window-scoped Agent `metadata.name` and its
+- `rename agent` changes only the root-scoped Agent `metadata.name` and its
   reservation. Agent topic annotations, provider, lifecycle status, and the
   managed Pane's name and raw title are independent and receive no tmux write.
 - Rename/rebind commits the authoritative Registry transaction before its
@@ -997,24 +1022,23 @@ tmux transport mirror:
   UID claim is nonzero and reports that Registry state committed plus
   `projmux reconcile resources` as the retry boundary.
 - The configured `window.rename` action (`Ctrl-M` by default) is the runtime
-  display path and invokes tmux `rename-window` directly. Reconciliation
-  observes that `window_name` back into `metadata.displayName` without changing
-  stable identity.
+  display path and invokes tmux `rename-window` directly. Reads may observe that
+  exact live `window_name` as invocation-scoped context; reconciliation never
+  persists it as a Registry address or presentation field.
 - Registry-managed Windows are set to `automatic-rename off` so a focused-Pane
   change cannot overwrite the Window name. The **global** `automatic-rename on`
   plus visible-pane-label `automatic-rename-format` default in the generated
   app config is unchanged, so unmanaged windows keep their existing behavior.
-- Legacy import gives every newly discovered Window the literal `window` base,
-  uniquified in Project scope (`window`, `window-1`, ...), and projects its
-  current `window_name` into duplicate-allowed `metadata.displayName` before
-  switching it to `automatic-rename off`. Re-observing an existing Window may
-  refresh only that display field; it never changes the uid, stable name,
-  ownerRef, or name reservation. An existing `@projmux_pane_label` remains the
-  migration seed and transport mirror for the Pane **name**; Pane naming is a
-  separate contract and is unchanged here.
-- `Pane.metadata.name` is the primary pane display source. The derived
-  `Pane.status.displayTitle` (Agent topic → known shell → raw pane title) is
-  secondary and is never a selector, an identity, or a Window name source.
+- Legacy import gives every newly discovered Window, Pane, and Agent its exact
+  minted UID as the automatic Registry name and switches managed Windows to
+  `automatic-rename off`. Observed `window_name`, Pane label/title, command,
+  shell, provider, and topic are never persisted as an address or presentation
+  field. Re-observing an existing resource preserves its UID, stable name,
+  ownerRef, and reservation. `@projmux_window_name` and
+  `@projmux_pane_label` remain live mirrors of the durable name.
+- `Pane.metadata.name` is the stable Pane address. Human-readable Pane context
+  is derived per invocation from the owner Agent topic/provider, command, and
+  exact live title; it is never a selector, identity, or Window name source.
 
 Runtime observation and resource status:
 
@@ -1154,13 +1178,12 @@ Binding reapply and adoption:
   and neither does a **refused** pane — a refusal means a real registry Pane sits
   on the other side of the ambiguity, so minting beside it would leave two Panes
   describing one tmux pane.
-- The registered Pane is named from `FallbackPaneNameBase` (`pane`, `pane-1`, …)
-  through the registry's own allocator, never from `pane_current_command`:
-  `metadata.name` is not derived from a runtime attribute, and the command
-  changes the moment the operator runs something else. The runtime reading goes
-  to `status.displayTitle` instead. The mint itself never creates an Agent: it
-  adds one Pane and stops. Linking that Pane to an Agent is the separate step
-  below, which runs on the Pane the walk just settled on.
+- The registered Pane uses its exact minted UID as `metadata.name`, never
+  `pane_current_command`, the Pane label/title, or a numeric suffix. Those
+  runtime values may contribute only to invocation-scoped context. The mint
+  itself never creates an Agent: it adds one Pane and stops. Linking that Pane
+  to an Agent is the separate step below, which runs on the Pane the walk just
+  settled on.
 - **Nothing is ever re-identified.** Adoption changes no uid, merges no uid, and
   reassigns no uid; it only decides which registry object a live tmux object is
   the runtime of, and then writes that object's existing uid. Adopted objects
@@ -1673,7 +1696,8 @@ Explicit Registry topology materialization:
   desired Windows remain Agent-anchored and acquire a shell only through the
   ordinary materializer. Source snapshot bytes and unrelated roots are never
   rewritten, and a second projection is byte-stable.
-- `Open fresh` replaces the exact same-root Project graph in one Registry
+- `Recreate Project` replaces the exact same-root Project graph, after an
+  explicit confirmation, in one Registry
   commit. It always allocates a new Project UID plus one new canonical Window
   and direct shell UID, whether the old Project retained Windows or had zero.
   The preimage remains the durable recovery state when the replacement commit
@@ -1849,11 +1873,12 @@ Resource-first create:
   through the same `@projmux_window_uid` mirror and registry `ownerRef` chain
   the read verbs use.
 - **Window and anchor follow the whole scope, not the Project flag.** They are
-  derived only when the argv named no `--project`, `--window`, `--pane`, and no
-  `--selector` at all. That keeps a bare `create pane --placement right` -- the
-  generated keybinding body -- a split of the Window the operator is looking at,
-  instead of a fan-out over every Window of the Project, while one explicit
-  occurrence still fixes the whole target set. An explicit `--pane` or popup
+  derived only when the argv named no `--project`, `--window`, `--pane`,
+  `--selector`, `--all-windows`, and no `--primary-window` at all. That keeps a
+  bare `create pane --placement right` -- the generated keybinding body -- a
+  split of the Window the operator is looking at, rather than of the Project's
+  primary Window, which is what the same route resolves once a `--project` scope
+  is typed, while one explicit occurrence still fixes the whole target set. An explicit `--pane` or popup
   origin is the exact split anchor. Only a scope with no Pane consumes the
   target Window's role-agnostic `spec.anchorPaneRef`; a missing, stale, dead, or
   cross-Window ref refuses with no alternate-live-Pane inference.
@@ -1880,7 +1905,7 @@ Resource-first create:
 Selector and the implicit active target:
 
 - A selector value is either `uid:<uid>` or a `metadata.name`. There is no
-  bare-uid form; `displayName`, `spec.root`, and tmux `%N`/`@N`/`$N` handles are
+  bare-uid form; ephemeral context, `spec.root`, and tmux `%N`/`@N`/`$N` handles are
   structurally unmatchable. `--project` is at-most-once and fixes the scope,
   `--window`/`--pane` repeat and union, `--selector key=value` repeats and ANDs,
   and how many targets a `<verb, kind>` pair accepts comes from one declared

package/docs/claude-coordination-endpoints.md

@@ -0,0 +1,254 @@
+# Claude coordination endpoint registration
+
+Phase 1 binds a Claude-created endpoint to a managed Agent activation. It does
+not implement message delivery, a provider message schema, a message/wait parser,
+or a new public provider command. `agent capabilities` reports the exact Agent's
+`runtimeEligibility.coordination` readiness and evidence. Static provider queries
+remain static, and existing action cells stay unchanged.
+
+`AgentRouteRef` shares stable Agent UID, Pane UID, and activation generation.
+Its sealed provider authority union consumes the existing Codex thread and
+`CodexAuthorityRef` composite unchanged. Claude authority instead consists of the
+actual public SessionStart session ID, kernel process birth identity, a fresh
+registration generation, and the kernel identity of the helper retaining its
+registration lease. No Claude connection/binding epochs are synthesized.
+
+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 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
+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.
+
+The hook obtains the socket and credential solely from Claude's documented
+`CLAUDE_CODE_MESSAGING_SOCKET` and `CLAUDE_CODE_MESSAGING_TOKEN` environment.
+These values pass to the helper over an anonymous pipe and remain in process
+memory. They are absent from Registry, helper argv, helper environment, public
+capabilities, diagnostic messages, and the content-free cleanup receipt.
+Projmux does not predict, issue, read a vendor registration file for, connect
+to, or write to the Claude inbox.
+
+Readiness validates exact Registry ownership/generation, provider and helper
+kernel birth identity, socket type/owner/mode and unchanged inode. The read-only
+capability query probes only a short, private Projmux readiness socket and
+authenticates its kernel peer PID and birth. Linux birth identity includes boot
+ID and start ticks; Darwin uses kernel process start time. The private socket
+path fits both supported Unix socket limits and does not depend on TMPDIR.
+
+The helper invalidates on provider exit, socket replacement, or loss of exact
+Registry authority. The supervisor independently detects helper death while
+the provider remains alive, clears only that exact lease, and removes orphaned
+helper files. Provider exit keeps the existing lock-free termination journal
+boundary; it never waits for the cleanup watcher's Registry transaction.
+Provider sockets are never removed by Projmux. Generation replacement and
+termination convergence discard old registration observations.
+
+The required deterministic process integration is
+`test/integration/claude-endpoint-binding.sh`. It is included in
+`make test-integration`. The opt-in `TestClaudeEndpointInstalledSourceGate`
+requires `PMX_TEST_CLAUDE_ENDPOINT_BIN`, `PMX_TEST_REAL_CLAUDE_BIN`, and a prepared
+disposable authenticated `PMX_TEST_REAL_CLAUDE_CONFIG_DIR`. The harness creates
+its own provider config with an authentication symlink; it never reads or copies
+the caller's credentials. Its one-shot uses
+strict empty MCP, empty tools, empty setting sources, and no session persistence;
+it checks public init tools/MCP/plugins and tool-use are all zero. Raw public
+stream and messaging credentials stay in memory; only allowlisted receipts
+are reported. The token scan covers all owned files, including provider source
+state. Upstream may store its own public locator; the test observes only a
+boolean and removes the entire owned provider config before reporting cleanup.
+Projmux Registry, helper files, diagnostics, and evidence contain neither value.
+Inbound cross-session messaging is explicitly refused during the one-shot.
+This is historical Phase 1 registration-source evidence only. It does not
+establish or relax Phase 4 qualification: safe mode disables hooks and cannot
+substitute for the separately owned, long-lived, hook-enabled current-version
+public-init and marker gate.
+
+The live canary accepts only paired, zero-output lifecycle events for its two
+owned SessionStart callbacks before init, correlated by exact session, hook ID,
+name, and event. It strips the empty output fields before storing evidence.
+Unobserved hook names, Setup, plugin installation, unknown fields/events,
+nonzero output, and incomplete pairs fail closed before any peer push. This
+startup ordering follows the [public stream contract](https://code.claude.com/docs/en/headless#read-session-metadata)
+and [hook lifecycle schemas](https://code.claude.com/docs/en/agent-sdk/typescript#sdkhookstartedmessage).
+The observed 2.1.263 public init also carries `capabilities` (protocol feature
+identifiers), `fast_mode_disabled_reason` (`sdk_opt_in_required`), and boolean
+`analytics_disabled` / `product_feedback_disabled` metadata. These fields are
+validated by type and known shape; none grants tool, plugin, or messaging
+authority. The owned wrapper sets the documented
+[`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1`](https://code.claude.com/docs/en/data-usage)
+opt-out. A feedback metadata boolean is not a record of external traffic.
+The observed `system/thinking_tokens` event carries only numeric progress
+estimates. The collector accepts its exact public shape after init for the same
+session, validates finite nonnegative numbers, and gives it no reply or tool
+authority. It does not carry or collect thinking text.
+Public assistant `request_id` and timestamp are validated metadata, never reply
+selectors. The observed `context_management`, `diagnostics`, and `stop_details`
+fields are accepted only as null. A public Messages API thinking block is
+validated in memory, then replaced by an omitted-content marker before disk;
+neither reasoning text nor signature is retained or sent to the provider. Only
+text blocks can provide semantic reply evidence; tool and unknown blocks fail
+closed. See the public [Messages schema](https://platform.claude.com/docs/en/api/http/beta/messages/create)
+and [ThinkingBlock schema](https://platform.claude.com/docs/en/api/typescript/messages).
+
+## Phase 4 push ingress and heterogeneous dialogue
+
+The registration helper owns the existing private `coord-*` Unix socket for
+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.
+
+Claude ingress is immediate push. There is no receiver waiter, pending ingress
+queue, `asyncRewake`, `begin-handoff`, or `no-waiter` state. The helper retains
+the opaque `CLAUDE_CODE_MESSAGING_SOCKET` and token only from the original
+anonymous bootstrap pipe, removes both keys from its environment, validates the
+unchanged 0600 provider socket and exact provider peer process, then performs
+one write containing the documented auth line followed by the single frozen
+current-version user frame:
+
+```json
+{"type":"user","message":{"role":"user","content":"..."}}
+```
+
+No control, status, reply, or inferred vendor frame is implemented. A known
+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.
+
+The frozen frame is closed to Claude Code `2.1.263`. A different provider
+version, helper replacement, provider restart, registration replacement, or
+activation restart inherits no qualification. An ordinary send cannot qualify
+the endpoint. The dedicated opt-in command requires a private 0600 sanitized
+collector record bound to the same public init session/process/Pane/generation
+and helper route, exact version, empty tools/MCP/plugins, zero pre-marker tool
+use/stderr, frozen stream, and inbound policy `accept`:
+
+```sh
+projmux agent message qualify uid:<claude-agent> \
+  --evidence /absolute/owned/private-init.json \
+  --confirm-isolated-provider-push -o json
+```
+
+The helper pushes a unique non-secret qualification marker. Only the exact
+ordinary official `Stop.last_assistant_message` at the unchanged safe-boundary
+epoch opens helper-memory eligibility. A missing/mismatched/recursive Stop,
+`UserPromptSubmit`, timeout, target exit, or post-write uncertainty closes the
+attempt as ambiguous/no-auto-resend. Late Stop cannot reopen it; retry requires
+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.
+
+Reply egress uses only documented official `Stop.last_assistant_message` plus
+one delivered Projmux-owned pending record at the same boundary. Push ingress
+correlates only an ordinary Stop (`stop_hook_active=false`); recursive Stop,
+`UserPromptSubmit`, multiple candidates, or authority drift fails closed.
+Assistant wording is never a selector. The reply reverses the routes, preserves
+`conversationRef`, sets `replyTo`, and completes only when the original exact
+Codex Agent self-claims it.
+
+| Receiver state or transition | Product result |
+| --- | --- |
+| Before readiness or qualification | Refused/failed terminal, held count zero, provider writes zero |
+| 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 |
+| Provider version replacement | Old qualification is cleared; unqualified writes zero |
+| Codex endpoint replacement | Old incarnation self-claim zero; exact new incarnation 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
+their badges. Public terminal states remain terminal-once.
+
+Explicit integration installs the SessionStart registration hook, one short
+synchronous Stop reply hook, and one short synchronous UserPromptSubmit boundary
+hook. It installs no long-lived ingress waiter and does not use `asyncRewake`.
+Capability reads never modify settings. Preview, enable, and remove only the
+owned hook entries:
+
+```sh
+projmux agent integrate claude --dry-run
+projmux agent integrate claude
+projmux agent integrate claude --remove
+```
+
+For a pre-install Running Claude whose activation has no registration, install
+the hooks, let that process exit normally, then run
+`projmux agent resume uid:<same-agent-uid>`. Resume preserves the same Agent UID
+and creates no replacement Agent. Delivery remains zero until the resumed
+process has a current registration and fresh exact-version qualification.
+`agent capabilities uid:<agent> -o json` reports source registration readiness
+separately from target `runtimeEligibility.coordination` and includes the exact
+recovery action and non-secret route incarnation.
+
+The only selectorless required E2E is offline scenario `L20`. It uses one
+synthetic auth+frozen-frame fixture, official-hook-shaped Stop input, semantic
+barriers, exact structured receipts, and no model or installed provider. The
+real-provider observation is opt-in through
+[`heterogeneous-dialogue-canary.md`](heterogeneous-dialogue-canary.md) and
+`scripts/agent-dialogue-live-canary.sh`; each version-stress row must qualify
+independently.
+
+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).
+
+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.
+
+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.
+
+The live harness begins with the benign `Reply READY.` control. The later broker
+payload contains its own exact acknowledgement request; the initial user turn
+does not authorize hypothetical future messages. Qualification keeps the same
+frozen user frame and its existing one-shot marker. Observed rate/result metadata
+is validated by closed shape and reduced before persistence. A refusal, API
+error, queued user turn, permission denial, or nonzero subagent activity closes
+the pre-inbound gate. Neither rate status nor timing/cost metadata is authority.
+
+Usage is validated and discarded before persistence. Server tool counters must
+be zero and tool/subagent iterations empty. After the semantic reply, the harness
+requires three successful results in the same session, the public assistant
+reply marker, and empty provider/collector stderr through owned cleanup.
+
+Public model IDs and usage labels are bounded strings, including provider aliases
+and context suffixes. They are discarded without imposing identifier syntax or
+using pricing metadata as a permission or correlation source.
+
+Failed live-canary cleanup captures exact Linux process births before unregister
+and tmux teardown, including pane supervisors, their descendants, and the
+detached registration helper. Supervisors write termination/operation receipts
+after their provider exits. Both success and failure cleanup wait for captured
+pidfds to report exit before removing the owned root. An unproven or stubborn
+writer leaves the root for diagnosis and fails cleanup; no quiet-file interval
+or process-name kill substitutes for exit proof. The owned credential copy is
+removed even when cleanup cannot complete. The actual reply-origin qualification
+blocker is unchanged by this cleanup guarantee.