@sema-agent/client-core 0.28.0 → 0.30.0

package/dist/adapter/runStream.d.ts

@@ -33,22 +33,39 @@
 import type { AgentEvent } from '@sema-agent/sdk';
 import { type SDKMessage, type EmitContext, type ModelUsage } from './types.js';
 import type { EngineTurnUsage } from './downstream/turnUsageToModelUsage.js';
+/**
+ * 409 body 的 pendingGate 材料(A-028.1,2026-08-12 具名化并补 `governanceForced` 位 ——
+ * 此前包侧只有 {kind, decidePath} 两位,壳侧抄件已多出该位 = 同一 wire 位两份解析器形不同,
+ * 以超集形归一进包)。
+ */
+export interface ActiveRunPendingGate {
+    /** 在等哪一种门;引擎对未知 kind 自己返 null。 */
+    readonly kind: string | null;
+    /** 兑现那个决定的**真路由**(wire 给的,消费方绝不按 kind 硬编码一张表)。 */
+    readonly decidePath: string | null;
+    /**
+     * 这道门的**出身**是运维治理层(AUTONOMY / commandPolicy / 守卫集)强制的
+     * (server ≥7.12 / SDK 6.15.0 `PendingGateMaterial`,ADDITIVE)。
+     * 🔴 **只在为真时在场,server 恒不写 false**;缺席 ≠「这不是治理门」,只是「没有治理来源的
+     * 证据」。消费方只做**在场才说**的加法:纯归因一句,不参与任何分诊/动作。
+     */
+    readonly governanceForced?: true;
+}
 /** #114/[C65] 单源化:三端共用的 409 active-run 拒收终帧判别(富信号形,包级唯一权威)。
- *  与壳侧抄件(cli `src/sema/activeRunSelfHeal.ts`)同义——0.13.0 到货后壳换包导入删本地抄件。
  *  🔧 2026-08-02 事实纠正([C77]③):原文写的是「与壳/desktop **各自**照抄件同义……各端换包
  *  导入删本地抄件」,而 desktop 全树扫描(`activeRunBusySignal` / `session_active_run` /
  *  `activeTaskId` 的 409 判别族)**零命中** —— 那边根本没有抄件,「各端」是句不实的话。
- *  删掉不实的那半:今天的抄件只有壳一份。 */
+ *  删掉不实的那半:今天的抄件只有壳一份。
+ *  🔧 A-028.1(2026-08-12):抄件漂移收口 —— 壳侧那份的 pendingGate 已多出 `governanceForced`
+ *  位,本形按超集归一(见 {@link ActiveRunPendingGate});分诊树/结局文案层同批落
+ *  `adapter/activeRunSelfHeal.ts`,壳侧换包导入在提货批。 */
 export interface ActiveRunBusySignal {
     /** 占锁 run 的 id;wire 没带 ⇒ null(诚实缺席,绝不铸造)。 */
     readonly activeTaskId: string | null;
     /** server 3.21+ 真发的占锁 run 状态;缺席 ⇒ null(由调用方走 runs.get 一级)。 */
     readonly activeTaskStatus: string | null;
     /** 409 body 的 pendingGate(wire 给的真路由,不自造);缺席 ⇒ null。 */
-    readonly pendingGate: {
-        readonly kind: string | null;
-        readonly decidePath: string | null;
-    } | null;
+    readonly pendingGate: ActiveRunPendingGate | null;
 }
 /**
  * 判别一个**原始 AgentEvent** 是不是 409 active-run 拒收终帧;非 busy ⇒ null。

package/dist/adapter/runStream.js

@@ -1,7 +1,7 @@
 import { eventSeq, } from './types.js';
 import { eventToSdkMessage, turnEndUsage } from './downstream/eventToSdkMessage.js';
 import { terminalToSdkResult } from './downstream/terminalToSdkResult.js';
-import { publishSubagentContentEvent } from '../subagentContentStore.js';
+import { coerceOutput, publishSubagentContentEvent } from '../subagentContentStore.js';
 /**
  * 409 session-busy 拒绝的 **canonical errorCode**([2377]C-1,server main `049ff2c`,随 5.0.0 发)。
  * 引擎把它 stamp 在 `done{status:'failed'}` / `failed` 终帧上,壳据此**结构判读**,不再读人话。
@@ -48,9 +48,13 @@ export function activeRunBusySignal(ev) {
     if (typeof rawGate === 'object' && rawGate !== null) {
         const k = rawGate.kind;
         const d = rawGate.decidePath;
+        // 出身位(A-028.1):**只认严格 true**。任何别的形(false / 'true' / 1 / 缺席)一律不置键 ——
+        // 键在场即渲徽标类文案,把一个含糊值读成「治理强制」= 对用户下一个证不出的断言。
+        const g = rawGate.governanceForced;
         pendingGate = {
             kind: typeof k === 'string' && k.length > 0 ? k : null,
             decidePath: typeof d === 'string' && d.length > 0 ? d : null,
+            ...(g === true ? { governanceForced: true } : {}),
         };
     }
     return {
@@ -222,14 +226,24 @@ async function* runStreamInner(events, ctx, handle = {}) {
             const sub = ev;
             publishSubagentContentEvent({
                 type: sub.type,
-                // taskId is on every subagent event (EventIdentity); parentToolCallId keys the fallback
+                // 🔴 EventIdentity 上**没有** `taskId`(sdk events.d.ts 的 `interface EventIdentity` 只有
+                // eventId / parentToolCallId,加 LIVE 白名单四臂的 sourceTaskId / bgAgentId;`taskId` 只长在
+                // `meta` 首帧)⇒ 生产上这里恒走右臂,归账键由 store 的 `parentToTask` 补(canonicalKey)。
+                // `??` 保留是**容将来**:哪天上游真在内容帧上发 taskId,这条直接认,不必改形。
+                // (0.30.0 发包扫描订正:此前这行注释写「taskId is on every subagent event」,与 store 侧
+                //  `canonicalKey` 的注释互相矛盾,且被 .d.ts 直接证伪。)
                 taskId: sub.taskId ?? sub.parentToolCallId,
                 parentToolCallId: sub.parentToolCallId,
                 delta: sub.delta,
                 toolCallId: sub.toolCallId,
                 toolName: sub.toolName,
                 args: sub.args,
-                output: typeof sub.output === 'string' ? sub.output : undefined,
+                // #158 移交①([3674](d) 姊妹病,2026-08-12):此前是 `typeof sub.output === 'string' ?
+                // sub.output : undefined` —— 而 wire 的 `tool_end.output` 是非均匀的(块数组形合法),
+                // 于是子代 lane 的块数组 output 经本臂进内容账本**恒空**(查看态卡有工具、结果栏永远空白)。
+                // 换用 store 自己的那个唯一字符串化口(tail 腿 engineSubagentTail 用的同一份):两条腿喂
+                // 同一个账本,字符串化口就不能有第二份。
+                output: coerceOutput(sub.output),
                 isError: sub.isError,
             });
             continue;
@@ -311,8 +325,8 @@ async function* runStreamInner(events, ctx, handle = {}) {
                 // 像 provider 故障,是误导。识别该终帧 → 一行专属文案(告知在等什么 + 出路);其它错误保持
                 // 原 API Error 行(未知错误 fallback 不变)。引擎侧解锁腿已到货([868]:cancel 对
                 // suspended/needs_review 就地终态化 ⇒ claim 释放),所以文案指的就是那个端点;
-                // 会自动执行「cancel + 重发」的自愈腿在宿主侧(cli: src/sema/activeRunSelfHeal.ts),
-                // 本层只负责:识别 + 说真话。
+                // 自愈分诊腿(重开卡把决定权还给用户;cancel+重发臂已退役)在 `adapter/activeRunSelfHeal.ts`
+                // (A-028.1 上收,宿主经 deps 注入重开口),本层只负责:识别 + 说真话。
                 const activeTaskId = failedResult?.activeTaskId ??
                     (ev.type === 'failed' ? ev.activeTaskId : undefined);
                 // REF-CC-054:判别**结构位两腿**(errorCode → activeTaskId;文案兜底腿 2026-08-03 已退役),

package/dist/engineWireSdk.d.ts

@@ -67,8 +67,16 @@ export type EngineProbeOpts = {
 };
 export type EngineWireClientConfig = {
     baseUrl: string;
-    /** 真 token 串;缺省经 wireAuthTokenFor 三态解析(loopback-unauthed / 'anon')。 */
-    token?: string;
+    /** 真 token 串;缺省经 wireAuthTokenFor 三态解析(loopback-unauthed / 'anon')。
+     *
+     *  `{ mode: 'same-origin-relay' }`([C175],0.29.0)= **浏览器同源宿主的显式声明形**:凭证由
+     *  同源反代(cookie/session)承载,出站零 Authorization 头;它是 SDK 浏览器守卫的**唯一**豁免形
+     *  (AgentClient 在浏览器宿主拒绝 token/loopback-unauthed/'anon' 三态构造),且该形下 `baseUrl`
+     *  允许相对/同源路径(`''`、`'/api'`)。🔴 这个形**只能显式传入**(作者声明「我部署在同源反代后」),
+     *  绝不由 `resolveWireAuth` 三态解析推导出来 —— 解析口的三态语义一字不动,relay 形直传 SDK。 */
+    token?: string | {
+        mode: 'same-origin-relay';
+    };
     /** 缺席/undefined=不发 x-agent-principal 头(owner-null;F-011 停发,replEntry live 车道同闸口
      *  语义;显式 `| undefined` 让 EngineWireTarget.principal 直传合法——exactOptionalPropertyTypes)。 */
     principal?: string | undefined;

package/dist/engineWireSdk.js

@@ -72,15 +72,19 @@ export function wireAuthTokenFor(baseUrl, token) {
  */
 export function makeEngineWireClient(cfg) {
     try {
-        return new AgentClient({
+        const base = {
             baseUrl: cfg.baseUrl,
-            authToken: resolveWireAuth(cfg.baseUrl, cfg.token),
             // F-011 停发:缺席/空串=不给键(SDK 6.11 缺席=不发 x-agent-principal 头,owner-null)。
             ...(cfg.principal !== undefined && cfg.principal !== '' ? { principal: cfg.principal } : {}),
             ...(cfg.timeoutMs !== undefined ? { timeoutMs: cfg.timeoutMs } : {}),
             maxRetries: cfg.maxRetries ?? 0,
             ...(cfg.fetchImpl ? { fetch: cfg.fetchImpl } : {}),
-        });
+        };
+        // relay 形直传(显式声明,不过三态解析);串/缺席走 resolveWireAuth 三态,语义与 0.28.x 字节
+        // 不变。分支构造而非三元合流:SDK AgentClientConfig 按 authToken 判别联合,联合值不可直赋。
+        return typeof cfg.token === 'object'
+            ? new AgentClient({ ...base, authToken: cfg.token })
+            : new AgentClient({ ...base, authToken: resolveWireAuth(cfg.baseUrl, cfg.token) });
     }
     catch {
         return null;

package/dist/hitl/approvalDecisionNoteAudit.d.ts

@@ -0,0 +1,58 @@
+/**
+ * hitl/approvalDecisionNoteAudit.ts — 审批**回决备注**(`decisionNote` / `noteRecorded`)的读面
+ * 判定 + 人话行(#265 上收件,2026-08-14;源形 = cli `src/sema/approvalDecisionNoteAudit.ts`,
+ * 供给半场 = server 7.15.0 的 `AskDecisionAck.decisionNote` / `ToolApprovalRespondAck.noteRecorded`)。
+ *
+ * ── 病 ────────────────────────────────────────────────────────────────────────────────────────
+ * 送出去的那条 deny 理由到底有没有落进审计档,客户端这边**一个字都不知道**:决断腿此前是
+ * `await decide…` 裸调,回体整个被丢掉。于是「我写了拒绝理由」与「那条理由真的进了审计行」之间
+ * 没有任何证据 —— deny 归因链在用户这一端是断的。
+ *
+ * ── 三态,不是两态 ────────────────────────────────────────────────────────────────────────────
+ * server 对这一位的契约(SDK `ToolApprovalRespondAck.noteRecorded` / `AskDecisionAck.decisionNote`
+ * 头注逐字)是**三态**,把它压成布尔就会造谎:
+ *   · `recorded`     —— `noteRecorded === true`,**或** durable ack 回显了 `decisionNote` 正文
+ *                       (契约:「行上有才发」⇒ 回显本身就是落行的证据);
+ *   · `not-recorded` —— `noteRecorded === false`。这是店的**真实结果**(并发歧义臂的输家如实 false),
+ *                       它说的是「理由没落档」,**不是**「审批失败」—— 决断照旧成立,渲染面必须
+ *                       在同一行里把这句说出来,否则用户会以为自己按的那个拒绝没生效;
+ *   · `unknown`      —— 两个位都不在场(旧 server / 这台部署没有 durable ask 账本 / 本次压根没送 note)。
+ *                       ⇒ **整行不渲**。缺席≠false —— 渲一行「未记录」等于替引擎回答一个它没回答
+ *                       的问题。
+ *
+ * 🔴 `noteRecorded === false` **压过**正文回显:显式的 per-call 真相优先。两者同时在场的形
+ *    (并发歧义臂:行上留的是赢家那条备注,我这条没落)只有这样才说得准 —— 正文仍带出来当归因
+ *    材料(用户看得见「行上现在是哪条」),但状态词按 false 走。
+ *
+ * ── 🔴 归层 ───────────────────────────────────────────────────────────────────────────────────
+ * 本文件 = **纯判定 + 文案**,`import` 列表为空(常驻门 ④ 段逐次对账)。呈现口不在这里 ——
+ * 装配层把行交给宿主的通知/转录面。三端(cli / desktop / web)撞的是同一件事,读的是同一份 ack。
+ *
+ * ── UNTRUSTED ─────────────────────────────────────────────────────────────────────────────────
+ * `decisionNote` 的正文是**卡口自由文本**原样回声(用户自己打的拒绝理由,也可能是别的客户端打的)。
+ * 读面就地有界截断 + 清洗控制字符 —— 只渲染,永不回喂模型,也绝不整段进日志。
+ */
+/** 审计面通知的独占 key —— 与审批流告警面分格(两件事不抢同一格)。 */
+export declare const DECISION_NOTE_NOTICE_KEY = "approval-decision-note";
+/** 备注面的三态判决。`note` = 引擎回显的正文(缺席 = 引擎没回显,**不是**「没有备注」)。 */
+export interface DecisionNoteAudit {
+    state: 'recorded' | 'not-recorded' | 'unknown';
+    note?: string;
+}
+/**
+ * 读一份回体(durable `AskDecisionAck` / legacy `ToolApprovalRespondAck` / 409
+ * `conflict.ask_decided` 体)里的备注面判决。
+ *
+ * 🔴 **在场即读、不在场即 unknown**:两个位在 SDK 类型上都是可选的,而「类型说 optional」与
+ *    「这台引擎真的发了」是两件事 —— 一律结构窄读,读不出就是缺席,绝不合成。
+ */
+export declare function readDecisionNoteAudit(ack: unknown): DecisionNoteAudit;
+/**
+ * 人话行。**`unknown` ⇒ `null`(整行不渲)** —— 这条纪律不可削。
+ *
+ * @param opts.settledElsewhere 这份材料来自 409 `conflict.ask_decided`(别的客户端/legacy 腿先结算)
+ *   ⇒ 行里要点明归因来源,否则用户会把首决那条备注当成自己刚写的那条。
+ */
+export declare function decisionNoteAuditLine(audit: DecisionNoteAudit, opts?: {
+    settledElsewhere?: boolean;
+}): string | null;

package/dist/hitl/approvalDecisionNoteAudit.js

@@ -0,0 +1,91 @@
+/**
+ * hitl/approvalDecisionNoteAudit.ts — 审批**回决备注**(`decisionNote` / `noteRecorded`)的读面
+ * 判定 + 人话行(#265 上收件,2026-08-14;源形 = cli `src/sema/approvalDecisionNoteAudit.ts`,
+ * 供给半场 = server 7.15.0 的 `AskDecisionAck.decisionNote` / `ToolApprovalRespondAck.noteRecorded`)。
+ *
+ * ── 病 ────────────────────────────────────────────────────────────────────────────────────────
+ * 送出去的那条 deny 理由到底有没有落进审计档,客户端这边**一个字都不知道**:决断腿此前是
+ * `await decide…` 裸调,回体整个被丢掉。于是「我写了拒绝理由」与「那条理由真的进了审计行」之间
+ * 没有任何证据 —— deny 归因链在用户这一端是断的。
+ *
+ * ── 三态,不是两态 ────────────────────────────────────────────────────────────────────────────
+ * server 对这一位的契约(SDK `ToolApprovalRespondAck.noteRecorded` / `AskDecisionAck.decisionNote`
+ * 头注逐字)是**三态**,把它压成布尔就会造谎:
+ *   · `recorded`     —— `noteRecorded === true`,**或** durable ack 回显了 `decisionNote` 正文
+ *                       (契约:「行上有才发」⇒ 回显本身就是落行的证据);
+ *   · `not-recorded` —— `noteRecorded === false`。这是店的**真实结果**(并发歧义臂的输家如实 false),
+ *                       它说的是「理由没落档」,**不是**「审批失败」—— 决断照旧成立,渲染面必须
+ *                       在同一行里把这句说出来,否则用户会以为自己按的那个拒绝没生效;
+ *   · `unknown`      —— 两个位都不在场(旧 server / 这台部署没有 durable ask 账本 / 本次压根没送 note)。
+ *                       ⇒ **整行不渲**。缺席≠false —— 渲一行「未记录」等于替引擎回答一个它没回答
+ *                       的问题。
+ *
+ * 🔴 `noteRecorded === false` **压过**正文回显:显式的 per-call 真相优先。两者同时在场的形
+ *    (并发歧义臂:行上留的是赢家那条备注,我这条没落)只有这样才说得准 —— 正文仍带出来当归因
+ *    材料(用户看得见「行上现在是哪条」),但状态词按 false 走。
+ *
+ * ── 🔴 归层 ───────────────────────────────────────────────────────────────────────────────────
+ * 本文件 = **纯判定 + 文案**,`import` 列表为空(常驻门 ④ 段逐次对账)。呈现口不在这里 ——
+ * 装配层把行交给宿主的通知/转录面。三端(cli / desktop / web)撞的是同一件事,读的是同一份 ack。
+ *
+ * ── UNTRUSTED ─────────────────────────────────────────────────────────────────────────────────
+ * `decisionNote` 的正文是**卡口自由文本**原样回声(用户自己打的拒绝理由,也可能是别的客户端打的)。
+ * 读面就地有界截断 + 清洗控制字符 —— 只渲染,永不回喂模型,也绝不整段进日志。
+ */
+/** 备注面在渲染时的正文上界(一行 footer 通知,不是转录面正文)。 */
+const NOTE_DISPLAY_MAX = 200;
+/** 审计面通知的独占 key —— 与审批流告警面分格(两件事不抢同一格)。 */
+export const DECISION_NOTE_NOTICE_KEY = 'approval-decision-note';
+/**
+ * 控制字符/换行清洗 + 有界截断(UNTRUSTED 正文只走这一个口)。
+ * 🔴 换行必须折平:footer 通知是**单行**面,一条带换行的备注会把整段排版撕开。
+ */
+function cleanNote(raw) {
+    const flat = raw
+        .replace(/[\u0000-\u001f\u007f-\u009f]+/g, ' ')
+        .replace(/ {2,}/g, ' ')
+        .trim();
+    return flat.length <= NOTE_DISPLAY_MAX ? flat : `${flat.slice(0, NOTE_DISPLAY_MAX - 1)}…`;
+}
+/**
+ * 读一份回体(durable `AskDecisionAck` / legacy `ToolApprovalRespondAck` / 409
+ * `conflict.ask_decided` 体)里的备注面判决。
+ *
+ * 🔴 **在场即读、不在场即 unknown**:两个位在 SDK 类型上都是可选的,而「类型说 optional」与
+ *    「这台引擎真的发了」是两件事 —— 一律结构窄读,读不出就是缺席,绝不合成。
+ */
+export function readDecisionNoteAudit(ack) {
+    if (ack === null || typeof ack !== 'object')
+        return { state: 'unknown' };
+    const o = ack;
+    const note = typeof o.decisionNote === 'string' && o.decisionNote.trim() !== '' ? cleanNote(o.decisionNote) : undefined;
+    // 显式 per-call 真相优先(见头注)。
+    if (o.noteRecorded === false)
+        return { state: 'not-recorded', ...(note !== undefined ? { note } : {}) };
+    if (o.noteRecorded === true)
+        return { state: 'recorded', ...(note !== undefined ? { note } : {}) };
+    // `noteRecorded` 是非布尔垃圾值(旧 server / 代理改写)⇒ 当它不在场,只看正文回显。
+    if (note !== undefined)
+        return { state: 'recorded', note };
+    return { state: 'unknown' };
+}
+/**
+ * 人话行。**`unknown` ⇒ `null`(整行不渲)** —— 这条纪律不可削。
+ *
+ * @param opts.settledElsewhere 这份材料来自 409 `conflict.ask_decided`(别的客户端/legacy 腿先结算)
+ *   ⇒ 行里要点明归因来源,否则用户会把首决那条备注当成自己刚写的那条。
+ */
+export function decisionNoteAuditLine(audit, opts) {
+    if (audit.state === 'unknown')
+        return null;
+    const quoted = audit.note !== undefined ? `: "${audit.note}"` : '';
+    if (opts?.settledElsewhere === true) {
+        // 首决备注只在 recorded 侧有意义(false = 我这条没落,但行上仍是别人那条)。
+        return audit.state === 'recorded'
+            ? `this approval was already decided elsewhere — the reason recorded on the audit trail${quoted}`
+            : `this approval was already decided elsewhere; your reason was not saved to the audit trail — that decision stands${quoted}`;
+    }
+    return audit.state === 'recorded'
+        ? `decision reason recorded on the audit trail${quoted}`
+        : `your decision stands — the engine did not save its reason to the audit trail${quoted}`;
+}

package/dist/hitl/armedGateRegistry.d.ts

@@ -0,0 +1,19 @@
+/** 登记一个已呈现的决断卡身份键(空/非法输入静默忽略 —— 登记面绝不炸渲染链)。 */
+export declare function registerArmedGate(key: string | null | undefined): void;
+/** W1 带 key 变体(多会话宿主每会话一键,互不串账)。 */
+export declare function registerArmedGateFor(sessionKey: string, key: string | null | undefined): void;
+/** 该身份键的卡在本进程本会话呈现过吗?(false = 首见;文案分形的唯一判据) */
+export declare function wasGateArmed(key: string | null | undefined): boolean;
+/** W1 带 key 变体。 */
+export declare function wasGateArmedFor(sessionKey: string, key: string | null | undefined): boolean;
+/** 消费一个身份键(A-024.4:plan_review 决断递交后清键 —— 同 taskId 的下一个 plan gate 读回首见)。 */
+export declare function clearArmedGate(key: string | null | undefined): void;
+/** W1 带 key 变体。 */
+export declare function clearArmedGateFor(sessionKey: string, key: string | null | undefined): void;
+/** 宿主呈现面登记口:收到可渲染 question 帧即记(键归一见 gateIdentity;坏形静默忽略 ——
+ *  id 是 wire/合成位,入参按边界收 unknown,本函数就是窄化动作本身)。 */
+export declare function registerArmedGateFromQuestionId(questionId: unknown): void;
+/** W1 带 key 变体。 */
+export declare function registerArmedGateFromQuestionIdFor(sessionKey: string, questionId: unknown): void;
+/** 测试用:清全部会话的台账。 */
+export declare function _resetArmedGateRegistryForTest(): void;

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/askParkRowRouting.d.ts

@@ -0,0 +1,150 @@
+/**
+ * hitl/askParkRowRouting.ts — ask park(`suspended`)重开链的**纯判定层**(#265 上收件,
+ * 2026-08-14;源形 = cli `src/sema/askParkReopen.ts` 的判据半场,该文件的呈现/决断编排留在端上)。
+ *
+ * 三端(cli / desktop / web)重开一张 ask park 的卡时,要按同一套判据回答四个问题;本文件是这
+ * 四问的唯一真源,**一个渲染面都不碰**(帧/卡口/HitlBridge 全在调用方):
+ *   ① 「此刻队列里有没有一行**该由本臂决**的行?」        → {@link classifyAskParkRows}(三态)
+ *   ② 「这一行的身份键是什么?」                           → {@link askParkRowIdentity}
+ *   ③ 「这一行该走问答臂还是工具门臂?」                   → {@link askParkRowArm}
+ *   ④ 「链跑砸了、而行已不在表 —— 这是已决还是没轮到?」   → {@link classifyAskParkChainFailure}
+ * 外加一件构造保证:同一行的并发重开**合流**成一次({@link createRowArmSingleFlight})。
+ *
+ * ── ① 三态与证据纪律(cli #269 的整个要点)────────────────────────────────────────────────────
+ * `/v1/approvals` 是 **scope 级全量单队列**:child 委派的 park 行 `taskId` = child 自己的 run id,
+ * 所以「按 busy 信号点名的 taskId 单键过滤」会结构性漏看。发现面 = 全量取回 → 先找点名行 →
+ * 没有时**在队列无歧义(恰一行)且该行归属可正向证明**的前提下兜底。
+ * 🔴 分态只有一条纪律:**只有正面证据才配 `settled`**。
+ *   · 空表 / 多行无点名行 / 唯一行归属证明不了 ⇒ 一律 `unborn`(缺席证明不了任何事;这三种形都
+ *     可能在下一拍变成「我的那一行出生了」——引擎正在跑那次决定 Write 参数的模型调用);
+ *   · 行在、但门种不属 ask 门族 ⇒ 也只给 `unborn`。「看得见的这一行不属本臂」与「这里已经没有本臂
+ *     该决的事」是两件事,而门换代窗恰恰会短暂两者同形(plan_review 行在 decide 落地后还能被读到
+ *     一小会儿,接替它的 human/tool_approval 行尚未出生)。把这一拍读成终判 = 把失败形换个姿势
+ *     原样复现。代价(如实记):真·走错臂时要等满有界窗才说那句诚实话。
+ * ⇒ 本函数**今天一条 `settled` 都不产**,这是成文结论不是遗漏:队列读面给得出的一切都只是缺席类
+ *   证据。`settled` 留在 {@link ParkRowProbe} 契约里给**读面更强**的宿主(注入 gate 实例态/wire
+ *   直供门身份)用 —— 那时「已了结」才是拿得出正面证据的判决。
+ *
+ * ── ③ 行路由:锚在**决定量**上,不锚门种的名字 ───────────────────────────────────────────────
+ * 🔴 `gateKind === 'human'` **不是**「这是 AskUserQuestion」的证据(engine 7.18.0 真 wire 直证):
+ * plan 批准之后铸出的 **Write** 审批行带的就是 `gateKind:"human" · toolName:"Write" ·
+ * input:{file_path,content}`。`human` 在引擎侧是**泛化的「要人来决定」**(本包 `hitlBridge.observe`
+ * 对 `gate:null` 的补形同样是 `{kind:'human'}`),它与 `tool_approval` 是「粗粒度 / 细粒度」的关系,
+ * 不是「问答 / 工具」的二分。把 `human` 单义化成问答臂,那一行就会被送进没有问句 payload 的臂 ⇒
+ * 静默失败 ⇒ write 卡永不呈现。问答臂要的东西是**问句**,那就问「这行到底有没有问句」。
+ *
+ * ── 归层 ────────────────────────────────────────────────────────────────────────────────────
+ * 本文件值级 import 全在包内(gateIdentity / parkOwnership / frameRouter / activeRunSelfHeal 词表),
+ * SDK 只 type-only;零宿主端口、零模块级状态(单活闸是**工厂**,寿命归调用方 —— 包不替宿主决定
+ * 那张表活多久)。
+ */
+import type { PendingCheckpoint } from '@sema-agent/sdk';
+import type { ParkRowProbe } from './parkRowBirthWait.js';
+import { type ParkOwnershipDeps } from './parkOwnership.js';
+/**
+ * 待决行有界等待窗的**建议上限**(端可覆盖;`waitForParkRowBirth` 自己不带缺省)。
+ * 实测锚:plan 批准之后引擎要跑**一次真实模型调用**才算得出 Write 的参数、才把审批行落库 ——
+ * t+2500ms 读到的仍是空表,t+3000ms 行才出生。15s = 实测 3s 的 5 倍余量(慢模型/负载下的头部
+ * 延迟);超限如实收口 —— 到那一刻降级话是真话,这正是有界的意义。
+ * 🔴 代价如实记:真孤儿 park(座位占着、确实没有任何待决行)要等满这个窗才说那句诚实的失败话。
+ * 方向取舍 = 让**常见且可修**的那一态(行未出生)真的被接住,代价是**罕见且本就已坏**的那一态
+ * 多等一个有界窗;等待全程可被中断(signal 直通重查环)。
+ */
+export declare const ASK_PARK_ROW_WAIT_MS = 15000;
+/** 重查节奏建议值。500ms 级:比行出生的量级(秒)细一个数量级,又不至于把本地引擎打成轮询风暴。 */
+export declare const ASK_PARK_ROW_POLL_MS = 500;
+/** {@link classifyAskParkRows} 的注入口(缺省 = 包内归属判据)。 */
+export interface AskParkRowScanDeps {
+    /** 归属判据(缺省 = `pendingRowIsOwnedByThisSession`)。fail-CLOSED:证不出 = 不采信。 */
+    isOwned?: (row: PendingCheckpoint) => boolean;
+    /** 缺省归属判据的注入位(多会话宿主传 sessionKey / 自己的 currentSessionId)。 */
+    ownership?: ParkOwnershipDeps;
+}
+/**
+ * ① 「本臂此刻有没有一行可决断的行」——三态判决(见文件头)。**纯函数**:行由调用方读面取回,
+ * 本函数只判;绝不抛。
+ *
+ * @param rows   `/v1/approvals` 全量 pending 行(scope 级单队列原样)
+ * @param taskId busy 信号点名的 run id(优先匹配它;匹配不到才谈兜底)
+ */
+export declare function classifyAskParkRows(rows: readonly PendingCheckpoint[], taskId: string, deps?: AskParkRowScanDeps): ParkRowProbe<PendingCheckpoint>;
+/** ② 行身份三件套(重开链的一切键都从这里出;两处各算一遍必漂)。 */
+export interface AskParkRowIdentity {
+    /** 🔴 行内身份绑定:decide 腿一律按**该行自己的** taskId 走,绝不绑请求者的 —— 兜底腿把别的行
+     *  解到请求者名下时,按请求者的 id 去决断就是决了另一件事。 */
+    rowTaskId: string;
+    gatedCallId: string | undefined;
+    /** 首见/复见 + 呈现回执的台账键(`gateIdentity.approvalCallKey` 单源,端零手抄字面)。 */
+    armedKey: string;
+}
+/** ② 算一行的身份三件套。`taskId` = 请求者点名的 id(行自己没带 taskId 时的回退)。 */
+export declare function askParkRowIdentity(taskId: string, row: PendingCheckpoint): AskParkRowIdentity;
+/**
+ * ③ 这一行该走哪条臂。判据锚在**决定量**(这行到底有没有问句)上,不锚门种的名字 —— 理由见文件头。
+ *   · kind 缺席(pre-3.0.0 旧行)⇒ 维持 toolName 判据(旧行没有别的信号);
+ *   · kind 是 ask 门族里 `human` 之外的词(tool_approval / irreversible_ask / policy_ask)⇒ 工具臂;
+ *   · kind = `human` ⇒ 三选一命中即问答臂:toolName 明说是 ask 工具 / 行真带问句 payload /
+ *     行**连 toolName 都没有**(没有工具可渲,问答臂是唯一可能的形,且它自己会对空 payload 诚实收口)。
+ * 🔴 `toolName` 是 UNTRUSTED wire 位且 `/v1/approvals` 行不经工具名归一 —— 用包的规范判据
+ *    {@link isAskTool}(空白/下划线/大小写不敏感),严格串比会把小写形误路由进工具臂。
+ */
+export declare function askParkRowArm(row: PendingCheckpoint): 'question' | 'tool-gate';
+/**
+ * ④ 「这一行还在不在待决表里」——回读判据(键取法与 {@link askParkRowIdentity} 同源)。
+ * 🔴 调用方读面失败时**必须**当「还在」(保守:照走重试/上屏;重复 decide 由 server 侧 checkpoint
+ * 一次性消费挡住,二发只会得到 stale/no_pending 拒绝,不会 double-act)。
+ */
+export declare function askParkRowStillPending(rows: readonly PendingCheckpoint[], identity: AskParkRowIdentity): boolean;
+/**
+ * ④ 链失败之后「行已不在 pending 表」的**两义分臂**判决。
+ *   · `retry`            —— 行还在表上 ⇒ 这就是一次真失败:照走重试 / 如实上屏;
+ *   · `row-gone-after-card` —— 行没了 **且卡呈现过** ⇒ **静默收口**:零重试、零失败话、零成功断言。
+ *     🔴 名字刻意只说**可观察事实**(二次评审两轮处置):它不叫「已在别处决了」,因为呈现只证明卡
+ *     渲出来过,证明不了有人做过决定 —— 一个带决断语义的判决值会诱导宿主替引擎宣布成功。它成立的
+ *     判据是两件可观察事实的合取:队列回读说这一行已不在待决表(一次真读数,不是缺席推断),且本链
+ *     确实把卡交到过渲染面。处置的理由也只由这两件事推出:重试 = 对一个不在待决表的行再决一次
+ *     (server 侧 checkpoint 一次性消费会拒),上屏「the session is still held」= 对一个已不在队列的
+ *     行说它还占着。🔴 宿主**不许**据此对用户断言「你的决定已生效」。残余(如实记):行在呈现窗里
+ *     被换代/过期而恰好没人决过时,这一格会把它按已收口处理 —— 代价是这一轮不再重开(用户下一条
+ *     消息会再撞 409,自愈腿重跑);要真的分出「已决」只能靠决断回执 / typed stale·conflict 应答那类
+ *     **正面证据**,而那属于决断腿的供给面,不在本读面。
+ *     🔴 为什么不干脆退回 `row-unborn` 继续重查(二次评审 R3 [medium] 提议,**未采纳**,理由对称):
+ *     那会把**最常见的良性时序**(决断真落地 → 座位释放 → 队列从此空表)变成「白等满一个窗,然后
+ *     对用户说『没能重开那张卡』」—— 一句同样为假的话,而且它出现在事情**本来就成了**的那一格。
+ *     两个方向各有一次谎报风险,取舍按代价:本格的代价是这一轮不重开(下一条消息自愈腿重跑,可收敛),
+ *     对面的代价是每一次成功决断都附赠一句假失败 + 一个满窗停顿(每次都发生,不可收敛)。
+ *   · `row-unborn`        —— 行没了 **且一张卡都没呈上** ⇒ 没有任何人决过任何事,行消失只可能是
+ *     「刚才那一行换代了 / 下一只门的行还没铸出来」。此时按成功收口 = 对一件从没发生过的决断下
+ *     断言,而呈现回执永远等不到 ⇒ 用户拿到降级话,三秒后真的出生的那张卡再没人去接。这一格
+ *     **不是失败**(不上失败话、不重试),交回有界重查环。
+ *
+ * 🔴 `cardPresented` 必须是**无窗的事实**(整条链寿命里的呈现事件订阅),不能拿带看门狗的呈现回执
+ * 近似:迟到卡会让带窗的那只回 false,于是一次真呈现被误判成「行从未出生」,重查环再铸一张卡 ⇒
+ * 同一个待决项两张可按的卡。
+ */
+export type AskParkChainFailureDisposition = 'retry' | 'row-gone-after-card' | 'row-unborn';
+export declare function classifyAskParkChainFailure(i: {
+    rowStillPending: boolean;
+    cardPresented: boolean;
+}): AskParkChainFailureDisposition;
+/**
+ * **行级重开单活闸**:同一行(键 = {@link AskParkRowIdentity.armedKey})的第二个调用方**合流**到
+ * 在飞的那一次(拿逐字相同的判决),不另起一条链 —— 「一个待决项至多一张卡」由此是构造保证。
+ *
+ * 🔴 为什么按**行键**而不是请求者的 taskId:发现面的兜底腿会把**不同** taskId 的两个调用方解到
+ * **同一行**,那时两条链会各铸一张身份不同、都能按的卡 —— 同一个待决项两张卡,先按的决断、后按的
+ * 变成 stale 误导面。而重开臂的寿命一旦从毫秒级拉到一个秒级的有界重查窗,「结构上不容易撞上」就
+ * 不再是防线([paired-mechanisms]:两半各持「对方会兜底」的假设 = 零结果),必须在源头收掉。
+ *
+ * 🔴 **工厂,不是模块级台账**:这张表的寿命 = 宿主一个会话的重开面,由装配点持有;包不替宿主决定
+ * 它活多久,多会话宿主天然一会话一只(单例化反而会让两个会话互相合流)。
+ */
+export interface RowArmSingleFlight<T> {
+    /** 有在飞的同键链 ⇒ 返回它(第二个调用方零副作用);否则起一条并登记(结束后自动清账)。 */
+    join: (key: string, start: () => Promise<T>) => Promise<T>;
+    /** 当前在飞条数(诊断/测试用)。 */
+    size: () => number;
+    /** 清空(套件之间不许互相串态)。 */
+    clear: () => void;
+}
+export declare function createRowArmSingleFlight<T>(): RowArmSingleFlight<T>;