@sema-agent/server 7.36.0-rc.1 → 7.37.0-rc.1

package/dist/plugins/task-list-store-sql.d.ts

@@ -1,35 +1,46 @@
-/**
- * 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 type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
 import { type TaskListStore } from "@sema-agent/core";
 export declare const TASK_LIST_META_TABLE = "task_list_meta";
 export declare 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 declare function taskListKeyFor(sessionId: string): string;
 export declare function ensureTiDBTaskListSchema(pool: MySqlPool): Promise<void>;
 export declare function ensurePgTaskListSchema(q: (text: string, params?: unknown[]) => Promise<unknown>): Promise<void>;
+/**
+ * 整份清单删除(#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 declare function deleteTiDBTaskList(pool: MySqlPool, listKey: string): Promise<void>;
+/** {@link deleteTiDBTaskList} 的 PG 孪生(同语义、同事务姿势)。 */
+export declare function deletePgTaskList(pool: PgPool, listKey: string): Promise<void>;
 export declare function createTiDBTaskListStore(pool: MySqlPool, listKey: string): TaskListStore;
 export declare function createPgTaskListStore(pool: PgPool, listKey: string): TaskListStore;
 //# sourceMappingURL=task-list-store-sql.d.ts.map

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/store-live-probe.d.ts

@@ -11,6 +11,8 @@
  * - 翻转披露(§M):live→dead warn `store_probe_dead`、dead→live info `store_probe_recovered`,
  *   只在翻转拍记(连续死不逐拍刷日志——down 的 DB 不该制造日志风暴);
  * - 诚实缺席:首拍落地前 state() = undefined(/health 键缺席=「还没探过」,不冒充「活」)。
+ * - 面分级(#305):`state().error` 是**原始** message —— 它只喂给凭证后/本机的消费面;免鉴权的
+ *   `/health` 一格由 wire 装配点过 {@link publicStoreProbeError} 换成闭集词(理由见该常量头注)。
  *
  * 探针原语:调用方给 `probe`(main.ts 传 `() => backend.dbNowMs!()`——既有 S10 时钟探针的真 DB
  * 往返,零新 SQL 面)。timer 全部 unref(环不得阻止进程退出)。
@@ -28,6 +30,30 @@ export interface StoreLiveProbe {
     state: () => StoreLiveState | undefined;
     stop: () => void;
 }
+/**
+ * #305(安全轴):`/health` 免鉴权面上 `storeProbe.error` 可披露的**闭集词表**。
+ *
+ * 为什么必须是闭集而不是「脱敏后的原文」:`/health` 排在 `http/server.ts` 的鉴权门**之前**、缺省全网卡
+ * 监听 ⇒ 任何能连到这个端口的人都读得到这一格;而它此前装的是**驱动原始异常 message 逐字**,DB 驱动
+ * 的连接类异常惯于把整条 DSN 回声进去(`mysql://user:pass@host:3306/db`)或带上内网主机名/账号名。
+ * `trace/redact.ts` 的 `redactSecrets` **挡不住这条**:它的 URL-userinfo 规则只把口令换成 `«redacted»`,
+ * **用户名与 `@` 之后的主机原样留下** —— 而本条要防的正是那两个。闭集词是严格更强的形(值恒为下列
+ * 字面量之一,构造上不可能携带调用方文本),因此不再叠加脱敏/长度帽:对一个恒为字面量的返回值,那两道
+ * 都只是装饰。
+ *
+ * 信息不丢:**完整原文走日志轴** —— 环在 live→dead 翻转拍打的 `store_probe_dead` warn 带 `{ error }`
+ * 原文,运维在自己的日志/采集里读得到全文,那一面本来就是凭证后的。
+ */
+export declare const STORE_PROBE_PUBLIC_PHRASES: readonly ["probe_timeout", "connection_refused", "connection_reset", "host_unreachable", "dns_failure", "network_timeout", "auth_failed", "connection_limit", "probe_failed"];
+export type StoreProbePublicPhrase = (typeof STORE_PROBE_PUBLIC_PHRASES)[number];
+/**
+ * 原始探针异常 message → 免鉴权面可披露的闭集词。**返回值恒是 {@link STORE_PROBE_PUBLIC_PHRASES} 的
+ * 一个字面量**(返回类型即闭集,写错一个词是编译错误),永不回声入参。
+ *
+ * 误分类的代价是「运维读到的分类不精确」,**不是泄露** —— 所以这里的判别用宽松的子串包含即可,不必为
+ * 精确性把原文碎片带出来。臂序有意义:自家的 race 超时先于泛化的 timeout 臂。
+ */
+export declare function publicStoreProbeError(raw: string): StoreProbePublicPhrase;
 export declare function createStoreLiveProbe(opts: {
     probe: () => Promise<unknown>;
     intervalMs: number;

package/dist/store-live-probe.js

@@ -11,12 +11,72 @@
  * - 翻转披露(§M):live→dead warn `store_probe_dead`、dead→live info `store_probe_recovered`,
  *   只在翻转拍记(连续死不逐拍刷日志——down 的 DB 不该制造日志风暴);
  * - 诚实缺席:首拍落地前 state() = undefined(/health 键缺席=「还没探过」,不冒充「活」)。
+ * - 面分级(#305):`state().error` 是**原始** message —— 它只喂给凭证后/本机的消费面;免鉴权的
+ *   `/health` 一格由 wire 装配点过 {@link publicStoreProbeError} 换成闭集词(理由见该常量头注)。
  *
  * 探针原语:调用方给 `probe`(main.ts 传 `() => backend.dbNowMs!()`——既有 S10 时钟探针的真 DB
  * 往返,零新 SQL 面)。timer 全部 unref(环不得阻止进程退出)。
  */
 /** 单拍探针上界——挂死连接的判死时间;3s 对 15s 默认间隔留足余量(环内串行,无叠拍)。 */
 export const STORE_PROBE_TIMEOUT_MS = 3000;
+/**
+ * #305(安全轴):`/health` 免鉴权面上 `storeProbe.error` 可披露的**闭集词表**。
+ *
+ * 为什么必须是闭集而不是「脱敏后的原文」:`/health` 排在 `http/server.ts` 的鉴权门**之前**、缺省全网卡
+ * 监听 ⇒ 任何能连到这个端口的人都读得到这一格;而它此前装的是**驱动原始异常 message 逐字**,DB 驱动
+ * 的连接类异常惯于把整条 DSN 回声进去(`mysql://user:pass@host:3306/db`)或带上内网主机名/账号名。
+ * `trace/redact.ts` 的 `redactSecrets` **挡不住这条**:它的 URL-userinfo 规则只把口令换成 `«redacted»`,
+ * **用户名与 `@` 之后的主机原样留下** —— 而本条要防的正是那两个。闭集词是严格更强的形(值恒为下列
+ * 字面量之一,构造上不可能携带调用方文本),因此不再叠加脱敏/长度帽:对一个恒为字面量的返回值,那两道
+ * 都只是装饰。
+ *
+ * 信息不丢:**完整原文走日志轴** —— 环在 live→dead 翻转拍打的 `store_probe_dead` warn 带 `{ error }`
+ * 原文,运维在自己的日志/采集里读得到全文,那一面本来就是凭证后的。
+ */
+export const STORE_PROBE_PUBLIC_PHRASES = [
+    "probe_timeout",
+    "connection_refused",
+    "connection_reset",
+    "host_unreachable",
+    "dns_failure",
+    "network_timeout",
+    "auth_failed",
+    "connection_limit",
+    /** 未识别臂 —— **刻意的**:分类不认得的异常一律丢原文取本词(fail-closed 的默认方向是「少说」,
+     *  不是「截断了再说」;截断的前 160 字恰恰是驱动最爱放 DSN 的位置)。 */
+    "probe_failed",
+];
+/**
+ * 原始探针异常 message → 免鉴权面可披露的闭集词。**返回值恒是 {@link STORE_PROBE_PUBLIC_PHRASES} 的
+ * 一个字面量**(返回类型即闭集,写错一个词是编译错误),永不回声入参。
+ *
+ * 误分类的代价是「运维读到的分类不精确」,**不是泄露** —— 所以这里的判别用宽松的子串包含即可,不必为
+ * 精确性把原文碎片带出来。臂序有意义:自家的 race 超时先于泛化的 timeout 臂。
+ */
+export function publicStoreProbeError(raw) {
+    const t = raw.toLowerCase();
+    if (t.includes("probe timed out"))
+        return "probe_timeout"; // 本环自铸的 race 超时(见 probeOnce)
+    if (t.includes("econnrefused") || t.includes("connection refused"))
+        return "connection_refused";
+    if (t.includes("econnreset") || t.includes("connection reset"))
+        return "connection_reset";
+    if (t.includes("ehostunreach") || t.includes("enetunreach") || t.includes("enetdown"))
+        return "host_unreachable";
+    if (t.includes("enotfound") || t.includes("eai_again") || t.includes("getaddrinfo"))
+        return "dns_failure";
+    if (t.includes("etimedout") || t.includes("timed out") || t.includes("timeout"))
+        return "network_timeout";
+    // mysql `ER_ACCESS_DENIED_ERROR` / pg `28P01 password authentication failed` / 通用 auth 措辞。
+    if (t.includes("access denied") || t.includes("authentication failed") || t.includes("28p01") || t.includes("er_access_denied") || t.includes("er_dbaccess_denied")) {
+        return "auth_failed";
+    }
+    // mysql `ER_CON_COUNT_ERROR` / pg `53300 sorry, too many clients already` / 池耗尽措辞。
+    if (t.includes("too many connections") || t.includes("too many clients") || t.includes("53300") || t.includes("er_con_count_error") || t.includes("connection slots")) {
+        return "connection_limit";
+    }
+    return "probe_failed";
+}
 export function createStoreLiveProbe(opts) {
     const timeoutMs = opts.timeoutMs ?? STORE_PROBE_TIMEOUT_MS;
     let last;

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