ralphctl 0.1.0

package/src/ai/executor.ts

@@ -0,0 +1,973 @@
+import { confirm } from '@inquirer/prompts';
+import { readFile, unlink } from 'node:fs/promises';
+import { highlight, info, muted, success, warning } from '@src/theme/index.ts';
+import { ProcessManager } from '@src/ai/process-manager.ts';
+import {
+  getNextTask,
+  getReadyTasks,
+  getRemainingTasks,
+  getTasks,
+  isTaskBlocked,
+  updateTask,
+  updateTaskStatus,
+} from '@src/store/task.ts';
+import { getProgress, logProgress, summarizeProgressForContext } from '@src/store/progress.ts';
+import { getProgressFilePath, getSprintDir } from '@src/utils/paths.ts';
+import { buildTaskExecutionPrompt } from '@src/ai/prompts/index.ts';
+import type { Task } from '@src/schemas/index.ts';
+import { createSpinner, formatTaskStatus } from '@src/theme/ui.ts';
+import { type ExecutionResult, parseExecutionResult } from '@src/ai/parser.ts';
+import type { SpawnResult } from '@src/ai/session.ts';
+import { SpawnError, spawnInteractive, spawnWithRetry } from '@src/ai/session.ts';
+import { RateLimitCoordinator } from '@src/ai/rate-limiter.ts';
+import { EXIT_ALL_BLOCKED, EXIT_ERROR, EXIT_NO_TASKS, EXIT_SUCCESS } from '@src/utils/exit-codes.ts';
+import { getSprint } from '@src/store/sprint.ts';
+import {
+  buildFullTaskContext,
+  formatTask,
+  getContextFileName,
+  getEffectiveCheckScript,
+  getProjectForTask,
+  getRecentGitHistory,
+  runPermissionCheck,
+  type CheckResults,
+  type CheckStatus,
+  type TaskContext,
+  writeTaskContextFile,
+} from '@src/ai/task-context.ts';
+import { runLifecycleHook } from '@src/ai/lifecycle.ts';
+import { type ProviderAdapter } from '@src/providers/types.ts';
+import { getActiveProvider } from '@src/providers/index.ts';
+import { verifySprintBranch } from '@src/ai/runner.ts';
+
+// ============================================================================
+// TYPES
+// ============================================================================
+
+export interface ExecutorOptions {
+  /** Step through tasks with approval between each */
+  step: boolean;
+  /** Limit number of tasks to execute */
+  count: number | null;
+  /** Interactive AI session (collaborate with provider) */
+  session: boolean;
+  /** Skip auto-commit after task completion */
+  noCommit: boolean;
+  /** Max parallel tasks (undefined = auto based on unique repos) */
+  concurrency?: number;
+  /** Max rate-limit retries per task */
+  maxRetries?: number;
+  /** Stop launching new tasks on first failure */
+  failFast?: boolean;
+  /** Skip precondition checks (e.g., unplanned tickets) */
+  force?: boolean;
+  /** Force re-run of check scripts even if they already ran this sprint */
+  refreshCheck?: boolean;
+  /** Auto-generate sprint branch (ralphctl/<sprint-id>) */
+  branch?: boolean;
+  /** Custom branch name for sprint execution */
+  branchName?: string;
+}
+
+/** Reason why execution stopped */
+export type StopReason =
+  | 'all_completed' // All tasks done
+  | 'count_reached' // Reached task count limit
+  | 'task_blocked' // A task could not be completed
+  | 'user_paused' // User chose not to continue in interactive mode
+  | 'no_tasks' // No tasks available
+  | 'all_blocked'; // All remaining tasks blocked by dependencies
+
+export interface ExecutionSummary {
+  /** Number of tasks completed in this run */
+  completed: number;
+  /** Number of remaining tasks */
+  remaining: number;
+  /** Why execution stopped */
+  stopReason: StopReason;
+  /** Task that caused pause (if stopReason is task_blocked) */
+  blockedTask: Task | null;
+  /** Reason for block (if any) */
+  blockedReason: string | null;
+  /** Exit code for CLI */
+  exitCode: number;
+}
+
+// ============================================================================
+// TASK EXECUTION
+// ============================================================================
+
+/** Extended result that includes session ID for resume capability */
+interface TaskExecutionResult extends ExecutionResult {
+  sessionId: string | null;
+}
+
+async function executeTask(
+  ctx: TaskContext,
+  options: ExecutorOptions,
+  sprintId: string,
+  resumeSessionId?: string,
+  provider?: ProviderAdapter,
+  checkStatus?: CheckStatus
+): Promise<TaskExecutionResult> {
+  const p = provider ?? (await getActiveProvider());
+  const label = p.displayName;
+  const projectPath = ctx.task.projectPath;
+  const sprintDir = getSprintDir(sprintId);
+
+  if (options.session) {
+    const contextFileName = getContextFileName(sprintId, ctx.task.id);
+    const gitHistory = getRecentGitHistory(projectPath, 20);
+    const checkScript = getEffectiveCheckScript(ctx.project, projectPath);
+    const allProgress = await getProgress(sprintId);
+    const progressSummary = summarizeProgressForContext(allProgress, projectPath, 3);
+    const fullTaskContent = buildFullTaskContext(ctx, progressSummary || null, gitHistory, checkScript, checkStatus);
+    const progressFilePath = getProgressFilePath(sprintId);
+    const instructions = buildTaskExecutionPrompt(progressFilePath, options.noCommit, contextFileName);
+    const contextFile = await writeTaskContextFile(projectPath, fullTaskContent, instructions, sprintId, ctx.task.id);
+
+    try {
+      const result = spawnInteractive(
+        `Read ${contextFileName} and follow the instructions`,
+        {
+          cwd: projectPath,
+          args: ['--add-dir', sprintDir],
+        },
+        p
+      );
+
+      if (result.error) {
+        return { success: false, output: '', blockedReason: result.error, sessionId: null };
+      }
+
+      if (result.code === 0) {
+        return { success: true, output: '', verified: true, sessionId: null };
+      }
+      return {
+        success: false,
+        output: '',
+        blockedReason: `${label} exited with code ${String(result.code)}`,
+        sessionId: null,
+      };
+    } finally {
+      try {
+        await unlink(contextFile);
+      } catch {
+        // Ignore cleanup errors
+      }
+    }
+  }
+
+  // Headless mode
+  let spawnResult: SpawnResult;
+
+  if (resumeSessionId) {
+    // Resume a previous session — send a short continuation prompt
+    const spinner = createSpinner(`Resuming ${label} session for: ${ctx.task.name}`).start();
+
+    // Register spinner cleanup with ProcessManager
+    const manager = ProcessManager.getInstance();
+    const deregister = manager.registerCleanup(() => {
+      spinner.stop();
+    });
+
+    try {
+      spawnResult = await spawnWithRetry(
+        {
+          cwd: projectPath,
+          args: ['--add-dir', sprintDir],
+          prompt: 'Continue where you left off. Complete the task and signal completion.',
+          resumeSessionId,
+        },
+        {
+          maxRetries: options.maxRetries,
+          onRetry: (attempt, delayMs) => {
+            spinner.text = `Rate limited, retrying in ${String(Math.round(delayMs / 1000))}s (attempt ${String(attempt)})...`;
+          },
+        },
+        p
+      );
+      spinner.succeed(`${label} completed: ${ctx.task.name}`);
+    } catch (err) {
+      spinner.fail(`${label} failed: ${ctx.task.name}`);
+      throw err;
+    } finally {
+      deregister(); // Clean up callback registration
+    }
+  } else {
+    // Fresh session — build full context
+    const contextFileName = getContextFileName(sprintId, ctx.task.id);
+    const gitHistory = getRecentGitHistory(projectPath, 20);
+    const checkScript = getEffectiveCheckScript(ctx.project, projectPath);
+    const allProgress = await getProgress(sprintId);
+    const progressSummary = summarizeProgressForContext(allProgress, projectPath, 3);
+    const fullTaskContent = buildFullTaskContext(ctx, progressSummary || null, gitHistory, checkScript, checkStatus);
+    const progressFilePath = getProgressFilePath(sprintId);
+    const instructions = buildTaskExecutionPrompt(progressFilePath, options.noCommit, contextFileName);
+    const contextFile = await writeTaskContextFile(projectPath, fullTaskContent, instructions, sprintId, ctx.task.id);
+
+    const spinner = createSpinner(`${label} is working on: ${ctx.task.name}`).start();
+
+    // Register spinner cleanup with ProcessManager
+    const manager = ProcessManager.getInstance();
+    const deregister = manager.registerCleanup(() => {
+      spinner.stop();
+    });
+
+    try {
+      const contextContent = await readFile(contextFile, 'utf-8');
+      spawnResult = await spawnWithRetry(
+        {
+          cwd: projectPath,
+          args: ['--add-dir', sprintDir],
+          prompt: contextContent,
+        },
+        {
+          maxRetries: options.maxRetries,
+          onRetry: (attempt, delayMs) => {
+            spinner.text = `Rate limited, retrying in ${String(Math.round(delayMs / 1000))}s (attempt ${String(attempt)})...`;
+          },
+        },
+        p
+      );
+      spinner.succeed(`${label} completed: ${ctx.task.name}`);
+    } catch (err) {
+      spinner.fail(`${label} failed: ${ctx.task.name}`);
+      throw err;
+    } finally {
+      deregister(); // Clean up callback registration
+      try {
+        await unlink(contextFile);
+      } catch {
+        // Ignore cleanup errors
+      }
+    }
+  }
+
+  const parsed = parseExecutionResult(spawnResult.stdout);
+  return { ...parsed, sessionId: spawnResult.sessionId };
+}
+
+// ============================================================================
+// SEQUENTIAL EXECUTION LOOP
+// ============================================================================
+
+/**
+ * Check if all remaining tasks are blocked by dependencies.
+ */
+async function areAllRemainingBlocked(sprintId: string): Promise<boolean> {
+  const remaining = await getRemainingTasks(sprintId);
+  if (remaining.length === 0) return false;
+
+  for (const task of remaining) {
+    if (task.status === 'in_progress') return false;
+    const blocked = await isTaskBlocked(task.id, sprintId);
+    if (!blocked) return false;
+  }
+  return true;
+}
+
+/**
+ * Sequential execution loop - executes tasks one at a time.
+ * Used for session mode, step mode, or --concurrency 1.
+ */
+export async function executeTaskLoop(
+  sprintId: string,
+  options: ExecutorOptions,
+  checkResults?: CheckResults
+): Promise<ExecutionSummary> {
+  // Install signal handlers eagerly so Ctrl+C works before the first child spawns
+  ProcessManager.getInstance().ensureHandlers();
+
+  // Resolve provider once for the entire loop
+  const provider = await getActiveProvider();
+  const label = provider.displayName;
+
+  const sprint = await getSprint(sprintId);
+  let completedCount = 0;
+  const targetCount = options.count ?? Infinity;
+
+  // Check for resumability - find in_progress task
+  const firstTask = await getNextTask(sprintId);
+  if (firstTask?.status === 'in_progress') {
+    console.log(warning(`\nResuming from: ${firstTask.id} - ${firstTask.name}`));
+  }
+
+  // Main implementation loop
+  while (completedCount < targetCount) {
+    // Break immediately if shutdown is in progress (Ctrl+C)
+    const manager = ProcessManager.getInstance();
+    if (manager.isShuttingDown()) {
+      const remaining = await getRemainingTasks(sprintId);
+      return {
+        completed: completedCount,
+        remaining: remaining.length,
+        stopReason: 'task_blocked',
+        blockedTask: null,
+        blockedReason: 'Interrupted by user',
+        exitCode: EXIT_ERROR,
+      };
+    }
+
+    const task = await getNextTask(sprintId);
+
+    if (!task) {
+      // Check if all remaining tasks are blocked
+      if (await areAllRemainingBlocked(sprintId)) {
+        const remaining = await getRemainingTasks(sprintId);
+        return {
+          completed: completedCount,
+          remaining: remaining.length,
+          stopReason: 'all_blocked',
+          blockedTask: null,
+          blockedReason: 'All remaining tasks are blocked by dependencies',
+          exitCode: EXIT_ALL_BLOCKED,
+        };
+      }
+
+      // Truly no tasks
+      const remaining = await getRemainingTasks(sprintId);
+      if (remaining.length === 0 && completedCount === 0) {
+        return {
+          completed: 0,
+          remaining: 0,
+          stopReason: 'no_tasks',
+          blockedTask: null,
+          blockedReason: null,
+          exitCode: EXIT_NO_TASKS,
+        };
+      }
+
+      console.log(success('\nAll tasks completed!'));
+      return {
+        completed: completedCount,
+        remaining: 0,
+        stopReason: 'all_completed',
+        blockedTask: null,
+        blockedReason: null,
+        exitCode: EXIT_SUCCESS,
+      };
+    }
+
+    console.log(info(`\n--- Task ${String(task.order)}: ${task.name} ---`));
+    console.log(info('ID:      ') + task.id);
+    console.log(info('Project: ') + task.projectPath);
+    console.log(info('Status:  ') + formatTaskStatus(task.status));
+
+    // Mark as in_progress if not already
+    if (task.status !== 'in_progress') {
+      await updateTaskStatus(task.id, 'in_progress', sprintId);
+      console.log(muted('Status updated to: in_progress'));
+    }
+
+    // Get project for the task (if available)
+    const project = await getProjectForTask(task, sprint);
+
+    // Build context for AI provider
+    const ctx: TaskContext = { sprint, task, project };
+    const taskPrompt = formatTask(ctx);
+
+    // Run permission check (only on first task of the loop)
+    if (completedCount === 0) {
+      runPermissionCheck(ctx, options.noCommit, provider.name);
+    }
+
+    // Branch verification (if sprint has a branch set)
+    if (sprint.branch) {
+      if (!verifySprintBranch(task.projectPath, sprint.branch)) {
+        console.log(warning(`\nBranch verification failed: expected '${sprint.branch}' in ${task.projectPath}`));
+        console.log(muted(`Task ${task.id} remains in_progress.`));
+        const remaining = await getRemainingTasks(sprintId);
+        return {
+          completed: completedCount,
+          remaining: remaining.length,
+          stopReason: 'task_blocked',
+          blockedTask: task,
+          blockedReason: `Repository ${task.projectPath} is not on expected branch '${sprint.branch}'`,
+          exitCode: EXIT_ERROR,
+        };
+      }
+    }
+
+    if (options.session) {
+      console.log(highlight(`\n[Task Context for ${label}]`));
+      console.log(muted('─'.repeat(50)));
+      console.log(taskPrompt);
+      console.log(muted('─'.repeat(50)));
+      console.log(muted(`\nStarting ${label} in ${task.projectPath} (session)...\n`));
+    } else {
+      console.log(muted(`Starting ${label} in ${task.projectPath} (headless)...`));
+    }
+
+    // Execute task with AI provider
+    const result = await executeTask(ctx, options, sprintId, undefined, provider, checkResults?.get(task.projectPath));
+
+    if (!result.success) {
+      console.log(warning('\nTask not completed.'));
+      if (result.blockedReason) {
+        console.log(warning(`Reason: ${result.blockedReason}`));
+      }
+      console.log(muted('\nExecution paused. Task remains in_progress.'));
+      console.log(muted(`Resume with: ralphctl sprint start ${sprintId}\n`));
+
+      const remaining = await getRemainingTasks(sprintId);
+      return {
+        completed: completedCount,
+        remaining: remaining.length,
+        stopReason: 'task_blocked',
+        blockedTask: task,
+        blockedReason: result.blockedReason ?? 'Unknown reason',
+        exitCode: EXIT_ERROR,
+      };
+    }
+
+    // Store verification result if available
+    if (result.verified) {
+      await updateTask(
+        task.id,
+        {
+          verified: true,
+          verificationOutput: result.verificationOutput,
+        },
+        sprintId
+      );
+      console.log(success('Verification: passed'));
+    }
+
+    // Post-task check hook — run checkScript as a gate before marking done
+    const checkScript = getEffectiveCheckScript(project, task.projectPath);
+    if (checkScript) {
+      console.log(muted(`Running post-task check: ${checkScript}`));
+      const hookResult = runLifecycleHook(task.projectPath, checkScript, 'taskComplete');
+      if (!hookResult.passed) {
+        console.log(warning(`\nPost-task check failed for: ${task.name}`));
+        console.log(muted('Task remains in_progress. Execution paused.'));
+        console.log(muted(`Resume with: ralphctl sprint start ${sprintId}\n`));
+        const remaining = await getRemainingTasks(sprintId);
+        return {
+          completed: completedCount,
+          remaining: remaining.length,
+          stopReason: 'task_blocked',
+          blockedTask: task,
+          blockedReason: `Post-task check failed: ${hookResult.output.slice(0, 500)}`,
+          exitCode: EXIT_ERROR,
+        };
+      }
+      console.log(success('Post-task check: passed'));
+    }
+
+    // Update task status: in_progress → done
+    await updateTaskStatus(task.id, 'done', sprintId);
+    console.log(success('Status updated to: done'));
+
+    // Log automatic progress
+    await logProgress(
+      `Completed task: ${task.id} - ${task.name}\n\n` +
+        (task.description ? `Description: ${task.description}\n` : '') +
+        (task.steps.length > 0 ? `Steps:\n${task.steps.map((s, i) => `  ${String(i + 1)}. ${s}`).join('\n')}` : ''),
+      { sprintId, projectPath: task.projectPath }
+    );
+
+    completedCount++;
+
+    // Interactive mode: confirm before continuing
+    if (options.step && completedCount < targetCount) {
+      const remaining = await getRemainingTasks(sprintId);
+      if (remaining.length > 0) {
+        console.log(info(`\n${String(remaining.length)} task(s) remaining.`));
+        const continueLoop = await confirm({
+          message: 'Continue to next task?',
+          default: true,
+        });
+        if (!continueLoop) {
+          console.log(muted('\nExecution paused.'));
+          console.log(muted(`Resume with: ralphctl sprint start ${sprintId}\n`));
+          return {
+            completed: completedCount,
+            remaining: remaining.length,
+            stopReason: 'user_paused',
+            blockedTask: null,
+            blockedReason: null,
+            exitCode: EXIT_SUCCESS,
+          };
+        }
+      }
+    }
+  }
+
+  // Reached count limit
+  const remaining = await getRemainingTasks(sprintId);
+  return {
+    completed: completedCount,
+    remaining: remaining.length,
+    stopReason: remaining.length === 0 ? 'all_completed' : 'count_reached',
+    blockedTask: null,
+    blockedReason: null,
+    exitCode: EXIT_SUCCESS,
+  };
+}
+
+// ============================================================================
+// PARALLEL EXECUTION LOOP
+// ============================================================================
+
+interface ParallelTaskResult {
+  task: Task;
+  result: TaskExecutionResult | null;
+  error: Error | null;
+  /** Whether this failure is a rate limit (should retry, not count as failure) */
+  isRateLimited: boolean;
+}
+
+/**
+ * Pick tasks to launch: one per unique projectPath, respecting concurrency limit.
+ * Excludes repos that already have an in-flight task.
+ */
+function pickTasksToLaunch(
+  readyTasks: Task[],
+  inFlightPaths: Set<string>,
+  concurrencyLimit: number,
+  currentInFlight: number
+): Task[] {
+  const available = readyTasks.filter((t) => !inFlightPaths.has(t.projectPath));
+
+  // Deduplicate by projectPath — pick the first (lowest order) task per repo
+  const byPath = new Map<string, Task>();
+  for (const task of available) {
+    if (!byPath.has(task.projectPath)) {
+      byPath.set(task.projectPath, task);
+    }
+  }
+
+  const candidates = [...byPath.values()];
+  const slotsAvailable = concurrencyLimit - currentInFlight;
+  return candidates.slice(0, Math.max(0, slotsAvailable));
+}
+
+/**
+ * Parallel execution loop - runs tasks concurrently across different repos.
+ * At most one task per projectPath runs at a time to avoid git conflicts.
+ */
+export async function executeTaskLoopParallel(
+  sprintId: string,
+  options: ExecutorOptions,
+  checkResults?: CheckResults
+): Promise<ExecutionSummary> {
+  // Install signal handlers eagerly so Ctrl+C works before the first child spawns
+  ProcessManager.getInstance().ensureHandlers();
+
+  // Resolve provider once for the entire loop
+  const provider = await getActiveProvider();
+  const label = provider.displayName;
+
+  const sprint = await getSprint(sprintId);
+  let completedCount = 0;
+  const targetCount = options.count ?? Infinity;
+  const failFast = options.failFast ?? true;
+  let hasFailed = false;
+  let firstBlockedTask: Task | null = null;
+  let firstBlockedReason: string | null = null;
+
+  // Determine concurrency limit (hard cap prevents resource exhaustion)
+  const MAX_CONCURRENCY = 10;
+  const allTasks = await getTasks(sprintId);
+  const uniqueRepoPaths = new Set(allTasks.map((t) => t.projectPath));
+  const concurrencyLimit = Math.min(options.concurrency ?? uniqueRepoPaths.size, MAX_CONCURRENCY);
+
+  console.log(muted(`Parallel mode: up to ${String(concurrencyLimit)} concurrent task(s)`));
+
+  // Set up rate limit coordinator
+  const coordinator = new RateLimitCoordinator({
+    onPause: (delayMs) => {
+      console.log(warning(`\nRate limited. Pausing new launches for ${String(Math.round(delayMs / 1000))}s...`));
+    },
+    onResume: () => {
+      console.log(success('Rate limit cooldown ended. Resuming launches.'));
+    },
+  });
+
+  // Track in-flight tasks and session IDs for resume
+  const inFlightPaths = new Set<string>();
+  const running = new Map<string, Promise<ParallelTaskResult>>();
+  const taskSessionIds = new Map<string, string>(); // taskId → AI session ID
+  const branchRetries = new Map<string, number>(); // taskId → branch verification attempts
+  const MAX_BRANCH_RETRIES = 3;
+  let permissionCheckDone = false;
+
+  try {
+    // Check for resumable in_progress tasks
+    const inProgressTasks = allTasks.filter((t) => t.status === 'in_progress');
+    if (inProgressTasks.length > 0) {
+      console.log(warning(`\nResuming ${String(inProgressTasks.length)} in-progress task(s):`));
+      for (const t of inProgressTasks) {
+        console.log(warning(`  - ${t.id}: ${t.name}`));
+      }
+    }
+
+    while (completedCount < targetCount) {
+      // Break immediately if shutdown is in progress (Ctrl+C)
+      const manager = ProcessManager.getInstance();
+      if (manager.isShuttingDown()) {
+        break;
+      }
+
+      // Wait if rate limited before checking for new tasks
+      await coordinator.waitIfPaused();
+
+      // Get current task state from disk
+      const readyTasks = await getReadyTasks(sprintId);
+
+      // Also check for in_progress tasks (resumable)
+      const currentTasks = await getTasks(sprintId);
+      const inProgress = currentTasks.filter((t) => t.status === 'in_progress' && !running.has(t.id));
+
+      // Combine: resume in_progress first, then ready tasks
+      const launchCandidates = [...inProgress, ...readyTasks.filter((t) => !inProgress.some((ip) => ip.id === t.id))];
+
+      if (launchCandidates.length === 0 && running.size === 0) {
+        // Nothing to run and nothing in flight
+        const remaining = await getRemainingTasks(sprintId);
+        if (remaining.length === 0) {
+          if (completedCount === 0) {
+            return {
+              completed: 0,
+              remaining: 0,
+              stopReason: 'no_tasks',
+              blockedTask: null,
+              blockedReason: null,
+              exitCode: EXIT_NO_TASKS,
+            };
+          }
+          console.log(success('\nAll tasks completed!'));
+          return {
+            completed: completedCount,
+            remaining: 0,
+            stopReason: 'all_completed',
+            blockedTask: null,
+            blockedReason: null,
+            exitCode: EXIT_SUCCESS,
+          };
+        }
+
+        // Tasks exist but none are launchable — all blocked
+        return {
+          completed: completedCount,
+          remaining: remaining.length,
+          stopReason: hasFailed ? 'task_blocked' : 'all_blocked',
+          blockedTask: firstBlockedTask,
+          blockedReason: firstBlockedReason ?? 'All remaining tasks are blocked by dependencies',
+          exitCode: hasFailed ? EXIT_ERROR : EXIT_ALL_BLOCKED,
+        };
+      }
+
+      // Pick tasks to launch (if we should)
+      if (!hasFailed || !failFast) {
+        const toStart = pickTasksToLaunch(launchCandidates, inFlightPaths, concurrencyLimit, running.size);
+
+        for (const task of toStart) {
+          if (completedCount + running.size >= targetCount) break;
+
+          // Cache project lookup — reused for permission check and execution
+          const project = await getProjectForTask(task, sprint);
+
+          // Run permission check once (before any task starts)
+          if (!permissionCheckDone) {
+            const ctx: TaskContext = { sprint, task, project };
+            runPermissionCheck(ctx, options.noCommit, provider.name);
+            permissionCheckDone = true;
+          }
+
+          // Branch verification (if sprint has a branch set)
+          if (sprint.branch) {
+            if (!verifySprintBranch(task.projectPath, sprint.branch)) {
+              const attempt = (branchRetries.get(task.id) ?? 0) + 1;
+              branchRetries.set(task.id, attempt);
+
+              if (attempt < MAX_BRANCH_RETRIES) {
+                // Transient failure — re-enqueue for retry (similar to rate-limited tasks)
+                console.log(
+                  warning(
+                    `\n  Branch verification failed (attempt ${String(attempt)}/${String(MAX_BRANCH_RETRIES)}): expected '${sprint.branch}' in ${task.projectPath}`
+                  )
+                );
+                console.log(muted(`  Task ${task.id} will retry on next loop iteration.`));
+                continue;
+              }
+
+              // Exhausted retries — treat as a real failure
+              console.log(
+                warning(
+                  `\n  Branch verification failed after ${String(MAX_BRANCH_RETRIES)} attempts: expected '${sprint.branch}' in ${task.projectPath}`
+                )
+              );
+              console.log(muted(`  Task ${task.id} not started — wrong branch.`));
+              hasFailed = true;
+              if (!firstBlockedTask) {
+                firstBlockedTask = task;
+                firstBlockedReason = `Repository ${task.projectPath} is not on expected branch '${sprint.branch}'`;
+              }
+              if (failFast) {
+                console.log(muted('Fail-fast: waiting for running tasks to finish...'));
+              }
+              continue;
+            }
+          }
+
+          // Mark as in_progress only after pre-flight passes
+          if (task.status !== 'in_progress') {
+            await updateTaskStatus(task.id, 'in_progress', sprintId);
+          }
+
+          // Check if we have a session ID to resume from (rate-limit recovery)
+          const resumeId = taskSessionIds.get(task.id);
+          const action = resumeId ? 'Resuming' : 'Starting';
+
+          console.log(info(`\n--- ${action} task ${String(task.order)}: ${task.name} ---`));
+          console.log(info('ID:      ') + task.id);
+          console.log(info('Project: ') + task.projectPath);
+          if (resumeId) {
+            console.log(muted(`Resuming ${label} session ${resumeId.slice(0, 8)}...`));
+          } else {
+            console.log(muted(`Starting ${label} in ${task.projectPath} (headless)...`));
+          }
+
+          inFlightPaths.add(task.projectPath);
+
+          const taskPromise = (async (): Promise<ParallelTaskResult> => {
+            try {
+              const ctx: TaskContext = { sprint, task, project };
+              const result = await executeTask(
+                ctx,
+                options,
+                sprintId,
+                resumeId,
+                provider,
+                checkResults?.get(task.projectPath)
+              );
+
+              // Store session ID for potential future resume
+              if (result.sessionId) {
+                taskSessionIds.set(task.id, result.sessionId);
+              }
+
+              return { task, result, error: null, isRateLimited: false };
+            } catch (err) {
+              if (err instanceof SpawnError && err.rateLimited) {
+                // Store session ID from error for resume after cooldown
+                if (err.sessionId) {
+                  taskSessionIds.set(task.id, err.sessionId);
+                }
+                const delay = err.retryAfterMs ?? 60_000;
+                coordinator.pause(delay);
+
+                return {
+                  task,
+                  result: null,
+                  error: err,
+                  isRateLimited: true,
+                };
+              }
+
+              return {
+                task,
+                result: null,
+                error: err instanceof Error ? err : new Error(String(err)),
+                isRateLimited: false,
+              };
+            } finally {
+              inFlightPaths.delete(task.projectPath);
+            }
+          })();
+
+          running.set(task.id, taskPromise);
+        }
+      }
+
+      // Wait for any task to complete
+      if (running.size === 0) {
+        // Check if any tasks are pending branch retry before giving up
+        const hasPendingBranchRetry = [...branchRetries.entries()].some(([, count]) => count < MAX_BRANCH_RETRIES);
+        if (hasPendingBranchRetry) {
+          // Brief delay before retrying to avoid tight-looping
+          await new Promise((resolve) => setTimeout(resolve, 1000));
+          continue;
+        }
+        // Nothing launched, nothing running, no retries pending — stop
+        break;
+      }
+
+      // Wait for first task to complete, then check rate limit state and launch next batch
+      const settled = await Promise.race([...running.values()]);
+      running.delete(settled.task.id);
+
+      // Process the result
+      if (settled.error) {
+        if (settled.isRateLimited) {
+          // Rate limit — not a real failure, will be re-queued after cooldown
+          const sessionId = taskSessionIds.get(settled.task.id);
+          console.log(warning(`\nRate limited: ${settled.task.name}`));
+          if (sessionId) {
+            console.log(muted(`Session saved for resume: ${sessionId.slice(0, 8)}...`));
+          }
+          console.log(muted('Will retry after cooldown.'));
+          // Don't set hasFailed — this task will be re-launched on next loop iteration
+          continue;
+        }
+
+        // Real error
+        console.log(warning(`\nTask failed: ${settled.task.name}`));
+        console.log(warning(`Error: ${settled.error.message}`));
+        console.log(muted(`Task ${settled.task.id} remains in_progress for resumption.`));
+
+        hasFailed = true;
+        if (!firstBlockedTask) {
+          firstBlockedTask = settled.task;
+          firstBlockedReason = settled.error.message;
+        }
+
+        if (failFast) {
+          console.log(muted('Fail-fast: waiting for running tasks to finish...'));
+        }
+        continue;
+      }
+
+      if (settled.result && !settled.result.success) {
+        console.log(warning(`\nTask not completed: ${settled.task.name}`));
+        if (settled.result.blockedReason) {
+          console.log(warning(`Reason: ${settled.result.blockedReason}`));
+        }
+        console.log(muted(`Task ${settled.task.id} remains in_progress.`));
+
+        hasFailed = true;
+        if (!firstBlockedTask) {
+          firstBlockedTask = settled.task;
+          firstBlockedReason = settled.result.blockedReason ?? 'Unknown reason';
+        }
+
+        if (failFast) {
+          console.log(muted('Fail-fast: waiting for running tasks to finish...'));
+        }
+        continue;
+      }
+
+      // Task completed successfully
+      if (settled.result) {
+        // Store verification result
+        if (settled.result.verified) {
+          await updateTask(
+            settled.task.id,
+            {
+              verified: true,
+              verificationOutput: settled.result.verificationOutput,
+            },
+            sprintId
+          );
+          console.log(success(`Verification passed: ${settled.task.name}`));
+        }
+
+        // Post-task check hook
+        const taskProject = await getProjectForTask(settled.task, sprint);
+        const taskCheckScript = getEffectiveCheckScript(taskProject, settled.task.projectPath);
+        if (taskCheckScript) {
+          const hookResult = runLifecycleHook(settled.task.projectPath, taskCheckScript, 'taskComplete');
+          if (!hookResult.passed) {
+            console.log(warning(`\nPost-task check failed for: ${settled.task.name}`));
+            console.log(muted(`Task ${settled.task.id} remains in_progress.`));
+            hasFailed = true;
+            if (!firstBlockedTask) {
+              firstBlockedTask = settled.task;
+              firstBlockedReason = `Post-task check failed: ${hookResult.output.slice(0, 500)}`;
+            }
+            if (failFast) {
+              console.log(muted('Fail-fast: waiting for running tasks to finish...'));
+            }
+            continue;
+          }
+          console.log(success(`Post-task check passed: ${settled.task.name}`));
+        }
+
+        // Mark done
+        await updateTaskStatus(settled.task.id, 'done', sprintId);
+        console.log(success(`Completed: ${settled.task.name}`));
+
+        // Clean up session tracking
+        taskSessionIds.delete(settled.task.id);
+
+        // Log progress
+        await logProgress(
+          `Completed task: ${settled.task.id} - ${settled.task.name}\n\n` +
+            (settled.task.description ? `Description: ${settled.task.description}\n` : '') +
+            (settled.task.steps.length > 0
+              ? `Steps:\n${settled.task.steps.map((s, i) => `  ${String(i + 1)}. ${s}`).join('\n')}`
+              : ''),
+          { sprintId, projectPath: settled.task.projectPath }
+        );
+
+        completedCount++;
+      }
+    }
+
+    // Wait for any remaining in-flight tasks
+    if (running.size > 0) {
+      console.log(muted(`\nWaiting for ${String(running.size)} remaining task(s)...`));
+      const remaining = await Promise.allSettled([...running.values()]);
+      for (const r of remaining) {
+        if (r.status === 'fulfilled' && r.value.result?.success) {
+          if (r.value.result.verified) {
+            await updateTask(
+              r.value.task.id,
+              { verified: true, verificationOutput: r.value.result.verificationOutput },
+              sprintId
+            );
+          }
+          // Post-task check hook
+          const drainProject = await getProjectForTask(r.value.task, sprint);
+          const drainCheckScript = getEffectiveCheckScript(drainProject, r.value.task.projectPath);
+          if (drainCheckScript) {
+            const hookResult = runLifecycleHook(r.value.task.projectPath, drainCheckScript, 'taskComplete');
+            if (!hookResult.passed) {
+              console.log(warning(`Post-task check failed for: ${r.value.task.name}`));
+              continue;
+            }
+          }
+          await updateTaskStatus(r.value.task.id, 'done', sprintId);
+          console.log(success(`Completed: ${r.value.task.name}`));
+          await logProgress(`Completed task: ${r.value.task.id} - ${r.value.task.name}`, {
+            sprintId,
+            projectPath: r.value.task.projectPath,
+          });
+          completedCount++;
+        }
+      }
+    }
+  } finally {
+    coordinator.dispose();
+  }
+
+  const remainingTasks = await getRemainingTasks(sprintId);
+
+  if (hasFailed) {
+    return {
+      completed: completedCount,
+      remaining: remainingTasks.length,
+      stopReason: 'task_blocked',
+      blockedTask: firstBlockedTask,
+      blockedReason: firstBlockedReason,
+      exitCode: EXIT_ERROR,
+    };
+  }
+
+  return {
+    completed: completedCount,
+    remaining: remainingTasks.length,
+    stopReason: remainingTasks.length === 0 ? 'all_completed' : 'count_reached',
+    blockedTask: null,
+    blockedReason: null,
+    exitCode: EXIT_SUCCESS,
+  };
+}
+
+// Re-export for backward compatibility
+export { formatTask as formatTaskContext } from '@src/ai/task-context.ts';
+// Re-export TaskContext type for consumers
+export type { TaskContext } from '@src/ai/task-context.ts';