swarm-engine 1.0.0

package/dist/runtime/engine.js

@@ -0,0 +1,969 @@
+import { emptyUsageStats, mergeUsageStats, generateId, } from '../core/types.js';
+import { AgentExecutor } from './executor.js';
+import { saveCheckpoint, loadCheckpoint } from '../core/checkpoint.js';
+import { PatternRegistry } from '../core/patterns.js';
+import { WorktreeManager } from './worktree.js';
+import { CompactionManager } from './compaction.js';
+import { ContextDistiller } from './distiller.js';
+import { Verifier } from './verifier.js';
+import { rewritePlan } from './rewriter.js';
+import { CostModel } from './cost-model.js';
+import { PlanSearcher } from './plan-search.js';
+import { StatsCollector } from './stats.js';
+import { AdaptiveReplanner } from './adaptive.js';
+import { ReflectionEngine } from './reflexion.js';
+import { TraceStore } from './traces.js';
+import { HeuristicStore } from './heuristics.js';
+import { KnowledgeCompounder } from './compounder.js';
+import { ModelRouter } from './model-router.js';
+import { AutonomyTracker } from './autonomy.js';
+import { ContinuousVerifier } from './verifier.js';
+import { optimizeForCache, estimateCacheSavings } from './cache-optimizer.js';
+import { classifyTaskComplexity, selectStartingTier } from './cascade.js';
+import { createLivingSpec, updateSpecFromPhase, formatLivingSpec } from './living-spec.js';
+import { estimateTokens } from '../utils/tokens.js';
+import { redactSecrets } from '../utils/redact.js';
+import { join } from 'path';
+import { existsSync, mkdirSync, writeFileSync, unlinkSync } from 'fs';
+import { randomUUID } from 'crypto';
+/**
+ * The Swarm Orchestration Engine.
+ *
+ * Manages the lifecycle of orchestrations — multi-phase workflows
+ * that dispatch parallel agents and manage dependencies between phases.
+ */
+export class SwarmEngine {
+    registry;
+    bus;
+    executor;
+    log;
+    patterns;
+    options;
+    orchestrations = new Map();
+    phaseOutputs = new Map();
+    abortController = new AbortController();
+    worktreeManager = null;
+    compaction;
+    distiller = null;
+    verifier;
+    costModel;
+    replanner;
+    reflectionEngine;
+    reflections = [];
+    traceStore = null;
+    heuristicStore = null;
+    stats;
+    modelRouter = null;
+    autonomyTracker = null;
+    compounder = null;
+    signalHandlers = [];
+    sharedContextFiles = [];
+    livingSpec = null;
+    constructor(options) {
+        this.options = options;
+        this.registry = options.registry;
+        this.bus = options.bus;
+        this.executor = new AgentExecutor({
+            bus: this.bus,
+            logger: options.logger,
+            cwd: options.cwd,
+            mock: options.mock ?? false,
+            permissionMode: options.permissionMode ?? 'default',
+            defaultBackend: options.defaultBackend,
+            permissionProfile: options.permissionProfile,
+            snapshotsEnabled: options.snapshotsEnabled,
+            doomLoopDetection: options.doomLoopDetection,
+            paneManager: options.paneManager,
+        });
+        this.log = options.logger.child('engine');
+        this.patterns = options.patterns ?? new PatternRegistry();
+        this.compaction = new CompactionManager(options.compactionEnabled === false ? { enabled: false } : undefined);
+        this.distiller = options.distillation !== false ? new ContextDistiller() : null;
+        this.verifier = new Verifier(options.cwd ?? process.cwd());
+        this.stats = new StatsCollector();
+        this.stats.attachToEventBus(this.bus, undefined);
+        this.costModel = new CostModel(this.stats);
+        this.reflectionEngine = new ReflectionEngine();
+        try {
+            this.traceStore = new TraceStore();
+        }
+        catch (e) {
+            this.log.warn('TraceStore init failed', { error: e instanceof Error ? e.message : e });
+        }
+        this.replanner = new AdaptiveReplanner(options.logger, this.traceStore ?? undefined);
+        try {
+            this.heuristicStore = new HeuristicStore();
+        }
+        catch (e) {
+            this.log.warn('HeuristicStore init failed', { error: e instanceof Error ? e.message : e });
+        }
+        try {
+            this.modelRouter = new ModelRouter();
+        }
+        catch (e) {
+            this.log.warn('ModelRouter init failed', { error: e instanceof Error ? e.message : e });
+        }
+        try {
+            this.autonomyTracker = new AutonomyTracker();
+        }
+        catch (e) {
+            this.log.warn('AutonomyTracker init failed', { error: e instanceof Error ? e.message : e });
+        }
+        try {
+            this.compounder = new KnowledgeCompounder();
+        }
+        catch (e) {
+            this.log.warn('KnowledgeCompounder init failed', { error: e instanceof Error ? e.message : e });
+        }
+        if (options.worktreeEnabled) {
+            try {
+                this.worktreeManager = new WorktreeManager(options.cwd);
+            }
+            catch { /* not a git repo */ }
+        }
+        if (options.pluginLoader) {
+            options.pluginLoader.wireHooks(this.bus);
+        }
+        this.setupSignalHandlers();
+    }
+    /**
+     * Execute an orchestration from config.
+     */
+    async execute(config) {
+        // Re-use existing instance if present (e.g., when resuming from checkpoint)
+        const orchestration = this.orchestrations.get(config.id) ?? this.createInstance(config);
+        this.orchestrations.set(config.id, orchestration);
+        this.log.info(`Starting orchestration: ${config.name}`, {
+            pattern: config.pattern,
+            phases: config.phases.length,
+        });
+        this.bus.emit('orchestration:start', {
+            id: config.id,
+            name: config.name,
+            pattern: config.pattern,
+            phaseCount: config.phases.length,
+        }, 'engine');
+        orchestration.status = 'running';
+        orchestration.startedAt = new Date();
+        this.phaseOutputs = new Map();
+        this.reflections = [];
+        this.sharedContextFiles = [];
+        this.abortController = new AbortController();
+        this.livingSpec = createLivingSpec(config.description);
+        // Start continuous verification
+        let continuousVerifier = null;
+        if (this.verifier) {
+            continuousVerifier = new ContinuousVerifier(this.verifier, this.bus);
+            continuousVerifier.start();
+        }
+        try {
+            // Execute phases using work-queue approach (handles DAGs correctly)
+            // If resuming, seed completed phases so the DAG executor skips them
+            const completed = new Set();
+            for (const phase of orchestration.phases) {
+                if (phase.status === 'completed') {
+                    completed.add(phase.config.name);
+                }
+            }
+            while (completed.size < orchestration.phases.length) {
+                // Check if abort was requested
+                if (this.abortController.signal.aborted) {
+                    orchestration.status = 'cancelled';
+                    break;
+                }
+                // Find all runnable phases (dependencies met, not yet completed)
+                const runnable = orchestration.phases.filter(p => {
+                    if (completed.has(p.config.name))
+                        return false;
+                    if (p.status === 'failed')
+                        return false;
+                    const deps = p.config.dependsOn ?? [];
+                    return deps.every(d => completed.has(d));
+                });
+                if (runnable.length === 0) {
+                    // No runnable phases — either all done or deadlocked
+                    const incomplete = orchestration.phases.filter(p => !completed.has(p.config.name) && p.status !== 'failed');
+                    if (incomplete.length > 0) {
+                        // Deadlock — blocked phases with unmet dependencies
+                        for (const p of incomplete) {
+                            p.status = 'blocked';
+                        }
+                        orchestration.status = 'failed';
+                        this.log.error('Orchestration deadlocked: blocked phases with unmet dependencies', {
+                            blocked: incomplete.map(p => p.config.name),
+                        });
+                    }
+                    break;
+                }
+                // Execute runnable phases (could be parallel if multiple are ready)
+                for (const phase of runnable) {
+                    orchestration.currentPhase = orchestration.phases.indexOf(phase);
+                    // Check for approval gate
+                    if (phase.config.requiresApproval) {
+                        this.log.info(`Phase requires approval: ${phase.config.name}`);
+                        this.bus.emit('orchestration:paused', {
+                            orchestrationId: orchestration.config.id,
+                            phase: phase.config.name,
+                            agentCount: phase.config.agents.length,
+                        }, 'engine');
+                        // In interactive mode, wait for approval
+                        if (!this.options.nonInteractive) {
+                            const approved = await this.requestApproval(phase.config.name, phase.config.agents);
+                            if (!approved) {
+                                phase.status = 'skipped';
+                                this.log.info(`Phase skipped (not approved): ${phase.config.name}`);
+                                completed.add(phase.config.name);
+                                continue;
+                            }
+                        }
+                    }
+                    const outputs = await this.executePhase(orchestration, phase);
+                    this.phaseOutputs.set(phase.config.name, outputs);
+                    if (phase.status === 'completed') {
+                        completed.add(phase.config.name);
+                    }
+                    else if (phase.status === 'failed') {
+                        orchestration.status = 'failed';
+                        break;
+                    }
+                }
+                if (orchestration.status === 'failed')
+                    break;
+                // Check cost budget after each batch of phases
+                if (orchestration.config.costBudget) {
+                    const spent = orchestration.phases
+                        .filter(p => p.status === 'completed')
+                        .reduce((sum, p) => sum + p.usage.costUsd, 0);
+                    if (spent >= orchestration.config.costBudget) {
+                        orchestration.status = 'failed';
+                        this.log.warn(`Cost budget exceeded: $${spent.toFixed(2)} >= $${orchestration.config.costBudget}`, {
+                            spent, budget: orchestration.config.costBudget,
+                        });
+                        this.bus.emit('system:warning', {
+                            reason: 'budget-exceeded',
+                            id: orchestration.config.id,
+                            spent,
+                            budget: orchestration.config.costBudget,
+                        }, 'engine');
+                        break;
+                    }
+                }
+            }
+            if (orchestration.status !== 'failed') {
+                orchestration.status = 'completed';
+            }
+        }
+        catch (error) {
+            orchestration.status = 'failed';
+            this.log.error(`Orchestration failed: ${config.name}`, {
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+        orchestration.completedAt = new Date();
+        continuousVerifier?.stop();
+        // Clean up shared context files
+        for (const f of this.sharedContextFiles) {
+            try {
+                unlinkSync(f);
+            }
+            catch { }
+        }
+        this.sharedContextFiles = [];
+        // Build phase data once for all consumers (avoids 4x redundant mapping)
+        const phaseData = orchestration.phases.map(p => ({
+            name: p.config.name,
+            status: p.status,
+            agentCount: p.agents.length,
+            tokens: p.usage.totalTokens,
+            durationMs: p.usage.durationMs,
+            confidence: p.agents[0]?.result?.confidence ?? 'unknown',
+        }));
+        const traceData = {
+            orchestrationId: config.id,
+            task: config.description,
+            pattern: config.pattern,
+            status: orchestration.status,
+            totalTokens: orchestration.usage.totalTokens,
+            costUsd: orchestration.usage.costUsd,
+            durationMs: orchestration.usage.durationMs,
+            phaseCount: orchestration.phases.length,
+            agentCount: orchestration.phases.reduce((n, p) => n + p.agents.length, 0),
+            phases: phaseData,
+            reflections: this.reflections.map(r => redactSecrets(r)),
+        };
+        // Store execution trace for learning
+        if (this.traceStore) {
+            try {
+                this.traceStore.store(traceData);
+            }
+            catch { /* Don't fail orchestration if trace storage fails */ }
+            // Extract heuristics from the trace for future learning
+            if (this.heuristicStore) {
+                try {
+                    this.heuristicStore.extractFromTrace(traceData);
+                }
+                catch { /* Don't fail orchestration if heuristic extraction fails */ }
+            }
+            // Auto-compound knowledge from completed orchestrations
+            if (orchestration.status === 'completed' && this.compounder) {
+                try {
+                    const doc = this.compounder.extractFromTrace({ ...traceData, status: 'completed' }, this.reflections);
+                    if (doc)
+                        this.compounder.store(doc);
+                }
+                catch { /* Don't fail orchestration if compounding fails */ }
+            }
+            // Auto-capture outcomes to memory
+            try {
+                const { traceToMemoryEntries } = await import('./traces.js');
+                const memEntries = traceToMemoryEntries(traceData);
+                // Store in memory if SwarmMemory is available
+                let memory;
+                try {
+                    const { SwarmMemory } = await import('../memory/index.js');
+                    memory = new SwarmMemory();
+                    for (const entry of memEntries) {
+                        memory.store({ type: entry.type, title: entry.title, content: entry.content });
+                    }
+                }
+                catch { /* Memory not available */ }
+                finally {
+                    try {
+                        memory?.close();
+                    }
+                    catch { }
+                }
+            }
+            catch { /* Don't fail orchestration */ }
+        }
+        // Record model outcomes for routing
+        if (this.modelRouter) {
+            for (const phase of orchestration.phases) {
+                for (const agent of phase.agents) {
+                    const model = agent.config.model;
+                    if (!model)
+                        continue;
+                    const success = agent.status === 'shutdown' || agent.status === 'idle';
+                    this.modelRouter.record(model, agent.config.name, success, success ? 1.0 : 0.0);
+                }
+            }
+        }
+        // Record autonomy outcome
+        if (this.autonomyTracker) {
+            const success = orchestration.status === 'completed';
+            const intervention = orchestration.phases.some(p => p.config.requiresApproval);
+            this.autonomyTracker.record(config.pattern, success, intervention);
+        }
+        // Compute total usage
+        orchestration.usage = orchestration.phases.reduce((total, phase) => mergeUsageStats(total, phase.usage), emptyUsageStats());
+        this.bus.emit(orchestration.status === 'completed' ? 'orchestration:complete' : 'orchestration:failed', {
+            id: config.id,
+            name: config.name,
+            status: orchestration.status,
+            usage: orchestration.usage,
+            durationMs: orchestration.completedAt.getTime() - (orchestration.startedAt?.getTime() ?? 0),
+        }, 'engine');
+        this.log.info(`Orchestration ${orchestration.status}: ${config.name}`, {
+            usage: orchestration.usage,
+        });
+        // Prune terminal agent instances to free memory
+        this.registry.pruneTerminalInstances();
+        return orchestration;
+    }
+    /**
+     * Execute a named pattern with a task description.
+     */
+    async runPattern(patternName, task, options) {
+        const pattern = this.patterns.get(patternName);
+        if (!pattern) {
+            throw new Error(`Unknown pattern: ${patternName}. Available: ${this.patterns.list().map(p => p.name).join(', ')}`);
+        }
+        // Inject task into all agent prompts
+        const config = {
+            id: generateId(),
+            name: `${patternName}: ${task.slice(0, 50)}`,
+            description: task,
+            pattern: patternName,
+            phases: pattern.phases.map(phase => ({
+                ...phase,
+                agents: phase.agents.map(a => ({
+                    ...a,
+                    prompt: `${task}\n\n${a.prompt ?? ''}`.trim(),
+                })),
+            })),
+            costBudget: options?.costBudget,
+        };
+        // Substitute pattern parameters into agent prompts
+        if (options?.params && pattern.parameters) {
+            for (const phase of config.phases) {
+                for (const agent of phase.agents) {
+                    if (agent.prompt) {
+                        for (const [key, value] of Object.entries(options.params)) {
+                            // Use string replacement instead of regex to avoid ReDoS from user-controlled keys
+                            const placeholder = '${' + key + '}';
+                            agent.prompt = agent.prompt.split(placeholder).join(String(value));
+                        }
+                    }
+                }
+            }
+        }
+        return this.execute(config);
+    }
+    /**
+     * Generate a serializable execution plan WITHOUT executing anything.
+     * Useful for previewing what an orchestration will do before running it.
+     */
+    plan(patternName, task, options) {
+        const pattern = this.patterns.get(patternName);
+        if (!pattern) {
+            throw new Error(`Unknown pattern: ${patternName}. Available: ${this.patterns.list().map(p => p.name).join(', ')}`);
+        }
+        // Check for similar past traces to inform planning
+        if (this.traceStore) {
+            try {
+                const similar = this.traceStore.findSimilar(task, 3);
+                if (similar.length > 0) {
+                    let traceContext = '';
+                    const best = similar.find(t => t.status === 'completed');
+                    if (best) {
+                        traceContext = `Past successful orchestration for similar task used pattern "${best.pattern}" with ${best.agentCount} agents (${best.totalTokens} tokens, ${Math.round(best.durationMs / 1000)}s).`;
+                    }
+                    const failed = similar.find(t => t.status === 'failed');
+                    if (failed && failed.reflections.length > 0) {
+                        traceContext += ` Previous attempt failed. Lessons: ${failed.reflections[0]?.slice(0, 200)}`;
+                    }
+                    if (traceContext) {
+                        this.log.info('Found similar past traces', { context: traceContext.slice(0, 200) });
+                    }
+                }
+            }
+            catch { /* Don't fail planning if trace lookup fails */ }
+        }
+        const id = generateId();
+        const phases = pattern.phases.map(phase => ({
+            name: phase.name,
+            parallel: phase.parallel,
+            dependsOn: phase.dependsOn,
+            requiresApproval: phase.requiresApproval,
+            tokenBudget: phase.tokenBudget,
+            agents: phase.agents.map(a => {
+                const agentConfig = this.registry.getConfig(a.type);
+                return {
+                    name: a.name,
+                    type: a.type,
+                    model: a.model ?? agentConfig?.model ?? 'sonnet',
+                    backend: a.backend ?? agentConfig?.backend,
+                    prompt: `${task}\n\n${a.prompt ?? agentConfig?.description ?? ''}`.trim(),
+                    permissionProfile: agentConfig?.permissionProfile,
+                    worktree: a.worktree,
+                };
+            }),
+        }));
+        // Substitute pattern parameters if provided
+        if (options?.params && pattern.parameters) {
+            for (const phase of phases) {
+                for (const agent of phase.agents) {
+                    for (const [key, value] of Object.entries(options.params)) {
+                        const placeholder = '${' + key + '}';
+                        agent.prompt = agent.prompt.split(placeholder).join(String(value));
+                    }
+                }
+            }
+        }
+        const planResult = {
+            id,
+            name: `${patternName}: ${task.slice(0, 50)}`,
+            task,
+            pattern: patternName,
+            phases,
+            costBudget: options?.costBudget,
+            createdAt: new Date().toISOString(),
+        };
+        // Apply plan rewriting rules
+        const { plan: rewrittenPlan, rewrites } = rewritePlan(planResult);
+        if (rewrites.length > 0) {
+            this.log.info('Plan rewritten', { rewrites });
+        }
+        // Retrieve relevant heuristics and inject into first phase
+        if (this.heuristicStore) {
+            try {
+                const heuristics = this.heuristicStore.retrieve(task);
+                if (heuristics.length > 0) {
+                    const context = this.heuristicStore.formatForContext(heuristics);
+                    for (const agent of rewrittenPlan.phases[0]?.agents ?? []) {
+                        agent.prompt = `${context}\n\n${agent.prompt}`;
+                    }
+                    this.log.info('Injected heuristics into plan', { count: heuristics.length });
+                }
+            }
+            catch { /* Don't fail planning if heuristic retrieval fails */ }
+        }
+        // Inject relevant past solutions from knowledge compounder (singleton)
+        if (this.compounder) {
+            try {
+                const solutions = this.compounder.findRelevant(task, 3);
+                if (solutions.length > 0) {
+                    const solutionContext = this.compounder.formatForContext(solutions);
+                    for (const agent of rewrittenPlan.phases[0]?.agents ?? []) {
+                        agent.prompt = `${solutionContext}\n\n${agent.prompt}`;
+                    }
+                    this.log.info('Injected past solutions into plan', { count: solutions.length });
+                }
+            }
+            catch { /* Don't fail planning if solution retrieval fails */ }
+        }
+        // Search over candidate plans to find the best one
+        const searcher = new PlanSearcher(this.costModel, this.traceStore ?? undefined);
+        const candidates = searcher.search(rewrittenPlan, {
+            maxCandidates: 3,
+            constraints: options?.costBudget ? { maxCostUsd: options.costBudget } : undefined,
+        });
+        // Use the best candidate
+        const bestPlan = candidates[0]?.plan ?? rewrittenPlan;
+        // Store search metadata
+        bestPlan.estimates = this.costModel.estimate(bestPlan);
+        bestPlan.rewrites = rewrites;
+        if (candidates.length > 1) {
+            bestPlan._alternatives = candidates.slice(1).map(c => ({
+                source: c.source,
+                costUsd: c.cost.costUsd,
+                quality: c.cost.qualityScore,
+            }));
+        }
+        return bestPlan;
+    }
+    /**
+     * Execute a single phase.
+     */
+    async executePhase(orchestration, phase) {
+        phase.status = 'running';
+        phase.startedAt = new Date();
+        // Evaluate agent dropout before executing
+        if (phase.config.agents.length > 1) {
+            const dropout = this.replanner.evaluateDropout(orchestration, phase.config);
+            if (dropout) {
+                this.log.info(`Agent dropout: ${dropout.reason}`);
+                phase.config.agents = phase.config.agents.filter(a => dropout.agentsToKeep.includes(a.name));
+                this.bus.emit('system:warning', { type: 'agent-dropout', ...dropout }, 'adaptive');
+            }
+        }
+        const maxRetries = phase.config.maxRetries ?? 2;
+        this.log.info(`Phase started: ${phase.config.name}`, {
+            agents: phase.config.agents.length,
+            parallel: phase.config.parallel,
+        });
+        this.bus.emit('orchestration:phase-start', {
+            orchestrationId: orchestration.config.id,
+            phase: phase.config.name,
+            agentCount: phase.config.agents.length,
+            parallel: phase.config.parallel,
+        }, 'engine');
+        try {
+            if (phase.config.parallel) {
+                // Run all agents in parallel (with retry)
+                const results = await Promise.allSettled(phase.config.agents.map(assignment => this.executeAgentWithRetry(assignment, phase, orchestration, maxRetries)));
+                // Log cache savings estimate for parallel phases
+                if (phase.config.agents.length > 1) {
+                    const phaseContext = this.compaction.buildContextPrefix(this.phaseOutputs);
+                    const sharedTokens = estimateTokens(`## Orchestration: ${orchestration.config.name}\nPattern: ${orchestration.config.pattern}\n\n${phaseContext}`);
+                    if (sharedTokens > 0) {
+                        const savings = estimateCacheSavings(sharedTokens, phase.config.agents.length, 3.0);
+                        this.log.info(`Cache optimization: ${savings.savingsPercent}% estimated savings on shared prefix (${phase.config.agents.length} agents)`, savings);
+                    }
+                }
+                // Check for failures
+                const failures = results.filter(r => r.status === 'rejected');
+                if (failures.length > 0) {
+                    const failureCount = failures.length;
+                    this.log.warn(`Phase had ${failureCount} agent failures`, {
+                        phase: phase.config.name,
+                    });
+                    // If all agents failed, phase fails
+                    if (failures.length === phase.config.agents.length) {
+                        phase.status = 'failed';
+                    }
+                    else {
+                        phase.status = 'completed'; // Partial success
+                    }
+                }
+                else {
+                    phase.status = 'completed';
+                }
+            }
+            else {
+                // Run agents sequentially (with retry)
+                for (const assignment of phase.config.agents) {
+                    await this.executeAgentWithRetry(assignment, phase, orchestration, maxRetries);
+                    // Check phase token budget after each agent
+                    if (phase.config.tokenBudget) {
+                        const phaseTokens = phase.agents.reduce((sum, a) => sum + a.usage.totalTokens, 0);
+                        if (phaseTokens >= phase.config.tokenBudget) {
+                            this.log.warn(`Phase token budget exceeded: ${phaseTokens} >= ${phase.config.tokenBudget}`, {
+                                phase: phase.config.name,
+                            });
+                            break;
+                        }
+                    }
+                }
+                phase.status = 'completed';
+            }
+        }
+        catch (error) {
+            phase.status = 'failed';
+            throw error;
+        }
+        phase.completedAt = new Date();
+        phase.usage = phase.agents.reduce((total, agent) => mergeUsageStats(total, agent.usage), emptyUsageStats());
+        // Run verification after implementation phases
+        if (this.verifier && (phase.config.name.includes('implement') || phase.config.name.includes('integrate'))) {
+            const results = await this.verifier.verify();
+            const summary = Verifier.summarize(results);
+            this.log.info(`Verification: ${summary}`, { phase: phase.config.name });
+            this.bus.emit('system:warning', { verification: summary, results }, 'verifier');
+        }
+        // Adaptive replanning based on phase results
+        const adaptation = this.replanner.analyze(orchestration, phase);
+        if (adaptation) {
+            this.replanner.apply(orchestration, adaptation);
+            this.bus.emit('system:warning', {
+                type: 'adaptive-replan',
+                reason: adaptation.reason,
+                skipped: adaptation.skipPhases,
+                overrides: Object.keys(adaptation.modelOverrides).length,
+            }, 'replanner');
+        }
+        this.bus.emit('orchestration:phase-complete', {
+            orchestrationId: orchestration.config.id,
+            phase: phase.config.name,
+            status: phase.status,
+            usage: phase.usage,
+        }, 'engine');
+        // Save checkpoint after each phase
+        saveCheckpoint(orchestration);
+        this.log.info(`Phase ${phase.status}: ${phase.config.name}`, {
+            agents: phase.agents.length,
+            usage: phase.usage,
+        });
+        // Collect agent outputs for inter-phase context
+        const outputs = phase.agents
+            .filter(a => a.result?.output)
+            .map(a => `[${a.config.name}]: ${a.result.output.slice(0, 2000)}`);
+        // Update living spec with phase outputs
+        if (this.livingSpec) {
+            this.livingSpec = updateSpecFromPhase(this.livingSpec, phase.config.name, outputs);
+        }
+        // Generate reflection and inject into outputs for next phase
+        const reflection = this.reflectionEngine.reflect(phase);
+        const reflectionText = this.reflectionEngine.format(reflection);
+        this.reflections.push(reflectionText);
+        outputs.push(reflectionText);
+        // Distill outputs if they're large
+        if (this.distiller) {
+            const distilled = await this.distiller.distill(outputs, phase.config.name);
+            return [distilled];
+        }
+        return outputs;
+    }
+    /**
+     * Execute a single agent within a phase.
+     */
+    async executeAgent(assignment, phase, orchestration) {
+        // Spawn from registry, passing all assignment overrides
+        const instance = this.registry.spawn(assignment.type, {
+            name: assignment.name,
+            model: assignment.model,
+            backend: assignment.backend,
+            backendModel: assignment.backendModel,
+        });
+        phase.agents.push(instance);
+        // Build task prompt with cache-friendly ordering:
+        // Shared prefix (orchestration + phase context) comes first for API cache hits,
+        // agent-specific content (definition + task) comes last.
+        const orchestrationContext = `## Orchestration: ${orchestration.config.name}\nPattern: ${orchestration.config.pattern}`;
+        const phaseContext = this.compaction.buildContextPrefix(this.phaseOutputs);
+        const agentPrompt = instance.config.prompt;
+        const baseTask = assignment.prompt || `Execute task as ${assignment.type}`;
+        const optimized = optimizeForCache(orchestrationContext, phaseContext, agentPrompt, baseTask);
+        // For parallel phases with large shared prefix, use shared context file
+        const sharedContextPath = phase.config.parallel
+            ? this.writeSharedContext(optimized.sharedPrefix)
+            : null;
+        // Cascade model selection: if no explicit model override, pick starting tier by complexity
+        if (!assignment.model) {
+            const complexity = classifyTaskComplexity(baseTask);
+            const startTier = selectStartingTier(complexity);
+            if (startTier !== instance.config.model) {
+                instance.config.model = startTier;
+            }
+        }
+        // Inject living spec into task context
+        const specPrefix = this.livingSpec ? formatLivingSpec(this.livingSpec) + '\n\n' : '';
+        const task = sharedContextPath
+            ? `Read the shared context file at ${sharedContextPath} first, then:\n\n${specPrefix}${optimized.agentSuffix}`
+            : `${specPrefix}${optimized.full}`;
+        // Transition to running
+        this.registry.updateStatus(instance.id, 'running');
+        // Create worktree if enabled and assignment requests it
+        let worktreeId;
+        if (this.worktreeManager && assignment.worktree) {
+            try {
+                const wt = this.worktreeManager.create(instance.id, assignment.name);
+                worktreeId = wt.id;
+                this.bus.emit('worktree:created', { agentId: instance.id, worktreeId: wt.id, path: wt.path }, instance.id);
+            }
+            catch (err) {
+                this.log.warn(`Failed to create worktree for ${assignment.name}: ${err}`);
+            }
+        }
+        // Execute with timeout
+        const timeoutMs = (instance.config.timeout ?? 300) * 1000; // default 5 min
+        let timer;
+        const timeoutPromise = new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new Error(`Agent timeout after ${timeoutMs / 1000}s`)), timeoutMs);
+        });
+        try {
+            await Promise.race([
+                this.executor.execute(instance, task),
+                timeoutPromise,
+            ]);
+            clearTimeout(timer);
+            // Merge worktree if created
+            if (worktreeId && this.worktreeManager) {
+                try {
+                    this.worktreeManager.merge(worktreeId);
+                    this.bus.emit('worktree:merged', { agentId: instance.id, worktreeId }, instance.id);
+                }
+                catch (err) {
+                    this.log.warn(`Failed to merge worktree ${worktreeId}: ${err}`);
+                }
+            }
+            // Transition to idle (completed successfully)
+            this.registry.updateStatus(instance.id, 'idle');
+            // Then shutdown
+            this.registry.updateStatus(instance.id, 'shutdown');
+            return instance;
+        }
+        catch (error) {
+            clearTimeout(timer);
+            if (String(error).includes('timeout')) {
+                this.registry.updateStatus(instance.id, 'timeout');
+            }
+            else {
+                this.registry.updateStatus(instance.id, 'error');
+            }
+            instance.error = error instanceof Error ? error.message : String(error);
+            throw error;
+        }
+    }
+    async executeAgentWithRetry(assignment, phase, orchestration, maxRetries = 2) {
+        let lastError;
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            try {
+                return await this.executeAgent(assignment, phase, orchestration);
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error : new Error(String(error));
+                // Remove the failed instance from phase agents to prevent duplicates on retry
+                const failedIndex = phase.agents.findIndex(a => a.config.name === assignment.name && (a.status === 'error' || a.status === 'timeout'));
+                if (failedIndex >= 0)
+                    phase.agents.splice(failedIndex, 1);
+                if (attempt < maxRetries) {
+                    const delayMs = Math.min(1000 * Math.pow(2, attempt) + Math.random() * 1000, 30000);
+                    this.log.warn(`Agent failed, retrying in ${Math.round(delayMs / 1000)}s (attempt ${attempt + 1}/${maxRetries})`, {
+                        agent: assignment.name,
+                        error: lastError.message,
+                    });
+                    await new Promise(resolve => setTimeout(resolve, delayMs));
+                }
+            }
+        }
+        throw lastError;
+    }
+    // ─── Resume ────────────────────────────────────────────────────
+    /**
+     * Resume an orchestration from a checkpoint.
+     */
+    async resume(orchestrationId) {
+        const checkpoint = loadCheckpoint(orchestrationId);
+        if (!checkpoint) {
+            this.log.error(`No checkpoint found for: ${orchestrationId}`);
+            return null;
+        }
+        this.log.info(`Resuming orchestration: ${checkpoint.config.name} from phase ${checkpoint.currentPhase + 1}`);
+        // Reconstruct the orchestration, marking completed phases
+        const orchestration = this.createInstance(checkpoint.config);
+        orchestration.status = 'running';
+        orchestration.startedAt = new Date();
+        // Mark completed phases from checkpoint
+        for (let i = 0; i < checkpoint.phaseResults.length; i++) {
+            const saved = checkpoint.phaseResults[i];
+            if (saved && (saved.status === 'completed' || saved.status === 'failed')) {
+                orchestration.phases[i].status = saved.status;
+            }
+        }
+        this.orchestrations.set(checkpoint.config.id, orchestration);
+        this.bus.emit('orchestration:resumed', {
+            id: checkpoint.config.id,
+            name: checkpoint.config.name,
+            resumedFromPhase: checkpoint.currentPhase,
+        }, 'engine');
+        // Re-run execute — the DAG executor will skip completed phases
+        // because they're already marked and seeded into the completed set
+        return this.execute(checkpoint.config);
+    }
+    // ─── Approval ─────────────────────────────────────────────────
+    async requestApproval(phaseName, agents) {
+        const { createInterface } = await import('readline');
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
+        return new Promise((resolve) => {
+            const agentList = agents.map(a => `  ${a.name} (${a.type})`).join('\n');
+            rl.question(`\n⏸  Phase "${phaseName}" requires approval.\n` +
+                `   Agents:\n${agentList}\n` +
+                `   Proceed? [Y/n] `, (answer) => {
+                rl.close();
+                resolve(answer.toLowerCase() !== 'n');
+            });
+        });
+    }
+    // ─── Signal Handling ──────────────────────────────────────────
+    /**
+     * Register signal handlers for graceful shutdown.
+     */
+    setupSignalHandlers() {
+        // Remove any previously registered handlers to prevent accumulation
+        this.removeSignalHandlers();
+        const handler = async () => {
+            this.log.warn('Shutdown signal received — saving checkpoint and cleaning up');
+            this.abortController.abort();
+            // Save checkpoint for any running orchestration
+            for (const orchestration of this.getActiveOrchestrations()) {
+                try {
+                    const path = saveCheckpoint(orchestration);
+                    this.log.info(`Checkpoint saved: ${path}`);
+                }
+                catch {
+                    // Best effort
+                }
+                orchestration.status = 'cancelled';
+            }
+            // Transition running agents to error
+            for (const instance of this.registry.getActiveInstances()) {
+                try {
+                    this.registry.updateStatus(instance.id, 'error');
+                }
+                catch {
+                    // Best effort — lifecycle may not allow transition
+                }
+            }
+            try {
+                this.stats.close();
+            }
+            catch { /* best effort */ }
+            try {
+                this.traceStore?.close();
+            }
+            catch { /* best effort */ }
+            try {
+                this.heuristicStore?.close();
+            }
+            catch { /* best effort */ }
+            try {
+                this.modelRouter?.close();
+            }
+            catch { }
+            try {
+                this.autonomyTracker?.close();
+            }
+            catch { }
+            this.bus.emit('system:warning', { message: 'Graceful shutdown complete' }, 'engine');
+        };
+        process.on('SIGINT', handler);
+        process.on('SIGTERM', handler);
+        this.signalHandlers.push({ signal: 'SIGINT', handler: handler });
+        this.signalHandlers.push({ signal: 'SIGTERM', handler: handler });
+    }
+    removeSignalHandlers() {
+        for (const { signal, handler } of this.signalHandlers) {
+            process.removeListener(signal, handler);
+        }
+        this.signalHandlers = [];
+    }
+    /** Close all resources (stats, traces, heuristics, model router, autonomy tracker). */
+    close() {
+        try {
+            this.stats.close();
+        }
+        catch { }
+        try {
+            this.traceStore?.close();
+        }
+        catch { }
+        try {
+            this.heuristicStore?.close();
+        }
+        catch { }
+        try {
+            this.modelRouter?.close();
+        }
+        catch { }
+        try {
+            this.autonomyTracker?.close();
+        }
+        catch { }
+        this.removeSignalHandlers();
+    }
+    // ─── Queries ───────────────────────────────────────────────────
+    /**
+     * Get an orchestration by ID.
+     */
+    getOrchestration(id) {
+        return this.orchestrations.get(id);
+    }
+    /**
+     * Get all orchestrations.
+     */
+    getAllOrchestrations() {
+        return [...this.orchestrations.values()];
+    }
+    /**
+     * Get active orchestrations.
+     */
+    getActiveOrchestrations() {
+        return [...this.orchestrations.values()].filter(o => o.status === 'running' || o.status === 'paused');
+    }
+    get patternRegistry() {
+        return this.patterns;
+    }
+    // ─── Shared Context ────────────────────────────────────────────
+    /**
+     * Write shared context to a file for parallel agents to read,
+     * avoiding duplicating large context in each agent's prompt.
+     */
+    writeSharedContext(context) {
+        if (!context || context.length < 2000)
+            return null; // Not worth sharing for small contexts
+        const contextDir = join(this.options.cwd ?? process.cwd(), '.swarm');
+        if (!existsSync(contextDir))
+            mkdirSync(contextDir, { recursive: true });
+        const contextPath = join(contextDir, `shared-context-${randomUUID().slice(0, 8)}.md`);
+        writeFileSync(contextPath, redactSecrets(context), { mode: 0o600 });
+        this.sharedContextFiles.push(contextPath);
+        return contextPath;
+    }
+    // ─── Factory ───────────────────────────────────────────────────
+    createInstance(config) {
+        return {
+            config,
+            status: 'pending',
+            phases: config.phases.map(phaseConfig => ({
+                config: phaseConfig,
+                status: 'pending',
+                agents: [],
+                usage: emptyUsageStats(),
+            })),
+            currentPhase: 0,
+            usage: emptyUsageStats(),
+        };
+    }
+}
+//# sourceMappingURL=engine.js.map