@expo/code-review-cli 0.3.0 → 0.5.0

package/build/core/review.js

@@ -1,18 +1,31 @@
-import path from 'node:path';
-import { prepareAuth } from './auth.js';
-import { coordinate } from './coordinator.js';
-import { writeRunLog } from './log.js';
-import { filterNoise, writePatchWorkspace } from './noise.js';
-import { addTokenUsage, AgentTimeoutError, buildOpencodeConfig, CROSS_CUTTING_AGENT, promptAndParse, startOpencode, } from './opencode.js';
-import { routeAgents } from './router.js';
-import { buildCrossCuttingSystem, buildCrossCuttingTask, buildReviewerSystem, buildReviewerTask, NO_TOOLS_INSTRUCTION, } from './prompts.js';
-import { fingerprintFinding, parseReviewerOutput } from './schema.js';
-import { sortFindings } from './render.js';
-import { errorMessage, sleep } from './util.js';
-import { verifyFindings } from './verify.js';
-import { applyInlineIgnores } from './suppress.js';
+import path from "node:path";
+import { prepareAuth } from "./auth.js";
+import { coordinate } from "./coordinator.js";
+import { writeRunLog } from "./log.js";
+import { filterNoise, writePatchWorkspace } from "./noise.js";
+import { addTokenUsage, AgentTimeoutError, assertModelsResolvable, buildOpencodeConfig, CROSS_CUTTING_AGENT, promptAndParse, startOpencode, } from "./opencode.js";
+import { routeAgents } from "./router.js";
+import { buildCrossCuttingSystem, buildCrossCuttingTask, buildReviewerSystem, buildReviewerTask, NO_TOOLS_INSTRUCTION, } from "./prompts.js";
+import { fingerprintFinding, parseReviewerOutput } from "./schema.js";
+import { sortFindings } from "./render.js";
+import { appendStepSummary } from "./step-summary.js";
+import { errorMessage, sleep } from "./util.js";
+import { verifyFindings } from "./verify.js";
+import { applyInlineIgnores } from "./suppress.js";
+/**
+ * Filter changed files down to an explicit include set (exact-path membership, not
+ * globs — scope assignment already happened in resolveScopes). With no include set,
+ * returns the input unchanged so the non-routed path is byte-identical.
+ */
+export function filterByIncludePaths(files, includePaths) {
+    if (!includePaths) {
+        return files;
+    }
+    const included = new Set(includePaths);
+    return files.filter((file) => included.has(file.path));
+}
 function makeRunId() {
-    return new Date().toISOString().replace(/[:.]/g, '-');
+    return new Date().toISOString().replace(/[:.]/g, "-");
 }
 /**
  * The invariant, mode-agnostic review core: filter → spawn each configured agent
@@ -24,9 +37,9 @@ export async function runReview(source, options) {
     const started = Date.now();
     const runId = makeRunId();
     const progress = options.onProgress ?? (() => { });
-    const runsRoot = path.join(config.configDir, '.runs');
+    const runsRoot = path.join(config.configDir, ".runs");
     const runDir = path.join(runsRoot, runId);
-    const logPath = path.join(runsRoot, 'reviews.jsonl');
+    const logPath = path.join(runsRoot, "reviews.jsonl");
     // Fail fast on an invalid explicit selection before doing any work. Routing
     // (if requested) is resolved later, once the server is up.
     const explicitAgents = options.agents?.length
@@ -36,24 +49,27 @@ export async function runReview(source, options) {
         source.getMetadata(),
         source.getChangedFiles(),
     ]);
-    const { kept, filtered } = await filterNoise(changedFiles, {
+    // Scope isolation: when includePaths is set, this run only ever sees its own
+    // scope's files — no scope reviews another team's diff.
+    const scopedFiles = filterByIncludePaths(changedFiles, options.includePaths);
+    const { kept, filtered } = await filterNoise(scopedFiles, {
         additionalIgnores: config.noise.additionalIgnores,
         additionalMarkers: config.noise.additionalMarkers,
     });
-    progress(`${changedFiles.length} changed file(s); ${kept.length} to review, ${filtered.length} filtered.`);
+    progress(`${scopedFiles.length} changed file(s); ${kept.length} to review, ${filtered.length} filtered.`);
     const baseRecord = {
         timestamp: new Date().toISOString(),
         mode: options.mode,
         runId,
         metadata: { baseRef: metadata.baseRef, headRef: metadata.headRef },
-        reviewedFiles: kept.map(entry => entry.path),
+        reviewedFiles: kept.map((entry) => entry.path),
         filteredFiles: filtered,
     };
     if (kept.length === 0) {
         const output = {
-            decision: 'approve',
+            decision: "approve",
             findings: [],
-            summary: 'No reviewable changes after noise filtering.',
+            summary: "No reviewable changes after noise filtering.",
             incomplete: [],
         };
         await safeLog(logPath, {
@@ -86,10 +102,10 @@ export async function runReview(source, options) {
         }
     };
     if (readRoot) {
-        progress('Reviewing the PR-head tree (so reads match the PR, not the checkout).');
+        progress("Reviewing the PR-head tree (so reads match the PR, not the checkout).");
         process.chdir(readRoot.dir);
     }
-    progress('Starting OpenCode server…');
+    progress("Starting OpenCode server…");
     let handle = null;
     try {
         handle = await startOpencode(buildOpencodeConfig(config));
@@ -98,22 +114,62 @@ export async function runReview(source, options) {
         await auth.cleanup();
         await restoreCwd();
         throw new Error(`Failed to start the OpenCode server. Ensure the \`opencode\` CLI is installed and ` +
-            `model credentials are configured.\n${errorMessage(error)}`);
+            `model credentials are configured (\`ecr doctor\` checks both).\n${errorMessage(error)}`);
+    }
+    // Preflight: a model id the server can't resolve would otherwise fail EVERY pass
+    // identically — N indistinguishable coverage gaps, after spending the run's budget
+    // discovering the same fixable thing N times. Throw once, up front, naming the fix.
+    try {
+        await assertModelsResolvable(handle, [...config.agents.map((agent) => agent.model), config.coordinator.model], config.auth);
+    }
+    catch (error) {
+        handle.close();
+        await auth.cleanup();
+        await restoreCwd();
+        throw error;
     }
     const agentCosts = {};
     const tokenTotals = {};
+    const agentTokens = {};
+    // Declared outside the try so the error-path log still carries whatever the
+    // reviewers produced before the failure — partial findings are exactly what's
+    // needed to debug a run that died mid-way.
+    const agentFindings = {};
+    // Every model request's usage lands in the run total AND its bucket, so the run
+    // log can show cache effectiveness per pass and not just run-wide.
+    const trackTokens = (bucket, tokens) => {
+        addTokenUsage(tokenTotals, tokens);
+        addTokenUsage((agentTokens[bucket] ??= {}), tokens);
+    };
+    // The provider/model that ACTUALLY answered each pass, and any pass whose model was
+    // silently substituted for the configured one. OpenCode does that substitution
+    // quietly whenever an agent's model id is empty or unusable, so a run can review with
+    // a different model than config.jsonc names and look completely normal — which is
+    // exactly what happened for weeks behind an empty REVIEWER_MODEL. Recorded in the run
+    // log, reported in the log line, and surfaced as a coverage note when it happens.
+    const agentModels = {};
+    const substituted = new Set();
+    const trackModel = (bucket, configured, actual) => {
+        if (!actual) {
+            return;
+        }
+        agentModels[bucket] = actual;
+        if (configured && actual !== configured) {
+            substituted.add(`${bucket}: configured ${configured}, ran ${actual}`);
+        }
+    };
     try {
         const workspace = await writePatchWorkspace(kept, metadata, runDir);
         // Resolve which agents run: an explicit list wins; otherwise route (LLM picks
         // relevant agents + always-run) when asked, else all.
         let selectedAgents = explicitAgents ?? config.agents;
         if (!explicitAgents && options.route) {
-            progress('Routing: selecting relevant agents…');
+            progress("Routing: selecting relevant agents…");
             const routed = await routeAgents(handle, config, workspace.files);
             selectedAgents = routed.agents;
             progress(routed.routed
-                ? `Router selected: ${selectedAgents.map(a => a.id).join(', ')}`
-                : 'Router unavailable; running all agents.');
+                ? `Router selected: ${selectedAgents.map((a) => a.id).join(", ")}`
+                : "Router unavailable; running all agents.");
         }
         // Split the diff into focused chunks so each reviewer call sees a small file
         // set (better recall than one giant blob), and run all agent×chunk calls
@@ -121,10 +177,9 @@ export async function runReview(source, options) {
         const chunks = chunkByLines(workspace.files, config.chunk.maxChangedLines, config.chunk.maxFiles);
         // Only chunk (and add a cross-cutting pass) when the diff exceeds one chunk.
         const chunked = chunks.length > 1;
-        progress(`Running ${selectedAgents.length} reviewer(s) [${selectedAgents.map(a => a.id).join(', ')}] over ${chunks.length} chunk(s)` +
-            `${chunked ? ' + cross-cutting pass' : ''} ` +
+        progress(`Running ${selectedAgents.length} reviewer(s) [${selectedAgents.map((a) => a.id).join(", ")}] over ${chunks.length} chunk(s)` +
+            `${chunked ? " + cross-cutting pass" : ""} ` +
             `(${kept.length} files, concurrency ${config.chunk.concurrency})…`);
-        const agentFindings = {};
         for (const agent of selectedAgents) {
             agentFindings[agent.id] = [];
             agentCosts[agent.id] = 0;
@@ -132,7 +187,6 @@ export async function runReview(source, options) {
         // These caps must fit inside PASSES_BUDGET_MS (below), which in turn fits inside
         // the CI job's timeout-minutes.
         const CHUNK_TIMEOUT_MS = 15 * 60 * 1000;
-        const CROSS_CUTTING_TIMEOUT_MS = 25 * 60 * 1000;
         // A subdivided sub-chunk is smaller, so it gets a shorter cap (halved per level,
         // floored) — enough to converge without letting the recursion balloon.
         const SUBDIVIDE_MIN_TIMEOUT_MS = 6 * 60 * 1000;
@@ -142,25 +196,62 @@ export async function runReview(source, options) {
         // Tool-call ceilings — generous for a legitimate pass, low enough to catch
         // runaway roaming (the root cause of the non-convergent timeouts).
         const CHUNK_MAX_TOOL_CALLS = 50;
-        const CROSS_CUTTING_MAX_TOOL_CALLS = 120;
         // Global ceiling for ALL passes incl. subdivision/fallback waves, sized to
         // leave room for the coordinator (10m) + verification + overhead inside the CI
         // job timeout. Past this, a timed-out pass is reported as a gap rather than
         // broken down further, so total wall-clock stays bounded.
-        const PASSES_BUDGET_MS = 32 * 60 * 1000;
-        const passesDeadline = started + PASSES_BUDGET_MS;
+        const PASSES_BUDGET_MS = 55 * 60 * 1000;
+        const passesBudgetMs = options.passesBudgetMs ?? PASSES_BUDGET_MS;
+        const passesDeadline = started + passesBudgetMs;
+        // The cross-file pass is the one pass whose scope cannot be traded for
+        // convergence: halving its file set deletes exactly the coverage it exists to
+        // provide (see the timeout branch below). So instead of a fixed cap it gets the
+        // WHOLE remaining passes window. Chunk passes run concurrently alongside it under
+        // their own caps, so a long cross-file pass doesn't starve them — it only extends
+        // the run toward the passes deadline, which the job timeout is sized for.
+        //
+        // Computed here, not as a constant, because the window is what's actually left:
+        // filtering, routing and server startup already spent some of it, and `ecr ci`
+        // divides the budget across active scopes.
+        //
+        // The reserve is what keeps its own salvage paths affordable: if it expanded into
+        // the entire window, then on a timeout there would be nothing left to run the
+        // whole-diff no-tools fallback with, and "elastic budget" would have quietly
+        // reintroduced the coverage gap it exists to prevent. Sized for the finalize
+        // soft-landing plus one FALLBACK_TIMEOUT_MS pass.
+        const CROSS_CUTTING_RESERVE_MS = FALLBACK_TIMEOUT_MS + 4 * 60 * 1000;
+        // Floor: never LESS generous than one chunk pass. On a run whose window is already
+        // small (many active scopes dividing the budget) this can exceed what's left, but
+        // that exposure is exactly what chunk passes already carry — their 15m cap can also
+        // outlast a small per-scope slice — and the job timeout keeps a wide margin over
+        // the budget for it. Dropping the pass instead would silently cost the coverage no
+        // other pass provides.
+        const crossCuttingWaitMs = Math.max(CHUNK_TIMEOUT_MS, passesDeadline - Date.now() - CROSS_CUTTING_RESERVE_MS);
+        // Tool calls are for TRACING (opening the caller a changed signature affects) —
+        // the changed files' diffs are inlined, so they are not spent fetching the diff.
+        // Scale with the diff's file count instead of fixing the ceiling: under a large
+        // elastic time budget a fixed cap becomes the binding constraint, and the extra
+        // time can't be used.
+        const CROSS_CUTTING_TOOL_CALLS_PER_FILE = 10;
+        const CROSS_CUTTING_MIN_TOOL_CALLS = 120;
+        const CROSS_CUTTING_MAX_TOOL_CALLS = 400;
+        const crossCuttingMaxToolCalls = Math.min(CROSS_CUTTING_MAX_TOOL_CALLS, Math.max(CROSS_CUTTING_MIN_TOOL_CALLS, CROSS_CUTTING_TOOL_CALLS_PER_FILE * workspace.files.length));
+        // Coverage notes for passes that hit their time limit, stalled, failed, or were
+        // never started, surfaced in the final review so a cut-short run is never
+        // presented as complete.
+        const incomplete = [];
         const tasks = [];
         for (const agent of selectedAgents) {
             const system = buildReviewerSystem(config, agent);
             chunks.forEach((chunk, index) => {
                 tasks.push({
                     bucket: agent.id,
-                    kind: 'reviewer',
+                    kind: "reviewer",
                     system,
                     label: chunked ? `${agent.id} [${index + 1}/${chunks.length}]` : agent.id,
                     title: `review-${agent.id}-c${index}`,
                     files: chunk,
-                    coverageLabel: `the ${agent.id} review${chunked ? ` (part ${index + 1} of ${chunks.length})` : ''}`,
+                    coverageLabel: `the ${agent.id} review${chunked ? ` (part ${index + 1} of ${chunks.length})` : ""}`,
                     maxWaitMs: CHUNK_TIMEOUT_MS,
                     maxToolCalls: CHUNK_MAX_TOOL_CALLS,
                     depth: 0,
@@ -173,14 +264,14 @@ export async function runReview(source, options) {
         if (chunked) {
             tasks.push({
                 bucket: CROSS_CUTTING_AGENT,
-                kind: 'cross-cutting',
-                system: buildCrossCuttingSystem(config, selectedAgents),
-                label: 'cross-file',
-                title: 'review-xcut',
+                kind: "cross-cutting",
+                system: buildCrossCuttingSystem(config),
+                label: "cross-file",
+                title: "review-xcut",
                 files: workspace.files,
-                coverageLabel: 'the cross-file review (issues spanning multiple changed files)',
-                maxWaitMs: CROSS_CUTTING_TIMEOUT_MS,
-                maxToolCalls: CROSS_CUTTING_MAX_TOOL_CALLS,
+                coverageLabel: "the cross-file review (issues spanning multiple changed files)",
+                maxWaitMs: crossCuttingWaitMs,
+                maxToolCalls: crossCuttingMaxToolCalls,
                 depth: 0,
                 fallback: false,
             });
@@ -188,18 +279,26 @@ export async function runReview(source, options) {
         // Longest-processing-time-first: schedule the long cross-cutting/large chunks
         // ahead of short ones so they don't dominate the tail of the makespan.
         tasks.sort((a, b) => b.maxWaitMs - a.maxWaitMs);
+        // What each task was CONFIGURED to run on — mirrors buildOpencodeConfig, which
+        // gives the cross-file pass the first agent's model. Compared against what actually
+        // answered so a silent substitution can't pass unnoticed.
+        const taskModel = (task) => task.kind === "cross-cutting"
+            ? (selectedAgents[0]?.model ?? config.coordinator.model)
+            : (selectedAgents.find((agent) => agent.id === task.bucket)?.model ?? "");
         // Build the task prompt on demand (so a subdivided task rebuilds over its
         // smaller file set); a fallback task forbids tools and reviews the inlined diff.
         const buildTaskText = (task) => {
-            const base = task.kind === 'cross-cutting'
-                ? buildCrossCuttingTask(task.files, filtered)
+            const base = task.kind === "cross-cutting"
+                ? buildCrossCuttingTask(task.files, selectedAgents, filtered, {
+                    noTools: task.fallback,
+                })
                 : buildReviewerTask(task.files, workspace.files, filtered);
             return task.fallback ? `${base}\n\n${NO_TOOLS_INSTRUCTION}` : base;
         };
         const filesLabel = (files) => files.length === 1
             ? `\`${files[0].path}\``
             : `${files.length} files (e.g. \`${files[0].path}\`)`;
-        const humanBucket = (bucket) => bucket === CROSS_CUTTING_AGENT ? 'cross-file' : bucket;
+        const humanBucket = (bucket) => bucket === CROSS_CUTTING_AGENT ? "cross-file" : bucket;
         const childTask = (parent, files, labelSuffix, overrides) => ({
             ...parent,
             files,
@@ -207,9 +306,6 @@ export async function runReview(source, options) {
             coverageLabel: `the ${humanBucket(parent.bucket)} review of ${filesLabel(files)}`,
             ...overrides,
         });
-        // Coverage notes for passes that hit their time limit or failed, surfaced in
-        // the final review so a cut-short run is never presented as complete.
-        const incomplete = [];
         let completedPasses = 0;
         let failedPasses = 0;
         // promptAndParse already retries internally (same-session corrective, then a
@@ -220,18 +316,19 @@ export async function runReview(source, options) {
         await runGrowableQueue(tasks, config.chunk.concurrency, async (task, enqueue) => {
             const minutes = Math.round(task.maxWaitMs / 60000);
             try {
-                const { value, cost, truncated, tokens } = await promptAndParse(handle, {
+                const { value, cost, truncated, tokens, model } = await promptAndParse(handle, {
                     agent: task.bucket,
                     system: task.system,
                     text: buildTaskText(task),
                     title: task.title,
-                    onActivity: line => progress(`  ${task.label}: ${line}`),
+                    onActivity: (line) => progress(`  ${task.label}: ${line}`),
                     maxWaitMs: task.maxWaitMs,
                     maxToolCalls: task.maxToolCalls,
                     finalizeOnTimeout: true,
                 }, parseReviewerOutput);
                 agentCosts[task.bucket] = (agentCosts[task.bucket] ?? 0) + cost;
-                addTokenUsage(tokenTotals, tokens);
+                trackTokens(task.bucket, tokens);
+                trackModel(task.bucket, taskModel(task), model);
                 (agentFindings[task.bucket] ??= []).push(...value.findings);
                 completedPasses++;
                 if (truncated) {
@@ -255,13 +352,17 @@ export async function runReview(source, options) {
                 }
                 // Account for the abandoned investigation's spend regardless of what's next.
                 agentCosts[task.bucket] = (agentCosts[task.bucket] ?? 0) + error.cost;
-                addTokenUsage(tokenTotals, error.tokens);
+                trackTokens(task.bucket, error.tokens);
                 const remaining = passesDeadline - Date.now();
-                // Cross-file analysis needs ≥2 files to be meaningful; a single-file
-                // reviewer chunk can't be split further.
-                const minFiles = task.kind === 'cross-cutting' ? 2 : 1;
+                // Subdividing trades scope for convergence, which is the right trade for a
+                // reviewer chunk (each file still gets reviewed) and the WRONG one for the
+                // cross-file pass: an interaction between a file in the left half and one in
+                // the right half is invisible to both halves, so "splitting" it silently
+                // deletes the coverage the pass exists to provide while reporting success.
+                // It goes straight to the whole-diff no-tools fallback below instead.
+                const canSubdivide = task.kind === "reviewer" && task.files.length > 1;
                 const childCap = Math.max(SUBDIVIDE_MIN_TIMEOUT_MS, Math.floor(task.maxWaitMs / 2));
-                if (task.files.length > minFiles && task.depth < MAX_SUBDIVIDE_DEPTH && remaining > childCap) {
+                if (canSubdivide && task.depth < MAX_SUBDIVIDE_DEPTH && remaining > childCap) {
                     const mid = Math.ceil(task.files.length / 2);
                     const left = task.files.slice(0, mid);
                     const right = task.files.slice(mid);
@@ -271,11 +372,14 @@ export async function runReview(source, options) {
                     enqueue(childTask(task, right, `↳${right.length}f`, over));
                     return;
                 }
-                // Can't subdivide further: try a fast no-tools pass over the inlined diff
-                // (reviewer only — cross-file analysis fundamentally needs to read files).
-                if (task.kind === 'reviewer' && !task.fallback && remaining > FALLBACK_TIMEOUT_MS) {
+                // Can't (or shouldn't) subdivide: fall back to a fast no-tools pass over the
+                // inlined diffs. This works for the cross-file pass too — every changed file's
+                // diff is inlined in its task, so it can still reason across the whole diff
+                // without tools; it just can't open a caller outside the diff. A lighter
+                // cross-file review beats the coverage gap it used to report.
+                if (!task.fallback && remaining > FALLBACK_TIMEOUT_MS) {
                     progress(`  ${task.label}: exceeded ${minutes}m — retrying ${filesLabel(task.files)} with a fast no-tools pass`);
-                    enqueue(childTask(task, task.files, '(no-tools fallback)', {
+                    enqueue(childTask(task, task.files, "(no-tools fallback)", {
                         fallback: true,
                         maxWaitMs: FALLBACK_TIMEOUT_MS,
                         maxToolCalls: 0,
@@ -286,10 +390,24 @@ export async function runReview(source, options) {
                 // never silent. Distinguish WHY so the note doesn't overstate what happened:
                 // we could still have split/fallen back, but the global budget ran out first,
                 // vs. the task was already at its smallest reviewable unit and still failed.
+                // A stalled pass is called out separately: it did not run out of time doing
+                // work, its model requests went silent, which is an infrastructure symptom
+                // and not something a bigger budget or a smaller scope would have fixed.
                 failedPasses++;
-                const couldStillReduce = (task.files.length > minFiles && task.depth < MAX_SUBDIVIDE_DEPTH) ||
-                    (task.kind === 'reviewer' && !task.fallback);
-                if (couldStillReduce) {
+                const couldStillReduce = (canSubdivide && task.depth < MAX_SUBDIVIDE_DEPTH) || !task.fallback;
+                if (error.reason === "stall") {
+                    progress(`  ${task.label}: its model requests went silent (stalled) and did not recover — ` +
+                        `most likely provider rate limiting; reporting a coverage gap`);
+                    // Name the likely cause. OpenCode retries a 429 internally without surfacing
+                    // it, so provider throttling reaches us as pure silence — indistinguishable
+                    // from a wedged connection, and the single most common reason a pass produces
+                    // nothing at all. Saying "went silent" alone sends people hunting for a bug
+                    // in the reviewer instead of checking their usage window.
+                    incomplete.push(`${capitalize(task.coverageLabel)} could not run: its model requests went silent and produced no output, even after being retried. ` +
+                        `The usual cause is the model provider rate-limiting the account (a subscription credential over its usage window), which reaches this tool as silence rather than an error; ` +
+                        `those changes were not fully reviewed.`);
+                }
+                else if (couldStillReduce) {
                     progress(`  ${task.label}: exceeded ${minutes}m and the run's time budget is spent — reporting a coverage gap`);
                     incomplete.push(`${capitalize(task.coverageLabel)} timed out and the overall review budget was exhausted before it could be broken down further; those changes were not fully reviewed.`);
                 }
@@ -299,6 +417,18 @@ export async function runReview(source, options) {
                 }
             }
         });
+        // A substituted model means the review did not run on the model this repo
+        // configured — the findings may be from a weaker (or free-tier) model entirely.
+        // Never silent: it goes to the log, the coverage notes, and the run log.
+        if (substituted.size > 0) {
+            for (const line of substituted) {
+                progress(`  ⚠ model substituted — ${line}`);
+            }
+            incomplete.push(`Some passes did not run on the configured model (${[...substituted].join("; ")}). ` +
+                `OpenCode silently falls back to a default model when the configured id is empty or ` +
+                `unusable, so these findings may come from a different (possibly much weaker) model ` +
+                `than intended — check the agents' \`model\`, \`coordinator.model\`, REVIEWER_MODEL, and the provider credential.`);
+        }
         // Note: routine noise filtering (lockfiles, generated, binary) is expected and
         // NOT a coverage gap — it stays in the run log (filteredFiles), not the
         // user-facing coverage note, which is reserved for passes that didn't finish.
@@ -306,27 +436,28 @@ export async function runReview(source, options) {
         let output;
         if (completedPasses === 0) {
             // Nothing succeeded — do NOT let this render as a clean "approve".
-            progress('All review passes failed — reporting an incomplete review.');
+            progress("All review passes failed — reporting an incomplete review.");
             output = {
-                decision: 'approve_with_comments',
+                decision: "approve_with_comments",
                 findings: [],
-                summary: '⚠️ The AI review could not complete: every review pass failed or timed out, ' +
+                summary: "⚠️ The AI review could not complete: every review pass failed or timed out, " +
                     'so these changes were effectively NOT reviewed. Treat this as "no review", not "looks good".',
                 incomplete: coverageNotes,
             };
         }
         else {
-            progress('Coordinating findings…');
+            progress("Coordinating findings…");
             let consolidated;
             try {
-                const { output: rawOutput, cost, tokens: coordinatorTokens, truncated: coordinatorTruncated, } = await coordinate(handle, config, metadata, agentFindings, coverageNotes);
-                agentCosts['coordinator'] = cost;
-                addTokenUsage(tokenTotals, coordinatorTokens);
+                const { output: rawOutput, cost, tokens: coordinatorTokens, truncated: coordinatorTruncated, model: coordinatorModel, } = await coordinate(handle, config, metadata, agentFindings, coverageNotes);
+                agentCosts["coordinator"] = cost;
+                trackTokens("coordinator", coordinatorTokens);
+                trackModel("coordinator", config.coordinator.model, coordinatorModel);
                 consolidated = applyReviewPolicy(rawOutput, config.policy);
                 if (coordinatorTruncated) {
                     // The coordinator ran out of time and returned partial findings — flag it
                     // like any other truncated pass so reduced coverage is never silent.
-                    coverageNotes.push('The consolidation step ran out of time and returned partial findings; some findings may have been dropped or not fully de-duplicated.');
+                    coverageNotes.push("The consolidation step ran out of time and returned partial findings; some findings may have been dropped or not fully de-duplicated.");
                 }
             }
             catch (error) {
@@ -335,11 +466,11 @@ export async function runReview(source, options) {
                 // merge so a comment is still posted.
                 progress(`Coordinator failed (${errorMessage(error)}); consolidating findings locally.`);
                 consolidated = fallbackConsolidation(agentFindings, config.policy);
-                coverageNotes.push('The consolidation step failed, so findings are shown merged but not de-duplicated or re-judged.');
+                coverageNotes.push("The consolidation step failed, so findings are shown merged but not de-duplicated or re-judged.");
             }
             // A run with any failed/timed-out pass must never present as a clean approve.
-            const decision = failedPasses > 0 && consolidated.decision === 'approve'
-                ? 'approve_with_comments'
+            const decision = failedPasses > 0 && consolidated.decision === "approve"
+                ? "approve_with_comments"
                 : consolidated.decision;
             output = { ...consolidated, decision, incomplete: [...new Set(coverageNotes)] };
         }
@@ -347,11 +478,15 @@ export async function runReview(source, options) {
         // finding against the real file, and adversarially verify criticals. This is
         // what stops a confident but wrong critical from shipping.
         const findingCountBeforeChecks = output.findings.length;
+        let verifierDropped = [];
         if (output.findings.length > 0) {
-            progress('Verifying findings…');
+            progress("Verifying findings…");
             const verification = await verifyFindings(handle, output.findings, process.cwd(), progress);
-            agentCosts['verifier'] = verification.cost;
-            addTokenUsage(tokenTotals, verification.tokens);
+            agentCosts["verifier"] = verification.cost;
+            trackTokens("verifier", verification.tokens);
+            // Mirrors buildOpencodeConfig, which gives the verifier the first agent's model.
+            trackModel("verifier", config.agents[0]?.model ?? config.coordinator.model, verification.model);
+            verifierDropped = verification.dropped;
             if (verification.dropped.length > 0) {
                 progress(`Verification dropped ${verification.dropped.length} unverified finding(s).`);
                 output = {
@@ -380,12 +515,26 @@ export async function runReview(source, options) {
         if (removedAfterChecks > 0) {
             output = { ...output, summary: reconcileSummary(output.summary, output.findings.length) };
         }
+        // Every pass says which model actually answered it — in the job log, the step
+        // summary table, and the run log — so a wrong or substituted model is always
+        // visible, not just when the substitution warning fires.
+        if (Object.keys(agentModels).length > 0) {
+            progress(`Models used — ${Object.entries(agentModels)
+                .map(([bucket, model]) => `${bucket}: ${model}`)
+                .join("; ")}`);
+        }
         progress(formatUsageSummary(tokenTotals, sum(agentCosts)));
+        await appendStepSummary(renderUsageMarkdown(agentTokens, agentCosts, tokenTotals, sum(agentCosts), agentModels));
         await safeLog(logPath, {
             ...baseRecord,
             agentCosts,
             totalCost: sum(agentCosts),
             tokens: tokenTotals,
+            agentTokens,
+            agentModels,
+            agentFindings,
+            coverageNotes,
+            verifierDropped,
             durationMs: Date.now() - started,
             decision: output.decision,
             findingCount: output.findings.length,
@@ -399,6 +548,8 @@ export async function runReview(source, options) {
             agentCosts,
             totalCost: sum(agentCosts),
             tokens: tokenTotals,
+            agentTokens,
+            agentFindings,
             durationMs: Date.now() - started,
             decision: null,
             findingCount: 0,
@@ -420,13 +571,13 @@ export async function runReview(source, options) {
 export function applyReviewPolicy(output, policy) {
     let findings = policy.includeSuggestions
         ? output.findings
-        : output.findings.filter(finding => finding.severity !== 'suggestion');
+        : output.findings.filter((finding) => finding.severity !== "suggestion");
     findings = sortFindings(findings);
     if (policy.maxFindings != null) {
         findings = findings.slice(0, policy.maxFindings);
     }
-    const decision = output.decision === 'approve_with_comments' && findings.length === 0
-        ? 'approve'
+    const decision = output.decision === "approve_with_comments" && findings.length === 0
+        ? "approve"
         : output.decision;
     return { ...output, findings, decision };
 }
@@ -448,16 +599,16 @@ function fallbackConsolidation(agentFindings, policy) {
             }
         }
     }
-    const decision = merged.some(finding => finding.severity === 'critical')
-        ? 'request_changes'
+    const decision = merged.some((finding) => finding.severity === "critical")
+        ? "request_changes"
         : merged.length > 0
-            ? 'approve_with_comments'
-            : 'approve';
+            ? "approve_with_comments"
+            : "approve";
     return applyReviewPolicy({
         decision,
         findings: merged,
-        summary: 'Consolidation step failed; showing the specialist reviewers’ findings ' +
-            'merged and de-duplicated, but not re-judged.',
+        summary: "Consolidation step failed; showing the specialist reviewers’ findings " +
+            "merged and de-duplicated, but not re-judged.",
         incomplete: [],
     }, policy);
 }
@@ -468,10 +619,10 @@ function fallbackConsolidation(agentFindings, policy) {
  */
 export function decisionAfterVerification(previous, kept) {
     if (kept.length === 0) {
-        return 'approve';
+        return "approve";
     }
-    if (previous === 'request_changes' && !kept.some(finding => finding.severity === 'critical')) {
-        return 'approve_with_comments';
+    if (previous === "request_changes" && !kept.some((finding) => finding.severity === "critical")) {
+        return "approve_with_comments";
     }
     return previous;
 }
@@ -484,10 +635,10 @@ export function decisionAfterVerification(previous, kept) {
  */
 export function reconcileSummary(summary, remaining) {
     if (remaining === 0) {
-        return 'All candidate findings were removed by automated verification and suppression, so no issues remain to report.';
+        return "All candidate findings were removed by automated verification and suppression, so no issues remain to report.";
     }
-    return ('_Note: some findings were removed by automated verification/suppression after ' +
-        'this summary was written, so it may mention issues no longer listed below._\n\n' +
+    return ("_Note: some findings were removed by automated verification/suppression after " +
+        "this summary was written, so it may mention issues no longer listed below._\n\n" +
         summary);
 }
 /** Capitalize the first letter (coverage notes read as sentences). */
@@ -514,19 +665,19 @@ export function isAuthError(error) {
         new RegExp(`${problem.source}\\b[^.]{0,20}${cred.source}`).test(message) ||
         new RegExp(`${cred.source}[^.]{0,20}${problem.source}`).test(message));
 }
-const AUTH_FAILURE_NOTE = 'The model provider rejected the request (authentication or permission). Check the ' +
-    'configured credential (auth.tokenEnv, or REVIEWER_MODEL for a local run) and re-run — ' +
-    'those changes were not reviewed.';
+const AUTH_FAILURE_NOTE = "The model provider rejected the request (authentication or permission). Check the " +
+    "configured credential (auth.tokenEnv, or REVIEWER_MODEL for a local run) and re-run — " +
+    "those changes were not reviewed.";
 function selectAgents(all, filter) {
     if (!filter?.length) {
         return all;
     }
-    const known = new Set(all.map(agent => agent.id));
-    const unknown = filter.filter(id => !known.has(id));
+    const known = new Set(all.map((agent) => agent.id));
+    const unknown = filter.filter((id) => !known.has(id));
     if (unknown.length > 0) {
-        throw new Error(`Unknown agent(s): ${unknown.join(', ')}. Available: ${all.map(a => a.id).join(', ')}`);
+        throw new Error(`Unknown agent(s): ${unknown.join(", ")}. Available: ${all.map((a) => a.id).join(", ")}`);
     }
-    return all.filter(agent => filter.includes(agent.id));
+    return all.filter((agent) => filter.includes(agent.id));
 }
 /**
  * Greedily pack files into chunks bounded by total changed lines (primary) and
@@ -604,8 +755,32 @@ export function formatUsageSummary(tokens, totalCost) {
         parts.push(`reasoning ${tokens.reasoning}`);
     }
     parts.push(`cache read ${tokens.cache?.read ?? 0}`, `cache write ${tokens.cache?.write ?? 0}`);
-    const cost = totalCost > 0 ? ` (cost $${totalCost.toFixed(4)})` : '';
-    return `Token usage — ${parts.join(', ')}${cost}`;
+    const cost = totalCost > 0 ? ` (cost $${totalCost.toFixed(4)})` : "";
+    return `Token usage — ${parts.join(", ")}${cost}`;
+}
+/**
+ * Markdown-table version of the usage summary for the Actions step summary: one
+ * row per pass plus a total, and the prompt-cache hit rate (the share of prompt
+ * tokens served from cache instead of being reprocessed at full price).
+ */
+export function renderUsageMarkdown(agentTokens, agentCosts, totals, totalCost, agentModels = {}) {
+    const row = (label, model, tokens, cost) => `| ${label} | ${model} | ${tokens.input ?? 0} | ${tokens.output ?? 0} | ${tokens.cache?.read ?? 0} | ${tokens.cache?.write ?? 0} | $${cost.toFixed(4)} |`;
+    const lines = [
+        "### 🤖 AI review — token usage",
+        "",
+        "| pass | model | input | output | cache read | cache write | cost |",
+        "| --- | --- | ---: | ---: | ---: | ---: | ---: |",
+        ...Object.keys(agentCosts).map((bucket) => row(bucket, agentModels[bucket] ?? "—", agentTokens[bucket] ?? {}, agentCosts[bucket] ?? 0)),
+        row("**total**", "", totals, totalCost),
+    ];
+    const read = totals.cache?.read ?? 0;
+    const uncached = totals.input ?? 0;
+    if (read + uncached > 0) {
+        const rate = Math.round((read / (read + uncached)) * 100);
+        lines.push("", `Prompt cache hit rate: **${rate}%** (cache read / (cache read + input)). ` +
+            'See "Tokens, cost & prompt caching" in the README for how to read these numbers.');
+    }
+    return lines.join("\n");
 }
 async function safeLog(logPath, record) {
     try {