feat: post a run's new inline comments in one review

README.md

@@ -732,8 +732,13 @@ Behavior notes:
 - **Replies on inline threads count as author feedback.** Replying in a thread
   matches the reply to that finding structurally; clearing still requires the
   `id:…` token in the replier's own words, same as main-comment replies.
-- **Notification fan-out.** The first enabled run on a PR sends one notification
-  per created inline comment; `maxComments` bounds it.
+- **One review per run.** A run's new inline comments go out in one `COMMENT`
+  review, so each run puts one review entry and one notification on the PR (one
+  per scope in per-scope comment mode), not one per comment. The reviewer never
+  approves or requests changes. If GitHub refuses one of the comments, for
+  example for a line it won't anchor, the comments are posted one by one
+  instead, each as its own review. The review has no body of its own, so
+  nothing is left on the PR once its threads are deleted.
 - **Disabling later** leaves existing threads up (the sync no longer runs); a
   comment-mode switch — or the reporter's clear path — stubs/removes them.
 

llp/0008-sources-and-reporters.explainer.md

@@ -57,7 +57,7 @@ The base OID is fetchable by SHA even though the base ref may have moved since t
 
 ## GitHub Reporter Identity
 
-The reporter maintains exactly one PR comment and is comment-only — it never touches the review-thread / GitHub "reviews" APIs, by explicit design [observed] ([github.ts:77-82](../src/reporters/github.ts)). The hard problem is: which comment on the PR is *ours*?
+The reporter maintains exactly one PR comment, plus optional inline threads (see [Inline Threads](#inline-threads)), and it never approves or requests changes: the only review it creates is a `COMMENT` review that carries a run's new inline threads [observed] ([github.ts](../src/reporters/github.ts) `GitHubReporter` doc comment). The hard problem is: which comment on the PR is *ours*?
 
 **Author + marker, never marker alone.** The comment marker is a hardcoded public literal, readable in the base-branch config, so anyone who can comment on the PR (including the untrusted PR author) could post a comment carrying the marker plus a forged embedded review state. A newest-marker-wins lookup would adopt that state and carry its `dismissed` list forward, silently suppressing real findings. So a comment counts as ours only if it carries the marker AND was authored by `ownLogin` — GitHub sets a comment's author from the authenticated identity and it cannot be spoofed [observed] ([github.ts:51-75](../src/reporters/github.ts); commit 93aaf30: "identify our own comment by author + marker, not the public marker alone, so a forged comment can't carry review state forward"; regression tests `src/__tests__/github-reporter.test.ts:25-34`). Any rewrite that reintroduces marker-only matching reopens this forged-dismissal-state attack.
 
@@ -79,6 +79,16 @@ The reporter maintains exactly one PR comment and is comment-only — it never t
 
 **Links fail soft.** `linkContextAsync` can be prebuilt and injected once so a CI fan-out builds one diff-lines + base-SHA context for all scopes instead of one pair of `gh` calls per scope — the reporter-side mirror of `memoizeSource` [observed] ([github.ts:33-37, 200-205](../src/reporters/github.ts)). Both underlying fetches fail soft: a missing diff index degrades in-diff findings to plain-text `file:line`, a missing base SHA degrades out-of-diff findings the same way — never a dead link, never a hard failure of the whole report [observed] ([github.ts:194-235](../src/reporters/github.ts); commits f9fecd5, 9446b42). This follows the repo rule that `ecr ci` must never fail a PR's checks on reviewer error [observed] (AGENTS.md: "`ecr ci` must never fail a PR's checks — reviewer errors degrade gracefully").
 
+## Inline Threads
+
+With `inline.enabled`, `syncInline` converges one inline thread per in-diff finding: `planInlineSync` decides which threads to create, patch, stub or delete, and the executor runs the plan [observed] ([github.ts](../src/reporters/github.ts) `planInlineSync`, `syncInline`).
+
+**One review per run for new threads.** GitHub makes every `POST /pulls/{n}/comments` its own review, so posting threads one by one put one "reviewed" entry and one notification per finding on the PR. The executor instead posts all of a run's new threads in one `POST /pulls/{n}/reviews` with `event: "COMMENT"`, the reviewed head as `commit_id`, and an empty body [observed] ([github.ts](../src/reporters/github.ts) `createInlineReview`). GitHub's docs call the body required for a `COMMENT` review, but it accepts an empty or missing one when the review has comments [observed: probe against a private scratch PR, 2026-10-21]. A submitted review can't be deleted, so a body would stay on the PR after its threads are torn down; an empty one leaves nothing. In per-scope comment mode every scope's reporter syncs its own threads, so a run posts one review per scope with new threads [observed] (`reporterFor` in `src/commands/ci.ts` passes the root `inline` config to each scope). Patches, stubs and deletes stay per comment: they edit existing threads and create no review.
+
+**The batch is all or nothing, and only a 422 a comment caused is retried.** GitHub rejects the whole review with a 422 when it refuses one comment, for example a line it will not anchor, and then creates nothing: a review with one valid and one unanchorable line came back 422 `Line could not be resolved` and created neither comment [observed: probe against a private scratch PR, 2026-10-21]. That error falls back to one `POST /pulls/{n}/comments` per thread, so only the refused comment is lost. Two 422s are about the account, not a comment, and one-by-one posts would hit them again: GitHub's spam throttle ("submitted too quickly") aborts the rest of the sync like a rate limit, for the review and for each one-by-one post, and a pending review the posting account already has on the PR (GitHub allows one, and refuses both POSTs with "one pending review per pull request" while it exists) fails the new threads with a message saying to submit or delete it, while stubs and deletes still run. Telling them apart needs the response body: `gh` prints only the top-level message to stderr (`gh: Unprocessable Entity (HTTP 422)`) and the body, with `errors[]`, to stdout [observed: probe against a private scratch PR, 2026-10-21; the spam throttle's text is from reports, not reproduced], so both POSTs run with `check: false` and `ghApiFailure` keeps the body's distinct messages, each capped, in the error. Any other failure, such as a 5xx or a dropped connection, may come after GitHub created the review, so a retry could post every thread twice: the executor counts those threads as failed and does not retry, the main comment renders the findings in full, and the next run creates whatever is still missing. A rate limit aborts the rest of the sync as before [observed] (`syncInline`, `isPendingReviewError`, `ghApiFailure`; tests `src/__tests__/inline-review.test.ts`).
+
+**Links come from a second call.** The review response does not list its comments, so the executor reads `GET /pulls/{n}/reviews/{id}/comments` a page at a time, up to the same 30-page bound as every comment listing, and maps each comment to its finding by the anchored marker in its body (`inlineUrlsByFp`). When a page fails, the pages before it stay linked, the threads exist, and the main comment renders the rest in full for this run; the next run finds the threads through `ownInlineComments` and links them. A rate limit on that read aborts the stubs and deletes still to come [observed] (`syncInline`, `inlineReviewCommentPages`).
+
 ## Terminal Reporter
 
 The terminal reporter writes the primary report to **stdout** (progress and logging go to stderr) specifically so `ecr review > out.txt` captures a clean report and shell redirection works as expected [observed] ([terminal.ts:45-47](../src/reporters/terminal.ts)). It maps `review.decision` to a process exit code via `decisionExitCode`, which is what makes it usable as a pre-push/pre-commit gate; `--json` disables color and `noFail` forces exit 0 [observed] ([terminal.ts:28-32, 38, 49](../src/reporters/terminal.ts)). Color is enabled only on a TTY and only when not `--json` [observed] ([terminal.ts:38](../src/reporters/terminal.ts): `!options.json && Boolean(process.stdout.isTTY)`) — naively coloring whenever output is not JSON, ignoring `isTTY`, would corrupt piped or redirected output with ANSI codes.