@sema-agent/client-core 0.77.1 → 0.78.0

package/dist/hitl/approvalsFeed.js

@@ -1,27 +1,7 @@
 import { hostLog } from '../host.js';
 import { unrefTimer } from '../unrefTimer.js';
 import { readLivePendingRows } from './livePendingAsk.js';
-/** [2393] hitl-F5:poll 回调体**连续**逃逸多少次之后判定「这条腿真挂了」并把 `mode` 打成 idle。
- *  取 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' };
@@ -43,17 +23,6 @@ function readDurablePendingRows(raw) {
         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);
@@ -63,11 +32,6 @@ function baselineDurableDigestThrows(raw) {
         return true;
     }
 }
-/**
- * pending 列表的稳定摘要 —— 只在**内容变了**的时候发快照。
- * 键里带 `boundInputHash`:同一条 pending 的绑定被服务端换掉(TOCTOU 场景)也算变化,
- * 否则端会拿着一个「id 没变但绑定变了」的行继续渲染。
- */
 function durableDigestOf(rows) {
     return rows
         .map(r => [r.sessionId ?? '', r.taskId ?? '', r.toolCallId ?? '', r.boundCallId ?? '', r.boundInputHash ?? '', r.toolName ?? '']
@@ -78,33 +42,15 @@ function durableDigestOf(rows) {
 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, 
-/** CC-98:读不出的行数也进摘要 —— 读得懂的那几行没变、但「另有几行读不懂」变了,同样是消费端要知道的变化
- *  (不进摘要 ⇒ 不发快照 ⇒ 端手上那面「不完整」旗永远是上一拍的)。 */
-dropped = 0, 
-/** CC-98:`pending` 段读不出的行数(同理进摘要)。 */
-droppedDurable = 0) {
+function digestOf(rows, live, dropped = 0, droppedDurable = 0) {
     const liveDigest = live === undefined
         ? 'absent'
         : live
-            // 0.73.2:`frame` 在场性进摘要 —— 同一行先盲后全(server 补帧)是内容变了,端要换全卡。
             .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}${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;
     const streamRetryMs = opts?.streamRetryMs ?? 60_000;
@@ -119,52 +65,23 @@ 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 臂。 */
     let consecutivePollEscapes = 0;
-    /** [F4957-1] 轮询腿的**代际**:push 腿每重连一次 +1。在途的旧拍完成时凭它认出自己已经过期 ——
-     *  它的成败属于上一条腿,不该改现在这条腿的连续计数,也不该由它来续排(见 `schedulePoll`)。 */
     let pollLeg = 0;
-    /**
-     * [F4957-1 三审] 取件的**单调发号**与「已观察到的最新一号」。乱序回滚是**取件面的通病**,不是
-     * 轮询腿的私事:`refresh()`(端上的显式刷新)与 push 腿的重取同样可能后发先至。所以提交面的闸
-     * 从「代际」升成请求序号 —— 一次响应只有在「没有更晚发起的请求先落过地」时才允许改视图。
-     */
     let takeSeq = 0;
     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) {
         return unrefTimer(t);
     }
-    /**
-     * [C77]② 这一拍要不要真去取件。缺省(宿主没装旋钮)恒 true —— 缺省路径上连一个函数调用都不多。
-     *
-     * 两个不确定方向都倒向**「查」**(fail-safe 方向定在这里,理由是代价不对称):多查一次 =
-     * 一个 `list()` 的流量;少查一次 = 一条待审批在端上迟迟不出现,而这条腿服务的正是 HITL 面。
-     *   · 谓词抛错 ⇒ 查(并记一行:宿主的谓词坏了它自己得看得见,不是静默吞);
-     *   · 谓词返回非布尔(宿主 bug / 忘了 return)⇒ 查,同样记一行。
-     */
     function pollGateOpen() {
         const gate = opts?.shouldPoll;
         if (!gate)
@@ -183,19 +100,12 @@ export function startApprovalsFeed(client, onSnapshot, opts) {
         }
         return verdict;
     }
-    // ── 0.73.4 欠一次看(见 `pushTakeRetryMs` 头注)──
     const pushTakeRetryBaseMs = opts?.pushTakeRetryMs ?? 1000;
     const pushTakeRetryMaxMs = Math.max(pushTakeRetryBaseMs, 30_000);
     let pushTakeRetryTimer;
     let pushTakeRetryDelayMs = pushTakeRetryBaseMs;
-    /** 欠账锚在**发起序号**上:最近一次没看成的 push 侧取件是第几号(0 = 不欠)。 */
     let owedSinceSeq = 0;
-    /** 已经看成的最晚发起序号(与欠账独立记):比它更早发起的失败是迟到的旧账,不记(对偶的乱序形)。 */
     let lastLookedSeq = 0;
-    /**
-     * 销账只认**比欠账更晚发起**的取件:更早发起的那一次看的是失败之前的世界,它迟到的成功说明不了
-     * 「引擎说变了的那一下」已经有人看过(乱序是真的会发生的:慢 list / `refresh()` 与 push 重取撞车)。
-     */
     function noteTakeLooked(seq) {
         if (seq > lastLookedSeq)
             lastLookedSeq = seq;
@@ -209,22 +119,16 @@ export function startApprovalsFeed(client, onSnapshot, opts) {
         pushTakeRetryDelayMs = pushTakeRetryBaseMs;
     }
     function noteTakeMissed(via, seq) {
-        // 🔴 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; // 更晚发起的一眼已经看成 ⇒ 这次迟到的失败不欠
+            return;
         if (seq > owedSinceSeq)
             owedSinceSeq = seq;
         if (stopped || ac.signal.aborted)
             return;
         if (pushTakeRetryTimer !== undefined)
-            return; // 幂等:已经有一只在排
+            return;
         const delay = pushTakeRetryDelayMs;
         pushTakeRetryDelayMs = Math.min(pushTakeRetryDelayMs * 2, pushTakeRetryMaxMs);
         pushTakeRetryTimer = arm(setTimeout(() => {
@@ -232,30 +136,14 @@ export function startApprovalsFeed(client, onSnapshot, opts) {
             if (stopped || ac.signal.aborted)
                 return;
             stats.pushTakeRetries++;
-            // 欠账不随模式走:期间若降级到轮询,这一次照取(轮询腿可能被 shouldPoll 关着)。
             void take('push').catch(e => {
-                // 重试自己逃逸(回体坏形):欠账已在 take() 内续记并再排,这里只接住 rejection。
                 hostLog('debug', `approvalsFeed: push-take retry escaped (unreadable body?) — still owed: ${String(e)}`);
             });
         }, 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;
@@ -270,26 +158,17 @@ export function startApprovalsFeed(client, onSnapshot, opts) {
             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) {
+    async function take(via, leg) {
         if (stopped)
             return;
         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 });
@@ -298,21 +177,17 @@ export function startApprovalsFeed(client, onSnapshot, opts) {
             stats.listErrors++;
             hostLog('debug', `approvalsFeed: list() failed (${via} leg): ${String(e)}`);
             noteTakeMissed(via, seq);
-            publishUnknown('list_threw', via, seq); // 🔴 CC-98:失败也要有出口,不说 = 端拿上一张当现在
+            publishUnknown('list_threw', via, seq);
             return;
         }
-        /** CC-98:`pending` 段的原始值。**在 try 里取**(回体是 `null` / 取键 getter 抛 ⇒ 与修前同档:不逃逸)。 */
         let rawPending;
         try {
             rawPending = 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`);
                 noteTakeMissed(via, seq);
-                // 🔴 CC-98:视图不提交,但**必须说一声** —— 不说 = 端继续拿上一张当现在(把「读不懂」渲成「没有」)。
                 publishUnknown('unreadable_payload', via, seq);
                 return;
             }
@@ -324,35 +199,24 @@ export function startApprovalsFeed(client, onSnapshot, opts) {
             }
         }
         catch (e) {
-            // 回体本身读不出(`null` / 非对象 / `pending` 位是个会抛的 getter)—— 与上一段同档处置,成因不同。
             stats.listErrors++;
             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);
@@ -368,59 +232,32 @@ export function startApprovalsFeed(client, onSnapshot, opts) {
         }
         if (stopped)
             return;
-        // 🔴 摘要排在销账**之前**:回体坏形(例:`pending` 不是数组)会让它抛出、整次取件逃逸(各调用点自己接盘,
-        // 轮询腿的连续逃逸计数靠的就是这条路)。先销账再抛 = 一份读不懂的回体把欠账销了,之后再没人来看。
-        // 逃逸本身也是「没看成」:在**这里**统一记欠账再原样抛出,四个调用点(起手 / 事件 / refresh / 重试)不必各记各的。
         let d;
         try {
             d = digestOf(rows, live, dropped, droppedDurable);
         }
         catch (e) {
             noteTakeMissed(via, seq);
-            // 🔴 CC-98:逃逸(`pending` 不是数组 / 行畸形)同样是「这次取不到」—— 先发臂再原样抛出,
-            // 免得四个调用点(起手 / 事件 / refresh / 重试)各自去猜该不该通知端。
             publishUnknown('unreadable_payload', via, seq);
             throw e;
         }
-        // 🔴 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'` 快照(刚出现的待审批被抹掉,
-        // 或刚解决的又冒回来)。过期的结论一个字节都不提交。
-        // (代际闸已上移到销账之前 —— 见上面那段 R3 [high] 采修的头注。**盲着时让位**的理由照旧:
-        //  `blind !== null` 时让位给序号闸,否则旧腿那份读得懂的结论被丢掉、blind 没人清 ⇒ 永久粘住;
-        //  让位是安全的,乱序本来就由序号闸守。)
-        // 🔴 [F4957-1 三审 finding②] 乱序闸(三条取件路径共用):比「已观察到的最新一号」更早发起的
-        // 响应,其结论已经被后发者的结论取代 —— 一个字节都不提交。`refresh()` 不带代际,单靠上面那道
-        // 闸盖不住它(端上「用户点了刷新」正是最容易与 push 重取撞车的那一发)。
         if (seq < lastObservedSeq) {
             hostLog('debug', `approvalsFeed: dropping out-of-order take #${seq} (newest observed #${lastObservedSeq})`);
             return;
         }
         lastObservedSeq = seq;
-        // 🔴 CC-98 **恢复路**:上一次发布是「不知道」⇒ 即使摘要与失败前一字不差也必须发一张真快照。
-        // 少了这一条(修前的形):失败期间内容没变 ⇒ 摘要相等 ⇒ 这里 return ⇒ 「又能取到了、而且还是那 N 条」
-        // 这件事没有任何出口,端永远停在「不知道」。
         const recovering = blind !== null;
         const contentChanged = d !== lastDigest;
         if (!contentChanged && !recovering)
-            return; // 内容没变 ⇒ 不打扰订阅者
+            return;
         blind = null;
         if (contentChanged)
-            contentRevision++; // 对账退避只认**内容**变化(见 contentRevision 头注)
+            contentRevision++;
         lastDigest = d;
         revision++;
         const snap = {
@@ -438,18 +275,9 @@ export function startApprovalsFeed(client, onSnapshot, opts) {
             onSnapshot(snap);
         }
         catch (e) {
-            // 订阅者抛错绝不能把 feed 打死(与 liveQuestionStore.publishQuestionFrame 同款纪律)。
             hostLog('debug', `approvalsFeed: subscriber threw (swallowed): ${String(e)}`);
         }
     }
-    /**
-     * 起轮询腿。**幂等**(`pollTimer` 在场就不再排一个)——
-     * 🔴 第一版把「排定时器」挂在 `mode !== 'poll'` 这个**状态迁移**上,于是「一开始就没有
-     * `approvals.stream`」的宿主(老 SDK / mock)因为初始 mode 本来就是 'poll',永远排不上
-     * 定时器 = 只取了起手那一次就再也不动了。测试当场逮住(先红后绿)。
-     * 教训与 [paired-mechanisms-must-share-premise] 同族:别把「该做的动作」挂在「状态变了」上,
-     * 挂在「现在该处于什么状态」上。
-     */
     function schedulePoll() {
         if (stopped || ac.signal.aborted)
             return;
@@ -457,14 +285,7 @@ export function startApprovalsFeed(client, onSnapshot, opts) {
             return;
         pollTimer = arm(setTimeout(() => {
             pollTimer = undefined;
-            // 🔴 [F4957-1 二审] 这一拍属于**哪一代**轮询腿。`take('poll')` 是可以挂很久的(慢 list /
-            // 挂死读面),期间 push 腿完全可能重连成功并把连续计数清零 —— 那一拍的结论此时已经是
-            // **上一条腿**的历史,回写到新计数里就等于把「被健康 push 窗隔开的失败」又算回连续
-            // (回落之后只需 4 拍就转 idle),而这正是本批要修掉的那条语义。代际在重连处 +1。
             const leg = pollLeg;
-            // [C77]② 跳拍:消费方说这一拍不用查 ⇒ 不取件、不计 `stats.polls`(没取件却计数 = 谎报流量)、
-            // **不动** `consecutivePollEscapes`(跳拍不是失败,连着跳一万拍也不该被 F5 判成腿挂了),
-            // 但下一拍照排 —— 这是「腿活着但闲着」,不是停摆。
             if (!pollGateOpen()) {
                 if (mode === 'poll')
                     schedulePoll();
@@ -472,32 +293,14 @@ export function startApprovalsFeed(client, onSnapshot, opts) {
             }
             void (async () => {
                 stats.polls++;
-                await take('poll', leg); // 代际随取件一路带进去(提交面的闸在 take 内,见其头注)
-                // 代际已翻篇 ⇒ 这一拍的成败都不属于现在这条腿:既不清零(会掩盖新腿真正的连续失败),
-                // 也不续排(当代那条链由 degradeToPoll 自己排,这里再排一次纯属两条腿并行的种子)。
+                await take('poll', leg);
                 if (leg !== pollLeg)
                     return;
-                consecutivePollEscapes = 0; // 跑完一整拍 ⇒ 之前的逃逸不再连续
+                consecutivePollEscapes = 0;
                 if (mode === 'poll')
                     schedulePoll();
             })().catch(e => {
-                // REF-CC-024 ①:take() 理论上自己兜底(见 take() 内的 try/catch),但这是它逃逸时的最后一道
-                // 接盘 —— 缺了它,轮询定时器的回调体抛出会变成 unhandled rejection(Node 默认致命)。
-                //
-                // 🔴 [2393] hitl-F5(2026-08-02):光接盘不够,**接盘之后还要接着排下一拍**。旧码在这里只记
-                // 一行 debug 就结束:那一拍的 `schedulePoll()` 在 `await take()` 之后、永远轮不到执行 ⇒
-                // 轮询腿当场死透。而 `mode()` 照旧报 'poll'、`stats()` 照旧有数 —— 文件头 38-42 卖的正是
-                // 「跑了 N 秒之后 mode 不是 idle 且 polls+pushEvents > 0」这条端自检,于是自检看着一个
-                // 已经死掉的 feed 说它活着(而「一条 pending 都没有」与「腿挂了」本来就长得一样,这恰恰是
-                // 那段诚实面存在的理由)。逃逸不是理论形:`take()` 的 try/catch 只护 `list()` 本身,其后的
-                // `digestOf(rows)` 在 wire 出畸形 payload(`pending` 不是数组)时就会从这里出去。
-                //
-                // 两条腿(不是二选一):① **续排** —— 一次抛出不该判 feed 死刑,下一拍照跑(下一拍在
-                // `pollIntervalMs` 之后,天然不忙转;不新开定时器,单例卫兵仍是 `pollTimer`);
-                // ② **连续失败上限转 idle** —— 一直抛就是真的挂了,那时 `mode` 必须说真话,让端的自检
-                // 看得见([honest-absence-not-fabricated-zero]:诚实缺席优先于一个还在报活的假象)。
                 hostLog('debug', `approvalsFeed: poll leg threw unexpectedly (take() should have self-caught): ${String(e)}`);
-                // 🔴 [F4957-1 二审] 同上:上一代的逃逸不喂现在这条腿的连续计数,也不由它来续排。
                 if (leg !== pollLeg) {
                     hostLog('debug', `approvalsFeed: stale poll completion from leg ${leg} (current ${pollLeg}) — not counted as a consecutive escape`);
                     return;
@@ -514,7 +317,6 @@ 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;
@@ -546,12 +348,12 @@ export function startApprovalsFeed(client, onSnapshot, opts) {
             if (stopped || ac.signal.aborted)
                 return;
             if (!reconcileGateOpen()) {
-                reconcileDelayMs = reconcileBaseMs; // 闸关 ⇒ 下次转开时从基础间隔起
+                reconcileDelayMs = reconcileBaseMs;
                 scheduleReconcile();
                 return;
             }
             void (async () => {
-                const before = contentRevision; // 🔴 CC-98:退避判据是**内容**变化,不是发布次数(恢复必发也发布)
+                const before = contentRevision;
                 stats.reconciles++;
                 await take('poll');
                 reconcileDelayMs = contentRevision !== before ? reconcileBaseMs : Math.min(reconcileDelayMs * 2, reconcileMaxMs);
@@ -562,11 +364,6 @@ export function startApprovalsFeed(client, onSnapshot, opts) {
                 .then(() => scheduleReconcile());
         }, reconcileDelayMs));
     }
-    /**
-     * 与 schedulePoll 对称(域词表-18):**幂等卫兵**(retryTimer 已在飞则不再排一个)+ **回调首行
-     * 自清**(否则 retryTimer 触发后仍持有已死句柄,degradeToPoll 若被再次调用会直接覆盖它而不清掉
-     * 旧的——旧的照样触发一次 `void runStream()`,两条 push 腿并行 = 双倍取件)。
-     */
     function scheduleStreamRetry() {
         if (stopped || ac.signal.aborted || streamRetryMs <= 0)
             return;
@@ -582,12 +379,6 @@ export function startApprovalsFeed(client, onSnapshot, opts) {
             void runStream();
         }, streamRetryMs));
     }
-    /**
-     * REF-CC-024 ③:`real`(缺省 true)只计**真正的** stream 故障(抛出 / 空转结束)进
-     * `stats.streamFailures`。「SDK 根本没有 `approvals.stream` 这个动词」不是失败,是能力缺席
-     * (老 SDK / mock)——此前无条件 `++` 会让这类宿主在 t=0 就报 streamFailures=1,而文件头
-     * 38-42 正是拿这个数卖「区分『连着但没事发生』与『断了』」,能力缺席被计成故障就说反了。
-     */
     function degradeToPoll(why, real = true) {
         if (stopped)
             return;
@@ -597,7 +388,7 @@ export function startApprovalsFeed(client, onSnapshot, opts) {
             hostLog('debug', `approvalsFeed: push leg unavailable (${why}) — falling back to polling every ${pollIntervalMs}ms`);
         }
         mode = 'poll';
-        schedulePoll(); // 幂等 —— 见 schedulePoll 头注(挂状态不挂迁移)
+        schedulePoll();
         scheduleStreamRetry();
     }
     async function runStream() {
@@ -611,22 +402,12 @@ export function startApprovalsFeed(client, onSnapshot, opts) {
                 if (stopped || ac.signal.aborted)
                     return;
                 if (mode !== 'push') {
-                    // 重试成功:停掉轮询腿(两条腿同时跑 = 双倍取件 + 快照抖动)。
                     mode = 'push';
                     if (pollTimer !== undefined) {
                         clearTimeout(pollTimer);
                         pollTimer = undefined;
                     }
-                    // 🔴 [F4957-1](0.41.0):**同批清零 F5 的连续逃逸计数**。这一拍与 `schedulePoll` 里
-                    // 「跑完一整拍 ⇒ 之前的逃逸不再连续」是同等强度的健康证据 —— 端真的从服务端收到了一个
-                    // 事件。不清零的后果不是多算几次:被一整段健康 push 窗**隔开**的两批逃逸会被当成连续
-                    // 累加(3 次 → 重连 → 再 2 次 = 5),于是刚从 push 回落的轮询腿才逃逸两拍就撞上限,
-                    // `mode()` 谎报 idle —— 而文件头 38-42 卖的正是「mode 不是 idle」这条端自检,
-                    // 它会指着一条刚活过来的腿说它停摆了([honest-absence-not-fabricated-zero] 的反面:
-                    // 把「活着」渲成「死了」同样是撒谎)。计数的语义是**连续**,那就只能被真正连续的失败喂大。
                     consecutivePollEscapes = 0;
-                    // 与清零**同一拍**翻代际:清零只管已经落地的计数,代际管的是那些还挂在 `take()` 里、
-                    // 稍后才回写的在途拍(二审 finding③ —— 少了这一半,清零会被一个旧拍当场推回 1)。
                     pollLeg++;
                     hostLog('debug', 'approvalsFeed: push leg re-established — polling leg stopped');
                 }
@@ -635,8 +416,6 @@ export function startApprovalsFeed(client, onSnapshot, opts) {
                     continue;
                 }
                 stats.pushEvents++;
-                // 🔴 绝不解析 delta 载荷(SDK 自述 FORWARD-DRAFT)—— 任何非 heartbeat 事件都只当
-                //    「变了」的信号,权威值一律重取 list()。
                 await take('push');
             }
             if (!stopped && !ac.signal.aborted)
@@ -648,18 +427,8 @@ export function startApprovalsFeed(client, onSnapshot, opts) {
             degradeToPoll(String(e));
         }
     }
-    // 首帧之前也要有内容:立刻取一次权威快照(否则端在第一个事件到达前是空白的,
-    // 而「空白」与「没有 pending」看起来一样)。
-    //
-    // 🔴 [2393] hitl-F5(同一条缺陷的**第二个**站点,2026-08-02):catch 必须排在 then **之前**。
-    // 旧写法是 `take().then(起两条腿).catch(记一行)` —— 首帧 take 逃逸时 `.then` 整个被跳过,
-    // 于是 `runStream()` / `degradeToPoll()` 一条都没起:feed 在 t=0 就是死的,而 `mode()` 还报着
-    // 构造期算出来的 'push'/'poll'。把接盘挪到前面,「起腿」这件事就从「首帧成功」这个前提上解耦了
-    // ——它本来也不该依赖首帧成不成功([paired-mechanisms-must-share-premise])。
     void take(mode === 'push' ? 'push' : 'poll')
         .catch(e => {
-        // REF-CC-024 ①:同款接盘(见 schedulePoll 里那份同款注释)——首帧取件是唯一没被 try/catch
-        // 包住的调用点之一,这里补上不让它成为 unhandled rejection。
         hostLog('debug', `approvalsFeed: initial take() threw unexpectedly (take() should have self-caught): ${String(e)}`);
     })
         .then(() => {

package/dist/hitl/armedGateRegistry.d.ts

@@ -1,71 +1,16 @@
-/** 登记一个已呈现的决断卡身份键(空/非法输入静默忽略 —— 登记面绝不炸渲染链)。
- *  每次调用都发事件(复见重开的第二次呈现也要有回执;Set 成员级当不了事件源)。 */
 export declare function registerArmedGate(key: string | null | undefined): void;
-/** W1 带 key 变体(多会话宿主每会话一键,互不串账)。 */
 export declare function registerArmedGateFor(sessionKey: string, key: string | null | undefined): void;
-/** 该身份键的卡在本进程本会话呈现过吗?(false = 首见;文案分形的唯一判据) */
 export declare function wasGateArmed(key: string | null | undefined): boolean;
-/** W1 带 key 变体。 */
 export declare function wasGateArmedFor(sessionKey: string, key: string | null | undefined): boolean;
-/** 消费一个身份键(plan 族的决断消费请优先走 {@link notePlanReviewAnswered} 族 —— 它同时推代;
- *  本口保留给「只清账不推代」的宿主场景与 0.30.0 存量消费方,语义不变)。 */
 export declare function clearArmedGate(key: string | null | undefined): void;
-/**
- * 订阅 arm 事件(#269 上收):返回退订钩,调用方**必须**在自己的生命周期末调它(监听器挂在
- * 模块级长存表上,漏退 = 闭包泄漏)。
- *
- * 🔴 为什么不复用 {@link waitForGateArmed}:那是**带窗**的一次性回执(超时即 resolve false),
- * 它答的是「看门狗窗内呈现了没有」;#269 的 tool 门臂另外要问一个**无窗**的事实 ——「这条链的
- * 整个寿命里,这张卡到底有没有呈现过」。用带窗的那只当事实源,会在「迟到卡」(窗后才入队)上
- * 给出 false ⇒ 把一次真呈现误判成「行从未出生」⇒ 回环再铸一张卡,同一个待决项两张可按的卡。
- */
 export declare function onGateArmed(listener: (key: string) => void): () => void;
-/** 测试用:缩短回执看门狗(null 复位)。 */
 export declare function _setGateArmedWaitMsForTest(ms: number | null): void;
-/** 回执看门狗现值(重开臂的缺省等待窗)。 */
 export declare function gateArmedWaitMs(): number;
-/**
- * 等「这几个键里任意一个被 arm」的**事件**(#250 件1 呈现回执)。resolve true = 回执到手;
- * false = 超时(呈现链没走到真入队 —— hook 自动应答/去重丢帧/enqueue 失败/处理器僵死)。
- *
- * 🔴 timer **不 unref**(包 `abortableSleep` 同判据):调用方(重开臂)正 await 本 promise 收
- * verdict —— 回执窗里这只 timer 可能是事件循环里唯一的活,unref 会让 `-p` 车道进程在 await
- * 中途直接退出,诚实的 reopen-failed 行一并蒸发。代价上限 = 一次 timeoutMs 的进程存活延长,
- * 换判决必达。(浏览器宿主无 unref 概念,裸 setTimeout 两端行为一致 —— portability 零分支。)
- */
 export declare function waitForGateArmed(keys: readonly string[], timeoutMs: number): Promise<boolean>;
-/** W1 带 key 变体。 */
 export declare function waitForGateArmedFor(sessionKey: string, keys: readonly string[], timeoutMs: number): Promise<boolean>;
-/** 宿主呈现面登记口:收到可渲染 question 帧即记(键归一见 gateIdentity;坏形静默忽略 ——
- *  id 是 wire/合成位,入参按边界收 unknown,本函数就是窄化动作本身)。
- *
- *  尝试级回执(#250 复审 轮二 [medium]):原始帧 id 自带 `#reopen-*` 尝试序号,是现成的
- *  attempt token —— 归一键之外**事件级**再发一枪原始 id(不入 Set,台账词汇保持归一键)。
- *  重开臂锚它,同 gate 两次在飞重开时一次真入队只唤对应那次尝试,不再同键互唤。 */
 export declare function registerArmedGateFromQuestionId(questionId: unknown): void;
-/**
- * plan_review 的台账键(当代)。0 代 = `planReviewQuestionId(taskId)`(canonical 原形 ——
- * overlay 对**原卡**(done 帧首扎)的登记落进同一键);≥1 代 = 同形 + `#g<N>` 尾。
- */
 export declare function planReviewArmedKey(taskId: string): string;
-/** W1 带 key 变体。 */
 export declare function planReviewArmedKeyFor(sessionKey: string, taskId: string): string;
-/**
- * 记「一张 plan 问答卡被答掉了」⇒ 当代门已被消费,同 run 的**下一只** plan 门是新实例,落新键。
- *
- * ── 为什么锚在「答卡」而不是「决断送达」(局限成文,A-024.4)────────────────────────────────
- * wire 上没有 gate 实例位,宿主能看见的最晚可靠时刻是作答(送达成败在 responder 返回之后才
- * 揭晓)。所以按「答卡」推代。方向代价:决断若终败(重试后仍没送达),门 1 其实还 pending,
- * 下一次重开会判成首见 ——「呈上了一张卡」零历史断言,诚实方向安全;反向(不推代)才会编造
- * 「被关过」。当代键同时从台账清掉(`clearArmedGate` 的 0.30.0 语义在 0 代逐字保持:决断递交后
- * `wasGateArmed(canonical)` 读回 false)。
- *
- * 🔴 决断性门控请走 {@link notePlanReviewAnsweredIfDecisive}(`planReviewWire`):Esc/空答是
- * dismissal 不是决断 —— 那时推代会把「被关过」翻成「首见」,恰是 A-024.4 在最常见路径(Esc
- * 关卡)上要保住的区分。本口只做记账,不做分类。
- */
 export declare function notePlanReviewAnswered(questionId: unknown): void;
-/** W1 带 key 变体。 */
 export declare function notePlanReviewAnsweredFor(sessionKey: string, questionId: unknown): void;
-/** 测试用:清全部会话的台账(含监听器/代数/答卡记账 —— 半清会让跨用例判决互相污染)。 */
 export declare function _resetArmedGateRegistryForTest(): void;