@delegance/claude-autopilot 5.5.2 → 7.2.0

package/dist/src/core/run-state/runs.js

@@ -0,0 +1,288 @@
+// src/core/run-state/runs.ts
+//
+// Top-level Run State Engine helpers — createRun, listRuns, gcRuns. These
+// are the entry points the (yet-to-be-built) phase wrapper, CLI, and budget
+// enforcer will call. Phase 1 ships only the data layer; later phases build
+// on top.
+//
+// Spec: docs/specs/v6-run-state-engine.md "State on disk", "Run lifecycle",
+// "Resume command".
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { ulid, decodeTime } from "./ulid.js";
+import { acquireRunLock } from "./lock.js";
+import { appendEvent, foldEvents, readEvents, stateToIndexEntry } from "./events.js";
+import { writeStateSnapshot } from "./state.js";
+import { RUN_STATE_SCHEMA_VERSION, } from "./types.js";
+const CACHE_DIR = '.guardrail-cache';
+const RUNS_DIR = 'runs';
+const INDEX_FILE = 'index.json';
+export function runsRoot(cwd) {
+    return path.join(cwd, CACHE_DIR, RUNS_DIR);
+}
+export function indexPath(cwd) {
+    return path.join(runsRoot(cwd), INDEX_FILE);
+}
+export function runDirFor(cwd, runId) {
+    return path.join(runsRoot(cwd), runId);
+}
+/** Create a fresh run directory, acquire its advisory lock, write the
+ *  initial state.json, and emit the `run.start` event.
+ *
+ *  Throws GuardrailError(lock_held) if a stale lock exists for the freshly-
+ *  generated runId — extremely unlikely (ULIDs are unique) but possible if
+ *  two parallel invocations on the same OS clock collide on a leftover dir
+ *  on disk. Caller can simply retry. */
+export async function createRun(opts) {
+    if (!Array.isArray(opts.phases) || opts.phases.length === 0) {
+        throw new Error('createRun: phases[] must be a non-empty array');
+    }
+    const runId = ulid();
+    const runDir = runDirFor(opts.cwd, runId);
+    fs.mkdirSync(runDir, { recursive: true });
+    // Acquire BEFORE first event write so writerId is well-defined.
+    const lock = await acquireRunLock(runDir);
+    // Seed the state snapshot first (with no events yet) so that even a crash
+    // before run.start lands leaves a recoverable artifact.
+    const startedAt = new Date(decodeTime(runId)).toISOString();
+    const initialState = {
+        schema_version: RUN_STATE_SCHEMA_VERSION,
+        runId,
+        startedAt,
+        status: 'pending',
+        phases: opts.phases.map((name, idx) => ({
+            schema_version: RUN_STATE_SCHEMA_VERSION,
+            name,
+            index: idx,
+            status: 'pending',
+            idempotent: false,
+            hasSideEffects: false,
+            costUSD: 0,
+            attempts: 0,
+            artifacts: [],
+            externalRefs: [],
+        })),
+        currentPhaseIdx: 0,
+        totalCostUSD: 0,
+        lastEventSeq: 0,
+        writerId: lock.writerId,
+        cwd: opts.cwd,
+        ...(opts.config !== undefined ? { config: opts.config } : {}),
+    };
+    writeStateSnapshot(runDir, initialState);
+    // Emit run.start. The appender owns the seq counter.
+    const startEvent = appendEvent(runDir, {
+        event: 'run.start',
+        phases: opts.phases,
+        ...(opts.config !== undefined ? { config: opts.config } : {}),
+    }, { writerId: lock.writerId, runId });
+    // Refresh the snapshot to reflect lastEventSeq=1.
+    initialState.lastEventSeq = startEvent.seq;
+    writeStateSnapshot(runDir, initialState);
+    // Refresh the index (best-effort — index is a pure cache).
+    try {
+        rebuildIndex(opts.cwd);
+    }
+    catch {
+        // Index failure shouldn't block the run.
+    }
+    return { runId, runDir, state: initialState, lock };
+}
+// ----------------------------------------------------------------------------
+// Listing + indexing.
+// ----------------------------------------------------------------------------
+function readIndex(cwd) {
+    const p = indexPath(cwd);
+    if (!fs.existsSync(p))
+        return null;
+    try {
+        return JSON.parse(fs.readFileSync(p, 'utf8'));
+    }
+    catch {
+        return null; // treat unreadable index as missing — it's a cache
+    }
+}
+function writeIndex(cwd, index) {
+    fs.mkdirSync(runsRoot(cwd), { recursive: true });
+    fs.writeFileSync(indexPath(cwd), JSON.stringify(index, null, 2), 'utf8');
+}
+/** Rebuild index.json from each run dir's state.json (or replayed state if
+ *  the snapshot is missing / corrupt). Newest-first ordering by ULID. */
+export function rebuildIndex(cwd) {
+    const root = runsRoot(cwd);
+    const entries = [];
+    if (!fs.existsSync(root)) {
+        const empty = { schema_version: RUN_STATE_SCHEMA_VERSION, runs: [] };
+        writeIndex(cwd, empty);
+        return empty;
+    }
+    const dirents = fs.readdirSync(root, { withFileTypes: true });
+    for (const d of dirents) {
+        if (!d.isDirectory())
+            continue;
+        const runId = d.name;
+        const runDir = path.join(root, runId);
+        let state;
+        let recovered = false;
+        try {
+            // We don't hold the lock during a list — listing is read-only and
+            // races with a concurrent writer are tolerated (we may briefly read
+            // a stale snapshot, which is fine). For replay-recovery we DO need
+            // a writerId, but only if the snapshot is bad; if so the run isn't
+            // healthy anyway, and we use a synthetic writerId so we never
+            // mutate the run's events.ndjson during a list operation.
+            // Instead of recoverState (which writes events) we just replay
+            // in-memory.
+            const fromEvents = readEvents(runDir);
+            // Build a fresh snapshot if state.json is missing or unreadable.
+            // Use the project-internal file paths to avoid pulling readState
+            // here just to throw.
+            const stateFilePath = path.join(runDir, 'state.json');
+            if (fs.existsSync(stateFilePath)) {
+                try {
+                    state = JSON.parse(fs.readFileSync(stateFilePath, 'utf8'));
+                }
+                catch {
+                    // fall through to replay
+                    recovered = true;
+                    // Replay needs the events; if the events are also corrupt we
+                    // surface the error via skip.
+                    state = replayInMemory(runDir, fromEvents.events);
+                }
+            }
+            else {
+                recovered = true;
+                state = replayInMemory(runDir, fromEvents.events);
+            }
+        }
+        catch {
+            // Corrupt run dir — skip from the index entirely. `runs doctor`
+            // (Phase 3) will surface these.
+            continue;
+        }
+        entries.push(stateToIndexEntry(state, recovered));
+    }
+    // ULIDs are sortable; we want NEWEST first → reverse-sort by runId.
+    entries.sort((a, b) => (a.runId < b.runId ? 1 : a.runId > b.runId ? -1 : 0));
+    const index = { schema_version: RUN_STATE_SCHEMA_VERSION, runs: entries };
+    writeIndex(cwd, index);
+    return index;
+}
+/** In-memory replay used by rebuildIndex / listRuns — does NOT write to disk
+ *  or emit events. Lets us pass pre-fetched events so we don't double-read
+ *  the file. */
+function replayInMemory(runDir, events) {
+    return foldEvents(runDir, events);
+}
+/** List all runs, newest-first. Lazily rebuilds index.json if missing. */
+export function listRuns(cwd, opts = {}) {
+    if (opts.rebuild)
+        return rebuildIndex(cwd).runs;
+    const idx = readIndex(cwd);
+    if (idx)
+        return idx.runs;
+    return rebuildIndex(cwd).runs;
+}
+/** Delete completed runs older than N days. Honors the spec's symlink
+ *  safety: uses lstat so we never traverse a symlink out of the runs/
+ *  tree. */
+export function gcRuns(cwd, opts) {
+    const root = runsRoot(cwd);
+    const result = { deleted: [], kept: [], skippedUnsafe: [] };
+    if (!fs.existsSync(root))
+        return result;
+    const cutoff = (opts.now ?? Date.now()) - opts.olderThanDays * 86_400_000;
+    const entries = fs.readdirSync(root, { withFileTypes: true });
+    for (const d of entries) {
+        if (d.name === INDEX_FILE)
+            continue;
+        const runId = d.name;
+        const runDir = path.join(root, runId);
+        // Symlinks (whether to dirs or files) are flagged unsafe. Dirent's
+        // isDirectory() returns FALSE for a symlink even if the target is a
+        // directory, which matches our policy here — we only operate on real
+        // dirs that lstat agrees are not links.
+        if (d.isSymbolicLink()) {
+            result.skippedUnsafe.push(runId);
+            continue;
+        }
+        if (!d.isDirectory())
+            continue;
+        let lst;
+        try {
+            lst = fs.lstatSync(runDir);
+        }
+        catch {
+            result.skippedUnsafe.push(runId);
+            continue;
+        }
+        if (!lst.isDirectory() || lst.isSymbolicLink()) {
+            result.skippedUnsafe.push(runId);
+            continue;
+        }
+        // Read state to decide. If unreadable, skip — `runs doctor` will deal.
+        let state = null;
+        try {
+            const sp = path.join(runDir, 'state.json');
+            if (fs.existsSync(sp)) {
+                state = JSON.parse(fs.readFileSync(sp, 'utf8'));
+            }
+        }
+        catch {
+            // fall through
+        }
+        if (!state) {
+            // Defensive: try to derive from ULID alone for "old enough" check.
+            // If runId isn't a ULID we treat it as suspicious and skip.
+            let createdMs;
+            try {
+                createdMs = decodeTime(runId);
+            }
+            catch {
+                result.skippedUnsafe.push(runId);
+                continue;
+            }
+            if (createdMs >= cutoff) {
+                result.kept.push(runId);
+                continue;
+            }
+            // Fall through — eligible for delete.
+        }
+        else {
+            const terminal = state.status === 'success' || state.status === 'failed' || state.status === 'aborted';
+            if (!terminal) {
+                result.kept.push(runId);
+                continue;
+            }
+            const endMs = state.endedAt ? Date.parse(state.endedAt) : Date.parse(state.startedAt);
+            if (Number.isFinite(endMs) && endMs >= cutoff) {
+                result.kept.push(runId);
+                continue;
+            }
+        }
+        if (opts.dryRun) {
+            result.deleted.push(runId);
+            continue;
+        }
+        try {
+            // Defense in depth: refuse to recurse out via a symlink hidden inside.
+            // fs.rmSync with `force: true, recursive: true` handles dirs but
+            // also follows nothing — it doesn't traverse symlinks for deletion
+            // boundaries (it deletes the link, not the target).
+            fs.rmSync(runDir, { recursive: true, force: true });
+            result.deleted.push(runId);
+        }
+        catch {
+            result.skippedUnsafe.push(runId);
+        }
+    }
+    // Refresh the index after a real GC pass.
+    if (!opts.dryRun && result.deleted.length > 0) {
+        try {
+            rebuildIndex(cwd);
+        }
+        catch { /* index is cache */ }
+    }
+    return result;
+}
+//# sourceMappingURL=runs.js.map

package/dist/src/core/run-state/snapshot.d.ts

@@ -0,0 +1,14 @@
+import { type PhaseSnapshot } from './types.ts';
+export declare function phasesDir(runDir: string): string;
+export declare function phaseSnapshotPath(runDir: string, phaseName: string): string;
+/** Write a per-phase snapshot atomically. Identical sequence to
+ *  state.json:
+ *    open(tmp, 'w') → write → fsync(fd) → close → rename → fsync(dirfd).
+ *
+ *  Any pre-existing snapshot is left untouched until the rename, so a crash
+ *  mid-write leaves the previous snapshot intact. */
+export declare function writePhaseSnapshot(runDir: string, snapshot: PhaseSnapshot): void;
+/** Read a per-phase snapshot. Returns null if missing. Throws
+ *  GuardrailError(corrupted_state) if it's present-but-unparseable. */
+export declare function readPhaseSnapshot(runDir: string, phaseName: string): PhaseSnapshot | null;
+//# sourceMappingURL=snapshot.d.ts.map

package/dist/src/core/run-state/snapshot.js

@@ -0,0 +1,114 @@
+// src/core/run-state/snapshot.ts
+//
+// Atomic per-phase snapshot writer/reader. Each phase, after run, gets a
+// `phases/<name>.json` artifact mirroring the corresponding entry in
+// state.json. Writes use the same tmp+rename+fsync protocol as state.json so
+// a crash mid-write never leaves a half-baked phase snapshot on disk.
+//
+// Phase 1 left this as a TODO; Phase 2 fills it in to back the lifecycle
+// wrapper (`runPhase`).
+//
+// Spec: docs/specs/v6-run-state-engine.md "State on disk" — `phases/<name>.json`.
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { GuardrailError } from "../errors.js";
+const PHASES_DIR = 'phases';
+export function phasesDir(runDir) {
+    return path.join(runDir, PHASES_DIR);
+}
+export function phaseSnapshotPath(runDir, phaseName) {
+    return path.join(phasesDir(runDir), `${sanitizePhaseFilename(phaseName)}.json`);
+}
+/** Reject filename characters that would escape `phases/`. Phase names are
+ *  caller-supplied strings; we bound them to a safe charset rather than
+ *  letting `..` / path separators sneak in.
+ *
+ *  Allowed: ASCII alphanumerics, dash, underscore, dot. Anything else is
+ *  rejected with a typed error so callers can correct the call-site rather
+ *  than silently producing a write to `../somewhere`. */
+function sanitizePhaseFilename(phaseName) {
+    if (!phaseName || typeof phaseName !== 'string') {
+        throw new GuardrailError(`phase snapshot: name must be a non-empty string`, { code: 'invalid_config', provider: 'run-state', details: { phaseName } });
+    }
+    if (!/^[A-Za-z0-9._-]+$/.test(phaseName)) {
+        throw new GuardrailError(`phase snapshot: name "${phaseName}" contains unsupported characters`, { code: 'invalid_config', provider: 'run-state', details: { phaseName } });
+    }
+    return phaseName;
+}
+/** Write a per-phase snapshot atomically. Identical sequence to
+ *  state.json:
+ *    open(tmp, 'w') → write → fsync(fd) → close → rename → fsync(dirfd).
+ *
+ *  Any pre-existing snapshot is left untouched until the rename, so a crash
+ *  mid-write leaves the previous snapshot intact. */
+export function writePhaseSnapshot(runDir, snapshot) {
+    const dir = phasesDir(runDir);
+    fs.mkdirSync(dir, { recursive: true });
+    const target = phaseSnapshotPath(runDir, snapshot.name);
+    const tmp = `${target}.tmp`;
+    const data = JSON.stringify(snapshot, null, 2);
+    const fd = fs.openSync(tmp, 'w');
+    let wroteOk = false;
+    try {
+        fs.writeSync(fd, data);
+        fs.fsyncSync(fd);
+        wroteOk = true;
+    }
+    finally {
+        fs.closeSync(fd);
+        if (!wroteOk) {
+            try {
+                fs.unlinkSync(tmp);
+            }
+            catch { /* ignore */ }
+        }
+    }
+    fs.renameSync(tmp, target);
+    // Best-effort dir fsync for rename durability. Same EISDIR/EPERM/ENOTSUP
+    // tolerance as state.ts (tmpfs / SMB / Windows quirks).
+    try {
+        const dirFd = fs.openSync(dir, 'r');
+        try {
+            fs.fsyncSync(dirFd);
+        }
+        finally {
+            fs.closeSync(dirFd);
+        }
+    }
+    catch (err) {
+        const code = err.code;
+        if (code !== 'EISDIR' && code !== 'EPERM' && code !== 'ENOTSUP') {
+            throw new GuardrailError(`phase snapshot: dir fsync failed: ${err.message}`, {
+                code: 'corrupted_state',
+                provider: 'run-state',
+                details: { runDir, phaseName: snapshot.name, errno: code },
+            });
+        }
+    }
+}
+/** Read a per-phase snapshot. Returns null if missing. Throws
+ *  GuardrailError(corrupted_state) if it's present-but-unparseable. */
+export function readPhaseSnapshot(runDir, phaseName) {
+    const p = phaseSnapshotPath(runDir, phaseName);
+    if (!fs.existsSync(p))
+        return null;
+    const raw = fs.readFileSync(p, 'utf8');
+    if (!raw) {
+        throw new GuardrailError(`phase snapshot: empty file ${p}`, {
+            code: 'corrupted_state',
+            provider: 'run-state',
+            details: { runDir, phaseName },
+        });
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        throw new GuardrailError(`phase snapshot: corrupt JSON: ${err.message}`, {
+            code: 'corrupted_state',
+            provider: 'run-state',
+            details: { runDir, phaseName, error: err.message },
+        });
+    }
+}
+//# sourceMappingURL=snapshot.js.map

package/dist/src/core/run-state/state.d.ts

@@ -0,0 +1,40 @@
+import { type RunState, type WriterId } from './types.ts';
+/** Lowest `schema_version` value this binary can replay. Bump only on a
+ *  major release that drops support for a prior wire shape. */
+export declare const RUN_STATE_MIN_SUPPORTED_SCHEMA_VERSION: 1;
+/** Highest `schema_version` value this binary can replay. Always equal to
+ *  the writer's `RUN_STATE_SCHEMA_VERSION` — the writer never produces a
+ *  newer shape than the reader on the same binary. */
+export declare const RUN_STATE_MAX_SUPPORTED_SCHEMA_VERSION: 2;
+export declare function statePath(runDir: string): string;
+/** Write the snapshot atomically. Sequence:
+ *    open(tmp, 'w') → write → fsync(fd) → close → rename → fsync(dirfd).
+ *
+ *  If any step fails, the tmp file is best-effort-cleaned. The pre-existing
+ *  state.json is untouched until the rename, so a crash anywhere before
+ *  rename leaves the previous snapshot intact. */
+export declare function writeStateSnapshot(runDir: string, state: RunState): void;
+/** Read the snapshot. Returns null if missing. Throws GuardrailError(
+ *  corrupted_state) if it's present but unparseable — recoverState() handles
+ *  the fallback to events-replay. */
+export declare function readStateSnapshot(runDir: string): RunState | null;
+export interface RecoverStateOptions {
+    /** Writer that will own the recovery's `index.rebuilt` event. The
+     *  caller must already hold the run's advisory lock. */
+    writerId: WriterId;
+    /** runId override; defaults to basename(runDir). */
+    runId?: string;
+}
+export interface RecoverStateResult {
+    state: RunState;
+    /** True if recovery actually re-derived the snapshot (vs. just reading
+     *  a healthy one). */
+    recovered: boolean;
+    /** When `recovered === true`, the cause that triggered the rebuild. */
+    cause?: 'missing' | 'corrupt';
+}
+/** Open-or-recover the snapshot. If state.json is missing or corrupt, fall
+ *  back to events.ndjson replay, persist the result, and emit
+ *  `index.rebuilt`. The caller MUST already hold the advisory lock. */
+export declare function recoverState(runDir: string, opts: RecoverStateOptions): RecoverStateResult;
+//# sourceMappingURL=state.d.ts.map

package/dist/src/core/run-state/state.js

@@ -0,0 +1,164 @@
+// src/core/run-state/state.ts
+//
+// Atomic snapshot writer for state.json. Persistence protocol per spec:
+//   1. write to state.json.tmp
+//   2. fsync(file) on the tmp
+//   3. rename tmp → state.json
+//   4. fsync(dir) so the rename is durable
+//
+// readStateSnapshot() returns null if the snapshot is missing (the canonical
+// "fresh run" state) and throws if it's present-but-corrupt. recoverState()
+// is the resilience entry point — it falls back to events.ndjson replay if
+// the snapshot is unreadable, then rewrites a clean snapshot and emits an
+// `index.rebuilt` event.
+//
+// Spec: docs/specs/v6-run-state-engine.md "Persistence protocol — Durable
+// append", "Failure modes the user should never have to debug".
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { GuardrailError } from "../errors.js";
+import { appendEvent, replayState } from "./events.js";
+import { RUN_STATE_SCHEMA_VERSION } from "./types.js";
+// ---------------------------------------------------------------------------
+// v6.2.2 — cache contract version policy (per spec / codex WARNING #1).
+//
+// `replayState()` uses these bounds to reject run dirs whose `schema_version`
+// is outside the supported window. Strict equality would block resume across
+// rolling deploys / mixed binary fleets — the window allows additive minor
+// schema bumps to ship without breaking forward-read on older readers, and a
+// future major (v7) resets `MIN_SUPPORTED` to break with the past explicitly.
+// ---------------------------------------------------------------------------
+/** Lowest `schema_version` value this binary can replay. Bump only on a
+ *  major release that drops support for a prior wire shape. */
+export const RUN_STATE_MIN_SUPPORTED_SCHEMA_VERSION = 1;
+/** Highest `schema_version` value this binary can replay. Always equal to
+ *  the writer's `RUN_STATE_SCHEMA_VERSION` — the writer never produces a
+ *  newer shape than the reader on the same binary. */
+export const RUN_STATE_MAX_SUPPORTED_SCHEMA_VERSION = RUN_STATE_SCHEMA_VERSION;
+const STATE_FILE = 'state.json';
+const STATE_TMP = 'state.json.tmp';
+export function statePath(runDir) {
+    return path.join(runDir, STATE_FILE);
+}
+function tmpPath(runDir) {
+    return path.join(runDir, STATE_TMP);
+}
+/** Write the snapshot atomically. Sequence:
+ *    open(tmp, 'w') → write → fsync(fd) → close → rename → fsync(dirfd).
+ *
+ *  If any step fails, the tmp file is best-effort-cleaned. The pre-existing
+ *  state.json is untouched until the rename, so a crash anywhere before
+ *  rename leaves the previous snapshot intact. */
+export function writeStateSnapshot(runDir, state) {
+    fs.mkdirSync(runDir, { recursive: true });
+    const data = JSON.stringify(state, null, 2);
+    const tmp = tmpPath(runDir);
+    const target = statePath(runDir);
+    const fd = fs.openSync(tmp, 'w');
+    let wroteOk = false;
+    try {
+        fs.writeSync(fd, data);
+        fs.fsyncSync(fd);
+        wroteOk = true;
+    }
+    finally {
+        fs.closeSync(fd);
+        if (!wroteOk) {
+            try {
+                fs.unlinkSync(tmp);
+            }
+            catch { /* ignore */ }
+        }
+    }
+    fs.renameSync(tmp, target);
+    // fsync the parent directory so the rename is durable on power-loss.
+    // On Linux/macOS this is best-effort (ENOTSUP on some filesystems for
+    // dir fds); we swallow expected platform-specific failures so a
+    // working-directory on tmpfs / SMB / etc. doesn't break the writer.
+    try {
+        const dirFd = fs.openSync(runDir, 'r');
+        try {
+            fs.fsyncSync(dirFd);
+        }
+        finally {
+            fs.closeSync(dirFd);
+        }
+    }
+    catch (err) {
+        const code = err.code;
+        // EISDIR happens on some Windows configs where opening a dir for read
+        // isn't permitted; EPERM/ENOTSUP on certain FS. We don't escalate —
+        // the rename itself is atomic; dir-fsync is a defense-in-depth.
+        if (code !== 'EISDIR' && code !== 'EPERM' && code !== 'ENOTSUP') {
+            // Anything else, surface as warning via a thrown GuardrailError so
+            // callers can decide. We choose `corrupted_state` as the closest
+            // category since the snapshot may not have been durably committed.
+            throw new GuardrailError(`state.json: dir fsync failed: ${err.message}`, {
+                code: 'corrupted_state',
+                provider: 'run-state',
+                details: { runDir, errno: code },
+            });
+        }
+    }
+}
+/** Read the snapshot. Returns null if missing. Throws GuardrailError(
+ *  corrupted_state) if it's present but unparseable — recoverState() handles
+ *  the fallback to events-replay. */
+export function readStateSnapshot(runDir) {
+    const p = statePath(runDir);
+    if (!fs.existsSync(p))
+        return null;
+    const raw = fs.readFileSync(p, 'utf8');
+    if (!raw) {
+        throw new GuardrailError(`state.json: empty file`, {
+            code: 'corrupted_state',
+            provider: 'run-state',
+            details: { runDir },
+        });
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        throw new GuardrailError(`state.json: corrupt JSON: ${err.message}`, {
+            code: 'corrupted_state',
+            provider: 'run-state',
+            details: { runDir, error: err.message },
+        });
+    }
+}
+/** Open-or-recover the snapshot. If state.json is missing or corrupt, fall
+ *  back to events.ndjson replay, persist the result, and emit
+ *  `index.rebuilt`. The caller MUST already hold the advisory lock. */
+export function recoverState(runDir, opts) {
+    let cause = null;
+    let snapshot = null;
+    try {
+        snapshot = readStateSnapshot(runDir);
+        if (!snapshot)
+            cause = 'missing';
+    }
+    catch (err) {
+        if (err instanceof GuardrailError && err.code === 'corrupted_state') {
+            cause = 'corrupt';
+        }
+        else {
+            throw err;
+        }
+    }
+    if (!cause && snapshot) {
+        return { state: snapshot, recovered: false };
+    }
+    // Recovery path. Replay first, then persist, then emit event in that
+    // order — emitting the event before persisting would leave a record of
+    // a recovery that didn't actually land if we crash between the two.
+    const replayed = replayState(runDir);
+    writeStateSnapshot(runDir, replayed);
+    appendEvent(runDir, { event: 'index.rebuilt', cause: cause }, { writerId: opts.writerId, ...(opts.runId !== undefined ? { runId: opts.runId } : {}) });
+    return {
+        state: replayed,
+        recovered: true,
+        cause: cause,
+    };
+}
+//# sourceMappingURL=state.js.map