claudeboard 2.16.0 → 3.1.0

package/src/orchestrator.js

@@ -0,0 +1,800 @@
+// src/orchestrator.js
+const { spawn } = require('child_process');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { createTask, updateTask, getTask, getTasks, savePRD, getPRD, getProjectPath, appendChatHistory, saveChatImage, writeHandoff, readHandoffs } = require('./store');
+const { runVerifier } = require('./verifier');
+const { notify } = require('./notifier');
+const { scanProject } = require('./scanner');
+
+// spawnClaude: writes prompt to temp file and pipes via PowerShell (Win) or sh (Mac/Linux)
+// This is the only reliable cross-platform way to pass long prompts to `claude --print`
+function spawnClaude(prompt, cwd) {
+  const tmpFile = path.join(os.tmpdir(), `cb-${Date.now()}-${Math.random().toString(36).slice(2)}.txt`);
+  fs.writeFileSync(tmpFile, prompt, { encoding: 'utf8' });
+
+  let child;
+  if (process.platform === 'win32') {
+    // PowerShell pipes file content reliably on Windows (no cmd line length limit, no char escaping issues)
+    const psCmd = `Get-Content -Raw -Encoding UTF8 '${tmpFile}' | claude --permission-mode bypassPermissions --print`;
+    child = spawn('powershell', ['-NoProfile', '-NonInteractive', '-Command', psCmd], {
+      cwd,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      shell: false,
+    });
+  } else {
+    child = spawn('sh', ['-c', `claude --permission-mode bypassPermissions --print < '${tmpFile}'`], {
+      cwd,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      shell: false,
+    });
+  }
+
+  child.on('close', () => { try { fs.unlinkSync(tmpFile); } catch (_) {} });
+  return child;
+}
+const MAX_INPUT_LEN = 10000;   // max user input chars
+const AGENT_TIMEOUT_MS = 10 * 60 * 1000; // 10 minutes
+
+// Assign the most qualified role based on task content
+function assignAgentRole(task) {
+  const text = `${task.title} ${task.description}`.toLowerCase();
+
+  if (/hero|css|design|visual|ui|ux|layout|style|color|font|frontend|html|landing|responsive|animation|gradient|button|card|navbar|section|spacing|padding|margin|typograph|flex|grid|tailwind|sass|scss/.test(text))
+    return 'Frontend Dev';
+  if (/icon|logo|illustration|figma|branding|brand|mockup|asset|image|svg|banner/.test(text))
+    return 'UI/UX Dev';
+  if (/api|server|database|db|endpoint|route|auth|login|session|token|middleware|express|node|backend|prisma|sql|mongo|redis|cache/.test(text))
+    return 'Backend Dev';
+  if (/deploy|ci\/cd|docker|nginx|infrastructure|pipeline|env|devops|vercel|netlify|hosting/.test(text))
+    return 'DevOps';
+  if (/test|qa|quality|verify|coverage|spec|unit|e2e|cypress|jest|vitest/.test(text))
+    return 'QA Engineer';
+  if (/security|permission|xss|injection|csrf|vulnerab|sanitiz|encrypt/.test(text))
+    return 'Security Dev';
+  if (/data|analytic|migration|schema|model|orm|import|export|csv|etl/.test(text))
+    return 'Data Engineer';
+
+  return 'Lead Developer';
+}
+
+let activeAgents = new Map(); // taskId -> { proc, timer }
+let broadcast = null;
+let maxAgents = 3;
+let agentSlot = 0;
+let qaAgentRan = false;
+let qaBuffer = '';
+let serverPort = 3000;
+let awaitingSupabaseCreds = false; // pauses queue until user provides Supabase credentials
+
+function setBroadcast(fn) { broadcast = fn; }
+function setMaxAgents(n) { maxAgents = n; }
+function setServerPort(p) { serverPort = p; }
+
+// Detect if a task involves Supabase operations
+function isSupabaseTask(task) {
+  const text = `${task.title} ${task.description}`.toLowerCase();
+  return /supabase/.test(text);
+}
+
+// Strip null bytes and enforce length limit before any input reaches the CLI
+function sanitizeInput(str) {
+  if (typeof str !== 'string') return '';
+  return str.replace(/\0/g, '').slice(0, MAX_INPUT_LEN);
+}
+
+// In-memory conversation state (not persisted to disk)
+let conversationHistory = [];
+let orchBuffer = '';
+let projectContext = null;
+
+function buildGreeting(ctx) {
+  if (ctx.isNewProject) {
+    return `¡Hola! Soy tu Orquestador. Contame qué querés construir y coordino tu equipo de agentes IA.`;
+  }
+
+  // Existing project
+  return `¡Bienvenido de vuelta! Ya tenés un PRD guardado. ¿Querés continuar, agregar tareas o empezar de nuevo?`;
+}
+
+function startOrchestrator() {
+  conversationHistory = [];
+  orchBuffer = '';
+
+  try {
+    projectContext = scanProject(getProjectPath());
+  } catch (err) {
+    console.warn('[orchestrator] scanner error:', err.message);
+    projectContext = null;
+  }
+
+  const greeting = projectContext
+    ? buildGreeting(projectContext)
+    : "¡Hola! Soy tu Orquestador. Contame qué querés construir y coordino tu equipo de agentes IA.";
+
+  if (broadcast) broadcast({ type: 'orchestrator:chunk', chunk: greeting });
+}
+
+function handleOrchOutput(text) {
+  orchBuffer += text;
+
+  const prdMatch = orchBuffer.match(/<PRD>([\s\S]*?)<\/PRD>/);
+  if (prdMatch) {
+    savePRD(prdMatch[1].trim());
+    notify('prd:generated', { taskTitle: null, status: 'generated' });
+  }
+
+  // Parse tasks when </TASKS> closes the block
+  if (orchBuffer.includes('</TASKS>')) {
+    let taskDefs = [];
+
+    // Primary: <TASK> key:value blocks
+    const taskBlocks = [...orchBuffer.matchAll(/<TASK>([\s\S]*?)<\/TASK>/g)];
+    if (taskBlocks.length > 0) {
+      taskDefs = taskBlocks.map(m => {
+        const block = m[1];
+        const get = (key) => {
+          const match = block.match(new RegExp(`^${key}:\\s*(.+)$`, 'mi'));
+          return match ? match[1].trim() : '';
+        };
+        return { title: get('title'), description: get('description'), successCriteria: get('successCriteria'), priority: get('priority') || 'medium' };
+      }).filter(t => t.title);
+    }
+
+    // Fallback: JSON array inside <TASKS>...</TASKS>
+    if (taskDefs.length === 0) {
+      try {
+        const jsonMatch = orchBuffer.match(/<TASKS>\s*(\[[\s\S]*?\])\s*<\/TASKS>/);
+        if (jsonMatch) {
+          const parsed = JSON.parse(jsonMatch[1]);
+          if (Array.isArray(parsed)) {
+            taskDefs = parsed.filter(t => t && t.title).map(t => ({
+              title: String(t.title || '').slice(0, 200),
+              description: String(t.description || '').slice(0, 2000),
+              successCriteria: String(t.successCriteria || '').slice(0, 1000),
+              priority: t.priority || 'medium',
+            }));
+          }
+        }
+      } catch { /* malformed JSON — skip */ }
+    }
+
+    if (taskDefs.length > 0) {
+      const created = taskDefs.map(t => createTask(t));
+      if (broadcast) broadcast({ type: 'tasks:created', tasks: created });
+      notify('tasks:created', { taskTitle: null, status: 'created' });
+      qaAgentRan = false;
+      orchBuffer = '';
+      // If any task requires Supabase, pause queue and ask user for credentials
+      const needsSupabase = taskDefs.some(isSupabaseTask);
+      if (needsSupabase && !awaitingSupabaseCreds) {
+        awaitingSupabaseCreds = true;
+        if (broadcast) broadcast({
+          type: 'supabase:preflight',
+          taskTitles: created.map(t => t.title),
+        });
+      } else {
+        processQueue();
+      }
+    }
+  }
+}
+
+function sendMessage(rawMessage, imageData = null) {
+  const message = sanitizeInput(rawMessage);
+  if (!message) return;
+
+  orchBuffer = ''; // reset buffer for each new message exchange
+  conversationHistory.push({ role: 'user', content: message });
+  appendChatHistory({ role: 'user', content: message });
+  if (broadcast) broadcast({ type: 'orchestrator:thinking' });
+
+  // Save attached image to disk so Claude can read it
+  let imagePath = null;
+  if (imageData) {
+    try { imagePath = saveChatImage(imageData); } catch (err) {
+      console.warn('[orchestrator] failed to save chat image:', err.message);
+    }
+  }
+
+  // Build project context section for the system prompt
+  let projectSection = '';
+  if (projectContext) {
+    const lines = [];
+    lines.push(`## Project Context`);
+    lines.push(`- **Name**: ${projectContext.projectName}`);
+    if (projectContext.techStack.length > 0) {
+      lines.push(`- **Tech stack**: ${projectContext.techStack.join(', ')}`);
+    }
+    if (projectContext.pkgDescription) {
+      lines.push(`- **Description**: ${projectContext.pkgDescription}`);
+    }
+    if (projectContext.readme) {
+      lines.push(`\n### README (excerpt)\n${projectContext.readme.slice(0, 1000)}`);
+    }
+    if (projectContext.existingPrd) {
+      lines.push(`\n### Existing PRD\n${projectContext.existingPrd.slice(0, 2000)}`);
+    }
+    if (projectContext.contextMd) {
+      lines.push(`\n### Brand guidelines / context.md\n${projectContext.contextMd.slice(0, 2000)}`);
+    }
+    lines.push(`\n### File tree\n\`\`\`\n${projectContext.fileTree.slice(0, 2000)}\n\`\`\``);
+    projectSection = '\n\n' + lines.join('\n');
+  }
+
+  const systemPrompt = `Sos el orquestador de ClaudeBoard. Español argentino, muy directo.${projectSection}
+
+Tu trabajo: traducir el pedido del usuario en tareas para agentes especialistas (Frontend Dev, Backend Dev, UI/UX Dev, etc.).
+
+CUÁNTAS TAREAS CREAR:
+- Si el usuario pide UN cambio o mejora puntual → 1 tarea.
+- Solo dividir en múltiples tareas si los cambios son en partes del proyecto claramente independientes (ej: frontend + backend por separado).
+- Nunca dividir algo que un solo agente puede resolver en una sola pasada.
+
+CÓMO ESCRIBIR LA DESCRIPCIÓN:
+- Reproducir el pedido del usuario casi literalmente, con contexto del proyecto si aplica.
+- Sin inventar implementación. Sin decirle AL AGENTE cómo hacerlo (eso lo decide él).
+- El agente va a leer el proyecto, entender el código y resolver por su cuenta.
+
+FORMATO EXACTO (no agregar nada más):
+
+Listo, [N] tarea(s) en el board.
+
+<PRD>
+Una oración con el objetivo.
+</PRD>
+<TASKS>
+<TASK>
+title: Qué hay que lograr
+description: El pedido del usuario en sus propias palabras + contexto relevante del proyecto. Sin instrucciones técnicas de implementación.
+successCriteria: Cómo se ve el resultado correcto para el usuario final
+priority: high|medium|low
+</TASK>
+</TASKS>`;
+
+  const historyText = conversationHistory
+    .map(m => `${m.role === 'user' ? 'Usuario' : 'Orquestador'}: ${m.content}`)
+    .join('\n\n');
+
+  const imageSection = imagePath
+    ? `\n\nEl usuario adjuntó una imagen del estado actual del proyecto en: ${imagePath}\nPodés leerla para ver cómo se ve visualmente y tenerlo en cuenta al crear las tareas.`
+    : '';
+
+  const fullPrompt = `${systemPrompt}\n\n--- CONVERSACIÓN ACTUAL ---\n${historyText}${imageSection}\n\nOrquestador:`;
+
+  const proc = spawnClaude(fullPrompt, process.cwd());
+
+  let response = '';
+
+  proc.stdout.on('data', (data) => {
+    const chunk = data.toString('utf-8');
+    response += chunk;
+    if (broadcast) broadcast({ type: 'orchestrator:chunk', chunk });
+    handleOrchOutput(chunk);
+  });
+
+  proc.stderr.on('data', () => {
+    // Swallow — don't expose internal details or system paths to the client
+  });
+
+  proc.on('close', () => {
+    if (response) {
+      const assistantContent = response.slice(0, MAX_INPUT_LEN);
+      conversationHistory.push({ role: 'assistant', content: assistantContent });
+      appendChatHistory({ role: 'assistant', content: assistantContent });
+    }
+  });
+
+  proc.on('error', (err) => {
+    console.error('[orchestrator] spawn error:', err.message);
+    if (broadcast) broadcast({ type: 'orchestrator:error', message: 'Orchestrator failed to start. Is the claude CLI installed and logged in?' });
+  });
+}
+
+function spawnTaskAgent(task) {
+  if (activeAgents.has(task.id)) return;
+
+  // Assign the most qualified role based on task content
+  const agentLabel = assignAgentRole(task);
+
+  const projectPath = getProjectPath();
+
+  // Read .claudeboard/context.md if present
+  let contextMdContent = '';
+  try {
+    const contextMdPath = path.join(projectPath, '.claudeboard', 'context.md');
+    if (fs.existsSync(contextMdPath)) {
+      contextMdContent = fs.readFileSync(contextMdPath, 'utf-8').slice(0, 8000);
+    }
+  } catch { /* ignore */ }
+
+  // Detect file path mentioned in task description
+  let fileContent = '';
+  const filePathMatch = task.description && task.description.match(/[\w/\\.\-]+\.(html|css|js|ts|jsx|tsx|json|md)/i);
+  if (filePathMatch) {
+    try {
+      const mentionedPath = filePathMatch[0];
+      const absPath = path.isAbsolute(mentionedPath)
+        ? mentionedPath
+        : path.join(projectPath, mentionedPath);
+      if (fs.existsSync(absPath)) {
+        fileContent = fs.readFileSync(absPath, 'utf-8').slice(0, 8000);
+      }
+    } catch { /* ignore */ }
+  }
+
+  // File tree from project context
+  const fileTree = projectContext ? projectContext.fileTree : '';
+
+  const contextMdSection = contextMdContent
+    ? `\n## Guías de marca / Design tokens\n${contextMdContent}`
+    : '';
+
+  const fileTreeSection = fileTree
+    ? `\n## Contexto del proyecto\n\`\`\`\n${fileTree.slice(0, 3000)}\n\`\`\``
+    : '';
+
+  const fileContentSection = fileContent
+    ? `\n## Contenido actual del archivo relevante\n\`\`\`\n${fileContent}\n\`\`\``
+    : '';
+
+  // Error memory: tell the agent what went wrong in a previous attempt
+  const retrySection = (task.retryCount > 0 && task.previousOutput)
+    ? `\n\n## ⚠ Intento anterior fallido (intento ${task.retryCount})\nEsto es lo que salió en el intento anterior — **no repitas el mismo enfoque**:\n\`\`\`\n${task.previousOutput.slice(-2000)}\n\`\`\``
+    : '';
+
+  // Agent handoffs: context from previous agents that already worked on this project
+  const handoffs = readHandoffs(task.id);
+  const handoffSection = handoffs.length > 0
+    ? `\n\n## Contexto de agentes anteriores\n${handoffs.join('\n\n---\n\n').slice(0, 4000)}`
+    : '';
+
+  const prompt = `Sos un agente de desarrollo de software. Completá la siguiente tarea exactamente como se describe.
+
+## Tarea
+Título: ${task.title}
+Descripción: ${task.description}
+Criterio de éxito: ${task.successCriteria}
+Prioridad: ${task.priority || 'medium'}
+
+## Directorio de trabajo
+${projectPath}
+${fileTreeSection}${contextMdSection}${fileContentSection}${handoffSection}${retrySection}
+
+Trabajá en el directorio actual. Sé meticuloso, seguí el estilo existente del código y las guías de marca si están disponibles.
+
+Cuando termines, escribí un bloque <HANDOFF> con lo que hiciste para que el próximo agente lo sepa:
+<HANDOFF>
+Archivos modificados: [lista de archivos]
+Decisiones tomadas: [notas clave sobre el enfoque]
+Lo que falta: [si algo quedó pendiente, si no nada]
+</HANDOFF>`;
+
+  updateTask(task.id, { status: 'in_progress', agentLabel });
+  if (broadcast) broadcast({ type: 'task:started', taskId: task.id, agentLabel });
+
+  const proc = spawnClaude(prompt, projectPath);
+
+  const timer = setTimeout(() => {
+    if (!proc.killed) {
+      console.warn(`[orchestrator] agent for task ${task.id} timed out — killing`);
+      proc.kill('SIGTERM');
+    }
+  }, AGENT_TIMEOUT_MS);
+
+  activeAgents.set(task.id, { proc, timer });
+
+  proc.stdout.on('data', (data) => {
+    const chunk = data.toString('utf-8');
+    const current = getTask(task.id);
+    if (current) {
+      updateTask(task.id, { output: (current.output || '') + chunk });
+    }
+    if (broadcast) broadcast({ type: 'task:output', taskId: task.id, chunk });
+  });
+
+  proc.stderr.on('data', () => {
+    // Swallow stderr — don't expose system paths or tokens
+  });
+
+  proc.on('close', () => {
+    clearTimeout(timer);
+    activeAgents.delete(task.id);
+    const current = getTask(task.id);
+    // Extract and save handoff note for future agents
+    if (current) {
+      const outputText = Array.isArray(current.output)
+        ? current.output.map(e => e.chunk || '').join('')
+        : (current.output || '');
+      const handoffMatch = outputText.match(/<HANDOFF>([\s\S]*?)<\/HANDOFF>/);
+      if (handoffMatch) writeHandoff(task.id, handoffMatch[1].trim());
+    }
+    if (current && current.status === 'in_progress') {
+      runVerifier(current, broadcast, processQueue);
+    }
+    processQueue();
+  });
+
+  proc.on('error', (err) => {
+    clearTimeout(timer);
+    activeAgents.delete(task.id);
+    updateTask(task.id, { status: 'error' });
+    if (broadcast) broadcast({ type: 'task:error', taskId: task.id, reason: 'Agent process failed to start' });
+    console.error(`[orchestrator] spawn error for task ${task.id}:`, err.message);
+    processQueue();
+  });
+}
+
+function processQueue() {
+  // Don't start tasks while waiting for user to provide required credentials
+  if (awaitingSupabaseCreds) return;
+
+  const tasks = getTasks();
+  const backlog = tasks.filter(t => t.status === 'backlog');
+  // Always run 1 task at a time so each agent sees the previous agent's handoff context
+  const slots = 1 - activeAgents.size;
+  const priorityOrder = { high: 0, medium: 1, low: 2 };
+  const toStart = backlog
+    .sort((a, b) => (priorityOrder[a.priority] ?? 1) - (priorityOrder[b.priority] ?? 1))
+    .slice(0, Math.max(0, slots));
+  toStart.forEach(t => spawnTaskAgent(t));
+
+  // Trigger QA when all tasks are done and none are running
+  if (toStart.length === 0 && activeAgents.size === 0 && !qaAgentRan) {
+    const allTasks = getTasks();
+    const pending = allTasks.filter(t => ['backlog', 'in_progress', 'verifying'].includes(t.status));
+    const done = allTasks.filter(t => t.status === 'done');
+    if (pending.length === 0 && done.length > 0) {
+      qaAgentRan = true;
+      spawnQAAgent(allTasks);
+    }
+  }
+}
+
+function startTask(taskId) {
+  const task = getTask(taskId);
+  if (!task) return;
+  if (task.status === 'error') {
+    updateTask(taskId, { status: 'backlog', output: '', verifierOutput: '' });
+    const reset = getTask(taskId);
+    if (broadcast) broadcast({ type: 'task:updated', task: reset });
+    spawnTaskAgent(reset);
+  } else if (task.status === 'backlog') {
+    spawnTaskAgent(task);
+  }
+}
+
+function spawnQAAgent(allTasks) {
+  const prd = (() => { try { return getPRD() || ''; } catch { return ''; } })();
+  const doneSummary = allTasks.filter(t => t.status === 'done').map(t => `- ${t.title}`).join('\n');
+  const errorSummary = allTasks.filter(t => t.status === 'error').map(t => `- ${t.title}`).join('\n');
+
+  const targetUrl = `http://127.0.0.1:${serverPort}`;
+  const screenshotPath = path.join(process.cwd(), '.claudeboard', 'qa-screenshot.png');
+  const screenshotPathEscaped = screenshotPath.replace(/\\/g, '/');
+
+  // Platform hints for finding Chrome
+  let findChromeHint, chromeFlagHint;
+  if (process.platform === 'win32') {
+    findChromeHint = `Run this to find Chrome: cmd /c "where chrome 2>nul & where msedge 2>nul & dir \\"C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe\\" 2>nul & dir \\"C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe\\" 2>nul"`;
+    chromeFlagHint = `--headless=new --disable-gpu --no-sandbox --screenshot="${screenshotPathEscaped}" --window-size=1280,900`;
+  } else if (process.platform === 'darwin') {
+    findChromeHint = `Run: which google-chrome || ls "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" 2>/dev/null`;
+    chromeFlagHint = `--headless=new --disable-gpu --no-sandbox --screenshot="${screenshotPath}" --window-size=1280,900`;
+  } else {
+    findChromeHint = `Run: which google-chrome || which chromium-browser || which chromium`;
+    chromeFlagHint = `--headless=new --disable-gpu --no-sandbox --screenshot="${screenshotPath}" --window-size=1280,900`;
+  }
+
+  const prompt = `You are a QA Engineer doing a visual review of a web project.
+The app is running at: ${targetUrl}
+
+PRD / Objective:
+${prd || 'No PRD available — review the completed tasks below.'}
+
+Completed tasks:
+${doneSummary || '(none)'}
+${errorSummary ? `\nFailed tasks (not fixed):\n${errorSummary}` : ''}
+
+== YOUR STEPS (follow in order) ==
+
+STEP 1 — Find Chrome on this machine.
+${findChromeHint}
+If Chrome is not found, try Microsoft Edge (msedge) as a fallback.
+
+STEP 2 — Take a screenshot.
+Use the Chrome (or Edge) path you found and run:
+  [chrome-path] ${chromeFlagHint} ${targetUrl}
+This saves the screenshot to: ${screenshotPath}
+NOTE: This runs headless — no window will open. It silently saves the PNG file.
+
+STEP 3 — Read the screenshot file.
+Use your file reading tool to read the image at: ${screenshotPath}
+Look carefully at: layout, colors, spacing, broken elements, missing content, typography.
+
+STEP 4 — Review the source files.
+Also read the main HTML/CSS/JS files of the project to spot any code-level issues.
+
+STEP 5 — Report results.
+If you find visual or functional issues, output EXACTLY this format (no JSON, no markdown fences):
+
+<TASKS>
+<TASK>
+title: Fix: [describe the issue concisely]
+description: [exact file path + what to change]
+successCriteria: [how to verify it looks/works correctly]
+priority: high
+</TASK>
+</TASKS>
+
+If everything is correct, say only: QA PASSED — all objectives met.`;
+
+  if (broadcast) broadcast({ type: 'qa:started' });
+
+  const projectPath = getProjectPath();
+  const proc = spawnClaude(prompt, projectPath);
+  qaBuffer = '';
+
+  proc.stdout.on('data', (data) => {
+    const chunk = data.toString('utf-8');
+    if (broadcast) broadcast({ type: 'qa:output', chunk });
+    qaBuffer += chunk;
+    if (qaBuffer.includes('</TASKS>')) {
+      const taskBlocks = [...qaBuffer.matchAll(/<TASK>([\s\S]*?)<\/TASK>/g)];
+      if (taskBlocks.length > 0) {
+        const taskDefs = taskBlocks.map(m => {
+          const block = m[1];
+          const get = (key) => {
+            const match = block.match(new RegExp(`^${key}:\\s*(.+)$`, 'mi'));
+            return match ? match[1].trim() : '';
+          };
+          return { title: get('title'), description: get('description'), successCriteria: get('successCriteria'), priority: get('priority') || 'high' };
+        }).filter(t => t.title);
+        if (taskDefs.length > 0) {
+          const created = taskDefs.map(t => createTask(t));
+          if (broadcast) broadcast({ type: 'tasks:created', tasks: created });
+          qaAgentRan = false; // new QA tasks → allow QA to run again after they complete
+          qaBuffer = '';
+          processQueue();
+        }
+      }
+    }
+  });
+
+  proc.on('close', () => {
+    if (broadcast) broadcast({ type: 'qa:done' });
+    // Send screenshot inline to chat (cap at 2 MB)
+    try {
+      if (fs.existsSync(screenshotPath)) {
+        const stats = fs.statSync(screenshotPath);
+        if (stats.size > 0 && stats.size < 2 * 1024 * 1024) {
+          const base64 = fs.readFileSync(screenshotPath).toString('base64');
+          if (broadcast) broadcast({ type: 'qa:screenshot', image: `data:image/png;base64,${base64}` });
+        }
+      }
+    } catch { /* ignore — screenshot is optional */ }
+  });
+
+  proc.on('error', (err) => {
+    console.error('[qa] spawn error:', err.message);
+    if (broadcast) broadcast({ type: 'qa:done' });
+  });
+}
+
+// Production checklist agent — web or mobile depending on project deps
+function spawnChecklistAgent() {
+  const projectPath = getProjectPath();
+  let isMobile = false;
+  try {
+    const pkgPath = path.join(projectPath, 'package.json');
+    if (fs.existsSync(pkgPath)) {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+      const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+      isMobile = !!(deps['react-native'] || deps['expo'] || deps['@capacitor/core'] || deps['flutter']);
+    }
+  } catch { /* ignore */ }
+
+  const checklist = isMobile ? `
+1. App icon: app.json/expo has a valid icon path, not placeholder
+2. Bundle ID: bundleIdentifier/packageName is NOT "com.example" or placeholder
+3. No hardcoded localhost URLs in API calls or config files
+4. Permissions declared only if actually used
+5. App store metadata: name and description filled in app.json/expo.json
+6. No console.log in production code
+7. Version/build number is set (not 1.0.0 default)` : `
+1. Favicon: <link rel="icon"> present in index.html, file exists
+2. Viewport meta: <meta name="viewport" content="width=device-width, initial-scale=1">
+3. Description meta: <meta name="description" content="..."> with real text, not empty
+4. All images have alt attributes
+5. No http:// links (use https:// or relative)
+6. Form submit handlers present
+7. No console.log in production code
+8. Title tag not "React App", "Vite App" or other placeholder default`;
+
+  const prompt = `You are a production readiness agent. Review this ${isMobile ? 'mobile' : 'web'} project for production readiness.
+
+Project directory: ${projectPath}
+
+PRODUCTION CHECKLIST (${isMobile ? 'MOBILE' : 'WEB'}):
+${checklist}
+
+INSTRUCTIONS:
+1. Read the relevant project files (index.html, package.json, app.json, source files).
+2. Check each checklist item one by one.
+3. If you find issues, output EXACTLY this format:
+
+<TASKS>
+<TASK>
+title: Fix: [concise issue description]
+description: [exact file and what to change]
+successCriteria: [how to verify it's fixed]
+priority: high
+</TASK>
+</TASKS>
+
+If everything passes, say only: CHECKLIST PASSED — project is production ready.`;
+
+  if (broadcast) broadcast({ type: 'checklist:started', isMobile });
+
+  const proc = spawnClaude(prompt, projectPath);
+  let checklistBuffer = '';
+
+  proc.stdout.on('data', (data) => {
+    const chunk = data.toString('utf-8');
+    if (broadcast) broadcast({ type: 'checklist:output', chunk });
+    checklistBuffer += chunk;
+    if (checklistBuffer.includes('</TASKS>')) {
+      const taskBlocks = [...checklistBuffer.matchAll(/<TASK>([\s\S]*?)<\/TASK>/g)];
+      if (taskBlocks.length > 0) {
+        const taskDefs = taskBlocks.map(m => {
+          const block = m[1];
+          const get = (key) => { const match = block.match(new RegExp(`^${key}:\\s*(.+)$`, 'mi')); return match ? match[1].trim() : ''; };
+          return { title: get('title'), description: get('description'), successCriteria: get('successCriteria'), priority: 'high' };
+        }).filter(t => t.title);
+        if (taskDefs.length > 0) {
+          const created = taskDefs.map(t => createTask(t));
+          if (broadcast) broadcast({ type: 'tasks:created', tasks: created });
+          checklistBuffer = '';
+          processQueue();
+        }
+      }
+    }
+  });
+
+  proc.on('close', () => { if (broadcast) broadcast({ type: 'checklist:done', passed: checklistBuffer.includes('CHECKLIST PASSED') }); });
+  proc.on('error', (err) => { console.error('[checklist] spawn error:', err.message); if (broadcast) broadcast({ type: 'checklist:done', passed: false }); });
+}
+
+// Deploy to Netlify
+function spawnDeployAgent() {
+  const projectPath = getProjectPath();
+  let buildCmd = 'npm run build';
+  let distDir = 'dist';
+  try {
+    const pkgPath = path.join(projectPath, 'package.json');
+    if (fs.existsSync(pkgPath)) {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+      if (pkg.scripts && !pkg.scripts.build) buildCmd = 'echo "No build step"';
+    }
+    for (const dir of ['dist', 'build', 'out', '.next']) {
+      if (fs.existsSync(path.join(projectPath, dir))) { distDir = dir; break; }
+    }
+  } catch { /* ignore */ }
+
+  const prompt = `You are a DevOps agent. Deploy this project to Netlify.
+
+Project directory: ${projectPath}
+Likely build command: ${buildCmd}
+Likely dist directory: ${distDir}
+
+STEPS:
+1. Check if netlify CLI is installed: run \`netlify --version\`. If not found, run \`npm install -g netlify-cli\`.
+2. Check if already linked: look for .netlify/state.json in project directory.
+3. Build the project: run \`${buildCmd}\` in the project directory.
+4. Deploy: run \`netlify deploy --prod --dir=${distDir}\` in the project directory.
+5. Report the live URL.
+
+If any step fails, clearly explain what failed and why.
+At the end, output the deployment URL exactly like this: DEPLOYED: https://your-site.netlify.app`;
+
+  if (broadcast) broadcast({ type: 'deploy:started' });
+
+  const proc = spawnClaude(prompt, projectPath);
+  let deployBuffer = '';
+
+  proc.stdout.on('data', (data) => {
+    const chunk = data.toString('utf-8');
+    if (broadcast) broadcast({ type: 'deploy:output', chunk });
+    deployBuffer += chunk;
+  });
+
+  proc.on('close', () => {
+    const urlMatch = deployBuffer.match(/DEPLOYED:\s*(https?:\/\/\S+)/);
+    if (broadcast) broadcast({ type: 'deploy:done', url: urlMatch ? urlMatch[1] : null });
+  });
+
+  proc.on('error', (err) => {
+    console.error('[deploy] spawn error:', err.message);
+    if (broadcast) broadcast({ type: 'deploy:done', url: null });
+  });
+}
+
+function stopTask(taskId) {
+  const agent = activeAgents.get(taskId);
+  if (agent) {
+    clearTimeout(agent.timer);
+    if (!agent.proc.killed) agent.proc.kill('SIGTERM');
+    activeAgents.delete(taskId);
+  }
+  updateTask(taskId, { status: 'backlog' });
+  if (broadcast) broadcast({ type: 'task:stopped', taskId });
+}
+
+function pauseAll() {
+  for (const [taskId, { proc, timer }] of activeAgents) {
+    clearTimeout(timer);
+    if (!proc.killed) proc.kill('SIGTERM');
+    updateTask(taskId, { status: 'backlog' });
+    if (broadcast) broadcast({ type: 'task:stopped', taskId });
+  }
+  activeAgents.clear();
+}
+
+function killAll() {
+  for (const [, { proc, timer }] of activeAgents) {
+    clearTimeout(timer);
+    if (!proc.killed) proc.kill('SIGTERM');
+  }
+  activeAgents.clear();
+}
+
+// Manual QA trigger — can be called regardless of task state
+function runQA() {
+  qaAgentRan = false;
+  spawnQAAgent(getTasks());
+}
+
+// Upload PRD from a markdown file — sends it through the orchestrator to generate tasks
+function uploadPRD(content) {
+  const trimmed = content.slice(0, 20000);
+  sendMessage(`Tengo mi PRD listo. Analizalo y creá las tareas necesarias para implementarlo:\n\n${trimmed}`);
+}
+
+// Called when the user submits Supabase credentials from the modal
+function provideCredentials({ supabaseUrl, anonKey, serviceKey, writeDotEnv }) {
+  awaitingSupabaseCreds = false;
+
+  if (writeDotEnv && supabaseUrl) {
+    try {
+      const projectPath = getProjectPath();
+      const envPath = path.join(projectPath, '.env');
+      let envContent = '';
+      try { envContent = fs.readFileSync(envPath, 'utf-8'); } catch { /* file doesn't exist yet */ }
+
+      const vars = {
+        SUPABASE_URL: supabaseUrl || '',
+        SUPABASE_ANON_KEY: anonKey || '',
+      };
+      if (serviceKey) vars['SUPABASE_SERVICE_ROLE_KEY'] = serviceKey;
+
+      for (const [key, val] of Object.entries(vars)) {
+        if (!val) continue;
+        const regex = new RegExp(`^${key}=.*$`, 'm');
+        if (regex.test(envContent)) {
+          envContent = envContent.replace(regex, `${key}=${val}`);
+        } else {
+          envContent += `\n${key}=${val}`;
+        }
+      }
+      fs.writeFileSync(envPath, envContent.trim() + '\n', 'utf-8');
+      if (broadcast) broadcast({ type: 'supabase:env_saved' });
+    } catch (err) {
+      console.error('[orchestrator] failed to write .env:', err.message);
+    }
+  }
+
+  processQueue();
+}
+
+module.exports = { setBroadcast, setMaxAgents, setServerPort, sendMessage, startTask, processQueue, startOrchestrator, killAll, stopTask, pauseAll, runQA, spawnChecklistAgent, spawnDeployAgent, uploadPRD, provideCredentials };