@delegance/claude-autopilot 5.2.2 → 6.2.2

package/dist/src/core/run-state/run-phase-with-lifecycle.js

@@ -0,0 +1,186 @@
+// src/core/run-state/run-phase-with-lifecycle.ts
+//
+// v6.0.6 — extract the lifecycle wrapper that's been duplicated across
+// every wrapped CLI verb (`scan`, `costs`, `fix`, `brainstorm`, `spec`,
+// `plan`, `review`, `validate`). The pattern is mechanical:
+//
+//   1. If engine-off → run the legacy phase body via `runEngineOff()` and
+//      return its result.
+//   2. If engine-on → createRun → optional run.warning for invalid env →
+//      runPhase → emit run.complete (success or failed) → refresh state.json
+//      → release lock (best effort, in finally).
+//
+// This helper sits ON TOP of `runPhase()` from `phase-runner.ts` — it does
+// not replace it. Callers continue to define their own `RunPhase<I, O>` with
+// per-phase `idempotent` / `hasSideEffects` / `run` and pass it in.
+//
+// Why now: with 8 of 10 phases wrapped (the v6.0.5 milestone), the pattern
+// is fully evidenced. The remaining 3 phases (`implement`, `migrate`, `pr`)
+// are side-effecting and need externalRefs — those will inform a v6.0.7+
+// extension to this helper but won't change its core shape. Doing the
+// extraction now means those 3 wraps build against the helper instead of
+// re-introducing the boilerplate.
+//
+// What this helper does NOT do:
+//   - Print success banners — rendering stays in the caller.
+//   - Decide engine-off behavior — that's `runEngineOff`, supplied by the
+//     caller (typically a thin closure over the phase body).
+//   - Plumb externalRefs / readback — the underlying `runPhase()` already
+//     handles those. This helper just owns the run-level lifecycle events.
+//
+// Future extension (v6.0.7+): `implement` / `migrate` / `pr` need
+// externalRef ledger entries (`git-remote-push`, `migration-version`,
+// `github-pr`). The helper's `phase.run` already receives `ctx` so
+// `ctx.emitExternalRef()` works without changes here. If a future PR needs
+// to fan-in run-wide externalRefs from multiple phases (multi-phase
+// pipelines, e.g. autopilot orchestrator), the signature can grow a
+// `phases: RunPhase[]` overload — but the single-phase shape stays identical.
+import { createRun } from "./runs.js";
+import { runPhase } from "./phase-runner.js";
+import { appendEvent, replayState } from "./events.js";
+import { writeStateSnapshot } from "./state.js";
+import { resolveEngineEnabled, emitEngineOffDeprecationWarning, } from "./resolve-engine.js";
+// Inline ANSI codes — same shape every wrapped verb uses. Kept here so the
+// helper doesn't depend on a verb-local `fmt`. The error message format
+// (`[<phase>] engine: phase failed — <msg>` + dim inspect hint) is
+// byte-for-byte identical to what every wrapped phase printed pre-extract.
+const ANSI_RESET = '\x1b[0m';
+const ANSI_DIM = '\x1b[2m';
+const ANSI_RED = '\x1b[31m';
+/** Drive a single-phase engine run with full lifecycle instrumentation,
+ *  OR fall through to the legacy `runEngineOff` callback when the engine
+ *  is disabled by config / CLI / env precedence.
+ *
+ *  Engine-on lifecycle (in order):
+ *    createRun → (optional run.warning for invalid env) → runPhase →
+ *    run.complete (success or failed) → refresh state.json → release lock.
+ *
+ *  On phase failure the helper:
+ *    1. Emits `run.complete` with `status: 'failed'`.
+ *    2. Refreshes state.json from the replayed events.
+ *    3. Prints the legacy `[<phase>] engine: phase failed — <msg>` banner
+ *       to stderr (byte-for-byte identical to the inline pattern that
+ *       lived in 8 of 8 wrapped verbs pre-v6.0.6).
+ *    4. Releases the lock and re-throws so the caller can return its
+ *       legacy non-zero exit code.
+ *
+ *  The lock release in `finally` is best-effort. `release()` is idempotent
+ *  (the runs lock module accepts double-release without throwing), so the
+ *  catch block does not need to release the lock itself — `finally` covers
+ *  both the success and failure exit paths. */
+export async function runPhaseWithLifecycle(opts) {
+    const { cwd, phase, input, config, cliEngine, envEngine, runEngineOff } = opts;
+    // Resolve engine via the canonical precedence (CLI > env > config >
+    // built-in default). The resolver is pure — same inputs always produce
+    // the same decision. We DO consult the loaded config's `engine.enabled`
+    // here so the helper's caller doesn't have to repeat the conditional
+    // spread that every wrapped verb wrote inline.
+    const engineResolved = resolveEngineEnabled({
+        ...(cliEngine !== undefined ? { cliEngine } : {}),
+        ...(envEngine !== undefined ? { envValue: envEngine } : {}),
+        ...(typeof config.engine?.enabled === 'boolean'
+            ? { configEnabled: config.engine.enabled }
+            : {}),
+    });
+    if (!engineResolved.enabled) {
+        // Engine off — call the caller's legacy path. No run dir, no events,
+        // no lifecycle work. Behavior is byte-for-byte identical to pre-engine
+        // versions of the verb. v6.1+ emits a one-line stderr deprecation
+        // notice when the user explicitly opted out (CLI / env / config); the
+        // v6.1 default is `enabled: true`, so a `'default'` source can't reach
+        // this branch and the deprecation helper no-ops on the `enabled: true`
+        // path. v7 removes the opt-out entirely.
+        emitEngineOffDeprecationWarning(engineResolved);
+        const output = await runEngineOff();
+        return { output, runId: null, runDir: null };
+    }
+    // Engine on — full lifecycle. Mirrors the pre-v6.0.6 inline shape that
+    // every wrapped verb duplicated.
+    const created = await createRun({
+        cwd,
+        phases: [phase.name],
+        config: {
+            engine: { enabled: true, source: engineResolved.source },
+            ...(engineResolved.invalidEnvValue !== undefined
+                ? { invalidEnvValue: engineResolved.invalidEnvValue }
+                : {}),
+        },
+    });
+    if (engineResolved.invalidEnvValue !== undefined) {
+        // Surface the invalid env value as a typed warning so observers
+        // (`runs show <id> --events`) can attribute the fallthrough.
+        appendEvent(created.runDir, {
+            event: 'run.warning',
+            message: `invalid CLAUDE_AUTOPILOT_ENGINE=${JSON.stringify(engineResolved.invalidEnvValue)} ignored`,
+            details: { resolution: engineResolved },
+        }, { writerId: created.lock.writerId, runId: created.runId });
+    }
+    const runStartedAt = Date.now();
+    try {
+        const output = await runPhase(phase, input, {
+            runDir: created.runDir,
+            runId: created.runId,
+            writerId: created.lock.writerId,
+            phaseIdx: 0,
+        });
+        // Final lifecycle event — run.complete. The runner doesn't emit this
+        // on its own; it's the caller's responsibility (multi-phase pipelines
+        // emit it after the LAST phase, single-phase wrappers like this emit
+        // after the only phase). Total cost falls back to 0 when the phase
+        // doesn't expose a `costUSD` field on its output (read-only verbs
+        // don't track cost; scan does).
+        const totalCostUSD = extractCostUSD(output);
+        appendEvent(created.runDir, {
+            event: 'run.complete',
+            status: 'success',
+            totalCostUSD,
+            durationMs: Date.now() - runStartedAt,
+        }, { writerId: created.lock.writerId, runId: created.runId });
+        // Refresh state.json from the replayed events. The events.ndjson is
+        // the source of truth; state.json is a derived snapshot that we MUST
+        // rewrite after run.complete so `runs show` / `runs list` reflect the
+        // terminal status without needing to replay on every read.
+        writeStateSnapshot(created.runDir, replayState(created.runDir));
+        return { output, runId: created.runId, runDir: created.runDir };
+    }
+    catch (err) {
+        // Engine-on failure — write run.complete with failed status, refresh
+        // state.json, print the legacy banner to stderr, then re-throw so the
+        // caller can return its legacy non-zero exit code. (Lock release
+        // happens in `finally` regardless of success / failure path.)
+        appendEvent(created.runDir, {
+            event: 'run.complete',
+            status: 'failed',
+            totalCostUSD: 0,
+            durationMs: Date.now() - runStartedAt,
+        }, { writerId: created.lock.writerId, runId: created.runId });
+        writeStateSnapshot(created.runDir, replayState(created.runDir));
+        const message = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`${ANSI_RED}[${phase.name}] engine: phase failed — ${message}${ANSI_RESET}\n`);
+        process.stderr.write(`${ANSI_DIM}  inspect: claude-autopilot runs show ${created.runId} --events${ANSI_RESET}\n`);
+        throw err;
+    }
+    finally {
+        // Best-effort lock release. The lock module's `release()` is
+        // idempotent; if the catch path already released (it doesn't, but a
+        // future change might), this is a no-op. Wrapping the await in
+        // `.catch(() => {})` ensures a release error never masks the original
+        // throw — the spec calls this out explicitly.
+        await created.lock.release().catch(() => { });
+    }
+}
+/** Extract `costUSD` from a phase output if present, else 0. JSON-style
+ *  duck-typing: we accept any output that exposes a numeric `costUSD`
+ *  field. Today only `scan` exposes one; the other 7 wrapped verbs
+ *  return outputs without a cost field, which means `extractCostUSD`
+ *  returns 0 — byte-for-byte matching the inline `totalCostUSD: 0` they
+ *  used pre-v6.0.6. */
+function extractCostUSD(output) {
+    if (output !== null && typeof output === 'object' && 'costUSD' in output) {
+        const v = output.costUSD;
+        if (typeof v === 'number' && Number.isFinite(v))
+            return v;
+    }
+    return 0;
+}
+//# sourceMappingURL=run-phase-with-lifecycle.js.map

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

@@ -0,0 +1,57 @@
+import { type RunLockHandle } from './lock.ts';
+import { type RunIndex, type RunIndexEntry, type RunState } from './types.ts';
+export declare function runsRoot(cwd: string): string;
+export declare function indexPath(cwd: string): string;
+export declare function runDirFor(cwd: string, runId: string): string;
+export interface CreateRunOptions {
+    cwd: string;
+    /** Phase names in the order they will execute. */
+    phases: string[];
+    /** Snapshot of the relevant guardrail.config.yaml fields. Free-form. */
+    config?: Record<string, unknown>;
+}
+export interface CreateRunResult {
+    runId: string;
+    runDir: string;
+    state: RunState;
+    /** Lock handle. Caller MUST `release()` on shutdown. */
+    lock: RunLockHandle;
+}
+/** 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 declare function createRun(opts: CreateRunOptions): Promise<CreateRunResult>;
+/** 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 declare function rebuildIndex(cwd: string): RunIndex;
+export interface ListRunsOptions {
+    /** Force a rebuild from disk even if index.json is fresh. */
+    rebuild?: boolean;
+}
+/** List all runs, newest-first. Lazily rebuilds index.json if missing. */
+export declare function listRuns(cwd: string, opts?: ListRunsOptions): RunIndexEntry[];
+export interface GcRunsOptions {
+    /** Delete completed runs older than this many days. Required. */
+    olderThanDays: number;
+    /** Don't actually delete; just return what would be removed. */
+    dryRun?: boolean;
+    /** Override "now" for tests. Default Date.now(). */
+    now?: number;
+}
+export interface GcRunsResult {
+    /** runIds that were (or would be) deleted. */
+    deleted: string[];
+    /** runIds skipped because they're still active or too young. */
+    kept: string[];
+    /** runIds skipped for safety reasons (symlink, suspicious path). */
+    skippedUnsafe: string[];
+}
+/** 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 declare function gcRuns(cwd: string, opts: GcRunsOptions): GcRunsResult;
+//# sourceMappingURL=runs.d.ts.map

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