minovative-mind-cli 1.5.0 → 2.0.0

package/dist/services/orchestration/messageBus.d.ts

@@ -0,0 +1,162 @@
+/**
+ * @fileoverview Two-Layer Message Bus for Sub-Agent Orchestration.
+ *
+ * Provides the core inter-agent communication primitive for the orchestration system.
+ * Two layers of communication:
+ *
+ * 1. **Automatic Activity Log** — Zero-cost tool call records captured by the orchestrator.
+ *    Every tool execution by any sub-agent is auto-logged without spending agent tokens.
+ *
+ * 2. **Agent-Posted Semantic Signals** — Typed coordination messages (discovery, warning,
+ *    request, completion) that agents manually post when they need to communicate intent
+ *    or changes that the activity log alone cannot capture.
+ *
+ * The bus is fully disk-backed via atomic writes to `.minovativemind/orchestration/` for
+ * crash recovery. If the CLI process dies mid-orchestration, the next invocation can
+ * restore the full bus state and resume.
+ */
+/**
+ * A single auto-captured tool execution record. Generated by the orchestrator's
+ * scoped tool wrapper — agents never spend tokens producing these.
+ */
+export interface ActivityEntry {
+    type: 'activity';
+    timestamp: number;
+    agentId: string;
+    /** The tool that was executed (e.g., 'write_file', 'modify_file', 'grep_search') */
+    tool: string;
+    /** What file/target was acted on (e.g., 'src/services/redis.ts', pattern string) */
+    target: string;
+    /** Short description of what happened (e.g., 'Created (52 lines)', 'Modified (added interface)') */
+    action: string;
+    /** Whether the tool call succeeded or errored */
+    status: 'success' | 'error';
+    /** Optional brief summary of the result */
+    resultSummary?: string;
+}
+/**
+ * Union type for all agent-posted semantic signals.
+ * These cost tokens (the agent decides to call the `post_message` tool)
+ * but carry semantic meaning the activity log can't express.
+ */
+export type BusSignal = DiscoverySignal | WarningSignal | RequestSignal | CompletionSignal;
+export interface DiscoverySignal {
+    type: 'discovery';
+    timestamp: number;
+    fromAgent: string;
+    content: string;
+    affectedFiles: string[];
+}
+export interface WarningSignal {
+    type: 'warning';
+    timestamp: number;
+    fromAgent: string;
+    content: string;
+    changedSignature?: string;
+}
+export interface RequestSignal {
+    type: 'request';
+    timestamp: number;
+    fromAgent: string;
+    toAgent: string;
+    content: string;
+}
+export interface CompletionSignal {
+    type: 'completion';
+    timestamp: number;
+    fromAgent: string;
+    summary: string;
+    exports: Record<string, string>;
+}
+/**
+ * Two-layer, disk-backed message bus for sub-agent coordination.
+ *
+ * - Layer 1 (Activity Log): Auto-captured tool executions. Zero agent cost.
+ * - Layer 2 (Semantic Signals): Agent-posted coordination messages. Capped at
+ *   `MAX_SIGNALS_PER_AGENT` per agent to prevent chatty flooding.
+ *
+ * All mutations are atomically persisted to disk so the orchestrator can survive
+ * a CLI crash and resume from the last known state.
+ */
+export declare class MessageBus {
+    private activityLog;
+    private signals;
+    private activityCursors;
+    private signalCursors;
+    private readonly persistPath;
+    private readonly workspaceRoot;
+    /** Maximum semantic signals any single agent can post */
+    static readonly MAX_SIGNALS_PER_AGENT = 20;
+    constructor(workspaceRoot: string, conversationId: string);
+    /**
+     * Records a tool execution into the activity log. Called by the scoped tool
+     * wrapper in `scopedTools.ts` — zero cost to the agent.
+     */
+    logActivity(entry: ActivityEntry): void;
+    /**
+     * Posts a semantic signal from an agent. These cost tokens (the agent calls
+     * `post_message`) but carry intent that raw tool logs cannot express.
+     *
+     * Enforces per-agent signal cap to prevent runaway agents from flooding the bus.
+     *
+     * @returns `true` if the signal was accepted, `false` if the agent hit the cap.
+     */
+    postSignal(signal: BusSignal): boolean;
+    /**
+     * Retrieves all unread activity entries and semantic signals for a specific agent.
+     * Advances the agent's cursors so subsequent calls return only new entries.
+     *
+     * Filters out the requesting agent's own entries (an agent doesn't need to
+     * re-read its own tool logs or signals).
+     */
+    getUnread(agentId: string): {
+        activities: ActivityEntry[];
+        signals: BusSignal[];
+    };
+    /**
+     * Returns the complete, unfiltered bus state for PM reconciliation.
+     * Used after all sub-agents complete to give the PM full visibility.
+     */
+    getFullLog(): {
+        activities: ActivityEntry[];
+        signals: BusSignal[];
+    };
+    /**
+     * Returns all activity entries for a specific agent (used for dead agent
+     * recovery — collecting partial progress before re-dispatch).
+     */
+    getAgentActivity(agentId: string): ActivityEntry[];
+    /**
+     * Returns the total number of activity entries and signals in the bus.
+     * Used for terminal display and diagnostics.
+     */
+    getStats(): {
+        activityCount: number;
+        signalCount: number;
+    };
+    /**
+     * Formats a batch of activity entries into a compact, human-readable string
+     * suitable for injection into an agent's context window.
+     */
+    static formatActivityEntries(entries: ActivityEntry[]): string;
+    /**
+     * Formats semantic signals into a readable string for agent context injection.
+     */
+    static formatSignals(signals: BusSignal[]): string;
+    /**
+     * Writes the full bus state to disk atomically. Called after every mutation
+     * to ensure crash resilience. Uses fire-and-forget to avoid blocking the
+     * hot path — write failures are logged but non-fatal.
+     */
+    private persistToDiskAsync;
+    /**
+     * Restores bus state from a previous disk snapshot. Called in the constructor.
+     * If the file doesn't exist or is corrupted, starts with a clean slate.
+     */
+    private restoreFromDisk;
+    /**
+     * Clears all bus state and removes the persistence file.
+     * Called when orchestration completes successfully (no crash recovery needed).
+     */
+    cleanup(): Promise<void>;
+}

package/dist/services/orchestration/messageBus.js

@@ -0,0 +1,225 @@
+/**
+ * @fileoverview Two-Layer Message Bus for Sub-Agent Orchestration.
+ *
+ * Provides the core inter-agent communication primitive for the orchestration system.
+ * Two layers of communication:
+ *
+ * 1. **Automatic Activity Log** — Zero-cost tool call records captured by the orchestrator.
+ *    Every tool execution by any sub-agent is auto-logged without spending agent tokens.
+ *
+ * 2. **Agent-Posted Semantic Signals** — Typed coordination messages (discovery, warning,
+ *    request, completion) that agents manually post when they need to communicate intent
+ *    or changes that the activity log alone cannot capture.
+ *
+ * The bus is fully disk-backed via atomic writes to `.minovativemind/orchestration/` for
+ * crash recovery. If the CLI process dies mid-orchestration, the next invocation can
+ * restore the full bus state and resume.
+ */
+import { promises as fs, readFileSync, existsSync, mkdirSync } from 'node:fs';
+import path from 'node:path';
+import { atomicWriteFile } from '../../utils/atomicWrite.js';
+import { debugLog } from '../../utils/logger.js';
+// ─── Message Bus Implementation ──────────────────────────────────────
+/**
+ * Two-layer, disk-backed message bus for sub-agent coordination.
+ *
+ * - Layer 1 (Activity Log): Auto-captured tool executions. Zero agent cost.
+ * - Layer 2 (Semantic Signals): Agent-posted coordination messages. Capped at
+ *   `MAX_SIGNALS_PER_AGENT` per agent to prevent chatty flooding.
+ *
+ * All mutations are atomically persisted to disk so the orchestrator can survive
+ * a CLI crash and resume from the last known state.
+ */
+export class MessageBus {
+    activityLog = [];
+    signals = [];
+    activityCursors = new Map();
+    signalCursors = new Map();
+    persistPath;
+    workspaceRoot;
+    /** Maximum semantic signals any single agent can post */
+    static MAX_SIGNALS_PER_AGENT = 20;
+    constructor(workspaceRoot, conversationId) {
+        this.workspaceRoot = workspaceRoot;
+        const orchestrationDir = path.join(workspaceRoot, '.minovativemind', 'orchestration');
+        this.persistPath = path.join(orchestrationDir, `${conversationId}-bus.json`);
+        this.restoreFromDisk();
+    }
+    // ─── Layer 1: Automatic Activity Log ─────────────────────────────
+    /**
+     * Records a tool execution into the activity log. Called by the scoped tool
+     * wrapper in `scopedTools.ts` — zero cost to the agent.
+     */
+    logActivity(entry) {
+        this.activityLog.push(entry);
+        this.persistToDiskAsync();
+    }
+    // ─── Layer 2: Semantic Signals ───────────────────────────────────
+    /**
+     * Posts a semantic signal from an agent. These cost tokens (the agent calls
+     * `post_message`) but carry intent that raw tool logs cannot express.
+     *
+     * Enforces per-agent signal cap to prevent runaway agents from flooding the bus.
+     *
+     * @returns `true` if the signal was accepted, `false` if the agent hit the cap.
+     */
+    postSignal(signal) {
+        const agentSignalCount = this.signals.filter(s => s.fromAgent === signal.fromAgent).length;
+        if (agentSignalCount >= MessageBus.MAX_SIGNALS_PER_AGENT) {
+            debugLog(`MessageBus: Agent ${signal.fromAgent} hit signal cap (${MessageBus.MAX_SIGNALS_PER_AGENT}). ` +
+                `Dropping signal of type "${signal.type}".`);
+            return false;
+        }
+        this.signals.push(signal);
+        this.persistToDiskAsync();
+        return true;
+    }
+    // ─── Reading ─────────────────────────────────────────────────────
+    /**
+     * Retrieves all unread activity entries and semantic signals for a specific agent.
+     * Advances the agent's cursors so subsequent calls return only new entries.
+     *
+     * Filters out the requesting agent's own entries (an agent doesn't need to
+     * re-read its own tool logs or signals).
+     */
+    getUnread(agentId) {
+        const actCursor = this.activityCursors.get(agentId) ?? 0;
+        const sigCursor = this.signalCursors.get(agentId) ?? 0;
+        const activities = this.activityLog
+            .slice(actCursor)
+            .filter(e => e.agentId !== agentId);
+        const signals = this.signals
+            .slice(sigCursor)
+            .filter(s => s.fromAgent !== agentId);
+        // Advance cursors to current end
+        this.activityCursors.set(agentId, this.activityLog.length);
+        this.signalCursors.set(agentId, this.signals.length);
+        return { activities, signals };
+    }
+    /**
+     * Returns the complete, unfiltered bus state for PM reconciliation.
+     * Used after all sub-agents complete to give the PM full visibility.
+     */
+    getFullLog() {
+        return {
+            activities: [...this.activityLog],
+            signals: [...this.signals],
+        };
+    }
+    /**
+     * Returns all activity entries for a specific agent (used for dead agent
+     * recovery — collecting partial progress before re-dispatch).
+     */
+    getAgentActivity(agentId) {
+        return this.activityLog.filter(e => e.agentId === agentId);
+    }
+    /**
+     * Returns the total number of activity entries and signals in the bus.
+     * Used for terminal display and diagnostics.
+     */
+    getStats() {
+        return {
+            activityCount: this.activityLog.length,
+            signalCount: this.signals.length,
+        };
+    }
+    // ─── Formatting Helpers ──────────────────────────────────────────
+    /**
+     * Formats a batch of activity entries into a compact, human-readable string
+     * suitable for injection into an agent's context window.
+     */
+    static formatActivityEntries(entries) {
+        if (entries.length === 0)
+            return '';
+        return entries.map(e => {
+            const statusIcon = e.status === 'success' ? '✓' : '✗';
+            const summary = e.resultSummary ? ` | ${e.resultSummary}` : '';
+            return `  ${e.agentId} | ${e.tool.padEnd(14)} → ${e.target.padEnd(40)} | ${statusIcon} ${e.action}${summary}`;
+        }).join('\n');
+    }
+    /**
+     * Formats semantic signals into a readable string for agent context injection.
+     */
+    static formatSignals(signals) {
+        if (signals.length === 0)
+            return '';
+        return signals.map(s => {
+            const tag = s.type.toUpperCase();
+            switch (s.type) {
+                case 'discovery':
+                    return `  [${tag} from ${s.fromAgent}]: "${s.content}" (affects: ${s.affectedFiles.join(', ')})`;
+                case 'warning':
+                    return `  [${tag} from ${s.fromAgent}]: "${s.content}"${s.changedSignature ? ` (signature: ${s.changedSignature})` : ''}`;
+                case 'request':
+                    return `  [${tag} from ${s.fromAgent} → ${s.toAgent}]: "${s.content}"`;
+                case 'completion':
+                    return `  [${tag} from ${s.fromAgent}]: "${s.summary}"`;
+                default:
+                    return `  [SIGNAL from ${s.fromAgent}]: ${JSON.stringify(s)}`;
+            }
+        }).join('\n');
+    }
+    // ─── Persistence ─────────────────────────────────────────────────
+    /**
+     * Writes the full bus state to disk atomically. Called after every mutation
+     * to ensure crash resilience. Uses fire-and-forget to avoid blocking the
+     * hot path — write failures are logged but non-fatal.
+     */
+    persistToDiskAsync() {
+        const snapshot = {
+            activityLog: this.activityLog,
+            signals: this.signals,
+            activityCursors: Object.fromEntries(this.activityCursors),
+            signalCursors: Object.fromEntries(this.signalCursors),
+        };
+        // Fire-and-forget — don't block the calling agent's tool loop
+        atomicWriteFile(this.persistPath, JSON.stringify(snapshot)).catch(err => {
+            debugLog(`MessageBus: Failed to persist to disk: ${err}`);
+        });
+    }
+    /**
+     * Restores bus state from a previous disk snapshot. Called in the constructor.
+     * If the file doesn't exist or is corrupted, starts with a clean slate.
+     */
+    restoreFromDisk() {
+        try {
+            // Sync FS functions imported at top of file
+            const dir = path.dirname(this.persistPath);
+            if (!existsSync(dir)) {
+                mkdirSync(dir, { recursive: true });
+            }
+            if (!existsSync(this.persistPath))
+                return;
+            const raw = readFileSync(this.persistPath, 'utf-8');
+            const snapshot = JSON.parse(raw);
+            this.activityLog = snapshot.activityLog ?? [];
+            this.signals = snapshot.signals ?? [];
+            this.activityCursors = new Map(Object.entries(snapshot.activityCursors ?? {}));
+            this.signalCursors = new Map(Object.entries(snapshot.signalCursors ?? {}));
+            debugLog(`MessageBus: Restored ${this.activityLog.length} activity entries and ${this.signals.length} signals from disk.`);
+        }
+        catch (err) {
+            debugLog(`MessageBus: Could not restore from disk (starting clean): ${err}`);
+            this.activityLog = [];
+            this.signals = [];
+            this.activityCursors = new Map();
+            this.signalCursors = new Map();
+        }
+    }
+    /**
+     * Clears all bus state and removes the persistence file.
+     * Called when orchestration completes successfully (no crash recovery needed).
+     */
+    async cleanup() {
+        this.activityLog = [];
+        this.signals = [];
+        this.activityCursors = new Map();
+        this.signalCursors = new Map();
+        try {
+            await fs.unlink(this.persistPath);
+        }
+        catch {
+            // File may not exist — non-fatal
+        }
+    }
+}

package/dist/services/orchestration/orchestrator.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @fileoverview Main Orchestrator for Sub-Agent Dispatch and Coordination.
+ *
+ * The orchestrator acts as the "PM Kernel", responsible for:
+ * 1. Task Decomposition (using gemini-3.5-flash)
+ * 2. Graph Validation (Cycle detection via Kahn's algorithm)
+ * 3. Lock Ordering (Conflict resolution across parallel waves)
+ * 4. Parallel Dispatch (Executing waves sequentially, agents in parallel)
+ * 5. Error Routing and Cross-Agent Integration Reconciliation
+ */
+import { AsyncInputHandler } from '../agent/inputHandler.js';
+export declare class Orchestrator {
+    private readonly workspaceRoot;
+    private readonly conversationId;
+    private readonly inputHandler;
+    private bus;
+    private locks;
+    private pmChat;
+    private agentResults;
+    constructor(workspaceRoot: string, conversationId: string, inputHandler: AsyncInputHandler);
+    /**
+     * Main entry point for orchestration. Decomposes the task, validates the graph,
+     * schedules waves, and dispatches sub-agents.
+     *
+     * @returns true if orchestration completed successfully, false if the task
+     *          was too simple and should be handled by the main agent loop.
+     */
+    runOrchestration(objective: string, contextInjection: string, signal: AbortSignal): Promise<boolean | string>;
+    /**
+     * Calls the PM Agent to decompose the task into a TaskGraph.
+     */
+    private decomposeTask;
+    /**
+     * Computes execution waves and resolves file lock conflicts via pre-allocation.
+     */
+    private scheduleWaves;
+    /**
+     * Dispatches a single sub-agent and records its result.
+     */
+    private dispatchAgent;
+    /**
+     * Final reconciliation phase after all waves complete.
+     */
+    private reconcile;
+}

package/dist/services/orchestration/orchestrator.js

@@ -0,0 +1,214 @@
+/**
+ * @fileoverview Main Orchestrator for Sub-Agent Dispatch and Coordination.
+ *
+ * The orchestrator acts as the "PM Kernel", responsible for:
+ * 1. Task Decomposition (using gemini-3.5-flash)
+ * 2. Graph Validation (Cycle detection via Kahn's algorithm)
+ * 3. Lock Ordering (Conflict resolution across parallel waves)
+ * 4. Parallel Dispatch (Executing waves sequentially, agents in parallel)
+ * 5. Error Routing and Cross-Agent Integration Reconciliation
+ */
+import * as p from '@clack/prompts';
+import pc from 'picocolors';
+import { ProxyChatSession } from '../ai.js';
+import { GEMINI_MODELS, MAX_OUTPUT_TOKENS } from '../../utils/config.js';
+import { debugLog } from '../../utils/logger.js';
+import { MessageBus } from './messageBus.js';
+import { FileLockRegistry } from './fileLockRegistry.js';
+import { SubAgentRunner } from './subAgent.js';
+import { validateTaskGraph, computeExecutionWaves, detectFileConflicts, resolveFileConflicts, buildCycleCorrectionPrompt, CyclicDependencyError, } from './taskGraph.js';
+// ─── Constants ───────────────────────────────────────────────────────
+const PM_SYSTEM_INSTRUCTION = `You are the PM Agent (Project Manager).
+Your job is to decompose the user's objective into a parallelizable Task Graph for sub-agents.
+You must output ONLY raw JSON representing the TaskGraph object. Do not wrap in markdown code blocks.
+
+Requirements:
+- Break the work down logically based on file isolation and dependency chains.
+- Tasks that don't depend on each other will run in parallel.
+- If a task depends on another, it must list its ID in "dependsOn".
+- Do NOT create cyclic dependencies (A -> B -> A).
+- If the entire objective is very simple and only requires modifying 1-2 files sequentially, output a graph with exactly 1 task.
+- Ensure 'targetFiles' lists all files the task will modify.
+
+JSON Schema:
+{
+  "objective": "string",
+  "tasks": [
+    {
+      "id": "string (unique)",
+      "intent": "string (what to do)",
+      "targetFiles": ["string"],
+      "readOnlyFiles": ["string"],
+      "dependsOn": ["string (IDs)"],
+      "exports": ["string (what this provides)"]
+    }
+  ],
+  "constraints": ["string"]
+}
+`;
+// ─── Orchestrator Implementation ─────────────────────────────────────
+export class Orchestrator {
+    workspaceRoot;
+    conversationId;
+    inputHandler;
+    bus;
+    locks;
+    pmChat;
+    agentResults = new Map();
+    constructor(workspaceRoot, conversationId, inputHandler) {
+        this.workspaceRoot = workspaceRoot;
+        this.conversationId = conversationId;
+        this.inputHandler = inputHandler;
+        this.bus = new MessageBus(workspaceRoot, conversationId);
+        this.locks = new FileLockRegistry();
+        this.pmChat = new ProxyChatSession(GEMINI_MODELS.FLASH_3_5, PM_SYSTEM_INSTRUCTION, [], {
+            maxOutputTokens: MAX_OUTPUT_TOKENS,
+            temperature: 0.1,
+            responseMimeType: 'application/json',
+        });
+    }
+    /**
+     * Main entry point for orchestration. Decomposes the task, validates the graph,
+     * schedules waves, and dispatches sub-agents.
+     *
+     * @returns true if orchestration completed successfully, false if the task
+     *          was too simple and should be handled by the main agent loop.
+     */
+    async runOrchestration(objective, contextInjection, signal) {
+        p.log.step(pc.cyan('Orchestrator: Planning task execution...'));
+        // 1. Task Decomposition
+        const graph = await this.decomposeTask(objective, contextInjection, signal);
+        if (!graph)
+            return false; // Aborted
+        if (graph.tasks.length <= 1) {
+            debugLog('Orchestrator: Only 1 task generated. Bypassing orchestration overhead.');
+            return false;
+        }
+        // 2. Validation & Scheduling
+        const waves = this.scheduleWaves(graph);
+        if (!waves || waves.length === 0)
+            return false; // Aborted or failed cycle detection
+        p.log.info(pc.blue(`Orchestrator: Generated ${waves.length} execution wave(s) with ${graph.tasks.length} total tasks.`));
+        // 3. Dispatch Waves
+        for (const wave of waves) {
+            if (signal.aborted)
+                break;
+            p.log.step(pc.magenta(`Starting Wave ${wave.depth + 1}...`));
+            const wavePromises = wave.taskIds.map(taskId => {
+                const taskDef = graph.tasks.find(t => t.id === taskId);
+                const globalContext = `Objective:\n${objective}\n\nContext:\n${contextInjection}`;
+                return this.dispatchAgent(taskDef, globalContext, signal);
+            });
+            // Run all agents in this wave concurrently
+            const results = await Promise.all(wavePromises);
+            // Post-wave evaluation
+            const failedCount = results.filter(r => !r.success).length;
+            if (failedCount > 0) {
+                p.log.warn(pc.yellow(`Wave ${wave.depth + 1} finished with ${failedCount} failure(s).`));
+                // Phase 3 implementation note: Right now, we continue and let downstream
+                // agents attempt to run, but in the future we will implement PM-driven
+                // downstream re-validation and dynamic graph patching here.
+            }
+            else {
+                p.log.success(pc.green(`Wave ${wave.depth + 1} completed successfully.`));
+            }
+        }
+        // 4. Reconciliation
+        const finalSummary = await this.reconcile(graph);
+        return finalSummary;
+    }
+    /**
+     * Calls the PM Agent to decompose the task into a TaskGraph.
+     */
+    async decomposeTask(objective, contextInjection, signal) {
+        const prompt = `Objective:\n${objective}\n\nContext:\n${contextInjection}`;
+        let result = await this.pmChat.sendMessage(prompt, undefined, signal);
+        if (signal.aborted)
+            return null;
+        let rawJson = result.response.text();
+        // Cycle Self-Correction Loop (Up to 3 attempts)
+        let attempts = 0;
+        while (attempts < 3) {
+            try {
+                const graph = JSON.parse(rawJson);
+                // Run Kahn's algorithm
+                validateTaskGraph(graph);
+                return graph; // Validation passed!
+            }
+            catch (err) {
+                if (err instanceof CyclicDependencyError) {
+                    debugLog(`PM Agent generated a cyclic graph. Attempt ${attempts + 1}/3 to self-correct.`);
+                    const correctionPrompt = buildCycleCorrectionPrompt(err.cycleNodes);
+                    result = await this.pmChat.sendMessage(correctionPrompt, undefined, signal);
+                    if (signal.aborted)
+                        return null;
+                    rawJson = result.response.text();
+                    attempts++;
+                }
+                else {
+                    // JSON parsing error or InvalidDependencyError
+                    debugLog(`PM Agent generated invalid graph: ${err.message}. Retrying...`);
+                    result = await this.pmChat.sendMessage(`Invalid JSON or missing dependency ID: ${err.message}. Please fix.`, undefined, signal);
+                    if (signal.aborted)
+                        return null;
+                    rawJson = result.response.text();
+                    attempts++;
+                }
+            }
+        }
+        p.log.error('Orchestrator: PM Agent failed to generate a valid, acyclic task graph after 3 attempts.');
+        return null;
+    }
+    /**
+     * Computes execution waves and resolves file lock conflicts via pre-allocation.
+     */
+    scheduleWaves(graph) {
+        try {
+            const rawWaves = computeExecutionWaves(graph);
+            const conflicts = detectFileConflicts(graph, rawWaves);
+            return resolveFileConflicts(rawWaves, conflicts);
+        }
+        catch (err) {
+            debugLog(`Orchestrator: Failed to schedule waves: ${err.message}`);
+            return null;
+        }
+    }
+    /**
+     * Dispatches a single sub-agent and records its result.
+     */
+    async dispatchAgent(taskDef, globalContext, signal) {
+        const runner = new SubAgentRunner(taskDef.id, taskDef.intent, this.workspaceRoot, this.bus, this.locks, globalContext);
+        const result = await runner.execute(signal);
+        // Clean up any stray locks if the agent crashed or stalled
+        if (result.crashed) {
+            this.locks.forceReleaseAll(taskDef.id);
+        }
+        this.agentResults.set(taskDef.id, result);
+        return result;
+    }
+    /**
+     * Final reconciliation phase after all waves complete.
+     */
+    async reconcile(graph) {
+        p.log.step(pc.cyan('Orchestrator: Reconciling results...'));
+        const stats = this.bus.getStats();
+        let totalTokens = 0;
+        let failedTasks = 0;
+        let finalSummary = '[Sub-Agent Orchestration Completed]\\n\\n';
+        for (const [taskId, res] of this.agentResults.entries()) {
+            totalTokens += res.creditsUsed;
+            if (!res.success)
+                failedTasks++;
+            debugLog(`Task ${taskId} summary: ${res.summary.substring(0, 100)}...`);
+            finalSummary += `**Task: ${taskId}**\\nStatus: ${res.success ? 'Success' : 'Failed'}\\n${res.summary}\\n\\n`;
+        }
+        p.log.info(`${pc.green('✓')} Sub-agent execution complete.\n` +
+            `  Total tasks: ${graph.tasks.length} (${failedTasks} failed)\n` +
+            `  Bus Activity: ${stats.activityCount} actions, ${stats.signalCount} signals\n` +
+            `  Total Tokens: ${totalTokens.toLocaleString()}`);
+        // Clear the bus persistence now that orchestration is done
+        await this.bus.cleanup();
+        this.locks.shutdown();
+        return finalSummary.trim();
+    }
+}