agent-embassy 1.9.5 → 3.0.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,287 +10,178 @@
 [![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.
-
-```bash
-npm install -g agent-embassy
-```
+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.
 
-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.
+## Install
 
 ```bash
-embassy serve
-```
-
-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 require Desktop configured to use its 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/packages/standalone/current/codex app-server daemon start
-/usr/bin/open --env CODEX_APP_SERVER_USE_LOCAL_DAEMON=1 -a ChatGPT
+npm install -g agent-embassy
+embassy service install
 ```
 
-The first command starts the managed daemon if it is not already running (`restart` and `stop` also exist); the second launches the ChatGPT desktop app pointed at it. `CODEX_APP_SERVER_USE_LOCAL_DAEMON` is not documented by OpenAI; it is observed to work with this Desktop build and may change. Run the daemon command from a normal terminal, never from inside an agent session: Codex tasks inherit the daemon's environment, so a daemon started inside a Claude Code session leaks that session's identity into every task and registration fails closed with `CALLER_IDENTITY_CONFLICT` — fix it from a normal terminal with `codex app-server daemon restart`. The Claude session you select as a destination needs [`crossSessionInbound`](docs/CONFIGURATION.md) enabled — that is Claude Code's own setting, configured in Claude Code, not in Embassy.
-
-Desktop attaches to the managed standalone App Server when it launches. If the daemon restarts while Desktop is already open, waiting alone does not reconnect that app process: fully quit Desktop, rerun `/usr/bin/open --env CODEX_APP_SERVER_USE_LOCAL_DAEMON=1 -a ChatGPT`, and reopen the exact task.
-
-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.
+`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`.
 
-> **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.
+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.
 
-### 1. Start Embassy
+## Your first message in four commands
 
-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:
-
-```bash
-embassy register-peer --alias peer-reviewer@this-mac
+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
 ```
 
-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:
+**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 await --alias peer-reviewer@this-mac --token-stdin <<'TOKEN'
-peer_<32-character-token>
-TOKEN
+embassy send --conversation conv_<token> --from advisor@your-host <<'MSG'
+The main risk is the double-write window; gate it behind the flag.
+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.
+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.
 
-### 3. Select a Claude destination
-
-Pick one name from `availablePeers`:
+## After any Claude Code or Codex CLI update
 
 ```bash
-embassy select-claude --alias advisor@this-mac
+embassy check
 ```
 
-Run this from the operator terminal, or from inside the Codex task — either works, because `select-claude` uses an inherited Codex identity when one is present and resolves the sole registered task when one is not. `embassy select-claude --session <uuid>` selects the same session by its native UUID.
-
-You should see `"accepted":true`. Registration and selection together form a pair — this Claude session and this Codex task can now exchange messages through Embassy.
-
-To connect any two routes from different providers, name both ends explicitly with `embassy pair --from <alias> --to <alias>`; many edges can coexist. The command must run under an inherited endpoint identity that belongs to the requested edge. The live dashboard offers the same bounded, confirmed operation to the local operator.
+`check` is the upstream-drift tripwire. It registers an ephemeral shell peer of its own — kept out of the durable state document and the federation catalog, expiring on its own; its only trace is the native advertisement to Claude sessions, released with it, and a broker that dies mid-check can leave that record until the alias is next registered and released — 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-to-claude \
-  --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.
-
-`send-to-codex` is the CLI form of that same direction, for a Claude session that prefers an explicit command. It takes the same flags and reads the body from stdin, and it must run inside the Claude session so it inherits that session's reply identity:
+Install the 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-to-codex \
-  --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.
-
-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 but the unchanged JSON snapshot when piped or with `--json`, so `embassy status --json | jq .routes` and every script keep working. `--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.0.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.
+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:
 
-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`; `select-claude` remains the one-Codex-task shorthand for a Claude↔Codex edge. Nothing is implied. 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.
-
-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 the roadmap: the same model extended to Codex tasks on remote hosts over attach-only SSH — designed, and deliberately disabled in v1.
-
-## 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.0.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 |
-| `convert-state-v2-to-v3` | operator, broker stopped | Back up and convert the configured private state to native v3 without starting providers or the broker |
-| `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` | endpoint participant | Add or remove one cross-provider edge by naming both ends: `embassy pair --from advisor@this-mac --to grok-main@this-mac`; the inherited caller must belong to the edge |
-| `select-claude` / `unselect-claude` | operator or Codex task | One-task shorthand for `pair`/`unpair`, taking `--alias <name@host>` or `--session <uuid>`: resolves the Codex end only when it is unambiguous (inherited or sole registered task), otherwise fails closed |
-| `send-to-claude` | registered Codex task | Send one bounded message to a paired Claude session: `--from <codex-alias> --to <claude-alias>`, body on stdin, optional `--expects-reply` and `--track [--idle-minutes <n>]` |
-| `send-to-codex` | Claude session | Same flags and stdin body, using the inherited native reply identity |
-| `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>]` |
-
-`--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 seventeen 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 v3 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.
+- **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: filled by the PM after the cutover drill -->
 
-## 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 |