@nanobpm/nano-workforce 0.205.0 → 0.205.1

package/app/mergeLoopBehaviour.test.ts

@@ -96,6 +96,8 @@ const DEFAULT_VARS: Record<string, unknown> = {
   mergeStatus: null,
   ciBlockedReconciled: null,
   failingChecks: 0,
+  reviewThreads: null,
+  pendingChecks: null,
   round: 2,
   abandonUrl: "http://host/app/api/hooks/abandon?token=tok-seeded",
 };
@@ -521,6 +523,133 @@ test("an unclassified verdict routes to auto-rebase (DEFAULT), not to a human (#
   assert(!openTasks.some((t) => t.elementId === "wait-merge-answer"), "the default arm must not page a human");
 });
 
+// ---------------------------------------------------------------------------
+// BLOCKED by unresolved review threads (issue #921)
+// ---------------------------------------------------------------------------
+// A PR at MERGEABLE/BLOCKED with all checks green and ≥1 unresolved review thread (branch
+// protection `required_conversation_resolution`) used to classify as "waiting": the poller never
+// published, 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. The `review-threads` verdict now routes to a dedicated escalation that names
+// the real cause (and parks the shared `wait-merge-answer` task, whose answer re-arms the poller),
+// never to the CI-fix or rebase agents.
+
+test("a 'review-threads' verdict escalates naming the unresolved threads — never 'never settled', never an agent (#921)", async () => {
+  const engine = await boot();
+  await engine.publishMessage({ name: "deps-cleared", correlationKey: "pr-1" });
+  await engine.publishMessage({
+    name: "merge-ready",
+    correlationKey: "pr-1",
+    variables: { mergeState: "review-threads", reviewThreads: 2, failingChecks: 0, failingChecksList: "" },
+  });
+  // The threads arm parks the shared answer task with the thread-specific question…
+  await assertThatUserTask(engine, { instance: byProcessId("merge-loop"), elementId: "wait-merge-answer" }).isCreated();
+  assertThatInstance(engine, byProcessId("merge-loop")).isActive().hasCompletedElements("merge-esc-threads");
+  const q = String(escalation(engine).question ?? "");
+  assertStringIncludes(q, "2 unresolved review thread(s)", "the escalation must name the actual blocker and count");
+  assert(!q.includes("never settled"), "a settled BLOCKED must never read as 'mergeability never settled'");
+  // …and never misroutes to the remediation agents or the generic conflict escalation.
+  assert(!completedElementIds(engine).has("fix-ci"), "green checks must not dispatch fix-ci");
+  assert(!completedElementIds(engine).has("rebase"), "a threads block must not dispatch rebase");
+  assert(!completedElementIds(engine).has("merge-esc-conflict"), "the threads arm has its own escalation");
+});
+
+test("answering the review-threads escalation re-arms the merge poller (#921)", async () => {
+  // The human resolves the threads on GitHub and replies; the answer re-arms `arm-merge` so the
+  // next poll re-derives mergeability — once the threads are gone the verdict flips to `ready` and
+  // the merge proceeds (the merge step is thereby gated on zero unresolved threads).
+  const engine = await boot({ responses: { "pr.merge": { mergeStatus: "merged" } } });
+  await engine.publishMessage({ name: "deps-cleared", correlationKey: "pr-1" });
+  await engine.publishMessage({
+    name: "merge-ready",
+    correlationKey: "pr-1",
+    variables: { mergeState: "review-threads", reviewThreads: 1, failingChecks: 0 },
+  });
+  await assertThatUserTask(engine, { instance: byProcessId("merge-loop"), elementId: "wait-merge-answer" }).isCreated();
+  await engine.completeUserTask(await mergeAnswerTaskKey(engine), { answer: "resolved the threads" });
+  // Re-armed at the poller wait — not merged yet (the poller must re-derive)…
+  assertThatInstance(engine, byProcessId("merge-loop")).isActive().hasActiveElement("wait-mergeable");
+  // …then the re-derived ready verdict lands the merge with no human in the loop.
+  await engine.publishMessage({ name: "merge-ready", correlationKey: "pr-1", variables: { mergeState: "ready", reviewThreads: 0 } });
+  assertThatInstance(engine, byProcessId("merge-loop")).hasCompleted().hasNoIncident().hasCompletedElements("attempt-merge", "mark-merged");
+});
+
+test("a stalled probe that re-derives 'review-threads' routes to the threads arm, not the re-poll loop (#921)", async () => {
+  // The poller-dead path: the mergeable-wait timer fires, the stall probe re-derives ground truth,
+  // and a `review-threads` verdict takes the same dedicated arm a live poller message would.
+  const engine = await boot({
+    responses: {
+      "pr.merge-stall-probe": { mergeState: "review-threads", failingChecks: 0, failingChecksList: "", reviewThreads: 3 },
+    },
+  });
+  await engine.publishMessage({ name: "deps-cleared", correlationKey: "pr-1" });
+  await engine.advanceTime(MERGEABLE_WAIT_MS + 1);
+  await assertThatUserTask(engine, { instance: byProcessId("merge-loop"), elementId: "wait-merge-answer" }).isCreated();
+  assertThatInstance(engine, byProcessId("merge-loop")).hasCompletedElements("merge-stall-probe", "merge-esc-threads");
+  const q = String(escalation(engine).question ?? "");
+  assertStringIncludes(q, "3 unresolved review thread(s)", "the probe path must carry the thread count into the question");
+  assert(!completedElementIds(engine).has("wait-mergeable-repoll"), "a settled review-threads verdict must not re-poll");
+});
+
+test("a stall-budget exhaustion on a settled BLOCKED with zero threads names the review requirement, not 'never settled' (#921)", async () => {
+  // GitHub settled: MERGEABLE/BLOCKED, checks green (none failing, none pending), every thread
+  // resolved — the block is a required human review approval. The probe reports `waiting` (the
+  // conservative verdict) with the probed counts, and the exhausted-budget escalation must name
+  // THAT cause.
+  const engine = await boot({
+    vars: { mergeStallMax: 0 },
+    responses: {
+      "pr.merge-stall-probe": { mergeState: "waiting", failingChecks: 0, failingChecksList: "", reviewThreads: 0, pendingChecks: 0 },
+    },
+  });
+  await engine.publishMessage({ name: "deps-cleared", correlationKey: "pr-1" });
+  await engine.advanceTime(MERGEABLE_WAIT_MS + 1);
+  await assertThatUserTask(engine, { instance: byProcessId("merge-loop"), elementId: "wait-merge-answer" }).isCreated();
+  assertThatInstance(engine, byProcessId("merge-loop")).hasCompletedElements("merge-stall-probe", "merge-esc-conflict");
+  const q = String(escalation(engine).question ?? "");
+  assertStringIncludes(q, "required review approval", "a settled BLOCKED with clear threads must name the review requirement");
+  assert(!q.includes("never settled"), "a settled BLOCKED must never read as 'mergeability never settled'");
+});
+
+test("a stall-budget exhaustion with checks still pending must NOT claim a verified review-approval blocker (PR #922 review)", async () => {
+  // Zero failing checks + zero unresolved threads, but a check is still queued/running: the BLOCKED
+  // cause is undetermined (the pending run may come back red), so the escalation must NOT assert
+  // "all checks green … required review approval" — it keeps the conservative unsettled wording.
+  const engine = await boot({
+    vars: { mergeStallMax: 0 },
+    responses: {
+      "pr.merge-stall-probe": { mergeState: "waiting", failingChecks: 0, failingChecksList: "", reviewThreads: 0, pendingChecks: 1 },
+    },
+  });
+  await engine.publishMessage({ name: "deps-cleared", correlationKey: "pr-1" });
+  await engine.advanceTime(MERGEABLE_WAIT_MS + 1);
+  await assertThatUserTask(engine, { instance: byProcessId("merge-loop"), elementId: "wait-merge-answer" }).isCreated();
+  assertThatInstance(engine, byProcessId("merge-loop")).hasCompletedElements("merge-stall-probe", "merge-esc-conflict");
+  const q = String(escalation(engine).question ?? "");
+  assert(!q.includes("required review approval"), "a pending check must never read as a verified review-approval block");
+  assertStringIncludes(q, "never settled", "an undetermined BLOCKED keeps the conservative unsettled wording");
+});
+
+test("the 'never settled' question is reserved for a genuinely unreadable/unsettled mergeability (#921)", async () => {
+  // mergeStallMax: 0 + a probe that still reads `waiting` with NOTHING probed (reviewThreads -1,
+  // checks unenumerable) — GitHub genuinely never settled (or the state could not be read). Only
+  // this case keeps the original message.
+  const engine = await boot({
+    vars: { mergeStallMax: 0 },
+    responses: {
+      "pr.merge-stall-probe": { mergeState: "waiting", failingChecks: 0, failingChecksList: "", reviewThreads: -1 },
+    },
+  });
+  await engine.publishMessage({ name: "deps-cleared", correlationKey: "pr-1" });
+  await engine.advanceTime(MERGEABLE_WAIT_MS + 1);
+  await assertThatUserTask(engine, { instance: byProcessId("merge-loop"), elementId: "wait-merge-answer" }).isCreated();
+  assertStringIncludes(
+    String(escalation(engine).question ?? ""),
+    "never settled",
+    "a genuinely unsettled/unreadable mergeability keeps the original message",
+  );
+});
+
 test("an evicted queued merge re-arms the poller rather than completing", async () => {
   const engine = await boot({ responses: { "pr.merge": { mergeStatus: "queued" } } });
   await engine.publishMessage({ name: "deps-cleared", correlationKey: "pr-1" });

package/app/readiness.ts

@@ -768,6 +768,7 @@ export function parsePrView(payload: unknown): PrObservation {
     isDraft: j.isDraft === true,
     headRefOid: str(j.headRefOid).trim() || null,
     mergeQueueEntry: null, // readiness probe doesn't read native-queue membership (merge-loop-only signal)
+    unresolvedThreads: -1, // …nor the review-threads probe (merge-stage-only signal, #921) → unprobed
     mergedSha,
     pendingChecks: pending.length,
   };

package/app/service.ts

@@ -1698,6 +1698,77 @@ export async function maybeEnsureFreshHeadRun(
  * EVERY branch first runs {@link advanceIfTerminalOutOfBand} — one shared "is this PR already
  * terminal (merged/closed) out-of-band?" pre-check — so no merge stage can silently strand when a PR
  * is landed/closed outside the loop (the `waiting_deps` self-merged wedge, #368). */
+/** Durably hand a `waiting_merge` PR back into the canonical convergence loop (issue #921, PR #922
+ * review): flip the row to `waiting_review` FIRST (so a review landing in the start window is still
+ * collected by `pollReviews` — it scans on `waiting_review`, not on instance liveness), RETIRE the
+ * live merge instance (while the row's `process_key` names a non-terminal merge instance, `submitPr`'s
+ * idempotency gate classifies the PR `alreadyRunning` and starts NOTHING — the cancel flips the derived
+ * tracking status terminal so the gate falls through), then `submitPr` re-opens the PR into a fresh
+ * convergence instance (round 1). The review-round agent's backlog IS the open threads: it fixes or
+ * pushes back, replies, and resolves them; on `converged` the converge-gate re-verifies zero
+ * unresolved threads and `pr.finalize` re-enters the merge stage — merging resumes automatically.
+ *
+ * The escalation-steward opt-in is carried through the resubmission (PR #922 review): `submitPr`
+ * defaults `autoResolveEscalations` to false and overwrites the row's flag on reopen, so an opted-in PR
+ * would silently lose automated escalation resolution merely because late review threads appeared.
+ *
+ * RETRYABLE on failure (PR #922 review, thread 3): if the cancel succeeds but `submitPr` throws, the
+ * row is restored to `waiting_merge` so the next pass re-attempts the handoff against the
+ * already-retired (terminal) merge key — rather than stranding in `waiting_review`, which `pollMerges`
+ * no longer scans and whose `readiness-ready` resume correlates to nothing once the merge instance is
+ * cancelled. The restored row's `process_key` still names the now-terminal merge instance, so the
+ * unfinished handoff is re-detected next pass by the dead-owner guard in `pollMerges` (which keys off
+ * the terminal `derived_status`, independently of the GitHub verdict). Best-effort throughout: a failed
+ * cancel or restore only logs, leaving the row for the next pass. */
+async function handoffWaitingMergeToConvergence(
+  data: DataLayer,
+  engine: EngineClient,
+  pr: PullRequest,
+  logContext: string,
+) {
+  const prKey = pr.pr_key;
+  try {
+    // `waiting_since` bounds the review the fresh loop collects: only a review submitted at or after
+    // the handoff counts, so a pre-merge review (submitted before this flip) can never satisfy the new
+    // run's wait.
+    const handoffTs = now();
+    await prs(data).update(prKey, { status: "waiting_review", waiting_since: handoffTs, updated_at: handoffTs });
+    const mergeKey = pr.process_key;
+    if (mergeKey != null) {
+      try {
+        await engine.cancelInstance({ processInstanceKey: String(mergeKey) });
+      } catch (cancelErr) {
+        console.error(`[poller] ${logContext} handoff ${prKey}: retire merge instance ${mergeKey}: ${cancelErr}`);
+      }
+    }
+    await submitPr(
+      data,
+      engine,
+      { repo: pr.repo, number: pr.number, url: pr.url, prKey },
+      [],
+      MAX_ROUNDS,
+      false,
+      null,
+      false,
+      pr.auto_resolve_escalations === 1,
+    );
+    console.log(`[poller] ${logContext} -> handed back into convergence -> ${prKey}`);
+  } catch (err) {
+    console.error(`[poller] ${logContext} handoff ${prKey}: ${err}`);
+    // Restore the row to `waiting_merge` so the next pass re-attempts the handoff, and NULL the
+    // `process_key`: the merge instance was retired above (or never lived), so the row genuinely has
+    // NO live owner. The null key is the durable "unfinished handoff" marker the dead-owner guard in
+    // `pollMerges` keys on — and it is what distinguishes this retryable shape from a HUMAN cancel of a
+    // parked merge wait (which leaves `process_key` naming the terminated instance and must NOT be
+    // resurrected). Best-effort: a failed restore still leaves the original error logged.
+    try {
+      await prs(data).update(prKey, { status: "waiting_merge", process_key: null, updated_at: now() });
+    } catch (restoreErr) {
+      console.error(`[poller] ${logContext} handoff ${prKey}: restore waiting_merge: ${restoreErr}`);
+    }
+  }
+}
+
 export async function pollMerges(data: DataLayer, engine: EngineClient, token: string) {
   // 1) Dependencies merged?
   for (const pr of await prs(data).find({ status: "waiting_deps" })) {
@@ -1731,7 +1802,12 @@ export async function pollMerges(data: DataLayer, engine: EngineClient, token: s
   for (const pr of await prs(data).find({ status: "waiting_merge" })) {
     const { repo, number, pr_key: prKey } = pr;
     try {
-      const st = await fetchPrState(repo, number, token);
+      // Opt into the review-threads probe so a `BLOCKED` merge state is classified by its real
+      // cause (issue #921): unresolved review threads (branch protection
+      // `required_conversation_resolution`) surface as the `review-threads` verdict below instead
+      // of polling as "waiting" until the mergeable-wait timer escalates the misleading
+      // "mergeability never settled". One extra GraphQL read per pass per waiting PR.
+      const st = await fetchPrState(repo, number, token, { withReviewThreads: true });
       if (st === null) continue; // no transport → skip this PR (others may still advance)
       // Out-of-band terminal (merged/closed) → the shared pre-check publishes `merge-ready {ready}`,
       // routing through `gw-mergeable → attempt-merge` whose idempotent already-merged check completes
@@ -1739,6 +1815,39 @@ export async function pollMerges(data: DataLayer, engine: EngineClient, token: s
       // (#342/#350). Reuse the `st` we just read so we don't double-fetch. This is the proven terminal
       // path the whole class (#368) now shares.
       if (await advanceIfTerminalOutOfBand(data, engine, pr, token, st)) continue;
+      // DEAD-OWNER guard (PR #922 review, round 5): a `waiting_merge` row with `process_key === null`
+      // has NO live owner — the unfinished-handoff shape {@link handoffWaitingMergeToConvergence}
+      // leaves when its `submitPr` failed after the merge instance was retired (the restore nulls the
+      // key to mark exactly this). The verdict switch below must NOT run against it: every arm ends in
+      // `flipToMergingThenPublish`, which would publish `merge-ready`/`merge-evicted`/remediation
+      // correlated to a merge instance that no longer exists — the message is dropped and the row wedges
+      // at the transient `merging` with no live owner (a fresh `ready`/`conflict`/`blocked` verdict after
+      // the threads cleared is exactly the case the retry-restore leaves behind). Persist the handoff
+      // INDEPENDENTLY of the current GitHub verdict: re-establish a live convergence owner FIRST,
+      // publishing nothing. Keying on the NULL key — not on the terminal `derived_status` — is what
+      // keeps a HUMAN cancel of a parked merge wait (which leaves `process_key` naming the terminated
+      // instance) OUT of this path: a cancelled run must stay cancelled, never auto-resurrected. A
+      // normal merge wait always carries a live `process_key`, so this fires only on the
+      // ownerless-handoff shape. Placed after the out-of-band terminal pre-check so a merged/closed PR
+      // still takes the proven terminal path first.
+      if (pr.process_key == null) {
+        await handoffWaitingMergeToConvergence(data, engine, pr, "dead merge owner (unfinished handoff)");
+        continue;
+      }
+      // HUMAN-CANCEL guard (PR #922 review, round 5): a `waiting_merge` row whose `process_key` names a
+      // TERMINAL merge instance (`derived_status` folded to `abandoned`) was cancelled out-of-band. The
+      // verdict switch must NOT run against it either — publishing `merge-ready`/`merge-evicted`/
+      // remediation to the dead instance is dropped and wedges the row at `merging` (the reviewer's "a
+      // new conflict or check failure likewise sends remediation to the dead owner"). Unlike the
+      // unfinished-handoff shape above, a cancelled run must NOT be resurrected into convergence — the
+      // abandon protocol exists to stop exactly that orphaned side effect — so it is simply SKIPPED
+      // (left cancelled) with nothing published. A LIVE parked merge wait reads a non-terminal
+      // `derived_status` (`waiting_merge` ∈ activeStatuses), so this fires only on the cancelled shape.
+      const trackedMerge = await prsTracking(data).get(prKey);
+      if (trackedMerge && TERMINAL_STATUSES.includes(trackedMerge.derived_status)) {
+        console.log(`[poller] merge owner terminal (cancelled) — leaving ${prKey} abandoned, no merge message published`);
+        continue;
+      }
       // Load the repo's merge protocol ONCE per PR iteration and pass it into the classifier so the
       // protocol-aware backstop (#392) can gate a red DECLARED-required check even when GitHub reports
       // the PR as UNSTABLE. The same handle is reused by the frugal-CI fresh-head-run branch below.
@@ -1788,6 +1897,25 @@ export async function pollMerges(data: DataLayer, engine: EngineClient, token: s
         }
         continue; // GitHub still computing / checks pending
       }
+      if (verdict === "review-threads") {
+        // BLOCKED by unresolved review threads with every check green (issue #921): the threads are
+        // findings from the reviewer this loop converges with, so route them back into convergence
+        // rather than escalating to a human. Requesting another Copilot review alone does NOT
+        // remediate them: `pollReviews` only scans `waiting_review` rows, so a review landing while
+        // the PR sits in `waiting_merge` is never picked up and no review-fix agent ever activates
+        // (PR #922 review). The handoff is a DURABLE re-entry into the canonical convergence loop
+        // (see {@link handoffWaitingMergeToConvergence}). Once the fresh convergence instance exists,
+        // `pr.progress-check` parks the row back in `waiting_merge` after the round, where this
+        // block's verdict has by then flipped off `review-threads` (the gate guarantees it) — so this
+        // fires at most once per thread-blocked episode.
+        await handoffWaitingMergeToConvergence(
+          data,
+          engine,
+          pr,
+          `blocked by ${st.unresolvedThreads} unresolved review thread(s)`,
+        );
+        continue;
+      }
       if (verdict === "ready") {
         const lane = await mergeLaneDecisionForPr(data, prKey);
         if (lane?.isHeld) {
@@ -1807,6 +1935,16 @@ export async function pollMerges(data: DataLayer, engine: EngineClient, token: s
           // fix-ci task appends it to the agent prompt so the agent knows which gates to green.
           failingChecks: st.failingChecks,
           failingChecksList: st.failingCheckNames.join("\n"),
+          // The probed unresolved-thread count (issue #921) — carried so a later stall-budget
+          // escalation can name the real BLOCKED cause (and so the `review-threads` arm's question
+          // can quote it). `-1` when the probe was unreadable.
+          reviewThreads: st.unresolvedThreads,
+          // The pending-check count (PR #922 review): zero failing checks does not mean checks are
+          // green — a queued/running check leaves the BLOCKED cause undetermined, so the
+          // stall-escalation question gates its "required review approval" wording on this being 0
+          // too. 0 in token mode (checks unenumerable — the conservative `waiting` verdict already
+          // keeps the approval wording from firing there).
+          pendingChecks: st.pendingCheckNames.length,
         },
       });
       console.log(`[poller] mergeable=${verdict} (${st.mergeStateStatus}) -> ${prKey}`);

package/app/userTasks.ts

@@ -90,6 +90,7 @@ export const PR_ESCALATION_PRODUCER_ELEMENTS: readonly string[] = [
   "merge-esc-conflict",
   "merge-esc-attempt",
   "merge-esc-landed",
+  "merge-esc-threads",
 ];
 
 /** The ACP permission-prompt escalation (issue #559, ADR 0056) — the Tasks-inbox kind a bridged

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.205.0",
+  "version": "0.205.1",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",

package/resources/processes/merge-loop.bpmn

@@ -53,11 +53,15 @@
           <nano:extend name="mergeState" type="string" />
           <nano:extend name="failingChecks" type="integer" optional="true" />
           <nano:extend name="failingChecksList" type="string" optional="true" />
+          <nano:extend name="reviewThreads" type="integer" optional="true" />
+          <nano:extend name="pendingChecks" type="integer" optional="true" />
         </nano:shape>
         <nano:shape id="MergeReady" name="merge-ready message payload">
           <nano:extend name="mergeState" type="string" />
           <nano:extend name="failingChecks" type="integer" optional="true" />
           <nano:extend name="failingChecksList" type="string" optional="true" />
+          <nano:extend name="reviewThreads" type="integer" optional="true" />
+          <nano:extend name="pendingChecks" type="integer" optional="true" />
         </nano:shape>
         <nano:shape id="FixCiIn" name="CI fix — input">
           <nano:extend name="prKey" type="string" />
@@ -179,6 +183,7 @@
       <bpmn:outgoing>f_m_mRebase</bpmn:outgoing>
       <bpmn:outgoing>f_m_mWaiting</bpmn:outgoing>
       <bpmn:outgoing>f_m_mDraft</bpmn:outgoing>
+      <bpmn:outgoing>f_m_mThreads</bpmn:outgoing>
       <bpmn:outgoing>f_m_mBlocked</bpmn:outgoing>
     </bpmn:exclusiveGateway>
     <bpmn:serviceTask id="attempt-merge" name="Merge PR">
@@ -258,7 +263,7 @@
         </zeebe:properties>
         <zeebe:ioMapping>
           <zeebe:input source="=&#34;blocked&#34;" target="status" />
-          <zeebe:input source="=if mergeState = &#34;draft&#34; then &#34;This PR is in draft and can&#39;t be merged. Mark it ready (gh pr ready), then reply to retry.&#34; else if mergeState = &#34;waiting&#34; then &#34;GitHub never settled this PR&#39;s mergeability (still computing after repeated re-polls, or the state could not be read). Check the PR on GitHub — resolve any conflict or failing required check if present — then reply to retry.&#34; else &#34;This PR is not mergeable (state: &#34; + mergeState + &#34;). Resolve the conflict or failing required check on the branch, then reply to retry.&#34;" target="question" />
+          <zeebe:input source="=if mergeState = &#34;draft&#34; then &#34;This PR is in draft and can&#39;t be merged. Mark it ready (gh pr ready), then reply to retry.&#34; else if mergeState = &#34;waiting&#34; and reviewThreads = 0 and failingChecks = 0 and pendingChecks = 0 then &#34;This PR is merge-blocked with all checks green (none failing, none pending) and every review thread resolved. GitHub still reports BLOCKED, which means a required review approval (or code-owner review) is outstanding — nothing the automated loop can produce. Approve the PR (or adjust the branch-protection review requirement), then reply to retry.&#34; else if mergeState = &#34;waiting&#34; then &#34;GitHub never settled this PR&#39;s mergeability (still computing or checks still pending after repeated re-polls, or the state could not be read). Check the PR on GitHub — resolve any conflict or failing required check if present — then reply to retry.&#34; else &#34;This PR is not mergeable (state: &#34; + mergeState + &#34;). Resolve the conflict or failing required check on the branch, then reply to retry.&#34;" target="question" />
         </zeebe:ioMapping>
       </bpmn:extensionElements>
       <bpmn:incoming>f_m_mDraft</bpmn:incoming>
@@ -287,9 +292,26 @@
       <bpmn:incoming>f_mr_giveup</bpmn:incoming>
       <bpmn:outgoing>f_m_escA</bpmn:outgoing>
     </bpmn:serviceTask>
+    <bpmn:serviceTask id="merge-esc-threads" name="Escalate: unresolved review threads">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="pr.persist-escalation" />
+        <zeebe:properties>
+          <zeebe:property name="io.nanobpm.dataEnvelope.in" value="EscalationIn" />
+          <zeebe:property name="io.nanobpm.dataEnvelope.out" value="EscalationOut" />
+        </zeebe:properties>
+        <zeebe:ioMapping>
+          <zeebe:input source="=&#34;blocked&#34;" target="status" />
+          <zeebe:input source="=&#34;This PR is merge-blocked by &#34; + string(reviewThreads) + &#34; unresolved review thread(s) (branch protection requires every conversation resolved; all checks are green and there is no conflict). These are review findings the loop already converged, so a fresh review round cannot clear them without a reply. Resolve the threads on the PR (or reply with guidance — e.g. which threads to push back on), then reply to retry.&#34;" target="question" />
+          <zeebe:input source="=null" target="agentSlaJobType" />
+        </zeebe:ioMapping>
+      </bpmn:extensionElements>
+      <bpmn:incoming>f_m_mThreads</bpmn:incoming>
+      <bpmn:outgoing>f_m_escT</bpmn:outgoing>
+    </bpmn:serviceTask>
     <bpmn:exclusiveGateway id="gw-merge-escalated" name="escalation opened?" default="f_m_escReenter">
       <bpmn:incoming>f_m_escA</bpmn:incoming>
       <bpmn:incoming>f_m_escLanded</bpmn:incoming>
+      <bpmn:incoming>f_m_escT</bpmn:incoming>
       <bpmn:outgoing>f_m_escWait</bpmn:outgoing>
       <bpmn:outgoing>f_m_escReenter</bpmn:outgoing>
     </bpmn:exclusiveGateway>
@@ -732,6 +754,9 @@
     <bpmn:sequenceFlow id="f_m_mDraft" name="draft — mark ready (human)" sourceRef="gw-mergeable" targetRef="merge-esc-conflict">
       <bpmn:conditionExpression xsi:type="bpmn:tFormalExpression">=mergeState = "draft"</bpmn:conditionExpression>
     </bpmn:sequenceFlow>
+    <bpmn:sequenceFlow id="f_m_mThreads" name="blocked (unresolved review threads)" sourceRef="gw-mergeable" targetRef="merge-esc-threads">
+      <bpmn:conditionExpression xsi:type="bpmn:tFormalExpression">=mergeState = "review-threads"</bpmn:conditionExpression>
+    </bpmn:sequenceFlow>
     <bpmn:sequenceFlow id="f_mrp_probe" sourceRef="wait-mergeable-repoll" targetRef="merge-stall-probe" />
     <bpmn:sequenceFlow id="f_m_mBlocked" name="unclassified — auto-rebase" sourceRef="gw-mergeable" targetRef="gw-rebase" />
     <bpmn:sequenceFlow id="f_ci_go" name="within budget" sourceRef="gw-ci-fix" targetRef="SP_cifix">
@@ -773,6 +798,7 @@
     <bpmn:sequenceFlow id="f_m_done" sourceRef="mark-merged" targetRef="MergeEnd" />
     <bpmn:sequenceFlow id="f_m_escC" sourceRef="merge-esc-conflict" targetRef="wait-merge-answer" />
     <bpmn:sequenceFlow id="f_m_escA" sourceRef="merge-esc-attempt" targetRef="gw-merge-escalated" />
+    <bpmn:sequenceFlow id="f_m_escT" sourceRef="merge-esc-threads" targetRef="gw-merge-escalated" />
     <bpmn:sequenceFlow id="f_m_escWait" sourceRef="gw-merge-escalated" targetRef="wait-merge-answer">
       <bpmn:conditionExpression xsi:type="bpmn:tFormalExpression">=escalated = true</bpmn:conditionExpression>
     </bpmn:sequenceFlow>
@@ -833,7 +859,7 @@
       <bpmndi:BPMNShape id="BPMNShape_gw-merge-stall" bpmnElement="gw-merge-stall" isMarkerVisible="true">
         <dc:Bounds x="1538" y="1535" width="50" height="50" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="1521" y="1650" width="85" height="42" />
+          <dc:Bounds x="1521" y="1630" width="85" height="42" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_gw-mergeable" bpmnElement="gw-mergeable" isMarkerVisible="true">
@@ -902,6 +928,9 @@
       <bpmndi:BPMNShape id="BPMNShape_merge-esc-attempt" bpmnElement="merge-esc-attempt">
         <dc:Bounds x="1688" y="720" width="100" height="80" />
       </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="BPMNShape_merge-esc-threads" bpmnElement="merge-esc-threads">
+        <dc:Bounds x="1138" y="1680" width="100" height="80" />
+      </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_gw-merge-escalated" bpmnElement="gw-merge-escalated" isMarkerVisible="true">
         <dc:Bounds x="2088" y="95" width="50" height="50" />
         <bpmndi:BPMNLabel>
@@ -1002,7 +1031,7 @@
         <di:waypoint x="402" y="1300" />
         <di:waypoint x="402" y="320" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="446" y="1239" width="88" height="56" />
+          <dc:Bounds x="919" y="1239" width="88" height="56" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_reb_rearm" bpmnElement="f_reb_rearm">
@@ -1179,6 +1208,14 @@
           <dc:Bounds x="1057" y="483" width="85" height="42" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="BPMNEdge_f_m_mThreads" bpmnElement="f_m_mThreads">
+        <di:waypoint x="1013" y="305" />
+        <di:waypoint x="1013" y="1720" />
+        <di:waypoint x="1138" y="1720" />
+        <bpmndi:BPMNLabel>
+          <dc:Bounds x="1018" y="1642" width="81" height="56" />
+        </bpmndi:BPMNLabel>
+      </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_m_mBlocked" bpmnElement="f_m_mBlocked">
         <di:waypoint x="1013" y="305" />
         <di:waypoint x="1013" y="440" />
@@ -1255,7 +1292,7 @@
         <di:waypoint x="1668" y="740" />
         <di:waypoint x="1688" y="740" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="1952" y="616" width="53" height="14" />
+          <dc:Bounds x="1932" y="616" width="53" height="14" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_m_gAbandoned" bpmnElement="f_m_gAbandoned">
@@ -1281,8 +1318,9 @@
         <di:waypoint x="870" y="618" />
         <di:waypoint x="870" y="638" />
         <di:waypoint x="888" y="638" />
-        <di:waypoint x="888" y="1598" />
-        <di:waypoint x="1338" y="1598" />
+        <di:waypoint x="888" y="1780" />
+        <di:waypoint x="1388" y="1780" />
+        <di:waypoint x="1388" y="1600" />
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_msp_gate" bpmnElement="f_msp_gate">
         <di:waypoint x="1438" y="1560" />
@@ -1308,6 +1346,14 @@
         <di:waypoint x="1988" y="120" />
         <di:waypoint x="2088" y="120" />
       </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="BPMNEdge_f_m_escT" bpmnElement="f_m_escT">
+        <di:waypoint x="1238" y="1720" />
+        <di:waypoint x="2008" y="1720" />
+        <di:waypoint x="2008" y="145" />
+        <di:waypoint x="2068" y="145" />
+        <di:waypoint x="2068" y="120" />
+        <di:waypoint x="2088" y="120" />
+      </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_m_escWait" bpmnElement="f_m_escWait">
         <di:waypoint x="2138" y="120" />
         <di:waypoint x="2238" y="120" />
@@ -1327,13 +1373,13 @@
         <di:waypoint x="1013" y="1620" />
         <di:waypoint x="1013" y="305" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="1446" y="1587" width="85" height="28" />
+          <dc:Bounds x="1246" y="1587" width="85" height="28" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_dep_rewait" bpmnElement="f_dep_rewait">
         <di:waypoint x="1738" y="1280" />
-        <di:waypoint x="1738" y="1640" />
-        <di:waypoint x="234" y="1640" />
+        <di:waypoint x="1738" y="1300" />
+        <di:waypoint x="234" y="1300" />
         <di:waypoint x="234" y="298" />
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_mr_go" bpmnElement="f_mr_go">

package/workers/merge-stall-probe/worker.ts

@@ -33,6 +33,14 @@ interface Out extends Record<string, unknown> {
   mergeState: string;
   failingChecks: number;
   failingChecksList: string;
+  // The unresolved-review-thread count behind a `review-threads` verdict (issue #921), mirrored
+  // into the escalation question so a human sees exactly what blocks the merge. `-1` = unprobed.
+  reviewThreads: number;
+  // The pending-check count (PR #922 review): zero failing checks does not mean checks are green —
+  // a queued/running check leaves the BLOCKED cause undetermined, so the stall-escalation question
+  // gates its "required review approval" wording on this being 0 too (never claims a verified
+  // blocker off a half-settled rollup).
+  pendingChecks: number;
 }
 
 const handler: AppJobHandler<In, Out> = async (job, app) => {
@@ -44,10 +52,14 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
   // GitHub reports UNSTABLE. Any transport hiccup is treated as "still waiting" — never a spurious
   // ready/conflict verdict — so a bad read is surfaced as `waiting`, which `gw-mergeable` routes to
   // a bounded re-poll (#774) rather than misrouting the token to a wrong remediation arm; a
-  // genuinely stuck verdict still escalates once the `mergeStallMax` budget is exhausted.
-  const st = await fetchPrState(repo, prNumber, token).catch(() => null);
+  // genuinely stuck verdict still escalates once the `mergeStallMax` budget is exhausted. The read
+  // opts into the review-threads probe (`withReviewThreads`) so a `BLOCKED` merge state is
+  // classified by its real cause (issue #921) — unresolved review threads surface as the
+  // `review-threads` verdict and route to their own arm instead of re-polling until the budget
+  // exhausts into the misleading "mergeability never settled" escalation.
+  const st = await fetchPrState(repo, prNumber, token, { withReviewThreads: true }).catch(() => null);
   if (st === null) {
-    return { mergeState: "waiting", failingChecks: 0, failingChecksList: "" };
+    return { mergeState: "waiting", failingChecks: 0, failingChecksList: "", reviewThreads: -1, pendingChecks: 0 };
   }
   const protocol = await loadMergeProtocol(repo, token).catch(() => null);
   const mergeState = classifyMergeability(st, protocol ?? undefined);
@@ -64,6 +76,8 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
     // poller's `merge-ready` payload so fix-ci knows which gates to green.
     failingChecks: st.failingChecks,
     failingChecksList: st.failingCheckNames.join("\n"),
+    reviewThreads: st.unresolvedThreads,
+    pendingChecks: st.pendingCheckNames.length,
   };
 };