@sema-agent/client-core 0.59.2 → 0.60.0

package/dist/runTerminal.d.ts

@@ -0,0 +1,194 @@
+/**
+ * src/runTerminal.ts — 一次 run **怎么结束的**:两代 wire 字节 → 一个带标读数(0.60.0)。
+ *
+ * ── 上游形变(engine ≥7.64.0 / sdk 8.4.0;wire BREAKING)────────────────────────────────────
+ * 7.63.0 及以前,终局要从并列的**八个可选平面键**里拼:`status` / `errorCode` / `errorMessage` /
+ * `blockedReason` / `checkpointToken` / `checkpointId` / `checkpointGate` / `workspaceRestoreMode`。
+ * 哪些组合合法只活在引擎那条 if/else 阶梯里,读的人只能靠**缺席**推断。7.64.0 起它是**形状**:
+ * `TaskResult.terminal`(四臂 `completed | failed | blocked | paused`),八个平面键从型面整删。
+ *
+ * ── 本模块存在的理由:两代字节,一个读器 ─────────────────────────────────────────────────────
+ * 🔴 **这不是「留一条旧引擎兼容读」**(那条本批刻意不留:peer 地板抬到 `>=8.4.0`,7.63.0 及以前的
+ *    引擎不在本版支持窗内)。本模块的第二代臂认的是**同一台 ≥7.64.0 引擎**在两条路上真会送来的
+ *    扁平字节,两条都有出处:
+ *      ① **读盘面**(上游逐字点名):`GET /v1/runs/:id` 的 `result` 是存储 blob 的**逐字透传**
+ *         (server 不补 `terminal`),durable 账本回放出来的 `done` 行同理 —— 一台跨 7.64.0 升级过的
+ *         部署上,升级**之前**落盘的那些行读出来仍是平面形;
+ *      ② **拒绝信封**:SSE 提交腿的 409(`conflict.session_active_run`)是 **server 自己的**拒绝帧、
+ *         不是引擎结果,这次形变没动它 —— 它带扁平 `status:"failed"` + `errorCode`,不带 `terminal`;
+ *      ③ **同步提交直接撞上暂停**(engine 7.64.0 真机黑盒 + server 回帖确认):`POST /v1/tasks`
+ *         若当场停在一道审批门上,200 回体是 **server 自造的一只形** ——
+ *         `{ taskId, sessionId, status: "suspended" | "needs_review" }`,**既没有退役的八个平面键、
+ *         也没有 `terminal`**,它**不是** `TaskResult`(是独立于它的另一个体)。它既不是历史字节
+ *         也不是拒绝信封,是**活流腿上的第三个来源**,而且它说的是一句正面事实(「这条 run park 了」)。
+ *         🔴 因此这一形上**连门都没有**(`checkpointGate` / `terminal.paused.gate` 两处皆缺)——
+ *         「这是复核还是交互作答」只能从那个 `status` 词读,见 {@link RunTerminalPausedRead.flatStatus}。
+ *    ⇒ 判别位就是上游钉的那一个:**`"terminal" in result`**。在场 = 因由形,缺席 = 扁平形。
+ * 🔴 **「缺席」不许折成 `completed` / `failed`**(真机黑盒点名的那条边界):`terminal` 缺席时,
+ *    读器要么按扁平词给出**对应的那一臂**(`suspended` ⇒ paused,不是 completed 也不是 failed),
+ *    要么在连词都没有时返回 `null`(见 {@link readRunTerminal} 的 `null` 语义)。**非终态**词
+ *    (`running` / 未来的排队词)落 `unknown` 臂 —— 那是「这不是一个我认得的终局」,同样**不是**成功。
+ *    `GET /v1/runs/:id` 对**暂停中**的 run 读不到 `result`,那一格连载体都没有,本读器答 `null`。
+ * 🔴 **两代读数在出口上带标**({@link RunTerminalRead.plane}):不带标就等于对消费端说「这两种字节
+ *    没有区别」,而它们在**能不能出现新键**这件事上区别很大(平面形是停产的写者留下的历史字节,
+ *    永远不会长出新位)。带标也让门可以对「哪一条腿读到了哪一代」下断言。
+ *
+ * ── 判据纪律 ────────────────────────────────────────────────────────────────────────────────
+ * 🔴 **不认识的终态词绝不折成成功**(本仓 [884]A1 / [909]B1 两次实锤事故的常驻结论):四臂之外的
+ *    `terminal.kind`、平面形里四词之外的 `status`,一律落 {@link RunTerminalRead} 的 `unknown` 臂并
+ *    **逐字带回那个词**,由消费点渲成「非成功终态」。整个读器只有一条路返回 `null`:**连终态词都
+ *    没有**(mock 车道 / 不带 status 的旧合成帧)—— 那一格的既有语义(落成功臂)由消费点保留。
+ * 🔴 **`code` 结构上只属于失败**:因由形下 `completed` / `blocked` / `paused` 上**写不出**码。
+ *    `blocked` / `paused` / `unknown` 三臂仍声明了 `code?`,那一位**只可能**来自平面形盘上字节
+ *    (旧写者把 `errorCode` 与 `status` 平铺,`review.pending` 就骑在 park 行上)—— 丢掉它等于在
+ *    回放历史行时把盘上真有的事实抹掉。因由形上它恒缺席,判据用 `plane`。
+ * 🔴 **`token` 席位永不上 wire**:paused 因由与 `failed.nestedPause` 都不带恢复凭据(上游在两条
+ *    够得着的路径上摘它)。本读器同样一个字节都不碰它,也不给它留位。
+ * 🔴 **不复制上游的投影**:本模块**不**提供「因由 → 五词 `status`」的兼容投影。同一个事实在这条
+ *    wire 上有两个真源之后,消费端会分成「读因由的」和「读投影的」两派,而下一次形变时后者全部
+ *    无声地错(sdk 顶注逐字同规)。要旧词的消费点自己按 `kind` 分支。
+ */
+import type { CheckpointGate } from '@sema-agent/sdk';
+/**
+ * 这条读数出自哪一代字节。
+ *  · `cause` —— 现行的带标因由形(`result.terminal` 在场);
+ *  · `flat`  —— 扁平形。**两个来源同形不可分**,所以刻意共用一个词:①升级前落盘、由读盘面逐字
+ *    回放的历史行;②server 自己的 409 拒绝信封(它从来就是扁平的,这次形变没动它)。
+ *    🔴 拿 `stats` 在场性去分这两源是**假判据**:本包的抢救腿(从 run row 合成的 done 帧)本来就
+ *    可能不带 `stats`(见 `terminalToSdkResult` 的 ADAPTER-1/-2 收口注),那条判据会把它误判成拒绝
+ *    信封。两源的**投影处置完全相同**,所以不分反而是诚实的。
+ */
+export type RunTerminalPlane = 'cause' | 'flat';
+/** paused 因由的**结构视图**(`token` 席位不在这里,也不在 wire 上)。 */
+export interface RunTerminalPause {
+    /** **哪一道**暂停 —— 谁/什么必须来恢复它。开集读(词表属主是引擎)。 */
+    gate?: CheckpointGate;
+    /** 这次暂停的**非密**稳定身份;pre-identity 的老 checkpoint 上缺席。 */
+    checkpointId?: string;
+    /**
+     * 被暂停任务的远端工作区**怎么回来**:`snapshot`(VM 挂起成快照)/ `park_only`(环境自陈不可
+     * 挂起 —— 机器继续跑、继续花钱)。**缺席 = 进程内暂停**(没有远端工作区被捕获)。
+     * 🔴 型面**不收窄成那两个词**:词表属主是引擎,抄一份会把新词吞成缺席。
+     */
+    restoreMode?: string;
+}
+/**
+ * paused 臂的整只读数 —— {@link RunTerminalPause} 三座 + 判别位。
+ *
+ * 🔴 **抽名而不是写成交叉形**(`{…} & RunTerminalPause`):交叉形的左操作数是一个内联匿名形,
+ *    typeshape 门的 B4 棘轮按设计把它算进「导出签名里的内联匿名形」——而具名 interface 正是那条
+ *    棘轮点名的替代品。`extends` 同时保住了三座的**单一真源**(顶层 paused 臂与
+ *    `failed.nestedPause` 读的是同一个形,两处各写一份必漂)。
+ */
+export interface RunTerminalPausedRead extends RunTerminalPause {
+    kind: 'paused';
+    plane: RunTerminalPlane;
+    /** 见 {@link RunTerminalRead} 顶注:只可能来自扁平形盘上字节。 */
+    code?: string;
+    /**
+     * 扁平形上那个退役的 status 词(`suspended` / `needs_review`)—— **因由形上恒缺席**。
+     *
+     * 🔴 **它不是「留一条兼容读」,是这一形上唯一存在的信号**(server 回帖确认):同步提交腿命中
+     *    park 时,server 自造的 200 体 `{taskId, sessionId, status}` **连门都不带** ⇒
+     *    {@link runTerminalGateKind} 在那一形上恒 `undefined`,「这是复核还是交互作答」除了这个词
+     *    再没有第二个来源。把它丢掉 = 那一形的 plan-review 卡与终帧措辞**全部**落到「交互作答」那一句上。
+     * 🔴 仍然**不做因由 → 五词 status 的反向投影**:本位只在扁平形上原样带回读到的那一个词,
+     *    因由形上不铸(读器一个词都不猜)。
+     */
+    flatStatus?: string;
+}
+/**
+ * 一次 run 的终局读数。`kind` 是判别位。
+ *
+ * ⚠️ 与 sdk `TerminalCause` 的差别只有两处,都是**防御读**逼出来的:①多一条 `unknown` 臂
+ * (四臂之外的词不许落成功);②`blocked` / `paused` / `unknown` 上多一个 `code?`(平面形盘上字节
+ * 才可能有,见模块顶注)。其余逐位同义。
+ */
+export type RunTerminalRead = {
+    kind: 'completed';
+    plane: RunTerminalPlane;
+} | {
+    kind: 'failed';
+    plane: RunTerminalPlane;
+    /** 这次失败带的**机器码**(开集,点分命名空间;缺席 = 这次失败本来就没有码)。 */
+    code?: string;
+    /** 人类可读的失败文本;没有就缺席。 */
+    message?: string;
+    /**
+     * 这次失败**顶替的那次耐久暂停** —— 只在**嵌套硬边界**(verify / cascade)上出现:嵌套腿停在
+     * 一道耐久门上而编排器驱动不了 resume,于是在它的边界上如实报 failed,同时把那次 park 的因由
+     * 整只带在这里。引擎自己组装的失败上恒缺席;平面形上**结构性缺席**(旧写者没有这个位)。
+     */
+    nestedPause?: RunTerminalPause;
+} | {
+    kind: 'blocked';
+    plane: RunTerminalPlane;
+    /** agent 为什么完不成(治理判决不是失败)。缺席 = 引擎没给因由,**不是**「没被挡」。 */
+    reason?: string;
+    /** 见模块顶注:只可能来自平面形。 */
+    code?: string;
+} | RunTerminalPausedRead | {
+    /** 四臂之外的终态词、**或一座读不出的因由** —— 两者都**绝不折成成功**。 */
+    kind: 'unknown';
+    plane: RunTerminalPlane;
+    /**
+     * 那个本读器不认识的词(因由形取 `terminal.kind`,扁平形取 `status`),逐字。
+     * 🔴 **缺席 = 那一座在场但整个读不出**(`terminal` 是 `null` / 数组 / 标量,或它的 `kind`
+     *    不是非空串)。这一格与「四臂之外的一个词」是两件事,所以刻意用**这一位的缺席**分开:
+     *    前者消费点只能说「一座读不出的终局」,后者能把那个词逐字报出来。
+     *    ⚠️ 它**不是**「没有终局」——那一格由 {@link readRunTerminal} 返 `null` 表达。
+     */
+    word?: string;
+    code?: string;
+    message?: string;
+};
+/**
+ * `done.result` / run row 的 `result` → 终局读数。**绝不抛**;读不出终态词 ⇒ `null`。
+ *
+ * 🔴 `null` **只有一个意思**:这份载体上连终态词都没有(mock 车道 / 不带 status 的旧合成帧)。
+ *    它**不是**「成功」也**不是**「未知终态」—— 消费点对这一格的既有处置(落成功臂)由消费点自己
+ *    保留,本读器不替它下这个断言。
+ * 🔴 **「因由座在场但读不出」绝不返 `null`**(异源对抗复审 [medium] 采纳,真病):`terminal: null` /
+ *    `{}` / `[]` / `{kind: 7}` 这几形若返 `null`,消费点会把它当成「连终态词都没有」而落**成功臂**
+ *    —— 一条明确 park 着的 run 被投影成空成功,正是 [884]A1 / [909]B1 两次事故的形状。⇒ 这几形
+ *    一律落 `unknown` 臂(`word` 缺席 = 那个词本身读不出),消费点照旧渲「非成功终局」。
+ *    ⚠️ 混合载体(既有坏 `terminal` 又有平面 `status`)同样落这里:判别位是**因由座在场性**,
+ *    因由在场就不再回头读平面键(留一条回落 = 同一事实两个真源,而坏的那一份才是当代写者写的)。
+ * 🔴 判别位是 **`"terminal" in result`**(上游钉的那一个),不是 `status` 的在场性:拒绝信封与
+ *    平面盘上字节**都**带 `status`,拿它当第一步判别位方向是脆的(sdk 顶注逐字点名)。
+ */
+export declare function readRunTerminal(result: unknown): RunTerminalRead | null;
+/**
+ * 「这次暂停要的是**一次复核**」的门种 —— **呈现措辞**这条轴上的单一词表(不是路由表)。
+ *
+ * 🔴 与 `activeRunSelfHeal.PLAN_REVIEW_GATE_KINDS`(`plan_review` / `dry_run_review`)**刻意不同集**,
+ *    差别有出处:那张表答的是「**重开臂能不能驱动它**」(两个成员共用同一个 resume 入口
+ *    `/v1/assistant/tasks/{taskId}/plan_review`),而本表答的是「**跟用户怎么说**」。门种
+ *    `needs_review`(design/76 dry-run/shadow 的 POST-prediction 复核)没有那个 resume 入口,所以
+ *    它不在路由表里 —— 但它同样是**一次复核**而不是「一次交互作答」,措辞轴上必须在。
+ * 🔴 两张表的包含关系由常驻门钉死(本表 ⊇ 路由表):路由表加员而本表没跟 ⇒ 新门种的终帧会被说成
+ *    「在等一次交互作答」,那正是 [884]A1 那句文案要防的错话。
+ * 🔴 **开集读**:表外门种一律落「交互作答」那一句 —— 它是两句里更宽的那一句(指的出路对两族都有效)。
+ */
+export declare const REVIEW_PARK_GATE_KINDS: readonly string[];
+/**
+ * 这次暂停停在**哪一种门**上(开集读;缺席 = 门没报 kind)。
+ * 消费点要分「plan 复核 park」与「审批/提问 park」时读它,**不要**再去找退役的 `status` 五词。
+ */
+export declare function runTerminalGateKind(read: RunTerminalRead | null): string | undefined;
+/** 这次暂停扣着**哪个工具**(开集读;tool-less park 上缺席)。 */
+export declare function runTerminalGateToolName(read: RunTerminalRead | null): string | undefined;
+/**
+ * 这次终局的**机器码**(开集)。`failed` 臂是它的结构归属;`blocked` / `paused` / `unknown` 上
+ * 只可能来自扁平形盘上字节(见模块顶注)。`completed` 上恒 `undefined`。
+ */
+export declare function runTerminalCode(read: RunTerminalRead | null): string | undefined;
+/**
+ * 这次暂停在等**一次复核**(而不是一次交互作答)吗。**两个来源,缺一不可**:
+ *   · **因由形** —— 门种 ∈ {@link REVIEW_PARK_GATE_KINDS};
+ *   · **扁平形** —— {@link RunTerminalPausedRead.flatStatus} 是 `needs_review`。
+ *     🔴 这一条不是冗余:server 自造的**同步 park 200 体**上连门都没有(见 `flatStatus` 顶注),
+ *     只读门种会让那一形**全部**落到「交互作答」那一句上 —— plan-review 卡不弹、终帧措辞说错话。
+ * 非 paused 的读数、以及两个来源都答不出的 paused,一律 `false`(更宽的那一句兜底)。
+ */
+export declare function isReviewPark(read: RunTerminalRead | null): boolean;

package/dist/runTerminal.js

@@ -0,0 +1,189 @@
+/** 非空串窄化(空串按缺席归一 —— 一个空的因由渲不出任何有用的话)。 */
+function str(v) {
+    return typeof v === 'string' && v.length > 0 ? v : undefined;
+}
+/** wire 上的门对象 → 结构视图;不成形 ⇒ 缺席(绝不铸一个空门)。 */
+function gateOf(v) {
+    if (typeof v !== 'object' || v === null || Array.isArray(v))
+        return undefined;
+    return v;
+}
+/** paused 三座的共用窄读(顶层 paused 臂与 `failed.nestedPause` 同一把 —— 两处各写一份必漂)。 */
+function pauseOf(v) {
+    if (typeof v !== 'object' || v === null || Array.isArray(v))
+        return undefined;
+    const p = v;
+    const gate = gateOf(p.gate);
+    const checkpointId = str(p.checkpointId);
+    const restoreMode = str(p.restoreMode);
+    return {
+        ...(gate !== undefined ? { gate } : {}),
+        ...(checkpointId !== undefined ? { checkpointId } : {}),
+        ...(restoreMode !== undefined ? { restoreMode } : {}),
+    };
+}
+/**
+ * 扁平形里映射到 **paused 因由臂**的两个退役 status 词。
+ * 🔴 表外词一律走 `unknown` 臂 —— 含历史终态 `timeout`,也含**非终态**词 `running`
+ *    (那是「这不是一个我认得的终局」,**不是**成功;真机黑盒点名的那条边界)。
+ */
+const FLAT_PAUSED_STATUSES = ['suspended', 'needs_review'];
+/**
+ * `done.result` / run row 的 `result` → 终局读数。**绝不抛**;读不出终态词 ⇒ `null`。
+ *
+ * 🔴 `null` **只有一个意思**:这份载体上连终态词都没有(mock 车道 / 不带 status 的旧合成帧)。
+ *    它**不是**「成功」也**不是**「未知终态」—— 消费点对这一格的既有处置(落成功臂)由消费点自己
+ *    保留,本读器不替它下这个断言。
+ * 🔴 **「因由座在场但读不出」绝不返 `null`**(异源对抗复审 [medium] 采纳,真病):`terminal: null` /
+ *    `{}` / `[]` / `{kind: 7}` 这几形若返 `null`,消费点会把它当成「连终态词都没有」而落**成功臂**
+ *    —— 一条明确 park 着的 run 被投影成空成功,正是 [884]A1 / [909]B1 两次事故的形状。⇒ 这几形
+ *    一律落 `unknown` 臂(`word` 缺席 = 那个词本身读不出),消费点照旧渲「非成功终局」。
+ *    ⚠️ 混合载体(既有坏 `terminal` 又有平面 `status`)同样落这里:判别位是**因由座在场性**,
+ *    因由在场就不再回头读平面键(留一条回落 = 同一事实两个真源,而坏的那一份才是当代写者写的)。
+ * 🔴 判别位是 **`"terminal" in result`**(上游钉的那一个),不是 `status` 的在场性:拒绝信封与
+ *    平面盘上字节**都**带 `status`,拿它当第一步判别位方向是脆的(sdk 顶注逐字点名)。
+ */
+export function readRunTerminal(result) {
+    if (typeof result !== 'object' || result === null || Array.isArray(result))
+        return null;
+    const r = result;
+    if ('terminal' in r) {
+        const t = r.terminal;
+        // 🔴 因由座在场但整个读不出 ⇒ `unknown` 臂(**不是** `null`;见顶注:返 `null` 会让消费点把
+        //    一条明确 park 着的 run 落进成功臂)。`word` 缺席 = 连那个词都读不出来。
+        if (typeof t !== 'object' || t === null || Array.isArray(t))
+            return { kind: 'unknown', plane: 'cause' };
+        const c = t;
+        const kind = str(c.kind);
+        if (kind === undefined)
+            return { kind: 'unknown', plane: 'cause' };
+        switch (kind) {
+            case 'completed':
+                return { kind: 'completed', plane: 'cause' };
+            case 'failed': {
+                const code = str(c.code);
+                const message = str(c.message);
+                const nestedPause = c.nestedPause !== undefined ? pauseOf(c.nestedPause) : undefined;
+                return {
+                    kind: 'failed',
+                    plane: 'cause',
+                    ...(code !== undefined ? { code } : {}),
+                    ...(message !== undefined ? { message } : {}),
+                    ...(nestedPause !== undefined ? { nestedPause } : {}),
+                };
+            }
+            case 'blocked': {
+                const reason = str(c.reason);
+                return { kind: 'blocked', plane: 'cause', ...(reason !== undefined ? { reason } : {}) };
+            }
+            case 'paused':
+                return { kind: 'paused', plane: 'cause', ...(pauseOf(c) ?? {}) };
+            default:
+                return { kind: 'unknown', plane: 'cause', word: kind };
+        }
+    }
+    // ── 扁平形(读盘回放 / 409 拒绝信封;见模块顶注)────────────────────────────────────────────
+    const status = str(r.status);
+    if (status === undefined)
+        return null;
+    const code = str(r.errorCode);
+    const message = str(r.errorMessage);
+    if (status === 'completed')
+        return { kind: 'completed', plane: 'flat' };
+    if (status === 'failed') {
+        return {
+            kind: 'failed',
+            plane: 'flat',
+            ...(code !== undefined ? { code } : {}),
+            ...(message !== undefined ? { message } : {}),
+        };
+    }
+    if (status === 'blocked') {
+        const reason = str(r.blockedReason);
+        return {
+            kind: 'blocked',
+            plane: 'flat',
+            ...(reason !== undefined ? { reason } : {}),
+            ...(code !== undefined ? { code } : {}),
+        };
+    }
+    if (FLAT_PAUSED_STATUSES.includes(status)) {
+        const gate = gateOf(r.checkpointGate);
+        const checkpointId = str(r.checkpointId);
+        const restoreMode = str(r.workspaceRestoreMode);
+        return {
+            kind: 'paused',
+            plane: 'flat',
+            // 🔴 见 `flatStatus` 顶注:server 自造的同步 park 体上**连门都没有**,这个词是那一形上
+            //    「复核 / 交互作答」的唯一信号。
+            flatStatus: status,
+            ...(code !== undefined ? { code } : {}),
+            ...(gate !== undefined ? { gate } : {}),
+            ...(checkpointId !== undefined ? { checkpointId } : {}),
+            ...(restoreMode !== undefined ? { restoreMode } : {}),
+        };
+    }
+    return {
+        kind: 'unknown',
+        plane: 'flat',
+        word: status,
+        ...(code !== undefined ? { code } : {}),
+        ...(message !== undefined ? { message } : {}),
+    };
+}
+/**
+ * 「这次暂停要的是**一次复核**」的门种 —— **呈现措辞**这条轴上的单一词表(不是路由表)。
+ *
+ * 🔴 与 `activeRunSelfHeal.PLAN_REVIEW_GATE_KINDS`(`plan_review` / `dry_run_review`)**刻意不同集**,
+ *    差别有出处:那张表答的是「**重开臂能不能驱动它**」(两个成员共用同一个 resume 入口
+ *    `/v1/assistant/tasks/{taskId}/plan_review`),而本表答的是「**跟用户怎么说**」。门种
+ *    `needs_review`(design/76 dry-run/shadow 的 POST-prediction 复核)没有那个 resume 入口,所以
+ *    它不在路由表里 —— 但它同样是**一次复核**而不是「一次交互作答」,措辞轴上必须在。
+ * 🔴 两张表的包含关系由常驻门钉死(本表 ⊇ 路由表):路由表加员而本表没跟 ⇒ 新门种的终帧会被说成
+ *    「在等一次交互作答」,那正是 [884]A1 那句文案要防的错话。
+ * 🔴 **开集读**:表外门种一律落「交互作答」那一句 —— 它是两句里更宽的那一句(指的出路对两族都有效)。
+ */
+export const REVIEW_PARK_GATE_KINDS = Object.freeze([
+    'plan_review',
+    'dry_run_review',
+    'needs_review',
+]);
+/**
+ * 这次暂停停在**哪一种门**上(开集读;缺席 = 门没报 kind)。
+ * 消费点要分「plan 复核 park」与「审批/提问 park」时读它,**不要**再去找退役的 `status` 五词。
+ */
+export function runTerminalGateKind(read) {
+    return read !== null && read.kind === 'paused' ? str(read.gate?.kind) : undefined;
+}
+/** 这次暂停扣着**哪个工具**(开集读;tool-less park 上缺席)。 */
+export function runTerminalGateToolName(read) {
+    return read !== null && read.kind === 'paused' ? str(read.gate?.toolName) : undefined;
+}
+/**
+ * 这次终局的**机器码**(开集)。`failed` 臂是它的结构归属;`blocked` / `paused` / `unknown` 上
+ * 只可能来自扁平形盘上字节(见模块顶注)。`completed` 上恒 `undefined`。
+ */
+export function runTerminalCode(read) {
+    if (read === null || read.kind === 'completed')
+        return undefined;
+    return read.code;
+}
+/**
+ * 扁平形上「这是一次复核」的那个退役 status 词。**只有一个**,刻意不写成表:
+ * `suspended` 与它是 `FLAT_PAUSED_STATUSES` 的两个成员,而两者的分法就是这一条。
+ */
+const FLAT_REVIEW_STATUS = 'needs_review';
+/**
+ * 这次暂停在等**一次复核**(而不是一次交互作答)吗。**两个来源,缺一不可**:
+ *   · **因由形** —— 门种 ∈ {@link REVIEW_PARK_GATE_KINDS};
+ *   · **扁平形** —— {@link RunTerminalPausedRead.flatStatus} 是 `needs_review`。
+ *     🔴 这一条不是冗余:server 自造的**同步 park 200 体**上连门都没有(见 `flatStatus` 顶注),
+ *     只读门种会让那一形**全部**落到「交互作答」那一句上 —— plan-review 卡不弹、终帧措辞说错话。
+ * 非 paused 的读数、以及两个来源都答不出的 paused,一律 `false`(更宽的那一句兜底)。
+ */
+export function isReviewPark(read) {
+    const kind = runTerminalGateKind(read);
+    if (kind !== undefined && REVIEW_PARK_GATE_KINDS.includes(kind))
+        return true;
+    return read !== null && read.kind === 'paused' && read.flatStatus === FLAT_REVIEW_STATUS;
+}

package/dist/sqlEngineCapability.d.ts

@@ -92,8 +92,18 @@ export declare function projectSqlEngineCapability(caps: unknown): SqlEngineRead
  * 🔴 **不按 principal 分域**:SQL 姿态是**这台 worker 的连接事实**,与调用者是谁无关
  *    (与 `workflows` 那种 per-caller 的位刻意不同)—— 加一个用不上的去重域只会造出一条
  *    「换主体就读不到」的假缺席。
+ *
+ * 🔴 **`opts.generation` = 关掉「旧探测覆盖新读数」那条竞态的唯一正确供给**(0.60.0;异源对抗复审
+ *    [medium] 采纳,真病):`kickEngineCapsProbe` 的代际闸在 **probe 返回之后**才跑,而本 tee 是在
+ *    probe **内部**落地的 ⇒ 一次慢的旧探测能在 `invalidateEngineCaps` + 新探测都走完之后才返回,
+ *    把**上一台引擎**的读数重新写回来。宿主在**起探测那一刻**调 `engineCapsGeneration(baseUrl)` 抓号、
+ *    在这里原样交回,陈旧那一发就会被整只丢掉。
+ *    ⚠️ **不传 = 与本位到货之前逐字节同行为**(照写)—— additive 供给,不是强制门;端没跟上之前不会
+ *    有任何东西变坏。🔴 **tee 自己抓号是假判据**(陈旧那一发在这里读到的是新代号,永远像当代的)。
  */
-export declare function noteEngineCapsForSqlEngine(baseUrl: string, caps: unknown): void;
+export declare function noteEngineCapsForSqlEngine(baseUrl: string, caps: unknown, opts?: {
+    generation?: number;
+}): void;
 /**
  * 本进程观测到的 SQL 姿态;这一格空缺 ⇒ `{kind:'unobserved'}`(**绝不**折成 `none`)。
  *

package/dist/sqlEngineCapability.js

@@ -43,6 +43,7 @@
  */
 import { escapeDisplayControlChars } from './fleetTaskDesc.js';
 import { engineWireTarget } from './engineWireTarget.js';
+import { engineCapsGeneration } from './engineCapsCache.js';
 /**
  * caps 回体 → 本格读数;**畸形一律 `undefined`**(= 这一格不写 ⇒ 读口答 `unobserved`)。
  *
@@ -88,11 +89,22 @@ const readingByBase = new Map();
  * 🔴 **不按 principal 分域**:SQL 姿态是**这台 worker 的连接事实**,与调用者是谁无关
  *    (与 `workflows` 那种 per-caller 的位刻意不同)—— 加一个用不上的去重域只会造出一条
  *    「换主体就读不到」的假缺席。
+ *
+ * 🔴 **`opts.generation` = 关掉「旧探测覆盖新读数」那条竞态的唯一正确供给**(0.60.0;异源对抗复审
+ *    [medium] 采纳,真病):`kickEngineCapsProbe` 的代际闸在 **probe 返回之后**才跑,而本 tee 是在
+ *    probe **内部**落地的 ⇒ 一次慢的旧探测能在 `invalidateEngineCaps` + 新探测都走完之后才返回,
+ *    把**上一台引擎**的读数重新写回来。宿主在**起探测那一刻**调 `engineCapsGeneration(baseUrl)` 抓号、
+ *    在这里原样交回,陈旧那一发就会被整只丢掉。
+ *    ⚠️ **不传 = 与本位到货之前逐字节同行为**(照写)—— additive 供给,不是强制门;端没跟上之前不会
+ *    有任何东西变坏。🔴 **tee 自己抓号是假判据**(陈旧那一发在这里读到的是新代号,永远像当代的)。
  */
-export function noteEngineCapsForSqlEngine(baseUrl, caps) {
+export function noteEngineCapsForSqlEngine(baseUrl, caps, opts) {
     try {
         if (typeof baseUrl !== 'string' || baseUrl === '')
             return;
+        // 陈旧代际的那一发整只丢掉(见本函数顶注的 `opts.generation` 段);不传 ⇒ 照写,零行为变化。
+        if (opts?.generation !== undefined && opts.generation !== engineCapsGeneration(baseUrl))
+            return;
         const reading = projectSqlEngineCapability(caps);
         if (reading === undefined) {
             readingByBase.delete(baseUrl);

package/dist/writeProtectionCapability.d.ts

@@ -0,0 +1,142 @@
+/**
+ * writeProtectionCapability — **写保护名表**姿态的三端共用读面(0.60.0)。
+ *
+ * 引擎带一张**字面名表**,落在表行上的可定路径写(Write / Edit / NotebookEdit)从 `allow` 降级成
+ * `ask` —— 所以端可以**事先**告诉人「这些路径会弹卡」。两个读面同源同一份 boot 产物:
+ *   · **租户面** `GET /v1/capabilities` 的 `writeProtection`(engine ≥7.63.0 / S-138;sdk 8.4.0
+ *     `Capabilities.writeProtection`)—— 只有三位计数/开关,**不含行内容**;
+ *   · **operator 面** `GET /v1/diagnostics/wiring` 的 `writeProtection` —— 多出**行内容**与来源词。
+ *
+ * ── 🔴 四态,不是两态([honest-absence-not-fabricated-zero])──────────────────────────────────
+ * 与 `sqlEngineCapability` 逐字同一套词汇(通用读口答「这一格上有没有值」,窄读器答「值成不成形」):
+ *   ① `unobserved`   —— **本进程一次 caps 响应都没观测到**(一次性 doctor 就是这一档)。
+ *   ② `not_reported` —— caps 观测到了,而回体上**没有**这个键 ⇒ 老引擎(<7.63.0)。
+ *      🔴 它**不是**「这台部署没有写保护表」—— 恰恰相反:引擎侧**座位缺席时缺省表在岗**
+ *         (按键名 grep 推断「没装」会推错,上游把这一条写进了本位的顶注)。
+ *   ③ `none`         —— 引擎**明确说** `null`:这个进程说不出来(非 composition root 装配的夹具形)。
+ *      同样**不是**「没有表」。
+ *   ④ `present`      —— 三位俱全,原样渲。
+ *
+ * ── 🔴 三位刻意不合成一个布尔(上游顶注逐字)────────────────────────────────────────────────
+ * `armed`(生效表非空 ⇒ 真会弹卡)/ `rows`(生效表行数)/ `replaced`(整表替换旋钮被写过)——
+ * 合成之后「引擎缺省表在岗」与「运维换了一张自己的表」同为 true,而两者对运维说的是两件事。
+ * ⚠️ `replaced` 把「整表替换成**空**表」也算 true:报 false 会把「运维亲手关掉了表」说成
+ * 「缺省表没被动过」。
+ *
+ * ── 🔴 最小披露:逐行 name/kind 不上租户面 ──────────────────────────────────────────────────
+ * 部署自定义行可能含内部路径名,列出来等于告诉想绕过的人「哪些名字不受保护」。行内容只在
+ * operator 面({@link projectWriteProtectionPosture}),而那个端点本身是 operator-gated。
+ * 🔴 与**模式型** write deny(`SENSITIVE_WRITE_PATTERNS`)是**并列机制**,两个读面分开报、
+ * 绝不合成一位:两者的解法不同(一套改模式,一套改名表)。
+ */
+/** 租户面三位(server `WriteProtectionCapability` 逐字同形)。 */
+export interface WriteProtectionCapabilityView {
+    /** 生效表非空 ⇒ 引擎真会对表行弹卡。 */
+    armed: boolean;
+    /** 生效表的**行数**(内容只上 operator 面)。 */
+    rows: number;
+    /** 整表替换旋钮被写过 ⇒ 缺省表不再原样在岗。与 {@link armed} 刻意不合成。 */
+    replaced: boolean;
+}
+/** 四态读数(见文件头)。`unobserved` 由**读口**在这一格空缺时铸,不由投影铸。 */
+export type WriteProtectionReading = {
+    kind: 'unobserved';
+} | {
+    kind: 'not_reported';
+} | {
+    kind: 'none';
+} | {
+    kind: 'present';
+    view: WriteProtectionCapabilityView;
+};
+/**
+ * caps 回体 → 本格读数;**畸形一律 `undefined`**(= 这一格不写 ⇒ 读口答 `unobserved`)。
+ *
+ * 🔴 `undefined`(键不在)与 `null`(引擎说不出来)**是两件事**:前者 ⇒ `not_reported`(老引擎),
+ *    后者 ⇒ `none`(夹具形进程)。用 `??` / falsy 判会把两者压成一件。
+ * 🔴 三位**任一**形不合 ⇒ 整条判畸形。绝不留一个缺位的对象:一行写着「rows: 」的诊断比不渲这一行
+ *    更坏(它看起来像一个答案)。
+ * ⚠️ `rows` 按**非负有限整数**判,不按真值判:`0` 是合法读数(表在、但生效行为零),折成缺席会让
+ *    「表空了」与「没报」在消费端同形。
+ */
+export declare function projectWriteProtectionCapability(caps: unknown): WriteProtectionReading | undefined;
+/** operator 面的一行:一个**字面**名字 + 它怎么匹配。`name` 同时是这一行的稳定身份。 */
+export interface WriteProtectedRowView {
+    name: string;
+    /** `basename`(目标最后一段)/ `segment`(任意一段)/ `segment-run`(连续若干段);**开集读**。 */
+    kind: string;
+}
+/** operator 面读数(`GET /v1/diagnostics/wiring` 的 `writeProtection`)。 */
+export interface WriteProtectionPostureView {
+    /** 生效表逐行,逐字来自引擎自己的编译产物。**空数组 = 显式无表**(不是缺席)。 */
+    rows: readonly WriteProtectedRowView[];
+    /** `default`(两根旋钮都没写)/ `extra`(缺省表 + 增量)/ `replace`(整表替换)/ `off`
+     *  (整表替换成空表,合法且响亮);**开集读**。 */
+    source: string;
+    /** 整表替换**丢掉**的缺省行名;只在替换族在场。 */
+    droppedDefaultRows?: readonly string[];
+}
+/**
+ * operator 面回体的 `writeProtection` 段 → 读数;不成形 ⇒ `undefined`。
+ *
+ * 🔴 **空 `rows` 数组是正面事实**(「显式无表」),照铸 `[]` —— 与 `wiring_manifest.mcp[]` 同一条
+ *    已定谳的纪律;把它折成缺席等于把引擎明说的一句话读成「不知道」。
+ * 🔴 **坏行只丢那一行**(与 mcp 行同判据),但 `source` 读不出 ⇒ **整段缺席**:没有来源词的行表
+ *    答不了运维真正要问的那一问(「这是缺省表还是你换过的表」),而半段会被当成完整答案。
+ * 🔴 **不校「`droppedDefaultRows` 只在替换族在场」**:那是引擎的段内规矩,server 已按它铸;
+ *    包再校一遍只会在上游合法演进的当天把一个真读数判没(与开集词表同规)。
+ */
+export declare function projectWriteProtectionPosture(wiring: unknown): WriteProtectionPostureView | undefined;
+/**
+ * 宿主 caps probe 的**读面 tee** 落点(与 `noteEngineCapsForSqlEngine` 并列)。绝不 throw ——
+ * 读面腿不许反噬 caps 探测链。
+ *
+ * 🔴 投影 `undefined`(caps 畸形)⇒ 这一格**被删**而不是留着上一台引擎的旧值。
+ * ⚠️ 「同端口 respawn / 版本回滚之后新探测失败或还在飞」是**另一条路**(本 tee 一次都不触发),
+ *    由 {@link forgetWriteProtectionReading} 在装配口上收 —— 与 SQL 那一格逐字同形。
+ * 🔴 **不按 principal 分域**:写保护表是**这台 worker 的 boot 产物**,与调用者是谁无关。
+ *
+ * 🔴 **`opts.generation` = 关掉「旧探测覆盖新读数」那条竞态的唯一正确供给**(0.60.0;异源对抗复审
+ *    [medium] 采纳,真病):`kickEngineCapsProbe` 的代际闸在 **probe 返回之后**才跑,而本 tee 是在
+ *    probe **内部**落地的 ⇒ 一次慢的旧探测能在 `invalidateEngineCaps` + 新探测都走完之后才返回,
+ *    把**上一台引擎**的读数重新写回来。宿主在**起探测那一刻**调 `engineCapsGeneration(baseUrl)` 抓号、
+ *    在这里原样交回,陈旧那一发就会被整只丢掉。
+ *    ⚠️ **不传 = 与本位到货之前逐字节同行为**(照写)—— additive 供给,不是强制门;端没跟上之前不会
+ *    有任何东西变坏。🔴 **tee 自己抓号是假判据**(陈旧那一发在这里读到的是新代号,永远像当代的)。
+ */
+export declare function noteEngineCapsForWriteProtection(baseUrl: string, caps: unknown, opts?: {
+    generation?: number;
+}): void;
+/** 本进程观测到的写保护姿态;这一格空缺 ⇒ `{kind:'unobserved'}`(**绝不**折成 `none`)。 */
+export declare function observedWriteProtection(baseUrl?: string | undefined): WriteProtectionReading;
+/**
+ * 四态 → doctor 那一行的 detail 串。**唯一措辞真源**(三端共用一句话;别在各端的行装配里另写一遍
+ * —— 与 `sqlEngineDoctorDetail` / `autoModeDoctorDetail` 同一条纪律)。
+ *
+ * 🔴 四句话刻意**互不相同、也互不蕴含**:「未观测」「老引擎不报」「进程说不出来」三种「读不出」
+ *    对运维是三条不同的下一步,而**没有一条**等于「这台部署没有写保护」。
+ * 🔴 `present` 那一句把三位**分开说**(见文件头「刻意不合成」):`armed` 说会不会弹卡,`rows` 说
+ *    几行,`replaced` 说缺省表还在不在岗。
+ * 🔴 行内容一个字都不渲(最小披露);`source` 是 operator 面的位,不上这一行。
+ */
+export declare function writeProtectionDoctorDetail(reading: WriteProtectionReading): string;
+/**
+ * operator 面读数 → 一行 detail(行名是 UNTRUSTED 自由文本 ⇒ 呈前**逐条**消毒 + 封长)。
+ *
+ * 🔴 只给**行数与来源**加上「头几行的名字」,不整表倾泻:一行诊断不是一个表格,而 operator 面的
+ *    真表读法是那个端点本身。
+ * 🔴 `rows: []` 渲的是**显式无表**这句正面事实,不是「读不出」。
+ */
+export declare function writeProtectionPostureDetail(posture: WriteProtectionPostureView): string;
+/**
+ * **换代失效口**(与 `forgetSqlEngineReading` 并列,由宿主在引擎温切成功后调)。
+ *
+ * 🔴 代际闸挡不住这一形:那道闸挡的是「旧响应写脏新一代」,而本格的病是反过来的 —— 新一代的探测
+ *    **根本没成功**,tee 一次都没触发,上一台引擎留在同一端口上的读数继续被当成当代事实答出去。
+ *    在 doctor 上它的形态最坏:一句**肯定句**(「这台部署有 12 行写保护」),说的却是一台已经不在
+ *    的引擎。处置是**清成未观测**,不是留旧值也不是铸一个 `none`。
+ * 空串 ⇒ no-op;绝不 throw(它跑在引擎温切路径上)。
+ */
+export declare function forgetWriteProtectionReading(baseUrl: string | undefined): void;
+/** 测试钩子。 */
+export declare function __resetWriteProtectionReadingsForTests(): void;