@sema-agent/client-core 0.12.1 → 0.13.0

package/dist/liveInitToolFace.d.ts

@@ -1,3 +1,53 @@
+/**
+ * ⇄ B6 批搬迁(2026-07-27,设计稿 §3 B6 · B2 判给后批的**宿主耦合六件**之一):cli
+ *    `src/sema/liveInitToolFace.ts` 整搬。B2 当时不搬的理由 = 它 `await import('./engineTarget.js')`
+ *    取凭证,而 engineTarget 是 fs 重图;B4 的 §8-2 收编把凭证解析定到了 `resolveWireAuth`
+ *    (engineWireSdk,零依赖),那条理由随之消失。
+ *
+ * 🔴 搬迁三处差分(行为一字节不变):
+ *   ① 凭证:`engineTarget.resolveLiveAuthToken(baseUrl)`(其 token 缺省 = `process.env.SEMA_LIVE_TOKEN`)
+ *      → `resolveWireAuth(baseUrl, env.SEMA_LIVE_TOKEN)`。两者是同一套 #118 三态,`resolveWireAuth`
+ *      的头注自述就是它的收编口。取值面完全一致:三态里只有**真 token 串**与 `'anon'` 是 string,
+ *      `{mode:'loopback-unauthed'}` 是对象 ⇒ 原文那句 `typeof t === 'string' ? t : undefined` 语义照搬。
+ *   ② 三个 `await import('./xxxWire.js')` fail-soft 动态 import → **静态 import**(scenarioWire /
+ *      interactiveToolsWire / webSearchWireCaps 三件 B5 都已在本包内)。原文那三层 try/catch 的
+ *      目的是「模块缺席也别挡首帧」,包内它们不可能缺席;**try/catch 仍逐条保留**——它护的另一半是
+ *      「函数自己抛」,那半在包内照样成立。
+ *   ③ `process.env` → 入参 `EnvLike`(签名本来就显式收 env;缺省值不存在,调用方必传)。
+ *
+ * 🔴 模块级状态:`cached`(baseUrl+scenario+旋钮 键控的一次性探测缓存)。写读口都在本文件;
+ *    两份实例只是多探一次(不是静默失效),但仍登记进单实例清单。
+ *
+ * ── 以下为原文件的领域说明(逐字保留)────────────────────────────────────────────────────────
+ *
+ * liveInitToolFace — 件1(core [931] 壳半场):headless `-p` live 车道 `system/init` 首帧的
+ * `tools` 自报面,从「壳静态工具表」改为「引擎实挂 wire 词表」生成。
+ *
+ * 根因(core [931]/CC209 裁决):壳自报静态表(TodoWrite 在、TaskCreate 族不在)而引擎 wire 实挂
+ * TaskCreate 族(core 1.296+ 默认)且不挂 TodoWrite ⇒ SDK/自动化消费者照自报面配
+ * `--disallowedTools TodoWrite` 之类静默无效(fail-open)。core 1.300 已在引擎侧加名单池审计
+ * advisory(config.toolpolicy.unmatched_names)兜观测面;这里是壳半场 = 自报按实挂生成。
+ *
+ * 真源层级(gap-check 2026-07-16 实测读数,server 1.214.0 / core 1.300.0):
+ *   1. server 无全量挂载探测面:GET /v1/capabilities 只有能力布尔;
+ *      GET /v1/capabilities/scenarios/:name 只含【场景附加】工具(default/code →
+ *      Now/WebFetch/Agent/TaskCreate 族七具),首方 band(Bash/Read/…)由 core prepare-task
+ *      另挂、不进该面 ⇒ 整表无法远端取。
+ *   2. 故缺省场景用壳已知 wire 词表(下表):观测 tap 记录壳 `-p` live 车道 LLM 请求体
+ *      tools[].name(REMOTE_EXEC=host 生产姿势)实测定稿,再按壳自己 stamp 的请求旋钮修正
+ *      (interactiveTools≠false → AskUserQuestion;settings.webSearch 在 → WebSearch)。
+ *   3. per-scenario 差异如实标注:非缺省 scenario(--scenario/SEMA_HEADLESS_SCENARIO)的工具面
+ *      由部署定义(scan/oa = repo-readonly 面,首方 band 是否在位壳无法确证)⇒ 尽力探场景详情面
+ *      GET /v1/capabilities/scenarios/:name 报【场景附加】工具 + runner 恒挂段,并经
+ *      SEMA_DEBUG 如实标注是探测面而非整表;探测失败回退缺省词表(fail-soft,绝不阻塞首帧)。
+ *   4. mock/离线车道(无 SEMA_LIVE_BASEURL)返回 null,调用方保持现状静态表 —— 宪法三问的
+ *      补偿轴:离线态回退静态表,行为字节不变。
+ *
+ * 已知局限(如实):词表按 pin 的 server/core 版本定稿,外接旧引擎或无执行底座的 worker
+ * (REMOTE_EXEC 缺省的裸 worker 不挂 hands band)会有偏差 —— 但相比旧静态表(TodoWrite 幻影 +
+ * TaskCreate 族缺席)已是严格更准的自报;整表探测面等引擎侧补(见 [931] 报告)。
+ */
+import { type EngineProbeOpts } from './engineWireSdk.js';
 import type { EnvLike } from './hostEnv.js';
 /** hands band(本地/远程执行底座在位时 prepare-task 挂载;壳自 spawn 恒 REMOTE_EXEC=host ⇒ 在位)。 */
 export declare const ENGINE_HANDS_BAND: readonly string[];
@@ -30,12 +80,7 @@ export declare function _resetLiveInitToolFaceForTest(): void;
  *  maxRetries=0 单发同原语义);ScenarioDetail 类型面之外仍保留逐字段运行时校验(引擎回什么不轻信)。
  *  差分:SDK Transport 恒 stamp x-agent-principal(缺省 'anon:shell-live')——原手抄在无 principal
  *  时省略该头;principal-first 宪法姿势,对 requirePrincipal 部署是 fail-open 改善。 */
-export declare function probeScenarioTools(baseUrl: string, scenario: string, opts?: {
-    fetchImpl?: typeof fetch;
-    timeoutMs?: number;
-    authToken?: string;
-    principal?: string;
-}): Promise<{
+export declare function probeScenarioTools(baseUrl: string, scenario: string, opts?: EngineProbeOpts): Promise<{
     tools: string[];
     toolset?: string;
 } | null>;

package/dist/liveQuestionStore.d.ts

@@ -1,3 +1,4 @@
+import type { AskAnswer } from './hitl/hitlBridge.js';
 /**
  * src/sema/liveQuestionStore.ts — the SIDE-CHANNEL for §4④ live-stream AskUserQuestion (the conversation-seam
  * twin of liveSessionStore.ts).
@@ -54,13 +55,11 @@ export interface QuestionFrame {
 }
 /** The answer the overlay sends back — keyed by HEADER; `selected` echoes exact option labels
  *  (`selected ⊆ options`, core's fence); off-list / free-text input rides `note` (untrusted-fenced).
- *  Entry shape === hitlBridge's AskAnswer (the T23 ApprovalDecision.answer leg consumes it as-is). */
+ *  REF-CC-038(2026-08-02):entry 直接是 hitlBridge 的 `AskAnswer`(唯一源),不再各写一份 ——
+ *  之前这里是一份内联匿名形的独立声明,只靠注释断言与 hitlBridge 那份「形状相同」,
+ *  下游(`askGateWire.ts`)因此要 `as AskAnswer[]` 兜齐两个名不同的等价形状。 */
 export interface QuestionAnswer {
-    answers: Array<{
-        header: string;
-        selected: string[];
-        note?: string;
-    }>;
+    answers: AskAnswer[];
 }
 type QuestionFrameHandler = (frame: QuestionFrame) => void;
 type RespondFn = (id: string, answer: QuestionAnswer, opts?: {

package/dist/model/providerPresets.js

@@ -85,7 +85,17 @@ export function inferFamily(modelId) {
         const ctx = capSuffix[2] === 'm' ? n * 1000000 : n * 1024;
         const base = inferFamily(raw.replace(/\[[0-9]+[km]\]$/, ''));
         // perModelCap 透传:后缀只声明 ctx,不改该模型的确证输出 cap(deepseek-chat[1m] 仍 cap 8192)
-        return { id: base?.id ?? 'cap-suffix', name: base?.name ?? 'capacity suffix', match: '', contextWindow: ctx, maxTokens: base?.maxTokens ?? 64000, vision: base?.vision, perModelCap: base?.perModelCap };
+        // eopt:vision/perModelCap 是「缺省=未知不 stamp」的条件展开位(与 taskId/status 那种「键恒在」
+        // 公面契约不同义——那两位没有「已确认为未知」这个第三态,这两位有),诚实透传 base 的键在场与否。
+        return {
+            id: base?.id ?? 'cap-suffix',
+            name: base?.name ?? 'capacity suffix',
+            match: '',
+            contextWindow: ctx,
+            maxTokens: base?.maxTokens ?? 64000,
+            ...(base?.vision !== undefined ? { vision: base.vision } : {}),
+            ...(base?.perModelCap !== undefined ? { perModelCap: base.perModelCap } : {}),
+        };
     }
     const id = normalizeId(raw);
     // ① preset 大表精确(含剥变体尾巴后再试)——精确命中才带 perModelCap(F2 裁决封顶① 证据位;

package/dist/notifications.d.ts

@@ -176,6 +176,27 @@ export declare function outstandingWorkflowCount(): number;
  *  必然送达或 TTL 放弃(2h 上界=run 蒸发极端形,与 CC 等本地 bg 任务的无界形同族)。 */
 export declare function outstandingDeliverableWorkflowCount(): number;
 export declare function subscribeOutstandingWorkflows(listener: () => void): () => void;
+/**
+ * 🔴 已**停止等待**的 outstanding 条目数(workflow + bg 合计,process-lifetime 只增)。
+ * 消费方(footer / headless 退出前的收尾行)据此把「N 个后台任务已停止等待」与「都送达了」
+ * 分开渲——H1:排队与放弃对消费方必须可分辨。additive:既有计数口的语义一字节不变。
+ */
+export declare function outstandingAbandonedCount(): number;
+/**
+ * 观测口:被**静默 return 掉**的投递次数(notif-02)。去重与丢失在行为上都是「不入队」,
+ * 不记账就在观测上等价 —— 分成两个键是因为它们的正当性完全不同:
+ *   · `bgDedupDropped` = 同 (taskId,seq,status) 键重复,**正当**(at-least-once 双投自免),恒可 >0;
+ *   · `bgCrossChannelDropped` = 首周期已由别的通道送达而被压制,**正当但需可查**(seq 透传一旦
+ *     回归,复活周期会伪装成首周期落进这一格 —— 这个数异常增长就是 seq 又丢了的信号);
+ *   · `stuckTickResets` = 在飞 tick 超过 STUCK_TICK_RESET_MS 被强制复位的次数,**恒应为 0**;
+ *     >0 = 有 probe 连 PROBE_TIMEOUT_MS 都没能截断它。
+ */
+export interface NotificationDropCounters {
+    bgDedupDropped: number;
+    bgCrossChannelDropped: number;
+    stuckTickResets: number;
+}
+export declare function notificationDropCounters(): NotificationDropCounters;
 /** liveClient 在构造会话 client 时注册(带正确 baseUrl/token/principal 的 workflows.get)。 */
 export declare function installWorkflowStatusProbe(probe: WorkflowStatusProbe): void;
 type BgTaskStatusProbe = (taskId: string) => Promise<{
@@ -185,8 +206,18 @@ type BgTaskStatusProbe = (taskId: string) => Promise<{
 /** 委派 prompt 取件口(行消费端建行/详情页兜底用)。未登记 ⇒ undefined(诚实缺席)。 */
 export declare function outstandingBgTaskPrompt(taskId: string): string | undefined;
 export declare function installBgTaskStatusProbe(probe: BgTaskStatusProbe): void;
-/** bridge 在 Agent async_launched 回执(structured type:'agent')经过时登记。幂等;已通知不再登记。 */
-export declare function registerOutstandingBgTask(taskId: string, description: string, prompt?: string): void;
+/**
+ * bridge 在 Agent async_launched 回执(structured type:'agent')经过时登记。按 (taskId,seq) 幂等。
+ *
+ * 🔴 notif-02(两账分离):登记闸**不再查 `notifiedRunIds`**。那个集合是「模型通知去重」账
+ * (哪次完成已经喂给模型了),不是「是否还要观察」账;两账混用的后果是 seq≥2 的复活周期
+ * 永远登记不进来(`notifiedRunIds` 全文无 delete 站点,首周期一通知就是终身黑名单)。
+ * 首周期若确已送达,由 watcher 的收摊臂在下一拍摘除(见 `tickWatchInner` bg 半场),
+ * 代价是一次 no-op 遍历,而不是一整个完成周期的结构性缺席。
+ *
+ * @param seq bg 子代生命周期号;wire 未带 ⇒ 按首周期(BG_FIRST_SEQ)解释。
+ */
+export declare function registerOutstandingBgTask(taskId: string, description: string, prompt?: string, seq?: number): void;
 export declare function isOwnWorkflowRun(runId: string): boolean;
 /** 本壳亲手启动过的 workflow run 列表(Set 插入序 = 启动序;/workflows 命令的目标 run 选择用,
  *  cmd-workflows.tsx——fleet source 无行可选时的兜底 id 源)。 */
@@ -211,6 +242,21 @@ export declare function enqueueEngineWorkflowNotification(c: EngineWorkflowCompl
 /** 测试钩(B2 新增,壳侧原文件没有):清空全部通知台账 + probe 槽 + watcher。
  *  🔴 生产绝不调用 —— 台账是 process-lifetime 去重的唯一凭据,清了就会双投。 */
 export declare function _resetEngineTaskNotificationForTest(): void;
+/**
+ * 测试钩:**驱动一拍** watcher(生产由 setInterval 驱动,外部无入口 ⇒ 护栏/TTL/deadline
+ * 三条链在门里全不可达,notif-01/-02/-03 才会一路活到今天)。
+ * @param nowMs TTL 判据的时钟注入(WATCH_TTL_MS 是 2h,不注入时钟就只能真等两小时)。
+ * 🔴 生产绝不调用。
+ */
+export declare function _tickWatchOnceForTest(nowMs?: number): Promise<void>;
+/**
+ * 测试钩:覆写 watcher 时序常量(默认是 10s/60s 量级,门里等不起)。传 null 恢复生产值。
+ * 🔴 生产绝不调用;覆写只影响 deadline 与强制复位门,不动 WATCH_INTERVAL_MS/WATCH_TTL_MS。
+ */
+export declare function _setWatcherTimingForTest(o: {
+    probeTimeoutMs?: number;
+    stuckTickResetMs?: number;
+} | null): void;
 /** 该 objective 是否为 task-notification 自动提交 turn 的注入 XML(整体即通知,非提及)。 */
 export declare function isTaskNotificationObjective(objective: unknown): boolean;
 /**

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;
@@ -290,10 +302,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;
 }
@@ -351,7 +360,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 +389,34 @@ 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;
+export function notificationDropCounters() {
+    return { bgDedupDropped, bgCrossChannelDropped, stuckTickResets };
+}
 let statusProbe = null;
 let watchTimer = null;
 const WATCH_INTERVAL_MS = 5000;
@@ -386,6 +425,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 +453,29 @@ 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 遍历,而不是一整个完成周期的结构性缺席。
+ *
+ * @param seq bg 子代生命周期号;wire 未带 ⇒ 按首周期(BG_FIRST_SEQ)解释。
+ */
+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(), description });
     ensureWatchTimer();
 }
 /** 本壳亲手启动过的 workflow run(process-lifetime,只增不摘——outstandingRuns 会随完成摘除,
@@ -446,18 +507,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 +607,66 @@ 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]) {
+        // 收摊臂**只对首周期成立**:notifiedRunIds 是裸 taskId 键空间,它只证明「首周期已送达」,
+        // 对 seq≥2 的新完成周期毫无判别力(与 enqueueBgChildNotification 的跨通道臂同一前提)。
+        if (meta.seq <= BG_FIRST_SEQ && notifiedRunIds.has(meta.taskId)) {
+            outstandingBgTasks.delete(key); // 推送/别的通道已送达 — 收摊
             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 +678,7 @@ async function tickWatchInner() {
             }
         }
         catch {
-            // 单次探测失败不放弃(网络抖动);TTL 兜底
+            // 单次探测失败(含 ProbeDeadlineError 截断)不放弃:网络抖动照旧,TTL 兜底
         }
     }
 }
@@ -545,15 +690,24 @@ 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);
     cardEnqueuedRunIds.add(n.taskId);
@@ -608,12 +762,35 @@ export function _resetEngineTaskNotificationForTest() {
     outstandingListeners.clear();
     statusProbe = null;
     bgStatusProbe = null;
-    tickInFlight = false;
+    tickStartedAtMs = null;
+    abandonedCount = 0;
+    bgDedupDropped = 0;
+    bgCrossChannelDropped = 0;
+    stuckTickResets = 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/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;
 }