@sema-agent/client-core 0.28.0 → 0.30.0

package/dist/hitl/parkRowBirthWait.js

@@ -0,0 +1,192 @@
+/**
+ * hitl/parkRowBirthWait.ts — 「park 的待决行**还没出生**」这个第三态的有界等待(#265 上收件,
+ * 2026-08-14;源形 = cli `src/sema/parkRowBirthWait.ts`,该文件自设计起就按候上收形写成零依赖)。
+ *
+ * ── 病(cli #269,plan 批准 → write 卡永不呈现)──────────────────────────────────────────────
+ * `/v1/approvals` 的 pending 表里**没有**某个 park 的行,过去被单义化成「这件事已经决了」。
+ * 真实世界有第三态:引擎刚被推进到下一只门,而门的行要等一次真实模型调用(实测 ~3s:plan
+ * 批准 → 模型算出 Write 的参数 → 才铸审批行)才落库。在那个窗里读到的空表既不是「已决」
+ * 也不是「没有这件事」,而是**还没出生**。
+ * 把「未出生」当「已决」的代价 = 客户端按成功收口 → 呈现回执永远等不到 → 上一句「没能重开
+ * 这张卡」的降级话,而那张卡三秒之后真的出生了却再没人去接 —— 用户看到的是会话死了。
+ *
+ * ── 这个模块是什么 ──────────────────────────────────────────────────────────────────────────
+ * 把「行不在表」拆成**三态**并给一个有界、可中断的重查环:
+ *   · `row`     —— 拿到一行可决断的行(唯一可以往下走的态);
+ *   · `unborn`  —— 此刻没有可决断的行,但**没有任何正面证据**说明这件事已经了结 ⇒ 值得再看一眼;
+ *   · `settled` —— 有正面证据说明这里没有本臂该决的事(如行在但门种不属本臂)⇒ 等待零意义,立即收口。
+ * 判据纪律:`settled` 必须由**正面证据**得出;缺席本身永远只能得 `unborn`
+ * (「不知道」不许渲成「已完成」)。
+ *
+ * ── 边界(承重,别削)────────────────────────────────────────────────────────────────────────
+ *   · **恒至少探一次**:`budgetMs <= 0` ⇒ 恰一次 probe,行为与「不等」逐字相同(存量判决不漂,
+ *     也让测试能把等待窗调成 0 拿回旧语义)。
+ *   · **有界**:总窗 `budgetMs` 封顶,轮询间隔 `intervalMs`;窗尽如实回 `unborn`(不是回
+ *     `settled` —— 等不到不等于已决,降级话在这一刻才是真话)。
+ *   · **真可中断**:每一轮 probe 前、每一次 sleep 后都读 `signal.aborted`;缺省 sleep 自身也吃
+ *     signal(包内共享叶 `abortableSleep`,不另铸第二份等待原语)。
+ *   · **绝不裸固定拍当判据**:sleep 只是轮询节奏,判决恒来自下一次 probe 的真实读数。
+ *   · probe 抛错按 `unborn` 处置(瞬时读面故障不该把有界重查提前判死),错误摘要进 reason ——
+ *     调用方只在 debug 档消费,绝不上屏(凭证外溢面纪律)。
+ *
+ * ── 归层 ────────────────────────────────────────────────────────────────────────────────────
+ * 「一条 park 的待决行到底出生了没有」是 wire 语义,三端(cli / desktop / web)都要问同一句;
+ * 各端只注入自己的读面(cli = `approvals.list` + 归属判据),环本身共用这一份。行形走结构泛型,
+ * 读面/时钟/sleep 全部注入 —— 本文件值级 import 只有包内 `abortableSleep`,零 SDK 零宿主。
+ */
+import { abortableSleep } from '../abortableSleep.js';
+/**
+ * 缺省轮询等待:signal 在场时直接借包内共享叶 {@link abortableSleep}(中止即刻 resolve 并清
+ * timer),缺席时退化成纯定时。
+ *
+ * 🔴 **不另铸第二份等待原语**:仓内「怎么安全地睡一觉」只此一份(`abortableSleep.ts` 的头注
+ * 写死了这条 —— D 族循环各自保留自己的节拍策略,但等待原语统一)。两份并存的代价不是重复代码,
+ * 是两条会各自漂的中止语义。
+ * 🔴 timer **不 unref**(与 abortableSleep 同判据):调用方正 await 本环拿判决,轮询窗里这只
+ * timer 可能是事件循环里唯一的活,unref 会让进程在等待中途直接退出、判决连同它要说的那句真话
+ * 一起蒸发。代价上限 = 一个 intervalMs 的进程存活延长。
+ */
+function parkRowPollDelay(ms, signal) {
+    // 无 signal 的调用方(端没接中断口)也走同一个叶:给它一只**永不 abort** 的 signal,而不是就地
+    // 再写一个裸 setTimeout —— 那就是第二份等待原语的起点。
+    return abortableSleep(ms, signal ?? new AbortController().signal);
+}
+/**
+ * 有界、可中断地等一条 park 的待决行出生。语义与边界见文件头;绝不抛。
+ *
+ * 🔴 判决只有 `row` 一态可以往下走 —— `unborn`(窗尽)与 `aborted` 都必须由调用方翻成**如实的
+ * 失败**,绝不许翻成「已决/已成功」(那正是 cli #269 的病)。
+ */
+export async function waitForParkRowBirth(deps) {
+    const now = typeof deps.now === 'function' ? deps.now : () => Date.now();
+    const sleep = typeof deps.sleep === 'function' ? deps.sleep : parkRowPollDelay;
+    const budgetMs = Number.isFinite(deps.budgetMs) && deps.budgetMs > 0 ? deps.budgetMs : 0;
+    const intervalMs = Number.isFinite(deps.intervalMs) && deps.intervalMs > 0 ? deps.intervalMs : 1;
+    const startedAt = now();
+    let probes = 0;
+    let lastReason = 'no decidable pending row for this park';
+    // 🔴 经函数读,别直接读 `deps.signal?.aborted`:tsc 的控制流分析会拿环顶那一次判断把它窄成
+    // `false | undefined`,sleep 之后的第二次判断当场被判「不可能为 true」而报错 —— 而真实世界里
+    // 正是 sleep 期间它会翻。函数返回值走声明类型,不参与那条窄化链。
+    const aborted = () => deps.signal?.aborted === true;
+    /** 一拍探测(读面故障按 unborn,绝不外溢)。 */
+    const safeProbe = async (attempt, signal) => {
+        try {
+            return await deps.probe(attempt, signal);
+        }
+        catch (e) {
+            // 读面瞬时故障 ≠ 已决:按未出生继续轮询(有界,窗尽自然如实收口)。
+            return { kind: 'unborn', reason: `probe threw: ${String(e)}` };
+        }
+    };
+    /**
+     * 🔴 把**剩余预算**套在每一拍 probe 上:deadline 只在 `await probe` **之后**判,等于什么都没
+     * 界住 —— 一次挂死的 `approvals.list` 能把「15s 有界」拖到 SDK 请求超时那么长,而中断也要等
+     * 那个 promise 落地才被看见。这里给每一拍配一个内部 controller:窗尽即 abort(读面真被掐,
+     * 不只是被放弃)并当拍判窗尽;外部 signal 与它合流,Esc 同样当拍生效。
+     * 零窗形(budgetMs<=0)**不设**内部 deadline —— 那一拍就是「修前那一次 list」,不许被新机制改语义。
+     */
+    const probeWithinRemaining = async (attempt, remainingMs) => {
+        if (budgetMs <= 0)
+            return safeProbe(attempt, deps.signal);
+        const ctl = new AbortController();
+        let timer;
+        const deadline = new Promise(resolve => {
+            timer = setTimeout(() => {
+                ctl.abort();
+                resolve('deadline');
+            }, Math.max(1, remainingMs));
+        });
+        // 🔴 外部中断**自己也是竞速的一臂**,不能只靠「signal 传下去 ⇒ 读面自己会拒」:那是对 probe
+        // 实现的一个假设,而假设不成立时(probe 吞了 signal / 读面 abort 得慢)Esc 之后这一拍要一直
+        // 等到窗尽才被看见 —— 「UI 说停了、后台还在等」正是本模块承诺不会发生的那件事。
+        const caller = deps.signal;
+        /**
+         * 把中止**传导到真正交给 probe 的那只 signal**(清理动作:它自己的异常绝不挡住中止判决)。
+         * 🔴 承重理由:`AbortSignal.any` 缺席的宿主上 `merged` 就是 `ctl.signal`,而外部中断只赢竞速、
+         * 不会传导到它 —— finally 又把 deadline timer 清了,于是那一拍挂死的读面**永远**不会被 abort
+         * (判决说「停了」,后台请求活到进程结束)。两个中止入口(进拍即已中断 / 等待期间翻)共用这一份。
+         */
+        const abortProbeLane = () => {
+            try {
+                ctl.abort();
+            }
+            catch {
+                /* abort 面异常绝不挡住中止判决(唯一后果是那一拍的读面少收一次 abort) */
+            }
+        };
+        let onAbort;
+        const externalAbort = new Promise(resolve => {
+            if (caller === undefined)
+                return; // 永不 settle:race 另有两臂,无害
+            if (caller.aborted) {
+                // 进这一拍时就已中断 ⇒ probe 拿到的那只 signal 必须是**已中止**的(一个不查 `aborted`、
+                // 只挂 'abort' 事件的读面否则会一直挂着)。
+                abortProbeLane();
+                resolve('aborted');
+                return;
+            }
+            // 🔴 先传导中止**再** resolve(见 {@link abortProbeLane}):否则「可中断」只是判决面的说法。
+            onAbort = () => {
+                abortProbeLane();
+                resolve('aborted');
+            };
+            try {
+                caller.addEventListener('abort', onAbort, { once: true });
+            }
+            catch {
+                onAbort = undefined; // 没有事件面的 signal 形:退化成环顶那次 aborted() 读
+            }
+        });
+        // 合流(Node ≥20.3 / 现代浏览器原生);缺席时退化成只吃内部 deadline —— 中止仍由上面那一臂
+        // 当拍生效。`typeof` 探的是**运行期**在场,不是类型面缺口。
+        const merged = caller !== undefined && typeof AbortSignal.any === 'function' ? AbortSignal.any([caller, ctl.signal]) : ctl.signal;
+        try {
+            return await Promise.race([safeProbe(attempt, merged), deadline, externalAbort]);
+        }
+        finally {
+            // timer 必清:竞速由 probe 赢时它还挂着,不清会把进程按 remainingMs 拖活一拍。
+            if (timer !== undefined)
+                clearTimeout(timer);
+            // 监听器必摘:环可以跑几十拍,不摘就是几十个挂在调用方 signal 上的闭包。
+            if (onAbort !== undefined && caller !== undefined) {
+                try {
+                    caller.removeEventListener('abort', onAbort);
+                }
+                catch {
+                    /* 监听面异常绝不反噬等待环 */
+                }
+            }
+        }
+    };
+    for (;;) {
+        if (aborted())
+            return { kind: 'aborted', waitedMs: now() - startedAt, probes };
+        probes += 1;
+        const outcome = await probeWithinRemaining(probes, budgetMs - (now() - startedAt));
+        // 读面挂着的时候用户按了 Esc ⇒ 当拍停(判决优先于窗尽,两者都成立时中断更准确)。
+        if (outcome === 'aborted' || aborted())
+            return { kind: 'aborted', waitedMs: now() - startedAt, probes };
+        if (outcome === 'deadline') {
+            return {
+                kind: 'unborn',
+                reason: `${lastReason} (the last read face did not answer within the remaining window)`,
+                waitedMs: now() - startedAt,
+                probes,
+            };
+        }
+        const probed = outcome;
+        if (probed.kind === 'row')
+            return { kind: 'row', row: probed.row, waitedMs: now() - startedAt, probes };
+        if (probed.kind === 'settled') {
+            return { kind: 'settled', reason: probed.reason, waitedMs: now() - startedAt, probes };
+        }
+        lastReason = probed.reason;
+        const remainingMs = budgetMs - (now() - startedAt);
+        if (remainingMs <= 0)
+            return { kind: 'unborn', reason: lastReason, waitedMs: now() - startedAt, probes };
+        await sleep(Math.min(intervalMs, remainingMs), deps.signal);
+        if (aborted())
+            return { kind: 'aborted', waitedMs: now() - startedAt, probes };
+    }
+}

package/dist/hitl/planReviewWire.d.ts

@@ -37,6 +37,7 @@
  * app-state seam 不在本模块可达面,记 rc.47 接 REPL 层;engine 侧 handsReadOnly 已由 resume 处理。
  */
 import { type QuestionAnswer } from '../liveQuestionStore.js';
+import type { ReopenCardVerdict } from '../adapter/activeRunSelfHeal.js';
 /**
  * REF-CC-026:此前是 module-private 常量,唯一另一个消费者(cli `planReviewReopen.ts`)只能靠
  * 人眼手抄同步(头注写着「与 client-core planReviewWire 的原卡逐字一致」)——漂一个字节,判决就
@@ -73,3 +74,53 @@ export declare function armPlanReviewApproval(result: unknown): boolean;
  *  server body.error 原文)→ 同款「HTTP <status> <error>」outcome 文案;网络失败走原「could not
  *  reach the engine」臂。 */
 export declare function decidePlanReview(taskId: string, decision: 'approve' | 'reject'): Promise<void>;
+/**
+ * {@link reopenPlanReviewCard} 的宿主参数。
+ */
+export interface ReopenPlanReviewOpts {
+    /**
+     * 宿主 overlay 是否按 questionId 做会话级去重(cli REPL 的 overlay 钩子 = true:它有一个
+     * `seenQuestionIds` 集,为的是 at-least-once wire 的重投不把 hook 跑第二遍 —— 拿 canonical id
+     * 再发一次,帧会被静默吃掉,「重开了」就成了假话)。
+     *   · `true`(缺省,两类宿主都安全):重开铸**每次都不同**的身份 `plan-review:<taskId>#reopen-*`;
+     *   · `false`:responder 仍绑着时按 canonical id 原样重呈(同一张卡、同一个 responder ——
+     *     与 arm 臂的重放重呈短路同形),不产生第二次 responder 注册。
+     */
+    mintFreshQuestionId?: boolean;
+    /**
+     * 决断投递口(缺省 = 包内 `decidePlanReview` fire-and-forget,自带 outcome 通知管道)。
+     * 宿主要包一层重试/上屏编排(如 cli 的短退避恰一次重试腿)就从这里注入 —— 卡链/三态判决
+     * 单源在包,投递编排留端。
+     * 🔴 成文例外(0.29.0 发包扫描门):`mintFreshQuestionId:false` 且 canonical(arm)responder
+     * 仍绑着时走「同 id 重呈短路臂」——作答经 **arm 的既有 responder** 投递(缺省 decidePlanReview),
+     * 本注入口**不生效**(短路臂命中时 debug 留痕)。要保证注入口恒生效就走缺省 mintFresh 臂。
+     */
+    deliverDecision?: (taskId: string, decision: 'approve' | 'reject') => void | Promise<void>;
+    /**
+     * 多会话宿主的会话键(复审 [high] 补口;缺省 = DEFAULT_SESSION_KEY,cli 单会话装配零参不动)。
+     * overlay 在场检查 / 帧发布 / 呈现台账读写全部按此键走 `*For` 变体 —— 不传就落默认键,
+     * 多会话宿主不传 = 帧和台账都路由到别的会话的默认面,所以它们**必须**传自己的键。
+     * (`registerLocalQuestionResponder` 的 responder 表是进程级单表、id 全局唯一,不分键。)
+     * 🔴 已知局限(0.29.0 发包扫描门,候跟进票):`armPlanReviewApproval` 的 arm 臂是**默认会话**
+     * 装配(无 sessionKey 形参),其 responder 递交决断时清账走默认键 —— 非默认键会话对同一
+     * taskId 混用 arm 臂 + `mintFreshQuestionId:false` 重呈臂时,该键会话槽的呈现史不被消费
+     * (影响=后续首见/复见**文案**判定,动作两形一致)。多会话宿主避开该组合(用缺省 mintFresh)
+     * 或候 armPlanReviewApproval 补 sessionKey 位。
+     */
+    sessionKey?: string;
+}
+/** 测试钩:清空重开 responder 台账(跨用例状态)。 */
+export declare function _resetActiveReopenRespondersForTest(): void;
+/**
+ * 重开某个 parked plan_review 的审批卡(409 自愈分诊树 `attemptActiveRunSelfHeal` 的
+ * `reopenPlanReview` 注入口的包内生产实现)。判决形/成文语义见 {@link ReopenCardVerdict}
+ * (`adapter/activeRunSelfHeal.ts`);本函数不产 `presented` 位 —— 包看不到像素,回执机制归
+ * 宿主端包装。绝不抛(turn 收尾路径)。
+ *
+ * 与 arm 臂的合成关系(A-028.4):首呈(done 帧)= `armPlanReviewApproval`;重开(409 撞锁)=
+ * 本函数。两臂共用同一份题面构造点/标签单源/决断三态判决与同一条 `decidePlanReview` 投递管道;
+ * 「铸新 questionId 还是复用同 id」由宿主去重语义作参数(见 {@link ReopenPlanReviewOpts})。
+ * firstSight 判据 = 呈现台账(`armedGateRegistry`,键 = canonical `plan-review:<taskId>`);
+ * 先查后记 —— 顺序决定判决正确性。
+ */
+export declare function reopenPlanReviewCard(taskId: string, opts?: ReopenPlanReviewOpts): ReopenCardVerdict;

package/dist/hitl/planReviewWire.js

@@ -36,11 +36,14 @@
  * 挂账(诚实边界):approve 后壳本地的 plan-mode footer 徽章不自动退(CC 会退)——退 mode 的
  * app-state seam 不在本模块可达面,记 rc.47 接 REPL 层;engine 侧 handsReadOnly 已由 resume 处理。
  */
-import { publishQuestionFrame, registerLocalQuestionResponder, hasLocalQuestionResponder, } from '../liveQuestionStore.js';
+import { publishQuestionFrame, publishQuestionFrameFor, registerLocalQuestionResponder, unregisterLocalQuestionResponder, hasLocalQuestionResponder, hasQuestionOverlayFor, } from '../liveQuestionStore.js';
 import { hostLog } from '../host.js';
 import { makeEngineWireClient } from '../engineWireSdk.js';
 import { engineWireTarget } from '../engineWireTarget.js';
 import { enqueuePlanReviewOutcome } from '../notifications.js';
+import { planReviewQuestionId, REOPEN_ID_TAIL } from './gateIdentity.js';
+import { clearArmedGate, clearArmedGateFor, registerArmedGateFor, wasGateArmedFor } from './armedGateRegistry.js';
+import { DEFAULT_SESSION_KEY } from '../sessionSlot.js';
 /** resume 是 SYNC 驱动到终态的(可能分钟级)——原 raw fetch 无超时;SDK Transport 恒有每请求
  *  超时,取 6h 宽上界(诚实预算:超过它基本是引擎僵死,超时文案与网络失败同走 outcome 通知)。 */
 const PLAN_REVIEW_RESUME_TIMEOUT_MS = 6 * 60 * 60_000;
@@ -92,26 +95,32 @@ const armedPlanReviewTaskIds = new Set();
 export function _resetArmedPlanReviewsForTest() {
     armedPlanReviewTaskIds.clear();
 }
-/** 合成 questionId 的唯一铸口(短路臂与首次 arm 共用,别各铸各的)。 */
-function planReviewQuestionId(taskId) {
-    return `plan-review:${taskId}`;
+/* 合成 questionId 的唯一铸口:A-028.3 起收编进 `gateIdentity.planReviewQuestionId`(公面导出,
+ * 壳侧重开腿从此 import 同一铸口,不再手抄字面)。本文件只 import,不再自铸。 */
+/** 首次 arm 的题面正句。 */
+const ARM_QUESTION = 'The plan is ready for review. Approve it and start the implementation?';
+/** 重开腿的题面正句(点明「这张卡就是占住会话的那件事」;标签/选项与首呈同源)。 */
+const REOPEN_QUESTION = 'This plan is still waiting for your review — it is what is holding this session. Approve it and start the implementation?';
+/** 题面唯一构造点 —— 首次 arm、重放重呈、重开三处共用,标签/选项描述不许各写一份。 */
+function planReviewQuestions(question) {
+    return [
+        {
+            header: 'Plan review',
+            question,
+            options: [
+                { label: APPROVE_LABEL, description: 'Resume the task now and execute the plan (runs to completion engine-side)' },
+                { label: REJECT_LABEL, description: 'Discard this plan and stay in plan mode to refine it' },
+            ],
+            multiSelect: false,
+        },
+    ];
 }
-/** 审批卡的题面 —— 首次 arm 与「重放 arm 重新弹卡」共用同一份,两处不许各写一份。 */
+/** 审批卡的发布口 —— 首次 arm 与「重放 arm 重新弹卡」共用同一份(canonical 身份)。 */
 function publishPlanReviewCard(taskId) {
     publishQuestionFrame({
         type: 'question',
         questionId: planReviewQuestionId(taskId),
-        questions: [
-            {
-                header: 'Plan review',
-                question: 'The plan is ready for review. Approve it and start the implementation?',
-                options: [
-                    { label: APPROVE_LABEL, description: 'Resume the task now and execute the plan (runs to completion engine-side)' },
-                    { label: REJECT_LABEL, description: 'Discard this plan and stay in plan mode to refine it' },
-                ],
-                multiSelect: false,
-            },
-        ],
+        questions: planReviewQuestions(ARM_QUESTION),
     });
 }
 /**
@@ -128,6 +137,11 @@ export function armPlanReviewApproval(result) {
         if (!engineWireTarget())
             return false;
         const { taskId } = result;
+        // 单活纪律(复审二轮,与 reopen 侧对偶):arm/重呈要发的 canonical 卡从此是这个 gate 唯一的
+        // 作答入口 —— 名下还在场的重开卡先退役(注销 responder + 撤帧)。不退役的话,durable 重放的
+        // arm 会在 fresh 重开卡还开着时再立一张 canonical 卡,双活双投递面从 arm 侧复发。
+        // (arm 臂是默认会话装配,退役也按默认键;多会话宿主的 arm 路径归后续工单。)
+        retireActiveReopen(DEFAULT_SESSION_KEY, planReviewQuestionId(taskId));
         if (armedPlanReviewTaskIds.has(taskId)) {
             // REF-CC-027:同一张卡还没消解就被重放的 arm 撞上——幂等,**不二次注册** responder。
             //
@@ -165,9 +179,15 @@ export function armPlanReviewApproval(result) {
             const decided = planReviewDecisionFromAnswer(answer);
             if (decided === 'dismissed') {
                 // dismiss/无法判读:诚实缺席优先于编造默认值(REF-CC-026)——不静默驱动 decidePlanReview,
-                // 卡的重开路径把决定权还给用户。
+                // 卡的重开路径把决定权还给用户。呈现台账的键**不清**:同一张卡再被重开就是真「reopened」。
                 return { ok: true };
             }
+            // A-024.4(键粒度收口):plan 键 = `plan-review:<taskId>`,粒度是 taskId 不是 gate ——
+            // 决断一经递交,这个门的呈现史就消费掉;同 run 的**下一个** plan gate(approve 推进后
+            // 引擎可再 park 一个新 plan)必须读回首见,否则文案对一张从未呈现过的新卡说「reopened」。
+            // 递交后决定未生效的形(RB-471 族)读回首见只损失「reopened」一词 —— 首见文案零历史断言,
+            // 诚实方向安全。
+            clearArmedGate(planReviewQuestionId(taskId));
             // fire-and-forget:resume 同步驱动到终态可能分钟级,不能挂住 overlay;结果经 queue 通知回来
             void decidePlanReview(taskId, decided);
             return { ok: true };
@@ -287,3 +307,138 @@ export async function decidePlanReview(taskId, decision) {
         hostLog('debug', `planReviewWire: outcome enqueue threw: ${String(e)}`);
     }
 }
+/** 重开身份的进程内唯一尾缀(时基 + 随机段:两份包实例同时铸也不撞键 —— 撞键会被宿主 overlay
+ *  的去重集吃掉帧,重开静默变 no-op;所以刻意不用模块级计数器)。 */
+function reopenIdSuffix() {
+    return `${Date.now().toString(36)}${Math.random().toString(36).slice(2, 8)}`;
+}
+/**
+ * 每个 `(sessionKey, canonicalId)` **至多一个在场的重开 responder**(复审 [high]:此前每次重开
+ * 都新注册一个 responder 而不退役上一个 —— 重试/并发 409 会留下两张都能投递决断的活卡,
+ * 一张 approve 一张 reject 就是两次相互冲突的状态变更请求)。铸新卡前:退役上一张的 responder +
+ * 对它的帧 id 发 `question_complete` 撤卡;作答/退役后清账。
+ * 🔴 模块级单例(singleton-manifest 登记):两份实例 ⇒ 各退各的,跨份的旧卡退役不掉 ——
+ * 退化回修复前的重复活卡形。
+ */
+const activeReopenResponders = new Map();
+/** 退役 `(sessionKey, canonicalId)` 名下还在场的重开 responder(撤帧 + 注销 + 清账)。 */
+function retireActiveReopen(sessionKey, canonicalId) {
+    const key = `${sessionKey}\u0000${canonicalId}`;
+    const prev = activeReopenResponders.get(key);
+    if (!prev)
+        return;
+    activeReopenResponders.delete(key);
+    try {
+        prev.unregister();
+    }
+    catch {
+        // 注销钩自身的意外 throw 不许挡住新卡铸造(退役面 fail-soft,新卡才是用户的把手)
+    }
+    publishQuestionFrameFor(sessionKey, { type: 'question_complete', questionId: prev.questionId });
+}
+/** 测试钩:清空重开 responder 台账(跨用例状态)。 */
+export function _resetActiveReopenRespondersForTest() {
+    activeReopenResponders.clear();
+}
+/**
+ * 重开某个 parked plan_review 的审批卡(409 自愈分诊树 `attemptActiveRunSelfHeal` 的
+ * `reopenPlanReview` 注入口的包内生产实现)。判决形/成文语义见 {@link ReopenCardVerdict}
+ * (`adapter/activeRunSelfHeal.ts`);本函数不产 `presented` 位 —— 包看不到像素,回执机制归
+ * 宿主端包装。绝不抛(turn 收尾路径)。
+ *
+ * 与 arm 臂的合成关系(A-028.4):首呈(done 帧)= `armPlanReviewApproval`;重开(409 撞锁)=
+ * 本函数。两臂共用同一份题面构造点/标签单源/决断三态判决与同一条 `decidePlanReview` 投递管道;
+ * 「铸新 questionId 还是复用同 id」由宿主去重语义作参数(见 {@link ReopenPlanReviewOpts})。
+ * firstSight 判据 = 呈现台账(`armedGateRegistry`,键 = canonical `plan-review:<taskId>`);
+ * 先查后记 —— 顺序决定判决正确性。
+ */
+export function reopenPlanReviewCard(taskId, opts) {
+    try {
+        if (typeof taskId !== 'string' || taskId.length === 0)
+            return { reopened: false };
+        const sessionKey = opts?.sessionKey ?? DEFAULT_SESSION_KEY;
+        // 诚实边界:请求方会话没有 overlay 订阅者(headless / 尚未挂载)⇒ 返回 false,调用方如实说
+        // 「没能重开」。overlay 在场答的是「有没有一个 UI 会收到这一帧」;检查按 sessionKey 走 ——
+        // 别的会话挂着 overlay 不等于本会话的卡有地方渲(复审 [high]:默认键硬走会把帧投进别人的面)。
+        if (!hasQuestionOverlayFor(sessionKey))
+            return { reopened: false };
+        const canonicalId = planReviewQuestionId(taskId);
+        // 先查(firstSight)后记(铸卡即 arm)—— 顺序决定判决正确性;台账按 sessionKey 分账。
+        const firstSight = !wasGateArmedFor(sessionKey, canonicalId);
+        const mintFresh = opts?.mintFreshQuestionId !== false;
+        if (!mintFresh && hasLocalQuestionResponder(canonicalId)) {
+            // 重呈短路(与 arm 臂的重放短路同形):同一个 canonical 身份、同一份题面、同一个 responder。
+            // 卡还开着的宿主只是收到一帧同形重绘,卡已被 dismiss 的宿主拿回重开路径。
+            // 0.29.0 发包扫描门:本臂沿用 arm responder ⇒ opts.deliverDecision 不生效(JSDoc 成文例外),
+            // 传了就留痕 —— 静默吞注入口是契约不一致的形。
+            if (opts?.deliverDecision !== undefined) {
+                hostLog('debug', `planReviewWire: reopen canonical-reuse branch for task ${taskId} ignores opts.deliverDecision (answers route through the existing arm responder — documented exception)`);
+            }
+            // 先退役本会话名下还在场的**重开**卡(如此前走过 mintFresh 臂)—— 同一 gate 不留两张活卡。
+            retireActiveReopen(sessionKey, canonicalId);
+            publishQuestionFrameFor(sessionKey, {
+                type: 'question',
+                questionId: canonicalId,
+                questions: planReviewQuestions(ARM_QUESTION),
+            });
+            registerArmedGateFor(sessionKey, canonicalId);
+            return { reopened: true, firstSight };
+        }
+        // 复审 [high] 单活纪律(两轮收紧):铸新卡前退役**全部**旧作答入口 —— 同一个 gate 至多一张
+        // 能投递决断的卡,两张都活着时一张 approve 一张 reject = 两次相互冲突的状态变更请求。
+        //   · 上一张重开卡:注销 responder + question_complete 撤帧(单活台账);
+        //   · canonical(arm)卡:question_complete 撤帧**且按 id 注销 responder**(二轮 [high]:
+        //     撤帧只是 UI 动作,表里的 responder 不死,在途的迟到作答仍能经它投递)。canonical
+        //     responder 死后,arm 重放走它自己的「陈旧武装态 ⇒ 整条重新 arm」自愈臂([2393] hitl-F3),
+        //     不会留下弹不出卡的死短路。
+        retireActiveReopen(sessionKey, canonicalId);
+        if (unregisterLocalQuestionResponder(canonicalId)) {
+            hostLog('debug', `planReviewWire: reopen retired the canonical responder for task ${taskId} (single-active discipline)`);
+        }
+        publishQuestionFrameFor(sessionKey, { type: 'question_complete', questionId: canonicalId });
+        const questionId = `${canonicalId}${REOPEN_ID_TAIL}${reopenIdSuffix()}`;
+        const deliver = opts?.deliverDecision ??
+            ((tid, decision) => {
+                // fire-and-forget:resume 同步驱动到终态可能分钟级,不能挂住 overlay(arm 臂同姿势);
+                // 失败处置/结果回植由 decidePlanReview 自带的 outcome 管道承担。
+                void decidePlanReview(tid, decision);
+            });
+        const activeKey = `${sessionKey}\u0000${canonicalId}`;
+        const unregister = registerLocalQuestionResponder(questionId, async (_id, answer) => {
+            unregister(); // 一次性(arm 臂同款):respond 侧 delete-before-invoke 之外的第二道钉
+            // 单活台账清账(只清**自己**的条目 —— 自己被更新的重开取代后,旧 responder 的迟到作答
+            // 不许把新卡的条目清掉)。
+            if (activeReopenResponders.get(activeKey)?.questionId === questionId) {
+                activeReopenResponders.delete(activeKey);
+            }
+            const decided = planReviewDecisionFromAnswer(answer);
+            if (decided === 'dismissed') {
+                // 三态(REF-CC-026):dismiss/读不出不驱动 decidePlanReview;呈现台账不清 ——
+                // 这张卡再被重开就是真「reopened」。
+                return { ok: true };
+            }
+            // A-024.4:决断递交即消费呈现史(与 arm 臂 responder 同点,理由见那里)。
+            clearArmedGateFor(sessionKey, canonicalId);
+            try {
+                await deliver(taskId, decided);
+            }
+            catch (e) {
+                // 投递编排是注入方的职责面(缺省臂自带 outcome 管道不会走到这);这里只留痕,
+                // 绝不把宿主投递臂的 throw 冒进 overlay 的 respond 链。
+                hostLog('error', `planReviewWire: reopen decision delivery threw for task ${taskId}: ${String(e)}`);
+            }
+            return { ok: true };
+        });
+        activeReopenResponders.set(activeKey, { questionId, unregister });
+        registerArmedGateFor(sessionKey, canonicalId);
+        publishQuestionFrameFor(sessionKey, {
+            type: 'question',
+            questionId,
+            questions: planReviewQuestions(REOPEN_QUESTION),
+        });
+        return { reopened: true, firstSight };
+    }
+    catch {
+        return { reopened: false }; // 重开失败绝不炸 turn —— 调用方会如实说「没能重开」
+    }
+}

package/dist/hitl/resumeRunningCard.d.ts

@@ -0,0 +1,134 @@
+/**
+ * hitl/resumeRunningCard.ts — **resume 撞上「上一轮还在跑」**时那张三选卡的判定 / 选项集 / 文案
+ * (#265 上收件,2026-08-14;源形 = cli `src/sema/resumeRunningArm.ts` 的纯判定半场,编排腿留在端上)。
+ *
+ * ── 病与改形 ────────────────────────────────────────────────────────────────────────────────
+ * resume 时读到一条 `running` 的 run,旧形是**客户端自己**给它打一枪 cancel(动机 = 僵尸烧 token)。
+ * 矛盾:resume 时的 running run **不可判**是「用户要的在飞工作」还是「僵尸」—— 而实况里自动 cancel
+ * 恰好是错的方向(用户批准之后 run 该继续跑,resume 时 cancel = 把刚救活的 run 又杀了)。血统纪律:
+ * **破坏性动作恒不自动**。改形 = 把三条路交回用户:
+ *   ① `Attach and watch`  —— 接管为当前 turn 输出;
+ *   ② `Cancel it`         —— 那个动作降级为**用户按下**的选项;
+ *   ③ `Leave it running in the background`(**默认焦点**)—— 零动作。
+ *
+ * ── §3.2a 活性证据的缺席纪律(不可削)──────────────────────────────────────────────────────
+ * 判活体的 `msSinceLastActivity`(相对毫秒)在场 ⇒ 卡上渲一行「last activity Ns ago」;
+ * **缺席 = 无法证明**(跨副本命中 / 副本重启后),不是「不活」—— 那一行**整行不渲**,绝不折成 0、
+ * 绝不写成「已死」。
+ *
+ * ── §3.2b 无 UI 臂:退役自动 cancel 之后不许留死墙 ──────────────────────────────────────────
+ * 「不自动 cancel + 没有卡可选」= 又一堵死墙。所以没有卡的形必须**显式定义臂**:恒不 cancel;
+ * 输出**机读三选指路**({@link resumeRunningNoUiGuidance},attach / cancel / 后台留着三条路各给
+ * 真实命令或 API 路径);headless 车道走**专码**退出({@link RESUME_RUNNING_NO_UI_EXIT_CODE});
+ * 绝不静默挂起、绝不谎报成功。
+ *
+ * ── 🔴 塌缩纪律 ─────────────────────────────────────────────────────────────────────────────
+ * Esc / 空答 / 认不出的自由文本 / 作答看门狗到点 / 呈卡失败 —— 一律收口成 ③(零动作)。
+ * 破坏性动作只认**逐字命中**的显式选择({@link resumeChoiceFromLabels})。
+ *
+ * ── 🔴 假 affordance 禁令(按供给渲)───────────────────────────────────────────────────────
+ * 一个按了没用的选项比没有这个选项更坏:durable `runs.events` 动词缺席**或**没有接管消费口 ⇒
+ * ① 整个不渲;`runs.cancel` 缺席 ⇒ ② 整个不渲;两条都缺 ⇒ 一张卡都不铸,走 §3.2b 臂。
+ *
+ * ── 归层 ────────────────────────────────────────────────────────────────────────────────────
+ * 本文件 = 纯判定 + 选项集 + 文案,**零 import**。呈卡口/动词切片/判活口/指路 sink/退出码应用口
+ * 全部由端在装配点注入;端只剩装配与呈现。
+ */
+/** ① 接管观看。 */
+export declare const RESUME_CHOICE_ATTACH_LABEL = "Attach and watch";
+/** ② 用户显式取消(自动 cancel 那个动作的降级形)。 */
+export declare const RESUME_CHOICE_CANCEL_LABEL = "Cancel it";
+/** ③ 后台留着 —— 🔴 **默认焦点**,所以它必须排在 options[0](见 {@link resumeRunningOptions})。 */
+export declare const RESUME_CHOICE_BACKGROUND_LABEL = "Leave it running in the background";
+/** 卡的 header(答案按 header 归键;本卡只有一问)。与 409 三选卡的入口刻意不同词 —— 同一张卡的
+ *  两个入口,题面说的不是一件事。 */
+export declare const RESUME_CHOICE_HEADER = "Earlier run still in flight";
+/** 用户在 resume 变体卡上的决定。 */
+export type ResumeRunningChoice = 'attach' | 'cancel' | 'background';
+/**
+ * 呈卡口的回执。🔴 `'unavailable'` 与 `'background'` **绝不合并**:前者 =「问都没问成」
+ * (§3.2b 臂的入口:用户还欠一次告知),后者 =「问过了,用户选了什么都不做」(已经告知过)。
+ * 合并的代价 = 一次呈现失败被静默当成用户的决定 —— 那正是 §3.2b 要封的死墙。
+ */
+export type ResumeChoiceOutcome = ResumeRunningChoice | 'unavailable';
+/** 铸卡所需的全部材料(纯数据 —— 呈现层按它铸自己的卡/帧)。 */
+export interface ResumeRunningCardInput {
+    /** 那条还在跑的 run。 */
+    taskId: string;
+    /** 引擎报的状态(如实转述,不加工)。 */
+    status: string;
+    /** ① 可渲吗(= durable events 动词在场 **且** 有接管消费口)。 */
+    canAttach: boolean;
+    /** ② 可渲吗(= `runs.cancel` 在场)。 */
+    canCancel: boolean;
+    /** §3.2a 活性证据(null = 引擎没给 ⇒ 无法证明 ⇒ 那一行整行不渲)。 */
+    msSinceLastActivity: number | null;
+}
+/** 一个选项(CC AskUserQuestionTool option 形)。 */
+export interface ResumeRunningCardOption {
+    label: string;
+    description: string;
+}
+/**
+ * §3.2a 活性证据行。**缺席 ⇒ null(整行不渲)**;绝不渲 0、绝不渲「已死」。
+ * 负数 / 非有限值同样按缺席处理(wire 位 UNTRUSTED,类型说是 number 也要真判)。
+ */
+export declare function resumeRunningLivenessRow(msSinceLastActivity: number | null | undefined): string | null;
+/**
+ * 卡的题面。第二行 = 活性证据(§3.2a 缺席时**整行消失**,不留占位、不留「unknown」字样 ——
+ * 一行「last activity: unknown」和一行 0 一样是在替引擎回答一个它没回答的问题)。
+ */
+export declare function resumeRunningQuestionText(i: ResumeRunningCardInput): string;
+/**
+ * 选项集(同一张卡两个入口,选项集**按入口分形**)。
+ *
+ * 🔴 **顺序即默认焦点**:卡的渲染面 `focusedIndex` 初值恒 0,而 wire 的 `QuestionFrame` 里
+ *    **没有**任何「默认焦点」位可传。所以「默认焦点 = ③ 后台留着」在结构上只有一个落法:把 ③ 排在
+ *    options[0]。谁哪天为了「读起来顺」把 ①②③ 按序号排回去,默认焦点就漂到了 `Attach and watch`
+ *    —— 一个手滑回车就把一条后台 run 接管到前台。常驻门逐位反钉这个顺序。
+ */
+export declare function resumeRunningOptions(i: ResumeRunningCardInput): ResumeRunningCardOption[];
+/**
+ * 答案 → 决定。🔴 只认**逐字命中**的标签;空答(overlay 的 Esc/dismiss 形)、多选、认不出的
+ * 自由文本一律回落 ③ —— 破坏性动作只认显式选择(与 409 三选卡同律)。
+ */
+export declare function resumeChoiceFromLabels(selected: readonly string[] | null | undefined): ResumeRunningChoice;
+/**
+ * headless 车道撞 resume-running 的**专码**退出码。
+ *
+ * 为什么非 0:这一趟 resume **没有**把会话交到一个可用状态 —— 那条 run 还占着会话,脚本接下来
+ * 提交什么都会撞 409。静默 0 = 谎报成功。
+ * 为什么是 75:sysexits.h 的 `EX_TEMPFAIL`(「暂时性失败,请稍后重试」)语义正对 —— run 跑完
+ * 或被取消之后同一条命令就能过;与 cli 既用的 0/1/2/129/143 零撞(脚本消费者据此可以把「会话被
+ * 在飞 run 占住」与「真失败(1)」「用法错(2)」分臂)。
+ */
+export declare const RESUME_RUNNING_NO_UI_EXIT_CODE = 75;
+/** 机读指路的行首标识 —— 脚本按它 grep;UI 改版不许动它。 */
+export declare const RESUME_RUNNING_GUIDANCE_TAG = "sema: resume-running:";
+/**
+ * §3.2b 的**机读三选指路**。三条路各给真实命令或 API 路径,一条都不许省 ——
+ * 少写一条 = 那条路在这个车道上被客户端单方面关掉了。
+ *
+ * 🔴 `attach=` 那一行只有在**真知道 session id** 时才给具体命令:不知道还硬拼一条
+ * `sema --resume <sessionId>` 字面量,就是印一条按了没用的命令(假 affordance 的文本形)。
+ */
+export declare function resumeRunningNoUiGuidance(i: {
+    taskId: string;
+    sessionId?: string | null;
+}): string;
+/**
+ * ① 接管之前的**显式披露**。
+ *
+ * resume 入口没有 `lastEventId` 可用(端今天不持久化引擎事件锚),所以 durable 尾从这条 run 的
+ * 第一帧读起 —— 崩溃前已落盘、已被 resume 还原到屏上的那一段会再渲一遍。续听腿那道「无锚 × 已上屏
+ * ⇒ 不许从头续读」的门在这一格判不出来(它数的是**本条流**吐过几帧,resume 入口恒 0),所以不能
+ * 拿它当安全证明。处置 = 说在前面:静默复读会让用户以为模型把同一段活干了两遍。
+ *
+ * 🔴 **账目面同源**:同一次重放也会把这条 run 已经执行过的每一个 `turn_end` 再喂一次成本累计器。
+ *    客户端这一端证明不了哪一枚已经在恢复出来的总额里(那需要一本按 turn 落盘的账 —— 与缺席的
+ *    事件锚是同一件移交残件),所以接管腿声明**不计账**。既然不计,就必须在**同一行**说清楚:
+ *    只披露视觉复读、不披露账目缺口,用户拿成本面跟引擎账本对不上时只会怀疑客户端算错了。
+ */
+export declare function resumeAttachReplayDisclosure(taskId: string): string;
+/** ② 打完 cancel 但引擎没确认落地时的如实一行(绝不谎报「已停止」)。 */
+export declare function resumeRunningCancelUnconfirmedRow(taskId: string): string;