@sema-agent/core 5.52.0 → 5.54.0

package/dist/stores/file/shared-ledger.d.ts

@@ -35,6 +35,17 @@
  *    compensation was the closest of the four and still wrong twice: it does not cover an unwritable
  *    FILE (the reopen throws too), and its reopen error REPLACES the fault that caused the swap. The
  *    answer is AppendLog's lazy reopen — {@link LedgerCore.compact}.
+ *  · **(2026-08-22, cross-process defect probe) — one authority per directory needs one WRITER per
+ *    directory, and that half was never enforced.** RB-55/59/134 closed the IN-PROCESS shape (two
+ *    instances, two private replays, two winners); two OS PROCESSES over one directory reproduced it
+ *    verbatim (a human approval and its refusal each reported as the winner) — and worse, the one that
+ *    never loaded the other's rows ERASED them at its next {@link LedgerCore.compact} (the snapshot is
+ *    rewritten from the in-memory map, and the live ledger is then truncated). The class docs all
+ *    credited a fence they did not hold: `root/LOCK` belongs to `FileStorageBackend`, which never
+ *    constructs the workflow-run store at all and which a directly-constructed store (all three are root
+ *    exports) never goes through. So the fence now lives WITH the authority: {@link LedgerCore.bootstrap}
+ *    takes `dir/LOCK` ({@link acquireStoreDirLock}) and the last {@link LedgerCore.release} drops it —
+ *    exclusive across processes, refcount-joined in-process, exactly like the authority it guards.
  *  · **RB-150 / RB-167 — compaction is HOUSEKEEPING.** It runs after the operation is durable AND
  *    applied, so its failure must never be reported as the operation's failure: a committed
  *    once-only CAS surfaced as "this did not happen" is the worst possible direction (the caller
@@ -57,6 +68,9 @@ export interface LedgerPaths {
 }
 /** The per-store half: how a SNAPSHOT row is keyed, and how one LEDGER event folds into the map. */
 export interface LedgerModel<Row, Ev> {
+    /** What this ledger IS, in an operator's words ("checkpoint ledger") — the noun the directory-fence
+     *  refusal names, so the message points at the store that is actually in use rather than at a path. */
+    label: string;
     keyOf(row: Row): string;
     apply(rows: Map<string, Row>, ev: Ev): void;
 }
@@ -77,9 +91,21 @@ export declare class LedgerCore<Row, Ev> {
     private readonly locks;
     private events;
     private handle;
+    /** This directory's cross-process writer fence, held for as long as the authority exists. */
+    private fence;
+    /** Set when the last holder left: this object is no longer the directory's authority (see compact). */
+    private released;
     constructor(key: string, paths: LedgerPaths, model: LedgerModel<Row, Ev>, table: Map<string, LedgerCore<Row, Ev>>);
-    /** Rebuild the authority: the snapshot (the compacted base) first, then the live ledger's events in
-     *  order (last-writer-wins), then open the append handle. Only the FIRST instance runs it. */
+    /**
+     * Rebuild the authority: take the directory's cross-process writer fence, then the snapshot (the
+     * compacted base), then the live ledger's events in order (last-writer-wins), then open the append
+     * handle. Only the FIRST instance over the directory runs it.
+     *
+     * The fence comes FIRST because everything after it assumes what the fence establishes: the replayed
+     * map is treated as THE authority for the directory (writes are decided against memory, and
+     * compaction rewrites the on-disk state FROM memory). Replaying first and locking after would be a
+     * window in which a second process's view is already stale.
+     */
     bootstrap(): void;
     /**
      * Serialize an op behind any in-flight op on the same key — the in-process per-key async mutex (the
@@ -93,11 +119,20 @@ export declare class LedgerCore<Row, Ev> {
      * memory and disk disagreeing. Then the best-effort housekeeping compaction (RB-150/RB-167).
      */
     commit(ev: Ev, fsync: boolean, compactEvery: number): void;
-    /** Rewrite the snapshot from the authoritative map (atomic) and truncate the live ledger. After
-     *  this a replay reads the whole state from the snapshot alone — the round-trip is identical. */
+    /**
+     * Rewrite the snapshot from the authoritative map (atomic) and truncate the live ledger. After
+     * this a replay reads the whole state from the snapshot alone — the round-trip is identical.
+     *
+     * REFUSED once this authority has been RELEASED. Compaction is the one operation that does not touch
+     * the append fd (it rewrites whole files), so a store object kept alive past its `close()` could still
+     * run it — rewriting the directory from a map that stopped being the authority, over rows a SUCCESSOR
+     * (here or in another process, holding the fence this core gave back) has since written. That is the
+     * same erasure the directory fence exists to prevent, arriving through a stale reference instead of a
+     * second process, so it is refused at the same door rather than trusted to caller discipline.
+     */
     compact(): void;
     /** Drop one instance's share. The LAST holder evicts the authority — identity-checked, so a stale
-     *  holder can never revoke a REBUILT entry — and closes the append fd. */
+     *  holder can never revoke a REBUILT entry — retires it (see {@link compact}) and closes the append fd. */
     release(): void;
     /** Test/inspection: events appended since the last compaction. */
     get pendingEvents(): number;

package/dist/stores/file/shared-ledger.js

@@ -1,4 +1,4 @@
-import { AppendLog, atomicWriteFile, canonicalStoreKey, ensureDir, readJsonlRecords } from "./fs-atomic.js";
+import { acquireStoreDirLock, AppendLog, atomicWriteFile, canonicalStoreKey, ensureDir, readJsonlRecords, } from "./fs-atomic.js";
 export class LedgerCore {
     key;
     paths;
@@ -9,6 +9,8 @@ export class LedgerCore {
     locks = new Map();
     events = 0;
     handle;
+    fence;
+    released = false;
     constructor(key, paths, model, table) {
         this.key = key;
         this.paths = paths;
@@ -16,13 +18,21 @@ export class LedgerCore {
         this.table = table;
     }
     bootstrap() {
-        for (const row of readJsonlRecords(this.paths.snapshotPath))
-            this.rows.set(this.model.keyOf(row), row);
-        const events = readJsonlRecords(this.paths.ledgerPath);
-        this.events = events.length;
-        for (const ev of events)
-            this.model.apply(this.rows, ev);
-        this.handle = new AppendLog(this.paths.ledgerPath);
+        this.fence = acquireStoreDirLock(this.paths.dir, { label: this.model.label });
+        try {
+            for (const row of readJsonlRecords(this.paths.snapshotPath))
+                this.rows.set(this.model.keyOf(row), row);
+            const events = readJsonlRecords(this.paths.ledgerPath);
+            this.events = events.length;
+            for (const ev of events)
+                this.model.apply(this.rows, ev);
+            this.handle = new AppendLog(this.paths.ledgerPath);
+        }
+        catch (e) {
+            this.fence.release();
+            this.fence = undefined;
+            throw e;
+        }
     }
     withLock(key, fn) {
         const prev = this.locks.get(key) ?? Promise.resolve();
@@ -48,6 +58,9 @@ export class LedgerCore {
         }
     }
     compact() {
+        if (this.released) {
+            throw new Error("file ledger: this authority was released (its store was closed) — refusing to compact a directory it no longer owns");
+        }
         const lines = [...this.rows.values()].map((r) => JSON.stringify(r)).join("\n");
         atomicWriteFile(this.paths.tmpDir, this.paths.snapshotPath, lines.length ? `${lines}\n` : "");
         this.log.closeForSwap();
@@ -60,7 +73,10 @@ export class LedgerCore {
             return;
         if (this.table.get(this.key) === this)
             this.table.delete(this.key);
+        this.released = true;
         this.handle?.close();
+        this.fence?.release();
+        this.fence = undefined;
     }
     get pendingEvents() {
         return this.events;

package/dist/stores/file/workflow-run-store.d.ts

@@ -35,6 +35,13 @@ export declare class FileWorkflowRunStore implements WorkflowRunStore {
     compactNow(): void;
     /** Test/inspection helper: number of stored runs. */
     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 (`<dir>/LOCK`), so a successor process can open the same run ledger.
+     * There is no OTHER door: this store is never constructed by `FileStorageBackend`, so nothing else
+     * ever hands its fence back — the doc line that used to credit "the backend factory" here named a
+     * release that could not happen under any assembly, for a lock this store did not hold in the first
+     * place (see the class note above).
+     */
     close(): void;
 }

package/dist/stores/file/workflow-run-store.js

@@ -4,6 +4,7 @@ import { WorkflowRunStoreError, isTerminalWorkflowStatus, nextWorkflowRunOnUpdat
 import { SharedLedgerTable } from "./shared-ledger.js";
 import { assertAdoptionBootGate } from "./adoption/marker.js";
 const runLedgers = new SharedLedgerTable({
+    label: "workflow-run ledger",
     keyOf: (run) => run.id,
     apply: (runs, ev) => {
         if (ev.t === "delete") {

package/dist/tools/fs/bash-readonly-classifier.d.ts

@@ -40,6 +40,29 @@ export interface LeadingCommandNameOptions {
      * operator character counts, exactly as without this option.
      */
     quotedOperatorsAreText?: boolean;
+    /**
+     * Read a PATH-PREFIXED `argv[0]` (`./gradlew`, `/usr/bin/git`, `bin/tool`) as an ordinary command
+     * name instead of refusing it.
+     *
+     * OPT-IN, and used by ONE family of callers: the persisted permission-RULE lane
+     * ({@link import("../../core/permission-rule-model.js").parseAllowRuleText} and its matcher), where
+     * both sides of the comparison are literal text a person read on an approval card. The refusal this
+     * option lifts exists for the argv[0]-NAME filters (the read-only allowlist, the coarse
+     * command-name policy, the skill specifier): those compare a bare token against a name set, and a
+     * path prefix is how a caller reaches a program the set never vetted. A rule lane compares the whole
+     * command line instead, so `./gradlew` there is not a way past a name set — it IS the name that was
+     * approved, and refusing it made the single most ordinary build command in a repository unable to
+     * carry a standing approval at all.
+     *
+     * What it does NOT lift: the argv[0] metacharacter refusal (quotes/braces/globs/`~` still make the
+     * parsed token differ from the program bash runs), the leading env-assignment refusal, and every
+     * shell operator. And it does not make a path-prefixed name equal its basename anywhere — the rule
+     * lane matches on the text as written, so `./gradlew` and `gradlew` stay two different commands. The
+     * one place a basename IS taken is the rule lane's own interpreter refusal, which must read
+     * `/usr/bin/node` as `node` (see
+     * {@link import("../../core/permission-rule-model.js").BARE_INTERPRETER_NAMES}).
+     */
+    pathPrefixedNameIsText?: boolean;
 }
 /**
  * The SINGLE fail-closed simple-command parser shared by `bash_readonly` ({@link coarseReadonlyCheck}), the
@@ -48,6 +71,8 @@ export interface LeadingCommandNameOptions {
  * `argv[0]` command NAME of a SINGLE simple command, rejecting anything that could chain past or escape an
  * argv[0]-name filter: shell operators (pipes / redirects / `;` / `&&` / `$(…)` / subshells / backticks /
  * newlines / backslash), a path-prefixed command (`/usr/bin/foo`), or a leading env-assignment (`FOO=bar cmd`).
+ * The path-prefix refusal is the one arm a caller may lift, opt-in and for the rule lane only — see
+ * {@link LeadingCommandNameOptions.pathPrefixedNameIsText} for why it is sound exactly there.
  *
  * Returns `{ name }` for a parseable single bare command, or `{ reject }` with a human reason otherwise. It
  * does NOT inspect ARGUMENTS for write flags or consult any allowlist — that is the caller's job (the
@@ -66,6 +91,52 @@ export declare function parseLeadingCommandName(command: string, options?: Leadi
  *  design/154: this `effect:"read"` DECLARATION face deliberately stays strict-single-command; only the
  *  classify face ({@link classifyCompoundReadonly} via {@link import("./fs-bash.js").bashReversibilityProbe}) segments compounds. */
 export declare function coarseReadonlyCheck(command: string, allow: ReadonlySet<string>, options?: LeadingCommandNameOptions): string | undefined;
+/** What {@link splitShellCompoundSegments} produces: the connector-delimited segments, plus which of
+ *  them a PIPE fed (the read-only classifier's stdin arm needs that distinction; a rule lane does not). */
+export interface ShellCompoundSegments {
+    segments: string[];
+    /** Parallel to {@link segments}: was this segment preceded by `|` (rather than `;`/`&&`/`||`/nothing)? */
+    pipeFed: boolean[];
+}
+/**
+ * Split a compound command into the segments bash would run, or refuse the whole string.
+ *
+ * THE one segmentation in this repository. Extracted from {@link classifyCompoundReadonlyDetailed}
+ * (whose behaviour it reproduces exactly) when a SECOND face needed segments — the persisted
+ * permission-rule lane, which must judge every segment of a compound against the deny/ask rules rather
+ * than reading the whole string as one unmatched blob. The same argument that keeps ONE
+ * {@link parseLeadingCommandName} applies with more force here: a second splitter would drift, and
+ * drift in a segmentation is drift in what a deny rule is even looking at.
+ *
+ * Three steps, in this order and load-bearing:
+ *  1. WHOLE-STRING hard reject of {@link SHELL_SEGMENT_HARD_REJECT} — redirection, substitution,
+ *     subshells, escapes, line breaks. This is what makes step 3's quote mask EXACT: with those
+ *     characters gone, `'`/`"` pairing is the entirety of quoting, so the mask's regions are exactly
+ *     bash's quoted regions and the unquoted connectors are exactly bash's command boundaries. Callers
+ *     that tolerate a narrow redirection subset (the read-only classify face and its two data-free
+ *     spellings) remove those words BEFORE calling; nothing here restores them.
+ *  2. one trailing `;` is stripped — a no-op terminator, not an empty command. OPTIONAL, because it is
+ *     the one step whose answer depends on what the caller is asking. A face that asks "which programs
+ *     does this run" wants it stripped (`ls;` runs `ls`, nothing else). A face that asks "is this ONE
+ *     command" must NOT strip it: `"keep"` makes `ls;` two segments, the second empty, so the caller's
+ *     own empty-command rule puts the whole string outside its lane — which is what keeps a statement
+ *     like "this rule form never matches a command containing a connector" literally true instead of
+ *     true-except-for-one-spelling.
+ *  3. the quote-aware connector scan over `;` `&&` `||` `|`. A lone `&` is REFUSED rather than split
+ *     on: it backgrounds a process that outlives the command, which is not a combinator any face here
+ *     is willing to reason about. Unbalanced quoting disables the mask, which degrades to the
+ *     quote-blind scan — strictly MORE segments, each of which the caller must still vet, i.e. the
+ *     fail-closed direction.
+ *
+ * Empty segments are NOT refused here (`;;`, a leading `;`, a trailing `&&`) — they come back as empty
+ * strings, and every caller's per-segment vetting rejects them through its own empty-command rule. The
+ * split does not judge segments; it says where they are.
+ */
+export declare function splitShellCompoundSegments(source: string, options?: {
+    trailingTerminator?: "strip" | "keep";
+}): ShellCompoundSegments | {
+    reject: string;
+};
 /**
  * RB-412 — the READ-BOUNDARY face of the read-only classification (opt-in).
  *

package/dist/tools/fs/bash-readonly-classifier.js

@@ -45,8 +45,9 @@ export function parseLeadingCommandName(command, options) {
         };
     }
     const first = trimmed.split(/\s+/)[0];
-    if (first.includes("/"))
+    if (first.includes("/") && options?.pathPrefixedNameIsText !== true) {
         return { reject: "the command must be a bare name resolved via PATH (no path prefix)" };
+    }
     if (first.includes("="))
         return { reject: "leading environment-variable assignments are not allowed" };
     if (/["'{}*?[\]~]/.test(first))
@@ -62,6 +63,55 @@ export function coarseReadonlyCheck(command, allow, options) {
     return undefined;
 }
 const SHELL_SEGMENT_HARD_REJECT = /[<>$()`\n\r\\]/;
+export function splitShellCompoundSegments(source, options) {
+    if (SHELL_SEGMENT_HARD_REJECT.test(source)) {
+        return { reject: "redirection, command/variable substitution, subshells, escapes, and line breaks are not allowed" };
+    }
+    const scanned = options?.trailingTerminator !== "keep" ? source.replace(/;\s*$/, "") : source;
+    const segments = [];
+    const pipeFed = [false];
+    const mask = quoteMask(scanned);
+    const quoted = (i) => mask.balanced && mask.quoted[i] === true;
+    let cur = "";
+    for (let i = 0; i < scanned.length; i++) {
+        const c = scanned[i];
+        if (quoted(i)) {
+            cur += c;
+        }
+        else if (c === "&") {
+            if (scanned[i + 1] === "&") {
+                segments.push(cur);
+                cur = "";
+                pipeFed.push(false);
+                i++;
+            }
+            else
+                return { reject: "`&` backgrounding is not allowed — a backgrounded process outlives the command" };
+        }
+        else if (c === "|") {
+            if (scanned[i + 1] === "|") {
+                segments.push(cur);
+                cur = "";
+                pipeFed.push(false);
+                i++;
+            }
+            else {
+                segments.push(cur);
+                cur = "";
+                pipeFed.push(true);
+            }
+        }
+        else if (c === ";") {
+            segments.push(cur);
+            cur = "";
+            pipeFed.push(false);
+        }
+        else
+            cur += c;
+    }
+    segments.push(cur);
+    return { segments, pipeFed };
+}
 const EXEMPT_REDIRECTION = /^(?:2>\/dev\/null|[12]?>&[12])$/;
 function stripExemptRedirections(command) {
     if (!command.includes(">"))
@@ -532,52 +582,13 @@ export function classifyCompoundReadonlyDetailed(command, allow, boundary) {
     if (!trimmed)
         return { reason: "empty command" };
     const redirectionStripped = stripExemptRedirections(trimmed);
-    if (SHELL_SEGMENT_HARD_REJECT.test(redirectionStripped)) {
-        return { reason: "redirection, command/variable substitution, subshells, escapes, and line breaks are not allowed" };
-    }
-    const source = redirectionStripped.endsWith(";") ? redirectionStripped.slice(0, -1) : redirectionStripped;
-    const segments = [];
-    const pipeFed = [false];
-    const mask = quoteMask(source);
-    const quoted = (i) => mask.balanced && mask.quoted[i] === true;
-    let cur = "";
-    for (let i = 0; i < source.length; i++) {
-        const c = source[i];
-        if (quoted(i)) {
-            cur += c;
-        }
-        else if (c === "&") {
-            if (source[i + 1] === "&") {
-                segments.push(cur);
-                cur = "";
-                pipeFed.push(false);
-                i++;
-            }
-            else
-                return { reason: "`&` backgrounding is not allowed — a backgrounded process outlives the command" };
-        }
-        else if (c === "|") {
-            if (source[i + 1] === "|") {
-                segments.push(cur);
-                cur = "";
-                pipeFed.push(false);
-                i++;
-            }
-            else {
-                segments.push(cur);
-                cur = "";
-                pipeFed.push(true);
-            }
-        }
-        else if (c === ";") {
-            segments.push(cur);
-            cur = "";
-            pipeFed.push(false);
-        }
-        else
-            cur += c;
-    }
-    segments.push(cur);
+    const terminatorStripped = redirectionStripped.endsWith(";")
+        ? redirectionStripped.slice(0, -1)
+        : redirectionStripped;
+    const split = splitShellCompoundSegments(terminatorStripped, { trailingTerminator: "keep" });
+    if ("reject" in split)
+        return { reason: split.reject };
+    const { segments, pipeFed } = split;
     for (const segment of segments) {
         const reason = coarseReadonlyCheck(segment, allow, { quotedOperatorsAreText: true });
         if (reason !== undefined)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/core",
-  "version": "5.52.0",
+  "version": "5.54.0",
   "description": "Stateless, task-oriented AI agent core",
   "type": "module",
   "license": "BUSL-1.1",

package/test/export-surface.snapshot.json

@@ -1,6 +1,6 @@
 {
   "_comment": "design/87 L3 — frozen public export surface of src/index.ts (name -> kind). DO NOT edit by hand to silence a red test. A removed/changed entry = a SemVer-BREAKING change; bump MAJOR and update this fixture in the SAME commit (design/87 §4.2 / §5.2). Regenerate via REGEN in test/export-surface.test.ts.",
-  "count": 1649,
+  "count": 1651,
   "exports": {
     "A2ATaskState": "type",
     "A2ATaskStateReversal": "type",
@@ -319,6 +319,8 @@
     "FileStorageBackend": "class",
     "FileStorageBackendOptions": "interface",
     "FileStorageCorruptReadInfo": "interface",
+    "FileStoreLockError": "class",
+    "FileStoreLockErrorCode": "type",
     "FileStrategyStore": "class",
     "FileStrategyStoreOptions": "interface",
     "FileToolResultStore": "class",