agent-embassy 4.3.0 → 4.4.1

package/CHANGELOG.md

@@ -4,6 +4,21 @@ 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
+- Embassy now requires Node.js 22 or newer. The terminal interface uses Ink 7 for layout, styling, input and incremental rendering.
+- `embassy tui` is rebuilt on Ink: endpoints grouped by state (Working, Waiting, Faulted, Ready, Dormant, Not reporting, Cached) with counts and a column header; one colour per state with the state word always shown; bold names, dim metadata, display-width padding so wide-character names keep the grid.
+- The selected row is one highlight bar and reverse video means selection only; the outcome column receives the width so a failed delivery's safe code is readable at 80 columns; lists scroll by rendered lines, never orphan a group header, and mark clipped rows with "↑ N more" / "↓ N more".
+- Host tabs with a health mark, section tabs with the failed count in red, and one footer line carrying the position counter and the keys; the discovery note shares the header line.
+- Centred, bordered dialogs for retirement and token entry; the retirement dialog shows host, alias, the full endpoint ID and the settlement consequences in red with a distinct confirm key. Every empty list says why it is empty. Without an interactive terminal `tui` prints plain text with no escape codes; NO_COLOR removes styling and keeps the screen interactive.
+- `string-width` is now a runtime dependency (pinned).
+
 ## [4.3.0] - 2026-09-06
 
 ### Added

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
@@ -13,17 +13,19 @@ identity, so a rename or replacement never silently retargets queued work.
 
 ## Requirements
 
-- macOS and Node.js 20 or newer.
+- 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-cli.js

@@ -13,7 +13,6 @@ import { LocalControlError, requestLocalControl } from "./local-control.js";
 import { runCoreRuntime } from "./runtime.js";
 import { defaultRunLaunchctl } from "./service-agent.js";
 import { runCoreServiceCommand } from "./core-service-command.js";
-import { runTui } from "./tui.js";
 import { createTuiSshClient } from "./tui-ssh.js";
 import { CORE_VERSION } from "./core-version.js";
 export { CORE_VERSION } from "./core-version.js";
@@ -203,8 +202,10 @@ export async function runCoreCli(args, dependencies = {}) {
         if (command === "tui") {
             if (args.length !== 1)
                 return invalid();
+            const { runTui } = await import("./tui.js");
             const ssh = createTuiSshClient({ nodes: inventory.nodes, env });
             await runTui({ input: stdin, output: stdout, call, renderStatus, host: inventory.host,
+                terminal: { noColor: env.NO_COLOR !== undefined, dumb: env.TERM === "dumb" },
                 remote: { hosts: inventory.nodes, call: ssh.call, close: ssh.close },
                 hint: (code, host) => host && host !== inventory.host
                     ? `On ${host}: ${hint("tui", code, "the configured state directory on that host")}`