@delegance/claude-autopilot 5.5.2 → 7.2.0

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

@@ -0,0 +1,74 @@
+// src/core/run-state/resolve-engine.ts
+//
+// v7.0 — engine-off path retired. The function is preserved for source
+// compatibility with callers that pass `cliEngine` / `envValue` /
+// `configEnabled`, but it now returns `enabled: true` unconditionally.
+//
+// What changed in v7.0 vs v6.x:
+//   - `ENGINE_DEFAULT_V6_0` and `ENGINE_DEFAULT_V6_1` exports REMOVED.
+//     Direct importers must replace with literal `true` (see
+//     docs/v7/breaking-changes.md).
+//   - The deprecation warning helpers (`emitEngineOffDeprecationWarning`
+//     / `shouldWarnEngineOffDeprecation` / `ENGINE_OFF_DEPRECATION_MESSAGE`)
+//     are RETAINED as no-op stubs so call sites don't have to change in
+//     the same PR — they always return false / never fire.
+//   - `parseEngineEnvValue()` is RETAINED for back-compat with any
+//     out-of-tree callers; `resolveEngineEnabled()` ignores the env
+//     value entirely (the engine-off env path is gone).
+//
+// Why keep the stub function shape: the CLI dispatcher passes
+// `cliEngine` / `envEngine` / config to `runPhaseWithLifecycle`, which
+// in turn calls `resolveEngineEnabled()`. Those parameters become
+// effective no-ops in v7.0 — the values are observed (so a future PR
+// can re-enable the path or surface a deprecation event) but never
+// override the always-on result.
+/** Parse a stringly-typed env value into a tri-state boolean.
+ *  Retained for back-compat with any out-of-tree callers; the v7
+ *  resolver does not consult env values. */
+export function parseEngineEnvValue(raw) {
+    if (raw === undefined)
+        return undefined;
+    const normalized = raw.trim().toLowerCase();
+    if (normalized === '')
+        return undefined;
+    switch (normalized) {
+        case 'on':
+        case 'true':
+        case '1':
+        case 'yes':
+            return true;
+        case 'off':
+        case 'false':
+        case '0':
+        case 'no':
+            return false;
+        default:
+            return undefined;
+    }
+}
+/** v7.0+ — engine is always on. Pure function; ignores all inputs.
+ *  Source compatible with v6.x call sites. */
+export function resolveEngineEnabled(_opts = {}) {
+    return {
+        enabled: true,
+        source: 'default',
+        reason: 'v7.0+ — engine always on (engine-off path removed)',
+    };
+}
+// ---------------------------------------------------------------------------
+// v6.1 deprecation helpers — retained as no-op stubs for source compat.
+// v7.0 removed the engine-off path entirely; no warning ever fires.
+// ---------------------------------------------------------------------------
+/** v6.1-era stable deprecation banner. v7.0+ never emits this string —
+ *  the path is gone. Kept exported so out-of-tree consumers that imported
+ *  it still type-check. */
+export const ENGINE_OFF_DEPRECATION_MESSAGE = '[deprecation] --no-engine / engine.enabled: false were removed in v7.0. Migration: drop the flag/env/config.';
+/** v7.0+ no-op. Always returns false. */
+export function shouldWarnEngineOffDeprecation(_resolved) {
+    return false;
+}
+/** v7.0+ no-op. Always returns false. */
+export function emitEngineOffDeprecationWarning(_resolved, _warn = () => { }) {
+    return false;
+}
+//# sourceMappingURL=resolve-engine.js.map

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

@@ -0,0 +1,66 @@
+import type { ExternalRef } from './types.ts';
+import type { ReadbackResult } from './provider-readback.ts';
+/** What the orchestrator should do for this phase on resume. */
+export type ResumeDecision = 
+/** No prior success → run the phase normally (no preflight needed). */
+{
+    kind: 'proceed-fresh';
+}
+/** All postEffect refs `merged`/`live` → emit phase.success with
+ *  `replayed: true` and skip the phase body. */
+ | {
+    kind: 'skip-already-applied';
+    readback: ReadbackResult[];
+    reason: string;
+}
+/** PreEffect ref `open` + postEffect incomplete → re-run the phase body;
+ *  its own ledger handles partial-state dedup. */
+ | {
+    kind: 'retry';
+    readback: ReadbackResult[];
+    reason: string;
+}
+/** Ambiguous state → emit replay.override + throw needs_human. */
+ | {
+    kind: 'needs-human';
+    readback: ReadbackResult[];
+    reason: string;
+    refsConsulted: ExternalRef[];
+};
+export interface ResumePreflightInput {
+    /** The phase's contract — read out of `PHASE_REGISTRY[name]`. Empty
+     *  arrays are valid (e.g. `pr` declares post-effect = []). */
+    preEffectRefKinds: readonly string[];
+    postEffectRefKinds: readonly string[];
+    /** Did the prior orchestrator attempt record `phase.success` for this
+     *  phaseIdx? When false, we return `proceed-fresh` immediately. */
+    priorPhaseSuccess: boolean;
+    /** Refs persisted by the prior attempt — both pre-effect and post-effect
+     *  kinds, in event order. The preflight filters them by kind to map
+     *  to the contract. */
+    priorRefs: readonly ExternalRef[];
+    /** Test seam — replace `verifyRefs` so unit tests don't need the real
+     *  github / supabase readbacks. Production callers omit this. */
+    verifyRefsImpl?: (refs: readonly ExternalRef[]) => Promise<ReadbackResult[]>;
+}
+/**
+ * Make the resume decision for one side-effecting phase.
+ *
+ * The contract:
+ *   - When `priorPhaseSuccess === false` → `proceed-fresh` (no preflight).
+ *   - When `priorRefs` is empty AND we have a prior phase.success →
+ *     `needs-human` (the phase claimed success but didn't persist any
+ *     ref — corrupted state we shouldn't auto-retry).
+ *   - When all refs whose kind is in `postEffectRefKinds` read back as
+ *     `merged` / `live` AND postEffect is non-empty → `skip-already-applied`.
+ *   - When at least one preEffect ref reads back as `open` AND not all
+ *     post-effect refs merged → `retry`.
+ *   - Otherwise → `needs-human`.
+ *
+ * `pr`'s contract has `postEffectRefKinds: []`. For that case the
+ * pre-effect ref (`github-pr`) doubles as the reconciliation ref — we
+ * inspect IT against `merged`/`open` semantics. Any other state →
+ * needs-human.
+ */
+export declare function resumePreflight(input: ResumePreflightInput): Promise<ResumeDecision>;
+//# sourceMappingURL=resume-preflight.d.ts.map

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

@@ -0,0 +1,116 @@
+// src/core/run-state/resume-preflight.ts
+//
+// v6.2.1 — orchestrator resume preflight for side-effecting phases.
+//
+// Background — the v6.2.1 side-effect idempotency contract requires every
+// `hasSideEffects: true` phase to declare two ref kind sets:
+//
+//   - `preEffectRefKinds`  — recorded BEFORE the side effect runs.
+//   - `postEffectRefKinds` — recorded AFTER the side effect completes.
+//
+// On resume of a runId the orchestrator must consult the persisted refs +
+// the platform of record (via `verifyRefs`) before re-invoking the phase
+// body. This module owns that decision.
+//
+// The decision matrix (per spec "Resume preflight pseudocode"):
+//
+//   - All postEffect refs read back as `merged` / `live`
+//     ⇒ `skip-already-applied` — orchestrator emits `phase.success
+//       { replayed: true, reason: 'side-effect-already-applied' }` and
+//       advances. NO retry.
+//   - PreEffect ref read back as `open` AND postEffect refs incomplete
+//     ⇒ `retry` — orchestrator runs the phase body normally; the phase's
+//       own ledger / preflight handles dedup against the partial state.
+//   - Otherwise (no prior success, ambiguous, or readback unknown)
+//     ⇒ `needs-human` — orchestrator emits `replay.override` event and
+//       throws `GuardrailError('needs_human')`.
+//
+// Fresh runs (no prior phase.success for this phaseIdx) get `proceed-fresh`
+// — the orchestrator just runs the phase normally.
+import { verifyRefs as defaultVerifyRefs } from "./provider-readback.js";
+/**
+ * Make the resume decision for one side-effecting phase.
+ *
+ * The contract:
+ *   - When `priorPhaseSuccess === false` → `proceed-fresh` (no preflight).
+ *   - When `priorRefs` is empty AND we have a prior phase.success →
+ *     `needs-human` (the phase claimed success but didn't persist any
+ *     ref — corrupted state we shouldn't auto-retry).
+ *   - When all refs whose kind is in `postEffectRefKinds` read back as
+ *     `merged` / `live` AND postEffect is non-empty → `skip-already-applied`.
+ *   - When at least one preEffect ref reads back as `open` AND not all
+ *     post-effect refs merged → `retry`.
+ *   - Otherwise → `needs-human`.
+ *
+ * `pr`'s contract has `postEffectRefKinds: []`. For that case the
+ * pre-effect ref (`github-pr`) doubles as the reconciliation ref — we
+ * inspect IT against `merged`/`open` semantics. Any other state →
+ * needs-human.
+ */
+export async function resumePreflight(input) {
+    if (!input.priorPhaseSuccess && input.priorRefs.length === 0) {
+        return { kind: 'proceed-fresh' };
+    }
+    const verify = input.verifyRefsImpl ?? defaultVerifyRefs;
+    const readback = input.priorRefs.length > 0 ? await verify(input.priorRefs) : [];
+    // postEffect path — if the contract declares post-effect kinds, the
+    // pre-effect breadcrumb's readback state is authoritative for the
+    // batch's "did all the planned work land?" question. Post-effect refs
+    // alone aren't authoritative because the resume doesn't know the total
+    // planned set just from the persisted ref count (a partial crash
+    // persists 3 of 5 migration-version refs and 0 readback for the missing
+    // 2 — counting the persisted set against itself always says "complete").
+    // The batch readback is the source of truth: it queries the dispatcher's
+    // ledger for the planned set vs the applied set.
+    if (input.postEffectRefKinds.length > 0) {
+        const preRefs = readback.filter(r => input.preEffectRefKinds.includes(r.refKind));
+        const postRefs = readback.filter(r => input.postEffectRefKinds.includes(r.refKind));
+        // Skip-already-applied: pre-effect breadcrumb confirms `merged` AND
+        // every persisted post-effect ref is live/merged. The pre-effect's
+        // `merged` state comes from the batch readback comparing planned to
+        // applied — so we trust it as the cross-set check.
+        const preMerged = preRefs.length > 0 && preRefs.every(r => r.currentState === 'merged' || r.currentState === 'live');
+        const postAllLive = postRefs.every(r => r.currentState === 'merged' || r.currentState === 'live');
+        if (preMerged && postAllLive) {
+            return {
+                kind: 'skip-already-applied',
+                readback,
+                reason: `pre-effect ref reports merged + ${postRefs.length} post-effect ref(s) live`,
+            };
+        }
+        // Retry: pre-effect breadcrumb is `open` (some planned items still
+        // pending). The phase body's own ledger guard handles dedup of the
+        // already-applied items.
+        const preOpen = preRefs.some(r => r.currentState === 'open');
+        if (preOpen) {
+            return {
+                kind: 'retry',
+                readback,
+                reason: 'pre-effect breadcrumb open + post-effect refs incomplete',
+            };
+        }
+    }
+    else {
+        // Empty postEffectRefKinds — pre-effect ref doubles as reconciliation.
+        // Used by `pr`: the github-pr ref IS the post-effect ref.
+        const preRefs = readback.filter(r => input.preEffectRefKinds.includes(r.refKind));
+        if (preRefs.length > 0 && preRefs.every(r => r.currentState === 'merged' || r.currentState === 'live' || r.currentState === 'open')) {
+            // For pr: open/merged both mean "the PR exists, don't recreate it."
+            return {
+                kind: 'skip-already-applied',
+                readback,
+                reason: `pre-effect ref doubles as reconciliation; all ${preRefs.length} report live/merged/open`,
+            };
+        }
+    }
+    // Anything else — refs missing, closed without merge, unknown — punt.
+    return {
+        kind: 'needs-human',
+        readback,
+        refsConsulted: [...input.priorRefs],
+        reason: readback.length === 0
+            ? 'prior phase.success exists but no externalRefs persisted'
+            : 'readback could not confirm skip-already-applied or retry-safe',
+    };
+}
+//# sourceMappingURL=resume-preflight.js.map

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

@@ -0,0 +1,69 @@
+import { type RunPhase } from './phase-runner.ts';
+import type { GuardrailConfig } from '../config/types.ts';
+/** Caller-supplied inputs to drive a single-phase engine run.
+ *
+ *  The helper is intentionally narrow: every wrapped verb passes the same
+ *  shape today. Side-effecting verbs (`pr`, `migrate`, `implement`) will
+ *  use the same shape too — they emit externalRefs from inside `phase.run`
+ *  via `ctx.emitExternalRef()`, which the underlying `runPhase()` records.
+ *  No new helper field is needed for them in v6.0.7+. */
+export interface RunPhaseWithLifecycleOpts<I, O> {
+    /** Project working directory. Passed straight through to `createRun`
+     *  so `.guardrail-cache/runs/<ulid>/` lands in the right place. */
+    cwd: string;
+    /** The pre-built phase definition (name, idempotent, hasSideEffects, run).
+     *  Same `RunPhase<I, O>` the caller would pass to `runPhase()` directly. */
+    phase: RunPhase<I, O>;
+    /** Phase input — same shape the caller would pass to `runPhase()`. */
+    input: I;
+    /** Loaded `guardrail.config.yaml` (or the default `{ configVersion: 1 }`).
+     *  Used only for the `engine.enabled` precedence layer. The helper does
+     *  NOT re-load config — that's the caller's responsibility (and lets
+     *  callers pass synthetic configs in tests). */
+    config: GuardrailConfig;
+    /** CLI flag override — `true` from `--engine`, `false` from `--no-engine`,
+     *  `undefined` if neither was passed. */
+    cliEngine: boolean | undefined;
+    /** Raw value of `process.env.CLAUDE_AUTOPILOT_ENGINE`. `undefined` if
+     *  unset. The helper passes this through to `resolveEngineEnabled` —
+     *  invalid values fall through with a `run.warning` recorded automatically. */
+    envEngine: string | undefined;
+    /** v6.x escape hatch — invoked when the engine was disabled. Retained
+     *  in the v7.0 type for source compatibility with existing callers,
+     *  but the helper NEVER calls it in v7.0+ (engine-off path was
+     *  removed). Optional in v7.0; can be omitted from new call sites. */
+    runEngineOff?: () => Promise<O>;
+}
+/** What the helper hands back. `runId` and `runDir` are null on the
+ *  engine-off path so callers can branch on whether engine artifacts exist
+ *  (e.g. for a future `--json` envelope that surfaces the runId). */
+export interface RunPhaseWithLifecycleResult<O> {
+    output: O;
+    /** ULID of the created run, or null when engine-off. */
+    runId: string | null;
+    /** Absolute path to the run dir, or null when engine-off. */
+    runDir: string | null;
+}
+/** 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 declare function runPhaseWithLifecycle<I, O>(opts: RunPhaseWithLifecycleOpts<I, O>): Promise<RunPhaseWithLifecycleResult<O>>;
+//# sourceMappingURL=run-phase-with-lifecycle.d.ts.map

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

@@ -0,0 +1,193 @@
+// 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, } 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 } = opts;
+    // v7.0 — engine is always on. resolveEngineEnabled() returns
+    // { enabled: true, source: 'default' } unconditionally. We still
+    // pass the v6-era inputs through so any future re-introduction of
+    // observability (a run.warning when a user passes the removed flags
+    // via env vars in CI) is a one-line change.
+    const engineResolved = resolveEngineEnabled({
+        ...(cliEngine !== undefined ? { cliEngine } : {}),
+        ...(envEngine !== undefined ? { envValue: envEngine } : {}),
+        ...(typeof config.engine?.enabled === 'boolean'
+            ? { configEnabled: config.engine.enabled }
+            : {}),
+    });
+    // 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 });
+    }
+    // v7.0 — emit `engine_off_removed` warning when CLAUDE_AUTOPILOT_ENGINE
+    // is set to an off-style value. The env value is otherwise ignored
+    // (engine remains on). Softer than --no-engine (which exits 1) because
+    // env vars in CI are sticky and silently breaking every v6.x → v7
+    // upgrade in CI on day one would burn user trust. See spec test #1(c).
+    if (envEngine !== undefined) {
+        const normalized = envEngine.trim().toLowerCase();
+        if (normalized === 'off' || normalized === 'false' || normalized === '0' || normalized === 'no') {
+            appendEvent(created.runDir, {
+                event: 'run.warning',
+                message: 'engine_off_removed',
+                details: {
+                    code: 'engine_off_removed',
+                    envValue: envEngine,
+                    note: 'CLAUDE_AUTOPILOT_ENGINE=off has no effect in v7.0+; engine remains on.',
+                },
+            }, { 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