@nanobpm/nano-workforce 0.210.0 → 0.210.2

package/app/retro.test.ts

@@ -140,6 +140,17 @@ test("isPlanComplete: true when every task is settled (terminal PR or skipped/bl
   assertEquals(await isPlanComplete(data, PLAN), true);
 });
 
+// Issue #959: a PR that MERGED but whose loop was terminated afterwards derived `abandoned` off the
+// `onTerminated` edge. Retro must still treat it as the landed terminal it is. Model the terminated
+// divergence by seeding the base row at its frozen in-flight transient WITH `merged_at` set: the
+// merge-aware tracking view folds it to `merged`, so the plan reads complete (not stuck-in-flight).
+test("isPlanComplete: a merged-then-terminated PR (frozen base + merged_at) is terminal/landed (#959)", async () => {
+  const { data, stores } = memData();
+  seedTask(stores, { id: "t1", status: "opened", pr_key: "acme/widgets#10" });
+  stores["pull_requests"] = [{ pr_key: "acme/widgets#10", status: "converging", merged_at: "2026-11-01T00:00:00Z" }];
+  assertEquals(await isPlanComplete(data, PLAN), true);
+});
+
 test("isPlanComplete: an empty plan has nothing to retrospect", async () => {
   const { data } = memData();
   assertEquals(await isPlanComplete(data, PLAN), false);

package/app/service.ts

@@ -1464,7 +1464,10 @@ export function isOrphanedPr(p: {
     // Provenance only explains the CURRENT owner's termination: a reason bound to a different
     // (predecessor) instance never masks an orphaned successor.
     !hasOwnTerminationReason(p) &&
-    p.merged_at == null
+    p.merged_at == null &&
+    // #959: a landing recorded only in the merge audit derives `merged` (base still `merging`,
+    // `merged_at` NULL) — that PR landed, it is not orphaned.
+    p.derived_status !== "merged"
   );
 }
 
@@ -2053,7 +2056,7 @@ async function classifyWaveTarget(
   token: string,
 ): Promise<"cleared" | "closed" | "pending"> {
   const tracked = await prsTracking(data).get(prKey);
-  if (tracked && tracked.status === "merged") return "cleared"; // worker-owned terminal, passes through the derive edge unchanged
+  if (tracked && (tracked.status === "merged" || tracked.derived_status === "merged")) return "cleared"; // worker-owned terminal, passes through the derive edge unchanged
   if (tracked && tracked.derived_status === ABANDONED_STATUS) return "cleared"; // ADR-0065 derive-only terminal → non-blocking, no re-reconcile needed
   const parsed = parsePr(prKey);
   if (!parsed) return "cleared"; // unparseable ref can't be checked → never wedge the barrier
@@ -2139,7 +2142,12 @@ export async function mergeLaneDecisionForPr(data: DataLayer, prKey: string): Pr
     // cancelled/terminated (derive-only terminal → `derived_status === "abandoned"`; the base row is
     // still frozen at its transient). Reading only base `status` here missed a cancelled member and
     // stalled/misrouted the lane.
-    if (lanePr && (lanePr.status === "merged" || lanePr.derived_status === "abandoned")) {
+    // #959: an audit-only landing (merge recorded, `pr.mark-merged` never ran) derives `merged` while
+    // the base row is still `merging` — it is just as complete as a base `merged` row.
+    if (
+      lanePr &&
+      (lanePr.status === "merged" || lanePr.derived_status === "merged" || lanePr.derived_status === "abandoned")
+    ) {
       completedPrKeys.add(lanePr.pr_key);
     }
   }

package/app/terminalReaderBehaviour.test.ts

@@ -319,3 +319,47 @@ test("startPlan re-admits a derive-only-abandoned epic (base 'dispatched', deriv
     assertEquals(stores.plan_tasks.rows.length, 0);
   });
 });
+
+// #959: an audit-only landing (merge recorded in `merges`, `pr.mark-merged` never ran) derives
+// `merged` while the base row is still `merging`. It must count as lane-complete and never surface as
+// `orphaned` in /status.
+test("#959 mergeLaneDecisionForPr treats an audit-only landed (derived merged) predecessor as complete", async () => {
+  const PLAN_KEY = "o/r#100";
+  const stores: Stores = {
+    plan_tasks: {
+      rows: [
+        { id: 1, plan_key: PLAN_KEY, task_id: "a", pr_key: "o/r#1" },
+        { id: 2, plan_key: PLAN_KEY, task_id: "b", pr_key: "o/r#2" },
+      ],
+      key: "id",
+    },
+    plan_merge_exclusions: {
+      rows: [{ id: 1, plan_key: PLAN_KEY, task_a: "a", task_b: "b", files: JSON.stringify(["shared.ts"]), source: "file-overlap" }],
+      key: "id",
+    },
+    plan_task_deps: { rows: [], key: "plan_key" },
+    pull_requests: {
+      rows: [
+        { pr_key: "o/r#1", repo: "o/r", number: 1, status: "merging", derived_status: "merged", merged_at: null },
+        { pr_key: "o/r#2", repo: "o/r", number: 2, status: "converging", derived_status: "converging" },
+      ],
+      key: "pr_key",
+    },
+  };
+  const decision = await mergeLaneDecisionForPr(memData(stores), "o/r#2");
+  assertEquals(decision?.isHeld, false);
+});
+
+test("#959 activePrs does not surface an audit-only landed (derived merged) PR as orphaned", async () => {
+  const stores: Stores = {
+    pull_requests: {
+      rows: [
+        { pr_key: "o/r#1", repo: "o/r", number: 1, url: "u1", status: "merging", derived_status: "merged", merged_at: null, current_round: 1, updated_at: "2024-01-01" },
+      ],
+      key: "pr_key",
+    },
+    escalations: { rows: [], key: "id" },
+  };
+  const active = await activePrs(memData(stores));
+  assertEquals(active.some((p) => p.status === "orphaned"), false);
+});

package/build-info.json

@@ -1,6 +1,6 @@
 {
-  "version": "0.210.0",
-  "gitSha": "c1a72ce90744ccd23aa8160d20f0add2779db837",
-  "gitTag": "v0.210.0",
-  "builtAt": "2026-11-12T10:53:21.705Z"
+  "version": "0.210.2",
+  "gitSha": "56f0ff4c4a3a0d8a3cf68745b1f7b9bf539987da",
+  "gitTag": "v0.210.2",
+  "builtAt": "2026-11-14T15:30:46.025Z"
 }

package/db/migrations/139_pull_requests_backfill_merged_not_abandoned.sql

@@ -0,0 +1,40 @@
+-- Backfill for issue #959: merged PRs whose run was terminated afterwards showed as "abandoned".
+--
+-- ROOT CAUSE. `pull_requests__tracking.derived_status` mapped ANY terminated run to `abandoned`
+-- without consulting the PR's merge state. Of the 24 top-level runs terminated in November, 23
+-- belong to PRs that MERGED on GitHub — an operator cancelled a redundant post-merge loop, an
+-- out-of-band merge (Mergify / a manual click) was reconciled, or a restart/upgrade cleaned up. Every
+-- one read "abandoned", which made the status untrustworthy and skewed retro/conformance stats
+-- (`LANDED_PR_STATUSES` excludes `abandoned`, so merged PRs didn't count as landed).
+--
+-- THE FIX is the merge-aware derivation (app/prTrackingReadModel.ts): a landed PR now reads `merged`
+-- regardless of how its instance ended, keyed off the base row's `merged_at`. That derivation is
+-- merge-aware ONLY when `merged_at` is set — but several out-of-band/reconciled merges terminated the
+-- loop BEFORE `pr.mark-merged` (or the review-wait retire) could stamp `merged_at`, leaving the base
+-- row frozen at its in-flight transient (`converging`/`waiting_merge`/…) with `merged_at` NULL. For
+-- those rows the derivation still has no merge signal, so they would keep reading `abandoned`.
+--
+-- This migration re-derives the existing rows so the 23 show as `merged`: any `pull_requests` row
+-- that has a `merged` outcome in its `merges` audit trail but whose base `status` is not already
+-- `merged` (and that has no `merged_at` yet) is stamped `status='merged'` + `merged_at`. The audit
+-- trail (`merges.outcome='merged'`) is the canonical record that the PR landed — written by
+-- `pr.mark-merged`, the merge worker's already-merged short-circuit, and the out-of-band retire path.
+-- With the base row settled to `merged`, the derivation reads `merged` whether or not the instance
+-- was later terminated (the terminated edge is gated on `merged_at IS NULL`).
+--
+-- Idempotent and additive-only: it touches only rows with a recorded `merged` audit outcome that are
+-- not already settled `merged`, and never overwrites an existing `merged_at`. `merged_at` is stamped
+-- from the earliest `merged` audit row (`MIN(m.at)`), falling back to the current timestamp when that
+-- is somehow NULL. Safe to re-run.
+UPDATE pull_requests
+SET status = 'merged',
+    merged_at = COALESCE(
+      merged_at,
+      (SELECT MIN(m.at) FROM merges m WHERE m.pr_key = pull_requests.pr_key AND m.outcome = 'merged'),
+      datetime('now')
+    ),
+    updated_at = datetime('now')
+WHERE status <> 'merged'
+  AND EXISTS (
+    SELECT 1 FROM merges m WHERE m.pr_key = pull_requests.pr_key AND m.outcome = 'merged'
+  );

package/main.ts

@@ -23,10 +23,16 @@ import { type AgenticChannelHandle, mountAgenticChannel } from "./app/agentic/ch
 import { makeElementInstanceResolver } from "./app/agentic/element-instance.ts";
 import { mountConsoleRedirect, resolveConsoleOrigin } from "./app/consoleRedirect.ts";
 import { announceEngine, resolveEngineAddress } from "./app/enginePreflight.ts";
+import { registerPullRequestTrackingReadModel } from "./app/prTrackingReadModel.ts";
 import { runEngineReconcile } from "./app/reconcile.ts";
 import { MAX_ROUNDS, pollOnce } from "./app/service.ts";
 import { envVar } from "./app/version.ts";
 
+// Issue #959: register the app-owned, merge-aware `pull_requests__tracking` read model BEFORE the
+// runtime mounts workers/instance-tracking, so the framework provisions THIS derivation (a landed PR
+// reads `merged`, never `abandoned`, however its loop ended) instead of the merge-blind default.
+registerPullRequestTrackingReadModel();
+
 const PORT = Number(process.env.PR_REVIEW_PORT ?? 3000);
 const POLL_MS = Number(process.env.NANO_PR_POLL_MS ?? 60_000);
 const GITHUB_TOKEN = process.env.GITHUB_TOKEN ?? "";

package/package.json

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

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/landed-probe/worker.test.ts

@@ -12,7 +12,7 @@ const base: PrState = {
   totalChecks: 0,
   presentCheckNames: [],
   pendingCheckNames: [],
-  checkConclusions: {},
+  checkGateConclusions: {},
   isDraft: false,
   headRefOid: null,
   mergeQueueEntry: null,

package/workers/merge-stall-probe/worker.test.ts

@@ -18,7 +18,7 @@ function state(over: Partial<PrState>): PrState {
     failingCheckNames: [],
     presentCheckNames: ["build", "Mergify Merge Queue"],
     pendingCheckNames: [],
-    checkConclusions: { build: "SUCCESS", "Mergify Merge Queue": "NEUTRAL" },
+    checkGateConclusions: { build: ["SUCCESS"], "Mergify Merge Queue": ["NEUTRAL"] },
     totalChecks: 2,
     isDraft: false,
     headRefOid: "abc",
@@ -80,7 +80,7 @@ test("merge-stall-probe: BLOCKED gh-merge PR with green checks still waits (#951
 // must NOT classify that head's stale check failures as `blocked` (which starts fix-ci / escalates).
 // It defers to `waiting` (bounded re-poll) until the head moves or the remedy's window lapses.
 test("merge-stall-probe: a blocked verdict on a pending-update old head defers to waiting (#951)", async () => {
-  const blocked = state({ failingChecks: 1, failingCheckNames: ["build"], checkConclusions: { build: "FAILURE" } });
+  const blocked = state({ failingChecks: 1, failingCheckNames: ["build"], checkGateConclusions: { build: ["FAILURE"] } });
   // Sanity: without a pending update this IS blocked (would route to fix-ci).
   assertEquals((await run(blocked, MERGIFY, false)).mergeState, "blocked");
   // With the update still pending on this head, the probe holds remediation.

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(