@nanobpm/nano-workforce 0.207.0 → 0.208.1

package/workers/merge/worker.test.ts

@@ -329,14 +329,13 @@ test("pr.merge #923: refuses to land when NO Copilot review exists (the #1443 fa
       app,
     )) as Record<string, unknown>;
 
-    assertEquals(out.mergeStatus, "blocked");
-    assertEquals(out.status, "blocked");
-    assertEquals(typeof out.question, "string");
-    assertEquals((out.question as string).includes("no head-current Copilot review"), true);
+    // Issue #939: an automatable remedy → `review-pending` (the model requests + waits), NEVER a
+    // human escalation payload on the first occurrence.
+    assertEquals(out, { mergeStatus: "review-pending" });
 
     // The refusal is audited, and NO land was attempted (no merge PUT, no enqueue comment).
     assertEquals(stores.merges.length, 1);
-    assertEquals(stores.merges[0].outcome, "blocked");
+    assertEquals(stores.merges[0].outcome, "review-pending");
     assertEquals(stores.merges[0].method, "review-backstop");
     assertEquals(calls.some((c) => /\/merge$/.test(c.url)), false);
     assertEquals(calls.some((c) => /\/comments$/.test(c.url)), false);
@@ -356,7 +355,7 @@ test("pr.merge #923: refuses to land when the head MOVED past the latest review
       app,
     )) as Record<string, unknown>;
 
-    assertEquals(out.mergeStatus, "blocked");
+    assertEquals(out, { mergeStatus: "review-pending" });
     assertEquals(stores.merges[0].method, "review-backstop");
     assertEquals(calls.some((c) => /\/merge$/.test(c.url)), false);
   });
@@ -440,7 +439,7 @@ test("pr.merge #927: reproduces nano-bpm#1467 — review REQUESTED but not yet a
           { variables: { prKey: "acme/widgets#1467", repo: "acme/widgets", prNumber: 1467 } } as any,
           app,
         )) as Record<string, unknown>;
-        assertEquals(out.mergeStatus, "blocked");
+        assertEquals(["blocked", "review-pending"].includes(String(out.mergeStatus)), true);
         assertEquals(stores.merges[0].method, "review-backstop");
         assertEquals(calls.some((c) => /\/comments$/.test(c.url)), false);
         assertEquals(calls.some((c) => /\/merge$/.test(c.url)), false);
@@ -457,8 +456,9 @@ test("pr.merge #923: a head-current review whose summary reports OPEN findings b
       readHeadSha: async () => "h1",
     });
     const out = (await backstop({ variables: { prKey: "acme/widgets#29", repo: "acme/widgets", prNumber: 29 } } as any, app)) as Record<string, unknown>;
-    assertEquals(out.mergeStatus, "blocked");
-    assertEquals((out.question as string).includes("open findings"), true);
+    // Issue #939: findings on a head-current review re-enter convergence, never a human.
+    assertEquals(out, { mergeStatus: "review-findings" });
+    assertEquals(stores.merges[0].outcome, "review-findings");
     assertEquals(stores.merges[0].method, "review-backstop");
     assertEquals(calls.some((c) => /\/merge$/.test(c.url)), false);
   });
@@ -538,3 +538,24 @@ for (const [label, finalRead] of [
     );
   });
 }
+
+// ── Defect-class guard (issue #939) ──────────────────────────────────────────
+// No merge-gate refusal whose remedy is fully automatable (missing head-current review, a review
+// made stale by a loop push, findings on a head-current review) may produce a human escalation
+// payload (`status`/`question`) on its first occurrence.
+for (const [label, review, head] of [
+  ["no review ever submitted", { body: "", commitId: null }, "h10"],
+  ["review stale after a loop push", { body: "lgtm", commitId: "old" }, "h10"],
+  ["head-current review with findings", { body: "### 🟡 Changes recommended\n<summary>1 open issue</summary>", commitId: "h10" }, "h10"],
+] as const) {
+  test(`pr.merge #939: an automatable refusal (${label}) never yields a human escalation payload`, async () => {
+    await withGithub(backstopRoutes, async () => {
+      const { app } = fakeApp();
+      const backstop = makeHandler({ readReview: async () => review, readHeadSha: async () => head });
+      const out = (await backstop({ variables: { prKey: "acme/widgets#40", repo: "acme/widgets", prNumber: 40 } } as any, app)) as Record<string, unknown>;
+      assertEquals(out.status, undefined);
+      assertEquals(out.question, undefined);
+      assertEquals(out.mergeStatus === "blocked", false);
+    });
+  });
+}

package/workers/merge/worker.ts

@@ -42,7 +42,7 @@ import type { WorkerInputs } from "../../nano-generated/worker-io.d.ts";
 type In = WorkerInputs["pr.merge"];
 
 interface Out extends Record<string, unknown> {
-  mergeStatus: "merged" | "queued" | "blocked" | "retry" | "abandoned";
+  mergeStatus: "merged" | "queued" | "blocked" | "retry" | "abandoned" | "review-pending" | "review-findings";
   status?: string;
   question?: string;
 }
@@ -142,11 +142,26 @@ export function makeHandler(deps: { readReview: MergeReviewReader; readHeadSha:
   // FAIL CLOSED (issue #927): a gate whose job is "never land unreviewed" must not land on an
   // UNVERIFIABLE read. nano-bpm#1467 merged 49 s before its first Copilot review because a `null`
   // review/head read (or an empty head) skipped this check entirely. An unreadable review or head now
-  // blocks (escalating to a human, who replies to retry) exactly like a missing/stale review.
+  // blocks (escalating to a human, who replies to retry); a VERIFIED missing/stale review instead
+  // takes the automated request-and-wait path below (issue #939).
   const headTrimmed = (backstopHead ?? "").trim();
   const unverifiable = backstopReview === null || headTrimmed === "";
-  if (unverifiable || isReviewMissingOrStale(backstopReview.commitId, headTrimmed)) {
-    const detail = unverifiable ? BLOCK_UNVERIFIABLE_REVIEW : BLOCK_NO_HEAD_CURRENT_REVIEW;
+  // AUTOMATABLE REMEDY (issue #939): a VERIFIED read showing no head-current review (the loop's own
+  // rebase/fix push moved the head, or no review exists yet) is not a human decision — the only
+  // remedy is "request a Copilot review and wait for it". Return `review-pending` so the model
+  // requests the review itself and waits on a bounded timer, escalating only when it never arrives.
+  if (!unverifiable && isReviewMissingOrStale(backstopReview.commitId, headTrimmed)) {
+    await app.data.table("merges", "id").insert({
+      pr_key: prKey,
+      outcome: "review-pending",
+      method: "review-backstop",
+      detail: BLOCK_NO_HEAD_CURRENT_REVIEW,
+      at: now,
+    });
+    return { mergeStatus: "review-pending" };
+  }
+  if (unverifiable) {
+    const detail = BLOCK_UNVERIFIABLE_REVIEW;
     await app.data.table("merges", "id").insert({
       pr_key: prKey,
       outcome: "blocked",
@@ -174,18 +189,14 @@ export function makeHandler(deps: { readReview: MergeReviewReader; readHeadSha:
     const detail = `the head-current Copilot review reports open findings (${openFindings.join(", ")})`;
     await app.data.table("merges", "id").insert({
       pr_key: prKey,
-      outcome: "blocked",
+      outcome: "review-findings",
       method: "review-backstop",
       detail,
       at: now,
     });
-    return {
-      mergeStatus: "blocked",
-      status: "blocked",
-      question:
-        `Merge refused: ${detail}. Address the review's findings on the branch (or reply with ` +
-        `guidance on which to push back on), let the convergence loop gate on a clean review, then reply to retry.`,
-    };
+    // Findings on a head-current review belong to the convergence path (fix → push → review), not
+    // to a human (issue #939): the model hands the PR back to the convergence loop.
+    return { mergeStatus: "review-findings" };
   }
   // The head the backstop verified — pinned through the land call so a push between this check
   // and the merge can never land a later, unreviewed head.

package/workers/reconverge/worker.test.ts

@@ -0,0 +1,110 @@
+// pr.reconverge (issue #939): findings on a head-current review hand the PR back to the ONE canonical
+// convergence entry (`submitPr`), declaring the merge-loop instance as the hand-off source.
+import { test } from "node:test";
+import { assertEquals, assertRejects, assertStringIncludes } from "#test-assert";
+import { noopLog } from "../../test/log.ts";
+import { makeHandler, type FetchPrHead, type Submit } from "./worker.ts";
+
+test("re-submits through submitPr with auto-merge on and handoffFrom = this merge-loop instance", async () => {
+  const merges: Record<string, unknown>[] = [];
+  const app = {
+    data: {
+      table: (name: string) => ({
+        get: async () => (name === "pull_requests" ? { auto_resolve_escalations: 1 } : undefined),
+        insert: async (r: Record<string, unknown>) => (merges.push(r), 1),
+      }),
+    },
+    engine: {},
+    log: noopLog(),
+  } as any;
+  let args: unknown[] = [];
+  const submit = (async (...a: unknown[]) => {
+    args = a;
+    return { prKey: "acme/w#7" };
+  }) as unknown as Submit;
+  await makeHandler(submit)({ processInstanceKey: "4242", variables: { prKey: "acme/w#7" } } as any, app);
+  assertEquals((args[2] as { prKey: string }).prKey, "acme/w#7");
+  assertEquals(args[7], false, "no re-gate on human approval");
+  assertEquals(args[8], true, "steward opt-in carried from the row");
+  assertEquals(args[9], true, "auto-merge stays on");
+  assertEquals(args[10], "4242", "hand-off source is this merge-loop instance");
+  assertEquals(merges[0].outcome, "reconverge");
+});
+
+// Issue #941 review: `submitPr` can return `processKey: null` after rewriting the row to
+// `converging` with no owner (a create-instance failure window). Completing the job successfully
+// then ends the merge loop at `MergeReconverged`, leaving the PR with NO live convergence or merge
+// instance to advance it. The worker must throw on a null process key so the job stays retryable
+// instead of stranding the PR.
+test("throws on a null processKey so the hand-off stays retryable (#941)", async () => {
+  const app = {
+    data: {
+      table: (name: string) => ({
+        get: async () => (name === "pull_requests" ? { auto_resolve_escalations: 0 } : undefined),
+        insert: async () => 1,
+      }),
+    },
+    engine: {},
+    log: noopLog(),
+  } as any;
+  const submit = (async () => ({ prKey: "acme/w#7", processKey: null })) as unknown as Submit;
+  const err = await assertRejects(
+    () => makeHandler(submit)({ processInstanceKey: "4242", variables: { prKey: "acme/w#7" } } as any, app),
+    Error,
+    "null processKey",
+  );
+  assertStringIncludes(err.message, "acme/w#7");
+});
+
+// Issue #941 round-4 review (Copilot "previously missed", high): the world checkpoint is written
+// ONLY by the convergence loop's `pr.persist-round` — a merge-stage rebase/fix-ci push advances the
+// PR head WITHOUT updating the checkpoint. On a durable-resume fleet a reconverge hand-off that
+// re-enters `submitPr` on the checkpoint therefore provisions the fresh convergence agent at the
+// PRE-MERGE tree, not the head whose review raised the findings. The hand-off must carry the
+// CURRENT PR head SHA as `submitPr`'s restore override.
+test("hands off at the CURRENT PR head, not the stale convergence checkpoint (#941 round 4)", async () => {
+  const app = {
+    data: {
+      table: (name: string) => ({
+        get: async () => (name === "pull_requests" ? { auto_resolve_escalations: 0 } : undefined),
+        insert: async () => 1,
+      }),
+    },
+    engine: {},
+    log: noopLog(),
+  } as any;
+  let args: unknown[] = [];
+  const submit = (async (...a: unknown[]) => {
+    args = a;
+    return { prKey: "acme/w#7", processKey: "999" };
+  }) as unknown as Submit;
+  const head = (async () => ({
+    headRef: "feat/x",
+    headSha: "b".repeat(40),
+    baseRef: "main",
+    headRepo: "acme/w",
+  })) as unknown as FetchPrHead;
+  await makeHandler(submit, head)({ processInstanceKey: "4242", variables: { prKey: "acme/w#7" } } as any, app);
+  assertEquals(args[11], "b".repeat(40), "the restore override is the live PR head SHA");
+});
+
+test("a head read that resolves no SHA degrades to the checkpoint restore (no override)", async () => {
+  const app = {
+    data: {
+      table: (name: string) => ({
+        get: async () => (name === "pull_requests" ? { auto_resolve_escalations: 0 } : undefined),
+        insert: async () => 1,
+      }),
+    },
+    engine: {},
+    log: noopLog(),
+  } as any;
+  let args: unknown[] = [];
+  const submit = (async (...a: unknown[]) => {
+    args = a;
+    return { prKey: "acme/w#7", processKey: "999" };
+  }) as unknown as Submit;
+  const head = (async () => null) as unknown as FetchPrHead;
+  await makeHandler(submit, head)({ processInstanceKey: "4242", variables: { prKey: "acme/w#7" } } as any, app);
+  assertEquals(args[11], null, "no live head SHA → no override (checkpoint restore, the pre-fix behaviour)");
+});

package/workers/reconverge/worker.ts

@@ -0,0 +1,81 @@
+// pr.reconverge — hand a PR back from the merge loop to the convergence loop (issue #939).
+//
+// Reached when `pr.merge`'s backstop finds a HEAD-CURRENT Copilot review whose own summary reports
+// open findings (`mergeStatus: "review-findings"`) — typically the review the merge loop itself
+// requested after a rebase / fix push. Actionable findings belong to the convergence path
+// (fix → push → review), not to a human, so this re-submits the PR through the ONE canonical entry
+// (`submitPr`), declaring this merge-loop instance as the hand-off source so the live row it owns is
+// not misread as "already running". The merge loop then ends; the fresh convergence run starts a new
+// merge loop on convergence, exactly as a first pass does. No parallel review loop is introduced.
+import type { AppJobHandler } from "@nanobpm/urban";
+import { fetchPrHead } from "../../app/github.ts";
+import { parsePr } from "../../app/prParse.ts";
+import { MAX_ROUNDS, submitPr } from "../../app/service.ts";
+import type { WorkerInputs } from "../../nano-generated/worker-io.d.ts";
+
+// Input typed off the model data envelope (`ReconvergeIn` in merge-loop.bpmn) — ADR 0040.
+type In = WorkerInputs["pr.reconverge"];
+
+export type Submit = typeof submitPr;
+export type FetchPrHead = typeof fetchPrHead;
+
+export function makeHandler(submit: Submit, fetchHead: FetchPrHead = fetchPrHead): AppJobHandler<In> {
+  return async (job, app) => {
+    const { prKey } = job.variables;
+    const parsed = parsePr(prKey);
+    if (!parsed) throw new Error(`reconverge: unparseable prKey ${JSON.stringify(prKey)}`);
+    const row = await app.data.table("pull_requests", "pr_key").get(prKey);
+    // biome-ignore lint/plugin: runtime/framework contract boundary for the untyped row shape
+    const optIn = (row as { auto_resolve_escalations?: number } | undefined)?.auto_resolve_escalations === 1;
+    await app.data.table("merges", "id").insert({
+      pr_key: prKey,
+      outcome: "reconverge",
+      method: "review-backstop",
+      detail: "head-current Copilot review reports open findings — re-entering convergence",
+      at: new Date().toISOString(),
+    });
+    // Head-current restore (#941 round-4 review): the durable world checkpoint is written only by
+    // the convergence loop's `pr.persist-round`, so a merge-stage rebase/fix-ci push — the very push
+    // whose head-current review sent us here — advances the PR head WITHOUT updating the checkpoint.
+    // Re-entering `submitPr` on the checkpoint would provision the fresh convergence agent at the
+    // PRE-MERGE tree, risking stale fixes or a rejected (non-fast-forward) push. Read the LIVE head
+    // SHA and pass it as the restore override so the hand-off resumes at the head the review saw.
+    // Best-effort: an unreadable head degrades to `null` (no override → the checkpoint restore, the
+    // pre-fix behaviour) rather than blocking the hand-off on a GitHub read.
+    let headSha: string | null = null;
+    try {
+      headSha = (await fetchHead(parsed.repo, parsed.number, process.env.GITHUB_TOKEN ?? ""))?.headSha ?? null;
+    } catch (err) {
+      app.log.warn("reconverge: head read failed — falling back to the checkpoint restore", { prKey, err: String(err) });
+    }
+    // The PR was already merging (merge intent on, any human approval already given), so the fresh
+    // run keeps auto-merge and does not re-gate on approval.
+    const result = await submit(
+      app.data,
+      app.engine,
+      parsed,
+      [],
+      MAX_ROUNDS,
+      false,
+      null,
+      false,
+      optIn,
+      true,
+      job.processInstanceKey != null ? String(job.processInstanceKey) : null,
+      headSha,
+    );
+    // `submitPr` can return `processKey: null` after rewriting the row to `converging` with no owner
+    // (the create-instance failure window). Completing HERE would end the merge loop at
+    // `MergeReconverged` with the PR left on a keyless `converging` row — no live convergence or
+    // merge instance to advance it. Throw instead so the job fails and stays RETRYABLE: the retry
+    // re-enters `submitPr`, which treats the keyless non-terminal row as resubmittable and re-enrolls
+    // it (the #704/#497 phantom-row recovery path).
+    if (result != null && typeof result === "object" && "processKey" in result && result.processKey == null) {
+      throw new Error(`reconverge: submitPr returned a null processKey for ${prKey} — no convergence instance was started; failing so the hand-off is retried`);
+    }
+    return {};
+  };
+}
+
+const handler = makeHandler(submitPr);
+export default handler;

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

@@ -0,0 +1,54 @@
+// pr.request-review (issue #939): the merge loop requests a head-current Copilot review itself, and
+// re-triggers a silently-ignored request (withdraw + re-add) on a re-request.
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import { noopLog } from "../../test/log.ts";
+import { makeHandler, type ReviewRequestOps } from "./worker.ts";
+
+function fakeApp() {
+  const merges: Record<string, unknown>[] = [];
+  return {
+    merges,
+    app: {
+      data: { table: () => ({ insert: (r: Record<string, unknown>) => (merges.push(r), Promise.resolve(1)) }) },
+      log: noopLog(),
+    } as any,
+  };
+}
+
+function ops(over: Partial<ReviewRequestOps>, calls: string[]): ReviewRequestOps {
+  return {
+    hasPending: async () => (calls.push("pending?"), false),
+    remove: async () => calls.push("remove"),
+    request: async () => (calls.push("request"), "requested"),
+    ...over,
+  };
+}
+
+const job = (round: number) => ({ variables: { prKey: "acme/w#1", repo: "acme/w", prNumber: 1, reviewRequestRound: round } }) as any;
+
+test("first request POSTs the Copilot reviewer and audits it", async () => {
+  const calls: string[] = [];
+  const { app, merges } = fakeApp();
+  const out = await makeHandler(ops({}, calls))(job(0), app);
+  assertEquals(out, { reviewRequest: "requested" });
+  assertEquals(calls, ["request"]);
+  assertEquals(merges[0].outcome, "review-requested");
+});
+
+test("a re-request with Copilot still pending (silently ignored) withdraws then re-adds", async () => {
+  const calls: string[] = [];
+  const { app } = fakeApp();
+  await makeHandler(ops({ hasPending: async () => (calls.push("pending?"), true) }, calls))(job(1), app);
+  assertEquals(calls, ["pending?", "remove", "request"]);
+});
+
+test("Copilot not assignable reports unavailable; a transport error reports failed (never throws)", async () => {
+  const { app } = fakeApp();
+  assertEquals(await makeHandler(ops({ request: async () => "unavailable" }, []))(job(0), app), { reviewRequest: "unavailable" });
+  assertEquals(
+    await makeHandler(ops({ request: async () => { throw new Error("502"); } }, []))(job(0), app),
+    { reviewRequest: "failed" },
+  );
+  assertEquals(await makeHandler(ops({ request: async () => null }, []))(job(0), app), { reviewRequest: "failed" });
+});

package/workers/request-review/worker.ts

@@ -0,0 +1,68 @@
+// pr.request-review — the merge loop requests a HEAD-CURRENT Copilot review itself (issue #939).
+//
+// Reached when `pr.merge`'s backstop finds no head-current review (`mergeStatus: "review-pending"`):
+// the loop's own rebase / merge-from-base / fix push moved the head, so the last review is stale.
+// The only remedy is mechanical — request a review and wait — so the loop does it instead of
+// escalating to a human. The model then waits on a bounded timer (`reviewRequestWait`) and re-arms
+// the merge poller; `pr.merge` re-runs the backstop on the new head. Only after `reviewRequestMax`
+// requests with no review (or when Copilot cannot be requested at all) does it escalate.
+//
+// "Silently ignored" requests: Copilot can stay listed as a pending reviewer yet never review, and a
+// 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 type { WorkerInputs } from "../../nano-generated/worker-io.d.ts";
+
+// Input typed off the model data envelope (`RequestReviewIn` in merge-loop.bpmn) — ADR 0040.
+type In = WorkerInputs["pr.request-review"];
+
+interface Out extends Record<string, unknown> {
+  /** `requested` — a request is in flight; `unavailable` — Copilot is not an assignable reviewer on
+   * this repo (waiting is pointless → escalate); `failed` — no usable transport / transport error
+   * (the bounded wait still re-checks, so a transient failure is retried by the budget). */
+  reviewRequest: "requested" | "unavailable" | "failed";
+}
+
+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>;
+}
+
+const token = () => process.env.GITHUB_TOKEN ?? "";
+const defaultOps: ReviewRequestOps = {
+  hasPending: (repo, n) => hasPendingCopilotReviewer(repo, n, token()),
+  remove: (repo, n) => removeCopilotReviewer(repo, n, token()),
+  request: (repo, n) => requestCopilotReview(repo, n, token()),
+};
+
+export function makeHandler(ops: ReviewRequestOps): AppJobHandler<In, Out> {
+  return async (job, app) => {
+    const { prKey, repo, prNumber, reviewRequestRound } = job.variables;
+    const round = typeof reviewRequestRound === "number" ? reviewRequestRound : 0;
+    let result: Out["reviewRequest"];
+    try {
+      // A re-request whose previous ask is still pending was silently ignored → withdraw, re-add.
+      if (round > 0 && (await ops.hasPending(repo, prNumber)) === true) {
+        await ops.remove(repo, prNumber);
+      }
+      const res = await ops.request(repo, prNumber);
+      result = res === "requested" ? "requested" : res === "unavailable" ? "unavailable" : "failed";
+    } catch (err) {
+      app.log.warn(`request-review: ${prKey} Copilot review request failed: ${err}`);
+      result = "failed";
+    }
+    await app.data.table("merges", "id").insert({
+      pr_key: prKey,
+      outcome: "review-requested",
+      method: "review-request",
+      detail: `head-current Copilot review request #${round + 1}: ${result}`,
+      at: new Date().toISOString(),
+    });
+    return { reviewRequest: result };
+  };
+}
+
+const handler = makeHandler(defaultOps);
+export default handler;