@sema-agent/client-core 0.3.0 → 0.5.0

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';

package/dist/permissionWireCaps.d.ts

@@ -0,0 +1,37 @@
+/**
+ * ⇄ B2 批搬迁(2026-07-27,多端改造设计稿 §3 B2):cli src/sema/permissionWireCaps.ts 逐字搬入(零依赖)。
+ */
+/**
+ * src/sema/permissionWireCaps.ts — PURE CC permission-mode INTENT projection (R4, revised per the two-axis
+ * seamless principle). seamQuery imports it.
+ *
+ * 🔴 Design (memory seamless-two-axis-wire-principle): the frontend carries the RAW permission-mode INTENT; the
+ * SERVICE interprets it (axis-aware, tighten-only). We do NOT pre-interpret `plan → enablePlanMode+handsReadOnly`
+ * on the client — that bakes policy into one frontend and would drift between the TUI shell and the web portal.
+ * Instead we stamp `permissionMode` and let the service own the interpretation (plan ⇒ present_plan + read-only;
+ * acceptEdits/bypassPermissions ⇒ loosening, coerced to default engine-side, enforced client-side). This keeps the
+ * shell a thin per-turn intent projector that's identical across TOC-local / TOB-cloud / centralized-session axes.
+ *
+ * `auto`(分类器批3,黑板 [907] server 五模式表):server ≥1.209 coercePermissionMode 认 "auto"
+ * (解释 = default 同款 fs 写 ask 门;存活 ask 由引擎侧 auto-mode 分类器先行裁决——武装 AND 门
+ * RuntimeCaps.autoMode ∧ RunnerDeps.autoMode,缺一静默回 ask,fail-closed)。壳只透传意图,分类器
+ * 规则/权益都在装配面,非 TaskSpec 字段。版本安全:老 server coerce 未知非空词 → "default"
+ * (manual ask 门)= 只紧不松。
+ */
+export type PermissionMode = 'default' | 'plan' | 'acceptEdits' | 'bypassPermissions' | 'auto';
+export interface PermissionModeField {
+    permissionMode?: PermissionMode;
+}
+/**
+ * Project the client's permission mode → the wire intent. Carries any KNOWN non-`default` mode verbatim (the
+ * service interprets); `default`/unknown/undefined ⇒ no stamp (the deployment baseline governs). No policy baked
+ * here — relevance + tighten-only governance is the service's job.
+ *
+ * `stampDefault`([830]① server 1.191 五模式解释层):server 侧 absent-mode 不挂门(存量 headless
+ * 零回归),manual(=CC default)要挂 fs 写 ask 门必须显式 stamp `permissionMode:"default"`。只有
+ * 三选卡真能弹出来的调用方(交互 REPL,leader ToolUseConfirm 队列已注册)才传 true —— print/headless
+ * 不 stamp;老 server 对 "default" 走 basePolicy(与 absent 等价),version-safe。
+ */
+export declare function permissionModeField(mode: string | undefined, opts?: {
+    stampDefault?: boolean;
+}): PermissionModeField;

package/dist/permissionWireCaps.js

@@ -0,0 +1,46 @@
+/**
+ * ⇄ B2 批搬迁(2026-07-27,多端改造设计稿 §3 B2):cli src/sema/permissionWireCaps.ts 逐字搬入(零依赖)。
+ */
+/**
+ * src/sema/permissionWireCaps.ts — PURE CC permission-mode INTENT projection (R4, revised per the two-axis
+ * seamless principle). seamQuery imports it.
+ *
+ * 🔴 Design (memory seamless-two-axis-wire-principle): the frontend carries the RAW permission-mode INTENT; the
+ * SERVICE interprets it (axis-aware, tighten-only). We do NOT pre-interpret `plan → enablePlanMode+handsReadOnly`
+ * on the client — that bakes policy into one frontend and would drift between the TUI shell and the web portal.
+ * Instead we stamp `permissionMode` and let the service own the interpretation (plan ⇒ present_plan + read-only;
+ * acceptEdits/bypassPermissions ⇒ loosening, coerced to default engine-side, enforced client-side). This keeps the
+ * shell a thin per-turn intent projector that's identical across TOC-local / TOB-cloud / centralized-session axes.
+ *
+ * `auto`(分类器批3,黑板 [907] server 五模式表):server ≥1.209 coercePermissionMode 认 "auto"
+ * (解释 = default 同款 fs 写 ask 门;存活 ask 由引擎侧 auto-mode 分类器先行裁决——武装 AND 门
+ * RuntimeCaps.autoMode ∧ RunnerDeps.autoMode,缺一静默回 ask,fail-closed)。壳只透传意图,分类器
+ * 规则/权益都在装配面,非 TaskSpec 字段。版本安全:老 server coerce 未知非空词 → "default"
+ * (manual ask 门)= 只紧不松。
+ */
+const KNOWN = new Set([
+    'default',
+    'plan',
+    'acceptEdits',
+    'bypassPermissions',
+    'auto',
+]);
+/**
+ * Project the client's permission mode → the wire intent. Carries any KNOWN non-`default` mode verbatim (the
+ * service interprets); `default`/unknown/undefined ⇒ no stamp (the deployment baseline governs). No policy baked
+ * here — relevance + tighten-only governance is the service's job.
+ *
+ * `stampDefault`([830]① server 1.191 五模式解释层):server 侧 absent-mode 不挂门(存量 headless
+ * 零回归),manual(=CC default)要挂 fs 写 ask 门必须显式 stamp `permissionMode:"default"`。只有
+ * 三选卡真能弹出来的调用方(交互 REPL,leader ToolUseConfirm 队列已注册)才传 true —— print/headless
+ * 不 stamp;老 server 对 "default" 走 basePolicy(与 absent 等价),version-safe。
+ */
+export function permissionModeField(mode, opts) {
+    if (typeof mode === 'string' && mode !== 'default' && KNOWN.has(mode)) {
+        return { permissionMode: mode };
+    }
+    if (opts?.stampDefault === true && (mode === undefined || mode === 'default')) {
+        return { permissionMode: 'default' };
+    }
+    return {};
+}

package/dist/promptProfileWireCaps.d.ts

@@ -0,0 +1,17 @@
+/**
+ * ⇄ B2 批搬迁(2026-07-27,多端改造设计稿 §3 B2):cli src/sema/promptProfileWireCaps.ts 逐字搬入(零依赖)。
+ */
+/**
+ * src/sema/promptProfileWireCaps.ts — PURE projection: the shell's prompt-profile pick → the
+ * `TaskRequest.promptProfile` axis (core 1.328 [1144]: CC LT(model_id)-同构的呈现轴,
+ * "simple"=CC 对 BYOM id 发的短形面(引擎缺省)/"classic"=长形面,按任务/模型可切)。
+ *
+ * Config source: env `SEMA_PROMPT_PROFILE`(A/B 与手选口;center 下发面走引擎侧 TaskSpec 直通,
+ * 不经此位)。STRICT allowlist:仅 "simple"/"classic"(大小写不敏感,trim)stamp;其它/缺省 ⇒
+ * `undefined`(不 stamp=引擎缺省 simple,请求形状不变——additive 纪律与 retainBackgroundWireCaps
+ * 同款)。CALLER 前置 live 门(mock 形不变)。
+ */
+import { type EnvLike } from './hostEnv.js';
+export declare const PROMPT_PROFILE_ENV: "SEMA_PROMPT_PROFILE";
+export type PromptProfile = 'simple' | 'classic';
+export declare function promptProfileFromEnv(env?: EnvLike): PromptProfile | undefined;

package/dist/promptProfileWireCaps.js

@@ -0,0 +1,20 @@
+/**
+ * ⇄ B2 批搬迁(2026-07-27,多端改造设计稿 §3 B2):cli src/sema/promptProfileWireCaps.ts 逐字搬入(零依赖)。
+ */
+/**
+ * src/sema/promptProfileWireCaps.ts — PURE projection: the shell's prompt-profile pick → the
+ * `TaskRequest.promptProfile` axis (core 1.328 [1144]: CC LT(model_id)-同构的呈现轴,
+ * "simple"=CC 对 BYOM id 发的短形面(引擎缺省)/"classic"=长形面,按任务/模型可切)。
+ *
+ * Config source: env `SEMA_PROMPT_PROFILE`(A/B 与手选口;center 下发面走引擎侧 TaskSpec 直通,
+ * 不经此位)。STRICT allowlist:仅 "simple"/"classic"(大小写不敏感,trim)stamp;其它/缺省 ⇒
+ * `undefined`(不 stamp=引擎缺省 simple,请求形状不变——additive 纪律与 retainBackgroundWireCaps
+ * 同款)。CALLER 前置 live 门(mock 形不变)。
+ */
+import { hostEnv } from './hostEnv.js';
+export const PROMPT_PROFILE_ENV = 'SEMA_PROMPT_PROFILE';
+export function promptProfileFromEnv(env = hostEnv()) {
+    const raw = env[PROMPT_PROFILE_ENV];
+    const s = typeof raw === 'string' ? raw.trim().toLowerCase() : '';
+    return s === 'simple' || s === 'classic' ? s : undefined;
+}

package/dist/retainBackgroundWireCaps.d.ts

@@ -0,0 +1,50 @@
+/**
+ * ⇄ B2 批搬迁(2026-07-27,多端改造设计稿 §3 B2):cli src/sema/retainBackgroundWireCaps.ts 逐字搬入(零依赖)。
+ */
+/**
+ * src/sema/retainBackgroundWireCaps.ts — PURE projection: the shell's "retain background processes past
+ * task teardown" opt-in → the TOP-LEVEL `TaskRequest.retainBackgroundProcesses` boolean the SERVICE consumes
+ * (spec-fields.js `retainBackgroundProcessesFromBody`: `raw !== true` ⇒ dropped;requirePrincipal 多租户形
+ * 服务端另有门)。Mirrors selfOrchestrationWireCaps(the verified top-of-body wire pattern)。
+ *
+ * 背景([1046] 核谳,TB [991]② reap 族):core 直跑腿(sema-tb)出厂显式
+ * `retainBackgroundProcesses:true`(design/128 T1-1——「交付存活服务」任务的 verifier 在进程退出后
+ * 才连接),而组合腿产品曾默认关 ⇒ 两腿在 reap 族不是同一场考试。
+ *
+ * ⚠️ 缺省已翻转为 ON(clay 亲报「后台 shell 命令跑到一半被杀」案,2026-07-26;[1046]④ 的裁量件本次
+ * 由真实场景需求兑现)。缺省不发时,引擎 turn finally 的**两道门**都关着:
+ *   ① `settleKilledForOwner({retainProcesses})` 的 retain 豁免;
+ *   ② `retainBgBySpec = spec.retainBackgroundProcesses === true && !ownedEnvDying` —— 为真才整块跳过
+ *      `bgEnv.disposeBackgroundShells(...)`(该 blanket sweep 不经 task-registry,故被它收掉的任务
+ *      `stopSource` 为空,终态归因落到 `stoppedBy = "system"` 缺省 = clay 观察到的 `stopped-by: system`)。
+ *
+ * 三问(宪法 NO-SHIP 检查):
+ *   谁需要:真人用户 —— `run_in_background` 起的构建/测试/服务在当轮结束后必须还活着,否则
+ *           BashOutput/TaskOutput 续读到的是尸体(clay 案:输出文件 0 字节 + status killed)。
+ *   谁受害:隔离执行环境(e2b/k8s/ssh 等 `isIsolated(env)`)—— 那里 `ownedEnvDying` 为真,retain 被
+ *           **无条件覆盖**(core 侧 `!opts.envDying` / `&& !ownedEnvDying`),进程随宿主一起走。这是
+ *           正确的:进程宿主没了,留 handle 无意义。故本翻转对隔离腿零语义变化。
+ *           次级受害面 = 本机资源泄漏(后台进程活过当轮)—— 但这正是 CC 的既定契约,不是回归。
+ *   补偿机制:`SEMA_RETAIN_BACKGROUND=0|false|no|off` 逃生口 ⇒ 不 stamp ⇒ 回引擎缺省 reap;
+ *           进程始终可由 KillShell/TaskStop 显式收,`/bashes` 面板可见可停;引擎 hard-wall
+ *           (defaultBgTimeoutSec 30min / maxBgTimeoutSec 2h)仍是兜底上限。
+ *
+ * CC 逐字锚(对标纲领 = 100% 达 CC 效果):CC 的 Bash `run_in_background` 契约 = 进程活过当轮,
+ * 由 BashOutput 续读、KillShell 显式收 —— **不在 turn 边界回收**。缺省 reap 是对 CC 的偏离,本次钉回。
+ *
+ * 语义:缺省 ON —— unset / 未识别值 ⇒ `true`(stamp);显式 truthy(1/true/yes/on)⇒ `true`;
+ * 只有显式 falsy(0/false/no/off)⇒ `undefined`(不 stamp ⇒ 引擎缺省 reap)。
+ * 服务端 `retainBackgroundProcessesFromBody` 是 `raw !== true ⇒ 丢弃` 的严格刻度,所以 opt-out 一律
+ * 表达为**不 stamp**,绝不发 `false`(形状诚实)。
+ * PURE — callers pass `env`;caller gates to LIVE mode(mock request shape 不变)。
+ */
+import { type EnvLike } from './hostEnv.js';
+/** The env key the shell reads(SEMA_ 命名空间,与引擎自己的 spec∨env 通道正交——这里是壳→
+ *  TaskRequest 的 per-request 意图面,非引擎部署面)。 */
+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」。
+ */
+export declare function retainBackgroundFromEnv(env?: EnvLike): true | undefined;