@mechanai/deepreview 2.1.5 → 2.2.0

package/.opencode/agents/deepreview-applier.md

@@ -21,7 +21,7 @@ For each fix in the plan, in the order specified by the "Order of Operations" se
 
 1. Read the current file at the referenced location
 2. Apply the code change exactly as specified in the plan
-3. **Globalize check:** After applying, check whether other files _listed in input.txt or the plan_ have the same pattern. If so, apply the equivalent fix there too. Do NOT search the broader codebase. Common cases:
+3. **Globalize check:** After applying, check whether other files _listed in input.txt or the plan_ have the same pattern. If so, apply the equivalent fix there too. Do NOT search the broader codebase. To identify "listed files": for diff inputs, use files from `diff --git a/... b/...` headers; for concatenated file inputs, use files from `=== filename ===` headers. Common cases:
    - A loop command fix that applies to the other loop command (code-loop ↔ spec-loop)
    - A prompt/contract change affecting multiple agent files
    - A variable rename or policy change referenced in multiple files

package/.opencode/agents/deepreview-review-formatter.md

@@ -22,18 +22,34 @@ Read both files.
 ## Process
 
 1. Read the synthesis and identify every individual finding (each bullet or paragraph that describes a distinct issue)
-2. For each finding, determine:
+2. If the synthesis contains an "Overall Assessment" section, emit it as the **first document** with frontmatter `summary: true` (no `path` or `line`). The body should be the assessment text, lightly edited for brevity.
+3. For each finding, determine:
    - `path`: the file path (relative to repo root) the finding refers to
    - `line`: the specific line number (new-side of diff). If the synthesis gives a range, use the end line.
    - `startLine`: if the finding spans multiple lines, use the start of the range. Omit if single-line.
-3. Read `input.txt` (the diff) to:
+4. Read `input.txt` (the diff) to:
    - Verify line references are correct
    - Generate ` ```suggestion ` blocks where a concrete fix is obvious and fits within the diff
-4. Write each finding as a document in the output file
+5. Write each finding as a document in the output file
 
 ## Output format
 
-Write to the output path provided. Use this exact format — one document per finding, separated by `---`:
+Write to the output path provided. The file has two parts:
+
+### 1. Summary document (first, when synthesis has an Overall Assessment)
+
+If the synthesis contains an "Overall Assessment" section, the first document must have `summary: true` in its frontmatter. Its body is a 2-3 sentence overall assessment. This appears as the review body on GitHub. Omit this document only if the synthesis has no assessment section.
+
+```
+---
+summary: true
+---
+<2-3 sentence overall assessment from the synthesis>
+```
+
+### 2. Finding documents (one per finding)
+
+Each finding follows the summary, separated by `---`:
 
 ```
 ---
@@ -49,7 +65,7 @@ line: <line number>
 - One finding per document. Never bundle multiple issues.
 - No stats, severity counts, or framing ("3 critical issues found")
 - No references to local file paths, session directories, AI tooling, or the deepreview pipeline
-- Use permalinks for code references: `https://github.com/OWNER/REPO/blob/$PR_HEAD_SHA/<path>#L<line>`
+- Use permalinks for code references: `https://github.com/OWNER/REPO/blob/<PR_HEAD_SHA>/<path>#L<line>`
   - Get OWNER/REPO from the diff header or from `input.txt` context
 - Use ` ```suggestion ` blocks where a concrete fix is obvious
 - American English. Succinct. No filler.

package/.opencode/commands/deepreview-loop.md

@@ -8,13 +8,14 @@ STEP 1: DETERMINE INPUT MODE
 Parse "$ARGUMENTS" the same way as /deepreview:
 
 - If it starts with `--context <path>`, extract CONTEXT_FILE=<path> and remove it from $ARGUMENTS before parsing the rest.
-- Validate CONTEXT_FILE: it must be a relative path (no leading `/`), must not contain `..`, must exist on disk, and must be a regular file (not a directory or symlink to outside the project), and must be under 50KB. If validation fails, tell the user the error and STOP.
+- Validate `CONTEXT_FILE`: it must be a relative path (no leading `/`), must not contain `..`, must exist on disk, and must be a regular file (not a directory or symlink to outside the project), and must be under 50KB. If validation fails, tell the user the error and STOP.
+  _(Canonical source for `CONTEXT_FILE` validation rules. Keep `deepreview.md`, `deepreview-spec.md`, and `deepreview-spec-loop.md` in sync.)_
 - If it is a number → MODE=pr, TARGET="$ARGUMENTS"
 - If it is a file path or multiple file paths → MODE=files, TARGET="$ARGUMENTS"
 - If it is empty → MODE=branch, TARGET=""
 
 Set ITERATION=1
-Set PRIOR_CONTEXT="" (empty — built up across iterations)
+Set PRIOR_CONTEXT="" (empty — built up across iterations; holds both design context and prior findings)
 Set ALL_SESSION_DIRS=[] (list of all session directories used, in order)
 
 If CONTEXT_FILE exists, read its contents and set PRIOR_CONTEXT to:

package/.opencode/commands/deepreview-spec-loop.md

@@ -11,7 +11,7 @@ STEP 1: DETERMINE INPUT
 - If remaining "$ARGUMENTS" is empty, tell the user "Usage: /deepreview-spec-loop [--context <file>] <file1> [file2 ...]" and STOP.
 - Set FILES="$ARGUMENTS"
 - Set ITERATION=1
-- Set PRIOR_CONTEXT="" (empty — built up across iterations)
+- Set PRIOR_CONTEXT="" (empty — built up across iterations; holds both design context and prior findings)
 - Set ALL_SESSION_DIRS=[] (list of all session directories used, in order)
 - If CONTEXT_FILE exists, set PRIOR_CONTEXT="## Design Decisions (intentional — do not flag)\nThe following are deliberate design choices. Do NOT flag these as issues or suggest alternatives.\n`\n" + contents of CONTEXT_FILE + "\n`\n\n"
 
@@ -81,7 +81,7 @@ Task — Use the Task tool with subagent_type="general":
 
 Deduplicate findings that appear in multiple syntheses. Return ONLY these two sections, nothing else."
 
-Set PRIOR_CONTEXT to the returned text. If CONTEXT_FILE exists, prepend:
+Set PRIOR_CONTEXT to the returned text. Validate that it contains "## Prior Findings" — if not, warn the user ("Helper returned malformed prior context — proceeding without deduplication") and set PRIOR_CONTEXT="". If CONTEXT_FILE exists, prepend:
 "## Design Decisions (intentional — do not flag)\nThe following are deliberate design choices. Do NOT flag these as issues or suggest alternatives.\n`\n" + contents of CONTEXT_FILE + "\n`\n\n"
 
 The REVIEWER_PREAMBLE for all iter2+ reviewers is:

package/README.md

@@ -83,6 +83,23 @@ its own context, keeping token usage minimal.
 - `git`
 - `gh` CLI (only for PR commands)
 
+## Upgrade
+
+OpenCode caches plugins on first install and does not automatically check for newer versions.
+To upgrade:
+
+```bash
+rm -rf ~/.cache/opencode/packages/*deepreview*/
+```
+
+Then restart OpenCode. It will re-fetch the latest version.
+
+If you installed with `--local`, also re-run the setup script to update symlinks:
+
+```bash
+bunx @mechanai/deepreview@latest/setup --local
+```
+
 > [!NOTE]
 > If upgrading from the old `npx @anthropic/deepreview install` workflow, remove
 > the old copied files first (`rm ~/.config/opencode/agents/deepreview*

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mechanai/deepreview",
-  "version": "2.1.5",
+  "version": "2.2.0",
   "description": "Multi-agent parallel code/spec review for OpenCode",
   "license": "MIT",
   "repository": {

package/src/diff-classifier.ts

@@ -22,8 +22,18 @@ interface FileHunks {
  * Tier 2: file-level (file in diff but line not in any hunk)
  * Tier 3: review body (file not in diff)
  */
+// 5MB — diffs larger than this are truncated before parsing
+const MAX_DIFF_SIZE = 5 * 1024 * 1024;
+
 export function classifyFindings(findings: Finding[], diffText: string): ClassifiedFinding[] {
-  const parsed = parseDiff(diffText);
+  let effectiveDiff = diffText;
+  if (diffText.length > MAX_DIFF_SIZE) {
+    console.warn(
+      `WARN: Diff size (${(diffText.length / 1024 / 1024).toFixed(1)}MB) exceeds ${MAX_DIFF_SIZE / 1024 / 1024}MB limit. Truncating — some findings may be demoted to tier 3.`,
+    );
+    effectiveDiff = diffText.slice(0, MAX_DIFF_SIZE);
+  }
+  const parsed = parseDiff(effectiveDiff);
   const fileMap = buildFileMap(parsed);
 
   return findings.map((finding) => {

package/src/parse-threads.test.ts

@@ -2,7 +2,76 @@ import { describe, it } from "bun:test";
 import assert from "node:assert/strict";
 import { parseThreads } from "./parse-threads.ts";
 
-describe("parseThreads", () => {
+describe("parseThreads summary extraction", () => {
+  it("extracts a summary document marked with summary: true", () => {
+    const input = [
+      "---",
+      "summary: true",
+      "---",
+      "Overall this PR looks good with minor issues.",
+      "---",
+      "path: src/main.go",
+      "line: 10",
+      "---",
+      "Error not propagated.",
+    ].join("\n");
+
+    const result = parseThreads(input);
+    assert.equal(result.summary, "Overall this PR looks good with minor issues.");
+    assert.equal(result.findings.length, 1);
+    assert.equal(result.findings[0].path, "src/main.go");
+  });
+
+  it("returns undefined summary when no summary document exists", () => {
+    const input = ["---", "path: src/main.go", "line: 10", "---", "Error not propagated."].join(
+      "\n",
+    );
+
+    const result = parseThreads(input);
+    assert.equal(result.summary, undefined);
+    assert.equal(result.findings.length, 1);
+  });
+
+  it("handles summary at end of file", () => {
+    const input = [
+      "---",
+      "path: src/main.go",
+      "line: 10",
+      "---",
+      "Finding body.",
+      "---",
+      "summary: true",
+      "---",
+      "Summary at the end.",
+    ].join("\n");
+
+    const result = parseThreads(input);
+    assert.equal(result.summary, "Summary at the end.");
+    assert.equal(result.findings.length, 1);
+  });
+});
+
+describe("parseThreads summary edge cases", () => {
+  it("treats empty summary body as empty string", () => {
+    const input = [
+      "---",
+      "summary: true",
+      "---",
+      "",
+      "---",
+      "path: src/main.go",
+      "line: 10",
+      "---",
+      "Finding.",
+    ].join("\n");
+
+    const result = parseThreads(input);
+    assert.equal(result.summary, "");
+    assert.equal(result.findings.length, 1);
+  });
+});
+
+describe("parseThreads findings", () => {
   it("parses a single finding", () => {
     const input = [
       "---",
@@ -13,11 +82,11 @@ describe("parseThreads", () => {
     ].join("\n");
 
     const result = parseThreads(input);
-    assert.equal(result.length, 1);
-    assert.equal(result[0].path, "pkg/server/handler.go");
-    assert.equal(result[0].line, 48);
-    assert.equal(result[0].startLine, undefined);
-    assert.equal(result[0].body.trim(), "The error is silently discarded.");
+    assert.equal(result.findings.length, 1);
+    assert.equal(result.findings[0].path, "pkg/server/handler.go");
+    assert.equal(result.findings[0].line, 48);
+    assert.equal(result.findings[0].startLine, undefined);
+    assert.equal(result.findings[0].body.trim(), "The error is silently discarded.");
   });
 
   it("parses multiple findings separated by ---", () => {
@@ -36,23 +105,23 @@ describe("parseThreads", () => {
     ].join("\n");
 
     const result = parseThreads(input);
-    assert.equal(result.length, 2);
-    assert.equal(result[0].path, "a.go");
-    assert.equal(result[0].startLine, 10);
-    assert.equal(result[0].line, 15);
-    assert.equal(result[1].path, "b.go");
-    assert.equal(result[1].line, 3);
+    assert.equal(result.findings.length, 2);
+    assert.equal(result.findings[0].path, "a.go");
+    assert.equal(result.findings[0].startLine, 10);
+    assert.equal(result.findings[0].line, 15);
+    assert.equal(result.findings[1].path, "b.go");
+    assert.equal(result.findings[1].line, 3);
   });
 
   it("ignores startLine: 0 (treats as single-line)", () => {
     const input = ["---", "path: x.go", "startLine: 0", "line: 5", "---", "Body."].join("\n");
 
     const result = parseThreads(input);
-    assert.equal(result[0].startLine, undefined);
+    assert.equal(result.findings[0].startLine, undefined);
   });
 
-  it("returns empty array for empty input", () => {
+  it("returns empty findings for empty input", () => {
     const result = parseThreads("");
-    assert.equal(result.length, 0);
+    assert.equal(result.findings.length, 0);
   });
 });

package/src/parse-threads.ts

@@ -2,6 +2,12 @@ import matter from "gray-matter";
 import yaml from "js-yaml";
 import type { Finding } from "./diff-classifier.ts";
 
+/** @internal Not part of the public API — subject to change without notice. */
+export interface ParsedThreads {
+  findings: Finding[];
+  summary?: string;
+}
+
 /**
  * gray-matter engine restricted to safe YAML parsing (no !!js/function etc.).
  * FAILSAFE_SCHEMA returns all scalars as strings — numeric fields (line, startLine)
@@ -16,11 +22,13 @@ const safeYamlEngine = (s: string): Record<string, unknown> => {
 const matterOptions = { engines: { yaml: safeYamlEngine } };
 
 /**
- * Parse a threads.md file into an array of finding objects.
- * The file uses --- separators between findings, each with YAML frontmatter.
+ * Parse a threads.md file into findings and an optional summary.
+ * The file uses --- separators between documents, each with YAML frontmatter.
+ * A document with `summary: true` in its frontmatter is extracted as the review summary.
  */
-function parseThreads(content: string): Finding[] {
+function parseThreads(content: string): ParsedThreads {
   const findings: Finding[] = [];
+  let summary: string | undefined;
   const documents = splitDocuments(content);
 
   for (const doc of documents) {
@@ -33,6 +41,16 @@ function parseThreads(content: string): Finding[] {
       continue;
     }
     const data = parsed.data as Record<string, unknown>;
+
+    // Handle summary documents
+    if (String(data.summary).toLowerCase() === "true") {
+      if (summary !== undefined) {
+        console.warn("WARN: Multiple summary documents found — using the last one.");
+      }
+      summary = parsed.content.trim();
+      continue;
+    }
+
     const path = typeof data.path === "string" ? data.path : undefined;
     const lineNum = Number(data.line);
     if (path === undefined || path === "" || !Number.isFinite(lineNum) || lineNum < 1) {
@@ -56,7 +74,7 @@ function parseThreads(content: string): Finding[] {
     });
   }
 
-  return findings;
+  return { findings, summary };
 }
 
 const YAML_KEY_RE = /^\w[\w\s]*:/u;

package/src/post-review.test.ts

@@ -2,6 +2,36 @@ import { describe, it } from "bun:test";
 import assert from "node:assert/strict";
 import { parseThreads } from "./parse-threads.ts";
 import { classifyFindings } from "./diff-classifier.ts";
+import { buildReviewBody } from "./review-helpers.ts";
+
+describe("buildReviewBody", () => {
+  it("includes summary when provided and no tier3 findings", () => {
+    const body = buildReviewBody([], "owner", "repo", "a".repeat(40), "Overall looks good.");
+    assert.ok(body.includes("Overall looks good."));
+    assert.ok(body.includes("🤖 Review generated by AI"));
+  });
+
+  it("includes both summary and tier3 findings", () => {
+    const tier3 = [{ path: "pkg/other.go", line: 5, body: "Unused import.", tier: 3 as const }];
+    const body = buildReviewBody(tier3, "owner", "repo", "a".repeat(40), "Has issues.");
+    assert.ok(body.includes("Has issues."));
+    assert.ok(body.includes("pkg/other.go"));
+    assert.ok(body.includes("Unused import."));
+  });
+
+  it("works without summary (backward compatible)", () => {
+    const tier3 = [{ path: "pkg/other.go", line: 5, body: "Unused import.", tier: 3 as const }];
+    const body = buildReviewBody(tier3, "owner", "repo", "a".repeat(40));
+    assert.ok(!body.includes("undefined"));
+    assert.ok(body.includes("pkg/other.go"));
+    assert.ok(body.includes("🤖 Review generated by AI"));
+  });
+
+  it("only shows trailer when no summary and no tier3 findings", () => {
+    const body = buildReviewBody([], "owner", "repo", "a".repeat(40));
+    assert.equal(body, "\n\n---\n🤖 Review generated by AI");
+  });
+});
 
 describe("integration: parse → classify", () => {
   const threadsContent = [
@@ -38,7 +68,7 @@ describe("integration: parse → classify", () => {
   ].join("\n");
 
   it("classifies findings correctly across all 3 tiers", () => {
-    const findings = parseThreads(threadsContent);
+    const { findings } = parseThreads(threadsContent);
     assert.equal(findings.length, 3);
 
     const classified = classifyFindings(findings, diff);

package/src/post-review.ts

@@ -1,8 +1,7 @@
 import { readFile, realpath } from "node:fs/promises";
 import { resolve } from "node:path";
 import { parseThreads } from "./parse-threads.ts";
-import { classifyFindings } from "./diff-classifier.ts";
-import type { Finding, ClassifiedFinding } from "./diff-classifier.ts";
+import { type Finding, type ClassifiedFinding } from "./diff-classifier.ts";
 import { type PrInfo, getPrInfo, execFileAsync } from "./graphql.ts";
 import {
   type PendingReview,
@@ -14,12 +13,13 @@ import {
   updateReviewComment,
 } from "./review-api.ts";
 import {
-  escapeHtml,
   isValidPath,
   isRateLimitError,
   findingId,
   embedFindingId,
   extractFindingId,
+  buildReviewBody,
+  classifyAndLog,
 } from "./review-helpers.ts";
 
 export interface PostReviewOptions {
@@ -37,27 +37,7 @@ export interface PostReviewResult {
   failed: string[];
 }
 
-const AI_TRAILER = "\n\n---\n🤖 Review generated by AI";
-
-function buildReviewBody(
-  tier3Findings: ClassifiedFinding[],
-  owner: string,
-  name: string,
-  headOid: string,
-): string {
-  let body = "";
-  for (const f of tier3Findings) {
-    if (!isValidPath(f.path)) {
-      console.warn(`WARN: Skipping finding with suspicious path: ${f.path}`);
-      continue;
-    }
-    const permalink = `https://github.com/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/blob/${headOid}/${f.path.split("/").map(encodeURIComponent).join("/")}#L${f.line}`;
-    // Neutralize all HTML tags — GitHub re-renders markdown inside <details>.
-    body += `<details>\n<summary><a href="${permalink}"><code>${escapeHtml(f.path)}:${f.line}</code></a></summary>\n\n${f.body}\n</details>\n\n`;
-  }
-  body += AI_TRAILER;
-  return body;
-}
+const MAX_INLINE_FINDINGS = 200;
 
 async function updateExistingThreads(
   existingReview: PendingReview,
@@ -79,9 +59,16 @@ async function updateExistingThreads(
     }
   }
 
-  for (const { finding, commentId, id } of toUpdate) {
-    const body = embedFindingId(finding.body, id);
-    await updateReviewComment(commentId, body);
+  const CONCURRENCY = 2;
+  for (let i = 0; i < toUpdate.length; i += CONCURRENCY) {
+    if (i > 0) await Bun.sleep(1000);
+    const batch = toUpdate.slice(i, i + CONCURRENCY);
+    await Promise.all(
+      batch.map(async ({ finding, commentId, id }) => {
+        const body = embedFindingId(finding.body, id);
+        await updateReviewComment(commentId, body);
+      }),
+    );
   }
 
   console.log(`Updated ${toUpdate.length} existing threads.`);
@@ -146,13 +133,20 @@ async function postInlineThreads(
     (f) => !updatedIds.has(findingId(f.path, f.startLine, f.line, f.body)),
   );
 
-  for (let i = 0; i < pending.length; i += CONCURRENCY) {
+  if (pending.length > MAX_INLINE_FINDINGS) {
+    console.warn(
+      `WARN: ${pending.length} inline findings exceed limit of ${MAX_INLINE_FINDINGS}. Truncating.`,
+    );
+  }
+  const capped = pending.slice(0, MAX_INLINE_FINDINGS);
+
+  for (let i = 0; i < capped.length; i += CONCURRENCY) {
     if (i > 0) await Bun.sleep(1000);
-    const batch = pending.slice(i, i + CONCURRENCY);
+    const batch = capped.slice(i, i + CONCURRENCY);
     const results = await Promise.all(
       batch.map(async (f) => {
         const id = findingId(f.path, f.startLine, f.line, f.body);
-        // Trust boundary: body content is rendered by GitHub's Markdown sanitizer
+        // Body rendered by GitHub's Markdown sanitizer; no escaping needed here
         const body = embedFindingId(f.body, id);
         const ok = await postWithRetry(reviewId, f, body);
         return ok ? null : id;
@@ -165,31 +159,6 @@ async function postInlineThreads(
   return failedFindings;
 }
 
-function classifyAndLog(
-  findings: Finding[],
-  diff: string,
-): { tier1: ClassifiedFinding[]; tier2: ClassifiedFinding[]; tier3: ClassifiedFinding[] } {
-  const validated = findings.filter((f) => {
-    if (!isValidPath(f.path)) {
-      console.warn(`WARN: Skipping finding with suspicious path: ${f.path}`);
-      return false;
-    }
-    return true;
-  });
-  const classified = classifyFindings(validated, diff);
-  const tier1 = classified.filter((f) => f.tier === 1);
-  const tier2 = classified.filter((f) => f.tier === 2);
-  const tier3 = classified.filter((f) => f.tier === 3);
-
-  for (const f of tier2) {
-    console.warn(`WARN: ${f.path}:${f.line} demoted to file-level`);
-  }
-  for (const f of tier3) {
-    console.warn(`WARN: ${f.path}:${f.line} demoted to review body`);
-  }
-  return { tier1, tier2, tier3 };
-}
-
 async function ensureReview(
   prNodeId: string,
   headOid: string,
@@ -198,18 +167,22 @@ async function ensureReview(
   tier3: ClassifiedFinding[],
   owner: string,
   name: string,
+  summary?: string,
 ): Promise<{ reviewId: string; updatedFindings: Set<string> }> {
   const existingReview = await findPendingReview(prNodeId);
   if (existingReview) {
     console.log(`Found existing pending review: ${existingReview.id}`);
-    await updateReviewBody(existingReview.id, buildReviewBody(tier3, owner, name, headOid));
+    await updateReviewBody(
+      existingReview.id,
+      buildReviewBody(tier3, owner, name, headOid, summary),
+    );
     const updated = await updateExistingThreads(existingReview, [...tier1, ...tier2]);
     return { reviewId: existingReview.id, updatedFindings: updated };
   }
   const reviewId = await createPendingReview(
     prNodeId,
     headOid,
-    buildReviewBody(tier3, owner, name, headOid),
+    buildReviewBody(tier3, owner, name, headOid, summary),
   );
   console.log(`Created pending review: ${reviewId}`);
   return { reviewId, updatedFindings: new Set() };
@@ -220,10 +193,11 @@ async function loadAndValidatePr(
   prNumber: number,
   expectedSha: string | undefined,
   cwd: string | undefined,
-): Promise<{ findings: Finding[]; prInfo: PrInfo } | null> {
+): Promise<{ findings: Finding[]; prInfo: PrInfo; summary?: string } | null> {
   if (!isValidPath(threadsPath)) {
     throw new Error(`Invalid threadsPath: ${threadsPath}`);
   }
+  // cwd is a trusted parameter set by the plugin framework (not user-supplied)
   const base = await realpath(resolve(cwd ?? process.cwd()));
   const candidatePath = resolve(base, threadsPath);
   let resolved: string;
@@ -236,8 +210,8 @@ async function loadAndValidatePr(
     throw new Error(`threadsPath escapes working directory: ${threadsPath}`);
   }
   const content = await readFile(resolved, "utf8");
-  const findings = parseThreads(content);
-  if (findings.length === 0) return null;
+  const { findings, summary } = parseThreads(content);
+  if (findings.length === 0 && (summary === undefined || summary === "")) return null;
 
   const prInfo = await getPrInfo(prNumber, { cwd });
   if (prInfo.state !== "OPEN") {
@@ -249,7 +223,7 @@ async function loadAndValidatePr(
     throw new Error(`ABORT: PR head moved (expected ${resolvedSha}, got ${prInfo.headOid}).`);
   }
 
-  return { findings, prInfo };
+  return { findings, prInfo, summary };
 }
 
 async function postFindings(
@@ -258,6 +232,7 @@ async function postFindings(
   tier3: ClassifiedFinding[],
   prInfo: PrInfo,
   skipIds: string[],
+  summary?: string,
 ): Promise<PostReviewResult> {
   const { owner, name, prNodeId, headOid } = prInfo;
   const { reviewId, updatedFindings } = await ensureReview(
@@ -268,6 +243,7 @@ async function postFindings(
     tier3,
     owner,
     name,
+    summary,
   );
 
   const skipSet = new Set(skipIds);
@@ -280,28 +256,28 @@ async function postFindings(
   const skipped = inlineFindings.filter((f) =>
     updatedFindings.has(findingId(f.path, f.startLine, f.line, f.body)),
   ).length;
-  const posted = inlineFindings.length - skipped - failedIds.length;
+  const pending = inlineFindings.length - skipped;
+  const truncatedCount = Math.max(0, pending - MAX_INLINE_FINDINGS);
+  const posted = Math.min(pending, MAX_INLINE_FINDINGS) - failedIds.length;
   const totalFindings = [...tier1, ...tier2].length;
   const skippedByUser = totalFindings - inlineFindings.length;
-  const summary =
-    `Posted ${posted}/${totalFindings} inline threads (${skipped} up-to-date, ${skippedByUser} skipped, ${failedIds.length} failed). ` +
+  const statusSummary =
+    `Posted ${posted}/${totalFindings} inline threads (${skipped} up-to-date, ${skippedByUser} skipped, ${failedIds.length} failed${truncatedCount > 0 ? `, ${truncatedCount} truncated` : ""}). ` +
     `${tier3.length} findings in review body.`;
 
-  console.log(summary);
+  console.log(statusSummary);
 
-  return { summary, failed: failedIds };
+  return { summary: statusSummary, failed: failedIds };
 }
 
-/**
- * Post a review to a GitHub PR.
- */
 export async function postReview(opts: PostReviewOptions): Promise<PostReviewResult> {
   const { threadsPath, prNumber, dryRun = false, skipIds = [], expectedSha } = opts;
 
   const result = await loadAndValidatePr(threadsPath, prNumber, expectedSha, opts.cwd);
   if (!result) return { summary: "No findings to post.", failed: [] };
 
-  const { findings, prInfo } = result;
+  const { findings, prInfo, summary: reviewSummary } = result;
+
   const diff =
     opts.diffText ??
     (
@@ -321,5 +297,5 @@ export async function postReview(opts: PostReviewOptions): Promise<PostReviewRes
     };
   }
 
-  return postFindings(tier1, tier2, tier3, prInfo, skipIds);
+  return postFindings(tier1, tier2, tier3, prInfo, skipIds, reviewSummary);
 }

package/src/review-api.ts

@@ -64,7 +64,15 @@ async function fetchRemainingComments(
   const comments: ReviewComment[] = [];
   let pageInfo = initialPageInfo;
   let pages = 0;
+  // 5 minute aggregate timeout for pagination
+  const deadline = Date.now() + 5 * 60 * 1000;
   while (pageInfo.hasNextPage && pages++ < MAX_PAGES) {
+    if (Date.now() > deadline) {
+      console.warn(
+        `WARN: Aggregate timeout reached after ${pages} pages. Returning partial results.`,
+      );
+      break;
+    }
     const page = await graphql<CommentsPage>(
       `
         query ($reviewId: ID!, $after: String!) {

package/src/review-helpers.ts

@@ -1,6 +1,9 @@
 import crypto from "node:crypto";
+import { classifyFindings, type Finding, type ClassifiedFinding } from "./diff-classifier.ts";
 
 const FINDING_ID_RE = /<!-- finding:([a-f0-9]+) -->/u;
+const AI_TRAILER = "\n\n---\n🤖 Review generated by AI";
+const GITHUB_NAME_RE = /^[a-zA-Z0-9](?:[a-zA-Z0-9._-]*[a-zA-Z0-9])?$/u;
 
 export function escapeHtml(s: string): string {
   return s
@@ -63,3 +66,66 @@ export function extractFindingId(body: string): string | null {
   const match = FINDING_ID_RE.exec(body);
   return match ? match[1] : null;
 }
+
+/** @internal Not part of the public API — subject to change without notice. */
+export function buildReviewBody(
+  tier3Findings: ClassifiedFinding[],
+  owner: string,
+  name: string,
+  headOid: string,
+  summary?: string,
+): string {
+  const validOid = /^[0-9a-f]{40,64}$/u.test(headOid);
+  if (!validOid) {
+    console.warn(`WARN: Invalid headOid format (${headOid}). Skipping permalinks.`);
+  }
+  const validRepo = GITHUB_NAME_RE.test(owner) && GITHUB_NAME_RE.test(name);
+  if (!validRepo) {
+    console.warn(`WARN: Invalid owner/name format (${owner}/${name}). Skipping permalinks.`);
+  }
+  let body = "";
+  if (summary !== undefined && summary !== "") {
+    // Trust boundary: summary is AI-generated Markdown from the formatter agent,
+    // rendered by GitHub's Markdown sanitizer (same trust level as finding bodies).
+    body += summary + "\n\n";
+  }
+  for (const f of tier3Findings) {
+    if (!isValidPath(f.path)) {
+      console.warn(`WARN: Skipping finding with suspicious path: ${f.path}`);
+      continue;
+    }
+    if (validOid && validRepo) {
+      const permalink = `https://github.com/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/blob/${headOid}/${f.path.split("/").map(encodeURIComponent).join("/")}#L${f.line}`;
+      body += `<details>\n<summary><a href="${permalink}"><code>${escapeHtml(f.path)}:${f.line}</code></a></summary>\n\n${f.body}\n</details>\n\n`;
+    } else {
+      body += `<details>\n<summary><code>${escapeHtml(f.path)}:${f.line}</code></summary>\n\n${f.body}\n</details>\n\n`;
+    }
+  }
+  body += AI_TRAILER;
+  return body;
+}
+
+export function classifyAndLog(
+  findings: Finding[],
+  diff: string,
+): { tier1: ClassifiedFinding[]; tier2: ClassifiedFinding[]; tier3: ClassifiedFinding[] } {
+  const validated = findings.filter((f) => {
+    if (!isValidPath(f.path)) {
+      console.warn(`WARN: Skipping finding with suspicious path: ${f.path}`);
+      return false;
+    }
+    return true;
+  });
+  const classified = classifyFindings(validated, diff);
+  const tier1 = classified.filter((f) => f.tier === 1);
+  const tier2 = classified.filter((f) => f.tier === 2);
+  const tier3 = classified.filter((f) => f.tier === 3);
+
+  for (const f of tier2) {
+    console.warn(`WARN: ${f.path}:${f.line} demoted to file-level`);
+  }
+  for (const f of tier3) {
+    console.warn(`WARN: ${f.path}:${f.line} demoted to review body`);
+  }
+  return { tier1, tier2, tier3 };
+}