agent-embassy 1.7.1 → 1.8.0

package/docs/CONFIGURATION.md

@@ -2,7 +2,7 @@
 
 Embassy is configured through environment variables read when each command
 starts. This document collects every variable, provider transport contracts,
-managed-launch resolution rules, and
+provider runtime rules, and
 the addressing model. There is no configuration file; all values are env vars
 or CLI flags.
 
@@ -13,14 +13,29 @@ or CLI flags.
 | Variable | Default | Purpose |
 | --- | --- | --- |
 | `EMBASSY_STATE_DIR` | `$XDG_STATE_HOME/agent-embassy`, or `$HOME/.local/state/agent-embassy` when `XDG_STATE_HOME` is unset | Private state, control socket, and dashboard; an override must be absolute and does not relocate the fixed host-wide lease |
-| `EMBASSY_CLAUDE_BIN` | `$HOME/.local/bin/claude`, resolved to its current verified version target | Absolute Claude Code launcher path; `PATH` is not searched |
 | `DSH_HOME` | `$HOME/.dsh` | DeepSeek Harness checkout root; when its owned directory and `package.json` are present, Embassy launches `pnpm --dir <home> run demo:acp` lazily on first dispatch |
 | `EMBASSY_STEERING_ENABLED` | `1` | Global Claude-to-Codex `STEER:` kill switch; set exactly `0` to treat every Claude-to-Codex body as an ordinary Codex-bound queued message; Claude-bound mailbox timing is unchanged |
 | `EMBASSY_DELIVERY_NOTICES` | `merged` | Claude sender notice policy: `merged` keeps stalls and folds terminal diagnostics into native status; `verbose` emits both; `quiet` emits no gateway user-frame notices |
-| `EMBASSY_TRACKING_ENABLED` | `1` | Global progress-watch kill switch; set exactly `0` to reject `--track`, `--idle-minutes`, and `TRACK:` open attempts and to settle stored watches on restart. With no active watch, `DONE:` is inert and `untrack` is not specially rejected—it returns `NOT_FOUND`. Any value other than `1` or `0` is a configuration error |
+| `EMBASSY_TRACKING_ENABLED` | `1` | Global progress-watch kill switch; set exactly `0` to reject `--track`, `--idle-minutes`, and `TRACK:` open attempts. Active watches are memory-only and end with the broker process; they are never restored after restart. With no active watch, `DONE:` is inert and `untrack` is not specially rejected—it returns `NOT_FOUND`. Any value other than `1` or `0` is a configuration error |
 | `EMBASSY_LOCALE` | `en` | CLI output language, exactly `en` or `zh-CN`. The `--lang` flag overrides it for the invocation that carries it; an unset or empty value means `en`, and any other value is an argument error |
 | `EMBASSY_HOSTS` | `this-mac` | Comma-separated list of 1 through 32 unique lowercase host aliases. **The v1 launcher accepts only the single exact value `this-mac`**: any other list — including a longer one that contains `this-mac` — fails `embassy serve` closed with `GATEWAY_REMOTE_PROVIDER_DISABLED`. The variable exists for the deferred remote-consulate work and has no useful setting today |
 
+### Offline state upgrade
+
+Schema 3 is the broker's only native state format. Before starting this release
+against schema-2 state, stop the broker and run:
+
+```bash
+embassy convert-state-v2-to-v3
+```
+
+The command resolves the same configured state directory as `serve`; it accepts
+no alternate state-path argument and starts no providers, helpers, discovery,
+listener, or control socket. It verifies a byte-identical v2 backup before
+atomically installing and reading back v3 state. Normal output contains only
+success and the backup basename. If conversion fails, use the exact normalized
+safe code; do not retry a commit-unknown result or hand-edit the state file.
+
 The live dashboard is available directly at `http://127.0.0.1:41961/` while
 its foreground companion runs. Its port is a per-invocation CLI choice, not an
 environment setting: pass `--port <n>` with an integer from 1024 through 65535
@@ -59,7 +74,7 @@ The stall notice is not separately configurable. It fires at
 default four-hour deadline a pending delivery is reported at two minutes, not
 two hours.
 
-A CLI initiator receives the full `conv_` token in its result, and every routed recipient receives the same token in the inbound provenance envelope and reply hint. The token is a memory-only participant-scoped locator, not an authority credential: every `reply` rechecks caller identity, conversation membership, and the live route. The token no longer exists after a broker restart; it must likewise never be retried or reconstructed after route retirement or identity succession.
+A CLI initiator receives the full `conv_` token in its result, and every routed recipient receives the same token in the inbound provenance envelope and reply hint. The token is a memory-only participant-scoped locator, not an authority credential: every `reply` rechecks caller identity, conversation membership, and the live route. The token no longer exists after a broker restart; it must likewise never be retried or reconstructed after route retirement or identity replacement.
 
 The public launcher accepts only host `this-mac`; remote connectors remain a future capability. `register-codex` therefore takes an optional `--host <id>`, but `this-mac` is the only value the broker will admit, and the alias must end in `@<id>` to match. `--host` is also mutually exclusive with `--succeeds`, which always inherits the succeeded alias's host.
 
@@ -84,15 +99,13 @@ the destination session before suspecting the route.
 
 Embassy routes four providers: Claude over peer protocol 1, Codex over the managed App Server, and DeepSeek plus Grok Build over ACP v1. The release-owned [support matrix](../support/provider-support-matrix.json) records the exact artifacts, protocols, capabilities, stop fidelity, limitations, and test date exercised offline. Runtime never imports that file. A build or version fact can qualify the release's “tested with” claim, but it never grants or withholds routing authority.
 
-Runtime is best effort: an explicit consent edge plus the exact owned route/session identity authorizes an attempt. The current connector, route generation, strict consumed wire fields, and correlated operation determine the result. Interface drift or a missing optional provider becomes provider-local degraded/offline health, route staleness, and an exact safe code; it does not create a compatibility tier or block unrelated providers.
+Runtime is best effort: an explicit consent edge plus the exact owned route/session identity authorizes an attempt. The current per-operation transport, strict consumed wire fields, and correlated operation determine the result. Interface drift or a missing optional provider becomes provider-local degraded/offline health and an exact safe code; it does not create a compatibility tier or block unrelated providers.
 
 Only unsafe OS evidence for Embassy-owned or executed artifacts and Embassy callback, control, or state paths—such as an unsafe lease or state, swapped binary, ownership/path/symlink mismatch, or invalid generation—refuses broker startup. The Claude-owned external sessions registry root is read-side identity evidence: an unsafe UID or mode degrades only Claude with a loud observation while the broker and other providers remain available. Claude still requires native `peerProtocol: 1` per session record: a record that declares any other value is rejected in isolation and included in bounded rejection evidence without stopping the broker or hiding other usable sessions.
 
 Runtime parsing remains strict on every known registry field, frame, and response; unknown top-level Claude registry fields are ignored because Embassy never consumes them. The Claude connector row in public status carries optional bounded `registry` observations: `entriesScanned`, `parseableRecords`, monotonic `parseableRecordSeenSinceBoot`, bounded per-safe-code `rejected`, and `rejectedCodesOmitted`. Both dashboards render the same evidence loudly: if Claude is running but no record with parseable required fields has been observed since broker start, its registry layout may have changed.
 
-For every replacement Codex App Server generation, Embassy negotiates a fresh connection and re-anchors a retained route only when `thread/loaded/list` finds its exact private task identity once. A failed negotiation, missing or duplicate task, or unclean transition leaves the route stale rather than retargeting it.
-
-The managed Codex installation is resolved by exact verified path; a `codex` elsewhere on `PATH` is neither used nor modified. Claude is resolved from `EMBASSY_CLAUDE_BIN` or the official per-user launcher, never by searching `PATH`. DeepSeek uses only the attested checkout root above. Grok Build uses the release-pinned ACP launch. Version strings, when present, are bounded diagnostic metadata only.
+The managed Codex installation is resolved by exact verified path; a `codex` elsewhere on `PATH` is neither used nor modified. Claude registry and callback roots are derived from the verified current OS user; no Claude launcher or configuration file is read. DeepSeek uses only the attested checkout root above. Grok Build uses the release-pinned ACP launch. Version strings, when present, are bounded diagnostic metadata only.
 
 ## Addressing
 
@@ -100,4 +113,4 @@ Claude sessions are addressed by their current `name@host` or by a user-supplied
 
 Names, old names, PIDs, registry paths, process generations, and socket generations never become alternate identity keys. Embassy refuses to guess when two live sessions share a current name.
 
-Codex routes use an explicit `codex-*` alias and the task's inherited thread identity. The private thread ID is never accepted as a command-line argument or printed. Compatible managed App Server generation changes and broker restarts can both re-anchor the exact loaded task automatically; a normal restart needs no manual registration. If boot reactivation cannot find that task exactly once, the route remains stale with `REOBSERVATION_REQUIRED`. Once the task is observable, recover it by rerunning `embassy register-codex --alias <same-alias>` from that exact Codex task without unregistering first. Never supply or reconstruct its thread ID. If the task no longer exists, the live dashboard can remove the retained registration only after the broker proves it stale on a dead endpoint generation.
+Codex routes use an explicit `codex-*` alias and the task's inherited thread identity. The private thread ID is never accepted as a command-line argument or printed. Registration performs no App Server operation. Every delivery opens and attests a fresh managed transport, initializes it, resumes the exact task with history excluded, and authorizes the body write once. App Server, Desktop, and broker restarts do not change logical route authority or require re-registration. A current unavailable or unobservable task reports an operation-local safe code while the registration and consent edge remain.

package/docs/CONFIGURATION.zh-CN.md

@@ -1,6 +1,6 @@
 # 配置与提供方契约
 
-Embassy 通过各命令启动时读取的环境变量进行配置。本文档汇集所有变量、提供方传输契约、托管启动解析规则与寻址模型。没有配置文件；所有值均为环境变量或 CLI 标志。
+Embassy 通过各命令启动时读取的环境变量进行配置。本文档汇集所有变量、提供方传输契约、提供方运行时规则与寻址模型。没有配置文件；所有值均为环境变量或 CLI 标志。
 
 ---
 
@@ -9,14 +9,28 @@ Embassy 通过各命令启动时读取的环境变量进行配置。本文档汇
 | 变量 | 默认值 | 用途 |
 | --- | --- | --- |
 | `EMBASSY_STATE_DIR` | `$XDG_STATE_HOME/agent-embassy`，当 `XDG_STATE_HOME` 未设置时为 `$HOME/.local/state/agent-embassy` | 私有状态、控制套接字和仪表盘；覆盖值必须为绝对路径，且不会迁移固定的主机级租约 |
-| `EMBASSY_CLAUDE_BIN` | `$HOME/.local/bin/claude`，解析到当前已验证的版本目标 | Claude Code 启动器的绝对路径；不搜索 `PATH` |
 | `DSH_HOME` | `$HOME/.dsh` | DeepSeek Harness checkout 根目录；当自有目录与 `package.json` 存在时，Embassy 会在首次投递时惰性运行 `pnpm --dir <home> run demo:acp` |
 | `EMBASSY_STEERING_ENABLED` | `1` | 全局 Claude→Codex `STEER:` 停用开关；精确设为 `0` 后，所有 Claude→Codex 正文都按朝向 Codex 的普通排队消息处理；朝向 Claude 的邮箱写入时机不受影响 |
 | `EMBASSY_DELIVERY_NOTICES` | `merged` | Claude 发送方通知策略：`merged` 保留停滞通知并把终局诊断合并到原生状态；`verbose` 同时发送两者；`quiet` 不发送任何网关用户帧通知 |
-| `EMBASSY_TRACKING_ENABLED` | `1` | 全局进度监视停用开关；精确设为 `0` 后，`--track`、`--idle-minutes` 与 `TRACK:` 开启请求会被拒绝，已有监视会在重启时结算。没有活跃监视时，`DONE:` 不产生作用；`untrack` 不会因开关而被特别拒绝，而是返回 `NOT_FOUND`。取值只能是 `1` 或 `0`，其他值均为配置错误 |
+| `EMBASSY_TRACKING_ENABLED` | `1` | 全局进度监视停用开关；精确设为 `0` 后，`--track`、`--idle-minutes` 与 `TRACK:` 开启请求会被拒绝。活跃监视只存在于内存中，并随代理进程结束；重启后绝不恢复。没有活跃监视时，`DONE:` 不产生作用；`untrack` 不会因开关而被特别拒绝，而是返回 `NOT_FOUND`。取值只能是 `1` 或 `0`，其他值均为配置错误 |
 | `EMBASSY_LOCALE` | `en` | CLI 输出语言，精确取值 `en` 或 `zh-CN`。`--lang` 标志会覆盖当次调用；未设置或为空表示 `en`，其他任何取值都是参数错误 |
 | `EMBASSY_HOSTS` | `this-mac` | 以逗号分隔的 1 到 32 个唯一小写主机别名。**v1 启动器只接受单个精确值 `this-mac`**：任何其他列表——包括包含 `this-mac` 的更长列表——都会让 `embassy serve` 以 `GATEWAY_REMOTE_PROVIDER_DISABLED` 关闭失败。该变量是为推迟的远程领事馆功能预留的，目前没有可用的设置 |
 
+### 离线状态升级
+
+架构 3 是代理唯一的原生状态格式。使用本版本启动架构-2 状态之前，
+请先停止代理并运行：
+
+```bash
+embassy convert-state-v2-to-v3
+```
+
+该命令使用与 `serve` 相同的配置来解析状态目录；它不接受其他状态路径
+参数，也不会启动提供方、辅助进程、发现、监听器或控制套接字。它先验证
+逐字节一致的 v2 备份，再原子安装并回读 v3 状态。正常输出只包含成功结果
+与备份文件的基本名称。转换失败时请使用精确的规范化安全代码；提交结果
+未知时不要重试，也不要手工编辑状态文件。
+
 当前台实时仪表盘组件运行时，可直接通过 `http://127.0.0.1:41961/` 访问。端口是单次命令的 CLI 选择，而不是环境设置；如需另一个稳定端口，请向 `embassy dashboard --live` 传入 `--port <n>`，其中整数范围为 1024 到 65535。当前台进程运行时，该 URL 最多支持四个并发实时视图（可分布在窗口、标签页或浏览器中）；在其中一个关闭前，第五条流会被拒绝。端口冲突会以 `LIVE_DASHBOARD_PORT_IN_USE` 失败并提示使用 `--port`；Embassy 绝不会回退到临时或其他端口。
 
 ## 高级边界
@@ -40,7 +54,7 @@ Embassy 通过各命令启动时读取的环境变量进行配置。本文档汇
 
 停滞通知本身不可单独配置。它在 `min(floor(EMBASSY_MESSAGE_DEADLINE_MS / 2), 120000)` 毫秒时触发，因此在默认的四小时截止时间下，待投递消息会在两分钟时被报告，而不是两小时。
 
-初始发送方从 CLI 结果获得完整 `conv_` 令牌，接收方则从入站消息的来源封装和回复提示中获得同一个令牌。令牌是内存中的参与方范围定位符，不是权限凭据：每次 `reply` 都会重新检查调用方身份、参与关系和实时路由。代理重启后令牌不再存在；路由失效或身份转交后，也不得重试或重构旧令牌。
+初始发送方从 CLI 结果获得完整 `conv_` 令牌，接收方则从入站消息的来源封装和回复提示中获得同一个令牌。令牌是内存中的参与方范围定位符，不是权限凭据：每次 `reply` 都会重新检查调用方身份、参与关系和实时路由。代理重启后令牌不再存在；路由失效或身份替换后，也不得重试或重构旧令牌。
 
 公开发布的启动器仅接受主机 `this-mac`；远程连接器仍是未来功能。因此 `register-codex` 提供可选的 `--host <id>`，但代理只会接纳 `this-mac`，而且别名必须以 `@<id>` 结尾才能匹配。`--host` 与 `--succeeds` 互斥，后者始终继承被接替别名的主机。
 
@@ -54,15 +68,13 @@ Embassy 通过各命令启动时读取的环境变量进行配置。本文档汇
 
 Embassy 路由四种提供方：Claude 使用对等协议 1，Codex 使用托管 App Server，DeepSeek 与 Grok Build 使用 ACP v1。发布版自有的[支持矩阵](../support/provider-support-matrix.json)记录离线测试的精确构件、协议、能力、停止保真度、限制与测试日期；运行时从不导入它。构建或版本事实可以限定发布版“已测试”的说法，但绝不授予或撤销路由权限。
 
-运行时采用尽力而为模式：显式同意边加上精确自有路由/会话身份会授权一次尝试。当前连接器、路由代际、被消费协议字段的严格结构与相关操作决定结果。接口变化或可选提供方缺失会显示为提供方局部的降级/离线健康度、路由陈旧状态与精确安全代码；它不会产生兼容性等级，也不会阻止其他提供方。
+运行时采用尽力而为模式：显式同意边加上精确自有路由/会话身份会授权一次尝试。当前逐操作传输、被消费协议字段的严格结构与相关操作决定结果。接口变化或可选提供方缺失会显示为提供方局部的降级/离线健康度与精确安全代码；它不会产生兼容性等级，也不会阻止其他提供方。
 
 只有 Embassy 自有或执行的构件及其回调、控制或状态路径出现不安全 OS 证据——例如不安全的租约或状态、被替换的二进制、所有权/路径/符号链接不匹配，或无效的代际——才会拒绝代理启动。Claude 自有的外部会话注册表根目录属于读取侧身份依据：UID 或模式不安全时，只会让 Claude 降级并醒目显示，代理与其他提供方继续运行。Claude 每条会话记录仍必须使用原生 `peerProtocol: 1`；声明其他值的记录会单独被拒绝并纳入有界拒绝证据，不会阻止代理启动或隐藏其他可用会话。
 
 运行时仍会严格解析每个已知注册表字段、帧和响应；未知的 Claude 注册表顶层字段会被忽略，因为 Embassy 从不使用它们。公开状态中的 Claude 连接器行会携带可选的有界 `registry` 观测：`entriesScanned`、`parseableRecords`、单调的 `parseableRecordSeenSinceBoot`、按安全代码分组且有界的 `rejected`，以及 `rejectedCodesOmitted`。两种仪表盘会醒目呈现同一事实：如果 Claude 正在运行，但自代理启动以来从未观测到带可解析必需字段的记录，它的注册表布局可能已更改。
 
-每个替代 Codex App Server 端点代际都会协商一条新连接；只有 `thread/loaded/list` 恰好一次找到精确私有任务身份时，Embassy 才会重新锚定保留路由。协商失败、任务缺失或重复、转换不干净都会让路由保持陈旧，而不是改投其他任务。
-
-托管 Codex 安装通过精确已验证路径解析；`PATH` 上其他位置的 `codex` 不会被使用或修改。Claude 从 `EMBASSY_CLAUDE_BIN` 或官方用户级启动器解析，从不搜索 `PATH`。DeepSeek 只使用上方已验证的 checkout 根目录。Grok Build 使用发布版固定的 ACP 启动。版本字符串如存在，也只是有界诊断元数据。
+托管 Codex 安装通过精确已验证路径解析；`PATH` 上其他位置的 `codex` 不会被使用或修改。Claude 注册表与回调根目录从已验证的当前 OS 用户派生；不会读取 Claude 启动器或配置文件。DeepSeek 只使用上方已验证的 checkout 根目录。Grok Build 使用发布版固定的 ACP 启动。版本字符串如存在，也只是有界诊断元数据。
 
 ## 寻址
 
@@ -70,4 +82,4 @@ Claude 会话通过其当前的 `name@host` 或用户提供的原生会话 UUID
 
 名称、旧名称、PID、注册表路径、进程生成号和套接字生成号绝不会成为替代身份键。当两个在线会话共享同一当前名称时，Embassy 拒绝猜测。
 
-Codex 路由使用显式的 `codex-*` 别名和任务继承的线程标识。私有线程 ID 从不被接受为命令行参数，也从不被打印。兼容的托管 App Server 端点代际变更与代理重启都能自动重新锚定精确的已加载任务；正常重启不需要手动重新注册。如果启动时重新激活无法恰好一次找到该任务，路由会以 `REOBSERVATION_REQUIRED` 保持陈旧。该任务恢复可观察后，请从精确 Codex 任务内使用同一别名再次运行 `embassy register-codex --alias <同一别名>`，且不要先注销。切勿提供或重构线程 ID。如果该任务已不存在，实时仪表盘只有在代理证明该注册陈旧且所属端点代际已失效后，才能移除该保留注册。
+Codex 路由使用显式的 `codex-*` 别名和任务继承的线程标识。私有线程 ID 从不作为命令行参数接受，也从不打印。注册时不执行 App Server 操作。每次投递都会打开并验证新的托管传输，初始化后在不读取历史的前提下恢复精确任务，并仅授权一次正文写入。App Server、桌面应用或代理重启不会改变逻辑路由权限，也无需重新注册。当前任务不可用或不可观察时，尝试会报告操作级安全代码，而注册和同意边仍会保留。

package/docs/DASHBOARD.md

@@ -68,22 +68,22 @@ Origin, but every POST requires the exact Origin plus
 These checks constrain browser cross-origin requests; they do not authenticate
 local software. There are no generic control or provider routes, telemetry, or
 external assets. The only mutation route accepts exact pair, unpair,
-refresh-discovery, and stale-Codex-registration-removal actions, requires an
-explicit in-page confirmation, rejects bodies over 1 KiB, and is limited to
-six actions per minute. Removal names only a public `codex-*` alias; the broker
-accepts it only when the registration is stale and its endpoint generation is
-dead. No task ID or endpoint generation enters the browser contract. The
+refresh-discovery, and named Codex-registration-removal actions, requires an
+explicit in-page consequence confirmation, rejects bodies over 1 KiB, and is
+limited to six actions per minute. Removal names only a public `codex-*` alias;
+the broker removes that registration's consent edges and settles active work by
+its durable write phase. No task ID enters the browser contract. The
 browser client keeps only a display-preference key
 (active tab and language) in `localStorage`.
-The browser cannot create or live-unregister tasks, send, reply, approve,
+The browser cannot create tasks, send, reply, approve,
 interrupt, change settings, or invoke arbitrary broker/provider methods. It receives a sanitized
 snapshot via same-origin `fetch`; after each bounded action it reads
-a fresh snapshot. A snapshot observation may settle already-due
-lifecycle deliveries before projecting state.
+a fresh snapshot. A snapshot observation may settle already-due delivery
+deadlines before projecting state.
 
-An exact App Server generation transition appears in Activity as an automatic event, distinct from operator actions. The dashboard does not certify builds or grant authority: it reports only best-effort runtime facts from the bounded public snapshot. Overview and Routes keep Claude, Codex, DeepSeek, and Grok Build visible even when a route or connector is absent; Deliveries filters by all four source and target providers; Diagnostics shows observed protocol/version metadata, current connector health, and the last safe code. Version metadata never changes route authority.
+App Server generations, re-anchors, and refreshes do not appear in Activity or grant route authority. The dashboard reports only best-effort runtime facts from the bounded public snapshot. That public snapshot remains schema version 2 even though the private native store is schema 3. Overview and Routes keep Claude, Codex, DeepSeek, and Grok Build visible even when a route or connector is absent; Deliveries filters by all four source and target providers; Diagnostics shows observed protocol/version metadata, current connector health, and the last safe code. Version metadata never changes route authority.
 
-The Diagnostics registry block mirrors optional bounded `registry` observations on the Claude connector row: `entriesScanned`, `parseableRecords`, monotonic `parseableRecordSeenSinceBoot`, bounded per-safe-code `rejected`, and `rejectedCodesOmitted`. It derives “Parseable required fields observed”, “Empty since broker start”, or “No parseable record since broker start”. The last warning says that no Claude registry record with parseable required fields has been observed since broker start and that, if Claude is running, its registry layout may have changed; that possible layout change therefore cannot look like a healthy empty peer list. The dashboard never exposes retained native IDs, endpoint generations, raw registry records, or the release-owned offline support matrix, and endpoint recovery never replays a message body.
+The Diagnostics registry block mirrors optional bounded `registry` observations on the Claude connector row: `entriesScanned`, `parseableRecords`, monotonic `parseableRecordSeenSinceBoot`, bounded per-safe-code `rejected`, and `rejectedCodesOmitted`. It derives “Parseable required fields observed”, “Empty since broker start”, or “No parseable record since broker start”. The last warning says that no Claude registry record with parseable required fields has been observed since broker start and that, if Claude is running, its registry layout may have changed; that possible layout change therefore cannot look like a healthy empty peer list. The dashboard never exposes retained native IDs, operation-local endpoint evidence, raw registry records, or the release-owned offline support matrix, and a later attempt never replays an uncertain message body.
 
 An optional `--lang en|zh-CN` flag selects the display language. It belongs to
 the live companion only; the static pair is always written in both languages

package/docs/DASHBOARD.zh-CN.md

@@ -36,11 +36,11 @@ embassy dashboard --live --port 41962
 
 这里没有 URL 片段令牌、Cookie、登录、逐浏览器会话或引导文件。预期姿态是一名操作员，以及已经受信任、以该操作员 macOS UID 运行的软件。HTTP 监听器有意不认证进程或 OS 用户，因此这是可信单用户机器的假设，而不是强制执行同 UID 的机制。任何能够访问或伪造 loopback 的本地软件都可以读取实时视图（包括保留的正文）并提交其有限操作。
 
-每个请求都会检查精确的 Host 头。导航 GET 可以缺少 Origin，但每个 POST 都要求精确的 Origin 与 `X-Embassy-Request: 1`。服务器不接受 `OPTIONS`，也不发送 CORS 头。这些检查约束浏览器的跨来源请求，但不认证本地软件。没有通用控制或提供方路由、遥测或外部资源。唯一的变更路由只接受配对、取消配对、刷新发现结果和移除陈旧 Codex 注册四种精确操作；每次都要求页内明确确认，正文上限为 1 KiB，并限制为每分钟六次。移除操作只携带公开的 `codex-*` 别名；仅当代理确认注册已陈旧且其端点代际已失效时才会接受。任务 ID 与端点代际不会进入浏览器契约。浏览器客户端仅在 `localStorage` 中保存一个显示偏好键（当前选项卡与语言）。浏览器不能创建或注销在线任务、发送、回复、审批、中断、更改设置，也不能调用任意代理或提供方方法。它通过同源 `fetch` 接收快照，并在每次有限操作后重新读取最新快照。一次快照观测可能会在投射状态之前结算已到期的生命周期投递。
+每个请求都会检查精确的 Host 头。导航 GET 可以缺少 Origin，但每个 POST 都要求精确的 Origin 与 `X-Embassy-Request: 1`。服务器不接受 `OPTIONS`，也不发送 CORS 头。这些检查约束浏览器的跨来源请求，但不认证本地软件。没有通用控制或提供方路由、遥测或外部资源。唯一的变更路由只接受配对、取消配对、刷新发现结果和移除具名 Codex 注册四种精确操作；每次都要求页内明确说明后果并确认，正文上限为 1 KiB，并限制为每分钟六次。移除操作只携带公开的 `codex-*` 别名；代理会删除该注册的同意边，并按其持久化写入阶段结算活动工作。任务 ID 不会进入浏览器契约。浏览器客户端仅在 `localStorage` 中保存一个显示偏好键（当前选项卡与语言）。浏览器不能创建任务、发送、回复、审批、中断、更改设置，也不能调用任意代理或提供方方法。它通过同源 `fetch` 接收快照，并在每次有限操作后重新读取最新快照。一次快照观测可能会在投射状态之前结算已到期的投递截止时间。
 
-精确 App Server 代际转换会作为自动事件出现在“活动”中，并与操作员操作明确区分。仪表盘不认证构建，也不授予权限；它只报告有界公开快照中的尽力而为运行时事实。“总览”与“路由”会在路由或连接器缺失时仍显示 Claude、Codex、DeepSeek 与 Grok Build；“投递”可按四种发送方与接收方提供方筛选；“诊断”显示已观察协议/版本元数据、当前连接器健康度与最近安全代码。版本元数据绝不改变路由权限。
+App Server 代际、重新锚定与刷新不会出现在“活动”中，也不会授予路由权限。仪表盘只报告有界公开快照中的尽力而为运行时事实。即使私有原生存储使用架构 3，公开快照仍保持架构版本 2。“总览”与“路由”会在路由或连接器缺失时仍显示 Claude、Codex、DeepSeek 与 Grok Build；“投递”可按四种发送方与接收方提供方筛选；“诊断”显示已观察协议/版本元数据、当前连接器健康度与最近安全代码。版本元数据绝不改变路由权限。
 
-“诊断”中的注册表区块会镜像 Claude 连接器行上可选的有界 `registry` 观测：`entriesScanned`、`parseableRecords`、单调的 `parseableRecordSeenSinceBoot`、按安全代码分组且有界的 `rejected`，以及 `rejectedCodesOmitted`。它会派生“已观察到可解析必需字段”、“自代理启动以来为空”或“自代理启动以来没有可解析记录”。最后一种警告会说明：自代理启动以来从未观察到带可解析必需字段的 Claude 注册表记录；如果 Claude 正在运行，它的注册表布局可能已更改。因此，这种变化不会伪装成健康的空对等列表。仪表盘绝不暴露保留的原生 ID、端点代际、原始注册表记录或发布版自有的离线支持矩阵；端点恢复也绝不重放消息正文。
+“诊断”中的注册表区块会镜像 Claude 连接器行上可选的有界 `registry` 观测：`entriesScanned`、`parseableRecords`、单调的 `parseableRecordSeenSinceBoot`、按安全代码分组且有界的 `rejected`，以及 `rejectedCodesOmitted`。它会派生“已观察到可解析必需字段”、“自代理启动以来为空”或“自代理启动以来没有可解析记录”。最后一种警告会说明：自代理启动以来从未观察到带可解析必需字段的 Claude 注册表记录；如果 Claude 正在运行，它的注册表布局可能已更改。因此，这种变化不会伪装成健康的空对等列表。仪表盘绝不暴露保留的原生 ID、逐操作端点证据、原始注册表记录或发布版自有的离线支持矩阵；之后的尝试也绝不重放结果不确定的消息正文。
 
 可选的 `--lang en|zh-CN` 标志用于选择显示语言。它仅属于实时组件；静态版本始终以两种语言写入，通过页内链接切换。
 

package/docs/DELIVERY.md

@@ -20,13 +20,13 @@ Embassy.
 - **Native failures.** A Claude-originated route or delivery failure settles as native `expired`; its native acknowledgement always retains the normalized safe code in the reason field. The default `merged` notice mode keeps the early stall frame but suppresses the duplicate terminal `<gateway-delivery-diagnostic>` user frame. `verbose` restores that readable diagnostic frame; `quiet` suppresses all gateway-authored user-frame notices, including stalls, while native status and dashboard truth remain. No notice contains a path, native identifier, exception, or message body. `denied` is reserved for a real user or policy refusal and is not authored by Embassy v1. `held` and transport-written are progress, never success.
 - **Native held is attempt-then-ack.** For Claude→Codex ingress, Embassy first attempts the exact immediate dispatch. A terminal result observed before the one-second prompt boundary produces only its terminal acknowledgement. Native `held` is sent only when the body actually remains queued (including a busy route or clean provider deferral) or dispatch is still nonterminal at that boundary; the terminal acknowledgement follows later. Claude's rendered “approved and released” notice means only that the paired-consent gateway accepted and released the body to the recipient queue. It does not mean a model read it, and it does not imply human approval.
 
-- **Retries are conservative.** Undispatched Codex-bound messages remain queued while the task is busy or temporarily unavailable. A Claude-bound body may remain queued only for a pre-write route failure or temporary unavailability, never merely because Claude is observed busy. Re-running `register-codex` replaces a closed or faulted App Server connector and wakes held Codex-bound work when the recovered route is idle. An explicit clean adapter deferral can return the same body to the queue. A Claude route that merely stops appearing in discovery is no longer invalidated on its own: its queued mail stays addressed to that session, and a write to a dead session socket fails fast with its exact safe code instead. A confirmed delivery failure settles; an ambiguous write is never retried automatically.
+- **Retries are conservative.** Undispatched Codex-bound messages remain queued while the task is busy or temporarily unavailable. Each attempt opens a fresh App Server transport; registration and connector observation never certify reachability. A clean pre-write deferral may return reserved work to the queue. Once the body write is armed, uncertainty is terminal and never replayed. A Claude-bound body may remain queued only for a pre-write route failure or temporary unavailability, never merely because Claude is observed busy. A confirmed delivery failure settles; an ambiguous write is never retried automatically.
 
 - **Bounded by design.** Bodies, queues, rate windows, deduplication tables, deadlines, and transient conversations all have fixed limits.
 
 - **Progress watches are independent evidence.** An opt-in watch may outlive an opener that expired before delivery, so a worker can remain unaware of the original assignment even while thread activity keeps the watch healthy. Owners should check the opener's `delivery-status` separately before assuming the assignment text arrived.
 
-- **Restarts keep queued mail.** Queued bodies persist under bounded retention and re-send exactly once when their route is re-observed. In-flight-at-crash messages settle ambiguous — never silently lost, never double-sent. Delivery tokens remain memory-only. A prior Claude binding remains stored but stale; after an authorized complete live discovery, an exact unique stored UUID reactivates automatically; explicit `select-claude` remains the optional fallback. No pending reply or conversation capability survives.
+- **Restarts keep clean work only.** Queued and reserved bodies persist under bounded retention and may resume once against the same logical route and consent edge. Armed or accepted work at crash settles ambiguous or unconfirmed and is never replayed. Each retained message keeps its opaque delivery token and status in the private v3 state, so the sender can continue checking that exact attempt after restart. No pending reply or conversation capability survives.
 
 Accepted messages are tracked toward terminal delivery while the broker and provider connections remain healthy. The dashboard distinguishes acceptance, progress, delivery, expiry, failure, ambiguity, and abandonment.
 
@@ -74,11 +74,11 @@ classified as an ambiguous write or replayed.
 
 ## Delivery tokens
 
-Every accepted `send-to-claude`, `send-to-codex`, and `reply` returns a delivery token: `dlv_` followed by exactly 24 base64url characters. It addresses one bounded in-memory tracker and is not a provider receipt handle.
+Every accepted `send-to-claude`, `send-to-codex`, and `reply` returns a delivery token: `dlv_` followed by exactly 24 base64url characters. It addresses one bounded private v3 message/status row and is not a provider receipt handle. The token is persisted only in the mode-0600 broker state; it never enters a public snapshot, normal log, provider receipt, or dashboard.
 
 ```bash
 embassy delivery-status --token dlv_<token>
 embassy wait-delivery --token dlv_<token>
 ```
 
-`delivery-status` reads the tracker once. `wait-delivery` polls until the tracker is terminal or the delivery deadline passes. It exits `0` only for `delivered`, `6` for any other terminal state (`unconfirmed`, `expired`, `failed`, `ambiguous`, or `cancelled`), `3` for an unknown token, and `4` for a local wait timeout — which is not a terminal state and does not authorize a resend. Tokens are memory-only: after a restart, a prior token reports `found: false`.
+`delivery-status` reads the retained status once. `wait-delivery` polls until the message is terminal or the delivery deadline passes. It exits `0` only for `delivered`, `6` for any other terminal state (`unconfirmed`, `expired`, `failed`, `ambiguous`, or `cancelled`), `3` for an unknown token, and `4` for a local wait timeout — which is not a terminal state and does not authorize a resend. A retained pre-restart token continues to resolve after restart; `found: false` means that exact token is not present in the bounded state, for example after terminal retention eviction.

package/docs/DELIVERY.zh-CN.md

@@ -15,13 +15,13 @@ Embassy 跟踪每条被接受的消息，从 CLI 接受到终态结算的全过
 - **原生失败。** Claude 发起的路由或投递失败会结算为原生 `expired`；其原生确认始终在 reason 字段中保留规范化安全代码。默认的 `merged` 通知模式保留早期停滞帧，但抑制重复的终局 `<gateway-delivery-diagnostic>` 用户帧。`verbose` 会恢复该可读诊断帧；`quiet` 会抑制所有由网关生成的用户帧通知（包括停滞通知），但仍保留原生状态和仪表盘事实。任何通知都不包含路径、原生标识符、异常或消息体。`denied` 保留用于真实的用户或策略拒绝，Embassy v1 不会生成该状态。`held` 和已完成传输写入是进度状态，不是成功状态。
 - **原生 held 采用“先尝试、后确认”。** 对 Claude→Codex 入站消息，Embassy 会先尝试精确的立即投递。在一秒提示边界前观察到终局结果时，只发送终局确认。仅当正文确实仍在排队（包括路由繁忙或提供方明确推迟）或到达该边界时投递仍未终结，才发送原生 `held`；终局确认随后发送。Claude 显示的“已批准并释放”通知只表示具备配对同意的网关已接受正文并将其释放到接收方队列；它不表示模型已读取，也不表示有人类批准。
 
-- **保守重试。** 尚未分派、朝向 Codex 的消息会在任务忙碌或暂时不可用期间保持排队。朝向 Claude 的正文只有在写前路由失败或暂时不可用时才可能排队，绝不会仅因观测到 Claude 繁忙而排队。重新运行 `register-codex` 会替换已关闭或故障的 App Server 连接器，并在恢复后的路由空闲时唤醒朝向 Codex 的挂起工作。显式的干净适配器延迟可以将同一消息体退回队列。仅仅从发现结果中消失的 Claude 路由不再被自动作废：其排队邮件仍指向该会话；改为在写入已失效的会话套接字时，带着精确的安全代码快速失败。已确认的投递失败会结算；不明确的写入结果绝不会被自动重试。
+- **保守重试。** 尚未分派、朝向 Codex 的消息会在任务忙碌或暂时不可用期间保持排队。每次尝试都打开新的 App Server 传输；注册和连接器观测都不证明可达性。写入前的干净延迟可将已保留工作退回队列。一旦正文写入已被授权，任何不确定性都是终态，绝不重放。朝向 Claude 的正文只有在写前路由失败或暂时不可用时才可能排队。
 
 - **有界设计。** 消息体、队列、速率窗口、去重表、截止时间和临时对话都有固定的上限。
 
 - **进度监视是独立证据。** 选择启用的监视可能比一条在投递前已过期的开启消息存续更久，因此即使线程活动让监视保持健康，工作方仍可能从未看到原始任务。所有者在假定任务文本已到达之前，应单独检查开启消息的 `delivery-status`。
 
-- **重启保留排队邮件。** 排队中的消息体按有界策略持久化，并在路由被重新观察到时恰好重发一次。崩溃时在途的消息结算为 ambiguous — 绝不悄然丢失，也绝不重复发送。投递令牌仍仅存于内存。先前的 Claude 绑定仍被存储但处于过期状态；经授权的完整实时发现后，精确唯一的存储 UUID 会自动重新激活；显式运行 `select-claude` 仍是可选的后备方式。待处理的回复或对话能力均不保留。
+- **重启仅保留干净工作。** 排队或已保留的消息体按有界策略持久化，并可在同一逻辑路由和同意边上恢复一次。崩溃时已授权或已接受的工作结算为 ambiguous 或 unconfirmed，绝不重放。每条仍保留的消息会在私有 v3 状态中保存其不透明投递令牌和状态，因此发送方可在重启后继续检查这一次精确尝试。待处理的回复或对话能力均不保留。
 
 已接受的消息在代理和提供方连接保持健康的情况下被跟踪至终态投递。仪表盘区分接受、进行中、已投递、过期、失败、不明确和废弃等状态。
 
@@ -43,11 +43,11 @@ Embassy 的存储、队列、`STEER:` 分类、去重、速率限制和 16 KiB
 
 ## 投递令牌
 
-每次被接受的 `send-to-claude`、`send-to-codex` 和 `reply` 都会返回一个投递令牌：`dlv_` 后跟恰好 24 个 base64url 字符。它指向一个有界的内存跟踪器，不是提供方回执句柄。
+每次被接受的 `send-to-claude`、`send-to-codex` 和 `reply` 都会返回一个投递令牌：`dlv_` 后跟恰好 24 个 base64url 字符。它指向私有 v3 状态中一条有界的消息／状态记录，不是提供方回执句柄。令牌只持久化在 mode-0600 的代理状态中，绝不会进入公开快照、普通日志、提供方回执或任何仪表盘。
 
 ```bash
 embassy delivery-status --token dlv_<token>
 embassy wait-delivery --token dlv_<token>
 ```
 
-`delivery-status` 读取跟踪器一次。`wait-delivery` 轮询直至跟踪器到达终态或投递截止时间到期。仅在 `delivered` 时以退出码 `0` 退出，任何其他终态（`unconfirmed`、`expired`、`failed`、`ambiguous` 或 `cancelled`）以退出码 `6` 退出，令牌未知时以 `3` 退出，本地等待超时以 `4` 退出——超时不是终态，不构成重发授权。令牌仅存于内存：重启后，先前的令牌会报告 `found: false`。
+`delivery-status` 读取保留状态一次。`wait-delivery` 轮询直至消息到达终态或投递截止时间到期。仅在 `delivered` 时以退出码 `0` 退出，任何其他终态（`unconfirmed`、`expired`、`failed`、`ambiguous` 或 `cancelled`）以退出码 `6` 退出，令牌未知时以 `3` 退出，本地等待超时以 `4` 退出——超时不是终态，不构成重发授权。重启前仍受保留的令牌在重启后会继续解析；`found: false` 表示该精确令牌不在有界状态中，例如其终态记录已按保留上限被淘汰。