@nanobpm/nano-workforce 0.210.1 → 0.210.2

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.210.2](https://github.com/nanobpm/nano-workforce/compare/v0.210.1...v0.210.2) (2026-11-14)
+
+### Bug Fixes
+
+* **tracking:** merged PRs no longer derive 'abandoned' when their run was terminated ([#960](https://github.com/nanobpm/nano-workforce/issues/960)) ([56f0ff4](https://github.com/nanobpm/nano-workforce/commit/56f0ff4c4a3a0d8a3cf68745b1f7b9bf539987da)), closes [nano-bpm#1579](https://github.com/nanobpm/nano-bpm/issues/1579) [#959](https://github.com/nanobpm/nano-workforce/issues/959)
+
 ## [0.210.1](https://github.com/nanobpm/nano-workforce/compare/v0.210.0...v0.210.1) (2026-11-12)
 
 ### Bug Fixes

package/app/abandon.test.ts

@@ -134,6 +134,37 @@ test("abandonStatusForToken derives abandoned from the row status", async () =>
   assertEquals(await abandonStatusForToken(data, "nope"), undefined);
 });
 
+test("abandonStatusForToken aborts a MERGED PR whose owning run was terminated (owner_terminated)", async () => {
+  // derived_status reports a landed PR as `merged` even when its run was terminated (#959), so the
+  // cancellation signal rides the separate owner_terminated column — terminating a redundant
+  // post-merge round must still tell its agent to stop.
+  const data = memData();
+  await data.table("pull_requests", "pr_key").insert({
+    pr_key: "o/r#4",
+    abandon_token: "landed-term",
+    status: "merged",
+    merged_at: "t",
+    owner_terminated: 1,
+  });
+  await data.table("pull_requests", "pr_key").insert({
+    pr_key: "o/r#5",
+    abandon_token: "landed-live",
+    status: "merged",
+    merged_at: "t",
+    owner_terminated: null,
+  });
+  assertEquals(await abandonStatusForToken(data, "landed-term"), {
+    prKey: "o/r#4",
+    status: "merged",
+    abandoned: true,
+  });
+  assertEquals(await abandonStatusForToken(data, "landed-live"), {
+    prKey: "o/r#5",
+    status: "merged",
+    abandoned: false,
+  });
+});
+
 test("abandonStatusForToken fails CLOSED on a non-string derived status", async () => {
   // A malformed/missing derived_status must never be reported as `abandoned:false`
   // (that would let a cancelled run proceed with irreversible side effects). It throws

package/app/abandon.ts

@@ -24,12 +24,15 @@
 import type { DataLayer } from "@nanobpm/urban";
 import { publicBaseUrl } from "./blackboard.ts";
 import { trackingTargetFor } from "./instanceTracking.ts";
+import { OWNER_TERMINATED_COLUMN } from "./prTrackingReadModel.ts";
 
 /** The one derived-status value meaning a PR is terminally abandoned — the run must not be worked on
  * further. Two disjoint producers surface a row here, and both are non-completion terminals that must
  * stop a servicing agent:
  *   1. an explicit **cancel** of a live convergence/merge run (Urban's cancel primitive terminates
- *      the instance; the `instanceTracking` `onTerminated.set` edge derives `abandoned` on read), and
+ *      the instance; the `instanceTracking` `onTerminated.set` edge derives `abandoned` on read) —
+ *      but ONLY when the PR did NOT land: the merge-aware derivation (app/prTrackingReadModel.ts,
+ *      issue #959) folds a terminated-but-MERGED PR to `merged`, never `abandoned`, and
  *   2. **`abandonClosedPr`** reconciling a wave-member PR that was **closed on GitHub without
  *      merging** (#352) — for both `pull_requests` and its `plan_tasks` — by writing the base row.
  * Convergence/merge terminal states `converged`/`merged` are NOT abandonment. In either abandoned
@@ -116,7 +119,10 @@ export async function abandonStatusForToken(
     );
   }
   const status = rawStatus;
-  return { prKey: row.pr_key, status, abandoned: isAbandoned(status) };
+  // `derived_status` reports a landed PR as `merged` even when its run was terminated (issue #959),
+  // so termination is read from its own column: a terminated owner ALWAYS aborts the agent.
+  const ownerTerminated = Boolean(row[OWNER_TERMINATED_COLUMN]);
+  return { prKey: row.pr_key, status, abandoned: isAbandoned(status) || ownerTerminated };
 }
 
 /** The instruction block appended (verbatim, via `appendPrompt`) to each side-effecting agent's

package/app/conformance.test.ts

@@ -126,6 +126,23 @@ test("hasDeliveredImplementation: true iff at least one PR landed", async () =>
   assert(hasDeliveredImplementation(await gatherConformance(data, PLAN)));
 });
 
+// Issue #959: a PR that MERGED but whose loop was terminated afterwards (operator cancel, out-of-band
+// merge reconcile, restart cleanup) derived `abandoned` off the `onTerminated` edge — and conformance
+// then refused to count it as landed. The merge-aware derivation folds it to `merged` (merged_at set),
+// so a merged-then-terminated PR IS landed. Model the terminated divergence by seeding the base row at
+// its frozen transient (`converging`) WITH `merged_at` set: the tracking view must report `merged`.
+test("hasDeliveredImplementation: a merged-then-terminated PR (frozen base + merged_at) counts as landed (#959)", async () => {
+  const { data, stores } = memData();
+  seedPlan(stores);
+  seedTask(stores, { id: 1, task_index: 0, task_id: "t1", status: "opened", pr_key: "acme/widgets#10" });
+  // Base status frozen at the in-flight transient, but the PR landed (merged_at set) before termination.
+  stores["pull_requests"] = [{ pr_key: "acme/widgets#10", status: "converging", merged_at: "2026-11-01T00:00:00Z" }];
+  assertEquals(await hasDeliveredImplementationForPlan(data, PLAN), true);
+  const d = await gatherConformance(data, PLAN);
+  assertEquals(hasDeliveredImplementation(d), true);
+  assertEquals(d.slices.find((s) => s.taskId === "t1")?.landed, true);
+});
+
 test("hasDeliveredImplementationForPlan: matches the digest without a blackboard scan", async () => {
   const { data, stores } = memData();
   seedPlan(stores);

package/app/loopTermination.test.ts

@@ -410,3 +410,7 @@ test("PR#944 round 6: a successor-owned converging row is NEVER demoted by a red
   assertEquals(stores.pull_requests[0].process_key, "succ");
   assertEquals(stores.pull_requests[0].retire_pending_key, "merge-1", "the pending retirement is left for retryPendingRetirements");
 });
+
+test("#959 isOrphanedPr: an audit-only landing (derived merged, base merging, no merged_at) is never orphaned", () => {
+  assert(!isOrphanedPr({ status: "merging", derived_status: "merged", termination_reason: null, merged_at: null }));
+});

package/app/migration139.test.ts

@@ -0,0 +1,115 @@
+// Migration guard for 139_pull_requests_backfill_merged_not_abandoned.sql (issue #959): the backfill
+// that re-derives the 23 merged-but-terminated PRs so they show as `merged`, not `abandoned`.
+//
+// Applies the migration to a real in-memory SQLite DB over a pre-existing `pull_requests` + `merges`
+// shape and asserts the contract:
+//   * a row with a `merged` audit outcome but a non-`merged` base status (the loop terminated before
+//     `merged_at` was stamped) is settled to `status='merged'` + `merged_at` — so the merge-aware
+//     derivation reports `merged` however the instance ended;
+//   * a row already settled `merged` is left untouched (idempotent);
+//   * a row with NO `merged` audit outcome (a genuinely abandoned/closed-unmerged run) is NOT
+//     flipped — it stays at its frozen transient so the derivation still reports `abandoned`;
+//   * re-running the migration is a no-op (forward-only, idempotent).
+import { readFileSync } from "node:fs";
+import { DatabaseSync } from "node:sqlite";
+import { test } from "node:test";
+import { fileURLToPath } from "node:url";
+import { assertEquals } from "#test-assert";
+
+const MIGRATION_139 = fileURLToPath(
+  new URL("../db/migrations/139_pull_requests_backfill_merged_not_abandoned.sql", import.meta.url),
+);
+
+function migratedDb(): DatabaseSync {
+  const db = new DatabaseSync(":memory:");
+  db.exec(
+    `CREATE TABLE pull_requests (
+       pr_key TEXT PRIMARY KEY,
+       repo TEXT NOT NULL,
+       number INTEGER NOT NULL,
+       status TEXT NOT NULL,
+       process_key TEXT,
+       merged_at TEXT,
+       updated_at TEXT
+     );
+     CREATE TABLE merges (
+       id INTEGER PRIMARY KEY AUTOINCREMENT,
+       pr_key TEXT NOT NULL,
+       outcome TEXT NOT NULL,
+       method TEXT,
+       detail TEXT,
+       at TEXT NOT NULL
+     );`,
+  );
+  return db;
+}
+
+function addPr(db: DatabaseSync, prKey: string, status: string, mergedAt: string | null = null): void {
+  db.prepare(
+    "INSERT INTO pull_requests (pr_key, repo, number, status, process_key, merged_at, updated_at) VALUES (?, 'o/r', 1, ?, 'PI-1', ?, 't0')",
+  ).run(prKey, status, mergedAt);
+}
+
+function addMerge(db: DatabaseSync, prKey: string, outcome: string, at: string): void {
+  db.prepare("INSERT INTO merges (pr_key, outcome, method, detail, at) VALUES (?, ?, 'squash', 'd', ?)").run(prKey, outcome, at);
+}
+
+function row(db: DatabaseSync, prKey: string): { status: string; merged_at: string | null } {
+  return db.prepare("SELECT status, merged_at FROM pull_requests WHERE pr_key = ?").get(prKey) as {
+    status: string;
+    merged_at: string | null;
+  };
+}
+
+const SQL = () => readFileSync(MIGRATION_139, "utf8");
+
+test("139 backfills a merged-but-terminated PR (frozen transient + merged audit) to status='merged' + merged_at", () => {
+  const db = migratedDb();
+  // The #959 case: PR landed (merged audit row) but the loop was terminated before merged_at was set,
+  // leaving the base status frozen at its in-flight transient.
+  addPr(db, "o/r#landed", "converging", null);
+  addMerge(db, "o/r#landed", "merged", "2026-11-01T02:03:04Z");
+  db.exec(SQL());
+  const r = row(db, "o/r#landed");
+  assertEquals(r.status, "merged");
+  assertEquals(r.merged_at, "2026-11-01T02:03:04Z", "merged_at is stamped from the earliest merged audit row");
+  db.close();
+});
+
+test("139 leaves an already-merged row untouched (idempotent, never overwrites merged_at)", () => {
+  const db = migratedDb();
+  addPr(db, "o/r#already", "merged", "2026-10-30T00:00:00Z");
+  addMerge(db, "o/r#already", "merged", "2026-10-30T00:00:00Z");
+  db.exec(SQL());
+  const r = row(db, "o/r#already");
+  assertEquals(r.status, "merged");
+  assertEquals(r.merged_at, "2026-10-30T00:00:00Z");
+  db.close();
+});
+
+test("139 does NOT flip a closed-unmerged / genuinely-abandoned PR (no merged audit outcome)", () => {
+  const db = migratedDb();
+  // A PR closed without merging: terminated → abandoned, NO merged audit row. Must stay un-merged.
+  addPr(db, "o/r#closed", "converging", null);
+  addMerge(db, "o/r#closed", "abandoned", "2026-11-01T00:00:00Z");
+  // A still-in-flight PR with no merge record at all.
+  addPr(db, "o/r#inflight", "waiting_merge", null);
+  db.exec(SQL());
+  assertEquals(row(db, "o/r#closed").status, "converging", "no merged outcome → not flipped to merged");
+  assertEquals(row(db, "o/r#closed").merged_at, null);
+  assertEquals(row(db, "o/r#inflight").status, "waiting_merge");
+  assertEquals(row(db, "o/r#inflight").merged_at, null);
+  db.close();
+});
+
+test("139 is idempotent — a second run is a no-op", () => {
+  const db = migratedDb();
+  addPr(db, "o/r#landed", "waiting_merge", null);
+  addMerge(db, "o/r#landed", "merged", "2026-11-01T02:03:04Z");
+  db.exec(SQL());
+  const first = row(db, "o/r#landed");
+  db.exec(SQL());
+  const second = row(db, "o/r#landed");
+  assertEquals(second, first);
+  db.close();
+});

package/app/prTrackingReadModel.test.ts

@@ -0,0 +1,175 @@
+// Issue #959 — the canonical "merged beats terminated" effective-status derivation for a PR.
+//
+// THE DEFECT: `pull_requests__tracking.derived_status` mapped ANY terminated run to `abandoned`
+// without consulting the PR's merge state, so the 23 November PRs that MERGED but whose loops were
+// terminated afterwards (operator cancel, out-of-band merge reconcile, restart cleanup) all read
+// "abandoned". These tests pin the fixed semantics against the REAL derivation SQL
+// (`pullRequestTrackingReadModel`, app/prTrackingReadModel.ts) compiled to an in-memory SQLite VIEW
+// over the SAME canonical `urban_instance_state` projection the framework feeds:
+//
+//   terminated + merged PR          → `merged`     (landed wins over terminated)
+//   terminated + closed-unmerged PR → `abandoned`  (no merged_at → the onTerminated edge)
+//   terminated + open PR            → `abandoned`
+//   live (non-terminated) run       → base `status` passes through
+//
+// and the downstream consequence: conformance/retro count a merged-then-terminated PR as LANDED.
+import { DatabaseSync } from "node:sqlite";
+import { test } from "node:test";
+import { registerCanonicalProjections, readModelRegistry } from "@nanobpm/urban";
+import { assert, assertEquals } from "#test-assert";
+import {
+  pullRequestTrackingReadModel,
+  registerPullRequestTrackingReadModel,
+} from "./prTrackingReadModel.ts";
+
+// The projection NAME→physical-table mapping the VIEW's `EXISTS` resolves through.
+registerCanonicalProjections();
+
+/** A minimal in-memory DB: the real `pull_requests` base columns the derivation reads (`status`,
+ *  `process_key`, `merged_at`), the canonical `_urban_instance_state` projection, and the
+ *  app-owned tracking VIEW compiled from the ONE declaration. */
+function viewDb(): DatabaseSync {
+  const db = new DatabaseSync(":memory:");
+  db.exec(
+    `CREATE TABLE pull_requests (pr_key TEXT PRIMARY KEY, status TEXT, process_key TEXT, merged_at TEXT);
+     CREATE TABLE merges (id INTEGER PRIMARY KEY, pr_key TEXT, outcome TEXT, method TEXT, detail TEXT, at TEXT);
+     CREATE TABLE _urban_instance_state (process_instance_key TEXT PRIMARY KEY, state TEXT, waiting_on_human INTEGER NOT NULL DEFAULT 0, updated_at TEXT);`,
+  );
+  db.exec(pullRequestTrackingReadModel.viewDdl());
+  return db;
+}
+
+function addPr(
+  db: DatabaseSync,
+  prKey: string,
+  opts: { status: string; processKey: string | null; mergedAt: string | null },
+): void {
+  db.prepare("INSERT INTO pull_requests (pr_key, status, process_key, merged_at) VALUES (?, ?, ?, ?)").run(
+    prKey,
+    opts.status,
+    opts.processKey,
+    opts.mergedAt,
+  );
+}
+
+function terminate(db: DatabaseSync, processKey: string): void {
+  db.prepare(
+    "INSERT INTO _urban_instance_state (process_instance_key, state, waiting_on_human, updated_at) VALUES (?, 'TERMINATED', 0, 't')",
+  ).run(processKey);
+}
+
+function derivedStatus(db: DatabaseSync, prKey: string): string {
+  const r = db.prepare("SELECT derived_status FROM pull_requests__tracking WHERE pr_key = ?").get(prKey) as {
+    derived_status: string;
+  };
+  return r.derived_status;
+}
+
+test("terminated instance + merged PR (merged_at set) derives `merged`, not `abandoned`", () => {
+  const db = viewDb();
+  // The #959 case: the loop was terminated AFTER the PR landed; base status frozen at its transient.
+  addPr(db, "o/r#merged", { status: "converging", processKey: "514213", mergedAt: "2026-11-01T00:00:00Z" });
+  terminate(db, "514213");
+  assertEquals(derivedStatus(db, "o/r#merged"), "merged");
+  db.close();
+});
+
+test("terminated instance + closed-unmerged PR (no merged_at) derives `abandoned`", () => {
+  const db = viewDb();
+  addPr(db, "o/r#closed", { status: "converging", processKey: "222", mergedAt: null });
+  terminate(db, "222");
+  assertEquals(derivedStatus(db, "o/r#closed"), "abandoned");
+  db.close();
+});
+
+test("terminated instance + open PR (no merged_at) derives `abandoned`", () => {
+  const db = viewDb();
+  addPr(db, "o/r#open", { status: "waiting_review", processKey: "333", mergedAt: null });
+  terminate(db, "333");
+  assertEquals(derivedStatus(db, "o/r#open"), "abandoned");
+  db.close();
+});
+
+test("a live (non-terminated) in-flight run passes its base status through unchanged", () => {
+  const db = viewDb();
+  addPr(db, "o/r#live", { status: "converging", processKey: "444", mergedAt: null });
+  db.prepare(
+    "INSERT INTO _urban_instance_state (process_instance_key, state, waiting_on_human, updated_at) VALUES ('444', 'ACTIVE', 0, 't')",
+  ).run();
+  assertEquals(derivedStatus(db, "o/r#live"), "converging");
+  db.close();
+});
+
+test("a merged PR whose instance COMPLETED normally (no terminated edge) reads base `merged`", () => {
+  const db = viewDb();
+  addPr(db, "o/r#done", { status: "merged", processKey: "555", mergedAt: "2026-11-01T00:00:00Z" });
+  db.prepare(
+    "INSERT INTO _urban_instance_state (process_instance_key, state, waiting_on_human, updated_at) VALUES ('555', 'COMPLETED', 0, 't')",
+  ).run();
+  assertEquals(derivedStatus(db, "o/r#done"), "merged");
+  db.close();
+});
+
+test("a landed PR with no instance-state row (null process_key) still derives merged off merged_at", () => {
+  const db = viewDb();
+  // merged_at set but the instance row is gone/null: the merged WHEN keys on merged_at, not the join.
+  addPr(db, "o/r#nullkey", { status: "converging", processKey: null, mergedAt: "2026-11-01T00:00:00Z" });
+  assertEquals(derivedStatus(db, "o/r#nullkey"), "merged");
+  db.close();
+});
+
+test("a landed PR whose instance-state row was pruned still derives merged off merged_at", () => {
+  const db = viewDb();
+  addPr(db, "o/r#pruned", { status: "waiting_merge", processKey: "777", mergedAt: "2026-11-01T00:00:00Z" });
+  assertEquals(derivedStatus(db, "o/r#pruned"), "merged");
+  db.close();
+});
+
+test("a run terminated between pr.merge's audit and pr.mark-merged (merged_at NULL) derives merged", () => {
+  const db = viewDb();
+  addPr(db, "o/r#gap", { status: "merging", processKey: "888", mergedAt: null });
+  db.prepare("INSERT INTO merges (pr_key, outcome, method, detail, at) VALUES ('o/r#gap', 'merged', 'squash', '', 't')").run();
+  terminate(db, "888");
+  assertEquals(derivedStatus(db, "o/r#gap"), "merged");
+  db.close();
+});
+
+test("a non-merged audit outcome does not fold a terminated run to merged", () => {
+  const db = viewDb();
+  addPr(db, "o/r#rc", { status: "merging", processKey: "889", mergedAt: null });
+  db.prepare("INSERT INTO merges (pr_key, outcome, method, detail, at) VALUES ('o/r#rc', 'reconverge', 'x', '', 't')").run();
+  terminate(db, "889");
+  assertEquals(derivedStatus(db, "o/r#rc"), "abandoned");
+  db.close();
+});
+
+test("owner_terminated exposes termination separately: set for a terminated merged PR, NULL for a live one", () => {
+  const db = viewDb();
+  addPr(db, "o/r#mt", { status: "merged", processKey: "901", mergedAt: "t" });
+  terminate(db, "901");
+  addPr(db, "o/r#ml", { status: "merged", processKey: "902", mergedAt: "t" });
+  const get = (k: string) =>
+    (db.prepare("SELECT derived_status, owner_terminated FROM pull_requests__tracking WHERE pr_key = ?").get(k) as {
+      derived_status: string;
+      owner_terminated: number | null;
+    });
+  assertEquals(get("o/r#mt").derived_status, "merged");
+  assertEquals(get("o/r#mt").owner_terminated, 1);
+  assertEquals(get("o/r#ml").owner_terminated, null);
+  db.close();
+});
+
+// The whole fix hinges on the app-owned model claiming the EXACT view name urban's provisioner would
+// otherwise manage, so the framework defers to it. Pin that contract: the model is named
+// `pull_requests__tracking`, registers into the process-wide registry (idempotently), and the
+// registration is what `main.ts` invokes before `runFromEnv`.
+test("the app-owned model is named pull_requests__tracking and registers idempotently", () => {
+  assertEquals(pullRequestTrackingReadModel.decl.name, "pull_requests__tracking");
+  assertEquals(pullRequestTrackingReadModel.decl.baseTable, "pull_requests");
+  registerPullRequestTrackingReadModel();
+  const registered = readModelRegistry.get("pull_requests__tracking");
+  assert(registered, "the model must be registered so the framework defers to it");
+  assertEquals(registered.decl.name, "pull_requests__tracking");
+  // Idempotent: re-registering the identical definition is a no-op (never throws).
+  registerPullRequestTrackingReadModel();
+});

package/app/prTrackingReadModel.ts

@@ -0,0 +1,152 @@
+// nano-workforce — the ONE canonical "what is this PR's effective status" derivation (issue #959).
+//
+// THE DEFECT. `derived_status` came from the `instanceTracking` `onTerminated.set` edge, which maps
+// **any** terminated run to `abandoned` without consulting the PR's merge state. But a run is
+// terminated AFTER its PR merged in several legitimate ways — an operator cancels a loop that is
+// redundant after a merge, an out-of-band merge (Mergify / a manual click) is reconciled, a restart
+// or upgrade cleans up. Every one of those was recorded "abandoned", which made the status
+// untrustworthy (an operator can't tell dropped work from shipped work) and skewed retro/conformance
+// stats (`LANDED_PR_STATUSES` excludes `abandoned`, so merged PRs didn't count as landed).
+//
+// THE FIX (the defect class, not the instance). `abandoned` must mean "terminated AND the PR did not
+// merge". When the PR landed — recorded on the base row's `merged_at` (set by `pr.mark-merged` or the
+// out-of-band `retireTerminalReviewWait`) — the effective status is `merged` REGARDLESS of how the
+// instance ended. This module owns that derivation ONCE, as a `defineReadModel` over the SAME
+// canonical `urban_instance_state` projection the framework's tracking view uses, plus the base row's
+// own `merged_at` column.
+//
+// HOW IT SHIPS. The model is named `pull_requests__tracking` — the EXACT managed-VIEW name urban's
+// `instanceTracking` provisioner would otherwise create for the `pull_requests` binding
+// (`instanceTrackingReadModelTarget`). Registering it into the process-wide `readModelRegistry` makes
+// the framework's mount DEFER to this app-owned derivation: `provisionInstanceTrackingViews` refuses
+// to clobber a registered read model of the same name (it logs and skips), and `mountWorkers`
+// (`readModelRegistry.ensureViews`) — which runs BEFORE `mountInstanceTracking` — applies this VIEW.
+// So every reader that already routes through `pull_requests__tracking.derived_status` (the abandon
+// check, conformance, retro, the PR list, the read model) picks up the merge-aware edge with NO
+// per-reader change — the "one canonical derivation, no per-reader logic" the issue asks for.
+//
+// PRECEDENCE (merged > terminated > waiting-human > base). The merged `WHEN` is emitted FIRST so a
+// landed PR reads `merged` even when its instance was terminated; a terminated-unmerged run still
+// reads `abandoned`; a waiting-on-human edge (none for pull_requests today, but kept for parity with
+// the framework's derivation) still applies to a live, unmerged run; otherwise the worker-owned base
+// `status` passes through.
+
+import {
+  and,
+  caseWhen,
+  col,
+  defineReadModel,
+  type Expr,
+  eq,
+  exists,
+  isNotNull,
+  lit,
+  not,
+  or,
+  pcol,
+  type ReadModel,
+  readModelRegistry,
+  when,
+} from "@nanobpm/urban";
+import { trackingBindingFor, trackingTargetFor } from "./instanceTracking.ts";
+
+const TABLE = "pull_requests";
+
+/** The engine-truth terminal lifecycle state the terminal edge keys on (mirrors urban's
+ *  `TERMINATED_STATE`). Duplicated as a literal so this module derives from the public DSL primitives
+ *  (`exists`/`pcol`) without reaching into urban's internals. */
+const TERMINATED = "TERMINATED";
+
+/** `EXISTS(urban_instance_state WHERE process_instance_key = base.<keyField> AND state='TERMINATED')`
+ *  — the SAME terminal edge the framework's tracking derivation uses, keyed off the binding's
+ *  `keyField` (`process_key`) so it can never drift from the reconciler's notion of "which column
+ *  holds the engine instance key". */
+function terminatedEdge(keyField: string): Expr {
+  return exists(
+    "urban_instance_state",
+    and(eq(pcol("process_instance_key"), col(keyField)), eq(pcol("state"), lit(TERMINATED))),
+  );
+}
+
+/** `EXISTS(urban_open_user_tasks WHERE process_instance_key = base.<keyField>)` — the wait-on-human
+ *  edge, kept for parity with the framework's derivation (a binding that adds `onWaitingHuman` later
+ *  still derives it correctly). */
+function waitingHumanEdge(keyField: string): Expr {
+  return exists("urban_open_user_tasks", eq(pcol("process_instance_key"), col(keyField)));
+}
+
+/** The landed signal: the base row's `merged_at` stamp OR a durable `merges.outcome='merged'` audit
+ *  row. `pr.merge` writes the audit BEFORE the separate `pr.mark-merged` task stamps `merged_at`, so a
+ *  run terminated between the two still landed — the audit alone must be sufficient. Neither signal
+ *  depends on a retained instance-state row (a pruned/null `process_key` still reads `merged`). */
+function landedEdge(): Expr {
+  return or(
+    isNotNull(col("merged_at")),
+    exists("merges", and(eq(pcol("pr_key"), col("pr_key")), eq(pcol("outcome"), lit("merged")))),
+  );
+}
+
+/** The merge-aware effective-status derivation for the `pull_requests` binding:
+ *
+ *   CASE
+ *     WHEN <merged_at set OR merged audit row>         THEN 'merged'      -- landed wins, however the run ended
+ *     WHEN <terminated>                                THEN <onTerminated> -- terminated-unmerged = abandoned
+ *     WHEN <waiting-on-human> AND NOT <terminated>     THEN <onWaitingHuman>
+ *     ELSE base.<statusField>                          -- the worker-owned transient
+ *   END
+ *
+ * The merged `WHEN` precedes the terminated one so a landed PR is `merged` no matter how its run
+ * ended; the terminated-unmerged branch preserves the manifest's `onTerminated.set.status` value
+ * (`abandoned`) rather than hard-coding it, so the manifest stays the source of truth for the
+ * not-landed terminal. */
+export function derivePrEffectiveStatusExpr(): Expr {
+  const binding = trackingBindingFor(TABLE);
+  const statusField = binding.statusField ?? "status";
+  const keyField = binding.keyField;
+  const terminated = terminatedEdge(keyField);
+
+  const whens = [
+    // Landed beats terminated: a merged PR is `merged` even when its loop was terminated afterwards.
+    when(landedEdge(), lit("merged")),
+  ];
+  const terminalStatus = binding.onTerminated?.set?.[statusField];
+  if (typeof terminalStatus === "string") {
+    whens.push(when(terminated, lit(terminalStatus)));
+  }
+  const waitingStatus = binding.onWaitingHuman?.set?.[statusField];
+  if (typeof waitingStatus === "string") {
+    whens.push(when(and(waitingHumanEdge(keyField), not(terminated)), lit(waitingStatus)));
+  }
+  return caseWhen(whens, col(statusField));
+}
+
+/** The derived column exposing "this PR's owning run was terminated" SEPARATELY from the effective
+ *  status. `derived_status` deliberately reports a landed PR as `merged` even when its run was
+ *  terminated, so it can no longer carry the cancellation signal on its own — the abort protocol
+ *  (`abandonStatusForToken`) reads THIS column too, so terminating a redundant post-merge round still
+ *  tells its agent to stop. `1` when terminated, otherwise `NULL`. */
+export const OWNER_TERMINATED_COLUMN = "owner_terminated";
+
+/** `CASE WHEN <terminated> THEN 1 END` over the same terminal edge `derived_status` uses. */
+export function deriveOwnerTerminatedExpr(): Expr {
+  return caseWhen([when(terminatedEdge(trackingBindingFor(TABLE).keyField), lit(1))], lit(null));
+}
+
+/** The app-owned `pull_requests__tracking` read model. `selectBaseColumns: true` (the default) so the
+ *  VIEW re-exports `pull_requests.*` plus the derived `derived_status` — byte-compatible with the
+ *  framework's own tracking VIEW shape, so every existing reader keeps working unchanged. */
+export const pullRequestTrackingReadModel: ReadModel = defineReadModel({
+  name: trackingTargetFor(TABLE).view,
+  baseTable: TABLE,
+  derive: {
+    [trackingTargetFor(TABLE).statusColumn]: derivePrEffectiveStatusExpr(),
+    [OWNER_TERMINATED_COLUMN]: deriveOwnerTerminatedExpr(),
+  },
+});
+
+/** Register the merge-aware tracking VIEW into the process-wide `readModelRegistry` so the framework
+ *  provisions THIS derivation (and defers its own). Call ONCE at boot, BEFORE `runFromEnv` mounts
+ *  workers/instance-tracking. Idempotent: re-registering the identical definition is a no-op. */
+export function registerPullRequestTrackingReadModel(): void {
+  readModelRegistry.register(pullRequestTrackingReadModel);
+}

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.1",
-  "gitSha": "e2c4e966b566ce8b4bdc19e84bceb130909a981c",
-  "gitTag": "v0.210.1",
-  "builtAt": "2026-11-12T12:00:58.232Z"
+  "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.1",
+  "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/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(