agent-embassy 2.0.1 → 3.1.0

package/CHANGELOG.md

@@ -4,6 +4,83 @@ All notable changes to this project are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
+## [3.1.0] - 2026-09-05
+
+### Added
+- `embassy retire --alias <local-alias>` — credential-free, same-UID operator removal of any local route (Claude session, Codex task, or shell peer) through the existing atomic removal. It settles queued and reserved work `cancelled`, armed work `ambiguous`, and accepted work `unconfirmed`, reports those counts, journals one `route_retired` event for every provider, and refuses federated mirrors with `FEDERATED_ROUTE_READ_ONLY`. No token, force, or remote option exists.
+- Proven destination enqueue refusals keep their safe code across federation; transport loss and failures after admission remain unknown and are never replayed.
+
+### Changed
+- Private control protocol 3 → 4: one new method (`retire_route`), 15 control methods, 18 CLI commands. A 3.0.0 CLI and a 3.1.0 broker refuse each other with the control mismatch code; restart the broker after upgrading.
+- `EMBASSY_MAX_ROUTES` accepts 2 through 128 and fails closed at config load above that with `INVALID_GATEWAY_CONFIGURATION`. 3.0.0 accepted 129–256 at parse and then refused provider startup. The tracked advertisement-helper cap is the same number.
+- Every busy-observation code on a Claude route (`CLAUDE_PEER_TARGET_UNKNOWN`, `CLAUDE_PEER_WORKSPACE_UNATTESTED`, `CLAUDE_PEER_NOT_OBSERVED`, `CLAUDE_DISCOVERY_UNAVAILABLE`) renders an operator remedy in `status`; the never-produced `CLAUDE_PEER_TARGET_STALE` and `CLAUDE_PEER_TARGET_CHANGED` codes are gone.
+- An idle or stale connector renders `ok` health; a named connector fault or a real provider failure stays `degraded`.
+- The supported package surface is the CLI, the skill, and the documented JSON. Deep imports of shipped `dist` declarations are unsupported; unused internal exports, dead validators, test-only runtime facades, and startup-owned route wiring were removed.
+- Public docs describe advertisement as one helper per local non-Claude route (`codex-*` or `peer-*`); federated mirrors are not advertised. A test guard rejects any singleton "one `codex-*` record" phrasing.
+
+### Fixed
+- Helper admission reserves a pending creation before forking, coalesces same-alias creation, releases a failed reservation, and joins in-flight creation on shutdown so every created client is closed.
+- Federated mirror routes are no longer handed to local native advertisement (no per-reconcile refusal or `NATIVE_ADVERTISEMENT_FAILED` alert).
+- Expired or unknown peer receipts return `not_found`, not `route_mismatch`; the peer-receipt fixtures no longer race a 100 ms timer on slow runners.
+- A renamed Claude source carries its current alias through envelopes, terminal replies, and native replies.
+- The service command's install/status/uninstall output is pinned byte-for-byte; the delivery runner's peer and provider engines are separate methods with a phase-failure characterization and no behavior change.
+
+## [3.0.0] - 2026-09-03
+
+### Added
+
+- `embassy status` renders for a person when stdout is a terminal: one broker line (pid, version, state directory, snapshot age), how old the last session scan is (offering `embassy refresh` past a minute), one plain word per connector that matters, a `sessions` block of the live Claude sessions the scan found and whether each has a route yet, a routes table with queue depth and last-seen age, the last messages with a one-line body preview (control and formatting characters stripped), and only those alerts that have a remedy — each non-`ok` word paired with its safe code and one line of what to do about it. It is read-only: it never rescans, so it is safe to run in a loop. Piped, or with `--json`, it prints the snapshot byte-for-byte as before, so every script and the skill are unaffected. `--recent <n>` (1–100, default 10) sizes the message list, and colour appears only on a terminal with `NO_COLOR` unset and never carries meaning alone. The staleness derivations are deliberate: a connector with nothing to observe is `stale`, not `degraded`; a shell peer holding unclaimed mail is reported without moving the overall word; a route is called `stale` only after ten minutes unobserved, and a Codex route gets the succession remedy only when it is also carrying a task-gone code; a Claude route the latest scan still lists is never stale (emb-107).
+- `embassy watch` tails the broker: each new message row and each settlement at most once (`accepted → delivered (61 ms)`), stamped with the local time, and route installs, retirements and discovery refreshes as a secondary line; rows evicted before the tail read them are announced as a note. `--json` streams the same events as JSONL, each transition carrying its `timestamp`; Ctrl-C exits 0; memory is bounded by the snapshot itself (emb-107).
+- `embassy check` is the upstream-drift tripwire to run after a Claude Code or Codex CLI update. It registers an ephemeral `peer-*` principal of its own — so it works from a plain terminal with no inherited identity, and leaves nothing behind but its native advertisement to Claude sessions, released with it — sends one `[embassy check <id>]` body through the ordinary send path to the most recently observed registered Codex task (observed within ten minutes; a task never observed is not eligible, and when none qualifies it names them and sends nothing), waits for `delivered`, awaits the correlated reply on its own mailbox, releases the registration, and prints every hop with its timing. `--to <alias>` picks a target instead; `--timeout <s>` (1–600, default 60) bounds each wait; any failing hop, an uncorrelated answer that times out, or a refused cleanup exits non-zero with the safe code that explains it; Ctrl-C runs the cleanup hop at once. The shipped skill gains the matching rule: a message whose verified sender alias starts with `peer-check-` and whose body starts `[embassy check` is answered with one line echoing the id (emb-107).
+- `register_peer` accepts `ephemeral: true` with an optional `ttlMs` (1 s–1 h, default 5 min) on a first registration: the route is real in memory but is never written to the state document, never published in the federation catalog, and is retired by the broker when its lifetime ends — gone on restart by construction. Every row it owns — the messages it sent and received, its dedupe and rate rows, and the journal rows that name it — is projected out of the written document while it lives and leaves the live state with it when it is removed, by the check's own cleanup or by expiry, so nothing of a check reaches disk at any point. A timed retirement that fails is retried twice more, five seconds apart, with an alert each time; after the third failure the registration is left until the broker restarts. Its native advertisement to Claude sessions is released with it but is not swept at boot: a broker that dies mid-check can leave that record behind, inert, until the alias is next registered and released. One safe code is added for the one thing that can go wrong with it: `EPHEMERAL_ROUTE_EXPIRY_FAILED`, the alert each failed retirement raises (emb-107).
+- `embassy service install|uninstall|status` runs the broker as a per-user macOS launchd agent, restarting it after a crash but never after a deliberate boot refusal (emb-108).
+- The three connect-stage codes that mean nothing is serving the state directory — `CONTROL_SOCKET_UNAVAILABLE`, `CONTROL_SOCKET_MISSING`, and `CONTROL_LISTENER_UNAVAILABLE` — now carry one hint that names the resolved state directory and points at `embassy service install` or `embassy serve` (emb-108).
+
+### Removed
+
+- The static dashboard and the live dashboard, with `embassy refresh-dashboard` and `embassy dashboard --live` (emb-100).
+- The ACP-backed DeepSeek and Grok providers with their `dsh-`/`grok-` routes, the offline provider support matrix, and `embassy doctor` with its Codex Desktop classifier (emb-101). The managed-socket holder check stays: a process outside Embassy holding the managed Codex control socket still degrades the Codex connector with `MANAGED_CODEX_UNAVAILABLE`.
+- zh-CN localization, the `--lang` option, and the copy-table layer (emb-102).
+- Progress watches: `TRACK:`/`DONE:`, `--track`, `--idle-minutes`, `untrack`, the automated liveness nudge, `EMBASSY_TRACKING_ENABLED`, `EMBASSY_MAX_WATCHES` (emb-103). A body beginning `TRACK:` or `DONE:` is now delivered verbatim as an ordinary message. Busy-gating (`ROUTE_BUSY` deferral and requeue), `STEER:`, and the queued-ahead marker are unchanged.
+- `GATEWAY_NODE_INVENTORY_REQUIRED` (emb-106).
+- Codex Desktop as a documented task host: the attachment mode upstream had broken, its `CODEX_APP_SERVER_USE_LOCAL_DAEMON` guidance, and the known-limitation note are gone from every shipped document; the supported host is Codex CLI with the managed standalone App Server (emb-109). The marketing site is one short page pointing at the README and this changelog; its former second-language page redirects to it (emb-109).
+- Consent edges, with `embassy pair` / `embassy unpair`, `embassy select-claude` / `embassy unselect-claude`, `embassy serve --inbound`, and `EMBASSY_MAX_PAIRS` (emb-104). The `pair`, `unpair`, `select_claude`, and `unselect_claude` control methods, the four safe codes `SENDER_NOT_PAIRED`, `CONSENT_OWNER_HOST_REQUIRED`, `INVALID_CONSENT_EDGE`, and `CONSENT_EDGE_CAPACITY_REACHED`, the `consentEdges` inventory in private state and in the public snapshot, the consent rows on the federation catalog and handoff wire, and the `native_reply` dispatch authorization (the one branch that skipped the target-workspace assertion) are all gone.
+
+### Changed
+
+- `nodes.json` is optional; when absent at boot, the broker writes it once, naming this machine by its own hostname with an empty peer list, and federates with nobody until you edit the file in. That written file — not the hostname — is the broker's durable identity from then on: renaming the machine does not rename the installation, and a controller lock left behind by a crash is recovered by process liveness rather than by the name that wrote it (emb-106).
+- Stale `gateway-dashboard*.html` files left by 2.x, and their `.tmp` publish artifacts from a crashed 2.x write, are removed from the state dir at boot (emb-106).
+- A `.gateway-controller.lock` is judged only by whether its recorded pid is alive. A lock left by a crash is recovered whatever machine name it records, so a rename can no longer wedge a state directory permanently, and an empty lock left mid-write is recovered too; an unreadable one refuses with `GATEWAY_STATE_LOCK_UNVERIFIED`, and a live pid still refuses with `GATEWAY_STATE_IN_USE`. Both refusals now print the lock's path, and the live-pid one the recorded host and pid, with the remedy. What this trades away: the old hostname gate also happened to keep two machines off one state directory shared over a network. Embassy has never supported sharing state across machines ([SECURITY.md](SECURITY.md)), so no supported configuration changes — but if you were relying on that side effect, it is gone. A record that parses but names no usable pid is unverified too, not "in use". Recovered locks are kept as `.gateway-controller.lock.stale-<recovered-at>-<uuid>` for seven days from the recovery — the timestamp is in the name because the file's own mtime is the crashed broker's and can be far older — then swept (emb-106).
+- `embassy refresh` reports a discovery failure honestly instead of claiming success.
+- Private state schema is 5, reset-only: 2.x state is refused with `GATEWAY_STATE_SCHEMA_UNSUPPORTED` and never rewritten; follow the [private state reset](docs/CONFIGURATION.md#private-state-reset).
+- Federation peer protocol is 2; a node answering `initialize` with another version surfaces `PEER_PROTOCOL_MISMATCH` on its mirrored routes and in `embassy status` instead of a tunnel fault.
+- Private control protocol is 3; a client and broker on different lines report `CONTROL_VERSION_MISMATCH`.
+- `unregister-codex` against a federated (read-only) route now returns `rejected` with `FEDERATED_ROUTE_READ_ONLY` instead of `not_found` (emb-101).
+- The stall and diagnostic notices written into a Claude session now say ``Run `embassy status` for details`` (emb-102).
+- `send` installs a discovered Claude session's route on first use; the permission to message is same UID + same host (or a configured node) + alias; the provenance envelope names the sender; a colliding alias is refused with `PEER_ALIAS_COLLISION` at send time (emb-104).
+- Private state keeps schema 5 with a shape change: the retired `consentEdges` key makes an existing file fail the exact-key check, so an older schema-5 state file is refused with `CORRUPT_GATEWAY_STATE` and the documented [private state reset](docs/CONFIGURATION.md#private-state-reset) applies (emb-104). A message's `sourceRegistrationId` is narrowed from nullable to always present, since every sender now holds a route.
+- Two safe codes are added (emb-104): `ROUTE_DIRECTION_MISMATCH`, when admission is asked to route between two endpoints with no direction between them, and `ENDPOINT_RETIRED`, the settlement reason for the work of a route displaced by another session claiming its alias. Two activity actions replace the four retired ones: `claude_route_installed` and `claude_route_retired`.
+- A refused `send` control result may carry an optional `reason` — the safe code behind the coarse decision — and the CLI renders one remedy per reason instead of one generic line (emb-104).
+- `availablePeers[].selected` is renamed to `routed` in the public snapshot: it means the session has an installed route, never a permission (emb-104).
+- The native Claude helper IPC protocol is version 2: `selected_route` is the only dispatch authorization and its `stateRoot` is required, so every preparation runs the target-workspace assertion (emb-104).
+- A federation node whose only routes are peer mirrors can persist and reload its state: the loader takes the local host identity from the broker's configuration instead of deriving it from local routes, which previously left a fresh node unable to write after its first peer refresh (emb-104).
+- `send` addresses either a route by name (`--to <alias>`) or an open conversation by its token (`--conversation conv_<token>`), never both and never neither; the conversation form is what `reply` was, and it is how a recipient answers (emb-105). The caller must already own one end of that conversation, the other end stays the binding the conversation recorded — a replaced endpoint still refuses with `CONVERSATION_ROUTE_RETIRED` rather than retargeting — and an answer always expects a reply, so `--expects-reply` is rejected beside `--conversation`. The `reply` control method is gone with it: both CLI verbs build one `send` request, and the closed version 3 method family is now fourteen methods. A conversation-addressed send with no inherited credential reports the provider-neutral `CALLER_IDENTITY_REQUIRED`, and the CLI's hint names the three credentials it accepts — the Codex task's `CODEX_THREAD_ID`, the Claude session's messaging socket, or a shell peer's token on the first stdin line with `--token-stdin`; a peer credential authenticates a `peer-*` alias and nothing else, in either addressing form (emb-109). A conversation answered from the wrong end — an end-owner naming the other end in `--from` with its own credential — is refused with `CODEX_THREAD_MISMATCH` or `CLAUDE_REPLY_ADDRESS_INVALID`, and the CLI renders the own-alias remedy for the caller-mismatch reasons (emb-109).
+- The `<embassy-reply-hint>` that begins every delivered envelope now names `embassy send --conversation <token> --from <alias>` (emb-105).
+- A control request naming a method this broker does not implement still fails with `UNKNOWN_METHOD`, and this CLI now adds one hint on every path that meets it — the plain command path, `status`, `watch`, and each `check` hop: rebuild or update so the client and broker are one Embassy installation. The hint helps a newer client against an older broker on the same protocol line; an older client sending a retired `reply` frame still gets the bare code, because that client predates the hint (emb-109).
+- A Codex task whose alias has no registration on this broker — the state every task is in after the private state reset — is refused with `ROUTE_UNREGISTERED` and told to run `embassy register-codex`; `CODEX_THREAD_MISMATCH` is reserved for a registration that exists under another task and carries its own remedy. A route send with no credential and a `codex-*` or `peer-*` `--from` reports `CALLER_IDENTITY_REQUIRED` naming the one credential that alias shape needs, and only a Claude-shaped alias keeps `CLAUDE_IDENTITY_REQUIRED`; a peer token beside a non-peer alias says so instead of a bare argument fault. `embassy check` fails its reply hop when the mailbox receipt is refused (emb-109).
+
+### Deprecated
+
+- `embassy reply --conversation <token> --alias <your-alias>` is a deprecated alias for `embassy send --conversation <token> --from <your-alias>` (emb-105). It builds the identical control request and returns the identical result and exit code; only the echoed `command` name differs. It stays for one release because reply hints delivered in envelopes already in flight still name it, and is removed after that.
+
+### Upgrade note
+
+- Reset only. Stop Embassy, move `gateway-state.json` aside — schema 5 refuses 2.x state with `GATEWAY_STATE_SCHEMA_UNSUPPORTED` and never rewrites it — and start 3.0, following the [private state reset](docs/CONFIGURATION.md#private-state-reset). `nodes.json` is optional: keep yours if you federate; the broker writes one on first boot if you have none.
+- Re-register Codex tasks from inside each task. There is no select or pair step: Claude routes install themselves on first use.
+- `embassy reply` is deprecated for `embassy send --conversation <token> --from <alias>`; update scripts now, it is removed next release.
+- Codex Desktop hosting is no longer documented; run tasks in Codex CLI with the managed standalone App Server.
+- The four numbers: private state schema 5, control protocol 3 (keep the CLI and broker on one installation), federation peer protocol 2 (upgrade every node), Claude helper protocol 2 (internal to one installation).
+
 ## [2.0.1] - 2026-09-01
 
 Identical product to the unpublished v2.0.0 (its pipeline was failed by a test-hermeticity defect — dashboard-command tests leaned on the developer's real state inventory, red on CI since the mandatory `nodes.json` cut; no product defect). The dashboard-command tests are now hermetic.

package/CONTRIBUTING.md

@@ -41,8 +41,8 @@ recovery.
 - Update README and architecture documentation when public behavior changes.
 - Verify that public files contain no credentials, native IDs, message bodies,
   local state, or personal absolute paths.
-- Do not commit `node_modules`, `dist`, package archives, generated dashboards,
-  logs, environment files, or live-validation artifacts.
+- Do not commit `node_modules`, `dist`, package archives, logs, environment
+  files, or live-validation artifacts.
 
 ## Architecture rules
 
@@ -50,13 +50,11 @@ recovery.
 
 - Codex tasks self-register through inherited `CODEX_THREAD_ID` and a
   `codex-*` alias. Never add a thread-ID argument or global task-history scan.
-- Codex-to-Claude sends require a previously selected compatible live session.
-  Do not auto-select during send.
-- In the default `paired` inbound mode, a Claude session reaches the registered
-  native Codex peer only across an existing pair edge; a sender without one is
-  refused `SENDER_NOT_PAIRED` before admission and the refusal is journaled.
-  Only `serve --inbound open` admits any exact compatible live same-UID session.
-  Neither path makes the inbound session outbound-selected.
+- A Codex-to-Claude send installs the addressed session's route on first use;
+  a Claude session's own route installs on its first outbound message. There is
+  no separate grant: the permission is the OS boundary — same UID, same host or
+  a host configured in `nodes.json` — plus the exact alias, and the provenance
+  envelope names the sender.
 - Claude's session UUID is its stable logical identity. Current names are a
   live index; do not add historical-name routing or PID/socket identity.
 - Preserve current-name collision refusal and exact registration fencing.
@@ -64,7 +62,7 @@ recovery.
   performs no provider or App Server I/O. `register-codex --succeeds` is one
   atomic logical replacement that settles queued/reserved work `cancelled`,
   armed work `ambiguous`, and accepted work `unconfirmed`; removes every
-  incident consent edge and conversation, reply, or native capability; and
+  incident conversation, reply, or native capability; and
   installs only the successor. Do not add prepared generations, re-anchoring,
   or recovery journals.
 
@@ -90,8 +88,10 @@ interface drift or an unavailable optional provider degrades only that
 surface. Do not widen a declared protocol without documented review and
 deterministic fixtures.
 
-The gateway may publish one process-owned `codex-*` peer so Claude's native
-`ListAgents` and `SendMessage` tools can reach Codex. It must never overwrite a
+The gateway may advertise each local non-Claude route (`codex-*` or `peer-*`) through
+its own forked helper, callback socket and marked registry record, subject to the
+tracked-helper limit and pending-creation limitation in SECURITY.md. Claude's native `ListAgents` and `SendMessage` tools
+can reach those local routes; federated mirrors are not advertised. The gateway must never overwrite a
 foreign registry record, claim to be a Claude model session, or unlink a socket
 whose exact generation it no longer owns.
 
@@ -124,37 +124,24 @@ native. Do not route around a hold or refusal or fabricate a successful receipt.
   terminal failure, ambiguity, expiry, and restart abandonment.
 - Never retry an ambiguous provider write. Requeue only a confirmed clean
   deferral that has not crossed an ambiguous mutation boundary.
-- The private mode-0600 v4 ledger retains bounded queued and recent bodies,
+- The private mode-0600 v5 ledger retains bounded queued and recent bodies,
   opaque delivery tokens, and status. Queued or reserved work may resume once
   within its deadline and attempt budget against the same exact route and edge.
   Armed work settles `ambiguous`; accepted work settles `unconfirmed`; neither
   is replayed. Conversations, reply/native capabilities, raw frames, callback
   addresses, and socket paths remain memory-only.
 - Persist native route identifiers only in the closed private binding schema.
-  Keep them out of events, snapshots, dashboard rows, logs, errors, and CLI
+  Keep them out of events, snapshots, logs, errors, and CLI
   output. The only CLI exception is a UUID explicitly supplied by the user as a
   Claude selector.
 
 ### Local control surface
 
-`embassy serve` may use one private same-user control UDS and publish two inert,
-metadata-only static dashboard files. It must not listen on TCP or HTTP. The
-only reviewed exception is the separately invoked foreground
-`embassy dashboard --live` companion, which binds exact IPv4 loopback on stable
-port `41961` by default or the validated per-invocation `--port <n>`. It has no
-local-process or UID authentication and therefore assumes a trusted
-single-user machine; exact Host on every request and exact Origin plus
-`X-Embassy-Request` on every POST constrain browser origins, not local
-software. Preserve the direct root URL, multi-window/browser access, collision
-failure with no fallback port, no CORS/`OPTIONS`, and only the reviewed pair,
-unpair, refresh-discovery, and named Codex-registration-removal mutations—never
-a provider or generic control method. Confirmed removal may target any named
-Codex registration; its atomic commit removes incident consent edges and
-conversation, reply, or native capabilities, and settles queued/reserved work
-`cancelled`, armed work `ambiguous`, and accepted work `unconfirmed`. Do not
-add a wildcard/remote listener, external assets, service workers, telemetry,
-or additional mutation endpoints. Keep the public v1 launcher foreground,
-macOS-only, and local-host-only.
+`embassy serve` may use one private same-user control UDS and nothing else. It
+must not listen on TCP or HTTP, and Embassy ships no other listener. Do not add
+a wildcard/remote listener, external assets, service workers, telemetry, or a
+mutation endpoint. Keep the shipped launcher foreground, macOS-only, and
+local-host-only.
 
 ## Live validation
 
@@ -180,8 +167,7 @@ lease spawns macOS's `/usr/bin/lockf`); macOS runs the full suite.
 
 ## Design honesty rules
 
-These outlive any visual era and bind every surface — dashboards, CLI copy,
-site, docs, in both languages:
+These outlive any visual era and bind every surface — CLI copy, site, docs:
 
 - Progress is never green. Only a terminal success state may look like one.
 - `delivered` means the write completed; `released` is not read; nothing may
@@ -197,7 +183,8 @@ site, docs, in both languages:
 [`docs/DECLINED.md`](docs/DECLINED.md) records, per release, what we considered
 and chose not to build, each with a one-line reason. It is product
 documentation: a product that documents what it refuses to build is making the
-same promise the dashboard makes—the truth over the appearance of completeness.
+same promise its status output makes—the truth over the appearance of
+completeness.
 PRs that implement something in the ledger must address its reason.
 
 ### Why tickets are priced by the PM
@@ -220,4 +207,4 @@ deliverability beats ceremony. Never auto-retry a delivery the recipient's
 user denied: that is consent, not transport.
 
 For long messages, write the body to a file and pipe it
-(`embassy reply ... < body.md`); never inline `printf` for prose.
+(`embassy send --conversation ... < body.md`); never inline `printf` for prose.