@nanobpm/nano-workforce 0.187.5 → 0.187.6

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.187.6](https://github.com/nanobpm/nano-workforce/compare/v0.187.5...v0.187.6) (2026-09-16)
+
+### Bug Fixes
+
+* **convergence:** re-solicit on a stale Copilot review instead of re-escalating ([#799](https://github.com/nanobpm/nano-workforce/issues/799)) ([#803](https://github.com/nanobpm/nano-workforce/issues/803)) ([58a99b6](https://github.com/nanobpm/nano-workforce/commit/58a99b6024af6cef37f724f9d50cf6151a6f061c)), closes [#789](https://github.com/nanobpm/nano-workforce/issues/789)
+
 ## [0.187.5](https://github.com/nanobpm/nano-workforce/compare/v0.187.4...v0.187.5) (2026-09-15)
 
 ### Bug Fixes

package/SPEC.md

@@ -135,9 +135,33 @@ MAX_ROUNDS forces an escalation ("not converged after N rounds") so a human
 decides rather than looping forever. The guard sits *after* `check-progress`
 (not before), so a husk auto-retry — which does not consume a round — bypasses
 the cap and is re-tried onto a healthy worker even on the final configured round.
+The **stale-review re-solicitation** path (below) likewise bypasses the cap: its
+`f_guardMax` arm is gated on `round ≥ maxRounds and reviewStale != true`, so a
+stale review received on the final configured round re-solicits a fresh review
+instead of escalating (the review-wait timeout remains the backstop).
 ```
 
 Notes:
+- **Convergence comment-gate + stale-review re-solicitation (issue #799).** The
+  agent's self-reported `converged` does not finalize directly: it first runs the
+  deterministic `pr.converge-gate` (`check-converge` → `gw-converge-gate`). That
+  gate **blocks** convergence (`convergeBlocked = true` → escalate "unaddressed
+  comments") while any review thread is unresolved or any suppressed advisory
+  lacks a resolved `nano-ack:` thread; otherwise it proceeds to the scope
+  classifier and finalizes. A third arm handles a **stale review** — one whose
+  `commit_id` predates the PR's current HEAD (its advisories describe code the
+  head has moved past, e.g. an advisory already fixed in a later commit). Rather
+  than block/escalate on the obsolete body, the gate signals `reviewStale = true`
+  and `f_convergeStale` re-enters `persist-round` → `check-progress` (which parks
+  the PR in `waiting_review`, the single writer), so the poller re-solicits a
+  fresh review of the current HEAD. The head is read via the shared
+  branch-ref-preferring reader (`makeDefaultReadHead`, atomic with the push, #786)
+  in BOTH the gate and the poller so they agree on the current head. `reviewStale`
+  is written only by the gate and cleared on BOTH loop re-entry paths — by the
+  `wait-review` catch when a fresh review lands, and by `record-answer` when a
+  human resumes after the review-stall timer — so the marker cannot leak into a
+  later round. Because a stale review is not a failure to converge, this path
+  bypasses the round cap (see the Guard above).
 - On `addressed`, the loop parks at an **event-based gateway** that races the
   canonical `readiness-ready` wait-gate message (ADR 0001 §2; correlated by the
   poller when a fresh review lands)

package/app/convergeGate.test.ts

@@ -18,6 +18,7 @@ import {
   parseAckedAdvisories,
   parseReviewThreadsPage,
   parseSuppressedAdvisories,
+  pickLatestCopilotReview,
   pickLatestCopilotReviewBody,
   type ReviewThread,
 } from "./github.ts";
@@ -432,12 +433,63 @@ test("pickLatestCopilotReviewBody: FAILS CLOSED (null) when the reviews read was
   );
 });
 
+// The COMMIT-ID-carrying picker (`pickLatestCopilotReview`) is the ONLY production path that carries
+// GitHub's `commit_id` into the stale-review guard (#799); the worker tests inject `{ commitId }`
+// directly, so without these the picker's commit_id selection could regress (disabling stale
+// detection) while every other test stays green. These lock: the NEWEST Copilot review's commit_id
+// (and body) is returned; a no-Copilot-review read is verified `{ body: "", commitId: null }`; a
+// truncated read fails closed to `null`.
+test("pickLatestCopilotReview: returns the NEWEST Copilot review's body AND commit_id (oldest\u2192newest)", () => {
+  const picked = pickLatestCopilotReview(
+    [
+      { user: { login: "human" }, body: "human review", commit_id: "humansha" },
+      { user: { login: "Copilot" }, body: "old copilot review", commit_id: "oldsha" },
+      { user: { login: "Copilot" }, body: "newest copilot review", commit_id: "newsha" },
+    ],
+    false,
+  );
+  assertEquals(picked, { body: "newest copilot review", commitId: "newsha" });
+});
+
+test('pickLatestCopilotReview: a complete read with NO Copilot review is verified { body: "", commitId: null }', () => {
+  assertEquals(pickLatestCopilotReview([{ user: { login: "human" }, body: "hi", commit_id: "x" }], false), {
+    body: "",
+    commitId: null,
+  });
+  assertEquals(pickLatestCopilotReview([], false), { body: "", commitId: null });
+});
+
+test("pickLatestCopilotReview: a Copilot review missing commit_id yields commitId null (not stale)", () => {
+  // A review with no commit_id must not fabricate a stale verdict: `isReviewStale` fails safe on a
+  // null review commit_id, and this picker must surface that null rather than an empty string.
+  assertEquals(pickLatestCopilotReview([{ user: { login: "Copilot" }, body: "b" }], false), {
+    body: "b",
+    commitId: null,
+  });
+});
+
+test("pickLatestCopilotReview: FAILS CLOSED (null) when the reviews read was TRUNCATED", () => {
+  assertEquals(pickLatestCopilotReview([{ user: { login: "Copilot" }, body: "possibly stale", commit_id: "s" }], true), null);
+});
+
 async function makeUnderTest(deps: {
   readThreads: (repo: string, n: number) => Promise<ReviewThread[] | null>;
   readReviewBody: (repo: string, n: number) => Promise<string | null>;
+  // The commit SHA the latest Copilot review was submitted against, and the PR's current HEAD SHA
+  // (issue #799). Absent ⇒ both null ⇒ never stale (the pre-#799 behaviour every existing test
+  // relies on). A stale-review test supplies a `reviewCommitId` that differs from `headSha`.
+  reviewCommitId?: string | null;
+  headSha?: string | null;
 }) {
   const { makeHandler } = await import("../workers/converge-gate/worker.ts");
-  return makeHandler(deps);
+  return makeHandler({
+    readThreads: deps.readThreads,
+    readReview: async (repo, n) => {
+      const body = await deps.readReviewBody(repo, n);
+      return body === null ? null : { body, commitId: deps.reviewCommitId ?? null };
+    },
+    readHeadSha: async () => deps.headSha ?? null,
+  });
 }
 
 test("converge-gate: a clean PR is allowed to converge", async () => {
@@ -446,7 +498,7 @@ test("converge-gate: a clean PR is allowed to converge", async () => {
     readReviewBody: async () => "## Overview\nNo suppressed block.",
   });
   const out = await handler({ variables: { prKey: "o/r#1", repo: "o/r", prNumber: 1 } } as any, {} as any);
-  assertEquals(out, { convergeBlocked: false, convergeBlockReason: "" });
+  assertEquals(out, { convergeBlocked: false, convergeBlockReason: "", reviewStale: false });
 });
 
 test("converge-gate: an unresolved thread blocks convergence", async () => {
@@ -488,7 +540,7 @@ test("converge-gate: an acknowledged advisory (resolved ack thread) is allowed",
     readReviewBody: async () => SAMPLE_REVIEW_BODY,
   });
   const out = await handler({ variables: { prKey: "o/r#1", repo: "o/r", prNumber: 1 } } as any, {} as any);
-  assertEquals(out, { convergeBlocked: false, convergeBlockReason: "" });
+  assertEquals(out, { convergeBlocked: false, convergeBlockReason: "", reviewStale: false });
 });
 
 test("converge-gate: FAILS CLOSED when the threads read returns null (no transport)", async () => {
@@ -544,7 +596,7 @@ test("converge-gate: a non-string prKey does not throw — resolves from repo/pr
     readReviewBody: async () => "",
   });
   const out = await handler({ variables: { repo: "o/r", prNumber: 1 } } as any, {} as any);
-  assertEquals(out, { convergeBlocked: false, convergeBlockReason: "" });
+  assertEquals(out, { convergeBlocked: false, convergeBlockReason: "", reviewStale: false });
 });
 
 test("converge-gate: FAILS CLOSED (no throw) when prKey is non-string and repo/prNumber are absent", async () => {
@@ -570,6 +622,57 @@ test("converge-gate: resolves repo/prNumber from the prKey when the vars are abs
   assertEquals(seen, ["o/r", 7]);
 });
 
+// ── Stale-review guard (issue #799) ──────────────────────────────────────────
+// FM2: when the PR HEAD has advanced past the commit the latest Copilot review was submitted
+// against, that review is stale — its suppressed advisories may already be fixed in code. The gate
+// must NOT block/escalate on it; it must signal `reviewStale` so the loop re-solicits a fresh
+// review of the current HEAD. FM1 (an applied-but-unacked advisory re-escalating forever) is
+// structurally cured by this: once the fixing commit lands, the review that still lists the
+// advisory is stale, so the gate re-solicits instead of re-blocking.
+
+test("converge-gate #799: a STALE review (commit_id predates HEAD) does not block — signals reviewStale", async () => {
+  // The review still lists an unacked suppressed advisory (would block if evaluated), but it was
+  // submitted against an OLD commit — the agent has since pushed a fix. The gate must re-solicit,
+  // not escalate.
+  const handler = await makeUnderTest({
+    readThreads: async () => [],
+    readReviewBody: async () => SAMPLE_REVIEW_BODY,
+    reviewCommitId: "oldsha1111111111111111111111111111111111",
+    headSha: "newsha2222222222222222222222222222222222",
+  });
+  const out = await handler({ variables: { prKey: "o/r#1", repo: "o/r", prNumber: 1 } } as any, {} as any);
+  assertEquals(out, { convergeBlocked: false, convergeBlockReason: "", reviewStale: true });
+});
+
+test("converge-gate #799: a HEAD-CURRENT review still blocks on an unacked advisory (control)", async () => {
+  // Same unacked advisory, but the review's commit_id MATCHES HEAD — it is fresh, so the ordinary
+  // gate runs and blocks. Proves the stale guard does not swallow a genuine block.
+  const handler = await makeUnderTest({
+    readThreads: async () => [],
+    readReviewBody: async () => SAMPLE_REVIEW_BODY,
+    reviewCommitId: "samesha33333333333333333333333333333333",
+    headSha: "samesha33333333333333333333333333333333",
+  });
+  const out = await handler({ variables: { prKey: "o/r#1", repo: "o/r", prNumber: 1 } } as any, {} as any);
+  assertEquals(out.convergeBlocked, true);
+  assertEquals(out.reviewStale, false);
+  assertStringIncludes(out.convergeBlockReason ?? "", "spec-app/nano-app.schema.json:613");
+});
+
+test("converge-gate #799: an unknown review commit_id or unreadable HEAD is NOT stale (evaluates normally)", async () => {
+  // Fail-safe: without both SHAs we cannot prove staleness, so the gate must fall through to the
+  // ordinary evaluation (here: block on the unacked advisory), never fabricate a re-solicit loop.
+  const handler = await makeUnderTest({
+    readThreads: async () => [],
+    readReviewBody: async () => SAMPLE_REVIEW_BODY,
+    reviewCommitId: null,
+    headSha: "newsha2222222222222222222222222222222222",
+  });
+  const out = await handler({ variables: { prKey: "o/r#1", repo: "o/r", prNumber: 1 } } as any, {} as any);
+  assertEquals(out.convergeBlocked, true);
+  assertEquals(out.reviewStale, false);
+});
+
 // ── Structural guard over the committed BPMN (no engine) ─────────────────────
 
 const bpmn = readFileSync("resources/processes/convergence-loop.bpmn", "utf8");
@@ -606,6 +709,60 @@ test("gw-converge-gate blocks on an explicit convergeBlocked = true condition",
   assertStringIncludes(f, "convergeBlocked = true");
 });
 
+test("gw-converge-gate routes a STALE review back to persist-round (re-solicit), not to escalation (#799)", () => {
+  const f = flowElement("f_convergeStale");
+  assert(f, "f_convergeStale flow missing");
+  assertStringIncludes(f, 'sourceRef="gw-converge-gate"');
+  // A stale review re-enters the round loop via persist-round → check-progress, which parks
+  // waiting_review (the single writer) and the poller re-solicits a fresh review.
+  assertStringIncludes(f, 'targetRef="persist-round"');
+  assertStringIncludes(f, "reviewStale = true");
+  // persist-round must accept the stale re-entry as an incoming.
+  const pr = flat.match(/<bpmn:serviceTask\b[^>]*\bid="persist-round"[^>]*>.*?<\/bpmn:serviceTask>/);
+  assert(pr, "persist-round task missing");
+  assertStringIncludes(pr[0], "<bpmn:incoming>f_convergeStale</bpmn:incoming>");
+  // The gate's output envelope must declare reviewStale for the FEEL condition to read it.
+  assertStringIncludes(flat, 'id="PrConvergeGateOut"');
+  assert(
+    /<nano:shape\b[^>]*\bid="PrConvergeGateOut"[^>]*>.*?name="reviewStale".*?<\/nano:shape>/.test(flat),
+    "PrConvergeGateOut must declare reviewStale",
+  );
+});
+
+test("the round cap does NOT escalate a stale-retry round — f_guardMax is gated on reviewStale != true (#799)", () => {
+  // A stale review re-enters persist-round → check-progress → gw-guard. On the FINAL configured round
+  // the cap would escalate a human instead of soliciting a fresh review — but a stale review is not a
+  // failure to converge, it is a review of obsolete code. The round cap must therefore bypass the
+  // stale-retry path (the review-wait timeout remains the backstop against an indefinitely stalled
+  // re-solicitation).
+  const f = flowElement("f_guardMax");
+  assert(f, "f_guardMax flow missing");
+  assertStringIncludes(f, "maxRounds and reviewStale != true");
+});
+
+test("wait-review clears reviewStale when a fresh review lands, so the marker can't leak into a later round (#799)", () => {
+  // reviewStale is written ONLY by the converge-gate; once a fresh review arrives it is no longer
+  // known-stale, so wait-review resets it to false alongside the round increment. Without this reset
+  // a stale marker would persist and disable the round cap for a subsequent addressed round.
+  const wr = flat.match(/<bpmn:intermediateCatchEvent\b[^>]*\bid="wait-review"[^>]*>.*?<\/bpmn:intermediateCatchEvent>/);
+  assert(wr, "wait-review catch event missing");
+  assertStringIncludes(wr[0], '<zeebe:output source="=round + 1" target="round" />');
+  assertStringIncludes(wr[0], '<zeebe:output source="=false" target="reviewStale" />');
+});
+
+test("record-answer clears reviewStale so a human-resumed round after a review-stall timeout is re-capped (#799)", () => {
+  // reviewStale is cleared on the wait-review MESSAGE arm, but the review-wait TIMER arm bypasses it:
+  // wait-review-timeout → persist-review-stalled → wait-answer → record-answer → capture-head. A
+  // stale-retry round that times out and is resumed by a human therefore re-enters the loop still
+  // carrying reviewStale = true, which — via `f_guardMax`'s `reviewStale != true` guard — would keep
+  // the round cap disabled for that (and every subsequent) human-directed addressed round. Once a
+  // human is answering escalations the automated stale-retry is over, so record-answer must reset the
+  // marker; a genuinely-still-stale next review re-sets it at the converge-gate.
+  const task = flat.match(/<bpmn:serviceTask\b[^>]*\bid="record-answer"[^>]*>.*?<\/bpmn:serviceTask>/);
+  assert(task, "record-answer task missing");
+  assertStringIncludes(task[0], '<zeebe:output source="=false" target="reviewStale" />');
+});
+
 test("gw-converge-gate default arm routes to the scope classifier (not straight to finalize)", () => {
   const gw = flat.match(/<bpmn:exclusiveGateway\b[^>]*\bid="gw-converge-gate"[^>]*>/);
   assert(gw, "gw-converge-gate gateway missing");

package/app/currentHead.ts

@@ -0,0 +1,60 @@
+// The PR "current HEAD" reader shared by every step that must gate on the head the push landed —
+// the capture-head / progress-check steps, the converge-gate's stale-review guard, AND the poller's
+// stale-review re-solicitation (#799). It lives in this neutral module (not in a worker) so the
+// poller in `app/service.ts` can reuse the EXACT reader the workers use without importing a worker
+// (which would form a `service.ts ↔ worker` cycle) and without a second, drift-prone copy of the
+// branch-ref-over-`head.sha` preference (#786).
+import type { fetchBranchHead, fetchPrHead } from "./github.ts";
+
+// Reads a PR's current head SHA. Injectable so unit tests never touch git/network; the default
+// binds the real GitHub reader (the shared gh | token transport) and swallows any failure to
+// `null` so the guard fails OPEN. It reads the BRANCH ref (`git/ref/heads/<branch>`) — updated
+// atomically with the push — in preference to the PR object's asynchronously-denormalized
+// `head.sha`, so a lagging PR projection can never fabricate a stale-but-valid no-advance
+// escalation (#786). Once a head ref is known this trusts ONLY its atomic ref: a failed/absent
+// ref read fails OPEN (`null`), never falling back to `head.sha`. The PR head is used only when
+// the PR carries NO head ref at all.
+// The optional `token` lets a caller that already holds a per-call GitHub credential (e.g. the
+// poller in `app/service.ts`, which is handed a `token` for its review fetch) read the head with the
+// SAME credential rather than silently diverging to `process.env.GITHUB_TOKEN`. Omitting it keeps
+// the env-token default, so the worker callers (capture-head / progress-check / converge-gate) are
+// unchanged. Binding both reads to one credential closes the drift where a caller supplying a token
+// without that env var would get a `null` head (→ `isReviewStale` fails open, advancing a stale
+// review); see #799.
+export type HeadReader = (repo: string, prNumber: number, token?: string) => Promise<string | null>;
+
+/** Build the real head reader from the GitHub fetchers (injected so tests can stub them). Prefers
+ * the branch ref (atomic with the push) over the PR object's denormalized `head.sha` (#786); fails
+ * OPEN (`null`) on any unreadable state so a transport hiccup never fabricates a stale verdict. The
+ * single canonical implementation — capture-head, progress-check, converge-gate, and the poller all
+ * bind this so they gate on the same head. */
+export function makeDefaultReadHead(deps: {
+  fetchPrHead: typeof fetchPrHead;
+  fetchBranchHead: typeof fetchBranchHead;
+}): HeadReader {
+  return async (repo, prNumber, token) => {
+    const tok = token ?? process.env.GITHUB_TOKEN ?? "";
+    const pr = await deps.fetchPrHead(repo, prNumber, tok).catch(() => null);
+    if (!pr) return null;
+    // Prefer the branch ref (atomic with the push) over the PR object's denormalized head.sha (#786).
+    // Once the head branch is known, trust ONLY its atomic ref: a failed/absent ref read fails OPEN
+    // (`null`) rather than falling back to the PR object's asynchronously-denormalized head.sha, which
+    // can still report a stale-but-valid SHA after a push and fabricate a no-advance escalation — the
+    // very projection this branch-ref read exists to avoid. The ref is read in the repository the
+    // head branch actually lives in (the fork for a cross-repo PR — see below), so a fork PR fails
+    // open safely instead of comparing an unrelated base-repo SHA. Fall back to the PR head only when
+    // there is NO head ref.
+    if (pr.headRef) {
+      // Resolve the head ref in the repository the head branch actually lives in — the FORK for a
+      // cross-repo PR (`pr.headRepo`), else the base `repo`. Querying the base repo unconditionally
+      // would, for a fork PR whose head branch shares a name with a base-repo branch, read the
+      // unrelated base-branch SHA and fabricate progress/no-progress (#786). When the head repo
+      // cannot be resolved (a deleted fork ⇒ `headRepo:null`) fail OPEN to `null` rather than fall
+      // back to the base repo and risk that collision.
+      const headRepo = pr.headRepo;
+      if (!headRepo) return null;
+      return await deps.fetchBranchHead(headRepo, pr.headRef, tok).catch(() => null);
+    }
+    return pr.headSha ?? null;
+  };
+}

package/app/github.test.ts

@@ -3,7 +3,7 @@
 // the merge-exclusion graph. Force the token transport and stub `globalThis.fetch`.
 import { test } from "node:test";
 import { assertEquals, assertRejects } from "#test-assert";
-import { BaseBranchMustExistError, checkConclusions, classifyMergeability, classifyPrLiveness, coalesceTitle, createPullRequest, ensureBaseBranch, ensurePromotionPr, fetchBranchHead, fetchIssueTitle, fetchPrFiles, fetchPrHead, isNotAPullRequestError, listPrsForHead, type Mergeability, type PrState } from "./github.ts";
+import { BaseBranchMustExistError, checkConclusions, classifyMergeability, classifyPrLiveness, coalesceTitle, createPullRequest, ensureBaseBranch, ensurePromotionPr, fetchBranchHead, fetchIssueTitle, fetchPrFiles, fetchPrHead, fetchPrReviews, isNotAPullRequestError, listPrsForHead, type Mergeability, type PrState } from "./github.ts";
 import { DEFAULT_MERGE_PROTOCOL, type MergeProtocol, type RequiredCheck } from "./mergeProtocol.ts";
 
 // A fake `fetch` that serves `pages` of file batches; each page N (1-based) returns `pages[N-1]`
@@ -60,6 +60,70 @@ test("fetchPrFiles: throws when the cap genuinely truncates (full last page + ne
   );
 });
 
+// ── fetchPrReviews token-transport paging (issue #799) ──────────────────────────────────────────
+// The poller picks the NEWEST review by id, so `fetchPrReviews` must page the FULL (oldest→newest)
+// list — reading only the first `per_page=100` page would surface the oldest 100 and miss the
+// genuinely newest review on a >100-review convergence loop. The token transport mirrors
+// `fetchPrFiles`: it fails CLOSED (throws) when the paging cap genuinely truncates rather than
+// returning a partial list the poller would treat as complete.
+
+// A fake `fetch` that serves `pages` of review batches; each page N (1-based) returns `pages[N-1]`
+// reviews (with ascending ids), setting `Link: rel="next"` whenever a later page exists.
+function stubReviewFetch(pages: number[]) {
+  return (url: string | URL | Request): Promise<Response> => {
+    const u = new URL(String(url));
+    const page = Number(u.searchParams.get("page") ?? "1");
+    const count = pages[page - 1] ?? 0;
+    const start = pages.slice(0, page - 1).reduce((a, b) => a + b, 0);
+    const body = Array.from({ length: count }, (_, i) => ({
+      id: start + i + 1,
+      state: "COMMENTED",
+      submitted_at: "2026-01-01T00:00:00Z",
+    }));
+    const headers = new Headers();
+    if (page < pages.length) {
+      headers.set("link", `<https://api.github.com/next?page=${page + 1}>; rel="next"`);
+    }
+    return Promise.resolve(new Response(JSON.stringify(body), { status: 200, headers }));
+  };
+}
+
+async function withReviewTransport<T>(pages: number[], fn: () => Promise<T>): Promise<T> {
+  const prevMode = process.env["NANO_PR_GITHUB_TRANSPORT"];
+  const prevFetch = globalThis.fetch;
+  process.env["NANO_PR_GITHUB_TRANSPORT"] = "token";
+  globalThis.fetch = stubReviewFetch(pages) as typeof fetch;
+  try {
+    return await fn();
+  } finally {
+    globalThis.fetch = prevFetch;
+    if (prevMode === undefined) delete process.env["NANO_PR_GITHUB_TRANSPORT"];
+    else process.env["NANO_PR_GITHUB_TRANSPORT"] = prevMode;
+  }
+}
+
+test("fetchPrReviews: pages the full list beyond the first 100 (newest review is seen)", async () => {
+  const reviews = await withReviewTransport([100, 37], () => fetchPrReviews("o/r", 1, "tok"));
+  assertEquals(reviews?.length, 137);
+  // The genuinely newest review (highest id) is on the SECOND page — it must be present.
+  assertEquals(reviews?.[reviews.length - 1]?.id, 137);
+});
+
+test("fetchPrReviews: no token → null (idle, not a throw)", async () => {
+  const reviews = await withReviewTransport([100], () => fetchPrReviews("o/r", 2, ""));
+  assertEquals(reviews, null);
+});
+
+test("fetchPrReviews: throws when the cap genuinely truncates (full last page + next)", async () => {
+  // MAX_PAGES=20 full pages, and the 20th still advertises `rel="next"` → fail closed.
+  const capped = Array.from({ length: 21 }, () => 100);
+  await assertRejects(
+    () => withReviewTransport(capped, () => fetchPrReviews("o/r", 3, "tok")),
+    Error,
+    "truncated",
+  );
+});
+
 // ── ensureBaseBranch (ADR 0003 rule 2) ──────────────────────────────────────
 // Force the token transport and stub `globalThis.fetch` so the create-if-missing primitive is
 // exercised end-to-end without touching the network: git-ref lookups, default-branch resolution,

package/app/github.ts

@@ -23,6 +23,10 @@ export interface GhReview {
   id: number;
   state: string;
   submitted_at?: string;
+  /** The commit SHA the review was submitted against (GitHub's `commit_id`). Used to detect a
+   * review that predates the PR's current HEAD — a STALE review whose advisories are about code the
+   * head has since moved past (issue #799). Absent on data GitHub did not carry a `commit_id` for. */
+  commit_id?: string | null;
 }
 
 export type GithubTransport = "gh" | "token" | "auto";
@@ -61,7 +65,12 @@ function isGhAvailable(): Promise<boolean> {
 }
 
 /** Fetch the reviews for one PR via the configured transport. Throws on transport failure so
- * the caller can log-and-continue; returns `null` when no transport is usable (idle). */
+ * the caller can log-and-continue; returns `null` when no transport is usable (idle). Pages the
+ * FULL (oldest→newest) reviews list — the poller picks the newest fresh review by id, so reading
+ * only the first `per_page=100` page would, on a >100-review convergence loop, surface the OLDEST
+ * 100 and miss the genuinely newest review (repeatedly nudging while a current-head review sits on a
+ * later page, or classifying an old review as stale). This mirrors {@link fetchLatestCopilotReview}'s
+ * paging so both readers agree on which review is newest. */
 export async function fetchPrReviews(
   repo: string,
   number: number | string,
@@ -71,17 +80,43 @@ export async function fetchPrReviews(
   const useGh = mode === "gh" || (mode === "auto" && (await isGhAvailable()));
   const path = `repos/${repo}/pulls/${number}/reviews?per_page=100`;
   if (useGh) {
-    const out = await runGh(["api", path, "-H", "Accept: application/vnd.github+json"]);
+    // `--paginate --slurp` walks EVERY page of the (oldest→newest) reviews array, so a >100-review
+    // convergence loop still surfaces the genuinely newest review rather than the oldest 100. Plain
+    // `--paginate` concatenates one JSON array PER PAGE (multiple documents) which `JSON.parse`
+    // cannot read; `--slurp` wraps the pages in an outer array we flatten one level (mirrors
+    // {@link githubReleasesCommand}/{@link parseReleases}).
+    const out = await runGh([
+      "api", "--paginate", "--slurp", path, "-H", "Accept: application/vnd.github+json",
+    ]);
     // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
-    return JSON.parse(out) as GhReview[];
+    return (JSON.parse(out) as GhReview[][]).flat();
   }
   if (!token) return null; // token mode with no token → poller idles
-  const r = await fetch(`https://api.github.com/${path}`, {
-    headers: { authorization: `Bearer ${token}`, accept: "application/vnd.github+json" },
-  });
-  if (!r.ok) throw new Error(`github ${r.status} ${r.statusText}`.trim());
-  // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
-  return (await r.json()) as GhReview[];
+  // Page the token transport the same way; 20×100 reviews is far past any real convergence loop, and
+  // a genuinely deeper history we can't reach is unverifiable → fail CLOSED (throw) rather than
+  // return a partial list the poller would treat as complete (selecting an older review, re-nudging).
+  const reviews: GhReview[] = [];
+  const MAX_PAGES = 20;
+  for (let page = 1; page <= MAX_PAGES; page++) {
+    const r = await fetch(`https://api.github.com/${path}&page=${page}`, {
+      headers: { authorization: `Bearer ${token}`, accept: "application/vnd.github+json" },
+    });
+    if (!r.ok) throw new Error(`github ${r.status} ${r.statusText}`.trim());
+    // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
+    const batch = (await r.json()) as GhReview[];
+    reviews.push(...batch);
+    // A short final page means we've read every review — the list is complete.
+    if (batch.length < 100) return reviews;
+    // A full page on the last allowed page is only truncated if GitHub says there's more; trust the
+    // `Link` header's `rel="next"` (mirrors {@link fetchPrFiles}) so an exact multiple of 100 isn't a
+    // false positive, and throw when the cap genuinely truncates rather than under-reading history.
+    if (page === MAX_PAGES && /<[^>]*>;\s*rel="next"/.test(r.headers.get("link") ?? "")) {
+      throw new Error(
+        `github pr reviews truncated: ${repo}#${number} exceeds ${MAX_PAGES * 100}-review paging cap`,
+      );
+    }
+  }
+  return reviews;
 }
 
 // ── Review-comment convergence gate (don't converge with unaddressed comments) ──────────────
@@ -279,36 +314,73 @@ export function pickLatestCopilotReviewBody(
   reviews: { user?: { login?: string }; body?: string }[],
   truncated: boolean,
 ): string | null {
+  const picked = pickLatestCopilotReview(reviews, truncated);
+  return picked === null ? null : picked.body;
+}
+
+/** Pick the newest Copilot review — body AND the commit SHA it was submitted against — from a
+ * reviews list (GitHub returns them oldest→newest). Semantics mirror {@link pickLatestCopilotReviewBody}
+ * exactly: `truncated = true` fails CLOSED (`null`, unverifiable); a verified-complete read with no
+ * Copilot review returns `{ body: "", commitId: null }` (a verified "no advisories"). The `commitId`
+ * lets a caller detect a review that predates the PR's current HEAD — a STALE review whose advisories
+ * are about code the head has since moved past (issue #799). Pure; unit-tested. */
+export function pickLatestCopilotReview(
+  reviews: { user?: { login?: string }; body?: string; commit_id?: string | null }[],
+  truncated: boolean,
+): { body: string; commitId: string | null } | null {
   if (truncated) return null;
   const copilot = reviews.filter((rv) => isCopilot(rv.user?.login));
-  return copilot[copilot.length - 1]?.body ?? "";
+  const latest = copilot[copilot.length - 1];
+  return { body: latest?.body ?? "", commitId: latest?.commit_id ?? null };
 }
 
 /** Fetch the latest Copilot review body for a PR (the newest review authored by the automated
  * Copilot reviewer). Returns `null` ONLY when no transport is usable (unverifiable → the worker
  * fails closed); returns `""` when transport is usable but the PR has no Copilot review yet (a
  * verified "no suppressed advisories"). Throws on a genuine transport failure. This split keeps
- * `null` from conflating "unverifiable" with "empty" and fail-OPENing the advisory dimension. */
+ * `null` from conflating "unverifiable" with "empty" and fail-OPENing the advisory dimension.
+ * Thin wrapper over {@link fetchLatestCopilotReview} (the single fetch implementation). */
 export async function fetchLatestCopilotReviewBody(
   repo: string,
   number: number | string,
   token: string,
 ): Promise<string | null> {
+  const picked = await fetchLatestCopilotReview(repo, number, token);
+  return picked === null ? null : picked.body;
+}
+
+/** Fetch the latest Copilot review — body AND the commit SHA it was submitted against — for a PR.
+ * Same null/`""`-vs-unverifiable semantics as {@link fetchLatestCopilotReviewBody} (which delegates
+ * here): `null` ONLY when no transport is usable (unverifiable → fail closed); a verified read with
+ * no Copilot review yet returns `{ body: "", commitId: null }`. The `commitId` lets the convergence
+ * gate detect a review that predates the PR's current HEAD — a STALE review whose advisories are
+ * about code the head has since moved past (issue #799) — and re-solicit a fresh review rather than
+ * block/escalate against the obsolete body. Throws on a genuine transport failure. */
+export async function fetchLatestCopilotReview(
+  repo: string,
+  number: number | string,
+  token: string,
+): Promise<{ body: string; commitId: string | null } | null> {
   const mode = githubTransport();
   const useGh = mode === "gh" || (mode === "auto" && (await isGhAvailable()));
   const basePath = `repos/${repo}/pulls/${number}/reviews?per_page=100`;
   interface Review {
     user?: { login?: string };
     body?: string;
+    commit_id?: string | null;
   }
   if (useGh) {
-    // `--paginate` merges EVERY page of the (oldest→newest) reviews array, so a >100-review
+    // `--paginate --slurp` walks EVERY page of the (oldest→newest) reviews array, so a >100-review
     // convergence loop still surfaces the genuinely newest Copilot review rather than the oldest
-    // 100 — reading only the first page here would fail-OPEN the advisory dimension.
-    const out = await runGh(["api", "--paginate", basePath, "-H", "Accept: application/vnd.github+json"]);
+    // 100 — reading only the first page here would fail-OPEN the advisory dimension. Plain
+    // `--paginate` concatenates one JSON array PER PAGE (multiple documents) which `JSON.parse`
+    // cannot read; `--slurp` wraps the pages in an outer array we flatten one level.
+    const out = await runGh([
+      "api", "--paginate", "--slurp", basePath, "-H", "Accept: application/vnd.github+json",
+    ]);
     // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
-    const reviews = JSON.parse(out) as Review[];
-    return pickLatestCopilotReviewBody(reviews, false);
+    const reviews = (JSON.parse(out) as Review[][]).flat();
+    return pickLatestCopilotReview(reviews, false);
   }
   if (!token) return null;
   // Page the token transport the same way; 20×100 reviews is far past any real convergence loop, and
@@ -324,14 +396,14 @@ export async function fetchLatestCopilotReviewBody(
     const batch = (await r.json()) as Review[];
     reviews.push(...batch);
     // A short page means we've read every review — the list is complete.
-    if (batch.length < 100) return pickLatestCopilotReviewBody(reviews, false);
+    if (batch.length < 100) return pickLatestCopilotReview(reviews, false);
     // A full page on the last allowed page is only truncated if GitHub says there's more; trust the
     // `Link` header's `rel="next"` so an exact multiple of 100 isn't a false positive.
     if (page === MAX_PAGES && /<[^>]*>;\s*rel="next"/.test(r.headers.get("link") ?? "")) {
-      return pickLatestCopilotReviewBody(reviews, true);
+      return pickLatestCopilotReview(reviews, true);
     }
   }
-  return pickLatestCopilotReviewBody(reviews, false);
+  return pickLatestCopilotReview(reviews, false);
 }
 
 /** Raw GraphQL response shape for the review-threads query. */