happy-stacks 0.3.0 → 0.5.0

package/scripts/review.mjs

@@ -0,0 +1,908 @@
+import './utils/env/env.mjs';
+import { parseArgs } from './utils/cli/args.mjs';
+import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
+import { coerceHappyMonorepoRootFromPath, getComponentDir, getRootDir } from './utils/paths/paths.mjs';
+import { getInvokedCwd, inferComponentFromCwd } from './utils/cli/cwd_scope.mjs';
+import { assertCliPrereqs } from './utils/cli/prereqs.mjs';
+import { resolveBaseRef } from './utils/review/base_ref.mjs';
+import { isStackMode, resolveDefaultStackReviewComponents } from './utils/review/targets.mjs';
+import { planCommitChunks } from './utils/review/chunks.mjs';
+import { planPathSlices } from './utils/review/slices.mjs';
+import { createHeadSliceCommits, getChangedOps } from './utils/review/head_slice.mjs';
+import { runWithConcurrencyLimit } from './utils/proc/parallel.mjs';
+import { runCodeRabbitReview } from './utils/review/runners/coderabbit.mjs';
+import { extractCodexReviewFromJsonl, runCodexReview } from './utils/review/runners/codex.mjs';
+import { formatTriageMarkdown, parseCodeRabbitPlainOutput, parseCodexReviewText } from './utils/review/findings.mjs';
+import { join } from 'node:path';
+import { ensureDir } from './utils/fs/ops.mjs';
+import { copyFile, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { runCapture } from './utils/proc/proc.mjs';
+
+const DEFAULT_COMPONENTS = ['happy', 'happy-cli', 'happy-server-light', 'happy-server'];
+const VALID_COMPONENTS = DEFAULT_COMPONENTS;
+const VALID_REVIEWERS = ['coderabbit', 'codex'];
+const VALID_DEPTHS = ['deep', 'normal'];
+const DEFAULT_REVIEW_MAX_FILES = 50;
+
+function parseCsv(raw) {
+  return String(raw ?? '')
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+function normalizeReviewers(list) {
+  const raw = Array.isArray(list) ? list : [];
+  const lower = raw.map((r) => String(r).trim().toLowerCase()).filter(Boolean);
+  const uniq = Array.from(new Set(lower));
+  return uniq.length ? uniq : ['coderabbit'];
+}
+
+function usage() {
+  return [
+    '[review] usage:',
+    '  happys review [component...] [--reviewers=coderabbit,codex] [--base-remote=<remote>] [--base-branch=<branch>] [--base-ref=<ref>] [--concurrency=N] [--depth=deep|normal] [--chunks|--no-chunks] [--chunking=auto|head-slice|commit-window] [--chunk-max-files=N] [--coderabbit-type=committed|uncommitted|all] [--coderabbit-max-files=N] [--coderabbit-chunks|--no-coderabbit-chunks] [--codex-chunks|--no-codex-chunks] [--run-label=<label>] [--no-stream] [--json]',
+    '',
+    'components:',
+    `  ${VALID_COMPONENTS.join(' | ')}`,
+    '',
+    'reviewers:',
+    `  ${VALID_REVIEWERS.join(' | ')}`,
+    '',
+    'depth:',
+    `  ${VALID_DEPTHS.join(' | ')}`,
+    '',
+    'notes:',
+    '- If run from inside a component checkout/worktree and no components are provided, defaults to that component.',
+    '- In stack mode (invoked via `happys stack review <stack>`), if no components are provided, defaults to stack-pinned non-default components only.',
+    '',
+    'examples:',
+    '  happys review',
+    '  happys review happy-cli --reviewers=coderabbit,codex',
+    '  happys stack review exp1 --reviewers=codex',
+    '  happys review happy --base-remote=upstream --base-branch=main',
+  ].join('\n');
+}
+
+function resolveComponentFromCwdOrNull({ rootDir, invokedCwd }) {
+  return inferComponentFromCwd({ rootDir, invokedCwd, components: DEFAULT_COMPONENTS });
+}
+
+function stackRemoteFallbackFromEnv(env) {
+  return String(env.HAPPY_STACKS_STACK_REMOTE ?? env.HAPPY_LOCAL_STACK_REMOTE ?? '').trim();
+}
+
+function sanitizeLabel(raw) {
+  return String(raw ?? '')
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+function tailLines(text, n) {
+  const lines = String(text ?? '')
+    .split('\n')
+    .slice(-n)
+    .join('\n')
+    .trimEnd();
+  return lines;
+}
+
+function printReviewOperatorGuidance() {
+  // Guidance for the human/LLM running the review (not the reviewer model itself).
+  // eslint-disable-next-line no-console
+  console.log(
+    [
+      '[review] operator guidance:',
+      '- Treat reviewer output as suggestions; verify against best practices + this codebase before applying.',
+      '- Triage every single finding (no skipping): apply / adjust / defer-with-rationale.',
+      '- Do not apply changes blindly; when uncertain, record in the report for discussion.',
+      '- When a suggestion references external standards, verify via official docs (or note what you checked).',
+      '- Prefer unified fixes; avoid duplication; avoid brittle tests (no exact wording assertions).',
+      '- This command writes a triage checklist file; work through it item-by-item and record decisions + commits.',
+      '',
+    ].join('\n')
+  );
+}
+
+function codexScopePathForComponent(component) {
+  switch (component) {
+    case 'happy':
+      return 'expo-app';
+    case 'happy-cli':
+      return 'cli';
+    case 'happy-server-light':
+    case 'happy-server':
+      return 'server';
+    default:
+      return null;
+  }
+}
+
+function buildCodexDeepPrompt({ component, baseRef }) {
+  const scopePath = codexScopePathForComponent(component);
+  const diffCmd = scopePath
+    ? `cd \"$(git rev-parse --show-toplevel)\" && git diff ${baseRef}...HEAD -- ${scopePath}/`
+    : `cd \"$(git rev-parse --show-toplevel)\" && git diff ${baseRef}...HEAD`;
+
+  return [
+    'Run a deep, long-form code review.',
+    '',
+    `Base for review: ${baseRef}`,
+    scopePath ? `Scope: ${scopePath}/` : 'Scope: full repo (no path filter)',
+    '',
+    'Instructions:',
+    `- Use: ${diffCmd}`,
+    '- Focus on correctness, edge cases, reliability, performance, and security.',
+    '- Prefer unified/coherent fixes; avoid duplication.',
+    '- Avoid brittle tests that assert on wording/phrasing/config; test real behavior and observable outcomes.',
+    '- Ensure i18n coverage is complete: do not introduce hardcoded user-visible strings; add translation keys across locales as needed.',
+    '- Treat every recommendation as a suggestion: validate it against best practices and this codebase’s existing patterns. Do not propose changes that violate project invariants.',
+    '- Be exhaustive: list all findings you notice, not only the highest-signal ones.',
+    '- Clearly mark any item that is uncertain, has tradeoffs, or needs product/UX decisions as "needs discussion".',
+    '',
+    'Output format:',
+    '- Start with a short overall verdict.',
+    '- Then list findings as bullets with severity (blocker/major/minor/nit) and a concrete fix suggestion.',
+    '',
+    'Machine-readable output (required):',
+    '- After your review, output a JSON array of findings preceded by a line containing exactly: ===FINDINGS_JSON===',
+    '- Each finding should include: severity, file, (optional) lines, title, description, recommendation, needsDiscussion (boolean).',
+  ].join('\n');
+}
+
+function buildCodexMonorepoSlicePrompt({ sliceLabel, baseCommit, baseRef }) {
+  const diffCmd = `cd \"$(git rev-parse --show-toplevel)\" && git diff ${baseCommit}...HEAD`;
+  return [
+    'Run a deep, long-form code review on the monorepo.',
+    '',
+    `Base ref: ${baseRef}`,
+    `Slice: ${sliceLabel}`,
+    '',
+    'Important:',
+    '- The base commit for this slice is synthetic: it represents upstream plus all NON-slice changes.',
+    '- Therefore, the diff below contains ONLY the changes for this slice, but the checked-out code is the full final HEAD.',
+    '',
+    'Instructions:',
+    `- Use: ${diffCmd}`,
+    '- You may inspect any file in the repo for cross-references (server/cli/ui), but keep findings scoped to this slice diff.',
+    '- Focus on correctness, edge cases, reliability, performance, and security.',
+    '- Prefer unified/coherent fixes; avoid duplication.',
+    '- Avoid brittle tests that assert on wording/phrasing/config; test real behavior and observable outcomes.',
+    '- Ensure i18n coverage is complete: do not introduce hardcoded user-visible strings; add translation keys across locales as needed.',
+    '- Treat every recommendation as a suggestion: validate it against best practices and this codebase’s existing patterns. Do not propose changes that violate project invariants.',
+    '- Be exhaustive within this slice: list all findings you notice, not only the highest-signal ones.',
+    '- Clearly mark any item that is uncertain, has tradeoffs, or needs product/UX decisions as "needs discussion".',
+    '',
+    'Output format:',
+    '- Start with a short overall verdict.',
+    '- Then list findings as bullets with severity (blocker/major/minor/nit) and a concrete fix suggestion.',
+    '',
+    'Machine-readable output (required):',
+    '- After your review, output a JSON array of findings preceded by a line containing exactly: ===FINDINGS_JSON===',
+    '- Each finding should include: severity, file, (optional) lines, title, description, recommendation, needsDiscussion (boolean).',
+  ].join('\n');
+}
+
+async function gitLines({ cwd, args, env }) {
+  const out = await runCapture('git', args, { cwd, env });
+  return String(out ?? '')
+    .split('\n')
+    .map((l) => l.trimEnd())
+    .filter(Boolean);
+}
+
+async function countChangedFiles({ cwd, base, env }) {
+  const lines = await gitLines({ cwd, env, args: ['diff', '--name-only', `${base}...HEAD`] });
+  return lines.length;
+}
+
+async function countChangedFilesBetween({ cwd, base, head, env }) {
+  const lines = await gitLines({ cwd, env, args: ['diff', '--name-only', `${base}...${head}`] });
+  return lines.length;
+}
+
+async function mergeBase({ cwd, a, b, env }) {
+  const out = await runCapture('git', ['merge-base', a, b], { cwd, env });
+  const mb = String(out ?? '').trim();
+  if (!mb) throw new Error('[review] failed to compute merge-base');
+  return mb;
+}
+
+async function listCommitsBetween({ cwd, base, head, env }) {
+  return await gitLines({ cwd, env, args: ['rev-list', '--reverse', `${base}..${head}`] });
+}
+
+async function withDetachedWorktree({ repoDir, headCommit, label, env }, 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 safeLabel = String(label ?? 'worktree')
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  const short = String(headCommit).slice(0, 12);
+  const dir = join(root, '.project', 'review-worktrees', `${safeLabel}-${short}`);
+
+  await ensureDir(join(root, '.project', 'review-worktrees'));
+
+  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
+    }
+  }
+}
+
+async function pickCoderabbitBaseCommitForMaxFiles({ cwd, baseRef, maxFiles, env }) {
+  const commits = await gitLines({ cwd, env, args: ['rev-list', '--reverse', `${baseRef}..HEAD`] });
+  if (!commits.length) return null;
+
+  let lo = 0;
+  let hi = commits.length - 1;
+  let best = null;
+
+  while (lo <= hi) {
+    const mid = Math.floor((lo + hi) / 2);
+    const startCommit = commits[mid];
+    let baseCommit = '';
+    try {
+      baseCommit = (await runCapture('git', ['rev-parse', `${startCommit}^`], { cwd, env })).toString().trim();
+    } catch {
+      baseCommit = (await runCapture('git', ['rev-parse', startCommit], { cwd, env })).toString().trim();
+    }
+
+    const n = await countChangedFiles({ cwd, env, base: baseCommit });
+    if (n <= maxFiles) {
+      best = baseCommit;
+      hi = mid - 1;
+    } else {
+      lo = mid + 1;
+    }
+  }
+
+  return best;
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const { flags, kv } = parseArgs(argv);
+  const json = wantsJson(argv, { flags });
+  const stream = !json && !flags.has('--no-stream');
+
+  if (wantsHelp(argv, { flags })) {
+    printResult({ json, data: { usage: usage() }, text: usage() });
+    return;
+  }
+
+  const rootDir = getRootDir(import.meta.url);
+  const invokedCwd = getInvokedCwd(process.env);
+  const positionals = argv.filter((a) => !a.startsWith('--'));
+
+  const reviewers = normalizeReviewers(parseCsv(kv.get('--reviewers') ?? ''));
+  for (const r of reviewers) {
+    if (!VALID_REVIEWERS.includes(r)) {
+      throw new Error(`[review] unknown reviewer: ${r} (expected one of: ${VALID_REVIEWERS.join(', ')})`);
+    }
+  }
+
+  await assertCliPrereqs({
+    git: true,
+    coderabbit: reviewers.includes('coderabbit'),
+    codex: reviewers.includes('codex'),
+  });
+
+  const inferred = positionals.length === 0 ? resolveComponentFromCwdOrNull({ rootDir, invokedCwd }) : null;
+  if (inferred) {
+    // Make downstream getComponentDir() resolve to the inferred repo dir for this run.
+    process.env[`HAPPY_STACKS_COMPONENT_DIR_${inferred.component.toUpperCase().replace(/[^A-Z0-9]+/g, '_')}`] = inferred.repoDir;
+  }
+
+  const inStackMode = isStackMode(process.env);
+  const requestedComponents = positionals.length ? positionals : inferred ? [inferred.component] : ['all'];
+  const wantAll = requestedComponents.includes('all');
+
+  let components = wantAll ? DEFAULT_COMPONENTS : requestedComponents;
+  if (!positionals.length && !inferred && inStackMode) {
+    const pinned = resolveDefaultStackReviewComponents({ rootDir, components: DEFAULT_COMPONENTS });
+    components = pinned.length ? pinned : [];
+  }
+
+  for (const c of components) {
+    if (!VALID_COMPONENTS.includes(c)) {
+      throw new Error(`[review] unknown component: ${c} (expected one of: ${VALID_COMPONENTS.join(', ')})`);
+    }
+  }
+
+  if (!components.length) {
+    const msg = inStackMode ? '[review] no non-default stack-pinned components to review' : '[review] no components selected';
+    printResult({ json, data: { ok: true, skipped: true, reason: msg }, text: msg });
+    return;
+  }
+
+  const baseRefOverride = (kv.get('--base-ref') ?? '').trim();
+  const baseRemoteOverride = (kv.get('--base-remote') ?? '').trim();
+  const baseBranchOverride = (kv.get('--base-branch') ?? '').trim();
+  const stackRemoteFallback = stackRemoteFallbackFromEnv(process.env);
+  const concurrency = (kv.get('--concurrency') ?? '').trim();
+  const limit = concurrency ? Number(concurrency) : 4;
+  const depth = (kv.get('--depth') ?? 'deep').toString().trim().toLowerCase();
+  const coderabbitType = (kv.get('--coderabbit-type') ?? 'committed').toString().trim().toLowerCase();
+  const chunkingMode = (kv.get('--chunking') ?? 'auto').toString().trim().toLowerCase();
+  const chunkMaxFilesRaw = (kv.get('--chunk-max-files') ?? '').toString().trim();
+  const coderabbitMaxFilesRaw = (kv.get('--coderabbit-max-files') ?? '').toString().trim();
+  const coderabbitMaxFiles = coderabbitMaxFilesRaw ? Number(coderabbitMaxFilesRaw) : DEFAULT_REVIEW_MAX_FILES;
+  const chunkMaxFiles = chunkMaxFilesRaw ? Number(chunkMaxFilesRaw) : coderabbitMaxFiles;
+  const globalChunks = flags.has('--chunks') ? true : flags.has('--no-chunks') ? false : null;
+  const coderabbitChunksOverride = flags.has('--coderabbit-chunks')
+    ? true
+    : flags.has('--no-coderabbit-chunks')
+      ? false
+      : null;
+  const codexChunksOverride = flags.has('--codex-chunks') ? true : flags.has('--no-codex-chunks') ? false : null;
+  if (!VALID_DEPTHS.includes(depth)) {
+    throw new Error(`[review] invalid --depth=${depth} (expected: ${VALID_DEPTHS.join(' | ')})`);
+  }
+  if (!['auto', 'head-slice', 'commit-window'].includes(chunkingMode)) {
+    throw new Error('[review] invalid --chunking (expected: auto|head-slice|commit-window)');
+  }
+
+  const deepInstructionsPath = join(rootDir, 'scripts', 'utils', 'review', 'instructions', 'deep.md');
+  const coderabbitConfigFiles = depth === 'deep' ? [deepInstructionsPath] : [];
+
+  if (reviewers.includes('coderabbit')) {
+    const coderabbitHomeKey = 'HAPPY_STACKS_CODERABBIT_HOME_DIR';
+    if (!(process.env[coderabbitHomeKey] ?? '').toString().trim()) {
+      process.env[coderabbitHomeKey] = join(rootDir, '.project', 'coderabbit-home');
+    }
+    await ensureDir(process.env[coderabbitHomeKey]);
+  }
+
+  if (reviewers.includes('codex')) {
+    const codexHomeKey = 'HAPPY_STACKS_CODEX_HOME_DIR';
+    if (!(process.env[codexHomeKey] ?? '').toString().trim()) {
+      process.env[codexHomeKey] = join(rootDir, '.project', 'codex-home');
+    }
+    await ensureDir(process.env[codexHomeKey]);
+
+    if (!(process.env.HAPPY_STACKS_CODEX_SANDBOX ?? '').toString().trim()) {
+      process.env.HAPPY_STACKS_CODEX_SANDBOX = 'workspace-write';
+    }
+
+    // Seed Codex auth/config into the isolated CODEX_HOME to avoid sandbox permission issues
+    // writing under the real ~/.codex. We never print or inspect auth contents.
+    try {
+      const realHome = (process.env.HOME ?? '').toString().trim();
+      const overrideHome = process.env[codexHomeKey];
+      if (realHome && overrideHome && realHome !== overrideHome) {
+        const srcAuth = join(realHome, '.codex', 'auth.json');
+        const srcCfg = join(realHome, '.codex', 'config.toml');
+        const destAuth = join(overrideHome, 'auth.json');
+        const destCfg = join(overrideHome, 'config.toml');
+        if (existsSync(srcAuth) && !existsSync(destAuth)) await copyFile(srcAuth, destAuth);
+        if (existsSync(srcCfg) && !existsSync(destCfg)) await copyFile(srcCfg, destCfg);
+      }
+    } catch {
+      // ignore (codex will surface auth issues if seeding fails)
+    }
+  }
+
+  if (stream) {
+    // eslint-disable-next-line no-console
+    console.log('[review] note: this can take a long time (up to 60+ minutes per reviewer). No timeout is enforced.');
+    printReviewOperatorGuidance();
+  }
+
+  const resolved = components.map((component) => ({ component, repoDir: getComponentDir(rootDir, component) }));
+  const monoRoots = new Set(resolved.map((x) => coerceHappyMonorepoRootFromPath(x.repoDir)).filter(Boolean));
+  if (monoRoots.size > 1) {
+    const roots = Array.from(monoRoots).sort();
+    throw new Error(
+      `[review] multiple monorepo roots detected across selected component dirs:\n` +
+        roots.map((r) => `- ${r}`).join('\n') +
+        `\n\n` +
+        `Fix: ensure all monorepo components (happy/happy-cli/happy-server(-light)) point at the same worktree.\n` +
+        `- Stack mode: use \`happys stack wt <stack> -- use happy <worktree>\` (monorepo-aware)\n` +
+        `- One-shot: pass --happy=... --happy-cli=... --happy-server-light=... all pointing into the same monorepo worktree`
+    );
+  }
+  const monorepoRoot = monoRoots.size === 1 ? Array.from(monoRoots)[0] : null;
+
+  const jobs = monorepoRoot
+    ? [{ component: 'monorepo', repoDir: monorepoRoot, monorepo: true }]
+    : resolved.map((x) => ({ component: x.component, repoDir: x.repoDir, monorepo: false }));
+
+  // Review artifacts: always create a per-run directory containing raw outputs + a triage checklist.
+  const reviewsRootDir = join(rootDir, '.project', 'reviews');
+  await ensureDir(reviewsRootDir);
+  const runLabelOverride = (kv.get('--run-label') ?? '').toString().trim();
+  const ts = new Date().toISOString().replace(/[:.]/g, '-');
+  const stackName = (process.env.HAPPY_STACKS_STACK ?? process.env.HAPPY_LOCAL_STACK ?? '').toString().trim();
+  const defaultLabel = `review-${ts}${stackName ? `-${sanitizeLabel(stackName)}` : ''}`;
+  const runLabel = sanitizeLabel(runLabelOverride || defaultLabel) || defaultLabel;
+  const runDir = join(reviewsRootDir, runLabel);
+  await ensureDir(runDir);
+  await ensureDir(join(runDir, 'raw'));
+
+  const jobResults = await runWithConcurrencyLimit({
+    items: jobs,
+    limit,
+    fn: async (job) => {
+      const { component, repoDir, monorepo } = job;
+      const base = await resolveBaseRef({
+        cwd: repoDir,
+        baseRefOverride,
+        baseRemoteOverride,
+        baseBranchOverride,
+        stackRemoteFallback,
+      });
+
+      const maxFiles = Number.isFinite(chunkMaxFiles) && chunkMaxFiles > 0 ? chunkMaxFiles : 300;
+      const wantChunksCoderabbit = coderabbitChunksOverride ?? globalChunks;
+      const wantChunksCodex = codexChunksOverride ?? globalChunks;
+      const effectiveChunking = chunkingMode === 'auto' ? (monorepo ? 'head-slice' : 'commit-window') : chunkingMode;
+
+      if (monorepo && stream) {
+        // eslint-disable-next-line no-console
+        console.log(`[review] monorepo detected at ${repoDir}; running a single unified review (chunking=${effectiveChunking}).`);
+      }
+
+      const perReviewer = await Promise.all(
+        reviewers.map(async (reviewer) => {
+          if (reviewer === 'coderabbit') {
+            const fileCount = await countChangedFiles({ cwd: repoDir, env: process.env, base: base.baseRef });
+            const autoChunks = fileCount > maxFiles;
+
+            let coderabbitBaseCommit = null;
+            let note = '';
+
+            // Monorepo: prefer HEAD-sliced chunking so each slice is reviewed in the final HEAD state.
+            if (monorepo && effectiveChunking === 'head-slice' && (wantChunksCoderabbit ?? autoChunks)) {
+              const headCommit = (await runCapture('git', ['rev-parse', 'HEAD'], { cwd: repoDir, env: process.env })).trim();
+              const baseCommit = (await runCapture('git', ['rev-parse', base.baseRef], { cwd: repoDir, env: process.env })).trim();
+              const ops = await getChangedOps({ cwd: repoDir, baseRef: baseCommit, headRef: headCommit, env: process.env });
+              const slices = planPathSlices({ changedPaths: Array.from(ops.all), maxFiles });
+
+              const sliceResults = [];
+              for (let i = 0; i < slices.length; i += 1) {
+                const slice = slices[i];
+                const logFile = join(runDir, 'raw', `coderabbit-slice-${i + 1}-of-${slices.length}-${sanitizeLabel(slice.label)}.log`);
+                // eslint-disable-next-line no-await-in-loop
+                const rr = await withDetachedWorktree(
+                  { repoDir, headCommit: baseCommit, label: `coderabbit-${i + 1}-of-${slices.length}`, env: process.env },
+                  async (worktreeDir) => {
+                    const { baseSliceCommit } = await createHeadSliceCommits({
+                      cwd: worktreeDir,
+                      env: process.env,
+                      baseRef: baseCommit,
+                      headCommit,
+                      ops,
+                      slicePaths: slice.paths,
+                      label: slice.label.replace(/\/+$/g, ''),
+                    });
+                    return await runCodeRabbitReview({
+                      repoDir: worktreeDir,
+                      baseRef: null,
+                      baseCommit: baseSliceCommit,
+                      env: process.env,
+                      type: coderabbitType,
+                      configFiles: coderabbitConfigFiles,
+                      streamLabel: stream ? `monorepo:coderabbit:${i + 1}/${slices.length}` : undefined,
+                      teeFile: logFile,
+                      teeLabel: `monorepo:coderabbit:${i + 1}/${slices.length}`,
+                    });
+                  }
+                );
+                sliceResults.push({
+                  index: i + 1,
+                  of: slices.length,
+                  slice: slice.label,
+                  fileCount: slice.paths.length,
+                  logFile,
+                  ok: Boolean(rr.ok),
+                  exitCode: rr.exitCode,
+                  signal: rr.signal,
+                  durationMs: rr.durationMs,
+                  stdout: rr.stdout ?? '',
+                  stderr: rr.stderr ?? '',
+                });
+              }
+
+              const okAll = sliceResults.every((r) => r.ok);
+              return {
+                reviewer,
+                ok: okAll,
+                exitCode: okAll ? 0 : 1,
+                signal: null,
+                durationMs: sliceResults.reduce((acc, r) => acc + (r.durationMs ?? 0), 0),
+                stdout: '',
+                stderr: '',
+                note: `monorepo head-slice: ${sliceResults.length} slices (maxFiles=${maxFiles})`,
+                slices: sliceResults,
+              };
+            }
+
+            // Non-monorepo or non-sliced: optionally chunk by commit windows (older behavior).
+            if (fileCount > maxFiles && effectiveChunking === 'commit-window' && (wantChunksCoderabbit ?? false)) {
+              // fall through to commit-window chunking below
+            } else if (fileCount > maxFiles && (wantChunksCoderabbit === false || wantChunksCoderabbit == null)) {
+              coderabbitBaseCommit = await pickCoderabbitBaseCommitForMaxFiles({
+                cwd: repoDir,
+                env: process.env,
+                baseRef: base.baseRef,
+                maxFiles,
+              });
+              note = coderabbitBaseCommit
+                ? `diff too large (${fileCount} files vs limit ${maxFiles}); using --base-commit ${coderabbitBaseCommit} for a partial review`
+                : `diff too large (${fileCount} files vs limit ${maxFiles}); unable to pick a --base-commit automatically`;
+              // eslint-disable-next-line no-console
+              console.log(`[review] coderabbit: ${note}`);
+            }
+
+            if (!(fileCount > maxFiles && effectiveChunking === 'commit-window' && (wantChunksCoderabbit ?? false))) {
+              const logFile = join(runDir, 'raw', `coderabbit-${sanitizeLabel(component)}.log`);
+              const res = await runCodeRabbitReview({
+                repoDir,
+                baseRef: coderabbitBaseCommit ? null : base.baseRef,
+                baseCommit: coderabbitBaseCommit,
+                env: process.env,
+                type: coderabbitType,
+                configFiles: coderabbitConfigFiles,
+                streamLabel: stream ? `${component}:coderabbit` : undefined,
+                teeFile: logFile,
+                teeLabel: `${component}:coderabbit`,
+              });
+              return {
+                reviewer,
+                ok: Boolean(res.ok),
+                exitCode: res.exitCode,
+                signal: res.signal,
+                durationMs: res.durationMs,
+                stdout: res.stdout ?? '',
+                stderr: res.stderr ?? '',
+                note,
+                logFile,
+              };
+            }
+
+            // Chunked mode: split the commit range into <=maxFiles windows and review each window by
+            // running CodeRabbit in a detached worktree checked out at the window head.
+            const mb = await mergeBase({ cwd: repoDir, env: process.env, a: base.baseRef, b: 'HEAD' });
+            const commits = await listCommitsBetween({ cwd: repoDir, env: process.env, base: mb, head: 'HEAD' });
+            const planned = await planCommitChunks({
+              baseCommit: mb,
+              commits,
+              maxFiles,
+              countFilesBetween: async ({ base: baseCommit, head }) =>
+                await countChangedFilesBetween({ cwd: repoDir, env: process.env, base: baseCommit, head }),
+            });
+
+            const chunks = planned.map((ch) => ({
+              baseCommit: ch.base,
+              headCommit: ch.head,
+              fileCount: ch.fileCount,
+              overLimit: Boolean(ch.overLimit),
+            }));
+
+            const chunkResults = [];
+            for (let i = 0; i < chunks.length; i += 1) {
+              const ch = chunks[i];
+              const logFile = join(
+                runDir,
+                'raw',
+                `coderabbit-${sanitizeLabel(component)}-window-${i + 1}-of-${chunks.length}-${String(ch.headCommit).slice(0, 12)}.log`
+              );
+              // eslint-disable-next-line no-await-in-loop
+              const rr = await withDetachedWorktree(
+                { repoDir, headCommit: ch.headCommit, label: `coderabbit-${component}-${i + 1}-of-${chunks.length}`, env: process.env },
+                async (worktreeDir) => {
+                  return await runCodeRabbitReview({
+                    repoDir: worktreeDir,
+                    baseRef: null,
+                    baseCommit: ch.baseCommit,
+                    env: process.env,
+                    type: coderabbitType,
+                    configFiles: coderabbitConfigFiles,
+                    streamLabel: stream ? `${component}:coderabbit:${i + 1}/${chunks.length}` : undefined,
+                    teeFile: logFile,
+                    teeLabel: `${component}:coderabbit:${i + 1}/${chunks.length}`,
+                  });
+                }
+              );
+              chunkResults.push({
+                index: i + 1,
+                of: chunks.length,
+                baseCommit: ch.baseCommit,
+                headCommit: ch.headCommit,
+                fileCount: ch.fileCount,
+                overLimit: ch.overLimit,
+                logFile,
+                ok: Boolean(rr.ok),
+                exitCode: rr.exitCode,
+                signal: rr.signal,
+                durationMs: rr.durationMs,
+                stdout: rr.stdout ?? '',
+                stderr: rr.stderr ?? '',
+              });
+            }
+
+            const okAll = chunkResults.every((r) => r.ok);
+            return {
+              reviewer,
+              ok: okAll,
+              exitCode: okAll ? 0 : 1,
+              signal: null,
+              durationMs: chunkResults.reduce((acc, r) => acc + (r.durationMs ?? 0), 0),
+              stdout: '',
+              stderr: '',
+              note: `chunked: ${chunkResults.length} windows (maxFiles=${maxFiles})`,
+              chunks: chunkResults,
+            };
+          }
+          if (reviewer === 'codex') {
+            const jsonMode = json;
+            const usePromptMode = depth === 'deep';
+            const fileCount = await countChangedFiles({ cwd: repoDir, env: process.env, base: base.baseRef });
+            const autoChunks = usePromptMode && fileCount > maxFiles;
+
+            if (monorepo && effectiveChunking === 'head-slice' && usePromptMode && (wantChunksCodex ?? autoChunks)) {
+              const headCommit = (await runCapture('git', ['rev-parse', 'HEAD'], { cwd: repoDir, env: process.env })).trim();
+              const baseCommit = (await runCapture('git', ['rev-parse', base.baseRef], { cwd: repoDir, env: process.env })).trim();
+              const ops = await getChangedOps({ cwd: repoDir, baseRef: baseCommit, headRef: headCommit, env: process.env });
+              const slices = planPathSlices({ changedPaths: Array.from(ops.all), maxFiles });
+
+              const sliceResults = [];
+              for (let i = 0; i < slices.length; i += 1) {
+                const slice = slices[i];
+                const logFile = join(runDir, 'raw', `codex-slice-${i + 1}-of-${slices.length}-${sanitizeLabel(slice.label)}.log`);
+                // eslint-disable-next-line no-await-in-loop
+                const rr = await withDetachedWorktree(
+                  { repoDir, headCommit: baseCommit, label: `codex-${i + 1}-of-${slices.length}`, env: process.env },
+                  async (worktreeDir) => {
+                    const { baseSliceCommit } = await createHeadSliceCommits({
+                      cwd: worktreeDir,
+                      env: process.env,
+                      baseRef: baseCommit,
+                      headCommit,
+                      ops,
+                      slicePaths: slice.paths,
+                      label: slice.label.replace(/\/+$/g, ''),
+                    });
+                    const prompt = buildCodexMonorepoSlicePrompt({ sliceLabel: slice.label, baseCommit: baseSliceCommit, baseRef: base.baseRef });
+                    return await runCodexReview({
+                      repoDir: worktreeDir,
+                      baseRef: null,
+                      env: process.env,
+                      jsonMode,
+                      prompt,
+                      streamLabel: stream && !jsonMode ? `monorepo:codex:${i + 1}/${slices.length}` : undefined,
+                      teeFile: logFile,
+                      teeLabel: `monorepo:codex:${i + 1}/${slices.length}`,
+                    });
+                  }
+                );
+                const extracted = jsonMode ? extractCodexReviewFromJsonl(rr.stdout ?? '') : null;
+                sliceResults.push({
+                  index: i + 1,
+                  of: slices.length,
+                  slice: slice.label,
+                  fileCount: slice.paths.length,
+                  logFile,
+                  ok: Boolean(rr.ok),
+                  exitCode: rr.exitCode,
+                  signal: rr.signal,
+                  durationMs: rr.durationMs,
+                  stdout: rr.stdout ?? '',
+                  stderr: rr.stderr ?? '',
+                  review_output: extracted,
+                });
+              }
+
+              const okAll = sliceResults.every((r) => r.ok);
+              return {
+                reviewer,
+                ok: okAll,
+                exitCode: okAll ? 0 : 1,
+                signal: null,
+                durationMs: sliceResults.reduce((acc, r) => acc + (r.durationMs ?? 0), 0),
+                stdout: '',
+                stderr: '',
+                note: `monorepo head-slice: ${sliceResults.length} slices (maxFiles=${maxFiles})`,
+                slices: sliceResults,
+              };
+            }
+
+            const prompt = usePromptMode ? buildCodexDeepPrompt({ component, baseRef: base.baseRef }) : '';
+            const logFile = join(runDir, 'raw', `codex-${sanitizeLabel(component)}.log`);
+            const res = await runCodexReview({
+              repoDir,
+              baseRef: usePromptMode ? null : base.baseRef,
+              env: process.env,
+              jsonMode,
+              prompt,
+              streamLabel: stream && !jsonMode ? `${component}:codex` : undefined,
+              teeFile: logFile,
+              teeLabel: `${component}:codex`,
+            });
+            const extracted = jsonMode ? extractCodexReviewFromJsonl(res.stdout ?? '') : null;
+            return {
+              reviewer,
+              ok: Boolean(res.ok),
+              exitCode: res.exitCode,
+              signal: res.signal,
+              durationMs: res.durationMs,
+              stdout: res.stdout ?? '',
+              stderr: res.stderr ?? '',
+              review_output: extracted,
+              logFile,
+            };
+          }
+          return { reviewer, ok: false, exitCode: null, signal: null, durationMs: 0, stdout: '', stderr: 'unknown reviewer\n' };
+        })
+      );
+
+      return { component, repoDir, base, results: perReviewer };
+    },
+  });
+
+  // Persist a structured triage checklist for the operator (human/LLM) to work through.
+  try {
+    const meta = {
+      runLabel,
+      startedAt: ts,
+      stackName: stackName || null,
+      reviewers,
+      jobs: jobs.map((j) => ({ component: j.component, repoDir: j.repoDir, monorepo: j.monorepo })),
+      depth,
+      chunkMaxFiles: Number.isFinite(chunkMaxFiles) ? chunkMaxFiles : null,
+      coderabbitMaxFiles,
+      chunkingMode,
+      argv,
+    };
+    await writeFile(join(runDir, 'meta.json'), JSON.stringify(meta, null, 2), 'utf-8');
+
+    const allFindings = [];
+    let cr = 0;
+    let cx = 0;
+
+    for (const job of jobResults) {
+      for (const rr of job.results) {
+        if (rr.reviewer === 'coderabbit') {
+          const sliceLike = rr.slices ?? rr.chunks ?? null;
+          if (Array.isArray(sliceLike)) {
+            for (const s of sliceLike) {
+              const parsed = parseCodeRabbitPlainOutput(s.stdout ?? '');
+              for (const f of parsed) {
+                cr += 1;
+                allFindings.push({
+                  ...f,
+                  id: `CR-${String(cr).padStart(3, '0')}`,
+                  job: job.component,
+                  slice: s.slice ?? `${s.index}/${s.of}`,
+                  sourceLog: s.logFile ?? null,
+                });
+              }
+            }
+          } else {
+            const parsed = parseCodeRabbitPlainOutput(rr.stdout ?? '');
+            for (const f of parsed) {
+              cr += 1;
+              allFindings.push({
+                ...f,
+                id: `CR-${String(cr).padStart(3, '0')}`,
+                job: job.component,
+                slice: null,
+                sourceLog: rr.logFile ?? null,
+              });
+            }
+          }
+        }
+
+        if (rr.reviewer === 'codex') {
+          const sliceLike = rr.slices ?? rr.chunks ?? null;
+          const consumeText = (reviewText, slice, sourceLog) => {
+            const parsed = parseCodexReviewText(reviewText);
+            for (const f of parsed) {
+              cx += 1;
+              allFindings.push({
+                ...f,
+                id: `CX-${String(cx).padStart(3, '0')}`,
+                job: job.component,
+                slice,
+                sourceLog: sourceLog ?? null,
+              });
+            }
+          };
+
+          if (Array.isArray(sliceLike)) {
+            for (const s of sliceLike) {
+              const reviewText = s.review_output ?? extractCodexReviewFromJsonl(s.stdout ?? '') ?? (s.stdout ?? '');
+              consumeText(reviewText, s.slice ?? `${s.index}/${s.of}`, s.logFile ?? null);
+            }
+          } else {
+            const reviewText = rr.review_output ?? extractCodexReviewFromJsonl(rr.stdout ?? '') ?? (rr.stdout ?? '');
+            consumeText(reviewText, null, rr.logFile ?? null);
+          }
+        }
+      }
+    }
+
+    await writeFile(join(runDir, 'findings.json'), JSON.stringify(allFindings, null, 2), 'utf-8');
+    const triage = formatTriageMarkdown({ runLabel, baseRef: jobResults?.[0]?.base?.baseRef ?? '', findings: allFindings });
+    await writeFile(join(runDir, 'triage.md'), triage, 'utf-8');
+
+    if (stream) {
+      // eslint-disable-next-line no-console
+      console.log(`[review] trust/triage checklist (READ THIS NEXT): ${join(runDir, 'triage.md')}`);
+      // eslint-disable-next-line no-console
+      console.log(`[review] findings (raw, parsed): ${join(runDir, 'findings.json')}`);
+      // eslint-disable-next-line no-console
+      console.log(`[review] raw outputs: ${join(runDir, 'raw')}`);
+      // eslint-disable-next-line no-console
+      console.log(
+        [
+          '[review] next steps (mandatory):',
+          `- STOP: open ${join(runDir, 'triage.md')} now and load it into your context before doing anything else.`,
+          `- Then load ${join(runDir, 'findings.json')} (full parsed finding details + source logs).`,
+          `- Treat reviewer output as suggestions: verify against codebase invariants + best practices (use web search when needed) before applying.`,
+          `- For each finding: verify in the validation worktree, decide apply/adjust/defer, and record rationale + commit refs in triage.md.`,
+          `- For tests: validate behavior/logic; avoid brittle "wording/policing" assertions.`,
+          `- Do not start a new review run until the checklist has no remaining TBD decisions.`,
+        ].join('\n')
+      );
+    }
+  } catch (e) {
+    if (stream) {
+      // eslint-disable-next-line no-console
+      console.warn('[review] warning: failed to write triage artifacts:', e);
+    }
+  }
+
+  const ok = jobResults.every((r) => r.results.every((x) => x.ok));
+  if (json) {
+    printResult({ json, data: { ok, reviewers, components, results: jobResults } });
+    if (!ok) process.exit(1);
+    return;
+  }
+
+  const lines = [];
+  lines.push('[review] results:');
+  for (const r of jobResults) {
+    lines.push('============================================================================');
+    lines.push(`component: ${r.component}`);
+    lines.push(`dir: ${r.repoDir}`);
+    lines.push(`baseRef: ${r.base.baseRef}`);
+    for (const rr of r.results) {
+      lines.push('');
+      const status = rr.ok ? '✅ ok' : '❌ failed';
+      lines.push(`[${rr.reviewer}] ${status} (exit=${rr.exitCode ?? 'null'} durMs=${rr.durationMs ?? '?'})`);
+      if (rr.note) lines.push(`note: ${rr.note}`);
+      if (!rr.ok) {
+        if (rr.stderr) {
+          lines.push('--- stderr (tail) ---');
+          lines.push(tailLines(rr.stderr, 120));
+        }
+        if (rr.stdout) {
+          lines.push('--- stdout (tail) ---');
+          lines.push(tailLines(rr.stdout, 120));
+        }
+      }
+    }
+    lines.push('');
+  }
+  lines.push(ok ? '[review] ok' : '[review] failed');
+  printResult({ json: false, text: lines.join('\n') });
+  if (!ok) process.exit(1);
+}
+
+main().catch((err) => {
+  console.error('[review] failed:', err);
+  process.exit(1);
+});