@delegance/claude-autopilot 5.5.2 → 7.2.0

package/dist/src/cli/dashboard/logout.js

@@ -0,0 +1,45 @@
+// `claude-autopilot dashboard logout` — revoke server-side, delete config locally.
+//
+// Idempotent: missing config or HTTP failure both still result in the
+// local file being deleted. Server-side revocation is best-effort but we
+// surface the status code on stdout for transparency.
+import { readConfig, deleteConfig } from "../../dashboard/config.js";
+export async function runDashboardLogout(opts = {}) {
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const baseUrl = opts.baseUrl ?? process.env.AUTOPILOT_DASHBOARD_BASE_URL ?? 'https://autopilot.dev';
+    const cfg = await readConfig();
+    if (!cfg) {
+        if (!opts.silent)
+            process.stdout.write(`[autopilot] not logged in.\n`);
+        await deleteConfig();
+        return { hadConfig: false, serverRevoked: false, serverStatus: null };
+    }
+    let status = null;
+    let revoked = false;
+    try {
+        const res = await fetchImpl(`${baseUrl}/api/dashboard/api-keys/revoke`, {
+            method: 'POST',
+            headers: {
+                authorization: `Bearer ${cfg.apiKey}`,
+                'content-type': 'application/json',
+            },
+            body: JSON.stringify({ apiKey: cfg.apiKey }),
+        });
+        status = res.status;
+        revoked = res.ok;
+    }
+    catch {
+        /* network error — local delete still proceeds */
+    }
+    await deleteConfig();
+    if (!opts.silent) {
+        if (revoked) {
+            process.stdout.write(`[autopilot] logged out (key ${cfg.fingerprint} revoked).\n`);
+        }
+        else {
+            process.stdout.write(`[autopilot] local config deleted; server revocation status=${status ?? 'network error'}.\n`);
+        }
+    }
+    return { hadConfig: true, serverRevoked: revoked, serverStatus: status };
+}
+//# sourceMappingURL=logout.js.map

package/dist/src/cli/dashboard/status.d.ts

@@ -0,0 +1,30 @@
+export interface StatusOptions {
+    baseUrl?: string;
+    fetchImpl?: typeof fetch;
+    silent?: boolean;
+}
+export interface MeResponse {
+    email: string | null;
+    fingerprint: string | null;
+    organizations: Array<{
+        id: string;
+        name: string;
+        role: string;
+    }>;
+    lastUploadAt: string | null;
+}
+export interface StatusResult {
+    loggedIn: boolean;
+    fingerprint: string | null;
+    email: string | null;
+    serverOk: boolean;
+    organizations: Array<{
+        id: string;
+        name: string;
+        role: string;
+    }>;
+    lastUploadAt: string | null;
+    permissiveWarning: string | null;
+}
+export declare function runDashboardStatus(opts?: StatusOptions): Promise<StatusResult>;
+//# sourceMappingURL=status.d.ts.map

package/dist/src/cli/dashboard/status.js

@@ -0,0 +1,65 @@
+// `claude-autopilot dashboard status` — read config + call /me + print.
+import { readConfig, warnIfPermissive, getConfigPath, } from "../../dashboard/config.js";
+export async function runDashboardStatus(opts = {}) {
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const baseUrl = opts.baseUrl ?? process.env.AUTOPILOT_DASHBOARD_BASE_URL ?? 'https://autopilot.dev';
+    const cfg = await readConfig();
+    const permissive = await warnIfPermissive();
+    if (!cfg) {
+        if (!opts.silent) {
+            process.stdout.write(`[autopilot] not logged in. Run: claude-autopilot dashboard login\n`);
+            process.stdout.write(`            (config path: ${getConfigPath()})\n`);
+        }
+        return {
+            loggedIn: false,
+            fingerprint: null,
+            email: null,
+            serverOk: false,
+            organizations: [],
+            lastUploadAt: null,
+            permissiveWarning: permissive,
+        };
+    }
+    let me = null;
+    let serverOk = false;
+    try {
+        const res = await fetchImpl(`${baseUrl}/api/dashboard/me`, {
+            method: 'GET',
+            headers: { authorization: `Bearer ${cfg.apiKey}` },
+        });
+        if (res.ok) {
+            me = await res.json();
+            serverOk = true;
+        }
+    }
+    catch {
+        /* network error — fall through with serverOk=false */
+    }
+    if (!opts.silent) {
+        process.stdout.write(`[autopilot] logged in as ${cfg.accountEmail} (${cfg.fingerprint}).\n`);
+        if (serverOk && me) {
+            if (me.organizations.length > 0) {
+                process.stdout.write(`            organizations: ${me.organizations.map((o) => `${o.name} (${o.role})`).join(', ')}\n`);
+            }
+            if (me.lastUploadAt) {
+                process.stdout.write(`            last upload: ${me.lastUploadAt}\n`);
+            }
+        }
+        else {
+            process.stdout.write(`            (server unreachable; using cached config)\n`);
+        }
+        if (permissive) {
+            process.stderr.write(`${permissive}\n`);
+        }
+    }
+    return {
+        loggedIn: true,
+        fingerprint: cfg.fingerprint,
+        email: cfg.accountEmail,
+        serverOk,
+        organizations: me?.organizations ?? [],
+        lastUploadAt: me?.lastUploadAt ?? null,
+        permissiveWarning: permissive,
+    };
+}
+//# sourceMappingURL=status.js.map

package/dist/src/cli/dashboard/upload.d.ts

@@ -0,0 +1,16 @@
+import { type UploadResult } from '../../dashboard/upload/uploader.ts';
+export interface ManualUploadOptions {
+    runId: string;
+    runsDir?: string;
+    baseUrl?: string;
+    fetchImpl?: typeof fetch;
+    silent?: boolean;
+    signal?: AbortSignal;
+}
+export interface ManualUploadResult extends UploadResult {
+    notLoggedIn?: boolean;
+    runDirMissing?: boolean;
+    runDir?: string;
+}
+export declare function runDashboardUpload(opts: ManualUploadOptions): Promise<ManualUploadResult>;
+//# sourceMappingURL=upload.d.ts.map

package/dist/src/cli/dashboard/upload.js

@@ -0,0 +1,48 @@
+// `claude-autopilot dashboard upload <runId>` — manual upload wrapper.
+//
+// Locates run dir at <homeDir>/runs/<runId>, calls uploadRun() directly,
+// and prints the result. Intended for resuming interrupted auto-uploads.
+import * as path from 'node:path';
+import { promises as fs } from 'node:fs';
+import { readConfig, getConfigDir } from "../../dashboard/config.js";
+import { uploadRun } from "../../dashboard/upload/uploader.js";
+export async function runDashboardUpload(opts) {
+    const cfg = await readConfig();
+    if (!cfg) {
+        if (!opts.silent) {
+            process.stderr.write(`[autopilot] not logged in. Run: claude-autopilot dashboard login\n`);
+        }
+        return { ok: false, notLoggedIn: true };
+    }
+    const runsDir = opts.runsDir ?? path.join(getConfigDir(), 'runs');
+    const runDir = path.join(runsDir, opts.runId);
+    try {
+        await fs.access(runDir);
+    }
+    catch {
+        if (!opts.silent) {
+            process.stderr.write(`[autopilot] run dir not found: ${runDir}\n`);
+        }
+        return { ok: false, runDirMissing: true, runDir };
+    }
+    const uploadOpts = {
+        apiKey: cfg.apiKey,
+        ...(opts.baseUrl !== undefined ? { baseUrl: opts.baseUrl } : {}),
+        ...(opts.fetchImpl !== undefined ? { fetchImpl: opts.fetchImpl } : {}),
+        ...(opts.signal !== undefined ? { signal: opts.signal } : {}),
+    };
+    const res = await uploadRun(opts.runId, runDir, uploadOpts);
+    if (!opts.silent) {
+        if (res.ok && res.url) {
+            process.stdout.write(`[autopilot] uploaded to ${res.url}\n`);
+        }
+        else if (res.ok && res.skipped) {
+            process.stdout.write(`[autopilot] skipping upload — events.ndjson is empty\n`);
+        }
+        else {
+            process.stderr.write(`[autopilot] upload failed: ${res.error}\n`);
+        }
+    }
+    return { ...res, runDir };
+}
+//# sourceMappingURL=upload.js.map

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/engine-flag-deprecation.d.ts

@@ -0,0 +1,14 @@
+/** Banner emitted to stderr (once per process) when `--engine` is
+ *  passed in v7.0+. The flag is preserved as a no-op shim; the engine
+ *  is unconditionally on. Codex pass-3 NOTE #2. */
+export declare const ENGINE_FLAG_DEPRECATION_MESSAGE = "[deprecation] --engine is a no-op in v7.0+ (engine is always on). Drop the flag from your scripts.";
+/** Banner emitted to stderr when `--no-engine` is passed in v7.0+. The
+ *  dispatcher rejects with `invalid_config` exit 1 immediately after. */
+export declare const ENGINE_OFF_REMOVED_MESSAGE = "[deprecation] --no-engine was removed in v7.0. The engine is always on. See docs/v7/breaking-changes.md.";
+/** Banner emitted to stderr (once per process) when
+ *  `CLAUDE_AUTOPILOT_ENGINE` is set to an off-style value. The env value
+ *  is otherwise ignored — softer than the `--no-engine` rejection
+ *  because env vars in CI are sticky and silently breaking every
+ *  v6.x → v7 upgrade in CI on day one would burn user trust. */
+export declare const ENGINE_OFF_ENV_REMOVED_MESSAGE = "[deprecation] CLAUDE_AUTOPILOT_ENGINE=off has no effect in v7.0+ (engine is always on). Unset the env var.";
+//# sourceMappingURL=engine-flag-deprecation.d.ts.map

package/dist/src/cli/engine-flag-deprecation.js

@@ -0,0 +1,20 @@
+// src/cli/engine-flag-deprecation.ts
+//
+// v7.0 — exported deprecation constants for the engine-flag removal.
+// Pulled out of src/cli/index.ts so tests can import them without
+// triggering the dispatcher's top-level switch (which exits the
+// process on module load).
+/** Banner emitted to stderr (once per process) when `--engine` is
+ *  passed in v7.0+. The flag is preserved as a no-op shim; the engine
+ *  is unconditionally on. Codex pass-3 NOTE #2. */
+export const ENGINE_FLAG_DEPRECATION_MESSAGE = '[deprecation] --engine is a no-op in v7.0+ (engine is always on). Drop the flag from your scripts.';
+/** Banner emitted to stderr when `--no-engine` is passed in v7.0+. The
+ *  dispatcher rejects with `invalid_config` exit 1 immediately after. */
+export const ENGINE_OFF_REMOVED_MESSAGE = '[deprecation] --no-engine was removed in v7.0. The engine is always on. See docs/v7/breaking-changes.md.';
+/** Banner emitted to stderr (once per process) when
+ *  `CLAUDE_AUTOPILOT_ENGINE` is set to an off-style value. The env value
+ *  is otherwise ignored — softer than the `--no-engine` rejection
+ *  because env vars in CI are sticky and silently breaking every
+ *  v6.x → v7 upgrade in CI on day one would burn user trust. */
+export const ENGINE_OFF_ENV_REMOVED_MESSAGE = '[deprecation] CLAUDE_AUTOPILOT_ENGINE=off has no effect in v7.0+ (engine is always on). Unset the env var.';
+//# sourceMappingURL=engine-flag-deprecation.js.map

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 {

package/dist/src/cli/help-text.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Two-level help grouping for the claude-autopilot CLI.
+ *
+ * The CLI ships ~25 subcommands. A flat list crowds the welcome screen and
+ * makes it hard for new users to find the verb they need. This module owns
+ * the canonical grouping (Pipeline / Review / Deploy / Migrate / Diagnostics
+ * / Advanced), the per-verb summaries, and the per-verb Options blocks.
+ *
+ * The dispatcher in index.ts imports these helpers — keeping the data here
+ * means the help text can be rendered into a string for tests without firing
+ * the side-effecting top-level switch statement in index.ts.
+ *
+ * Group assignments are asserted by tests/cli/help-text.test.ts so newly
+ * added verbs are forced into the structure rather than silently dropped.
+ *
+ * Groups are ordered roughly by user journey:
+ *   Pipeline    — brainstorm → spec → plan → implement → PR
+ *   Review      — operates on findings / runs the LLM-backed code review
+ *   Deploy      — platform-specific deploy verbs
+ *   Migrate     — database migration dispatch
+ *   Diagnostics — sanity checks, second-opinion, test scaffolding
+ *   Advanced    — long-running daemons / niche / experimental verbs
+ */
+export type HelpVerb = {
+    verb: string;
+    summary: string;
+};
+export type HelpGroup = {
+    name: string;
+    tagline: string;
+    verbs: HelpVerb[];
+};
+export declare const HELP_GROUPS: HelpGroup[];
+/**
+ * Per-verb Options blocks. Keyed by the verb that owns the block. Some verbs
+ * have no documented flags (e.g. `costs`, `lsp`, `report`) and are absent here;
+ * `claude-autopilot help <verb>` will show just the row in that case.
+ */
+export declare const HELP_OPTIONS: Record<string, string>;
+/**
+ * Global flags advertised in --help. These work across most verbs (per-verb
+ * support varies; v6.0.1 wires them into `scan` first, additional verbs land
+ * in subsequent v6.0.x point releases per docs/v6/wrapping-pipeline-phases.md).
+ */
+export declare const GLOBAL_FLAGS_BLOCK = "Global flags:\n  --json                 Emit a structured JSON envelope on stdout (most verbs)\n  --engine               [v7.0 deprecated no-op] engine is always on; flag emits a warning\n                         v7.0 removed the engine-off opt-out flag and code path entirely.\n                         CLAUDE_AUTOPILOT_ENGINE=off is now ignored (warns once per process)\n                         instead of disabling the engine. See docs/v7/breaking-changes.md.";
+/** Build the full two-level help text. Returned as a string so tests can assert against it without spawning. */
+export declare function buildHelpText(): string;
+/** Build help text for a single verb. Returns null if the verb is unknown. */
+export declare function buildCommandHelpText(verb: string): string | null;
+/** Set of verbs that have a row in HELP_GROUPS — used by `help <verb>` lookup and by tests. */
+export declare const HELP_VERBS: readonly string[];
+//# sourceMappingURL=help-text.d.ts.map