@sema-agent/server 7.43.0 → 7.44.0

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

@@ -1,77 +1,28 @@
-/**
- * File-backed async run registry + replayable event log — the DURABLE local twin of {@link MemoryRunStore} (and the
- * file-backed sibling of {@link TiDBRunStore}/{@link PgRunStore}). P0.5 variant-1 (clay 2026-06-26): the file-backed
- * follow-on the Memory twin's header promised — a locally-run HTTP service now keeps its runs ledger + trace event log
- * across a process restart, not just in memory. Behaviour is byte-identical to MemoryRunStore (the shared parity oracle
- * — same single-active claim, the suspend/needs_review parks that KEEP the claim, the markResuming CAS that resets
- * cancel/preempt, the owner null-safe guard, the keyset list order, the (taskId,seq) event dedup, and the structuredClone
- * write/read isolation); the only difference is durability.
- *
- * THREE on-disk data planes (all under `<root>/runs/`), each using core's crash-safe fs primitives — never hand-rolled
- * fs (zero drift, no zero-length/torn corruption):
- *  1. run registry  — `<root>/runs/<taskId>/run.json` = the RunRow, replaced WHOLE on every status change via
- *                     `atomicWriteFile` (tmp→fsync→rename→fsync-dir, the 5-step atomic replace).
- *  2. single-active claim — `<root>/runs/active/<sanitizePathComponent(sessionId)>` carrying the active taskId, created
- *                     with `writeThenLink` (atomic create; EEXIST ⇒ the session already has an active run → the
- *                     createRun loses the claim, returns `{ok:false, activeTaskId}`). The file version of task_active's
- *                     unique key.
- *  3. per-run event log — `<root>/runs/<taskId>/events.jsonl` = an `AppendLog` (one line per event, fsync:false — events
- *                     are high-frequency, the torn-tail-drop on replay covers a crash tail; only the run.json status
- *                     commit + the active-claim create use fsync). (taskId,seq) is deduped on replay.
- *
- * 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 — 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, 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)
+        return true;
     try {
         process.kill(pid, 0);
         return true;
@@ -80,45 +31,29 @@ function isPidAlive(pid) {
         return e.code !== "ESRCH";
     }
 }
-/**
- * park 孤儿的**静置线**(防竞态余量,不是判据本身 —— 判据是「无 checkpoint 可续」)。
- * 见 judgeClaim 里 park 族那一段的红字注:它盖的是 decide 腿「解 checkpoint」与「markResuming」之间那一拍。
- */
 const PARK_ORPHAN_SETTLE_MS = 30_000;
 export class FileRunStore {
     runsDir;
     activeDir;
     tmpDir;
-    /** taskId → RunRow (the run registry index). */
     runs = new Map();
-    /** sessionId → taskId — the single-active-run claim (the task_active table; index of active/*). */
     active = new Map();
-    /** taskId → events (kept seq-sorted on read), the event-log index. */
     events = new Map();
-    /** taskId → the open append log (one O_APPEND fd per run, lazily opened, held for lifetime). */
     eventLogs = new Map();
-    /** [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();
-    /** 件6(#43 案 [4281]):启动期告警座(可选)。既有调用方不传 ⇒ 只走 fail-open 遥测那一半,不炸。 */
     logger;
     constructor(root, logger) {
         this.logger = logger;
         this.runsDir = join(root, "runs");
         this.activeDir = join(root, "runs", "active");
-        this.tmpDir = join(root, "tmp"); // atomicWriteFile temp dir (same FS as runs → rename is atomic)
+        this.tmpDir = join(root, "tmp");
         ensureDir(this.runsDir);
         ensureDir(this.activeDir);
         ensureDir(this.tmpDir);
         this.hydrate();
-        // NB: orphan reclaim is NOT auto-run here — main.ts boot drives it AFTER the checkpointStore is wired, so a
-        // resume-in-progress (markResuming) row with a pending checkpoint is excluded (see reclaimOrphanedAtBoot).
     }
-    // ── disk paths ──
     runDir(taskId) {
         return join(this.runsDir, sanitizePathComponent(taskId));
     }
@@ -154,22 +89,12 @@ export class FileRunStore {
             updatedAt: r.updatedAt.toISOString(),
         };
     }
-    /** Replay the on-disk registry/claims/event-logs into the in-memory index on boot. Each plane is torn-tail-/
-     *  partial-write-safe (run.json via atomicWriteFile can never be half-written; the active file via writeThenLink is
-     *  all-or-nothing; events.jsonl via readJsonlRecords drops a crash tail). A corrupt run.json (failed parse) is
-     *  skipped — that run is lost, not a poison that fails the boot. */
     hydrate() {
         let entries;
         try {
             entries = readdirSync(this.runsDir);
         }
         catch (err) {
-            // 🔴 件6(#43 案 [4281],静默降级纪律):旧形是**空 catch + return** —— data root 不可读时引擎以
-            // 空账起动、零告警,此后每一次 getRun 恒 miss,而「恒 miss」正是 #43 现场看到的形。方向错在这里:
-            // 吞掉之后被读成的是「**证不出有行 ⇒ 没有行**」,而这两句话不等价,一次环境故障就此被伪装成
-            // 「本来就没有这条 run」。
-            // **行为不变**(仍不拒启 —— 拒启是行为变更,另立),只从静默变响亮:一行 error 级日志带 runs 目录
-            // **绝对路径** + 异常文案(运维一眼能判是权限还是路径),外加登记进 fail-open 遥测让这条债显形。
             const detail = err instanceof Error ? err.message : String(err);
             this.logger?.error?.("file_run_store_hydrate_unreadable", {
                 runsDir: this.runsDir,
@@ -181,24 +106,19 @@ export class FileRunStore {
         }
         for (const name of entries) {
             if (name === "active")
-                continue; // the claims dir, scanned separately
+                continue;
             const dir = join(this.runsDir, name);
             const jsonPath = join(dir, "run.json");
             if (!existsSync(jsonPath))
                 continue;
-            const rows = readJsonlRecords(jsonPath); // run.json is a single atomic record; tolerate a torn/empty file
-            const disk = rows[rows.length - 1]; // last complete record (atomicWriteFile writes the whole file each time)
+            const rows = readJsonlRecords(jsonPath);
+            const disk = rows[rows.length - 1];
             if (!disk || typeof disk.taskId !== "string")
                 continue;
-            // R8 修:atomicWriteFile 防的是半写,防不了 schema 半态(旧版残留/手工改动的 run.json 缺时间戳字段)。
-            // 不挡在这里的话,坏行会在**读路径**上毒发:`toRecord` 对 Invalid Date 调 toISOString ⇒ RangeError ⇒
-            // 一条坏文件打死整个 listRuns(GET /v1/runs 全 500)。按顶注自述的隔离承诺同款处置:跳过该行,
-            // 一条坏行最多只影响它自己。
             if (typeof disk.createdAt !== "string" || Number.isNaN(Date.parse(disk.createdAt)) ||
                 typeof disk.updatedAt !== "string" || Number.isNaN(Date.parse(disk.updatedAt)))
                 continue;
             this.runs.set(disk.taskId, this.toRow(disk));
-            // event log
             const eventsPath = join(dir, "events.jsonl");
             const recs = readJsonlRecords(eventsPath);
             if (recs.length) {
@@ -206,14 +126,13 @@ export class FileRunStore {
                 const seen = new Set();
                 for (const e of recs) {
                     if (!e || typeof e.seq !== "number" || seen.has(e.seq))
-                        continue; // (taskId,seq) dedup-on-replay (last write wins by skip-first? no: first wins, matching append-ignore-dup)
+                        continue;
                     seen.add(e.seq);
                     list.push({ seq: e.seq, type: String(e.type), data: e.data ?? null, ts: String(e.ts) });
                 }
                 this.events.set(disk.taskId, list);
             }
         }
-        // active claims
         let claims;
         try {
             claims = readdirSync(this.activeDir);
@@ -221,22 +140,14 @@ 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);
         }
@@ -244,38 +155,22 @@ export class FileRunStore {
             const path = join(this.activeDir, sanitized);
             const recs = readJsonlRecords(path);
             const claim = recs[recs.length - 1];
-            // 与判定腿同一把尺(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 重试。
+                    continue;
                 try {
                     rmSync(path, { force: true });
                 }
@@ -285,7 +180,6 @@ export class FileRunStore {
             }
         }
     }
-    /** Commit a RunRow to disk (whole-file atomic replace) AND the index — the single write path for every status change. */
     persist(r) {
         mkdirSync(this.runDir(r.taskId), { recursive: true });
         atomicWriteFile(this.tmpDir, this.runJsonPath(r.taskId), `${JSON.stringify(this.toDisk(r))}\n`);
@@ -300,16 +194,7 @@ export class FileRunStore {
         }
         return log;
     }
-    /** Create a run iff the session has no active run (the task_active unique-key claim). The claim file is created with
-     *  writeThenLink (atomic): if it already exists (EEXIST) the session has an active run → lose, return the holder. */
     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.
-        // #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)
@@ -317,7 +202,6 @@ export class FileRunStore {
             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();
@@ -341,15 +225,11 @@ export class FileRunStore {
             });
         }
         catch (e) {
-            // R9 修:claim 与 run 行是一体的 —— 行没落下(如超长 taskId 的 ENAMETOOLONG)就把刚落的 claim 撤掉再
-            // rethrow。否则 session 被一个 getRun=undefined 的幽灵 taskId 占用:起不了新 run、也取消不了"活跃 run",
-            // 直到进程重启 sweepClaims 才解(SQL 孪生天然免疫:createRun 整体在一个事务里)。
             this.active.delete(sessionId);
             try {
                 rmSync(this.activePath(sessionId), { force: true });
             }
             catch {
-                /* best-effort:claim 文件撤不掉时至少 index 已撤;重启 sweep 兜底 */
             }
             throw e;
         }
@@ -388,14 +268,8 @@ export class FileRunStore {
     }
     async appendEvent(taskId, seq, type, data) {
         const list = this.events.get(taskId) ?? [];
-        // Mirror the (task_id, seq) PK: a duplicate seq is a caller bug (callers use ++seq); ignore a re-append of the
-        // same seq rather than corrupt the log (the SQL twin throws ER_DUP_ENTRY — callers never hit it).
         if (list.some((e) => e.seq === seq))
             return;
-        // Deep-clone `data` on WRITE so the stored event is isolated from later caller mutation — the SQL twin
-        // JSON.stringify's it into the column, giving the same write-isolation (parity oracle). Persist BEFORE indexing
-        // so a crash after the append still replays the event (fsync:false — events are high-frequency, the torn-tail
-        // drop on replay covers a crash tail; only run.json status + the active claim need fsync).
         const clone = data == null ? null : structuredClone(data);
         const ts = new Date().toISOString();
         this.eventLogFor(taskId).append({ seq, type, data: clone, ts }, false);
@@ -412,21 +286,14 @@ export class FileRunStore {
     }
     async getEvents(taskId, afterSeq) {
         const list = this.events.get(taskId) ?? [];
-        // Deep-clone `data` on READ so each call yields a fresh, mutation-isolated object — the SQL twin re-parses the
-        // JSON column per read (parity oracle); a shallow `{...e}` would alias `data` into the stored list (review footgun).
         return list
             .filter((e) => e.seq > afterSeq)
             .sort((a, b) => a.seq - b.seq)
             .map((e) => ({ ...e, data: e.data == null ? null : structuredClone(e.data) }));
     }
-    /** [888] FIRST terminal writer wins(SQL 孪生同款正向 CAS on running/suspended/needs_review,
-     *  [1.207 codex M1] 负向形漏 blocked/timeout);claim 释放保持无条件(幂等)。 */
     async setTerminal(taskId, status, result, error) {
         const r = this.runs.get(taskId);
         if (!r) {
-            // [2255]③ claim 孤儿修:行不在(跨进程窗 —— claim 落盘、行未落/已失;R9 只兜同进程写失败)时,
-            // 终局动词仍必须能放锁:cancel 是文案承诺的用户自救路,它对孤儿失效=会话钉死到 reaper/boot。
-            // 反查 active 索引找持有该 taskId 的 session(O(claims),claims 数=活跃会话数,小)。
             for (const [sessionId, tid] of this.active)
                 if (tid === taskId) {
                     this.releaseClaim(sessionId);
@@ -442,11 +309,9 @@ export class FileRunStore {
             r.updatedAt = new Date();
             this.persist(r);
         }
-        // Release the single-active-run claim (DELETE FROM task_active WHERE task_id = ?) — unlink the claim file + index.
         if (this.active.get(r.sessionId) === taskId)
             this.releaseClaim(r.sessionId);
     }
-    /** Durable F4: park NON-terminal `suspended`, KEEP the task_active claim. CAS on running/suspended (reaper-revert guard). */
     async setSuspended(taskId) {
         const r = this.runs.get(taskId);
         if (r && (r.status === "running" || r.status === "suspended")) {
@@ -455,7 +320,6 @@ export class FileRunStore {
             this.persist(r);
         }
     }
-    /** design/80 D-B: park NON-terminal `needs_review`, KEEP the claim. CAS on running/needs_review. */
     async setNeedsReview(taskId) {
         const r = this.runs.get(taskId);
         if (r && (r.status === "running" || r.status === "needs_review")) {
@@ -464,7 +328,6 @@ export class FileRunStore {
             this.persist(r);
         }
     }
-    /** Durable F4 resume: flip suspended/needs_review → running (CAS) + reset cancel/preempt flags. */
     async markResuming(taskId) {
         const r = this.runs.get(taskId);
         if (!r || (r.status !== "suspended" && r.status !== "needs_review"))
@@ -483,33 +346,27 @@ export class FileRunStore {
         const r = this.runs.get(taskId);
         return r ? this.toRecord(r) : undefined;
     }
-    /** Runs newest-first, keyset on (createdAt, taskId) DESC; optional exact-match filters (owner is exact, like the SQL). */
     async listRuns(opts) {
-        // 夜测 N1(2026-07-09,LOW):a non-date cursor.createdAt made the four backends diverge (PG threw a raw
-        // DB error; the other three returned an empty page). HTTP's decodeCursor pre-validates, so this is
-        // defence-in-depth for direct store callers — normalize ALL backends to the empty page.
         if (opts.cursor && Number.isNaN(Date.parse(opts.cursor.createdAt)))
             return [];
         const cursorAt = opts.cursor ? Date.parse(opts.cursor.createdAt) : undefined;
         const rows = [...this.runs.values()]
             .filter((r) => (opts.status ? r.status === opts.status : true))
-            .filter((r) => (opts.jobId !== undefined ? r.jobId === opts.jobId : true)) // "" is a valid exact jobId, not "no filter" (B10)
-            .filter((r) => (opts.source !== undefined ? r.source === opts.source : true)) // "" is a valid exact source, not "no filter" (B10)
-            .filter((r) => (opts.owner !== undefined ? r.owner === opts.owner : true)) // exact (SQL `owner = ?`): "" is a valid exact owner, not "no filter" (B10)
+            .filter((r) => (opts.jobId !== undefined ? r.jobId === opts.jobId : true))
+            .filter((r) => (opts.source !== undefined ? r.source === opts.source : true))
+            .filter((r) => (opts.owner !== undefined ? r.owner === opts.owner : true))
             .filter((r) => {
             if (cursorAt === undefined)
                 return true;
             const t = r.createdAt.getTime();
-            return t < cursorAt || (t === cursorAt && r.taskId < opts.cursor.taskId); // keyset: strictly older, ties by taskId
+            return t < cursorAt || (t === cursorAt && r.taskId < opts.cursor.taskId);
         })
             .sort((a, b) => b.createdAt.getTime() - a.createdAt.getTime() || (a.taskId < b.taskId ? 1 : a.taskId > b.taskId ? -1 : 0));
         return rows.slice(0, opts.limit).map((r) => this.toRecord(r));
     }
-    /** DISTINCT sessions newest-first by last activity (the CC /resume picker): latest run's preview/status + first/last/count. */
     async listSessions(opts) {
         const bySession = new Map();
         for (const r of this.runs.values()) {
-            // exact owner filter (SQL `owner = ?`); "" is a valid exact owner (B10). `includeUnowned` = [4198] 窄臂第三条件(SQL `OR owner IS NULL`)。
             if (opts.owner !== undefined && r.owner !== opts.owner && !(opts.includeUnowned === true && r.owner === null))
                 continue;
             const arr = bySession.get(r.sessionId) ?? [];
@@ -517,14 +374,11 @@ export class FileRunStore {
             bySession.set(r.sessionId, arr);
         }
         const cursorAt = opts.cursor ? Date.parse(opts.cursor.lastActivityAt) : undefined;
-        const qlc = opts.q?.toLowerCase(); // `?q=`: any-run preview match — signature parity with the memory twin
-        // (this lister is UNREACHABLE via GET /v1/sessions today [local backend's sessionStorage lister wins], but a
-        // carried lister must not silently ignore a filter key — the workflow-audit hygiene item, 2026-07-13).
+        const qlc = opts.q?.toLowerCase();
         const summaries = [];
         for (const [sessionId, arr] of bySession) {
             if (qlc && !arr.some((r) => r.objectivePreview?.toLowerCase().includes(qlc)))
                 continue;
-            // rn=1 = latest run (createdAt DESC, taskId DESC) → preview/status/owner.
             const sorted = [...arr].sort((a, b) => b.createdAt.getTime() - a.createdAt.getTime() || (a.taskId < b.taskId ? 1 : a.taskId > b.taskId ? -1 : 0));
             const latest = sorted[0];
             const times = arr.map((r) => r.createdAt.getTime());
@@ -538,8 +392,8 @@ export class FileRunStore {
                 runCount: arr.length,
                 objectivePreview: latest.objectivePreview,
                 lastStatus: latest.status,
-                lastRunId: latest.taskId, // K-5c: latest run id = the live-tail re-attach anchor
-                title: null, // honest degrade (no session_meta on the file runs-ledger twin)
+                lastRunId: latest.taskId,
+                title: null,
             });
         }
         return summaries
@@ -552,12 +406,8 @@ export class FileRunStore {
             .sort((a, b) => Date.parse(b.lastActivityAt) - Date.parse(a.lastActivityAt) || (a.sessionId < b.sessionId ? 1 : a.sessionId > b.sessionId ? -1 : 0))
             .slice(0, opts.limit);
     }
-    /** 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),理由与替代围栏逐字见 {@link MemoryRunStore.deleteBySession}。 */
     async deleteBySession(sessionId, expectedSessionOwner) {
-        void expectedSessionOwner; // 见上:围栏在协调器那一侧(local 无 session_meta)
+        void expectedSessionOwner;
         const claimed = this.active.get(sessionId);
         if (claimed !== undefined)
             return { active: claimed };
@@ -570,7 +420,6 @@ export class FileRunStore {
         }
         return { removed };
     }
-    /** 用量扫窗——in-memory 腿:遍历窗内行,投影同 usage-analytics 纯函数(SQL 孪生 parity)。 */
     async usageScan(fromMs, toMs, opts) {
         const limit = Math.min(opts?.limit ?? USAGE_SCAN_LIMIT, USAGE_SCAN_LIMIT);
         const all = [];
@@ -591,16 +440,13 @@ export class FileRunStore {
         for (const r of this.runs.values()) {
             if (r.createdAt.getTime() < sinceMs)
                 continue;
-            const key = JSON.stringify([r.source, r.status]); // collision-proof + keeps NULL distinct from "" (SQL GROUP BY parity)
+            const key = JSON.stringify([r.source, r.status]);
             const cur = counts.get(key) ?? { source: r.source, status: r.status, count: 0 };
             cur.count += 1;
             counts.set(key, cur);
         }
         return [...counts.values()];
     }
-    /** Fail stale `running` rows (crashed-run backstop) + release task_active for any now-terminal row. */
-    /** Release any claim whose row is now terminal; KEEP suspended/needs_review (resume re-finds them). One place for
-     *  the claim-release invariant, shared by reapRunning + reclaimOrphanedAtBoot. */
     sweepClaims() {
         for (const [sessionId, taskId] of [...this.active]) {
             const r = this.runs.get(taskId);
@@ -608,7 +454,6 @@ export class FileRunStore {
                 this.releaseClaim(sessionId);
         }
     }
-    /** Flip every `running` row matching `pred` → failed (with `reason`), then sweep terminal claims. */
     reapRunning(pred, reason) {
         let reaped = 0;
         for (const r of this.runs.values()) {
@@ -627,18 +472,6 @@ export class FileRunStore {
         const cutoff = Date.now() - olderThanMs;
         return this.reapRunning((r) => r.updatedAt.getTime() < cutoff, "run stalled (instance lost?)");
     }
-    /** TOC integration ask③ (INTEGRATION-DESIGN §11): a host-lane engine restart leaves the PREVIOUS process's
-     *  `running` rows orphaned — their in-process driver (runInBackground, in the dead process's memory) is gone, but the
-     *  `active/<sessionId>` claim persists on disk and EEXIST-blocks a re-submit (the shell reads the session as stuck).
-     *  The boot flock (store-backend `LOCK`) already proves no concurrent live owner reached here: a still-alive old
-     *  engine holds it so the new one FAILS FAST; a dead one had it kernel-released. So a `running` row here is orphaned
-     *  → flip failed + release its claim UNCONDITIONALLY (no TTL wait, unlike reapStale's steady-state poll).
-     *  🔴 EXCEPT a resume-in-progress row: `markResuming` flips a suspended run (suspended→running) while its pending
-     *  checkpoint still exists, and the resume picker will re-drive it — reclaiming it would STRAND a resumable session
-     *  as failed. `isResumable(sessionId)` (wired by main.ts boot, which holds the checkpointStore) excludes those; with
-     *  no callback every running row is treated as orphaned (conservative default when no checkpoint plane is wired).
-     *  HOST/FILE LANE ONLY — the cross-replica tidb/pg store uses heartbeat→reapStale (a running row there may be alive
-     *  on another replica; an unconditional reclaim would kill a live fleet run). */
     async reclaimOrphanedAtBoot(isResumable) {
         const orphans = [];
         for (const r of this.runs.values()) {
@@ -654,12 +487,9 @@ export class FileRunStore {
         this.sweepClaims();
         return orphans.length;
     }
-    /** [868] wire the checkpoint probe (LocalBackend.checkpoint(), where checkpoint + run store share one root). */
     setCheckpointProbe(probe) {
         this.checkpointProbe = probe;
     }
-    /** [868] shared tail of both suspended-run reapers: flip one parked row → failed('approval.expired') and
-     *  PERSIST it — the file twin of the SQL UPDATE (`error`/`error_code` set directly, no result blob). */
     failExpiredPark(r) {
         r.status = "failed";
         r.error = "approval expired before decision";
@@ -667,22 +497,12 @@ export class FileRunStore {
         r.updatedAt = new Date();
         this.persist(r);
     }
-    /**
-     * [868] Durable F4 expiry — the file twin of TiDBRunStore.reapSuspended, driven by the injected checkpoint
-     * probe instead of a SQL JOIN (formerly a NO-OP — one of the five closed doors in the "suspended run locks the
-     * session forever" incident). Semantics verbatim from the SQL twin: suspended ∧ updatedAt < cutoff ∧ NOT
-     * probe.hasPending(session) → failed 'approval expired before decision' / errorCode 'approval.expired' +
-     * release the task_active claim. The NOT-pending clause is the design/80 D-D adversarial-blocker guard
-     * (SQL 孪生现在的真身:`run-store-sql.ts` 的 `reapSuspended`;`tidb-run-store.ts` 该壳文件已删(5.0.0)): a row whose checkpoint is STILL pending belongs to the checkpoint-state sweeps —
-     * time-reaping it would orphan a model leg on a now-unlocked session. Probe absent ⇒ honest NO-OP.
-     * MemoryRunStore is the parity oracle (byte-identical predicate; only the persist differs).
-     */
     async reapSuspended(olderThanMs) {
         const probe = this.checkpointProbe;
         if (!probe) {
             this.sweepClaims();
             return 0;
-        } // [2255]③:时间腿无 probe=诚实 NO-OP,但 claim 不变式维护不跟 probe 走
+        }
         const cutoff = Date.now() - olderThanMs;
         let reaped = 0;
         for (const r of this.runs.values()) {
@@ -690,10 +510,7 @@ export class FileRunStore {
                 continue;
             const snap = r.updatedAt.getTime();
             if (await probe.hasPending(r.sessionId))
-                continue; // D-D guard: a still-pending checkpoint owns this row
-            // codex H2:probe 的 await 让出事件循环——markResuming(approve 恢复)/cancel/新一轮 park 可能已改行。
-            // 复核与改写之间无 await(Node 单线程 ⇒ 原子);状态或 updatedAt 变了就放手,绝不覆盖一条已被别腿
-            // 认领的行(SQL 孪生靠单条条件 UPDATE 天然原子,这里的 snap 复核就是它的本地等价)。
+                continue;
             if (r.status !== "suspended" || r.updatedAt.getTime() !== snap)
                 continue;
             this.failExpiredPark(r);
@@ -702,20 +519,12 @@ export class FileRunStore {
         this.sweepClaims();
         return reaped;
     }
-    /**
-     * [868] design/80 §3 inv#3 crash-safe backstop — the file twin of TiDBRunStore.failSuspendedWithExpiredCheckpoint
-     * (checkpoint-STATE-driven, not time-driven; scheduled UNCONDITIONALLY by the main.ts reaper, no
-     * APPROVAL_TIMEOUT_SEC gate). Semantics verbatim from the SQL twin: (suspended ∨ needs_review) ∧
-     * probe.hasExpired(session) ∧ NOT probe.hasPending(session) → same fail + claim release (wq64gmm5e: an
-     * abandoned needs_review park leaks exactly like a suspended one; a re-suspended session that minted a NEW
-     * pending gate is excluded by the NOT-pending clause).
-     */
     async failSuspendedWithExpiredCheckpoint() {
         const probe = this.checkpointProbe;
         if (!probe) {
             this.sweepClaims();
             return 0;
-        } // [2255]③ 同上
+        }
         let reaped = 0;
         for (const r of this.runs.values()) {
             if (r.status !== "suspended" && r.status !== "needs_review")
@@ -726,7 +535,6 @@ export class FileRunStore {
                 continue;
             if (await probe.hasPending(r.sessionId))
                 continue;
-            // codex H2 同款 snap 复核(两个 await 窗都盖住):行被别腿改过就放手。
             if (r.status !== parkedAs || r.updatedAt.getTime() !== snap)
                 continue;
             this.failExpiredPark(r);
@@ -735,21 +543,9 @@ export class FileRunStore {
         this.sweepClaims();
         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))
@@ -763,24 +559,12 @@ export class FileRunStore {
             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;
@@ -799,25 +583,9 @@ export class FileRunStore {
         }
         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;
@@ -826,7 +594,7 @@ export class FileRunStore {
         });
         this.claimLocks.set(sessionId, mine);
         if (prev)
-            await prev; // 前一位失败也不会卡住后一位:mine 在 finally 里无条件 release
+            await prev;
         try {
             return await fn();
         }
@@ -836,7 +604,6 @@ export class FileRunStore {
                 this.claimLocks.delete(sessionId);
         }
     }
-    /** #213 —— 临界区内的 claim 获取本体:铸不下就裁定持有者,判陈旧则接管后重铸。有界重试(论证见 takeOverClaim)。 */
     async acquireClaim(sessionId, taskId) {
         for (let attempt = 0; attempt < CLAIM_TAKEOVER_ATTEMPTS; attempt += 1) {
             try {
@@ -846,20 +613,14 @@ export class FileRunStore {
             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); // 复核不过/搬不动也重来一轮
+                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 };
@@ -871,52 +632,18 @@ export class FileRunStore {
         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 也要报得出真持有者(修前这形只能报空串)
+                holder = row.taskId;
             }
             else if (this.active.has(sessionId)) {
                 return { kind: "live", holderTaskId: this.active.get(sessionId) };
@@ -929,10 +656,6 @@ export class FileRunStore {
                 };
             }
         }
-        // 判定链里的每个 await 都会让出事件循环 —— 复审(codex R1 [critical])的靶心:probe 期间 resume 腿
-        // 可能已经 `markResuming`(park→running)、终局腿可能已经放锁重铸。所以这里先取一份快照,接管前
-        // 必须**逐字复核**(见 takeOverClaim);任何一项动了就放手重来。同一条纪律在 reapSuspended 里
-        // 已经有先例(那处的 `snap` 复核),本函数照抄并把 **claim 身份**也一并纳入。
         const snapshot = {
             taskId: holder,
             ownerNonce: owner?.nonce,
@@ -940,105 +663,53 @@ export class FileRunStore {
             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 面 ⇒ 证不出不可续 ⇒ 挡住
+                return live();
             if (await probe.hasPending(row.sessionId))
-                return live(); // 可续的 park —— 用户的待决审批,绝不许抢
+                return live();
             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 秒。
+                return live();
             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 无死亡证据 ⇒ 挡住
+            return live();
         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;
@@ -1047,15 +718,12 @@ export class FileRunStore {
             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);
         const path = this.activePath(sessionId);
@@ -1064,11 +732,9 @@ export class FileRunStore {
                 rmSync(path, { force: true });
             }
             catch {
-                /* best-effort — a stale claim file is harmless (the index entry is already gone) */
             }
         }
     }
-    /** Drop a run entirely (registry + event log + open fd + on-disk dir) — used by deleteBySession. */
     dropRun(taskId) {
         const log = this.eventLogs.get(taskId);
         if (log) {
@@ -1076,7 +742,6 @@ export class FileRunStore {
                 log.close();
             }
             catch {
-                /* best-effort */
             }
             this.eventLogs.delete(taskId);
         }
@@ -1088,18 +753,15 @@ export class FileRunStore {
                 rmSync(dir, { recursive: true, force: true });
             }
             catch {
-                /* best-effort */
             }
         }
     }
-    /** Release every open event-log fd (called by LocalBackend.close so a graceful restart can re-open the data dir). */
     dispose() {
         for (const log of this.eventLogs.values()) {
             try {
                 log.close();
             }
             catch {
-                /* best-effort */
             }
         }
         this.eventLogs.clear();