@jojonax/codex-copilot 1.4.2 → 1.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jojonax/codex-copilot",
-  "version": "1.4.2",
+  "version": "1.5.0",
   "description": "PRD-driven automated development orchestrator for CodeX / Cursor",
   "bin": {
     "codex-copilot": "./bin/cli.js"

package/src/commands/evolve.js

@@ -248,9 +248,9 @@ export async function evolve(projectDir) {
 
   // Execute via AI provider
   log.step(`Invoking AI to analyze gaps and plan Round ${nextRound}...`);
-  const ok = await provider.executePrompt(providerId, promptPath, projectDir);
+  const result = await provider.executePrompt(providerId, promptPath, projectDir);
 
-  if (!ok) {
+  if (!result.ok) {
     log.error('AI invocation failed. You can manually edit the prompt and retry.');
     closePrompt();
     process.exit(1);

package/src/commands/init.js

@@ -101,12 +101,42 @@ export async function init(projectDir) {
 
   // ===== Select AI Provider =====
   log.step('Select AI coding tool...');
+
+  // Check versions of installed CLI tools (non-blocking)
+  log.info('Checking tool versions...');
+  let versionCache = {};
+  try {
+    versionCache = provider.checkAllVersions();
+    const updatable = Object.entries(versionCache).filter(([, v]) => v.updateAvailable);
+    if (updatable.length > 0) {
+      for (const [id, v] of updatable) {
+        log.warn(`${provider.getProvider(id).name}: v${v.current} → v${v.latest} update available`);
+      }
+    } else if (Object.keys(versionCache).length > 0) {
+      log.info('All detected tools are up to date ✓');
+    }
+  } catch {
+    // Version check failed — continue normally
+  }
+
   log.blank();
-  const providerChoices = provider.buildProviderChoices();
+  const providerChoices = provider.buildProviderChoices(versionCache);
   const selectedProvider = await select('Which AI tool will you use?', providerChoices);
   const providerId = selectedProvider.value;
   const providerInfo = provider.getProvider(providerId);
   log.info(`Selected: ${providerInfo.name}`);
+
+  // Offer update if newer version available
+  const vi = versionCache[providerId];
+  if (vi && vi.updateAvailable) {
+    log.blank();
+    log.warn(`${providerInfo.name} v${vi.current} → v${vi.latest} available`);
+    const doUpdate = await confirm(`Update ${providerInfo.name} now?`);
+    if (doUpdate) {
+      provider.updateProvider(providerId);
+    }
+  }
+
   log.blank();
 
   // ===== Create .codex-copilot directory =====
@@ -194,8 +224,8 @@ You are an efficient automated development agent responsible for completing feat
     const autoparse = await confirm(`Auto-invoke ${providerInfo.name} to decompose PRD?`);
     if (autoparse) {
       log.step(`Invoking ${providerInfo.name} to decompose PRD...`);
-      const ok = await provider.executePrompt(providerId, promptPath, projectDir);
-      if (ok) {
+      const result = await provider.executePrompt(providerId, promptPath, projectDir);
+      if (result.ok) {
         log.info('PRD decomposition complete!');
       }
     } else {

package/src/commands/run.js

@@ -54,6 +54,8 @@ export async function run(projectDir) {
   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 maxRateLimitRetries = 3;
 
   const providerInfo = provider.getProvider(providerId);
   log.info(`AI Provider: ${providerInfo ? providerInfo.name : providerId}`);
@@ -85,7 +87,7 @@ export async function run(projectDir) {
   log.info(`Base branch: ${baseBranch}`);
 
   // ===== Pre-flight: ensure base branch is committed & pushed =====
-  await ensureBaseReady(projectDir, baseBranch);
+  await ensureBaseReady(projectDir, baseBranch, isPrivate);
 
   // Show resume info if resuming mid-task
   if (state.phase && state.current_task > 0) {
@@ -131,6 +133,23 @@ export async function run(projectDir) {
     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`.
@@ -156,6 +175,8 @@ export async function run(projectDir) {
 
     // 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 =====
@@ -185,10 +206,19 @@ export async function run(projectDir) {
 
     // ===== 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)');
@@ -198,7 +228,18 @@ export async function run(projectDir) {
     if (!checkpoint.isStepDone(task.id, 'merge', 'merged')) {
       await mergePhase(projectDir, task, prInfo, baseBranch, checkpoint);
     } else {
-      log.dim('⏩ Skipping merge phase (already merged)');
+      // 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
@@ -282,14 +323,34 @@ async function developPhase(projectDir, task, baseBranch, checkpoint, providerId
     log.dim('⏩ Prompt already generated');
   }
 
-  // Step 3: Execute via AI Provider
+  // Step 3: Execute via AI Provider (with rate limit auto-retry)
   if (!checkpoint.isStepDone(task.id, 'develop', 'codex_complete')) {
     const promptPath = resolve(projectDir, '.codex-copilot/_current_prompt.md');
-    const ok = await provider.executePrompt(providerId, promptPath, projectDir);
-    if (ok) {
-      log.info('Development complete');
-      checkpoint.saveStep(task.id, 'develop', 'codex_complete', { branch: task.branch });
-    } else {
+    let rateLimitRetries = 0;
+
+    while (rateLimitRetries < maxRateLimitRetries) {
+      const result = await provider.executePrompt(providerId, promptPath, projectDir);
+      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';
@@ -357,7 +418,7 @@ async function prPhase(projectDir, task, baseBranch, checkpoint, isPrivate) {
 // ──────────────────────────────────────────────
 // Phase 3: Review loop
 // ──────────────────────────────────────────────
-async function reviewLoop(projectDir, task, prInfo, { maxRounds: _maxRounds, pollInterval, waitTimeout }, checkpoint, providerId, isPrivate) {
+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);
@@ -388,8 +449,19 @@ async function reviewLoop(projectDir, task, prInfo, { maxRounds: _maxRounds, pol
     // and fast bot responses after fix pushes.
     const existingReviews = github.getReviews(projectDir, prInfo.number);
     const existingComments = github.getIssueComments(projectDir, prInfo.number);
-    const hasReview = existingReviews.some(r => r.state !== 'PENDING');
-    const hasBotComment = existingComments.some(c =>
+
+    // 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')
     );
 
@@ -592,11 +664,29 @@ ${feedback}
 4. Do NOT run git add or git commit — the automation handles committing
 `;
 
-  // Save to file and execute via provider
+  // Save to file and execute via provider (with rate limit auto-retry)
   const promptPath = resolve(projectDir, '.codex-copilot/_current_prompt.md');
   writeFileSync(promptPath, fixPrompt);
 
-  await provider.executePrompt(providerId, promptPath, projectDir);
+  let rateLimitRetries = 0;
+  while (rateLimitRetries < 3) {
+    const result = await provider.executePrompt(providerId, promptPath, projectDir);
+    if (result.ok) {
+      break;
+    }
+    if (result.rateLimited && result.retryAt) {
+      rateLimitRetries++;
+      if (rateLimitRetries >= 3) {
+        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');
 }
 
@@ -649,7 +739,8 @@ async function mergePhase(projectDir, task, prInfo, baseBranch, checkpoint) {
 // ──────────────────────────────────────────────
 // Pre-flight: ensure base branch has commits & is pushed
 // ──────────────────────────────────────────────
-async function ensureBaseReady(projectDir, baseBranch) {
+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) {
@@ -657,7 +748,7 @@ async function ensureBaseReady(projectDir, baseBranch) {
     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');
+      git.commitAll(projectDir, `chore: initial commit${skipCI}`);
       log.info('✅ Initial commit created');
     } else {
       log.warn('Repository is empty — no files to commit');
@@ -668,7 +759,7 @@ async function ensureBaseReady(projectDir, baseBranch) {
     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');
+      git.commitAll(projectDir, `chore: save current progress before automation${skipCI}`);
       log.info('✅ Base branch changes committed');
     }
   }
@@ -723,5 +814,41 @@ 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);
+}
+
 
 

package/src/commands/usage.js

@@ -237,29 +237,61 @@ export async function usage() {
     log.info(`  Total (${codexSessions.length} sessions): ${formatTokens(totalTokens)} tokens`);
     log.blank();
 
+    // Collect all breakdowns first to compute per-session quota delta
+    const allBreakdowns = codexSessions.map(s => ({
+      session: s,
+      breakdown: getCodexTokenBreakdown(s.rolloutPath),
+    })).filter(b => b.breakdown);
+
     // Token breakdown per session
-    for (const session of codexSessions) {
-      const breakdown = getCodexTokenBreakdown(session.rolloutPath);
-      if (!breakdown) continue;
+    for (let idx = 0; idx < allBreakdowns.length; idx++) {
+      const { session, breakdown } = allBreakdowns[idx];
 
       const title = session.title.length > 50 ? session.title.substring(0, 47) + '...' : session.title;
       console.log(`\x1b[2m    ┌ ${title}\x1b[0m`);
 
+      // Effective (non-cached) tokens and cache rate
+      const effectiveInput = Math.max(0, breakdown.input - breakdown.cached);
+      const cacheRate = breakdown.input > 0
+        ? ((breakdown.cached / breakdown.input) * 100).toFixed(0)
+        : '0';
+      const effectiveTotal = effectiveInput + breakdown.output;
+
       const bRows = [
         ['Input', formatTokens(breakdown.input)],
         ['  ↳ Cached', formatTokens(breakdown.cached)],
         ['Output', formatTokens(breakdown.output)],
         ['  ↳ Reasoning', formatTokens(breakdown.reasoning)],
         ['Total', formatTokens(breakdown.total)],
+        ['Effective', `${formatTokens(effectiveTotal)} (cache ${cacheRate}%)`],
       ];
       for (const [label, val] of bRows) {
-        console.log(`\x1b[2m    │ ${padRight(label, 16)} ${padLeft(val, 10)}\x1b[0m`);
+        console.log(`\x1b[2m    │ ${padRight(label, 16)} ${padLeft(val, 24)}\x1b[0m`);
       }
 
       if (breakdown.rateLimits) {
         const rl = breakdown.rateLimits;
         const resetPrimary = rl.primaryResets ? new Date(rl.primaryResets * 1000).toLocaleString() : 'N/A';
-        console.log(`\x1b[2m    │ Quota: ${rl.primaryUsed ?? '?'}% (5h) / ${rl.secondaryUsed ?? '?'}% (7d)  Resets: ${resetPrimary}\x1b[0m`);
+
+        // Estimate this session's quota contribution by comparing with next (older) session
+        // Sessions are sorted newest-first, so next entry is the previous session
+        let quotaNote5h = '';
+        let quotaNote7d = '';
+        const nextBreakdown = idx < allBreakdowns.length - 1 ? allBreakdowns[idx + 1].breakdown : null;
+        if (nextBreakdown?.rateLimits) {
+          const nrl = nextBreakdown.rateLimits;
+          // Only compute delta if same reset window (same resets_at timestamp)
+          if (nrl.primaryResets === rl.primaryResets && rl.primaryUsed != null && nrl.primaryUsed != null) {
+            const delta5h = rl.primaryUsed - nrl.primaryUsed;
+            quotaNote5h = delta5h >= 0 ? ` (this session: +${delta5h}%)` : '';
+          }
+          if (nrl.secondaryResets === rl.secondaryResets && rl.secondaryUsed != null && nrl.secondaryUsed != null) {
+            const delta7d = rl.secondaryUsed - nrl.secondaryUsed;
+            quotaNote7d = delta7d >= 0 ? ` (this session: +${delta7d}%)` : '';
+          }
+        }
+
+        console.log(`\x1b[2m    │ Quota: ${rl.primaryUsed ?? '?'}% (5h)${quotaNote5h} / ${rl.secondaryUsed ?? '?'}% (7d)${quotaNote7d}  Resets: ${resetPrimary}\x1b[0m`);
       }
       console.log(`\x1b[2m    └──\x1b[0m`);
     }

package/src/utils/github.js

@@ -383,7 +383,7 @@ export const github = {
   ensureRemoteBranch, hasCommitsBetween,
   getReviews, getReviewComments, getIssueComments,
   getLatestReviewState, mergePR, collectReviewFeedback,
-  isPrivateRepo, requestReReview, closePR, deleteBranch,
+  isPrivateRepo, requestReReview, closePR, deleteBranch, getPRState,
 };
 
 /**
@@ -412,3 +412,18 @@ export function deleteBranch(cwd, branch) {
     return false;
   }
 }
+
+/**
+ * Get the state of a PR: 'open', 'closed', or 'merged'
+ */
+export function getPRState(cwd, prNumber) {
+  try {
+    const num = validatePRNumber(prNumber);
+    const output = gh(`pr view ${num} --json state,mergedAt`, cwd);
+    const data = JSON.parse(output);
+    if (data.mergedAt) return 'merged';
+    return (data.state || 'OPEN').toLowerCase();
+  } catch {
+    return 'unknown';
+  }
+}

package/src/utils/provider.js

@@ -10,12 +10,14 @@
  */
 
 import { execSync, spawn } from 'child_process';
-import { readFileSync, writeFileSync } from 'fs';
+import { readFileSync, writeFileSync, existsSync } from 'fs';
 import { resolve } from 'path';
 import { log } from './logger.js';
 import { ask } from './prompt.js';
 import { automator } from './automator.js';
 
+const HOME = process.env.HOME || process.env.USERPROFILE || '~';
+
 // ──────────────────────────────────────────────
 // Provider Registry — each provider is unique
 // ──────────────────────────────────────────────
@@ -31,6 +33,12 @@ const PROVIDERS = {
     buildCommand: (promptPath, cwd) =>
       `cat ${shellEscape(promptPath)} | codex exec --full-auto -`,
     description: 'OpenAI Codex CLI — pipes prompt via stdin',
+    version: {
+      command: 'codex --version',
+      parse: (output) => output.match(/[\d.]+/)?.[0],
+      latest: { type: 'brew-cask', name: 'codex' },
+      update: 'brew upgrade --cask codex',
+    },
   },
 
   'claude-code': {
@@ -45,6 +53,12 @@ const PROVIDERS = {
       return `claude -p "$(cat ${escaped})" --allowedTools "Bash(git*),Read,Write,Edit"`;
     },
     description: 'Anthropic Claude Code CLI — -p mode with tool permissions',
+    version: {
+      command: 'claude --version',
+      parse: (output) => output.match(/[\d.]+/)?.[0],
+      latest: { type: 'npm', name: '@anthropic-ai/claude-code' },
+      update: 'npm update -g @anthropic-ai/claude-code',
+    },
   },
 
   'cursor-agent': {
@@ -57,6 +71,7 @@ const PROVIDERS = {
       return `cursor-agent -p "$(cat ${escaped})"`;
     },
     description: 'Cursor Agent CLI — headless -p mode',
+    // No standard package manager — skip version check
   },
 
   'gemini-cli': {
@@ -69,6 +84,12 @@ const PROVIDERS = {
       return `gemini -p "$(cat ${escaped})"`;
     },
     description: 'Google Gemini CLI — non-interactive -p mode',
+    version: {
+      command: 'gemini --version',
+      parse: (output) => output.match(/[\d.]+/)?.[0],
+      latest: { type: 'brew', name: 'gemini-cli' },
+      update: 'brew upgrade gemini-cli',
+    },
   },
 
   // ─── IDE Providers (clipboard + manual) ───
@@ -136,15 +157,28 @@ export function detectAvailable() {
  * Groups CLIs first (with detection status), then IDEs
  * @returns {{ label: string, value: string }[]}
  */
-export function buildProviderChoices() {
+export function buildProviderChoices(versionCache = {}) {
   const detected = detectAvailable();
   const choices = [];
 
-  // CLI providers first with detection indicator
+  // CLI providers first with detection indicator + version info
   for (const [id, prov] of Object.entries(PROVIDERS)) {
     if (prov.type === 'cli') {
       const installed = detected.includes(id);
-      const tag = installed ? ' ✓ detected' : '';
+      let tag = installed ? ' ✓ detected' : '';
+
+      // Append version info if available in cache
+      const vi = versionCache[id];
+      if (vi && vi.current) {
+        if (vi.updateAvailable) {
+          tag += ` (v${vi.current} → v${vi.latest} available)`;
+        } else if (vi.latest) {
+          tag += ` (v${vi.current} ✓ latest)`;
+        } else {
+          tag += ` (v${vi.current})`;
+        }
+      }
+
       choices.push({
         label: `${prov.name}${tag} — ${prov.description}`,
         value: id,
@@ -178,20 +212,22 @@ export function buildProviderChoices() {
  * @param {string} providerId - Provider ID from config
  * @param {string} promptPath - Absolute path to prompt file
  * @param {string} cwd - Working directory
- * @returns {Promise<boolean>} true if execution succeeded
+ * @returns {Promise<{ ok: boolean, rateLimited?: boolean, retryAt?: Date }>}
  */
 export async function executePrompt(providerId, promptPath, cwd) {
   const prov = PROVIDERS[providerId];
 
   if (!prov) {
     log.warn(`Unknown provider '${providerId}', falling back to clipboard mode`);
-    return await clipboardFallback(promptPath);
+    const ok = await clipboardFallback(promptPath);
+    return { ok };
   }
 
   if (prov.type === 'cli') {
     return await executeCLI(prov, providerId, promptPath, cwd);
   } else {
-    return await executeIDE(prov, providerId, promptPath);
+    const ok = await executeIDE(prov, providerId, promptPath);
+    return { ok };
   }
 }
 
@@ -210,7 +246,8 @@ async function executeCLI(prov, providerId, promptPath, cwd) {
       execSync(cmd, { stdio: 'pipe' });
     } catch {
       log.warn(`${prov.name} not found in PATH, falling back to clipboard mode`);
-      return await clipboardFallback(promptPath);
+      const ok = await clipboardFallback(promptPath);
+      return { ok };
     }
   }
 
@@ -227,6 +264,7 @@ async function executeCLI(prov, providerId, promptPath, cwd) {
     let lastFile = '';
     let statusText = command.substring(0, 80);
     let lineBuffer = '';
+    let stderrBuffer = '';  // Capture stderr for rate limit detection
     const FILE_EXT = /(?:^|\s|['"|(/])([a-zA-Z0-9_.\/-]+\.(?:rs|ts|js|jsx|tsx|py|go|toml|yaml|yml|json|md|css|html|sh|sql|prisma|vue|svelte))\b/;
 
     // Spinner animation — gives a dynamic, alive feel
@@ -247,16 +285,20 @@ async function executeCLI(prov, providerId, promptPath, cwd) {
     }
 
     child.stdout.on('data', (data) => {
-      lineBuffer += data.toString();
+      const text = data.toString();
+      lineBuffer += text;
+      stderrBuffer += text;  // Also check stdout for rate limit messages
       const lines = lineBuffer.split('\n');
       lineBuffer = lines.pop();
       for (const line of lines) processLine(line);
     });
 
     child.stderr.on('data', (data) => {
-      const text = data.toString().trim();
-      if (text && !text.includes('\u2588') && !text.includes('progress')) {
-        for (const line of text.split('\n').slice(0, 3)) {
+      const text = data.toString();
+      stderrBuffer += text;
+      const trimmed = text.trim();
+      if (trimmed && !trimmed.includes('\u2588') && !trimmed.includes('progress')) {
+        for (const line of trimmed.split('\n').slice(0, 3)) {
           if (line.trim()) log.dim(`  ${line.substring(0, 120)}`);
         }
       }
@@ -267,10 +309,17 @@ async function executeCLI(prov, providerId, promptPath, cwd) {
       process.stdout.write('\r\x1b[K');
       if (code === 0) {
         log.info(`${prov.name} execution complete`);
-        resolvePromise(true);
+        resolvePromise({ ok: true });
       } else {
-        log.warn(`${prov.name} exited with code ${code}`);
-        resolvePromise(false);
+        // Check for rate limit error in captured output
+        const rateLimitInfo = parseRateLimitError(stderrBuffer);
+        if (rateLimitInfo) {
+          log.warn(`${prov.name} hit rate limit — retry at ${rateLimitInfo.retryAtStr}`);
+          resolvePromise({ ok: false, rateLimited: true, retryAt: rateLimitInfo.retryAt, retryAtStr: rateLimitInfo.retryAtStr });
+        } else {
+          log.warn(`${prov.name} exited with code ${code}`);
+          resolvePromise({ ok: false });
+        }
       }
     });
 
@@ -278,7 +327,7 @@ async function executeCLI(prov, providerId, promptPath, cwd) {
       clearInterval(spinTimer);
       process.stdout.write('\r\x1b[K');
       log.warn(`${prov.name} execution failed: ${err.message}`);
-      resolvePromise(false);
+      resolvePromise({ ok: false });
     });
   });
 }
@@ -458,7 +507,263 @@ IMPORTANT: Output ONLY a single word on the first line: either PASS or FIX. No o
   return null; // Ambiguous — caller decides fallback
 }
 
+// ──────────────────────────────────────────────
+// Version Check & Auto-Update
+// ──────────────────────────────────────────────
+
+/**
+ * Compare two semver-like version strings.
+ * Returns true if latest > current.
+ */
+function isNewerVersion(current, latest) {
+  if (!current || !latest) return false;
+  const a = current.split('.').map(Number);
+  const b = latest.split('.').map(Number);
+  const len = Math.max(a.length, b.length);
+  for (let i = 0; i < len; i++) {
+    const av = a[i] || 0;
+    const bv = b[i] || 0;
+    if (bv > av) return true;
+    if (bv < av) return false;
+  }
+  return false;
+}
+
+/**
+ * Get the locally installed version of a provider.
+ * @returns {string|null} version string or null
+ */
+function getLocalVersion(providerId) {
+  const prov = PROVIDERS[providerId];
+  if (!prov?.version) return null;
+  try {
+    const output = execSync(prov.version.command, {
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+      timeout: 5000,
+    }).trim();
+    return prov.version.parse(output);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Fetch the latest available version from the package registry.
+ * @returns {string|null} latest version string or null
+ */
+function fetchLatestVersion(providerId) {
+  const prov = PROVIDERS[providerId];
+  if (!prov?.version?.latest) return null;
+
+  const { type, name } = prov.version.latest;
+  try {
+    if (type === 'npm') {
+      return execSync(`npm view ${name} version`, {
+        encoding: 'utf-8',
+        stdio: ['pipe', 'pipe', 'pipe'],
+        timeout: 10000,
+      }).trim();
+    }
+    if (type === 'brew') {
+      const json = execSync(`brew info ${name} --json=v2`, {
+        encoding: 'utf-8',
+        stdio: ['pipe', 'pipe', 'pipe'],
+        timeout: 10000,
+      });
+      const data = JSON.parse(json);
+      return data.formulae?.[0]?.versions?.stable || null;
+    }
+    if (type === 'brew-cask') {
+      const json = execSync(`brew info --cask ${name} --json=v2`, {
+        encoding: 'utf-8',
+        stdio: ['pipe', 'pipe', 'pipe'],
+        timeout: 10000,
+      });
+      const data = JSON.parse(json);
+      return data.casks?.[0]?.version || null;
+    }
+  } catch {
+    return null;
+  }
+  return null;
+}
+
+/**
+ * Check version status for a single provider.
+ * @param {string} providerId
+ * @returns {{ current: string|null, latest: string|null, updateAvailable: boolean, updateCommand: string|null }}
+ */
+export function checkProviderVersion(providerId) {
+  const prov = PROVIDERS[providerId];
+  if (!prov?.version) {
+    return { current: null, latest: null, updateAvailable: false, updateCommand: null };
+  }
+
+  const current = getLocalVersion(providerId);
+  const latest = fetchLatestVersion(providerId);
+  const updateAvailable = isNewerVersion(current, latest);
+
+  return {
+    current,
+    latest,
+    updateAvailable,
+    updateCommand: updateAvailable ? prov.version.update : null,
+  };
+}
+
+/**
+ * Check versions for all installed CLI providers in parallel.
+ * Returns a map of providerId → version info.
+ * Non-blocking: failures are silently ignored.
+ */
+export function checkAllVersions() {
+  const detected = detectAvailable();
+  const results = {};
+
+  for (const id of detected) {
+    const prov = PROVIDERS[id];
+    if (!prov?.version) continue;
+    try {
+      results[id] = checkProviderVersion(id);
+    } catch {
+      // Skip on failure — non-blocking
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Execute the update command for a provider.
+ * @param {string} providerId
+ * @returns {boolean} true if update succeeded
+ */
+export function updateProvider(providerId) {
+  const prov = PROVIDERS[providerId];
+  if (!prov?.version?.update) return false;
+
+  try {
+    log.info(`Updating ${prov.name}...`);
+    execSync(prov.version.update, {
+      encoding: 'utf-8',
+      stdio: 'inherit',
+      timeout: 120000, // 2 minute timeout for updates
+    });
+    log.info(`✅ ${prov.name} updated successfully`);
+    return true;
+  } catch (err) {
+    log.warn(`Failed to update ${prov.name}: ${(err.message || '').substring(0, 100)}`);
+    return false;
+  }
+}
+
+// ──────────────────────────────────────────────
+// Rate Limit Detection
+// ──────────────────────────────────────────────
+
+/**
+ * Parse rate limit error from CLI output.
+ * Looks for: "try again at X:XX PM" or "try again at X:XX AM"
+ * @param {string} output - Combined stdout+stderr text
+ * @returns {{ retryAt: Date, retryAtStr: string } | null}
+ */
+function parseRateLimitError(output) {
+  if (!output) return null;
+
+  // Match "usage limit" or "rate limit" patterns
+  const isRateLimited = /usage limit|rate limit|too many requests/i.test(output);
+  if (!isRateLimited) return null;
+
+  // Extract time: "try again at 6:06 PM" or "try again at 18:06"
+  const timeMatch = output.match(/try again at\s+(\d{1,2}:\d{2}(?::\d{2})?\s*(?:AM|PM)?)/i);
+  if (!timeMatch) {
+    // Rate limited but no specific time — estimate 30 minutes from now
+    const retryAt = new Date(Date.now() + 30 * 60 * 1000);
+    return { retryAt, retryAtStr: retryAt.toLocaleTimeString() };
+  }
+
+  const timeStr = timeMatch[1].trim();
+  const now = new Date();
+  const today = now.toISOString().split('T')[0]; // YYYY-MM-DD
+
+  // Parse the time string
+  let retryAt;
+  if (/AM|PM/i.test(timeStr)) {
+    // 12-hour format: "6:06 PM"
+    retryAt = new Date(`${today} ${timeStr}`);
+  } else {
+    // 24-hour format: "18:06"
+    retryAt = new Date(`${today}T${timeStr}`);
+  }
+
+  // If parsed time is in the past, it's tomorrow
+  if (retryAt <= now) {
+    retryAt.setDate(retryAt.getDate() + 1);
+  }
+
+  // Sanity check: if retry is more than 6 hours away, something's wrong
+  if (retryAt - now > 6 * 60 * 60 * 1000) {
+    retryAt = new Date(Date.now() + 30 * 60 * 1000);
+  }
+
+  return { retryAt, retryAtStr: timeStr };
+}
+
+// ──────────────────────────────────────────────
+// Quota Pre-Check
+// ──────────────────────────────────────────────
+
+/**
+ * Check current Codex 7d quota usage before execution.
+ * Reads the latest rollout file for quota data.
+ * 
+ * @param {number} threshold - Percentage at which to block (default 98)
+ * @returns {{ ok: boolean, quota5h: number|null, quota7d: number|null, warning: boolean }}
+ */
+export function checkQuotaBeforeExecution(threshold = 97) {
+  try {
+    const sessionsDir = resolve(HOME, '.codex/sessions');
+    if (!existsSync(sessionsDir)) return { ok: true, quota5h: null, quota7d: null, warning: false };
+
+    // Find the most recent rollout file
+    const raw = execSync(
+      `find "${sessionsDir}" -name "rollout-*.jsonl" -type f | sort -r | head -1`,
+      { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'], timeout: 5000 }
+    ).trim();
+    if (!raw || !existsSync(raw)) return { ok: true, quota5h: null, quota7d: null, warning: false };
+
+    // Get the last token_count event with rate_limits
+    const line = execSync(
+      `grep '"rate_limits"' "${raw}" | tail -1`,
+      { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'], timeout: 5000 }
+    ).trim();
+    if (!line) return { ok: true, quota5h: null, quota7d: null, warning: false };
+
+    const data = JSON.parse(line);
+    const limits = data?.payload?.rate_limits;
+    if (!limits) return { ok: true, quota5h: null, quota7d: null, warning: false };
+
+    const quota5h = limits.primary?.used_percent ?? null;
+    const quota7d = limits.secondary?.used_percent ?? null;
+
+    // Block if 7d quota exceeds threshold
+    if (quota7d !== null && quota7d >= threshold) {
+      return { ok: false, quota5h, quota7d, warning: false };
+    }
+
+    // Warn if 7d quota is high (>= 95%)
+    const warning = quota7d !== null && quota7d >= 95;
+    return { ok: true, quota5h, quota7d, warning };
+  } catch {
+    // Quota check failed — don't block execution
+    return { ok: true, quota5h: null, quota7d: null, warning: false };
+  }
+}
+
 export const provider = {
   getProvider, getAllProviderIds, detectAvailable,
   buildProviderChoices, executePrompt, queryAI, classifyReview,
+  checkProviderVersion, checkAllVersions, updateProvider,
+  checkQuotaBeforeExecution,
 };