@mechanai/deepreview 2.12.0 → 2.14.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/.opencode/agents/deepreview-synthesizer.md

@@ -21,6 +21,25 @@ If your prompt begins with a "Prior Findings" preamble, reviewers were instructe
 - **New findings only**: Your synthesis should contain only genuinely new findings. Do not re-synthesize issues from the prior review preamble.
 - **Regression detection**: If a reviewer flags something in a region that was previously fixed (per the preamble), treat it as a potential regression and flag it at warning severity or higher.
 
+## Novelty classification (iter2+ loop context only)
+
+If your prompt includes a "## Prior Findings for Novelty Classification" preamble, classify each
+finding in the current iteration:
+
+- **[NEW]**: mechanism not present in any prior finding (different file + different mechanism, or same file but genuinely different issue)
+- **[RECURRING]**: same file + same mechanism as a prior finding (even if reworded or at a slightly different line)
+- **[REGRESSION]**: found in code/spec modified by a previous iteration's applied fix AND the mechanism is directly related to the change made by the fix
+
+Classification process (after deduplication, before ranking):
+
+1. Check "Applied Fixes" — if the finding is in a region modified by a fix AND the mechanism is directly related to the change, classify as [REGRESSION].
+2. Check prior findings — if a finding matches an existing mechanism (same file + similar problem, even if differently worded), classify as [RECURRING].
+3. Everything else is [NEW].
+
+Prefix each finding entry with its classification tag: `[NEW]`, `[RECURRING]`, or `[REGRESSION]`.
+
+If no "Prior Findings for Novelty Classification" preamble is present, skip classification entirely — do not emit tags or the Iteration Metrics section.
+
 ## Process
 
 1. Read all validated review files
@@ -50,6 +69,12 @@ Write your synthesis to the output path provided. Use this structure:
 ## Overall Assessment
 [2-3 sentences: is this safe to merge, what is the biggest concern, overall quality]
 
+## Iteration Metrics
+Iteration N: X findings (Y new, Z recurring, W regression)
+- Convergence: [converging|deadlocked|diverging]
+
+[Omit this section entirely if no novelty classification was performed (iter1 or single-pass)]
+
 ## Critical Issues (must fix before merge)
 [All critical severity items, deduplicated and ranked by confidence]
 
@@ -74,6 +99,17 @@ The following doc/comment updates were identified (suggestion-level):
 
 Be concise. No preamble or filler.
 
+Convergence value for the Iteration Metrics section:
+
+- `converging`: 0 new findings, or fewer new findings than the prior iteration
+- `deadlocked`: 0 new findings but recurring findings persist
+- `diverging`: more new findings than the prior iteration
+
 ## Response contract
 
-After writing your synthesis file, your ONLY response must be the absolute path to your output file and a single stats line (e.g., "3 critical, 5 warnings, 2 suggestions"). Do not summarize findings. Do not include any other text.
+After writing your synthesis file, your ONLY response must be the absolute path to your output file and a single stats line. Format:
+
+- Without novelty classification: `"3 critical, 5 warnings, 2 suggestions"`
+- With novelty classification: `"3 critical, 5 warnings, 2 suggestions | 4 new, 5 recurring, 1 regression"`
+
+Do not summarize findings. Do not include any other text.

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

@@ -16,6 +16,7 @@ Parse "$ARGUMENTS" the same way as /deepreview:
 
 Set ITERATION=1
 Set PRIOR_CONTEXT="" (empty — built up across iterations; holds both design context and prior findings)
+Set CONSECUTIVE_ZERO_NEW=0 (tracks consecutive iterations with 0 new findings for deadlock detection)
 Set ALL_SESSION_DIRS=[] (list of all session directories used, in order)
 
 Determine REPO_ROOT — the main repository root (not a worktree root). Run:
@@ -53,10 +54,38 @@ Run the full deepreview pipeline (Stages 1-5 from the deepreview command):
 Record the stats from the synthesis return: count of critical, warning, and suggestion findings.
 
 STEP 3: CHECK EXIT CONDITION
-DEADLOCK CHECK (iter 2+ only):
-Compare this iteration's findings (file:line + issue title) against the previous iteration's findings. If two consecutive iterations produce the SAME findings, this indicates a deadlock — the applier is making changes that don't resolve the issue, or the reviewer keeps flagging the same thing.
 
-When deadlock is detected:
+Parse the stats line from the synthesizer. If it contains novelty metrics (the `| N new, N recurring, N regression` suffix), use NOVELTY MODE. Otherwise use LEGACY MODE.
+
+NOVELTY MODE (iter2+ only):
+
+A) CONVERGENCE EXIT: If `0 new AND 0 regression`:
+
+- Tell the user: "deepreview-loop converged after $ITERATION iteration(s). No new findings detected."
+- STOP.
+
+B) DEADLOCK (synthesizer signal): If `0 new AND N recurring (N > 0) AND 0 regression` for 2 consecutive iterations:
+
+- Tell the user: "Deadlock detected: $N recurring findings persist with no new issues found across 2 iterations:"
+- List the recurring findings from the synthesis.
+- Ask: "How would you like to resolve these? Options: skip these findings, provide guidance, or stop the loop."
+- Follow the user's instruction.
+
+C) DEADLOCK (orchestrator fallback): Compare this iteration's findings (file:line + issue title) against the previous iteration's findings. If they match BUT the synthesizer did NOT signal deadlock (i.e., it classified some as [NEW]):
+
+- Log warning: "Note: deterministic check found matching findings, but synthesizer classified them as new. Trusting synthesizer classification."
+- Do NOT trigger deadlock. Continue.
+
+D) Otherwise: proceed to STEP 4.
+
+Tracking: If `0 new`, increment CONSECUTIVE_ZERO_NEW. If `> 0 new`, reset CONSECUTIVE_ZERO_NEW to 0. Deadlock (B) triggers when CONSECUTIVE_ZERO_NEW >= 2 AND recurring > 0.
+
+LEGACY MODE (fallback when synthesizer omits novelty metrics):
+
+Warn the user: "Synthesizer did not return novelty metrics — falling back to legacy convergence detection."
+
+DEADLOCK CHECK (iter 2+ only):
+Compare this iteration's findings (file:line + issue title) against the previous iteration's findings. If two consecutive iterations produce the SAME findings:
 
 - Tell the user: "Deadlock detected: the following findings persist across iterations:"
 - List the repeated findings.
@@ -65,7 +94,7 @@ When deadlock is detected:
 
 If the synthesis/review has 0 critical AND 0 warning AND 0 suggestion findings:
 
-- Tell the user: "deepreviewloop complete after $ITERATION iteration(s). No findings remain."
+- Tell the user: "deepreview-loop complete after $ITERATION iteration(s). No findings remain."
 - STOP.
 
 STEP 4: APPLY ALL FIXES
@@ -249,8 +278,20 @@ Task 14 — Use the Task tool with subagent_type="deepreview-validator":
 Wait for all 7 to return.
 
 Stage 3 — DISPATCH SYNTHESIZER:
+Extract PRIOR_FINDINGS_SECTION from PRIOR_CONTEXT: include only the "## Prior Findings" and "## Applied Fixes" sections (not "Known Issue Locations" or "Covered Regions" — those are for reviewers only).
+
+If PRIOR_FINDINGS_SECTION is non-empty, include the novelty classification header in the synthesizer prompt. If empty (helper returned malformed context), omit the header — the synthesizer will operate in standard mode and the orchestrator MUST use LEGACY MODE for this iteration's exit check.
+
 Task 15 — Use the Task tool with subagent_type="deepreview-synthesizer":
-"Read the validated reviews at: $SESSION_DIR/validated-correctness.md, $SESSION_DIR/validated-security.md, $SESSION_DIR/validated-architecture.md, $SESSION_DIR/validated-docs.md, $SESSION_DIR/validated-compatibility.md, $SESSION_DIR/validated-performance.md, $SESSION_DIR/validated-maintainability.md (skip any that don't exist). Write the synthesis to $SESSION_DIR/synthesis.md."
+
+- If PRIOR_FINDINGS_SECTION is non-empty:
+  "## Prior Findings for Novelty Classification
+  $PRIOR_FINDINGS_SECTION
+
+  Read the validated reviews at: $SESSION_DIR/validated-correctness.md, $SESSION_DIR/validated-security.md, $SESSION_DIR/validated-architecture.md, $SESSION_DIR/validated-docs.md, $SESSION_DIR/validated-compatibility.md, $SESSION_DIR/validated-performance.md, $SESSION_DIR/validated-maintainability.md (skip any that don't exist). Write the synthesis to $SESSION_DIR/synthesis.md."
+
+- If PRIOR_FINDINGS_SECTION is empty:
+  "Read the validated reviews at: $SESSION_DIR/validated-correctness.md, $SESSION_DIR/validated-security.md, $SESSION_DIR/validated-architecture.md, $SESSION_DIR/validated-docs.md, $SESSION_DIR/validated-compatibility.md, $SESSION_DIR/validated-performance.md, $SESSION_DIR/validated-maintainability.md (skip any that don't exist). Write the synthesis to $SESSION_DIR/synthesis.md."
 
 Record the stats line.
 

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

@@ -12,6 +12,7 @@ STEP 1: DETERMINE INPUT
 - Set FILES="$ARGUMENTS"
 - Set ITERATION=1
 - Set PRIOR_CONTEXT="" (empty — built up across iterations; holds both design context and prior findings)
+- Set CONSECUTIVE_ZERO_NEW=0 (tracks consecutive iterations with 0 new findings for deadlock detection)
 - Set ALL_SESSION_DIRS=[] (list of all session directories used, in order)
 - Determine REPO_ROOT — the main repository root (not a worktree root). Run:
   `REPO_ROOT=$(realpath "$(git rev-parse --git-common-dir)" | sed 's|/\.git$||')`
@@ -47,6 +48,47 @@ Run the full deepreview-spec pipeline (Stages 1-5 from the deepreview-spec comma
 Record the stats from the synthesis return: count of critical, warning, and suggestion findings.
 
 STEP 3: CHECK EXIT CONDITIONS
+
+Parse the stats line from the synthesizer. If it contains novelty metrics (the `| N new, N recurring, N regression` suffix), use NOVELTY MODE. Otherwise use LEGACY MODE.
+
+NOVELTY MODE (iter2+ only):
+
+A) CLEAN EXIT: If 0 critical AND 0 warning AND 0 suggestion:
+
+- Tell the user: "deepreview-spec-loop complete after $ITERATION iteration(s). No findings remain."
+- STOP.
+
+B) CONVERGENCE EXIT: If `0 new AND 0 regression`:
+
+- Tell the user: "deepreview-spec-loop converged after $ITERATION iteration(s). No new findings detected. Remaining recurring findings (if any) reflect reviewer opinion differences."
+- STOP.
+
+C) DEADLOCK EXIT: If `0 new AND N recurring (N > 0) AND 0 regression` for 2 consecutive iterations:
+
+- Tell the user: "Deadlock detected: $N recurring findings persist with no new issues found across 2 iterations:"
+- List the recurring findings.
+- Ask: "How would you like to resolve these? Options: skip these findings, provide guidance, or stop the loop."
+- Follow the user's instruction.
+
+D) DIVERGENCE CHECK (iter2+ only): If total findings INCREASE from the previous iteration:
+
+- If all additional findings are classified [RECURRING] (none are [NEW]):
+  Treat as deadlock, not divergence. Tell the user: "Apparent divergence is actually recurring findings being re-reported. Treating as deadlock."
+  Trigger deadlock prompt (same as C).
+- Otherwise (genuinely new findings increasing):
+  Tell the user: "Divergence detected: findings increased from N to M. The review is not converging — fixes are introducing new issues or reviewers are finding new stylistic concerns."
+  Show the iteration-over-iteration stats.
+  Ask: "Accept current state, revert last iteration's changes, or continue with only critical/warning fixes (ignore suggestions)?"
+  Follow the user's instruction.
+
+E) Otherwise: proceed to STEP 4.
+
+Tracking: If `0 new`, increment CONSECUTIVE_ZERO_NEW. If `> 0 new`, reset CONSECUTIVE_ZERO_NEW to 0. Deadlock (C) triggers when CONSECUTIVE_ZERO_NEW >= 2 AND recurring > 0.
+
+LEGACY MODE (fallback when synthesizer omits novelty metrics):
+
+Warn the user: "Synthesizer did not return novelty metrics — falling back to legacy convergence detection."
+
 Track the total finding count (critical + warning + suggestion) for each iteration in a list: HISTORY.
 
 A) CLEAN EXIT: If 0 critical AND 0 warning AND 0 suggestion:
@@ -54,11 +96,11 @@ A) CLEAN EXIT: If 0 critical AND 0 warning AND 0 suggestion:
 - Tell the user: "deepreview-spec-loop complete after $ITERATION iteration(s). No findings remain."
 - STOP.
 
-B) PLATEAU EXIT: If ITERATION >= 3 and the total has not decreased compared to the minimum of any previous iteration for 2 consecutive iterations (i.e., the last 2 totals are both >= the historical minimum):
+B) PLATEAU EXIT: If ITERATION >= 3 and the total has not decreased compared to the minimum of any previous iteration for 2 consecutive iterations:
 
-- Tell the user: "deepreview-spec-loop plateau after $ITERATION iteration(s). Findings are oscillating (history: [list totals]) and not converging. The spec has been substantively improved but remaining findings likely reflect reviewer opinion differences."
-- Show the latest stats breakdown (critical/warning/suggestion).
-- STOP. Do NOT ask to continue — plateaus in spec review are a natural stopping point.
+- Tell the user: "deepreview-spec-loop plateau after $ITERATION iteration(s). Findings are oscillating (history: [list totals]) and not converging."
+- Show the latest stats breakdown.
+- STOP.
 
 STEP 4: APPLY ALL FIXES
 Dispatch the applier automatically — do NOT ask the user for permission.
@@ -74,7 +116,7 @@ Set ITERATION = ITERATION + 1
 
 If ITERATION > 7:
 
-- Tell the user: "deepreview-spec-loop hit iteration limit (7). This should not normally happen — plateau detection should have stopped earlier."
+- Tell the user: "deepreview-spec-loop hit iteration limit (7). This should not normally happen — convergence or deadlock detection should have stopped earlier."
 - Show the latest stats.
 - STOP.
 
@@ -177,8 +219,20 @@ Note: Validators intentionally do NOT receive PRIOR_CONTEXT. They filter on obje
 Wait for all 5.
 
 Stage 3 — DISPATCH SYNTHESIZER:
+Extract PRIOR_FINDINGS_SECTION from PRIOR_CONTEXT: include only the "## Prior Findings" and "## Applied Fixes" sections (not "Known Issue Locations" or "Covered Regions" — those are for reviewers only).
+
+If PRIOR_FINDINGS_SECTION is non-empty, include the novelty classification header in the synthesizer prompt. If empty (helper returned malformed context), omit the header — the synthesizer will operate in standard mode and the orchestrator MUST use LEGACY MODE for this iteration's exit check.
+
 Task 11 — Use the Task tool with subagent_type="deepreview-synthesizer":
-"Read the validated reviews at: $SESSION_DIR/validated-completeness.md, $SESSION_DIR/validated-consistency.md, $SESSION_DIR/validated-feasibility.md, $SESSION_DIR/validated-docs.md, $SESSION_DIR/validated-architecture.md. Write the synthesis to $SESSION_DIR/synthesis.md."
+
+- If PRIOR_FINDINGS_SECTION is non-empty:
+  "## Prior Findings for Novelty Classification
+  $PRIOR_FINDINGS_SECTION
+
+  Read the validated reviews at: $SESSION_DIR/validated-completeness.md, $SESSION_DIR/validated-consistency.md, $SESSION_DIR/validated-feasibility.md, $SESSION_DIR/validated-docs.md, $SESSION_DIR/validated-architecture.md (skip any that don't exist). Write the synthesis to $SESSION_DIR/synthesis.md."
+
+- If PRIOR_FINDINGS_SECTION is empty:
+  "Read the validated reviews at: $SESSION_DIR/validated-completeness.md, $SESSION_DIR/validated-consistency.md, $SESSION_DIR/validated-feasibility.md, $SESSION_DIR/validated-docs.md, $SESSION_DIR/validated-architecture.md (skip any that don't exist). Write the synthesis to $SESSION_DIR/synthesis.md."
 
 Record the stats line.
 
@@ -196,23 +250,6 @@ If this task fails, emit a warning: "Plan validation failed — applying unvalid
 
 Go to STEP 3.
 
-STEP 6: DIVERGENCE AND DEADLOCK DETECTION
-Track finding counts across iterations. Detect TWO failure modes:
-
-A) DIVERGENCE: If total findings INCREASE from one iteration to the next:
-
-- Tell the user: "Divergence detected: findings increased from N to M. The review is not converging — fixes are introducing new issues or reviewers are finding new stylistic concerns."
-- Show the iteration-over-iteration stats.
-- Ask: "Accept current state, revert last iteration's changes, or continue with only critical/warning fixes (ignore suggestions)?"
-- Follow the user's instruction.
-
-B) DEADLOCK: If two consecutive iterations produce the same findings (same location, same issue title):
-
-- Tell the user: "Deadlock detected: the following findings persist across iterations:"
-- List the repeated findings.
-- Ask: "How would you like to resolve these? Options: skip these findings, provide guidance, or stop the loop."
-- Follow the user's instruction.
-
 IMPORTANT RULES:
 
 - Do NOT read any review/synthesis/plan files yourself. Ever.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mechanai/deepreview",
-  "version": "2.12.0",
+  "version": "2.14.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 } },
+  );
+}