@sema-agent/client-core 0.27.0 → 0.29.0

package/dist/hitl/armedGateRegistry.js

@@ -0,0 +1,92 @@
+/**
+ * armedGateRegistry.ts — per-session 呈现台账:哪些决断卡在**这个宿主进程的哪个会话**里真的
+ * 呈现过(A-028.3,#244 族A 包半场,2026-08-12;源形 = cli `src/sema/armedGateRegistry.ts`,
+ * 上收时由模块级单 Set 改为 sessionSlot per-session 键,支持多会话宿主)。
+ *
+ * ── 为什么需要它 ────────────────────────────────────────────────────────────────────────────
+ * 409 自愈重开臂(`adapter/activeRunSelfHeal.ts` 的分诊消费方)此前对每一张 pending 卡都说
+ * 「that card was closed without being answered, so sema reopened it」。但已定谳的机理链
+ * (plan approve → outcome enqueue 成新提交 → 引擎已推进到**新** gate → 该提交撞 409 →
+ * 重开腿铸出全新 pending 卡)里,那张卡是**首见**的 —— 从未被 arm 过,更谈不上 closed/
+ * reopened。文案对首见卡编造历史 = 对用户下一个证不出的断言。重开机制本身是设计内的
+ * surfacing 路径(承重,不动);本台账只供「说了什么」分形:firstSight 判据 = 这张卡的身份键
+ * 有没有在本进程本会话呈现过。
+ *
+ * ── 键的词汇(单源 = `gateIdentity.ts`,别自造字面)────────────────────────────────────────
+ *   · tool 审批卡:durable 腿 = `approvalCallKey(gatedCallId, taskId)`;live 帧腿 =
+ *     `liveFrameCallKey(approvalId)`(帧上无 gatedCallId,与 pending 行的 callId 天然对不上 ——
+ *     漏配的代价只是把「重开」说成「呈上」,首见文案零历史断言,诚实方向安全)。
+ *   · AskUserQuestion overlay:`askGateQuestionId(callKey)` 铸帧 id,本台账经
+ *     {@link registerArmedGateFromQuestionId} 剥前缀取键(= callKey,与卡键同域)。
+ *   · plan_review:`planReviewQuestionId(taskId)` 整串作键(保留前缀,与 taskId 直接作 ask 键
+ *     永不撞域);重开腿铸 `…#reopen-*`,归一化剥尾 —— 首呈与重开落同一键。
+ *
+ * ── 登记点(「没呈现就不算 arm」)───────────────────────────────────────────────────────────
+ *   ① 宿主呈现面:overlay 收到可渲染 question 帧时 / 卡口真把卡 enqueue 进渲染队列时,宿主调
+ *      {@link registerArmedGateFromQuestionId} / {@link registerArmedGate}(auto-allow/deny/
+ *      失败臂不登记)。包的 publish 点**不**代登记 —— publish 无 overlay 时是 no-op,代登记 =
+ *      把「发过帧」谎报成「呈现过」。
+ *   ② 重开腿:先读(firstSight 判决)后写(铸卡即 arm)—— 同一张卡第二次撞 409 才说 reopened。
+ *      包内 `planReviewWire.reopenPlanReviewCard` 与壳侧 ask 重开腿都按此序。
+ *   ③ 消费点:plan_review 决断**递交后**清键({@link clearArmedGate};A-024.4 —— 同 run 的下一
+ *      个 plan gate 必须读回首见,键粒度是 taskId,不清就把新门谎成复见)。ask 族键粒度是
+ *      callId(每 gate 唯一),无此问题,不清。
+ *
+ * per-session 语义:sessionSlot 注册表(desktop session-host 多引擎会话互不串账);零参 API =
+ * DEFAULT_SESSION_KEY 兼容层,单会话宿主(cli)装配一行不动。callId 全局唯一,跨 /clear 不撞键。
+ */
+import { createSessionSlot, DEFAULT_SESSION_KEY } from '../sessionSlot.js';
+import { armedKeyFromQuestionId } from './gateIdentity.js';
+// 🔴 模块级单例(singleton-manifest 登记):per-session 键 → 已呈现身份键集。
+const armedGatesByKey = createSessionSlot();
+function setFor(sessionKey) {
+    let s = armedGatesByKey.get(sessionKey);
+    if (!s) {
+        s = new Set();
+        armedGatesByKey.set(sessionKey, s);
+    }
+    return s;
+}
+/** 登记一个已呈现的决断卡身份键(空/非法输入静默忽略 —— 登记面绝不炸渲染链)。 */
+export function registerArmedGate(key) {
+    registerArmedGateFor(DEFAULT_SESSION_KEY, key);
+}
+/** W1 带 key 变体(多会话宿主每会话一键,互不串账)。 */
+export function registerArmedGateFor(sessionKey, key) {
+    if (typeof key === 'string' && key.length > 0)
+        setFor(sessionKey).add(key);
+}
+/** 该身份键的卡在本进程本会话呈现过吗?(false = 首见;文案分形的唯一判据) */
+export function wasGateArmed(key) {
+    return wasGateArmedFor(DEFAULT_SESSION_KEY, key);
+}
+/** W1 带 key 变体。 */
+export function wasGateArmedFor(sessionKey, key) {
+    if (typeof key !== 'string' || key.length === 0)
+        return false;
+    return armedGatesByKey.get(sessionKey)?.has(key) === true;
+}
+/** 消费一个身份键(A-024.4:plan_review 决断递交后清键 —— 同 taskId 的下一个 plan gate 读回首见)。 */
+export function clearArmedGate(key) {
+    clearArmedGateFor(DEFAULT_SESSION_KEY, key);
+}
+/** W1 带 key 变体。 */
+export function clearArmedGateFor(sessionKey, key) {
+    if (typeof key === 'string' && key.length > 0)
+        armedGatesByKey.get(sessionKey)?.delete(key);
+}
+/** 宿主呈现面登记口:收到可渲染 question 帧即记(键归一见 gateIdentity;坏形静默忽略 ——
+ *  id 是 wire/合成位,入参按边界收 unknown,本函数就是窄化动作本身)。 */
+export function registerArmedGateFromQuestionId(questionId) {
+    registerArmedGateFromQuestionIdFor(DEFAULT_SESSION_KEY, questionId);
+}
+/** W1 带 key 变体。 */
+export function registerArmedGateFromQuestionIdFor(sessionKey, questionId) {
+    if (typeof questionId !== 'string' || questionId.length === 0)
+        return;
+    registerArmedGateFor(sessionKey, armedKeyFromQuestionId(questionId));
+}
+/** 测试用:清全部会话的台账。 */
+export function _resetArmedGateRegistryForTest() {
+    armedGatesByKey.clear();
+}

package/dist/hitl/frameRouter.d.ts

@@ -16,7 +16,7 @@
  */
 import type { AgentEvent } from '@sema-agent/sdk';
 import type { HitlClientLike } from './hitlBridge.js';
-import { type RespondToolApprovalFn } from './toolApprovalWire.js';
+import { type RespondToolApprovalFn, type ToolApprovalFrameLaneOpts } from './toolApprovalWire.js';
 import type { GateLedger } from './gateLedger.js';
 /**
  * CC `utils/messages.ts` 的 `REJECT_MESSAGE` **逐字**(B7 搬迁差分 2)。deny 后重放 tool_end 的
@@ -50,6 +50,10 @@ export interface AskGateWireDeps {
     /** POST /v1/tool-approvals/:id/respond(server 1.191 同步帧腿,[830]①)。缺省=不消费
      *  tool_approval 帧(帧被吞、引擎按自身 fail-closed TTL 自决)——mock/旧引擎路径零影响。 */
     respondToolApproval?: RespondToolApprovalFn;
+    /** #229 respond-note 供给链(0.29.0 发包扫描门修,2026-08-12):帧腿车道参数(能力位读数),
+     *  宿主从自己的 caps 缓存供给。缺席 = note 门 fail-closed 到「不发」侧(决断照常,现状字节
+     *  不变)—— 此前包内唯一生产调用点(routeFrame 的 tool_approval 臂)无此位,note 恒不发。 */
+    approvalLane?: ToolApprovalFrameLaneOpts;
 }
 /** 两族 gate:AskUserQuestion 走问答 overlay(原路);其余(fs 写三件 / Bash / 一等
  *  `kind==='tool_approval'`)走 CC 三选卡。 */

package/dist/hitl/frameRouter.js

@@ -302,7 +302,7 @@ async function routeToolApprovalFrame(ev, ctx) {
     const gatedCallId = !fromSubagent ? led.lastPendingFsCall() : undefined;
     // FIX①(2026-08-07):产物是 `{decision, ack?}` —— ack 上的 `rememberApplied`/`updatedInputForwarded`
     // 由 toolApprovalWire 就地收敛成宿主通知(本路由只认决断词,不重复解释 ack)。
-    const { decision } = await surfaceToolApprovalFrameAndRespond(ev, deps.respondToolApproval, argsOfGatedStart(led, gatedCallId), ctx.signal);
+    const { decision } = await surfaceToolApprovalFrameAndRespond(ev, deps.respondToolApproval, argsOfGatedStart(led, gatedCallId), ctx.signal, deps.approvalLane);
     if (decision === 'deny' && !fromSubagent) {
         // 该 call 的报错收口帧 stamp REJECT 文案(vendored `User rejected <op> to <path>` 卡)。
         if (gatedCallId !== undefined)

package/dist/hitl/gateIdentity.d.ts

@@ -0,0 +1,42 @@
+/**
+ * gateIdentity.ts — HITL 决断卡**身份键**的唯一铸口(A-028.3,#244 族A 包半场,2026-08-12)。
+ *
+ * 为什么要有它:三条身份键字面此前散在三处各铸各的 ——
+ *   · `parkResolver.ts` 铸 `hitl-ask:${gatedCallId ?? taskId}`(overlay 问答帧 id);
+ *   · `toolApprovalWire.ts` 铸 `gatedCallId ?? taskId`(durable 腿卡口 callKey)与
+ *     `hitl-frame:${approvalId}`(live 帧腿 callKey);
+ *   · `planReviewWire.ts` 铸 `plan-review:${taskId}`(module 私有,壳侧只能人肉抄字面对齐)。
+ * 消费方(呈现台账 `armedGateRegistry` 的键归一、壳侧重开腿)靠「与铸口逐字对齐」的注释纪律
+ * 活着 —— 漂一个字节,首见/复见判决就静默失真。本文件把全部字面收成单源:铸口 import 这里,
+ * 台账的键推导也 import 这里,两边在结构上不可能再漂。
+ *
+ * 🔴 零 import 纯函数叶(portability:不进任何闭包新边;index 闭包 +1 文件已登记)。
+ */
+/** overlay 问答帧的 ask-gate 命名空间前缀(`parkResolver.surfaceGateAndDecide` 合成帧 id 用)。 */
+export declare const HITL_ASK_QUESTION_ID_PREFIX = "hitl-ask:";
+/** plan_review 审批卡的合成 questionId 前缀(`planReviewWire` 首次 arm 与重开腿共用)。 */
+export declare const PLAN_REVIEW_QUESTION_ID_PREFIX = "plan-review:";
+/** live `tool_approval` 帧腿的卡口 callKey 前缀(帧上无 gatedCallId 可对齐,以 approvalId 铸)。 */
+export declare const HITL_FRAME_CALL_KEY_PREFIX = "hitl-frame:";
+/** 重开腿铸新身份的尾分隔符(`…#reopen-<suffix>`);键归一时从这里剥尾,首呈与重开落同一键。 */
+export declare const REOPEN_ID_TAIL = "#reopen-";
+/**
+ * durable 审批腿的卡身份键(`toolApprovalWire` 卡口 / own-run 台账同域):
+ * gate 绑定的 callId 优先,行没带 callId 时退 taskId。
+ */
+export declare function approvalCallKey(gatedCallId: string | undefined, taskId: string): string;
+/** ask-gate overlay 帧 id(入参 = {@link approvalCallKey} 的产出)。 */
+export declare function askGateQuestionId(callKey: string): string;
+/** plan_review 审批卡的合成 questionId(首次 arm 的 canonical 身份;重开腿在其后接 {@link REOPEN_ID_TAIL})。
+ *  A-028.3:此前是 `planReviewWire.ts` 的 module 私有函数,壳侧重开腿只能手抄字面 —— 现转公面单源。 */
+export declare function planReviewQuestionId(taskId: string): string;
+/** live `tool_approval` 帧腿的卡口 callKey(`toolApprovalWire.surfaceToolApprovalFrameAndRespond`)。 */
+export declare function liveFrameCallKey(approvalId: string): string;
+/**
+ * question 帧 id → 呈现台账键的归一(armedGateRegistry 的键推导):
+ *   · `hitl-ask:X` → `X`(ask 帧的台账键 = 卡口 callKey,与 durable 腿卡的键同域);
+ *   · `…#reopen-<suffix>` 尾剥掉(重开铸的新身份归一到原键,首呈与重开同键);
+ *   · `plan-review:<taskId>` **保留前缀**(plan 键与「taskId 直接作 ask 键」永不撞域);
+ *   · 不认识的形原样入册(未来新 id 形至多多占一个键,不误伤既有词汇)。
+ */
+export declare function armedKeyFromQuestionId(questionId: string): string;

package/dist/hitl/gateIdentity.js

@@ -0,0 +1,56 @@
+/**
+ * gateIdentity.ts — HITL 决断卡**身份键**的唯一铸口(A-028.3,#244 族A 包半场,2026-08-12)。
+ *
+ * 为什么要有它:三条身份键字面此前散在三处各铸各的 ——
+ *   · `parkResolver.ts` 铸 `hitl-ask:${gatedCallId ?? taskId}`(overlay 问答帧 id);
+ *   · `toolApprovalWire.ts` 铸 `gatedCallId ?? taskId`(durable 腿卡口 callKey)与
+ *     `hitl-frame:${approvalId}`(live 帧腿 callKey);
+ *   · `planReviewWire.ts` 铸 `plan-review:${taskId}`(module 私有,壳侧只能人肉抄字面对齐)。
+ * 消费方(呈现台账 `armedGateRegistry` 的键归一、壳侧重开腿)靠「与铸口逐字对齐」的注释纪律
+ * 活着 —— 漂一个字节,首见/复见判决就静默失真。本文件把全部字面收成单源:铸口 import 这里,
+ * 台账的键推导也 import 这里,两边在结构上不可能再漂。
+ *
+ * 🔴 零 import 纯函数叶(portability:不进任何闭包新边;index 闭包 +1 文件已登记)。
+ */
+/** overlay 问答帧的 ask-gate 命名空间前缀(`parkResolver.surfaceGateAndDecide` 合成帧 id 用)。 */
+export const HITL_ASK_QUESTION_ID_PREFIX = 'hitl-ask:';
+/** plan_review 审批卡的合成 questionId 前缀(`planReviewWire` 首次 arm 与重开腿共用)。 */
+export const PLAN_REVIEW_QUESTION_ID_PREFIX = 'plan-review:';
+/** live `tool_approval` 帧腿的卡口 callKey 前缀(帧上无 gatedCallId 可对齐,以 approvalId 铸)。 */
+export const HITL_FRAME_CALL_KEY_PREFIX = 'hitl-frame:';
+/** 重开腿铸新身份的尾分隔符(`…#reopen-<suffix>`);键归一时从这里剥尾,首呈与重开落同一键。 */
+export const REOPEN_ID_TAIL = '#reopen-';
+/**
+ * durable 审批腿的卡身份键(`toolApprovalWire` 卡口 / own-run 台账同域):
+ * gate 绑定的 callId 优先,行没带 callId 时退 taskId。
+ */
+export function approvalCallKey(gatedCallId, taskId) {
+    return gatedCallId ?? taskId;
+}
+/** ask-gate overlay 帧 id(入参 = {@link approvalCallKey} 的产出)。 */
+export function askGateQuestionId(callKey) {
+    return `${HITL_ASK_QUESTION_ID_PREFIX}${callKey}`;
+}
+/** plan_review 审批卡的合成 questionId(首次 arm 的 canonical 身份;重开腿在其后接 {@link REOPEN_ID_TAIL})。
+ *  A-028.3:此前是 `planReviewWire.ts` 的 module 私有函数,壳侧重开腿只能手抄字面 —— 现转公面单源。 */
+export function planReviewQuestionId(taskId) {
+    return `${PLAN_REVIEW_QUESTION_ID_PREFIX}${taskId}`;
+}
+/** live `tool_approval` 帧腿的卡口 callKey(`toolApprovalWire.surfaceToolApprovalFrameAndRespond`)。 */
+export function liveFrameCallKey(approvalId) {
+    return `${HITL_FRAME_CALL_KEY_PREFIX}${approvalId}`;
+}
+/**
+ * question 帧 id → 呈现台账键的归一(armedGateRegistry 的键推导):
+ *   · `hitl-ask:X` → `X`(ask 帧的台账键 = 卡口 callKey,与 durable 腿卡的键同域);
+ *   · `…#reopen-<suffix>` 尾剥掉(重开铸的新身份归一到原键,首呈与重开同键);
+ *   · `plan-review:<taskId>` **保留前缀**(plan 键与「taskId 直接作 ask 键」永不撞域);
+ *   · 不认识的形原样入册(未来新 id 形至多多占一个键,不误伤既有词汇)。
+ */
+export function armedKeyFromQuestionId(questionId) {
+    const base = questionId.startsWith(HITL_ASK_QUESTION_ID_PREFIX)
+        ? questionId.slice(HITL_ASK_QUESTION_ID_PREFIX.length)
+        : questionId;
+    const cut = base.indexOf(REOPEN_ID_TAIL);
+    return cut >= 0 ? base.slice(0, cut) : base;
+}

package/dist/hitl/hitlBridge.d.ts

@@ -66,6 +66,18 @@
  * backend supplies the SIGNAL; the shell owns the chrome.
  */
 import type { AgentEvent, ApprovalDecision, PendingCheckpoint, CheckpointGate, PlanReviewRequest, AssistantTaskStatus } from '@sema-agent/sdk';
+/** durable `/decide` 腿的既有缺省拒因(不带归因时逐字不变 —— 0.27.0 及之前的 wire 字节)。 */
+export declare const DEFAULT_DENY_REASON = "The user rejected this tool use";
+/** server 两条腿共用的 reason 字符上限(超限 413,决断被打回)。 */
+export declare const MAX_DENY_REASON_CHARS = 4096;
+/**
+ * 归因原文 → 可上 wire 的形。缺席/非串/纯空白 ⇒ `undefined`(调用方自定回落:deny 腿落
+ * {@link DEFAULT_DENY_REASON},plan-review 腿键不落);超上限 ⇒ 截到上限并 debug 留痕。
+ * 🔴 截断**边界安全**:切点落在代理对中间会产出孤高代理 —— server 长度检查放行,但 UTF-8
+ * 落库/入签时末尾退化成 U+FFFD,两侧字节不一致还会毒化签名对账。末码元是高代理就再退一位。
+ * 🔴 只做归因,不参与裁决:任何返回值都不改变这次决断本身。
+ */
+export declare function denyReasonForWire(reason: string | undefined, tag: string): string | undefined;
 /** CC `PermissionDecision` 的结构切片 —— 本桥运行时真正读的三个键。 */
 export interface HitlPermissionDecisionLike {
     behavior: 'allow' | 'ask' | 'deny';

package/dist/hitl/hitlBridge.js

@@ -1,4 +1,38 @@
 import { eventSeq } from '../adapter/types.js';
+import { hostLog } from '../host.js';
+// ── deny/plan-review 归因的 wire 窄化(0.28.0 发版扫描 F1/F2/F3 收编;单源,三条腿共用)──────
+//
+// server 对 `/decide` 与 plan-review 两条腿的 `reason` 同限 `MAX_APPROVAL_REASON_CHARS`(4096 字符,
+// 超限 **413 `reason_too_large`**;server 侧 reason 入签后无法替发送方截 —— 超长原样发出去,丢掉的
+// 不是归因而是**整次决断**:413 ⇒ 决断没送达 ⇒ run 留 suspended)。所以三条 reason 出口(卡 deny /
+// canUseTool deny / plan-review)全部经本窄化器,绝不裸发。
+/** durable `/decide` 腿的既有缺省拒因(不带归因时逐字不变 —— 0.27.0 及之前的 wire 字节)。 */
+export const DEFAULT_DENY_REASON = 'The user rejected this tool use';
+/** server 两条腿共用的 reason 字符上限(超限 413,决断被打回)。 */
+export const MAX_DENY_REASON_CHARS = 4096;
+/**
+ * 归因原文 → 可上 wire 的形。缺席/非串/纯空白 ⇒ `undefined`(调用方自定回落:deny 腿落
+ * {@link DEFAULT_DENY_REASON},plan-review 腿键不落);超上限 ⇒ 截到上限并 debug 留痕。
+ * 🔴 截断**边界安全**:切点落在代理对中间会产出孤高代理 —— server 长度检查放行,但 UTF-8
+ * 落库/入签时末尾退化成 U+FFFD,两侧字节不一致还会毒化签名对账。末码元是高代理就再退一位。
+ * 🔴 只做归因,不参与裁决:任何返回值都不改变这次决断本身。
+ */
+export function denyReasonForWire(reason, tag) {
+    if (typeof reason !== 'string')
+        return undefined;
+    const trimmed = reason.trim();
+    if (trimmed === '')
+        return undefined;
+    if (trimmed.length <= MAX_DENY_REASON_CHARS)
+        return trimmed;
+    let cut = trimmed.slice(0, MAX_DENY_REASON_CHARS);
+    const last = cut.charCodeAt(cut.length - 1);
+    if (last >= 0xd800 && last <= 0xdbff)
+        cut = cut.slice(0, -1); // 孤高代理:退一位,绝不发半个字符
+    hostLog('debug', `hitlBridge: reason for ${tag} truncated ${trimmed.length}→${cut.length} chars ` +
+        `(server caps approval reason at ${MAX_DENY_REASON_CHARS}; over-cap is a 413 reason_too_large that would drop the DECISION, not just the reason)`);
+    return cut;
+}
 // ── Errors the bridge surfaces (fail-closed; never auto-retried) ───────────────
 /** A safety stop: a contract law was about to be violated (e.g. a binding mismatch, a wrong-gate route).
  *  The caller MUST re-present to the human or surface the error — NEVER silently retry or auto-decide
@@ -254,8 +288,12 @@ export class HitlBridge {
         // (PlanReviewRequest 是 SDK 外部 wire 型,不能改;诚实缺席 = 键不落,不传 `editedPlan: undefined`)。
         if (outcome.decision === 'edit' && outcome.editedPlan !== undefined)
             req.editedPlan = outcome.editedPlan;
-        if (outcome.reason !== undefined)
-            req.reason = outcome.reason;
+        // 0.28.0 发版扫描 F2:reason 经窄化器(超 4096 截断防 413 丢整次计划决断);空白 ⇒ 键不落。
+        if (outcome.reason !== undefined) {
+            const r = denyReasonForWire(outcome.reason, `plan-review ${this.taskId}`);
+            if (r !== undefined)
+                req.reason = r;
+        }
         return this.client.assistant.planReview(this.taskId, req, opts);
     }
     // ── §5. resource_limit: continue ────────────────────────────────────────────
@@ -305,7 +343,9 @@ export function makeHitlCanUseTool(bridge, prompt) {
             (await prompt({ toolName: tool.name, input, toolUseID, gate }));
         if (decision.behavior === 'deny') {
             // Deny → cancel-by-deny (contract/04 §2.4). The deny message rides `reason`.
-            await bridge.decideTool({ decision: 'deny', reason: decision.message }, toolUseID);
+            // 0.28.0 发版扫描 F1(P2):message 逐字嵌原始命令(壳侧 bashPermissions 无上限)——必须与
+            // 卡腿同门经窄化器截到 4096,否则 server 413 丢的是整次 deny(run 留 suspended)。
+            await bridge.decideTool({ decision: 'deny', reason: denyReasonForWire(decision.message, `canUseTool ${toolUseID}`) ?? DEFAULT_DENY_REASON }, toolUseID);
             return decision;
         }
         if (decision.behavior === 'allow') {

package/dist/hitl/parkOwnership.d.ts

@@ -0,0 +1,65 @@
+/**
+ * parkOwnership.ts — ask park 重开腿的**纯判据**三件(A-028.2,#244 族A 包半场,2026-08-12;
+ * 源形 = cli `src/sema/askParkReopen.ts` 的发现面判据半场;`approvals.list` 编排与 stderr
+ * 留宿主 —— 本文件零网络、零渲染,只回答判决)。
+ *
+ * ── A-024.1:「队列恰一行」不是归属证明 ────────────────────────────────────────────────────
+ * `/v1/approvals` 是 **scope 级**单队列:恰一行只说明「此刻没有别的行在排队」,而孤儿 park、
+ * 行可见性延迟、另一会话独占队列三种形都能让**别人的**行落单。把这一行直接展示并代为决断,
+ * 是 REF-CC-029(`?? pending[0]`)那个病的换形复发 —— 后果不是渲染错,是**把别人的审批递到
+ * 这个用户手上并替他按了钮**。
+ *
+ * 宿主能拿出的归属硬证据只有两条(缺一不可地互补,不是二选一):
+ *   ① 行的 `taskId` ∈ own-run 台账(`isOwnEngineRun`,只记本进程亲手驱动的 run + fleet 行帧
+ *      闭包进来的自家子代)⇒ 本宿主起的 run/子代。child 委派行走这条 —— 子代 park 行的
+ *      `sessionId` 是子代自己的 session,天生 ≠ 本会话,只按 ② 判会把发现面拆掉。
+ *   ② 行自带 `sessionId` === 本宿主当前引擎会话 ⇒ 本会话自己的 park。
+ *
+ * 🔴 判据是 **fail-CLOSED 的正向证明**:两条腿任一成立才采信,**都不成立就不采信** —— 包括
+ * 「本会话 id 还没有」「行没带 sessionId」这两种**判不出**的形。把「证明不了」当「是我的」,
+ * 在一个会替用户按钮的面上正好反了。判不出的代价只是一句诚实的 reopen-failed(用户重发消息
+ * 即重走本链),而放行的代价是替别人决断,不对等。
+ */
+import type { PendingCheckpoint } from '@sema-agent/sdk';
+import type { AskQuestion } from '../liveQuestionStore.js';
+/** 归属判据的两条腿的注入口(缺席走包内既有真源:SessionPort + own-run 台账)。 */
+export interface ParkOwnershipDeps {
+    /**
+     * 多会话宿主的会话键(缺省 = DEFAULT_SESSION_KEY,单会话宿主零参装配)。
+     * 🔴 传了**非默认键**而没有注入 `isOwnRun` 时,own-run 缺省腿**整条跳过**(复审 [high] 收紧):
+     * 包内 own-run 台账是**进程级**的(记「本进程驱动过的 run」),在一个跑着 A/B 两个会话的宿主
+     * 进程里,它答不了「这行是 A 的还是 B 的」—— 拿进程级证据放行会把 A 的审批递到 B 手上。
+     * 多会话宿主要么注入自己会话粒度的 `isOwnRun`,要么只靠会话腿(fail-closed:少一条腿的代价
+     * 只是多一次诚实 reopen-failed)。
+     */
+    sessionKey?: string;
+    /** 会话腿真源(缺省 = `hostSessionFor(sessionKey).currentSessionId()`;空串按缺席归一,
+     *  判不出 ≠ 命中)。 */
+    currentSessionId?: () => string | undefined;
+    /** own-run 台账腿(缺省 = 包 `isOwnEngineRun`,**仅默认会话键**下启用,理由见 sessionKey 注)。
+     *  🔴 键域 = `rowIdTail(行 taskId)`(fleet 台账登记时就过 rowIdTail,本判据同域取键后才调本口)。
+     *  🔴 成文局限(复审二轮裁定,不改行为):默认键下的缺省腿是**进程级**证据,不区分同一宿主
+     *  进程内的会话代际 —— `/clear` 前登记的 run 在新会话语境下仍判 owned。这是单会话宿主的
+     *  出货语义(owner = 本进程的这一位用户;child 委派行的 sessionId 天生 ≠ 本会话,发现面恰恰
+     *  依赖跨会话 id 的进程级证据),最坏形 = 用户看到**自己**旧会话的审批卡(卡面标注行归属)。
+     *  要会话代际粒度就注入自己的 `isOwnRun` —— 台账本体改代际级属 own-run 域独立议题。 */
+    isOwnRun?: (taskIdTail: string) => boolean;
+}
+/**
+ * 这行 pending 能不能**正向证明**属于本宿主会话(fail-closed;两腿语义见文件头)。
+ * 腿序:own-run 先问(child 委派行不依赖会话 id),会话腿后问。
+ */
+export declare function pendingRowIsOwnedByThisSession(row: PendingCheckpoint, deps?: ParkOwnershipDeps): boolean;
+/**
+ * questions payload 从 pending.input 读 —— **结构判定**收窄到 AskQuestion 必需键(question
+ * 非 string / questions 非数组 / 空数组 ⇒ null,不 cast 硬塞;缺 header 的行照 CC 形容忍,
+ * overlay 自兜)。铸空卡 = 假 affordance,拿不到题就诚实返 null。
+ */
+export declare function askQuestionsFromPending(pending: PendingCheckpoint): AskQuestion[] | null;
+/**
+ * HitlSafetyError 判型的 duck-check(按 `name`,不按 instanceof —— 宿主 bundle 里存在第二份包
+ * 实例时 instanceof 会分叉,sseIdleTriage 同款纪律)。安全信号(binding_mismatch 族)契约禁
+ * 盲重试,重开腿据此把「可重试的瞬时故障」与「必须交还人重决的安全停」分开。
+ * 入参是任意抛出值,本函数就是窄化动作本身(unknown 出境登记见 typeshape 门 RATCHET 注)。
+ */
+export declare function isHitlSafetyErrorLike(e: unknown): boolean;

package/dist/hitl/parkOwnership.js

@@ -0,0 +1,49 @@
+import { isOwnEngineRun } from '../subagentContentStore.js';
+import { rowIdTail } from '../workflow.js';
+import { hostSessionFor } from '../host.js';
+import { DEFAULT_SESSION_KEY } from '../sessionSlot.js';
+/**
+ * 这行 pending 能不能**正向证明**属于本宿主会话(fail-closed;两腿语义见文件头)。
+ * 腿序:own-run 先问(child 委派行不依赖会话 id),会话腿后问。
+ */
+export function pendingRowIsOwnedByThisSession(row, deps) {
+    const sessionKey = deps?.sessionKey ?? DEFAULT_SESSION_KEY;
+    // ① 本宿主亲手驱动的 run / 由它闭包进来的自家子代 —— 不依赖会话 id。
+    //    进程级缺省腿只在默认会话键下启用(多会话宿主必须注入会话粒度的口,见 deps.sessionKey 注)。
+    const rowTaskId = typeof row.taskId === 'string' ? row.taskId : '';
+    const ownRun = deps?.isOwnRun ?? (sessionKey === DEFAULT_SESSION_KEY ? isOwnEngineRun : undefined);
+    if (ownRun !== undefined && rowTaskId.length > 0 && ownRun(rowIdTail(rowTaskId)))
+        return true;
+    // ② 行自带 sessionId === 本会话当前引擎会话。任一侧缺席/空串 = 判不出,不是命中。
+    const currentSessionId = deps?.currentSessionId ?? (() => hostSessionFor(sessionKey)?.currentSessionId());
+    const sessionId = currentSessionId();
+    const rowSessionId = typeof row.sessionId === 'string' ? row.sessionId : '';
+    return (typeof sessionId === 'string' &&
+        sessionId.length > 0 &&
+        rowSessionId.length > 0 &&
+        rowSessionId === sessionId);
+}
+/**
+ * questions payload 从 pending.input 读 —— **结构判定**收窄到 AskQuestion 必需键(question
+ * 非 string / questions 非数组 / 空数组 ⇒ null,不 cast 硬塞;缺 header 的行照 CC 形容忍,
+ * overlay 自兜)。铸空卡 = 假 affordance,拿不到题就诚实返 null。
+ */
+export function askQuestionsFromPending(pending) {
+    const input = pending.input;
+    if (typeof input !== 'object' || input === null)
+        return null;
+    const qs = input.questions;
+    if (!Array.isArray(qs) || qs.length === 0)
+        return null;
+    const ok = qs.every(q => typeof q === 'object' && q !== null && typeof q.question === 'string');
+    return ok ? qs : null;
+}
+/**
+ * HitlSafetyError 判型的 duck-check(按 `name`,不按 instanceof —— 宿主 bundle 里存在第二份包
+ * 实例时 instanceof 会分叉,sseIdleTriage 同款纪律)。安全信号(binding_mismatch 族)契约禁
+ * 盲重试,重开腿据此把「可重试的瞬时故障」与「必须交还人重决的安全停」分开。
+ * 入参是任意抛出值,本函数就是窄化动作本身(unknown 出境登记见 typeshape 门 RATCHET 注)。
+ */
+export function isHitlSafetyErrorLike(e) {
+    return typeof e === 'object' && e !== null && e.name === 'HitlSafetyError';
+}

package/dist/hitl/parkResolver.js

@@ -4,6 +4,7 @@ import { hostLog } from '../host.js';
 import { surfaceFsApprovalAndDecide } from './toolApprovalWire.js';
 import { observeCancelByDeny } from './hitlHostSurface.js';
 import { isAskTool } from './frameRouter.js';
+import { approvalCallKey, askGateQuestionId } from './gateIdentity.js';
 /** 一 turn 内最多循环这么多次 park(防御:引擎/模型病态连环提问时不无限 attach)。 */
 const MAX_GATE_HOPS = 24;
 /**
@@ -121,7 +122,8 @@ async function surfaceGateAndDecide(deps, taskId, askArgsByCall, signal) {
         };
     }
     // overlay 往返:合成 frame(id 独占命名空间 hitl-ask:)→ local responder 一次性收答。
-    const questionId = `hitl-ask:${gatedCallId ?? taskId}`;
+    // A-028.3:id 经 gateIdentity 唯一铸口(呈现台账/壳侧重开腿的键推导同源,字面不再各铸各的)。
+    const questionId = askGateQuestionId(approvalCallKey(gatedCallId, taskId));
     const answer = await new Promise(resolve => {
         const unregister = registerLocalQuestionResponder(questionId, async (_id, a) => {
             cleanup();

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;