@sema-agent/core 7.26.2 → 7.27.0

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

@@ -4,6 +4,7 @@ import { assertRetentionPolicy } from "../../core/retention-policy.js";
 import { existsSync, linkSync, readdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { detachMailboxMessage, newestSentAt, readMailboxPeerMeta, } from "../../core/mailbox-store.js";
 import { AppendLog, atomicWriteFile, canonicalStoreKey, ensureDir, readJsonlRecords, sanitizeScope, sanitizePathComponent } from "./fs-atomic.js";
+import { guardCorruptSink } from "./corrupt-read-sink.js";
 import { physicalPathOf } from "../../core/physical-path.js";
 import { assertAdoptionBootGate } from "./adoption/marker.js";
 function diskMarkOf(path) {
@@ -339,17 +340,7 @@ export class FileMailboxStore {
             throw new Error(`FileMailboxStore: lockWaitMs must be a finite number > 0, got ${JSON.stringify(opts.lockWaitMs)}`);
         }
         this.lockWaitMs = lockWaitMs;
-        const sink = opts.onCorruptRead;
-        this.discloseCorrupt =
-            sink === undefined
-                ? undefined
-                : (info) => {
-                    try {
-                        sink(info);
-                    }
-                    catch {
-                    }
-                };
+        this.discloseCorrupt = guardCorruptSink(opts.onCorruptRead);
         const lexicalDir = resolve(join(root, "mailboxes"));
         const lexicalTmp = resolve(join(root, "tmp"));
         ensureDir(lexicalDir);
@@ -382,6 +373,11 @@ export class FileMailboxStore {
             return result;
         });
     }
+    applyReplayed(b, ev, path) {
+        if (applyEvent(b, ev))
+            return;
+        this.discloseCorrupt?.({ path, reason: "missing-required: a mailbox record is not one of this box's events — an unknown tag, or a known tag whose payload is missing (skipped; the rest of the replay is intact)" });
+    }
     reconcile(b) {
         const now = diskMarkOf(b.path);
         if (sameDiskMark(now, b.mark))
@@ -393,7 +389,7 @@ export class FileMailboxStore {
         b.nextSeq = 1;
         delete b.lease;
         for (const ev of events)
-            applyEvent(b, ev);
+            this.applyReplayed(b, ev, b.path);
         b.events = Math.max(0, events.length - (b.messages.length + 1 + (b.lease !== undefined ? 1 : 0)));
         b.mark = now;
     }
@@ -413,7 +409,7 @@ export class FileMailboxStore {
         const events = readJsonlRecords(path, this.discloseCorrupt);
         const state = { messages: [], nextSeq: 1, log: new AppendLog(path), events: events.length, refs: 1, path, mark: undefined };
         for (const ev of events)
-            applyEvent(state, ev);
+            this.applyReplayed(state, ev, path);
         state.mark = diskMarkOf(path);
         sharedBoxes.set(key, state);
         this.touched.set(key, state);
@@ -501,7 +497,7 @@ export class FileMailboxStore {
         return withPathLock(this.lockKey(scope, handle), () => {
             const b = { messages: [], nextSeq: 1 };
             for (const ev of readJsonlRecords(path, this.discloseCorrupt))
-                applyEvent(b, ev);
+                this.applyReplayed(b, ev, path);
             return b.messages.length;
         });
     }
@@ -561,7 +557,7 @@ export class FileMailboxStore {
                     return false;
                 const b = { messages: [], nextSeq: 1 };
                 for (const ev of readJsonlRecords(path, this.discloseCorrupt))
-                    applyEvent(b, ev);
+                    this.applyReplayed(b, ev, path);
                 const newest = newestSentAt(b.messages);
                 if (newest === undefined || newest >= now - maxAgeMs)
                     return false;
@@ -587,26 +583,36 @@ export class FileMailboxStore {
         this.touched.clear();
     }
 }
+const num = (v) => typeof v === "number" && Number.isFinite(v);
 function applyEvent(b, ev) {
     if (ev.t === "append") {
+        if (ev.m === null || typeof ev.m !== "object" || !num(ev.m.seq))
+            return false;
         b.messages.push(ev.m);
         if (ev.m.seq >= b.nextSeq)
             b.nextSeq = ev.m.seq + 1;
-        return;
+        return true;
     }
     if (ev.t === "lease") {
+        if (typeof ev.owner !== "string" || !num(ev.maxSeq) || !num(ev.expiresAt))
+            return false;
         if (ev.maxSeq >= b.nextSeq)
             b.nextSeq = ev.maxSeq + 1;
         if (ev.owner !== "")
             b.lease = { owner: ev.owner, expiresAt: ev.expiresAt, maxSeq: ev.maxSeq };
-        return;
+        return true;
     }
     if (ev.t === "ack") {
+        if (!num(ev.upToSeq))
+            return false;
         b.messages = b.messages.filter((m) => m.seq > ev.upToSeq);
         if (b.lease !== undefined && b.lease.maxSeq <= ev.upToSeq)
             b.lease = undefined;
-        return;
+        return true;
     }
+    if (ev.t !== "release" || typeof ev.owner !== "string")
+        return false;
     if (b.lease?.owner === ev.owner)
         b.lease = undefined;
+    return true;
 }

package/dist/stores/file/permission-rule-store.js

@@ -48,8 +48,25 @@ export function readRuleAdoptionFile(dir) {
     }
     return parsed;
 }
+function isRuleOwnerShape(v) {
+    if (v === null || typeof v !== "object")
+        return false;
+    const owner = v;
+    return owner.kind === "local-owner" || (owner.kind === "principal" && typeof owner.principal === "string");
+}
 function isRuleAdoptionFileShape(v) {
-    return typeof v === "object" && v !== null && v.schemaVersion === 1 && ("marker" in v || "adopted" in v);
+    if (v === null || typeof v !== "object" || v.schemaVersion !== 1)
+        return false;
+    const hasMarker = "marker" in v;
+    const hasAdopted = "adopted" in v;
+    if (hasMarker === hasAdopted)
+        return false;
+    const rec = (hasMarker ? v.marker : v.adopted);
+    if (rec === null || typeof rec !== "object")
+        return false;
+    if (!isRuleOwnerShape(rec.from) || typeof rec.toPrincipal !== "string" || rec.toPrincipal === "")
+        return false;
+    return hasMarker ? rec.phase === 2 || rec.phase === 3 || rec.phase === 4 || rec.phase === 5 : typeof rec.atMs === "number" && Number.isFinite(rec.atMs);
 }
 export function writeRuleAdoptionFile(dir, content) {
     assertSafeDir(dir);

package/dist/stores/file/session-policy-store.d.ts

@@ -1,4 +1,20 @@
 import { type PutRulesOptions, type SessionPermissionRules, type SessionPolicyStore, type SessionRulesRecord, type StoredSessionRules } from "../../core/session-policy-store.js";
+/**
+ * design/99 §E6 — file-backed {@link SessionPolicyStore} for the local (TOC) backend: one JSON row file per
+ * `(sessionId, principal)`, plus — once that key has ever been stamped — a second, tiny file beside it holding
+ * the number the erase contract on {@link SessionPolicyStore.deleteBySession} says must outlive the row. Both
+ * names share a stem, and the mark's suffix is what every directory sweep here tests first
+ * ({@link MARK_SUFFIX}). Semantics otherwise **byte-for-byte identical to `InMemorySessionPolicyStore`** (the
+ * cross-backend equivalence contract). CAS-rev OCC + tighten-only reuse the SAME pure helpers
+ * (`loosenReasons`/`normalizeRules`/`stripRev`) as core — no re-implemented rule logic that could drift.
+ *
+ * Atomicity: the file backend is single-process (the `FileStorageBackend` boot lock guarantees ONE writer per
+ * data dir), and `getRules`/`putRules` read-check-write SYNCHRONOUSLY (no await between the rev read and the
+ * atomic write), so the read-modify-write is atomic in the one event loop — exactly the InMemory store's premise.
+ * Cross-process CORRECT concurrency is the Pg/TiDB backend's job (a CAS WHERE clause), by design.
+ */
+/** Coordinates of one corrupt-treated-as-absent policy read (the {@link FileSessionPolicyStoreOptions.onCorruptRead}
+ *  payload). Named rather than inline so the backend option that forwards it names the SAME shape. */
 export interface SessionPolicyCorruptReadInfo {
     /** The session whose read observed the corrupt row. On the enumeration face this is the session being
      *  ENUMERATED — a corrupt row's own `__sid` is by definition unreadable, so it cannot be attributed. */
@@ -84,7 +100,7 @@ export declare class FileSessionPolicyStore implements SessionPolicyStore {
      *  alike (a window-era anonymous write must not mint a fresh orphan row). */
     private readonly anonymousAlias;
     constructor(root: string, opts?: FileSessionPolicyStoreOptions);
-    /** The one delivery point for {@link onCorruptRead}. Swallow-guarded here so no caller has to remember. */
+    /** The one delivery point for {@link onCorruptRead}. */
     private disclose;
     /** RB-482 top item (baggage class-4 ruling): corrupt-read fail-open is a DOCUMENTED compromise (a throwing
      *  getRules fails the whole task; a throwing putRules self-locks the repair write) — but it must not

package/dist/stores/file/session-policy-store.js

@@ -2,13 +2,8 @@ import { existsSync, readFileSync, readdirSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 import { loosenReasons, normalizeRules, stripRev, SessionPolicyError, } from "../../core/session-policy-store.js";
 import { atomicWriteFile, ensureDir, sanitizeScope } from "./fs-atomic.js";
+import { guardCorruptSink } from "./corrupt-read-sink.js";
 import { assertAdoptionBootGate, readRootAdoptionFile } from "./adoption/marker.js";
-function containSinkThenable(r) {
-    if (typeof r?.then === "function") {
-        r.then(undefined, () => {
-        });
-    }
-}
 export const SESSION_POLICY_MARK_SUFFIX = ".hwm.json";
 const MARK_SUFFIX = SESSION_POLICY_MARK_SUFFIX;
 export function readSessionPolicyMark(path) {
@@ -76,17 +71,13 @@ export class FileSessionPolicyStore {
         assertAdoptionBootGate(root, "FileSessionPolicyStore");
         this.dir = join(root, "session-policy");
         ensureDir(this.dir);
-        this.onCorruptRead = opts?.onCorruptRead;
+        this.onCorruptRead = guardCorruptSink(opts?.onCorruptRead);
         const adoption = readRootAdoptionFile(root);
         this.anonymousAlias =
             adoption !== undefined && "adopted" in adoption && adoption.adopted.from.kind === "local-owner" ? adoption.adopted.toPrincipal : undefined;
     }
     disclose(info) {
-        try {
-            containSinkThenable(this.onCorruptRead?.(info));
-        }
-        catch {
-        }
+        this.onCorruptRead?.(info);
     }
     discloseCorrupt(sessionId, principal, reason) {
         this.disclose({ sessionId, ...(principal !== undefined ? { principal } : {}), path: this.pathFor(sessionId, principal), reason });

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

@@ -28,11 +28,7 @@ export declare class FileSessionRepo implements SessionRepo {
      *  check on the way out possible without pinning a storage the table itself only holds weakly. */
     private readonly joined;
     constructor(root: string, opts?: FileSessionRepoOptions);
-    /** The one delivery point for {@link FileSessionRepoOptions.onCorruptRead}; swallow-guarded here so
-     *  no call site has to remember. The sink seat is void-typed but a host may hand it an async
-     *  function — an async sink's rejection is observed off its returned thenable (same containment
-     *  as the strategy store's incident sink), so neither a sync throw nor an async rejection can
-     *  re-introduce the failure mode the fail-open avoids. */
+    /** The one delivery point for {@link FileSessionRepoOptions.onCorruptRead}. */
     private disclose;
     private pathFor;
     /** Read + torn-tail-recover a session file into (meta, entries); a missing file → not_found. */

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

@@ -2,14 +2,9 @@ import { existsSync, readdirSync, rmSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { BaseSessionStorage, StoredSession, SessionError, getEntriesToFork, uuidv7, validateEntriesForImport, } from "../../internal/harness.js";
 import { canonicalStoreKey, AppendLog, atomicWriteFile, ensureDir, readJsonlRecords, sanitizePathComponent } from "./fs-atomic.js";
+import { guardCorruptSink } from "./corrupt-read-sink.js";
 import { assertAdoptionBootGate } from "./adoption/marker.js";
 import { thrownText } from "../../core/thrown-value.js";
-function containSinkThenable(r) {
-    if (typeof r?.then === "function") {
-        r.then(undefined, () => {
-        });
-    }
-}
 const SUFFIX = ".jsonl";
 const sharedSessionStorages = new Map();
 const sessionStorageFinalizer = new FinalizationRegistry(({ canonical, log }) => {
@@ -70,14 +65,10 @@ export class FileSessionRepo {
         this.tmpDir = join(root, "tmp");
         ensureDir(this.dir);
         ensureDir(this.tmpDir);
-        this.onCorruptRead = opts?.onCorruptRead;
+        this.onCorruptRead = guardCorruptSink(opts?.onCorruptRead);
     }
     disclose(path, reason) {
-        try {
-            containSinkThenable(this.onCorruptRead?.({ path, reason }));
-        }
-        catch {
-        }
+        this.onCorruptRead?.({ path, reason });
     }
     pathFor(id) {
         return join(this.dir, `${sanitizePathComponent(id)}${SUFFIX}`);
@@ -97,9 +88,13 @@ export class FileSessionRepo {
                 createdAt = line.createdAt;
                 forkedFrom = line.forkedFrom;
                 placement = line.placement;
+                continue;
+            }
+            if (line.kind !== "entry" || line.entry === null || typeof line.entry !== "object") {
+                this.disclose(path, "missing-required: a session line is neither a meta header nor an entry record (skipped; the rest of the replay is intact)");
+                continue;
             }
-            else
-                entries.push(line.entry);
+            entries.push(line.entry);
         }
         return { createdAt, ...(forkedFrom !== undefined ? { forkedFrom } : {}), ...(placement !== undefined ? { placement } : {}), entries };
     }

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

@@ -1,3 +1,4 @@
+import type { CorruptReadInfo } from "./corrupt-read-sink.js";
 /**
  * design/157 A9 — the SHARED substrate under the three snapshot+ledger file stores
  * ({@link import("./background-agent-store.js").FileBackgroundAgentStore},
@@ -61,6 +62,11 @@
 /** The paths one ledger authority owns. `dir` is also what the authority is keyed on. */
 export interface LedgerPaths {
     readonly dir: string;
+    /** Disclosure seat for a replay row this authority DROPPED as corrupt — without it the loss is
+     *  indistinguishable from "fewer rows". Already swallow-guarded by the store that wired it. Only the
+     *  FIRST instance over a directory replays, so only its seat can fire: a joiner reads the authority
+     *  that instance built, which is the same fact its refcount records. */
+    readonly onCorruptRead?: (info: CorruptReadInfo) => void;
     /** Scratch dir for {@link atomicWriteFile} (same filesystem as the targets → rename is atomic). */
     readonly tmpDir: string;
     readonly ledgerPath: string;
@@ -73,6 +79,18 @@ export interface LedgerModel<Row, Ev> {
     label: string;
     keyOf(row: Row): string;
     apply(rows: Map<string, Row>, ev: Ev): void;
+    /**
+     * `@contract store.read_back_shape_judged` floor: is this parsed body one of MY rows / MY events at
+     * all? Judged on the DISCRIMINANT only — the key a row is filed under, the tag an event is folded by —
+     * because what to do with a discriminant this binary does not KNOW is the model's own business (the
+     * checkpoint ledger refuses the whole replay for a kind from a newer worker, deliberately). A body
+     * that carries no discriminant carries no such choice: it is damage, and `bootstrap` discloses and
+     * skips it. Required rather than optional, so a fourth ledger store cannot inherit the silence by
+     * omission — before this floor existed, `{"note":"x"}` in an agent ledger filed a row under the key
+     * `undefined` and the next enumeration read members off it.
+     */
+    judgeRow(x: unknown): boolean;
+    judgeEvent(x: unknown): boolean;
 }
 /**
  * One directory's authority: the replayed row map, the per-key async mutex, the append log and the

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

@@ -20,9 +20,23 @@ export class LedgerCore {
     bootstrap() {
         this.fence = acquireStoreDirLock(this.paths.dir, { label: this.model.label });
         try {
-            for (const row of readJsonlRecords(this.paths.snapshotPath))
+            const disclose = this.paths.onCorruptRead;
+            const mine = (xs, judge, path, what) => {
+                const kept = [];
+                for (const x of xs) {
+                    if (judge(x))
+                        kept.push(x);
+                    else
+                        disclose?.({ path, reason: `missing-required: a ${what} carries none of this ${this.model.label}'s own members (skipped; the rest of the replay is intact)` });
+                }
+                return kept;
+            };
+            const snapPath = this.paths.snapshotPath;
+            const ledgerPath = this.paths.ledgerPath;
+            for (const row of mine(readJsonlRecords(snapPath, disclose), this.model.judgeRow, snapPath, "snapshot row")) {
                 this.rows.set(this.model.keyOf(row), row);
-            const events = readJsonlRecords(this.paths.ledgerPath);
+            }
+            const events = mine(readJsonlRecords(ledgerPath, disclose), this.model.judgeEvent, ledgerPath, "ledger event");
             this.events = events.length;
             for (const ev of events)
                 this.model.apply(this.rows, ev);

package/dist/stores/file/tool-result-store.d.ts

@@ -1,4 +1,5 @@
 import type { ToolResultDeletionReport, ToolResultProvenance, ToolResultSlice, ToolResultStore } from "../../core/tool-result-store.js";
+import { type CorruptReadInfo } from "./corrupt-read-sink.js";
 /**
  * design/80 §2.5 — file {@link ToolResultStore}: write-once-idempotent, ONE file per ref.
  *
@@ -26,9 +27,16 @@ import type { ToolResultDeletionReport, ToolResultProvenance, ToolResultSlice, T
  * is present but unreadable stops the write loudly, where treating it as "no owner" would report
  * success and leave the entry unclaimable forever.
  */
+export interface FileToolResultStoreOptions {
+    /** Disclosure seat for an owner sidecar that is PRESENT but unreadable: {@link
+     *  FileToolResultStore.ownerOf} answers `undefined` — the same word it uses for an entry nobody owns,
+     *  so a host that authorizes on it reads damage as "unowned". Swallow-guarded. */
+    onCorruptRead?: (info: CorruptReadInfo) => void;
+}
 export declare class FileToolResultStore implements ToolResultStore {
     private readonly dir;
-    constructor(root: string);
+    private readonly discloseCorrupt;
+    constructor(root: string, opts?: FileToolResultStoreOptions);
     /** The directory a ref's files live in, and their shared stem. See {@link encodeRefFilename} for why
      *  a FOLDED name gets its own directory instead of sharing one with identity names. */
     private locate;

package/dist/stores/file/tool-result-store.js

@@ -3,12 +3,15 @@ import { readFileSync, readdirSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 import { assertSafeToolResultRef, assertToolResultProvenanceMatch, normalizeToolResultProvenance, ToolResultRefConflictError, } from "../../core/tool-result-store.js";
 import { ensureDir, sanitizePathComponent, writeThenLink } from "./fs-atomic.js";
+import { guardCorruptSink } from "./corrupt-read-sink.js";
 import { assertAdoptionBootGate } from "./adoption/marker.js";
 export class FileToolResultStore {
     dir;
-    constructor(root) {
+    discloseCorrupt;
+    constructor(root, opts) {
         assertAdoptionBootGate(root, "FileToolResultStore");
         this.dir = join(root, "tool-results");
+        this.discloseCorrupt = guardCorruptSink(opts?.onCorruptRead);
         ensureDir(this.dir);
     }
     locate(ref) {
@@ -59,15 +62,26 @@ export class FileToolResultStore {
         return this.readOwnerFile(ref, { loud: false });
     }
     readOwnerFile(ref, opts) {
+        const ownerPath = (() => {
+            try {
+                return this.ownerPathFor(ref);
+            }
+            catch {
+                return undefined;
+            }
+        })();
+        if (ownerPath === undefined)
+            return undefined;
         let raw;
         try {
-            raw = readFileSync(this.ownerPathFor(ref), "utf8");
+            raw = readFileSync(ownerPath, "utf8");
         }
         catch (err) {
             if (err.code === "ENOENT")
                 return undefined;
             if (opts.loud)
                 throw err;
+            this.discloseCorrupt?.({ path: ownerPath, reason: `unreadable owner sidecar (${err.code ?? "unknown"}) — read as unowned` });
             return undefined;
         }
         const parsed = parseOwnerRecord(raw);
@@ -76,6 +90,7 @@ export class FileToolResultStore {
         if (opts.loud) {
             throw new Error(`tool-result store: owner record for ref ${JSON.stringify(ref)} is present but unreadable — refusing to write over it`);
         }
+        this.discloseCorrupt?.({ path: ownerPath, reason: "not-an-object: owner sidecar is present but is not an owner record — read as unowned" });
         return undefined;
     }
     writeOwnerFile(ref, provenance) {

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

@@ -1,4 +1,5 @@
 import { type WorkflowJournalEntry, type WorkflowJournalStore, type ResumeClaimArgs } from "../../core/workflow-journal-store.js";
+import { type CorruptReadInfo } from "./corrupt-read-sink.js";
 /**
  * SVC-2 — the shared size bound for a journaled workflow-agent entry, so ALL backends answer an oversize
  * TaskResult with the SAME refusal (no dialect divergence). Inlined from service's `workflow-journal-limits` on
@@ -46,6 +47,12 @@ export declare const RESUME_CLAIM_SWEEP_INTERVAL_MS = 60000;
  * stays well clear of that handover rather than adding a second unlinker to it.
  */
 export declare const RESUME_CLAIM_REAP_GRACE_MS: number;
+export interface FileWorkflowJournalStoreOptions {
+    /** Disclosure seat for a ledger line this store DROPPED on replay (not JSON, not a record, or a record
+     *  with none of this ledger's members) — a resume that silently finds "nothing to replay" re-runs the
+     *  work with no signal. Never fires on a missing ledger; swallow-guarded. */
+    onCorruptRead?: (info: CorruptReadInfo) => void;
+}
 export declare class FileWorkflowJournalStore implements WorkflowJournalStore {
     private readonly fsyncEnabled;
     private readonly dir;
@@ -65,7 +72,9 @@ export declare class FileWorkflowJournalStore implements WorkflowJournalStore {
      *  ledger per append (a journaled result can be MBs; a many-agent workflow would go O(n²) on disk). One replay
      *  discovers it; every later append compares against the cache. */
     private get scopes();
-    constructor(root: string, fsyncEnabled?: boolean);
+    /** The swallow-guarded corrupt-read seat (undefined = the old silent tolerance). */
+    private readonly discloseCorrupt;
+    constructor(root: string, fsyncEnabled?: boolean, opts?: FileWorkflowJournalStoreOptions);
     private pathFor;
     /** CC local form: the run's on-disk journal path for the notification diagnostics line.
      *  Traversal-shaped ids (LLM-controlled on some paths) degrade to undefined, never throw. */

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

@@ -2,7 +2,8 @@ import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, unlinkSync
 import { createHash } from "node:crypto";
 import { join } from "node:path";
 import { callKeyOrdinal } from "../../core/workflow-journal-store.js";
-import { AppendLog } from "./fs-atomic.js";
+import { AppendLog, readJsonlRecords } from "./fs-atomic.js";
+import { guardCorruptSink } from "./corrupt-read-sink.js";
 import { canonicalStoreKey, sanitizePathComponent, writeThenLink } from "./fs-atomic.js";
 import { assertAdoptionBootGate } from "./adoption/marker.js";
 import { assertJournalEntryFits } from "../../core/workflow-journal-store.js";
@@ -32,8 +33,10 @@ export class FileWorkflowJournalStore {
     get scopes() {
         return this.shared.scopes;
     }
-    constructor(root, fsyncEnabled = true) {
+    discloseCorrupt;
+    constructor(root, fsyncEnabled = true, opts) {
         this.fsyncEnabled = fsyncEnabled;
+        this.discloseCorrupt = guardCorruptSink(opts?.onCorruptRead);
         assertAdoptionBootGate(root, "FileWorkflowJournalStore");
         this.dir = join(root, "workflow-journal");
         mkdirSync(this.dir, { recursive: true, mode: 0o700 });
@@ -72,18 +75,11 @@ export class FileWorkflowJournalStore {
             return undefined;
         let scope;
         const byOrdinal = new Map();
-        for (const line of readFileSync(path, "utf8").split("\n")) {
-            if (!line.trim())
+        for (const rec of readJsonlRecords(path, this.discloseCorrupt)) {
+            if (typeof rec.callKey !== "string" || typeof rec.scope !== "string" || !Number.isFinite(rec.ordinal)) {
+                this.discloseCorrupt?.({ path, reason: "missing-required: a journal line carries no callKey/scope pair (skipped; the rest of the replay is intact)" });
                 continue;
-            let rec;
-            try {
-                rec = JSON.parse(line);
             }
-            catch {
-                continue;
-            }
-            if (typeof rec.callKey !== "string" || typeof rec.scope !== "string")
-                continue;
             scope = scope ?? rec.scope;
             if (rec.scope !== scope)
                 continue;

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

@@ -1,10 +1,13 @@
 import { type WorkflowRunListByScopeOptions, type WorkflowRunStore, type WorkflowRunSummary } from "../../core/workflow-run-store.js";
 import type { WorkflowRun } from "../../orchestration/workflow.js";
+import { type CorruptReadInfo } from "./corrupt-read-sink.js";
 export interface FileWorkflowRunStoreOptions {
     /** When false, a ledger append is NOT fsync'd (the observability store is non-engine-critical). Default true. */
     fsync?: boolean;
     /** Compact the ledger into a snapshot once it exceeds this many events (then truncate). Default 1000. */
     compactEvery?: number;
+    /** The observability ledger's seat; see {@link import("./shared-ledger.js").LedgerPaths.onCorruptRead}. */
+    onCorruptRead?: (info: CorruptReadInfo) => void;
 }
 export declare class FileWorkflowRunStore implements WorkflowRunStore {
     private readonly fsyncEnabled;

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

@@ -2,7 +2,9 @@ import { join } from "node:path";
 import { assertRetentionPolicy } from "../../core/retention-policy.js";
 import { WorkflowRunStoreError, isTerminalWorkflowStatus, nextWorkflowRunOnUpdate, queryWorkflowRuns, } from "../../core/workflow-run-store.js";
 import { SharedLedgerTable } from "./shared-ledger.js";
+import { guardCorruptSink } from "./corrupt-read-sink.js";
 import { assertAdoptionBootGate } from "./adoption/marker.js";
+const isRunRow = (x) => x !== null && typeof x === "object" && typeof x.id === "string";
 const runLedgers = new SharedLedgerTable({
     label: "workflow-run ledger",
     keyOf: (run) => run.id,
@@ -13,6 +15,13 @@ const runLedgers = new SharedLedgerTable({
         }
         runs.set(ev.id, ev.run);
     },
+    judgeRow: isRunRow,
+    judgeEvent: (x) => {
+        const ev = x;
+        if (typeof ev.id !== "string")
+            return false;
+        return ev.t === "delete" ? true : isRunRow(ev.run);
+    },
 });
 export class FileWorkflowRunStore {
     fsyncEnabled;
@@ -30,6 +39,7 @@ export class FileWorkflowRunStore {
         this.ledger = runLedgers.acquire({
             dir,
             tmpDir: join(root, "tmp"),
+            ...(opts.onCorruptRead !== undefined ? { onCorruptRead: guardCorruptSink(opts.onCorruptRead) } : {}),
             ledgerPath: join(dir, "runs.jsonl"),
             snapshotPath: join(dir, "runs.snapshot.jsonl"),
         });

package/dist/tools/artifact/local-stub.js

@@ -1,7 +1,7 @@
 import { randomBytes } from "node:crypto";
 import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve, sep } from "node:path";
-import {} from "../../core/artifact-host.js";
+import { ARTIFACT_HOST_FAILURE_CODES, } from "../../core/artifact-host.js";
 import { physicalPathOf } from "../../core/physical-path.js";
 import { acquireStoreDirLock } from "../../stores/file/fs-atomic.js";
 import { normalizePublishedPath } from "./artifact-tool.js";
@@ -25,6 +25,18 @@ const isRow = (x, key) => {
         return false;
     return r.files.every((f) => f !== null && typeof f === "object" && typeof f.path === "string" && normalizePublishedPath(f.path).ok && Number.isSafeInteger(f.bytes));
 };
+const isAttempt = (x) => {
+    if (x === null || typeof x !== "object" || Array.isArray(x))
+        return false;
+    const a = x;
+    if ("ref" in a) {
+        const r = a.ref;
+        return r !== null && typeof r === "object" && typeof r.url === "string" && typeof r.slug === "string" && typeof r.version === "string";
+    }
+    if (typeof a.code !== "string" || !ARTIFACT_HOST_FAILURE_CODES.includes(a.code))
+        return false;
+    return a.code === "conflict" ? typeof a.slug === "string" && typeof a.currentVersion === "string" : typeof a.message === "string";
+};
 function parseLedger(text, path) {
     let parsed;
     try {
@@ -40,6 +52,9 @@ function parseLedger(text, path) {
     for (const [key, row] of Object.entries(l.artifacts))
         if (!isRow(row, key))
             throw new Error(`artifact stub ledger is corrupt (bad artifact row): ${path}`);
+    for (const attempt of Object.values(l.attempts))
+        if (!isAttempt(attempt))
+            throw new Error(`artifact stub ledger is corrupt (bad attempt record): ${path}`);
     return { v: 1, artifacts: { ...l.artifacts }, attempts: { ...l.attempts } };
 }
 function fsyncDirBestEffort(dir) {

package/dist/tools/fs/dead-cwd.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The tracked-cwd liveness probe and its diagnosis, shared by the three sites that spawn into the tracked
+ * logical cwd: the shell's foreground and background legs, and the watch tool's background leg. A second
+ * copy of either half would be a second answer to "is this directory usable?" and a second refusal
+ * wording for the same fact, so both are minted here once and each leg passes only its own tool name.
+ */
+import type { ExecutionEnv } from "../../internal/harness-types.js";
+/**
+ * Is `dir` USABLE as a spawn cwd? "Dead" is the whole class, not just deletion: gone, replaced by a FILE
+ * of the same name or standing under one, or a symlink that does not resolve to a directory. `fileInfo`
+ * is lstat-semantics, so a symlink is judged by FOLLOWING it (`canonicalPath`, then one probe of the
+ * target — a link retargeted at a file resolves perfectly well and is still not a cwd).
+ *
+ * The failure direction is deliberately asymmetric. Where a failure says nothing about the chain (the
+ * initial lstat, the target's own), an error means death only when it SAYS so — refusing a command, or
+ * resetting somebody's working directory, over one flaky stat would be worse than the failure being
+ * diagnosed. The RESOLUTION step is the exception: a chain that will not resolve is no directory by any
+ * reading; see {@link resolutionFailureMeansDead} for the one code that step reads as death on top.
+ */
+export declare function isDeadCwd(env: ExecutionEnv, dir: string, signal?: AbortSignal): Promise<boolean>;
+/**
+ * Dead-cwd diagnosis for a never-started command (spawn_error / shell_unavailable): a command that
+ * DELETED or REPLACED the tracked cwd (e.g. `opam clean` after `cd` into a build dir) leaves the
+ * persistent session pinned to a dead directory — every later spawn fails ENOENT/ENOTDIR with a message
+ * blaming the SHELL BINARY ("spawn /bin/bash ENOENT"), the model concludes bash is gone, and the run is
+ * permanently disabled (TB compile-compcert, 14 contaminated calls). The env can't distinguish this (spawn
+ * reports the same code either way), so probe here:
+ *  - tracked cwd dead + task root alive → SELF-HEAL: reset the tracked cwd to the root, tell the model
+ *    what happened and that a retry works;
+ *  - tracked cwd dead + root ALSO dead (never promise a retry that must fail) → honest
+ *    unrecoverable verdict;
+ *  - cwd IS the root and it's dead (`rm -rf "$PWD"` in place — a diverged-guard would
+ *    skip diagnosis entirely) → honest root-gone verdict (no reset target exists);
+ *  - the caller knows NO root (`root === undefined` — a direct mount that was never handed one) → say the
+ *    cwd is gone and that this tool has no reset target, and stop there. Calling that directory "the task
+ *    root" or declaring the tree unrecoverable would both be claims the caller cannot back: the root may
+ *    well be alive, and a `cd` to it recovers. Nothing is reset.
+ *  - cwd healthy → return undefined (the spawn failure has another cause; keep the original error).
+ * Returns the model-facing message, or undefined when this is not a dead-cwd case. Uses only the public
+ * env faces (`fileInfo`/`canonicalPath`) — works for any env that maps never-started failures to
+ * spawn_error/shell_unavailable (contract note on ExecutionErrorCode).
+ *
+ * `root` is REQUIRED-but-nullable on purpose (not an optional parameter): a caller without a root has to
+ * say so at the call site, so "this mount has no root" can never be spelled the same way as "I forgot".
+ */
+export declare function diagnoseDeadCwd(env: ExecutionEnv, toolName: string, effectiveCwd: string, root: string | undefined, cwdRef?: {
+    current: string;
+}, signal?: AbortSignal): Promise<string | undefined>;