@nanobpm/nano-workforce 0.209.0 → 0.209.1

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.209.1](https://github.com/nanobpm/nano-workforce/compare/v0.209.0...v0.209.1) (2026-11-12)
+
+### Bug Fixes
+
+* **merge-loop:** land CLEAN mergify-queue PRs instead of escalating; never escalate merged PRs ([#953](https://github.com/nanobpm/nano-workforce/issues/953)) ([5b70c17](https://github.com/nanobpm/nano-workforce/commit/5b70c1733cd919fcc8f43ca118a863d3714030ea)), closes [#951](https://github.com/nanobpm/nano-workforce/issues/951) [#951](https://github.com/nanobpm/nano-workforce/issues/951)
+
 ## [0.209.0](https://github.com/nanobpm/nano-workforce/compare/v0.208.5...v0.209.0) (2026-11-12)
 
 ### Features

package/app/behindBaseRemedy.test.ts

@@ -0,0 +1,115 @@
+// Issue #951 (comment): failing checks on a head BEHIND its base must be remedied mechanically —
+// update the branch from base (and close/reopen on a reopen-CI repo) — instead of re-escalating
+// "failing required checks" to a human.
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import { _resetBehindBaseLatch, BEHIND_BASE_PENDING_MS, type BehindBaseDeps, isBehindBaseUpdatePending, maybeUpdateBehindBranch } from "./behindBaseRemedy.ts";
+import type { PrState } from "./github.ts";
+import { DEFAULT_MERGE_PROTOCOL, type MergeProtocol } from "./mergeProtocol.ts";
+
+function st(over: Partial<PrState> = {}): PrState {
+  return {
+    merged: false,
+    state: "open",
+    mergeStateStatus: "BLOCKED",
+    failingChecks: 1,
+    failingCheckNames: ["build"],
+    presentCheckNames: ["build"],
+    pendingCheckNames: [],
+    checkConclusions: { build: "FAILURE" },
+    totalChecks: 1,
+    isDraft: false,
+    headRefOid: "head1",
+    mergeQueueEntry: null,
+    unresolvedThreads: 0,
+    ...over,
+  };
+}
+
+const REOPEN: MergeProtocol = { ...DEFAULT_MERGE_PROTOCOL, freshHeadRun: "ready-or-reopen" };
+
+function deps(behindBy: number, calls: string[], updateOk = true, clock = { t: 0 }): BehindBaseDeps {
+  return {
+    readBase: () => Promise.resolve("main"),
+    compare: () => Promise.resolve({ status: behindBy > 0 ? "diverged" : "ahead", aheadBy: 1, behindBy }),
+    updateBranch: (_r, _n, _t, sha) => {
+      calls.push(`update@${sha}`);
+      return Promise.resolve(updateOk);
+    },
+    now: () => clock.t,
+  };
+}
+
+test("failing checks on a behind head, reopen-CI repo: update-branch only — never reopen the stale head (#951)", async () => {
+  _resetBehindBaseLatch();
+  const calls: string[] = [];
+  assertEquals(await maybeUpdateBehindBranch("o/r", 1, "t", st(), REOPEN, deps(3, calls)), true);
+  assertEquals(calls, ["update@head1"]);
+});
+
+test("an accepted (async) update HOLDS the old head until it moves — stale failures never reach fix-ci (#951)", async () => {
+  _resetBehindBaseLatch();
+  const calls: string[] = [];
+  const clock = { t: 0 };
+  const d = deps(3, calls, true, clock);
+  assertEquals(await maybeUpdateBehindBranch("o/r", 1, "t", st(), REOPEN, d), true);
+  clock.t = 60_000; // next poll: GitHub has not applied the update yet
+  assertEquals(await maybeUpdateBehindBranch("o/r", 1, "t", st(), REOPEN, d), true);
+  assertEquals(calls, ["update@head1"]);
+  // The new head appears (up to date) and is still red → falls through to fix-ci.
+  assertEquals(await maybeUpdateBehindBranch("o/r", 1, "t", st({ headRefOid: "head2" }), REOPEN, deps(0, calls, true, clock)), false);
+});
+
+test("a pending update that never applies stops holding after the bounded window (#951)", async () => {
+  _resetBehindBaseLatch();
+  const calls: string[] = [];
+  const clock = { t: 0 };
+  const d = deps(3, calls, true, clock);
+  assertEquals(await maybeUpdateBehindBranch("o/r", 1, "t", st(), REOPEN, d), true);
+  clock.t = BEHIND_BASE_PENDING_MS;
+  assertEquals(await maybeUpdateBehindBranch("o/r", 1, "t", st(), REOPEN, d), false);
+});
+
+test("failing checks on a behind head, plain repo: update-branch only (#951)", async () => {
+  _resetBehindBaseLatch();
+  const calls: string[] = [];
+  assertEquals(await maybeUpdateBehindBranch("o/r", 1, "t", st(), DEFAULT_MERGE_PROTOCOL, deps(2, calls)), true);
+  assertEquals(calls, ["update@head1"]);
+});
+
+test("failing checks on an up-to-date head fall through to fix-ci (#951)", async () => {
+  _resetBehindBaseLatch();
+  const calls: string[] = [];
+  assertEquals(await maybeUpdateBehindBranch("o/r", 1, "t", st(), REOPEN, deps(0, calls)), false);
+  assertEquals(calls, []);
+});
+
+test("green checks never update the branch (#951)", async () => {
+  _resetBehindBaseLatch();
+  const calls: string[] = [];
+  assertEquals(await maybeUpdateBehindBranch("o/r", 1, "t", st({ failingChecks: 0 }), REOPEN, deps(5, calls)), false);
+  assertEquals(calls, []);
+});
+
+test("the remedy fires at most once per head (#951)", async () => {
+  _resetBehindBaseLatch();
+  const calls: string[] = [];
+  assertEquals(await maybeUpdateBehindBranch("o/r", 1, "t", st(), REOPEN, deps(3, calls, false)), false);
+  assertEquals(await maybeUpdateBehindBranch("o/r", 1, "t", st(), REOPEN, deps(3, calls)), false);
+  assertEquals(calls, ["update@head1"]);
+});
+
+// The merge-stall probe reads `isBehindBaseUpdatePending` to hold remediation on a stale head. It is
+// true only while the SAME head is held inside the bounded window — a moved head or a lapsed window
+// reads false, and it never mutates the pending state (the remedy still owns the lifecycle).
+test("isBehindBaseUpdatePending holds the old head only within the bounded window (#951)", async () => {
+  _resetBehindBaseLatch();
+  const clock = { t: 0 };
+  assertEquals(await maybeUpdateBehindBranch("o/r", 1, "t", st(), REOPEN, deps(3, [], true, clock)), true);
+  // Same head, inside the window → pending. A different head, or a lapsed window → not pending.
+  assertEquals(isBehindBaseUpdatePending("o/r", 1, "head1", () => clock.t), true);
+  assertEquals(isBehindBaseUpdatePending("o/r", 1, "head2", () => clock.t), false);
+  assertEquals(isBehindBaseUpdatePending("o/r", 1, "head1", () => clock.t + BEHIND_BASE_PENDING_MS), false);
+  // A PR with no accepted update is never pending.
+  assertEquals(isBehindBaseUpdatePending("o/r", 999, "head1", () => clock.t), false);
+});

package/app/behindBaseRemedy.ts

@@ -0,0 +1,95 @@
+// Behind-base remedy for failing required checks (issue #951).
+//
+// When a PR's required checks FAILED on a head that is BEHIND its base (e.g. CI infra was broken
+// and has since been fixed on the base branch), the mechanical fix is to bring the branch up to
+// date with its base — not to page a human or burn a fix-ci agent round on a defect that no longer
+// exists. GitHub's update-branch is ASYNCHRONOUS (202 Accepted): the head only moves later. So an
+// accepted update is tracked as PENDING and the old head is HELD (no fix-ci on its stale failures)
+// until the poller observes the new head (or a bounded window lapses). The fresh-head CI run for a
+// reopen-CI repo is then produced by the canonical frugal-CI remedy (`maybeEnsureFreshHeadRun`,
+// once per head) when the NEW head reads as "no required run yet" — never by reopening the stale
+// head here. Attempted at most ONCE per head: a still-red, up-to-date head falls through to fix-ci.
+import { compareCommits, fetchPrBase, type PrState, updatePrBranch } from "./github.ts";
+import type { MergeProtocol } from "./mergeProtocol.ts";
+
+/** How long an accepted (async) update may leave the old head in place before we stop holding it. */
+export const BEHIND_BASE_PENDING_MS = 10 * 60_000;
+
+export interface BehindBaseDeps {
+  readBase: (repo: string, number: number, token: string) => Promise<string | null>;
+  compare: typeof compareCommits;
+  updateBranch: typeof updatePrBranch;
+  now: () => number;
+}
+
+const realDeps: BehindBaseDeps = {
+  readBase: fetchPrBase,
+  compare: compareCommits,
+  updateBranch: updatePrBranch,
+  now: () => Date.now(),
+};
+
+/** Heads already remedied (`<repo>#<n>@<sha>`) — the once-per-head latch. In-process: a restart
+ * may retry once more, which is harmless (an up-to-date head compares `behindBy: 0`). */
+const attempted = new Set<string>();
+
+/** Accepted-but-not-yet-applied updates (`<repo>#<n>` → the old head + acceptance time). */
+const pending = new Map<string, { oldHead: string; at: number }>();
+
+/** Test-only: reset the once-per-head latch and pending updates. */
+export function _resetBehindBaseLatch(): void {
+  attempted.clear();
+  pending.clear();
+}
+
+/** Is an accepted (async) update-branch still holding `headOid` as the old head? The merge-stall
+ * probe reads this so it does not classify the old head's stale check failures as `blocked` (and
+ * start fix-ci / escalate) while GitHub has accepted — but not yet applied — the branch update
+ * (issue #951 review). Bounded by the same BEHIND_BASE_PENDING_MS window the remedy uses, so a
+ * never-applied update stops holding once the window lapses. Pure read: never mutates the map. */
+export function isBehindBaseUpdatePending(
+  repo: string,
+  number: number,
+  headOid: string,
+  now: () => number = () => Date.now(),
+): boolean {
+  const inflight = pending.get(`${repo}#${number}`);
+  return inflight !== undefined && inflight.oldHead === headOid && now() - inflight.at < BEHIND_BASE_PENDING_MS;
+}
+
+/** If `st` has failing checks on a head that is behind its base, update the branch from base.
+ * Returns `true` when an update was accepted OR is still pending on this (old) head — the caller
+ * should re-poll instead of dispatching fix-ci/escalating. Never throws. `_protocol` is accepted for
+ * call-site stability; the fresh-run nudge for the new head belongs to the frugal-CI remedy. */
+export async function maybeUpdateBehindBranch(
+  repo: string,
+  number: number,
+  token: string,
+  st: PrState,
+  _protocol: MergeProtocol | null | undefined,
+  deps: BehindBaseDeps = realDeps,
+): Promise<boolean> {
+  const prId = `${repo}#${number}`;
+  const inflight = pending.get(prId);
+  if (inflight) {
+    if (st.headRefOid === inflight.oldHead && deps.now() - inflight.at < BEHIND_BASE_PENDING_MS) return true;
+    pending.delete(prId); // the head moved (update applied) or the window lapsed — judge afresh
+  }
+  if (st.failingChecks <= 0 || !st.headRefOid || st.state !== "open") return false;
+  const latch = `${repo}#${number}@${st.headRefOid}`;
+  if (attempted.has(latch)) return false;
+  attempted.add(latch);
+  try {
+    const base = await deps.readBase(repo, number, token);
+    if (!base) return false;
+    const cmp = await deps.compare(repo, base, st.headRefOid, token);
+    if (!cmp || cmp.behindBy <= 0) return false;
+    const updated = await deps.updateBranch(repo, number, token, st.headRefOid);
+    if (!updated) return false;
+    pending.set(prId, { oldHead: st.headRefOid, at: deps.now() });
+    console.log(`[poller] failing checks on a head ${cmp.behindBy} behind '${base}' -> update-branch accepted (pending new head) ${repo}#${number}`);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/app/github.test.ts

@@ -2,8 +2,8 @@
 // a COMPLETE file list or a thrown error — never a silently truncated one that under-approximates
 // 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, 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 { assert, assertEquals, assertRejects } from "#test-assert";
+import { BaseBranchMustExistError, checkConclusions, hasCopilotWorkStarted, classifyBlockedCause, copilotWorkStartedSince, 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]`
@@ -1505,3 +1505,138 @@ test("updateBranchRef: CAS refuses (false) when the ref is absent/unreadable (nu
   );
   assertEquals(moved, false, "a deleted/unreadable base ref is not the validated state, so the move is refused");
 });
+
+// ── Mergify queue awaiting its enqueue comment is ready, not a "required review" (issue #951) ─────
+//
+// A `mergify-queue` repo (nano-bpm) reports a converged, green PR with Mergify's own check sitting at
+// NEUTRAL ("not queued yet") and GitHub may still report the merge BLOCKED on it. That is the PR
+// waiting for the declared land step (`@mergifyio queue`), not a human review requirement — so the
+// classifier must say `ready` (→ attempt-merge posts the queue comment), never `waiting` (→ stall
+// budget → the misleading "likely a required review approval" escalation).
+const MERGIFY_PROTOCOL = protocolWith({
+  land: { method: "mergify-queue", comment: "@mergifyio queue" },
+  requiredChecks: reqChecks("build"),
+  waitForChecks: true,
+});
+const MERGIFY_ROLLUP = [
+  { name: "build", conclusion: "SUCCESS" },
+  { name: "Mergify Merge Queue", conclusion: "NEUTRAL" },
+];
+
+for (const status of ["BLOCKED", "CLEAN"]) {
+  test(`classifyMergeability: ${status} + NEUTRAL Mergify queue check + mergify-queue land → ready (#951)`, () => {
+    const s = mergePrState({ mergeStateStatus: status, unresolvedThreads: 0, rollup: MERGIFY_ROLLUP });
+    assertEquals(classifyMergeability(s, MERGIFY_PROTOCOL), "ready");
+  });
+}
+
+test("classifyMergeability: BLOCKED + NEUTRAL Mergify check on a gh-merge repo still waits (#951)", () => {
+  const s = mergePrState({ mergeStateStatus: "BLOCKED", unresolvedThreads: 0, rollup: MERGIFY_ROLLUP });
+  assertEquals(classifyMergeability(s, protocolWith({ requiredChecks: reqChecks("build") })), "waiting");
+});
+
+test("classifyMergeability: BLOCKED mergify-queue repo with NO Mergify queue check still waits (#951)", () => {
+  const s = mergePrState({
+    mergeStateStatus: "BLOCKED",
+    unresolvedThreads: 0,
+    rollup: [{ name: "build", conclusion: "SUCCESS" }],
+  });
+  assertEquals(classifyMergeability(s, MERGIFY_PROTOCOL), "waiting");
+});
+
+test("classifyMergeability: BLOCKED mergify-queue repo with another NEUTRAL check still waits (#951)", () => {
+  const s = mergePrState({
+    mergeStateStatus: "BLOCKED",
+    unresolvedThreads: 0,
+    rollup: [...MERGIFY_ROLLUP, { name: "lint", conclusion: "NEUTRAL" }],
+  });
+  assertEquals(classifyMergeability(s, MERGIFY_PROTOCOL), "waiting");
+});
+
+test("copilotWorkStartedSince: only a copilot_work_started at/after the request counts (#951)", () => {
+  const since = "2026-11-11T10:00:00Z";
+  assertEquals(copilotWorkStartedSince([{ event: "review_requested", created_at: "2026-11-11T10:00:05Z" }], since), false);
+  assertEquals(copilotWorkStartedSince([{ event: "copilot_work_started", created_at: "2026-11-11T09:59:00Z" }], since), false);
+  assertEquals(copilotWorkStartedSince([{ event: "copilot_work_started", created_at: "2026-11-11T10:00:30Z" }], since), true);
+});
+
+test("copilotWorkStartedSince: a start in the SAME second as a ms-precise request counts (#951)", () => {
+  const since = "2026-11-11T10:00:00.750Z";
+  assertEquals(copilotWorkStartedSince([{ event: "copilot_work_started", created_at: "2026-11-11T10:00:00Z" }], since), true);
+  assertEquals(copilotWorkStartedSince([{ event: "copilot_work_started", created_at: "2026-11-11T09:59:59Z" }], since), false);
+});
+
+test("hasCopilotWorkStarted (token): paginates the timeline; a start on page 2 counts (#951)", async () => {
+  const pages = [
+    Array.from({ length: 100 }, () => ({ event: "commented", created_at: "2026-11-11T10:00:01Z" })),
+    [{ event: "copilot_work_started", created_at: "2026-11-11T10:00:02Z" }],
+  ];
+  const requests: string[] = [];
+  // biome-ignore lint/plugin: test stub shares the review-page fetch shape
+  const got = await withTokenFetch(reviewFetch(pages as unknown as GhReview[][], requests) as typeof fetch, () =>
+    hasCopilotWorkStarted("o/r", 1, "t", "2026-11-11T10:00:00Z"),
+  );
+  assertEquals(got, true);
+  assertEquals(requests.length, 2);
+});
+
+test("hasCopilotWorkStarted (token): a failed later page is UNKNOWN (null), not false (#951)", async () => {
+  const fetchImpl = (url: string | URL | Request): Promise<Response> => {
+    const page = Number(new URL(String(url)).searchParams.get("page") ?? "1");
+    if (page === 1) {
+      const headers = new Headers({ link: '<https://api.github.com/x?page=2>; rel="next"' });
+      return Promise.resolve(new Response(JSON.stringify([{ event: "commented" }]), { status: 200, headers }));
+    }
+    return Promise.resolve(new Response("boom", { status: 502 }));
+  };
+  const got = await withTokenFetch(fetchImpl as typeof fetch, () => hasCopilotWorkStarted("o/r", 1, "t", "2026-11-11T10:00:00Z"));
+  assertEquals(got, null);
+});
+
+// Issue #951 review: the verification caller has a fixed deadline, so the read must carry an abort
+// signal bounded by the remaining budget — a stalled read must not run unbounded and starve the
+// BPMN review-wait timer. Assert the token path passes a (timed) AbortSignal to fetch.
+test("hasCopilotWorkStarted (token): a timeout budget attaches an abort signal to the read (#951)", async () => {
+  let sawSignal: AbortSignal | undefined;
+  const fetchImpl = (_url: string | URL | Request, init?: RequestInit): Promise<Response> => {
+    sawSignal = init?.signal ?? undefined;
+    return Promise.resolve(new Response(JSON.stringify([{ event: "copilot_work_started", created_at: "2026-11-11T10:00:02Z" }]), { status: 200 }));
+  };
+  const got = await withTokenFetch(fetchImpl as typeof fetch, () =>
+    hasCopilotWorkStarted("o/r", 1, "t", "2026-11-11T10:00:00Z", { timeoutMs: 5_000 }),
+  );
+  assertEquals(got, true);
+  assertEquals(sawSignal instanceof AbortSignal, true);
+  assertEquals(sawSignal?.aborted, false);
+});
+
+test("hasCopilotWorkStarted (token): ONE abort signal bounds every page of the walk (#951)", async () => {
+  const signals: (AbortSignal | null | undefined)[] = [];
+  const fetchImpl = (_url: string | URL | Request, init?: RequestInit): Promise<Response> => {
+    signals.push(init?.signal);
+    const more = signals.length < 3;
+    return Promise.resolve(
+      new Response(JSON.stringify([{ event: "commented", created_at: "2026-11-11T10:00:02Z" }]), {
+        status: 200,
+        headers: more ? { link: '<https://api.github.com/x?page=2>; rel="next"' } : {},
+      }),
+    );
+  };
+  await withTokenFetch(fetchImpl as typeof fetch, () =>
+    hasCopilotWorkStarted("o/r", 1, "t", "2026-11-11T10:00:00Z", { timeoutMs: 5_000 }),
+  );
+  assertEquals(signals.length, 3);
+  assert(signals[0] instanceof AbortSignal);
+  assert(signals.every((s) => s === signals[0]), "every page must share the one budget signal");
+});
+
+test("hasCopilotWorkStarted (token): an aborted (timed-out) read is UNKNOWN (null), not false (#951)", async () => {
+  const fetchImpl = (_url: string | URL | Request, init?: RequestInit): Promise<Response> => {
+    // Simulate a read that exceeds the budget: reject with the abort reason.
+    return Promise.reject(init?.signal?.reason ?? new Error("aborted"));
+  };
+  const got = await withTokenFetch(fetchImpl as typeof fetch, () =>
+    hasCopilotWorkStarted("o/r", 1, "t", "2026-11-11T10:00:00Z", { timeoutMs: 1 }),
+  );
+  assertEquals(got, null);
+});

package/app/github.ts

@@ -716,7 +716,10 @@ export async function requestCopilotReview(
   const path = `repos/${repo}/pulls/${number}/requested_reviewers`;
   if (await useGh()) {
     try {
-      await runGh(["api", path, "-X", "POST", "-f", `reviewers[]=${COPILOT_REVIEWER}`]);
+      // `gh pr edit --add-reviewer @copilot` (issue #951): the REST POST with the bot login can add a
+      // `review_requested` event yet never start Copilot (`copilot_work_started` never appears); the
+      // gh-native @copilot reviewer path is the one that reliably triggers the review.
+      await runGh(["pr", "edit", String(number), "--repo", repo, "--add-reviewer", "@copilot"]);
       return "requested";
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
@@ -743,6 +746,73 @@ export async function requestCopilotReview(
   throw new Error(`github ${r.status} ${r.statusText}: ${(await r.text()).slice(0, 300)}`.trim());
 }
 
+/** Whether Copilot has STARTED working on a review request since `sinceIso` — a
+ * `copilot_work_started` event on the PR's issue timeline (issue #951). A request that produced
+ * `review_requested` but never `copilot_work_started` was silently dropped. `null` when no transport
+ * is usable or the read failed (unknown — callers must not treat it as "dropped").
+ *
+ * `opts.timeoutMs` bounds the WHOLE read (issue #951 review): the verification caller has a fixed
+ * deadline, so a stalled `gh` or REST read must not run past it and starve the BPMN review-wait
+ * timer. The `gh` path passes it to `runGh`'s process `timeout`; the REST path creates ONE
+ * `AbortSignal.timeout` before pagination and shares it across every page, so the whole walk —
+ * not each page — is bounded by the budget. A timeout surfaces as `null` (unknown), never `false`. */
+export async function hasCopilotWorkStarted(
+  repo: string,
+  number: number | string,
+  token: string,
+  sinceIso: string,
+  opts: { timeoutMs?: number } = {},
+): Promise<boolean | null> {
+  const path = `repos/${repo}/issues/${number}/timeline?per_page=100`;
+  try {
+    let events: { event?: string; created_at?: string }[];
+    if (await useGh()) {
+      const out = await runGh(
+        ["api", path, "--paginate", "--slurp", "-H", "Accept: application/vnd.github+json"],
+        opts.timeoutMs === undefined ? undefined : { timeoutMs: opts.timeoutMs },
+      );
+      // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
+      events = (JSON.parse(out) as { event?: string; created_at?: string }[][]).flat();
+    } else {
+      if (!token) return null;
+      // Walk EVERY page (mirrors the `gh --paginate` path): a `copilot_work_started` beyond the first
+      // 100 events must not read as "never started". An incomplete read (non-OK page, or the page cap
+      // still advertising `rel="next"`) is UNKNOWN (`null`), never `false`.
+      const MAX_PAGES = 20;
+      const signal = opts.timeoutMs === undefined ? undefined : AbortSignal.timeout(opts.timeoutMs);
+      events = [];
+      for (let page = 1; page <= MAX_PAGES; page++) {
+        const r = await fetch(`https://api.github.com/${path}&page=${page}`, {
+          headers: { authorization: `Bearer ${token}`, accept: "application/vnd.github+json" },
+          ...(signal === undefined ? {} : { signal }),
+        });
+        if (!r.ok) return null;
+        // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
+        const batch = (await r.json()) as { event?: string; created_at?: string }[];
+        if (!Array.isArray(batch)) return null;
+        events.push(...batch);
+        const hasNext = /<[^>]*>;\s*rel="next"/.test(r.headers.get("link") ?? "");
+        if (!hasNext) break;
+        if (page === MAX_PAGES) return copilotWorkStartedSince(events, sinceIso) ? true : null;
+      }
+    }
+    return copilotWorkStartedSince(events, sinceIso);
+  } catch {
+    return null;
+  }
+}
+
+/** Pure: does the timeline carry a `copilot_work_started` at/after `sinceIso`? GitHub timeline
+ * timestamps have WHOLE-SECOND precision, so the lower bound is floored to the second — otherwise a
+ * start in the same second as a millisecond-precise request time would never count. */
+export function copilotWorkStartedSince(events: { event?: string; created_at?: string }[], sinceIso: string): boolean {
+  const parsed = Date.parse(sinceIso);
+  const since = Number.isNaN(parsed) ? parsed : Math.floor(parsed / 1000) * 1000;
+  return events.some(
+    (e) => e.event === "copilot_work_started" && (Number.isNaN(since) || Date.parse(e.created_at ?? "") >= since),
+  );
+}
+
 /** Withdraw a pending Copilot review request (REST reviewers DELETE). Used by the merge loop's
  * head-current review request (issue #939) when a prior request was silently ignored: Copilot stays
  * listed as pending but never reviews, and a second POST is a no-op — removing and re-adding it is
@@ -1631,6 +1701,32 @@ function requiredChecksVerdict(s: PrState, protocol?: MergeProtocol): "blocked"
   return "pass";
 }
 
+/** True for Mergify's merge-queue check run (e.g. "Mergify Merge Queue" / "Mergify — Merge Queue"). */
+export function isMergifyQueueCheck(name: string): boolean {
+  return /mergify/i.test(name) && /queue/i.test(name);
+}
+
+const SETTLED_OK_CONCLUSIONS = new Set(["SUCCESS", "SKIPPED"]);
+
+/** Issue #951: is this BLOCKED PR merely waiting for the repo's declared `mergify-queue` land step?
+ * True only when the protocol lands via `mergify-queue`, checks are enumerable and settled (none
+ * failing, none pending), and every non-SUCCESS/SKIPPED check is a Mergify queue check at NEUTRAL —
+ * with at least one such check present. Anything else keeps the conservative `waiting`. */
+export function awaitingMergifyEnqueue(s: PrState, protocol?: MergeProtocol): boolean {
+  if (protocol?.land.method !== "mergify-queue") return false;
+  if (s.failingChecks !== 0 || s.pendingCheckNames.length > 0) return false;
+  let sawMergifyNeutral = false;
+  for (const [name, conclusion] of Object.entries(s.checkConclusions)) {
+    if (SETTLED_OK_CONCLUSIONS.has(conclusion)) continue;
+    if (conclusion === "NEUTRAL" && isMergifyQueueCheck(name)) {
+      sawMergifyNeutral = true;
+      continue;
+    }
+    return false;
+  }
+  return sawMergifyNeutral;
+}
+
 export function classifyMergeability(s: PrState, protocol?: MergeProtocol): Mergeability {
   // A draft PR is NEVER landable — GitHub refuses the merge outright, whatever its checks say — so
   // draft outranks every other signal (issue #454). Surface it as a first-class verdict rather than
@@ -1723,6 +1819,11 @@ export function classifyMergeability(s: PrState, protocol?: MergeProtocol): Merg
           return "blocked";
         case "review-threads":
           return "review-threads";
+        case "reviews":
+          // Issue #951: on a `mergify-queue` repo a green, thread-free PR whose ONLY non-success
+          // check is Mergify's own queue check at NEUTRAL ("not queued yet") is waiting for the
+          // declared land step (`@mergifyio queue`), not a human review — land it.
+          return awaitingMergifyEnqueue(s, protocol) ? "ready" : "waiting";
         default:
           return "waiting";
       }
@@ -2321,3 +2422,38 @@ export async function ensurePromotionPr(
   if (!created) return null;
   return { ...created, created: true };
 }
+
+/** Bring a PR's head up to date with its base (GitHub's "Update branch" — `PUT
+ * /pulls/{n}/update-branch`, the API behind `gh pr update-branch`). `expectedHeadSha` pins the head
+ * the caller judged, so a concurrent push makes GitHub refuse (422) rather than merge base into a
+ * head nobody inspected. Returns whether GitHub accepted the update; never throws (best-effort —
+ * a refusal falls through to the caller's existing remediation). Issue #951. */
+export async function updatePrBranch(
+  repo: string,
+  number: number | string,
+  token: string,
+  expectedHeadSha: string | null,
+): Promise<boolean> {
+  const apiPath = `repos/${repo}/pulls/${number}/update-branch`;
+  try {
+    if (await useGh()) {
+      const args = ["api", "-X", "PUT", apiPath, "-H", "Accept: application/vnd.github+json"];
+      if (expectedHeadSha) args.push("-f", `expected_head_sha=${expectedHeadSha}`);
+      await runGh(args);
+      return true;
+    }
+    if (!token) return false;
+    const r = await fetch(`https://api.github.com/${apiPath}`, {
+      method: "PUT",
+      headers: {
+        authorization: `Bearer ${token}`,
+        accept: "application/vnd.github+json",
+        "content-type": "application/json",
+      },
+      body: JSON.stringify(expectedHeadSha ? { expected_head_sha: expectedHeadSha } : {}),
+    });
+    return r.ok;
+  } catch {
+    return false;
+  }
+}

package/app/mergeLoopBehaviour.test.ts

@@ -523,6 +523,55 @@ test("the stall-round cap escalates to a human instead of looping forever (#636)
   assert(!completedElementIds(engine).has("mark-merged"), "an exhausted stall must not mark-merged");
 });
 
+test("an exhausted stall budget re-polls (not escalates) while a behind-base update is pending (#951)", async () => {
+  // The probe reports `waiting` + `updatePending: true` (an accepted update-branch still exposes the
+  // old head). The remedy's own bounded hold owns liveness, so `gw-merge-stall` must re-poll rather
+  // than escalate even with `mergeStallMax` spent.
+  const engine = await boot({
+    vars: { mergeStallMax: 0 },
+    responses: {
+      "pr.merge-stall-probe": { mergeState: "waiting", updatePending: true, failingChecks: 0, failingChecksList: "" },
+    },
+  });
+  await engine.publishMessage({ name: "deps-cleared", correlationKey: "pr-1" });
+  await engine.advanceTime(MERGEABLE_WAIT_MS + 1);
+  assertThatInstance(engine, byProcessId("merge-loop")).isActive().hasActiveElement("wait-mergeable-repoll");
+  assert(!completedElementIds(engine).has("merge-esc-conflict"), "a pending update must not escalate");
+});
+
+test("an exhausted stall budget still escalates an ordinary waiting verdict (#951)", async () => {
+  const engine = await boot({
+    vars: { mergeStallMax: 0 },
+    responses: {
+      "pr.merge-stall-probe": { mergeState: "waiting", updatePending: false, failingChecks: 0, failingChecksList: "" },
+    },
+  });
+  await engine.publishMessage({ name: "deps-cleared", correlationKey: "pr-1" });
+  await engine.advanceTime(MERGEABLE_WAIT_MS + 1);
+  assertThatInstance(engine, byProcessId("merge-loop")).hasCompletedElements("merge-stall-probe", "merge-esc-conflict");
+});
+
+test("an exhausted stall budget whose probe re-reads a MERGED PR completes merged — never escalates (#951)", async () => {
+  // The probe re-reads PR state and surfaces `ready` for an already-merged PR (a human queued it while
+  // the loop waited). Even with the stall budget exhausted, `gw-merge-stall` must route a `ready`
+  // re-derivation to `attempt-merge` (whose already-merged short-circuit returns `merged`) rather
+  // than opening a "merge-blocked" escalation against a PR that has already landed.
+  const engine = await boot({
+    vars: { mergeStallMax: 0 },
+    responses: {
+      "pr.merge-stall-probe": { mergeState: "ready", failingChecks: 0, failingChecksList: "" },
+      "pr.merge": { mergeStatus: "merged" },
+    },
+  });
+  await engine.publishMessage({ name: "deps-cleared", correlationKey: "pr-1" });
+  await engine.advanceTime(MERGEABLE_WAIT_MS + 1);
+  assertThatInstance(engine, byProcessId("merge-loop"))
+    .hasCompleted()
+    .hasNoIncident()
+    .hasCompletedElements("merge-stall-probe", "attempt-merge", "mark-merged");
+  assert(!completedElementIds(engine).has("merge-esc-conflict"), "a merged PR must never escalate");
+});
+
 // ---------------------------------------------------------------------------
 // Async-UNKNOWN "waiting" verdict → bounded re-poll, NOT a human (issue #774)
 // ---------------------------------------------------------------------------

package/app/service.ts

@@ -13,6 +13,7 @@ import { matchAdjudication, prAdjudications, resetAdjudications } from "./adjudi
 import { AGENT_SLA_JOB_TYPES, recordAgentJobObservation } from "./agentActivationLedger.ts";
 import { completeEscalationAutoApplied, escalationFormId } from "./agentCompletion.ts";
 import { AGENT_SLA_TIMEOUT } from "./agentSla.ts";
+import { maybeUpdateBehindBranch } from "./behindBaseRemedy.ts";
 import {
   CAPS_RESOLVED_MESSAGE,
   type CapabilityNeed,
@@ -2646,6 +2647,12 @@ export async function pollMerges(data: DataLayer, engine: EngineClient, token: s
         );
         continue;
       }
+      if (verdict === "blocked" && (await maybeUpdateBehindBranch(repo, number, token, st, protocol))) {
+        // Issue #951: the checks failed on a head BEHIND its base (e.g. a CI-infra fix since landed on
+        // base) — update the branch (and reopen on a reopen-CI repo) and re-poll the fresh head
+        // instead of dispatching fix-ci / escalating "failing required checks". Once per head.
+        continue;
+      }
       if (verdict === "ready") {
         const lane = await mergeLaneDecisionForPr(data, prKey);
         if (lane?.isHeld) {

package/build-info.json

@@ -1,6 +1,6 @@
 {
-  "version": "0.209.0",
-  "gitSha": "21622b4529383c575de7ffcf77548a704353c4d4",
-  "gitTag": "v0.209.0",
-  "builtAt": "2026-11-12T05:08:52.210Z"
+  "version": "0.209.1",
+  "gitSha": "5b70c1733cd919fcc8f43ca118a863d3714030ea",
+  "gitTag": "v0.209.1",
+  "builtAt": "2026-11-12T07:16:21.905Z"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.209.0",
+  "version": "0.209.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

@@ -55,6 +55,7 @@
           <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:extend name="updatePending" type="boolean" optional="true" />
         </nano:shape>
         <nano:shape id="LandedProbeIn" name="Landed probe — input">
           <nano:extend name="prKey" type="string" />
@@ -846,7 +847,7 @@
     <bpmn:sequenceFlow id="f_mw_stall" sourceRef="wait-mergeable-timeout" targetRef="merge-stall-probe" />
     <bpmn:sequenceFlow id="f_msp_gate" sourceRef="merge-stall-probe" targetRef="gw-merge-stall" />
     <bpmn:sequenceFlow id="f_msp_rederive" name="re-derived — route to arm" sourceRef="gw-merge-stall" targetRef="gw-mergeable">
-      <bpmn:conditionExpression xsi:type="bpmn:tFormalExpression">=mergeStallRounds &lt;= mergeStallMax</bpmn:conditionExpression>
+      <bpmn:conditionExpression xsi:type="bpmn:tFormalExpression">=mergeStallRounds &lt;= mergeStallMax or mergeState = "ready" or updatePending = true</bpmn:conditionExpression>
     </bpmn:sequenceFlow>
     <bpmn:sequenceFlow id="f_msp_giveup" name="stall budget exhausted" sourceRef="gw-merge-stall" targetRef="merge-esc-conflict" />
     <bpmn:sequenceFlow id="f_m_ready" sourceRef="wait-mergeable" targetRef="gw-mergeable" />

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

@@ -0,0 +1,119 @@
+// pr.merge-stall-probe — issue #951: the probe must re-read PR state before the merge loop can
+// escalate. A PR that already MERGED (a human queued it while the loop waited) must surface `ready`
+// so `gw-merge-stall` routes it to `attempt-merge` (whose already-merged short-circuit ends the loop
+// as merged) instead of exhausting the stall budget into a "merge-blocked" escalation.
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import type { PrState } from "../../app/github.ts";
+import { DEFAULT_MERGE_PROTOCOL, type MergeProtocol } from "../../app/mergeProtocol.ts";
+import { noopLog } from "../../test/log.ts";
+import { makeHandler } from "./worker.ts";
+
+function state(over: Partial<PrState>): PrState {
+  return {
+    merged: false,
+    state: "open",
+    mergeStateStatus: "BLOCKED",
+    failingChecks: 0,
+    failingCheckNames: [],
+    presentCheckNames: ["build", "Mergify Merge Queue"],
+    pendingCheckNames: [],
+    checkConclusions: { build: "SUCCESS", "Mergify Merge Queue": "NEUTRAL" },
+    totalChecks: 2,
+    isDraft: false,
+    headRefOid: "abc",
+    mergeQueueEntry: null,
+    unresolvedThreads: 0,
+    ...over,
+  };
+}
+
+const MERGIFY: MergeProtocol = {
+  ...DEFAULT_MERGE_PROTOCOL,
+  land: { method: "mergify-queue", comment: "@mergifyio queue" },
+  requiredChecks: [{ name: "build", acceptedConclusions: ["success"] }],
+};
+
+async function run(st: PrState, protocol: MergeProtocol | null, isUpdatePending = false): Promise<Record<string, unknown>> {
+  const handler = makeHandler({
+    readState: () => Promise.resolve(st),
+    readProtocol: () => Promise.resolve(protocol),
+    isUpdatePending: () => isUpdatePending,
+  });
+  const job: any = { variables: { prKey: "o/r#1", repo: "o/r", prNumber: 1 } };
+  const app: any = { log: noopLog() };
+  return (await handler(job, app)) as Record<string, unknown>;
+}
+
+async function runNullRead(isUpdatePending = false): Promise<Record<string, unknown>> {
+  const handler = makeHandler({
+    readState: () => Promise.reject(new Error("GitHub unreachable")),
+    readProtocol: () => Promise.resolve(null),
+    isUpdatePending: () => isUpdatePending,
+  });
+  const job: any = { variables: { prKey: "o/r#1", repo: "o/r", prNumber: 1 } };
+  const app: any = { log: noopLog() };
+  return (await handler(job, app)) as Record<string, unknown>;
+}
+
+test("merge-stall-probe: a PR already MERGED surfaces `ready` (never an escalation) (#951)", async () => {
+  const out = await run(state({ merged: true, state: "merged", mergeStateStatus: "UNKNOWN" }), MERGIFY);
+  assertEquals(out.mergeState, "ready");
+});
+
+test("merge-stall-probe: a CLOSED PR surfaces `ready` so attempt-merge abandons it (#951)", async () => {
+  const out = await run(state({ state: "closed", mergeStateStatus: "UNKNOWN" }), null);
+  assertEquals(out.mergeState, "ready");
+});
+
+test("merge-stall-probe: green PR awaiting `@mergifyio queue` is `ready`, not a review stall (#951)", async () => {
+  const out = await run(state({}), MERGIFY);
+  assertEquals(out.mergeState, "ready");
+});
+
+test("merge-stall-probe: BLOCKED gh-merge PR with green checks still waits (#951)", async () => {
+  const out = await run(state({}), { ...MERGIFY, land: { method: "gh-merge" } });
+  assertEquals(out.mergeState, "waiting");
+});
+
+// Issue #951 review: while an accepted (async) update-branch still exposes the old head, the probe
+// must NOT classify that head's stale check failures as `blocked` (which starts fix-ci / escalates).
+// It defers to `waiting` (bounded re-poll) until the head moves or the remedy's window lapses.
+test("merge-stall-probe: a blocked verdict on a pending-update old head defers to waiting (#951)", async () => {
+  const blocked = state({ failingChecks: 1, failingCheckNames: ["build"], checkConclusions: { build: "FAILURE" } });
+  // Sanity: without a pending update this IS blocked (would route to fix-ci).
+  assertEquals((await run(blocked, MERGIFY, false)).mergeState, "blocked");
+  // With the update still pending on this head, the probe holds remediation.
+  const held = await run(blocked, MERGIFY, true);
+  assertEquals(held.mergeState, "waiting");
+  // The hold is surfaced so gw-merge-stall re-polls past the stall cap (only for this hold).
+  assertEquals(held.updatePending, true);
+  assertEquals((await run(blocked, MERGIFY, false)).updatePending, false);
+});
+
+test("merge-stall-probe: a non-blocked verdict is never downgraded by a pending update (#951)", async () => {
+  // A ready PR stays ready even if (spuriously) an update is pending — the hold only masks `blocked`.
+  const out = await run(state({}), MERGIFY, true);
+  assertEquals(out.mergeState, "ready");
+});
+
+// PR #953 review: a probe that emits `updatePending: true` is followed (next re-poll) by a read that
+// does NOT recompute the hold — a failed/null state read, or a terminal (merged/closed) liveness
+// short-circuit. Those paths must explicitly clear the flag: an omitted field would leave the stale
+// `true` standing, and `gw-merge-stall` would keep bypassing the stall cap on it even after the
+// remedy's bounded hold expired — a GitHub outage would turn the bounded hold into an indefinite
+// re-poll.
+test("merge-stall-probe: a failed/null state read clears updatePending (no stale cap bypass) (#953)", async () => {
+  const out = await runNullRead(true);
+  assertEquals(out.mergeState, "waiting");
+  assertEquals(out.updatePending, false);
+});
+
+test("merge-stall-probe: a terminal (merged/closed) read clears updatePending (#953)", async () => {
+  const merged = await run(state({ merged: true, state: "merged", mergeStateStatus: "UNKNOWN" }), MERGIFY, true);
+  assertEquals(merged.mergeState, "ready");
+  assertEquals(merged.updatePending, false);
+  const closed = await run(state({ state: "closed", mergeStateStatus: "UNKNOWN" }), null, true);
+  assertEquals(closed.mergeState, "ready");
+  assertEquals(closed.updatePending, false);
+});

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

@@ -17,8 +17,9 @@
 // (incremented by this task's output mapping, capped by `mergeStallMax`) stops the probe from
 // re-arming forever: once exhausted, `gw-merge-stall` routes to human escalation instead.
 import type { AppJobHandler } from "@nanobpm/urban";
-import { classifyMergeability, fetchPrState } from "../../app/github.ts";
-import { loadMergeProtocol } from "../../app/mergeProtocol.ts";
+import { isBehindBaseUpdatePending } from "../../app/behindBaseRemedy.ts";
+import { classifyMergeability, classifyPrLiveness, fetchPrState, type PrState } from "../../app/github.ts";
+import { loadMergeProtocol, type MergeProtocol } from "../../app/mergeProtocol.ts";
 import type { WorkerInputs } from "../../nano-generated/worker-io.d.ts";
 
 // Input typed off the model data envelope (`MergeStallProbeIn` in merge-loop.bpmn) — ADR 0040.
@@ -43,7 +44,25 @@ interface Out extends Record<string, unknown> {
   pendingChecks: number;
 }
 
-const handler: AppJobHandler<In, Out> = async (job, app) => {
+/** Injectable GitHub readers (tests stub them); the default export binds the real ones. */
+export interface StallProbeDeps {
+  readState: (repo: string, prNumber: number, token: string) => Promise<PrState | null>;
+  readProtocol: (repo: string, token: string) => Promise<MergeProtocol | null>;
+  /** Issue #951 review: is an accepted (async) update-branch still holding this head? While it is,
+   * the old head's stale check failures must NOT classify as `blocked` (which would start fix-ci /
+   * escalate) — the branch update is in flight and will move the head. Bounded by the remedy's own
+   * window, so a never-applied update stops holding. */
+  isUpdatePending: (repo: string, prNumber: number, headOid: string) => boolean;
+}
+
+const realDeps: StallProbeDeps = {
+  readState: (repo, prNumber, token) => fetchPrState(repo, prNumber, token, { withReviewThreads: true }),
+  readProtocol: (repo, token) => loadMergeProtocol(repo, token),
+  isUpdatePending: (repo, prNumber, headOid) => isBehindBaseUpdatePending(repo, prNumber, headOid),
+};
+
+export function makeHandler(deps: StallProbeDeps): AppJobHandler<In, Out> {
+  return async (job, app) => {
   const { repo, prNumber } = job.variables;
   const token = process.env.GITHUB_TOKEN ?? "";
 
@@ -57,12 +76,50 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
   // 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);
+  const st = await deps.readState(repo, prNumber, token).catch(() => null);
   if (st === null) {
-    return { mergeState: "waiting", failingChecks: 0, failingChecksList: "", reviewThreads: -1, pendingChecks: 0 };
+    // Explicitly clear `updatePending` (PR #953 review): a failed/null read returns `waiting`
+    // WITHOUT recomputing the hold, and an omitted field would leave any earlier `true` standing —
+    // `gw-merge-stall` would then keep bypassing the stall cap on the stale flag even after the
+    // remedy's bounded hold expired. Returning `false` keeps a GitHub outage from turning the
+    // bounded hold into an indefinite re-poll.
+    return { mergeState: "waiting", updatePending: false, failingChecks: 0, failingChecksList: "", reviewThreads: -1, pendingChecks: 0 };
+  }
+  // Issue #951: re-read PR liveness BEFORE any verdict. A PR that already MERGED (e.g. a human
+  // queued it while the loop waited) or was CLOSED must never reach an escalation: surface `ready`,
+  // which `gw-merge-stall` always routes (even past the stall budget) to `attempt-merge`, whose
+  // already-merged / closed short-circuits finish the loop as merged / abandoned.
+  const liveness = classifyPrLiveness(st);
+  if (liveness === "merged" || liveness === "closed") {
+    app.log.info("merge-stall-probe: PR already terminal — routing to attempt-merge short-circuit", {
+      prKey: job.variables.prKey,
+      liveness,
+    });
+    // `updatePending: false` here too: a terminal PR short-circuits the merge, so a stale hold
+    // from an earlier round must not survive into `gw-merge-stall`'s bypass-cap condition.
+    return { mergeState: "ready", updatePending: false, failingChecks: 0, failingChecksList: "", reviewThreads: 0, pendingChecks: 0 };
+  }
+  const protocol = await deps.readProtocol(repo, token).catch(() => null);
+  let mergeState = classifyMergeability(st, protocol ?? undefined);
+
+  // Issue #951 review: a `blocked` verdict on the OLD head while an accepted update-branch is still
+  // pending is a stale-read, not a real block — the poller's behind-base remedy is holding that head
+  // (no fix-ci on its stale failures) until GitHub applies the update and the head moves. Mirroring
+  // that hold here, the probe downgrades the verdict to `waiting` so `gw-mergeable` routes to the
+  // bounded re-poll (`wait-mergeable-repoll`) instead of dispatching fix-ci / escalating against a
+  // head that is about to change. The hold shares the remedy's bounded window, so a never-applied
+  // update stops holding and the next probe judges the (still-red) head afresh.
+  // `updatePending` is surfaced so `gw-merge-stall` keeps re-polling inside the remedy's bounded hold
+  // window even once `mergeStallMax` is spent (an ordinary `waiting` still respects the stall cap).
+  let updatePending = false;
+  if (mergeState === "blocked" && st.headRefOid && deps.isUpdatePending(repo, prNumber, st.headRefOid)) {
+    updatePending = true;
+    app.log.info("merge-stall-probe: behind-base update pending — deferring remediation until the head moves", {
+      prKey: job.variables.prKey,
+      head: st.headRefOid,
+    });
+    mergeState = "waiting";
   }
-  const protocol = await loadMergeProtocol(repo, token).catch(() => null);
-  const mergeState = classifyMergeability(st, protocol ?? undefined);
 
   app.log.info("merge-stall-probe: poller stalled — re-derived mergeability", {
     prKey: job.variables.prKey,
@@ -72,6 +129,7 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
 
   return {
     mergeState,
+    updatePending,
     // Carried for the CI-fix arm (mergeState "blocked" = a failed required check), mirroring the
     // poller's `merge-ready` payload so fix-ci knows which gates to green.
     failingChecks: st.failingChecks,
@@ -79,6 +137,9 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
     reviewThreads: st.unresolvedThreads,
     pendingChecks: st.pendingCheckNames.length,
   };
-};
+  };
+}
+
+const handler: AppJobHandler<In, Out> = makeHandler(realDeps);
 
 export default handler;

package/workers/request-review/worker.test.ts

@@ -21,6 +21,7 @@ function ops(over: Partial<ReviewRequestOps>, calls: string[]): ReviewRequestOps
     hasPending: async () => (calls.push("pending?"), false),
     remove: async () => calls.push("remove"),
     request: async () => (calls.push("request"), "requested"),
+    awaitStarted: async () => true,
     ...over,
   };
 }
@@ -52,3 +53,29 @@ test("Copilot not assignable reports unavailable; a transport error reports fail
   );
   assertEquals(await makeHandler(ops({ request: async () => null }, []))(job(0), app), { reviewRequest: "failed" });
 });
+
+// Issue #951: a request that produced `review_requested` but never `copilot_work_started` is stuck —
+// verify via the timeline and withdraw + retry ONCE before leaving it to the bounded wait.
+test("a request that never starts Copilot is withdrawn and retried once (#951)", async () => {
+  const calls: string[] = [];
+  const { app } = fakeApp();
+  const out = await makeHandler(
+    ops({ awaitStarted: async () => (calls.push("started?"), false) }, calls),
+  )(job(0), app);
+  assertEquals(out, { reviewRequest: "requested" });
+  assertEquals(calls, ["request", "started?", "remove", "request", "started?"]);
+});
+
+test("a request that starts Copilot is not retried (#951)", async () => {
+  const calls: string[] = [];
+  const { app } = fakeApp();
+  await makeHandler(ops({ awaitStarted: async () => (calls.push("started?"), true) }, calls))(job(0), app);
+  assertEquals(calls, ["request", "started?"]);
+});
+
+test("an unverifiable timeline (null) is not treated as a dropped request (#951)", async () => {
+  const calls: string[] = [];
+  const { app } = fakeApp();
+  await makeHandler(ops({ awaitStarted: async () => (calls.push("started?"), null) }, calls))(job(0), app);
+  assertEquals(calls, ["request", "started?"]);
+});

package/workers/request-review/worker.ts

@@ -11,7 +11,12 @@
 // second POST is then a no-op. On a re-request (round > 0) with Copilot still pending, withdraw the
 // request first and re-add it — the equivalent that re-triggers the review.
 import type { AppJobHandler } from "@nanobpm/urban";
-import { hasPendingCopilotReviewer, removeCopilotReviewer, requestCopilotReview } from "../../app/github.ts";
+import {
+  hasCopilotWorkStarted,
+  hasPendingCopilotReviewer,
+  removeCopilotReviewer,
+  requestCopilotReview,
+} from "../../app/github.ts";
 import type { WorkerInputs } from "../../nano-generated/worker-io.d.ts";
 
 // Input typed off the model data envelope (`RequestReviewIn` in merge-loop.bpmn) — ADR 0040.
@@ -28,6 +33,29 @@ export interface ReviewRequestOps {
   hasPending: (repo: string, prNumber: number) => Promise<boolean | null>;
   remove: (repo: string, prNumber: number) => Promise<unknown>;
   request: (repo: string, prNumber: number) => Promise<"requested" | "unavailable" | null>;
+  /** Issue #951: poll the PR timeline until Copilot STARTS the requested review
+   * (`copilot_work_started` at/after `sinceIso`) or the verify window (~2 min) elapses. `true` =
+   * started, `false` = the request was silently dropped, `null` = unverifiable (treated as started). */
+  awaitStarted: (repo: string, prNumber: number, sinceIso: string) => Promise<boolean | null>;
+}
+
+const VERIFY_WINDOW_MS = 120_000;
+const VERIFY_POLL_MS = 15_000;
+
+async function pollWorkStarted(repo: string, n: number, sinceIso: string): Promise<boolean | null> {
+  const deadline = Date.now() + VERIFY_WINDOW_MS;
+  for (;;) {
+    // Bound each read by the REMAINING verification budget (issue #951 review): the deadline is
+    // otherwise checked only AFTER the read returns, so a stalled `gh`/REST read could run past it
+    // and starve the BPMN review-wait timer. A read that exhausts its budget returns null (unknown)
+    // — surfaced as "started" (no spurious retry), and the loop stops because the deadline is met.
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) return false;
+    const started = await hasCopilotWorkStarted(repo, n, token(), sinceIso, { timeoutMs: remaining });
+    if (started !== false) return started;
+    if (Date.now() >= deadline) return false;
+    await new Promise((r) => setTimeout(r, Math.min(VERIFY_POLL_MS, deadline - Date.now())));
+  }
 }
 
 const token = () => process.env.GITHUB_TOKEN ?? "";
@@ -35,6 +63,7 @@ const defaultOps: ReviewRequestOps = {
   hasPending: (repo, n) => hasPendingCopilotReviewer(repo, n, token()),
   remove: (repo, n) => removeCopilotReviewer(repo, n, token()),
   request: (repo, n) => requestCopilotReview(repo, n, token()),
+  awaitStarted: pollWorkStarted,
 };
 
 export function makeHandler(ops: ReviewRequestOps): AppJobHandler<In, Out> {
@@ -47,7 +76,18 @@ export function makeHandler(ops: ReviewRequestOps): AppJobHandler<In, Out> {
       if (round > 0 && (await ops.hasPending(repo, prNumber)) === true) {
         await ops.remove(repo, prNumber);
       }
-      const res = await ops.request(repo, prNumber);
+      let since = new Date().toISOString();
+      let res = await ops.request(repo, prNumber);
+      // Issue #951: verify the request actually STARTED a review. A request that only produced
+      // `review_requested` (no `copilot_work_started`) is stuck — withdraw it and retry ONCE before
+      // leaving it to the bounded wait (and, past budget, the escalation).
+      if (res === "requested" && (await ops.awaitStarted(repo, prNumber, since)) === false) {
+        app.log.warn(`request-review: ${prKey} Copilot review request did not start — withdrawing and retrying once`);
+        await ops.remove(repo, prNumber);
+        since = new Date().toISOString();
+        res = await ops.request(repo, prNumber);
+        if (res === "requested") await ops.awaitStarted(repo, prNumber, since);
+      }
       result = res === "requested" ? "requested" : res === "unavailable" ? "unavailable" : "failed";
     } catch (err) {
       app.log.warn(`request-review: ${prKey} Copilot review request failed: ${err}`);