specdacular 0.10.1 → 0.11.1

package/runner/main/agent/runner.js

@@ -0,0 +1,137 @@
+import { spawn } from 'child_process';
+import { EventEmitter } from 'events';
+import { createWriteStream } from 'fs';
+import { StreamParser } from './parser.js';
+
+export class AgentRunner extends EventEmitter {
+  constructor({ cmd, input_mode, output_format, system_prompt, timeout, stuck_timeout }) {
+    super();
+    this.cmd = cmd;
+    this.inputMode = input_mode || 'stdin';
+    this.outputFormat = output_format || 'stream_json';
+    this.systemPrompt = system_prompt || '';
+    this.timeout = (timeout || 3600) * 1000;
+    this.stuckTimeout = (stuck_timeout || 1800) * 1000;
+  }
+
+  async run(prompt, { cwd, logPath } = {}) {
+    return new Promise((resolve, reject) => {
+      const fullPrompt = this.systemPrompt ? `${this.systemPrompt}\n\n${prompt}` : prompt;
+      const args = this.cmd.split(' ').slice(1);
+      const bin = this.cmd.split(' ')[0];
+
+      const proc = spawn(bin, args, {
+        cwd,
+        shell: true,
+        stdio: ['pipe', 'pipe', 'pipe'],
+        env: { ...process.env },
+      });
+
+      const logStream = logPath ? createWriteStream(logPath, { flags: 'a' }) : null;
+      let lastOutputAt = Date.now();
+      let result = null;
+
+      const parser = new StreamParser();
+      parser.on('status', (s) => {
+        lastOutputAt = Date.now();
+        this.emit('status', s);
+      });
+      parser.on('result', (r) => {
+        lastOutputAt = Date.now();
+        result = r;
+        this.emit('result', r);
+      });
+      parser.on('output', (line) => {
+        lastOutputAt = Date.now();
+        this.emit('output', line);
+      });
+
+      const handleLine = (line) => {
+        if (logStream) logStream.write(line + '\n');
+
+        if (this.outputFormat === 'stream_json') {
+          try {
+            const event = JSON.parse(line);
+            if (event.type === 'assistant' && event.message?.content) {
+              for (const block of event.message.content) {
+                if (block.type === 'text') {
+                  for (const textLine of block.text.split('\n')) {
+                    parser.feed(textLine);
+                  }
+                }
+              }
+            } else if (event.type === 'result' && event.result) {
+              for (const block of event.result) {
+                if (block.type === 'text') {
+                  for (const textLine of block.text.split('\n')) {
+                    parser.feed(textLine);
+                  }
+                }
+              }
+            }
+          } catch {
+            parser.feed(line);
+          }
+        } else {
+          parser.feed(line);
+        }
+      };
+
+      let stdout = '';
+      proc.stdout.on('data', (chunk) => {
+        stdout += chunk.toString();
+        const lines = stdout.split('\n');
+        stdout = lines.pop();
+        for (const line of lines) {
+          if (line.trim()) handleLine(line.trim());
+        }
+      });
+
+      proc.stderr.on('data', (chunk) => {
+        if (logStream) logStream.write(`[stderr] ${chunk}`);
+      });
+
+      if (this.inputMode === 'stdin') {
+        proc.stdin.write(fullPrompt);
+        proc.stdin.end();
+      }
+
+      // Global timeout
+      const globalTimer = setTimeout(() => {
+        proc.kill('SIGTERM');
+        setTimeout(() => proc.kill('SIGKILL'), 5000);
+      }, this.timeout);
+
+      // Stuck detection
+      const stuckCheck = setInterval(() => {
+        if (Date.now() - lastOutputAt > this.stuckTimeout) {
+          this.emit('error', new Error('Agent stuck — no output'));
+          proc.kill('SIGTERM');
+          setTimeout(() => proc.kill('SIGKILL'), 5000);
+        }
+      }, 30000);
+
+      proc.on('close', (code) => {
+        clearTimeout(globalTimer);
+        clearInterval(stuckCheck);
+        if (logStream) logStream.end();
+        if (stdout.trim()) handleLine(stdout.trim());
+
+        if (result) {
+          resolve(result);
+        } else if (code === 0) {
+          resolve({ status: 'success', summary: 'Agent completed without explicit result' });
+        } else {
+          resolve({ status: 'failure', summary: `Agent exited with code ${code}` });
+        }
+      });
+
+      proc.on('error', (err) => {
+        clearTimeout(globalTimer);
+        clearInterval(stuckCheck);
+        if (logStream) logStream.end();
+        reject(err);
+      });
+    });
+  }
+}

package/runner/main/agent/template.js

@@ -0,0 +1,16 @@
+export function resolveTemplate(template, variables) {
+  return template.replace(/\{\{([^}]+)\}\}/g, (match, path) => {
+    const value = path.trim().split('.').reduce((obj, key) => obj?.[key], variables);
+    return value !== undefined ? String(value) : match;
+  });
+}
+
+export function buildTemplateContext(task, stage, pipeline, paths) {
+  return {
+    task: { id: task.id, name: task.name, spec: task.spec || '' },
+    stage: { name: stage.stage, index: stage.index, total: stage.total },
+    pipeline: { name: pipeline.name },
+    status_file: paths?.statusJson || '',
+    log_dir: paths?.logsDir || '',
+  };
+}

package/runner/main/bootstrap.js

@@ -0,0 +1,69 @@
+import { mkdirSync, writeFileSync, existsSync } from 'fs';
+import { join } from 'path';
+
+const DEFAULT_CONFIG = {
+  server: { port: 3700 },
+  notifications: { telegram: { enabled: false } },
+  defaults: {
+    pipeline: 'default',
+    failure_policy: 'skip',
+    timeout: 3600,
+    stuck_timeout: 1800,
+    max_parallel: 1,
+  },
+};
+
+const DEFAULT_AGENTS = {
+  'claude-planner': {
+    cmd: 'claude -p --dangerously-skip-permissions',
+    input_mode: 'stdin',
+    output_format: 'stream_json',
+    system_prompt: 'You are a feature planner working on: {{task.name}} ({{task.id}})\nPipeline: {{pipeline.name}} | Stage: {{stage.name}} ({{stage.index}}/{{stage.total}})\n\nResearch the codebase thoroughly, then create a detailed implementation plan.\n\nEmit progress:\n```specd-status\n{"task_id":"{{task.id}}","stage":"{{stage.name}}","progress":"...","percent":0}\n```\n\nWhen done:\n```specd-result\n{"status":"success","summary":"...","files_changed":[],"issues":[]}\n```',
+  },
+  'claude-implementer': {
+    cmd: 'claude -p --dangerously-skip-permissions',
+    input_mode: 'stdin',
+    output_format: 'stream_json',
+    system_prompt: 'You are an implementer working on: {{task.name}} ({{task.id}})\nPipeline: {{pipeline.name}} | Stage: {{stage.name}} ({{stage.index}}/{{stage.total}})\n\nImplement the plan from the previous stage. Write clean, tested code.\n\nEmit progress:\n```specd-status\n{"task_id":"{{task.id}}","stage":"{{stage.name}}","progress":"...","percent":0}\n```\n\nWhen done:\n```specd-result\n{"status":"success","summary":"...","files_changed":[],"issues":[]}\n```',
+  },
+  'claude-reviewer': {
+    cmd: 'claude -p --dangerously-skip-permissions',
+    input_mode: 'stdin',
+    output_format: 'stream_json',
+    system_prompt: 'You are a code reviewer for: {{task.name}} ({{task.id}})\nPipeline: {{pipeline.name}} | Stage: {{stage.name}} ({{stage.index}}/{{stage.total}})\n\nReview the implementation from the previous stage. Check for bugs, style, tests.\n\nEmit progress:\n```specd-status\n{"task_id":"{{task.id}}","stage":"{{stage.name}}","progress":"...","percent":0}\n```\n\nWhen done:\n```specd-result\n{"status":"success","summary":"...","files_changed":[],"issues":[]}\n```',
+  },
+};
+
+const DEFAULT_PIPELINE = {
+  name: 'default',
+  stages: [
+    { stage: 'plan', agent: 'claude-planner', critical: true },
+    { stage: 'implement', agent: 'claude-implementer', critical: true },
+    { stage: 'review', agent: 'claude-reviewer', on_fail: 'retry', max_retries: 2 },
+  ],
+};
+
+function writeIfMissing(filePath, data) {
+  if (!existsSync(filePath)) {
+    writeFileSync(filePath, JSON.stringify(data, null, 2));
+  }
+}
+
+export async function bootstrap(paths) {
+  // Create directories
+  mkdirSync(paths.agentTemplatesDir, { recursive: true });
+  mkdirSync(paths.pipelineTemplatesDir, { recursive: true });
+  mkdirSync(paths.projectsDir, { recursive: true });
+
+  // Write default files
+  writeIfMissing(paths.db, { projects: [] });
+  writeIfMissing(paths.config, DEFAULT_CONFIG);
+
+  // Write default agent templates
+  for (const [name, agent] of Object.entries(DEFAULT_AGENTS)) {
+    writeIfMissing(join(paths.agentTemplatesDir, `${name}.json`), agent);
+  }
+
+  // Write default pipeline template
+  writeIfMissing(join(paths.pipelineTemplatesDir, 'default.json'), DEFAULT_PIPELINE);
+}

package/runner/main/db.js

@@ -0,0 +1,45 @@
+import { readFileSync, writeFileSync } from 'fs';
+import { randomUUID } from 'crypto';
+
+export class ProjectDB {
+  constructor(dbPath) {
+    this.dbPath = dbPath;
+    this.data = JSON.parse(readFileSync(dbPath, 'utf-8'));
+  }
+
+  register(name, folderPath) {
+    const project = {
+      id: randomUUID().slice(0, 8),
+      name,
+      path: folderPath,
+      active: true,
+      registeredAt: new Date().toISOString(),
+    };
+    this.data.projects.push(project);
+    this._save();
+    return project;
+  }
+
+  unregister(id) {
+    this.data.projects = this.data.projects.filter(p => p.id !== id);
+    this._save();
+  }
+
+  get(id) {
+    return this.data.projects.find(p => p.id === id) || null;
+  }
+
+  findByPath(folderPath) {
+    return this.data.projects.find(p =>
+      folderPath === p.path || folderPath.startsWith(p.path + '/')
+    ) || null;
+  }
+
+  list() {
+    return this.data.projects;
+  }
+
+  _save() {
+    writeFileSync(this.dbPath, JSON.stringify(this.data, null, 2));
+  }
+}

package/runner/main/index.js

@@ -0,0 +1,103 @@
+// runner/main/index.js
+import { app, BrowserWindow } from 'electron';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+import { readFileSync, existsSync, writeFileSync, mkdirSync } from 'fs';
+import { Paths } from './paths.js';
+import { bootstrap } from './bootstrap.js';
+import { ProjectDB } from './db.js';
+import { Orchestrator } from './orchestrator.js';
+import { createServer } from './server/index.js';
+import { setupIpc } from './ipc.js';
+
+let mainWindow;
+const paths = new Paths();
+const orchestrators = new Map();
+let db;
+let config;
+let server;
+
+function getContext() {
+  return { db, config, paths, orchestrators };
+}
+
+async function initBackend() {
+  await bootstrap(paths);
+
+  db = new ProjectDB(paths.db);
+  config = JSON.parse(readFileSync(paths.config, 'utf-8'));
+
+  // Initialize orchestrators for active projects
+  for (const project of db.list().filter(p => p.active)) {
+    // Ensure project.json exists (may not if registered via CLI only)
+    const projectPaths = paths.forProject(project.id);
+    mkdirSync(projectPaths.dir, { recursive: true });
+    if (!existsSync(projectPaths.projectJson)) {
+      writeFileSync(projectPaths.projectJson, JSON.stringify({
+        name: project.name,
+        path: project.path,
+        registeredAt: project.registeredAt,
+      }, null, 2));
+    }
+
+    const orch = new Orchestrator({ projectId: project.id, paths, config });
+    orch.init();
+    orchestrators.set(project.id, orch);
+  }
+
+  // Start API server
+  server = createServer(getContext);
+  const port = config.server?.port || 3700;
+  await server.start(port);
+
+  // Wire orchestrators to WebSocket
+  for (const orch of orchestrators.values()) {
+    server.wireOrchestrator(orch);
+  }
+
+  // Start orchestrator loops
+  for (const orch of orchestrators.values()) {
+    orch.startLoop().catch(err => console.error('Loop error:', err));
+  }
+}
+
+function createWindow() {
+  mainWindow = new BrowserWindow({
+    width: 1200,
+    height: 800,
+    webPreferences: {
+      preload: join(__dirname, '..', 'preload.js'),
+      contextIsolation: true,
+      nodeIntegration: false,
+    },
+  });
+
+  if (process.env.NODE_ENV === 'development') {
+    mainWindow.loadURL('http://localhost:5173');
+  } else {
+    mainWindow.loadFile(join(__dirname, '..', 'renderer', 'dist', 'index.html'));
+  }
+}
+
+app.whenReady().then(async () => {
+  setupIpc(getContext);
+  await initBackend();
+  createWindow();
+});
+
+app.on('window-all-closed', () => {
+  if (process.platform !== 'darwin') app.quit();
+});
+
+app.on('activate', () => {
+  if (BrowserWindow.getAllWindows().length === 0) createWindow();
+});
+
+app.on('before-quit', () => {
+  for (const orch of orchestrators.values()) {
+    orch.stop();
+  }
+  if (server) server.stop();
+});

package/runner/main/ipc.js

@@ -0,0 +1,72 @@
+// runner/main/ipc.js
+import { ipcMain } from 'electron';
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+
+export function setupIpc(getContext) {
+  ipcMain.handle('get-projects', () => {
+    const { db, orchestrators } = getContext();
+    return db.list().map(p => {
+      const orch = orchestrators.get(p.id);
+      const tasks = orch ? orch.getTasks() : [];
+      return {
+        ...p,
+        taskCounts: {
+          total: tasks.length,
+          ready: tasks.filter(t => t.status === 'ready').length,
+          running: tasks.filter(t => t.status === 'in_progress').length,
+          done: tasks.filter(t => t.status === 'done').length,
+          failed: tasks.filter(t => t.status === 'failed').length,
+        },
+      };
+    });
+  });
+
+  ipcMain.handle('get-project-status', (event, projectId) => {
+    const { orchestrators } = getContext();
+    const orch = orchestrators.get(projectId);
+    if (!orch) return null;
+    return orch.stateManager.getState();
+  });
+
+  ipcMain.handle('get-tasks', (event, projectId) => {
+    const { orchestrators } = getContext();
+    const orch = orchestrators.get(projectId);
+    if (!orch) return [];
+    return orch.getTasks();
+  });
+
+  ipcMain.handle('get-task', (event, projectId, taskId) => {
+    const { orchestrators } = getContext();
+    const orch = orchestrators.get(projectId);
+    if (!orch) return null;
+    return orch.getTask(taskId);
+  });
+
+  ipcMain.handle('create-task', (event, projectId, taskData) => {
+    const { orchestrators } = getContext();
+    const orch = orchestrators.get(projectId);
+    if (!orch) return null;
+    return orch.createTask(taskData);
+  });
+
+  ipcMain.handle('retry-task', (event, projectId, taskId) => {
+    const { orchestrators } = getContext();
+    const orch = orchestrators.get(projectId);
+    if (!orch) return null;
+    return orch.updateTask(taskId, { status: 'ready' });
+  });
+
+  ipcMain.handle('get-task-logs', (event, projectId, taskId) => {
+    const { paths } = getContext();
+    const logPath = join(paths.forProject(projectId).logsDir, `${taskId}.log`);
+    if (!existsSync(logPath)) return { lines: [] };
+    const content = readFileSync(logPath, 'utf-8');
+    return { lines: content.split('\n').slice(-200) };
+  });
+
+  ipcMain.handle('get-config', () => {
+    const { config } = getContext();
+    return config;
+  });
+}

package/runner/main/notifications/telegram.js

@@ -0,0 +1,45 @@
+// runner/main/notifications/telegram.js
+import { request } from 'https';
+
+export class TelegramNotifier {
+  constructor({ bot_token, chat_id, notify_on }) {
+    this.botToken = bot_token;
+    this.chatId = chat_id;
+    this.notifyOn = new Set(notify_on || ['task_complete', 'task_failed']);
+  }
+
+  async onTaskComplete(taskId, taskName, summary) {
+    if (!this.notifyOn.has('task_complete')) return;
+    await this._send(`✅ *Task Complete*\n*${taskName}* (${taskId})\n${summary}`);
+  }
+
+  async onTaskFailed(taskId, taskName, stage, error) {
+    if (!this.notifyOn.has('task_failed')) return;
+    await this._send(`❌ *Task Failed*\n*${taskName}* (${taskId})\nStage: ${stage}\nError: ${error}`);
+  }
+
+  async onStuck(taskId, taskName, stage) {
+    if (!this.notifyOn.has('task_stuck')) return;
+    await this._send(`⚠️ *Agent Stuck*\n*${taskName}* (${taskId})\nStage: ${stage}`);
+  }
+
+  async onNeedsInput(taskId, taskName, stage, question) {
+    if (!this.notifyOn.has('needs_input')) return;
+    await this._send(`❓ *Input Needed*\n*${taskName}* (${taskId})\nStage: ${stage}\n${question}`);
+  }
+
+  _send(text) {
+    return new Promise((resolve) => {
+      const data = JSON.stringify({ chat_id: this.chatId, text, parse_mode: 'Markdown' });
+      const req = request({
+        hostname: 'api.telegram.org',
+        path: `/bot${this.botToken}/sendMessage`,
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(data) },
+      }, resolve);
+      req.on('error', (err) => { console.error('Telegram error:', err.message); resolve(); });
+      req.write(data);
+      req.end();
+    });
+  }
+}

package/runner/main/orchestrator.js

@@ -0,0 +1,193 @@
+// runner/main/orchestrator.js
+import { readFileSync, readdirSync, writeFileSync, existsSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { EventEmitter } from 'events';
+import { StateManager } from './state/manager.js';
+import { TemplateManager } from './template-manager.js';
+import { AgentRunner } from './agent/runner.js';
+import { StageSequencer } from './pipeline/sequencer.js';
+import { resolvePipeline } from './pipeline/resolver.js';
+import { resolveTemplate, buildTemplateContext } from './agent/template.js';
+import { WorktreeManager } from './worktree/manager.js';
+
+export class Orchestrator extends EventEmitter {
+  constructor({ projectId, paths, config }) {
+    super();
+    this.projectId = projectId;
+    this.paths = paths;
+    this.config = config;
+    this.projectPaths = paths.forProject(projectId);
+    this.stateManager = new StateManager(this.projectPaths.statusJson);
+    this.templateManager = new TemplateManager(paths);
+    this.running = false;
+    this.runningTasks = new Set();
+    this.worktreeManager = null;
+  }
+
+  init() {
+    // Ensure project dirs exist
+    mkdirSync(this.projectPaths.tasksDir, { recursive: true });
+    mkdirSync(this.projectPaths.logsDir, { recursive: true });
+
+    // Load project config
+    const projectJson = JSON.parse(readFileSync(this.projectPaths.projectJson, 'utf-8'));
+    this.projectPath = projectJson.path;
+
+    // Init worktree manager if parallel
+    const maxParallel = this.config.defaults?.max_parallel || 1;
+    if (maxParallel > 1 && existsSync(join(this.projectPath, '.git'))) {
+      this.worktreeManager = new WorktreeManager(this.projectPath);
+    }
+
+    // Forward state events
+    this.stateManager.on('change', (event) => {
+      this.emit('change', { ...event, project: this.projectId });
+    });
+  }
+
+  getTasks() {
+    const tasksDir = this.projectPaths.tasksDir;
+    if (!existsSync(tasksDir)) return [];
+    return readdirSync(tasksDir)
+      .filter(f => f.endsWith('.json'))
+      .map(f => JSON.parse(readFileSync(join(tasksDir, f), 'utf-8')));
+  }
+
+  getTask(taskId) {
+    const taskPath = join(this.projectPaths.tasksDir, `${taskId}.json`);
+    if (!existsSync(taskPath)) return null;
+    return JSON.parse(readFileSync(taskPath, 'utf-8'));
+  }
+
+  createTask(task) {
+    mkdirSync(this.projectPaths.tasksDir, { recursive: true });
+    const taskPath = join(this.projectPaths.tasksDir, `${task.id}.json`);
+    writeFileSync(taskPath, JSON.stringify(task, null, 2));
+    return task;
+  }
+
+  updateTask(taskId, updates) {
+    const task = this.getTask(taskId);
+    if (!task) return null;
+    const updated = { ...task, ...updates };
+    const taskPath = join(this.projectPaths.tasksDir, `${taskId}.json`);
+    writeFileSync(taskPath, JSON.stringify(updated, null, 2));
+    return updated;
+  }
+
+  pickNextTask() {
+    const tasks = this.getTasks();
+    const completedIds = new Set(
+      Object.entries(this.stateManager.getState().tasks)
+        .filter(([, t]) => t.status === 'done')
+        .map(([id]) => id)
+    );
+
+    return tasks
+      .filter(t => t.status === 'ready' && !this.runningTasks.has(t.id))
+      .filter(t => (t.depends_on || []).every(dep => completedIds.has(dep)))
+      .sort((a, b) => (a.priority || 99) - (b.priority || 99))[0] || null;
+  }
+
+  async runTask(task) {
+    const agents = this.templateManager.getAgents(this.projectId);
+    const pipelines = this.templateManager.getPipelines(this.projectId);
+    const pipelineName = task.pipeline || this.config.defaults?.pipeline || 'default';
+    const pipeline = resolvePipeline(pipelineName, pipelines, task.stage_overrides, this.config.defaults);
+
+    this.runningTasks.add(task.id);
+    this.stateManager.registerTask(task.id, { name: task.name, pipeline: pipelineName });
+    this.stateManager.updateTaskStatus(task.id, 'in_progress');
+    this.updateTask(task.id, { status: 'in_progress' });
+
+    // Determine working directory
+    const workingDir = task.working_dir || '.';
+    let cwd = join(this.projectPath, workingDir);
+    let worktreePath = null;
+
+    if (this.worktreeManager && existsSync(join(cwd, '.git'))) {
+      worktreePath = this.worktreeManager.create(task.id);
+      cwd = worktreePath;
+    }
+
+    const logPath = join(this.projectPaths.logsDir, `${task.id}.log`);
+
+    const sequencer = new StageSequencer({
+      stages: pipeline.stages,
+      createRunner: (stage) => {
+        const agentDef = agents[stage.agent];
+        if (!agentDef) throw new Error(`Agent not found: ${stage.agent}`);
+
+        const context = buildTemplateContext(task, stage, pipeline, this.projectPaths);
+        const resolvedPrompt = resolveTemplate(agentDef.system_prompt || '', context);
+
+        const runner = new AgentRunner({
+          ...agentDef,
+          system_prompt: resolvedPrompt,
+          timeout: stage.timeout,
+          stuck_timeout: this.config.defaults?.stuck_timeout,
+        });
+
+        runner.on('status', (s) => this.stateManager.updateLiveProgress(task.id, s));
+        runner.on('output', () => this.stateManager.persist());
+
+        return { run: () => runner.run(task.spec || task.description || task.name, { cwd, logPath }) };
+      },
+      onStageStart: async (stage, attempt) => {
+        this.stateManager.startStage(task.id, { stage: stage.stage, agent: stage.agent });
+        this.stateManager.persist();
+      },
+      onStageComplete: async (stage, result, attempt) => {
+        this.stateManager.completeStage(task.id, result.status, result.summary);
+        this.stateManager.persist();
+      },
+    });
+
+    const result = await sequencer.run();
+
+    const finalStatus = result.status === 'success' ? 'done' : 'failed';
+    this.stateManager.updateTaskStatus(task.id, finalStatus);
+    this.stateManager.persist();
+    this.updateTask(task.id, { status: finalStatus });
+
+    // Create PR if worktree has changes
+    if (worktreePath && this.worktreeManager.hasChanges(task.id)) {
+      const summary = result.results.map(r => `- ${r.stage}: ${r.summary}`).join('\n');
+      const prUrl = this.worktreeManager.createPR(task.id, task.name, summary);
+      if (prUrl) this.stateManager.setPrUrl(task.id, prUrl);
+      this.stateManager.persist();
+    }
+
+    // Cleanup worktree
+    if (worktreePath) {
+      this.worktreeManager.remove(task.id);
+    }
+
+    this.runningTasks.delete(task.id);
+    return result;
+  }
+
+  async startLoop(interval = 5000) {
+    this.running = true;
+
+    while (this.running) {
+      const maxParallel = this.config.defaults?.max_parallel || 1;
+      const available = maxParallel - this.runningTasks.size;
+
+      for (let i = 0; i < available; i++) {
+        const task = this.pickNextTask();
+        if (!task) break;
+        // Fire and forget — runs in parallel
+        this.runTask(task).catch(err => {
+          console.error(`Task ${task.id} failed:`, err);
+        });
+      }
+
+      await new Promise(r => setTimeout(r, interval));
+    }
+  }
+
+  stop() {
+    this.running = false;
+  }
+}