@nanobpm/nano-workforce 0.187.5 → 0.188.0

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) ──────────────
@@ -246,25 +281,59 @@ export function parseSuppressedAdvisories(reviewBody: string | null | undefined)
   return out;
 }
 
+/** The line-stable advisory keys carried by a SINGLE comment body's canonical `nano-ack: <path> ::
+ * <text>` markers. This is the SOLE recognizer of an acknowledgement, shared by `isAckThread` and
+ * `parseAckedAdvisories` so "is this an ack?" has ONE canonical implementation (derivation over
+ * duplication — no drift between the two consumers). The bare `nano-ack: <path>:<line>` form yields
+ * NOTHING here: `NEW_ACK` requires the ` :: <text>` prose (a bare `path:line` is prose-blind and
+ * would false-OPEN a new advisory re-emitted at a previously-acked line). */
+function canonicalAckKeys(body: string): string[] {
+  const keys: string[] = [];
+  ACK_MARKER.lastIndex = 0;
+  let m: RegExpExecArray | null;
+  // biome-ignore lint/suspicious/noAssignInExpressions: canonical regex-exec accumulation loop
+  while ((m = ACK_MARKER.exec(body)) !== null) {
+    const nw = NEW_ACK.exec(m[1].trim());
+    if (nw) keys.push(advisoryStableKey(nw[1], nw[2]));
+  }
+  return keys;
+}
+
+/** True when a review thread is a DEDICATED `nano-ack:` acknowledgement thread — one whose ROOT
+ * comment (`bodies[0]`, the thread-opening comment) carries a valid canonical `nano-ack: <path> ::
+ * <text>` marker — rather than a substantive code-review thread. This is a CLASSIFICATION only: the
+ * converge gate never DROPS an unresolved thread on the strength of this predicate. An unresolved ack
+ * thread still BLOCKS convergence (it is a genuinely-open GitHub thread); the classification only
+ * routes that block onto the recoverable ack-only path — a partially-completed acknowledgement the
+ * bounded #796 auto-ack retry can finish (post-and-resolve) — instead of escalating a human. A
+ * substantive unresolved thread escalates to a human.
+ *
+ * Because the gate BLOCKS either way, this predicate is FAIL-CLOSED even under a false positive:
+ *   1. Only the canonical prose-keyed form counts (via `canonicalAckKeys`); the retired bare
+ *      `nano-ack: <path>:<line>` form does NOT — matching `parseAckedAdvisories`.
+ *   2. Only the ROOT comment is inspected — a reviewer's substantive finding is ALWAYS its thread's
+ *      root and (canonical-form) never carries this marker, so a substantive thread that merely
+ *      quotes or replies `nano-ack:` in a later comment is not mis-classified.
+ *   3. Even if a root DID quote the canonical marker mid-prose and were mis-labelled an ack, the
+ *      thread is NOT excluded — it still blocks (as ack-only), and the bounded auto-ack retry cannot
+ *      ack a non-advisory, so it escalates to a human on exhaustion. Marker presence never finalizes
+ *      the gate with an open thread (the fail-OPEN this design forecloses). */
+export function isAckThread(thread: ReviewThread): boolean {
+  const root = thread.bodies[0];
+  return root !== undefined && canonicalAckKeys(root).length > 0;
+}
+
 /** Extract the acknowledged advisory keys from a set of review threads (only RESOLVED threads
  * count — an open ack thread is not yet an acknowledgement). Returns line-stable keys (`<path>#<fp>`)
- * parsed from the `nano-ack: <path> :: <text>` form ONLY. A bare `nano-ack: <path>:<line>` marker is
- * intentionally NOT honoured: its `path:line` key is blind to the advisory prose and would false-OPEN
- * a genuinely new advisory re-emitted at a previously-acked line. The gate treats an advisory as
- * acked iff its stable key appears here. */
+ * parsed from the `nano-ack: <path> :: <text>` form ONLY (via the shared `canonicalAckKeys`). A bare
+ * `nano-ack: <path>:<line>` marker is intentionally NOT honoured: its `path:line` key is blind to the
+ * advisory prose and would false-OPEN a genuinely new advisory re-emitted at a previously-acked line.
+ * The gate treats an advisory as acked iff its stable key appears here. */
 export function parseAckedAdvisories(threads: ReviewThread[]): string[] {
   const acked = new Set<string>();
   for (const t of threads) {
     if (!t.isResolved) continue;
-    for (const body of t.bodies) {
-      ACK_MARKER.lastIndex = 0;
-      let m: RegExpExecArray | null;
-      // biome-ignore lint/suspicious/noAssignInExpressions: canonical regex-exec accumulation loop
-      while ((m = ACK_MARKER.exec(body)) !== null) {
-        const nw = NEW_ACK.exec(m[1].trim());
-        if (nw) acked.add(advisoryStableKey(nw[1], nw[2]));
-      }
-    }
+    for (const body of t.bodies) for (const k of canonicalAckKeys(body)) acked.add(k);
   }
   return [...acked];
 }
@@ -279,36 +348,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 +430,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. */

package/app/pollReviewsStale.test.ts

@@ -0,0 +1,187 @@
+// Behavioral regression for the poller's stale-review branch (#799, FM2).
+//
+// `pollReviews` must only resume the convergence loop on a review of the CURRENT head. When the PR
+// HEAD has advanced past the commit the newest review was submitted against, that review is STALE:
+// its advisories describe code the head already moved past. Publishing `readiness-ready` on it would
+// resume the loop on obsolete findings and re-escalate a human on an already-fixed advisory. The
+// poller must instead treat a stale review like "no fresh review" — (re-)solicit and wait — WITHOUT
+// advancing `last_review_id` or emitting the readiness signal.
+//
+// The pure `isReviewStale` predicate and the injected converge-gate already have coverage; this
+// test locks the poller's own STATE TRANSITION (which those cannot), driving the real token-mode
+// transport with a stubbed `fetch` so a differing branch-head SHA vs review `commit_id` is exercised
+// end-to-end. A control with a CURRENT-head review asserts the loop still resumes.
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import { withTrackingViews } from "../test/trackingViews.ts";
+import { READINESS_READY_MESSAGE } from "./readiness.ts";
+import { pollReviews } from "./service.ts";
+
+function memTable(rows: any[], key: string) {
+  return {
+    get: (k: any) => Promise.resolve(rows.find((r) => r[key] === k) ?? null),
+    all: () => Promise.resolve([...rows]),
+    find: (q: any) =>
+      Promise.resolve(rows.filter((r) => Object.entries(q).every(([f, v]) => r[f] === v))),
+    findOne: (q: any) =>
+      Promise.resolve(rows.find((r) => Object.entries(q).every(([f, v]) => r[f] === v)) ?? null),
+    insert: (r: any) => {
+      rows.push(r);
+      return Promise.resolve(r);
+    },
+    update: (k: any, patch: any) => {
+      const r = rows.find((x) => x[key] === k);
+      if (r) Object.assign(r, patch);
+      return Promise.resolve(r);
+    },
+    delete: (k: any) => {
+      for (let i = rows.length - 1; i >= 0; i--) if (rows[i][key] === k) rows.splice(i, 1);
+      return Promise.resolve();
+    },
+  };
+}
+
+const REPO = "owner/repo";
+const NUMBER = 7;
+const HEAD_REF = "feat/x";
+
+/** Stub the token transport for exactly the endpoints the stale-review branch reads:
+ *  - the paged reviews list (one short page → complete),
+ *  - the PR object (for the head ref/repo),
+ *  - the atomic branch ref (`git/ref/heads/<branch>`) the shared reader prefers, and
+ *  - the requested-reviewers GET/POST the re-solicitation nudge uses.
+ * `branchHead` drives staleness: when it differs from the review's `commit_id` the review is stale.
+ * Every non-GET request is recorded in `posts` so a test can assert the nudge's reviewer-request POST
+ * actually fired (a regression that dropped the stale branch's nudge would leave `posts` empty). */
+function reviewFetch(opts: { reviewCommitId: string; branchHead: string; posts: string[] }) {
+  return (url: string | URL | Request, init?: RequestInit): Promise<Response> => {
+    const u = typeof url === "string" ? url : url.toString();
+    const method = (init?.method ?? "GET").toUpperCase();
+    const json = (body: unknown, status = 200) =>
+      Promise.resolve(
+        new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json" } }),
+      );
+    if (u.includes(`/pulls/${NUMBER}/requested_reviewers`)) {
+      if (method !== "GET") {
+        opts.posts.push(`${method} ${u}`);
+        return json({}, 201); // reviewer requested
+      }
+      return json({ users: [] }); // none pending → the nudge proceeds to the POST
+    }
+    if (u.includes(`/pulls/${NUMBER}/reviews`)) {
+      return json([
+        { id: 5, state: "COMMENTED", submitted_at: "2026-09-16T00:45:33Z", commit_id: opts.reviewCommitId },
+      ]);
+    }
+    if (u.includes(`/git/ref/heads/${HEAD_REF}`)) {
+      return json({ object: { sha: opts.branchHead } });
+    }
+    if (u.endsWith(`/pulls/${NUMBER}`)) {
+      return json({ head: { ref: HEAD_REF, sha: opts.branchHead, repo: { full_name: REPO } }, base: { ref: "main" } });
+    }
+    throw new Error(`unexpected fetch: ${method} ${u}`);
+  };
+}
+
+function makeEngine() {
+  const published: Array<{ name: string; correlationKey: string }> = [];
+  const engine = {
+    publishMessage: (m: { name: string; correlationKey: string }) => {
+      published.push({ name: m.name, correlationKey: m.correlationKey });
+      return Promise.resolve();
+    },
+  } as any;
+  return { engine, published };
+}
+
+function withTokenTransport<T>(run: () => Promise<T>): Promise<T> {
+  const prevMode = process.env["NANO_PR_GITHUB_TRANSPORT"];
+  const prevTok = process.env["GITHUB_TOKEN"];
+  process.env["NANO_PR_GITHUB_TRANSPORT"] = "token";
+  process.env["GITHUB_TOKEN"] = "test-token";
+  return run().finally(() => {
+    if (prevMode !== undefined) process.env["NANO_PR_GITHUB_TRANSPORT"] = prevMode;
+    else delete process.env["NANO_PR_GITHUB_TRANSPORT"];
+    if (prevTok !== undefined) process.env["GITHUB_TOKEN"] = prevTok;
+    else delete process.env["GITHUB_TOKEN"];
+  });
+}
+
+function prRow() {
+  return {
+    pr_key: `${REPO}#${NUMBER}`,
+    repo: REPO,
+    number: NUMBER,
+    status: "waiting_review",
+    last_review_id: 0,
+    waiting_since: "2026-09-16T00:00:00Z",
+    // An EXPIRED nudge timestamp so `maybeRerequestReview` does NOT short-circuit at its cooldown —
+    // the stale branch must actually re-solicit a fresh review, and the test asserts that POST fired
+    // (a recent nudge would mask a regression that dropped the nudge entirely, #799 review).
+    last_nudge_at: "2000-01-01T00:00:00Z",
+    updated_at: "t0",
+  };
+}
+
+test("pollReviews: a STALE review (branch head past the review's commit) nudges but does NOT resume the loop", async () => {
+  const row = prRow();
+  const stores: Record<string, { rows: unknown[]; key: string }> = {
+    pull_requests: { rows: [row], key: "pr_key" },
+  };
+  const data = {
+    table: withTrackingViews((name: string, key: string) =>
+      memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key),
+    ),
+  } as any;
+  const { engine, published } = makeEngine();
+  const posts: string[] = [];
+  const prevFetch = globalThis.fetch;
+  await withTokenTransport(async () => {
+    // review was submitted against SHA_OLD, but the branch head has advanced to SHA_NEW → stale.
+    globalThis.fetch = reviewFetch({ reviewCommitId: "SHA_OLD", branchHead: "SHA_NEW", posts }) as typeof fetch;
+    try {
+      await pollReviews(data, engine, "test-token");
+    } finally {
+      globalThis.fetch = prevFetch;
+    }
+  });
+  assertEquals(published.length, 0, "no readiness-ready signal is published for a stale review");
+  assertEquals(row.last_review_id, 0, "last_review_id is NOT advanced past the stale review");
+  assertEquals(row.status, "waiting_review", "the PR stays parked awaiting a fresh review");
+  assertEquals(posts.length, 1, "the stale branch re-solicits a fresh Copilot review (one nudge POST)");
+  assertEquals(
+    posts[0],
+    `POST https://api.github.com/repos/${REPO}/pulls/${NUMBER}/requested_reviewers`,
+    "the nudge POSTs the requested-reviewers endpoint",
+  );
+});
+
+test("pollReviews: a CURRENT-head review (control) resumes the loop and publishes the readiness signal", async () => {
+  const row = prRow();
+  const stores: Record<string, { rows: unknown[]; key: string }> = {
+    pull_requests: { rows: [row], key: "pr_key" },
+  };
+  const data = {
+    table: withTrackingViews((name: string, key: string) =>
+      memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key),
+    ),
+  } as any;
+  const { engine, published } = makeEngine();
+  const posts: string[] = [];
+  const prevFetch = globalThis.fetch;
+  await withTokenTransport(async () => {
+    // review's commit_id equals the current branch head → NOT stale.
+    globalThis.fetch = reviewFetch({ reviewCommitId: "SHA_NEW", branchHead: "SHA_NEW", posts }) as typeof fetch;
+    try {
+      await pollReviews(data, engine, "test-token");
+    } finally {
+      globalThis.fetch = prevFetch;
+    }
+  });
+  assertEquals(published.length, 1, "the readiness-ready signal is published for a fresh review");
+  assertEquals(published[0]?.name, READINESS_READY_MESSAGE);
+  assertEquals(published[0]?.correlationKey, `${REPO}#${NUMBER}`);
+  assertEquals(row.last_review_id, 5, "last_review_id advances to the fresh review");
+  assertEquals(row.status, "converging", "the loop resumes (status flips to converging)");
+  assertEquals(posts.length, 0, "a current-head review resumes directly — no re-solicitation nudge");
+});

package/app/reviewWait.test.ts

@@ -9,6 +9,7 @@ import {
   DEFAULT_REVIEW_NUDGE_MINUTES,
   DEFAULT_REVIEW_WAIT_TIMEOUT,
   isoDurationToMs,
+  isReviewStale,
   MAX_REVIEW_NUDGE_MINUTES,
   reviewWaitTimeout,
 } from "./reviewWait.ts";
@@ -95,3 +96,35 @@ test("clampNudgeMinutes: above the ceiling is clamped, not rejected", () => {
 test("clampNudgeMinutes: an oversized fallback is itself clamped to the ceiling", () => {
   assertEquals(clampNudgeMinutes("", MAX_REVIEW_NUDGE_MINUTES + 50), MAX_REVIEW_NUDGE_MINUTES);
 });
+
+// ── isReviewStale (issue #799) ───────────────────────────────────────────────
+
+test("isReviewStale: differing review commit_id and HEAD sha is stale", () => {
+  assertEquals(isReviewStale("aaa1111", "bbb2222"), true);
+});
+
+test("isReviewStale: matching review commit_id and HEAD sha is NOT stale", () => {
+  assertEquals(isReviewStale("aaa1111", "aaa1111"), false);
+});
+
+test("isReviewStale: surrounding whitespace is ignored in the comparison", () => {
+  assertEquals(isReviewStale("  aaa1111 ", "aaa1111"), false);
+  assertEquals(isReviewStale("aaa1111", " bbb2222  "), true);
+});
+
+test("isReviewStale: a missing review commit_id fails safe to NOT stale", () => {
+  assertEquals(isReviewStale(null, "bbb2222"), false);
+  assertEquals(isReviewStale(undefined, "bbb2222"), false);
+  assertEquals(isReviewStale("", "bbb2222"), false);
+  assertEquals(isReviewStale("   ", "bbb2222"), false);
+});
+
+test("isReviewStale: a missing HEAD sha fails safe to NOT stale", () => {
+  assertEquals(isReviewStale("aaa1111", null), false);
+  assertEquals(isReviewStale("aaa1111", undefined), false);
+  assertEquals(isReviewStale("aaa1111", ""), false);
+});
+
+test("isReviewStale: both missing is NOT stale", () => {
+  assertEquals(isReviewStale(null, null), false);
+});

package/app/reviewWait.ts

@@ -93,3 +93,24 @@ export function clampNudgeMinutes(
   if (i < 1) return safeFallback;
   return Math.min(i, MAX_REVIEW_NUDGE_MINUTES);
 }
+
+/** Is the latest Copilot review STALE relative to the PR's current HEAD? (issue #799)
+ *
+ * A review is stale when it was submitted against a commit the head has since moved past — its
+ * advisories describe code that no longer exists, so the convergence gate must NOT block/escalate
+ * against it and the poller must NOT unpark the loop on it; instead a fresh review of the current
+ * HEAD must be solicited and gated on. Staleness is a plain SHA inequality.
+ *
+ * Fails SAFE to "not stale" when either SHA is unknown (`null`/`undefined`/blank): GitHub did not
+ * carry a `commit_id` for the review, or the head could not be read. Without both SHAs we cannot
+ * prove the review predates the head, so we must not fabricate a stale verdict that would loop the
+ * loop re-soliciting forever — the review-wait timeout and the round cap remain the safety nets. */
+export function isReviewStale(
+  reviewCommitId: string | null | undefined,
+  headSha: string | null | undefined,
+): boolean {
+  const rev = (reviewCommitId ?? "").trim();
+  const head = (headSha ?? "").trim();
+  if (rev === "" || head === "") return false;
+  return rev !== head;
+}