@nanobpm/nano-workforce 0.187.5 → 0.187.6

package/app/pollReviewsStale.test.ts

@@ -0,0 +1,187 @@
+// Behavioral regression for the poller's stale-review branch (#799, FM2).
+//
+// `pollReviews` must only resume the convergence loop on a review of the CURRENT head. When the PR
+// HEAD has advanced past the commit the newest review was submitted against, that review is STALE:
+// its advisories describe code the head already moved past. Publishing `readiness-ready` on it would
+// resume the loop on obsolete findings and re-escalate a human on an already-fixed advisory. The
+// poller must instead treat a stale review like "no fresh review" — (re-)solicit and wait — WITHOUT
+// advancing `last_review_id` or emitting the readiness signal.
+//
+// The pure `isReviewStale` predicate and the injected converge-gate already have coverage; this
+// test locks the poller's own STATE TRANSITION (which those cannot), driving the real token-mode
+// transport with a stubbed `fetch` so a differing branch-head SHA vs review `commit_id` is exercised
+// end-to-end. A control with a CURRENT-head review asserts the loop still resumes.
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import { withTrackingViews } from "../test/trackingViews.ts";
+import { READINESS_READY_MESSAGE } from "./readiness.ts";
+import { pollReviews } from "./service.ts";
+
+function memTable(rows: any[], key: string) {
+  return {
+    get: (k: any) => Promise.resolve(rows.find((r) => r[key] === k) ?? null),
+    all: () => Promise.resolve([...rows]),
+    find: (q: any) =>
+      Promise.resolve(rows.filter((r) => Object.entries(q).every(([f, v]) => r[f] === v))),
+    findOne: (q: any) =>
+      Promise.resolve(rows.find((r) => Object.entries(q).every(([f, v]) => r[f] === v)) ?? null),
+    insert: (r: any) => {
+      rows.push(r);
+      return Promise.resolve(r);
+    },
+    update: (k: any, patch: any) => {
+      const r = rows.find((x) => x[key] === k);
+      if (r) Object.assign(r, patch);
+      return Promise.resolve(r);
+    },
+    delete: (k: any) => {
+      for (let i = rows.length - 1; i >= 0; i--) if (rows[i][key] === k) rows.splice(i, 1);
+      return Promise.resolve();
+    },
+  };
+}
+
+const REPO = "owner/repo";
+const NUMBER = 7;
+const HEAD_REF = "feat/x";
+
+/** Stub the token transport for exactly the endpoints the stale-review branch reads:
+ *  - the paged reviews list (one short page → complete),
+ *  - the PR object (for the head ref/repo),
+ *  - the atomic branch ref (`git/ref/heads/<branch>`) the shared reader prefers, and
+ *  - the requested-reviewers GET/POST the re-solicitation nudge uses.
+ * `branchHead` drives staleness: when it differs from the review's `commit_id` the review is stale.
+ * Every non-GET request is recorded in `posts` so a test can assert the nudge's reviewer-request POST
+ * actually fired (a regression that dropped the stale branch's nudge would leave `posts` empty). */
+function reviewFetch(opts: { reviewCommitId: string; branchHead: string; posts: string[] }) {
+  return (url: string | URL | Request, init?: RequestInit): Promise<Response> => {
+    const u = typeof url === "string" ? url : url.toString();
+    const method = (init?.method ?? "GET").toUpperCase();
+    const json = (body: unknown, status = 200) =>
+      Promise.resolve(
+        new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json" } }),
+      );
+    if (u.includes(`/pulls/${NUMBER}/requested_reviewers`)) {
+      if (method !== "GET") {
+        opts.posts.push(`${method} ${u}`);
+        return json({}, 201); // reviewer requested
+      }
+      return json({ users: [] }); // none pending → the nudge proceeds to the POST
+    }
+    if (u.includes(`/pulls/${NUMBER}/reviews`)) {
+      return json([
+        { id: 5, state: "COMMENTED", submitted_at: "2026-09-16T00:45:33Z", commit_id: opts.reviewCommitId },
+      ]);
+    }
+    if (u.includes(`/git/ref/heads/${HEAD_REF}`)) {
+      return json({ object: { sha: opts.branchHead } });
+    }
+    if (u.endsWith(`/pulls/${NUMBER}`)) {
+      return json({ head: { ref: HEAD_REF, sha: opts.branchHead, repo: { full_name: REPO } }, base: { ref: "main" } });
+    }
+    throw new Error(`unexpected fetch: ${method} ${u}`);
+  };
+}
+
+function makeEngine() {
+  const published: Array<{ name: string; correlationKey: string }> = [];
+  const engine = {
+    publishMessage: (m: { name: string; correlationKey: string }) => {
+      published.push({ name: m.name, correlationKey: m.correlationKey });
+      return Promise.resolve();
+    },
+  } as any;
+  return { engine, published };
+}
+
+function withTokenTransport<T>(run: () => Promise<T>): Promise<T> {
+  const prevMode = process.env["NANO_PR_GITHUB_TRANSPORT"];
+  const prevTok = process.env["GITHUB_TOKEN"];
+  process.env["NANO_PR_GITHUB_TRANSPORT"] = "token";
+  process.env["GITHUB_TOKEN"] = "test-token";
+  return run().finally(() => {
+    if (prevMode !== undefined) process.env["NANO_PR_GITHUB_TRANSPORT"] = prevMode;
+    else delete process.env["NANO_PR_GITHUB_TRANSPORT"];
+    if (prevTok !== undefined) process.env["GITHUB_TOKEN"] = prevTok;
+    else delete process.env["GITHUB_TOKEN"];
+  });
+}
+
+function prRow() {
+  return {
+    pr_key: `${REPO}#${NUMBER}`,
+    repo: REPO,
+    number: NUMBER,
+    status: "waiting_review",
+    last_review_id: 0,
+    waiting_since: "2026-09-16T00:00:00Z",
+    // An EXPIRED nudge timestamp so `maybeRerequestReview` does NOT short-circuit at its cooldown —
+    // the stale branch must actually re-solicit a fresh review, and the test asserts that POST fired
+    // (a recent nudge would mask a regression that dropped the nudge entirely, #799 review).
+    last_nudge_at: "2000-01-01T00:00:00Z",
+    updated_at: "t0",
+  };
+}
+
+test("pollReviews: a STALE review (branch head past the review's commit) nudges but does NOT resume the loop", async () => {
+  const row = prRow();
+  const stores: Record<string, { rows: unknown[]; key: string }> = {
+    pull_requests: { rows: [row], key: "pr_key" },
+  };
+  const data = {
+    table: withTrackingViews((name: string, key: string) =>
+      memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key),
+    ),
+  } as any;
+  const { engine, published } = makeEngine();
+  const posts: string[] = [];
+  const prevFetch = globalThis.fetch;
+  await withTokenTransport(async () => {
+    // review was submitted against SHA_OLD, but the branch head has advanced to SHA_NEW → stale.
+    globalThis.fetch = reviewFetch({ reviewCommitId: "SHA_OLD", branchHead: "SHA_NEW", posts }) as typeof fetch;
+    try {
+      await pollReviews(data, engine, "test-token");
+    } finally {
+      globalThis.fetch = prevFetch;
+    }
+  });
+  assertEquals(published.length, 0, "no readiness-ready signal is published for a stale review");
+  assertEquals(row.last_review_id, 0, "last_review_id is NOT advanced past the stale review");
+  assertEquals(row.status, "waiting_review", "the PR stays parked awaiting a fresh review");
+  assertEquals(posts.length, 1, "the stale branch re-solicits a fresh Copilot review (one nudge POST)");
+  assertEquals(
+    posts[0],
+    `POST https://api.github.com/repos/${REPO}/pulls/${NUMBER}/requested_reviewers`,
+    "the nudge POSTs the requested-reviewers endpoint",
+  );
+});
+
+test("pollReviews: a CURRENT-head review (control) resumes the loop and publishes the readiness signal", async () => {
+  const row = prRow();
+  const stores: Record<string, { rows: unknown[]; key: string }> = {
+    pull_requests: { rows: [row], key: "pr_key" },
+  };
+  const data = {
+    table: withTrackingViews((name: string, key: string) =>
+      memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key),
+    ),
+  } as any;
+  const { engine, published } = makeEngine();
+  const posts: string[] = [];
+  const prevFetch = globalThis.fetch;
+  await withTokenTransport(async () => {
+    // review's commit_id equals the current branch head → NOT stale.
+    globalThis.fetch = reviewFetch({ reviewCommitId: "SHA_NEW", branchHead: "SHA_NEW", posts }) as typeof fetch;
+    try {
+      await pollReviews(data, engine, "test-token");
+    } finally {
+      globalThis.fetch = prevFetch;
+    }
+  });
+  assertEquals(published.length, 1, "the readiness-ready signal is published for a fresh review");
+  assertEquals(published[0]?.name, READINESS_READY_MESSAGE);
+  assertEquals(published[0]?.correlationKey, `${REPO}#${NUMBER}`);
+  assertEquals(row.last_review_id, 5, "last_review_id advances to the fresh review");
+  assertEquals(row.status, "converging", "the loop resumes (status flips to converging)");
+  assertEquals(posts.length, 0, "a current-head review resumes directly — no re-solicitation nudge");
+});

package/app/reviewWait.test.ts

@@ -9,6 +9,7 @@ import {
   DEFAULT_REVIEW_NUDGE_MINUTES,
   DEFAULT_REVIEW_WAIT_TIMEOUT,
   isoDurationToMs,
+  isReviewStale,
   MAX_REVIEW_NUDGE_MINUTES,
   reviewWaitTimeout,
 } from "./reviewWait.ts";
@@ -95,3 +96,35 @@ test("clampNudgeMinutes: above the ceiling is clamped, not rejected", () => {
 test("clampNudgeMinutes: an oversized fallback is itself clamped to the ceiling", () => {
   assertEquals(clampNudgeMinutes("", MAX_REVIEW_NUDGE_MINUTES + 50), MAX_REVIEW_NUDGE_MINUTES);
 });
+
+// ── isReviewStale (issue #799) ───────────────────────────────────────────────
+
+test("isReviewStale: differing review commit_id and HEAD sha is stale", () => {
+  assertEquals(isReviewStale("aaa1111", "bbb2222"), true);
+});
+
+test("isReviewStale: matching review commit_id and HEAD sha is NOT stale", () => {
+  assertEquals(isReviewStale("aaa1111", "aaa1111"), false);
+});
+
+test("isReviewStale: surrounding whitespace is ignored in the comparison", () => {
+  assertEquals(isReviewStale("  aaa1111 ", "aaa1111"), false);
+  assertEquals(isReviewStale("aaa1111", " bbb2222  "), true);
+});
+
+test("isReviewStale: a missing review commit_id fails safe to NOT stale", () => {
+  assertEquals(isReviewStale(null, "bbb2222"), false);
+  assertEquals(isReviewStale(undefined, "bbb2222"), false);
+  assertEquals(isReviewStale("", "bbb2222"), false);
+  assertEquals(isReviewStale("   ", "bbb2222"), false);
+});
+
+test("isReviewStale: a missing HEAD sha fails safe to NOT stale", () => {
+  assertEquals(isReviewStale("aaa1111", null), false);
+  assertEquals(isReviewStale("aaa1111", undefined), false);
+  assertEquals(isReviewStale("aaa1111", ""), false);
+});
+
+test("isReviewStale: both missing is NOT stale", () => {
+  assertEquals(isReviewStale(null, null), false);
+});

package/app/reviewWait.ts

@@ -93,3 +93,24 @@ export function clampNudgeMinutes(
   if (i < 1) return safeFallback;
   return Math.min(i, MAX_REVIEW_NUDGE_MINUTES);
 }
+
+/** Is the latest Copilot review STALE relative to the PR's current HEAD? (issue #799)
+ *
+ * A review is stale when it was submitted against a commit the head has since moved past — its
+ * advisories describe code that no longer exists, so the convergence gate must NOT block/escalate
+ * against it and the poller must NOT unpark the loop on it; instead a fresh review of the current
+ * HEAD must be solicited and gated on. Staleness is a plain SHA inequality.
+ *
+ * Fails SAFE to "not stale" when either SHA is unknown (`null`/`undefined`/blank): GitHub did not
+ * carry a `commit_id` for the review, or the head could not be read. Without both SHAs we cannot
+ * prove the review predates the head, so we must not fabricate a stale verdict that would loop the
+ * loop re-soliciting forever — the review-wait timeout and the round cap remain the safety nets. */
+export function isReviewStale(
+  reviewCommitId: string | null | undefined,
+  headSha: string | null | undefined,
+): boolean {
+  const rev = (reviewCommitId ?? "").trim();
+  const head = (headSha ?? "").trim();
+  if (rev === "" || head === "") return false;
+  return rev !== head;
+}

package/app/service.ts

@@ -26,6 +26,7 @@ import {
   CONFORMANCE_ESCALATION_ELEMENT,
   conformanceEscalationQuestion,
 } from "./conformance.ts";
+import { makeDefaultReadHead } from "./currentHead.ts";
 import { isUniqueConstraintFence } from "./dbFence.ts";
 import { deriveDelivery, EPIC_LIVE_STATUSES, TERMINAL_STATUSES } from "./delivery.ts";
 import { sweepExpiredProposals } from "./deliveryGraphProposals.ts";
@@ -40,6 +41,7 @@ import {
   coalesceTitle,
   ensureFreshHeadRun,
   ensurePromotionPr,
+  fetchBranchHead,
   fetchDefaultBranch,
   fetchPrHead,
   fetchPrMeta,
@@ -91,7 +93,7 @@ import {
 // (submitPr/startMerge) and re-exported below so the long-standing `import { repoEnvelopeVars } from
 // "./service.ts"` call sites (and its tests) keep resolving.
 import { repoEnvelopeVars } from "./repoEnvelope.ts";
-import { clampNudgeMinutes, reviewWaitTimeout } from "./reviewWait.ts";
+import { clampNudgeMinutes, isReviewStale, reviewWaitTimeout } from "./reviewWait.ts";
 import { trialMergeAudits } from "./trialMerge.ts";
 import {
   buildUserTaskRow,
@@ -833,7 +835,12 @@ export async function activePrs(data: DataLayer): Promise<ActivePr[]> {
  * fresh-review detection + Copilot nudge below stay here because review freshness is inherently
  * STATEFUL (keyed off `last_review_id`/`waiting_since`), which the stateless probe matchers cannot
  * subsume — the poller owns the forward-progress guarantee, the gate owns the bounded wait. */
-async function pollReviews(data: DataLayer, engine: EngineClient, token: string) {
+// The poller's PR current-head reader — the SAME branch-ref-preferring reader the converge-gate and
+// progress-check bind (#786/#799), so the poller's stale-review detection sees the exact head those
+// steps do. Fails OPEN to `null` (unreadable head → not stale, per `isReviewStale`).
+const readCurrentHead = makeDefaultReadHead({ fetchPrHead, fetchBranchHead });
+
+export async function pollReviews(data: DataLayer, engine: EngineClient, token: string) {
   const waiting = await prs(data).find({ status: "waiting_review" });
   for (const pr of waiting) {
     const { repo, number, pr_key: prKey } = pr;
@@ -854,6 +861,34 @@ async function pollReviews(data: DataLayer, engine: EngineClient, token: string)
         await maybeRerequestReview(data, pr, token);
         continue;
       }
+      // #799 (FM2): only resume the loop on a review of the CURRENT head. If the PR HEAD has
+      // advanced past the commit the newest review was submitted against, that review is STALE — its
+      // advisories describe code the head has moved past (e.g. an advisory the agent already fixed in
+      // a later commit). Publishing `readiness-ready` on it would resume the loop on obsolete
+      // findings and, at the converge-gate, re-escalate a human on an already-fixed advisory (PR
+      // #789). Treat a stale review like "no fresh review": (re-)solicit a fresh review of the
+      // current head and wait — without bumping `last_review_id`, so the next HEAD-current review is
+      // still detected. The head read fails OPEN (null → not stale), so a transport hiccup never
+      // strands a genuine review; the review-wait timer remains the backstop.
+      //
+      // Read the head via the SHARED branch-ref-preferring reader (`makeDefaultReadHead`, #786) — the
+      // exact reader the converge-gate uses — NOT `fetchPrHead(...).headSha` directly: the PR object's
+      // `head.sha` is an asynchronously-denormalized projection that can still equal `fresh.commit_id`
+      // right after a push, which would make the poller advance `last_review_id` on a stale review the
+      // gate would then classify stale, wedging the loop. Using the atomic branch ref makes the poller
+      // detect the same stale-head case the gate does.
+      // Read the head with the SAME per-call token the review fetch above uses (#799) — NOT the
+      // env-token default `makeDefaultReadHead` would otherwise fall back to. A caller that supplies
+      // a `token` without also setting GITHUB_TOKEN would otherwise get a `null` head here, which
+      // `isReviewStale` treats as not-stale (fails OPEN) and would advance `last_review_id` /
+      // publish readiness on a genuinely stale review. Passing `token` keeps both reads on one
+      // credential so the stale guard sees the real head.
+      const headSha = await readCurrentHead(repo, number, token).catch(() => null);
+      if (isReviewStale(fresh.commit_id, headSha)) {
+        console.log(`[poller] review ${fresh.id} is stale (predates HEAD) -> re-soliciting ${prKey}`);
+        await maybeRerequestReview(data, pr, token);
+        continue;
+      }
       await prs(data).update(prKey, { last_review_id: fresh.id, status: "converging", updated_at: now() });
       await engine.publishMessage({
         name: READINESS_READY_MESSAGE,

package/package.json

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