@expo/code-review-cli 0.10.0 → 0.11.1

package/README.md

@@ -71,6 +71,9 @@ ecr review
 ecr review --pr 123
 # …and post it as the PR comment
 ecr review --pr 123 --post
+# Preview once, save the exact result, and post it later without another model run
+ecr review --repo owner/repo --pr 123 --save-review --json
+ecr post-review --artifact .expo-code-review/.runs/deferred/<artifact>.json --repo owner/repo --pr 123
 ```
 
 Options (most to least common):
@@ -79,6 +82,7 @@ Options (most to least common):
 | --- | --- |
 | `--pr <n>` | Review GitHub PR #n by number (diff fetched via `gh`, no checkout); not combinable with `--base`/`--head`/`--staged`. |
 | `--post` | With `--pr`, also post the result as the PR comment (needs `gh` auth). Omit to preview only; re-run with `--post` to publish. |
+| `--save-review` | With explicit `--repo` + `--pr`, save the exact preview as a private postable artifact. Mutually exclusive with `--post`. |
 | `--staged` | Review only staged changes (index vs HEAD; not combinable with `--base`/`--head`). |
 | `--base <ref>` | Base ref to diff against (default: merge-base with the default branch). |
 | `--head <ref>` | Head ref to diff (default: working tree, incl. uncommitted changes). |
@@ -111,6 +115,7 @@ is a ready example to adapt.
 | `ecr setup-auth [--yes]` | Walk through getting model credentials for local runs (ChatGPT/Claude sign-in and/or API keys), printing the `export` lines for your shell config. |
 | `ecr review [options]` | Review local changes and print an advisory review (default command). |
 | `ecr review --scope <name>` | Review only one routing scope over just that scope's changed files. |
+| `ecr post-review --artifact <path> --repo <owner/repo> --pr <n>` | Post an exact saved PR preview without re-running models; refuses target, head, config, or break-glass drift. |
 | `ecr ci` | Review the current GitHub PR and post/update a comment. For GitHub Actions. |
 | `ecr doctor [--list-scopes]` | Check environment, config, credentials, and (with a manifest) scopes. |
 | `ecr feedback [--repo <owner/repo>]` | Report which findings PR authors pushed back on, across history. See below. |
@@ -339,7 +344,18 @@ cache, in three places:
   run, so the step summary is where past runs' comments remain readable.
 - **`.expo-code-review/.runs/reviews.jsonl`** — one JSON line per run (uploaded as
   a CI artifact) with the same totals plus per-pass `agentTokens`, the raw
-  per-agent findings, coverage notes, and what the verifier dropped.
+  per-agent findings, bounded reviewer traces, coverage notes, and what the verifier
+  dropped.
+
+Each reviewer can also return a compact trace with up to three concrete checks and
+two unresolved questions. The reporter stores it only inside the existing base64
+`<!-- <commentTag>:state=… -->` comment marker as `review.reviewTrace`; it does not
+render in the visible review. Agents and other machine consumers can decode that
+state to see what a clean review covered. The payload declares
+`trust: "unverified-model-diagnostics"`: it contains bounded conclusions, never a
+raw transcript or chain-of-thought, and must not be treated as a verified finding.
+The engine sorts agent ids and caps the complete decoded trace at 6 KB so this hidden
+diagnostic cannot crowd visible findings out of GitHub's comment-size limit.
 
 **How the caching works.** Provider prompt caching is a *prefix match*: the
 provider caches the rendered prompt up to a point, and any byte change anywhere
@@ -645,9 +661,16 @@ variables: `ATLANTIS_BOT_LOGIN` (the Atlantis bot's comment login, e.g.
 Each run appends a JSON line to `.expo-code-review/.runs/reviews.jsonl` with the
 inputs, decision, finding count, duration, per-agent cost, and aggregate token
 usage (incl. prompt-cache read/write counts) — for auditing and measuring
-cost/latency/cache reuse over time. The same totals are printed as a one-line
-summary to the terminal / CI job log at the end of each run, so cache reuse is
-visible even in CI (where the run log is ephemeral).
+cost/latency/cache reuse over time. It also records the same bounded `reviewTrace`
+that the PR comment embeds for machine consumers. The same totals are printed as a
+one-line summary to the terminal / CI job log at the end of each run, so cache reuse
+is visible even in CI (where the run log is ephemeral).
+
+`ecr review --save-review` additionally writes a versioned artifact under
+`.expo-code-review/.runs/deferred/` with owner-only permissions. It contains the
+verified final review and bounded feedback metadata, but no credential. `ecr
+post-review` schema-validates it and refuses to post if its explicit repo/PR, live
+head commit, or local comment-policy fingerprint no longer matches.
 
 </details>
 

package/build/cli.js

@@ -5,6 +5,7 @@ import { dismissCommand } from "./commands/dismiss.js";
 import { doctorCommand } from "./commands/doctor.js";
 import { feedbackCommand } from "./commands/feedback.js";
 import { initCommand } from "./commands/init.js";
+import { postReviewCommand } from "./commands/post-review.js";
 import { refCheckCommand } from "./commands/ref-check.js";
 import { reviewCommand } from "./commands/review.js";
 import { setupAuthCommand } from "./commands/setup-auth.js";
@@ -13,6 +14,7 @@ const USAGE = `expo-code-review (ecr) — config-driven AI code reviewer
 
 Usage:
   ecr review [options]   Review local changes (default). See \`ecr review --help\`.
+  ecr post-review --artifact <path> --repo <owner/repo> --pr <n>   Post an exact saved preview.
   ecr ci                 Review the current PR and post a comment (GitHub Actions).
   ecr dismiss --pr <n> <id...>     Hide a finding on a PR (see \`ecr dismiss --help\`).
   ecr undismiss --pr <n> <id...>   Restore a dismissed finding.
@@ -43,6 +45,9 @@ async function main() {
         case "review":
             await reviewCommand(rest);
             break;
+        case "post-review":
+            await postReviewCommand(rest);
+            break;
         case "ci":
             await ciCommand(rest);
             break;

package/build/commands/post-review.js

@@ -0,0 +1,147 @@
+// @ref LLP 0007#deferred-review-posting [implements] — no-model post of an exact, target-bound preview artifact
+import path from "node:path";
+import { loadReviewConfig } from "../config/load.js";
+import { assertDeferredReviewCurrent, readDeferredReviewArtifact, reviewPostingConfigFingerprint, } from "../core/deferred-review.js";
+import { repoRoot } from "../core/exec.js";
+import { errorMessage } from "../core/util.js";
+import { GitHubReporter } from "../reporters/github.js";
+import { GitHubPRSource, isCommitOid } from "../sources/github-pr.js";
+const USAGE = `ecr post-review — post an exact saved PR review without re-running models
+
+Usage:
+  ecr post-review --artifact <path> --repo <owner/repo> --pr <n>
+
+The artifact must come from \`ecr review --save-review --repo <owner/repo> --pr <n>\`.
+Before writing to GitHub, this command verifies the explicit repo/PR, the live PR
+head commit, the local posting policy, and the PR's break-glass marker.
+`;
+function requireValue(flag, value) {
+    if (value === undefined || value.startsWith("--")) {
+        throw new Error(`${flag} requires a value`);
+    }
+    return value;
+}
+export function parsePostReviewArgs(argv) {
+    const args = { help: false };
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        switch (arg) {
+            case "--artifact":
+                args.artifact = requireValue(arg, argv[++i]);
+                break;
+            case "--repo":
+                args.repo = requireValue(arg, argv[++i]);
+                break;
+            case "--pr": {
+                const value = requireValue(arg, argv[++i]);
+                const number = Number(value);
+                if (!Number.isSafeInteger(number) || number <= 0) {
+                    throw new Error(`--pr requires a positive safe integer (got "${value}")`);
+                }
+                args.pr = number;
+                break;
+            }
+            case "-h":
+            case "--help":
+                args.help = true;
+                break;
+            default:
+                throw new Error(`Unknown argument: ${arg}`);
+        }
+    }
+    return args;
+}
+function validatePostReviewArgs(args) {
+    if (!args.artifact || !args.repo || args.pr == null) {
+        throw new Error("--artifact, --repo, and --pr are all required");
+    }
+    if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(args.repo)) {
+        throw new Error(`--repo requires owner/repo (got "${args.repo}")`);
+    }
+}
+/** Break-glass errors fail closed: no report call occurs unless the check says false. */
+export async function publishDeferredReview(poster, artifact, assertReadyToPost = async () => { }) {
+    if (await poster.checkBreakGlass()) {
+        return "break-glass";
+    }
+    await assertReadyToPost();
+    await poster.report(artifact.review, artifact.feedback);
+    return "posted";
+}
+export async function postReviewCommand(argv) {
+    let args;
+    try {
+        args = parsePostReviewArgs(argv);
+        if (args.help) {
+            process.stdout.write(USAGE);
+            return;
+        }
+        validatePostReviewArgs(args);
+    }
+    catch (error) {
+        process.stderr.write(`${errorMessage(error)}\n\n${USAGE}`);
+        process.exitCode = 2;
+        return;
+    }
+    // Resolve before chdir so a relative artifact path keeps the caller's meaning.
+    const artifactPath = path.resolve(process.cwd(), args.artifact);
+    try {
+        const root = await repoRoot();
+        if (root && root !== process.cwd()) {
+            process.chdir(root);
+        }
+        const cwd = process.cwd();
+        const [artifact, config] = await Promise.all([
+            readDeferredReviewArtifact(artifactPath),
+            loadReviewConfig(cwd),
+        ]);
+        const source = new GitHubPRSource({ prNumber: args.pr, repo: args.repo, cwd });
+        const headSha = (await source.getMetadata()).headOid;
+        if (!isCommitOid(headSha)) {
+            throw new Error(`could not resolve a full head commit for ${args.repo}#${args.pr}`);
+        }
+        assertDeferredReviewCurrent(artifact, {
+            repo: args.repo,
+            pr: args.pr,
+            headSha,
+            configFingerprint: reviewPostingConfigFingerprint(config),
+        });
+        const reporter = new GitHubReporter({
+            prNumber: args.pr,
+            repo: args.repo,
+            commentTag: config.commentTag,
+            breakGlassMarker: config.breakGlassMarker,
+            cwd,
+            feedback: config.feedback,
+            headSha,
+        });
+        const result = await publishDeferredReview(reporter, artifact, async () => {
+            // Re-fetch rather than reusing GitHubPRSource's memoized metadata, and reload
+            // config after the break-glass API call. This narrows the unavoidable remote
+            // TOCTOU window and prevents a head/policy change during setup from reaching
+            // the reporter.
+            const [latestMetadata, latestConfig] = await Promise.all([
+                new GitHubPRSource({ prNumber: args.pr, repo: args.repo, cwd }).getMetadata(),
+                loadReviewConfig(cwd),
+            ]);
+            if (!isCommitOid(latestMetadata.headOid)) {
+                throw new Error(`could not re-resolve a full head commit for ${args.repo}#${args.pr}`);
+            }
+            assertDeferredReviewCurrent(artifact, {
+                repo: args.repo,
+                pr: args.pr,
+                headSha: latestMetadata.headOid,
+                configFingerprint: reviewPostingConfigFingerprint(latestConfig),
+            });
+        });
+        if (result === "break-glass") {
+            process.stderr.write(`Not posting: ${config.breakGlassMarker} is set on ${args.repo}#${args.pr}.\n`);
+            return;
+        }
+        process.stderr.write(`Posted saved review to ${args.repo}#${args.pr}.\n`);
+    }
+    catch (error) {
+        process.stderr.write(`Saved review was not posted: ${errorMessage(error)}\n`);
+        process.exitCode = 2;
+    }
+}

package/build/commands/review.js

@@ -4,10 +4,11 @@ import { loadRoutingManifest, resolveScopes, scopedCommentTag } from "../config/
 import { repoRoot, resolveRepo } from "../core/exec.js";
 import { errorMessage } from "../core/util.js";
 import { readContextFile } from "../core/context-file.js";
+import { writeDeferredReviewArtifact } from "../core/deferred-review.js";
 import { feedbackNeedsRunSeam } from "../core/adjudicate.js";
 import { runReview } from "../core/review.js";
 import { LocalGitSource } from "../sources/local-git.js";
-import { GitHubPRSource } from "../sources/github-pr.js";
+import { GitHubPRSource, isCommitOid } from "../sources/github-pr.js";
 import { memoizeSource, stackConfirmFromConfig, stackWalkFromConfig } from "../sources/source.js";
 import { TerminalReporter } from "../reporters/terminal.js";
 import { GitHubReporter } from "../reporters/github.js";
@@ -15,7 +16,8 @@ const USAGE = `ecr review — AI code review, printed to your terminal
 
 Usage:
   ecr review [options]                 review local changes
-  ecr review --pr <n> [--post]         review a GitHub PR by number
+  ecr review --pr <n> [--post | --save-review]
+                                       review a GitHub PR by number
 
 Source (pick one):
   (default)          diff the working tree against the merge-base
@@ -31,6 +33,8 @@ Options:
   --post               with --pr: also post the result as the PR comment (needs
                        \`gh\` auth). Omit to only preview here; re-run with --post
                        to publish.
+  --save-review        with explicit --repo + --pr: save this exact preview as a
+                       postable artifact for a later \`ecr post-review\` command.
   --agents <a,b>       run only these agents (comma-separated ids); default: all
   --route              let the router pick relevant agents from the diff
   --scope <name>       review only this routing scope (needs a routing.jsonc);
@@ -60,10 +64,11 @@ function requireValue(flag, value) {
     }
     return value;
 }
-function parseArgs(argv) {
+export function parseReviewArgs(argv) {
     const args = {
         staged: false,
         post: false,
+        saveReview: false,
         route: false,
         stackAware: false,
         json: false,
@@ -85,8 +90,8 @@ function parseArgs(argv) {
             case "--pr": {
                 const value = requireValue(arg, argv[++i]);
                 const number = Number(value);
-                if (!Number.isInteger(number) || number <= 0) {
-                    throw new Error(`--pr requires a positive PR number (got "${value}")`);
+                if (!Number.isSafeInteger(number) || number <= 0) {
+                    throw new Error(`--pr requires a positive safe integer (got "${value}")`);
                 }
                 args.pr = number;
                 break;
@@ -97,6 +102,9 @@ function parseArgs(argv) {
             case "--post":
                 args.post = true;
                 break;
+            case "--save-review":
+                args.saveReview = true;
+                break;
             case "--agents":
                 args.agents = requireValue(arg, argv[++i])
                     .split(",")
@@ -137,7 +145,7 @@ function parseArgs(argv) {
 export async function reviewCommand(argv) {
     let args;
     try {
-        args = parseArgs(argv);
+        args = parseReviewArgs(argv);
     }
     catch (error) {
         process.stderr.write(`${errorMessage(error)}\n\n${USAGE}`);
@@ -149,7 +157,7 @@ export async function reviewCommand(argv) {
         return;
     }
     try {
-        validateArgs(args);
+        validateReviewArgs(args);
     }
     catch (error) {
         process.stderr.write(`${errorMessage(error)}\n\n${USAGE}`);
@@ -292,11 +300,13 @@ export async function reviewCommand(argv) {
         }
         const config = await loadReviewConfig(cwd, { configDir: args.configDir });
         const source = makeSource();
-        // Build the PR reporter up front when posting, so adjudicate mode can judge the
+        // Build the PR reporter up front when posting OR saving a postable preview, so
+        // adjudicate mode can judge the
         // PR's replies against the source before the result is rendered. Feedback only
         // has replies to match when reviewing a PR and posting (the terminal preview never
-        // renders annotations), so it is wired only on the --post --pr path.
-        const { repo: postRepo, error: postRepoError } = await resolvePostRepo(args, cwd);
+        // renders annotations), so it is wired only when a later/current post is possible.
+        const { repo: postRepo, error: postRepoError } = await resolvePostRepo({ ...args, post: args.post || args.saveReview }, cwd);
+        const headSha = postRepo != null && args.pr != null ? await reviewedHeadSha(source) : undefined;
         const reporter = postRepo != null && args.pr != null
             ? new GitHubReporter({
                 prNumber: args.pr,
@@ -305,7 +315,7 @@ export async function reviewCommand(argv) {
                 breakGlassMarker: config.breakGlassMarker,
                 cwd,
                 feedback: config.feedback,
-                headSha: await reviewedHeadSha(source),
+                headSha,
             })
             : null;
         const review = await runReview(source, {
@@ -325,6 +335,19 @@ export async function reviewCommand(argv) {
         });
         // Always print the result here first.
         await new TerminalReporter({ json: args.json, noFail: args.noFail }).report(review);
+        if (args.saveReview) {
+            if (postRepo == null || args.pr == null || !isCommitOid(headSha)) {
+                throw new Error(`could not save a postable review: ${postRepoError ? errorMessage(postRepoError) : "the PR head commit could not be resolved"}`);
+            }
+            const artifactPath = await writeDeferredReviewArtifact(config, {
+                repo: postRepo,
+                pr: args.pr,
+                headSha,
+                review,
+                feedback: review.feedback,
+            });
+            process.stderr.write(`\nSaved postable review artifact: ${artifactPath}\n`);
+        }
         // Then, only if asked, publish the same result to the PR.
         if (args.pr != null && args.post) {
             if (reporter) {
@@ -403,12 +426,21 @@ export async function resolvePostRepo(args, cwd, resolve = resolveRepo) {
 }
 // @ref LLP 0007#ecr-review-local-trust-and-flag-rules [implements] — mutually exclusive flags rejected outright, never silently ignored
 /** Reject flag combinations that don't make sense together. */
-function validateArgs(args) {
+export function validateReviewArgs(args) {
     if (args.pr != null && (args.base || args.head || args.staged)) {
         throw new Error("--pr reviews a PR by its diff and cannot be combined with --base/--head/--staged.");
     }
-    if (args.pr == null && (args.repo || args.post)) {
-        throw new Error("--repo/--post only apply together with --pr.");
+    if (args.pr == null && (args.repo || args.post || args.saveReview)) {
+        throw new Error("--repo/--post/--save-review only apply together with --pr.");
+    }
+    if (args.saveReview && !args.repo) {
+        throw new Error("--save-review requires explicit --repo owner/repo.");
+    }
+    if (args.saveReview && args.post) {
+        throw new Error("--save-review and --post are mutually exclusive.");
+    }
+    if (args.saveReview && (args.scope || args.configDir)) {
+        throw new Error("--save-review does not support --scope or --config-dir.");
     }
     // Same rule as --repo/--post: the stack walk needs a PR to walk from, so a bare
     // --stack-aware would be silently ignored — reject it instead.

package/build/core/deferred-review.js

@@ -0,0 +1,119 @@
+// @ref LLP 0007#deferred-review-posting [implements] — exact preview artifact, explicit target binding, and stale-head/config refusal
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, open, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { z } from "zod";
+import { CoordinatorOutputSchema, FeedbackRecordSchema, } from "./schema.js";
+export const DEFERRED_REVIEW_ARTIFACT_VERSION = 1;
+export const DEFERRED_REVIEW_ARTIFACT_MAX_BYTES = 1_000_000;
+const READ_CHUNK_BYTES = 65_536;
+const RepoSchema = z.string().regex(/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/, "expected owner/repo");
+const CommitOidSchema = z.string().regex(/^[0-9a-f]{40}$/i, "expected a full commit OID");
+/**
+ * A postable review produced by one completed local PR review. The review and
+ * feedback are the exact verified values that terminal preview rendered; target,
+ * head and posting-policy bindings are checked again before any GitHub write.
+ */
+export const DeferredReviewArtifactSchema = z
+    .object({
+    version: z.literal(DEFERRED_REVIEW_ARTIFACT_VERSION),
+    createdAt: z.string().datetime(),
+    repo: RepoSchema,
+    pr: z.number().int().positive().safe(),
+    headSha: CommitOidSchema,
+    configFingerprint: z.string().regex(/^[0-9a-f]{64}$/i),
+    review: CoordinatorOutputSchema,
+    feedback: z.array(FeedbackRecordSchema).optional(),
+})
+    .strict();
+/** Bind the artifact to the local config fields that affect the posted comment. */
+export function reviewPostingConfigFingerprint(config) {
+    return createHash("sha256")
+        .update(JSON.stringify({
+        commentTag: config.commentTag,
+        breakGlassMarker: config.breakGlassMarker,
+        feedback: config.feedback,
+    }))
+        .digest("hex");
+}
+function artifactFilename(repo, pr) {
+    const safeRepo = repo.replace(/[^A-Za-z0-9_.-]+/g, "-");
+    return `${safeRepo}-pr-${pr}-${randomUUID()}.json`;
+}
+/**
+ * Persist with owner-only permissions and exclusive creation. The random filename
+ * avoids overwriting another session's pending review; no credential is stored.
+ */
+export async function writeDeferredReviewArtifact(config, input) {
+    const artifact = DeferredReviewArtifactSchema.parse({
+        version: DEFERRED_REVIEW_ARTIFACT_VERSION,
+        createdAt: new Date().toISOString(),
+        repo: input.repo,
+        pr: input.pr,
+        headSha: input.headSha,
+        configFingerprint: reviewPostingConfigFingerprint(config),
+        review: input.review,
+        ...(input.feedback ? { feedback: input.feedback } : {}),
+    });
+    const serialized = `${JSON.stringify(artifact, null, 2)}\n`;
+    const serializedBytes = Buffer.byteLength(serialized);
+    if (serializedBytes > DEFERRED_REVIEW_ARTIFACT_MAX_BYTES) {
+        throw new Error(`deferred review artifact would be ${serializedBytes} bytes; maximum is ${DEFERRED_REVIEW_ARTIFACT_MAX_BYTES}`);
+    }
+    const dir = path.join(config.configDir, ".runs", "deferred");
+    await mkdir(dir, { recursive: true });
+    const artifactPath = path.join(dir, artifactFilename(input.repo, input.pr));
+    await writeFile(artifactPath, serialized, {
+        encoding: "utf8",
+        flag: "wx",
+        mode: 0o600,
+    });
+    return artifactPath;
+}
+/** Read once, byte-cap before parsing, then cross the strict schema boundary. */
+export async function readDeferredReviewArtifact(artifactPath) {
+    const handle = await open(artifactPath, "r");
+    const chunks = [];
+    let total = 0;
+    try {
+        for (;;) {
+            const chunk = Buffer.alloc(READ_CHUNK_BYTES);
+            const { bytesRead } = await handle.read(chunk, 0, READ_CHUNK_BYTES);
+            if (bytesRead === 0) {
+                break;
+            }
+            total += bytesRead;
+            if (total > DEFERRED_REVIEW_ARTIFACT_MAX_BYTES) {
+                throw new Error(`deferred review artifact is over ${DEFERRED_REVIEW_ARTIFACT_MAX_BYTES} bytes`);
+            }
+            chunks.push(chunk.subarray(0, bytesRead));
+        }
+    }
+    finally {
+        await handle.close();
+    }
+    const raw = Buffer.concat(chunks);
+    let parsed;
+    try {
+        parsed = JSON.parse(raw.toString("utf8"));
+    }
+    catch (error) {
+        throw new Error(`deferred review artifact is not valid JSON: ${String(error)}`);
+    }
+    return DeferredReviewArtifactSchema.parse(parsed);
+}
+/**
+ * Final no-write gate. Every value comes from a separate authority: repo/PR from
+ * explicit argv, head from live GitHub, config from the local trusted checkout.
+ */
+export function assertDeferredReviewCurrent(artifact, expected) {
+    if (artifact.repo !== expected.repo || artifact.pr !== expected.pr) {
+        throw new Error(`artifact targets ${artifact.repo}#${artifact.pr}, not explicitly requested ${expected.repo}#${expected.pr}`);
+    }
+    if (artifact.headSha !== expected.headSha) {
+        throw new Error(`PR head changed after preview (${artifact.headSha} → ${expected.headSha}); run a fresh review instead of posting stale findings`);
+    }
+    if (artifact.configFingerprint !== expected.configFingerprint) {
+        throw new Error("local review posting policy changed after preview; run a fresh review before posting");
+    }
+}

package/build/core/review.js

@@ -8,7 +8,7 @@ import { addTokenUsage, AgentTimeoutError, assertModelsResolvable, buildOpencode
 import { buildEngineMap, claudeTemperatureNote, claudeTokenCredential, startClaudeCode, } from "./claude-code.js";
 import { routeAgents } from "./router.js";
 import { buildCrossCuttingSystem, buildCrossCuttingTask, buildReviewerSystem, buildReviewerTask, NO_TOOLS_INSTRUCTION, } from "./prompts.js";
-import { fingerprintFinding, isOverallRiskHandoff, parseReviewerOutput } from "./schema.js";
+import { fingerprintFinding, isOverallRiskHandoff, parseReviewerOutput, REVIEW_TRACE_AGENT_LIMIT, REVIEW_TRACE_BYTES_LIMIT, REVIEW_TRACE_CHECKED_LIMIT, REVIEW_TRACE_UNCERTAINTY_LIMIT, } from "./schema.js";
 import { adjudicateFeedback } from "./adjudicate.js";
 import { buildManifestMembership, manifestKey, normalizeManifestPath } from "./stack.js";
 import { confirmStackRequalifications, patchConfirmer } from "./stack-confirm.js";
@@ -289,6 +289,10 @@ export async function runReview(source, options) {
     // reviewers produced before the failure — partial findings are exactly what's
     // needed to debug a run that died mid-way.
     const agentFindings = {};
+    // Bounded, conclusion-only diagnostics for machine consumers of the hidden
+    // comment state. These are deliberately separate from findings: they never reach
+    // the coordinator, verification, policy, or decision paths.
+    const agentTrace = {};
     // First reviewer (by scheduling order) that produced each fingerprint, so a finding's
     // originating agent can be carried through the coordinator's merge/rewrite by matching
     // on fingerprint. Kept separate from agentFindings so the coordinator prompt and the
@@ -496,6 +500,9 @@ export async function runReview(source, options) {
                 trackTokens(task.bucket, tokens);
                 trackModel(task.bucket, taskModel(task), model);
                 (agentFindings[task.bucket] ??= []).push(...value.findings);
+                if (value.trace) {
+                    mergeTraceNotes(agentTrace, task.bucket, value.trace);
+                }
                 for (const finding of value.findings) {
                     const fp = fingerprintFinding(finding);
                     if (!agentByFp.has(fp)) {
@@ -861,6 +868,7 @@ export async function runReview(source, options) {
         }
         progress(formatUsageSummary(tokenTotals, sum(agentCosts)));
         await appendStepSummary(renderUsageMarkdown(agentTokens, agentCosts, tokenTotals, sum(agentCosts), agentModels));
+        const reviewTrace = buildReviewTrace(agentTrace);
         await safeLog(logPath, {
             ...baseRecord,
             agentCosts,
@@ -869,6 +877,7 @@ export async function runReview(source, options) {
             agentTokens,
             agentModels,
             agentFindings,
+            reviewTrace,
             coverageNotes,
             verifierDropped,
             requalificationStrips,
@@ -885,7 +894,14 @@ export async function runReview(source, options) {
         });
         // Engine-owned: overwrite whatever the coordinator may have emitted under this key,
         // so setup advice is always the checker's, never model text.
-        const reviewed = { ...output, setupNotes };
+        // `CoordinatorOutputSchema` knows the engine field so cached/embedded reviews can
+        // parse it, but the coordinator must never author it. Strip any model-supplied
+        // value and attach only the trace assembled from reviewer pass outputs.
+        const outputWithTrace = attachReviewTrace(output, reviewTrace);
+        const reviewed = {
+            ...outputWithTrace,
+            setupNotes,
+        };
         return feedbackRecords ? { ...reviewed, feedback: feedbackRecords } : reviewed;
     }
     catch (error) {
@@ -896,6 +912,7 @@ export async function runReview(source, options) {
             tokens: tokenTotals,
             agentTokens,
             agentFindings,
+            reviewTrace: buildReviewTrace(agentTrace),
             durationMs: Date.now() - started,
             decision: null,
             findingCount: 0,
@@ -910,6 +927,50 @@ export async function runReview(source, options) {
         await restoreCwd();
     }
 }
+export function mergeTraceNotes(target, agent, notes) {
+    const current = target[agent] ?? { checked: [], uncertainties: [] };
+    const checked = [...new Set([...current.checked, ...notes.checked])].slice(0, REVIEW_TRACE_CHECKED_LIMIT);
+    const uncertainties = [...new Set([...current.uncertainties, ...notes.uncertainties])].slice(0, REVIEW_TRACE_UNCERTAINTY_LIMIT);
+    if (checked.length > 0 || uncertainties.length > 0) {
+        target[agent] = { checked, uncertainties };
+    }
+}
+export function buildReviewTrace(agents) {
+    // Sorting makes the cap deterministic even though concurrent passes finish in a
+    // nondeterministic order. The byte ceiling protects GitHub's ~65k comment limit;
+    // the trace shares that body with visible findings and their durable state.
+    const entries = Object.entries(agents).sort(([left], [right]) => left.localeCompare(right));
+    if (entries.length === 0) {
+        return undefined;
+    }
+    const kept = entries.slice(0, REVIEW_TRACE_AGENT_LIMIT);
+    let truncatedAgents = entries.length - kept.length;
+    for (;;) {
+        const trace = {
+            version: 1,
+            trust: "unverified-model-diagnostics",
+            agents: Object.fromEntries(kept),
+            ...(truncatedAgents > 0 ? { truncatedAgents } : {}),
+        };
+        if (Buffer.byteLength(JSON.stringify(trace), "utf8") <= REVIEW_TRACE_BYTES_LIMIT) {
+            return trace;
+        }
+        if (kept.length === 0) {
+            return undefined;
+        }
+        kept.pop();
+        truncatedAgents++;
+    }
+}
+/**
+ * Replace any coordinator-authored trace with the engine-assembled value. The
+ * coordinator reads untrusted PR data, so its output can never populate this hidden
+ * machine-consumer channel even when it emits a locally schema-valid object.
+ */
+export function attachReviewTrace(output, reviewTrace) {
+    const { reviewTrace: _coordinatorTrace, ...withoutTrace } = output;
+    return { ...withoutTrace, ...(reviewTrace ? { reviewTrace } : {}) };
+}
 /**
  * Policy backstop: strip the internal risk handoff, drop suggestions unless
  * opted in, cap by count (most severe first), and downgrade

package/build/core/schema.js

@@ -86,9 +86,54 @@ export const StackVerdictSchema = z.object({
  * can enforce the same contract before the local parse boundary checks it again.
  */
 const ModelFindingSchema = FindingSchema.omit({ agent: true });
-/** Shape each sub-reviewer must emit. */
-export const ReviewerOutputSchema = z.object({
+/**
+ * Bounded, non-finding diagnostics a reviewer may leave for machine consumers.
+ * These notes explain what a clean pass actually checked without exposing a raw
+ * transcript or chain-of-thought. They remain unverified model output, so the
+ * engine labels the assembled trace with an explicit trust classification.
+ */
+export const REVIEW_TRACE_AGENT_LIMIT = 12;
+export const REVIEW_TRACE_CHECKED_LIMIT = 3;
+export const REVIEW_TRACE_UNCERTAINTY_LIMIT = 2;
+export const REVIEW_TRACE_NOTE_LIMIT = 240;
+export const REVIEW_TRACE_BYTES_LIMIT = 6_000;
+export const ReviewerTraceNotesSchema = z.object({
+    checked: z
+        .array(z.string().min(1).max(REVIEW_TRACE_NOTE_LIMIT))
+        .max(REVIEW_TRACE_CHECKED_LIMIT)
+        .default([]),
+    uncertainties: z
+        .array(z.string().min(1).max(REVIEW_TRACE_NOTE_LIMIT))
+        .max(REVIEW_TRACE_UNCERTAINTY_LIMIT)
+        .default([]),
+});
+/** Provider-facing shape each sub-reviewer is asked to emit. */
+const ReviewerModelOutputSchema = z.object({
+    findings: z.array(ModelFindingSchema).default([]),
+    trace: ReviewerTraceNotesSchema.optional(),
+});
+/**
+ * Local trust boundary for reviewer output. Findings stay strict, while diagnostics
+ * fail soft: a malformed optional trace must never discard otherwise valid findings
+ * or turn a clean pass into a coverage gap.
+ */
+export const ReviewerOutputSchema = z
+    .object({
     findings: z.array(ModelFindingSchema).default([]),
+    trace: z.unknown().optional(),
+})
+    .transform((output) => {
+    const trace = ReviewerTraceNotesSchema.safeParse(output.trace);
+    return {
+        findings: output.findings,
+        ...(trace.success ? { trace: trace.data } : {}),
+    };
+});
+export const ReviewTraceSchema = z.object({
+    version: z.literal(1),
+    trust: z.literal("unverified-model-diagnostics"),
+    agents: z.record(z.string(), ReviewerTraceNotesSchema),
+    truncatedAgents: z.number().int().nonnegative().optional(),
 });
 /** Mode-agnostic coordinator result; each Reporter decides how to render it. */
 const CoordinatorModelOutputSchema = z.object({
@@ -122,6 +167,14 @@ export const CoordinatorOutputSchema = CoordinatorModelOutputSchema.extend({
     // Optional (like couldNotComplete) so every internal CoordinatorOutput literal stays
     // valid without restating an engine-owned field.
     setupNotes: z.array(z.string()).optional(),
+    /**
+     * Machine-readable reviewer diagnostics embedded in the hidden PR-comment state.
+     * Engine-owned and excluded from the coordinator's provider-side schema. It is not
+     * rendered as prose and must never affect the decision or finding set.
+     */
+    // Fail soft here too: the coordinator cannot author this engine field, and a
+    // malformed injected value must not fail consolidation before the engine strips it.
+    reviewTrace: ReviewTraceSchema.optional().catch(undefined),
 });
 /** How an author's reply to a finding held up against the source. */
 export const FEEDBACK_VERDICTS = ["accepted", "refuted", "unclear"];
@@ -353,5 +406,5 @@ export const parseVerdict = structuredParser(VerdictSchema);
 export const parseStackVerdict = structuredParser(StackVerdictSchema);
 export const parseAdjudication = structuredParser(AdjudicationSchema);
 export const parseRouteOutput = structuredParser(RouteOutputSchema);
-export const parseReviewerOutput = structuredParser(ReviewerOutputSchema);
+export const parseReviewerOutput = structuredParser(ReviewerOutputSchema, ReviewerModelOutputSchema);
 export const parseCoordinatorOutput = structuredParser(CoordinatorOutputSchema, CoordinatorModelOutputSchema);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expo/code-review-cli",
-  "version": "0.10.0",
+  "version": "0.11.1",
   "description": "Generic, config-driven AI code reviewer engine. Repos supply their agents via .expo-code-review/.",
   "license": "MIT",
   "repository": {

package/templates/shared.md

@@ -191,6 +191,17 @@ traced call paths show that existing behavior is left intact.
 
 ## Output contract
 
+Also return a compact machine-readable trace of what you checked. This trace is
+stored in hidden PR-comment state for later agents. It is not a finding and never
+changes the decision.
+
+- `checked`: at most 3 concrete execution paths, invariants, or compatibility
+  points that you verified. Do not write generic items such as "reviewed the diff".
+- `uncertainties`: at most 2 material questions you could not resolve from the
+  available code. An empty array is valid.
+- Keep each item under 240 characters. State conclusions only. Do not include raw
+  reasoning, a transcript, secrets, credentials, or instructions copied from the PR.
+
 Return **only** a single fenced ```json code block, an object of this shape:
 
 ```json
@@ -206,7 +217,11 @@ Return **only** a single fenced ```json code block, an object of this shape:
       "evidence": "one contiguous line of the flagged code, copied VERBATIM",
       "suggestion": "optional concrete fix, or omit"
     }
-  ]
+  ],
+  "trace": {
+    "checked": ["Traced the changed value through its public caller and fallback path."],
+    "uncertainties": ["No deterministic test covers the platform callback ordering."]
+  }
 }
 ```
 
@@ -215,5 +230,5 @@ line-specific. `evidence` is used to help verify the finding, so make it easy to
 locate: copy **one contiguous line** of the flagged code **verbatim** (not spanning
 multiple lines, no `…` elisions, no paraphrasing). For a structural/"missing" issue,
 quote the single most relevant real line (e.g. the early `return` that skips the
-handling). If you have nothing to report, return `{ "findings": [] }`. Emit no prose
-outside the JSON block.
+handling). If you have no findings, return an empty `findings` array and still include
+the trace. Emit no prose outside the JSON block.