happy-stacks 0.6.11 → 0.6.13

package/scripts/utils/review/detached_worktree.mjs

@@ -0,0 +1,61 @@
+import { join } from 'node:path';
+import { existsSync } from 'node:fs';
+import { ensureDir } from '../fs/ops.mjs';
+import { runCapture } from '../proc/proc.mjs';
+
+function sanitizeLabel(raw) {
+  return String(raw ?? 'worktree')
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+function defaultNonce() {
+  const rand = Math.random().toString(16).slice(2, 10);
+  return `${process.pid}-${Date.now()}-${rand}`;
+}
+
+export function computeDetachedWorktreeDir({ repoRootDir, label, headCommit, nonce } = {}) {
+  const root = String(repoRootDir ?? '').trim();
+  if (!root) throw new Error('[review] computeDetachedWorktreeDir: missing repoRootDir');
+
+  const safeLabel = sanitizeLabel(label);
+  const short = String(headCommit ?? '').slice(0, 12);
+  const n = String(nonce ?? defaultNonce()).trim();
+  return join(root, '.project', 'review-worktrees', `${safeLabel}-${short}-${n}`);
+}
+
+/**
+ * Create a detached git worktree for `headCommit`, run `fn(worktreeDir)`, then clean up.
+ *
+ * Notes:
+ * - The worktree directory name includes a nonce to avoid collisions when a prior run crashed
+ *   and left behind a directory, or when multiple review runs happen in parallel.
+ * - We do best-effort cleanup even if `fn` throws.
+ */
+export async function withDetachedWorktree({ repoDir, headCommit, label, env, nonce }, fn) {
+  const root = (await runCapture('git', ['rev-parse', '--show-toplevel'], { cwd: repoDir, env })).toString().trim();
+  if (!root) throw new Error('[review] failed to resolve git toplevel');
+
+  const worktreesRoot = join(root, '.project', 'review-worktrees');
+  await ensureDir(worktreesRoot);
+  const dir = computeDetachedWorktreeDir({ repoRootDir: root, label, headCommit, nonce });
+
+  // Extremely defensive: should not happen with nonced dirs, but avoid surprising errors.
+  if (existsSync(dir)) {
+    throw new Error(`[review] detached worktree dir already exists: ${dir}`);
+  }
+
+  try {
+    await runCapture('git', ['worktree', 'add', '--detach', dir, headCommit], { cwd: repoDir, env });
+    return await fn(dir);
+  } finally {
+    try {
+      await runCapture('git', ['worktree', 'remove', '--force', dir], { cwd: repoDir, env });
+      await runCapture('git', ['worktree', 'prune'], { cwd: repoDir, env });
+    } catch {
+      // best-effort cleanup; leave an orphaned worktree if needed
+    }
+  }
+}
+

package/scripts/utils/review/detached_worktree.test.mjs

@@ -0,0 +1,62 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, mkdir, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { run, runCapture } from '../proc/proc.mjs';
+import { computeDetachedWorktreeDir, withDetachedWorktree } from './detached_worktree.mjs';
+
+function gitEnv() {
+  const clean = {};
+  for (const [k, v] of Object.entries(process.env)) {
+    if (k.startsWith('HAPPY_STACKS_') || k.startsWith('HAPPY_LOCAL_')) continue;
+    clean[k] = v;
+  }
+  return {
+    ...clean,
+    GIT_AUTHOR_NAME: 'Test',
+    GIT_AUTHOR_EMAIL: 'test@example.com',
+    GIT_COMMITTER_NAME: 'Test',
+    GIT_COMMITTER_EMAIL: 'test@example.com',
+  };
+}
+
+test('computeDetachedWorktreeDir includes nonce to avoid collisions', () => {
+  const dir1 = computeDetachedWorktreeDir({ repoRootDir: '/repo', label: 'coderabbit-1-of-21', headCommit: 'abcdef0123456789', nonce: 'n1' });
+  const dir2 = computeDetachedWorktreeDir({ repoRootDir: '/repo', label: 'coderabbit-1-of-21', headCommit: 'abcdef0123456789', nonce: 'n2' });
+  assert.notEqual(dir1, dir2);
+  assert.ok(dir1.includes('coderabbit-1-of-21-abcdef012345-n1'));
+  assert.ok(dir2.includes('coderabbit-1-of-21-abcdef012345-n2'));
+});
+
+test('withDetachedWorktree can be called repeatedly without directory collisions', async () => {
+  const repo = await mkdtemp(join(tmpdir(), 'happy-review-wt-'));
+  const env = gitEnv();
+
+  try {
+    await run('git', ['init', '-q'], { cwd: repo, env });
+    await run('git', ['checkout', '-q', '-b', 'main'], { cwd: repo, env });
+    await mkdir(join(repo, 'x'), { recursive: true });
+    await writeFile(join(repo, 'x', 'a.txt'), 'a\n', 'utf-8');
+    await run('git', ['add', '.'], { cwd: repo, env });
+    await run('git', ['commit', '-q', '-m', 'base'], { cwd: repo, env });
+
+    const head = (await runCapture('git', ['rev-parse', 'HEAD'], { cwd: repo, env })).trim();
+
+    const seen = [];
+    await withDetachedWorktree({ repoDir: repo, headCommit: head, label: 'test', env, nonce: 'one' }, async (dir) => {
+      seen.push(dir);
+      assert.equal((await runCapture('git', ['rev-parse', '--is-inside-work-tree'], { cwd: dir, env })).trim(), 'true');
+    });
+    await withDetachedWorktree({ repoDir: repo, headCommit: head, label: 'test', env, nonce: 'two' }, async (dir) => {
+      seen.push(dir);
+      assert.equal((await runCapture('git', ['rev-parse', '--is-inside-work-tree'], { cwd: dir, env })).trim(), 'true');
+    });
+
+    assert.equal(seen.length, 2);
+    assert.notEqual(seen[0], seen[1]);
+  } finally {
+    await rm(repo, { recursive: true, force: true });
+  }
+});
+

package/scripts/utils/review/findings.mjs

@@ -45,7 +45,9 @@ export function parseCodeRabbitPlainOutput(text) {
 
   for (let i = 0; i < lines.length; i += 1) {
     const line = lines[i];
-    const trimmed = line.trimEnd();
+    // The raw log files written by the review runner prefix each line with "[label] ".
+    // Strip that prefix so we can parse both prefixed logs and unprefixed stdout.
+    const trimmed = line.trimEnd().replace(/^\[[^\]]+\]\s*/g, '');
 
     if (trimmed.startsWith('============================================================================')) {
       flush();
@@ -95,27 +97,129 @@ export function parseCodexReviewText(reviewText) {
   const s = String(reviewText ?? '');
   const marker = '===FINDINGS_JSON===';
   const idx = s.indexOf(marker);
-  if (idx < 0) return [];
-  const jsonText = s.slice(idx + marker.length).trim();
-  if (!jsonText) return [];
-
-  let parsed;
-  try {
-    parsed = JSON.parse(jsonText);
-  } catch {
-    return [];
+  if (idx >= 0) {
+    let jsonText = s.slice(idx + marker.length).trim();
+    if (!jsonText) return [];
+
+    // The raw log files written by the review runner prefix each line with "[label] ".
+    // Strip that prefix so we can parse both prefixed logs and unprefixed stdout.
+    jsonText = jsonText
+      .split('\n')
+      .map((line) => String(line ?? '').replace(/^\[[^\]]+\]\s*/g, ''))
+      .join('\n')
+      .trim();
+
+    // Some reviewers wrap the JSON in a fenced code block:
+    // ===FINDINGS_JSON===
+    // ```json
+    // [...]
+    // ```
+    //
+    // Strip the outer fence so JSON.parse can succeed.
+    const fence = jsonText.match(/^```[a-z0-9_-]*\s*\n([\s\S]*?)\n```/i);
+    if (fence?.[1]) jsonText = fence[1].trim();
+
+    let parsed;
+    try {
+      parsed = JSON.parse(jsonText);
+    } catch {
+      parsed = null;
+    }
+
+    // Some tools append non-JSON metadata after the array (e.g. "Request ID: ...").
+    // As a last resort, try to parse the first top-level JSON array substring.
+    if (!Array.isArray(parsed)) {
+      const firstBracket = jsonText.indexOf('[');
+      const lastBracket = jsonText.lastIndexOf(']');
+      if (firstBracket >= 0 && lastBracket > firstBracket) {
+        try {
+          parsed = JSON.parse(jsonText.slice(firstBracket, lastBracket + 1));
+        } catch {
+          // ignore
+        }
+      }
+    }
+    if (Array.isArray(parsed)) {
+      return parsed
+        .map((x) => ({
+          reviewer: 'codex',
+          severity: x?.severity ?? null,
+          file: x?.file ?? null,
+          lines: x?.lines ?? null,
+          title: x?.title ?? null,
+          recommendation: x?.recommendation ?? null,
+          needsDiscussion: Boolean(x?.needsDiscussion),
+        }))
+        .filter((x) => x.file && x.title);
+    }
+  }
+
+  // Fallback: Codex sometimes returns a human-readable list like:
+  // - [P2] Thing — /abs/path/.project/review-worktrees/codex-.../cli/src/foo.ts:10-12
+  //
+  // Parse these into structured findings so they appear in triage even when the
+  // JSON trailer is missing.
+  const priorityToSeverity = { 1: 'blocker', 2: 'major', 3: 'minor', 4: 'nit' };
+  const lines = s.split('\n');
+  const findings = [];
+  const seen = new Set();
+
+  function stripPrefix(line) {
+    return String(line ?? '').replace(/^\[[^\]]+\]\s*/g, '').trim();
+  }
+
+  function normalizePath(rawPath) {
+    const p = String(rawPath ?? '').trim();
+    const marker2 = '/.project/review-worktrees/';
+    const i = p.indexOf(marker2);
+    if (i < 0) return p;
+    const rest = p.slice(i + marker2.length);
+    const slash = rest.indexOf('/');
+    if (slash < 0) return p;
+    return rest.slice(slash + 1);
   }
-  if (!Array.isArray(parsed)) return [];
-  return parsed
-    .map((x) => ({
+
+  for (const rawLine of lines) {
+    const line = stripPrefix(rawLine);
+    const m = line.match(/^- \[P([1-4])\]\s+(.+?)\s+—\s+(.+)$/);
+    if (!m) continue;
+
+    const priority = Number(m[1]);
+    const title = String(m[2]).trim();
+    const pathPart = String(m[3]).trim();
+
+    let file = pathPart;
+    let range = null;
+
+    const lastColon = pathPart.lastIndexOf(':');
+    if (lastColon > 0) {
+      const suffix = pathPart.slice(lastColon + 1).trim();
+      const rm = suffix.match(/^(\d+)(?:-(\d+))?$/);
+      if (rm) {
+        const start = Number(rm[1]);
+        const end = Number(rm[2] ?? rm[1]);
+        range = { start, end };
+        file = pathPart.slice(0, lastColon);
+      }
+    }
+
+    const normalizedFile = normalizePath(file);
+    const severity = priorityToSeverity[priority] ?? null;
+    const key = `${normalizedFile}:${range?.start ?? ''}-${range?.end ?? ''}:${title}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    findings.push({
       reviewer: 'codex',
-      severity: x?.severity ?? null,
-      file: x?.file ?? null,
-      title: x?.title ?? null,
-      recommendation: x?.recommendation ?? null,
-      needsDiscussion: Boolean(x?.needsDiscussion),
-    }))
-    .filter((x) => x.file && x.title);
+      severity,
+      file: normalizedFile,
+      lines: range,
+      title,
+      recommendation: null,
+      needsDiscussion: false,
+    });
+  }
+
+  return findings.filter((x) => x.file && x.title);
 }
 
 export function formatTriageMarkdown({ runLabel, baseRef, findings }) {
@@ -126,6 +230,15 @@ export function formatTriageMarkdown({ runLabel, baseRef, findings }) {
     `- Base ref: ${baseRef ?? ''}`,
     `- Findings: ${items.length}`,
     '',
+    '## Trust checklist (READ THIS FIRST)',
+    '',
+    'Before you act on reviewer output:',
+    '1) Load this file into your context (human/LLM) so you follow the workflow end-to-end.',
+    '2) Treat every suggestion as a suggestion: verify against best practices + project invariants.',
+    '3) If you are unsure, do not apply; mark **Needs discussion** and capture rationale.',
+    '4) Do not skip nits by default: apply them when they improve long-term maintainability without risk.',
+    '5) Use web search sparingly when needed to validate best practices, but prefer primary sources/docs.',
+    '',
     '## Mandatory workflow',
     '',
     'For each finding below:',

package/scripts/utils/review/findings.test.mjs

@@ -64,6 +64,93 @@ test('parseCodexReviewText extracts findings JSON trailer', () => {
   assert.equal(findings[0].severity, 'major');
 });
 
+test('parseCodexReviewText extracts findings JSON trailer even when fenced', () => {
+  const review = [
+    'All good.',
+    '',
+    '===FINDINGS_JSON===',
+    '```json',
+    JSON.stringify(
+      [
+        {
+          severity: 'minor',
+          file: 'cli/src/foo.ts',
+          title: 'Prefer explicit return type',
+          recommendation: 'Add an explicit return type for clarity.',
+        },
+      ],
+      null,
+      2
+    ),
+    '```',
+  ].join('\n');
+
+  const findings = parseCodexReviewText(review);
+  assert.equal(findings.length, 1);
+  assert.equal(findings[0].file, 'cli/src/foo.ts');
+  assert.equal(findings[0].severity, 'minor');
+});
+
+test('parseCodexReviewText extracts findings JSON trailer when lines are log-prefixed', () => {
+  const label = '[monorepo:augment:4/39] ';
+  const review = [
+    `${label}some preamble`,
+    `${label}===FINDINGS_JSON===`,
+    `${label}\`\`\`json`,
+    `${label}[`,
+    `${label}  {`,
+    `${label}    \"severity\": \"major\",`,
+    `${label}    \"file\": \"cli/src/x.ts\",`,
+    `${label}    \"title\": \"Fix thing\",`,
+    `${label}    \"recommendation\": \"Do it.\",`,
+    `${label}    \"needsDiscussion\": false`,
+    `${label}  }`,
+    `${label}]`,
+    `${label}\`\`\``,
+    `${label}`,
+    `${label}Request ID: abc`,
+  ].join('\n');
+
+  const findings = parseCodexReviewText(review);
+  assert.equal(findings.length, 1);
+  assert.equal(findings[0].file, 'cli/src/x.ts');
+  assert.equal(findings[0].severity, 'major');
+});
+
+test('parseCodexReviewText falls back to parsing [P#] bullet lines', () => {
+  const review = [
+    '[monorepo:codex:2/21] Review comment:',
+    '[monorepo:codex:2/21] - [P1] Fix thing one — /Users/me/repo/.project/review-worktrees/codex-2-of-21-abc/cli/src/foo.ts:10-12',
+    '[monorepo:codex:2/21] - [P3] Fix thing two — /Users/me/repo/.project/review-worktrees/codex-2-of-21-abc/expo-app/sources/bar.tsx:7',
+  ].join('\n');
+
+  const findings = parseCodexReviewText(review);
+  assert.equal(findings.length, 2);
+  assert.equal(findings[0].file, 'cli/src/foo.ts');
+  assert.deepEqual(findings[0].lines, { start: 10, end: 12 });
+  assert.equal(findings[0].severity, 'blocker');
+  assert.equal(findings[0].title, 'Fix thing one');
+  assert.equal(findings[1].file, 'expo-app/sources/bar.tsx');
+  assert.deepEqual(findings[1].lines, { start: 7, end: 7 });
+  assert.equal(findings[1].severity, 'minor');
+  assert.equal(findings[1].title, 'Fix thing two');
+});
+
+test('parseCodexReviewText falls back when marker exists but JSON is missing/invalid', () => {
+  const review = [
+    'instructions...',
+    '===FINDINGS_JSON===',
+    'this is not json',
+    '[monorepo:codex:2/21] - [P2] Fix thing — /Users/me/repo/.project/review-worktrees/codex-2-of-21-abc/server/src/x.ts:1-2',
+  ].join('\n');
+
+  const findings = parseCodexReviewText(review);
+  assert.equal(findings.length, 1);
+  assert.equal(findings[0].file, 'server/src/x.ts');
+  assert.deepEqual(findings[0].lines, { start: 1, end: 2 });
+  assert.equal(findings[0].severity, 'major');
+});
+
 test('formatTriageMarkdown includes required workflow fields', () => {
   const md = formatTriageMarkdown({
     runLabel: 'review-123',
@@ -78,8 +165,8 @@ test('formatTriageMarkdown includes required workflow fields', () => {
       },
     ],
   });
+  assert.match(md, /Trust checklist/i);
   assert.match(md, /Final decision: \*\*TBD\*\*/);
   assert.match(md, /Verified in validation worktree:/);
   assert.match(md, /Commit:/);
 });
-

package/scripts/utils/review/runners/augment.mjs

@@ -0,0 +1,71 @@
+import { runCaptureResult } from '../../proc/proc.mjs';
+
+export function detectAugmentAuthError({ stdout, stderr }) {
+  const combined = `${stdout ?? ''}\n${stderr ?? ''}`;
+  return combined.includes('Authentication failed') && combined.includes("Run 'auggie login'");
+}
+
+export function buildAugmentReviewArgs({
+  prompt,
+  workspaceRoot,
+  cacheDir,
+  model,
+  rulesFiles = [],
+  retryTimeoutSec,
+  maxTurns,
+} = {}) {
+  const args = ['--print', '--quiet', '--dont-save-session', '--ask', '--output-format', 'text'];
+
+  const wr = String(workspaceRoot ?? '').trim();
+  if (wr) args.push('--workspace-root', wr);
+
+  const cd = String(cacheDir ?? '').trim();
+  if (cd) args.push('--augment-cache-dir', cd);
+
+  const m = String(model ?? '').trim();
+  if (m) args.push('--model', m);
+
+  const rt = String(retryTimeoutSec ?? '').trim();
+  if (rt) args.push('--retry-timeout', rt);
+
+  const mt = String(maxTurns ?? '').trim();
+  if (mt) args.push('--max-turns', mt);
+
+  for (const rf of Array.isArray(rulesFiles) ? rulesFiles : []) {
+    const p = String(rf ?? '').trim();
+    if (!p) continue;
+    args.push('--rules', p);
+  }
+
+  const p = String(prompt ?? '').trim();
+  if (!p) throw new Error('[review] augment: missing prompt');
+  args.push(p);
+  return args;
+}
+
+export async function runAugmentReview({
+  repoDir,
+  prompt,
+  env,
+  streamLabel,
+  teeFile,
+  teeLabel,
+  cacheDir,
+  model,
+  rulesFiles = [],
+  retryTimeoutSec = 60 * 60 * 2,
+  maxTurns,
+} = {}) {
+  const args = buildAugmentReviewArgs({
+    prompt,
+    workspaceRoot: repoDir,
+    cacheDir,
+    model,
+    rulesFiles,
+    retryTimeoutSec,
+    maxTurns,
+  });
+  const res = await runCaptureResult('auggie', args, { cwd: repoDir, env: env ?? {}, streamLabel, teeFile, teeLabel });
+  return { ...res, stdout: res.out, stderr: res.err };
+}
+

package/scripts/utils/review/runners/augment.test.mjs

@@ -0,0 +1,42 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { buildAugmentReviewArgs, detectAugmentAuthError } from './augment.mjs';
+
+test('detectAugmentAuthError matches 401 login guidance', () => {
+  const stdout = "❌ Authentication failed: HTTP error: 401 Unauthorized\n   Run 'auggie login' to authenticate first.";
+  assert.equal(detectAugmentAuthError({ stdout, stderr: '' }), true);
+});
+
+test('buildAugmentReviewArgs builds auggie --print args with optional settings', () => {
+  const args = buildAugmentReviewArgs({
+    prompt: 'Review the code',
+    workspaceRoot: '/repo',
+    cacheDir: '/cache',
+    model: 'gpt-5.2',
+    rulesFiles: ['/rules/a.md', '/rules/b.md'],
+    retryTimeoutSec: 123,
+    maxTurns: 9,
+  });
+
+  assert.equal(args[0], '--print');
+  assert.ok(args.includes('--quiet'));
+  assert.ok(args.includes('--dont-save-session'));
+  assert.ok(args.includes('--ask'));
+  assert.ok(args.includes('--workspace-root'));
+  assert.ok(args.includes('/repo'));
+  assert.ok(args.includes('--augment-cache-dir'));
+  assert.ok(args.includes('/cache'));
+  assert.ok(args.includes('--model'));
+  assert.ok(args.includes('gpt-5.2'));
+  assert.ok(args.includes('--retry-timeout'));
+  assert.ok(args.includes('123'));
+  assert.ok(args.includes('--max-turns'));
+  assert.ok(args.includes('9'));
+
+  const joined = args.join(' ');
+  assert.match(joined, /--rules \/rules\/a\.md/);
+  assert.match(joined, /--rules \/rules\/b\.md/);
+  assert.equal(args.at(-1), 'Review the code');
+});
+

package/scripts/utils/review/runners/coderabbit.mjs

@@ -1,5 +1,6 @@
 import { runCaptureResult } from '../../proc/proc.mjs';
 import { join } from 'node:path';
+import { appendFile } from 'node:fs/promises';
 
 function normalizeType(raw) {
   const t = String(raw ?? '').trim().toLowerCase();
@@ -8,6 +9,19 @@ function normalizeType(raw) {
   throw new Error(`[review] invalid coderabbit type: ${raw} (expected: all|committed|uncommitted)`);
 }
 
+export function parseCodeRabbitRateLimitRetryMs(text) {
+  const s = String(text ?? '');
+  const m = s.match(/Rate limit exceeded,\s*please try after\s+(\d+)\s+minutes?\s+and\s+(\d+)\s+seconds?/i);
+  if (!m) return null;
+  const minutes = Number(m[1]);
+  const seconds = Number(m[2]);
+  if (!Number.isFinite(minutes) || minutes < 0) return null;
+  if (!Number.isFinite(seconds) || seconds < 0) return null;
+  // Add +1s padding to avoid retrying too early.
+  const totalSeconds = minutes * 60 + seconds + 1;
+  return Math.max(1000, totalSeconds * 1000);
+}
+
 export function buildCodeRabbitReviewArgs({ repoDir, baseRef, baseCommit, type, configFiles }) {
   const args = ['review', '--plain', '--no-color', '--type', normalizeType(type), '--cwd', repoDir];
   const base = String(baseRef ?? '').trim();
@@ -27,8 +41,15 @@ export function buildCodeRabbitEnv({ env, homeDir }) {
   const dir = String(homeDir ?? '').trim();
   if (!dir) return merged;
 
-  merged.HOME = dir;
-  merged.USERPROFILE = dir;
+  // IMPORTANT:
+  // Do not override HOME/USERPROFILE here.
+  //
+  // CodeRabbit uses OS credential storage (e.g. macOS Keychain). If HOME is pointed at
+  // an isolated directory (like .project/coderabbit-home), the underlying keychain
+  // lookup can fail with "Keychain Not Found" and auth will not work in the wrapper.
+  //
+  // We still isolate CodeRabbit's on-disk config/cache under the provided homeDir via
+  // CODERABBIT_HOME + XDG dirs.
   merged.CODERABBIT_HOME = join(dir, '.coderabbit');
   merged.XDG_CONFIG_HOME = join(dir, '.config');
   merged.XDG_CACHE_HOME = join(dir, '.cache');
@@ -50,12 +71,35 @@ export async function runCodeRabbitReview({
 }) {
   const homeDir = (env?.HAPPY_STACKS_CODERABBIT_HOME_DIR ?? env?.HAPPY_LOCAL_CODERABBIT_HOME_DIR ?? '').toString().trim();
   const args = buildCodeRabbitReviewArgs({ repoDir, baseRef, baseCommit, type, configFiles });
-  const res = await runCaptureResult('coderabbit', args, {
-    cwd: repoDir,
-    env: buildCodeRabbitEnv({ env, homeDir }),
-    streamLabel,
-    teeFile,
-    teeLabel,
-  });
-  return { ...res, stdout: res.out, stderr: res.err };
+  const maxAttempts = 50;
+  let last = null;
+  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+    // eslint-disable-next-line no-await-in-loop
+    const res = await runCaptureResult('coderabbit', args, {
+      cwd: repoDir,
+      env: buildCodeRabbitEnv({ env, homeDir }),
+      streamLabel,
+      teeFile,
+      teeLabel,
+    });
+    last = res;
+    if (res.ok) return { ...res, stdout: res.out, stderr: res.err };
+
+    const retryMs = parseCodeRabbitRateLimitRetryMs(`${res.out ?? ''}\n${res.err ?? ''}`);
+    if (!retryMs) return { ...res, stdout: res.out, stderr: res.err };
+
+    const seconds = Math.ceil(retryMs / 1000);
+    const msg = `[review] coderabbit rate limited; retrying in ${seconds}s (attempt ${attempt}/${maxAttempts})\n`;
+    try {
+      if (teeFile) await appendFile(teeFile, msg);
+    } catch {
+      // ignore
+    }
+    // eslint-disable-next-line no-console
+    console.warn(msg.trimEnd());
+    // eslint-disable-next-line no-await-in-loop
+    await new Promise((r) => setTimeout(r, retryMs));
+  }
+
+  return { ...last, stdout: last?.out ?? '', stderr: last?.err ?? '' };
 }