@sema-agent/server 7.36.0 → 7.37.0

package/dist/plugins/task-list-store-sql.js

@@ -1,8 +1,60 @@
+/**
+ * TaskListStore SQL twins(design/151 S3c server pg 半场,[1530] 提货单②)——core 团队共享任务
+ * 清单(TaskCreate/TaskUpdate/TaskList 工具族)的 TiDB/PG 双方言实现。挂载缝 = S3c 行为车定
+ * (createTaskListTools(store) 已收 store 参数);本文件先就绪 store 半场。
+ *
+ * 语义真源 = core file 实现(dist/stores/file/task-list-store.js,durable 对 durable)+ [1530] 定谳:
+ *  1. **`mutate` 必须后端事务原子**(接口 JSDoc codex S4 F2 句):read-modify-write 全序列进一个
+ *     事务;分区锁 = meta 行 `SELECT … FOR UPDATE`(天然 advisory lock,同清单 mutate 串行)。
+ *  2. **nextId 只增不回退、与分配同事务**(删最高 id 不复用):`task_list_meta` 单行携 `next_id`,
+ *     **永不从存量 MAX 派生**。
+ *  3. metadata = JSON 列(`assertJsonMetadata` 在 set 面拦,file/memory 同形);id 任意 string
+ *     (工具层走 allocateId 产数字串,接口不排除外部 id)。
+ *
+ * `list` 序:两个 core 参照本就不同(memory=Map 纯插入序;file=JS 对象序 = integer-like 键数字
+ * 升序、其余按插入序殿后)——SQL twin 对齐 **file 形**(durable 参照):`id_num` 物化列(canonical
+ * array-index 形才非 NULL)数字升序,非数字 id 按 `sort_seq`(插入序)殿后。set 覆盖已有 id 保位
+ * (sort_seq 不变)= 两参照一致的保位语义。`sort_seq` 从 **meta 行计数器同事务分配**(复审 F6:
+ * TiDB AUTO_INCREMENT 按 tidb-server 分段缓存,跨节点不单调——「插入序」在多网关部署下会倒序;
+ * meta 计数器 = allocateId 同姿势,真单调;覆盖写浪费一个号,单调性无损)。
+ *
+ * 分区键 `listKey` = 构造参数(file 形的 root 目录对位):谁的清单由挂载点决定(per-team 组装,
+ * S3c 行为车),store 层只管字节隔离(VARBINARY / COLLATE "C",roster F2 案)。PG unstorable
+ * bytes([1439]):item 正文(subject/description/metadata)= 内容面 lossy(pgSafeJsonStringify,
+ * U+FFFD);**身份键 listKey/id 拒绝式**(清洗形变 = 行与查询键错位)。TiDB verbatim。
+ */
+import { createHash } from "node:crypto";
 // assertJsonMetadata:core 1.374 起包根导出([1531]§一3——私拷镜像即换,DURABLE_AGENT_HANDLE_RE 同姿势)。
 import { assertJsonMetadata } from "@sema-agent/core";
 import { pgHasUnstorable, pgSafeJsonStringify, PgUnstorableError } from "./pg-safe-json.js";
 export const TASK_LIST_META_TABLE = "task_list_meta";
 export const TASK_LIST_ITEM_TABLE = "task_list_item";
+/**
+ * #318 `sessionId ↦ 本表的身份键`:`session:<可读前缀>-<sha256(sessionId) 前 16 位>`。
+ *
+ * 🔴 为什么不直接把 sessionId 当 listKey:sessionId 是**调用方可自报**的不透明串(提交门
+ * `http/server.ts` 只卡 ≤64 **字符** —— [#15] 刻意的宽松提交契约,不卡字节数也不卡字符集)。
+ * 而本文件的身份键是字节面严格的:{@link assertListKeyBytes} 对 >190 字节当场拒(TiDB
+ * `INSERT IGNORE` 静默截断案),PG twin 对孤代理/NUL 走 {@link PgUnstorableError} 拒。直接透传
+ * 的话,一个 64 字符全四字节 emoji 的会话(256 字节)会让**整条请求**在场景装配处 500 —— 而那条腿
+ * 只是待办清单。派生一个恒可存的键把这一整类失败模式消掉(既不是 fail-open 也不是 fail-loud,是让
+ * 那条臂不存在)。
+ *
+ * 判据:确定性(同 sessionId 跨副本/跨重启恒同键)、字节安全(纯 ASCII,≤ 8+24+1+16 = 49 字节)、
+ * 抗碰撞(摘要取**全串**,可读前缀只为运维肉眼对账)。
+ *
+ * `session:` 是**命名空间**位:design/147 §6 D2 的团队共享清单将来若按 team 分区,两族键同表不撞。
+ * 同族先例 = `env-facts.ts` 的 `scratchpadSessionSegment`(文件名面)——刻意**不**复用彼此的实现:
+ * 一个键空间改了算法不该把另一个键空间的存量行全孤儿化。
+ *
+ * 🔴 属主在**本文件**(而不是消费它的 boot 车道):留存腿(`retention-store-sql.ts`)按同一派生式
+ * 批量删本表的行,两个消费点必须读同一个函数 —— 键派生有两份就是「在线删除删得掉、留存腿删不掉」。
+ */
+export function taskListKeyFor(sessionId) {
+    const readable = sessionId.replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 24);
+    const digest = createHash("sha256").update(sessionId).digest("hex").slice(0, 16);
+    return `session:${readable.length > 0 ? readable : "_"}-${digest}`;
+}
 /** JS 对象 integer-like(array-index)键判別——file 参照的遍历序里数字升序的那一族:canonical
  *  十进制、0 ≤ n < 2^32-1。"01"/"1e3"/负数/超界 = 普通串键(插入序殿后)。 */
 function arrayIndexOf(id) {
@@ -91,6 +143,56 @@ async function setOn(exec, dialect, listKey, id, itemJson) {
         ? `UPDATE ${TASK_LIST_META_TABLE} SET next_sort = ? WHERE list_key = ?`
         : `UPDATE ${TASK_LIST_META_TABLE} SET next_sort = $1 WHERE list_key = $2`, [sort + 1, listKey]);
 }
+/**
+ * 整份清单删除(#318 / E21 会话删除级联;codex R1-[high] 验真后加)。
+ *
+ * 语义 = 「这个 listKey 的清单**不存在过**」:item 行 + meta 行(高水位 `next_id` / 插入序
+ * `next_sort`)一并抹掉。⚠️ **meta 行必须一起删**:留着它,同一个 listKey 被重新登记后
+ * (会话 id 由调用方自选、删除后可被别人 `register`)新主的第一条任务会从旧主的高水位续号 ——
+ * 那是一条跨化身的信息泄漏(「上一位在这里建过 47 条」)。
+ *
+ * 事务内先对 meta 行 `FOR UPDATE`(与 `mutate` 同一把分区锁)⇒ 与并发的清单写串行,不会删到
+ * 一半被插回新行。meta 行不在(从未写过任何任务)= 无锁可拿,DELETE 命中 0 行,幂等。
+ */
+export async function deleteTiDBTaskList(pool, listKey) {
+    assertListKeyBytes(listKey);
+    const c = await pool.getConnection();
+    try {
+        await c.beginTransaction();
+        await c.query(`SELECT next_id FROM ${TASK_LIST_META_TABLE} WHERE list_key = ? FOR UPDATE`, [listKey]);
+        await c.query(`DELETE FROM ${TASK_LIST_ITEM_TABLE} WHERE list_key = ?`, [listKey]);
+        await c.query(`DELETE FROM ${TASK_LIST_META_TABLE} WHERE list_key = ?`, [listKey]);
+        await c.commit();
+    }
+    catch (e) {
+        await c.rollback().catch(() => { });
+        throw e;
+    }
+    finally {
+        c.release();
+    }
+}
+/** {@link deleteTiDBTaskList} 的 PG 孪生(同语义、同事务姿势)。 */
+export async function deletePgTaskList(pool, listKey) {
+    if (pgHasUnstorable(listKey))
+        throw new PgUnstorableError("task-list listKey");
+    assertListKeyBytes(listKey);
+    const c = await pool.connect();
+    try {
+        await c.query("BEGIN");
+        await c.query(`SELECT next_id FROM ${TASK_LIST_META_TABLE} WHERE list_key = $1 FOR UPDATE`, [listKey]);
+        await c.query(`DELETE FROM ${TASK_LIST_ITEM_TABLE} WHERE list_key = $1`, [listKey]);
+        await c.query(`DELETE FROM ${TASK_LIST_META_TABLE} WHERE list_key = $1`, [listKey]);
+        await c.query("COMMIT");
+    }
+    catch (e) {
+        await c.query("ROLLBACK").catch(() => { });
+        throw e;
+    }
+    finally {
+        c.release();
+    }
+}
 export function createTiDBTaskListStore(pool, listKey) {
     assertListKeyBytes(listKey);
     const tx = async (fn) => {

package/dist/run-local.js

@@ -66,6 +66,7 @@ import { loadSkills } from "./capabilities/skills.js";
 import { createRepoClient } from "./capabilities/repo-tools.js";
 import { webSearchConfigFromEnv, createWebSearchBackend } from "./plugins/web-search.js";
 import { buildScenarios, selectScenario, centerScenarios, canonicalScenarioName } from "./capabilities/scenarios.js";
+import { createTaskListLane } from "./boot/task-list-lane.js";
 import { pickHandsRunner, withoutExecutionEnv } from "./capabilities/hands-lane.js";
 import { HttpError } from "./security.js";
 import { memoryEngineBackendFor, memorySpecForRequest } from "./memory-scope.js";
@@ -701,9 +702,15 @@ export async function runLocal(argv, deps = {}) {
     // default scenario's WebSearch tool is assembled on the CLI path too (it was silently never built before).
     const webSearchCfg = webSearchConfigFromEnv();
     const webSearch = webSearchCfg ? createWebSearchBackend(webSearchCfg) : undefined;
+    // #318:会话级任务清单车道。run-local 无 SQL 后端 ⇒ 内存臂(进程内 per-session)。一次性 CLI 的
+    // 单进程内本来就只解析一次场景,接它的意义在于**装配面同源**:server 与 run-local 走同一条
+    // `ScenarioDeps.taskListStoreFor` 契约,不让 CLI 腿静默留在「per-call 私店」的修前形上。
+    // `--session` 跨调用续聊的待办清单不跨进程存活(local 形的诚实边界,USAGE 已登记)。
+    const taskListLane = createTaskListLane({ logger });
     const scenarioDeps = {
         runner, subRunner, handslessSubRunner, model: "default", skills, repoClient, metrics, logger,
         ...(webSearch ? { webSearch } : {}),
+        taskListStoreFor: taskListLane.storeFor,
         brandIdentity: true, // run-local is always a local/TOC deployment → brand the default scenario as Sema.
     };
     const scenarios = buildScenarios(scenarioDeps);
@@ -724,9 +731,15 @@ export async function runLocal(argv, deps = {}) {
     // GIT_API_BASEURL + a repo — which a one-shot CLI may not
     // supplies). The server catches this in resolveSpec/prepareSpec and returns a clean 4xx; here we mirror that
     // with the doctor-style UX (message to stderr + exit 2) instead of letting it bubble to the fatal exit-1 path.
+    // --session REUSES a session (durable multi-turn across invocations, via the file session store); absent →
+    // a fresh uuidv7 (still persisted). --user is the stable memory/identity scope so long-term memory
+    // accumulates per user (default "local" = the single TOC user). The file stores acquire/append lazily.
+    // #318:解析点上提到场景装配**之前** —— 场景工厂现在要 `ScenarioContext.sessionId`(会话级任务
+    // 清单的分区键)。纯移动,取值逐字不变(uuidv7() 无前置依赖)。
+    const sessionId = args.session ?? uuidv7();
     let cap;
     try {
-        cap = selectScenario(scenarios, scenarioName)({ scenario: scenarioName, objective: args.objective });
+        cap = selectScenario(scenarios, scenarioName)({ scenario: scenarioName, objective: args.objective }, undefined, { sessionId });
     }
     catch (err) {
         if (err instanceof HttpError) {
@@ -740,10 +753,6 @@ export async function runLocal(argv, deps = {}) {
         throw err;
     }
     const mention = parseModelMention(args.objective, Object.keys(config.models));
-    // --session REUSES a session (durable multi-turn across invocations, via the file session store); absent →
-    // a fresh uuidv7 (still persisted). --user is the stable memory/identity scope so long-term memory
-    // accumulates per user (default "local" = the single TOC user). The file stores acquire/append lazily.
-    const sessionId = args.session ?? uuidv7();
     const scope = args.user ?? "local";
     // Timeout policy mirrors the server (taskWallClockSec): run-local IS the pure single-user
     // TOC lane → NO wall clock by default (core's wedge safety-net still applies); explicit TASK_TIMEOUT_SEC

package/dist/runs.js

@@ -3,11 +3,13 @@ import { withPrincipal } from "./observability/principal-context.js";
 import { redactSecrets } from "./trace/redact.js";
 import { taskNotificationEventData, appendModelUsageDelta, appendPromptManifest, attachModelUsage } from "./trace/project.js";
 import { createLedgerSink } from "./trace/ledger-sink.js";
+import { registerEngineNoticeLeg } from "./trace/engine-notice-wire.js"; // #310:通告 wire 腿(bg 半场)
 import { recordTurnActivity } from "./turn-activity.js";
 import { createApprovalCardEmitter, resolveApprovalLeg } from "./tool-approval.js";
 import { fleetRunResiduals, isFleetAgentTerminalNotification } from "./fleet/fleet-bus.js";
 import { defaultSubagentTailBus, projectTailFrame } from "./fleet/subagent-tail-bus.js";
 import { emitPendingWorkflowCompletions, taskNotificationInboxEntry, taskNotificationStreamKey, NotifiedKeys } from "./orchestration/workflow-completion-inbox.js";
+import { recordFailOpen } from "./observability/fail-open.js"; // #310:通告 durable 写失败的留痕口
 /**
  * stoppedBy (core 1.252): a service cancel is a USER stop — mark the run's still-running background
  * children BEFORE core's teardown reaps them (bare abort = attribution falls back to "system"; core's own
@@ -526,6 +528,20 @@ approval) {
         const { type, ...rest } = frame;
         return append(type, rest);
     };
+    // #310 `engine_notice` wire 腿(设计稿 = 黑板 [4630],三腿之一:**bg**)。本腿**没有 live SSE**
+    // (消费方走 `GET /v1/runs/:id/events` 的 durable tail),所以只挂 durable 口 —— 这与本腿的 HITL 帧
+    // (elicit/question/approval 三族)姿态逐字相同:唯一投递面就是账本,tail 负责送到人眼前。
+    // fire-and-forget:`onNotice` 是 core 的同步回调,不能拿一次账本写去阻塞引擎;seq 在 `append` 的链步内
+    // 同步分配 ⇒ 与主循环的 await 写不会乱序(`onForwardEvent` 同款契约)。
+    // 🔴 写失败**留痕不裸吞**(codex 对抗复审 R1-[medium],验真后修):本腿账本是通告的**唯一**用户可见
+    // 终点,一次 store 抖动就让它对用户永久消失;`route` 的同步 try 观察不到异步 reject。同文件 resume 腿
+    // 的 `warnAppend` 是同一条纪律的先例(C2/C5 批2)。
+    const unregisterEngineNotice = registerEngineNoticeLeg({
+        sessionId: spec.sessionId,
+        // (本函数没有 logger 席 —— 留痕走 `recordFailOpen` 的三件套:逐次计数 + 逐次探针行[带 detail] +
+        //  一次性 warn。这正是 #157 为「结构上拿不到 logger 的兜底臂」准备的口,不为它加一个参数。)
+        durable: (row) => void append("engine_notice", row).catch(() => recordFailOpen("server.engine-notice.durable-append-failed", `leg=bg code=${row.code} task=${taskId}`)),
+    });
     try {
         // P1 ①② follow-on (core): drain this session's async-workflow completion inbox at the START of the
         // background leg (before ANY branch — verify/cascade/plain-stream all get it; parity with the sync leg's
@@ -953,6 +969,7 @@ approval) {
     }
     finally {
         legLive = false; // notifications from here on take the durable-inbox path
+        unregisterEngineNotice(); // #310:腿结束即注销 wire 口(下一条同会话腿自带自己的口)
         // MF-Fleet: flip/remove the fleet row at the SINGLE finalization point — runs once for EVERY exit path
         // (success / cancel / error / suspend / needs_review). A truly-terminal status leaves the fleet; a PARKED
         // status (suspended→waiting / needs_review→awaiting approval) STAYS (the run is still active). A cancelled

package/dist/trace/engine-notice-wire.d.ts

@@ -0,0 +1,128 @@
+/**
+ * 上 wire 的通告码 —— **显式闭集常量表**(设计稿 ①,起步三码)。
+ *
+ * 三码同族:都是「这条 session 的记忆姿态」的披露,resume 之后仍然相关 ⇒ 也进 durable 账本
+ * (cli 断连补看走既有 events 重放腿,[4634](ii))。
+ */
+export declare const ENGINE_NOTICE_WIRE_CODES: readonly ["memory.session_polluted", "memory.harvest_quarantined", "memory.delegation_static_mark_waived"];
+export type EngineNoticeWireCode = (typeof ENGINE_NOTICE_WIRE_CODES)[number];
+/** 白名单谓词(单点):路由与门都读这一个,不许第二处手抄码串。 */
+export declare function isEngineNoticeWireCode(code: string): code is EngineNoticeWireCode;
+/**
+ * 归属键抽取 —— `detail.sessionId` 提升为顶层(设计稿 ②:归属键一等化)。
+ *
+ * 非串 / 空串一律按**缺席**处理(不铸 `"undefined"` 这种看起来合法的假值——`compactionOutcomeEventData`
+ * 的同款缺键守卫纪律)。core [4631] 的顶层 `EngineNotice.sessionId` 到货后,这里先读顶层再回落 detail
+ * (两处同值,additive 零 BREAKING),届时本函数是唯一改动点。
+ */
+export declare function engineNoticeSessionId(notice: {
+    sessionId?: unknown;
+    detail?: Record<string, unknown>;
+}): string | undefined;
+/** wire 上的 `engine_notice` 载荷(**五键固定**,设计稿 ②)。`type` 由发帧处补(SSE)/ 由账本行的 type 列承载。 */
+export interface EngineNoticeWireRow {
+    /** 稳定机器码 —— 消费契约:cli 按 `code`+`detail` 渲染(见 {@link ENGINE_NOTICE_WIRE_CODES} 各码的 detail 形)。 */
+    code: string;
+    /**
+     * core 铸的人话行。🔴 **仅 fallback 展示,不是匹配键**:core 明写 `memory.session_polluted` 的 message
+     * 随 `memoryProvenance` 模式变文(design/336 mode-aware),按 message 匹配必碎(5.41 合流码形退役同教训)。
+     */
+    message: string;
+    /** 机器可读事实,逐键消毒后直透(见 {@link sanitizeNoticeDetail} 的消毒/尺寸契约)。 */
+    detail: Record<string, unknown>;
+    /** 归属键(从 detail 提升)。本行只会出现在**这一条** session 的流上。 */
+    sessionId: string;
+    /** **服务端观察时刻**(ms epoch)——`EngineNotice` 自身不带时间戳,这是本仓收到它的那一拍,不是 core 铸它的那一拍。 */
+    ts: number;
+}
+/**
+ * `detail` 消毒(设计稿 ②:`redactSecrets` + 尺寸 bound;`workspaceChangedEventData` 先例)。
+ *
+ * core 已 neutralize 三码的 `reason`(工具名/子代类型是 host/模型可控输入),**server 按纪律再过一遍**
+ * ——§E1 的既有姿态:上 wire 的自由文本一律经本仓的脱敏器,不因为上游说过一次就免检。
+ *
+ * 契约(逐条,门在 `test/engine-notice-wire.test.ts`):
+ *  · 串 ⇒ `redactSecrets` + 截到 {@link NOTICE_TEXT_MAX};
+ *  · 有限 number / boolean / null ⇒ 逐字(harvest 的 count/moved/escalated 是判据数字,不许变形);
+ *  · 非有限 number(NaN/Infinity)⇒ **丢键**(JSON 里它们会变成 `null`,一个看起来合法的假读数);
+ *  · 数组 ⇒ 逐项消毒,超 {@link DETAIL_MAX_ITEMS} 截断;对象 ⇒ 逐键消毒,超 {@link DETAIL_MAX_KEYS} 丢尾键;
+ *  · 深度超 {@link DETAIL_MAX_DEPTH} ⇒ 该子树丢弃;
+ *  · 其余(function / symbol / bigint / undefined)⇒ 丢键(JSON 不可承载或语义不明)。
+ */
+export declare function sanitizeNoticeDetail(detail: Record<string, unknown> | undefined): Record<string, unknown>;
+/**
+ * `engine_notice` 载荷构造器(三条终点腿同源:live SSE / durable 账本 / 未来的任何第四条腿)。
+ *
+ * 与 `trace/project.ts` 的 `*EventData` 族同纪律(白名单挑键、禁 `{...notice}`),但**不住在那个文件里**:
+ * 那一族的入参全是 core `TaskEvent` 的臂(有 `wire-whitelist-exhaustiveness` 的臂集编译门看着),
+ * 而 `EngineNotice` 不是 `TaskEvent` —— 混进去会让那道门的语义变成"两个不同来源的联合",判别力反而降。
+ */
+export declare function engineNoticeEventData(notice: {
+    code: string;
+    message: string;
+    detail?: Record<string, unknown>;
+}, sessionId: string, nowMs: number): EngineNoticeWireRow;
+/** 一条 run 腿注册进来的投递口。抛错由 {@link EngineNoticeRouter.route} 隔离(见那里的 fail-open 登记)。 */
+export type EngineNoticeWireSink = (row: EngineNoticeWireRow) => void;
+/**
+ * sessionId → 该会话活跃 run 腿的投递口。**进程内**(`defaultSubagentTailBus` 同款姿势):
+ * `onNotice` 是同进程的同步回调,通告与它要投的那条腿必然同副本,跨副本路由这件事结构上不存在。
+ *
+ * 🔴 跨 session 隔离靠的是 **Map 键的精确串相等**,不是任何「最近活跃」回落 —— 缺席就是缺席(G5)。
+ *
+ * 🔴 **同 session 的跨代隔离靠 legId「最新代独占」**(#310 codex 对抗复审 R1-[high],验真后修)。
+ * 病(真窗,本仓每一处 in-flight 登记都为它写过 identity-guard):run 行在**流体内**就已 setTerminal /
+ * setSuspended,而本腿的注销在 `finally` —— 中间那一窗里,同一条 session 上的**下一条腿**(快速续跑 /
+ * 紧接着的新提交)已经注册好了自己的口。若按「会话内全量扇出」投,新腿的一条通告会**同时**落进:
+ *  · 旧腿那条已 end 的 SSE(顶多记一次 fail-open,无害),以及
+ *  · **旧 taskId 的账本** —— 一条不属于那条 run 的、终态之后的行;resume 复用同 taskId 时还会与新腿
+ *    抢同一个 `(task_id, seq)` 域。这不是跨租户泄露,是**同租户跨 run 的账本污染**,同样必须关死。
+ * 药:每次 `registerLeg` 铸一个单调 legId,`route` **只投最新代**;旧代的口留在表里(它自己的注销仍
+ * 按身份精确删,不会误删新代),但一帧都收不到。方向 = fail-closed(宁可旧腿少一帧,不可新腿的事实
+ * 写进旧腿的账)。
+ */
+export declare class EngineNoticeRouter {
+    private readonly legs;
+    /**
+     * 登记**一条腿**的全部口(live / durable 作为**一代**同进同出)。返回注销函数(幂等,身份精确删)。
+     *
+     * 每只口各自 try 隔离在 {@link route} 里,单口抛不牵连同腿另一口。
+     */
+    registerLeg(sessionId: string, sinks: readonly EngineNoticeWireSink[]): () => void;
+    /** 单口腿的便捷形(测试与单终点腿用)。 */
+    register(sessionId: string, sink: EngineNoticeWireSink): () => void;
+    /** 诊断/门用:某会话此刻**最新代**有几只口在听(旧代不计——它们收不到帧)。 */
+    sinkCount(sessionId: string): number;
+    /** 诊断/门用:某会话此刻有几代腿在表里(>1 = 正处在换代窗内)。 */
+    legCount(sessionId: string): number;
+    /**
+     * 分流器的 wire 半场。返回**真投出去的口数**(0 = 没投:非白名单码 / 缺 sessionId / 该会话无活跃腿)。
+     *
+     * 单只口抛错**不吃掉同腿的其它口**(fleet bus 订阅者隔离同理由),并按 F 类登记留痕。
+     */
+    route(notice: {
+        code: string;
+        message: string;
+        detail?: Record<string, unknown>;
+        sessionId?: unknown;
+    }, nowMs?: number): number;
+}
+/** 进程单例(`defaultSubagentTailBus` 同款):分流器与 run 腿直接 import,不穿长参数列表;测试自 new 独立实例。 */
+export declare const defaultEngineNoticeRouter: EngineNoticeRouter;
+/**
+ * run 腿的注册助手 —— 三条腿(sync stream / bg / resume-verify)用**同一个**形,免得各写一份漂。
+ *
+ * `sessionId` 缺席(adhoc 无会话腿)⇒ 返回 no-op 注销函数,一个字节不注册(顶注的 fail-closed 方向)。
+ * `live` / `durable` 各自可缺席:bg 腿没有 live SSE(消费方走 events tail),ephemeral sync 腿没有账本。
+ *
+ * 🔴 两口注册成**两只独立 sink**(不是一只闭包里顺序调两次):route 的隔离粒度是 sink,合成一只会让
+ * live 写(断连的 socket、JSON.stringify 抛)吃掉同一拍的 durable 落账 —— 而 durable 那半正是断连之后
+ * 唯一还看得见这条通告的地方(G3),两者的失败必须互不牵连。
+ */
+export declare function registerEngineNoticeLeg(opts: {
+    sessionId: string | undefined;
+    live?: EngineNoticeWireSink;
+    durable?: EngineNoticeWireSink;
+    router?: EngineNoticeRouter;
+}): () => void;
+//# sourceMappingURL=engine-notice-wire.d.ts.map

package/dist/trace/engine-notice-wire.js

@@ -0,0 +1,256 @@
+/**
+ * `engine_notice` wire 腿(#310,设计稿 = 黑板 [4630],core 表态 [4631] / cli 表态 [4634])——
+ * core `EngineNotice` 的**第二终点**:按 sessionId 路由到那条会话的事件投影(SSE + durable 账本)。
+ *
+ * ## 为什么是白名单而不是全族上 wire
+ * `RunnerDeps.onNotice` 是 **deps 级单 sink**(一部署一只),`EngineNotice` 上**没有 runId**——
+ * 归属只能靠 `detail.sessionId`。于是:
+ *  · `config.*` 族一个都不带 sessionId ⇒ 结构性无处投(投给谁都是猜);
+ *  · core 侧**按 sink 去重**的码(`config.read_face_deployment_clamped` / `config.tool_model_gate_*`)
+ *    一旦上 per-session 流,语义当场翻面:共享 sink 意味着整进程只发一次,第二条会话的用户看到的是
+ *    「随机缺席」而不是「没发生」;
+ *  · 运维码(`config.env_timeout_discarded` 一族)推给终端用户 = 跨租户串台面。
+ * 白名单里的三码,core 侧的去重单位分别是 **session / harvest / prepared-leg**(不是 sink),所以它们
+ * 上 per-session 流不产生上面第二条的翻面——这正是白名单避开去重陷阱的判据,不是随手挑的三个码。
+ *
+ * ## 缺 sessionId 的白名单码:如实不投
+ * 三码的 `detail.sessionId` 在 core 类型上是**可选**的(部分铸点确无 session 语境)。缺席时本腿
+ * **不投**(fail-closed 方向 = 宁缺席不串台;猜一个"当前活跃会话"就是串台的定义)。日志终点仍逐字
+ * 保留 ⇒ 运维观察面零回退,事实一条不丢。
+ *
+ * ## 白名单的演化机制(设计稿 ④)
+ * 本表是**过渡形**。core [4631] 已认领 `NOTICE_AUDIENCE` **码级注册表**(code → "user"|"operator",
+ * 闭集映射,随 5.46 / 最迟 5.47)+ `EngineNotice.sessionId` 顶层可选。到货后本表**退役为消费该表**,
+ * 不在本仓自造第二份「哪类码该上 wire」的判定语义。
+ * 🔴 在此之前的固定动作:**每一次 core 提货批**,LEDGER 对表 core `EngineNotice` 码册的新增码,
+ * 三选一登记(入册 / 明拒 + 理由 / 申裁),登记在 `docs/CORE-CONSUMPTION-LEDGER.md` 的该批行里。
+ * 漏对表的后果不是报错而是**静默缺席**:新码永远不上 wire,消费端(cli)无从知道该码存在。
+ */
+import { redactSecrets } from "./redact.js";
+import { recordFailOpen } from "../observability/fail-open.js";
+/**
+ * 上 wire 的通告码 —— **显式闭集常量表**(设计稿 ①,起步三码)。
+ *
+ * 三码同族:都是「这条 session 的记忆姿态」的披露,resume 之后仍然相关 ⇒ 也进 durable 账本
+ * (cli 断连补看走既有 events 重放腿,[4634](ii))。
+ */
+export const ENGINE_NOTICE_WIRE_CODES = [
+    /** design/178 §3:本会话记忆越过一次性 POLLUTED 态。core 去重单位 = **session**。`detail: { reason, sessionId? }` */
+    "memory.session_polluted",
+    /** design/178 §3:被污染会话的 harvest 执行了容纳。core 去重单位 = **harvest**(检查点收与终局收是两件事)。
+     *  `detail: { count, moved, escalated, reason?, sessionId? }` —— 🔴 `moved` 与 `escalated` **不可相减**
+     *  (就地墓碑同时计入两者,core 顶注);消费端并列呈现,不做算术。 */
+    "memory.harvest_quarantined",
+    /** design/324 #324①:`memoryDelegationEvidence:"attested-only"` 下,一次静态面本会打的污染标记被豁免。
+     *  core 去重单位 = **prepared leg**。`detail: { reason, subagentType?, sessionId? }` */
+    "memory.delegation_static_mark_waived",
+];
+const WIRE_CODES = new Set(ENGINE_NOTICE_WIRE_CODES);
+/** 白名单谓词(单点):路由与门都读这一个,不许第二处手抄码串。 */
+export function isEngineNoticeWireCode(code) {
+    return WIRE_CODES.has(code);
+}
+/**
+ * 归属键抽取 —— `detail.sessionId` 提升为顶层(设计稿 ②:归属键一等化)。
+ *
+ * 非串 / 空串一律按**缺席**处理(不铸 `"undefined"` 这种看起来合法的假值——`compactionOutcomeEventData`
+ * 的同款缺键守卫纪律)。core [4631] 的顶层 `EngineNotice.sessionId` 到货后,这里先读顶层再回落 detail
+ * (两处同值,additive 零 BREAKING),届时本函数是唯一改动点。
+ */
+export function engineNoticeSessionId(notice) {
+    const top = notice.sessionId; // core 5.46+ 顶层键(到货前恒 undefined,读它零代价)
+    if (typeof top === "string" && top.length > 0)
+        return top;
+    const fromDetail = notice.detail?.sessionId;
+    return typeof fromDetail === "string" && fromDetail.length > 0 ? fromDetail : undefined;
+}
+/** 自由文本(message / detail 里的串)的长度上限。`workspaceChangedEventData` 的 300 是**路径**级 bound;
+ *  通告的 `reason` 是一整句话(core 侧已 neutralize + bound),这里给它一个不腰斩正常句子的上限。 */
+const NOTICE_TEXT_MAX = 1000;
+/** detail 递归消毒的结构上限。三码的真 detail 都是 ≤5 键的扁平对象 ⇒ 生产上永不触顶;
+ *  上限存在的理由是**未来码**(以及被污染输入)不得把任意大小的对象推上 wire。 */
+const DETAIL_MAX_DEPTH = 4;
+const DETAIL_MAX_KEYS = 32;
+const DETAIL_MAX_ITEMS = 32;
+/**
+ * `detail` 消毒(设计稿 ②:`redactSecrets` + 尺寸 bound;`workspaceChangedEventData` 先例)。
+ *
+ * core 已 neutralize 三码的 `reason`(工具名/子代类型是 host/模型可控输入),**server 按纪律再过一遍**
+ * ——§E1 的既有姿态:上 wire 的自由文本一律经本仓的脱敏器,不因为上游说过一次就免检。
+ *
+ * 契约(逐条,门在 `test/engine-notice-wire.test.ts`):
+ *  · 串 ⇒ `redactSecrets` + 截到 {@link NOTICE_TEXT_MAX};
+ *  · 有限 number / boolean / null ⇒ 逐字(harvest 的 count/moved/escalated 是判据数字,不许变形);
+ *  · 非有限 number(NaN/Infinity)⇒ **丢键**(JSON 里它们会变成 `null`,一个看起来合法的假读数);
+ *  · 数组 ⇒ 逐项消毒,超 {@link DETAIL_MAX_ITEMS} 截断;对象 ⇒ 逐键消毒,超 {@link DETAIL_MAX_KEYS} 丢尾键;
+ *  · 深度超 {@link DETAIL_MAX_DEPTH} ⇒ 该子树丢弃;
+ *  · 其余(function / symbol / bigint / undefined)⇒ 丢键(JSON 不可承载或语义不明)。
+ */
+export function sanitizeNoticeDetail(detail) {
+    const out = sanitizeValue(detail ?? {}, 0);
+    return (out ?? {});
+}
+function sanitizeValue(v, depth) {
+    if (v === null)
+        return null;
+    if (typeof v === "string")
+        return redactSecrets(v).slice(0, NOTICE_TEXT_MAX);
+    if (typeof v === "number")
+        return Number.isFinite(v) ? v : undefined;
+    if (typeof v === "boolean")
+        return v;
+    if (depth >= DETAIL_MAX_DEPTH)
+        return undefined;
+    if (Array.isArray(v)) {
+        const items = [];
+        for (const item of v.slice(0, DETAIL_MAX_ITEMS)) {
+            const s = sanitizeValue(item, depth + 1);
+            if (s !== undefined)
+                items.push(s);
+        }
+        return items;
+    }
+    if (typeof v === "object") {
+        const rec = {};
+        let n = 0;
+        for (const [k, val] of Object.entries(v)) {
+            if (n >= DETAIL_MAX_KEYS)
+                break;
+            const s = sanitizeValue(val, depth + 1);
+            if (s === undefined)
+                continue;
+            rec[k] = s;
+            n++;
+        }
+        return rec;
+    }
+    return undefined; // function / symbol / bigint / undefined
+}
+/**
+ * `engine_notice` 载荷构造器(三条终点腿同源:live SSE / durable 账本 / 未来的任何第四条腿)。
+ *
+ * 与 `trace/project.ts` 的 `*EventData` 族同纪律(白名单挑键、禁 `{...notice}`),但**不住在那个文件里**:
+ * 那一族的入参全是 core `TaskEvent` 的臂(有 `wire-whitelist-exhaustiveness` 的臂集编译门看着),
+ * 而 `EngineNotice` 不是 `TaskEvent` —— 混进去会让那道门的语义变成"两个不同来源的联合",判别力反而降。
+ */
+export function engineNoticeEventData(notice, sessionId, nowMs) {
+    return {
+        code: notice.code,
+        message: redactSecrets(String(notice.message)).slice(0, NOTICE_TEXT_MAX),
+        detail: sanitizeNoticeDetail(notice.detail),
+        sessionId,
+        ts: nowMs,
+    };
+}
+let nextLegId = 1;
+/**
+ * sessionId → 该会话活跃 run 腿的投递口。**进程内**(`defaultSubagentTailBus` 同款姿势):
+ * `onNotice` 是同进程的同步回调,通告与它要投的那条腿必然同副本,跨副本路由这件事结构上不存在。
+ *
+ * 🔴 跨 session 隔离靠的是 **Map 键的精确串相等**,不是任何「最近活跃」回落 —— 缺席就是缺席(G5)。
+ *
+ * 🔴 **同 session 的跨代隔离靠 legId「最新代独占」**(#310 codex 对抗复审 R1-[high],验真后修)。
+ * 病(真窗,本仓每一处 in-flight 登记都为它写过 identity-guard):run 行在**流体内**就已 setTerminal /
+ * setSuspended,而本腿的注销在 `finally` —— 中间那一窗里,同一条 session 上的**下一条腿**(快速续跑 /
+ * 紧接着的新提交)已经注册好了自己的口。若按「会话内全量扇出」投,新腿的一条通告会**同时**落进:
+ *  · 旧腿那条已 end 的 SSE(顶多记一次 fail-open,无害),以及
+ *  · **旧 taskId 的账本** —— 一条不属于那条 run 的、终态之后的行;resume 复用同 taskId 时还会与新腿
+ *    抢同一个 `(task_id, seq)` 域。这不是跨租户泄露,是**同租户跨 run 的账本污染**,同样必须关死。
+ * 药:每次 `registerLeg` 铸一个单调 legId,`route` **只投最新代**;旧代的口留在表里(它自己的注销仍
+ * 按身份精确删,不会误删新代),但一帧都收不到。方向 = fail-closed(宁可旧腿少一帧,不可新腿的事实
+ * 写进旧腿的账)。
+ */
+export class EngineNoticeRouter {
+    legs = new Map();
+    /**
+     * 登记**一条腿**的全部口(live / durable 作为**一代**同进同出)。返回注销函数(幂等,身份精确删)。
+     *
+     * 每只口各自 try 隔离在 {@link route} 里,单口抛不牵连同腿另一口。
+     */
+    registerLeg(sessionId, sinks) {
+        const leg = { legId: nextLegId++, sinks: [...sinks] };
+        const list = this.legs.get(sessionId) ?? [];
+        list.push(leg); // 追加 = 本代成为最新代
+        this.legs.set(sessionId, list);
+        let done = false;
+        return () => {
+            if (done)
+                return;
+            done = true;
+            const cur = this.legs.get(sessionId);
+            if (!cur)
+                return;
+            const at = cur.indexOf(leg); // 身份精确删:绝不按位置/长度删(会误删新代)
+            if (at >= 0)
+                cur.splice(at, 1);
+            if (cur.length === 0)
+                this.legs.delete(sessionId);
+        };
+    }
+    /** 单口腿的便捷形(测试与单终点腿用)。 */
+    register(sessionId, sink) {
+        return this.registerLeg(sessionId, [sink]);
+    }
+    /** 诊断/门用:某会话此刻**最新代**有几只口在听(旧代不计——它们收不到帧)。 */
+    sinkCount(sessionId) {
+        const list = this.legs.get(sessionId);
+        return list && list.length > 0 ? list[list.length - 1].sinks.length : 0;
+    }
+    /** 诊断/门用:某会话此刻有几代腿在表里(>1 = 正处在换代窗内)。 */
+    legCount(sessionId) {
+        return this.legs.get(sessionId)?.length ?? 0;
+    }
+    /**
+     * 分流器的 wire 半场。返回**真投出去的口数**(0 = 没投:非白名单码 / 缺 sessionId / 该会话无活跃腿)。
+     *
+     * 单只口抛错**不吃掉同腿的其它口**(fleet bus 订阅者隔离同理由),并按 F 类登记留痕。
+     */
+    route(notice, nowMs = Date.now()) {
+        if (!isEngineNoticeWireCode(notice.code))
+            return 0;
+        const sessionId = engineNoticeSessionId(notice);
+        if (sessionId === undefined)
+            return 0; // 如实不投(顶注:宁缺席不串台)
+        const list = this.legs.get(sessionId);
+        const leg = list && list.length > 0 ? list[list.length - 1] : undefined; // 只投最新代
+        if (!leg || leg.sinks.length === 0)
+            return 0;
+        const row = engineNoticeEventData(notice, sessionId, nowMs);
+        let delivered = 0;
+        for (const sink of leg.sinks) {
+            try {
+                sink(row);
+                delivered++;
+            }
+            catch {
+                recordFailOpen("server.engine-notice.wire-sink-threw", `code=${notice.code}`);
+            }
+        }
+        return delivered;
+    }
+}
+/** 进程单例(`defaultSubagentTailBus` 同款):分流器与 run 腿直接 import,不穿长参数列表;测试自 new 独立实例。 */
+export const defaultEngineNoticeRouter = new EngineNoticeRouter();
+/**
+ * run 腿的注册助手 —— 三条腿(sync stream / bg / resume-verify)用**同一个**形,免得各写一份漂。
+ *
+ * `sessionId` 缺席(adhoc 无会话腿)⇒ 返回 no-op 注销函数,一个字节不注册(顶注的 fail-closed 方向)。
+ * `live` / `durable` 各自可缺席:bg 腿没有 live SSE(消费方走 events tail),ephemeral sync 腿没有账本。
+ *
+ * 🔴 两口注册成**两只独立 sink**(不是一只闭包里顺序调两次):route 的隔离粒度是 sink,合成一只会让
+ * live 写(断连的 socket、JSON.stringify 抛)吃掉同一拍的 durable 落账 —— 而 durable 那半正是断连之后
+ * 唯一还看得见这条通告的地方(G3),两者的失败必须互不牵连。
+ */
+export function registerEngineNoticeLeg(opts) {
+    const { sessionId, live, durable } = opts;
+    if (sessionId === undefined || sessionId.length === 0)
+        return () => undefined;
+    const sinks = [...(live ? [live] : []), ...(durable ? [durable] : [])];
+    if (sinks.length === 0)
+        return () => undefined;
+    // 🔴 两口登记成**同一代**(`registerLeg` 一次调用)而不是两次 `register`:代是"腿"的属性,拆成两代
+    // 会让换代时旧腿的一只口先被超代、另一只还没 —— 半代状态没有任何正确语义。口的失败隔离是 `route`
+    // 里的 per-sink try(与代无关),两者是正交的两件事。
+    return (opts.router ?? defaultEngineNoticeRouter).registerLeg(sessionId, sinks);
+}
+//# sourceMappingURL=engine-notice-wire.js.map

package/dist/trace/ledger-events.d.ts

@@ -39,5 +39,15 @@ export type LedgerEventType = "reasoning" | "text" | "tool_start" | "tool_end" |
 /** design/172 §4.3 新协议的呈卡帧(与上面两只 tool_approval 帧同一条投递面)。 */
  | "approval_request"
 /** 异步 workflow 完成的入箱 drain(`emitPendingWorkflowCompletions` 两个字面型之一)。 */
- | "workflow_complete";
+ | "workflow_complete"
+/**
+ * #310 `engine_notice` —— core `EngineNotice` 白名单三码按 `detail.sessionId` 路由到该会话的事件投影。
+ *
+ * 🔴 **是"腿自己的带外行",不是流事件投影**:它不经 `TaskStream`(`RunnerDeps.onNotice` 是 deps 级
+ * 同步 sink),所以两条 durable 腿的 `switch (ev.type)` 里**没有也不该有** `case "engine_notice"` ——
+ * `test/durable-append-arm-parity.test.ts` 的差集是按那个 switch 抽的,本型结构上在它射程之外
+ * (与 `elicitation` / `question` / `approval_request` / `model_usage` 同类)。本型的"三腿是否都挂了口"
+ * 由 `test/engine-notice-wire.test.ts` 的腿覆盖门看守,那才是它的对位门。
+ */
+ | "engine_notice";
 //# sourceMappingURL=ledger-events.d.ts.map

package/dist/trace/ledger-sink.d.ts

@@ -70,6 +70,23 @@ export interface LedgerSink {
         status?: string;
     }): Promise<void>;
 }
+/**
+ * **单写串行链**的可复用形(#310 codex 对抗复审 R1-[high],验真后修)—— `seq` 的**分配发生在链步内**,
+ * 于是「分配序 == 发起序 == 提交序」。
+ *
+ * 病(实测形,`LedgerSink` 内部早有这条纪律的内联版、其顶注 [1.211 codex H2] 逐字记着它):裸写口
+ * (`(type, data) => rs.appendEvent(taskId, ++seq, type, data)`)在**同步分配 seq、立刻发起 insert**。
+ * 主循环 await 自己的写,所以主循环内部有序;但只要有**一个 fire-and-forget 写者**(子代 forward 帧、
+ * #310 的通告口),它的 N 号 insert 可能在池化 SQL 后端上晚于后发的 N+1 号提交。events tail 的读法是
+ * `getEvents(id, afterSeq)` —— 读到 N+1 就把游标推过 N,**那一行此后永远不会被投递**(重连也不会,
+ * 游标只前进)。行在库里,消费端结构性看不见。
+ *
+ * 药:所有写口共用一条 promise 链,`++seq` 在链步内取。链上一步失败**不断链**(catch → undefined),
+ * 调用方仍拿到自己那一步的真实结果(await 者照常收到 reject)——与 `LedgerSink` 内联版逐字同语义。
+ *
+ * ⚠️ 用它的前提是**这条腿的全部写口都走它**(混用一个绕开链的写口 = 病灶原样保留)。
+ */
+export declare function createSerialLedgerAppend(appendEvent: (seq: number, type: LedgerEventType, data: unknown) => Promise<void>, startSeq: number): (type: LedgerEventType, data: unknown) => Promise<void>;
 export declare function createLedgerSink(opts: {
     /** The seq-stamped durable append — typically `(seq, type, data) => runStore.appendEvent(taskId, seq, type, data)`. */
     appendEvent: (seq: number, type: LedgerEventType, data: unknown) => Promise<void>;