@nanobpm/nano-workforce 0.187.4 → 0.187.6

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [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
+
+* **convergence:** classify husked review rounds and bound-retry the no-progress loop ([#789](https://github.com/nanobpm/nano-workforce/issues/789)) ([faebcdc](https://github.com/nanobpm/nano-workforce/commit/faebcdcaca017fab8d7436a50e3dc09354dc3022)), closes [jwulf/c8ctl-plugin-nano#230](https://github.com/jwulf/c8ctl-plugin-nano/issues/230) [#786](https://github.com/nanobpm/nano-workforce/issues/786) [#786](https://github.com/nanobpm/nano-workforce/issues/786)
+
 ## [0.187.4](https://github.com/nanobpm/nano-workforce/compare/v0.187.3...v0.187.4) (2026-09-14)
 
 ### Bug Fixes

package/SPEC.md

@@ -101,11 +101,17 @@ known at submit time, carried as a process variable and stored on the DB row.
 │    <gateway: status>
 │      ├── converged  → [Mark converged] → (end: converged)
 │      │
-│      ├── addressed  → [Record round] → <event-based gateway: review ready or timeout?>
-│      │                     ├── readiness-ready (msg catch, key = prKey) → round++ ─┐
-│      │                     └── =reviewWaitTimeout (timer catch)                     │
-│      │                          → [Escalate: review stalled] (blocked)              │
-│      │                          → [Wait: wait-answer userTask] ─────────────────────┤
+│      ├── addressed  → [Record round] → [Check progress] (did the PR head advance?)
+│      │                   ├── progressed → <guard: round ≥ maxRounds → escalate "not converged"> │
+│      │                   │                   → <event-based gateway: review ready or timeout?>   │
+│      │                   │      ├── readiness-ready (msg catch, key = prKey) → round++ ─┐
+│      │                   │      └── =reviewWaitTimeout (timer catch)                    │
+│      │                   │           → [Escalate: review stalled] (blocked)             │
+│      │                   │           → [Wait: wait-answer userTask] ────────────────────┤
+│      │                   └── no progress → <husk? no commit AND no terminal instance>   │
+│      │                          ├── husk & retries < MAX → re-enter [Review round] (bypasses the round-cap guard) │
+│      │                          └── no-advance / husk cap → [Escalate: no progress]      │
+│      │                                     → [Wait: wait-answer userTask] ───────────────────┤
 │      │                                                                             │
 │      └── needs_input     [Record escalation]                       │               │
 │          or blocked  →   (kind = question | blocker)               │               │
@@ -124,11 +130,38 @@ step, then retry the same round with the human's `answer`. They differ only by e
 which the UI uses to label the card. Neither ends the run — a human always gets
 a chance to unblock and resume.
 
-Guard: before each Review round, if round > MAX_ROUNDS → force an escalation
-("not converged after N rounds") so a human decides, rather than looping forever.
+Guard: after progress classification, a **progressing** round with round ≥
+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)
@@ -149,6 +182,59 @@ Notes:
   backstop when even repeated nudges fail.
 - On `needs_input`, the same `round` is retried after the answer (the answer is
   added to the agent's context; the round number does not advance).
+- **No-progress guard + husk classification (issue #786).** Before the review
+  wait, an `addressed` round passes through `pr.progress-check`
+  (`workers/progress-check/worker.ts`, mirrored by `app/roundProgress.ts`): it
+  reads the PR's current head SHA (the branch ref, atomic with the push) and
+  compares it to the **round-entry head** — the head captured by `pr.capture-head`
+  immediately BEFORE `review-round` ran this round, published as the
+  `roundEntryHead` process variable. `pr.capture-head` sits on EVERY entry into
+  `review-round` (the first round from `Start`, a review-loop re-enter, a
+  human-answer resume, and a husk auto-retry), so within any round there is always
+  a baseline captured against the agent's own starting point — closing the
+  no-baseline gap where a FIRST addressed round had no prior-round head to compare
+  against (and either waved a first-round husk through as progress, or risked
+  mis-escalating a straggler push). If `roundEntryHead` is absent — an older
+  in-flight instance whose flow predates `capture-head`, or a capture read that
+  failed open (it publishes the empty string as its "unknown" sentinel) —
+  progress-check falls back to the head persisted from the previous round
+  (`last_round_head`). A round whose head DID advance past the round-entry baseline
+  is real progress and continues to the review-wait gateway. A round whose head did
+  NOT advance pushed no commit, so re-requesting a review would loop on
+  byte-identical code; `gw-progress` routes it to `gw-husk`, which SPLITS it on a
+  corroboration correlated to the COMPLETING `review-round` element-instance (NOT
+  an aggregate terminal count — a same-round human-answered resume is classified on
+  its own fresh attempt):
+    - a **husk** — no commit AND the completing `review-round` attempt is
+      NON-TERMINAL (the producer harness died mid-run, leaving a stuck instance) —
+      is auto-re-run onto a healthy worker up to `MAX_HUSK_RETRIES` (2) before
+      escalating; and
+    - a **no-advance** — the completing attempt ran to a terminal instance but
+      nothing was pushed — (and a husk that exhausts its retries) escalates to the
+      human `wait-answer` task.
+  The agent-instance read is AVAILABILITY-AWARE via a **two-tier probe** and fails
+  SAFE (ADR 0056). `review-round` is an external-agent service task, so a job that
+  husks BEFORE it ever registers an AgentInstance leaves the scoped `review-round`
+  search EMPTY — indistinguishable, on that query alone, from an engine that has no
+  AgentInstance projection at all. The probe therefore resolves an empty
+  `review-round` search against a SECOND, process-wide read:
+    - if the process-wide read also finds NO instance, the **channel is absent**
+      (an engine with no AgentInstance projection) — UNKNOWN, treated as no-advance,
+      never an auto-retry that could duplicate genuinely-completed work;
+    - if the process-wide read finds ANOTHER instance (from `classify-scope`, an
+      earlier round, etc.), the **channel is PRESENT** but this round registered
+      nothing — a genuine **pre-registration husk**, so it is classified as a husk
+      and auto-retried.
+  A head that cannot be read fails OPEN (continue), so a transient GitHub hiccup
+  never fabricates a no-progress escalation. Two supporting invariants keep an
+  auto-retry clean: `pr.persist-round`
+  records a round IDEMPOTENTLY on `(pr_key, round_no, process_instance_key)` — a husk
+  retry (same process instance) updates its row in place, while a resubmission that
+  re-opens the PR at round 1 in a NEW process instance inserts a fresh row and so
+  never clobbers a prior run's durable round history (migration 102) — and the guard flips the PR back to
+  the running `converging` status before a retry re-enters `review-round` so the
+  poller does not solicit a spurious review against the still-running round. The
+  round cap and the review-wait timeout remain the outer safety nets.
 
 
 ## 5. Agent job contract (`senior:pr-review`)

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/convergenceEscalationGuard.test.ts

@@ -19,7 +19,8 @@
 //
 // The fix (mirroring the merge loop's `gw-merge-escalated`, PR #331): route EVERY arm that can reach
 // `wait-answer` through the single `gw-escalated` guard, so a `persist-escalation` returning
-// `escalated:false` RE-ENTERS the loop (`gw-guard`) instead of parking a dead wait. This makes the
+// `escalated:false` RE-ENTERS the loop (round processing, `persist-round`) instead of parking a dead
+// wait. This makes the
 // invariant structural — `wait-answer` is reachable ONLY from a `gw-escalated == true` edge, so a
 // "durable answer-wait with no escalation" is unrepresentable.
 //
@@ -77,7 +78,7 @@ test("gw-escalated honours persist-escalation's escalated output for every arm",
   assertStringIncludes(escWait![0], "escalated = true", "the wait arm must be guarded by escalated = true");
   // escalated:false (a non-escalation, e.g. a blank convergeBlockReason) → re-enter the loop, not a dead wait.
   assert(gatewayDefault("gw-escalated", "f_escReenter"), "gw-escalated default must re-enter the loop");
-  assert(flowHasId("f_escReenter", "gw-escalated", "gw-guard"), "the non-escalation arm must re-enter via gw-guard, not park a wait");
+  assert(flowHasId("f_escReenter", "gw-escalated", "persist-round"), "the non-escalation arm must re-enter round processing (persist-round), not park a wait");
 });
 
 test("wait-answer is reachable ONLY from the gw-escalated == true edge (structural invariant)", () => {

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, fetchIssueTitle, fetchPrFiles, 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,
@@ -723,3 +787,127 @@ test("checkConclusions: in-flight runs map to '' for both CheckRun and StatusCon
     "legacy-error": "ERROR",
   });
 });
+
+// ── fetchBranchHead — the atomic branch-ref reader (issue #786) ──────────────
+//
+// The no-progress guard reads the branch ref (git/ref/heads/<branch>), updated ATOMICALLY with the
+// push, rather than the PR object's asynchronously-denormalized head.sha, so a lagging PR projection
+// can never fabricate a stale-but-valid no-advance escalation. Force the token transport and stub
+// `globalThis.fetch` to serve the git-ref endpoint.
+async function withRefFetch<T>(
+  serve: (path: string) => { status: number; body: unknown },
+  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 = ((url: string | URL | Request): Promise<Response> => {
+    const path = new URL(String(url)).pathname.replace(/^\/repos\//, "");
+    const { status, body } = serve(path);
+    return Promise.resolve(new Response(JSON.stringify(body), { status }));
+  }) 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("fetchBranchHead: returns the branch ref's atomic head SHA", async () => {
+  const sha = await withRefFetch(
+    (path) => {
+      assertEquals(path, "o/r/git/ref/heads/feat/x");
+      return { status: 200, body: { object: { sha: "deadbeef" } } };
+    },
+    () => fetchBranchHead("o/r", "feat/x", "tok"),
+  );
+  assertEquals(sha, "deadbeef");
+});
+
+test("fetchBranchHead: a 404 (branch absent) resolves to null, never throws", async () => {
+  const sha = await withRefFetch(
+    () => ({ status: 404, body: { message: "Not Found" } }),
+    () => fetchBranchHead("o/r", "feat/missing", "tok"),
+  );
+  assertEquals(sha, null);
+});
+
+test("fetchBranchHead: no usable transport (token mode, empty token) resolves to null, never throws", async () => {
+  // The documented contract promises `null` when no transport is usable, matching fetchPrHead /
+  // fetchPrBase — a missing token under the token transport must not surface an exception to callers
+  // relying on the Promise<string | null> shape.
+  const prevMode = process.env["NANO_PR_GITHUB_TRANSPORT"];
+  process.env["NANO_PR_GITHUB_TRANSPORT"] = "token";
+  try {
+    const sha = await fetchBranchHead("o/r", "feat/x", "");
+    assertEquals(sha, null);
+  } finally {
+    if (prevMode === undefined) delete process.env["NANO_PR_GITHUB_TRANSPORT"];
+    else process.env["NANO_PR_GITHUB_TRANSPORT"] = prevMode;
+  }
+});
+
+// ── fetchPrHead — the PR head reader surfaces the head branch's OWNING repo (issue #786) ─────
+//
+// The no-progress head reader resolves the head ref in `headRepo`, so a cross-repo (fork) PR reads
+// the fork's ref, not a same-named branch in the base repo (which would resolve to an unrelated
+// SHA). These assert the transport-level mapping of the source repository through `fetchPrHead`'s
+// REST branch (forced via the token transport), which the handler-level tests — injecting an
+// already-parsed `{ headRepo }` — do not exercise.
+test("fetchPrHead: REST maps head.repo.full_name to the fork's source repository", async () => {
+  const head = await withRefFetch(
+    (path) => {
+      assertEquals(path, "base/repo/pulls/789");
+      return {
+        status: 200,
+        body: {
+          head: { ref: "feat/x", sha: "cafef00d", repo: { full_name: "fork-owner/repo" } },
+          base: { ref: "main" },
+        },
+      };
+    },
+    () => fetchPrHead("base/repo", 789, "tok"),
+  );
+  assertEquals(head, { headRef: "feat/x", headSha: "cafef00d", baseRef: "main", headRepo: "fork-owner/repo" });
+});
+
+test("fetchPrHead: REST fails open to headRepo=null when the head repo is absent (deleted fork)", async () => {
+  const head = await withRefFetch(
+    () => ({
+      status: 200,
+      body: { head: { ref: "feat/x", sha: "cafef00d", repo: null }, base: { ref: "main" } },
+    }),
+    () => fetchPrHead("base/repo", 789, "tok"),
+  );
+  // A null head repo must surface as headRepo=null (the reader then fails open), never the base repo.
+  assertEquals(head?.headRepo, null);
+});
+
+test("fetchPrHead: no usable transport (token mode, empty token) resolves to null, never throws", async () => {
+  const prevMode = process.env["NANO_PR_GITHUB_TRANSPORT"];
+  process.env["NANO_PR_GITHUB_TRANSPORT"] = "token";
+  try {
+    const head = await fetchPrHead("o/r", 1, "");
+    assertEquals(head, null);
+  } finally {
+    if (prevMode === undefined) delete process.env["NANO_PR_GITHUB_TRANSPORT"];
+    else process.env["NANO_PR_GITHUB_TRANSPORT"] = prevMode;
+  }
+});
+
+// A branch name may legally contain `#`, `?`, or spaces. The reader must percent-encode each ref
+// SEGMENT (preserving `/`) before building the API path/URL — otherwise a `#` starts a URL fragment,
+// the path is truncated to the wrong ref, and the no-progress guard fails open (issue #786).
+test("fetchBranchHead: percent-encodes a special-character branch ref (preserving '/')", async () => {
+  const sha = await withRefFetch(
+    (path) => {
+      // The `#` must survive as %23 inside the path, not truncate it into a URL fragment.
+      assertEquals(path, "o/r/git/ref/heads/feat/x%23123");
+      return { status: 200, body: { object: { sha: "cafef00d" } } };
+    },
+    () => fetchBranchHead("o/r", "feat/x#123", "tok"),
+  );
+  assertEquals(sha, "cafef00d");
+});