@jojonax/codex-copilot 1.5.5 → 1.6.1

package/src/commands/run.js

@@ -1,958 +1,958 @@
-/**
- * codex-copilot run - Main orchestration loop
- * 
- * Executes tasks one by one: Develop → PR → Review → Fix → Merge → Next
- * Features fine-grained checkpoint/resume at every sub-step.
- */
-
-import { readFileSync, writeFileSync, existsSync } from 'fs';
-import { resolve } from 'path';
-import { log, progressBar } from '../utils/logger.js';
-import { git } from '../utils/git.js';
-import { github } from '../utils/github.js';
-import { closePrompt } from '../utils/prompt.js';
-import { createCheckpoint } from '../utils/checkpoint.js';
-import { provider } from '../utils/provider.js';
-import { readJSON, writeJSON } from '../utils/json.js';
-import { preFlightCheck, releaseLock } from '../utils/self-heal.js';
-
-const maxRateLimitRetries = 3;
-
-export async function run(projectDir) {
-  const tasksPath = resolve(projectDir, '.codex-copilot/tasks.json');
-  const configPath = resolve(projectDir, '.codex-copilot/config.json');
-  const checkpoint = createCheckpoint(projectDir);
-
-  let tasks;
-  let state;
-
-  // Load tasks.json (required)
-  try {
-    tasks = readJSON(tasksPath);
-  } catch (err) {
-    log.warn(`tasks.json read issue: ${err.message}`);
-    log.info('Attempting auto-repair...');
-
-    // Try auto-fix (deep repair + schema validation)
-    const { autoFix } = await import('./fix.js');
-    const fixResult = autoFix(projectDir, { files: ['tasks.json'] });
-
-    if (fixResult.ok && fixResult.repaired.includes('tasks.json')) {
-      try {
-        tasks = readJSON(tasksPath);
-        log.info('✅ tasks.json auto-repaired successfully');
-      } catch {
-        // Auto-fix wrote the file but it's still not readable (shouldn't happen)
-        log.error('Auto-repair wrote file but it remains unreadable');
-      }
-    }
-
-    // If still no tasks, try backup
-    if (!tasks && existsSync(tasksPath + '.bak')) {
-      log.info('Trying backup file...');
-      try {
-        tasks = readJSON(tasksPath + '.bak');
-        writeJSON(tasksPath, tasks);
-        log.info('✅ Restored tasks.json from backup');
-      } catch {
-        log.error('Backup is also corrupted');
-      }
-    }
-
-    if (!tasks) {
-      log.error('Cannot recover tasks.json. Run: codex-copilot fix');
-      closePrompt();
-      process.exit(1);
-    }
-  }
-
-  // Load state.json (optional — falls back to default)
-  try {
-    state = checkpoint.load();
-  } catch {
-    log.warn('State file corrupted — resetting to initial state');
-    state = checkpoint.reset();
-  }
-  const config = existsSync(configPath) ? readJSON(configPath) : {};
-
-  // Validate tasks.json structure
-  if (!tasks.tasks || !Array.isArray(tasks.tasks) || !tasks.total) {
-    log.error('Invalid tasks.json format: missing tasks array or total field');
-    log.warn('Please re-run codex-copilot init and let CodeX regenerate tasks.json');
-    closePrompt();
-    process.exit(1);
-  }
-
-  const baseBranch = config.base_branch || 'main';
-  const providerId = config.provider || 'codex-cli';
-  const maxReviewRounds = config.max_review_rounds || 2;
-  const pollInterval = config.review_poll_interval || 60;
-  const waitTimeout = config.review_wait_timeout || 600;
-  const isPrivate = github.isPrivateRepo(projectDir); // Cache once
-  const weeklyQuotaThreshold = config.weekly_quota_threshold || 97;
-
-  const providerInfo = provider.getProvider(providerId);
-  log.info(`AI Provider: ${providerInfo ? providerInfo.name : providerId}`);
-
-  // ===== Graceful shutdown handler =====
-  let shuttingDown = false;
-  const gracefulShutdown = () => {
-    if (shuttingDown) {
-      log.warn('Force exit');
-      process.exit(1);
-    }
-    shuttingDown = true;
-    log.blank();
-    log.warn('Interrupt received — saving checkpoint...');
-    // State is already saved at each step, just need to save tasks.json
-    writeJSON(tasksPath, tasks);
-    releaseLock(projectDir);
-    log.info('✅ Checkpoint saved. Run `codex-copilot run` to resume.');
-    log.blank();
-    closePrompt();
-    process.exit(0);
-  };
-  process.on('SIGINT', gracefulShutdown);
-  process.on('SIGTERM', gracefulShutdown);
-
-  log.title('🚀 Starting automated development loop');
-  log.blank();
-  log.info(`Project: ${tasks.project}`);
-  log.info(`Total tasks: ${tasks.total}`);
-  log.info(`Base branch: ${baseBranch}`);
-
-  // ===== Pre-flight self-healing =====
-  const health = preFlightCheck(projectDir, baseBranch, { checkpoint, tasks });
-  if (!health.ok) {
-    log.blank();
-    log.error('Pre-flight check failed — cannot proceed:');
-    for (const b of health.blockers) {
-      log.error(`  🛑 ${b}`);
-    }
-    log.blank();
-    releaseLock(projectDir);
-    closePrompt();
-    process.exit(1);
-  }
-  log.blank();
-
-  // ===== Pre-flight: ensure base branch is committed & pushed =====
-  await ensureBaseReady(projectDir, baseBranch, isPrivate);
-
-  // Show resume info if resuming mid-task
-  if (state.phase && state.current_task > 0) {
-    log.blank();
-    log.info(`⏩ Resuming task #${state.current_task} from: ${state.phase} → ${state.phase_step}`);
-  }
-
-  // ===== Auto-retry blocked tasks =====
-  // On each run, reset blocked tasks to pending so they're retried in order.
-  // Branches and checkpoint steps are PRESERVED — the task resumes from where
-  // it left off, keeping all previously developed code.
-  const blockedTasks = tasks.tasks.filter(t => t.status === 'blocked');
-  if (blockedTasks.length > 0) {
-    log.blank();
-    log.info(`🔄 Auto-retrying ${blockedTasks.length} blocked task(s)...`);
-    for (const bt of blockedTasks) {
-      bt.status = 'pending';
-      bt.retry_count = (bt.retry_count || 0) + 1;
-      bt._retrying = true; // Flag: don't skip even if below checkpoint
-      log.dim(`   ↳ Task #${bt.id}: ${bt.title.substring(0, 50)} (attempt ${bt.retry_count + 1})`);
-    }
-    writeJSON(tasksPath, tasks);
-  }
-
-  const completedCount = tasks.tasks.filter(t => t.status === 'completed').length;
-  log.blank();
-  progressBar(completedCount, tasks.total, `${completedCount}/${tasks.total} tasks done`);
-  log.blank();
-
-  // Execute tasks one by one
-  for (const task of tasks.tasks) {
-    // Skip fully completed tasks
-    if (task.status === 'completed' || task.status === 'skipped') continue;
-
-    // Skip tasks whose ID is below the checkpoint (unless retrying a blocked task)
-    const isResumingTask = state.current_task === task.id && state.phase;
-    if (task.id < state.current_task && !isResumingTask && !task._retrying) continue;
-
-    // Clean up retry flag (used only to bypass checkpoint skip)
-    delete task._retrying;
-
-    log.blank();
-    log.title(`━━━ Task ${task.id}/${tasks.total}: ${task.title} ━━━`);
-    log.blank();
-
-    // ===== Quota pre-check (Codex CLI only) =====
-    if (providerId === 'codex-cli' || providerId === 'codex-desktop') {
-      const quota = provider.checkQuotaBeforeExecution(weeklyQuotaThreshold);
-      if (!quota.ok) {
-        log.blank();
-        log.error(`⚠ Weekly quota at ${quota.quota7d}% (threshold: ${weeklyQuotaThreshold}%) — stopping to preserve remaining quota`);
-        log.info('Run `codex-copilot usage` to check quota details');
-        log.info('Run `codex-copilot run` again when quota resets');
-        writeJSON(tasksPath, tasks);
-        closePrompt();
-        process.exit(0);
-      }
-      if (quota.warning) {
-        log.warn(`⚠ Weekly quota at ${quota.quota7d}% — approaching limit`);
-      }
-    }
-
-    // Check dependencies — completed, skipped, and blocked all satisfy dependencies.
-    // Blocked tasks are treated as "done for now" to prevent cascade-skipping;
-    // the user can retry them later with `codex-copilot retry`.
-    if (task.depends_on && task.depends_on.length > 0) {
-      const DONE_STATUSES = ['completed', 'skipped', 'blocked'];
-      const unfinished = task.depends_on.filter(dep => {
-        const depTask = tasks.tasks.find(t => t.id === dep);
-        return depTask && !DONE_STATUSES.includes(depTask.status);
-      });
-      if (unfinished.length > 0) {
-        log.warn(`Unfinished dependencies: ${unfinished.join(', ')} — skipping`);
-        continue;
-      }
-      // Warn about blocked deps but still proceed
-      const blockedDeps = task.depends_on.filter(dep => {
-        const depTask = tasks.tasks.find(t => t.id === dep);
-        return depTask && depTask.status === 'blocked';
-      });
-      if (blockedDeps.length > 0) {
-        log.warn(`⚠ Dependencies ${blockedDeps.join(', ')} are blocked — proceeding anyway`);
-      }
-    }
-
-    // ===== Ensure task has all required fields =====
-    // Auto-generate branch name if missing (common after corruption recovery)
-    if (!task.branch) {
-      // Try to recover from checkpoint state
-      if (state.current_task === task.id && state.branch) {
-        task.branch = state.branch;
-        log.dim(`  ↳ Recovered branch name from checkpoint: ${task.branch}`);
-      } else {
-        const slug = (task.title || `task-${task.id}`)
-          .toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').substring(0, 40);
-        task.branch = `feature/${String(task.id).padStart(3, '0')}-${slug}`;
-        log.dim(`  ↳ Generated branch name: ${task.branch}`);
-      }
-    }
-    if (!task.depends_on) task.depends_on = [];
-    if (!task.acceptance) task.acceptance = [];
-    if (!task.description) task.description = task.title;
-
-    // Mark task as in_progress
-    task.status = 'in_progress';
-    const isRetry = (task.retry_count || 0) > 0;
-    const retryStartedAt = isRetry ? new Date().toISOString() : null;
-    writeJSON(tasksPath, tasks);
-
-    // ===== Phase 1: Develop =====
-    if (!checkpoint.isStepDone(task.id, 'develop', 'codex_complete')) {
-      await developPhase(projectDir, task, baseBranch, checkpoint, providerId);
-      // If dev phase failed, mark blocked and skip to next task
-      if (task.status === 'blocked') {
-        writeJSON(tasksPath, tasks);
-        log.blank();
-        log.warn(`⚠ Task #${task.id} is blocked — AI development failed`);
-        continue;
-      }
-    } else {
-      log.dim('⏩ Skipping develop phase (already completed)');
-    }
-
-    // ===== Phase 2: Create PR =====
-    let prInfo;
-    if (!checkpoint.isStepDone(task.id, 'pr', 'pr_created')) {
-      prInfo = await prPhase(projectDir, task, baseBranch, checkpoint, isPrivate);
-    } else {
-      // PR already created, load from state
-      state = checkpoint.load();
-      prInfo = { number: state.current_pr, url: '' };
-      log.dim(`⏩ Skipping PR phase (PR #${prInfo.number} already created)`);
-    }
-
-    // ===== Phase 3: Review loop =====
-    if (!checkpoint.isStepDone(task.id, 'merge', 'merged')) {
-      // On retry: request fresh re-review since old reviews may be stale
-      if (isRetry && prInfo?.number) {
-        log.info('🔄 Retry: requesting fresh re-review on existing PR...');
-        try {
-          github.requestReReview(projectDir, prInfo.number);
-        } catch { /* ignore — review bots may not be configured */ }
-      }
-
-      await reviewLoop(projectDir, task, prInfo, {
-        maxRounds: maxReviewRounds,
-        pollInterval,
-        waitTimeout,
-        retryStartedAt, // Only count reviews after this timestamp
-      }, checkpoint, providerId, isPrivate);
-    } else {
-      log.dim('⏩ Skipping review phase (already completed)');
-    }
-
-    // ===== Phase 4: Merge =====
-    if (!checkpoint.isStepDone(task.id, 'merge', 'merged')) {
-      await mergePhase(projectDir, task, prInfo, baseBranch, checkpoint);
-    } else {
-      // Checkpoint says merged — verify against GitHub
-      if (prInfo?.number) {
-        const prState = github.getPRState(projectDir, prInfo.number);
-        if (prState !== 'merged') {
-          log.warn(`⚠ Checkpoint says merged but PR #${prInfo.number} is ${prState} — re-entering merge`);
-          await mergePhase(projectDir, task, prInfo, baseBranch, checkpoint);
-        } else {
-          log.dim('⏩ Skipping merge phase (PR confirmed merged on GitHub)');
-        }
-      } else {
-        log.dim('⏩ Skipping merge phase (already merged)');
-      }
-    }
-
-    // Check if task was blocked during review/merge
-    if (task.status === 'blocked') {
-      writeJSON(tasksPath, tasks);
-      log.blank();
-      log.warn(`⚠ Task #${task.id} is blocked — needs manual intervention`);
-      log.blank();
-      const done = tasks.tasks.filter(t => t.status === 'completed').length;
-      const blocked = tasks.tasks.filter(t => t.status === 'blocked').length;
-      progressBar(done, tasks.total, `${done}/${tasks.total} done, ${blocked} blocked`);
-      continue;
-    }
-
-    // Mark task complete
-    task.status = 'completed';
-    delete task.block_reason;
-    delete task.retry_count;
-    writeJSON(tasksPath, tasks);
-    checkpoint.completeTask(task.id);
-
-    log.blank();
-    const done = tasks.tasks.filter(t => t.status === 'completed').length;
-    progressBar(done, tasks.total, `${done}/${tasks.total} tasks done`);
-    log.info(`✅ Task #${task.id} complete!`);
-  }
-
-  log.blank();
-  const finalDone = tasks.tasks.filter(t => t.status === 'completed').length;
-  const finalBlocked = tasks.tasks.filter(t => t.status === 'blocked').length;
-  if (finalBlocked > 0) {
-    log.title(`✅ Finished — ${finalDone}/${tasks.total} done, ${finalBlocked} blocked`);
-  } else {
-    log.title('🎉 All tasks complete!');
-  }
-  log.blank();
-  process.removeListener('SIGINT', gracefulShutdown);
-  process.removeListener('SIGTERM', gracefulShutdown);
-  releaseLock(projectDir);
-
-  // ===== Auto-evolve: trigger next round if enabled =====
-  if (config.auto_evolve !== false) {
-    log.blank();
-    log.info('🔄 Auto-evolving to next round...');
-    log.blank();
-    const { evolve } = await import('./evolve.js');
-    await evolve(projectDir);
-    return; // evolve() calls run() internally
-  }
-
-  closePrompt();
-}
-
-// ──────────────────────────────────────────────
-// Phase 1: Develop
-// ──────────────────────────────────────────────
-async function developPhase(projectDir, task, baseBranch, checkpoint, providerId) {
-  log.step('Phase 1/4: Develop');
-
-  // Step 1: Switch to feature branch
-  if (!checkpoint.isStepDone(task.id, 'develop', 'branch_created')) {
-    try {
-      git.checkoutBranch(projectDir, task.branch, baseBranch);
-    } catch (err) {
-      log.error(`Failed to switch to branch ${task.branch}: ${err.message}`);
-      task.status = 'blocked';
-      task.block_reason = 'git_checkout_failed';
-      return;
-    }
-    log.info(`Switched to branch: ${task.branch}`);
-    checkpoint.saveStep(task.id, 'develop', 'branch_created', { branch: task.branch });
-  } else {
-    // Ensure we're on the right branch
-    const current = git.currentBranch(projectDir);
-    if (current !== task.branch) {
-      try {
-        git.checkoutBranch(projectDir, task.branch, baseBranch);
-      } catch (err) {
-        log.error(`Failed to switch to branch ${task.branch}: ${err.message}`);
-        task.status = 'blocked';
-        task.block_reason = 'git_checkout_failed';
-        return;
-      }
-    }
-    log.dim('⏩ Branch already created');
-  }
-
-  // Step 2: Build development prompt
-  if (!checkpoint.isStepDone(task.id, 'develop', 'prompt_ready')) {
-    const devPrompt = buildDevPrompt(task, projectDir);
-    const promptPath = resolve(projectDir, '.codex-copilot/_current_prompt.md');
-    writeFileSync(promptPath, devPrompt);
-    checkpoint.saveStep(task.id, 'develop', 'prompt_ready', { branch: task.branch });
-    log.info('Development prompt generated');
-  } else {
-    log.dim('⏩ Prompt already generated');
-  }
-
-  // Step 3: Execute via AI Provider (with rate limit auto-retry + timeout protection)
-  if (!checkpoint.isStepDone(task.id, 'develop', 'codex_complete')) {
-    const promptPath = resolve(projectDir, '.codex-copilot/_current_prompt.md');
-    let rateLimitRetries = 0;
-    const AI_TIMEOUT_MS = 30 * 60 * 1000; // D4: 30 minute timeout for AI execution
-
-    while (rateLimitRetries < maxRateLimitRetries) {
-      // D4: Race the AI execution against a timeout to prevent infinite hangs
-      const timeoutPromise = new Promise((_, reject) =>
-        setTimeout(() => reject(new Error('AI_TIMEOUT')), AI_TIMEOUT_MS)
-      );
-
-      let result;
-      try {
-        result = await Promise.race([
-          provider.executePrompt(providerId, promptPath, projectDir),
-          timeoutPromise,
-        ]);
-      } catch (timeoutErr) {
-        if (timeoutErr.message === 'AI_TIMEOUT') {
-          log.error(`AI provider timed out after ${AI_TIMEOUT_MS / 60000} minutes — marking task as blocked`);
-          task.status = 'blocked';
-          task.block_reason = 'ai_timeout';
-          return;
-        }
-        throw timeoutErr;
-      }
-
-      if (result.ok) {
-        log.info('Development complete');
-        checkpoint.saveStep(task.id, 'develop', 'codex_complete', { branch: task.branch });
-        break;
-      }
-
-      if (result.rateLimited && result.retryAt) {
-        rateLimitRetries++;
-        log.warn(`Rate limit hit (attempt ${rateLimitRetries}/${maxRateLimitRetries})`);
-        if (rateLimitRetries >= maxRateLimitRetries) {
-          log.error('Max rate limit retries reached — marking task as blocked');
-          task.status = 'blocked';
-          task.block_reason = 'rate_limited';
-          return;
-        }
-        await waitForRateLimitReset(result.retryAt, result.retryAtStr);
-        log.info('Rate limit reset — resuming development...');
-        continue;
-      }
-
-      // Non-rate-limit failure
-      log.error('AI development failed — marking task as blocked');
-      task.status = 'blocked';
-      task.block_reason = 'dev_failed';
-      return;
-    }
-  }
-}
-
-// ──────────────────────────────────────────────
-// Phase 2: Create PR
-// ──────────────────────────────────────────────
-async function prPhase(projectDir, task, baseBranch, checkpoint, isPrivate) {
-  log.step('Phase 2/4: Submit PR');
-
-  // Step 1: Commit changes
-  if (!checkpoint.isStepDone(task.id, 'pr', 'committed')) {
-    if (!git.isClean(projectDir)) {
-      log.info('Uncommitted changes detected, auto-committing...');
-      const skipCI = isPrivate ? ' [skip ci]' : '';
-      git.commitAll(projectDir, `feat(task-${task.id}): ${task.title}${skipCI}`);
-    }
-    checkpoint.saveStep(task.id, 'pr', 'committed', { branch: task.branch });
-    log.info('Changes committed');
-  } else {
-    log.dim('⏩ Changes already committed');
-  }
-
-  // Step 2: Push
-  if (!checkpoint.isStepDone(task.id, 'pr', 'pushed')) {
-    git.pushBranch(projectDir, task.branch);
-    checkpoint.saveStep(task.id, 'pr', 'pushed', { branch: task.branch });
-    log.info('Code pushed');
-  } else {
-    log.dim('⏩ Code already pushed');
-  }
-
-  // Step 3: Create PR
-  if (!checkpoint.isStepDone(task.id, 'pr', 'pr_created')) {
-    const acceptanceList = Array.isArray(task.acceptance) && task.acceptance.length > 0
-      ? task.acceptance.map(a => `- [ ] ${a}`).join('\n')
-      : '- [ ] Feature works correctly';
-    const prBody = `## Task #${task.id}: ${task.title}\n\n${task.description}\n\n### Acceptance Criteria\n${acceptanceList}\n\n---\n*Auto-created by Codex-Copilot*`;
-
-    // Use auto-recovery: create → find existing → fix remote → retry
-    const prInfo = github.createPRWithRecovery(projectDir, {
-      title: `feat(task-${task.id}): ${task.title}`,
-      body: prBody,
-      base: baseBranch,
-      head: task.branch,
-    });
-    log.info(`PR ready: #${prInfo.number} ${prInfo.url}`);
-
-    checkpoint.saveStep(task.id, 'pr', 'pr_created', {
-      branch: task.branch,
-      current_pr: prInfo.number,
-    });
-    return prInfo;
-  }
-
-  // If we get here, PR was already created — load from state
-  const state = checkpoint.load();
-  return { number: state.current_pr, url: '' };
-}
-
-// ──────────────────────────────────────────────
-// Phase 3: Review loop
-// ──────────────────────────────────────────────
-async function reviewLoop(projectDir, task, prInfo, { maxRounds: _maxRounds, pollInterval, waitTimeout, retryStartedAt }, checkpoint, providerId, isPrivate) {
-  const HARD_MAX_ROUNDS = 5;
-  const MAX_POLL_RETRIES = 3;
-  let maxRounds = Math.min(_maxRounds, HARD_MAX_ROUNDS);
-  log.step('Phase 3/4: Waiting for review');
-
-  // Resume from saved review round
-  const state = checkpoint.load();
-  const startRound = (state.current_task === task.id && state.review_round > 0)
-    ? state.review_round
-    : 1;
-
-  let pollRetries = 0;
-
-  for (let round = startRound; round <= maxRounds; round++) {
-    // Step: Waiting for review
-    checkpoint.saveStep(task.id, 'review', 'waiting_review', {
-      branch: task.branch,
-      current_pr: prInfo.number,
-      review_round: round,
-    });
-
-    log.info('Checking for review feedback...');
-
-    let gotReview = false;
-
-    // Always proactively check for existing reviews first.
-    // This catches: already-posted bot reviews, stale reviews found on resume,
-    // and fast bot responses after fix pushes.
-    const existingReviews = github.getReviews(projectDir, prInfo.number);
-    const existingComments = github.getIssueComments(projectDir, prInfo.number);
-
-    // On retry: only count reviews posted AFTER the retry started
-    const isReviewFresh = (item) => {
-      if (!retryStartedAt) return true; // Not a retry — all reviews are valid
-      const itemDate = item.submitted_at || item.created_at || item.updated_at;
-      return itemDate && new Date(itemDate) > new Date(retryStartedAt);
-    };
-
-    const freshReviews = existingReviews.filter(isReviewFresh);
-    const freshComments = existingComments.filter(isReviewFresh);
-
-    const hasReview = freshReviews.some(r => r.state !== 'PENDING');
-    const hasBotComment = freshComments.some(c =>
-      c.user?.type === 'Bot' || c.user?.login?.includes('bot')
-    );
-
-    if (hasReview || hasBotComment) {
-      log.info('Review found — processing immediately');
-      gotReview = true;
-    }
-
-    if (!gotReview) {
-      // After fix pushes (round > 1), bot should respond quickly if configured.
-      // Use shorter timeout to avoid wasting 10+ minutes waiting for nothing.
-      const effectiveTimeout = round > 1 ? Math.min(waitTimeout, 120) : waitTimeout;
-      log.info(`Waiting for ${round > 1 ? 'new ' : ''}review... (timeout: ${effectiveTimeout}s)`);
-      gotReview = await waitForReview(projectDir, prInfo.number, pollInterval, effectiveTimeout);
-    }
-
-    if (!gotReview) {
-      // Before giving up, do one last proactive check
-      const lastChance = github.getLatestReviewState(projectDir, prInfo.number);
-      if (lastChance === 'APPROVED') {
-        log.info('✅ Review approved (found on final check)!');
-        return;
-      }
-      const lastFeedback = github.collectReviewFeedback(projectDir, prInfo.number);
-      if (lastFeedback) {
-        log.info('Found existing feedback — processing');
-        gotReview = true;
-      }
-    }
-
-    if (!gotReview) {
-      pollRetries++;
-      if (pollRetries >= MAX_POLL_RETRIES) {
-        log.error(`Review polling timed out ${MAX_POLL_RETRIES} times — marking task as blocked`);
-        task.status = 'blocked';
-        task.block_reason = 'review_timeout';
-        return;
-      }
-      log.warn(`Review wait timed out — auto-retrying (${pollRetries}/${MAX_POLL_RETRIES})...`);
-      round--; // retry same round
-      continue;
-    }
-    pollRetries = 0; // reset on success
-
-    // Step: Feedback received
-    checkpoint.saveStep(task.id, 'review', 'feedback_received', {
-      branch: task.branch,
-      current_pr: prInfo.number,
-      review_round: round,
-    });
-
-    // Check review status
-    const reviewState = github.getLatestReviewState(projectDir, prInfo.number);
-    log.info(`Review status: ${reviewState}`);
-
-    if (reviewState === 'APPROVED') {
-      log.info('✅ Review approved!');
-      return;
-    }
-
-    // Collect review feedback (raw — classification done by AI)
-    const feedback = github.collectReviewFeedback(projectDir, prInfo.number);
-    if (!feedback) {
-      log.info('No review feedback found — proceeding ✅');
-      return;
-    }
-
-    // Use AI to classify the review feedback
-    log.info('Classifying review feedback via AI...');
-    const classification = await provider.classifyReview(providerId, feedback, projectDir);
-
-    if (classification === 'pass') {
-      log.info('AI determined no actionable issues — proceeding ✅');
-      return;
-    }
-
-    if (classification === null) {
-      // AI classification failed — fall back to structural GitHub API signals
-      log.dim('AI classification unavailable, using structural fallback');
-      const inlineComments = github.getReviewComments(projectDir, prInfo.number);
-      const hasInlineComments = inlineComments && inlineComments.length > 0;
-
-      if (reviewState === 'CHANGES_REQUESTED') {
-        log.info('Review state: CHANGES_REQUESTED — entering fix phase');
-      } else if (reviewState === 'COMMENTED' && !hasInlineComments) {
-        log.info('COMMENTED with no inline code comments — treating as passed ✅');
-        return;
-      } else if (!hasInlineComments) {
-        log.info('No inline code comments found — treating as passed ✅');
-        return;
-      } else {
-        log.info(`Found ${inlineComments.length} inline code comment(s) — entering fix phase`);
-      }
-    }
-
-    // AI says FIX, or structural fallback indicates issues
-    log.blank();
-    log.warn(`Received review feedback (round ${round}/${maxRounds})`);
-
-    if (round >= maxRounds) {
-      if (maxRounds < HARD_MAX_ROUNDS) {
-        // Auto-extend: give it one more round
-        maxRounds++;
-        log.warn(`Auto-extending fix rounds to ${maxRounds}`);
-      } else {
-        // Hard limit reached — cannot keep fixing forever
-        log.error(`Hard limit of ${HARD_MAX_ROUNDS} fix rounds reached — marking task as blocked`);
-        log.error('This task needs manual intervention to resolve review issues');
-        task.status = 'blocked';
-        return;
-      }
-    }
-
-    // Let AI fix based on the specific review feedback
-    await fixPhase(projectDir, task, feedback, round, providerId);
-
-    // Step: Fix applied
-    checkpoint.saveStep(task.id, 'review', 'fix_applied', {
-      branch: task.branch,
-      current_pr: prInfo.number,
-      review_round: round,
-    });
-
-    // Push fix — only if there are actual changes
-    if (!git.isClean(projectDir)) {
-      const skipCI = isPrivate ? ' [skip ci]' : '';
-      git.commitAll(projectDir, `fix(task-${task.id}): address review comments (round ${round})${skipCI}`);
-      git.pushBranch(projectDir, task.branch);
-      log.info('Fix pushed');
-
-      // Request bot to re-review the updated code
-      log.info('Requesting re-review...');
-      github.requestReReview(projectDir, prInfo.number);
-
-      // Wait for review bot to react
-      await sleep(15000);
-    } else {
-      // AI fix produced no code changes — it cannot resolve this issue
-      log.error('AI fix produced no changes — marking task as blocked');
-      log.error('This task needs manual code changes to resolve review issues');
-      task.status = 'blocked';
-      task.block_reason = 'review_failed';
-      return;
-    }
-  }
-}
-
-async function waitForReview(projectDir, prNumber, pollInterval, timeout) {
-  let elapsed = 0;
-  const startReviewCount = github.getReviews(projectDir, prNumber).length;
-  const startCommentCount = github.getIssueComments(projectDir, prNumber).length;
-
-  // Spinner for visual feedback during polling
-  const SPINNER = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
-  let spinIdx = 0;
-  const spinTimer = setInterval(() => {
-    const frame = SPINNER[spinIdx % SPINNER.length];
-    const remaining = Math.max(0, timeout - elapsed);
-    process.stdout.write(`\r\x1b[K  \x1b[36m${frame}\x1b[0m Waiting for review... (${remaining}s remaining)`);
-    spinIdx++;
-  }, 80);
-
-  while (elapsed < timeout) {
-    await sleep(pollInterval * 1000);
-    elapsed += pollInterval;
-
-    const currentReviews = github.getReviews(projectDir, prNumber);
-    const currentComments = github.getIssueComments(projectDir, prNumber);
-
-    const hasNewReview = currentReviews.length > startReviewCount;
-    const hasNewBotComment = currentComments.length > startCommentCount &&
-      currentComments.some(c => c.user?.type === 'Bot' || c.user?.login?.includes('bot'));
-
-    if (hasNewReview || hasNewBotComment) {
-      clearInterval(spinTimer);
-      process.stdout.write('\r\x1b[K');
-      return true;
-    }
-  }
-  clearInterval(spinTimer);
-  process.stdout.write('\r\x1b[K');
-  return false;
-}
-
-// ──────────────────────────────────────────────
-// Fix phase
-// ──────────────────────────────────────────────
-async function fixPhase(projectDir, task, feedback, round, providerId) {
-  log.step(`Fixing review comments (round ${round})`);
-
-  const fixPrompt = `Please fix the following review comments on Task #${task.id}: ${task.title}
-
-## Review Feedback
-${feedback}
-
-## Requirements
-1. Fix each issue listed above
-2. Suggestions (non-blocking) can be skipped — explain why in the commit message
-3. Ensure fixes don't introduce new issues
-4. Do NOT run git add or git commit — the automation handles committing
-`;
-
-  // Save to file and execute via provider (with rate limit auto-retry)
-  const promptPath = resolve(projectDir, '.codex-copilot/_current_prompt.md');
-  writeFileSync(promptPath, fixPrompt);
-
-  let rateLimitRetries = 0;
-  while (rateLimitRetries < maxRateLimitRetries) {
-    const result = await provider.executePrompt(providerId, promptPath, projectDir);
-    if (result.ok) {
-      break;
-    }
-    if (result.rateLimited && result.retryAt) {
-      rateLimitRetries++;
-      if (rateLimitRetries >= maxRateLimitRetries) {
-        log.warn('Max rate limit retries reached during fix phase');
-        break;
-      }
-      log.warn(`Rate limit hit during fix — waiting for reset...`);
-      await waitForRateLimitReset(result.retryAt, result.retryAtStr);
-      log.info('Rate limit reset — retrying fix...');
-      continue;
-    }
-    break; // Non-rate-limit failure
-  }
-  log.info('Fix complete');
-}
-
-// ──────────────────────────────────────────────
-// Phase 4: Merge
-// ──────────────────────────────────────────────
-async function mergePhase(projectDir, task, prInfo, baseBranch, checkpoint) {
-  log.step('Phase 4/4: Merge PR');
-
-  // Skip merge if task was blocked during review
-  if (task.status === 'blocked') {
-    log.warn(`Task #${task.id} is blocked — skipping merge`);
-    return;
-  }
-
-  log.info(`Auto-merging PR #${prInfo.number}...`);
-
-  let merged = false;
-  for (let attempt = 1; attempt <= 3; attempt++) {
-    try {
-      github.mergePR(projectDir, prInfo.number);
-      log.info(`PR #${prInfo.number} merged ✅`);
-      merged = true;
-      break;
-    } catch (err) {
-      log.warn(`Merge attempt ${attempt}/3 failed: ${err.message}`);
-      if (attempt < 3) {
-        log.info('Retrying in 10s...');
-        await sleep(10000);
-      }
-    }
-  }
-
-  if (!merged) {
-    log.error('Merge failed after 3 attempts — marking task as blocked');
-    task.status = 'blocked';
-    task.block_reason = 'merge_failed';
-    return;
-  }
-
-  checkpoint.saveStep(task.id, 'merge', 'merged', {
-    branch: task.branch,
-    current_pr: prInfo.number,
-  });
-
-  // Switch back to main branch
-  git.checkoutMain(projectDir, baseBranch);
-}
-
-// ──────────────────────────────────────────────
-// Pre-flight: ensure base branch has commits & is pushed
-// ──────────────────────────────────────────────
-async function ensureBaseReady(projectDir, baseBranch, isPrivate = false) {
-  const skipCI = isPrivate ? ' [skip ci]' : '';
-  // Check if the repo has any commits at all
-  const hasCommits = git.execSafe('git rev-parse HEAD', projectDir);
-  if (!hasCommits.ok) {
-    // No commits yet — brand new repo
-    log.warn('No commits found in repository');
-    if (!git.isClean(projectDir)) {
-      log.info('Creating initial commit from existing code...');
-      git.commitAll(projectDir, `chore: initial commit${skipCI}`);
-      log.info('✅ Initial commit created');
-    } else {
-      log.warn('Repository is empty — no files to commit');
-      return;
-    }
-  } else {
-    // Has commits, but base branch might have uncommitted changes
-    const currentBranch = git.currentBranch(projectDir);
-    if (currentBranch === baseBranch && !git.isClean(projectDir)) {
-      log.info('Uncommitted changes on base branch, committing first...');
-      git.commitAll(projectDir, `chore: save current progress before automation${skipCI}`);
-      log.info('✅ Base branch changes committed');
-    }
-  }
-
-  // Ensure we're on the base branch
-  const currentBranch = git.currentBranch(projectDir);
-  if (currentBranch !== baseBranch) {
-    // If base branch doesn't exist locally, create it from current
-    const branchExists = git.execSafe(`git rev-parse --verify ${baseBranch}`, projectDir);
-    if (!branchExists.ok) {
-      log.info(`Creating base branch '${baseBranch}' from current branch...`);
-      git.execSafe(`git branch ${baseBranch}`, projectDir);
-    }
-  }
-
-  // Ensure base branch is pushed to remote
-  github.ensureRemoteBranch(projectDir, baseBranch);
-  log.info(`Base branch '${baseBranch}' ready ✓`);
-}
-
-function buildDevPrompt(task, projectDir) {
-  const acceptanceList = Array.isArray(task.acceptance) && task.acceptance.length > 0
-    ? task.acceptance.map(a => `- ${a}`).join('\n')
-    : '- Feature works correctly';
-
-  let retrySection = '';
-  if (projectDir) {
-    const retryContextPath = resolve(projectDir, `.codex-copilot/retry_context/${task.id}.md`);
-    if (existsSync(retryContextPath)) {
-      const retryContext = readFileSync(retryContextPath, 'utf-8');
-      retrySection = `\n## ⚠️ Retry Context (from previous failed attempt)\n${retryContext}\n`;
-    }
-  }
-
-  return `Please complete the following development task:
-
-## Task #${task.id}: ${task.title}
-
-${task.description}
-${retrySection}
-## Acceptance Criteria
-${acceptanceList}
-
-## Requirements
-1. Strictly follow the project's existing code style and tech stack
-2. Ensure the code compiles/runs correctly when done
-3. Do NOT run git add or git commit — the automation handles committing
-`;
-}
-
-function sleep(ms) {
-  return new Promise(resolve => setTimeout(resolve, ms));
-}
-
-/**
- * Wait for rate limit reset with countdown display.
- * @param {Date} retryAt - When to resume
- * @param {string} retryAtStr - Human-readable time string
- */
-async function waitForRateLimitReset(retryAt, retryAtStr) {
-  const SPINNER = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
-  let spinIdx = 0;
-
-  log.blank();
-  log.info(`⏳ Rate limited — auto-resuming at ${retryAtStr}`);
-  log.blank();
-
-  while (true) {
-    const now = Date.now();
-    const remaining = retryAt.getTime() - now;
-    if (remaining <= 0) break;
-
-    const mins = Math.floor(remaining / 60000);
-    const secs = Math.floor((remaining % 60000) / 1000);
-    const frame = SPINNER[spinIdx % SPINNER.length];
-    spinIdx++;
-
-    process.stdout.write(
-      `\r\x1b[K  \x1b[33m${frame}\x1b[0m Waiting for rate limit reset... \x1b[1m${mins}m ${secs}s\x1b[0m remaining`
-    );
-
-    await sleep(1000);
-  }
-
-  process.stdout.write('\r\x1b[K');
-  log.info('✅ Rate limit reset — waiting 3min buffer before resuming...');
-  // Add 3-minute buffer to ensure the limit is actually lifted
-  await sleep(180_000);
-}
-
-
-
+/**
+ * codex-copilot run - Main orchestration loop
+ * 
+ * Executes tasks one by one: Develop → PR → Review → Fix → Merge → Next
+ * Features fine-grained checkpoint/resume at every sub-step.
+ */
+
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { resolve } from 'path';
+import { log, progressBar } from '../utils/logger.js';
+import { git } from '../utils/git.js';
+import { github } from '../utils/github.js';
+import { closePrompt } from '../utils/prompt.js';
+import { createCheckpoint } from '../utils/checkpoint.js';
+import { provider } from '../utils/provider.js';
+import { readJSON, writeJSON } from '../utils/json.js';
+import { preFlightCheck, releaseLock } from '../utils/self-heal.js';
+
+const maxRateLimitRetries = 3;
+
+export async function run(projectDir) {
+  const tasksPath = resolve(projectDir, '.codex-copilot/tasks.json');
+  const configPath = resolve(projectDir, '.codex-copilot/config.json');
+  const checkpoint = createCheckpoint(projectDir);
+
+  let tasks;
+  let state;
+
+  // Load tasks.json (required)
+  try {
+    tasks = readJSON(tasksPath);
+  } catch (err) {
+    log.warn(`tasks.json read issue: ${err.message}`);
+    log.info('Attempting auto-repair...');
+
+    // Try auto-fix (deep repair + schema validation)
+    const { autoFix } = await import('./fix.js');
+    const fixResult = autoFix(projectDir, { files: ['tasks.json'] });
+
+    if (fixResult.ok && fixResult.repaired.includes('tasks.json')) {
+      try {
+        tasks = readJSON(tasksPath);
+        log.info('✅ tasks.json auto-repaired successfully');
+      } catch {
+        // Auto-fix wrote the file but it's still not readable (shouldn't happen)
+        log.error('Auto-repair wrote file but it remains unreadable');
+      }
+    }
+
+    // If still no tasks, try backup
+    if (!tasks && existsSync(tasksPath + '.bak')) {
+      log.info('Trying backup file...');
+      try {
+        tasks = readJSON(tasksPath + '.bak');
+        writeJSON(tasksPath, tasks);
+        log.info('✅ Restored tasks.json from backup');
+      } catch {
+        log.error('Backup is also corrupted');
+      }
+    }
+
+    if (!tasks) {
+      log.error('Cannot recover tasks.json. Run: codex-copilot fix');
+      closePrompt();
+      process.exit(1);
+    }
+  }
+
+  // Load state.json (optional — falls back to default)
+  try {
+    state = checkpoint.load();
+  } catch {
+    log.warn('State file corrupted — resetting to initial state');
+    state = checkpoint.reset();
+  }
+  const config = existsSync(configPath) ? readJSON(configPath) : {};
+
+  // Validate tasks.json structure
+  if (!tasks.tasks || !Array.isArray(tasks.tasks) || !tasks.total) {
+    log.error('Invalid tasks.json format: missing tasks array or total field');
+    log.warn('Please re-run codex-copilot init and let CodeX regenerate tasks.json');
+    closePrompt();
+    process.exit(1);
+  }
+
+  const baseBranch = config.base_branch || 'main';
+  const providerId = config.provider || 'codex-cli';
+  const maxReviewRounds = config.max_review_rounds || 2;
+  const pollInterval = config.review_poll_interval || 60;
+  const waitTimeout = config.review_wait_timeout || 600;
+  const isPrivate = github.isPrivateRepo(projectDir); // Cache once
+  const weeklyQuotaThreshold = config.weekly_quota_threshold || 97;
+
+  const providerInfo = provider.getProvider(providerId);
+  log.info(`AI Provider: ${providerInfo ? providerInfo.name : providerId}`);
+
+  // ===== Graceful shutdown handler =====
+  let shuttingDown = false;
+  const gracefulShutdown = () => {
+    if (shuttingDown) {
+      log.warn('Force exit');
+      process.exit(1);
+    }
+    shuttingDown = true;
+    log.blank();
+    log.warn('Interrupt received — saving checkpoint...');
+    // State is already saved at each step, just need to save tasks.json
+    writeJSON(tasksPath, tasks);
+    releaseLock(projectDir);
+    log.info('✅ Checkpoint saved. Run `codex-copilot run` to resume.');
+    log.blank();
+    closePrompt();
+    process.exit(0);
+  };
+  process.on('SIGINT', gracefulShutdown);
+  process.on('SIGTERM', gracefulShutdown);
+
+  log.title('🚀 Starting automated development loop');
+  log.blank();
+  log.info(`Project: ${tasks.project}`);
+  log.info(`Total tasks: ${tasks.total}`);
+  log.info(`Base branch: ${baseBranch}`);
+
+  // ===== Pre-flight self-healing =====
+  const health = preFlightCheck(projectDir, baseBranch, { checkpoint, tasks });
+  if (!health.ok) {
+    log.blank();
+    log.error('Pre-flight check failed — cannot proceed:');
+    for (const b of health.blockers) {
+      log.error(`  🛑 ${b}`);
+    }
+    log.blank();
+    releaseLock(projectDir);
+    closePrompt();
+    process.exit(1);
+  }
+  log.blank();
+
+  // ===== Pre-flight: ensure base branch is committed & pushed =====
+  await ensureBaseReady(projectDir, baseBranch, isPrivate);
+
+  // Show resume info if resuming mid-task
+  if (state.phase && state.current_task > 0) {
+    log.blank();
+    log.info(`⏩ Resuming task #${state.current_task} from: ${state.phase} → ${state.phase_step}`);
+  }
+
+  // ===== Auto-retry blocked tasks =====
+  // On each run, reset blocked tasks to pending so they're retried in order.
+  // Branches and checkpoint steps are PRESERVED — the task resumes from where
+  // it left off, keeping all previously developed code.
+  const blockedTasks = tasks.tasks.filter(t => t.status === 'blocked');
+  if (blockedTasks.length > 0) {
+    log.blank();
+    log.info(`🔄 Auto-retrying ${blockedTasks.length} blocked task(s)...`);
+    for (const bt of blockedTasks) {
+      bt.status = 'pending';
+      bt.retry_count = (bt.retry_count || 0) + 1;
+      bt._retrying = true; // Flag: don't skip even if below checkpoint
+      log.dim(`   ↳ Task #${bt.id}: ${bt.title.substring(0, 50)} (attempt ${bt.retry_count + 1})`);
+    }
+    writeJSON(tasksPath, tasks);
+  }
+
+  const completedCount = tasks.tasks.filter(t => t.status === 'completed').length;
+  log.blank();
+  progressBar(completedCount, tasks.total, `${completedCount}/${tasks.total} tasks done`);
+  log.blank();
+
+  // Execute tasks one by one
+  for (const task of tasks.tasks) {
+    // Skip fully completed tasks
+    if (task.status === 'completed' || task.status === 'skipped') continue;
+
+    // Skip tasks whose ID is below the checkpoint (unless retrying a blocked task)
+    const isResumingTask = state.current_task === task.id && state.phase;
+    if (task.id < state.current_task && !isResumingTask && !task._retrying) continue;
+
+    // Clean up retry flag (used only to bypass checkpoint skip)
+    delete task._retrying;
+
+    log.blank();
+    log.title(`━━━ Task ${task.id}/${tasks.total}: ${task.title} ━━━`);
+    log.blank();
+
+    // ===== Quota pre-check (Codex CLI only) =====
+    if (providerId === 'codex-cli' || providerId === 'codex-desktop') {
+      const quota = provider.checkQuotaBeforeExecution(weeklyQuotaThreshold);
+      if (!quota.ok) {
+        log.blank();
+        log.error(`⚠ Weekly quota at ${quota.quota7d}% (threshold: ${weeklyQuotaThreshold}%) — stopping to preserve remaining quota`);
+        log.info('Run `codex-copilot usage` to check quota details');
+        log.info('Run `codex-copilot run` again when quota resets');
+        writeJSON(tasksPath, tasks);
+        closePrompt();
+        process.exit(0);
+      }
+      if (quota.warning) {
+        log.warn(`⚠ Weekly quota at ${quota.quota7d}% — approaching limit`);
+      }
+    }
+
+    // Check dependencies — completed, skipped, and blocked all satisfy dependencies.
+    // Blocked tasks are treated as "done for now" to prevent cascade-skipping;
+    // the user can retry them later with `codex-copilot retry`.
+    if (task.depends_on && task.depends_on.length > 0) {
+      const DONE_STATUSES = ['completed', 'skipped', 'blocked'];
+      const unfinished = task.depends_on.filter(dep => {
+        const depTask = tasks.tasks.find(t => t.id === dep);
+        return depTask && !DONE_STATUSES.includes(depTask.status);
+      });
+      if (unfinished.length > 0) {
+        log.warn(`Unfinished dependencies: ${unfinished.join(', ')} — skipping`);
+        continue;
+      }
+      // Warn about blocked deps but still proceed
+      const blockedDeps = task.depends_on.filter(dep => {
+        const depTask = tasks.tasks.find(t => t.id === dep);
+        return depTask && depTask.status === 'blocked';
+      });
+      if (blockedDeps.length > 0) {
+        log.warn(`⚠ Dependencies ${blockedDeps.join(', ')} are blocked — proceeding anyway`);
+      }
+    }
+
+    // ===== Ensure task has all required fields =====
+    // Auto-generate branch name if missing (common after corruption recovery)
+    if (!task.branch) {
+      // Try to recover from checkpoint state
+      if (state.current_task === task.id && state.branch) {
+        task.branch = state.branch;
+        log.dim(`  ↳ Recovered branch name from checkpoint: ${task.branch}`);
+      } else {
+        const slug = (task.title || `task-${task.id}`)
+          .toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').substring(0, 40);
+        task.branch = `feature/${String(task.id).padStart(3, '0')}-${slug}`;
+        log.dim(`  ↳ Generated branch name: ${task.branch}`);
+      }
+    }
+    if (!task.depends_on) task.depends_on = [];
+    if (!task.acceptance) task.acceptance = [];
+    if (!task.description) task.description = task.title;
+
+    // Mark task as in_progress
+    task.status = 'in_progress';
+    const isRetry = (task.retry_count || 0) > 0;
+    const retryStartedAt = isRetry ? new Date().toISOString() : null;
+    writeJSON(tasksPath, tasks);
+
+    // ===== Phase 1: Develop =====
+    if (!checkpoint.isStepDone(task.id, 'develop', 'codex_complete')) {
+      await developPhase(projectDir, task, baseBranch, checkpoint, providerId);
+      // If dev phase failed, mark blocked and skip to next task
+      if (task.status === 'blocked') {
+        writeJSON(tasksPath, tasks);
+        log.blank();
+        log.warn(`⚠ Task #${task.id} is blocked — AI development failed`);
+        continue;
+      }
+    } else {
+      log.dim('⏩ Skipping develop phase (already completed)');
+    }
+
+    // ===== Phase 2: Create PR =====
+    let prInfo;
+    if (!checkpoint.isStepDone(task.id, 'pr', 'pr_created')) {
+      prInfo = await prPhase(projectDir, task, baseBranch, checkpoint, isPrivate);
+    } else {
+      // PR already created, load from state
+      state = checkpoint.load();
+      prInfo = { number: state.current_pr, url: '' };
+      log.dim(`⏩ Skipping PR phase (PR #${prInfo.number} already created)`);
+    }
+
+    // ===== Phase 3: Review loop =====
+    if (!checkpoint.isStepDone(task.id, 'merge', 'merged')) {
+      // On retry: request fresh re-review since old reviews may be stale
+      if (isRetry && prInfo?.number) {
+        log.info('🔄 Retry: requesting fresh re-review on existing PR...');
+        try {
+          github.requestReReview(projectDir, prInfo.number);
+        } catch { /* ignore — review bots may not be configured */ }
+      }
+
+      await reviewLoop(projectDir, task, prInfo, {
+        maxRounds: maxReviewRounds,
+        pollInterval,
+        waitTimeout,
+        retryStartedAt, // Only count reviews after this timestamp
+      }, checkpoint, providerId, isPrivate);
+    } else {
+      log.dim('⏩ Skipping review phase (already completed)');
+    }
+
+    // ===== Phase 4: Merge =====
+    if (!checkpoint.isStepDone(task.id, 'merge', 'merged')) {
+      await mergePhase(projectDir, task, prInfo, baseBranch, checkpoint);
+    } else {
+      // Checkpoint says merged — verify against GitHub
+      if (prInfo?.number) {
+        const prState = github.getPRState(projectDir, prInfo.number);
+        if (prState !== 'merged') {
+          log.warn(`⚠ Checkpoint says merged but PR #${prInfo.number} is ${prState} — re-entering merge`);
+          await mergePhase(projectDir, task, prInfo, baseBranch, checkpoint);
+        } else {
+          log.dim('⏩ Skipping merge phase (PR confirmed merged on GitHub)');
+        }
+      } else {
+        log.dim('⏩ Skipping merge phase (already merged)');
+      }
+    }
+
+    // Check if task was blocked during review/merge
+    if (task.status === 'blocked') {
+      writeJSON(tasksPath, tasks);
+      log.blank();
+      log.warn(`⚠ Task #${task.id} is blocked — needs manual intervention`);
+      log.blank();
+      const done = tasks.tasks.filter(t => t.status === 'completed').length;
+      const blocked = tasks.tasks.filter(t => t.status === 'blocked').length;
+      progressBar(done, tasks.total, `${done}/${tasks.total} done, ${blocked} blocked`);
+      continue;
+    }
+
+    // Mark task complete
+    task.status = 'completed';
+    delete task.block_reason;
+    delete task.retry_count;
+    writeJSON(tasksPath, tasks);
+    checkpoint.completeTask(task.id);
+
+    log.blank();
+    const done = tasks.tasks.filter(t => t.status === 'completed').length;
+    progressBar(done, tasks.total, `${done}/${tasks.total} tasks done`);
+    log.info(`✅ Task #${task.id} complete!`);
+  }
+
+  log.blank();
+  const finalDone = tasks.tasks.filter(t => t.status === 'completed').length;
+  const finalBlocked = tasks.tasks.filter(t => t.status === 'blocked').length;
+  if (finalBlocked > 0) {
+    log.title(`✅ Finished — ${finalDone}/${tasks.total} done, ${finalBlocked} blocked`);
+  } else {
+    log.title('🎉 All tasks complete!');
+  }
+  log.blank();
+  process.removeListener('SIGINT', gracefulShutdown);
+  process.removeListener('SIGTERM', gracefulShutdown);
+  releaseLock(projectDir);
+
+  // ===== Auto-evolve: trigger next round if enabled =====
+  if (config.auto_evolve !== false) {
+    log.blank();
+    log.info('🔄 Auto-evolving to next round...');
+    log.blank();
+    const { evolve } = await import('./evolve.js');
+    await evolve(projectDir);
+    return; // evolve() calls run() internally
+  }
+
+  closePrompt();
+}
+
+// ──────────────────────────────────────────────
+// Phase 1: Develop
+// ──────────────────────────────────────────────
+async function developPhase(projectDir, task, baseBranch, checkpoint, providerId) {
+  log.step('Phase 1/4: Develop');
+
+  // Step 1: Switch to feature branch
+  if (!checkpoint.isStepDone(task.id, 'develop', 'branch_created')) {
+    try {
+      git.checkoutBranch(projectDir, task.branch, baseBranch);
+    } catch (err) {
+      log.error(`Failed to switch to branch ${task.branch}: ${err.message}`);
+      task.status = 'blocked';
+      task.block_reason = 'git_checkout_failed';
+      return;
+    }
+    log.info(`Switched to branch: ${task.branch}`);
+    checkpoint.saveStep(task.id, 'develop', 'branch_created', { branch: task.branch });
+  } else {
+    // Ensure we're on the right branch
+    const current = git.currentBranch(projectDir);
+    if (current !== task.branch) {
+      try {
+        git.checkoutBranch(projectDir, task.branch, baseBranch);
+      } catch (err) {
+        log.error(`Failed to switch to branch ${task.branch}: ${err.message}`);
+        task.status = 'blocked';
+        task.block_reason = 'git_checkout_failed';
+        return;
+      }
+    }
+    log.dim('⏩ Branch already created');
+  }
+
+  // Step 2: Build development prompt
+  if (!checkpoint.isStepDone(task.id, 'develop', 'prompt_ready')) {
+    const devPrompt = buildDevPrompt(task, projectDir);
+    const promptPath = resolve(projectDir, '.codex-copilot/_current_prompt.md');
+    writeFileSync(promptPath, devPrompt);
+    checkpoint.saveStep(task.id, 'develop', 'prompt_ready', { branch: task.branch });
+    log.info('Development prompt generated');
+  } else {
+    log.dim('⏩ Prompt already generated');
+  }
+
+  // Step 3: Execute via AI Provider (with rate limit auto-retry + timeout protection)
+  if (!checkpoint.isStepDone(task.id, 'develop', 'codex_complete')) {
+    const promptPath = resolve(projectDir, '.codex-copilot/_current_prompt.md');
+    let rateLimitRetries = 0;
+    const AI_TIMEOUT_MS = 30 * 60 * 1000; // D4: 30 minute timeout for AI execution
+
+    while (rateLimitRetries < maxRateLimitRetries) {
+      // D4: Race the AI execution against a timeout to prevent infinite hangs
+      const timeoutPromise = new Promise((_, reject) =>
+        setTimeout(() => reject(new Error('AI_TIMEOUT')), AI_TIMEOUT_MS)
+      );
+
+      let result;
+      try {
+        result = await Promise.race([
+          provider.executePrompt(providerId, promptPath, projectDir),
+          timeoutPromise,
+        ]);
+      } catch (timeoutErr) {
+        if (timeoutErr.message === 'AI_TIMEOUT') {
+          log.error(`AI provider timed out after ${AI_TIMEOUT_MS / 60000} minutes — marking task as blocked`);
+          task.status = 'blocked';
+          task.block_reason = 'ai_timeout';
+          return;
+        }
+        throw timeoutErr;
+      }
+
+      if (result.ok) {
+        log.info('Development complete');
+        checkpoint.saveStep(task.id, 'develop', 'codex_complete', { branch: task.branch });
+        break;
+      }
+
+      if (result.rateLimited && result.retryAt) {
+        rateLimitRetries++;
+        log.warn(`Rate limit hit (attempt ${rateLimitRetries}/${maxRateLimitRetries})`);
+        if (rateLimitRetries >= maxRateLimitRetries) {
+          log.error('Max rate limit retries reached — marking task as blocked');
+          task.status = 'blocked';
+          task.block_reason = 'rate_limited';
+          return;
+        }
+        await waitForRateLimitReset(result.retryAt, result.retryAtStr);
+        log.info('Rate limit reset — resuming development...');
+        continue;
+      }
+
+      // Non-rate-limit failure
+      log.error('AI development failed — marking task as blocked');
+      task.status = 'blocked';
+      task.block_reason = 'dev_failed';
+      return;
+    }
+  }
+}
+
+// ──────────────────────────────────────────────
+// Phase 2: Create PR
+// ──────────────────────────────────────────────
+async function prPhase(projectDir, task, baseBranch, checkpoint, isPrivate) {
+  log.step('Phase 2/4: Submit PR');
+
+  // Step 1: Commit changes
+  if (!checkpoint.isStepDone(task.id, 'pr', 'committed')) {
+    if (!git.isClean(projectDir)) {
+      log.info('Uncommitted changes detected, auto-committing...');
+      const skipCI = isPrivate ? ' [skip ci]' : '';
+      git.commitAll(projectDir, `feat(task-${task.id}): ${task.title}${skipCI}`);
+    }
+    checkpoint.saveStep(task.id, 'pr', 'committed', { branch: task.branch });
+    log.info('Changes committed');
+  } else {
+    log.dim('⏩ Changes already committed');
+  }
+
+  // Step 2: Push
+  if (!checkpoint.isStepDone(task.id, 'pr', 'pushed')) {
+    git.pushBranch(projectDir, task.branch);
+    checkpoint.saveStep(task.id, 'pr', 'pushed', { branch: task.branch });
+    log.info('Code pushed');
+  } else {
+    log.dim('⏩ Code already pushed');
+  }
+
+  // Step 3: Create PR
+  if (!checkpoint.isStepDone(task.id, 'pr', 'pr_created')) {
+    const acceptanceList = Array.isArray(task.acceptance) && task.acceptance.length > 0
+      ? task.acceptance.map(a => `- [ ] ${a}`).join('\n')
+      : '- [ ] Feature works correctly';
+    const prBody = `## Task #${task.id}: ${task.title}\n\n${task.description}\n\n### Acceptance Criteria\n${acceptanceList}\n\n---\n*Auto-created by Codex-Copilot*`;
+
+    // Use auto-recovery: create → find existing → fix remote → retry
+    const prInfo = github.createPRWithRecovery(projectDir, {
+      title: `feat(task-${task.id}): ${task.title}`,
+      body: prBody,
+      base: baseBranch,
+      head: task.branch,
+    });
+    log.info(`PR ready: #${prInfo.number} ${prInfo.url}`);
+
+    checkpoint.saveStep(task.id, 'pr', 'pr_created', {
+      branch: task.branch,
+      current_pr: prInfo.number,
+    });
+    return prInfo;
+  }
+
+  // If we get here, PR was already created — load from state
+  const state = checkpoint.load();
+  return { number: state.current_pr, url: '' };
+}
+
+// ──────────────────────────────────────────────
+// Phase 3: Review loop
+// ──────────────────────────────────────────────
+async function reviewLoop(projectDir, task, prInfo, { maxRounds: _maxRounds, pollInterval, waitTimeout, retryStartedAt }, checkpoint, providerId, isPrivate) {
+  const HARD_MAX_ROUNDS = 5;
+  const MAX_POLL_RETRIES = 3;
+  let maxRounds = Math.min(_maxRounds, HARD_MAX_ROUNDS);
+  log.step('Phase 3/4: Waiting for review');
+
+  // Resume from saved review round
+  const state = checkpoint.load();
+  const startRound = (state.current_task === task.id && state.review_round > 0)
+    ? state.review_round
+    : 1;
+
+  let pollRetries = 0;
+
+  for (let round = startRound; round <= maxRounds; round++) {
+    // Step: Waiting for review
+    checkpoint.saveStep(task.id, 'review', 'waiting_review', {
+      branch: task.branch,
+      current_pr: prInfo.number,
+      review_round: round,
+    });
+
+    log.info('Checking for review feedback...');
+
+    let gotReview = false;
+
+    // Always proactively check for existing reviews first.
+    // This catches: already-posted bot reviews, stale reviews found on resume,
+    // and fast bot responses after fix pushes.
+    const existingReviews = github.getReviews(projectDir, prInfo.number);
+    const existingComments = github.getIssueComments(projectDir, prInfo.number);
+
+    // On retry: only count reviews posted AFTER the retry started
+    const isReviewFresh = (item) => {
+      if (!retryStartedAt) return true; // Not a retry — all reviews are valid
+      const itemDate = item.submitted_at || item.created_at || item.updated_at;
+      return itemDate && new Date(itemDate) > new Date(retryStartedAt);
+    };
+
+    const freshReviews = existingReviews.filter(isReviewFresh);
+    const freshComments = existingComments.filter(isReviewFresh);
+
+    const hasReview = freshReviews.some(r => r.state !== 'PENDING');
+    const hasBotComment = freshComments.some(c =>
+      c.user?.type === 'Bot' || c.user?.login?.includes('bot')
+    );
+
+    if (hasReview || hasBotComment) {
+      log.info('Review found — processing immediately');
+      gotReview = true;
+    }
+
+    if (!gotReview) {
+      // After fix pushes (round > 1), bot should respond quickly if configured.
+      // Use shorter timeout to avoid wasting 10+ minutes waiting for nothing.
+      const effectiveTimeout = round > 1 ? Math.min(waitTimeout, 120) : waitTimeout;
+      log.info(`Waiting for ${round > 1 ? 'new ' : ''}review... (timeout: ${effectiveTimeout}s)`);
+      gotReview = await waitForReview(projectDir, prInfo.number, pollInterval, effectiveTimeout);
+    }
+
+    if (!gotReview) {
+      // Before giving up, do one last proactive check
+      const lastChance = github.getLatestReviewState(projectDir, prInfo.number);
+      if (lastChance === 'APPROVED') {
+        log.info('✅ Review approved (found on final check)!');
+        return;
+      }
+      const lastFeedback = github.collectReviewFeedback(projectDir, prInfo.number);
+      if (lastFeedback) {
+        log.info('Found existing feedback — processing');
+        gotReview = true;
+      }
+    }
+
+    if (!gotReview) {
+      pollRetries++;
+      if (pollRetries >= MAX_POLL_RETRIES) {
+        log.error(`Review polling timed out ${MAX_POLL_RETRIES} times — marking task as blocked`);
+        task.status = 'blocked';
+        task.block_reason = 'review_timeout';
+        return;
+      }
+      log.warn(`Review wait timed out — auto-retrying (${pollRetries}/${MAX_POLL_RETRIES})...`);
+      round--; // retry same round
+      continue;
+    }
+    pollRetries = 0; // reset on success
+
+    // Step: Feedback received
+    checkpoint.saveStep(task.id, 'review', 'feedback_received', {
+      branch: task.branch,
+      current_pr: prInfo.number,
+      review_round: round,
+    });
+
+    // Check review status
+    const reviewState = github.getLatestReviewState(projectDir, prInfo.number);
+    log.info(`Review status: ${reviewState}`);
+
+    if (reviewState === 'APPROVED') {
+      log.info('✅ Review approved!');
+      return;
+    }
+
+    // Collect review feedback (raw — classification done by AI)
+    const feedback = github.collectReviewFeedback(projectDir, prInfo.number);
+    if (!feedback) {
+      log.info('No review feedback found — proceeding ✅');
+      return;
+    }
+
+    // Use AI to classify the review feedback
+    log.info('Classifying review feedback via AI...');
+    const classification = await provider.classifyReview(providerId, feedback, projectDir);
+
+    if (classification === 'pass') {
+      log.info('AI determined no actionable issues — proceeding ✅');
+      return;
+    }
+
+    if (classification === null) {
+      // AI classification failed — fall back to structural GitHub API signals
+      log.dim('AI classification unavailable, using structural fallback');
+      const inlineComments = github.getReviewComments(projectDir, prInfo.number);
+      const hasInlineComments = inlineComments && inlineComments.length > 0;
+
+      if (reviewState === 'CHANGES_REQUESTED') {
+        log.info('Review state: CHANGES_REQUESTED — entering fix phase');
+      } else if (reviewState === 'COMMENTED' && !hasInlineComments) {
+        log.info('COMMENTED with no inline code comments — treating as passed ✅');
+        return;
+      } else if (!hasInlineComments) {
+        log.info('No inline code comments found — treating as passed ✅');
+        return;
+      } else {
+        log.info(`Found ${inlineComments.length} inline code comment(s) — entering fix phase`);
+      }
+    }
+
+    // AI says FIX, or structural fallback indicates issues
+    log.blank();
+    log.warn(`Received review feedback (round ${round}/${maxRounds})`);
+
+    if (round >= maxRounds) {
+      if (maxRounds < HARD_MAX_ROUNDS) {
+        // Auto-extend: give it one more round
+        maxRounds++;
+        log.warn(`Auto-extending fix rounds to ${maxRounds}`);
+      } else {
+        // Hard limit reached — cannot keep fixing forever
+        log.error(`Hard limit of ${HARD_MAX_ROUNDS} fix rounds reached — marking task as blocked`);
+        log.error('This task needs manual intervention to resolve review issues');
+        task.status = 'blocked';
+        return;
+      }
+    }
+
+    // Let AI fix based on the specific review feedback
+    await fixPhase(projectDir, task, feedback, round, providerId);
+
+    // Step: Fix applied
+    checkpoint.saveStep(task.id, 'review', 'fix_applied', {
+      branch: task.branch,
+      current_pr: prInfo.number,
+      review_round: round,
+    });
+
+    // Push fix — only if there are actual changes
+    if (!git.isClean(projectDir)) {
+      const skipCI = isPrivate ? ' [skip ci]' : '';
+      git.commitAll(projectDir, `fix(task-${task.id}): address review comments (round ${round})${skipCI}`);
+      git.pushBranch(projectDir, task.branch);
+      log.info('Fix pushed');
+
+      // Request bot to re-review the updated code
+      log.info('Requesting re-review...');
+      github.requestReReview(projectDir, prInfo.number);
+
+      // Wait for review bot to react
+      await sleep(15000);
+    } else {
+      // AI fix produced no code changes — it cannot resolve this issue
+      log.error('AI fix produced no changes — marking task as blocked');
+      log.error('This task needs manual code changes to resolve review issues');
+      task.status = 'blocked';
+      task.block_reason = 'review_failed';
+      return;
+    }
+  }
+}
+
+async function waitForReview(projectDir, prNumber, pollInterval, timeout) {
+  let elapsed = 0;
+  const startReviewCount = github.getReviews(projectDir, prNumber).length;
+  const startCommentCount = github.getIssueComments(projectDir, prNumber).length;
+
+  // Spinner for visual feedback during polling
+  const SPINNER = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+  let spinIdx = 0;
+  const spinTimer = setInterval(() => {
+    const frame = SPINNER[spinIdx % SPINNER.length];
+    const remaining = Math.max(0, timeout - elapsed);
+    process.stdout.write(`\r\x1b[K  \x1b[36m${frame}\x1b[0m Waiting for review... (${remaining}s remaining)`);
+    spinIdx++;
+  }, 80);
+
+  while (elapsed < timeout) {
+    await sleep(pollInterval * 1000);
+    elapsed += pollInterval;
+
+    const currentReviews = github.getReviews(projectDir, prNumber);
+    const currentComments = github.getIssueComments(projectDir, prNumber);
+
+    const hasNewReview = currentReviews.length > startReviewCount;
+    const hasNewBotComment = currentComments.length > startCommentCount &&
+      currentComments.some(c => c.user?.type === 'Bot' || c.user?.login?.includes('bot'));
+
+    if (hasNewReview || hasNewBotComment) {
+      clearInterval(spinTimer);
+      process.stdout.write('\r\x1b[K');
+      return true;
+    }
+  }
+  clearInterval(spinTimer);
+  process.stdout.write('\r\x1b[K');
+  return false;
+}
+
+// ──────────────────────────────────────────────
+// Fix phase
+// ──────────────────────────────────────────────
+async function fixPhase(projectDir, task, feedback, round, providerId) {
+  log.step(`Fixing review comments (round ${round})`);
+
+  const fixPrompt = `Please fix the following review comments on Task #${task.id}: ${task.title}
+
+## Review Feedback
+${feedback}
+
+## Requirements
+1. Fix each issue listed above
+2. Suggestions (non-blocking) can be skipped — explain why in the commit message
+3. Ensure fixes don't introduce new issues
+4. Do NOT run git add or git commit — the automation handles committing
+`;
+
+  // Save to file and execute via provider (with rate limit auto-retry)
+  const promptPath = resolve(projectDir, '.codex-copilot/_current_prompt.md');
+  writeFileSync(promptPath, fixPrompt);
+
+  let rateLimitRetries = 0;
+  while (rateLimitRetries < maxRateLimitRetries) {
+    const result = await provider.executePrompt(providerId, promptPath, projectDir);
+    if (result.ok) {
+      break;
+    }
+    if (result.rateLimited && result.retryAt) {
+      rateLimitRetries++;
+      if (rateLimitRetries >= maxRateLimitRetries) {
+        log.warn('Max rate limit retries reached during fix phase');
+        break;
+      }
+      log.warn(`Rate limit hit during fix — waiting for reset...`);
+      await waitForRateLimitReset(result.retryAt, result.retryAtStr);
+      log.info('Rate limit reset — retrying fix...');
+      continue;
+    }
+    break; // Non-rate-limit failure
+  }
+  log.info('Fix complete');
+}
+
+// ──────────────────────────────────────────────
+// Phase 4: Merge
+// ──────────────────────────────────────────────
+async function mergePhase(projectDir, task, prInfo, baseBranch, checkpoint) {
+  log.step('Phase 4/4: Merge PR');
+
+  // Skip merge if task was blocked during review
+  if (task.status === 'blocked') {
+    log.warn(`Task #${task.id} is blocked — skipping merge`);
+    return;
+  }
+
+  log.info(`Auto-merging PR #${prInfo.number}...`);
+
+  let merged = false;
+  for (let attempt = 1; attempt <= 3; attempt++) {
+    try {
+      github.mergePR(projectDir, prInfo.number);
+      log.info(`PR #${prInfo.number} merged ✅`);
+      merged = true;
+      break;
+    } catch (err) {
+      log.warn(`Merge attempt ${attempt}/3 failed: ${err.message}`);
+      if (attempt < 3) {
+        log.info('Retrying in 10s...');
+        await sleep(10000);
+      }
+    }
+  }
+
+  if (!merged) {
+    log.error('Merge failed after 3 attempts — marking task as blocked');
+    task.status = 'blocked';
+    task.block_reason = 'merge_failed';
+    return;
+  }
+
+  checkpoint.saveStep(task.id, 'merge', 'merged', {
+    branch: task.branch,
+    current_pr: prInfo.number,
+  });
+
+  // Switch back to main branch
+  git.checkoutMain(projectDir, baseBranch);
+}
+
+// ──────────────────────────────────────────────
+// Pre-flight: ensure base branch has commits & is pushed
+// ──────────────────────────────────────────────
+async function ensureBaseReady(projectDir, baseBranch, isPrivate = false) {
+  const skipCI = isPrivate ? ' [skip ci]' : '';
+  // Check if the repo has any commits at all
+  const hasCommits = git.execSafe('git rev-parse HEAD', projectDir);
+  if (!hasCommits.ok) {
+    // No commits yet — brand new repo
+    log.warn('No commits found in repository');
+    if (!git.isClean(projectDir)) {
+      log.info('Creating initial commit from existing code...');
+      git.commitAll(projectDir, `chore: initial commit${skipCI}`);
+      log.info('✅ Initial commit created');
+    } else {
+      log.warn('Repository is empty — no files to commit');
+      return;
+    }
+  } else {
+    // Has commits, but base branch might have uncommitted changes
+    const currentBranch = git.currentBranch(projectDir);
+    if (currentBranch === baseBranch && !git.isClean(projectDir)) {
+      log.info('Uncommitted changes on base branch, committing first...');
+      git.commitAll(projectDir, `chore: save current progress before automation${skipCI}`);
+      log.info('✅ Base branch changes committed');
+    }
+  }
+
+  // Ensure we're on the base branch
+  const currentBranch = git.currentBranch(projectDir);
+  if (currentBranch !== baseBranch) {
+    // If base branch doesn't exist locally, create it from current
+    const branchExists = git.execSafe(`git rev-parse --verify ${baseBranch}`, projectDir);
+    if (!branchExists.ok) {
+      log.info(`Creating base branch '${baseBranch}' from current branch...`);
+      git.execSafe(`git branch ${baseBranch}`, projectDir);
+    }
+  }
+
+  // Ensure base branch is pushed to remote
+  github.ensureRemoteBranch(projectDir, baseBranch);
+  log.info(`Base branch '${baseBranch}' ready ✓`);
+}
+
+function buildDevPrompt(task, projectDir) {
+  const acceptanceList = Array.isArray(task.acceptance) && task.acceptance.length > 0
+    ? task.acceptance.map(a => `- ${a}`).join('\n')
+    : '- Feature works correctly';
+
+  let retrySection = '';
+  if (projectDir) {
+    const retryContextPath = resolve(projectDir, `.codex-copilot/retry_context/${task.id}.md`);
+    if (existsSync(retryContextPath)) {
+      const retryContext = readFileSync(retryContextPath, 'utf-8');
+      retrySection = `\n## ⚠️ Retry Context (from previous failed attempt)\n${retryContext}\n`;
+    }
+  }
+
+  return `Please complete the following development task:
+
+## Task #${task.id}: ${task.title}
+
+${task.description}
+${retrySection}
+## Acceptance Criteria
+${acceptanceList}
+
+## Requirements
+1. Strictly follow the project's existing code style and tech stack
+2. Ensure the code compiles/runs correctly when done
+3. Do NOT run git add or git commit — the automation handles committing
+`;
+}
+
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+/**
+ * Wait for rate limit reset with countdown display.
+ * @param {Date} retryAt - When to resume
+ * @param {string} retryAtStr - Human-readable time string
+ */
+async function waitForRateLimitReset(retryAt, retryAtStr) {
+  const SPINNER = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+  let spinIdx = 0;
+
+  log.blank();
+  log.info(`⏳ Rate limited — auto-resuming at ${retryAtStr}`);
+  log.blank();
+
+  while (true) {
+    const now = Date.now();
+    const remaining = retryAt.getTime() - now;
+    if (remaining <= 0) break;
+
+    const mins = Math.floor(remaining / 60000);
+    const secs = Math.floor((remaining % 60000) / 1000);
+    const frame = SPINNER[spinIdx % SPINNER.length];
+    spinIdx++;
+
+    process.stdout.write(
+      `\r\x1b[K  \x1b[33m${frame}\x1b[0m Waiting for rate limit reset... \x1b[1m${mins}m ${secs}s\x1b[0m remaining`
+    );
+
+    await sleep(1000);
+  }
+
+  process.stdout.write('\r\x1b[K');
+  log.info('✅ Rate limit reset — waiting 3min buffer before resuming...');
+  // Add 3-minute buffer to ensure the limit is actually lifted
+  await sleep(180_000);
+}
+
+
+