@synergenius/flow-weaver-pack-weaver 0.9.59 → 0.9.77

package/src/bot/swarm-controller.ts

@@ -0,0 +1,780 @@
+/**
+ * SwarmController — multi-bot orchestrator for the Weaver Swarm.
+ *
+ * Uses a centralized orchestrator dispatch loop instead of per-bot pull loops.
+ * The Orchestrator routes pending tasks to the best available bot instance,
+ * the InstanceManager handles scaling, and the ProfileStore persists profiles.
+ *
+ * Singleton per workspace via `SwarmController.getInstance(projectDir)`.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { TaskStore } from './task-store.js';
+import { BotRegistry } from './bot-registry.js';
+import type { BotRegistration } from './bot-registry.js';
+import { SwarmEventLog } from './swarm-event-log.js';
+import { RunStore } from './run-store.js';
+import { EventLog } from './event-log.js';
+import { runRegistry } from './run-registry.js';
+import { runWorkflow } from './runner.js';
+import { buildTaskPrompt } from './task-prompt-builder.js';
+import { Orchestrator } from './orchestrator.js';
+import { AIRouterImpl } from './ai-router.js';
+import { InstanceManager } from './instance-manager.js';
+import { ProfileStore } from './profile-store.js';
+import type { BotProfile, BotInstance, OrchestratorInput, OrchestratorDecision } from './profile-types.js';
+import type { Task, RunSummary } from './task-types.js';
+import type { WorkflowResult } from './types.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface SwarmBudgets {
+  workspace: { limitTokens: number; usedTokens: number; limitCost: number; usedCost: number };
+  session: { limitTokens: number; usedTokens: number; limitCost: number; usedCost: number };
+}
+
+export interface SwarmState {
+  status: 'idle' | 'running' | 'paused' | 'stopping';
+  startedAt?: string;
+
+  /** Active bot instances managed by InstanceManager. */
+  instances: Record<string, BotInstance>;
+  maxConcurrent: number;
+
+  budgets: SwarmBudgets;
+
+  autoRetry: boolean;
+  maxAttemptsDefault: number;
+
+  // Stats
+  tasksCompleted: number;
+  tasksFailed: number;
+  totalTokensUsed: number;
+  totalCost: number;
+}
+
+export interface SwarmConfig {
+  maxConcurrent?: number;
+  sessionBudgetTokens?: number;
+  sessionBudgetCost?: number;
+  workspaceBudgetTokens?: number;
+  workspaceBudgetCost?: number;
+  autoRetry?: boolean;
+  maxAttemptsDefault?: number;
+}
+
+export interface SwarmStartConfig {
+  maxConcurrent?: number;
+  sessionBudgetTokens?: number;
+  sessionBudgetCost?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const DISPATCH_LOOP_SLEEP_MS = 2000;
+const SWARM_STATE_FILE = 'swarm.json';
+
+// ---------------------------------------------------------------------------
+// SwarmController
+// ---------------------------------------------------------------------------
+
+export class SwarmController {
+  private static instances = new Map<string, SwarmController>();
+
+  private readonly projectDir: string;
+  private readonly weaverDir: string;
+  private readonly statePath: string;
+  private readonly taskStore: TaskStore;
+  private readonly eventLog: SwarmEventLog;
+  private readonly orchestrator: Orchestrator;
+  private readonly instanceManager: InstanceManager;
+  private readonly profileStore: ProfileStore;
+
+  private state: SwarmState;
+
+  /** Abort controller for the single dispatch loop. */
+  private dispatchAbort: AbortController | null = null;
+  /** Promise for the dispatch loop (resolved when the loop exits). */
+  private dispatchLoopPromise: Promise<void> | null = null;
+  /** Promises for currently executing tasks (instanceId -> Promise). */
+  private executionPromises = new Map<string, Promise<void>>();
+
+  /** Map of profileId -> BotRegistration for workflow execution. */
+  private profileBotMap = new Map<string, BotRegistration>();
+
+  // -----------------------------------------------------------------------
+  // Singleton
+  // -----------------------------------------------------------------------
+
+  static getInstance(projectDir: string): SwarmController {
+    const key = path.resolve(projectDir);
+    let inst = SwarmController.instances.get(key);
+    if (!inst) {
+      inst = new SwarmController(key);
+      SwarmController.instances.set(key, inst);
+    }
+    return inst;
+  }
+
+  /** Clear all cached instances (used by tests). */
+  static clearInstances(): void {
+    SwarmController.instances.clear();
+  }
+
+  private constructor(projectDir: string) {
+    this.projectDir = projectDir;
+    this.weaverDir = path.join(projectDir, '.weaver');
+    if (!fs.existsSync(this.weaverDir)) fs.mkdirSync(this.weaverDir, { recursive: true });
+    this.statePath = path.join(this.weaverDir, SWARM_STATE_FILE);
+    this.taskStore = new TaskStore(projectDir);
+    this.eventLog = new SwarmEventLog(projectDir);
+    this.orchestrator = new Orchestrator({ aiRouter: new AIRouterImpl(projectDir) });
+    this.instanceManager = new InstanceManager();
+    this.profileStore = new ProfileStore(projectDir);
+
+    // Load persisted state or create default
+    this.state = this._loadState();
+
+    // Crash recovery: no dispatch loop survives a process restart, so reset
+    // any stale active status back to idle so start() is not short-circuited.
+    if (this.state.status === 'running' || this.state.status === 'paused' || this.state.status === 'stopping') {
+      this.state.status = 'idle';
+    }
+
+    this._persist();
+  }
+
+  // -----------------------------------------------------------------------
+  // Public API
+  // -----------------------------------------------------------------------
+
+  async start(config?: SwarmStartConfig): Promise<void> {
+    if (this.state.status === 'running') return;
+
+    // Apply start config
+    if (config?.maxConcurrent !== undefined) this.state.maxConcurrent = config.maxConcurrent;
+    if (config?.sessionBudgetTokens !== undefined) this.state.budgets.session.limitTokens = config.sessionBudgetTokens;
+    if (config?.sessionBudgetCost !== undefined) this.state.budgets.session.limitCost = config.sessionBudgetCost;
+
+    // Reset session budget counters on new start
+    this.state.budgets.session.usedTokens = 0;
+    this.state.budgets.session.usedCost = 0;
+
+    // Discover bots from registry
+    const registry = new BotRegistry(this.projectDir);
+    const bots = registry.list();
+
+    // Ensure default profiles exist for all registered bots
+    this.profileStore.ensureDefaultProfiles(
+      bots.map((b) => ({ id: b.id, name: b.name, icon: b.icon, color: b.color })),
+    );
+
+    // Load profiles and build profile-to-bot mapping
+    const profiles = this.profileStore.list();
+    this.profileBotMap.clear();
+    for (const profile of profiles) {
+      const bot = bots.find((b) => b.id === profile.botId);
+      if (bot) this.profileBotMap.set(profile.id, bot);
+    }
+
+    // Stop any existing instances
+    this.instanceManager.stopAll();
+
+    // Spawn initial instances per profile (up to maxConcurrent total)
+    let totalSpawned = 0;
+    for (const profile of profiles) {
+      if (totalSpawned >= this.state.maxConcurrent) break;
+
+      // Spawn at least minInstances, or 1 if minInstances is 0
+      const toSpawn = Math.max(profile.minInstances, 1);
+      const clamped = Math.min(toSpawn, this.state.maxConcurrent - totalSpawned);
+
+      for (let i = 0; i < clamped; i++) {
+        this.instanceManager.spawn(profile);
+        totalSpawned++;
+      }
+    }
+
+    // Populate state fields
+    this._syncInstancesState();
+
+    this.state.status = 'running';
+    this.state.startedAt = new Date().toISOString();
+    this._persist();
+
+    this.eventLog.emit({ type: 'swarm-started', timestamp: Date.now() });
+
+    // Start the centralized dispatch loop
+    this._startDispatchLoop();
+  }
+
+  async pause(): Promise<void> {
+    if (this.state.status !== 'running') return;
+
+    this.state.status = 'paused';
+    this._persist();
+
+    this.eventLog.emit({ type: 'swarm-paused', timestamp: Date.now() });
+
+    // The dispatch loop will check paused status and skip routing
+  }
+
+  async stop(): Promise<void> {
+    if (this.state.status === 'idle') return;
+
+    this.state.status = 'stopping';
+    this._persist();
+
+    // Signal the dispatch loop to stop
+    if (this.dispatchAbort) {
+      this.dispatchAbort.abort();
+    }
+
+    // Wait for the dispatch loop to finish
+    if (this.dispatchLoopPromise) {
+      await this.dispatchLoopPromise;
+    }
+
+    // Wait for all running executions to finish
+    const execPromises = Array.from(this.executionPromises.values());
+    await Promise.allSettled(execPromises);
+
+    // Stop all instances
+    this.instanceManager.stopAll();
+
+    // Update state
+    this._syncInstancesState();
+
+    this.state.status = 'idle';
+    this._persist();
+
+    this.dispatchAbort = null;
+    this.dispatchLoopPromise = null;
+    this.executionPromises.clear();
+
+    this.eventLog.emit({ type: 'swarm-stopped', timestamp: Date.now() });
+  }
+
+  getStatus(): SwarmState {
+    // Sync instances from InstanceManager before returning
+    this._syncInstancesState();
+    return { ...this.state, instances: { ...this.state.instances } };
+  }
+
+  configure(config: SwarmConfig): void {
+    if (config.maxConcurrent !== undefined) this.state.maxConcurrent = config.maxConcurrent;
+    if (config.sessionBudgetTokens !== undefined) this.state.budgets.session.limitTokens = config.sessionBudgetTokens;
+    if (config.sessionBudgetCost !== undefined) this.state.budgets.session.limitCost = config.sessionBudgetCost;
+    if (config.workspaceBudgetTokens !== undefined) this.state.budgets.workspace.limitTokens = config.workspaceBudgetTokens;
+    if (config.workspaceBudgetCost !== undefined) this.state.budgets.workspace.limitCost = config.workspaceBudgetCost;
+    if (config.autoRetry !== undefined) this.state.autoRetry = config.autoRetry;
+    if (config.maxAttemptsDefault !== undefined) this.state.maxAttemptsDefault = config.maxAttemptsDefault;
+    this._persist();
+  }
+
+  // -----------------------------------------------------------------------
+  // Crash recovery
+  // -----------------------------------------------------------------------
+
+  async recover(): Promise<void> {
+    // Reset all instances to idle
+    const allInstances = this.instanceManager.listAll();
+    for (const inst of allInstances) {
+      if (inst.status === 'executing') {
+        this.instanceManager.markIdle(inst.instanceId, false);
+      }
+    }
+
+    // Reset in-progress tasks
+    const tasks = await this.taskStore.list({ status: 'in-progress' });
+    for (const task of tasks) {
+      if (this.state.autoRetry && task.attempt < task.maxAttempts) {
+        await this.taskStore.update(task.id, {
+          status: 'pending',
+          currentBotId: undefined,
+        });
+      } else {
+        await this.taskStore.update(task.id, {
+          status: 'failed',
+          currentBotId: undefined,
+        });
+      }
+    }
+
+    // Reset swarm status to idle
+    this.state.status = 'idle';
+    this._syncInstancesState();
+    this._persist();
+  }
+
+  // -----------------------------------------------------------------------
+  // Token/cost recording
+  // -----------------------------------------------------------------------
+
+  recordTokenUsage(instanceId: string, _taskId: string, tokensUsed: number, cost: number): void {
+    // Update instance in InstanceManager
+    try {
+      this.instanceManager.recordUsage(instanceId, tokensUsed, cost);
+    } catch { /* instance may not exist if stopped */ }
+
+    // Update session budgets
+    this.state.budgets.session.usedTokens += tokensUsed;
+    this.state.budgets.session.usedCost += cost;
+
+    // Update workspace budgets
+    this.state.budgets.workspace.usedTokens += tokensUsed;
+    this.state.budgets.workspace.usedCost += cost;
+
+    // Update totals
+    this.state.totalTokensUsed += tokensUsed;
+    this.state.totalCost += cost;
+
+    this._persist();
+
+    this.eventLog.emit({
+      type: 'budget-updated',
+      timestamp: Date.now(),
+      data: { botId: instanceId, tokensUsed, cost },
+    });
+  }
+
+  // -----------------------------------------------------------------------
+  // Orchestrator accessors
+  // -----------------------------------------------------------------------
+
+  getProfileStore(): ProfileStore {
+    return this.profileStore;
+  }
+
+  getInstanceManager(): InstanceManager {
+    return this.instanceManager;
+  }
+
+  getOrchestrator(): Orchestrator {
+    return this.orchestrator;
+  }
+
+  getOrchestratorStatus(): { decisions: OrchestratorDecision[]; stats: { totalDecisions: number; assignmentsByMethod: Record<string, number> } } {
+    const decisions = this.orchestrator.getDecisionLog();
+    const stats = {
+      totalDecisions: decisions.length,
+      assignmentsByMethod: {} as Record<string, number>,
+    };
+    for (const d of decisions) {
+      stats.assignmentsByMethod[d.method] = (stats.assignmentsByMethod[d.method] ?? 0) + 1;
+    }
+    return { decisions, stats };
+  }
+
+  // -----------------------------------------------------------------------
+  // Dispatch loop
+  // -----------------------------------------------------------------------
+
+  private _startDispatchLoop(): void {
+    const abort = new AbortController();
+    this.dispatchAbort = abort;
+
+    this.dispatchLoopPromise = this._dispatchLoop(abort.signal).catch(() => {
+      // Swallow errors in dispatch loop — self-heals on next cycle
+    });
+  }
+
+  private async _dispatchLoop(signal: AbortSignal): Promise<void> {
+    while (!signal.aborted) {
+      // Check if swarm is still running
+      if (this.state.status === 'stopping' || this.state.status === 'idle') break;
+
+      // Check if paused — sleep and try again
+      if (this.state.status === 'paused') {
+        await this._sleep(DISPATCH_LOOP_SLEEP_MS, signal);
+        continue;
+      }
+
+      // Budget check before routing
+      if (this._isBudgetExceeded()) {
+        this.state.status = 'paused';
+        this._persist();
+        this.eventLog.emit({
+          type: 'swarm-paused',
+          timestamp: Date.now(),
+          data: { reason: 'budget-exceeded' },
+        });
+        break;
+      }
+
+      // Check instance-level steering
+      const allInstances = this.instanceManager.listAll();
+      for (const inst of allInstances) {
+        await this._checkSteering(inst.instanceId);
+      }
+
+      // Collect pending tasks (and all tasks for dependency checks)
+      const pendingTasks = await this.taskStore.list({ status: ['pending', 'failed'] });
+      const allTasks = await this.taskStore.list();
+      const routableTasks = pendingTasks.filter((t) => {
+        // Skip parent tasks
+        if (t.isParent) return false;
+        // Skip tasks that have exhausted retries
+        if (t.status === 'failed' && t.attempt >= t.maxAttempts) return false;
+        // Skip tasks over per-task budget
+        if (t.budgetTokens !== undefined && t.tokensUsed >= t.budgetTokens) return false;
+        if (t.budgetCost !== undefined && t.costUsed >= t.budgetCost) return false;
+        // Skip tasks whose dependencies are not all done
+        if (t.dependsOn && t.dependsOn.length > 0) {
+          const allDepsDone = t.dependsOn.every((depId) => {
+            const dep = allTasks.find((d) => d.id === depId);
+            return dep && dep.status === 'done';
+          });
+          if (!allDepsDone) return false;
+        }
+        return true;
+      });
+
+      if (routableTasks.length === 0) {
+        await this._sleep(DISPATCH_LOOP_SLEEP_MS, signal);
+        continue;
+      }
+
+      // Build orchestrator input
+      const profiles = this.profileStore.list();
+      const instances = this.instanceManager.listAll();
+      const { workspace, session } = this.state.budgets;
+
+      const budgetRemaining = {
+        tokens: this._remainingBudget(session.limitTokens, session.usedTokens, workspace.limitTokens, workspace.usedTokens),
+        cost: this._remainingBudget(session.limitCost, session.usedCost, workspace.limitCost, workspace.usedCost),
+      };
+
+      const input: OrchestratorInput = {
+        pendingTasks: routableTasks.map((t) => ({
+          id: t.id,
+          title: t.title,
+          description: t.description,
+          priority: t.priority,
+          complexity: t.complexity ?? 'moderate',
+          assignedProfile: t.assignedProfile,
+          context: {
+            runSummaries: t.context.runSummaries.map((rs) => ({
+              outcome: rs.outcome,
+              botId: rs.botId,
+            })),
+          },
+        })),
+        profiles,
+        instances,
+        budgetRemaining,
+      };
+
+      // Route
+      const output = await this.orchestrator.route(input);
+
+      // Apply scale actions
+      for (const sa of output.scaleActions) {
+        const profile = profiles.find((p) => p.id === sa.profileId);
+        if (profile) {
+          this.instanceManager.scaleTo(profile, sa.targetInstances);
+        }
+      }
+
+      // Apply assignments
+      for (const assignment of output.assignments) {
+        const profile = profiles.find((p) => p.id === assignment.profileId);
+        const bot = this.profileBotMap.get(assignment.profileId);
+        if (!profile || !bot) continue;
+
+        try {
+          // Assign task in TaskStore
+          await this.taskStore.assignToInstance(assignment.taskId, assignment.instanceId, assignment.profileId);
+
+          // Mark instance as executing and store runId on task for live streaming
+          const runId = RunStore.newId();
+          this.instanceManager.markExecuting(assignment.instanceId, assignment.taskId, runId);
+          await this.taskStore.update(assignment.taskId, { currentRunId: runId });
+
+          // Sync state for dashboard
+          this._syncInstancesState();
+          this._persist();
+
+          this.eventLog.emit({
+            type: 'task-claimed',
+            timestamp: Date.now(),
+            data: { botId: assignment.instanceId, taskId: assignment.taskId, profileId: assignment.profileId, method: assignment.method },
+          });
+
+          // Spawn execution (non-blocking)
+          const execPromise = this._executeTask(assignment.instanceId, assignment.taskId, runId, bot, profile).catch(() => {
+            // errors handled inside _executeTask
+          });
+          this.executionPromises.set(assignment.instanceId, execPromise);
+        } catch {
+          // Assignment failed (task may have been grabbed by another cycle) — skip
+        }
+      }
+
+      // Wait for completions via Promise.race with a sleep timeout
+      if (this.executionPromises.size > 0) {
+        const sleepPromise = this._sleep(DISPATCH_LOOP_SLEEP_MS, signal);
+        await Promise.race([
+          Promise.race(Array.from(this.executionPromises.values())),
+          sleepPromise,
+        ]);
+      } else {
+        await this._sleep(DISPATCH_LOOP_SLEEP_MS, signal);
+      }
+
+      // Clean up completed execution promises
+      for (const [instanceId, promise] of this.executionPromises) {
+        // Check if resolved by racing with an immediately resolved promise
+        const result = await Promise.race([
+          promise.then(() => 'done'),
+          Promise.resolve('pending'),
+        ]);
+        if (result === 'done') {
+          this.executionPromises.delete(instanceId);
+        }
+      }
+
+      // Post-cycle budget check
+      if (this._isBudgetExceeded()) {
+        this.state.status = 'paused';
+        this._persist();
+        this.eventLog.emit({
+          type: 'swarm-paused',
+          timestamp: Date.now(),
+          data: { reason: 'budget-exceeded' },
+        });
+        break;
+      }
+
+      this._syncInstancesState();
+      this._persist();
+    }
+  }
+
+  // -----------------------------------------------------------------------
+  // Task execution
+  // -----------------------------------------------------------------------
+
+  private async _executeTask(
+    instanceId: string,
+    taskId: string,
+    runId: string,
+    bot: BotRegistration,
+    profile: BotProfile,
+  ): Promise<void> {
+    const startTime = Date.now();
+    let result: WorkflowResult;
+
+    try {
+      const task = await this.taskStore.get(taskId);
+      if (!task) throw new Error(`Task not found: ${taskId}`);
+
+      // Build prompt from task context
+      const parentTask = task.parentId ? await this.taskStore.get(task.parentId) : null;
+      const siblingTasks = task.parentId ? await this.taskStore.getSubtasks(task.parentId) : [];
+      const prompt = buildTaskPrompt(task, parentTask, siblingTasks, profile.preferences);
+
+      // Create per-run event log
+      const runEventLog = new EventLog(runId);
+
+      // Execute workflow
+      result = await runWorkflow(bot.filePath, {
+        runId,
+        taskId,
+        botId: instanceId,
+        config: { provider: 'auto' },
+        params: { taskJson: prompt, projectDir: this.projectDir },
+        eventLog: runEventLog,
+      });
+
+      runEventLog.done();
+    } catch (err) {
+      result = {
+        success: false,
+        summary: (err instanceof Error ? err.message : String(err)),
+        outcome: 'error',
+      };
+    }
+
+    const durationMs = Date.now() - startTime;
+
+    // Extract run summary
+    const tokensUsed = Math.max(0, (result.cost?.totalInputTokens ?? 0) + (result.cost?.totalOutputTokens ?? 0));
+    const costUsed = Math.max(0, result.cost?.totalCost ?? 0);
+
+    const runSummary: RunSummary = {
+      runId,
+      botId: instanceId,
+      outcome: result.success ? 'success' : 'failed',
+      summary: result.summary || (result.success ? 'Completed' : 'Failed'),
+      filesModified: [],
+      error: result.success ? undefined : (result.summary || 'Unknown error'),
+      durationMs,
+      tokensUsed,
+      cost: costUsed,
+    };
+
+    // Release task
+    const releaseStatus = result.success ? 'done' : 'failed';
+    await this.taskStore.release(taskId, releaseStatus, runSummary);
+
+    // Record token usage
+    this.recordTokenUsage(instanceId, taskId, tokensUsed, costUsed);
+
+    // Update stats
+    if (result.success) {
+      this.state.tasksCompleted += 1;
+    } else {
+      this.state.tasksFailed += 1;
+    }
+
+    // Mark instance as idle
+    try {
+      this.instanceManager.markIdle(instanceId, result.success);
+    } catch { /* instance may have been stopped */ }
+
+    // Emit task event
+    this.eventLog.emit({
+      type: result.success ? 'task-done' : 'task-failed',
+      timestamp: Date.now(),
+      data: { botId: instanceId, taskId, outcome: runSummary.outcome },
+    });
+
+    this._syncInstancesState();
+    this._persist();
+  }
+
+  // -----------------------------------------------------------------------
+  // Budget checks
+  // -----------------------------------------------------------------------
+
+  private _isBudgetExceeded(): boolean {
+    const { workspace, session } = this.state.budgets;
+
+    // Check session budget
+    if (session.limitTokens > 0 && session.usedTokens >= session.limitTokens) return true;
+    if (session.limitCost > 0 && session.usedCost >= session.limitCost) return true;
+
+    // Check workspace budget
+    if (workspace.limitTokens > 0 && workspace.usedTokens >= workspace.limitTokens) return true;
+    if (workspace.limitCost > 0 && workspace.usedCost >= workspace.limitCost) return true;
+
+    return false;
+  }
+
+  /** Calculate remaining budget across session and workspace. */
+  private _remainingBudget(
+    sessionLimit: number,
+    sessionUsed: number,
+    workspaceLimit: number,
+    workspaceUsed: number,
+  ): number {
+    const remaining: number[] = [];
+    if (sessionLimit > 0) remaining.push(sessionLimit - sessionUsed);
+    if (workspaceLimit > 0) remaining.push(workspaceLimit - workspaceUsed);
+    if (remaining.length === 0) return Number.MAX_SAFE_INTEGER;
+    return Math.min(...remaining);
+  }
+
+  // -----------------------------------------------------------------------
+  // Steering
+  // -----------------------------------------------------------------------
+
+  private async _checkSteering(instanceId: string): Promise<void> {
+    const steerPath = path.join(this.weaverDir, `steer-${instanceId}.json`);
+    try {
+      if (!fs.existsSync(steerPath)) return;
+      const raw = fs.readFileSync(steerPath, 'utf-8');
+      fs.unlinkSync(steerPath); // consume the command
+      const command = JSON.parse(raw);
+
+      switch (command.command) {
+        case 'pause':
+          this.eventLog.emit({ type: 'bot-paused', timestamp: Date.now(), data: { botId: instanceId } });
+          break;
+        case 'resume':
+          break;
+        case 'cancel':
+          this.instanceManager.stop(instanceId);
+          break;
+      }
+    } catch { /* steer file read error — skip */ }
+  }
+
+  // -----------------------------------------------------------------------
+  // State sync — instances field
+  // -----------------------------------------------------------------------
+
+  private _syncInstancesState(): void {
+    const allInstances = this.instanceManager.listAll();
+
+    // Build instances record
+    this.state.instances = {};
+    for (const inst of allInstances) {
+      this.state.instances[inst.instanceId] = inst;
+    }
+  }
+
+  // -----------------------------------------------------------------------
+  // State persistence
+  // -----------------------------------------------------------------------
+
+  private _loadState(): SwarmState {
+    try {
+      if (fs.existsSync(this.statePath)) {
+        const raw = fs.readFileSync(this.statePath, 'utf-8');
+        const data = JSON.parse(raw) as SwarmState;
+        if (!data.instances) data.instances = {};
+        return data;
+      }
+    } catch { /* corrupt file — use defaults */ }
+    return this._defaultState();
+  }
+
+  private _defaultState(): SwarmState {
+    return {
+      status: 'idle',
+      instances: {},
+      maxConcurrent: 3,
+      budgets: {
+        workspace: { limitTokens: 0, usedTokens: 0, limitCost: 0, usedCost: 0 },
+        session: { limitTokens: 0, usedTokens: 0, limitCost: 0, usedCost: 0 },
+      },
+      autoRetry: true,
+      maxAttemptsDefault: 3,
+      tasksCompleted: 0,
+      tasksFailed: 0,
+      totalTokensUsed: 0,
+      totalCost: 0,
+    };
+  }
+
+  private _persist(): void {
+    try {
+      const tmpPath = this.statePath + '.tmp';
+      fs.writeFileSync(tmpPath, JSON.stringify(this.state, null, 2), 'utf-8');
+      fs.renameSync(tmpPath, this.statePath);
+    } catch (err) {
+      console.error('[swarm] Failed to persist state:', err instanceof Error ? err.message : err);
+    }
+  }
+
+  // -----------------------------------------------------------------------
+  // Utilities
+  // -----------------------------------------------------------------------
+
+  private _sleep(ms: number, signal?: AbortSignal): Promise<void> {
+    return new Promise((resolve) => {
+      const timer = setTimeout(resolve, ms);
+      signal?.addEventListener('abort', () => {
+        clearTimeout(timer);
+        resolve();
+      }, { once: true });
+    });
+  }
+}