@sema-agent/server 7.147.0 → 7.148.0

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

@@ -52,8 +52,9 @@ export declare class LocalSessionWindow extends BaseSessionStorage {
     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. */
+    /** `SessionStorage.getEpochAnchor?()` — the nearest carrier on the branch below the floor, as stored ({@link scanEpochAnchor}: the floor's
+     *  parent chain, the one walk every windowed storage shares). A row's `seq` is its position on the branch; the whole branch is in memory,
+     *  so one page holds every row (every one of them on the walk). */
     getEpochAnchor(): Promise<unknown>;
     /** Wake the window of `sessionId` from the local session store's rows; `null` if there is no such session. */
     static wake(rows: LocalSessionRows, sessionId: string): Promise<LocalSessionWindow | null>;

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

@@ -1,5 +1,5 @@
 import { BaseSessionStorage, InMemorySessionStorage, SessionError, boundedTail } from "@sema-agent/core";
-import { scanEpochAnchor } from "./session-epoch-anchor.js";
+import { epochFloorOf, scanEpochAnchor } from "./session-epoch-anchor.js";
 export class LocalSessionWindow extends BaseSessionStorage {
     below;
     constructor(metadata, window, leafId, floorEntryId, below) {
@@ -13,7 +13,8 @@ export class LocalSessionWindow extends BaseSessionStorage {
         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);
+        const floorId = this.getFloorId();
+        return scanEpochAnchor(epochFloorOf(this.below.length, floorId === null ? undefined : await this.getEntry(floorId)), async (beforeSeq) => this.below.slice(0, beforeSeq).map((entry, seq) => ({ seq, id: entry.id, parentId: entry.parentId ?? null, type: entry.type, entry })).reverse(), (row) => row.entry);
     }
     static async wake(rows, sessionId) {
         const log = await rows.exportEntries(sessionId);

package/dist/plugins/local-sidecar-quarantine.js

@@ -1,3 +1,4 @@
+import { writeLogText } from "../observability/logger.js";
 import { renameSync } from "node:fs";
 export function quarantineUnreadableSidecar(path, what, reason) {
     const target = `${path}.corrupt-${Date.now()}-${process.pid}`;
@@ -5,11 +6,11 @@ export function quarantineUnreadableSidecar(path, what, reason) {
         renameSync(path, target);
     }
     catch (e) {
-        console.warn(`${what}: ${path} is unreadable (${reason}) and could NOT be quarantined (${e instanceof Error ? e.message : String(e)}) — ` +
+        writeLogText("stderr", `${what}: ${path} is unreadable (${reason}) and could NOT be quarantined (${e instanceof Error ? e.message : String(e)}) — ` +
             `the bytes are still at that path; a later write to it may replace them`);
         return undefined;
     }
-    console.warn(`${what}: ${path} is unreadable (${reason}) — quarantined at ${target} so the next write cannot replace it`);
+    writeLogText("stderr", `${what}: ${path} is unreadable (${reason}) — quarantined at ${target} so the next write cannot replace it`);
     return target;
 }
 //# sourceMappingURL=local-sidecar-quarantine.js.map

package/dist/plugins/local-task-attachment-store.d.ts

@@ -1,4 +1,5 @@
 import { type AttachmentStoreBindOutcome, type TaskAttachmentStore, type TaskAttachmentRecord } from "./task-attachment-store.js";
+import type { LocalSessionStore } from "./local-session-store.js";
 /** 附件店在数据根下的目录(构造器与一次性迁移 M39 的名册同读这一只)。 */
 export declare function attachmentStoreDirFor(rootDir: string): string;
 export declare class LocalTaskAttachmentStore implements TaskAttachmentStore {
@@ -7,7 +8,17 @@ export declare class LocalTaskAttachmentStore implements TaskAttachmentStore {
     private hydration;
     /** 变更串行段的尾(见 `serialized`):每只变更口排在上一只的落盘与合回之后。本店唯一一只。 */
     private mutationTail;
-    constructor(rootDir: string);
+    /**
+     * 客户端写计数口(同一数据根上的 local 会话店;提交出口撤回一只刚铸会话之前读这只计数,`session-birth.ts`):绑定在这只会话的根行锁里判、真绑上行时先 +1 再落盘。
+     * 缺席 = 本店的绑定不计数 —— 撤回就可能删掉一只已绑附件的会话,所以带会话店的装配必须交它(只测附件店的用例不交)。
+     */
+    private readonly clientWrites;
+    constructor(rootDir: string, opts?: {
+        readonly clientWrites?: Pick<LocalSessionStore, "withClientWrite">;
+    });
+    /** 一次性迁移 **M42 的 local 附件腿**(场景前缀的切换检查;窗口见 `plugins/one-time-migrations.ts` 登记表):属主以保留前缀开头的附件数。
+     *  附件可以先于任何会话 / run 上传(属主不经那两只店)⇒ 本店自己一处来源。水合那一读,零写;读不出的 meta 照水合同一条跳过臂。 */
+    scenarioPrefixOwnerRowsM42(): Promise<number>;
     private hydrate;
     /**
      * 本店**唯一**的变更串行段:凡改 `this.metas` 或删盘上行的口(put / bind / delete / deleteBySession / reapUnbound)把**整条操作**
@@ -23,10 +34,16 @@ export declare class LocalTaskAttachmentStore implements TaskAttachmentStore {
     getContent(owner: string, id: string): Promise<Uint8Array | null>;
     private persistMeta;
     bind(owner: string, ids: readonly string[], sessionId: string, boundAtMs: number): Promise<AttachmentStoreBindOutcome>;
+    /** {@link bind} 的串行段一形(`count` = 客户端写计数,真绑上行时在落盘之前调;缺 = 不计)。 */
+    private bindSerialized;
     listBySession(sessionId: string): Promise<TaskAttachmentRecord[]>;
     /** 删一行(meta + bytes + 内存索引)。只在 `serialized` 的操作体里调用。 */
     private removeRow;
     delete(owner: string, id: string): Promise<boolean>;
+    /** local 形一行一份字节(不跨行共享,行删即字节删,见 `removeRow`)⇒ 给不出「行已删、字节还在」的哈希:local 执行体回执里的附件哈希恒空,这一口无字节可放。 */
+    releaseBytes(_shas: readonly string[]): Promise<{
+        readonly failed: readonly string[];
+    }>;
     deleteBySession(sessionId: string): Promise<number>;
     reapUnbound(olderThanMs: number): Promise<number>;
 }

package/dist/plugins/local-task-attachment-store.js

@@ -1,3 +1,4 @@
+import { SCENARIO_SUBJECT_PREFIX } from "../owner-brands.js";
 import { promises as fsp } from "node:fs";
 import { join } from "node:path";
 import { ensureDir } from "@sema-agent/core";
@@ -14,8 +15,17 @@ export class LocalTaskAttachmentStore {
     metas;
     hydration;
     mutationTail = Promise.resolve();
-    constructor(rootDir) {
+    clientWrites;
+    constructor(rootDir, opts) {
         this.dir = attachmentStoreDirFor(rootDir);
+        this.clientWrites = opts?.clientWrites;
+    }
+    async scenarioPrefixOwnerRowsM42() {
+        let n = 0;
+        for (const meta of (await this.hydrate()).values())
+            if (meta.owner.startsWith(SCENARIO_SUBJECT_PREFIX))
+                n += 1;
+        return n;
     }
     hydrate() {
         this.hydration ??= (async () => {
@@ -77,6 +87,12 @@ export class LocalTaskAttachmentStore {
         await atomicWriteFileAsync(join(this.dir, `${m.id}.json`), JSON.stringify(m), { durability: "best-effort" });
     }
     bind(owner, ids, sessionId, boundAtMs) {
+        const gate = this.clientWrites;
+        if (gate === undefined)
+            return this.bindSerialized(owner, ids, sessionId, boundAtMs, undefined);
+        return gate.withClientWrite(sessionId, (count) => this.bindSerialized(owner, ids, sessionId, boundAtMs, count));
+    }
+    bindSerialized(owner, ids, sessionId, boundAtMs, count) {
         return this.serialized(async () => {
             const metas = await this.hydrate();
             const draft = new Map(metas);
@@ -86,6 +102,8 @@ export class LocalTaskAttachmentStore {
                     draft.set(id, { ...row });
             }
             const { outcome, claimed } = bindRowsInProcess(draft, owner, ids, sessionId, boundAtMs);
+            if (claimed.length > 0 && count !== undefined)
+                await count();
             const landed = [];
             try {
                 for (const m of claimed) {
@@ -121,6 +139,9 @@ export class LocalTaskAttachmentStore {
             return true;
         });
     }
+    async releaseBytes(_shas) {
+        return { failed: [] };
+    }
     deleteBySession(sessionId) {
         return this.serialized(async () => {
             const metas = await this.hydrate();

package/dist/plugins/memory-embedder.js

@@ -1,7 +1,11 @@
 import { joinRequestUrl } from "@sema-agent/core";
 import { z } from "zod";
-import { egressRedirectRefusal } from "../egress-redirect.js";
+import { EgressRedirectRefusedError, createEgressFetch } from "../egress-redirect.js";
 import { buildDisplaySafeRefusal, buildDisplaySafeUrl } from "../trace/redact.js";
+import { createLogger } from "../observability/logger.js";
+import { errorText } from "../observability/err-text.js";
+const MEMORY_EMBEDDER_HOOK_THREW = "memory_embedder_observability_hook_threw";
+const embedderLog = createLogger();
 const EmbeddingsResponse = z.object({
     data: z.array(z.object({ embedding: z.array(z.number()) })).min(1),
 });
@@ -28,7 +32,7 @@ function credentialsInQuery(endpoint) {
 export function createOpenAiCompatEmbedder(opts) {
     const url = embeddingsUrl(opts.endpoint);
     const shownUrl = buildDisplaySafeUrl(url);
-    const fetchImpl = opts.fetchImpl ?? fetch;
+    const fetchImpl = createEgressFetch("declare the final endpoint as MEMORY_EMBEDDER_ENDPOINT", opts.fetchImpl);
     const { model, dimensions, timeoutMs, apiKey, onFailure } = opts;
     const secrets = [...(apiKey !== undefined ? [apiKey] : []), ...credentialsInQuery(opts.endpoint)];
     const scrub = (raw) => secrets.reduce((acc, s) => acc.replaceAll(s, "***"), raw);
@@ -44,15 +48,13 @@ export function createOpenAiCompatEmbedder(opts) {
                 },
                 body: JSON.stringify({ model, input: text }),
                 signal: AbortSignal.timeout(timeoutMs),
-                redirect: "manual",
             });
         }
         catch (transportErr) {
+            if (transportErr instanceof EgressRedirectRefusedError)
+                throw new Error(`memory embedder POST ${shownUrl}: ${transportErr.message}`);
             throw new Error(`memory embedder POST ${shownUrl}: transport failure — ${safeSlice(String(transportErr))}`);
         }
-        const redirected = egressRedirectRefusal(res, "declare the final endpoint as MEMORY_EMBEDDER_ENDPOINT");
-        if (redirected !== undefined)
-            throw new Error(`memory embedder POST ${shownUrl}: ${redirected}`);
         const raw = await res.text().catch((readErr) => {
             throw new Error(`memory embedder POST ${shownUrl}: response body unreadable — ${safeSlice(String(readErr))}`);
         });
@@ -86,7 +88,7 @@ export function createOpenAiCompatEmbedder(opts) {
                     onFailure?.(err);
                 }
                 catch (hookErr) {
-                    process.emitWarning(`memory embedder onFailure hook threw: ${String(hookErr)}`, "MemoryEmbedderObservabilityWarning");
+                    embedderLog.warn(MEMORY_EMBEDDER_HOOK_THREW, { err: errorText(hookErr) });
                 }
                 throw err;
             }

package/dist/plugins/memory-engine-pg.d.ts

@@ -41,7 +41,7 @@ export interface PgMemoryEngineBackendOptions {
      *  connections, so a true transaction would require refactoring the constructor to a client-checkout
      *  seam (breaks the origin-core@3071dd3 minimal-diff move-in discipline).
      *  Chosen trade-off: entry write commits first, history append is BEST-EFFORT
-     *  (failure = swallow + console.warn) — history is the AUDIT face, not the correctness face: a lost
+     *  (failure = swallow + a log-seam warn line) — history is the AUDIT face, not the correctness face: a lost
      *  history row loses an audit line, never data (the entries table stays the single truth). */
     history?: {
         appendHistory(rows: readonly MemoryHistoryAppendRow[]): Promise<void>;
@@ -93,7 +93,8 @@ export declare class PgMemoryEngineBackend implements MemoryBackend {
      */
     private writeAdd;
     /** update:条件 = 判过的 rev **且**判过的投影(rev 是内容哈希、不含 scope / slug)。零行 ⇒ 现读:内容未变而投影变了 = `moved`;其余 =
-     *  CAS 冲突,currentRev 报现值(行没了 ⇒ 判时的值)。 */
+     *  CAS 冲突,currentRev 报现值(行没了 ⇒ 判时的值)。撞唯一键:主键 `id` 不变,能撞的只有 `(scope, slug)` —— 目标名在判之后被别的 id 占了
+     *  ⇒ `slug-taken`(与 add 口同一结局词;驱动器重判,判当场判成冲突)。 */
     private writeUpdate;
     /** delete:条件同 update。 */
     private writeDelete;

package/dist/plugins/memory-engine-pg.js

@@ -1,3 +1,4 @@
+import { writeLogText } from "../observability/logger.js";
 import { cosineDistance, jaccardDistance, termSet } from "@sema-agent/core";
 import { isUniqueViolation, readEmbeddingColumn, readFrontmatterColumn } from "./memory-engine-vector-util.js";
 import { decodeJsonColumn, decodeNullableJsonColumn, foldJsonColumn, isJsonColumnBodyProblem, jsonColumnText } from "./sql-json-column.js";
@@ -250,10 +251,18 @@ export class PgMemoryEngineBackend {
     async writeUpdate({ entry, rev, currentRev, current, baseRev }, embedding, confirm) {
         const params = [entry.id, entry.scope, entry.slug, pgSafeJsonStringify(entry.frontmatter), entry.body, rev, this.clock(), Buffer.byteLength(serializeEntryFile(entry), "utf8"), embedding, currentRev, current.scope, current.slug];
         confirm();
-        const res = await this.query(`UPDATE ${PG_MEMORY_ENGINE_TABLES.entry}
-          SET scope = $2, slug = $3, frontmatter = $4, body = $5, rev = $6, mtime_ms = $7, size_bytes = $8, embedding = $9
-        WHERE id = $1 AND rev = $10 AND scope = $11 AND slug = $12
-        RETURNING id`, params);
+        let res;
+        try {
+            res = await this.query(`UPDATE ${PG_MEMORY_ENGINE_TABLES.entry}
+            SET scope = $2, slug = $3, frontmatter = $4, body = $5, rev = $6, mtime_ms = $7, size_bytes = $8, embedding = $9
+          WHERE id = $1 AND rev = $10 AND scope = $11 AND slug = $12
+          RETURNING id`, params);
+        }
+        catch (err) {
+            if (isUniqueViolation(err))
+                return { kind: "slug-taken" };
+            throw err;
+        }
         if (res.rows.length > 0)
             return { kind: "committed" };
         const fresh = await this.freshRow(entry.id);
@@ -279,7 +288,7 @@ export class PgMemoryEngineBackend {
         }
         catch (err) {
             this.historyRowsLost += rows.length;
-            console.warn(`PgMemoryEngineBackend: best-effort history append failed (${rows.length} row(s) lost, ${this.historyRowsLost} cumulative — audit face only, entries committed): ${err instanceof Error ? err.message : String(err)}`);
+            writeLogText("stderr", `PgMemoryEngineBackend: best-effort history append failed (${rows.length} row(s) lost, ${this.historyRowsLost} cumulative — audit face only, entries committed): ${err instanceof Error ? err.message : String(err)}`);
         }
     }
     async getConsolidationCursor(scope) {

package/dist/plugins/memory-engine-sql-apply.d.ts

@@ -24,15 +24,19 @@
  * · LANDING = 一个 patch 写下或移走的每个拼写 `{ id, scope, slug }`:add 的终拼(含撞名后缀)、同 scope 改名留下的旧拼、update 的目标
  *   与移走的旧拼、delete 移走的拼。
  * · 写语句把**计划的投影**也绑进条件(rev 是内容哈希、不含 scope / slug,单靠 `WHERE id AND rev` 绑不住落点):行在计划之后被挪到别的拼写
- *   ⇒ 写不落,方言写口按现读答 `moved`,驱动器重判(新拼写同样要问过才写);名被占(唯一键冲突)⇒ `slug-taken`,重判从下一个后缀起
- *   (与改前「撞键即退下一个后缀」同一序列)。
+ *   ⇒ 写不落,方言写口按现读答 `moved`,驱动器重判(新拼写同样要问过才写);名被占(唯一键 `(scope, slug)` 冲突,add 与 update 两口同译)
+ *   ⇒ `slug-taken`,一条律:这一 patch 的候选起格越过被拒的那个拼写、驱动器重判 —— add 从下一个后缀起(与改前「撞键即退下一个后缀」同一序列);
+ *   update 只有一个候选(目标拼写)⇒ 越过即没有候选,判成冲突(被库拒过的拼写本次 apply 不再重写:对手在拒之后腾出名也一样,重写留给下次 apply ——
+ *   否则「每条写前占名、拒后腾名」的对手能让同一计划无界重写)。
+ * · 「目标名被别的 id 占着」只在判里判一处({@link planSqlPatch} 的 update 支):计划阶段就看得见的占名在那里直接判成冲突(一句、方言无关、
+ *   零写语句、不产落点);写语句那一刻才撞上的占名经 `slug-taken` 推过候选起格、回到同一处判。所以这一冲突两条路同一句,且都不是「可能写过」。
  * · 问的次数有上限(core `MAX_LANDING_ADMISSION_ROUNDS`),超了 core 抛 `memory.landing_unstable`(此时恒一字未写)。
  * · `confirm` = 调用方的最后一句话:方言写口在**每条** entry 写语句发出之前同步调它(与写语句之间没有 await)。SQL 腿不持事务锁 ——
  *   confirm 与写语句之间仍有一段竞争窗,这是两腿「单语句 CAS、无事务」的既有结构事实(MIGRATION / USAGE 的已知限制一句)。
  * · 抛错分诊:per-patch 的 catch 只把读 / 写 I/O 失败记成 `io error` 冲突(改前同);`confirm` 的抛被包成 {@link CallerThrow} 越过这道
  *   catch,出驱动器时还原成调用方抛出的**同一个值**;`admit` 根本不在 catch 内。已提交 patch 的 history 在 `finally` 里照冲刷。
  * · 「已经写过」按**可能写过**算:一条写语句发出之后以 I/O 失败收场,库里落没落不知道 ⇒ 当作写过(此后不再问),否则后面一次被拒的重问
- *   就可能发生在一笔其实已落下的写之后。写语句的三种「没落」结局(唯一键冲突 / 零行 + 现读)是库给的确答,不算写过。
+ *   就可能发生在一笔其实已落下的写之后。写语句的「没落」结局(唯一键冲突 —— add 与 update 两口 / 零行 + 现读)是库给的确答,不算写过。
  * · 不传 opts ⇒ 没有计划阶段、`confirm` 是空操作;常规路径与改前逐字同。只在并发竞争路径上收紧:行在判与写之间被挪走 ⇒ 按现状重判
  *   再写(此前按 id 盲写);同 id 的行在判与写之间被别的副本插入或改写 ⇒ 重判(guard / 跨 scope 拒照判,此前按 id 盲覆盖)。
  * · 写条件只有一条律:写语句绑住**判据用到的那一份** —— update / delete 判的是 rev(CAS)与投影 ⇒ 两者都绑;add 覆盖判的是投影
@@ -91,7 +95,7 @@ export interface SqlDeleteWrite {
     readonly baseRev: string | undefined;
 }
 /**
- * 一次写的结局:`committed` = 落了;`slug-taken` = 唯一键 `(scope, slug)` 冲突(名在计划之后被别的副本占了);`moved` = 写不落而现读显示
+ * 一次写的结局:`committed` = 落了;`slug-taken` = 唯一键 `(scope, slug)` 冲突(名在计划之后被别的副本占了;add 与 update 两口同译);`moved` = 写不落而现读显示
  * 这个 id 的行已不在计划的投影上(或计划时没有、现在有了);`lost` = rev CAS 输了(冲突里的 currentRev 是现值)。
  */
 export type SqlWriteOutcome = {

package/dist/plugins/memory-engine-sql-apply.js

@@ -138,6 +138,9 @@ async function planSqlPatch(patch, reads, baseline, claims, unstorableReason, su
         return conflict({ op: "update", id: patch.id, reason: unstorableReason });
     }
     const moves = current.scope !== entry.scope || current.slug !== entry.slug;
+    if (moves && (suffixFrom > FIRST_SUFFIX_STEP || (await reads.idsAt(entry.scope, entry.slug)).some((holder) => holder !== patch.id))) {
+        return conflict({ op: "update", id: patch.id, reason: `update target ${JSON.stringify(`${entry.scope}/${entry.slug}`)} is held by another entry (unique (scope, slug)); not written` });
+    }
     return {
         kind: "update",
         entry,
@@ -145,6 +148,7 @@ async function planSqlPatch(patch, reads, baseline, claims, unstorableReason, su
         currentRev: current.rev,
         current: at,
         baseRev: patch.baseRev,
+        suffixAt: FIRST_SUFFIX_STEP,
         landings: [...(moves ? [{ id: patch.id, ...at }] : []), { id: entry.id, scope: entry.scope, slug: entry.slug }],
     };
 }
@@ -187,13 +191,8 @@ async function predictLandings(patches, from, duplicateAt, reads, unstorableReas
         if (duplicateAt.has(i))
             continue;
         let plan;
-        let targetHeld = false;
         try {
             plan = await planSqlPatch(patches[i], view, scratchBaseline, scratchClaims, unstorableReason, suffixFloor.get(i) ?? FIRST_SUFFIX_STEP);
-            if (plan.kind === "update") {
-                const { id, scope, slug } = plan.entry;
-                targetHeld = (await view.idsAt(scope, slug)).some((holder) => holder !== id);
-            }
         }
         catch {
             continue;
@@ -206,8 +205,7 @@ async function predictLandings(patches, from, duplicateAt, reads, unstorableReas
             scratchClaims.add(slugKey(plan.stored.scope, plan.stored.slug));
         }
         else if (plan.kind === "update") {
-            if (!targetHeld)
-                overlay.set(plan.entry.id, { scope: plan.entry.scope, slug: plan.entry.slug, rev: plan.rev, frontmatter: plan.entry.frontmatter });
+            overlay.set(plan.entry.id, { scope: plan.entry.scope, slug: plan.entry.slug, rev: plan.rev, frontmatter: plan.entry.frontmatter });
         }
         else {
             overlay.set(plan.id, null);
@@ -302,7 +300,7 @@ export async function applySqlPatches(patches, opts, leg) {
                         report.conflicts.push(outcome.conflict);
                         return [];
                     case "slug-taken":
-                        if (plan.kind === "add")
+                        if (plan.kind !== "delete")
                             suffixFloor.set(k, plan.suffixAt + 1);
                         continue;
                     case "moved":

package/dist/plugins/memory-engine-tidb.d.ts

@@ -27,7 +27,7 @@ export interface TiDBMemoryEngineBackendOptions {
      *  entry plane itself is deliberately NON-transactional (single-statement CAS is the correctness
      *  mechanism), and the Pg twin's bare-PgQueryFn seam cannot cheaply transact — wrapping only the
      *  TiDB side would fork the twins' semantics. Chosen trade-off on BOTH dialects: entry write commits
-     *  first, history append is BEST-EFFORT (failure = swallow + console.warn) — history is the AUDIT
+     *  first, history append is BEST-EFFORT (failure = swallow + a log-seam warn line) — history is the AUDIT
      *  face, not the correctness face: a lost history row loses an audit line, never data. */
     history?: {
         appendHistory(rows: readonly MemoryHistoryAppendRow[]): Promise<void>;
@@ -84,7 +84,9 @@ export declare class TiDBMemoryEngineBackend implements MemoryBackend {
      *    这是零行唯一能是 applied 的形 —— 目标 rev 与判过的 rev 不同的 update 一定改动行(rev 列本身变了),零行即未匹配;
      *    行被对手改走又改回判过的 rev 时,按 rev 它没变过(与 File 腿的比对、与共享判里「A→B→A 让 stale baseRev 重新当前」同一读法),这一条本来就是什么都没改 ⇒ 照样已落;
      *  · 内容未变而投影变了 = `moved`;其余 = CAS 冲突,`currentRev` 报现值。
-     *  🔴 行存在性是承重的:判与写之间行被并发删掉时 affectedRows 也是 0,现读对没了的行答 undefined ⇒ 落冲突(逐字相同的 update 也一样),两方言同答。 */
+     *  🔴 行存在性是承重的:判与写之间行被并发删掉时 affectedRows 也是 0,现读对没了的行答 undefined ⇒ 落冲突(逐字相同的 update 也一样),两方言同答。
+     *  撞唯一键(ER_DUP_ENTRY):主键 `id` 不变,能撞的只有 `(scope, slug)` —— 目标名在判之后被别的 id 占了 ⇒ `slug-taken`(与 add 口、PG 孪生同一结局词;
+     *  驱动器重判,判当场判成冲突)。 */
     private writeUpdate;
     /** delete:条件同 update;DELETE 的 affectedRows 数的是删掉的行(FOUND_ROWS 只影响 UPDATE):0 = 行变了 / 挪了 / 没了。 */
     private writeDelete;

package/dist/plugins/memory-engine-tidb.js

@@ -1,3 +1,4 @@
+import { writeLogText } from "../observability/logger.js";
 import { jaccardDistance, termSet } from "@sema-agent/core";
 import { readFrontmatterColumn } from "./memory-engine-vector-util.js";
 import { decodeJsonColumn, foldJsonColumn, jsonColumnText } from "./sql-json-column.js";
@@ -214,7 +215,15 @@ export class TiDBMemoryEngineBackend {
     async writeUpdate({ entry, rev, currentRev, current, baseRev }, _prepared, confirm) {
         const params = [entry.scope, entry.slug, JSON.stringify(entry.frontmatter), entry.body, rev, this.clock(), Buffer.byteLength(serializeEntryFile(entry), "utf8"), entry.id, currentRev, current.scope, current.slug];
         confirm();
-        const res = await this.write(`UPDATE ${TIDB_MEMORY_ENGINE_TABLES.entry} SET scope = ?, slug = ?, frontmatter = ?, body = ?, rev = ?, mtime_ms = ?, size_bytes = ?, embedding = NULL WHERE id = ? AND rev = ? AND ${AT_PLANNED_PROJECTION}`, params);
+        let res;
+        try {
+            res = await this.write(`UPDATE ${TIDB_MEMORY_ENGINE_TABLES.entry} SET scope = ?, slug = ?, frontmatter = ?, body = ?, rev = ?, mtime_ms = ?, size_bytes = ?, embedding = NULL WHERE id = ? AND rev = ? AND ${AT_PLANNED_PROJECTION}`, params);
+        }
+        catch (err) {
+            if (isDupEntry(err))
+                return { kind: "slug-taken" };
+            throw err;
+        }
         if (res.affectedRows > 0)
             return { kind: "committed" };
         const fresh = await this.freshRow(entry.id);
@@ -244,7 +253,7 @@ export class TiDBMemoryEngineBackend {
         }
         catch (err) {
             this.historyRowsLost += rows.length;
-            console.warn(`TiDBMemoryEngineBackend: best-effort history append failed (${rows.length} row(s) lost, ${this.historyRowsLost} cumulative — audit face only, entries committed): ${err instanceof Error ? err.message : String(err)}`);
+            writeLogText("stderr", `TiDBMemoryEngineBackend: best-effort history append failed (${rows.length} row(s) lost, ${this.historyRowsLost} cumulative — audit face only, entries committed): ${err instanceof Error ? err.message : String(err)}`);
         }
     }
     async getConsolidationCursor(scope) {

package/dist/plugins/memory-optout-grant-store-sql.d.ts

@@ -6,7 +6,7 @@
  *
  * ── 数据形([ref] §1.1 的施工形;**稿偏离如实记**)────────────────────────────────────────────────
  * [ref] 稿写的是 `PRIMARY KEY (org_id, principal)` + `principal=''` 为 org 级缺省哨兵行。亲读本仓
- * (侦察 2026-08-30):server **没有 org 身份维** —— 租户维 = 单 `principal`(`gatedPrincipal` 供给),
+ * (侦察 2026-08-30):server **没有 org 身份维** —— 租户维 = 单 `principal`(`gatedSubject` 供给),
  * `org` 只是记忆 scope 目录里的一个词(`org-memory-admission.ts`:授权目录三态,不是 principal 的属性),
  * 任何 SQL 表都没有 `org_id` 列。给表铸一根没人能填的 `org_id` 就是编数据(「不编」律)。所以:
  *   · **一台 worker = 一个租户面**,稿中「org 级缺省行」落成**部署级缺省行**(同一哨兵 `principal=''`);

package/dist/plugins/memory-optout-grant-store-sql.js

@@ -1,5 +1,5 @@
 import { mysqlDriver, pgDriver } from "./sql-driver.js";
-import { RESERVED_PRINCIPALS, RESERVED_PRINCIPAL_PREFIXES } from "../security.js";
+import { PRINCIPAL_MAX_BYTES, RESERVED_PRINCIPALS, RESERVED_PRINCIPAL_PREFIXES } from "../principal-shape.js";
 export const MEMORY_OPTOUT_GRANT_TABLE = "memory_optout_grant";
 export const MEMORY_OPTOUT_DEFAULT_PRINCIPAL = "";
 export function buildMemoryOptOutVerdict(rows, principal) {
@@ -16,8 +16,8 @@ export function buildMemoryOptOutVerdict(rows, principal) {
 export function memoryOptOutPrincipalShapeProblem(principal) {
     if (principal.length === 0)
         return "principal is empty (the empty string is the deployment-default sentinel row, not an addressable principal)";
-    if (principal.length > 190)
-        return "principal exceeds the 190-char column width";
+    if (Buffer.byteLength(principal, "utf8") > PRINCIPAL_MAX_BYTES)
+        return `principal exceeds ${PRINCIPAL_MAX_BYTES} UTF-8 bytes (the principal length every identity column holds)`;
     if (/^\s|\s$/u.test(principal))
         return "principal has leading/trailing whitespace (rejected at the boundary: MySQL-protocol PAD SPACE collation would fold it onto another principal's row)";
     if (/[\u0000-\u001f\u007f]/u.test(principal))

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 FenceLanded, type FencedRun, type InProcessClaimFence, type CreateRunOutcome, type NewRunMeta, type RunIdemBinding, type RunListQuery, type RunRecord, type SessionSummary, type RunEvent, type PersistedTaskResult, type LatestRunRef, type SettledLegMemoryObservation } from "./store-contracts.js";
+import { type RunStallWiring, type SessionRootRows, type FenceLanded, type FencedRun, type InProcessClaimFence, type CreateRunOutcome, type NewRunMeta, type RunIdemBinding, type RunListQuery, type RunRecord, type SessionRunRollup, type RunEvent, type PersistedTaskResult, type LatestRunRef, type SettledLegMemoryObservation } from "./store-contracts.js";
 import type { LedgerEventType } from "../trace/ledger-events.js";
 import { type SpaceCommitClaim, type SpaceCommitReading, type SpaceCommitState } from "../workspace-space-commit.js";
 /**
@@ -35,6 +35,17 @@ export declare class MemoryRunStore implements InProcessClaimFence {
     /** spaceKey → row — the twin of `workspace_space_commit` (the k8s workspace space's commit fence, `workspace-space-commit.ts`). */
     private readonly spaceCommitRecords;
     private readonly spaceCommits;
+    /**
+     * 规则 L 的根行面(可选;文件孪生同形同读法,见 `FileRunStore` 的同名字段):在场 ⇒ `createRun` 先在它的锁里判根行在不在(不在 ⇒ `sessionAbsent`),再认领 ——
+     * 测试装配「内存 run 店 + 同一只 local 会话店」的撤回与认领因此排在同一把根锁上。缺席(只测 run 店、或配引擎内存会话店的装配:那种店没有根行)⇒ 不判根行,行为与修前同。
+     */
+    private readonly rootRows;
+    /** 落死亡判决的窗与计数(构造时拿到;SQL 孪生同注,见 {@link RunStallWiring})。 */
+    private readonly stall;
+    constructor(opts?: {
+        readonly rootRows?: () => SessionRootRows;
+        readonly stall?: RunStallWiring;
+    });
     /** The k8s workspace space's commit fence rows (SQL twin: `workspace_space_commit`; the rule: `workspace-space-commit.ts`). */
     readSpaceCommit(spaceKey: string): Promise<SpaceCommitReading | undefined>;
     claimSpaceCommit(spaceKey: string, taskId: string, state: SpaceCommitState, claim: SpaceCommitClaim): Promise<boolean>;
@@ -46,6 +57,15 @@ export declare class MemoryRunStore implements InProcessClaimFence {
     /** Create a run iff no submission key of this request names a row (idemKey first, then a caller-minted taskId —
      *  OBSERVED, see {@link CreateRunOutcome}) and the session has no active run (the task_active unique-key claim). */
     createRun(taskId: string, sessionId: string, owner: string | null, instanceId: string, meta?: NewRunMeta): Promise<CreateRunOutcome>;
+    /** {@link createRun} 的认领一半(根行已判过在 —— 或本店不接根行面)。同步判、同步写(没有让出点:两只并发认领不交错)。 */
+    private createRunClaimed;
+    /**
+     * 提交出口条件撤回的 run 半(`local-session-store.ts` 的 `SessionRunWithdrawSource`;文件孪生同名方法同判序):本会话有 `ownTaskId` 之外的 run 行 ⇒ `{ keep: "runs" }`;
+     * 否则删本次 run(事件 / 幂等键 / 行)。调用方持根行锁 —— 不取锁、不让出事件循环。`ownTaskId` 那一行不属于这只会话 ⇒ 响亮抛。
+     */
+    withdrawRunsOf(sessionId: string, ownTaskId: string | undefined): "proceed" | {
+        readonly keep: "runs";
+    };
     /** Undo THIS submission's binding (key + body fingerprint → null) — called only where the submit surface refuses the submission
      *  before any work and terminalizes the row it just claimed (the sync leg's zero-work refusal, an execution-placement reject):
      *  the error answer invites a retry, and a retry with the same key must run, not replay the refusal. The row stays (it
@@ -63,7 +83,8 @@ export declare class MemoryRunStore implements InProcessClaimFence {
     isCancelRequested(taskId: string, owner: string | null): Promise<boolean>;
     requestPreempt(taskId: string, owner: string | null): Promise<boolean>;
     isPreemptRequested(taskId: string, owner: string | null): Promise<boolean>;
-    heartbeat(taskId: string, owner: string | null): Promise<void>;
+    /** 心跳:刷新并交回「行还在 running 吗」(持有者据它停腿;SQL 孪生同注)。 */
+    heartbeat(taskId: string, owner: string | null): Promise<boolean>;
     appendEvent(taskId: string, seq: number, type: LedgerEventType, data: unknown): Promise<void>;
     maxSeq(taskId: string): Promise<number>;
     retainedFrom(taskId: string): Promise<number>;
@@ -91,7 +112,7 @@ export declare class MemoryRunStore implements InProcessClaimFence {
     listRuns(opts: RunListQuery): Promise<RunRecord[]>;
     /**
      * [ref] —— 这个会话**最近一条腿**的窄指针({@link SqlRunStore.latestRunForSession} 的孪生:同一个排序口径
-     *  `createdAt DESC, taskId DESC`,与本店 {@link MemoryRunStore.listSessions} 挑 `rn=1` 那一行的比较器逐字同一份)。
+     *  `createdAt DESC, taskId DESC`,与本店窄读面 {@link MemoryRunStore.sessionRunRollups} 挑最新一条的比较器同一口径 —— `session-run-rollup.ts` 的 `newer`)。
      */
     latestRunForSession(sessionId: string): Promise<LatestRunRef | undefined>;
     /**
@@ -99,32 +120,17 @@ export declare class MemoryRunStore implements InProcessClaimFence {
      * {@link SqlRunStore.latestMemoryObservationForSession} 的孪生:同一只已结谓词(`isTerminalRunStatus`)、同一个排序口径 —— 与本店 {@link MemoryRunStore.latestRunForSession} 的比较器逐字同一份)。
      */
     latestMemoryObservationForSession(sessionId: string): Promise<SettledLegMemoryObservation | undefined>;
-    /** DISTINCT sessions newest-first by last activity (the CC /resume picker): latest run's preview/status + first/last/count. */
-    listSessions(opts: {
-        owner?: string;
-        includeUnowned?: boolean;
-        cursor?: {
-            lastActivityAt: string;
-            sessionId: string;
-        };
-        limit: number;
-        q?: string;
-    }): Promise<SessionSummary[]>;
+    /** 会话枚举面读 run 账的窄读面(`SessionRunRollupSource`;规则 = 共用纯函数 {@link buildSessionRunRollups},与文件孪生、SQL 会话店的列表子查询同读)。 */
+    sessionRunRollups(opts?: {
+        readonly q?: string;
+    }): Promise<ReadonlyMap<string, SessionRunRollup>>;
     /**
      * E21 (§0.5 delete) — purge the runs ledger for one session, scoped by `session_id` ALONE (per-row owner is the
-     * submitting principal and diverges from the session owner — full 判据 see the SQL twin's head-note, F-A);
-     * aborts (returns {active}) if a run is live.
-     *
-     * `expectedSessionOwner` 是 SQL 双生的**化身围栏**入参(事务内复核 `session_meta.owner`,防「A 验权后 A' 删完、
-     * 别人用同一 uuid 重新登记」那一形)。本孪生**执行不了**它:local 车道的会话表在另一只店里,这只账本没有
-     * session_meta 可读 —— 参数只作契约对齐(签名不齐会让 RunStore 联合类型的调用点直接不可调)。local 的替代
-     * 围栏是两条:①协调器在本调用**紧前**复读一次 canonical owner(不齐即整条中止);②数据根的独占 BootLock
-     * 保证一个数据根恒一个进程,交错只可能发生在同进程的 await 缝里。这条不对称是**明写**的,不是遗漏。
+     * submitting principal and diverges from the session owner — full 判据 see the SQL twin's head-note, F-A)。
+     * **不判认领**:与 File / SQL 孪生同一条(唯一调用点 = 删除协调器的账本腿,围栏之后才调;律在 `src/session-deletion.ts`)。
      */
-    deleteBySession(sessionId: string, expectedSessionOwner: string | null): Promise<{
+    deleteBySession(sessionId: string): Promise<{
         removed: number;
-    } | {
-        active: string;
     }>;
     /** 用量扫窗——in-memory 腿:遍历窗内行,投影同 usage-analytics 纯函数(SQL 孪生 parity)。 */
     usageScan(fromMs: number, toMs: number, opts?: {
@@ -139,8 +145,14 @@ export declare class MemoryRunStore implements InProcessClaimFence {
         status: string;
         count: number;
     }>>;
-    /** Fail stale `running` rows (crashed-run backstop) + release task_active for any now-terminal row. */
-    reapStale(olderThanMs: number): Promise<number>;
+    /** 收割器(全表形;SQL 孪生同注):心跳过期的 `running` 行判死 + 放掉终局行的认领。窗读构造时拿到的 getter。 */
+    reapStale(): Promise<number>;
+    /** 死亡判决的那一笔(收割器 / 观察口 / 认领冲突同一只;SQL 孪生的 `landStallVerdicts`):行 `due` ⇒ 翻 `failed`(`run.stalled`)、交回 `true`;否则不动。认领由调用方放。 */
+    private landStallVerdict;
+    /** 认领冲突的持有者落判决(SQL 孪生同判):`due` ⇒ 判死、放它的认领、交回 `true`(调用方照常认领)。 */
+    private settleDueHolder;
+    /** 观察口(落判决的三处之一;SQL 孪生同注):属主门之后的那条行 —— `due` ⇒ 判死、放认领、交回当前行;否则原样。 */
+    observeRun(row: RunRecord): Promise<RunRecord>;
     /** [ref] shared tail of both suspended-run reapers: flip one parked row → failed('approval.expired'), the
      *  in-memory twin of the SQL UPDATE (`error`/`error_code` set directly — no result blob to derive from; [ref]: the park-time `result` is cleared, same as the SQL `result = NULL`). */
     private failExpiredPark;