agent-embassy 4.2.0 → 4.3.0

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.3.0",
   "description": "A local gateway for bidirectional messaging between Claude Code sessions and Codex tasks.",
   "license": "MIT",
   "repository": {
@@ -57,7 +57,7 @@
     "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"
   },

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.