agent-embassy 2.0.1 → 3.1.0

package/README.md

@@ -1,7 +1,5 @@
-[English](README.md) · [简体中文](README.zh-CN.md)
-
 <p align="center">
-  <img src="https://raw.githubusercontent.com/YuanpingSong/embassy/main/assets/social-preview.png" alt="Embassy — a local gateway for bidirectional messaging between Claude Code sessions and Codex desktop tasks" width="720">
+  <img src="https://raw.githubusercontent.com/YuanpingSong/embassy/main/assets/social-preview.png" alt="Embassy — a local gateway for messaging between Claude Code sessions and Codex CLI tasks" width="720">
 </p>
 
 # Embassy
@@ -12,294 +10,197 @@
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![Node ≥ 20](https://img.shields.io/badge/node-%E2%89%A520-43853d)](package.json)
 
-Your [Claude Code](https://code.claude.com) sessions, [Codex](https://chatgpt.com/codex) desktop tasks, local DeepSeek Harness, Grok Build agent, and shell harnesses do not share one routing surface. Embassy is a small local broker that gives all five providers named routes and explicit consent edges — no plugins, no API keys handled by Embassy, and no cloud relay.
+Embassy is a small local broker that lets a [Claude Code](https://code.claude.com) session and a [Codex](https://chatgpt.com/codex) CLI task on the same Mac message each other by name, with a receipt for every delivery. It is personal software — one person, one macOS account, agents you already trust to run as that user — and an unofficial project, not affiliated with or endorsed by Anthropic or OpenAI.
+
+## Install
 
 ```bash
 npm install -g agent-embassy
+embassy service install
 ```
 
-Prerequisites, stated honestly: Claude routes require a live same-user Claude
-Code session with peer protocol 1. Embassy derives the external registry and
-peer-socket roots from the current OS user; it does not inspect Claude's
-launcher or configuration. Codex routes require **a managed Codex App Server
-standalone install** (created by the ChatGPT desktop app, or by the official
-installer `curl -fsSL
-https://chatgpt.com/codex/install.sh | sh` followed by `codex app-server
-daemon start` — the daemon alone does not provision the layout). A missing
-Claude registry degrades only Claude while the broker and other providers stay
-available. pnpm users: pin the version (`pnpm install -g
-agent-embassy@latest` can resolve stale metadata; prefer an explicit
-version) and ensure `PNPM_HOME/bin` is on PATH in non-interactive shells.
+Use one global package manager for Embassy (npm or pnpm), not both. Check for shadowing installations in each launch environment:
 
 ```bash
-embassy serve
+which -a embassy
+embassy --version
+ssh <node> 'which -a embassy; embassy --version'
 ```
 
-Or from source: `git clone https://github.com/YuanpingSong/embassy && cd embassy && npm ci && npm run build && npm link`.
-
-Embassy is built for one person, one macOS account, and agents you already trust to run as that user. It is an unofficial community project and is not affiliated with or endorsed by Anthropic or OpenAI.
-
-## Quickstart
-
-**Requirements:** macOS and Node.js 20+. Claude routes require peer protocol 1; Codex routes use Codex CLI tasks with the managed standalone App Server. DeepSeek is optional and launches from `DSH_HOME` (default `~/.dsh`) through the checkout's `demo:acp` script; Grok Build is optional and launches the release-pinned ACP package. A shell peer needs only the local CLI and its one-time token. The release-owned [support matrix](support/provider-support-matrix.json) records the exact tested provider artifacts and capabilities; it is release evidence, never a runtime allowlist:
-
-```bash
-codex app-server daemon start
-```
+For a configured federation peer, `<node>` is its OpenSSH Host alias; the SSH
+check uses federation's non-interactive launch environment. Update or remove a
+shadowing install through its owning package manager; updating npm does not update pnpm.
+The launchd plist pins the absolute Node and CLI paths used by `embassy service install`,
+not the next shell's PATH. After removing an installation, rerun `embassy service install`
+from the retained installation. `embassy service status` reports a plist program path
+that is no longer on disk.
 
-Run the managed daemon from a normal terminal and use Codex CLI as the supported task host. Desktop's `CODEX_APP_SERVER_USE_LOCAL_DAEMON` attachment is broken in Desktop 26.820 and later ([openai/codex#41112](https://github.com/openai/codex/issues/41112)), so it is not a supported setup. If `CALLER_IDENTITY_CONFLICT` reports both identities, strip only the unwanted inherited identity at the call site: use `env -u CLAUDE_CODE_MESSAGING_SOCKET embassy …` for a Codex-side call, or `env -u CODEX_THREAD_ID embassy …` for a Claude-side call. The Claude destination needs [`crossSessionInbound`](docs/CONFIGURATION.md) enabled.
+`service install` runs the broker as your user's launchd agent: it starts at login, restarts after a crash, and logs to `~/Library/Logs/agent-embassy/broker.log`. Prefer a process you start by hand? Run `embassy serve` in a terminal and leave it running instead. You need macOS, Node.js 20+, Claude Code (with its [`crossSessionInbound`](docs/CONFIGURATION.md#claude-codes-own-setting-crosssessioninbound) setting enabled on any session that should receive mail), and Codex CLI with the managed standalone App Server — the official installer `curl -fsSL https://chatgpt.com/codex/install.sh | sh`, then `codex app-server daemon start`. From source: `git clone https://github.com/YuanpingSong/embassy && cd embassy && npm ci && npm run build && npm link`.
 
-Runtime delivery is best effort. Version and build strings are unverified metadata and never grant or withhold routing authority. Consent plus exact logical route/session identity authorizes an attempt; the current per-operation transport and correlated evidence determine its honest result. Unsupported or changed interfaces therefore fail with provider-local safe codes instead of an online compatibility tier. Embassy still validates the trust boundary: exact owned or executed artifacts and state paths, generations of artifacts it actually uses, strict consumed protocol fields, Claude peer protocol 1, bounded queues, and no replay after an ambiguous write.
+Every alias below ends in `@your-host`. Replace `your-host` with this machine's host — the `hostId` on the broker's ready line (in the log, under launchd); name the wrong host and the CLI says which one this machine uses.
 
-> **Known limitation:** Embassy can reach Codex tasks only while Desktop uses the managed standalone App Server. In that mode, tasks currently cannot connect to Desktop's built-in in-app browser (`@Browser` loads but does not attach). Switching Desktop back to its default private App Server restores the built-in browser immediately — but makes those tasks unreachable by Embassy. No other capability regressions have been identified, though this was not an exhaustive parity test.
+## Your first message in four commands
 
-### 1. Start Embassy
-
-After creating the mandatory private `nodes.json` described in [Configuration](docs/CONFIGURATION.md), run the foreground broker under the same OS account as Claude Code and Codex:
+**1. Register the Codex task.** Ask your Codex agent to run this as a shell step in its current turn; it must run inside the task so it inherits the task's identity. You should see `"accepted":true`.
 
 ```bash
-embassy serve
+embassy register-codex --alias codex-reviewer@your-host
 ```
 
-You should see `"status":"ready"`. In another terminal:
+**2. Read what the broker sees.** The `sessions` block lists your live Claude Code sessions by name. If it is empty, start a Claude Code session and run `embassy refresh`, then look again.
 
 ```bash
-embassy health
 embassy status
 ```
 
-`status` lists `availablePeers` — the live Claude sessions you can select. If
-that list is empty, start a Claude Code session and run
-`embassy refresh-dashboard`, which refreshes discovery; the next `status`
-should show it.
-
-### 2. Register the Codex task
-
-Ask your Codex agent to run this as a shell step in its current turn — the command must run inside the task so it inherits the task's identity:
+**3. Send.** From the Codex task, body on stdin, to the name `status` showed. The session's route installs on its first use — there is no step between reading a name and messaging it. You get a `conv_` conversation token and a `dlv_` delivery token back.
 
 ```bash
-embassy register-codex --alias codex-reviewer@this-mac
-```
-
-You should see `"accepted":true`. The `codex-` prefix is required for Claude discovery. To retire the task later, run `embassy unregister-codex --alias codex-reviewer@this-mac` from inside that same task.
-
-Registration records the exact inherited task identity and performs no App Server I/O. Every delivery opens a fresh attested local transport, initializes it, resumes that exact task with history excluded, and authorizes the body write once. App Server and Desktop restarts therefore do not require re-registration or re-anchoring; a current unavailable or unobservable task keeps the logical route and consent edge while the attempt reports an exact safe code. Embassy never retargets by alias or replays an ambiguously written body.
-
-### Optional: register a universal shell peer
-
-A local shell harness can join as a `peer-*` route without a plugin, stable shell, daemon, PID binding, token file, or Keychain entry:
-
-When native Codex inbound dispatch is unavailable, this shell-peer mailbox is the supported fallback channel: register once, keep its token only in agent memory, and receive with bounded `await` calls.
-
-```bash
-embassy register-peer --alias peer-reviewer@this-mac
-```
-
-Registration prints the `peer_` token exactly once. Keep it in the agent's context and provide it on the first stdin line of every authenticated peer command; when a command also carries a message body, the remaining stdin bytes are the body. Never put the token in argv. For example, wait for inbound mail:
-
-```bash
-embassy await --alias peer-reviewer@this-mac --token-stdin <<'TOKEN'
-peer_<32-character-token>
-TOKEN
+embassy send --from codex-reviewer@your-host --to advisor@your-host --expects-reply <<'MSG'
+Please review the current approach and identify the main risk.
+MSG
 ```
 
-`await` performs bounded 30-second long polls until mail arrives or the caller stops it. Each registration may have one waiter and the broker permits 16 in total. Embassy writes the complete framed message to stdout, waits for stdout to flush, and only then acknowledges its private receipt. A missing receipt is `unconfirmed`; uncertainty after write authorization is `ambiguous`, and neither is replayed after restart. `register-peer --emit-env` is an optional convenience for harnesses that really do retain one stable shell; stdin is the universal path.
-
-### 3. Select a Claude destination
-
-Pick one name from `availablePeers`:
+**4. Answer by conversation.** Every delivered body arrives inside one broker-owned `<cross-session-message>` frame naming the attested sender (on a federated hop, the sender is named by the sending node — see [SECURITY.md](SECURITY.md)), and its first `<embassy-reply-hint>` carries the full `conv_` token and this exact command; the recipient runs it with the answer on stdin.
 
 ```bash
-embassy select-claude --alias advisor@this-mac
+embassy send --conversation conv_<token> --from advisor@your-host <<'MSG'
+The main risk is the double-write window; gate it behind the flag.
+MSG
 ```
 
-Run this from any same-UID process that can reach the private control socket. `embassy select-claude --session <uuid>` selects the same session by its native UUID.
+The same `send` runs from a Claude Code session, inheriting that session's identity, and the other direction needs no Embassy command at all: a Claude session finds `codex-reviewer` with its native `ListAgents` tool and messages it with `SendMessage`. `--to <session-uuid>` addresses a Claude session by its UUID. When two live sessions share a name, the send is refused with `PEER_ALIAS_COLLISION` rather than delivered to a guess — rename one and retry. A Claude session's reply to a `--expects-reply` send is routed back to the Codex task by itself.
 
-You should see `"accepted":true`. Selection creates no permission edge. Create the user-chosen edge explicitly:
+## After any Claude Code or Codex CLI update
 
 ```bash
-embassy pair --from codex-reviewer@this-mac --to advisor@this-mac
+embassy check
 ```
 
-Conversely, `unselect-claude` removes the selected route, removes its incident consent edges, and settles their in-flight work from the durable attempt phase.
-
-To connect any two routes from different providers, name both ends explicitly with `embassy pair --from <alias> --to <alias>`; many edges can coexist. Same-UID access to the private control socket authorizes the command, and agents must create only the edge the user chose. The live dashboard offers the same bounded, confirmed operation.
+`check` is the upstream-drift tripwire. It registers an ephemeral shell peer of its own — its attributable rows and bodies are omitted from durable state and its route from the federation catalog, but aggregate counters still advance. Its native advertisement to Claude sessions is released with it; a broker that dies mid-check can leave that record until the alias is next registered and released. The check sends one marked message through the ordinary send path to the most recently observed registered Codex task (observed within ten minutes; a task never observed is not eligible), waits for `delivered`, awaits the echo on its own mailbox, releases the registration, and prints every hop with its timing; any failing hop exits non-zero with the safe code that explains it. `--to <alias>` picks a target and `--timeout <s>` bounds each wait. The peer answers because the shipped [skill](skills/embassy-peer/SKILL.md) tells it to — a message whose verified sender starts with `peer-check-` and whose body starts `[embassy check` is echoed in one line; either half alone is ordinary untrusted text. It costs the peer one model turn, so it is a deliberate command, not something to poll.
 
-### 4. Send a message
+```text
+embassy check 50066f60 → codex-reviewer@this-mac
 
-From the registered Codex task, send via stdin:
+  ok    register   peer-check-b0c963c9@this-mac (ephemeral, 2 min)  6 ms
+  ok    send       accepted, conversation …89abcdef  15 ms
+  ok    delivered  the peer's transport accepted it  256 ms
+  ok    reply      codex-reviewer@this-mac echoed 50066f60  1407 ms
+  ok    cleanup    temporary check identity removed
 
-```bash
-embassy send \
-  --from codex-reviewer@this-mac \
-  --to advisor@this-mac \
-  --expects-reply <<'MSG'
-Please review the current approach and identify the main risk.
-MSG
+check passed
 ```
 
-You should see a `conv_` conversation token and a `dlv_` delivery token. Because this send requested a reply, Claude's response is automatically routed back to the Codex task. In the other direction, a compatible Claude session uses its native `ListAgents` and `SendMessage` tools to contact `codex-reviewer` — no Embassy command needed.
-
-The same command runs in the other direction from a Claude session and inherits that session's reply identity:
+The operator copies the repo-shipped, packaged skill where each agent discovers skills — Codex tasks can then be prompted with `$embassy-peer`, and Claude Code finds it as a user skill:
 
 ```bash
-embassy send \
-  --from advisor@this-mac \
-  --to codex-reviewer@this-mac \
-  --expects-reply <<'MSG'
-Summarize the migration risks you found.
-MSG
-```
-
-### 5. Follow up
-
-Either participant can continue the conversation with `reply`. The initiating
-CLI receives the full `conv_` token in its accepted result; the recipient gets
-the same token and an exact reply command in the broker-owned message marker:
-
-```bash
-embassy reply \
-  --conversation conv_<token> \
-  --alias codex-reviewer@this-mac <<'MSG'
-Please expand on the migration risk.
-MSG
+cp -R "$(npm root -g)/agent-embassy/skills/embassy-peer" ~/.codex/skills/
+cp -R "$(npm root -g)/agent-embassy/skills/embassy-peer" ~/.claude/skills/
 ```
 
-Every routed body reaches either product inside one broker-owned
-`<cross-session-message>` textual frame. It identifies the verified sender
-alias and begins with an `<embassy-reply-hint>` containing the full conversation
-token, the recipient's exact alias, and the corresponding `embassy reply`
-command. Use only that delivered full token and alias; never guess one from a
-suffix or substitute the sender's alias. The CLI still rechecks the caller,
-conversation membership, and current route policy, so the hint is
-not a permission bypass.
+For a pnpm installation, substitute `pnpm root -g` for `npm root -g` in both copy commands. Embassy does not install the skill automatically.
 
-The frame is a clear provenance marker, not a cryptographic signature or a
-claim that the body is trustworthy. Embassy neutralizes nested occurrences of
-its reserved framing tags in the untrusted body before provider delivery;
-arbitrary same-user code and all message text remain untrusted input.
+## Shell-peer fallback
 
-### See it live
+Any local harness that can run the CLI can join as a `peer-*` route — no plugin, daemon, PID binding, token file, or Keychain entry — and it is the supported fallback channel when native Codex delivery is unavailable. `embassy register-peer --alias peer-reviewer@your-host` prints a `peer_` token exactly once; keep it in the agent's context, never in argv, and pass it as the first stdin line of every later peer command with `--token-stdin` (the remaining stdin bytes are the body; `--emit-env` exists only for a harness that really does keep one stable shell). `embassy await --alias peer-reviewer@your-host --token-stdin` long-polls the mailbox in bounded 30-second iterations — one waiter per route, 16 in total — writes the complete framed message to stdout, and acknowledges only after stdout has flushed. A missing acknowledgement settles `unconfirmed`; uncertainty after the write was armed settles `ambiguous`; neither is replayed.
 
-`embassy dashboard --live` opens a five-tab streaming view in the browser
-(overview, deliveries, routes, activity, diagnostics) at
-`http://127.0.0.1:41961/` by default. To choose another stable port for that
-invocation, run `embassy dashboard --live --port <n>` with an integer from 1024
-through 65535. Up to four concurrent live views — across windows, tabs, or
-browsers — can use that URL while the foreground companion runs; a fifth stream
-is refused until one closes. If the port is occupied, startup fails explicitly,
-points to `--port`, and never falls back to another port. See
-[Dashboard](docs/DASHBOARD.md) for details.
+## Federation
 
-The live dashboard can remove any named Codex registration after an explicit confirmation. The confirmation names the consequence: the broker deletes that registration's consent edges, cancels queued or reserved work, settles armed work ambiguous and accepted work unconfirmed, and never replays either uncertain class.
+`nodes.json` in the state directory is optional. The broker writes it on first boot, naming this machine by its own hostname with an empty peer list, and from then on that file — not the hostname — is the broker's durable identity. To reach a second machine, add its OpenSSH `Host` alias to `nodes`, keep `host` exactly as written, and restart: the brokers exchange body-free route catalogs and destination-owned handoffs over `ssh <node> embassy peer-stdio`, your SSH configuration owns keys and users, and Embassy opens no listener. Remote routes appear as `alias@host` mirrors. Details in [Configuration](docs/CONFIGURATION.md).
 
-The broker also publishes mode-0600 static snapshots as `gateway-dashboard.html` and `gateway-dashboard.zh-CN.html`. The live dashboard has no login, token, cookie, or per-browser session: it assumes a trusted single-user machine, and local software that can reach or spoof loopback can read it and invoke its bounded actions. The server still requires the exact Host header on every request and the exact Origin plus `X-Embassy-Request` on every POST; it sends no CORS headers and does not accept `OPTIONS`.
+## Observability
 
-## How it works
+`embassy status` is the one command for "what is going on". It is read-only — it never rescans; `embassy refresh` does — and prints prose in a terminal. Piped or with `--json`, it emits `{ok,command,result}` with the snapshot under `result`: use `embassy status --json | jq .result.routes`. `--recent <n>` (1–100, default 10) sizes the message list.
 
 ```text
- Claude Code sessions                         Codex desktop task
- (native ListAgents /                         (native App Server,
-  SendMessage tools)                           existing task policy)
-        │                                             │
-        ▼                                             ▼
-  ┌──────────────────── Embassy ─────────────────────────────┐
-  │ explicit routes │ Codex busy queue │ receipts │ dashboard │
-  └───────────────────────────────────────────────────────────┘
+embassy 3.1.0  broker ok · pid 41213 · snapshot just now
+state dir /Users/you/.local/state/agent-embassy
+sessions scanned 3s ago
+
+connectors
+  claude  ok
+  codex   ok
+
+sessions
+  session           state  route   last seen
+  advisor@this-mac  busy   routed  3s ago
+
+routes
+  alias                    provider  state  queue  last seen
+  advisor@this-mac         claude    busy   2      discovered 3s
+  codex-reviewer@this-mac  codex     idle   0      12s ago
+
+recent (3 of 3)
+  12s ago    advisor@this-mac → codex-reviewer@this-mac  queued
+  2m ago     codex-reviewer@this-mac → advisor@this-mac  delivered  210 ms
+             The risk is the double-write window; I would gate it behind…
+  5m ago     advisor@this-mac → codex-reviewer@this-mac  delivered  61 ms
+             Please review the migration risk before the freeze.
 ```
 
-Embassy publishes each registered Codex task into Claude Code's live-session registry as its own `codex-*` peer. Claude sessions discover those tasks through `ListAgents`; Codex uses its managed App Server. DeepSeek and Grok Build are boot-registered ACP routes whose owned subprocess and one route-local session start lazily on first dispatch. Universal shell peers use `peer-*` aliases and a pull mailbox authenticated by an alias plus one-time-minted token.
-
-A pair is one explicit permission edge between two named routes from different providers, bounded at 128 edges by default. Every edge is created explicitly with generic `pair --from/--to`; the same-UID private control socket is the command's authority, while agents are instructed to create only user-chosen edges. Selection is separate and implies no consent. Without an edge, a sender settles terminally as `SENDER_NOT_PAIRED`. `embassy serve --inbound open` is the explicit opt-out for supported native inbound senders.
+When something is wrong it says the safe code **and** what to do about it, and one quiet corner never makes the whole broker look broken:
 
-Delivery timing is directional. Once routing and pre-write checks pass, every Claude-bound body is written immediately to Claude's native mailbox regardless of its observed busy or idle state. `transport_written` records that mailbox write and is the Claude-bound terminal `delivered` boundary; it does not mean Claude read or consumed the body. Codex-bound ordinary bodies instead queue while the task is busy and start a turn when it goes idle. In the Claude-to-Codex direction only, a body with an exact leading `STEER:` prefix may enter the active turn at the App Server's next tool-call boundary; if that boundary is unavailable, the message returns to the normal queue.
-
-Immediately before the provider write, Embassy gives every routed body one
-broker-owned cross-session marker containing the verified sender alias and a
-recipient reply hint. The full conversation token travels only in the
-initiator's accepted result and the recipient's transient message payload; it
-never enters the dashboard, public snapshot, journal, receipt, or log.
-
-Every settled message produces a receipt. `delivered` means the direction's terminal provider boundary was observed — toward Codex, the App Server accepted the turn; toward Claude, the native mailbox write completed. Neither means the model read or acted on it. `unconfirmed` and `ambiguous` mean the required evidence is missing; they are terminal states and never auto-retried. See [Delivery](docs/DELIVERY.md) for the full semantics.
-
-## The vocabulary
-
-Four embassy terms name real features:
-
-- **Registration and pairing** are the permission model: a Codex task is explicitly registered, and each pair is one explicit Claude↔Codex edge — only paired ends exchange messages, and many edges can coexist. No edge means `SENDER_NOT_PAIRED`; nothing is ever implicit.
-- **The ledger** is the delivery record: a receipt for every settled message, and a metadata-only dashboard.
-- **The pouch** is transit and the archive: bounded bodies, retained under bounded limits, private to your OS account — sealed against other users, not against you.
-- **Consulates** are configured Embassy nodes: brokers federate over attach-only SSH and keep destination-owned delivery and consent authority.
-
-## For agents
-
-Embassy's operators are often agents themselves: `register-codex` runs inside the Codex task, and the Claude side is driven entirely through native tools. The repo ships [`skills/embassy-peer/SKILL.md`](skills/embassy-peer/SKILL.md) — point your agent at it rather than paraphrasing this README.
-
-The skill ships in the npm package; install it where each agent discovers skills:
-
-```bash
-cp -R "$(npm root -g)/agent-embassy/skills/embassy-peer" ~/.codex/skills/
-cp -R "$(npm root -g)/agent-embassy/skills/embassy-peer" ~/.claude/skills/
+```text
+embassy 3.1.0  broker degraded · pid 41213 · snapshot just now
+state dir /Users/you/.local/state/agent-embassy
+sessions scanned 3s ago
+
+connectors
+  claude  ok
+  codex   degraded  MANAGED_CODEX_UNAVAILABLE
+          Either a process outside Embassy holds the managed Codex control socket — quit it — or the managed App Server standalone layout is missing, which starting the daemon alone does not create: follow the Codex prerequisite in the README (the official installer, then the daemon).
+  peer-release@this-mac stale (token or await loop gone)
+          2 message(s) waiting: run `embassy await --alias peer-release@this-mac --token-stdin` in the shell holding its token, or `embassy unregister-peer --alias peer-release@this-mac --token-stdin`.
+
+sessions
+  session           state  route   last seen
+  advisor@this-mac  busy   routed  3s ago
+
+routes
+  alias                    provider  state  queue  last seen
+  advisor@this-mac         claude    busy   2      discovered 3s
+  codex-reviewer@this-mac  codex     stale  1      30m ago
+  peer-release@this-mac    peer      idle   2      never
+    codex-reviewer@this-mac: That Codex task is gone. Run `embassy register-codex --alias <new-alias> --succeeds <this alias>` from the new task, or `embassy unregister-codex --alias <this alias>` from the old one.
+
+recent (3 of 3)
+  12s ago    advisor@this-mac → codex-reviewer@this-mac  queued
+  2m ago     codex-reviewer@this-mac → advisor@this-mac  delivered  210 ms
+             The risk is the double-write window; I would gate it behind…
+  5m ago     advisor@this-mac → codex-reviewer@this-mac  delivered  61 ms
+             Please review the migration risk before the freeze.
+
+alerts
+  PEER_TUNNEL_UNAVAILABLE  studio  45s ago
+    The SSH tunnel to that node is down; check the node is reachable and its broker is running.
 ```
 
-Codex tasks can then be prompted with `$embassy-peer`; Claude Code discovers it as a user skill.
-
-## Commands
-
-| Command | Run by | Purpose |
-| --- | --- | --- |
-| `serve` | operator | Start the foreground broker and dashboard |
-| `health` / `status` | operator | Check liveness and inspect the sanitized snapshot |
-| `refresh-dashboard` | operator | Refresh provider discovery and regenerate both static dashboard files |
-| `dashboard --live [--lang en\|zh-CN] [--port <n>]` | operator | Start the live dashboard companion with bounded route-consent actions; requires a running `embassy serve` |
-| `delivery-status` | either provider | Read one delivery tracker with `embassy delivery-status --token dlv_<token>` |
-| `wait-delivery` | either provider | Wait for that tracker to settle, up to the delivery deadline |
-| `untrack` | either provider | Close one active progress watch: `embassy untrack --conversation conv_<token>` |
-| `register-codex` / `unregister-codex` | Codex task | Advertise or retire that exact task; both take `--alias <codex-alias>`, and `embassy register-codex --alias codex-successor@this-mac --succeeds codex-reviewer@this-mac` hands the registration to a different task |
-| `register-peer` / `unregister-peer` | shell harness | Register or retire a `peer-*` route; registration emits its raw token once, while authenticated calls use `--token-stdin` (or the optional stable-shell env form) |
-| `await` | registered shell peer | Long-poll the peer mailbox in bounded 30-second iterations; one waiter per route, 16 globally, with acknowledgement only after stdout flush |
-| `pair` / `unpair` | same-UID control client | Add or remove one user-chosen cross-provider edge by naming both ends: `embassy pair --from advisor@this-mac --to grok-main@this-mac` |
-| `select-claude` / `unselect-claude` | same-UID control client | Select or remove one Claude route using `--alias <name@host>` or `--session <uuid>`; selection creates no permission edge |
-| `send` | registered Codex task, Claude session, or shell peer | Send one bounded stdin message between paired routes: `--from <alias> --to <alias>`, optional `--expects-reply` and `--track [--idle-minutes <n>]`; the broker derives direction from the resolved providers |
-| `reply` | conversation-token holder | Continue an active conversation with the full token returned to the initiator or delivered in the recipient's broker-owned reply hint: `--conversation conv_<token> --alias <your-alias>`, body on stdin, optional `--track [--idle-minutes <n>]` |
-
-Version 2.0 accepts only fresh private state. Follow the
-[reset-only state runbook](docs/CONFIGURATION.md#private-state-reset) before
-starting it over an older installation.
-
-`--track` opens a progress watch over the conversation; `--idle-minutes <n>`
-sets the idle interval for bounded liveness nudges (1–1440, default 5, rejected
-without `--track`). If the watch ultimately times out, Embassy records it only
-in watch history and emits no runtime stall alert. Close a watch with `untrack`,
-or by replying with a leading `DONE:`. See [Delivery](docs/DELIVERY.md).
+`embassy watch` tails the broker until Ctrl-C: each new message and each settlement at most once (`accepted → delivered (61 ms)`), stamped with the local time, plus route installs and retirements as a secondary line; `--json` streams the same events as JSONL. At most once, not exactly once — a transition that passes entirely between two one-second polls is never seen, and rows that left the retained window before the tail reached them are announced as a one-line note. `embassy --help` lists all eighteen commands.
 
 ## Safety in one minute
 
-- **Local broker, stable loopback dashboard.** `embassy serve` listens on private Unix-domain sockets and makes no provider API call. The opt-in `embassy dashboard --live` companion is a separate process and the only listener Embassy can create, bound to exact `127.0.0.1` on stable port `41961` by default (or the per-invocation `--port <n>`). It is deliberately unauthenticated local HTTP for a trusted single-user machine; Host, Origin, and sentinel checks constrain browser-origin requests but do not authenticate local processes or OS users.
-- **Same-UID containment, not authentication.** Caller identity is inherited from the local process environment. Route ownership and per-operation artifact checks reduce mistakes, but are not a defense against code already running as your OS user.
-- **Compatibility is tested offline; runtime is best effort.** The release-owned support matrix records exact tested artifacts, protocols, capabilities, stop fidelity, limitations, and test dates. Runtime never imports that matrix and never turns a version fact into authority. It validates exact owned boundaries and protocol facts, attempts the current operation, and reports provider-local health and safe codes without replaying uncertainty.
-- **Native permissions stay native.** Embassy sends no Codex approval or sandbox overrides and answers no approval request. `crossSessionInbound` remains Claude's own control; Embassy cannot override it.
-- **Provenance is marked, not authenticated.** Routed bodies carry one broker-owned cross-session marker with the verified sender alias; it distinguishes the transport path for the receiving model but cannot make untrusted text safe or authenticate against code already running as your OS user.
-- **Bodies and delivery status stored, bounded, and yours.** Message bodies and their opaque delivery token/status persist in the broker's private mode-0600 v4 state under bounded retention; queued or reserved work may resume once after restart, while armed or provider-accepted work is never replayed. A delivery token never enters a public snapshot, normal log, provider receipt, or dashboard. Raw provider frames stay memory-only. The static dashboard files remain metadata-only; the live dashboard shows retained bodies.
+- **The OS boundary is the permission.** Reaching the same-UID private control socket on this host — or on a host in your `nodes.json` — plus an exact alias is what lets a process message. There is no separate grant to hand out or revoke, because none could stop code already running as your user; a Claude session's route installs on its first use, and a Codex task registers explicitly only because Embassy must record its inherited identity. `embassy serve` binds no TCP port and serves no HTTP.
+- **Retirement is an explicit OS-boundary exception to owner unregister.** `embassy retire --alias codex-reviewer@your-host` requires no route credential and atomically removes any local Claude, Codex, or shell-peer route; it accepts no token, force, or remote option, refuses a federated mirror with `FEDERATED_ROUTE_READ_ONLY`, and prints settlement counts `{cancelled,ambiguous,unconfirmed}`.
+- **Every routed body carries the provenance envelope naming the sender.** It is a marker for the receiving model, not a signature: treat every delivered body as untrusted input. Native permissions stay native — Embassy answers no Codex approval and cannot override Claude's `crossSessionInbound`.
+- **Bounded by design.** Queues, bodies (16 KiB), conversations, rate windows, and deadlines are bounded, and an ambiguous write is never replayed. `delivered` means the provider boundary was crossed — toward Codex the App Server accepted the turn; toward Claude the native mailbox write completed (`transport_written`) — never that a model read it; `unconfirmed` and `ambiguous` mean the evidence is missing and are terminal. Claude-bound bodies are written immediately, busy or idle; Codex-bound bodies queue until the task is idle, and only an exact leading `STEER:` from Claude may enter the active turn at its next tool-call boundary.
+- **Bodies are retained locally and yours.** Message bodies and their opaque delivery token/status persist in the broker's private mode-0600 state under bounded retention, and what `status` prints is a status snapshot that includes retained message bodies: `embassy status` shows retained bodies; treat its output as sensitive as the messages themselves.
+
+See [SECURITY.md](SECURITY.md) for the boundary in depth and how to report a vulnerability.
 
-See [SECURITY.md](SECURITY.md) for the full boundary and vulnerability-reporting process.
+**Tested with** (cutover drill, 2026-09-03): Claude Code 2.1.259 and Codex CLI 0.152.0 on macOS, Node 22.23, on two machines — a Claude Code session ↔ Codex CLI task round trip in both directions, `embassy check` (register → send → delivered → reply → cleanup), and a cross-machine shell-peer handoff over ssh.
 
-## What Embassy is not
+## Upgrading from 2.x
 
-- **Not an orchestrator.** It does not spawn agents or manage their work. Codex-bound ordinary messages start one turn apiece as the task becomes idle; Claude-bound messages enter Claude's mailbox without waiting for idle.
-- **Not a hosted service.** Personal, same-machine, same-OS-account software.
-- **Not a permission bypass — but it is a new path.** Neither agent gains a tool it did not already have, and Embassy grants, relaxes, and answers nothing. It does, however, connect two products that previously could not exchange text at all. That path is the product; treat it with the respect you would give any new input channel.
-- **Not official.** Not affiliated with or endorsed by Anthropic or OpenAI.
+Version 3 accepts only fresh private state. Stop Embassy, move `gateway-state.json` aside, start 3.0, and re-register Codex tasks; Claude routes reinstall themselves on first use, and `nodes.json` is written for you if absent. The full [private state reset](docs/CONFIGURATION.md#private-state-reset) and every change are in the [changelog](CHANGELOG.md).
 
 ## Documentation
 
 | Document | What it covers |
 | --- | --- |
-| [Architecture](docs/GATEWAY-ARCHITECTURE.md) | The full design: topology, adapters, control plane, threat model, and the paired-consent inbound model |
+| [Architecture](docs/GATEWAY-ARCHITECTURE.md) | Topology, adapters, control plane, federation, protocol versions, and the OS-boundary permission model |
 | [Delivery](docs/DELIVERY.md) | Delivery semantics, tokens, settlement states, and retry rules |
-| [Configuration](docs/CONFIGURATION.md) | Environment variables, provider contracts, and addressing rules |
-| [Dashboard](docs/DASHBOARD.md) | Static and live dashboard setup, security model, and mutation actions |
-| [Security policy](SECURITY.md) | How to report a vulnerability, and the boundary in depth |
+| [Configuration](docs/CONFIGURATION.md) | Environment variables, `nodes.json`, the launchd service, and addressing |
+| [Security policy](SECURITY.md) | The boundary in depth, and how to report a vulnerability |
 | [Contributing](CONTRIBUTING.md) | Where changes go, and how to run the deterministic suite |
 | [Changelog](CHANGELOG.md) | What each release contains |
 | [Agent skill](skills/embassy-peer/SKILL.md) | The workflow an agent follows to operate Embassy |