@sema-agent/client-core 0.28.0 → 0.30.0

package/dist/hitl/resumeRunningCard.js

@@ -0,0 +1,177 @@
+/**
+ * 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/退出码应用口
+ * 全部由端在装配点注入;端只剩装配与呈现。
+ */
+// ── 逐字契约面(答案按 label 原样回声 —— 引擎的 `selected ⊆ options` 围栏,漂一个字节即失灵)──
+/** ① 接管观看。 */
+export const RESUME_CHOICE_ATTACH_LABEL = 'Attach and watch';
+/** ② 用户显式取消(自动 cancel 那个动作的降级形)。 */
+export const RESUME_CHOICE_CANCEL_LABEL = 'Cancel it';
+/** ③ 后台留着 —— 🔴 **默认焦点**,所以它必须排在 options[0](见 {@link resumeRunningOptions})。 */
+export const RESUME_CHOICE_BACKGROUND_LABEL = 'Leave it running in the background';
+/** 卡的 header(答案按 header 归键;本卡只有一问)。与 409 三选卡的入口刻意不同词 —— 同一张卡的
+ *  两个入口,题面说的不是一件事。 */
+export const RESUME_CHOICE_HEADER = 'Earlier run still in flight';
+/**
+ * §3.2a 活性证据行。**缺席 ⇒ null(整行不渲)**;绝不渲 0、绝不渲「已死」。
+ * 负数 / 非有限值同样按缺席处理(wire 位 UNTRUSTED,类型说是 number 也要真判)。
+ */
+export function resumeRunningLivenessRow(msSinceLastActivity) {
+    const ms = msSinceLastActivity;
+    if (typeof ms !== 'number' || !Number.isFinite(ms) || ms < 0)
+        return null;
+    return `The engine last recorded activity on it ${String(Math.round(ms / 1000))}s ago.`;
+}
+/**
+ * 卡的题面。第二行 = 活性证据(§3.2a 缺席时**整行消失**,不留占位、不留「unknown」字样 ——
+ * 一行「last activity: unknown」和一行 0 一样是在替引擎回答一个它没回答的问题)。
+ */
+export function resumeRunningQuestionText(i) {
+    const head = `This conversation was resumed while an earlier turn is still executing on the engine ` +
+        `(run ${i.taskId}, status ${i.status}). sema did not touch it. What should it do?`;
+    const liveness = resumeRunningLivenessRow(i.msSinceLastActivity);
+    return liveness === null ? head : `${head}\n${liveness}`;
+}
+/**
+ * 选项集(同一张卡两个入口,选项集**按入口分形**)。
+ *
+ * 🔴 **顺序即默认焦点**:卡的渲染面 `focusedIndex` 初值恒 0,而 wire 的 `QuestionFrame` 里
+ *    **没有**任何「默认焦点」位可传。所以「默认焦点 = ③ 后台留着」在结构上只有一个落法:把 ③ 排在
+ *    options[0]。谁哪天为了「读起来顺」把 ①②③ 按序号排回去,默认焦点就漂到了 `Attach and watch`
+ *    —— 一个手滑回车就把一条后台 run 接管到前台。常驻门逐位反钉这个顺序。
+ */
+export function resumeRunningOptions(i) {
+    const options = [
+        {
+            // 🔴 默认焦点 —— 三条路里唯一零副作用的一条,所以它是手滑回车的落点。
+            // 🔴 措辞:这一项**不许**承诺「它会留在某个任务面板里」—— 这张卡的前提恰恰是「那条 run 活得
+            //    比上一个客户端进程久」,新进程里没有任何腿会为它建行(③ 的处置本身也是显式零动作)。
+            //    默认焦点上的一句假 affordance 是最坏的一格:手滑回车的人拿到一条既看不见、也停不掉、
+            //    还占着会话锁的 run。换成两句**可证的**真话:本屏不会列出它;它还占着会话,所以下一条
+            //    消息会再撞上它(那时 409 三选卡会带着 steer/cancel 两条真出路出现)。
+            label: RESUME_CHOICE_BACKGROUND_LABEL,
+            description: 'Leaves the run alone. It keeps executing on the engine, but this screen will not show it and it will not be listed here — your next message runs into it again, and sema asks you then.',
+        },
+    ];
+    if (i.canAttach) {
+        options.push({
+            label: RESUME_CHOICE_ATTACH_LABEL,
+            // 🔴 第二句是**知情同意**那一半(见 {@link resumeAttachReplayDisclosure}):resume 入口没有
+            //    事件锚可用,durable 尾只能从这条 run 的第一帧读起,所以崩溃前已经落盘并被 resume 还原到
+            //    屏上的那一段会再出现一次。用户按下之前就得看见这句 —— 一个会做出用户没预料到的事的
+            //    选项,和一个按了没用的选项同样是假 affordance。
+            description: 'Follows that run from here: sema replays it from the engine ledger and keeps streaming it into this conversation. ' +
+                'Anything from that turn already shown above will appear a second time — sema has no resume marker for it.',
+        });
+    }
+    if (i.canCancel) {
+        options.push({
+            label: RESUME_CHOICE_CANCEL_LABEL,
+            description: 'Stops that run on the engine (whatever it has been doing is discarded) and frees this session for a new turn.',
+        });
+    }
+    return options;
+}
+/**
+ * 答案 → 决定。🔴 只认**逐字命中**的标签;空答(overlay 的 Esc/dismiss 形)、多选、认不出的
+ * 自由文本一律回落 ③ —— 破坏性动作只认显式选择(与 409 三选卡同律)。
+ */
+export function resumeChoiceFromLabels(selected) {
+    if (!Array.isArray(selected) || selected.length !== 1)
+        return 'background';
+    const label = selected[0];
+    if (label === RESUME_CHOICE_ATTACH_LABEL)
+        return 'attach';
+    if (label === RESUME_CHOICE_CANCEL_LABEL)
+        return 'cancel';
+    return 'background';
+}
+// ── §3.2b 无 UI 臂 ───────────────────────────────────────────────────────────────────────────
+/**
+ * headless 车道撞 resume-running 的**专码**退出码。
+ *
+ * 为什么非 0:这一趟 resume **没有**把会话交到一个可用状态 —— 那条 run 还占着会话,脚本接下来
+ * 提交什么都会撞 409。静默 0 = 谎报成功。
+ * 为什么是 75:sysexits.h 的 `EX_TEMPFAIL`(「暂时性失败,请稍后重试」)语义正对 —— run 跑完
+ * 或被取消之后同一条命令就能过;与 cli 既用的 0/1/2/129/143 零撞(脚本消费者据此可以把「会话被
+ * 在飞 run 占住」与「真失败(1)」「用法错(2)」分臂)。
+ */
+export const RESUME_RUNNING_NO_UI_EXIT_CODE = 75;
+/** 机读指路的行首标识 —— 脚本按它 grep;UI 改版不许动它。 */
+export const RESUME_RUNNING_GUIDANCE_TAG = 'sema: resume-running:';
+/**
+ * §3.2b 的**机读三选指路**。三条路各给真实命令或 API 路径,一条都不许省 ——
+ * 少写一条 = 那条路在这个车道上被客户端单方面关掉了。
+ *
+ * 🔴 `attach=` 那一行只有在**真知道 session id** 时才给具体命令:不知道还硬拼一条
+ * `sema --resume <sessionId>` 字面量,就是印一条按了没用的命令(假 affordance 的文本形)。
+ */
+export function resumeRunningNoUiGuidance(i) {
+    const sid = typeof i.sessionId === 'string' && i.sessionId.length > 0 ? i.sessionId : null;
+    const attach = sid === null ? 'sema --resume (pick this session from the list)' : `sema --resume ${sid}`;
+    const T = RESUME_RUNNING_GUIDANCE_TAG;
+    return [
+        `${T} run ${i.taskId} from an earlier turn is still executing on the engine, and this lane has no card to ask you on. sema did NOT cancel it and did NOT attach to it.`,
+        `${T} attach=${attach}`,
+        `${T} cancel=POST /v1/runs/${i.taskId}/cancel`,
+        // 🔴 这条车道连 REPL 都不挂载,更没有任何本地面板可看。给的是引擎侧真读面。
+        `${T} background=do nothing — run ${i.taskId} keeps executing on the engine; this client does not list it (read it with GET /v1/runs/${i.taskId})`,
+    ].join('\n');
+}
+/**
+ * ① 接管之前的**显式披露**。
+ *
+ * resume 入口没有 `lastEventId` 可用(端今天不持久化引擎事件锚),所以 durable 尾从这条 run 的
+ * 第一帧读起 —— 崩溃前已落盘、已被 resume 还原到屏上的那一段会再渲一遍。续听腿那道「无锚 × 已上屏
+ * ⇒ 不许从头续读」的门在这一格判不出来(它数的是**本条流**吐过几帧,resume 入口恒 0),所以不能
+ * 拿它当安全证明。处置 = 说在前面:静默复读会让用户以为模型把同一段活干了两遍。
+ *
+ * 🔴 **账目面同源**:同一次重放也会把这条 run 已经执行过的每一个 `turn_end` 再喂一次成本累计器。
+ *    客户端这一端证明不了哪一枚已经在恢复出来的总额里(那需要一本按 turn 落盘的账 —— 与缺席的
+ *    事件锚是同一件移交残件),所以接管腿声明**不计账**。既然不计,就必须在**同一行**说清楚:
+ *    只披露视觉复读、不披露账目缺口,用户拿成本面跟引擎账本对不上时只会怀疑客户端算错了。
+ */
+export function resumeAttachReplayDisclosure(taskId) {
+    return (`sema: attaching to run ${taskId} — sema is replaying it from the engine's ledger, so anything from that ` +
+        `turn already shown above will appear again below. There is no resume marker for a run that outlived its shell. ` +
+        `The replayed turns are not billed into this session's cost again either — the engine's own record ` +
+        `(GET /v1/runs/${taskId}) is the authority on what that run really spent.`);
+}
+/** ② 打完 cancel 但引擎没确认落地时的如实一行(绝不谎报「已停止」)。 */
+export function resumeRunningCancelUnconfirmedRow(taskId) {
+    return (`sema: the cancel for run ${taskId} did not come back confirmed, so that run may still be executing. ` +
+        `This screen does not list it — read its real state on the engine (GET /v1/runs/${taskId}) before ` +
+        `assuming this session is free.`);
+}

package/dist/hitl/toolApprovalWire.d.ts

@@ -69,10 +69,13 @@
  *    规则逐字节相同、更不是它的 id;下游「删除/撤销规则」面拿它当身份用 = 删错或删不掉。
  * ② **deny 归因通道**({@link ApprovalCardDenyDecision.reason}):两腿不同形 ——
  *    durable `/decide` **有** reason 位 ⇒ 原文上 wire(包内按 server 4096 上限截断);
- *    live 帧腿 `/v1/tool-approvals/:id/respond` 是三词闭集、**无** reason 位 ⇒ 只 debug 留痕、不发、
- *    不自造侧信道。⏳ **记账:respond 端点的 reason 位候 server**(server 辖区,到货后本包侧
- *    只需在 opts 上加一位,窄化器 `denyReasonForWire` 已在)。
- *    🔴 方向纪律:reason 只做归因,绝不参与裁决;缺席 ⇒ 现状字节不变。
+ *    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';
@@ -139,8 +142,14 @@ export interface ApprovalCardDenyDecision {
      * 这次决断仍是 deny(两条腿上的 `decision` 位逐字节不动)。
      * 🔴 **两腿不同形**(见 {@link surfaceFsApprovalAndDecide} / {@link surfaceToolApprovalFrameAndRespond}):
      *   · durable park 腿(`/decide`)wire **有** reason 位 ⇒ 原文上 wire(包内按 server 上限截断);
-     *   · live 帧腿(`/v1/tool-approvals/:id/respond`)wire 是三词闭集、**无** reason 位 ⇒ 只留痕不发,
-     *     绝不自造侧信道(候 server 给 respond 补位)。
+     *   · live 帧腿(`/v1/tool-approvals/:id/respond`)的 `decision` 仍是三词闭集,归因走**另一个键
+     *     `note`**(与 durable `AskDecisionBody.note` 同词同源同一列 `decision_note`)—— 本位的原文经
+     *     两道门后落到 `RespondToolApprovalOpts.note` 上 wire:能力位
+     *     `approvalDecisionNoteCapable === true`,且长度不超 `MAX_RESPOND_NOTE_CHARS`;任一不满足则
+     *     只留痕不发(绝不自造侧信道)。发了还要看 ack 的 `noteRecorded` 才算落行。
+     *     ⚠️ 本段 0.28.0 原文写的是「wire 无 reason 位、只留痕不发,候 server 补位」—— server 7.15.0
+     *     已到货、0.29.0 #229 已兑现,那句话从此不成立(2026-08-13 类型/wire 超集台账普查时发现该
+     *     JSDoc 已陈旧;实现坐标见 {@link surfaceToolApprovalFrameAndRespond} 里的 note 两道门)。
      * 与 `{kind:'failed'}` 的 `reason` **不同义**:那一位是「卡面本身不可用」的诊断,不是人的拒因,
      * 两者绝不互相顶替。
      */
@@ -158,7 +167,17 @@ export interface ApprovalCardRequest {
     args: object;
     callKey: string;
     signal?: AbortSignal;
-    /** 后台子代 ask 的归属徽章(卡头 `· @name`,CC swarm workerBadge 原生位;宿主 ask 恒缺席)。 */
+    /**
+     * 后台子代 ask 的归属徽章(卡头 `· @name`;宿主 ask 恒缺席)。
+     * ⚠️ **出身声明订正**(0.30.0 发包扫描,2026-08-14):本段 0.28.0 原文写的是「CC swarm workerBadge
+     * **原生位**」。类型/wire 超集台账普查逐份直证的结果与那句话相反 —— CC 语料九份
+     * (cli220/221/222/223 + pretty218/219/220/221/223)`workerBadge` **全 0 命中**(正控:同一把探针在
+     * 同目录对 `permissionMode` 有命中,证明它会说话),`@sema-agent/agent-types` 0.2.0 镜像的 TS AST
+     * 声明名集合(1651 个名字)里也没有这个名字。⇒ 这一位按现有证据是 **sema 自铸**,不是 CC 原生位;
+     * 终判(让位/改名/登记为超集)候台账 `docs/type-superset.json` 的 `_covenant`「未建工作」条清账。
+     * 🔴 三端读到的 `.d.ts` 注释随 dist 出包,所以订正必须落在这里 —— 只在不进 tarball 的台账里留话,
+     *    消费端读到的仍是那句错误出身断言。
+     */
     workerBadge?: {
         name: string;
         color: string;
@@ -167,10 +186,19 @@ export interface ApprovalCardRequest {
      *  不可注入 args 的提示走这里([1543]③ 记账的 note 位,2026-07-23 落位)。 */
     wireNote?: string;
     /**
-     * 治理强制位(server ≥7.5.0,2026-08-08 补透传)——原样来自
-     * {@link ToolApprovalFrame.governanceForced}。**缺席 ≠ false**:只在为真时在场,缺席 = 无治理来源
-     * 的证据。壳应据此把门呈成**表态掀不掉**(而不是引导用户去改 `permissionMode`);呈现形是壳半场,
-     * 本包只保证这一位到得了卡口 —— 此前它在帧类型上就不存在,于是宿主无论怎么写都读不到。
+     * 治理强制位(server ≥7.5.0,2026-08-08 补透传)。**缺席 ≠ false**:只在为真时在场,缺席 = 无治理
+     * 来源的证据。壳应据此把门呈成**表态掀不掉**(而不是引导用户去改 `permissionMode`);呈现形是壳
+     * 半场,本包只保证这一位到得了卡口 —— 此前它在帧类型上就不存在,于是宿主无论怎么写都读不到。
+     *
+     * 🔴 **本位是双源合流**(0.30.0 发包扫描订正,2026-08-14;本段原文只写「原样来自
+     * {@link ToolApprovalFrame.governanceForced}」,而 [C170] 那一批起 durable 腿也往这一位灌):
+     *   · **活卡帧腿**:`ToolApprovalFrame.governanceForced`(进程内治理标记表);
+     *   · **durable park 行腿**:`PendingCheckpoint.governanceForced`(`surfaceFsApprovalAndDecide` 的
+     *     行 → 卡重铸处 stamp,条件同样只认 `=== true`)。
+     * ⚠️ 上游对这两位的关系有逐字声明(sdk 6.17.2 `PendingCheckpoint` JSDoc):判据属主是
+     * `governanceOriginOf`(行上取证格 ∧ 部署姿态合取),与活卡帧那位**语义同族、判据不同源**,
+     * 「同一只 ask 两条腿的在场性可以不一致」。⇒ 宿主**不许**把本位读成「活卡帧的治理标记」:
+     * 帧腿缺席不等于 durable 腿缺席,反之亦然;要区分来源就看你拿到的是哪条腿的卡。
      */
     governanceForced?: true;
     /** 委派出处链(core 5.9.0 W1)——原样来自 {@link ToolApprovalFrame.delegation};只读展示增强,
@@ -183,6 +211,17 @@ export interface ApprovalCardRequest {
      * 出身裁剪(MANDATED ask 不提供本档)候 core 5.25.0 出身键 wire 过境,见 #144/[3438]/[3442]。
      */
     ruleSuggestions?: RuleSuggestion[];
+    /**
+     * 持久规则候选的**只读**对偶([C170] 答问②半场,0.29.0)——原样来自 durable 队列行
+     * `PendingCheckpoint.ruleSuggestions`(server 7.16.0 [3684]② 补齐的供给)的合形项。
+     * 🔴 与 {@link ruleSuggestions} **刻意分键不合流**:那一位的契约是「卡渲可选中的『不再询问』档
+     * → 决断带 {@link ApprovalCardAllowDecision.persistRule} 回兑」,兑付口=同副本活卡腿
+     * `respond.persistRule`;而 durable 腿的 `/decide` 体**无规则位**(SDK 6.17.2 PendingCheckpoint
+     * JSDoc 逐字:display/triage-only)——把行上候选落进那一位,就是一个按下去规则不落地的假
+     * affordance。卡口对本键只许**只读渲染**(chips/说明行),绝不渲成可选中项、决断绝不因它带
+     * `persistRule`。缺席 = 无候选/老行/坏形(三者同形,不猜);既有卡口不读本键 ⇒ 卡形字节不变。
+     */
+    ruleSuggestionsReadOnly?: RuleSuggestion[];
     /**
      * 被越级的持久 allow 规则**原文**(#144,原样来自 {@link ToolApprovalFrame.persistedRuleShadowed}
      * 的合形值)——壳据此渲「你的规则仍在,只是这次调用被要求逐次确认」;缺席 = 卡形与 0.27.0
@@ -305,8 +344,9 @@ export interface ToolApprovalFrame {
      * {@link ApprovalCardRequest.persistedRuleShadowed} 的同名警示(下游删除规则面不许拿它当规则身份)。
      *
      * 耐久路(park 行)的对偶是 `gate.riskDescriptor.shadowedRule`(server 对 riskDescriptor 整体透传);
-     * 本包的 durable 腿今天不 stamp 任何展示键(见 {@link surfaceFsApprovalAndDecide} 的卡入参),
-     * 那一路的消费是独立的一件,不在本键的施工面内。
+     * durable 腿自 0.29.0 起 stamp 行上的 governanceForced/ruleSuggestionsReadOnly 两个展示键
+     * ([C170] 答问②半场,见 {@link surfaceFsApprovalAndDecide} 的卡入参),但 shadowedRule 的
+     * 耐久对偶仍未消费——那一路是独立的一件,不在本键的施工面内。
      */
     persistedRuleShadowed?: string;
 }
@@ -350,6 +390,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>;
 /**
@@ -380,13 +425,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

@@ -69,16 +69,20 @@
  *    规则逐字节相同、更不是它的 id;下游「删除/撤销规则」面拿它当身份用 = 删错或删不掉。
  * ② **deny 归因通道**({@link ApprovalCardDenyDecision.reason}):两腿不同形 ——
  *    durable `/decide` **有** reason 位 ⇒ 原文上 wire(包内按 server 4096 上限截断);
- *    live 帧腿 `/v1/tool-approvals/:id/respond` 是三词闭集、**无** reason 位 ⇒ 只 debug 留痕、不发、
- *    不自造侧信道。⏳ **记账:respond 端点的 reason 位候 server**(server 辖区,到货后本包侧
- *    只需在 opts 上加一位,窄化器 `denyReasonForWire` 已在)。
- *    🔴 方向纪律:reason 只做归因,绝不参与裁决;缺席 ⇒ 现状字节不变。
+ *    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 { 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) {
@@ -242,12 +246,22 @@ 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);
+    // [C170] 答问②半场(0.29.0):durable 富行的两个展示键随卡透传 —— 修前这里是四位闭集,
+    // server 7.16.0 起行上就有的 ruleSuggestions/governanceForced 在「行 → 卡」重铸处整段丢失
+    // (feed 行原样透传零丢失,丢的只有这处)。governanceForced 条件 stamp 只认 === true(缺席
+    // 纪律与活卡腿同款:缺席=无治理来源证据,绝不写 false);候选走 readRuleSuggestions 同一把
+    // 合形窄化,落**只读键**(红线见 ApprovalCardRequest.ruleSuggestionsReadOnly 顶注:/decide
+    // 无规则位,落可兑付位=假 affordance)。
+    const ruleSuggestionsReadOnly = readRuleSuggestions(pending.ruleSuggestions);
     const card = await surfaceApprovalCard({
         toolName,
         args,
         callKey,
         ...(signal ? { signal } : {}),
+        ...(pending.governanceForced === true ? { governanceForced: true } : {}),
+        ...(ruleSuggestionsReadOnly !== undefined ? { ruleSuggestionsReadOnly } : {}),
     });
     switch (card.kind) {
         case 'failed':
@@ -408,6 +422,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 === 帧名)。
@@ -497,7 +514,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
@@ -527,7 +547,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 } : {}),
@@ -554,24 +575,31 @@ export async function surfaceToolApprovalFrameAndRespond(frame, respond, streamA
     if (card.kind === 'failed') {
         hostLog('debug', `liveToolApprovalWire: approval card unavailable (${card.reason}) — fail-closed deny for ${frame.approvalId}`);
     }
-    // #144 半场记账(0.28.0):respond 端点(POST /v1/tool-approvals/:id/respond)的体是**三词闭集**
-    // (`allow|allow_session|deny`,server `parseToolApprovalResponse`)—— wire 上**没有 reason 位**。
-    // 所以这条腿上的拒因只留痕、**不发**:塞进 `updatedInput` 会把归因喂回工具入参面,另开一条消息
-    // /header 是自造侧信道,两者都比「暂时没有这个位」更坏。durable `/decide` 腿有位、已透传(上面
-    // 那条腿)。⏳ 记账:respond 端点的 reason 位候 server(本包侧零改动即可消费,窄化器已在)。
-    // 🔴 留痕只写**元数据**(在场 + 长度),绝不把拒因正文拷进日志(对抗复审命中):
-    //    正文是自由文本(人打的拒绝说明 / 规则原文),可能带路径、命令、被拒内容的片段,而 `hostLog`
-    //    的落点是宿主任意注入的 sink(文件/远端都可能)—— 把它原样拷过去既是外溢面,也给了
-    //    换行/控制字符注入日志行的口子。**而且正文本来就在宿主手里**:这条腿上的 reason 正是宿主
-    //    自己的卡口返回的,回喂给它自己的 sink 零诊断增量。要看正文的场景是 durable 腿,那一路它
-    //    真的上了 wire。
-    // 0.28.0 发版扫描 F4:本腿留痕**不借** denyReasonForWire —— 那个窄化器的超限日志讲的是
-    // 「413 会丢掉决断」,对 respond 端点是假话(它根本不收 reason,无 413 可言);且截断后 len
-    // 恒 4096,掩盖真实丢弃量。本地判空白+报**原始**长度,只说这条腿真实发生的事:归因整条没发。
+    // #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() !== '') {
-        hostLog('debug', `liveToolApprovalWire: ${frame.approvalId} card supplied a deny reason (len=${card.reason.length}) but the respond ` +
-            'endpoint carries no reason slot (three-word closed set) — attribution not sent on this lane, no side channel invented ' +
-            '(content not logged: it is host-authored free text and the host already holds it)');
+        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。
@@ -592,6 +620,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 包装器复用了连接)如果照样被
@@ -619,6 +648,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,13 @@ 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/parkRowBirthWait.js';
+export * from './hitl/approvalDecisionNoteAudit.js';
+export * from './hitl/askParkRowRouting.js';
+export * from './hitl/resumeRunningCard.js';
 export * from './hitl/approvalsFeed.js';
 export * from './compensations.js';
 export * from './request/printNotification.js';
@@ -231,3 +239,4 @@ export * from './model/catalogLoader.js';
 export * from './model/providerAuth.js';
 export * from './websearch/searchProviderPresets.js';
 export * from './env/localeGeo.js';
+export type { PendingCheckpoint, RuleSuggestion } from '@sema-agent/sdk';

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,32 @@ 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';
+// ── #265(2026-08-14):C1-C5「决策卡死墙」病族的三端公共判定层上收(源形 = cli 五模块的判据半场;
+//    呈现/编排留端)。四件都是纯判定,零宿主端口:
+// · parkRowBirthWait:「待决行还没出生」这个第三态的有界可中断重查环 —— 把「行不在 pending 表」
+//   从单义的「已决」拆成 row/unborn/settled 三态,`settled` 必须由正面证据得出。
+// · approvalDecisionNoteAudit:回决备注(decisionNote/noteRecorded)三态读面 + 人话行,
+//   `unknown ⇒ 整行不渲`(缺席 ≠ false)。
+// · askParkRowRouting:ask park 重开链的四问(队列三态分类 / 行身份 / 问答臂 vs 工具门臂 /
+//   「行已消失」两义分臂)+ 行级单活闸工厂(一个待决项至多一张卡)。
+// · resumeRunningCard:resume 撞上在飞 run 的三选卡(默认焦点 = 零动作那一项 / 活性证据缺席整行
+//   不渲 / 无 UI 臂的机读三选指路与专码退出)。
+export * from './hitl/parkRowBirthWait.js';
+export * from './hitl/approvalDecisionNoteAudit.js';
+export * from './hitl/askParkRowRouting.js';
+export * from './hitl/resumeRunningCard.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)
  *

package/dist/liveQuestionStore.js

@@ -20,6 +20,19 @@ export function registerLocalQuestionResponder(id, fn) {
         localResponders.delete(id);
     };
 }
+/**
+ * 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 function unregisterLocalQuestionResponder(id) {
+    return localResponders.delete(id);
+}
 /**
  * Is a local responder for this synthetic questionId still bound?([2393] hitl-F3,2026-08-02)
  *