@sema-agent/sdk 12.0.1 → 13.1.0

package/dist/types.d.ts

@@ -61,18 +61,30 @@ import type { AskOrigin, ClassifierUnavailable, DenialLimitFallback, PersistedRu
 /** 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;
-/** The scenarios a stock `@sema-agent/server` ships today — the builtin table in its
- *  `src/capabilities/scenarios.ts`, **five** names. `code` is the factory default ([891]); `default` is the
- *  domain-neutral assistant face; `scan` is the neutral read-only repo lane; `code-review` / `team` are the
- *  multi-lens and round-table lanes.
- *  🔴 Two RETIRED names are deliberately NOT here, and neither left a transition alias:
+/** Builtin scenarios of a stock `@sema-agent/server` that this SDK offers as known names — **four**, all in the table its
+ *  `buildScenarios()` returns (`src/capabilities/scenarios.ts`). `code` is the factory default ([891]); `default` is the
+ *  domain-neutral assistant face; `scan` is the neutral read-only repo lane; `code-review` is the multi-lens review lane.
+ *  ⚠️ The server's table has ONE more name today, `discuss` (the multi-agent discussion round-table), and it is still
+ *  accepted — it is deliberately NOT listed here: it sits inside core #1056's (7.35.0) retirement sweep (server S-630 ②), and
+ *  listing it now only to delete it at 7.35.0 would be two hard breaking changes on one type surface. Its fate is decided
+ *  by that wave, and this list changes once, then. (`Scenario` is open, so `scenario: "discuss"` compiles today.)
+ *  🔴 CHECKED AGAINST THE SERVER, not hand-kept (K-20): `test/scenario-capabilities.test.ts` ① reads the builtin table out of
+ *  the PUBLISHED `@sema-agent/server` bytes (devDep dist; `SEMA_SERVER_SRC=` reads an unpublished checkout) and requires it
+ *  to equal this list plus the one closed, dated hold-out (`SCENARIO_SERVER_ONLY_PENDING` in `test/_keyset-divergence.ts`) —
+ *  a server rename or retirement turns that cell red on the next pin bump.
+ *  🔴 Three RETIRED names are deliberately NOT here, and none left a transition alias:
  *   - `oa` — server 5.0.0 deleted it whole ([2354]; its `OA_*` env names are now boot-refusing tombstones).
  *   - `autonomous` — retired by [2400] CAPS-OPS-11 (clay 2026-08-03, 不留任何过渡). It used to be `code` with
  *     finalVerification pinned on; final verification is now a pure caller-side knob, so the migration shape is
- *     `scenario:"code"` + `body.finalVerification:true`. Sending `scenario:"autonomous"` to a ≥5.1.0 server is a
- *     LOUD typed 400 `scenario_unknown` (the response carries the deployment's live vocabulary), not a silent
- *     fold to `default`. */
-export type KnownScenario = "code" | "default" | "code-review" | "scan" | "team";
+ *     `scenario:"code"` + `body.finalVerification:true`.
+ *   - `team` — renamed `discuss` (server #273 / C-R14), and the old name's alias was withdrawn (#342), so a server
+ *     answers it 400 today. Removed here in K-20. (The discuss scenario's body key `team`, which picks the roster
+ *     template, kept its historical name — that is a request key, not this union.)
+ *  Sending a retired name to a ≥5.1.0 server is a LOUD typed 400 `scenario_unknown` (the response carries the
+ *  deployment's live vocabulary), not a silent fold to `default`. */
+export declare const KNOWN_SCENARIOS: readonly ["code", "default", "code-review", "scan"];
+/** One of {@link KNOWN_SCENARIOS} — derived from the value (one list, no second hand-written union). */
+export type KnownScenario = (typeof KNOWN_SCENARIOS)[number];
 /** Service scenario = the primary routing axis (one image serves many).
  *
  *  🔴 Deliberately OPEN (`KnownScenario | (string & {})`, 4.0.1): a deployment can register its own
@@ -509,8 +521,10 @@ export interface TaskRequest {
      *  taskId 为键记 user-message 锚,值 = 该 user message 的 entryId;`http/durable-run-leg.ts` / `routes/tasks.ts` 的锚捕获)。
      *  server `src/boot/resolve-spec.ts:686-697`:`resumeAnchorStore.resolve(sessionId, <手柄>, principal)` → entry id;未知手柄 ⇒ 404
      *  `rewind_files_to.unknown_event`;没带会话 ⇒ 422 `rewind_files_to.no_session`;worker 无锚店 / 无 `getLeafId` ⇒ 501。
-     *  ⚠️ 501 **不是**能力位的全部谓词(车OV 对抗复审 [low] 订正):{@link Capabilities.rewindFilesTo} 还合取文件历史店(捕获脸);
-     *  那一半缺席时 server **不** 501,而是 core 在 run 里响亮拒 `rewind.store_unconfigured`(`prepare-file-history.js`)⇒ 先探能力位。
+     *  ⚠️ 501 **不是**能力位的全部谓词(车OV 对抗复审 [low] 订正):{@link Capabilities.rewindFilesTo} 还合取文件历史店;
+     *  那一半缺席时 server **不** 501,而是 core 在 prepare 里拒 `rewind.store_unconfigured`(`prepare-file-history.js`)⇒ 先探能力位。
+     *  (server ≥7.104.0 / S-724:同步 `POST /v1/tasks` 零工作时那一拒答 **409** 错误体 —— 见 {@link ConflictError};异步 / 活流腿仍是终态
+     *  run 行同码。`FILE_HISTORY_CAPTURE=false` 自 7.104.0 **不再**触发它:旋钮只关捕获、店照接。)与 {@link fileHistory} 同体 ⇒ 400。
      *  **只在 `resumeAt` 缺席时受理**(两模式互斥:带了 `resumeAt` 就是那条分叉腿自己的
      *  `restoreFiles` 说了算)。7.72.0 起是**提交那一拍的一次性动作**(续跑腿整族剥掉它);部分恢复看 {@link acceptPartialRestore}。 */
     rewindFilesTo?: string;
@@ -527,6 +541,20 @@ export interface TaskRequest {
      *  恢复**与** `rewindFilesTo` 的 code-only 恢复 —— code-only 调用方漏带本位同样吃 loud 终局。
      *  恢复动作 per-file 幂等:重跑同一恢复即收敛。 */
     acceptPartialRestore?: boolean;
+    /**
+     * 🔴 **请求级文件历史关断词**(K-24;server ≥7.104.0 / S-724;core 7.31.0 #1048 `TaskSpec.fileHistory`,型与 core 同一只 ——
+     * 测试里对 `@sema-agent/core` 的 `TaskSpec["fileHistory"]` 做 Equal 锚)。**唯一词 `"disabled"`**:这一条 run 不做首次触碰备份、
+     * 不铸回合边界(子代继承);缺席 = 按部署设置(**没有** `"enabled"` 的拼法)。
+     *  · 拼写门(fresh / resume 两腿同判):别的任何值 ⇒ 400 `request.field_invalid`,句子以
+     *    `fileHistory must be the string 'disabled' when present` 开头;
+     *  · 🔴 与任一还原键**同体**(`restoreFiles` / {@link rewindFilesTo} / 退役 {@link rewindFiles})⇒ **受理时** 400
+     *    `request.field_conflict`(`fileHistory: 'disabled' cannot ride with a file restore …`),会话与文件都不动 —— 要还原就别带它;
+     *  · 这条腿的实际结论读 `wiring_manifest.fileHistory`(`"on"` / `"disabled"`);要不要给用户渲「本会话不捕获」开关读
+     *    {@link Capabilities.fileHistoryCapture}(`"on-optional"` 才渲;「本会话不捕获」= 这条会话的每个提交都带本键)。
+     * ⚠️ 老 server:7.78.1–7.103.x 对本键答 400 `request.body_shape`(顶层体键闭集,未知键拒不丢);更老的 server 静默忽略它(那时没有
+     * 顶层键闭集)—— 两形都按 `fileHistoryCapture === "on-optional"` 判再发。
+     */
+    fileHistory?: "disabled";
     /** 🔴 PERMISSION MODE INTENT — the TOB-fleet server's five accepted wire values: `default` | `plan` |
      *  `acceptEdits` | `bypassPermissions` | `auto` (post-[816]/[820]/[822] current state; server task-settings.ts
      *  `SettingsPermissionMode` is the same closed set, same-batch aligned 2026-08-05 via server.ts submit-gate
@@ -935,6 +963,68 @@ export interface PausedCause {
      *  🔴 把「paused ⇒ 空闲且免费」当成不变量的调度器必须看得见这一位。 */
     restoreMode?: "snapshot" | "park_only";
 }
+/**
+ * `GET /v1/capabilities` 的 `sealedKey` 段(K-24;server ≥7.104.0 / S-737)—— **恰三键**,与 server `src/sealed-key.ts` 的同名接口
+ * 逐键同(测试源码腿 / dist 腿对拍)。私钥、私钥文件路径、本机持有的旧钥匙 id、`createdAt` **都不上 wire**。
+ */
+export interface SealedKeyCapability {
+    /** v1 唯一值 `"libsodium-sealedbox-x25519"`,与 settings-schema 的 `SEALED_BOX_ALG` **同型**(测试里 Equal 锚属主,不手抄)。
+     *  别的 alg 在引擎的配置应用期是逐模型的响亮拒,不是猜。 */
+    alg: "libsodium-sealedbox-x25519";
+    /** 写进 `sealedApiKey.publicKeyId` 的 id(server 缺省铸法 `exec-<sha256(公钥原字节) 前 12 位 hex>`,`sealed-key.ts:169-172`;按不透明串用,
+     *  别解析);引擎按它**精确**选私钥开箱(不逐把试)。 */
+    publicKeyId: string;
+    /** 32 字节 X25519 公钥的**标准** base64(44 字符)。公钥,可记日志。 */
+    publicKey: string;
+}
+/**
+ * S-173(K-24;server ≥7.104.0)—— 一条**停在门上**的 run 在 `GET /v1/runs/:id` 行上的 `status` 词,也是同步提交撞 park 时
+ * 200 体上的回执词。server 从 `RUN_STATUS_CLASS` 判 `"parked"` 的那几个词**派生**(`plugins/store-contracts.ts` 的
+ * `ParkedRunStatus`),本型与它逐词同(测试源码腿 / dist 腿对拍)。{@link RunStatus} 的子集。
+ */
+export type ParkedRunStatus = "suspended" | "needs_review";
+/**
+ * S-173(K-24;server ≥7.104.0)—— 同步提交撞 park 时叠在结果上的 **poll 回执三键**(修前 park 体的全部内容,值逐字不变;
+ * 与 server `http/sync-submit-body.ts` 的同名接口逐键同,测试对拍)。
+ */
+export interface SyncParkReceipt {
+    /** 同步腿提交时铸的 durable run id —— `GET /v1/runs/:taskId` 的 poll 键(= 结果自带的 `taskId`)。 */
+    taskId: string;
+    /** 提交的会话(= 结果自带的 `sessionId`)。 */
+    sessionId: string;
+    /** 对外词 = `GET /v1/runs/:id` 行上的 `status`(park 两词之一)。 */
+    status: ParkedRunStatus;
+}
+/**
+ * `POST /v1/tasks`(非流式)的 200 体(K-24;server 名 `SyncSubmitBody`,`http/sync-submit-body.ts` `buildSyncSubmitBody` 单点铸)。
+ *
+ * **一条规则**(server ≥7.104.0,契约 §5.0c):200 体**恒** = 结果本身(出口封口 + 脱敏后的引擎结果,即 {@link TaskResult});run
+ * **停在门上**(`terminal.kind === "paused"`)时再叠 {@link SyncParkReceipt} 三键 —— 所以在 7.104.0 上 `status` **只在 park 时在场**,
+ * 终局体不带它(不给终局造 `terminal.kind` 之外的第二真源)。同一次 park 在 `/v1/tasks/stream` 的 `done.result` 上除身份键外逐字相同;
+ * 恢复凭据从不在体上(`paused.token` 摘掉)。
+ *
+ * ⚠️ **三代同一个型,如实登记**(本包支持地板 3.0.0;与 {@link TaskResult.terminal} 同款:型面按现行代声明,老代的差别写在这里,
+ * 不把 `terminal` 做成可选去逼每个现行读点处理一个不存在的缺席分支):
+ *  · **server ≤7.63**:平面形(见 {@link LegacyPlaneTaskResult})—— `status` 是**终局词**(`completed` / `failed` / `blocked` /
+ *    park 两词),**没有** `terminal`,码在退役平面键(`r["errorCode"]` 经开集索引读);
+ *  · **7.64–7.103**:终局体 = 现行 `terminal` 形、无 `status`;**park 体只有**回执三键 `{ taskId, sessionId, status }`(`terminal` /
+ *    `stats` 运行期缺席);
+ *  · **≥7.104**:上面那条规则。
+ * ⇒ 所以 `status` 的词 = park 两词 ∪ ≤7.63 平面词(`LegacyPlaneTaskResult["status"]`,本包对那一代的既有声明,不另抄一份)。
+ * **三代通用读法**(测试 `server-7104-wire` ④bis 三代样例都编译得过、读得对):
+ * ```ts
+ * const r = await client.tasks.submit(req);
+ * if (r.status === "suspended" || r.status === "needs_review") pollLater(r.taskId);   // 三代都在 park 时带回执词
+ * else if (r.terminal === undefined) legacyFlat(r.status, r["errorCode"]);           // ≤7.63 平面形
+ * else render(r.terminal);                                                            // ≥7.64
+ * ```
+ * 🔴 判代用 `r.terminal === undefined`,**别用** `"terminal" in r`:`terminal` 在型上是必填,`in` 的假支会被收成 `never`
+ * (那一支里 `r.status` 编译不过)。
+ */
+export interface SyncSubmitResult extends TaskResult {
+    /** 回执词 / ≤7.63 平面词(见上):≥7.104 只在 park 时在场(park 两词);7.64–7.103 只在 park 体上;≤7.63 恒在(平面终局词)。 */
+    status?: ParkedRunStatus | LegacyPlaneTaskResult["status"];
+}
 /** Synchronous task result (`POST /v1/tasks`). */
 export interface TaskResult {
     taskId: string;
@@ -1806,9 +1896,16 @@ export interface RunRecord {
     status: RunStatus;
     /** 🔴 **读盘面 ⇒ 两代字节**(server ≥7.64.0 起;见 {@link LegacyPlaneTaskResult}):server 对存储 blob 是
      *  逐字透传、**不补** `terminal`,所以一台跨 7.64.0 升级过的部署上,升级前的历史行读出来仍是旧的平面形。
-     *  判别位 `"terminal" in run.result`。 */
+     *  判别位 `"terminal" in run.result`。
+     *
+     *  🔴 K-24 / S-173(server ≥7.104.0,契约 §5.0c):本位**恒描述当前态** —— park 中(`status` ∈ {@link ParkedRunStatus})带停下来
+     *  那一份结果(`terminal.kind === "paused"`,凭据摘掉;= 同步提交 200 体去掉 `status`);`running`(含被认领续跑之后)**缺席**;终局
+     *  整块替换;审批过期 / 失联收割后**缺席**。7.103.x 及以前 park 行没有本位。⚠️ **先读 `status` 再读 `result`**:`result` 在场不等于
+     *  已结束。混版窗例外:≤7.103.x 的副本不清这一列,滚动升级窗内旧副本的审批过期收割可能留下 `failed` 行上的 paused 结果(MIGRATION 7.104.0)。 */
     result?: TaskResult | LegacyPlaneTaskResult;
-    /** 本**行的列**,7.64.0 未变(照旧说五词);只是数据源改成从 `result.terminal` 投影一次(旧行则直接读平面键)。 */
+    /** 本**行的列**,7.64.0 未变(照旧说五词);只是数据源改成从 `result.terminal` 投影一次(旧行则直接读平面键)。
+     *  ⚠️ K-24 / S-173(server ≥7.104.0):`needs_review` park 行上本位 = core 的规范码 **`review.pending`**(此前缺席)——
+     *  **禁**把「本位在场」读成失败,先读 `status`。`suspended` park 行缺席。 */
     errorCode?: string;
     error?: string;
     /** Work-view correlation. Present when the run has a jobId (omitted when null). LIVE server-side
@@ -1844,7 +1941,8 @@ export interface RunRecord {
     suggestions?: string[];
     /** 🔴 facade 审计(2026-07-24,SDK 全量核查批次②-1):design/80 b item 3 的合成成本面
      *  (src/http/routes/runs.ts,`composeSupervisorCost()`)—— 顶层字段(`result` 的**兄弟**,不在 result.stats
-     *  里面),只在 infra 定价已配置(`hasInfraPricing`)且 run 已终态并带 `result.stats` 时出现;否则整个
+     *  里面),只在 infra 定价已配置(`hasInfraPricing`)且行上带 `result.stats` 时出现(7.103.x 及以前 = 终态行;K-24 / S-173 起
+     *  server ≥7.104.0 的 **park 行**也带结果 ⇒ park 中同样出现,读数 = 停下来那一刻为止的成本);否则整个
      *  字段 OMIT(不是伪造空对象)。此前误放进 `TaskStats`(嵌套,永远读不到)且误标量成 number(真实是
      *  `{llm,infra,totalMicroUsd}` 富对象)——两处都改。 */
     supervisorCost?: SupervisorCostBreakdown;
@@ -1864,6 +1962,8 @@ export interface TaskSummary {
     owner?: string;
     startedAt: string;
     endedAt?: string;
+    /** `turns` / `tokens` / `costMicroUsd`:读自行上的结果。K-24 / S-173(server ≥7.104.0):park 中的行也带结果 ⇒ 三位在 park 中
+     *  是**停下来那一刻**的读数(下界;终局时整块替换)。7.103.x 及以前 park 行缺席。 */
     turns?: number;
     tokens?: number;
     costMicroUsd?: number;
@@ -3369,9 +3469,11 @@ export interface Capabilities {
      *  `Boolean(deps.fileHistoryStore && deps.resumeAnchorStore && deps.sessionStorage?.getLeafId)` —— 要还原(文件历史店)、
      *  也要解析目标手柄(锚店 + `getLeafId`):「说 yes ⟺ 纯代码回卷的提交解析得出、还原得了」)。
      *  🔴 sdk 11.4.0 订正([8437] U3):旧注点名的是 S-15(design/381)之前的**整树快照店**,那一席早已换成
-     *  **文件历史店** `fileHistoryStore`;且 server 7.97.0(S-589)起那一席是**捕获脸** = 后端 ∧ 部署旋钮 `FILE_HISTORY_CAPTURE`
-     *  (`src/file-history-capture.ts` 的装配单点)⇒ 关掉捕获的部署上本位与 `rewindFiles` / `restoreFiles` / `sessionSync` 同为 false,
-     *  {@link fileHistoryCapture} 同时报 `"off"`。 */
+     *  **文件历史店** `fileHistoryStore`。
+     *  🔴 K-24 改真(server ≥7.104.0 / S-724):7.97.0–7.103.x 上那一席是**捕获脸**(后端 ∧ 部署旋钮 `FILE_HISTORY_CAPTURE`),关掉捕获的
+     *  部署上本位与 `rewindFiles` / `restoreFiles` / `sessionSync` 同为 false;**7.104.0 起旋钮只关捕获**(店照接,已存历史照常
+     *  还原 / 同步)⇒ 本位与那三位只看「有没有文件历史店」(= 有没有存储后端),与旋钮无关 —— `fileHistoryCapture: "off"` 不再意味着
+     *  没有 rewind。rewind 入口看本位 / `rewindFiles`,**别**看 {@link fileHistoryCapture}。 */
     rewindFilesTo?: boolean;
     /** assistant-scheduler 面(`routes/capabilities.ts` 的能力对象 `schedulerEnabled && requirePrincipal!==true && remoteExec==="host"` 三与)。 */
     scheduler?: boolean;
@@ -3673,20 +3775,35 @@ export interface Capabilities {
      *  射程与 {@link taskWriteFaceOpen} 的托管门那一半同一只谓词(托管形 ⇒ 两位同 `false`);`AUTONOMY` 只动那一位、不动本位。
      *  ⚠️ 缺席 = 老 worker(≤7.94)⇒ 按 `true` 兜底(契约附录 B.1:那时它原样过境)。 */
     taskApproverPosture?: boolean;
-    /** **文件历史捕获关不关得掉**(server ≥7.97.0 / S-589;铸点 `routes/capabilities.ts:847` =
-     *  `fileHistoryCaptureOf(deps.fileHistoryStore)`,闭集属主 server `src/file-history-capture.ts` 的
-     *  `FILE_HISTORY_CAPTURE_WORD_SET`)。从**装配结果**派生(捕获脸 = 后端 ∧ 部署旋钮 `FILE_HISTORY_CAPTURE`),
-     *  **不是**旋钮字面回声 —— 无后端的部署同样是 `"off"`;与 `rewindFiles` / `restoreFiles` / {@link rewindFilesTo} /
-     *  `sessionSync` 同一判定。
-     *  · `"off"` —— 这台部署不捕获任何改动文件的首次快照,同时也没有 rewind / restore / 纯代码回卷 / session-sync
-     *    ⇒ 不渲「关闭捕获」开关,也不渲 rewind 入口;
-     *  · `"on-always"` —— 捕获中,且**无法按会话关闭**(core 的首次触碰捕获是进程级的)⇒ 只渲一句只读真话,
-     *    别渲一个关不掉的开关。
-     *  🔴 第三词 `"on-optional"`(本会话可以不捕获)server **刻意不声明**(要等 core 收一个单会话不捕获位)——
-     *  本型因此是两词闭集;将来加词是 server 的一次 additive,那时本型随之加员。消费端 switch 仍留 default 臂
-     *  (词表外 ⇒ 按未知处理、不渲开关)。⚠️ 关掉 ≠ 删掉:翻成 `"off"` 之后已捕获的历史不批量删除。
-     *  ⚠️ 缺席 = 老 worker(≤7.96)⇒ 按 `rewindFiles` 兜底:`true` 读作 `"on-always"`、`false` 读作 `"off"`(逐字等价)。 */
-    fileHistoryCapture?: "off" | "on-always";
+    /** **文件历史捕获开没开、能不能按 run 关掉**(server ≥7.97.0 / S-589 立位;**7.104.0 / S-724 换词**;铸点 int-7104
+     *  `routes/capabilities.ts:846` = `fileHistoryCaptureOf(deps.fileHistoryStore, deps.config.fileHistoryCapture)`,闭集属主 server
+     *  `src/file-history-capture.ts` 的 `FILE_HISTORY_CAPTURE_WORD_SET` —— 测试对它做源码腿 / dist 腿的词表对拍)。从**装配结果**派生
+     *  (店在 ∧ 部署旋钮 `FILE_HISTORY_CAPTURE` 没关),**不是**旋钮字面回声 —— 无后端的部署同样是 `"off"`。穷举读:
+     *  · `"off"` —— 这台部署**不捕获**任何改动文件的首次快照 ⇒ 不渲「关闭捕获」开关。🔴 7.104.0 起**不再连带 rewind**:
+     *    旋钮只关捕获,已存历史照常 `restoreFiles` / `rewindFilesTo` / session-sync —— rewind 入口看 `rewindFiles` / {@link rewindFilesTo},别看本位;
+     *  · `"on-optional"` —— 捕获中,且**可以按 run 关掉**:提交体带 {@link TaskRequest.fileHistory} `"disabled"` ⇒ 渲开关
+     *    (关 = 这条会话的每个提交都带它;续跑腿重放同一个体,照带);
+     *  · ⚰️ `"on-always"` —— **退役词**(server 7.104.0 起不再发出:请求词接线后「捕获中且关不掉」结构上不可达),7.97.0–7.103.x 的 worker
+     *    仍发它 = 捕获中且**无法按会话关闭** ⇒ 只渲一句只读真话「本部署恒捕获,无法按会话关闭」(契约附录 B.1 逐臂),别渲关不掉的开关。
+     *    本包支持地板(3.0.0)之内的 server 真会发它,所以它留在联合里(K-24 复审 r1 M2,偏离任务书的「硬删」,理由如实:删了 ⇒ 随包 spec
+     *    判一份合法的 7.103 能力面违约、消费端写不出契约要的那一臂);登记 `_keyset-divergence.ts` `CAPABILITY_RETIRED_WORDS`,
+     *    删除条件 = 支持地板抬过 7.104.0。
+     *  词表外的词按未知处理(不按前缀猜,不渲开关)。⚠️ 关掉 ≠ 删掉:部署翻成 `"off"` 不做任何批量删除。
+     *  ⚠️ 缺席 = 老 worker(≤7.96,没有这根旋钮)⇒ 按 `rewindFiles` 兜底:`true` 读作 `"on-always"`、`false` 读作 `"off"`(那时捕获 ⟺
+     *  历史店在场,逐字等价)。 */
+    fileHistoryCapture?: "off" | "on-optional" | "on-always";
+    /** **模型钥匙 sealed 形的公钥发现面**(K-24;server ≥7.104.0 / S-737;铸点 int-7104 `routes/capabilities.ts:969` 普通成员
+     *  `sealedKey: projectSealedKeyCapability(deps.sealedKeyPublic)`,段形属主 `src/sealed-key.ts` 的 `SealedKeyCapability`)——
+     *  本进程模型钥匙保管店里**最新**那把 X25519 公钥,恰三键(见 {@link SealedKeyCapability})。用法:对着 `publicKey` 做
+     *  `crypto_box_seal`(明文 = 模型 key 的 UTF-8 字节),密文转**标准 base64**,连同 `alg` / `publicKeyId` 写进 `ModelEntry.sealedApiKey`
+     *  (本地车道 = `config.d/models.json`;server USAGE §9.10)。与 `apiKeyEnv` 同设 ⇒ sealed 优先;开不了 ⇒ 这只模型每次调用都失败
+     *  (`sealed_decrypt_failed` / `stale_ciphertext` / `no_key_store`),**不**回落 `apiKeyEnv` 也不回落网关 key。
+     *  🔴 **present-iff**(能力面唯一的逐键例外,契约附录 B.1):缺席有两种含义、同一个动作 —— 老 server(< 7.104.0)/ 这台引擎今天
+     *  **没有保管店**(起服建店失败;同一体的 `version` 能分这两种)⇒ **不要封**,改用 `apiKeyEnv`,或修好保管目录后重启再取。
+     *  缺席是**键不在**,不是 `null` / `{}`(判 `caps.sealedKey !== undefined`)。
+     *  🔴 **每台宿主一份**:保管店在 `<数据根>/sealed-key/`;多副本不共享这个目录时各副本答的公钥不同,对着 A 副本公钥封的密文在
+     *  B 副本上是 `stale_ciphertext`(逐模型响亮失败)。出路 = 共享保管目录,或走中心形。 */
+    sealedKey?: SealedKeyCapability;
     /** **会话后台任务两口的在场位**(server ≥7.102.0 / S-745 / core 7.32.0 #1107;铸点 `routes/capabilities.ts:308` =
      *  `{ listFace: sessionBackgroundFacesAvailable(deps), exitFaces: sessionBackgroundFacesAvailable(deps) }`,与两口的 501
      *  **同一只谓词**:会话属主面 `sessionStorage.ownerOf` 在场 ⇒「说 yes 但 501」结构上不可能;缺它 ⇒ 两位显式 `false`、
@@ -4998,7 +5115,7 @@ export interface AssistantTaskStatus {
  * 🔴 **一条规则管所有「effective 半场 only」的键**(9.7.0 立,codex 对抗复审 [high] 验真后收成这一句,
  * 而不是给新加的三段各写一条特例):本型**今天唯一的消费点**是 `GET /v1/diagnostics/wiring` 的 `static`
  * 半场,而标了「只在 effective 半场铸」的键(`leg` / `ask.effective` / `configFingerprint` / `tools` /
- * `hooks` / `lsp` / `modelGate` / `autoMode` / `writeProtection` / `readDeny` / `autoConsolidation`)
+ * `hooks` / `lsp` / `modelGate` / `autoMode` / `writeProtection` / `readDeny` / `autoConsolidation` / `fileHistory`)
  * 在这条 wire 上**恒缺席** ⇒ **它们在本面上的缺席不携带任何信息**。
  * 每一段顶注里写的那些「缺席 = 未武装 / 缺席 = 第三态」的读法**只对 live 帧成立**(`AgentEvent` 的
  * `wiring_manifest` 臂),**不许**搬到这条端点的响应上来读 —— 在这里把缺席读成「未武装」,恰恰会把一台
@@ -5126,7 +5243,17 @@ export interface WiringManifest {
      *  外流记忆的部署渲成没在外流)。这台部署武装没武装,租户面读
      *  {@link SessionMemoryStatusResponse.autoConsolidationArmed}(恒在场的真布尔)。 */
     autoConsolidation?: WiringManifestAutoConsolidation;
+    /** K-24(server ≥7.104.0 / S-724;core 7.31.0 #1048 / #1050)—— 这条腿捕不捕文件历史,词形单源 {@link WiringManifestFileHistory}。
+     *  🔴 **effective 半场 only ⇒ 本面恒缺席**(见块头那一条规则):读法只对 live `wiring_manifest` 帧成立;部署形读
+     *  {@link Capabilities.fileHistoryCapture}。 */
+    fileHistory?: WiringManifestFileHistory;
 }
+/**
+ * `wiring_manifest.fileHistory` 的词(K-24;server ≥7.104.0 / S-724;core 7.31.0 `WiringManifest.fileHistory` = `"on" | "disabled"`,
+ * 测试对 `@sema-agent/core` 做可赋锚)—— live 帧与 {@link WiringManifest} 共用这一只(段形单源,同 {@link WiringManifestReadDeny} 先例)。
+ * 🔴 **开集**:server 不枚举这个词(在场却不是非空串 ⇒ 丢键),第三个词原样过境 ⇒ 按未知处理。
+ */
+export type WiringManifestFileHistory = "on" | "disabled" | (string & {});
 /** core `ToolRoster`(design/388 B-4)—— 一条腿的工具名册。**顶层四键逐键镜像**;`entries[]` 的行只镜像身份 /
  *  出身 / 轴 / 面几组消费端会读的键,其余按开集读(core 给行加键不该把消费端编译炸掉;属主是 core 的 typebox
  *  schema,server 侧零键表)。`digest` = 整只名册的指纹,**恰 16 位 hex**,任一轴/面/契约/别名变化都会移动它。 */