@nanobpm/nano-workforce 0.205.0 → 0.205.2

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [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
+
+* **merge:** classify BLOCKED merge state and route unresolved review threads back into convergence ([#922](https://github.com/nanobpm/nano-workforce/issues/922)) ([5265f66](https://github.com/nanobpm/nano-workforce/commit/5265f66f7a0aca05fbb205c15b2ee0ef45c2aead)), closes [nano-bpm#1427](https://github.com/nanobpm/nano-bpm/issues/1427) [#921](https://github.com/nanobpm/nano-workforce/issues/921) [#921](https://github.com/nanobpm/nano-workforce/issues/921) [pre-#921](https://github.com/nanobpm/pre-/issues/921) [#921](https://github.com/nanobpm/nano-workforce/issues/921) [pre-#921](https://github.com/nanobpm/pre-/issues/921) [#921](https://github.com/nanobpm/nano-workforce/issues/921)
+
 ## [0.205.0](https://github.com/nanobpm/nano-workforce/compare/v0.204.1...v0.205.0) (2026-11-04)
 
 ### Features

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.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, compareCommits, createPullRequest, ensureBaseBranch, ensurePromotionPr, fetchBranchHead, fetchIssueTitle, fetchPrFiles, fetchPrHead, fetchPrReviews, isNotAPullRequestError, listPrsForHead, updateBranchRef, type GhReview, type Mergeability, type PrState } from "./github.ts";
+import { BaseBranchMustExistError, checkConclusions, classifyBlockedCause, classifyMergeability, classifyPrLiveness, coalesceTitle, compareCommits, createPullRequest, ensureBaseBranch, ensurePromotionPr, fetchBranchHead, fetchIssueTitle, fetchPrFiles, fetchPrHead, fetchPrReviews, isNotAPullRequestError, listPrsForHead, THREAD_PROBE_FAILED, updateBranchRef, type GhReview, 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]`
@@ -556,6 +556,7 @@ function prState(over: Partial<PrState>): PrState {
     isDraft: false,
     headRefOid: null,
     mergeQueueEntry: null,
+    unresolvedThreads: -1,
     ...over,
   };
 }
@@ -604,6 +605,7 @@ function mergePrState(over: Partial<PrState> & { rollup?: { name: string; conclu
     isDraft: false,
     headRefOid: "abc123",
     mergeQueueEntry: null,
+    unresolvedThreads: -1,
   };
   if (rollup) {
     const bad = new Set(["FAILURE", "TIMED_OUT", "CANCELLED", "ACTION_REQUIRED", "STARTUP_FAILURE", "ERROR"]);
@@ -808,6 +810,288 @@ test("classifyMergeability: a non-draft PR is unaffected (regression guard, issu
   assertEquals(classifyMergeability(prState({ mergeStateStatus: "CLEAN", isDraft: false })), "ready");
 });
 
+// ── BLOCKED-cause classification (issue #921) ────────────────────────────────────────────────────
+//
+// GitHub reports one flat `mergeStateStatus: BLOCKED` for several distinct causes. Before the fix,
+// `classifyMergeability` mapped `BLOCKED` with no failing checks to `"waiting"` — so a PR blocked
+// ONLY by unresolved review threads (branch protection `required_conversation_resolution`, checks
+// green) was never published to the merge loop; the mergeable-wait timer fired, the stall probe
+// re-derived the same `"waiting"`, and after the stall budget the escalation read "GitHub never
+// settled this PR's mergeability" — when GitHub HAD settled (MERGEABLE/BLOCKED). The classifier now
+// distinguishes the causes: unresolved threads are a settled `review-threads` verdict the loop
+// routes back into convergence; a failed required check stays `blocked` (fix-ci); an unreadable
+// cause stays a conservative `waiting`.
+
+test("classifyBlockedCause: a failing required check is the 'checks' cause", () => {
+  assertEquals(classifyBlockedCause(prState({ failingChecks: 2, unresolvedThreads: 3 })), "checks");
+  assertEquals(classifyBlockedCause(prState({ failingChecks: 1, unresolvedThreads: -1 })), "checks");
+});
+
+test("classifyBlockedCause: green checks + unresolved threads is the 'review-threads' cause", () => {
+  assertEquals(classifyBlockedCause(prState({ failingChecks: 0, unresolvedThreads: 1 })), "review-threads");
+  assertEquals(classifyBlockedCause(prState({ failingChecks: 0, unresolvedThreads: 5 })), "review-threads");
+});
+
+test("classifyBlockedCause: green checks + zero unresolved threads is the 'reviews' cause", () => {
+  // Everything the loop can act on is clear, yet GitHub still blocks → a required human review
+  // approval (or code-owner review) is outstanding.
+  assertEquals(classifyBlockedCause(prState({ failingChecks: 0, unresolvedThreads: 0 })), "reviews");
+});
+
+test("classifyBlockedCause: an unprobed or unenumerable read is 'unknown' (never fabricates a cause)", () => {
+  // Threads not probed (-1) — the pre-#921 default for every non-merge-stage read.
+  assertEquals(classifyBlockedCause(prState({ failingChecks: 0, unresolvedThreads: -1 })), "unknown");
+  // Token mode: checks unenumerable (-1) even with threads probed.
+  assertEquals(classifyBlockedCause(prState({ failingChecks: -1, unresolvedThreads: 0 })), "unknown");
+  assertEquals(classifyBlockedCause(prState({ failingChecks: -1, unresolvedThreads: 2 })), "unknown");
+});
+
+test("classifyBlockedCause: a pending check keeps the cause 'unknown' — zero failing ≠ green (PR #922 review)", () => {
+  // Queued/running checks are tracked in `pendingCheckNames`, not `failingChecks`. While any check
+  // is still in flight the BLOCKED cause is undetermined (the pending run may come back red), so no
+  // thread/approval cause may be assigned — the caller keeps waiting.
+  assertEquals(
+    classifyBlockedCause(prState({ failingChecks: 0, pendingCheckNames: ["build"], unresolvedThreads: 2 })),
+    "unknown",
+  );
+  assertEquals(
+    classifyBlockedCause(prState({ failingChecks: 0, pendingCheckNames: ["build"], unresolvedThreads: 0 })),
+    "unknown",
+  );
+});
+
+test("classifyMergeability: BLOCKED + green checks + unresolved threads is a settled 'review-threads' verdict (#921)", () => {
+  // The incident shape (nano-bpm#1427): MERGEABLE/BLOCKED, all required checks green, ≥1 unresolved
+  // Copilot thread. Before the fix this read as "waiting" and escalated as "never settled".
+  assertEquals(
+    classifyMergeability(prState({ mergeStateStatus: "BLOCKED", failingChecks: 0, unresolvedThreads: 2 })),
+    "review-threads",
+  );
+});
+
+test("classifyMergeability: BLOCKED + failing checks still routes to fix-ci, threads or not (#921)", () => {
+  assertEquals(
+    classifyMergeability(prState({ mergeStateStatus: "BLOCKED", failingChecks: 1, unresolvedThreads: 2 })),
+    "blocked",
+  );
+});
+
+test("classifyMergeability: BLOCKED with an unprobed thread read keeps waiting conservatively (#921)", () => {
+  // `unresolvedThreads: -1` (not probed / unreadable) must never fabricate the review-threads
+  // verdict — the PR keeps polling exactly as before #921.
+  assertEquals(
+    classifyMergeability(prState({ mergeStateStatus: "BLOCKED", failingChecks: 0, unresolvedThreads: -1 })),
+    "waiting",
+  );
+  // Token mode (checks unenumerable) likewise stays a conservative wait.
+  assertEquals(
+    classifyMergeability(prState({ mergeStateStatus: "BLOCKED", failingChecks: -1, unresolvedThreads: 0 })),
+    "waiting",
+  );
+});
+
+test("classifyMergeability: BLOCKED + green checks + zero unresolved threads keeps waiting, gated on resolution (#921)", () => {
+  // A required human review holds the merge. The verdict stays "waiting" (the poller keeps
+  // watching), and the merge-stall escalation names the specific cause once the budget exhausts —
+  // the merge step never fires while the block stands.
+  assertEquals(
+    classifyMergeability(prState({ mergeStateStatus: "BLOCKED", failingChecks: 0, unresolvedThreads: 0 })),
+    "waiting",
+  );
+});
+
+test("classifyMergeability: an opted-in read with unresolved threads is never merge-ready — the merge-stage thread gate (#921, PR #922 review)", () => {
+  // Issue #921's merge contract is ZERO unresolved threads — independent of `mergeStateStatus`. A
+  // repo WITHOUT branch-protection `required_conversation_resolution` reports a thread-blocked PR
+  // CLEAN/UNSTABLE (mergeable by GitHub's rules), but the threads are review findings the loop
+  // converges with, so an opted-in (`withReviewThreads`) merge-stage read routes the PR back into
+  // convergence instead of landing over them.
+  assertEquals(
+    classifyMergeability(prState({ mergeStateStatus: "CLEAN", failingChecks: 0, unresolvedThreads: 3 })),
+    "review-threads",
+  );
+  assertEquals(
+    classifyMergeability(prState({ mergeStateStatus: "UNSTABLE", failingChecks: 0, unresolvedThreads: 3 })),
+    "review-threads",
+  );
+  assertEquals(
+    classifyMergeability(prState({ mergeStateStatus: "HAS_HOOKS", failingChecks: 0, unresolvedThreads: 1 })),
+    "review-threads",
+  );
+  assertEquals(
+    classifyMergeability(prState({ mergeStateStatus: "BEHIND", failingChecks: 0, unresolvedThreads: 1 })),
+    "review-threads",
+  );
+});
+
+test("classifyMergeability: an UNPROBED read keeps the pre-#921 verdicts — non-merge-stage callers are untouched (#921)", () => {
+  // `unresolvedThreads: -1` (the probe not opted into — e.g. the readiness `pr` probe's
+  // `matchPr`) must never fabricate the review-threads verdict: the mergeStateStatus switch
+  // governs, exactly as before #921.
+  assertEquals(
+    classifyMergeability(prState({ mergeStateStatus: "CLEAN", failingChecks: 0, unresolvedThreads: -1 })),
+    "ready",
+  );
+  assertEquals(
+    classifyMergeability(prState({ mergeStateStatus: "UNSTABLE", failingChecks: 0, unresolvedThreads: -1 })),
+    "ready",
+  );
+});
+
+test("classifyMergeability: BLOCKED with pending checks keeps waiting — no cause off a half-settled rollup (PR #922 review)", () => {
+  // Zero failing checks with a check still queued/running is not "checks green": the BLOCKED cause
+  // is undetermined until the pending run concludes, so the verdict stays a conservative wait even
+  // with open threads.
+  assertEquals(
+    classifyMergeability(
+      prState({ mergeStateStatus: "BLOCKED", failingChecks: 0, pendingCheckNames: ["build"], unresolvedThreads: 2 }),
+    ),
+    "waiting",
+  );
+});
+
+test("classifyMergeability: known unresolved threads never reach 'ready' when checks are NOT settled (PR #922 review, thread 2)", () => {
+  // The pre-switch thread gate must hold the merge even when the checks aren't green: a token-mode
+  // CLEAN PR has `failingChecks === -1` (checks unenumerable), and an UNSTABLE PR can have a failing
+  // non-required check. Without conversation-resolution protection, `pollMerges` would otherwise
+  // authorise merging over the open threads. The threads still block the merge, but a failing check
+  // owns remediation (`blocked` → fix-ci) while a pending / unenumerable check holds `waiting` —
+  // either way the verdict is never `ready`.
+  // Token mode: checks unenumerable (failingChecks -1), threads open, CLEAN → waiting (not ready).
+  assertEquals(
+    classifyMergeability(prState({ mergeStateStatus: "CLEAN", failingChecks: -1, unresolvedThreads: 2 })),
+    "waiting",
+  );
+  // UNSTABLE with a failing non-required check + open threads → the failing check owns remediation
+  // (`blocked` → fix-ci), never `ready`: the merge never lands over the open threads.
+  assertEquals(
+    classifyMergeability(prState({ mergeStateStatus: "UNSTABLE", failingChecks: 1, unresolvedThreads: 2 })),
+    "blocked",
+  );
+  // A pending check + open threads on a CLEAN PR → waiting (not ready).
+  assertEquals(
+    classifyMergeability(prState({ mergeStateStatus: "CLEAN", failingChecks: 0, pendingCheckNames: ["build"], unresolvedThreads: 2 })),
+    "waiting",
+  );
+  // …and a BLOCKED PR with a failing required check + open threads still routes to fix-ci (the
+  // check owns remediation), NOT to a review round on top of the CI problem.
+  assertEquals(
+    classifyMergeability(prState({ mergeStateStatus: "BLOCKED", failingChecks: 1, unresolvedThreads: 2 })),
+    "blocked",
+  );
+});
+
+test("classifyMergeability: a FAILED opted-in thread probe is never merge-ready — it holds waiting (PR #922 review, thread 1)", () => {
+  // `unresolvedThreads === THREAD_PROBE_FAILED (-2)` means the merge-stage read opted into the
+  // probe but it errored, so the thread count is UNKNOWN. That must NOT collapse to the unprobed
+  // `-1` (which would let a CLEAN PR classify `ready` and merge over threads that were never
+  // verified resolved). The verdict is a conservative `waiting` for every mergeable state.
+  for (const mergeStateStatus of ["CLEAN", "HAS_HOOKS", "UNSTABLE", "BEHIND"]) {
+    assertEquals(
+      classifyMergeability(prState({ mergeStateStatus, failingChecks: 0, unresolvedThreads: THREAD_PROBE_FAILED })),
+      "waiting",
+      `${mergeStateStatus} with a failed thread probe must hold waiting, never ready`,
+    );
+  }
+  // BLOCKED with a failed probe also stays waiting (the cause is unknown — never fabricate one).
+  assertEquals(
+    classifyMergeability(prState({ mergeStateStatus: "BLOCKED", failingChecks: 0, unresolvedThreads: THREAD_PROBE_FAILED })),
+    "waiting",
+  );
+  // …and the BLOCKED-cause classifier likewise refuses to assign a cause off a failed probe.
+  assertEquals(classifyBlockedCause(prState({ failingChecks: 0, unresolvedThreads: THREAD_PROBE_FAILED })), "unknown");
+});
+
+test("classifyMergeability: a known merge conflict is never suppressed by the thread gate (PR #922 review, thread 1)", () => {
+  // `mergeStateStatus: "DIRTY"` is GitHub's ground-truth "the head conflicts with the base" signal —
+  // its remedy is a rebase, dispatched off the `conflict` verdict. A thread-probe read must never
+  // mask it: a FAILED probe (`THREAD_PROBE_FAILED`, `-2`) returning `waiting` before the switch would
+  // park a KNOWN conflict forever (neither the poller nor the stall probe dispatches the rebase), and
+  // an OPEN thread count returning `review-threads`/`waiting` would route a conflict into a review
+  // round that cannot clear it. The conflict outranks the thread gate either way.
+  assertEquals(
+    classifyMergeability(prState({ mergeStateStatus: "DIRTY", failingChecks: 0, unresolvedThreads: THREAD_PROBE_FAILED })),
+    "conflict",
+    "DIRTY + a failed thread probe still surfaces the known conflict (rebase), not a blind wait",
+  );
+  assertEquals(
+    classifyMergeability(prState({ mergeStateStatus: "DIRTY", failingChecks: 0, unresolvedThreads: 3 })),
+    "conflict",
+    "DIRTY + open threads still surfaces the known conflict (rebase), not a review round",
+  );
+  // …and an UNPROBED read keeps the pre-#921 conflict verdict (unchanged).
+  assertEquals(
+    classifyMergeability(prState({ mergeStateStatus: "DIRTY", failingChecks: 0, unresolvedThreads: -1 })),
+    "conflict",
+  );
+  // A red DECLARED-required check still outranks even the conflict: a conflicting PR whose CI is
+  // also red routes to fix-ci (the check owns remediation), not a doomed rebase. This preserves the
+  // required-checks backstop's priority over the `mergeStateStatus` switch.
+  assertEquals(
+    classifyMergeability(
+      prState({
+        mergeStateStatus: "DIRTY",
+        failingChecks: 1,
+        presentCheckNames: ["build"],
+        checkConclusions: { build: "FAILURE" },
+        unresolvedThreads: 2,
+      }),
+      { requiredChecks: [{ name: "build", acceptedConclusions: ["SUCCESS"] }] },
+    ),
+    "blocked",
+    "a red declared-required check owns remediation even over a known conflict",
+  );
+});
+
+test("classifyMergeability: the declared required-check verdict outranks the settled-thread verdict (PR #922 review, thread 2)", () => {
+  // The `unresolvedThreads > 0` arm must consult `requiredChecksVerdict` before assigning
+  // `review-threads`: a repo whose protocol declares a success-only required check reads a NEUTRAL
+  // build as `blocked` (fix-ci), and an absent declared-required check reads as `waiting` — starting
+  // a convergence round on top of either begins remediation before the check requirements are met.
+  const successOnly = { requiredChecks: [{ name: "build", acceptedConclusions: ["SUCCESS"] }] };
+  // NEUTRAL build rejected by the success-only protocol + open threads → the required check owns
+  // remediation (`blocked` → fix-ci), NOT `review-threads`.
+  assertEquals(
+    classifyMergeability(
+      prState({
+        mergeStateStatus: "CLEAN",
+        failingChecks: 0,
+        presentCheckNames: ["build"],
+        checkConclusions: { build: "NEUTRAL" },
+        unresolvedThreads: 2,
+      }),
+      successOnly,
+    ),
+    "blocked",
+    "a NEUTRAL required check rejected by a success-only protocol keeps fix-ci priority over threads",
+  );
+  // An absent declared-required check + open threads → `waiting` (the not-yet-run required check
+  // owns the verdict), NOT `review-threads`.
+  assertEquals(
+    classifyMergeability(
+      prState({ mergeStateStatus: "CLEAN", failingChecks: 0, presentCheckNames: [], unresolvedThreads: 2 }),
+      successOnly,
+    ),
+    "waiting",
+    "an absent declared-required check holds waiting before the threads route to convergence",
+  );
+  // …and when every declared-required check IS satisfied, the open threads still own the verdict.
+  assertEquals(
+    classifyMergeability(
+      prState({
+        mergeStateStatus: "CLEAN",
+        failingChecks: 0,
+        presentCheckNames: ["build"],
+        checkConclusions: { build: "SUCCESS" },
+        unresolvedThreads: 2,
+      }),
+      successOnly,
+    ),
+    "review-threads",
+    "satisfied required checks leave the open threads owning the verdict",
+  );
+});
+
 // `checkConclusions` must report a terminal conclusion per check but normalise a STILL-IN-FLIGHT run
 // to "" for BOTH rollup shapes — a CheckRun whose `status` is not COMPLETED, and a legacy
 // StatusContext whose `state` is PENDING/EXPECTED — so a caller never mistakes a pending