agent-embassy 1.9.5 → 3.0.0

package/docs/GATEWAY-ARCHITECTURE.md

@@ -1,40 +1,34 @@
 # Embassy Gateway Architecture
 
-Status: local bidirectional routing is implemented for Claude, Codex, DeepSeek,
-Grok, and universal shell peers. Configured Embassy nodes federate allowlisted
-named routes over a fixed attach-only SSH transport. The published package
-supports macOS, the only platform exercised end to end so far.
+Local bidirectional routing between Claude Code sessions, Codex CLI tasks,
+and universal shell peers, with optional federation of named routes between
+the operator's own machines over a fixed attach-only SSH transport. The
+published package supports macOS, the only platform exercised end to end.
 
-This document uses four evidence labels:
+This document uses three evidence labels:
 
 - **Official**: documented by Anthropic or OpenAI.
-- **Implemented**: present in this worktree and covered by deterministic tests.
-- **Observed**: established by a bounded, read-only local feasibility probe.
-- **Planned**: designed but not yet integrated or live-validated.
-
-A bounded real test completed native Claude discovery and messaging, held a
-message while the registered Codex task was active, automatically started the
-queued turn after idle, and delivered the exact final reply back to Claude.
+- **Implemented**: present in this tree and covered by deterministic tests.
+- **Observed**: established by a bounded, read-only local probe.
 
 ## Purpose and boundary
 
 The gateway lets already-running Claude Code sessions and explicitly
-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
+registered native Codex tasks address one another by short aliases. The
+permission to message is the boundary the broker already sits inside: the same
+UID, the same host — or a host the operator listed in the private `nodes.json`
+— and an exact alias. There is no separate, revocable grant between two
+endpoints, because no such record could defend against software already
+running as that UID; what the broker guarantees instead is attribution, and a
+discovered Claude session's route installs on its first use rather than by a
+separate command. It provides
 a single private operational view across the two products without rebuilding
 either agent runtime.
 
 Provider versions are best-effort diagnostic metadata, never routing authority.
-An explicit pair plus the exact owned route and session identity authorizes an
+The OS boundary plus the exact owned route and session identity authorizes an
 attempt; the current per-operation transport, strict wire, capability, and
-correlated operation facts decide its result. The release-owned offline support matrix is
-the tested-artifact record and is never imported by runtime. Unsafe OS evidence
+correlated operation facts decide its result. Unsafe OS evidence
 for Embassy-owned or executed artifacts and Embassy callback, control, or state
 paths refuses broker startup; unsafe UID or mode evidence on Claude's external
 sessions registry root quarantines only Claude. A Claude session record whose
@@ -50,12 +44,8 @@ It is deliberately:
 - unable to create Codex sidebar task cards or Claude session UI.
 
 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 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).
+clients. `embassy serve` does not add a TCP listener, HTTP server, or public
+API.
 
 ### Why this uses the new feature, but is not skill-only
 
@@ -67,9 +57,9 @@ Claude–Codex address book the user wants.
 
 The repo-shipped skill is the lightweight user/agent interface. A persistent
 local broker is still required to own the private control socket, retain
-transient reply correlation, publish native advertisements, queue while a Codex
-task is busy, and regenerate the dashboard between agent turns. The skill does
-not wrap, replace, or recreate either provider.
+transient reply correlation, publish native advertisements, and queue while a
+Codex task is busy. The skill does not wrap, replace, or recreate either
+provider.
 
 ## What is official and what is internal
 
@@ -105,11 +95,12 @@ Consequences:
   explicitly marked `codex-*` gateway peer.
 - The gateway discovers compatible real Claude sessions as transient
   candidates, but publishes only sanitized aliases and state. A send from a
-  registered Codex task may address only an explicitly selected route by its
-  current name or UUID. Per-message consent stays native: delivery lands in the
+  registered Codex task addresses a session by its current name or its UUID,
+  and the broker installs that session's logical route on this first use.
+  Per-message consent stays native: delivery lands in the
   Claude session's own `crossSessionInbound` policy and approval flow.
-- Codex aliases are discovered through the gateway CLI/skill and dashboard,
-  not through `ListAgents`.
+- Codex aliases are discovered through the gateway CLI/skill, not through
+  `ListAgents`.
 - A gateway-owned anonymous callback UDS can receive a correlated reply. It
   does not need, and must not create, a Claude registry record.
 
@@ -122,20 +113,6 @@ turn start, turn steer, turn interrupt, and notifications. Embassy exposes
 `turn/steer` only behind the exact Claude-to-Codex `STEER:` contract described
 below; there is no generic RPC surface.
 
-**Official:** for an SSH project, the ChatGPT desktop app starts the remote
-Codex App Server through SSH using the remote user's login shell. Files,
-commands, credentials, permissions, plugins, skills, and local tools come from
-that execution host. App Server transports should not be exposed directly on
-a shared or public network.
-
-**Observed:** this Desktop build connects to a host-local App Server on each
-execution host. Remote tasks on `build-mac` do not route through the local App
-Server. Desktop reaches the remote listener through an SSH `app-server proxy`.
-A second attach-only client successfully initialized against the already-owned
-`build-mac` listener and called only `thread/loaded/list` without creating a turn.
-The same topology is expected for `lab-mac.example`, but that host has not been
-probed by this project.
-
 ## Topology
 
 ```text
@@ -146,14 +123,12 @@ probed by this project.
        │              │ callback replies
        ▼              ▼
   ┌──────────────────────── local singleton gateway ───────────────────────┐
-  │ private control UDS │ retained bodies  │ metadata state │ static HTML  │
-  └──────────┬──────────┴──────────────────┴────────────────┴──────────────┘
+  │ private control UDS │ retained bodies  │ metadata state │ public snapshot │
+  └──────────┬──────────┴──────────────────┴────────────────┴─────────────────┘
              │
              ├─ local Codex App Server ─ registered native local tasks
              │
-             ├─ planned attach-only SSH proxy ─ build-mac App Server
-             │
-             └─ planned attach-only SSH proxy ─ lab-mac.example App Server
+             └─ optional federation ─ ssh <node> embassy peer-stdio ─ peer broker
 
   Claude-side skill/CLI ─ private control UDS ─ gateway
   Codex-side skill/CLI  ─ private control UDS ─ gateway
@@ -166,32 +141,28 @@ wake a different idle runtime after that turn ends.
 
 ## Component status
 
-The status below is intentionally narrower than the target architecture.
+Everything below is exercised by the deterministic suite; live validation is
+a separately authorized operator action (see [Validation boundary](#validation-boundary)).
 
 | Component | Current evidence |
 | --- | --- |
-| Neutral gateway types, native-v3 metadata store, bounded attempt state machine, queues, dedupe, rate limits, and public projection | **Implemented**, deterministic tests; message bodies persist under bounded retention |
+| Neutral gateway types, schema-5 metadata store, bounded attempt state machine, 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 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 with strict peer protocol 1 and per-operation validation | **Implemented** and live-tested through Claude Code 2.1.227, including discovery, native status frames, cancellation, and accessible-workspace validation |
+| Claude registry/peer adapter with strict peer protocol 1 and per-operation validation | **Implemented**; deterministic tests cover discovery, native status frames, cancellation, and accessible-workspace validation |
 | Claude current-user runtime roots | **Implemented**; derives the registry and callback roots from the verified OS user without inspecting a launcher or configuration file |
 | Stateless allowlisted Codex App Server transport with bounded busy behavior | **Implemented**; every operation opens and attests its own transport, and the conformance suite covers idle gating, exact `STEER:` behavior, clean retry, and ambiguous no-replay settlement |
 | 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 and Embassy-node federation | **Implemented**, focused synthetic tests cover Claude discovery, exact Codex ownership, lazy ACP-backed DeepSeek and Grok routes with provider-local degradation and cleanup, plus bounded catalog reconciliation and destination-owned handoff over the fixed attach-only SSH transport |
+| Local provider adapters and Embassy-node federation | **Implemented**, focused synthetic tests cover Claude discovery, exact Codex ownership, plus bounded catalog reconciliation and destination-owned handoff over the fixed attach-only SSH transport |
 | Universal shell peer mailbox | **Implemented**, alias-plus-token same-UID attribution, hash-only durable ownership, bounded long polling, stdout-flush receipts, and restart uncertainty tests; no PID binding, token file, Keychain entry, or daemon |
-| Gateway service composition | **Implemented**, including private control-server startup, synthetic cross-provider selection/dispatch/reply correlation, metadata-only publication, and restart attempt-phase tests |
-| Delivery receipt/status lifecycle | **Implemented**, deterministic synthetic tests cover stable-UUID native receipt re-resolution, the merged/verbose/quiet Claude notice policy, one bounded stall notice with pending age where enabled, opaque private-v3 correlation handles, restart continuity, the closed status/terminal schema, and one-shot/bounded-wait CLI behavior |
+| Gateway service composition | **Implemented**, including private control-server startup, synthetic cross-provider route installation/dispatch/reply correlation, bounded public-snapshot projection, and restart attempt-phase tests |
+| Delivery receipt/status lifecycle | **Implemented**, deterministic synthetic tests cover stable-UUID native receipt re-resolution, the merged/verbose/quiet Claude notice policy, one bounded stall notice with pending age where enabled, opaque private-v5 correlation handles, restart continuity, the closed status/terminal schema, and one-shot/bounded-wait CLI behavior |
 | Broker-owned cross-provider provenance framing | **Implemented**, deterministic tests cover exact Codex and Claude wire shapes, bounded long-alias attribution, recipient reply hints, reserved-tag neutralization, single wrapping across clean retries, and pre-write failure |
 | Operator/agent client CLI and package binary | **Implemented**, deterministic private-UDS tests cover the closed command family, inherited provider identity, bounded stdin-only bodies, normalized output, and ambiguous no-retry behavior |
 | Repo-shipped cross-provider skill | **Implemented** as a repo-scoped workflow over the client CLI; it is not installed into either provider's global configuration |
 | Foreground local broker launcher and provider assembly | **Implemented** as `embassy serve`; local-host-only with native messaging enabled |
-| Live Codex-to-Claude delivery | **Tested** through selected real Claude 2.1.224–2.1.226 sessions |
-| Claude-initiated Codex turn/reply into Codex | **Tested** with a real busy Codex task: native `busy → waiting`, automatic post-idle turn, terminal delivery status, and exact reply round trip |
-| Remote production connector | **Planned**; only the `build-mac` read-only attach feasibility probe is complete |
 
 Synthetic tests do not scan `~/.claude`, connect `/tmp/cc-socks`, attach to a
-Desktop App Server, invoke SSH, or make a model request.
+live App Server, invoke SSH, or make a model request.
 
 ## Identity, discovery, and opt-in
 
@@ -209,7 +180,7 @@ claude-advisor@this-mac
 Claude's native `sessionId` UUID is its sole logical identity. Its current
 name is a mutable lookup alias for that UUID; the gateway keeps no historical
 name index. A rename therefore makes the old name stop resolving immediately,
-while the UUID and an already selected UUID-bound route continue to identify
+while the UUID and an already installed UUID-bound route continue to identify
 the same session. PID, registry path, process generation, and socket generation
 are replaceable delivery coordinates, not identity, and are refreshed from the
 live registry before a write. The gateway rejects duplicate current names and
@@ -225,18 +196,11 @@ Codex registration is explicit. A task registers its own alias and
 authoritative `CODEX_THREAD_ID`; the gateway does not enumerate global Codex
 history to invent routes. Registration performs no provider I/O. Each delivery
 opens a fresh attested App Server transport, initializes it, resumes the exact
-private task with history excluded, and authorizes one body write. Endpoint or
-Desktop restart is therefore a transport fact, not a logical route transition;
+private task with history excluded, and authorizes one body write. An App
+Server restart is therefore a transport fact, not a logical route transition;
 an unavailable or duplicate exact task fails that operation with a safe code
 without retargeting the alias or replaying an ambiguous write.
 
-The live dashboard exposes the bounded `remove_codex_registration` operation.
-It carries only one public canonical `codex-*` alias and requires explicit
-operator confirmation of the consequences. In one fencing commit the broker
-cancels queued or reserved work, settles armed work ambiguous and accepted work
-unconfirmed, removes that registration and its incident consent edges, and
-never replays uncertain work. The browser cannot name a thread ID.
-
 Claude discovery is passive and limited to currently advertised genuine
 Claude session records. Only a validated native record bearing the supported
 explicit versioned Embassy-advertisement marker is classified as a gateway
@@ -262,20 +226,73 @@ correlation, accessibility, liveness, and generation checks above without an
 invented additional owner or mode rule. A current name resolves to a UUID but
 never substitutes for it.
 
-A selected Claude UUID remains the durable route identity until explicit
-unselection. Discovery publishes only bounded sanitized candidates and current
-lookup aliases; it never changes the selected UUID. Immediately before a
+An installed Claude route keeps its UUID as durable identity until a
+different session claims its alias and displaces it; there is no operator
+command that retires one.
+Discovery publishes only bounded sanitized candidates and current
+lookup aliases; it never changes the installed UUID. Immediately before a
 Claude-bound write, Embassy performs a fresh bounded registry scan, resolves
 that byte-identical UUID exactly once, and revalidates its current workspace,
 process, socket, and used-artifact generation. An incomplete scan, duplicate
-name or UUID, changed UUID, or unsafe current coordinate fails that operation
-closed. A name alone never restores or retargets a durable selection.
-
-The dashboard is the single pane for the human. It shows both sanitized
-available/selected Claude aliases and explicitly registered Codex aliases,
-including their host, current state, last-seen age, and queue depth.
+UUID, changed UUID, or unsafe current coordinate fails that operation closed.
+A duplicate display name is fenced from listing and from every send that
+addresses it BY NAME, and the fence is re-evaluated inside the
+send path, never only on the discovery timer. The fence is a fence on names:
+a session UUID is unambiguous, so an operator-supplied UUID remains the
+recovery selector and reaches the session even while its name collides, and a
+sender whose own display name collides is never silenced, because its identity
+was attested rather than typed. A pre-bound route retains its identity-pinned
+binding, and a name alone never restores or retargets a durable route.
+
+`embassy status` is the single pane for the human, and it is read-only: it
+makes exactly one call, `list_snapshot`, and never `refresh_discovery`, so the
+scan it reports is the broker's own and a status loop cannot journal anything.
+Its `sessions` block is the sanitized `availablePeers` inventory — every live
+Claude session the last scan found, by current name, marked `routed` once a
+route exists for it — and its header says how old that scan is, offering
+`embassy refresh` when it is older than a minute — that age is read from the
+newest discovered session's own stamp, because the connector's `lastSeenAt`
+also moves on a delivery. Below the sessions come the
+routes: routed Claude aliases and explicitly registered Codex aliases, with
+provider, current state, queue depth, and last-seen age. The same
+pane also carries the bounded ledger's retained message bodies, so its output
+is as sensitive as the messages themselves.
 The thin skill/CLI exposes the same safe alias list to either provider.
 
+That pane has two forms of the same snapshot. Piped, or with `--json`, it is
+the snapshot verbatim — the form every script and the skill read. On a
+terminal it is rendered by `status-view.ts`, a pure function of the snapshot
+and the reader's clock: it derives one of four plain words per connector
+(`ok`, `stale`, `degraded`, `offline`) and pairs every word that is not `ok`
+with its safe code and a one-line remedy. Two clocks govern staleness, and
+they are deliberately far apart. The broker's own connector window is 35
+seconds (`CONNECTOR_OBSERVATION_STALE_AFTER_MS`), and it is crossed routinely
+and innocently — the Codex observer polls one route at a time every 15
+seconds, and Claude routes are not polled at all: their evidence is
+edge-triggered, written when a discovery scan or a delivery observes the
+session, so a quiet Claude session's `lastSeenAt` stops advancing while the
+session is perfectly alive. The view therefore keeps the broker's word until
+a route has gone unobserved for ten minutes, and only then calls it `stale`;
+past that backstop a Codex route earns the succession remedy only when it
+also carries a code that says the task itself is gone (`THREAD_NOT_OBSERVED`)
+— bare silence says the task may be busy or the app-server slow. A Claude
+route whose alias the latest scan still lists is never `stale`: the scan is
+fresher evidence than the route's own observation, so the discovered state is
+shown with `discovered <age>` as its last-seen cell, and a Claude route past
+the backstop that the scan no longer lists says the session exited or renamed.
+A connector that merely has nothing to observe is `stale`, never `degraded`,
+and a shell peer with unclaimed mail never moves the overall word at all:
+silence in a pull mailbox is a fact about the operator's other terminal.
+`embassy watch` tails the same snapshot through `observe_snapshot` once a
+second, printing each new message row and each settlement at most once — a
+transition passed through entirely between two polls is never seen, and rows
+evicted from the retained window before the tail read them are announced as
+a note. `embassy check` proves the whole path end to end — it registers an
+ephemeral `peer-*` principal of its own, sends one marked body through the
+ordinary send path, waits for `delivered`, then awaits the correlated reply on
+its own mailbox, and releases the registration again; the broker retires the
+registration itself if the check never gets to.
+
 ## Message flows
 
 ### Codex to Claude
@@ -285,10 +302,10 @@ The thin skill/CLI exposes the same safe alias list to either provider.
    and bounded text.
 2. The gateway checks thread ownership, selector state, rate and size limits,
    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
-   before every send.
+3. It resolves the selector against a discovery scan run inside this send,
+   installing the session's route if this is its first use, then refreshes the
+   UUID's current process/socket coordinates and revalidates that Claude
+   peer's canonical workspace access and exact generation before every send.
 4. Immediately before the native write, it composes one broker-owned canonical
    `cross-session-message` textual frame with bounded sender attribution and a
    first-child reply hint containing the full conversation token, exact aliases,
@@ -325,15 +342,12 @@ final reply.
 2. A real Claude session uses native `ListAgents` and `SendMessage`; the
    gateway validates that exact live registry/socket generation and treats the
    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 — 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.
+   transient, in-memory capability for the correlated reply. The sending
+   session's own route is installed here, from the exact identity the adapter
+   attested, so the Codex task's reply travels the ordinary path; the alias the
+   adapter reports must be the one discovery shows for that UUID, and a
+   mismatch is refused rather than silently renamed. Installing the route
+   authorizes nothing beyond what addressing already implied.
 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
@@ -367,7 +381,7 @@ final reply.
    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.
+   or public snapshot state.
 8. A later bounded attempt opens a new transport and starts the held message
    after it observes the exact task idle. A route retains at most three queued steering
    messages; accepting a fourth atomically cancels the oldest with safe code
@@ -398,7 +412,7 @@ not uniquely re-observed with peer protocol 1, the write fails closed. A termina
 write whose outcome is ambiguous is never replayed; only a proven pre-write
 failure may be retried while the bounded in-memory receipt remains live. The
 receipt correlation does not add the UUID or receipt handle to public output
-or durable state; a separately selected route may already persist that same
+or durable state; a separately installed route may already persist that same
 Claude UUID as its private native route handle.
 
 Delivery callback arrival is timestamped at the service boundary. A terminal
@@ -422,8 +436,8 @@ next-tool-call-boundary rules above.
 
 ### Provenance framing and conversation continuation
 
-The broker classifies `STEER:`, `TRACK:`, and `DONE:`, enforces raw-byte body
-limits, deduplicates, and queues before presentation framing.
+The broker classifies `STEER:`, enforces raw-byte body 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
@@ -445,7 +459,7 @@ broker-owned `cross-session-message` outer element and an
   does not accept.
 - 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
+  `embassy send --conversation ... --from ...` instruction and the statement
   that caller, conversation, and route policy are rechecked.
 
 Embassy does not synthesize `from`, `from-session`, or `from-mode` attributes:
@@ -463,20 +477,21 @@ consistent structural provenance marker at the model input boundary. A native
 Claude wrapper already present in an inbound body is untrusted nested text
 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 full token delivered in the hint lets the recipient answer with
+`send --conversation`, but it is only a participant-scoped conversation
+locator. The service still validates
 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,
+journaled, logged, snapshotted, placed in a receipt,
 or returned from suffix-only public correlation. Formatter,
 provenance-metadata, and framed-size failures are clean pre-write terminal
 failures; they can never become ambiguous writes or replay authorizations.
 
 The gateway exposes `turn/steer` only through an exact leading `STEER:` body in
 the Claude-to-Codex direction. The global `EMBASSY_STEERING_ENABLED` switch is
-on by default and exact `0` disables classification. The tested 0.147.0 schema
-requires `expectedTurnId`, rejects a nonmatching active turn, reports a clean
+on by default and exact `0` disables classification. The 0.147.0 schema this
+adapter targets requires `expectedTurnId`, rejects a nonmatching active turn, reports a clean
 `activeTurnNotSteerable` condition, and returns the accepted turn ID. Embassy
 validates all of those temporal correlations before settlement. `turn/interrupt`
 is never called or exposed, and there is no generic App Server RPC escape
@@ -484,15 +499,14 @@ hatch.
 
 ### Delivery status and bounded waits
 
-Every accepted control-plane `send_to_claude`, `send_to_codex`, or `reply`
+Every accepted control-plane `send`
 result contains both its conversation ID and a fresh opaque delivery
 correlation handle called a delivery token.
 The token has the closed form `dlv_` followed by exactly 24 base64url
 characters (`A-Z`, `a-z`, `0-9`, `_`, or `-`). It addresses one bounded
-private-v3 message/status row and is not a provider receipt handle or a
+private schema-5 message/status row and is not a provider receipt handle or a
 provider native identifier. It is stored only in the mode-0600 broker state
-and never appears in a public snapshot, normal log, provider receipt, or
-dashboard.
+and never appears in a public snapshot, normal log, or provider receipt.
 
 The read-only `delivery_status` method accepts only that token and returns one
 of these closed results:
@@ -539,7 +553,7 @@ never displaced to admit a new send. A pressure-evicted handle returns
 Conversation IDs correlate replies, and callback addresses exist only in
 memory, but message bodies and their bounded attempt phase are durable. After a
 gateway restart, queued or reserved work may resume once against the same
-logical route and consent edge. Work that crossed the armed boundary settles
+logical route. Work that crossed the armed boundary settles
 `ambiguous`; provider-accepted work without terminal evidence settles
 `unconfirmed`. Neither is replayed. Work already past its deadline settles
 `expired`.
@@ -548,8 +562,8 @@ The delivery token and status of each retained message survive the restart: a
 queued or reserved attempt remains inspectable while it resumes, and armed or
 accepted work remains inspectable after it settles ambiguous or unconfirmed.
 Pending replies, callbacks, native receipt handles, and conversation
-capabilities do not survive. Logical registrations, Claude selections, and
-consent edges remain, while each subsequent provider operation must attest its
+capabilities do not survive. Logical registrations and installed Claude routes
+remain, while each subsequent provider operation must attest its
 own current transport facts.
 
 ## Gateway control plane
@@ -559,78 +573,97 @@ 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 closed version 1 method family is exactly these sixteen methods:
+The closed version 3 method family is exactly these fourteen methods:
 
 - `health` and `list_snapshot`, a safe public snapshot;
 - `observe_snapshot`, a read-only projection that may settle already-due
   delivery deadlines before projecting;
-- `register_codex`, `unregister_codex`, and
-  `remove_codex_registration` — explicit Codex registration and atomic
-  `--succeeds` replacement, owner unregister, and confirmed operator removal;
-- `select_claude` and `unselect_claude`, from the current sanitized
-  available-peer inventory;
-- `pair` and `unpair`, the two-endpoint permission edge;
+- `register_codex` and `unregister_codex` — explicit Codex registration with
+  atomic `--succeeds` replacement, and owner unregister;
 - `delivery_status`, a lookup by an opaque correlation handle retained only in
-  bounded private v3 state;
-- `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 provider discovery and republishes.
-
-The live dashboard companion calls `observe_snapshot` for every read; its
-mutation route additionally calls `pair`, `unpair`,
-`remove_codex_registration`, and `refresh_dashboard`, and nothing else.
+  bounded private v5 state;
+- `send`, whose direction follows the inherited principal — who is sending —
+  rather than the route table, and which installs a discovered Claude
+  session's route on its first use. It addresses either a route by name
+  (`toAlias`) or an open conversation by its token (`conversationId`), never
+  both: the conversation form is the correlated reply operation, and the
+  caller must already own one end of that conversation;
+- `refresh_discovery`, which rescans for Claude sessions;
+- `peer_catalog` and `peer_handoff`, the private federation catalog and
+  destination-owned handoff operations; and
+- `register_peer`, `unregister_peer`, `await_peer`, and `peer_receipt`, the
+  shell-peer registration, mailbox, and flush-before-receipt operations. A
+  first registration may ask to be `ephemeral` with a bounded `ttlMs`
+  (default five minutes): the route is real in memory — it routes, queues,
+  and settles like any other — but it is projected out of the durable state
+  document together with every row that names it (its messages, dedupe and
+  rate rows, and journal entries), excluded from the federation catalog, and
+  retired by the broker's own clock, so it cannot survive a restart or be
+  restored on another node. Removal — by `unregister_peer` or by that clock —
+  takes the same rows out of the live state in the same write, so nothing of
+  it is written afterwards either; a retirement that fails is retried twice,
+  five seconds apart, then left to the next restart. The clock is guarded by
+  the registration's identity, so a durable route that later takes the same
+  alias is never retired by it. `embassy check` uses one.
 
 The installed binary is `embassy`, and it is the only installed binary. Its
-eighteen implemented commands are
-`serve`, `health`, `status`, `delivery-status`, `wait-delivery`, `untrack`,
-`refresh-dashboard`, `dashboard`, `register-codex`, `unregister-codex`,
-`select-claude`, `unselect-claude`, `pair`, `unpair`, `send-to-claude`,
-`send-to-codex`, `reply`, and `convert-state-v2-to-v3`. `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
+seventeen implemented commands are
+`serve`, `service`, `health`, `status`, `watch`, `check`, `delivery-status`,
+`wait-delivery`, `refresh`, `register-codex`, `unregister-codex`, `send`,
+`reply`, `register-peer`, `unregister-peer`, `await`, and
+`peer-stdio`. `reply --conversation <token> --alias <own-alias>` is a
+deprecated alias for `send --conversation <token> --from <own-alias>`: it
+builds the same `send` request and is kept only until the reply hints already
+delivered in older envelopes have aged out. 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 and `convert-state-v2-to-v3` is an offline one-shot
-upgrade. The converter uses only the normally resolved state directory,
-requires the controller lock, installs strict native schema 3 through an
-fsynced atomic replacement, and reports only success plus the verified v2
-backup basename. It starts no provider, helper, listener, discovery, or control
-socket. The launcher never daemonizes itself.
+in an argument or file. The client emits one bounded normalized JSON line, and
+for every broker-protocol command it never returns a thread ID,
+provider-native ID, path, or address, and only `status` and `watch` return
+message bodies — the snapshot's own. There are three deliberate
+exceptions, each of them about something the operator alone is looking at.
+`service` reports its own plist path, its log path, and any program path in
+the plist that is no longer on disk, because managing local files is what it
+does. `status` on a terminal, `watch`, and `check` render for a person instead
+of emitting that JSON line: `status` and `watch` show the snapshot's own
+retained bodies (previewed to one control-free line) and the resolved state
+directory, and `check` prints its own hops. Piped or with `--json`, `status`
+and `watch` are machine-readable again, and every other command is unchanged. Every command but `serve` and `service` requires a running
+broker: `serve`
+starts one in the current terminal, and `service install|uninstall|status`
+manages the macOS launchd agent that runs one, contacting no broker itself
+apart from the bounded health check `install` reports at the end. The launcher
+never daemonizes itself.
 
 `register-codex --alias <new> --succeeds <current>` is one atomic logical-route
 transaction. It verifies the inherited identity of the replacement task,
 settles the outgoing route's work according to recorded write phase, removes
-its incident consent edges and transient capabilities, and publishes only the
+its transient capabilities, and publishes only the
 new registration. There is no prepared, activated, endpoint-generation, or
 manual-recovery state.
 
-`select-claude --alias <current-name@host>` and
-`select-claude --session <uuid>` select the same logical session.
-`send-to-claude --to` accepts either form only after explicit selection. UUID
+`send --to <current-name@host>` and `send --to <uuid>` address the same logical
+session, and either form installs its route on first use. UUID
 input is normalized to lowercase. No command returns the
 UUID, and no historical name remains routable after a rename.
 
-Provider-authorized mutations require one exclusive inherited principal.
+Provider-authorized registration and send operations require one exclusive inherited principal.
 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. `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.
+path and fails if a non-empty Codex thread ID is also present. A
+conversation-addressed send likewise fails with both identities or neither.
+
+Installing a Claude route is a side effect of a send, not a command: the
+sending principal is already attested, the addressed session is resolved
+against a discovery scan performed inside that send, and the store binds the
+route under the live-peer registration mode. A session already bound under the
+same (host, session UUID) keeps its registration — and therefore its in-flight
+conversations — and is renamed in place if its display name changed; a route
+whose alias now names a different session is displaced, its work settled
+`cancelled` with `ENDPOINT_RETIRED`, and both outcomes are journaled so
+`embassy status` shows them. Agents are instructed to send only where the user
+pointed them; that is an operating norm, not an additional gateway identity
+check.
 
 The foreground command is:
 
@@ -638,15 +671,8 @@ The foreground command is:
 embassy serve
 ```
 
-`--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.
+`serve` takes no options. There is no inbound mode to choose: the broker has
+one posture, and it is the OS boundary.
 
 Before provider validation, listener creation, or App Server attachment, the
 launcher acquires one fixed host-wide crash-reclaimable owner lease under the
@@ -655,8 +681,8 @@ controllers cannot be started for the same login account by choosing different
 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
+It emits one normalized ready line and holds the process until `SIGINT` or
+`SIGTERM`, when exact-owned resources are
 closed. Startup validates exact owned provider paths and binds controller-owned
 UDS listeners. Missing optional providers or a provider-local interface failure
 degrades only that surface. Unsafe ownership, path, symlink, lease, state,
@@ -668,54 +694,28 @@ does not publish candidates, select or connect to a peer, write a provider
 socket, request provider history, start a model turn, or contact a remote host.
 Validated target bindings may retain private native and socket-derived evidence
 memory-only until rescan or close, but none enters public state or persistence.
-Its ready result reports local host `this-mac`, dashboard filename
-`gateway-dashboard.html`, and `codexMode: "native_messaging"` without exposing
-paths.
+Its ready result reports the exact local host — from `nodes.json`, or this
+host's own hostname when that file is absent — and `codexMode: "native_messaging"`
+without exposing paths.
 
 There is no arbitrary filesystem operation, shell command, SSH command, App
 Server method, Claude registry mutation, credential argument, approval reply,
 or raw diagnostic method.
 
-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 each bounded liveness nudge. If the watch ultimately times out, Embassy
-records `settled` / `gateway` / `idle_timeout` only in watch history and emits
-no runtime stall alert. `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).
+Reaching the same-UID private control socket is the permission to message —
+and it 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. A name
+currently shared by more than one live Claude session is refused with
+`PEER_ALIAS_COLLISION` inside the send that addressed it BY NAME; the broker
+never resolves an ambiguous name by picking first. The fence is a fence on
+names only: a session UUID is unambiguous, so a UUID selector still reaches its
+session, and a sender is never fenced by its own display name because its
+identity was attested rather than typed.
 
-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 connector and federation
 
-## Codex connectors and remote hosts
-
-In the target multi-host design, each allowlisted execution host has a separate
-connector because each host has its own App Server and native state:
-
-- `this-mac`: the managed local App Server shared with Desktop;
-- `build-mac`: a host-local remote App Server reached through an attach-only SSH
-  proxy; and
-- `lab-mac.example`: the same design, still unprobed and disabled by default.
-
-The shipped foreground launcher accepts only `this-mac`; it rejects any remote
-host configuration. The two SSH connectors above remain planned rather than
-runnable v1 routes.
+Each broker's local connector has an explicit host identity, from `nodes.json` when federating or from this host's own hostname otherwise; `this-mac` has no reserved meaning. Configured peers exchange only body-free local catalogs and destination-owned handoffs over fixed SSH.
 
 The local connector resolves the managed standalone Codex release by exact
 owned path; it does not use `PATH`. That installation is separate from
@@ -731,7 +731,7 @@ unsubscribe, interrupt, archive,
 delete, history, shell, configuration, authentication, plugin,
 approval-response, and generic RPC methods remain excluded everywhere.
 
-The App Server capability first tested with 0.147.0 gates the privacy-preserving
+The App Server 0.147.0 schema this adapter targets gates the privacy-preserving
 `thread/resume.excludeTurns` field behind initialization capability
 `experimentalApi: true`. The transport therefore hard-codes that one
 non-configurable capability solely to suppress history retrieval. The attempt's
@@ -750,9 +750,9 @@ does not participate. Embassy does not read or retain reported
 working-directory or policy fields, and a transport failure cannot discard the
 registration or its accepted queue.
 
-Version 1 never changes or independently classifies a Codex task's approval or
-sandbox policy. Offline `TurnStartParams` schema evidence from tested App
-Server 0.147.0 shows that
+Embassy never changes or independently classifies a Codex task's approval or
+sandbox policy. Offline `TurnStartParams` schema evidence from the App
+Server 0.147.0 schema this adapter targets shows that
 policy overrides persist for the current and subsequent turns, so using them
 as per-message restrictions would silently mutate the native task. Embassy
 therefore starts the turn without overrides and leaves approval, sandbox, and
@@ -760,37 +760,24 @@ tool enforcement to the registered task's native Codex configuration. Explicit
 `codex-*` registration plus exact per-operation task and transport validation is the
 gateway reachability boundary; native task policy remains Codex's concern.
 
-A remote connector never starts, stops, replaces, signals, or unlinks a
-Desktop-owned App Server or its socket. If attach fails, the host is offline;
-Desktop remains responsible for lifecycle recovery. SSH aliases are fixed
-operator configuration, never model-provided strings. Normal OpenSSH host-key
-validation applies.
-
-### Completed no-model feasibility evidence
-
-On 2026-08-07:
-
-- A no-model environment check in the current Codex task confirmed that the
-  task tool process inherits `CODEX_THREAD_ID` and that its value matches the
-  required UUID grammar. The check emitted booleans only and never printed or
-  retained the identifier. This validates the repo skill/CLI premise that a
-  Codex task can self-register without accepting its private thread ID as a
-  command-line argument.
-- A local attach-only probe connected through a second proxy to managed Codex
-  App Server 0.147.0, initialized, called only `thread/loaded/list`, and
-  confirmed the current task was already loaded. It emitted normalized
-  booleans and an aggregate count, then confirmed cleanup of only its own
-  proxy process.
-- An authorized remote probe attached through a second SSH proxy to the
-  already-running `build-mac` App Server (remote Codex CLI 0.145.0), initialized,
-  and validated a schema-correct `thread/loaded/list`. It printed no task IDs,
-  payloads, remote diagnostics, history, or credentials and left Desktop's
-  original proxy alive.
-
-Both proxy processes required their exact-owned forced-cleanup fallback after
-the bounded graceful-close window; final cleanup was confirmed. These probes
-prove attach and loaded-task discovery on the tested versions. They do not
-prove notification fanout, approval routing, or writable task control.
+### Federation
+
+Federation is the only cross-machine path. Each entry in `nodes.json` is an
+OpenSSH `Host` alias; the broker dials `ssh <node> embassy peer-stdio` and
+speaks the fixed peer protocol — version 2, three methods: `initialize`,
+`catalog/get`, `handoff`. A peer's catalog is body-free (aliases, providers,
+states), and its routes appear locally as `alias@host` mirrors behind opaque
+references; a handoff is `delivered` when the destination durably accepts it,
+after which the destination owns provider delivery, and anything lost after
+that acceptance settles ambiguous and is never replayed. One hop only, no
+forwarding. A node answering `initialize` with another protocol version
+surfaces `PEER_PROTOCOL_MISMATCH` on its mirrored routes and in `embassy
+status` instead of a tunnel fault. SSH aliases are fixed operator
+configuration, never model-provided strings; normal OpenSSH host-key
+validation applies, your SSH configuration owns keys, users, and ports, and
+Embassy opens no listener of its own.
+
+### Offline App Server schema evidence
 
 The connector requires turn notifications to carry the exact `threadId` and
 correlates the exact `turn.id`; `item/completed` must carry the exact
@@ -818,122 +805,29 @@ next-tool-call timing boundary to App Server, treats a clean refusal as normal
 queue fallback, and treats malformed or write-ambiguous results as terminally
 uncertain without replay.
 
-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 major
-upgrade may change an internal interface; strict per-operation checks keep the
-responsible route closed if that interface no longer matches. Other providers
-remain available. If the attachment mode changes, a supporting release may
-require a separately announced controlled restart. The offline support matrix
-records what a release was tested with but never grants runtime authority.
-
-## Dashboard
-
-Version 1 generates self-contained HTML files under the controller-owned state
-directory: `gateway-dashboard.html` and `gateway-dashboard.zh-CN.html`, both
-rendered from one typed catalog and both atomically replaced, mode 0600, on
-every publish. Each page links to the other; that in-page link is the only
-static language switch, and `refresh-dashboard` takes no `--lang`. Each page
-has inline CSS and a restrictive Content Security Policy, with no JavaScript,
-external assets, CDN, cookies, local storage, service worker, telemetry,
-mutation endpoint, or network listener.
-
-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`.
-
-Each page assembles seven sections:
-
-- **Exchange** — aggregate gateway health plus every explicit cross-provider
-  pair and its per-edge counters.
-- **Attention** — allowlisted alerts such as an unavailable 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** — first-class Claude, Codex, DeepSeek, Grok, and shell-peer provider rows,
-  aliases, host, route state, and queue depth.
-- **Diagnostics** — best-effort observed metadata, per-host connector health,
-  last safe code, 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 — 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 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 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; 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_codex_registration`
-  control calls behind one closed `/action` route. The removal action carries
-  only a canonical public `codex-*` alias; native task IDs never enter the
-  browser contract. In one fencing commit it cancels queued or reserved work,
-  settles armed work ambiguous and accepted work unconfirmed, removes the
-  route's consent edges, and never replays uncertain work. The browser shows
-  the consequence and requires
-  explicit confirmation; the server rejects bodies over 1 KiB and limits the
-  companion to six actions per minute. It cannot create a registration,
-  succeed,
-  send, reply, approve, interrupt, change settings, or invoke a generic/provider
-  method. Each mutation touches only the edge it names: adding an edge never
-  retires another, and removing one settles its accepted work before the
-  change is published. Every action is followed by a
-  fresh observation. An observation may
-  settle already-due lifecycle deliveries before projecting, which is a broker
-  timer effect, not additional browser authority.
-- **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.
+## Protocol and schema versions
+
+Each number below is bumped once per release line, at first need, and a
+mismatch is refused rather than adapted to:
+
+| Surface | Version | On mismatch |
+| --- | --- | --- |
+| Private state schema (`gateway-state.json`) | 5 | An older or unknown schema refuses with `GATEWAY_STATE_SCHEMA_UNSUPPORTED`; reset only, never rewritten |
+| Private control protocol (CLI ↔ broker) | 3 | `CONTROL_VERSION_MISMATCH` at the client; keep the CLI and broker on one installation. A method the broker does not implement is `UNKNOWN_METHOD`, and the CLI says to rebuild or update the client |
+| Federation peer protocol (`peer-stdio`) | 2 | `PEER_PROTOCOL_MISMATCH` on that node's mirrored routes and in `embassy status` |
+| Native Claude helper IPC protocol | 2 | Internal to one installation; the helper and broker ship together |
+| Public snapshot schema (`embassy status --json`) | 2 | Unchanged across the 3.0 line |
+| Claude peer protocol (consumed, not owned) | 1 | A session record declaring another value is rejected in isolation and counted |
 
 ## Persistence and privacy
 
 The private store may retain:
 
-- schema-3 logical registrations with aliases, registration IDs, and exact
+- schema-5 logical registrations with aliases, registration IDs, and exact
   provider-native route handles inside the closed private binding schema;
-- consent edges tied to exact registration IDs, so alias reuse cannot inherit
-  permission;
 - bounded messages with explicit `queued`, `reserved`, `armed`, `accepted`, or
   `terminal` attempt phase and normalized activity used for accounting and
-  dashboard projection;
+  public projection;
 - timestamps, counters, dedupe/rate-limit records, and safe error codes.
 
 It also retains message bodies under bounded caps — the queued body of every
@@ -945,19 +839,18 @@ snapshot is a
 strict projection that removes private route handles, registration IDs, and
 operation-local endpoint evidence. The state directory is mode 0700 and state is mode 0600;
 provider-native identifiers never enter normalized events, public snapshots,
-the dashboard, CLI arguments/output, aliases, logs, or error text. On restart,
-logical routes and consent edges remain unchanged. Queued and reserved bodies
-may resume once only after their exact registration and consent authority is
+CLI arguments/output, aliases, logs, or error text. On restart,
+logical routes remain unchanged. Queued and reserved bodies
+may resume once only after their exact registration authority is
 rechecked; armed and accepted work settles without replay. Callback, native
 receipt, conversation, and reply capabilities are not reconstructed.
 
-Private schema 3 is the binary's only native store format; the bounded public
-snapshot deliberately remains schema version 2. Upgrading an existing schema-2
-state requires the offline `embassy convert-state-v2-to-v3` command before
-starting the broker. It verifies and retains a byte-identical v2 backup, then
-atomically installs and reads back strict v3 state. The runtime performs no
-in-binary migration or best-effort rewrite; any non-v3 state produces the
-ordinary strict corrupt-state error.
+Private schema 5 is the binary's only native store format; the bounded public
+snapshot deliberately remains schema version 2. The runtime performs no
+migration or best-effort rewrite. An old or unknown private schema refuses with
+`GATEWAY_STATE_SCHEMA_UNSUPPORTED` without mutating the state file; the operator
+must follow the reset-only runbook in `docs/CONFIGURATION.md`. A malformed
+schema-5 document produces the ordinary strict corrupt-state error.
 
 ## Minimum filesystem and process access
 
@@ -969,11 +862,12 @@ user's interactive Claude history. The narrow live boundary is:
   directory;
 - create and later remove only its exact-owned callback socket inside the
   accessible Claude peer-socket directory, with inode/generation checks;
-- create its control socket plus metadata/dashboard files only inside its
+- create its control socket plus metadata files only inside its
   separate controller-owned mode-0700 state directory;
-- attach to explicitly allowlisted Codex App Server endpoints; and
-- optionally execute fixed `ssh`/Codex proxy argv for allowlisted hosts, with
-  no shell and no model-supplied command or hostname.
+- attach to the managed local Codex App Server; and
+- optionally execute the fixed `ssh <node> embassy peer-stdio` argv for each
+  node listed in `nodes.json`, with no shell and no model-supplied command or
+  hostname.
 
 It does not read Claude transcripts, settings, project state, credentials,
 Keychain, shell history, or unrelated user files. It does not copy, print,
@@ -994,27 +888,26 @@ paths, peers, and transports:
 | `/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/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 |
+| `~/.local/state/agent-embassy` (or explicit `EMBASSY_STATE_DIR`) | Default controller-owned store, control UDS, and state lock; an explicit absolute configuration may replace only these state surfaces |
 | `~/.codex/packages/standalone` and `~/.codex/app-server-control/app-server-control.sock` | Resolve the exact owned managed Codex binary and attach to the already-running private local App Server; never bootstrap or unlink it |
 
 No grant to `~/.claude/projects`, the rest of
 `~/.claude`, Keychain APIs, the full home directory, or
-unrelated temporary files is required. Remote-host access is a later,
-separately reviewed fixed-SSH-alias capability.
+unrelated temporary files is required. Cross-machine reach is federation over
+`ssh <node> embassy peer-stdio`, configured only in `nodes.json`.
 
-Selected Claude workspaces may contain the private controller-state directory. The
-filesystem root and configured temporary roots are still rejected as
-deliberately broad Claude workspaces. The user's home is selectable with the
+A routed Claude session's workspace may contain the private controller-state
+directory. The filesystem root and configured temporary roots are still
+rejected as deliberately broad Claude workspaces, and that refusal happens
+before any route is installed. The user's home is addressable with the
 default controller-state root beneath it. A narrower project directory remains
 the preferred least-context setup, but it is not mandatory.
 
 ## Failure and upgrade policy
 
 - Provider versions are best-effort metadata and never grant or remove routing
-  authority. The offline support matrix records tested artifacts, capabilities,
-  limitations, and dates without entering runtime. A session record whose peer
+  authority. A session record whose peer
   protocol is not 1 is rejected per record and counted without stopping the
   broker; interface drift degrades only its responsible provider.
 - Unsafe ownership, path, symlink, lease, state, or generation evidence for
@@ -1026,8 +919,8 @@ the preferred least-context setup, but it is not mandatory.
   gateway-owned state, unexpected paths, queue overflow, deadline expiry, and ambiguous writes are
   normalized failures, never raw diagnostics.
 - A provider disconnect fails or defers only the current operation. The next
-  eligible attempt opens and attests a new transport; logical registration and
-  consent do not depend on a connector lifecycle.
+  eligible attempt opens and attests a new transport; logical registration
+  does not depend on a connector lifecycle.
 - The first successful Codex registration locks its exact alias, task, and host
   until that registration is explicitly replaced or unregistered. Exact
   re-registration remains idempotent.
@@ -1036,15 +929,15 @@ the preferred least-context setup, but it is not mandatory.
   the one atomic transaction that changes the registered Codex identity. A
   replacement must name the exact current registration on the same host, with
   a different alias and thread. Embassy settles the outgoing registration's
-  work from its durable attempt phase, removes its consent edges and transient
+  work from its durable attempt phase, removes its transient
   capabilities, and publishes only the replacement. No conversation, reply
-  capability, queued body, or permission transfers to the new identity, and no
+  capability, or queued body transfers to the new identity, and no
   intermediate generation or manual-recovery state exists.
 - No ambiguous mutation is retried automatically.
 - A queued or reserved body survives process loss under bounded retention and
   may resume once after exact logical authority is rechecked. Armed or accepted
   work settles `ambiguous` or `unconfirmed` and is never replayed.
-- A provider or Desktop update that changes an internal interface degrades its
+- A provider update that changes an internal interface degrades its
   responsible route while the broker and other providers remain available. A
   Claude record outside peer protocol 1 is rejected per record, and every
   current provider artifact used for an operation is re-attested before effect.
@@ -1053,11 +946,10 @@ the preferred least-context setup, but it is not mandatory.
 
 Routine validation is deterministic and synthetic: it does not inspect live
 provider state, connect a provider socket, attach to App Server, invoke SSH, or
-make a model request. The separately authorized local live tests recorded
-above established discovery and both message directions. Remote production
-connectors remain a separately reviewed future capability.
+make a model request. Live validation is a separately authorized operator
+action — `embassy check` is its everyday form — and is never part of CI.
 
-Only the synthetic layer is routine validation. Server/dashboard startup,
+Only the synthetic layer is routine validation. Server startup,
 discovery, and callback binding remain no-send operations; step 4 is the first
 provider write. A real provider message is never enabled in CI.