agent-embassy 1.2.0 → 1.4.0

package/docs/GATEWAY-ARCHITECTURE.md

@@ -18,16 +18,21 @@ queued turn after idle, and delivered the exact final reply back to Claude.
 ## Purpose and boundary
 
 The gateway lets already-running Claude Code sessions and explicitly
-registered native Codex tasks address one another by short aliases. Outbound
-Codex-to-Claude sends require an explicitly selected Claude route; inbound
-native Claude messages may come from any exact compatible live same-UID
-session without making that session outbound-selected. It provides a single
-private operational view across the two products without rebuilding either
-agent runtime.
+registered native Codex tasks address one another by short aliases. Both
+directions require an explicit permission edge. The broker runs in `paired`
+inbound mode by default, so an inbound native Claude message is admitted only
+from a session that already holds a pair edge to the addressed Codex task;
+`embassy serve --inbound open` is the explicit opt-out that restores any exact
+compatible live same-UID session as an inbound sender without making it
+outbound-selected. Outbound Codex-to-Claude sends likewise require the pair
+edge, created by `pair` or the one-task `select-claude` shorthand. It provides
+a single private operational view across the two products without rebuilding
+either agent runtime.
 
 Its exact Claude Code 2.1.226 runtime/peer-protocol pin is fail-closed.
-Still-running 2.1.224 sessions remain compatible during a patch upgrade
-because their registry records use the same reviewed peer protocol 1 shape.
+Still-running 2.1.224 and 2.1.225 sessions remain compatible during a patch
+upgrade because their registry records use the same reviewed peer protocol 1
+shape.
 
 It is deliberately:
 
@@ -40,8 +45,8 @@ Embassy uses one private same-user Unix-domain control socket for its thin
 clients and generates a private static dashboard page in each supported
 language. `embassy serve` does not add a TCP listener, HTTP server, or public
 API. The opt-in `embassy dashboard --live` companion is a separate foreground
-process that binds an authenticated listener with four bounded route actions
-on `127.0.0.1`; it is
+process that binds an unauthenticated stable-port listener with four bounded
+route actions on exact `127.0.0.1`; it is
 described under [Live dashboard companion](#live-dashboard-companion).
 
 ### Why this uses the new feature, but is not skill-only
@@ -129,7 +134,7 @@ probed by this project.
        │              │ callback replies
        ▼              ▼
   ┌──────────────────────── local singleton gateway ───────────────────────┐
-  │ private control UDS │ transient bodies │ metadata state │ static HTML  │
+  │ private control UDS │ retained bodies  │ metadata state │ static HTML  │
   └──────────┬──────────┴──────────────────┴────────────────┴──────────────┘
              │
              ├─ local Codex App Server ─ registered native local tasks
@@ -153,12 +158,12 @@ The status below is intentionally narrower than the target architecture.
 
 | Component | Current evidence |
 | --- | --- |
-| Neutral gateway types, metadata store, route fencing, bounded queues, dedupe, rate limits, and public projection | **Implemented**, deterministic tests; message bodies persist under bounded retention (CO #36) |
+| Neutral gateway types, metadata store, route fencing, bounded queues, dedupe, rate limits, and public projection | **Implemented**, deterministic tests; message bodies persist under bounded retention |
 | Private JSONL control protocol over a controller-owned UDS | **Implemented**, deterministic synthetic tests; no provider connection required |
 | Static metadata-only dashboard renderer and atomic publisher | **Implemented**, deterministic security tests; the static renderer requires no browser or HTTP server |
-| Opt-in live dashboard companion (`embassy dashboard --live`) | **Implemented**, deterministic tests over the loopback listener, capability-to-cookie exchange, projection, and four bounded route actions; it is a separate foreground process, never part of `embassy serve` |
+| Opt-in live dashboard companion (`embassy dashboard --live`) | **Implemented**, deterministic tests over the stable loopback listener, direct multi-browser access, projection, request guards, and four bounded route actions; it is a separate foreground process, never part of `embassy serve` |
 | Claude registry/peer adapter pinned to 2.1.226 / peer protocol 1 | **Implemented** and live-tested, including 2.1.224–2.1.226 patch-overlap discovery, print-session discovery, native status frames, cancellation, and accessible-workspace attestation |
-| Exact Claude 2.1.226 binary/runtime attestation | **Implemented**; executes only bounded `claude --version` with a scrubbed environment and derives but does not open provider roots |
+| Automatic exact Claude 2.1.226 binary/runtime validation | **Implemented**; executes only bounded `claude --version` with a scrubbed environment and derives but does not open provider roots |
 | Allowlisted Codex App Server connector with bounded busy behavior | **Implemented** and live-tested against App Server 0.147.0 for external busy observation, registered-route reachability across settings changes, and an automatically started queued turn; exact `STEER:` boundary behavior is covered deterministically |
 | Attach-only local Codex proxy transport and exact-owned cleanup | **Implemented**, five deterministic tests; no live App Server connection in routine tests |
 | Local provider adapters | **Implemented**, focused synthetic tests cover genuine-interactive Claude discovery, exact send/callback/receipt settlement and post-dispatch refresh, plus exact opted-in Codex ownership, registered-route reachability, monitor-only fallback, and cleanup; remote adapters remain disabled |
@@ -210,13 +215,13 @@ connector positively observes that exact task on the current endpoint
 generation.
 
 An App Server endpoint-generation change is a fenced route transition, not a
-new registration. Embassy stops dispatch through the old connector, creates a
-replacement connector, and runs the existing bounded compatibility probe
-against that replacement. Only a compatible result may proceed to
-`thread/loaded/list`, where every retained private thread ID must occur exactly
-once. The connector resumes that exact task with history excluded, and the
-store atomically re-anchors the same alias, owner lease, and pair edges to the
-new endpoint generation. Each successful re-anchor is recorded in a bounded
+new registration. Embassy stops dispatch through the old connector and creates
+a monitor-only replacement connector. That exact generation must pass a fresh
+automatic initialize and `thread/loaded/list` validation, where every retained
+private thread ID must occur exactly once. The connector resumes that exact
+task with history excluded; only then may the controller activate writes and
+atomically re-anchor the same alias, owner lease, and pair edges to the new
+endpoint generation. Each successful re-anchor is recorded in a bounded
 private journal; neither thread IDs nor endpoint generations enter public
 activity, diagnostics, logs, or CLI output. An incompatible endpoint, a
 missing or duplicate exact task, or an unclean transition leaves the route
@@ -269,7 +274,7 @@ The thin skill/CLI exposes the same safe alias list to either provider.
    thread identity, source alias, target Claude current name or session UUID,
    and bounded text.
 2. The gateway checks thread ownership, selector state, rate and size limits,
-   deadline, hop count, and dedupe state.
+   deadline, and dedupe state.
 3. It requires the selector to match an explicitly selected live UUID,
    refreshes the UUID's current process/socket coordinates, and revalidates
    the selected Claude peer's canonical workspace access and exact generation
@@ -278,7 +283,9 @@ The thin skill/CLI exposes the same safe alias list to either provider.
    `cross-session-message` textual frame with bounded sender attribution and a
    first-child reply hint containing the full conversation token, exact aliases,
    and reply command. It then opens a short-lived connection and writes one
-   version-pinned peer frame. A reply request carries the gateway's own
+   version-pinned peer frame immediately, regardless of whether the current
+   Claude registry observation says `idle`, `busy`, or `waiting`. A reply
+   request carries the gateway's own
    anonymous callback UDS as the transport reply address; that path is never
    exposed in the content frame.
 5. It records only normalized delivery metadata. It does not retry an
@@ -286,12 +293,13 @@ The thin skill/CLI exposes the same safe alias list to either provider.
 6. A reply received on the callback listener is correlated in memory and
    routed to the owning explicitly registered Codex task.
 
-A transport write is not proof of successful model completion. The adapter
-distinguishes transport state from any hold/release/denial receipt supported
-by the pinned protocol. `transport_written` and native `held` are adapter/native
-progress signals only, not public `delivery_status` states. The public tracker
-remains `queued` or `stalled` until a terminal state; neither signal proves
-terminal success or permits a retry.
+A Claude-bound peer socket is a native mailbox, not an idle gate. Once the
+pre-write route checks pass, Embassy attempts that mailbox write immediately;
+an observed busy state never queues the body. `transport_written` proves the
+mailbox write and is reduced to terminal `delivered` for this direction. That
+still does not prove Claude read, consumed, or acted on the body. The adapter
+distinguishes this transport boundary from Claude-to-Codex native `held`, which
+is a progress signal only. Neither boundary permits a retry.
 
 ### Claude to Codex
 
@@ -309,9 +317,13 @@ final reply.
    text as untrusted user-role input. This inbound observation grants only a
    transient, in-memory capability for the correlated reply. It does not add a
    Claude route, flip `selected`, or authorize a later unsolicited send.
-   In paired mode, a sender without the exact permission edge is refused before
-   message admission with `SENDER_NOT_PAIRED`; because no message was accepted,
-   that refusal is not added to the delivery journal.
+   In paired mode — the default — a sender without the exact permission edge is
+   refused before message admission with `SENDER_NOT_PAIRED`. No message is
+   accepted, so no delivery is created, but the refusal is not silent: the
+   broker records it as a `rejected` journal event carrying the direction, both
+   aliases, the byte count, and the safe error code, and increments the
+   rejected counters on the accounting, the source route, and any matching
+   pair.
 3. The Claude process's inherited messaging-socket value may be accepted as a
    transient reply address after strict validation. Claude Code exports
    `CLAUDE_CODE_MESSAGING_SOCKET` as a raw absolute socket path; the CLI
@@ -337,12 +349,15 @@ final reply.
    emit Claude's approval-specific native `held` control frame for ordinary
    queueing.
 8. In `merged` and `verbose` notice modes, if the delivery remains pending for
-   exactly `floor(messageDeadlineMs / 2)`, the gateway may send the
-   originating Claude session at most one nonterminal
+   exactly `min(floor(messageDeadlineMs / 2), 120_000)` milliseconds, the
+   gateway may send the originating Claude session at most one nonterminal
    `<gateway-delivery-stall>` user frame for that receipt. It contains only an
    allowlisted reason and a bounded `queued-for-ms` age; it is not a native
-   `held` receipt and does not settle the delivery. `quiet` suppresses this
-   gateway-authored frame without changing native status or dashboard state.
+   `held` receipt and does not settle the delivery. The two-minute ceiling is
+   deliberate: stall visibility must not scale with the deadline, so under the
+   default four-hour deadline the notice fires at two minutes, not two hours.
+   `quiet` suppresses this gateway-authored frame without changing native status
+   or dashboard state.
 9. When the task becomes idle, the connector refreshes the exact task state and
    starts the held message. A route retains at most three queued steering
    messages; accepting a fourth atomically cancels the oldest with safe code
@@ -387,19 +402,24 @@ terminally settles accepted work, joins its bounded receipt writes, and only
 then closes provider adapters. This orders `GATEWAY_SHUTDOWN` receipts ahead of
 listener teardown instead of silently dropping late admitted work.
 
-Claude's native peer socket is itself an inbox, so Codex replies may be
-written while the Claude route is busy. The gateway still serializes its own
-writes, but it does not wait for Claude to become idle and thereby deadlock a
-Claude turn that is waiting for the reply.
+Claude's native peer socket is itself a mailbox, so every Claude-bound body,
+including a correlated Codex reply, is written regardless of Claude's observed
+busy or idle state. The gateway still serializes its own writes, but it never
+waits for Claude to become idle and thereby deadlocks a Claude turn that is
+waiting for the reply. This does not change the opposite direction: ordinary
+Codex-bound bodies remain idle-gated, and exact leading `STEER:` bodies keep the
+next-tool-call-boundary rules above.
 
 ### Provenance framing and conversation continuation
 
 The broker classifies `STEER:`, `TRACK:`, and `DONE:`, enforces raw-byte body
-limits, deduplicates, accounts hops, and queues before presentation framing.
-The store therefore retains only the raw transient body. A pure composer runs
-at the final semantic provider-write boundary so a clean retry produces the
-same bytes with exactly one authoritative outer wrapper. Compatibility probes,
-receipt frames, and diagnostics do not use this path.
+limits, deduplicates, and queues before presentation framing.
+The store therefore retains only the raw unframed body, never the composed
+envelope. A pure composer runs at the final semantic provider-write boundary so
+a clean retry produces the same bytes with exactly one authoritative outer
+wrapper. Automatic provider
+startup and endpoint-generation validation, receipt frames, and diagnostics do
+not use this path.
 
 Both provider directions use Claude-compatible textual framing with a
 broker-owned `cross-session-message` outer element and an
@@ -416,17 +436,17 @@ broker-owned `cross-session-message` outer element and an
 - In either direction, the first hint carries the full token in `conversation`
   and the exact recipient alias in `reply-as`, followed by an exact stdin-based
   `embassy reply --conversation ... --alias ...` instruction and the statement
-  that route and hop policy are rechecked.
+  that caller, conversation, and route policy are rechecked.
 
-Embassy does not synthesize `from`, `from-session`, `hop-chain`, or `from-mode`
-attributes: those names have provider-native meanings the broker cannot
-truthfully claim. Native socket addresses, Codex thread IDs, Claude session
-UUIDs, endpoint generations, and route handles never enter the content frame.
+Embassy does not synthesize `from`, `from-session`, or `from-mode` attributes:
+those names have provider-native meanings the broker cannot truthfully claim.
+Native socket addresses, Codex thread IDs, Claude session UUIDs, endpoint
+generations, and route handles never enter the content frame.
 
 The outer structure and hint come only from validated broker metadata. Before
 composition, the untrusted body case-insensitively neutralizes boundary-shaped
-opening or closing occurrences of `cross-session-message` and
-`embassy-reply-hint` by inserting `\` immediately after the leading `<`.
+opening or closing occurrences of Embassy's reserved framing tags by inserting
+`\` immediately after the leading `<`.
 Everything else remains raw text. This is not general XML, cryptographic
 authentication, or proof that the message content is trustworthy; it is a
 consistent structural provenance marker at the model input boundary. A native
@@ -435,8 +455,8 @@ beneath the Embassy wrapper.
 
 The full token delivered in the hint lets the recipient call `reply`, but it is
 only a participant-scoped conversation locator. The service still validates
-the inherited caller, current conversation membership, current route policy,
-and hop count. The full token remains confined to the accepted control result
+the inherited caller, current conversation membership, and current route
+policy. The full token remains confined to the accepted control result
 and transient provider payload, and is memory-only: it is never persisted,
 journaled, logged, snapshotted, rendered on a dashboard, placed in a receipt,
 or returned from suffix-only public correlation. Formatter,
@@ -505,16 +525,22 @@ never displaced to admit a new send. A pressure-evicted handle returns
 
 ### Replies and process restarts
 
-Conversation IDs correlate replies, but callback addresses and message bodies
-exist only in memory. After a gateway restart, previously queued or in-flight
-metadata is marked abandoned; bodies are not recoverable and are never
-replayed. The prior Claude binding remains stored but stale. After authorized
-live discovery, one exact UUID-bound selection may be reactivated under its
-latest name. No queued text, pending reply, callback, native receipt handle,
-delivery token/status tracker, or conversation capability survives the
-restart; a prior token therefore returns `found: false`. A stale or offline
-selection can be explicitly removed by its stored alias or a user-supplied UUID
-without requiring discovery first.
+Conversation IDs correlate replies, and callback addresses exist only in
+memory, but queued message bodies are durable. After a gateway restart, each
+queued message is triaged: one already past its deadline settles `expired`; one
+whose target authority was transient, or whose target route is gone, settles
+`abandoned` with `CONTROLLER_RESTARTED`; every other queued body is restored and
+re-armed for dispatch, then sent exactly once after its exact route is
+re-observed. A message in flight at the moment of the restart or crash settles
+`ambiguous` with `CONTROLLER_RESTARTED` and is never replayed.
+
+The prior Claude binding remains stored but stale. After authorized live
+discovery, one exact UUID-bound selection may be reactivated under its latest
+name. No pending reply, callback, native receipt handle, delivery token/status
+tracker, or conversation capability survives the restart; a prior token
+therefore returns `found: false`. A stale or offline selection can be explicitly
+removed by its stored alias or a user-supplied UUID without requiring discovery
+first.
 
 ## Gateway control plane
 
@@ -523,33 +549,41 @@ controller-owned mode-0700 state directory. The socket and state files are
 mode 0600. Frames are size-bounded and closed against unknown keys, methods,
 versions, and enum values.
 
-The small version 1 method family covers:
+The closed version 1 method family is exactly these sixteen methods:
 
-- health and a safe public snapshot;
-- a read-only `observe_snapshot` projection, which may settle already-due
-  lifecycle deliveries before projecting and is the only method the live
-  dashboard companion calls;
-- explicit Codex registration, succession, and unregister;
-- explicit Claude selection and unselection from the current sanitized
+- `health` and `list_snapshot`, a safe public snapshot;
+- `observe_snapshot`, a read-only projection that may settle already-due
+  lifecycle deliveries before projecting;
+- `register_codex`, `unregister_codex`, and
+  `remove_stale_codex_registration` — explicit Codex registration and
+  succession, unregister, and broker-guarded removal of a stale orphan whose
+  owning endpoint generation is dead;
+- `select_claude` and `unselect_claude`, from the current sanitized
   available-peer inventory;
-- delivery-status lookup by an opaque, memory-only correlation handle;
-- provider-specific send operations;
-- a correlated reply operation; and
-- dashboard refresh.
-
-The installed binary is `embassy` (`claude-codex-gateway` is a one-release
-deprecated alias). Its implemented commands are
-`serve`, `health`, `status`, `delivery-status`, `wait-delivery`,
+- `pair` and `unpair`, the two-endpoint permission edge;
+- `delivery_status`, a lookup by opaque, memory-only correlation handle;
+- `untrack`, which closes one active progress watch by conversation token;
+- `send_to_claude` and `send_to_codex`, the provider-specific sends;
+- `reply`, the correlated reply operation; and
+- `refresh_dashboard`, which refreshes Claude discovery and republishes.
+
+The live dashboard companion calls `observe_snapshot` for every read; its
+mutation route additionally calls `pair`, `unpair`,
+`remove_stale_codex_registration`, and `refresh_dashboard`, and nothing else.
+
+The installed binary is `embassy`, and it is the only installed binary. Its
+seventeen implemented commands are
+`serve`, `health`, `status`, `delivery-status`, `wait-delivery`, `untrack`,
 `refresh-dashboard`, `dashboard`, `register-codex`, `unregister-codex`,
-`select-claude`, `unselect-claude`, `send-to-claude`, `send-to-codex`, and
-`reply`. `dashboard` requires `--live` and accepts an optional
-`--lang en|zh-CN`; it starts the companion process rather than issuing a single
-control request. Message bodies are non-empty UTF-8 from standard input only,
-with a 16 KiB ceiling; they are never accepted in an argument or file. The
-client emits one bounded normalized JSON line and never returns a thread ID,
-provider-native ID, path, address, or message body. These commands require the
-foreground broker, except that `serve` starts it in the current terminal. It
-never daemonizes itself.
+`select-claude`, `unselect-claude`, `pair`, `unpair`, `send-to-claude`,
+`send-to-codex`, and `reply`. `dashboard` requires `--live` and accepts an
+optional `--lang en|zh-CN` and `--port <n>`; it starts the companion process
+rather than issuing a single control request. Message bodies are non-empty
+UTF-8 from standard input only, with a 16 KiB ceiling; they are never accepted
+in an argument or file. The client emits one bounded normalized JSON line and
+never returns a thread ID, provider-native ID, path, address, or message body.
+These commands require the foreground broker, except that `serve` starts it in
+the current terminal. It never daemonizes itself.
 
 `select-claude --alias <current-name@host>` and
 `select-claude --session <uuid>` select the same logical session.
@@ -562,9 +596,19 @@ Codex registration, unregister, and Codex-to-Claude send require only a valid
 `CODEX_THREAD_ID`; they fail if a non-empty Claude messaging socket is also
 inherited. Claude-to-Codex send requires only the raw inherited Claude socket
 path and fails if a non-empty Codex thread ID is also present. `reply` likewise
-fails with both identities or neither. The operator-only health, status,
-dashboard refresh, live dashboard, select, unselect, and serve commands ignore
-provider identities.
+fails with both identities or neither. `pair` and `unpair` also require an
+exclusive inherited `CODEX_THREAD_ID`: naming both endpoints does not make them
+operator commands, and they fail `CODEX_IDENTITY_REQUIRED` from a plain terminal
+or `CALLER_IDENTITY_CONFLICT` from inside a Claude session.
+
+`select-claude` and `unselect-claude` are the operator-runnable shorthand.
+They do not ignore provider identity — they consume an inherited
+`CODEX_THREAD_ID` when one is present, to resolve the Codex end, and reject a
+malformed one — but they tolerate its absence and then resolve the Codex end
+from the sole registered task. Selection is not a weaker operation than
+`pair`: it atomically creates the same permission edge. The health, status,
+dashboard refresh, live dashboard, untrack, and serve commands are the ones
+that genuinely ignore provider identities.
 
 The foreground command is:
 
@@ -572,21 +616,27 @@ The foreground command is:
 embassy serve
 ```
 
-Before provider attestation, listener creation, or App Server attachment, the
+`--inbound open` is the one security-relevant option:
+
+```text
+embassy serve --inbound open
+```
+
+The default is `paired`. `open` is the explicit opt-out that lets any exact
+compatible live same-UID Claude session send inbound without a pair edge; it is
+never implied and cannot be set through an environment variable.
+
+Before provider validation, listener creation, or App Server attachment, the
 launcher acquires one fixed host-wide crash-reclaimable owner lease under the
 verified login home. The lease is independent of `EMBASSY_STATE_DIR`, so two foreground
 controllers cannot be started for the same login account by choosing different
-state roots. During the one-release prototype transition, a recognized exact
-legacy default root is also controller-locked while Embassy runs. Any
-pre-existing legacy lock blocks startup as `GATEWAY_INSTANCE_IN_USE` and is
-preserved; the operator may remove that exact stale lock only after confirming
-no prototype process remains. Missing, unsafe, or unrecognized legacy roots
-are not created, imported, or mutated.
+state roots. It is the only instance lock Embassy takes: the pre-rename
+prototype state root is no longer read, locked, or mutated.
 
 It emits one normalized ready line, publishes the private dashboard, and
 holds the process until `SIGINT` or `SIGTERM`, when exact-owned resources are
-closed. Startup attests the pinned local Claude and Codex runtimes and binds
-controller-owned UDS listeners, but does not discover a Claude peer, write a
+closed. Startup automatically validates the exact-pinned local Claude and Codex
+runtimes and binds controller-owned UDS listeners, but does not discover a Claude peer, write a
 provider socket, start a model turn, or contact a remote host. Its ready result
 reports local host `this-mac`, dashboard filename `gateway-dashboard.html`, and
 `codexMode: "native_messaging"` without exposing paths.
@@ -599,6 +649,27 @@ Same-UID socket access is a local containment boundary, not proof of a trusted
 agent process. Every mutation additionally checks route ownership, exact
 thread/session generation, source alias, bounds, and conversation state.
 
+### Progress watches
+
+`send-to-claude`, `send-to-codex`, and `reply` each accept an opt-in `--track`
+flag that opens one progress watch over the resulting conversation, plus an
+optional `--idle-minutes <n>` that sets how long the watched thread may sit idle
+before the watch reports a stall. `n` is an integer from 1 through 1440 and
+defaults to 5; supplying it without `--track` is an argument error. A body with
+an exact leading `TRACK:` prefix opens the same watch at the default idle window
+without the flag.
+
+`untrack --conversation conv_<token>` closes an active watch explicitly, and a
+body with an exact leading `DONE:` prefix closes it as completed; one message
+may not both open and complete a watch (`PROGRESS_WATCH_SIGNAL_CONFLICT`). The
+global `EMBASSY_TRACKING_ENABLED` switch is on by default and exact `0` disables
+the surface; `EMBASSY_MAX_WATCHES` bounds concurrent watches at 32 by default
+(hard cap 256).
+
+A watch is independent evidence about thread activity, not delivery evidence. It
+may outlive an opener whose own delivery expired, so check the opener's
+`delivery-status` separately before assuming the assignment text arrived.
+
 ## Codex connectors and remote hosts
 
 In the target multi-host design, each allowlisted execution host has a separate
@@ -636,11 +707,12 @@ Missing, malformed, or nonempty turns fail closed and are never emitted or
 persisted. The capability does not add an experimental client method or change
 the closed RPC allowlist.
 
-Monitor compatibility and write compatibility are distinct gates. A connector
-may initialize, list, resume, and expose normalized monitor state after its
-schema compatibility is attested while still reporting its write gate as
-unavailable. No Claude-initiated turn can start until exact write compatibility
-and explicit route ownership are established.
+Automatic generation validation and controller write activation are distinct
+gates. A replacement connector may initialize, list, resume, and expose
+normalized monitor state after its exact version and required schemas validate
+while still reporting its write gate as unavailable. No Claude-initiated turn
+can start until the controller activates that exact endpoint generation and
+explicit route ownership is established.
 
 Registration resumes the exact task and establishes reachability. Embassy does
 not read or retain reported working-directory or policy fields. Before
@@ -720,8 +792,9 @@ The one Desktop restart needed for the local shared-App-Server feasibility
 test has already been completed. Building, running synthetic tests, starting
 the gateway, rendering the dashboard, and a future Claude peer-socket test do
 not themselves require another Desktop restart. A provider or Desktop upgrade
-may require a new compatibility probe and, if its attachment mode changes, a
-separately announced controlled restart.
+outside this release's exact pins requires an updated, reviewed Embassy
+adapter and, if its attachment mode changes, a separately announced controlled
+restart.
 
 ## Dashboard
 
@@ -738,50 +811,62 @@ A static page is a point-in-time snapshot and never refreshes itself: it emits
 no meta refresh and the page tells the operator to re-run
 `embassy refresh-dashboard` and reload, or to use `embassy dashboard --live`.
 
-It shows only:
-
-- aggregate gateway and per-host connector health;
-- available/selected Claude aliases, registered Codex aliases, provider, host,
-  compatibility, state, and queue depth;
-- normalized message direction and delivery state, timestamp, latency, byte
-  count, hop count, and a short opaque message-ID suffix; and
-- allowlisted alerts such as stale route, protocol mismatch, queue full, or
-  ambiguous delivery.
+Each page assembles seven sections:
+
+- **Exchange** — aggregate gateway health plus the pair graph: every explicit
+  Claude↔Codex edge and its per-edge counters.
+- **Attention** — allowlisted alerts such as stale route, protocol mismatch,
+  queue full, or ambiguous delivery.
+- **Transit** — queued-message depth and bytes in flight.
+- **Progress supervision** — active progress watches and their state.
+- **Operator activity** — the broker's bounded public journal of accepted
+  operator actions.
+- **Sessions** — available/selected Claude aliases, registered Codex aliases,
+  provider, host, compatibility, state, and queue depth.
+- **Diagnostics** — compatibility attestations per provider, per-host connector
+  health and protocol, deadline-pressure buckets, accounting totals, and the
+  omission counters below. Normalized message direction and delivery state,
+  timestamp, latency, byte count, and a short opaque message-ID suffix appear
+  with the delivery rows.
 
 It never shows message content, prompts, replies, transcripts, titles, working
 directories, native IDs, PIDs, socket paths, endpoint paths, tool data, raw
-events, stderr, credentials, or configuration contents. This is a
-controller-owned UI artifact, not a shared task file. The public snapshot has
-a 240 KiB projection budget and reports explicit omission counters if bounded
-connector, peer, route, message, or alert rows are truncated.
+events, stderr, credentials, or configuration contents — retained bodies reach
+only the live companion, never these files. This is a controller-owned UI
+artifact, not a shared task file. The public snapshot has a 240 KiB projection
+budget and reports explicit omission counters whenever bounded rows are
+truncated: connectors, available peers, routes, pairs, progress watches,
+upstream and projected progress-watch events, upstream message events, message
+groups, message events, upstream alerts, attention items, and upstream and
+projected activity events.
 
 ### Live dashboard companion
 
-`embassy dashboard --live` is the opt-in browser view of the same projection.
+`embassy dashboard --live` is the opt-in browser view of broker state,
+including bounded retained bodies in delivery detail; the static dashboard's
+public projection remains metadata-only.
 It is a separate foreground process, not a mode of `embassy serve`: it holds no
 provider capability, owns no registry record, and reaches the broker over the
 same private control socket every other client command uses, so it reports the
 gateway as unavailable when nothing is serving.
 
-- **Bind.** One `http.createServer` listener on `127.0.0.1` with an ephemeral
-  port, under a random per-run instance path. No other interface is bound and
-  no port is fixed or advertised.
-- **Bootstrap.** Startup mints one 256-bit (32-byte) capability, base64url
-  encoded, carried only in the URL fragment. The bootstrap URL is written to a
-  mode-0600 `bootstrap.html` inside a fresh mode-0700 `live-<random>` run
-  directory under the private state root, opened `wx` and identity-checked, and
-  both file and directory are removed when the companion exits.
-- **Exchange.** The capability is single-use. It is exchanged once for a
-  path-scoped `HttpOnly` `SameSite=Strict` session cookie; the fragment never
-  reaches the server as part of a request line.
+- **Bind.** One `http.createServer` listener binds exact `127.0.0.1` on stable
+  port `41961` by default, or the integer from the per-invocation `--port <n>`
+  option in the closed range 1024 through 65535. The direct root URL is
+  `http://127.0.0.1:<port>/`. A collision fails with
+  `LIVE_DASHBOARD_PORT_IN_USE` and directs the operator to `--port`; there is no
+  ephemeral-port fallback. No other interface is bound.
+- **Access.** The root URL is usable concurrently from multiple windows, tabs,
+  and browsers. There is no capability token, URL fragment, cookie, browser
+  session, random instance path, or bootstrap file.
 - **Request checks.** The exact Host header is validated on every request.
-  Navigation GETs may omit Origin and carry no sentinel; non-navigation POSTs
-  require the exact Origin plus `X-Embassy-Request`. There are no CORS headers,
-  no cross-origin reads, and no routes outside the instance path.
+  Navigation GETs may omit Origin; every POST requires the exact Origin plus
+  `X-Embassy-Request: 1`. `OPTIONS` is not accepted, there are no CORS headers,
+  and cross-origin reads are unavailable.
 - **Projection and actions.** The companion observes through
   `observe_snapshot`. Its only mutations are exact two-endpoint `pair`,
   `unpair`, `refresh_dashboard`, and `remove_stale_codex_registration`
-  control calls behind one closed authenticated `/action` route. The recovery
+  control calls behind one closed `/action` route. The recovery
   action carries only a canonical public `codex-*` alias and is accepted only
   after the broker revalidates that the route is stale and its endpoint
   generation is dead; native task and generation IDs never enter the browser
@@ -796,9 +881,11 @@ gateway as unavailable when nothing is serving.
   fresh observation. An observation may
   settle already-due lifecycle deliveries before projecting, which is a broker
   timer effect, not additional browser authority.
-- **Containment.** Authentication scopes the browser, not the machine. Any
-  process running as the same OS user — including root and browser extensions
-  with local filesystem access — can read what the browser can read.
+- **Containment.** The loopback server deliberately performs no local-process
+  or UID authentication. It assumes a trusted single-user machine: any local
+  software that can reach or spoof loopback can read the live view and invoke
+  the bounded actions. Host, Origin, and sentinel checks constrain ambient
+  browser-origin requests; they do not authenticate local software.
 
 `--lang en|zh-CN` selects the companion's display language. It has no effect on
 the static pair, which is always written in both languages.
@@ -814,9 +901,12 @@ The private store may retain:
   accounting and dashboard projection;
 - timestamps, counters, dedupe/rate-limit records, and safe error codes.
 
-It must never retain message bodies, provider output, prompts, replies, tool
-input/output, raw App Server or Claude frames, stderr, histories, credentials,
-Claude registry payloads, or callback/socket paths. The public snapshot is a
+It also retains message bodies under bounded caps — the queued body of every
+undelivered message and the recent delivery ledger's retained bodies, evicted
+oldest-first against a 1 MiB budget by default. It must never retain provider
+output, tool input/output, raw App Server or Claude frames, stderr, histories,
+credentials, Claude registry payloads, or callback/socket paths. The public
+snapshot is a
 strict projection that also removes private route handles and endpoint
 generations. The state directory is mode 0700 and binding state is mode 0600;
 provider-native identifiers never enter normalized events, public snapshots,
@@ -825,14 +915,15 @@ every restored route begins stale and unusable. An authorized discovery may
 reactivate only the byte-identical durable Claude UUID after the current
 provider endpoint, workspace, complete unique discovery, and ownership lease
 all revalidate. The public `selected` bit flips only after that atomic private
-rebind succeeds. No queued body, callback, receipt handle, conversation, or
-reply capability is restored, and no delivery token or status tracker is
-reconstructed.
+rebind succeeds. Queued bodies are restored and re-armed for dispatch; no
+callback, receipt handle, conversation, or reply capability is restored, and no
+delivery token or status tracker is reconstructed.
 
 The delivery-token mapping, queryable status tracker, native receipt handle,
 and one-stall-notice state are always memory-only. Durable delivery metadata
-does not contain enough information to reconstruct any of those capabilities
-or replay a body after restart.
+does not contain enough information to reconstruct any of those capabilities.
+A restored body is re-sent exactly once and only into its own exact
+re-observed route; it is never replayed into a reconstructed capability.
 
 ## Minimum filesystem and process access
 
@@ -858,20 +949,20 @@ and fake App Server transports.
 
 ### Exact default roots on macOS
 
-The runtime attestation code derives these paths from the current OS user's
+The automatic exact-version validator derives these paths from the current OS user's
 verified home; it does not scan the home directory. These are the reviewed
 boundaries exercised by the live gateway; routine tests substitute synthetic
 paths, peers, and transports:
 
 | Path/capability | Minimum purpose |
 | --- | --- |
-| `~/.local/bin/claude` and derived expected target `~/.local/share/claude/versions/2.1.226` | Stat the owned launcher/path components and read/execute only the resolved pinned target for bounded `--version`; live launcher attestation succeeded |
+| `~/.local/bin/claude` (or the absolute `EMBASSY_CLAUDE_BIN` override) and derived expected target `~/.local/share/claude/versions/2.1.226` | Stat the owned launcher/path components and read/execute only the resolved pinned target for bounded `--version`; `PATH` and interactive shell profiles are never searched; live launcher validation succeeded |
 | `~/.claude/sessions` | Read/enumerate only live registry JSON during the separately authorized passive-discovery gate |
 | `/tmp/cc-socks` | At foreground startup, validate the private directory and create/remove only `/tmp/cc-socks/<gateway-pid>.sock` after inode/generation checks; search/stat genuine peers at passive discovery and connect one validated target only at the separately authorized send gate |
 | `~/.local/state/agent-embassy/.agent-embassy-state` | Validate or establish the exact ownership marker before creating the fixed host lease; an existing non-empty unmarked root is rejected without mutation |
 | `/usr/bin/lockf` and `/bin/cat` | Hold one fixed, non-waiting macOS advisory lease for the foreground controller; the helper receives no shell text, provider data, or model-supplied argument |
+| `/usr/bin/open` | Executed only by the opt-in `embassy dashboard --live` companion, to open the loopback dashboard URL in the operator's browser; no shell, a scrubbed fixed environment, and a bounded timeout and output cap |
 | `~/.local/state/agent-embassy/.gateway-host.lock` | Fixed per-login kernel-held lease acquired before provider setup; it remains here even when `EMBASSY_STATE_DIR` is overridden. Its bounded PID/token record is exact-cleanup metadata, not a path-only stale-lock authority; a crash releases the kernel lock and the next foreground process may acquire the existing file |
-| `~/.local/state/claude-agent-bridge/gateway/.claude-codex-gateway-state` and `.gateway-controller.lock` | For one release, bounded-read the exact legacy ownership marker and lock record; create and hold the lock only when absent, preserve any pre-existing lock, and read no other legacy state or message data |
 | `~/.local/state/agent-embassy` (or explicit `EMBASSY_STATE_DIR`) | Default controller-owned store, control UDS, state lock, and static dashboard; an explicit absolute configuration may replace only these state surfaces |
 | `~/.codex/packages/standalone` and `~/.codex/app-server-control/app-server-control.sock` | Resolve the pinned managed Codex binary and attach to the already-running private local App Server; never bootstrap or unlink it |
 
@@ -922,9 +1013,14 @@ the preferred least-context setup, but it is not mandatory.
   fail-closed. Only exact retry is permitted until the old route is confirmed
   unregistered and the controller is restarted.
 - No ambiguous mutation is retried automatically.
-- No queued body survives process loss.
-- Version-specific compatibility evidence expires on a provider or Desktop
-  update.
+- A queued body survives process loss under bounded retention and is re-sent
+  exactly once after its exact route is re-observed. A message in flight when
+  the process was lost settles `ambiguous` with `CONTROLLER_RESTARTED`; a
+  message whose target authority was transient, or whose target route no longer
+  exists, settles `abandoned` with the same code.
+- A provider or Desktop update outside the release's exact reviewed pins fails
+  closed; retained state never admits an unreviewed version or activates an
+  unvalidated replacement endpoint generation.
 
 ## Validation boundary