Embassy v4.7.0

Embassy 4.7.0 — retiring your own route is no longer a one-way door

A Codex agent that retired its own route could not come back for 24 hours: the retirement fenced the thread's identity so that automatic discovery would not quietly resurrect it, and that fence also blocked the agent's own explicit re-registration. Several real incidents followed the same script — an agent "cleans up" its registration, cancels its own queued messages, then cannot register again.

Now an explicit embassy register-codex from the same live thread lifts the fence. Embassy takes a fresh, exact observation of that thread from the managed App Server (loaded and live, idle or busy), performs no resume, turn or steer, and commits atomically: the old retirement evidence stays, the retirement must not have changed during the read, and the thread gets a new endpoint ID. Automatic discovery still cannot resurrect a retired thread, old deliveries and conversation references never retarget the new ID, and --succeeds of a retired predecessor works only for the thread that owned it. embassy retire now says what it does: it cancels queued work in both directions, and a retired Codex thread stays out of discovery until it registers itself again (a retired Claude session reappears on its own, as since 4.6.0).

RPC_REJECTED explained — when the App Server refuses a wake, the route's last operation now carries a bounded detail: the numeric JSON-RPC code and which call was refused (resume, start or steer), kept in memory only, never error text, bodies or thread IDs. The hint distinguishes a refused resume (another host owns the thread, or the session predates a daemon restart) from a refused turn.

Which Codex agents can receive — the docs and the packaged skill now say it plainly: sessions attached to the managed App Server daemon (the Codex CLI, codex exec) receive and are woken; Codex running inside other hosts, such as the ChatGPT desktop app, can send but cannot be woken. They also say never to retire your own route as a troubleshooting step.

Protocol — private control protocol is now 8 for the new status detail. Update the CLI and broker together: npm install -g agent-embassy@4.7.0 then embassy service install. State schema 7 and federation protocol 3 are unchanged; no reset.

Tested with offline suite 444/444 on Node 22 (macOS and Ubuntu); 126 focused tests over the recovery path, fake-wire refusal details and the closed projection; an adversarial review; and a live drill on this Mac.

Embassy v4.6.2

Embassy 4.6.2 — a wrong alias says so

embassy register-codex refused aliases that did not fit the rule — no codex- prefix, the wrong host, or the documentation's your-host placeholder used literally — under INVALID_GATEWAY_CONFIGURATION, which sent agents and operators to look for a broker problem that did not exist.

Now those refusals return INVALID_ALIAS with a hint that states the rule and the actual local host: Codex aliases are codex-<name>@<host>, lowercase letters, digits, underscore and dash before the @ (at most 32 characters including the prefix), the host from nodes.json after it. A malformed alias string is classified the same way at the request decoder, so one mistake produces one code. Genuine configuration failures keep INVALID_GATEWAY_CONFIGURATION. The accepted grammar is unchanged. README (both languages) and the packaged skill state the rule beside the example.

Upgrading — install and restart the broker; no state or protocol change.

Tested with offline suite 431/431 on Node 22 (macOS and Ubuntu), including a real CLI-to-broker fixture for each alias mistake and a real configuration failure.

Embassy v4.6.1

Embassy 4.6.1 — renamed sessions can talk again

When two Claude Code sessions share a name, Claude renames the second one to "name (2)". Embassy's registry parser rejected any session name with a space or parentheses, so such a session could neither send (every send failed with REGISTRY_INVALID_SCHEMA) nor be discovered. Nothing was wrong with the broker or its state; resetting the ledger would not have helped.

Now the session name is treated as a display label: any non-empty name up to 64 characters is accepted, and the public alias is derived from it the same way for endpoints, warnings and delivery checks — "compressor-pm (2)" becomes compressor-pm-2@host. A name with no usable letters or digits gets a stable claude-<hash> alias. Two sessions whose names normalise to the same alias are still refused with PEER_ALIAS_COLLISION rather than merged. Genuinely malformed records (missing fields, wrong types, wrong peer protocol) are still refused.

Upgrading — install and restart the broker; no state or protocol change. Update the CLI in each shell too, as with 4.6.0.

Tested with offline suite 429/429 on Node 22 (macOS and Ubuntu), including a real-registry fixture that sends and replies both ways as "compressor-pm (2)" and as a punctuation-only name.

Embassy v4.6.0

Embassy 4.6.0 — a restarted Claude session keeps its route

Restart a Claude Code session (to load an MCP server, say) while the old process is still alive, and until now Embassy saw two registry records for one session and dropped both: the session could neither be reached nor send, and every failure read "route unregistered". Retiring the route to fix it made things worse, locking that session out for a day.

Now — when two live processes share a session UUID, Embassy binds to the newest reachable process, revalidates the exact record before every write, and reports CLAUDE_SESSION_DUPLICATE in status, refresh and send with the selected and other PIDs and a reason: an older process is stale (exit it), the newest did not answer a probe (check it before exiting anything), or none answered. Sends keep working meanwhile. Daemons never displace an interactive session or gain caller eligibility.

Retiring a Claude route now fences only the old endpoint ID: a live session that reappears gets a fresh ID immediately; old deliveries and old conversation replies never retarget it. Codex retirement and successor semantics are unchanged.

Protocol — private control protocol is now 7 (bounded optional warnings). Update the CLI and broker together: npm install -g agent-embassy@4.6.0 then embassy service install. State schema 7 and federation protocol 3 are unchanged; no reset.

Documented limits — duplicate detection during a write is bounded to a 4096-entry registry window; siblings beyond it are unobserved until the next refresh.

Tested with offline suite 426/426 on Node 22 (macOS and Ubuntu); an end-to-end fixture with real registry files and sockets for the duplicate-process and retire-then-reappear scenarios; an adversarial review whose three findings were fixed and re-verified; a live drill on two Macs reproducing the incident.

Embassy v4.5.2

Embassy 4.5.2 — the demo, designed

No code change from 4.5.1. The video at the top of both READMEs is remade design-first: a light palette around the mark's amber, the recorded terminals set into the page as dispatch cards marked RECORDED, an illustrated SSH scene marked as such, and a new live exchange — a Claude Code session asks a Codex agent to review a login-flow change, the agent reads the real diff and names the risk, and the reply arrives back in Claude with both receipts settled. Nothing on screen is invented. The same file is attached to this release as embassy-demo.mp4; the Remotion project under demo/ is updated and stays out of the package.

Upgrading — nothing to do.

Tested with offline suite 414/414 on Node 22 (macOS and Ubuntu).

Embassy v4.5.1

Embassy 4.5.1 — the skill, compacted; README in Chinese

The embassy-peer skill that embassy skills install places in Claude Code and Codex CLI is rewritten around what an agent actually does: see who is there, send by name, reply with the exact hinted command, receive natively, check a delivery's receipt, and what to do when a call is refused. About half the previous length; every specific claim re-verified against the code. Run embassy skills install after upgrading to refresh both copies.

README now has a Simplified Chinese edition (README_CN.md) with a language switcher, a Status section written as two short lists (what works today, what Embassy deliberately does not promise), and the final cut of the demo video. The operations, configuration and security docs describe embassy skills install|status; the 3.x migration procedure is gone.

Demo — the video at the top of the README is the v5 cut: illustrated agents, one idea per scene, the real moments where Codex and Claude receive a message, an illustrated SSH diagram, and the two real receipts. The same file is attached to this release as embassy-demo.mp4.

Upgrading — install and restart the broker, then embassy skills install. No state change.

Tested with offline suite 414/414 on Node 22 (macOS and Ubuntu).

Embassy v4.5.0

Embassy 4.5.0 — skills install, and a README worth reading

embassy skills install puts the packaged embassy-peer skill where Claude Code and Codex CLI look for it (~/.claude/skills, ~/.codex/skills), idempotently: it installs what is absent, updates what is stale, leaves identical copies and your other files alone, and refuses symlinked or foreign-owned targets. embassy skills status reports absent, current or stale per provider; --claude-only / --codex-only scope either command. Neither contacts the broker. Agents still never install skills themselves; the operator runs this once per machine.

README is rebuilt as a newcomer's path under eight screens: the mark and a one-sentence definition, live badges, a five-step Quick start whose second step is the new command, a Status section stating what is proven and what is bounded by design, and one-paragraph summaries that link into the docs. Operational detail moved to docs/OPERATIONS.md. The 3.x upgrade section is gone.

Demo — a 40-second video at the top of the README, recorded from live sessions: a Claude Code session sends to a Codex agent by name, the Codex task wakes with its provenance envelope and replies through the same command, the reply arrives in Claude natively, one more Mac appears over SSH, and both receipts settle in the ledger. The Remotion project under demo/ produced it and is not part of the package. The video is attached to this release.

Upgrading — install and restart the broker, then run embassy skills install to refresh the skill copies; no state change.

Tested with offline suite 414/414 on Node 22 (macOS and Ubuntu); the skills command drilled against a fixture home and a symlinked target.

Embassy v4.4.2

Embassy 4.4.2 — the demo

A 12-second GIF at the top of the README shows the real thing: a Claude Code session sends to a Codex agent by name, the Codex task wakes with its provenance envelope and runs the emitted reply command, and the reply arrives in Claude natively, with both receipts settling in the ledger. It was recorded from live sessions on an installed 4.4.1 with no fabricated terminal text; conversation references and native identifiers were masked. The 55-second 1080p video is attached to this release when available. The Remotion project and recorder are under demo/ and are not part of the npm package.

Small changes — the header's Codex discovery age shows "just now" below one second; the peer skill's default Codex prompt says agents are discovered automatically and registration is only for a non-native harness; the service-command test uses a short socket root on macOS.

Upgrading — install and restart the broker; no state change.

Tested with offline suite 408/408 on Node 22 (macOS and Ubuntu).

Embassy v4.4.1

Embassy 4.4.1 — documentation

No code change from 4.4.0. The shipped documentation now describes the current product in the present tense: README is a newcomer's path (install, start the broker, see the agents, send, reply, federate, retire) with embassy tui as the daily view; history scaffolding and references to removed features are gone except in the upgrade sections kept for 3.x users; protocol and schema numbers are stated once each and match the source (private state schema 7 with the schema-6 forward read, private control 6, federation 3); issue and pull-request templates match the CLI that ships. Every claim was traced to code before release.

Upgrading — install and restart the broker; no state change.

Tested with offline suite 408/408 on Node 22 (macOS and Ubuntu).

Embassy v4.4.0

Embassy 4.4.0 — the terminal, designed

4.4 changes what you see, not what Embassy does. The operator TUI is rebuilt on Ink, the same terminal UI framework Claude Code runs on, and every screen was redrawn to be scanned rather than read.

What is different on screen — endpoints grouped the way the Codex agents view groups them: Working, Waiting, Faulted, Ready, Dormant, Not reporting, Cached, with counts, and a column header (State, Endpoint, Type, Queue, Outcome); one colour per state, used the same way everywhere, with the state word always beside it so nothing depends on colour alone; bold names, dim metadata, a real column grid with aligned counts and display-width padding so wide-character names keep the grid; the selected row is one highlight bar, and reverse video means selection and nothing else; the outcome column gets the width, so a failed delivery's safe code is readable at 80 columns; the list scrolls by rendered lines, never orphans a group header, and marks clipped rows with "↑ N more" / "↓ N more"; host tabs with a health mark, section tabs, and a persistent footer with the keys for the current mode; centred, bordered dialogs for retirement and token entry, the retirement dialog showing host, alias, the full endpoint ID and the settlement consequences in red with a distinct confirm key; the header fixed in place so nothing jumps between polls. Unreachable and stale states are loud and say what to do, and every empty list says why it is empty (broker unreachable with its code, no endpoints registered, no deliveries yet, no retirements). Failed counts stay red in the tab bar even when the tab is not focused.

What is the same — every key, every action, every honesty line ("not a provider readiness proof", the stale age, "up to 20 most recent"), the polling and action serialization, the exact-ID retirement guard, and the metadata-only rule. Without an interactive terminal, tui prints the plain status text with no escape codes. NO_COLOR removes all styling and keeps the screen interactive.

Requirement change — Embassy now requires Node 22 or newer. Node 20 is no longer supported.

Footprint — Ink 7.1.1, React 19.2.8, wrap-ansi and string-width, pinned; no native modules (the layout engine is WebAssembly); loaded only when embassy tui runs.

Upgrading from 4.3.0 — install and restart the broker; no state reset.

Tested with (m5dev and a laptop over SSH, 2026-09-06): the live TUI against both brokers at 80×24, 100×30 and 140×45 on dark and light palettes, NO_COLOR and plain output verified byte-clean, and two independent operator-perspective reviews of every screen, whose findings were folded in before release. Offline suite 408/408.