@sema-agent/client-core 0.12.2 → 0.14.0

package/dist/hitl/askGateWire.js

@@ -1,648 +1,99 @@
-import { HitlBridge } from './hitlBridge.js';
-import { publishQuestionFrame, registerLocalQuestionResponder, hasQuestionOverlay, } from '../liveQuestionStore.js';
-import { hostLog } from '../host.js';
-import { createSessionSlot, DEFAULT_SESSION_KEY } from '../sessionSlot.js';
-import { isToolApprovalGate, toolNameIsFsWrite, toolNameIsShellExec, surfaceFsApprovalAndDecide, isToolApprovalFrame, isFromSubagent, surfaceToolApprovalFrameAndRespond, } from './toolApprovalWire.js';
-import { classifierDenyFromToolEnd } from '../classifierVerdictWire.js';
-// W1(design/161):sessionKey → 注册表;零参 API = DEFAULT_SESSION_KEY 兼容层(cli 装配不动)。
-const hostSurfaceByKey = createSessionSlot();
-const hostSurfaceMissesByKey = new Map();
-/** 装 HITL 宿主面(传 null 卸)。返回还原函数。 */
-export function installHitlHostSurface(surface) {
-    return installHitlHostSurfaceFor(DEFAULT_SESSION_KEY, surface);
-}
-/** W1 带 key 变体:装/卸某会话的 HITL 宿主面(多会话宿主每会话一键,互不顶盖)。 */
-export function installHitlHostSurfaceFor(sessionKey, surface) {
-    const prev = hostSurfaceByKey.get(sessionKey);
-    hostSurfaceByKey.set(sessionKey, surface);
-    return () => {
-        hostSurfaceByKey.set(sessionKey, prev);
-    };
-}
-/** 🔴 宿主自检:恒应为 0。非 0 = 有 HITL 副作用发生时口不在,那一行 warn / 那条记账丢了。 */
-export function hitlHostSurfaceMisses() {
-    return hitlHostSurfaceMissesFor(DEFAULT_SESSION_KEY);
-}
-/** W1 带 key 变体(miss 计数逐键)。 */
-export function hitlHostSurfaceMissesFor(sessionKey) {
-    return hostSurfaceMissesByKey.get(sessionKey) ?? 0;
-}
-/** W1 读端:某会话的 HITL 宿主面(未装 = null;**不计 miss** —— miss 只在副作用真发生时计)。 */
-export function hitlHostSurfaceFor(sessionKey) {
-    return hostSurfaceByKey.get(sessionKey) ?? null;
-}
-/** 测试钩:卸口 + 清计数。 */
-export function _resetHitlHostSurfaceForTest() {
-    hostSurfaceByKey.clear();
-    hostSurfaceMissesByKey.clear();
-}
-function surface() {
-    const hostSurface = hitlHostSurfaceFor(DEFAULT_SESSION_KEY);
-    if (hostSurface === null) {
-        hostSurfaceMissesByKey.set(DEFAULT_SESSION_KEY, (hostSurfaceMissesByKey.get(DEFAULT_SESSION_KEY) ?? 0) + 1);
-    }
-    return hostSurface;
-}
-/**
- * CC `utils/messages.ts` 的 `REJECT_MESSAGE` **逐字**(搬迁差分 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;
-}
-/** 一 turn 内最多循环这么多次 park(防御:引擎/模型病态连环提问时不无限 attach)。 */
-const MAX_GATE_HOPS = 24;
-/** core 对被 gate/连坐 abort 的 call 铸的 tool_end 载体(逐字;desktop session-host 真引擎实测
- *  同款)——HOLD 谓词锚它做**精确等值**,普通工具错的输出是各自错误文案,永不进 HOLD。 */
-export const ENGINE_ABORT_TOOL_RESULT = 'Operation aborted';
-/**
- * 「这个工具名归 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`;
- *   ② 更狠的是紧接着的 `endedCalls.add(toolCallId)` —— resume 后引擎重放的**真** tool_end
- *      被手柄开头的 `if (endedCalls.has(...)) continue` 静默去重,真结果一帧都上不了屏。
- * 附带第三件:deny 腿的 `User rejected …` 文案对 Bash 同样进不去,用户看到的是引擎原文。
- * 证据链见 cli 仓 design/cli-164 T4-A(硬 oracle=磁盘状态:按 Yes 后 printf +504ms 真落盘)。
- */
-/**
- * decide 的 `failed` 原因是不是「这个 gate 早就被解决了」(#110 缺陷② c 的判据)。
- *
- * 判据锚在**语义词**而不是整句:上游改文案是常事,而 `no pending checkpoint` / `resolved` /
- * `already` 三者任一在场就足以把「重放的已决断 park」与真失败(网络断、决断超时、hop 超限)分开。
- * 🔴 方向:这条判**错**的后果不对称 —— 误判成「已解决」最多让流多读一轮(hop 预算兜底),
- * 误判成「真失败」会把一个已经 completed 的 run 谎报成失败并烧掉整条会话转录。所以宁可宽。
- */
-function isAlreadyResolvedGateReason(reason) {
-    if (typeof reason !== 'string')
-        return false;
-    const r = reason.toLowerCase();
-    return r.includes('no pending checkpoint') || r.includes('resolved') || r.includes('already');
-}
-function isGatedToolName(name) {
-    if (isAskTool(name))
-        return true;
-    if (typeof name !== 'string')
-        return false;
-    return toolNameIsFsWrite(name) || toolNameIsShellExec(name);
-}
-function isAskTool(name) {
-    return typeof name === 'string' && name.replace(/[\s_-]+/g, '').toLowerCase() === 'askuserquestion';
-}
-/** done 帧的 AskUserQuestion park 形状(结构性读;别的终态一律 false)。 */
-function isAskGatePark(result) {
-    const r = result;
-    return (!!r &&
-        r.status === 'suspended' &&
-        isAskTool(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 &&
-        !isAskTool(r.checkpointGate?.toolName) &&
-        isToolApprovalGate(r.checkpointGate));
-}
-/** 把 wire 答案({answers:[{header,selected,note?}]})折回 CC 卡片的 Record<question,string> 形状
- *  (multiSelect 与对话框同款 ", " lossy join;note → annotations.notes)。 */
-export function toAnsweredOutput(questions, answer) {
-    const answers = {};
-    const annotations = {};
-    for (const entry of answer.answers ?? []) {
-        const q = questions.find(qq => qq.header === entry.header);
-        const key = typeof q?.question === 'string' ? q.question : entry.header;
-        answers[key] = (entry.selected ?? []).join(', ');
-        if (entry.note)
-            annotations[key] = { notes: entry.note };
-    }
-    return {
-        type: 'ask-user-question',
-        questions,
-        answers,
-        ...(Object.keys(annotations).length > 0 ? { annotations } : {}),
-    };
-}
-// ── 件3(中断事故修复批 G,2026-07-15)—— 中断 deny 的有界观察 ─────────────────────────────────
-/** cancel-by-deny 的后台 settle 预算。decide 是 SYNC 驱动的(引擎跑到下一 park/终态才返,实测
- *  4-5s+),但 DENY-abort 语义上引擎收到即终结 run;2s 内连收都没收到 ⇒ 按丢失警示(晚到成功
- *  只是多一行良性 warn,比锁死无线索诚实)。 */
-export const CANCEL_DENY_BUDGET_MS = 2000;
-/** warn 行文案(测试锁字面)。 */
-export const CANCEL_DENY_WARN_TEXT = 'could not cancel the pending question — the session may stay locked; the run may need engine-side recovery';
-const CANCEL_DENY_WARN_KEY = 'hitl-cancel-deny-warn';
-const CANCEL_DENY_WARN_TIMEOUT_MS = 10_000;
-/** 失败 warn 上屏:借 footer notifications 通道。壳原文经 `appStateRef` 直写 store
- *  (immediate 语义:立即顶到 current + 到点自清「仅当仍是本 warn 时」);本包把那两次
- *  setState 拆成宿主口的两个动词,**时序纪律(2s 预算 / 10s 自清)留在库内**——
- *  [paired-mechanisms-must-share-premise]:只给「显示」不给「清」,端各写各的清法必然漂。
- *  无口(print/headless 没屏可上)⇒ 静默,与壳原文 `if (!store) return` 同语义。 */
-function surfaceCancelDenyWarn() {
-    try {
-        const s = surface();
-        if (!s)
-            return;
-        s.showNotice({
-            key: CANCEL_DENY_WARN_KEY,
-            text: CANCEL_DENY_WARN_TEXT,
-            color: 'warning',
-            priority: 'immediate',
-            timeoutMs: CANCEL_DENY_WARN_TIMEOUT_MS,
-        });
-        const timer = setTimeout(() => {
-            try {
-                s.clearNoticeIfCurrent(CANCEL_DENY_WARN_KEY);
-            }
-            catch {
-                /* fail-soft */
-            }
-        }, CANCEL_DENY_WARN_TIMEOUT_MS);
-        timer.unref?.();
-    }
-    catch {
-        /* fail-soft:上屏失败绝不再伤害 abort 流 */
-    }
-}
-/**
- * 中断 deny 的有界观察(壳侧单测 `hitlCancelDeny.test.ts` 的被测面)。
- * 铁律:不 await 进 abort 返回路径(用户立即拿回控制);这里只管后台 settle 的«观察»:
- *   - 2s 内 settle 成功 ⇒ 零上屏(SEMA_DEBUG 记成功);
- *   - 失败/超时 ⇒ 上屏一行 warn + SEMA_DEBUG 记原因(deny 丢失 = run 卡 suspended,下一条消息
- *     撞 409;配合件2b 的专属文案,用户知道现场 + 出路);
- *   - HitlSafetyError code==='no_pending' ⇒ 良性静默(pending 已被别处消解/过期 —— run 没锁;
- *     hitlBridge decideTool 的同款语义,那里的静默维持不动)。
- */
-export function observeCancelByDeny(settle, taskId) {
-    let timer;
-    const budget = new Promise((_, reject) => {
-        timer = setTimeout(() => reject(new Error(`cancel-by-deny did not settle within ${CANCEL_DENY_BUDGET_MS}ms`)), CANCEL_DENY_BUDGET_MS);
-        timer.unref?.();
-    });
-    void Promise.race([settle, budget])
-        .then(() => {
-        hostLog('debug', `[hitl-ask] cancel-by-deny settled for run ${taskId} (session unlocked)`);
-    })
-        .catch((e) => {
-        // ⚠️ 这里的 `.code` 是 **client-core 自家 HitlSafetyError 的契约属性**(hitlBridge.ts,词表
-        // binding_mismatch|no_pending|wrong_gate|bad_plan_edit)—— 不是 SDK 错误的 `errorCode`。
-        // 2026-07-30 `.code` 普查曾把本处误判成 SDK 属性名病改成 errorCode,pure 门 B7 腿当场拦下
-        // (反向修复);判 `.code` 读点的病与否,先看**谁抛的**,别按属性名模式匹配。
-        if (e?.code === 'no_pending') {
-            hostLog('debug', `[hitl-ask] cancel-by-deny no_pending for run ${taskId} (benign — already resolved)`);
-            return;
-        }
-        hostLog('error', `[hitl-ask] cancel-by-deny FAILED for run ${taskId}: ${String(e)}`);
-        surfaceCancelDenyWarn();
-    })
-        .finally(() => {
-        if (timer !== undefined)
-            clearTimeout(timer);
-    });
-    // 超时后原 promise 迟到 reject 不得变成 unhandledRejection。
-    void settle.catch(() => { });
-}
-/**
- * 弹既有 AskUserQuestion overlay → 等作答 → 经 HitlBridge decide(答案/拒答)。
- * decide 成功即引擎已把 run 驱到下一状态(sync);调用方随后 attach runs.events 续流。
- */
-async function surfaceGateAndDecide(deps, taskId, askArgsByCall, signal) {
-    if (!hasQuestionOverlay()) {
-        return { kind: 'failed', reason: 'no question overlay mounted (print/non-REPL mode)' };
-    }
-    // pending 行 = 问题 payload 的权威源 + D-1 绑定的唯一 surface(PendingCheckpoint.input)。
-    let pending;
-    try {
-        const rows = (await deps.client.approvals.list(signal ? { signal } : undefined)).pending;
-        pending =
-            rows.find(r => r.taskId === taskId && isAskTool(r.toolName ?? undefined)) ??
-                rows.find(r => r.taskId === taskId);
-    }
-    catch (e) {
-        return { kind: 'failed', reason: `approvals.list failed: ${String(e)}` };
-    }
-    if (!pending)
-        return { kind: 'failed', reason: 'no pending checkpoint for this run (resolved/expired?)' };
-    const gatedCallId = pending.toolCallId ?? pending.boundCallId ?? undefined;
-    // 问题 payload:优先流上 tool_start.args(零额外语义),缺则 pending.input(service 已 redact + 限长)。
-    const fromArgs = gatedCallId
-        ? askArgsByCall.get(gatedCallId)?.questions
-        : undefined;
-    const fromPending = pending.input?.questions;
-    const questions = Array.isArray(fromArgs) && fromArgs.length > 0 ? fromArgs : fromPending;
-    if (!Array.isArray(questions) || questions.length === 0) {
-        // [1543]②:input 超引擎入参帽(MAX_TOOL_INPUT_CHARS,preview 富文本题易中)时 server 降级为
-        // {truncated:true} ——无题可渲不是引擎代差,是 payload 被截。分形出诚实理由(fail-soft 链
-        // 会把 reason 记入 SEMA_DEBUG,别再误导成 pre-CHANNEL[56] 老引擎)。
-        const truncated = pending.input?.truncated === true;
-        return {
-            kind: 'failed',
-            gatedCallId,
-            reason: truncated
-                ? 'question payload exceeded the engine input cap (input={truncated:true}) — dialog cannot be re-rendered; run stays suspended for out-of-band decide'
-                : 'gate has no question payload (pre-CHANNEL[56] engine?)',
-        };
-    }
-    // overlay 往返:合成 frame(id 独占命名空间 hitl-ask:)→ local responder 一次性收答。
-    const questionId = `hitl-ask:${gatedCallId ?? taskId}`;
-    const answer = await new Promise(resolve => {
-        const unregister = registerLocalQuestionResponder(questionId, async (_id, a) => {
-            cleanup();
-            resolve(a);
-            return { ok: true };
-        });
-        const onAbort = () => {
-            cleanup();
-            // 撤下还开着的对话框(question_complete = overlay 的既有 dismiss 语义)
-            publishQuestionFrame({ type: 'question_complete', questionId });
-            resolve(null);
-        };
-        const cleanup = () => {
-            unregister();
-            signal?.removeEventListener('abort', onAbort);
-        };
-        if (signal?.aborted) {
-            onAbort();
-            return;
-        }
-        signal?.addEventListener('abort', onAbort, { once: true });
-        publishQuestionFrame({ type: 'question', questionId, questions });
-    });
-    const bridge = new HitlBridge(deps.client, taskId);
-    if (answer === null) {
-        // turn 被中断(Esc/Ctrl+C):cancel-by-deny(contract/04 §2.4 —— suspended run 不 runs.cancel)。
-        // 件3(中断事故修复批 G,2026-07-15,症状1 壳侧配套):此前 .catch(()=>{}) 全吞 = deny 丢失时
-        // run 永卡 suspended,session 锁死,用户下一条消息撞 409「active run」还全无线索。改为有界观察
-        // (observeCancelByDeny,2s 预算):abort 仍立即返回用户控制(不 await,交互时序不变),后台
-        // settle 失败/超时上屏一行 warn + SEMA_DEBUG 记失败原因。引擎侧解锁腿([866] server:cancel
-        // suspended 改语义 + reapSuspended TTL)到货前,这是壳能做的最诚实半场。
-        observeCancelByDeny(bridge.decideTool({ decision: 'deny', reason: 'Interrupted by user' }, gatedCallId), taskId);
-        return { kind: 'aborted', gatedCallId };
-    }
-    try {
-        const entries = (answer.answers ?? []);
-        const hasContent = entries.some(a => (a.selected?.length ?? 0) > 0 || (a.note?.length ?? 0) > 0);
-        if (hasContent) {
-            await bridge.answerQuestion(entries, gatedCallId, signal ? { signal } : undefined);
-            return { kind: 'decided', gatedCallId, answered: toAnsweredOutput(questions, answer) };
-        }
-        else {
-            // 用户拒答(overlay reject/dismiss 送空 answers)= 诚实 deny;模型收 denied 结果自续。
-            await bridge.decideTool({ decision: 'deny', reason: 'User declined to answer' }, gatedCallId, signal ? { signal } : undefined);
-        }
-        return { kind: 'decided', gatedCallId };
-    }
-    catch (e) {
-        return { kind: 'failed', gatedCallId, reason: `decide failed: ${String(e)}` };
-    }
-}
+import { createGateLedger } from './gateLedger.js';
+import { isHostProgressFrame, routeFrame, } from './frameRouter.js';
+import { resolvePark } from './parkResolver.js';
+// ── 宿主面口(搬迁差分 3)────────────────────────────────────────────────────────────────────
+//
+// 壳里这三件都是 `getAppStateStoreRef()` 直写 `AppState` + `require('../utils/autoModeDenials.js')`。
+// `AppState.notifications` 与 Recent Denials 面板都是**端的状态形状**(web/桌面各有各的通知系统),
+// 所以做成口。🔴 缺席 = 那一行 warn 不上屏 —— 壳原文在无 provider(print/headless)时**本来就是
+// 静默**(`if (!store) return`),所以缺席语义与原文一致;但**漏装**与「真的没屏」看起来一样,
+// 于是计 miss(`hitlHostSurfaceMisses()` 宿主自检恒应为 0)。
+// REF-CC-023(2026-08-02,P3 wave2 卡C-bridge):口本体(`HitlHostSurface` 接口 / install·misses·for
+// 读写口 / `surfaceForCurrentSession`)与 cancel-by-deny 有界观察(`observeCancelByDeny`)
+// 已整条搬进 `./hitlHostSurface.js` —— `toolApprovalWire.ts` 的中断-deny 臂也要用同一份观察器,
+// 而 `toolApprovalWire.ts` 是本文件的上游 import,反向 import 会成环;单源到一个两边都能到达的
+// 独立模块解环。REF-CC-032 之后这两处的消费点在 `frameRouter.ts` / `parkResolver.ts`。
+// ── 公开面(REF-CC-032 三刀后原位 re-export;`index.ts` 的 `export *` 经本文件出去)──────────
+//
+// 🔴 名字与语义一个都没动:值四个(`HITL_REJECT_MESSAGE` / `ENGINE_ABORT_TOOL_RESULT` /
+//    `toAnsweredOutput` / 下方 `bridgeAskUserQuestionGates`)、类型四个。定义搬去了实现所在的
+//    那一刀,本文件是它们对外的**唯一门牌**——下游 import 路径不变,public-export 基线不变。
+export { HITL_REJECT_MESSAGE, ENGINE_ABORT_TOOL_RESULT } from './frameRouter.js';
+export { toAnsweredOutput, isAlreadyResolvedGateReason } from './parkResolver.js';
 /**
  * 包一层 AgentEvent 流:把 AskUserQuestion 的 suspended park 变成「对话框 → decide → 续流」闭环。
  * 其它事件原样透传;非 AskUserQuestion 的 gate 保持现状。fail-soft:任何桥内失败回退为
  * 「flush 毒化 tool_end + 原样终帧」(= 修复前行为)。
  *
+ * 双层循环(REF-CC-032 后只剩驱动骨架):
+ *   · 内环 `for await` 读流 —— 每帧先记 seq、再判扣留帧放行、再交 `routeFrame` 定处置;
+ *     `park` 动作 break 出内环。
+ *   · 外环 `while` —— `resolvePark` 决断:`reattach` 就换一条 `runs.events` 流接着读
+ *     (hop 预算在 resolver 内按 `hops` 判),`failsoft` 就吐完 events 收场。
+ *
  * @param source 上游 AgentEvent 流(tasks.stream 或 runs.events,已过 demuxQuestionFrames)。
  * @param opts.taskId runs.events 消费时已知的 run handle(sync leg 从 suspended done 捕获)。
  */
 export async function* bridgeAskUserQuestionGates(source, deps, opts) {
-    const startedCalls = new Set();
-    const endedCalls = new Set();
-    /** park 毒化的 gated tool_end(isError:true "Operation aborted")——HOLD 到 gate 定性
-     *  (AskUserQuestion + [816] 放宽后的 fs 写工具)。 */
-    const heldAskEnds = new Map();
-    /** gated 工具的 tool_start.args(toolCallId → args)= 对话框/三选卡 payload 的一手源。 */
-    const askArgsByCall = new Map();
-    /** 三选卡 deny 过的 call:重放 tool_end 的 render 面 stamp REJECT_MESSAGE(vendored
-     *  renderToolUseRejectedMessage 渲 `User rejected <op> to <path>`,CC 逐字)。 */
-    const deniedCalls = new Set();
-    /** started-未-ended 的 fs 写 call(顺序保留)——同步 tool_approval 帧的 callId 关联面
-     *  (帧契约不带 toolCallId;引擎阻塞在帧上,最后一张未收口 fs 写 call 即被 gate 的 call)。 */
-    const pendingFsCalls = [];
-    /** 同步帧腿 deny 但 callId 关联不上(引擎在 tool_start 前出帧的形状):stamp 下一张 fs 写报错帧。 */
-    let denyStampNextFsEnd = false;
-    /** 已作答的 gate(toolCallId → CC 卡片形状的真实答案)——续流重放的解答 tool_end 无 output,
-     *  不补就会渲成结果不可用;这里 stamp `structured` 让卡片渲真实选择。 */
-    const resolvedAnswers = new Map();
-    let lastSeq;
-    /**
-     * 已经决断过的 gate 身份(#110 缺陷② 的**承重**修,2026-08-02)。
-     *
-     * durable re-attach 会把「已经决断过的 park」重放一遍(边界上必然发生:`lastEventId` 再准也
-     * 只能精确到帧,park 帧本身就在续流的重放窗口里)。重放的 park 走到下面会去
-     * `surfaceFsApprovalAndDecide` 取 pending approval —— 那一行早已 resolved ⇒ 拿不到 ⇒
-     * `failed` ⇒ 合成 `hitl_unanswered` 终帧。而引擎侧 run 其实已经 `completed`:壳谎报失败,
-     * 连带 CC 转录 0 行写出、同 session `--resume` 报 `No conversation found` —— **会话废掉**。
-     * 与 `startedCalls`/`endedCalls` 同款的身份去重是这条的正解:决断过的 gate 不再决断第二次。
-     */
-    const decidedGates = new Set();
-    let realTaskId = opts?.taskId;
+    const led = createGateLedger();
+    const taskId = { current: opts?.taskId };
+    const ctx = {
+        led,
+        deps,
+        taskId,
+        ...(opts?.signal ? { signal: opts.signal } : {}),
+    };
     let stream = source;
     let hops = 0;
-    function* flushHeld() {
-        for (const [callId, held] of heldAskEnds) {
-            endedCalls.add(callId);
-            yield held;
-        }
-        heldAskEnds.clear();
-    }
     while (true) {
-        /** park 请求:遇 AskUserQuestion / fs 写权限 gate 时置位后 break 内环。 */
+        /** park 请求:遇 AskUserQuestion / 工具审批 gate 时置位后 break 内环。 */
         let park = null;
         for await (const ev of stream) {
-            // #110 缺陷② a:`lastSeq` 要跟得上**已消费的最大 seq**。durable `runs.events` 流上并非每帧
-            // 都带 `id`(数字 `seq` 位的帧同样在场),旧式只吃 `ev.id` ⇒ 停在最后一个带 id 的帧上 ⇒
-            // re-attach 从一个陈旧位置重放,把已经决断的 park 又送一遍(实测:消费到 16 却 attach from 8)。
-            const rawSeq = ev.id ?? ev.seq;
-            if (typeof rawSeq === 'string' && rawSeq.length > 0)
-                lastSeq = rawSeq;
-            else if (typeof rawSeq === 'number' && Number.isFinite(rawSeq))
-                lastSeq = String(rawSeq);
-            // ── [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 的 endedCalls 记账让 decide 后重放的解答帧被当已收口丢弃
-            // (真实答案卡永不出现)。代价 = turn 末尾无后续推进帧的 abort 形帧等到终帧 flush,与修前同。
-            // parentToolCallId 在场 = sub-agent 行帧,park 期间孙代照常说话,不算 host 推进(负控①C)。
-            // (普通工具错自 [2084]①-b 谓词收窄后根本不进 HOLD,零滞后不依赖本触发集。)
-            if (heldAskEnds.size > 0 &&
-                (ev.type === 'text_delta' || ev.type === 'reasoning_delta' || ev.type === 'tool_start') &&
-                ev.parentToolCallId === undefined) {
-                yield* flushHeld();
-            }
-            // ── server 1.191 同步帧腿([830]①):`tool_approval` 帧 → 三选卡 → respond ────────────────
-            // 引擎此刻同步阻塞在帧上(fail-closed:无 respond/TTL 5min/abort ⇒ deny),await 卡决断安全。
-            // 帧是 HITL 词汇非 AgentEvent arm——两种帧都不外泄到渲染管道。
-            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;
-                if (frame.type === 'tool_approval_complete')
-                    continue; // 收口帧:卡已由决断路径撤下,吞掉
-                if (!deps.respondToolApproval) {
-                    hostLog('debug', `liveHitlAskWire: tool_approval frame ${frame.approvalId} but no respond wire — engine self-settles (TTL deny)`);
-                    continue;
-                }
-                // 补验批 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 (isAskTool(ev.toolName)) {
-                    try {
-                        await deps.respondToolApproval(frame.approvalId, 'allow', {
-                            ...(opts?.signal && !opts.signal.aborted ? { signal: opts.signal } : {}),
-                        });
-                        hostLog('debug', `liveHitlAskWire: ask-tool approval frame ${frame.approvalId} → allow(问题门放行,候 park 弹卡)`);
-                    }
-                    catch (e) {
-                        hostLog('debug', `liveHitlAskWire: ask-tool approval allow failed for ${frame.approvalId}: ${String(e)} — engine self-settles (TTL)`);
-                    }
-                    continue;
-                }
-                // [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 ${frame.approvalId} tool=${String(ev.toolName)}${fromSubagent ? ` from-subagent=${String(ev.sourceTaskId ?? ev.sourceAgentName ?? 'explicit')}` : ''}`);
-                const gatedCallId = !fromSubagent && pendingFsCalls.length > 0 ? pendingFsCalls[pendingFsCalls.length - 1] : undefined;
-                const decision = await surfaceToolApprovalFrameAndRespond(ev, deps.respondToolApproval, gatedCallId !== undefined ? askArgsByCall.get(gatedCallId) : undefined, opts?.signal);
-                if (decision === 'deny' && !fromSubagent) {
-                    // 该 call 的报错收口帧 stamp REJECT 文案(vendored `User rejected <op> to <path>` 卡)。
-                    if (gatedCallId !== undefined)
-                        deniedCalls.add(gatedCallId);
-                    else
-                        denyStampNextFsEnd = true;
-                }
+            led.noteSeq(ev);
+            // HOLD 只护 park 窗口:host lane 的模型推进帧一到就放行扣留帧(触发集的来龙去脉见
+            // `frameRouter.isHostProgressFrame` 上方长注)。
+            if (led.heldCount() > 0 && isHostProgressFrame(ev))
+                yield* led.flushHeld();
+            const action = await routeFrame(ev, ctx);
+            if (action.kind === 'skip')
                 continue;
-            }
-            if (ev.type === 'tool_start' && typeof ev.toolCallId === 'string') {
-                if (startedCalls.has(ev.toolCallId))
-                    continue; // durable 重放的已渲 call
-                startedCalls.add(ev.toolCallId);
-                if (isGatedToolName(ev.toolName)) {
-                    // #110:Bash 也要记 args —— 卡片渲染要拿到 `command`,不记则 shell gate 的卡面空着。
-                    askArgsByCall.set(ev.toolCallId, ev.args);
-                    if (typeof ev.toolName === 'string' && toolNameIsFsWrite(ev.toolName)) {
-                        pendingFsCalls.push(ev.toolCallId);
-                    }
-                }
-                yield ev;
+            if (action.kind === 'yield') {
+                for (const out of action.events)
+                    yield out;
                 continue;
             }
-            if (ev.type === 'tool_end' && typeof ev.toolCallId === 'string') {
-                if (endedCalls.has(ev.toolCallId))
-                    continue; // durable 重放/park 复写的已收口 call
-                {
-                    const pi = pendingFsCalls.indexOf(ev.toolCallId);
-                    if (pi !== -1)
-                        pendingFsCalls.splice(pi, 1);
-                }
-                // ── 分类器批3([907]):auto-mode 分类器 deny 裁决帧 —— 结构性识别(core 机器签名)优先于
-                // fs HOLD/REJECT 分支(签名比"fs 写报错"更特定;分类器 deny 从不产 tool_approval 帧,
-                // deniedCalls/denyStampNextFsEnd 与之互斥)。副作用 = CC 207 通知行 + Recent Denials 记账;
-                // render 面 stamp 去 system-reminder 包裹渲裁决原文(render-only,模型面原文不动)。
-                if (ev.isError === true && !deniedCalls.has(ev.toolCallId)) {
-                    const verdict = classifierDenyFromToolEnd(ev);
-                    if (verdict) {
-                        endedCalls.add(ev.toolCallId);
-                        heldAskEnds.delete(ev.toolCallId);
-                        surface()?.surfaceClassifierDeny(typeof ev.toolName === 'string' ? ev.toolName : 'tool', verdict);
-                        hostLog('debug', `liveHitlAskWire: classifier deny verdict on ${ev.toolCallId} (${String(ev.toolName)}) — labeled render + notice`);
-                        yield { ...ev, output: verdict.message, structured: undefined };
-                        continue;
-                    }
-                }
-                if (ev.isError === true &&
-                    // #110:同步帧腿 deny 的 stamp 也要盖 shell —— 否则按 No 时用户看到的是引擎原文
-                    // `Operation aborted` 而不是 CC 的 `User rejected …`。
-                    isGatedToolName(ev.toolName) &&
-                    denyStampNextFsEnd &&
-                    !deniedCalls.has(ev.toolCallId)) {
-                    // 同步帧腿 deny 且 callId 没关联上:下一张 fs 写报错帧即该 gate 的收口帧,stamp REJECT 文案。
-                    denyStampNextFsEnd = false;
-                    endedCalls.add(ev.toolCallId);
-                    heldAskEnds.delete(ev.toolCallId);
-                    yield { ...ev, output: rejectMessageForRender(), structured: undefined };
-                    continue;
-                }
-                if (ev.isError === true && isGatedToolName(ev.toolName)) {
-                    if (deniedCalls.has(ev.toolCallId)) {
-                        // 三选卡 No:重放的报错帧 stamp REJECT 文案 → vendored 卡渲 `User rejected <op> to <path>`。
-                        deniedCalls.delete(ev.toolCallId);
-                        endedCalls.add(ev.toolCallId);
-                        heldAskEnds.delete(ev.toolCallId);
-                        yield { ...ev, output: rejectMessageForRender(), structured: undefined };
-                        continue;
-                    }
-                    // [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**——收窄后它们零滞后直达转录,不再依赖「推进信号放行」。
-                    if (ev.output === ENGINE_ABORT_TOOL_RESULT) {
-                        heldAskEnds.set(ev.toolCallId, ev); // park 毒化帧,先 HOLD(gate 定性前不渲 Error 卡)
-                        continue;
-                    }
-                    // 普通失败:落到下方通用收口路径,立即上屏。
-                }
-                endedCalls.add(ev.toolCallId);
-                heldAskEnds.delete(ev.toolCallId); // 正常收口(重放的 isError:false 解答帧)赢
-                const answered = resolvedAnswers.get(ev.toolCallId);
-                if (answered &&
-                    ev.isError !== true &&
-                    ev.structured === undefined) {
-                    resolvedAnswers.delete(ev.toolCallId);
-                    yield { ...ev, structured: answered }; // 真实答案卡(见 resolvedAnswers 注)
-                }
-                else {
-                    yield ev;
-                }
-                continue;
-            }
-            if (ev.type === 'suspended') {
-                // durable leg 的 park arm(续流中模型再次提问/再次撞写权限)。gate 只带 kind/toolName,
-                // payload 走 approvals。
-                if (ev.gate && isAskTool(ev.gate.toolName) && realTaskId) {
-                    park = { gate: 'ask' };
-                    break;
-                }
-                if (ev.gate && isToolApprovalGate(ev.gate) && realTaskId) {
-                    park = { gate: 'fs' };
-                    break;
-                }
-                yield ev; // 其余 gate:透传(现状,eventToSdkMessage 出 null)
-                continue;
-            }
-            if (ev.type === 'done') {
-                if (isAskGatePark(ev.result)) {
-                    realTaskId = realTaskId ?? ev.result.taskId;
-                    park = { pendingDone: ev, gate: 'ask' };
-                    break;
-                }
-                if (isFsApprovalPark(ev.result)) {
-                    realTaskId = realTaskId ?? ev.result.taskId;
-                    park = { pendingDone: ev, gate: 'fs' };
-                    break;
-                }
-                yield* flushHeld(); // 真错(非 gate)的 Ask tool_end 此刻诚实渲染
-                // durable 终帧的 result.taskId === sessionId(引擎 durable quirk)会让 captureSessionId 跳过
-                // rewind 绑定 —— 用 sync leg 捕的真 handle 修正回去。
-                const r = ev.result;
-                if (realTaskId && r && r.taskId === r.sessionId && r.taskId !== realTaskId) {
-                    yield { ...ev, result: { ...ev.result, taskId: realTaskId } };
-                }
-                else {
-                    yield ev;
-                }
-                return;
-            }
-            if (ev.type === 'failed') {
-                yield* flushHeld();
-                yield ev;
+            if (action.kind === 'end') {
+                for (const out of action.events)
+                    yield out;
                 return;
             }
-            yield ev;
+            park = {
+                gate: action.gate,
+                ...(action.pendingDone !== undefined ? { pendingDone: action.pendingDone } : {}),
+            };
+            break;
         }
         if (!park) {
             // 源流走完没终帧(disconnect/abort)——flush 后结束,与现状一致。
-            yield* flushHeld();
+            yield* led.flushHeld();
             return;
         }
         hops++;
-        let outcome;
-        if (hops > MAX_GATE_HOPS) {
-            outcome = { kind: 'failed', reason: `gate hop limit (${MAX_GATE_HOPS}) exceeded` };
-        }
-        else if (park.gate === 'fs') {
-            // [816] 放宽腿:fs 写权限 gate → CC 三选卡(vendored PermissionRequest)→ decide。
-            outcome = await surfaceFsApprovalAndDecide({ client: deps.client }, realTaskId, askArgsByCall, opts?.signal);
-            // #51: `outcome`'s declared type is the wider `GateOutcome |
-            // FsApprovalOutcome`; both unions share a 'decided' kind with
-            // different optional fields (`answered` vs `denied`), so a plain
-            // `.denied` access doesn't hold for every 'decided' member even
-            // though this branch only ever assigns the FsApprovalOutcome shape.
-            // 'in' narrowing sidesteps it.
-            const outcomeDenied = 'denied' in outcome ? outcome.denied : undefined;
-            if (outcome.kind === 'decided' && outcomeDenied === true && outcome.gatedCallId) {
-                deniedCalls.add(outcome.gatedCallId); // 重放的报错帧渲 `User rejected …`(见 tool_end 手柄)
-            }
-        }
-        else {
-            outcome = await surfaceGateAndDecide(deps, realTaskId, askArgsByCall, opts?.signal);
-        }
-        // #110 缺陷② b/c —— **重放的、早已决断过的 park 不是失败**。
-        // durable re-attach 必然会把 park 帧再送一遍(`lastEventId` 再准也只能精确到帧,park 就在
-        // 重放窗口里)。这时 approval 行早已 resolved,`surfaceFsApprovalAndDecide` 取不到 pending,
-        // 返回 `failed: no pending checkpoint for this run (resolved/expired?)` —— 那句话的语义恰恰是
-        // **「这个 gate 已经被解决了」**,正确处置是**继续读流**(引擎那边 run 正常往下跑,实测
-        // `run.json status="completed"`),而不是宣布 turn 失败。旧行为的代价不是一句错文案:
-        // 终帧被投影成 `error_during_execution` ⇒ 壳走失败路径 ⇒ CC 转录**一行都不写** ⇒
-        // 同 session `--resume` 报 `No conversation found` ⇒ **整个会话废掉**。
-        // 无限循环由 `hops > MAX_GATE_HOPS` 兜底(本 continue 照常吃 hop 预算,不绕过它)。
-        if (outcome.kind === 'failed' && isAlreadyResolvedGateReason(outcome.reason)) {
-            hostLog('debug', `liveHitlAskWire: gate already resolved (${outcome.reason}) — replayed park, re-attaching runs.events(${realTaskId})${lastSeq ? ` from seq ${lastSeq}` : ''} instead of failing the turn` +
-                (decidedGates.size > 0 ? ` [decided so far: ${decidedGates.size}]` : ''));
-            stream = deps.runsEvents(realTaskId, {
-                ...(lastSeq !== undefined ? { lastEventId: lastSeq } : {}),
-                ...(opts?.signal ? { signal: opts.signal } : {}),
-            });
-            continue;
-        }
-        if (outcome.kind !== 'decided') {
-            hostLog('debug', `liveHitlAskWire: gate not decided (${outcome.kind}${'reason' in outcome ? `: ${outcome.reason}` : ''}) — fail-soft to suspended terminal`);
-            yield* flushHeld(); // 回退:毒化帧照旧渲染(= 修复前的诚实红)
-            if (park.pendingDone) {
-                yield park.pendingDone;
-            }
-            else if (outcome.kind === 'failed') {
-                // 记案(#87 评审② minor,不修):durable re-attach 的第二问(park.pendingDone 无)走 `aborted`
-                // 时(仅用户主动 Esc/Ctrl+C 中断触发)不吐终帧——下游正在拆流,合成终帧也没人渲;flushHeld
-                // 已把毒化帧诚实吐出。真正的 failed 才合成下面的可见终帧。
-                // durable-leg park 无 done 可回吐 —— 合成 failed 让用户看得见为什么停了
-                yield {
-                    type: 'failed',
-                    errorCode: 'hitl_unanswered',
-                    errorMessage: `${park.gate === 'fs' ? 'Tool approval' : 'AskUserQuestion'} gate could not be answered: ${outcome.reason}`,
-                };
-            }
+        const resolution = await resolvePark(park, {
+            deps,
+            led,
+            taskId: taskId.current,
+            hops,
+            ...(opts?.signal ? { signal: opts.signal } : {}),
+        });
+        if (resolution.kind === 'failsoft') {
+            for (const out of resolution.events)
+                yield out;
             return;
         }
-        // decide 成功:丢弃该 call 的毒化 HOLD(续流重放会带 isError:false 的解答帧收口卡片),
-        // 并记下真实答案供该解答帧 stamp `structured`(否则卡片渲成结果不可用)。
-        if (outcome.gatedCallId) {
-            heldAskEnds.delete(outcome.gatedCallId);
-            decidedGates.add(outcome.gatedCallId); // #110 缺陷② b:决断过的 gate 身份留痕(诊断面)
-            if ('answered' in outcome && outcome.answered)
-                resolvedAnswers.set(outcome.gatedCallId, outcome.answered);
-        }
-        hostLog('debug', `liveHitlAskWire: gate decided (call ${outcome.gatedCallId ?? '?'}) — attaching runs.events(${realTaskId})${lastSeq ? ` from seq ${lastSeq}` : ''}`);
-        stream = deps.runsEvents(realTaskId, {
-            ...(lastSeq !== undefined ? { lastEventId: lastSeq } : {}),
+        const seq = led.lastSeq();
+        stream = deps.runsEvents(taskId.current, {
+            ...(seq !== undefined ? { lastEventId: seq } : {}),
             ...(opts?.signal ? { signal: opts.signal } : {}),
         });
     }