swarm-orchestrator 7.0.0-alpha.0

package/dist/src/swarm-orchestrator.js

@@ -0,0 +1,686 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SwarmOrchestrator = void 0;
+const child_process_1 = require("child_process");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const adapters_1 = require("./adapters");
+const config_loader_1 = require("./config-loader");
+const context_broker_1 = __importDefault(require("./context-broker"));
+const execution_queue_1 = require("./execution-queue");
+const knowledge_base_1 = require("./knowledge-base");
+const meta_analyzer_1 = require("./meta-analyzer");
+const metrics_collector_1 = __importDefault(require("./metrics-collector"));
+const post_run_reporter_1 = require("./post-run-reporter");
+const quality_gates_1 = require("./quality-gates");
+const session_executor_1 = __importDefault(require("./session-executor"));
+const share_parser_1 = __importDefault(require("./share-parser"));
+const verifier_engine_1 = __importDefault(require("./verifier-engine"));
+const wave_resizer_1 = require("./wave-resizer");
+const cost_estimator_1 = require("./cost-estimator");
+const pr_manager_1 = __importDefault(require("./pr-manager"));
+const worktree_manager_1 = require("./worktree-manager");
+const branch_merger_1 = require("./branch-merger");
+const baseline_scanner_1 = require("./baseline-scanner");
+const task_classifier_1 = require("./task-classifier");
+const tier_maps_1 = require("./tier-maps");
+const requirement_filter_1 = require("./requirement-filter");
+const logger_1 = require("./logger");
+const prompt_builder_1 = require("./prompt-builder");
+const wave_scheduler_1 = require("./wave-scheduler");
+const deployment_handler_1 = require("./deployment-handler");
+const commit_quality_analyzer_1 = require("./commit-quality-analyzer");
+const pause_controller_1 = require("./orchestrator/pause-controller");
+const git_state_utils_1 = require("./orchestrator/git-state-utils");
+const async_meta_analysis_1 = require("./orchestrator/async-meta-analysis");
+const final_gates_remediation_1 = require("./orchestrator/final-gates-remediation");
+const replan_runner_1 = require("./orchestrator/replan-runner");
+const step_executor_1 = require("./orchestrator/step-executor");
+const wave_scheduler_loop_1 = require("./orchestrator/wave-scheduler-loop");
+const fatal_run_error_1 = require("./orchestrator/fatal-run-error");
+const logger = (0, logger_1.getLogger)('orchestrator');
+/**
+ * Swarm Orchestrator - coordinates parallel execution of independent Copilot CLI sessions
+ * Manages concurrent sessions, per-agent branches, and automatic merging
+ */
+class SwarmOrchestrator {
+    sessionExecutor;
+    shareParser;
+    verifier;
+    workingDir;
+    worktreeManager;
+    branchMerger;
+    pauseController = new pause_controller_1.PauseController();
+    /**
+     * `targetMode` is true when the orchestrator is operating on an external
+     * target repo (e.g. `swarm bootstrap ./external-repo`, the SWE-bench
+     * harness). False when operating on its own codebase (self-improvement
+     * runs). Structural signal, not keyword-based: the caller passes a
+     * truthy `workingDir` that is not the orchestrator's own cwd, and the
+     * CLI dispatcher sets `targetMode = true` at that boundary.
+     *
+     * Drives two behaviors:
+     *   1. Orchestrator-internal quality gates (scaffoldDefaults,
+     *      duplicateBlocks, readmeClaims, testIsolation, runtimeChecks,
+     *      accessibility, testCoverage) are skipped when targetMode is
+     *      true — those enforce conventions on the orchestrator's own
+     *      generated code, not on arbitrary target repos. See #27 Phase-4a
+     *      smoke4 for the failure mode this prevents.
+     *   2. Verifier per-step outcome checks (git_diff, file_existence,
+     *      build_exec, test_exec) are NOT affected by targetMode. Those
+     *      are the orchestrator's verification contract for detecting
+     *      agent lies about their own work, and apply universally.
+     */
+    targetMode;
+    constructor(workingDir, targetMode = false) {
+        this.workingDir = workingDir || process.cwd();
+        this.targetMode = targetMode;
+        this.sessionExecutor = new session_executor_1.default(this.workingDir);
+        this.shareParser = new share_parser_1.default();
+        this.verifier = new verifier_engine_1.default(this.workingDir);
+        this.worktreeManager = new worktree_manager_1.WorktreeManager(this.workingDir);
+        this.branchMerger = new branch_merger_1.BranchMerger(this.workingDir, this.worktreeManager);
+    }
+    /**
+     * Look up an agent by name, falling back to normalized (snake_case) matching.
+     * Handles plans using lowercase ('worker', 'reviewer') against YAML agents.
+     * Public to satisfy `RemediationHost`; callers outside the class should still
+     * treat it as an internal helper.
+     */
+    resolveAgent(agents, name) {
+        const exact = agents.get(name);
+        if (exact)
+            return exact;
+        const normalized = config_loader_1.ConfigLoader.normalizeAgentName(name);
+        for (const [key, agent] of agents) {
+            if (config_loader_1.ConfigLoader.normalizeAgentName(key) === normalized)
+                return agent;
+        }
+        return undefined;
+    }
+    /**
+     * Request pause of current execution
+     */
+    requestPause() {
+        this.pauseController.requestPause();
+    }
+    /**
+     * Request resume of paused execution
+     */
+    requestResume() {
+        this.pauseController.requestResume();
+    }
+    /**
+     * Check if pause is requested
+     */
+    isPauseRequested() {
+        return this.pauseController.isPauseRequested();
+    }
+    /**
+     * Initialize swarm execution context
+     */
+    initializeSwarmExecution(plan, runDir, maxConcurrency) {
+        const executionId = this.generateExecutionId();
+        const contextBroker = new context_broker_1.default(runDir);
+        const metricsCollector = new metrics_collector_1.default(executionId, plan.goal);
+        // ensure repo has at least one commit (required for branch creation)
+        this.ensureInitialCommit();
+        // resolve the integration branch: prefer origin/HEAD's symbolic ref (so repos
+        // whose default is `master` or `trunk` work), fall back to the currently
+        // checked-out branch, then fall back to 'main'. See worktree-manager
+        // .resolveDefaultBranch() for the rationale.
+        const mainBranch = this.worktreeManager.resolveDefaultBranch();
+        let baseCommitSha;
+        try {
+            baseCommitSha = (0, child_process_1.execSync)('git rev-parse HEAD', {
+                cwd: this.workingDir, encoding: 'utf8', stdio: 'pipe'
+            }).trim();
+        }
+        catch {
+            // fresh repo with no commits yet
+        }
+        // initialize scalability components
+        const concurrencyLimit = maxConcurrency || 3;
+        const executionQueue = new execution_queue_1.ExecutionQueue(concurrencyLimit);
+        const waveResizer = new wave_resizer_1.WaveResizer();
+        const adaptiveConcurrency = new wave_resizer_1.AdaptiveConcurrencyManager(concurrencyLimit, 10);
+        // initialize adaptive intelligence components
+        // save knowledge base in run dir, not target repo (avoids git checkout conflicts)
+        const knowledgeBase = new knowledge_base_1.KnowledgeBaseManager(runDir);
+        const metaAnalyzer = new meta_analyzer_1.MetaAnalyzer();
+        const context = {
+            plan,
+            runDir,
+            executionId,
+            startTime: new Date().toISOString(),
+            results: plan.steps.map(step => ({
+                stepNumber: step.stepNumber,
+                agentName: step.agentName,
+                status: 'pending'
+            })),
+            contextBroker,
+            mainBranch,
+            ...(baseCommitSha ? { baseCommitSha } : {}),
+            metricsCollector,
+            executionQueue,
+            queueStats: executionQueue.getStats(),
+            waveResizer,
+            adaptiveConcurrency,
+            knowledgeBase,
+            metaAnalyzer,
+            waveAnalyses: []
+        };
+        return context;
+    }
+    /**
+     * Execute plan with parallel swarm - independent steps run concurrently
+     */
+    async executeSwarm(plan, agents, runDir, options) {
+        const context = this.initializeSwarmExecution(plan, runDir, options?.maxConcurrency);
+        // Sanitize git state before starting. Previous crashed runs may have left
+        // unmerged files, staged changes, or an in-progress merge that would block
+        // branch creation, worktree setup, and post-step merge operations.
+        this.sanitizeGitState();
+        context.agents = agents;
+        context.qualityGatesTriggered = {
+            duplicateRefactorAdded: false,
+            readmeTruthAdded: false,
+            scaffoldFixAdded: false,
+            configFixAdded: false,
+            accessibilityFixAdded: false,
+            testCoverageFixAdded: false
+        };
+        // Initialize PR manager when --pr mode is set
+        if (options?.prMode) {
+            const prManager = new pr_manager_1.default(this.workingDir);
+            if (!prManager.isGhAvailable()) {
+                logger.error('  --pr requires gh CLI installed and authenticated. Run "gh auth login" first.');
+                process.exit(1);
+            }
+            context.prManager = prManager;
+            context.prUrls = new Map();
+        }
+        // Execution-header scaffolding (exec id, main branch, concurrency) is
+        // diagnostic detail; emit at debug level so --verbose surfaces it on
+        // stderr while default user output stays uncluttered.
+        logger.debug(`exec id ${context.executionId}`);
+        logger.debug(`main ${context.mainBranch}`);
+        logger.debug(`concurrency ${options?.maxConcurrency || 'unlimited'}`);
+        if (options?.confirmDeploy) {
+            logger.info(`  deployment   enabled (--confirm-deploy)`);
+        }
+        // Group steps by repo for multi-repo orchestration
+        const repoGroups = new Map();
+        for (const step of plan.steps) {
+            const repo = step.repo ?? process.cwd();
+            if (!repoGroups.has(repo))
+                repoGroups.set(repo, []);
+            repoGroups.get(repo).push(step);
+        }
+        if (repoGroups.size > 1) {
+            const presenter = require('./presenter');
+            const p = presenter.getPresenter();
+            p.print(`  ${p.dim('multi-repo')}  ${repoGroups.size} repos`);
+            for (const [repo, steps] of repoGroups) {
+                p.print(`    ${path.basename(repo)}  ${p.dim(`${steps.length} step${steps.length === 1 ? '' : 's'}`)}`);
+            }
+        }
+        // build dependency graph
+        const dependencyGraph = this.buildDependencyGraph(plan);
+        // identify waves of parallel execution
+        const executionWaves = this.identifyExecutionWaves(dependencyGraph);
+        context.totalWaves = executionWaves.length;
+        if (executionWaves.length > 1) {
+            const presenter = require('./presenter');
+            const p = presenter.getPresenter();
+            p.print(`  ${p.dim('plan')}     ${executionWaves.length} waves`);
+            p.blank();
+        }
+        // Pre-execution cost estimation
+        const costEstimator = new cost_estimator_1.CostEstimator(context.knowledgeBase);
+        const modelName = options?.model || (0, adapters_1.defaultModelForAdapter)(options?.cliAgent);
+        context.costEstimator = costEstimator;
+        context.costEstimate = costEstimator.estimate(plan, {
+            modelName,
+            fleetMode: !!options?.useInnerFleet,
+            qualityGatesEnabled: options?.qualityGates !== false,
+        });
+        context.stepCostRecords = [];
+        // Capture existing file inventory before agents run, so preservation rules
+        // can be injected into shared instructions and per-step prompts.
+        context.baselineSnapshot = (0, baseline_scanner_1.scanBaseline)(this.workingDir);
+        // Classify the goal and filter requirements by tier so agents only see
+        // what matters for this task type (backend, frontend, CLI, etc.)
+        const taskClassifier = new task_classifier_1.TaskClassifier();
+        const taskClassification = taskClassifier.classify(plan.goal || '');
+        const requirementFilter = new requirement_filter_1.RequirementFilter(tier_maps_1.TIER_MAPS);
+        const filtered = requirementFilter.filter(taskClassification);
+        context.filteredRequirements = filtered;
+        const tierInjection = requirementFilter.toPromptInjection(filtered);
+        // Write common prompt instructions to repo root so Copilot CLI picks them up natively.
+        // Per-step prompts only carry task-specific content; shared boilerplate lives here.
+        this.writeSharedInstructions(context.baselineSnapshot, tierInjection);
+        // Cache quality gates config once for the entire run
+        const gatesConfig = (0, quality_gates_1.load_quality_gates_config)(this.workingDir, options?.qualityGatesConfigPath);
+        // Scheduler loop: greedy as-soon-as-ready scheduling, lean-mode KB
+        // injection, optional /fleet dispatch, adaptive concurrency.
+        // See src/orchestrator/wave-scheduler-loop.ts
+        // for the INVARIANT on context.plan re-read (executeReplan may swap
+        // it mid-run; scheduler re-reads context.plan.steps every iteration).
+        try {
+            await (0, wave_scheduler_loop_1.runWaveLoop)(this, plan, agents, context, options);
+        }
+        catch (err) {
+            if ((0, fatal_run_error_1.isFatalRunError)(err)) {
+                // Account-level wall (usage-limit, auth, extended rate-limit) reached.
+                // Skip the failed-step replan, the quality-gate pipeline, and the
+                // post-run reporter — none of those can recover from "no agent
+                // calls will succeed". Persist a sentinel for the SWE-bench harness
+                // and rethrow so the CLI exits non-zero with the fatal kind.
+                const sentinel = {
+                    kind: err.fatalKind,
+                    message: err.message,
+                    evidence: err.evidence,
+                    stepNumber: err.stepNumber ?? null,
+                    agentName: err.agentName ?? null,
+                    executionId: context.executionId,
+                    timestamp: new Date().toISOString(),
+                };
+                try {
+                    fs.writeFileSync(path.join(runDir, 'fatal-run-error.json'), JSON.stringify(sentinel, null, 2), 'utf8');
+                }
+                catch {
+                    // Sentinel-write failure is non-fatal; the rethrown error still
+                    // surfaces the abort to the CLI exit handler.
+                }
+                logger.error(`\n  aborting: agent CLI reported unrecoverable ${err.fatalKind} error`);
+                logger.error(`  evidence: ${err.evidence}`);
+                logger.error(`  no replan or quality gate can recover from an account-level wall.`);
+                throw err;
+            }
+            throw err;
+        }
+        // Per-step execution summary. The wave-loop already prints the per-step
+        // verified/failed lines via LiveStatus; this block is intentionally
+        // suppressed to keep the post-run section quiet, leaving the final
+        // headline (printed by the CLI handler) as the user-visible signal.
+        const failedResults = context.results.filter(r => r.status === 'failed');
+        if (context.unmergedBranches && context.unmergedBranches.length > 0) {
+            logger.warn(`\n  ${context.unmergedBranches.length} branch${context.unmergedBranches.length === 1 ? '' : 'es'} could not merge (work preserved):`);
+            for (const um of context.unmergedBranches) {
+                logger.warn(`    step-${um.stepNumber} ${um.agentName} on ${um.branchName}`);
+            }
+        }
+        // Remove any remaining worktrees (failed or unmerged steps) so their
+        // leftover test files don't pollute recursive test runners during gates.
+        // mergeWaveBranches already cleaned merged steps; this catches the rest.
+        await this.cleanupRemainingWorktrees(context);
+        // Install dependencies if any agent added new ones to package.json.
+        // Without this, quality gates' `npm test` would fail on MODULE_NOT_FOUND
+        // for newly-added packages like express or cors.
+        await this.installDependenciesIfNeeded();
+        // Re-queue failed steps before quality gates so their objectives aren't silently
+        // dropped. A step that fails verification doesn't disappear — its required work
+        // is still in scope. Build a targeted repair task per failed step, include the
+        // original task text and the verification failure context, and run a replan pass
+        // so the repair executes on the current merged state before gates run against it.
+        const retriableFailures = context.results.filter(r => r.status === 'failed' && (r.retryCount ?? 0) < 3);
+        if (retriableFailures.length > 0) {
+            const completedStepNumbers = context.results
+                .filter(r => r.status === 'completed')
+                .map(r => r.stepNumber);
+            const maxCompletedStep = completedStepNumbers.length > 0
+                ? Math.max(...completedStepNumbers)
+                : 0;
+            const failedStepRetries = [];
+            for (const failed of retriableFailures) {
+                const originalStep = context.plan.steps.find(s => s.stepNumber === failed.stepNumber);
+                if (!originalStep)
+                    continue;
+                const failureDetail = failed.verificationResult?.failureContext ?? failed.error ?? 'Verification failed';
+                const retryTask = [
+                    `The previous attempt by ${originalStep.agentName} failed verification.`,
+                    `Failure reason:\n${failureDetail}`,
+                    ``,
+                    `Original task:`,
+                    originalStep.task,
+                ].join('\n');
+                failedStepRetries.push({
+                    agent: originalStep.agentName,
+                    task: retryTask,
+                    ...(maxCompletedStep > 0 ? { afterStep: maxCompletedStep } : {}),
+                });
+            }
+            if (failedStepRetries.length > 0) {
+                logger.info(`\n  re-queuing ${failedStepRetries.length} failed step${failedStepRetries.length === 1 ? '' : 's'}`);
+                await this.executeReplan(context, { retrySteps: [], addSteps: failedStepRetries }, agents, options);
+                // Re-run dep install in case the repair step added packages.
+                await this.installDependenciesIfNeeded();
+            }
+        }
+        // final quality gates run on the merged state (hard gate)
+        // this happens before auto-PR so we don't create a PR for a failing run
+        const gatesEnabled = options?.qualityGates !== false;
+        if (gatesEnabled) {
+            const pipelineResult = await (0, final_gates_remediation_1.runFinalGatesPipeline)(this, context, runDir, agents, gatesConfig, options);
+            if (!pipelineResult.passed && gatesConfig.failOnIssues) {
+                if (pipelineResult.remediationAttempted && failedResults.length === 0) {
+                    // All plan steps passed but remediation couldn't fully resolve
+                    // pre-existing quality gaps. Downgrade to a warning so the run
+                    // isn't marked failed for issues outside the plan's scope.
+                    const remaining = pipelineResult.finalGateResults
+                        .filter(r => r.status === 'fail')
+                        .map(r => `${r.id} (${r.issues.length} issues)`);
+                    logger.warn(`  quality gates still have issues after remediation: ${remaining.join(', ')}`);
+                    logger.warn('  treating as warning since all plan steps passed.');
+                }
+                else {
+                    logger.error('  quality gates failed. See report in:', pipelineResult.gatesOut);
+                    throw new Error('Quality gates failed');
+                }
+            }
+        }
+        // Final merge pass: sweep any branches the wave loop did not already
+        // merge. Header is suppressed because the wave loop's per-branch
+        // "merged step-N <agent>" lines (and any "(already merged)" follow-ups
+        // below) carry the signal on their own.
+        // Clean up any stale locks before final merge (e.g. from cancelled runs)
+        context.contextBroker.forceReleaseStaleLocks();
+        await this.mergeAllBranches(context);
+        // Metrics, cost attribution, session state, OWASP, KB recordRun, auto-PR.
+        // All of this lives in src/post-run-reporter.ts; the inline block was a
+        // pre-existing duplicate. See docs/post-run-diff-report.md for the
+        // behavioral diff that preceded this swap.
+        const postRunContext = context;
+        const postRunOptions = {};
+        if (options?.model !== undefined)
+            postRunOptions.model = options.model;
+        if (options?.cliAgent !== undefined)
+            postRunOptions.cliAgent = options.cliAgent;
+        if (options?.owaspReport !== undefined)
+            postRunOptions.owaspReport = options.owaspReport;
+        if (options?.strictIsolation !== undefined)
+            postRunOptions.strictIsolation = options.strictIsolation;
+        if (options?.enableExternal !== undefined)
+            postRunOptions.enableExternal = options.enableExternal;
+        if (options?.dryRun !== undefined)
+            postRunOptions.dryRun = options.dryRun;
+        if (options?.autoPR !== undefined)
+            postRunOptions.autoPR = options.autoPR;
+        await (0, post_run_reporter_1.runPostExecution)(this.workingDir, runDir, postRunContext, plan, postRunOptions);
+        return context;
+    }
+    /**
+     * Shared auto-remediation logic for quality gate failures -
+     * delegates to final-gates-remediation module. Kept as a thin private
+     * method so tests that invoke it via `(orch as any).buildRemediationStep`
+     * continue to work unchanged.
+     */
+    buildRemediationStep(gateResult, configEnabled, triggeredFlag, context, agents, taskDescription, warningMessage, afterStep, fallbackAgent) {
+        return (0, final_gates_remediation_1.buildRemediationStepForDelegate)(this, gateResult, configEnabled, triggeredFlag, context, agents, taskDescription, warningMessage, afterStep, fallbackAgent);
+    }
+    /**
+     * execute replan - delegates to replan-runner module. Public to satisfy
+     * `RemediationHost` and `ReplanHost`; callers outside the class should
+     * still treat it as an internal helper.
+     *
+     * WARNING: mutates context.plan by assignment. See replan-runner.ts
+     * for the full invariant comment.
+     */
+    async executeReplan(context, replanPayload, agents, options) {
+        return (0, replan_runner_1.executeReplan)(this, context, replanPayload, agents, options);
+    }
+    /**
+     * Execute a single step within the swarm - delegates to step-executor module.
+     * Public to satisfy `ReplanHost` and `StepExecutorHost`; callers outside
+     * the class should still treat it as an internal helper.
+     */
+    async executeStepInSwarm(step, agent, context, options) {
+        return (0, step_executor_1.executeStepInSwarm)(this, step, agent, context, options);
+    }
+    /** Build prompt for swarm step execution. Delegates to prompt-builder module. */
+    buildSwarmPrompt(step, agent, context, dependencyContext) {
+        // Pass the orchestrator's working dir so prompt-builder can read the
+        // target project's package.json to discover the real test gate.
+        return (0, prompt_builder_1.buildSwarmPrompt)(step, agent, { ...context, targetProjectRoot: this.workingDir }, dependencyContext);
+    }
+    /** Build dependency graph from plan. Delegates to wave-scheduler module. */
+    buildDependencyGraph(plan) {
+        return (0, wave_scheduler_1.buildDependencyGraph)(plan);
+    }
+    /** Identify waves of parallel execution (topological sort by levels). Delegates to wave-scheduler module. */
+    identifyExecutionWaves(graph) {
+        return (0, wave_scheduler_1.identifyExecutionWaves)(graph);
+    }
+    /**
+     * Create a git worktree for an agent - delegates to WorktreeManager.
+     * Public to satisfy `StepExecutorHost`.
+     */
+    async createAgentWorktree(branchName, fromBranch, runDir, stepNumber, repoDir) {
+        return this.worktreeManager.createAgentWorktree(branchName, fromBranch, runDir, stepNumber, repoDir);
+    }
+    /**
+     * Remove a git worktree after merge - delegates to WorktreeManager.
+     */
+    async removeAgentWorktree(worktreePath) {
+        return this.worktreeManager.removeAgentWorktree(worktreePath);
+    }
+    /**
+     * Remove all remaining worktree directories under runs/<id>/worktrees/.
+     * mergeWaveBranches cleans up merged steps, but failed or unmerged steps
+     * leave worktrees containing test files that recursive test runners
+     * (node --test, Jest, etc.) discover during quality gates.
+     */
+    async cleanupRemainingWorktrees(context) {
+        const worktreesDir = path.join(context.runDir, 'worktrees');
+        if (!fs.existsSync(worktreesDir))
+            return;
+        const entries = fs.readdirSync(worktreesDir, { withFileTypes: true });
+        const remainingDirs = entries.filter(e => e.isDirectory());
+        if (remainingDirs.length === 0)
+            return;
+        logger.info(`\n🧹 Cleaning up ${remainingDirs.length} remaining worktree(s) before quality gates...`);
+        for (const dir of remainingDirs) {
+            const worktreePath = path.join(worktreesDir, dir.name);
+            try {
+                await this.worktreeManager.removeAgentWorktree(worktreePath);
+            }
+            catch (err) {
+                // Force-remove if git worktree remove fails (e.g., already detached)
+                try {
+                    fs.rmSync(worktreePath, { recursive: true, force: true });
+                }
+                catch {
+                    // Best-effort cleanup; log but don't block execution
+                    logger.warn(`  could not remove worktree ${dir.name}: ${err.message}`);
+                }
+            }
+        }
+    }
+    /**
+     * Create a new git branch for an agent - delegates to WorktreeManager.
+     * Public to satisfy `ReplanHost`.
+     */
+    async createAgentBranch(branchName, fromBranch) {
+        return this.worktreeManager.createAgentBranch(branchName, fromBranch);
+    }
+    /**
+     * Merge completed branches to main. Delegates to BranchMerger with
+     * the appropriate context and tracks unmerged branches on the context.
+     * Public to satisfy `ReplanHost`.
+     */
+    async mergeWaveBranches(completedResults, context, options) {
+        const mergeCtx = {
+            mainBranch: context.mainBranch,
+            contextBroker: context.contextBroker,
+            prManager: context.prManager,
+        };
+        const unmerged = await this.branchMerger.mergeWaveBranches(completedResults, mergeCtx, options?.prMode, context.prUrls, context.stepCostRecords, context.plan);
+        if (unmerged.length > 0) {
+            if (!context.unmergedBranches)
+                context.unmergedBranches = [];
+            context.unmergedBranches.push(...unmerged);
+        }
+        // Remove worktrees for merged steps so their leftover test files
+        // don't confuse recursive test runners (node --test, Jest, etc.)
+        const worktreesDir = path.join(context.runDir, 'worktrees');
+        for (const result of completedResults) {
+            if (result.branchName) {
+                const worktreePath = path.join(worktreesDir, `step-${result.stepNumber}`);
+                await this.worktreeManager.removeAgentWorktree(worktreePath);
+            }
+        }
+    }
+    /**
+     * Merge all agent branches back to main and clean up worktrees
+     */
+    /**
+     * Merge all agent branches back to main - delegates to BranchMerger.
+     */
+    async mergeAllBranches(context) {
+        const mergeCtx = {
+            mainBranch: context.mainBranch,
+            contextBroker: context.contextBroker,
+            prManager: context.prManager,
+        };
+        const unmerged = await this.branchMerger.mergeAllBranches(context.results, context.runDir, mergeCtx);
+        if (unmerged.length > 0) {
+            if (!context.unmergedBranches)
+                context.unmergedBranches = [];
+            context.unmergedBranches.push(...unmerged);
+        }
+    }
+    /**
+     * Detect whether agents introduced new dependencies and install them - delegates to git-state-utils.
+     */
+    async installDependenciesIfNeeded() {
+        return (0, git_state_utils_1.installDependenciesIfNeeded)(this.workingDir);
+    }
+    /**
+     * Switch to a git branch - delegates to WorktreeManager.
+     * Public to satisfy `ReplanHost`.
+     */
+    async switchBranch(branchName) {
+        return this.worktreeManager.switchBranch(branchName);
+    }
+    /**
+     * Merge a branch with conflict detection
+     */
+    /**
+     * Wait for resume signal - delegates to PauseController.
+     */
+    async waitForResume() {
+        return this.pauseController.waitForResume();
+    }
+    /**
+     * Rebase a branch onto main and retry the merge - delegates to BranchMerger.
+     */
+    tryRebaseAndMerge(branchName, context) {
+        const mergeCtx = {
+            mainBranch: context.mainBranch,
+            contextBroker: context.contextBroker,
+            prManager: context.prManager,
+        };
+        return this.branchMerger.tryRebaseAndMerge(branchName, mergeCtx);
+    }
+    /**
+     * Merge a single branch via git merge --no-ff - delegates to BranchMerger.
+     */
+    async mergeBranch(branchName, context) {
+        const mergeCtx = {
+            mainBranch: context.mainBranch,
+            contextBroker: context.contextBroker,
+            prManager: context.prManager,
+        };
+        return this.branchMerger.mergeBranch(branchName, mergeCtx);
+    }
+    /**
+     * Get current git branch - delegates to WorktreeManager.
+     */
+    getCurrentBranch() {
+        return this.worktreeManager.getCurrentBranch();
+    }
+    /**
+     * Ensure repo has at least one commit - delegates to WorktreeManager.
+     */
+    ensureInitialCommit() {
+        this.worktreeManager.ensureInitialCommit();
+    }
+    /**
+     * Clean up leftover git state from crashed runs - delegates to git-state-utils.
+     */
+    sanitizeGitState() {
+        (0, git_state_utils_1.sanitizeGitState)(this.workingDir);
+    }
+    generateExecutionId() {
+        return `swarm-${new Date().toISOString().replace(/[:.]/g, '-')}`;
+    }
+    /**
+    /** Analyze commit quality and flag anti-patterns. Delegates to commit-quality-analyzer module. */
+    async analyzeCommitQuality(commits, stepNumber, agentName, _context) {
+        return (0, commit_quality_analyzer_1.analyzeCommitQuality)(commits, stepNumber, agentName);
+    }
+    /**
+     * Write .copilot-instructions.md to the repo root with boilerplate every agent needs.
+     * Copilot CLI picks this up automatically, so per-step prompts stay minimal.
+     */
+    writeSharedInstructions(baseline, tierInjection) {
+        (0, prompt_builder_1.writeSharedInstructions)(this.workingDir, baseline, tierInjection);
+    }
+    /**
+     * Run meta-analysis off the critical path - delegates to async-meta-analysis module.
+     */
+    runAsyncMetaAnalysis(context, plan, runDir, completedSteps) {
+        (0, async_meta_analysis_1.runAsyncMetaAnalysis)(context, plan, runDir, completedSteps);
+    }
+    /**
+     * execute optional deployment for devops_pro when --confirm-deploy is set
+     * captures preview URL and stores in context
+     */
+    async executeOptionalDeployment(step, agent, context, options) {
+        await (0, deployment_handler_1.executeOptionalDeployment)(this.workingDir, step, agent, {
+            runDir: context.runDir,
+            executionId: context.executionId,
+            results: context.results,
+            deployments: context.deployments,
+        }, options);
+    }
+}
+exports.SwarmOrchestrator = SwarmOrchestrator;
+exports.default = SwarmOrchestrator;