@sema-agent/core 5.53.0 → 5.55.0

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();
     }
 }

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/dist/tools/fs/index.d.ts

@@ -163,7 +163,9 @@ export interface HandsToolkitOptions {
     reminderMark?: string;
     /** design/319 (B ticket) — the per-run trailer/defuse trigger counters (observation seat, G9②):
      *  the Read text/notebook/PDF-text disclosure trailers bump `read.*` / `notebook.*` / `pdf.*`
-     *  keys here (appended / marked / bare_throttled). Threaded by prepare-task, which folds the
+     *  keys here. The form suffixes are enumerated once, on the consumer-facing contract
+     *  (`TaskResult.stats.mechanisms.reminderDisclosures` in core/types.ts) — this map is the same
+     *  open record and is not a second, narrower registry of them. Threaded by prepare-task, which folds the
      *  non-zero result into `TaskResult.stats.mechanisms.reminderDisclosures`; a library-direct
      *  mount may pass its own object or omit it (counting off — and the whole disclosure pipeline
      *  is off anyway when `reminderMark` is absent). */

package/package.json

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