@fermindi/pwn-cli 0.9.6 → 0.9.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fermindi/pwn-cli",
-  "version": "0.9.6",
+  "version": "0.9.7",
   "description": "Professional AI Workspace - Inject structured memory and automation into any project for AI-powered development",
   "type": "module",
   "bin": {

package/src/services/batch-runner.js

@@ -24,17 +24,23 @@ import {
   runQualityGate,
   loadConfig,
   commitTask,
+  commitPrdUpdate,
   updateBatchState,
   clearBatchState,
-  getCurrentBranch,
-  createTaskBranch,
-  checkoutBranch,
-  createBatchBranch,
-  mergeBranch
+  mergeBranch,
+  ensureMetadataIgnored,
+  createBatchRef,
+  createBatchWorktree,
+  createTaskWorktree,
+  addExistingBranchWorktree,
+  removeWorktree,
+  cleanupAllWorktrees,
+  prepareWorktree,
+  unprepareWorktree
 } from './batch-service.js';
 
 // --- Constants ---
-const RUNNER_VERSION = '2.3';
+const RUNNER_VERSION = '3.0';
 const DEFAULT_TIMEOUT_MS = 900_000;  // 15 minutes fallback
 const MIN_TIMEOUT_MS = 300_000;      // 5 minutes minimum (claude init ~30-40s + real work)
 
@@ -114,8 +120,8 @@ async function waitForRateLimit(waitSeconds, attempt) {
 
 // --- Planning Phase ---
 
-function buildPlanPrompt(task, cwd, replanContext = null) {
-  const prdPath = join(cwd, '.ai', 'tasks', 'prd.json');
+function buildPlanPrompt(task, batchWorktreePath, replanContext = null) {
+  const prdPath = join(batchWorktreePath, '.ai', 'tasks', 'prd.json');
   const prd = JSON.parse(readFileSync(prdPath, 'utf8'));
   const story = prd.stories.find(s => s.id === task.id);
   if (!story) return '';
@@ -158,8 +164,8 @@ Recommend a model for execution:
 - "opus": high complexity (new module, multi-file refactor, architecture)`;
 }
 
-async function planTask(task, cwd, replanContext = null) {
-  const prompt = buildPlanPrompt(task, cwd, replanContext);
+async function planTask(task, batchWorktreePath, replanContext = null) {
+  const prompt = buildPlanPrompt(task, batchWorktreePath, replanContext);
   if (!prompt) return null;
 
   const env = { ...process.env };
@@ -174,7 +180,7 @@ async function planTask(task, cwd, replanContext = null) {
       '-c',
       `claude --model opus --print -p "$(cat)"`,
     ], {
-      cwd,
+      cwd: batchWorktreePath,
       stdio: ['pipe', 'pipe', 'pipe'],
       env,
     });
@@ -235,10 +241,11 @@ function computeTimeout(estimatedSeconds) {
  * 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 mainCwd = cwd;
+  const prdPath = join(mainCwd, '.ai', 'tasks', 'prd.json');
+  const promptPath = join(mainCwd, '.ai', 'batch', 'prompt.md');
+  const logDir = join(mainCwd, 'logs');
+  const progressPath = join(mainCwd, '.ai', 'batch', 'progress.txt');
   const noPlan = options.noPlan || false;
   const rateLimitWait = options.rateLimitWait || DEFAULT_RATE_LIMIT_WAIT;
 
@@ -253,41 +260,68 @@ export async function runBatch(options = {}, cwd = process.cwd()) {
   }
 
   mkdirSync(logDir, { recursive: true });
-  mkdirSync(getTasksDir(cwd), { recursive: true });
+  mkdirSync(getTasksDir(mainCwd), { recursive: true });
 
-  const stories = parsePrdTasks(cwd);
+  const stories = parsePrdTasks(mainCwd);
   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);
+  // Count ALL stories matching the filter (not just currently eligible).
+  // Dependencies resolve dynamically as tasks complete within the batch,
+  // so we can't limit iterations by initial eligibility.
   const filterRe = taskFilter ? new RegExp(taskFilter, 'i') : null;
-  const eligibleCount = stories.filter(s =>
+  const matchingCount = 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;
+  const maxIterations = options.maxIterations || matchingCount;
 
   // --- Dry run ---
   if (options.dryRun) {
-    return dryRunPreview(cwd, phaseFilter, maxIterations, taskFilter);
+    return dryRunPreview(mainCwd, phaseFilter, maxIterations, taskFilter);
   }
 
   // --- Print header ---
-  printHeader(maxIterations, phaseFilter, totalStories, doneAtStart, noPlan, cwd, taskFilter);
+  printHeader(maxIterations, phaseFilter, totalStories, doneAtStart, noPlan, mainCwd, taskFilter);
+
+  // --- Ensure metadata is gitignored ---
+  ensureMetadataIgnored(mainCwd);
+  // Auto-commit .gitignore if ensureMetadataIgnored modified it
+  try {
+    const { stdout: gitignoreDiff } = await execAsync('git diff --name-only -- .gitignore', { cwd: mainCwd });
+    if (gitignoreDiff.trim()) {
+      await execAsync('git add .gitignore && git commit -m "chore: gitignore batch runner metadata"', { cwd: mainCwd });
+    }
+  } catch {}
 
-  // NO custom SIGINT handler — Ctrl+C uses default Node.js behavior (kills process group)
+  // --- Crash recovery: clean up any leftover worktrees from previous runs ---
+  await cleanupAllWorktrees(mainCwd);
 
-  // --- Save original branch for isolation ---
-  const originalBranch = await getCurrentBranch(cwd);
+  // --- Create batch ref + worktree ---
+  const batchBranch = await createBatchRef(mainCwd);
+  const batchWorktreePath = await createBatchWorktree(batchBranch, mainCwd);
+  prepareWorktree(batchWorktreePath, mainCwd);
+  const activeWorktrees = new Set([batchWorktreePath]);
 
-  // --- Create batch branch ---
-  const batchBranch = await createBatchBranch(cwd);
   console.log(chalk.blue(`  Batch branch: ${chalk.bold(batchBranch)}`));
+  console.log(chalk.dim(`  Batch worktree: ${batchWorktreePath}`));
+
+  // --- Signal handler: set flag + schedule cleanup, let main loop bail ---
+  let sigintReceived = false;
+  const signalHandler = (signal) => {
+    if (sigintReceived) {
+      // Second Ctrl+C — force exit immediately
+      process.exit(1);
+    }
+    sigintReceived = true;
+    console.log(chalk.yellow(`\n  Received ${signal}. Stopping after current step...`));
+    // Deferred cleanup — main loop will bail, then cleanup runs in finally block
+  };
+  process.on('SIGINT', signalHandler);
+  process.on('SIGTERM', signalHandler);
 
   // --- Main loop ---
   let iteration = 0;
@@ -304,32 +338,105 @@ export async function runBatch(options = {}, cwd = process.cwd()) {
     status: 'running',
     completed: [],
     max_tasks: maxIterations
-  }, cwd);
+  }, mainCwd);
 
-  while (iteration < maxIterations) {
+  while (iteration < maxIterations && !sigintReceived) {
     iteration++;
 
-    const task = selectNextTask(cwd, { phase: phaseFilter, filter: taskFilter });
+    const task = selectNextTask(batchWorktreePath, { phase: phaseFilter, filter: taskFilter });
     if (!task) {
       console.log(chalk.green('\nAll eligible stories completed!'));
       break;
     }
 
-    const currentDone = parsePrdTasks(cwd).filter(s => s.passes).length;
+    const currentDone = parsePrdTasks(batchWorktreePath).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}`);
 
+    // --- Pre-validation: check existing feat branch BEFORE planning ---
+    let storyDone = false;
+    const taskBranchName = `feat/${task.id}`;
+    let branchExists = false;
+    try {
+      await execAsync(`git rev-parse --verify ${taskBranchName}`, { cwd: mainCwd });
+      branchExists = true;
+    } catch {}
+
+    if (branchExists) {
+      let prevalWorktreePath = null;
+      try {
+        const prevalResult = await addExistingBranchWorktree(task.id, mainCwd);
+        prevalWorktreePath = prevalResult.worktreePath;
+        prepareWorktree(prevalWorktreePath, mainCwd);
+
+        // Count commits on feat branch that aren't on the current HEAD
+        // (using HEAD, not batchBranch, because batchBranch is recreated each run)
+        const { stdout: logCount } = await execAsync(`git rev-list --count HEAD..${taskBranchName}`, { cwd: mainCwd });
+        const commits = parseInt(logCount.trim(), 10);
+
+        if (commits > 0) {
+          console.log(chalk.blue(`  Pre-validation: found ${commits} commit(s) on ${taskBranchName}, running quality gates...`));
+          const preGates = await runGatesWithStatus(prevalWorktreePath, mainCwd);
+
+          if (preGates.success) {
+            console.log(chalk.green(`  Pre-validation PASSED — skipping execution`));
+            markStoryDone(task.id, prevalWorktreePath);
+            await commitPrdUpdate(task.id, prevalWorktreePath);
+            appendProgress(progressPath, task.id, 'Pre-validation: existing code passed quality gates');
+
+            storyDone = true;
+            storiesCompleted++;
+            noProgressCount = 0;
+
+            updateBatchState({
+              completed: [task.id],
+              current_task: null,
+              last_completed_at: new Date().toISOString()
+            }, mainCwd);
+
+            // Merge into batch worktree
+            try {
+              unprepareWorktree(batchWorktreePath);
+              await mergeBranch(taskBranchName, batchWorktreePath);
+              prepareWorktree(batchWorktreePath, mainCwd);
+              mergedCount++;
+              mergedBranches.push(taskBranchName);
+              console.log(chalk.green(`  Merged ${taskBranchName} → ${batchBranch}`));
+            } catch (err) {
+              prepareWorktree(batchWorktreePath, mainCwd);
+              console.log(chalk.red(`  Merge failed: ${err.message}`));
+              console.log(chalk.yellow(`  Branch ${taskBranchName} available for manual merge`));
+              unmergedBranches.push(taskBranchName);
+            }
+          } else {
+            console.log(chalk.yellow(`  Pre-validation FAILED — will re-execute`));
+          }
+        }
+      } catch (err) {
+        console.log(chalk.dim(`  Pre-validation worktree failed: ${err.message}`));
+      }
+
+      // Always clean up pre-validation worktree
+      if (prevalWorktreePath) {
+        try { await removeWorktree(prevalWorktreePath, mainCwd, { force: true }); } catch {}
+      }
+    }
+
+    if (storyDone) {
+      branchesCreated.push(taskBranchName);
+      continue;
+    }
+
     // --- Phase 1: Planning (skip if already planned) ---
     let taskTimeoutMs = DEFAULT_TIMEOUT_MS;
     let taskFile = null;
 
     if (!noPlan) {
-      const existing = loadTaskFile(task.id, cwd);
+      const existing = loadTaskFile(task.id, mainCwd);
 
       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'})`));
@@ -337,7 +444,7 @@ export async function runBatch(options = {}, cwd = process.cwd()) {
         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);
+        const planResult = await planTask(task, batchWorktreePath);
 
         if (planResult) {
           const complexity = planResult.complexity || 'medium';
@@ -361,13 +468,12 @@ export async function runBatch(options = {}, cwd = process.cwd()) {
             completed_at: null,
             failure_reason: null
           };
-          saveTaskFile(taskFile, cwd);
+          saveTaskFile(taskFile, mainCwd);
 
           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,
@@ -383,7 +489,7 @@ export async function runBatch(options = {}, cwd = process.cwd()) {
             completed_at: null,
             failure_reason: null
           };
-          saveTaskFile(taskFile, cwd);
+          saveTaskFile(taskFile, mainCwd);
           taskTimeoutMs = DEFAULT_TIMEOUT_MS;
 
           planSpinner.warn(chalk.yellow(`Planning failed, using default timeout (${formatDuration(fallbackSeconds)})`));
@@ -391,98 +497,28 @@ export async function runBatch(options = {}, cwd = process.cwd()) {
       }
     }
 
-    // --- Pre-validation: check existing feat branch before reset ---
-    let storyDone = false;
-    const taskBranchName = `feat/${task.id}`;
-    let branchExists = false;
-    try {
-      await execAsync(`git rev-parse --verify ${taskBranchName}`, { cwd });
-      branchExists = true;
-    } catch {}
-
-    if (branchExists) {
-      try {
-        // Checkout WITHOUT reset to inspect existing work
-        await checkoutBranch(taskBranchName, cwd, { stash: true });
-        const { stdout: logCount } = await execAsync(`git rev-list --count ${batchBranch}..HEAD`, { cwd });
-        const commits = parseInt(logCount.trim(), 10);
-
-        if (commits > 0) {
-          console.log(chalk.blue(`  Pre-validation: found ${commits} commit(s) on ${taskBranchName}, running quality gates...`));
-          const preGates = await runGatesWithStatus(cwd);
-
-          if (preGates.success) {
-            console.log(chalk.green(`  Pre-validation PASSED — skipping execution`));
-            markStoryDone(task.id, cwd);
-            appendProgress(progressPath, task.id, 'Pre-validation: existing code passed quality gates');
-
-            storyDone = true;
-            storiesCompleted++;
-            noProgressCount = 0;
-
-            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);
-
-            // Merge into batch branch
-            try {
-              await checkoutBranch(batchBranch, cwd, { stash: true });
-              await mergeBranch(taskBranchName, cwd);
-              mergedCount++;
-              mergedBranches.push(taskBranchName);
-              console.log(chalk.green(`  Merged ${taskBranchName} → ${batchBranch}`));
-            } catch (err) {
-              console.log(chalk.red(`  Merge failed: ${err.message}`));
-              console.log(chalk.yellow(`  Branch ${taskBranchName} available for manual merge`));
-              unmergedBranches.push(taskBranchName);
-            }
-          } else {
-            console.log(chalk.yellow(`  Pre-validation FAILED — will re-execute`));
-            // Return to batch branch so createTaskBranch resets properly
-            await checkoutBranch(batchBranch, cwd, { force: true, stash: true });
-          }
-        } else {
-          // No commits — return to batch branch for normal flow
-          await checkoutBranch(batchBranch, cwd, { force: true, stash: true });
-        }
-      } catch {
-        // Checkout failed — proceed normally
-        try { await checkoutBranch(batchBranch, cwd, { force: true, stash: true }); } catch {}
-      }
-    }
-
-    if (storyDone) {
-      branchesCreated.push(taskBranchName);
-      try {
-        await checkoutBranch(batchBranch, cwd, { force: true, stash: true });
-        console.log(chalk.dim(`  Returned to branch: ${batchBranch}`));
-      } catch {}
-      continue;
-    }
-
-    // --- Branch isolation: create/checkout task branch (resets existing) ---
+    // --- Create task worktree ---
     let taskBranch = null;
+    let taskWorktreePath = null;
     try {
-      taskBranch = await createTaskBranch(task.id, cwd);
+      const result = await createTaskWorktree(task.id, batchBranch, mainCwd);
+      taskBranch = result.branch;
+      taskWorktreePath = result.worktreePath;
+      prepareWorktree(taskWorktreePath, mainCwd);
+      activeWorktrees.add(taskWorktreePath);
       branchesCreated.push(taskBranch);
       console.log(chalk.blue(`  Branch: ${chalk.bold(taskBranch)}`));
+      console.log(chalk.dim(`  Worktree: ${taskWorktreePath}`));
 
-      // Track branch in task file
       if (taskFile) {
         taskFile.branch = taskBranch;
-        saveTaskFile(taskFile, cwd);
+        saveTaskFile(taskFile, mainCwd);
       }
     } catch (err) {
-      console.log(chalk.red(`  Failed to create branch feat/${task.id}: ${err.message}`));
-      console.log(chalk.yellow('  Continuing on current branch...'));
+      console.log(chalk.red(`  Failed to create worktree for feat/${task.id}: ${err.message}`));
+      console.log(chalk.yellow('  Skipping task...'));
+      noProgressCount++;
+      continue;
     }
 
     // --- Phase 2: Execution ---
@@ -498,7 +534,7 @@ export async function runBatch(options = {}, cwd = process.cwd()) {
         console.log(chalk.yellow(`  Retry ${retry}/${MAX_RETRIES}`));
       }
 
-      const prompt = buildPrompt(task.id, cwd, prdPath, promptPath, errorContext);
+      const prompt = buildPrompt(task.id, batchWorktreePath, mainCwd, errorContext);
       if (!prompt) {
         console.log(chalk.red(`  Cannot build prompt for ${task.id} — skipping`));
         break;
@@ -507,22 +543,17 @@ export async function runBatch(options = {}, cwd = process.cwd()) {
 
       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);
+      const result = await spawnClaude(prompt, task, iteration, maxIterations, currentDone, totalStories, phaseFilter, logFile, taskWorktreePath, 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}`));
-        if (taskBranch) {
-          try { await checkoutBranch(batchBranch, cwd, { force: true, stash: true }); } catch {}
-        }
-        clearBatchState(cwd);
-        printSummary(cwd, iteration, storiesCompleted, batchStart, branchesCreated, batchBranch, originalBranch, mergedCount, unmergedBranches);
+      // Killed by signal or Ctrl+C — bail immediately
+      if (result.signal || sigintReceived) {
+        if (result.signal) console.log(chalk.yellow(`  Killed by ${result.signal}`));
+        clearBatchState(mainCwd);
         return;
       }
 
       // Timeout
       if (result.timedOut) {
-        // Timeout can also be caused by rate limit — check output
         if (isRateLimitError(result.output)) {
           rateLimitAttempts++;
           await waitForRateLimit(rateLimitWait, rateLimitAttempts);
@@ -532,17 +563,14 @@ export async function runBatch(options = {}, cwd = process.cwd()) {
         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;
@@ -552,10 +580,10 @@ export async function runBatch(options = {}, cwd = process.cwd()) {
           taskFile.estimated_time_seconds = newEstimate;
           taskFile.timeout_seconds = newTimeout;
           taskFile.complexity = newComplexity;
-          taskFile.recommended_model = 'opus'; // upgrade model on timeout
+          taskFile.recommended_model = 'opus';
           taskFile.replanned_at = new Date().toISOString();
           taskFile.replan_reason = `timeout after ${prevTimeout}s (${prevComplexity} → ${newComplexity})`;
-          saveTaskFile(taskFile, cwd);
+          saveTaskFile(taskFile, mainCwd);
 
           console.log(chalk.blue(
             `  Escalated: ${prevComplexity} → ${newComplexity}, timeout ${formatDuration(newTimeout)}, model: opus`
@@ -567,82 +595,82 @@ export async function runBatch(options = {}, cwd = process.cwd()) {
         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.
+      // Non-zero exit
       if (result.exitCode !== 0) {
         if (isRateLimitError(result.output)) {
           rateLimitAttempts++;
           await waitForRateLimit(rateLimitWait, rateLimitAttempts);
-          continue; // no retry increment — wait and try again
+          continue;
         }
         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);
+          saveTaskFile(taskFile, mainCwd);
         }
 
         retry++;
         continue;
       }
 
-      // Quality gates
-      const gatesResult = await runGatesWithStatus(cwd);
+      // Bail if Ctrl+C received during execution
+      if (sigintReceived) break;
+
+      // Quality gates — run in task worktree, config from mainCwd
+      const gatesResult = await runGatesWithStatus(taskWorktreePath, mainCwd);
 
       if (gatesResult.success) {
         console.log(chalk.green(`  Quality gates PASSED`));
-        markStoryDone(task.id, cwd);
+        markStoryDone(task.id, taskWorktreePath);
         appendProgress(progressPath, task.id, 'All quality gates passed');
 
-        const config = loadConfig(cwd);
+        const config = loadConfig(mainCwd);
         if (config.auto_commit) {
-          await commitTask(task, {}, cwd);
+          await commitTask(task, {}, taskWorktreePath);
+        } else {
+          await commitPrdUpdate(task.id, taskWorktreePath);
         }
 
         storyDone = true;
         storiesCompleted++;
         noProgressCount = 0;
 
-        // Update task file status
         if (taskFile) {
           taskFile.status = 'completed';
           taskFile.completed_at = new Date().toISOString();
-          saveTaskFile(taskFile, cwd);
+          saveTaskFile(taskFile, mainCwd);
         }
 
         updateBatchState({
           completed: [task.id],
           current_task: null,
           last_completed_at: new Date().toISOString()
-        }, cwd);
-
-        // Merge successful task branch into batch branch
-        if (taskBranch) {
-          try {
-            await checkoutBranch(batchBranch, cwd, { stash: true });
-            await mergeBranch(taskBranch, cwd);
-            mergedCount++;
-            mergedBranches.push(taskBranch);
-            console.log(chalk.green(`  Merged ${taskBranch} → ${batchBranch}`));
-          } catch (err) {
-            console.log(chalk.red(`  Merge failed: ${err.message}`));
-            console.log(chalk.yellow(`  Branch ${taskBranch} available for manual merge`));
-            unmergedBranches.push(taskBranch);
-          }
+        }, mainCwd);
+
+        // Merge into batch worktree
+        try {
+          unprepareWorktree(batchWorktreePath);
+          await mergeBranch(taskBranch, batchWorktreePath);
+          prepareWorktree(batchWorktreePath, mainCwd);
+          mergedCount++;
+          mergedBranches.push(taskBranch);
+          console.log(chalk.green(`  Merged ${taskBranch} → ${batchBranch}`));
+        } catch (err) {
+          prepareWorktree(batchWorktreePath, mainCwd);
+          console.log(chalk.red(`  Merge failed: ${err.message}`));
+          console.log(chalk.yellow(`  Branch ${taskBranch} available for manual merge`));
+          unmergedBranches.push(taskBranch);
         }
       } 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);
+          saveTaskFile(taskFile, mainCwd);
         }
 
         retry++;
@@ -654,28 +682,23 @@ export async function runBatch(options = {}, cwd = process.cwd()) {
       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);
+        saveTaskFile(taskFile, mainCwd);
       }
 
       noProgressCount++;
+      unmergedBranches.push(taskBranch);
     }
 
-    // --- Return to batch branch ---
-    if (taskBranch) {
-      try {
-        await checkoutBranch(batchBranch, cwd, { force: true, stash: true });
-        console.log(chalk.dim(`  Returned to branch: ${batchBranch}`));
-      } catch (err) {
-        console.log(chalk.red(`  Warning: failed to return to ${batchBranch}: ${err.message}`));
-      }
-      if (!storyDone) {
-        unmergedBranches.push(taskBranch);
-      }
+    // --- Remove task worktree ---
+    try {
+      await removeWorktree(taskWorktreePath, mainCwd, { force: !storyDone });
+      activeWorktrees.delete(taskWorktreePath);
+    } catch (err) {
+      console.log(chalk.dim(`  Warning: failed to remove worktree: ${err.message}`));
     }
 
     if (noProgressCount >= MAX_NO_PROGRESS) {
@@ -684,8 +707,36 @@ export async function runBatch(options = {}, cwd = process.cwd()) {
     }
   }
 
-  clearBatchState(cwd);
-  printSummary(cwd, iteration, storiesCompleted, batchStart, branchesCreated, batchBranch, originalBranch, mergedCount, unmergedBranches);
+  if (sigintReceived) {
+    console.log(chalk.yellow('\n  Interrupted. Cleaning up...'));
+  }
+
+  // --- Summary (before removing batch worktree, so prd.json is readable) ---
+  printSummary(mainCwd, batchWorktreePath, iteration, storiesCompleted, batchStart, branchesCreated, batchBranch, mergedCount, unmergedBranches);
+
+  // --- Merge batch branch into main repo ---
+  if (mergedCount > 0 && !sigintReceived) {
+    try {
+      await mergeBranch(batchBranch, mainCwd);
+      console.log(chalk.green(`  Merged ${batchBranch} into main repo`));
+    } catch (err) {
+      console.log(chalk.red(`  Failed to merge ${batchBranch} into main repo: ${err.message}`));
+      console.log(chalk.yellow(`  Run manually: git merge ${batchBranch}`));
+    }
+  }
+
+  // --- Cleanup all worktrees ---
+  for (const wt of activeWorktrees) {
+    try { await removeWorktree(wt, mainCwd, { force: true }); } catch {}
+  }
+  await cleanupAllWorktrees(mainCwd);
+  clearBatchState(mainCwd);
+
+  // Cleanup signal handlers
+  process.removeListener('SIGINT', signalHandler);
+  process.removeListener('SIGTERM', signalHandler);
+
+  // Main repo never left its original branch — nothing to restore
 }
 
 /**
@@ -791,9 +842,11 @@ function spawnClaude(prompt, task, iteration, maxIter, done, total, phase, logFi
 
 /**
  * Run quality gates with real-time PASS/FAIL display.
+ * @param {string} taskCwd - Directory where gates run (task worktree)
+ * @param {string} mainCwd - Main repo directory for config (defaults to taskCwd for backwards compat)
  */
-async function runGatesWithStatus(cwd) {
-  const config = loadConfig(cwd);
+async function runGatesWithStatus(taskCwd, mainCwd = taskCwd) {
+  const config = loadConfig(mainCwd);
   const gates = config.quality_gates || [];
   const skipGates = config.skip_gates || [];
   let allPassed = true;
@@ -806,7 +859,7 @@ async function runGatesWithStatus(cwd) {
     }
 
     const spinner = ora({ text: `Running ${gate}...`, indent: 2 }).start();
-    const result = await runQualityGate(gate, cwd);
+    const result = await runQualityGate(gate, taskCwd, { configCwd: mainCwd });
 
     if (result.success || result.skipped) {
       spinner.succeed(chalk.green(`${gate}: PASS`));
@@ -822,8 +875,15 @@ async function runGatesWithStatus(cwd) {
 
 /**
  * Build the prompt from template, substituting placeholders.
+ * @param {string} storyId - Story ID
+ * @param {string} batchWorktreePath - Batch worktree (for prd.json, tracked file)
+ * @param {string} mainCwd - Main repo (for prompt.md, gitignored file)
+ * @param {string} extraContext - Error context from previous attempt
  */
-function buildPrompt(storyId, cwd, prdPath, promptPath, extraContext) {
+function buildPrompt(storyId, batchWorktreePath, mainCwd, extraContext) {
+  const prdPath = join(batchWorktreePath, '.ai', 'tasks', 'prd.json');
+  const promptPath = join(mainCwd, '.ai', 'batch', 'prompt.md');
+
   const prd = JSON.parse(readFileSync(prdPath, 'utf8'));
   const story = prd.stories.find(s => s.id === storyId);
   if (!story) {
@@ -934,17 +994,20 @@ function printHeader(maxIter, phase, total, done, noPlan = false, cwd = process.
   console.log(chalk.dim('─'.repeat(40)));
 }
 
-function printSummary(cwd, iterations, completed, startTime, branchesCreated = [], batchBranch = null, originalBranch = null, mergedCount = 0, unmergedBranches = []) {
-  const stories = parsePrdTasks(cwd);
+function printSummary(mainCwd, batchWorktreePath, iterations, completed, startTime, branchesCreated = [], batchBranch = null, mergedCount = 0, unmergedBranches = []) {
+  // Read prd.json from batch worktree (still alive at this point)
+  const stories = existsSync(join(batchWorktreePath, '.ai', 'tasks', 'prd.json'))
+    ? parsePrdTasks(batchWorktreePath)
+    : parsePrdTasks(mainCwd);
   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
+  // Cleanup: delete completed task files, keep failed (from mainCwd)
   let cleaned = 0;
   let failedKept = 0;
-  const tasksDir = getTasksDir(cwd);
+  const tasksDir = getTasksDir(mainCwd);
   if (existsSync(tasksDir)) {
     const files = readdirSync(tasksDir).filter(f => f.endsWith('.json'));
     for (const file of files) {
@@ -983,9 +1046,7 @@ function printSummary(cwd, iterations, completed, startTime, branchesCreated = [
     const unique = [...new Set(branchesCreated)];
     console.log(`  Branches:         ${unique.map(b => chalk.cyan(b)).join(', ')}`);
   }
-  if (originalBranch) {
-    console.log(`  Original branch:  ${chalk.green(originalBranch)} (intact)`);
-  }
+  console.log(`  Main repo:        ${chalk.green('intact (never changed branch)')}`);
   console.log(chalk.dim('─'.repeat(40)));
   console.log('');
 }

package/src/services/batch-service.js

@@ -5,14 +5,18 @@
  * checkpointing, and signal handling.
  */
 
-import { existsSync, readFileSync, writeFileSync, readdirSync } from 'fs';
+import { existsSync, readFileSync, writeFileSync, readdirSync, appendFileSync, symlinkSync, unlinkSync, lstatSync } from 'fs';
 import { join } from 'path';
+import os from 'os';
 import { exec } from 'child_process';
 import { promisify } from 'util';
 import { getState, updateState, hasWorkspace } from '../core/state.js';
 
 const execAsync = promisify(exec);
 
+// --- Metadata patterns that should never be tracked by git ---
+const METADATA_IGNORE_ENTRIES = ['.ai/batch/', '.ai/state.json', 'logs/'];
+
 // --- Git Helpers ---
 
 /**
@@ -25,6 +29,31 @@ export async function getCurrentBranch(cwd = process.cwd()) {
   return stdout.trim();
 }
 
+/**
+ * Ensure metadata paths are in .gitignore so they never block checkout or get committed.
+ * Idempotent — safe to call multiple times.
+ * @param {string} cwd - Working directory
+ */
+export function ensureMetadataIgnored(cwd = process.cwd()) {
+  const gitignorePath = join(cwd, '.gitignore');
+  let content = '';
+  if (existsSync(gitignorePath)) {
+    content = readFileSync(gitignorePath, 'utf8');
+  }
+
+  const missing = METADATA_IGNORE_ENTRIES.filter(entry => {
+    // Check if entry already exists as a line (ignoring trailing whitespace)
+    return !content.split('\n').some(line => line.trim() === entry);
+  });
+
+  if (missing.length > 0) {
+    const suffix = (content && !content.endsWith('\n') ? '\n' : '')
+      + '\n# PWN batch runner metadata (auto-added)\n'
+      + missing.join('\n') + '\n';
+    appendFileSync(gitignorePath, suffix);
+  }
+}
+
 /**
  * Create and checkout a task branch from the current HEAD
  * If branch already exists, just checkout.
@@ -47,47 +76,218 @@ export async function createTaskBranch(taskId, cwd = process.cwd()) {
     // so we don't carry stale/dirty state from previous attempt
     const { stdout } = await execAsync('git rev-parse HEAD', { cwd });
     const baseRef = stdout.trim();
-    await checkoutBranch(branch, cwd, { stash: true });
+    await checkoutBranch(branch, cwd);
     await execAsync(`git reset --hard ${baseRef}`, { cwd });
   } else {
-    // Stash + drop to unblock checkout -b (metadata files re-created by runner)
-    try { await execAsync('git stash --include-untracked', { cwd }); } catch {}
     await execAsync(`git checkout -b ${branch}`, { cwd });
-    try { await execAsync('git stash drop', { cwd }); } catch {}
   }
   return branch;
 }
 
 /**
  * Checkout an existing branch.
- * When stash=true, stashes untracked/dirty files before checkout and
- * restores them after — prevents .ai/batch/tasks/*.json from blocking.
+ * With metadata gitignored, no stash is needed — checkouts are clean.
  * @param {string} branch - Branch name
  * @param {string} cwd - Working directory
- * @param {{ force?: boolean, stash?: boolean }} options
+ * @param {{ force?: boolean }} options
  */
-export async function checkoutBranch(branch, cwd = process.cwd(), { force = false, stash = false } = {}) {
-  if (stash) {
-    // Stash only to unblock checkout, then drop — these are runner
-    // metadata files (.ai/batch/tasks/*.json) that get re-created by
-    // saveTaskFile, so restoring them causes merge conflicts for no gain.
-    try { await execAsync('git stash --include-untracked', { cwd }); } catch {}
-  }
-
+export async function checkoutBranch(branch, cwd = process.cwd(), { force = false } = {}) {
   const flag = force ? ' --force' : '';
   await execAsync(`git checkout${flag} ${branch}`, { cwd });
+}
+
+// --- Worktree Helpers ---
+
+/**
+ * Create a batch ref (branch) without checkout.
+ * Fails fast if the working tree has dirty tracked files.
+ * @param {string} cwd - Working directory
+ * @returns {Promise<string>} Branch name (batch/{timestamp})
+ */
+export async function createBatchRef(cwd = process.cwd()) {
+  // Check for dirty tracked files (excluding batch runner metadata)
+  try {
+    const { stdout: dirty } = await execAsync('git diff --name-only HEAD', { cwd });
+    const { stdout: staged } = await execAsync('git diff --cached --name-only', { cwd });
+    const allDirty = (dirty + staged).trim()
+      .split('\n')
+      .filter(f => f && !METADATA_IGNORE_ENTRIES.some(m => f.startsWith(m)))
+      .join('\n');
+    if (allDirty) {
+      throw new Error(
+        `Working tree has uncommitted changes:\n${allDirty}\n\n` +
+        'Commit or stash your changes before starting a batch run.'
+      );
+    }
+  } catch (err) {
+    if (err.message.includes('uncommitted changes')) throw err;
+  }
+
+  const ts = new Date().toISOString().replace(/[:.]/g, '').slice(0, 15);
+  const branch = `batch/${ts}`;
+  await execAsync(`git branch ${branch}`, { cwd });
+  return branch;
+}
+
+/**
+ * Add a git worktree.
+ * @param {string} worktreePath - Path for the new worktree
+ * @param {string} branch - Branch to checkout in the worktree
+ * @param {string} cwd - Main repo directory
+ * @param {{ createBranch?: boolean, baseBranch?: string }} opts
+ */
+export async function addWorktree(worktreePath, branch, cwd, { createBranch = false, baseBranch = null } = {}) {
+  if (createBranch) {
+    await execAsync(`git worktree add "${worktreePath}" -b ${branch} ${baseBranch || 'HEAD'}`, { cwd });
+  } else {
+    await execAsync(`git worktree add "${worktreePath}" ${branch}`, { cwd });
+  }
+}
+
+/**
+ * Remove a git worktree.
+ * @param {string} worktreePath - Path of the worktree to remove
+ * @param {string} cwd - Main repo directory
+ * @param {{ force?: boolean }} opts
+ */
+export async function removeWorktree(worktreePath, cwd, { force = false } = {}) {
+  try {
+    await execAsync(`git worktree remove "${worktreePath}"${force ? ' --force' : ''}`, { cwd });
+  } catch {
+    if (!force) await execAsync(`git worktree remove "${worktreePath}" --force`, { cwd });
+  }
+}
 
-  if (stash) {
-    try { await execAsync('git stash drop', { cwd }); } catch {}
+/**
+ * Create the batch worktree from an existing batch branch ref.
+ * @param {string} batchBranch - Branch name (e.g. batch/20260228T...)
+ * @param {string} cwd - Main repo directory
+ * @returns {Promise<string>} Worktree path
+ */
+export async function createBatchWorktree(batchBranch, cwd) {
+  const basePath = join(os.tmpdir(), `pwn-batch-${process.pid}`);
+  const worktreePath = join(basePath, 'batch');
+  await addWorktree(worktreePath, batchBranch, cwd);
+  return worktreePath;
+}
+
+/**
+ * Create a task worktree for feat/{taskId}.
+ * If the feat branch already exists, resets it to the batch tip.
+ * @param {string} taskId - Task ID
+ * @param {string} batchBranch - Batch branch name
+ * @param {string} cwd - Main repo directory
+ * @returns {Promise<{branch: string, worktreePath: string}>}
+ */
+export async function createTaskWorktree(taskId, batchBranch, cwd) {
+  const branch = `feat/${taskId}`;
+  const basePath = join(os.tmpdir(), `pwn-batch-${process.pid}`);
+  const worktreePath = join(basePath, `task-${taskId}`);
+
+  let branchExists = false;
+  try { await execAsync(`git rev-parse --verify ${branch}`, { cwd }); branchExists = true; } catch {}
+
+  if (branchExists) {
+    const { stdout } = await execAsync(`git rev-parse ${batchBranch}`, { cwd });
+    await execAsync(`git branch -f ${branch} ${stdout.trim()}`, { cwd });
+    await addWorktree(worktreePath, branch, cwd);
+  } else {
+    await addWorktree(worktreePath, branch, cwd, { createBranch: true, baseBranch: batchBranch });
   }
+  return { branch, worktreePath };
 }
 
 /**
- * Create a batch branch from the current HEAD
+ * Create a worktree for an existing feat branch (for pre-validation).
+ * Does NOT reset the branch — inspects it as-is.
+ * @param {string} taskId - Task ID
+ * @param {string} cwd - Main repo directory
+ * @returns {Promise<{branch: string, worktreePath: string}>}
+ */
+export async function addExistingBranchWorktree(taskId, cwd) {
+  const branch = `feat/${taskId}`;
+  const basePath = join(os.tmpdir(), `pwn-batch-${process.pid}`);
+  const worktreePath = join(basePath, `preval-${taskId}`);
+  await addWorktree(worktreePath, branch, cwd);
+  return { branch, worktreePath };
+}
+
+/**
+ * Remove all pwn-batch worktrees (from any PID) and prune.
+ * Called at startup for crash recovery and at end for cleanup.
+ * @param {string} cwd - Main repo directory
+ */
+export async function cleanupAllWorktrees(cwd) {
+  const prefix = join(os.tmpdir(), 'pwn-batch-');
+  try {
+    const { stdout } = await execAsync('git worktree list --porcelain', { cwd });
+    const paths = stdout.split('\n')
+      .filter(line => line.startsWith('worktree '))
+      .map(line => line.slice('worktree '.length))
+      .filter(p => p.startsWith(prefix));
+    for (const p of paths) {
+      try { await execAsync(`git worktree remove "${p}" --force`, { cwd }); } catch {}
+    }
+  } catch {}
+  try { await execAsync('git worktree prune', { cwd }); } catch {}
+}
+
+/**
+ * Symlink node_modules from mainCwd into worktree so quality gates work.
+ * @param {string} worktreePath - Worktree directory
+ * @param {string} mainCwd - Main repo directory
+ */
+const DEP_DIRS = ['node_modules', '.venv', 'venv', 'vendor'];
+
+export function prepareWorktree(worktreePath, mainCwd) {
+  // Symlink dependency directories so quality gates work in worktrees
+  for (const dir of DEP_DIRS) {
+    const source = join(mainCwd, dir);
+    const target = join(worktreePath, dir);
+    if (existsSync(source) && !existsSync(target)) {
+      symlinkSync(source, target);
+    }
+  }
+}
+
+/**
+ * Remove dep symlinks from worktree so git merge doesn't choke on untracked files.
+ * @param {string} worktreePath - Worktree directory
+ */
+export function unprepareWorktree(worktreePath) {
+  for (const dir of DEP_DIRS) {
+    const target = join(worktreePath, dir);
+    try {
+      if (lstatSync(target).isSymbolicLink()) unlinkSync(target);
+    } catch {}
+  }
+}
+
+/**
+ * Create a batch branch from the current HEAD.
+ * Fails fast if the working tree has dirty tracked files (metadata is excluded).
+ * @deprecated Use createBatchRef + createBatchWorktree instead
  * @param {string} cwd - Working directory
  * @returns {Promise<string>} Branch name (batch/{timestamp})
  */
 export async function createBatchBranch(cwd = process.cwd()) {
+  // Check for dirty tracked files (excluding gitignored metadata)
+  try {
+    const { stdout: dirty } = await execAsync('git diff --name-only HEAD', { cwd });
+    const { stdout: staged } = await execAsync('git diff --cached --name-only', { cwd });
+    const allDirty = (dirty + staged).trim();
+    if (allDirty) {
+      throw new Error(
+        `Working tree has uncommitted changes:\n${allDirty}\n\n` +
+        'Commit or stash your changes before starting a batch run.'
+      );
+    }
+  } catch (err) {
+    // If the error is our own, rethrow
+    if (err.message.includes('uncommitted changes')) throw err;
+    // Otherwise (e.g. no HEAD yet), proceed
+  }
+
   const ts = new Date().toISOString().replace(/[:.]/g, '').slice(0, 15);
   const branch = `batch/${ts}`;
   await execAsync(`git checkout -b ${branch}`, { cwd });
@@ -532,15 +732,46 @@ export function markStoryDone(taskId, cwd = process.cwd()) {
   return false;
 }
 
+/**
+ * Commit ONLY prd.json on the current branch.
+ * Used after markStoryDone to persist the "passes: true" update
+ * before switching branches. No-op if prd.json has no changes.
+ * @param {string} taskId - Task ID for commit message
+ * @param {string} cwd - Working directory
+ * @returns {Promise<{success: boolean, noChanges?: boolean, error?: string}>}
+ */
+export async function commitPrdUpdate(taskId, cwd = process.cwd()) {
+  try {
+    await execAsync('git add .ai/tasks/prd.json', { cwd });
+
+    // Check if there's actually a change staged
+    try {
+      await execAsync('git diff --cached --quiet -- .ai/tasks/prd.json', { cwd });
+      return { success: true, noChanges: true };
+    } catch {
+      // There are changes, commit them
+    }
+
+    await execAsync(
+      `git commit -m "chore: mark ${taskId} done in prd.json"`,
+      { cwd }
+    );
+    return { success: true };
+  } catch (error) {
+    return { success: false, error: error.message };
+  }
+}
+
 /**
  * Run a single quality gate
  * @param {string} gate - Gate name (typecheck, lint, test, build, security)
- * @param {string} cwd - Working directory
+ * @param {string} cwd - Working directory where the gate command runs
+ * @param {{ configCwd?: string }} opts - configCwd: directory to load config from (defaults to cwd)
  * @returns {Promise<{success: boolean, output?: string, error?: string}>}
  */
-export async function runQualityGate(gate, cwd = process.cwd()) {
-  // Check for custom gate commands in config
-  const config = loadConfig(cwd);
+export async function runQualityGate(gate, cwd = process.cwd(), { configCwd } = {}) {
+  // Check for custom gate commands in config (from configCwd, not execution cwd)
+  const config = loadConfig(configCwd || cwd);
   const customCmd = config.gate_commands?.[gate];
   const commands = customCmd ? [customCmd] : GATE_COMMANDS[gate];
 
@@ -677,9 +908,16 @@ export async function commitTask(task, options = {}, cwd = process.cwd()) {
   const config = loadConfig(cwd);
 
   try {
-    // Stage all changes
+    // Stage all changes (respects .gitignore)
     await execAsync('git add .', { cwd });
 
+    // Defense-in-depth: unstage metadata and worktree symlinks
+    try {
+      await execAsync('git reset HEAD -- ".ai/batch/" ".ai/state.json" "logs/" "node_modules" ".venv" "venv" "vendor"', { cwd });
+    } catch {
+      // Files may not exist in index — that's fine
+    }
+
     // Check if there are changes to commit
     try {
       await execAsync('git diff --cached --quiet', { cwd });