@sema-agent/client-core 0.77.0 → 0.77.2

package/dist/hitl/hitlHostSurface.d.ts

@@ -1,5 +1,4 @@
 import type { ClassifierDenyVerdict } from '../classifierVerdictWire.js';
-/** footer 通知(壳 `AppState.notifications.current` 的形)。 */
 export interface HitlNotice {
     key: string;
     text: string;
@@ -7,181 +6,32 @@ export interface HitlNotice {
     priority: 'immediate';
     timeoutMs: number;
 }
-/**
- * 分类器 deny 裁决的**这一只 call 的现场**(L-69⑨,0.52.0;{@link HitlHostSurface.surfaceClassifierDeny}
- * 的 **additive 可选**第三参)。
- *
- * 🔴 为什么要有它:修前宿主只拿到 `toolName`,于是端的 Recent Denials 面板三行同名(三条被拒的
- *    `Bash` 长一个样),而端要做的两件事 —— **行文案**(这一行说的是哪条命令 / 哪个文件)与
- *    **retry 粒度**(重试这一只调用,而不是「整个 Bash 工具」)—— 都需要这一只 call 的身份与入参。
- * 🔴 `args` 是 **UNTRUSTED** wire 值(模型产出的工具入参):本包**原样**交给宿主,不渲染、不截断、
- *    不消毒 —— 展示消毒是端的事(cli 有 `cleanUntrustedForDisplay`)。要拿它铸**行文案**请用
- *    `classifierDenyDisplay(toolName, args)`(`src/classifierVerdictWire.ts`,三端同形的判定)。
- * 🔴 `args` **可缺席**:分类器拒绝的工具通常没被 gate,而在飞 args 表是**有界**的(见
- *    `gateLedger.START_ARGS_MAX_ENTRIES`),长流上早期 call 的快照可能已被淘汰。缺席 = 诚实缺席,
- *    端按「只有工具名」降级渲,**绝不**据此编一个空 args 出来。
- */
 export interface ClassifierDenyContext {
-    /** 这一只被拒调用的 wire `toolCallId`(retry 粒度的锚;帧上取,恒在场)。 */
     toolCallId: string;
-    /** 这一只调用的 `tool_start` 入参快照;**UNTRUSTED**,缺席 = 台账里没有(见上)。 */
     args?: unknown;
 }
-/** HITL 的宿主副作用面 —— 通知上屏 + 分类器 deny 的端侧记账。 */
 export interface HitlHostSurface {
-    /** 立即顶到 current(壳:`notifications.current = notice`,queue 不动)。 */
     showNotice(notice: HitlNotice): void;
-    /** **仅当** current 仍是这个 key 时清掉(壳原文的 if-still-mine 语义 —— 否则会误清别人的通知)。 */
     clearNoticeIfCurrent(key: string): void;
-    /**
-     * 分类器 deny 裁决的宿主副作用:footer 通知 + /permissions Recent Denials 记账(壳资产)。
-     *
-     * 🔴 `ctx` 是 **additive 可选**第三参(0.52.0,L-69⑨):老宿主的两参实现**零改动照跑**
-     *    —— JS 里多传一个实参不影响两参函数,TS 里「参数少的函数可赋给参数多的签名」是语言规则
-     *    (函数参数双变/协变),desktop/web 现有 `surfaceClassifierDeny(t, v)` 实现不需要跟车。
-     *    ⚠️ 反过来**不成立**:端一旦读了 `ctx`,就必须按可选处理(库对老路径/缺席场景不承诺在场)。
-     */
     surfaceClassifierDeny(toolName: string, verdict: ClassifierDenyVerdict, ctx?: ClassifierDenyContext): void;
 }
-/** 装 HITL 宿主面(传 null 卸)。返回还原函数。 */
 export declare function installHitlHostSurface(surface: HitlHostSurface | null): () => void;
-/** W1 带 key 变体:装/卸某会话的 HITL 宿主面(多会话宿主每会话一键,互不顶盖)。 */
 export declare function installHitlHostSurfaceFor(sessionKey: string, surface: HitlHostSurface | null): () => void;
-/** 🔴 宿主自检:恒应为 0。非 0 = 有 HITL 副作用发生时口不在,那一行 warn / 那条记账丢了。 */
 export declare function hitlHostSurfaceMisses(): number;
-/** W1 带 key 变体(miss 计数逐键)。 */
 export declare function hitlHostSurfaceMissesFor(sessionKey: string): number;
-/** W1 读端:某会话的 HITL 宿主面(未装 = null;**不计 miss** —— miss 只在副作用真发生时计)。 */
 export declare function hitlHostSurfaceFor(sessionKey: string): HitlHostSurface | null;
-/** 测试钩:卸口 + 清计数。 */
 export declare function _resetHitlHostSurfaceForTest(): void;
-/** 内部读点(计 miss)。`askGateWire.ts` 的 `surfaceClassifierDeny` 路径与本文件的
- *  `surfaceCancelDenyWarn` 共用它。 */
 export declare function surfaceForCurrentSession(): HitlHostSurface | null;
-/**
- * 中断-deny 的后台 settle 观察预算。
- *
- * ══ 🔴 §2.4「DENY-abort」撤稿 + 本常量的论证前提重审(0.42.0;server [4833] 明请)═══════════
- *
- * **本段 0.28.0 原文写的是**:「decide 是 SYNC 驱动的(引擎跑到下一 park/终态才返,实测 4-5s+),
- * 但 **DENY-abort 语义上引擎收到即终结 run**;2s 内连收都没收到 ⇒ 按丢失警示」。
- * 那句加粗的前提**已被上游撤稿**,来源是 server 自己的契约成文(`4631a0f`,随 7.39 出;
- * `ASSISTANT-WIRE-CONTRACT.md` §4a):**DENY 是 TOOL 级的应答,永远不是 run kill**;客户端不得
- * 把「拒绝」译成「取消」;两个动词的 wire 判别式是 `cancelled` vs `gate.batch_halted`。
- * ⇒ 「引擎收到 deny 即终结 run」这条**不成立**:deny 只结算**这一只 ask**,run 按自己的编排继续
- *   (裸拒 ⇒ `gate.batch_halted` 兄弟 coded 结算 + `haltedOnUserRejection`;带留言拒 ⇒ run 续跑)。
- *
- * **重审结论(本批只改论证,不改数值 —— 理由写全)**:
- *   · 旧论证「2s 没结算 = deny 大概率丢了,因为收到就该终结」**作废**;
- *   · 但本常量守的那件事**换一个理由仍然成立**:它是一个**观察上限**,给「decide 永不返回」这种
- *     形态一条出声的路 —— 没有它,一次真的丢失就只剩静默;
- *   · **数值不在本批动**:动它是行为面改动,而判据(多久算「没回来」)只有拿真实 decide 往返分布
- *     说了算,那份实测在**消费端**(壳中断路径)而不在包里;且下游 `sema-cli` 的
- *     `src/sema/hitlCancelDeny.test.ts` 按现值锁着行为,单边改会当场把消费端打红。
- *   · **如实登记的残余**(接入档 §6e/§7 同批记):预算到点就发的那行 warn 措辞是
- *     {@link CANCEL_DENY_WARN_TEXT}（「the session may stay locked」),而在新契约下「decide 慢」
- *     与「deny 丢了」这两件事在 2s 这个刻度上**不可分** —— 晚到的成功不会撤回那行 warn(只有 10s
- *     自清)。要根治得做成两档(软档只记 debug、硬档才上屏),那是**跨仓一批**:包侧改时序、壳侧
- *     同批换判据与用例。本批不做单边改动。
- */
 export declare const CANCEL_DENY_BUDGET_MS = 2000;
-/** warn 行文案(测试锁字面)。 */
 export declare const CANCEL_DENY_WARN_TEXT = "could not cancel the pending question \u2014 the session may stay locked; the run may need engine-side recovery";
-/** 文案(测试锁字面)。措辞刻意描述**后果**而不是内部机制:用户要知道的是「下次还会问」。 */
 export declare const REMEMBER_NOT_APPLIED_WARN_TEXT = "this session-wide allow was not remembered by the worker \u2014 you will be asked again for this tool";
-/** 文案(测试锁字面)。"original" 是判据词:用户必须读到「跑的是原来那份」。 */
 export declare const EDIT_NOT_FORWARDED_WARN_TEXT = "your edited tool input was NOT forwarded \u2014 the tool is running with the ORIGINAL input you saw before editing";
-/**
- * `allow_session` 决断的 ack 回报 `rememberApplied:false`(server 1.239 起诚实回显 —— 典型成因
- * 是这条 run 没有 sessionId,grant 无处可落)。
- *
- * 🔴 为什么这必须上屏而不是只记 debug:三选卡第 2 项在用户心里签的是「本会话这个工具不再问我」。
- * 记没落店而界面照渲「全放行」,就是**把一个没有发生的授权渲成发生了** —— 下一次弹卡时用户会以为
- * 是 bug,更坏的是他可能因此养成「一路回车」的习惯。缺席(旧 server 不出这个位)= 未知,
- * 按 [honest-absence-not-fabricated-zero] 一律不发通知,绝不把未知渲成失败。
- * 无宿主口(print/headless 没屏)⇒ 静默,与 {@link surfaceCancelDenyWarn} 同语义。
- */
 export declare function surfaceRememberNotApplied(): void;
-/**
- * 「编辑并批准」带了 `updatedInput`,而 ack 回报 `updatedInputForwarded:false`(server 1.241 起
- * 诚实回显)—— 引擎拿到的是**原始**入参。
- *
- * 🔴 这一条比 remember 那条严重一个量级,它是本批 对抗复审判的 [high]:用户在卡上把
- * `rm -rf /tmp/x` 改成 `rm -rf /tmp/x/build` 然后按了批准,而真正执行的是他改之前那条。
- * **事后没有 fail-closed 的余地**(allow 已经送达,工具已经在跑),所以唯一诚实的处置就是立刻
- * 响亮地说出来 —— 静默(此前只写 debug 日志)等于让用户以为自己的编辑生效了。
- * 上游的正位是让 server 在「带了 updatedInput 却转发不了」时 fail-closed 拒批;那属跨仓,
- * 已记进 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] 修):
- *  · 不写「这台引擎不支持」——能力位缺席有三种同形成因(宿主没接这个字段 / 探测还没回来 / 探测失败),
- *    其中只有明确的 `false` 才勉强算「引擎说了不」。写成断言就是替引擎宣布一件没证据的事
- *    ([honest-absence-not-fabricated-zero]);改成 `could not be confirmed` 的未知口径。
- *  · 「审批本身过了」这句**只在 respond 真成功之后**才成立 —— 所以本通知的**发出时机**被移到
- *    `await respond(...)` 成功之后(见 `toolApprovalWire` 的调用点顶注),而不是丢键那一刻。
- */
 export declare const RULE_NOT_SENT_WARN_TEXT = "your \"don't ask again\" choice was NOT sent to this engine \u2014 support for that rule form could not be confirmed. The approval itself went through, but you will be asked again";
-/**
- * 卡上选中了「不再询问」(编辑臂的自由文本 / 批臂的合取批),而**这台引擎的能力位没有确认**
- * 那条兑付通道 ⇒ 编排层把持久臂整条丢掉、只送决断。
- *
- * 🔴 为什么这必须上屏而不是只记 debug(异源对抗复审三轮 [high] 采纳,0.43.0):它与
- * {@link surfaceRememberNotApplied} 是**同一个病**——用户按下了一个明确的意图,系统把它静默
- * 丢掉,然后下一次照旧弹卡。用户能得出的唯一结论是「这个功能坏了」或「我按错了」。卡上那一格
- * 是**真 affordance**(offer 确实在场、确实可以走本地落规则那条路),被丢的只是**这条 wire
- * 兑付通道** —— 所以正解不是把选项藏起来,是**如实说出来**。
- * 🔴 **一条通知服务两条臂**(同形清剿):编辑臂(`respondFreeFormRules` 位缺席)与批臂
- * (`respondBatchRuleOffers` 位缺席)此前都只写 debug —— 同一个病形两处存量,同批一起改。
- * 🔴 决断本身**不受影响**(照常送达),所以文案第二句说清「审批过了,只是规则没存」——
- * ⚠️ 正因为文案里有那句话,**调用时机必须在 `respond` 真成功之后**(异源对抗复审四轮 [medium]:
- * 丢键那一刻就发,而随后 respond 抛错 ⇒ 决断其实**没有**落定,用户却已经读到「审批过了」,
- * 可能按「工具已经在跑」继续操作)。调用点的时序契约见 `toolApprovalWire` 那一处。
- * 🔴 文案**不说「引擎不支持」**:能力位缺席三种同形成因(宿主没接字段 / 探测未回 / 探测失败),
- * 断言引擎的能力是没有证据的话 —— 用 `could not be confirmed` 的未知口径。
- * 无宿主口(print/headless 没屏)⇒ 静默,与本文件其余 surface 同语义。
- */
 export declare function surfaceRuleArmNotSent(): void;
-/**
- * 文案(测试锁字面)。与 {@link RULE_NOT_SENT_WARN_TEXT} **刻意分两条**:两者对用户的下一步建议不同 ——
- * 那条说「这台引擎能不能收还不知道」(换台引擎/等探测就好了),本条说「你这次的选择**本身**没过
- * 客户端那道核对」(卡口实现有问题或同时给了两个互斥选择,换台引擎也不会变)。折成一条会让任一方
- * 谎报原因。措辞同样只说证得出的话:不猜是哪一种坏法,把两种都摆出来。
- */
 export declare const RULE_NOT_SENT_REJECTED_WARN_TEXT = "your \"don't ask again\" choice was NOT sent \u2014 it did not pass the client-side check (the card returned a rule the engine never offered, an index that is not a batch offer, or two conflicting choices at once). The approval itself went through, but you will be asked again";
-/**
- * 卡上选中了「不再询问」,而那次选择**没过包内那道表核 / 互斥核**(报了引擎没 offer 过的文本、
- * 下标不指向 batch offer、或文本臂与批臂同场)⇒ 编排层把持久臂整条丢掉、只送决断。
- *
- * 🔴 为什么这也必须上屏(异源对抗复审十轮 [medium] 采纳,0.43.0):它与
- * {@link surfaceRuleArmNotSent} 是**同一个诚实性问题**,只是原因换了一个 —— 用户按下的明确意图
- * 被系统丢掉,审批照常成功,下次照旧弹卡。此前这三条丢键路径**只写 `hostLog('error')`**:
- * 那是给开发者看的诊断,**不是**给按下按钮的那个人的答复。
- * 🔴 **时序契约与那条一致**:文案里有「审批本身过了」⇒ 只在 `await respond(...)` 真成功之后发。
- * 🔴 **成因通常是卡口实现的 bug**(表外文本/坏下标/两臂同场都是宿主侧构造出来的),所以 `hostLog`
- * 的那条 `error` 留痕**照旧保留** —— 两个受众,两条通道,谁都不顶替谁。
- * 无宿主口(print/headless 没屏)⇒ 静默,与本文件其余 surface 同语义。
- */
 export declare function surfaceRuleArmRejected(): void;
-/**
- * 中断 deny 的有界观察(壳侧单测 `hitlCancelDeny.test.ts` 的被测面;REF-CC-023 起两条决断腿共用)。
- *
- * 🔴 **命名撤稿(0.42.0)**:函数名与日志里的「cancel-by-deny」是**历史词**,保留只为不打断下游
- * 按名锚的用例。它描述的动作在现行契约(server `ASSISTANT-WIRE-CONTRACT.md` §4a)下的准确说法是
- * 「**中断时把这只挂着的 ask 用一个 TOOL 级 deny 结算掉**,好让 run 不停在 suspended 上」——
- * **不是**「用 deny 去 cancel 一条 run」。方向也别读反:这里是把**用户的中断**结算成一次 deny,
- * 而 §4a 禁的是反向的那件事(把**用户的拒绝**译成 cancel),两者不是同一件事。
- *
- * 铁律:不 await 进 abort 返回路径(用户立即拿回控制);这里只管后台 settle 的«观察»:
- *   - 2s 内 settle 成功 ⇒ 零上屏(SEMA_DEBUG 记成功);
- *   - 失败/超时 ⇒ 上屏一行 warn + SEMA_DEBUG 记原因(deny 丢失 = run 卡 suspended,下一条消息
- *     撞 409;配合件2b 的专属文案,用户知道现场 + 出路);
- *   - `code === 'no_pending'`(判据见上方 `isNoPendingError`)⇒ 良性静默(pending 已被别处消解/
- *     过期 —— run 没锁;hitlBridge decideTool 的同款语义,那里的静默维持不动)。
- */
 export declare function observeCancelByDeny(settle: Promise<unknown>, taskId: string): void;

package/dist/hitl/hitlHostSurface.js

@@ -1,32 +1,12 @@
-/**
- * hitlHostSurface.ts — REF-CC-023(2026-08-02,P3 wave2 卡C-bridge):共享的 HITL 宿主通知面
- * + cancel-by-deny 有界观察,从 `askGateWire.ts` 提出来给 `toolApprovalWire.ts` 也用。
- *
- * 🔴 为什么要提出来(不是顺手重排):`askGateWire.ts` 已经 `import` `toolApprovalWire.ts`(§ ask 桥
- * 消费工具审批帧判定),反向 `toolApprovalWire.ts` → `askGateWire.ts` 会成环。`observeCancelByDeny`
- * 曾经只活在 `askGateWire.ts` 里,而 `toolApprovalWire.ts:surfaceFsApprovalAndDecide` 的中断-deny
- * 臂原样复刻了它要修的那个事故(件3,中断事故修复批 G,2026-07-15):裸 `.catch(()=>{})` 全吞 ⇒
- * deny 丢失时 run 永卡 suspended、session 锁死,用户下一条消息撞 409「active run」还全无线索。
- * 单源到一个两边都能 import 的模块,两条腿共用同一次修复,而不是「同一个仓、同一个事故、
- * 一处修了另一处原样留着」。
- *
- * 这个模块也顺带带走了 `surfaceCancelDenyWarn` 唯一依赖的宿主通知面(`HitlHostSurface` /
- * `installHitlHostSurface*` / `hitlHostSurfaceFor*`)—— 它不只是给 cancel-by-deny 用(分类器 deny
- * 的端侧记账 `surfaceClassifierDeny` 也走它),`askGateWire.ts` 仍然是它的主要消费方,只是不再是
- * 唯一持有方。
- */
 import { createSessionSlot, DEFAULT_SESSION_KEY } from '../sessionSlot.js';
 import { hostLog } from '../host.js';
 import { unrefTimer } from '../unrefTimer.js';
 import { HitlSafetyError } from './hitlBridge.js';
-// W1(design/161):sessionKey → 注册表;零参 API = DEFAULT_SESSION_KEY 兼容层(cli 装配不动)。
 const hostSurfaceByKey = createSessionSlot();
 const hostSurfaceMissesByKey = new Map();
-/** 装 HITL 宿主面(传 null 卸)。返回还原函数。 */
 export function installHitlHostSurface(surface) {
     return installHitlHostSurfaceFor(DEFAULT_SESSION_KEY, surface);
 }
-/** W1 带 key 变体:装/卸某会话的 HITL 宿主面(多会话宿主每会话一键,互不顶盖)。 */
 export function installHitlHostSurfaceFor(sessionKey, surface) {
     const prev = hostSurfaceByKey.get(sessionKey);
     hostSurfaceByKey.set(sessionKey, surface);
@@ -34,25 +14,19 @@ export function installHitlHostSurfaceFor(sessionKey, surface) {
         hostSurfaceByKey.set(sessionKey, prev);
     };
 }
-/** 🔴 宿主自检:恒应为 0。非 0 = 有 HITL 副作用发生时口不在,那一行 warn / 那条记账丢了。 */
 export function hitlHostSurfaceMisses() {
     return hitlHostSurfaceMissesFor(DEFAULT_SESSION_KEY);
 }
-/** W1 带 key 变体(miss 计数逐键)。 */
 export function hitlHostSurfaceMissesFor(sessionKey) {
     return hostSurfaceMissesByKey.get(sessionKey) ?? 0;
 }
-/** W1 读端:某会话的 HITL 宿主面(未装 = null;**不计 miss** —— miss 只在副作用真发生时计)。 */
 export function hitlHostSurfaceFor(sessionKey) {
     return hostSurfaceByKey.get(sessionKey) ?? null;
 }
-/** 测试钩:卸口 + 清计数。 */
 export function _resetHitlHostSurfaceForTest() {
     hostSurfaceByKey.clear();
     hostSurfaceMissesByKey.clear();
 }
-/** 内部读点(计 miss)。`askGateWire.ts` 的 `surfaceClassifierDeny` 路径与本文件的
- *  `surfaceCancelDenyWarn` 共用它。 */
 export function surfaceForCurrentSession() {
     const hostSurface = hitlHostSurfaceFor(DEFAULT_SESSION_KEY);
     if (hostSurface === null) {
@@ -60,52 +34,13 @@ export function surfaceForCurrentSession() {
     }
     return hostSurface;
 }
-// ── 件3(中断事故修复批 G,2026-07-15)—— 中断 deny 的有界观察 ─────────────────────────────────
-/**
- * 中断-deny 的后台 settle 观察预算。
- *
- * ══ 🔴 §2.4「DENY-abort」撤稿 + 本常量的论证前提重审(0.42.0;server [4833] 明请)═══════════
- *
- * **本段 0.28.0 原文写的是**:「decide 是 SYNC 驱动的(引擎跑到下一 park/终态才返,实测 4-5s+),
- * 但 **DENY-abort 语义上引擎收到即终结 run**;2s 内连收都没收到 ⇒ 按丢失警示」。
- * 那句加粗的前提**已被上游撤稿**,来源是 server 自己的契约成文(`4631a0f`,随 7.39 出;
- * `ASSISTANT-WIRE-CONTRACT.md` §4a):**DENY 是 TOOL 级的应答,永远不是 run kill**;客户端不得
- * 把「拒绝」译成「取消」;两个动词的 wire 判别式是 `cancelled` vs `gate.batch_halted`。
- * ⇒ 「引擎收到 deny 即终结 run」这条**不成立**:deny 只结算**这一只 ask**,run 按自己的编排继续
- *   (裸拒 ⇒ `gate.batch_halted` 兄弟 coded 结算 + `haltedOnUserRejection`;带留言拒 ⇒ run 续跑)。
- *
- * **重审结论(本批只改论证,不改数值 —— 理由写全)**:
- *   · 旧论证「2s 没结算 = deny 大概率丢了,因为收到就该终结」**作废**;
- *   · 但本常量守的那件事**换一个理由仍然成立**:它是一个**观察上限**,给「decide 永不返回」这种
- *     形态一条出声的路 —— 没有它,一次真的丢失就只剩静默;
- *   · **数值不在本批动**:动它是行为面改动,而判据(多久算「没回来」)只有拿真实 decide 往返分布
- *     说了算,那份实测在**消费端**(壳中断路径)而不在包里;且下游 `sema-cli` 的
- *     `src/sema/hitlCancelDeny.test.ts` 按现值锁着行为,单边改会当场把消费端打红。
- *   · **如实登记的残余**(接入档 §6e/§7 同批记):预算到点就发的那行 warn 措辞是
- *     {@link CANCEL_DENY_WARN_TEXT}（「the session may stay locked」),而在新契约下「decide 慢」
- *     与「deny 丢了」这两件事在 2s 这个刻度上**不可分** —— 晚到的成功不会撤回那行 warn(只有 10s
- *     自清)。要根治得做成两档(软档只记 debug、硬档才上屏),那是**跨仓一批**:包侧改时序、壳侧
- *     同批换判据与用例。本批不做单边改动。
- */
 export const CANCEL_DENY_BUDGET_MS = 2000;
-/** warn 行文案(测试锁字面)。 */
 export const CANCEL_DENY_WARN_TEXT = 'could not cancel the pending question — the session may stay locked; the run may need engine-side recovery';
 const CANCEL_DENY_WARN_KEY = 'hitl-cancel-deny-warn';
 const CANCEL_DENY_WARN_TIMEOUT_MS = 10_000;
-/** 失败 warn 上屏:借 footer notifications 通道。壳原文经 `appStateRef` 直写 store
- *  (immediate 语义:立即顶到 current + 到点自清「仅当仍是本 warn 时」);本包把那两次
- *  setState 拆成宿主口的两个动词,**时序纪律(2s 预算 / 10s 自清)留在库内**——
- *  [paired-mechanisms-must-share-premise]:只给「显示」不给「清」,端各写各的清法必然漂。
- *  无口(print/headless 没屏可上)⇒ 静默,与壳原文 `if (!store) return` 同语义。 */
 function surfaceCancelDenyWarn() {
     surfaceSelfClearingWarn(CANCEL_DENY_WARN_KEY, CANCEL_DENY_WARN_TEXT, CANCEL_DENY_WARN_TIMEOUT_MS);
 }
-/**
- * 「上屏一行 warning + 到点自清(仅当仍是本 key)」的**唯一**实现(FIX① 收编:此前只有
- * cancel-by-deny 一处,新增 remember-not-applied 时若各写一遍,两处的自清时序必然漂 ——
- * [paired-mechanisms-must-share-premise];顺带保住 TIMER③ 的裸定时器创建点基线不上涨)。
- * 无宿主口 ⇒ 静默(print/headless 没屏可上,与壳原文 `if (!store) return` 同语义)。
- */
 function surfaceSelfClearingWarn(key, text, timeoutMs) {
     try {
         const s = surfaceForCurrentSession();
@@ -117,130 +52,43 @@ function surfaceSelfClearingWarn(key, text, timeoutMs) {
                 s.clearNoticeIfCurrent(key);
             }
             catch {
-                /* fail-soft */
             }
         }, timeoutMs);
         unrefTimer(timer);
     }
     catch {
-        /* fail-soft:上屏失败绝不再伤害它所依附的那条流 */
     }
 }
-// ── FIX① (2026-08-07) —— allow_session 的「记住了没有」诚实回执 ────────────────────────────────
-/** 文案(测试锁字面)。措辞刻意描述**后果**而不是内部机制:用户要知道的是「下次还会问」。 */
 export const REMEMBER_NOT_APPLIED_WARN_TEXT = 'this session-wide allow was not remembered by the worker — you will be asked again for this tool';
 const REMEMBER_NOT_APPLIED_KEY = 'hitl-remember-not-applied';
 const REMEMBER_NOT_APPLIED_TIMEOUT_MS = 10_000;
-/** 文案(测试锁字面)。"original" 是判据词:用户必须读到「跑的是原来那份」。 */
 export const EDIT_NOT_FORWARDED_WARN_TEXT = 'your edited tool input was NOT forwarded — the tool is running with the ORIGINAL input you saw before editing';
 const EDIT_NOT_FORWARDED_KEY = 'hitl-edit-not-forwarded';
-/** 比 remember 那条久:它说的是「正在跑的东西和你批的不是同一份」,值得多留一会儿。 */
 const EDIT_NOT_FORWARDED_TIMEOUT_MS = 20_000;
-/**
- * `allow_session` 决断的 ack 回报 `rememberApplied:false`(server 1.239 起诚实回显 —— 典型成因
- * 是这条 run 没有 sessionId,grant 无处可落)。
- *
- * 🔴 为什么这必须上屏而不是只记 debug:三选卡第 2 项在用户心里签的是「本会话这个工具不再问我」。
- * 记没落店而界面照渲「全放行」,就是**把一个没有发生的授权渲成发生了** —— 下一次弹卡时用户会以为
- * 是 bug,更坏的是他可能因此养成「一路回车」的习惯。缺席(旧 server 不出这个位)= 未知,
- * 按 [honest-absence-not-fabricated-zero] 一律不发通知,绝不把未知渲成失败。
- * 无宿主口(print/headless 没屏)⇒ 静默,与 {@link surfaceCancelDenyWarn} 同语义。
- */
 export function surfaceRememberNotApplied() {
     surfaceSelfClearingWarn(REMEMBER_NOT_APPLIED_KEY, REMEMBER_NOT_APPLIED_WARN_TEXT, REMEMBER_NOT_APPLIED_TIMEOUT_MS);
 }
-/**
- * 「编辑并批准」带了 `updatedInput`,而 ack 回报 `updatedInputForwarded:false`(server 1.241 起
- * 诚实回显)—— 引擎拿到的是**原始**入参。
- *
- * 🔴 这一条比 remember 那条严重一个量级,它是本批 对抗复审判的 [high]:用户在卡上把
- * `rm -rf /tmp/x` 改成 `rm -rf /tmp/x/build` 然后按了批准,而真正执行的是他改之前那条。
- * **事后没有 fail-closed 的余地**(allow 已经送达,工具已经在跑),所以唯一诚实的处置就是立刻
- * 响亮地说出来 —— 静默(此前只写 debug 日志)等于让用户以为自己的编辑生效了。
- * 上游的正位是让 server 在「带了 updatedInput 却转发不了」时 fail-closed 拒批;那属跨仓,
- * 已记进 docs/refactor/README.md 的宿主/上游工单表,本层不做旁路补偿(只做如实告知)。
- */
 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] 修):
- *  · 不写「这台引擎不支持」——能力位缺席有三种同形成因(宿主没接这个字段 / 探测还没回来 / 探测失败),
- *    其中只有明确的 `false` 才勉强算「引擎说了不」。写成断言就是替引擎宣布一件没证据的事
- *    ([honest-absence-not-fabricated-zero]);改成 `could not be confirmed` 的未知口径。
- *  · 「审批本身过了」这句**只在 respond 真成功之后**才成立 —— 所以本通知的**发出时机**被移到
- *    `await respond(...)` 成功之后(见 `toolApprovalWire` 的调用点顶注),而不是丢键那一刻。
- */
 export const RULE_NOT_SENT_WARN_TEXT = 'your "don\'t ask again" choice was NOT sent to this engine — support for that rule form could not be confirmed. The approval itself went through, but you will be asked again';
 const RULE_NOT_SENT_KEY = 'hitl-rule-arm-not-sent';
-/** 与 remember 那条同量级(都是「你以为记住了、其实没有」),取同一个时长。 */
 const RULE_NOT_SENT_TIMEOUT_MS = 10_000;
-/**
- * 卡上选中了「不再询问」(编辑臂的自由文本 / 批臂的合取批),而**这台引擎的能力位没有确认**
- * 那条兑付通道 ⇒ 编排层把持久臂整条丢掉、只送决断。
- *
- * 🔴 为什么这必须上屏而不是只记 debug(异源对抗复审三轮 [high] 采纳,0.43.0):它与
- * {@link surfaceRememberNotApplied} 是**同一个病**——用户按下了一个明确的意图,系统把它静默
- * 丢掉,然后下一次照旧弹卡。用户能得出的唯一结论是「这个功能坏了」或「我按错了」。卡上那一格
- * 是**真 affordance**(offer 确实在场、确实可以走本地落规则那条路),被丢的只是**这条 wire
- * 兑付通道** —— 所以正解不是把选项藏起来,是**如实说出来**。
- * 🔴 **一条通知服务两条臂**(同形清剿):编辑臂(`respondFreeFormRules` 位缺席)与批臂
- * (`respondBatchRuleOffers` 位缺席)此前都只写 debug —— 同一个病形两处存量,同批一起改。
- * 🔴 决断本身**不受影响**(照常送达),所以文案第二句说清「审批过了,只是规则没存」——
- * ⚠️ 正因为文案里有那句话,**调用时机必须在 `respond` 真成功之后**(异源对抗复审四轮 [medium]:
- * 丢键那一刻就发,而随后 respond 抛错 ⇒ 决断其实**没有**落定,用户却已经读到「审批过了」,
- * 可能按「工具已经在跑」继续操作)。调用点的时序契约见 `toolApprovalWire` 那一处。
- * 🔴 文案**不说「引擎不支持」**:能力位缺席三种同形成因(宿主没接字段 / 探测未回 / 探测失败),
- * 断言引擎的能力是没有证据的话 —— 用 `could not be confirmed` 的未知口径。
- * 无宿主口(print/headless 没屏)⇒ 静默,与本文件其余 surface 同语义。
- */
 export function surfaceRuleArmNotSent() {
     surfaceSelfClearingWarn(RULE_NOT_SENT_KEY, RULE_NOT_SENT_WARN_TEXT, RULE_NOT_SENT_TIMEOUT_MS);
 }
-/**
- * 文案(测试锁字面)。与 {@link RULE_NOT_SENT_WARN_TEXT} **刻意分两条**:两者对用户的下一步建议不同 ——
- * 那条说「这台引擎能不能收还不知道」(换台引擎/等探测就好了),本条说「你这次的选择**本身**没过
- * 客户端那道核对」(卡口实现有问题或同时给了两个互斥选择,换台引擎也不会变)。折成一条会让任一方
- * 谎报原因。措辞同样只说证得出的话:不猜是哪一种坏法,把两种都摆出来。
- */
 export const RULE_NOT_SENT_REJECTED_WARN_TEXT = 'your "don\'t ask again" choice was NOT sent — it did not pass the client-side check (the card returned a rule the engine never offered, an index that is not a batch offer, or two conflicting choices at once). The approval itself went through, but you will be asked again';
 const RULE_NOT_SENT_REJECTED_KEY = 'hitl-rule-arm-rejected';
 const RULE_NOT_SENT_REJECTED_TIMEOUT_MS = 10_000;
-/**
- * 卡上选中了「不再询问」,而那次选择**没过包内那道表核 / 互斥核**(报了引擎没 offer 过的文本、
- * 下标不指向 batch offer、或文本臂与批臂同场)⇒ 编排层把持久臂整条丢掉、只送决断。
- *
- * 🔴 为什么这也必须上屏(异源对抗复审十轮 [medium] 采纳,0.43.0):它与
- * {@link surfaceRuleArmNotSent} 是**同一个诚实性问题**,只是原因换了一个 —— 用户按下的明确意图
- * 被系统丢掉,审批照常成功,下次照旧弹卡。此前这三条丢键路径**只写 `hostLog('error')`**:
- * 那是给开发者看的诊断,**不是**给按下按钮的那个人的答复。
- * 🔴 **时序契约与那条一致**:文案里有「审批本身过了」⇒ 只在 `await respond(...)` 真成功之后发。
- * 🔴 **成因通常是卡口实现的 bug**(表外文本/坏下标/两臂同场都是宿主侧构造出来的),所以 `hostLog`
- * 的那条 `error` 留痕**照旧保留** —— 两个受众,两条通道,谁都不顶替谁。
- * 无宿主口(print/headless 没屏)⇒ 静默,与本文件其余 surface 同语义。
- */
 export function surfaceRuleArmRejected() {
     surfaceSelfClearingWarn(RULE_NOT_SENT_REJECTED_KEY, RULE_NOT_SENT_REJECTED_WARN_TEXT, RULE_NOT_SENT_REJECTED_TIMEOUT_MS);
 }
-/**
- * cancel-by-deny 的「良性 no_pending」判据。**结构化 `.code` 为主,`instanceof` 只作加强,绝不替代**:
- *  - `.code` 是 client-core 自家 `HitlSafetyError` 的契约属性(hitlBridge.ts,REF-CC-036 起是闭集
- *    联合 binding_mismatch|no_pending|wrong_gate|bad_plan_edit)—— 不是 SDK 错误的 `errorCode`;
- *  - 只按 `instanceof` 判会在**跨 realm / 双实例**下假阴:打包后同一个包出现两份副本(本仓
- *    `singleton-manifest.json` 把双实例当在册风险处理)、或宿主与包各持一份构造器时,同一个
- *    语义错误 `instanceof` 为假 ⇒ 良性 no_pending 被当成「deny 丢失」弹一行吓人的 warn;
- *  - 下游 `sema-cli` 的 `src/sema/hitlCancelDeny.test.ts` 用例 3 正是按 `code + name` 鸭子形造错,
- *    那份契约就是「结构判据」本身。
- * ⚠️ 判据不许松成「有 `.code` 就静默」—— 闭集里只有 `no_pending` 是良性,别的 code 照走 warn 臂。
- */
 function isNoPendingError(e) {
     if (e instanceof HitlSafetyError)
         return e.code === 'no_pending';
@@ -249,22 +97,6 @@ function isNoPendingError(e) {
     const code = e.code;
     return typeof code === 'string' && code === 'no_pending';
 }
-/**
- * 中断 deny 的有界观察(壳侧单测 `hitlCancelDeny.test.ts` 的被测面;REF-CC-023 起两条决断腿共用)。
- *
- * 🔴 **命名撤稿(0.42.0)**:函数名与日志里的「cancel-by-deny」是**历史词**,保留只为不打断下游
- * 按名锚的用例。它描述的动作在现行契约(server `ASSISTANT-WIRE-CONTRACT.md` §4a)下的准确说法是
- * 「**中断时把这只挂着的 ask 用一个 TOOL 级 deny 结算掉**,好让 run 不停在 suspended 上」——
- * **不是**「用 deny 去 cancel 一条 run」。方向也别读反:这里是把**用户的中断**结算成一次 deny,
- * 而 §4a 禁的是反向的那件事(把**用户的拒绝**译成 cancel),两者不是同一件事。
- *
- * 铁律:不 await 进 abort 返回路径(用户立即拿回控制);这里只管后台 settle 的«观察»:
- *   - 2s 内 settle 成功 ⇒ 零上屏(SEMA_DEBUG 记成功);
- *   - 失败/超时 ⇒ 上屏一行 warn + SEMA_DEBUG 记原因(deny 丢失 = run 卡 suspended,下一条消息
- *     撞 409;配合件2b 的专属文案,用户知道现场 + 出路);
- *   - `code === 'no_pending'`(判据见上方 `isNoPendingError`)⇒ 良性静默(pending 已被别处消解/
- *     过期 —— run 没锁;hitlBridge decideTool 的同款语义,那里的静默维持不动)。
- */
 export function observeCancelByDeny(settle, taskId) {
     let timer;
     const budget = new Promise((_, reject) => {
@@ -287,6 +119,5 @@ export function observeCancelByDeny(settle, taskId) {
         if (timer !== undefined)
             clearTimeout(timer);
     });
-    // 超时后原 promise 迟到 reject 不得变成 unhandledRejection。
     void settle.catch(() => { });
 }

package/dist/hitl/livePendingAsk.d.ts

@@ -1,53 +1,17 @@
-/**
- * livePendingAsk — 「悬挂的流内 ask」的三端共用读面与决断口(0.72.14)。
- *
- * ── 这个模块补的是哪一个缺口 ────────────────────────────────────────────────────────────────
- * 流内 ask 在铸造那一刻若没有活着的宿主流可投,引擎把它转成**悬挂**(窗约一小时,不补发、不重算),此后只在
- * `GET /v1/approvals` 回体的第二顶层键 `livePending` 里可发现。后台 workflow 的子代恒落这一形:宿主 turn 先结束,
- * 子代稍后才撞上审批门 ⇒ 用户面零帧零卡,代理静默卡到窗尽。本模块让端从 {@link startApprovalsFeed} 的快照里
- * 读到这些行、出带子代身份的卡、并经**与流内帧腿同一条链**决断。
- *
- * ── 🔴 四条读法 ────────────────────────────────────────────────────────────────────────────
- *  ① **键缺席 ≠ 没有悬挂 ask**:老引擎不发这个键 ⇒ `not_reported`;快照上键缺席,计数读 `null`(不知道),绝不铸 `[]` / `0`。
- *     🔴 CC-98 同一条纪律的第三态:feed 发的「这次取不到」臂(`kind:'unknown'`)喂进本模块三个口时,
- *     计数读 `null`、视图读空、跟踪器**零 delta**(绝不把「取不到」当成「行都消失了」去撤卡)。
- *  ② **数组名即路由判据**:`livePending` 行的决议口是 `POST /v1/tool-approvals/{approvalId}/respond`(流内审批那个口),
- *     **不是** durable 行的 decide 口;两数组不混编。幂等键 = `approvalId`(与流内帧同一个 id)。
- *  ③ **可选旗标 only-if-true**:`fromSubagent` / `governanceForced` / `requiresRealApproval` 缺席绝不编码成 `false`。
- *  ④ **行上没有工具入参**(引擎刻意不在这个读面开第二道脱敏面)⇒ 卡必须明说「看不到入参」,不许渲一个空命令冒充全貌。
- *
- * sdk 的 barrel 没有导出这一行的类型 ⇒ 按**结构**窄读(与 `capabilities.executionLane` 同一姿势),多余成员不过境。
- */
 import type { ApprovalsFeedEmission } 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;
-    /**
-     * 0.73.2(server ≥7.87.0):本来会 emit 的那只 `tool_approval` 帧(含入参 / 窗三键 / 规则报价 …)。在场 ⇒ 出**全卡**;
-     * 缺席(老 server)⇒ 盲卡(`argsUnavailable`)。只在帧判别器过 **且** `type === 'tool_approval'` **且** `frame.approvalId === approvalId` 时在场(否则坏形丢该位不丢行);
-     * 整只原样带出,帧腿自己逐键窄读。
-     */
     frame?: ToolApprovalFrame;
 }
-/**
- * `livePending` 段的三态读数。`malformed` = 键在场但读不懂(**不**折成 `not_reported`,也不折成空)。
- * 🔴 CC-98:`malformed` 含**非空数组却一行都读不出**那一形(见 {@link readLivePendingRows} 内的分界注);
- * **部分**坏行仍是 `present` + `dropped`。
- */
 export type LivePendingReading = {
     kind: 'not_reported';
 } | {
@@ -57,83 +21,28 @@ export type LivePendingReading = {
     rows: LivePendingAskView[];
     dropped: number;
 };
-/**
- * `GET /v1/approvals` 回体 → `livePending` 段读数。四必填位坏形的行丢弃并计数;同 `approvalId` 重复行留第一条。
- * 🔴 CC-98:**非空数组却一行都读不出** ⇒ `malformed`(不是 `present` + 空列表)——分界与理由见函数末那段注。
- */
 export declare function readLivePendingRows(body: unknown): LivePendingReading;
-/** 视图过滤:给了 `sessionId` ⇒ 只留该会话的行;行上没有 `sessionId` = 归不了属 ⇒ 不留(不替别的会话出卡)。 */
 export interface SuspendedAskFilter {
     sessionId?: string;
 }
-/** 快照里**出自子代**的悬挂 ask(宿主自己的流内 ask 走流内帧腿,不在这里出卡)。未报 / 没有快照 ⇒ `[]`。 */
 export declare function suspendedSubagentAsks(snapshot: ApprovalsFeedEmission | 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: ApprovalsFeedEmission | 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[];
-    /**
-     * 0.73.2:此前 appeared 过(当时无 `frame`,出的是盲卡)、这一张快照上 `frame` 到了的行(server 滚动升级到 ≥7.87.0 的中途形)。
-     * 🔴 包**不会**替换已出的盲卡(帧腿撤卡的唯一方式是给一个决断,那会把 ask 结算掉);端若有按 callKey 原地更新卡的能力就用它刷新
-     * 入参,否则让用户在盲卡上决定 —— 常态(7.87.0 起帧从第一张快照就在)不会走到这里。
-     */
     upgraded: LivePendingAskView[];
 }
 export interface SuspendedAskTracker {
-    /**
-     * 吞一张 feed 发布物。三种入参三句话:
-     *   · 真快照(`kind:'snapshot'`)⇒ 正常对账(appeared / gone / upgraded);
-     *   · 🔴 CC-98「这次取不到」(`kind:'unknown'`)⇒ **零 delta**,已出的卡一张都不撤;
-     *   · `null` / `undefined` ⇒ 由**调用方**声明「现在一条都看不到」(引擎换代 / 拆装配),按「列表空」对账 ⇒ 撤卡。
-     * 🔴 后两者是**两句话**,别当一回事:`kind:'unknown'` 说的是「**wire 这一眼没看成**」(包说的),
-     * `null` 说的是「**我这边现在没有可看的东西**」(端说的,典型 = 拆装配:卡已经没有决断口,留着才是骗人)。
-     * 取不到请把 unknown 臂**原样**喂进来,别自己转成 `null` —— 转一下就把「不知道」变成了「没有」。
-     * 🔴 第三种不完整:真快照带 `livePendingDropped > 0`(这一段有读不出来的行)⇒ 照报 `appeared` / `upgraded`,
-     * 但**不报 `gone`**(禁止缺席对账;那几行留在账上,等下一张完整快照再判)。
-     */
     ingest(snapshot: ApprovalsFeedEmission | 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;