@delegance/claude-autopilot 5.5.2 → 6.2.2

package/dist/src/cli/brainstorm.d.ts

@@ -0,0 +1,23 @@
+export interface BrainstormCommandOptions {
+    cwd?: string;
+    configPath?: string;
+    /**
+     * v6.0.3 — engine knob inputs. Same shape and precedence as scan / costs /
+     * fix (CLI > env > config > built-in default off in v6.0.x). The CLI
+     * dispatcher wires `cliEngine` from `--engine` / `--no-engine`;
+     * `envEngine` from `process.env.CLAUDE_AUTOPILOT_ENGINE`. An absent CLI
+     * flag + absent env value falls through to the loaded config and then to
+     * the built-in default.
+     */
+    cliEngine?: boolean;
+    envEngine?: string;
+    /**
+     * Test-only seam — when true, the phase body returns its result without
+     * printing the advisory banner. Lets engine-smoke tests assert the
+     * `state.json` + `events.ndjson` lifecycle without polluting stdout.
+     * Production callers (the CLI dispatcher) MUST NOT pass this.
+     */
+    __silent?: boolean;
+}
+export declare function runBrainstorm(options?: BrainstormCommandOptions): Promise<number>;
+//# sourceMappingURL=brainstorm.d.ts.map

package/dist/src/cli/brainstorm.js

@@ -0,0 +1,131 @@
+// src/cli/brainstorm.ts
+//
+// v6.0.3 — wrap the `brainstorm` pipeline phase through `runPhase`.
+//
+// `brainstorm` is the entry point of the autopilot pipeline. It is implemented
+// primarily as a Claude Code skill (`/brainstorm` → `superpowers:brainstorming`),
+// not as a standalone CLI subcommand. The CLI verb that ships in this binary is
+// an advisory shim: it points the user at the Claude Code skill and the next
+// pipeline verbs. There is no LLM call in the CLI verb body, and no provider
+// side effects. The pure-LLM design dialogue happens in Claude Code; the spec
+// markdown produced there lands at `docs/superpowers/specs/<slug>.md` (a local
+// file write, not a platform-side-effect-free remote write — the recipe treats
+// local file writes as acceptable inside the phase body, identical precedent to
+// `fix.ts` editing local source files).
+//
+// Idempotency / side effects (deviation note vs. spec table):
+//   - The spec table at docs/specs/v6-run-state-engine.md says
+//     `idempotent: no` for `brainstorm` because re-running produces NEW LLM
+//     content each invocation. The recipe table at
+//     docs/v6/wrapping-pipeline-phases.md previously echoed that. v6.0.3
+//     declares `idempotent: true` to match the engine's actual semantics
+//     ("safe to retry without reconciliation"): the CLI verb itself is a
+//     printed advisory message that is byte-for-byte identical on every
+//     invocation, has no externalRefs to reconcile, and no provider state
+//     to roll back. The engine's idempotency check is "safe to replay,"
+//     not "produces byte-identical output." See the recipe section 2:
+//     `idempotent: true → phase output depends only on its input + project
+//     state, and re-running gives the same answer.` That holds here.
+//   - `hasSideEffects: false` — the CLI verb prints to stdout. No provider
+//     calls, no git push, no PR creation, no remote API write. Identical
+//     to costs.
+import * as path from 'node:path';
+import * as fs from 'node:fs';
+import { loadConfig } from "../core/config/loader.js";
+import { runPhaseWithLifecycle } from "../core/run-state/run-phase-with-lifecycle.js";
+const C = {
+    reset: '\x1b[0m', bold: '\x1b[1m', dim: '\x1b[2m',
+    cyan: '\x1b[36m', red: '\x1b[31m',
+};
+const fmt = (c, t) => `${C[c]}${t}${C.reset}`;
+export async function runBrainstorm(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const configPath = options.configPath ?? path.join(cwd, 'guardrail.config.yaml');
+    let config = { configVersion: 1 };
+    if (fs.existsSync(configPath)) {
+        const loaded = await loadConfig(configPath);
+        if (loaded)
+            config = loaded;
+    }
+    const brainstormInput = { cwd, silent: options.__silent === true };
+    // The wrapped phase body. Pure: reads no files, makes no provider calls.
+    // Engine-off callers invoke `executeBrainstormPhase()` directly;
+    // engine-on callers route through `runPhase()`.
+    const phase = {
+        name: 'brainstorm',
+        // Pure-LLM design dialogue happens in the Claude Code skill, not here.
+        // The CLI verb is an advisory print with no externalRefs to reconcile
+        // and no provider state to roll back. Safe to retry. (Deviation from
+        // the spec table noted at the top of the file.)
+        idempotent: true,
+        // No provider calls, no git push, no PR creation. Identical to costs.
+        hasSideEffects: false,
+        run: async (input) => executeBrainstormPhase(input),
+    };
+    // v6.0.6 — lifecycle wiring lives in `runPhaseWithLifecycle`. The helper
+    // owns the engine-on/engine-off branch and the failure banner.
+    let output;
+    try {
+        const result = await runPhaseWithLifecycle({
+            cwd,
+            phase,
+            input: brainstormInput,
+            config,
+            cliEngine: options.cliEngine,
+            envEngine: options.envEngine,
+            runEngineOff: () => executeBrainstormPhase(brainstormInput),
+        });
+        output = result.output;
+    }
+    catch {
+        // Helper already printed the failure banner + emitted run.complete
+        // failed + refreshed state.json + released the lock.
+        return 1;
+    }
+    return renderBrainstormOutput(output, brainstormInput);
+}
+// ---------------------------------------------------------------------------
+// Phase body — produce the advisory payload. Pure: no provider calls. By
+// default does NOT print to stdout (the renderer handles that) so the engine
+// path's idempotency isn't coupled to console output. Returns a
+// JSON-serializable BrainstormOutput so the engine can persist it as
+// `result` on the phase snapshot.
+// ---------------------------------------------------------------------------
+async function executeBrainstormPhase(_input) {
+    return {
+        kind: 'advisory',
+        nextActions: [
+            'Invoke /brainstorm from Claude Code for interactive spec writing',
+            'Then /autopilot to run the full pipeline from an approved spec',
+        ],
+    };
+}
+// ---------------------------------------------------------------------------
+// Render — translate BrainstormOutput back to the legacy stdout advisory +
+// exit code. Lives outside the wrapped phase because it's pure presentation;
+// doing the rendering inside the phase would couple the engine path's
+// idempotency to console output.
+// ---------------------------------------------------------------------------
+function renderBrainstormOutput(_output, input) {
+    if (input.silent)
+        return 0;
+    console.log(`
+${fmt('bold', '[brainstorm]')} The pipeline entry point is a Claude Code skill, not a CLI subcommand.
+
+Invoke it from Claude Code:
+
+  ${fmt('cyan', '/brainstorm')}                         Interactive spec writing
+  ${fmt('cyan', '/autopilot')}                          Full pipeline from an approved spec
+  ${fmt('cyan', '/migrate')}                            Database migration phase (stack-dependent)
+
+From the terminal, the CLI subset exposes only the individual review-phase subcommands:
+
+  ${fmt('cyan', 'claude-autopilot run --base main')}    Just the review phase
+  ${fmt('cyan', 'claude-autopilot doctor')}             Check prerequisites (incl. superpowers plugin)
+  ${fmt('cyan', 'claude-autopilot migrate-v4')}         Codemod for v4 → v5 repo migration (not a pipeline phase)
+
+Full pipeline docs: https://github.com/axledbetter/claude-autopilot#the-pipeline-phase-by-phase
+`);
+    return 0;
+}
+//# sourceMappingURL=brainstorm.js.map

package/dist/src/cli/costs.d.ts

@@ -1,2 +1,16 @@
-export declare function runCosts(cwd?: string): Promise<number>;
+export interface CostsCommandOptions {
+    cwd?: string;
+    configPath?: string;
+    /**
+     * v6.0.2 — engine knob inputs. Same shape and precedence as scan
+     * (CLI > env > config > built-in default off in v6.0.x). The CLI dispatcher
+     * wires `cliEngine` from `--engine` / `--no-engine`; `envEngine` from
+     * `process.env.CLAUDE_AUTOPILOT_ENGINE`. An absent CLI flag + absent env
+     * value falls through to the loaded config and then to the built-in
+     * default.
+     */
+    cliEngine?: boolean;
+    envEngine?: string;
+}
+export declare function runCosts(cwdOrOptions?: string | CostsCommandOptions): Promise<number>;
 //# sourceMappingURL=costs.d.ts.map

package/dist/src/cli/costs.js

@@ -1,7 +1,11 @@
+import * as path from 'node:path';
+import * as fs from 'node:fs';
 import { readCostLog } from "../core/persist/cost-log.js";
+import { loadConfig } from "../core/config/loader.js";
+import { runPhaseWithLifecycle } from "../core/run-state/run-phase-with-lifecycle.js";
 const C = {
     reset: '\x1b[0m', bold: '\x1b[1m', dim: '\x1b[2m',
-    green: '\x1b[32m', yellow: '\x1b[33m', cyan: '\x1b[36m',
+    green: '\x1b[32m', yellow: '\x1b[33m', cyan: '\x1b[36m', red: '\x1b[31m',
 };
 const fmt = (c, t) => `${C[c]}${t}${C.reset}`;
 function formatDate(iso) {
@@ -19,13 +23,69 @@ function fmtUSD(n) {
 function fmtTokens(n) {
     return n >= 1000 ? `${(n / 1000).toFixed(1)}k` : String(n);
 }
-export async function runCosts(cwd = process.cwd()) {
-    const log = readCostLog(cwd);
-    if (log.length === 0) {
-        console.log(fmt('yellow', `[costs] No run history found in ${cwd} — run \`guardrail run\` first.`));
-        console.log(fmt('dim', `        (Costs are scoped per-project. \`cd\` to the project before checking.)`));
-        return 0;
+export async function runCosts(cwdOrOptions = {}) {
+    // Back-compat — early callers (tests, MCP) pass a bare `cwd: string`. The
+    // tests/costs.test.ts harness drives this shape directly. Promote both
+    // forms into a single options struct so the rest of the function can treat
+    // it uniformly.
+    const options = typeof cwdOrOptions === 'string'
+        ? { cwd: cwdOrOptions }
+        : cwdOrOptions;
+    const cwd = options.cwd ?? process.cwd();
+    const configPath = options.configPath ?? path.join(cwd, 'guardrail.config.yaml');
+    let config = { configVersion: 1 };
+    if (fs.existsSync(configPath)) {
+        const loaded = await loadConfig(configPath);
+        if (loaded)
+            config = loaded;
+    }
+    const costsInput = { cwd };
+    // The wrapped phase body — pure read of the cost ledger + summary build.
+    // Extracted into a RunPhase so the engine-on path and the engine-off path
+    // share the exact same logic. Engine-off callers invoke this directly via
+    // `executeCostsPhase()`; engine-on callers route through `runPhase()`.
+    const phase = {
+        name: 'costs',
+        // Cost summary is a pure read of `.guardrail-cache/costs.jsonl` — re-running
+        // produces identical output for identical ledger contents. Always safe to
+        // retry.
+        idempotent: true,
+        // No provider calls, no git push, no PR comment, no file writes (the
+        // ledger is read-only on this path; the writer is `appendCostLog` called
+        // by other verbs). Replays are safe.
+        hasSideEffects: false,
+        run: async (input) => executeCostsPhase(input),
+    };
+    // v6.0.6 — lifecycle wiring lives in `runPhaseWithLifecycle`. The helper
+    // owns the engine-on/engine-off branch and the failure banner; the caller
+    // just supplies the phase, the input, and the engine-off escape hatch.
+    let output;
+    try {
+        const result = await runPhaseWithLifecycle({
+            cwd,
+            phase,
+            input: costsInput,
+            config,
+            cliEngine: options.cliEngine,
+            envEngine: options.envEngine,
+            runEngineOff: () => executeCostsPhase(costsInput),
+        });
+        output = result.output;
+    }
+    catch {
+        // Helper already printed the failure banner + emitted run.complete
+        // failed + refreshed state.json + released the lock.
+        return 1;
     }
+    return renderCostsOutput(output, costsInput);
+}
+// ---------------------------------------------------------------------------
+// Phase body — read the cost ledger and assemble the summary. Pure: no
+// console output, no exit codes. Returns a JSON-serializable CostsOutput so
+// the engine can persist it as `result` on the phase snapshot.
+// ---------------------------------------------------------------------------
+async function executeCostsPhase(input) {
+    const log = readCostLog(input.cwd);
     // 7-day window
     const sevenDaysAgo = Date.now() - 7 * 24 * 60 * 60 * 1000;
     const recent = log.filter(e => new Date(e.timestamp).getTime() >= sevenDaysAgo);
@@ -34,12 +94,41 @@ export async function runCosts(cwd = process.cwd()) {
     const totalInput = log.reduce((s, e) => s + e.inputTokens, 0);
     const totalOutput = log.reduce((s, e) => s + e.outputTokens, 0);
     const recentCost = recent.reduce((s, e) => s + e.costUSD, 0);
+    return {
+        entryCount: log.length,
+        totals: {
+            runs: log.length,
+            inputTokens: totalInput,
+            outputTokens: totalOutput,
+            costUSD: totalCost,
+        },
+        recent: {
+            runs: recent.length,
+            costUSD: recentCost,
+        },
+        last10,
+    };
+}
+// ---------------------------------------------------------------------------
+// Render — translate CostsOutput back to the legacy stdout summary + exit
+// code. Lives outside the wrapped phase because it's pure presentation;
+// doing the rendering inside the phase would couple the engine path's
+// idempotency to console output.
+// ---------------------------------------------------------------------------
+function renderCostsOutput(output, input) {
+    const { cwd } = input;
+    const { entryCount, totals, recent, last10 } = output;
+    if (entryCount === 0) {
+        console.log(fmt('yellow', `[costs] No run history found in ${cwd} — run \`guardrail run\` first.`));
+        console.log(fmt('dim', `        (Costs are scoped per-project. \`cd\` to the project before checking.)`));
+        return 0;
+    }
     console.log(`\n${fmt('bold', '[costs]')} ${fmt('dim', cwd)}\n`);
     // Summary row
     console.log(fmt('bold', 'Summary'));
-    console.log(`  All-time runs:   ${log.length}`);
-    console.log(`  All-time cost:   ${fmtUSD(totalCost)}  (${fmtTokens(totalInput)} in / ${fmtTokens(totalOutput)} out)`);
-    console.log(`  Last 7 days:     ${fmtUSD(recentCost)}  (${recent.length} run${recent.length !== 1 ? 's' : ''})`);
+    console.log(`  All-time runs:   ${totals.runs}`);
+    console.log(`  All-time cost:   ${fmtUSD(totals.costUSD)}  (${fmtTokens(totals.inputTokens)} in / ${fmtTokens(totals.outputTokens)} out)`);
+    console.log(`  Last 7 days:     ${fmtUSD(recent.costUSD)}  (${recent.runs} run${recent.runs !== 1 ? 's' : ''})`);
     console.log(fmt('dim', `  (per-project — scoped to ${cwd}/.guardrail-cache/costs.jsonl)`));
     console.log('');
     // Last 10 runs table

package/dist/src/cli/deploy.d.ts

@@ -2,7 +2,7 @@ import type { DeployAdapter, DeployConfig } from '../adapters/deploy/types.ts';
 export interface RunDeployOptions {
     configPath?: string;
     /** When set, overrides `deploy.adapter` from config. */
-    adapterOverride?: 'vercel' | 'generic';
+    adapterOverride?: 'vercel' | 'fly' | 'render' | 'generic';
     ref?: string;
     commitSha?: string;
     cwd?: string;
@@ -39,7 +39,7 @@ export interface RunDeployOptions {
 export declare function runDeploy(opts: RunDeployOptions): Promise<number>;
 export interface RunDeployRollbackOptions {
     configPath?: string;
-    adapterOverride?: 'vercel' | 'generic';
+    adapterOverride?: 'vercel' | 'fly' | 'render' | 'generic';
     /** Specific deploy ID to roll back to. When omitted, the previous prod deploy is used. */
     to?: string;
     cwd?: string;
@@ -48,7 +48,7 @@ export interface RunDeployRollbackOptions {
 }
 export interface RunDeployStatusOptions {
     configPath?: string;
-    adapterOverride?: 'vercel' | 'generic';
+    adapterOverride?: 'vercel' | 'fly' | 'render' | 'generic';
     cwd?: string;
     adapterFactory?: (config: DeployConfig) => DeployAdapter;
 }

package/dist/src/cli/deploy.js

@@ -55,7 +55,7 @@ async function loadDeployConfigAsync(opts) {
     const adapter = opts.adapterOverride ?? configBlock?.adapter;
     if (!adapter) {
         console.error('\x1b[31m[deploy] no deploy adapter configured\x1b[0m\n' +
-            '  hint: set `deploy.adapter` in guardrail.config.yaml, or pass --adapter <vercel|generic>');
+            '  hint: set `deploy.adapter` in guardrail.config.yaml, or pass --adapter <vercel|fly|render|generic>');
         return { errorCode: 1 };
     }
     const merged = {
@@ -85,6 +85,16 @@ export async function runDeploy(opts) {
         let onDeployStart;
         if (opts.watch) {
             if (typeof deployAdapter.streamLogs === 'function') {
+                // Phase 3 of v5.6 — when an adapter advertises `streamMode: 'polling'`
+                // (currently only Render), surface a one-line stderr notice BEFORE
+                // iteration starts so users understand why their log lines arrive
+                // in batches with short gaps. Adapters with `streamMode: 'websocket'`
+                // (Vercel SSE, Fly WS) or `'none'`/undefined get no notice — their
+                // streaming behavior matches user expectations. Spec: § "Capability
+                // metadata".
+                if (deployAdapter.capabilities?.streamMode === 'polling') {
+                    process.stderr.write(`[deploy] note: ${deployAdapter.name} uses 2s log polling — lines may arrive in batches and could include short gaps. See docs/deploy/adapters.md#log-streaming for details.\n`);
+                }
                 streamController = new AbortController();
                 const streamFn = deployAdapter.streamLogs.bind(deployAdapter);
                 const ctrlSignal = streamController.signal;
@@ -142,12 +152,20 @@ export async function runDeploy(opts) {
                     const wantRollback = triggers.includes('healthCheckFailure');
                     if (wantRollback) {
                         if (typeof deployAdapter.rollback === 'function') {
+                            // BOUND: exactly one auto-rollback per deploy attempt (spec §
+                            // "Health-check policy" → "After rollback completes (success
+                            // or failure), the adapter returns; no second rollback
+                            // attempt"). The single `rollback({})` call below is the only
+                            // place this path is invoked; we do NOT loop. Result status
+                            // becomes one of the two new terminal values:
+                            //   - `fail_rolled_back` — rollback returned `pass`
+                            //   - `fail_rollback_failed` — rollback returned non-pass OR threw
                             try {
                                 const rb = await deployAdapter.rollback({});
                                 if (rb.status === 'pass') {
                                     result = {
                                         ...result,
-                                        status: 'fail',
+                                        status: 'fail_rolled_back',
                                         rolledBackTo: rb.rolledBackTo ?? rb.deployId,
                                         output: `Deploy passed; health check failed (${healthOutcome.lastError}); auto-rolled back to ${rb.rolledBackTo ?? rb.deployId ?? '<unknown>'}.`,
                                     };
@@ -156,7 +174,7 @@ export async function runDeploy(opts) {
                                 else {
                                     result = {
                                         ...result,
-                                        status: 'fail',
+                                        status: 'fail_rollback_failed',
                                         output: `Deploy passed; health check failed; auto-rollback ALSO failed: ${rb.output ?? '<no output>'}`,
                                     };
                                     printAutoRollbackFailed(rb.output ?? 'rollback returned non-pass');
@@ -166,7 +184,7 @@ export async function runDeploy(opts) {
                                 const msg = err?.message ?? String(err);
                                 result = {
                                     ...result,
-                                    status: 'fail',
+                                    status: 'fail_rollback_failed',
                                     output: `Deploy passed; health check failed; auto-rollback ERRORED: ${msg}`,
                                 };
                                 printAutoRollbackFailed(msg);
@@ -364,15 +382,22 @@ function formatAge(createdAtMs) {
     const days = Math.floor(hours / 24);
     return `${days}d`;
 }
+/** Per v5.6 spec § "Health-check policy" — cap retries at 5× with 6s backoff. */
+const HEALTH_CHECK_MAX_ATTEMPTS = 5;
+const HEALTH_CHECK_BACKOFF_MS = 6000;
 /**
- * Probe a URL up to 3 times with 2s backoff between attempts. 2xx → pass.
+ * Probe a URL up to {@link HEALTH_CHECK_MAX_ATTEMPTS} times with
+ * {@link HEALTH_CHECK_BACKOFF_MS} backoff between attempts. 2xx → pass.
  * Per-attempt timeout is 10s. Network errors are treated as failures and
  * retried.
+ *
+ * Total wall-clock budget: ~30s (5 attempts × 6s backoff between, minus
+ * the trailing skip — matches the spec's "max ~30s window").
  */
 async function runHealthCheck(opts) {
     const { url, fetchImpl, sleepImpl } = opts;
     let lastError = '';
-    for (let attempt = 1; attempt <= 3; attempt += 1) {
+    for (let attempt = 1; attempt <= HEALTH_CHECK_MAX_ATTEMPTS; attempt += 1) {
         const ctrl = new AbortController();
         const timer = setTimeout(() => ctrl.abort(), 10_000);
         try {
@@ -387,8 +412,8 @@ async function runHealthCheck(opts) {
             clearTimeout(timer);
             lastError = err?.message ?? String(err);
         }
-        if (attempt < 3)
-            await sleepImpl(2000);
+        if (attempt < HEALTH_CHECK_MAX_ATTEMPTS)
+            await sleepImpl(HEALTH_CHECK_BACKOFF_MS);
     }
     return { status: 'fail', url, lastError };
 }
@@ -406,7 +431,7 @@ function printAutoRollback(adapter, hc, rb) {
     const reset = '\x1b[0m';
     const target = rb.rolledBackTo ?? rb.deployId ?? '<unknown>';
     console.log(`${yellow}🔄 [deploy] auto-rolled-back-to=${target} via=${adapter} health-check-url=${hc.url}${reset}`);
-    console.log(`${dim}   reason: health check failed 3x against ${hc.url} (${hc.lastError})${reset}`);
+    console.log(`${dim}   reason: health check failed ${HEALTH_CHECK_MAX_ATTEMPTS}x against ${hc.url} (${hc.lastError})${reset}`);
     if (rb.deployUrl) {
         console.log(`${dim}   current: ${rb.deployUrl}${reset}`);
     }

package/dist/src/cli/fix.d.ts

@@ -1,3 +1,4 @@
+import type { ReviewEngine } from '../adapters/review-engine/types.ts';
 export interface FixCommandOptions {
     cwd?: string;
     configPath?: string;
@@ -5,6 +6,23 @@ export interface FixCommandOptions {
     dryRun?: boolean;
     yes?: boolean;
     noVerify?: boolean;
+    /**
+     * v6.0.2 — engine knob inputs. Same shape and precedence as scan / costs
+     * (CLI > env > config > built-in default off in v6.0.x). The CLI
+     * dispatcher wires `cliEngine` from `--engine` / `--no-engine`;
+     * `envEngine` from `process.env.CLAUDE_AUTOPILOT_ENGINE`. An absent CLI
+     * flag + absent env value falls through to the loaded config and then to
+     * the built-in default.
+     */
+    cliEngine?: boolean;
+    envEngine?: string;
+    /**
+     * Test-only seam — injects a pre-built ReviewEngine so tests can exercise
+     * the engine-wrap path without hitting `loadAdapter()` (and therefore
+     * without needing an LLM API key in the environment). Mirrors the seam
+     * in `scan.ts`. Production callers MUST NOT pass this.
+     */
+    __testReviewEngine?: ReviewEngine;
 }
 export declare function runFix(options?: FixCommandOptions): Promise<number>;
 //# sourceMappingURL=fix.d.ts.map

package/dist/src/cli/fix.js

@@ -6,6 +6,7 @@ import { loadCachedFindings } from "../core/persist/findings-cache.js";
 import { loadConfig } from "../core/config/loader.js";
 import { loadAdapter } from "../adapters/loader.js";
 import { generateFix, buildUnifiedDiff } from "../core/fix/generator.js";
+import { runPhaseWithLifecycle } from "../core/run-state/run-phase-with-lifecycle.js";
 const C = {
     reset: '\x1b[0m', bold: '\x1b[1m', dim: '\x1b[2m',
     green: '\x1b[32m', yellow: '\x1b[33m', red: '\x1b[31m', cyan: '\x1b[36m',
@@ -90,14 +91,22 @@ export async function runFix(options = {}) {
     let loadedConfig = null;
     try {
         loadedConfig = fs.existsSync(configPath) ? await loadConfig(configPath) : null;
-        const ref = loadedConfig
-            ? (typeof loadedConfig.reviewEngine === 'string' ? loadedConfig.reviewEngine : (loadedConfig.reviewEngine?.adapter ?? 'auto'))
-            : 'auto';
-        engine = await loadAdapter({
-            point: 'review-engine',
-            ref,
-            options: loadedConfig && typeof loadedConfig.reviewEngine === 'object' ? loadedConfig.reviewEngine.options : undefined,
-        });
+        if (options.__testReviewEngine) {
+            // Test-only fast path — skip the adapter loader (and therefore the
+            // implicit LLM key check inside the auto-loader). Same seam as scan's
+            // `__testReviewEngine`. Production callers do not pass this.
+            engine = options.__testReviewEngine;
+        }
+        else {
+            const ref = loadedConfig
+                ? (typeof loadedConfig.reviewEngine === 'string' ? loadedConfig.reviewEngine : (loadedConfig.reviewEngine?.adapter ?? 'auto'))
+                : 'auto';
+            engine = await loadAdapter({
+                point: 'review-engine',
+                ref,
+                options: loadedConfig && typeof loadedConfig.reviewEngine === 'object' ? loadedConfig.reviewEngine.options : undefined,
+            });
+        }
     }
     catch (err) {
         console.error(fmt('red', `[fix] Could not load review engine: ${err instanceof Error ? err.message : String(err)}`));
@@ -108,6 +117,81 @@ export async function runFix(options = {}) {
     if (shouldVerify) {
         console.log(fmt('dim', `[fix] Verified mode — running "${testCommand}" after each fix\n`));
     }
+    const fixInput = {
+        cwd,
+        fixable,
+        engine,
+        testCommand,
+        shouldVerify,
+        // The early-return above already exits when options.dryRun is true, so
+        // we're always entering the apply loop here with dryRun=false. Keep the
+        // field on FixInput for shape parity (renderFixOutput consumes it) and
+        // for future engine-resume scenarios where the snapshot is replayed.
+        dryRun: false,
+        yes: options.yes === true,
+    };
+    // The wrapped phase body — runs the apply loop with native readline +
+    // per-finding console output INSIDE the phase body. The recipe doc says
+    // "no console output" for phase bodies, but `fix` is fundamentally
+    // interactive: the user must see each diff and approve it. Same precedent
+    // as scan keeping its LLM call inside the phase body. Documented
+    // deviation, intentional.
+    const phase = {
+        name: 'fix',
+        // Same-input → same-output: the LLM fix generator is deterministic per
+        // (finding, file content) pair, and applied diffs are exact text
+        // replacements. Re-running against the same cached findings against an
+        // unchanged tree produces the same results.
+        idempotent: true,
+        // Local file edits only — no remote / git push / PR creation in the
+        // existing `fix` flow. Per the recipe table, "side effects" means
+        // platform-side mutations (PR comments, git push, deploy). Local file
+        // writes are inside the project tree and the engine treats them like
+        // findings-cache writes (already overwrite-style).
+        hasSideEffects: false,
+        run: async (input) => executeFixPhase(input),
+    };
+    // v6.0.6 — lifecycle wiring lives in `runPhaseWithLifecycle`. The helper
+    // owns the engine-on/engine-off branch and the failure banner; the caller
+    // just supplies the phase, the input, and the engine-off escape hatch.
+    // The fix phase body is interactive (readline + per-finding diff prints
+    // INSIDE executeFixPhase) — that deviation from "pure phase body" is
+    // documented in fix's executeFixPhase header comment and unaffected by
+    // the helper extract: the helper still calls phase.run, which IS
+    // executeFixPhase, exactly as before.
+    let output;
+    try {
+        const result = await runPhaseWithLifecycle({
+            cwd,
+            phase,
+            input: fixInput,
+            // The helper only consults `config.engine.enabled` — pass through
+            // `loadedConfig` if we have one, otherwise an empty default.
+            config: loadedConfig ?? { configVersion: 1 },
+            cliEngine: options.cliEngine,
+            envEngine: options.envEngine,
+            runEngineOff: () => executeFixPhase(fixInput),
+        });
+        output = result.output;
+    }
+    catch {
+        // Helper already printed the failure banner + emitted run.complete
+        // failed + refreshed state.json + released the lock.
+        return 1;
+    }
+    return renderFixOutput(output, fixInput);
+}
+// ---------------------------------------------------------------------------
+// Phase body — drive the apply loop. INTENTIONAL DEVIATION from the recipe:
+// the loop emits per-finding console output and prompts via readline. Pure
+// side-effect-free phase bodies are the recipe default; interactive verbs
+// like `fix` are an explicit exception (same precedent as scan's LLM call
+// inside its phase body). The summary banner + exit code logic still lives
+// in `renderFixOutput` so the engine path's idempotency isn't coupled to
+// the final stdout shape.
+// ---------------------------------------------------------------------------
+async function executeFixPhase(input) {
+    const { cwd, fixable, engine, testCommand, shouldVerify, dryRun, yes } = input;
     const results = [];
     let quit = false;
     for (const finding of fixable) {
@@ -135,7 +219,7 @@ export async function runFix(options = {}) {
         }
         // Show diff
         const diff = buildUnifiedDiff(result.originalLines, result.replacementLines, finding.file, result.startLine);
-        if (options.dryRun) {
+        if (dryRun) {
             console.log('');
             console.log(diff);
             console.log(fmt('dim', '    (dry run — not applied)'));
@@ -143,7 +227,7 @@ export async function runFix(options = {}) {
             continue;
         }
         // Interactive confirmation (unless --yes)
-        if (!options.yes) {
+        if (!yes) {
             const answer = await confirmFix(diff, finding);
             if (answer === 'quit') {
                 quit = true;
@@ -197,12 +281,22 @@ export async function runFix(options = {}) {
             results.push({ file: finding.file, line: finding.line, findingMessage: finding.message, status: 'failed', reason: String(err) });
         }
     }
+    return { results, dryRun };
+}
+// ---------------------------------------------------------------------------
+// Render — translate FixOutput back to the legacy stdout summary + exit
+// code. Lives outside the wrapped phase so the engine path's idempotency
+// isn't coupled to the final summary line shape.
+// ---------------------------------------------------------------------------
+function renderFixOutput(output, input) {
+    const { results, dryRun } = output;
+    const { fixable } = input;
     const fixed = results.filter(r => r.status === 'fixed').length;
     const rejected = results.filter(r => r.status === 'rejected').length;
     const failed = results.filter(r => r.status === 'failed').length;
     const skipped = results.filter(r => r.status === 'skipped').length;
     console.log('');
-    if (options.dryRun) {
+    if (dryRun) {
         console.log(fmt('yellow', `[fix] Dry run complete — ${fixable.length} finding${fixable.length !== 1 ? 's' : ''} previewed, no files modified.\n`));
     }
     else {