@nanobpm/nano-workforce 0.208.5 → 0.209.1

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [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
+
+* **nav:** green Delivery Graphs badge counting staged proposals awaiting approval ([#954](https://github.com/nanobpm/nano-workforce/issues/954)) ([21622b4](https://github.com/nanobpm/nano-workforce/commit/21622b4529383c575de7ffcf77548a704353c4d4))
+
 ## [0.208.5](https://github.com/nanobpm/nano-workforce/compare/v0.208.4...v0.208.5) (2026-11-11)
 
 ### Bug Fixes

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.208.5",
-  "gitSha": "c3f19d50ef6cf4f731f50ab778b5cd7ebdb3454e",
-  "gitTag": "v0.208.5",
-  "builtAt": "2026-11-11T09:26:21.393Z"
+  "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.208.5",
+  "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",