@nanobpm/nano-workforce 0.205.0 → 0.205.2

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

package/app/mergeRetry.test.ts

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

package/app/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/reviewWait.test.ts

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

package/app/reviewWait.ts

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

package/app/roundProgress.test.ts

@@ -24,8 +24,11 @@ test("routeProgress: an addressed round whose head advanced continues", () => {
 
 test("routeProgress: an explicit non-addressed round always continues (no push is expected)", () => {
   // These are the statuses gw-status routes AWAY from the addressed/default arm — a legit no-push
-  // round. They always continue regardless of the head.
-  for (const status of ["waiting", "converged", "needs_input", "blocked"]) {
+  // round. They always continue regardless of the head. `review-stale` (#923 §4) joins them: the
+  // round re-entered via the converge gate's stale/missing-review path, so no reviewer verdict was
+  // obtained and no push was claimed — it must continue to the review wait, never escalate as
+  // no-progress.
+  for (const status of ["waiting", "converged", "needs_input", "blocked", "review-stale"]) {
     assertEquals(
       routeProgress(status, "sha-1", "sha-1"),
       "continue",
@@ -280,6 +283,64 @@ test("progress-check: a non-addressed round records the baseline and consumes th
   );
 });
 
+test("progress-check: a review-stale re-entry parks with waiting_since at the gate's reviewWaitCutoff, not the park time", async () => {
+  // Issue #923 review ("previously missed"): the converge-gate decides stale/missing from ITS review
+  // read, but the loop parks several tasks later — and the old park stamped `waiting_since` at the
+  // (later) park time. A head-current review landing in that read→park window was then REJECTED by
+  // `pollReviews` (`submitted_at >= waiting_since`), so the loop re-solicited and could time out
+  // despite a valid verdict already sitting unconsumed on the PR. The gate emits `reviewWaitCutoff`
+  // (its read time); the park must stamp `waiting_since` at THAT cutoff so the in-window review
+  // satisfies the wait.
+  const CUTOFF = "2026-11-08T01:00:00.000Z"; // the gate's review-read time (earlier than "now")
+  const handler = await makeUnderTest(
+    async () => "sha-2",
+    async () => ({ work: true, consumedKey: "9" }),
+  );
+  const { app, updates } = fakeApp({ last_round_head: "sha-1" });
+  const out = await handler(
+    {
+      processInstanceKey: "pik",
+      variables: {
+        prKey: "o/r#1",
+        status: "waiting",
+        repo: "o/r",
+        prNumber: 1,
+        reviewWaitCutoff: CUTOFF,
+      },
+    } as any,
+    app as any,
+  );
+  assertEquals(out, { progressed: true, huskRetries: 0 });
+  assertEquals(updates.length, 1, "one atomic park write");
+  assertEquals(updates[0]!.patch.status, "waiting_review", "the round parks for review");
+  assertEquals(
+    updates[0]!.patch.waiting_since,
+    CUTOFF,
+    "waiting_since is stamped at the gate's review-read cutoff, so a review landing in the read→park window satisfies the wait",
+  );
+});
+
+test("progress-check: a normal round (no reviewWaitCutoff) still stamps waiting_since at the park time", async () => {
+  // The cutoff is only emitted on a review-stale re-entry. A normal round carries no
+  // `reviewWaitCutoff`, so the park falls back to "now" — the pre-fix behaviour every existing test
+  // relies on.
+  const handler = await makeUnderTest(
+    async () => "sha-2",
+    async () => ({ work: true, consumedKey: "9" }),
+  );
+  const { app, updates } = fakeApp({ last_round_head: "sha-1" });
+  await handler(
+    { processInstanceKey: "pik", variables: { prKey: "o/r#1", status: "waiting", repo: "o/r", prNumber: 1 } } as any,
+    app as any,
+  );
+  assertEquals(updates[0]!.patch.status, "waiting_review");
+  const stamped = updates[0]!.patch.waiting_since;
+  assertEquals(typeof stamped, "string", "a park time is stamped");
+  // Not the (absent) cutoff — a fresh "now" timestamp, i.e. close to the wall clock.
+  const driftMs = Math.abs(Date.now() - Date.parse(stamped as string));
+  assertEquals(driftMs < 60_000, true, "waiting_since falls back to the park time when no cutoff is carried");
+});
+
 test("progress-check: a blank/unknown status is treated as addressed — reads the head and can report no progress", async () => {
   let called = false;
   const handler = await makeUnderTest(async () => {

package/app/roundProgress.ts

@@ -39,6 +39,12 @@ const NON_ADDRESSED_STATUSES: ReadonlySet<string> = new Set([
   "converged",
   "needs_input",
   "blocked",
+  // `review-stale` (issue #923 §4): the round re-entered persist-round via the converge gate's
+  // stale/missing-review path (f_convergeStale) — no head-current reviewer verdict was ever
+  // obtained, so the round claims no push and must always continue to the review wait (the poller
+  // re-solicits a fresh review of the current head). Treating it as `addressed` would fabricate a
+  // no-progress escalation on a round that never claimed progress.
+  "review-stale",
 ]);
 
 /** True when a round's status is `addressed` for no-progress purposes — i.e. NOT one of the

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.2",
   "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/convergence-loop.bpmn

@@ -42,6 +42,7 @@
           <nano:extend name="round" type="integer" optional="true" />
           <nano:extend name="huskRetries" type="integer" optional="true" />
           <nano:extend name="roundEntryHead" type="string" optional="true" />
+          <nano:extend name="reviewWaitCutoff" type="string" optional="true" />
         </nano:shape>
         <nano:shape id="PrCaptureHeadIn" name="Capture round-entry head — input">
           <nano:extend name="prKey" type="string" />
@@ -68,6 +69,7 @@
           <nano:extend name="convergeBlockReason" type="string" optional="true" />
           <nano:extend name="convergeAckOnly" type="boolean" optional="true" />
           <nano:extend name="reviewStale" type="boolean" optional="true" />
+          <nano:extend name="reviewWaitCutoff" type="string" optional="true" />
         </nano:shape>
         <nano:shape id="EscalationIn" name="Record escalation — input">
           <nano:extend name="prKey" type="string" />
@@ -307,6 +309,9 @@
         <zeebe:properties>
           <zeebe:property name="io.nanobpm.dataEnvelope.in" value="PrPersistRoundIn" />
         </zeebe:properties>
+        <zeebe:ioMapping>
+          <zeebe:input source="=if reviewStale = true then &#34;review-stale&#34; else status" target="status" />
+        </zeebe:ioMapping>
       </bpmn:extensionElements>
       <bpmn:incoming>f_advSkip</bpmn:incoming>
       <bpmn:incoming>f_advClean</bpmn:incoming>