agent-embassy 4.2.0 → 4.4.0

package/docs/CONFIGURATION.md

@@ -1,5 +1,7 @@
 # Configuration
 
+Embassy requires macOS and Node.js 22 or newer.
+
 Embassy has one broker per login user and machine. Configuration is inherited
 when the broker starts; changing it requires a broker restart. Provider build
 or version metadata never grants routing authority.
@@ -96,20 +98,54 @@ native agent list.
 
 To receive in Codex, use its managed standalone installation with its App Server
 daemon already running under the same macOS login; merely having a `codex`
-executable on PATH is insufficient, and Embassy does not install or start that daemon.
-
-A Codex task registers itself with `embassy register-codex --alias ...` using
-its inherited `CODEX_THREAD_ID`. The ID is not a command argument or public
-output. Registration is a logical state change and performs no App Server I/O.
-Each delivery independently attests the current App Server interface and exact
-task before authorization, resumes that task without retaining history, and
-writes through a fresh operation.
+executable on PATH is insufficient, and Embassy does not install, start or
+update that daemon.
+
+Embassy observes the daemon's recency-sorted top 20 unarchived root threads and keeps them
+current from lifecycle and name events. Native names become public lookup
+aliases; native task IDs remain only in the closed private endpoint binding,
+while previews, turns and item content are neither retained nor printed.
+Sub-agents are not discovered or displayed. Busy roots queue ordinary messages;
+waiting means approval/user input, idle means ready, and dormant means unloaded.
+Delivery resumes the exact dormant root without retaining history.
+Embassy derives a safe alias from the native name: normalized
+lower-case ASCII tokens, a `codex-` prefix, at most 32 characters before
+`@host`. A missing, `Untitled task`, or native-ID-revealing name gets a stable alias from
+the opaque Embassy endpoint ID, never from the native task ID.
+
+Absence from the daemon's loaded list alone never marks an agent unreachable;
+dormant wake is ordinary use. Embassy labels a session unsupported only from
+positive native evidence.
+
+`embassy register-codex --alias ...` remains a fallback for harnesses without
+native daemon integration. It uses the caller's inherited `CODEX_THREAD_ID`;
+the ID is not a command argument or public output. A fallback registration is
+the same endpoint kind as discovery, and a matching native identity cannot
+create a duplicate. Each delivery independently attests the current App Server
+interface and exact task before authorization.
+Explicit registration sets a private retention marker, so older roots remain
+listed after restart even outside the discovery window. Window aging preserves
+automatic rows referenced by pending work, but drops unused automatic rows to
+release capacity. No retirement, suppression or settlement occurs. A returning
+root keeps its ID while retained/pending; after pruning it receives a fresh ID,
+and old receipts never retarget. An unnamed root gets a new generated alias
+after pruning. The existing 128-endpoint bound remains.
+No discovered/registered badge is exposed.
+Explicitly registered rows keep their registered aliases through native scans;
+native names drive automatic rows only. A later explicit registration can rename
+the retained row without moving its identity or admitted work.
 The ellipsis in `--alias ...` is a substitution: use the task's chosen
 `codex-` name with this machine's exact `@host` suffix.
 
 `register-codex --succeeds <old-alias>` atomically retires a predecessor and
 installs the caller. It never reanchors pending work to a new identity.
 
+Explicit retirement suppresses re-discovery of that native identity while its
+bounded retirement evidence remains. Embassy never answers approvals or
+changes a task's sandbox or approval policy. It consumes only the App Server
+metadata and operation methods needed for discovery, unsubscribe, resume,
+delivery and exact-turn STEER; it exposes no generic provider RPC.
+
 ## SSH federation
 
 Install Embassy and run `embassy service install` on both Macs; for `studio`
@@ -119,8 +155,9 @@ with each peer name matching both the remote inventory's `host` and a working
 SSH destination or `~/.ssh/config` Host alias.
 
 After changing a running broker's inventory, reload it with
-`embassy service install`; register `codex-reviewer@laptop` from the live
-Codex task on laptop, then ask the Claude session on studio to run
+`embassy service install`; wait for `codex-reviewer@laptop` to appear from the
+Codex daemon on laptop (or use fallback registration), then ask the Claude
+session on studio to run
 `embassy send --to codex-reviewer@laptop` with the message on stdin.
 
 For each configured remote node Embassy runs the fixed system SSH client in
@@ -148,7 +185,7 @@ destination persists its queue before acceptance, and an uncertain result is
 never replayed.
 
 `embassy refresh` observes configured catalogs in parallel with local Claude
-discovery. A successful observation replaces that node's bounded display rows
+and Codex discovery. A successful observation replaces that node's bounded display rows
 and timestamp. A failed observation retains its last rows and records
 `PEER_TUNNEL_UNAVAILABLE`. `embassy status` reads that snapshot without SSH or
 provider I/O. Display is capped at 128 remote rows across all nodes; exact and
@@ -200,9 +237,12 @@ before provider setup, so only one broker can run.
 
 ## Private state reset
 
-Version 4 accepts only schema-6 `gateway-state.json`. It deliberately contains
-no 3.x converter or compatibility reader. An older or unknown schema refuses
-with `GATEWAY_STATE_SCHEMA_UNSUPPORTED`; invalid schema-6 bytes refuse with
+This release reads valid schema-6 `gateway-state.json` forward, treating every
+existing row as retained; new writes use schema 7. The retention marker is the
+only added field. Back up state before upgrading 4.2.0; no reset is required,
+but 4.2.0 refuses schema 7 and rollback requires the pre-upgrade backup.
+There is no 3.x converter. Schema ≤5 or unknown schemas refuse with
+`GATEWAY_STATE_SCHEMA_UNSUPPORTED`; malformed accepted schemas refuse with
 `CORRUPT_GATEWAY_STATE`. Refusal does not mutate the installed file.
 
 Reset procedure:
@@ -213,9 +253,11 @@ Reset procedure:
    serve process) and confirm it is stopped with `embassy service status`.
 3. Back up and move aside only `gateway-state.json` in that broker's state
    directory. Keep the valid `nodes.json`.
-4. Install 4.0.0, then run `embassy service install`.
-5. The v4 broker creates fresh schema-6 state.
-6. Re-register Codex tasks. Claude endpoints are recorded on discovery/use.
+4. Install the current discovery-enabled 4.x release, then run
+   `embassy service install`.
+5. The broker creates fresh schema-7 state.
+6. Let current Codex agents be discovered. Use fallback registration only for
+   non-native harnesses. Claude endpoints are recorded on discovery/use.
 
 All state produced by Embassy 3.x is unsupported by 4.x; preserve the matching
 old binary as well as its old state if rollback may be needed, and never run

package/docs/DELIVERY.md

@@ -10,8 +10,10 @@ Its `name@host` alias is a lookup index and display label. A send by name
 resolves once, before admission. Every later transition and reply uses the
 endpoint tuple; a rename or replacement cannot retarget old work.
 
-Codex callers must already be registered. A Claude caller is derived from its
-inherited native socket and recorded under the exact discovered session UUID.
+Codex callers must already be known through daemon discovery or fallback
+registration. Both paths identify the same endpoint kind by the exact native
+task identity. A Claude caller is derived from its inherited native socket and
+recorded under the exact discovered session UUID.
 The caller never supplies `--from`. A remote source is supplied by the trusted
 SSH peer. Its claimed host must be in `nodes.json`, and the message's source
 host must match that claim. The destination does not wait for a catalog poll
@@ -72,10 +74,17 @@ The receiving Claude session wakes through its native socket.
 ### Codex destination
 
 The broker creates a fresh bounded App Server operation, resumes the exact
-registered task without retaining returned history, prepares the input, then
-revalidates the registration and operation immediately before the write. The
-accepted operation remains attached until its terminal lifetime event so an
-active-turn STEER has a valid target.
+known task without retaining returned history, prepares the input, then
+revalidates the endpoint and operation immediately before the write. Dormant
+roots therefore wake through ordinary delivery. The accepted operation remains attached
+until its terminal lifetime event so an active-turn STEER has a valid target.
+
+Ordinary messages remain queued while the immediately observed task status is
+active. If another client starts a turn between Embassy's idle check and its
+write, the message enters that turn as steer text; the App Server response
+cannot distinguish this, so the receipt proves acceptance and lifetime only,
+not that a fresh turn started. The same residual race applies to fallback-
+registered tasks. Embassy does not use the App Server's native queue.
 
 An exact leading `STEER:` is special only from Claude to Codex. It is delivered
 through that exact accepted operation's `turn/steer` capability at the next
@@ -111,6 +120,9 @@ broker restart while its bounded retained row and both endpoint identities are
 still valid. Retirement, replacement, retention expiry, eviction, or state
 reset makes it unavailable. Conversation references are intentionally not
 stable across a reset.
+If an unused automatic endpoint is pruned from the discovery window, references
+bound to that identity refuse for the rest of their retention window, even if
+the native thread returns as a new endpoint. Re-address it by its current alias.
 
 ## Receipts and retirement
 

package/docs/GATEWAY-ARCHITECTURE.md

@@ -2,7 +2,7 @@
 
 ## Product contract
 
-Embassy connects live Claude Code sessions and registered Codex CLI tasks by
+Embassy connects live Claude Code sessions and Codex CLI agents by
 name, locally or across directly configured SSH gateways. All four provider
 pairs are supported. Sending is one `embassy send` command; receiving wakes the
 target through its native interface. A receipt proves delivery machinery, not
@@ -31,7 +31,7 @@ Claude/Codex CLI
                                       remote broker ledger
 ```
 
-There is one broker per login user and host. The broker owns one schema-6 JSON
+There is one broker per login user and host. The broker owns one schema-7 JSON
 document and one private control socket. It does not listen on a network port.
 launchd may supervise the same foreground `serve` entry point.
 
@@ -52,13 +52,18 @@ and restart. Retirement retains a bounded private hash of the native binding
 to fence immediate re-enrollment. After that evidence is evicted, a later
 registration gets a new ID; old replies and remote references cannot revive.
 
-Codex endpoints are explicitly registered by the task that inherits the exact
-task UUID. Claude endpoints are discovered by exact session UUID and recorded
+Codex endpoints are discovered as bounded metadata from the same-user App
+Server daemon. The immutable native thread UUID is their private identity;
+native names are mutable lookup aliases for automatic rows; explicitly registered
+rows keep the operator's alias. Only the 20 most recent roots are
+automatically listed, without publishing native IDs. Explicit registration by a
+task that inherits the exact UUID remains a fallback and reconciles with the
+same endpoint row. Claude endpoints are discovered by exact session UUID and recorded
 when a Claude caller or target is resolved. A same-UUID rename updates one
-endpoint; a different identity never inherits work. Two live Claude sessions
-may share a display name, but name resolution then refuses with
-`PEER_ALIAS_COLLISION`. An exact user-supplied Claude UUID can disambiguate
-selection without making UUIDs public output.
+endpoint; a different identity never inherits work. Live endpoints may share
+a display name, but name resolution then refuses with `PEER_ALIAS_COLLISION`.
+An exact user-supplied Claude UUID can disambiguate Claude selection without
+making UUIDs public output.
 Partial discovery cannot clear an observed collision. The bounded collision
 proof sets fail closed on overflow until a complete scan; exact UUID lookup
 remains available. Operator retirement can use `--endpoint <public-id>` when
@@ -69,8 +74,10 @@ and any local cache are bounded and memory-only; neither grants lookup or write
 authority. Remote endpoint rows contain opaque IDs and aliases, not native
 handles.
 
-`refresh` runs local Claude discovery and all configured catalog observations
-in parallel. Each successful node observation replaces its rows and timestamp.
+`refresh` runs local Claude and Codex discovery and all configured catalog
+observations in parallel. Codex discovery also follows bounded daemon metadata
+events and reconnects with a fresh bounded enumeration after daemon loss. Each
+successful node observation replaces its rows and timestamp.
 A failure retains the last timestamped rows with `PEER_TUNNEL_UNAVAILABLE`.
 The status projection reads this cache without network I/O and caps the combined
 remote display at 128 rows, reporting truncation. Routing still uses the owner
@@ -132,8 +139,8 @@ guessing. The live host lease is checked before a transaction, before
 persistence, and immediately before rename.
 
 No-op transactions write nothing. Unsupported or corrupt state refuses before
-mutation. Schema 6 is reset-only; no older loader or converter is linked into
-the v4 binary.
+mutation. Valid schema 6 reads forward with all existing rows retained; writes use 7.
+The only added field is the private retention marker. Schema ≤5 still needs a reset.
 
 ## Coordinator
 
@@ -172,10 +179,24 @@ native socket is still used for receive and reply wake-up.
 
 ### Codex operation
 
+One bounded App Server observer enumerates the recency top 20 unarchived root threads,
+combines loaded-state and lifecycle/name events, and retains only the metadata
+used by the endpoint directory. It drains unwanted notifications and
+unsubscribes from threads it is not actively brokering so observation does not
+pin them in memory. Window aging preserves pending identities and drops unused
+automatic rows without settlement or retirement. Explicit registrations remain
+retained across restart. `thread/closed` marks a root dormant, not retired.
+Archive/delete evidence and explicit retirement use existing settlement; operator
+retirement evidence suppresses rediscovery. Identity storage stays bounded.
+
 The Codex adapter creates a fresh App Server connection per operation, checks
-the current interface, resumes the exact registered thread with history
-excluded, and starts one turn carrying the bounded batch. Returned history and
-model output are not retained or forwarded.
+the current interface, resumes the exact known
+thread with history excluded when needed, and starts one turn carrying the
+bounded batch only after an immediate idle-status check. Returned history and
+model output are not retained or forwarded. While active, ordinary messages
+remain in Embassy's ledger. A competing client can start a turn between the
+idle check and write; the indistinguishable App Server response means the
+receipt proves acceptance and lifetime, not that Embassy started a fresh turn.
 
 An accepted operation remains tracked until its terminal lifetime notification.
 An exact leading Claude-to-Codex `STEER:` may use that same accepted
@@ -218,7 +239,7 @@ reset.
 
 ## Local control and CLI
 
-The private control protocol is version 5. Each connection carries one bounded
+The private control protocol is version 6. Each connection carries one bounded
 JSON request and one closed JSON response over the expected private Unix
 socket. A mutating request whose reply is lost after write reports
 `CONTROL_WRITE_OUTCOME_AMBIGUOUS`; the CLI does not retry it.
@@ -236,8 +257,9 @@ serve            service           peer-stdio
 `send` accepts exactly one of `--to` and `--conversation`; it has no `--from`.
 Human `status` is a rendering of the same closed body-free JSON shape. Its
 health word describes control/ledger health, local route rows expose their last
-native operation, and the federation section exposes only the last bounded
-catalog observation. `health` is a control-path probe. `check` creates temporary
+native operation, and Codex rows expose busy, waiting, idle, dormant or unknown
+status, without parent references or registration-origin labels. The federation section
+exposes only the last bounded catalog observation. `health` is a control-path probe. `check` creates temporary
 private loopback endpoints and uses the real ledger/coordinator/receipt path,
 then retires them; no provider or model is contacted. It is not a
 provider-readiness test.
@@ -261,7 +283,7 @@ Startup order is ownership-sensitive:
 1. load the private node inventory, or derive a transient first-boot default,
    and load configuration;
 2. acquire the fixed host-wide kernel lease;
-3. open and validate schema-6 state without changing the inventory;
+3. open and validate schema-7 state without changing the inventory;
 4. atomically install and reload the default inventory when first boot needs
    one;
 5. construct native and SSH adapters;
@@ -282,8 +304,8 @@ model interrupt.
 
 | Surface | Version | Compatibility policy |
 |---|---:|---|
-| Private state (`gateway-state.json`) | 6 | Reset only; older and unknown schemas refuse without mutation |
-| Private control (CLI ↔ broker) | 5 | CLI and broker must come from one installation |
+| Private state (`gateway-state.json`) | 7 | Reset only; older and unknown schemas refuse without mutation |
+| Private control (CLI ↔ broker) | 6 | CLI and broker must come from one installation |
 | Federation (`peer-stdio`) | 3 | Exact version and host handshake; no compatibility mode |
 | Consumed Claude peer protocol | 1 | Incompatible records are rejected in isolation |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-embassy",
-  "version": "4.2.0",
+  "version": "4.4.0",
   "description": "A local gateway for bidirectional messaging between Claude Code sessions and Codex tasks.",
   "license": "MIT",
   "repository": {
@@ -57,18 +57,23 @@
     "probe:codex-remote": "tsx scripts/probe-codex-remote.ts",
     "pretest": "npm run build",
     "start": "node dist/src/gateway/core-cli.js serve",
-    "test": "tsx --test test/*.test.ts",
+    "test": "tsx --test --test-timeout=120000 test/*.test.ts",
     "typecheck": "tsc -p tsconfig.json",
     "soak": "tsx --test test/soak/core-soak.test.ts"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "dependencies": {
+    "ink": "7.1.1",
+    "react": "19.2.8",
+    "string-width": "8.2.2",
+    "wrap-ansi": "10.0.1",
     "ws": "8.21.3"
   },
   "devDependencies": {
     "@types/node": "24.10.1",
+    "@types/react": "19.2.18",
     "@types/ws": "8.18.1",
     "tsx": "4.20.6",
     "typescript": "5.9.3"

package/skills/embassy-peer/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: embassy-peer
-description: Register a Codex task, find named Claude/Codex sessions, and send or reply through an installed Embassy gateway. Use for agent-to-agent messaging and receipts, not provider configuration or direct socket access.
+description: Find named Claude/Codex sessions, use fallback Codex registration when needed, and send or reply through an installed Embassy gateway. Use for agent-to-agent messaging and receipts, not provider configuration or direct socket access.
 ---
 
 # Embassy Peer Gateway
@@ -15,9 +15,9 @@ Healthy means the Embassy control socket and ledger respond; a passing check exe
 
 A client reads the private state directory and optional `nodes.json`, then connects to its private Unix socket. A sandboxed task needs read/write access to that directory. Follow denied-access guidance; do not relocate state or start a second broker to bypass it. If access was expected, verify `EMBASSY_STATE_DIR` names this user's own directory.
 
-To receive in Codex, use its managed standalone installation with its App Server daemon already running under the same macOS login; merely having a `codex` executable on PATH is insufficient, and Embassy does not install or start that daemon.
+To receive in Codex, use its managed standalone installation with its App Server daemon already running under the same macOS login; merely having a `codex` executable on PATH is insufficient, and Embassy does not install or start that daemon. The 20 most recent unarchived Codex roots appear automatically in `embassy status`, including dormant roots that resume on delivery. Sub-agents are excluded; explicit fallback registrations remain retained outside that window, including after a broker restart.
 
-Ask the live Codex CLI task to execute the following registration through its shell tool; an ordinary terminal lacks that task's inherited identity:
+For a harness without native daemon integration, ask the live Codex CLI task to execute this fallback registration through its shell tool; an ordinary terminal lacks that task's inherited identity:
 
 ```sh
 embassy register-codex --alias codex-reviewer@your-host
@@ -25,7 +25,7 @@ embassy register-codex --alias codex-reviewer@your-host
 
 Read `host` from the `nodes.json` that first boot created and use it as every local `@host` suffix; replace `your-host` with that exact value, not the example `studio` unless you explicitly chose it. `nodes.json` lives inside `EMBASSY_STATE_DIR` when set; otherwise it lives in `$XDG_STATE_HOME/agent-embassy`, or `~/.local/state/agent-embassy` when `XDG_STATE_HOME` is unset; every client shell must use the same state-directory configuration captured by the installed service.
 
-The CLI reads inherited `CODEX_THREAD_ID`; never supply, print, or guess it. Registration performs no provider I/O. Claude callers are identified from inherited `CLAUDE_CODE_MESSAGING_SOCKET` and live registry evidence on first use; there is no separate Claude registration command.
+The CLI reads inherited `CODEX_THREAD_ID`; never supply, print, or guess it. Discovery and fallback registration produce the same endpoint kind and identity. Registration performs no provider I/O. Claude callers are identified from inherited `CLAUDE_CODE_MESSAGING_SOCKET` and live registry evidence on first use; there is no separate Claude registration command.
 
 For `CALLER_IDENTITY_CONFLICT`, strip only the unwanted identity at the call site: `env -u CLAUDE_CODE_MESSAGING_SOCKET embassy …` for Codex, or `env -u CODEX_THREAD_ID embassy …` for Claude. Do not read either value or restart the broker to repair the caller's environment.
 
@@ -33,7 +33,7 @@ Ellipses (`...` or `…`) stand for the intended command and arguments; `conv_RE
 
 ## Address, send, reply
 
-`embassy status --json` returns metadata under `.result`: owned routes, recent delivery states, retirements and last operation outcomes. It includes no bodies or native IDs. Human terminal rendering is not a parser contract. `embassy refresh` performs live Claude discovery; run it only when authorized. Named sends resolve directly, including over configured SSH, without requiring prior catalog polling at the destination.
+`embassy status --json` returns metadata under `.result`: owned routes, recent delivery states, retirements and last operation outcomes. It includes no bodies or native IDs. Human terminal rendering is not a parser contract. `embassy refresh` performs live Claude and Codex discovery; run it only when authorized. Named sends resolve directly, including over configured SSH, without requiring prior catalog polling at the destination.
 
 Names are lookup indexes, not identities. Stop on `PEER_ALIAS_COLLISION` rather than choosing a session. A Claude UUID may be used as `--to` only when user-supplied; do not discover or echo native IDs. A renamed or replaced endpoint never inherits work addressed to another identity.
 
@@ -84,7 +84,7 @@ The waiter is bounded by the deadline plus three seconds. A found result has `st
 
 Do not resend an ambiguous or unconfirmed delivery. `CONTROL_WRITE_OUTCOME_AMBIGUOUS` also means the operation may have applied: inspect status, do not repeat it. Explicit replies are new messages, not automatic forwarding of Codex output.
 
-Receiving is native: Claude's socket mailbox or Codex's accepted turn. Agents do not poll inbound mail. Ordinary Codex work queues while the task is busy; a bounded backlog is packed into one wake with separate identities, provenance, and receipts. Capacity and deadlines still apply.
+Receiving is native: Claude's socket mailbox or Codex's accepted turn. Agents do not poll inbound mail. Ordinary Codex work queues while the task is observed busy; a bounded backlog is packed into one wake with separate identities, provenance, and receipts. A competing client can start a turn after Embassy's idle check, causing an ordinary message to enter that turn as steer text; the provider response cannot distinguish the race, so the receipt proves acceptance and lifetime, not fresh-turn creation. Capacity and deadlines still apply.
 
 Only when explicitly asked to steer, a Claude sender may start the body with exact `STEER:` for an active Codex recipient. Embassy uses that exact turn's same-session capability at the next tool-call boundary, never interrupts, and keeps the three-steer cap and global kill switch. A cleanly unavailable boundary leaves the message queued. Never synthesize STEER, answer approvals, or change a sandbox to force delivery.