agent-embassy 1.4.1 → 1.6.0

package/CHANGELOG.md

@@ -4,7 +4,46 @@ 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/).
 
-## [Unreleased]
+## [1.6.0] - 2026-08-16
+
+### Fixed
+
+- An App Server restart no longer wedges Codex routes until the broker is restarted: endpoint-transition evidence survives to be claimed once by a later selector, queued message contexts migrate their binding keys across the transition, already-published evidence can never be republished under a divergent key, and one observed stale-to-healthy recovery edge re-arms an exhausted transition — recovery listens for reality instead of retrying into silence.
+- Stale Codex guidance now distinguishes the automatic endpoint transition from a Desktop app or task that has not reconnected after the recovery burst, and gives the exact managed-daemon relaunch command. The quickstart documents Desktop's attach-at-launch precondition.
+
+### Added
+
+- Codex compatibility now includes an optional write-attestation probe that may create at most one disposable broker-owned thread per attempt under a bounded write fence, never touches user threads, and archives every created probe thread with loaded-set cleanup confirmed. It grants no authority by itself. The probe resolves the pinned model's lowest advertised effort; whenever that model/effort pin cannot resolve, it declines in a zero-spend fail-safe before creating any thread or model turn.
+- The evidence ladder records which authority its probes covered: passing write attestation appears as optional probe evidence and a derived writes-covered marker on the diagnostics table — downgrade-safe, never persisted as a new field, unlocking nothing by itself.
+- Compatibility surfaces may now be optional: a declared-but-absent surface boots quietly and renders as "Not detected" instead of failing the broker, and the diagnostics capacity derives from the declared surface set so a third surface can never be silently truncated.
+- A locally installed DeepSeek harness (dsh) is detected and shown on the diagnostics table — attested executable and harness home, one bounded closed-environment --version read, never launched, never routed, credentials provably untouched — rendered honestly as unknown/incompatible until a stable release is certified.
+- Version evidence accepts bounded SemVer prerelease suffixes and represents them honestly: a prerelease on a supported series can earn schema_attested but remains monitor-only forever, and 0.x compatibility series are per-minor — a Codex minor bump stays monitor-only until an Embassy release certifies the new series.
+
+### Changed
+
+- Every published claim that bounded Codex reads "never invoke turn/start" was replaced across all surfaces and both languages with the precise truth: ordinary reads remain read-only; the optional write-attestation probe alone may create one fenced disposable thread, and only it may archive that thread.
+
+## [1.5.0] - 2026-08-11
+
+### Changed
+
+- Provider versions now follow one evidence ladder: certified same-major builds are writable; same-major builds with fully passing bounded probes are `schema_attested` and writable only when those probes cover the write path. Claude's probes cover its native write path, while untested Codex 0.x remains monitor-only pending a certified `turn/start` write schema. Failed probes, a different major, or version evidence that cannot establish a safe major leave only that provider degraded, monitor-only, and write-fenced while the broker, control socket, dashboards, and other provider keep running. Probes never promote across a major or compensate for unknown major evidence. An exact official launcher target may supply separate bounded major evidence even when its version banner is unparseable. Different-major guidance names the observed and tested versions plus the supported major and says that a supporting Embassy release is required. Exact OS ownership, path, symlink, lease, state, and generation failures still refuse broker startup.
+- The progress watch keeps its six promises — visible to both parties, one per consent edge, closed by `DONE:` from either side with attribution, idle nudges, restart survival, attributed history — with a third of the machinery. Settlement is absence plus history; the journal vocabulary is exactly `opened`, `replaced`, `settled`, each row carrying a strict actor and reason; every journal write flows through one guarded batch append site. Upgrading from v1.4 settles each live watch once with a journaled row, and migration never consults today's configuration: history a past broker legitimately wrote loads to the immutable hard bound regardless of current depth settings.
+- The static and live dashboards render one shared semantic vocabulary from `dashboard-model`, shipped to the live app inside its boot payload and compiler-linked through source-level type declarations verified against a never-built checkout. The surfaces keep deliberately different prose and CSS but can no longer disagree about what a state means. The static view model cannot materialize message bodies at all, proven by a sentinel test.
+- A Claude route's endpoint generation is a named constant: broker restarts and upgrades no longer cycle Claude routes through stale and reobservation when the session is unchanged. Old hashed rows load untouched and heal exactly once through the existing session-identity rebind.
+
+### Added
+
+- A `STEER:` message delivered to Codex carries one broker-owned line naming how many earlier accepted messages are queued on that route, counted read-only at injection and omitted when zero. The stalled-queue attention item carries the live queue depth for a busy Codex route, and the dashboard states the dynamic plainly: queued mail reaches the recipient when its current turn ends; end the turn if you control it.
+- `docs/DECLINED.md`, the declined ledger: what Embassy considered and chose not to build, each with its reason. AGENTS.md and CONTRIBUTING.md carry the two-axis ticket system (effort budgets and blast-radius ratings) this release was built under.
+
+### Fixed
+
+- A monitor-only Codex route renders as needing attention with a plain-language explanation on both dashboard surfaces — never as a ready exchange with a ready pair. A quarantined provider owns its recovery guidance: discovery, restore, and registration suggestions that cannot change compatibility evidence are suppressed; observation commands remain. Unsupported-major guidance stands alone without adjacent restart noise.
+- A Claude registry record whose peer protocol is not 1 is rejected per record and included in bounded rejection evidence without stopping the broker.
+- Claude registry parsing remains strict for every required and consumed field while tolerating unknown top-level fields. Optional bounded evidence on the existing Claude connector row carries scanned/parseable-required-field totals, whether such a record has appeared since broker start, and rejected-record counts by safe code. Status and both dashboards surface that evidence so an observed-empty registry stays loud; if Claude is running, its registry layout may have changed.
+- Bounded `claude --version` observation tolerates suffixes and stderr notices and reports an unparseable banner without turning it into a misleading patch-drift failure.
+- Dashboard guidance no longer claims a broker restart abandons queued mail — the durable queue re-sends exactly once, and only a write in flight at the moment of a crash settles ambiguous. The live view's privacy footnote says which rows carry no bodies and which show retained bodies by design. The static snapshot tells a dead-broker reader to run `embassy serve`. The native stall notice names the one-hop remedy for a busy recipient. A message over the 16 KiB acceptance cap gets a hint naming the cap and the remedy.
 
 ## [1.4.1] - 2026-08-11
 

package/CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # Contributing to Embassy
 
-Embassy connects two powerful local agent runtimes across version-pinned native
+Embassy connects two powerful local agent runtimes across evidence-gated native
 interfaces. Small changes can alter permission, privacy, or delivery behavior,
 so contributions should be narrow, testable, and explicit about boundaries.
 
@@ -33,6 +33,11 @@ recovery.
 - Add deterministic regression coverage for routing, protocol, persistence,
   permission, process-lifecycle, or redaction changes.
 - Keep the pull request focused and explain every security-boundary change.
+- For every new audit check, cite the sentence it enforces in
+  [“What Embassy defends, and what it deliberately does not”](SECURITY.md#what-embassy-defends-and-what-it-deliberately-does-not).
+  If no sentence supports the check, propose the doctrine change explicitly,
+  with its product and threat-model consequence, before implementation. Do not
+  smuggle a boundary expansion into a test, review finding, or hardening patch.
 - Update README and architecture documentation when public behavior changes.
 - Verify that public files contain no credentials, native IDs, message bodies,
   local state, or personal absolute paths.
@@ -59,9 +64,36 @@ recovery.
 ### Provider adapters
 
 Claude Code's cross-session feature is official. Embassy's use of its external
-registry and peer socket shape is an internal, version-pinned adapter. Codex App
-Server is likewise version-pinned. Do not widen either compatibility range
-without a documented review and deterministic fixtures for the new version.
+registry and peer socket shape remains an internal adapter: require the
+native peer protocol 1 and bounded live-schema probes while
+validating every consumed field and frame. Unknown top-level registry fields
+may be ignored; required and consumed fields remain strict, and rejection or
+observed-empty counts must stay loud. A certified same-major build is writable;
+a same-major build whose probes all pass is `schema_attested`, but it is
+writable only when those probes cover the write path. Claude's probes do.
+Ordinary Codex compatibility and registration reads remain read-only: they may
+include `initialize`, `thread/loaded/list`, and registration-time
+`thread/resume`, but do not invoke `turn/start`. The optional Codex
+write-attestation probe is the sole exception. It may create at most one
+disposable broker-owned thread per attempt, under a bounded write fence with
+zero user-thread contact; every created probe thread is archived and confirmed
+absent from the loaded set. The probe resolves the pinned model's lowest
+advertised effort. Whenever that model/effort pin cannot resolve, it declines
+in a zero-spend fail-safe before creating any thread or model turn. Untested
+Codex 0.x therefore remains monitor-only pending a certified write schema.
+Failed
+probes, a different major, or version evidence that cannot establish a safe
+major leave only that
+provider degraded, monitor-only, and write-fenced while the broker,
+control/dashboard surfaces, and other provider remain available; probes can
+never promote across a major or unknown version. Unsafe ownership, path,
+symlink, lease, state, or generation evidence for Embassy-owned or executed
+artifacts and Embassy callback, control, or state paths still aborts startup;
+an unsafe Claude-owned external sessions registry root quarantines only Claude.
+Do not widen a supported major or declared protocol without a
+documented review and deterministic fixtures. Different-major guidance must
+safely name the observed/tested versions and supported major, say that a
+supporting Embassy release is required, and never prescribe `embassy health`.
 
 The gateway may publish one process-owned `codex-*` peer so Claude's native
 `ListAgents` and `SendMessage` tools can reach Codex. It must never overwrite a
@@ -127,8 +159,9 @@ registry discovery, peer connection, provider messaging, App Server turns, and
 SSH attachment are separate external actions.
 
 A live action requires an explicit user request that identifies its scope. For
-a message, confirm the exact destination and body, send only once, avoid fanout,
-and do not retry an ambiguous result. Never put real provider traffic in CI.
+a message, confirm the exact destination and body and avoid fanout. Follow the
+send-failure policy below for command failures; never retry a confirmed
+delivery or a recipient denial. Never put real provider traffic in CI.
 
 ## Reporting security issues
 
@@ -154,3 +187,33 @@ site, docs, in both languages:
 - The brand accent is never a state color, and state colors are never
   decoration.
 - Every alert pairs its state with the exact next command, copyable.
+
+### The declined ledger
+
+[`docs/DECLINED.md`](docs/DECLINED.md) records, per release, what we considered
+and chose not to build, each with a one-line reason. It is product
+documentation: a product that documents what it refuses to build is making the
+same promise the dashboard makes—the truth over the appearance of completeness.
+PRs that implement something in the ledger must address its reason.
+
+### Why tickets are priced by the PM
+
+The level of implementation—the one-hour version versus the one-week version—
+is a scope decision, and scope is a product judgment. The PM prices it; the
+engineer builds it faithfully within budget or contests the price with reasons.
+Economy here never means lowering the bar on what ships: it means fewer things,
+done well, and being explicit about what waits.
+
+### Send-failure policy
+
+A send or reply whose command result is an error, truncation, or ambiguity is
+not a delivery—it is a failed attempt to create one. Verify with read-only
+`status`/`delivery-status`; if no acceptance is confirmed, resend without
+asking, up to three attempts. Escalate to the PM only when a recipient
+explicitly denied the message or three resends have failed. A duplicated
+coordination message is a nuisance; a lost one deadlocks the pipeline, so
+deliverability beats ceremony. Never auto-retry a delivery the recipient's
+user denied: that is consent, not transport.
+
+For long messages, write the body to a file and pipe it
+(`embassy reply ... < body.md`); never inline `printf` for prose.

package/README.md

@@ -25,7 +25,7 @@ Embassy is built for one person, one macOS account, and agents you already trust
 
 ## Quickstart
 
-**Requirements:** macOS, Node.js 20+, Claude Code 2.1.227 (still-running 2.1.224–2.1.226 sessions remain discoverable), and Codex desktop configured to use the managed standalone App Server 0.147.0:
+**Requirements:** macOS, Node.js 20+, Claude Code on the supported 2.x major with peer protocol 1, and Codex desktop configured to use its managed standalone App Server. Embassy was last live-tested with Claude Code 2.1.227 and Codex App Server 0.147.0; those patch versions are evidence, not startup pins:
 
 ```bash
 ~/.codex/packages/standalone/current/codex app-server daemon start
@@ -34,7 +34,9 @@ Embassy is built for one person, one macOS account, and agents you already trust
 
 The first command starts the managed daemon if it is not already running (`restart` and `stop` also exist); the second launches the ChatGPT desktop app pointed at it. `CODEX_APP_SERVER_USE_LOCAL_DAEMON` is not documented by OpenAI; it is observed to work with this Desktop build and may change. Run the daemon command from a normal terminal, never from inside an agent session: Codex tasks inherit the daemon's environment, so a daemon started inside a Claude Code session leaks that session's identity into every task and registration fails closed with `CALLER_IDENTITY_CONFLICT` — fix it from a normal terminal with `codex app-server daemon restart`. The Claude session you select as a destination needs [`crossSessionInbound`](docs/CONFIGURATION.md) enabled — that is Claude Code's own setting, configured in Claude Code, not in Embassy.
 
-Provider compatibility needs no separate operator step. `embassy serve` automatically validates the release's exact Claude and Codex version pins and fails closed on unknown versions or required protocol shapes.
+Desktop attaches to the managed standalone App Server when it launches. If the daemon restarts while Desktop is already open, waiting alone does not reconnect that app process: fully quit Desktop, rerun `/usr/bin/open --env CODEX_APP_SERVER_USE_LOCAL_DAEMON=1 -a ChatGPT`, and reopen the exact task.
+
+Provider compatibility needs no separate operator step. `embassy serve` attests the resolved installations and applies one evidence ladder to both providers. A certified same-major build is writable; a same-major build outside this release's tested inventory is shown as `schema_attested` when every bounded live-schema probe passes and is writable only when those probes cover its write path. Claude's probes cover its native write path. Ordinary Codex compatibility and registration reads remain read-only: they may include `initialize`, `thread/loaded/list`, and registration-time `thread/resume`, but do not invoke `turn/start`. The optional Codex write-attestation probe is the sole exception. It may create at most one disposable broker-owned thread per attempt, under a bounded write fence with zero user-thread contact; every created probe thread is archived and confirmed absent from the loaded set. The probe resolves the pinned model's lowest advertised effort. Whenever that model/effort pin cannot resolve, it declines in a zero-spend fail-safe before creating any thread or model turn. Untested Codex 0.x therefore stays monitor-only pending a certified write schema. Failed probes, a different major, or version evidence that cannot establish a safe major leave only that provider degraded, monitor-only, and write-fenced. Probes never promote across a major or compensate for unknown major evidence; a different-major alert names the observed/tested versions and supported major and says that an Embassy release supporting the observed major is required. In every degraded case, the broker, control/dashboard surfaces, and other provider keep running. Only unsafe OS evidence for Embassy-owned or executed artifacts and Embassy callback, control, or state paths refuses broker startup; unsafe UID or mode evidence on Claude's external sessions registry root quarantines only Claude. A Claude session record whose peer protocol is not 1 is rejected in isolation and counted.
 
 > **Known limitation:** Embassy can reach Codex tasks only while Desktop uses the managed standalone App Server. In that mode, tasks currently cannot connect to Desktop's built-in in-app browser (`@Browser` loads but does not attach). Switching Desktop back to its default private App Server restores the built-in browser immediately — but makes those tasks unreachable by Embassy. No other capability regressions have been identified, though this was not an exhaustive parity test.
 
@@ -222,15 +224,16 @@ Codex tasks can then be prompted with `$embassy-peer`; Claude Code discovers it
 | `reply` | conversation-token holder | Continue an active conversation with the full token returned to the initiator or delivered in the recipient's broker-owned reply hint: `--conversation conv_<token> --alias <your-alias>`, body on stdin, optional `--track [--idle-minutes <n>]` |
 
 `--track` opens a progress watch over the conversation; `--idle-minutes <n>`
-sets how long the watched thread may idle before the watch reports a stall
-(1–1440, default 5, rejected without `--track`). Close a watch with `untrack`,
+sets the idle interval for bounded liveness nudges (1–1440, default 5, rejected
+without `--track`). If the watch ultimately times out, Embassy records it only
+in watch history and emits no runtime stall alert. Close a watch with `untrack`,
 or by replying with a leading `DONE:`. See [Delivery](docs/DELIVERY.md).
 
 ## Safety in one minute
 
 - **Local broker, stable loopback dashboard.** `embassy serve` listens on private Unix-domain sockets and makes no provider API call. The opt-in `embassy dashboard --live` companion is a separate process and the only listener Embassy can create, bound to exact `127.0.0.1` on stable port `41961` by default (or the per-invocation `--port <n>`). It is deliberately unauthenticated local HTTP for a trusted single-user machine; Host, Origin, and sentinel checks constrain browser-origin requests but do not authenticate local processes or OS users.
 - **Same-UID containment, not authentication.** Caller identity is inherited from the local process environment. Route ownership and generation checks reduce mistakes, but are not a defense against code already running as your OS user.
-- **Compatibility is automatic and exact-pinned.** Broker/provider startup validates only the release's reviewed versions and protocol shapes. Every replacement App Server endpoint generation gets a fresh monitor-only check before route re-anchoring; unknown versions and malformed generations stay write-disabled.
+- **Compatibility follows evidence, not patch pins.** Broker/provider startup attests exact filesystem ownership and paths, then applies the evidence ladder. Certified same-major builds are writable; fully probed same-major builds are `schema_attested` and writable only when the probes cover writes. Ordinary Codex compatibility and registration reads remain read-only: they may include `initialize`, `thread/loaded/list`, and registration-time `thread/resume`, but do not invoke `turn/start`. The optional Codex write-attestation probe is the sole exception. It may create at most one disposable broker-owned thread per attempt, under a bounded write fence with zero user-thread contact; every created probe thread is archived and confirmed absent from the loaded set. The probe resolves the pinned model's lowest advertised effort. Whenever that model/effort pin cannot resolve, it declines in a zero-spend fail-safe before creating any thread or model turn. Untested Codex 0.x therefore remains monitor-only. Failed probes, a different major, or unknown version evidence fence only that provider while the broker and other provider keep running. Probes never promote across a major or unknown version. Unsafe Embassy-owned/executed artifacts and Embassy callback/control/state paths still refuse startup; an unsafe Claude-owned sessions registry root quarantines only Claude.
 - **Native permissions stay native.** Embassy sends no Codex approval or sandbox overrides and answers no approval request. `crossSessionInbound` remains Claude's own control; Embassy cannot override it.
 - **Provenance is marked, not authenticated.** Routed bodies carry one broker-owned cross-session marker with the verified sender alias; it distinguishes the transport path for the receiving model but cannot make untrusted text safe or authenticate against code already running as your OS user.
 - **Bodies stored, bounded, and yours.** Message bodies persist in the broker's private mode-0600 state under bounded retention so the ledger can show you the mail itself; queued mail survives a broker restart and re-sends exactly once. Raw provider frames stay memory-only. The static dashboard files remain metadata-only; the live dashboard shows retained bodies.

package/README.zh-CN.md

@@ -25,7 +25,7 @@ Embassy 专为单人、单一 macOS 账户以及你已信任以该用户身份
 
 ## 快速开始
 
-**前置要求：** macOS、Node.js 20+、Claude Code 2.1.227（仍在运行的 2.1.224–2.1.226 会话保持可发现），以及配置为使用托管独立 App Server 0.147.0 的 Codex 桌面应用：
+**前置要求：** macOS、Node.js 20+、使用已支持 2.x 主版本且对等协议为 1 的 Claude Code，以及配置为使用托管独立 App Server 的 Codex 桌面应用。Embassy 最近完成实机测试的版本是 Claude Code 2.1.227 与 Codex App Server 0.147.0；这些补丁版本是测试证据，而非启动固定值：
 
 ```bash
 ~/.codex/packages/standalone/current/codex app-server daemon start
@@ -34,7 +34,9 @@ Embassy 专为单人、单一 macOS 账户以及你已信任以该用户身份
 
 第一条命令在托管守护进程未运行时启动它（也提供 `restart` 与 `stop` 子命令）；第二条以指向该守护进程的方式启动 ChatGPT 桌面应用。`CODEX_APP_SERVER_USE_LOCAL_DAEMON` 未见于 OpenAI 文档；它经验证适用于当前 Desktop 构建，未来可能变化。请在普通终端中运行守护进程命令，切勿在代理会话内运行：Codex 任务会继承守护进程的环境，因此在 Claude Code 会话内启动的守护进程会把该会话的身份泄漏到每个任务中，注册将以 `CALLER_IDENTITY_CONFLICT` 关闭失败——请在普通终端执行 `codex app-server daemon restart` 修复。你选择作为目的地的 Claude 会话需要启用 [`crossSessionInbound`](docs/CONFIGURATION.zh-CN.md)——这是 Claude Code 自身的设置，在 Claude Code 中配置，而非在 Embassy 中。
 
-提供方兼容性无需操作员执行额外步骤。`embassy serve` 会自动验证本发布版精确固定的 Claude 与 Codex 版本，并在遇到未知版本或必需协议结构时关闭失败。
+Desktop 仅在启动时附着到托管独立 App Server。如果 Desktop 已打开时守护进程重启，单纯等待不会让该应用进程重新连接：请完全退出 Desktop，重新运行 `/usr/bin/open --env CODEX_APP_SERVER_USE_LOCAL_DAEMON=1 -a ChatGPT`，再打开该确切任务。
+
+提供方兼容性无需操作员执行额外步骤。`embassy serve` 会验证解析到的安装边界，并对两种提供方应用同一套证据阶梯：同主版本且在已认证清单中的构建可写；同主版本但不在本发布版已测清单中的构建，在全部有界实时结构探测通过后显示为 `schema_attested`，但只有探测覆盖写入路径时才可写。Claude 探测覆盖原生写入路径。常规 Codex 兼容性与注册读取仍保持只读：它们可能包括 `initialize`、`thread/loaded/list` 与注册时的 `thread/resume`，但不会调用 `turn/start`。唯一例外是可选的 Codex 写入认证探测：每次尝试最多可创建一个代理自有的临时线程，在有界写入围栏下运行且绝不接触用户线程；每个已创建的探测线程都会被归档，并确认已从已加载集合中清除。该探测会解析固定模型所公布的最低 effort。只要该模型/effort 固定项无法解析，探测就会以零消耗故障安全方式拒绝，并且不会创建任何线程或模型轮次。未测试的 Codex 0.x 在认证写入结构出现前保持仅监控。探测失败、主版本不同或版本证据无法建立安全主版本时，只有该提供方保持降级、仅监控并禁止写入，代理、控制面/仪表盘和另一提供方继续运行。探测绝不能跨主版本或未知主版本提升权限。主版本不同的告警会列出已观测/已测版本和支持主版本，并说明必须使用支持已观测主版本的 Embassy 发布版。只有 Embassy 自有或执行的构件及其回调、控制与状态路径出现不安全 OS 证据时才会拒绝代理启动；Claude 外部会话注册表根目录的 UID 或模式不安全时，只隔离 Claude。对等协议不是 1 的 Claude 会话记录会单独被拒绝并计数。
 
 > **已知限制：** 仅当 Desktop 使用托管独立 App Server 时，Embassy 才能访问 Codex 任务。在该模式下，任务目前无法连接 Desktop 内置的应用内浏览器（`@Browser` 可加载但无法附着）。将 Desktop 切换回其默认的私有 App Server 会立即恢复内置浏览器——但会使这些任务对 Embassy 不可达。目前未发现其他能力回退，但这并非穷尽的能力对比测试。
 
@@ -196,13 +198,13 @@ cp -R "$(npm root -g)/agent-embassy/skills/embassy-peer" ~/.claude/skills/
 | `send-to-codex` | Claude 会话 | 标志与正文输入方式相同，使用继承的原生回复标识 |
 | `reply` | 对话令牌持有方 | 使用初始发送时返回或随入站来源提示收到的完整令牌继续一个活跃对话：`--conversation conv_<token> --alias <你的别名>`，正文从标准输入读取，可选 `--track [--idle-minutes <n>]`；调用方、对话参与关系和路由会重新检查 |
 
-`--track` 会为该对话开启一个进度监视；`--idle-minutes <n>` 设置被监视线程在监视报告停滞前可以空闲多久（1–1440，默认 5，未加 `--track` 时会被拒绝）。用 `untrack` 关闭监视，或在回复正文开头使用 `DONE:` 关闭。详见[投递](docs/DELIVERY.zh-CN.md)。
+`--track` 会为该对话开启一个进度监视；`--idle-minutes <n>` 设置有界活跃提醒的空闲间隔（1–1440，默认 5，未加 `--track` 时会被拒绝）。如果监视最终超时，Embassy 只在监视历史中记录该结算，不会发出运行时停滞告警。用 `untrack` 关闭监视，或在回复正文开头使用 `DONE:` 关闭。详见[投递](docs/DELIVERY.zh-CN.md)。
 
 ## 一分钟了解安全性
 
 - **本地代理，稳定的 loopback 仪表盘。** `embassy serve` 仅监听私有 Unix 域套接字，不发起任何提供商 API 调用。可选启用的 `embassy dashboard --live` 组件是一个独立进程，也是 Embassy 能创建的唯一监听器；它精确绑定 `127.0.0.1`，默认使用稳定端口 `41961`（也可为本次启动传入 `--port <n>`）。它是在可信单用户机器上有意不设身份认证的本地 HTTP；Host、Origin 与哨兵检查约束浏览器来源的请求，但不认证本地进程或 OS 用户。
 - **同 UID 隔离，而非身份认证。** 调用者身份继承自本地进程环境。路由所有权和生成号检查能减少误操作，但不是对已以你的 OS 用户身份运行的代码的防御。
-- **兼容性检查自动执行并精确固定版本。** 代理/提供方启动只验证本发布版已审查的版本和协议结构。每个替代 App Server 端点代际都必须先通过新的仅监控检查才能重新锚定路由；未知版本与结构异常的代际保持禁止写入。
+- **兼容性依据证据，而非固定补丁版本。** 代理/提供方启动先验证精确的 OS 边界，再应用证据阶梯。同主版本的已认证构建可写；全部探测通过的同主版本构建显示为 `schema_attested`，且仅在探测覆盖写入时才可写。常规 Codex 兼容性与注册读取仍保持只读：它们可能包括 `initialize`、`thread/loaded/list` 与注册时的 `thread/resume`，但不会调用 `turn/start`。唯一例外是可选的 Codex 写入认证探测：每次尝试最多可创建一个代理自有的临时线程，在有界写入围栏下运行且绝不接触用户线程；每个已创建的探测线程都会被归档，并确认已从已加载集合中清除。该探测会解析固定模型所公布的最低 effort。只要该模型/effort 固定项无法解析，探测就会以零消耗故障安全方式拒绝，并且不会创建任何线程或模型轮次。未测试的 Codex 0.x 保持仅监控。探测失败、主版本不同或版本证据未知时，只封锁该提供方，代理和另一提供方继续运行。探测绝不能跨主版本或未知版本提升权限。Embassy 自有或执行的构件及其回调、控制与状态路径不安全时仍拒绝启动；Claude 外部会话注册表根目录不安全时只隔离 Claude。
 - **来源标记是提示，不是签名。** Embassy 在提供方写入边界生成跨会话来源封装，让接收模型能够区分代理路由消息及其已验证发送方别名；这不是密码学证明，也不会把不可信正文变成可信指令。
 - **原生权限保持原生。** Embassy 不发送任何 Codex 审批或沙盒覆盖，也不应答任何审批请求。`crossSessionInbound` 仍是 Claude 自身的控制机制；Embassy 无法覆盖它。
 - **消息体有界保存，属于你。** 消息体以有界保留策略持久化在 broker 的私有 mode-0600 状态中，让台账能够展示邮件本身；排队中的邮件在 broker 重启后幸存并恰好重发一次。原始提供方帧仍仅存于内存。静态仪表盘文件保持仅元数据；实时仪表盘展示保留的正文。

package/SECURITY.md

@@ -49,6 +49,71 @@ against other processes running as the same OS user.
   environment or socket capabilities. Embassy is not a sandbox for untrusted
   same-user code.
 
+## What Embassy defends, and what it deliberately does not
+
+Embassy's security boundary is intentionally narrower than “protect this user
+from every process this user runs.” The boundary below governs implementation,
+review, and audit work.
+
+### What Embassy defends
+
+- **The same-UID OS and artifact boundary for anything Embassy executes or
+  treats as identity evidence.** Embassy validates canonical paths, ownership,
+  symlink policy, modes, approved version-directory containment, its own state
+  and sockets, and the generation of artifacts it owns. Before acting on an
+  identity-bearing input—such as an inherited task identity, provider record,
+  endpoint binding, route, or reply request—it validates the input's bounded
+  shape and its current ownership, correlation, and generation. Unsafe
+  controller-wide evidence is fatal; this class comprises Embassy-owned or
+  executed artifacts and Embassy callback, control, and state paths. The
+  Claude-owned external sessions registry root is instead a read-side identity
+  source: unsafe UID or mode evidence quarantines and write-fences only Claude,
+  with a loud observation, while the broker and other provider stay available.
+  A bad provider record, endpoint, or acted-on input is rejected or fenced at
+  that artifact rather than accepted on a best-effort basis.
+- **Honest provenance at the message boundary.** The broker creates the outer
+  `cross-session-message` frame and first-child reply hint from validated route
+  metadata, and neutralizes body text shaped like its reserved framing tags
+  before composition. Those marks tell the receiver which transport path and
+  sender alias Embassy observed. They are not a signature, and every delivered
+  body remains untrusted input whose claims and requested actions require the
+  receiver's normal judgment, sandbox, and approval policy.
+- **Anti-runaway containment.** Queue counts and bytes, message and frame sizes,
+  callbacks, conversations, retained bodies, deduplication records, rate
+  windows, and deadlines are bounded. Exhaustion rejects, expires, or fences
+  work with an explicit result; a bound never creates permission or justifies
+  replaying an ambiguous write.
+
+### What Embassy deliberately does not defend
+
+- **Other local software already running as the same user.** Embassy provides
+  no local-process authentication and no capability or local-user consent
+  boundary against software already operating under that UID. Pair edges encode
+  routing consent between agent endpoints; aliases, conversation tokens,
+  inherited environment values, private sockets, and same-user file modes do
+  not authenticate one same-user process from another.
+- **Local software through browser-origin checks.** Exact Host, Origin, the
+  `X-Embassy-Request` sentinel, and same-origin response policy constrain what a
+  browser can issue or read across origins. They do not authenticate a loopback
+  caller, its process, or its UID; the live dashboard assumes a trusted
+  single-user machine.
+- **Predictions based on version strings.** A version string is a compatibility
+  observation, never security evidence or attack detection. Directly observed
+  path, ownership, protocol, schema, and generation facts outrank prediction
+  from a version string. Within the security boundary, boot refusal is reserved
+  for an unsafe or lost singleton lease, corrupt controller state, or unsafe
+  OS-boundary attestation. Version drift, an unparseable version, failed probes,
+  or one incompatible provider degrades and write-fences that surface; it does
+  not take down the broker or the other provider.
+
+### Audit rule
+
+Every new audit check must cite the sentence in this doctrine that it enforces.
+If the proposed check has no supporting sentence here, raise it explicitly as
+a doctrine-change proposal, including the product and threat-model consequence,
+before adding the check. A test, review finding, or “hardening” patch must not
+silently expand Embassy's claimed boundary.
+
 ## Routing and consent
 
 - A Codex task must explicitly self-register with a `codex-*` alias before it
@@ -107,19 +172,51 @@ broker.
   only listeners are private Unix-domain sockets. The opt-in
   `embassy dashboard --live` companion is a separate process with its own
   loopback HTTP listener — see "Live companion boundary" below.
-- Provider protocols are exact-version-pinned. Provider startup automatically
-  validates the release's reviewed Claude launcher/runtime, Claude peer-version
-  inventory and protocol, and Codex App Server version. Unknown versions or
-  required schemas fail closed. Every replacement Codex endpoint generation
-  starts monitor-only and remains write-fenced until its fresh initialize and
-  exact-task listing checks pass and the controller activates it.
-- Embassy publishes at most one visibly prefixed, process-owned `codex-*`
-  record in Claude's registry. It creates one callback socket and removes only
-  exact-owned artifacts whose generation still matches during graceful
-  shutdown.
-- App Server methods are allowlisted. Embassy exposes no archive, deletion,
-  shell, configuration, authentication, plugin, history, approval-response, or
-  generic RPC method.
+- Provider compatibility is evidence-gated rather than patch-version-pinned.
+  Provider startup first validates exact OS ownership, path, symlink, lease,
+  state, and generation evidence. Unsafe evidence for Embassy-owned or executed
+  artifacts and Embassy callback, control, or state paths refuses broker
+  startup; unsafe UID or mode evidence for Claude's external sessions registry
+  root quarantines and write-fences only Claude.
+  A certified same-major provider build is writable. A same-major build whose
+  bounded live-schema probes all pass is `schema_attested` and writable only
+  when those probes cover the write path. Claude's probes cover its native
+  write path. Ordinary Codex compatibility and registration reads remain
+  read-only: they may include `initialize`, `thread/loaded/list`, and
+  registration-time `thread/resume`, but do not invoke `turn/start`. The
+  optional Codex write-attestation probe is the sole exception. It may create
+  at most one disposable broker-owned thread per attempt, under a bounded write
+  fence with zero user-thread contact; every created probe thread is archived
+  and confirmed absent from the loaded set. The probe resolves the pinned
+  model's lowest advertised effort. Whenever that model/effort pin cannot
+  resolve, it declines in a zero-spend fail-safe before creating any thread or
+  model turn. Untested Codex 0.x therefore stays monitor-only pending a
+  certified write schema. Failed
+  probes, a different major, or version evidence that cannot establish a safe
+  major leave only that
+  provider degraded, monitor-only, and write-fenced while the broker,
+  control/dashboard surfaces, and other provider remain available; probes
+  never promote across a major or unknown version. A Claude
+  session record whose peer protocol is not 1 is rejected in isolation and
+  included in bounded rejection evidence. Every replacement Codex endpoint
+  generation remains write-fenced until its fresh initialize and exact-task
+  listing checks pass and the controller activates it.
+- Embassy publishes at most one process-owned `codex-*` record in Claude's
+  registry with the supported explicit versioned Embassy-advertisement marker.
+  The prefix is a visible alias convention, not the discriminator: an unmarked
+  genuine Claude session named `codex-*` remains discoverable. Embassy creates
+  one callback socket and removes only exact-owned artifacts whose generation
+  still matches during graceful shutdown.
+- App Server methods are allowlisted. Ordinary connectors expose no archive,
+  deletion, shell, configuration, authentication, plugin, history,
+  approval-response, or generic RPC method. The optional write-attestation
+  probe alone may call `thread/archive`, only for its validated disposable
+  broker-owned probe thread; it then confirms that thread is absent from the
+  loaded set. The probe resolves the pinned model's lowest advertised effort.
+  Whenever that model/effort pin cannot resolve, it declines in a zero-spend
+  fail-safe before creating any thread or model turn. No archive method is
+  exposed to ordinary routes, and the other excluded method classes remain
+  excluded everywhere.
 - `turn/steer` is reachable only for an exact leading `STEER:` body in the
   Claude-to-Codex direction, with an exact observed active-turn ID. App Server
   admits it at the next tool-call boundary; Embassy never interrupts or injects
@@ -127,7 +224,7 @@ broker.
   retains at most three steers per route. The environment kill switch defaults
   on and can disable this classification globally. Interrupt remains limited to
   an exact turn started and positively observed by the same connector.
-- Exact App Server 0.147.0 initialization enables `experimentalApi: true`
+- The tested App Server 0.147.0 initialization enables `experimentalApi: true`
   solely for `thread/resume.excludeTurns: true`. It adds no general
   experimental method or authority. Missing, malformed, or nonempty returned
   turns fail closed and are never retained.
@@ -163,7 +260,7 @@ kernel lock.
 Embassy's provider-facing access is intentionally enumerable:
 
 - read and execute the configured Claude launcher only for bounded automatic
-  exact-version validation;
+  path, version-banner, and compatibility observation;
 - read the live Claude session registry and connect validated peer sockets;
 - create and later remove its one callback socket and one registry record;
 - resolve the managed Codex installation and attach to the already-running
@@ -171,10 +268,13 @@ Embassy's provider-facing access is intentionally enumerable:
 - inspect canonical filesystem metadata needed to validate provider-advertised
   endpoints and generations.
 
-Claude-owned registry files and peer sockets are accepted according to actual
-filesystem accessibility plus bounded schema, type, PID/path correlation,
-liveness, and generation checks. Embassy does not treat provider-owned Unix
-owner or mode bits as an additional routing policy.
+The Claude-owned external sessions registry root must be owned by the current
+UID with exact mode 0700 before Embassy enumerates it; failure quarantines and
+write-fences only Claude. Within an admitted root, individual registry records
+and peer sockets retain their bounded schema, file/socket type, PID/path and
+allowed-root correlation, accessibility, liveness, and generation checks.
+Embassy invents no additional owner or mode rule for those individual
+provider-owned artifacts.
 
 Embassy does not need or intentionally read credentials, Keychain items,
 Claude project history, Codex or Claude transcripts, shell history, or provider
@@ -253,14 +353,39 @@ because this surface intentionally has no such authentication boundary.
 Routine tests use temporary directories, fake peers, and fake App Server
 transports. They do not inspect live provider state or contact a model.
 
-Compatibility admission is automatic and exact-pinned. Broker/provider startup
-owns the bounded read-only validation of the configured installations, exact
-versions, protocol constants, and required schemas; an unknown same-major build
-is not admitted. These checks do not route a user message or start a model
-turn. A replacement Codex endpoint generation receives its own fresh
-monitor-only initialize and exact-task listing check, while the write gate
-stays closed until controller activation. Runtime record, frame, response,
-identity, generation, and deadline checks remain mandatory after admission.
+Compatibility admission is automatic and evidence-gated. Broker/provider
+startup owns bounded read-only validation of the configured installations,
+exact OS boundaries, provider majors, declared protocol constants, and live
+schemas. Unsafe Embassy-owned/executed artifacts or Embassy callback, control,
+or state paths remain startup-fatal; unsafe UID or mode evidence on Claude's
+external sessions registry root quarantines only that provider. Certified
+same-major builds are writable. Fully probed same-major
+builds are `schema_attested` and writable only where the probes cover writes.
+Ordinary Codex compatibility and registration reads remain read-only: they may
+include `initialize`, `thread/loaded/list`, and registration-time
+`thread/resume`, but do not invoke `turn/start`. The optional Codex
+write-attestation probe is the sole exception. It may create at most one
+disposable broker-owned thread per attempt, under a bounded write fence with
+zero user-thread contact; every created probe thread is archived and confirmed
+absent from the loaded set. The probe resolves the pinned model's lowest
+advertised effort. Whenever that model/effort pin cannot resolve, it declines
+in a zero-spend fail-safe before creating any thread or model turn. Untested
+Codex 0.x therefore remains monitor-only. Failed
+probes, different majors, and
+version evidence that cannot establish a safe major remain provider-local
+monitor-only states; the
+broker and other provider stay available, and no probe can promote across a
+major or unknown version. Different-major guidance
+names the observed/tested versions and supported major and requires an Embassy
+release supporting the observed major. These checks do not route a user
+message or start a model turn. Claude
+registry parsing remains strict for every required and consumed field while
+ignoring unknown top-level fields; bounded rejected-record counts and an
+observed-empty registry are surfaced instead of hidden. A replacement Codex
+endpoint generation receives its own fresh monitor-only initialize and
+exact-task listing check, while the write gate stays closed until controller
+activation. Runtime record, frame, response, identity, generation, and
+deadline checks remain mandatory after admission.
 
 Passive live discovery, a live provider connection, a native message, and an
 App Server turn are distinct authorization gates. Each requires an explicit

package/dist/src/gateway/claude-peer.d.ts

@@ -11,8 +11,6 @@ export declare const CLAUDE_PEER_COMPATIBILITY: Readonly<{
     peerProtocol: 1;
     messageVersion: 1;
 }>;
-/** Live peer records may outlive a same-protocol Claude Code upgrade. */
-export declare const CLAUDE_PEER_COMPATIBLE_SESSION_VERSIONS: readonly ["2.1.224", "2.1.225", "2.1.226", "2.1.227"];
 export declare const claudePeerStatuses: readonly ["busy", "shell", "idle", "waiting"];
 export type ClaudePeerStatus = (typeof claudePeerStatuses)[number];
 export declare const claudePeerKinds: readonly ["interactive", "bg", "daemon", "daemon-worker"];
@@ -33,7 +31,7 @@ export type ClaudePeerDiscovery = {
     truncated: boolean;
     /** Bounded registry entries examined, including safely skipped records. */
     entriesScanned: number;
-    /** Records whose closed wire schema parsed before later liveness checks. */
+    /** Records whose required known fields parsed before later liveness checks. */
     parseableRecords: number;
 };
 export type ClaudePeerTransportStatus = "connecting" | "write_started" | "transport_written" | "ambiguous" | "not_written";
@@ -88,7 +86,7 @@ export type ClaudePeerConnect = (socketPath: string) => Socket;
 export type ClaudePeerAdapterOptions = {
     sessionsDir: string;
     socketDir: string;
-    /** Exact version attested by the trusted launcher, never user input. */
+    /** Bounded version evidence attested by the trusted launcher, never user input. */
     attestedClaudeCodeVersion: string;
     /** Locale for bounded user-visible gateway notices written to Claude. */
     locale?: DashboardLocale;
@@ -107,6 +105,8 @@ export type ClaudePeerAdapterOptions = {
 };
 /** Dependency seams for deterministic tests; never populate from config. */
 export type ClaudePeerAdapterTestOverrides = {
+    /** Deterministic owner-mismatch seam; production always uses process.getuid(). */
+    expectedUid?: number;
     processInspector?: ClaudeProcessInspector;
     connect?: ClaudePeerConnect;
     now?: () => number;
@@ -122,6 +122,7 @@ export type ClaudePeerAdapterTestOverrides = {
     userHome?: string;
     tempRoots?: readonly string[];
     registryPublicationHook?: (stage: "before_rename" | "after_rename") => void | Promise<void>;
+    postBindHook?: (socketPath: string) => void | Promise<void>;
 };
 export type ClaudePeerRegistryPublicationOutcome = "published" | "not_published" | "unknown";
 export type ClaudePeerListenerOptions = {
@@ -159,6 +160,7 @@ type ParsedRegistryRecord = {
     messagingSocketPath: string;
     name: string;
     status: ClaudePeerStatus;
+    embassyAdvertisement: boolean;
 };
 type TargetBinding = {
     targetId: string;
@@ -230,6 +232,7 @@ type ListenerCreateOptions = {
     runRegistryMutation: <T>(operation: () => Promise<T>) => Promise<T>;
     preparedGeneration?: string;
     registryPublicationHook?: (stage: "before_rename" | "after_rename") => void | Promise<void>;
+    postBindHook: ClaudePeerAdapterTestOverrides["postBindHook"];
     onClosed: () => void;
 };
 export declare class ClaudePeerListener {