agent-embassy 4.4.0 → 4.4.1

package/CHANGELOG.md

@@ -4,6 +4,11 @@ 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/).
 
+## [4.4.1] - 2026-09-06
+
+### Changed
+- Documentation describes the current product; historical scaffolding removed.
+
 ## [4.4.0] - 2026-09-06
 
 ### Changed

package/CONTRIBUTING.md

@@ -21,7 +21,7 @@ and must never run in CI.
 
 ## Core shape
 
-Keep changes inside the v4 architecture:
+Keep changes inside the shipped architecture:
 
 - `ledger.ts` owns pure synchronous state transitions;
 - `owned-state.ts` owns private atomic persistence;

package/README.md

@@ -1,6 +1,6 @@
 # Embassy
 
-Embassy lets live Claude Code sessions and Codex CLI tasks message one another
+Embassy lets live Claude Code sessions and Codex CLI agents message one another
 by name, on one Mac or across user-owned Macs reached through SSH. The broker
 wakes the receiving agent through its native interface; agents do not poll.
 Claude→Claude, Claude→Codex, Codex→Claude, and Codex→Codex all use the same
@@ -15,15 +15,17 @@ identity, so a rename or replacement never silently retargets queued work.
 
 - macOS and Node.js 22 or newer.
 - Claude Code installed for the Claude sessions you use.
-- To receive in Codex, use its managed standalone installation with its App
-  Server daemon already running under the same macOS login. Embassy discovers
-  its 20 most recent unarchived root agents automatically, but does not install, start or
-  update that daemon; merely having a `codex` executable on PATH is
+- To receive in Codex, its managed standalone installation with the App Server
+  daemon already running under the same macOS login. Embassy discovers the
+  20 most recent unarchived root agents automatically, but does not install,
+  start or update that daemon; merely having a `codex` executable on PATH is
   insufficient.
 - A private `nodes.json` when choosing an explicit host name or federating;
   first single-machine boot creates one from the short hostname.
 - Key-based, non-interactive SSH between configured machines when federating.
 
+## Install
+
 Install one copy with one package manager and verify what the shell resolves:
 
 ```sh
@@ -32,94 +34,119 @@ which -a embassy
 embassy --version
 ```
 
-The launchd service records the absolute installation path used by
-`embassy service install`. After replacing or removing that installation, run
-the install command again.
-
-`embassy service install` starts the per-user launchd agent immediately and
-arranges login startup; use the same command to reload broker configuration or
-start a stopped installation, and use `embassy service uninstall` to stop and
-unload it.
+## Start the broker
 
-The agent uses launchd's crash-only keepalive policy. A
-verified `SIGABRT` crash relaunches it. A clean exit, boot refusal, `SIGTERM`,
-or deliberate `kill -9` leaves it stopped; inspect `embassy service status`
-and run `embassy service install` deliberately rather than assuming every
-signal restarts it.
-
-## Quickstart
+```sh
+embassy service install
+embassy health
+```
 
-For an explicit host name or federation, create `nodes.json` before starting
-the broker. `host` is this machine's name; `nodes` lists directly reachable
-Embassy hosts.
+`embassy service install` starts the per-user launchd agent immediately and
+arranges login startup; run the same command again to reload broker
+configuration, to start a stopped installation, or after replacing or removing
+the installation (the service records the absolute installation path). Use
+`embassy service uninstall` to stop and unload it. `embassy serve` is the
+foreground alternative.
+
+The agent uses launchd's crash-only keepalive policy. A verified `SIGABRT`
+crash relaunches it. A clean exit, boot refusal, `SIGTERM`, or deliberate
+`kill -9` leaves it stopped; inspect `embassy service status` and run
+`embassy service install` deliberately rather than assuming every signal
+restarts it.
+
+`health` means the Embassy control socket and ledger respond. It is not a
+provider readiness proof: it does not show that any Claude session or Codex
+task can receive or answer a message.
+
+### Host name and state directory
+
+Every local alias ends in `@host`, where `host` is the value in `nodes.json`.
+On first single-machine boot without that file, Embassy derives a lower-case
+name from the short hostname and atomically writes an empty-node inventory; it
+never rewrites a present file. Read `host` from that file and use it as every
+local `@host` suffix; the examples use `@studio` only because they chose
+`host: studio`.
+
+To choose an explicit host name or to federate, create `nodes.json` before
+starting the broker. `host` is this machine's name; `nodes` lists directly
+reachable Embassy hosts:
 
 ```json
 {"version":1,"host":"studio","nodes":[]}
 ```
 
-`nodes.json` lives inside `EMBASSY_STATE_DIR` when set; otherwise it lives in
+`nodes.json` lives inside `EMBASSY_STATE_DIR` when set; otherwise 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. Create the private state
-directory before saving the example, and set directory mode 0700 and
-`nodes.json` mode 0600 before installing the service.
-
-The file must be owned by the current user, mode 0600, inside the private
-mode-0700 state directory. If it is absent on first single-machine boot, Embassy derives a
-lower-case name from the short hostname and atomically writes the equivalent
-empty-node file. It never rewrites a present inventory.
+`XDG_STATE_HOME` is unset. Create the private state directory first, set it to
+mode 0700 and `nodes.json` to mode 0600, and install the service afterwards.
+Every client shell must use the same state-directory configuration captured by
+the installed service.
 
-Install the supervised broker:
+## See the agents
 
 ```sh
-embassy service install
-embassy health
+embassy tui       # the daily view
+embassy status    # one text snapshot
 ```
 
-Global npm installation includes `skills/embassy-peer` under the
-`agent-embassy` package in `npm root -g`; the operator can copy that entire
-folder into `~/.codex/skills/` and `~/.claude/skills/`, then ask each agent to
-use it, or provide the shown commands directly to the agent's shell tool.
+`embassy tui` is the daily view: an Ink-based terminal client (Node 22+) that
+shows the local broker and each direct host in `nodes.json`, with endpoints
+grouped by state, deliveries newest first, retirements, and action results.
+`embassy status` prints the same snapshot once as text.
 
-Read `host` from the `nodes.json` that first boot created and use it as every
-local `@host` suffix; the examples use `@studio` only when you explicitly chose
-`host: studio`, not as a universal alias suffix.
+Codex agents appear automatically. Embassy observes the same-user Codex App
+Server daemon and lists its 20 most recent unarchived root agents by their
+current public names; dormant agents remain addressable and wake on delivery.
+Only head agents are endpoints: sub-agents are never discovered or displayed.
+Native task IDs, previews and history never appear in Embassy output. If no
+Codex agent appears, check that the Codex daemon is running under this login;
+Embassy never starts it.
 
-The 20 most recent Codex root agents appear automatically from the same-user App Server daemon. Run
-`embassy status` to see their current public names; dormant agents remain
-addressable and wake on delivery. Native task IDs, previews and history never
-appear in Embassy output.
+Claude sessions are discovered and recorded by exact native identity when a
+Claude caller sends or when a named Claude target is resolved. No helper or
+native advertisement process is installed. To find a Claude session's current
+name, run `embassy refresh` (authorized live discovery) followed by
+`embassy status --json`, or use the exact current name that session supplies.
 
-For a harness without native daemon integration, ask the live Codex CLI task
-to execute this fallback registration through its shell tool; an ordinary
+For a harness without native daemon integration, registration is the fallback.
+Ask the live Codex CLI task to run this through its own shell tool; an ordinary
 terminal lacks that task's inherited identity:
 
 ```sh
 embassy register-codex --alias codex-reviewer@studio
 ```
 
-Claude sessions are discovered and recorded by exact native identity when a
-Claude caller sends or when a named Claude target is resolved. No helper or
-native advertisement process is installed.
+The `skills/embassy-peer` folder ships in the `agent-embassy` package under
+`npm root -g`. Copy that entire folder into `~/.codex/skills/` and
+`~/.claude/skills/` and ask each agent to use it, or hand the agent the commands
+shown here directly.
+
+## Message an agent
 
-After `codex-reviewer@studio` appears in status, ask the live Claude Code session
-to run `embassy send --to codex-reviewer@studio` with 'Please review the change
-and reply using the supplied Embassy hint' on stdin; execute this through the
-agent's shell tool, not an unrelated terminal. The sender is inferred from the calling session:
+Ask the live Claude Code session to run `embassy send --to codex-reviewer@studio`
+with the message body on stdin, through the agent's shell tool rather than an
+unrelated terminal. The sender is inferred from the calling session; `send`
+takes exactly one of `--to` or `--conversation` and has no `--from`:
 
 ```sh
 printf '%s\n' 'Please review the change and reply using the supplied Embassy hint' |
   embassy send --to codex-reviewer@studio
 ```
 
-The receiving Codex task sees a broker hint such as:
+A successful send returns `result.deliveryToken` and a conversation reference.
+The receipt proves transport, not comprehension: acceptance means the broker
+owns the delivery, not that a model read or understood the body.
+
+## Reply
+
+The receiving agent sees a broker hint such as:
 
 ```text
 <embassy-reply-hint conversation="conv_EXACT_REFERENCE" ...>Reply by running `embassy send --conversation conv_EXACT_REFERENCE` with the reply body on stdin.</embassy-reply-hint>
 ```
 
-It must execute the exact received command to send the reply, because ordinary
-Codex final output is not forwarded automatically and `conv_example` is not a
+It must execute the exact received command to send the reply. Ordinary Codex
+final output is not forwarded automatically, and `conv_example` is not a
 usable reference:
 
 ```sh
@@ -127,10 +154,6 @@ printf '%s\n' 'Review complete.' |
   embassy send --conversation conv_example
 ```
 
-For a Claude target, find the current Claude target name with an authorized
-`embassy refresh` followed by `embassy status --json`, or use the exact current
-name supplied by that session.
-
 Conversation references are identity-bound, are not aliases, and may survive a
 broker restart while their retained ledger row and both exact endpoints remain
 valid. They stop resolving after retirement, replacement, expiry, eviction, or
@@ -147,6 +170,12 @@ The durable write phases are `queued`, `reserved`, `armed`, `accepted`, and
 `terminal`. Work known not to have been written may return to the queue. An
 uncertain armed or accepted write is never replayed.
 
+Ordinary Codex delivery starts only after an immediate idle observation. A
+competing client can start a turn between that observation and Embassy's
+write; the App Server response cannot distinguish the resulting steer from a
+fresh turn, so the race is undetectable on the wire and the receipt proves
+acceptance and lifetime, not fresh-turn creation.
+
 An exact leading `STEER:` from Claude to Codex targets the active accepted
 Codex operation at its next safe tool-call boundary. It never interrupts a
 generation. If that boundary is cleanly unavailable, the message remains in
@@ -155,26 +184,21 @@ the ordinary bounded queue. The global kill switch is
 
 See [Delivery semantics](docs/DELIVERY.md) for the phase and receipt contract.
 
-## Multiple machines
-
-Install Embassy and run `embassy service install` on both Macs; for `studio`
-and `laptop`, use `{"version":1,"host":"studio","nodes":["laptop"]}` on
-studio and `{"version":1,"host":"laptop","nodes":["studio"]}` on laptop,
-with each peer name matching both the remote inventory's `host` and a working
-SSH destination or `~/.ssh/config` Host alias.
+## Federate
 
-After changing a running broker's inventory, reload it with
-`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.
+Connectivity comes first. Install Embassy and run `embassy service install` on
+both Macs; for `studio` and `laptop`, use
+`{"version":1,"host":"studio","nodes":["laptop"]}` on studio and
+`{"version":1,"host":"laptop","nodes":["studio"]}` on laptop, 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`.
 
 From studio, verify the remote command environment with
 `/usr/bin/ssh laptop 'which -a embassy; node --version; embassy --version'`,
 then verify the corresponding direction from laptop; both remote Node and
-Embassy must resolve without an interactive shell or password prompt.
-
-The local broker launches:
+Embassy must resolve without an interactive shell or password prompt. The local
+broker launches:
 
 ```text
 /usr/bin/ssh <node> embassy peer-stdio
@@ -189,83 +213,83 @@ queue and trusts the peer's source identity, so first contact does not wait
 for a destination catalog poll. Catalogs are bounded memory-only observations,
 never routing authority.
 
+Once `codex-reviewer@laptop` appears from the Codex daemon on laptop (or from
+fallback registration there), the Claude session on studio sends with
+`embassy send --to codex-reviewer@laptop` exactly as it would locally.
+
 `embassy refresh` observes local Claude and Codex sessions and every configured
-SSH catalog in parallel. `status` performs no provider or network I/O: it shows the
-last per-node catalog rows and observation time, retains the last rows when a
-later refresh fails, and labels that node `PEER_TUNNEL_UNAVAILABLE`. At most 128
-remote rows are displayed; truncation is explicit. Named and exact sends still
-ask the owner directly.
+SSH catalog in parallel. `status` performs no provider or network I/O: it shows
+the last per-node catalog rows and observation time, retains the last rows when
+a later refresh fails, and labels that node `PEER_TUNNEL_UNAVAILABLE`. At most
+128 remote rows are displayed; truncation is explicit. Named and exact sends
+still ask the owner directly.
+
+In `embassy tui`, use `[` / `]` to select a host: the local pane polls every
+second, while independent SSH clients read each remote's
+`embassy status --json` about every five seconds. Each pane reports its own
+broker's health, queue and last operations, not another broker's cached
+catalog, and one hanging host cannot block the other panes. Remote actions run
+the same CLI there over the configured non-interactive SSH; remote retirement
+requires the host plus full endpoint ID confirmation and a fresh supported
+owner snapshot. Disconnected panes are marked stale; an uncertain action is
+never automatically retried. Without an interactive terminal, `tui` prints the
+local status text once and exits without SSH.
+
+## Retire
 
-## Operations
+```sh
+embassy retire --alias codex-reviewer@studio
+embassy retire --endpoint <public-id>
+```
 
-Retain `result.deliveryToken` from the successful send response in your current
-session and substitute that exact value for the example; status shows aggregate
-route queues and recent delivery metadata but cannot recover a lost delivery
-token or distinguish identical sends by token.
+`retire` removes one local endpoint identity and settles all of its
+outstanding work: queued and reserved work is cancelled, armed work becomes
+ambiguous, and accepted work becomes unconfirmed. Remote endpoints must be
+retired on their owning host. If departed sessions share a name, retire one
+exactly with `--endpoint` using its opaque public ID from `result.routes`;
+`--alias` and `--endpoint` are mutually exclusive.
 
-The ellipses (`...` or `…`), `conv_example`, `dlv_example`, and `<public-id>`
-are substitutions, not runnable literal values: supply the indicated command
-arguments, exact received conversation reference, exact returned delivery
-token, or public endpoint ID respectively.
+## Operations
 
 ```sh
-embassy status
 embassy status --json
-embassy tui                                # interactive operator client
 embassy refresh
 embassy delivery-status --token dlv_example
 embassy wait-delivery --token dlv_example
-embassy retire --alias codex-reviewer@studio
 embassy check
 embassy service status
-embassy serve                              # foreground alternative
 ```
 
+`conv_example`, `dlv_example`, and `<public-id>` are substitutions, not
+runnable literal values: supply the exact received conversation reference,
+exact returned delivery token, or public endpoint ID respectively. Retain `result.deliveryToken` from
+the successful send response in your current session; status shows aggregate
+route queues and recent delivery metadata but cannot recover a lost delivery
+token or distinguish identical sends by token.
+
 `status` reports the broker ledger, queue depth, recent message outcomes,
 retirements, each local route's last native operation, and the last bounded SSH
 catalog observation. It does not claim that an idle provider is ready.
-
-Use `delivery-status` to inspect that delivery's phase, pending age or terminal
-code; use `status --json` to identify a stranded local route, and retire it with
-`retire --alias` using its alias or `retire --endpoint` using its public id from `result.routes`,
-understanding that this settles all outstanding work for that endpoint.
-
-`embassy tui` shows the local broker and each direct host in `nodes.json` in one
-terminal. Use `[` / `]` to select a host: local status polls every second, while
-independent SSH clients read each remote's `embassy status --json` about every
-five seconds. Each pane reports its own broker's health, queue and last
-operations—not another broker's cached catalog. One hanging host cannot block
-the other panes. No message bodies are displayed.
-On-screen keys refresh, check, look up a token or retire on the selected host.
-Remote actions run the same CLI there over configured non-interactive SSH;
-retirement requires HOST + full endpoint ID confirmation and a fresh supported
-owner snapshot. An uncertain action is never automatically retried.
-Disconnected views are marked stale; actions are never automatically retried.
-Without an interactive terminal, `tui` prints local status text once and exits
-without SSH. Unsupported remote response shapes are not guessed; a lazy
-`embassy --version` read identifies only that remote CLI, not its broker version.
-Deliveries are newest-admitted first, with faults distinguished from successful
-delivery. Use 1–4 or Tab to change sections, g/G for first/last row, and Esc to
-return from an action result. Token lookup echoes only the token you type;
-tokens are not added to the general delivery list. Retirement confirmation
-shows the full endpoint identity and the consequences for unsettled work.
-
 Machine output is one closed JSON line shaped as
 `{"ok":true,"command":"status","result":{...}}`; route rows are therefore at
 `.result.routes`. A terminal `embassy status` renders the same body for a
-person, while `--json` keeps the envelope.
+person, while `--json` keeps the envelope. No message body appears in either.
+
+Use `delivery-status` to inspect one delivery's phase, pending age or terminal
+code; `wait-delivery` polls until it is terminal or the bounded wait ends.
 
 `check` is a broker-only loopback through the real ledger and coordinator. It
 proves local control, persistence, routing, and receipt handling without
-contacting a live Claude or Codex agent. Healthy means the Embassy control
-socket and ledger respond; a passing check exercises only broker loopback, so
-neither proves that a Claude session or Codex task can receive or answer a message.
+contacting a live Claude or Codex agent. A passing check exercises only broker
+loopback, so neither `health` nor `check` proves that a Claude session or Codex
+task can receive or answer a message.
 
-`retire` removes one local endpoint identity. Queued and reserved work is
-cancelled, armed work becomes ambiguous, and accepted work becomes unconfirmed.
-Remote endpoints must be retired on their owning host.
-If departed sessions share a name, retire one exactly with
-`embassy retire --endpoint <public-id>` using its opaque ID from status.
+In the TUI, on-screen keys refresh, check, look up a token or retire on the
+selected host. Use 1–4 or Tab to change sections, `g`/`G` for the first or last
+row, and Esc to return from an action result. Token lookup echoes only the
+token you type; tokens are not added to the general delivery list. Retirement
+confirmation shows the full endpoint identity and the consequences for
+unsettled work. No message bodies are displayed.
 
 ## Safety
 
@@ -278,36 +302,30 @@ If departed sessions share a name, retire one exactly with
 - Embassy launches `/usr/bin/ssh` directly without a local shell, in batch mode
   with forwarding disabled; the remote account must resolve the fixed
   `embassy peer-stdio` command in its non-interactive SSH environment.
-- Healthy means the Embassy control socket and ledger respond; a passing check
-  exercises only broker loopback, so neither proves that a Claude session or
-  Codex task can receive or answer a message.
+- Embassy never changes a Codex approval or sandbox policy and never answers
+  an approval.
 
 See [Security](SECURITY.md), [Configuration](docs/CONFIGURATION.md), and
 [Architecture](docs/GATEWAY-ARCHITECTURE.md).
 
 ## Upgrading to 4.x
 
-Codex discovery reads valid schema 6 forward and writes schema 7, adding only a
-private retention marker; existing 4.2.0 endpoints stay retained. No reset is
-needed for 4.2.0. Back up `gateway-state.json` before upgrading: 4.2.0 refuses
-schema 7, so rollback requires that pre-upgrade backup. Private control changes
-5→6; upgrade CLI and broker together. There is no 3.x migration.
-
-Before replacing a 3.x installation, use its matching CLI to inspect and
-settle or explicitly abandon pending work; stop a launchd broker with
-`embassy service uninstall` (or stop the foreground serve process) and confirm
-it is stopped with `embassy service status`, back up and move aside only
-`gateway-state.json` in that broker's state directory while retaining
-`nodes.json`, then install the current discovery-enabled 4.x release and run
-`embassy service install`. Current Codex agents are discovered; use fallback
-registration only for non-native harnesses.
-
-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
-the old and new brokers together. See the [reset procedure](docs/CONFIGURATION.md#private-state-reset).
-
-The rollback boundary is the preserved old state plus its matching old binary.
-Do not point 4.2.0 at schema-7 state or this release at schema ≤5.
+Upgrade the CLI and broker together; they must come from one installation.
+Private state written by an earlier 4.x release (schema 6) is read forward
+into the current schema 7 with every existing endpoint retained; no reset is
+needed, but back up `gateway-state.json` first, because an earlier 4.x binary
+refuses schema 7 and rollback requires that backup.
+
+There is no 3.x migration or converter. Before replacing a 3.x installation,
+use its matching CLI to inspect and settle or explicitly abandon pending work;
+stop the broker with `embassy service uninstall` (or stop the foreground serve
+process) and confirm with `embassy service status`; back up and move aside only
+`gateway-state.json` while retaining `nodes.json`; then install the current
+release and run `embassy service install`. Codex agents are discovered; use
+fallback registration only for non-native harnesses. All 3.x state is
+unsupported: preserve the old binary with its old state if rollback may be
+needed, and never run the old and new brokers together. See the
+[reset procedure](docs/CONFIGURATION.md#private-state-reset).
 
 ## Development
 

package/SECURITY.md

@@ -2,9 +2,9 @@
 
 ## Supported versions
 
-Security fixes are provided for the current release line. Private schema 6 is
-read forward into 7; schema ≤5 still requires a reset. Private control peers
-must use the same protocol version.
+Security fixes are provided for the current release line. The CLI and broker
+must come from one installation, and federated peers must run the same
+federation protocol.
 
 ## Reporting a vulnerability
 
@@ -200,8 +200,9 @@ commit boundary remain uncertain and are never replayed automatically.
 Public JSON is a closed projection. It may contain opaque Embassy endpoint IDs,
 aliases, providers, hosts, queue depths, safe codes, phases/outcomes, ages,
 recent retirement times, and bounded remote catalog rows and observation times.
-Codex rows may additionally contain observed busy, waiting, idle, dormant or unknown state.
-The explicit-registration retention marker remains private.
+Codex rows may additionally contain the observed busy, waiting, idle, dormant,
+systemError or unknown state. The explicit-registration retention marker
+remains private.
 It must never contain native IDs or handles, socket paths, message bodies,
 delivery/conversation secrets, credentials, exceptions, raw diagnostics, or
 provider histories. Human output is derived from the same validated shape.
@@ -211,12 +212,13 @@ protocol channel. Operational hints use bounded safe codes and stderr.
 
 ## State reset and rollback
 
-Private state writes schema 7 and reads valid schema 6 forward, retaining its
-existing rows. Control protocol is 6. Schemas ≤5 and unknown state refuse before
-mutation; no 3.x converter or removed-command alias exists. Before upgrading
-4.2.0, stop the broker and back up its state; 4.2.0 refuses schema 7, so rollback
-requires that pre-upgrade backup. Upgrading from 3.x still requires inspecting
-unsettled work with the old binary and resetting state while keeping `nodes.json`.
+Private state is schema 7; a valid schema-6 document from an earlier 4.x
+release is read forward with its rows retained. Schemas ≤5 and unknown state
+refuse before mutation; there is no 3.x converter or removed-command alias.
+Back up state before upgrading, because an earlier 4.x binary refuses schema
+7 and rollback requires that pre-upgrade backup. Upgrading from 3.x requires
+inspecting unsettled work with the old binary and resetting state while keeping
+`nodes.json`.
 
 Reset invalidates all old routes, receipts, and conversation references. The
 only rollback is the preserved old binary with its untouched old state. Embassy

package/dist/src/gateway/core-version.d.ts

@@ -1 +1 @@
-export declare const CORE_VERSION = "4.4.0";
+export declare const CORE_VERSION = "4.4.1";

package/dist/src/gateway/core-version.js

@@ -1,2 +1,2 @@
-export const CORE_VERSION = "4.4.0";
+export const CORE_VERSION = "4.4.1";
 //# sourceMappingURL=core-version.js.map

package/docs/CONFIGURATION.md

@@ -123,19 +123,18 @@ 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.
+Explicit registration sets a private retention marker, so registered roots
+remain listed after restart even outside the discovery window, and 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. Window aging preserves automatic rows referenced
+by pending work but drops unused automatic rows to release capacity, without
+retirement, suppression or settlement. A returning root keeps its ID while
+retained or pending; after pruning it receives a fresh ID (and, if unnamed, a
+new generated alias), and old receipts never retarget. The 128-endpoint bound
+applies to discovered and registered rows alike, and public output carries no
+discovered/registered badge. 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.
@@ -237,11 +236,11 @@ before provider setup, so only one broker can run.
 
 ## Private state reset
 
-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.json` is written as schema 7. A valid schema-6 document from an
+earlier 4.x release is read forward with every existing row retained; no reset
+is required, but back up state before upgrading, because an earlier 4.x binary
+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.
 
@@ -253,20 +252,20 @@ 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 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.
+4. Install the current release, then run `embassy service install`. The
+   broker creates fresh schema-7 state.
+5. Let current Codex agents be discovered. Use fallback registration only for
+   non-native harnesses. Claude endpoints are recorded on discovery or 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
-the old and new brokers together.
+All state produced by Embassy 3.x is unsupported; preserve the matching old
+binary as well as its old state if rollback may be needed, and never run the
+old and new brokers together.
 
 A reset abandons unsettled work and invalidates delivery tokens and
-conversation references. Rollback means stopping v4 and restoring both the old
-binary and its untouched old state. Never hand-edit either schema.
-After v4 has accepted work, the old backup does not contain that work. Before
-rolling back, inspect and drain or explicitly abandon v4 deliveries, and keep
-a separate backup of the v4 state. Restoring v3 is not a rollback of those
-delivery effects and must never silently discard unsettled v4 work.
+conversation references. Rollback means stopping the current broker and
+restoring both the old binary and its untouched old state. Never hand-edit
+either schema. Work accepted after the upgrade is absent from the old backup:
+before rolling back, inspect and drain or explicitly abandon those deliveries
+and keep a separate backup of the current state. Restoring the old binary is
+not a rollback of those delivery effects and must never silently discard
+unsettled work.

package/docs/GATEWAY-ARCHITECTURE.md

@@ -8,10 +8,8 @@ pairs are supported. Sending is one `embassy send` command; receiving wakes the
 target through its native interface. A receipt proves delivery machinery, not
 model comprehension.
 
-The design optimizes for this steady state and deliberately excludes native
-Claude `SendMessage` advertisement helpers, shell-peer mailboxes, automatic
-Codex output forwarding, persistent remote mirrors, general activity streams,
-and migration compatibility.
+The design optimizes for this steady state; everything it deliberately leaves
+out is listed under [Responsibility exclusions](#responsibility-exclusions).
 
 ## Topology
 
@@ -31,8 +29,8 @@ Claude/Codex CLI
                                       remote broker ledger
 ```
 
-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.
+There is one broker per login user and host. The broker owns one private JSON
+state document and one private control socket. It does not listen on a network port.
 launchd may supervise the same foreground `serve` entry point.
 
 ## Endpoint directory
@@ -139,8 +137,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. 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.
+mutation. A valid schema-6 document from an earlier 4.x release reads forward
+with all existing rows retained; schema ≤5 needs a reset.
 
 ## Coordinator
 
@@ -239,9 +237,8 @@ reset.
 
 ## Local control and CLI
 
-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
+Each private control 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.
 
 The public CLI is:
@@ -257,8 +254,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 Codex rows expose busy, waiting, idle, dormant or unknown
-status, without parent references or registration-origin labels. The federation section
+native operation, and Codex rows expose busy, waiting, idle, dormant,
+systemError 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
@@ -283,7 +281,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-7 state without changing the inventory;
+3. open and validate the private state without changing the inventory;
 4. atomically install and reload the default inventory when first boot needs
    one;
 5. construct native and SSH adapters;
@@ -304,7 +302,7 @@ model interrupt.
 
 | Surface | Version | Compatibility policy |
 |---|---:|---|
-| Private state (`gateway-state.json`) | 7 | Reset only; older and unknown schemas refuse without mutation |
+| Private state (`gateway-state.json`) | 7 | A valid schema-6 document is read forward with rows retained; ≤5 and unknown refuse without mutation (reset) |
 | 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 |
@@ -314,10 +312,11 @@ each use boundary. Version or build metadata is never routing authority.
 
 ## Responsibility exclusions
 
-The v4 core intentionally has no shell-peer registration/token/mailbox/await
+The core intentionally has no shell-peer registration/token/mailbox/await
 system, no native Claude advertisement helper, no automatic provider-output
 reply capture, no persisted remote route mirror, no pair/selection graph, no
-dashboard/watch event system, no notice-mode machinery, and no v3 migration
-reader. The responsibilities that remain are endpoint identity, bounded
+dashboard/watch event system, no notice-mode machinery, and no old-state
+migration reader. Its responsibilities are endpoint identity, bounded
 delivery, native wake, exact replies, direct federation, status, retirement,
-service supervision, and loopback verification.
+service supervision, and loopback verification. The reasons are recorded in
+the repository's `docs/DECLINED.md`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-embassy",
-  "version": "4.4.0",
+  "version": "4.4.1",
   "description": "A local gateway for bidirectional messaging between Claude Code sessions and Codex tasks.",
   "license": "MIT",
   "repository": {

package/skills/embassy-peer/SKILL.md

@@ -100,4 +100,4 @@ For operator-authorized removal use `embassy retire --alias <local-alias>`. It r
 
 When a name collides, operator-authorized `embassy retire --endpoint <public-id>` removes just that local endpoint using its opaque ID from status. Use exactly one of `--alias` or `--endpoint`; never substitute a native session ID. A partial discovery cannot clear a known collision; exact user-supplied UUID addressing remains available until a complete scan proves uniqueness.
 
-There is no shell-peer mailbox, await command, native sending advertisement, automatic output forwarding, reply alias, or unregister-codex command in v4. Do not fall back to removed commands or direct provider sockets; report the precise refusal.
+`embassy --help` lists the whole public CLI; do not fall back to a command that is not listed there or to direct provider sockets; report the precise refusal.