@nanobpm/nano-workforce 0.205.1 → 0.206.0

package/.github/workflows/release.yml

@@ -197,8 +197,11 @@ jobs:
       # token, still OIDC + provenance via the job's id-token. This step is a NO-OP
       # when the release step succeeded or when the version is already on npm, so it
       # can never double-publish. If OIDC stays down through every retry, fail loudly:
-      # a human must `npm publish` the pushed tag locally (npm login with 2FA, then
-      # `git checkout vX.Y.Z && npm ci && npm publish --provenance --access public`).
+      # a human must `npm publish` the pushed tag locally — restoring the build identity first,
+      # because a fresh tag checkout has no build-info.json and plain `npm publish` skips the
+      # prepare hook (npm login with 2FA, then `git checkout vX.Y.Z && npm ci &&
+      # node --experimental-strip-types scripts/write-build-info.ts X.Y.Z --sha "$(git rev-parse
+      # vX.Y.Z^)" && npm publish --provenance --access public`; see the ::error:: message below).
       - name: Retry OIDC publish if the release publish failed
         if: steps.release.outcome == 'failure'
         env:
@@ -213,6 +216,18 @@ jobs:
             exit 0
           fi
           echo "semantic-release prepared + tagged ${PKG}@${VERSION} but the OIDC publish failed; retrying."
+          # Reuse the build-info.json that semantic-release's prepare step already wrote (prepareCmd
+          # in .releaserc.json) — do NOT regenerate it here. By the time this retry runs,
+          # @semantic-release/git has already created the release commit, so HEAD is that
+          # metadata-only `chore(release)` commit, NOT the source HEAD the release was cut from.
+          # Re-running write-build-info.ts would call `git rev-parse HEAD` and overwrite the recorded
+          # source SHA with the release commit's SHA (and replace builtAt), making the documented
+          # identity depend on whether OIDC publishing failed. The prepared file is already present
+          # in this checkout with the correct source HEAD; this step re-packs via plain `npm publish`
+          # (which runs OUTSIDE semantic-release, so the prepare hook does not re-run), so the baked
+          # file is packed as-is. Validate it is present and well-formed (fail loudly if a future
+          # change ever drops it) rather than regenerate it from the changed HEAD (issue #925).
+          node --experimental-strip-types scripts/write-build-info.ts --check
           published=false
           for attempt in 1 2 3; do
             echo "OIDC publish attempt ${attempt}/3 for ${PKG}@${VERSION}"
@@ -224,7 +239,7 @@ jobs:
             sleep $((attempt * 30))
           done
           if [ "$published" != true ]; then
-            echo "::error::OIDC publish of ${PKG}@${VERSION} still failing after retries. The git tag v${VERSION} is pushed but npm has no tarball. Publish it locally: 'git fetch --tags && git checkout v${VERSION} && npm ci && npm publish --provenance --access public' (npm login with 2FA first)."
+            echo "::error::OIDC publish of ${PKG}@${VERSION} still failing after retries. The git tag v${VERSION} is pushed but npm has no tarball. Publish it locally (npm login with 2FA first): 'git fetch --tags && git checkout v${VERSION} && npm ci && node --experimental-strip-types scripts/write-build-info.ts ${VERSION} --sha \"\$(git rev-parse v${VERSION}^)\" && node --experimental-strip-types scripts/write-build-info.ts --check && npm publish --provenance --access public'. The write-build-info step is REQUIRED: a fresh tag checkout has no build-info.json (it is an uncommitted build artifact) and plain npm publish does not run the semantic-release prepare hook, so without it the package ships with gitSha: null. Passing --sha \"\$(git rev-parse v${VERSION}^)\" records the SOURCE HEAD (the tag's parent), not the metadata-only release commit the tag points at."
             exit 1
           fi
           # semantic-release aborts before @semantic-release/github when the npm

package/.releaserc.json

@@ -40,6 +40,13 @@
     "@semantic-release/changelog",
     "@semantic-release/npm",
     "@semantic-release/github",
+    [
+      "@semantic-release/exec",
+      {
+        "//": "Bake the build identity into the package (issue #925). prepareCmd runs in semantic-release's prepare step — AFTER @semantic-release/npm bumps package.json to ${nextRelease.version} and BEFORE it packs/publishes the tarball — so the published package ships build-info.json and an npm-installed instance (no .git, no env override) can still report its gitSha. The recorded gitSha is the SOURCE HEAD the release is cut from; the tag commit is created afterwards by @semantic-release/git (see scripts/write-build-info.ts). There is deliberately NO verifyConditionsCmd: semantic-release runs verifyConditions BEFORE it computes nextRelease, so ${nextRelease.version} interpolates empty there and the command would fail with EVERIFYCONDITIONS, blocking every release. The workflow's OIDC-retry step re-runs plain `npm publish` (which re-packs) in the same checkout — where prepare already wrote build-info.json — and validates + reuses that prepared file (it does NOT regenerate it: by then HEAD is the release commit, so re-running the writer would overwrite the source SHA with the release commit's SHA; see release.yml), so the retry never publishes a tarball with no or wrong build-info.json.",
+        "prepareCmd": "node --experimental-strip-types scripts/write-build-info.ts ${nextRelease.version}"
+      }
+    ],
     [
       "@semantic-release/git",
       {

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.206.0](https://github.com/nanobpm/nano-workforce/compare/v0.205.2...v0.206.0) (2026-11-08)
+
+### Features
+
+* **version:** bake the git SHA into release packages and report identity on /status ([#926](https://github.com/nanobpm/nano-workforce/issues/926)) ([e5eedca](https://github.com/nanobpm/nano-workforce/commit/e5eedca0ee28db1f54167b4bb962ce4c06776e9f)), closes [#925](https://github.com/nanobpm/nano-workforce/issues/925) [#925](https://github.com/nanobpm/nano-workforce/issues/925) [#925](https://github.com/nanobpm/nano-workforce/issues/925) [#925](https://github.com/nanobpm/nano-workforce/issues/925)
+
+## [0.205.2](https://github.com/nanobpm/nano-workforce/compare/v0.205.1...v0.205.2) (2026-11-08)
+
+### Bug Fixes
+
+* **convergence:** fail closed when no head-current Copilot review exists ([#924](https://github.com/nanobpm/nano-workforce/issues/924)) ([e0ded57](https://github.com/nanobpm/nano-workforce/commit/e0ded57e0888755fa6fd77495f3361e8dafc0980)), closes [#923](https://github.com/nanobpm/nano-workforce/issues/923) [nano-bpm#1443](https://github.com/nanobpm/nano-bpm/issues/1443) [#923](https://github.com/nanobpm/nano-workforce/issues/923) [#923](https://github.com/nanobpm/nano-workforce/issues/923) [#923](https://github.com/nanobpm/nano-workforce/issues/923) [#923](https://github.com/nanobpm/nano-workforce/issues/923)
+
 ## [0.205.1](https://github.com/nanobpm/nano-workforce/compare/v0.205.0...v0.205.1) (2026-11-06)
 
 ### Bug Fixes

package/app/contracts.ts

@@ -301,7 +301,7 @@ export const ENV_CONTRACTS = {
     name: "NANO_WORKFORCE_GIT_SHA",
     owner: "app/version.ts",
     semantics:
-      "Explicit git SHA override for version reporting on deploys shipped without a .git directory; version derivation reads .git when unset.",
+      "Explicit git SHA override for version reporting on deploys shipped without a .git directory; version derivation reads .git when unset, then falls back to the release-baked build-info.json (issue #925).",
   },
   NANO_AUTO_RETRO: {
     category: "env",

package/app/convergeAdversarial.test.ts

@@ -292,3 +292,57 @@ test("the pass budget resets when the next review lands (new round)", async () =
   // Round 2 gets its own full budget of 1 pass.
   assert(completions(engine, "adversarial-review") === 2, `round 2 must get a fresh pass: ${runs(engine)}`);
 });
+
+// Issue #923 §4 (behavioural, not substring): a `converged` agent verdict with NO head-current review
+// makes the converge-gate report `reviewStale`; the loop must record the round as `review-stale`
+// (not the agent's self-reported `converged`) and park for a fresh review — never reaching
+// `persist-converged`.
+test("#923: a stale converge-gate verdict persists the round as review-stale and parks without converging", async () => {
+  const { engine, seen } = await boot({
+    responses: {
+      "senior:pr-review": [{ status: "converged", summary: "done" }, { status: "waiting", summary: "awaiting" }],
+      "pr.converge-gate": {
+        convergeBlocked: false,
+        convergeBlockReason: "",
+        convergeAckOnly: false,
+        reviewStale: true,
+      },
+    },
+    vars: { advMax: 0 },
+  });
+  assertThatInstance(engine, byProcessId("convergence-loop")).isActive().hasNoIncident();
+  assert(completions(engine, "persist-converged") === 0, `must not converge on a stale review: ${runs(engine)}`);
+  const recorded = seen["pr.persist-round"][0];
+  assert(recorded?.status === "review-stale", `persist-round status: ${JSON.stringify(recorded?.status)}`);
+  assert(completions(engine, "wait-review") === 0, "must be parked waiting for a fresh review");
+});
+
+// Issue #923 review ("previously missed", behavioural): the arrival-window cutoff the converge-gate
+// emits on a stale verdict must PROPAGATE through the process to the check-progress park — the
+// variable crosses persist-round untouched, so check-progress can stamp `waiting_since` at the
+// gate's read time (not the later park time) and a head-current review landing in the read→park
+// window still satisfies the wait. This is the process-level wiring the worker unit tests cannot
+// see (each worker is tested in isolation with an injected variable).
+test("#923 review: the converge-gate's reviewWaitCutoff reaches check-progress on a stale verdict", async () => {
+  const CUTOFF = "2026-11-08T01:00:00.000Z";
+  const { engine, seen } = await boot({
+    responses: {
+      "senior:pr-review": [{ status: "converged", summary: "done" }, { status: "waiting", summary: "awaiting" }],
+      "pr.converge-gate": {
+        convergeBlocked: false,
+        convergeBlockReason: "",
+        convergeAckOnly: false,
+        reviewStale: true,
+        reviewWaitCutoff: CUTOFF,
+      },
+    },
+    vars: { advMax: 0 },
+  });
+  assertThatInstance(engine, byProcessId("convergence-loop")).isActive().hasNoIncident();
+  const progressJobs = seen["pr.progress-check"];
+  assert(progressJobs.length >= 1, "check-progress ran");
+  assert(
+    progressJobs[0]?.reviewWaitCutoff === CUTOFF,
+    `check-progress must receive the gate's reviewWaitCutoff, got ${JSON.stringify(progressJobs[0]?.reviewWaitCutoff)}`,
+  );
+});

package/app/convergeGate.test.ts

@@ -17,6 +17,7 @@ import {
   advisoryStableKey,
   isAckThread,
   parseAckedAdvisories,
+  parseReviewOpenFindings,
   parseReviewThreadsPage,
   parseSuppressedAdvisories,
   pickLatestCopilotReview,
@@ -820,7 +821,11 @@ test("converge-gate #799: a STALE review (commit_id predates HEAD) does not bloc
     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: "", convergeAckOnly: false, reviewStale: true });
+  assertEquals(out.convergeBlocked, false);
+  assertEquals(out.reviewStale, true);
+  // The gate stamps the review-wait cutoff (the time of ITS review read) so a head-current review
+  // landing in the read→park window still satisfies the wait (issue #923 review).
+  assertEquals(typeof out.reviewWaitCutoff, "string");
 });
 
 test("converge-gate #799: a HEAD-CURRENT review still blocks on an unacked advisory (control)", async () => {
@@ -838,9 +843,14 @@ test("converge-gate #799: a HEAD-CURRENT review still blocks on an unacked advis
   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.
+test("converge-gate #799/#923: a review commit_id GitHub did not carry is treated as MISSING — re-solicits (no fail-open)", async () => {
+  // #799's fail-safe ("a null review commit_id is not stale") was written for a gate that only
+  // handled a review that EXISTS. #923 closes the class: a null commit_id is ambiguous between "no
+  // review at all" and "a review GitHub carried no commit_id for", and the gate cannot distinguish
+  // them — converging on either is converging without a verifiable head-current verdict (the
+  // #1443 fail-open). With a readable head the gate now signals reviewStale for BOTH, so the
+  // poller re-solicits a review whose commit_id IS carried, un-wedging the loop. The head-side
+  // fail-safe is unchanged: an unreadable head still evaluates normally (see the #923 test below).
   const handler = await makeUnderTest({
     readThreads: async () => [],
     readReviewBody: async () => SAMPLE_REVIEW_BODY,
@@ -848,8 +858,66 @@ test("converge-gate #799: an unknown review commit_id or unreadable HEAD is NOT
     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);
+  assertEquals(out.convergeBlocked, false);
+  assertEquals(out.reviewStale, true);
+  // The gate stamps the review-wait cutoff (the time of ITS review read) so a head-current review
+  // landing in the read→park window still satisfies the wait (issue #923 review).
+  assertEquals(typeof out.reviewWaitCutoff, "string");
+});
+
+// ── Fail closed on "no review exists" (issue #923 §1) ────────────────────────
+// The gate used to treat `{ body: "", commitId: null }` — a VERIFIED "no Copilot review on this
+// PR" — as "a verified clean review": zero threads + zero advisories → not blocked → merged with
+// ZERO reviews (nano-bpm#1443). Convergence requires a HEAD-CURRENT reviewer verdict, so a missing
+// review must signal `reviewStale` and route to the review wait (the poller solicits a review of
+// the head), exactly like a stale one.
+
+test("converge-gate #923: NO Copilot review at all signals reviewStale (never converges unreviewed)", async () => {
+  // `readReview` returns `{ body: "", commitId: null }` (verified: no Copilot review) and the head
+  // read succeeds. The old gate fell through as the most permissive case and converged.
+  const handler = await makeUnderTest({
+    readThreads: async () => [],
+    readReviewBody: async () => "",
+    reviewCommitId: null,
+    headSha: "headsha4444444444444444444444444444444444",
+  });
+  const out = await handler({ variables: { prKey: "o/r#1", repo: "o/r", prNumber: 1 } } as any, {} as any);
+  assertEquals(out.convergeBlocked, false);
+  assertEquals(out.reviewStale, true);
+  // The gate stamps the review-wait cutoff (the time of ITS review read) so a head-current review
+  // landing in the read→park window still satisfies the wait (issue #923 review).
+  assertEquals(typeof out.reviewWaitCutoff, "string");
+});
+
+test("converge-gate #923: a review GitHub carried no commit_id for is ALSO treated as missing (fail closed)", async () => {
+  // A null commit_id is ambiguous — "no review" vs "a review with no commit_id" — and the gate
+  // cannot distinguish them, so BOTH must take the re-solicit path. Converging on an unverifiable
+  // verdict is the fail-open this issue closes; the re-solicit produces a review whose commit_id
+  // IS carried, un-wedging the loop.
+  const handler = await makeUnderTest({
+    readThreads: async () => [],
+    readReviewBody: async () => "## Overview\nNo suppressed block.",
+    reviewCommitId: null,
+    headSha: "headsha4444444444444444444444444444444444",
+  });
+  const out = await handler({ variables: { prKey: "o/r#1", repo: "o/r", prNumber: 1 } } as any, {} as any);
+  assertEquals(out.reviewStale, true);
+  assertEquals(out.convergeBlocked, false);
+});
+
+test("converge-gate #923: a missing review with an UNREADABLE head still fails safe (no fabricated re-solicit)", async () => {
+  // Without the head we cannot prove anything — the gate keeps `isReviewStale`'s fail-safe and
+  // falls through to the ordinary evaluation (here: a clean empty review converges). A transport
+  // hiccup must never strand the loop re-soliciting forever; the review-wait timeout is the
+  // backstop.
+  const handler = await makeUnderTest({
+    readThreads: async () => [],
+    readReviewBody: async () => "",
+    reviewCommitId: null,
+    headSha: null,
+  });
+  const out = await handler({ variables: { prKey: "o/r#1", repo: "o/r", prNumber: 1 } } as any, {} as any);
+  assertEquals(out, { convergeBlocked: false, convergeBlockReason: "", convergeAckOnly: false, reviewStale: false });
 });
 
 // ── Structural guard over the committed BPMN (no engine) ─────────────────────
@@ -971,6 +1039,20 @@ test("the round cap does NOT escalate a stale-retry round — f_guardMax is gate
   assertStringIncludes(f, "maxRounds and reviewStale != true");
 });
 
+test("persist-round records a stale re-entry as 'review-stale', not the agent's self-report (#923 §4)", () => {
+  // Round accounting must reflect whether a reviewer verdict was obtained: a round that re-enters
+  // persist-round via f_convergeStale (no head-current review existed, or it predated the head)
+  // never received a verdict, so recording the agent's self-reported status ("converged") would
+  // tell the operator a review round happened that never did (/status showed nano-bpm#1443 as
+  // "round 2" with zero reviews). The stale re-entry maps `status` from `reviewStale` so the
+  // durable round history reads `review-stale`.
+  const task = flat.match(/<bpmn:serviceTask\b[^>]*\bid="persist-round"[^>]*>.*?<\/bpmn:serviceTask>/);
+  assert(task, "persist-round task missing");
+  assertStringIncludes(task[0], 'target="status"');
+  assertStringIncludes(task[0], "reviewStale");
+  assertStringIncludes(task[0], "review-stale");
+});
+
 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
@@ -1196,3 +1278,101 @@ test("parseSuppressedAdvisories: v2 table rows without findings yield nothing; n
   );
   assertEquals(parseSuppressedAdvisories("| `a.ts` | Broken thing (moderate, 1 vote). |"), []);
 });
+
+// ── The reviewer-verdict gate (issue #923 §2) ────────────────────────────────
+// Convergence requires a head-current reviewer VERDICT, not just zero unresolved threads: a
+// head-current review whose own summary reports open findings must block the same way an
+// unresolved thread does. `parseReviewOpenFindings` reads that verdict out of the review body
+// (Copilot's "Changes recommended" / "N open issue(s)" / ccr-overview-v2 "Open (N)" section).
+
+test("parseReviewOpenFindings: a 'Changes recommended' review reports open findings", () => {
+  const body = "## Pull Request Overview\n🟡 Changes recommended — 7 findings (6 high).";
+  assertEquals(parseReviewOpenFindings(body), ["changes recommended"]);
+});
+
+test("parseReviewOpenFindings: an 'N open issue(s)' summary reports N", () => {
+  assertEquals(
+    parseReviewOpenFindings("<details open>\n<summary><strong>3 open issues</strong></summary>\n</details>"),
+    ["3 open issues"],
+  );
+  assertEquals(parseReviewOpenFindings("<summary>1 open issue</summary>"), ["1 open issue"]);
+});
+
+test("parseReviewOpenFindings: '0 open issues' is a clean verdict, not a finding", () => {
+  assertEquals(parseReviewOpenFindings("Review complete. 0 open issues."), []);
+  assertEquals(parseReviewOpenFindings("<details><summary><strong>0 open issues</strong></summary></details>"), []);
+});
+
+test("parseReviewOpenFindings: a ccr-overview-v2 'Open (N)' section reports N", () => {
+  assertEquals(parseReviewOpenFindings(V2_REVIEW_BODY), ["1 open finding"]);
+});
+
+test("parseReviewOpenFindings: a clean review (no open-issues signal) reports none", () => {
+  assertEquals(parseReviewOpenFindings("## Pull Request Overview\n✅ Looks good — no issues found."), []);
+  assertEquals(parseReviewOpenFindings(""), []);
+  assertEquals(parseReviewOpenFindings(null), []);
+  assertEquals(parseReviewOpenFindings(undefined), []);
+});
+
+test("parseReviewOpenFindings: verdict phrases in descriptive prose / table rows are NOT findings", () => {
+  const clean = [
+    "<!-- ccr-overview-v2 -->",
+    "",
+    "### ✅ Looks good",
+    "",
+    "<details>",
+    "<summary><strong>What changed in this PR</strong></summary>",
+    "",
+    "| File | Summary and final review notes |",
+    "|---|---|",
+    '| `a.ts` | Recognizes "Changes recommended" and counts 3 open issues; parses Open (2) sections. |',
+    "</details>",
+    "<summary>Notes</summary> then later Open (4) outside any summary",
+  ].join("\n");
+  assertEquals(parseReviewOpenFindings(clean), []);
+});
+
+test("parseReviewOpenFindings: a v2 overview with NO Open section reports none", () => {
+  const clean = [
+    "<!-- ccr-overview-v2 -->",
+    "",
+    "## Copilot review overview",
+    "",
+    "<details>",
+    "<summary><strong>What changed in this PR</strong></summary>",
+    "",
+    "| File | Summary and final review notes |",
+    "|---|---|",
+    "| `a.ts` | Adds a thing. |",
+    "</details>",
+  ].join("\n");
+  assertEquals(parseReviewOpenFindings(clean), []);
+});
+
+test("converge-gate #923: a head-current review whose body reports OPEN ISSUES blocks (verdict gate, no threads)", async () => {
+  // The verdict gate: zero unresolved threads and no suppressed advisories, but the head-current
+  // review's own summary says findings are open. This must block EXACTLY like an unresolved
+  // thread — NOT ack-only (the round agent's code/reply work is needed, not a nano-ack repost).
+  const handler = await makeUnderTest({
+    readThreads: async () => [],
+    readReviewBody: async () => "## Pull Request Overview\n🟡 Changes recommended — 7 findings (6 high).",
+    reviewCommitId: "headsha4444444444444444444444444444444444",
+    headSha: "headsha4444444444444444444444444444444444",
+  });
+  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);
+  assertEquals(out.convergeAckOnly, false);
+  assertStringIncludes(out.convergeBlockReason ?? "", "changes recommended");
+});
+
+test("converge-gate #923: a head-current CLEAN review with no findings still converges (verdict-gate control)", async () => {
+  const handler = await makeUnderTest({
+    readThreads: async () => [],
+    readReviewBody: async () => "## Pull Request Overview\n✅ Looks good — no issues found.",
+    reviewCommitId: "headsha4444444444444444444444444444444444",
+    headSha: "headsha4444444444444444444444444444444444",
+  });
+  const out = await handler({ variables: { prKey: "o/r#1", repo: "o/r", prNumber: 1 } } as any, {} as any);
+  assertEquals(out, { convergeBlocked: false, convergeBlockReason: "", convergeAckOnly: false, reviewStale: false });
+});

package/app/github.ts

@@ -290,6 +290,37 @@ export function parseSuppressedAdvisories(reviewBody: string | null | undefined)
   return out;
 }
 
+/** Read the reviewer VERDICT out of a Copilot review body (issue #923 §2): does the review's own
+ * summary report OPEN, actionable findings? Convergence requires a head-current verdict that is
+ * CLEAN — a review whose body says findings are still open must block the same way an unresolved
+ * thread does, even when every inline thread happens to be resolved (a review can carry findings
+ * with no unresolved threads at all: the nano-bpm#1443 review raised 7 findings as a summary-only
+ * "Changes recommended").
+ *
+ * Recognised open-finding signals (each returns a short human label for the block reason):
+ *   • "Changes recommended" — Copilot's 🟡 verdict line (vs. the ✅ clean verdict);
+ *   • "N open issue(s)"    — the summary count Copilot emits when findings remain;
+ *   • a ccr-overview-v2 `<summary>…Open (N)…</summary>` section (issue #835's format) with N ≥ 1.
+ * A body carrying NONE of these reports no open findings (empty array) — including the empty body
+ * of a comment-only review. Pure; unit-tested. */
+export function parseReviewOpenFindings(reviewBody: string | null | undefined): string[] {
+  const body = reviewBody ?? "";
+  if (body.trim() === "") return [];
+  const out: string[] = [];
+  // Only VERDICT lines and dedicated finding-count <summary> sections count — never descriptive
+  // prose (a clean review's file table may legitimately say `Recognizes "Changes recommended"`).
+  // A verdict line STARTS with the verdict (`### 🟡 Changes recommended`, `🟡 Changes recommended`).
+  if (/^[ \t]*(?:#{1,6}[ \t]*)?(?:🟡[ \t]*)?changes recommended\b/imu.test(body)) out.push("changes recommended");
+  // Each <summary> match is bounded by its own closing tag ([^<]* cannot cross `</summary>`).
+  for (const m of body.matchAll(/<summary>(?:<strong>)?\s*(\d+)\s+open\s+issues?\s*(?:<\/strong>)?\s*<\/summary>/gi)) {
+    if (Number(m[1]) > 0) out.push(`${m[1]} open issue${m[1] === "1" ? "" : "s"}`);
+  }
+  for (const m of body.matchAll(/<summary>(?:<strong>)?\s*Open\s*\((\d+)\)\s*(?:<\/strong>)?\s*<\/summary>/gi)) {
+    if (Number(m[1]) > 0) out.push(`${m[1]} open finding${m[1] === "1" ? "" : "s"}`);
+  }
+  return out;
+}
+
 /** A finding clause's trailing `(<severity>, N vote[s])` tag in the ccr-overview-v2 file table. */
 const V2_FINDING_TAG = /\s*\(\s*[a-z]+\s*,\s*\d+\s+votes?\s*\)/gi;
 
@@ -1665,6 +1696,10 @@ export type MergeMethod = "squash" | "merge" | "rebase";
 export interface MergeOptions {
   method: MergeMethod;
   admin: boolean;
+  /** The head SHA the caller verified (issue #923 backstop). When set, GitHub refuses the merge if
+   * the PR head moved since — gh `--match-head-commit`, REST `sha` — so a later, unreviewed head
+   * can never be landed by a check-then-merge race. The refusal surfaces as a transient `retry`. */
+  expectedHeadSha?: string;
 }
 export interface MergeResult {
   outcome: "merged" | "queued" | "blocked" | "retry";
@@ -1677,9 +1712,21 @@ export interface MergeResult {
  * must re-attempt on the settled base, NOT page a human. Matches GitHub's stable message across
  * both the GraphQL `mergePullRequest` error and its HTTP 405 REST variant. Kept narrow — the exact
  * "<Base|Head> branch was modified" phrase — so a genuine block (conflict, failing required check,
- * 403 perms, 422 not-mergeable) is never swallowed as transient. */
+ * 403 perms, 422 not-mergeable) is never swallowed as transient.
+ *
+ * The same class covers the `--match-head-commit` / REST `sha` pin refusal (issue #923 review): the
+ * PR head advanced past the verified head between the review backstop and the merge mutation, so
+ * GitHub refused the pinned merge. That is a check-then-act race the loop is designed to absorb —
+ * the bounded merge retry re-runs the review backstop on the new head — not a human-actionable
+ * block. gh words it "Head commit of pull request #… does not match '--match-head-commit'"; the
+ * REST `sha` mismatch surfaces as a 409 whose body carries the same "Head branch was modified"
+ * phrase (matched by the first alternative) or a "SHA does not match" wording. */
 export function isTransientMergeRace(detail: string): boolean {
-  return /\b(?:base|head) branch was modified\b/i.test(detail);
+  return (
+    /\b(?:base|head) branch was modified\b/i.test(detail) ||
+    /does not match ['"]--match-head-commit['"]/i.test(detail) ||
+    /\bsha does not match\b/i.test(detail)
+  );
 }
 
 /** Attempt to land the PR. Returns `merged` (landed now), `queued` (added to the repo's merge
@@ -1697,6 +1744,7 @@ export async function mergePr(
   if (await useGh()) {
     const args = ["pr", "merge", String(number), "--repo", repo, methodFlag];
     if (opts.admin) args.push("--admin");
+    if (opts.expectedHeadSha) args.push("--match-head-commit", opts.expectedHeadSha);
     try {
       const out = await runGh(args);
       // gh prints "… will be added to the merge queue" when the branch requires one.
@@ -1721,7 +1769,9 @@ export async function mergePr(
       accept: "application/vnd.github+json",
       "content-type": "application/json",
     },
-    body: JSON.stringify({ merge_method: opts.method }),
+    body: JSON.stringify(
+      opts.expectedHeadSha ? { merge_method: opts.method, sha: opts.expectedHeadSha } : { merge_method: opts.method },
+    ),
   });
   if (r.ok) {
     // A 2xx from the REST merge endpoint does not guarantee the PR has *landed*: the body's

package/app/mergeLoopBehaviour.test.ts

@@ -688,6 +688,18 @@ test("a retry that exhausts the budget escalates as a repeated race, not a gener
   assertStringIncludes(String(escalation(engine).question ?? ""), "retry budget", "the retry escalation must read as a repeated race");
 });
 
+test("a worker-supplied block question (review backstop #923) reaches the human escalation verbatim", async () => {
+  const engine = await boot({
+    responses: { "pr.merge": { mergeStatus: "blocked", status: "blocked", question: "Merge refused: no head-current Copilot review exists." } },
+  });
+  await engine.publishMessage({ name: "deps-cleared", correlationKey: "pr-1" });
+  await engine.publishMessage({ name: "merge-ready", correlationKey: "pr-1", variables: { mergeState: "ready" } });
+  await assertThatUserTask(engine, { instance: byProcessId("merge-loop"), elementId: "wait-merge-answer" }).isCreated();
+  const q = String(escalation(engine).question ?? "");
+  assertStringIncludes(q, "no head-current Copilot review", "the backstop's recovery instructions must reach the human");
+  assert(!q.includes("Investigate why GitHub refused"), "must not be overwritten by the generic refusal text");
+});
+
 // ---------------------------------------------------------------------------
 // CI-fix sub-process (SP_cifix) — mergeCiReattempt (#134), #329
 // ---------------------------------------------------------------------------

package/app/mergeRetry.test.ts

@@ -43,6 +43,33 @@ test("isTransientMergeRace: genuine blocks are NOT transient (never swallowed)",
   assertEquals(isTransientMergeRace("Merge conflict; base branch has conflicts"), false); // a base conflict is a real block
 });
 
+// #923 review (Copilot "previously missed"): the `--match-head-commit` / REST `sha` pin refuses the
+// merge when the PR head advanced past the verified head between the review backstop and the merge
+// mutation. That refusal is the SAME class as the base/head-moved race — a transient check-then-act
+// race GitHub resolves by re-attempting — so it must classify as `retry` (the merge loop's bounded
+// retry re-runs the review backstop on the new head), never `blocked` (which pages a human for a
+// race the loop is designed to absorb).
+test("isTransientMergeRace: the pinned-head mismatch refusal is transient", () => {
+  // gh CLI `--match-head-commit` refusal (gh's own wording).
+  assertEquals(
+    isTransientMergeRace(
+      "Head commit of pull request #924 does not match '--match-head-commit' expected f5a6f20",
+    ),
+    true,
+  );
+  // gh wording variant (no "expected" tail).
+  assertEquals(
+    isTransientMergeRace("Head commit of pull request #924 does not match '--match-head-commit'"),
+    true,
+  );
+  // REST PUT /pulls/{n}/merge `sha` mismatch — GitHub returns 409 Conflict.
+  assertEquals(
+    isTransientMergeRace("github 409 Conflict: Head branch was modified. Review and try the merge again."),
+    true,
+  );
+  assertEquals(isTransientMergeRace("github 409 Conflict: SHA does not match expected head"), true);
+});
+
 // Drive `mergePr`'s REST (token) transport: the 405 base-moved race must surface as `retry`, while
 // a genuine 405 refusal stays `blocked`.
 async function withMergePut(
@@ -88,3 +115,25 @@ test("mergePr: a genuine 405 refusal → outcome 'blocked' (not swallowed as tra
     assertEquals(res?.outcome, "blocked");
   });
 });
+
+test("mergePr: a REST 409 sha-mismatch refusal → outcome 'retry' (not blocked)", async () => {
+  await withMergePut(409, "Conflict", "Head branch was modified. Review and try the merge again.", async () => {
+    const res = await mergePr("acme/widgets", 42, "test-token", {
+      method: "squash",
+      admin: false,
+      expectedHeadSha: "f5a6f20",
+    });
+    assertEquals(res?.outcome, "retry");
+  });
+});
+
+test("mergePr: a genuine 409 refusal → outcome 'blocked' (not swallowed as transient)", async () => {
+  await withMergePut(409, "Conflict", "Pull Request is not mergeable", async () => {
+    const res = await mergePr("acme/widgets", 42, "test-token", {
+      method: "squash",
+      admin: false,
+      expectedHeadSha: "f5a6f20",
+    });
+    assertEquals(res?.outcome, "blocked");
+  });
+});

package/app/reviewWait.test.ts

@@ -9,6 +9,7 @@ import {
   DEFAULT_REVIEW_NUDGE_MINUTES,
   DEFAULT_REVIEW_WAIT_TIMEOUT,
   isoDurationToMs,
+  isReviewMissingOrStale,
   isReviewStale,
   MAX_REVIEW_NUDGE_MINUTES,
   reviewWaitTimeout,
@@ -128,3 +129,39 @@ test("isReviewStale: a missing HEAD sha fails safe to NOT stale", () => {
 test("isReviewStale: both missing is NOT stale", () => {
   assertEquals(isReviewStale(null, null), false);
 });
+
+// ── isReviewMissingOrStale (issue #923) ──────────────────────────────────────
+// The CONVERGENCE-GATE variant of the staleness predicate. `isReviewStale` intentionally fails
+// safe to "not stale" on a missing review commit_id (a review GitHub carried no `commit_id` for
+// must not fabricate a re-solicit loop) — but that same fail-safe is a fail-OPEN when the null
+// means "no Copilot review exists AT ALL" (nano-bpm#1443 merged with ZERO reviews). The gate's
+// precondition is a HEAD-CURRENT reviewer verdict, so a missing review must route to the review
+// wait exactly like a stale one.
+
+test("isReviewMissingOrStale: NO review (null commit_id) with a readable HEAD is stale/missing — fail CLOSED", () => {
+  // The #923 case: `readReview` verified "no Copilot review" (`commitId: null`) and the head read
+  // succeeded — the gate must NOT treat "no review" as "a verified clean review".
+  assertEquals(isReviewMissingOrStale(null, "bbb2222"), true);
+  assertEquals(isReviewMissingOrStale(undefined, "bbb2222"), true);
+  assertEquals(isReviewMissingOrStale("", "bbb2222"), true);
+  assertEquals(isReviewMissingOrStale("   ", "bbb2222"), true);
+});
+
+test("isReviewMissingOrStale: a differing review commit_id and HEAD sha is stale (same as isReviewStale)", () => {
+  assertEquals(isReviewMissingOrStale("aaa1111", "bbb2222"), true);
+});
+
+test("isReviewMissingOrStale: a head-current review is NOT stale/missing", () => {
+  assertEquals(isReviewMissingOrStale("aaa1111", "aaa1111"), false);
+  assertEquals(isReviewMissingOrStale("  aaa1111 ", "aaa1111"), false);
+});
+
+test("isReviewMissingOrStale: an UNREADABLE head fails safe to NOT stale (never fabricates a re-solicit loop)", () => {
+  // Without the head we cannot prove the review predates it NOR that a missing review should
+  // re-solicit — a transport hiccup must not strand the loop re-requesting forever (the same
+  // fail-safe `isReviewStale` keeps; the review-wait timeout remains the backstop).
+  assertEquals(isReviewMissingOrStale(null, null), false);
+  assertEquals(isReviewMissingOrStale("aaa1111", null), false);
+  assertEquals(isReviewMissingOrStale("aaa1111", ""), false);
+  assertEquals(isReviewMissingOrStale(null, ""), false);
+});

package/app/reviewWait.ts

@@ -114,3 +114,29 @@ export function isReviewStale(
   if (rev === "" || head === "") return false;
   return rev !== head;
 }
+
+/** Is there NO head-current Copilot review to gate on? (issue #923) — the CONVERGENCE-GATE /
+ * merge-backstop variant of {@link isReviewStale}.
+ *
+ * `isReviewStale` intentionally fails safe to "not stale" on a missing review `commit_id` — for
+ * the POLLER, a review GitHub carried no `commit_id` for must not fabricate a re-solicit loop. But
+ * the gate's consumer is different: `fetchLatestCopilotReview` returns `commitId: null` both when
+ * no Copilot review exists AT ALL and when the newest one lacks a `commit_id`, and the gate's
+ * precondition is a HEAD-CURRENT reviewer verdict. Treating "no review" as "a verified clean
+ * review" is the fail-open that merged nano-bpm#1443 with ZERO reviews — so for the GATE, a
+ * missing review commit is stale/missing, not current.
+ *
+ * The head-side fail-safe is kept: with an UNREADABLE head we can prove nothing, so we must not
+ * fabricate a re-solicit loop on a transport hiccup (the review-wait timeout remains the
+ * backstop). Only a READABLE head + a missing/mismatched review commit routes to the review wait. */
+export function isReviewMissingOrStale(
+  reviewCommitId: string | null | undefined,
+  headSha: string | null | undefined,
+): boolean {
+  const head = (headSha ?? "").trim();
+  if (head === "") return false; // unverifiable head → fail safe, exactly as isReviewStale
+  const rev = (reviewCommitId ?? "").trim();
+  // A missing review commit with a readable head = NO head-current verdict → stale/missing.
+  if (rev === "") return true;
+  return rev !== head;
+}