@sema-agent/client-core 0.27.0 → 0.29.0

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

@@ -60,6 +60,22 @@
  * 🔴 fail-soft 铁律(与 ask 桥同款):leader 队列未注册(print/非 REPL)、pending 蒸发、decide 409/404
  *   都返回 failed —— 调用方回退「flush + 原样终帧」的诚实红,绝不更糟。
  * 🔴 UNTRUSTED:gate args 为模型作文(service 已 redact),只渲染绝不回喂;决断只带 decision 枚举。
+ *
+ * ── #144 半场(client-core 0.28.0)────────────────────────────────────────────────────────────
+ * ① **透传** `persistedRuleShadowed`(server ≥7.13.0,来源锚 = engine fixture
+ *    `@sema-agent/server/dist/tool-approval.d.ts` 同名键;ADDITIVE、`tool_approval` only)——
+ *    帧 → {@link ApprovalCardRequest.persistedRuleShadowed},壳据此渲「你的规则仍在,只是这次被
+ *    要求逐次确认」。🔴 它是 **display 值,不是身份通道**:脱敏后的展示文本,不保证与规则店里那条
+ *    规则逐字节相同、更不是它的 id;下游「删除/撤销规则」面拿它当身份用 = 删错或删不掉。
+ * ② **deny 归因通道**({@link ApprovalCardDenyDecision.reason}):两腿不同形 ——
+ *    durable `/decide` **有** reason 位 ⇒ 原文上 wire(包内按 server 4096 上限截断);
+ *    live 帧腿 `/v1/tool-approvals/:id/respond`:✅ **#229 已兑现**(0.29.0 respond-note 批,
+ *    server ≥7.15.0)—— 端点收 **`note`**(不是 reason;与 durable `AskDecisionBody.note`
+ *    同词同源同一列 `decision_note`),deny reason 经 {@link RespondToolApprovalOpts.note} 上 wire。
+ *    发送前置两道门:能力位 `approvalDecisionNote`(SDK 6.16 成文「位缺席就别发」)+ 2048 上限
+ *    (server 超限响亮 400 且**连决断一起拒**,所以超限 ⇒ 整条不发 + 留痕,诚实缺席优先于
+ *    静默截断);真落行与否看 ack 的 `noteRecorded`(缺席 ≠ false)。
+ *    🔴 方向纪律:reason/note 只做归因,绝不参与裁决;缺席 ⇒ 现状字节不变。
  */
 import { type HitlClientLike } from './hitlBridge.js';
 import type { RuleSuggestion, ToolApprovalRespondAck } from '@sema-agent/sdk';
@@ -111,9 +127,29 @@ export interface ApprovalCardAllowDecision {
      *  缺席/空串 = 本次不兑付。表外文本会在编排层被丢键留痕(server 亦拒 rule_not_offered)。 */
     persistRule?: string;
 }
-export type ApprovalCardDecision = ApprovalCardAllowDecision | {
+/**
+ * deny 决断臂(命名形,typeshape B4 口径;0.28.0 因 `reason` 位抽名,与 0.26.0
+ * {@link ApprovalCardAllowDecision} 抽名同姿势)。
+ */
+export interface ApprovalCardDenyDecision {
     kind: 'deny';
-} | {
+    /**
+     * #144 半场(0.28.0):这次拒绝的**归因原文**——人手打的拒绝说明,或壳侧权限规则自动 deny 的
+     * 机器判据(rule-deny / dontAsk / headless fail-closed 三条路)。缺席/空白 = 不带归因,调用方
+     * 落回既有缺省拒因,**现状字节不变**。
+     *
+     * 🔴 **方向纪律**:reason 只进归因通道,**绝不参与裁决** —— 带不带它、内容是什么,都不改变
+     * 这次决断仍是 deny(两条腿上的 `decision` 位逐字节不动)。
+     * 🔴 **两腿不同形**(见 {@link surfaceFsApprovalAndDecide} / {@link surfaceToolApprovalFrameAndRespond}):
+     *   · durable park 腿(`/decide`)wire **有** reason 位 ⇒ 原文上 wire(包内按 server 上限截断);
+     *   · live 帧腿(`/v1/tool-approvals/:id/respond`)wire 是三词闭集、**无** reason 位 ⇒ 只留痕不发,
+     *     绝不自造侧信道(候 server 给 respond 补位)。
+     * 与 `{kind:'failed'}` 的 `reason` **不同义**:那一位是「卡面本身不可用」的诊断,不是人的拒因,
+     * 两者绝不互相顶替。
+     */
+    reason?: string;
+}
+export type ApprovalCardDecision = ApprovalCardAllowDecision | ApprovalCardDenyDecision | {
     kind: 'aborted';
 } | {
     kind: 'failed';
@@ -150,6 +186,19 @@ export interface ApprovalCardRequest {
      * 出身裁剪(MANDATED ask 不提供本档)候 core 5.25.0 出身键 wire 过境,见 #144/[3438]/[3442]。
      */
     ruleSuggestions?: RuleSuggestion[];
+    /**
+     * 被越级的持久 allow 规则**原文**(#144,原样来自 {@link ToolApprovalFrame.persistedRuleShadowed}
+     * 的合形值)——壳据此渲「你的规则仍在,只是这次调用被要求逐次确认」;缺席 = 卡形与 0.27.0
+     * 字节不变(不渲该行)。
+     *
+     * 🔴 **display 值,不是身份通道**:它是一段**已过脱敏**的展示文本(core `inlineUntrusted` +
+     * server `redactSecrets`),不保证与规则店里存着的那条规则逐字节相同,更不是规则的 id/句柄。
+     * 下游的「删除/撤销这条规则」面**不许**把它当身份用(拿它去 match 规则店 = 删错规则或删不掉),
+     * 也不许把它回喂给模型/工具入参;要操作规则必须走规则店自己的枚举与标识。
+     * 🔴 **缺席 ≠「你没有规则」**:键只在「有规则命中 ∧ 规则清不掉这只 ask」时在场,绝大多数 ask
+     * 压根没有规则命中(缺席),而命中且清掉了的那些根本不会变成卡。
+     */
+    persistedRuleShadowed?: string;
 }
 /**
  * 🔴 **拆缝口** —— 弹「三选卡」并等人的决断。壳 = vendored CC `PermissionRequest`;
@@ -239,6 +288,30 @@ export interface ToolApprovalFrame {
      * (`respond` 体 `persistRule.rule`),报表外文本 = server 拒 `rule_not_offered`。
      */
     ruleSuggestions?: RuleSuggestion[];
+    /**
+     * server ≥7.13.0(#144 / core 5.25.0,[3438] 接力契约 / [3443] 主件;**ADDITIVE**,
+     * `"tool_approval"` only。来源锚 = engine fixture `@sema-agent/server/dist/tool-approval.d.ts`
+     * 的同名键)——这只 ask **命中了**调用方的一条持久 allow 规则,而那条规则**没能清掉它**。
+     * 值 = 被越级的那条规则**原文**(core `AskRequest.persistedRuleShadowed`,core 侧已过
+     * `inlineUntrusted`;server 侧与 `message`/`sourceAgentName` 同待遇 `redactSecrets` 后上帧)。
+     *
+     * 🔴 它存在的理由是一次真实的用户面回归:core 5.25.0 收窄消音边界后(「Allow rules silence the
+     * CLASSIFIER's questions, never a MANDATED one」),此前被规则消掉的 ask 重新出现 —— 没有这个键,
+     * 人看到的是「我明明点过『不再询问』,它怎么又问」,唯一合理的结论是「我的规则坏了/没存上」。
+     *
+     * 🔴 **缺席 ≠「你没有规则」**:键只在「有规则命中 ∧ 规则清不掉这只 ask」时在场。绝大多数 ask
+     * 压根没有规则命中(缺席),而**命中且清掉了**的那些根本不会变成 ask(被消音了,没有卡)。
+     * 🔴 与 {@link governanceForced} **刻意分列不合并**:那个键答「门是谁下的」(运维治理层),本键
+     * 答「你那条规则怎么了」。不可消音的来源有三类(governance / doctrine `always` / 工具自带 mark),
+     * 合并会让后两类要么谎报治理出身、要么丢掉规则解释。
+     * 🔴 **UNTRUSTED-for-display,且不是身份通道** —— 详见
+     * {@link ApprovalCardRequest.persistedRuleShadowed} 的同名警示(下游删除规则面不许拿它当规则身份)。
+     *
+     * 耐久路(park 行)的对偶是 `gate.riskDescriptor.shadowedRule`(server 对 riskDescriptor 整体透传);
+     * 本包的 durable 腿今天不 stamp 任何展示键(见 {@link surfaceFsApprovalAndDecide} 的卡入参),
+     * 那一路的消费是独立的一件,不在本键的施工面内。
+     */
+    persistedRuleShadowed?: string;
 }
 /** {@link ToolApprovalFrame.delegation} 的形(命名形,不用内联匿名 —— typeshape 门 B4 棘轮口径)。 */
 export interface ToolApprovalDelegation {
@@ -254,7 +327,7 @@ export interface ToolApprovalDelegation {
  * `TOOL_APPROVAL_FRAME_KEYS` 比对——SDK additive 增键时对账当天红,不再人肉追平。
  * 下面两个类型钉保证镜像与 interface 本身不可能漂移(少键/多键都是编译错)。
  */
-export declare const TOOL_APPROVAL_FRAME_KEYS_MIRROR: readonly ["type", "approvalId", "toolCallId", "toolName", "sourceTaskId", "fromSubagent", "sourceAgentName", "message", "args", "argsOmitted", "governanceForced", "ruleSuggestions", "delegation", "outcome"];
+export declare const TOOL_APPROVAL_FRAME_KEYS_MIRROR: readonly ["type", "approvalId", "toolCallId", "toolName", "sourceTaskId", "fromSubagent", "sourceAgentName", "message", "args", "argsOmitted", "governanceForced", "ruleSuggestions", "persistedRuleShadowed", "delegation", "outcome"];
 /** 子代帧判别:显式键 fromSubagent(core 1.378 RB-39②)优先;缺席退 sourceTaskId 在场性权宜式
  *  (server 1.258 [1549]①3,旧代际兼容)。 */
 export declare function isFromSubagent(frame: ToolApprovalFrame): boolean;
@@ -280,6 +353,11 @@ export interface RespondToolApprovalOpts {
     updatedInput?: unknown;
     /** #225 件1:兑付键 —— 帧候选之一的**原文**(编排层已做表内核对与 deny 剥除)。 */
     persistRule?: string;
+    /** #229(server ≥7.15.0):回决备注 —— 与 durable 腿 `AskDecisionBody.note` **同词同源同一列**
+     *  (`decision_note`,≤2048)。任何 decision 都可带(deny 的「为什么拒」正是审计面上最值钱的
+     *  一条);真落行与否看 ack 的 {@link surfaceToolApprovalFrameAndRespond} 消费的 `noteRecorded`。
+     *  🔴 编排层(本文件)只在能力位确认 + 上限内才填本位 —— 注入面原样透传,别自己再判。 */
+    note?: string;
 }
 export type RespondToolApprovalFn = (approvalId: string, decision: ToolApprovalRespondDecision, opts?: RespondToolApprovalOpts) => Promise<ToolApprovalRespondAck | void>;
 /**
@@ -310,13 +388,14 @@ export interface ToolApprovalFrameOutcome {
  *  `AgentEvent` 的臂了(durable 腿也回放),所以结构识别与 union 收窄两条路都成立;本函数仍按
  *  结构读(不依赖类型收窄),因为它同时服务 raw SSE 与 durable 回放两条入口。 */
 export declare function isToolApprovalFrame(ev: unknown): ev is ToolApprovalFrame;
-/**
- * 消费一张 `tool_approval` 帧:弹三选卡 → respond。引擎此刻同步阻塞在本帧上(fail-closed 全腿:
- * TTL 5min/abort/emit 失败⇒deny),所以本函数 await 卡决断是安全的(流上不会再来别的内容帧)。
- *
- * fail-closed:卡面不可用(print 模式无卡口/enqueue 失败)⇒ 立刻 respond deny,不让引擎
- * 干等 TTL。respond 自身失败(404=已过期/settled)⇒ 'unresolved'(诚实放行后续帧,引擎已自决)。
- *
- * @returns {@link ToolApprovalFrameOutcome} —— 决断 + server ack(ack 缺席 = 未知,不是 false)。
- */
-export declare function surfaceToolApprovalFrameAndRespond(frame: ToolApprovalFrame, respond: RespondToolApprovalFn, streamArgs: unknown | undefined, signal?: AbortSignal): Promise<ToolApprovalFrameOutcome>;
+/** 帧腿的宿主车道参数(#229 respond-note 批,0.29.0)。 */
+export interface ToolApprovalFrameLaneOpts {
+    /**
+     * server 能力位 `capabilities.approvalDecisionNote` 的读数(宿主从自己的 caps 缓存供给)。
+     * 🔴 SDK 6.16 成文:**位缺席就别发 `note`** —— 老 server 对未知请求键静默忽略且照回 200,
+     * 「这台不认识 note」与「记上了」在响应上不可分,发了只造「已留档」的错觉。
+     * 缺席/false ⇒ 不发(fail-closed 到「不发」侧;决断本身照常送达,现状字节不变)。
+     */
+    approvalDecisionNoteCapable?: boolean;
+}
+export declare function surfaceToolApprovalFrameAndRespond(frame: ToolApprovalFrame, respond: RespondToolApprovalFn, streamArgs: unknown | undefined, signal?: AbortSignal, lane?: ToolApprovalFrameLaneOpts): Promise<ToolApprovalFrameOutcome>;

package/dist/hitl/toolApprovalWire.js

@@ -60,12 +60,29 @@
  * 🔴 fail-soft 铁律(与 ask 桥同款):leader 队列未注册(print/非 REPL)、pending 蒸发、decide 409/404
  *   都返回 failed —— 调用方回退「flush + 原样终帧」的诚实红,绝不更糟。
  * 🔴 UNTRUSTED:gate args 为模型作文(service 已 redact),只渲染绝不回喂;决断只带 decision 枚举。
+ *
+ * ── #144 半场(client-core 0.28.0)────────────────────────────────────────────────────────────
+ * ① **透传** `persistedRuleShadowed`(server ≥7.13.0,来源锚 = engine fixture
+ *    `@sema-agent/server/dist/tool-approval.d.ts` 同名键;ADDITIVE、`tool_approval` only)——
+ *    帧 → {@link ApprovalCardRequest.persistedRuleShadowed},壳据此渲「你的规则仍在,只是这次被
+ *    要求逐次确认」。🔴 它是 **display 值,不是身份通道**:脱敏后的展示文本,不保证与规则店里那条
+ *    规则逐字节相同、更不是它的 id;下游「删除/撤销规则」面拿它当身份用 = 删错或删不掉。
+ * ② **deny 归因通道**({@link ApprovalCardDenyDecision.reason}):两腿不同形 ——
+ *    durable `/decide` **有** reason 位 ⇒ 原文上 wire(包内按 server 4096 上限截断);
+ *    live 帧腿 `/v1/tool-approvals/:id/respond`:✅ **#229 已兑现**(0.29.0 respond-note 批,
+ *    server ≥7.15.0)—— 端点收 **`note`**(不是 reason;与 durable `AskDecisionBody.note`
+ *    同词同源同一列 `decision_note`),deny reason 经 {@link RespondToolApprovalOpts.note} 上 wire。
+ *    发送前置两道门:能力位 `approvalDecisionNote`(SDK 6.16 成文「位缺席就别发」)+ 2048 上限
+ *    (server 超限响亮 400 且**连决断一起拒**,所以超限 ⇒ 整条不发 + 留痕,诚实缺席优先于
+ *    静默截断);真落行与否看 ack 的 `noteRecorded`(缺席 ≠ false)。
+ *    🔴 方向纪律:reason/note 只做归因,绝不参与裁决;缺席 ⇒ 现状字节不变。
  */
-import { HitlBridge, HitlSafetyError, findPendingForTask } from './hitlBridge.js';
+import { DEFAULT_DENY_REASON, HitlBridge, HitlSafetyError, denyReasonForWire, findPendingForTask, } from './hitlBridge.js';
 import { hostLog } from '../host.js';
 import { createSessionSlot, DEFAULT_SESSION_KEY } from '../sessionSlot.js';
 import { readEngineActiveBgTasks } from '../fleet/fleetLedger.js';
 import { observeCancelByDeny, surfaceRememberNotApplied, surfaceEditNotForwarded } from './hitlHostSurface.js';
+import { approvalCallKey, liveFrameCallKey } from './gateIdentity.js';
 /** fs 写权限 gate 判定:未来的一等 kind(tool_approval)或按 toolName(server 桥首批=fs 写三件,
  *  [820] 表)。AskUserQuestion 永不进这里(ask 桥先判)。 */
 export function isFsApprovalGate(gate) {
@@ -195,6 +212,8 @@ function cardPortMissReason() {
     }
     return 'no approval card port installed (print/non-REPL mode, or host forgot installApprovalCardPort)';
 }
+// deny 归因窄化(0.28.0 发版扫描 F1 收编):单源下沉 hitlBridge —— 三条 reason 出口(卡 deny /
+// canUseTool deny / plan-review)共用一把,坐标与理由见 hitlBridge.ts 的导出处顶注。
 /**
  * 弹 CC 三选卡 → 等决断 → 经 HitlBridge decide(durable park 腿,server 桥前的 checkpointGate 面;
  * 合成单测/旧引擎兜底保留)。decide 成功即引擎驱到下一状态(sync);调用方随后 attach runs.events
@@ -227,7 +246,8 @@ export async function surfaceFsApprovalAndDecide(deps, taskId, argsByCall, signa
         return { kind: 'failed', gatedCallId, reason: 'gate has no tool input payload' };
     }
     const bridge = new HitlBridge(deps.client, taskId);
-    const callKey = gatedCallId ?? taskId;
+    // A-028.3:卡身份键经 gateIdentity 唯一铸口(呈现台账/壳侧重开腿同源,字面不再各铸各的)。
+    const callKey = approvalCallKey(gatedCallId, taskId);
     const card = await surfaceApprovalCard({
         toolName,
         args,
@@ -277,7 +297,11 @@ export async function surfaceFsApprovalAndDecide(deps, taskId, argsByCall, signa
             }
         case 'deny':
             try {
-                await bridge.decideTool({ decision: 'deny', reason: 'The user rejected this tool use' }, gatedCallId, signal ? { signal } : undefined, pending);
+                // #144 半场(0.28.0):卡给的拒因原样上 wire(`/decide` 本就有 reason 位)—— 壳侧三处权限
+                // 规则自动 deny(rule-deny / dontAsk / headless fail-closed)的真实拒因此前只能落 debug 日志,
+                // 引擎与运维队列上看到的都是那句无差别的缺省文案。缺席/空白 ⇒ 缺省,现状字节不变。
+                // 🔴 归因不改裁决:无论 reason 是什么,这一支恒 `decision:'deny'`。
+                await bridge.decideTool({ decision: 'deny', reason: denyReasonForWire(card.reason, `task ${taskId}`) ?? DEFAULT_DENY_REASON }, gatedCallId, signal ? { signal } : undefined, pending);
                 return { kind: 'decided', gatedCallId, denied: true };
             }
             catch (e) {
@@ -309,6 +333,11 @@ export const TOOL_APPROVAL_FRAME_KEYS_MIRROR = [
     // sdk 6.14.0 追平(#225 件1,client-core 0.26.0):server 7.12.0 起真发规则候选 —— 门
     // (run-approval-frame-keys-test.mjs)在 bump SDK 当天恰红抓获本键缺席,本次补齐。
     'ruleSuggestions',
+    // #144(client-core 0.28.0):server 7.13.0 起真发 `persistedRuleShadowed`(证据=engine fixture
+    // 的 `@sema-agent/server/dist/tool-approval.d.ts`)。⚠️ 本键**领先** SDK 运行期锚一代
+    // (sdk 6.14.0/6.15.0 的 TOOL_APPROVAL_FRAME_KEYS 都还没有它)⇒ 对账门里有一条**带退出条件**的
+    // 领先登记(AHEAD_OF_ANCHOR):SDK 锚一旦补上,那条登记当场红,逼人删登记而不是让豁免长住。
+    'persistedRuleShadowed',
     'delegation',
     'outcome',
 ];
@@ -384,6 +413,9 @@ export function readToolApprovalRespondAck(v) {
         ...(typeof o.ruleRefusal === 'string' && o.ruleRefusal !== ''
             ? { ruleRefusal: o.ruleRefusal }
             : {}),
+        // #229(sdk 6.16.0):这次回决的 note 有没有**真落进持久行**。缺席 ≠ false(未带 note 的回决/
+        // 老 server 字段省略);非布尔降缺席 —— 它决定「审计理由记没记上」的诚实告知。
+        ...(typeof o.noteRecorded === 'boolean' ? { noteRecorded: o.noteRecorded } : {}),
     };
 }
 /** 结构性识别流上的 tool_approval 帧(named SSE frame,payload.type === 帧名)。
@@ -473,7 +505,10 @@ function subagentBadgeFor(frame) {
  *
  * @returns {@link ToolApprovalFrameOutcome} —— 决断 + server ack(ack 缺席 = 未知,不是 false)。
  */
-export async function surfaceToolApprovalFrameAndRespond(frame, respond, streamArgs, signal) {
+/** respond `note` 位的 server 上限(server `MAX_DECISION_NOTE_CHARS` = 2048,与 durable
+ *  `AskDecisionBody.note` 同一列;超限 server **响亮 400 且连决断一起拒**,所以本包发送前有界)。 */
+const MAX_RESPOND_NOTE_CHARS = 2048;
+export async function surfaceToolApprovalFrameAndRespond(frame, respond, streamArgs, signal, lane) {
     const toolName = typeof frame.toolName === 'string' ? frame.toolName : 'Write';
     // 工具入参:流上 tool_start.args(完整一手源)> 帧 args(redacted+16KiB 帽)> message 兜 path。
     let args = streamArgs !== undefined && streamArgs !== null
@@ -503,7 +538,8 @@ export async function surfaceToolApprovalFrameAndRespond(frame, respond, streamA
     const card = await surfaceApprovalCard({
         toolName,
         args: args,
-        callKey: `hitl-frame:${frame.approvalId}`,
+        // A-028.3:live 帧腿的卡身份键经 gateIdentity 唯一铸口(帧上无 gatedCallId,以 approvalId 铸)。
+        callKey: liveFrameCallKey(frame.approvalId),
         ...(signal ? { signal } : {}),
         ...(isFromSubagent(frame) ? { workerBadge: subagentBadgeFor(frame) } : {}),
         ...(wireNote !== undefined ? { wireNote } : {}),
@@ -518,11 +554,44 @@ export async function surfaceToolApprovalFrameAndRespond(frame, respond, streamA
             : {}),
         // #225 件1:规则候选透传(合形项;缺席/坏形 ⇒ 键不 stamp,卡形与 0.25.0 字节不变)。
         ...(ruleSuggestions !== undefined ? { ruleSuggestions } : {}),
+        // #144:被越级的持久规则原文(UNTRUSTED-for-display)。窄化=**非空白串才 stamp**,坏形降缺席
+        // (server 明说空串不铸键:「空串是坏值不是『空规则』」)—— 一格空白的规则解释比没有解释更坏。
+        // 🔴 stamp 的是**原文字节**(不 trim、不截、不改写):展示值一改写就不再是「你那条规则」的原文;
+        //    渲染面的长度夹取归壳,与 `message`/`sourceAgentName` 同族口径(本模块对展示文本零加工)。
+        ...(typeof frame.persistedRuleShadowed === 'string' && frame.persistedRuleShadowed.trim() !== ''
+            ? { persistedRuleShadowed: frame.persistedRuleShadowed }
+            : {}),
     });
     const decision = card.kind === 'allow' ? (card.allowSession ? 'allow_session' : 'allow') : 'deny';
     if (card.kind === 'failed') {
         hostLog('debug', `liveToolApprovalWire: approval card unavailable (${card.reason}) — fail-closed deny for ${frame.approvalId}`);
     }
+    // #229 兑现(0.29.0 respond-note 批;此前 0.28.0 记账「候 server」,server 7.15.0 已到货):
+    // respond 端点收 **`note`**(不是 reason —— 与 durable `AskDecisionBody.note` 同词同源同一列
+    // `decision_note`),任何 decision 都可带。deny reason 经它上 wire,发送前置两道门:
+    //   · 能力位(`lane.approvalDecisionNoteCapable === true`)—— SDK 6.16 成文「位缺席就别发」:
+    //     老 server 静默忽略未知键照回 200,「没听懂」与「记上了」不可分,发了只造「已留档」错觉;
+    //   · 上限(≤{@link MAX_RESPOND_NOTE_CHARS}=2048)—— server 超限**响亮 400 且连决断一起拒**,
+    //     而备注是决断的补充面,绝不许它把决断本身打失败。超限 ⇒ **整条不发** + 留痕
+    //     (诚实缺席优先于静默截断 —— 「一条被悄悄砍半的审计理由比没有理由更坏」,server 同款立场)。
+    // 🔴 留痕纪律不变:只写**元数据**(在场 + 长度 + 没发的原因),绝不把正文拷进日志 ——
+    //    正文是宿主自己卡口返回的自由文本,回喂宿主 sink 零诊断增量,还是外溢/注入面。
+    let note;
+    if (card.kind === 'deny' && typeof card.reason === 'string' && card.reason.trim() !== '') {
+        if (lane?.approvalDecisionNoteCapable !== true) {
+            hostLog('debug', `liveToolApprovalWire: ${frame.approvalId} card supplied a deny reason (len=${card.reason.length}) but the ` +
+                'approvalDecisionNote capability is not confirmed for this engine — note not sent (an unknown key would be ' +
+                'silently swallowed by an older server while still acking 200)');
+        }
+        else if (card.reason.length > MAX_RESPOND_NOTE_CHARS) {
+            hostLog('debug', `liveToolApprovalWire: ${frame.approvalId} deny reason exceeds the decision_note cap ` +
+                `(len=${card.reason.length} > ${MAX_RESPOND_NOTE_CHARS}) — note not sent at all (the server rejects the WHOLE ` +
+                'respond with 400 over an oversize note, and a silently halved audit reason is worse than none)');
+        }
+        else {
+            note = card.reason;
+        }
+    }
     try {
         // abort 后的 deny 仍要送达(引擎侧同款 cancel-by-deny)——不带已 aborted 的 signal。
         // #225 件1:卡决断携带的 persistRule 只在「确是帧候选之一的原文」时上 wire —— server 本就
@@ -542,6 +611,7 @@ export async function surfaceToolApprovalFrameAndRespond(frame, respond, streamA
             ...(signal && !signal.aborted ? { signal } : {}),
             ...(card.kind === 'allow' && card.updatedInput !== undefined ? { updatedInput: card.updatedInput } : {}),
             ...(persistRule !== undefined ? { persistRule } : {}),
+            ...(note !== undefined ? { note } : {}),
         });
         // 🔴 相关性门(对抗复审二轮):ack 必须是**这一次**审批的回执 —— id 与决断词都要对上。
         //    对不上的 ack(注入面串了别人的响应 / 坏 mock / raw-fetch 包装器复用了连接)如果照样被
@@ -569,6 +639,13 @@ export async function surfaceToolApprovalFrameAndRespond(frame, respond, streamA
             hostLog('debug', `liveToolApprovalWire: ${frame.approvalId} edited args were NOT forwarded (ack.updatedInputForwarded=false) — the tool runs on the ORIGINAL input`);
             surfaceEditNotForwarded();
         }
+        // #229:note 发了而 ack 说没落行(noteRecorded=false:纯活卡无行可落 / 店抖但裁决照常生效 /
+        // 并发同决议先落行)或位缺席(异常形:能力位为真却没回执)—— 审计面事实,decision 本身不受
+        // 影响,debug 留痕即可(不惊动用户:决断没丢,丢的只是理由的持久档)。
+        if (note !== undefined && ack !== undefined && ack.noteRecorded !== true) {
+            hostLog('debug', `liveToolApprovalWire: ${frame.approvalId} decision note was sent but not persisted ` +
+                `(ack.noteRecorded=${String(ack.noteRecorded)}) — decision stood; the audit note did not land on the ask row`);
+        }
         return ack !== undefined ? { decision, ack } : { decision };
     }
     catch (e) {

package/dist/index.d.ts

@@ -182,6 +182,7 @@ export * from './adapter/downstream/turnUsageToModelUsage.js';
 export * from './adapter/downstream/eventToSdkMessage.js';
 export * from './adapter/downstream/terminalToSdkResult.js';
 export * from './adapter/runStream.js';
+export * from './adapter/activeRunSelfHeal.js';
 export * from './request/taskRequest.js';
 export * from './clientSlice.js';
 export * from './host.js';
@@ -220,6 +221,9 @@ export * from './hitl/hitlHostSurface.js';
 export * from './hitl/toolApprovalWire.js';
 export * from './hitl/askGateWire.js';
 export * from './hitl/planReviewWire.js';
+export * from './hitl/gateIdentity.js';
+export * from './hitl/armedGateRegistry.js';
+export * from './hitl/parkOwnership.js';
 export * from './hitl/approvalsFeed.js';
 export * from './compensations.js';
 export * from './request/printNotification.js';

package/dist/index.js

@@ -208,6 +208,14 @@ export * from './adapter/downstream/turnUsageToModelUsage.js';
 export * from './adapter/downstream/eventToSdkMessage.js';
 export * from './adapter/downstream/terminalToSdkResult.js';
 export * from './adapter/runStream.js';
+// ── A-028.1(#244 族A,2026-08-12):409 active-run 自愈的分诊树 + 结局文案层 ————————————
+// 判别半场(activeRunBusySignal)在 runStream.js 早已出面;本件是它的消费侧:四路分诊
+// (pendingGate.kind 优先 / status 表回退)+ 八种结局的可覆盖默认文案。归通用半场的理由:
+// 三端面对同一把会话锁 —— cli 交互/headless 两车道换包导入删本地抄件(提货批);desktop
+// session-host 已自写同族「parked run 不能 cancel」分诊,收敛到此;web 读 activeTaskId 的
+// busy 面同源。文案默认串 = cli 产品面逐字,端经 ActiveRunSelfHealCopy 覆盖出路句。
+// 🔴 零值级 import 纯函数叶(类型 type-only 借 runStream),不进内核/A 层闭包。
+export * from './adapter/activeRunSelfHeal.js';
 // ── B4 批:A 层帧分派收官 + 请求面合一 + 构造点收编(2026-07-27)────────────────────────────────
 // 请求面:三个构造器(seamQuery.toTaskRequest / seamQueryEngine / liveClient.toLiveRequest)
 // 的**字段集与合并语义**收成一份;车道差异做成 REQUEST_FIELD_MATRIX 数据表(gap:true = 判为漏)。
@@ -306,6 +314,18 @@ export * from './hitl/hitlHostSurface.js';
 export * from './hitl/toolApprovalWire.js';
 export * from './hitl/askGateWire.js';
 export * from './hitl/planReviewWire.js';
+// ── A-028.2/.3(#244 族A,2026-08-12):决断卡链的键词汇/呈现台账/归属判据三件 ————————————
+// · gateIdentity:三条身份键字面(hitl-ask:/callKey/plan-review:,外加 hitl-frame: 同族)的唯一
+//   铸口 —— 包内三处铸口与呈现台账的键推导同源;壳侧 armedGateRegistry/askParkReopen 的手抄字面
+//   换 import 删本地(提货批);desktop session-host 的 plan:/durable: 前缀族收敛候后续对齐。
+// · armedGateRegistry:per-session 呈现台账(firstSight 文案分形的唯一判据);sessionSlot 键支持
+//   多会话宿主(desktop session-host 多引擎会话),cli 走 DEFAULT_SESSION_KEY 零参兼容层。
+// · parkOwnership:ask park 重开腿的纯判据三件(fail-closed 归属证明/questions 结构判定/
+//   HitlSafetyError duck 判型)—— cli 换包导入删抄件;desktop refreshPendingApprovals 的自写
+//   归属判定收敛到同一判据。approvals.list 编排与 stderr 留各端。
+export * from './hitl/gateIdentity.js';
+export * from './hitl/armedGateRegistry.js';
+export * from './hitl/parkOwnership.js';
 // B7 ③(census G20,**行为改动**不是搬迁):pending-approvals 推送 feed(stream 优先 / 断流回落
 // 轮询 / 定期再试)。🔴 它**不替换** D-1 的取件 —— 那三处必须继续走权威 `list()`(见文件头)。
 export * from './hitl/approvalsFeed.js';

package/dist/liveQuestionStore.d.ts

@@ -68,6 +68,17 @@ type RespondFn = (id: string, answer: QuestionAnswer, opts?: {
 /** Register a one-shot local responder for a SYNTHETIC question frame (e.g. `plan-review:<taskId>`).
  *  Returns an unregister fn (dialog dismissed without answering ⇒ caller cleans up). */
 export declare function registerLocalQuestionResponder(id: string, fn: RespondFn): () => void;
+/**
+ * Unregister a local responder **by id**(A-028.4 复审二轮收紧,2026-08-12)。
+ *
+ * 为什么需要按 id 注销:`registerLocalQuestionResponder` 的注销钩只回到注册方手里,而重开腿
+ * (`planReviewWire.reopenPlanReviewCard`)要退役的是**别的注册方**(arm 臂)登记的 canonical
+ * responder —— 只发 `question_complete` 撤帧撤不掉表里的 responder,一个在途的迟到作答仍能经
+ * 它投递决断,与新卡的投递构成同一 gate 的双决断面。返回是否真删了一条(调用方留痕用)。
+ * 🔴 只删表项,不通知原注册方 —— 原注册方的自愈臂(如 arm 的陈旧武装态分支)按
+ * `hasLocalQuestionResponder` 探询真相,不依赖回调。
+ */
+export declare function unregisterLocalQuestionResponder(id: string): boolean;
 /**
  * Is a local responder for this synthetic questionId still bound?([2393] hitl-F3,2026-08-02)
  *