@sema-agent/client-core 0.12.2 → 0.14.0

package/dist/hitl/hitlHostSurface.js

@@ -0,0 +1,155 @@
+/**
+ * hitlHostSurface.ts — REF-CC-023(2026-08-02,P3 wave2 卡C-bridge):共享的 HITL 宿主通知面
+ * + cancel-by-deny 有界观察,从 `askGateWire.ts` 提出来给 `toolApprovalWire.ts` 也用。
+ *
+ * 🔴 为什么要提出来(不是顺手重排):`askGateWire.ts` 已经 `import` `toolApprovalWire.ts`(§ ask 桥
+ * 消费工具审批帧判定),反向 `toolApprovalWire.ts` → `askGateWire.ts` 会成环。`observeCancelByDeny`
+ * 曾经只活在 `askGateWire.ts` 里,而 `toolApprovalWire.ts:surfaceFsApprovalAndDecide` 的中断-deny
+ * 臂原样复刻了它要修的那个事故(件3,中断事故修复批 G,2026-07-15):裸 `.catch(()=>{})` 全吞 ⇒
+ * deny 丢失时 run 永卡 suspended、session 锁死,用户下一条消息撞 409「active run」还全无线索。
+ * 单源到一个两边都能 import 的模块,两条腿共用同一次修复,而不是「同一个仓、同一个事故、
+ * 一处修了另一处原样留着」。
+ *
+ * 这个模块也顺带带走了 `surfaceCancelDenyWarn` 唯一依赖的宿主通知面(`HitlHostSurface` /
+ * `installHitlHostSurface*` / `hitlHostSurfaceFor*`)—— 它不只是给 cancel-by-deny 用(分类器 deny
+ * 的端侧记账 `surfaceClassifierDeny` 也走它),`askGateWire.ts` 仍然是它的主要消费方,只是不再是
+ * 唯一持有方。
+ */
+import { createSessionSlot, DEFAULT_SESSION_KEY } from '../sessionSlot.js';
+import { hostLog } from '../host.js';
+import { unrefTimer } from '../unrefTimer.js';
+import { HitlSafetyError } from './hitlBridge.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();
+}
+/** 内部读点(计 miss)。`askGateWire.ts` 的 `surfaceClassifierDeny` 路径与本文件的
+ *  `surfaceCancelDenyWarn` 共用它。 */
+export function surfaceForCurrentSession() {
+    const hostSurface = hitlHostSurfaceFor(DEFAULT_SESSION_KEY);
+    if (hostSurface === null) {
+        hostSurfaceMissesByKey.set(DEFAULT_SESSION_KEY, (hostSurfaceMissesByKey.get(DEFAULT_SESSION_KEY) ?? 0) + 1);
+    }
+    return hostSurface;
+}
+// ── 件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 = surfaceForCurrentSession();
+        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);
+        unrefTimer(timer);
+    }
+    catch {
+        /* fail-soft:上屏失败绝不再伤害 abort 流 */
+    }
+}
+/**
+ * cancel-by-deny 的「良性 no_pending」判据。**结构化 `.code` 为主,`instanceof` 只作加强,绝不替代**:
+ *  - `.code` 是 client-core 自家 `HitlSafetyError` 的契约属性(hitlBridge.ts,REF-CC-036 起是闭集
+ *    联合 binding_mismatch|no_pending|wrong_gate|bad_plan_edit)—— 不是 SDK 错误的 `errorCode`;
+ *  - 只按 `instanceof` 判会在**跨 realm / 双实例**下假阴:打包后同一个包出现两份副本(本仓
+ *    `singleton-manifest.json` 把双实例当在册风险处理)、或宿主与包各持一份构造器时,同一个
+ *    语义错误 `instanceof` 为假 ⇒ 良性 no_pending 被当成「deny 丢失」弹一行吓人的 warn;
+ *  - 下游 `sema-cli` 的 `src/sema/hitlCancelDeny.test.ts` 用例 3 正是按 `code + name` 鸭子形造错,
+ *    那份契约就是「结构判据」本身。
+ * ⚠️ 判据不许松成「有 `.code` 就静默」—— 闭集里只有 `no_pending` 是良性,别的 code 照走 warn 臂。
+ */
+function isNoPendingError(e) {
+    if (e instanceof HitlSafetyError)
+        return e.code === 'no_pending';
+    if (typeof e !== 'object' || e === null || !('code' in e))
+        return false;
+    const code = e.code;
+    return typeof code === 'string' && code === 'no_pending';
+}
+/**
+ * 中断 deny 的有界观察(壳侧单测 `hitlCancelDeny.test.ts` 的被测面;REF-CC-023 起两条决断腿共用)。
+ * 铁律:不 await 进 abort 返回路径(用户立即拿回控制);这里只管后台 settle 的«观察»:
+ *   - 2s 内 settle 成功 ⇒ 零上屏(SEMA_DEBUG 记成功);
+ *   - 失败/超时 ⇒ 上屏一行 warn + SEMA_DEBUG 记原因(deny 丢失 = run 卡 suspended,下一条消息
+ *     撞 409;配合件2b 的专属文案,用户知道现场 + 出路);
+ *   - `code === 'no_pending'`(判据见上方 `isNoPendingError`)⇒ 良性静默(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);
+        unrefTimer(timer);
+    });
+    void Promise.race([settle, budget])
+        .then(() => {
+        hostLog('debug', `[hitl-cancel-deny] cancel-by-deny settled for run ${taskId} (session unlocked)`);
+    })
+        .catch((e) => {
+        if (isNoPendingError(e)) {
+            hostLog('debug', `[hitl-cancel-deny] cancel-by-deny no_pending for run ${taskId} (benign — already resolved)`);
+            return;
+        }
+        hostLog('error', `[hitl-cancel-deny] cancel-by-deny FAILED for run ${taskId}: ${String(e)}`);
+        surfaceCancelDenyWarn();
+    })
+        .finally(() => {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    });
+    // 超时后原 promise 迟到 reject 不得变成 unhandledRejection。
+    void settle.catch(() => { });
+}

package/dist/hitl/parkResolver.d.ts

@@ -0,0 +1,74 @@
+/**
+ * parkResolver — HITL gate 桥**外环**的 park 决断(REF-CC-032 / SPLIT-12 第三刀,2026-08-02)。
+ *
+ * 内环(`frameRouter.ts`)带出一个 `GatePark` 之后,这里回答唯一一个问题:**接着读流,还是
+ * fail-soft 收场**。三条出路:
+ *   · 决断成功 ⇒ `reattach`(驱动 attach `runs.events`,`lastEventId` 续传);
+ *   · 「这个 gate 早就被解决了」(durable re-attach 必然重放已决断的 park)⇒ 同样 `reattach`;
+ *   · 其余(overlay 缺席 / pending 蒸发 / decide 409/404 / turn 中断 / hop 预算耗尽)⇒ `failsoft`:
+ *     flush HOLD 的毒化帧 + 原样吐 suspended 终帧(durable 腿无终帧则合成一条可见的 failed)。
+ *
+ * 🔴 本文件不碰流、不 yield:events 以数组交回驱动。`resolvePark` 的**返回值**就是它的全部对外
+ *    效果(台账写入除外,且台账写入全经 `GateLedger` 的动词)—— 于是「禁掉某条真臂」这种变异
+ *    在驱动的消费点上必然显形,而不是被本文件自己吞掉。
+ */
+import type { AgentEvent } from '@sema-agent/sdk';
+import { type QuestionAnswer } from '../liveQuestionStore.js';
+import type { AskAnsweredOutput, GateLedger } from './gateLedger.js';
+import { type AskGateWireDeps, type GatePark } from './frameRouter.js';
+/**
+ * REF-CC-033:`GateOutcome` 的 `failed` 分支闭集判别码。来源两处:①本文件自己的
+ * 「pending 行取不到」早退(`surfaceGateAndDecide` 里 `!pending` 那条);②`HitlBridge` 抛出的
+ * `HitlSafetyError.code`(hitlBridge.ts 契约:`binding_mismatch|no_pending|wrong_gate|bad_plan_edit`
+ * ——该属性今天仍是开集 `string`,TYPESHAPE-07/REF-CC-036 候后续车锁死;这里落地前用
+ * `isGateFailureCode` 按闭集白名单过滤,不认得的值一律降级成 `undefined`,退回文案兜底,不让
+ * 开集腐蚀这个新判别位)。消费点只认 `'no_pending'` 为「已解决」,其余码(binding_mismatch 等)
+ * 是真需要重新呈现给人的失败,不能走「继续读流」这条路。
+ */
+export type GateFailureCode = 'no_pending' | 'binding_mismatch' | 'wrong_gate' | 'bad_plan_edit';
+export type GateOutcome = {
+    kind: 'decided';
+    gatedCallId?: string | undefined;
+    answered?: AskAnsweredOutput | undefined;
+} | {
+    kind: 'aborted';
+    gatedCallId?: string | undefined;
+} | {
+    kind: 'failed';
+    gatedCallId?: string | undefined;
+    reason: string;
+    code?: GateFailureCode | undefined;
+};
+/**
+ * decide 的 `failed` 原因是不是「这个 gate 早就被解决了」(#110 缺陷② c 的判据)。
+ *
+ * REF-CC-033:此前判据**只**锚在文案词(`no pending checkpoint` / `resolved` / `already` 三者
+ * 任一在场)——server 原文改一个字,整条命中当场失效(FIX-13 / 域词表-01)。现在消费点(见下方
+ * `isAlreadyResolvedFailure`)优先判 `GateOutcome.code`(闭集判别位,见 `GateFailureCode`);
+ * 这个函数降级为**文案兜底臂**,只在 outcome 没带 code 的时候才被调用(典型:`FsApprovalOutcome`
+ * 来自 `toolApprovalWire.ts`,那份类型今天没有 code 字段——C-bridge 卡的文件域,本卡不改)。
+ * 🔴 方向没变:这条判**错**的后果不对称 —— 误判成「已解决」最多让流多读一轮(hop 预算兜底),
+ * 误判成「真失败」会把一个已经 completed 的 run 谎报成失败并烧掉整条会话转录。所以宁可宽。
+ */
+/** #114/[C68] 单源化提升:desktop 照抄件(durable 双实现审计 P0-1 修)到货换包导入删抄件。 */
+export declare function isAlreadyResolvedGateReason(reason: unknown): boolean;
+/** 把 wire 答案({answers:[{header,selected,note?}]})折回 CC 卡片的 Record<question,string> 形状
+ *  (multiSelect 与对话框同款 ", " lossy join;note → annotations.notes)。 */
+export declare function toAnsweredOutput(questions: unknown[], answer: QuestionAnswer): AskAnsweredOutput;
+/** 外环决断的两种出路(见文件头注)。 */
+export type ParkResolution = {
+    kind: 'reattach';
+} | {
+    kind: 'failsoft';
+    events: readonly AgentEvent[];
+};
+export interface ParkResolveCtx {
+    deps: AskGateWireDeps;
+    led: GateLedger;
+    /** sync leg 捕获的真 run handle(内环 `TaskIdRef` 的当前值)。 */
+    taskId: string;
+    /** 本 turn 内这是第几次 park(hop 预算的唯一计量;由驱动累加,本函数只读)。 */
+    hops: number;
+    signal?: AbortSignal | undefined;
+}
+export declare function resolvePark(park: GatePark, ctx: ParkResolveCtx): Promise<ParkResolution>;

package/dist/hitl/parkResolver.js

@@ -0,0 +1,250 @@
+import { HitlBridge, HitlSafetyError, findPendingForTask } from './hitlBridge.js';
+import { publishQuestionFrame, registerLocalQuestionResponder, hasQuestionOverlay, } from '../liveQuestionStore.js';
+import { hostLog } from '../host.js';
+import { surfaceFsApprovalAndDecide } from './toolApprovalWire.js';
+import { observeCancelByDeny } from './hitlHostSurface.js';
+import { isAskTool } from './frameRouter.js';
+/** 一 turn 内最多循环这么多次 park(防御:引擎/模型病态连环提问时不无限 attach)。 */
+const MAX_GATE_HOPS = 24;
+function isGateFailureCode(v) {
+    return v === 'no_pending' || v === 'binding_mismatch' || v === 'wrong_gate' || v === 'bad_plan_edit';
+}
+/**
+ * decide 的 `failed` 原因是不是「这个 gate 早就被解决了」(#110 缺陷② c 的判据)。
+ *
+ * REF-CC-033:此前判据**只**锚在文案词(`no pending checkpoint` / `resolved` / `already` 三者
+ * 任一在场)——server 原文改一个字,整条命中当场失效(FIX-13 / 域词表-01)。现在消费点(见下方
+ * `isAlreadyResolvedFailure`)优先判 `GateOutcome.code`(闭集判别位,见 `GateFailureCode`);
+ * 这个函数降级为**文案兜底臂**,只在 outcome 没带 code 的时候才被调用(典型:`FsApprovalOutcome`
+ * 来自 `toolApprovalWire.ts`,那份类型今天没有 code 字段——C-bridge 卡的文件域,本卡不改)。
+ * 🔴 方向没变:这条判**错**的后果不对称 —— 误判成「已解决」最多让流多读一轮(hop 预算兜底),
+ * 误判成「真失败」会把一个已经 completed 的 run 谎报成失败并烧掉整条会话转录。所以宁可宽。
+ */
+/** #114/[C68] 单源化提升:desktop 照抄件(durable 双实现审计 P0-1 修)到货换包导入删抄件。 */
+export 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');
+}
+/** 已解决判据(REF-CC-033):code 在场就只信 code,不在场才落回文案兜底(fs 审批腿的
+ *  `FsApprovalOutcome` 今天没有 code 字段——C-bridge 卡域,退役条件 = 那边也补上 code)。
+ *  🔴 入参**已经**是窄化到 `{kind:'failed'}` 的那半:一个「true ⇒ 是 failed」的判定不能反过来
+ *  当「false ⇒ 不是 failed」的类型谓词用(TS 的 `outcome is Extract<…>` 负向窄化会把整个
+ *  `'failed'` 分支从联合类型里排除,而这个函数对未解决的真失败照样返回 false——那不是「它不是
+ *  failed」,是「它是 failed 但没解决」。调用点先用 `outcome.kind === 'failed'` 做真正的判别式
+ *  窄化,再把窄化后的值交给这里,本函数只回答布尔,不再兼职类型谓词。 */
+function isAlreadyResolvedFailure(outcome) {
+    const code = 'code' in outcome && isGateFailureCode(outcome.code) ? outcome.code : undefined;
+    return code !== undefined ? code === 'no_pending' : isAlreadyResolvedGateReason(outcome.reason);
+}
+/** 把 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 } : {}),
+    };
+}
+/**
+ * 弹既有 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)。
+    // REF-CC-029(单源取件)+ REF-CC-033(no_pending 判别码):findPendingForTask 是唯一取件口
+    // (三份近似复刻已收敛),其失败形带 code 判别位,本处原样透传给 GateOutcome ——
+    // 「没有待决 gate」(良性,park 重放常见)与「approvals.list 真失败」自此结构可分。
+    const found = await findPendingForTask(deps.client, taskId, isAskTool, signal ? { signal } : undefined);
+    if (!found.ok)
+        return { kind: 'failed', reason: found.reason, ...(found.code !== undefined ? { code: found.code } : {}) };
+    const { pending, gatedCallId } = found;
+    // 问题 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, undefined, pending), taskId);
+        return { kind: 'aborted', gatedCallId };
+    }
+    try {
+        // REF-CC-038(2026-08-02):`answer.answers` 已经是 `AskAnswer[]`(liveQuestionStore 的
+        // `QuestionAnswer` 直用 hitlBridge 的 `AskAnswer` 为唯一源)—— 不再需要靠 cast 把两个
+        // 名不同的等价形状缝合。
+        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, pending);
+            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, pending);
+        }
+        return { kind: 'decided', gatedCallId };
+    }
+    catch (e) {
+        // REF-CC-033:HitlSafetyError.code 是 hitlBridge.ts 自己的闭集契约(见其类型头注),
+        // 这里 instanceof 窄化后再过 isGateFailureCode 白名单——不认得的码(将来 hitlBridge 那边
+        // 万一多加一种)一律降级成 undefined,退回文案兜底,不让开集腐蚀这个新判别位。
+        const code = e instanceof HitlSafetyError && isGateFailureCode(e.code) ? e.code : undefined;
+        return { kind: 'failed', gatedCallId, reason: `decide failed: ${String(e)}`, ...(code !== undefined ? { code } : {}) };
+    }
+}
+/** 台账里那批 gated `tool_start` 当拍 args 快照 → 决断腿要的 `toolCallId → args` 表(UNTRUSTED 原样搬运)。 */
+function argsByCallOf(led) {
+    return new Map(led.gatedStartArgs());
+}
+export async function resolvePark(park, ctx) {
+    const { deps, led, taskId, hops } = ctx;
+    let outcome;
+    // REF-CC-034:这次 park 的候选 callId(仅 fs 分支填,已决断身份匹配用)——ask 分支不填,
+    // 因为 `surfaceGateAndDecide` 的 `!pending` 早退已经自带 `code:'no_pending'`(REF-CC-033),
+    // 不需要这条第二判据。用 `lastFsOrShellGatedCallId()` 而非「未收口 fs call 栈」:durable
+    // re-attach 重放的 `suspended` park 没有配套的新 tool_start/tool_end,那个栈在这次重放之前
+    // 早被 tool_end 的 drop 清空了(见台账声明处注),取不到候选。
+    let candidateGatedCallId;
+    if (hops > MAX_GATE_HOPS) {
+        outcome = { kind: 'failed', reason: `gate hop limit (${MAX_GATE_HOPS}) exceeded` };
+    }
+    else if (park.gate === 'fs') {
+        candidateGatedCallId = led.lastFsOrShellGatedCallId();
+        // [816] 放宽腿:fs 写权限 gate → CC 三选卡(vendored PermissionRequest)→ decide。
+        outcome = await surfaceFsApprovalAndDecide({ client: deps.client }, taskId, argsByCallOf(led), ctx.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) {
+            led.markDenied(outcome.gatedCallId); // 重放的报错帧渲 `User rejected …`(见 tool_end 有序臂 ③)
+        }
+    }
+    else {
+        outcome = await surfaceGateAndDecide(deps, taskId, argsByCallOf(led), ctx.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` 兜底(本 reattach 照常吃 hop 预算,不绕过它)。
+    //
+    // REF-CC-034:`isAlreadyResolvedFailure` 是首选判据(code/文案双臂),但 fs 腿的
+    // `FsApprovalOutcome` 今天没有 `code`(toolApprovalWire.ts,C-bridge 域),失败原因若不是
+    // 那三个文案子串(例如 `approvals.list` 自身网络失败)就会漏判。已决断身份匹配是独立于
+    // 文案的第二判据 —— 两臂任一命中都按「已解决」处置,方向偏宽(见台账 `markDecided` 处注)。
+    //
+    // [2393] hitl-F2(2026-08-02):这条身份判据**一次性消费**(`takeDecided` 而不是 `isDecided`)。
+    // 它的正当性只覆盖「durable re-attach 把**那一次**已决断的 park 重放一遍」这一个窗口,而它的两个
+    // 输入都是单调的(`lastFsOrShellGatedCallId()` 故意不随 tool_end 清空 + `decidedGates` 只增),
+    // 不消费就等于:本 turn 只要成功决断过一次,之后**每一次** park 失败都被判「已解决」——
+    // `approvals.list` 网络失败这类真失败会连吃 24 个 hop,最后吐一句与真因无关的 `gate hop limit`。
+    // 消费点写在 `outcome.kind === 'failed'` 之内:决断成功的那一轮压根不该动这个记号。
+    const alreadyDecidedById = outcome.kind === 'failed' &&
+        candidateGatedCallId !== undefined &&
+        led.takeDecided(candidateGatedCallId);
+    if (outcome.kind === 'failed' && (isAlreadyResolvedFailure(outcome) || alreadyDecidedById)) {
+        const seq = led.lastSeq();
+        hostLog('debug', `liveHitlAskWire: gate already resolved (${outcome.reason}) — replayed park, re-attaching runs.events(${taskId})${seq ? ` from seq ${seq}` : ''} instead of failing the turn` +
+            (alreadyDecidedById ? ` [decidedGates id match: ${candidateGatedCallId}]` : '') +
+            (led.decidedCount() > 0 ? ` [decided so far: ${led.decidedCount()}]` : ''));
+        return { kind: 'reattach' };
+    }
+    if (outcome.kind !== 'decided') {
+        hostLog('debug', `liveHitlAskWire: gate not decided (${outcome.kind}${'reason' in outcome ? `: ${outcome.reason}` : ''}) — fail-soft to suspended terminal`);
+        const events = [...led.flushHeld()]; // 回退:毒化帧照旧渲染(= 修复前的诚实红)
+        if (park.pendingDone) {
+            events.push(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 让用户看得见为什么停了
+            events.push({
+                type: 'failed',
+                errorCode: 'hitl_unanswered',
+                errorMessage: `${park.gate === 'fs' ? 'Tool approval' : 'AskUserQuestion'} gate could not be answered: ${outcome.reason}`,
+            });
+        }
+        return { kind: 'failsoft', events };
+    }
+    // decide 成功:丢弃该 call 的毒化 HOLD(续流重放会带 isError:false 的解答帧收口卡片),
+    // 并记下真实答案供该解答帧 stamp `structured`(否则卡片渲成结果不可用)。
+    if (outcome.gatedCallId) {
+        led.dropHeld(outcome.gatedCallId);
+        led.markDecided(outcome.gatedCallId); // #110 缺陷② b / REF-CC-034:身份留痕,上方候选匹配消费
+        if ('answered' in outcome && outcome.answered)
+            led.rememberAnswer(outcome.gatedCallId, outcome.answered);
+    }
+    const seq = led.lastSeq();
+    hostLog('debug', `liveHitlAskWire: gate decided (call ${outcome.gatedCallId ?? '?'}) — attaching runs.events(${taskId})${seq ? ` from seq ${seq}` : ''}`);
+    return { kind: 'reattach' };
+}

package/dist/hitl/planReviewWire.d.ts

@@ -1,12 +1,70 @@
+/**
+ * ⇄ B7 批搬迁(2026-07-27,设计稿 §3 B7):cli `src/sema/planReviewWire.ts`(142 行)**整条进包**。
+ *
+ * 🔴 **`wireConfig()` 第七份收编闭合**:B6 的 `engineWireTarget.ts` 头注记着「本批搬入的是前六份;
+ *    第七份 `planReviewWire` 不在 B6 范围,仍留壳内 —— 它是下一批的收编候选,别以为已经收干净了」。
+ *    本批就是那一批:这里改用 `engineWireTarget()`,壳树 `grep -rn 'function wireConfig' src/sema/`
+ *    的七份手抄至此**归零**(pure 门 B7 段有断言:壳树在场时命中数 = 0;缺席 ⇒ DEGRADED)。
+ *
+ * 🔴 其余搬迁差分(零行为变化):
+ *   1. `logForDebugging` → `hostLog`。
+ *   2. `await import('../utils/messageQueueManager.js').enqueuePendingNotification({...})`
+ *      → `NotificationQueuePort.enqueueMetaPrompt`(B7 新增的**可选**方法 —— 既有宿主实现不破)。
+ *      🔴 缺席后果不是「少个装饰」:模型永远不知道 plan 被批准/驳回后引擎跑出了什么结果,
+ *      于是它在 approve 之后**原地不动**。所以缺席计 miss(`notificationQueuePortMisses()`),
+ *      并保留壳原文的 try/catch fail-soft(投递失败绝不炸流)。
+ *   3. `registerLocalQuestionResponder`/`publishQuestionFrame` → 包内 `liveQuestionStore`
+ *      (B1 已搬,**同一个 module 台账**;两份实例 ⇒ 卡弹出来没人收答)。
+ *
+ * ── 以下为原文件的领域说明(逐字保留)────────────────────────────────────────────────────────
+ *
+ * planReviewWire — plan_review park 的壳侧审批闭环(core [508]③ 形状拍板 + [511]② 实证)。
+ *
+ * WIRE 全链(server 1.138 × core 1.257.4 探针逐字实证,probe-plan-final-frame.mjs):
+ *   1. plan-mode turn 里模型调 ExitPlanMode → 引擎 park:done 帧 `status:"needs_review"` +
+ *      `checkpointGate:{kind:"plan_review",reason:"ExitPlanMode"}` + `errorCode:"review.pending"`;
+ *      plan 文本已由 ExitPlanMode tool_end 渲染在转录(fence 块),checkpoint 落 FileCheckpointStore。
+ *   2. 壳(本模块,runStream done 分支调用)合成一个 QuestionFrame 借 AskUserQuestion overlay 弹
+ *      审批卡(core 拍板:不新造 live question 帧,壳自绘)——合成 id `plan-review:<taskId>` 经
+ *      liveQuestionStore 的 LOCAL responder 拦截,绝不会打到引擎的 /v1/questions(那里 404)。
+ *   3. 决断 → POST /v1/assistant/tasks/:taskId/plan_review `{decision:"approve"|"reject"}`——
+ *      resume 是 SYNC 驱动到终态的(实证 200 `{taskId,sessionId,status:"completed"}`,可能分钟级),
+ *      所以 fire 后卡片即关,完成后经 enqueuePendingNotification 入队一个 isMeta turn:模型收到
+ *      resume 终态,自然接续汇报(approve 后"继续干活"的 CC 体验由引擎侧 resume 已完成,这里是
+ *      结果呈现)。reject 同构(引擎丢 plan 保持 plan 语境)。
+ *
+ * 挂账(诚实边界):approve 后壳本地的 plan-mode footer 徽章不自动退(CC 会退)——退 mode 的
+ * app-state seam 不在本模块可达面,记 rc.47 接 REPL 层;engine 侧 handsReadOnly 已由 resume 处理。
+ */
+import { type QuestionAnswer } from '../liveQuestionStore.js';
+/**
+ * REF-CC-026:此前是 module-private 常量,唯一另一个消费者(cli `planReviewReopen.ts`)只能靠
+ * 人眼手抄同步(头注写着「与 client-core planReviewWire 的原卡逐字一致」)——漂一个字节,判决就
+ * 落到危险的默认臂(见下方 `planReviewDecisionFromAnswer` 的头注)。现在导出成唯一真源;cli 侧改
+ * import 是后续跟车工单(壳仓文件域,不在本卡范围)。
+ */
+export declare const PLAN_REVIEW_APPROVE_LABEL = "Yes, approve and run the plan";
+export declare const PLAN_REVIEW_REJECT_LABEL = "No, reject it (keep planning)";
+/**
+ * REF-CC-026:三值判决(此前 `selected === APPROVE_LABEL ? 'approve' : 'reject'` 把「没读懂/没
+ * 选」的第三种输入静默塌缩进危险的 reject 臂——overlay 的 dismiss/拒答语义是「送空 answers」,
+ * 与用户真的点了 REJECT_LABEL 长得一模一样)。两个标签都做**显式**等值比对,任何第三种输入
+ * (含 undefined)落 `'dismissed'`,由调用方决定是保持 park 还是显式当 reject 处理——本函数只
+ * 负责如实分类,不替调用方做选择。
+ */
+export declare function planReviewDecisionFromAnswer(answer: QuestionAnswer | null | undefined): 'approve' | 'reject' | 'dismissed';
 /** done 帧的 plan_review park 形状(结构性读,别的终态一律 false)。 */
 export declare function isPlanReviewPark(result: unknown): result is {
     taskId: string;
     sessionId?: string;
 };
+/** 测试钩:清掉武装态(不动 liveQuestionStore 本身,那边有自己的 reset)。 */
+export declare function _resetArmedPlanReviewsForTest(): void;
 /**
  * Arm the approval card for a parked plan_review (call with the RAW done.result). Returns true when
- * armed (live path + shape matched); false = caller renders the terminal as usual. Fail-soft: any
- * error inside must never break the stream drain.
+ * armed (live path + shape matched, INCLUDING the idempotent "already armed" short-circuit — see
+ * REF-CC-027 above); false = caller renders the terminal as usual. Fail-soft: any error inside must
+ * never break the stream drain.
  */
 export declare function armPlanReviewApproval(result: unknown): boolean;
 /** POST the decision; on settle enqueue an isMeta turn so the model reports the resume outcome.