@sema-agent/client-core 0.3.0 → 0.4.0

package/dist/modelWireCaps.js

@@ -0,0 +1,16 @@
+/**
+ * ⇄ B2 批搬迁(2026-07-27,多端改造设计稿 §3 B2):cli src/sema/modelWireCaps.ts 逐字搬入(零依赖)。
+ */
+/**
+ * src/sema/modelWireCaps.ts — PURE per-turn /model projection (CC /model picker parity). seamQuery imports it.
+ *
+ * The mid-session model lives at `AppState`/`toolUseContext.options.mainLoopModel` (the /model picker writes it,
+ * query.ts). sema's engine ALREADY consumes a top-level `body.model` (service resolveTaskModel main.ts:1217 →
+ * core `TaskSpec.model`, catalog-gated, body.model wins over @mention wins over default). Without this wire a
+ * mid-session /model switch did NOTHING on the live engine (the survey's biggest functional hole). config-class
+ * intent → tighten/select only (the service catalog-gates an out-of-roster pick), so it rides the wire directly.
+ */
+/** Project the client's selected model → the wire intent. Non-empty string carried verbatim; else no stamp. */
+export function modelFromAppState(model) {
+    return typeof model === 'string' && model.trim().length > 0 ? { model: model.trim() } : {};
+}

package/dist/notifications.d.ts

@@ -1,7 +1,3 @@
-/**
- * 通知投影纯函数(抽自 sema-cli engineTaskNotification/upstreamBridge 通知臂;
- * result 段纪律=cli #49 C1:帧带 result 必入 XML,core renderTaskNotificationXml 同名 tag 同段序)。
- */
 /**
  * ⚠️ 调用方契约(交叉复审 [MED] 登记):cli 原版在渲染前有两条默认值回填——
  *   summary 缺省 ⇒ `Background task "${taskId}" ${status}`;status 非串 ⇒ 'completed'。
@@ -53,3 +49,153 @@ export declare function taskNotificationDedupKey(n: {
     seq?: number | string;
     taskType?: string;
 }): string;
+/** 宿主队列条目的最小结构形(壳 QueuedCommand 的子集;本包只读这三个键)。 */
+export interface QueuedCommandLike {
+    mode?: unknown;
+    agentId?: unknown;
+    value?: unknown;
+}
+export interface NotificationQueuePort {
+    /** 壳 = messageQueueManager.enqueuePendingNotification(无显式优先级 ⇒ 队列缺省 'later')。 */
+    enqueuePendingNotification(command: {
+        value: string;
+        mode: 'task-notification';
+    }): void;
+    /** 壳 = messageQueueManager.removeByFilter;返回被摘掉的条目(数量是判据)。 */
+    removeByFilter(predicate: (cmd: QueuedCommandLike) => boolean): QueuedCommandLike[];
+}
+/** 宿主装配:壳侧 shim / web 宿主在**模块加载期**装(装之前的调用会计入 miss)。 */
+export declare function installNotificationQueuePort(port: NotificationQueuePort | null): void;
+/** 🔴 未注入队列口而发生的投递次数 —— 恒应为 0;>0 = 宿主装配漏了,通知已静默丢失。 */
+export declare function notificationQueuePortMisses(): number;
+/** 测试钩:清 port + miss 计数(不动台账,台账各有自己的 reset)。 */
+export declare function _resetNotificationQueuePortForTest(): void;
+/**
+ * B1(frame-lane-matrix 三节定谳)— Path A 回声到达时丢弃同 run 的 pending 队列条目。
+ * 双投机理:活跃 turn 内 Path B(workflow_complete/bg_notification/probe feeder →
+ * enqueuePendingNotification)先入队,Path A(引擎 server-side steer-inject 的
+ * task_notification 回声帧)随流到达——引擎侧模型已收到一遍;turn 收口 idle 排水若再
+ * auto-submit 队列条目 = 模型二收同一份 XML。壳撤不回引擎侧注入(跨进程),但能在
+ * drain 前把已被回声证实送达的同 run 队列条目丢掉。键空间 = 裸 taskId/runId(与
+ * notifiedRunIds/cardEnqueuedRunIds 同域);条目匹配按队列 XML 的 <task-id> 标签
+ * (enqueue 两族与 bridge 渲染同用 escapeXml,键形字节对齐)。仅主线程 task-notification
+ * 条目(agentId undefined);用户输入/其他模式绝不触碰。
+ */
+export declare function dropQueuedNotificationsForRun(taskId: string): number;
+/**
+ * Pre-seed the runId dedup WITHOUT enqueueing — the completion already reached the model in-band
+ * (clay 2026-07-04 复审:模型用 TaskOutput 轮询拿到 workflow 终态并当轮总结完;引擎 completion inbox
+ * 不知道"轮询已送达",下一次开流仍补发 workflow_complete —— 对模型是纯重复,还触发一轮"这是补发通知,
+ * 无需重复"的空转)。终态在 turn 内经过壳的投影(TaskOutput workflow 终态卡 / 引擎 server-side 已
+ * steer-inject 的 task_notification 帧)即预标记,Channel A 对同 runId 的补发直接丢弃。
+ */
+export declare function markEngineWorkflowNotified(runId: string): void;
+export declare function isWorkflowCompletionCardEnqueued(runId: string): boolean;
+type WorkflowStatusProbe = (runId: string) => Promise<{
+    terminal: boolean;
+    status: 'completed' | 'failed';
+    summary: string;
+} | null>;
+export declare function outstandingWorkflowCount(): number;
+/** headless(-p)退出门用([1340] BGB 分化案):**可送达**的 outstanding 数——probe 未装
+ *  (mock/离线)恒 0,print 驱动器不为永远等不到的通知悬置;probe 在装则 watcher 5s 节拍
+ *  必然送达或 TTL 放弃(2h 上界=run 蒸发极端形,与 CC 等本地 bg 任务的无界形同族)。 */
+export declare function outstandingDeliverableWorkflowCount(): number;
+export declare function subscribeOutstandingWorkflows(listener: () => void): () => void;
+/** liveClient 在构造会话 client 时注册(带正确 baseUrl/token/principal 的 workflows.get)。 */
+export declare function installWorkflowStatusProbe(probe: WorkflowStatusProbe): void;
+type BgTaskStatusProbe = (taskId: string) => Promise<{
+    terminal: boolean;
+    status: string;
+} | null>;
+export declare function installBgTaskStatusProbe(probe: BgTaskStatusProbe): void;
+/** bridge 在 Agent async_launched 回执(structured type:'agent')经过时登记。幂等;已通知不再登记。 */
+export declare function registerOutstandingBgTask(taskId: string, description: string): void;
+export declare function isOwnWorkflowRun(runId: string): boolean;
+/** 本壳亲手启动过的 workflow run 列表(Set 插入序 = 启动序;/workflows 命令的目标 run 选择用,
+ *  cmd-workflows.tsx——fleet source 无行可选时的兜底 id 源)。 */
+export declare function listOwnWorkflowRuns(): string[];
+/** bridge 在 run_workflow 回执(structured type:'workflow-run')经过时登记。幂等;已通知的不再登记。 */
+export declare function registerOutstandingWorkflowRun(runId: string): void;
+export interface EngineWorkflowCompletion {
+    runId: string;
+    status: 'completed' | 'failed';
+    summary: string;
+}
+export declare function enqueueBgChildNotification(n: {
+    taskId: string;
+    status: string;
+    /** bg 子代生命周期号(SendMessage 复活即 +1;service seq 字段)。去重键必须含 seq——
+     *  revive 周期(seq≥2)与首周期同 (taskId,status),不带 seq 会被首周期键吞掉
+     *  =「续派后完成通知永不上屏」(clay 图2 案根因,core1.355 复验帧实锤 2026-07-20)。 */
+    seq?: number;
+    summary?: string;
+}): void;
+export declare function enqueueEngineWorkflowNotification(c: EngineWorkflowCompletion): void;
+/** 测试钩(B2 新增,壳侧原文件没有):清空全部通知台账 + probe 槽 + watcher。
+ *  🔴 生产绝不调用 —— 台账是 process-lifetime 去重的唯一凭据,清了就会双投。 */
+export declare function _resetEngineTaskNotificationForTest(): void;
+/** 该 objective 是否为 task-notification 自动提交 turn 的注入 XML(整体即通知,非提及)。 */
+export declare function isTaskNotificationObjective(objective: unknown): boolean;
+/**
+ * 通知 turn → supplement 文案(非通知 turn → undefined,判别不扩散)。措辞英文、CC 报错语气
+ * (事实 + 出路,不惊悚)。status 从 XML `<status>` 读:completed 用定稿句;其余终态如实带
+ * status(通知可能报 failed/killed —— 谎称 completed 比不加更糟)。
+ */
+export declare function taskNotificationDeliverySupplement(objective: unknown): string | undefined;
+/**
+ * API-error 行文拆分(渲染层消费):尾部的 supplement 行(若在)分离出来渲 dim,main 保留原始
+ * error 字面渲红。无 supplement 的行原样返回 —— 既有 API-error 渲染路径零改变。
+ */
+export declare function splitApiErrorSupplement(text: string): {
+    main: string;
+    supplement?: string;
+};
+/** SSE 平铺 wire 形(server 1.280.0 http/server.js:6347-6355 直证;ownerScope/ownerSessionId 上 wire 前剥掉)。 */
+export interface HookNoticeWire {
+    type?: unknown;
+    kind?: unknown;
+    event?: unknown;
+    reason?: unknown;
+    detail?: unknown;
+    ts?: unknown;
+}
+export type HookNoticeReason = 'no_content' | 'unparsed' | 'skipped';
+/** ActiveGoal.lastNotice 的形(壳 state/AppStateStore.ts 同步声明)。 */
+export interface GoalHookNotice {
+    reason: HookNoticeReason;
+    detail?: string;
+    at: number;
+}
+/** 判定结果:ok=true 才交给宿主写 store;drop 原因供宿主打 SEMA_DEBUG 档(壳侧文案不变)。 */
+export type HookNoticeVerdict = {
+    ok: true;
+    notice: GoalHookNotice;
+    event: 'Stop';
+} | {
+    ok: false;
+    drop: 'not-hook-notice' | 'unknown-kind' | 'not-session-scoped' | 'non-stop-event';
+    kind?: string;
+    event?: string;
+    reason?: HookNoticeReason;
+};
+/**
+ * hook_notice 帧的判定本体(壳 ingestHookNoticeFrame 的判定半场逐字等价)。
+ * 🔴 归属镜像在**这里**做而不是在 fleetClient 里做 —— #105 变异普查(F3)定谳过:分发条件留在
+ * fleetClient 时,离线门只能 grep 源码,而 grep 对「把 'hook_notice' 改成 'hook_noticeZZZ'」
+ * 这类变异因注释碰撞+子串命中恒绿。提到这里后离线门直接**行为测本函数**。
+ */
+export declare function classifyHookNoticeFrame(frame: unknown, opts: {
+    sessionScoped: boolean;
+    now?: number;
+}): HookNoticeVerdict;
+/** 判别口:是不是 hook_notice 帧(宿主 fleet applyFrame 的分发条件;不是则继续走别的臂)。 */
+export declare function isHookNoticeFrame(frame: unknown): boolean;
+/**
+ * 「Last check」行的诚实文案([1790] 措辞纪律:「本轮未能评估,已放行」方向;detail 是 server
+ * 结构化日志同源的机器话,dim 展示原文比意译更可追责)。
+ */
+export declare function hookNoticeLastCheckText(n: GoalHookNotice): string;
+/** footer 通知条文案前缀(测试锁字面;宿主拼 ` (${reason})`)。 */
+export declare const HOOK_NOTICE_WARN_PREFIX = "Goal check: couldn't evaluate this turn \u2014 proceeded";
+export {};

package/dist/notifications.js

@@ -1,7 +1,11 @@
 /**
  * 通知投影纯函数(抽自 sema-cli engineTaskNotification/upstreamBridge 通知臂;
  * result 段纪律=cli #49 C1:帧带 result 必入 XML,core renderTaskNotificationXml 同名 tag 同段序)。
+ * 0.4.0(B2 批)起本模块还含:engineTaskNotification 全文(台账/watcher/入队合成)、
+ * taskNotificationErrorSupplement 全文、hookNoticeStore 的判定半场 —— 见文件下半的 B2 分节。
  */
+import { hostEnv } from './hostEnv.js';
+import { clearEnginePanelTaskResident, publishEngineAgentPanelEvent, } from './engineAgentPanelStore.js';
 function escapeXml(v) {
     return v.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
 }
@@ -95,3 +99,471 @@ export function taskNotificationDedupKey(n) {
     const lane = n.taskType === 'external' ? 'external:' : '';
     return `${lane}${n.taskId}:${n.status}${seq ? `:${seq}` : ''}`;
 }
+// ══════════════════════════════════════════════════════════════════════════════════════════════
+// ⇄ B2 批搬迁(2026-07-27,多端改造设计稿 §3 B2「通知族合并」):cli 三个文件并入本模块
+//   ① src/sema/engineTaskNotification.ts(347 行,台账 + watcher + 入队合成)
+//   ② src/sema/taskNotificationErrorSupplement.ts(58 行,纯函数)
+//   ③ src/sema/hookNoticeStore.ts(177 行)的**判定半场**(store 写入半场留宿主)
+// 🔴 单实例纪律(B1 血泪同款):①带 11 个模块级台账(notifiedRunIds / cardEnqueuedRunIds /
+//   outstandingRuns / outstandingBgTasks / ownWorkflowRuns / bgNotifiedKeys / 两个 probe 槽 /
+//   listener 集 / watchTimer / tickInFlight)—— 写口(bridge 登记、probe 安装)与读口
+//   (footer outstanding 计数、fleet own 判别、去重)必须解析到**同一个包实例**。
+// 🔴 队列口(messageQueueManager)是宿主件:本包不 import 壳的队列,改成**注入 port**
+//   (设计稿原文「messageQueueManager 调用 ⇒ chrome 事件」的等价实现:先给最小注入口,
+//   chrome 事件化留给 B3 的 AdapterContext 扩容)。**未注入 = 通知投递静默丢失**,所以
+//   miss 有计数 + 一次性告警,绝不让它悄悄消失(a0110e88 零渲染案的教训:配对机制必须共享前提)。
+// ══════════════════════════════════════════════════════════════════════════════════════════════
+// cli src/constants/xml.ts 的四个 tag 常量(值逐字对齐;本包不引壳的 constants 桶)。
+const TASK_NOTIFICATION_TAG = 'task-notification';
+const TASK_ID_TAG = 'task-id';
+const STATUS_TAG = 'status';
+const SUMMARY_TAG = 'summary';
+let queuePort = null;
+let queuePortMisses = 0;
+let queuePortWarned = false;
+/** 宿主装配:壳侧 shim / web 宿主在**模块加载期**装(装之前的调用会计入 miss)。 */
+export function installNotificationQueuePort(port) {
+    queuePort = port;
+}
+/** 🔴 未注入队列口而发生的投递次数 —— 恒应为 0;>0 = 宿主装配漏了,通知已静默丢失。 */
+export function notificationQueuePortMisses() {
+    return queuePortMisses;
+}
+function port() {
+    if (queuePort)
+        return queuePort;
+    queuePortMisses++;
+    if (!queuePortWarned) {
+        queuePortWarned = true;
+        // eslint-disable-next-line no-console
+        console.error('[client-core] notification queue port NOT installed — task-notification delivery is being dropped. ' +
+            'Host must call installNotificationQueuePort() at startup (see notifications.ts B2 section).');
+    }
+    return null;
+}
+/** 测试钩:清 port + miss 计数(不动台账,台账各有自己的 reset)。 */
+export function _resetNotificationQueuePortForTest() {
+    queuePort = null;
+    queuePortMisses = 0;
+    queuePortWarned = false;
+}
+// ══════════════════════════════════════════════════════════════════════════════════════════════
+// ① engineTaskNotification — engine-side background-run completion → CC `<task-notification>` injection.
+//
+// The service pushes a `workflow_complete` named SSE frame (service 1.75, `{runId, status, summary}` —
+// an explicit whitelist) onto the session's NEXT `/v1/tasks/stream` connection when a background
+// workflow it launched earlier finishes out-of-band. The shell turns that frame into CC's OWN
+// remote-task completion mechanism (the RemoteAgentTask `enqueueRemoteNotification` precedent,
+// CC 187 `Nco`): build the `<task-notification>` XML, enqueue it as a `task-notification` queued
+// command, and let CC's native drain / queue processor (idle → auto-submit) deliver it to the model.
+// No explicit priority — CC's RemoteAgentTask enqueues WITHOUT one, so the queue default ('later',
+// messageQueueManager: "so user input is never starved") applies; 'next' is the LocalShellTask/
+// MONITOR_TOOL precedent, not the remote-completion one (adversarial review w0zwpa251 §5).
+//
+// Dedup: CC marks the task registry entry `notified` — an engine workflow has no registry entry, so a
+// PROCESS-LIFETIME Set on runId does the same job (the service inbox is at-least-once; its enqueue is
+// runId-idempotent across restarts, this Set covers redelivery within one shell process).
+//
+// No `<output-file>` line: CC's output-file points at a LOCAL task output file (getTaskOutputPath);
+// an engine run has none — the SDK-exit regex reads tags independently, an absent tag is undefined
+// (the `<tool-use-id>` line is optional in CC's own template the same way).
+// ══════════════════════════════════════════════════════════════════════════════════════════════
+const notifiedRunIds = new Set();
+/**
+ * B1(frame-lane-matrix 三节定谳)— Path A 回声到达时丢弃同 run 的 pending 队列条目。
+ * 双投机理:活跃 turn 内 Path B(workflow_complete/bg_notification/probe feeder →
+ * enqueuePendingNotification)先入队,Path A(引擎 server-side steer-inject 的
+ * task_notification 回声帧)随流到达——引擎侧模型已收到一遍;turn 收口 idle 排水若再
+ * auto-submit 队列条目 = 模型二收同一份 XML。壳撤不回引擎侧注入(跨进程),但能在
+ * drain 前把已被回声证实送达的同 run 队列条目丢掉。键空间 = 裸 taskId/runId(与
+ * notifiedRunIds/cardEnqueuedRunIds 同域);条目匹配按队列 XML 的 <task-id> 标签
+ * (enqueue 两族与 bridge 渲染同用 escapeXml,键形字节对齐)。仅主线程 task-notification
+ * 条目(agentId undefined);用户输入/其他模式绝不触碰。
+ */
+export function dropQueuedNotificationsForRun(taskId) {
+    const needle = `<${TASK_ID_TAG}>${escapeXml(taskId)}</${TASK_ID_TAG}>`;
+    const p = port();
+    if (!p)
+        return 0;
+    const dropped = p.removeByFilter(cmd => cmd.mode === 'task-notification' &&
+        cmd.agentId === undefined &&
+        typeof cmd.value === 'string' &&
+        cmd.value.includes(needle));
+    // 🔴 a0110e88 零渲染案(clay 1.0.55 真机):删掉的条目正是 cardEnqueuedRunIds
+    // 记号所指的「会渲卡的队列条目」——条目死了记号还在,推送帧的渲染臂会按记号 break,两条渲染路
+    // 互相踢皮球 = UI 永远没有这条通知。删除成功必须同时交还卡所有权(清记号),让帧臂渲染。
+    // 模型面不受影响:core 文档化设计(task-notification.ts design/116 §7)保证 turn 边界 steer
+    // 注入,引擎侧单投成立;这里只救 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`);
+        }
+    }
+    return dropped.length;
+}
+/**
+ * Pre-seed the runId dedup WITHOUT enqueueing — the completion already reached the model in-band
+ * (clay 2026-07-04 复审:模型用 TaskOutput 轮询拿到 workflow 终态并当轮总结完;引擎 completion inbox
+ * 不知道"轮询已送达",下一次开流仍补发 workflow_complete —— 对模型是纯重复,还触发一轮"这是补发通知,
+ * 无需重复"的空转)。终态在 turn 内经过壳的投影(TaskOutput workflow 终态卡 / 引擎 server-side 已
+ * steer-inject 的 task_notification 帧)即预标记,Channel A 对同 runId 的补发直接丢弃。
+ */
+export function markEngineWorkflowNotified(runId) {
+    notifiedRunIds.add(runId);
+    if (outstandingRuns.delete(runId))
+        notifyOutstanding();
+}
+/** 双通道「完成卡」去重(clay dogfood 2026-07-19 双通知案):与 notifiedRunIds(模型通知去重,
+ *  external mark 也写它)**分键**——本集只由 probe 合成 enqueue 写入(workflow+bg agent 两族,
+ *  对抗复审§1:bg 合成不写此集时 probe 先到→后到推送帧仍渲第二张卡)、只由推送帧渲染前读,
+ *  故 external 先到的 mark 不会误吞后到的内部帧(dedup-lane 单测双向钉)。 */
+const cardEnqueuedRunIds = new Set();
+export function isWorkflowCompletionCardEnqueued(runId) {
+    return cardEnqueuedRunIds.has(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)。仅通知计数变化。
+const outstandingListeners = new Set();
+function notifyOutstanding() {
+    for (const l of [...outstandingListeners]) {
+        try {
+            l();
+        }
+        catch {
+            /* 订阅方异常不拖累通知链 */
+        }
+    }
+}
+export function outstandingWorkflowCount() {
+    return outstandingRuns.size;
+}
+/** headless(-p)退出门用([1340] BGB 分化案):**可送达**的 outstanding 数——probe 未装
+ *  (mock/离线)恒 0,print 驱动器不为永远等不到的通知悬置;probe 在装则 watcher 5s 节拍
+ *  必然送达或 TTL 放弃(2h 上界=run 蒸发极端形,与 CC 等本地 bg 任务的无界形同族)。 */
+export function outstandingDeliverableWorkflowCount() {
+    return statusProbe ? outstandingRuns.size : 0;
+}
+export function subscribeOutstandingWorkflows(listener) {
+    outstandingListeners.add(listener);
+    return () => {
+        outstandingListeners.delete(listener);
+    };
+}
+let statusProbe = null;
+let watchTimer = null;
+const WATCH_INTERVAL_MS = 5000;
+const WATCH_TTL_MS = 2 * 60 * 60 * 1000; // 2h 兜底放弃(run 蒸发/owner 不可读时不永轮)
+/** liveClient 在构造会话 client 时注册(带正确 baseUrl/token/principal 的 workflows.get)。 */
+export function installWorkflowStatusProbe(probe) {
+    statusProbe = probe;
+}
+const outstandingBgTasks = new Map();
+let bgStatusProbe = null;
+export function installBgTaskStatusProbe(probe) {
+    bgStatusProbe = probe;
+}
+/** bridge 在 Agent async_launched 回执(structured type:'agent')经过时登记。幂等;已通知不再登记。 */
+export function registerOutstandingBgTask(taskId, description) {
+    if (!taskId || notifiedRunIds.has(taskId) || outstandingBgTasks.has(taskId))
+        return;
+    outstandingBgTasks.set(taskId, { registeredAt: Date.now(), description });
+    ensureWatchTimer();
+}
+/** 本壳亲手启动过的 workflow run(process-lifetime,只增不摘——outstandingRuns 会随完成摘除,
+ *  这个集合是 fleet 行渲染的 own 判别台账;clay 2026-07-23 双 session 串扰案:旧代际引擎对
+ *  fleet 行帧广播,workflow 行必须有壳侧行级判别兜底,与 bg_notification 的 isOwnEngineRun
+ *  台账对称)。诚实边界同款:壳重启/resume 后旧 workflow 行在老引擎下会被藏(1.244+ server
+ *  已按会话过滤=sessionScoped 让位,不受此限)。 */
+const ownWorkflowRuns = new Set();
+export function isOwnWorkflowRun(runId) {
+    return ownWorkflowRuns.has(runId);
+}
+/** 本壳亲手启动过的 workflow run 列表(Set 插入序 = 启动序;/workflows 命令的目标 run 选择用,
+ *  cmd-workflows.tsx——fleet source 无行可选时的兜底 id 源)。 */
+export function listOwnWorkflowRuns() {
+    return [...ownWorkflowRuns];
+}
+/** bridge 在 run_workflow 回执(structured type:'workflow-run')经过时登记。幂等;已通知的不再登记。 */
+export function registerOutstandingWorkflowRun(runId) {
+    if (!runId)
+        return;
+    ownWorkflowRuns.add(runId); // own 台账先记(与 outstanding 摘除解耦)
+    if (notifiedRunIds.has(runId) || outstandingRuns.has(runId))
+        return;
+    outstandingRuns.set(runId, Date.now());
+    notifyOutstanding();
+    ensureWatchTimer();
+}
+function ensureWatchTimer() {
+    if (watchTimer !== null)
+        return;
+    watchTimer = setInterval(() => {
+        void tickWatch();
+    }, WATCH_INTERVAL_MS);
+    // 不阻止进程退出
+    if (typeof watchTimer.unref === 'function') {
+        ;
+        watchTimer.unref?.();
+    }
+}
+// 重入护栏(对抗复审§5):慢 probe(>5s)时多个 tick 并发走同一 outstanding 快照=同任务
+// 重复探测×N。单飞:在飞即跳过本 tick,下个节拍自然补上。
+let tickInFlight = false;
+async function tickWatch() {
+    if (outstandingRuns.size === 0 && outstandingBgTasks.size === 0) {
+        if (watchTimer !== null) {
+            clearInterval(watchTimer);
+            watchTimer = null;
+        }
+        return;
+    }
+    if (tickInFlight)
+        return;
+    tickInFlight = true;
+    try {
+        await tickWatchInner();
+    }
+    finally {
+        tickInFlight = false;
+    }
+}
+async function tickWatchInner() {
+    // bg agent 半场(与 workflow 半场同节拍同 TTL;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);
+            continue;
+        }
+        if (!bgProbe)
+            continue;
+        try {
+            const res = await bgProbe(taskId);
+            if (res?.terminal) {
+                outstandingBgTasks.delete(taskId);
+                enqueueBgChildNotification({
+                    taskId,
+                    status: res.status,
+                    summary: `Background agent "${meta.description}" ${res.status}`,
+                });
+            }
+        }
+        catch {
+            // 单次探测失败不放弃(网络抖动);TTL 兜底
+        }
+    }
+    const probe = statusProbe;
+    const now = Date.now();
+    for (const [runId, registeredAt] of [...outstandingRuns]) {
+        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);
+            if (res?.terminal) {
+                if (outstandingRuns.delete(runId))
+                    notifyOutstanding();
+                enqueueEngineWorkflowNotification({
+                    runId,
+                    status: res.status,
+                    summary: res.summary,
+                });
+            }
+        }
+        catch {
+            // 单次探测失败不放弃(网络抖动);TTL 兜底
+        }
+    }
+}
+/**
+ * bg_notification 帧桥([446] 帧契约,service 1.119 上线):session 级后台子代的
+ * 完成/终态通知走常开 fleet lane → 这里转入 #21 的 pending-notification 注入链
+ * (idle 自动注入,彻底关掉「bg 完成通知等下次输入才 drain」的死窗)。
+ * (taskId,status) 去重=外圈皮带(durable park 腿重放/at-least-once 双投自免)。
+ */
+const bgNotifiedKeys = new Set();
+export function enqueueBgChildNotification(n) {
+    const key = `${n.taskId}:${n.seq ?? 1}:${n.status}`;
+    if (bgNotifiedKeys.has(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))
+        return;
+    bgNotifiedKeys.add(key);
+    notifiedRunIds.add(n.taskId);
+    cardEnqueuedRunIds.add(n.taskId);
+    // #6 通知-settle 边(合成半场):bg 子代行不再被 turn sweep 假结(session 常驻台账),真终态
+    // 唯二来源 = 推送帧(bridge task_notification 臂)与本合成链(probe/fleet bg_notification 收敛点)。
+    // 消费端 settle 幂等(running 才动),推送帧先到时此发布为 no-op。
+    try {
+        clearEnginePanelTaskResident(n.taskId);
+        publishEngineAgentPanelEvent({
+            kind: 'end',
+            taskId: n.taskId,
+            isError: n.status === 'failed' || n.status === 'killed',
+        });
+    }
+    catch {
+        /* fail-soft — 面板 settle 失败绝不挡模型通知注入 */
+    }
+    const message = `<${TASK_NOTIFICATION_TAG}>
+<${TASK_ID_TAG}>${escapeXml(n.taskId)}</${TASK_ID_TAG}>
+<${STATUS_TAG}>${escapeXml(n.status)}</${STATUS_TAG}>
+<${SUMMARY_TAG}>${escapeXml(n.summary ?? `Background agent ${n.status}`)}</${SUMMARY_TAG}>
+</${TASK_NOTIFICATION_TAG}>`;
+    port()?.enqueuePendingNotification({
+        value: message,
+        mode: 'task-notification',
+    });
+}
+export function enqueueEngineWorkflowNotification(c) {
+    if (notifiedRunIds.has(c.runId))
+        return;
+    notifiedRunIds.add(c.runId);
+    cardEnqueuedRunIds.add(c.runId);
+    const message = `<${TASK_NOTIFICATION_TAG}>
+<${TASK_ID_TAG}>${escapeXml(c.runId)}</${TASK_ID_TAG}>
+<${STATUS_TAG}>${c.status}</${STATUS_TAG}>
+<${SUMMARY_TAG}>${escapeXml(c.summary)}</${SUMMARY_TAG}>
+</${TASK_NOTIFICATION_TAG}>`;
+    port()?.enqueuePendingNotification({
+        value: message,
+        mode: 'task-notification',
+    });
+}
+/** 测试钩(B2 新增,壳侧原文件没有):清空全部通知台账 + probe 槽 + watcher。
+ *  🔴 生产绝不调用 —— 台账是 process-lifetime 去重的唯一凭据,清了就会双投。 */
+export function _resetEngineTaskNotificationForTest() {
+    notifiedRunIds.clear();
+    cardEnqueuedRunIds.clear();
+    outstandingRuns.clear();
+    outstandingBgTasks.clear();
+    ownWorkflowRuns.clear();
+    bgNotifiedKeys.clear();
+    outstandingListeners.clear();
+    statusProbe = null;
+    bgStatusProbe = null;
+    tickInFlight = false;
+    if (watchTimer !== null) {
+        clearInterval(watchTimer);
+        watchTimer = null;
+    }
+}
+// ══════════════════════════════════════════════════════════════════════════════════════════════
+// ② taskNotificationErrorSupplement — S4-P3(clay 专项;取证 workflow-card-forensics,
+// 2026-07-24「workflow completed 卡下挂 API Error: 503 · draining」案):task-notification
+// 自动提交 turn 的 API-error 行 supplement。
+//
+// 场景:后台 workflow/bg agent 完成 → 完成通知入队自动提交新 turn(enqueueEngineWorkflowNotification/
+// enqueueBgChildNotification → queueProcessor idle 排水)→ 该 turn 的引擎提交失败(典型:撞温切排水的
+// 503 draining,S4-P0 有界重试打光)→ CC 转录形制里 assistant error 行恒以 ⎿ 臂贴在其 user 消息
+// (= 通知卡)正下方,用户误读为「后台任务本身失败」。这里生成一句 supplement 澄清:任务本身已终态,
+// 失败的只是「把结果通知投递给模型」这一轮;/tasks 可查结果。supplement, never mask
+// (detachWire/sandboxDegradeHint 同款姿势):原始 error 行原样保留,只追加一行。
+//
+// 判别:通知 turn 的 objective 就是合成的 `<task-notification>` XML 整体(queueProcessor 自动提交,
+// user 消息 origin kind 'task-notification')——以 trimStart() 后 startsWith 判型,用户手打正文里
+// 【提到】该 tag 不误伤。
+// 渲染:AssistantTextMessage 的 API-error 臂经 splitApiErrorSupplement 把本行拆出来渲 dim。
+// ══════════════════════════════════════════════════════════════════════════════════════════════
+/** 所有 supplement 变体共享的行首 —— 渲染侧拆行锚(splitApiErrorSupplement),两侧必须同步改。 */
+const SUPPLEMENT_LINE_PREFIX = 'The background task itself ';
+/** 该 objective 是否为 task-notification 自动提交 turn 的注入 XML(整体即通知,非提及)。 */
+export function isTaskNotificationObjective(objective) {
+    return (typeof objective === 'string' &&
+        objective.trimStart().startsWith(`<${TASK_NOTIFICATION_TAG}>`));
+}
+/**
+ * 通知 turn → supplement 文案(非通知 turn → undefined,判别不扩散)。措辞英文、CC 报错语气
+ * (事实 + 出路,不惊悚)。status 从 XML `<status>` 读:completed 用定稿句;其余终态如实带
+ * status(通知可能报 failed/killed —— 谎称 completed 比不加更糟)。
+ */
+export function taskNotificationDeliverySupplement(objective) {
+    if (!isTaskNotificationObjective(objective))
+        return undefined;
+    const m = new RegExp(`<${STATUS_TAG}>([^<]*)</${STATUS_TAG}>`).exec(objective);
+    const status = m?.[1]?.trim();
+    if (status === 'completed') {
+        return `${SUPPLEMENT_LINE_PREFIX}completed — only this notification delivery failed. Check /tasks for the result.`;
+    }
+    const statusNote = status && status.length > 0 ? ` (status: ${status})` : '';
+    return `${SUPPLEMENT_LINE_PREFIX}already finished${statusNote} — only this notification delivery failed. Check /tasks for the result.`;
+}
+/**
+ * API-error 行文拆分(渲染层消费):尾部的 supplement 行(若在)分离出来渲 dim,main 保留原始
+ * error 字面渲红。无 supplement 的行原样返回 —— 既有 API-error 渲染路径零改变。
+ */
+export function splitApiErrorSupplement(text) {
+    const idx = text.lastIndexOf(`\n${SUPPLEMENT_LINE_PREFIX}`);
+    if (idx === -1)
+        return { main: text };
+    return { main: text.slice(0, idx), supplement: text.slice(idx + 1) };
+}
+const KNOWN_REASONS = new Set(['no_content', 'unparsed', 'skipped']);
+/**
+ * hook_notice 帧的判定本体(壳 ingestHookNoticeFrame 的判定半场逐字等价)。
+ * 🔴 归属镜像在**这里**做而不是在 fleetClient 里做 —— #105 变异普查(F3)定谳过:分发条件留在
+ * fleetClient 时,离线门只能 grep 源码,而 grep 对「把 'hook_notice' 改成 'hook_noticeZZZ'」
+ * 这类变异因注释碰撞+子串命中恒绿。提到这里后离线门直接**行为测本函数**。
+ */
+export function classifyHookNoticeFrame(frame, opts) {
+    const f = frame;
+    if (f?.type !== 'hook_notice')
+        return { ok: false, drop: 'not-hook-notice' };
+    if (f.kind !== 'hook_decision_unavailable') {
+        // 未来新 kind:纯 observe 道,未知即忽略(不猜语义)。
+        return { ok: false, drop: 'unknown-kind', kind: String(f.kind) };
+    }
+    // 🔴 归属镜像:server 只对 scoped 连接 fail-closed;未 scoped 连接上这帧可能是任何会话的。
+    if (!opts.sessionScoped)
+        return { ok: false, drop: 'not-session-scoped' };
+    const reason = typeof f.reason === 'string' && KNOWN_REASONS.has(f.reason)
+        ? f.reason
+        : 'skipped';
+    const event = typeof f.event === 'string' ? f.event : '';
+    // 非 Stop 事件今天没有承载面(PreToolUse 等等有承载面再接)。
+    if (event !== 'Stop')
+        return { ok: false, drop: 'non-stop-event', event, reason };
+    return {
+        ok: true,
+        event: 'Stop',
+        notice: {
+            reason,
+            ...(typeof f.detail === 'string' && f.detail ? { detail: f.detail } : {}),
+            at: typeof f.ts === 'number' ? f.ts : (opts.now ?? Date.now()),
+        },
+    };
+}
+/** 判别口:是不是 hook_notice 帧(宿主 fleet applyFrame 的分发条件;不是则继续走别的臂)。 */
+export function isHookNoticeFrame(frame) {
+    return frame?.type === 'hook_notice';
+}
+/**
+ * 「Last check」行的诚实文案([1790] 措辞纪律:「本轮未能评估,已放行」方向;detail 是 server
+ * 结构化日志同源的机器话,dim 展示原文比意译更可追责)。
+ */
+export function hookNoticeLastCheckText(n) {
+    return `couldn't evaluate this turn — proceeded (${n.reason}${n.detail ? `: ${n.detail}` : ''})`;
+}
+/** footer 通知条文案前缀(测试锁字面;宿主拼 ` (${reason})`)。 */
+export const HOOK_NOTICE_WARN_PREFIX = 'Goal check: couldn\'t evaluate this turn — proceeded';