@sema-agent/server 7.131.0 → 7.133.0

package/dist/plugins/local-session-window.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The local (File) leg's **bounded window** of one session — the reader that loads `[floor .. leaf]` instead of the whole tree
+ * (today: the session view, `audit.ts#buildSessionAuditLocal`). The twin of `TiDBSessionStorage.wake` / `PgSessionStorage.wake`.
+ *
+ * ## One rule: the view reads what the run reads
+ * A run on this backend wakes the **whole tree** (`LocalSessionStore.acquire` → core `FileSessionRepo.open`): core resolves the
+ * log's leaf and the engine walks the branch from that leaf to the root. A window shows the same thing only when it is cut **from
+ * that branch**, keeps **that leaf**, and carries the reading below its floor — the halves of core's bounded-storage contract:
+ *  · the window = core's `boundedTail` over the **branch path** (root → the run's leaf), not over the log in file order. The log
+ *    also holds abandoned branches (a resumeAt moves the leaf in place): cut in file order, the floor can come from a compaction
+ *    the branch no longer contains — the view then reads a context the run does not (a rewind inside the kept tail), or cannot be
+ *    built at all (a rewind past the last compaction: the branch's parent lies below the cut);
+ *  · the leaf = the one core resolved over the whole log, handed to the window as is (a window that re-resolved its leaf from its
+ *    own entries would read a leaf entry on the branch a second time and land on an entry it does not hold);
+ *  · below the floor = `getEpochAnchor`, the one reading every windowed storage shares ({@link scanEpochAnchor}), paged over the
+ *    branch below the floor — so the record the engine reads is the one the run's walk reaches.
+ * Read-only: the log is read once (`exportEntries`, pure), no append log is opened, and the window refuses writes.
+ *
+ * ## Cost: one linear walk
+ * The branch is the `parentId` chain from the leaf — the chain core's `getPathToRoot` follows, with the same stop rule (an entry
+ * without a parent ends it; a parent the log does not hold is `invalid_session`). It is walked here once, in linear time: core
+ * 7.52.0 builds its path with `unshift` (quadratic in the branch length — seconds on a long session, on the event loop), and the
+ * view must cost a window read, not a whole-branch walk. Every later read of the window goes through core's own walk, bounded by
+ * the floor.
+ */
+import { BaseSessionStorage } from "@sema-agent/core";
+export declare class LocalSessionWindow extends BaseSessionStorage {
+    /** The branch below the floor, root first (empty when the window is the whole branch). */
+    private readonly below;
+    private constructor();
+    appendEntry(): Promise<void>;
+    setLeafId(): Promise<void>;
+    /** `SessionStorage.getEpochAnchor?()` — the nearest carrier on the branch below the floor, as stored ({@link scanEpochAnchor}).
+     *  A row's `seq` is its position on the branch; the whole branch is in memory, so one page holds every row. */
+    getEpochAnchor(): Promise<unknown>;
+    /** Wake the window of `sessionId` under the local data root `root`; `null` if there is no such session. */
+    static wake(root: string, sessionId: string): Promise<LocalSessionWindow | null>;
+}
+//# sourceMappingURL=local-session-window.d.ts.map

package/dist/plugins/local-session-window.js

@@ -0,0 +1,54 @@
+import { BaseSessionStorage, InMemorySessionStorage, SessionError, boundedTail } from "@sema-agent/core";
+import { createLocalSessionRepo } from "./local-session-store.js";
+import { scanEpochAnchor } from "./session-epoch-anchor.js";
+export class LocalSessionWindow extends BaseSessionStorage {
+    below;
+    constructor(metadata, window, leafId, floorEntryId, below) {
+        super(metadata, window, leafId, { floorEntryId });
+        this.below = below;
+    }
+    async appendEntry() {
+        throw new SessionError("storage", "LocalSessionWindow is a read-only view of a session — write through the session store");
+    }
+    async setLeafId() {
+        throw new SessionError("storage", "LocalSessionWindow is a read-only view of a session — write through the session store");
+    }
+    async getEpochAnchor() {
+        return scanEpochAnchor(this.below.length, async (beforeSeq) => this.below.slice(0, beforeSeq).map((entry, seq) => ({ seq, entry })).reverse(), (row) => row.entry);
+    }
+    static async wake(root, sessionId) {
+        const repo = createLocalSessionRepo(root);
+        let log;
+        try {
+            log = await repo.exportEntries(sessionId);
+        }
+        catch (e) {
+            if (e.code === "not_found")
+                return null;
+            throw e;
+        }
+        const metadata = (await repo.list()).find((m) => m.id === sessionId) ?? { id: sessionId, createdAt: new Date().toISOString() };
+        const whole = new InMemorySessionStorage({ entries: log });
+        const leafId = await whole.getLeafId();
+        const branch = await branchOf(whole, leafId, log.length);
+        const { tail, floorEntryId } = boundedTail(branch);
+        return new LocalSessionWindow(metadata, tail, leafId, floorEntryId, branch.slice(0, branch.length - tail.length));
+    }
+}
+async function branchOf(whole, leafId, logLength) {
+    const fromLeaf = [];
+    let current = leafId === null ? undefined : await whole.getEntry(leafId);
+    while (current) {
+        fromLeaf.push(current);
+        if (!current.parentId)
+            break;
+        if (fromLeaf.length > logLength)
+            throw new SessionError("invalid_session", `Entry ${current.id} is on a parent cycle`);
+        const parent = await whole.getEntry(current.parentId);
+        if (!parent)
+            throw new SessionError("invalid_session", `Entry ${current.parentId} not found`);
+        current = parent;
+    }
+    return fromLeaf.reverse();
+}
+//# sourceMappingURL=local-session-window.js.map

package/dist/plugins/mailbox-recipient-lifecycle.d.ts

@@ -66,8 +66,9 @@ export interface MailboxRecipientLifecycle {
      * **只打标**——不删消息、不动租约、不碰盒行的高水位(理由 = core T2 试剂盒的两格副作用判据,见模块头)。
      * 幂等(重复 retire 只更新时刻/名字)。
      *
-     * @returns 是否真的落了一张耐久墓碑。`false` = 本后端没有预删除态,箱已被直接 `drop`
-     *          (拒的方向不变,退化的只有拒绝措辞与「正在删除中」那一行的可见性)。
+     * @returns 是否真的落了一张耐久墓碑。`false` 有两种,都是「没落」:① 本后端没有预删除态,箱已被直接 `drop`
+     *          (拒的方向不变,退化的只有拒绝措辞与「正在删除中」那一行的可见性);② 这只键收件箱的键判官不收(SQL 两孪生:没有箱可打标,
+     *          这只键的 `append` 本来就以判官那一句拒,不带墓碑码)。
      */
     retireRecipient(scope: string, handle: string, at: number, label?: string): Promise<boolean>;
     /** 本 scope 下句柄以 `handlePrefix` 开头的墓碑。无预删除态的后端恒返回空。 */

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

@@ -1,49 +1,3 @@
-/**
- * MailboxStore SQL twins([ref] S3c server pg 半场,[ref] 提货单①)——core teammate 信箱
- * (SendMessage 链)的 TiDB/PG 双方言实现。挂载缝 = S3c 行为车的 `RunnerDeps.mailboxStore`(core
- * 命名预告,[ref]§三);本文件先就绪 store 半场,行为车到货接线。
- *
- * 语义真源 = core `InMemoryMailboxStore`(dist/core/mailbox-store.js)+ [ref] 定谳(core 1.372
- * 终版文本,conformance 无两可):
- *  1. **同主重 claim = 续期 + 纳新**(crash-retry 正形):活 lease 只挡**别的** owner;同 owner 任意
- *     时刻重 claim 重设 TTL 并拿到当前全部未 ack 消息(maxSeq 随最新行走)。
- *  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 围栏**(MB1,core 1.452 起;原「无守卫、信任 claim 赢者链」已被推翻):当前持租者才删
- *     `seq <= upToSeq` 的行;lease 的 `maxSeq <= upToSeq` 时顺带清 lease(全量 ack = 释放)。**围栏的判决报出来**
- *     (core 7.30.0 #1036,S-616):放行 ⇒ `{ acked: true }`(删 0 行也是 true —— 契约是「围栏放行」不是「删了几行」),
- *     盒不在 / 无人持租 / 非持租者 ⇒ `{ acked: false }`;逐格与 core `InMemoryMailboxStore.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` **清箱**(删消息 + 清租约,
- *     盒行/高水位保留,见定谳 2 的 [ref] 半句);空盒(有 box 行无消息)不清(InMemory 同形——`newest ===
- *     undefined` 不动)。
- *
- * 键列 = 字节等价(TiDB VARBINARY / PG COLLATE "C",roster F2 案):scope/handle/lease_owner 的
- * `=` 必须纯字节——PAD SPACE 近撞不得穿隔离/抢别人 lease。PG unstorable bytes([ref] 三层定谳):
- * `content` 是消息**内容面**(收件人将读到、注入对话)→ 与 PG 转录 payload 同族 lossy(pgSanitizeText,
- * U+FFFD 标记,内容不失行);**身份键 scope/handle/owner/from 拒绝式**(pgHasUnstorable →
- * PgUnstorableError fail-loud——attribution/路由键清洗形变 = 行与查询键错位,协议数据同向)。TiDB
- * 侧 LONGTEXT/VARBINARY verbatim(replay 面定谳)。
- *
- * 并发正确性(InMemory 单进程无此象限、SQL 多副本有;发车复审 F2/F3/F4 批):
- *  - **锁序统一「盒行 → 消息行」**(append/claim/ack/drop/reap 五面同序)——ack/drop/reap 原为
- *    消息先行,与 claim 的盒先行构成 ABBA 死锁形;统一后同盒并发只在盒行锁上排队。
- *  - drop/reap 先删/锁**盒行**再动消息:反序留「消息已删、盒行未删」窗,并发 append 完整穿过后
- *    盒重建会撞存活的孤儿消息行(PK 冲突→此后 append 永久失败)。
- *  - reap 候删 = 事务外粗筛 + 事务内**逐盒锁定重验**(当前读 newest):窗内新到的消息救活盒,
- *    绝不连带删信;盒行已被并发 drop = 跳过不计。
- *  - append 的 ensure 与 FOR UPDATE 之间被并发 drop 提交 = 同事务内重建一次(语义 = drop 后重建,
- *    seq 从 1)。建盒动词 = 形 A(S-127)`ON DUPLICATE KEY UPDATE <pk> = <pk>`:重复键取 X 锁,与随后的
- *    `FOR UPDATE` **同锁模式**(`INSERT IGNORE` 取 S 再升 X = InnoDB 上的并发死锁形,B-013)。
- *  - 键长 > 190 字节写入即拒(fail-loud):截断键与全长查询参数字节比对恒 miss(分配读空行崩/隔离键
- *    错位)。守卫在**语句之前**,与建行动词无关 —— 换成 ON DUPLICATE 之后超长键由引擎直接报错(严格
- *    模式下 IGNORE 会把它降级成静默截断),方向=更响亮,守卫依旧是第一道。
- */
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
 import type { MailboxAckResult, MailboxAppendMessage, MailboxLease, MailboxStore } from "@sema-agent/core";
@@ -57,6 +11,36 @@ export declare const MAILBOX_MSG_TABLE = "mailbox_message";
  *  —— `mailbox` 行是**盒**事实(next_seq / lease),墓碑是**收件人**事实,两者的生命周期本来就不同
  *  (`drop` 同时终结两者 —— 墓碑随箱亡,理由全文见 `mailbox-recipient-lifecycle.ts` 模块头)。 */
 export declare const MAILBOX_TOMBSTONE_TABLE = "mailbox_tombstone";
+/**
+ * 身份键(`scope` / `handle` / lease `owner`)的 UTF-8 字节上界 = 键列宽(TiDB `VARBINARY(190)`;PG 列按字符,本判官在两方言上都按字节拒)。
+ */
+export declare const MAILBOX_KEY_MAX_UTF8_BYTES = 190;
+/**
+ * 🔴 **「这只串能当收件箱的身份键吗」的唯一判官**(三只键列:`scope` / `handle` / lease `owner`;两方言同一只、同一句拒因)。一只串当得了键 ⇔
+ *  ⓪ `scope` 非空(引擎 InMemory 同一句「without a scope」:没有箱址;handle / owner 空照引擎参照形放行);
+ *  ① **良构 Unicode**(没有孤立代理):两只驱动按 UTF-8 送库时都把孤立代理换成 U+FFFD 的三字节 ⇒ 库里它与另一只键同键(TiDB 写进别人的箱、续不了自己的租约;
+ *     PG 另把它当不可存字节);
+ *  ② **不含控制字符**(C0 含 NUL、DEL):键要能逐字节寻址([ref] 试剂盒:NUL 键两后端一致拒、不得串箱);
+ *  ③ **UTF-8 字节不超过键列宽**:截断的键与全长查询参数逐字节比对恒 miss(seq 分配读空行崩 / 隔离键错位)。
+ * 答第一道不过的拒因,都过 ⇒ `undefined`。**判官拒的键没有箱**,两方言每一只入口在语句之前问它,一条律两种答法:建状态的两面(`append` 的 scope 与 handle、
+ * `claimLease` 写进租约的 owner)拒就抛这一句({@link assertMailboxKey});其余每一面(读 / 清 / 打标 / 放租 / 确认)照「箱不在」答、不把键送进驱动({@link keyless}):
+ * `peekCount` 0、`claimLease` null、`ack` `{ acked: false }`、`releaseLease` / `drop` 无事、`reap` 0(候选扫描交回的句柄同判:判官拒的跳过、零语句)、
+ * `retireRecipient` false(没落墓碑 —— 没有箱可打标;这只键的 append 本来就以判官那一句拒)、`listRetiredRecipients` 空。跨主体投递门在扣投递额度之前问它
+ * (收件人 scope 就是这只键,`org-delivery-gate.ts`)。库里已有的这种键(升级前写下的)由一次性迁移 M27 删掉,判据是同一只判官({@link storedMailboxKeyless})。没有第二道键判。
+ */
+export declare function mailboxKeyProblem(what: MailboxKeyColumn, v: string): string | undefined;
+/** 收件箱的三只键列(判官的 `what`;闭集)。 */
+export type MailboxKeyColumn = "scope" | "handle" | "owner";
+/** 库里读回的一对键列判官拒不拒(与入口同一只判官;字节先无损读成串,读不成 = 不良构)。`reap` 的候选句柄与一次性迁移 M27 都按它判。 */
+export declare function storedMailboxKeyless(scopeKey: unknown, handle: unknown): boolean;
+/**
+ * 收件箱表族:三张表的键都是 `(scope_key, handle)`。次序 = 锁序(盒行 → 消息行 → 墓碑行;盒行先删的理由见 `drop`)。
+ * 「丢掉一只箱」= 按这个次序逐表按键删 —— `drop` 与一次性迁移 M27 是同一组语句({@link mailboxKeyDeleteSql})。
+ */
+export declare const MAILBOX_KEYED_TABLES: readonly ["mailbox", "mailbox_message", "mailbox_tombstone"];
+export type MailboxKeyedTable = (typeof MAILBOX_KEYED_TABLES)[number];
+/** 按键删收件箱表族的一张表(两方言;参数 = [scope_key, handle])。 */
+export declare function mailboxKeyDeleteSql(dialect: "tidb" | "pg", table: MailboxKeyedTable): string;
 /** 店侧日志座(可选;boot 注入 `Logger`)。7.58.0 合并重扫 [medium]:坏行的 fail-closed 抛必须**响亮**——core 唯一的
  *  claimLease 调用方(peer-session-drain)吞掉该错,店不记这一笔就成了「静默永久卡箱」。抛之前记
  *  `mailbox_message_column_corrupt`(scope/handle/seq/column/code),运维按 seq 修行。
@@ -106,8 +90,6 @@ export declare class PgMailboxStore implements MailboxStore, MailboxRecipientLif
     readonly crossProcessSafe = true;
     constructor(pool: PgPool, logger?: MailboxStoreLogger | undefined);
     private tx;
-    /** 身份键拒绝式([ref] 协议纪律):scope/handle/owner/from 清洗形变 = 路由/attribution 错位。 */
-    private assertIdentity;
     append(scope: string, handle: string, msg: MailboxAppendMessage): Promise<number>;
     claimLease(scope: string, handle: string, owner: string, ttlMs: number, now?: number): Promise<MailboxLease | null>;
     ack(scope: string, handle: string, owner: string, upToSeq: number): Promise<MailboxAckResult>;

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

@@ -1,5 +1,7 @@
+import { isUtf8 } from "node:buffer";
 import { MAILBOX_INVALID_PEER_META_CODE, MAILBOX_TOMBSTONED_RECIPIENT_CODE, MailboxStoreError, readMailboxPeerMeta } from "@sema-agent/core";
 import { pgHasUnstorable, pgSanitizeText, PgUnstorableError } from "./pg-safe-json.js";
+import { isWellFormedUnicode } from "../principal-jwt.js";
 import { ensureIndexes } from "./ensure-index.js";
 import { escapeLike } from "./sql-escape.js";
 import { decodeNullableJsonColumn, foldJsonColumn, isJsonColumnBodyProblem, jsonColumnText, readStringArrayColumn } from "./sql-json-column.js";
@@ -19,20 +21,38 @@ function rowToTombstone(r) {
     const label = r.label === null || r.label === undefined ? undefined : bufToStr(r.label);
     return { handle: bufToStr(r.handle), retiredAt: Number(r.retired_at_ms), ...(label !== undefined ? { label } : {}) };
 }
-function assertScope(scope) {
-    if (scope === undefined || scope === "") {
-        throw new Error("MailboxStore.append: refusing a message without a scope");
-    }
+export const MAILBOX_KEY_MAX_UTF8_BYTES = 190;
+export function mailboxKeyProblem(what, v) {
+    if (what === "scope" && (v === undefined || v === ""))
+        return "MailboxStore: refusing a message without a scope (an empty scope addresses no box)";
+    if (!isWellFormedUnicode(v))
+        return `MailboxStore: ${what} is not well-formed Unicode (lone surrogate) (refusing — the driver would store it as U+FFFD and alias a different key)`;
+    if ([...v].some((ch) => ch.charCodeAt(0) < 0x20 || ch.charCodeAt(0) === 0x7f))
+        return `MailboxStore: ${what} contains control characters (refusing — identity keys must be byte-exact addressable)`;
+    if (Buffer.byteLength(v, "utf8") > MAILBOX_KEY_MAX_UTF8_BYTES) {
+        return `MailboxStore: ${what} exceeds the ${MAILBOX_KEY_MAX_UTF8_BYTES}-byte key column (refusing — a truncated key would desync from its byte-exact lookups)`;
+    }
+    return undefined;
 }
-function assertIdentityChars(what, v) {
-    if ([...v].some((ch) => ch.charCodeAt(0) < 0x20 || ch.charCodeAt(0) === 0x7f)) {
-        throw new Error(`MailboxStore: ${what} contains control characters (refusing — identity keys must be byte-exact addressable)`);
-    }
+function assertMailboxKey(what, v) {
+    const problem = mailboxKeyProblem(what, v);
+    if (problem !== undefined)
+        throw new Error(problem);
 }
-function assertKeyBytes(what, v) {
-    if (Buffer.byteLength(v, "utf8") > 190) {
-        throw new Error(`MailboxStore: ${what} exceeds the 190-byte key column (refusing — a truncated key would desync from its byte-exact lookups)`);
-    }
+const keyless = (scope, handle, owner) => mailboxKeyProblem("scope", scope) !== undefined || mailboxKeyProblem("handle", handle) !== undefined || (owner !== undefined && mailboxKeyProblem("owner", owner) !== undefined);
+function storedKeyText(v) {
+    if (!Buffer.isBuffer(v))
+        return String(v);
+    return isUtf8(v) ? v.toString("utf8") : undefined;
+}
+export function storedMailboxKeyless(scopeKey, handle) {
+    const scope = storedKeyText(scopeKey);
+    const h = storedKeyText(handle);
+    return scope === undefined || h === undefined || keyless(scope, h);
+}
+export const MAILBOX_KEYED_TABLES = [MAILBOX_TABLE, MAILBOX_MSG_TABLE, MAILBOX_TOMBSTONE_TABLE];
+export function mailboxKeyDeleteSql(dialect, table) {
+    return dialect === "tidb" ? `DELETE FROM ${table} WHERE scope_key = ? AND handle = ?` : `DELETE FROM ${table} WHERE scope_key = $1 AND handle = $2`;
 }
 function bufToStr(v) {
     return Buffer.isBuffer(v) ? v.toString("utf8") : String(v);
@@ -220,11 +240,8 @@ export class TiDBMailboxStore {
         }
     }
     async append(scope, handle, msg) {
-        assertScope(scope);
-        assertIdentityChars("scope", scope);
-        assertIdentityChars("handle", handle);
-        assertKeyBytes("scope", scope);
-        assertKeyBytes("handle", handle);
+        assertMailboxKey("scope", scope);
+        assertMailboxKey("handle", handle);
         const hopChain = encodeHopChain(msg.hopChain);
         const peerMeta = encodePeerMeta(msg.peerMeta);
         return this.tx(async (c) => {
@@ -244,6 +261,9 @@ export class TiDBMailboxStore {
         });
     }
     async claimLease(scope, handle, owner, ttlMs, now = Date.now()) {
+        assertMailboxKey("owner", owner);
+        if (keyless(scope, handle))
+            return null;
         return this.tx(async (c) => {
             const [boxes] = (await c.query(`SELECT lease_owner, lease_expires_at_ms FROM ${MAILBOX_TABLE} WHERE scope_key = ? AND handle = ? FOR UPDATE`, [scope, handle]));
             if (boxes.length === 0)
@@ -263,6 +283,8 @@ export class TiDBMailboxStore {
         });
     }
     async ack(scope, handle, owner, upToSeq) {
+        if (keyless(scope, handle, owner))
+            return { acked: false };
         return this.tx(async (c) => {
             const [rows] = (await c.query(`SELECT lease_owner FROM ${MAILBOX_TABLE} WHERE scope_key = ? AND handle = ? FOR UPDATE`, [scope, handle]));
             if (rows.length === 0 || rows[0].lease_owner == null || bufToStr(rows[0].lease_owner) !== owner)
@@ -274,28 +296,33 @@ export class TiDBMailboxStore {
         });
     }
     async releaseLease(scope, handle, owner) {
+        if (keyless(scope, handle, owner))
+            return;
         await this.pool.query(`UPDATE ${MAILBOX_TABLE} SET lease_owner = NULL, lease_expires_at_ms = NULL, lease_max_seq = NULL
        WHERE scope_key = ? AND handle = ? AND lease_owner = ?`, [scope, handle, owner]);
     }
     async peekCount(scope, handle) {
+        if (keyless(scope, handle))
+            return 0;
         const [rows] = (await this.pool.query(`SELECT COUNT(*) AS n FROM ${MAILBOX_MSG_TABLE} WHERE scope_key = ? AND handle = ?`, [scope, handle]));
         return Number(rows[0].n);
     }
     async drop(scope, handle) {
+        if (keyless(scope, handle))
+            return;
         await this.tx(async (c) => {
-            await c.query(`DELETE FROM ${MAILBOX_TABLE} WHERE scope_key = ? AND handle = ?`, [scope, handle]);
-            await c.query(`DELETE FROM ${MAILBOX_MSG_TABLE} WHERE scope_key = ? AND handle = ?`, [scope, handle]);
-            await c.query(`DELETE FROM ${MAILBOX_TOMBSTONE_TABLE} WHERE scope_key = ? AND handle = ?`, [scope, handle]);
+            for (const table of MAILBOX_KEYED_TABLES)
+                await c.query(mailboxKeyDeleteSql("tidb", table), [scope, handle]);
         });
     }
     async reap(scope, now, opts) {
-        if (opts?.maxAgeMs === undefined)
+        if (opts?.maxAgeMs === undefined || mailboxKeyProblem("scope", scope) !== undefined)
             return 0;
         const cutoff = now - opts.maxAgeMs;
         const [cands] = (await this.pool.query(`SELECT handle FROM ${MAILBOX_MSG_TABLE} WHERE scope_key = ? GROUP BY handle HAVING MAX(sent_at_ms) < ?`, [scope, cutoff]));
-        if (cands.length === 0)
+        const handles = cands.filter((r) => !storedMailboxKeyless(scope, r.handle)).map((r) => bufToStr(r.handle));
+        if (handles.length === 0)
             return 0;
-        const handles = cands.map((r) => bufToStr(r.handle));
         return this.tx(async (c) => {
             let dropped = 0;
             for (const h of handles) {
@@ -313,11 +340,8 @@ export class TiDBMailboxStore {
         });
     }
     async retireRecipient(scope, handle, at, label) {
-        assertScope(scope);
-        assertIdentityChars("scope", scope);
-        assertIdentityChars("handle", handle);
-        assertKeyBytes("scope", scope);
-        assertKeyBytes("handle", handle);
+        if (keyless(scope, handle))
+            return false;
         await this.tx(async (c) => {
             await c.query(`INSERT INTO ${MAILBOX_TABLE} (scope_key, handle, scope, next_seq) VALUES (?, ?, ?, 1) ON DUPLICATE KEY UPDATE scope_key = scope_key`, [scope, handle, scope]);
             await c.query(`SELECT next_seq FROM ${MAILBOX_TABLE} WHERE scope_key = ? AND handle = ? FOR UPDATE`, [scope, handle]);
@@ -327,6 +351,8 @@ export class TiDBMailboxStore {
         return true;
     }
     async listRetiredRecipients(scope, handlePrefix) {
+        if (mailboxKeyProblem("scope", scope) !== undefined)
+            return [];
         const [rows] = await this.pool.query(`SELECT handle, retired_at_ms, label FROM ${MAILBOX_TOMBSTONE_TABLE} WHERE scope_key = ? AND handle LIKE ? ESCAPE '\\\\'`, [scope, `${escapeLike(handlePrefix)}%`]);
         return rows.map(rowToTombstone);
     }
@@ -355,18 +381,12 @@ export class PgMailboxStore {
             c.release();
         }
     }
-    assertIdentity(what, v) {
-        if (v !== undefined && pgHasUnstorable(v))
-            throw new PgUnstorableError(`mailbox ${what}`);
-    }
     async append(scope, handle, msg) {
-        assertScope(scope);
-        this.assertIdentity("scope", scope);
-        this.assertIdentity("handle", handle);
-        this.assertIdentity("from", msg.from);
+        assertMailboxKey("scope", scope);
+        assertMailboxKey("handle", handle);
+        if (msg.from !== undefined && pgHasUnstorable(msg.from))
+            throw new PgUnstorableError("mailbox from");
         const content = pgSanitizeText(msg.content);
-        assertKeyBytes("scope", scope);
-        assertKeyBytes("handle", handle);
         const hopChain = encodeHopChain(msg.hopChain);
         const peerMeta = encodePeerMeta(msg.peerMeta);
         return this.tx(async (c) => {
@@ -394,7 +414,9 @@ export class PgMailboxStore {
         });
     }
     async claimLease(scope, handle, owner, ttlMs, now = Date.now()) {
-        this.assertIdentity("owner", owner);
+        assertMailboxKey("owner", owner);
+        if (keyless(scope, handle))
+            return null;
         return this.tx(async (c) => {
             const { rows: boxes } = await c.query(`SELECT lease_owner, lease_expires_at_ms FROM ${MAILBOX_TABLE} WHERE scope_key = $1 AND handle = $2 FOR UPDATE`, [scope, handle]);
             if (boxes.length === 0)
@@ -411,6 +433,8 @@ export class PgMailboxStore {
         });
     }
     async ack(scope, handle, owner, upToSeq) {
+        if (keyless(scope, handle, owner))
+            return { acked: false };
         return this.tx(async (c) => {
             const r = (await c.query(`SELECT lease_owner FROM ${MAILBOX_TABLE} WHERE scope_key = $1 AND handle = $2 FOR UPDATE`, [scope, handle]));
             if (r.rows.length === 0 || r.rows[0].lease_owner == null || bufToStr(r.rows[0].lease_owner) !== owner)
@@ -422,31 +446,33 @@ export class PgMailboxStore {
         });
     }
     async releaseLease(scope, handle, owner) {
-        this.assertIdentity("owner", owner);
+        if (keyless(scope, handle, owner))
+            return;
         await this.pool.query(`UPDATE ${MAILBOX_TABLE} SET lease_owner = NULL, lease_expires_at_ms = NULL, lease_max_seq = NULL
        WHERE scope_key = $1 AND handle = $2 AND lease_owner = $3`, [scope, handle, owner]);
     }
     async peekCount(scope, handle) {
-        if (pgHasUnstorable(scope) || pgHasUnstorable(handle))
+        if (keyless(scope, handle))
             return 0;
         const { rows } = await this.pool.query(`SELECT COUNT(*) AS n FROM ${MAILBOX_MSG_TABLE} WHERE scope_key = $1 AND handle = $2`, [scope, handle]);
         return Number(rows[0].n);
     }
     async drop(scope, handle) {
+        if (keyless(scope, handle))
+            return;
         await this.tx(async (c) => {
-            await c.query(`DELETE FROM ${MAILBOX_TABLE} WHERE scope_key = $1 AND handle = $2`, [scope, handle]);
-            await c.query(`DELETE FROM ${MAILBOX_MSG_TABLE} WHERE scope_key = $1 AND handle = $2`, [scope, handle]);
-            await c.query(`DELETE FROM ${MAILBOX_TOMBSTONE_TABLE} WHERE scope_key = $1 AND handle = $2`, [scope, handle]);
+            for (const table of MAILBOX_KEYED_TABLES)
+                await c.query(mailboxKeyDeleteSql("pg", table), [scope, handle]);
         });
     }
     async reap(scope, now, opts) {
-        if (opts?.maxAgeMs === undefined)
+        if (opts?.maxAgeMs === undefined || mailboxKeyProblem("scope", scope) !== undefined)
             return 0;
         const cutoff = now - opts.maxAgeMs;
         const { rows: cands } = await this.pool.query(`SELECT handle FROM ${MAILBOX_MSG_TABLE} WHERE scope_key = $1 GROUP BY handle HAVING MAX(sent_at_ms) < $2`, [scope, cutoff]);
-        if (cands.length === 0)
+        const handles = cands.filter((r) => !storedMailboxKeyless(scope, r.handle)).map((r) => String(r.handle));
+        if (handles.length === 0)
             return 0;
-        const handles = cands.map((r) => String(r.handle));
         return this.tx(async (c) => {
             let dropped = 0;
             for (const h of handles) {
@@ -464,11 +490,8 @@ export class PgMailboxStore {
         });
     }
     async retireRecipient(scope, handle, at, label) {
-        assertScope(scope);
-        this.assertIdentity("scope", scope);
-        this.assertIdentity("handle", handle);
-        assertKeyBytes("scope", scope);
-        assertKeyBytes("handle", handle);
+        if (keyless(scope, handle))
+            return false;
         const bounded = boundedLabel(label);
         const stored = bounded === null ? null : pgSanitizeText(bounded);
         await this.tx(async (c) => {
@@ -480,6 +503,8 @@ export class PgMailboxStore {
         return true;
     }
     async listRetiredRecipients(scope, handlePrefix) {
+        if (mailboxKeyProblem("scope", scope) !== undefined)
+            return [];
         const { rows } = await this.pool.query(`SELECT handle, retired_at_ms, label FROM ${MAILBOX_TOMBSTONE_TABLE} WHERE scope_key = $1 AND handle LIKE $2 ESCAPE '\\'`, [scope, `${escapeLike(handlePrefix)}%`]);
         return rows.map(rowToTombstone);
     }

package/dist/plugins/memory-embedder-fingerprint.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { PG_MEMORY_ENGINE_TABLES } from "./memory-engine-pg.js";
 import { createZodColumnReader, decodeJsonColumn, jsonColumnText, SqlJsonColumnError } from "./sql-json-column.js";
+import { echoCallerText } from "../caller-text-echo.js";
 export const PG_MEMORY_ENGINE_META_TABLE = "agent_memory_engine_meta";
 export const EMBEDDER_IDENTITY_META_KEY = "embedder_identity";
 export const CAS_MAX_ROUNDS = 3;
@@ -22,7 +23,7 @@ function parseStoredText(text) {
     catch (err) {
         if (!(err instanceof SqlJsonColumnError))
             throw err;
-        return { kind: "unreadable", raw: `${text.slice(0, 160)} [${err.problem}: ${err.message.slice(0, 120)}]` };
+        return { kind: "unreadable", raw: `${echoCallerText(text, { maxChars: 160 })} [${err.problem}: ${echoCallerText(err.message, { maxChars: 120 })}]` };
     }
 }
 async function readStored(query) {

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

@@ -1,6 +1,6 @@
 import { type UsageRow } from "../usage-analytics.js";
 import type { TaskStatus } from "@sema-agent/core";
-import { type CreateRunOutcome, type NewRunMeta, type RunIdemBinding, type RunRecord, type SessionSummary, type RunEvent, type PersistedTaskResult, type LatestRunRef } from "./store-contracts.js";
+import { type FenceLanded, type InProcessClaimFence, type CreateRunOutcome, type NewRunMeta, type RunIdemBinding, type RunListQuery, type RunRecord, type SessionSummary, type RunEvent, type PersistedTaskResult, type LatestRunRef } from "./store-contracts.js";
 import type { LedgerEventType } from "../trace/ledger-events.js";
 import { type SpaceCommitClaim, type SpaceCommitReading, type SpaceCommitState } from "../workspace-space-commit.js";
 /**
@@ -22,7 +22,7 @@ export interface RunStoreCheckpointProbe {
     hasPending(sessionId: string): Promise<boolean>;
     hasExpired(sessionId: string): Promise<boolean>;
 }
-export declare class MemoryRunStore {
+export declare class MemoryRunStore implements InProcessClaimFence {
     private readonly runs;
     /** sessionId → taskId — the single-active-run claim (the `task_active` table). */
     private readonly active;
@@ -82,19 +82,11 @@ export declare class MemoryRunStore {
      *  [ref](codex R1 [medium]):认领 = 接管 `instanceId`(= 当前持有副本;SQL 孪生同注)。CAS 输不改。 */
     markResuming(taskId: string, instanceId: string): Promise<boolean>;
     getActiveTaskId(sessionId: string): Promise<string | undefined>;
+    /** 认领当写栅栏用(契约 = `store-contracts.ts` 的 `InProcessClaimFence`):判、刷新活性与 `write` 是同一个同步段。 */
+    whileHoldingClaim(sessionId: string, taskId: string, write: () => FenceLanded): boolean;
     getRun(taskId: string): Promise<RunRecord | undefined>;
     /** Runs newest-first, keyset on (createdAt, taskId) DESC; optional exact-match filters (owner is exact, like the SQL). */
-    listRuns(opts: {
-        status?: string;
-        jobId?: string;
-        source?: string;
-        owner?: string;
-        cursor?: {
-            createdAt: string;
-            taskId: string;
-        };
-        limit: number;
-    }): Promise<RunRecord[]>;
+    listRuns(opts: RunListQuery): Promise<RunRecord[]>;
     /**
      * S-297 —— 这个会话**最近一条腿**的窄指针({@link SqlRunStore.latestRunForSession} 的孪生:同一个排序口径
      *  `createdAt DESC, taskId DESC`,与本店 {@link MemoryRunStore.listSessions} 挑 `rn=1` 那一行的比较器逐字同一份)。

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

@@ -231,6 +231,14 @@ export class MemoryRunStore {
     async getActiveTaskId(sessionId) {
         return this.active.get(sessionId);
     }
+    whileHoldingClaim(sessionId, taskId, write) {
+        const r = this.runs.get(taskId);
+        if (this.active.get(sessionId) !== taskId || r === undefined || r.status !== "running")
+            return false;
+        r.updatedAt = new Date();
+        write();
+        return true;
+    }
     async getRun(taskId) {
         const r = this.runs.get(taskId);
         return r ? this.toRecord(r) : undefined;