@sema-agent/core 5.53.0 → 5.54.0

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

@@ -3,6 +3,7 @@ import { BackgroundAgentStoreError, STALE_RUNNING_REAP_ATTRIBUTION, assertBackgr
 import { SharedLedgerTable } from "./shared-ledger.js";
 import { assertAdoptionBootGate } from "./adoption/marker.js";
 const agentLedgers = new SharedLedgerTable({
+    label: "background-agent ledger",
     keyOf: (r) => FileBackgroundAgentStore.key(r.handle, r.scope),
     apply: (rows, ev) => {
         if (ev.t === "delete") {

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

@@ -11,7 +11,9 @@ 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. */
+     *  single-instance-per-data-dir, and now SELF-ENFORCING about it: the constructor takes the ledger
+     *  directory's writer fence and refuses a second OS process by name (see the class header). Serving
+     *  many writers at once remains Pg/TiDB's job — this refuses the second one, it does not coordinate it. */
     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
@@ -62,7 +64,9 @@ export declare class FileCheckpointStore implements CheckpointStore {
     /** 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.
+     * Release the append handle (best-effort). The LAST holder over the directory also drops its
+     * cross-process writer fence, so a successor process can open the same data root; the data-dir-wide
+     * `root/LOCK` (a different fence) stays the backend factory's to release.
      *
      * 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

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

@@ -56,6 +56,7 @@ function applyCheckpointEvent(cps, ev) {
     }
 }
 const checkpointLedgers = new SharedLedgerTable({
+    label: "checkpoint ledger",
     keyOf: (cp) => cp.token,
     apply: applyCheckpointEvent,
 });

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

@@ -151,27 +151,168 @@ export declare class AppendLog {
     closeForSwap(): void;
     private releaseFd;
 }
+/** Why a {@link BootLock}/{@link acquireStoreDirLock} acquisition was refused, as a branchable code. */
+export type FileStoreLockErrorCode = 
+/** A LIVE process (this one or another) already holds the directory. Steady state: it ends when that
+ *  process ends. */
+"store.dir_in_use"
+/** Another process is mid-RECLAIM of a lock left by a crashed owner. Transient by construction — the
+ *  claimant either finishes (and then owns the directory) or dies (and its gate is pruned in turn), so
+ *  the honest advice here is "retry", NOT the "stop the other process" that `dir_in_use` earns. */
+ | "store.dir_claiming"
+/** The lock is in a state only a human should resolve — no parseable owner, or buried under nested
+ *  reclaim gates from repeated crashes. Never pruned blindly; the message names what to remove. */
+ | "store.lock_unreadable";
 /**
- * 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.
+ * The structured refusal of a file-store directory fence. Carried as a class (not a bare `Error`) so a
+ * host can branch on {@link code} — "someone else owns this data dir" is an operator-actionable
+ * condition (stop the other process / pick another root / move to a SQL backend), and telling it apart
+ * from a genuine I/O failure by string-matching a message is exactly the fragility the codes exist to
+ * remove. The messages are unchanged from the pre-code era, so existing text assertions still hold.
+ */
+export declare class FileStoreLockError extends Error {
+    readonly code: FileStoreLockErrorCode;
+    /** The lock file whose acquisition was refused. */
+    readonly lockPath: string;
+    /** The live owner's pid when the lock named one (absent for an unreadable lock or a lost race). */
+    readonly ownerPid?: number | undefined;
+    readonly name = "FileStoreLockError";
+    constructor(code: FileStoreLockErrorCode, message: string, 
+    /** The lock file whose acquisition was refused. */
+    lockPath: string, 
+    /** The live owner's pid when the lock named one (absent for an unreadable lock or a lost race). */
+    ownerPid?: number | undefined);
+}
+/**
+ * The coarse boot guard (§2.4): an `O_EXCL` PID file (`root/LOCK` for the whole data dir; one per store
+ * ledger directory via {@link acquireStoreDirLock}) that forbids two processes sharing it. 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.
+ * This is the family's ONE lock MECHANISM (the per-operation CAS stays in-process: one event loop + a
+ * per-token async mutex, so there is NO per-operation flock). A holder of one of these fences guarantees
+ * the in-process model's premise — a single writer to the directory — actually holds. Cross-process
+ * CORRECT concurrency (many writers at once) is still the Pg/TiDB backend's job, by design: this fence
+ * refuses the second writer, it does not coordinate it.
  */
 export declare class BootLock {
     private readonly lockPath;
     private held;
+    /** The verdict of the ONE release this holding gets, replayed to any later caller (see {@link release}). */
+    private spentVerdict;
     constructor(lockPath: string);
-    /** Acquire the lock or throw. Prunes a stale lock whose recorded PID is not running. */
+    /** Acquire the lock or throw. Reclaims a lock whose recorded PID is not running (see below). */
     acquire(): void;
+    /**
+     * @param depth how many stale reclaim gates deep we already are (see the gate below). Bounded so a
+     *  pathological chain demands an operator instead of recursing without end.
+     */
+    private acquireWithin;
+    /** Publish our lock, or say out loud that a fresh contender got there first. */
+    private publishOrLoseRace;
+    /** Take back a lock THIS process published and could not remove on release (never someone else's). */
+    private pruneOwnAbandoned;
     private writeLock;
-    private readLockPid;
-    /** Release the lock (only if we hold it). Best-effort; never throws. */
+    /**
+     * Key for the {@link abandonedLocks} registry: the RESOLVED path, deliberately NOT case-folded. Folding
+     * (as the store-table key does) would alias `/data/foo/LOCK` and `/data/Foo/LOCK` — two genuinely
+     * different files on a case-sensitive filesystem — and this registry authorizes a DELETE. Missing an
+     * entry costs a loud refusal; a false hit costs someone else's lock.
+     */
+    private get abandonKey();
+    /**
+     * Read the lock as one of three ANSWERS, never as one "undefined" that means all of them: absent (nobody
+     * holds it), a named owner, or unreadable. Collapsing the last two is what let a release that could not
+     * even READ the file report the lock as gone — after which the bookkeeping was dropped while the file
+     * still named this process, and the directory was refused for the rest of the process's life.
+     */
+    private inspectLock;
+    /**
+     * Release the lock (only if we hold it), ONCE. Best-effort; never throws.
+     *
+     * @returns whether the lock is now GONE — removed, or provably somebody else's. A `false` means the file
+     * is still there and this process cannot prove it is not the owner of record, which the caller must not
+     * treat as released: every later acquisition would read a live owner (us) and refuse a directory nobody is
+     * using. The path is remembered as ABANDONED so a later acquisition in this process can take it back
+     * rather than refuse a directory nobody is using — a lock carrying our own pid can only be ours
+     * ({@link pruneOwnAbandoned} removes and republishes it; {@link resumeAbandoned} re-arms a holder over
+     * the file as it stands).
+     *
+     * ONE-SHOT, and that is load-bearing. This object stops being a holder the moment it is ASKED to release
+     * — before the filesystem is touched — and a second call REPEATS the first verdict instead of acting on
+     * it again. A lock file is a bare pid, so two BootLocks over one path in this process are byte-identical
+     * on disk: after a FAILED release the path can legitimately be re-published (a later acquisition here
+     * finishing our cleanup), and a stale object that "removed its own lock" a second time would be deleting
+     * the SUCCESSOR's fence while both sides believed they held the directory — the double-writer this whole
+     * mechanism exists to refuse, minted from bookkeeping instead of from a race. So a second release answers
+     * the first question again and touches nothing.
+     */
+    release(): boolean;
+    /**
+     * The filesystem half of {@link release}: remove the lock while the file still names US, and report what
+     * the directory looks like AFTERWARDS (never what we intended).
+     *
+     * "Still names us" is a READ, and `unlink` cannot be made conditional on content — so, exactly as in
+     * {@link resumeAbandoned}, an external removal landing between the two lets this delete a file that is no
+     * longer the one we read. That is the advisory-pid-file mechanism's exposure, identical for every holder
+     * and every moment of a holding, not something this ordering introduces; the re-inspection below is why
+     * the ANSWER stays honest even then.
+     */
+    private removeOwnLock;
+    /**
+     * Resume holding a lock THIS process published and could not remove on release — the state a zero-ref
+     * entry in {@link acquireStoreDirLock}'s table is in, and the only way a joiner may ride that entry.
+     *
+     * Pure INSPECTION of the disk: it publishes nothing and removes nothing. The claim is honoured only
+     * when the file still there is the one we left (our own pid) AND no publish on this path has spent the
+     * abandoned note since — any successful publish (ours, or a reclaim) makes some OTHER object the holder,
+     * and re-arming here would put two holders on one path, exactly what one-shot {@link release} closes. A
+     * `false` says the bookkeeping can no longer be trusted and the caller must go back to the disk: the
+     * file may have been cleared (an operator, a tmp cleaner) and the directory since taken by another
+     * OS process.
+     *
+     * A successful resume SPENDS the note, for the same reason a successful publish does: the note is what
+     * authorizes {@link pruneOwnAbandoned} to DELETE this file, and while somebody holds the path that
+     * authorization must not exist — a second acquisition here is a genuine conflict that has to be refused
+     * by name, not a leftover to be cleaned up over a live holder. A later failed release writes it again.
+     *
+     * What a `true` establishes, exactly: the file was the one we left AT THE MOMENT WE LOOKED. It is not an
+     * atomic handoff and cannot be — this fence is an advisory pid FILE, so nothing stops an operator (or a
+     * tmp cleaner) from removing it the instant after any check, here or hours into an ordinary holding, and
+     * a foreign process publishing over the gap. That exposure belongs to the mechanism and is the same for
+     * a fence nobody ever released; what this check removes is the far wider window in which the removal
+     * already happened and the table would have kept vouching for it anyway. The branch where the file is
+     * ALREADY gone is not re-armed here at all: it falls through to a real acquisition, whose `O_EXCL`
+     * publish is the atomic test-and-set, and a foreign owner there is refused by name.
+     */
+    resumeAbandoned(): boolean;
+}
+/** One holder's share of a directory fence. Releasing is idempotent and only the LAST share unlinks. */
+export interface StoreDirLockLease {
+    /** The lock file this share is counted against (inspection/tests). */
+    readonly lockPath: string;
+    /** Drop this share. The lock file survives until every share over the directory is released. */
     release(): void;
 }
+/**
+ * Take (or JOIN) the cross-process writer fence for one store directory.
+ *
+ * The file family's premise everywhere is "one writer per data directory"; before this, the ONLY thing
+ * enforcing it was the `root/LOCK` a `FileStorageBackend` takes — which a store constructed directly
+ * (every one of them is a root export) never sees, and which never covered a store the backend does not
+ * construct at all. A second OS process then replayed a PRIVATE view of the same ledger: both sides win
+ * a once-only CAS, and the one that never loaded the other's rows ERASES them at its next compaction.
+ * So the fence belongs to the directory that holds the authority, taken by whoever opens it.
+ *
+ * Semantics: exclusive across PROCESSES (a live foreign owner ⇒ {@link FileStoreLockError} naming the
+ * pid; a dead owner's lock is pruned as stale), refcount-JOINED inside this process (siblings over one
+ * directory share the fence, and the last {@link StoreDirLockLease.release} unlinks it). `dir` must
+ * already exist (the caller's `ensureDir`), since the fence lives inside it.
+ */
+export declare function acquireStoreDirLock(dir: string, opts: {
+    label: string;
+    fileName?: string;
+}): StoreDirLockLease;
 /**
  * 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

package/dist/stores/file/fs-atomic.js

@@ -255,71 +255,247 @@ function truncateTornTail(path) {
     const lastNl = raw.lastIndexOf("\n");
     truncateSync(path, lastNl === -1 ? 0 : Buffer.byteLength(raw.slice(0, lastNl + 1), "utf8"));
 }
+export class FileStoreLockError extends Error {
+    code;
+    lockPath;
+    ownerPid;
+    name = "FileStoreLockError";
+    constructor(code, message, lockPath, ownerPid) {
+        super(message);
+        this.code = code;
+        this.lockPath = lockPath;
+        this.ownerPid = ownerPid;
+    }
+}
+const MAX_RECLAIM_DEPTH = 8;
+const MAX_ACQUIRE_ATTEMPTS = 4;
+const abandonedLocks = new Set();
 export class BootLock {
     lockPath;
     held = false;
+    spentVerdict;
     constructor(lockPath) {
         this.lockPath = lockPath;
     }
     acquire() {
-        try {
-            this.writeLock();
-            this.held = true;
-            return;
-        }
-        catch (err) {
-            if (err.code !== "EEXIST")
+        this.acquireWithin(0);
+    }
+    acquireWithin(depth) {
+        for (let attempt = 0; attempt < MAX_ACQUIRE_ATTEMPTS; attempt++) {
+            try {
+                this.writeLock();
+                this.held = true;
+                abandonedLocks.delete(this.abandonKey);
+                return;
+            }
+            catch (err) {
+                if (err.code !== "EEXIST")
+                    throw err;
+            }
+            const owner = this.inspectLock();
+            if (owner.state === "absent")
+                continue;
+            if (owner.state === "unreadable") {
+                throw new FileStoreLockError("store.lock_unreadable", `file store: lock file at ${this.lockPath} is unreadable/corrupt; remove it manually if it is stale`, this.lockPath);
+            }
+            if (owner.pid === process.pid && abandonedLocks.has(this.abandonKey)) {
+                this.pruneOwnAbandoned();
+                return;
+            }
+            if (isProcessRunning(owner.pid)) {
+                throw new FileStoreLockError("store.dir_in_use", `file store: another instance (pid ${owner.pid}) owns this data dir (${dirnameOf(this.lockPath)})`, this.lockPath, owner.pid);
+            }
+            if (depth >= MAX_RECLAIM_DEPTH) {
+                throw new FileStoreLockError("store.lock_unreadable", `file store: lock file at ${this.lockPath} is buried under ${depth} nested stale reclaim gates ` +
+                    `(repeated crashes mid-reclaim); remove the ${basenameOf(this.lockPath)}.claim.* files manually`, this.lockPath);
+            }
+            const gate = new BootLock(`${this.lockPath}.claim.${owner.pid}`);
+            try {
+                gate.acquireWithin(depth + 1);
+            }
+            catch (err) {
+                if (err instanceof FileStoreLockError && err.code === "store.dir_in_use" && err.ownerPid !== undefined) {
+                    throw new FileStoreLockError("store.dir_claiming", `file store: another instance${err.ownerPid !== undefined ? ` (pid ${err.ownerPid})` : ""} is claiming ` +
+                        `this data dir (${dirnameOf(this.lockPath)}) from a stale lock`, this.lockPath, err.ownerPid);
+                }
                 throw err;
+            }
+            try {
+                const under = this.inspectLock();
+                if (under.state === "owner" && under.pid === owner.pid) {
+                    try {
+                        unlinkSync(this.lockPath);
+                    }
+                    catch {
+                    }
+                }
+                else if (under.state !== "absent") {
+                    continue;
+                }
+                this.publishOrLoseRace();
+                return;
+            }
+            finally {
+                gate.release();
+            }
         }
-        const ownerPid = this.readLockPid();
-        if (ownerPid === undefined) {
-            throw new Error(`file store: lock file at ${this.lockPath} is unreadable/corrupt; remove it manually if it is stale`);
-        }
-        if (isProcessRunning(ownerPid)) {
-            throw new Error(`file store: another instance (pid ${ownerPid}) owns this data dir (${dirnameOf(this.lockPath)})`);
-        }
-        try {
-            unlinkSync(this.lockPath);
-        }
-        catch {
-        }
+        throw new FileStoreLockError("store.dir_in_use", `file store: ownership of this data dir (${dirnameOf(this.lockPath)}) kept changing under us ` +
+            `(${MAX_ACQUIRE_ATTEMPTS} attempts); another instance is starting and stopping on the same directory`, this.lockPath);
+    }
+    publishOrLoseRace() {
         try {
             this.writeLock();
             this.held = true;
+            abandonedLocks.delete(this.abandonKey);
         }
         catch (err) {
             if (err.code === "EEXIST") {
-                throw new Error(`file store: another instance won the lock race for this data dir`);
+                throw new FileStoreLockError("store.dir_in_use", `file store: another instance won the lock race for this data dir`, this.lockPath);
             }
             throw err;
         }
     }
+    pruneOwnAbandoned() {
+        try {
+            unlinkSync(this.lockPath);
+        }
+        catch (err) {
+            throw new FileStoreLockError("store.lock_unreadable", `file store: this process still owns the lock file at ${this.lockPath} from an earlier release that ` +
+                `could not remove it, and removing it now failed too (${String(err.message)}); ` +
+                `remove it manually`, this.lockPath, process.pid);
+        }
+        abandonedLocks.delete(this.abandonKey);
+        this.publishOrLoseRace();
+    }
     writeLock() {
         writeThenLink(this.lockPath, String(process.pid));
     }
-    readLockPid() {
+    get abandonKey() {
+        return resolvePath(this.lockPath);
+    }
+    inspectLock() {
+        let raw;
         try {
-            const raw = readFileSync(this.lockPath, "utf8").trim();
-            if (!/^[1-9][0-9]*$/.test(raw))
-                return undefined;
-            const pid = Number.parseInt(raw, 10);
-            return Number.isInteger(pid) && pid > 0 ? pid : undefined;
+            raw = readFileSync(this.lockPath, "utf8").trim();
         }
-        catch {
-            return undefined;
+        catch (err) {
+            return err.code === "ENOENT" ? { state: "absent" } : { state: "unreadable" };
         }
+        if (!/^[1-9][0-9]*$/.test(raw))
+            return { state: "unreadable" };
+        const pid = Number.parseInt(raw, 10);
+        return Number.isInteger(pid) && pid > 0 ? { state: "owner", pid } : { state: "unreadable" };
     }
     release() {
-        if (!this.held)
-            return;
+        if (!this.held) {
+            return this.spentVerdict ?? true;
+        }
         this.held = false;
+        this.spentVerdict = this.removeOwnLock();
+        return this.spentVerdict;
+    }
+    removeOwnLock() {
+        const before = this.inspectLock();
+        if (before.state === "absent" || (before.state === "owner" && before.pid !== process.pid)) {
+            abandonedLocks.delete(this.abandonKey);
+            return true;
+        }
+        if (before.state === "unreadable") {
+            abandonedLocks.add(this.abandonKey);
+            return false;
+        }
         try {
-            if (this.readLockPid() === process.pid)
-                unlinkSync(this.lockPath);
+            unlinkSync(this.lockPath);
         }
         catch {
         }
+        const after = this.inspectLock();
+        const gone = after.state === "absent" || (after.state === "owner" && after.pid !== process.pid);
+        if (gone)
+            abandonedLocks.delete(this.abandonKey);
+        else
+            abandonedLocks.add(this.abandonKey);
+        return gone;
+    }
+    resumeAbandoned() {
+        if (this.held)
+            return true;
+        if (!abandonedLocks.has(this.abandonKey))
+            return false;
+        const owner = this.inspectLock();
+        if (owner.state !== "owner" || owner.pid !== process.pid)
+            return false;
+        this.held = true;
+        this.spentVerdict = undefined;
+        abandonedLocks.delete(this.abandonKey);
+        return true;
+    }
+}
+const heldStoreDirLocks = new Map();
+export function acquireStoreDirLock(dir, opts) {
+    const fileName = opts.fileName ?? "LOCK";
+    const lockPath = join(dir, fileName);
+    const key = `${fileName}@${canonicalStoreKey(dir)}`;
+    const lease = (entry) => {
+        let released = false;
+        return {
+            lockPath,
+            release: () => {
+                if (released)
+                    return;
+                released = true;
+                if (heldStoreDirLocks.get(key) !== entry)
+                    return;
+                entry.refs -= 1;
+                if (entry.refs > 0)
+                    return;
+                if (entry.lock.release()) {
+                    heldStoreDirLocks.delete(key);
+                    return;
+                }
+                console.warn(`[sema] file store: the ${opts.label} directory fence at ${lockPath} could not be handed back — the ` +
+                    `removal could not be proven, so a lock file naming this live process (pid ${process.pid}) may still ` +
+                    `be there. While it is, another process opening that directory is refused by name; the next open of ` +
+                    `it in THIS process finishes the cleanup or refuses by name. After this process exits the file is ` +
+                    `reclaimed as a stale lock ONLY if it is readable and its directory writable — otherwise it has to ` +
+                    `be removed by hand.`);
+            },
+        };
+    };
+    const existing = heldStoreDirLocks.get(key);
+    if (existing !== undefined) {
+        if (existing.refs > 0 || existing.lock.resumeAbandoned()) {
+            existing.refs += 1;
+            return lease(existing);
+        }
+        heldStoreDirLocks.delete(key);
+    }
+    const lock = new BootLock(lockPath);
+    try {
+        lock.acquire();
+    }
+    catch (err) {
+        if (err instanceof FileStoreLockError) {
+            const who = err.ownerPid !== undefined ? ` (pid ${err.ownerPid})` : "";
+            const single = `This backend is SINGLE-WRITER per directory: a second process replays a private view (both sides can ` +
+                `win a once-only decision) and its next compaction erases the records it never loaded.`;
+            throw new FileStoreLockError(err.code, err.code === "store.lock_unreadable"
+                ?
+                    `file store: the ${opts.label} directory (${dir}) cannot be opened — ${err.message}`
+                : err.code === "store.dir_claiming"
+                    ?
+                        `file store: another OS process${who} is claiming this data dir — it is reclaiming the ${opts.label} ` +
+                            `directory (${dir}) from a lock a crashed owner left behind. ${single} Retry in a moment: either that ` +
+                            `process finishes and owns the directory, or it dies and the next start reclaims it.`
+                    : `file store: another OS process${who} is using the ${opts.label} directory (${dir}). ${single} Stop the ` +
+                        `other process, point this one at a different data root, or use the pg/tidb backend for real ` +
+                        `multi-process concurrency.`, err.code === "store.lock_unreadable" ? err.lockPath : lockPath, err.ownerPid);
+        }
+        throw err;
     }
+    const entry = { lock, refs: 1 };
+    heldStoreDirLocks.set(key, entry);
+    return lease(entry);
 }
 export function createFileConsolidationLock(lockDir) {
     return (scope) => {

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

@@ -22,6 +22,7 @@ export { FileWorkflowJournalStore, MAX_JOURNAL_RESULT_BYTES, oversizeJournalResu
 export { FileUsageWindowStore } from "./usage-window-store.js";
 export { FileStrategyStore, type FileStrategyStoreOptions } from "./strategy-store.js";
 export { resolveDataRoot, sanitizeScope, sanitizePathComponent, createFileConsolidationLock } from "./fs-atomic.js";
+export { FileStoreLockError, type FileStoreLockErrorCode } from "./fs-atomic.js";
 export { atomicWriteFile, writeThenLink, ensureDir, readJsonlRecords, AppendLog } from "./fs-atomic.js";
 export { AdoptionError, assertAdoptionBootGate, readRootAdoptionFile, writeRootAdoptionFile, ROOT_ADOPTION_FILE, type AdoptionErrorCode, type AdoptionSource, type AdoptionReport, type AdoptionReceipt, type AdoptionLegReport, type AffectedDeploymentConfig, type RootAdoptionFile, } from "./adoption/marker.js";
 export { adoptLocalDataRoot, ackAdoptionConfig, witnessAdoptionConfig, listAdoptionQuarantine, readAdoptionStatus, type AdoptionStatus, type AdoptLocalDataRootOptions, type AdoptLocalDataRootResult, type AdoptionCarriageLeg, type AdoptionCarriageLegContext, type AdoptionConfigWitnessReceipt, } from "./adoption/adopt.js";
@@ -45,9 +46,13 @@ export { adoptLocalDataRoot, ackAdoptionConfig, witnessAdoptionConfig, listAdopt
  *
  * **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.
+ * dir"); a stale lock from a dead PID is pruned. The once-only checkpoint CAS is in-process (one event
+ * loop), so there is still no per-operation lock. What this backend's lock does NOT cover — and never did,
+ * despite what the store docs used to say — is a store constructed DIRECTLY off the root export (or one
+ * this backend does not construct at all, like `FileWorkflowRunStore`); those now take their own
+ * per-directory writer fence at construction ({@link import("./fs-atomic.js").acquireStoreDirLock}), so
+ * the single-writer premise holds however the stores were assembled. Serving many writers CONCURRENTLY
+ * (rather than refusing the second) is the Pg/TiDB backend's job, by design.
  */
 export interface FileStorageBackendOptions {
     /** Data root. Default `$AGENT_DATA_DIR ?? ~/.ai-agent`, NFC-normalized + realpath-canonicalized. */
@@ -165,6 +170,24 @@ export declare class FileStorageBackend {
     private readonly fileSessions;
     private readonly fileWorkflowJournal;
     constructor(opts?: FileStorageBackendOptions);
+    /**
+     * The data-dir boot lock could not be handed back — a root that turned read-only under a running
+     * process, an unreadable lock file. Teardown here is best-effort by contract, but best-effort must not
+     * mean SILENT: a lock file naming a LIVE pid refuses this data root to every other process, and only
+     * somebody saying so out loud makes that operator-actionable. (The release's own answer is the seat for
+     * this — a discarded boolean was the backend never learning that the fence it took at construction was
+     * never given back.)
+     *
+     * The wording states what a FAILED release actually establishes and no more: the removal could not be
+     * proven. A repeat teardown replays that same verdict without re-reading the directory (the release is
+     * one-shot), so this must not assert the file's CURRENT contents — only the consequence while it is
+     * there, and the ways out. In particular it must NOT promise that exiting clears it: the two conditions
+     * that produce this verdict are an UNREADABLE lock (never pruned by anyone — a stale-lock reclaim has to
+     * read the pid it is reclaiming) and a directory the removal cannot write; neither is undone by the
+     * owner exiting, and "it will be cleaned up automatically" is the one sentence that turns a five-second
+     * `chmod` into an outage.
+     */
+    private discloseRetainedBootLock;
     /** Release file handles + the boot lock (best-effort). Call on shutdown so a successor can acquire. */
     dispose(): Promise<void>;
 }

package/dist/stores/file/index.js

@@ -25,6 +25,7 @@ export { FileWorkflowJournalStore, MAX_JOURNAL_RESULT_BYTES, oversizeJournalResu
 export { FileUsageWindowStore } from "./usage-window-store.js";
 export { FileStrategyStore } from "./strategy-store.js";
 export { resolveDataRoot, sanitizeScope, sanitizePathComponent, createFileConsolidationLock } from "./fs-atomic.js";
+export { FileStoreLockError } from "./fs-atomic.js";
 export { atomicWriteFile, writeThenLink, ensureDir, readJsonlRecords, AppendLog } from "./fs-atomic.js";
 export { AdoptionError, assertAdoptionBootGate, readRootAdoptionFile, writeRootAdoptionFile, ROOT_ADOPTION_FILE, } from "./adoption/marker.js";
 export { adoptLocalDataRoot, ackAdoptionConfig, witnessAdoptionConfig, listAdoptionQuarantine, readAdoptionStatus, } from "./adoption/adopt.js";
@@ -56,6 +57,7 @@ export class FileStorageBackend {
         assertAdoptionBootGate(this.root, "FileStorageBackend");
         this.lock = new BootLock(join(this.root, "LOCK"));
         this.lock.acquire();
+        const built = [];
         try {
             const corruptRead = opts.onCorruptRead !== undefined ? { onCorruptRead: opts.onCorruptRead } : undefined;
             const repo = new FileSessionRepo(this.root, corruptRead);
@@ -63,18 +65,23 @@ export class FileStorageBackend {
             this.ttl = new TtlSessionStore({ repo, evict: opts.evict ?? "forget", durability: "durable", placements: { subagent: { durability: "durable" } } });
             this.sessionStore = this.ttl;
             this.fileCheckpoints = new FileCheckpointStore(this.root, opts.checkpoint);
+            built.push(() => this.fileCheckpoints.close());
             this.checkpointStore = this.fileCheckpoints;
             this.fileMemory = new FileMemoryStore(this.root, opts.embedder ? { embedder: opts.embedder } : {});
+            built.push(() => this.fileMemory.close());
             this.memoryStore = guardedMemoryStore(this.fileMemory, opts.utilityGate);
             this.toolResultStore = new FileToolResultStore(this.root);
             this.sessionPolicyStore = new FileSessionPolicyStore(this.root, corruptRead);
             this.fileSnapshotStore = new FileFileSnapshotStore(this.root, opts.snapshotBounds, corruptRead);
             this.fileWorkflowJournal = new FileWorkflowJournalStore(this.root);
+            built.push(() => this.fileWorkflowJournal.dispose());
             this.workflowJournalStore = this.fileWorkflowJournal;
             this.usageWindowStore = new FileUsageWindowStore(this.root);
             this.fileAgentRows = new FileBackgroundAgentStore(this.root);
+            built.push(() => this.fileAgentRows.close());
             this.backgroundAgentStore = this.fileAgentRows;
             this.fileMailbox = new FileMailboxStore(this.root, corruptRead ?? {});
+            built.push(() => this.fileMailbox.close());
             this.mailboxStore = this.fileMailbox;
             this.rosterStore = new FileRosterStore(join(this.root, "roster.json"), corruptRead ?? {});
             const strategiesRoot = join(this.root, "strategies");
@@ -89,10 +96,25 @@ export class FileStorageBackend {
             this.consolidationLock = createFileConsolidationLock(join(this.root, "consolidation-locks"));
         }
         catch (err) {
-            this.lock.release();
+            for (const undo of built.reverse()) {
+                try {
+                    undo();
+                }
+                catch {
+                }
+            }
+            if (!this.lock.release())
+                this.discloseRetainedBootLock();
             throw err;
         }
     }
+    discloseRetainedBootLock() {
+        console.warn(`[sema] file store: this backend could not hand back its boot lock at ${join(this.root, "LOCK")} — the ` +
+            `removal could not be proven, so a lock file naming this live process (pid ${process.pid}) may still be ` +
+            `there. While it is, another process opening this data root is refused by name; a later open of this root ` +
+            `in THIS process finishes the cleanup or refuses by name. After this process exits the file is reclaimed ` +
+            `as a stale lock ONLY if it is readable and its directory writable — otherwise it has to be removed by hand.`);
+    }
     async dispose() {
         try {
             await this.ttl.dispose();
@@ -122,6 +144,7 @@ export class FileStorageBackend {
         }
         catch {
         }
-        this.lock.release();
+        if (!this.lock.release())
+            this.discloseRetainedBootLock();
     }
 }