@sema-agent/client-core 0.8.0 → 0.9.0

package/README.md

@@ -23,12 +23,14 @@ Renamed from **`@sema-agent/wire-cc-adapter`** (0.1.x, deprecated — see *Migra
 
 ## Scope
 
-- **Today (0.8.0)** — the adapter seam, the whole `adapt()` pipeline (all 14 A-layer arms plus the
+- **Today (0.9.0)** — the adapter seam, the whole `adapt()` pipeline (all 14 A-layer arms plus the
   B/D/E tool-card layers), the notification/caps/model families, the adapter kernel (stream driver
   + downstream projectors), the request-shaping surface, the fleet/panel projections and the
-  subagent wire family, the workflow monitor contract + live source, and the model catalog tables.
-- **Planned** — what is still in the shell: HITL / approvals (`hitlBridge`, `liveHitlAskWire`,
-  `liveToolApprovalWire`, `planReviewWire`) and the single-authority completion event (batch B7);
+  subagent wire family, the workflow monitor contract + live source, the model catalog tables, and
+  the **HITL family** (`hitl/`: the D-1 approval bridge, the ask-gate stream bridge, the
+  tool-approval wire, plan review, and the pending-approvals push feed).
+- **Planned** — what is still in the shell: the print lane tail (batch B8) and the registry
+  user-plane hand-copies (they retire onto `@sema-agent/sdk/registry`, not into this package);
   plus everything that is genuinely host-specific — Ink rendering and keyboard interaction,
   filesystem persistence, pty/terminal, and the signal-path teardown. The web session view
   (first target consumer) and the desktop client (second) consume the same package.
@@ -129,7 +131,7 @@ grew the host context to carry what a non-Node host must supply:
   desktop host coalesces single-frame deltas at 16 ms; the 2.1.207 CLI line we track uses 100 ms),
   so the cadence is host render policy while the merge *semantics* stay here, in one place.
 
-0.6.0 – 0.8.0 (batches B4 – B6) completed the frame dispatch and moved in everything that is not
+0.6.0 – 0.9.0 (batches B4 – B7) completed the frame dispatch and moved in everything that is not
 host-specific. The blow-by-blow lives in the `src/index.ts` head comment (the source of truth); the
 short version:
 
@@ -144,6 +146,16 @@ short version:
   source, `hooksWireCaps` on the `SettingsPort`, `liveInitToolFace`, the model catalog tables, and
   `MIGRATED_COMPENSATIONS` — the ledger of which shell-side compensation was split where, which
   chrome arm carries the host's half, and when upstream lets it retire.
+- **0.9.0** — the HITL family. `hitl/hitlBridge` carries the **D-1 action binding**: the
+  `boundCallId` + `boundInputHash` two-tuple is read off the pending row the human saw and echoed
+  back **verbatim** — never recomputed — and a 409 binding mismatch is a safety stop that is
+  **never** auto-retried. Both code paths are pinned byte-for-byte by the pure gate.
+  `hitl/toolApprovalWire` is a split: the gate decisions and both decide legs live here, the
+  three-choice card itself is an `ApprovalCardPort` the host installs. `hitl/askGateWire` runs the
+  park → decide → re-attach loop; `hitl/planReviewWire` closes the seventh and last `wireConfig()`
+  hand-copy. `hitl/approvalsFeed` is the one behavioural change in the batch: a pending-approvals
+  push channel over `approvals.stream()` that falls back to polling and periodically retries the
+  push leg — it deliberately does **not** take over the D-1 fetch, which must stay authoritative.
 
 Known intentional deltas from the CLI are enumerated in `ADAPTER_DIVERGENCES`. The *compensation*
 ledger is a different table (`MIGRATED_COMPENSATIONS`): the entries there behave identically on
@@ -153,7 +165,7 @@ both sides — what it records is why a compensation exists and when it can be d
 
 ```bash
 npm install
-node scripts/run-client-core-pure-test.mjs         # 867 consumer-view checks (22 + 140 + 208 + 59 + 101 + 96 + 241); no CLI tree needed
+node scripts/run-client-core-pure-test.mjs         # 1030 consumer-view checks (22 + 140 + 208 + 59 + 101 + 96 + 241 + 163); no CLI tree needed
 node scripts/run-client-core-portability-test.mjs  # 39 checks: kernel + A-layer + index closures, browser bundle
 node scripts/run-client-core-diff-test.mjs         # 1397 checks: differential + replay-id + ledger
 ```

package/dist/adapt.js

@@ -1,5 +1,5 @@
 import { deriveTranscriptId } from './seam.js';
-import { dropQueuedNotificationsForRun, isEngineWorkflowNotified, isWorkflowCompletionCardEnqueued, listNotifiedRuns, listWorkflowCompletionCardsEnqueued, markEngineWorkflowNotified, normalizeTaskNotification, noteWorkflowCompletionCardEnqueued, renderTaskNotificationXml, taskNotificationDedupKey, } from './notifications.js';
+import { dropQueuedNotificationsForRun, isEngineWorkflowNotified, isWorkflowCompletionCardEnqueued, listNotifiedRuns, listWorkflowCompletionCardsEnqueued, markEngineWorkflowNotified, normalizeTaskNotification, noteWorkflowCompletionCardEnqueued, parseTranscriptNotificationSeeds, renderTaskNotificationXml, taskNotificationDedupKey, } from './notifications.js';
 import { mapBrainStatusToRetry } from './retryStatus.js';
 import { steeringInjectedToAttachments } from './steering.js';
 import { projectDiagnosticsFrame } from './diagnostics.js';
@@ -336,53 +336,17 @@ class WireToCcAdapterImpl {
      * task-id/status/type="external",恰可重建**无 seq 键形**;Monitor 的 `:seq` 批键形不同,绝不误伤。
      */
     importLedgerFromTranscript(messages) {
-        const unescape = (s) => s
-            .replace(/&lt;/g, '<')
-            .replace(/&gt;/g, '>')
-            .replace(/&quot;/g, '"')
-            .replace(/&#39;/g, "'")
-            .replace(/&amp;/g, '&');
-        let seeded = 0;
-        for (const m of messages) {
-            const rec = m;
-            if (rec?.type !== 'user')
-                continue;
-            const content = rec.message?.content;
-            const texts = [];
-            if (typeof content === 'string')
-                texts.push(content);
-            else if (Array.isArray(content)) {
-                for (const b of content) {
-                    const bb = b;
-                    if (bb?.type === 'text' && typeof bb.text === 'string')
-                        texts.push(bb.text);
-                }
-            }
-            for (const text of texts) {
-                if (!text.includes(`<${TASK_NOTIFICATION_TAG}`))
-                    continue;
-                const blockRe = new RegExp(`<${TASK_NOTIFICATION_TAG}(\\s[^>]*)?>([\\s\\S]*?)</${TASK_NOTIFICATION_TAG}>`, 'g');
-                for (const bm of text.matchAll(blockRe)) {
-                    const attrs = bm[1] ?? '';
-                    const body = bm[2] ?? '';
-                    const idM = body.match(new RegExp(`<${TASK_ID_TAG}>([\\s\\S]*?)</${TASK_ID_TAG}>`));
-                    const stM = body.match(new RegExp(`<${STATUS_TAG}>([\\s\\S]*?)</${STATUS_TAG}>`));
-                    if (!idM || !stM)
-                        continue;
-                    const taskId = unescape(idM[1] ?? '');
-                    const status = unescape(stM[1] ?? '');
-                    if (taskId.length === 0 || status.length === 0)
-                        continue;
-                    const external = /\btype="external"/.test(attrs);
-                    this.renderedNotifications.add(`${external ? 'external:' : ''}${taskId}:${status}`);
-                    if (!external && (status === 'completed' || status === 'failed' || status === 'killed')) {
-                        // cli seedEngineTaskNotificationDedupFromTranscript 同位:回植走 module 台账
-                        // (outstanding 药丸 / idle watcher 收摊那半场读的就是它)。
-                        markEngineWorkflowNotified(taskId);
-                    }
-                    seeded++;
-                }
-            }
+        // 🔴 B7(T3):解析半场收成 `notifications.parseTranscriptNotificationSeeds`(**唯一一份**)。
+        //    此前本方法与 cli `seedEngineTaskNotificationDedupFromTranscript` 各写了一遍同样的
+        //    XML 反解 —— 两份手写解析里任何一份漂了,resume 回植就在那一侧静默失效(而两边代码
+        //    看着都对)。壳侧 shim 化后两个入口都落到同一个解析器上。
+        const { renderedKeys, notifiedKeys, seeded } = parseTranscriptNotificationSeeds(messages);
+        for (const k of renderedKeys)
+            this.renderedNotifications.add(k);
+        for (const taskId of notifiedKeys) {
+            // cli seedEngineTaskNotificationDedupFromTranscript 同位:回植走 module 台账
+            // (outstanding 药丸 / idle watcher 收摊那半场读的就是它)。
+            markEngineWorkflowNotified(taskId);
         }
         return seeded;
     }

package/dist/compensations.d.ts

@@ -46,7 +46,8 @@ export interface CompensationRecord {
     retireOn: string | null;
 }
 /**
- * B6 P5 处置的八条(T32/T34/T47/T48/T49 整条进包 · T35/T36/T44 拆)。
+ * B6 P5 处置的八条(T32/T34/T47/T48/T49 整条进包 · T35/T36/T44 拆)+ **B7 完成事件族五条**
+ * (T1/T2/T3/T25/T53,全部「只搬不删」—— P1-3 未到货)。
  *
  * 🔴 事实核对(B6 余项批实测,不是照抄设计稿):这八条的落码**都发生在 B4**
  * (`adapt.ts` A 层第 14 臂 `task_progress` 收官那一批),本批做的是**核实 + 登记 + 定案**,

package/dist/compensations.js

@@ -27,7 +27,8 @@
  */
 import { CHROME_ARMS } from './seam.js';
 /**
- * B6 P5 处置的八条(T32/T34/T47/T48/T49 整条进包 · T35/T36/T44 拆)。
+ * B6 P5 处置的八条(T32/T34/T47/T48/T49 整条进包 · T35/T36/T44 拆)+ **B7 完成事件族五条**
+ * (T1/T2/T3/T25/T53,全部「只搬不删」—— P1-3 未到货)。
  *
  * 🔴 事实核对(B6 余项批实测,不是照抄设计稿):这八条的落码**都发生在 B4**
  * (`adapt.ts` A 层第 14 臂 `task_progress` 收官那一批),本批做的是**核实 + 登记 + 定案**,
@@ -102,6 +103,75 @@ export const MIGRATED_COMPENSATIONS = [
         //    Set 恒空 ⇒ 判据④ 静默失效」复活,所以 chromeArm 恒 null,拆的是**过滤策略**不是台账。
         retireOn: 'P1-2 到货后 fleet 行自带 parentToolCallId ⇒ 双生行不需要按尾段查',
     },
+    // ── B7 处置的五条(完成事件族 T1/T2/T3/T25/T53)──────────────────────────────────────────────
+    // 🔴 **P1-3(完成事件单一权威)未到货 ⇒ 这五条全是「只搬不删」**:四道去重原样保留。
+    //    每条的 `retireOn` 写的就是「P1-3 到货后**降哪一道**」——退役条件必须是**可执行的判据**,
+    //    不是「以后再说」。设计稿 §3 B7:「P1-3 到货 ⇒ 四道去重降到一道 + 删 XML 反解回植」。
+    //    ⚠️ 「降到一道」不等于「删三道」:下面 T53 行逐道写清了哪一道是权威、另外三道各防什么,
+    //    否则到货那天没人分得清哪些能删([anchor-on-the-deciding-quantity]:先定这个量门控什么)。
+    {
+        id: 'T1',
+        what: '三个跨 turn 台账(渲染去重 / 跨通道记账 / 完成卡已入队)—— completion inbox 是 at-least-once,' +
+            '客户端必须自己记「这条完成我处理过了」',
+        disposition: 'in-library',
+        libraryHalf: 'notifications.ts 的 module 台账(notifiedRunIds / cardEnqueuedRunIds)+ ' +
+            '适配器实例的 renderedNotifications;序列化口 exportLedger/importLedger',
+        chromeArm: null,
+        hostHalf: null,
+        // 长期职责:只要投递是 at-least-once,客户端就得有去重记忆。P1-3 换的是**键**不是台账。
+        retireOn: null,
+    },
+    {
+        id: 'T2',
+        what: '去重键客户端重算(`[external:]taskId:status[:seq]`)—— wire 上没有「这次完成的唯一 id」',
+        disposition: 'in-library',
+        libraryHalf: 'notifications.ts taskNotificationDedupKey + taskNotificationDedupKeyFromWire(裸 wire 入口)',
+        chromeArm: null,
+        hostHalf: null,
+        retireOn: 'P1-3 到货(帧带 completionId)⇒ 键改成**读** completionId,重算算法整条删;' +
+            '删之前要先有一批「同一完成在两条通道上 completionId 相同」的实测(否则换成了一把更差的键)',
+    },
+    {
+        id: 'T3',
+        what: '从落盘转录的 `<task-notification>` XML 反解回植去重键 —— 去重面纯内存,重启即蒸发,' +
+            '「通知 user-turn 已落盘、ack 未落」的 crash 窗口会二次喂模型(#63)',
+        disposition: 'in-library',
+        libraryHalf: 'notifications.ts parseTranscriptNotificationSeeds(**唯一一份**解析)+ ' +
+            'adapt.ts importLedgerFromTranscript(消费口)',
+        chromeArm: null,
+        hostHalf: null,
+        retireOn: 'P1-3 到货 ⇒ **回植仍要做**(crash 窗口客观存在),但不必再解 XML —— 转录里直接带 ' +
+            'completionId。所以退的是「XML 反解」这一段,不是整条回植',
+    },
+    {
+        id: 'T25',
+        what: 'workflow 终态轮询卡经过投影 ⇒ 预 seed runId 去重(补发通道对同 runId 丢弃)—— ' +
+            '同一个完成会从「轮询卡」和「补发通道」两个方向到达',
+        disposition: 'in-library',
+        libraryHalf: 'toolResult.ts 终态轮询卡臂的预 seed + notifications.markEngineWorkflowNotified',
+        chromeArm: null,
+        hostHalf: null,
+        retireOn: 'P1-3 到货 ⇒ 两个方向带同一个 completionId,预 seed 这一手(按 runId 抢跑)可删',
+    },
+    {
+        id: 'T53',
+        what: '同一次完成四通道扇出 ⇒ 四道去重(设计稿列为最贵 #4)',
+        disposition: 'in-library',
+        // 四道各自防什么(P1-3 到货那天要按这个清单逐道判,别一刀切):
+        //  ① renderedNotifications(键=T2)—— 防**同一帧重放**(durable re-attach / at-least-once 重投)。
+        //     ⇒ P1-3 后这一道**留**,只是键换成 completionId。这是「降到一道」里的那一道。
+        //  ② isWorkflowCompletionCardEnqueued —— 防「Path B 已入队的完成卡」与「Path A 推送帧」双投。
+        //     ⇒ P1-3 后可删:两条通道带同一 completionId,①就能盖住。
+        //  ③ isEngineWorkflowNotified(workflow_complete 臂首行)—— 防补发通道在引擎已 server-side
+        //     inject 之后再喂一遍。⇒ P1-3 后可删,同②。
+        //  ④ dropQueuedNotificationsForRun —— 回声到达时把还躺在队列里的同 run 条目捞回来。
+        //     ⇒ **不是去重是撤单**,P1-3 后仍需要(队列里那条已经排上了,得有人撤)。
+        libraryHalf: 'adapt.ts task_notification / workflow_complete 两臂的四道门(逐道说明见本行上方注释)',
+        chromeArm: null,
+        hostHalf: null,
+        retireOn: 'P1-3 到货 ⇒ 降到「①渲染去重(键换 completionId)+ ④队列撤单」两道;②③ 删。' +
+            '🔴 判据不是「四变一」而是逐道过一遍上面那四行 —— 把 ④ 当成去重删掉会让队列里的旧条目重新上屏',
+    },
     {
         id: 'T49',
         what: 'subagent alias 只能在 tick 上学 —— content 帧只带 parentToolCallId、没有 taskId',

package/dist/hitl/approvalsFeed.d.ts

@@ -0,0 +1,102 @@
+/**
+ * ⇄ B7 ③(census **G20**,设计稿 §3 B7 末条):`approvals.list` 取件 → **SDK 原生推送
+ *    `approvals.stream()`**,断流/无端点**回落轮询**的韧性臂保留。这是**行为改动**(不是搬迁),
+ *    所以单独一个文件、单独一条测试、单独一个 commit。
+ *
+ * ## 先纠一个事实(census G20 的措辞会误导下一棒)
+ *
+ * G20 原话是「`hitlBridge.ts:197` 等三处今天靠 `approvals.list` 轮询」。**实测不是轮询** ——
+ * 那三处(`hitlBridge.findPending` / `askGateWire.surfaceGateAndDecide` /
+ * `toolApprovalWire.surfaceFsApprovalAndDecide`)都是**按需单次取件**:流上已经来了 park 信号,
+ * 才去取那一行。真正缺的不是「把轮询换成推送」,而是**根本没有推送通道**:
+ *   · 别的客户端(web/桌面/另一个 TUI)解掉了一条 pending —— 本端不知道;
+ *   · 后台子代 lane 的 park 不在宿主自己的流上 —— 本端只有等下一次自己去 list 才看得见;
+ *   · 端要渲一个「有 N 条待审批」的常驻指示 —— 今天只能自己起定时器。
+ *
+ * ⇒ 本文件提供的是那条**缺失的推送通道**(pending 快照的订阅面),而不是把上面三处改成读缓存。
+ *
+ * ## 🔴 它**不替换** D-1 的取件(这条是安全边界,别"顺手优化"掉)
+ *
+ * D-1 两元组必须取自**人看见的那一行**。让 `findPending` 去读一个可能陈旧的快照 =
+ * 用一个过期的 `boundInputHash` 去 decide ⇒ server fail-closed 409 ⇒ 一个合法审批被拒
+ * (或者更坏:快照比服务端新旧关系不确定时,人看到的和绑定的不是同一件事)。
+ * 所以那三处**继续走权威 `list()`**,本 feed 只做「有变化了」的通知面与快照面。
+ * pure 门 B7③ 段对这条有断言(feed 跑着的时候,decide 路径仍然打 `list()`)。
+ *
+ * ## 两条腿与降级次序
+ *
+ * 1. **push**:`approvals.stream()`(SDK 内部已带断线重连 + heartbeat 静默重连)。
+ *    收到**非 heartbeat** 事件 ⇒ 重取权威 `list()`。
+ *    🔴 绝不解析 delta 载荷 —— SDK 自述 `ApprovalStreamEvent` 是 **FORWARD-DRAFT**
+ *    (「payload fields are FORWARD-DRAFT pending service's shape confirmation」),
+ *    照着未确认的形写解析 = 服务端一改就静默错。
+ * 2. **poll**:stream 抛(404 无端点 / SDK 连 5 次开不起来 / 连 5 次空转)⇒ 落到定时 `list()`。
+ *    并按 `streamRetryMs` 定期**再试一次 stream** —— 回落是降级不是永久放弃
+ *    (服务端升级上线后不该还要重启客户端)。
+ * 3. **idle**:stop() 之后 / signal abort 之后。
+ *
+ * ## 诚实面([probe-must-prove-it-speaks])
+ *
+ * 「一条快照都没有」既可能是「真的没有 pending」,也可能是「两条腿都挂了」。所以 feed 暴露
+ * `stats()`(pushEvents / polls / listErrors / streamFailures / snapshots)与 `mode()`,
+ * 端的自检可以断言「跑了 N 秒之后 mode 不是 idle 且 polls+pushEvents > 0」。
+ */
+import type { PendingCheckpoint } from '@sema-agent/sdk';
+/** feed 消费的 wire 切片。`stream` 可选 —— 老 SDK / mock 没有它就直接走轮询腿。 */
+export interface ApprovalsFeedClientLike {
+    approvals: {
+        list(opts?: {
+            signal?: AbortSignal;
+        }): Promise<PendingCheckpoint[]>;
+        stream?(opts?: {
+            signal?: AbortSignal;
+        }): AsyncGenerator<{
+            type?: unknown;
+            [k: string]: unknown;
+        }>;
+    };
+}
+export type ApprovalsFeedMode = 'push' | 'poll' | 'idle';
+export interface ApprovalsFeedSnapshot {
+    /** 权威 pending 列表(**恒来自 `list()`**,不是 delta 拼出来的)。 */
+    pending: PendingCheckpoint[];
+    /** 这次快照是被哪条腿触发的。 */
+    mode: 'push' | 'poll';
+    /** 单调递增的修订号(端可用它判「我看到的是不是最新的」)。 */
+    revision: number;
+}
+export interface ApprovalsFeedStats {
+    /** 收到的**非 heartbeat** 推送事件数。 */
+    pushEvents: number;
+    /** heartbeat 帧数(证明「连着但没事发生」,与「断了」区分开)。 */
+    heartbeats: number;
+    /** 轮询腿真取件的次数。 */
+    polls: number;
+    /** `list()` 抛错的次数(两条腿共用计数 —— 取件失败不该被静默)。 */
+    listErrors: number;
+    /** stream 抛出(404 / 反复失败)导致降级的次数。 */
+    streamFailures: number;
+    /** 真正发给订阅者的快照数(内容无变化时不发 ⇒ 这个数会小于 polls+pushEvents)。 */
+    snapshots: number;
+}
+export interface ApprovalsFeedOptions {
+    /** 回落轮询间隔;缺省 5000ms。 */
+    pollIntervalMs?: number;
+    /** 降级后多久再试一次 stream;缺省 60_000ms。0 = 不再试(永久轮询)。 */
+    streamRetryMs?: number;
+    signal?: AbortSignal;
+}
+export interface ApprovalsFeedHandle {
+    stop(): void;
+    mode(): ApprovalsFeedMode;
+    stats(): ApprovalsFeedStats;
+    /** 最近一次快照(还没取过 ⇒ null)。 */
+    snapshot(): ApprovalsFeedSnapshot | null;
+    /** 立刻取一次权威 list 并(有变化时)发快照。端在「用户点了刷新」之类的场景用。 */
+    refresh(): Promise<void>;
+}
+/**
+ * 起一条 pending-approvals feed。**幂等性归调用方**:一个 client 起一条就够了,起两条 =
+ * 两倍取件(不是错误,但没意义)。
+ */
+export declare function startApprovalsFeed(client: ApprovalsFeedClientLike, onSnapshot: (snap: ApprovalsFeedSnapshot) => void, opts?: ApprovalsFeedOptions): ApprovalsFeedHandle;

package/dist/hitl/approvalsFeed.js

@@ -0,0 +1,185 @@
+import { hostLog } from '../host.js';
+/**
+ * pending 列表的稳定摘要 —— 只在**内容变了**的时候发快照。
+ * 键里带 `boundInputHash`:同一条 pending 的绑定被服务端换掉(TOCTOU 场景)也算变化,
+ * 否则端会拿着一个「id 没变但绑定变了」的行继续渲染。
+ */
+function digestOf(rows) {
+    return rows
+        .map(r => [r.sessionId ?? '', r.taskId ?? '', r.toolCallId ?? '', r.boundCallId ?? '', r.boundInputHash ?? '', r.toolName ?? '']
+        .join('
'))
+        .sort()
+        .join('');
+}
+/**
+ * 起一条 pending-approvals feed。**幂等性归调用方**:一个 client 起一条就够了,起两条 =
+ * 两倍取件(不是错误,但没意义)。
+ */
+export function startApprovalsFeed(client, onSnapshot, opts) {
+    const pollIntervalMs = opts?.pollIntervalMs ?? 5000;
+    const streamRetryMs = opts?.streamRetryMs ?? 60_000;
+    const ac = new AbortController();
+    const onOuterAbort = () => ac.abort();
+    if (opts?.signal) {
+        if (opts.signal.aborted)
+            ac.abort();
+        else
+            opts.signal.addEventListener('abort', onOuterAbort, { once: true });
+    }
+    let mode = client.approvals.stream ? 'push' : 'poll';
+    let stopped = false;
+    let revision = 0;
+    let lastDigest = null;
+    let last = null;
+    let pollTimer;
+    let retryTimer;
+    const stats = {
+        pushEvents: 0, heartbeats: 0, polls: 0, listErrors: 0, streamFailures: 0, snapshots: 0,
+    };
+    function arm(t) {
+        ;
+        t.unref?.();
+        return t;
+    }
+    async function take(via) {
+        if (stopped)
+            return;
+        let rows;
+        try {
+            rows = await client.approvals.list({ signal: ac.signal });
+        }
+        catch (e) {
+            stats.listErrors++;
+            hostLog('debug', `approvalsFeed: list() failed (${via} leg): ${String(e)}`);
+            return;
+        }
+        if (stopped)
+            return;
+        const d = digestOf(rows);
+        if (d === lastDigest)
+            return; // 内容没变 ⇒ 不打扰订阅者
+        lastDigest = d;
+        revision++;
+        const snap = { pending: rows, mode: via, revision };
+        last = snap;
+        stats.snapshots++;
+        try {
+            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;
+        if (pollTimer !== undefined)
+            return;
+        pollTimer = arm(setTimeout(() => {
+            pollTimer = undefined;
+            void (async () => {
+                stats.polls++;
+                await take('poll');
+                if (mode === 'poll')
+                    schedulePoll();
+            })();
+        }, pollIntervalMs));
+    }
+    function scheduleStreamRetry() {
+        if (stopped || ac.signal.aborted || streamRetryMs <= 0)
+            return;
+        if (!client.approvals.stream)
+            return;
+        retryTimer = arm(setTimeout(() => {
+            if (stopped || ac.signal.aborted)
+                return;
+            hostLog('debug', 'approvalsFeed: retrying push leg (降级是暂时的,服务端升级后不该还要重启客户端)');
+            void runStream();
+        }, streamRetryMs));
+    }
+    function degradeToPoll(why) {
+        if (stopped)
+            return;
+        stats.streamFailures++;
+        if (mode !== 'poll') {
+            hostLog('debug', `approvalsFeed: push leg unavailable (${why}) — falling back to polling every ${pollIntervalMs}ms`);
+        }
+        mode = 'poll';
+        schedulePoll(); // 幂等 —— 见 schedulePoll 头注(挂状态不挂迁移)
+        scheduleStreamRetry();
+    }
+    async function runStream() {
+        const stream = client.approvals.stream;
+        if (!stream) {
+            degradeToPoll('SDK has no approvals.stream (old SDK / mock)');
+            return;
+        }
+        try {
+            for await (const ev of stream.call(client.approvals, { signal: ac.signal })) {
+                if (stopped || ac.signal.aborted)
+                    return;
+                if (mode !== 'push') {
+                    // 重试成功:停掉轮询腿(两条腿同时跑 = 双倍取件 + 快照抖动)。
+                    mode = 'push';
+                    if (pollTimer !== undefined) {
+                        clearTimeout(pollTimer);
+                        pollTimer = undefined;
+                    }
+                    hostLog('debug', 'approvalsFeed: push leg re-established — polling leg stopped');
+                }
+                if (ev?.type === 'heartbeat') {
+                    stats.heartbeats++;
+                    continue;
+                }
+                stats.pushEvents++;
+                // 🔴 绝不解析 delta 载荷(SDK 自述 FORWARD-DRAFT)—— 任何非 heartbeat 事件都只当
+                //    「变了」的信号,权威值一律重取 list()。
+                await take('push');
+            }
+            if (!stopped && !ac.signal.aborted)
+                degradeToPoll('stream ended without progress');
+        }
+        catch (e) {
+            if (stopped || ac.signal.aborted)
+                return;
+            degradeToPoll(String(e));
+        }
+    }
+    // 首帧之前也要有内容:立刻取一次权威快照(否则端在第一个事件到达前是空白的,
+    // 而「空白」与「没有 pending」看起来一样)。
+    void take(mode === 'push' ? 'push' : 'poll').then(() => {
+        if (stopped)
+            return;
+        if (client.approvals.stream)
+            void runStream();
+        else
+            degradeToPoll('SDK has no approvals.stream (old SDK / mock)');
+    });
+    return {
+        stop() {
+            if (stopped)
+                return;
+            stopped = true;
+            mode = 'idle';
+            if (pollTimer !== undefined)
+                clearTimeout(pollTimer);
+            if (retryTimer !== undefined)
+                clearTimeout(retryTimer);
+            opts?.signal?.removeEventListener('abort', onOuterAbort);
+            ac.abort();
+        },
+        mode: () => mode,
+        stats: () => ({ ...stats }),
+        snapshot: () => last,
+        refresh: () => take(mode === 'push' ? 'push' : 'poll'),
+    };
+}