@nanobpm/nano-workforce 0.208.2 → 0.208.4

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/repoEnvelope.test.ts

@@ -12,82 +12,18 @@
 // consumer together so they cannot drift again.
 import { test } from "node:test";
 import { assert, assertEquals } from "#test-assert";
-import { agentNodeRepoEnvelope, flattenAgentTaskEnvelope, repoEnvelopeVars } from "./repoEnvelope.ts";
+import { agentNodeRepoEnvelope, flattenAgentTaskEnvelope, recoverBranchCreate, repoEnvelopeVars } from "./repoEnvelope.ts";
 
-// ─── A faithful mirror of the harness's consumer shape ───────────────────────────────
-// These mirror the EXACT semantics of c8ctl-plugin-nano `normalizeTaskEnvelope`
-// (c8ctl-plugin.js): `collectEnvelopeFrom` reassembles the reserved
-// `io.nanobpm.agentTask` namespace out of BOTH a whole-object/JSON value AND flattened
-// dotpath keys, `deepMerge`s the two sources, and `normalizeTaskEnvelope` then reads
-// `branch` from the TOP LEVEL of the merged envelope (`isPlainObject(raw.branch)`),
-// NOT from `raw.repository.branch`. Keeping this mirror in lock-step with the harness
-// is the point of the test: if the producer emits a shape the consumer doesn't read,
-// the round-trip below drops `branch.create` and fails.
-const AGENT_TASK_NS = "io.nanobpm.agentTask";
-
-function isPlainObject(v: unknown): v is Record<string, unknown> {
-  return v != null && typeof v === "object" && !Array.isArray(v);
-}
-
-function deepMerge(base: unknown, over: unknown): unknown {
-  if (!isPlainObject(base)) return isPlainObject(over) ? deepMerge({}, over) : over;
-  const out: Record<string, unknown> = { ...base };
-  if (!isPlainObject(over)) return out;
-  for (const [k, v] of Object.entries(over)) {
-    if (v === undefined) continue;
-    out[k] = isPlainObject(v) && isPlainObject(out[k]) ? deepMerge(out[k], v) : v;
-  }
-  return out;
-}
-
-function setPath(obj: Record<string, unknown>, path: string[], value: unknown): void {
-  let cur = obj;
-  for (let i = 0; i < path.length - 1; i++) {
-    const k = path[i];
-    if (!isPlainObject(cur[k])) cur[k] = {};
-    cur = cur[k] as Record<string, unknown>;
-  }
-  cur[path[path.length - 1]] = value;
-}
-
-/** Mirror of the harness's `collectEnvelopeFrom`: reassemble the reserved namespace from a
- * whole-object/JSON value AND flattened dotpath keys (element templates / task headers emit the
- * latter). */
-function collectEnvelopeFrom(source: Record<string, unknown>): Record<string, unknown> {
-  const out: Record<string, unknown> = {};
-  if (!isPlainObject(source)) return out;
-  const whole = source[AGENT_TASK_NS];
-  if (whole != null) {
-    let val: unknown = whole;
-    if (typeof whole === "string") {
-      try {
-        val = JSON.parse(whole);
-      } catch {
-        val = undefined;
-      }
-    }
-    if (isPlainObject(val)) Object.assign(out, deepMerge(out, val));
-  }
-  const prefix = `${AGENT_TASK_NS}.`;
-  for (const [key, value] of Object.entries(source)) {
-    if (!key.startsWith(prefix)) continue;
-    const rest = key.slice(prefix.length);
-    if (!rest) continue;
-    setPath(out, rest.split("."), value);
-  }
-  return out;
-}
-
-/** Mirror of the harness's `normalizeTaskEnvelope` branch slice: it reads `branch` from the TOP
- * LEVEL of the merged envelope — `isPlainObject(raw.branch) ? raw.branch : {}` — never from
- * `raw.repository.branch`. Returns the consumer's recovered `branch.create` (undefined when the
- * producer put it somewhere the consumer doesn't look). */
-function harnessReadsBranchCreate(customHeaders: Record<string, unknown>, variables: Record<string, unknown>): string | undefined {
-  const raw = deepMerge(collectEnvelopeFrom(customHeaders), collectEnvelopeFrom(variables)) as Record<string, unknown>;
-  const branch = isPlainObject(raw.branch) ? raw.branch : {};
-  const create = branch.create;
-  return create == null ? undefined : String(create);
-}
+// ─── The consumer mirror ─────────────────────────────────────────────────────────────
+// `recoverBranchCreate` (app/repoEnvelope.ts) is the ONE canonical mirror of the c8ctl harness's
+// consumer shape (`collectEnvelopeFrom` + `normalizeTaskEnvelope`): it reassembles the reserved
+// `io.nanobpm.agentTask` namespace out of BOTH a whole-object/JSON value AND flattened dotpath keys,
+// `deepMerge`s the two sources (variables over headers), and reads `branch` from the TOP LEVEL of the
+// merged envelope (`isPlainObject(raw.branch)`), NOT from `raw.repository.branch`. Keeping that mirror
+// in lock-step with the harness is the point of this test: if the producer emits a shape the consumer
+// doesn't read, the round-trip below drops `branch.create` and fails. Aliased here under the
+// harness-centric name the assertions read naturally with.
+const harnessReadsBranchCreate = recoverBranchCreate;
 
 // ─── The round-trip contract ──────────────────────────────────────────────────────────