agent-embassy 1.6.1 → 1.7.0

package/docs/CONFIGURATION.md

@@ -1,8 +1,8 @@
-# Configuration and compatibility
+# Configuration and provider contracts
 
 Embassy is configured through environment variables read when each command
-starts. This document collects every variable, the compatibility contract with
-Claude Code and the Codex App Server, managed-binary resolution rules, and
+starts. This document collects every variable, provider transport contracts,
+managed-launch resolution rules, and
 the addressing model. There is no configuration file; all values are env vars
 or CLI flags.
 
@@ -14,6 +14,7 @@ or CLI flags.
 | --- | --- | --- |
 | `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 |
@@ -79,19 +80,19 @@ the send reaches the Claude end. If registration and selection both succeeded
 but your first `send-to-claude` does not arrive, check `crossSessionInbound` on
 the destination session before suspecting the route.
 
-## Compatibility contract
+## Provider and runtime contract
 
-Embassy speaks two provider surfaces that are not documented as stable third-party APIs. Compatibility is automatic and evidence-based, not an operator workflow or an exact patch-version pin. This release was last live-tested with Claude Code 2.1.227 and Codex App Server 0.147.0, but applies the same five-step ladder to each provider.
+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.
 
-A certified version on the supported major is writable as `certified`. A same-major build outside the tested inventory appears as `schema_attested` when all bounded live-schema probes pass and is writable only when those probes cover its write path. Claude's probes cover the native peer 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. An untested Codex build therefore stays monitor-only pending a certified write schema. A same-major build whose probes fail stays degraded, monitor-only, and write-fenced. A different major or version evidence that cannot establish a safe major also stays provider-local monitor-only and can never be promoted by probes. An exact official launcher target may supply separate bounded major evidence even when its banner is unparseable; probes alone never compensate for unknown major evidence. In every degraded case, the broker, control socket, dashboards, and other provider remain available. The different-major alert safely names the observed and tested versions plus this release's supported major and says that an Embassy release supporting the observed major is required; `embassy health` is not a recovery step.
+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.
 
-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 quarantines and write-fences only Claude, with a loud observation, while the broker and other provider 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.
+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.
 
-Before granting write authority, the broker owns bounded compatibility and registration reads: it checks the configured launcher or managed installation, filesystem ownership and path shape, registry/control-socket shape, `initialize` and `thread/loaded/list` schemas, declared protocol constants, and—during Codex registration—an exact `thread/resume` with history excluded. These ordinary reads do not route a user message, retain history, or 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. 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 existing Claude connector row in public status carries optional bounded `registry` evidence: `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.
+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.
 
-Every replacement Codex App Server endpoint generation starts monitor-only. Embassy performs a fresh initialize and `thread/loaded/list` check on that generation, then re-anchors a retained route only when its exact private task identity is found once. Writes remain fenced until the controller activates that exact generation. A version or schema mismatch, missing task, duplicate task, or unclean transition leaves the route stale and write-disabled rather than retargeting it.
+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`. Version banners are bounded observations: a suffix or bounded stderr notice does not itself make the gateway unavailable, while a version that cannot be identified is surfaced for diagnosis. Provider updates within the supported major therefore do not require a patch-pin release, but still must pass the live schema and declared-protocol checks above to become writable. A different major needs an Embassy release that supports 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.
 
 ## Addressing
 

package/docs/CONFIGURATION.zh-CN.md

@@ -1,6 +1,6 @@
-# 配置与兼容性
+# 配置与提供方契约
 
-Embassy 通过各命令启动时读取的环境变量进行配置。本文档汇集了所有变量、与 Claude Code 和 Codex App Server 的兼容性约定、托管二进制文件解析规则，以及寻址模型。没有配置文件；所有值均为环境变量或 CLI 标志。
+Embassy 通过各命令启动时读取的环境变量进行配置。本文档汇集所有变量、提供方传输契约、托管启动解析规则与寻址模型。没有配置文件；所有值均为环境变量或 CLI 标志。
 
 ---
 
@@ -10,6 +10,7 @@ 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`，其他值均为配置错误 |
@@ -49,19 +50,19 @@ Embassy 通过各命令启动时读取的环境变量进行配置。本文档汇
 
 这是你唯一必须主动开启的前置条件，也是最常见的首次运行故障——因为它**失败得很晚**。快速开始的第 3 步（`select-claude`）无论该设置是否启用都会打印 `"accepted":true`：选择只创建 Embassy 自己的权限边，从不查询 Claude 的原生入站策略。拒绝要到第 4 步、消息抵达 Claude 端时才出现。如果注册与选择都成功，但你的第一条 `send-to-claude` 没有送达，请先检查目的地会话上的 `crossSessionInbound`，再去怀疑路由。
 
-## 兼容性约定
+## 提供方与运行时契约
 
-Embassy 使用两个未被记录为稳定第三方 API 的提供方接口。兼容性检查自动依据证据，不是操作员工作流，也不精确固定补丁版本。本发布版最近完成实机测试的版本是 Claude Code 2.1.227 与 Codex App Server 0.147.0，并对每种提供方应用同一套五步阶梯。
+Embassy 路由四种提供方：Claude 使用对等协议 1，Codex 使用托管 App Server，DeepSeek 与 Grok Build 使用 ACP v1。发布版自有的[支持矩阵](../support/provider-support-matrix.json)记录离线测试的精确构件、协议、能力、停止保真度、限制与测试日期；运行时从不导入它。构建或版本事实可以限定发布版“已测试”的说法，但绝不授予或撤销路由权限。
 
-支持主版本内的已认证版本以 `certified` 可写运行。同主版本但不在已测清单中的构建，在全部有界实时结构探测通过后显示为 `schema_attested`，且只有探测覆盖写入路径时才可写。Claude 探测覆盖原生对等写入路径。常规 Codex 兼容性与注册读取仍保持只读：它们可能包括 `initialize`、`thread/loaded/list` 与注册时的 `thread/resume`，但不会调用 `turn/start`。唯一例外是可选的 Codex 写入认证探测：每次尝试最多可创建一个代理自有的临时线程，在有界写入围栏下运行且绝不接触用户线程；每个已创建的探测线程都会被归档，并确认已从已加载集合中清除。该探测会解析固定模型所公布的最低 effort。只要该模型/effort 固定项无法解析，探测就会以零消耗故障安全方式拒绝，并且不会创建任何线程或模型轮次。未测试的 Codex 构建在认证写入结构出现前保持仅监控。同主版本但探测失败时，该提供方保持降级、仅监控并禁止写入。主版本不同或版本证据无法建立安全主版本时，该提供方同样只进入仅监控状态，且探测绝不能跨主版本或未知主版本提升权限。即使版本标幅无法解析，精确的官方启动器目标也可能提供独立的有界主版本证据；仅靠探测绝不能弥补未知主版本证据。所有降级情况下，代理、控制套接字、仪表盘和另一提供方继续运行。主版本不同的告警会安全列出已观测与已测版本以及本发布版支持的主版本，并说明必须使用支持已观测主版本的 Embassy 发布版；`embassy health` 不是恢复步骤。
+运行时采用尽力而为模式：显式同意边加上精确自有路由/会话身份会授权一次尝试。当前连接器、路由代际、被消费协议字段的严格结构与相关操作决定结果。接口变化或可选提供方缺失会显示为提供方局部的降级/离线健康度、路由陈旧状态与精确安全代码；它不会产生兼容性等级，也不会阻止其他提供方。
 
-只有 Embassy 自有或执行的构件及其回调、控制或状态路径出现不安全 OS 证据——例如不安全的租约或状态、被替换的二进制、所有权/路径/符号链接不匹配，或无效的代际——才会拒绝代理启动。Claude 自有的外部会话注册表根目录属于读取侧身份依据：UID 或模式不安全时，会以醒目观测只隔离并禁止 Claude 写入，代理和另一提供方继续运行。Claude 每条会话记录仍必须使用原生 `peerProtocol: 1`；声明其他值的记录会单独被拒绝并纳入有界拒绝证据，不会阻止代理启动或隐藏其他可用会话。
+只有 Embassy 自有或执行的构件及其回调、控制或状态路径出现不安全 OS 证据——例如不安全的租约或状态、被替换的二进制、所有权/路径/符号链接不匹配，或无效的代际——才会拒绝代理启动。Claude 自有的外部会话注册表根目录属于读取侧身份依据：UID 或模式不安全时，只会让 Claude 降级并醒目显示，代理与其他提供方继续运行。Claude 每条会话记录仍必须使用原生 `peerProtocol: 1`；声明其他值的记录会单独被拒绝并纳入有界拒绝证据，不会阻止代理启动或隐藏其他可用会话。
 
-在授予写入权限前，代理自行执行有界的兼容性与注册读取：检查配置的启动器或托管安装、文件系统所有权与路径结构、注册表/控制套接字结构、`initialize` 与 `thread/loaded/list` 响应结构、声明的协议常量，以及 Codex 注册时排除历史记录的精确 `thread/resume`。这些常规读取不会路由用户消息、保留历史记录或调用 `turn/start`。唯一例外是可选的 Codex 写入认证探测：每次尝试最多可创建一个代理自有的临时线程，在有界写入围栏下运行且绝不接触用户线程；每个已创建的探测线程都会被归档，并确认已从已加载集合中清除。该探测会解析固定模型所公布的最低 effort。只要该模型/effort 固定项无法解析，探测就会以零消耗故障安全方式拒绝，并且不会创建任何线程或模型轮次。运行时仍会严格解析每个已知注册表字段、帧和响应；未知的 Claude 注册表顶层字段会被忽略，因为 Embassy 从不使用它们。公开状态中现有的 Claude 连接器行会携带可选的有界 `registry` 证据：`entriesScanned`、`parseableRecords`、单调的 `parseableRecordSeenSinceBoot`、按安全代码分组且有界的 `rejected`，以及 `rejectedCodesOmitted`。两种仪表盘会醒目呈现同一证据：如果 Claude 正在运行，但自代理启动以来从未观测到带可解析必需字段的记录，它的注册表布局可能已更改。
+运行时仍会严格解析每个已知注册表字段、帧和响应；未知的 Claude 注册表顶层字段会被忽略，因为 Embassy 从不使用它们。公开状态中的 Claude 连接器行会携带可选的有界 `registry` 观测：`entriesScanned`、`parseableRecords`、单调的 `parseableRecordSeenSinceBoot`、按安全代码分组且有界的 `rejected`，以及 `rejectedCodesOmitted`。两种仪表盘会醒目呈现同一事实：如果 Claude 正在运行，但自代理启动以来从未观测到带可解析必需字段的记录，它的注册表布局可能已更改。
 
-每个替代 Codex App Server 端点代际都从仅监控状态开始。Embassy 会在该代际上重新执行初始化和 `thread/loaded/list` 检查，只有精确的私有任务身份恰好出现一次时才重新锚定保留路由。在控制器激活这个精确代际之前，写入始终保持封锁。版本或结构不匹配、任务缺失、任务重复或转换不干净，都会让路由保持陈旧且禁止写入，而不是改投其他任务。
+每个替代 Codex App Server 端点代际都会协商一条新连接；只有 `thread/loaded/list` 恰好一次找到精确私有任务身份时，Embassy 才会重新锚定保留路由。协商失败、任务缺失或重复、转换不干净都会让路由保持陈旧，而不是改投其他任务。
 
-托管的 Codex 安装通过精确已验证路径解析；`PATH` 上其他位置的 `codex` 不会被使用或修改。Claude 从 `EMBASSY_CLAUDE_BIN` 或官方的用户级启动器解析，从不搜索 `PATH`。版本标幅是有界观测：后缀或有界的 stderr 通知本身不会使网关不可用，而无法识别版本时会显式呈现以便诊断。因此，已支持主版本内的提供方更新无需等待补丁固定发布，但仍必须通过上述实时结构与声明协议检查才能变为可写。不同主版本需要支持它的 Embassy 发布版。
+托管 Codex 安装通过精确已验证路径解析；`PATH` 上其他位置的 `codex` 不会被使用或修改。Claude 从 `EMBASSY_CLAUDE_BIN` 或官方用户级启动器解析，从不搜索 `PATH`。DeepSeek 只使用上方已验证的 checkout 根目录。Grok Build 使用发布版固定的 ACP 启动。版本字符串如存在，也只是有界诊断元数据。
 
 ## 寻址
 

package/docs/DASHBOARD.md

@@ -9,7 +9,7 @@ tabs, request controls, bounded actions, and security caveat.
 
 ## Static dashboard
 
-Open `gateway-dashboard.html` inside the configured state directory. It gives a metadata-only view of connector health, available and selected Claude peers, the registered Codex route, recent delivery states, queue depth, latency, and safe alerts.
+Open `gateway-dashboard.html` inside the configured state directory. It gives a metadata-only view of all four provider rows (Claude, Codex, DeepSeek, and Grok Build), connector health, exact named routes and consent edges, recent delivery states, queue depth, latency, and last safe codes.
 
 Interpret queue and delivery by direction. Codex-bound ordinary work can wait
 for the task to become idle. Claude-bound work does not wait for Claude idle:
@@ -81,43 +81,9 @@ 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.
 
-An automatically schema-probed and generation-gated App Server endpoint
-refresh appears in Activity as an automatic event, distinct from operator
-actions. Diagnostics reports each provider's compatibility evidence:
-`schema_attested` is informational and means the live probes passed on a
-same-major build outside this release's tested inventory. It is writable only
-when those probes cover the 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. Current untested Codex 0.x builds therefore stay monitor-only.
-A same-major probe failure, different major, or version evidence that
-cannot establish a safe major leaves only that provider degraded, monitor-only,
-and write-fenced while the
-broker and other provider remain available, and probes never promote across a
-major or unknown major. The different-major alert names the observed/tested
-versions and supported major
-and says that a supporting Embassy release is required. Probe, major-version,
-or generation failures remain explicit while a missing or duplicate exact task
-leaves its route stale. The Diagnostics
-registry block mirrors optional bounded `registry` evidence on the existing
-public 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. Compatibility remains passive status: the
-dashboard has no compatibility action or override. The dashboard never exposes
-the retained task ID, either
-endpoint generation, or raw registry records, and endpoint recovery never
-replays a message body.
+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.
+
+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.
 
 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

@@ -6,7 +6,7 @@ Embassy 提供两种仪表盘界面：一对仅包含元数据的静态文件，
 
 ## 静态仪表盘
 
-在配置的状态目录下打开 `gateway-dashboard.html`。它提供了一个纯元数据视图，包括连接器健康状态、可用和已选择的 Claude 对等方、已注册的 Codex 路由、近期投递状态、队列深度、延迟和安全告警。
+在配置的状态目录下打开 `gateway-dashboard.html`。它提供一个纯元数据视图，包含四种提供方行（Claude、Codex、DeepSeek、Grok Build）、连接器健康度、精确具名路由与同意边、近期投递状态、队列深度、延迟和最近安全代码。
 
 请按方向理解队列与投递。朝向 Codex 的普通工作可以等待任务空闲；朝向 Claude 的工作不等待 Claude 空闲：通过路由与写前检查后，它会立即进入 Claude 的原生邮箱，而 `transport_written` 会把该方向结算为 `delivered`。这个邮箱边界不表示 Claude 已读取或消费正文。
 
@@ -38,7 +38,9 @@ embassy dashboard --live --port 41962
 
 每个请求都会检查精确的 Host 头。导航 GET 可以缺少 Origin，但每个 POST 都要求精确的 Origin 与 `X-Embassy-Request: 1`。服务器不接受 `OPTIONS`，也不发送 CORS 头。这些检查约束浏览器的跨来源请求，但不认证本地软件。没有通用控制或提供方路由、遥测或外部资源。唯一的变更路由只接受配对、取消配对、刷新发现结果和移除陈旧 Codex 注册四种精确操作；每次都要求页内明确确认，正文上限为 1 KiB，并限制为每分钟六次。移除操作只携带公开的 `codex-*` 别名；仅当代理确认注册已陈旧且其端点代际已失效时才会接受。任务 ID 与端点代际不会进入浏览器契约。浏览器客户端仅在 `localStorage` 中保存一个显示偏好键（当前选项卡与语言）。浏览器不能创建或注销在线任务、发送、回复、审批、中断、更改设置，也不能调用任意代理或提供方方法。它通过同源 `fetch` 接收快照，并在每次有限操作后重新读取最新快照。一次快照观测可能会在投射状态之前结算已到期的生命周期投递。
 
-经过自动结构探测与代际门控的 App Server 端点刷新会作为自动事件出现在“活动”中，并与操作员操作明确区分。“诊断”会报告每个提供方的兼容性证据：`schema_attested` 是信息性状态，表示同主版本、但不在本发布版已测清单中的构建已通过全部实时探测；只有探测覆盖写入路径时，该提供方才可写。常规 Codex 兼容性与注册读取仍保持只读：它们可能包括 `initialize`、`thread/loaded/list` 与注册时的 `thread/resume`，但不会调用 `turn/start`。唯一例外是可选的 Codex 写入认证探测：每次尝试最多可创建一个代理自有的临时线程，在有界写入围栏下运行且绝不接触用户线程；每个已创建的探测线程都会被归档，并确认已从已加载集合中清除。该探测会解析固定模型所公布的最低 effort。只要该模型/effort 固定项无法解析，探测就会以零消耗故障安全方式拒绝，并且不会创建任何线程或模型轮次。当前未测试的 Codex 0.x 保持仅监控。同主版本探测失败、主版本不同或版本证据无法建立安全主版本时，只有该提供方保持降级、仅监控并禁止写入，代理和另一提供方继续运行；探测绝不能跨主版本或未知主版本提升权限。主版本不同的告警会列出已观测/已测版本和支持主版本，并说明必须使用支持已观测主版本的 Embassy 发布版。探测、主版本或代际失败会显式呈现；精确任务缺失或重复时，路由保持陈旧。“诊断”中的注册表区块会镜像现有公开 Claude 连接器行上可选的有界 `registry` 证据：`entriesScanned`、`parseableRecords`、单调的 `parseableRecordSeenSinceBoot`、按安全代码分组且有界的 `rejected`，以及 `rejectedCodesOmitted`。它会派生“已观测到可解析必需字段”、“自代理启动以来为空”或“自代理启动以来没有可解析记录”。最后一种警告会说明：自代理启动以来从未观测到带可解析必需字段的 Claude 注册表记录；如果 Claude 正在运行，它的注册表布局可能已更改。因此，这种可能的布局变化不会伪装成健康的空对等列表。兼容性在仪表盘中只作为被动状态：这里没有兼容性操作或覆盖机制。仪表盘绝不暴露保留的任务 ID、任一端点代际或原始注册表记录，端点恢复也绝不重放消息正文。
+精确 App Server 代际转换会作为自动事件出现在“活动”中，并与操作员操作明确区分。仪表盘不认证构建，也不授予权限；它只报告有界公开快照中的尽力而为运行时事实。“总览”与“路由”会在路由或连接器缺失时仍显示 Claude、Codex、DeepSeek 与 Grok Build；“投递”可按四种发送方与接收方提供方筛选；“诊断”显示已观察协议/版本元数据、当前连接器健康度与最近安全代码。版本元数据绝不改变路由权限。
+
+“诊断”中的注册表区块会镜像 Claude 连接器行上可选的有界 `registry` 观测：`entriesScanned`、`parseableRecords`、单调的 `parseableRecordSeenSinceBoot`、按安全代码分组且有界的 `rejected`，以及 `rejectedCodesOmitted`。它会派生“已观察到可解析必需字段”、“自代理启动以来为空”或“自代理启动以来没有可解析记录”。最后一种警告会说明：自代理启动以来从未观察到带可解析必需字段的 Claude 注册表记录；如果 Claude 正在运行，它的注册表布局可能已更改。因此，这种变化不会伪装成健康的空对等列表。仪表盘绝不暴露保留的原生 ID、端点代际、原始注册表记录或发布版自有的离线支持矩阵；端点恢复也绝不重放消息正文。
 
 可选的 `--lang en|zh-CN` 标志用于选择显示语言。它仅属于实时组件；静态版本始终以两种语言写入，通过页内链接切换。
 

package/docs/GATEWAY-ARCHITECTURE.md

@@ -1,8 +1,8 @@
 # Embassy Gateway Architecture
 
-Status: local bidirectional version 1 implemented and live-tested with one
-advertised Codex task; remote connectors remain deferred. The published v1
-package supports macOS, the only platform exercised end to end so far.
+Status: local bidirectional routing is implemented for Claude, Codex, DeepSeek,
+and Grok. Remote connectors remain deferred. The published package supports
+macOS, the only platform exercised end to end so far.
 
 This document uses four evidence labels:
 
@@ -29,33 +29,17 @@ edge, created by `pair` or the one-task `select-claude` shorthand. It provides
 a single private operational view across the two products without rebuilding
 either agent runtime.
 
-Provider compatibility follows exact OS-boundary attestation, version-major
-evidence, and bounded live-schema probes. A certified same-major build is
-writable; a same-major build whose probes all pass is `schema_attested` and
-writable only when the probes cover the write path. Current Claude probes cover
-their 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. An untested
-Codex 0.x build 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 and other provider remain available. 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 banner is
-unparseable. 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 native peer protocol is not 1 is rejected in isolation and
-included in bounded rejection evidence.
+Provider versions are best-effort diagnostic metadata, never routing authority.
+An explicit pair plus the exact owned route and session identity authorizes an
+attempt; current connector, generation, strict wire, capability, and correlated
+operation facts decide its result. The release-owned offline support matrix is
+the tested-artifact record and is never imported by runtime. 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
+native peer protocol is not 1 is rejected in isolation and included in bounded
+rejection evidence. Missing optional providers and interface drift degrade only
+their own routes while the broker and other providers remain available.
 
 It is deliberately:
 
@@ -96,27 +80,22 @@ sessions and `SendMessage` to contact them. A target can accept, hold, or
 refuse inbound cross-session messages through `crossSessionInbound`. Messages
 do not bypass the receiver's tool permissions or approval boundary.
 
-**Evidence-gated internal boundary:** the installed Claude Code build advertises
+**Best-effort internal boundary:** the installed Claude Code build advertises
 live sessions through registry records and transports peer frames over
 per-session Unix-domain sockets using peer protocol 1. Those registry and wire
 shapes are not documented as a stable third-party integration API. The gateway
-therefore assigns write authority only from supported-major evidence and
-bounded live-schema probes, and validates every consumed field, frame, and
-socket immediately before use. Unknown top-level registry fields are tolerated
-because Embassy never consumes them; malformed required fields and records
-whose peer protocol is not 1 remain isolated and counted. A passing same-major
-patch outside the tested inventory is writable `schema_attested`; a failed
-probe, different major, or version evidence that cannot establish a safe major
-keeps only the Claude surface monitor-only. An exact official launcher target
-may supply separate bounded major evidence when its banner is unparseable, but
-unknown major evidence is never promoted by probes.
+therefore validates every consumed field, frame, socket, generation, and
+correlated result immediately before use. Unknown top-level registry fields are
+tolerated because Embassy never consumes them; malformed required fields and
+records whose peer protocol is not 1 remain isolated and counted. Version
+metadata describes what was observed but grants no runtime authority.
 
 For the lowest-impedance native path, the gateway publishes one process-owned
 registry record whose name is visibly prefixed `codex-` and which carries the
 supported explicit versioned Embassy-advertisement marker. The listener remains
 gateway-owned and does not claim to be a Claude model session; the marker, not
 the name prefix alone, distinguishes Embassy's advertisement. The record uses
-the schema-attested native peer shape so Claude's own `ListAgents` and
+the validated native peer shape so Claude's own `ListAgents` and
 `SendMessage` tools work unchanged.
 
 Consequences:
@@ -194,11 +173,11 @@ The status below is intentionally narrower than the target architecture.
 | Private JSONL control protocol over a controller-owned UDS | **Implemented**, deterministic synthetic tests; no provider connection required |
 | Static metadata-only dashboard renderer and atomic publisher | **Implemented**, deterministic security tests; the static renderer requires no browser or HTTP server |
 | Opt-in live dashboard companion (`embassy dashboard --live`) | **Implemented**, deterministic tests over the stable loopback listener, direct multi-browser access, projection, request guards, and four bounded route actions; it is a separate foreground process, never part of `embassy serve` |
-| Claude registry/peer adapter gated by supported major / peer protocol 1 / live schema probes | **Implemented** and live-tested through Claude Code 2.1.227, including patch-overlap discovery, print-session discovery, native status frames, cancellation, accessible-workspace attestation, and writable `schema_attested` admission for passing same-major builds outside the tested inventory |
-| Automatic Claude binary/runtime attestation | **Implemented**; validates the exact owned path, executes only bounded `claude --version` with a scrubbed environment, tolerates bounded suffix/stderr observations, and derives but does not open provider roots |
+| Claude registry/peer adapter with strict peer protocol 1 and per-operation validation | **Implemented** and live-tested through Claude Code 2.1.227, including discovery, native status frames, cancellation, and accessible-workspace validation |
+| Claude binary/runtime metadata | **Implemented**; validates the exact owned path and records launcher-leaf metadata without granting it routing authority |
 | Allowlisted Codex App Server connector with bounded busy behavior | **Implemented** and live-tested against App Server 0.147.0 for external busy observation, registered-route reachability across settings changes, and an automatically started queued turn; exact `STEER:` boundary behavior is covered deterministically |
 | Attach-only local Codex proxy transport and exact-owned cleanup | **Implemented**, five deterministic tests; no live App Server connection in routine tests |
-| Local provider adapters | **Implemented**, focused synthetic tests cover genuine-interactive Claude discovery, exact send/callback/receipt settlement and post-dispatch refresh, plus exact opted-in Codex ownership, registered-route reachability, monitor-only fallback, and cleanup; remote adapters remain disabled |
+| Local provider adapters | **Implemented**, focused synthetic tests cover Claude discovery, exact Codex ownership, and lazy ACP-backed DeepSeek and Grok routes with provider-local degradation and cleanup; remote adapters remain disabled |
 | Gateway service composition | **Implemented**, including private control-server startup, adapter lifecycle, synthetic cross-provider selection/dispatch/reply correlation, metadata-only publication, and clean-restart abandonment tests |
 | Delivery receipt/status lifecycle | **Implemented**, deterministic synthetic tests cover stable-UUID native receipt re-resolution, the merged/verbose/quiet Claude notice policy, one bounded stall notice with pending age where enabled, opaque memory-only correlation handles, the closed status/terminal schema, and one-shot/bounded-wait CLI behavior |
 | Broker-owned cross-provider provenance framing | **Implemented**, deterministic tests cover exact Codex and Claude wire shapes, bounded long-alias attribution, recipient reply hints, reserved-tag neutralization, single wrapping across clean retries, and pre-write failure |
@@ -248,8 +227,8 @@ generation.
 
 An App Server endpoint-generation change is a fenced route transition, not a
 new registration. Embassy stops dispatch through the old connector and creates
-a monitor-only replacement connector. That exact generation must pass a fresh
-automatic initialize and `thread/loaded/list` validation, where every retained
+a replacement connector. That exact generation must negotiate its current
+interface and pass `thread/loaded/list` validation, where every retained
 private thread ID must occur exactly once. The connector resumes that exact
 task with history excluded; only then may the controller activate writes and
 atomically re-anchor the same alias, owner lease, and pair edges to the new
@@ -687,10 +666,9 @@ prototype state root is no longer read, locked, or mutated.
 
 It emits one normalized ready line, publishes the private dashboard, and
 holds the process until `SIGINT` or `SIGTERM`, when exact-owned resources are
-closed. Startup automatically attests the exact owned Claude and Codex paths,
-observes their version majors, and runs bounded required-schema probes, then
-binds controller-owned UDS listeners. A provider-local compatibility failure
-keeps that surface monitor-only. Unsafe ownership, path, symlink, lease, state,
+closed. Startup validates exact owned provider paths and binds controller-owned
+UDS listeners. Missing optional providers or a provider-local interface failure
+degrades only that surface. Unsafe ownership, path, symlink, lease, state,
 or generation evidence for Embassy-owned or executed artifacts and Embassy
 callback, control, or state paths aborts startup; unsafe UID or mode evidence
 on Claude's external sessions registry root quarantines only Claude. The bounded read-only Claude registry
@@ -755,16 +733,11 @@ any NVM-managed `codex` on the user's `PATH` (for example
 it, and does not edit a shell profile. The two installations therefore do not
 conflict.
 
-The connector has a fixed App Server method allowlist. An ordinary connector
+The connector has a fixed App Server method allowlist. A connector
 may initialize, observe loaded tasks, resume/unsubscribe the exact registered
-task, start a dedicated turn, and interrupt only its own confirmed turn. The
-optional write-attestation probe alone may call `thread/archive`, only for its
-validated disposable broker-owned probe thread, 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. Delete,
-history, shell, configuration, authentication, plugin, approval-response, and
-generic RPC methods remain excluded everywhere.
+task, start a dedicated turn, and interrupt only its own confirmed turn. Archive,
+delete, history, shell, configuration, authentication, plugin,
+approval-response, and generic RPC methods remain excluded everywhere.
 
 The App Server capability first tested with 0.147.0 gates the privacy-preserving
 `thread/resume.excludeTurns` field behind initialization capability
@@ -776,25 +749,12 @@ Missing, malformed, or nonempty turns fail closed and are never emitted or
 persisted. The capability does not add an experimental client method or change
 the closed RPC allowlist.
 
-Automatic generation validation and controller write activation are distinct
-gates. A replacement connector may initialize, list, resume, and expose
-normalized monitor state while still reporting its write gate as unavailable.
-A certified same-major Codex build may activate after the exact generation
-checks pass. A fully probed untested same-major `schema_attested` build does not
-authorize Codex writes. Its ordinary 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. That build,
-failed probes, a different major, or version evidence
-that cannot establish a safe major remain on the monitor-only path and cannot
-be promoted by probes. No Claude-initiated turn
-can start until the controller activates that exact endpoint generation and
-explicit route ownership is established.
+Generation validation and controller activation are distinct gates. A
+replacement connector may initialize, list, resume, and expose normalized
+status before the controller activates it. No Claude-initiated turn can start
+until that exact endpoint generation has negotiated its current interface,
+re-observed the registered task, and established explicit route ownership.
+Version metadata does not participate in that decision.
 
 Registration resumes the exact task and establishes reachability. Embassy does
 not read or retain reported working-directory or policy fields. Before
@@ -875,13 +835,11 @@ The one Desktop restart needed for the local shared-App-Server feasibility
 test has already been completed. Building, running synthetic tests, starting
 the gateway, rendering the dashboard, and a future Claude peer-socket test do
 not themselves require another Desktop restart. A provider or Desktop major
-upgrade outside the supported compatibility major leaves only that provider
-monitor-only and requires an Embassy release supporting the observed major
-before writes can resume. A required-schema or declared-protocol change also
-keeps its responsible boundary closed. If the attachment mode changes, the
-supporting release may require a separately announced controlled restart.
-Patch updates within the supported major are admitted according to live
-evidence rather than a release pin.
+upgrade may change an internal interface; strict per-operation checks keep the
+responsible route closed if that interface no longer matches. Other providers
+remain available. If the attachment mode changes, a supporting release may
+require a separately announced controlled restart. The offline support matrix
+records what a release was tested with but never grants runtime authority.
 
 ## Dashboard
 
@@ -900,18 +858,18 @@ no meta refresh and the page tells the operator to re-run
 
 Each page assembles seven sections:
 
-- **Exchange** — aggregate gateway health plus the pair graph: every explicit
-  Claude↔Codex edge and its per-edge counters.
+- **Exchange** — aggregate gateway health plus every explicit cross-provider
+  pair and its per-edge counters.
 - **Attention** — allowlisted alerts such as stale route, protocol mismatch,
   queue full, or ambiguous delivery.
 - **Transit** — queued-message depth and bytes in flight.
 - **Progress supervision** — active progress watches and their state.
 - **Operator activity** — the broker's bounded public journal of accepted
   operator actions.
-- **Sessions** — available/selected Claude aliases, registered Codex aliases,
-  provider, host, compatibility, state, and queue depth.
-- **Diagnostics** — compatibility attestations per provider, per-host connector
-  health and protocol, deadline-pressure buckets, accounting totals, and the
+- **Sessions** — first-class Claude, Codex, DeepSeek, and Grok provider rows,
+  aliases, host, route state, and queue depth.
+- **Diagnostics** — best-effort observed metadata, per-host connector health,
+  last safe code, deadline-pressure buckets, accounting totals, and the
   omission counters below. Normalized message direction and delivery state,
   timestamp, latency, byte count, and a short opaque message-ID suffix appear
   with the delivery rows.
@@ -1036,8 +994,8 @@ and fake App Server transports.
 
 ### Exact default roots on macOS
 
-The automatic provider attestor derives these paths from the current OS user's
-verified home; it does not scan the home directory. These are the reviewed
+Provider setup derives these paths from the current OS user's verified home; it
+does not scan the home directory. These are the reviewed
 boundaries exercised by the live gateway; routine tests substitute synthetic
 paths, peers, and transports:
 
@@ -1066,25 +1024,11 @@ the preferred least-context setup, but it is not mandatory.
 
 ## Failure and upgrade policy
 
-- A certified same-major provider build is writable; a fully probed same-major
-  build is `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.
-  Current untested Codex 0.x therefore stays monitor-only. Failed
-  probes, a different major, or
-  version evidence that cannot establish a safe major leave only that provider
-  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 requires an Embassy release supporting the observed
-  major. A session record whose peer protocol is not 1 is rejected per record
-  and counted without stopping the broker.
+- Provider versions are best-effort metadata and never grant or remove routing
+  authority. The offline support matrix records tested artifacts, capabilities,
+  limitations, and dates without entering runtime. A session record whose peer
+  protocol is not 1 is rejected per record and counted without stopping the
+  broker; interface drift degrades only its responsible provider.
 - Unsafe ownership, path, symlink, lease, state, or generation 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
@@ -1127,12 +1071,10 @@ the preferred least-context setup, but it is not mandatory.
   the process was lost settles `ambiguous` with `CONTROLLER_RESTARTED`; a
   message whose target authority was transient, or whose target route no longer
   exists, settles `abandoned` with the same code.
-- A provider or Desktop update outside the supported major leaves that surface
-  monitor-only while the broker and other surface remain available. A Claude
-  record outside peer protocol 1 is rejected per record; a required live-schema
-  failure degrades the responsible provider, and retained state never activates
-  an unvalidated replacement endpoint generation. A patch update that passes
-  those checks does not block writes for its version alone.
+- A provider or Desktop update that changes an internal interface degrades its
+  responsible route while the broker and other providers remain available. A
+  Claude record outside peer protocol 1 is rejected per record, and retained
+  state never activates an unvalidated replacement endpoint generation.
 
 ## Validation boundary
 

package/package.json

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

package/skills/embassy-peer/SKILL.md

@@ -31,7 +31,7 @@ embassy health
 
 If Embassy is unavailable, stop and report that it must be started in a trusted local terminal with `embassy serve`. `GATEWAY_INSTANCE_IN_USE` means an Embassy or recognized legacy lock already owns this login account; stop that foreground process rather than changing `EMBASSY_STATE_DIR`. If no legacy process remains, the operator may remove only the exact stale legacy controller lock and retry. Do not launch a background copy, retry in a loop, discover sockets, or fall back to a provider CLI.
 
-Compatibility is automatic and evidence-gated. A certified same-major provider is writable; a same-major build whose bounded live schema probes all pass is schema-attested (`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 no longer loaded. 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. 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 and other provider remain available; probes never promote across a major or unknown major. A different-major alert safely names the observed/tested versions and supported major and means an Embassy release supporting the observed major is required—`embassy health` is not a recovery step. Claude `peerProtocol 1` is required per registry record; other values are rejected in isolation and counted. Unknown top-level registry fields are tolerated, but every required known field remains strict; bounded rejected-record counts and an observed-empty registry are loud status and dashboard observations. There is no separate agent or operator compatibility action. Report a degraded surface and stop rather than manually probing the provider, sending a test message, or trying to override the fence.
+Embassy presents Claude, Codex, DeepSeek, and Grok as first-class providers. Runtime status is best-effort: use route staleness, connector health, observed metadata, and the last safe code to explain what is available now. Provider versions are diagnostic metadata, not routing authority; the release-owned offline support matrix is the record of tested artifacts, capabilities, limitations, and test dates. There is no agent or operator compatibility action. Report a degraded surface and stop rather than sending a test message or trying to override a failed route.
 
 List the public snapshot:
 
@@ -47,18 +47,18 @@ embassy refresh-dashboard
 
 Run that refresh only at the passive-discovery authorization stage. Treat the response as a normalized refresh result; it does not reveal the path. The operator-facing page is `gateway-dashboard.html` in the configured state directory, by default `~/.local/state/agent-embassy/`. Use the operator's configured location when it differs. Do not search for the file or scan controller-owned paths.
 
-## Pair with a Claude session
+## Pair providers
 
-Create one explicit Claude↔Codex edge by naming both ends. The Claude end must be a user-chosen, unique candidate from `availablePeers`:
+Create one explicit cross-provider edge by naming both ends. Each endpoint must be a user-chosen route from the current snapshot:
 
 ```sh
-embassy pair --claude advisor@this-mac --codex codex-reviewer@this-mac
+embassy pair --from codex-reviewer@this-mac --to advisor@this-mac
 ```
 
 Pairs are additive and bounded; many edges may coexist, and `pair` never retires another edge. Run `pair` and `unpair` from inside a registered Codex task so the CLI reads the inherited `CODEX_THREAD_ID`; a plain operator shell fails closed with `CODEX_IDENTITY_REQUIRED` — use the live dashboard or the one-task shorthand instead. Remove exactly the named edge:
 
 ```sh
-embassy unpair --claude advisor@this-mac --codex codex-reviewer@this-mac
+embassy unpair --from codex-reviewer@this-mac --to advisor@this-mac
 ```
 
 When the Codex end is unambiguous — inherited from the calling task, or the sole registered task — the one-task shorthand forms or removes the same edge:
@@ -113,7 +113,7 @@ until manual recovery rather than leaving two live registrations.
 
 Embassy also pins the exact identity fail-closed when a retained route cannot fully reactivate or a fresh registration cannot confirm complete rollback. Retry only that exact identity; choose another only after the old route is confirmed unregistered and Embassy is restarted.
 
-A compatible Codex App Server generation change or broker restart can reattach an exact registered task automatically. Each replacement generation starts monitor-only and must pass a fresh initialize plus exact `thread/loaded/list` observation before re-anchoring; provider writes remain fenced until the controller activates that exact generation. A normal broker restart therefore needs no manual registration. If boot reactivation cannot find the task exactly once, the route remains stale with `REOBSERVATION_REQUIRED`; once the task is observable, recover it only from that exact Codex task by rerunning `embassy register-codex --alias <same-alias>`. Do not unregister first, supply a thread ID, or replay any ambiguously written body.
+A Codex App Server generation change or broker restart can reattach an exact registered task automatically. Each replacement generation negotiates its current interface and must observe the exact task before the controller re-anchors it. A normal broker restart therefore needs no manual registration. If boot reactivation cannot find the task exactly once, the route remains stale with `REOBSERVATION_REQUIRED`; once the task is observable, recover it only from that exact Codex task by rerunning `embassy register-codex --alias <same-alias>`. Do not unregister first, supply a thread ID, or replay any ambiguously written body.
 
 Unregister from the same Codex task: