@sema-agent/server 7.91.2 → 7.92.1

package/dist/plugins/remote-env-host.d.ts

@@ -103,6 +103,55 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
      *  `exitCode 0`。对模型而言那与「成功且无输出」**不可区分**。(与 core [ref] 同形:写已释放的 inode。)
      *  判据与 `hasShells()` 并列:**只要还有人在读写这个根下的文件,就不删它**。 */
     private readonly liveFgSpools;
+    /** 🔴 S-539 在飞的 fs **写**登记表(`liveFgSpools` 同律:「还有人在动这棵树,就别删它」)。
+     *  为什么按 promise 存而不是计数:只有 promise 才能被 `destroy()` **await**;计数只能轮询。 */
+    private readonly inflightFs;
+    /** 一次性:慢 drain 只抱怨一次(一条按次数刷屏的 teardown 读数没人会看)。 */
+    private inflightFsDrainWarned;
+    /**
+     * 🔴 S-539 —— 把一只**会在 workspace / spool 根里建路径或改路径**的 fs 动作登记为「在飞」,直到它 settle。
+     *
+     * ── 病(旧 `destroy()` 的自称与实情)──────────────────────────────────────────────────────────
+     * `destroy()` 只 await 了 `ensurePrepared()` 那只 memo(`preparing`),于是它顶注里的
+     * 「eliminating the prepared-flag race entirely」只对 **prepare 那一段**成立。写面在
+     * `await this.fsReady(p)` 放行**之后**还会自己碰一次磁盘(`writeFile`/`appendFile` 的
+     * `mkdir(dirname)`、`createDir` 的 `mkdir`、`createTempDir`/`createTempFile` 在 spool 根下建),
+     * 那一次调用与 destroy 的 `fs.rm` 是**两条独立 fs 调用在 libuv 线程池里赛跑**:rm 先 ⇒ `mkdir -p` 把已拆除
+     * 的工作区重建成**孤儿**(而 rm 成功后 `untrackEphemeralHostWorkspace()` 已注销 ⇒ 兜底腿也捞不回);
+     * mkdir 先 ⇒ 随后 rm 删掉,调用方拿到 `EINVAL`/`ENOENT` 而不是 "already destroyed"。
+     *
+     * ── 治(一处定义,十几个面共用)────────────────────────────────────────────────────────────────
+     * 调用点必须在方法体的**第一个同步段**里调它(第一个 `await` 之前),登记才与 `destroy()` 置 `destroyed`
+     * 的同步段互斥。于是二者只有两种相对次序,**两种都安全**:
+     *  · 先登记 ⇒ destroy 的快照看得到它,`rm` 等它 settle 之后才发;
+     *  · 后登记 ⇒ 这一面自己的 `fsReady` 看得到 `destroyed`,一个字节都不碰磁盘。
+     * 登记放在 `await this.fsReady(...)` **之后**就没有这个性质:那一刻已经跨过一个 microtask,destroy 可能刚好
+     * 在这中间把快照取完了。所以形状是 `return this.withInflightFs(async () => { …原方法体… })`,
+     * 而不是在方法体里补一句 `if (this.destroyed)` —— 后者仍然不原子(查完到动手之间还有让出点)。
+     *
+     * ── 读面刻意不进来 ─────────────────────────────────────────────────────────────────────────────
+     * ① 读不建路径:拆除之后一次在飞的读拿到 ENOENT 是**诚实**的,复活目录这条病与它无关;
+     * ② 把读拉进来会让 teardown 去等一次可能**永不 settle** 的读(workspace 里的 FIFO / 特殊文件),
+     *    把 destroy 挂死 —— 拿一条新的可用性病换一条不存在的正确性收益。
+     * 判据因此是一句话:**「可能建路径或改路径的那些面」进在飞集合**,不是「过了 fsReady 的都进」。
+     */
+    private withInflightFs;
+    /**
+     * 等 `destroy()` 取到的那批在飞写全部 settle。**永不抛**;答「在时限内清空了吗」。
+     *
+     * 🔴 两条都不能要,所以有第三条(合并复审 [high] 打出来的):
+     *  ① 无界等 —— workspace 里的 FIFO / 特殊文件会让一次 `writeFile` **永不 settle**,而拆除在 run 收尾路径上
+     *     ⇒ 整条收尾停摆。用一条新的可用性病换一条正确性收益,不划算。
+     *  ② 到点就照删 —— 把 S-539 的竞态**原样**搬回来(rm 与在飞 mkdir 再次在线程池里赛跑),只是把窗口从
+     *     「总是」改成「慢的时候」;一条确定的病换一条间歇的病,更糟。
+     *  ③ **到点就不再占着调用方,但 rm 依旧排在那批写之后**(`destroy()` 里的 `void …then(removeOwnedTrees)`)。
+     *     次序保证一个字节不松,teardown 变成「有界返回」。teardown 契约(core 1.258.2)禁的是**抛**,不是**慢**;
+     *     这一条连慢都不欠。
+     *
+     * 快照是 `destroy()` 在同步段取的,所以 destroy **之后**才登记的那些面(唯一一族:`appendFile` 的
+     * `lingeringBgWrite` 残余镜像写)不在这一批里 —— 它们按设计就是跨 destroy 存活的,等它们等于等后台 shell。
+     */
+    private drainInflightFs;
     private ensureSpoolRoot;
     /** True when `workspaceDir` was given (user-owned persistent dir) → destroy() must NOT delete it. */
     private readonly persistent;
@@ -155,6 +204,10 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
      *  core 留活过的驻留 watcher 又杀了一遍(run 尾 dispose→destroy 顺序,destroy 是第二刀)。隔离 env(容器/VM)
      *  整体拆机自然带走进程,与本契约不冲突(k8s/e2b 各自 destroy 不走这条路径)。 */
     destroy(): Promise<void>;
+    /** `destroy()` 真正动手删的那一段(本 env **自有**的两棵树:spool 根 + ephemeral workspace)。
+     *  抽成一只是因为它有两个调用时机 —— 在飞写按时清空时由 `destroy()` 直接 await,超时时挂在那批写后面异步跑
+     *  (见 {@link drainInflightFs} 头注③)。永不抛(teardown 契约)。 */
+    private removeOwnedTrees;
     cleanup(): Promise<void>;
     get backgroundCapabilities(): BackgroundShellCapability["backgroundCapabilities"];
     private _bgManager?;
@@ -210,7 +263,12 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
         abortSignal?: AbortSignal;
     }): Promise<Result<string[], FileError>>;
     readBinaryFile(p: string, abortSignal?: AbortSignal): Promise<Result<Uint8Array, FileError>>;
+    /** S-539:整只方法体(**含** `fsReady` 那道门)走 `withInflightFs` —— 登记必须与调用方同一同步段,
+     *  否则 destroy 的快照可能刚好在 `await this.fsReady(...)` 的让出点上取完。见那处头注。 */
     writeFile(p: string, content: string | Uint8Array, abortSignal?: AbortSignal): Promise<Result<void, FileError>>;
+    /** S-539(写面一律 `withInflightFs`,见那处头注)。本面是唯一能在 `destroyed` **之后**过门的写面
+     *  (`lingeringBgWrite`):那一族登记在 destroy 的快照**之后**,所以 destroy 不会去等它们 —— 正确,
+     *  它们按设计跨 destroy 存活(等它们等于等后台 shell)。 */
     appendFile(p: string, content: string | Uint8Array, abortSignal?: AbortSignal): Promise<Result<void, FileError>>;
     fileInfo(p: string, abortSignal?: AbortSignal): Promise<Result<FileInfo, FileError>>;
     listDir(p: string, abortSignal?: AbortSignal): Promise<Result<FileInfo[], FileError>>;
@@ -231,10 +289,14 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
      */
     canonicalChain(p: string, abortSignal?: AbortSignal): Promise<Result<SymlinkChain, FileError>>;
     exists(p: string, abortSignal?: AbortSignal): Promise<Result<boolean, FileError>>;
+    /** S-539(写面一律 `withInflightFs`,见那处头注)。 */
     createDir(p: string, options?: {
         recursive?: boolean;
         abortSignal?: AbortSignal;
     }): Promise<Result<void, FileError>>;
+    /** S-539(写面一律 `withInflightFs`,见那处头注)。本面**不会**复活目录(`fs.rm` 只删),进在飞集合的理由是
+     *  同一条:destroy 的 rm 把树从它脚下抽走 ⇒ 一次本该 ok 的删返回 `not_found`。判据是「可能建或改路径」,
+     *  不是「可能复活目录」—— 少一条例外就少一处以后要重新想清楚的地方。 */
     remove(p: string, options?: {
         recursive?: boolean;
         force?: boolean;
@@ -252,7 +314,10 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
      *   · 镜像写仍然可用 —— `isLingeringMirrorTarget` 同批放行这个根(见那里的旁注);
      *   · ephemeral 形反而更好:`destroy()` 在**有后台 shell 在册**时不删这个根,而 workspace 是会被 rm 的。
      *  ⚠️ 这是 **host-only**:k8s/local-docker 的临时文件必须落在**容器内**可见的 cwd,ssh/e2b 本来就用远端系统 tmp。 */
+    /** S-539(写面一律 `withInflightFs`,见那处头注)。这一面建在 **spool 根**下,而 destroy 也会整树删那个根 ——
+     *  `fs.mkdtemp` 不建父目录,所以它不会复活什么,坏处是一次本该成功的调用返回 `not_found`。 */
     createTempDir(prefix?: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
+    /** S-539(写面一律 `withInflightFs`,见那处头注;spool 根同 `createTempDir`)。 */
     createTempFile(options?: {
         prefix?: string;
         suffix?: string;

package/dist/plugins/remote-env-host.js

@@ -14,6 +14,7 @@ import { recordSecretEnvScrub } from "../observability/secret-env-scrub.js";
 import { trackEphemeralHostWorkspace, untrackEphemeralHostWorkspace } from "./host-workspace-registry.js";
 const PROVIDER = "host";
 const DEFAULT_COMMAND_TIMEOUT_MS = 30 * 60_000;
+const inflightFsDrainWaitMs = () => numEnvOr("HOST_FS_DRAIN_WAIT_MS", 10_000, 1);
 const HOST_BG_MAX_CONCURRENT = numEnvOr("HOST_BG_MAX_CONCURRENT", 8, 1);
 const HOST_BG_DEFAULT_TIMEOUT_SEC = numEnvOr("HOST_BG_DEFAULT_TIMEOUT_SEC", 300, 1);
 const HOST_BG_MAX_TIMEOUT_SEC = numEnvOr("HOST_BG_MAX_TIMEOUT_SEC", 1800, HOST_BG_DEFAULT_TIMEOUT_SEC);
@@ -62,6 +63,41 @@ export class RemoteHostExecutionEnv {
     destroyed = false;
     spoolRootDir;
     liveFgSpools = new Set();
+    inflightFs = new Set();
+    inflightFsDrainWarned = false;
+    withInflightFs(fn) {
+        const p = fn();
+        this.inflightFs.add(p);
+        const forget = () => void this.inflightFs.delete(p);
+        void p.then(forget, forget);
+        return p;
+    }
+    async drainInflightFs(inflight) {
+        if (inflight.length === 0)
+            return true;
+        const settled = Promise.allSettled(inflight);
+        const waitMs = inflightFsDrainWaitMs();
+        const timedOut = Symbol("inflight-fs-drain-timeout");
+        let timer;
+        const deadline = new Promise((resolve) => {
+            timer = setTimeout(() => resolve(timedOut), waitMs);
+            timer.unref?.();
+        });
+        try {
+            const drained = (await Promise.race([settled, deadline])) !== timedOut;
+            if (!drained && !this.inflightFsDrainWarned) {
+                this.inflightFsDrainWarned = true;
+                console.warn(`RemoteHostExecutionEnv.destroy: ${this.inflightFs.size} in-flight filesystem write(s) did not settle within ` +
+                    `${waitMs}ms — returning from teardown now; removal of ${this.workspaceDir} stays ordered AFTER those writes ` +
+                    `and will land when they finish (a write that never settles, e.g. a FIFO target inside the workspace, defers it)`);
+            }
+            return drained;
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
     ensureSpoolRoot() {
         if (!this.spoolRootDir)
             this.spoolRootDir = mkdtempSync(path.join(os.tmpdir(), "sema-host-spool-"));
@@ -130,25 +166,32 @@ export class RemoteHostExecutionEnv {
         this.destroyed = true;
         const p = this.preparing;
         this.preparing = undefined;
+        const inflight = [...this.inflightFs];
         try {
             await p?.catch(() => { });
         }
         finally {
-            if (this.spoolRootDir && !this.bgManager.hasShells() && this.liveFgSpools.size === 0) {
-                try {
-                    await fs.rm(this.spoolRootDir, { recursive: true, force: true });
-                }
-                catch { }
-                this.spoolRootDir = undefined;
-            }
-            if (this.persistent)
-                return;
+            if (await this.drainInflightFs(inflight))
+                await this.removeOwnedTrees();
+            else
+                void Promise.allSettled(inflight).then(() => this.removeOwnedTrees());
+        }
+    }
+    async removeOwnedTrees() {
+        if (this.spoolRootDir && !this.bgManager.hasShells() && this.liveFgSpools.size === 0) {
             try {
-                await fs.rm(this.workspaceDir, { recursive: true, force: true });
-                untrackEphemeralHostWorkspace(this.workspaceDir);
-            }
-            catch {
+                await fs.rm(this.spoolRootDir, { recursive: true, force: true });
             }
+            catch { }
+            this.spoolRootDir = undefined;
+        }
+        if (this.persistent)
+            return;
+        try {
+            await fs.rm(this.workspaceDir, { recursive: true, force: true });
+            untrackEphemeralHostWorkspace(this.workspaceDir);
+        }
+        catch {
         }
     }
     async cleanup() {
@@ -905,37 +948,41 @@ export class RemoteHostExecutionEnv {
             return { ok: false, error: this.fileError(e, abs, abortSignal) };
         }
     }
-    async writeFile(p, content, abortSignal) {
-        const ready = await this.fsReady(p);
-        if (!ready.ok)
-            return ready;
-        const abs = this.resolve(p);
-        try {
-            await fs.mkdir(path.dirname(abs), { recursive: true });
-            const data = typeof content === "string" ? content : Buffer.from(content);
-            await fs.writeFile(abs, data, { signal: abortSignal });
-            return ok(undefined);
-        }
-        catch (e) {
-            return { ok: false, error: this.fileError(e, abs, abortSignal) };
-        }
+    writeFile(p, content, abortSignal) {
+        return this.withInflightFs(async () => {
+            const ready = await this.fsReady(p);
+            if (!ready.ok)
+                return ready;
+            const abs = this.resolve(p);
+            try {
+                await fs.mkdir(path.dirname(abs), { recursive: true });
+                const data = typeof content === "string" ? content : Buffer.from(content);
+                await fs.writeFile(abs, data, { signal: abortSignal });
+                return ok(undefined);
+            }
+            catch (e) {
+                return { ok: false, error: this.fileError(e, abs, abortSignal) };
+            }
+        });
     }
-    async appendFile(p, content, abortSignal) {
-        const ready = await this.fsReady(p, { lingeringBgWrite: true });
-        if (!ready.ok)
-            return ready;
-        const abs = this.resolve(p);
-        try {
-            await fs.mkdir(path.dirname(abs), { recursive: true });
-            if (abortSignal?.aborted)
-                throw Object.assign(new Error("aborted"), { name: "AbortError" });
-            const data = typeof content === "string" ? content : Buffer.from(content);
-            await fs.appendFile(abs, data);
-            return ok(undefined);
-        }
-        catch (e) {
-            return { ok: false, error: this.fileError(e, abs, abortSignal) };
-        }
+    appendFile(p, content, abortSignal) {
+        return this.withInflightFs(async () => {
+            const ready = await this.fsReady(p, { lingeringBgWrite: true });
+            if (!ready.ok)
+                return ready;
+            const abs = this.resolve(p);
+            try {
+                await fs.mkdir(path.dirname(abs), { recursive: true });
+                if (abortSignal?.aborted)
+                    throw Object.assign(new Error("aborted"), { name: "AbortError" });
+                const data = typeof content === "string" ? content : Buffer.from(content);
+                await fs.appendFile(abs, data);
+                return ok(undefined);
+            }
+            catch (e) {
+                return { ok: false, error: this.fileError(e, abs, abortSignal) };
+            }
+        });
     }
     async fileInfo(p, abortSignal) {
         const ready = await this.fsReady(p);
@@ -1058,66 +1105,74 @@ export class RemoteHostExecutionEnv {
             return { ok: false, error: fe };
         }
     }
-    async createDir(p, options) {
-        const ready = await this.fsReady(p);
-        if (!ready.ok)
-            return ready;
-        const abs = this.resolve(p);
-        try {
-            await fs.mkdir(abs, { recursive: options?.recursive ?? true });
-            return ok(undefined);
-        }
-        catch (e) {
-            return { ok: false, error: this.fileError(e, abs, options?.abortSignal) };
-        }
-    }
-    async remove(p, options) {
-        const ready = await this.fsReady(p);
-        if (!ready.ok)
-            return ready;
-        const abs = this.resolve(p);
-        try {
-            if (!options?.force) {
-                await fs.lstat(abs);
+    createDir(p, options) {
+        return this.withInflightFs(async () => {
+            const ready = await this.fsReady(p);
+            if (!ready.ok)
+                return ready;
+            const abs = this.resolve(p);
+            try {
+                await fs.mkdir(abs, { recursive: options?.recursive ?? true });
+                return ok(undefined);
             }
-            await fs.rm(abs, { recursive: options?.recursive ?? false, force: options?.force ?? false });
-            return ok(undefined);
-        }
-        catch (e) {
-            const fe = this.fileError(e, abs, options?.abortSignal);
-            if (options?.force && fe.code === "not_found")
+            catch (e) {
+                return { ok: false, error: this.fileError(e, abs, options?.abortSignal) };
+            }
+        });
+    }
+    remove(p, options) {
+        return this.withInflightFs(async () => {
+            const ready = await this.fsReady(p);
+            if (!ready.ok)
+                return ready;
+            const abs = this.resolve(p);
+            try {
+                if (!options?.force) {
+                    await fs.lstat(abs);
+                }
+                await fs.rm(abs, { recursive: options?.recursive ?? false, force: options?.force ?? false });
                 return ok(undefined);
-            return { ok: false, error: fe };
-        }
+            }
+            catch (e) {
+                const fe = this.fileError(e, abs, options?.abortSignal);
+                if (options?.force && fe.code === "not_found")
+                    return ok(undefined);
+                return { ok: false, error: fe };
+            }
+        });
     }
-    async createTempDir(prefix = "tmp-", abortSignal) {
-        const ready = await this.fsReady(".");
-        if (!ready.ok)
-            return ready;
-        try {
-            return ok(await fs.mkdtemp(path.join(this.ensureSpoolRoot(), prefix)));
-        }
-        catch (e) {
-            return { ok: false, error: this.fileError(e, this.workspaceDir, abortSignal) };
-        }
+    createTempDir(prefix = "tmp-", abortSignal) {
+        return this.withInflightFs(async () => {
+            const ready = await this.fsReady(".");
+            if (!ready.ok)
+                return ready;
+            try {
+                return ok(await fs.mkdtemp(path.join(this.ensureSpoolRoot(), prefix)));
+            }
+            catch (e) {
+                return { ok: false, error: this.fileError(e, this.workspaceDir, abortSignal) };
+            }
+        });
     }
-    async createTempFile(options) {
-        const ready = await this.fsReady(".");
-        if (!ready.ok)
-            return ready;
-        const prefix = options?.prefix ?? "";
-        const suffix = options?.suffix ?? "";
-        try {
-            const name = `${prefix}${randomBytes(8).toString("hex")}${suffix}`;
-            const abs = path.join(this.ensureSpoolRoot(), name);
-            if (options?.abortSignal?.aborted)
-                throw Object.assign(new Error("aborted"), { name: "AbortError" });
-            await fs.writeFile(abs, "", { flag: "wx" });
-            return ok(abs);
-        }
-        catch (e) {
-            return { ok: false, error: this.fileError(e, this.workspaceDir, options?.abortSignal) };
-        }
+    createTempFile(options) {
+        return this.withInflightFs(async () => {
+            const ready = await this.fsReady(".");
+            if (!ready.ok)
+                return ready;
+            const prefix = options?.prefix ?? "";
+            const suffix = options?.suffix ?? "";
+            try {
+                const name = `${prefix}${randomBytes(8).toString("hex")}${suffix}`;
+                const abs = path.join(this.ensureSpoolRoot(), name);
+                if (options?.abortSignal?.aborted)
+                    throw Object.assign(new Error("aborted"), { name: "AbortError" });
+                await fs.writeFile(abs, "", { flag: "wx" });
+                return ok(abs);
+            }
+            catch (e) {
+                return { ok: false, error: this.fileError(e, this.workspaceDir, options?.abortSignal) };
+            }
+        });
     }
     resolve(p) {
         return path.isAbsolute(p) ? path.normalize(p) : path.normalize(path.resolve(this.cwd, p));
@@ -1207,7 +1262,7 @@ export class RemoteHostExecutionEnv {
             const rel = path.relative(real(root), real(abs));
             return rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel);
         };
-        return inside(this.workspaceDir) || (this.spoolRootDir !== undefined && inside(this.spoolRootDir));
+        return (this.spoolRootDir !== undefined && inside(this.spoolRootDir)) || (this.persistent && inside(this.workspaceDir));
     }
     async fsReady(p, opts) {
         if (this.destroyed) {

package/dist/plugins/session-policy-store-sql.d.ts

@@ -25,9 +25,57 @@ export declare class SqlSessionPolicyStore implements SessionPolicyStore {
     listBySession(sessionId: string): Promise<SessionRulesRecord[]>;
     /** Operator/owner write: CAS + tighten-only (unless operator) + rev bump, atomic in one txn; first-write race retried. */
     putRules(sessionId: string, principal: string | undefined, rules: SessionPermissionRules, opts?: PutRulesOptions): Promise<StoredSessionRules>;
-    /** E21 purge — drop ALL policy rows for a session (every principal). Scoped by session_id (the route owner-gates).
-     *  Return shape aligned to core 1.423's optional interface seam (`Promise<void>`) — the affectedRows count was
-     *  incidental and unconsumed; the integration test asserts the post-state (listBySession empty) instead. */
+    /**
+     * The store's ONE retry arm: re-run the whole read-check-write transaction while the failure is an engine
+     * ARBITRATION artifact rather than an answer. Two such artifacts, and only two:
+     *  · **dup-key** — a concurrent FIRST write won the PK (no row ⇒ `FOR UPDATE` locked nothing). The re-read takes
+     *    the UPDATE/CAS path, which is core's serialized outcome; converting it to `conflict` in place would be a
+     *    spurious answer the caller can't tell from a real CAS loss.
+     *  · **deadlock** — the engine picked THIS transaction as the victim and already rolled it back. Which side gets
+     *    picked is arbitrary, so propagating it hands the caller an internal coin flip. 🔴 This arm is NOT a licence
+     *    for sloppy lock order: the order is still policy row → mark row on BOTH methods, and the oracle for it is
+     *    `test/sql-lock-shape-innodb-integration.test.ts` (site ⑩, three engines). It exists because on REAL InnoDB
+     *    (REPEATABLE READ) a `FOR UPDATE` read of a MISSING primary key takes a GAP lock, and gap locks are mutually
+     *    compatible while both block the other side's INSERT — so N concurrent first writes on one key deadlock NO
+     *    MATTER what order any table is touched in. Measured on the real engine (2026-09-20, S-529, 8-way race on
+     *    `main`'s statement sequence, zero mark table involved): InnoDB 1 winner / 7 `ER_LOCK_DEADLOCK`, TiDB 0,
+     *    PG 0 — i.e. this is a PRE-EXISTING MySQL-leg defect that S-529's lock-shape site made visible, not a new one.
+     *    After the first insert commits, the retried writers find the row and take the UPDATE path (record lock,
+     *    no gap) ⇒ the loop converges in one extra round per missing-row window; the bound is the suite's concurrency.
+     *  Lock-WAIT-TIMEOUT is deliberately NOT retried ({@link isDeadlockError}'s own note: it is a latency signal,
+     *  and retrying it multiplies an already-long wait).
+     */
+    private retrying;
+    /** E21 purge — drop ALL policy rows for a session (every principal), KEEPING each key's rev high-water mark.
+     *  Scoped by session_id (the route owner-gates). Return shape aligned to core 1.423's optional interface seam
+     *  (`Promise<void>`) — the affectedRows count was incidental and unconsumed; the integration test asserts the
+     *  post-state (listBySession empty) instead.
+     *
+     *  S-529 (`@contract session_policy.rev_survives_delete`): the rules ROW dies, the key's REV LINE does not, and the
+     *  erase ALSO ENDS THE ROW'S LINEAGE (`gen` + 1 — the next write on this key belongs to another generation, which no
+     *  reader treats as a continuation of the erased row whatever rev it wears) — one
+     *  transaction, three statements, and BOTH the order and the locking verb are load-bearing:
+     *   ① `SELECT … ORDER BY policy_key FOR UPDATE` — the rows to erase are read and X-LOCKED first, in a DETERMINISTIC
+     *      order. This is the SAME lock order putRules uses (policy row → mark row), which is the whole point: the
+     *      obvious shape (`INSERT … SELECT` the marks, then DELETE) locks the MARK first and takes only a SHARED lock
+     *      on the policy rows it reads, i.e. a reversed order PLUS an S→X upgrade — the textbook deadlock this repo
+     *      已经吃过两次(retention-store-sql.ts ④a/④b 的 S-131 案:一边持 boundary 等哨兵,一边持哨兵等 boundary)。
+     *   ② the marks (their revs come from ①'s already-locked rows) — `GREATEST` merge, so a mark only ever RISES and
+     *      repeated erases never walk the line back.
+     *   ③ the DELETE — scoped to ①'s POLICY_KEY SET, never re-scanned by `session_id`. 🔴 This is the whole of
+     *      codex r1 [high] #1 (verified, not rebutted): both engines re-evaluate a `WHERE session_id = ?` DELETE
+     *      against a CURRENT read (PG is pinned to READ COMMITTED, TiDB's DML is a current read), so a row for a
+     *      DIFFERENT principal that a concurrent putRules commits BETWEEN ① and ③ would be deleted by a session-wide
+     *      DELETE while ② never marked it — a silently reset rev line, exactly the defect this batch exists to close.
+     *      Scoped to the key set, the invariant is exact and checkable: **every row this seam deletes leaves a mark**.
+     *      A row born after ① is simply not part of this erase (same as one born a microsecond after ③ — the caller
+     *      that needs "and nothing came back" re-issues; the seam is idempotent).
+     *  No rows ⇒ return early: an erase of a session that never had rules writes NO mark (no line, nothing to keep),
+     *  which is what makes a repeated/empty delete idempotent instead of resurrecting a mark.
+     *  Why the mark is a separate table and not a tombstone row: see the DDL comment in tidb-pool.ts — a tombstone
+     *  would keep `session_id` + the DENORMALIZED plaintext `principal` in the table after an E21 purge, i.e. the
+     *  right-to-delete would degrade to buy rev ordering. The mark keeps only the one-way hash, the session id and
+     *  an integer. */
     deleteBySession(sessionId: string): Promise<void>;
     /**
      * The store's one read-check-write transaction. Its load-bearing read is line ~106's

package/dist/plugins/session-policy-store-sql.js

@@ -2,10 +2,22 @@ import { createHash } from "node:crypto";
 import { loosenReasons, SessionPolicyError, normalizeRules, stripRev } from "@sema-agent/core";
 import { pgHasUnstorable } from "./pg-safe-json.js";
 import { mysqlDriver, pgDriver } from "./sql-driver.js";
-import { isDupKeyError } from "./sql-errors.js";
+import { isDeadlockError, isDupKeyError } from "./sql-errors.js";
 export const policyKeyFor = (sessionId, principal) => createHash("sha256").update(JSON.stringify([sessionId, principal ?? null])).digest("hex");
 const policyKey = policyKeyFor;
+const RETRY_LIMIT = 8;
 const parseRules = (v) => (typeof v === "string" ? JSON.parse(v) : v);
+function rowToStored(r, where) {
+    const rev = Number(r.rev);
+    if (!Number.isFinite(rev) || !Number.isInteger(rev) || rev < 1) {
+        throw new SessionPolicyError("corrupt", `session rules row ${where} carries rev ${String(r.rev)} — a stored row's rev is always ≥ 1 (the stamp is floor+1), and rev 0 is the live reader's synthetic empty seed; refusing rather than serve it as rules`);
+    }
+    const gen = Number(r.gen ?? 0);
+    if (!Number.isFinite(gen) || !Number.isInteger(gen) || gen < 0) {
+        throw new SessionPolicyError("corrupt", `session rules row ${where} carries lineage gen ${String(r.gen)} — a generation is a whole number ≥ 0; refusing rather than let a reader judge lineage by a value nothing minted`);
+    }
+    return { ...parseRules(r.rules), rev, gen };
+}
 export class SqlSessionPolicyStore {
     db;
     constructor(db) {
@@ -18,62 +30,89 @@ export class SqlSessionPolicyStore {
         return isDupKeyError(this.db.dialect, e);
     }
     async getRules(sessionId, principal) {
-        const { rows } = await this.db.query(this.q("SELECT rules, rev FROM session_policy WHERE policy_key = ?", "SELECT rules, rev FROM session_policy WHERE policy_key = $1"), [policyKey(sessionId, principal)]);
+        const { rows } = await this.db.query(this.q("SELECT rules, rev, gen FROM session_policy WHERE policy_key = ?", "SELECT rules, rev, gen FROM session_policy WHERE policy_key = $1"), [policyKey(sessionId, principal)]);
         if (!rows[0])
             return null;
-        return { ...parseRules(rows[0].rules), rev: Number(rows[0].rev) };
+        return rowToStored(rows[0], `for session ${JSON.stringify(sessionId)}`);
     }
     async listBySession(sessionId) {
-        const { rows } = await this.db.query(this.q("SELECT principal, rules, rev FROM session_policy WHERE session_id = ?", "SELECT principal, rules, rev FROM session_policy WHERE session_id = $1"), [sessionId]);
+        const { rows } = await this.db.query(this.q("SELECT principal, rules, rev, gen FROM session_policy WHERE session_id = ?", "SELECT principal, rules, rev, gen FROM session_policy WHERE session_id = $1"), [sessionId]);
         return rows.map((r) => ({
             principal: r.principal == null ? undefined : String(r.principal),
-            rules: { ...parseRules(r.rules), rev: Number(r.rev) },
+            rules: rowToStored(r, `for session ${JSON.stringify(sessionId)} (enumeration)`),
         }));
     }
     async putRules(sessionId, principal, rules, opts) {
         const key = policyKey(sessionId, principal);
-        for (let attempt = 0;; attempt++) {
+        return this.retrying(() => this.tx(async (conn) => {
+            const { rows } = await conn.query(this.q("SELECT rules, rev, gen FROM session_policy WHERE policy_key = ? FOR UPDATE", "SELECT rules, rev, gen FROM session_policy WHERE policy_key = $1 FOR UPDATE"), [key]);
+            const prior = rows[0] ? rowToStored(rows[0], `for session ${JSON.stringify(sessionId)} (pre-write snapshot)`) : undefined;
+            const priorRev = prior?.rev ?? 0;
+            if (opts?.expectedRev !== undefined && priorRev !== opts.expectedRev) {
+                throw new SessionPolicyError("conflict", `session rules rev mismatch (expected ${opts.expectedRev}, have ${priorRev})`);
+            }
+            const { rows: markRows } = await conn.query(this.q("SELECT rev, gen FROM session_policy_rev_mark WHERE policy_key = ? FOR UPDATE", "SELECT rev, gen FROM session_policy_rev_mark WHERE policy_key = $1 FOR UPDATE"), [key]);
+            const markRev = markRows[0] ? Number(markRows[0].rev) : 0;
+            const markGen = markRows[0] ? Number(markRows[0].gen) : 0;
+            if (markRows[0] !== undefined && (!Number.isInteger(markGen) || markGen < 0 || !Number.isFinite(markRev) || markRev < 0)) {
+                throw new SessionPolicyError("corrupt", `the session rules rev mark for session ${JSON.stringify(sessionId)} is unreadable (rev ${String(markRows[0].rev)}, gen ${String(markRows[0].gen)}) — refusing rather than stamp a rev/lineage nothing proves`);
+            }
+            const clean = normalizeRules(stripRev(rules));
+            if (prior && opts?.operator !== true) {
+                const loosens = loosenReasons(prior, clean);
+                if (loosens.length > 0) {
+                    throw new SessionPolicyError("loosen_forbidden", `a non-operator session-rule write may only tighten; refused: ${loosens.join("; ")}`);
+                }
+            }
+            if (this.db.dialect === "pg" && pgHasUnstorable(clean)) {
+                throw new SessionPolicyError("loosen_forbidden", "rules contain unstorable bytes (NUL / lone surrogate) — refused; strip them at the source (authorization rules are never rewritten by the store)");
+            }
+            const nextRev = Math.max(priorRev, markRev) + 1;
+            const nextGen = prior?.gen ?? markGen;
+            const json = JSON.stringify(clean);
+            const now = new Date();
+            if (prior) {
+                const upd = await conn.query(this.q("UPDATE session_policy SET principal = ?, rules = ?, rev = ?, gen = ?, updated_at = ? WHERE policy_key = ? AND rev = ?", "UPDATE session_policy SET principal = $1, rules = $2::jsonb, rev = $3, gen = $4, updated_at = $5 WHERE policy_key = $6 AND rev = $7"), [principal ?? null, json, nextRev, nextGen, now, key, priorRev]);
+                if (upd.affected !== 1)
+                    throw new SessionPolicyError("conflict", `session rules rev mismatch (expected ${opts?.expectedRev ?? priorRev}, have ${priorRev})`);
+            }
+            else {
+                await conn.query(this.q("INSERT INTO session_policy (policy_key, session_id, principal, rules, rev, gen, created_at, updated_at) VALUES (?,?,?,?,?,?,?,?)", "INSERT INTO session_policy (policy_key, session_id, principal, rules, rev, gen, created_at, updated_at) VALUES ($1,$2,$3,$4::jsonb,$5,$6,$7,$8)"), [key, sessionId, principal ?? null, json, nextRev, nextGen, now, now]);
+            }
+            return structuredClone({ ...clean, rev: nextRev, gen: nextGen });
+        }));
+    }
+    async retrying(attempt) {
+        for (let tries = 0;; tries++) {
             try {
-                return await this.tx(async (conn) => {
-                    const { rows } = await conn.query(this.q("SELECT rules, rev FROM session_policy WHERE policy_key = ? FOR UPDATE", "SELECT rules, rev FROM session_policy WHERE policy_key = $1 FOR UPDATE"), [key]);
-                    const prior = rows[0] ? { rules: parseRules(rows[0].rules), rev: Number(rows[0].rev) } : undefined;
-                    const priorRev = prior?.rev ?? 0;
-                    if (opts?.expectedRev !== undefined && priorRev !== opts.expectedRev) {
-                        throw new SessionPolicyError("conflict", `session rules rev mismatch (expected ${opts.expectedRev}, have ${priorRev})`);
-                    }
-                    const clean = normalizeRules(stripRev(rules));
-                    if (prior && opts?.operator !== true) {
-                        const loosens = loosenReasons(prior.rules, clean);
-                        if (loosens.length > 0) {
-                            throw new SessionPolicyError("loosen_forbidden", `a non-operator session-rule write may only tighten; refused: ${loosens.join("; ")}`);
-                        }
-                    }
-                    if (this.db.dialect === "pg" && pgHasUnstorable(clean)) {
-                        throw new SessionPolicyError("loosen_forbidden", "rules contain unstorable bytes (NUL / lone surrogate) — refused; strip them at the source (authorization rules are never rewritten by the store)");
-                    }
-                    const nextRev = priorRev + 1;
-                    const json = JSON.stringify(clean);
-                    const now = new Date();
-                    if (prior) {
-                        const upd = await conn.query(this.q("UPDATE session_policy SET principal = ?, rules = ?, rev = ?, updated_at = ? WHERE policy_key = ? AND rev = ?", "UPDATE session_policy SET principal = $1, rules = $2::jsonb, rev = $3, updated_at = $4 WHERE policy_key = $5 AND rev = $6"), [principal ?? null, json, nextRev, now, key, priorRev]);
-                        if (upd.affected !== 1)
-                            throw new SessionPolicyError("conflict", `session rules rev mismatch (expected ${opts?.expectedRev ?? priorRev}, have ${priorRev})`);
-                    }
-                    else {
-                        await conn.query(this.q("INSERT INTO session_policy (policy_key, session_id, principal, rules, rev, created_at, updated_at) VALUES (?,?,?,?,?,?,?)", "INSERT INTO session_policy (policy_key, session_id, principal, rules, rev, created_at, updated_at) VALUES ($1,$2,$3,$4::jsonb,$5,$6,$7)"), [key, sessionId, principal ?? null, json, nextRev, now, now]);
-                    }
-                    return structuredClone({ ...clean, rev: nextRev });
-                });
+                return await attempt();
             }
             catch (e) {
-                if (this.isDupKey(e) && attempt < 4)
+                if (tries < RETRY_LIMIT && (this.isDupKey(e) || isDeadlockError(this.db.dialect, e)))
                     continue;
                 throw e;
             }
         }
     }
     async deleteBySession(sessionId) {
-        await this.db.query(this.q("DELETE FROM session_policy WHERE session_id = ?", "DELETE FROM session_policy WHERE session_id = $1"), [sessionId]);
+        await this.retrying(() => this.tx(async (conn) => {
+            const { rows } = await conn.query(this.q("SELECT policy_key, rev, gen FROM session_policy WHERE session_id = ? ORDER BY policy_key FOR UPDATE", "SELECT policy_key, rev, gen FROM session_policy WHERE session_id = $1 ORDER BY policy_key FOR UPDATE"), [sessionId]);
+            if (rows.length === 0)
+                return;
+            const now = new Date();
+            const keys = rows.map((r) => String(r.policy_key));
+            const params = [];
+            const tuples = rows.map((r) => {
+                params.push(String(r.policy_key), sessionId, Number(r.rev), Number(r.gen ?? 0) + 1, now);
+                const base = params.length - 5;
+                return this.db.dialect === "tidb" ? "(?,?,?,?,?)" : `($${base + 1},$${base + 2},$${base + 3},$${base + 4},$${base + 5})`;
+            });
+            await conn.query(this.q(`INSERT INTO session_policy_rev_mark (policy_key, session_id, rev, gen, erased_at) VALUES ${tuples.join(",")}` +
+                " ON DUPLICATE KEY UPDATE rev = GREATEST(session_policy_rev_mark.rev, VALUES(rev)), gen = GREATEST(session_policy_rev_mark.gen + 1, VALUES(gen)), erased_at = VALUES(erased_at)", `INSERT INTO session_policy_rev_mark (policy_key, session_id, rev, gen, erased_at) VALUES ${tuples.join(",")}` +
+                " ON CONFLICT (policy_key) DO UPDATE SET rev = GREATEST(session_policy_rev_mark.rev, EXCLUDED.rev), gen = GREATEST(session_policy_rev_mark.gen + 1, EXCLUDED.gen), erased_at = EXCLUDED.erased_at"), params);
+            const holes = keys.map((_, i) => (this.db.dialect === "tidb" ? "?" : `$${i + 1}`)).join(",");
+            await conn.query(`DELETE FROM session_policy WHERE policy_key IN (${holes})`, keys);
+        }));
     }
     async tx(fn) {
         const conn = await this.db.connect();