@delegance/claude-autopilot 5.5.2 → 6.2.2

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

@@ -0,0 +1,100 @@
+/** What the resolver decided plus the rationale. The `source` field tells
+ *  callers which precedence layer won so they can surface it in diagnostics
+ *  (`runs show`, `--json` envelopes, etc.). */
+export interface ResolveEngineResult {
+    /** Final decision — whether the engine runs for this invocation. */
+    enabled: boolean;
+    /** Which precedence layer produced the decision. */
+    source: 'cli' | 'env' | 'config' | 'default';
+    /** Human-readable explanation, suitable for run.warning details / verbose
+     *  CLI output / debug logs. */
+    reason: string;
+    /** When `source === 'env'` and the env value was malformed, this carries the
+     *  raw string so the caller can route a `run.warning` describing the
+     *  fallthrough. Absent on the happy path. */
+    invalidEnvValue?: string;
+}
+export interface ResolveEngineOptions {
+    /** True if `--engine` was passed; false if `--no-engine`; undefined if
+     *  neither flag was present. The CLI parser is responsible for rejecting
+     *  the case where BOTH flags are passed before this function is called. */
+    cliEngine?: boolean;
+    /** Raw value of `process.env.CLAUDE_AUTOPILOT_ENGINE`. Undefined if the
+     *  variable is unset. Empty string is treated as unset (matches Node's
+     *  convention). Case-insensitive parsing of the string value. */
+    envValue?: string;
+    /** Value of `engine.enabled` from guardrail.config.yaml, or undefined if
+     *  the config file is missing / does not declare the key. */
+    configEnabled?: boolean;
+    /** Built-in default. v6.0: false. Tests pin this explicitly to exercise
+     *  the v6.1-flip behavior without needing to bump the constant globally. */
+    builtInDefault?: boolean;
+}
+/** v6.1+ ships with the engine ON by default — flipped from the v6.0
+ *  default (`false`) per `docs/specs/v6.1-default-flip.md`. Exported so
+ *  tests / future releases can pin a known value. */
+export declare const ENGINE_DEFAULT_V6_1: true;
+/** Historical v6.0 default. Preserved verbatim — its semantic meaning
+ *  ("the v6.0 default was off") doesn't change just because the active
+ *  default flipped. Out-of-tree consumers that pinned this constant get
+ *  the value the name promises. Use `ENGINE_DEFAULT_V6_1` for the active
+ *  default. Removed in v7.
+ *  @deprecated Use `ENGINE_DEFAULT_V6_1` or omit `builtInDefault` to inherit
+ *  the active default. */
+export declare const ENGINE_DEFAULT_V6_0: false;
+/** Parse a stringly-typed env value into a tri-state boolean.
+ *  Accepts (case-insensitive): on, off, true, false, 1, 0, yes, no.
+ *  Returns undefined for any other input INCLUDING empty / whitespace-only
+ *  strings — that signals the caller to fall through to the next precedence
+ *  layer. */
+export declare function parseEngineEnvValue(raw: string | undefined): boolean | undefined;
+/** Resolve whether the Run State Engine should run for this invocation.
+ *  Pure function — does not touch process.env, fs, or anything I/O. */
+export declare function resolveEngineEnabled(opts?: ResolveEngineOptions): ResolveEngineResult;
+/** Stable copy emitted on stderr when a user explicitly opts out of the
+ *  engine via `--no-engine`, `CLAUDE_AUTOPILOT_ENGINE=off`, or
+ *  `engine.enabled: false`. v7 removes the escape hatch entirely.
+ *
+ *  Exported for tests + downstream consumers (e.g. CI parsers) that want to
+ *  match against the exact string. Kept on a single line so terminals don't
+ *  wrap mid-message. */
+export declare const ENGINE_OFF_DEPRECATION_MESSAGE = "[deprecation] --no-engine / engine.enabled: false will be removed in v7. Migrate to engine-on (default).";
+/** Optional callback shape for the deprecation warner. Tests pass a capture
+ *  function; production callers omit it and get the default `process.stderr`
+ *  writer. Kept narrow (single-arg) so a `jest.fn` or a `(msg) => lines.push(msg)`
+ *  array sink is trivially droppable. */
+export type EngineDeprecationWarn = (message: string) => void;
+/** Decide whether v6.1's `--no-engine` deprecation warning applies for a
+ *  given resolver result. Returns `true` ONLY when the user explicitly
+ *  opted out (via CLI flag, env var, or config) — never on the v6.1 default
+ *  (which is `enabled: true`, so it can't trigger here anyway) and never
+ *  when the engine is actually on. Pure: takes the resolver result, returns
+ *  a boolean.
+ *
+ *  Why this is a separate predicate (not collapsed into the warner): the
+ *  CLI dispatcher wants to ALSO emit a typed `run.warning` event into a
+ *  ledger when the engine ends up on but the resolver came from a layer
+ *  that's about to be removed — except today, on v6.1, the only path that
+ *  warns IS the "engine off, explicit opt-out" path. So the predicate
+ *  collapses cleanly to that single condition. v7 removes both. */
+export declare function shouldWarnEngineOffDeprecation(resolved: Pick<ResolveEngineResult, 'enabled' | 'source'>): boolean;
+/** Emit the v6.1 `--no-engine` deprecation warning to stderr (or the
+ *  supplied `warn` callback) when the resolver result indicates the user
+ *  explicitly opted out of the engine. No-op when:
+ *    - the engine is on (no opt-out happened);
+ *    - the source is `'default'` (v6.1's flipped default = on, so a default
+ *      result with `enabled: false` is impossible without a custom
+ *      `builtInDefault` override — and even that path doesn't warn since
+ *      it's not a user-driven opt-out).
+ *
+ *  Pure-ish: side-effect is captured behind the optional `warn` callback so
+ *  tests can assert on the message without spawning a subprocess. The
+ *  default warner writes to `process.stderr` with a trailing newline.
+ *
+ *  Returns `true` when the warning fired, `false` when it was a no-op. The
+ *  return value is purely informational — callers can use it to decide
+ *  whether to also append a `run.warning` event into a run ledger (only
+ *  meaningful on the engine-on path; the v6.1 deprecation only fires on
+ *  engine-off, where there's no run dir to write into). */
+export declare function emitEngineOffDeprecationWarning(resolved: Pick<ResolveEngineResult, 'enabled' | 'source'>, warn?: EngineDeprecationWarn): boolean;
+//# sourceMappingURL=resolve-engine.d.ts.map

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

@@ -0,0 +1,190 @@
+// src/core/run-state/resolve-engine.ts
+//
+// v6.0.1 — pure precedence resolver for whether the Run State Engine should
+// run for a given CLI invocation. Spec: docs/specs/v6-run-state-engine.md
+// "Migration path (v5.6 → v6) + precedence matrix" + docs/v6/migration-guide.md
+// "How to opt in".
+//
+// v6.1 update — built-in default flipped from `false` → `true` per
+// docs/specs/v6.1-default-flip.md. Users who opt out explicitly via
+// `--no-engine`, `CLAUDE_AUTOPILOT_ENGINE=off|false|0|no`, or
+// `engine.enabled: false` in `guardrail.config.yaml` keep the legacy
+// (engine-off) behavior, but they now receive a deprecation warning —
+// the escape hatch goes away in v7. See `emitEngineOffDeprecationWarning`
+// below.
+//
+// Precedence (highest wins):
+//   1. CLI flag         — `--engine` / `--no-engine`
+//   2. Env var          — `CLAUDE_AUTOPILOT_ENGINE=on|off|true|false|1|0|yes|no`
+//   3. Config           — `engine.enabled: true|false` in guardrail.config.yaml
+//   4. Built-in default — v6.1+: true (was false in v6.0)
+//
+// This module is intentionally pure and side-effect-free: it never reads from
+// the environment or the config file directly. Callers (the CLI dispatcher)
+// gather the inputs and pass them in — that keeps the function trivially
+// testable and lets the dispatcher own all I/O.
+//
+// Invalid env values do NOT throw. The contract from the spec / migration
+// guide is "treat as unset and emit a run.warning so observers can attribute
+// the fallthrough." This module returns metadata — the resolver caller
+// (cli/index.ts) is responsible for emitting the warning event.
+/** v6.1+ ships with the engine ON by default — flipped from the v6.0
+ *  default (`false`) per `docs/specs/v6.1-default-flip.md`. Exported so
+ *  tests / future releases can pin a known value. */
+export const ENGINE_DEFAULT_V6_1 = true;
+/** Historical v6.0 default. Preserved verbatim — its semantic meaning
+ *  ("the v6.0 default was off") doesn't change just because the active
+ *  default flipped. Out-of-tree consumers that pinned this constant get
+ *  the value the name promises. Use `ENGINE_DEFAULT_V6_1` for the active
+ *  default. Removed in v7.
+ *  @deprecated Use `ENGINE_DEFAULT_V6_1` or omit `builtInDefault` to inherit
+ *  the active default. */
+export const ENGINE_DEFAULT_V6_0 = false;
+/** Parse a stringly-typed env value into a tri-state boolean.
+ *  Accepts (case-insensitive): on, off, true, false, 1, 0, yes, no.
+ *  Returns undefined for any other input INCLUDING empty / whitespace-only
+ *  strings — that signals the caller to fall through to the next precedence
+ *  layer. */
+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;
+    }
+}
+/** Resolve whether the Run State Engine should run for this invocation.
+ *  Pure function — does not touch process.env, fs, or anything I/O. */
+export function resolveEngineEnabled(opts = {}) {
+    const { cliEngine, envValue, configEnabled, builtInDefault } = opts;
+    const builtIn = builtInDefault ?? ENGINE_DEFAULT_V6_1;
+    // Layer 1 — CLI flag wins outright.
+    if (cliEngine === true) {
+        return { enabled: true, source: 'cli', reason: '--engine flag' };
+    }
+    if (cliEngine === false) {
+        return { enabled: false, source: 'cli', reason: '--no-engine flag' };
+    }
+    // Layer 2 — env var.
+    if (envValue !== undefined && envValue.trim() !== '') {
+        const parsed = parseEngineEnvValue(envValue);
+        if (parsed !== undefined) {
+            return {
+                enabled: parsed,
+                source: 'env',
+                reason: `CLAUDE_AUTOPILOT_ENGINE=${envValue}`,
+            };
+        }
+        // Invalid value — fall through, but record the raw value so the caller
+        // can emit a run.warning. Continue to config / default below.
+        // We bind it here so it survives the recursion-style fallthrough.
+        return resolveWithFallthrough({
+            configEnabled,
+            builtIn,
+            invalidEnvValue: envValue,
+        });
+    }
+    return resolveWithFallthrough({ configEnabled, builtIn });
+}
+/** Layers 3 + 4 — config, then built-in default. Factored out so the env
+ *  invalid-value path can reach the same logic without recursing into
+ *  resolveEngineEnabled (which would re-evaluate the env var and loop). */
+function resolveWithFallthrough(opts) {
+    const { configEnabled, builtIn, invalidEnvValue } = opts;
+    const invalidSuffix = invalidEnvValue !== undefined
+        ? `; invalid CLAUDE_AUTOPILOT_ENGINE=${JSON.stringify(invalidEnvValue)} ignored`
+        : '';
+    if (configEnabled === true) {
+        return {
+            enabled: true,
+            source: 'config',
+            reason: `engine.enabled: true in guardrail.config.yaml${invalidSuffix}`,
+            ...(invalidEnvValue !== undefined ? { invalidEnvValue } : {}),
+        };
+    }
+    if (configEnabled === false) {
+        return {
+            enabled: false,
+            source: 'config',
+            reason: `engine.enabled: false in guardrail.config.yaml${invalidSuffix}`,
+            ...(invalidEnvValue !== undefined ? { invalidEnvValue } : {}),
+        };
+    }
+    return {
+        enabled: builtIn,
+        source: 'default',
+        reason: `built-in default (engine ${builtIn ? 'on' : 'off'} in v6.1+)${invalidSuffix}`,
+        ...(invalidEnvValue !== undefined ? { invalidEnvValue } : {}),
+    };
+}
+// ---------------------------------------------------------------------------
+// v6.1 deprecation warning for explicit engine-off
+// ---------------------------------------------------------------------------
+/** Stable copy emitted on stderr when a user explicitly opts out of the
+ *  engine via `--no-engine`, `CLAUDE_AUTOPILOT_ENGINE=off`, or
+ *  `engine.enabled: false`. v7 removes the escape hatch entirely.
+ *
+ *  Exported for tests + downstream consumers (e.g. CI parsers) that want to
+ *  match against the exact string. Kept on a single line so terminals don't
+ *  wrap mid-message. */
+export const ENGINE_OFF_DEPRECATION_MESSAGE = '[deprecation] --no-engine / engine.enabled: false will be removed in v7. Migrate to engine-on (default).';
+/** Decide whether v6.1's `--no-engine` deprecation warning applies for a
+ *  given resolver result. Returns `true` ONLY when the user explicitly
+ *  opted out (via CLI flag, env var, or config) — never on the v6.1 default
+ *  (which is `enabled: true`, so it can't trigger here anyway) and never
+ *  when the engine is actually on. Pure: takes the resolver result, returns
+ *  a boolean.
+ *
+ *  Why this is a separate predicate (not collapsed into the warner): the
+ *  CLI dispatcher wants to ALSO emit a typed `run.warning` event into a
+ *  ledger when the engine ends up on but the resolver came from a layer
+ *  that's about to be removed — except today, on v6.1, the only path that
+ *  warns IS the "engine off, explicit opt-out" path. So the predicate
+ *  collapses cleanly to that single condition. v7 removes both. */
+export function shouldWarnEngineOffDeprecation(resolved) {
+    if (resolved.enabled)
+        return false;
+    return (resolved.source === 'cli' ||
+        resolved.source === 'env' ||
+        resolved.source === 'config');
+}
+/** Emit the v6.1 `--no-engine` deprecation warning to stderr (or the
+ *  supplied `warn` callback) when the resolver result indicates the user
+ *  explicitly opted out of the engine. No-op when:
+ *    - the engine is on (no opt-out happened);
+ *    - the source is `'default'` (v6.1's flipped default = on, so a default
+ *      result with `enabled: false` is impossible without a custom
+ *      `builtInDefault` override — and even that path doesn't warn since
+ *      it's not a user-driven opt-out).
+ *
+ *  Pure-ish: side-effect is captured behind the optional `warn` callback so
+ *  tests can assert on the message without spawning a subprocess. The
+ *  default warner writes to `process.stderr` with a trailing newline.
+ *
+ *  Returns `true` when the warning fired, `false` when it was a no-op. The
+ *  return value is purely informational — callers can use it to decide
+ *  whether to also append a `run.warning` event into a run ledger (only
+ *  meaningful on the engine-on path; the v6.1 deprecation only fires on
+ *  engine-off, where there's no run dir to write into). */
+export function emitEngineOffDeprecationWarning(resolved, warn = (msg) => {
+    process.stderr.write(`${msg}\n`);
+}) {
+    if (!shouldWarnEngineOffDeprecation(resolved))
+        return false;
+    warn(ENGINE_OFF_DEPRECATION_MESSAGE);
+    return true;
+}
+//# 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,73 @@
+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;
+    /** Engine-off escape hatch — what to return when `resolveEngineEnabled`
+     *  decides the engine should NOT run. Most callers pass an async function
+     *  that runs the legacy code path (typically the same `phase.run` body
+     *  invoked without the lifecycle wrapper). The helper does not invoke
+     *  `phase.run` for engine-off so the caller has full control over the
+     *  legacy path's behavior — keeps engine-off byte-for-byte identical to
+     *  pre-v6 behavior even when the phase body's signature would otherwise
+     *  pin the call shape. */
+    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