@nanobpm/nano-workforce 0.207.0 → 0.208.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.208.0](https://github.com/nanobpm/nano-workforce/compare/v0.207.0...v0.208.0) (2026-11-10)
+
+### Features
+
+* **merge:** request the head-current Copilot review after a loop-authored head move ([#941](https://github.com/nanobpm/nano-workforce/issues/941)) ([0e2d50e](https://github.com/nanobpm/nano-workforce/commit/0e2d50e8610beb5e939cd3a143d28e62d690f272)), closes [#939](https://github.com/nanobpm/nano-workforce/issues/939)
+
 ## [0.207.0](https://github.com/nanobpm/nano-workforce/compare/v0.206.4...v0.207.0) (2026-11-09)
 
 ### Features

package/SPEC.md

@@ -855,6 +855,24 @@ start ─► wait: deps merged ─► arm merge ─► wait: mergeable ─┬─
     sets `ciBlockedReconciled`), and escalates only if the PR is **still** blocked on the
     re-derived state.
 
+- **Head-current review after a loop-authored head move — request it, don't escalate**
+  (issue #939) — `pr.merge` refuses to land without a Copilot review of the PR's
+  current HEAD (#923 backstop). When the loop's own rebase / merge-from-base / fix push
+  moved the head, the only remedy is mechanical, so instead of escalating the worker
+  returns `mergeStatus: "review-pending"` and the model **requests the review itself**
+  (`pr.request-review` — REST `requested_reviewers` POST of
+  `copilot-pull-request-reviewer[bot]`; on a re-request whose prior ask is still pending,
+  i.e. silently ignored, it withdraws then re-adds the reviewer), waits on a timer
+  (`reviewRequestWait`, derived from the review-nudge window) and re-arms the poller so
+  the backstop re-checks the new head. It repeats up to `reviewRequestMax` (3) requests;
+  only when no review arrives in that budget — or Copilot is not an assignable reviewer —
+  does it escalate, with a question stating what was tried. A head-current review whose
+  summary reports open findings returns `mergeStatus: "review-findings"`: `pr.reconverge`
+  hands the PR back to the convergence loop through the canonical `submitPr` (declaring
+  the owning merge-loop instance as `handoffFrom`) and the merge loop ends — the fresh
+  convergence run fixes, pushes, re-reviews and starts a new merge loop on convergence.
+  An *unreadable* review/head still fails closed to a human (#927).
+
 - **Discovered dependency** — a `senior:fix-ci` or `senior:rebase` agent may find that
   the PR cannot land because **another PR must merge first** (a required linked-issue
   gate a sibling PR will close, a stacked base PR, or a `Depends-on:` the agent read

package/app/github.ts

@@ -743,6 +743,35 @@ export async function requestCopilotReview(
   throw new Error(`github ${r.status} ${r.statusText}: ${(await r.text()).slice(0, 300)}`.trim());
 }
 
+/** 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
+ * the equivalent that re-triggers the review. `null` when no transport is usable; throws on a
+ * genuine transport failure. */
+export async function removeCopilotReviewer(
+  repo: string,
+  number: number | string,
+  token: string,
+): Promise<"removed" | null> {
+  const path = `repos/${repo}/pulls/${number}/requested_reviewers`;
+  if (await useGh()) {
+    await runGh(["api", path, "-X", "DELETE", "-f", `reviewers[]=${COPILOT_REVIEWER}`]);
+    return "removed";
+  }
+  if (!token) return null;
+  const r = await fetch(`https://api.github.com/${path}`, {
+    method: "DELETE",
+    headers: {
+      authorization: `Bearer ${token}`,
+      accept: "application/vnd.github+json",
+      "content-type": "application/json",
+    },
+    body: JSON.stringify({ reviewers: [COPILOT_REVIEWER] }),
+  });
+  if (r.ok) return "removed";
+  throw new Error(`github ${r.status} ${r.statusText}: ${(await r.text()).slice(0, 300)}`.trim());
+}
+
 // ── Merge stage (SPEC §11) ──────────────────────────────────────────────────
 // The same two-transport model (gh | token) backs the merge stage: read a PR's merge state to
 // decide when it is landable, and perform the merge (directly or via the repo's merge queue).

package/app/mergeLoopBehaviour.test.ts

@@ -43,7 +43,8 @@ const MODEL = readFileSync("resources/processes/merge-loop.bpmn", "utf8");
 const AGENT_SLA_MS = 30 * 60 * 1000; // matches the PT30M we start instances with
 const LANDED_WAIT_MS = 30 * 60 * 1000; // matches the PT30M landedWaitTimeout we start instances with
 const MERGEABLE_WAIT_MS = 30 * 60 * 1000; // matches the PT30M mergeableWaitTimeout we start instances with
-const MERGEABLE_REPOLL_MS = 2 * 60 * 1000; // matches the PT2M mergeableRepollInterval we start instances with
+const MERGEABLE_REPOLL_MS = 2 * 60 * 1000;
+const REVIEW_REQUEST_WAIT_MS = 10 * 60 * 1000; // matches the PT10M reviewRequestWait we start instances with // matches the PT2M mergeableRepollInterval we start instances with
 
 type Output = Record<string, unknown>;
 type Responder = Output | Output[] | ((job: { variables: Record<string, unknown> }) => Output);
@@ -59,6 +60,8 @@ const ALL_JOB_TYPES = [
   "pr.persist-escalation",
   "pr.answer-escalation",
   "pr.record-dependency",
+  "pr.request-review",
+  "pr.reconverge",
 ] as const;
 
 const DEFAULT_RESPONSES: Record<string, Responder> = {
@@ -68,6 +71,8 @@ const DEFAULT_RESPONSES: Record<string, Responder> = {
   "pr.answer-escalation": {},
   "pr.persist-escalation": { escalated: true },
   "pr.landed-probe": { landedVerdict: "waiting" },
+  "pr.request-review": { reviewRequest: "requested" },
+  "pr.reconverge": {},
 };
 
 // Every FEEL expression in the model references these; start them defined (null,
@@ -91,6 +96,10 @@ const DEFAULT_VARS: Record<string, unknown> = {
   mergeableRepollInterval: "PT2M",
   mergeStallRounds: 0,
   mergeStallMax: 3,
+  reviewRequestRound: 0,
+  reviewRequestMax: 3,
+  reviewRequestWait: "PT10M",
+  reviewRequest: null,
   abandonBrief: "\n\n---\nAbort if cancelled: curl …",
   failingChecksList: null,
   status: null,
@@ -413,6 +422,59 @@ test("a fix-ci agent echoing abandonBrief cannot corrupt the seeded abort brief
     .hasVariable("abandonBrief", "\n\n---\nAbort if cancelled: curl …");
 });
 
+test("a fix-ci agent echoing review-request state cannot clobber the seeded budget or timer (#941 round 4)", async () => {
+  // Same guard class as the #887 echoes: `reviewRequestRound`/`reviewRequestMax` bound the
+  // head-current review re-request loop (`reviewRequestRound < reviewRequestMax` gates a retry) and
+  // `reviewRequestWait` arms its timer. An agent completion echoing `reviewRequestMax: 0` would send
+  // the FIRST missing-review verdict straight to a human escalation, and a clobbered
+  // `reviewRequestWait` would reshape the wait. The snapshot/restore guard must pin all four.
+  const engine = await boot({
+    responses: {
+      "pr.merge-stall-probe": { mergeState: "blocked", failingChecks: 1, failingChecksList: "build" },
+      "senior:fix-ci": {
+        status: "fixed",
+        reviewRequestRound: 99,
+        reviewRequestMax: 0,
+        reviewRequestWait: "PT1S",
+        reviewRequest: "unavailable",
+      },
+    },
+  });
+  await engine.publishMessage({ name: "deps-cleared", correlationKey: "pr-1" });
+  await engine.advanceTime(MERGEABLE_WAIT_MS + 1);
+  assertThatInstance(engine, byProcessId("merge-loop"))
+    .isActive()
+    .hasCompletedElements("merge-stall-probe", "fix-ci")
+    .hasVariable("reviewRequestRound", 0)
+    .hasVariable("reviewRequestMax", 3)
+    .hasVariable("reviewRequestWait", "PT10M");
+  assert(instanceVars(engine).reviewRequest !== "unavailable", "a fix-ci agent must not forge reviewRequest:unavailable");
+});
+
+test("a rebase agent echoing review-request state cannot clobber the seeded budget or timer (#941 round 4)", async () => {
+  const engine = await boot({
+    responses: {
+      "pr.merge-stall-probe": { mergeState: "conflict", failingChecks: 0, failingChecksList: "" },
+      "senior:rebase": {
+        status: "rebased",
+        reviewRequestRound: 99,
+        reviewRequestMax: 0,
+        reviewRequestWait: "PT1S",
+        reviewRequest: "unavailable",
+      },
+    },
+  });
+  await engine.publishMessage({ name: "deps-cleared", correlationKey: "pr-1" });
+  await engine.advanceTime(MERGEABLE_WAIT_MS + 1);
+  assertThatInstance(engine, byProcessId("merge-loop"))
+    .isActive()
+    .hasCompletedElements("rebase")
+    .hasVariable("reviewRequestRound", 0)
+    .hasVariable("reviewRequestMax", 3)
+    .hasVariable("reviewRequestWait", "PT10M");
+  assert(instanceVars(engine).reviewRequest !== "unavailable", "a rebase agent must not forge reviewRequest:unavailable");
+});
+
 test("a blocked PR probed on timeout reaches the CI-fix arm via the timeout path (#636)", async () => {
   const engine = await boot({
     responses: {
@@ -908,6 +970,79 @@ test("a worker-supplied block question (review backstop #923) reaches the human
   assert(!q.includes("Investigate why GitHub refused"), "must not be overwritten by the generic refusal text");
 });
 
+// ---------------------------------------------------------------------------
+// Head-current review after a loop-authored head move (issue #939)
+// ---------------------------------------------------------------------------
+
+async function driveToAttempt(engine: WasmEngineClient): Promise<void> {
+  await engine.publishMessage({ name: "deps-cleared", correlationKey: "pr-1" });
+  await engine.publishMessage({ name: "merge-ready", correlationKey: "pr-1", variables: { mergeState: "ready" } });
+}
+
+test("#939: a missing head-current review requests one itself, waits, and merges on the re-check — no human", async () => {
+  const engine = await boot({ responses: { "pr.merge": [{ mergeStatus: "review-pending" }, { mergeStatus: "merged" }] } });
+  await driveToAttempt(engine);
+  assertThatInstance(engine, byProcessId("merge-loop")).isActive().hasActiveElement("wait-review-requested");
+  assertThatInstance(engine, byProcessId("merge-loop")).hasCompletedElements("request-review");
+  assertEquals(instanceVars(engine).reviewRequestRound, 1);
+  await engine.advanceTime(REVIEW_REQUEST_WAIT_MS + 1);
+  assertThatInstance(engine, byProcessId("merge-loop")).isActive().hasActiveElement("wait-mergeable");
+  await engine.publishMessage({ name: "merge-ready", correlationKey: "pr-1", variables: { mergeState: "ready" } });
+  assertThatInstance(engine, byProcessId("merge-loop")).hasCompleted().hasCompletedElements("mark-merged");
+  assert(!completedElementIds(engine).has("merge-esc-attempt"), "an automatable review gap must never escalate");
+});
+
+test("#939 defect-class guard: no automatable merge-gate refusal escalates to a human on its first occurrence", async () => {
+  for (const mergeStatus of ["review-pending", "review-findings"]) {
+    const engine = await boot({ responses: { "pr.merge": { mergeStatus } } });
+    await driveToAttempt(engine);
+    const done = completedElementIds(engine);
+    assert(!done.has("merge-esc-attempt") && !done.has("merge-esc-conflict"), `${mergeStatus}: must not escalate`);
+    const open = await engine.searchUserTasks({});
+    assertEquals(open.length, 0, `${mergeStatus}: no human task on the first occurrence`);
+  }
+});
+
+test("#939: a head-current review with findings re-enters convergence and ends the merge loop", async () => {
+  const engine = await boot({ responses: { "pr.merge": { mergeStatus: "review-findings" } } });
+  await driveToAttempt(engine);
+  assertThatInstance(engine, byProcessId("merge-loop")).hasCompleted().hasCompletedElements("reconverge", "MergeReconverged");
+  assert(!completedElementIds(engine).has("mark-merged"), "findings must not merge");
+});
+
+test("#939: a review that never arrives escalates after the bounded request budget, stating what was tried", async () => {
+  const engine = await boot({
+    responses: { "pr.merge": { mergeStatus: "review-pending" } },
+    vars: { reviewRequestMax: 1 },
+  });
+  await driveToAttempt(engine);
+  await engine.advanceTime(REVIEW_REQUEST_WAIT_MS + 1);
+  await engine.publishMessage({ name: "merge-ready", correlationKey: "pr-1", variables: { mergeState: "ready" } });
+  await assertThatUserTask(engine, { instance: byProcessId("merge-loop"), elementId: "wait-merge-answer" }).isCreated();
+  const q = String(escalation(engine).question ?? "");
+  assertStringIncludes(q, "requested a Copilot review of the current HEAD 1 time(s)");
+  assertStringIncludes(q, "PT10M");
+});
+
+test("#939: a clean re-check resets the request budget so a later head move gets a fresh budget", async () => {
+  const engine = await boot({
+    responses: { "pr.merge": [{ mergeStatus: "review-pending" }, { mergeStatus: "retry" }, { mergeStatus: "merged" }] },
+  });
+  await driveToAttempt(engine);
+  await engine.advanceTime(REVIEW_REQUEST_WAIT_MS + 1);
+  await engine.publishMessage({ name: "merge-ready", correlationKey: "pr-1", variables: { mergeState: "ready" } });
+  assertEquals(instanceVars(engine).reviewRequestRound, 0);
+});
+
+test("#939: Copilot not assignable escalates immediately, naming the cause", async () => {
+  const engine = await boot({
+    responses: { "pr.merge": { mergeStatus: "review-pending" }, "pr.request-review": { reviewRequest: "unavailable" } },
+  });
+  await driveToAttempt(engine);
+  await assertThatUserTask(engine, { instance: byProcessId("merge-loop"), elementId: "wait-merge-answer" }).isCreated();
+  assertStringIncludes(String(escalation(engine).question ?? ""), "not an assignable reviewer");
+});
+
 // ---------------------------------------------------------------------------
 // CI-fix sub-process (SP_cifix) — mergeCiReattempt (#134), #329
 // ---------------------------------------------------------------------------

package/app/service.test.ts

@@ -2563,3 +2563,152 @@ test("pollCapabilityGatesImpl: scopes the barrier subscription search server-sid
   assertEquals(published.length, 1, "the scoped search still finds THIS task's subscription and releases it");
   assertEquals(published[0]?.correlationKey, barrierKey);
 });
+
+// Issue #939: the merge loop hands a PR with head-current review findings back to convergence via
+// `submitPr`. The OWNING merge-loop instance (the row's `process_key`) is live while it calls, so the
+// hand-off must bypass the alreadyRunning gate — but ONLY for that exact owner; any other caller still
+// dedupes against the live merge loop.
+test("submitPr handoffFrom: only the owning merge-loop instance may re-enter convergence (#939)", async () => {
+  await withGithubOff(async () => {
+    const PR_KEY = "owner/repo#77";
+    const mk = () => {
+      const stores: Record<string, { rows: any[]; key: string }> = {
+        pull_requests: {
+          rows: [{ pr_key: PR_KEY, repo: "owner/repo", number: 77, url: "https://github.com/owner/repo/pull/77", title: "t", status: "waiting_merge", current_round: 4, process_key: "PI-MERGE" }],
+          key: "pr_key",
+        },
+        escalations: { rows: [], key: "id" },
+        pr_adjudications: { rows: [], key: "id" },
+        pr_dependencies: { rows: [], key: "pr_key" },
+      };
+      const data = { table: withTrackingViews((name: string, key: string) => memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key)), open: () => memOpen(stores) } as any;
+      return { stores, data };
+    };
+    let calls = 0;
+    const engine = { createInstance: async () => ({ processInstanceKey: `PI-CONV-${++calls}` }) } as any;
+    const parsed = { repo: "owner/repo", number: 77, url: "https://github.com/owner/repo/pull/77", prKey: PR_KEY };
+
+    const a = mk();
+    const plain = await submitPr(a.data, engine, parsed);
+    assertEquals((plain as any).alreadyRunning, true, "a plain submit dedupes against the live merge loop");
+    const foreign = await submitPr(a.data, engine, parsed, [], undefined, false, null, false, false, true, "PI-OTHER");
+    assertEquals((foreign as any).alreadyRunning, true, "a non-owner hand-off still dedupes");
+    assertEquals(calls, 0);
+
+    const owned = await submitPr(a.data, engine, parsed, [], undefined, false, null, false, false, true, "PI-MERGE");
+    assertEquals((owned as any).alreadyRunning, undefined);
+    assertEquals(calls, 1);
+    const row = a.stores.pull_requests.rows[0];
+    assertEquals(row.status, "converging");
+    assertEquals(row.process_key, "PI-CONV-1");
+  });
+});
+
+// Issue #941 review: a redelivered `pr.reconverge` can arrive AFTER its successor has already
+// settled the PR (merged/abandoned). The stale job still carries the OLD merge-loop instance key as
+// `handoffFrom`, and the settled row's `process_key` still names that same instance, so an owner
+// match ALONE would let the bypass treat the dead job as the row's live owner and restart
+// convergence, clearing the settled state. The internal hand-off channel is fenced against a
+// TERMINAL row outright: it dedupes idempotently and never resubmits. Only a DELIBERATE PUBLIC
+// submission (no `handoffFrom`) may re-open a settled PR.
+test("submitPr handoffFrom: a stale hand-off against a settled row is fenced, a public resubmit still re-opens (#941)", async () => {
+  await withGithubOff(async () => {
+    const PR_KEY = "owner/repo#78";
+    const mk = () => {
+      const stores: Record<string, { rows: any[]; key: string }> = {
+        pull_requests: {
+          // The successor convergence run MERGED the PR; the row is terminal (`merged`) but its
+          // `process_key` still names the OLD merge-loop instance the redelivered job belongs to.
+          rows: [{ pr_key: PR_KEY, repo: "owner/repo", number: 78, url: "https://github.com/owner/repo/pull/78", title: "t", status: "merged", current_round: 5, process_key: "PI-MERGE" }],
+          key: "pr_key",
+        },
+        escalations: { rows: [], key: "id" },
+        pr_adjudications: { rows: [], key: "id" },
+        pr_dependencies: { rows: [], key: "pr_key" },
+      };
+      const data = { table: withTrackingViews((name: string, key: string) => memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key)), open: () => memOpen(stores) } as any;
+      return { stores, data };
+    };
+    const parsed = { repo: "owner/repo", number: 78, url: "https://github.com/owner/repo/pull/78", prKey: PR_KEY };
+
+    // The stale hand-off (owner key matches, but the row is terminal) is FENCED: it dedupes
+    // idempotently, mints no instance, and leaves the settled row byte-for-byte untouched.
+    const a = mk();
+    let calls = 0;
+    const engine = { createInstance: async () => ({ processInstanceKey: `PI-CONV-${++calls}` }) } as any;
+    const stale = await submitPr(a.data, engine, parsed, [], undefined, false, null, false, false, true, "PI-MERGE");
+    assertEquals((stale as any).alreadyRunning, true, "a stale hand-off against a terminal row dedupes instead of re-entering convergence");
+    assertEquals(calls, 0, "no fresh instance is minted for the stale hand-off");
+    assertEquals(a.stores.pull_requests.rows[0].status, "merged", "the settled row's state is untouched");
+    assertEquals(a.stores.pull_requests.rows[0].process_key, "PI-MERGE", "the settled row's owner is untouched");
+
+    // A deliberate PUBLIC resubmission of the same settled PR (no handoffFrom) still re-opens it —
+    // the fence only closes the internal hand-off channel, never the terminal→resubmittable path.
+    const b = mk();
+    const resubmit = await submitPr(b.data, engine, parsed);
+    assertEquals((resubmit as any).alreadyRunning, undefined);
+    assertEquals(calls, 1);
+    assertEquals(b.stores.pull_requests.rows[0].status, "converging");
+    assertEquals(b.stores.pull_requests.rows[0].process_key, "PI-CONV-1");
+  });
+});
+
+// Issue #941 review: if the adjudication reset fails AFTER the atomic reopen advanced `process_key`
+// to the new convergence instance, the rollback cancels that instance — but leaving its key on the
+// row would make the cancelled run the row's "owner". Once tracking derives `abandoned`, the stale
+// hand-off fence would treat the reconverge retry as settled and end the merge loop with no live
+// convergence owner. The rollback must RESTORE the prior row (owner key + status), so the retry is
+// still the owning hand-off and re-enters convergence.
+test("submitPr handoffFrom: a failed reset restores the prior owner so the hand-off retry re-enters (#941)", async () => {
+  await withGithubOff(async () => {
+    const PR_KEY = "owner/repo#79";
+    const stores: Record<string, { rows: any[]; key: string }> = {
+      pull_requests: {
+        rows: [{ pr_key: PR_KEY, repo: "owner/repo", number: 79, url: "https://github.com/owner/repo/pull/79", title: "t", status: "waiting_merge", current_round: 4, process_key: "PI-MERGE" }],
+        key: "pr_key",
+      },
+      escalations: { rows: [], key: "id" },
+      pr_adjudications: { rows: [], key: "id" },
+      pr_dependencies: { rows: [], key: "pr_key" },
+    };
+    let failReset = true;
+    const open = () => {
+      const real = memOpen(stores);
+      return {
+        ...real,
+        exec: async (sql: string, ...rest: unknown[]) => {
+          if (failReset && /DELETE FROM "pr_adjudications"/.test(sql)) throw new Error("boom: reset failed");
+          return (real as any).exec(sql, ...rest);
+        },
+      };
+    };
+    const data = { table: withTrackingViews((name: string, key: string) => memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key)), open } as any;
+    let calls = 0;
+    const cancelled: string[] = [];
+    const engine = {
+      createInstance: async () => ({ processInstanceKey: `PI-CONV-${++calls}` }),
+      cancelInstance: async (i: { processInstanceKey: string }) => {
+        cancelled.push(i.processInstanceKey);
+      },
+    } as any;
+    const parsed = { repo: "owner/repo", number: 79, url: "https://github.com/owner/repo/pull/79", prKey: PR_KEY };
+
+    let threw = false;
+    try {
+      await submitPr(data, engine, parsed, [], undefined, false, null, false, false, true, "PI-MERGE");
+    } catch {
+      threw = true;
+    }
+    assertEquals(threw, true);
+    assertEquals(cancelled, ["PI-CONV-1"]);
+    const row = stores.pull_requests.rows[0];
+    assertEquals(row.process_key, "PI-MERGE", "rollback restores the prior owner, never leaves the cancelled key");
+    assertEquals(row.status, "waiting_merge", "rollback restores the prior status");
+    assertEquals(row.current_round, 4);
+
+    failReset = false;
+    const retry = await submitPr(data, engine, parsed, [], undefined, false, null, false, false, true, "PI-MERGE");
+    assertEquals((retry as any).alreadyRunning, undefined, "the retried hand-off re-enters convergence");
+    assertEquals(stores.pull_requests.rows[0].process_key, "PI-CONV-2");
+  });
+});

package/app/service.ts

@@ -288,6 +288,14 @@ export const MERGEABLE_REPOLL_INTERVAL = mergeableRepollInterval(
  * to one attempt per window. Set via `NANO_PR_REVIEW_NUDGE_MINUTES` (minutes). */
 export const REVIEW_NUDGE_MS = clampNudgeMinutes(process.env.NANO_PR_REVIEW_NUDGE_MINUTES) * 60_000;
 
+/** Merge-loop head-current review request (issue #939). When the merge backstop finds no
+ * head-current Copilot review (the loop's own rebase/fix push moved the head), the merge loop
+ * requests the review itself and waits `REVIEW_REQUEST_WAIT` before re-checking — derived from the
+ * SAME nudge window the convergence poller uses, so there is one knob for "how long to give Copilot".
+ * It re-requests up to `MAX_REVIEW_REQUESTS` times before escalating (stating what was tried). */
+export const REVIEW_REQUEST_WAIT = `PT${Math.round(REVIEW_NUDGE_MS / 60_000)}M`;
+export const MAX_REVIEW_REQUESTS = 3;
+
 /** Grace window (ms) before the `escalated`→`running` self-heal (below) may act on a row. The sole
  * writer of `status="escalated"` — `record-feature-escalation` — runs on the `escalated` arm and stamps
  * `updated_at` IMMEDIATELY BEFORE the engine creates the `feature-escalation` user task. A poll landing
@@ -632,9 +640,11 @@ export async function submitPr(
   humanApproval = false,
   autoResolveEscalations = false,
   autoMerge?: boolean,
+  handoffFrom: string | null = null,
+  headShaOverride: string | null = null,
 ) {
   return withPrSubmitLock(parsed.prKey, () =>
-    submitPrCritical(data, engine, parsed, dependsOn, maxRounds, convergeOnly, rootRequestKey, humanApproval, autoResolveEscalations, autoMerge),
+    submitPrCritical(data, engine, parsed, dependsOn, maxRounds, convergeOnly, rootRequestKey, humanApproval, autoResolveEscalations, autoMerge, handoffFrom, headShaOverride),
   );
 }
 
@@ -649,6 +659,8 @@ async function submitPrCritical(
   humanApproval = false,
   autoResolveEscalations = false,
   autoMerge?: boolean,
+  handoffFrom: string | null = null,
+  headShaOverride: string | null = null,
 ) {
   // Merge intent (issue #916): `autoMerge` is the CANONICAL positive form end to end — the same name
   // the feature/convergence-loop/plan-fanout doors accept. The legacy inverted `convergeOnly`
@@ -680,7 +692,28 @@ async function submitPrCritical(
   // would skip it as non-terminal, never re-enrolling). Treat a keyless non-terminal row as
   // RESUBMITTABLE — fall through and re-enroll, exactly as `startFeature`'s intake guard (feature.ts)
   // treats a keyless `running` feature row. A terminal row (any `process_key`) already falls through.
-  if (trackedExisting && existing?.process_key != null && !TERMINAL_STATUSES.includes(trackedExisting.derived_status)) {
+  // Merge-loop → convergence hand-back (issue #939): the merge-loop instance that currently OWNS the
+  // row (`process_key`) re-enters convergence when a head-current review reports findings. That
+  // instance is live (it is the caller, and ends right after this submit), so it must not read as
+  // "already running" — only the exact owning instance may hand back; any other key still dedupes.
+  // The bypass additionally requires the row to be LIVE (non-terminal, #941 review): a redelivered
+  // `pr.reconverge` can arrive after its successor has already settled the PR (merged/abandoned),
+  // and the settled row's `process_key` still names that stale job's instance — an owner match alone
+  // would let the dead hand-off restart convergence and clear the settled state. So an internal
+  // hand-off against a TERMINAL row is fenced off entirely (below): it dedupes as `alreadyRunning`
+  // instead of resubmitting. Only a DELIBERATE PUBLIC submission (no `handoffFrom`) may re-open a
+  // settled PR — the internal hand-off channel never may. A partially-failed hand-off's retry
+  // against a keyless NON-terminal row still works (that row is not terminal, so it falls through
+  // and re-enrolls via the phantom-row path).
+  const trackedTerminal = trackedExisting != null && TERMINAL_STATUSES.includes(trackedExisting.derived_status);
+  const handingBack =
+    handoffFrom != null && existing?.process_key != null && existing.process_key === handoffFrom && !trackedTerminal;
+  if (handoffFrom != null && trackedTerminal) {
+    // Stale internal hand-off against a settled row: report the existing (terminal) owner without
+    // minting a fresh run or touching the settled state. The redelivered job completes idempotently.
+    return { prKey: parsed.prKey, alreadyRunning: true };
+  }
+  if (!handingBack && trackedExisting && existing?.process_key != null && !trackedTerminal) {
     // Human approval is monotonic (issue #826): a gated caller adopting a live loop — possibly an
     // ungated one another run started — narrows it to gated instead of inheriting its auto-merge.
     // Idempotent, so a retry against our own gated loop is a no-op. A loop the engine no longer reports
@@ -801,7 +834,14 @@ async function submitPrCritical(
   // fleet advertising `durable-resume`: with no participant it stays null, so the round redrives from
   // scratch (graceful degradation). Absent (null) on a first submit, which leaves the envelope
   // unchanged.
-  const worldSha = await worldRestoreSha(data, parsed.prKey);
+  //
+  // `headShaOverride` (#941 round-4 review) WINS over the checkpoint: the checkpoint is written only
+  // by the convergence loop's `pr.persist-round`, so a merge-stage rebase/fix-ci push advances the PR
+  // head WITHOUT updating it. A merge→convergence hand-off (`pr.reconverge`) that restored the
+  // checkpoint would provision the fresh run at the PRE-MERGE tree, not the head whose review raised
+  // the findings — so the hand-off passes the live head SHA it read, and a fresh hand-off restores
+  // the CURRENT head. `null` (every other caller) keeps the checkpoint resume.
+  const worldSha = headShaOverride ?? (await worldRestoreSha(data, parsed.prKey));
   const { processInstanceKey } = await engine.createInstance({
     processDefinitionId: PROCESS_ID,
     variables: {
@@ -877,6 +917,11 @@ async function submitPrCritical(
   // run auto-applies stale decisions, and (crucially) the row stays in its OLD terminal shape until
   // the atomic reopen write lands, so no straggler ever sees a fresh-run row still owned by the old
   // instance.
+  let reopened = false;
+  // Snapshot BEFORE the reopen write — the row object may be a live reference the update mutates.
+  const prior = existing
+    ? { status: existing.status, current_round: existing.current_round, process_key: existing.process_key }
+    : null;
   try {
     if (existing) {
       // ATOMIC REOPEN (Copilot review of #819): reset the row to the fresh run's shape AND publish the
@@ -931,6 +976,7 @@ async function submitPrCritical(
         process_key: processKey,
         updated_at: ts,
       });
+      reopened = true;
     } else if (processKey != null) {
       // First submit: the row was INSERTED keyless before `createInstance` (the phantom-row pattern,
       // #704/#497); publish its `process_key` now that the instance exists.
@@ -949,6 +995,19 @@ async function submitPrCritical(
       await resetAdjudications(data, parsed.prKey);
     }
   } catch (err) {
+    // Restore the prior row (#941 review): the atomic reopen already advanced `process_key` to the
+    // instance we are about to cancel. Leaving that cancelled key on the row would make a dead run its
+    // "owner" — once tracking derives `abandoned`, a retried merge-loop hand-off would be fenced as
+    // stale (settled row) and the merge loop would end with no live convergence owner. Restoring the
+    // pre-reopen shape (owner key + status) keeps the retry the owning hand-off, and a public retry
+    // still sees the old terminal row as resubmittable.
+    if (reopened && prior) {
+      try {
+        await table.update(parsed.prKey, { ...prior, updated_at: now() });
+      } catch (restoreErr) {
+        console.warn(`[submit] ${parsed.prKey} rollback-restore failed: ${restoreErr}`);
+      }
+    }
     if (processInstanceKey != null) {
       try {
         await engine.cancelInstance({ processInstanceKey: String(processInstanceKey) });
@@ -1025,6 +1084,11 @@ export async function startMerge(
       mergeableRepollInterval: MERGEABLE_REPOLL_INTERVAL,
       mergeStallRounds: 0,
       mergeStallMax: MAX_MERGE_STALL_ROUNDS,
+      // Head-current review request budget (issue #939): see REVIEW_REQUEST_WAIT.
+      reviewRequestRound: 0,
+      reviewRequestMax: MAX_REVIEW_REQUESTS,
+      reviewRequestWait: REVIEW_REQUEST_WAIT,
+      reviewRequest: null,
       // Lineage (issue #245): thread the origin identity onto the merge instance (see startMerge).
       rootRequestKey,
       abandonUrl: abUrl,

package/build-info.json

@@ -1,6 +1,6 @@
 {
-  "version": "0.207.0",
-  "gitSha": "e3955c8145a966a29806400872b7a9c362d1d992",
-  "gitTag": "v0.207.0",
-  "builtAt": "2026-11-09T23:52:15.727Z"
+  "version": "0.208.0",
+  "gitSha": "0e2d50e8610beb5e939cd3a143d28e62d690f272",
+  "gitTag": "v0.208.0",
+  "builtAt": "2026-11-10T03:09:52.732Z"
 }

package/nano.app.json

@@ -144,6 +144,14 @@
       "taskType": "pr.merge",
       "handler": "workers/merge/worker.ts"
     },
+    {
+      "taskType": "pr.request-review",
+      "handler": "workers/request-review/worker.ts"
+    },
+    {
+      "taskType": "pr.reconverge",
+      "handler": "workers/reconverge/worker.ts"
+    },
     {
       "taskType": "pr.mark-merged",
       "handler": "workers/mark-merged/worker.ts"

package/package.json

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