@nanobpm/nano-workforce 0.210.1 → 0.211.0

package/test/trackingViews.ts

@@ -17,6 +17,21 @@ import { baseStatusFieldFor, baseTableForTrackingView, trackingTargetFor } from
 // biome-ignore lint/suspicious/noExplicitAny: test-only fake `table` resolver over dynamic row shapes.
 type TableFn = (name: string, pk?: string) => any;
 
+/** Project a base row onto its tracking-VIEW shape: the base columns plus `derived_status`. Mirrors
+ *  the merge-aware derivation (app/prTrackingReadModel.ts, issue #959): an explicitly-seeded
+ *  `derived_status` (a test modelling the ADR-0065 terminated divergence) wins ONLY when the row has
+ *  NOT landed — a `merged_at` stamp folds the effective status to `merged` regardless, exactly as the
+ *  real VIEW's merged-beats-terminated `WHEN` does. Absent an explicit override, the VIEW's
+ *  `ELSE base.<statusField>` fall-through applies. */
+// biome-ignore lint/suspicious/noExplicitAny: test-only projection over dynamic row shapes.
+function projectRow(row: any, derivedColumn: string, statusField: string) {
+  if (row == null) return row;
+  const seeded = row[derivedColumn];
+  // merged beats terminated: a landed PR (merged_at set) is `merged` even when its run was terminated.
+  if (row.merged_at != null) return { ...row, [derivedColumn]: "merged" };
+  return { ...row, [derivedColumn]: seeded ?? row[statusField] };
+}
+
 /** Decorate a fake `table(name, pk)` resolver so it also serves every `<table>__tracking` derived
  * VIEW off the corresponding base store, projecting `derived_status := base.<statusField>` onto each
  * row the read methods (`findOne`/`get`/`find`/`all`) return. A non-tracking name is passed through
@@ -29,18 +44,7 @@ export function withTrackingViews<F extends TableFn>(base: F): F {
     const derivedColumn = trackingTargetFor(baseName).statusColumn;
     const statusField = baseStatusFieldFor(baseName);
     // biome-ignore lint/suspicious/noExplicitAny: test-only projection over dynamic row shapes.
-    const project = (row: any) =>
-      row == null
-        ? row
-        : // Honor an explicitly-seeded `derived_status` so a test can model the ADR-0065 divergence a
-          // real terminated instance produces — the base `<statusField>` frozen at its last transient
-          // while the derive edge reports the terminal (`abandoned`/`failed`/`reviewed`). When a row
-          // seeds no derived column the VIEW's `ELSE base.<statusField>` fall-through applies, so it
-          // stays byte-for-byte the pass-through the previous behaviour modelled.
-          {
-            ...row,
-            [derivedColumn]: row[derivedColumn] ?? row[statusField],
-          };
+    const project = (row: any) => projectRow(row, derivedColumn, statusField);
     // biome-ignore lint/suspicious/noExplicitAny: test-only Proxy over a dynamic DataLayer table.
     return new Proxy(inner, {
       get(target: any, prop: string) {

package/workers/reconverge/worker.test.ts

@@ -1,9 +1,106 @@
 // 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 { assert, assertEquals, assertRejects, assertStringIncludes } from "#test-assert";
 import { noopLog } from "../../test/log.ts";
-import { makeHandler, type FetchPrHead, type Submit } from "./worker.ts";
+import { makeHandler, type FetchPrHead, type ReadLiveness, type Submit } from "./worker.ts";
+
+// Deterministic liveness stub for hand-off tests: never reach the real GitHub transport.
+const openLive: ReadLiveness = async () => "open";
+const nullHead = (async () => null) as unknown as FetchPrHead;
+
+// Issue #959: a reconverge hand-off can fire AFTER the PR landed out-of-band (a gate override /
+// Mergify / a manual merge). Re-entering `submitPr` on a landed PR would restart a redundant
+// convergence loop against a deleted head branch (the nano-bpm#1579 clone incident). The worker must
+// instead stamp the row `merged` (so the merge-aware derivation reports `merged`, not `abandoned`,
+// when the instance then ends), record the already-merged audit row, and end the loop cleanly — NOT
+// reconverge.
+test("an already-merged PR ends the loop cleanly instead of reconverging (#959)", async () => {
+  const merges: Record<string, unknown>[] = [];
+  const updates: Record<string, unknown>[] = [];
+  const app = {
+    data: {
+      table: (name: string) => ({
+        get: async () => (name === "pull_requests" ? { auto_resolve_escalations: 0 } : undefined),
+        find: async () => [],
+        findOne: async () => undefined,
+        insert: async (r: Record<string, unknown>) => (merges.push(r), 1),
+        update: async (_k: string, patch: Record<string, unknown>) => (updates.push(patch), undefined),
+      }),
+      source: () => ({ on: () => {}, off: () => {}, emit: () => {} }),
+    },
+    engine: { createInstance: async () => ({ processInstanceKey: "retro-1" }) },
+    log: noopLog(),
+  } as any;
+  let submitted = false;
+  const submit = (async () => {
+    submitted = true;
+    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;
+  const live: ReadLiveness = async () => "merged";
+  const out = await makeHandler(submit, head, live)({ processInstanceKey: "4242", variables: { prKey: "acme/w#7" } } as any, app);
+  // Ends cleanly — NO reconverge submit, no mergeStatus routing (the loop completes at MergeReconverged).
+  assertEquals(submitted, false);
+  assertEquals(out, {});
+  // The row is stamped landed (merged_at set) so the derivation reports `merged` on termination.
+  assert(updates.some((u) => u.status === "merged" && typeof u.merged_at === "string"), "row must be stamped merged");
+  // The audit trail carries the already-merged landing (alongside the reconverge-findings record).
+  const landing = merges.filter((m) => m.outcome === "merged");
+  assertEquals(landing.length, 1);
+  assertEquals(landing[0].method, "already-merged");
+});
+
+// The guard must NOT fire on a still-open PR: the normal reconverge hand-off proceeds.
+test("a still-open PR proceeds with the normal reconverge hand-off", async () => {
+  const app = {
+    data: {
+      table: (name: string) => ({
+        get: async () => (name === "pull_requests" ? { auto_resolve_escalations: 0 } : undefined),
+        insert: async () => 1,
+        update: async () => undefined,
+      }),
+    },
+    engine: {},
+    log: noopLog(),
+  } as any;
+  let submitted = false;
+  const submit = (async () => {
+    submitted = true;
+    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;
+  const live: ReadLiveness = async () => "open";
+  const out = await makeHandler(submit, head, live)({ processInstanceKey: "4242", variables: { prKey: "acme/w#7" } } as any, app);
+  assertEquals(submitted, true);
+  assertEquals(out, {});
+});
+
+// An unreadable liveness read (transport hiccup) must not block a genuine reconverge — fail open.
+test("an unreadable liveness read falls through to the normal hand-off (fail-open)", async () => {
+  const app = {
+    data: {
+      table: (name: string) => ({
+        get: async () => (name === "pull_requests" ? { auto_resolve_escalations: 0 } : undefined),
+        insert: async () => 1,
+        update: async () => undefined,
+      }),
+    },
+    engine: {},
+    log: noopLog(),
+  } as any;
+  let submitted = false;
+  const submit = (async () => {
+    submitted = true;
+    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;
+  const live: ReadLiveness = async () => {
+    throw new Error("github unreachable");
+  };
+  await makeHandler(submit, head, live)({ processInstanceKey: "4242", variables: { prKey: "acme/w#7" } } as any, app);
+  assertEquals(submitted, true);
+});
 
 test("re-submits through submitPr with auto-merge on and handoffFrom = this merge-loop instance", async () => {
   const merges: Record<string, unknown>[] = [];
@@ -22,7 +119,7 @@ test("re-submits through submitPr with auto-merge on and handoffFrom = this merg
     args = a;
     return { prKey: "acme/w#7" };
   }) as unknown as Submit;
-  await makeHandler(submit)({ processInstanceKey: "4242", variables: { prKey: "acme/w#7" } } as any, app);
+  await makeHandler(submit, nullHead, openLive)({ 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");
@@ -49,7 +146,7 @@ test("throws on a null processKey so the hand-off stays retryable (#941)", async
   } 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),
+    () => makeHandler(submit, nullHead, openLive)({ processInstanceKey: "4242", variables: { prKey: "acme/w#7" } } as any, app),
     Error,
     "null processKey",
   );
@@ -84,7 +181,7 @@ test("hands off at the CURRENT PR head, not the stale convergence checkpoint (#9
     baseRef: "main",
     headRepo: "acme/w",
   })) as unknown as FetchPrHead;
-  await makeHandler(submit, head)({ processInstanceKey: "4242", variables: { prKey: "acme/w#7" } } as any, app);
+  await makeHandler(submit, head, openLive)({ 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");
 });
 
@@ -105,7 +202,7 @@ test("a head read that resolves no SHA degrades to the checkpoint restore (no ov
     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);
+  await makeHandler(submit, head, openLive)({ 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)");
 });
 
@@ -134,7 +231,7 @@ test("preserves the run's custom instructions across the merge→reconvergence h
     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);
+  await makeHandler(submit, head, openLive)({ processInstanceKey: "4242", variables: { prKey: "acme/w#7" } } as any, app);
   assertEquals(args[12], "  commit as josh.wulf@camunda.com  ", "the durable instruction text rides the handoff into the fresh convergence run");
 });
 
@@ -155,6 +252,38 @@ test("a PR row with no stored instructions hands off with null (no steering)", 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);
+  await makeHandler(submit, head, openLive)({ processInstanceKey: "4242", variables: { prKey: "acme/w#7" } } as any, app);
   assertEquals(args[12], null, "no stored text → null (the fresh run's prompts stay byte-identical to no-instructions)");
 });
+
+// A PR closed WITHOUT merging before the hand-off must be settled abandoned via the canonical
+// `abandonClosedPr` (row + plan tasks + audit) — never resubmitted into a replacement run.
+test("a closed-unmerged PR is abandoned and no replacement run is submitted", async () => {
+  const merges: Record<string, unknown>[] = [];
+  const prUpdates: Record<string, unknown>[] = [];
+  const app = {
+    data: {
+      table: (name: string) => ({
+        get: async () => (name === "pull_requests" ? { pr_key: "acme/w#7", auto_resolve_escalations: 0 } : undefined),
+        find: async () => [],
+        findOne: async () => null,
+        insert: async (r: Record<string, unknown>) => (name === "merges" && merges.push(r), 1),
+        update: async (_k: string, patch: Record<string, unknown>) => (name === "pull_requests" && prUpdates.push(patch), undefined),
+        upsert: async () => undefined,
+      }),
+    },
+    engine: {},
+    log: noopLog(),
+  } as any;
+  let submitted = false;
+  const submit = (async () => {
+    submitted = true;
+    return { prKey: "acme/w#7", processKey: "999" };
+  }) as unknown as Submit;
+  const live: ReadLiveness = async () => "closed";
+  const out = await makeHandler(submit, nullHead, live)({ processInstanceKey: "4242", variables: { prKey: "acme/w#7" } } as any, app);
+  assertEquals(submitted, false);
+  assertEquals(out, {});
+  assert(merges.some((m) => m.outcome === "abandoned" && m.method === "pr-closed"), "closed audit row written");
+  assert(prUpdates.some((u) => u.status === "abandoned"), "row settled abandoned");
+});

package/workers/reconverge/worker.ts

@@ -7,10 +7,16 @@
 // (`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.
+//
+// EXCEPTION (issue #959): if the PR has ALREADY MERGED out-of-band by the time the hand-off fires
+// (a gate override / Mergify / a manual merge landed it), there is nothing to reconverge — the worker
+// stamps the row `merged`, records the already-merged audit, kicks the retrospective, and ends the
+// loop cleanly instead of restarting convergence against a deleted head branch.
 import type { AppJobHandler } from "@nanobpm/urban";
-import { fetchPrHead } from "../../app/github.ts";
+import { classifyPrLiveness, fetchPrHead, fetchPrState } from "../../app/github.ts";
 import { parsePr } from "../../app/prParse.ts";
-import { MAX_ROUNDS, submitPr } from "../../app/service.ts";
+import { maybeStartRetro } from "../../app/retro.ts";
+import { abandonClosedPr, 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.
@@ -18,8 +24,18 @@ type In = WorkerInputs["pr.reconverge"];
 
 export type Submit = typeof submitPr;
 export type FetchPrHead = typeof fetchPrHead;
+/** The PR-liveness reader used for the already-merged guard. Injectable so tests drive the
+ * merged/closed/open matrix without a transport; the default binds the canonical `fetchPrState`. */
+export type ReadLiveness = (repo: string, prNumber: number) => Promise<"open" | "merged" | "closed" | "unknown">;
+
+const defaultReadLiveness: ReadLiveness = async (repo, prNumber) =>
+  classifyPrLiveness(await fetchPrState(repo, prNumber, process.env.GITHUB_TOKEN ?? ""));
 
-export function makeHandler(submit: Submit, fetchHead: FetchPrHead = fetchPrHead): AppJobHandler<In> {
+export function makeHandler(
+  submit: Submit,
+  fetchHead: FetchPrHead = fetchPrHead,
+  readLiveness: ReadLiveness = defaultReadLiveness,
+): AppJobHandler<In> {
   return async (job, app) => {
     const { prKey } = job.variables;
     const parsed = parsePr(prKey);
@@ -54,6 +70,40 @@ export function makeHandler(submit: Submit, fetchHead: FetchPrHead = fetchPrHead
     } catch (err) {
       app.log.warn("reconverge: head read failed — falling back to the checkpoint restore", { prKey, err: String(err) });
     }
+    // Already-merged guard (issue #959): a reconverge hand-off can fire AFTER the PR landed out-of-band
+    // (a gate override / Mergify / a manual merge) — the very race that left nano-bpm#1579's loop dying
+    // trying to clone a deleted head branch. Re-entering `submitPr` on a landed PR would restart a
+    // redundant convergence loop against a deleted head. Detect the terminal merge first and end the
+    // merge loop cleanly instead: stamp the row `merged` (so the merge-aware derivation reports
+    // `merged`, not `abandoned`, when this instance then ends), record the already-merged audit row, and
+    // kick the retrospective exactly as `pr.mark-merged` would. The merge loop then completes normally
+    // at `MergeReconverged` — a COMPLETED instance is NOT the `onTerminated` edge, so the row stays
+    // `merged`. Best-effort: an unreadable liveness (`unknown` / a throw) falls through to the normal
+    // hand-off rather than blocking a genuine reconverge.
+    const liveness = await readLiveness(parsed.repo, parsed.number).catch(() => "unknown" as const);
+    if (liveness === "merged") {
+      const ts = new Date().toISOString();
+      await app.data.table("pull_requests", "pr_key").update(prKey, { status: "merged", merged_at: ts, updated_at: ts });
+      await app.data.table("merges", "id").insert({
+        pr_key: prKey,
+        outcome: "merged",
+        method: "already-merged",
+        detail: "PR was already merged on GitHub (landed out-of-band) — ending the merge loop instead of reconverging",
+        at: ts,
+      });
+      // The merged-completion side effect `pr.mark-merged` runs: an externally merged PR may be its
+      // plan's last to settle, so its automatic retrospective must still start. Best-effort, never throws.
+      await maybeStartRetro(app.data, app.engine, prKey);
+      return {};
+    }
+    // A PR verified CLOSED without merging (it closed between the merge worker's findings and this
+    // hand-off) has nothing to reconverge either: settle it terminal through the ONE canonical
+    // `abandonClosedPr` (row + plan tasks + idempotent audit) and end the loop — never start a
+    // replacement convergence run on a closed PR.
+    if (liveness === "closed") {
+      await abandonClosedPr(app.data, prKey, "PR was closed without merging before the reconverge hand-off");
+      return {};
+    }
     // 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(