@nanobpm/nano-workforce 0.205.0 → 0.205.1

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [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/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

package/app/github.ts

@@ -862,6 +862,21 @@ export interface PrState {
    *     perpetually-null entry on such a repo must NOT read as an eviction, so the classifier stays
    *     conservative and leaves the `landedWaitTimeout` human backstop to cover a never-lands wedge. */
   mergeQueueEntry: boolean | null;
+  /** Count of UNRESOLVED review threads on the PR (GraphQL `reviewThreads{isResolved}`). Tri-state
+   * (PR #922 review):
+   *   • `>= 0` — the probe was opted into (`withReviewThreads: true`, the merge-stage
+   *     `waiting_merge` poll + the `merge-stall-probe` worker) and succeeded: the real count.
+   *   • `-1`   — NOT probed: the caller did not opt in, so threads are not part of its verdict.
+   *     This keeps {@link classifyMergeability} on exactly its pre-#921 behaviour for every
+   *     non-merge-stage caller (e.g. the readiness `pr` probe).
+   *   • `-2` ({@link THREAD_PROBE_FAILED}) — the probe WAS opted into but the read failed, so the
+   *     count is UNKNOWN. A failed read must never be conflated with `-1` (unprobed): an opted-in
+   *     merge-stage read that couldn't verify threads is not merge-ready.
+   * This is the signal that classifies a `BLOCKED` merge state whose checks are all green: branch
+   * protection's `required_conversation_resolution` blocks the merge while any review thread is
+   * open, and those threads are REVIEW FINDINGS the convergence loop can act on — not a human
+   * problem (issue #921). */
+  unresolvedThreads: number;
 }
 
 /** Map GitHub's REST `mergeable_state` (lower-case) onto the GraphQL `mergeStateStatus`
@@ -1115,7 +1130,7 @@ export async function fetchPrState(
   repo: string,
   number: number | string,
   token: string,
-  opts?: { withMergeQueue?: boolean },
+  opts?: { withMergeQueue?: boolean; withReviewThreads?: boolean },
 ): Promise<PrState | null> {
   if (await useGh()) {
     const out = await runGh([
@@ -1145,6 +1160,7 @@ export async function fetchPrState(
     const mergeQueueEntry = opts?.withMergeQueue
       ? await fetchMergeQueueMembership(repo, number, j.baseRefName ?? "", token)
       : null;
+    const unresolvedThreads = await countUnresolvedThreads(repo, number, token, opts);
     return {
       merged,
       state: merged ? "merged" : (j.state ?? "").toUpperCase() === "CLOSED" ? "closed" : "open",
@@ -1158,6 +1174,7 @@ export async function fetchPrState(
       isDraft: !!j.isDraft,
       headRefOid: j.headRefOid ?? null,
       mergeQueueEntry,
+      unresolvedThreads,
     };
   }
   if (!token) return null;
@@ -1196,9 +1213,43 @@ export async function fetchPrState(
     isDraft: !!j.draft,
     headRefOid: j.head?.sha ?? null,
     mergeQueueEntry, // native-queue membership (GraphQL), probed only for block-4 reconciliation
+    unresolvedThreads: await countUnresolvedThreads(repo, number, token, opts),
   };
 }
 
+/** Sentinel for an OPTED-IN review-threads probe that FAILED (PR #922 review). Distinct from the
+ * `-1` "not probed" sentinel: `-1` means the caller never asked (threads are not part of its
+ * verdict — the pre-#921 default); `THREAD_PROBE_FAILED` means the caller asked and the read
+ * errored, so the unresolved-thread count is UNKNOWN. Both are not-merge-ready, but a failed
+ * opted-in read must never be conflated with an unprobed one — a CLEAN PR whose probe errored
+ * must NOT classify `ready` and merge over threads that were never verified resolved. */
+export const THREAD_PROBE_FAILED = -2;
+
+/** Count a PR's unresolved review threads for the BLOCKED-cause classification (issue #921), but
+ * ONLY when the caller opted in (`withReviewThreads: true`) — it is an extra GraphQL round-trip, so
+ * every other caller keeps `-1` ("not probed"), the conservative value that leaves
+ * {@link classifyMergeability} on its pre-#921 behaviour.
+ *
+ * Failure semantics (PR #922 review): the two `-1`-producing cases are NOT interchangeable, so an
+ * OPTED-IN read that fails does NOT collapse to the unprobed `-1` sentinel — it returns
+ * {@link THREAD_PROBE_FAILED} (`-2`) instead. `-1` means "this caller never asked, so threads are
+ * not part of its verdict" (the pre-#921 default); `-2` means "this caller asked and the read
+ * failed, so the thread count is UNKNOWN". The classifier treats both as not-merge-ready, but a
+ * failed opted-in read must never be mistaken for an unprobed one — otherwise a CLEAN PR whose
+ * thread probe errored would classify `ready` and merge over threads that were never verified
+ * resolved. */
+async function countUnresolvedThreads(
+  repo: string,
+  number: number | string,
+  token: string,
+  opts?: { withReviewThreads?: boolean },
+): Promise<number> {
+  if (!opts?.withReviewThreads) return -1; // not probed — threads are not part of this caller's verdict
+  const threads = await fetchReviewThreads(repo, number, token).catch(() => null);
+  if (threads === null) return THREAD_PROBE_FAILED; // opted in but the read failed → UNKNOWN, not unprobed
+  return threads.filter((t) => !t.isResolved).length;
+}
+
 /** Map a PR's live GitHub state to one **liveness** verdict shared by both durable loops (merge +
  * convergence), so neither can ever escalate against a non-open PR (#342):
  *
@@ -1423,9 +1474,52 @@ export async function baseBranchLanded(
 /** A settled landability verdict, or `waiting` when GitHub hasn't determined it yet (or is
  * still running checks / awaiting review). `draft` is a settled *not-landable* verdict: a draft PR
  * can never be merged (GitHub refuses it outright), regardless of its checks — so it outranks every
- * other signal and carries its own actionable remedy (mark it ready). The poller only advances the
- * process on a settled verdict; `waiting` means re-poll later. */
-export type Mergeability = "ready" | "waiting" | "conflict" | "blocked" | "draft";
+ * other signal and carries its own actionable remedy (mark it ready). `review-threads` (issue #921)
+ * is likewise a settled *not-landable* verdict: the merge is `BLOCKED` with every check green, but
+ * ≥1 review thread is still unresolved (branch protection `required_conversation_resolution`) —
+ * those threads are review findings the loop acts on, not a "mergeability never settled" stall.
+ * The poller only advances the process on a settled verdict; `waiting` means re-poll later. */
+export type Mergeability = "ready" | "waiting" | "conflict" | "blocked" | "draft" | "review-threads";
+
+/** WHY a `mergeStateStatus = BLOCKED` PR is blocked (issue #921). GitHub reports one flat `BLOCKED`
+ * for several distinct causes, each with a different remedy — so the merge loop must classify the
+ * cause instead of escalating the misleading "mergeability never settled":
+ *   • `"checks"`         — a required check failed (the existing `blocked` verdict → fix-ci).
+ *   • `"review-threads"` — checks are green but ≥1 review thread is unresolved (branch protection
+ *                          `required_conversation_resolution`); the threads are review findings the
+ *                          loop sends back into convergence, not a human escalation.
+ *   • `"reviews"`        — checks green, threads probed and ALL resolved, yet still BLOCKED: the
+ *                          remaining causes are a required human review approval (or a code-owner
+ *                          review) — nothing an automated loop can produce → escalate with THAT
+ *                          reason named.
+ *   • `"unknown"`        — the cause could not be determined (checks unenumerable in token mode,
+ *                          or the thread read was unverifiable) → stays on the conservative
+ *                          `waiting` re-poll, exactly as before #921. */
+export type BlockedCause = "checks" | "review-threads" | "reviews" | "unknown";
+
+/** Classify why a `BLOCKED` PR is blocked. Pure; unit-tested. Only meaningful for a state read
+ * that opted into the review-threads probe (`unresolvedThreads >= 0`); an unprobed read (`-1`) or a
+ * FAILED probe (`THREAD_PROBE_FAILED`, `-2`) can never distinguish "no threads" from "couldn't read
+ * threads", so it reports `"unknown"` and the caller keeps waiting — a failed read must never
+ * fabricate a "reviews"-caused escalation. */
+export function classifyBlockedCause(s: PrState): BlockedCause {
+  if (s.failingChecks > 0) return "checks";
+  // Checks unenumerable (token mode, `failingChecks === -1`): "green checks" can't be confirmed, so
+  // no thread count can settle the cause — stay `unknown` (the caller keeps waiting), exactly as
+  // before #921. This guard must precede the thread read or a token-mode BLOCKED with open threads
+  // would fabricate a `review-threads` verdict off an unverifiable "checks green" premise.
+  if (s.failingChecks < 0) return "unknown";
+  // Zero FAILING checks does not mean checks are green: queued/running checks are tracked
+  // separately in `pendingCheckNames`. While any check is still in flight the BLOCKED cause is
+  // undetermined — the pending run may come back red (→ `checks`) — so stay `unknown` and let the
+  // caller keep waiting rather than assign a thread/approval cause off a half-settled rollup
+  // (PR #922 review). This guard must precede the thread read for the same reason the
+  // unenumerable-checks guard does: "checks green" is the premise every later cause stands on.
+  if (s.pendingCheckNames.length > 0) return "unknown";
+  if (s.unresolvedThreads > 0) return "review-threads";
+  if (s.unresolvedThreads === 0) return "reviews";
+  return "unknown";
+}
 
 /** Intersect a repo's declared `requiredChecks` against the head's actual per-check conclusions —
  * an INDEPENDENT backstop that runs BEFORE the `mergeStateStatus` switch, so nwf never merges a red
@@ -1485,13 +1579,57 @@ export function classifyMergeability(s: PrState, protocol?: MergeProtocol): Merg
   // ready. The poller self-heals this (mark-ready) when the repo's protocol wants a fresh head run,
   // else escalates with an actionable message.
   if (s.isDraft) return "draft";
-  // Protocol-aware backstop FIRST (issue #392): honour the repo's declared `requiredChecks`
+  // Protocol-aware backstop (issue #392): honour the repo's declared `requiredChecks`
   // against the actual head rollup, so an `UNSTABLE` PR with a red DECLARED-required
   // check is no longer blindly `ready`. This never weakens GitHub branch protection (the switch
   // below still gates) — it only tightens merges on repos that under-specify their required checks.
+  // It ALSO outranks the thread gate (PR #922 review, thread 2): a declared-required check that is
+  // red (`blocked`) or not-yet-satisfied (`waiting` — e.g. a NEUTRAL build a success-only protocol
+  // rejects, or an absent required check) owns remediation/waiting, so a convergence round must not
+  // start on top of it. Consulting the verdict here keeps the protocol's decisions ahead of the
+  // settled-thread routing below.
   const gate = requiredChecksVerdict(s, protocol);
   if (gate === "blocked") return "blocked";
   if (gate === "waiting") return "waiting";
+  // A GitHub-identified merge conflict (`mergeStateStatus: "DIRTY"`) is ground truth whose remedy is
+  // a rebase, dispatched off the `conflict` verdict. It outranks the thread gate below (PR #922
+  // review, thread 1): a FAILED thread probe (`THREAD_PROBE_FAILED`) returning `waiting` here 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. Surface the conflict first; the threads are re-triaged once the
+  // rebased head is re-read. (A red declared-required check still outranks even this — see the
+  // backstop above — so a conflicting PR with failing CI routes to fix-ci, not a doomed rebase.)
+  if (s.mergeStateStatus === "DIRTY") return "conflict";
+  // The merge-stage thread gate (issue #921, PR #922 review): a read that opted into the
+  // review-threads probe and found ≥1 open thread (`unresolvedThreads > 0`) is NEVER merge-ready,
+  // whatever `mergeStateStatus` says. A repo without branch-protection
+  // `required_conversation_resolution` reports such a PR CLEAN/UNSTABLE — mergeable by GitHub's
+  // rules — but issue #921's merge contract is zero unresolved threads: those threads are review
+  // findings the loop converges with, so the PR routes back into convergence instead of landing
+  // over them. An UNPROBED read (`-1`) keeps exactly its pre-#921 behaviour — every non-merge-stage
+  // caller (e.g. the readiness `pr` probe, readiness.ts `matchPr`) never opted in and is untouched.
+  // A FAILED opted-in probe (`THREAD_PROBE_FAILED`, `-2`) is likewise never merge-ready: the thread
+  // count is UNKNOWN, so the read holds `waiting` rather than merging over threads it could not
+  // verify (PR #922 review, thread 1).
+  //
+  // This gate runs BEFORE the `mergeStateStatus` switch's `ready` arms so a known open thread can
+  // never fall through to a `ready` (PR #922 review, thread 2) — but AFTER the conflict and
+  // required-check verdicts above, so it can only ever decide between `ready` and a thread verdict,
+  // never suppress a known conflict or a declared-required-check remediation. The verdict splits on
+  // whether the checks are KNOWN settled:
+  //   • a failing check (`failingChecks > 0`) owns remediation → `blocked` (fix-ci), never a review
+  //     round on top of the CI problem;
+  //   • checks settled green (none failing, none pending, enumerable) → the threads OWN the
+  //     verdict: `review-threads` routes the PR back into a convergence round;
+  //   • otherwise (a pending check, or checks unenumerable in token mode, `failingChecks === -1`) →
+  //     the threads still block the merge but the check state owns the verdict, so hold `waiting`
+  //     and re-fire the gate on the next pass once the rollup settles.
+  if (s.unresolvedThreads === THREAD_PROBE_FAILED) return "waiting";
+  if (s.unresolvedThreads > 0) {
+    if (s.failingChecks > 0) return "blocked";
+    if (s.failingChecks === 0 && s.pendingCheckNames.length === 0) return "review-threads";
+    return "waiting";
+  }
   switch (s.mergeStateStatus) {
     case "CLEAN":
     case "HAS_HOOKS":
@@ -1501,9 +1639,23 @@ export function classifyMergeability(s: PrState, protocol?: MergeProtocol): Merg
     case "DIRTY":
       return "conflict";
     case "BLOCKED":
-      // A required check failed -> a human must act. Pending checks / awaiting review -> wait.
-      // When we can't enumerate checks (failingChecks < 0, token mode) stay conservative: wait.
-      return s.failingChecks > 0 ? "blocked" : "waiting";
+      // Classify WHY GitHub blocks the merge (issue #921): a failed required check routes to
+      // fix-ci; unresolved review threads (checks green, branch protection
+      // `required_conversation_resolution`) are a settled not-landable verdict of their own —
+      // `review-threads` — so the loop routes them back into a review round instead of waiting
+      // out the stall budget and escalating the misleading "mergeability never settled". A BLOCKED
+      // whose cause can't be read (checks unenumerable in token mode, or the threads probe
+      // unreadable) stays conservative: wait. A BLOCKED with green checks and zero unresolved
+      // threads (a required human review) also keeps waiting here — the merge-stall escalation
+      // names that specific cause once the re-poll budget is exhausted.
+      switch (classifyBlockedCause(s)) {
+        case "checks":
+          return "blocked";
+        case "review-threads":
+          return "review-threads";
+        default:
+          return "waiting";
+      }
     default: // UNKNOWN / "" — GitHub is still computing mergeability
       return "waiting";
   }