@nanobpm/nano-workforce 0.208.2 → 0.208.3

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.208.3](https://github.com/nanobpm/nano-workforce/compare/v0.208.2...v0.208.3) (2026-11-11)
+
+### Bug Fixes
+
+* **merge:** never retire a merge loop into nothing on the convergence hand-off ([#944](https://github.com/nanobpm/nano-workforce/issues/944)) ([ff42e2a](https://github.com/nanobpm/nano-workforce/commit/ff42e2a6fa77fd780949822adf3d4f2b9caefc38)), closes [nanobpm/nano-bpm#1452](https://github.com/nanobpm/nano-bpm/issues/1452) [#939](https://github.com/nanobpm/nano-workforce/issues/939) [#943](https://github.com/nanobpm/nano-workforce/issues/943)
+
 ## [0.208.2](https://github.com/nanobpm/nano-workforce/compare/v0.208.1...v0.208.2) (2026-11-10)
 
 ### Bug Fixes

package/app/loopTermination.test.ts

@@ -0,0 +1,412 @@
+// Issue #943 — defect-class guard: a convergence/merge loop must never end without an outcome.
+// A merge loop (nanobpm/nano-bpm#1452, instance 607414) was terminated in-app by the waiting-merge →
+// convergence hand-off with NO successor, NO escalation and NO recorded reason, and silently dropped
+// off `/status`. This suite guards the whole class:
+//   1. every `cancelInstance(` call site in the app source is ENUMERATED and classified — a new site
+//      fails here until it is routed through `terminatePrLoop` (which records a reason naming the
+//      successor/outcome) or justified in the registry below;
+//   2. `terminatePrLoop` records the reason BEFORE cancelling;
+//   3. an orphaned PR (loop ended, base row still in flight, no reason, not merged) is VISIBLE in
+//      `/status` as `orphaned` instead of being filtered out.
+import { test } from "node:test";
+import { readdir, readFile } from "node:fs/promises";
+import { join, relative } from "node:path";
+import { assert, assertEquals } from "#test-assert";
+import type { DataLayer } from "@nanobpm/urban";
+import {
+  activePrs,
+  handoffWaitingMergeToConvergence,
+  isOrphanedPr,
+  ORPHANED_PR_STATUS,
+  recordOperatorCancelProvenance,
+  retireHandedOffMergeLoop,
+  retryPendingRetirements,
+  terminatePrLoop,
+} from "./service.ts";
+
+const ROOT = join(import.meta.dirname, "..");
+
+/** Every sanctioned `cancelInstance(` call site, keyed `file` → count, with its outcome contract. */
+const SANCTIONED_CANCEL_SITES: Record<string, { count: number; outcome: string }> = {
+  // (a) `terminatePrLoop` — THE canonical PR-loop door: stamps `termination_reason` (naming the
+  //     successor instance or the terminal GitHub state) before cancelling. Callers: the merge →
+  //     convergence hand-off (successor started FIRST) and the terminal review-wait retire (row
+  //     settled merged/abandoned).
+  // (b) `submitPr` rollback — cancels the instance THIS submit just created and never published as
+  //     owner; the prior row (owner key + status) is restored, so the prior owner remains the outcome.
+  "app/service.ts": { count: 2, outcome: "terminatePrLoop door + submitPr rollback (prior owner restored)" },
+  // Delivery-graph reconcile-before-relaunch: not a PR loop; cancels a duplicate original under the
+  // stale-claim CAS lease so the run is relaunched (the successor) at-most-once.
+  "app/deliveryGraphRun.ts": { count: 1, outcome: "duplicate original retired; relaunch is the successor" },
+};
+
+async function sourceFiles(dir: string): Promise<string[]> {
+  const out: string[] = [];
+  for (const e of await readdir(dir, { withFileTypes: true })) {
+    const p = join(dir, e.name);
+    if (e.isDirectory()) {
+      if (e.name === "node_modules" || e.name.startsWith(".")) continue;
+      out.push(...(await sourceFiles(p)));
+    } else if (e.name.endsWith(".ts") && !e.name.endsWith(".test.ts") && !e.name.endsWith(".e2e.ts") && !e.name.endsWith(".d.ts")) {
+      out.push(p);
+    }
+  }
+  return out;
+}
+
+test("#943 guard: every cancelInstance call site that can end a loop is enumerated and records an outcome", async () => {
+  const found: Record<string, number> = {};
+  for (const dir of ["app", "workers", "actions", "operations"]) {
+    let files: string[] = [];
+    try {
+      files = await sourceFiles(join(ROOT, dir));
+    } catch {
+      continue; // directory absent
+    }
+    for (const f of files) {
+      const n = ((await readFile(f, "utf8")).match(/\.cancelInstance\(/g) ?? []).length;
+      if (n > 0) found[relative(ROOT, f)] = n;
+    }
+  }
+  const expected = Object.fromEntries(Object.entries(SANCTIONED_CANCEL_SITES).map(([k, v]) => [k, v.count]));
+  assertEquals(
+    found,
+    expected,
+    "a cancelInstance call site was added/removed: route a PR-loop cancel through terminatePrLoop (reason + successor/outcome), then update SANCTIONED_CANCEL_SITES",
+  );
+});
+
+function memData(rows: any[], tracking: any[]) {
+  const stores: Record<string, any[]> = { pull_requests: rows, pull_requests__tracking: tracking, user_tasks: [] };
+  const tbl = (name: string, pk: string) => {
+    const r = (stores[name] ??= []);
+    return {
+      all: async () => r.slice(),
+      get: async (id: any) => r.find((x) => x[pk] === id),
+      find: async (w: any = {}) => r.filter((x) => Object.entries(w).every(([k, v]) => x[k] === v)),
+      update: async (id: any, patch: any) => {
+        const x = r.find((y) => y[pk] === id);
+        if (x) Object.assign(x, patch);
+      },
+    };
+  };
+  const data = { table: (n: string, pk = "id") => tbl(n, pk) } as unknown as DataLayer;
+  return { data, stores };
+}
+
+test("#943 terminatePrLoop records the reason BEFORE the engine cancel", async () => {
+  const { data, stores } = memData([{ pr_key: "o/r#1", process_key: "k1", termination_reason: null }], []);
+  const seen: (string | null)[] = [];
+  const engine = {
+    cancelInstance: async () => {
+      seen.push(stores.pull_requests[0].termination_reason);
+    },
+  };
+  await terminatePrLoop(data, engine as never, "o/r#1", "k1", "handed back -> successor k2", false);
+  assertEquals(seen, ["handed back -> successor k2"]);
+  assertEquals(stores.pull_requests[0].termination_process_key, "k1", "the reason is bound to the cancelled instance");
+});
+
+test("#943/PR#944 terminatePrLoop never stamps a predecessor's reason onto a successor-owned row", async () => {
+  const { data, stores } = memData([{ pr_key: "o/r#1", process_key: "succ", termination_reason: null }], []);
+  const cancelled: string[] = [];
+  const engine = { cancelInstance: async (a: { processInstanceKey: string }) => void cancelled.push(a.processInstanceKey) };
+  await terminatePrLoop(data, engine as never, "o/r#1", "pred", "handed back -> successor succ", true);
+  assertEquals(cancelled, ["pred"], "the predecessor is still retired");
+  assertEquals(stores.pull_requests[0].termination_reason, null, "the successor's row carries no predecessor provenance");
+});
+
+test("#943/PR#944 terminatePrLoop still cancels when the provenance write fails", async () => {
+  const data = {
+    table: () => ({
+      get: async () => ({ pr_key: "o/r#1", process_key: "k1" }),
+      update: async () => {
+        throw new Error("db down");
+      },
+    }),
+  } as unknown as DataLayer;
+  const cancelled: string[] = [];
+  const engine = { cancelInstance: async (a: { processInstanceKey: string }) => void cancelled.push(a.processInstanceKey) };
+  await terminatePrLoop(data, engine as never, "o/r#1", "k1", "r", true);
+  assertEquals(cancelled, ["k1"]);
+});
+
+test("#943/PR#944 retireHandedOffMergeLoop retries the CAPTURED merge key and never touches the successor row's stage", async () => {
+  const { data, stores } = memData([{ pr_key: "o/r#1", process_key: "succ", status: "waiting_review" }], []);
+  let calls = 0;
+  const engine = {
+    cancelInstance: async (a: { processInstanceKey: string }) => {
+      calls++;
+      assertEquals(a.processInstanceKey, "merge-1");
+      if (calls === 1) throw new Error("transient");
+    },
+  };
+  assert(await retireHandedOffMergeLoop(data, engine as never, "o/r#1", "merge-1", "succ", "test"));
+  assertEquals(calls, 2);
+  assertEquals(stores.pull_requests[0].status, "waiting_review");
+  assertEquals(stores.pull_requests[0].process_key, "succ");
+  const failing = { cancelInstance: async () => Promise.reject(new Error("down")) };
+  assert(!(await retireHandedOffMergeLoop(data, failing as never, "o/r#1", "merge-1", "succ", "test")));
+  assertEquals(stores.pull_requests[0].status, "waiting_review", "a persistent retire failure never demotes the successor");
+});
+
+test("#943/PR#944 recordOperatorCancelProvenance binds an operator cancel to the owning instance", async () => {
+  const { data, stores } = memData([{ pr_key: "o/r#1", process_key: "k1" }, { pr_key: "o/r#2", process_key: "k2" }], []);
+  await recordOperatorCancelProvenance(data, "k1", "/actions/cancel-pr");
+  assertEquals(stores.pull_requests[0].termination_reason, "operator cancel (/actions/cancel-pr)");
+  assertEquals(stores.pull_requests[0].termination_process_key, "k1");
+  assertEquals(stores.pull_requests[1].termination_reason, undefined);
+});
+
+test("#943/PR#944 the page Cancel button routes through the provenance-recording door, not the built-in route", async () => {
+  const page = await readFile(join(ROOT, "pages/home.page.json"), "utf8");
+  assert(!page.includes('"/app/actions/cancel"'), "the built-in /app/actions/cancel bypasses termination provenance");
+  assert(page.includes('"/app/api/actions/cancel-pr"'));
+});
+
+test("#943 terminatePrLoop: strict rethrows a failed cancel; lenient only logs", async () => {
+  const { data } = memData([{ pr_key: "o/r#1" }], []);
+  const engine = {
+    cancelInstance: async () => {
+      throw new Error("boom");
+    },
+  };
+  let threw = false;
+  try {
+    await terminatePrLoop(data, engine as never, "o/r#1", "k1", "r", true);
+  } catch {
+    threw = true;
+  }
+  assert(threw, "strict rethrows");
+  await terminatePrLoop(data, engine as never, "o/r#1", "k1", "r", false);
+});
+
+const base = {
+  repo: "o/r",
+  url: "u",
+  title: null,
+  current_round: 1,
+  waiting_since: null,
+  last_review_id: null,
+  outcome: null,
+  created_at: "t",
+  updated_at: "t",
+  converged_at: "t",
+  merged_at: null,
+  active_worker: null,
+  lease_until: null,
+  incident_key: null,
+  incident_type: null,
+  incident_message: null,
+  incident_since: null,
+  auto_resolve_escalations: 0,
+  termination_reason: null,
+};
+
+test("#943 isOrphanedPr: loop ended in-app with the row still in flight and no reason → orphaned", () => {
+  assert(isOrphanedPr({ status: "waiting_review", derived_status: "abandoned", termination_reason: null, merged_at: null }));
+  assert(
+    !isOrphanedPr({ status: "waiting_review", derived_status: "abandoned", process_key: "k", termination_reason: "handed back", termination_process_key: "k", merged_at: null }),
+    "a reason recorded for the current owner is not an orphan",
+  );
+  assert(
+    isOrphanedPr({ status: "waiting_review", derived_status: "abandoned", process_key: "succ", termination_reason: "handed back", termination_process_key: "pred", merged_at: null }),
+    "a predecessor's reason never masks an orphaned successor (PR #944 review)",
+  );
+  assert(
+    isOrphanedPr({ status: "waiting_review", derived_status: "abandoned", process_key: "k", termination_reason: "legacy", merged_at: null }),
+    "an unbound reason explains nothing",
+  );
+  assert(!isOrphanedPr({ status: "abandoned", derived_status: "abandoned", termination_reason: null, merged_at: null }), "a settled row (human cancel/close) is not an orphan");
+  assert(!isOrphanedPr({ status: "waiting_merge", derived_status: "waiting_merge", termination_reason: null, merged_at: null }), "a live loop is not an orphan");
+  assert(!isOrphanedPr({ status: "merging", derived_status: "abandoned", termination_reason: null, merged_at: "t" }), "a merged PR is not an orphan");
+});
+
+test("#943 /status surfaces an orphaned PR instead of filtering it out", async () => {
+  const orphan = { ...base, pr_key: "o/r#1452", number: 1452, status: "waiting_review", process_key: "607414" };
+  const live = { ...base, pr_key: "o/r#2", number: 2, status: "waiting_merge", process_key: "9" };
+  const { data } = memData(
+    [orphan, live],
+    [
+      { ...orphan, derived_status: "abandoned" },
+      { ...live, derived_status: "waiting_merge" },
+    ],
+  );
+  const rows = await activePrs(data);
+  const o = rows.find((r) => r.prKey === "o/r#1452");
+  assert(o, "the orphaned PR is listed in /status");
+  assertEquals(o?.status, ORPHANED_PR_STATUS);
+  assertEquals(o?.terminationReason, null);
+  assertEquals(rows.find((r) => r.prKey === "o/r#2")?.status, "waiting_merge");
+});
+
+test("#943/PR#944 a persistently failed retirement is persisted and retried by later poll passes", async () => {
+  const { data, stores } = memData([{ pr_key: "o/r#1", process_key: "succ", status: "waiting_review" }], []);
+  const failing = { cancelInstance: async () => Promise.reject(new Error("down")) };
+  assert(!(await retireHandedOffMergeLoop(data, failing as never, "o/r#1", "merge-1", "succ", "test")));
+  assertEquals(stores.pull_requests[0].retire_pending_key, "merge-1", "the predecessor key is never dropped");
+  await retryPendingRetirements(data, failing as never);
+  assertEquals(stores.pull_requests[0].retire_pending_key, "merge-1");
+  const cancelled: string[] = [];
+  const ok = { cancelInstance: async (a: { processInstanceKey: string }) => void cancelled.push(a.processInstanceKey) };
+  await retryPendingRetirements(data, ok as never);
+  assertEquals(cancelled, ["merge-1"]);
+  assertEquals(stores.pull_requests[0].retire_pending_key, null);
+  assertEquals(stores.pull_requests[0].process_key, "succ");
+  assertEquals(stores.pull_requests[0].status, "waiting_review");
+});
+
+test("PR#944 a pending retirement whose key still OWNS the row (unpublished successor) is never retired", async () => {
+  const { data, stores } = memData([{ pr_key: "o/r#1", process_key: "merge-1", status: "waiting_review", retire_pending_key: "merge-1" }], []);
+  const cancelled: string[] = [];
+  const ok = { cancelInstance: async (a: { processInstanceKey: string }) => void cancelled.push(a.processInstanceKey) };
+  await retryPendingRetirements(data, ok as never);
+  assertEquals(cancelled, [], "a live owning merge loop is never retired into nothing");
+  assertEquals(stores.pull_requests[0].retire_pending_key, "merge-1");
+});
+
+test("PR#944 round 5: a KEYLESS owner row (unpublished handoff) is never retired into nothing — it stays recoverable", async () => {
+  // `submitPr` can publish a null `process_key` (phantom row, #704/#497); if the app stops before the
+  // handoff rollback lands (or the rollback write fails), the pending predecessor key survives with NO
+  // successor. Cancelling the still-live merge loop here would recreate the ownerless termination this
+  // PR prevents — the retirement must be deferred, leaving the NULL-key row for the dead-owner guard in
+  // `pollMerges` to re-drive the handoff.
+  const { data, stores } = memData([{ pr_key: "o/r#1", process_key: null, status: "waiting_review", retire_pending_key: "merge-1" }], []);
+  const cancelled: string[] = [];
+  const ok = { cancelInstance: async (a: { processInstanceKey: string }) => void cancelled.push(a.processInstanceKey) };
+  await retryPendingRetirements(data, ok as never);
+  assertEquals(cancelled, [], "no live successor → the predecessor is never retired");
+  assertEquals(stores.pull_requests[0].retire_pending_key, "merge-1", "the pending marker survives for recovery");
+  // Once a successor IS published, the same pass retires the predecessor against it.
+  stores.pull_requests[0].process_key = "succ";
+  await retryPendingRetirements(data, ok as never);
+  assertEquals(cancelled, ["merge-1"]);
+  assertEquals(stores.pull_requests[0].retire_pending_key, null);
+});
+
+// ── PR #944 round-6 review: restart-recovery of a pending handoff ───────────────────────────────
+// A restart between the handoff's staging write and the successor publication strands the row in a
+// shape NEITHER poll pass recovers: the `waiting_review`/`converging` stages sit outside the
+// `waiting_merge` recovery scan, and the one-pending-retirement guard rejected a KEYLESS owner row
+// outright, so even a keyless `waiting_merge` row could never re-drive its handoff. The recovery
+// must be fenced to the LIVE merge stages (never demote a successor-owned `converging` row) and the
+// pending-predecessor guard must admit a keyless owner row (there IS no live owner to protect).
+
+/** In-memory `data` double with the exact tables `submitPr` touches on a phantom (null-key) publish. */
+function handoffData(rows: any[], tracking: any[]) {
+  const stores: Record<string, any[]> = {
+    pull_requests: rows,
+    pull_requests__tracking: tracking,
+    escalations: [],
+    pr_dependencies: [],
+    worker_durable_resume: [],
+    world_checkpoints: [],
+    world_effects: [],
+  };
+  const tbl = (name: string, pk: string) => {
+    const r = (stores[name] ??= []);
+    return {
+      all: async () => r.slice(),
+      get: async (id: any) => r.find((x) => x[pk] === id),
+      find: async (w: any = {}) => r.filter((x) => Object.entries(w).every(([k, v]) => x[k] === v)),
+      findOne: async (w: any = {}) => r.find((x) => Object.entries(w).every(([k, v]) => x[k] === v)),
+      insert: async (row: any) => void r.push(row),
+      update: async (id: any, patch: any) => {
+        const x = r.find((y) => y[pk] === id);
+        if (x) Object.assign(x, patch);
+      },
+      delete: async (id: any) => {
+        const i = r.findIndex((y) => y[pk] === id);
+        if (i >= 0) r.splice(i, 1);
+      },
+    };
+  };
+  const data = {
+    table: (n: string, pk = "id") => tbl(n, pk),
+    open: () => ({ exec: async () => {} }),
+  } as unknown as DataLayer;
+  return { data, stores };
+}
+
+/** Run a handoff with the GitHub transport DISABLED (PR #944 round-7 review): forcing the `token`
+ * transport with no `GITHUB_TOKEN` makes `submitPr`'s best-effort `fetchPrMeta` return `null`
+ * WITHOUT any `gh` subprocess or network fetch — the test never depends on ambient credentials,
+ * the network, or an unroutable host failing fast. The engine double publishes a NULL key (the
+ * phantom-row path, #704/#497), so `submitPr` starts no successor and the handoff must roll back. */
+async function runPhantomHandoff(row: any, tracking: any[]) {
+  const prevTransport = process.env["NANO_PR_GITHUB_TRANSPORT"];
+  const prevToken = process.env["GITHUB_TOKEN"];
+  process.env["NANO_PR_GITHUB_TRANSPORT"] = "token";
+  delete process.env["GITHUB_TOKEN"];
+  try {
+    const { data, stores } = handoffData([row], tracking);
+    const engine = {
+      createInstance: async () => ({ processInstanceKey: null }),
+      cancelInstance: async () => {},
+    };
+    await handoffWaitingMergeToConvergence(data, engine as never, stores.pull_requests[0], "test");
+    return stores;
+  } finally {
+    if (prevTransport === undefined) delete process.env["NANO_PR_GITHUB_TRANSPORT"];
+    else process.env["NANO_PR_GITHUB_TRANSPORT"] = prevTransport;
+    if (prevToken === undefined) delete process.env["GITHUB_TOKEN"];
+    else process.env["GITHUB_TOKEN"] = prevToken;
+  }
+}
+
+test("PR#944 round 6: a restart-stranded KEYLESS waiting_merge row re-drives its handoff past the pending-predecessor guard", async () => {
+  const stores = await runPhantomHandoff(
+    { pr_key: "o/r#1", repo: "o/r", number: 1, url: "u", process_key: null, status: "waiting_merge", retire_pending_key: "merge-1" },
+    [{ pr_key: "o/r#1", derived_status: "waiting_merge" }],
+  );
+  assertEquals(stores.pull_requests[0].status, "waiting_merge", "the failed handoff restores the live merge stage");
+  assertEquals(stores.pull_requests[0].process_key, null, "a keyless row stays keyless (the durable unfinished-handoff marker)");
+  assertEquals(stores.pull_requests[0].retire_pending_key, "merge-1", "the pending predecessor survives the retry for later passes");
+});
+
+test("PR#944 round 6: a restart-stranded waiting_review row still OWNED by its live merge loop is left for the retirement-retry pass, not demoted", async () => {
+  // The staging write already flipped the row to `waiting_review` and the owner is still the merge
+  // loop: this is a MID-HANDOFF shape, not a stranded one. The stage fence correctly skips it —
+  // re-staging would strand it outside `waiting_merge`'s scan. `retryPendingRetirements` recovers it
+  // once the successor publishes (the round-5 test covers that retirement); the fence must NOT
+  // "recover" it by demoting the stage back.
+  const stores = await runPhantomHandoff(
+    { pr_key: "o/r#1", repo: "o/r", number: 1, url: "u", process_key: "merge-1", status: "waiting_review", retire_pending_key: "merge-1" },
+    [{ pr_key: "o/r#1", derived_status: "waiting_merge" }],
+  );
+  assertEquals(stores.pull_requests[0].status, "waiting_review", "a mid-handoff row is never demoted back to waiting_merge");
+  assertEquals(stores.pull_requests[0].process_key, "merge-1", "the merge loop keeps owning the row until the successor publishes");
+  assertEquals(stores.pull_requests[0].retire_pending_key, "merge-1", "the pending marker survives for retryPendingRetirements");
+});
+
+test("PR#944 round 6: a restart-stranded KEYLESS converging row re-drives its handoff past the pending-predecessor guard", async () => {
+  // The reviewer's second stranded shape: the app stopped after the phantom (null-key) publish but
+  // before the rollback, leaving the row keyless at `converging` with the pending predecessor. The
+  // dead-owner guard in `pollMerges` re-drives the handoff from this shape; the pending-predecessor
+  // guard must admit it (there is no live owner to protect), and the rollback restores the live
+  // merge stage so the next pass retries cleanly.
+  const stores = await runPhantomHandoff(
+    { pr_key: "o/r#1", repo: "o/r", number: 1, url: "u", process_key: null, status: "converging", retire_pending_key: "merge-1" },
+    [{ pr_key: "o/r#1", derived_status: "converging" }],
+  );
+  assertEquals(stores.pull_requests[0].status, "waiting_merge", "the failed recovery handoff restores the live merge stage");
+  assertEquals(stores.pull_requests[0].process_key, null, "a keyless row stays keyless (the durable unfinished-handoff marker)");
+  assertEquals(stores.pull_requests[0].retire_pending_key, "merge-1", "the pending predecessor survives the retry for later passes");
+});
+
+test("PR#944 round 6: a successor-owned converging row is NEVER demoted by a redelivered handoff", async () => {
+  const { data, stores } = handoffData(
+    [{ pr_key: "o/r#1", repo: "o/r", number: 1, url: "u", process_key: "succ", status: "converging", retire_pending_key: "merge-1" }],
+    [{ pr_key: "o/r#1", derived_status: "converging" }],
+  );
+  const engine = {
+    createInstance: async () => {
+      throw new Error("must not be called — the successor owns the row");
+    },
+    cancelInstance: async () => {},
+  };
+  await handoffWaitingMergeToConvergence(data, engine as never, stores.pull_requests[0], "test");
+  assertEquals(stores.pull_requests[0].status, "converging");
+  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");
+});

package/app/mcpExclusions.test.ts

@@ -34,7 +34,7 @@ function projectedOperations() {
 // dismiss) whose approval is a human click in the cockpit (ADR 0005 Decision 7), plus the
 // incident-retry remediation door (issue #931) — the human unstick action on an incident-parked
 // run. These — and ONLY these — must be excluded from the projected MCP tool surface.
-const EXPECTED_EXCLUDED = ["stageDeliveryGraph", "dispatchDeliveryGraph", "dismissProposal", "retryIncident"];
+const EXPECTED_EXCLUDED = ["stageDeliveryGraph", "dispatchDeliveryGraph", "dismissProposal", "retryIncident", "cancelPrRun"];
 
 // A representative set of agent-facing operations that MUST stay exposed as tools — the drive doors
 // (submit PR / epic / delivery-graph set), the pure compile/preview doors, and the read/orientation

package/app/mergeBlockedThreads.test.ts

@@ -374,10 +374,13 @@ fi
   process.env["NANO_PR_GITHUB_TRANSPORT"] = "gh";
   globalThis.fetch = (() => Promise.resolve(new Response("no fetch in gh mode", { status: 500 }))) as typeof fetch;
   try {
-    // Pass 1: the handoff fails (createInstance throws) AFTER the merge instance is retired.
+    // Pass 1: the handoff fails (createInstance throws). Issue #943: the successor is started BEFORE
+    // the merge instance is retired, so a failed start leaves the merge instance LIVE (never retired
+    // into nothing).
     await pollMerges(data, engine, "tok");
     const rowAfterFail = stores["pull_requests"][0];
-    assertEquals(cancelled, ["merge-1"], "the live merge instance is still retired");
+    assertEquals(cancelled, [], "no successor -> the live merge instance is NOT retired");
+    assertEquals(rowAfterFail.process_key, "merge-1", "the live merge instance still owns the row");
     assertEquals(
       rowAfterFail.status,
       "waiting_merge",
@@ -403,6 +406,63 @@ fi
   assertEquals(instances[0].processDefinitionId, "convergence-loop", "the canonical convergence loop is re-entered on retry");
   assertEquals(row.status, "converging", "the retried handoff completes — the row presents the fresh convergence run");
   assertEquals(row.process_key, "conv-retry-1", "the row is re-pointed at the fresh convergence instance");
+  assertEquals(cancelled, ["merge-1"], "the merge instance is retired only once the successor exists");
+});
+
+test("#943 poller: the convergence handoff never retires the merge loop into NOTHING — the derived tracking edge folds the cancel ASYNCHRONOUSLY (nanobpm/nano-bpm#1452)", async () => {
+  // Production shape: `pull_requests__tracking.derived_status` folds an engine cancel in LATER (the
+  // reconciler edge), not synchronously inside `cancelInstance`. The old cancel-then-submit order
+  // therefore had `submitPr` read the just-cancelled merge key as a LIVE owner, return
+  // `alreadyRunning`, and start nothing — merge loop terminated, no successor, no escalation.
+  const { data, stores } = memData();
+  const { engine, cancelled } = recordingEngine();
+  const instances: any[] = [];
+  (engine as any).createInstance = async (args: any) => {
+    instances.push(args);
+    return { processInstanceKey: "conv-943" };
+  };
+  const mergeRow = { ...waitingMergeRow("o/r#1452", 1452), process_key: "merge-607414" };
+  stores["pull_requests"] = [mergeRow];
+  // The tracking view stays `waiting_merge` across the cancel (async fold), exactly as on merlin.
+  stores["pull_requests__tracking"] = [{ ...mergeRow, derived_status: "waiting_merge" }];
+  const bin = await mkdtemp(join(tmpdir(), "gh-stub-"));
+  const script = `#!/usr/bin/env bash
+set -euo pipefail
+if [[ "$*" == *"pr view"* ]]; then
+  echo '{"state":"OPEN","mergedAt":null,"mergeStateStatus":"BLOCKED","statusCheckRollup":[{"name":"build","status":"COMPLETED","conclusion":"SUCCESS"}],"isDraft":false,"headRefOid":"deadbeef","baseRefName":"main"}'
+elif [[ "$*" == *"graphql"* ]]; then
+  echo '${graphqlThreads(1)}'
+elif [[ "$*" == *"requested_reviewers"* ]]; then
+  exit 0
+else
+  echo "unexpected gh args: $*" >&2
+  exit 1
+fi
+`;
+  await writeFile(join(bin, "gh"), script, { mode: 0o755 });
+  const prevPath = process.env.PATH;
+  const prevFetch = globalThis.fetch;
+  const prevMode = process.env["NANO_PR_GITHUB_TRANSPORT"];
+  process.env.PATH = `${bin}:${prevPath ?? ""}`;
+  process.env["NANO_PR_GITHUB_TRANSPORT"] = "gh";
+  globalThis.fetch = (() => Promise.resolve(new Response("no fetch in gh mode", { status: 500 }))) as typeof fetch;
+  try {
+    await pollMerges(data, engine, "tok");
+  } finally {
+    globalThis.fetch = prevFetch;
+    if (prevPath === undefined) delete process.env.PATH;
+    else process.env.PATH = prevPath;
+    if (prevMode === undefined) delete process.env["NANO_PR_GITHUB_TRANSPORT"];
+    else process.env["NANO_PR_GITHUB_TRANSPORT"] = prevMode;
+    await rm(bin, { recursive: true, force: true });
+  }
+  const row = stores["pull_requests"][0];
+  assertEquals(instances.length, 1, "a successor convergence instance is started");
+  assertEquals(row.process_key, "conv-943", "the row is owned by the successor");
+  assertEquals(cancelled, ["merge-607414"], "the merge loop is retired only after the successor exists");
+  // PR #944 review: the predecessor's cancel reason is bound to the predecessor, never stamped onto
+  // the successor-owned row (it would mask a later orphaning of the successor).
+  assert(row.termination_reason == null, `the successor's row carries no predecessor provenance, got ${row.termination_reason}`);
 });
 
 test("#921/PR#922 poller: an UNFINISHED handoff (dead merge instance) never publishes merge-ready to the cancelled owner — it re-establishes a live convergence owner first (PR #922 review, round 5)", async () => {

package/app/pullRequestReadModel.test.ts

@@ -33,7 +33,7 @@ import {
 const MIG = (name: string) => readFileSync(fileURLToPath(new URL(`../db/migrations/${name}`, import.meta.url)), "utf8");
 const PAGE = (name: string) => JSON.parse(readFileSync(fileURLToPath(new URL(`../pages/${name}`, import.meta.url)), "utf8"));
 
-const READ_MODEL_MIGRATION = "128_pull_requests_read_model_incidents.sql";
+const READ_MODEL_MIGRATION = "131_pull_requests_read_model_termination_reason.sql";
 
 // The real base `pull_requests` columns, in schema order — DERIVED from the migration chain (not a
 // hand-kept list that could silently omit one), used by both the drift guard and the e2e stand-in.

package/app/service.ts

@@ -416,6 +416,21 @@ export interface PullRequest {
   // Opt-in escalation steward (120_escalation_auto_resolutions.sql, issue #889): 1 ⇒ this PR's open
   // escalations are eligible for the steward to auto-resolve (recorded reviewably). Default 0.
   auto_resolve_escalations: number;
+  // Loop-termination provenance (130_pull_requests_termination_reason.sql, issue #943): the reason the
+  // app last cancelled this PR's convergence/merge loop, stamped by {@link terminatePrLoop}. NULL when
+  // the app never cancelled the current run.
+  termination_reason: string | null;
+  // The engine instance `termination_reason` describes (issue #943, PR #944 review): provenance is
+  // bound to the CANCELLED instance, so a predecessor's reason can never explain away the orphaning of
+  // a successor that later owns the row. Honoured only while it equals `process_key`.
+  termination_process_key: string | null;
+  // A handed-off predecessor merge loop whose retirement (engine cancel) has not yet succeeded (PR #944
+  // review). Durable so {@link retryPendingRetirements} re-attempts it on every poll pass instead of
+  // dropping the key after a bounded in-memory retry. NULL when nothing is pending.
+  retire_pending_key?: string | null;
+  // Operator Dismiss stamp (app/acknowledge.ts). Run-scoped: cleared on reopen so a dismissal of a
+  // PRIOR run never hides an orphaning of the current one.
+  acknowledged_at?: string | null;
 }
 
 interface PrDependency {
@@ -963,6 +978,13 @@ async function submitPrCritical(
         // watermark could drop the new run's early rounds from the churn window (or, after the new
         // run passes that number, silently expire). Reset it so the new run's churn clock starts clean.
         churn_escalated_round: null,
+        // Run-scoped termination provenance (issue #943): a prior run's cancel reason must not mask a
+        // later orphaning of THIS run in `/status`.
+        termination_reason: null,
+        termination_process_key: null,
+        // The operator Dismiss is run-scoped too (PR #944 review): a dismissal of the PRIOR run must not
+        // count as acknowledging a later unexplained termination of THIS run.
+        acknowledged_at: null,
         outcome: null,
         converged_at: null,
         merged_at: null,
@@ -1191,6 +1213,9 @@ export interface ActivePr {
   /** The ACTIVE engine incident parking this PR's instance (issue #931), mirrored by the poller's
    * `pollIncidents` pass; null when none. While set, `status` reads `incident`. */
   incident: StatusIncident | null;
+  /** Why the app last cancelled this PR's loop (issue #943), naming the successor/outcome; null when
+   * never. An `orphaned` status means the loop ended with no reason, successor, or escalation. */
+  terminationReason: string | null;
 }
 
 /** Every tracked PR not in a terminal state (converged/abandoned), newest-updated first. Backs
@@ -1218,7 +1243,7 @@ export async function activePrs(
     // `status`/worker-owned transient columns are still surfaced on each row below (the view re-exports
     // `base.*`), and `pull_requests` has no `onWaitingHuman` edge, so for a still-active PR
     // `derived_status === status`.
-    .filter((p) => !TERMINAL_STATUSES.includes(p.derived_status))
+    .filter((p) => !TERMINAL_STATUSES.includes(p.derived_status) || isOrphanedPr(p))
     .sort((a, b) => (a.updated_at < b.updated_at ? 1 : a.updated_at > b.updated_at ? -1 : 0));
   // Derive the STRUCTURED open-escalation pointer from the ONE `user_tasks` read model (issue #666) —
   // the same user-task surface `listEscalations` and the Convergence/Tasks page consume — so `/status`
@@ -1256,13 +1281,14 @@ export async function activePrs(
     // kept reading `converging` for hours while nothing ran. Overlay the derived `incident` status
     // (the base `status` column is never touched) and carry the mirrored incident block.
     const incident = statusIncidentFor(p);
+    const orphaned = isOrphanedPr(p);
     return {
       prKey: p.pr_key,
       repo: p.repo,
       number: p.number,
       url: p.url,
       title: p.title ?? null,
-      status: incident ? INCIDENT_STATUS : p.status,
+      status: orphaned ? ORPHANED_PR_STATUS : incident ? INCIDENT_STATUS : p.status,
       round: p.current_round,
       processKey: p.process_key ?? null,
       waitingSince: p.waiting_since ?? null,
@@ -1273,10 +1299,57 @@ export async function activePrs(
       autoResolveEscalations: p.auto_resolve_escalations === 1,
       merge: mergeByPr.get(p.pr_key) ?? mergePolicyDefault(),
       incident,
+      terminationReason: p.termination_reason ?? null,
     };
   });
 }
 
+/** `/status` overlay for an ORPHANED PR (issue #943): its loop instance ended (derived tracking edge
+ * folded to `abandoned`) while the base row still sits at an in-flight stage — no worker or human
+ * settled it — and no termination reason was recorded (every app-initiated cancel records one via
+ * {@link terminatePrLoop}, and the operator cancel door records one too), no merge landed, and no
+ * successor took over. Cleared by an operator Dismiss (`acknowledged_at`). That is exactly the
+ * silently-dropped nanobpm/nano-bpm#1452 shape; it must be visible, not filtered out. */
+export const ORPHANED_PR_STATUS = "orphaned";
+
+/** Whether a tracked PR row is orphaned (see {@link ORPHANED_PR_STATUS}). Exported for tests. */
+export function isOrphanedPr(p: {
+  status: string;
+  derived_status: string;
+  process_key?: string | null;
+  termination_reason?: string | null;
+  termination_process_key?: string | null;
+  merged_at: string | null;
+  acknowledged_at?: string | null;
+}): boolean {
+  return (
+    TERMINAL_STATUSES.includes(p.derived_status) &&
+    // An operator Dismiss (`acknowledged_at`) clears the overlay once a human has seen it.
+    !p.acknowledged_at &&
+    // The BASE row is still at an in-flight stage of the loop (the manifest's active set): nothing
+    // settled it. This base-vs-derived divergence IS the orphan signal.
+    activeStatusesFor("pull_requests").includes(p.status) &&
+    // 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
+  );
+}
+
+/** Whether the row carries a termination reason recorded for the instance that currently owns it. */
+function hasOwnTerminationReason(p: {
+  process_key?: string | null;
+  termination_reason?: string | null;
+  termination_process_key?: string | null;
+}): boolean {
+  return (
+    !!p.termination_reason &&
+    p.termination_process_key != null &&
+    p.process_key != null &&
+    String(p.termination_process_key) === String(p.process_key)
+  );
+}
+
 /** The default merge policy when no instance variables are readable (mid-handoff row, engine
  * unreachable, or a legacy loop carrying neither variable): the pre-#916 behaviour merged by
  * default, so the projection must NOT read such a PR as review-only. */
@@ -1592,7 +1665,7 @@ export async function retireTerminalReviewWait(
   if (pr.process_key != null) {
     const key = String(pr.process_key);
     try {
-      await engine.cancelInstance({ processInstanceKey: key });
+      await terminatePrLoop(data, engine, pr.pr_key, key, `review wait retired: PR ${liveness} out-of-band`, true);
     } catch (err) {
       // Only finalize the row once the instance is confirmed gone/terminal: a transiently-failed
       // cancel would otherwise drop the row from `waiting_review` scans while the live instance's
@@ -2016,36 +2089,75 @@ export async function maybeEnsureFreshHeadRun(
  * defaults `autoResolveEscalations` to false and overwrites the row's flag on reopen, so an opted-in PR
  * would silently lose automated escalation resolution merely because late review threads appeared.
  *
- * RETRYABLE on failure (PR #922 review, thread 3): if the cancel succeeds but `submitPr` throws, the
- * row is restored to `waiting_merge` so the next pass re-attempts the handoff against the
- * already-retired (terminal) merge key — rather than stranding in `waiting_review`, which `pollMerges`
- * no longer scans and whose `readiness-ready` resume correlates to nothing once the merge instance is
- * cancelled. The restored row's `process_key` still names the now-terminal merge instance, so the
- * unfinished handoff is re-detected next pass by the dead-owner guard in `pollMerges` (which keys off
- * the terminal `derived_status`, independently of the GitHub verdict). Best-effort throughout: a failed
- * cancel or restore only logs, leaving the row for the next pass. */
-async function handoffWaitingMergeToConvergence(
+ * RETRYABLE on failure, with creation and retirement recovered SEPARATELY (PR #944 review): if no
+ * successor is created, the row is restored to `waiting_merge` naming the still-LIVE merge owner, so
+ * the next pass simply retries. Once a successor is published the row is never demoted; retiring the
+ * captured merge key is retried by {@link retireHandedOffMergeLoop}. Exported for tests. */
+export async function handoffWaitingMergeToConvergence(
   data: DataLayer,
   engine: EngineClient,
   pr: PullRequest,
   logContext: string,
 ) {
   const prKey = pr.pr_key;
+  const mergeKey = pr.process_key != null ? String(pr.process_key) : null;
   try {
     // `waiting_since` bounds the review the fresh loop collects: only a review submitted at or after
     // the handoff counts, so a pre-merge review (submitted before this flip) can never satisfy the new
     // run's wait.
-    const handoffTs = now();
-    await prs(data).update(prKey, { status: "waiting_review", waiting_since: handoffTs, updated_at: handoffTs });
-    const mergeKey = pr.process_key;
-    if (mergeKey != null) {
-      try {
-        await engine.cancelInstance({ processInstanceKey: String(mergeKey) });
-      } catch (cancelErr) {
-        console.error(`[poller] ${logContext} handoff ${prKey}: retire merge instance ${mergeKey}: ${cancelErr}`);
-      }
+    // FENCE the staging write on the captured owner (PR #944 review): if a cancel/resubmit replaced the
+    // owner while this pass awaited GitHub, the replacement owns the row (possibly parked on a stage such
+    // as `waiting_deps`) — re-staging it to `waiting_review` would strand it outside its stage's scan.
+    // The STAGE side of the fence is an allowlist (PR #944 round-6 review), not "unchanged since this
+    // pass read the row": a restart mid-handoff can strand the row at a handoff-transient stage
+    // (`waiting_review`, or keyless at `converging` after a phantom null-key publish) outside the
+    // `waiting_merge` recovery scan, and an unchanged-stage fence would skip it forever. The fence
+    // admits (a) the LIVE merge stages the merge poller scans (`waiting_merge`, `waiting_lane`) and
+    // (b) a KEYLESS row at a handoff-transient stage — there is no live owner to protect, and the
+    // rollback below restores the live merge stage so the next pass re-drives the handoff. A
+    // successor-owned row (`converging` naming the fresh convergence instance) still fails the OWNER
+    // check and is never demoted; a predecessor-owned `waiting_review` row is mid-handoff and is left
+    // for `retryPendingRetirements`, not re-staged.
+    const fresh = await prs(data).get(prKey);
+    const freshOwner = fresh?.process_key != null ? String(fresh.process_key) : null;
+    const HANDOFFABLE_STAGES = new Set(["waiting_merge", "waiting_lane"]);
+    const HANDOFF_TRANSIENT_STAGES = new Set(["waiting_review", "converging"]);
+    const stageOk =
+      HANDOFFABLE_STAGES.has(String(fresh?.status)) ||
+      (freshOwner == null && HANDOFF_TRANSIENT_STAGES.has(String(fresh?.status)));
+    if (!fresh || freshOwner !== mergeKey || !stageOk) {
+      console.log(`[poller] ${logContext} handoff ${prKey}: owner/stage changed (${freshOwner}/${fresh?.status}); skipping`);
+      return;
+    }
+    // ONE pending predecessor retirement at a time (PR #944 review): while an earlier predecessor's
+    // retirement is unconfirmed, never start another handoff — a second key would overwrite the first
+    // and leave that live loop untracked. `retryPendingRetirements` clears it first. A KEYLESS owner
+    // row is exempt (PR #944 round-6 review): there is no live owner to protect — the pending key names
+    // the predecessor the ORIGINAL handoff stranded, and this recovery handoff re-stages against THAT
+    // SAME key, so nothing is overwritten.
+    const pendingKey = fresh.retire_pending_key != null ? String(fresh.retire_pending_key) : "";
+    if (pendingKey !== "" && mergeKey != null && pendingKey !== mergeKey) {
+      console.log(`[poller] ${logContext} handoff ${prKey}: predecessor ${pendingKey} retirement pending; deferring`);
+      return;
     }
-    await submitPr(
+    const handoffTs = now();
+    // Persist the retirement INTENT in the same write that stages the handoff (PR #944 review), so a
+    // restart after successor publication can never lose the predecessor's key. The retry pass only
+    // acts once the row's owner is no longer this key (i.e. the successor is published); a rollback
+    // clears it.
+    await prs(data).update(prKey, {
+      status: "waiting_review",
+      waiting_since: handoffTs,
+      updated_at: handoffTs,
+      ...(mergeKey != null ? { retire_pending_key: mergeKey } : {}),
+    });
+    // SUCCESSOR FIRST, then retire (issue #943). The old order — cancel the merge instance, THEN
+    // `submitPr` — orphaned nanobpm/nano-bpm#1452: the derived tracking status folds the cancel in
+    // asynchronously, so `submitPr` still read the row's `process_key` as a LIVE owner, returned
+    // `alreadyRunning`, and started NOTHING — the merge loop was gone, no convergence loop took over,
+    // no human was told. Now the live merge instance hands back as the exact owner (`handoffFrom`, the
+    // #939 channel), so the successor exists before the predecessor is retired.
+    const res = await submitPr(
       data,
       engine,
       { repo: pr.repo, number: pr.number, url: pr.url, prKey },
@@ -2055,25 +2167,183 @@ async function handoffWaitingMergeToConvergence(
       null,
       false,
       pr.auto_resolve_escalations === 1,
+      undefined,
+      mergeKey,
     );
-    console.log(`[poller] ${logContext} -> handed back into convergence -> ${prKey}`);
+    const successor = "processKey" in res ? res.processKey : null;
+    if (successor == null) {
+      // Deduped against a REPLACEMENT owner (a cancel/resubmit landed while this pass awaited GitHub):
+      // the live replacement owns the row now — never overwrite its key with the stale merge key.
+      const current = await prs(data).get(prKey);
+      if (current?.process_key != null && String(current.process_key) !== mergeKey) {
+        console.log(`[poller] ${logContext} handoff ${prKey}: replaced by ${current.process_key}; leaving it as owner`);
+        return;
+      }
+      // No successor was started — never retire the merge loop into nothing.
+      throw new Error("convergence hand-off started no successor instance");
+    }
+    // The successor is PUBLISHED: from here on the row is convergence-owned and must never be demoted
+    // back to `waiting_merge` (PR #944 review) — a retirement failure is recovered separately, against
+    // the CAPTURED merge key, without touching the successor's row.
+    if (mergeKey != null) await retireHandedOffMergeLoop(data, engine, prKey, mergeKey, successor, logContext);
+    console.log(`[poller] ${logContext} -> handed back into convergence (${successor}) -> ${prKey}`);
   } catch (err) {
+    // CREATION failed (submitPr threw or started nothing): roll back to the prior owner. The merge
+    // instance was NOT retired, so it stays LIVE and keeps owning the PR — restore BOTH the stage and
+    // its `process_key` (a null-successor reopen may already have overwritten the key with NULL), so
+    // the next pass re-attempts the handoff against the right instance. A row that had no owner key
+    // (an earlier unfinished handoff) stays keyless: the NULL key is the durable "unfinished handoff"
+    // marker the dead-owner guard in `pollMerges` keys on. Best-effort: a failed restore is only logged.
     console.error(`[poller] ${logContext} handoff ${prKey}: ${err}`);
-    // Restore the row to `waiting_merge` so the next pass re-attempts the handoff, and NULL the
-    // `process_key`: the merge instance was retired above (or never lived), so the row genuinely has
-    // NO live owner. The null key is the durable "unfinished handoff" marker the dead-owner guard in
-    // `pollMerges` keys on — and it is what distinguishes this retryable shape from a HUMAN cancel of a
-    // parked merge wait (which leaves `process_key` naming the terminated instance and must NOT be
-    // resurrected). Best-effort: a failed restore still leaves the original error logged.
     try {
-      await prs(data).update(prKey, { status: "waiting_merge", process_key: null, updated_at: now() });
+      // FENCE the rollback on the captured owner (PR #944 review): if a replacement took the row while
+      // we awaited, it owns the PR — restoring the stale merge key would point tracking at a retired loop.
+      const current = await prs(data).get(prKey);
+      if (current?.process_key != null && String(current.process_key) !== mergeKey) {
+        console.log(`[poller] ${logContext} handoff ${prKey}: owner changed to ${current.process_key}; no rollback`);
+        return;
+      }
+      await prs(data).update(prKey, {
+        status: "waiting_merge",
+        ...(mergeKey != null ? { process_key: mergeKey, retire_pending_key: null } : {}),
+        updated_at: now(),
+      });
     } catch (restoreErr) {
       console.error(`[poller] ${logContext} handoff ${prKey}: restore waiting_merge: ${restoreErr}`);
     }
   }
 }
 
+/** Retire the predecessor merge loop after its convergence successor is published (issue #943, PR #944
+ * review). Bounded retry against the CAPTURED merge key; a persistent failure is logged loudly but never
+ * rolls the successor-owned row back. Exported for tests. */
+export async function retireHandedOffMergeLoop(
+  data: DataLayer,
+  engine: Pick<EngineClient, "cancelInstance">,
+  prKey: string,
+  mergeKey: string,
+  successor: string,
+  logContext: string,
+  attempts = 2,
+): Promise<boolean> {
+  const reason = `merge loop handed back to convergence (${logContext}) -> successor ${successor}`;
+  for (let i = 1; i <= attempts; i++) {
+    try {
+      await terminatePrLoop(data, engine, prKey, mergeKey, reason, true);
+      await setRetirePending(data, prKey, mergeKey, false);
+      return true;
+    } catch (err) {
+      console.error(`[poller] ${logContext} handoff ${prKey}: retire merge ${mergeKey} attempt ${i}/${attempts}: ${err}`);
+    }
+  }
+  // Persist the pending retirement so later passes keep retrying it (never drop the predecessor key —
+  // a live merge loop could fire its timeout and overwrite the successor-owned row).
+  await setRetirePending(data, prKey, mergeKey, true);
+  return false;
+}
+
+/** Durably mark/clear a pending predecessor retirement. Clearing is fenced on the key so a newer
+ * pending retirement is never wiped by an older one's success. Best-effort (logged). */
+async function setRetirePending(data: DataLayer, prKey: string, mergeKey: string, pending: boolean): Promise<void> {
+  try {
+    const row = await prs(data).get(prKey);
+    if (!row) return;
+    if (pending) await prs(data).update(prKey, { retire_pending_key: mergeKey, updated_at: now() });
+    else if (row.retire_pending_key != null && String(row.retire_pending_key) === mergeKey)
+      await prs(data).update(prKey, { retire_pending_key: null, updated_at: now() });
+  } catch (err) {
+    console.error(`[poller] ${prKey}: persist retire-pending ${mergeKey}: ${err}`);
+  }
+}
+
+/** Poll pass (PR #944 review): re-attempt every persisted pending predecessor retirement. Never touches
+ * the row's stage or owner — only the predecessor instance and the pending marker. Exported for tests. */
+export async function retryPendingRetirements(data: DataLayer, engine: Pick<EngineClient, "cancelInstance">) {
+  for (const pr of await prs(data).all()) {
+    const key = pr.retire_pending_key;
+    if (key == null || key === "") continue;
+    // A pending key that is still the row's OWNER means the handoff never published a successor (e.g. a
+    // restart mid-handoff): the merge loop is live and owning — never retire it into nothing.
+    if (pr.process_key != null && String(pr.process_key) === String(key)) continue;
+    // A KEYLESS owner row is the same unpublished-handoff shape (PR #944 round-5 review): `submitPr`
+    // can publish a null `process_key`, and if the app stops before the rollback lands (or the rollback
+    // write fails) the pending key survives with NO successor. Retiring here would cancel the still-live
+    // merge loop with successor "none" — the ownerless termination this PR exists to prevent. Leave the
+    // pending marker in place: the dead-owner guard in `pollMerges` re-drives the handoff from the
+    // NULL-key row, and the next pass after a successor is published retires the predecessor against it.
+    if (pr.process_key == null) {
+      console.log(`[poller] retire-retry ${pr.pr_key}: no successor published (process_key null); deferring retirement of ${key}`);
+      continue;
+    }
+    await retireHandedOffMergeLoop(data, engine, pr.pr_key, String(key), String(pr.process_key), "retire-retry", 1);
+  }
+}
+
+/** Record WHY a PR loop instance was terminated (issue #943), bound to THAT instance. The ONE writer of
+ * termination provenance, shared by {@link terminatePrLoop} (app-initiated) and every operator cancel
+ * door (`/actions/cancel`, `/actions/cancel-pr`). The reason is stamped only when `processKey` is the
+ * row's CURRENT owner: once a successor owns the row (the convergence hand-off publishes it before
+ * retiring the predecessor), the predecessor's reason has nothing to explain on that row and must not
+ * mask a later orphaning of the successor (PR #944 review). Exported for the cancel doors + tests. */
+export async function recordTerminationProvenance(
+  data: DataLayer,
+  prKey: string,
+  processKey: string,
+  reason: string,
+): Promise<boolean> {
+  const row = await prs(data).get(prKey);
+  if (!row || row.process_key == null || String(row.process_key) !== String(processKey)) return false;
+  await prs(data).update(prKey, {
+    termination_reason: reason,
+    termination_process_key: String(processKey),
+    updated_at: now(),
+  });
+  return true;
+}
+
+/** Record operator-cancel provenance on every PR row a cancelled instance owns (issue #943). */
+export async function recordOperatorCancelProvenance(data: DataLayer, processKey: string, door: string): Promise<void> {
+  for (const row of await prs(data).find({ process_key: processKey })) {
+    await recordTerminationProvenance(data, row.pr_key, processKey, `operator cancel (${door})`);
+  }
+}
+
+/** THE canonical door for an app-initiated cancel of a PR's convergence/merge loop (issue #943).
+ * Every in-app termination must say WHY and what took over: the reason (which names the successor
+ * instance or the terminal GitHub outcome) is stamped on the row's `termination_reason` BEFORE the
+ * engine cancel, so even a crash between the two leaves provenance. `strict` rethrows a failed cancel
+ * (callers that must confirm the instance is gone); otherwise a failed cancel is logged. The
+ * `cancel-sites` guard test (app/loopTermination.test.ts) fails if any new `cancelInstance` call site
+ * targeting a PR loop bypasses this door. Exported for tests. */
+export async function terminatePrLoop(
+  data: DataLayer,
+  engine: Pick<EngineClient, "cancelInstance">,
+  prKey: string,
+  processKey: string,
+  reason: string,
+  strict: boolean,
+): Promise<void> {
+  try {
+    await recordTerminationProvenance(data, prKey, processKey, reason);
+  } catch (err) {
+    // Provenance is diagnostic: a failed write must never keep a loop alive that must be retired.
+    console.error(`[loop] ${prKey}: record termination reason for ${processKey} failed: ${err}`);
+  }
+  try {
+    await engine.cancelInstance({ processInstanceKey: processKey });
+  } catch (err) {
+    if (strict) throw err;
+    console.error(`[loop] ${prKey}: cancel ${processKey} (${reason}) failed: ${err}`);
+  }
+}
+
 export async function pollMerges(data: DataLayer, engine: EngineClient, token: string) {
+  // 0) Pending predecessor retirements from earlier hand-offs (PR #944 review).
+  try {
+    await retryPendingRetirements(data, engine);
+  } catch (err) {
+    console.error(`[poller] retire-retry: ${err}`);
+  }
   // 1) Dependencies merged?
   for (const pr of await prs(data).find({ status: "waiting_deps" })) {
     const prKey = pr.pr_key;

package/app/terminalReaderBehaviour.test.ts

@@ -104,6 +104,10 @@ test("submitPr re-opens a derive-only-terminated PR (base 'converging', derived
           status: "converging", // base transient FROZEN — reconciler no longer writes the terminal
           derived_status: "abandoned", // ADR-0065 derive-only terminal
           current_round: 3,
+          // A PRIOR run's operator Dismiss + provenance must not survive the reopen (PR #944 review).
+          acknowledged_at: "2024-01-05",
+          termination_reason: "operator cancel",
+          termination_process_key: "PI-1",
         }],
         key: "pr_key",
       },
@@ -126,24 +130,31 @@ test("submitPr re-opens a derive-only-terminated PR (base 'converging', derived
     assertEquals(pr.status, "converging");
     assertEquals(pr.current_round, 1); // re-opened for a fresh run
     assertEquals(pr.process_key, "PI-9");
+    assertEquals(pr.acknowledged_at, null, "a prior run's Dismiss never acknowledges this run's orphaning");
+    assertEquals(pr.termination_reason, null);
+    assertEquals(pr.termination_process_key, null);
   });
 });
 
-// #503 / #497 phantom: `activePrs` filters on `derived_status`, so a derive-only-terminated PR drops
-// off the Convergence tab instead of showing "active" indefinitely.
-test("activePrs excludes a derive-only-terminated PR and keeps a genuinely active one", async () => {
+// #503 / #497 phantom: `activePrs` classifies on `derived_status`, so a derive-only-terminated PR never
+// reads as its frozen in-flight base status. Issue #943: if NO reason was recorded for the termination
+// (an orphan) it is surfaced as `orphaned` rather than silently dropped; a recorded reason or an
+// operator Dismiss (`acknowledged_at`) excludes it.
+test("activePrs never reports a derive-only-terminated PR as active — orphaned if unexplained, excluded if explained/dismissed", async () => {
   const stores: Stores = {
     pull_requests: {
       rows: [
         { pr_key: "o/r#1", repo: "o/r", number: 1, url: "u1", status: "converging", derived_status: "abandoned", current_round: 2, updated_at: "2024-01-02" },
         { pr_key: "o/r#2", repo: "o/r", number: 2, url: "u2", status: "converging", derived_status: "converging", current_round: 1, updated_at: "2024-01-01" },
+        { pr_key: "o/r#3", repo: "o/r", number: 3, url: "u3", status: "converging", derived_status: "abandoned", process_key: "PI-3", termination_reason: "operator cancel", termination_process_key: "PI-3", current_round: 1, updated_at: "2024-01-03" },
+        { pr_key: "o/r#4", repo: "o/r", number: 4, url: "u4", status: "converging", derived_status: "abandoned", acknowledged_at: "2024-01-05", current_round: 1, updated_at: "2024-01-04" },
       ],
       key: "pr_key",
     },
     escalations: { rows: [], key: "id" },
   };
   const active = await activePrs(memData(stores));
-  assertEquals(active.map((p) => p.prKey), ["o/r#2"]);
+  assertEquals(active.map((p) => [p.prKey, p.status]), [["o/r#1", "orphaned"], ["o/r#2", "converging"]]);
 });
 
 // #503: `pollIncidentsImpl` classifies a dead instance on `derived_status`, so a derive-only-terminated

package/build-info.json

@@ -1,6 +1,6 @@
 {
-  "version": "0.208.2",
-  "gitSha": "a9778e1c7db7205fe0b3b5dfebc597468c4e66f4",
-  "gitTag": "v0.208.2",
-  "builtAt": "2026-11-10T20:28:50.098Z"
+  "version": "0.208.3",
+  "gitSha": "ff42e2a6fa77fd780949822adf3d4f2b9caefc38",
+  "gitTag": "v0.208.3",
+  "builtAt": "2026-11-11T02:35:58.462Z"
 }

package/db/migrations/130_pull_requests_termination_reason.sql

@@ -0,0 +1,17 @@
+-- Loop-termination provenance (issue #943). A merge loop was terminated in-app (the waiting-merge →
+-- convergence hand-off) with no successor and no escalation, and nothing on the row said why — the PR
+-- silently dropped off `/status`. Every APP-INITIATED cancel of a PR's convergence/merge loop now
+-- stamps a one-line reason here (via `terminatePrLoop` in app/service.ts), naming the outcome it
+-- led to (a successor convergence instance, or the PR's terminal GitHub state). NULL when the current
+-- run was never cancelled by the app. `/status` surfaces it, and an `orphaned` overlay flags a PR
+-- whose loop ended with NO recorded reason, no successor and no escalation.
+ALTER TABLE pull_requests ADD COLUMN termination_reason TEXT;
+
+-- The instance the reason describes (PR #944 review): provenance is bound to the CANCELLED instance and
+-- only explains a termination while it equals the row's `process_key`, so a predecessor's reason can
+-- never mask the later orphaning of a successor.
+ALTER TABLE pull_requests ADD COLUMN termination_process_key TEXT;
+
+-- A handed-off predecessor merge loop whose retirement has not yet succeeded (PR #944 review): durable
+-- so the poller retries it every pass instead of dropping the key. NULL when nothing is pending.
+ALTER TABLE pull_requests ADD COLUMN retire_pending_key TEXT;

package/db/migrations/131_pull_requests_read_model_termination_reason.sql

@@ -0,0 +1,48 @@
+-- Re-create the `pull_requests_read_model` VIEW so it re-exports the new base column (the VIEW must pass
+-- through EVERY base `pull_requests` column — app/pullRequestReadModel.test.ts DRIFT GUARD). A mechanical
+-- re-emission of 128 with `termination_reason` added; the derived columns are emitted VERBATIM from
+-- app/pullRequestReadModel.ts and are unchanged. No BEGIN/COMMIT (the runner wraps each file). Numbered after 130.
+
+DROP VIEW IF EXISTS pull_requests_read_model;
+
+CREATE VIEW pull_requests_read_model AS
+SELECT
+  pr.pr_key AS pr_key,
+  pr.repo AS repo,
+  pr.number AS number,
+  pr.url AS url,
+  pr.title AS title,
+  COALESCE(pr.derived_status, pr.status) AS status,
+  pr.current_round AS current_round,
+  pr.process_key AS process_key,
+  pr.waiting_since AS waiting_since,
+  pr.last_review_id AS last_review_id,
+  pr.outcome AS outcome,
+  pr.created_at AS created_at,
+  pr.updated_at AS updated_at,
+  pr.converged_at AS converged_at,
+  pr.merged_at AS merged_at,
+  pr.active_worker AS active_worker,
+  pr.lease_until AS lease_until,
+  pr.last_nudge_at AS last_nudge_at,
+  pr.fresh_head_run_head AS fresh_head_run_head,
+  pr.abandon_token AS abandon_token,
+  pr.incident_key AS incident_key,
+  pr.incident_type AS incident_type,
+  pr.incident_since AS incident_since,
+  pr.incident_message AS incident_message,
+  pr.last_round_head AS last_round_head,
+  pr.last_progress_job_key AS last_progress_job_key,
+  pr.last_progress_result AS last_progress_result,
+  pr.last_progress_agent_watermark AS last_progress_agent_watermark,
+  pr.churn_escalated_round AS churn_escalated_round,
+  pr.root_request_key AS root_request_key,
+  pr.epic_phase_label AS epic_phase_label,
+  pr.acknowledged_at AS acknowledged_at,
+  pr.auto_resolve_escalations AS auto_resolve_escalations,
+  pr.termination_reason AS termination_reason,
+  pr.termination_process_key AS termination_process_key,
+  pr.retire_pending_key AS retire_pending_key,
+  CASE WHEN COALESCE((COALESCE((COALESCE(("pr"."derived_status" = 'merged'), 0) OR COALESCE(("pr"."derived_status" = 'converged'), 0) OR COALESCE(("pr"."derived_status" = 'abandoned'), 0) OR COALESCE(("pr"."derived_status" = 'closed'), 0) OR COALESCE(("pr"."derived_status" = 'failed'), 0)), 0) AND COALESCE(("pr"."acknowledged_at" = "pr"."acknowledged_at"), 0)), 0) THEN 'history' ELSE 'active' END AS list_bucket,
+  CASE WHEN COALESCE((COALESCE((COALESCE(("pr"."derived_status" = 'merged'), 0) OR COALESCE(("pr"."derived_status" = 'converged'), 0) OR COALESCE(("pr"."derived_status" = 'abandoned'), 0) OR COALESCE(("pr"."derived_status" = 'closed'), 0) OR COALESCE(("pr"."derived_status" = 'failed'), 0)), 0) AND (NOT COALESCE(COALESCE(("pr"."acknowledged_at" = "pr"."acknowledged_at"), 0), 0))), 0) THEN 1 ELSE 0 END AS ack_open
+FROM pull_requests__tracking pr;

package/openapi.yaml

@@ -94,7 +94,15 @@ components:
         - autoResolveEscalations
         - merge
         - incident
+        - terminationReason
       properties:
+        terminationReason:
+          type: string
+          nullable: true
+          description: >-
+            Why the app (or an operator) last cancelled this PR's current loop instance (issue #943),
+            naming the successor/outcome; null when never. An `orphaned` status means the loop ended
+            with no recorded reason, successor, or escalation.
         prKey:
           type: string
         repo:
@@ -4357,6 +4365,51 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorBody"
+  /actions/cancel-pr:
+    post:
+      operationId: cancelPrRun
+      # x-mcp exclusion: the page-only twin of `cancelInstance` (the per-row Cancel button). Agents use
+      # the guarded `/actions/cancel` door.
+      x-mcp:
+        exclude: true
+      summary: "Page-facing record-consistent cancel (issue #943): identical to `cancelInstance` (shared implementation, records termination provenance) but unguarded, because the declarative page action cannot attach x-hook-secret (see operations/cancelPrRun.ts)."
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CancelInstanceIntent"
+      responses:
+        "200":
+          description: The instance was terminated; its record derives/flips to `abandoned` and drops out of `listActivePrs`.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CancelInstanceResult"
+        "400":
+          description: Missing/invalid `processInstanceKey`.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
+        "404":
+          description: "No tracked record owns the key (a clean no-op — the engine is never touched). Body is a CancelInstanceResult with `ok:false`, `state:\"gone\"`, `reconciled:0`."
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CancelInstanceResult"
+        "502":
+          description: "The cancel did not fully take: EITHER the engine did NOT stop the instance (the cancel was not committed; the run may still be live), OR the engine stopped it but the tracked record did not settle to a terminal edge (`ok:false`, `reconciled:0`) — a wedged record the caller must not read as done."
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CancelInstanceResult"
+        "503":
+          description: The app has no data source configured, so the cancel cannot be reconciled into the record.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
   /actions/incident/retry:
     post:
       operationId: retryIncident

package/operations/cancelInstance.test.ts

@@ -293,3 +293,12 @@ test("record routing also covers PR/plan aggregates (a resolved pull_requests ke
   assertEquals(res.body.ok, true);
   assertEquals(res.body.reconciled, 1);
 });
+
+test("PR#944: operator-cancel provenance is recorded even when the record fails to reconcile (502)", async () => {
+  const rows: any[] = [{ pr_key: "o/r#4", process_key: "400", status: "converging" }];
+  const { app } = makeRecordApp({ pull_requests: { rows, key: "pr_key" } }, { readBackState: "TERMINATED" });
+  const res = await call(app, { processInstanceKey: "400" });
+  assertEquals(res.status, 502, "the unreconciled record still surfaces as 502");
+  assertEquals(rows[0].termination_process_key, "400", "provenance is stamped once the engine confirms termination");
+  assert(typeof rows[0].termination_reason === "string" && rows[0].termination_reason.length > 0);
+});

package/operations/cancelInstance.ts

@@ -37,9 +37,12 @@
 // door, when NANO_PR_WEBHOOK_SECRET is set callers must present it via the x-hook-secret header —
 // mirroring `reconcileEngineState`/`agentCompleteEscalation`.
 
+import type { AppApi } from "@nanobpm/urban";
 import { cancelInstanceReconciling } from "@nanobpm/urban";
 import { engineBackedBindings, resolveTrackedInstance } from "../app/instanceTracking.ts";
+import { recordOperatorCancelProvenance } from "../app/service.ts";
 import { envVar } from "../app/version.ts";
+import type { CancelInstanceResponse } from "../nano-generated/api-io.d.ts";
 import { defineOperation } from "../nano-generated/operations.ts";
 
 const SECRET = envVar("NANO_PR_WEBHOOK_SECRET") ?? "";
@@ -49,6 +52,17 @@ export default defineOperation("cancelInstance", async ({ req, body }, app) => {
     app.log.warn("cancelInstance rejected: missing/invalid shared secret");
     return { status: 401, body: { error: "unauthorized" } };
   }
+  return cancelTrackedRun(app, body, "/actions/cancel");
+});
+
+/** The ONE record-consistent cancel implementation shared by every cancel door (this guarded API/MCP
+ * door and the unguarded page door `/actions/cancel-pr`, operations/cancelPrRun.ts), so both stamp
+ * termination provenance (issue #943, PR #944 review) and neither can drift. Auth stays per door. */
+export async function cancelTrackedRun(
+  app: AppApi,
+  body: unknown,
+  door: string,
+): Promise<{ status: number; body: CancelInstanceResponse }> {
   if (!app.data) {
     app.log.warn("cancelInstance: no data source configured — cannot reconcile the record");
     return { status: 503, body: { error: "no data source configured" } };
@@ -58,7 +72,7 @@ export default defineOperation("cancelInstance", async ({ req, body }, app) => {
   // so a numeric JSON value would already have lost precision before it reached us — accepting it
   // (and coercing it back to a string) would silently cancel the wrong instance and also contradicts
   // the OpenAPI `string` contract. Reject a non-string with a 400 rather than coerce.
-  const raw = body && typeof body === "object" ? body.processInstanceKey : undefined;
+  const raw = body && typeof body === "object" && "processInstanceKey" in body ? body.processInstanceKey : undefined;
   const processInstanceKey = typeof raw === "string" ? raw.trim() : "";
   if (!processInstanceKey) {
     return { status: 400, body: { error: "processInstanceKey is required and must be a string" } };
@@ -124,6 +138,17 @@ export default defineOperation("cancelInstance", async ({ req, body }, app) => {
   // delta lies. Re-read the resolved record and count it reconciled only when its ADR-0065
   // `derived_status` has LEFT its `activeStatuses` (become terminal → resubmittable). When we cannot
   // read the record (no default source), trust the primitive's own count.
+  // Termination provenance (issue #943): a deliberate operator cancel of a PR loop is NOT an orphan —
+  // stamp the reason (as soon as the ENGINE confirms termination, before
+  // the record re-read — a 502 on an unreconciled record must not lose it; PR #944 review) on the owning PR row so `/status` does not flag it `orphaned`. Best-effort.
+  if (canResolveRecord) {
+    try {
+      await recordOperatorCancelProvenance(app.data, processInstanceKey, door);
+    } catch (err) {
+      app.log.warn("cancelInstance: could not record termination reason", { processInstanceKey, error: String(err) });
+    }
+  }
+
   let reconciled = result.reconciled;
   let recordReconciled = true;
   if (canResolveRecord) {
@@ -163,4 +188,5 @@ export default defineOperation("cancelInstance", async ({ req, body }, app) => {
     reconciled,
   });
   return { status: 200, body: responseBody };
-});
+}
+

package/operations/cancelPrRun.ts

@@ -0,0 +1,16 @@
+// POST /app/api/actions/cancel-pr → operationId `cancelPrRun` (issue #943, PR #944 review).
+//
+// The page-facing twin of `cancelInstance` for the per-row Cancel button. The runtime's built-in
+// `/app/actions/cancel` page action bypassed the app's termination-provenance write, so a deliberate
+// UI cancel left an in-flight base status with no reason and `/status` reported it `orphaned`. Both
+// doors now route through ONE implementation (`cancelTrackedRun`), which stamps provenance.
+//
+// Auth posture is preserved: like the built-in page action it replaces (and `retryIncident`), this
+// door is INTENTIONALLY UNGUARDED by NANO_PR_WEBHOOK_SECRET — the `@nanobpm/urban` page runtime cannot
+// attach x-hook-secret, so a guard would 401 every button press on a secured deployment. The guarded
+// `/actions/cancel` stays the API/MCP door; this one is excluded from MCP (`x-mcp`).
+
+import { defineOperation } from "../nano-generated/operations.ts";
+import { cancelTrackedRun } from "./cancelInstance.ts";
+
+export default defineOperation("cancelPrRun", async ({ body }, app) => cancelTrackedRun(app, body, "/actions/cancel-pr"));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.208.2",
+  "version": "0.208.3",
   "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/pages/home.page.json

@@ -247,7 +247,7 @@
             "confirm": "Cancel this PR's review run?",
             "showWhenField": "process_key",
             "action": {
-              "path": "/app/actions/cancel",
+              "path": "/app/api/actions/cancel-pr",
               "body": {
                 "processInstanceKey": "{{row.process_key}}"
               }