@mechanai/deepreview 2.12.0 → 2.13.0

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

@@ -24,6 +24,21 @@ Read all provided files.
 
 When `prior-review.md` is provided, emit findings from **both** the synthesis and the prior review, but deduplicate: if a prior-review finding and a synthesis finding refer to the same file path and line (or overlapping line range) AND describe the same issue, keep only the synthesis version (it may have updated wording). When in doubt, keep both — false duplicates are worse than a missing dedup.
 
+## Replying to existing threads
+
+When a finding overlaps with an existing thread from the prior review (identified by its `[thread: ID]` tag), decide:
+
+1. Does your finding add substantive value beyond what the thread already says?
+   - A concrete suggestion block the thread lacks: reply
+   - Additional analysis or a related issue the original missed: reply
+   - Just restating what's already there: omit the finding entirely
+
+2. If replying, use `replyTo: <thread ID>` in the frontmatter instead of `startLine`. The body should be written as a reply — it appears below existing comments in the thread. Don't repeat context the reader can see above.
+
+3. If the thread is marked `[resolved]` or `[outdated]` in the prior review, do NOT reply to it. Post as a new finding instead (or omit if redundant).
+
+4. `replyTo` and `startLine` are mutually exclusive. When using `replyTo`, omit `startLine`.
+
 ## Prior-review-only mode
 
 This mode activates when the orchestrator provides `prior-review.md` but no `synthesis.md` (synthesis failed or was skipped). In this mode:
@@ -74,6 +89,17 @@ line: <line number>
 <markdown body of the comment>
 ```
 
+If replying to an existing thread:
+
+```
+---
+path: <file path>
+line: <line number>
+replyTo: <thread ID from prior review>
+---
+<markdown body of the reply>
+```
+
 ## Content rules
 
 - One finding per document. Never bundle multiple issues.

package/package.json

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

package/src/batch-retry.ts

@@ -0,0 +1,62 @@
+import { isRateLimitError } from "./review-helpers.ts";
+
+const BATCH_CONCURRENCY = 2;
+const BATCH_DELAY_MS = 1000;
+const RATE_LIMIT_DELAY_MS = 60_000;
+const RATE_LIMIT_JITTER_MS = 10_000;
+const MAX_RATE_LIMIT_RETRIES = 2;
+
+export interface BatchOptions {
+  concurrency?: number;
+  delayMs?: number;
+}
+
+/** Process items in batches with concurrency and inter-batch delay. */
+export async function mapBatch<T, R>(
+  items: T[],
+  fn: (item: T) => Promise<R>,
+  opts: BatchOptions = {},
+): Promise<R[]> {
+  const concurrency = opts.concurrency ?? BATCH_CONCURRENCY;
+  const delayMs = opts.delayMs ?? BATCH_DELAY_MS;
+  const results: R[] = [];
+  for (let i = 0; i < items.length; i += concurrency) {
+    if (i > 0) await Bun.sleep(delayMs);
+    results.push(...(await Promise.all(items.slice(i, i + concurrency).map(fn))));
+  }
+  return results;
+}
+
+/** Retry an async operation with rate-limit-aware backoff. Returns true on success. */
+export async function withRateLimitRetry(
+  fn: () => Promise<void>,
+  label: string,
+  maxRetries: number = MAX_RATE_LIMIT_RETRIES,
+): Promise<boolean> {
+  try {
+    await fn();
+    return true;
+  } catch (err: unknown) {
+    if (!isRateLimitError(err)) {
+      const message = err instanceof Error ? err.message : String(err);
+      console.error(`FAIL: ${label} — ${message}`);
+      return false;
+    }
+    for (let attempt = 0; attempt < maxRetries; attempt++) {
+      console.warn(`Rate limited on ${label}. Waiting 60s (retry ${attempt + 1}/${maxRetries})...`);
+      await Bun.sleep(RATE_LIMIT_DELAY_MS + Math.floor(Math.random() * RATE_LIMIT_JITTER_MS));
+      try {
+        await fn();
+        return true;
+      } catch (retryErr: unknown) {
+        if (!isRateLimitError(retryErr)) {
+          const message = retryErr instanceof Error ? retryErr.message : String(retryErr);
+          console.error(`FAIL: ${label} — ${message}`);
+          return false;
+        }
+      }
+    }
+    console.error(`FAIL: ${label} — rate limited after retries`);
+    return false;
+  }
+}

package/src/build-prior-review-fetch.ts

@@ -82,6 +82,7 @@ function classifyAuthorType(
 /** Map raw GraphQL thread nodes to domain ReviewThread objects with author classification. */
 export function mapGraphQLThreads(nodes: GQLThreadNode[]): ReviewThread[] {
   return nodes.map((node) => ({
+    id: node.id,
     path: node.path,
     startLine: node.startLine,
     line: node.line,

package/src/build-prior-review.test.ts

@@ -14,9 +14,10 @@ function makeThread(
   path: string,
   line: number,
   comments: { login: string; body: string }[],
-  opts?: { startLine?: number; isResolved?: boolean; isOutdated?: boolean },
+  opts?: { id?: string; startLine?: number; isResolved?: boolean; isOutdated?: boolean },
 ): ReviewThread {
   return {
+    id: opts?.id ?? `PRT_${path}_${line}`,
     path,
     startLine: opts?.startLine ?? null,
     line,
@@ -54,10 +55,12 @@ describe("formatPriorReview: sections", () => {
   });
 });
 
+// oxlint-disable-next-line max-lines-per-function -- Why: two inline thread fixtures with full comment arrays are required to test multi-thread grouping and line-range formatting; extracting them would obscure the test intent
 describe("formatPriorReview: thread formatting", () => {
   it("formats threads grouped by file with line numbers", () => {
     const threads: ReviewThread[] = [
       {
+        id: "PRT_1",
         path: "src/foo.ts",
         startLine: 10,
         line: 15,
@@ -79,6 +82,7 @@ describe("formatPriorReview: thread formatting", () => {
         ],
       },
       {
+        id: "PRT_2",
         path: "src/foo.ts",
         startLine: null,
         line: 42,
@@ -248,6 +252,31 @@ describe("mapGraphQLThreads", () => {
     assert.equal(result[0].comments[0].authorType, "bot");
   });
 
+  it("preserves thread id from GraphQL node", () => {
+    const nodes = [
+      {
+        id: "PRT_kwDOABC123",
+        path: "src/foo.ts",
+        startLine: null,
+        line: 10,
+        isResolved: false,
+        isOutdated: false,
+        comments: {
+          pageInfo: { hasNextPage: false, endCursor: null },
+          nodes: [
+            {
+              author: { login: "alice", __typename: "User" },
+              body: "Fix this",
+              createdAt: "2026-01-01T00:00:00Z",
+            },
+          ],
+        },
+      },
+    ];
+    const result = mapGraphQLThreads(nodes);
+    assert.equal(result[0].id, "PRT_kwDOABC123");
+  });
+
   it("detects deepreview by finding ID HTML comment in body", () => {
     const nodes = [
       {
@@ -279,6 +308,7 @@ describe("buildPriorReviewContent: basic behavior", () => {
   it("keeps all content when under budget", () => {
     const threads: ReviewThread[] = [
       {
+        id: "PRT_basic",
         path: "a.ts",
         startLine: null,
         line: 1,
@@ -316,6 +346,7 @@ describe("buildPriorReview (integration shape)", () => {
 describe("buildPriorReviewContent: truncation", () => {
   it("drops oldest threads first when over budget", () => {
     const oldThread: ReviewThread = {
+      id: "PRT_old",
       path: "old.ts",
       startLine: null,
       line: 1,
@@ -331,6 +362,7 @@ describe("buildPriorReviewContent: truncation", () => {
       ],
     };
     const newThread: ReviewThread = {
+      id: "PRT_new",
       path: "new.ts",
       startLine: null,
       line: 1,
@@ -354,6 +386,7 @@ describe("buildPriorReviewContent: truncation", () => {
 
   it("preserves PR description and manual content even when threads are large", () => {
     const bigThread: ReviewThread = {
+      id: "PRT_big",
       path: "big.ts",
       startLine: null,
       line: 1,
@@ -383,6 +416,7 @@ describe("formatPriorReview: formatCommentBody paths", () => {
   it("renders multi-line body as indented blockquote", () => {
     const threads: ReviewThread[] = [
       {
+        id: "PRT_multi",
         path: "src/multi.ts",
         startLine: null,
         line: 1,
@@ -409,6 +443,7 @@ describe("formatPriorReview: formatCommentBody paths", () => {
   it("renders single-line body in quotes", () => {
     const threads: ReviewThread[] = [
       {
+        id: "PRT_single",
         path: "src/single.ts",
         startLine: null,
         line: 1,
@@ -433,6 +468,7 @@ describe("formatPriorReview: formatLineRef paths", () => {
   it("renders startLine only when line is null", () => {
     const threads: ReviewThread[] = [
       {
+        id: "PRT_start_only",
         path: "src/start-only.ts",
         startLine: 42,
         line: null,
@@ -457,6 +493,7 @@ describe("formatPriorReview: formatLineRef paths", () => {
   it("renders file-level when both startLine and line are null", () => {
     const threads: ReviewThread[] = [
       {
+        id: "PRT_file_level",
         path: "src/file-level.ts",
         startLine: null,
         line: null,
@@ -481,6 +518,7 @@ describe("formatPriorReview: formatSourceTag paths", () => {
   it("renders deepreview author type in source tag", () => {
     const threads: ReviewThread[] = [
       {
+        id: "PRT_dr",
         path: "src/dr.ts",
         startLine: null,
         line: 5,
@@ -503,6 +541,7 @@ describe("formatPriorReview: formatSourceTag paths", () => {
   it("renders both resolved and outdated simultaneously", () => {
     const threads: ReviewThread[] = [
       {
+        id: "PRT_both",
         path: "src/both.ts",
         startLine: null,
         line: 10,
@@ -523,10 +562,29 @@ describe("formatPriorReview: formatSourceTag paths", () => {
   });
 });
 
+describe("formatPriorReview: thread ID tags", () => {
+  it("includes thread ID tag in formatted output", () => {
+    const thread = makeThread("src/foo.ts", 10, [{ login: "alice", body: "Fix this" }], {
+      id: "PRT_kwDOABC123",
+    });
+    const result = formatPriorReview("", [thread], null);
+    assert.ok(result.includes("[thread: PRT_kwDOABC123]"));
+  });
+
+  it("places thread ID after source tag", () => {
+    const thread = makeThread("src/foo.ts", 10, [{ login: "alice", body: "Fix this" }], {
+      id: "PRT_kwDOXYZ789",
+    });
+    const result = formatPriorReview("", [thread], null);
+    assert.match(result, /\[source: [^\]]+\] \[thread: PRT_kwDOXYZ789\]/u);
+  });
+});
+
 describe("formatPriorReview: formatThread empty comments", () => {
   it("returns empty output for thread with no comments", () => {
     const threads: ReviewThread[] = [
       {
+        id: "PRT_empty",
         path: "src/empty.ts",
         startLine: null,
         line: 1,
@@ -585,6 +643,7 @@ describe("buildPriorReviewContent: edge cases", () => {
     const hugeThreadBody = "z".repeat(40_000);
     const threads: ReviewThread[] = [
       {
+        id: "PRT_big1",
         path: "big1.ts",
         startLine: null,
         line: 1,
@@ -600,6 +659,7 @@ describe("buildPriorReviewContent: edge cases", () => {
         ],
       },
       {
+        id: "PRT_big2",
         path: "big2.ts",
         startLine: null,
         line: 1,

package/src/build-prior-review.ts

@@ -15,6 +15,7 @@ export interface ThreadComment {
 
 /** A review thread attached to a file path and line range. */
 export interface ReviewThread {
+  id: string;
   path: string;
   startLine: number | null;
   line: number | null;
@@ -54,7 +55,8 @@ function formatThread(thread: ReviewThread): string {
   const lines: string[] = [];
   const lineRef = formatLineRef(thread.startLine, thread.line);
   const tag = formatSourceTag(first, thread);
-  lines.push(`- ${lineRef} ${tag}: ${formatCommentBody(first.body, "  ")}`);
+  const threadTag = `[thread: ${thread.id}]`;
+  lines.push(`- ${lineRef} ${tag} ${threadTag}: ${formatCommentBody(first.body, "  ")}`);
   for (const reply of replies) {
     lines.push(`  - @${reply.authorLogin} replied: ${formatCommentBody(reply.body, "    ")}`);
   }

package/src/diff-classifier.ts

@@ -5,6 +5,7 @@ export interface Finding {
   line: number;
   startLine?: number;
   body: string;
+  replyTo?: string;
 }
 
 export interface ClassifiedFinding extends Finding {
@@ -13,6 +14,11 @@ export interface ClassifiedFinding extends Finding {
   renderedBody?: string;
 }
 
+/** A classified finding that targets an existing thread for reply. */
+export interface ReplyFinding extends ClassifiedFinding {
+  replyTo: string;
+}
+
 interface FileHunks {
   hunks: { newStart: number; newLines: number }[];
 }

package/src/load-pr.test.ts

@@ -0,0 +1,75 @@
+import { describe, it } from "bun:test";
+import assert from "node:assert/strict";
+import { writeFile, mkdir, rm, symlink } from "node:fs/promises";
+import { join } from "node:path";
+import { loadAndValidatePr } from "./load-pr.ts";
+
+const TMP_DIR = "/tmp/opencode/load-pr-test";
+
+describe("loadAndValidatePr — path validation", () => {
+  it("rejects paths with null bytes", async () => {
+    await assert.rejects(
+      loadAndValidatePr("threads\x00.md", 1, undefined, TMP_DIR),
+      /Invalid threadsPath/u,
+    );
+  });
+
+  it("rejects absolute paths", async () => {
+    await assert.rejects(
+      loadAndValidatePr("/etc/passwd", 1, undefined, TMP_DIR),
+      /Invalid threadsPath/u,
+    );
+  });
+
+  it("rejects paths with directory traversal", async () => {
+    await assert.rejects(
+      loadAndValidatePr("../../../etc/passwd", 1, undefined, TMP_DIR),
+      /Invalid threadsPath/u,
+    );
+  });
+
+  it("rejects empty path", async () => {
+    await assert.rejects(loadAndValidatePr("", 1, undefined, TMP_DIR), /Invalid threadsPath/u);
+  });
+});
+
+describe("loadAndValidatePr — file system", () => {
+  it("throws when file does not exist", async () => {
+    await mkdir(TMP_DIR, { recursive: true });
+    await assert.rejects(
+      loadAndValidatePr("nonexistent.md", 1, undefined, TMP_DIR),
+      /Threads file not found/u,
+    );
+  });
+
+  it("throws when resolved path escapes working directory via symlink", async () => {
+    await mkdir(TMP_DIR, { recursive: true });
+    const linkPath = join(TMP_DIR, "escape.md");
+    try {
+      await rm(linkPath);
+    } catch {
+      // ignore if not present
+    }
+    try {
+      await symlink("/etc/hostname", linkPath);
+    } catch {
+      // symlink creation may fail on some systems — skip test
+      return;
+    }
+    try {
+      await assert.rejects(
+        loadAndValidatePr("escape.md", 1, undefined, TMP_DIR),
+        /escapes working directory/u,
+      );
+    } finally {
+      await rm(linkPath);
+    }
+  });
+
+  it("returns null when threads file has no findings", async () => {
+    await mkdir(TMP_DIR, { recursive: true });
+    await writeFile(join(TMP_DIR, "empty.md"), "");
+    const result = await loadAndValidatePr("empty.md", 1, undefined, TMP_DIR);
+    assert.equal(result, null);
+  });
+});

package/src/load-pr.ts

@@ -0,0 +1,44 @@
+import { readFile, realpath } from "node:fs/promises";
+import { resolve } from "node:path";
+import { parseThreads } from "./parse-threads.ts";
+import { type Finding } from "./diff-classifier.ts";
+import { type PrInfo, getPrInfo } from "./graphql.ts";
+import { isValidPath } from "./review-helpers.ts";
+
+/** Load and parse a threads file, validate the PR is open, and verify the head SHA matches. */
+export async function loadAndValidatePr(
+  threadsPath: string,
+  prNumber: number,
+  expectedSha: string | undefined,
+  cwd: string | undefined,
+): Promise<{ findings: Finding[]; prInfo: PrInfo; summary?: string } | null> {
+  if (!isValidPath(threadsPath)) {
+    throw new Error(`Invalid threadsPath: ${threadsPath}`);
+  }
+  const base = await realpath(resolve(cwd ?? process.cwd()));
+  const candidatePath = resolve(base, threadsPath);
+  let resolved: string;
+  try {
+    resolved = await realpath(candidatePath);
+  } catch {
+    throw new Error(`Threads file not found: ${candidatePath}`);
+  }
+  if (!resolved.startsWith(base + "/") && resolved !== base) {
+    throw new Error(`threadsPath escapes working directory: ${threadsPath}`);
+  }
+  const content = await readFile(resolved, "utf8");
+  const { findings, summary } = parseThreads(content);
+  if (findings.length === 0 && (summary === undefined || summary === "")) return null;
+
+  const prInfo = await getPrInfo(prNumber, { cwd });
+  if (prInfo.state !== "OPEN") {
+    throw new Error(`PR is ${prInfo.state}. Aborting.`);
+  }
+
+  const resolvedSha = expectedSha ?? process.env.PR_HEAD_SHA;
+  if (resolvedSha !== undefined && resolvedSha !== "" && resolvedSha !== prInfo.headOid) {
+    throw new Error(`ABORT: PR head moved (expected ${resolvedSha}, got ${prInfo.headOid}).`);
+  }
+
+  return { findings, prInfo, summary };
+}

package/src/parse-threads.test.ts

@@ -125,3 +125,44 @@ describe("parseThreads findings", () => {
     assert.equal(result.findings.length, 0);
   });
 });
+
+describe("parseThreads replyTo", () => {
+  it("extracts replyTo from frontmatter", () => {
+    const input = [
+      "---",
+      "path: src/foo.ts",
+      "line: 42",
+      "replyTo: PRT_kwDOABC123",
+      "---",
+      "This adds a suggestion.",
+    ].join("\n");
+
+    const result = parseThreads(input);
+    assert.equal(result.findings.length, 1);
+    assert.equal(result.findings[0].replyTo, "PRT_kwDOABC123");
+    assert.equal(result.findings[0].startLine, undefined);
+  });
+
+  it("returns undefined replyTo when not present", () => {
+    const input = ["---", "path: src/foo.ts", "line: 42", "---", "Normal finding."].join("\n");
+
+    const result = parseThreads(input);
+    assert.equal(result.findings[0].replyTo, undefined);
+  });
+
+  it("replyTo and startLine are mutually exclusive — replyTo wins", () => {
+    const input = [
+      "---",
+      "path: src/foo.ts",
+      "startLine: 40",
+      "line: 45",
+      "replyTo: PRT_kwDOABC123",
+      "---",
+      "Reply body.",
+    ].join("\n");
+
+    const result = parseThreads(input);
+    assert.equal(result.findings[0].replyTo, "PRT_kwDOABC123");
+    assert.equal(result.findings[0].startLine, undefined);
+  });
+});

package/src/parse-threads.ts

@@ -21,6 +21,36 @@ const safeYamlEngine = (s: string): Record<string, unknown> => {
 };
 const matterOptions = { engines: { yaml: safeYamlEngine } };
 
+/** Build a Finding from parsed frontmatter data and body content. */
+function buildFinding(
+  data: Record<string, unknown>,
+  path: string,
+  lineNum: number,
+  body: string,
+): Finding {
+  const rawStartLine: unknown = data.startLine;
+  const startLineNum =
+    rawStartLine !== null && rawStartLine !== undefined ? Number(rawStartLine) : undefined;
+
+  const rawReplyTo: unknown = data.replyTo;
+  const replyTo = typeof rawReplyTo === "string" && rawReplyTo.length > 0 ? rawReplyTo : undefined;
+
+  // Replies don't use startLine; only set it when present and valid
+  const validStartLine =
+    replyTo === undefined &&
+    startLineNum !== undefined &&
+    startLineNum > 0 &&
+    Number.isFinite(startLineNum);
+
+  return {
+    path,
+    line: lineNum,
+    startLine: validStartLine ? startLineNum : undefined,
+    body,
+    replyTo,
+  };
+}
+
 /**
  * Parse a threads.md file into findings and an optional summary.
  * The file uses --- separators between documents, each with YAML frontmatter.
@@ -60,18 +90,7 @@ function parseThreads(content: string): ParsedThreads {
       continue;
     }
 
-    const rawStartLine: unknown = data.startLine;
-    const startLineNum =
-      rawStartLine !== null && rawStartLine !== undefined ? Number(rawStartLine) : undefined;
-    findings.push({
-      path,
-      line: lineNum,
-      startLine:
-        startLineNum !== undefined && startLineNum > 0 && Number.isFinite(startLineNum)
-          ? startLineNum
-          : undefined,
-      body: parsed.content.trim(),
-    });
+    findings.push(buildFinding(data, path, lineNum, parsed.content.trim()));
   }
 
   return { findings, summary };

package/src/post-review.test.ts

@@ -1,7 +1,7 @@
 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 { classifyFindings, type ReplyFinding } from "./diff-classifier.ts";
 import { buildReviewBody } from "./review-helpers.ts";
 
 describe("buildReviewBody", () => {
@@ -33,6 +33,59 @@ describe("buildReviewBody", () => {
   });
 });
 
+describe("postReview reply routing", () => {
+  it("classifies findings with replyTo separately from new findings", () => {
+    const threadsContent = [
+      "---",
+      "path: src/foo.ts",
+      "line: 10",
+      "replyTo: PRT_kwDOABC123",
+      "---",
+      "Reply body here.",
+      "---",
+      "path: src/bar.ts",
+      "line: 20",
+      "---",
+      "New finding body.",
+    ].join("\n");
+
+    const { findings } = parseThreads(threadsContent);
+    const replyFindings = findings.filter((f) => f.replyTo !== undefined);
+    const newFindings = findings.filter((f) => f.replyTo === undefined);
+
+    assert.equal(replyFindings.length, 1);
+    assert.equal(replyFindings[0].replyTo, "PRT_kwDOABC123");
+    assert.equal(newFindings.length, 1);
+    assert.equal(newFindings[0].path, "src/bar.ts");
+  });
+});
+
+describe("postReview dry-run with replyTo", () => {
+  it("includes reply findings in dry-run count", () => {
+    const threadsContent = [
+      "---",
+      "path: src/foo.ts",
+      "line: 10",
+      "replyTo: PRT_kwDOABC123",
+      "---",
+      "Reply finding.",
+      "---",
+      "path: src/bar.ts",
+      "startLine: 5",
+      "line: 10",
+      "---",
+      "New finding.",
+    ].join("\n");
+
+    const { findings } = parseThreads(threadsContent);
+    assert.equal(findings.length, 2);
+    assert.equal(findings[0].replyTo, "PRT_kwDOABC123");
+    assert.equal(findings[0].startLine, undefined);
+    assert.equal(findings[1].replyTo, undefined);
+    assert.equal(findings[1].startLine, 5);
+  });
+});
+
 describe("integration: parse → classify", () => {
   const threadsContent = [
     "---",
@@ -80,3 +133,33 @@ describe("integration: parse → classify", () => {
     assert.equal(classified[2].tier, 3);
   });
 });
+
+describe("ReplyFinding type narrowing", () => {
+  it("filter produces ReplyFinding[] when checking replyTo", () => {
+    const { findings } = parseThreads(
+      [
+        "---",
+        "path: src/foo.ts",
+        "line: 10",
+        "replyTo: PRT_kwDOABC123",
+        "---",
+        "Reply body.",
+        "---",
+        "path: src/bar.ts",
+        "line: 20",
+        "---",
+        "New body.",
+      ].join("\n"),
+    );
+
+    const replies: ReplyFinding[] = findings
+      .filter((f): f is ReplyFinding => f.replyTo !== undefined)
+      .map((f) => ({ ...f, tier: 1 as const }));
+
+    assert.equal(replies.length, 1);
+    assert.equal(replies[0].replyTo, "PRT_kwDOABC123");
+    // Type check: replyTo is string (not string | undefined)
+    const threadId: string = replies[0].replyTo;
+    assert.equal(threadId, "PRT_kwDOABC123");
+  });
+});

package/src/post-review.ts

@@ -1,8 +1,5 @@
-import { readFile, realpath } from "node:fs/promises";
-import { resolve } from "node:path";
-import { parseThreads } from "./parse-threads.ts";
-import { type Finding, type ClassifiedFinding } from "./diff-classifier.ts";
-import { type PrInfo, getPrInfo, execFileAsync } from "./graphql.ts";
+import { type ClassifiedFinding, type ReplyFinding } from "./diff-classifier.ts";
+import { type PrInfo, execFileAsync } from "./graphql.ts";
 import {
   type PendingReview,
   findPendingReview,
@@ -11,16 +8,17 @@ import {
   addLineThread,
   addFileThread,
   updateReviewComment,
+  replyToThread,
 } from "./review-api.ts";
 import {
-  isValidPath,
-  isRateLimitError,
   findingId,
   embedFindingId,
   extractFindingId,
   buildReviewBody,
   classifyAndLog,
 } from "./review-helpers.ts";
+import { mapBatch, withRateLimitRetry } from "./batch-retry.ts";
+import { loadAndValidatePr } from "./load-pr.ts";
 
 export interface PostReviewOptions {
   threadsPath: string;
@@ -59,17 +57,10 @@ async function updateExistingThreads(
     }
   }
 
-  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.renderedBody ?? finding.body, id);
-        await updateReviewComment(commentId, body);
-      }),
-    );
-  }
+  await mapBatch(toUpdate, async ({ finding, commentId, id }) => {
+    const body = embedFindingId(finding.renderedBody ?? finding.body, id);
+    await updateReviewComment(commentId, body);
+  });
 
   console.log(`Updated ${toUpdate.length} existing threads.`);
   return new Set(toUpdate.map(({ id }) => id));
@@ -92,71 +83,65 @@ async function postWithRetry(
   finding: ClassifiedFinding,
   body: string,
 ): Promise<boolean> {
-  try {
-    await postThread(reviewId, finding, body);
-    return true;
-  } catch (err: unknown) {
-    if (!isRateLimitError(err)) {
-      const message = err instanceof Error ? err.message : String(err);
-      console.error(`FAIL: ${finding.path}:${finding.line} — ${message}`);
-      return false;
-    }
-    for (let attempt = 0; attempt < 2; attempt++) {
-      console.warn(
-        `Rate limited on ${finding.path}:${finding.line}. Waiting 60s (retry ${attempt + 1}/2)...`,
-      );
-      await Bun.sleep(60_000 + Math.floor(Math.random() * 10_000));
-      try {
-        await postThread(reviewId, finding, body);
-        return true;
-      } catch (retryErr: unknown) {
-        if (!isRateLimitError(retryErr)) {
-          const message = retryErr instanceof Error ? retryErr.message : String(retryErr);
-          console.error(`FAIL: ${finding.path}:${finding.line} — ${message}`);
-          return false;
-        }
-      }
-    }
-    console.error(`FAIL: ${finding.path}:${finding.line} — rate limited after retries`);
-    return false;
-  }
+  return withRateLimitRetry(
+    async () => postThread(reviewId, finding, body),
+    `${finding.path}:${finding.line}`,
+  );
 }
 
 async function postInlineThreads(
   reviewId: string,
   inlineFindings: ClassifiedFinding[],
   updatedIds: Set<string>,
+  maxThreads: number = MAX_INLINE_FINDINGS,
 ): Promise<string[]> {
-  const CONCURRENCY = 2;
-  const failedFindings: string[] = [];
   const pending = inlineFindings.filter(
     (f) => !updatedIds.has(findingId(f.path, f.startLine, f.line, f.body)),
   );
 
-  if (pending.length > MAX_INLINE_FINDINGS) {
+  if (pending.length > maxThreads) {
     console.warn(
-      `WARN: ${pending.length} inline findings exceed limit of ${MAX_INLINE_FINDINGS}. Truncating.`,
+      `WARN: ${pending.length} inline findings exceed limit of ${maxThreads}. Truncating.`,
     );
   }
-  const capped = pending.slice(0, MAX_INLINE_FINDINGS);
+  const capped = pending.slice(0, maxThreads);
 
-  for (let i = 0; i < capped.length; i += CONCURRENCY) {
-    if (i > 0) await Bun.sleep(1000);
-    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);
-        // Body rendered by GitHub's Markdown sanitizer; no escaping needed here
-        const body = embedFindingId(f.renderedBody ?? f.body, id);
-        const ok = await postWithRetry(reviewId, f, body);
-        return ok ? null : id;
-      }),
+  const results = await mapBatch(capped, async (f) => {
+    const id = findingId(f.path, f.startLine, f.line, f.body);
+    const body = embedFindingId(f.renderedBody ?? f.body, id);
+    const ok = await postWithRetry(reviewId, f, body);
+    return ok ? null : id;
+  });
+  return results.filter((id): id is string => id !== null);
+}
+
+async function postReplyThreads(
+  replyFindings: ReplyFinding[],
+  reviewId: string,
+  inlineBudgetRemaining: number,
+): Promise<{ failedIds: string[]; fallbackCount: number }> {
+  let fallbackCount = 0;
+  const results = await mapBatch(replyFindings, async (f) => {
+    const id = findingId(f.path, f.startLine, f.line, f.body);
+    const body = embedFindingId(f.renderedBody ?? f.body, id);
+    const replied = await withRateLimitRetry(
+      async () => replyToThread(f.replyTo, body),
+      `reply to ${f.replyTo}`,
     );
-    for (const id of results) {
-      if (id !== null) failedFindings.push(id);
+    if (replied) return null;
+    // Fallback: post as new thread, subject to inline cap
+    if (fallbackCount >= inlineBudgetRemaining) {
+      console.warn(
+        `WARN: Reply to thread ${f.replyTo} failed. Inline cap reached — skipping fallback.`,
+      );
+      return id;
     }
-  }
-  return failedFindings;
+    console.warn(`WARN: Reply to thread ${f.replyTo} failed. Falling back to new thread.`);
+    fallbackCount++;
+    const ok = await postWithRetry(reviewId, f, body);
+    return ok ? null : id;
+  });
+  return { failedIds: results.filter((id): id is string => id !== null), fallbackCount };
 }
 
 async function ensureReview(
@@ -188,44 +173,32 @@ async function ensureReview(
   return { reviewId, updatedFindings: new Set() };
 }
 
-async function loadAndValidatePr(
-  threadsPath: string,
-  prNumber: number,
-  expectedSha: string | undefined,
-  cwd: string | undefined,
-): 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;
-  try {
-    resolved = await realpath(candidatePath);
-  } catch {
-    throw new Error(`Threads file not found: ${candidatePath}`);
-  }
-  if (!resolved.startsWith(base + "/") && resolved !== base) {
-    throw new Error(`threadsPath escapes working directory: ${threadsPath}`);
-  }
-  const content = await readFile(resolved, "utf8");
-  const { findings, summary } = parseThreads(content);
-  if (findings.length === 0 && (summary === undefined || summary === "")) return null;
-
-  const prInfo = await getPrInfo(prNumber, { cwd });
-  if (prInfo.state !== "OPEN") {
-    throw new Error(`PR is ${prInfo.state}. Aborting.`);
-  }
-
-  const resolvedSha = expectedSha ?? process.env.PR_HEAD_SHA;
-  if (resolvedSha !== undefined && resolvedSha !== "" && resolvedSha !== prInfo.headOid) {
-    throw new Error(`ABORT: PR head moved (expected ${resolvedSha}, got ${prInfo.headOid}).`);
-  }
+interface StatusCounts {
+  posted: number;
+  total: number;
+  replies: number;
+  upToDate: number;
+  skipped: number;
+  failed: number;
+  truncated: number;
+  tier3Count: number;
+}
 
-  return { findings, prInfo, summary };
+function formatStatusSummary(counts: StatusCounts): string {
+  const parts: string[] = [];
+  if (counts.replies > 0) parts.push(`${counts.replies} replies`);
+  if (counts.upToDate > 0) parts.push(`${counts.upToDate} up-to-date`);
+  if (counts.skipped > 0) parts.push(`${counts.skipped} skipped`);
+  if (counts.failed > 0) parts.push(`${counts.failed} failed`);
+  if (counts.truncated > 0) parts.push(`${counts.truncated} truncated`);
+  const detail = parts.length > 0 ? ` (${parts.join(", ")})` : "";
+  return (
+    `Posted ${counts.posted}/${counts.total} inline threads${detail}. ` +
+    `${counts.tier3Count} findings in review body.`
+  );
 }
 
+// oxlint-disable-next-line max-lines-per-function -- Why: orchestration function that coordinates reply/new posting and computes stats; splitting further would fragment the logic
 async function postFindings(
   tier1: ClassifiedFinding[],
   tier2: ClassifiedFinding[],
@@ -247,26 +220,57 @@ async function postFindings(
   );
 
   const skipSet = new Set(skipIds);
-  const inlineFindings = [...tier1, ...tier2].filter((f) => {
+  const allInline = [...tier1, ...tier2].filter((f) => {
     const id = findingId(f.path, f.startLine, f.line, f.body);
     return !skipSet.has(id);
   });
 
-  const failedIds = await postInlineThreads(reviewId, inlineFindings, updatedFindings);
-  const skipped = inlineFindings.filter((f) =>
+  // Split into reply findings and new findings
+  const replyFindings = allInline.filter(
+    (f): f is ReplyFinding =>
+      f.replyTo !== undefined &&
+      !updatedFindings.has(findingId(f.path, f.startLine, f.line, f.body)),
+  );
+  const newFindings = allInline.filter((f) => f.replyTo === undefined);
+
+  // Post replies first (fallbacks count against inline cap)
+  const inlineBudget = MAX_INLINE_FINDINGS;
+  const { failedIds: replyFailedIds, fallbackCount } = await postReplyThreads(
+    replyFindings,
+    reviewId,
+    inlineBudget,
+  );
+
+  // Post new threads with remaining budget after reply fallbacks
+  const newFailedIds = await postInlineThreads(
+    reviewId,
+    newFindings,
+    updatedFindings,
+    inlineBudget - fallbackCount,
+  );
+
+  const failedIds = [...replyFailedIds, ...newFailedIds];
+  const skipped = newFindings.filter((f) =>
     updatedFindings.has(findingId(f.path, f.startLine, f.line, f.body)),
   ).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 pendingNew = newFindings.length - skipped;
+  const postedNew = Math.min(pendingNew, inlineBudget - fallbackCount) - newFailedIds.length;
+  const postedReplies = replyFindings.length - replyFailedIds.length;
   const totalFindings = [...tier1, ...tier2].length;
-  const skippedByUser = totalFindings - inlineFindings.length;
-  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.`;
+  const truncated = Math.max(0, pendingNew - (inlineBudget - fallbackCount));
 
-  console.log(statusSummary);
+  const statusSummary = formatStatusSummary({
+    posted: postedNew + postedReplies,
+    total: totalFindings,
+    replies: postedReplies,
+    upToDate: skipped,
+    skipped: totalFindings - allInline.length,
+    failed: failedIds.length,
+    truncated,
+    tier3Count: tier3.length,
+  });
 
+  console.log(statusSummary);
   return { summary: statusSummary, failed: failedIds };
 }
 
@@ -291,8 +295,15 @@ export async function postReview(opts: PostReviewOptions): Promise<PostReviewRes
   const { tier1, tier2, tier3 } = classifyAndLog(findings, diff);
 
   if (dryRun) {
+    const replyCount = findings.filter((f) => f.replyTo !== undefined).length;
+    const parts = [
+      `${tier1.length} line-level`,
+      `${tier2.length} file-level`,
+      `${tier3.length} review-body`,
+    ];
+    if (replyCount > 0) parts.push(`${replyCount} replies`);
     return {
-      summary: `Dry run: ${tier1.length} line-level, ${tier2.length} file-level, ${tier3.length} review-body findings.`,
+      summary: `Dry run: ${parts.join(", ")} findings.`,
       failed: [],
     };
   }

package/src/review-api.ts

@@ -259,3 +259,19 @@ export async function updateReviewComment(commentId: string, body: string): Prom
     { input: { pullRequestReviewCommentId: commentId, body } },
   );
 }
+
+/** Post a reply comment on an existing review thread. */
+export async function replyToThread(threadId: string, body: string): Promise<void> {
+  await graphql(
+    `
+      mutation ($input: AddPullRequestReviewThreadReplyInput!) {
+        addPullRequestReviewThreadReply(input: $input) {
+          comment {
+            id
+          }
+        }
+      }
+    `,
+    { input: { pullRequestReviewThreadId: threadId, body } },
+  );
+}