@sema-agent/client-core 0.75.0 → 0.76.0

package/dist/hitl/approvalsFeed.js

@@ -5,6 +5,64 @@ import { readLivePendingRows } from './livePendingAsk.js';
  *  取 5 是为了让「偶发一拍畸形 payload」不误判(单次逃逸下一拍就归零),同时不让一条永远抛的腿
  *  无限期地对着端的自检假装自己还活着。 */
 const MAX_CONSECUTIVE_POLL_ESCAPES = 5;
+/**
+ * 🔴 CC-98(异源复审 R2 [medium] 采修)`pending` 段的**结构窄读**。
+ *
+ * 修前这一段一个字都没校验:摘要函数对缺键一律 `?? ''`,于是 `{pending:[{}]}` / `{pending:[7]}` /
+ * `{pending:{map:()=>[]}}` 这类回体会被当成**合形真快照**发出去,端照着它渲一个确定的数字
+ * (`durable: 1`)—— 与「取不到渲成没有」同一个病形的镜像:**读不懂渲成读懂了**。
+ *
+ * 三分界与 `livePending` 段逐字同:
+ *   · 不是数组 ⇒ `malformed`(整次不提交、发「不知道」);
+ *   · **非空数组却一行都读不出** ⇒ `malformed`(不许答「有 0 条」);
+ *   · **部分**行读不出 ⇒ 逐条丢 + `present` + `dropped`(读得出的行是真的;`dropped` 上快照,
+ *     计数口据此把 durable 格答 `null`);空数组 ⇒ `present`(引擎明说一条都没有)。
+ *
+ * 一行的**最低可读位** = 非空串 `sessionId`:它就是决断口(`POST /v1/approvals/:sessionId/decide`)的钥匙,
+ * 也是按会话过滤计数的键;没有它这一行既决断不了也归不了属。`scope`(sdk 型面上也是必填)**刻意不要求** ——
+ * 缺它的行仍然决断得了,fail-safe 方向是留行不是丢行(丢一行 = 一条等人的审批在端上消失)。
+ */
+function readDurablePendingRows(raw) {
+    if (!Array.isArray(raw))
+        return { kind: 'malformed' };
+    const rows = [];
+    let dropped = 0;
+    for (const item of raw) {
+        if (item === null || typeof item !== 'object' || Array.isArray(item)) {
+            dropped++;
+            continue;
+        }
+        const sid = item.sessionId;
+        if (typeof sid !== 'string' || sid === '') {
+            dropped++;
+            continue;
+        }
+        rows.push(item);
+    }
+    if (raw.length > 0 && rows.length === 0)
+        return { kind: 'malformed' };
+    return { kind: 'present', rows, dropped };
+}
+/**
+ * 🔴 CC-98(异源复审 R3 [medium] 采修)**「修前这一形会不会让回调体逃逸」的判据 —— 真去算一遍修前那个摘要**。
+ *
+ * 为什么不许猜:逃逸是 [2393] hitl-F5 **熔断**的输入(连续 5 次 ⇒ `mode` 诚实转 idle),本车不许悄悄把它拿掉。
+ * 上一版在读器里手列了「整段不是数组 / 行里有 null」两形当作逃逸形 —— 一条普通 JSON 就能证伪:
+ * `{"pending":[{"sessionId":{"toString":null}}]}` 在修前是 `Array.join` 做字符串转换时抛 TypeError(逃逸),
+ * 而手列的两形认不出它 ⇒ 持续坏回体不再触发 F5。⇒ 判据换成**行为等价**:把原摘要在原始值上真算一遍,
+ * 抛了就是逃逸形。这样「逐字保留」是被**执行**出来的,不是被声明出来的。
+ *
+ * 只在坏形路上算(多算一次字符串拼接,常态零成本);本函数自己**绝不**抛。
+ */
+function baselineDurableDigestThrows(raw) {
+    try {
+        durableDigestOf(raw);
+        return false;
+    }
+    catch {
+        return true;
+    }
+}
 /**
  * pending 列表的稳定摘要 —— 只在**内容变了**的时候发快照。
  * 键里带 `boundInputHash`:同一条 pending 的绑定被服务端换掉(TOCTOU 场景)也算变化,
@@ -24,7 +82,12 @@ const LIVE_SECTION_SEP = String.fromCharCode(3);
  * 0.72.14:流内 ask 段进摘要 —— 此前只算 `pending`,悬挂 ask 出现 / 消失都不触发快照。
  * 「未报」与「报了且为空」是两个不同的事实(前者读不出计数),摘要上也分开。
  */
-function digestOf(rows, live) {
+function digestOf(rows, live, 
+/** CC-98:读不出的行数也进摘要 —— 读得懂的那几行没变、但「另有几行读不懂」变了,同样是消费端要知道的变化
+ *  (不进摘要 ⇒ 不发快照 ⇒ 端手上那面「不完整」旗永远是上一拍的)。 */
+dropped = 0, 
+/** CC-98:`pending` 段读不出的行数(同理进摘要)。 */
+droppedDurable = 0) {
     const liveDigest = live === undefined
         ? 'absent'
         : live
@@ -32,11 +95,15 @@ function digestOf(rows, live) {
             .map(r => [r.approvalId, r.toolName, String(r.expiresAtMs), r.sessionId ?? '', r.originTaskId ?? '', r.frame !== undefined ? 'f' : ''].join(LIVE_FIELD_SEP))
             .sort()
             .join(LIVE_ROW_SEP);
-    return `${durableDigestOf(rows)}${LIVE_SECTION_SEP}${liveDigest}`;
+    return `${durableDigestOf(rows)}${LIVE_SECTION_SEP}${liveDigest}${LIVE_SECTION_SEP}${dropped}${LIVE_SECTION_SEP}${droppedDurable}`;
 }
 /**
  * 起一条 pending-approvals feed。**幂等性归调用方**:一个 client 起一条就够了,起两条 =
  * 两倍取件(不是错误,但没意义)。
+ *
+ * 🔴 CC-98 订阅口收**两臂**({@link ApprovalsFeedEmission}):真快照(`kind:'snapshot'`)与
+ * 「这次取不到」({@link ApprovalsFeedUnknownSnapshot},`kind:'unknown'`)。先判 `kind` 再读别的键 ——
+ * 把 unknown 臂当成一张空列表就是把「不知道」渲成「没有」。三态的拉面读口是 `reading()`。
  */
 export function startApprovalsFeed(client, onSnapshot, opts) {
     const pollIntervalMs = opts?.pollIntervalMs ?? 5000;
@@ -52,8 +119,22 @@ export function startApprovalsFeed(client, onSnapshot, opts) {
     let mode = client.approvals.stream ? 'push' : 'poll';
     let stopped = false;
     let revision = 0;
+    /**
+     * 🔴 CC-98(异源复审 R1 [medium] 采修):**内容**变化计数 —— 只在摘要真的变了时 +1。
+     * 对账节拍的退避判据(「取件后快照没变 ⇒ 间隔翻倍」)用本位,**不用** `revision`:后者现在还会为
+     * 「恢复必发」+1(内容一字未变),拿它判退避就等于每次间歇失败都把节拍无故拉回基础间隔 ——
+     * 那是把本车不该动的 KL-15 面动了。两个计数分开之后,对账退避逐字与 0.75.0 同。
+     */
+    let contentRevision = 0;
     let lastDigest = null;
     let last = null;
+    /**
+     * CC-98:「现在取不到」的粘性态(null = 不盲)。两处承重:
+     *   ① `reading()` 的第三态;
+     *   ② **恢复必发**的判据 —— 只要它非空,下一次提交就算摘要与失败前一字不差也要发一张真快照
+     *      (否则端永远停在「不知道」)。真快照落地即清。
+     */
+    let blind = null;
     let pollTimer;
     let retryTimer;
     /** [2393] hitl-F5:连续「回调体抛出」的次数(一次跑完就归零)——见 `schedulePoll` 的 catch 臂。 */
@@ -70,6 +151,7 @@ export function startApprovalsFeed(client, onSnapshot, opts) {
     let lastObservedSeq = 0;
     const stats = {
         pushEvents: 0, heartbeats: 0, polls: 0, listErrors: 0, streamFailures: 0, snapshots: 0, reconciles: 0, pushTakeRetries: 0,
+        unknowns: 0,
     };
     /** 域词表-14 收编:「怎么调 unref」的单一实现见 unrefTimer.ts,本函数只是就地起个短名。 */
     function arm(t) {
@@ -127,7 +209,13 @@ export function startApprovalsFeed(client, onSnapshot, opts) {
         pushTakeRetryDelayMs = pushTakeRetryBaseMs;
     }
     function noteTakeMissed(via, seq) {
-        if (via !== 'push' || pushTakeRetryBaseMs <= 0)
+        // 🔴 CC-98(异源复审 R2 [high] 采修)原条件是「只在 push 腿记账 —— 轮询模式下轮询腿自己会再来」。
+        // 那条**前提**在当前模式已经是 push 时不成立:重连那一拍把 `pollTimer` 清了、也不再续排,
+        // 于是一发**轮询腿的**失败(典型:重连那一刻还在途的那一拍)之后再没有任何人来取件 ——
+        // 「不知道」没人清([paired-mechanisms-must-share-premise]:配对机制必须共享前提)。
+        // ⇒ 条件放宽成「这一发是 push 腿 **或** 现在是 push 模式」。纯轮询模式(两者都是 poll)一字不变:
+        // 轮询腿的下一拍照旧自己会来,不额外记账、不额外流量。
+        if ((via !== 'push' && mode !== 'push') || pushTakeRetryBaseMs <= 0)
             return;
         if (seq < lastLookedSeq)
             return; // 更晚发起的一眼已经看成 ⇒ 这次迟到的失败不欠
@@ -151,6 +239,41 @@ export function startApprovalsFeed(client, onSnapshot, opts) {
             });
         }, delay));
     }
+    /**
+     * CC-98:发一张「不知道」。三条纪律:
+     *  ① **乱序闸与真快照共用一条**:比「已观察到的最新一号」更早发起的失败,其结论已被后发者取代 ⇒
+     *     一个字节都不发(一发迟到的 404 不许把一发更晚发起的成功盖成「不知道」);发得出去就同样推进那一号。
+     *  ② **一段只发一张**(与「内容没变 ⇒ 不打扰订阅者」同一条纪律):同一成因连着失败不重复发,
+     *     `stats.listErrors` 照旧逐次记;成因变了(抛 ⇄ 读不懂)是两句话 ⇒ 再发一张。
+     *  ③ 与**重试 / 退避 / 熔断解耦**:发过「不知道」之后欠账重试照旧排、轮询腿照旧续排、
+     *     F5 的连续逃逸照旧计数 —— 本臂只说「现在不知道」,不说「不再试了」。
+     */
+    function publishUnknown(why, via, seq) {
+        if (stopped || ac.signal.aborted)
+            return;
+        // 🔴 CC-98 **失败路只过发起序号闸,不过腿代际闸**(异源复审 R2 [high] 纠 R1 的修法 —— 上一版在这里加了
+        // 一道代际闸,换来的是另一半谎:退役腿的失败被整份吞掉,而没有任何**更新的**结论取代它 ⇒ 端继续
+        // 读到 `present` 和一个确定的数字,而最近一次取件其实失败了)。
+        // 判据只能是「有没有更晚发起的结论已经落地」= 序号;**腿换代不是那件事的证据**(重连只说明推面活了,
+        // 不说明有人重新取过件)。「那条退役的腿不会再来一拍」这件事由 `noteTakeMissed` 负责(见其头注)。
+        if (seq < lastObservedSeq) {
+            hostLog('debug', `approvalsFeed: dropping out-of-order failure #${seq} (newest observed #${lastObservedSeq}) — view untouched`);
+            return;
+        }
+        lastObservedSeq = seq;
+        if (blind !== null && blind.why === why)
+            return;
+        const at = Date.now();
+        blind = { why, at };
+        stats.unknowns++;
+        try {
+            onSnapshot({ kind: 'unknown', why, at, mode: via });
+        }
+        catch (e) {
+            // 订阅者抛错绝不能把 feed 打死(与真快照臂同款纪律)。
+            hostLog('debug', `approvalsFeed: subscriber threw on the unknown arm (swallowed): ${String(e)}`);
+        }
+    }
     async function take(via, 
     /** [F4957-1 二审] 发起这次取件时的轮询代际(只有轮询腿传;push/refresh 不受代际管)。 */
     leg) {
@@ -159,9 +282,29 @@ export function startApprovalsFeed(client, onSnapshot, opts) {
         const seq = ++takeSeq;
         let rows;
         let live;
+        /** CC-98:`livePending` 段里读不出来的行数(0 = 这一段完整)。见 `ApprovalsFeedSnapshot.livePendingDropped`。 */
+        let dropped = 0;
+        /** CC-98:`pending` 段里读不出来的行数(0 = 这一段完整)。见 `ApprovalsFeedSnapshot.pendingDropped`。 */
+        let droppedDurable = 0;
+        // 🔴 CC-98 两段 try 是**刻意**分开的,不是洁癖:「没拿到」(取件自己抛 / reject)与「拿到了但不敢信」
+        // (回体不是对象 / 键坏形)是两句话,`why` 要分得清 —— 合成一段的话一只 `null` 回体会被报成
+        // 「取件失败」,宿主的提示文案与自检口径都会指错方向。两段的处置完全一致(记 listErrors、记欠账、
+        // 发一张「不知道」、整次不提交),只有成因词不同。
+        let body;
+        try {
+            body = await client.approvals.list({ signal: ac.signal });
+        }
+        catch (e) {
+            stats.listErrors++;
+            hostLog('debug', `approvalsFeed: list() failed (${via} leg): ${String(e)}`);
+            noteTakeMissed(via, seq);
+            publishUnknown('list_threw', via, seq); // 🔴 CC-98:失败也要有出口,不说 = 端拿上一张当现在
+            return;
+        }
+        /** CC-98:`pending` 段的原始值。**在 try 里取**(回体是 `null` / 取键 getter 抛 ⇒ 与修前同档:不逃逸)。 */
+        let rawPending;
         try {
-            const body = await client.approvals.list({ signal: ac.signal });
-            rows = body.pending;
+            rawPending = body.pending;
             // 0.72.14:`livePending` 段按结构窄读。键在场却读不懂 ⇒ **整次取件不提交**(保留上一张快照):
             // 把「读不懂」提交成「未报 / 为空」会让端撤掉一张还在等人的卡。
             const reading = readLivePendingRows(body);
@@ -169,20 +312,60 @@ export function startApprovalsFeed(client, onSnapshot, opts) {
                 stats.listErrors++;
                 hostLog('debug', `approvalsFeed: list() body has an unreadable livePending section (${via} leg) — snapshot not committed`);
                 noteTakeMissed(via, seq);
+                // 🔴 CC-98:视图不提交,但**必须说一声** —— 不说 = 端继续拿上一张当现在(把「读不懂」渲成「没有」)。
+                publishUnknown('unreadable_payload', via, seq);
                 return;
             }
             if (reading.kind === 'present') {
                 live = reading.rows;
+                dropped = reading.dropped;
                 if (reading.dropped > 0)
-                    hostLog('debug', `approvalsFeed: dropped ${reading.dropped} malformed livePending row(s)`);
+                    hostLog('debug', `approvalsFeed: dropped ${reading.dropped} malformed livePending row(s) — snapshot carries livePendingDropped`);
             }
         }
         catch (e) {
+            // 回体本身读不出(`null` / 非对象 / `pending` 位是个会抛的 getter)—— 与上一段同档处置,成因不同。
             stats.listErrors++;
-            hostLog('debug', `approvalsFeed: list() failed (${via} leg): ${String(e)}`);
+            hostLog('debug', `approvalsFeed: list() body unreadable (${via} leg): ${String(e)}`);
             noteTakeMissed(via, seq);
+            publishUnknown('unreadable_payload', via, seq);
             return;
         }
+        // ── 🔴 CC-98 第三段:`pending` 段按结构窄读(见 readDurablePendingRows 头注:修前一个字都没校验)。
+        //    刻意排在上面那个 try **之外** —— 「逃逸形照旧逃出 take()」是 F5 熔断的输入,包在 try 里就等于
+        //    悄悄把熔断拿掉了(实测:第一版包在里面,F5 门当场从「连续逃逸转 idle」变成永远 poll)。
+        {
+            let durableRead;
+            try {
+                durableRead = readDurablePendingRows(rawPending);
+            }
+            catch {
+                // 载体上的 getter / 撤销过的 Proxy 抛 ⇒ 判 malformed;**是不是逃逸形**由下面那条行为等价判据答
+                // (同一份原始值上原摘要同样会抛 ⇒ 照旧逃),不在这里猜。
+                durableRead = { kind: 'malformed' };
+            }
+            // 🔴 F5 输入逐字保留的判据(见 baselineDurableDigestThrows 头注):**只在坏形路上**问一次
+            // 「修前那个摘要会不会在这份原始值上抛」。抛 ⇒ 这一形修前是逃逸的,照旧逃(整次不交,连半程都不交);
+            // 不抛 ⇒ 修前是**静默发布**成确定数字的那几形,现在改判「不知道」并 return。
+            const badDurable = durableRead.kind === 'malformed' || durableRead.dropped > 0;
+            const escapes = badDurable && baselineDurableDigestThrows(rawPending);
+            if (durableRead.kind === 'malformed' || escapes) {
+                hostLog('debug', `approvalsFeed: list() body has an unreadable pending section (${via} leg) — snapshot not committed`);
+                // 修前静默发布的那几形现在与 `livePending` 段同档:记一次取件失败。修前**逃逸**的那几形不记
+                // —— 它们走下面那条 throw(修前也不记,`listErrors` 的账逐字同)。
+                if (!escapes)
+                    stats.listErrors++;
+                noteTakeMissed(via, seq);
+                publishUnknown('unreadable_payload', via, seq);
+                if (escapes)
+                    throw new TypeError('approvalsFeed: unreadable pending section (baseline digest would have thrown)');
+                return;
+            }
+            rows = durableRead.rows;
+            droppedDurable = durableRead.dropped;
+            if (durableRead.dropped > 0)
+                hostLog('debug', `approvalsFeed: dropped ${durableRead.dropped} malformed pending row(s) — snapshot carries pendingDropped`);
+        }
         if (stopped)
             return;
         // 🔴 摘要排在销账**之前**:回体坏形(例:`pending` 不是数组)会让它抛出、整次取件逃逸(各调用点自己接盘,
@@ -190,24 +373,36 @@ export function startApprovalsFeed(client, onSnapshot, opts) {
         // 逃逸本身也是「没看成」:在**这里**统一记欠账再原样抛出,四个调用点(起手 / 事件 / refresh / 重试)不必各记各的。
         let d;
         try {
-            d = digestOf(rows, live);
+            d = digestOf(rows, live, dropped, droppedDurable);
         }
         catch (e) {
             noteTakeMissed(via, seq);
+            // 🔴 CC-98:逃逸(`pending` 不是数组 / 行畸形)同样是「这次取不到」—— 先发臂再原样抛出,
+            // 免得四个调用点(起手 / 事件 / refresh / 重试)各自去猜该不该通知端。
+            publishUnknown('unreadable_payload', via, seq);
             throw e;
         }
-        // 看成了(回体读得懂)⇒ 销掉**更早发起**的欠账(判据在发起序号上,见 noteTakeLooked;与下面两道提交闸无关:
-        // 销账问的是「失败之后有没有人再看过」,提交闸问的是「这份结论还新不新」)。
+        // 🔴 CC-98(异源复审 R3 [high] 采修)**代际闸排在销账之前**。原注说「销账与提交闸无关」——
+        // 那句话只对**序号闸**成立(被序号闸丢掉 = 有更晚的结论已经落地 ⇒ 视图是新的 ⇒ 确实不欠了);
+        // 对**代际闸**不成立:那份结论被整份丢掉、没有任何东西取代它,端手上什么都没更新 ——
+        // 拿它去销账 = 让「谁来补这一眼」这件事凭空消失(实复现:较晚的成功先被丢掉、较早的失败随后发布
+        // 「不知道」,而欠账因 `seq < lastLookedSeq` 不记 ⇒ 没人再取件 ⇒ 永久粘住)。
+        // 两句话合成一条纪律:**只有真的改变了端手上那份视图、或被更新的结论取代的取件,才算「有人看过」**。
+        if (leg !== undefined && leg !== pollLeg && blind === null) {
+            hostLog('debug', `approvalsFeed: dropping stale poll snapshot from leg ${leg} (current ${pollLeg}) — debt untouched`);
+            return;
+        }
+        // 看成了(回体读得懂)⇒ 销掉**更早发起**的欠账(判据在发起序号上,见 noteTakeLooked;与**序号**闸无关:
+        // 销账问的是「失败之后有没有人再看过」,序号闸问的是「这份结论还新不新」)。
         noteTakeLooked(seq);
         // 🔴 [F4957-1 二审 finding②] 代际闸必须排在**提交之前**:下面四行(lastDigest / revision /
         // last / onSnapshot)一落,视图就已经被改了 —— 守卫排在 take() 之外只挡得住计数与续排,挡不住
         // 回滚。乱序是真的会发生的:旧 poll 在途 → push 重连并发布新快照 → 旧 poll 才带着**更老**的
         // 结果返回 ⇒ 端拿到一张 revision 更高、内容更旧的 `mode:'poll'` 快照(刚出现的待审批被抹掉,
         // 或刚解决的又冒回来)。过期的结论一个字节都不提交。
-        if (leg !== undefined && leg !== pollLeg) {
-            hostLog('debug', `approvalsFeed: dropping stale poll snapshot from leg ${leg} (current ${pollLeg})`);
-            return;
-        }
+        // (代际闸已上移到销账之前 —— 见上面那段 R3 [high] 采修的头注。**盲着时让位**的理由照旧:
+        //  `blind !== null` 时让位给序号闸,否则旧腿那份读得懂的结论被丢掉、blind 没人清 ⇒ 永久粘住;
+        //  让位是安全的,乱序本来就由序号闸守。)
         // 🔴 [F4957-1 三审 finding②] 乱序闸(三条取件路径共用):比「已观察到的最新一号」更早发起的
         // 响应,其结论已经被后发者的结论取代 —— 一个字节都不提交。`refresh()` 不带代际,单靠上面那道
         // 闸盖不住它(端上「用户点了刷新」正是最容易与 push 重取撞车的那一发)。
@@ -216,11 +411,27 @@ export function startApprovalsFeed(client, onSnapshot, opts) {
             return;
         }
         lastObservedSeq = seq;
-        if (d === lastDigest)
+        // 🔴 CC-98 **恢复路**:上一次发布是「不知道」⇒ 即使摘要与失败前一字不差也必须发一张真快照。
+        // 少了这一条(修前的形):失败期间内容没变 ⇒ 摘要相等 ⇒ 这里 return ⇒ 「又能取到了、而且还是那 N 条」
+        // 这件事没有任何出口,端永远停在「不知道」。
+        const recovering = blind !== null;
+        const contentChanged = d !== lastDigest;
+        if (!contentChanged && !recovering)
             return; // 内容没变 ⇒ 不打扰订阅者
+        blind = null;
+        if (contentChanged)
+            contentRevision++; // 对账退避只认**内容**变化(见 contentRevision 头注)
         lastDigest = d;
         revision++;
-        const snap = { pending: rows, ...(live !== undefined ? { livePending: live } : {}), mode: via, revision };
+        const snap = {
+            kind: 'snapshot',
+            pending: rows,
+            ...(live !== undefined ? { livePending: live } : {}),
+            ...(dropped > 0 ? { livePendingDropped: dropped } : {}),
+            ...(droppedDurable > 0 ? { pendingDropped: droppedDurable } : {}),
+            mode: via,
+            revision,
+        };
         last = snap;
         stats.snapshots++;
         try {
@@ -340,10 +551,10 @@ export function startApprovalsFeed(client, onSnapshot, opts) {
                 return;
             }
             void (async () => {
-                const before = revision;
+                const before = contentRevision; // 🔴 CC-98:退避判据是**内容**变化,不是发布次数(恢复必发也发布)
                 stats.reconciles++;
                 await take('poll');
-                reconcileDelayMs = revision !== before ? reconcileBaseMs : Math.min(reconcileDelayMs * 2, reconcileMaxMs);
+                reconcileDelayMs = contentRevision !== before ? reconcileBaseMs : Math.min(reconcileDelayMs * 2, reconcileMaxMs);
             })()
                 .catch(e => {
                 hostLog('debug', `approvalsFeed: reconcile tick threw unexpectedly (take() should have self-caught): ${String(e)}`);
@@ -480,6 +691,11 @@ export function startApprovalsFeed(client, onSnapshot, opts) {
         mode: () => mode,
         stats: () => ({ ...stats }),
         snapshot: () => last,
+        reading: () => blind !== null
+            ? { kind: 'unknown', why: blind.why, at: blind.at }
+            : last !== null
+                ? { kind: 'present', snapshot: last }
+                : { kind: 'unobserved' },
         refresh: () => take(mode === 'push' ? 'push' : 'poll'),
     };
 }

package/dist/hitl/livePendingAsk.d.ts

@@ -9,6 +9,8 @@
  *
  * ── 🔴 四条读法 ────────────────────────────────────────────────────────────────────────────
  *  ① **键缺席 ≠ 没有悬挂 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`。
@@ -16,7 +18,7 @@
  *
  * sdk 的 barrel 没有导出这一行的类型 ⇒ 按**结构**窄读(与 `capabilities.executionLane` 同一姿势),多余成员不过境。
  */
-import type { ApprovalsFeedSnapshot } from './approvalsFeed.js';
+import type { ApprovalsFeedEmission } from './approvalsFeed.js';
 import { type RespondToolApprovalFn, type ToolApprovalFrame, type ToolApprovalFrameLaneOpts, type ToolApprovalFrameOutcome } from './toolApprovalWire.js';
 /** 一条悬挂的流内 ask(窄读后的形;键集即全部)。 */
 export interface LivePendingAskView {
@@ -41,7 +43,11 @@ export interface LivePendingAskView {
      */
     frame?: ToolApprovalFrame;
 }
-/** `livePending` 段的三态读数。`malformed` = 键在场但读不懂(**不**折成 `not_reported`,也不折成空)。 */
+/**
+ * `livePending` 段的三态读数。`malformed` = 键在场但读不懂(**不**折成 `not_reported`,也不折成空)。
+ * 🔴 CC-98:`malformed` 含**非空数组却一行都读不出**那一形(见 {@link readLivePendingRows} 内的分界注);
+ * **部分**坏行仍是 `present` + `dropped`。
+ */
 export type LivePendingReading = {
     kind: 'not_reported';
 } | {
@@ -51,14 +57,17 @@ export type LivePendingReading = {
     rows: LivePendingAskView[];
     dropped: number;
 };
-/** `GET /v1/approvals` 回体 → `livePending` 段读数。四必填位坏形的行丢弃并计数;同 `approvalId` 重复行留第一条。 */
+/**
+ * `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: ApprovalsFeedSnapshot | null | undefined, filter?: SuspendedAskFilter): LivePendingAskView[];
+export declare function suspendedSubagentAsks(snapshot: ApprovalsFeedEmission | null | undefined, filter?: SuspendedAskFilter): LivePendingAskView[];
 /** 「在等人决定」的计数。`null` = 不知道(没有快照 / 引擎没报这一段),**不是** 0。 */
 export interface ApprovalsAwaitingDecisionCount {
     /** durable 停驻行数。 */
@@ -68,7 +77,7 @@ export interface ApprovalsAwaitingDecisionCount {
     /** 其中出自子代的行数。 */
     suspendedSubagent: number | null;
 }
-export declare function countApprovalsAwaitingDecision(snapshot: ApprovalsFeedSnapshot | null | undefined, filter?: SuspendedAskFilter): ApprovalsAwaitingDecisionCount;
+export declare function countApprovalsAwaitingDecision(snapshot: ApprovalsFeedEmission | null | undefined, filter?: SuspendedAskFilter): ApprovalsAwaitingDecisionCount;
 /**
  * 悬挂行 → 流内帧腿的输入。只带行上**真有**的位:窗三键不带(行上只有绝对死线,没有出帧时刻,凑不出可校偏的窗),
  * `args` 不带(行上没有)。`sourceTaskId` = `originTaskId`(卡头子代身份徽章的来源)。
@@ -95,7 +104,18 @@ export interface SuspendedAskDelta {
     upgraded: LivePendingAskView[];
 }
 export interface SuspendedAskTracker {
-    ingest(snapshot: ApprovalsFeedSnapshot | null | undefined): SuspendedAskDelta;
+    /**
+     * 吞一张 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 只有一张卡、一次决断)。

package/dist/hitl/livePendingAsk.js

@@ -9,6 +9,8 @@
  *
  * ── 🔴 四条读法 ────────────────────────────────────────────────────────────────────────────
  *  ① **键缺席 ≠ 没有悬挂 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`。
@@ -23,7 +25,10 @@ function nonEmptyString(v) {
 function nonNegativeFinite(v) {
     return typeof v === 'number' && Number.isFinite(v) && v >= 0;
 }
-/** `GET /v1/approvals` 回体 → `livePending` 段读数。四必填位坏形的行丢弃并计数;同 `approvalId` 重复行留第一条。 */
+/**
+ * `GET /v1/approvals` 回体 → `livePending` 段读数。四必填位坏形的行丢弃并计数;同 `approvalId` 重复行留第一条。
+ * 🔴 CC-98:**非空数组却一行都读不出** ⇒ `malformed`(不是 `present` + 空列表)——分界与理由见函数末那段注。
+ */
 export function readLivePendingRows(body) {
     if (body === null || typeof body !== 'object' || Array.isArray(body))
         return { kind: 'malformed' };
@@ -66,10 +71,22 @@ export function readLivePendingRows(body) {
             ...(isToolApprovalFrame(o.frame) && o.frame.type === 'tool_approval' && o.frame.approvalId === o.approvalId ? { frame: o.frame } : {}),
         });
     }
+    // 🔴 CC-98 **分界**(主会话裁定):**非空数组、却一行都读不出来** ⇒ 判 `malformed`(= 这一眼没看成)。
+    // 不许答 `present` + 空列表 —— 那是把「取不到」冒充「一条都没有」,与 `list()` 抛是同一个病形,
+    // 只是换了个入口(端照着它渲「0 条在等你」,而引擎明明报了 N 行)。
+    // 分界的另一半照旧:**部分**坏行逐条丢 + `present`(与 server 的逐行律同形 —— 读得出来的行是真的,
+    // 丢掉那几条由 `dropped` 如实交代,不因为一条坏行就把整段作废)。
+    // 🔴 空数组**不在**本条射程:`[]` 是引擎明说「一条都没有」,恒 `present`(这正是要守住的那一态)。
+    if (raw.length > 0 && rows.length === 0)
+        return { kind: 'malformed' };
     return { kind: 'present', rows, dropped };
 }
 /** 快照里**出自子代**的悬挂 ask(宿主自己的流内 ask 走流内帧腿,不在这里出卡)。未报 / 没有快照 ⇒ `[]`。 */
 export function suspendedSubagentAsks(snapshot, filter) {
+    // CC-98:「这次取不到」⇒ 手上没有行,出不了卡。但这**不是**「一条都没有」——
+    // 计数口答 `null`、跟踪器零 delta(见下面两处),端别拿本函数的空数组当「没有悬挂 ask」的证据。
+    if (snapshot?.kind === 'unknown')
+        return [];
     const rows = snapshot?.livePending;
     if (!Array.isArray(rows))
         return [];
@@ -78,10 +95,20 @@ export function suspendedSubagentAsks(snapshot, filter) {
 export function countApprovalsAwaitingDecision(snapshot, filter) {
     if (snapshot === null || snapshot === undefined)
         return { durable: null, live: null, suspendedSubagent: null };
+    // 🔴 CC-98:「这次取不到」与「没有快照」同一档 —— 三格全 `null`(不知道),绝不折成 0。
+    // 底栏 / 页脚据此渲破折号;渲 0 = 告诉用户「没人在等你」,而真相是这一眼没看成。
+    if (snapshot.kind === 'unknown')
+        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;
+    // 🔴 CC-98:`pending` 段有读不出来的行(`pendingDropped > 0`)⇒ durable 格答 `null`(不知道确切数)。
+    const durable = (snapshot.pendingDropped ?? 0) > 0 ? null : Array.isArray(snapshot.pending) ? bySession(snapshot.pending).length : null;
     if (!Array.isArray(snapshot.livePending))
         return { durable, live: null, suspendedSubagent: null };
+    // 🔴 CC-98(异源复审 R1 [high] 采修):这一段有**读不出来的行** ⇒ 流内两格答 `null`(不知道确切数)。
+    // 引擎照旧在报那几行,只是这一拍读不懂 —— 拿读得懂的那几条报精确数 = 「0 条在等你」而其实有人在等
+    // (与「取不到渲成没有」同一个病形,只是小一号)。durable 段不受影响,它自己读得出来。
+    if ((snapshot.livePendingDropped ?? 0) > 0)
+        return { durable, live: null, suspendedSubagent: null };
     const live = bySession(snapshot.livePending);
     return { durable, live: live.length, suspendedSubagent: live.filter(r => r.fromSubagent === true).length };
 }
@@ -153,6 +180,11 @@ export function createSuspendedAskTracker(filter) {
     };
     return {
         ingest(snapshot) {
+            // 🔴 CC-98:「这次取不到」是**零信息**,不是「行都消失了」⇒ 零 delta。
+            // 走下面那条路的后果:`rows` 空 ⇒ 全部 shown 行进 `gone` ⇒ 屏上还在等人的卡被撤掉,
+            // 而那只 ask 在引擎上照旧挂着、照旧没人答 —— 「取不到当成没有」最坏的一形。
+            if (snapshot?.kind === 'unknown')
+                return { appeared: [], gone: [], upgraded: [] };
             const rows = suspendedSubagentAsks(snapshot, filter);
             const present = new Set(rows.map(r => r.approvalId));
             const appeared = [];
@@ -174,18 +206,26 @@ export function createSuspendedAskTracker(filter) {
                     shownWithFrame.add(r.approvalId);
                 appeared.push(r);
             }
+            // 🔴 CC-98(异源复审 R1 [high] 采修):这一张快照里有**读不出来的行**(`livePendingDropped > 0`)⇒
+            // **禁止缺席对账**:一行「不在列表里」可能只是这一拍读不懂,引擎照旧在报它。据此撤卡 =
+            // 把一张还在等人的卡撤掉,而 ask 在引擎上照旧挂着没人答(「取不到当成没有」最坏的一形)。
+            // 新出现的可读行照旧出卡(`appeared`)、补帧照旧升级(`upgraded`)—— 只有「消失」这一句话不许说。
+            // 账**不清**:那几行还留在 `shown` 里,等下一张**完整**的快照再判 gone(撤卡延后,不是丢掉)。
+            const incomplete = snapshot !== null && snapshot !== undefined && (snapshot.livePendingDropped ?? 0) > 0;
             const gone = [];
-            for (const id of [...shown]) {
-                if (present.has(id))
-                    continue;
-                shown.delete(id);
-                shownWithFrame.delete(id);
-                gone.push(id);
+            if (!incomplete) {
+                for (const id of [...shown]) {
+                    if (present.has(id))
+                        continue;
+                    shown.delete(id);
+                    shownWithFrame.delete(id);
+                    gone.push(id);
+                }
+                // 见过、现在不在列表里的认领 = 这只 ask 已结算 ⇒ 离账
+                for (const [id, seen] of [...claimed])
+                    if (seen && !present.has(id))
+                        claimed.delete(id);
             }
-            // 见过、现在不在列表里的认领 = 这只 ask 已结算 ⇒ 离账
-            for (const [id, seen] of [...claimed])
-                if (seen && !present.has(id))
-                    claimed.delete(id);
             return { appeared, gone, upgraded };
         },
         noteSurfacedByStream(approvalId) {

package/dist/index.d.ts

@@ -140,6 +140,7 @@ export * from './steering.js';
 export * from './diagnostics.js';
 export * from './retryStatus.js';
 export * from './sessionMemoryStatus.js';
+export * from './memorySpecWire.js';
 export * from './adapt.js';
 export * from './adapt/textSegmentAuthority.js';
 export * from './engineHttpTools.js';
@@ -257,6 +258,7 @@ export * from './model/providerPresets.js';
 export * from './hitl/hitlBridge.js';
 export * from './hitl/suspendedReopen.js';
 export * from './hitl/approvalOutcomeNote.js';
+export * from './hitl/approvalResolution.js';
 export { toolEndOutputText, ENGINE_ABORT_TOOL_RESULT } from './hitl/frameRouter.js';
 export { isAskTool } from './hitl/frameRouter.js';
 export * from './hitl/hitlHostSurface.js';

package/dist/index.js

@@ -151,6 +151,7 @@ export * from './retryStatus.js';
 // 把「部署没这个面」说成「你这个会话不存在」;② 五键缺席语义**逐键不同**,健康会话上就有两键
 // 合法缺席,一律读成「没有/关着/0」就是对用户下一个证不出的断言。
 export * from './sessionMemoryStatus.js';
+export * from './memorySpecWire.js';
 export * from './adapt.js';
 // ── L-318(0.68.2):`text_end` 权威段替换的**判决单源** + print 形车道的段账状态机 ──────────
 // 修前这套六形判据有两份实现:本包 `adapt/textStream.replaceAnswerSegment`(交互车道)与 cli
@@ -446,6 +447,8 @@ export * from './hitl/hitlBridge.js';
 export * from './hitl/suspendedReopen.js';
 // 0.74.5 CC-88:流内帧腿审批结局 → 宿主便签的单源映射(三端手拼退役)
 export * from './hitl/approvalOutcomeNote.js';
+// CC-77 ①:「一次审批决断最后怎么了」的单源判别联合 + 唯一映射口(additive;既有结局型面一字不动)
+export * from './hitl/approvalResolution.js';
 // [C93] P0 直讨(0.17.1):toolEndOutputText 单一真源导出——web/desktop 被点名「两端务必接」的
 // 6.0.0 output content-block 归一,此前 frameRouter 内私有,两端手抄=漂移温床。frameRouter 只
 // 挑名导出这一件(整星导出会把路由内部面全泄进公面)。