@sema-agent/client-core 0.12.2 → 0.14.0

package/dist/notifications.js

@@ -5,6 +5,7 @@
  * taskNotificationErrorSupplement 全文、hookNoticeStore 的判定半场 —— 见文件下半的 B2 分节。
  */
 import { hostEnv } from './hostEnv.js';
+import { unrefTimer } from './unrefTimer.js';
 import { clearEnginePanelTaskResident, publishEngineAgentPanelEvent, } from './engineAgentPanelStore.js';
 function escapeXml(v) {
     return v.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
@@ -203,6 +204,17 @@ export function installNotificationQueuePort(port) {
 export function notificationQueuePortMisses() {
     return queuePortMisses;
 }
+/**
+ * 本模块唯一的 SEMA_DEBUG 留痕出口(前缀逐字保持 `[sema][notif] `,与既有 drop 那行同形)。
+ * 🔴 为什么要单口:C5「静默丢数据零容忍」的执行方式是**每条丢弃/放弃路径都能在同一个前缀下
+ * grep 到**;散写 console.error 时新增的丢弃路径很容易漏掉留痕(notif-02/-03 就是这么漏的)。
+ */
+function traceNotif(line) {
+    if (!hostEnv().SEMA_DEBUG)
+        return;
+    // eslint-disable-next-line no-console
+    console.error(`[sema][notif] ${line}`);
+}
 function port() {
     if (queuePort)
         return queuePort;
@@ -243,6 +255,22 @@ export function _resetNotificationQueuePortForTest() {
 // (the `<tool-use-id>` line is optional in CC's own template the same way).
 // ══════════════════════════════════════════════════════════════════════════════════════════════
 const notifiedRunIds = new Set();
+const notifiedBgCycleHigh = new Map();
+let ledgerOrder = 0;
+const nextLedgerOrder = () => ++ledgerOrder;
+/** 「已送达」两账的**唯一**写口(裸 id 维 + 周期维必须同时前进,否则收摊臂又回到没有周期证据)。 */
+function markRunNotified(runId, cycle = BG_FIRST_SEQ) {
+    notifiedRunIds.add(runId);
+    const prev = notifiedBgCycleHigh.get(runId);
+    if (prev === undefined || cycle > prev.cycle) {
+        notifiedBgCycleHigh.set(runId, { cycle, order: nextLedgerOrder() });
+    }
+}
+/** 「**这一个周期**已经送达过」——收摊臂唯一可用的删除证据。 */
+function notifiedBgCycleAtLeast(taskId, cycle) {
+    const high = notifiedBgCycleHigh.get(taskId);
+    return high !== undefined && high.cycle >= cycle ? high : undefined;
+}
 /**
  * B1(frame-lane-matrix 三节定谳)— Path A 回声到达时丢弃同 run 的 pending 队列条目。
  * 双投机理:活跃 turn 内 Path B(workflow_complete/bg_notification/probe feeder →
@@ -290,10 +318,7 @@ export function dropQueuedNotificationsForRun(taskId) {
     // 注入,引擎侧单投成立;这里只救 UI 半场。
     if (dropped.length > 0) {
         cardEnqueuedRunIds.delete(taskId);
-        if (hostEnv().SEMA_DEBUG) {
-            // eslint-disable-next-line no-console
-            console.error(`[sema][notif] dropped ${dropped.length} queued task-notification(s) for ${taskId} — engine echo already delivered (B1); card ownership returned to the frame lane`);
-        }
+        traceNotif(`dropped ${dropped.length} queued task-notification(s) for ${taskId} — engine echo already delivered (B1); card ownership returned to the frame lane`);
     }
     return dropped.length;
 }
@@ -305,7 +330,9 @@ export function dropQueuedNotificationsForRun(taskId) {
  * steer-inject 的 task_notification 帧)即预标记,Channel A 对同 runId 的补发直接丢弃。
  */
 export function markEngineWorkflowNotified(runId) {
-    notifiedRunIds.add(runId);
+    // [2393] F-1:外部 mark 只证「首周期已送达」(它没有周期号可带),周期维按首周期记 —— 与本函数
+    // 既有的跨通道语义逐字一致(enqueueBgChildNotification 的跨通道臂同样只对首周期成立)。
+    markRunNotified(runId);
     if (outstandingRuns.delete(runId))
         notifyOutstanding();
 }
@@ -351,7 +378,9 @@ export function isWorkflowCompletionCardEnqueued(runId) {
 }
 const outstandingRuns = new Map(); // runId → registeredAt(ms)
 // ── D4(212 对拍):outstanding 计数订阅面——REPL 空闲态渲「✻ Waiting for N dynamic
-// workflow(s) to finish」(CC 2.1.212 同形,wf-ui-cc2 ground truth)。仅通知计数变化。
+// workflow(s) to finish」(CC 2.1.212 同形,wf-ui-cc2 ground truth)。仅通知计数变化 ——
+// notif-03 起「计数」含 `outstandingAbandonedCount()`,故 bg 半场的 TTL 放弃也发一次通知
+// (那一格变了,消费方要重渲「N 个后台任务已停止等待」)。
 const outstandingListeners = new Set();
 function notifyOutstanding() {
     for (const l of [...outstandingListeners]) {
@@ -378,6 +407,36 @@ export function subscribeOutstandingWorkflows(listener) {
         outstandingListeners.delete(listener);
     };
 }
+let abandonedCount = 0;
+/**
+ * 🔴 放弃观察的**唯一出口**。`id` 是各自台账的键(bg 侧 = `taskId:seq` 复合键,留痕里可直读)。
+ * 未命中(键已不在台账)⇒ 不计数、不留痕:放弃必须是**真发生过**的事,别把「本来就没有」算成放弃。
+ */
+function abandonOutstanding(kind, id, reason) {
+    const removed = kind === 'bg-task' ? outstandingBgTasks.delete(id) : outstandingRuns.delete(id);
+    if (!removed)
+        return;
+    abandonedCount++;
+    traceNotif(`abandoned ${kind} ${id} — reason=${reason}, waited > WATCH_TTL_MS(${WATCH_TTL_MS}ms); ` +
+        'no completion notification will ever be delivered for it');
+    notifyOutstanding();
+}
+/**
+ * 🔴 已**停止等待**的 outstanding 条目数(workflow + bg 合计,process-lifetime 只增)。
+ * 消费方(footer / headless 退出前的收尾行)据此把「N 个后台任务已停止等待」与「都送达了」
+ * 分开渲——H1:排队与放弃对消费方必须可分辨。additive:既有计数口的语义一字节不变。
+ */
+export function outstandingAbandonedCount() {
+    return abandonedCount;
+}
+let bgDedupDropped = 0;
+let bgCrossChannelDropped = 0;
+let stuckTickResets = 0;
+let bgWatchRevivalPromoted = 0;
+let bgWatchCollectedUnprobed = 0;
+export function notificationDropCounters() {
+    return { bgDedupDropped, bgCrossChannelDropped, stuckTickResets, bgWatchRevivalPromoted, bgWatchCollectedUnprobed };
+}
 let statusProbe = null;
 let watchTimer = null;
 const WATCH_INTERVAL_MS = 5000;
@@ -386,6 +445,16 @@ const WATCH_TTL_MS = 2 * 60 * 60 * 1000; // 2h 兜底放弃(run 蒸发/owner 不
 export function installWorkflowStatusProbe(probe) {
     statusProbe = probe;
 }
+/** bg 子代生命周期号的首周期值(SendMessage 复活即 +1;wire 缺 seq ⇒ 按首周期解释)。 */
+const BG_FIRST_SEQ = 1;
+/**
+ * 🔴 notif-02:观察台账的键是 **(taskId, seq) 复合键**,不是裸 taskId。
+ * 裸 taskId 时 seq≥2 的复活周期与首周期同键 ⇒ 复活周期结构性进不了台账,而 watcher 存在的
+ * 全部理由就是「bg 完成通知 idle 期没有到达通道」—— 复活周期因此退回那条已判定不可靠的推送通道。
+ */
+function bgOutstandingKey(taskId, seq) {
+    return `${taskId}:${seq}`;
+}
 const outstandingBgTasks = new Map();
 let bgStatusProbe = null;
 /**
@@ -404,17 +473,39 @@ export function outstandingBgTaskPrompt(taskId) {
 export function installBgTaskStatusProbe(probe) {
     bgStatusProbe = probe;
 }
-/** bridge 在 Agent async_launched 回执(structured type:'agent')经过时登记。幂等;已通知不再登记。 */
-export function registerOutstandingBgTask(taskId, description, prompt) {
+/**
+ * bridge 在 Agent async_launched 回执(structured type:'agent')经过时登记。按 (taskId,seq) 幂等。
+ *
+ * 🔴 notif-02(两账分离):登记闸**不再查 `notifiedRunIds`**。那个集合是「模型通知去重」账
+ * (哪次完成已经喂给模型了),不是「是否还要观察」账;两账混用的后果是 seq≥2 的复活周期
+ * 永远登记不进来(`notifiedRunIds` 全文无 delete 站点,首周期一通知就是终身黑名单)。
+ * 首周期若确已送达,由 watcher 的收摊臂在下一拍摘除(见 `tickWatchInner` bg 半场),
+ * 代价是一次 no-op 遍历,而不是一整个完成周期的结构性缺席。
+ *
+ * 🔴 [2393] F-1:`seq` 缺席时这里仍然**按首周期解释,不在登记口猜周期号** —— 猜出来的周期号会
+ * 把「已终局任务的回执重放」也升成新周期,方向相反地造出重复通知。周期号只在 watcher 那侧、
+ * 拿到 probe 的「它又在跑」这个证据之后才前进(见 `tickWatchInner` 的收摊臂三档)。
+ *
+ * @param seq bg 子代生命周期号;wire 未带 ⇒ 按首周期(BG_FIRST_SEQ)解释,复活周期由 watcher 补。
+ */
+export function registerOutstandingBgTask(taskId, description, prompt, seq) {
     if (!taskId)
         return;
     // prompt 台账先记(与 watcher 登记的幂等早退解耦:重复回执/已通知任务的 prompt 仍要可取)。
     if (typeof prompt === 'string' && prompt.length > 0 && !bgTaskPrompts.has(taskId)) {
         bgTaskPrompts.set(taskId, prompt);
     }
-    if (notifiedRunIds.has(taskId) || outstandingBgTasks.has(taskId))
+    const cycle = typeof seq === 'number' && Number.isFinite(seq) && seq >= BG_FIRST_SEQ ? Math.floor(seq) : BG_FIRST_SEQ;
+    const key = bgOutstandingKey(taskId, cycle);
+    if (outstandingBgTasks.has(key))
         return;
-    outstandingBgTasks.set(taskId, { registeredAt: Date.now(), description });
+    outstandingBgTasks.set(key, {
+        taskId,
+        seq: cycle,
+        registeredAt: Date.now(),
+        registeredOrder: nextLedgerOrder(),
+        description,
+    });
     ensureWatchTimer();
 }
 /** 本壳亲手启动过的 workflow run(process-lifetime,只增不摘——outstandingRuns 会随完成摘除,
@@ -446,18 +537,99 @@ function ensureWatchTimer() {
     if (watchTimer !== null)
         return;
     watchTimer = setInterval(() => {
-        void tickWatch();
+        // 定时器回调不能 await:tick 的失败必须在这里落地,否则变成 unhandledRejection 打死宿主进程。
+        tickWatch().catch(err => {
+            traceNotif(`watcher tick threw: ${err instanceof Error ? err.message : String(err)}`);
+        });
     }, WATCH_INTERVAL_MS);
-    // 不阻止进程退出
-    if (typeof watchTimer.unref === 'function') {
-        ;
-        watchTimer.unref?.();
+    // 不阻止进程退出(域词表-14:unrefTimer 单一实现)
+    unrefTimer(watchTimer);
+}
+// ── notif-01(D4 必有 settle 路径 + A5 界不得来自第三方默认值)────────────────────────────────
+// 病形:重入护栏是**不带超时的单飞**,而 tickWatchInner 里两个 `await probe(...)` 没有任何
+// deadline —— probe 由宿主注入,今天两处实装都只是 `await client.runs/workflows.get(...)`,
+// 界完全外包给了宿主的 HTTP 栈。probe 的 promise 若不 settle:护栏永久为真 ⇒ 此后每拍早退 ⇒
+// **住在 tick 里的 TTL 清扫也一并失效** ⇒ outstanding 永不清空 ⇒ watchTimer 永不停 ⇒
+// `outstandingDeliverableWorkflowCount()` 恒 >0 ⇒ headless(-p)的退出门恒真、进程永不退出。
+// 修法三件(缺一条链就还在):①每个 probe await 包 deadline;②护栏改时间戳 + 强制复位;
+// ③TTL 清扫提到护栏**之前**,让「探测卡死」不连坐「超时放弃」。
+/**
+ * 单次探测的截止。取值理由:节拍是 WATCH_INTERVAL_MS(5s),本值 = **2 个节拍**——
+ *   · 下界:比一个节拍大,慢但活着的 probe(一次往返略超 5s)不会被切成「必失败」;
+ *   · 上界:小整数倍,单个条目最坏只压住 2 拍,而不是把整条链交给宿主 HTTP 栈的默认值。
+ */
+const PROBE_TIMEOUT_MS = 2 * WATCH_INTERVAL_MS;
+/**
+ * 在飞 tick 的强制复位门。取值理由:一拍最坏耗时 ≈ 条目数 × PROBE_TIMEOUT_MS,故门必须显著
+ * 大于单条截止,否则条目一多就会误判卡死。6 倍截止 = 一拍里有 3 个条目全部吃满超时仍不算卡死。
+ * ⚠️ 复位**不能**中止那个已在飞的 tick(probe promise 不在我们手里),只是允许下一拍照常起 ——
+ * 代价是短时间内可能有两拍并发探测同一条目;相对「进程永不退出」这是明确划算的取舍,
+ * 且 `stuckTickResets` 恒应为 0,>0 说明有 probe 连 deadline 都截不住,是要查的账。
+ */
+const STUCK_TICK_RESET_MS = 6 * PROBE_TIMEOUT_MS;
+/** 测试可覆写的时序(仅测试钩写;生产恒 null ⇒ 用上面两个常量)。 */
+let probeTimeoutOverrideMs = null;
+let stuckTickResetOverrideMs = null;
+const probeTimeoutMs = () => probeTimeoutOverrideMs ?? PROBE_TIMEOUT_MS;
+const stuckTickResetMs = () => stuckTickResetOverrideMs ?? STUCK_TICK_RESET_MS;
+/**
+ * probe 超时的**类型化**错误(错误判别一律 instanceof,禁按文案前缀判)。
+ * 不导出:它只在本模块的 catch 臂之间流动,宿主注入的 probe 永远看不到它 —— 公面每多一个名字
+ * 就是多一条对外承诺,没有消费者的错误类别不该上公面(要用时再导出并同批更新导出基线)。
+ */
+class ProbeDeadlineError extends Error {
+    timeoutMs;
+    constructor(timeoutMs) {
+        super(`probe did not settle within ${timeoutMs}ms`);
+        this.name = 'ProbeDeadlineError';
+        this.timeoutMs = timeoutMs;
     }
 }
+/**
+ * 给一个不受我们控制的 promise 加一道**本仓自己声明**的界(A5)。超时 ⇒ reject
+ * `ProbeDeadlineError`,落进调用方既有的「单次探测失败」catch 臂,TTL 继续兜底。
+ * 计时器 unref(存在则),绝不因为一次探测把宿主进程钉住。
+ */
+function withProbeDeadline(p, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            reject(new ProbeDeadlineError(timeoutMs));
+        }, timeoutMs);
+        unrefTimer(timer);
+        p.then(v => {
+            clearTimeout(timer);
+            resolve(v);
+        }, e => {
+            clearTimeout(timer);
+            reject(e instanceof Error ? e : new Error(String(e)));
+        });
+    });
+}
 // 重入护栏(对抗复审§5):慢 probe(>5s)时多个 tick 并发走同一 outstanding 快照=同任务
 // 重复探测×N。单飞:在飞即跳过本 tick,下个节拍自然补上。
-let tickInFlight = false;
-async function tickWatch() {
+// 🔴 布尔改**起始时间戳**(notif-01②):布尔形没有任何复位路径能对付「await 永不返回」。
+let tickStartedAtMs = null;
+/** 在飞 tick 的世代号:强制复位后旧 tick 收口时不许清掉**新** tick 的时间戳。 */
+let tickGeneration = 0;
+/**
+ * TTL 清扫(notif-03 的单口收敛 + notif-01③ 的位置修正)。
+ * 🔴 必须在重入护栏**之前**跑:清扫住在 tickWatchInner 里时,一个卡死的 probe 会连坐 TTL,
+ * 于是「2h 上界」这个 `outstandingDeliverableWorkflowCount()` 正当性的另一半也一起失效。
+ */
+function sweepExpiredOutstanding(now) {
+    for (const [key, meta] of [...outstandingBgTasks]) {
+        if (now - meta.registeredAt > WATCH_TTL_MS)
+            abandonOutstanding('bg-task', key, 'ttl');
+    }
+    for (const [runId, registeredAt] of [...outstandingRuns]) {
+        if (now - registeredAt > WATCH_TTL_MS)
+            abandonOutstanding('workflow-run', runId, 'ttl');
+    }
+}
+/** @param nowMs 时钟注入(仅测试钩用;生产走 Date.now())。 */
+async function tickWatch(nowMs) {
+    const now = nowMs ?? Date.now();
+    sweepExpiredOutstanding(now);
     if (outstandingRuns.size === 0 && outstandingBgTasks.size === 0) {
         if (watchTimer !== null) {
             clearInterval(watchTimer);
@@ -465,63 +637,111 @@ async function tickWatch() {
         }
         return;
     }
-    if (tickInFlight)
-        return;
-    tickInFlight = true;
+    if (tickStartedAtMs !== null) {
+        if (now - tickStartedAtMs <= stuckTickResetMs())
+            return;
+        stuckTickResets++;
+        traceNotif(`forcing watcher re-entry: previous tick has been in flight for ${now - tickStartedAtMs}ms ` +
+            `(> ${stuckTickResetMs()}ms) — a probe outlived its deadline; next tick proceeds concurrently`);
+    }
+    const myGeneration = ++tickGeneration;
+    tickStartedAtMs = now;
     try {
         await tickWatchInner();
     }
     finally {
-        tickInFlight = false;
+        // 被强制复位过就别清:那面时间戳已经属于后来的那一拍了。
+        if (tickGeneration === myGeneration)
+            tickStartedAtMs = null;
     }
 }
 async function tickWatchInner() {
-    // bg agent 半场(与 workflow 半场同节拍同 TTL;probe 未装=mock/离线,只等推送补发)
+    // bg agent 半场(与 workflow 半场同节拍;TTL 已提到 tickWatch 的护栏之前统一清扫。
+    // probe 未装=mock/离线,只等推送补发)
     const bgProbe = bgStatusProbe;
-    const bgNow = Date.now();
-    for (const [taskId, meta] of [...outstandingBgTasks]) {
-        if (notifiedRunIds.has(taskId)) {
-            outstandingBgTasks.delete(taskId); // 推送/别的通道已送达 — 收摊
-            continue;
-        }
-        if (bgNow - meta.registeredAt > WATCH_TTL_MS) {
-            outstandingBgTasks.delete(taskId);
+    for (const [key, meta] of [...outstandingBgTasks]) {
+        // 🔴 [2393] F-1:收摊臂的删除必须**挣得**。此前的判据是裸 taskId 黑名单
+        // (`meta.seq <= BG_FIRST_SEQ && notifiedRunIds.has(meta.taskId)`),它只证明「这个 id 曾经
+        // 送达过某次完成」;而 `structured.seq` 缺席时复活周期的 cycle 塌回首周期,于是这条臂拿
+        // **首周期的送达记录**把**第二周期**的观察条目在下一拍秒删,probe 一次不跑 —— 与 notif-02
+        // 修前的静默丢通知逐字相同,且删在 enqueue 之前 ⇒ 三个既有计数器一格都摸不到。
+        // 新判据分三档,每一档都拿得出理由:
+        //   ① 这一周期确已送达(周期键台账)⇒ 才谈得上收摊;
+        //   ①a 条目**登记在那次送达之前** ⇒ 它就是那次送达自己的观察条目,无歧义,零成本收摊
+        //       (= 旧行为的正当那一半,常态路径,不多花一次探测);
+        //   ①b 条目**登记在送达之后** ⇒ 有歧义:复活周期?还是已终局任务的回执重放?靠 probe 定夺:
+        //   ② probe 说它**真终局** ⇒ 就是那个已送达的周期,收摊(重放回执落这里,不会二次喂模型);
+        //   ③ probe 说它**又在跑** ⇒ 这按构造是一个**新的完成周期**(裸 id 黑名单对它零判别力),
+        //      把条目升到下一个周期号继续观察,并留痕。probe 未装 ⇒ 没有可挣得的证据,沿用旧的盲摘
+        //      但记账;probe 失败/答不上来 ⇒ 不删也不升(TTL 兜底),绝不拿探测失败当终局证据。
+        const delivered = notifiedBgCycleAtLeast(meta.taskId, meta.seq);
+        if (delivered !== undefined) {
+            if (meta.registeredOrder < delivered.order) {
+                outstandingBgTasks.delete(key); // ①a 推送/别的通道已送达本条目观察的那个周期 — 收摊
+                continue;
+            }
+            if (!bgProbe) {
+                outstandingBgTasks.delete(key);
+                bgWatchCollectedUnprobed++;
+                continue;
+            }
+            let alive;
+            try {
+                const res = await withProbeDeadline(bgProbe(meta.taskId), probeTimeoutMs());
+                if (res === null || res === undefined)
+                    continue; // 答不上来 ≠ 终局,留给下一拍/TTL
+                alive = !res.terminal;
+            }
+            catch {
+                continue; // 探测失败(含 ProbeDeadlineError)不构成删除证据
+            }
+            if (!alive) {
+                outstandingBgTasks.delete(key); // 真终局 = 已送达的那个周期,收摊
+                continue;
+            }
+            const promoted = Math.max(meta.seq, delivered.cycle) + 1;
+            outstandingBgTasks.delete(key);
+            const promotedKey = bgOutstandingKey(meta.taskId, promoted);
+            if (!outstandingBgTasks.has(promotedKey)) {
+                outstandingBgTasks.set(promotedKey, { ...meta, seq: promoted, registeredOrder: nextLedgerOrder() });
+            }
+            bgWatchRevivalPromoted++;
+            traceNotif(`bg task ${meta.taskId} is running again after cycle ${meta.seq} was already delivered — ` +
+                `promoting the watch entry to cycle ${promoted} (wire carried no seq; without this the entry ` +
+                'would be collected by the bare-taskId ledger and this completion would never reach the user)');
             continue;
         }
         if (!bgProbe)
             continue;
         try {
-            const res = await bgProbe(taskId);
+            const res = await withProbeDeadline(bgProbe(meta.taskId), probeTimeoutMs());
             if (res?.terminal) {
-                outstandingBgTasks.delete(taskId);
+                outstandingBgTasks.delete(key);
                 enqueueBgChildNotification({
-                    taskId,
+                    taskId: meta.taskId,
+                    // 🔴 seq 必须透传:不带 seq 时键退化成 `taskId:1:status`,与首周期键碰撞 ⇒ 被去重臂
+                    // 静默吞掉,而台账条目已经先删了 ⇒ 该完成**永久丢失**(clay 图2 案在 watcher 车道的复刻)。
+                    seq: meta.seq,
                     status: res.status,
                     summary: `Background agent "${meta.description}" ${res.status}`,
                 });
             }
         }
         catch {
-            // 单次探测失败不放弃(网络抖动);TTL 兜底
+            // 单次探测失败(含 ProbeDeadlineError 截断)不放弃:网络抖动照旧,TTL 兜底
         }
     }
     const probe = statusProbe;
-    const now = Date.now();
-    for (const [runId, registeredAt] of [...outstandingRuns]) {
+    for (const runId of [...outstandingRuns.keys()]) {
         if (notifiedRunIds.has(runId)) {
             if (outstandingRuns.delete(runId))
                 notifyOutstanding(); // 推送/终态轮询卡已送达 —— 收摊
             continue;
         }
-        if (now - registeredAt > WATCH_TTL_MS) {
-            if (outstandingRuns.delete(runId))
-                notifyOutstanding();
-            continue;
-        }
         if (!probe)
             continue; // live client 未装(mock/离线)→ 只等推送
         try {
-            const res = await probe(runId);
+            const res = await withProbeDeadline(probe(runId), probeTimeoutMs());
             if (res?.terminal) {
                 if (outstandingRuns.delete(runId))
                     notifyOutstanding();
@@ -533,7 +753,7 @@ async function tickWatchInner() {
             }
         }
         catch {
-            // 单次探测失败不放弃(网络抖动);TTL 兜底
+            // 单次探测失败(含 ProbeDeadlineError 截断)不放弃:网络抖动照旧,TTL 兜底
         }
     }
 }
@@ -545,17 +765,27 @@ async function tickWatchInner() {
  */
 const bgNotifiedKeys = new Set();
 export function enqueueBgChildNotification(n) {
-    const key = `${n.taskId}:${n.seq ?? 1}:${n.status}`;
-    if (bgNotifiedKeys.has(key))
+    const cycle = n.seq ?? BG_FIRST_SEQ;
+    const key = `${n.taskId}:${cycle}:${n.status}`;
+    // 🔴 notif-03 同族(C5):两条静默 return 都记账 + 留痕 —— 不记账时「按设计去重」与
+    // 「seq 丢了导致完成被吞」在观测上完全等价,而后者是用户永远收不到通知的那一类。
+    if (bgNotifiedKeys.has(key)) {
+        bgDedupDropped++;
+        traceNotif(`bg notification suppressed (same key already delivered) key=${key}`);
         return;
+    }
     // cross-channel 去重(clay 2026-07-06 截图疑似双唤醒定谳):同一完成可能同时走
     // workflow_complete/probe 链(notifiedRunIds 键空间)与 bg_notification 帧——两空间互认,
     // 任一链注入过即跳过,并反向 seed。仅首周期查(revive 周期是新完成,probe 链只报首周期
     // 终态,不构成双投)。
-    if ((n.seq ?? 1) <= 1 && notifiedRunIds.has(n.taskId))
+    if (cycle <= BG_FIRST_SEQ && notifiedRunIds.has(n.taskId)) {
+        bgCrossChannelDropped++;
+        traceNotif(`bg notification suppressed (cross-channel: run already notified) taskId=${n.taskId} seq=${cycle} status=${n.status}`);
         return;
+    }
     bgNotifiedKeys.add(key);
-    notifiedRunIds.add(n.taskId);
+    // [2393] F-1:周期维必须跟着前进 —— 收摊臂删条目的唯一证据就是这一格。
+    markRunNotified(n.taskId, cycle);
     cardEnqueuedRunIds.add(n.taskId);
     // #6 通知-settle 边(合成半场):bg 子代行不再被 turn sweep 假结(session 常驻台账),真终态
     // 唯二来源 = 推送帧(bridge task_notification 臂)与本合成链(probe/fleet bg_notification 收敛点)。
@@ -584,7 +814,8 @@ export function enqueueBgChildNotification(n) {
 export function enqueueEngineWorkflowNotification(c) {
     if (notifiedRunIds.has(c.runId))
         return;
-    notifiedRunIds.add(c.runId);
+    // [2393] F-1:workflow 侧没有周期概念,周期维按首周期记(与 markEngineWorkflowNotified 同理)。
+    markRunNotified(c.runId);
     cardEnqueuedRunIds.add(c.runId);
     const message = `<${TASK_NOTIFICATION_TAG}>
 <${TASK_ID_TAG}>${escapeXml(c.runId)}</${TASK_ID_TAG}>
@@ -600,6 +831,7 @@ export function enqueueEngineWorkflowNotification(c) {
  *  🔴 生产绝不调用 —— 台账是 process-lifetime 去重的唯一凭据,清了就会双投。 */
 export function _resetEngineTaskNotificationForTest() {
     notifiedRunIds.clear();
+    notifiedBgCycleHigh.clear();
     cardEnqueuedRunIds.clear();
     outstandingRuns.clear();
     outstandingBgTasks.clear();
@@ -608,12 +840,37 @@ export function _resetEngineTaskNotificationForTest() {
     outstandingListeners.clear();
     statusProbe = null;
     bgStatusProbe = null;
-    tickInFlight = false;
+    tickStartedAtMs = null;
+    abandonedCount = 0;
+    bgDedupDropped = 0;
+    bgCrossChannelDropped = 0;
+    stuckTickResets = 0;
+    bgWatchRevivalPromoted = 0;
+    bgWatchCollectedUnprobed = 0;
+    probeTimeoutOverrideMs = null;
+    stuckTickResetOverrideMs = null;
     if (watchTimer !== null) {
         clearInterval(watchTimer);
         watchTimer = null;
     }
 }
+/**
+ * 测试钩:**驱动一拍** watcher(生产由 setInterval 驱动,外部无入口 ⇒ 护栏/TTL/deadline
+ * 三条链在门里全不可达,notif-01/-02/-03 才会一路活到今天)。
+ * @param nowMs TTL 判据的时钟注入(WATCH_TTL_MS 是 2h,不注入时钟就只能真等两小时)。
+ * 🔴 生产绝不调用。
+ */
+export async function _tickWatchOnceForTest(nowMs) {
+    await tickWatch(nowMs);
+}
+/**
+ * 测试钩:覆写 watcher 时序常量(默认是 10s/60s 量级,门里等不起)。传 null 恢复生产值。
+ * 🔴 生产绝不调用;覆写只影响 deadline 与强制复位门,不动 WATCH_INTERVAL_MS/WATCH_TTL_MS。
+ */
+export function _setWatcherTimingForTest(o) {
+    probeTimeoutOverrideMs = o?.probeTimeoutMs ?? null;
+    stuckTickResetOverrideMs = o?.stuckTickResetMs ?? null;
+}
 // ══════════════════════════════════════════════════════════════════════════════════════════════
 // ② taskNotificationErrorSupplement — S4-P3(clay 专项;取证 workflow-card-forensics,
 // 2026-07-24「workflow completed 卡下挂 API Error: 503 · draining」案):task-notification

package/dist/printToolResultFrame.d.ts

@@ -36,11 +36,19 @@
 import type { SDKMessage } from '@sema-agent/agent-types';
 /**
  * Flatten the §E1 wire `output`(NON-UNIFORM: `string` | `(TextContent|ImageContent)[]`)into one
- * plain-text blob(upstreamBridge.flattenWireOutput 同款语义的轻量副本——避免把重量级 REPL 桥
- * 拖进 `-p` 车道的 import 图)。🔴 UNTRUSTED / OBSERVABILITY-ONLY:只呈现,绝不回喂模型。
+ * plain-text blob。🔴 UNTRUSTED / OBSERVABILITY-ONLY:只呈现,绝不回喂模型。
+ *
+ * ⇄ REF-CC-008 / dup-05 兑现(ADAPT-F1,2026-08-02):此处曾是 `flattenWireOutput` 的**逐字节副本**,
+ * 豁免理由写着「避免把重量级 REPL 桥拖进 `-p` 车道的 import 图」。A 族拆分把该函数从 1607 行的
+ * `adapt.ts` 搬进了 `adapt/wireShapes.ts`,而那个文件**唯一的 import 是 `import type {Frame}`**
+ * (type-only,编译后整段消失)—— 正是台账要的那片「零 import 叶」,拆分创造了退役条件。
+ * 副本随之删除,`flattenToolOutput` 收成对唯一实现的**具名再导出**(公面名不动:它在
+ * public-export-baseline 里,改名会当场红)。
  */
-export declare function flattenToolOutput(output: unknown): string;
-/** 内部 tool_end_result arm(eventToSdkMessage.ts:213-231 铸造)的防御性读形。 */
+export { flattenWireOutput as flattenToolOutput } from './adapt/wireShapes.js';
+/** 内部 tool_end_result arm(`eventToSdkMessage.ts` 的 `case 'tool_end'` 臂铸造)的防御性读形。
+ *  ⚠️ ADAPTER-F8 注纠(2026-08-02):原文锚的是裸行号 `213-231`,A 族拆分后那段是 `case 'text'` /
+ *  `case 'reasoning'`,真正的 tool_end 臂已挪位。锚换成符号名(REF-CC-063 同款,腐烂不了)。 */
 export interface ToolEndResultArmLike {
     type?: unknown;
     toolCallId?: unknown;

package/dist/printToolResultFrame.js

@@ -1,26 +1,16 @@
 /**
  * Flatten the §E1 wire `output`(NON-UNIFORM: `string` | `(TextContent|ImageContent)[]`)into one
- * plain-text blob(upstreamBridge.flattenWireOutput 同款语义的轻量副本——避免把重量级 REPL 桥
- * 拖进 `-p` 车道的 import 图)。🔴 UNTRUSTED / OBSERVABILITY-ONLY:只呈现,绝不回喂模型。
+ * plain-text blob。🔴 UNTRUSTED / OBSERVABILITY-ONLY:只呈现,绝不回喂模型。
+ *
+ * ⇄ REF-CC-008 / dup-05 兑现(ADAPT-F1,2026-08-02):此处曾是 `flattenWireOutput` 的**逐字节副本**,
+ * 豁免理由写着「避免把重量级 REPL 桥拖进 `-p` 车道的 import 图」。A 族拆分把该函数从 1607 行的
+ * `adapt.ts` 搬进了 `adapt/wireShapes.ts`,而那个文件**唯一的 import 是 `import type {Frame}`**
+ * (type-only,编译后整段消失)—— 正是台账要的那片「零 import 叶」,拆分创造了退役条件。
+ * 副本随之删除,`flattenToolOutput` 收成对唯一实现的**具名再导出**(公面名不动:它在
+ * public-export-baseline 里,改名会当场红)。
  */
-export function flattenToolOutput(output) {
-    if (typeof output === 'string')
-        return output;
-    if (Array.isArray(output)) {
-        const parts = [];
-        for (const block of output) {
-            if (block && typeof block === 'object') {
-                const b = block;
-                if (b.type === 'text' && typeof b.text === 'string')
-                    parts.push(b.text);
-                else if (b.type === 'image')
-                    parts.push('[image]');
-            }
-        }
-        return parts.join('');
-    }
-    return '';
-}
+export { flattenWireOutput as flattenToolOutput } from './adapt/wireShapes.js';
+import { flattenWireOutput } from './adapt/wireShapes.js';
 /**
  * Bash 臂的 is_error 派生(真行为实证,2026-07-16):引擎 tool_end.isError 语义 = 「工具本身
  * 是否执行失败」——命令非零退出时工具照常返回模型面框架文本(core runShell `exit code: N\n---
@@ -50,7 +40,7 @@ function bashExitCodeFailed(toolName, text, structured) {
 export function toolEndResultToUserFrame(arm) {
     if (typeof arm.toolCallId !== 'string' || arm.toolCallId.length === 0)
         return null;
-    const text = flattenToolOutput(arm.output);
+    const text = flattenWireOutput(arm.output);
     return {
         type: 'user',
         message: {

package/dist/retainBackgroundWireCaps.d.ts

@@ -44,7 +44,8 @@ import { type EnvLike } from './hostEnv.js';
 export declare const RETAIN_BACKGROUND_ENV: "SEMA_RETAIN_BACKGROUND";
 /**
  * ENV source → `true`(缺省 ON = CC `run_in_background` 契约:后台进程活过当轮),
- * 只有显式 falsy 逃生口(`SEMA_RETAIN_BACKGROUND=0|false|no|off`)⇒ `undefined`(不 stamp ⇒ 引擎缺省 reap)。
- * 返回型刻意是 `true | undefined` —— 服务端 `raw !== true ⇒ 丢弃`,opt-out 只能表达为「不 stamp」。
+ * 只有显式 falsy 逃生口({@link envFlagOff} 拼写集,REF-CC-141 dup-02 单源)⇒ `undefined`
+ * (不 stamp ⇒ 引擎缺省 reap)。返回型刻意是 `true | undefined` —— 服务端 `raw !== true ⇒ 丢弃`,
+ * opt-out 只能表达为「不 stamp」。
  */
 export declare function retainBackgroundFromEnv(env?: EnvLike): true | undefined;

package/dist/retainBackgroundWireCaps.js

@@ -39,20 +39,16 @@
  * PURE — callers pass `env`;caller gates to LIVE mode(mock request shape 不变)。
  */
 import { hostEnv } from './hostEnv.js';
+import { envFlagOff } from './envFlag.js';
 /** The env key the shell reads(SEMA_ 命名空间,与引擎自己的 spec∨env 通道正交——这里是壳→
  *  TaskRequest 的 per-request 意图面,非引擎部署面)。 */
 export const RETAIN_BACKGROUND_ENV = 'SEMA_RETAIN_BACKGROUND';
-/** FALSY spellings that opt OUT (case-insensitive, trimmed). Conservative allowlist —— 只有这些
- *  拼写能关掉 retain;其它一切(含未识别值/空串)落缺省 ON,绝不静默 opt-out。 */
-function isFalsy(v) {
-    const s = typeof v === 'string' ? v.trim().toLowerCase() : '';
-    return s === '0' || s === 'false' || s === 'no' || s === 'off';
-}
 /**
  * ENV source → `true`(缺省 ON = CC `run_in_background` 契约:后台进程活过当轮),
- * 只有显式 falsy 逃生口(`SEMA_RETAIN_BACKGROUND=0|false|no|off`)⇒ `undefined`(不 stamp ⇒ 引擎缺省 reap)。
- * 返回型刻意是 `true | undefined` —— 服务端 `raw !== true ⇒ 丢弃`,opt-out 只能表达为「不 stamp」。
+ * 只有显式 falsy 逃生口({@link envFlagOff} 拼写集,REF-CC-141 dup-02 单源)⇒ `undefined`
+ * (不 stamp ⇒ 引擎缺省 reap)。返回型刻意是 `true | undefined` —— 服务端 `raw !== true ⇒ 丢弃`,
+ * opt-out 只能表达为「不 stamp」。
  */
 export function retainBackgroundFromEnv(env = hostEnv()) {
-    return isFalsy(env[RETAIN_BACKGROUND_ENV]) ? undefined : true;
+    return envFlagOff(env[RETAIN_BACKGROUND_ENV]) ? undefined : true;
 }