@fermindi/pwn-cli 0.6.0 → 0.8.0

package/src/services/batch-runner.js

@@ -0,0 +1,860 @@
+/**
+ * PWN Batch Runner — Node.js TUI with chalk
+ *
+ * Two-phase execution model:
+ * Phase 1: Planning — Claude estimates time and creates action plan
+ * Phase 2: Execution — Dynamic timeout based on estimate + 20%
+ *
+ * Task files (.ai/batch/tasks/{US-ID}.json) track status per story.
+ * Completed files are cleaned up at the end; failed are kept for review.
+ */
+
+import { spawn } from 'child_process';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, createWriteStream, appendFileSync, unlinkSync, readdirSync } from 'fs';
+import { join } from 'path';
+import ora from 'ora';
+import chalk from 'chalk';
+import {
+  parsePrdTasks,
+  selectNextTask,
+  markStoryDone,
+  runQualityGate,
+  loadConfig,
+  commitTask,
+  updateBatchState,
+  clearBatchState
+} from './batch-service.js';
+
+// --- Constants ---
+const RUNNER_VERSION = '2.1';
+const DEFAULT_TIMEOUT_MS = 900_000;  // 15 minutes fallback
+const MIN_TIMEOUT_MS = 300_000;      // 5 minutes minimum (claude init ~30-40s + real work)
+
+// Complexity → timeout mapping (based on real-world execution data)
+// AI is bad at estimating seconds but decent at classifying complexity
+const COMPLEXITY_TIMEOUT = {
+  low:    { seconds: 300,  label: '5m' },    // config change, small fix
+  medium: { seconds: 600,  label: '10m' },   // new function, 1-3 files
+  high:   { seconds: 900,  label: '15m' },   // new module, multi-file refactor
+};
+const PLAN_TIMEOUT_MS = 120_000;     // 2 minutes for planning phase (claude init ~30s)
+const DEFAULT_RATE_LIMIT_WAIT = 1800; // 30 minutes (seconds)
+const MAX_RETRIES = 2;
+const MAX_NO_PROGRESS = 3;           // circuit breaker
+const RATE_LIMIT_RE = /rate.?limit|429|overloaded|hit your limit|quota exceeded|resets|too many requests/i;
+const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+
+// --- Task File CRUD ---
+
+function getTasksDir(cwd) {
+  return join(cwd, '.ai', 'batch', 'tasks');
+}
+
+export function saveTaskFile(taskData, cwd) {
+  const tasksDir = getTasksDir(cwd);
+  mkdirSync(tasksDir, { recursive: true });
+  const filePath = join(tasksDir, `${taskData.id}.json`);
+  writeFileSync(filePath, JSON.stringify(taskData, null, 2));
+}
+
+export function loadTaskFile(taskId, cwd) {
+  const filePath = join(getTasksDir(cwd), `${taskId}.json`);
+  if (!existsSync(filePath)) return null;
+  return JSON.parse(readFileSync(filePath, 'utf8'));
+}
+
+export function deleteTaskFile(taskId, cwd) {
+  const filePath = join(getTasksDir(cwd), `${taskId}.json`);
+  if (existsSync(filePath)) {
+    unlinkSync(filePath);
+    return true;
+  }
+  return false;
+}
+
+export function listTaskFiles(cwd, { statusFilter } = {}) {
+  const tasksDir = getTasksDir(cwd);
+  if (!existsSync(tasksDir)) return [];
+  const files = readdirSync(tasksDir).filter(f => f.endsWith('.json'));
+  const tasks = files.map(f => JSON.parse(readFileSync(join(tasksDir, f), 'utf8')));
+  if (statusFilter) return tasks.filter(t => t.status === statusFilter);
+  return tasks;
+}
+
+// --- Rate Limit Handling ---
+
+function isRateLimitError(output) {
+  return output && RATE_LIMIT_RE.test(output);
+}
+
+async function waitForRateLimit(waitSeconds, attempt) {
+  const resumeAt = new Date(Date.now() + waitSeconds * 1000);
+  console.log(chalk.yellow(`  Rate limited (wait #${attempt}). Cooling down ${formatDuration(waitSeconds)}...`));
+  console.log(chalk.dim(`  Resumes at: ${resumeAt.toLocaleTimeString()}`));
+
+  let remaining = waitSeconds;
+  while (remaining > 0) {
+    const spinner = SPINNER_FRAMES[Math.floor(Date.now() / 80) % SPINNER_FRAMES.length];
+    process.stdout.write(`\r\x1b[K  ${chalk.yellow(spinner)} Rate limit cooldown: ${chalk.bold(formatDuration(remaining))} remaining`);
+    const tick = Math.min(remaining, 1);
+    await sleep(tick * 1000);
+    remaining -= tick;
+  }
+  process.stdout.write('\r\x1b[K');
+  console.log(chalk.green('  Cooldown complete. Retrying...'));
+}
+
+// --- Planning Phase ---
+
+function buildPlanPrompt(task, cwd, replanContext = null) {
+  const prdPath = join(cwd, '.ai', 'tasks', 'prd.json');
+  const prd = JSON.parse(readFileSync(prdPath, 'utf8'));
+  const story = prd.stories.find(s => s.id === task.id);
+  if (!story) return '';
+
+  const acList = (story.acceptance_criteria || []).map(ac => `- ${ac}`).join('\n') || 'None';
+
+  let replanSection = '';
+  if (replanContext) {
+    replanSection = `
+
+IMPORTANT — REPLANNING: A previous attempt FAILED.
+- Previous complexity: ${replanContext.previousComplexity}
+- Failure reason: ${replanContext.failureReason}
+Re-evaluate the complexity. If it timed out, it's likely MORE complex than you initially thought.`;
+  }
+
+  return `You are analyzing task ${task.id}: ${task.title}
+
+Acceptance criteria:
+${acList}
+
+Notes: ${story.notes || 'None'}
+${replanSection}
+Analyze this task and respond with ONLY a JSON object (no markdown, no code fences):
+{
+  "plan": ["step 1", "step 2", ...],
+  "complexity": "low|medium|high",
+  "recommended_model": "opus|sonnet|haiku",
+  "files_likely_affected": ["path1", "path2"]
+}
+
+Classify complexity:
+- "low": config change, small fix, single file tweak
+- "medium": new function, simple feature, 1-3 files
+- "high": new module, multi-file refactor, architecture change, 4+ files
+
+Recommend a model for execution:
+- "haiku": trivial (config change, typo, single-line fix)
+- "sonnet": low-medium complexity (new function, simple feature, 1-3 files)
+- "opus": high complexity (new module, multi-file refactor, architecture)`;
+}
+
+async function planTask(task, cwd, replanContext = null) {
+  const prompt = buildPlanPrompt(task, cwd, replanContext);
+  if (!prompt) return null;
+
+  const env = { ...process.env };
+  // Remove all Claude session markers to avoid "nested session" detection
+  Object.keys(env).forEach(k => { if (k.startsWith('CLAUDE')) delete env[k]; });
+
+  return new Promise((resolve) => {
+    let output = '';
+
+    // Planning uses --print WITHOUT --dangerously-skip-permissions (read-only)
+    const child = spawn('bash', [
+      '-c',
+      `claude --model opus --print -p "$(cat)"`,
+    ], {
+      cwd,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      env,
+    });
+
+    // Pass prompt via stdin
+    child.stdin.write(prompt);
+    child.stdin.end();
+
+    const timeoutId = setTimeout(() => {
+      child.kill('SIGTERM');
+    }, PLAN_TIMEOUT_MS);
+
+    child.stdout.on('data', (data) => { output += data.toString(); });
+    child.stderr.on('data', (data) => { output += data.toString(); });
+
+    child.on('close', (code, signal) => {
+      clearTimeout(timeoutId);
+
+      if (signal) {
+        console.log(chalk.dim(`    Planning killed by ${signal} (timeout=${signal === 'SIGTERM' ? 'likely' : 'no'})`));
+        resolve(null);
+        return;
+      }
+      if (code !== 0) {
+        console.log(chalk.dim(`    Planning exited with code ${code}`));
+        resolve(null);
+        return;
+      }
+
+      // Try to parse JSON from output
+      try {
+        let jsonStr = output.trim();
+        const jsonMatch = jsonStr.match(/\{[\s\S]*\}/);
+        if (jsonMatch) jsonStr = jsonMatch[0];
+        const parsed = JSON.parse(jsonStr);
+        resolve(parsed);
+      } catch (e) {
+        console.log(chalk.dim(`    Planning JSON parse failed: ${e.message}`));
+        console.log(chalk.dim(`    Raw output (first 200 chars): ${output.slice(0, 200)}`));
+        resolve(null);
+      }
+    });
+
+    child.on('error', (err) => {
+      clearTimeout(timeoutId);
+      console.log(chalk.dim(`    Planning spawn error: ${err.message}`));
+      resolve(null);
+    });
+  });
+}
+
+function computeTimeout(estimatedSeconds) {
+  if (!estimatedSeconds || estimatedSeconds <= 0) return DEFAULT_TIMEOUT_MS;
+  return Math.max(Math.ceil(estimatedSeconds * 1.05) * 1000, MIN_TIMEOUT_MS);
+}
+
+/**
+ * Main entry point for the TUI batch runner.
+ */
+export async function runBatch(options = {}, cwd = process.cwd()) {
+  const prdPath = join(cwd, '.ai', 'tasks', 'prd.json');
+  const promptPath = join(cwd, '.ai', 'batch', 'prompt.md');
+  const logDir = join(cwd, 'logs');
+  const progressPath = join(cwd, '.ai', 'batch', 'progress.txt');
+  const noPlan = options.noPlan || false;
+  const rateLimitWait = options.rateLimitWait || DEFAULT_RATE_LIMIT_WAIT;
+
+  // --- Pre-flight checks ---
+  if (!existsSync(prdPath)) {
+    console.log(chalk.red('Error:') + ` ${prdPath} not found`);
+    process.exit(1);
+  }
+  if (!existsSync(promptPath)) {
+    console.log(chalk.red('Error:') + ` ${promptPath} not found`);
+    process.exit(1);
+  }
+
+  mkdirSync(logDir, { recursive: true });
+  mkdirSync(getTasksDir(cwd), { recursive: true });
+
+  const stories = parsePrdTasks(cwd);
+  const totalStories = stories.length;
+  const doneAtStart = stories.filter(s => s.passes).length;
+  const phaseFilter = options.phase ? `Phase ${options.phase}` : undefined;
+  const taskFilter = options.filter || null;
+
+  // Count remaining eligible stories (respecting filters)
+  const doneIds = stories.filter(s => s.passes).map(s => s.id);
+  const filterRe = taskFilter ? new RegExp(taskFilter, 'i') : null;
+  const eligibleCount = stories.filter(s =>
+    !s.passes &&
+    s.dependencies.every(dep => doneIds.includes(dep)) &&
+    (!phaseFilter || s.phase === phaseFilter) &&
+    (!filterRe || filterRe.test(s.id) || filterRe.test(s.title))
+  ).length;
+  const maxIterations = options.maxIterations || eligibleCount;
+
+  // --- Dry run ---
+  if (options.dryRun) {
+    return dryRunPreview(cwd, phaseFilter, maxIterations, taskFilter);
+  }
+
+  // --- Print header ---
+  printHeader(maxIterations, phaseFilter, totalStories, doneAtStart, noPlan, cwd, taskFilter);
+
+  // NO custom SIGINT handler — Ctrl+C uses default Node.js behavior (kills process group)
+
+  // --- Main loop ---
+  let iteration = 0;
+  let noProgressCount = 0;
+  let storiesCompleted = 0;
+  const batchStart = Date.now();
+
+  updateBatchState({
+    started_at: new Date().toISOString(),
+    status: 'running',
+    completed: [],
+    max_tasks: maxIterations
+  }, cwd);
+
+  while (iteration < maxIterations) {
+    iteration++;
+
+    const task = selectNextTask(cwd, { phase: phaseFilter, filter: taskFilter });
+    if (!task) {
+      console.log(chalk.green('\nAll eligible stories completed!'));
+      break;
+    }
+
+    const currentDone = parsePrdTasks(cwd).filter(s => s.passes).length;
+
+    console.log(chalk.dim(`\n--- Iteration ${iteration}/${maxIterations} ---`));
+    console.log(`${chalk.cyan(`[${currentDone + 1}/${totalStories}]`)} ${chalk.bold(task.id)}: ${task.title}`);
+
+    // --- Phase 1: Planning (skip if already planned) ---
+    let taskTimeoutMs = DEFAULT_TIMEOUT_MS;
+    let taskFile = null;
+
+    if (!noPlan) {
+      const existing = loadTaskFile(task.id, cwd);
+
+      const needsReplan = existing && existing.last_failure_type && existing.status !== 'completed';
+      if (existing && existing.status === 'planned' && existing.complexity !== 'unknown' && !needsReplan) {
+        // Reuse previous plan (only if it hasn't failed before)
+        taskFile = existing;
+        taskTimeoutMs = computeTimeout(existing.estimated_time_seconds);
+        console.log(chalk.dim(`  Phase 1: Reusing plan for ${task.id} (${existing.complexity}, ~${formatDuration(existing.estimated_time_seconds)}, model: ${existing.recommended_model || 'sonnet'})`));
+      } else {
+        console.log(chalk.blue(`  Phase 1: Planning ${task.id}...`));
+        const planSpinner = ora({ text: `Planning ${task.id}...`, indent: 2 }).start();
+
+        const planResult = await planTask(task, cwd);
+
+        if (planResult) {
+          const complexity = planResult.complexity || 'medium';
+          const tier = COMPLEXITY_TIMEOUT[complexity] || COMPLEXITY_TIMEOUT.medium;
+          const estimatedSeconds = tier.seconds;
+          const timeoutSeconds = Math.ceil(estimatedSeconds * 1.05);
+          taskTimeoutMs = timeoutSeconds * 1000;
+
+          const recommendedModel = planResult.recommended_model || 'sonnet';
+          taskFile = {
+            id: task.id,
+            title: task.title,
+            status: 'planned',
+            estimated_time_seconds: estimatedSeconds,
+            timeout_seconds: timeoutSeconds,
+            plan: planResult.plan || [],
+            complexity,
+            recommended_model: recommendedModel,
+            files_likely_affected: planResult.files_likely_affected || [],
+            created_at: new Date().toISOString(),
+            completed_at: null,
+            failure_reason: null
+          };
+          saveTaskFile(taskFile, cwd);
+
+          planSpinner.succeed(chalk.green(
+            `Planned: ${complexity} complexity, timeout ${tier.label}, model: ${recommendedModel}`
+          ));
+        } else {
+          // Fallback when planning fails
+          const fallbackSeconds = DEFAULT_TIMEOUT_MS / 1000;
+          taskFile = {
+            id: task.id,
+            title: task.title,
+            status: 'planned',
+            estimated_time_seconds: fallbackSeconds,
+            timeout_seconds: fallbackSeconds,
+            plan: ['fallback - no plan available'],
+            complexity: 'unknown',
+            recommended_model: 'sonnet',
+            files_likely_affected: [],
+            created_at: new Date().toISOString(),
+            completed_at: null,
+            failure_reason: null
+          };
+          saveTaskFile(taskFile, cwd);
+          taskTimeoutMs = DEFAULT_TIMEOUT_MS;
+
+          planSpinner.warn(chalk.yellow(`Planning failed, using default timeout (${formatDuration(fallbackSeconds)})`));
+        }
+      }
+    }
+
+    // --- Phase 2: Execution ---
+    const phaseLabel = noPlan ? '' : 'Phase 2';
+    console.log(chalk.blue(`  ${noPlan ? 'Executing' : 'Phase 2: Executing'} ${task.id}...`));
+
+    let retry = 0;
+    let rateLimitAttempts = 0;
+    let storyDone = false;
+    let errorContext = '';
+
+    while (retry <= MAX_RETRIES && !storyDone) {
+      if (retry > 0) {
+        console.log(chalk.yellow(`  Retry ${retry}/${MAX_RETRIES}`));
+      }
+
+      const prompt = buildPrompt(task.id, cwd, prdPath, promptPath, errorContext);
+      if (!prompt) {
+        console.log(chalk.red(`  Cannot build prompt for ${task.id} — skipping`));
+        break;
+      }
+      const logFile = join(logDir, `${task.id}_${timestamp()}.log`);
+
+      const estimatedSeconds = taskFile?.estimated_time_seconds || null;
+      const executionModel = taskFile?.recommended_model || null;
+      const result = await spawnClaude(prompt, task, iteration, maxIterations, currentDone, totalStories, phaseFilter, logFile, cwd, taskTimeoutMs, estimatedSeconds, phaseLabel, executionModel);
+
+      // Killed by signal (user did kill or Ctrl+C) — don't retry, exit
+      if (result.signal) {
+        console.log(chalk.yellow(`  Killed by ${result.signal}`));
+        clearBatchState(cwd);
+        printSummary(cwd, iteration, storiesCompleted, batchStart);
+        return;
+      }
+
+      // Timeout
+      if (result.timedOut) {
+        // Timeout can also be caused by rate limit — check output
+        if (isRateLimitError(result.output)) {
+          rateLimitAttempts++;
+          await waitForRateLimit(rateLimitWait, rateLimitAttempts);
+          continue;
+        }
+
+        const prevTimeout = Math.round(taskTimeoutMs / 1000);
+        console.log(chalk.yellow(`  Timed out after ${prevTimeout}s`));
+
+        // --- Replan on timeout: bump complexity tier ---
+        if (taskFile) {
+          const prevComplexity = taskFile.complexity;
+          const prevEstimate = taskFile.estimated_time_seconds;
+
+          // Escalate complexity: low → medium → high, high stays high but doubles
+          const escalation = { low: 'medium', medium: 'high' };
+          const newComplexity = escalation[prevComplexity] || 'high';
+          const tier = COMPLEXITY_TIMEOUT[newComplexity] || COMPLEXITY_TIMEOUT.high;
+
+          // If already high, double the previous timeout
+          const newEstimate = prevComplexity === 'high'
+            ? prevEstimate * 2
+            : tier.seconds;
+          const newTimeout = Math.ceil(newEstimate * 1.05);
+          taskTimeoutMs = newTimeout * 1000;
+
+          taskFile.estimated_time_seconds = newEstimate;
+          taskFile.timeout_seconds = newTimeout;
+          taskFile.complexity = newComplexity;
+          taskFile.recommended_model = 'opus'; // upgrade model on timeout
+          taskFile.replanned_at = new Date().toISOString();
+          taskFile.replan_reason = `timeout after ${prevTimeout}s (${prevComplexity} → ${newComplexity})`;
+          saveTaskFile(taskFile, cwd);
+
+          console.log(chalk.blue(
+            `  Escalated: ${prevComplexity} → ${newComplexity}, timeout ${formatDuration(newTimeout)}, model: opus`
+          ));
+        }
+
+        errorContext = `Session timed out after ${prevTimeout}s. The task was replanned with more time. Focus on core acceptance criteria first, then iterate.`;
+        retry++;
+        continue;
+      }
+
+      // Non-zero exit (not from signal) — check if it's a rate limit
+      // Rate limit detection only on FAILURES. Successful output (exit 0) may
+      // mention "rate limit" as a feature description, not an actual API error.
+      if (result.exitCode !== 0) {
+        if (isRateLimitError(result.output)) {
+          rateLimitAttempts++;
+          await waitForRateLimit(rateLimitWait, rateLimitAttempts);
+          continue; // no retry increment — wait and try again
+        }
+        console.log(chalk.yellow(`  Claude exited with code ${result.exitCode}`));
+        errorContext = `Claude session failed with exit code ${result.exitCode}.`;
+
+        // Save error output snippet to task file for debugging
+        if (taskFile) {
+          taskFile.last_error_output = (result.output || '').slice(-2000);
+          taskFile.last_failure_type = 'crash';
+          saveTaskFile(taskFile, cwd);
+        }
+
+        retry++;
+        continue;
+      }
+
+      // Quality gates
+      const gatesResult = await runGatesWithStatus(cwd);
+
+      if (gatesResult.success) {
+        console.log(chalk.green(`  Quality gates PASSED`));
+        markStoryDone(task.id, cwd);
+        appendProgress(progressPath, task.id, 'All quality gates passed');
+
+        const config = loadConfig(cwd);
+        if (config.auto_commit) {
+          await commitTask(task, {}, cwd);
+        }
+
+        storyDone = true;
+        storiesCompleted++;
+        noProgressCount = 0;
+
+        // Update task file status
+        if (taskFile) {
+          taskFile.status = 'completed';
+          taskFile.completed_at = new Date().toISOString();
+          saveTaskFile(taskFile, cwd);
+        }
+
+        updateBatchState({
+          completed: [task.id],
+          current_task: null,
+          last_completed_at: new Date().toISOString()
+        }, cwd);
+      } else {
+        console.log(chalk.red(`  Quality gates FAILED`));
+        errorContext = gatesResult.errorOutput;
+
+        // Save gate failure details to task file
+        if (taskFile) {
+          taskFile.last_error_output = (gatesResult.errorOutput || '').slice(-2000);
+          taskFile.last_failure_type = 'quality_gate';
+          saveTaskFile(taskFile, cwd);
+        }
+
+        retry++;
+      }
+    }
+
+    if (!storyDone) {
+      const failureType = taskFile?.last_failure_type || 'unknown';
+      console.log(chalk.red(`  FAILED: ${task.id} after ${MAX_RETRIES} retries (${failureType})`));
+      appendProgress(progressPath, task.id, `FAILED after ${MAX_RETRIES} retries (${failureType}). Skipping.`);
+
+      // Update task file with failure
+      if (taskFile) {
+        taskFile.status = 'failed';
+        taskFile.failure_reason = errorContext || `Failed after ${MAX_RETRIES} retries`;
+        taskFile.completed_at = new Date().toISOString();
+        saveTaskFile(taskFile, cwd);
+      }
+
+      noProgressCount++;
+    }
+
+    if (noProgressCount >= MAX_NO_PROGRESS) {
+      console.log(chalk.red(`\nCIRCUIT BREAKER: ${MAX_NO_PROGRESS} consecutive failures. Stopping.`));
+      break;
+    }
+  }
+
+  clearBatchState(cwd);
+  printSummary(cwd, iteration, storiesCompleted, batchStart);
+}
+
+/**
+ * Spawn claude with piped stdio + spinner status line.
+ * Uses temp file for prompt to avoid shell escaping issues.
+ * Ctrl+C works because: no custom SIGINT handler + pipe mode (child not in foreground).
+ */
+function spawnClaude(prompt, task, iteration, maxIter, done, total, phase, logFile, cwd, timeoutMs = DEFAULT_TIMEOUT_MS, estimatedSeconds = null, phaseTag = '', model = null) {
+  return new Promise((resolve) => {
+    let bytesReceived = 0;
+    let output = '';
+    const logStream = createWriteStream(logFile);
+    const startTime = Date.now();
+
+    const env = { ...process.env };
+    // Remove all Claude session markers to avoid "nested session" detection
+    Object.keys(env).forEach(k => { if (k.startsWith('CLAUDE')) delete env[k]; });
+
+    const modelFlag = model ? `--model ${model} ` : '';
+    const child = spawn('bash', [
+      '-c',
+      `claude ${modelFlag}--print --dangerously-skip-permissions -p "$(cat)"`,
+    ], {
+      cwd,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      env,
+    });
+
+    // Pass prompt via stdin to avoid shell escaping issues and file race conditions
+    child.stdin.write(prompt);
+    child.stdin.end();
+
+    const modelLabel = model ? chalk.magenta(model) : chalk.dim('default');
+    console.log(chalk.dim(`  Log: tail -f ${logFile}`));
+    console.log(chalk.dim(`  PID: ${child.pid}  |  Model: `) + modelLabel + chalk.dim(`  |  Prompt: ${prompt.length} chars  |  Timeout: ${formatDuration(Math.round(timeoutMs / 1000))}`));
+
+    // Spinner via \r — no ora, no SIGINT hijack, no hidden cursor
+    let frame = 0;
+    const timer = setInterval(() => {
+      const spinner = chalk.cyan(SPINNER_FRAMES[frame++ % SPINNER_FRAMES.length]);
+      const elapsed = Math.round((Date.now() - startTime) / 1000);
+      const bytesLabel = bytesReceived === 0
+        ? chalk.dim('waiting (~2min)...')
+        : chalk.green(formatBytes(bytesReceived));
+      const phaseLabel = phase ? chalk.dim(` | ${phase}`) : '';
+      const estLabel = estimatedSeconds
+        ? ` / ${chalk.dim('~' + formatDuration(estimatedSeconds))}`
+        : '';
+      const phaseTagLabel = phaseTag ? chalk.dim(` | ${phaseTag}`) : '';
+      const modelIndicator = model ? chalk.dim(` | ${model}`) : '';
+      const line = `  ${spinner} ${chalk.cyan(`[${done + 1}/${total}]`)} ${task.id}: Executing  |  Iter ${iteration}/${maxIter}  |  ${chalk.yellow(formatDuration(elapsed))}${estLabel}  |  ${bytesLabel}${phaseLabel}${phaseTagLabel}${modelIndicator}`;
+      process.stdout.write(`\r\x1b[K${line}`);
+    }, 80);
+
+    const timeoutId = setTimeout(() => {
+      child.kill('SIGTERM');
+    }, timeoutMs);
+
+    child.stdout.on('data', (data) => {
+      bytesReceived += data.length;
+      output += data.toString();
+      logStream.write(data);
+    });
+    child.stderr.on('data', (data) => {
+      bytesReceived += data.length;
+      output += data.toString();
+      logStream.write(data);
+    });
+
+    child.on('close', (code, signal) => {
+      clearTimeout(timeoutId);
+      clearInterval(timer);
+      logStream.end();
+
+      // Clear spinner line
+      process.stdout.write('\r\x1b[K');
+
+      const elapsed = Math.round((Date.now() - startTime) / 1000);
+      // Timeout detection: SIGTERM signal, OR exit code 143 (128+SIGTERM) near the timeout boundary
+      const nearTimeout = elapsed >= Math.floor(timeoutMs / 1000) - 2;
+      const timedOut = nearTimeout && (signal === 'SIGTERM' || code === 143);
+
+      if (signal && !timedOut) {
+        console.log(chalk.dim(`  Claude killed (${signal}) after ${formatDuration(elapsed)}`));
+        resolve({ exitCode: code, output, timedOut: false, signal });
+        return;
+      }
+
+      console.log(chalk.dim(`  Claude finished in ${formatDuration(elapsed)} | ${formatBytes(bytesReceived)}`));
+      resolve({ exitCode: code ?? 1, output, timedOut, signal: null });
+    });
+
+    child.on('error', (err) => {
+      clearTimeout(timeoutId);
+      clearInterval(timer);
+      logStream.end();
+      process.stdout.write('\r\x1b[K');
+      console.log(chalk.red(`  Spawn error: ${err.message}`));
+      resolve({ exitCode: 1, output: '', timedOut: false, signal: null });
+    });
+  });
+}
+
+/**
+ * Run quality gates with real-time PASS/FAIL display.
+ */
+async function runGatesWithStatus(cwd) {
+  const config = loadConfig(cwd);
+  const gates = config.quality_gates || [];
+  const skipGates = config.skip_gates || [];
+  let allPassed = true;
+  let errorOutput = '';
+
+  for (const gate of gates) {
+    if (skipGates.includes(gate)) {
+      console.log(chalk.dim(`  ${gate}: SKIP`));
+      continue;
+    }
+
+    const spinner = ora({ text: `Running ${gate}...`, indent: 2 }).start();
+    const result = await runQualityGate(gate, cwd);
+
+    if (result.success || result.skipped) {
+      spinner.succeed(chalk.green(`${gate}: PASS`));
+    } else {
+      spinner.fail(chalk.red(`${gate}: FAIL`));
+      allPassed = false;
+      errorOutput += `=== ${gate} ===\n${result.error || result.stderr || ''}\n\n`;
+    }
+  }
+
+  return { success: allPassed, errorOutput };
+}
+
+/**
+ * Build the prompt from template, substituting placeholders.
+ */
+function buildPrompt(storyId, cwd, prdPath, promptPath, extraContext) {
+  const prd = JSON.parse(readFileSync(prdPath, 'utf8'));
+  const story = prd.stories.find(s => s.id === storyId);
+  if (!story) {
+    console.log(chalk.yellow(`  Warning: story ${storyId} not found in prd.json — may have been modified during execution`));
+    return '';
+  }
+
+  const doneIds = prd.stories.filter(s => s.passes).map(s => s.id);
+  const acList = (story.acceptance_criteria || []).map(ac => `- ${ac}`).join('\n') || 'None';
+
+  let depsList = 'None';
+  if (story.dependencies?.length > 0) {
+    depsList = story.dependencies
+      .filter(dep => doneIds.includes(dep))
+      .map(dep => {
+        const depStory = prd.stories.find(s => s.id === dep);
+        return `- ${dep}: ${depStory?.title || 'unknown'} (done)`;
+      })
+      .join('\n') || 'None';
+  }
+
+  let prompt = readFileSync(promptPath, 'utf8');
+  prompt = prompt.replaceAll('{STORY_ID}', storyId);
+  prompt = prompt.replaceAll('{STORY_TITLE}', story.title || '');
+  prompt = prompt.replaceAll('{ACCEPTANCE_CRITERIA}', acList);
+  prompt = prompt.replaceAll('{NOTES}', story.notes || '');
+  prompt = prompt.replaceAll('{DEPENDENCIES}', depsList);
+
+  if (extraContext) {
+    prompt += `\n\n## Previous Attempt Failed\nThe previous attempt failed quality gates. Here is the error output:\n\n\`\`\`\n${extraContext}\n\`\`\`\n\nFix these issues before committing.`;
+  }
+
+  return prompt;
+}
+
+/**
+ * Dry run: show formatted preview of eligible tasks.
+ */
+function dryRunPreview(cwd, phaseFilter, maxIterations, taskFilter = null) {
+  const stories = parsePrdTasks(cwd);
+  const total = stories.length;
+  const done = stories.filter(s => s.passes).length;
+  const remaining = total - done;
+
+  console.log(chalk.bold('\nDry Run Preview\n'));
+  console.log(`  Progress: ${chalk.green(done)}/${total} done, ${chalk.yellow(remaining)} remaining`);
+  console.log(`  Max iterations: ${maxIterations}`);
+  if (phaseFilter) console.log(`  Phase filter: ${chalk.blue(phaseFilter)}`);
+  if (taskFilter) console.log(`  Task filter:  ${chalk.blue(taskFilter)}`);
+
+  const doneIds = stories.filter(s => s.passes).map(s => s.id);
+  const filterRe = taskFilter ? new RegExp(taskFilter, 'i') : null;
+  const eligible = stories.filter(s =>
+    !s.passes &&
+    s.dependencies.every(dep => doneIds.includes(dep)) &&
+    (!phaseFilter || s.phase === phaseFilter) &&
+    (!filterRe || filterRe.test(s.id) || filterRe.test(s.title))
+  );
+
+  if (eligible.length === 0) {
+    console.log(chalk.yellow('\n  No eligible stories found.'));
+    return;
+  }
+
+  console.log(chalk.bold('\n  Eligible stories:\n'));
+  for (let i = 0; i < Math.min(eligible.length, maxIterations); i++) {
+    const s = eligible[i];
+    const phaseLabel = s.phase ? chalk.dim(` (${s.phase})`) : '';
+    const effort = s.effort ? chalk.dim(` [${s.effort}]`) : '';
+
+    // Show planning info if task file exists
+    const existing = loadTaskFile(s.id, cwd);
+    const planInfo = existing
+      ? chalk.dim(` — ${existing.complexity}, ~${formatDuration(existing.estimated_time_seconds)}, model: ${existing.recommended_model || 'sonnet'}`)
+      : '';
+
+    console.log(`  ${chalk.cyan(`${i + 1}.`)} ${chalk.bold(s.id)}: ${s.title}${phaseLabel}${effort}${planInfo}`);
+  }
+
+  const config = loadConfig(cwd);
+  console.log(chalk.bold('\n  Quality gates:'));
+  for (const gate of config.quality_gates) {
+    if (config.skip_gates.includes(gate)) {
+      console.log(chalk.dim(`    ${gate} (skip)`));
+    } else {
+      console.log(`    ${chalk.green('>')} ${gate}`);
+    }
+  }
+
+  console.log(chalk.dim('\n  Run without --dry-run to execute.\n'));
+}
+
+function printHeader(maxIter, phase, total, done, noPlan = false, cwd = process.cwd(), taskFilter = null) {
+  const config = loadConfig(cwd);
+  const skipGates = config.skip_gates || [];
+
+  console.log('');
+  console.log(chalk.bold('PWN Batch Runner') + chalk.dim(` (v${RUNNER_VERSION})`));
+  console.log(chalk.dim('─'.repeat(40)));
+  console.log(`  Max iterations: ${chalk.cyan(maxIter)}`);
+  console.log(`  Progress:       ${chalk.green(done)}/${total} done`);
+  console.log(`  Planning:       ${noPlan ? chalk.yellow('disabled') : chalk.green('enabled')}`);
+  if (phase) console.log(`  Phase filter:   ${chalk.blue(phase)}`);
+  if (taskFilter) console.log(`  Task filter:    ${chalk.blue(taskFilter)}`);
+  if (skipGates.length > 0) {
+    console.log(`  ${chalk.yellow('⚠️  Skipping gates (no tooling):')} ${skipGates.join(', ')}`);
+  }
+  console.log(chalk.dim('─'.repeat(40)));
+}
+
+function printSummary(cwd, iterations, completed, startTime) {
+  const stories = parsePrdTasks(cwd);
+  const total = stories.length;
+  const done = stories.filter(s => s.passes).length;
+  const remaining = total - done;
+  const elapsed = Math.round((Date.now() - startTime) / 1000);
+
+  // Cleanup: delete completed task files, keep failed
+  let cleaned = 0;
+  let failedKept = 0;
+  const tasksDir = getTasksDir(cwd);
+  if (existsSync(tasksDir)) {
+    const files = readdirSync(tasksDir).filter(f => f.endsWith('.json'));
+    for (const file of files) {
+      try {
+        const data = JSON.parse(readFileSync(join(tasksDir, file), 'utf8'));
+        if (data.status === 'completed') {
+          unlinkSync(join(tasksDir, file));
+          cleaned++;
+        } else if (data.status === 'failed') {
+          failedKept++;
+        }
+      } catch {}
+    }
+  }
+
+  console.log('');
+  console.log(chalk.bold('Batch Runner Complete'));
+  console.log(chalk.dim('─'.repeat(40)));
+  console.log(`  Iterations:       ${iterations}`);
+  console.log(`  Completed:        ${chalk.green(completed)}`);
+  console.log(`  Total progress:   ${chalk.green(done)}/${total} done, ${chalk.yellow(remaining)} remaining`);
+  console.log(`  Duration:         ${formatDuration(elapsed)}`);
+  console.log(`  Logs:             logs/`);
+  if (cleaned > 0 || failedKept > 0) {
+    console.log(`  Cleanup:          ${chalk.green(`${cleaned} completed`)} removed, ${failedKept > 0 ? chalk.red(`${failedKept} failed`) : '0 failed'} kept for review`);
+  }
+  console.log(chalk.dim('─'.repeat(40)));
+  console.log('');
+}
+
+// --- Utilities ---
+
+function formatBytes(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+function formatDuration(seconds) {
+  const m = Math.floor(seconds / 60);
+  const s = seconds % 60;
+  return m > 0 ? `${m}m ${String(s).padStart(2, '0')}s` : `${s}s`;
+}
+
+function timestamp() {
+  return new Date().toISOString().replace(/[:.]/g, '').slice(0, 15);
+}
+
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+function appendProgress(progressPath, storyId, notes) {
+  const line = `\n=== ${storyId} completed at ${new Date().toISOString()} ===\n- ${notes}\n`;
+  appendFileSync(progressPath, line);
+}