@expo/code-review-cli 0.2.3 → 0.4.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, 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));
@@ -102,18 +118,29 @@ export async function runReview(source, options) {
     }
     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);
+    };
     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 +148,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;
@@ -148,19 +174,20 @@ export async function runReview(source, options) {
         // 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 passesBudgetMs = options.passesBudgetMs ?? PASSES_BUDGET_MS;
+        const passesDeadline = started + passesBudgetMs;
         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,12 +200,12 @@ 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)',
+                coverageLabel: "the cross-file review (issues spanning multiple changed files)",
                 maxWaitMs: CROSS_CUTTING_TIMEOUT_MS,
                 maxToolCalls: CROSS_CUTTING_MAX_TOOL_CALLS,
                 depth: 0,
@@ -191,15 +218,15 @@ export async function runReview(source, options) {
         // 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)
                 : 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,
@@ -225,13 +252,13 @@ export async function runReview(source, options) {
                     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);
                 (agentFindings[task.bucket] ??= []).push(...value.findings);
                 completedPasses++;
                 if (truncated) {
@@ -245,18 +272,25 @@ export async function runReview(source, options) {
                 if (!(error instanceof AgentTimeoutError)) {
                     failedPasses++;
                     progress(`  ${task.label}: FAILED (${errorMessage(error)})`);
-                    incomplete.push(`${capitalize(task.coverageLabel)} failed to run; those changes were not reviewed.`);
+                    // An auth/permission failure hits every pass identically; push one shared,
+                    // actionable note (deduped into a single coverage line) instead of N generic
+                    // per-pass failures that bury the real, fixable cause.
+                    incomplete.push(isAuthError(error)
+                        ? AUTH_FAILURE_NOTE
+                        : `${capitalize(task.coverageLabel)} failed to run; those changes were not reviewed.`);
                     return;
                 }
                 // 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;
+                const minFiles = task.kind === "cross-cutting" ? 2 : 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 (task.files.length > minFiles &&
+                    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);
@@ -268,9 +302,9 @@ export async function runReview(source, options) {
                 }
                 // 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) {
+                if (task.kind === "reviewer" && !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,
@@ -283,7 +317,7 @@ export async function runReview(source, options) {
                 // vs. the task was already at its smallest reviewable unit and still failed.
                 failedPasses++;
                 const couldStillReduce = (task.files.length > minFiles && task.depth < MAX_SUBDIVIDE_DEPTH) ||
-                    (task.kind === 'reviewer' && !task.fallback);
+                    (task.kind === "reviewer" && !task.fallback);
                 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.`);
@@ -301,27 +335,27 @@ 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);
+                agentCosts["coordinator"] = cost;
+                trackTokens("coordinator", coordinatorTokens);
                 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) {
@@ -330,11 +364,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)] };
         }
@@ -342,11 +376,13 @@ 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);
+            verifierDropped = verification.dropped;
             if (verification.dropped.length > 0) {
                 progress(`Verification dropped ${verification.dropped.length} unverified finding(s).`);
                 output = {
@@ -375,11 +411,17 @@ export async function runReview(source, options) {
         if (removedAfterChecks > 0) {
             output = { ...output, summary: reconcileSummary(output.summary, output.findings.length) };
         }
+        progress(formatUsageSummary(tokenTotals, sum(agentCosts)));
+        await appendStepSummary(renderUsageMarkdown(agentTokens, agentCosts, tokenTotals, sum(agentCosts)));
         await safeLog(logPath, {
             ...baseRecord,
             agentCosts,
             totalCost: sum(agentCosts),
             tokens: tokenTotals,
+            agentTokens,
+            agentFindings,
+            coverageNotes,
+            verifierDropped,
             durationMs: Date.now() - started,
             decision: output.decision,
             findingCount: output.findings.length,
@@ -393,6 +435,8 @@ export async function runReview(source, options) {
             agentCosts,
             totalCost: sum(agentCosts),
             tokens: tokenTotals,
+            agentTokens,
+            agentFindings,
             durationMs: Date.now() - started,
             decision: null,
             findingCount: 0,
@@ -414,13 +458,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 };
 }
@@ -442,16 +486,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);
 }
@@ -462,10 +506,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;
 }
@@ -478,26 +522,49 @@ 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). */
 function capitalize(text) {
     return text.length > 0 ? text[0].toUpperCase() + text.slice(1) : text;
 }
+/**
+ * An authentication/authorization failure from the model provider (401/403, a
+ * rejected/expired/missing credential) — distinct from a transient blip or a real
+ * code finding. Every pass hits the same wall, so the caller collapses it into one
+ * actionable coverage note instead of N generic "failed to run" lines.
+ */
+export function isAuthError(error) {
+    const message = errorMessage(error).toLowerCase();
+    const cred = /(api.?key|token|credential)/;
+    const problem = /(invalid|expired|revoked|missing|rejected|no)/;
+    return (/\b401\b|\b403\b/.test(message) ||
+        /unauthor/.test(message) ||
+        /\bforbidden\b/.test(message) ||
+        /authentication/.test(message) ||
+        /permission denied/.test(message) ||
+        /invalid x-api-key/.test(message) ||
+        // a credential noun and a problem word near each other, in either order
+        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.";
 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
@@ -563,6 +630,45 @@ export async function runGrowableQueue(initial, limit, fn) {
 function sum(costs) {
     return Object.values(costs).reduce((total, value) => total + value, 0);
 }
+/**
+ * One-line usage summary for the run. Emitted via progress so it lands in the CI
+ * job log (and the local terminal) — `.runs/reviews.jsonl` is ephemeral in CI, so
+ * this is the only place the token/cache totals are visible after a CI run, which
+ * is how prompt-cache effectiveness gets confirmed there.
+ */
+export function formatUsageSummary(tokens, totalCost) {
+    const parts = [`input ${tokens.input ?? 0}`, `output ${tokens.output ?? 0}`];
+    if (tokens.reasoning) {
+        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}`;
+}
+/**
+ * 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) {
+    const row = (label, tokens, cost) => `| ${label} | ${tokens.input ?? 0} | ${tokens.output ?? 0} | ${tokens.cache?.read ?? 0} | ${tokens.cache?.write ?? 0} | $${cost.toFixed(4)} |`;
+    const lines = [
+        "### 🤖 AI review — token usage",
+        "",
+        "| pass | input | output | cache read | cache write | cost |",
+        "| --- | ---: | ---: | ---: | ---: | ---: |",
+        ...Object.keys(agentCosts).map((bucket) => row(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 {
         await writeRunLog(logPath, record);

package/build/core/router.js

@@ -1,27 +1,27 @@
-import { promptAndParse } from './opencode.js';
-import { buildRouterSystem, buildRouterTask } from './prompts.js';
-import { parseRouteOutput } from './schema.js';
+import { promptAndParse } from "./opencode.js";
+import { buildRouterSystem, buildRouterTask } from "./prompts.js";
+import { parseRouteOutput } from "./schema.js";
 /**
  * Ask the model which agents are relevant to the changed files. Agents marked
  * `alwaysRun` are unioned in regardless. Falls back to ALL agents if the router
  * returns nothing usable or errors — a review must never run with zero agents.
  */
 export async function routeAgents(handle, config, files) {
-    const always = config.agents.filter(agent => agent.alwaysRun);
+    const always = config.agents.filter((agent) => agent.alwaysRun);
     try {
         const { value } = await promptAndParse(handle, {
-            agent: 'coordinator',
+            agent: "coordinator",
             system: buildRouterSystem(),
             text: buildRouterTask(config.agents, files),
-            title: 'route',
+            title: "route",
         }, parseRouteOutput);
-        const byId = new Map(config.agents.map(agent => [agent.id, agent]));
+        const byId = new Map(config.agents.map((agent) => [agent.id, agent]));
         const picked = value.agents
-            .map(id => byId.get(id))
+            .map((id) => byId.get(id))
             .filter((agent) => Boolean(agent));
-        const chosenIds = new Set([...picked, ...always].map(agent => agent.id));
+        const chosenIds = new Set([...picked, ...always].map((agent) => agent.id));
         // Preserve config order and dedupe.
-        const chosen = config.agents.filter(agent => chosenIds.has(agent.id));
+        const chosen = config.agents.filter((agent) => chosenIds.has(agent.id));
         if (chosen.length === 0) {
             return { agents: config.agents, routed: false };
         }

package/build/core/schema.js

@@ -1,12 +1,12 @@
-import { createHash } from 'node:crypto';
-import { z } from 'zod';
-import { normalizeCode } from './util.js';
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { normalizeCode } from "./util.js";
 /** Severity levels, ordered most→least severe for sorting/rendering. */
-export const SEVERITIES = ['critical', 'warning', 'suggestion'];
+export const SEVERITIES = ["critical", "warning", "suggestion"];
 /** Sort rank for severities (0 = most severe). Single source of truth. */
 export const SEVERITY_RANK = { critical: 0, warning: 1, suggestion: 2 };
-export const CATEGORIES = ['correctness', 'quality', 'security', 'secrets'];
-export const DECISIONS = ['approve', 'approve_with_comments', 'request_changes'];
+export const CATEGORIES = ["correctness", "quality", "security", "secrets"];
+export const DECISIONS = ["approve", "approve_with_comments", "request_changes"];
 export const FindingSchema = z.object({
     severity: z.enum(SEVERITIES),
     category: z.enum(CATEGORIES),
@@ -25,7 +25,7 @@ export const FindingSchema = z.object({
 /** A verifier's verdict on whether a finding is real (adversarial refute pass). */
 export const VerdictSchema = z.object({
     verified: z.boolean(),
-    reason: z.string().default(''),
+    reason: z.string().default(""),
 });
 export function parseVerdict(text) {
     return VerdictSchema.parse(extractJsonObject(text));
@@ -60,10 +60,24 @@ const MIN_FP_EVIDENCE_LEN = 12;
  * there's too little evidence to key on.
  */
 export function fingerprintFinding(finding) {
-    const evidence = normalizeCode(finding.evidence ?? '');
+    const evidence = normalizeCode(finding.evidence ?? "");
     const key = evidence.length >= MIN_FP_EVIDENCE_LEN ? evidence : normalizeCode(finding.title);
-    const normalized = ['v2', finding.file, finding.category, key].join('|');
-    return createHash('sha1').update(normalized).digest('hex').slice(0, 12);
+    const normalized = ["v2", finding.file, finding.category, key].join("|");
+    return createHash("sha1").update(normalized).digest("hex").slice(0, 12);
+}
+/**
+ * Namespace a finding's fingerprint by scope so cross-scope dismissals never
+ * collide. The DEFAULT scope (config '.') passes `null` and keeps the plain
+ * fingerprintFinding value, so pre-routing dismissal state carries over unchanged
+ * (risk 9). Non-default scopes hash into the same hex alphabet the dismiss command
+ * sanitizes to (dismiss.ts strips /[^a-f0-9]/), at the same length.
+ */
+export function scopedFingerprint(scopeName, finding) {
+    const fp = fingerprintFinding(finding);
+    if (!scopeName) {
+        return fp;
+    }
+    return createHash("sha1").update(`scope|${scopeName}|${fp}`).digest("hex").slice(0, fp.length);
 }
 /**
  * Extract the JSON payload from an LLM response. Prefers the last fenced
@@ -76,8 +90,8 @@ export function extractJsonObject(text) {
     if (fenceMatches.length > 0) {
         candidates.push(fenceMatches[fenceMatches.length - 1][1].trim());
     }
-    const firstBrace = text.indexOf('{');
-    const lastBrace = text.lastIndexOf('}');
+    const firstBrace = text.indexOf("{");
+    const lastBrace = text.lastIndexOf("}");
     if (firstBrace !== -1 && lastBrace > firstBrace) {
         candidates.push(text.slice(firstBrace, lastBrace + 1));
     }