@sema-agent/client-core 0.12.1 → 0.13.0

package/dist/hitl/frameRouter.d.ts

@@ -0,0 +1,86 @@
+/**
+ * frameRouter — HITL gate 桥**内环**的帧路由(REF-CC-032 / SPLIT-12 第二刀,2026-08-02)。
+ *
+ * 一帧进、一个 `FrameAction` 出:路由本身不 yield、不读流、不决断,只把「这一帧该怎么处置」表达成
+ * 数据。驱动(`askGateWire.bridgeAskUserQuestionGates`)照 action 吐帧 / 结束 / park,外环决断在
+ * `parkResolver.ts`。这样内外环对台账的写全部经 `GateLedger` 的动词,不再各自直写同一批容器。
+ *
+ * 🔴 本文件同时是两把刀的**共享词汇层**:`AskGateWireDeps` / `isAskTool` / 两个 CC 逐字常量 /
+ *    park 形状谓词都落在这里 —— 它是「内环路由」与「外环决断」都够得着的最低模块(`parkResolver.ts`
+ *    import 本文件,反向没有边,不成环)。`askGateWire.ts` 原样 re-export 其中的公开面,对外零变化。
+ *
+ * 🔴 tool_end 的**有序**臂(拆分硬约束):原文 5 条分支的顺序是承重的 ——
+ *    分类器 deny(结构性机器签名,比「fs 写报错」更特定)必须先于 fs 的 HOLD/REJECT 分支判。
+ *    注册表化之后顺序不再由代码位置显式表达,所以 `TOOL_END_ARM_ORDER` 把顺序写成**数据**,
+ *    模块加载期一条断言把两者钉死:重排 `TOOL_END_ARMS` 而不同批改 `TOOL_END_ARM_ORDER` ⇒ 当场抛。
+ */
+import type { AgentEvent } from '@sema-agent/sdk';
+import type { HitlClientLike } from './hitlBridge.js';
+import { type RespondToolApprovalFn } from './toolApprovalWire.js';
+import type { GateLedger } from './gateLedger.js';
+/**
+ * CC `utils/messages.ts` 的 `REJECT_MESSAGE` **逐字**(B7 搬迁差分 2)。deny 后重放 tool_end 的
+ * render 面 stamp 用 —— vendored `renderToolUseRejectedMessage` 渲 `User rejected <op> to <path>`。
+ * 🔴 pure 门 B7 段:包内冻结字面量(无条件)+ 壳树全树扫描「每一处声明都逐字节相同」(壳树缺席=跳过)。
+ */
+export declare const HITL_REJECT_MESSAGE = "The user doesn't want to proceed with this tool use. The tool use was rejected (eg. if it was a file edit, the new_string was NOT written to the file). STOP what you are doing and wait for the user to tell you how to proceed.";
+/** core 对被 gate/连坐 abort 的 call 铸的 tool_end 载体(逐字;desktop session-host 真引擎实测
+ *  同款)——HOLD 谓词锚它做**精确等值**,普通工具错的输出是各自错误文案,永不进 HOLD。 */
+export declare const ENGINE_ABORT_TOOL_RESULT = "Operation aborted";
+/** 本桥消费的 wire 面(@sema-agent/sdk AgentClient 的结构切片,mock 可注入)。 */
+export interface AskGateWireDeps {
+    /** approvals.list/decide + assistant(HitlBridge 的 client 切片)。 */
+    client: HitlClientLike;
+    /** GET /v1/runs/:id/events — decide 后的续流 attach(lastEventId 续传)。 */
+    runsEvents: (taskId: string, opts?: {
+        signal?: AbortSignal;
+        lastEventId?: string;
+    }) => AsyncGenerator<AgentEvent>;
+    /** POST /v1/tool-approvals/:id/respond(server 1.191 同步帧腿,[830]①)。缺省=不消费
+     *  tool_approval 帧(帧被吞、引擎按自身 fail-closed TTL 自决)——mock/旧引擎路径零影响。 */
+    respondToolApproval?: RespondToolApprovalFn;
+}
+/** 两族 gate:AskUserQuestion 走问答 overlay(原路);其余(fs 写三件 / Bash / 一等
+ *  `kind==='tool_approval'`)走 CC 三选卡。 */
+export type GateKind = 'ask' | 'fs';
+/** park 请求:内环遇 gate 时带出去给外环决断。 */
+export interface GatePark {
+    gate: GateKind;
+    /** sync leg 的 `done{suspended}` 终帧 —— fail-soft 回退时原样吐回去(durable leg 的 park 无此帧)。 */
+    pendingDone?: AgentEvent | undefined;
+}
+/** 帧路由的产物:驱动只认这四种,自己不再判帧型。 */
+export type FrameAction = {
+    kind: 'yield';
+    events: readonly AgentEvent[];
+} | {
+    kind: 'skip';
+} | {
+    kind: 'park';
+    gate: GateKind;
+    pendingDone?: AgentEvent | undefined;
+} | {
+    kind: 'end';
+    events: readonly AgentEvent[];
+};
+/** 跨刀共享的可变标量(`realTaskId`):sync leg 从 `done{suspended}` 捕获、外环 attach 时读。
+ *  显式 ref 传参而不是让两把刀各存一份 —— 两份会在 durable 腿上分叉。 */
+export interface TaskIdRef {
+    current: string | undefined;
+}
+export interface FrameRouterCtx {
+    led: GateLedger;
+    deps: AskGateWireDeps;
+    taskId: TaskIdRef;
+    signal?: AbortSignal | undefined;
+}
+/** 上者的**窄口**(`findPendingForTask` 的 gate 过滤谓词签名)—— 出境的那一版不吃 `unknown`:
+ *  边界层的 unknown 在本模块里窄化完再跨模块(typeshape 门 B2 的纪律)。 */
+export declare function isAskTool(toolName: string | undefined): boolean;
+/** 这一帧是不是「host lane 的模型推进」= 扣留帧的放行信号。 */
+export declare function isHostProgressFrame(ev: AgentEvent): boolean;
+/**
+ * 一帧 → 一个处置。手柄的**先后**与原文逐条同序:tool_approval 帧 → tool_start → tool_end →
+ * suspended → done → failed → 透传。
+ */
+export declare function routeFrame(ev: AgentEvent, ctx: FrameRouterCtx): Promise<FrameAction>;

package/dist/hitl/frameRouter.js

@@ -0,0 +1,342 @@
+import { hostLog } from '../host.js';
+import { isToolApprovalGate, toolNameIsFsWrite, toolNameIsShellExec, isToolApprovalFrame, isFromSubagent, surfaceToolApprovalFrameAndRespond, } from './toolApprovalWire.js';
+import { classifierDenyFromToolEnd } from '../classifierVerdictWire.js';
+import { surfaceForCurrentSession } from './hitlHostSurface.js';
+/**
+ * CC `utils/messages.ts` 的 `REJECT_MESSAGE` **逐字**(B7 搬迁差分 2)。deny 后重放 tool_end 的
+ * render 面 stamp 用 —— vendored `renderToolUseRejectedMessage` 渲 `User rejected <op> to <path>`。
+ * 🔴 pure 门 B7 段:包内冻结字面量(无条件)+ 壳树全树扫描「每一处声明都逐字节相同」(壳树缺席=跳过)。
+ */
+export const HITL_REJECT_MESSAGE = "The user doesn't want to proceed with this tool use. The tool use was rejected (eg. if it was a file edit, the new_string was NOT written to the file). STOP what you are doing and wait for the user to tell you how to proceed.";
+function rejectMessageForRender() {
+    return HITL_REJECT_MESSAGE;
+}
+/** core 对被 gate/连坐 abort 的 call 铸的 tool_end 载体(逐字;desktop session-host 真引擎实测
+ *  同款)——HOLD 谓词锚它做**精确等值**,普通工具错的输出是各自错误文案,永不进 HOLD。 */
+export const ENGINE_ABORT_TOOL_RESULT = 'Operation aborted';
+// ── gate 词汇(两把刀共享)──────────────────────────────────────────────────────────────────────
+/** 工具名是不是 AskUserQuestion(空白/下划线/连字符与大小写都不敏感)。
+ *  **宽口**:帧上的 `toolName` 位是 UNTRUSTED 的任意值,判据自己吃 `unknown`,本模块内部用。 */
+function isAskToolLoose(name) {
+    return typeof name === 'string' && name.replace(/[\s_-]+/g, '').toLowerCase() === 'askuserquestion';
+}
+/** 上者的**窄口**(`findPendingForTask` 的 gate 过滤谓词签名)—— 出境的那一版不吃 `unknown`:
+ *  边界层的 unknown 在本模块里窄化完再跨模块(typeshape 门 B2 的纪律)。 */
+export function isAskTool(toolName) {
+    return isAskToolLoose(toolName);
+}
+/**
+ * 「这个工具名归 gate 管」的**统一**判据(#110 修,2026-08-02)。
+ *
+ * 🔴 它必须与 park 判定(`isAskTool` / `isToolApprovalGate`)覆盖**同一个集合** ——
+ * 两边不同集就是 [paired-mechanisms-must-share-premise] 那种「park 认得出、HOLD 认不出」的
+ * 半场病:[2150] S1 给 park 判定加了 `toolNameIsShellExec`(Bash/shell 类进 gate 了),但
+ * tool_end 手柄的 HOLD/REJECT 谓词还停在 `isAskTool || toolNameIsFsWrite` ——
+ * 于是 Bash 的 durable gate 走到这里就两件事同时出错:
+ *   ① park 期的毒化帧(`tool_end{isError:true, output:"Operation aborted"}`)没被 HOLD,
+ *      **当场上屏**;用户按了 Yes、命令也真跑了,屏幕上却永远停在 `Error: Operation aborted`;
+ *   ② 更狠的是紧接着的 `markEnded(toolCallId)` —— resume 后引擎重放的**真** tool_end
+ *      被手柄开头的 `isEnded` 早退静默去重,真结果一帧都上不了屏。
+ * 附带第三件:deny 腿的 `User rejected …` 文案对 Bash 同样进不去,用户看到的是引擎原文。
+ * 证据链见 cli 仓 design/cli-164 T4-A(硬 oracle=磁盘状态:按 Yes 后 printf +504ms 真落盘)。
+ */
+function isGatedToolName(name) {
+    if (isAskToolLoose(name))
+        return true;
+    if (typeof name !== 'string')
+        return false;
+    return toolNameIsFsWrite(name) || toolNameIsShellExec(name);
+}
+/** done 帧的 AskUserQuestion park 形状(结构性读;别的终态一律 false)。 */
+function isAskGatePark(result) {
+    const r = result;
+    return (!!r &&
+        r.status === 'suspended' &&
+        isAskToolLoose(r.checkpointGate?.toolName) &&
+        typeof r.taskId === 'string' &&
+        r.taskId.length > 0);
+}
+/** done 帧的工具审批 park 形状([816] 放宽腿 + [2150] Bash 半场):status suspended +
+ *  checkpointGate 指 fs 写三件 / Bash / 一等 kind==='tool_approval'(超集谓词 isToolApprovalGate,
+ *  decide 腿对两族同构、卡形归壳分发)。Ask gate 恒先判(问答 overlay 原路)。 */
+function isFsApprovalPark(result) {
+    const r = result;
+    return (!!r &&
+        r.status === 'suspended' &&
+        typeof r.taskId === 'string' &&
+        r.taskId.length > 0 &&
+        !isAskToolLoose(r.checkpointGate?.toolName) &&
+        isToolApprovalGate(r.checkpointGate));
+}
+/** 台账里那份 gated `tool_start` 当拍的 args 快照(UNTRUSTED,只搬运不解释)。 */
+function argsOfGatedStart(led, callId) {
+    if (callId === undefined)
+        return undefined;
+    return led.gatedStartArgs().get(callId);
+}
+// ── [2084]① 扣留帧「模型推进即放行」(2026-07-30;同日 web 复审纠偏收窄触发集)────────────────
+//
+// HOLD 只护 park 窗口。放行触发集 = host-lane **模型推进**帧:text_delta/reasoning_delta/
+// tool_start —— park 路径上这三种在 done{suspended} 之前不会出现,真错路径上下一轮必来其一。
+// 🔴 turn_end 明确**不在**触发集(初版在,web 复审真机轨迹逮红):core agent-loop 的 turn_end
+// emit 在 executeToolCalls 之后**无 abort/suspend 守卫**(邻臂都有,唯此一处没有)⇒ 真 park
+// 的帧序是 tool_end(毒化)→ message_committed → turn_end → done{suspended},turn_end 若放行
+// 会把毒化帧漏上屏,且 flushHeld 的 ended 记账让 decide 后重放的解答帧被当已收口丢弃
+// (真实答案卡永不出现)。代价 = turn 末尾无后续推进帧的 abort 形帧等到终帧 flush,与修前同。
+// parentToolCallId 在场 = sub-agent 行帧,park 期间孙代照常说话,不算 host 推进(负控①C)。
+// (普通工具错自 [2084]①-b 谓词收窄后根本不进 HOLD,零滞后不依赖本触发集。)
+/** 这一帧是不是「host lane 的模型推进」= 扣留帧的放行信号。 */
+export function isHostProgressFrame(ev) {
+    return ((ev.type === 'text_delta' || ev.type === 'reasoning_delta' || ev.type === 'tool_start') &&
+        ev.parentToolCallId === undefined);
+}
+/**
+ * 🔴 **有序**(承重):分类器批3([907])的注释原文 = 「结构性识别(core 机器签名)优先于 fs
+ * HOLD/REJECT 分支(签名比"fs 写报错"更特定;分类器 deny 从不产 tool_approval 帧,denied /
+ * denyStamp 与之互斥)」。顺序作为数据写在这里,下方加载期断言把它与 `TOOL_END_ARMS` 钉死。
+ */
+const TOOL_END_ARM_ORDER = [
+    'classifier-deny',
+    'deny-stamp-next',
+    'denied-call',
+    'hold-poison',
+    'generic-close',
+];
+/**
+ * tool_end 的**有序**臂表:自上而下第一个返回动作的臂胜出。顺序 = 原文 5 条分支的书写顺序,
+ * 由 `TOOL_END_ARM_ORDER` + 下方加载期断言锁死(改这张表的顺序必须同批改那张表)。
+ * 🔴 表尾 `generic-close` 是**无条件**兜底臂 —— 给它加早退条件 = tool_end 会被整帧静默丢弃。
+ */
+const TOOL_END_ARMS = [
+    {
+        // ① 分类器 deny 裁决帧:副作用 = CC 207 通知行 + Recent Denials 记账;render 面 stamp 去
+        //    system-reminder 包裹渲裁决原文(render-only,模型面原文不动)。
+        id: 'classifier-deny',
+        run(ev, callId, led) {
+            if (ev.isError !== true || led.isDenied(callId))
+                return undefined;
+            const verdict = classifierDenyFromToolEnd(ev);
+            if (!verdict)
+                return undefined;
+            led.markEnded(callId);
+            led.dropHeld(callId);
+            surfaceForCurrentSession()?.surfaceClassifierDeny(typeof ev.toolName === 'string' ? ev.toolName : 'tool', verdict);
+            hostLog('debug', `liveHitlAskWire: classifier deny verdict on ${callId} (${String(ev.toolName)}) — labeled render + notice`);
+            return { kind: 'yield', events: [{ ...ev, output: verdict.message, structured: undefined }] };
+        },
+    },
+    {
+        // ② 同步帧腿 deny 且 callId 没关联上:下一张 gated 报错帧即该 gate 的收口帧,stamp REJECT 文案。
+        //    #110:stamp 也要盖 shell —— 否则按 No 时用户看到的是引擎原文 `Operation aborted`。
+        id: 'deny-stamp-next',
+        run(ev, callId, led) {
+            if (ev.isError !== true || !isGatedToolName(ev.toolName) || led.isDenied(callId))
+                return undefined;
+            if (!led.takeDenyStamp())
+                return undefined;
+            led.markEnded(callId);
+            led.dropHeld(callId);
+            return { kind: 'yield', events: [{ ...ev, output: rejectMessageForRender(), structured: undefined }] };
+        },
+    },
+    {
+        // ③ 三选卡 No:重放的报错帧 stamp REJECT 文案 → vendored 卡渲 `User rejected <op> to <path>`。
+        id: 'denied-call',
+        run(ev, callId, led) {
+            if (ev.isError !== true || !isGatedToolName(ev.toolName))
+                return undefined;
+            if (!led.takeDenied(callId))
+                return undefined;
+            led.markEnded(callId);
+            led.dropHeld(callId);
+            return { kind: 'yield', events: [{ ...ev, output: rejectMessageForRender(), structured: undefined }] };
+        },
+    },
+    {
+        // ④ [2084]①-b HOLD 谓词收窄(2026-07-30,desktop 复审建议采纳):park 毒化帧的载体是**确切的
+        //    引擎 abort 标记**(core 对被 gate/连坐 abort 的 call 铸 `tool_end{isError:true,
+        //    output:"Operation aborted"}`;desktop session-host 2026-07-29 对真引擎实测同款)。普通
+        //    工具错(old_string 不命中/read-gate 拒绝…)输出是各自的错误文案,**根本不该进 HOLD**
+        //    —— 收窄后它们零滞后直达转录(落到 ⑤ 通用收口),不再依赖「推进信号放行」。
+        id: 'hold-poison',
+        run(ev, callId, led) {
+            if (ev.isError !== true || !isGatedToolName(ev.toolName))
+                return undefined;
+            if (ev.output !== ENGINE_ABORT_TOOL_RESULT)
+                return undefined;
+            led.hold(callId, ev); // park 毒化帧,先 HOLD(gate 定性前不渲 Error 卡)
+            return { kind: 'skip' };
+        },
+    },
+    {
+        // ⑤ 通用收口(**无条件命中**,兜底臂):正常收口(重放的 isError:false 解答帧)赢;已作答的
+        //    gate 在这里把真实答案 stamp 回 `structured`,否则卡片渲成结果不可用。
+        id: 'generic-close',
+        run(ev, callId, led) {
+            led.markEnded(callId);
+            led.dropHeld(callId);
+            const answered = led.answerFor(callId);
+            if (answered && ev.isError !== true && ev.structured === undefined) {
+                led.dropAnswer(callId);
+                return { kind: 'yield', events: [{ ...ev, structured: answered }] }; // 真实答案卡
+            }
+            return { kind: 'yield', events: [ev] };
+        },
+    },
+];
+// 🔴 顺序锁(SPLIT-12 硬约束):注册表化把「顺序」从代码位置搬成了数据,于是顺序本身需要一条断言。
+// 加载期求值 —— 重排 `TOOL_END_ARMS` 而没同批改 `TOOL_END_ARM_ORDER` 的那次 import 当场抛,
+// 而不是等到某个 Bash gate 的毒化帧在用户屏上停住才发现。
+{
+    const actual = TOOL_END_ARMS.map(a => a.id).join(' > ');
+    const expected = TOOL_END_ARM_ORDER.join(' > ');
+    if (actual !== expected) {
+        throw new Error(`frameRouter: tool_end 有序臂被重排(实际 ${actual} ≠ 登记 ${expected})—— ` +
+            '这五条分支的先后是承重的(分类器 deny 的结构性签名必须先于 fs 的 HOLD/REJECT 判),' +
+            '改顺序必须同批改 TOOL_END_ARM_ORDER 并说明为什么新顺序仍然对。');
+    }
+}
+// ── 帧手柄 ────────────────────────────────────────────────────────────────────────────────────
+async function routeToolApprovalFrame(ev, ctx) {
+    // ── server 1.191 同步帧腿([830]①):`tool_approval` 帧 → 三选卡 → respond ────────────────
+    // 引擎此刻同步阻塞在帧上(fail-closed:无 respond/TTL 5min/abort ⇒ deny),await 卡决断安全。
+    // 帧是 HITL 词汇非 AgentEvent arm——两种帧都不外泄到渲染管道。
+    const { led, deps } = ctx;
+    if (ev.type === 'tool_approval_complete')
+        return { kind: 'skip' }; // 收口帧:卡已由决断路径撤下,吞掉
+    if (!deps.respondToolApproval) {
+        hostLog('debug', `liveHitlAskWire: tool_approval frame ${ev.approvalId} but no respond wire — engine self-settles (TTL deny)`);
+        return { kind: 'skip' };
+    }
+    // 补验批 askq 案定谳(2026-07-23,黑板 [1534],引擎 dist 逐坐标读定):core 的 durable
+    // question policy 对 AskUserQuestion 出 action:"ask",本意让 durable gate park(suspended
+    // → 下方 bridge 弹卡收答);但 core suspendAsk 的退位条件(safety 缺席 + onAsk 在场)
+    // 把问题门也抢进了同步审批帧腿(壳为 fs 写权限三选卡开的 TOOL_APPROVAL_ENABLED)——同步帧
+    // 二值 respond 装不下「答案」,链路死锁:deny=模型误信问题已展示原地等;allow=执行工具
+    // 本体炸 durable 装配的 onQuestion 占位(QUESTION_AWAITS_RESUME)。此处取两害之轻恒 allow:
+    // 模型收到明确错误后退化成正文提问,用户尚可下一条消息作答(deny 形连这条退化路都没有)。
+    // 承重域收敛史([1543]§一 cli 注意):core 1.375 修 question gate 恒 park(健康路),
+    // 1.376 又断了降级路(checkpoint pre-commit/put 失败 fallback 改 typed refusal)与继承链
+    // 两臂——1.376+ 下 ask 工具在任何路径都不再出 tool_approval 帧,本分支唯一剩余承重
+    // = 旧引擎(<1.375)兼容,askq pty fence @1.375+ 已四门全绿实证([1542])。
+    if (isAskToolLoose(ev.toolName)) {
+        try {
+            await deps.respondToolApproval(ev.approvalId, 'allow', {
+                ...(ctx.signal && !ctx.signal.aborted ? { signal: ctx.signal } : {}),
+            });
+            hostLog('debug', `liveHitlAskWire: ask-tool approval frame ${ev.approvalId} → allow(问题门放行,候 park 弹卡)`);
+        }
+        catch (e) {
+            hostLog('debug', `liveHitlAskWire: ask-tool approval allow failed for ${ev.approvalId}: ${String(e)} — engine self-settles (TTL)`);
+        }
+        return { kind: 'skip' };
+    }
+    // [1535]/server 1.258:子代的审批帧(broker 腿浮到宿主流,判别=fromSubagent 显式键
+    // core 1.378 优先/sourceTaskId 在场性兜底)——子代的 tool_start 不在宿主行流上,绝不把
+    // 宿主自己的 pending fs call 关联给它(args 会错配成宿主的 diff、deny 会误标宿主 call 的
+    // REJECT 收口)。args 从帧上取,deny 收口归子代 lane 自理。
+    const fromSubagent = isFromSubagent(ev);
+    hostLog('debug', `liveHitlAskWire: tool_approval frame ${ev.approvalId} tool=${String(ev.toolName)}${fromSubagent ? ` from-subagent=${String(ev.sourceTaskId ?? ev.sourceAgentName ?? 'explicit')}` : ''}`);
+    const gatedCallId = !fromSubagent ? led.lastPendingFsCall() : undefined;
+    const decision = await surfaceToolApprovalFrameAndRespond(ev, deps.respondToolApproval, argsOfGatedStart(led, gatedCallId), ctx.signal);
+    if (decision === 'deny' && !fromSubagent) {
+        // 该 call 的报错收口帧 stamp REJECT 文案(vendored `User rejected <op> to <path>` 卡)。
+        if (gatedCallId !== undefined)
+            led.markDenied(gatedCallId);
+        else
+            led.armDenyStamp();
+    }
+    return { kind: 'skip' };
+}
+function routeToolStart(ev, callId, led) {
+    if (!led.markStarted(callId))
+        return { kind: 'skip' }; // durable 重放的已渲 call
+    if (isGatedToolName(ev.toolName)) {
+        // #110:Bash 也要记 args —— 卡片渲染要拿到 `command`,不记则 shell gate 的卡面空着。
+        led.noteGatedStart(callId, ev);
+        if (typeof ev.toolName === 'string' && toolNameIsFsWrite(ev.toolName))
+            led.pushFsCall(callId);
+        // REF-CC-034:`park.gate==='fs'` 分支覆盖 fs 写 + shell 执行两族(isToolApprovalGate
+        // 超集谓词)——`lastFsOrShellGatedCallId` 两族都要跟,否则 Bash gate 的已决断身份
+        // 候选恒 undefined。与 `pushFsCall` 不同,它不在 tool_end 到达时清空(见台账声明处注)。
+        if (typeof ev.toolName === 'string' && (toolNameIsFsWrite(ev.toolName) || toolNameIsShellExec(ev.toolName))) {
+            led.noteFsOrShellGate(callId);
+        }
+    }
+    return { kind: 'yield', events: [ev] };
+}
+function routeToolEnd(ev, callId, led) {
+    if (led.isEnded(callId))
+        return { kind: 'skip' }; // durable 重放/park 复写的已收口 call
+    led.dropFsCall(callId);
+    for (const arm of TOOL_END_ARMS) {
+        const action = arm.run(ev, callId, led);
+        if (action)
+            return action;
+    }
+    // 不可达:兜底臂 generic-close 无条件命中。真走到这里 = 有人给它加了早退条件,
+    // 那样 tool_end 会被整帧静默丢弃(用户看不到任何收口),必须当场喊出来而不是 `skip`。
+    throw new Error('frameRouter: tool_end 有序臂全部落空 —— generic-close 不再是无条件兜底臂');
+}
+function routeSuspended(ev, ctx) {
+    // durable leg 的 park arm(续流中模型再次提问/再次撞写权限)。gate 只带 kind/toolName,
+    // payload 走 approvals。
+    if (ev.gate && isAskToolLoose(ev.gate.toolName) && ctx.taskId.current)
+        return { kind: 'park', gate: 'ask' };
+    if (ev.gate &&
+        isToolApprovalGate(ev.gate) &&
+        ctx.taskId.current) {
+        return { kind: 'park', gate: 'fs' };
+    }
+    return { kind: 'yield', events: [ev] }; // 其余 gate:透传(现状,eventToSdkMessage 出 null)
+}
+function routeDone(ev, ctx) {
+    const { led } = ctx;
+    if (isAskGatePark(ev.result)) {
+        ctx.taskId.current = ctx.taskId.current ?? ev.result.taskId;
+        return { kind: 'park', gate: 'ask', pendingDone: ev };
+    }
+    if (isFsApprovalPark(ev.result)) {
+        ctx.taskId.current = ctx.taskId.current ?? ev.result.taskId;
+        return { kind: 'park', gate: 'fs', pendingDone: ev };
+    }
+    const events = [...led.flushHeld()]; // 真错(非 gate)的 Ask tool_end 此刻诚实渲染
+    // durable 终帧的 result.taskId === sessionId(引擎 durable quirk)会让 captureSessionId 跳过
+    // rewind 绑定 —— 用 sync leg 捕的真 handle 修正回去。
+    const r = ev.result;
+    const realTaskId = ctx.taskId.current;
+    if (realTaskId && r && r.taskId === r.sessionId && r.taskId !== realTaskId) {
+        events.push({ ...ev, result: { ...ev.result, taskId: realTaskId } });
+    }
+    else {
+        events.push(ev);
+    }
+    return { kind: 'end', events };
+}
+/**
+ * 一帧 → 一个处置。手柄的**先后**与原文逐条同序:tool_approval 帧 → tool_start → tool_end →
+ * suspended → done → failed → 透传。
+ */
+export async function routeFrame(ev, ctx) {
+    const { led } = ctx;
+    if (isToolApprovalFrame(ev)) {
+        // #51: `ToolApprovalFrame` frames are documented as NOT part of the
+        // `AgentEvent` union (a separate SSE wire vocabulary riding the same
+        // stream) — intersecting the type-predicate's asserted type with the
+        // unrelated `AgentEvent` union collapses every arm to `never`. Local
+        // rebind restores the real (already-checked) shape.
+        const frame = ev;
+        return await routeToolApprovalFrame(frame, ctx);
+    }
+    if (ev.type === 'tool_start' && typeof ev.toolCallId === 'string')
+        return routeToolStart(ev, ev.toolCallId, led);
+    if (ev.type === 'tool_end' && typeof ev.toolCallId === 'string')
+        return routeToolEnd(ev, ev.toolCallId, led);
+    if (ev.type === 'suspended')
+        return routeSuspended(ev, ctx);
+    if (ev.type === 'done')
+        return routeDone(ev, ctx);
+    if (ev.type === 'failed')
+        return { kind: 'end', events: [...led.flushHeld(), ev] };
+    return { kind: 'yield', events: [ev] };
+}

package/dist/hitl/gateLedger.d.ts

@@ -0,0 +1,107 @@
+/**
+ * gateLedger — HITL gate 桥的**单一台账**(REF-CC-032 / SPLIT-12 第一刀,2026-08-02)。
+ *
+ * 拆分动机(P1 lens-giant-split SPLIT-12 的 evidence 段逐条):`bridgeAskUserQuestionGates`
+ * 里的 8 个集合 + 若干标量,**内环帧路由**与**外环 park 决断**各自直写同一批容器 ——
+ *   · `heldAskEnds` 写于内环 tool_end 手柄、删于内环四处 **与外环 decide 成功那一处**、drain 于 flushHeld;
+ *   · `deniedCalls` 写于内环 tool_approval 手柄 **与外环 fs decide 的 denied 臂**、消费于内环 tool_end;
+ *   · `resolvedAnswers` 写于**外环**、消费于**内环**;
+ *   · `endedCalls` 写于内环四处 **与 flushHeld**。
+ * 「同一个容器有两个写者、写法各自散着」正是这段代码没法拆的真约束。本文件把容器收成一个对象并
+ * 给出**动词**:内外环从此都只经动词写,容器本身只有一个写者(本模块),两把刀之间靠显式传参共享
+ * 这一个台账对象。
+ *
+ * 🔴 本模块**没有**模块级状态:`createGateLedger()` 每个 turn 造一份(与原来那些函数体内 `new Map()`
+ *    的生命周期逐字相同)。它不是单例,也不该变成单例 —— 两个并发 turn 共用一份台账 =
+ *    A turn 的 HOLD 帧被 B turn 的 flush 吐出去。
+ *
+ * 🔴 `AskAnsweredOutput` 落在本文件而不是留在 `askGateWire.ts`:它是 `resolvedAnswers` 的值类型,
+ *    台账要能自描述,值类型必须与台账同层或更低。`askGateWire.ts` 原样 re-export 它,对外类型面不变。
+ */
+import type { AgentEvent } from '@sema-agent/sdk';
+/** CC AskUserQuestion outputSchema 形状(答过的问题卡):toolResult 的 `ask-user-question` arm
+ *  消费它渲真实答案卡(否则「诚实缺席」路径会把这张卡渲成结果不可用)。 */
+export interface AskAnsweredOutput {
+    type: 'ask-user-question';
+    questions: unknown[];
+    answers: Record<string, string>;
+    annotations?: Record<string, {
+        notes?: string;
+    }>;
+}
+/**
+ * 一个 turn 的 gate 台账。动词按「谁写、谁读」分组,每组的注释说明它承的是哪条不变量。
+ *
+ * 🔴 命名纪律:`mark*` = 只写;`is*` / `*For` / `last*` = 只读;`take*` = 读且消费(一次性);
+ *    `drop*` = 只删。读写混合的动词只有 `take*` 与 `markStarted`,两者的一次性语义都写在各自注释里 ——
+ *    因为原文里正是「`has` 完接着 `delete`」「`has` 完接着 `add`」这两种成对写法散在多处,
+ *    收成一个动词才谈得上「写者唯一」。
+ */
+export interface GateLedger {
+    /** #110 缺陷② a:`lastSeq` 要跟得上**已消费的最大 seq**。durable `runs.events` 流上并非每帧
+     *  都带 `id`(数字 `seq` 位的帧同样在场),旧式只吃 `ev.id` ⇒ 停在最后一个带 id 的帧上 ⇒
+     *  re-attach 从一个陈旧位置重放,把已经决断的 park 又送一遍(实测:消费到 16 却 attach from 8)。 */
+    noteSeq(ev: AgentEvent): void;
+    lastSeq(): string | undefined;
+    /** 首见 ⇒ true(并记账);durable 重放的已渲 call ⇒ false。 */
+    markStarted(callId: string): boolean;
+    /** 🔴 存 **tool_start 当拍的 `args` 快照**而非帧引用(与拆分前 `askArgsByCall` 逐字同语义;
+     *  codex 复审确证差异 #1 的收货修)——存帧引用意味着「上游在 yield 后改写 `ev.args`」会漂进
+     *  审批 payload,且台账持帧延长了整帧生命周期。载荷仍是 UNTRUSTED unknown,台账只搬运不解释。 */
+    noteGatedStart(callId: string, ev: AgentEvent): void;
+    gatedStartArgs(): ReadonlyMap<string, unknown>;
+    isEnded(callId: string): boolean;
+    markEnded(callId: string): void;
+    /** park 毒化的 gated tool_end(isError:true "Operation aborted")——HOLD 到 gate 定性
+     *  (AskUserQuestion + [816] 放宽后的 fs 写工具 + [2150] Bash)。 */
+    hold(callId: string, ev: AgentEvent): void;
+    dropHeld(callId: string): void;
+    heldCount(): number;
+    /** drain:逐帧吐出并**同批记 ended**(fail-soft 回退路径与终帧路径共用的唯一出口)。 */
+    flushHeld(): Generator<AgentEvent>;
+    /** 三选卡 deny 过的 call:重放 tool_end 的 render 面 stamp REJECT_MESSAGE(vendored
+     *  renderToolUseRejectedMessage 渲 `User rejected <op> to <path>`,CC 逐字)。 */
+    markDenied(callId: string): void;
+    isDenied(callId: string): boolean;
+    /** 一次性消费(原文的 `has` + `delete` 成对写法)。 */
+    takeDenied(callId: string): boolean;
+    /** 同步帧腿 deny 但 callId 关联不上(引擎在 tool_start 前出帧的形状):stamp 下一张 gated 报错帧。 */
+    armDenyStamp(): void;
+    /** 一次性消费:武装中 ⇒ 解除并返回 true。 */
+    takeDenyStamp(): boolean;
+    /** started-未-ended 的 fs 写 call(顺序保留)——帧契约不带 toolCallId;引擎阻塞在帧上,
+     *  最后一张未收口 fs 写 call 即被 gate 的 call。 */
+    pushFsCall(callId: string): void;
+    dropFsCall(callId: string): void;
+    lastPendingFsCall(): string | undefined;
+    /** REF-CC-034:最近一次见到的 fs 写 / shell 执行 gated tool_start 的 callId(`park.gate==='fs'`
+     *  分支的两族 toolName)——**不**随 tool_end 清空(与 `pushFsCall/dropFsCall` 的关键差异:
+     *  那一组在 tool_end 到达就 drop 掉,而 durable re-attach 重放的 `suspended` park 没有配套的新
+     *  tool_start/tool_end,那时它早已空了,取不到候选 callId)。只在**新的** gated tool_start 到来
+     *  时前进,天然把「这次 park 到底是哪个 call」的身份带过 decide→重放两轮。 */
+    noteFsOrShellGate(callId: string): void;
+    lastFsOrShellGatedCallId(): string | undefined;
+    /** 续流重放的解答 tool_end 无 output,不补就会渲成结果不可用;这里记下真实答案供该帧 stamp
+     *  `structured` 让卡片渲真实选择。 */
+    rememberAnswer(callId: string, answered: AskAnsweredOutput): void;
+    answerFor(callId: string): AskAnsweredOutput | undefined;
+    dropAnswer(callId: string): void;
+    /**
+     * #110 缺陷② 的**承重**修 / REF-CC-034:durable re-attach 会把「已经决断过的 park」重放一遍
+     * (边界上必然发生:`lastEventId` 再准也只能精确到帧,park 帧本身就在续流的重放窗口里)。重放的
+     * park 走到决断会去取 pending approval —— 那一行早已 resolved ⇒ 拿不到 ⇒ `failed` ⇒ 合成
+     * `hitl_unanswered` 终帧。而引擎侧 run 其实已经 `completed`:壳谎报失败,连带 CC 转录 0 行写出、
+     * 同 session `--resume` 报 `No conversation found` —— **会话废掉**。
+     *
+     * 首选判据是文案/code 双臂(`parkResolver.isAlreadyResolvedFailure`);本集合是第二条、
+     * **身份匹配**(非文案)的独立判据:拿 `lastFsOrShellGatedCallId()` 算出这次 park 的候选 callId,
+     * 若它已在本集合里,不论失败文案长什么样都按「已解决」处置。方向偏宽符合不对称原则(误判成
+     * 「已解决」最多多读一轮、被 hop 预算兜底;误判成「真失败」烧会话)。
+     */
+    markDecided(callId: string): void;
+    isDecided(callId: string): boolean;
+    /** 只给 debug 串用的规模位(`[decided so far: N]`)。 */
+    decidedCount(): number;
+}
+/** 造一份 turn 级 gate 台账(**不是单例**,见文件头注)。 */
+export declare function createGateLedger(): GateLedger;

package/dist/hitl/gateLedger.js

@@ -0,0 +1,113 @@
+/** 造一份 turn 级 gate 台账(**不是单例**,见文件头注)。 */
+export function createGateLedger() {
+    const startedCalls = new Set();
+    const endedCalls = new Set();
+    const heldAskEnds = new Map();
+    const gatedStartArgsByCall = new Map();
+    const deniedCalls = new Set();
+    const pendingFsCalls = [];
+    const resolvedAnswers = new Map();
+    const decidedGates = new Set();
+    let lastFsOrShellGatedCall;
+    let denyStampNextFsEnd = false;
+    let seq;
+    return {
+        noteSeq(ev) {
+            const rawSeq = ev.id ?? ev.seq;
+            if (typeof rawSeq === 'string' && rawSeq.length > 0)
+                seq = rawSeq;
+            else if (typeof rawSeq === 'number' && Number.isFinite(rawSeq))
+                seq = String(rawSeq);
+        },
+        lastSeq() {
+            return seq;
+        },
+        markStarted(callId) {
+            if (startedCalls.has(callId))
+                return false;
+            startedCalls.add(callId);
+            return true;
+        },
+        noteGatedStart(callId, ev) {
+            gatedStartArgsByCall.set(callId, ev.args);
+        },
+        gatedStartArgs() {
+            return gatedStartArgsByCall;
+        },
+        isEnded(callId) {
+            return endedCalls.has(callId);
+        },
+        markEnded(callId) {
+            endedCalls.add(callId);
+        },
+        hold(callId, ev) {
+            heldAskEnds.set(callId, ev);
+        },
+        dropHeld(callId) {
+            heldAskEnds.delete(callId);
+        },
+        heldCount() {
+            return heldAskEnds.size;
+        },
+        *flushHeld() {
+            for (const [callId, held] of heldAskEnds) {
+                endedCalls.add(callId);
+                yield held;
+            }
+            heldAskEnds.clear();
+        },
+        markDenied(callId) {
+            deniedCalls.add(callId);
+        },
+        isDenied(callId) {
+            return deniedCalls.has(callId);
+        },
+        takeDenied(callId) {
+            return deniedCalls.delete(callId);
+        },
+        armDenyStamp() {
+            denyStampNextFsEnd = true;
+        },
+        takeDenyStamp() {
+            if (!denyStampNextFsEnd)
+                return false;
+            denyStampNextFsEnd = false;
+            return true;
+        },
+        pushFsCall(callId) {
+            pendingFsCalls.push(callId);
+        },
+        dropFsCall(callId) {
+            const at = pendingFsCalls.indexOf(callId);
+            if (at !== -1)
+                pendingFsCalls.splice(at, 1);
+        },
+        lastPendingFsCall() {
+            return pendingFsCalls.length > 0 ? pendingFsCalls[pendingFsCalls.length - 1] : undefined;
+        },
+        noteFsOrShellGate(callId) {
+            lastFsOrShellGatedCall = callId;
+        },
+        lastFsOrShellGatedCallId() {
+            return lastFsOrShellGatedCall;
+        },
+        rememberAnswer(callId, answered) {
+            resolvedAnswers.set(callId, answered);
+        },
+        answerFor(callId) {
+            return resolvedAnswers.get(callId);
+        },
+        dropAnswer(callId) {
+            resolvedAnswers.delete(callId);
+        },
+        markDecided(callId) {
+            decidedGates.add(callId);
+        },
+        isDecided(callId) {
+            return decidedGates.has(callId);
+        },
+        decidedCount() {
+            return decidedGates.size;
+        },
+    };
+}