@sema-agent/server 7.12.0 → 7.14.0

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

@@ -22,7 +22,10 @@
  * An in-memory INDEX (the same Maps MemoryRunStore holds) is hydrated on construction by scanning each runs/<taskId>/
  * run.json + the active claim files — so listRuns/listSessions/getActiveTaskId are O(in-mem) with byte-identical keyset sort to the SQL/Memory
  * twins. Every write touches BOTH the disk and the index on one path. Single-process (the FileStorageBackend boot lock
- * guarantees one writer per data dir), so there is no per-op lock. The checkpoint-coupled suspended-run reapers run
+ * guarantees one writer per data dir), so there is no per-op lock — with ONE exception: #213's claim acquisition
+ * (`withClaimLock`) runs under a per-session in-process critical section, because judging a claim stale involves
+ * awaits (the checkpoint probe) and the claim + run row must commit as one unit (the SQL twin's transaction). The
+ * checkpoint-coupled suspended-run reapers run
  * off an injected {@link RunStoreCheckpointProbe} ([868]; wired by the local backend where checkpoint + run store
  * share one root) and degrade to honest no-ops when the probe is absent — exactly like MemoryRunStore.
  */
@@ -45,6 +48,10 @@ export declare class FileRunStore {
     /** [868] the checkpoint-table stand-in (see memory-run-store.ts {@link RunStoreCheckpointProbe} — the full
      *  rationale lives on the interface); absent ⇒ the suspended-run reapers stay honest NO-OPs. */
     private checkpointProbe?;
+    /** #213 —— 本实例的 claim 身份(见 {@link ClaimOwner} 的选型注)。 */
+    private readonly claimOwner;
+    /** #213 —— sessionId → 该会话 claim 获取的临界区链尾(见 {@link withClaimLock})。 */
+    private readonly claimLocks;
     constructor(root: string);
     private runDir;
     private runJsonPath;
@@ -73,6 +80,8 @@ export declare class FileRunStore {
         ok: false;
         activeTaskId: string;
     }>;
+    /** #213 —— createRun 临界区的后半段:落 claim 索引 + run 行(两者一体,行写失败即回滚 claim)。 */
+    private commitNewRun;
     requestCancel(taskId: string, owner: string | null): Promise<boolean>;
     isCancelRequested(taskId: string, owner: string | null): Promise<boolean>;
     requestPreempt(taskId: string, owner: string | null): Promise<boolean>;
@@ -179,6 +188,81 @@ export declare class FileRunStore {
      * pending gate is excluded by the NOT-pending clause).
      */
     failSuspendedWithExpiredCheckpoint(): Promise<number>;
+    /**
+     * #213 —— 裁定/接管路径上唯一许可的取行方式:**盘优先**,盘上没有才回退内存索引。
+     *
+     * 复审 R2 [high]:反过来(索引优先)会在「同进程两只实例、两边索引都热」时出事 —— A 把 park 行
+     * `markResuming` 成 running 并消费掉 checkpoint,B 的索引里还留着**旧的 park 对象**;B 于是读不到
+     * 变化、拿自己那份陈旧对象通过复核,把 A 正在跑的行盖成 failed 再放锁。盘是唯一权威,判据只能读盘。
+     * 回退内存索引只为「行还没落盘」这一种形(理论上不该出现,留着不让判据凭空缺行)。
+     * 代价:只在 EEXIST 争用路径上多一次读文件,常路零开销。
+     */
+    private authoritativeRow;
+    /** #213 —— 越过内存索引直接读盘上的那一行(索引可能比另一实例的写晚一步;判据必须以盘为准)。
+     *  读不出/坏行 ⇒ undefined,与 hydrate 的跳过口径一致。 */
+    private readRowFromDisk;
+    /**
+     * A1/codex R2 —— 盘上扫该会话最新的非终局行:撕裂 claim(解析不出记录)唯一还能认主的通道。
+     * 内存索引不可用作判据 —— 同进程冷索引姊妹实例的行可能晚于本实例 hydrate 才落盘(L9/[1684] 同族),
+     * 判据必须以盘为准。O(盘上 run 数),只在「claim 解析不出记录」这条罕见路径上走,常路零开销。
+     * 行的读法与 hydrate/readRowFromDisk 同一套宽容口径(坏行跳过,不毒判定)。
+     */
+    private newestNonTerminalRowOnDisk;
+    /** 本进程要落盘的 claim 形(带持有者身份 —— #213 的活性证据)。 */
+    private claimRecord;
+    /**
+     * #213 —— **每会话**的 claim 获取临界区。
+     *
+     * 为什么必须有:接管的判定链里有 `await`(checkpoint probe 的两条 EXISTS 谓词),两条并发 `createRun`
+     * 会在同一枚陈旧 claim 上**各判各的**、然后**各接管各的** —— 第二条的 `rename` 搬走的是第一条刚写下的
+     * **新** claim,于是两条都拿到 ok:true,单活不变式被并发撕开。(这不是纸面推演:L7 那一格先红,就是
+     * 这条路径。`rename` 只保证「同一个源路径只成功一次」,它**不是**对被判定那份内容的 CAS。)
+     *
+     * 为什么进程内互斥就够:这条车道是「一个数据根一个写者」——`FileStorageBackend` 的 `root/LOCK` 让第二个
+     * 活进程 fail fast。跨进程并发在本车道**不存在**;而这正是接管判据本身所依赖的同一条不变式
+     * (`reclaimOrphanedAtBoot` 也全靠它),所以这里没有引入新的假设。`rename` 仍然留着当廉价二道闸:
+     * 判定与接管之间 claim 若已被别腿正常释放,它给 ENOENT,整轮重来。
+     *
+     * 形状:每 session 一条 promise 链,后来者 await 前一位;链尾归零时删表项(不无界增长)。
+     */
+    private withClaimLock;
+    /** #213 —— 临界区内的 claim 获取本体:铸不下就裁定持有者,判陈旧则接管后重铸。有界重试(论证见 takeOverClaim)。 */
+    private acquireClaim;
+    /**
+     * #213 —— 撞上 EEXIST 之后,对**现持有者**的裁定。默认方向是 `live`(挡住):只有能**证明**
+     * 持有者已死的形才判 `stale`。证不出来一律 fail-closed —— 单活不变式比自愈更重要。
+     *
+     * 三族:
+     *  ① 行不在 / 行已终局 —— claim 是残骸(R9 回滚失手、跨进程窗)。`sweepClaims` 本该收掉,
+     *     它只在 boot 与几条 reaper 上跑;这里就地补齐。
+     *  ② 行 `running` —— 有没有在飞的驱动腿,取决于**谁**写的这枚 claim:本进程写的 ⇒ 驱动腿就在
+     *     本进程内存里 ⇒ 真活主;别的进程写的 ⇒ 那个进程已死(boot 单写者锁作证)⇒ 驱动腿随它一起没了,
+     *     行永远不会自己走到终局。这与 `reclaimOrphanedAtBoot` 的判决**逐字同源**,只是时点不同。
+     *  ③ 行 `suspended`/`needs_review`(park)—— park 按契约**没有在飞的腿**(腿返回 suspended 后就退出了,
+     *     resume 腿会先 `markResuming` 翻回 running),所以这一族与「谁写的」无关,只问一件事:
+     *     **还有东西可续吗**。有 pending ⇒ 可续(409 体里的 pendingGate 就是出路);有 expired ⇒ 归
+     *     [868] `failSuspendedWithExpiredCheckpoint` 那条腿收(它要落 `approval.expired` 这个终局语义,
+     *     本函数不许抢);两者皆无 ⇒ 这条 park 谁也续不动,而**没有任何一条排期腿够得着它**
+     *     (reapStale 只碰 running;boot 回收刻意跳过 park;时间腿 reapSuspended 挂 APPROVAL_TIMEOUT_SEC,
+     *     默认 0 = 不排期)⇒ 永久占用,判 stale。probe 缺席 ⇒ 证不出「无可续」⇒ fail-closed 判 live。
+     */
+    private judgeClaim;
+    /**
+     * #213 —— 接管一枚已判定陈旧的 claim。返回 false = 现场已经变了 / 抢输了,调用方整轮重来。
+     * **整段同步**(无 await)⇒ 进程内不可被打断;跨进程由 rename 与单写者锁兜。
+     *
+     * ① **复核先行**(复审 codex R1 [critical]):judgeClaim 的 probe await 期间,resume 腿可能已经
+     *    `markResuming`、终局腿可能已经放锁重铸。所以第一件事是拿判定时的快照逐字比对**盘上现状**
+     *    (claim 的 taskId+owner nonce、行的 status+updatedAt)。任何一项动了 ⇒ 判决作废,不许动手。
+     * ② **先把行写死,再拆 claim**(复审 codex R1 [medium]):次序反过来的话,「claim 已拆、行还 park」
+     *    这半拍崩溃会留下一条**永远 park** 的行 —— boot 回收刻意跳过 park、sweepClaims 又没有 claim 可循,
+     *    没人收得掉。现在的次序里,同一处崩溃留下的是「行已终局 + claim 还在」,而那正是 `sweepClaims`
+     *    每次 boot / 每条 reaper 都会扫掉的形 —— 崩在哪一步都自愈。
+     * ③ 拆 claim 用 `renameSync(claim → tmp/隔离名)`:POSIX `rename` 对同一个源路径只可能**成功一次**,
+     *    并发的第二个 racer 拿 ENOENT。隔离件落在 `tmp/` 而不是 `runs/active/` —— `hydrate()` 把 activeDir 里的
+     *    **每个文件**都当 claim 读,隔离件留在那儿就等于把刚拆掉的幽灵在下次 boot 原样复活。
+     */
+    private takeOverClaim;
     /** Release a session's single-active claim: unlink the claim file + drop the index entry (idempotent). */
     private releaseClaim;
     /** Drop a run entirely (registry + event log + open fd + on-disk dir) — used by deleteBySession. */

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

@@ -22,16 +22,69 @@
  * An in-memory INDEX (the same Maps MemoryRunStore holds) is hydrated on construction by scanning each runs/<taskId>/
  * run.json + the active claim files — so listRuns/listSessions/getActiveTaskId are O(in-mem) with byte-identical keyset sort to the SQL/Memory
  * twins. Every write touches BOTH the disk and the index on one path. Single-process (the FileStorageBackend boot lock
- * guarantees one writer per data dir), so there is no per-op lock. The checkpoint-coupled suspended-run reapers run
+ * guarantees one writer per data dir), so there is no per-op lock — with ONE exception: #213's claim acquisition
+ * (`withClaimLock`) runs under a per-session in-process critical section, because judging a claim stale involves
+ * awaits (the checkpoint probe) and the claim + run row must commit as one unit (the SQL twin's transaction). The
+ * checkpoint-coupled suspended-run reapers run
  * off an injected {@link RunStoreCheckpointProbe} ([868]; wired by the local backend where checkpoint + run store
  * share one root) and degrade to honest no-ops when the probe is absent — exactly like MemoryRunStore.
  */
 import { projectUsageStats, USAGE_SCAN_LIMIT } from "../usage-analytics.js";
 import { join } from "node:path";
-import { existsSync, mkdirSync, readdirSync, rmSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, renameSync, rmSync } from "node:fs";
+import { randomBytes } from "node:crypto";
 import { AppendLog, atomicWriteFile, ensureDir, readJsonlRecords, sanitizePathComponent, writeThenLink } from "@sema-agent/core";
+import { recordFailOpen } from "../observability/fail-open.js";
 /** Null-safe owner equality — the JS twin of the SQL `owner <=> ?` guard (a legacy null-owner run matches owner=null). */
 const ownerEq = (a, b) => (a ?? null) === (b ?? null);
+/** 进程事实(取证列),模块加载时算一次。 */
+const PROCESS_FACTS = {
+    pid: process.pid,
+    startedAtMs: Date.now() - Math.round(process.uptime() * 1000),
+};
+/** 接管的有界重试次数:一次判定 + 一次接管后重铸 + 一次输掉竞争后的复判,3 次足够收敛(论证见 takeOverClaim)。 */
+const CLAIM_TAKEOVER_ATTEMPTS = 3;
+/**
+ * A1/codex R4 —— claim 记录的**有效形**读法(判定/接管/收口三处共用,与 hydrate 的收编守卫同一把尺)。
+ * 「可解析但缺键」(如 `{}` 整行)与零长/被撕是同一种损坏 —— 只认 `claim === undefined` 当撕裂会让
+ * 这形走可解析路径、持有者又从陈旧索引里猜(R3 修掉的遮蔽原样复发)。会话对不上号的记录同判无效
+ * (错位/拷贝进来的文件):认主一律回落盘上非终局行,那才是权威。
+ */
+/** core `sanitizePathComponent`(fs-atomic SAFE_COMPONENT)同一条规则的**布尔形**(codex R5):
+ *  它本体对不安全分量是 throw —— 判定腿要的是「无效 ⇒ 走恢复路」,不是「无效 ⇒ 每发 createRun 500」。
+ *  规则只可能比 core 更保守地漂(判无效 ⇒ 回落盘上认行,方向安全)。 */
+const SAFE_PATH_COMPONENT = /^[A-Za-z0-9_.-]+$/;
+const isSafePathComponent = (s) => s !== "" && s !== "." && s !== ".." && SAFE_PATH_COMPONENT.test(s);
+function readClaimRecord(recs, sessionId) {
+    const c = recs[recs.length - 1];
+    if (!c || typeof c.sessionId !== "string" || typeof c.taskId !== "string" || c.sessionId !== sessionId)
+        return undefined;
+    // 不安全的 taskId(`../x` 之类)当有效读会让 authoritativeRow 在 sanitize 处炸(codex R5)——同判无效。
+    if (!isSafePathComponent(c.taskId))
+        return undefined;
+    return c;
+}
+/**
+ * 「这个 pid 现在还在吗」—— 信号 0 探活,与 core 剪 `root/LOCK` 陈旧锁用的是同一条判据。
+ * 🔴 方向:只有 **ESRCH**(确凿不在)才回 false。EPERM = 进程存在但不归我管 ⇒ 回 true(在);
+ * 任何其它异常同样回 true —— 探测失败不许被读成「它死了」(那才是会错杀活主的方向)。
+ */
+function isPidAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return true; // 读不出像样的 pid ⇒ 无证据 ⇒ 按「在」处理(fail-closed)
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e.code !== "ESRCH";
+    }
+}
+/**
+ * park 孤儿的**静置线**(防竞态余量,不是判据本身 —— 判据是「无 checkpoint 可续」)。
+ * 见 judgeClaim 里 park 族那一段的红字注:它盖的是 decide 腿「解 checkpoint」与「markResuming」之间那一拍。
+ */
+const PARK_ORPHAN_SETTLE_MS = 30_000;
 export class FileRunStore {
     runsDir;
     activeDir;
@@ -47,6 +100,10 @@ export class FileRunStore {
     /** [868] the checkpoint-table stand-in (see memory-run-store.ts {@link RunStoreCheckpointProbe} — the full
      *  rationale lives on the interface); absent ⇒ the suspended-run reapers stay honest NO-OPs. */
     checkpointProbe;
+    /** #213 —— 本实例的 claim 身份(见 {@link ClaimOwner} 的选型注)。 */
+    claimOwner = { nonce: randomBytes(12).toString("hex"), ...PROCESS_FACTS };
+    /** #213 —— sessionId → 该会话 claim 获取的临界区链尾(见 {@link withClaimLock})。 */
+    claimLocks = new Map();
     constructor(root) {
         this.runsDir = join(root, "runs");
         this.activeDir = join(root, "runs", "active");
@@ -148,11 +205,67 @@ export class FileRunStore {
         catch {
             claims = [];
         }
+        // A1 幸存者索引(codex R1 [high]):撕裂 claim 只剩文件名可认 —— 文件名 = sanitize 后的会话名,
+        // 不可逆,所以对已 hydrate 的**非终局**行正向重算 sanitize 比对。撕的是文件,不是会话的占用语义:
+        // park 行跨重启刻意保锁、可续的 running 行 boot 回收也刻意保 —— 这些会话必须**收编回索引**而不是
+        // 当残骸解锁(解锁 = 新 run 与将来 resume 的旧 run 并飞,单活不变式被 boot 自己撕开)。
+        const nonTerminalBySanitizedSession = new Map();
+        for (const r of this.runs.values()) {
+            if (r.status !== "running" && r.status !== "suspended" && r.status !== "needs_review")
+                continue;
+            // sanitizePathComponent 对不安全分量是 THROW——坏 run.json(sessionId 非 string/带空格)在此
+            // 会把整个构造器炸死(boot 亡),违背文件头「坏行跳过,不毒 boot」承诺(增量重扫 [med] 拦下)。
+            // 同尺跳过:这种行进不了幸存者索引,其 claim 文件(若有)走无主隔离路——方向仍 fail-closed。
+            if (typeof r.sessionId !== "string" || !isSafePathComponent(r.sessionId))
+                continue;
+            const key = sanitizePathComponent(r.sessionId);
+            const prev = nonTerminalBySanitizedSession.get(key);
+            // 同会话多条非终局行不该存在(单活);真撞上取最新的一条,方向仍是 fail-closed(保锁)。
+            if (!prev || r.createdAt.getTime() > prev.createdAt.getTime())
+                nonTerminalBySanitizedSession.set(key, r);
+        }
         for (const sanitized of claims) {
-            const recs = readJsonlRecords(join(this.activeDir, sanitized));
+            const path = join(this.activeDir, sanitized);
+            const recs = readJsonlRecords(path);
             const claim = recs[recs.length - 1];
-            if (claim && typeof claim.sessionId === "string" && typeof claim.taskId === "string") {
+            // 与判定腿同一把尺(codex R5):不安全 taskId(`../x` 之类)不得进索引 —— 进了,后续任何
+            // authoritativeRow(taskId) 都在 sanitize 处炸(runDir throw ⇒ createRun 每发 500)。这种记录
+            // 与零长/缺键同判无效,落到下面的幸存者收编/隔离路。
+            if (claim && typeof claim.sessionId === "string" && typeof claim.taskId === "string" && isSafePathComponent(claim.taskId)) {
                 this.active.set(claim.sessionId, claim.taskId);
+                continue;
+            }
+            const survivor = nonTerminalBySanitizedSession.get(sanitized);
+            if (survivor) {
+                // 幸存者在 ⇒ 只收编、不裁死活:死不死轮不到 hydrate 裁 —— checkpoint 面(isResumable/probe)
+                // 此刻还没接线,裁了必错杀可续行。收编之后一切既有腿照常工作:EEXIST ⇒ torn 裁定的
+                // 「索引里有」臂挡住并报真持有者;孤儿 running ⇒ reclaimOrphanedAtBoot(checkpoint 接好后
+                // 由 main.ts 驱动)裁;终局 ⇒ releaseClaim 连撕裂文件一并收走。文件本身不重写 —— 索引才是
+                // 运行期的判据面,重写一个正在被 EEXIST 依赖的文件反而引入新的失败形。
+                this.active.set(survivor.sessionId, survivor.taskId);
+                continue;
+            }
+            // A1(rescan 2026-08-11):解析不出记录(零长/被撕/缺键)**且无任何非终局行认领**的 claim 文件,
+            // 在 boot 这一刻可以无条件判残骸 —— 单写者锁作证没有并存的活写者(与 reclaimOrphanedAtBoot
+            // 同一条论证),而 writeThenLink 的原子性保证活写者留不下这种形。不收的话它进不了索引;
+            // sweepClaims 只扫索引,这枚文件从此无人能删,EEXIST 把该会话永远拦死(createRun 的 torn
+            // 裁定救得了新提交,救不了「残骸文件常驻 activeDir」本身)。隔离到 tmp(同 takeOverClaim 的
+            // 姿势):留证据,且绝不留在 activeDir 里等下次 hydrate 又把它当 claim 读一遍。
+            const quarantine = join(this.tmpDir, `torn-claim.${sanitized}.${process.pid}.${randomBytes(6).toString("hex")}`);
+            try {
+                renameSync(path, quarantine);
+            }
+            catch (e) {
+                if (e.code === "ENOENT")
+                    continue; // 已被并发腿收走 —— 目的已达
+                // 搬不动(EPERM/EIO…)再试直删;仍失败 = 残骸文件继续拦人,按 F 类留痕(同 tag:都是
+                // 「陈旧 claim 的清理没做成」这一种形),下次 boot 重试。
+                try {
+                    rmSync(path, { force: true });
+                }
+                catch {
+                    recordFailOpen("server.run-store.stale-claim-quarantine-unremoved", e instanceof Error ? e.message : String(e));
+                }
             }
         }
     }
@@ -176,19 +289,20 @@ export class FileRunStore {
     async createRun(taskId, sessionId, owner, instanceId, meta = {}) {
         // Atomic single-active claim: writeThenLink throws EEXIST if the claim already exists (the file twin of the
         // task_active unique key). The index is the fast-path read; the file is the authority on a concurrent create.
-        try {
-            writeThenLink(this.activePath(sessionId), `${JSON.stringify({ sessionId, taskId })}\n`);
-        }
-        catch (e) {
-            if (e.code === "EEXIST") {
-                // Recover the current holder from the claim file (the index may lag a concurrent winner, but in this
-                // single-process model the index is authoritative; read disk for robustness anyway).
-                const recs = readJsonlRecords(this.activePath(sessionId));
-                const holder = recs[recs.length - 1]?.taskId ?? this.active.get(sessionId) ?? "";
-                return { ok: false, activeTaskId: holder };
-            }
-            throw e;
-        }
+        // #213: an EEXIST no longer ends the story — the holder is ADJUDICATED (live vs dead-owner debris) and a
+        // provably-stale claim is TAKEN OVER.
+        // 🔴 **claim 与 run 行整段都在临界区里**(不只是取 claim 那一步)——SQL 孪生把两件事放在**一个事务**里,
+        // 本地车道的等价物就是这段临界区。只锁取 claim 会留下一个真窗:A 拿到 claim、行还没落盘时 B 就进来了,
+        // B 读到「有 claim 无行」⇒ 按残骸把 A 刚拿到的 claim 接管走 —— L7 那一格第二次红就是这条路径。
+        return this.withClaimLock(sessionId, async () => {
+            const acquired = await this.acquireClaim(sessionId, taskId);
+            if (!acquired.ok)
+                return acquired;
+            return this.commitNewRun(taskId, sessionId, owner, instanceId, meta);
+        });
+    }
+    /** #213 —— createRun 临界区的后半段:落 claim 索引 + run 行(两者一体,行写失败即回滚 claim)。 */
+    commitNewRun(taskId, sessionId, owner, instanceId, meta) {
         this.active.set(sessionId, taskId);
         const now = new Date();
         try {
@@ -601,6 +715,325 @@ export class FileRunStore {
         return reaped;
     }
     // ── claim / run file lifecycle helpers ──
+    /**
+     * #213 —— 裁定/接管路径上唯一许可的取行方式:**盘优先**,盘上没有才回退内存索引。
+     *
+     * 复审 R2 [high]:反过来(索引优先)会在「同进程两只实例、两边索引都热」时出事 —— A 把 park 行
+     * `markResuming` 成 running 并消费掉 checkpoint,B 的索引里还留着**旧的 park 对象**;B 于是读不到
+     * 变化、拿自己那份陈旧对象通过复核,把 A 正在跑的行盖成 failed 再放锁。盘是唯一权威,判据只能读盘。
+     * 回退内存索引只为「行还没落盘」这一种形(理论上不该出现,留着不让判据凭空缺行)。
+     * 代价:只在 EEXIST 争用路径上多一次读文件,常路零开销。
+     */
+    authoritativeRow(taskId) {
+        return this.readRowFromDisk(taskId) ?? this.runs.get(taskId);
+    }
+    /** #213 —— 越过内存索引直接读盘上的那一行(索引可能比另一实例的写晚一步;判据必须以盘为准)。
+     *  读不出/坏行 ⇒ undefined,与 hydrate 的跳过口径一致。 */
+    readRowFromDisk(taskId) {
+        const path = this.runJsonPath(taskId);
+        if (!existsSync(path))
+            return undefined;
+        const rows = readJsonlRecords(path);
+        const disk = rows[rows.length - 1];
+        if (!disk || typeof disk.taskId !== "string")
+            return undefined;
+        if (typeof disk.createdAt !== "string" || Number.isNaN(Date.parse(disk.createdAt)) ||
+            typeof disk.updatedAt !== "string" || Number.isNaN(Date.parse(disk.updatedAt)))
+            return undefined;
+        return this.toRow(disk);
+    }
+    /**
+     * A1/codex R2 —— 盘上扫该会话最新的非终局行:撕裂 claim(解析不出记录)唯一还能认主的通道。
+     * 内存索引不可用作判据 —— 同进程冷索引姊妹实例的行可能晚于本实例 hydrate 才落盘(L9/[1684] 同族),
+     * 判据必须以盘为准。O(盘上 run 数),只在「claim 解析不出记录」这条罕见路径上走,常路零开销。
+     * 行的读法与 hydrate/readRowFromDisk 同一套宽容口径(坏行跳过,不毒判定)。
+     */
+    newestNonTerminalRowOnDisk(sessionId) {
+        // readdir 失败**不吞**(静默降级棘轮三问):吞成「无行」会把「证不出有行」读成「可接管」——
+        // 在单活轴上方向反了。真 fs 故障就让 createRun 响亮地抛(takeOverClaim 对非 ENOENT 同姿势)。
+        const names = readdirSync(this.runsDir);
+        let best;
+        for (const name of names) {
+            if (name === "active")
+                continue;
+            // 与 hydrate(:283)/readRowFromDisk 同一把尺:条目不是目录 / run.json 不在 ⇒ 跳过。
+            // 少了这行守卫时,runs/ 里任何非目录杂物(.DS_Store/._* 备份残件)会让 readJsonlRecords 抛
+            // ENOTDIR(core 只吞 ENOENT)⇒ torn 裁定路 500 且 torn claim 永不清理——「会话永钉」以更响的
+            // 形回归(7.13.0 发车前增量重扫 [high] 拦下)。上面「readdir 失败不吞」只管 readdirSync 本体。
+            const path = join(this.runsDir, name, "run.json");
+            if (!existsSync(path))
+                continue;
+            const rows = readJsonlRecords(path);
+            const disk = rows[rows.length - 1];
+            if (!disk || typeof disk.taskId !== "string" || disk.sessionId !== sessionId)
+                continue;
+            if (typeof disk.createdAt !== "string" || Number.isNaN(Date.parse(disk.createdAt)) ||
+                typeof disk.updatedAt !== "string" || Number.isNaN(Date.parse(disk.updatedAt)))
+                continue;
+            if (disk.status !== "running" && disk.status !== "suspended" && disk.status !== "needs_review")
+                continue;
+            const row = this.toRow(disk);
+            if (!best || row.createdAt.getTime() > best.createdAt.getTime())
+                best = row;
+        }
+        return best;
+    }
+    /** 本进程要落盘的 claim 形(带持有者身份 —— #213 的活性证据)。 */
+    claimRecord(sessionId, taskId) {
+        return { sessionId, taskId, owner: { ...this.claimOwner } };
+    }
+    /**
+     * #213 —— **每会话**的 claim 获取临界区。
+     *
+     * 为什么必须有:接管的判定链里有 `await`(checkpoint probe 的两条 EXISTS 谓词),两条并发 `createRun`
+     * 会在同一枚陈旧 claim 上**各判各的**、然后**各接管各的** —— 第二条的 `rename` 搬走的是第一条刚写下的
+     * **新** claim,于是两条都拿到 ok:true,单活不变式被并发撕开。(这不是纸面推演:L7 那一格先红,就是
+     * 这条路径。`rename` 只保证「同一个源路径只成功一次」,它**不是**对被判定那份内容的 CAS。)
+     *
+     * 为什么进程内互斥就够:这条车道是「一个数据根一个写者」——`FileStorageBackend` 的 `root/LOCK` 让第二个
+     * 活进程 fail fast。跨进程并发在本车道**不存在**;而这正是接管判据本身所依赖的同一条不变式
+     * (`reclaimOrphanedAtBoot` 也全靠它),所以这里没有引入新的假设。`rename` 仍然留着当廉价二道闸:
+     * 判定与接管之间 claim 若已被别腿正常释放,它给 ENOENT,整轮重来。
+     *
+     * 形状:每 session 一条 promise 链,后来者 await 前一位;链尾归零时删表项(不无界增长)。
+     */
+    async withClaimLock(sessionId, fn) {
+        const prev = this.claimLocks.get(sessionId);
+        let release = () => undefined;
+        const mine = new Promise((res) => {
+            release = res;
+        });
+        this.claimLocks.set(sessionId, mine);
+        if (prev)
+            await prev; // 前一位失败也不会卡住后一位:mine 在 finally 里无条件 release
+        try {
+            return await fn();
+        }
+        finally {
+            release();
+            if (this.claimLocks.get(sessionId) === mine)
+                this.claimLocks.delete(sessionId);
+        }
+    }
+    /** #213 —— 临界区内的 claim 获取本体:铸不下就裁定持有者,判陈旧则接管后重铸。有界重试(论证见 takeOverClaim)。 */
+    async acquireClaim(sessionId, taskId) {
+        for (let attempt = 0; attempt < CLAIM_TAKEOVER_ATTEMPTS; attempt += 1) {
+            try {
+                writeThenLink(this.activePath(sessionId), `${JSON.stringify(this.claimRecord(sessionId, taskId))}\n`);
+                return { ok: true };
+            }
+            catch (e) {
+                if (e.code !== "EEXIST")
+                    throw e;
+                // Recover the current holder from the claim file (the index may lag a concurrent winner, but in this
+                // single-process model the index is authoritative; read disk for robustness anyway).
+                // 有效形读法(readClaimRecord):缺键/错会话的记录读成 undefined ⇒ 走撕裂裁定的扫盘认主。
+                const claim = readClaimRecord(readJsonlRecords(this.activePath(sessionId)), sessionId);
+                const holder = claim?.taskId ?? this.active.get(sessionId) ?? "";
+                const verdict = await this.judgeClaim(sessionId, claim, holder);
+                if (verdict.kind === "live")
+                    return { ok: false, activeTaskId: verdict.holderTaskId ?? holder };
+                this.takeOverClaim(sessionId, verdict.reason, verdict.snapshot); // 复核不过/搬不动也重来一轮
+            }
+        }
+        // 预算用尽的收口(复审 R2 [medium]):最后一轮里**接管刚刚成功**时,循环已经没有回合去铸新 claim 了。
+        // 此时直接回 409 是**撒谎** —— 会话其实是空的,且 activeTaskId 只能给出空串,调用方连 attach 到谁都不知道。
+        // 所以先诚实地再铸一次;只有真的还被人占着(EEXIST)才报冲突,而且报的是**盘上真持有者**。
+        try {
+            writeThenLink(this.activePath(sessionId), `${JSON.stringify(this.claimRecord(sessionId, taskId))}\n`);
+            return { ok: true };
+        }
+        catch (e) {
+            if (e.code !== "EEXIST")
+                throw e;
+        }
+        const finalClaim = readClaimRecord(readJsonlRecords(this.activePath(sessionId)), sessionId);
+        return { ok: false, activeTaskId: finalClaim?.taskId ?? this.active.get(sessionId) ?? "" };
+    }
+    /**
+     * #213 —— 撞上 EEXIST 之后,对**现持有者**的裁定。默认方向是 `live`(挡住):只有能**证明**
+     * 持有者已死的形才判 `stale`。证不出来一律 fail-closed —— 单活不变式比自愈更重要。
+     *
+     * 三族:
+     *  ① 行不在 / 行已终局 —— claim 是残骸(R9 回滚失手、跨进程窗)。`sweepClaims` 本该收掉,
+     *     它只在 boot 与几条 reaper 上跑;这里就地补齐。
+     *  ② 行 `running` —— 有没有在飞的驱动腿,取决于**谁**写的这枚 claim:本进程写的 ⇒ 驱动腿就在
+     *     本进程内存里 ⇒ 真活主;别的进程写的 ⇒ 那个进程已死(boot 单写者锁作证)⇒ 驱动腿随它一起没了,
+     *     行永远不会自己走到终局。这与 `reclaimOrphanedAtBoot` 的判决**逐字同源**,只是时点不同。
+     *  ③ 行 `suspended`/`needs_review`(park)—— park 按契约**没有在飞的腿**(腿返回 suspended 后就退出了,
+     *     resume 腿会先 `markResuming` 翻回 running),所以这一族与「谁写的」无关,只问一件事:
+     *     **还有东西可续吗**。有 pending ⇒ 可续(409 体里的 pendingGate 就是出路);有 expired ⇒ 归
+     *     [868] `failSuspendedWithExpiredCheckpoint` 那条腿收(它要落 `approval.expired` 这个终局语义,
+     *     本函数不许抢);两者皆无 ⇒ 这条 park 谁也续不动,而**没有任何一条排期腿够得着它**
+     *     (reapStale 只碰 running;boot 回收刻意跳过 park;时间腿 reapSuspended 挂 APPROVAL_TIMEOUT_SEC,
+     *     默认 0 = 不排期)⇒ 永久占用,判 stale。probe 缺席 ⇒ 证不出「无可续」⇒ fail-closed 判 live。
+     */
+    async judgeClaim(sessionId, claim, holderTaskId) {
+        const owner = claim?.owner;
+        const who = owner
+            ? `pid ${owner.pid} started ${new Date(owner.startedAtMs).toISOString()}`
+            : "an owner-less claim (written before the liveness stamp existed)";
+        const torn = claim === undefined;
+        // 🔴 索引里没有 ≠ 行不存在:另一个实例在本实例 hydrate **之后**建的 run,只活在盘上。拿索引当判据
+        // 会把它读成「幽灵 claim」并抢走一个**真活主**的锁([1684] 的两实例并发格就是这条路)。以盘为准。
+        // 撕裂形跳过这次急切取行(holder 是索引猜的,可能陈旧甚至不安全)——撕裂臂里无条件扫盘认主。
+        let row = !torn && holderTaskId ? this.authoritativeRow(holderTaskId) : undefined;
+        let holder = holderTaskId;
+        // ── A1(rescan 2026-08-11 + codex R2 两条 [high]):claim 文件在(EEXIST 撞上了它)却解析不出任何
+        // 记录 = 「被撕的写」(readJsonlRecords 契约:零长=[],无尾换行的末行被丢)。撕的是**文件**,不是
+        // 会话的占用语义 —— 修前这形恒 fail-closed live 且 activeTaskId 为空、任何收割腿都够不着,会话被一枚
+        // 谁都删不掉的空文件永久钉死。裁定:唯一还能认主的通道是**行**,而行必须**以盘为准**(同进程冷索引
+        // 姊妹实例的行可能不在本实例内存里 —— L9/[1684] 冷索引形 × 外力截断的组合,codex R2 第二条)。
+        //  · 认出非终局行 ⇒ 把持有者当它,走下面与可解析 claim **同一套**裁定(park 族问可续性、running 族要
+        //    死亡证据;文件不可读 ⇒ 无 owner 证据 ⇒ running 族自然 fail-closed)。blanket-live 是反例:它会把
+        //    「无可续的老 park」这一 L2 形永久锁死,而它的可解析孪生早就该被接管(codex R2 第一条)。
+        //  · 认不出行:本实例索引在飞(claim 已铸、行未落的半拍)⇒ live;索引也没有 ⇒ 单写者不变式作证
+        //    (活写者只能是本进程,而本进程持有中的 claim 必在索引里)⇒ 死进程残骸,判 stale。
+        if (torn) {
+            // codex R3 [high]:认主**无条件**以盘上最新非终局行为准 —— 索引猜出来的 holder 可能是姊妹实例
+            // 缓存的**旧**持有者(行已终局):拿它当行会遮住接班的 park(409 报一个终局名字,替班行照 live
+            // 挡住,永锁)。索引只在「盘上无非终局行」时兜「claim 已铸、行未落」的本进程半拍。
+            row = this.newestNonTerminalRowOnDisk(sessionId);
+            if (row) {
+                holder = row.taskId; // 409 也要报得出真持有者(修前这形只能报空串)
+            }
+            else if (this.active.has(sessionId)) {
+                return { kind: "live", holderTaskId: this.active.get(sessionId) };
+            }
+            else {
+                return {
+                    kind: "stale",
+                    reason: "torn claim file (no parseable record — dead-writer debris) reclaimed",
+                    snapshot: { taskId: "", ownerNonce: undefined, status: undefined, updatedAtMs: undefined, torn: true },
+                };
+            }
+        }
+        // 判定链里的每个 await 都会让出事件循环 —— 复审(codex R1 [critical])的靶心:probe 期间 resume 腿
+        // 可能已经 `markResuming`(park→running)、终局腿可能已经放锁重铸。所以这里先取一份快照,接管前
+        // 必须**逐字复核**(见 takeOverClaim);任何一项动了就放手重来。同一条纪律在 reapSuspended 里
+        // 已经有先例(那处的 `snap` 复核),本函数照抄并把 **claim 身份**也一并纳入。
+        const snapshot = {
+            taskId: holder,
+            ownerNonce: owner?.nonce,
+            status: row?.status,
+            updatedAtMs: row?.updatedAt.getTime(),
+            ...(torn ? { torn: true } : {}),
+        };
+        /** live 判决统一带上真持有者(撕裂形的 holder 是从行认出来的,调用方的 claim 读数里没有它)。 */
+        const live = () => ({ kind: "live", ...(holder ? { holderTaskId: holder } : {}) });
+        // ── ③ park 族:与「谁写的」无关,只问「还有东西可续吗」 ──
+        if (row && (row.status === "suspended" || row.status === "needs_review")) {
+            const probe = this.checkpointProbe;
+            if (!probe)
+                return live(); // 无 checkpoint 面 ⇒ 证不出不可续 ⇒ 挡住
+            if (await probe.hasPending(row.sessionId))
+                return live(); // 可续的 park —— 用户的待决审批,绝不许抢
+            if (await probe.hasExpired(row.sessionId))
+                return live(); // expired 有专腿收(approval.expired),不越权
+            // 🔴 复审 R1 [critical] 的残余窗:decide 腿「解掉 checkpoint」与「markResuming」之间,行还是 park、
+            //    checkpoint 已不 pending —— 快照复核看不出区别。用一道**静置线**盖住它:只收「已经躺了
+            //    PARK_ORPHAN_SETTLE_MS 没人动过」的 park。这不是把 TTL 当修法(修法是「无 checkpoint 可续」
+            //    这条新谓词 —— 今天没有任何一条腿有它);静置线只是防竞态的余量,而它要清的占用本来是**无界**的,
+            //    多等 30 秒零代价。真要跨过它,得有一条 resume 腿在解 checkpoint 与 markResuming 之间卡满 30 秒。
+            if (Date.now() - row.updatedAt.getTime() < PARK_ORPHAN_SETTLE_MS)
+                return live();
+            return { kind: "stale", reason: `parked run (${row.status}) has no resumable checkpoint — claim reclaimed`, snapshot };
+        }
+        // ── ①② 非 park 族:判死之前必须有**正面死亡证据** ──
+        // 证据只有两种:(a) 这枚 claim 是**本实例**写的 —— 那我对它的驱动腿有完整的内存知识;
+        //              (b) 它是外来的,且 owner 的 pid **确凿不在了**(ESRCH)。
+        // 为什么不能只看 nonce:`root/LOCK` 保证的是「一个数据根一个活**进程**」,同一进程里再造第二只
+        // FileRunStore(测试/误配)并不违反它,而那第二只的 claim 背后是一个**活着的**驱动腿 —— 只看 nonce
+        // 就会把真活主抢走([1684] 两实例并发格 + 「claim 已落、行还没落」那半拍窗,两次都真红过)。
+        // 🔴 pid 复用在这里**不会造成误判**:方向是 fail-closed —— 只有「确凿不在」才判陈旧;pid 被复用 ⇒
+        //    探到「在」⇒ 判 live ⇒ 维持今天的 409(少愈一次,绝不错杀),boot 回收仍是兜底。EPERM(属于别的
+        //    用户)同样表示进程存在,按 live 处理。缺 owner 戳的老 claim 无证可查,同样 live —— 升级本身就是
+        //    一次重启,`reclaimOrphanedAtBoot`(它靠单写者锁,不需要逐 claim 的死亡证据)才是它的正经收口。
+        const mine = owner?.nonce === this.claimOwner.nonce;
+        const ownerGone = owner !== undefined && !isPidAlive(owner.pid);
+        if (!mine && !ownerGone)
+            return live(); // 撕裂形(owner 无从读起)也天然落在这臂:running 无死亡证据 ⇒ 挡住
+        if (!row)
+            return { kind: "stale", reason: `claim reclaimed: no run row for ${holder || "(unknown task)"} — ${who}`, snapshot };
+        if (row.status !== "running")
+            return { kind: "stale", reason: `claim reclaimed: holder already terminal (${row.status})`, snapshot };
+        // running:本实例写的 ⇒ 驱动腿就在本进程内存里 ⇒ 真活主(单活不变式在此守住)。
+        if (mine)
+            return live();
+        // 🔴 复审 R1 [high]:外来且 owner 已死 **仍不够** —— `reclaimOrphanedAtBoot` 刻意用
+        //    `isResumable(sessionId)`(= 该会话有 pending checkpoint)把一类 running 行留下来:
+        //    `markResuming` 会把 park 翻成 running,而它的 checkpoint 还没被消费,resume 挑选器会重新驱动它。
+        //    本函数是同一条判决的「晚一点的时点」,判据必须**逐字同源**,否则新提交会把一条 boot 特意保住的
+        //    行打成 failed、把用户还没决议的审批晾在那儿。
+        const probe = this.checkpointProbe;
+        if (probe && (await probe.hasPending(row.sessionId)))
+            return live();
+        // 外来 + owner 已死 + 无可续 ⇒ 驱动腿随那个进程没了,这行永远走不到终局 ⇒ 孤儿。
+        return { kind: "stale", reason: `run orphaned by engine restart (claim held by ${who}, which is gone)`, snapshot };
+    }
+    /**
+     * #213 —— 接管一枚已判定陈旧的 claim。返回 false = 现场已经变了 / 抢输了,调用方整轮重来。
+     * **整段同步**(无 await)⇒ 进程内不可被打断;跨进程由 rename 与单写者锁兜。
+     *
+     * ① **复核先行**(复审 codex R1 [critical]):judgeClaim 的 probe await 期间,resume 腿可能已经
+     *    `markResuming`、终局腿可能已经放锁重铸。所以第一件事是拿判定时的快照逐字比对**盘上现状**
+     *    (claim 的 taskId+owner nonce、行的 status+updatedAt)。任何一项动了 ⇒ 判决作废,不许动手。
+     * ② **先把行写死,再拆 claim**(复审 codex R1 [medium]):次序反过来的话,「claim 已拆、行还 park」
+     *    这半拍崩溃会留下一条**永远 park** 的行 —— boot 回收刻意跳过 park、sweepClaims 又没有 claim 可循,
+     *    没人收得掉。现在的次序里,同一处崩溃留下的是「行已终局 + claim 还在」,而那正是 `sweepClaims`
+     *    每次 boot / 每条 reaper 都会扫掉的形 —— 崩在哪一步都自愈。
+     * ③ 拆 claim 用 `renameSync(claim → tmp/隔离名)`:POSIX `rename` 对同一个源路径只可能**成功一次**,
+     *    并发的第二个 racer 拿 ENOENT。隔离件落在 `tmp/` 而不是 `runs/active/` —— `hydrate()` 把 activeDir 里的
+     *    **每个文件**都当 claim 读,隔离件留在那儿就等于把刚拆掉的幽灵在下次 boot 原样复活。
+     */
+    takeOverClaim(sessionId, reason, snapshot) {
+        // ① 复核:盘上的 claim 还是我判过的那一枚吗?(同一把有效形尺:缺键/错会话读成 undefined)
+        const nowClaim = readClaimRecord(readJsonlRecords(this.activePath(sessionId)), sessionId);
+        if (snapshot.torn) {
+            // A1:被撕的形没有可比的字段 —— 复核=「现在仍然解析不出记录」。解析得出 ⇒ 判定的 await
+            // 间隙里这枚 claim 被正常释放又被活主重铸了,判决作废(下一轮对新 claim 重新裁定)。
+            if (nowClaim !== undefined)
+                return false;
+        }
+        else if (!nowClaim || nowClaim.taskId !== snapshot.taskId || nowClaim.owner?.nonce !== snapshot.ownerNonce)
+            return false;
+        // 行的键统一取自快照(裁定认出的持有者)——撕裂 claim 的调用方读数里没有 taskId,快照才有(codex R2)。
+        const row = snapshot.taskId ? this.authoritativeRow(snapshot.taskId) : undefined;
+        if (row?.status !== snapshot.status || row?.updatedAt.getTime() !== snapshot.updatedAtMs)
+            return false;
+        // ② 先落终局行:留一条永远 running/park 的行会让 listRuns/fleet 显示一个永不结束的假活 run。
+        //    errorCode 刻意留空 —— 与 reclaimOrphanedAtBoot 同族(它也只写 error),不新铸 wire 错误码。
+        // 🔴 **副本写,不原地改**:本文件其它写路径是「改 row 再 persist」,那在 persist 抛出时会留下
+        //    「内存已 failed、盘上还 park」的分叉。接管这条路径必须是全有或全无(下一步就要拆 claim),
+        //    所以交给 persist 去 `runs.set` —— 写盘失败就什么都没发生,claim 原封不动,下一轮重来。
+        if (row && (row.status === "running" || row.status === "suspended" || row.status === "needs_review")) {
+            this.persist({ ...row, status: "failed", error: reason, updatedAt: new Date() });
+        }
+        // ③ 再拆 claim。
+        const quarantine = join(this.tmpDir, `stale-claim.${sanitizePathComponent(sessionId)}.${process.pid}.${randomBytes(6).toString("hex")}`);
+        try {
+            renameSync(this.activePath(sessionId), quarantine);
+        }
+        catch (e) {
+            // ENOENT = 输掉了这一枚 claim 的接管权(或它已被正常释放);行已终局,sweepClaims 会收尾。
+            // 其它错误(EPERM/EIO…)不是「输掉竞争」而是真实 fs 故障——吞成 false 会把故障演成永远的
+            // 「接管失败→重试→再失败」静默循环,rethrow 让它像其它写路径一样响亮。
+            if (e.code === "ENOENT")
+                return false;
+            throw e;
+        }
+        try {
+            rmSync(quarantine, { force: true });
+        }
+        catch (e) {
+            // F 类兜底:隔离件是死物,且不在 activeDir 下,留着不会被 hydrate 当成 claim 复活;
+            // 但删不掉仍要留痕(计数+一次性 warn),否则 tmp 静默膨胀没人知道。
+            recordFailOpen("server.run-store.stale-claim-quarantine-unremoved", e instanceof Error ? e.message : String(e));
+        }
+        if (this.active.get(sessionId) === snapshot.taskId)
+            this.active.delete(sessionId);
+        return true;
+    }
     /** Release a session's single-active claim: unlink the claim file + drop the index entry (idempotent). */
     releaseClaim(sessionId) {
         this.active.delete(sessionId);