@nanobpm/nano-workforce 0.205.1 → 0.206.0

package/scripts/write-build-info.test.ts

@@ -0,0 +1,87 @@
+// Tests for scripts/write-build-info.ts — the release-time bake of `build-info.json` (issue #925).
+//
+// The acceptance criterion is end-to-end: an `npm pack` of a tree whose build-info.json was written
+// by this script CONTAINS the file, with a 40-hex gitSha — i.e. the published tarball carries the
+// identity an npm-installed instance falls back to. Plus unit coverage of the payload the script
+// composes (source-HEAD sha, `v<version>` tag, ISO builtAt) and its validation.
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { test } from "node:test";
+import { assert, assertEquals, assertThrows } from "#test-assert";
+import { buildInfoProblems, composeBuildInfo } from "./write-build-info.ts";
+
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+const BUILD_INFO = join(REPO_ROOT, "build-info.json");
+const SHA_RE = /^[0-9a-f]{40}$/;
+
+test("composeBuildInfo records the checkout HEAD (40-hex), the v<version> tag, and an ISO builtAt", () => {
+  const head = execFileSync("git", ["rev-parse", "HEAD"], { cwd: REPO_ROOT, encoding: "utf8" }).trim();
+  const info = composeBuildInfo("1.2.3", new Date("2026-01-02T03:04:05.000Z"));
+  assertEquals(info.gitSha, head);
+  assert(SHA_RE.test(info.gitSha));
+  assertEquals(info.gitTag, "v1.2.3");
+  assertEquals(info.builtAt, "2026-01-02T03:04:05.000Z");
+  assertEquals(buildInfoProblems(info), []);
+});
+
+test("composeBuildInfo honours an explicit source SHA instead of the checkout HEAD", () => {
+  // The manual OIDC-recovery path checks out the release TAG, whose HEAD is the metadata-only
+  // release commit — so it passes the source HEAD explicitly. The explicit SHA must win over
+  // `git rev-parse HEAD` and must be validated against the 40-hex contract.
+  const sourceHead = "b".repeat(40);
+  const info = composeBuildInfo("2.0.0", new Date("2026-01-02T03:04:05.000Z"), sourceHead);
+  assertEquals(info.gitSha, sourceHead);
+  assertEquals(info.gitTag, "v2.0.0");
+  assertEquals(buildInfoProblems(info), []);
+});
+
+test("composeBuildInfo rejects a malformed explicit source SHA (fail closed)", () => {
+  assertThrows(() => composeBuildInfo("2.0.0", new Date(), "not-a-sha"), Error, "non-SHA");
+  assertThrows(() => composeBuildInfo("2.0.0", new Date(), "abc123"), Error, "non-SHA");
+});
+
+test("buildInfoProblems rejects malformed payloads", () => {
+  assert(buildInfoProblems(null).length > 0);
+  assert(buildInfoProblems({ version: "1.0.0", gitSha: "not-a-sha", gitTag: "v1.0.0", builtAt: "2026-01-02T03:04:05.000Z" }).length > 0);
+  assert(buildInfoProblems({ version: "1.0.0", gitSha: "a".repeat(40), gitTag: "", builtAt: "2026-01-02T03:04:05.000Z" }).length > 0);
+  assert(buildInfoProblems({ version: "1.0.0", gitSha: "a".repeat(40), gitTag: "v1.0.0", builtAt: "not-a-date" }).length > 0);
+});
+
+test("an npm pack of the package contains build-info.json with a 40-hex SHA", () => {
+  // Write the file exactly as the release pipeline does (prepare step), pack, inspect, then clean
+  // up — build-info.json is a build artifact and MUST NOT be committed (a stale committed copy
+  // would mislabel every later dev checkout), so the test restores the prior state in `finally`.
+  const prior = (() => {
+    try {
+      return readFileSync(BUILD_INFO, "utf8");
+    } catch {
+      return null;
+    }
+  })();
+  const packDir = mkdtempSync(join(tmpdir(), "nwf-pack-"));
+  try {
+    execFileSync("node", ["--experimental-strip-types", "scripts/write-build-info.ts", "0.0.0-packtest"], {
+      cwd: REPO_ROOT,
+      stdio: "pipe",
+    });
+    const out = execFileSync("npm", ["pack", "--pack-destination", packDir], { cwd: REPO_ROOT, encoding: "utf8" });
+    const tarball = join(packDir, out.trim().split("\n").pop() ?? "");
+    const listing = execFileSync("tar", ["-tzf", tarball], { encoding: "utf8" });
+    assert(
+      listing.split("\n").some((f) => f === "package/build-info.json" || f === "build-info.json"),
+      `the tarball must contain build-info.json; got:\n${listing.split("\n").slice(0, 5).join("\n")}…`,
+    );
+    const raw = execFileSync("tar", ["-xzOf", tarball, "package/build-info.json"], { encoding: "utf8" });
+    const packed: unknown = JSON.parse(raw);
+    assertEquals(buildInfoProblems(packed), [], `packed build-info.json must be well-formed: ${raw}`);
+    const gitSha = (packed as { gitSha: string }).gitSha;
+    assert(SHA_RE.test(gitSha), `packed gitSha must be 40-hex, got ${gitSha}`);
+  } finally {
+    if (prior == null) rmSync(BUILD_INFO, { force: true });
+    else writeFileSync(BUILD_INFO, prior);
+    rmSync(packDir, { recursive: true, force: true });
+  }
+});

package/scripts/write-build-info.ts

@@ -0,0 +1,126 @@
+// write-build-info — bake the release's build identity into `build-info.json` at the package root
+// (issue #925).
+//
+// WHY: an npm-installed instance has no `.git` directory and no `NANO_WORKFORCE_GIT_SHA` env var,
+// so `app/version.ts` reported `gitSha: null` on exactly the deploys an operator most needs to
+// identify ("is the fix live on merlin?"). The release pipeline writes this file during
+// semantic-release's `prepare` step — AFTER @semantic-release/npm bumps `package.json` to the
+// release version and BEFORE it packs/publishes the tarball — so every published package carries
+// its own identity and `app/version.ts` can fall back to it (env → .git → build-info.json).
+//
+// WHAT IT RECORDS (and why): `gitSha` is the SOURCE HEAD the release was cut from
+// (`git rev-parse HEAD` in the release checkout), NOT the `chore(release): X.Y.Z` commit
+// @semantic-release/git creates afterwards — that commit does not exist yet at prepare time, so it
+// cannot be recorded here. The release TAG `vX.Y.Z` is later placed on that release commit, whose
+// tree is identical to the source HEAD's tree except for the version-bump metadata (CHANGELOG.md,
+// package.json, package-lock.json). `gitTag` carries the tag name so an operator can resolve the
+// exact release commit (`git rev-list -1 <tag>`) when they need it; `gitSha` answers the
+// day-to-day question "which source code is running".
+//
+// USAGE:
+//   node --experimental-strip-types scripts/write-build-info.ts <version> [--sha <40-hex>]   # release pipeline
+//   node --experimental-strip-types scripts/write-build-info.ts --check                      # test: validate on disk
+//
+// `<version>` alone records the current checkout HEAD — correct at semantic-release `prepare` time.
+// The manual OIDC-recovery path runs from a fresh checkout of the release TAG, whose HEAD is the
+// metadata-only `chore(release)` commit, NOT the source HEAD; it passes `--sha "$(git rev-parse
+// v<version>^")"` so the recorded gitSha still names the source code (see release.yml's recovery
+// instructions).
+//
+// `--check` validates the committed/generated `build-info.json` (present, well-formed, 40-hex
+// gitSha) — used by the pack test to assert the release artifact contract without cutting a
+// release.
+import { execFileSync } from "node:child_process";
+import { writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+export const BUILD_INFO_PATH = join(REPO_ROOT, "build-info.json");
+
+export interface BuildInfo {
+  version: string;
+  gitSha: string;
+  gitTag: string;
+  builtAt: string;
+}
+
+// The ONE payload validator is shared with the reader (app/version.ts) so writer and reader can
+// never disagree on what a valid build-info.json is.
+export { buildInfoProblems } from "../app/version.ts";
+
+import { buildInfoProblems, SHA_RE } from "../app/version.ts";
+
+/**
+ * Compose the build-info payload for a release of `version`. `gitSha` is the SOURCE HEAD the
+ * release was cut from. By default it is read from the current checkout HEAD (`git rev-parse HEAD`)
+ * — correct at semantic-release `prepare` time, when HEAD is still the source commit. Callers that
+ * run LATER (the manual OIDC-recovery path, which checks out the release TAG) must pass `sha`
+ * explicitly as the source HEAD (`git rev-parse v<version>^`): by then HEAD is the metadata-only
+ * `chore(release)` commit, and recording it would mislabel the package with a commit whose only
+ * change is the version bump. An explicit `sha` is validated against the 40-hex contract.
+ */
+export function composeBuildInfo(version: string, now: Date = new Date(), sha?: string): BuildInfo {
+  const gitSha = (
+    sha ?? execFileSync("git", ["rev-parse", "HEAD"], { cwd: REPO_ROOT, encoding: "utf8" })
+  ).trim();
+  if (!SHA_RE.test(gitSha)) throw new Error(`git rev-parse HEAD returned a non-SHA: ${JSON.stringify(gitSha)}`);
+  return {
+    version,
+    gitSha,
+    // The tag semantic-release will place on the release commit for this version.
+    gitTag: `v${version}`,
+    builtAt: now.toISOString(),
+  };
+}
+
+function main(argv: string[]): void {
+  const arg = argv[2];
+  if (arg === "--check") {
+    // Lazy import so the write path never needs fs/readFileSync beyond writeFileSync.
+    import("node:fs").then(({ readFileSync }) => {
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(readFileSync(BUILD_INFO_PATH, "utf8"));
+      } catch (err) {
+        // biome-ignore lint/plugin: narrowing a caught unknown to Error for its message
+        console.error(`build-info.json is missing or invalid JSON: ${(err as Error).message}`);
+        process.exit(1);
+      }
+      const problems = buildInfoProblems(parsed);
+      if (problems.length > 0) {
+        console.error(`build-info.json failed validation:\n - ${problems.join("\n - ")}`);
+        process.exit(1);
+      }
+      console.log(`build-info.json OK: ${JSON.stringify(parsed)}`);
+    });
+    return;
+  }
+  const version = arg?.trim();
+  if (!version) {
+    console.error("usage: write-build-info.ts <version> [--sha <40-hex>] | --check");
+    process.exit(1);
+  }
+  // Optional explicit source SHA (see composeBuildInfo). The manual OIDC-recovery path checks out
+  // the release TAG, whose HEAD is the release commit — so it passes the source HEAD
+  // (`git rev-parse v<version>^`) explicitly to keep gitSha pointing at the source code.
+  let sha: string | undefined;
+  const shaIdx = argv.indexOf("--sha");
+  if (shaIdx !== -1) {
+    sha = argv[shaIdx + 1]?.trim();
+    if (!sha || !SHA_RE.test(sha)) {
+      console.error(`--sha must be a 40-hex commit SHA, got ${JSON.stringify(argv[shaIdx + 1])}`);
+      process.exit(1);
+    }
+  }
+  const info = composeBuildInfo(version, new Date(), sha);
+  writeFileSync(BUILD_INFO_PATH, `${JSON.stringify(info, null, 2)}\n`);
+  console.log(`wrote build-info.json: version=${info.version} gitSha=${info.gitSha} gitTag=${info.gitTag}`);
+}
+
+// Run the CLI only when executed directly — importing this module (e.g. from the test) must not
+// parse argv or write files.
+const invokedAs = process.argv[1] ? pathToFileURL(process.argv[1]).href : "";
+if (invokedAs === import.meta.url) {
+  main(process.argv);
+}

package/workers/converge-gate/worker.ts

@@ -29,6 +29,15 @@
 // re-enters the review wait for a fresh review of the current HEAD. The head read fails OPEN, so a
 // transport hiccup can never fabricate a stale verdict.
 //
+// MISSING-REVIEW GUARD (issue #923): the same `reviewStale` signal fires when NO Copilot review
+// exists at all — the gate's single most important precondition. The old code treated
+// `{ body: "", commitId: null }` as "a verified clean review" and converged, merging
+// nano-bpm#1443 with ZERO reviews. A missing review now fails CLOSED into the re-solicit path.
+//
+// VERDICT GATE (issue #923 §2): even a head-current review BLOCKS when its own summary reports
+// open, actionable findings ("Changes recommended" / "N open issue(s)" / a v2 "Open (N)" section)
+// — zero unresolved threads is not a clean verdict.
+//
 // Scope integrity is NO LONGER judged here. A deterministic regex over the PR description could not
 // read the closed issue's acceptance criteria, so it false-positived on any body that merely
 // *mentioned* deferral (an ADR non-goal, a PR whose subject is scope tooling) and forced needless
@@ -49,10 +58,11 @@ import {
   fetchReviewThreads,
   isAckThread,
   parseAckedAdvisories,
+  parseReviewOpenFindings,
   parseSuppressedAdvisories,
   type ReviewThread,
 } from "../../app/github.ts";
-import { isReviewStale } from "../../app/reviewWait.ts";
+import { isReviewMissingOrStale } from "../../app/reviewWait.ts";
 import { parsePr } from "../../app/service.ts";
 import type { WorkerInputs, WorkerOutputs } from "../../nano-generated/worker-io.d.ts";
 import { type HeadReader, makeDefaultReadHead } from "../progress-check/worker.ts";
@@ -118,17 +128,57 @@ export function makeHandler(deps: {
       if (review === null) {
         return { convergeBlocked: true, convergeBlockReason: BLOCK_UNVERIFIABLE, convergeAckOnly: false, reviewStale: false };
       }
-      // STALE-REVIEW GUARD (issue #799). When the PR HEAD has advanced PAST the commit the latest
-      // Copilot review was submitted against, that review's suppressed advisories describe code the
-      // head has moved past — e.g. an advisory the agent already FIXED IN CODE (but did not ack) is
-      // still re-listed in the obsolete body. Blocking/escalating on it re-escalates a human
-      // indefinitely (PR #789). Instead of gating on the stale body, signal `reviewStale` so the
-      // process re-enters the review wait and the poller re-solicits a fresh review of the current
-      // HEAD to gate on. The head read fails OPEN (null → not stale), so a transport hiccup can never
-      // fabricate a stale verdict; the ordinary gate below still runs on a HEAD-current review.
+      // STALE-OR-MISSING-REVIEW GUARD (issues #799 / #923). Convergence requires a HEAD-CURRENT
+      // reviewer verdict. Two states fail that precondition and must route to the review wait (the
+      // poller (re-)solicits a review of the current HEAD) rather than be gated on:
+      //   • STALE (#799): the PR HEAD has advanced PAST the commit the latest Copilot review was
+      //     submitted against — its suppressed advisories describe code the head has moved past
+      //     (e.g. an advisory the agent already FIXED IN CODE but did not ack), so blocking on the
+      //     obsolete body re-escalates a human indefinitely (PR #789).
+      //   • MISSING (#923): NO Copilot review exists at all (`commitId: null` with a readable
+      //     head). The old gate treated that as "a verified clean review" — zero threads, zero
+      //     advisories → not blocked — and merged nano-bpm#1443 with ZERO reviews. A missing
+      //     review is the gate's single most important precondition, so it fails CLOSED into the
+      //     same re-solicit path (`isReviewMissingOrStale`), never through to finalize.
+      // The head read still fails OPEN (null → not stale): without the head we can prove nothing,
+      // so a transport hiccup can never fabricate a stale/missing verdict that would loop the loop
+      // re-soliciting forever — the review-wait timeout remains the backstop.
+      //
+      // ARRIVAL-WINDOW CUTOFF (issue #923 review, "previously missed"): the stale/missing verdict
+      // is decided from the review read ABOVE — but the loop only PARKS for the next review several
+      // tasks later (persist-round → check-progress), and check-progress stamps `waiting_since` at
+      // THAT (later) park time. A head-current review that lands in the window BETWEEN this read
+      // and the park would then be REJECTED by `pollReviews` (it filters
+      // `submitted_at >= waiting_since`), so the loop re-solicits and can time out despite a valid
+      // verdict already sitting unconsumed on the PR. Emit the time of THIS read as
+      // `reviewWaitCutoff` so check-progress can park with `waiting_since` at the cutoff — any
+      // review that arrived in the window then satisfies the wait instead of being discarded.
       const headSha = await readHeadSha(ghRepo, ghNumber).catch(() => null);
-      if (isReviewStale(review.commitId, headSha)) {
-        return { convergeBlocked: false, convergeBlockReason: "", convergeAckOnly: false, reviewStale: true };
+      if (isReviewMissingOrStale(review.commitId, headSha)) {
+        return {
+          convergeBlocked: false,
+          convergeBlockReason: "",
+          convergeAckOnly: false,
+          reviewStale: true,
+          reviewWaitCutoff: new Date().toISOString(),
+        };
+      }
+      // VERDICT GATE (issue #923 §2): a head-current review whose OWN summary reports open,
+      // actionable findings (Copilot's "Changes recommended" / "N open issue(s)" / a v2 "Open (N)"
+      // section) blocks the same way an unresolved thread does — even with zero unresolved threads
+      // (a review can carry findings as summary-only, as #1443's 7-finding review did). This block
+      // is NOT ack-only: the findings need the round agent's code/reply work, so it escalates to a
+      // human rather than entering the bounded auto-ack path.
+      const openFindings = parseReviewOpenFindings(review.body);
+      if (openFindings.length > 0) {
+        return {
+          convergeBlocked: true,
+          convergeBlockReason:
+            `Convergence blocked: the latest head-current Copilot review reports ${openFindings.join("; ")}. ` +
+            `Address every finding the review raised (or reply-and-resolve why each is a false positive) before converging.`,
+          convergeAckOnly: false,
+          reviewStale: false,
+        };
       }
       // Split the unresolved threads into SUBSTANTIVE reviewer findings vs partially-completed
       // `nano-ack:` ACK threads (root carries a canonical `nano-ack: <path> :: <text>` marker — see

package/workers/merge/worker.test.ts

@@ -8,7 +8,7 @@ import { test } from "node:test";
 import { assertEquals } from "#test-assert";
 import { _clearMergeProtocolCache } from "../../app/mergeProtocol.ts";
 import { noopLog } from "../../test/log.ts";
-import handler from "./worker.ts";
+import handler, { makeHandler } from "./worker.ts";
 
 function fakeApp() {
   const stores: Record<string, Record<string, unknown>[]> = {
@@ -294,3 +294,194 @@ test("pr.merge abandons a closed-not-merged PR without escalating (terminal aban
     },
   );
 });
+
+// ── Merge-loop backstop (issue #923 §3) ──────────────────────────────────────
+// Just before landing, the worker re-checks that a HEAD-CURRENT Copilot review exists. A head that
+// moved between convergence and landing — or a review that never existed (the nano-bpm#1443
+// fail-open: merged with ZERO reviews) — must block the landing, not slip through. These tests
+// drive the backstop through `makeHandler`'s injected readers; the fetch stub only needs the
+// single-PR GET (liveness) since the injected readers replace the review/head fetches.
+
+function backstopRoutes(url: string): Response | null {
+  if (/\/pulls\/\d+$/.test(url)) {
+    return new Response(JSON.stringify({ merged: false, mergeable_state: "clean" }));
+  }
+  return null; // no AGENTS.md / merge-protocol.json → DEFAULT gh-merge protocol
+}
+
+test("pr.merge #923: refuses to land when NO Copilot review exists (the #1443 fail-open)", async () => {
+  await withGithub(backstopRoutes, async (calls) => {
+    const { app, stores } = fakeApp();
+    const backstop = makeHandler({
+      // Verified "no Copilot review on this PR" + a readable head → missing → BLOCK.
+      readReview: async () => ({ body: "", commitId: null }),
+      readHeadSha: async () => "headsha4444444444444444444444444444444444",
+    });
+    const out = (await backstop(
+      { variables: { prKey: "acme/widgets#21", repo: "acme/widgets", prNumber: 21 } } as any,
+      app,
+    )) as Record<string, unknown>;
+
+    assertEquals(out.mergeStatus, "blocked");
+    assertEquals(out.status, "blocked");
+    assertEquals(typeof out.question, "string");
+    assertEquals((out.question as string).includes("no head-current Copilot review"), true);
+
+    // The refusal is audited, and NO land was attempted (no merge PUT, no enqueue comment).
+    assertEquals(stores.merges.length, 1);
+    assertEquals(stores.merges[0].outcome, "blocked");
+    assertEquals(stores.merges[0].method, "review-backstop");
+    assertEquals(calls.some((c) => /\/merge$/.test(c.url)), false);
+    assertEquals(calls.some((c) => /\/comments$/.test(c.url)), false);
+  });
+});
+
+test("pr.merge #923: refuses to land when the head MOVED past the latest review (stale at land time)", async () => {
+  await withGithub(backstopRoutes, async (calls) => {
+    const { app, stores } = fakeApp();
+    const backstop = makeHandler({
+      // The review was submitted against the OLD head; the branch has since advanced.
+      readReview: async () => ({ body: "lgtm", commitId: "oldsha1111111111111111111111111111111111" }),
+      readHeadSha: async () => "newsha2222222222222222222222222222222222",
+    });
+    const out = (await backstop(
+      { variables: { prKey: "acme/widgets#23", repo: "acme/widgets", prNumber: 23 } } as any,
+      app,
+    )) as Record<string, unknown>;
+
+    assertEquals(out.mergeStatus, "blocked");
+    assertEquals(stores.merges[0].method, "review-backstop");
+    assertEquals(calls.some((c) => /\/merge$/.test(c.url)), false);
+  });
+});
+
+test("pr.merge #923: a HEAD-CURRENT review lands normally (backstop control)", async () => {
+  await withGithub(
+    (url) => {
+      if (/\/pulls\/\d+\/merge$/.test(url)) return new Response(JSON.stringify({ merged: true }), { status: 200 });
+      return backstopRoutes(url);
+    },
+    async (calls) => {
+      const { app, stores } = fakeApp();
+      const backstop = makeHandler({
+        readReview: async () => ({ body: "lgtm", commitId: "samesha33333333333333333333333333333333" }),
+        readHeadSha: async () => "samesha33333333333333333333333333333333",
+      });
+      const out = (await backstop(
+        { variables: { prKey: "acme/widgets#25", repo: "acme/widgets", prNumber: 25 } } as any,
+        app,
+      )) as Record<string, unknown>;
+
+      // The backstop passes and the ordinary land protocol runs (direct merge).
+      assertEquals(out, { mergeStatus: "merged" });
+      assertEquals(
+        calls.some((c) => /\/pulls\/\d+\/merge$/.test(c.url) && c.method === "PUT"),
+        true,
+      );
+      assertEquals(stores.merges.some((m) => m.method === "review-backstop"), false);
+    },
+  );
+});
+
+test("pr.merge #923: an UNREADABLE review/head fails OPEN (a transport hiccup never wedges a merge)", async () => {
+  await withGithub(
+    (url) => {
+      if (/\/pulls\/\d+\/merge$/.test(url)) return new Response(JSON.stringify({ merged: true }), { status: 200 });
+      return backstopRoutes(url);
+    },
+    async (calls) => {
+      const { app, stores } = fakeApp();
+      const backstop = makeHandler({
+        readReview: async () => null, // no usable transport → unverifiable, NOT "no review"
+        readHeadSha: async () => {
+          throw new Error("boom");
+        },
+      });
+      const out = (await backstop(
+        { variables: { prKey: "acme/widgets#27", repo: "acme/widgets", prNumber: 27 } } as any,
+        app,
+      )) as Record<string, unknown>;
+
+      assertEquals(out, { mergeStatus: "merged" });
+      assertEquals(
+        calls.some((c) => /\/pulls\/\d+\/merge$/.test(c.url) && c.method === "PUT"),
+        true,
+      );
+      assertEquals(stores.merges.some((m) => m.method === "review-backstop"), false);
+    },
+  );
+});
+
+test("pr.merge #923: a head-current review whose summary reports OPEN findings blocks landing", async () => {
+  await withGithub(backstopRoutes, async (calls) => {
+    const { app, stores } = fakeApp();
+    const backstop = makeHandler({
+      readReview: async () => ({ body: "### 🟡 Changes recommended\n<summary>2 open issues</summary>", commitId: "h1" }),
+      readHeadSha: async () => "h1",
+    });
+    const out = (await backstop({ variables: { prKey: "acme/widgets#29", repo: "acme/widgets", prNumber: 29 } } as any, app)) as Record<string, unknown>;
+    assertEquals(out.mergeStatus, "blocked");
+    assertEquals((out.question as string).includes("open findings"), true);
+    assertEquals(stores.merges[0].method, "review-backstop");
+    assertEquals(calls.some((c) => /\/merge$/.test(c.url)), false);
+  });
+});
+
+for (const [label, readHeadSha] of [
+  ["returns null", async () => null],
+  ["throws", async () => { throw new Error("transient"); }],
+] as const) {
+  test(`pr.merge #923: an unverifiable head (read ${label}) never blocks on a possibly-stale review's open findings`, async () => {
+    await withGithub(backstopRoutes, async () => {
+      const { app, stores } = fakeApp();
+      const backstop = makeHandler({
+        readReview: async () => ({ body: "### 🟡 Changes recommended\n<summary>2 open issues</summary>", commitId: "old" }),
+        readHeadSha,
+      });
+      await backstop({ variables: { prKey: "acme/widgets#29", repo: "acme/widgets", prNumber: 29 } } as any, app);
+      assertEquals(stores.merges.some((m) => m.method === "review-backstop"), false);
+    });
+  });
+}
+
+test("pr.merge #923: the direct merge pins the verified head SHA (no check-then-merge race)", async () => {
+  let putBody = "";
+  await withGithub(
+    (url, init) => {
+      if (/\/pulls\/\d+\/merge$/.test(url)) {
+        putBody = String(init?.body ?? "");
+        return new Response(JSON.stringify({ merged: true }), { status: 200 });
+      }
+      return backstopRoutes(url);
+    },
+    async () => {
+      const { app } = fakeApp();
+      const backstop = makeHandler({ readReview: async () => ({ body: "lgtm", commitId: "h2" }), readHeadSha: async () => "h2" });
+      await backstop({ variables: { prKey: "acme/widgets#31", repo: "acme/widgets", prNumber: 31 } } as any, app);
+      assertEquals(JSON.parse(putBody).sha, "h2");
+    },
+  );
+});
+
+test("pr.merge #923: a queue-comment repo whose head moved after the backstop retries instead of enqueueing", async () => {
+  const protocol =
+    "# repo\n\n```merge-protocol\n{ \"land\": { \"method\": \"mergify-queue\", \"comment\": \"@mergifyio queue\" } }\n```\n";
+  await withGithub(
+    (url) => {
+      if (/\/contents\/AGENTS\.md$/.test(url)) return new Response(protocol);
+      if (/\/issues\/\d+\/comments$/.test(url)) return new Response(JSON.stringify({ id: 1 }), { status: 201 });
+      return backstopRoutes(url);
+    },
+    async (calls) => {
+      const { app } = fakeApp();
+      const heads = ["h3", "h4"];
+      const backstop = makeHandler({
+        readReview: async () => ({ body: "lgtm", commitId: "h3" }),
+        readHeadSha: async () => heads.shift() ?? "h4",
+      });
+      const out = (await backstop({ variables: { prKey: "acme/widgets#33", repo: "acme/widgets", prNumber: 33 } } as any, app)) as Record<string, unknown>;
+      assertEquals(out.mergeStatus, "retry");
+      assertEquals(calls.some((c) => /\/issues\/\d+\/comments$/.test(c.url) && c.method === "POST"), false);
+    },
+  );
+});