@delegance/claude-autopilot 5.2.2 → 6.2.2

package/dist/src/cli/index.js

@@ -29,9 +29,12 @@ import { runCouncilCmd } from "./council.js";
 import { runMigrateV4 } from "./migrate-v4.js";
 import { runMigrateDoctor } from "./migrate-doctor.js";
 import { initMigrate, NoMigrationToolDetectedError } from "./init-migrate.js";
-import { dispatch as runMigrateDispatch } from "../core/migrate/dispatcher.js";
+import { runMigrate } from "./migrate.js";
+import { runDeploy, runDeployRollback, runDeployStatus } from "./deploy.js";
 import { findPackageRoot } from "./_pkg-root.js";
 import { GuardrailError } from "../core/errors.js";
+import { buildHelpText, buildCommandHelpText } from "./help-text.js";
+import { runUnderJsonMode } from "./json-envelope.js";
 // Format unhandled errors as a one-line user-facing message instead of dumping a
 // Node stack trace. Auth/network failures are by far the most common path here
 // (bad/missing API key, rate limit, network blip) and surfacing the raw stack
@@ -105,6 +108,21 @@ const REVIEW_VERBS = new Set(['run', 'scan', 'ci', 'fix', 'baseline', 'explain',
 // `detector` is a library used by setup/run, not a CLI subcommand — leave it out.
 const ADVANCED_VERBS = new Set(['lsp', 'mcp', 'worker', 'autoregress', 'test-gen', 'hook', 'ignore']);
 if (args[0] === 'review') {
+    // v6.0.4 — `review` is BOTH a grouping prefix (legacy alpha.2) AND a flat
+    // verb (the new engine-wrapped `runReview`). Disambiguate based on args[1]:
+    //
+    //   - missing                  → grouping-prefix help banner (legacy V16)
+    //   - --help / -h              → grouping-prefix help banner (legacy)
+    //   - in REVIEW_VERBS          → grouping prefix (shift, route to flat handler)
+    //   - other flag (`--engine`,
+    //     `--config`, etc.)        → flat-verb invocation; let `case 'review':` handle it
+    //   - anything else            → reject with legacy "not a review-phase verb"
+    //
+    // The "missing → prefix help" branch preserves the V16 v4-compat test
+    // (`claude-autopilot review` alone prints the review-phase verb list);
+    // users who want the v6 flat-verb behavior must pass at least one flag
+    // (e.g. `--engine`, `--config`, `--context`). `help review` continues to
+    // surface the flat-verb Options block via buildCommandHelpText.
     const sub = args[1];
     if (!sub || sub === '--help' || sub === '-h') {
         console.log(`
@@ -122,16 +140,25 @@ Review-phase verbs:
 
 These are aliases for the flat subcommands — \`claude-autopilot run\` and
 \`claude-autopilot review run\` are equivalent.
+
+The v6 \`review\` phase verb (engine-wrap shell) is invoked with any flag
+present, e.g. \`claude-autopilot review --engine\`. See
+\`claude-autopilot help review\` for its options.
 `);
         process.exit(0);
     }
-    if (!REVIEW_VERBS.has(sub)) {
+    if (sub.startsWith('--')) {
+        // Flat-verb invocation — fall through; do not shift.
+    }
+    else if (!REVIEW_VERBS.has(sub)) {
         console.error(`\x1b[31m[claude-autopilot] "${sub}" is not a review-phase verb.\x1b[0m`);
         console.error(`\x1b[2m  Valid: ${[...REVIEW_VERBS].join(', ')}\x1b[0m`);
         console.error(`\x1b[2m  Did you mean: claude-autopilot ${sub} ...?\x1b[0m`);
         process.exit(1);
     }
-    args.shift(); // drop 'review', leave the flat subcommand at args[0]
+    else {
+        args.shift(); // drop 'review', leave the flat subcommand at args[0]
+    }
 }
 if (args[0] === 'advanced') {
     const sub = args[1];
@@ -159,8 +186,17 @@ These are aliases for the flat subcommands; they still work without the 'advance
     }
     args.shift(); // drop 'advanced'
 }
-const SUBCOMMANDS = ['init', 'run', 'scan', 'report', 'explain', 'ignore', 'ci', 'pr', 'fix', 'costs', 'watch', 'hook', 'autoregress', 'baseline', 'triage', 'lsp', 'worker', 'mcp', 'test-gen', 'pr-desc', 'doctor', 'preflight', 'setup', 'council', 'migrate-v4', 'migrate', 'migrate-doctor', 'brainstorm', 'help', '--help', '-h'];
-const VALUE_FLAGS = ['base', 'config', 'files', 'format', 'output', 'debounce', 'ask', 'focus', 'fail-on', 'note', 'reason', 'expires', 'profile', 'severity', 'prompt', 'context-file', 'path'];
+// `internal` is a hidden verb (v6 Phase 2): markdown-driven skills shell out
+// to it to append typed events. Deliberately not in HELP_GROUPS / HELP_VERBS,
+// not advertised in the welcome banner. Documented only via
+// `claude-autopilot internal --help`.
+//
+// `runs` (plural) is the v6 Phase 3 umbrella verb — its sub-verbs (list, show,
+// gc, delete, doctor) are dispatched inside its case block. The singular
+// `run resume` form is handled BEFORE the default `run` -> review dispatch
+// kicks in (see disambiguation block just below).
+const SUBCOMMANDS = ['init', 'run', 'runs', 'scan', 'report', 'explain', 'ignore', 'ci', 'pr', 'fix', 'costs', 'watch', 'hook', 'autoregress', 'baseline', 'triage', 'lsp', 'worker', 'mcp', 'test-gen', 'pr-desc', 'doctor', 'preflight', 'setup', 'council', 'migrate-v4', 'migrate', 'migrate-doctor', 'deploy', 'brainstorm', 'spec', 'plan', 'implement', 'review', 'validate', 'autopilot', 'internal', 'help', '--help', '-h'];
+const VALUE_FLAGS = ['base', 'config', 'files', 'format', 'output', 'debounce', 'ask', 'focus', 'fail-on', 'note', 'reason', 'expires', 'profile', 'severity', 'prompt', 'context-file', 'path', 'adapter', 'ref', 'sha', 'spec', 'context', 'mode', 'phases', 'budget'];
 // Bare invocation — no subcommand, no flags → show welcome guide
 if (args.length === 0) {
     const hasKey = !!(process.env.ANTHROPIC_API_KEY || process.env.GEMINI_API_KEY ||
@@ -196,8 +232,16 @@ Run \x1b[36mclaude-autopilot --help\x1b[0m for full command reference.
 `);
     process.exit(0);
 }
-// Detect first non-flag arg as subcommand, default to 'run'
-const subcommand = (args[0] && !args[0].startsWith('--')) ? args[0] : 'run';
+// Detect first non-flag arg as subcommand, default to 'run'.
+//
+// v6 Phase 3 disambiguation: `run resume <id>` is a v6 verb; the bare `run`
+// remains the legacy review-phase entry point. We rewrite the head to a
+// synthetic 'run-resume' subcommand so the existing 'run' case keeps doing
+// `runReview` and we don't need to special-case it inside the review path.
+let subcommand = (args[0] && !args[0].startsWith('--')) ? args[0] : 'run';
+if (subcommand === 'run' && args[1] === 'resume') {
+    subcommand = 'run-resume';
+}
 /** Returns value for --name <value>. Exits if value is missing (next token is another flag or absent). */
 function flag(name) {
     const idx = args.indexOf(`--${name}`);
@@ -213,113 +257,76 @@ function flag(name) {
 function boolFlag(name) {
     return args.includes(`--${name}`);
 }
+/**
+ * Parse the `--engine` / `--no-engine` flag pair into a tri-state.
+ *
+ * Returns:
+ *   - true  if `--engine` was passed
+ *   - false if `--no-engine` was passed
+ *   - undefined if neither was passed
+ *
+ * If BOTH are passed, exits 1 with `invalid_config` — the spec is explicit
+ * that this is single-version-supported, you can't ask for both at once.
+ */
+function parseEngineCliFlag() {
+    const on = args.includes('--engine');
+    const off = args.includes('--no-engine');
+    if (on && off) {
+        console.error(`\x1b[31m[claude-autopilot] invalid_config: --engine and --no-engine cannot both be passed\x1b[0m`);
+        console.error(`\x1b[2m  hint: pass exactly one. Precedence: CLI > env > config > default.\x1b[0m`);
+        process.exit(1);
+    }
+    if (on)
+        return true;
+    if (off)
+        return false;
+    return undefined;
+}
 /**
  * Run the migrate-doctor with shared CLI formatting and exit handling.
  *
  * Both `migrate doctor` (two-word) and `migrate-doctor` (single-verb alias)
  * resolve to this helper to keep their behavior locked together.
+ *
+ * Phase 5: also handles --json (envelope on stdout, no human banner).
  */
 async function runMigrateDoctorCLI() {
     const fix = args.includes('--fix');
-    const result = await runMigrateDoctor({ repoRoot: process.cwd(), fix });
-    for (const r of result.results) {
-        const mark = r.result.ok ? '\x1b[32m✓\x1b[0m' : '\x1b[31m✗\x1b[0m';
-        console.log(`${mark} ${r.name}${r.result.message ? ` — ${r.result.message}` : ''}`);
-        if (!r.result.ok && r.result.fixHint) {
-            console.log(`  \x1b[2mhint: ${r.result.fixHint}\x1b[0m`);
+    const json = args.includes('--json');
+    let docResult = null;
+    const code = await runUnderJsonMode({
+        command: 'migrate-doctor',
+        active: json,
+        payload: () => docResult ? {
+            results: docResult.results,
+            mutations: docResult.mutations ?? [],
+            migrationReportPath: docResult.migrationReportPath,
+            allOk: docResult.allOk,
+        } : {},
+        statusFor: exit => exit === 0 ? 'pass' : 'fail',
+    }, async () => {
+        docResult = await runMigrateDoctor({ repoRoot: process.cwd(), fix });
+        for (const r of docResult.results) {
+            const mark = r.result.ok ? '\x1b[32m✓\x1b[0m' : '\x1b[31m✗\x1b[0m';
+            console.log(`${mark} ${r.name}${r.result.message ? ` — ${r.result.message}` : ''}`);
+            if (!r.result.ok && r.result.fixHint) {
+                console.log(`  \x1b[2mhint: ${r.result.fixHint}\x1b[0m`);
+            }
         }
-    }
-    if (result.mutations && result.mutations.length > 0) {
-        console.log(`\n\x1b[1mFixes applied:\x1b[0m`);
-        for (const m of result.mutations)
-            console.log(`  - ${m}`);
-    }
-    if (result.migrationReportPath) {
-        console.log(`\n\x1b[2mMigration report: ${result.migrationReportPath}\x1b[0m`);
-    }
-    process.exit(result.allOk ? 0 : 1);
+        if (docResult.mutations && docResult.mutations.length > 0) {
+            console.log(`\n\x1b[1mFixes applied:\x1b[0m`);
+            for (const m of docResult.mutations)
+                console.log(`  - ${m}`);
+        }
+        if (docResult.migrationReportPath) {
+            console.log(`\n\x1b[2mMigration report: ${docResult.migrationReportPath}\x1b[0m`);
+        }
+        return docResult.allOk ? 0 : 1;
+    });
+    process.exit(code);
 }
 function printUsage() {
-    console.log(`
-Usage: claude-autopilot <command> [options]  (legacy alias: guardrail)
-
-Commands:
-  run          Review git-changed files (default)
-  scan         Review any path — no git required
-  report       Render cached findings as a markdown report
-  explain      Deep-dive explanation + remediation for a specific finding
-  ignore       Interactively add findings to .guardrail-ignore
-  watch        Watch for file changes and re-run on each save
-  pr           Review a specific PR by number (auto-detects if on PR branch)
-  fix          Auto-fix cached findings using the configured LLM
-  costs        Show per-run cost summary
-  ci           Opinionated CI entrypoint (post comments + SARIF)
-  init         Scaffold guardrail.config.yaml + auto-detect migrate stack (writes .autopilot/stack.md)
-  migrate      Run database migrations via the stack-aware dispatcher
-  migrate doctor   Validate .autopilot/stack.md and skill manifests (alias: migrate-doctor)
-  setup        Auto-detect stack, write config, install pre-push hook
-  doctor       Check prerequisites (alias: preflight)
-  preflight    Check prerequisites (alias: doctor)
-  hook         Install / remove the pre-push git hook
-  baseline     Manage the committed findings baseline (create|update|show|delete)
-  triage       Mark individual findings as accepted/dismissed
-  pr-desc      Generate a PR title / summary / test plan from the current diff
-  council      Multi-model review — dispatch the diff to N models and synthesize consensus
-  mcp          MCP server for Claude / ChatGPT integration
-  autoregress  Snapshot regression tests (run|diff|update|generate)
-  lsp          Language server — publishes findings as LSP diagnostics (stdin/stdout)
-  worker       Persistent review daemon for multi-terminal parallel usage (start|stop|status)
-  test-gen     Detect uncovered exports and generate test cases using the LLM
-
-Options (run):
-  --base <ref>         Git base ref for diff (default: HEAD~1)
-  --config <path>      Path to config file (default: ./guardrail.config.yaml)
-  --files <a,b,c>      Explicit comma-separated file list (skips git detection)
-  --dry-run            Show what would run without executing
-  --diff               Send git diff hunks instead of full files (~70% fewer tokens)
-  --delta              Only report findings new since last run (suppress pre-existing)
-  --inline-comments    Post per-line review comments on the PR diff
-  --post-comments      Post/update a summary comment on the open PR
-  --format <text|sarif>  Output format (default: text)
-  --output <path>        Output file path (required with --format sarif)
-
-Options (scan):
-  <path> [path...]     Files or directories to scan (or --all for entire codebase)
-  --all                Scan entire codebase
-  --ask <question>     Targeted question to inject into the LLM review prompt
-  --focus <type>       security | logic | performance (default: all)
-  --dry-run            List files that would be scanned without running
-  --config <path>      Path to config file
-
-Options (pr):
-  <number>                   PR number to review (optional if on a PR branch)
-  --no-post-comments         Skip posting/updating PR summary comment
-  --no-inline-comments       Skip posting per-line inline annotations
-  --config <path>            Path to config file
-
-Options (fix):
-  --severity <critical|warning|all>  Which findings to fix (default: critical)
-  --dry-run                          Preview fixes without writing files
-  --config <path>                    Path to config file
-
-Options (watch):
-  --config <path>      Path to config file (default: ./guardrail.config.yaml)
-  --debounce <ms>      Debounce delay in ms (default: 300)
-
-Options (autoregress):
-  --all                    Run/diff all snapshots
-  --since <ref>            Git ref for changed-files detection
-  --snapshot <slug>        Target a single snapshot
-  --files <a,b,c>          Explicit file list for generate (skips git detection)
-
-Options (migrate):
-  --env <name>         Target environment from .autopilot/stack.md (default: dev)
-  --dry-run            Run skill in dry-run mode (no side effects)
-  --yes                Required to apply prod migrations in CI
-
-Options (migrate doctor / migrate-doctor):
-  --fix                Apply auto-fixable mutations (legacy stack.md, skills/migrate/, schema_version)
-`);
+    process.stdout.write(buildHelpText());
 }
 switch (subcommand) {
     case 'scan': {
@@ -332,72 +339,113 @@ switch (subcommand) {
         }
         const dryRun = boolFlag('dry-run');
         const all = boolFlag('all');
+        const json = boolFlag('json');
+        // v6.0.1 — engine knob. CLI flag wins; env / config / default resolved
+        // inside runScan once it's loaded the config file.
+        const cliEngine = parseEngineCliFlag();
         // Remaining non-flag args after 'scan' are paths
         const targets = args.slice(1).filter(a => !a.startsWith('--') && a !== ask && a !== focusArg && a !== config);
-        const code = await runScan({
+        const code = await runUnderJsonMode({ command: 'scan', active: json }, () => runScan({
             configPath: config,
             targets: targets.length > 0 ? targets : undefined,
             all,
             ask,
             focus: focusArg,
             dryRun,
-        });
+            ...(cliEngine !== undefined ? { cliEngine } : {}),
+            envEngine: process.env.CLAUDE_AUTOPILOT_ENGINE,
+        }));
         process.exit(code);
         break;
     }
     case 'init': {
         // `init` and `setup` are aliases. Keep both supported — no nag banner.
         const force = args.includes('--force');
-        await runSetup({ force });
-        // After the existing init/setup logic, sniff for a migration tool and write
-        // .autopilot/stack.md. Non-interactive: high-confidence single matches are
-        // auto-selected; ambiguity / no-match downgrades to a TODO 'none@1' shape so
-        // we don't block the user. (Interactive prompts come from the autopilot skill,
-        // not the CLI.)
-        try {
-            const result = await initMigrate({
-                repoRoot: process.cwd(),
-                force,
-            });
-            for (const ws of result.workspaces) {
-                const rel = ws.workspace === process.cwd() ? '.' : ws.workspace;
-                console.log(`\x1b[2m[init-migrate] ${ws.action} ${rel}/.autopilot/stack.md (skill: ${ws.skill})\x1b[0m`);
+        const json = boolFlag('json');
+        const code = await runUnderJsonMode({ command: 'init', active: json }, async () => {
+            await runSetup({ force });
+            // After the existing init/setup logic, sniff for a migration tool and write
+            // .autopilot/stack.md. Non-interactive: high-confidence single matches are
+            // auto-selected; ambiguity / no-match downgrades to a TODO 'none@1' shape so
+            // we don't block the user. (Interactive prompts come from the autopilot skill,
+            // not the CLI.)
+            try {
+                const result = await initMigrate({
+                    repoRoot: process.cwd(),
+                    force,
+                });
+                for (const ws of result.workspaces) {
+                    const rel = ws.workspace === process.cwd() ? '.' : ws.workspace;
+                    console.log(`\x1b[2m[init-migrate] ${ws.action} ${rel}/.autopilot/stack.md (skill: ${ws.skill})\x1b[0m`);
+                }
             }
-        }
-        catch (err) {
-            if (err instanceof NoMigrationToolDetectedError) {
-                // No high-confidence match — fall back to skipMigrate shape so the user
-                // can edit it later. This matches the auto-detection contract documented
-                // in the v5.2.0 CHANGELOG.
-                try {
-                    await initMigrate({
-                        repoRoot: process.cwd(),
-                        force,
-                        skipMigrate: true,
-                    });
-                    console.log(`\x1b[33m[init-migrate] No migration tool detected — wrote 'none@1' stack.md (edit .autopilot/stack.md to configure)\x1b[0m`);
+            catch (err) {
+                if (err instanceof NoMigrationToolDetectedError) {
+                    // No high-confidence match — fall back to skipMigrate shape so the user
+                    // can edit it later. This matches the auto-detection contract documented
+                    // in the v5.2.0 CHANGELOG.
+                    try {
+                        await initMigrate({
+                            repoRoot: process.cwd(),
+                            force,
+                            skipMigrate: true,
+                        });
+                        console.log(`\x1b[33m[init-migrate] No migration tool detected — wrote 'none@1' stack.md (edit .autopilot/stack.md to configure)\x1b[0m`);
+                    }
+                    catch (fallbackErr) {
+                        console.error(`\x1b[31m[init-migrate] failed: ${fallbackErr.message}\x1b[0m`);
+                        return 1;
+                    }
                 }
-                catch (fallbackErr) {
-                    console.error(`\x1b[31m[init-migrate] failed: ${fallbackErr.message}\x1b[0m`);
+                else {
+                    console.error(`\x1b[31m[init-migrate] failed: ${err.message}\x1b[0m`);
+                    return 1;
                 }
             }
-            else {
-                console.error(`\x1b[31m[init-migrate] failed: ${err.message}\x1b[0m`);
-            }
-        }
+            return 0;
+        });
+        if (json)
+            process.exit(code);
         break;
     }
     case 'doctor':
     case 'preflight': {
-        const result = await runDoctor();
-        process.exit(result.blockers > 0 ? 1 : 0);
+        const json = boolFlag('json');
+        let docResult = null;
+        const code = await runUnderJsonMode({
+            command: subcommand,
+            active: json,
+            payload: () => docResult ? {
+                blockers: docResult.blockers,
+                warnings: docResult.warnings,
+            } : {},
+        }, async () => {
+            docResult = await runDoctor();
+            return docResult.blockers > 0 ? 1 : 0;
+        });
+        process.exit(code);
         break;
     }
     case 'help':
     case '--help':
-    case '-h':
+    case '-h': {
+        // `claude-autopilot help <command>` — focused per-command help. Falls back
+        // to the full two-level listing with an "unknown command" notice + exit 1
+        // when the named verb isn't documented.
+        const target = args[1];
+        if (target && !target.startsWith('-')) {
+            const focused = buildCommandHelpText(target);
+            if (focused !== null) {
+                process.stdout.write(focused);
+                process.exit(0);
+            }
+            process.stderr.write(`\x1b[31m[claude-autopilot] unknown command: "${target}"\x1b[0m\n`);
+            process.stdout.write(buildHelpText());
+            process.exit(1);
+        }
         printUsage();
         break;
+    }
     case 'watch': {
         const config = flag('config');
         const debounceArg = flag('debounce');
@@ -435,7 +483,8 @@ switch (subcommand) {
             process.exit(1);
         }
         const newOnly = boolFlag('new-only');
-        const code = await runCommand({
+        const json = boolFlag('json');
+        const code = await runUnderJsonMode({ command: 'run', active: json }, () => runCommand({
             base,
             configPath: config,
             files: filesArg ? filesArg.split(',').map(f => f.trim()) : undefined,
@@ -449,7 +498,7 @@ switch (subcommand) {
             format: formatArg,
             outputPath,
             skipReview: staticOnly,
-        });
+        }));
         process.exit(code);
         break;
     }
@@ -462,7 +511,8 @@ switch (subcommand) {
         const diff = boolFlag('diff');
         const newOnly = boolFlag('new-only');
         const failOnArg = flag('fail-on');
-        const code = await runCi({
+        const json = boolFlag('json');
+        const code = await runUnderJsonMode({ command: 'ci', active: json }, () => runCi({
             configPath: config,
             base,
             sarifOutput: outputPath,
@@ -471,7 +521,7 @@ switch (subcommand) {
             diff,
             newOnly,
             failOn: failOnArg,
-        });
+        }));
         process.exit(code);
         break;
     }
@@ -480,21 +530,35 @@ switch (subcommand) {
         const sub = args[1] ?? 'show';
         const note = flag('note');
         const config = flag('config');
-        const code = await rb(sub, { cwd: process.cwd(), note, baselinePath: config });
+        const json = boolFlag('json');
+        const code = await runUnderJsonMode({ command: `baseline ${sub}`, active: json }, () => rb(sub, { cwd: process.cwd(), note, baselinePath: config }));
         process.exit(code);
         break;
     }
     case 'pr': {
+        // v6.0.9 — engine-wrap shell for the `pr` pipeline phase. Side-effecting
+        // (posts/updates a PR comment + inline review comments via the `gh` CLI
+        // inside runCommand). Declared `idempotent: false, hasSideEffects: true`
+        // with a `github-pr` externalRef recorded before the inner pipeline
+        // runs. See the long declaration note in src/cli/pr.ts for the
+        // per-call breakdown of what `gh` mutations happen and why the
+        // declaration matches the v6 spec table.
         const config = flag('config');
         const noPostComments = boolFlag('no-post-comments');
         const noInlineComments = boolFlag('no-inline-comments');
+        const json = boolFlag('json');
         const prNumber = args.slice(1).find(a => !a.startsWith('--') && /^\d+$/.test(a));
-        const code = await runPr({
+        // v6.0.9 — engine knob. CLI flag wins; env / config / default resolved
+        // inside runPr once it's loaded the config file.
+        const cliEngine = parseEngineCliFlag();
+        const code = await runUnderJsonMode({ command: 'pr', active: json }, () => runPr({
             configPath: config,
             prNumber,
             noPostComments,
             noInlineComments,
-        });
+            ...(cliEngine !== undefined ? { cliEngine } : {}),
+            envEngine: process.env.CLAUDE_AUTOPILOT_ENGINE,
+        }));
         process.exit(code);
         break;
     }
@@ -525,19 +589,26 @@ switch (subcommand) {
         }
         const dryRun = boolFlag('dry-run');
         const noVerify = boolFlag('no-verify');
-        const code = await runFix({
+        const json = boolFlag('json');
+        // v6.0.2 — engine knob. CLI flag wins; env / config / default resolved
+        // inside runFix once it's loaded the config file.
+        const cliEngine = parseEngineCliFlag();
+        const code = await runUnderJsonMode({ command: 'fix', active: json }, () => runFix({
             configPath: config,
             severity: severityArg,
             dryRun,
             noVerify,
-        });
+            ...(cliEngine !== undefined ? { cliEngine } : {}),
+            envEngine: process.env.CLAUDE_AUTOPILOT_ENGINE,
+        }));
         process.exit(code);
         break;
     }
     case 'triage': {
         const sub = args[1];
         const rest = args.slice(2);
-        const code = await runTriage(sub, rest);
+        const json = boolFlag('json');
+        const code = await runUnderJsonMode({ command: `triage${sub ? ` ${sub}` : ''}`, active: json }, () => runTriage(sub, rest));
         process.exit(code);
         break;
     }
@@ -546,15 +617,16 @@ switch (subcommand) {
         const base = flag('base');
         const dryRun = boolFlag('dry-run');
         const verify = boolFlag('verify');
+        const json = boolFlag('json');
         const targets = args.slice(1).filter(a => !a.startsWith('--') && a !== config && a !== base);
-        const code = await runTestGen({
+        const code = await runUnderJsonMode({ command: 'test-gen', active: json }, () => runTestGen({
             cwd: process.cwd(),
             configPath: config,
             targets: targets.length > 0 ? targets : undefined,
             base,
             dryRun,
             verify,
-        });
+        }));
         process.exit(code);
         break;
     }
@@ -564,12 +636,18 @@ switch (subcommand) {
         const base = baseIdx !== -1 ? args[baseIdx + 1] : undefined;
         const outputIdx = args.indexOf('--output');
         const output = outputIdx !== -1 ? args[outputIdx + 1] : undefined;
-        await runPrDesc({
-            base,
-            post: args.includes('--post'),
-            yes: args.includes('--yes'),
-            output,
+        const json = boolFlag('json');
+        const code = await runUnderJsonMode({ command: 'pr-desc', active: json }, async () => {
+            await runPrDesc({
+                base,
+                post: args.includes('--post'),
+                yes: args.includes('--yes'),
+                output,
+            });
+            return 0;
         });
+        if (json)
+            process.exit(code);
         break;
     }
     case 'lsp': {
@@ -578,22 +656,214 @@ switch (subcommand) {
     }
     case 'costs': {
         const { runCosts } = await import("./costs.js");
-        const code = await runCosts();
+        const json = boolFlag('json');
+        const config = flag('config');
+        // v6.0.2 — engine knob. CLI flag wins; env / config / default resolved
+        // inside runCosts once it's loaded the config file.
+        const cliEngine = parseEngineCliFlag();
+        const code = await runUnderJsonMode({ command: 'costs', active: json }, () => runCosts({
+            ...(config !== undefined ? { configPath: config } : {}),
+            ...(cliEngine !== undefined ? { cliEngine } : {}),
+            envEngine: process.env.CLAUDE_AUTOPILOT_ENGINE,
+        }));
+        process.exit(code);
+        break;
+    }
+    case 'plan': {
+        // v6.0.4 — engine-wrap shell for the `plan` pipeline phase. The actual
+        // LLM-driven planning content is produced by the Claude Code
+        // superpowers:writing-plans skill; this CLI verb provides a
+        // checkpointable phase shell so v6 pipeline runs can record a `plan`
+        // entry. Mirrors the costs/scan/fix dispatcher shape.
+        const { runPlan } = await import("./plan.js");
+        const json = boolFlag('json');
+        const config = flag('config');
+        const specPath = flag('spec');
+        const outputPath = flag('output');
+        const cliEngine = parseEngineCliFlag();
+        const code = await runUnderJsonMode({ command: 'plan', active: json }, () => runPlan({
+            ...(config !== undefined ? { configPath: config } : {}),
+            ...(specPath !== undefined ? { specPath } : {}),
+            ...(outputPath !== undefined ? { outputPath } : {}),
+            ...(cliEngine !== undefined ? { cliEngine } : {}),
+            envEngine: process.env.CLAUDE_AUTOPILOT_ENGINE,
+        }));
+        process.exit(code);
+        break;
+    }
+    case 'review': {
+        // v6.0.4 — engine-wrap shell for the `review` pipeline phase. The actual
+        // LLM-driven review content is produced by the Claude Code review skills
+        // (`/review`, `/review-2pass`, `pr-review-toolkit:review-pr`). PR-side
+        // comment posting lives in `claude-autopilot pr --inline-comments` /
+        // `--post-comments`; this verb does not post anywhere. See the long
+        // deviation note in src/cli/review.ts for the idempotent / hasSideEffects
+        // declaration rationale.
+        const { runReview } = await import("./review.js");
+        const json = boolFlag('json');
+        const config = flag('config');
+        const context = flag('context');
+        const outputPath = flag('output');
+        const cliEngine = parseEngineCliFlag();
+        const code = await runUnderJsonMode({ command: 'review', active: json }, () => runReview({
+            ...(config !== undefined ? { configPath: config } : {}),
+            ...(context !== undefined ? { context } : {}),
+            ...(outputPath !== undefined ? { outputPath } : {}),
+            ...(cliEngine !== undefined ? { cliEngine } : {}),
+            envEngine: process.env.CLAUDE_AUTOPILOT_ENGINE,
+        }));
+        process.exit(code);
+        break;
+    }
+    case 'validate': {
+        // v6.0.5 — engine-wrap shell for the `validate` pipeline phase. The
+        // actual validation pipeline (static checks, auto-fix, tests, Codex
+        // review with auto-fix, bugbot triage) lives in the Claude Code
+        // `/validate` skill; this verb provides a checkpointable phase shell so
+        // v6 pipeline runs can record a `validate` entry. Mirrors the
+        // plan / review dispatcher shape. See the long deviation note in
+        // src/cli/validate.ts for the externalRefs / sarif-artifact
+        // declaration rationale.
+        const { runValidate } = await import("./validate.js");
+        const json = boolFlag('json');
+        const config = flag('config');
+        const context = flag('context');
+        const outputPath = flag('output');
+        const cliEngine = parseEngineCliFlag();
+        const code = await runUnderJsonMode({ command: 'validate', active: json }, () => runValidate({
+            ...(config !== undefined ? { configPath: config } : {}),
+            ...(context !== undefined ? { context } : {}),
+            ...(outputPath !== undefined ? { outputPath } : {}),
+            ...(cliEngine !== undefined ? { cliEngine } : {}),
+            envEngine: process.env.CLAUDE_AUTOPILOT_ENGINE,
+        }));
+        process.exit(code);
+        break;
+    }
+    case 'implement': {
+        // v6.0.7 — engine-wrap shell for the `implement` pipeline phase. The
+        // actual implement loop (read plan → dispatch subagents one per plan
+        // phase via `subagent-driven-development` → write code → run tests →
+        // commit → optionally push via `commit-push-pr`) lives in the Claude
+        // Code `claude-autopilot` skill; this verb provides a checkpointable
+        // phase shell so v6 pipeline runs can record an `implement` entry.
+        // Mirrors the plan / review / validate dispatcher shape. See the long
+        // deviation note in src/cli/implement.ts for the idempotent /
+        // hasSideEffects / git-remote-push declaration rationale.
+        const { runImplement } = await import("./implement.js");
+        const json = boolFlag('json');
+        const config = flag('config');
+        const context = flag('context');
+        const plan = flag('plan');
+        const outputPath = flag('output');
+        const cliEngine = parseEngineCliFlag();
+        const code = await runUnderJsonMode({ command: 'implement', active: json }, () => runImplement({
+            ...(config !== undefined ? { configPath: config } : {}),
+            ...(context !== undefined ? { context } : {}),
+            ...(plan !== undefined ? { plan } : {}),
+            ...(outputPath !== undefined ? { outputPath } : {}),
+            ...(cliEngine !== undefined ? { cliEngine } : {}),
+            envEngine: process.env.CLAUDE_AUTOPILOT_ENGINE,
+        }));
         process.exit(code);
         break;
     }
+    case 'autopilot': {
+        // v6.2.0 — multi-phase orchestrator. One runId across all phases.
+        // Engine-on REQUIRED (rejected at pre-flight if --no-engine / env=off
+        // / config=false). v6.2.0 ships --mode=full (scan → spec → plan →
+        // implement); v6.2.1 extends to scan → spec → plan → implement →
+        // migrate → pr; v6.2.2 adds the `--json` outer envelope.
+        const { runAutopilot, runAutopilotWithJsonEnvelope } = await import("./autopilot.js");
+        const json = boolFlag('json');
+        const modeArg = flag('mode');
+        if (modeArg !== undefined && modeArg !== 'full') {
+            // In --json mode emit the spec envelope instead of stderr text so
+            // CI consumers get a deterministic shape even on this synchronous
+            // pre-run validation failure.
+            if (json) {
+                const { writeAutopilotEnvelope } = await import("./json-envelope.js");
+                writeAutopilotEnvelope({
+                    runId: null,
+                    status: 'failed',
+                    exitCode: 1,
+                    phases: [],
+                    totalCostUSD: 0,
+                    durationMs: 0,
+                    errorCode: 'invalid_config',
+                    errorMessage: `--mode "${modeArg}" not supported (use --mode=full)`,
+                });
+                process.exit(1);
+            }
+            console.error(`\x1b[31m[claude-autopilot] invalid_config: --mode "${modeArg}" not supported (use --mode=full)\x1b[0m`);
+            console.error(`\x1b[2m  --mode=fix and --mode=review land in v6.2.x+; use --phases=<csv> for custom lists\x1b[0m`);
+            process.exit(1);
+        }
+        const phasesArg = flag('phases');
+        const phases = phasesArg
+            ? phasesArg.split(',').map(s => s.trim()).filter(s => s.length > 0)
+            : undefined;
+        const budgetRaw = flag('budget');
+        let budgetUSD;
+        if (budgetRaw !== undefined) {
+            const parsed = Number.parseFloat(budgetRaw);
+            if (!Number.isFinite(parsed) || parsed <= 0) {
+                if (json) {
+                    const { writeAutopilotEnvelope } = await import("./json-envelope.js");
+                    writeAutopilotEnvelope({
+                        runId: null,
+                        status: 'failed',
+                        exitCode: 1,
+                        phases: [],
+                        totalCostUSD: 0,
+                        durationMs: 0,
+                        errorCode: 'invalid_config',
+                        errorMessage: `--budget must be a positive number, got "${budgetRaw}"`,
+                    });
+                    process.exit(1);
+                }
+                console.error(`\x1b[31m[claude-autopilot] invalid_config: --budget must be a positive number, got "${budgetRaw}"\x1b[0m`);
+                process.exit(1);
+            }
+            budgetUSD = parsed;
+        }
+        const cliEngine = parseEngineCliFlag();
+        if (json) {
+            const exitCode = await runAutopilotWithJsonEnvelope({
+                cwd: process.cwd(),
+                mode: 'full',
+                ...(phases !== undefined ? { phases } : {}),
+                ...(budgetUSD !== undefined ? { budgetUSD } : {}),
+                ...(cliEngine !== undefined ? { cliEngine } : {}),
+                envEngine: process.env.CLAUDE_AUTOPILOT_ENGINE,
+            });
+            process.exit(exitCode);
+        }
+        const result = await runAutopilot({
+            cwd: process.cwd(),
+            mode: 'full',
+            ...(phases !== undefined ? { phases } : {}),
+            ...(budgetUSD !== undefined ? { budgetUSD } : {}),
+            ...(cliEngine !== undefined ? { cliEngine } : {}),
+            envEngine: process.env.CLAUDE_AUTOPILOT_ENGINE,
+        });
+        process.exit(result.exitCode);
+        break;
+    }
     case 'report': {
         const outputPath = flag('output');
         const trend = boolFlag('trend');
-        const code = await runReport({ output: outputPath, trend });
+        const json = boolFlag('json');
+        const code = await runUnderJsonMode({ command: 'report', active: json }, () => runReport({ output: outputPath, trend }));
         process.exit(code);
         break;
     }
     case 'explain': {
         const config = flag('config');
+        const json = boolFlag('json');
         // Target is the first non-flag arg after 'explain'
         const target = args.slice(1).find(a => !a.startsWith('--'));
-        const code = await runExplain({ configPath: config, target });
+        const code = await runUnderJsonMode({ command: 'explain', active: json }, () => runExplain({ configPath: config, target }));
         process.exit(code);
         break;
     }
@@ -607,11 +877,17 @@ switch (subcommand) {
     case 'setup': {
         const force = args.includes('--force');
         const profileArg = flag('profile');
+        const json = boolFlag('json');
         if (profileArg && !['security-strict', 'team', 'solo'].includes(profileArg)) {
             console.error(`\x1b[31m[claude-autopilot] --profile must be "security-strict", "team", or "solo"\x1b[0m`);
             process.exit(1);
         }
-        await runSetup({ force, profile: profileArg });
+        const code = await runUnderJsonMode({ command: 'setup', active: json }, async () => {
+            await runSetup({ force, profile: profileArg });
+            return 0;
+        });
+        if (json)
+            process.exit(code);
         break;
     }
     case 'worker': {
@@ -627,28 +903,46 @@ switch (subcommand) {
         const contextFile = flag('context-file');
         const dryRun = boolFlag('dry-run');
         const noSynthesize = boolFlag('no-synthesize');
-        const code = await runCouncilCmd({
+        const json = boolFlag('json');
+        const code = await runUnderJsonMode({ command: 'council', active: json }, () => runCouncilCmd({
             prompt,
             contextFile,
             configPath: config,
             dryRun,
             noSynthesize,
-        });
+        }));
         process.exit(code);
         break;
     }
     case 'mcp': {
-        const { runMcp } = await import("./mcp.js");
+        let runMcp;
+        try {
+            ({ runMcp } = await import("./mcp.js"));
+        }
+        catch (err) {
+            const code = err.code;
+            const msg = err.message ?? String(err);
+            // The mcp module imports @modelcontextprotocol/sdk at the top — if the
+            // package was installed with --omit=optional the dynamic import surfaces
+            // ERR_MODULE_NOT_FOUND naming the SDK. Translate to a friendly hint.
+            if ((code === 'ERR_MODULE_NOT_FOUND' || code === 'MODULE_NOT_FOUND') && /modelcontextprotocol/.test(msg)) {
+                console.error('\x1b[31m[claude-autopilot] mcp subcommand requires @modelcontextprotocol/sdk\x1b[0m');
+                console.error('  install: npm install @modelcontextprotocol/sdk');
+                process.exit(1);
+            }
+            throw err;
+        }
         const configPath = flag('config');
         await runMcp({ cwd: process.cwd(), configPath });
         break;
     }
     case 'migrate-v4': {
-        const code = await runMigrateV4({
+        const json = boolFlag('json');
+        const code = await runUnderJsonMode({ command: 'migrate-v4', active: json }, () => runMigrateV4({
             cwd: flag('path') ?? process.cwd(),
             write: boolFlag('write'),
             undo: boolFlag('undo'),
-        });
+        }));
         process.exit(code);
         break;
     }
@@ -662,41 +956,49 @@ switch (subcommand) {
             break;
         }
         // Plain `migrate [--env <name>] [--dry-run] [--yes]` → dispatcher.
+        // v6.0.8: routed through `runMigrate` (src/cli/migrate.ts) which
+        // wraps the dispatcher in a `RunPhase<MigrateInput, MigrateOutput>`
+        // with `--engine` / `--no-engine` precedence. Engine-off is byte-for-
+        // byte identical to v6.0.7 — same dispatch shape, same render lines.
         const envName = flag('env') ?? 'dev';
         const dryRun = boolFlag('dry-run');
         const yesFlag = boolFlag('yes');
-        // Read package version for the runtime handshake.
-        const root = findPackageRoot(import.meta.url);
-        let runtimeVersion = 'unknown';
-        if (root) {
-            try {
-                const nodeFs = await import('node:fs');
-                const nodePath = await import('node:path');
-                const pkg = JSON.parse(nodeFs.readFileSync(nodePath.join(root, 'package.json'), 'utf8'));
-                runtimeVersion = pkg.version;
-            }
-            catch {
-                /* fall through with 'unknown' — handshake will fail closed */
-            }
-        }
-        const result = await runMigrateDispatch({
-            repoRoot: process.cwd(),
-            env: envName,
-            yesFlag,
-            nonInteractive: !process.stdin.isTTY,
-            currentRuntimeVersion: runtimeVersion,
-            dryRun,
+        const json = boolFlag('json');
+        const cliEngine = parseEngineCliFlag();
+        // Capture migrate result in an outer ref so the wrapper's payload
+        // callback can surface its structured fields in --json mode.
+        let migrateResult = null;
+        const code = await runUnderJsonMode({
+            command: 'migrate',
+            active: json,
+            payload: () => migrateResult ? {
+                migrate: {
+                    status: migrateResult.status,
+                    reasonCode: migrateResult.reasonCode,
+                    appliedMigrations: migrateResult.appliedMigrations,
+                    nextActions: migrateResult.nextActions,
+                },
+                ...(migrateResult.nextActions.length > 0 ? { nextActions: migrateResult.nextActions } : {}),
+            } : {},
+            statusFor: exit => {
+                if (!migrateResult)
+                    return exit === 0 ? 'pass' : 'fail';
+                return migrateResult.status === 'applied' || migrateResult.status === 'skipped' ? 'pass' : 'fail';
+            },
+        }, async () => {
+            const out = await runMigrate({
+                cwd: process.cwd(),
+                env: envName,
+                dryRun,
+                yesFlag,
+                nonInteractive: json || !process.stdin.isTTY,
+                ...(cliEngine !== undefined ? { cliEngine } : {}),
+                envEngine: process.env.CLAUDE_AUTOPILOT_ENGINE,
+            });
+            migrateResult = out.result;
+            return out.exitCode;
         });
-        const ok = result.status === 'applied' || result.status === 'skipped';
-        const color = ok ? '\x1b[32m' : '\x1b[31m';
-        console.log(`${color}[migrate] status=${result.status} reason=${result.reasonCode}\x1b[0m`);
-        if (result.appliedMigrations.length > 0) {
-            console.log(`  applied: ${result.appliedMigrations.join(', ')}`);
-        }
-        if (result.nextActions.length > 0) {
-            console.log(`  next: ${result.nextActions.join('; ')}`);
-        }
-        process.exit(ok ? 0 : 1);
+        process.exit(code);
         break;
     }
     case 'migrate-doctor': {
@@ -705,31 +1007,291 @@ switch (subcommand) {
         await runMigrateDoctorCLI();
         break;
     }
+    case 'deploy': {
+        const config = flag('config');
+        const adapterArg = flag('adapter');
+        // Keep this list in sync with `DeployConfig.adapter` in
+        // src/adapters/deploy/types.ts and the factory in
+        // src/adapters/deploy/index.ts.
+        const ADAPTER_NAMES = ['vercel', 'fly', 'render', 'generic'];
+        if (adapterArg && !ADAPTER_NAMES.includes(adapterArg)) {
+            console.error(`\x1b[31m[claude-autopilot] --adapter must be one of: ${ADAPTER_NAMES.join(', ')}\x1b[0m`);
+            process.exit(1);
+        }
+        // Phase 3 — `deploy rollback` and `deploy status` subverbs. The first
+        // non-flag positional after `deploy` selects the verb. The historic
+        // `claude-autopilot deploy` (no subverb) keeps calling runDeploy.
+        const subverb = args[1] && !args[1].startsWith('--') ? args[1] : undefined;
+        const json = boolFlag('json');
+        if (subverb === 'rollback') {
+            const to = flag('to');
+            const code = await runUnderJsonMode({ command: 'deploy rollback', active: json }, () => runDeployRollback({
+                configPath: config,
+                adapterOverride: adapterArg,
+                to,
+            }));
+            process.exit(code);
+        }
+        if (subverb === 'status') {
+            const code = await runUnderJsonMode({ command: 'deploy status', active: json }, () => runDeployStatus({
+                configPath: config,
+                adapterOverride: adapterArg,
+            }));
+            process.exit(code);
+        }
+        if (subverb !== undefined) {
+            console.error(`\x1b[31m[claude-autopilot] unknown deploy subverb "${subverb}" — valid: rollback, status\x1b[0m`);
+            process.exit(1);
+        }
+        const ref = flag('ref');
+        const commitSha = flag('sha');
+        const watch = boolFlag('watch');
+        const prRaw = flag('pr');
+        let prNum;
+        if (prRaw !== undefined) {
+            const n = parseInt(prRaw, 10);
+            if (Number.isNaN(n) || n <= 0) {
+                console.error(`\x1b[31m[claude-autopilot] --pr must be a positive integer, got "${prRaw}"\x1b[0m`);
+                process.exit(1);
+            }
+            prNum = n;
+        }
+        const code = await runUnderJsonMode({ command: 'deploy', active: json }, () => runDeploy({
+            configPath: config,
+            adapterOverride: adapterArg,
+            ref,
+            commitSha,
+            watch,
+            pr: prNum,
+        }));
+        process.exit(code);
+        break;
+    }
     case 'brainstorm': {
-        // `brainstorm` is the front of the pipeline and is implemented as a Claude
-        // Code skill (superpowers:brainstorming → autopilot), not a standalone CLI.
-        // The welcome screen advertises `claude-autopilot brainstorm "..."` as the
-        // primary quickstart, so users WILL land here. Give them clear instructions
-        // instead of a generic "Unknown subcommand" rejection. Only reference CLI
-        // subcommands that actually route (verified by the welcome regression test).
-        console.log(`
-\x1b[1m[brainstorm]\x1b[0m The pipeline entry point is a Claude Code skill, not a CLI subcommand.
-
-Invoke it from Claude Code:
-
-  \x1b[36m/brainstorm\x1b[0m                         Interactive spec writing
-  \x1b[36m/autopilot\x1b[0m                          Full pipeline from an approved spec
-  \x1b[36m/migrate\x1b[0m                            Database migration phase (stack-dependent)
-
-From the terminal, the CLI subset exposes only the individual review-phase subcommands:
-
-  \x1b[36mclaude-autopilot run --base main\x1b[0m    Just the review phase
-  \x1b[36mclaude-autopilot doctor\x1b[0m             Check prerequisites (incl. superpowers plugin)
-  \x1b[36mclaude-autopilot migrate-v4\x1b[0m         Codemod for v4 → v5 repo migration (not a pipeline phase)
-
-Full pipeline docs: https://github.com/axledbetter/claude-autopilot#the-pipeline-phase-by-phase
-`);
-        process.exit(0);
+        // v6.0.3 — `brainstorm` is wrapped through `runPhase`. Engine-off path
+        // is byte-for-byte identical to v6.0.2 (advisory print pointing at the
+        // Claude Code skill); engine-on path creates a run dir + emits
+        // run.start/phase.start/phase.success/run.complete events. See
+        // src/cli/brainstorm.ts for the deviation rationale on
+        // `idempotent: true` vs. the spec table's `idempotent: no`.
+        const { runBrainstorm } = await import("./brainstorm.js");
+        const json = boolFlag('json');
+        const config = flag('config');
+        const cliEngine = parseEngineCliFlag();
+        if (json) {
+            // --json mode: surface the resume hint via nextActions, not a banner.
+            // Mirror the v6.0.2 envelope shape so existing consumers (the
+            // json-channel-discipline test, MCP wrappers) don't break. The phase
+            // body itself runs in silent mode — engine-on still produces
+            // run-state artifacts; engine-off short-circuits to 0.
+            const code = await runUnderJsonMode({
+                command: 'brainstorm',
+                active: true,
+                payload: () => ({
+                    note: 'brainstorm is a Claude Code skill, not a CLI subcommand',
+                    nextActions: [
+                        'Invoke /brainstorm from Claude Code for interactive spec writing',
+                        'Then /autopilot to run the full pipeline from an approved spec',
+                    ],
+                }),
+            }, () => runBrainstorm({
+                ...(config !== undefined ? { configPath: config } : {}),
+                ...(cliEngine !== undefined ? { cliEngine } : {}),
+                envEngine: process.env.CLAUDE_AUTOPILOT_ENGINE,
+                __silent: true,
+            }));
+            process.exit(code);
+        }
+        const code = await runBrainstorm({
+            ...(config !== undefined ? { configPath: config } : {}),
+            ...(cliEngine !== undefined ? { cliEngine } : {}),
+            envEngine: process.env.CLAUDE_AUTOPILOT_ENGINE,
+        });
+        process.exit(code);
+        break;
+    }
+    case 'spec': {
+        // v6.0.3 — `spec` is wrapped through `runPhase`. Same shape as
+        // brainstorm: engine-off prints an advisory pointing at the Claude
+        // Code skill; engine-on creates a run dir + emits lifecycle events.
+        // Like brainstorm, the deviation from the spec table's
+        // `idempotent: no` is justified inline at the top of src/cli/spec.ts.
+        const { runSpec } = await import("./spec.js");
+        const json = boolFlag('json');
+        const config = flag('config');
+        const cliEngine = parseEngineCliFlag();
+        if (json) {
+            const code = await runUnderJsonMode({
+                command: 'spec',
+                active: true,
+                payload: () => ({
+                    note: 'spec is a Claude Code skill, not a CLI subcommand',
+                    nextActions: [
+                        'Approve a brainstorm output, then invoke /autopilot from Claude Code',
+                        'The autopilot skill writes the implementation plan + executes the pipeline',
+                    ],
+                }),
+            }, () => runSpec({
+                ...(config !== undefined ? { configPath: config } : {}),
+                ...(cliEngine !== undefined ? { cliEngine } : {}),
+                envEngine: process.env.CLAUDE_AUTOPILOT_ENGINE,
+                __silent: true,
+            }));
+            process.exit(code);
+        }
+        const code = await runSpec({
+            ...(config !== undefined ? { configPath: config } : {}),
+            ...(cliEngine !== undefined ? { cliEngine } : {}),
+            envEngine: process.env.CLAUDE_AUTOPILOT_ENGINE,
+        });
+        process.exit(code);
+        break;
+    }
+    case 'runs': {
+        // v6 Phase 3 — umbrella verb. Sub-verbs: list, show, gc, delete, doctor.
+        const sub = args[1];
+        const json = boolFlag('json');
+        const cwd = process.cwd();
+        if (!sub || sub === '--help' || sub === '-h' || sub === 'help') {
+            const focused = (await import("./help-text.js")).buildCommandHelpText('runs');
+            process.stdout.write(focused ?? buildHelpText());
+            process.exit(0);
+        }
+        const { runRunsList, runRunsShow, runRunsGc, runRunsDelete, runRunsDoctor, } = await import("./runs.js");
+        let result;
+        switch (sub) {
+            case 'list': {
+                result = await runRunsList({ cwd, status: flag('status'), json });
+                break;
+            }
+            case 'show': {
+                const events = boolFlag('events');
+                const tailRaw = flag('events-tail');
+                const eventsTail = tailRaw ? parseInt(tailRaw, 10) : undefined;
+                // Filter out value-flag *values* — without this, `runs show
+                // --events-tail 5 <ULID>` would resolve runId to '5'. Same pattern
+                // as the scan case above. Caught by Cursor Bugbot on PR #88
+                // (MEDIUM).
+                const runId = args.slice(2).find(a => !a.startsWith('--') && a !== tailRaw);
+                result = await runRunsShow({
+                    runId: runId ?? '',
+                    cwd,
+                    events,
+                    ...(eventsTail !== undefined ? { eventsTail } : {}),
+                    json,
+                });
+                break;
+            }
+            case 'gc': {
+                const dryRun = boolFlag('dry-run');
+                const yes = boolFlag('yes');
+                const olderRaw = flag('older-than-days');
+                const olderThanDays = olderRaw ? parseInt(olderRaw, 10) : undefined;
+                result = await runRunsGc({
+                    cwd,
+                    dryRun,
+                    yes,
+                    ...(olderThanDays !== undefined ? { olderThanDays } : {}),
+                    json,
+                });
+                break;
+            }
+            case 'delete': {
+                const runId = args.slice(2).find(a => !a.startsWith('--'));
+                const force = boolFlag('force');
+                result = await runRunsDelete({ runId: runId ?? '', cwd, force, json });
+                break;
+            }
+            case 'doctor': {
+                const runId = args.slice(2).find(a => !a.startsWith('--'));
+                const fix = boolFlag('fix');
+                result = await runRunsDoctor({
+                    cwd,
+                    ...(runId ? { runId } : {}),
+                    fix,
+                    json,
+                });
+                break;
+            }
+            case 'watch': {
+                // v6.1 — `runs watch <id>` tails events.ndjson with a live cost meter.
+                // The other umbrella verbs use a unified `RunsCliResult` shape so the
+                // dispatcher can treat them uniformly; `runs-watch.ts` returns the
+                // same shape.
+                const sinceRaw = flag('since');
+                const since = sinceRaw !== undefined ? parseInt(sinceRaw, 10) : undefined;
+                if (sinceRaw !== undefined && (Number.isNaN(since) || since < 0)) {
+                    process.stderr.write(`\x1b[31m[claude-autopilot] --since must be a non-negative integer\x1b[0m\n`);
+                    process.exit(1);
+                }
+                const noFollow = boolFlag('no-follow');
+                const noColor = boolFlag('no-color');
+                // Filter the value-flag value out of the positional lookup —
+                // matches the same defensive pattern used in `runs show` (Bugbot
+                // PR #88 MEDIUM). Without this, `runs watch --since 5 <ULID>`
+                // would resolve runId to "5".
+                const runId = args.slice(2).find(a => !a.startsWith('--') && a !== sinceRaw);
+                const { runRunsWatch } = await import("./runs-watch.js");
+                result = await runRunsWatch({
+                    runId: runId ?? '',
+                    cwd,
+                    ...(since !== undefined ? { since } : {}),
+                    noFollow,
+                    json,
+                    noColor,
+                });
+                break;
+            }
+            default: {
+                process.stderr.write(`\x1b[31m[claude-autopilot] runs: unknown sub-verb "${sub}" — valid: list, show, gc, delete, doctor, watch\x1b[0m\n`);
+                process.exit(1);
+            }
+        }
+        for (const line of result.stdout)
+            process.stdout.write(line.endsWith('\n') ? line : `${line}\n`);
+        for (const line of result.stderr)
+            process.stderr.write(line.endsWith('\n') ? line : `${line}\n`);
+        process.exit(result.exit);
+        break;
+    }
+    case 'run-resume': {
+        // v6 Phase 3 — `run resume <id>`. Lookup-only: identifies the next phase
+        // and decision rationale. Actual phase execution wires in Phase 6+.
+        // The synthetic 'run-resume' subcommand was set above by the
+        // disambiguation block; args[0]==='run', args[1]==='resume', args[2] is
+        // optional run id.
+        const json = boolFlag('json');
+        const fromPhase = flag('from-phase') ?? flag('from');
+        // Filter value-flag values out of positional lookup — see same comment
+        // in the `runs show` case above. (Bugbot MEDIUM, PR #88.)
+        const runId = args.slice(2).find(a => !a.startsWith('--') && a !== fromPhase);
+        const { runRunResume } = await import("./runs.js");
+        const result = await runRunResume({
+            runId: runId ?? '',
+            cwd: process.cwd(),
+            ...(fromPhase ? { fromPhase } : {}),
+            json,
+        });
+        for (const line of result.stdout)
+            process.stdout.write(line.endsWith('\n') ? line : `${line}\n`);
+        for (const line of result.stderr)
+            process.stderr.write(line.endsWith('\n') ? line : `${line}\n`);
+        process.exit(result.exit);
+        break;
+    }
+    case 'internal': {
+        // v6 Phase 2 — hidden verb. Markdown skills shell out to append typed
+        // events into a run's events.ndjson. NOT advertised in the main help.
+        const { runInternalCli } = await import("../core/run-state/cli-internal.js");
+        const result = await runInternalCli({
+            args: args.slice(1),
+            cwd: process.cwd(),
+        });
+        for (const line of result.stdout)
+            process.stdout.write(line.endsWith('\n') ? line : `${line}\n`);
+        for (const line of result.stderr)
+            process.stderr.write(line.endsWith('\n') ? line : `${line}\n`);
+        process.exit(result.exit);
         break;
     }
     default: