@sema-agent/server 7.56.0 → 7.58.0

package/dist/plugins/local-checkpoint-store.js

@@ -231,6 +231,9 @@ export class LocalCheckpointStore {
         }
         return out;
     }
+    async peekScopeByToken(token) {
+        return (await this.inner.get(token))?.scope;
+    }
     async peekPendingScope(sessionId, binding) {
         return this.pickPendingRow(await this.pendings(), sessionId, binding)?.cp.scope;
     }

package/dist/plugins/mailbox-store-sql.d.ts

@@ -7,15 +7,19 @@
  * 终版文本,conformance 无两可):
  *  1. **同主重 claim = 续期 + 纳新**(crash-retry 正形):活 lease 只挡**别的** owner;同 owner 任意
  *     时刻重 claim 重设 TTL 并拿到当前全部未 ack 消息(maxSeq 随最新行走)。
- *  2. **seq = 盒生命周期内不复用**:box 行携 `next_seq`,分配与 append 同事务;`drop`/`reap` 删整盒
- *     (含 box 行)= 生命周期终结,重建从 1(core 定谳:行随盒亡,dedup 键携 handle)。
+ *  2. **seq = 盒生命周期内不复用**:box 行携 `next_seq`,分配与 append 同事务;`drop` 删整盒(含 box 行)
+ *     = 生命周期终结,重建从 1(core 定谳:行随盒亡,dedup 键携 handle)。⚠️ **`reap` 自 [ref](core
+ *     2026-07-25)起不再与 drop 同句**:reap 是收件人活着时的龄扫,**清箱保高水位**(删消息、清租约、盒行与
+ *     next_seq 留着)——本文件 2026-09-03(车BF,codex r1 [high])才跟上;此前 reap 删盒行 ⇒ 下一条 append 从 1
+ *     重铸,陈旧 ack 可删掉一条没人见过的新消息。跨进程试剂盒明钉此条。
  *  3. **ack 无 owner 守卫**(信任 claim 赢者链):`seq <= upToSeq` 删行;lease 的 `maxSeq <= upToSeq`
  *     时顺带清 lease(全量 ack = 释放)。
  *  4. **lease 过期判 = 严格 `expiresAt > now` 才挡**;`releaseLease` 只在 owner 匹配时清。
  *  5. `peekCount` 含已 lease 消息(可见性 ≠ lease 态);空盒 claim = null(box 行在而消息 0 也 null)。
  *  6. **reap = SQL 全量真扫**(core File 实现只扫已加载盒 = 进程内 backstop,[ref] 确认 SQL 是全量
- *     真扫的正确层):`maxAgeMs` 缺省 → 0;按盒 newest `sentAt < now - maxAgeMs` 删整盒;空盒(有
- *     box 行无消息)不删(InMemory 同形——`newest === undefined` 不删)。
+ *     真扫的正确层):`maxAgeMs` 缺省 → 0;按盒 newest `sentAt < now - maxAgeMs` **清箱**(删消息 + 清租约,
+ *     盒行/高水位保留,见定谳 2 的 [ref] 半句);空盒(有 box 行无消息)不清(InMemory 同形——`newest ===
+ *     undefined` 不动)。
  *
  * 键列 = 字节等价(TiDB VARBINARY / PG COLLATE "C",roster F2 案):scope/handle/lease_owner 的
  * `=` 必须纯字节——PAD SPACE 近撞不得穿隔离/抢别人 lease。PG unstorable bytes([ref] 三层定谳):
@@ -37,15 +41,28 @@
  */
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
-import type { MailboxLease, MailboxStore } from "@sema-agent/core";
-type MailboxAppendMessage = Parameters<MailboxStore["append"]>[2];
+import type { MailboxAppendMessage, MailboxLease, MailboxStore } from "@sema-agent/core";
 export declare const MAILBOX_TABLE = "mailbox";
 export declare const MAILBOX_MSG_TABLE = "mailbox_message";
+/** 店侧日志座(可选;boot 注入 `Logger`)。7.58.0 合并重扫 [medium]:坏 `peer_meta` 行的 fail-closed 抛必须**响亮**——core 唯一的
+ *  claimLease 调用方(peer-session-drain)吞掉该错,店不记这一笔就成了「静默永久卡箱」。抛之前记 `mailbox_peer_meta_corrupt`
+ *  (scope/handle/seq/code),运维按 seq 修行。 */
+export interface MailboxStoreLogger {
+    warn(event: string, fields: Record<string, unknown>): void;
+}
 export declare function ensureTiDBMailboxSchema(pool: MySqlPool): Promise<void>;
 export declare function ensurePgMailboxSchema(q: (text: string, params?: unknown[]) => Promise<unknown>): Promise<void>;
 export declare class TiDBMailboxStore implements MailboxStore {
     private readonly pool;
-    constructor(pool: MySqlPool);
+    private readonly logger?;
+    /** [ref]([ref] §1.2⑥):跨进程安全**显式**声明 —— core 的 `mailboxCrossProcessMountVerdict` 只对字面 `true` 放行
+     *  peer lane(缺席/false/畸形一律响亮拒挂 `config.peer_lane_unmounted`)。真值前提 = 本文件头注「并发正确性」段:seq
+     *  在事务内经盒行 FOR UPDATE 单铸、lease/ack/drop/reap 统一盒行锁序、reap 事务内逐盒当前读重验 —— 多副本(=多 OS
+     *  进程)共享一个盒本就是 SQL 双生的设计象限。**终验** = core 跨进程试剂盒 `mailboxCrossProcessContract` 跑在真第二个
+     *  OS 进程上:`test/mailbox-cross-process-kit.test.ts`(file 腿恒跑验 harness;tidb/pg 腿 ENV-GATED,发车前双库门必跑,
+     *  红即摘本声明——core 契约逐字「declares true AFTER passing」,声明不许先于试剂盒长期悬空)。 */
+    readonly crossProcessSafe = true;
+    constructor(pool: MySqlPool, logger?: MailboxStoreLogger | undefined);
     private tx;
     append(scope: string, handle: string, msg: MailboxAppendMessage): Promise<number>;
     claimLease(scope: string, handle: string, owner: string, ttlMs: number, now?: number): Promise<MailboxLease | null>;
@@ -59,7 +76,10 @@ export declare class TiDBMailboxStore implements MailboxStore {
 }
 export declare class PgMailboxStore implements MailboxStore {
     private readonly pool;
-    constructor(pool: PgPool);
+    private readonly logger?;
+    /** [ref] 跨进程安全显式声明(TiDB 孪生同注:事务 + 盒行 FOR UPDATE 锁序是真值前提;终验 = test/mailbox-cross-process-kit.test.ts pg 腿)。 */
+    readonly crossProcessSafe = true;
+    constructor(pool: PgPool, logger?: MailboxStoreLogger | undefined);
     private tx;
     /** 身份键拒绝式([ref] 协议纪律):scope/handle/owner/from 清洗形变 = 路由/attribution 错位。 */
     private assertIdentity;
@@ -73,5 +93,4 @@ export declare class PgMailboxStore implements MailboxStore {
         maxAgeMs?: number;
     }): Promise<number>;
 }
-export {};
 //# sourceMappingURL=mailbox-store-sql.d.ts.map

package/dist/plugins/mailbox-store-sql.js

@@ -1,3 +1,4 @@
+import { MAILBOX_INVALID_PEER_META_CODE, MailboxStoreError, readMailboxPeerMeta } from "@sema-agent/core";
 import { pgHasUnstorable, pgSanitizeText, PgUnstorableError } from "./pg-safe-json.js";
 export const MAILBOX_TABLE = "mailbox";
 export const MAILBOX_MSG_TABLE = "mailbox_message";
@@ -43,14 +44,61 @@ function decodeHopChain(raw) {
         return undefined;
     return parsed;
 }
+const PEER_META_MAX_BYTES = 60_000;
+function encodePeerMeta(raw) {
+    const meta = readMailboxPeerMeta(raw);
+    if (meta === undefined)
+        return null;
+    const text = JSON.stringify(meta);
+    if (Buffer.byteLength(text, "utf8") > PEER_META_MAX_BYTES) {
+        throw new Error(`MailboxStore: peerMeta exceeds the ${PEER_META_MAX_BYTES}-byte column (refusing — a truncated record would silently read back as ABSENT, which the drain treats as a foreign record)`);
+    }
+    return text;
+}
+function decodePeerMeta(raw) {
+    if (raw === null || raw === undefined)
+        return undefined;
+    const text = bufToStr(raw);
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (err) {
+        throw new MailboxStoreError(MAILBOX_INVALID_PEER_META_CODE, `MailboxStore: stored peer_meta is not JSON (refusing the lease — a corrupt typed record must not be read as "no metadata"): ${err instanceof Error ? err.message : String(err)}`);
+    }
+    try {
+        return readMailboxPeerMeta(parsed);
+    }
+    catch (err) {
+        if (err instanceof MailboxStoreError)
+            throw err;
+        throw new MailboxStoreError(MAILBOX_INVALID_PEER_META_CODE, `MailboxStore: stored peer_meta failed validation (refusing the lease): ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+function rowsToMessages(rows, scope, handle, logger) {
+    const out = [];
+    for (const r of rows) {
+        try {
+            out.push(rowToMessage(r));
+        }
+        catch (err) {
+            if (err instanceof MailboxStoreError)
+                logger?.warn("mailbox_peer_meta_corrupt", { scope, handle, seq: Number(r.seq), code: err.code, note: "claimLease refused for the whole box (fail-closed); repair or NULL the peer_meta column of this row" });
+            throw err;
+        }
+    }
+    return out;
+}
 function rowToMessage(r) {
     const hopChain = decodeHopChain(r.hop_chain);
+    const peerMeta = decodePeerMeta(r.peer_meta);
     return {
         seq: Number(r.seq),
         ...(r.from_id !== null && r.from_id !== undefined ? { from: bufToStr(r.from_id) } : {}),
         content: String(r.content),
         sentAt: Number(r.sent_at_ms),
         ...(hopChain !== undefined ? { hopChain } : {}),
+        ...(peerMeta !== undefined ? { peerMeta } : {}),
     };
 }
 export async function ensureTiDBMailboxSchema(pool) {
@@ -75,6 +123,11 @@ export async function ensureTiDBMailboxSchema(pool) {
     -- 见 encodeHopChain 头注:缺席 vs 空数组绝不互折)。TEXT 而非 LONGTEXT——链上界在 core(28 跳,
     -- 短 token),写入面另有 HOP_CHAIN_MAX_BYTES fail-loud 守卫关掉静默截断类。
     hop_chain TEXT NULL,
+    -- peer_meta(S-90;core fc52b4d4 design/385 片2b):drain 点权威判断读的 typed peer 记录,JSON 文本;
+    -- NULL = 缺席(**有语义**:pre-385/foreign 记录,drain 永不回溯准入;与空对象绝不互折)。写入面先过 core
+    -- readMailboxPeerMeta(坏值带码拒于任何副作用前)+ PEER_META_MAX_BYTES 守卫关掉静默截断类。
+    -- 新列按 2026-07-26 schema policy 直接折进 CREATE(不开 ALTER seam,存量库删库重建)。
+    peer_meta TEXT NULL,
     PRIMARY KEY (scope_key, handle, seq),
     KEY idx_mbm_sent (scope_key, handle, sent_at_ms)
   ) COLLATE utf8mb4_bin`);
@@ -98,14 +151,18 @@ export async function ensurePgMailboxSchema(q) {
     content TEXT COLLATE "C" NOT NULL,
     sent_at_ms BIGINT NOT NULL,
     hop_chain TEXT COLLATE "C", -- core 5.17.0 design/176(TiDB twin 同注:NULL = 缺席且有语义)
+    peer_meta TEXT COLLATE "C", -- S-90 core fc52b4d4 design/385 片2b(TiDB twin 同注:typed peer 记录 JSON;NULL = 缺席且有语义)
     PRIMARY KEY (scope_key, handle, seq)
   )`);
     await q(`CREATE INDEX IF NOT EXISTS idx_mbm_sent ON ${MAILBOX_MSG_TABLE} (scope_key, handle, sent_at_ms)`);
 }
 export class TiDBMailboxStore {
     pool;
-    constructor(pool) {
+    logger;
+    crossProcessSafe = true;
+    constructor(pool, logger) {
         this.pool = pool;
+        this.logger = logger;
     }
     async tx(fn) {
         const c = await this.pool.getConnection();
@@ -130,6 +187,7 @@ export class TiDBMailboxStore {
         assertKeyBytes("scope", scope);
         assertKeyBytes("handle", handle);
         const hopChain = encodeHopChain(msg.hopChain);
+        const peerMeta = encodePeerMeta(msg.peerMeta);
         return this.tx(async (c) => {
             await c.query(`INSERT IGNORE INTO ${MAILBOX_TABLE} (scope_key, handle, scope, next_seq) VALUES (?, ?, ?, 1)`, [scope, handle, scope]);
             let [rows] = (await c.query(`SELECT next_seq FROM ${MAILBOX_TABLE} WHERE scope_key = ? AND handle = ? FOR UPDATE`, [scope, handle]));
@@ -139,7 +197,7 @@ export class TiDBMailboxStore {
             }
             const seq = Number(rows[0].next_seq);
             await c.query(`UPDATE ${MAILBOX_TABLE} SET next_seq = ? WHERE scope_key = ? AND handle = ?`, [seq + 1, scope, handle]);
-            await c.query(`INSERT INTO ${MAILBOX_MSG_TABLE} (scope_key, handle, seq, from_id, content, sent_at_ms, hop_chain) VALUES (?, ?, ?, ?, ?, ?, ?)`, [scope, handle, seq, msg.from ?? null, msg.content, msg.sentAt, hopChain]);
+            await c.query(`INSERT INTO ${MAILBOX_MSG_TABLE} (scope_key, handle, seq, from_id, content, sent_at_ms, hop_chain, peer_meta) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`, [scope, handle, seq, msg.from ?? null, msg.content, msg.sentAt, hopChain, peerMeta]);
             return seq;
         });
     }
@@ -154,12 +212,12 @@ export class TiDBMailboxStore {
                 bufToStr(box.lease_owner) !== owner) {
                 return null;
             }
-            const [msgs] = (await c.query(`SELECT seq, from_id, content, sent_at_ms, hop_chain FROM ${MAILBOX_MSG_TABLE} WHERE scope_key = ? AND handle = ? ORDER BY seq FOR UPDATE`, [scope, handle]));
+            const [msgs] = (await c.query(`SELECT seq, from_id, content, sent_at_ms, hop_chain, peer_meta FROM ${MAILBOX_MSG_TABLE} WHERE scope_key = ? AND handle = ? ORDER BY seq FOR UPDATE`, [scope, handle]));
             if (msgs.length === 0)
                 return null;
             const maxSeq = Number(msgs[msgs.length - 1].seq);
             await c.query(`UPDATE ${MAILBOX_TABLE} SET lease_owner = ?, lease_expires_at_ms = ?, lease_max_seq = ? WHERE scope_key = ? AND handle = ?`, [owner, now + ttlMs, maxSeq, scope, handle]);
-            return { messages: msgs.map(rowToMessage), maxSeq };
+            return { messages: rowsToMessages(msgs, scope, handle, this.logger), maxSeq };
         });
     }
     async ack(scope, handle, owner, upToSeq) {
@@ -203,8 +261,8 @@ export class TiDBMailboxStore {
                 const [newest] = (await c.query(`SELECT sent_at_ms FROM ${MAILBOX_MSG_TABLE} WHERE scope_key = ? AND handle = ? ORDER BY sent_at_ms DESC LIMIT 1 FOR UPDATE`, [scope, h]));
                 if (newest.length === 0 || Number(newest[0].sent_at_ms) >= cutoff)
                     continue;
-                await c.query(`DELETE FROM ${MAILBOX_TABLE} WHERE scope_key = ? AND handle = ?`, [scope, h]);
                 await c.query(`DELETE FROM ${MAILBOX_MSG_TABLE} WHERE scope_key = ? AND handle = ?`, [scope, h]);
+                await c.query(`UPDATE ${MAILBOX_TABLE} SET lease_owner = NULL, lease_expires_at_ms = NULL, lease_max_seq = NULL WHERE scope_key = ? AND handle = ?`, [scope, h]);
                 dropped++;
             }
             return dropped;
@@ -213,8 +271,11 @@ export class TiDBMailboxStore {
 }
 export class PgMailboxStore {
     pool;
-    constructor(pool) {
+    logger;
+    crossProcessSafe = true;
+    constructor(pool, logger) {
         this.pool = pool;
+        this.logger = logger;
     }
     async tx(fn) {
         const c = await this.pool.connect();
@@ -245,6 +306,7 @@ export class PgMailboxStore {
         assertKeyBytes("scope", scope);
         assertKeyBytes("handle", handle);
         const hopChain = encodeHopChain(msg.hopChain);
+        const peerMeta = encodePeerMeta(msg.peerMeta);
         return this.tx(async (c) => {
             await c.query(`INSERT INTO ${MAILBOX_TABLE} (scope_key, handle, scope, next_seq) VALUES ($1, $2, $3, 1) ON CONFLICT (scope_key, handle) DO NOTHING`, [
                 scope,
@@ -262,7 +324,7 @@ export class PgMailboxStore {
             }
             const seq = Number(rows[0].next_seq);
             await c.query(`UPDATE ${MAILBOX_TABLE} SET next_seq = $1 WHERE scope_key = $2 AND handle = $3`, [seq + 1, scope, handle]);
-            await c.query(`INSERT INTO ${MAILBOX_MSG_TABLE} (scope_key, handle, seq, from_id, content, sent_at_ms, hop_chain) VALUES ($1, $2, $3, $4, $5, $6, $7)`, [scope, handle, seq, msg.from ?? null, content, msg.sentAt, hopChain]);
+            await c.query(`INSERT INTO ${MAILBOX_MSG_TABLE} (scope_key, handle, seq, from_id, content, sent_at_ms, hop_chain, peer_meta) VALUES ($1, $2, $3, $4, $5, $6, $7, $8)`, [scope, handle, seq, msg.from ?? null, content, msg.sentAt, hopChain, peerMeta]);
             return seq;
         });
     }
@@ -275,12 +337,12 @@ export class PgMailboxStore {
             const box = boxes[0];
             if (box.lease_owner !== null && Number(box.lease_expires_at_ms) > now && String(box.lease_owner) !== owner)
                 return null;
-            const { rows: msgs } = await c.query(`SELECT seq, from_id, content, sent_at_ms, hop_chain FROM ${MAILBOX_MSG_TABLE} WHERE scope_key = $1 AND handle = $2 ORDER BY seq FOR UPDATE`, [scope, handle]);
+            const { rows: msgs } = await c.query(`SELECT seq, from_id, content, sent_at_ms, hop_chain, peer_meta FROM ${MAILBOX_MSG_TABLE} WHERE scope_key = $1 AND handle = $2 ORDER BY seq FOR UPDATE`, [scope, handle]);
             if (msgs.length === 0)
                 return null;
             const maxSeq = Number(msgs[msgs.length - 1].seq);
             await c.query(`UPDATE ${MAILBOX_TABLE} SET lease_owner = $1, lease_expires_at_ms = $2, lease_max_seq = $3 WHERE scope_key = $4 AND handle = $5`, [owner, now + ttlMs, maxSeq, scope, handle]);
-            return { messages: msgs.map((r) => rowToMessage(r)), maxSeq };
+            return { messages: rowsToMessages(msgs, scope, handle, this.logger), maxSeq };
         });
     }
     async ack(scope, handle, owner, upToSeq) {
@@ -327,8 +389,8 @@ export class PgMailboxStore {
                 const { rows: newest } = await c.query(`SELECT sent_at_ms FROM ${MAILBOX_MSG_TABLE} WHERE scope_key = $1 AND handle = $2 ORDER BY sent_at_ms DESC LIMIT 1 FOR UPDATE`, [scope, h]);
                 if (newest.length === 0 || Number(newest[0].sent_at_ms) >= cutoff)
                     continue;
-                await c.query(`DELETE FROM ${MAILBOX_TABLE} WHERE scope_key = $1 AND handle = $2`, [scope, h]);
                 await c.query(`DELETE FROM ${MAILBOX_MSG_TABLE} WHERE scope_key = $1 AND handle = $2`, [scope, h]);
+                await c.query(`UPDATE ${MAILBOX_TABLE} SET lease_owner = NULL, lease_expires_at_ms = NULL, lease_max_seq = NULL WHERE scope_key = $1 AND handle = $2`, [scope, h]);
                 dropped++;
             }
             return dropped;

package/dist/plugins/memory-run-store.d.ts

@@ -1,18 +1,6 @@
-/**
- * In-memory async run registry + replayable event log — the LOCAL (DB-less) twin of {@link TiDBRunStore}/
- * {@link PgRunStore} (clay 2026-06-25: the seamless local↔cloud switch — a locally-run HTTP service must serve the
- * SAME contract a cloud worker does, incl. `/v1/runs` async runs + the trace event log). Behaviourally identical to
- * the SQL twins (the shared `storeBehaviorSuite` keeps them in lock-step), but process-local + ephemeral: a restart
- * loses run history (file-backed durability is the immediate follow-on; the conversation HISTORY + checkpoints DO
- * persist via core's FileStorageBackend). Single-process, so the cross-replica/durable reapers degrade — see below.
- *
- * Mirrors the SQL semantics exactly: the `task_active` single-active-run claim (a Map keyed by sessionId), the
- * NON-terminal suspend/needs_review parks that KEEP the claim, the markResuming CAS that resets cancel/preempt, the
- * owner null-safe guard on the flag/heartbeat paths (`<=>` → JS `(a??null)===(b??null)`), and the keyset list order.
- */
 import { type UsageRow } from "../usage-analytics.js";
-import type { TaskResult, TaskStatus } from "@sema-agent/core";
-import type { RunRecord, SessionSummary, RunEvent } from "./store-contracts.js";
+import type { TaskStatus } from "@sema-agent/core";
+import type { RunRecord, SessionSummary, RunEvent, PersistedTaskResult } from "./store-contracts.js";
 import type { LedgerEventType } from "../trace/ledger-events.js";
 /**
  * [ref] P0 — the local lane's stand-in for the SQL twins' checkpoint-table JOIN. The file/memory run stores
@@ -66,7 +54,7 @@ export declare class MemoryRunStore {
     getEvents(taskId: string, afterSeq: number): Promise<RunEvent[]>;
     /** [ref] FIRST terminal writer wins(SQL 孪生同款正向 CAS on running/suspended/needs_review,
      *  [1.207 codex M1] 负向形漏 blocked/timeout);claim 释放保持无条件(幂等)。 */
-    setTerminal(taskId: string, status: TaskStatus, result: TaskResult | null, error: string | null): Promise<void>;
+    setTerminal(taskId: string, status: TaskStatus, result: PersistedTaskResult | null, error: string | null): Promise<void>;
     /** Durable F4: park NON-terminal `suspended`, KEEP the task_active claim. CAS on running/suspended (reaper-revert guard). */
     setSuspended(taskId: string): Promise<void>;
     /** [ref] D-B: park NON-terminal `needs_review`, KEEP the claim. CAS on running/needs_review. */

package/dist/plugins/memory-run-store.js

@@ -1,4 +1,6 @@
+import { redactErrorMessage, redactLedgerEventData, redactTerminalResult } from "../observability/run-terminal-log.js";
 import { projectUsageStats, USAGE_SCAN_LIMIT } from "../usage-analytics.js";
+import { notifyRunTerminal } from "../observability/run-terminal-log.js";
 const ownerEq = (a, b) => (a ?? null) === (b ?? null);
 export class MemoryRunStore {
     runs = new Map();
@@ -78,6 +80,7 @@ export class MemoryRunStore {
             r.updatedAt = new Date();
     }
     async appendEvent(taskId, seq, type, data) {
+        data = redactLedgerEventData(type, data);
         const list = this.events.get(taskId) ?? [];
         if (list.some((e) => e.seq === seq))
             return;
@@ -100,6 +103,8 @@ export class MemoryRunStore {
             .map((e) => ({ ...e, data: e.data == null ? null : structuredClone(e.data) }));
     }
     async setTerminal(taskId, status, result, error) {
+        result = redactTerminalResult(result);
+        error = error === null ? null : (redactErrorMessage(error) ?? null);
         const r = this.runs.get(taskId);
         if (!r) {
             for (const [sessionId, tid] of this.active)
@@ -109,15 +114,29 @@ export class MemoryRunStore {
                 }
             return;
         }
+        let pending;
         if (r.status === "running" || r.status === "suspended" || r.status === "needs_review") {
             r.status = status;
             r.result = result;
             r.error = error;
             r.errorCode = result?.errorCode ?? null;
             r.updatedAt = new Date();
+            pending = {
+                runId: taskId,
+                sessionId: r.sessionId,
+                owner: r.owner,
+                status,
+                resultTaskId: result?.taskId,
+                model: result?.model,
+                errorCode: r.errorCode ?? undefined,
+                errorMessage: result?.errorMessage ?? error ?? undefined,
+                elapsedMs: Math.max(0, Date.now() - r.createdAt.getTime()),
+            };
         }
         if (this.active.get(r.sessionId) === taskId)
             this.active.delete(r.sessionId);
+        if (pending)
+            notifyRunTerminal(pending);
     }
     async setSuspended(taskId) {
         const r = this.runs.get(taskId);

package/dist/plugins/permission-rule-store-file.js

@@ -5,6 +5,7 @@ import { performance } from "node:perf_hooks";
 import { FilePermissionRuleStoreProvider, AppendLog, ensureDir, readJsonlRecords, } from "@sema-agent/core";
 import { z } from "zod";
 import { buildRulePayloadHash } from "./permission-rule-store-sql.js";
+import { EDITED_RULE_BREADTH_WARNING_CODES, RULE_APPROVAL_RECORD_SCHEMA, UNCOVERED_SEGMENT_REASONS } from "../permission-rule-vocab.js";
 const RuleScopeSchema = z.union([
     z.object({ kind: z.literal("global") }).strict(),
     z.object({ kind: z.literal("project"), root: z.string().min(1) }).strict(),
@@ -19,6 +20,7 @@ const RuleOffer2Schema = z.union([
         candidates: z.array(z.number().int().nonnegative().safe()),
         segments: z.array(z.string()).optional(),
         uncoveredSegments: z.number().int().nonnegative().safe().optional(),
+        uncoveredDetail: z.array(z.object({ segment: z.string(), reason: z.enum(UNCOVERED_SEGMENT_REASONS) }).strict()).optional(),
     })
         .strict(),
 ]);
@@ -27,7 +29,7 @@ const ApprovalRecordSchema = z
     id: z.string().min(1),
     principal: z.string().optional(),
     owner: z.union([z.object({ kind: z.literal("principal"), principal: z.string() }).strict(), z.object({ kind: z.literal("local-owner") }).strict()]).optional(),
-    schema: z.literal(2),
+    schema: z.literal(RULE_APPROVAL_RECORD_SCHEMA),
     kind: z.enum(["card", "import", "starter"]),
     state: z.enum(["pending", "approved", "redeemed"]),
     candidates: z.array(RuleCandidateSchema),
@@ -36,7 +38,10 @@ const ApprovalRecordSchema = z
     toolCallId: z.string().optional(),
     boundInputHash: z.string().optional(),
     command: z.string().optional(),
-    edited: z.object({ index: z.number().int().nonnegative().safe(), text: z.string(), at: z.string() }).strict().optional(),
+    edited: z
+        .object({ index: z.number().int().nonnegative().safe(), text: z.string(), at: z.string(), warnings: z.array(z.enum(EDITED_RULE_BREADTH_WARNING_CODES)).optional() })
+        .strict()
+        .optional(),
     rev: z.number().int().nonnegative().safe(),
     selectedOffer: z.number().int().nonnegative().safe().optional(),
     redeemedDots: z.record(z.string(), RuleDotSchema).optional(),
@@ -138,7 +143,7 @@ export class FileRuleApprovalRecordStore {
             const parsed = ApprovalLineSchema.safeParse(raw);
             if (!parsed.success) {
                 const stale = StaleApprovalLineSchema.safeParse(raw);
-                if (stale.success && stale.data.record.schema !== 2) {
+                if (stale.success && stale.data.record.schema !== RULE_APPROVAL_RECORD_SCHEMA) {
                     this.rows.set(stale.data.record.id, toStaleEnvelope(stale.data.record));
                     continue;
                 }

package/dist/plugins/permission-rule-store-sql.js

@@ -4,6 +4,7 @@ import { applyTombstones, assertDeleteDeltaCarriesNoAdd, assertRedemptionNotQuar
 import { dialectProtocolJsonEncoder } from "./sql-driver.js";
 import { isMissingColumnError } from "./sql-errors.js";
 import { canonicalJson } from "../canonical-json.js";
+import { EDITED_RULE_BREADTH_WARNING_CODES, PERSISTED_RULE_MATCHES, PERSISTED_RULE_TOOLS, RULE_APPROVAL_RECORD_SCHEMA, UNCOVERED_SEGMENT_REASONS } from "../permission-rule-vocab.js";
 export function writerOfSqlRuleStore(store) {
     const w = Reflect.get(store, PERMISSION_RULE_WRITER);
     if (w === null || typeof w !== "object")
@@ -26,8 +27,8 @@ const RuleAddSchema = z
 const PersistedAllowRuleSchema = z
     .object({
     rule: z.string(),
-    tool: z.literal("Bash"),
-    match: z.enum(["exact", "prefix"]),
+    tool: z.enum(PERSISTED_RULE_TOOLS),
+    match: z.enum(PERSISTED_RULE_MATCHES),
     command: z.string(),
     scope: DurableRuleScopeSchema,
     adds: z.array(RuleAddSchema),
@@ -52,7 +53,9 @@ const QuarantinedRuleAddSchema = z
 const FrontierSchema = z.record(z.string(), z.number().int().nonnegative().safe());
 const RuleCandidateSchema = z.object({ rule: z.string(), scope: DurableRuleScopeSchema }).strict();
 const RedeemedDotsSchema = z.record(z.string(), RuleDotSchema);
-const RuleEditedSchema = z.object({ index: z.number().int().nonnegative().safe(), text: z.string(), at: z.string() }).strict();
+const RuleEditedSchema = z
+    .object({ index: z.number().int().nonnegative().safe(), text: z.string(), at: z.string(), warnings: z.array(z.enum(EDITED_RULE_BREADTH_WARNING_CODES)).optional() })
+    .strict();
 const RuleOffer2Schema = z.union([
     z.object({ kind: z.literal("single"), candidate: z.number().int().nonnegative().safe() }).strict(),
     z
@@ -61,6 +64,7 @@ const RuleOffer2Schema = z.union([
         candidates: z.array(z.number().int().nonnegative().safe()),
         segments: z.array(z.string()).optional(),
         uncoveredSegments: z.number().int().nonnegative().safe().optional(),
+        uncoveredDetail: z.array(z.object({ segment: z.string(), reason: z.enum(UNCOVERED_SEGMENT_REASONS) }).strict()).optional(),
     })
         .strict(),
 ]);
@@ -104,8 +108,9 @@ export const TIDB_PERMISSION_RULE_STATEMENTS = [
     state VARCHAR(32) NOT NULL,
     rev BIGINT NOT NULL DEFAULT 0,
     candidates_json LONGTEXT NOT NULL,
-    -- version:**数据格式版本**(= core \`RuleApprovalRecord.schema\`,本形恒 2;OCC 守卫另在 rev,
-    -- 两轴禁混,schema-naming 门③ 白名单登记)。读侧对非 2 的行交还 design/375 §4.5 的
+    -- version:**数据格式版本**(= core \`RuleApprovalRecord.schema\`,本形恒 3 —— design/382 §3.5 由 2 升,
+    -- 代码里的单点是 RULE_APPROVAL_RECORD_SCHEMA;OCC 守卫另在 rev,两轴禁混,schema-naming 门③ 白名单
+    -- 登记)。读侧对非 3 的行(含上一形的 2)交还 design/375 §4.5 的
     -- StaleRuleApprovalRecord 信封(identity 键 only)—— 本仓 SCHEMA POLICY 是删表重建,重建后的表
     -- 不该有这种行,这一臂是「未来再换形」的防御位,绝不静默 widen 成一条本形担保不了的记录。
     version INT NOT NULL,
@@ -258,7 +263,8 @@ export async function ensurePgPermissionRuleSchema(q) {
     rev BIGINT NOT NULL DEFAULT 0,
     candidates_json TEXT COLLATE "C" NOT NULL,
     -- version / offers_json / selected_offer:design/375 换形三列(MySQL 孪生的行内注写了理由:
-    -- version=数据格式版本恒 2,非 2 的行读成 Stale 信封;offers_json=按 index 引用的 OPTION 结构,
+    -- version=数据格式版本恒 3(design/382 §3.5 由 2 升;单点 RULE_APPROVAL_RECORD_SCHEMA),非 3 的行(含 2)
+    -- 读成 Stale 信封;offers_json=按 index 引用的 OPTION 结构,
     -- 禁存文本副本;selected_offer=确认的 OFFER index,与 ticket/redeemed_dots 的 CANDIDATE index
     -- 两空间分离)。
     version INT NOT NULL,
@@ -525,7 +531,7 @@ export class SqlRuleApprovalRecordStore {
         const ownerKind = String(row.owner_kind);
         const principal = row.principal === null || row.principal === undefined ? undefined : String(row.principal);
         const identity = ownerKind === "principal" ? { principal: principal ?? "" } : { owner: { kind: "local-owner" } };
-        if (Number(row.version) !== 2) {
+        if (Number(row.version) !== RULE_APPROVAL_RECORD_SCHEMA) {
             return { staleSchema: true, id: String(row.record_id), ...identity };
         }
         const candidates = parseColumn(z.array(RuleCandidateSchema), row.candidates_json, "candidates_json", id);
@@ -541,7 +547,7 @@ export class SqlRuleApprovalRecordStore {
         return {
             id: String(row.record_id),
             ...identity,
-            schema: 2,
+            schema: RULE_APPROVAL_RECORD_SCHEMA,
             kind: kind.data,
             state: state.data,
             candidates,
@@ -584,14 +590,14 @@ export class SqlRuleApprovalRecordStore {
         ]);
     }
     async discardPendingRecord(recordId) {
-        const { affected } = await this.db.query(this.q(`DELETE FROM ${PERMISSION_RULE_APPROVAL_TABLE} WHERE record_id = ? AND state = 'pending' AND version = 2`, `DELETE FROM ${PERMISSION_RULE_APPROVAL_TABLE} WHERE record_id = $1 AND state = 'pending' AND version = 2`), [recordId]);
+        const { affected } = await this.db.query(this.q(`DELETE FROM ${PERMISSION_RULE_APPROVAL_TABLE} WHERE record_id = ? AND state = 'pending' AND version = ${RULE_APPROVAL_RECORD_SCHEMA}`, `DELETE FROM ${PERMISSION_RULE_APPROVAL_TABLE} WHERE record_id = $1 AND state = 'pending' AND version = ${RULE_APPROVAL_RECORD_SCHEMA}`), [recordId]);
         return affected === 1;
     }
     async cas(id, expectRev, next) {
         if (next.rev !== expectRev + 1) {
             throw new Error(`rule-approval CAS must advance rev by exactly one (expectRev=${expectRev}, next.rev=${next.rev})`);
         }
-        const { affected } = await this.db.query(this.q(`UPDATE ${PERMISSION_RULE_APPROVAL_TABLE} SET state = ?, rev = ?, candidates_json = ?, offers_json = ?, selected_offer = ?, redeemed_dots_json = ?, edited_json = ?, updated_at_ms = ? WHERE record_id = ? AND rev = ? AND version = 2`, `UPDATE ${PERMISSION_RULE_APPROVAL_TABLE} SET state = $1, rev = $2, candidates_json = $3, offers_json = $4, selected_offer = $5, redeemed_dots_json = $6, edited_json = $7, updated_at_ms = $8 WHERE record_id = $9 AND rev = $10 AND version = 2`), [
+        const { affected } = await this.db.query(this.q(`UPDATE ${PERMISSION_RULE_APPROVAL_TABLE} SET state = ?, rev = ?, candidates_json = ?, offers_json = ?, selected_offer = ?, redeemed_dots_json = ?, edited_json = ?, updated_at_ms = ? WHERE record_id = ? AND rev = ? AND version = ${RULE_APPROVAL_RECORD_SCHEMA}`, `UPDATE ${PERMISSION_RULE_APPROVAL_TABLE} SET state = $1, rev = $2, candidates_json = $3, offers_json = $4, selected_offer = $5, redeemed_dots_json = $6, edited_json = $7, updated_at_ms = $8 WHERE record_id = $9 AND rev = $10 AND version = ${RULE_APPROVAL_RECORD_SCHEMA}`), [
             next.state,
             next.rev,
             this.enc(next.candidates, "permission_rule_approval.candidates_json"),

package/dist/plugins/remote-scratchpad.js

@@ -1,3 +1,4 @@
+import { redactHead } from "../observability/run-terminal-log.js";
 const REMOTE_SCRATCHPAD_LANES = new Set(["e2b", "k8s", "local-docker", "ssh", "device"]);
 export function isRemoteScratchpadLane(provider) {
     return provider !== undefined && REMOTE_SCRATCHPAD_LANES.has(provider);
@@ -28,12 +29,12 @@ export function withRemoteScratchpad(factory, logger) {
                 if (!r.ok || r.value.exitCode !== 0) {
                     logger?.warn?.("remote_scratchpad_mkdir_failed", {
                         dir,
-                        ...(r.ok ? { exitCode: r.value.exitCode, stderr: r.value.stderr.slice(0, 256) } : { error: r.error.message }),
+                        ...(r.ok ? { exitCode: r.value.exitCode, stderr: redactHead(r.value.stderr, 256) } : { error: redactHead(r.error.message, 512) }),
                     });
                 }
             }
             catch (err) {
-                logger?.warn?.("remote_scratchpad_mkdir_failed", { dir, error: err instanceof Error ? err.message : String(err) });
+                logger?.warn?.("remote_scratchpad_mkdir_failed", { dir, error: redactHead(err instanceof Error ? err.message : String(err), 512) });
             }
         })());
         e.exec = async (command, options) => {

package/dist/plugins/run-store-sql.d.ts

@@ -1,47 +1,8 @@
-/**
- * Async run registry (S1) + replayable event log (S2) — SINGLE-FILE DUAL-DIALECT ([ref] A12 定型半场).
- * ONE implementation, TWO dialects; the historical `TiDBRunStore` / `PgRunStore` class names survive as thin
- * ctor subclasses so every consumer (store-backend.ts, the run/reaper/session/usage suites) is untouched.
- *
- * A run is the background execution of one task. `POST /v1/runs` records it `running` and returns
- * immediately; the background driver (`src/runs.ts`) appends events here as they happen and marks the
- * run terminal when done. Because runs + events are durable and shared, any stateless instance can
- * report status or replay the event stream — a client can reconnect (even to a different instance)
- * with `Last-Event-ID` and resume. The two dialects are kept in lock-step by ONE shared integration suite
- * (test/run-store-reaper-integration.test.ts) that runs the SAME park→resume→claim scenario against BOTH
- * real engines — the anti-drift guard.
- *
- * ── Dialect deltas, kept EXPLICIT (never hidden behind an abstraction) ────────────────────────────────
- *   - `?` placeholders vs `$n` (transaction control itself is normalized by `SqlDriver`/`SqlTxConn` —
- *     mysql2's native begin/commit/rollback vs PG's statement form; see sql-driver.ts)
- *   - dup-key classification (createRun's task_active claim race) — the PREDICATE has a single owner
- *     (`sql-errors.ts`, [ref] P1-①); only the dialect DISPATCH is visible here
- *
- * ⚠️ The run ACTIVE-status word list written out in the `status IN (…)` / `NOT IN (…)` fragments below
- * is the closed set owned by `store-contracts.ts` (`isTerminalRunStatus` / `isParkedRunStatus`). The SQL
- * text stays literal ON PURPOSE (A12: both dialects readable side by side), so the tie is a PARITY GATE:
- * `test/source-hygiene-gate.test.ts` → "[ref] P1-② run 活状态 SQL 字面 ↔ store-contracts 闭集属主 parity".
- * core adding a TaskStatus member turns that gate red on every fragment here — update them in the same batch.
- *   - null-safe owner compare: `<=>` (TiDB) vs `IS NOT DISTINCT FROM` (PG) — a null-owner run still matches
- *     `owner=null` on both, single-DB-fleet defense-in-depth (see {@link requestCancel})
- *   - multi-table DELETE: `DELETE t FROM t JOIN j …` (TiDB) vs `DELETE FROM t USING j …` (PG)
- *   - `UPDATE t AS a SET col=…` — PG's SET columns are NOT alias-qualified (PG rejects `SET a.col`), while
- *     TiDB's SET clause DOES qualify (`SET tr.col = …`) — see reapSuspended / failSuspendedWithExpiredCheckpoint
- *   - JSON binding: TiDB `JSON.stringify` verbatim vs PG `pgSafeJsonStringify` + `$n::jsonb` casts
- *   - PG-only protocol-byte defenses on plain-TEXT columns: `pgSanitizeText` on objective_preview (createRun)
- *     and error/error_code (setTerminal) — a raw NUL would throw 22P05 and roll back the whole terminal write,
- *     stranding the run in a live status forever (codex R12); TiDB stores these verbatim
- *   - dynamic multi-clause builders (listRuns/listSessions): TiDB's `?` is position-agnostic so the WHERE
- *     array is built with plain string pushes; PG's `$n` needs numbered placeholders, so those two methods
- *     keep an EXPLICIT per-dialect branch (a shared positional-counter abstraction would hide the very
- *     placeholder-numbering divergence this file exists to keep visible)
- *   - schema ownership: TiDB DDL in tidb-pool.ts, PG DDL centrally in pg-pool.ts (neither store creates tables).
- */
-import type { TaskResult, TaskStatus } from "@sema-agent/core";
+import type { TaskStatus } from "@sema-agent/core";
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
 import { type UsageRow } from "../usage-analytics.js";
-import type { RunRecord, SessionSummary, RunEvent } from "./store-contracts.js";
+import type { RunRecord, SessionSummary, RunEvent, PersistedTaskResult } from "./store-contracts.js";
 import { type SqlDriver } from "./sql-driver.js";
 import type { LedgerEventType } from "../trace/ledger-events.js";
 export type { RunRecord, SessionSummary, RunEvent } from "./store-contracts.js";
@@ -119,7 +80,7 @@ export declare class SqlRunStore {
      *  abort text, or vice versa). Positive form ([1.207 codex M1]): the negative NOT IN missed the
      *  blocked/timeout terminals — a first write of those could still be overwritten. The claim DELETE stays
      *  unconditional (idempotent; the first writer already released it). */
-    setTerminal(taskId: string, status: TaskStatus, result: TaskResult | null, error: string | null): Promise<void>;
+    setTerminal(taskId: string, status: TaskStatus, result: PersistedTaskResult | null, error: string | null): Promise<void>;
     /**
      * Durable F4 ([ref]): a task suspended on a policy `ask`. Sets the run NON-terminal `suspended` and
      * KEEPS the `task_active` claim — the session stays locked (no new run) until an operator resumes it to a