@sema-agent/sdk 8.2.0 → 8.4.0

package/dist/types.d.ts

@@ -57,7 +57,7 @@
  *    null" may be correct — check for a normalizer at the boundary before widening it to `| null`.
  */
 import type { SemaSettings } from "./settings.js";
-import type { RuleOffer } from "./resources/tool-approvals.js";
+import type { AskOrigin, RuleOffer } from "./resources/tool-approvals.js";
 /** Authenticated end-user identity. Opaque to the service (used as memory scope + session owner). The SDK
  *  normalizes; the service does NOT validate the format. Convention: `user:` / `org:` / `ai:` / `anon:`. */
 export type Principal = string;
@@ -699,11 +699,94 @@ export interface PendingGateMaterial {
     decidePath: string;
     governanceForced?: true;
 }
+/**
+ * 🔴 **BREAKING(server ≥ 7.64.0,core 7.6.0 design/390 D-8)—— 终局是一条带标因由,不再是八个平面键。**
+ *
+ * 7.63.0 及以前,一次 run 怎么结束的要从并列的八个可选键里拼:`status` / `errorCode` / `errorMessage` /
+ * `blockedReason` / `checkpointToken` / `checkpointId` / `checkpointGate` / `workspaceRestoreMode`。哪些组合
+ * 合法(「`suspended` ⇔ 有 token」「review park 与 approval park 不同时置位」)只活在引擎那条 if/else 阶梯的
+ * 顺序里,读的人只能靠**缺席**推断。现在它是**形状**:paused 因由带着它的门,completed 因由**写不出**码。
+ *
+ * **怎么读**:分诊读 `terminal.kind`。要旧的五词 `status`,调引擎导出的 `terminalProjection(terminal)` ——
+ * 那是**唯一**一条 因由→平面 的派生。🔴 **本 SDK 刻意不提供兼容投影**:提供一条就等于同一个事实在这条
+ * wire 上有了两个真源,而消费端会分成「读因由的」和「读投影的」两派(下一次形变时后者全部无声地错)。
+ * 「哪个 park 读作 `suspended`、哪个读作 `needs_review`」由引擎的 pause registry 决定,不是本服务的表。
+ *
+ * 🔴 **没有变的是 server 自己的列与信封**(它们不是引擎结果):`GET /v1/runs/:id` 行上的 `status` /
+ * `errorCode` 列、任务列表行的 `status`、`/decide` 200 体的三键、fleet 行的终态词 —— 照旧说五词,只是
+ * 数据源改成从因由投影一次。
+ */
+export type TerminalCause = {
+    kind: "completed";
+} | {
+    kind: "failed";
+    /** 这次失败带的**机器码**——退役的平面 `errorCode` 那一席,现在**结构上**只属于失败臂
+     *  (「码属于失败」成了形状,不再是一条跨字段口头约定)。**开集**,点分命名空间可按族前缀匹配:
+     *  `limits.max_tokens_exceeded` / `limits.max_cost_exceeded` / `limits.max_turns_exceeded` /
+     *  `limits.max_walltime_exceeded` / `config.*` / `resume_at.*`;brain 码(`auth`/`network`/
+     *  `rate_limit`/…)与 `conflict` 仍是扁平词。
+     *  ⚠️ 两个**外因**停因刻意**不在** `limits.*` 族(重试要的是新环境 / 等窗口放开,不是更小的预算):
+     *  `env.lifetime_expired` 与 `usage.window_exhausted`。
+     *  治理码同样落这里,而**哪条腿把它改写成 HTTP 状态逐码不同**,别互相推广:
+     *  · `memory.admission_denied` / `memory.admission_required` **只**在同步 `POST /v1/tasks` 上被改写成
+     *    403/503;异步轮询腿与 `done` 帧上它们骑 200;
+     *  · `usage.window_exhausted` 只有**进场前**那道门是 429,进场后竞态窗内的拒**任何腿都不改写**。
+     *  嵌套编排器遇到自己驱动不了的耐久 park 时盖 `unexpected.suspended` / `unexpected.needs_review`,
+     *  并把那次 park 整只带在 {@link nestedPause}。
+     *  🔴 消费端必须带 `default` 臂;缺席 = 这次失败本来就没有码。 */
+    code?: string;
+    /** 人类可读的失败文本;没有就缺席。 */
+    message?: string;
+    /** 这次失败**顶替的那次耐久暂停** —— 只在**嵌套硬边界**(verify / cascade)上出现:嵌套腿停在一道
+     *  耐久门上,而编排器从内部驱动不了 resume,于是在**它的**边界上如实报 failed,同时把那次 park 的
+     *  因由整只带在这里,顶层调用方据此仍能恢复。
+     *  🔴 wire 上它同样**不带 `token`**(与顶层 paused 臂同一条摘除规则);`gate` / `checkpointId` 照常在。
+     *  引擎自己组装的失败上恒缺席。 */
+    nestedPause?: PausedCause;
+} | {
+    kind: "blocked";
+    /** agent 为什么完不成(治理判决不是失败)。 */
+    reason: string;
+} | PausedCause;
+/**
+ * 一次耐久暂停的因由(`TerminalCause` 的 paused 臂)—— 提交了 checkpoint,这条 run 可恢复。
+ *
+ * 🔴 **`token` 席位永不上 wire**:它是恢复**能力凭据**(token-as-auth),永不离开服务边界 —— 与 7.63.0
+ * 之前的 `checkpointToken` 从不上 wire 是**同一条纪律**,只是凭据换了住址(server `src/terminal.ts` 的
+ * `stripResumeToken` 在**两条**够得着的路径上摘它:本臂与 `failed.nestedPause`)。要动这次暂停:走
+ * `POST /v1/approvals/{sessionId}/decide`,凭 `checkpointId` 对账。
+ */
+export interface PausedCause {
+    kind: "paused";
+    /** **哪一道**暂停 —— 谁/什么必须来恢复它。与 park 行的 `gate.kind` 是同一个词。 */
+    gate: CheckpointGate;
+    /** 这次暂停的**非密**稳定身份 —— token 不能去的地方可以记/可以渲的那个对账键。
+     *  pre-identity 的老 checkpoint 上缺席。 */
+    checkpointId?: string;
+    /** 被暂停任务的远端工作区**怎么回来**,只要这次暂停捕获了远端工作区就在场。两种模式计费与行为差得远:
+     *  · `"snapshot"` —— VM 被挂起成快照(供应商侧计费通常停,进程内存态被捕获,resume 复原);
+     *  · `"park_only"` —— 环境自陈不可挂起(SSH 主机 / ADB 设备),于是**什么都没被暂停**:机器继续跑、
+     *    继续花钱,进程内存态听凭那头处置,resume 只是重新连上还在那儿的工作区。
+     *  **缺席** = 进程内暂停(静态的、调用方自有的环境:没有远端工作区被捕获)。
+     *  🔴 把「paused ⇒ 空闲且免费」当成不变量的调度器必须看得见这一位。 */
+    restoreMode?: "snapshot" | "park_only";
+}
 /** Synchronous task result (`POST /v1/tasks`). */
 export interface TaskResult {
     taskId: string;
     sessionId: string;
-    status: RunStatus;
+    /** 🔴 **server ≥ 7.64.0** —— 这条 run 的**唯一**终局记录。分诊读 `terminal.kind`;退役的八个平面键
+     *  (`status` / `errorCode` / `errorMessage` / `blockedReason` / `checkpointToken` / `checkpointId` /
+     *  `checkpointGate` / `workspaceRestoreMode`)已从本型面**整删**,**不留可选兼容键**(同一条 wire 上
+     *  两种拼法 = 一个语义面两个写者)。要五词 `status` 的消费方自己调引擎的 `terminalProjection(terminal)`。
+     *
+     *  ⚠️ **跨代偏斜,如实登记**(与 8.0.0 的 `CcImportResult` 换形同款处置):本 SDK 的 server 支持地板是
+     *  **3.0.0**,而 `terminal` 只有 **≥7.64.0** 的 server 才发。对着一台更老的 server,这一座在运行期
+     *  **缺席**(而型面上它是必填)—— 旧的平面键则仍在 wire 上,经开集索引读得到但**无类型**。
+     *  🔴 要同时吃两代 server 的消费方:先用 `"terminal" in result` 判形,别把型面的必填当成运行期保证。
+     *  ⚠️ 本座**不**做成可选来「表达这件事」:可选会让 7.64.0 之后的每一个读点都被迫处理一个**不存在**的
+     *  缺席分支,而真正的判别位是对端版本,不是这个键。 */
+    terminal: TerminalCause;
     result?: string;
     /** [2255]① 拒绝形材料(server ≥3.21:SSE 车道 409 conflict.session_active_run 的 done 帧 result 携带;
      *  普通终态帧不带)。activeTaskId 其实自 [1833] G10 起就在 wire 上,此前 SDK 侧漏登记——一并补。
@@ -711,8 +794,6 @@ export interface TaskResult {
     activeTaskId?: string | null;
     activeTaskStatus?: string;
     pendingGate?: PendingGateMaterial;
-    errorCode?: string;
-    errorMessage?: string;
     /** 🔴 **等待提示的 2xx 形**(复审车 C,2026-08-05)—— 引擎 result 里的等待提示,**毫秒、未换算**
      *  (与错误体的 `retryAfterSec`(**秒**)不同单位,别混用)。
      *  ⚠️「带等待提示」≠「transient」:引擎把 `memory.admission_required` 判为 **transient**(目录答上来后
@@ -741,17 +822,15 @@ export interface TaskResult {
     };
     /** [1543] SDK-M 补键(core 真域逐字,engine 一直在发、此前封闭接口读不到):
      *  salvagedOutput = degenerate/timeout 终态抢救出的最后模型文本(render as partial);
-     *  blockedReason = 任务被策略/门挡下的人类可读因;
-     *  checkpointGate = suspended 时挂起的门(与 events 的 `suspended.gate` 同源——poller 面读这里);
      *  degraded = 模型降级链实录(from/to/reason/atTurn);
-     *  structuredOutput = outputSchema 任务的结构化产出(0.0.74 的 outputRetries 旋钮所服务的产物)。 */
+     *  structuredOutput = outputSchema 任务的结构化产出(0.0.74 的 outputRetries 旋钮所服务的产物)。
+     *  (7.64.0 删:`blockedReason` → `terminal.blocked.reason`;`checkpointGate` → `terminal.paused.gate`,
+     *   而且不再是 `unknown` —— 因由形下它是 typed 的 {@link CheckpointGate}。) */
     salvagedOutput?: string;
-    blockedReason?: string;
-    checkpointGate?: unknown;
-    /** [4913](server 7.41+)—— durable park(status suspended/needs_review)时**待批工具调用**的 id,
+    /** [4913](server 7.41+)—— durable park(`terminal.kind === "paused"`)时**待批工具调用**的 id,
      *  与 tool_approval 帧的 `toolCallId` 同键同义(server ≥1.307)。缺席形照 core [1995]② OMITTED 契约:
      *  tool-less park(resource_limit / plan_review / task_done)或 server 侧读失败时**键整个缺席**,
-     *  绝不编 null——消费方测 presence。终态结果(completed/failed)恒缺席。 */
+     *  绝不编 null——消费方测 presence。非 paused 的因由上恒缺席。 */
     toolCallId?: string;
     degraded?: {
         from: string;
@@ -776,7 +855,10 @@ export interface TaskResult {
  *  }
  *  ```
  *  或直接按机器码 `ev.result.errorCode === "conflict.session_active_run"`。
- *  ⚠️ `status` **不能**当判别位 —— 两形都有(拒绝形恒 `"failed"`)。
+ *  🔴 **server ≥ 7.64.0 起两形靠键分家**:正常终态带 `terminal`(带标因由)、**没有** `status`;拒绝形带扁平
+ *  `status: "failed"` + `errorCode`,因为它是 **server 自己的**拒绝信封、不是引擎结果,这次形变没动它。
+ *  于是 `status` 现在只在其中一形上 —— 但判别位仍按 server 钉的那两个来(`stats` 在场性 / `errorCode`),
+ *  别改判成 `status` 缺席(那是拿「另一形没有的键」当判据,方向脆)。
  *
  *  出路材料([2255]①/[2257]):`activeTaskStatus` 分「插话/取消」(running)与「决议/取消」(parked)两族;
  *  `pendingGate.decidePath` 是 parked run 的**那一个**正确 resume 入口(sessionId 寻址,checkpoint token
@@ -1381,13 +1463,53 @@ export interface SupervisorCostBreakdown {
     };
     totalMicroUsd: number;
 }
+/**
+ * 🔴 **盘上的那一形** —— server 7.63.0 及以前写下的任务结果,退役的**平面**形。
+ *
+ * 它只出现在**回放持久字节**的那几张脸上,而且只在跨过 7.64.0 升级过的部署上:`GET /v1/runs/:id` 的
+ * `result`(server 对存储 blob 是**逐字透传**,只过一次脱敏,**不补** `terminal` —— `src/http/routes/runs.ts`)
+ * 与 durable 账本回放出来的 `done` 帧。**没有任何东西会再写出它**:写口只铸一种形({@link TaskResult})。
+ *
+ * 🔴 **这不是兼容孪生键**。「同一条 wire 上一个事实两种拼法」禁的是**写者**:一个语义面两个生产者。这里
+ * 只有**一个**写者,外加一张**读盘**面认盘上那个已停产的写者真留下的字节 —— 与 server 自己那只两代读器
+ * (`persistedPlaneOf`)划的是同一条线,而那个函数的顶注逐字记着「删掉它」造成的两条可复现回归:历史 run 的
+ * `GET /v1/runs/:id` 整个 500,以及旧账本行回放时凭据重新明文外发。
+ *
+ * **判别位** = `"terminal" in result`:在场 = 现行因由形,缺席 = 本形。🔴 **别只按 `status` 判** ——
+ * SSE 的拒绝信封({@link ActiveRunConflictDoneResult})也带 `status`。
+ */
+export interface LegacyPlaneTaskResult {
+    taskId: string;
+    sessionId: string;
+    /** 退役的五词平面状态。它的继任是 {@link TaskResult.terminal} 的 `kind`(经引擎的 `terminalProjection` 派生)。 */
+    status: RunStatus;
+    result?: string;
+    stats: TaskStats;
+    /** 退役的平面终局码。继任者 = `terminal.failed.code`。 */
+    errorCode?: string;
+    /** 退役的平面失败文本。继任者 = `terminal.failed.message`。 */
+    errorMessage?: string;
+    /** 退役的平面治理因由。继任者 = `terminal.blocked.reason`。 */
+    blockedReason?: string;
+    /** 退役的平面暂停门 —— **刻意留 `unknown`**:这是上一代写下的字节,本契约不替它重新裁定形状。
+     *  继任者 = `terminal.paused.gate`(typed 的 {@link CheckpointGate})。 */
+    checkpointGate?: unknown;
+    salvagedOutput?: string;
+    model?: string;
+    toolCallId?: string;
+    retryAfterMs?: number;
+}
 /** Run state (`GET /v1/runs/:id`) — LIVE shape (service Drift 2): `result` is the NESTED TaskResult
  *  (output text = result.result, stats = result.stats; no top-level stats); error text field is `error`. */
 export interface RunRecord {
     taskId: string;
     sessionId: string;
     status: RunStatus;
-    result?: TaskResult;
+    /** 🔴 **读盘面 ⇒ 两代字节**(server ≥7.64.0 起;见 {@link LegacyPlaneTaskResult}):server 对存储 blob 是
+     *  逐字透传、**不补** `terminal`,所以一台跨 7.64.0 升级过的部署上,升级前的历史行读出来仍是旧的平面形。
+     *  判别位 `"terminal" in run.result`。 */
+    result?: TaskResult | LegacyPlaneTaskResult;
+    /** 本**行的列**,7.64.0 未变(照旧说五词);只是数据源改成从 `result.terminal` 投影一次(旧行则直接读平面键)。 */
     errorCode?: string;
     error?: string;
     /** Work-view correlation. Present when the run has a jobId (omitted when null). LIVE server-side
@@ -1594,6 +1716,156 @@ export interface TraceTurn {
     };
     [k: string]: unknown;
 }
+/**
+ * **谁拒的** —— 判决是这次 deny 的那一**层**(core 7.6.0 `DENIED_BY_VALUES`,闭八词)。
+ * deny 引出的另一个问题「谁**问**的」由 {@link AskOrigin} 回答;7.6.0 之前两者共用一张七词表
+ * (`PermissionDeniedSource`),其中 `classifier` 同时兼任「分类器提的问」与「分类器拒的」两义。
+ *  · `policy` —— 部署 `ToolPolicy` 拒(直接拒,或复查一次被批准的编辑),或审批-编辑链撞了轮次上限;
+ *  · `hook` —— PreToolUse hook 拒 / 抛 / 从未作答(对「没作决定的 hook」的 fail-closed 拦阻按 hook 层归因);
+ *  · `org` —— 组织策略规则拒;
+ *  · `classifier` —— auto 模式分类器**直接**拒(它的 ASK 侧角色是 `origin: "denial_limit_fallback"`);
+ *  · `plan_mode` —— plan 模式对写工具的只读拦阻;
+ *  · `compliance` —— 合规的调用期锁;
+ *  · `write_protection` —— 一次被批准的编辑被限制链改写到了**没有任何审批覆盖**的写保护路径上;
+ *  · `ask_resolution` —— 这次 ask 的**结算本身**就是拒(有人说了不 / 窗到期 / 没人可问……),细节在
+ *    {@link GateOutcome.settlement}。
+ * 🔴 **本词表在这条 wire 上是真闭集,所以类型也闭**(与 {@link McpFailureKind} 那种「只是眼下十个词」的开集
+ * 不同,这条差别有出处):引擎的 `screenGateOutcome` 把「`deniedBy` 出闭集」列为记录**缺陷**,而 server 对
+ * 有缺陷的记录是**整条不上帧**(report + withhold)。⇒ 一个词表外的 `deniedBy` **结构上到不了消费端** ——
+ * 它到达的形式是 `gate` **整键缺席**,而不是一个陌生的词。给这里加一条 `(string & {})` 只会造出一个永远
+ * 走不到的分支,同时把消费端本可以拿到的**编译期穷尽性**弄丢。
+ * {@link Settlement} 的 `kind` 与 {@link GateOutcome.origin} 走同一只筛子,同样是这条纪律。
+ */
+export type DeniedBy = "policy" | "hook" | "org" | "classifier" | "plan_mode" | "compliance" | "write_protection" | "ask_resolution";
+/**
+ * 这次门通过的**最终处置**:放行,或被哪一层拒。deny 臂**必须**点名那一层 —— 这正是它与 allow 臂
+ * 在类型上分家的理由(「拒了但说不出谁拒的」写不出来)。
+ */
+export type GateDisposition = {
+    kind: "allowed";
+} | {
+    kind: "denied";
+    deniedBy: DeniedBy;
+};
+/**
+ * 一只 ask 在等的那次等待**怎么结束的** —— 按 `kind` 判别的联合(core 7.6.0 `SETTLEMENT_KINDS`,闭十二词)。
+ *
+ * 🔴 它**刻意不是** `kind × who` 的自由积:自由积表达得出「human_allowed,由引擎的窗结束」——一条结构完整
+ * 却自相矛盾的记录,而消费端随后就得自己记住这张配对表。这里 `who` 的形**由词决定**:两个 human 词带人,
+ * 两条窗词说是谁的窗,park 词说是宿主,fail-closed 那一族谁也不是。
+ * 🔴 **单铸律**:每一个词都由**引擎**在那次等待结束的地方铸出来。宿主永不铸词,只报**事实**(同步 approver
+ * 报 `human`/`timeout`,耐久 decide 报 `decidedBy: "person" | "sla_timeout"`),core 据此铸词。
+ * ⚠️ server 侧投影:`who.approver`(宿主派生的身份串)与 `note`(拒批人自己写的自由文本)在上 wire 前
+ * 都过脱敏,`note` 另有长度上界。
+ */
+export type Settlement = {
+    /** 人(或代他行事的 approver)做了决定;`human_refused` 可带决策者自己写的那句话。 */
+    kind: "human_allowed" | "human_refused";
+    who: {
+        party: "person";
+        approver?: string;
+    };
+    /** epoch ms,写在结算发生的那一处。 */
+    when: number;
+    /** 拒批人附的那句话。**没有 note 的拒 = 一句干脆的「不」**,不是「没说理由的 bug」。 */
+    note?: string;
+} | {
+    /** 审批窗走完了没人答:引擎自己的审批工厂窗,或同步宿主 approver 报「我的窗到了」。 */
+    kind: "approval_window_expired";
+    who: {
+        party: "engine";
+        window: "approval_factory";
+    } | {
+        party: "host";
+    };
+    when: number;
+} | {
+    /** 分类器拒绝上限回落的自动拒窗(core 在同步腿上自己的计时器)走完了没人答。 */
+    kind: "denial_limit_window_expired";
+    who: {
+        party: "engine";
+        window: "denial_limit";
+    };
+    when: number;
+} | {
+    /** 一次**耐久 park** 的 SLA 到期,宿主的扫把它判成拒。店的 `expire`/`reap` 不产 `tool_end`,
+     *  因此也不产结算。 */
+    kind: "park_sla_expired";
+    who: {
+        party: "host";
+        approver?: string;
+    };
+    when: number;
+} | {
+    /** fail-closed 一族 —— 结束这次等待的不是某个人,是处境本身。
+     *  `no_approver`(headless:没接 approver / 问答面,或就是拒的姿态串)/ `approver_unavailable`
+     *  (approver 对**路由**问题答了「没人可达」,且没有 park 接住)/ `approver_error`(它抛了)/
+     *  `approver_contract`(它答在契约之外)/ `presentation_failed`(参数或编辑没法安全呈现/采纳)/
+     *  `blanket_allow_refused`(整体放行撞上 `requiresRealApproval` 的 ask)/ `task_aborted`
+     *  (等待的中止信号结束了它)。 */
+    kind: "no_approver" | "approver_unavailable" | "approver_error" | "approver_contract" | "presentation_failed" | "blanket_allow_refused" | "task_aborted";
+    who: {
+        party: "none";
+    };
+    when: number;
+};
+/**
+ * 🔴 **BREAKING(server ≥ 7.64.0,core 7.6.0 design/390 S6-A)—— 一次工具门通过的整条记录。**
+ *
+ * 它取代了 7.63.0 及以前的四个正交词(`settledBy` / `resolution` / `autoDenied` / `approver`,**四键全删,
+ * 无 alias**):那四个词的配对规则只活在注释里,消费端要靠**缺席**推语义(「有 `timeout` 没有 `resolution`
+ * ⇒ 耐久 park 过期」)。现在配对规则是引擎的四条不变量,判据是引擎的一只筛子。
+ *
+ * **铸一次,投三面**(门的出口;耐久 park 走 decide 车道)—— `permissionDenied` 观察者的载荷、这次调用的
+ * `tool_end` 帧、耐久行的 resolved outcome。三面是同一张对象图,所以讲不出三个故事。
+ *
+ * 三个成员正交,但被引擎的四条不变量绑住:
+ *  · **I1** `settlement` 在场 ⇔ `origin` 在场(它们说的是同一只 ask);
+ *  · **I2** `deniedBy === "ask_resolution"` ⇒ `settlement` 在场且是拒绝类词;
+ *  · **I3** `human_allowed` 结算旁边出现 `denied` 处置 ⇒ 那是**人批了之后的复查**否决,`deniedBy` 必是可否决层
+ *    (`policy` / `hook` / `org` / `write_protection`),而 approver 留在结算上(这不是 approver 的拒);
+ *  · **I4** `allowed` 处置 ⇒ `settlement` 缺席或恰是 `human_allowed`。
+ *
+ * 🔴 **没有任何一项从缺席读出来**:普通放行是 `{ disposition: { kind: "allowed" } }`,直接策略拒是
+ * `{ disposition: { kind: "denied", deniedBy: "policy" } }`,两者都不带结算 —— 因为两者都没结算过什么。
+ * 🔴 **server 对过不了引擎不变量筛的记录整条不投**(report + withhold,计数 `server.trace.gate-outcome-defective`),
+ * 所以「本该有 `gate` 却缺席」除了「门没看见这次调用」(未武装的门 / 延后重发 / reconcile 捡回的孤儿)之外
+ * 还有第四种成因:那条记录坏了。四者在 wire 上不可分辨 ⇒ 一律退回 `isError` + 文案。
+ */
+export interface GateOutcome {
+    disposition: GateDisposition;
+    /** 只在**这次通过真的结算了一只 ask** 时在场。与 {@link origin} 同在同缺(I1)。 */
+    settlement?: Settlement;
+    /** 谁**问**的。与 {@link settlement} 同在同缺(I1)。 */
+    origin?: AskOrigin;
+}
+/**
+ * 一次失败的 MCP 请求**到没到那台服务器**(core 7.6.0 `MCP_DELIVERY_VERDICTS`,闭三词)。
+ *  · `yes` —— 服务器答了(`protocol` 型拒绝本身就证明交换发生过);
+ *  · `no` —— **可证**没发出去(connect 相 errno / spawn 失败 / 声明畸形 / 已知死掉的服务器)⇒ 直接重试或
+ *    放弃都安全,什么都没执行;
+ *  · `unknown` —— 客户端在交换中途不等了或丢了管道(超时 / 在飞关闭 / reset / 前置网关给的 HTTP 状态)⇒
+ *    请求**可能**已经执行,带写副作用的工具必须先核实再重试。
+ *
+ * 🔴 **与 `errorCode` 合读,别单读**:同一个 `connection_closed`,`no` 可以直接重试、`unknown` 必须先去查 ——
+ * 这正是判词自成一格、不折进失败类的理由。
+ * ⚠️ `no` 说的是**调用方的工具调用**没发出去,**不**保证「那台服务器一个字节都没收到」(dial 期的
+ * elicitation 可能已经跨过连接)—— core 的契约原话,逐字透传。
+ */
+export type McpDelivered = "yes" | "no" | "unknown";
+/**
+ * MCP 失败的**类**(core 7.6.0 `MCP_FAILURE_KINDS`,闭十词)—— `tool_end.errorCode` 与
+ * `wiring_manifest.mcp[].errorCode` 上 MCP 那一族的取值。
+ *  `connect_refused`(连接相 errno:请求**可证**从未离开)/ `connection_failed`(其他 errno:可能跑过了)/
+ *  `connection_closed`(SDK 报传输已关:在飞时命运不可知,对已知死掉的服务器则从未尝试——两者靠
+ *  {@link McpDelivered} 分辨)/ `http_status`(HTTP 端点回了状态而不是 MCP 响应;数字在 `httpStatus`)/
+ *  `not_mcp_response` / `spawn_failed`(stdio 子进程起不来)/ `timeout` / `protocol`(服务器**答**了一个
+ *  MCP/JSON-RPC 错:交换发生过)/ `invalid_config`(声明本身拨不出去 —— 要改 spec,不是等它恢复)/ `unknown`。
+ * 🔴 core 7.6.0 起**退役** `MCP_FAILURE_CODES` 那张十词表,`network` 与 `http_<status>` **两种拼法一并作废**
+ * (HTTP 状态从此走结构位 `httpStatus`,不再编进码里)。
+ * 🔴 `tool_end.errorCode` 整体仍是**开集**(词表属主是工具);本类型只描述其中 MCP 这一族,按开集读。
+ */
+export type McpFailureKind = "connect_refused" | "connection_failed" | "connection_closed" | "http_status" | "not_mcp_response" | "spawn_failed" | "timeout" | "protocol" | "invalid_config" | "unknown" | (string & {});
 /** Open set — render unknown types generically, never crash.
  *
  *  design/99 §E1/§E2 (SHIPPED, service `TraceBlock`/`projectEvents` project.ts:69-73,160-165): the action-card
@@ -1630,16 +1902,18 @@ export type TraceBlock = {
 /** `label` 同 `tool-call`(`toolResultFieldsOf`,`trace/project.ts:603`);`totalChars` = **截断前的可信总量**
  *  (core 1.442 / RB-210,`:604`)—— `truncated:true` 时「还剩多少没显示」= `totalChars` 减已渲染长度。
  *  与 `honest-absence-not-fabricated-zero` 同族:缺席 = 旧 core / 未截断场景,**不要当 0 读**。 */
-/** `settledBy` = core ≥5.18.1 (#187):这次调用**是怎么结算的**(`human` 有人真答 / `timeout` 审批窗到期 /
- *  `aborted` 中止·参数不可克隆·出契约)。与 `AgentEvent.tool_end.settledBy` **同一个值**——server 的共享
- *  挑键器 `toolResultFieldsOf` 把它同时喂给 turns 面与 SSE 面,所以三处必须同形(此前只补了 tool_end,
- *  两条 trace 面漏声明 = 运行时给了值、类型上却拿不到)。
- *  🔴 **缺席不带语义**:旧 worker 与「姿态臂故意不填」(headless auto-deny / 整体放行)两种来源不可区分,
- *  所以既不等于 `human`,也不等于「没走审批」。闭集但按开集读(引擎是词表属主,禁无 default 的穷举)。 */
+/** 🔴 **server ≥7.64.0 BREAKING**:`gate` = 这次调用**整条门记录**({@link GateOutcome})—— 它取代了退役的
+ *  四个正交词 `settledBy` / `resolution` / `autoDenied` / `approver`(四键全删,无 alias)。与
+ *  `AgentEvent.tool_end.gate` **同一个值**:server 的共享挑键器 `toolResultFieldsOf` 把它同时喂给 turns 面
+ *  与 SSE 面,所以三处同形(历史教训:此前只补 tool_end、两条 trace 面漏声明 = 运行时给了值、类型上拿不到)。
+ *  🔴 **读腿是独立的一道筛**:账本行可以来自任何引擎世代或第三方 producer,所以坏记录在读面同样被扣下 ——
+ *  缺席不是关于这次调用的事实。
+ *  `delivered` = MCP 投递判词({@link McpDelivered}),与 `errorCode` **合读**;非 MCP 失败上恒缺席。
+ *  `gatedCallId` = 耐久 park 正扣着哪个 call(core ≥5.55.0);tool-less park 上缺席。 */
 /** `errorCode` = core ≥5.9.0(W3 / [2535],#191 件三补):这次调用**为什么失败**的机器可判别短码。
  *  与 `AgentEvent.tool_end.errorCode` **同一个值**(server 的共享挑键器 `toolResultFieldsOf` 同时喂 turns 面
  *  与 SSE 面),完整语义见那一处的长注。
- *  🔴 **开集**(与同帧上闭集的 `settledBy` 不同族):词表属主在**工具**那一侧,任意 `ToolResult.details.code`
+ *  🔴 **开集**:词表属主在**工具**那一侧,任意 `ToolResult.details.code`
  *  都可能到达 —— 分支已知值、永远带 `default`。与 HTTP 错误体上的 `errorCode` 是两个不同的命名空间,只是
  *  同名;**两者都可增补**,差别在属主与兜底手段(HTTP 那张属 server、按前缀/状态码兜底;本键属工具、
  *  只能靠 `default`)—— 完整口径见 `AgentEvent.tool_end.errorCode` 的长注。 */
@@ -1652,7 +1926,9 @@ export type TraceBlock = {
     truncated?: boolean;
     totalChars?: number;
     structured?: unknown;
-    settledBy?: "human" | "timeout" | "aborted";
+    gate?: GateOutcome;
+    delivered?: McpDelivered;
+    gatedCallId?: string;
     errorCode?: string;
     eventId?: string;
     parentToolCallId?: string;
@@ -1750,7 +2026,9 @@ export type TraceStreamEvent = {
         truncated?: boolean;
         totalChars?: number;
         structured?: unknown;
-        settledBy?: "human" | "timeout" | "aborted";
+        gate?: GateOutcome;
+        delivered?: McpDelivered;
+        gatedCallId?: string;
         errorCode?: string;
         eventId?: string;
         parentToolCallId?: string;
@@ -1998,6 +2276,66 @@ export interface McpServerSpec {
 }
 /** Worker capability map (`GET /v1/capabilities`). Open set — ignore unknown keys. Booleans
  *  share deps with the route gates ("says yes but 501s" is structurally impossible, producer-tested). */
+/**
+ * `permissionModeAuto` 的**武装未达成因由**(server `AUTO_MODE_UNARMED_REASONS` 闭六词;S-80)。
+ * 🔴 **按开集读**:词表已经从四词长到六词,server 再加员时未知词必须落进 `default` 臂当「未知因由」,
+ * 不许被当成「没有因由」。`local_denied`(本机 `PERMISSIONS_DISABLE_AUTO_MODE`)与 `org_denied`
+ * (center deny)**分词就是为了让壳指不同的路**(改本机 env vs 找组织),消费端别把两者折在一起。
+ */
+export type AutoModeUnarmedReason = "mode_not_auto" | "deployment_incapable" | "org_denied" | "local_denied" | "settings_denied" | "resolver_fault" | (string & {});
+/** 三代形共有的三位 —— server **≤7.56.0 只发这三位**(见 {@link PermissionModeAutoCapability})。 */
+interface PermissionModeAutoBase {
+    /** 提交面按五词闭集收 `"auto"`(server 写的是字面量,恒 `true`)。 */
+    accepted: true;
+    /** 分类器席位真挂上了(桩 / 一次性 CLI 不挂席位时如实 `false`)。 */
+    classifierSeat: boolean;
+    /** **center 源在不在**,绝不冒充「你被授权了」—— 授权是 per-principal 的,部署级布尔对它说不了话。 */
+    entitlementSource: boolean;
+    [k: string]: unknown;
+}
+/**
+ * `capabilities.permissionModeAuto` 的**两代形**(判别位 = `armed` 的**三态**)。
+ *
+ * 🔴 **武装三键(`intentArming` / `armed` / `reason`)是 server ≥7.57.0(S-80)才有的**,而本包声明的
+ * 支持地板是 **3.0.0** ⇒ 每一台 7.x ≤7.56.0 的 server 都在承诺面内,它们**只发** {@link PermissionModeAutoBase}
+ * 那三位(亲核 server tag `v7.50.0` / `v7.56.0` 的 `routes/capabilities.ts` 逐字确认)。
+ * 所以 `armed` **不能**写成必填:写成必填会让
+ * ```ts
+ * if (!auto.armed) console.log(auto.reason.toUpperCase());   // 老 server 上 reason 根本不在场
+ * ```
+ * **编译通过、运行期炸**,而 spec 侧同样会把一台受支持 server 的**合法**响应判成非法。
+ *
+ * 🔴 正确读法是**三态**,不是二值:
+ *  · `armed === true` —— 此刻会武装;
+ *  · `armed === false` —— 此刻不会,`reason` **必在场**(按开集分支);
+ *  · `armed === undefined` —— **老 server,武装态不可知**。禁折成 `false`(那会把一台正在武装的
+ *    7.50 部署渲成「auto 是 default 的别名」),该渲成「这台 worker 不报武装态」。
+ *
+ * 四位披露键**刻意不合成一个布尔**:合成后「这份二进制不认识 auto」与「认识但本机没有 entitlement 源」
+ * 会得到同一个 `false`,而壳对这两种要做的事不同(前者别给这一档;后者给,但别宣称在筛)。
+ */
+export type PermissionModeAutoCapability = 
+/** **server ≤7.56.0**:只有三位,武装三键**整体缺席**(`armed` 缺席 = 武装态不可知)。 */
+(PermissionModeAutoBase & {
+    intentArming?: undefined;
+    armed?: undefined;
+    reason?: undefined;
+    model?: undefined;
+})
+/** **server ≥7.57.0** · 会武装。`model` = 分类器**配置**的模型路由;解不出时 server 不写这个键。 */
+ | (PermissionModeAutoBase & {
+    intentArming: boolean;
+    armed: true;
+    reason?: undefined;
+    model?: string;
+})
+/** **server ≥7.57.0** · 不会武装 ⇒ `reason` 必在场(闭六词,按开集分支)。 */
+ | (PermissionModeAutoBase & {
+    intentArming: boolean;
+    armed: false;
+    reason: AutoModeUnarmedReason;
+    model?: string;
+});
 export interface Capabilities {
     asyncRuns?: boolean;
     /** [1833] G6(server `src/http/routes/capabilities.ts` 的 `sideQuery` 位,恒 `true` —— runner 自带):
@@ -2332,6 +2670,239 @@ export interface Capabilities {
     sendUserFileLedger?: boolean;
     /** GET /v1/workflows 列表面(`routes/capabilities.ts` 的能力对象 `Boolean(workflowRunStore)`;`workflows` 总位见上)。 */
     workflowsList?: boolean;
+    /** device lane 探测位(server `routes/capabilities.ts:162`;design/device-executor-lane-v2 §4.8)——
+     *  **一个诚实对象或 `false`**,与 {@link fleet} / {@link workspace} 同族三态形。谓词 = `deps.deviceHub`
+     *  在场,而那正是 `GET /v1/device/ws` 的 upgrade 处理器挂没挂的**同一个**判据(`server.ts` 的
+     *  `deps.deviceHub?.attach(server)`)⇒「说 yes ⟺ 设备连得上」是结构性的,executor 不必
+     *  trial-by-upgrade-404。三个字段各答一件 executor 在**首连之前**就必须知道的事:
+     *   · `protocolVersion` —— 本 server 说第几版(§5.6:不满足最低版 = 响亮 helloReject,**不静默降级**);
+     *   · `maxInflightPerDevice` —— per-device 在途上限(§5.5 背压;超额在云侧排队,到期 `device.busy`);
+     *   · `wsPath` —— upgrade 路径。**刻意上 wire** 而不让客户端硬编码:路径是 server 铸的 wire 契约的
+     *     一部分,硬编码在别的仓里 = 把「改路径」变成一次跨仓破坏性变更。
+     *  🔴 server **刻意不广告**设备台数 / 在线态:那是管理面(`/v1/devices/*`)的事,能力面暴露它等于给
+     *  未鉴权探测送一个组织规模 oracle。 */
+    deviceExecutor?: false | {
+        enabled: true;
+        protocolVersion: number;
+        maxInflightPerDevice: number;
+        wsPath: string;
+        [k: string]: unknown;
+    };
+    /** 记忆**引擎**位(server `routes/capabilities.ts:210` = `projectMemoryEngineCapability(deps.memoryPosture)`,
+     *  实现在 `src/memory-posture.ts:143`)—— 对象 = 本部署的记忆面**真点亮**,`false` = 暗。判据**逐字**是
+     *  boot 的 `memoryPosture`(`boot/stores.ts` 的单一推导点)的窄投影,与 operator 诊断面
+     *  `GET /v1/diagnostics/wiring` 的 `memoryPosture` 段同源 ⇒「诊断页说亮、能力位说暗」结构上不可能。
+     *  🔴 与 {@link memory} / {@link memoryWrite} **不是**一回事:那两位说的是**退役的** MemoryStore HTTP
+     *  动词(恒假,且会一直恒假);本位说的是**引擎接线**,它没有 HTTP 动词面 —— 记忆是模型在注入目录上的
+     *  文件技能。所以本位为真**不**意味着有记忆读写端点可打(那正是 legacy 两位在否认的东西)。
+     *  🔴 `vectorMode: null` = 这条腿**没有档位指示面**(`file` 引擎),**不是**「档位是词面」。 */
+    memoryEngine?: false | {
+        backend: "file" | "pg" | "tidb" | (string & {});
+        vectorMode: "native" | "portable" | "lexical" | null;
+        [k: string]: unknown;
+    };
+    /** 本部署的 **SQL 事务读语义**(server `routes/capabilities.ts:216` =
+     *  `projectSqlEngineCapability(deps.sqlEngineFacts?.())`,实现在 `src/sql-engine-posture.ts:57`;S-131)。
+     *  判据**逐字**是驱动连接初始化**回读复核过**的那份事实(`plugins/sql-driver.ts` 的 `SqlEngineFacts`),
+     *  与 operator 面 `GET /v1/diagnostics/wiring` 的 `sqlEngine` 段同源(那一段另有一个 `version`,纯排障料,
+     *  刻意不进本位)⇒「诊断页说悲观、能力位说乐观」结构上不可能。
+     *  🔴 `null` = 本部署**没有 SQL 后端**(env-only worker / local 文件后端),**不是**「读不出来」。
+     *  🔴 `txnMode: null` = 这个引擎**没有该指示面**,**不是** `"optimistic"`。
+     *  受众是运维与部署自述:一个多副本部署不登服务器就能答出「本仓的连接跑在什么读语义上」。 */
+    sql?: null | {
+        engine: "tidb" | "innodb" | "pg" | (string & {});
+        isolation: string;
+        txnMode: "pessimistic" | null;
+        [k: string]: unknown;
+    };
+    /** **远端车道可 detach**(server `routes/capabilities.ts:233` = `Boolean(deps.runStore)`)—— 零新机制,
+     *  说的就是既有的那条腿:`POST /v1/tasks/stream` 带请求头 `x-detach-on-disconnect: true` ⇒ 客户端断连
+     *  **不杀** run,它在 server 跑完;回来按响应头 `X-Task-Id` 走 `GET /v1/runs/:id` 与 `/events`
+     *  (durable 事件日志重放 + `Last-Event-ID` 续流)拿全离开期间的帧。
+     *  谓词 = **部署半场**,逐字就是那条腿自己的前置判据(`routes/tasks.ts` 缺 runStore ⇒ 400
+     *  `request.precondition_unmet`「detached 的结果无处可查」);**per-request 半场(调用方必须带
+     *  `sessionId`)不在本位里** —— 那是每次调用自己的事,部署级布尔对它说不了话。
+     *  🔴 **辖域只到远端车道**:本地车道的转后台归壳自己的判据,本位不覆盖、也不许被拿去禁本地。
+     *  🔴 **不承诺** detach 期间流内审批的存活(那条另有 {@link approvals} / {@link streamApproval} 广告;
+     *  本位为真而它们为假的部署上 detach 照常工作,只是断连那刻挂起的审批走 core 的 fail-closed 臂)。
+     *  今天取值与 {@link asyncRuns} 相同是**诚实记账不是冗余**:那一位问「异步 run API 在不在」,本位问
+     *  「壳的转后台键在远端车道该不该映射成 detach」。 */
+    sessionBackgroundable?: boolean;
+    /** 中途翻转 verb `POST /v1/runs/:id/memory/capture-optout` 的在场位(server `routes/capabilities.ts:237`
+     *  = `Boolean(deps.runStore)`;design/383 S-8①)。谓词与 {@link sessionBackgroundable} 同源:该 verb 需要
+     *  持久 run 账面做属主门 + 活流句柄。缺席(老 worker)⇒ 壳**不渲入口**(假 affordance 纪律)。
+     *  🔴 位为真只保证**端点在场**,不保证这一次是 live —— 非 live ⇒ 409 指路声明形。 */
+    runMemoryCaptureOptOut?: boolean;
+    /** 治理携出 bundle 两口 `POST /v1/memory/{export,import}`(operator lane)的位
+     *  —— server `routes/capabilities.ts:261` = `Boolean(deps.memoryBundleExport && deps.memoryBundleImport)
+     *  && deps.config.operatorPrincipals.length > 0`(#264 v2-c)。
+     *  ⚠️ 位为真**不**保证后端真有 bundle 复合面:server 的两只 SQL 记忆孪生未实现
+     *  `exportSnapshotOf`/`importBundleCommit`,那时 core 响亮拒 `memory.export_incomplete`。 */
+    memoryBundle?: boolean;
+    /** 出处 / 抹除合规两口 `GET /v1/memory/entries/:entryId/provenance` · `POST /v1/memory/erase`
+     *  (operator lane)的位 —— server `routes/capabilities.ts:273` = `Boolean(deps.memoryCompliance) &&
+     *  operatorPrincipals.length > 0`(design/316 件③)。第一项在**挂载期**判后端有没有控制面归属(缺则整口不挂)。
+     *  ⚠️ 与 {@link memoryBundle} **不同源**:一个部署可以有 bundle 复合面而没有控制面归属,反之亦然。 */
+    memoryCompliance?: boolean;
+    /** 外源标记人面三口 `GET /v1/memory/origin/external` · `GET /v1/memory/origin/clearances` ·
+     *  `POST /v1/memory/origin/entries/:entryId/clear`(operator lane)的位 —— server
+     *  `routes/capabilities.ts:287` = `Boolean(deps.memoryOriginFace) && operatorPrincipals.length > 0`
+     *  (design/316 件②)。
+     *  ⚠️ 与 {@link memoryCompliance} **同判据不同位**:两族今天查后端的同一个面(`controlPlaneRoot`),
+     *  但它们是**两个产品面**(合规问询/抹除 vs 外源审计/清标),一个部署可以只想开其中一族 ——
+     *  server 刻意不合并,即使今天两位恒同值。
+     *  ⚠️ 位为真**也不**保证 `GET …/external` 的答案完备:server v1 没有 scope 枚举读面,答案只覆盖调用方
+     *  点名的那些 scope,**空答绝不读作「本店干净」**。 */
+    memoryOrigin?: boolean;
+    /** consolidation 阀门两口 `POST /v1/admin/memory/consolidation/run` ·
+     *  `GET /v1/admin/memory/consolidation`(operator lane)的位 —— server `routes/capabilities.ts:301`
+     *  = `Boolean(deps.memoryConsolidation) && operatorPrincipals.length > 0`(design/378 D4)。
+     *  第一项 ⟺ `MEMORY_CONSOLIDATION_DRIVER=on` **且**座解析成功(座配不出 / 引擎没接线 / 后端无控制面
+     *  归属 / provenance=off 四形都在**启动期**被拒,那些机器根本起不来)。
+     *  🔴 位为假时两口是 **404**(整域不挂)**而不是 501** —— 消费端别按 501 分支(阀门未开是一句运维表态,
+     *  不是部署能力缺失);与 {@link memoryOptOutGrant} 的 501 分家。
+     *  ⚠️ 位为真不保证这一轮跑得完:模型失败 / fuse 残留 / 被 park 都是运行期事实,落在收执的 `outcome` 上
+     *  (200 + 一个非 converged 的停因)。 */
+    memoryConsolidationDriver?: boolean;
+    /** memory-capture opt-out **授权表**管理四口 `/v1/admin/memory-optout[/default|/:principal]`
+     *  (operator-only)的位 —— server `routes/capabilities.ts:307` = `Boolean(deps.memoryOptOutGrant) &&
+     *  operatorPrincipals.length > 0`(design/383 S-2)。第一项 = 授权表在场(SQL 后端有;**local 车道刻意无源**
+     *  ⇒ 四口 501 `capability.memory_optout_grant_required`)。
+     *  🔴 位为假时是 **501**(换部署形态),与 {@link memoryConsolidationDriver} 的 404(开旋钮)分家。 */
+    memoryOptOutGrant?: boolean;
+    /** `permissionMode: "auto"` 的**缺省态披露**(server `routes/capabilities.ts:463`;裁决在
+     *  `src/auto-mode-face.ts` 的 `judgeAutoModeArming`)。**四项刻意不合成一个布尔** —— 合成后
+     *  「这份二进制不认识 auto」与「认识但本机没有 entitlement 源」会得到同一个 `false`,而壳对这两种要做的
+     *  事不同(前者别给这一档;后者给,但别宣称在筛)。
+     *   · `accepted` —— 提交面按五词闭集收 `"auto"`(恒 `true`,server 写的是字面量);
+     *   · `classifierSeat` —— 分类器席位真挂上了(server 读装配面递来的 `autoModeFace.seatMounted`,
+     *     桩 / 一次性 CLI 不挂席位时如实 `false`);
+     *   · `entitlementSource` —— **center 源在不在**,绝不冒充「你被授权了」(授权是 per-principal 的,
+     *     部署级布尔对它说不了话);自 S-80 起它是**三态里的一格**,`false` 不再意味着 auto 不武装;
+     *   · `intentArming` —— 这对 server+core 走的是哪套极性:`true` = core #521 的**意图武装式**
+     *     (用户开 + org 拒),`false` = 旧式「org 授予」。壳据此渲「无 center 也能 auto」与否;
+     *   · `armed` —— **此刻会不会武装**(按当前运行时真值答;旧式 core 下按旧谓词答,不得假阴);
+     *   · `reason` —— **仅** `armed:false` 时在场,server 闭六词集(`AUTO_MODE_UNARMED_REASONS`)。
+     *     `local_denied` = 本机 `PERMISSIONS_DISABLE_AUTO_MODE`,`org_denied` = center deny ——
+     *     **分词就是为了让壳指不同的路**(改本机 env vs 找组织)。按开集读:server 已经从四词长到六词。
+     *   · `model` —— 分类器**配置**的模型路由(core 的 role 回落链 `classifier → summarize → default`);
+     *     解不出时 server **不写这个键**(把 core 的拒句当数据记进日志,读面不 500)。
+     *  🔴 查询串 `?permissionMode=<五词>` 把「本次意图」折进裁决(缺席 = 按 auto 意图答);五词闭集之外
+     *  server 回 **400 `request.field_invalid`**(读面也不静默折词)。 */
+    permissionModeAuto?: PermissionModeAutoCapability;
+    /** READ 容纳面的**生效档**披露位(server `routes/capabilities.ts:484` = `deps.config.readFace ?? null`;#A4)。
+     *  值 = 本部署**显式**表态的那一档(env `READ_FACE`,或 config-center 的 `readFace.face` —— 两条腿落的是
+     *  同一个 config 键,所以这一位对「组织下发」与「本机 env」不做区分,它说的是**最终生效值**)。
+     *  🔴 `null` = **本部署没有钉这一档**,由引擎默认接管。server 刻意**不**把 `null` 折成 `"roots"`:
+     *  在这条轴上从不复制上游默认 —— 把引擎默认抄进 wire 会在 core 改默认的那天变成一句谎,而消费端无从察觉。
+     *  🔴 **最小披露**:deny 表(pattern 表 / 内建档位 / 排除行名)**不上**能力面 —— 那是策略内容。
+     *  ⚠️ 与 `TaskRequest` 无关:这条轴上**没有** per-request 接收臂(部署 env 席,负控钉在
+     *  `test/capabilities-full.test.ts` 的「A4 / [4073] readFace 定界」那组)。 */
+    readFace?: "open" | "roots" | (string & {}) | null;
+    /** 调用方给的 `cwd` **到底兑不兑现**的精确位(server `routes/capabilities.ts:541` =
+     *  `cwdHonored(deps.config) || deviceCwdHonored(deps.config)`)。真 ⟺ 单用户 `host` lane **或**
+     *  `device` lane(路径落在**发起者自己的**机器上,host 闸防的跨租户宿主穿越在那儿结构性不存在)。
+     *  谓词与提交侧 `boot/resolve-spec.ts` 的写侧闸**逐字同源** —— 它漂了就是「说没有其实有」。
+     *  消费端读法:**优先读本位**;缺席(老 worker)⇒ 按 {@link projectContext} 兜底 = 本位出现前的逐字行为。 */
+    callerCwd?: boolean;
+    /** A2A **client** 读面 `GET /v1/sessions/:id/a2a` 在场位(server `routes/capabilities.ts:555`,恒 `true`;
+     *  DESIGN-269 车1 件4)。与 {@link mcp} 同姿势的无条件位:没配 peer 时它回一个**诚实的空面板**,
+     *  所以根本没有 501 路可门。
+     *  🔴 与 {@link a2aInjection} **刻意两位不同谓词**(一位诚实不了两件事):本位答「读面在不在」。 */
+    a2a?: boolean;
+    /** 本部署**是否兑现**调用方送的 `body.a2aPeers`(server `routes/capabilities.ts:556` =
+     *  `a2aInjectionHonored(deps.config)`,属主 `src/task-a2a.ts`)。三条否决全归那只函数:
+     *  单用户 ∧ `a2a` 未锁 ∧ 合规允许。
+     *  🔴 `false` 的行为是**字段门**形:请求照样 200,字段被 **warn + 忽略**(不是 4xx)——
+     *  **例外**是配置被 lock 时,提交口 400 `config.locked_key`(那条 veto 正是让「说 yes ⟺ 路真能用」
+     *  在这一形上仍成立的东西)。 */
+    a2aInjection?: boolean;
+    /** server-as-peer 半场的**旋钮实况**(server `routes/capabilities.ts:564` =
+     *  `deps.config.a2aServe !== undefined`;DESIGN-269 车2)—— 这台 worker 是否作为一个 A2A agent 对外存在。
+     *  `true` ⟺ `A2A_SERVE_ENABLED` 开 ⟺ `GET /.well-known/agent-card.json` 与 `POST /v1/a2a` 两条路由存在;
+     *  `false` ⟺ 两条都 **404**(设计稿 §3.3「卡都不发 = 对外不存在」)。缺席即关。
+     *  ⚠️ **辖域 = 路由在不在,不是「每个方法都能跑」**:`message/send` / `tasks/get` 还需要 durable run store
+     *  (缺它时两个方法回具名 JSON-RPC `-32004`,不是静默降级)。server 刻意不把 runStore 折进本位 ——
+     *  那会造出「卡还在发、位却是 false」这种更糟的谎。 */
+    a2aServe?: boolean;
+    /** 后台 agent **名册读面** `GET /v1/agents/roster` 的位(server `routes/capabilities.ts:640` =
+     *  `Boolean(deps.backgroundAgentStore)`;#A1)。谓词**逐字**是那条路由的 501 门 ⇒「说 yes ⟺ 路由真能用」
+     *  是结构性的。
+     *  ⚠️ **辖域 = 列举面**:名册回的是 content-free 投影(handle / name / agentType / status / 三个时间戳);
+     *  要子代**产物正文**走 `/v1/runs/:id/subagents/:handle/output`(那条口有它自己的谓词 {@link subagentOutput})。 */
+    agentRoster?: boolean;
+    /** **托管留存**的部署事实(server `routes/capabilities.ts:654` = `retentionAdvertisement(deps.config)`;#270 车2)。
+     *  `null` = sweep lane 关着(缺省);在场 = `{mode, maxAgeDays}` —— 两格都是**部署事实不是秘密**
+     *  (策略数值本来就该告诉用户「你的数据留多久」)。`mode: "audit-only"` = 照跑照判、只记审计行、
+     *  **不调任何破坏性方法**;`"enforce"` = 真删。
+     *  🔴 谓词只看 config 而不合取「执行器在场」是**结构性**的,不是疏漏:`intervalSec > 0` 而没有真执行器的
+     *  那台机器**根本起不来**(`boot/retention-lane.ts` 的 `assertRetentionLaneWirable` 在 boot 期就拒了)。 */
+    retention?: null | {
+        mode: "audit-only" | "enforce" | (string & {});
+        maxAgeDays: number;
+        [k: string]: unknown;
+    };
+    /** 自编排(workflows)的**拒因披露**(server `routes/capabilities.ts:739`;S-81)。**两项刻意不合成一个
+     *  布尔**(与 {@link permissionModeAuto} 同判据):
+     *   · `engineCan` —— core 的 `workflowsCapability`(硬化脚本 runner ∧ 治理基线)。`false` = 这台机器压根
+     *     没有工作流引擎,壳别给这一格;
+     *   · `denial` —— **部署级准入**拒因闭集(今日唯一成员 `"entitlement_resolver_absent"`),`null` = 这一层
+     *     不拒。非 `null` = 引擎在、但本部署对**任何** principal 都授不出去(半配置:阀门开着而配不出来)——
+     *     壳该提示运维接 config-center(或关掉 `SELF_ORCHESTRATION_ENABLED`),**而不是提示用户重试**。
+     *  🔴 `denial: null` **不**等于「你被授权了」:授权是 per-principal 的(core 逐 principal 解 `allowWorkflows`),
+     *  部署级布尔对它说不了话 —— 与 `permissionModeAuto.entitlementSource` 同一条辖域线。
+     *  🔴 与 {@link workflows} 的关系:那一位是 `engineCan × 准入` 的**乘积**(「说 yes ⟺ 这台机器上真跑得起来」),
+     *  本位把两个因子拆开给壳看拒因。 */
+    workflowsGate?: {
+        engineCan: boolean;
+        denial: "entitlement_resolver_absent" | (string & {}) | null;
+        [k: string]: unknown;
+    };
+    /** **写保护名表**的姿态(server ≥7.63.0 / S-138;`routes/capabilities.ts` = `projectWriteProtectionCapability`)。
+     *  引擎的**字面名表**把落在表行上的可定路径写(Write/Edit/NotebookEdit)从 `allow` 降级成 `ask`,所以壳
+     *  可以**事先**知道这些路径会弹卡。
+     *  🔴 **三项刻意不合成一个布尔**:合成之后「引擎缺省表在岗」与「运维换了一张自己的表」同为 true,而两者
+     *  对运维说的是两件事。
+     *  🔴 **最小披露**:逐行 name/kind **不在**这一位 —— 部署自定义行可能含内部路径名,列出来等于告诉想绕过的人
+     *  「哪些名字不受保护」。行内容在 operator 面 `GET /v1/diagnostics/wiring` 的 `writeProtection.rows`。
+     *  🔴 与 `SENSITIVE_WRITE_PATTERNS`(**模式型** write deny)是**并列机制**,两个读面分开报、绝不合成一位:
+     *  两者的解法不同(一套改模式,一套改名表)。
+     *  `null` = 这个进程说不出来(非 composition root 装配的夹具形)。**老 worker 上整键缺席,而「没有这个键」
+     *  不是「没有表」** —— 引擎侧座位缺席恰恰是**缺省表在岗**(按键名 grep 推断「没装」会推错,B-023 F2 真案)。 */
+    writeProtection?: WriteProtectionCapability | null;
+    [k: string]: unknown;
+}
+/** 写保护名表的**租户面**窄投影(`GET /v1/capabilities.writeProtection`)。**不含行内容**。 */
+export interface WriteProtectionCapability {
+    /** 生效表非空 ⇒ 引擎真会对表行弹卡。 */
+    armed: boolean;
+    /** 生效表的**行数**(内容只上 operator 面)。 */
+    rows: number;
+    /** 整表替换旋钮被写 ⇒ 缺省表不再原样在岗。与 {@link armed} 刻意不合成。
+     *  ⚠️ 「整表替换成**空**表」也算 —— 报 false 会把「运维亲手关掉了表」说成「缺省表没被动过」。 */
+    replaced: boolean;
+    [k: string]: unknown;
+}
+/** 写保护表的**一行**(core `WriteProtectedRow`):一个**字面**名字 + 它怎么匹配。
+ *  `name` 同时是这一行的稳定身份 —— 拒绝/询问文案里引用的就是这个串。 */
+export interface WriteProtectedRow {
+    name: string;
+    /** `basename` = 目标的**最后一段**等于行名;`segment` = **任意**一段等于行名;
+     *  `segment-run` = **连续若干段**等于行名按 `/` 切出的那几段。 */
+    kind: "basename" | "segment" | "segment-run" | (string & {});
+    [k: string]: unknown;
+}
+/** 写保护表的 **operator 面**(`GET /v1/diagnostics/wiring` 的 `writeProtection`;server ≥7.63.0 / S-138)。
+ *  与租户面能力位**同一份 boot 产物** ⇒ 两面不可能各说各话;本面多出来的是**行内容**。 */
+export interface WriteProtectionPosture {
+    /** 生效表逐行,逐字来自引擎自己的编译产物(server 零重算)。空数组 = 显式无表。 */
+    rows: WriteProtectedRow[];
+    /** `default` = 两根旋钮都没写(引擎缺省表在岗;server **不复制**那张表,属主在引擎)/ `extra` = 缺省表 + 增量 /
+     *  `replace` = 整表替换 / `off` = 整表替换成空表(合法,且响亮)。 */
+    source: "default" | "extra" | "replace" | "off" | (string & {});
+    /** 整表替换**丢掉**的缺省行名;只在替换族在场(`extra`/`default` 结构上丢不掉行)。
+     *  行的身份判据借**引擎自己**的折叠规则,所以大小写变体不会被误报成「你丢了一行」。 */
+    droppedDefaultRows?: string[];
     [k: string]: unknown;
 }
 /** One scenario's detail card (`GET /v1/capabilities/scenarios/:name` — server handler = the
@@ -3110,5 +3681,25 @@ export interface ServerWiringGates {
 export interface WiringDiagnostics {
     static: WiringManifest;
     serverGates: ServerWiringGates;
-}
+    /** **写保护名表**,带**行内容**(server ≥7.63.0 / S-138;operator 面独有 —— 租户面
+     *  `capabilities.writeProtection` 只有计数)。与那一位是**同一份 boot 产物**。
+     *  `null` = 这个进程说不出来。 */
+    writeProtection?: WriteProtectionPosture | null;
+    /** 记忆面姿态(server ≥7.30 / #252):backend / vector 模式 / 点亮态与 dark 成因 / embedder 身份 ——
+     *  此前只活在启动日志里(不可查询、跨副本不可聚合)。
+     *  🔴 **本代 SDK 尚未逐键镜像**:声明在这里是为了让严格消费端停止拒收真实的 operator 响应,按不透明读。 */
+    memoryPosture?: Record<string, unknown> | null;
+    /** 本部署的 SQL 引擎姿态(server ≥7.60 / S-131):引擎 / 版本 / 会话隔离级 / TiDB 事务模式,读的是驱动在
+     *  真连接上 `SET` 完之后**回读**的值,不是 env 里写了什么。`null` = 无 SQL 后端。
+     *  🔴 **本代 SDK 尚未逐键镜像** —— 按不透明读。 */
+    sqlEngine?: Record<string, unknown> | null;
+    /** 配置世代账的 operator 面(server ≥7.5x / #322):按组的 appliedVersion / deferredKeys+铸因 /
+     *  **消毒形** lastRejected(只有键名与判据文案,值从不进读面)。`/health` 那三键是同一份读数的窄投影。
+     *  🔴 **本代 SDK 尚未逐键镜像** —— 按不透明读。 */
+    configApply?: Record<string, unknown> | null;
+    /** mid-turn MCP 撤销名单(server ≥7.5x / #324,design/338)。`null` = 本进程没有配置管道(说不出来)。
+     *  🔴 **本代 SDK 尚未逐键镜像** —— 按不透明读。 */
+    mcpRevocations?: Record<string, unknown> | null;
+}
+export {};
 //# sourceMappingURL=types.d.ts.map