@sema-agent/server 1.323.0 → 2.0.1

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

@@ -1,3 +1,31 @@
+/**
+ * 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. 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 { type UsageRow } from "../usage-analytics.js";
 import type { TaskResult, TaskStatus } from "@sema-agent/core";
 import type { RunRecord, SessionSummary, RunEvent } from "./store-contracts.js";
@@ -6,10 +34,16 @@ export declare class FileRunStore {
     private readonly runsDir;
     private readonly activeDir;
     private readonly tmpDir;
+    /** taskId → RunRow (the run registry index). */
     private readonly runs;
+    /** sessionId → taskId — the single-active-run claim (the task_active table; index of active/*). */
     private readonly active;
+    /** taskId → events (kept seq-sorted on read), the event-log index. */
     private readonly events;
+    /** taskId → the open append log (one O_APPEND fd per run, lazily opened, held for lifetime). */
     private readonly eventLogs;
+    /** [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?;
     constructor(root: string);
     private runDir;
@@ -19,9 +53,16 @@ export declare class FileRunStore {
     private toRow;
     private toDisk;
     private toRecord;
+    /** 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. */
     private hydrate;
+    /** Commit a RunRow to disk (whole-file atomic replace) AND the index — the single write path for every status change. */
     private persist;
     private eventLogFor;
+    /** 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. */
     createRun(taskId: string, sessionId: string, owner: string | null, instanceId: string, meta?: {
         jobId?: string | null;
         source?: string | null;
@@ -41,12 +82,18 @@ export declare class FileRunStore {
     maxSeq(taskId: string): Promise<number>;
     retainedFrom(taskId: string): Promise<number>;
     getEvents(taskId: string, afterSeq: number): Promise<RunEvent[]>;
+    /** [888] FIRST terminal writer wins(SQL 孪生同款正向 CAS on running/suspended/needs_review,
+     *  [1.207 codex M1] 负向形漏 blocked/timeout);claim 释放保持无条件(幂等)。 */
     setTerminal(taskId: string, status: TaskStatus, result: TaskResult | null, error: string | null): Promise<void>;
+    /** Durable F4: park NON-terminal `suspended`, KEEP the task_active claim. CAS on running/suspended (reaper-revert guard). */
     setSuspended(taskId: string): Promise<void>;
+    /** design/80 D-B: park NON-terminal `needs_review`, KEEP the claim. CAS on running/needs_review. */
     setNeedsReview(taskId: string): Promise<void>;
+    /** Durable F4 resume: flip suspended/needs_review → running (CAS) + reset cancel/preempt flags. */
     markResuming(taskId: string): Promise<boolean>;
     getActiveTaskId(sessionId: string): Promise<string | undefined>;
     getRun(taskId: string): Promise<RunRecord | undefined>;
+    /** Runs newest-first, keyset on (createdAt, taskId) DESC; optional exact-match filters (owner is exact, like the SQL). */
     listRuns(opts: {
         status?: string;
         jobId?: string;
@@ -58,6 +105,7 @@ export declare class FileRunStore {
         };
         limit: number;
     }): Promise<RunRecord[]>;
+    /** DISTINCT sessions newest-first by last activity (the CC /resume picker): latest run's preview/status + first/last/count. */
     listSessions(opts: {
         owner?: string;
         cursor?: {
@@ -67,11 +115,13 @@ export declare class FileRunStore {
         limit: number;
         q?: string;
     }): Promise<SessionSummary[]>;
+    /** E21 (§0.5 delete) — purge the runs ledger for one session, owner-guarded; aborts (returns {active}) if a run is live. */
     deleteBySession(sessionId: string, owner: string | null): Promise<{
         removed: number;
     } | {
         active: string;
     }>;
+    /** 用量扫窗——in-memory 腿:遍历窗内行,投影同 usage-analytics 纯函数(SQL 孪生 parity)。 */
     usageScan(fromMs: number, toMs: number, opts?: {
         owner?: string;
         limit?: number;
@@ -84,16 +134,56 @@ export declare class FileRunStore {
         status: string;
         count: number;
     }>>;
+    /** 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. */
     private sweepClaims;
+    /** Flip every `running` row matching `pred` → failed (with `reason`), then sweep terminal claims. */
     private reapRunning;
     reapStale(olderThanMs: number): Promise<number>;
+    /** 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). */
     reclaimOrphanedAtBoot(isResumable?: (sessionId: string) => Promise<boolean>): Promise<number>;
+    /** [868] wire the checkpoint probe (LocalBackend.checkpoint(), where checkpoint + run store share one root). */
     setCheckpointProbe(probe: RunStoreCheckpointProbe): void;
+    /** [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). */
     private failExpiredPark;
+    /**
+     * [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
+     * (tidb-run-store.ts:577-583): 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).
+     */
     reapSuspended(olderThanMs: number): Promise<number>;
+    /**
+     * [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).
+     */
     failSuspendedWithExpiredCheckpoint(): Promise<number>;
+    /** 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. */
     private dropRun;
+    /** Release every open event-log fd (called by LocalBackend.close so a graceful restart can re-open the data dir). */
     dispose(): void;
 }
 //# sourceMappingURL=file-run-store.d.ts.map

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

@@ -1,26 +1,64 @@
+/**
+ * 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. 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 { AppendLog, atomicWriteFile, ensureDir, readJsonlRecords, sanitizePathComponent, writeThenLink } from "@sema-agent/core";
+/** 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);
 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;
     constructor(root) {
         this.runsDir = join(root, "runs");
         this.activeDir = join(root, "runs", "active");
-        this.tmpDir = join(root, "tmp");
+        this.tmpDir = join(root, "tmp"); // atomicWriteFile temp dir (same FS as runs → rename is atomic)
         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));
     }
@@ -56,6 +94,10 @@ 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 {
@@ -66,19 +108,24 @@ export class FileRunStore {
         }
         for (const name of entries) {
             if (name === "active")
-                continue;
+                continue; // the claims dir, scanned separately
             const dir = join(this.runsDir, name);
             const jsonPath = join(dir, "run.json");
             if (!existsSync(jsonPath))
                 continue;
-            const rows = readJsonlRecords(jsonPath);
-            const disk = rows[rows.length - 1];
+            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)
             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) {
@@ -86,13 +133,14 @@ export class FileRunStore {
                 const seen = new Set();
                 for (const e of recs) {
                     if (!e || typeof e.seq !== "number" || seen.has(e.seq))
-                        continue;
+                        continue; // (taskId,seq) dedup-on-replay (last write wins by skip-first? no: first wins, matching append-ignore-dup)
                     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);
@@ -108,6 +156,7 @@ 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`);
@@ -122,12 +171,18 @@ 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.
         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 };
@@ -156,11 +211,15 @@ 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;
         }
@@ -199,8 +258,14 @@ 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);
@@ -217,11 +282,15 @@ 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)
@@ -234,9 +303,11 @@ 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")) {
@@ -245,6 +316,7 @@ 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")) {
@@ -253,6 +325,7 @@ 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"))
@@ -271,7 +344,11 @@ 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;
@@ -279,31 +356,35 @@ export class FileRunStore {
             .filter((r) => (opts.status ? r.status === opts.status : true))
             .filter((r) => (opts.jobId ? r.jobId === opts.jobId : true))
             .filter((r) => (opts.source ? r.source === opts.source : true))
-            .filter((r) => (opts.owner ? r.owner === opts.owner : true))
+            .filter((r) => (opts.owner ? r.owner === opts.owner : true)) // exact (SQL `owner = ?`): a set owner excludes null-owner rows
             .filter((r) => {
             if (cursorAt === undefined)
                 return true;
             const t = r.createdAt.getTime();
-            return t < cursorAt || (t === cursorAt && r.taskId < opts.cursor.taskId);
+            return t < cursorAt || (t === cursorAt && r.taskId < opts.cursor.taskId); // keyset: strictly older, ties by 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()) {
             if (opts.owner && r.owner !== opts.owner)
-                continue;
+                continue; // exact owner filter (SQL `owner = ?`)
             const arr = bySession.get(r.sessionId) ?? [];
             arr.push(r);
             bySession.set(r.sessionId, arr);
         }
         const cursorAt = opts.cursor ? Date.parse(opts.cursor.lastActivityAt) : undefined;
-        const qlc = opts.q?.toLowerCase();
+        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 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());
@@ -317,8 +398,8 @@ export class FileRunStore {
                 runCount: arr.length,
                 objectivePreview: latest.objectivePreview,
                 lastStatus: latest.status,
-                lastRunId: latest.taskId,
-                title: null,
+                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)
             });
         }
         return summaries
@@ -331,6 +412,7 @@ 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, owner-guarded; aborts (returns {active}) if a run is live. */
     async deleteBySession(sessionId, owner) {
         const claimed = this.active.get(sessionId);
         if (claimed !== undefined)
@@ -344,6 +426,7 @@ 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 = [];
@@ -364,13 +447,16 @@ export class FileRunStore {
         for (const r of this.runs.values()) {
             if (r.createdAt.getTime() < sinceMs)
                 continue;
-            const key = JSON.stringify([r.source, r.status]);
+            const key = JSON.stringify([r.source, r.status]); // collision-proof + keeps NULL distinct from "" (SQL GROUP BY parity)
             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);
@@ -378,6 +464,7 @@ 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()) {
@@ -396,6 +483,18 @@ 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()) {
@@ -411,9 +510,12 @@ 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";
@@ -421,6 +523,16 @@ 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
+     * (tidb-run-store.ts:577-583): 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)
@@ -432,7 +544,10 @@ export class FileRunStore {
                 continue;
             const snap = r.updatedAt.getTime();
             if (await probe.hasPending(r.sessionId))
-                continue;
+                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 复核就是它的本地等价)。
             if (r.status !== "suspended" || r.updatedAt.getTime() !== snap)
                 continue;
             this.failExpiredPark(r);
@@ -441,6 +556,14 @@ 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)
@@ -455,6 +578,7 @@ 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);
@@ -463,6 +587,8 @@ export class FileRunStore {
         this.sweepClaims();
         return reaped;
     }
+    // ── claim / run file lifecycle helpers ──
+    /** 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);
@@ -471,9 +597,11 @@ 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) {
@@ -481,6 +609,7 @@ export class FileRunStore {
                 log.close();
             }
             catch {
+                /* best-effort */
             }
             this.eventLogs.delete(taskId);
         }
@@ -492,15 +621,18 @@ 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();