@sema-agent/client-core 0.72.12 → 0.72.14

package/dist/hitl/approvalsFeed.js

@@ -1,5 +1,6 @@
 import { hostLog } from '../host.js';
 import { unrefTimer } from '../unrefTimer.js';
+import { readLivePendingRows } from './livePendingAsk.js';
 /** [2393] hitl-F5:poll 回调体**连续**逃逸多少次之后判定「这条腿真挂了」并把 `mode` 打成 idle。
  *  取 5 是为了让「偶发一拍畸形 payload」不误判(单次逃逸下一拍就归零),同时不让一条永远抛的腿
  *  无限期地对着端的自检假装自己还活着。 */
@@ -9,13 +10,29 @@ const MAX_CONSECUTIVE_POLL_ESCAPES = 5;
  * 键里带 `boundInputHash`:同一条 pending 的绑定被服务端换掉(TOCTOU 场景)也算变化,
  * 否则端会拿着一个「id 没变但绑定变了」的行继续渲染。
  */
-function digestOf(rows) {
+function durableDigestOf(rows) {
     return rows
         .map(r => [r.sessionId ?? '', r.taskId ?? '', r.toolCallId ?? '', r.boundCallId ?? '', r.boundInputHash ?? '', r.toolName ?? '']
         .join('
'))
         .sort()
         .join('');
 }
+const LIVE_FIELD_SEP = String.fromCharCode(1);
+const LIVE_ROW_SEP = String.fromCharCode(2);
+const LIVE_SECTION_SEP = String.fromCharCode(3);
+/**
+ * 0.72.14:流内 ask 段进摘要 —— 此前只算 `pending`,悬挂 ask 出现 / 消失都不触发快照。
+ * 「未报」与「报了且为空」是两个不同的事实(前者读不出计数),摘要上也分开。
+ */
+function digestOf(rows, live) {
+    const liveDigest = live === undefined
+        ? 'absent'
+        : live
+            .map(r => [r.approvalId, r.toolName, String(r.expiresAtMs), r.sessionId ?? '', r.originTaskId ?? ''].join(LIVE_FIELD_SEP))
+            .sort()
+            .join(LIVE_ROW_SEP);
+    return `${durableDigestOf(rows)}${LIVE_SECTION_SEP}${liveDigest}`;
+}
 /**
  * 起一条 pending-approvals feed。**幂等性归调用方**:一个 client 起一条就够了,起两条 =
  * 两倍取件(不是错误,但没意义)。
@@ -51,7 +68,7 @@ export function startApprovalsFeed(client, onSnapshot, opts) {
     let takeSeq = 0;
     let lastObservedSeq = 0;
     const stats = {
-        pushEvents: 0, heartbeats: 0, polls: 0, listErrors: 0, streamFailures: 0, snapshots: 0,
+        pushEvents: 0, heartbeats: 0, polls: 0, listErrors: 0, streamFailures: 0, snapshots: 0, reconciles: 0,
     };
     /** 域词表-14 收编:「怎么调 unref」的单一实现见 unrefTimer.ts,本函数只是就地起个短名。 */
     function arm(t) {
@@ -90,8 +107,23 @@ export function startApprovalsFeed(client, onSnapshot, opts) {
             return;
         const seq = ++takeSeq;
         let rows;
+        let live;
         try {
-            rows = (await client.approvals.list({ signal: ac.signal })).pending;
+            const body = await client.approvals.list({ signal: ac.signal });
+            rows = body.pending;
+            // 0.72.14:`livePending` 段按结构窄读。键在场却读不懂 ⇒ **整次取件不提交**(保留上一张快照):
+            // 把「读不懂」提交成「未报 / 为空」会让端撤掉一张还在等人的卡。
+            const reading = readLivePendingRows(body);
+            if (reading.kind === 'malformed') {
+                stats.listErrors++;
+                hostLog('debug', `approvalsFeed: list() body has an unreadable livePending section (${via} leg) — snapshot not committed`);
+                return;
+            }
+            if (reading.kind === 'present') {
+                live = reading.rows;
+                if (reading.dropped > 0)
+                    hostLog('debug', `approvalsFeed: dropped ${reading.dropped} malformed livePending row(s)`);
+            }
         }
         catch (e) {
             stats.listErrors++;
@@ -100,7 +132,7 @@ export function startApprovalsFeed(client, onSnapshot, opts) {
         }
         if (stopped)
             return;
-        const d = digestOf(rows);
+        const d = digestOf(rows, live);
         // 🔴 [F4957-1 二审 finding②] 代际闸必须排在**提交之前**:下面四行(lastDigest / revision /
         // last / onSnapshot)一落,视图就已经被改了 —— 守卫排在 take() 之外只挡得住计数与续排,挡不住
         // 回滚。乱序是真的会发生的:旧 poll 在途 → push 重连并发布新快照 → 旧 poll 才带着**更老**的
@@ -122,7 +154,7 @@ export function startApprovalsFeed(client, onSnapshot, opts) {
             return; // 内容没变 ⇒ 不打扰订阅者
         lastDigest = d;
         revision++;
-        const snap = { pending: rows, mode: via, revision };
+        const snap = { pending: rows, ...(live !== undefined ? { livePending: live } : {}), mode: via, revision };
         last = snap;
         stats.snapshots++;
         try {
@@ -205,6 +237,54 @@ export function startApprovalsFeed(client, onSnapshot, opts) {
             });
         }, pollIntervalMs));
     }
+    /** 0.72.14 对账节拍(见 {@link ApprovalsFeedReconcileOptions})。独立于两条腿:不读 `mode`、不动 F5 计数、不计 `polls`。 */
+    const reconcileBaseMs = Math.max(1, opts?.reconcile?.intervalMs ?? 5000);
+    const reconcileMaxMs = Math.max(reconcileBaseMs, opts?.reconcile?.maxIntervalMs ?? 30_000);
+    let reconcileTimer;
+    let reconcileDelayMs = reconcileBaseMs;
+    function reconcileGateOpen() {
+        let verdict;
+        try {
+            verdict = opts?.reconcile?.shouldReconcile();
+        }
+        catch (e) {
+            hostLog('debug', `approvalsFeed: shouldReconcile() threw — treating this tick as "reconcile" (fail-safe): ${String(e)}`);
+            return true;
+        }
+        if (typeof verdict !== 'boolean') {
+            hostLog('debug', `approvalsFeed: shouldReconcile() returned ${typeof verdict} (not boolean) — treating this tick as "reconcile"`);
+            return true;
+        }
+        return verdict;
+    }
+    function scheduleReconcile() {
+        if (opts?.reconcile === undefined)
+            return;
+        if (stopped || ac.signal.aborted)
+            return;
+        if (reconcileTimer !== undefined)
+            return;
+        reconcileTimer = arm(setTimeout(() => {
+            reconcileTimer = undefined;
+            if (stopped || ac.signal.aborted)
+                return;
+            if (!reconcileGateOpen()) {
+                reconcileDelayMs = reconcileBaseMs; // 闸关 ⇒ 下次转开时从基础间隔起
+                scheduleReconcile();
+                return;
+            }
+            void (async () => {
+                const before = revision;
+                stats.reconciles++;
+                await take('poll');
+                reconcileDelayMs = revision !== before ? reconcileBaseMs : Math.min(reconcileDelayMs * 2, reconcileMaxMs);
+            })()
+                .catch(e => {
+                hostLog('debug', `approvalsFeed: reconcile tick threw unexpectedly (take() should have self-caught): ${String(e)}`);
+            })
+                .then(() => scheduleReconcile());
+        }, reconcileDelayMs));
+    }
     /**
      * 与 schedulePoll 对称(域词表-18):**幂等卫兵**(retryTimer 已在飞则不再排一个)+ **回调首行
      * 自清**(否则 retryTimer 触发后仍持有已死句柄,degradeToPoll 若被再次调用会直接覆盖它而不清掉
@@ -312,6 +392,7 @@ export function startApprovalsFeed(client, onSnapshot, opts) {
             void runStream();
         else
             degradeToPoll('SDK has no approvals.stream (old SDK / mock)', false);
+        scheduleReconcile();
     });
     return {
         stop() {
@@ -323,6 +404,8 @@ export function startApprovalsFeed(client, onSnapshot, opts) {
                 clearTimeout(pollTimer);
             if (retryTimer !== undefined)
                 clearTimeout(retryTimer);
+            if (reconcileTimer !== undefined)
+                clearTimeout(reconcileTimer);
             opts?.signal?.removeEventListener('abort', onOuterAbort);
             ac.abort();
         },

package/dist/hitl/crashConverged.d.ts

@@ -88,7 +88,8 @@ export interface CrashConvergedRow {
  * `GET /v1/approvals` 的**信封**形。`pending` 是老形的全部;后两键 additive
  * (server 按 deps 在场才发)⇒ **老形 `{ pending }` 仍然可赋值到本型**,现有消费点一个字节不用改。
  *
- * 🔴 `livePending` 在本包是**不透明载体**,留 `unknown[]` 有两条**互相独立**的理由:
+ * 🔴 `livePending` 在**本型上**留 `unknown[]`(0.72.14 起它有了包内读器 `readLivePendingRows`,按结构窄读;
+ *    下面 ① 说的「零消费点」自那版起不再成立,② 仍然成立,也是读器按结构读而不引类型的原因):
  *    ① 本包对它零消费点,在这里手抄一份结构 = 手抄一份会漂的上游形(与 `ToolApprovalFrame.probeCause`
  *       同一条理由);
  *    ② **SDK barrel 根本没把 `LivePendingRow` 导出**(实证:`@sema-agent/sdk` 7.4.0 的 `dist/index.d.ts`

package/dist/hitl/hitlBridge.d.ts

@@ -138,7 +138,18 @@ export interface PlanReviewOutcome {
     decision: 'approve' | 'edit' | 'reject';
     editedPlan?: string;
     reason?: string;
+    /**
+     * 0.72.13 CC-46(engine ≥7.86.0;契约 §4c):批准之后这条任务继续用的 permission mode。**只配 `approve`**;
+     * 缺席 = 键不落(老壳姿势,引擎按 `default`)。🔴 适用面读不到 wire:只有**提交这条任务的那一方**知道它是不是
+     * `permissionMode:"plan"` 只读起步的 —— 不是只读起步的任务送这一位会吃 400 `request.field_conflict`,那次批准整个送不出去。
+     */
+    permissionModeAfter?: PlanReviewModeAfter;
 }
+/** 契约 §4c `permissionModeAfter` 的闭集两词(`acceptEdits` = 工作目录内的写不再逐次征询;`default` = 每次写照常征询)。 */
+export declare const PLAN_REVIEW_MODE_AFTER_WORDS: readonly ["default", "acceptEdits"];
+export type PlanReviewModeAfter = (typeof PLAN_REVIEW_MODE_AFTER_WORDS)[number];
+/** 这个值是不是闭集里的词(词表外 —— 含 `plan` / `bypassPermissions` / `auto` —— 引擎 400:一次批准不许顺带关掉征询面)。 */
+export declare function isPlanReviewModeAfter(v: string | undefined): v is PlanReviewModeAfter;
 /**
  * {@link HitlSafetyError.code} 的闭集(0.60.0 抽名,**成员一个没动**)。
  *
@@ -147,7 +158,7 @@ export interface PlanReviewOutcome {
  * ——抄一份就是给自己立第二个判官(B-025 的病形)。加员仍必须**同批**改齐
  * `parkResolver.GATE_FAILURE_CODES` 白名单(见下方原注)。
  */
-export type HitlSafetyCode = 'binding_mismatch' | 'no_pending' | 'wrong_gate' | 'bad_plan_edit' | 'empty_answer';
+export type HitlSafetyCode = 'binding_mismatch' | 'no_pending' | 'wrong_gate' | 'bad_plan_edit' | 'bad_plan_mode' | 'empty_answer';
 /**
  * 一次决断链失败**停在哪一段**(0.60.0;异源对抗复审 [medium] 采纳,B-037 候包件 ② 的完整兑现)。
  *

package/dist/hitl/hitlBridge.js

@@ -35,6 +35,12 @@ export function denyReasonForWire(reason, tag) {
         `(server caps approval reason at ${MAX_DENY_REASON_CHARS}; over-cap is a 413 reason_too_large that would drop the DECISION, not just the reason)`);
     return cut;
 }
+/** 契约 §4c `permissionModeAfter` 的闭集两词(`acceptEdits` = 工作目录内的写不再逐次征询;`default` = 每次写照常征询)。 */
+export const PLAN_REVIEW_MODE_AFTER_WORDS = Object.freeze(['default', 'acceptEdits']);
+/** 这个值是不是闭集里的词(词表外 —— 含 `plan` / `bypassPermissions` / `auto` —— 引擎 400:一次批准不许顺带关掉征询面)。 */
+export function isPlanReviewModeAfter(v) {
+    return v !== undefined && PLAN_REVIEW_MODE_AFTER_WORDS.includes(v);
+}
 /** A safety stop: a contract law was about to be violated (e.g. a binding mismatch, a wrong-gate route).
  *  The caller MUST re-present to the human or surface the error — NEVER silently retry or auto-decide
  *  (contract/04 §9.1 fail-closed law). */
@@ -603,7 +609,21 @@ export class HitlBridge {
         else if (outcome.editedPlan !== undefined) {
             throw new HitlSafetyError(`plan-review "${outcome.decision}" must NOT carry editedPlan`, 'bad_plan_edit');
         }
+        // 0.72.13 CC-46:permissionModeAfter invariant(契约 §4c)—— 只配 approve、闭集两词;坏形本地拦,一个字节都不出门
+        // (server 会 400 field_conflict / field_invalid,而那次决断就整个丢了)。拒文不回显调用方给的值。
+        const modeAfter = outcome.permissionModeAfter;
+        if (modeAfter !== undefined) {
+            if (outcome.decision !== 'approve') {
+                throw new HitlSafetyError(`plan-review "${outcome.decision}" must NOT carry permissionModeAfter (it only applies to an approval)`, 'bad_plan_mode');
+            }
+            if (!isPlanReviewModeAfter(modeAfter)) {
+                throw new HitlSafetyError('plan-review permissionModeAfter must be "default" or "acceptEdits"', 'bad_plan_mode');
+            }
+        }
+        // sdk 9.6.0 的 PlanReviewRequest 尚未声明 permissionModeAfter ⇒ 交集型加一可选位(不断言、不 any);缺席 = 键不落。
         const req = { decision: outcome.decision };
+        if (modeAfter !== undefined && isPlanReviewModeAfter(modeAfter))
+            req.permissionModeAfter = modeAfter;
         // eopt:上面的 invariant 检查已经保证 decision==='edit' ⇒ editedPlan 非空,但那道保证隔着一个
         // 已经关闭的 if 块,TS 不跨块记账——这里重新直接判一次 undefined,narrowing 与赋值同一表达式内完成
         // (PlanReviewRequest 是 SDK 外部 wire 型,不能改;诚实缺席 = 键不落,不传 `editedPlan: undefined`)。

package/dist/hitl/hitlHostSurface.d.ts

@@ -114,6 +114,10 @@ export declare function surfaceRememberNotApplied(): void;
  * 已记进 docs/refactor/README.md 的宿主/上游工单表,本层不做旁路补偿(只做如实告知)。
  */
 export declare function surfaceEditNotForwarded(): void;
+/** 0.72.14:入参不可得的卡上收到了「编辑后批准」——什么都没发,ask 仍挂着(文案测试锁字面)。 */
+export declare const EDIT_REFUSED_ON_BLIND_ASK_WARN_TEXT: string;
+/** 见 {@link EDIT_REFUSED_ON_BLIND_ASK_WARN_TEXT};无宿主口 ⇒ 静默(与同族通知同语义)。 */
+export declare function surfaceEditRefusedOnBlindAsk(): void;
 /**
  * 文案(测试锁字面)。措辞刻意描述**后果**,并且**只说证得出的话**(异源对抗复审四轮 [medium] 修):
  *  · 不写「这台引擎不支持」——能力位缺席有三种同形成因(宿主没接这个字段 / 探测还没回来 / 探测失败),

package/dist/hitl/hitlHostSurface.js

@@ -163,6 +163,14 @@ export function surfaceRememberNotApplied() {
 export function surfaceEditNotForwarded() {
     surfaceSelfClearingWarn(EDIT_NOT_FORWARDED_KEY, EDIT_NOT_FORWARDED_WARN_TEXT, EDIT_NOT_FORWARDED_TIMEOUT_MS);
 }
+/** 0.72.14:入参不可得的卡上收到了「编辑后批准」——什么都没发,ask 仍挂着(文案测试锁字面)。 */
+export const EDIT_REFUSED_ON_BLIND_ASK_WARN_TEXT = 'That approval was NOT sent: this request does not expose its tool arguments here, so an edited approval cannot be applied. ' +
+    'The request is still waiting — approve or deny it as it is.';
+const EDIT_REFUSED_ON_BLIND_ASK_KEY = 'hitl-edit-refused-blind-ask';
+/** 见 {@link EDIT_REFUSED_ON_BLIND_ASK_WARN_TEXT};无宿主口 ⇒ 静默(与同族通知同语义)。 */
+export function surfaceEditRefusedOnBlindAsk() {
+    surfaceSelfClearingWarn(EDIT_REFUSED_ON_BLIND_ASK_KEY, EDIT_REFUSED_ON_BLIND_ASK_WARN_TEXT, EDIT_NOT_FORWARDED_TIMEOUT_MS);
+}
 /**
  * 文案(测试锁字面)。措辞刻意描述**后果**,并且**只说证得出的话**(异源对抗复审四轮 [medium] 修):
  *  · 不写「这台引擎不支持」——能力位缺席有三种同形成因(宿主没接这个字段 / 探测还没回来 / 探测失败),

package/dist/hitl/livePendingAsk.d.ts

@@ -0,0 +1,107 @@
+/**
+ * livePendingAsk — 「悬挂的流内 ask」的三端共用读面与决断口(0.72.14)。
+ *
+ * ── 这个模块补的是哪一个缺口 ────────────────────────────────────────────────────────────────
+ * 流内 ask 在铸造那一刻若没有活着的宿主流可投,引擎把它转成**悬挂**(窗约一小时,不补发、不重算),此后只在
+ * `GET /v1/approvals` 回体的第二顶层键 `livePending` 里可发现。后台 workflow 的子代恒落这一形:宿主 turn 先结束,
+ * 子代稍后才撞上审批门 ⇒ 用户面零帧零卡,代理静默卡到窗尽。本模块让端从 {@link startApprovalsFeed} 的快照里
+ * 读到这些行、出带子代身份的卡、并经**与流内帧腿同一条链**决断。
+ *
+ * ── 🔴 四条读法 ────────────────────────────────────────────────────────────────────────────
+ *  ① **键缺席 ≠ 没有悬挂 ask**:老引擎不发这个键 ⇒ `not_reported`;快照上键缺席,计数读 `null`(不知道),绝不铸 `[]` / `0`。
+ *  ② **数组名即路由判据**:`livePending` 行的决议口是 `POST /v1/tool-approvals/{approvalId}/respond`(流内审批那个口),
+ *     **不是** durable 行的 decide 口;两数组不混编。幂等键 = `approvalId`(与流内帧同一个 id)。
+ *  ③ **可选旗标 only-if-true**:`fromSubagent` / `governanceForced` / `requiresRealApproval` 缺席绝不编码成 `false`。
+ *  ④ **行上没有工具入参**(引擎刻意不在这个读面开第二道脱敏面)⇒ 卡必须明说「看不到入参」,不许渲一个空命令冒充全貌。
+ *
+ * sdk 的 barrel 没有导出这一行的类型 ⇒ 按**结构**窄读(与 `capabilities.executionLane` 同一姿势),多余成员不过境。
+ */
+import type { ApprovalsFeedSnapshot } from './approvalsFeed.js';
+import { type RespondToolApprovalFn, type ToolApprovalFrame, type ToolApprovalFrameLaneOpts, type ToolApprovalFrameOutcome } from './toolApprovalWire.js';
+/** 一条悬挂的流内 ask(窄读后的形;键集即全部)。 */
+export interface LivePendingAskView {
+    /** 与 respond 口收的同一个 id。 */
+    approvalId: string;
+    toolName: string;
+    /** 登记时刻(epoch ms)。 */
+    ts: number;
+    /** 窗死线(绝对 epoch ms;引擎铸定,本包不重算)。 */
+    expiresAtMs: number;
+    sessionId?: string;
+    requiresRealApproval?: true;
+    governanceForced?: true;
+    /** 出自委派子代。 */
+    fromSubagent?: true;
+    /** 子代 taskId(与 `fromSubagent` 同生同缺)。 */
+    originTaskId?: string;
+}
+/** `livePending` 段的三态读数。`malformed` = 键在场但读不懂(**不**折成 `not_reported`,也不折成空)。 */
+export type LivePendingReading = {
+    kind: 'not_reported';
+} | {
+    kind: 'malformed';
+} | {
+    kind: 'present';
+    rows: LivePendingAskView[];
+    dropped: number;
+};
+/** `GET /v1/approvals` 回体 → `livePending` 段读数。四必填位坏形的行丢弃并计数;同 `approvalId` 重复行留第一条。 */
+export declare function readLivePendingRows(body: unknown): LivePendingReading;
+/** 视图过滤:给了 `sessionId` ⇒ 只留该会话的行;行上没有 `sessionId` = 归不了属 ⇒ 不留(不替别的会话出卡)。 */
+export interface SuspendedAskFilter {
+    sessionId?: string;
+}
+/** 快照里**出自子代**的悬挂 ask(宿主自己的流内 ask 走流内帧腿,不在这里出卡)。未报 / 没有快照 ⇒ `[]`。 */
+export declare function suspendedSubagentAsks(snapshot: ApprovalsFeedSnapshot | null | undefined, filter?: SuspendedAskFilter): LivePendingAskView[];
+/** 「在等人决定」的计数。`null` = 不知道(没有快照 / 引擎没报这一段),**不是** 0。 */
+export interface ApprovalsAwaitingDecisionCount {
+    /** durable 停驻行数。 */
+    durable: number | null;
+    /** 流内 ask 行数(含宿主自己的与子代的)。 */
+    live: number | null;
+    /** 其中出自子代的行数。 */
+    suspendedSubagent: number | null;
+}
+export declare function countApprovalsAwaitingDecision(snapshot: ApprovalsFeedSnapshot | null | undefined, filter?: SuspendedAskFilter): ApprovalsAwaitingDecisionCount;
+/**
+ * 悬挂行 → 流内帧腿的输入。只带行上**真有**的位:窗三键不带(行上只有绝对死线,没有出帧时刻,凑不出可校偏的窗),
+ * `args` 不带(行上没有)。`sourceTaskId` = `originTaskId`(卡头子代身份徽章的来源)。
+ */
+export declare function livePendingRowToApprovalFrame(row: LivePendingAskView): ToolApprovalFrame;
+/**
+ * 出卡并决断一条悬挂 ask —— **与流内帧腿同一条链**({@link surfaceToolApprovalFrameAndRespond}):同一个卡口、
+ * 同一个身份键铸口(`approvalId`)、同一套回执 / 拒绝读法。差别只有一处:行上没有入参 ⇒ 卡上明说
+ * (`argsUnavailable`),且这张卡上收到「编辑后批准」时**整次不发**(结局 `editRefused`;没有原文可编,丢掉改写再批准 =
+ * 批准了人没看到的原始入参)。
+ */
+export declare function surfaceSuspendedAskAndRespond(row: LivePendingAskView, respond: RespondToolApprovalFn, signal?: AbortSignal, lane?: ToolApprovalFrameLaneOpts): Promise<ToolApprovalFrameOutcome>;
+/** {@link createSuspendedAskTracker} 每次吞一张快照的产出。 */
+export interface SuspendedAskDelta {
+    /** 首次见到、该出卡的行。 */
+    appeared: LivePendingAskView[];
+    /** 此前 appeared 过、现在不在列表里的 approvalId(已被别处决断 / 过期 / 引擎换代)⇒ 撤卡。 */
+    gone: string[];
+}
+export interface SuspendedAskTracker {
+    ingest(snapshot: ApprovalsFeedSnapshot | null | undefined): SuspendedAskDelta;
+    /**
+     * 流内帧腿出卡**之前**调:认领这只 ask。返回 `true` = 帧腿可以出卡(此后快照不再为它出第二张);
+     * 返回 `false` = 它已经从快照出过卡 / 已被认领 / 已决断 ⇒ 帧腿**跳过出卡**(两条通道同一只 ask 只有一张卡、一次决断)。
+     */
+    noteSurfacedByStream(approvalId: string): boolean;
+    /** 让一只已出过卡的 ask 在下一张快照里重新 `appeared`(卡被关掉 / 改写被拒 `editRefused` 之后)。 */
+    requeue(approvalId: string): void;
+    /** 这只 ask 已在本端决断 ⇒ 引擎结算前它还会在列表里待一会儿,不重新出卡;之后消失也不再报 gone。 */
+    noteDecided(approvalId: string): void;
+}
+/**
+ * 快照 → 出卡 / 撤卡的去重账(每个宿主会话一只;不是模块级单例)。同一 `approvalId` 只 `appeared` 一次;
+ * `livePending` 键缺席按「现在一条都看不到」处理已出的卡(引擎换代后旧卡没有决断口可用)。
+ *
+ * 两本账,**都不按条数淘汰活跃条目**(异源对抗复审:无差别的「满了删最旧」会让仍挂着的卡重出、漏撤):
+ *   · `shown` = 从快照出过卡、且仍在列表里的 ask。条目随「从列表消失」离账 ⇒ 大小恒 ≤ 列表长度,不设上界。
+ *   · `claimed` = 被流内帧腿认领 / 已在本端决断的 ask,值 = 是否已在某张快照里见过。见过之后从列表消失 ⇒ 这只 ask
+ *     的一生结束,离账(同 id 日后再出现是新的一只)。**从未见过**的认领才受上界管(帧先到、快照一直没列到它的那一小段),
+ *     满了只淘汰这一类里最旧的。
+ */
+export declare function createSuspendedAskTracker(filter?: SuspendedAskFilter): SuspendedAskTracker;

package/dist/hitl/livePendingAsk.js

@@ -0,0 +1,198 @@
+/**
+ * livePendingAsk — 「悬挂的流内 ask」的三端共用读面与决断口(0.72.14)。
+ *
+ * ── 这个模块补的是哪一个缺口 ────────────────────────────────────────────────────────────────
+ * 流内 ask 在铸造那一刻若没有活着的宿主流可投,引擎把它转成**悬挂**(窗约一小时,不补发、不重算),此后只在
+ * `GET /v1/approvals` 回体的第二顶层键 `livePending` 里可发现。后台 workflow 的子代恒落这一形:宿主 turn 先结束,
+ * 子代稍后才撞上审批门 ⇒ 用户面零帧零卡,代理静默卡到窗尽。本模块让端从 {@link startApprovalsFeed} 的快照里
+ * 读到这些行、出带子代身份的卡、并经**与流内帧腿同一条链**决断。
+ *
+ * ── 🔴 四条读法 ────────────────────────────────────────────────────────────────────────────
+ *  ① **键缺席 ≠ 没有悬挂 ask**:老引擎不发这个键 ⇒ `not_reported`;快照上键缺席,计数读 `null`(不知道),绝不铸 `[]` / `0`。
+ *  ② **数组名即路由判据**:`livePending` 行的决议口是 `POST /v1/tool-approvals/{approvalId}/respond`(流内审批那个口),
+ *     **不是** durable 行的 decide 口;两数组不混编。幂等键 = `approvalId`(与流内帧同一个 id)。
+ *  ③ **可选旗标 only-if-true**:`fromSubagent` / `governanceForced` / `requiresRealApproval` 缺席绝不编码成 `false`。
+ *  ④ **行上没有工具入参**(引擎刻意不在这个读面开第二道脱敏面)⇒ 卡必须明说「看不到入参」,不许渲一个空命令冒充全貌。
+ *
+ * sdk 的 barrel 没有导出这一行的类型 ⇒ 按**结构**窄读(与 `capabilities.executionLane` 同一姿势),多余成员不过境。
+ */
+import { surfaceToolApprovalFrameAndRespond, } from './toolApprovalWire.js';
+function nonEmptyString(v) {
+    return typeof v === 'string' && v !== '';
+}
+function nonNegativeFinite(v) {
+    return typeof v === 'number' && Number.isFinite(v) && v >= 0;
+}
+/** `GET /v1/approvals` 回体 → `livePending` 段读数。四必填位坏形的行丢弃并计数;同 `approvalId` 重复行留第一条。 */
+export function readLivePendingRows(body) {
+    if (body === null || typeof body !== 'object' || Array.isArray(body))
+        return { kind: 'malformed' };
+    if (!('livePending' in body))
+        return { kind: 'not_reported' };
+    const raw = body.livePending;
+    if (raw === undefined)
+        return { kind: 'not_reported' };
+    if (!Array.isArray(raw))
+        return { kind: 'malformed' };
+    const rows = [];
+    const seen = new Set();
+    let dropped = 0;
+    for (const item of raw) {
+        if (item === null || typeof item !== 'object' || Array.isArray(item)) {
+            dropped++;
+            continue;
+        }
+        const o = item;
+        if (!nonEmptyString(o.approvalId) || !nonEmptyString(o.toolName) || !nonNegativeFinite(o.ts) || !nonNegativeFinite(o.expiresAtMs)) {
+            dropped++;
+            continue;
+        }
+        if (seen.has(o.approvalId)) {
+            dropped++;
+            continue;
+        }
+        seen.add(o.approvalId);
+        rows.push({
+            approvalId: o.approvalId,
+            toolName: o.toolName,
+            ts: o.ts,
+            expiresAtMs: o.expiresAtMs,
+            ...(nonEmptyString(o.sessionId) ? { sessionId: o.sessionId } : {}),
+            ...(o.requiresRealApproval === true ? { requiresRealApproval: true } : {}),
+            ...(o.governanceForced === true ? { governanceForced: true } : {}),
+            ...(o.fromSubagent === true ? { fromSubagent: true } : {}),
+            ...(nonEmptyString(o.originTaskId) ? { originTaskId: o.originTaskId } : {}),
+        });
+    }
+    return { kind: 'present', rows, dropped };
+}
+/** 快照里**出自子代**的悬挂 ask(宿主自己的流内 ask 走流内帧腿,不在这里出卡)。未报 / 没有快照 ⇒ `[]`。 */
+export function suspendedSubagentAsks(snapshot, filter) {
+    const rows = snapshot?.livePending;
+    if (!Array.isArray(rows))
+        return [];
+    return rows.filter(r => r.fromSubagent === true && (filter?.sessionId === undefined || r.sessionId === filter.sessionId));
+}
+export function countApprovalsAwaitingDecision(snapshot, filter) {
+    if (snapshot === null || snapshot === undefined)
+        return { durable: null, live: null, suspendedSubagent: null };
+    const bySession = (rows) => filter?.sessionId === undefined ? [...rows] : rows.filter(r => r.sessionId === filter.sessionId);
+    const durable = Array.isArray(snapshot.pending) ? bySession(snapshot.pending).length : null;
+    if (!Array.isArray(snapshot.livePending))
+        return { durable, live: null, suspendedSubagent: null };
+    const live = bySession(snapshot.livePending);
+    return { durable, live: live.length, suspendedSubagent: live.filter(r => r.fromSubagent === true).length };
+}
+/**
+ * 悬挂行 → 流内帧腿的输入。只带行上**真有**的位:窗三键不带(行上只有绝对死线,没有出帧时刻,凑不出可校偏的窗),
+ * `args` 不带(行上没有)。`sourceTaskId` = `originTaskId`(卡头子代身份徽章的来源)。
+ */
+export function livePendingRowToApprovalFrame(row) {
+    return {
+        type: 'tool_approval',
+        approvalId: row.approvalId,
+        toolName: row.toolName,
+        ...(row.fromSubagent === true ? { fromSubagent: true } : {}),
+        ...(row.originTaskId !== undefined ? { sourceTaskId: row.originTaskId } : {}),
+        ...(row.governanceForced === true ? { governanceForced: true } : {}),
+        ...(row.requiresRealApproval === true ? { requiresRealApproval: true } : {}),
+    };
+}
+/**
+ * 出卡并决断一条悬挂 ask —— **与流内帧腿同一条链**({@link surfaceToolApprovalFrameAndRespond}):同一个卡口、
+ * 同一个身份键铸口(`approvalId`)、同一套回执 / 拒绝读法。差别只有一处:行上没有入参 ⇒ 卡上明说
+ * (`argsUnavailable`),且这张卡上收到「编辑后批准」时**整次不发**(结局 `editRefused`;没有原文可编,丢掉改写再批准 =
+ * 批准了人没看到的原始入参)。
+ */
+export function surfaceSuspendedAskAndRespond(row, respond, signal, lane) {
+    return surfaceToolApprovalFrameAndRespond(livePendingRowToApprovalFrame(row), respond, undefined, signal, {
+        ...lane,
+        argsUnavailable: true,
+    });
+}
+/** 「认领了但还没在任何一张快照里见过」的条目上界(见 {@link createSuspendedAskTracker} 的账目说明)。 */
+const TRACKER_UNSEEN_CLAIMS_MAX = 512;
+/**
+ * 快照 → 出卡 / 撤卡的去重账(每个宿主会话一只;不是模块级单例)。同一 `approvalId` 只 `appeared` 一次;
+ * `livePending` 键缺席按「现在一条都看不到」处理已出的卡(引擎换代后旧卡没有决断口可用)。
+ *
+ * 两本账,**都不按条数淘汰活跃条目**(异源对抗复审:无差别的「满了删最旧」会让仍挂着的卡重出、漏撤):
+ *   · `shown` = 从快照出过卡、且仍在列表里的 ask。条目随「从列表消失」离账 ⇒ 大小恒 ≤ 列表长度,不设上界。
+ *   · `claimed` = 被流内帧腿认领 / 已在本端决断的 ask,值 = 是否已在某张快照里见过。见过之后从列表消失 ⇒ 这只 ask
+ *     的一生结束,离账(同 id 日后再出现是新的一只)。**从未见过**的认领才受上界管(帧先到、快照一直没列到它的那一小段),
+ *     满了只淘汰这一类里最旧的。
+ */
+export function createSuspendedAskTracker(filter) {
+    const shown = new Set();
+    const claimed = new Map();
+    const claim = (id) => {
+        if (claimed.has(id))
+            return;
+        claimed.set(id, false);
+        let unseen = 0;
+        for (const seen of claimed.values())
+            if (!seen)
+                unseen++;
+        if (unseen <= TRACKER_UNSEEN_CLAIMS_MAX)
+            return;
+        for (const [oldId, seen] of claimed) {
+            if (seen)
+                continue;
+            claimed.delete(oldId);
+            break;
+        }
+    };
+    return {
+        ingest(snapshot) {
+            const rows = suspendedSubagentAsks(snapshot, filter);
+            const present = new Set(rows.map(r => r.approvalId));
+            const appeared = [];
+            for (const r of rows) {
+                if (claimed.has(r.approvalId)) {
+                    claimed.set(r.approvalId, true);
+                    continue;
+                }
+                if (shown.has(r.approvalId))
+                    continue;
+                shown.add(r.approvalId);
+                appeared.push(r);
+            }
+            const gone = [];
+            for (const id of [...shown]) {
+                if (present.has(id))
+                    continue;
+                shown.delete(id);
+                gone.push(id);
+            }
+            // 见过、现在不在列表里的认领 = 这只 ask 已结算 ⇒ 离账
+            for (const [id, seen] of [...claimed])
+                if (seen && !present.has(id))
+                    claimed.delete(id);
+            return { appeared, gone };
+        },
+        noteSurfacedByStream(approvalId) {
+            if (typeof approvalId !== 'string' || approvalId === '')
+                return false;
+            if (shown.has(approvalId) || claimed.has(approvalId))
+                return false;
+            claim(approvalId);
+            return true;
+        },
+        noteDecided(approvalId) {
+            if (typeof approvalId !== 'string' || approvalId === '')
+                return;
+            // 从快照出过卡的 ask 已在列表里见过 ⇒ 认领直接记「见过」,结算后随列表消失离账
+            const wasShown = shown.delete(approvalId);
+            if (wasShown)
+                claimed.set(approvalId, true);
+            else
+                claim(approvalId);
+        },
+        requeue(approvalId) {
+            if (typeof approvalId !== 'string' || approvalId === '')
+                return;
+            shown.delete(approvalId);
+            claimed.delete(approvalId);
+        },
+    };
+}

package/dist/hitl/parkResolver.d.ts

@@ -45,7 +45,7 @@ export declare const MAX_TOTAL_PARKS = 64;
  * 双向钉住,任何一边加员而另一边不跟 ⇒ 编译红。此前两边靠人肉同步,而不同步的可观测后果是
  * 「新码被 `isGateFailureCode` 降成 undefined 后静默走文案兜底臂」—— 门里长得跟正常一模一样。
  */
-export declare const GATE_FAILURE_CODES: readonly ["no_pending", "binding_mismatch", "wrong_gate", "bad_plan_edit", "empty_answer"];
+export declare const GATE_FAILURE_CODES: readonly ["no_pending", "binding_mismatch", "wrong_gate", "bad_plan_edit", "bad_plan_mode", "empty_answer"];
 export type GateFailureCode = (typeof GATE_FAILURE_CODES)[number];
 export type GateOutcome = 
 /** `receipt`(B-070 / L-200,0.65.0):这次 decide 的 **200 回执读数** —— 与 fs 腿的

package/dist/hitl/parkResolver.js

@@ -98,6 +98,8 @@ export const GATE_FAILURE_CODES = [
     'binding_mismatch',
     'wrong_gate',
     'bad_plan_edit',
+    /** 0.72.13 CC-46:plan-review 的 permissionModeAfter 坏形(非 approve 带这一位 / 词表外)被本地拦下。 */
+    'bad_plan_mode',
     /** FIX②:空作答被本地拦下(空 answers[] / 空 selected[] / 空 header)。 */
     'empty_answer',
 ];