@sema-agent/client-core 0.12.2 → 0.13.0

package/dist/hitl/parkResolver.js

@@ -0,0 +1,241 @@
+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` 处注)。
+    const alreadyDecidedById = candidateGatedCallId !== undefined && led.isDecided(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.

package/dist/hitl/planReviewWire.js

@@ -44,8 +44,31 @@ import { enqueuePlanReviewOutcome } from '../notifications.js';
 /** resume 是 SYNC 驱动到终态的(可能分钟级)——原 raw fetch 无超时;SDK Transport 恒有每请求
  *  超时,取 6h 宽上界(诚实预算:超过它基本是引擎僵死,超时文案与网络失败同走 outcome 通知)。 */
 const PLAN_REVIEW_RESUME_TIMEOUT_MS = 6 * 60 * 60_000;
-const APPROVE_LABEL = 'Yes, approve and run the plan';
-const REJECT_LABEL = 'No, reject it (keep planning)';
+/**
+ * REF-CC-026:此前是 module-private 常量,唯一另一个消费者(cli `planReviewReopen.ts`)只能靠
+ * 人眼手抄同步(头注写着「与 client-core planReviewWire 的原卡逐字一致」)——漂一个字节,判决就
+ * 落到危险的默认臂(见下方 `planReviewDecisionFromAnswer` 的头注)。现在导出成唯一真源;cli 侧改
+ * import 是后续跟车工单(壳仓文件域,不在本卡范围)。
+ */
+export const PLAN_REVIEW_APPROVE_LABEL = 'Yes, approve and run the plan';
+export const PLAN_REVIEW_REJECT_LABEL = 'No, reject it (keep planning)';
+const APPROVE_LABEL = PLAN_REVIEW_APPROVE_LABEL;
+const REJECT_LABEL = PLAN_REVIEW_REJECT_LABEL;
+/**
+ * REF-CC-026:三值判决(此前 `selected === APPROVE_LABEL ? 'approve' : 'reject'` 把「没读懂/没
+ * 选」的第三种输入静默塌缩进危险的 reject 臂——overlay 的 dismiss/拒答语义是「送空 answers」,
+ * 与用户真的点了 REJECT_LABEL 长得一模一样)。两个标签都做**显式**等值比对,任何第三种输入
+ * (含 undefined)落 `'dismissed'`,由调用方决定是保持 park 还是显式当 reject 处理——本函数只
+ * 负责如实分类,不替调用方做选择。
+ */
+export function planReviewDecisionFromAnswer(answer) {
+    const selected = answer?.answers?.[0]?.selected?.[0];
+    if (selected === APPROVE_LABEL)
+        return 'approve';
+    if (selected === REJECT_LABEL)
+        return 'reject';
+    return 'dismissed';
+}
 /** done 帧的 plan_review park 形状(结构性读,别的终态一律 false)。 */
 export function isPlanReviewPark(result) {
     const r = result;
@@ -55,24 +78,56 @@ export function isPlanReviewPark(result) {
         typeof r.taskId === 'string' &&
         r.taskId.length > 0);
 }
+/**
+ * REF-CC-027:已武装未消解的 taskId 去重集(与 `HitlBridge`/`liveQuestionStore` 同款「进程内单例
+ * 承重不变量」——见 `docs/refactor/p1-scan/singleton-manifest.json` 登记)。durable re-attach 会把
+ * 同一个 `done{needs_review}` 帧再送一遍(与 askGateWire 的 `decidedGates` 同一族问题);此前
+ * `armPlanReviewApproval` 对同一 taskId 的重复调用会**再注册一次** responder(旧的注销函数被整个
+ * 丢掉),第二次注册会覆盖 `localResponders` 里的条目——若第一张卡此刻还没答,它的 unregister
+ * 闭包会变成一个指向"已被覆盖"槽位的悬空引用。这个集合让重复 arm 直接幂等短路,不再产生第二次
+ * `registerLocalQuestionResponder` 调用。
+ */
+const armedPlanReviewTaskIds = new Set();
+/** 测试钩:清掉武装态(不动 liveQuestionStore 本身,那边有自己的 reset)。 */
+export function _resetArmedPlanReviewsForTest() {
+    armedPlanReviewTaskIds.clear();
+}
 /**
  * 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 function armPlanReviewApproval(result) {
+    let armedTaskId;
     try {
         if (!isPlanReviewPark(result))
             return false;
         if (!engineWireTarget())
             return false;
         const { taskId } = result;
+        if (armedPlanReviewTaskIds.has(taskId)) {
+            // REF-CC-027:同一张卡还没消解就被重放的 arm 撞上——幂等,不二次弹卡/二次注册。
+            hostLog('debug', `planReviewWire: arm skipped — task ${taskId} is already armed (durable replay, idempotent)`);
+            return true;
+        }
+        armedPlanReviewTaskIds.add(taskId);
+        armedTaskId = taskId;
         const questionId = `plan-review:${taskId}`;
-        registerLocalQuestionResponder(questionId, async (_id, answer) => {
-            const selected = answer?.answers?.[0]?.selected?.[0];
-            const decision = selected === APPROVE_LABEL ? 'approve' : 'reject';
+        const unregister = registerLocalQuestionResponder(questionId, async (_id, answer) => {
+            // REF-CC-027:一次性 —— 首句就注销 + 清武装态(照 askGateWire 的 cleanup() 形)。
+            // liveQuestionStore.respondToQuestion 自身也是一次性取件(delete-before-invoke),这里是
+            // 第二道钉:武装态一清,同 taskId 才能重新正常 arm(证明 responder 真的落定了)。
+            unregister();
+            armedPlanReviewTaskIds.delete(taskId);
+            const decided = planReviewDecisionFromAnswer(answer);
+            if (decided === 'dismissed') {
+                // dismiss/无法判读:诚实缺席优先于编造默认值(REF-CC-026)——不静默驱动 decidePlanReview,
+                // 卡的重开路径把决定权还给用户。
+                return { ok: true };
+            }
             // fire-and-forget:resume 同步驱动到终态可能分钟级,不能挂住 overlay;结果经 queue 通知回来
-            void decidePlanReview(taskId, decision);
+            void decidePlanReview(taskId, decided);
             return { ok: true };
         });
         publishQuestionFrame({
@@ -94,6 +149,10 @@ export function armPlanReviewApproval(result) {
         return true;
     }
     catch (e) {
+        // REF-CC-027:arm 本身失败(register/publish 抛)绝不能把 taskId 永久锁在武装态里
+        // ——那样这张卡再也无法被正常 arm 一次。
+        if (armedTaskId !== undefined)
+            armedPlanReviewTaskIds.delete(armedTaskId);
         hostLog('debug', `planReviewWire: arm failed (fail-soft): ${String(e)}`);
         return false;
     }
@@ -104,80 +163,99 @@ export function armPlanReviewApproval(result) {
  *  server body.error 原文)→ 同款「HTTP <status> <error>」outcome 文案;网络失败走原「could not
  *  reach the engine」臂。 */
 export async function decidePlanReview(taskId, decision) {
+    // REF-CC-025:此前 `cfg`/`client` 缺席各自 `return` 静默——卡已经对用户回了「收到」
+    // (armPlanReviewApproval 的 responder 早就 `return {ok:true}` 过了),但决断本身连一次网络
+    // 请求都没发出去,而模型/用户没有任何回程信号。两条早退现在都汇进同一条 outcome 管道(下方
+    // 唯一的 enqueue 调用点),不再是两条独立的静默 return。
+    let outcome;
     const cfg = engineWireTarget();
-    if (!cfg)
-        return;
-    const client = makeEngineWireClient({
-        baseUrl: cfg.baseUrl,
-        ...(cfg.token ? { token: cfg.token } : {}),
-        principal: cfg.principal,
-        timeoutMs: PLAN_REVIEW_RESUME_TIMEOUT_MS,
-    });
-    if (!client)
-        return;
-    let outcome = '';
-    try {
-        const body = await client.assistant.planReview(taskId, { decision });
-        hostLog('debug', `planReviewWire: ${decision} → ok ${JSON.stringify(body).slice(0, 200)}`);
-        // [2315]/[2316](#109,2026-08-02):decide 的 **2xx 不当终态** —— test 黑盒实测 reject 9/9
-        // 返回 200 而会话仍锁在同一 gate(core RB-471:重开兜底对 reject 腿恒真误触发)。这里回拉
-        // 一次任务状态,按真形分三路措辞;根因归 core/server,本腿是「对外动作回读验证」在产品面的
-        // 同款,上游修后仍有价值(approve 合法推进新 gate 的形也靠它说真话)。
-        // 回拉用**短超时**独立 client(15s):verify 腿挂住不该占用 decide 的 6h 宽预算。
-        let postStatus;
-        try {
-            const probe = makeEngineWireClient({
-                baseUrl: cfg.baseUrl,
-                ...(cfg.token ? { token: cfg.token } : {}),
-                principal: cfg.principal,
-                timeoutMs: 15_000,
-            });
-            const post = probe ? (await probe.runs.get(taskId)) : null;
-            postStatus = typeof post?.status === 'string' ? post.status : undefined;
-        }
-        catch (e) {
-            hostLog('debug', `planReviewWire: post-decide status re-pull failed (fail-soft): ${String(e)}`);
-        }
-        // 回拉失败时回落 decide 200 体自带的 status(次级来源;两者都缺=unverified,措辞如实降级)。
-        const effective = postStatus ?? (typeof body?.status === 'string' ? body.status : undefined);
-        if (effective === 'needs_review') {
-            // 决定没生效,仍锁原 gate。不渲「已处理」;真出路只有 approve 或 cancel(下一次提交撞 409
-            // 时 activeRunSelfHeal 会把审批卡重开——这里不自动重弹卡,避免「刚拒绝又弹卡」的突袭感,
-            // 决定权经卡的重开路径还给用户)。
-            outcome =
-                `The plan_review ${decision} returned HTTP 200 but the session is STILL locked on the same review gate ` +
-                    `(post-decide status: needs_review). The decision did NOT take effect (known engine issue, RB-471 family). ` +
-                    `Tell the user plainly that the ${decision} did not go through; the reliable exits today are approving the plan or cancelling the task.`;
-        }
-        else if (effective === 'suspended') {
-            // 合法推进到新 gate(test [2315] ②形):不是「完成」,如实说下一张审批卡会跟上。
-            outcome =
-                `The plan was ${decision === 'approve' ? 'approved' : 'rejected'} and the task advanced to a NEW approval gate ` +
-                    `(post-decide status: suspended) — the next approval card will surface it; this is not a completion yet.`;
-        }
-        else if (effective !== undefined) {
-            outcome = `The plan was ${decision === 'approve' ? 'approved and the parked task resumed to completion' : 'rejected (plan discarded)'} — final status: ${effective} (post-decide re-checked: task left the review gate).`;
-        }
-        else {
-            outcome = `The plan was ${decision === 'approve' ? 'approved and the parked task resumed to completion' : 'rejected (plan discarded)'} — final status: unknown (post-decide verification unavailable; treat as unconfirmed).`;
-        }
+    if (!cfg) {
+        hostLog('error', `planReviewWire: ${decision} NOT sent — engineWireTarget() unavailable`);
+        outcome = `The plan_review ${decision} could NOT be sent: no engine connection is configured on this host. Tell the user plainly that the decision did not go through.`;
     }
-    catch (e) {
-        // APIError 判型走 status duck-check(sseIdleTriage 同款纪律:双包时 instanceof 会分叉)。
-        const status = e?.status;
-        if (typeof status === 'number') {
-            const msg = e instanceof Error ? e.message : String(e);
-            hostLog('debug', `planReviewWire: ${decision} → ${status} ${msg.slice(0, 200)}`);
-            outcome = `The plan_review decision failed: HTTP ${status} ${msg}`.trim();
+    else {
+        const client = makeEngineWireClient({
+            baseUrl: cfg.baseUrl,
+            ...(cfg.token ? { token: cfg.token } : {}),
+            principal: cfg.principal,
+            timeoutMs: PLAN_REVIEW_RESUME_TIMEOUT_MS,
+        });
+        if (!client) {
+            hostLog('error', `planReviewWire: ${decision} NOT sent — makeEngineWireClient() returned null`);
+            outcome = `The plan_review ${decision} could NOT be sent: the engine client could not be constructed. Tell the user plainly that the decision did not go through.`;
         }
         else {
-            outcome = `The plan_review decision could not reach the engine: ${String(e)}`;
+            try {
+                const body = await client.assistant.planReview(taskId, { decision });
+                hostLog('debug', `planReviewWire: ${decision} → ok ${JSON.stringify(body).slice(0, 200)}`);
+                // [2315]/[2316](#109,2026-08-02):decide 的 **2xx 不当终态** —— test 黑盒实测 reject 9/9
+                // 返回 200 而会话仍锁在同一 gate(core RB-471:重开兜底对 reject 腿恒真误触发)。这里回拉
+                // 一次任务状态,按真形分三路措辞;根因归 core/server,本腿是「对外动作回读验证」在产品面的
+                // 同款,上游修后仍有价值(approve 合法推进新 gate 的形也靠它说真话)。
+                // 回拉用**短超时**独立 client(15s):verify 腿挂住不该占用 decide 的 6h 宽预算。
+                let postStatus;
+                try {
+                    const probe = makeEngineWireClient({
+                        baseUrl: cfg.baseUrl,
+                        ...(cfg.token ? { token: cfg.token } : {}),
+                        principal: cfg.principal,
+                        timeoutMs: 15_000,
+                    });
+                    const post = probe ? (await probe.runs.get(taskId)) : null;
+                    postStatus = typeof post?.status === 'string' ? post.status : undefined;
+                }
+                catch (e) {
+                    hostLog('debug', `planReviewWire: post-decide status re-pull failed (fail-soft): ${String(e)}`);
+                }
+                // 回拉失败时回落 decide 200 体自带的 status(次级来源;两者都缺=unverified,措辞如实降级)。
+                const effective = postStatus ?? (typeof body?.status === 'string' ? body.status : undefined);
+                if (effective === 'needs_review') {
+                    // 决定没生效,仍锁原 gate。不渲「已处理」;真出路只有 approve 或 cancel(下一次提交撞 409
+                    // 时 activeRunSelfHeal 会把审批卡重开——这里不自动重弹卡,避免「刚拒绝又弹卡」的突袭感,
+                    // 决定权经卡的重开路径还给用户)。
+                    outcome =
+                        `The plan_review ${decision} returned HTTP 200 but the session is STILL locked on the same review gate ` +
+                            `(post-decide status: needs_review). The decision did NOT take effect (known engine issue, RB-471 family). ` +
+                            `Tell the user plainly that the ${decision} did not go through; the reliable exits today are approving the plan or cancelling the task.`;
+                }
+                else if (effective === 'suspended') {
+                    // 合法推进到新 gate(test [2315] ②形):不是「完成」,如实说下一张审批卡会跟上。
+                    outcome =
+                        `The plan was ${decision === 'approve' ? 'approved' : 'rejected'} and the task advanced to a NEW approval gate ` +
+                            `(post-decide status: suspended) — the next approval card will surface it; this is not a completion yet.`;
+                }
+                else if (effective !== undefined) {
+                    outcome = `The plan was ${decision === 'approve' ? 'approved and the parked task resumed to completion' : 'rejected (plan discarded)'} — final status: ${effective} (post-decide re-checked: task left the review gate).`;
+                }
+                else {
+                    outcome = `The plan was ${decision === 'approve' ? 'approved and the parked task resumed to completion' : 'rejected (plan discarded)'} — final status: unknown (post-decide verification unavailable; treat as unconfirmed).`;
+                }
+            }
+            catch (e) {
+                // APIError 判型走 status duck-check(sseIdleTriage 同款纪律:双包时 instanceof 会分叉)。
+                const status = e?.status;
+                if (typeof status === 'number') {
+                    const msg = e instanceof Error ? e.message : String(e);
+                    hostLog('debug', `planReviewWire: ${decision} → ${status} ${msg.slice(0, 200)}`);
+                    outcome = `The plan_review decision failed: HTTP ${status} ${msg}`.trim();
+                }
+                else {
+                    outcome = `The plan_review decision could not reach the engine: ${String(e)}`;
+                }
+            }
         }
     }
+    // REF-CC-025:唯一的 enqueue 调用点(三条上游路径——cfg 缺席 / client 缺席 / 正常决断—— 都汇到
+    // 这里)。返回值此前被丢弃:`enqueuePlanReviewOutcome` 返回 `false` 意味着队列口没装或没实现
+    // `enqueueMetaPrompt`(notifications.ts 头注:「模型永远不知道 plan 被批准/驳回后引擎跑出了
+    // 什么结果」),这是与 HTTP 失败同等重量的静默丢失,必须留痕。
     try {
-        enqueuePlanReviewOutcome(`<plan-review-outcome>\n${outcome}${decision === 'approve' ? `\nUse TaskOutput("${taskId}") if you need the resumed task's full output, then give the user a brief report of what was done.` : '\nBriefly acknowledge to the user that the plan was rejected and continue planning.'}\n</plan-review-outcome>`);
+        const delivered = enqueuePlanReviewOutcome(`<plan-review-outcome>\n${outcome}${decision === 'approve' ? `\nUse TaskOutput("${taskId}") if you need the resumed task's full output, then give the user a brief report of what was done.` : '\nBriefly acknowledge to the user that the plan was rejected and continue planning.'}\n</plan-review-outcome>`);
+        if (!delivered) {
+            hostLog('error', `planReviewWire: outcome enqueue MISSED (queue port not installed or lacks enqueueMetaPrompt) for task ${taskId} — model will not learn the ${decision} result`);
+        }
     }
     catch (e) {
-        hostLog('debug', `planReviewWire: outcome enqueue failed: ${String(e)}`);
+        hostLog('debug', `planReviewWire: outcome enqueue threw: ${String(e)}`);
     }
 }