@jokerized/getresearchdone 0.4.1

package/dist/lib/autopilot.js

@@ -0,0 +1,1314 @@
+'use strict';
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs = require('fs');
+const path = require('path');
+const childProcess = require('child_process');
+const { loadConfig, findPhaseInternal, output, getMilestoneInfo, MODEL_PROFILES, resolveModelForAgent, } = require('./utils');
+const { detectBackend, getBackendCapabilities, getEffectiveTierForDispatch, } = require('./backend');
+const { isOntologyConverged, } = require('./drift');
+const { analyzeRoadmap, } = require('./roadmap');
+const { parseLongTermRoadmap, } = require('./long-term-roadmap');
+const { createScheduler, resolveAccount, } = require('./scheduler');
+const { slingPlanAsync, loadOverstoryConfig, generateOverlay, } = require('./overstory');
+const { worktreePath: getWorktreePath, worktreeBranch: getWorktreeBranch, ensureWorktreesDir, } = require('./worktree');
+const { execGit, } = require('./utils');
+const { buildKnowledgeInjectionBlock, } = require('./knowledge');
+const { createMergeQueue, parseWriteIntent, compareWriteIntent, formatWriteIntentMismatch, buildWaves, buildWavesFromPlans, } = require('./autopilot-waves');
+const { isMilestoneComplete, resolveNextMilestone, buildNewMilestonePrompt, buildMilestoneCompletePrompt, } = require('./autopilot-milestone');
+const { selectCandidate, } = require('./commands/select-candidate');
+const { toSpawnResult, spawnClaude, spawnClaudeAsync, writeStatusMarker, updateStateProgress, buildSimplifyPrompt, buildCodeReviewPrompt, buildConflictResolvePrompt, buildKnowledgeMiningPrompt, buildCritiqueAgentPrompt, runKnowledgeMining, runRefinementLoop, runPostPhasePipeline, finalizePhaseAfterPipeline, } = require('./autopilot-pipeline');
+// ─── Default Constants ──────────────────────────────────────────────────────
+const DEFAULT_TIMEOUT_MINUTES = 120;
+const HEARTBEAT_INTERVAL_MS = 30000;
+/**
+ * Codex r44 P1 #6: invoke handleSpinEvent when the scheduler detected a
+ * spinning subprocess. `spawnStep` (lib/autopilot-pipeline.ts) already
+ * does this for post-pipeline steps, but the main autopilot plan and
+ * execute calls go through `scheduler.spawn` directly and previously
+ * dropped the event. Helper de-duplicates the wiring so every direct
+ * scheduler.spawn caller surfaces SPIN-REPORT.md.
+ */
+function _handleSpinIfDetected(cwd, phaseNum, result) {
+    if (!result.spinEvent || !result.spinEvent.detected)
+        return;
+    try {
+        const info = findPhaseInternal(cwd, phaseNum);
+        const phaseDir = info && info.found ? require('path').join(cwd, info.directory) : cwd;
+        handleSpinEvent(phaseDir, result.spinEvent, `phase-${phaseNum}`);
+    }
+    catch {
+        /* spin handling is best-effort */
+    }
+}
+// ─── Scheduler State Helpers ────────────────────────────────────────────────
+/**
+ * Build a states map from the scheduler for use with resolveAccount().
+ * Enumerates all configured account state keys and queries the scheduler
+ * for each, collecting only those that exist.
+ */
+function _getSchedulerStates(scheduler, schedulerConfig, superpowersConfig) {
+    const states = new Map();
+    const accounts = superpowersConfig.accounts;
+    const allBackends = new Set([
+        ...schedulerConfig.backend_priority,
+        schedulerConfig.free_fallback.backend,
+    ]);
+    for (const backend of allBackends) {
+        const backendAccounts = accounts[backend];
+        if (!backendAccounts || backendAccounts.length === 0)
+            continue;
+        for (const account of backendAccounts) {
+            const stateKey = `${backend}/${account.config_dir}`;
+            const state = scheduler.getState(stateKey);
+            if (state) {
+                states.set(stateKey, state);
+            }
+        }
+    }
+    // Also check the fallback backend with no config_dir
+    const fallbackState = scheduler.getState(schedulerConfig.free_fallback.backend);
+    if (fallbackState) {
+        states.set(schedulerConfig.free_fallback.backend, fallbackState);
+    }
+    // Check default_backend with no config_dir
+    const defaultBackend = superpowersConfig.default_backend;
+    const defaultState = scheduler.getState(defaultBackend);
+    if (defaultState) {
+        states.set(defaultBackend, defaultState);
+    }
+    return states;
+}
+// ─── Pure Helper Functions ──────────────────────────────────────────────────
+/**
+ * Resolve the range of phases to process from ROADMAP.md.
+ */
+function resolvePhaseRange(cwd, from, to) {
+    const analysis = analyzeRoadmap(cwd);
+    if (analysis.error) {
+        return { phases: [], error: analysis.error };
+    }
+    let phases = analysis.phases;
+    if (!phases || phases.length === 0) {
+        return { phases: [], error: 'No phases found in ROADMAP.md' };
+    }
+    // Filter to range
+    if (from) {
+        const fromNum = parseFloat(from);
+        phases = phases.filter((p) => parseFloat(p.number) >= fromNum);
+    }
+    if (to) {
+        const toNum = parseFloat(to);
+        phases = phases.filter((p) => parseFloat(p.number) <= toNum);
+    }
+    if (phases.length === 0) {
+        return { phases: [], error: `No phases found in range ${from || 'start'}..${to || 'end'}` };
+    }
+    return {
+        phases: phases.map((p) => ({
+            number: p.number,
+            name: p.name,
+            disk_status: p.disk_status || 'unknown',
+            depends_on: p.depends_on,
+        })),
+        error: null,
+    };
+}
+/**
+ * Check if a phase has been planned (used for auto-resume skip logic).
+ */
+function isPhasePlanned(cwd, phaseNum) {
+    const info = findPhaseInternal(cwd, phaseNum);
+    if (!info)
+        return false;
+    return info.plans.length > 0;
+}
+/**
+ * Check if a phase has been fully executed (used for auto-resume skip logic).
+ */
+function isPhaseExecuted(cwd, phaseNum) {
+    const info = findPhaseInternal(cwd, phaseNum);
+    if (!info)
+        return false;
+    return info.plans.length > 0 && info.incomplete_plans.length === 0;
+}
+/**
+ * v0.4 Phase 2 gate: detect when a phase has multiple PLAN candidates
+ * (PLAN-1.md ... PLAN-N.md) instead of a single resolved PLAN.md.
+ *
+ * Multi-candidate phases are NOT yet runnable by execute-phase — Phase 3's
+ * deterministic selector picks one and renames it to PLAN.md before
+ * execution can proceed. Until Phase 3 lands, this gate logs and skips
+ * execution; an operator must select manually.
+ */
+function hasMultipleCandidates(cwd, phaseNum) {
+    const info = findPhaseInternal(cwd, phaseNum);
+    if (!info)
+        return false;
+    // Phase has PLAN-N.md candidates AND no resolved bare PLAN.md.
+    const candidateRe = /^PLAN-\d+\.md$/;
+    let candidateCount = 0;
+    let hasResolvedPlan = false;
+    for (const filename of info.plans) {
+        if (candidateRe.test(filename))
+            candidateCount++;
+        if (filename === 'PLAN.md')
+            hasResolvedPlan = true;
+    }
+    return candidateCount >= 2 && !hasResolvedPlan;
+}
+/**
+ * Prepend "ultrathink" keyword when the backend supports the effort capability.
+ */
+function withUltrathink(prompt, backend) {
+    if (backend && getBackendCapabilities(backend).effort) {
+        return `ultrathink\n\n${prompt}`;
+    }
+    return prompt;
+}
+/**
+ * Build the prompt for planning a phase via `claude -p`.
+ */
+function buildPlanPrompt(phaseNum, backend, cwd) {
+    const basePrompt = `Use the Skill tool to invoke skill "grd:plan-phase" with args "${phaseNum}" (i.e. plan-phase ${phaseNum}). Autonomous mode — make all decisions yourself, no questions. Complete all planning steps and write the PLAN.md files. Ensure each PLAN.md includes a \`files_modified:\` field in its YAML frontmatter listing the lib/ modules and other files the plan expects to modify. Each PLAN.md MUST also include \`provides: []\`, \`requires: []\`, and \`integration_points: []\` in YAML frontmatter. \`provides\` lists artifact identifiers this plan creates (format: "module:ExportName", e.g., "lib/deps.ts:buildArtifactDAG"). \`requires\` lists artifacts from other plans that must exist before this plan executes. \`integration_points\` lists artifacts this plan connects to but does not strictly depend on.`;
+    const knowhowBlock = cwd ? buildKnowledgeInjectionBlock(cwd, phaseNum) : '';
+    return withUltrathink(knowhowBlock ? `${knowhowBlock}\n\n${basePrompt}` : basePrompt, backend);
+}
+/**
+ * Build the prompt for executing a phase via `claude -p`.
+ */
+function buildExecutePrompt(phaseNum, cwd) {
+    const basePrompt = `Use the Skill tool to invoke skill "grd:execute-phase" with args "${phaseNum}" (i.e. execute-phase ${phaseNum}). Autonomous mode — make all decisions yourself, no questions. After execution, merge locally. Do not push.`;
+    const knowhowBlock = cwd ? buildKnowledgeInjectionBlock(cwd, phaseNum) : '';
+    return knowhowBlock ? `${knowhowBlock}\n\n${basePrompt}` : basePrompt;
+}
+/** Wireup discovery after milestone completion. */
+function buildWireupPrompt() {
+    return 'Use the Skill tool to invoke skill "grd:wireup" with no additional args. Autonomous mode — make all decisions yourself, no questions. Run wireup discovery (exported-but-uncalled, config-without-surface, endpoint-without-integration-test) and fix any findings.';
+}
+// ─── Main Loop ──────────────────────────────────────────────────────────────
+/**
+ * Run the autopilot loop over a range of phases, grouped by dependency waves.
+ * Independent phases are planned in parallel; execution is always sequential.
+ */
+async function runAutopilot(cwd, options = {}) {
+    const { phaseFrom = null, phaseTo = null, dryRun = false, skipPlan = false, skipExecute = false, skipPostPipeline = false, timeout, maxTurns, model, } = options;
+    const { phases, error: rangeError } = resolvePhaseRange(cwd, phaseFrom, phaseTo);
+    if (rangeError) {
+        return {
+            phases_attempted: 0,
+            phases_completed: 0,
+            stopped_at: rangeError,
+            converged_at: null,
+            waves: [],
+            results: [],
+        };
+    }
+    const waves = buildWaves(phases);
+    const timeoutMs = timeout ? timeout * 60 * 1000 : undefined;
+    const results = [];
+    let phasesAttempted = 0;
+    let phasesCompleted = 0;
+    let stoppedAt = null;
+    // Graceful early termination (Tier-3 #10). Separate from stoppedAt so
+    // existing callers (multi-milestone autopilot, evolve) do not classify
+    // convergence as a failure. codex r2 P2 on PR #40.
+    let convergedAt = null;
+    const config = loadConfig(cwd);
+    const backend = detectBackend(cwd);
+    const scheduler = createScheduler(config.scheduler, config.superpowers);
+    if (scheduler) {
+        scheduler.loadPersistedState(path.join(cwd, '.planning'));
+    }
+    // autopilot.log is project-scoped (.planning/autopilot/).
+    // Cross-project scheduler state (e.g., global phase timing stats,
+    // retry policies) could use CLAUDE_PLUGIN_DATA when available:
+    //   const globalSchedulerDir = process.env.CLAUDE_PLUGIN_DATA
+    //     ? path.join(process.env.CLAUDE_PLUGIN_DATA, 'grd', 'scheduler')
+    //     : null;
+    const logFile = path.join(cwd, '.planning', 'autopilot', 'autopilot.log');
+    fs.mkdirSync(path.dirname(logFile), { recursive: true });
+    const log = (msg) => {
+        const line = `[${new Date().toISOString()}] ${msg}\n`;
+        process.stderr.write(`[autopilot] ${msg}\n`);
+        fs.appendFileSync(logFile, line);
+    };
+    log(`Starting autopilot: ${phases.length} phase(s) in ${waves.length} wave(s)`);
+    // Single merge queue shared across all waves — only the rebase+merge step
+    // is serialized; simplify/PR/review steps run concurrently per phase.
+    const mergeQueue = createMergeQueue();
+    for (let waveIdx = 0; waveIdx < waves.length; waveIdx++) {
+        const wave = waves[waveIdx];
+        if (stoppedAt || convergedAt)
+            break;
+        log(`Wave ${waveIdx + 1}/${waves.length}: phases [${wave.join(', ')}]`);
+        // ── Plan step: all phases in wave in parallel ──
+        if (!skipPlan) {
+            const planTasks = [];
+            for (const phaseNum of wave) {
+                phasesAttempted++;
+                if (isPhasePlanned(cwd, phaseNum)) {
+                    results.push({
+                        phase: phaseNum,
+                        step: 'plan',
+                        status: 'skipped',
+                        reason: 'already planned',
+                    });
+                    planTasks.push({ phaseNum, skipped: true });
+                }
+                else if (dryRun) {
+                    results.push({
+                        phase: phaseNum,
+                        step: 'plan',
+                        status: 'dry-run',
+                        prompt: buildPlanPrompt(phaseNum, backend, cwd),
+                    });
+                    planTasks.push({ phaseNum, skipped: true });
+                }
+                else {
+                    log(`Phase ${phaseNum}: planning...`);
+                    writeStatusMarker(cwd, phaseNum, 'plan', 'started');
+                    updateStateProgress(cwd, phaseNum, 'planning');
+                    // Compute the plan prompt once so we can pass it to both the adaptive
+                    // tier helper (for promptLength) and the actual dispatch.
+                    const planPrompt = buildPlanPrompt(phaseNum, backend, cwd);
+                    // Resolve the effective model for this dispatch. When the caller
+                    // passed an explicit --model flag we honour it; otherwise the Spec 4
+                    // chain (complexity → pressure → tier) picks the right model.
+                    const planTier = getEffectiveTierForDispatch({
+                        agentType: 'grd-planner',
+                        prompt: planPrompt,
+                        config,
+                        scheduler,
+                        schedulerConfig: config.scheduler,
+                        superpowersConfig: config.superpowers,
+                        modelProfiles: MODEL_PROFILES,
+                    });
+                    const planModel = model
+                        ? model
+                        : resolveModelForAgent(config, 'grd-planner', cwd, {
+                            effectiveTierOverride: planTier,
+                        });
+                    // Check for overstory sling path: parallel wave + account rotation + native worktree isolation
+                    let promise;
+                    if (config.superpowers?.account_rotation && scheduler && config.scheduler) {
+                        const resolution = resolveAccount(config.superpowers, config.scheduler, _getSchedulerStates(scheduler, config.scheduler, config.superpowers), config.scheduler.prediction.safety_margin_tasks);
+                        const caps = getBackendCapabilities(resolution.backend);
+                        if (caps.native_worktree_isolation) {
+                            // Overstory sling path: bypass scheduler.spawn() for parallel wave planning
+                            const ovConfig = loadOverstoryConfig(cwd);
+                            const milestoneInfo = getMilestoneInfo(cwd);
+                            const phaseInfo = findPhaseInternal(cwd, phaseNum);
+                            const phaseDir = phaseInfo?.directory ||
+                                path.join(cwd, '.planning', 'milestones', milestoneInfo.version, 'phases', `phase-${phaseNum}`);
+                            const planId = `phase-${phaseNum}-plan`;
+                            const overlayContent = generateOverlay(planPrompt, {
+                                phase_number: phaseNum,
+                                plan_id: planId,
+                                milestone: milestoneInfo.version,
+                                phase_dir: phaseDir,
+                            });
+                            const overlayDir = path.join(cwd, '.planning', 'autopilot', 'overlays');
+                            fs.mkdirSync(overlayDir, { recursive: true });
+                            const overlayPath = path.join(overlayDir, `overlay-${phaseNum}.md`);
+                            fs.writeFileSync(overlayPath, overlayContent);
+                            const slingOpts = {
+                                plan_path: phaseDir,
+                                overlay_path: overlayPath,
+                                runtime: ovConfig.runtime,
+                                model: planModel || 'default',
+                                phase_number: phaseNum,
+                                plan_id: planId,
+                                milestone: milestoneInfo.version,
+                                timeout_minutes: timeout || DEFAULT_TIMEOUT_MINUTES,
+                            };
+                            log(`Phase ${phaseNum}: using overstory sling path (backend: ${resolution.backend})`);
+                            promise = slingPlanAsync(cwd, slingOpts, ovConfig.poll_interval_ms, ovConfig.merge_strategy).then((slingResult) => {
+                                // Record the sample back to the scheduler
+                                const sample = {
+                                    backend: resolution.backend,
+                                    stateKey: resolution.stateKey,
+                                    timestamp: Date.now(),
+                                    duration: slingResult.duration,
+                                    tokenEstimate: Math.round(slingResult.duration * 10), // fallback estimate
+                                    exitCode: slingResult.exitCode,
+                                    workItemId: `phase-${phaseNum}-plan`,
+                                };
+                                scheduler.recordExternalSample(resolution.stateKey, sample);
+                                return { exitCode: slingResult.exitCode, timedOut: false };
+                            });
+                        }
+                        else {
+                            // Non-overstory backend with account rotation: use scheduler.spawn
+                            promise = scheduler
+                                .spawn(planPrompt, {
+                                timeout: timeoutMs,
+                                maxTurns,
+                                model: planModel,
+                                cwd,
+                                workItemId: `phase-${phaseNum}-plan`,
+                                agentType: 'grd-planner',
+                            })
+                                .then((sr) => {
+                                _handleSpinIfDetected(cwd, phaseNum, sr);
+                                return toSpawnResult(sr);
+                            });
+                        }
+                    }
+                    else {
+                        promise = scheduler
+                            ? scheduler
+                                .spawn(planPrompt, {
+                                timeout: timeoutMs,
+                                maxTurns,
+                                model: planModel,
+                                cwd,
+                                workItemId: `phase-${phaseNum}-plan`,
+                                agentType: 'grd-planner',
+                            })
+                                .then((sr) => {
+                                _handleSpinIfDetected(cwd, phaseNum, sr);
+                                return toSpawnResult(sr);
+                            })
+                            : spawnClaudeAsync(cwd, planPrompt, {
+                                timeout: timeoutMs,
+                                maxTurns,
+                                model: planModel,
+                            });
+                    }
+                    planTasks.push({ phaseNum, skipped: false, promise });
+                }
+            }
+            // Await all parallel plan spawns
+            for (const task of planTasks) {
+                if (task.skipped)
+                    continue;
+                const planResult = await task.promise;
+                if (planResult.exitCode !== 0) {
+                    const reason = planResult.timedOut
+                        ? 'timeout'
+                        : `exit code ${planResult.exitCode}`;
+                    log(`Phase ${task.phaseNum}: plan FAILED (${reason})`);
+                    writeStatusMarker(cwd, task.phaseNum, 'plan', 'failed');
+                    results.push({ phase: task.phaseNum, step: 'plan', status: 'failed', reason });
+                    stoppedAt = `Phase ${task.phaseNum} plan failed: ${reason}`;
+                    continue;
+                }
+                log(`Phase ${task.phaseNum}: plan completed`);
+                writeStatusMarker(cwd, task.phaseNum, 'plan', 'completed');
+                results.push({ phase: task.phaseNum, step: 'plan', status: 'completed' });
+            }
+            if (stoppedAt)
+                break;
+            // If skipExecute, count only planned phases (not yet counted above for non-skipPlan path)
+            if (skipExecute) {
+                phasesCompleted += wave.length;
+                continue;
+            }
+        }
+        else {
+            // skipPlan: still need to count attempts
+            phasesAttempted += wave.length;
+            if (skipExecute) {
+                phasesCompleted += wave.length;
+                continue;
+            }
+        }
+        // ── Execute step: parallel within wave using worktrees ──
+        // Track which phases failed planning so we skip them during execution
+        const failedPlanPhases = new Set(results.filter((r) => r.step === 'plan' && r.status === 'failed').map((r) => r.phase));
+        if (!skipExecute) {
+            const milestoneInfo = getMilestoneInfo(cwd);
+            ensureWorktreesDir(cwd);
+            // Build execution tasks for all phases in the wave
+            const execTasks = [];
+            for (const phaseNum of wave) {
+                if (failedPlanPhases.has(phaseNum)) {
+                    log(`Phase ${phaseNum}: skipping execution (planning failed)`);
+                    results.push({
+                        phase: phaseNum,
+                        step: 'execute',
+                        status: 'skipped',
+                        reason: 'planning failed',
+                    });
+                    execTasks.push({ phaseNum, skipped: true });
+                    continue;
+                }
+                if (isPhaseExecuted(cwd, phaseNum)) {
+                    results.push({
+                        phase: phaseNum,
+                        step: 'execute',
+                        status: 'skipped',
+                        reason: 'already executed',
+                    });
+                    execTasks.push({ phaseNum, skipped: true });
+                    continue;
+                }
+                // v0.4 Phase 3: when multiple PLAN candidates exist and none has been
+                // promoted to PLAN.md yet, run the deterministic selector. It scores
+                // each candidate, hard-fails DEAD-ENDS violators, picks the highest
+                // survivor, promotes it to PLAN.md, and writes PLAN-SELECTION.json.
+                if (hasMultipleCandidates(cwd, phaseNum)) {
+                    if (dryRun) {
+                        log(`Phase ${phaseNum}: [dry-run] would run deterministic selector over candidates`);
+                    }
+                    else {
+                        const selection = selectCandidate(cwd, phaseNum);
+                        if (!selection.winner) {
+                            log(`Phase ${phaseNum}: all PLAN candidates hard-failed DEAD-ENDS checks — cannot select`);
+                            failedPlanPhases.add(phaseNum);
+                            results.push({
+                                phase: phaseNum,
+                                step: 'execute',
+                                status: 'skipped',
+                                reason: 'all candidates hard-failed DEAD-ENDS; no viable plan to execute',
+                            });
+                            execTasks.push({ phaseNum, skipped: true });
+                            continue;
+                        }
+                        log(`Phase ${phaseNum}: selected ${selection.winner.relPath} (score ${selection.winner.total_score.toFixed(3)}) → promoted to PLAN.md`);
+                    }
+                }
+                if (dryRun) {
+                    results.push({
+                        phase: phaseNum,
+                        step: 'execute',
+                        status: 'dry-run',
+                        prompt: buildExecutePrompt(phaseNum, cwd),
+                    });
+                    execTasks.push({ phaseNum, skipped: true });
+                    continue;
+                }
+                // Create worktree for this phase
+                const wtPath = getWorktreePath(cwd, milestoneInfo.version, phaseNum);
+                const branch = getWorktreeBranch(cwd, milestoneInfo.version, phaseNum, phaseNum);
+                // Remove stale worktree if it exists
+                // Remove stale worktree if present (no existence check — idempotent)
+                execGit(cwd, ['worktree', 'remove', wtPath, '--force'], { allowBlocked: true });
+                execGit(cwd, ['worktree', 'prune']);
+                // Remove stale branch if it exists
+                execGit(cwd, ['branch', '-D', branch]);
+                const wtResult = execGit(cwd, ['worktree', 'add', '-b', branch, wtPath]);
+                if (wtResult.exitCode !== 0) {
+                    log(`Phase ${phaseNum}: failed to create worktree: ${wtResult.stderr}`);
+                    results.push({
+                        phase: phaseNum,
+                        step: 'execute',
+                        status: 'failed',
+                        reason: `worktree creation failed: ${wtResult.stderr}`,
+                    });
+                    execTasks.push({ phaseNum, skipped: true });
+                    continue;
+                }
+                log(`Phase ${phaseNum}: executing in worktree ${wtPath}...`);
+                writeStatusMarker(cwd, phaseNum, 'execute', 'started');
+                updateStateProgress(cwd, phaseNum, 'executing');
+                // Compute execute prompt once to share between tier computation and dispatch.
+                const executePrompt = buildExecutePrompt(phaseNum, wtPath);
+                // Resolve effective model for execution dispatch via the Spec 4 chain.
+                const executeTier = getEffectiveTierForDispatch({
+                    agentType: 'grd-executor',
+                    prompt: executePrompt,
+                    config,
+                    scheduler,
+                    schedulerConfig: config.scheduler,
+                    superpowersConfig: config.superpowers,
+                    modelProfiles: MODEL_PROFILES,
+                });
+                const executeModel = model
+                    ? model
+                    : resolveModelForAgent(config, 'grd-executor', cwd, {
+                        effectiveTierOverride: executeTier,
+                    });
+                const promise = (async () => {
+                    let execResult;
+                    if (scheduler) {
+                        const sr = await scheduler.spawn(executePrompt, {
+                            timeout: timeoutMs,
+                            maxTurns,
+                            model: executeModel,
+                            cwd: wtPath,
+                            workItemId: `phase-${phaseNum}-execute`,
+                            agentType: 'grd-executor',
+                        });
+                        _handleSpinIfDetected(cwd, phaseNum, sr);
+                        execResult = toSpawnResult(sr);
+                    }
+                    else {
+                        execResult = await spawnClaudeAsync(wtPath, executePrompt, {
+                            timeout: timeoutMs,
+                            maxTurns,
+                            model: executeModel,
+                        });
+                    }
+                    return { execResult, wtPath };
+                })();
+                execTasks.push({ phaseNum, skipped: false, promise, wtPath });
+            }
+            // Await all parallel execution spawns and collect successful phases for pipelines
+            const pipelineTasks = [];
+            for (const task of execTasks) {
+                if (task.skipped)
+                    continue;
+                const { execResult, wtPath } = await task.promise;
+                if (execResult.exitCode !== 0) {
+                    const reason = execResult.timedOut
+                        ? 'timeout'
+                        : `exit code ${execResult.exitCode}`;
+                    log(`Phase ${task.phaseNum}: execute FAILED (${reason})`);
+                    writeStatusMarker(cwd, task.phaseNum, 'execute', 'failed');
+                    results.push({ phase: task.phaseNum, step: 'execute', status: 'failed', reason });
+                    stoppedAt = `Phase ${task.phaseNum} execute failed: ${reason}`;
+                    // Clean up worktree on failure
+                    execGit(cwd, ['worktree', 'remove', wtPath, '--force'], { allowBlocked: true });
+                    execGit(cwd, ['worktree', 'prune']);
+                    continue;
+                }
+                log(`Phase ${task.phaseNum}: execute completed`);
+                writeStatusMarker(cwd, task.phaseNum, 'execute', 'completed');
+                results.push({ phase: task.phaseNum, step: 'execute', status: 'completed' });
+                // Knowledge mining (non-blocking — runKnowledgeMining never rejects)
+                await runKnowledgeMining(cwd, task.phaseNum, { scheduler, log });
+                // Refinement loop (non-blocking — runRefinementLoop never rejects).
+                // Codex r43 P1 #2: pass wtPath so critique-agent edits land in
+                // the phase worktree the post-pipeline merges.
+                await runRefinementLoop(cwd, task.phaseNum, { scheduler, log, workCwd: wtPath });
+                // Launch post-phase pipeline concurrently (Steps 1-3 run in parallel across
+                // phases; Step 4 rebase+merge is serialized via the shared mergeQueue).
+                if (!skipPostPipeline) {
+                    const phaseNumCapture = task.phaseNum;
+                    const wtPathCapture = wtPath;
+                    log(`Phase ${phaseNumCapture}: starting post-phase pipeline`);
+                    writeStatusMarker(cwd, phaseNumCapture, 'post-pipeline', 'started');
+                    const pipelinePromise = runPostPhasePipeline(cwd, phaseNumCapture, wtPathCapture, {
+                        timeout,
+                        maxTurns,
+                        model,
+                        scheduler,
+                        log,
+                        mergeQueue,
+                    }).then((result) => ({ phaseNum: phaseNumCapture, result }));
+                    pipelineTasks.push({
+                        phaseNum: phaseNumCapture,
+                        wtPath: wtPathCapture,
+                        promise: pipelinePromise,
+                    });
+                }
+                else {
+                    // No pipeline — clean up worktree immediately
+                    execGit(cwd, ['worktree', 'remove', wtPath, '--force'], { allowBlocked: true });
+                    execGit(cwd, ['worktree', 'prune']);
+                }
+            }
+            // Await all concurrent post-phase pipelines
+            if (pipelineTasks.length > 0) {
+                const pipelineResults = await Promise.all(pipelineTasks.map((t) => t.promise));
+                for (const { phaseNum: pNum, result: pipelineResult } of pipelineResults) {
+                    const taskEntry = pipelineTasks.find((t) => t.phaseNum === pNum);
+                    if (pipelineResult.status === 'failed') {
+                        log(`Phase ${pNum}: post-pipeline FAILED at ${pipelineResult.failedStep}: ${pipelineResult.reason}`);
+                        writeStatusMarker(cwd, pNum, 'post-pipeline', 'failed');
+                        results.push({
+                            phase: pNum,
+                            step: 'post-pipeline',
+                            status: 'failed',
+                            reason: `${pipelineResult.failedStep}: ${pipelineResult.reason}`,
+                        });
+                        if (!stoppedAt) {
+                            stoppedAt = `Phase ${pNum} post-pipeline failed at ${pipelineResult.failedStep}`;
+                        }
+                    }
+                    else {
+                        log(`Phase ${pNum}: post-pipeline completed`);
+                        writeStatusMarker(cwd, pNum, 'post-pipeline', 'completed');
+                        results.push({ phase: pNum, step: 'post-pipeline', status: 'completed' });
+                        // Spec 3: mechanical phase finalization. On a successful post-pipeline,
+                        // fold in phase complete (ROADMAP + STATE + quality analysis) instead
+                        // of leaving it for the user to run manually.
+                        const finalizeResult = await finalizePhaseAfterPipeline(cwd, pNum, scheduler, log);
+                        if (finalizeResult) {
+                            results.push({ phase: pNum, step: 'phase-finalize', status: 'completed' });
+                        }
+                        else {
+                            results.push({
+                                phase: pNum,
+                                step: 'phase-finalize',
+                                status: 'failed',
+                                reason: 'phase complete failed — see logs for details',
+                            });
+                        }
+                    }
+                    // Clean up worktree after pipeline completes (success or failure)
+                    execGit(cwd, ['worktree', 'remove', taskEntry.wtPath, '--force'], { allowBlocked: true });
+                    execGit(cwd, ['worktree', 'prune']);
+                }
+            }
+            if (stoppedAt)
+                break;
+            // Count phases where execution didn't fail
+            for (const phaseNum of wave) {
+                const hasFailed = results.some((r) => r.phase === phaseNum && r.status === 'failed');
+                if (!hasFailed)
+                    phasesCompleted++;
+            }
+            // Tier-3 #10: ontology-convergence termination. Opt-in via
+            // config.autopilot.stop_on_ontology_convergence. Recorded on the
+            // separate `convergedAt` channel (codex r2 P2 on PR #40) so callers
+            // like runMultiMilestoneAutopilot / evolve do not classify graceful
+            // termination as a failure. Guards from codex r1: only fire when
+            // there's a NEXT wave to skip, and require non-overlapping windows
+            // (handled by isOntologyConverged).
+            if (config.autopilot?.stop_on_ontology_convergence === true &&
+                waveIdx < waves.length - 1) {
+                const threshold = config.autopilot.ontology_convergence_threshold ?? 0.95;
+                const result = isOntologyConverged(cwd, threshold);
+                if (result.converged && result.similarity !== undefined) {
+                    convergedAt = `ontology-convergence (similarity ${result.similarity.toFixed(3)} >= ${threshold})`;
+                    log(`Autopilot: converged early — ${convergedAt}`);
+                }
+            }
+        }
+    }
+    // ── Milestone mode: run wireup after all phases complete ──
+    // codex r3 P2: convergence skips later waves intentionally, so the
+    // milestone is NOT complete in the user's sense. Gate wireup on
+    // !convergedAt so wireup does not run as though everything finished.
+    const isMilestoneMode = options.milestone === true || (!phaseFrom && !phaseTo);
+    if (isMilestoneMode &&
+        !stoppedAt &&
+        !convergedAt &&
+        !dryRun &&
+        phasesCompleted === phasesAttempted &&
+        phasesCompleted > 0) {
+        log('Milestone mode: all phases complete — running wireup');
+        // Compute wireup prompt once for tier routing and dispatch.
+        const wireupPrompt = buildWireupPrompt();
+        // Resolve effective model for wireup via the Spec 4 chain.
+        const wireupTier = getEffectiveTierForDispatch({
+            agentType: 'grd-executor',
+            prompt: wireupPrompt,
+            config,
+            scheduler,
+            schedulerConfig: config.scheduler,
+            superpowersConfig: config.superpowers,
+            modelProfiles: MODEL_PROFILES,
+        });
+        const wireupModel = model
+            ? model
+            : resolveModelForAgent(config, 'grd-executor', cwd, {
+                effectiveTierOverride: wireupTier,
+            });
+        const wireupResult = scheduler
+            ? toSpawnResult(await scheduler.spawn(wireupPrompt, {
+                timeout: timeoutMs,
+                maxTurns,
+                model: wireupModel,
+                cwd,
+                workItemId: 'milestone-wireup',
+                agentType: 'grd-integration-checker',
+            }))
+            : await spawnClaudeAsync(cwd, wireupPrompt, {
+                timeout: timeoutMs,
+                maxTurns,
+                model: wireupModel,
+            });
+        if (wireupResult.exitCode !== 0) {
+            const reason = wireupResult.timedOut
+                ? 'timeout'
+                : `exit code ${wireupResult.exitCode}`;
+            log(`Wireup FAILED (${reason})`);
+            results.push({ phase: 'wireup', step: 'wireup', status: 'failed', reason });
+        }
+        else {
+            log('Wireup completed');
+            results.push({ phase: 'wireup', step: 'wireup', status: 'completed' });
+        }
+    }
+    log(`Done: ${phasesCompleted}/${phasesAttempted} phases completed${stoppedAt
+        ? ` (stopped: ${stoppedAt})`
+        : convergedAt
+            ? ` (converged: ${convergedAt})`
+            : ''}`);
+    if (scheduler) {
+        scheduler.persistState(path.join(cwd, '.planning'));
+    }
+    return {
+        phases_attempted: phasesAttempted,
+        phases_completed: phasesCompleted,
+        stopped_at: stoppedAt,
+        converged_at: convergedAt,
+        waves,
+        results,
+    };
+}
+// ─── Multi-Milestone Orchestration ───────────────────────────────────────────
+/**
+ * Run the multi-milestone autopilot loop.
+ * Orchestrates across milestone boundaries: completes current milestone phases,
+ * detects milestone completion, resolves the next milestone, creates it, and continues.
+ *
+ * Safety: maxMilestones cap (default 10) prevents infinite loops.
+ *
+ * @param cwd - Absolute path to the project root directory
+ * @param options - Configuration options including maxMilestones cap, dryRun flag, resume flag, timeout, maxTurns, model, skipPlan, and skipExecute
+ * @returns Aggregate result with milestone and phase counts, per-milestone results, and the stop reason if any
+ */
+async function runMultiMilestoneAutopilot(cwd, options = {}) {
+    const maxMilestones = options.maxMilestones ?? 10;
+    const dryRun = options.dryRun ?? false;
+    const timeoutMs = options.timeout ? options.timeout * 60 * 1000 : undefined;
+    // Set up logging (reuse existing autopilot log pattern)
+    const logFile = path.join(cwd, '.planning', 'autopilot', 'autopilot.log');
+    fs.mkdirSync(path.dirname(logFile), { recursive: true });
+    const log = (msg) => {
+        const line = `[${new Date().toISOString()}] [multi-milestone] ${msg}\n`;
+        process.stderr.write(`[multi-milestone] ${msg}\n`);
+        fs.appendFileSync(logFile, line);
+    };
+    // Initialize result tracking
+    const milestoneResults = [];
+    let milestonesAttempted = 0;
+    let milestonesCompleted = 0;
+    let totalPhasesAttempted = 0;
+    let totalPhasesCompleted = 0;
+    let stoppedAt = null;
+    // Graceful early termination at the milestone-chain level (Tier-3 #10).
+    // codex r4 P2 on PR #40: the maxMilestones cap check at the bottom of
+    // this function overwrites stoppedAt to "Reached maxMilestones cap"
+    // when convergence fires on the last permitted iteration — turning a
+    // graceful stop into a reported failure. Tracking convergence on a
+    // dedicated channel lets us bypass that overwrite cleanly.
+    let convergedAt = null;
+    log(`Starting multi-milestone autopilot (max: ${maxMilestones}, dryRun: ${dryRun})`);
+    const mmConfig = loadConfig(cwd);
+    const mmBackend = detectBackend(cwd);
+    const mmScheduler = createScheduler(mmConfig.scheduler, mmConfig.superpowers);
+    if (mmScheduler) {
+        mmScheduler.loadPersistedState(path.join(cwd, '.planning'));
+    }
+    for (let i = 0; i < maxMilestones; i++) {
+        if (stoppedAt)
+            break;
+        // Get current milestone info (re-read each iteration for fresh state)
+        const milestoneInfo = getMilestoneInfo(cwd);
+        const currentVersion = milestoneInfo.version;
+        log(`Milestone ${i + 1}/${maxMilestones}: ${currentVersion} (${milestoneInfo.name})`);
+        milestonesAttempted++;
+        // Check for incomplete phases in current milestone
+        const { phases, error: rangeError } = resolvePhaseRange(cwd, null, null);
+        if (rangeError) {
+            log(`Error resolving phases: ${rangeError}`);
+            milestoneResults.push({
+                milestone: currentVersion,
+                phases_attempted: 0,
+                phases_completed: 0,
+                status: 'failed',
+                reason: rangeError,
+            });
+            stoppedAt = `Failed to resolve phases for ${currentVersion}: ${rangeError}`;
+            break;
+        }
+        const incompletePhases = phases.filter((p) => p.disk_status !== 'complete');
+        if (incompletePhases.length > 0) {
+            log(`${currentVersion}: ${incompletePhases.length} incomplete phase(s), running autopilot...`);
+            if (dryRun) {
+                milestoneResults.push({
+                    milestone: currentVersion,
+                    phases_attempted: incompletePhases.length,
+                    phases_completed: 0,
+                    status: 'dry-run',
+                    reason: `Would process ${incompletePhases.length} incomplete phase(s)`,
+                });
+                totalPhasesAttempted += incompletePhases.length;
+            }
+            else {
+                // Run single-milestone autopilot for current milestone's phases
+                const autopilotResult = await runAutopilot(cwd, {
+                    skipPlan: options.skipPlan,
+                    skipExecute: options.skipExecute,
+                    skipPostPipeline: options.skipPostPipeline,
+                    timeout: options.timeout,
+                    maxTurns: options.maxTurns,
+                    model: options.model,
+                });
+                totalPhasesAttempted += autopilotResult.phases_attempted;
+                totalPhasesCompleted += autopilotResult.phases_completed;
+                const autopilotFailed = autopilotResult.stopped_at !== null;
+                const autopilotConverged = autopilotResult.converged_at !== null;
+                milestoneResults.push({
+                    milestone: currentVersion,
+                    phases_attempted: autopilotResult.phases_attempted,
+                    phases_completed: autopilotResult.phases_completed,
+                    status: autopilotFailed
+                        ? 'failed'
+                        : autopilotConverged
+                            ? 'converged'
+                            : 'completed',
+                    reason: autopilotResult.stopped_at || autopilotResult.converged_at || undefined,
+                });
+                if (autopilotFailed) {
+                    log(`${currentVersion}: autopilot stopped: ${autopilotResult.stopped_at}`);
+                    stoppedAt = `Autopilot failed for ${currentVersion}: ${autopilotResult.stopped_at}`;
+                    break;
+                }
+                // codex r3 P2: convergence is a graceful TERMINAL state for this
+                // milestone chain — do not advance to the next milestone. Track
+                // on the dedicated `convergedAt` channel so the post-loop
+                // maxMilestones cap check (codex r4 P2) does not overwrite it.
+                if (autopilotConverged) {
+                    convergedAt = autopilotResult.converged_at;
+                    log(`${currentVersion}: autopilot converged early — ${convergedAt}`);
+                    break;
+                }
+            }
+        }
+        else {
+            log(`${currentVersion}: all phases already complete`);
+            milestoneResults.push({
+                milestone: currentVersion,
+                phases_attempted: 0,
+                phases_completed: 0,
+                status: 'skipped',
+                reason: 'all phases already complete',
+            });
+        }
+        // Check milestone completion after autopilot run
+        if (isMilestoneComplete(cwd)) {
+            log(`${currentVersion}: milestone complete`);
+            if (!dryRun) {
+                // Complete the milestone via deterministic grd-tools command
+                const completePrompt = buildMilestoneCompletePrompt(currentVersion);
+                log(`${currentVersion}: completing milestone...`);
+                const completeResult = mmScheduler
+                    ? toSpawnResult(await mmScheduler.spawn(completePrompt, {
+                        timeout: timeoutMs,
+                        maxTurns: options.maxTurns,
+                        model: options.model,
+                        cwd,
+                        workItemId: `milestone-${currentVersion}-complete`,
+                        agentType: 'grd-integration-checker',
+                    }))
+                    : spawnClaude(cwd, completePrompt, {
+                        timeout: timeoutMs,
+                        maxTurns: options.maxTurns,
+                        model: options.model,
+                    });
+                if (completeResult.exitCode !== 0) {
+                    const reason = completeResult.timedOut
+                        ? 'timeout'
+                        : `exit code ${completeResult.exitCode}`;
+                    log(`${currentVersion}: milestone complete FAILED (${reason})`);
+                    stoppedAt = `Failed to complete milestone ${currentVersion}: ${reason}`;
+                    break;
+                }
+                log(`${currentVersion}: milestone completed successfully`);
+            }
+            else {
+                log(`${currentVersion}: [dry-run] would complete milestone`);
+            }
+            milestonesCompleted++;
+        }
+        else {
+            log(`${currentVersion}: milestone not fully complete yet`);
+            stoppedAt = `Milestone ${currentVersion} is not fully complete after autopilot run`;
+            break;
+        }
+        // Resolve next milestone
+        const nextMs = resolveNextMilestone(cwd);
+        if (!nextMs) {
+            log('No next milestone found in LONG-TERM-ROADMAP.md — stopping');
+            stoppedAt = null; // Graceful completion, not an error
+            break;
+        }
+        log(`Next milestone: ${nextMs.version} (${nextMs.name})`);
+        if (dryRun) {
+            log(`[dry-run] Would create new milestone: ${nextMs.version}`);
+            continue;
+        }
+        // Spawn new milestone creation via claude -p
+        const newMilestonePrompt = buildNewMilestonePrompt(mmBackend);
+        log('Creating new milestone...');
+        const createResult = mmScheduler
+            ? toSpawnResult(await mmScheduler.spawn(newMilestonePrompt, {
+                timeout: timeoutMs,
+                maxTurns: options.maxTurns,
+                model: options.model,
+                cwd,
+                workItemId: 'new-milestone',
+                agentType: 'grd-planner',
+            }))
+            : spawnClaude(cwd, newMilestonePrompt, {
+                timeout: timeoutMs,
+                maxTurns: options.maxTurns,
+                model: options.model,
+            });
+        if (createResult.exitCode !== 0) {
+            const reason = createResult.timedOut
+                ? 'timeout'
+                : `exit code ${createResult.exitCode}`;
+            log(`New milestone creation FAILED (${reason})`);
+            stoppedAt = `Failed to create new milestone: ${reason}`;
+            break;
+        }
+        log('New milestone created, continuing loop...');
+    }
+    // codex r4 P2: do not overwrite a graceful convergence with the
+    // "Reached maxMilestones cap" failure signal. Convergence is the
+    // terminal reason; the cap only matters when the loop exhausted
+    // milestones without converging.
+    if (!stoppedAt && !convergedAt && milestonesAttempted >= maxMilestones) {
+        stoppedAt = `Reached maxMilestones cap (${maxMilestones})`;
+        log(stoppedAt);
+    }
+    log(`Multi-milestone autopilot done: ${milestonesCompleted}/${milestonesAttempted} milestones completed` +
+        (stoppedAt
+            ? ` (stopped: ${stoppedAt})`
+            : convergedAt
+                ? ` (converged: ${convergedAt})`
+                : ''));
+    if (mmScheduler) {
+        mmScheduler.persistState(path.join(cwd, '.planning'));
+    }
+    return {
+        milestones_attempted: milestonesAttempted,
+        milestones_completed: milestonesCompleted,
+        milestone_results: milestoneResults,
+        stopped_at: stoppedAt,
+        converged_at: convergedAt,
+        total_phases_attempted: totalPhasesAttempted,
+        total_phases_completed: totalPhasesCompleted,
+    };
+}
+// ─── CLI Entry Points ───────────────────────────────────────────────────────
+/**
+ * Parse CLI flags and run the autopilot loop.
+ */
+async function cmdAutopilot(cwd, args, raw) {
+    const flag = (name, fallback) => {
+        const i = args.indexOf(name);
+        return i !== -1 ? args[i + 1] : fallback;
+    };
+    const hasFlag = (name) => args.indexOf(name) !== -1;
+    const options = {
+        phaseFrom: flag('--phase-from', null),
+        phaseTo: flag('--phase-to', null),
+        milestone: hasFlag('--milestone'),
+        dryRun: hasFlag('--dry-run'),
+        skipPlan: hasFlag('--skip-plan'),
+        skipExecute: hasFlag('--skip-execute'),
+        skipPostPipeline: hasFlag('--skip-post-pipeline'),
+        timeout: (() => {
+            if (!hasFlag('--timeout'))
+                return undefined;
+            const parsed = parseInt(flag('--timeout', '0'), 10);
+            if (isNaN(parsed) || parsed <= 0) {
+                process.stderr.write('Error: --timeout must be a positive integer\n');
+                process.exit(1);
+            }
+            return parsed;
+        })(),
+        maxTurns: (() => {
+            if (!flag('--max-turns', null))
+                return undefined;
+            const parsed = parseInt(flag('--max-turns', '0'), 10);
+            if (isNaN(parsed) || parsed <= 0) {
+                process.stderr.write('Error: --max-turns must be a positive integer\n');
+                process.exit(1);
+            }
+            return parsed;
+        })(),
+        model: flag('--model', undefined) ?? undefined,
+    };
+    // Pre-execution dry-run plan: compute phase order, parallel groups, and model routing
+    // and attach to the result (without short-circuiting — runAutopilot still runs).
+    let dryRunPlan;
+    if (options.dryRun) {
+        const drConfig = loadConfig(cwd);
+        const drAnalysis = analyzeRoadmap(cwd);
+        const drPhases = (drAnalysis.phases ?? []).filter((p) => {
+            if (options.phaseFrom && parseFloat(p.number) < parseFloat(options.phaseFrom))
+                return false;
+            if (options.phaseTo && parseFloat(p.number) > parseFloat(options.phaseTo))
+                return false;
+            return !p.roadmap_complete;
+        });
+        const drWaves = buildWaves(drPhases, {});
+        const drScheduler = createScheduler(drConfig.scheduler, drConfig.superpowers);
+        dryRunPlan = [];
+        for (let wi = 0; wi < drWaves.length; wi++) {
+            const wavePlan = drWaves[wi].map((phaseNum) => {
+                const phaseInfo = drPhases.find((p) => p.number === phaseNum);
+                const planPrompt = `plan phase ${phaseNum}`;
+                const execPrompt = `execute phase ${phaseNum}`;
+                const planTier = getEffectiveTierForDispatch({ agentType: 'grd-planner', prompt: planPrompt, config: drConfig, scheduler: drScheduler, schedulerConfig: drConfig.scheduler, superpowersConfig: drConfig.superpowers, modelProfiles: MODEL_PROFILES });
+                const execTier = getEffectiveTierForDispatch({ agentType: 'grd-executor', prompt: execPrompt, config: drConfig, scheduler: drScheduler, schedulerConfig: drConfig.scheduler, superpowersConfig: drConfig.superpowers, modelProfiles: MODEL_PROFILES });
+                const planModel = options.model ?? resolveModelForAgent(drConfig, 'grd-planner', cwd, { effectiveTierOverride: planTier });
+                const execModel = options.model ?? resolveModelForAgent(drConfig, 'grd-executor', cwd, { effectiveTierOverride: execTier });
+                return { phase: phaseNum, name: phaseInfo?.name ?? '', plan_model: planModel, execute_model: execModel };
+            });
+            dryRunPlan.push({ wave: wi + 1, phases: wavePlan });
+        }
+    }
+    const result = await runAutopilot(cwd, options);
+    const finalResult = dryRunPlan !== undefined
+        ? { ...result, execution_plan: dryRunPlan }
+        : result;
+    const rawSummary = raw
+        ? `Autopilot: ${result.phases_completed}/${result.phases_attempted} phases completed${result.stopped_at ? ` (stopped: ${result.stopped_at})` : ''}`
+        : undefined;
+    output(finalResult, raw, rawSummary);
+}
+/**
+ * Pre-flight context for autopilot initialization.
+ */
+function cmdInitAutopilot(cwd, raw) {
+    const config = loadConfig(cwd);
+    const analysis = analyzeRoadmap(cwd);
+    // Check if claude CLI is available
+    let claudeAvailable = false;
+    try {
+        const check = childProcess.spawnSync('claude', ['--version'], {
+            stdio: 'pipe',
+            timeout: config.timeouts.autopilot_check_ms,
+        });
+        claudeAvailable = check.status === 0;
+    }
+    catch {
+        // claude CLI not found -- claudeAvailable stays false
+    }
+    const phases = analysis.phases || [];
+    const incomplete = phases.filter((p) => p.disk_status !== 'complete' && !p.roadmap_complete);
+    const backend = detectBackend(cwd);
+    const caps = getBackendCapabilities(backend);
+    const result = {
+        claude_available: claudeAvailable,
+        cron_available: caps.cron === true,
+        total_phases: phases.length,
+        incomplete_phases: incomplete.length,
+        phase_range: {
+            first: phases.length > 0 ? phases[0].number : null,
+            last: phases.length > 0 ? phases[phases.length - 1].number : null,
+            first_incomplete: incomplete.length > 0 ? incomplete[0].number : null,
+        },
+        config: {
+            model_profile: config.model_profile,
+            autonomous_mode: config.autonomous_mode,
+        },
+        phases: phases.map((p) => ({
+            number: p.number,
+            name: p.name,
+            disk_status: p.disk_status || 'unknown',
+            roadmap_complete: p.roadmap_complete || false,
+        })),
+    };
+    output(result, raw, raw ? JSON.stringify(result) : undefined);
+}
+/**
+ * Parse CLI flags and run the multi-milestone autopilot loop.
+ */
+async function cmdMultiMilestoneAutopilot(cwd, args, raw) {
+    const flag = (name, fallback) => {
+        const i = args.indexOf(name);
+        return i !== -1 ? args[i + 1] : fallback;
+    };
+    const hasFlag = (name) => args.indexOf(name) !== -1;
+    const options = {
+        maxMilestones: hasFlag('--max-milestones')
+            ? parseInt(flag('--max-milestones', '10'), 10)
+            : undefined,
+        dryRun: hasFlag('--dry-run'),
+        timeout: (() => {
+            if (!hasFlag('--timeout'))
+                return undefined;
+            const parsed = parseInt(flag('--timeout', '0'), 10);
+            if (isNaN(parsed) || parsed <= 0) {
+                process.stderr.write('Error: --timeout must be a positive integer\n');
+                process.exit(1);
+            }
+            return parsed;
+        })(),
+        maxTurns: (() => {
+            if (!flag('--max-turns', null))
+                return undefined;
+            const parsed = parseInt(flag('--max-turns', '0'), 10);
+            if (isNaN(parsed) || parsed <= 0) {
+                process.stderr.write('Error: --max-turns must be a positive integer\n');
+                process.exit(1);
+            }
+            return parsed;
+        })(),
+        model: flag('--model', undefined) ?? undefined,
+        skipPlan: hasFlag('--skip-plan'),
+        skipExecute: hasFlag('--skip-execute'),
+        skipPostPipeline: hasFlag('--skip-post-pipeline'),
+    };
+    const result = await runMultiMilestoneAutopilot(cwd, options);
+    const rawSummary = raw
+        ? `Multi-milestone autopilot: ${result.milestones_completed}/${result.milestones_attempted} milestones completed (${result.total_phases_completed}/${result.total_phases_attempted} phases)${result.stopped_at ? ` (stopped: ${result.stopped_at})` : ''}`
+        : undefined;
+    output(result, raw, rawSummary);
+}
+/**
+ * Pre-flight context for multi-milestone autopilot initialization.
+ * Returns LT roadmap state, current milestone info, and next milestone resolution.
+ */
+function cmdInitMultiMilestoneAutopilot(cwd, raw) {
+    const config = loadConfig(cwd);
+    const analysis = analyzeRoadmap(cwd);
+    // Check if claude CLI is available
+    let claudeAvailable = false;
+    try {
+        const check = childProcess.spawnSync('claude', ['--version'], {
+            stdio: 'pipe',
+            timeout: config.timeouts.autopilot_check_ms,
+        });
+        claudeAvailable = check.status === 0;
+    }
+    catch {
+        // claude CLI not found -- claudeAvailable stays false
+    }
+    // Current milestone info
+    const milestoneInfo = getMilestoneInfo(cwd);
+    // Current milestone completion state
+    const milestoneComplete = isMilestoneComplete(cwd);
+    // Next milestone from LT roadmap
+    const nextMilestone = resolveNextMilestone(cwd);
+    // LT roadmap existence and state
+    const ltRoadmapPath = path.join(cwd, '.planning', 'LONG-TERM-ROADMAP.md');
+    const ltRoadmapExists = fs.existsSync(ltRoadmapPath);
+    let ltMilestoneCount = 0;
+    if (ltRoadmapExists) {
+        const ltContent = fs.readFileSync(ltRoadmapPath, 'utf-8');
+        const parsed = parseLongTermRoadmap(ltContent);
+        if (parsed) {
+            ltMilestoneCount = parsed.milestones.length;
+        }
+    }
+    const phases = analysis.phases || [];
+    const incomplete = phases.filter((p) => p.disk_status !== 'complete' && !p.roadmap_complete);
+    const result = {
+        claude_available: claudeAvailable,
+        current_milestone: {
+            version: milestoneInfo.version,
+            name: milestoneInfo.name,
+            is_complete: milestoneComplete,
+            total_phases: phases.length,
+            incomplete_phases: incomplete.length,
+        },
+        lt_roadmap: {
+            exists: ltRoadmapExists,
+            milestone_count: ltMilestoneCount,
+        },
+        next_milestone: nextMilestone,
+        config: {
+            model_profile: config.model_profile,
+            autonomous_mode: config.autonomous_mode,
+        },
+    };
+    output(result, raw, raw ? JSON.stringify(result) : undefined);
+}
+// ─── Spin Event Handler ──────────────────────────────────────────────────────
+/**
+ * Handle a spin detection event by writing a SPIN-REPORT.md to the phase directory
+ * and returning action options (resume, skip, abort) for the caller to present to the user.
+ *
+ * @param phaseDir - Absolute path to the phase directory
+ * @param spinEvent - The SpinDetectedEvent from detectSpin()
+ * @param phaseName - Human-readable phase name for the report header
+ * @returns Path to the written SPIN-REPORT.md, or null if write failed
+ */
+function handleSpinEvent(phaseDir, spinEvent, phaseName) {
+    const pattern = spinEvent.repeated_pattern;
+    // Auto-generate recovery suggestions based on error keywords in the pattern
+    const suggestions = [];
+    const lower = pattern.toLowerCase();
+    if (/type.?error|cannot find|property .* does not exist/i.test(lower)) {
+        suggestions.push('Run `npm run build:check` to identify type errors and fix them before retrying');
+    }
+    if (/test failed|expect|assertion/i.test(lower)) {
+        suggestions.push('Run `npm test` to identify failing tests; review the test output for clues on missing implementation');
+    }
+    if (/cannot find module|module not found|require.*failed/i.test(lower)) {
+        suggestions.push('Check that all required packages are installed (`npm install`) and import paths are correct');
+    }
+    if (suggestions.length === 0) {
+        suggestions.push('Review the error pattern above and check for missing files, imports, or API mismatches');
+        suggestions.push('Consider breaking the phase into smaller tasks or skipping and addressing manually');
+    }
+    suggestions.push('Check ROADMAP.md for any prerequisite phases that may not be complete yet');
+    const reportLines = [
+        `# Spin Detected — ${phaseName}`,
+        '',
+        `Generated: ${new Date().toISOString().slice(0, 19).replace('T', ' ')} UTC`,
+        '',
+        `## Summary`,
+        '',
+        `The autopilot detected **${spinEvent.consecutive_count} consecutive similar output chunks** (similarity: ${spinEvent.max_similarity}) suggesting the agent is looping on the same error without progress.`,
+        '',
+        '## Repeated Error Pattern',
+        '',
+        '```',
+        pattern,
+        '```',
+        '',
+        '## Recovery Suggestions',
+        '',
+        ...suggestions.map((s, i) => `${i + 1}. ${s}`),
+        '',
+        '## Actions',
+        '',
+        '- **Resume**: Fix the underlying issue above, then re-run `gd execute-phase <N>`',
+        '- **Skip**: Mark the phase as skipped and continue autopilot with the next phase',
+        '- **Abort**: Stop the autopilot run and investigate manually',
+    ];
+    try {
+        const reportPath = path.join(phaseDir, 'SPIN-REPORT.md');
+        fs.writeFileSync(reportPath, reportLines.join('\n') + '\n', 'utf-8');
+        return reportPath;
+    }
+    catch {
+        return null;
+    }
+}
+// ─── Exports ────────────────────────────────────────────────────────────────
+module.exports = {
+    createMergeQueue,
+    cmdAutopilot,
+    cmdInitAutopilot,
+    cmdMultiMilestoneAutopilot,
+    cmdInitMultiMilestoneAutopilot,
+    runAutopilot,
+    runMultiMilestoneAutopilot,
+    resolvePhaseRange,
+    isPhasePlanned,
+    isPhaseExecuted,
+    hasMultipleCandidates,
+    isMilestoneComplete,
+    resolveNextMilestone,
+    buildNewMilestonePrompt,
+    buildMilestoneCompletePrompt,
+    spawnClaude,
+    spawnClaudeAsync,
+    buildPlanPrompt,
+    buildExecutePrompt,
+    buildSimplifyPrompt,
+    buildCodeReviewPrompt,
+    buildConflictResolvePrompt,
+    buildWireupPrompt,
+    buildKnowledgeMiningPrompt,
+    runKnowledgeMining,
+    buildCritiqueAgentPrompt,
+    runRefinementLoop,
+    runPostPhasePipeline,
+    buildWaves,
+    buildWavesFromPlans,
+    parseWriteIntent,
+    compareWriteIntent,
+    formatWriteIntentMismatch,
+    writeStatusMarker,
+    updateStateProgress,
+    DEFAULT_TIMEOUT_MINUTES,
+    HEARTBEAT_INTERVAL_MS,
+    _getSchedulerStates,
+    handleSpinEvent,
+};
+//# sourceMappingURL=autopilot.js.map