@sema-agent/core 5.19.0 → 5.21.0

package/dist/stores/file/background-agent-store.d.ts

@@ -1,17 +1,36 @@
 import { type BackgroundAgentReapOptions, type BackgroundAgentRecord, type BackgroundAgentRowSummary, type BackgroundAgentStore, type BackgroundAgentUpdateIfExpect } from "../../core/background-agent-store.js";
 export interface FileBackgroundAgentStoreOptions {
+    /** When false, a ledger append is NOT fsync'd. Default true. */
     fsync?: boolean;
+    /** Compact the ledger into a snapshot once it exceeds this many events (then truncate). Default 1000. */
     compactEvery?: number;
 }
 export declare class FileBackgroundAgentStore implements BackgroundAgentStore {
     private readonly fsyncEnabled;
     private readonly compactEvery;
+    /** RB-55: all mutable state is SHARED per canonical directory (see the note above the class). */
     private readonly ledger;
+    /** RB-145: this instance's own close latch — the refcount belongs to the DIRECTORY, not to callers. */
     private closed;
     private get rows();
     constructor(root: string, opts?: FileBackgroundAgentStoreOptions);
+    /**
+     * RB-60 (2026-07-25, red probe): the composite key must be INJECTIVE — `get`/`update` no longer re-check
+     * scope, so tenant isolation rests entirely on this function. A SPACE separator is not injective
+     * (`scope="a", handle="b c"` and `scope="a b", handle="c"` produce the same key), which let one tenant's
+     * row collide with another's. The in-memory reference implementation (`core/background-agent-store.ts`)
+     * uses `\u0000` for exactly this reason ("the composite key keeps the info-hiding property structural") —
+     * a NUL can never occur in a scope or handle, so the mapping is injective. Matching it also restores this
+     * backend's stated "byte-for-byte the InMemory reference implementation's" claim.
+     *
+     * MIGRATION: the key is IN-MEMORY only (the ledger stores whole records with their own `scope`/`handle`
+     * fields, and replay rebuilds keys through this function), so changing the separator needs no on-disk
+     * migration — an existing directory replays into the new key space on next open.
+     */
     static key(handle: string, scope: string): string;
     private withLock;
+    /** Durable append FIRST, in-memory flip AFTER, then best-effort compaction — all in the base
+     *  (RB-150/RB-167: a failing housekeeping compaction must never be reported as this CAS failing). */
     private commit;
     put(record: BackgroundAgentRecord): Promise<void>;
     get(handle: string, scope: string): Promise<BackgroundAgentRecord | null>;
@@ -32,7 +51,12 @@ export declare class FileBackgroundAgentStore implements BackgroundAgentStore {
         rev: number;
     }): Promise<boolean>;
     reap(scope: string, now: number, opts?: BackgroundAgentReapOptions): Promise<number>;
+    /** Force a compaction now (test/inspection). RB-167's closeForSwap recipe lives in the base. */
     compactNow(): void;
+    /** Test/inspection helper: number of stored rows. */
     get size(): number;
+    /** Release the append handle (best-effort). RB-55: refcounted — the directory's shared authority
+     *  (rows/locks/log) is torn down only when the LAST instance over it closes, so a sibling instance
+     *  is never left holding a closed fd or a half-dropped view. */
     close(): void;
 }

package/dist/stores/file/background-agent-store.js

@@ -1,5 +1,5 @@
 import { join } from "node:path";
-import { BackgroundAgentStoreError, STALE_RUNNING_REAP_ATTRIBUTION, queryBackgroundAgents, } from "../../core/background-agent-store.js";
+import { BackgroundAgentStoreError, STALE_RUNNING_REAP_ATTRIBUTION, assertBackgroundAgentReapOptions, queryBackgroundAgents, } from "../../core/background-agent-store.js";
 import { SharedLedgerTable } from "./shared-ledger.js";
 const agentLedgers = new SharedLedgerTable({
     keyOf: (r) => FileBackgroundAgentStore.key(r.handle, r.scope),
@@ -113,6 +113,7 @@ export class FileBackgroundAgentStore {
         });
     }
     async reap(scope, now, opts) {
+        assertBackgroundAgentReapOptions(opts);
         if (!opts || (opts.maxAgeMs === undefined && opts.keep === undefined && opts.staleRunningMaxAgeMs === undefined))
             return 0;
         const changed = new Set();

package/dist/stores/file/checkpoint-store.d.ts

@@ -1,19 +1,44 @@
 import { type Checkpoint, type PendingSteerInput, type CheckpointFaultMode, type CheckpointStore, type CheckpointSummary, type CheckpointToken, type ReopenReason, type ResolveExpectation, type ResumeOutcome } from "../../core/checkpoint-store.js";
 export interface FileCheckpointStoreOptions {
+    /** When false, an `appendLine` for a state transition is NOT fsync'd. The checkpoint COMMIT POINT always
+     *  fsyncs regardless (its crash-safety depends on it); this only affects whether `put` fsyncs. Default true. */
     fsync?: boolean;
+    /** Compact the ledger into a snapshot once it exceeds this many events (then truncate). Default 1000. */
     compactEvery?: number;
 }
 export declare class FileCheckpointStore implements CheckpointStore {
+    /** design/173 §2.3 — honest declaration on the restart-survival axis the vocabulary claims: rows
+     *  live on disk (fsync'd append log) and survive a process restart. Multi-replica coordination is
+     *  NOT claimed by this axis (see {@link StoreDurability}) — this backend is deliberately
+     *  single-instance-per-data-dir (the boot lock refuses a second process); Pg/TiDB own that. */
     readonly durability: "durable";
+    /** Honest declaration on the fidelity axis: the ledger is JSONL, so what survives the restart this
+     *  backend promises is the JSON PROJECTION of the row — a `Date` replays as its ISO string, a
+     *  `Map`/`Set` as `{}`, `NaN` as `null`. The in-process map holds the structured clone, which is why
+     *  the loss is invisible until something reads the disk; the declaration is what makes it visible to
+     *  the mint BEFORE the row is filed. */
     readonly fidelity: "json";
     private readonly fsyncEnabled;
     private readonly compactEvery;
+    /** RB-134: the directory's ONE authority (map + token mutex + append log), joined not rebuilt. */
     private readonly ledger;
     private closed;
     private get cps();
+    /** One-shot crash fault (mirrors `InMemoryCheckpointStore.testInjectFault`). */
     private fault;
     constructor(root: string, opts?: FileCheckpointStoreOptions);
+    /** Serialize an op behind any in-flight op on the same token (the in-process per-token async mutex). */
     private withLock;
+    /**
+     * Commit one ledger event (append + fsync) THEN flip the in-memory map (crash-safe ordering, §2.4).
+     *
+     * RB-150 (2026-07-25, cross-backend differential): the compaction that may follow is HOUSEKEEPING and
+     * runs AFTER the operation is durable and the memory flip has happened — so its failure must never be
+     * reported as the operation's failure. It was: a snapshot write hitting EACCES made `resolve()` REJECT
+     * while the row was already `resolved` and the winner recorded, i.e. a consumed approval presented to
+     * the caller as "this did not happen" — the worst possible direction for a once-only gate, and something
+     * the in-memory reference cannot do because it has no I/O here. Both halves are now in the base.
+     */
     private commit;
     put(token: CheckpointToken, cp: Checkpoint): Promise<void>;
     get(token: CheckpointToken): Promise<Checkpoint | null>;
@@ -24,8 +49,21 @@ export declare class FileCheckpointStore implements CheckpointStore {
     reap(scope: string, cutoff: number): Promise<number>;
     listByScope(scope: string): Promise<CheckpointSummary[]>;
     listScopes(): Promise<string[]>;
+    /** Force a compaction now (test/inspection). The snapshot rewrite + RB-167 closeForSwap swap that
+     *  makes `replay` read the full state from the snapshot alone is the base's {@link LedgerCore.compact}. */
     compactNow(): void;
+    /** Arm a one-shot fault on the next `resolve` (mirrors InMemory `testInjectFault`, council #5). */
     testInjectFault(mode: CheckpointFaultMode | null): void;
+    /** Test/inspection helper: number of stored checkpoints. */
     get size(): number;
+    /**
+     * Release the append handle (best-effort). The boot LOCK is released by the backend factory.
+     *
+     * RB-134: refcounted, and the LAST holder REVOKES the directory's authority. Adding the shared table
+     * without this would have repeated RB-73's mistake exactly — a cache with no invalidation: after a
+     * `close()` the next `new FileCheckpointStore(sameRoot)` joined a table whose log was already closed and
+     * every write threw `log_closed`, instead of replaying the on-disk truth into a fresh authority. Idempotent:
+     * a second `close()` on the same instance must not decrement someone else's share.
+     */
     close(): void;
 }

package/dist/stores/file/file-snapshot-store.d.ts

@@ -1,6 +1,18 @@
 import type { ExecutionEnv } from "../../internal/harness-types.js";
 import { type FileSnapshotBounds, type FileSnapshotResult, type FileSnapshotStore } from "../../core/file-snapshot-store.js";
 export interface FileFileSnapshotStoreOptions {
+    /**
+     * Disclosure sink for a durable read this store treats as ABSENT (ruled 2026-08-03). Same name and
+     * same `{path, reason}` shape as the sibling file stores' seat — "unreadable read as missing" and
+     * "corrupt read as missing" are one failure grammar, so they get one seat name.
+     *
+     * Fires for: a corrupt/unreadable MANIFEST collapsed to "no snapshot" (the never-throw seam's
+     * documented fail-open — `has`/`restore`/`exportManifest`/`listKeys` all report absence), an
+     * unreadable manifest DIRECTORY that degrades an enumeration to "no keys", and a blob-GC pass that
+     * aborted because its live set could not be completed (blobs are kept — leaked, not lost).
+     *
+     * Never fires on plain ENOENT: a scope with no snapshots yet really is empty. Swallow-guarded.
+     */
     onCorruptRead?: (info: {
         path: string;
         reason: string;
@@ -10,14 +22,27 @@ export declare class FileFileSnapshotStore implements FileSnapshotStore {
     private readonly base;
     private readonly blobsDir;
     private readonly manifestsDir;
+    /**
+     * RB-163 (2026-07-26): the in-flight blob set is authority over a DIRECTORY, so it lives with the
+     * directory. On the instance, a second store on the same base ran `reap()` while the first was midway
+     * through `importManifest` — its live set did not include the peer's in-flight blobs, so it collected
+     * blobs the peer had already published, and the import still reported `ok` with a manifest referencing
+     * files that no longer exist. Keyed by {@link canonicalStoreKey} so two spellings of one directory
+     * cannot each keep their own idea of what is in flight.
+     */
     private get inFlight();
     private readonly inFlightKey;
     private readonly bounds;
     private readonly onCorruptRead;
     constructor(root: string, bounds?: Partial<FileSnapshotBounds>, opts?: FileFileSnapshotStoreOptions);
+    /** The one delivery point for {@link FileFileSnapshotStoreOptions.onCorruptRead}; swallow-guarded
+     *  here so no call site has to remember (and so the never-throw seam contract cannot be broken by a
+     *  host's sink). */
     private disclose;
     private scopeDir;
     private manifestPath;
+    /** manifestPath, but a key that fails the strict path-component guard → null (so the seam's NEVER-throw
+     *  contract holds for a direct SDK caller; engine keys are uuidv7 so this never fires in practice). */
     private tryManifestPath;
     private blobPath;
     private readManifest;

package/dist/stores/file/fs-atomic.d.ts

@@ -1,34 +1,189 @@
+/**
+ * Validate an engine-minted id (sessionId / tool-result ref) before using it as a path component. These are
+ * `uuidv7` / `tr_<sessionId>_<toolCallId>` — already filename-safe — but a strict guard is cheap
+ * defense-in-depth: reject `.`/`..`/empty/separators so nothing can traverse out of the store dir.
+ */
 export declare function sanitizePathComponent(raw: string): string;
+/**
+ * Map a model-influenced memory `scope` to a safe directory name (CC `sanitizePath` parity). Replace every
+ * non-alphanumeric run with `-`; if the result is over 200 chars, append a short content hash so two long
+ * scopes can't collide. The ORIGINAL scope is the partition key the engine passes — this only affects the
+ * on-disk dir name, never the stored data. Never `path.join` a raw scope.
+ */
 export declare function sanitizeScope(scope: string): string;
+/**
+ * Resolve the data root (CC `getClaudeConfigHomeDir` analog): `$AGENT_DATA_DIR ?? ~/.ai-agent`,
+ * NFC-normalized, and `realpath`-canonicalized once the dir exists. Creates the dir (0o700) if absent.
+ */
 export declare function resolveDataRoot(explicit?: string): string;
+/** Ensure a directory exists with 0o700 perms (idempotent). */
+/**
+ * Atomically CREATE `target` carrying `content` — it appears in ONE step already fully written, no empty/partial
+ * window. Fixes the create-then-write race (codex review BUG-1/BUG-3): a reader/pruner can see a half-written
+ * file, and a crash mid-write leaves a zero-byte target a retry would silently keep. Writes a temp in `target`'s
+ * OWN dir (same FS → `link` is atomic) + fsync, then `linkSync`-publishes it; throws `EEXIST` if `target` exists.
+ */
 export declare function writeThenLink(target: string, content: string | Uint8Array): void;
 export declare function ensureDir(dir: string): void;
+/**
+ * The 5-step atomic whole-file replace (§2.1). Skipping any of steps 3/5/6 is the classic corruption bug:
+ *  1. open a temp under `root/tmp/` (same FS → rename is atomic),
+ *  2. write the bytes,
+ *  3. fsync the DATA (else ext4 "zero-length file after crash"),
+ *  4. close → rename(tmp, target) (atomic intra-FS namespace swap),
+ *  5. fsync the containing DIRECTORY (persists the rename itself).
+ * On any failure the temp is unlinked so a crashed write leaves no scratch behind.
+ */
 export declare function atomicWriteFile(tmpDir: string, target: string, bytes: string): void;
+/**
+ * Read a JSONL file and return every COMPLETE, parseable record — the universal torn-tail recovery (§2.2):
+ *  - a trailing line with no terminating `\n` (a crash mid-write) is discarded,
+ *  - any line (interior or tail) that fails `JSON.parse` is skipped (never throws — `listRemoteAgentMetadata`
+ *    parity), so a single corrupt interior line never poisons the whole replay.
+ * A missing file → `[]`. This is why JSONL beats one big JSON blob: a torn tail can never corrupt the store.
+ *
+ * `onCorrupt` (optional, review-510 disclosure-seat family): fired once per skipped INTERIOR record so a
+ * caller-side seat can observe real corruption — a silently-skipped record is otherwise indistinguishable
+ * from "less data". The torn TAIL stays out of it by design: dying mid-write is the documented crash
+ * shape this format exists to absorb, not corruption. The callback is invoked as given — a seat that
+ * must not throw swallow-guards on ITS side (the stores do).
+ */
 export declare function readJsonlRecords<T>(path: string, onCorrupt?: (info: {
     path: string;
     reason: string;
 }) => void): T[];
+/**
+ * An append-only JSONL log opened once with `O_APPEND` and held for the file's lifetime. One record =
+ * one `JSON.stringify(...) + "\n"` written in a SINGLE `writeSync` call (never split across writes → the
+ * only torn line possible is a crash tail, which {@link readJsonlRecords} drops). `fsync` is opt-in per
+ * append (the checkpoint commit point ALWAYS fsyncs; session/memory cadence is the caller's `fsyncEvery`).
+ */
+/**
+ * RB-144 (2026-07-25, 按面收口): THE canonical key for "one authority per physical location".
+ *
+ * Every file backend keeps a module-level table so that N instances over one directory collapse into one
+ * CAS authority. Getting the KEY wrong reopens the exact defect the table exists to close — and this repo
+ * has now paid for that four separate times: RB-62 taught the mailbox to realpath, RB-101 taught the
+ * session store, RB-119 added case folding there, and a defect hunt then found the agent store, the run store
+ * and the task-list still keying on a lexical `resolve()` while two of them cite the mailbox as the
+ * precedent they copied. Point fixes kept missing siblings, so the rule now lives in ONE place that all of
+ * them call.
+ *
+ * Two normalizations, each for a demonstrated failure:
+ *  - REALPATH — a symlinked data dir (`/var` → `/private/var` on macOS, a container bind-mount, a linked
+ *    `~/.ai-agent`) otherwise yields two authorities for one directory, and both writers win the CAS.
+ *  - CASE FOLD — on a case-insensitive filesystem (macOS/Windows default) `Foo/` and `foo/` are the same
+ *    directory; `realpath` does NOT fold case there, so realpath alone is not enough (measured).
+ *
+ * The key is used ONLY for table lookup — never for I/O, so the on-disk name stays verbatim. A path that
+ * does not exist yet resolves through its parent directory; if even that fails, the lexical form is used
+ * (a store must not fail to construct because canonicalization is unavailable).
+ */
 export declare function canonicalStoreKey(p: string): string;
 export declare class AppendLog {
     private fd;
+    /**
+     * RB-167 (2026-07-26): distinguishes "closed because the holder is done with it" from "closed for a
+     * compaction swap". Only the first is permanent.
+     *
+     * Every store that compacts does close → rewrite → reopen, and the rewrite can fail (EACCES, ENOSPC, a
+     * read-only mount, an immutable flag). The stores handled that in three different and individually
+     * insufficient ways: three of them left the log CLOSED FOREVER, so one transient I/O error turned into
+     * `log_closed` on every later write — and because these logs are now SHARED per directory, that bricks
+     * every instance on it, not just the one that compacted. The fourth reopened in a `finally`, which only
+     * covers the failure shapes where reopening still works and, worse, replaces the original error with the
+     * reopen's own when it does not.
+     *
+     * The reopen therefore belongs here, lazily: a swap-closed log reopens on its next write, so a fault that
+     * has cleared simply resolves itself, a fault that has not surfaces at the write (with its own error, the
+     * original having already propagated from the compaction), and `close()` keeps meaning exactly what
+     * RB-99 made it mean.
+     */
     private disposed;
     private readonly path;
+    /**
+     * RB-438 — the file size as of the end of THIS log's last successful append (or of the last time it
+     * observed the file at a record boundary). `-1` = unknown, re-establish on the next append.
+     *
+     * It is the cheap arbiter for "did the file change under us since we last left it whole": equal ⇒
+     * nothing to check, different ⇒ read the last byte and repair if it is not a newline. See
+     * {@link repairTornTail}.
+     */
     private boundary;
     constructor(path: string);
     private sizeOrUnknown;
+    /**
+     * RB-438 (2026-07-31, hardening probe R2) — re-establish the last-complete-record boundary before a write.
+     *
+     * The constructor's {@link truncateTornTail} (and the RB-167 lazy reopen) only ever ran at OPEN time, and
+     * the RB-66 loop below only repairs a SHORT write — not a `writeSync` that THROWS mid-loop (ENOSPC/EDQUOT/
+     * EIO after a partial `write(2)`, the classic full-volume shape) and not the `n <= 0` guard. Both leave
+     * `written` bytes on disk with no terminating newline while the fd and this object stay live, and every
+     * caller retries through the SAME AppendLog (`FileSessionStorage.appendEntry` throws before `recordEntry`,
+     * so the in-memory leaf is unchanged and the CAS retry appends again). The retry's record was then GLUED
+     * onto the remnant, so replay dropped BOTH — after that second append had returned and fsync'd. Measured:
+     * records [1,2,3] + a torn remnant + appends 5,6 replayed as [1,2,3,6].
+     *
+     * Cost on the healthy path is ONE `fstat` per append (the sizes match and we return); the whole-file read
+     * only happens when the file actually moved off a boundary. A legitimate concurrent appender (another
+     * process under the boot-lock handoff) leaves the file newline-terminated, so it is adopted, not truncated.
+     */
     private repairTornTail;
+    /**
+     * Append one record (`json + "\n"`). `fsync:true` makes the record durable before return.
+     *
+     * RB-66 (2026-07-25, red probe): `writeSync(fd, string)` issues ONE write(2) and may SHORT-WRITE — the
+     * same defect class this file's own `writeThenLink` already documents and fixed ("silently SHORT-WRITES
+     * (codex/Opus review B1)"), never propagated to this shared primitive. A short write here leaves a torn
+     * line with no trailing newline, so the NEXT append concatenates onto it and replay drops BOTH records.
+     * Loop until every byte lands (write(2) returns how many it took) — the O_APPEND atomicity per call is
+     * unchanged, and a genuine I/O error still throws.
+     */
     append(record: unknown, fsync: boolean): void;
     close(): void;
+    /**
+     * RB-167 — release the descriptor for a compaction SWAP. The next write reopens it lazily.
+     *
+     * Callers must use this rather than `close()` around a rewrite: `close()` means "this log is finished",
+     * and a store that used it for a swap and then failed to rewrite left the log permanently unusable —
+     * one transient I/O error becoming a permanent brick, shared by every instance on that directory.
+     */
     closeForSwap(): void;
     private releaseFd;
 }
+/**
+ * The SINGLE coarse boot guard (§2.4): an `O_EXCL` PID file at `root/LOCK` that forbids two processes
+ * sharing a data dir. A second instance fails fast ("another instance owns this data dir"). A STALE lock
+ * (the writing PID is dead) is pruned and re-acquired — `proper-lockfile`/CC `concurrentSessions` parity.
+ *
+ * This is the ONLY legitimate file lock in the backend: the once-only CAS is in-process (one event loop +
+ * a per-token async mutex), so there is NO per-operation flock — this fence just guarantees the
+ * in-process model's premise (a single writer to the dir) holds. Cross-process CORRECT concurrency is the
+ * Pg/TiDB backend's job, by design.
+ */
 export declare class BootLock {
     private readonly lockPath;
     private held;
     constructor(lockPath: string);
+    /** Acquire the lock or throw. Prunes a stale lock whose recorded PID is not running. */
     acquire(): void;
     private writeLock;
     private readLockPid;
+    /** Release the lock (only if we hold it). Best-effort; never throws. */
     release(): void;
 }
+/**
+ * design/84 Seam B (TOC profile) — a per-scope CONSOLIDATION lock factory for the file backend's
+ * {@link import("../../core/consolidate-scope.js").ConsolidateScopeDeps.acquire} injection point. A single
+ * machine may run a periodic-consolidation timer AND a task-end inline pass concurrently; this advisory lock
+ * stops two processes consolidating the SAME scope at once (the in-process model the file backend assumes —
+ * see {@link BootLock} — does not cover a second OS process with its own timer).
+ *
+ * `acquire(scope)` writes `lockDir/<sanitizedScope>.consolidate.lock` carrying THIS pid (atomic
+ * {@link writeThenLink}, so the lock appears with its pid already in it — no empty-window prune race). It
+ * returns a `release` callback on success, or `undefined` when a LIVE owner already holds it (the caller
+ * treats `undefined` as "busy → skip this pass", a no-op). A STALE lock (recorded pid is dead) is pruned and
+ * re-acquired once. The implementation lives HERE (the deployment shell's persist/exec axis), NOT core — core
+ * only DEFINES the injection point (the constitutional split: gate-presence in core, mechanism in the profile).
+ */
 export declare function createFileConsolidationLock(lockDir: string): (scope: string) => (() => void) | undefined;

package/dist/stores/file/index.d.ts

@@ -18,38 +18,127 @@ export { FileWorkflowJournalStore, MAX_JOURNAL_RESULT_BYTES, oversizeJournalResu
 export { FileUsageWindowStore } from "./usage-window-store.js";
 export { resolveDataRoot, sanitizeScope, sanitizePathComponent, createFileConsolidationLock } from "./fs-atomic.js";
 export { atomicWriteFile, writeThenLink, ensureDir, readJsonlRecords, AppendLog } from "./fs-atomic.js";
+/**
+ * design/80 — the file-backed `StorageBackend` for the local (TOC) single-user binary: the 3rd store impl
+ * alongside `InMemory*` and `Pg*`, selected purely by what the embedder injects into `RunnerDeps` (no engine
+ * change). Construct one over a single data root and pass its four members straight into `RunnerDeps`:
+ *
+ * ```ts
+ * const backend = new FileStorageBackend(); // ~/.ai-agent (or $AGENT_DATA_DIR)
+ * const runner = new Runner({
+ *   brain,
+ *   sessionStore: backend.sessionStore,
+ *   checkpointStore: backend.checkpointStore,
+ *   memoryStore: backend.memoryStore,
+ *   toolResultStore: backend.toolResultStore,
+ * });
+ * // …on shutdown:
+ * await backend.dispose();
+ * ```
+ *
+ * **Single-instance-per-data-dir (§2.4 / §7 decision 4):** the constructor takes a coarse boot `flock` on
+ * `root/LOCK`. A second `FileStorageBackend` over the same dir FAILS FAST ("another instance owns this data
+ * dir"); a stale lock from a dead PID is pruned. This is the ONLY file lock here — the once-only checkpoint
+ * CAS is in-process (one event loop), so there is no per-operation lock. Cross-process correct concurrency
+ * is the Pg/TiDB backend's job, by design.
+ */
 export interface FileStorageBackendOptions {
+    /** Data root. Default `$AGENT_DATA_DIR ?? ~/.ai-agent`, NFC-normalized + realpath-canonicalized. */
     root?: string;
+    /** Profile-injected promotable-write gate (design/77 §2). Threaded into `guardedMemoryStore`. */
     utilityGate?: UtilityGate;
+    /** `TtlSessionStore` idle-eviction policy. Default `"forget"` (§7 decision 5 — durable history is never
+     *  deleted by an idle timer). */
     evict?: EvictPolicy;
+    /** Checkpoint store tuning (fsync cadence for `put`, ledger compaction threshold). */
     checkpoint?: FileCheckpointStoreOptions;
+    /** design/101 §E19 — file-snapshot enumerator bounds (maxFiles/maxBytes/ignoreDirs). Default
+     *  {@link DEFAULT_SNAPSHOT_BOUNDS}. */
     snapshotBounds?: Partial<import("../../core/file-snapshot-store.js").FileSnapshotBounds>;
+    /** design/81 Slice 5 — an optional {@link import("../../core/memory.js").Embedder}. Injected ⇒ the memory
+     *  store does portable (in-process) vector recall over a rebuildable sidecar index (`vectorMode:"portable"`);
+     *  absent ⇒ the lexical floor, byte-identical to before. Config-driven (the deployment injects it); OFF by
+     *  default. 🔴 the consolidation band `{0.05,0.3}` is tuned for the lexical distance — a real embedding model
+     *  needs it re-tuned + a no-mis-merge live check BEFORE production-enable (design/81 Slice 5 release gate). */
     embedder?: import("../../core/memory.js").Embedder;
+    /**
+     * Disclosure sink for a durable read this backend's stores treat as ABSENT because the bytes were
+     * corrupt or unreadable (never fires on plain ENOENT — real absence).
+     *
+     * Why it lives on the BACKEND options and not only on the individual store: the fail-open it discloses
+     * exists for the DEFAULT deployment (a corrupt policy file yields an apparently normal, UNCONSTRAINED
+     * task), and the default deployment constructs its stores through this one-argument constructor — the
+     * per-store constructor parameter was unreachable from here, so the disclosure was wired exactly
+     * nowhere for the deployments that need it most.
+     *
+     * Reach TODAY: {@link FileStorageBackend.sessionPolicyStore} (rules read as ABSENT ⇒ an unconstrained
+     * task), {@link FileStorageBackend.sessionStore}'s repo (a session listing that silently omits what it
+     * could not read) and {@link FileStorageBackend.fileSnapshotStore} (a snapshot/scope read as missing,
+     * and a blob GC that aborted). The roster and CC-mailbox stores also carry the seat, but a deployment
+     * builds those itself and passes the sink directly. A store that grows the seat later is wired here in
+     * the same constructor.
+     *
+     * The payload is the UNION shape ({@link FileStorageCorruptReadInfo}): `path` + `reason` always,
+     * with the session-policy face's `sessionId`/`principal` present only when the reading store keys by
+     * them. One sink for one failure grammar — a host does not register three.
+     */
     onCorruptRead?: (info: FileStorageCorruptReadInfo) => void;
 }
+/**
+ * The payload of {@link FileStorageBackendOptions.onCorruptRead} — the widest shape any store this
+ * backend constructs can deliver, so ONE sink reaches all of them (a per-store payload type would make
+ * the backend's forwarding contravariance-illegal, which is what kept the seat single-store).
+ * `SessionPolicyCorruptReadInfo` is assignable to it; the two-field store seats are satisfied by it.
+ */
 export interface FileStorageCorruptReadInfo {
+    /** Absolute path of the offending file/directory. */
     path: string;
+    /** What was observed and what the read degraded to. */
     reason: string;
+    /** Present only when the reading store keys by session (the session-policy face). */
     sessionId?: string;
+    /** Present only when the read was keyed by a principal. */
     principal?: string;
 }
 export declare class FileStorageBackend {
+    /** The resolved, canonical data root all four stores live under. */
     readonly root: string;
     readonly sessionStore: SessionStore;
     readonly checkpointStore: CheckpointStore;
+    /** Wrapped in `guardedMemoryStore` (Gate-2 chokepoint). design/81: implements the id-addressable trio on
+     *  a lexical cosine-distance → `supportsConsolidation` is true → end-of-task consolidation lights up. */
     readonly memoryStore: MemoryStore;
     readonly toolResultStore: ToolResultStore;
+    /** design/99 §E6 — file-backed per-session permission rules (E6). Wire into `RunnerDeps.sessionPolicyStore`
+     *  for a local deployment that needs session rules to survive a restart. */
     readonly sessionPolicyStore: SessionPolicyStore;
+    /** design/101 §E19 — file-backed working-tree snapshots (rewind-files). Wire into
+     *  `RunnerDeps.fileSnapshotStore`. Content-addressed blobs persist across restarts (local-only; a remote env
+     *  defers rewind to its own VM-snapshot backend). */
     readonly fileSnapshotStore: FileSnapshotStore;
+    /** SVC-2 / [381]⑥ (onboarded per [375]) — file-backed durable workflow resume journal. Wire into
+     *  `RunnerDeps.workflowJournalStore` so `resumeFromRunId` survives a process restart on a TOC box. */
     readonly workflowJournalStore: WorkflowJournalStore;
+    /** design/164 件五 — file-backed cross-task usage-governance ledger. Wire into
+     *  `RunnerDeps.usageWindowStore` so a deployment's `usageWindows` survive a restart (an in-memory
+     *  ledger silently re-grants every allowance on every boot). */
     readonly usageWindowStore: UsageWindowStore;
+    /**
+     * design/84 Seam B (TOC) — the per-scope consolidation lock for `consolidateScope`'s `acquire` injection
+     * point: `consolidateScope(scope, { store: backend.memoryStore, llm, acquire: backend.consolidationLock })`.
+     * Stops two OS processes sharing this data dir from consolidating the SAME scope at once (a busy scope ⇒
+     * `undefined` ⇒ the pass is a no-op). The locks live under `root/consolidation-locks/`.
+     */
     readonly consolidationLock: (scope: string) => (() => void) | undefined;
     private readonly lock;
     private readonly fileCheckpoints;
     private readonly fileMemory;
     private readonly ttl;
+    /** RB-437 — kept so {@link dispose} can release the shared per-session authorities (and their append
+     *  descriptors) this backend joined; `TtlSessionStore.dispose()` only clears the sweep timer. */
     private readonly fileSessions;
     private readonly fileWorkflowJournal;
     constructor(opts?: FileStorageBackendOptions);
+    /** Release file handles + the boot lock (best-effort). Call on shutdown so a successor can acquire. */
     dispose(): Promise<void>;
 }

package/dist/stores/file/mailbox-store.d.ts

@@ -1,7 +1,13 @@
 import { type MailboxAppendMessage, type MailboxLease, type MailboxStore } from "../../core/mailbox-store.js";
 export interface FileMailboxStoreOptions {
+    /** When false, ledger appends are NOT fsync'd. Default true. */
     fsync?: boolean;
+    /** Compact a box's event log into a snapshot-form log once it exceeds this many events. Default 500. */
     compactEvery?: number;
+    /** Disclosure seat (review-510 family; server pickup receipt named this store's gap): a corrupt
+     *  INTERIOR record dropped by the JSONL replay is disclosed here instead of silently reading as
+     *  "less mail". The torn tail stays silent by design — that is the append-log's documented
+     *  crash-recovery shape, not corruption. Swallow-guarded; absent = the old silent tolerance. */
     onCorruptRead?: (info: {
         path: string;
         reason: string;
@@ -12,10 +18,39 @@ export declare class FileMailboxStore implements MailboxStore {
     private readonly tmpDir;
     private readonly fsyncEnabled;
     private readonly compactEvery;
+    /** Paths THIS instance has touched → the EXACT BoxState it took a ref on (server[1523] 对等复审
+     *  发现1: after a drop/reap deletes the shared box, another instance's stale close() must not
+     *  decrement a REBUILT box's refs — identity is checked, not just the path). */
     private readonly touched;
+    /** The swallow-guarded corrupt-read seat (undefined = the old silent tolerance). */
     private readonly discloseCorrupt;
     constructor(root: string, opts?: FileMailboxStoreOptions);
+    /**
+     * RB-67 (2026-07-25, red probe): the on-disk name is CASE-FOLDED, so the in-memory key and the physical
+     * file can never disagree. Before this, `AgentOne` and `agentone` produced two DIFFERENT shared-state
+     * keys but the SAME file on a case-insensitive filesystem (macOS/Windows default) — one recipient read
+     * the other's messages after a restart. Folding is also the semantically correct answer, not just the
+     * safe one: the addressing layer's `normalizeAgentName` (task-registry.ts:621) already lowercases, so
+     * two case-variant handles ARE the same agent; this makes the storage layer say so explicitly instead of
+     * depending on an upstream coincidence, and behave identically on case-SENSITIVE filesystems (Linux),
+     * where the old code silently split one logical agent's mail across two boxes.
+     */
     private boxPath;
+    /**
+     * The canonical mutex / shared-state key — instance-independent (X-5).
+     *
+     * RB-162 (2026-07-26): this went through `realpath` (RB-62) but NOT the case fold (RB-67/RB-119), even
+     * though the module header above claims "the shared-state KEY goes through `canonicalStoreKey`, which
+     * also folds case". It did not — that name appeared exactly once in this file, inside that sentence.
+     * The handle component was folded by `boxPath`, but the ROOT was not: two spellings of the same
+     * directory on a case-insensitive filesystem produced two shared-state slots over one physical file, and
+     * each allocated its own `seq` — the very contract violation the realpath comment above describes,
+     * reached by the other half of the same canonicalization.
+     *
+     * Worse for the record: the enumerative guard written for this exact family tested
+     * `src.includes("canonicalStoreKey")`, which that one comment satisfied. The guard was green because the
+     * file talked about the rule.
+     */
     private lockKey;
     private load;
     private commit;
@@ -29,5 +64,6 @@ export declare class FileMailboxStore implements MailboxStore {
     reap(scope: string, now: number, opts?: {
         maxAgeMs?: number;
     }): Promise<number>;
+    /** Release THIS instance's share of the box handles (fd closes when the last instance leaves). */
     close(): void;
 }

package/dist/stores/file/mailbox-store.js

@@ -1,4 +1,5 @@
 import { join, resolve, sep } from "node:path";
+import { assertRetentionPolicy } from "../../core/retention-policy.js";
 import { existsSync, readdirSync, realpathSync } from "node:fs";
 import { newestSentAt, } from "../../core/mailbox-store.js";
 import { AppendLog, atomicWriteFile, canonicalStoreKey, ensureDir, readJsonlRecords, sanitizeScope, sanitizePathComponent } from "./fs-atomic.js";
@@ -176,6 +177,7 @@ export class FileMailboxStore {
         });
     }
     async reap(scope, now, opts) {
+        assertRetentionPolicy("MailboxStore.reap", opts);
         if (opts?.maxAgeMs === undefined)
             return 0;
         let dropped = 0;