@sema-agent/client-core 0.12.1 → 0.13.0

package/dist/seatContract.d.ts

@@ -12,10 +12,11 @@
  * 落点为什么是本包:desktop 与 web 都已经依赖 `@sema-agent/client-core`(0.11.5),而本文件是
  * **纯类型 + 常量 + 纯谓词**,零值级 import、零 Node 内建 ⇒ 不动本包的可移植闭包(portability 门的
  * `EXPECTED_PACKAGES_INDEX` 一个字不变)。
- * ⚠️ 唯一一条 `import type`(`./effortWire.js` 的 `ReasoningEffort`)是**类型边**:portability 门
- * 走值级传递闭包时按规则剥掉 type-only import(门里 `/^\s*type\b/` 那一跳),bundle 里一个字节都
- * 不多。写成 import 而不是就地复刻那七档,是因为「座位闭集」与「wire 投影闭集」必须是**同一套词**
- * ——复刻一份就等于埋一条只有真用户能发现的漂移(拨盘上的档在座位 lane 上静默到不了引擎)。
+ * ⚠️ 两条 `import type`(`./effortWire.js` 的 `ReasoningEffort`、`./seam.js` 的 `LaneProof`)都是
+ * **类型边**:portability 门走值级传递闭包时按规则剥掉 type-only import(门里 `/^\s*type\b/` 那一跳),
+ * bundle 里一个字节都不多。写成 import 而不是就地复刻,是因为「座位闭集」与「wire 投影闭集」必须是
+ * **同一套词**——复刻一份就等于埋一条只有真用户能发现的漂移(拨盘上的档在座位 lane 上静默到不了引擎;
+ * 车道证明在座位面变成一个「有位无证」的空对象)。
  *
  * ── 搬迁时按「真源为准」收敛的漂移(逐条,web 侧镜像 → 本文件)────────────────────────────
  *  🔴 D1 `LocalSessionEvent.outcome` —— web 镜像整位缺席 ⇒ `tool_permission_resolved` 只会清面,
@@ -24,7 +25,7 @@
  *      而宿主入站门 `requireOptionalPermissionMode` 是**会抛的闭集门**。今日两边词表逐字相等
  *      (web `ComposerMode` 五档 ≡ `PERMISSION_MODE_INTENTS` 五档,已核),所以是**潜伏**不是现症:
  *      ComposerMode 哪天加一档,裸 string 一路放行到宿主门口才抛。收敛成闭集后当天编译红。
- *  D3 `AttachmentUploadReceipt.sha256` / `ToolPermissionRequest.createdAt` / `StartSessionOptions.cwd`
+ *  D3 `AttachmentUploadReceipt.sha256` / `ToolPermissionRequest.createdAtMs` / `StartSessionOptions.cwd`
  *      / `.excludeTools` / `LocalSessionRecord.queuedMessages`·`model`·`engineSessionId` ——
  *      web 镜像缺位。都是「没接线」不是「接错线」(web 侧今日无消费点,已核),收敛后位在、待接。
  *  D4 `LocalSessionEvent.request` —— 真源有这个位,**宿主从不发**(session-host 零处写 `request:`);
@@ -37,6 +38,23 @@
  *    focusedSessionState / settingsState / `CHROME_EVENT_KINDS` / `ATTACHMENT_IDS_PER_TASK_CAP`。
  *    本文件导出后它们对 web 首次可见(接不接线是渲染面的决定)。
  *
+ * ── 🔴 wave2 卡E-seat 的**破坏性契约变更**(2026-08-02,REF-CC-064~070/072~074;发包说明点名)──
+ *  ① `EipcMethodSpec.validate` / `EipcStoreSpec.validate` → **改名 `check`**,返回形从 `boolean`
+ *     升成 `true | SeatValidationFailure`(REF-CC-069)。改名是**安全机制不是洁癖**:老消费点写的是
+ *     `if (m.validate && !m.validate(v))`,而失败**对象是真值** ⇒ 那一行会把「不合格」读成「合格」,
+ *     门从 fail-closed 静默变成 fail-open。改名让每个旧调用点在编译期红,而不是在运行期悄悄放行。
+ *  ② `ToolPermissionRequest.createdAt: number` → **`createdAtMs`**(REF-CC-067):同一文件里
+ *     `LocalSessionRecord.createdAt` 是 ISO 串,两个同名位两种域两种类型;epoch 单位入名(A4)。
+ *  ③ `ToolPermissionRequest.boundCallId` + `.boundInputHash` → **合成 `toctouBinding`**
+ *     (REF-CC-070):注释一直把它称作 pair,而类型/门此前各查各的,半个 pair 照样过门。
+ *  ④ `LocalSessionEvent.chrome.laneProof` **可选 → 必填**且升成命名类型 `LaneProof`(REF-CC-064)——
+ *     出站门本来就要求它在场,类型却说可以缺席:一个照着这份「单一真源」写的宿主编译全绿、
+ *     事件被整条丢掉、而门只回 boolean 说不出为什么。这条是本卡的 bug 修复位。
+ *  ⑤ `LocalSessionEvent.type` / `.chrome.kind` / `.permissionMode` 三个位闭集化(REF-CC-065)。
+ *  ⑥ `uploadAttachment` 入参、`getTranscript`/`searchSessions` 返回形、三个 store 状态形全部提成
+ *     具名 interface(REF-CC-072/073/074),SPEC 里 13 个内联匿名 validator 收成具名 `check*`。
+ *  三端消费坐标见本批 commit message 的「候提货单」节。
+ *
  * ── 沿革(以下正文自 sema-desktop/src/shared/localSessions.ts 逐字迁入)──────────────────────
  * LocalSessions — the desktop host's session service contract, FORM-ported from the CC desktop
  * app's `claude.web / LocalSessions` eipc interface (212 methods there; FIRST BATCH here = the four
@@ -55,6 +73,28 @@
  * @sema-agent/client-core), the contract shape does not.
  */
 import type { ReasoningEffort } from "./effortWire.js";
+import type { LaneProof } from "./seam.js";
+import type { QuestionAnswer } from "./liveQuestionStore.js";
+/** 一次门校验的失败说明。 */
+export interface SeatValidationFailure {
+    /** 人可读的失败原因,恒在场且非空(宿主日志里那一行的正文)。 */
+    reason: string;
+    /** 出错的那个键名(嵌套位用点号,如 `chrome.laneProof`)。
+     *  缺席 = 这次失败**不归属某一个字段**(整体不是对象 / 是跨字段的联合判据)⇒ 宿主日志只打
+     *  `service.method` + `reason`,**绝不**回落成 `"unknown"` 或空串当字段名 —— 编出来的字段名会把
+     *  排查引到一个根本没出问题的位上(§B10 同族:缺席要如实渲缺席,不是造一个值)。 */
+    field?: string;
+}
+/**
+ * 门的返回形:成功恰是 `true`(**只有一种写法**,消费端 `=== true` 判定即可),失败带原因。
+ *
+ * 🔴 为什么不是 `boolean`:这一族门是 fail-closed 的(见 `EipcMethodSpec.check` 的头注),false 时
+ * 整条事件/结果都不发。而 boolean 里没有任何位能说出是哪个字段哪条规则不过 —— 渲染端的现象是
+ * 「这个面偶尔什么都不来」,宿主端的现象是零日志,两端都无从下手(REF-CC-064 就是这么被埋住的)。
+ * 🔴 为什么消费端必须写 `=== true` 而不是 `if (!check(v))`:失败是**对象**(真值)。老写法会把
+ * 不合格读成合格 —— 这正是本批把位名从 `validate` 改成 `check` 的原因:让老写法编译期就红。
+ */
+export type SeatValidation = true | SeatValidationFailure;
 export type EipcMethodKind = "invoke" | "event";
 export interface EipcMethodSpec {
     kind: EipcMethodKind;
@@ -62,13 +102,15 @@ export interface EipcMethodSpec {
      *  schema gate — `Result from method "<m>" in interface "<S>" failed to pass validation`).
      *  event: validates the PAYLOAD before `webContents.send` (CC's dispatcher-side validator, the
      *  `fQe` position for `LocalSessions.onEvent`). Absent = any result/payload passes (CC has
-     *  `void`-returning methods with trivially-true validators). */
-    validate?: (value: unknown) => boolean;
+     *  `void`-returning methods with trivially-true validators).
+     *  🔴 位名 `check`(REF-CC-069,原 `validate`):返回 `true | SeatValidationFailure`,消费端必须
+     *  写 `if (verdict !== true)` 并把 `reason`/`field` 打进宿主日志 —— 一条被门吃掉的事件从此可诊断。 */
+    check?: (value: unknown) => SeatValidation;
 }
 export interface EipcStoreSpec {
     /** Validates the STATE payload both on read replies and on update pushes (fail-closed like the
-     *  method gates). Absent = any state passes. */
-    validate?: (state: unknown) => boolean;
+     *  method gates). Absent = any state passes. 位名与返回形同 `EipcMethodSpec.check`。 */
+    check?: (state: unknown) => SeatValidation;
 }
 export interface EipcServiceSpec {
     ns: string;
@@ -83,10 +125,17 @@ export interface LocalSessionRecord {
     sessionId: string;
     /** Engine (service)-minted session id, known after the first reply; absent before it. */
     engineSessionId?: string;
+    /** 这条会话钉住的模型 id。缺席 = 宿主没为它钉模型 ⇒ 每轮走部署默认(`SeatModelCatalog.defaultId`);
+     *  消费端渲那个默认名,**不要**渲空串或「未知模型」(部署默认是一个真实存在的答案)。 */
     model?: string;
+    /** 会话标题。缺席 = 还没有标题(首轮之前 / 摘要未回)⇒ 消费端渲「新会话」占位,不要渲空行。 */
     title?: string;
     isRunning: boolean;
+    /** ISO-8601 串(host clock)。与 `ToolPermissionRequest.createdAtMs` **不同域**:那一位是 epoch 毫秒数
+     *  (REF-CC-067 给它加了单位后缀,免得渲染端写出跨两种行复用的 `formatCreatedAt`)。 */
     createdAt: string;
+    /** 最近一次活动时刻(ISO-8601)。缺席 = 自建起没有任何活动 ⇒ 列表按 `createdAt` 排序,
+     *  **不要**把缺席当成 0 时刻(那会把新会话排到列表最底)。 */
     lastActivityAt?: string;
     /** Host-side deferred queue (CC `deferredSends` seat, in submit order — drives the queued-message
      *  bar). Present (possibly empty) whenever the host projects the record during a running turn. */
@@ -95,6 +144,13 @@ export interface LocalSessionRecord {
         text: string;
     }>;
 }
+/** design/80 D-1 的 TOCTOU 绑定**对**(REF-CC-070:此前是两个互不相干的 optional,半个 pair 照样过门)。
+ *  一位承载整对 ⇒「只有 callId 没有 inputHash」在类型层不可表达,门里也不用再补联合判据。 */
+export interface ToctouBinding {
+    callId: string;
+    inputHash: string;
+}
+export declare const TOCTOU_BINDING_KEYS: readonly ["callId", "inputHash"];
 /** HITL request row (CC's `request` position is schema-gated by `S1`; ours is this shape, projected
  *  from the sema wire's PendingCheckpoint — see session-host). */
 export interface ToolPermissionRequest {
@@ -114,47 +170,117 @@ export interface ToolPermissionRequest {
     requestId: string;
     sessionId: string;
     /** For the two ask families this is the CC tool vocabulary name the renderer branches on:
-     *  `AskUserQuestion` (question domain) / `McpElicitation` (elicit domain). */
+     *  `AskUserQuestion` (question domain) / `McpElicitation` (elicit domain).
+     *  缺席或 `null` = wire 没给工具名(旧 server / 通用审批行)⇒ 消费端走**通用**审批卡,
+     *  绝不猜工具名(猜错就是把 Bash 的确认框渲成别的工具的)。 */
     toolName?: string | null;
     /** The ENGINE's tool-call id (`call_…`) — the SAME id the assistant message's `tool_use` block
      *  carries, so a renderer can key the approval onto the tool card that actually raised it.
      *  Present on tool-approval rows from server ≥1.307; `null` when the wire did not offer one
      *  (old server, or the ask families, which have no tool call of their own). NEVER synthesized. */
     toolCallId?: string | null;
-    /** UNTRUSTED, service-redacted tool args / question payload (render-only, never re-fed). */
+    /** UNTRUSTED, service-redacted tool args / question payload (render-only, never re-fed).
+     *  🔴 缺席语义(REF-CC-066):门**刻意不校验**这一位(见 SEAT_VALIDATOR_KEY_COVERAGE 的豁免登记),
+     *  所以消费端拿到的可能是 undefined、也可能是任意形状。`question:` 域的整张卡押在 `input.questions`
+     *  上 ⇒ 缺席/畸形时渲染端必须显式渲「问题内容不可用」并把决断按钮留给 deny 侧,
+     *  **绝不**渲一张空卡(空卡看起来像「没有问题要问」,而真相是「问题丢了」)。 */
     input?: unknown;
-    /** UNTRUSTED, service-redacted engine ask text (live face only) — display only. */
+    /** UNTRUSTED, service-redacted engine ask text (live face only) — display only.
+     *  缺席 = 这一族(durable 行)本来就没有引擎问句 ⇒ 渲染端用工具名 + 参数摘要成句,不要留空。 */
     message?: string;
     /** design/80 D-1 TOCTOU binding pair (durable face only) — echo VERBATIM into the decision.
      *  🔴 出站**只读**位:回程的 verbatim 回显由宿主自己的登记表做(session-host 的
      *  `row.boundCallId/boundInputHash`),`ToolPermissionDecision` 因此没有对应席位 —— 渲染端
-     *  拿到它只为展示,绝不需要(也不该)自己回传。 */
-    boundCallId?: string;
-    boundInputHash?: string;
-    createdAt?: number;
+     *  拿到它只为展示,绝不需要(也不该)自己回传。
+     *  缺席 = 这一行不是 durable 域(live/question/elicit 三域没有绑定对)⇒ 消费端不渲绑定摘要。 */
+    toctouBinding?: ToctouBinding;
+    /** 行的诞生时刻,**epoch 毫秒**(单位入名,A4;时钟来源 = 宿主本地 `Date.now()`,不是引擎时钟 ⇒
+     *  与转录里的引擎时间戳不可直接相减)。缺席 = wire 那一行没带时间(旧 server 的 durable 行)⇒
+     *  消费端渲「刚刚」或不渲时间,**绝不**回落成 0(那会渲成 1970)。 */
+    createdAtMs?: number;
 }
+/**
+ * 座位事件名的**闭集**(REF-CC-065):这是三端唯一的事件名真源。
+ *
+ * 方向判据(本文件 `PERMISSION_MODE_INTENTS` 头注立的那条):词由**我们自己的宿主**铸出、发往渲染端,
+ * 因此闭集 —— 拼错一个字母在编译期红,而不是变成一条谁也不认识、被 switch 默默丢掉的事件。
+ * 与 `outcome`(wire 铸词,开集)的区别正是「谁铸的词」,不是「字段像不像枚举」。
+ * 词表 = sema-desktop `session-host` 的 emit 面实测八词。
+ */
+declare const SEAT_EVENT_TYPE_TUPLE: readonly ["start", "close", "session_updated", "message", "stream_event", "chrome_event", "error", "tool_permission_resolved"];
+export type SeatEventType = (typeof SEAT_EVENT_TYPE_TUPLE)[number];
+export declare const SEAT_EVENT_TYPES: readonly SeatEventType[];
+/** Chrome arms wired to the renderer position (batch 4); other arms stay host-side on the ring. */
+declare const CHROME_EVENT_KIND_TUPLE: readonly ["panel_task", "notification_terminal", "prompt_suggestions", "subagent_lifecycle"];
+export type ChromeEventKind = (typeof CHROME_EVENT_KIND_TUPLE)[number];
+/**
+ * 🔴 BREAKING(REF-CC-065,2026-08-02):公开面类型从 `readonly string[]` **收窄**成
+ * `readonly ChromeEventKind[]`。与 `PERMISSION_MODE_INTENTS` / `SEAT_REASONING_EFFORTS` 那两条
+ * **不同**:那两个本来就已经是闭集类型,加元组只是补「类型→常量」那半边、公开面一个字没变;
+ * 这一个的公开面**真的变了**,所以它是本批第四处破坏性契约变更,不是「同上理由」的搭车项。
+ *
+ * 谁受影响(实测消费坐标,提货单同条):`sema-desktop/src/main/session-host.ts:1752`
+ * `CHROME_EVENT_KINDS.includes(event.kind)` —— 那里的 `event: ChromeEvent` 是 seam.ts 的 17 词
+ * 判别式联合,收窄后 `includes()` 的入参类型只认这 4 个词 ⇒ TS2345,提货当天编译红。
+ * 迁移形:`(CHROME_EVENT_KINDS as readonly string[]).includes(event.kind)`,或先按 `ChromeEventKind`
+ * 做一次显式收窄再进这一支。sema-web-client / sema-cli 实测零命中。
+ */
+export declare const CHROME_EVENT_KINDS: readonly ChromeEventKind[];
+/** chrome 信封的**必填**键(REF-CC-064:`laneProof` 此前类型可选、门必填,两边说的不是一句话)。 */
+export interface SeatChromeEnvelopeBase {
+    kind: ChromeEventKind;
+    /** 车道证明([1617] 家族一等公民)。**必填**:出站门本来就要求它在场,类型说可选 = 一个合规的
+     *  生产者编译全绿、事件被整条静默丢弃。缺席在这条 lane 上不是「降级」,是「这帧不该发出来」。 */
+    laneProof: LaneProof;
+}
+/** 臂自身的载荷键随 `kind` 变(client-core `ChromeEvent` 的判别式联合),故留 index 位;
+ *  必填两位由 `SeatChromeEnvelopeBase` 承载,键集钉也钉在它上面。 */
+export interface SeatChromeEnvelope extends SeatChromeEnvelopeBase {
+    [k: string]: unknown;
+}
+export declare const SEAT_CHROME_ENVELOPE_KEYS: readonly ["kind", "laneProof"];
 export interface LocalSessionEvent {
-    type: string;
+    /** 事件名(闭集 `SEAT_EVENT_TYPES`)—— 消费端的判别位,switch 可穷举。 */
+    type: SeatEventType;
     sessionId: string;
     /** 🔴 transcript-plane passthrough (SDKMessage body) — deliberately UNVALIDATED (fQe posture). */
     message?: unknown;
     /** 🔴 transcript-plane passthrough batch — array-checked only, elements unvalidated (fQe posture). */
     messages?: unknown[];
+    /** 人可读的失败说明(仅 `error` 事件)。缺席 = 这条事件不是失败事件 ⇒ 渲染端不要因为「没有 error」
+     *  就把一次真失败渲成成功;判失败看的是 `type === "error"`,不是这一位在不在。 */
     error?: string;
+    /** 失败的**类别**(宿主自铸:`turn_failed` / `plan_review_failed` …)。缺席 = 宿主没有给这次失败分类
+     *  ⇒ 渲染端只渲 `error` 文本,不要猜类别、也不要按文案分类(§B8)。 */
     errorCategory?: string;
+    /** 引擎/传输层状态码(有则透传)。缺席 = 这次失败没有码可报(本地异常)⇒ 不渲码位,**绝不**渲 0。 */
     code?: number;
     /** CC `fQe` 的 form 位。🔴 **本宿主从不发这个位**(session-host 零处写 `request:`;HITL 行走
      *  独立的 `onToolPermissionRequest` 通道)—— 位保留是为了与 CC 的 fQe 逐位同形,消费端不该
      *  为它写分支(见文件头 D4)。 */
     request?: ToolPermissionRequest;
+    /** 自由文本载荷(CC fQe 的 `data` 位,本宿主目前不发)。缺席 = 没有附带文本,消费端不渲这一行。 */
     data?: string;
+    /** 引用来源列表(CC fQe 的 `sources` 位,本宿主目前不发)。缺席 = 没有来源可标 ⇒ 不渲来源脚注;
+     *  空数组与缺席同义(都表示「没有来源」),渲染端不必区分。 */
     sources?: string[];
-    permissionMode?: string;
+    /** 本轮生效的权限模式回显(闭集,与入站 `SendMessageRequest.permissionMode` 同一套词)。
+     *  缺席 = 宿主没有回显模式(今日常态:session-host 零处发这一位)⇒ 渲染端继续显示 composer 自己的
+     *  模式徽标,**不要**因为缺席就把徽标降回 `default`(那是把「没说」渲成「说了 default」)。
+     *  🔴 闭集的前提是「词由我们自己铸」:哪天改成回显**引擎的** effective mode(wire 铸的词),
+     *  必须同批把这一位降级成开集,理由与 `outcome` 逐字相同。 */
+    permissionMode?: PermissionModeIntent;
+    /** 会话行快照(`start`/`close`/`session_updated` 带)。缺席 = 这条事件不携带会话态 ⇒ 消费端
+     *  沿用 store 里的现有行,**不要**当成「会话没了」。 */
     session?: LocalSessionRecord;
+    /** 触发这条事件的用户消息 uuid(`message` 事件带)。缺席 = 这条事件不属于某条用户消息(引擎侧自发)
+     *  ⇒ 渲染端把它挂在当前 turn 上,不要另开一条用户气泡。 */
     userMessageUuid?: string;
+    /** CC form:本条 `message` 之前宿主已清过屏(`/clear` 语义)。缺席 ≡ false(没清过)——
+     *  这一位只在为真时出现,消费端按「缺席 = 不清屏」处理即可。 */
     hasPreClearSession?: boolean;
     /** On `tool_permission_resolved`: which request settled (so a native notification for it can be
-     *  dismissed — CC `closePermissionNotification(requestId)`). */
+     *  dismissed — CC `closePermissionNotification(requestId)`). 缺席 = 这条不是审批收面事件。 */
     requestId?: string;
     /**
      * On `tool_permission_resolved`: HOW it settled ([1947] 红③). Without this the renderer only ever
@@ -175,12 +301,9 @@ export interface LocalSessionEvent {
     outcome?: string;
     /** On `chrome_event`: one client-core ChromeEvent arm (the NEUTRAL typed chrome vocabulary —
      *  [1832] axiom 2's non-transcript half). Only the renderer-wired arm kinds cross the wire
-     *  (see CHROME_EVENT_KINDS); the outbound gate checks kind membership + the laneProof discipline. */
-    chrome?: {
-        kind: string;
-        laneProof?: unknown;
-        [k: string]: unknown;
-    };
+     *  (see CHROME_EVENT_KINDS); the outbound gate checks kind membership + the laneProof discipline.
+     *  缺席 = 这条不是 chrome 事件(按 `type` 判别,不要按这一位在不在判别)。 */
+    chrome?: SeatChromeEnvelope;
 }
 /**
  * The resolution words the host currently puts on `tool_permission_resolved.outcome` ([1947] 红③).
@@ -226,10 +349,10 @@ export declare const HITL_RESOLUTION_OUTCOMES: readonly string[];
  *     ignores `remember` here rather than pretend, so the renderer should hide that control for
  *     `elicit:` rows (a button that changes nothing is the false-affordance family again).
  */
-/** Chrome arms wired to the renderer position (batch 4); other arms stay host-side on the ring. */
-export declare const CHROME_EVENT_KINDS: readonly string[];
 export interface StartSessionOptions {
+    /** 起会话时钉的模型 id。缺席 = 用部署默认(`SeatModelCatalog.defaultId`),这是一个真实答案而不是错误。 */
     model?: string;
+    /** 起会话时给的标题。缺席 = 宿主不铸标题(记录里的 `title` 随后也缺席,渲染端渲「新会话」)。 */
     title?: string;
     /** Working directory for the session's hand tools (TaskRequest.cwd). Default = a per-session dir
      *  under the host's workspace base. A UI that picks a project directory passes it here — CC desktop
@@ -269,13 +392,15 @@ export interface SeatTurnSettings {
     /** CC's `settings.ultracode` PRESET boolean (max thinking × workflow orchestration, service ≥1.48.0
      *  reads `body.settings.ultracode` and expands it). NOT a seventh effort tier — the dial separately
      *  coerces the reasoning axis to `xhigh`, and collapsing the two loses the orchestration half
-     *  (`ultracodeWireCaps` in this package records that semantics verbatim). */
+     *  (`ultracodeWireCaps` in this package records that semantics verbatim).
+     *  缺席 = 没开这个预设(≡ false);渲染端按缺席渲「关」,不必区分缺席与显式 false。 */
     ultracode?: boolean;
 }
 export declare const SEAT_TURN_SETTINGS_KEYS: readonly ["ultracode"];
 export interface SendMessageRequest {
     sessionId: string;
     text: string;
+    /** 本轮临时换模型。缺席 = 用会话钉住的模型(`LocalSessionRecord.model`),再缺席才是部署默认。 */
     model?: string;
     /** Client-supplied echo key for the user message (CC form: userMessageUuid); minted if absent. */
     userMessageUuid?: string;
@@ -303,6 +428,20 @@ export interface SendMessageRequest {
      *  today's only member is the `ultracode` preset boolean. */
     settings?: SeatTurnSettings;
 }
+/** `uploadAttachment` 入参(REF-CC-074:此前是导出方法签名里的 3 成员内联匿名形,直接命中 B4)。 */
+export interface AttachmentUploadRequest {
+    /** 本地文件名。服务端会自己 sanitize 出 `AttachmentUploadReceipt.name`,渲染端显示的是**回执**那个。 */
+    name: string;
+    /** MIME 类型。缺席 = 让服务端自己嗅探(它有权拒 415);消费端不要自己编一个 `application/octet-stream`
+     *  —— 编出来的类型会让服务端把本可识别的文件当二进制。 */
+    mimeType?: string;
+    bytes: Uint8Array;
+}
+export declare const ATTACHMENT_UPLOAD_REQUEST_KEYS: readonly ["name", "mimeType", "bytes"];
+/** 只带会话 id 的入参(interrupt/stop 共用;REF-CC-074 同族,1 成员形也统一成具名)。 */
+export interface SessionScopedRequest {
+    sessionId: string;
+}
 /** `uploadAttachment` receipt — the SDK's `AttachmentInfo` verbatim (server POST /v1/attachments 201).
  *  `name` is the SERVER's sanitized basename, not the local filename: it is the name the engine
  *  materializes, so the renderer must display THAT one. */
@@ -317,15 +456,21 @@ export interface AttachmentUploadReceipt {
  *  strips baseUrl/apiKey/headers). `contextWindow`/`maxOutputTokens` are soft-degrade extras. */
 export interface SeatModelInfo {
     id: string;
+    /** 展示名。缺席 = 部署没给展示名 ⇒ 渲染端显示 `id` 本身(不要显示空串)。 */
     name?: string;
+    /** 供应商名。缺席 = 部署没标供应商 ⇒ 不渲供应商标签,**不要**回落成 "unknown"。 */
     provider?: string;
+    /** 上下文窗口 token 数(statusline 的 Context 环分母)。缺席 = 引擎没报这个量 ⇒ 环渲不确定态,
+     *  绝不按某个猜测值算百分比([honest-absence-not-fabricated-zero])。 */
     contextWindow?: number;
+    /** 单次回复上限 token 数。缺席 = 引擎没报 ⇒ 不渲这一行。 */
     maxOutputTokens?: number;
 }
 /** `listModels` envelope. `defaultId` = the deployment's resolved default model id (display only —
  *  the per-turn choice always rides `sendMessage({model})`). */
 export interface SeatModelCatalog {
     models: SeatModelInfo[];
+    /** 缺席 = 部署没有解析出默认模型 ⇒ 渲染端不要给「默认」打勾,也不要自己挑第一行冒充默认。 */
     defaultId?: string;
 }
 export interface SendMessageAck {
@@ -351,13 +496,17 @@ export interface ToolPermissionDecision {
     /** AskUserQuestion answer (approve only) — `{answers:[{header, selected: string[], note?}]}`,
      *  keyed by the question's HEADER, `selected` echoing the EXACT option labels the user saw (core
      *  fences `selected ⊆ options`). Malformed shapes are refused at the door, never coerced: a
-     *  silently emptied answer is the user's choice being thrown away without anyone noticing. */
-    answer?: unknown;
+     *  silently emptied answer is the user's choice being thrown away without anyone noticing.
+     *  REF-CC-038(2026-08-02):typed as `QuestionAnswer`(hitlBridge's `AskAnswer` at the entry
+     *  level) — this was `unknown` before, the 4th of 4 divergent copies of the same shape.
+     *  缺席 = 这不是 question 域的决断(或是 deny)⇒ 宿主发 wire 自己的 NO_HUMAN 形(REF-CC-066)。 */
+    answer?: QuestionAnswer;
     /** Approve-with-edit rewritten args (design/37 last-wins). On the `elicit:` domain this position
      *  carries the submitted FORM CONTENT — a flat record of `string|number|boolean|string[]`
-     *  (the only shape the wire accepts; anything else is refused, not filtered). */
+     *  (the only shape the wire accepts; anything else is refused, not filtered).
+     *  缺席 = 原样批准(不改参数);`elicit:` 域缺席 = 没有表单内容,宿主绝不代填。 */
     updatedInput?: unknown;
-    /** "Don't ask again this session" (approve only). */
+    /** "Don't ask again this session" (approve only). 缺席 = 只批这一次。 */
     remember?: "session";
 }
 /** Renderer-side `$store$` client (CC form: read + subscribe; `update` channel is the push). */
@@ -368,33 +517,59 @@ export interface EipcStoreClient<T> {
 }
 export interface SettingsState {
     defaultModel: string | null;
+    /** 引擎版本串。缺席 = 宿主还没连上引擎(启动窗口)⇒ 渲染端渲「连接中」,不要渲空版本号。 */
     engineVersion?: string;
+    /** 引擎数据根目录。缺席 = 同上(还不知道)⇒ 不渲路径行,不要渲 "~" 之类的猜测值。 */
     dataRoot?: string;
 }
 export interface SessionSearchResult {
     sessionId: string;
+    /** 命中会话的标题。缺席 = 该会话没有标题 ⇒ 结果行渲「新会话」+ 片段,不要渲空标题行。 */
     title?: string;
     matches: Array<{
         snippet: string;
     }>;
 }
+export declare const SESSION_SEARCH_RESULT_KEYS: readonly ["sessionId", "title", "matches"];
+/** `searchSessions` 返回形(REF-CC-072:此前是 SPEC 里的内联匿名 validator 之一;
+ *  它从不校 `title` 那一半归 REF-CC-073,见 `SESSION_SEARCH_RESULT_KEYS`)。 */
+export interface SessionSearchEnvelope {
+    results: SessionSearchResult[];
+}
+/** `getTranscript` 返回形(REF-CC-073:此前内联匿名、无 interface、无键集、无钉)。
+ *  `messages` = transcript 面直通批(fQe 姿态:只校数组形,元素是 CC SDKMessage 体,刻意不校)。 */
+export interface GetTranscriptResult {
+    sessionId: string;
+    messages: unknown[];
+}
+export declare const GET_TRANSCRIPT_RESULT_KEYS: readonly ["sessionId", "messages"];
+/** interrupt 回执(CC form:true = 真打断了一轮在跑的 turn,false = 当时没有在跑的 turn)。 */
+export interface InterruptAck {
+    interrupted: boolean;
+}
+/** stop 回执(false = 会话本来就不在跑,不是错误)。 */
+export interface StopAck {
+    stopped: boolean;
+}
+/** 通用「收到了」回执(respondToToolPermission / setFocusedSession)。 */
+export interface OkAck {
+    ok: boolean;
+}
+/** `sessionsState` store 的状态形。 */
+export interface SessionsState {
+    sessions: LocalSessionRecord[];
+}
+/** `focusedSessionState` store 的状态形(`null` = 没有会话被聚焦,是一个真实状态不是缺席)。 */
+export interface FocusedSessionState {
+    sessionId: string | null;
+}
 /** Renderer-facing surface exposed by the mainView preload as `sema.web.LocalSessions`. */
 export interface LocalSessionsApi {
     start(opts?: StartSessionOptions): Promise<LocalSessionRecord>;
     sendMessage(req: SendMessageRequest): Promise<SendMessageAck>;
-    interrupt(req: {
-        sessionId: string;
-    }): Promise<{
-        interrupted: boolean;
-    }>;
-    stop(req: {
-        sessionId: string;
-    }): Promise<{
-        stopped: boolean;
-    }>;
-    respondToToolPermission(req: ToolPermissionDecision): Promise<{
-        ok: boolean;
-    }>;
+    interrupt(req: SessionScopedRequest): Promise<InterruptAck>;
+    stop(req: SessionScopedRequest): Promise<StopAck>;
+    respondToToolPermission(req: ToolPermissionDecision): Promise<OkAck>;
     /** Queue family (CC LocalSessionManager semantics; booleans, false = too-late/no-op form). */
     cancelQueuedMessage(sessionId: string, userMessageUuid: string): Promise<boolean>;
     /** CC signature: (sessionId, uuid, TARGET uuid) — position the message relative to the target
@@ -402,58 +577,27 @@ export interface LocalSessionsApi {
     reorderQueuedMessage(sessionId: string, userMessageUuid: string, targetUserMessageUuid: string): Promise<boolean>;
     promoteQueuedMessage(sessionId: string, userMessageUuid: string): Promise<boolean>;
     /** CC census verbs (batch 4). setFocusedSession(null) clears focus. */
-    setFocusedSession(sessionId: string | null): Promise<{
-        ok: boolean;
-    }>;
+    setFocusedSession(sessionId: string | null): Promise<OkAck>;
     setModel(sessionId: string, model: string): Promise<boolean>;
-    getTranscript(sessionId: string): Promise<{
-        sessionId: string;
-        messages: unknown[];
-    }>;
-    searchSessions(query: string): Promise<{
-        results: SessionSearchResult[];
-    }>;
+    getTranscript(sessionId: string): Promise<GetTranscriptResult>;
+    searchSessions(query: string): Promise<SessionSearchEnvelope>;
     /** Attachment BYTE channel (红批注 web#1 的另一半). Upload first, then reference the receipt id
      *  from `sendMessage({attachmentIds})`. Rejects (413/415/501 → thrown typed error) surface to the
      *  renderer as-is: a shelf row that says "ready" for a file the engine never received is the
      *  same lie as a mode badge that never crossed the wire. */
-    uploadAttachment(req: {
-        name: string;
-        mimeType?: string;
-        bytes: Uint8Array;
-    }): Promise<AttachmentUploadReceipt>;
+    uploadAttachment(req: AttachmentUploadRequest): Promise<AttachmentUploadReceipt>;
     /** Read-only model catalog (engine `GET /v1/models`). Empty `models` = the deployment offers no
      *  catalog; the renderer must degrade honestly rather than fall back to a fixture list. */
     listModels(): Promise<SeatModelCatalog>;
     onEvent(cb: (ev: LocalSessionEvent) => void): () => void;
     onToolPermissionRequest(cb: (req: ToolPermissionRequest) => void): () => void;
     /** `$store$` reactive states (read + subscribe; writes go through the verbs above). */
-    sessionsStateStore: EipcStoreClient<{
-        sessions: LocalSessionRecord[];
-    }>;
-    focusedSessionStateStore: EipcStoreClient<{
-        sessionId: string | null;
-    }>;
+    sessionsStateStore: EipcStoreClient<SessionsState>;
+    focusedSessionStateStore: EipcStoreClient<FocusedSessionState>;
     settingsStateStore: EipcStoreClient<SettingsState>;
 }
 export declare function isLocalSessionRecord(s: unknown): s is LocalSessionRecord;
 export declare function isToolPermissionRequest(r: unknown): r is ToolPermissionRequest;
-/**
- * onEvent payload validator — line-for-line FORM port of CC's `fQe`
- * (`.vite/build/index.chunk-CnWKsyE_.js:369773`). Field-by-field mapping:
- *  - `type`/`sessionId`: required strings (same);
- *  - `message`: CC's minified source reads `typeof e.message<"u"` inside a comma expression whose
- *    value is discarded — i.e. NO validation, a deliberate transcript-plane passthrough. Same here.
- *  - `messages`: array-checked, elements `every(t=>!0)` (constant true) — array shape only. Same here.
- *  - `error`/`errorCategory`: optional strings (same); `code`: optional number (same);
- *  - `request`: CC gates with `S1` (ToolPermissionRequest schema) → our isToolPermissionRequest;
- *  - `session`: CC gates with `aM` (SessionRecord schema) → our isLocalSessionRecord;
- *  - `data`: optional string / `sources`: optional string[] / `permissionMode`: optional string /
- *    `userMessageUuid`: optional string / `hasPreClearSession`: optional boolean (same);
- *  - CC fields we do not emit in this batch (`tccFolderKind`/`initializationStatus`/`fsFile`/
- *    `localMcpServers`/`refusalFallbackPrompt`) are not carried — their positions return when the
- *    corresponding service families are ported.
- */
 export declare function isLocalSessionEvent(v: unknown): v is LocalSessionEvent;
 export declare function isAttachmentUploadReceipt(v: unknown): v is AttachmentUploadReceipt;
 export declare function isSeatModelCatalog(v: unknown): v is SeatModelCatalog;
@@ -466,8 +610,150 @@ export declare const SEAT_STORE_PROPS: readonly ["sessionsStateStore", "focusedS
 /** 事件式(main→renderer push)的 verb —— SPEC 里 `kind: "event"` 的那一撮,门里逐元素对账。 */
 export declare const SEAT_EVENT_METHOD_NAMES: readonly ["onEvent", "onToolPermissionRequest"];
 export declare const LOCAL_SESSION_EVENT_KEYS: readonly ["type", "sessionId", "message", "messages", "error", "errorCategory", "code", "request", "data", "sources", "permissionMode", "session", "userMessageUuid", "hasPreClearSession", "requestId", "outcome", "chrome"];
-export declare const TOOL_PERMISSION_REQUEST_KEYS: readonly ["requestId", "sessionId", "toolName", "toolCallId", "input", "message", "boundCallId", "boundInputHash", "createdAt"];
+export declare const TOOL_PERMISSION_REQUEST_KEYS: readonly ["requestId", "sessionId", "toolName", "toolCallId", "input", "message", "toctouBinding", "createdAtMs"];
 export declare const LOCAL_SESSION_RECORD_KEYS: readonly ["sessionId", "engineSessionId", "model", "title", "isRunning", "createdAt", "lastActivityAt", "queuedMessages"];
 export declare const SEND_MESSAGE_REQUEST_KEYS: readonly ["sessionId", "text", "model", "userMessageUuid", "permissionMode", "attachmentIds", "reasoningEffort", "retainBackgroundProcesses", "settings"];
 export declare const TOOL_PERMISSION_DECISION_KEYS: readonly ["sessionId", "requestId", "decision", "answer", "updatedInput", "remember"];
 export declare const START_SESSION_OPTION_KEYS: readonly ["model", "title", "cwd", "excludeTools"];
+/**
+ * 校验器覆盖表(REF-CC-068)—— 每个校验器**逐键**声明:哪些位真被校验、哪些位**刻意**不校验。
+ *
+ * 为什么需要它:`防再漂钉` 封的是「interface ↔ 名字常量 ↔ SPEC」两跳,**校验器这条链此前没人钉**。
+ * 给一个 interface 加一个必填位,门全绿,而新位从此不过校验(fail-closed 面出现缺口)。
+ * 正确做法不是「全键必查」—— 本文件有真正**刻意不查**的位(transcript 面直通),所以豁免必须显式登记
+ * 并带理由。门里对每个位投毒:说校验的必拒、说豁免的必过 ⇒ 这张表不可能变成一段过期的说明文字。
+ *
+ * 🔴 覆盖范围(wave2 回炉批 2026-08-02 补齐,首版只登了 6 个而发包说明写的是「每个校验器」——
+ * 那 8 个没登的恰好就是 REF-CC-072 本批新提名的那批 `check*`,实测「加一个必填位、全门照绿」在它们
+ * 身上仍然全开,即这张表自称堵死的失效形当时并没有被堵死):
+ *   · **SPEC 面 15 个具名 `check`,14 个对象形在本表登记**,余下 1 个(裸布尔回执)逐形豁免;
+ *   · 另加 4 个**嵌套**形(SeatModelInfo / SessionSearchResult / ToctouBinding /
+ *     SeatChromeEnvelopeBase)—— 它们不是 SPEC 面的直接 check,但父校验器的覆盖表只登记得到
+ *     `models` / `results` / `toctouBinding` / `chrome` 这一个顶层键,给**子形**加必填位同样全绿;
+ *   · 合计 **18 条**。两个不适用的形逐形写在 `SEAT_VALIDATOR_COVERAGE_EXEMPT` 里。
+ * 完备性不靠这段话:门里逐条比对 `LOCAL_SESSIONS_SPEC` 每个 method/store 的 `check` **函数引用**
+ * 必须落在「本表 ∪ 豁免表」里 —— 再加一条 verb 而不登记,门当场红。
+ *
+ * `check` 位存的是**函数引用本身**(不是名字):名字查表要靠一张 guards 映射,而那张映射漏一行
+ * 就是又一个没人看见的缺口;引用相等是机械的。`guard` 位只在该形另有公开面 `is*` 谓词时登记,
+ * 门里额外校「谓词与 check 判决一致」。
+ */
+export declare const SEAT_VALIDATOR_KEY_COVERAGE: {
+    readonly LocalSessionRecord: {
+        readonly guard: "isLocalSessionRecord";
+        readonly check: (s: unknown) => SeatValidation;
+        readonly validated: readonly ["sessionId", "engineSessionId", "model", "title", "isRunning", "createdAt", "lastActivityAt", "queuedMessages"];
+        readonly unchecked: readonly [];
+    };
+    readonly ToolPermissionRequest: {
+        readonly guard: "isToolPermissionRequest";
+        readonly check: (r: unknown) => SeatValidation;
+        readonly validated: readonly ["requestId", "sessionId", "toolName", "toolCallId", "message", "toctouBinding", "createdAtMs"];
+        readonly unchecked: readonly [{
+            readonly key: "input";
+            readonly why: "UNTRUSTED service-redacted 工具参数 / 问题载荷:形状由工具自己定(CC request-args 姿态),渲染端只读不回喂;缺席/畸形的渲染义务写在字段注释里。";
+        }];
+    };
+    readonly LocalSessionEvent: {
+        readonly guard: "isLocalSessionEvent";
+        readonly check: (v: unknown) => SeatValidation;
+        readonly validated: readonly ["type", "sessionId", "messages", "error", "errorCategory", "code", "request", "data", "sources", "permissionMode", "session", "userMessageUuid", "hasPreClearSession", "requestId", "outcome", "chrome"];
+        readonly unchecked: readonly [{
+            readonly key: "message";
+            readonly why: "transcript 面直通位(CC fQe 逐字姿态:SDKMessage 体不做 schema 校验)—— 校它 = 引擎加一种消息体的那天整条转录被门吃掉。";
+        }];
+    };
+    readonly AttachmentUploadReceipt: {
+        readonly guard: "isAttachmentUploadReceipt";
+        readonly check: (v: unknown) => SeatValidation;
+        readonly validated: readonly ["id", "name", "mime", "sha256", "sizeBytes"];
+        readonly unchecked: readonly [];
+    };
+    readonly SeatModelCatalog: {
+        readonly guard: "isSeatModelCatalog";
+        readonly check: (v: unknown) => SeatValidation;
+        readonly validated: readonly ["models", "defaultId"];
+        readonly unchecked: readonly [];
+    };
+    readonly SendMessageAck: {
+        readonly guard: "isSendMessageAck";
+        readonly check: (v: unknown) => SeatValidation;
+        readonly validated: readonly ["sessionId", "userMessageUuid", "queued"];
+        readonly unchecked: readonly [];
+    };
+    readonly InterruptAck: {
+        readonly check: (v: unknown) => SeatValidation;
+        readonly validated: readonly ["interrupted"];
+        readonly unchecked: readonly [];
+    };
+    readonly StopAck: {
+        readonly check: (v: unknown) => SeatValidation;
+        readonly validated: readonly ["stopped"];
+        readonly unchecked: readonly [];
+    };
+    readonly OkAck: {
+        readonly check: (v: unknown) => SeatValidation;
+        readonly validated: readonly ["ok"];
+        readonly unchecked: readonly [];
+    };
+    readonly GetTranscriptResult: {
+        readonly check: (v: unknown) => SeatValidation;
+        readonly validated: readonly ["sessionId", "messages"];
+        readonly unchecked: readonly [];
+    };
+    readonly SessionSearchEnvelope: {
+        readonly check: (v: unknown) => SeatValidation;
+        readonly validated: readonly ["results"];
+        readonly unchecked: readonly [];
+    };
+    readonly SessionsState: {
+        readonly check: (v: unknown) => SeatValidation;
+        readonly validated: readonly ["sessions"];
+        readonly unchecked: readonly [];
+    };
+    readonly FocusedSessionState: {
+        readonly check: (v: unknown) => SeatValidation;
+        readonly validated: readonly ["sessionId"];
+        readonly unchecked: readonly [];
+    };
+    readonly SettingsState: {
+        readonly check: (v: unknown) => SeatValidation;
+        readonly validated: readonly ["defaultModel", "engineVersion", "dataRoot"];
+        readonly unchecked: readonly [];
+    };
+    readonly SeatModelInfo: {
+        readonly check: (v: unknown) => SeatValidation;
+        readonly validated: readonly ["id", "name", "provider", "contextWindow", "maxOutputTokens"];
+        readonly unchecked: readonly [];
+    };
+    readonly SessionSearchResult: {
+        readonly check: (v: unknown) => SeatValidation;
+        readonly validated: readonly ["sessionId", "title", "matches"];
+        readonly unchecked: readonly [];
+    };
+    readonly ToctouBinding: {
+        readonly check: (v: unknown) => SeatValidation;
+        readonly validated: readonly ["callId", "inputHash"];
+        readonly unchecked: readonly [];
+    };
+    readonly SeatChromeEnvelopeBase: {
+        readonly check: (v: unknown) => SeatValidation;
+        readonly validated: readonly ["kind", "laneProof"];
+        readonly unchecked: readonly [];
+    };
+};
+/**
+ * 逐形豁免(REF-CC-068 的另一半):**不适用**覆盖表的具名校验器 —— 每条写清为什么,以及它的判别力
+ * 由谁承担。这张表存在的唯一理由是让「本表 ∪ 覆盖表 ⊇ SPEC 面全部 check」这条完备性钉能机械成立:
+ * 没有它,「某个 check 没登记」和「某个 check 不该登记」在门里长得一模一样。
+ */
+export declare const SEAT_VALIDATOR_COVERAGE_EXEMPT: readonly [{
+    readonly label: "BooleanAck";
+    readonly check: (v: unknown) => SeatValidation;
+    readonly why: "载荷是**裸布尔**(queue 三件 + setModel 的 CC 形回执,false = too-late/no-op),没有键面 ⇒ `keyof` 覆盖表在它身上无从谈起。判别力由 J 段承担:认 true/false、拒非布尔(对象 / 字符串 'true' / null / undefined 四形逐一投毒)。";
+}, {
+    readonly label: "LaneProof";
+    readonly check: (v: unknown) => SeatValidation;
+    readonly why: "判别式联合:必填键面随 `lane` 臂而变(subagent 要 parentToolCallId、workflow 要 via+key),而覆盖表的方法是「一个最小合法体 + 逐键投毒」—— 那套方法在它身上没有判别力(main 臂对另外两臂的伴随位本来就不该拒,投毒过了不代表漏校)。判别力由 `LANE_PROOF_LANE_TUPLE` ⇄ seam.ts 车道联合的双向 `Covers` + F 段逐臂投毒(空对象 / 非对象 / 未登记车道词)承担。";
+}];
+export {};