@nanobpm/nano-workforce 0.32.0 → 0.32.2

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [0.32.2](https://github.com/nanobpm/nano-workforce/compare/v0.32.1...v0.32.2) (2026-08-09)
+
+
+### Bug Fixes
+
+* heal missing pull_requests FK parent before child writes ([#93](https://github.com/nanobpm/nano-workforce/issues/93)) ([896c1f7](https://github.com/nanobpm/nano-workforce/commit/896c1f7a71098463c581816ffc2821af196f779e)), closes [owner/repo#N](https://github.com/owner/repo/issues/N)
+
+## [0.32.1](https://github.com/nanobpm/nano-workforce/compare/v0.32.0...v0.32.1) (2026-08-09)
+
+
+### Bug Fixes
+
+* **cancel:** reconcile terminated Epic/plan runs via instanceTracking ([#96](https://github.com/nanobpm/nano-workforce/issues/96)) ([3d0c5ba](https://github.com/nanobpm/nano-workforce/commit/3d0c5ba1b8bb9bd0c28432323b1867a7c86d1835))
+
 # [0.32.0](https://github.com/nanobpm/nano-workforce/compare/v0.31.0...v0.32.0) (2026-08-09)
 
 

package/app/abandon.test.ts

@@ -3,6 +3,7 @@ import { assertEquals, assertNotEquals } from "jsr:@std/assert@1";
 import type { DataLayer } from "@nanobpm/urban";
 import {
   abandonStatusForToken,
+  abandonTokenFromUrl,
   abandonUrl,
   isAbandoned,
   mintAbandonToken,
@@ -61,6 +62,21 @@ Deno.test("abandonUrl carries the token on the query string (url-encoded)", () =
   );
 });
 
+Deno.test("abandonTokenFromUrl round-trips the token minted into an abandonUrl", () => {
+  const tok = mintAbandonToken();
+  assertEquals(abandonTokenFromUrl(abandonUrl(tok, "https://host")), tok);
+  // url-special tokens survive the encode/decode round-trip too.
+  assertEquals(abandonTokenFromUrl(abandonUrl("tok+/=", "https://host")), "tok+/=");
+});
+
+Deno.test("abandonTokenFromUrl returns undefined for absent/tokenless/garbage input", () => {
+  assertEquals(abandonTokenFromUrl(undefined), undefined);
+  assertEquals(abandonTokenFromUrl(null), undefined);
+  assertEquals(abandonTokenFromUrl(""), undefined);
+  assertEquals(abandonTokenFromUrl("https://host/hooks/abandon"), undefined, "no token param");
+  assertEquals(abandonTokenFromUrl("not a url"), undefined, "unparseable input never throws");
+});
+
 Deno.test("renderAbandonBrief embeds the concrete URL and the stop contract", () => {
   const brief = renderAbandonBrief("https://host/hooks/abandon?token=tok");
   assertEquals(brief.includes("https://host/hooks/abandon?token=tok"), true);

package/app/abandon.ts

@@ -44,6 +44,21 @@ export function abandonUrl(token: string, base: string = publicBaseUrl()): strin
   return `${base}/hooks/abandon?token=${encodeURIComponent(token)}`;
 }
 
+/** Recover the capability token from an abandon URL — the inverse of `abandonUrl`. Returns
+ * undefined when the input is absent or carries no `token` query param. A desync-heal uses this to
+ * reconstruct a missing `pull_requests` row with the SAME token the running agent was already
+ * handed (via the `abandonUrl` process variable), so its `curl -f "…/hooks/abandon?token=…"` abort
+ * check keeps resolving instead of 404-ing on a freshly-minted token and aborting a live run. */
+export function abandonTokenFromUrl(url: string | null | undefined): string | undefined {
+  if (!url) return undefined;
+  try {
+    const t = new URL(url).searchParams.get("token");
+    return t || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 /** Resolve an abandon token back to its PR key, or undefined when the token is unknown. */
 export async function prKeyForAbandonToken(
   data: DataLayer,

package/app/ensure-pr.test.ts

@@ -0,0 +1,117 @@
+// Tests for ensurePr — the idempotent, race-safe heal that reconstructs a missing
+// `pull_requests` FK parent before a child (`rounds`/`escalations`/`merges`) insert, so an
+// engine/app.db store desync never parks an opaque `FOREIGN KEY constraint failed` incident
+// (observed on convergence-loop instance 94).
+import { assert, assertEquals } from "jsr:@std/assert@1";
+import type { DataLayer } from "@nanobpm/urban";
+import { canonicalPrUrl, ensurePr } from "./service.ts";
+
+// A tiny in-memory DataLayer backing only the `.get`/`.insert` surface ensurePr uses. `insert`
+// can be made to throw to exercise the race guard, optionally after seeding the row so the
+// post-throw `.get` sees it.
+function memData(opts: { throwOnInsert?: boolean; seedOnThrow?: boolean } = {}): {
+  data: DataLayer;
+  rows: Map<string, Record<string, unknown>>;
+  insertCalls: number;
+} {
+  const rows = new Map<string, Record<string, unknown>>();
+  let insertCalls = 0;
+  function tbl(name: string, key: string) {
+    return {
+      // deno-lint-ignore require-await
+      async get(id: string) {
+        return rows.get(id);
+      },
+      // deno-lint-ignore no-explicit-any require-await
+      async insert(row: any) {
+        insertCalls++;
+        if (opts.throwOnInsert) {
+          if (opts.seedOnThrow) rows.set(row[key], { ...row });
+          throw new Error("FOREIGN KEY constraint failed");
+        }
+        rows.set(row[key], { ...row });
+        return row[key];
+      },
+    };
+  }
+  // deno-lint-ignore no-explicit-any
+  const data = { table: (n: string, k: string) => tbl(n, k) } as any as DataLayer;
+  return { data, rows, get insertCalls() {
+    return insertCalls;
+  } };
+}
+
+Deno.test("ensurePr is a no-op when the parent already exists", async () => {
+  const mem = memData();
+  const { data, rows } = mem;
+  rows.set("o/r#1", { pr_key: "o/r#1", status: "converging" });
+  const before = { ...rows.get("o/r#1") };
+  await ensurePr(data, { prKey: "o/r#1", repo: "o/r", number: 1 });
+  assertEquals(rows.size, 1, "no new row is written");
+  assertEquals(rows.get("o/r#1"), before, "the existing row is untouched");
+  assertEquals(mem.insertCalls, 0, "insert is never attempted — the no-write guarantee holds");
+});
+
+Deno.test("ensurePr reconstructs a minimal converging row when the parent is absent", async () => {
+  const { data, rows } = memData();
+  await ensurePr(data, { prKey: "o/r#2", repo: "o/r", number: 2, round: 3 });
+  const row = rows.get("o/r#2")!;
+  assertEquals(row.pr_key, "o/r#2");
+  assertEquals(row.repo, "o/r");
+  assertEquals(row.number, 2);
+  assertEquals(row.status, "converging");
+  assertEquals(row.current_round, 3, "the round is carried through so the aggregate isn't behind");
+  assertEquals(row.url, canonicalPrUrl("o/r", 2), "URL is derived canonically when none is passed");
+  assert(typeof row.abandon_token === "string" && (row.abandon_token as string).length > 0);
+});
+
+Deno.test("ensurePr defaults current_round to 1 (rounds are 1-based) when none is passed", async () => {
+  const { data, rows } = memData();
+  await ensurePr(data, { prKey: "o/r#5", repo: "o/r", number: 5 });
+  assertEquals(
+    rows.get("o/r#5")!.current_round,
+    1,
+    "an unknown round heals to 1, not 0, matching submitPr's 1-based invariant",
+  );
+});
+
+Deno.test("ensurePr reuses a supplied abandon token instead of minting a new one", async () => {
+  const { data, rows } = memData();
+  await ensurePr(data, { prKey: "o/r#7", repo: "o/r", number: 7, abandonToken: "TOK-en_123" });
+  assertEquals(
+    rows.get("o/r#7")!.abandon_token,
+    "TOK-en_123",
+    "the running agent's existing token is preserved so its abort check keeps resolving",
+  );
+});
+
+Deno.test("ensurePr mints a token when none is supplied", async () => {
+  const { data, rows } = memData();
+  await ensurePr(data, { prKey: "o/r#8", repo: "o/r", number: 8 });
+  const tok = rows.get("o/r#8")!.abandon_token;
+  assert(typeof tok === "string" && (tok as string).length > 0, "a fresh token is minted as a fallback");
+});
+
+Deno.test("ensurePr prefers an explicit url over the canonical one", async () => {
+  const { data, rows } = memData();
+  const url = "https://github.com/o/r/pull/9";
+  await ensurePr(data, { prKey: "o/r#9", repo: "o/r", number: 9, url });
+  assertEquals(rows.get("o/r#9")!.url, url);
+});
+
+Deno.test("ensurePr swallows an insert race when the row appears anyway", async () => {
+  // insert throws (unique-violation / concurrent writer) but the row is now present → healed.
+  const { data } = memData({ throwOnInsert: true, seedOnThrow: true });
+  await ensurePr(data, { prKey: "o/r#3", repo: "o/r", number: 3 });
+});
+
+Deno.test("ensurePr rethrows when the insert fails and the row is still absent", async () => {
+  const { data } = memData({ throwOnInsert: true, seedOnThrow: false });
+  let threw = false;
+  try {
+    await ensurePr(data, { prKey: "o/r#4", repo: "o/r", number: 4 });
+  } catch (_e) {
+    threw = true;
+  }
+  assert(threw, "a genuine insert failure must surface, not be silently swallowed");
+});

package/app/instance-tracking.test.ts

@@ -0,0 +1,73 @@
+// Guard for the `instanceTracking` manifest bindings (nano.app.json). The reconciler flips a row
+// whose engine instance is TERMINATED only when the row is in one of `activeStatuses`. A status
+// that is genuinely in-flight but missing from that list would leave an operator-terminated (or
+// crashed) run stuck "active" in the UI — the exact drift Copilot flagged on #96. This ties the
+// manifest to the code's single source of truth for "done" (TERMINAL_STATUSES / PLAN_TERMINAL_
+// STATUSES) so the two can't diverge silently.
+import { assert, assertEquals } from "jsr:@std/assert@1";
+import { TERMINAL_STATUSES } from "./service.ts";
+import { PLAN_TERMINAL_STATUSES } from "./plan.ts";
+
+interface Binding {
+  table: string;
+  statusField?: string;
+  activeStatuses?: string[];
+  onTerminated: { set: Record<string, unknown> };
+}
+
+async function bindings(): Promise<Binding[]> {
+  const manifest = JSON.parse(await Deno.readTextFile(new URL("../nano.app.json", import.meta.url)));
+  return manifest.instanceTracking as Binding[];
+}
+
+function bindingFor(all: Binding[], table: string): Binding {
+  const b = all.find((x) => x.table === table);
+  assert(b, `no instanceTracking binding for ${table}`);
+  return b;
+}
+
+Deno.test("instanceTracking: pull_requests activeStatuses excludes every terminal status", async () => {
+  const b = bindingFor(await bindings(), "pull_requests");
+  for (const terminal of TERMINAL_STATUSES) {
+    assert(
+      !b.activeStatuses?.includes(terminal),
+      `terminal status "${terminal}" must not be listed active (it would let the reconciler clobber a settled row)`,
+    );
+  }
+});
+
+// Every in-flight status the merge train keys off must be reconcilable. These are the states a
+// pull_requests row can hold while a live engine instance still backs it (see app/service.ts merge
+// poller: converging/waiting_review/escalated + the merge-stage waiting_deps/waiting_merge/
+// waiting_lane/queued/merging). If a new one is added to the flow, add it here AND to the manifest.
+Deno.test("instanceTracking: pull_requests activeStatuses covers every in-flight status", async () => {
+  const inFlight = [
+    "converging",
+    "waiting_review",
+    "escalated",
+    "waiting_deps",
+    "waiting_merge",
+    "waiting_lane",
+    "queued",
+    "merging",
+  ];
+  const b = bindingFor(await bindings(), "pull_requests");
+  for (const s of inFlight) {
+    assert(b.activeStatuses?.includes(s), `in-flight status "${s}" missing from activeStatuses`);
+  }
+  // No terminal status leaks into the in-flight universe we assert on.
+  for (const s of inFlight) assert(!TERMINAL_STATUSES.includes(s));
+});
+
+Deno.test("instanceTracking: plans activeStatuses excludes every terminal status", async () => {
+  const b = bindingFor(await bindings(), "plans");
+  for (const terminal of PLAN_TERMINAL_STATUSES) {
+    assert(!b.activeStatuses?.includes(terminal), `terminal status "${terminal}" must not be active`);
+  }
+});
+
+Deno.test("instanceTracking: plans activeStatuses covers every in-flight status", async () => {
+  const inFlight = ["planning", "dispatched"];
+  const b = bindingFor(await bindings(), "plans");
+  assertEquals([...(b.activeStatuses ?? [])].sort(), [...inFlight].sort());
+});

package/app/persist-escalation.test.ts

@@ -12,13 +12,22 @@ import handler from "../workers/persist-escalation/worker.ts";
 function fakeApp() {
   const inserts: Record<string, unknown[]> = { rounds: [], escalations: [] };
   const updates: Record<string, unknown[]> = { pull_requests: [] };
+  const rows: Record<string, Map<string, unknown>> = {};
   const app = {
     data: {
       table(name: string, _key: string) {
+        const store = (rows[name] ??= new Map());
         return {
+          // deno-lint-ignore require-await
+          async get(key: string) {
+            return store.get(key);
+          },
           // deno-lint-ignore require-await
           async insert(row: unknown) {
             (inserts[name] ??= []).push(row);
+            const pk = name === "escalations" ? "id" : name === "rounds" ? "id" : "pr_key";
+            // deno-lint-ignore no-explicit-any
+            store.set((row as any)[pk], row);
             return name === "escalations" ? 42 : 1;
           },
           // deno-lint-ignore require-await
@@ -29,7 +38,7 @@ function fakeApp() {
       },
     },
   };
-  return { app, inserts, updates };
+  return { app, inserts, updates, rows };
 }
 
 Deno.test("stalled arm (recordRound=false) does not insert a duplicate rounds row", async () => {
@@ -55,8 +64,39 @@ Deno.test("escalation arm without the flag still records the round", async () =>
   assertEquals((inserts.rounds[0] as any).round_no, 3);
 });
 
-// A blank question would have to be trimmed away, so a padded-but-non-blank question is stored
-// trimmed (matching the sibling `persist-task-escalation`) — no whitespace drift into the UI/DB.
+// When the convergence-loop passes repo/prNumber and the FK parent is missing (engine/app.db
+// desync), persist-escalation reconstructs the `pull_requests` row before the rounds/escalations
+// inserts so opening an escalation never dies with an opaque FOREIGN KEY constraint failure.
+Deno.test("persist-escalation heals a missing pull_requests parent before recording", async () => {
+  const { app, inserts, updates } = fakeApp();
+  const job = {
+    variables: {
+      prKey: "o/r#8",
+      round: 4,
+      status: "blocked",
+      question: "max rounds",
+      repo: "o/r",
+      prNumber: 8,
+    },
+  };
+  // deno-lint-ignore no-explicit-any
+  await handler(job as any, app as any);
+  assertEquals(inserts.pull_requests?.length, 1, "the missing parent is reconstructed");
+  // Assert against the reconstruction insert payload (ensurePr) rather than the stored row: the
+  // fake update() doesn't apply patches, so the row would otherwise still read the insert's
+  // "converging" status and mask the worker's real final state.
+  // deno-lint-ignore no-explicit-any
+  const healed = inserts.pull_requests![0] as any;
+  assertEquals(healed.status, "converging", "the healed parent starts in the converging aggregate");
+  assertEquals(inserts.rounds.length, 1, "the round is still recorded");
+  assertEquals(inserts.escalations.length, 1, "the escalation is still opened");
+  // And the worker still moves the (now-present) PR to escalated as its final state.
+  assertEquals(updates.pull_requests!.length, 1, "the PR is updated once after the heal");
+  // deno-lint-ignore no-explicit-any
+  assertEquals((updates.pull_requests![0] as any).patch.status, "escalated");
+});
+
+
 Deno.test("a padded question is persisted trimmed (no whitespace drift)", async () => {
   const { app, inserts, updates } = fakeApp();
   const job = { variables: { prKey: "o/r#1", round: 4, status: "needs_input", question: "  needs a decision  " } };
@@ -117,3 +157,31 @@ Deno.test("unclassified status without a question names the status in the fabric
   assert(esc.question.includes("in_progress"), "fabricated question references the raw status");
   assertEquals(esc.kind, "blocker", "a non needs_input status is a blocker escalation");
 });
+
+// When repo/prNumber process variables are absent the heal still runs by parsing the canonical
+// `owner/repo#N` prKey, so the escalation's FK parent is never left unguarded.
+Deno.test("persist-escalation heals from the prKey when repo/prNumber are absent", async () => {
+  const { app, inserts } = fakeApp();
+  const job = {
+    variables: {
+      prKey: "o/r#12",
+      round: 2,
+      status: "needs_input",
+      question: "decide",
+      abandonUrl: "https://host/hooks/abandon?token=TOK-en_123",
+    },
+  };
+  // deno-lint-ignore no-explicit-any
+  await handler(job as any, app as any);
+  assertEquals(inserts.pull_requests?.length, 1, "the parent is reconstructed from the prKey");
+  // deno-lint-ignore no-explicit-any
+  const healed = inserts.pull_requests![0] as any;
+  assertEquals(healed.repo, "o/r");
+  assertEquals(healed.number, 12);
+  assertEquals(healed.url, "https://github.com/o/r/pull/12", "URL is derived from the parsed prKey");
+  assertEquals(
+    healed.abandon_token,
+    "TOK-en_123",
+    "the running agent's abandon token is preserved from abandonUrl, not re-minted",
+  );
+});

package/app/persist-round.test.ts

@@ -12,13 +12,22 @@ import handler from "../workers/persist-round/worker.ts";
 function fakeApp() {
   const inserts: Record<string, unknown[]> = { rounds: [] };
   const updates: Record<string, unknown[]> = { pull_requests: [] };
+  const rows: Record<string, Map<string, unknown>> = {};
   const app = {
     data: {
       table(name: string, _key: string) {
+        const store = (rows[name] ??= new Map());
         return {
+          // deno-lint-ignore require-await
+          async get(key: string) {
+            return store.get(key);
+          },
           // deno-lint-ignore require-await
           async insert(row: unknown) {
             (inserts[name] ??= []).push(row);
+            const pk = name === "rounds" ? "id" : "pr_key";
+            // deno-lint-ignore no-explicit-any
+            store.set((row as any)[pk], row);
             return 1;
           },
           // deno-lint-ignore require-await
@@ -29,7 +38,7 @@ function fakeApp() {
       },
     },
   };
-  return { app, inserts, updates };
+  return { app, inserts, updates, rows };
 }
 
 for (const status of ["addressed", "waiting"]) {
@@ -53,7 +62,38 @@ for (const status of ["addressed", "waiting"]) {
   });
 }
 
-// When the agent omits `status` (e.g. a fallback), persist-round defaults it to `addressed`
+// When the convergence-loop passes repo/prNumber and the FK parent is missing (engine/app.db
+// desync), persist-round reconstructs the `pull_requests` row before recording the round so the
+// insert never dies with an opaque FOREIGN KEY constraint failure.
+Deno.test("persist-round heals a missing pull_requests parent before recording the round", async () => {
+  const { app, inserts, updates } = fakeApp();
+  const job = {
+    variables: {
+      prKey: "o/r#7",
+      round: 3,
+      status: "addressed",
+      repo: "o/r",
+      prNumber: 7,
+    },
+  };
+  // deno-lint-ignore no-explicit-any
+  await handler(job as any, app as any);
+
+  assertEquals(inserts.pull_requests?.length, 1, "the missing parent is reconstructed");
+  // Assert against the reconstruction insert payload (ensurePr) rather than the stored row: the
+  // fake update() doesn't apply patches, so the row would otherwise still read the insert's
+  // "converging" status and mask the worker's real final state.
+  // deno-lint-ignore no-explicit-any
+  const healed = inserts.pull_requests![0] as any;
+  assertEquals(healed.status, "converging", "the healed parent starts in the converging aggregate");
+  assertEquals(healed.url, "https://github.com/o/r/pull/7", "URL is derived canonically");
+  assertEquals(inserts.rounds.length, 1, "the round is still recorded after the heal");
+  // And the worker still parks the (now-present) PR in waiting_review as its final state.
+  assertEquals(updates.pull_requests!.length, 1, "the PR is updated once after the heal");
+  // deno-lint-ignore no-explicit-any
+  assertEquals((updates.pull_requests![0] as any).patch.status, "waiting_review");
+});
+
 // rather than writing a NULL status — the round history stays readable.
 Deno.test("persist-round defaults a missing status to 'addressed'", async () => {
   const { app, inserts } = fakeApp();
@@ -63,3 +103,31 @@ Deno.test("persist-round defaults a missing status to 'addressed'", async () =>
   // deno-lint-ignore no-explicit-any
   assertEquals((inserts.rounds[0] as any).status, "addressed");
 });
+
+// When repo/prNumber process variables are absent (an older in-flight instance, or a regression)
+// the heal still runs by parsing the canonical `owner/repo#N` prKey, so the FK-child insert is
+// never left unguarded.
+Deno.test("persist-round heals from the prKey when repo/prNumber are absent", async () => {
+  const { app, inserts } = fakeApp();
+  const job = {
+    variables: {
+      prKey: "o/r#12",
+      round: 2,
+      status: "addressed",
+      abandonUrl: "https://host/hooks/abandon?token=TOK-en_123",
+    },
+  };
+  // deno-lint-ignore no-explicit-any
+  await handler(job as any, app as any);
+  assertEquals(inserts.pull_requests?.length, 1, "the parent is reconstructed from the prKey");
+  // deno-lint-ignore no-explicit-any
+  const healed = inserts.pull_requests![0] as any;
+  assertEquals(healed.repo, "o/r");
+  assertEquals(healed.number, 12);
+  assertEquals(healed.url, "https://github.com/o/r/pull/12", "URL is derived from the parsed prKey");
+  assertEquals(
+    healed.abandon_token,
+    "TOK-en_123",
+    "the running agent's abandon token is preserved from abandonUrl, not re-minted",
+  );
+});

package/app/service.test.ts

@@ -6,7 +6,7 @@
 // loop already guards in `startPlan`). Drives `submitPr` against an in-memory data layer with the
 // GitHub transport forced off so it is hermetic.
 import { assertEquals } from "jsr:@std/assert@1";
-import { pollIncidentsImpl, submitPr } from "./service.ts";
+import { cancelRun, pollIncidentsImpl, submitPr } from "./service.ts";
 
 // deno-lint-ignore no-explicit-any
 function memTable(rows: any[], key: string) {
@@ -251,3 +251,77 @@ Deno.test("pollIncidents picks the oldest incident by creationTime, sorting a mi
   assertEquals(row.incident_key, "INC-OLD");
   assertEquals(row.incident_message, "the first fault");
 });
+
+
+// Bug: the Epic cancel button (Nano Workforce UI) POSTs the plan row's `process_key` to
+// /app/actions/cancel → cancelRun. cancelRun only knows the `pull_requests` table, so for a plan
+// instance it terminated the engine instance but returned `not_found` (a 404 the UI surfaces as an
+// error), and never reconciled the `plans` row — so "cancel didn't cancel the epic". The instance
+// IS torn down; the declarative instanceTracking reconciler flips the plans row. cancelRun must
+// therefore report success for a raw instance key it terminated.
+Deno.test("cancelRun terminates a non-PR (Epic/plan) instance and reports success", async () => {
+  const stores: Record<string, { rows: unknown[]; key: string }> = {
+    pull_requests: { rows: [], key: "pr_key" }, // no PR tracks this key — it's a plan instance
+  };
+  const data = {
+    table: (name: string, key: string) => memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key),
+    // deno-lint-ignore no-explicit-any
+  } as any;
+  const cancelled: string[] = [];
+  const engine = {
+    // deno-lint-ignore no-explicit-any
+    cancelInstance: (input: any) => {
+      cancelled.push(String(input.processInstanceKey));
+      return Promise.resolve();
+    },
+    // deno-lint-ignore no-explicit-any
+  } as any;
+
+  const r = await cancelRun(data, engine, { processInstanceKey: "PI-EPIC-1" });
+
+  assertEquals(cancelled, ["PI-EPIC-1"]); // the engine instance was terminated …
+  assertEquals(r.ok, true); // … and cancel is reported successful (no misleading 404).
+});
+
+// The tracked-PR path must still flip the row abandoned SYNCHRONOUSLY: app/abandon.ts derives the
+// agent-abort signal straight off pull_requests.status, so a deferred (reconciler-only) write would
+// widen the check-then-push window a side-effecting agent races against.
+Deno.test("cancelRun flips a tracked PR to abandoned immediately and clears the escalation pointer", async () => {
+  const PR_KEY = "owner/repo#7";
+  const stores: Record<string, { rows: unknown[]; key: string }> = {
+    pull_requests: {
+      rows: [{
+        pr_key: PR_KEY,
+        repo: "owner/repo",
+        number: 7,
+        status: "escalated",
+        process_key: "PI-PR-7",
+        open_escalation_id: 3,
+        open_escalation_question: "why?",
+      }],
+      key: "pr_key",
+    },
+  };
+  const data = {
+    table: (name: string, key: string) => memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key),
+    // deno-lint-ignore no-explicit-any
+  } as any;
+  const cancelled: string[] = [];
+  const engine = {
+    // deno-lint-ignore no-explicit-any
+    cancelInstance: (input: any) => {
+      cancelled.push(String(input.processInstanceKey));
+      return Promise.resolve();
+    },
+    // deno-lint-ignore no-explicit-any
+  } as any;
+
+  const r = await cancelRun(data, engine, { prKey: PR_KEY });
+
+  assertEquals(r.ok, true);
+  assertEquals(cancelled, ["PI-PR-7"]);
+  const pr = stores.pull_requests.rows[0] as Record<string, unknown>;
+  assertEquals(pr.status, "abandoned");
+  assertEquals(pr.open_escalation_id, null);
+  assertEquals(pr.open_escalation_question, null);
+});

package/app/service.ts

@@ -168,6 +168,64 @@ export interface ParsedPr {
   prKey: string;
 }
 
+/** Canonical GitHub PR URL for a repo + number. Matches the `url` `parsePr` derives, so a
+ * reconstructed row is indistinguishable from one registered at submit time. */
+export function canonicalPrUrl(repo: string, number: number): string {
+  return `https://github.com/${repo}/pull/${number}`;
+}
+
+/**
+ * Guarantee the `pull_requests` parent row exists before a FK-child row (`rounds`, `escalations`,
+ * `merges`) is written. Idempotent and race-safe.
+ *
+ * The durable engine and the app's `app.db` are two INDEPENDENT stores. If they ever desync — the
+ * DB is rebuilt, restored from a stale copy, or simply lags a live process instance while running
+ * from a local checkout — a persist/finalize/merge job would otherwise insert a child row whose
+ * FK parent is absent and die with an opaque `FOREIGN KEY constraint failed` incident that a human
+ * has to hand-resolve (observed on convergence-loop instance 94). The PR's `repo`/`prNumber` are
+ * normally carried as process variables; where they may be absent (older in-flight instances) the
+ * call sites derive them from the canonical `owner/repo#N` prKey, so the parent can always be
+ * reconstructed deterministically: we heal the missing row (a minimal `converging` aggregate) and
+ * let the loop continue instead of parking a dead-end incident. Callers pass the instance's
+ * `abandonToken` (recovered from its `abandonUrl` var) so the healed row keeps the token the
+ * running agent was handed and its cooperative-abort check keeps resolving. When the row already
+ * exists this is a no-op, so the healthy path is unchanged.
+ */
+export async function ensurePr(
+  data: DataLayer,
+  pr: { prKey: string; repo: string; number: number; url?: string; round?: number; abandonToken?: string },
+): Promise<void> {
+  const table = prs(data);
+  if (await table.get(pr.prKey)) return;
+  const ts = now();
+  console.warn(
+    `[ensurePr] pull_requests row for ${pr.prKey} was missing — reconstructing it so the FK-child ` +
+      `write can proceed (engine/app.db desync heal)`,
+  );
+  try {
+    await table.insert({
+      pr_key: pr.prKey,
+      repo: pr.repo,
+      number: pr.number,
+      url: pr.url ?? canonicalPrUrl(pr.repo, pr.number),
+      status: "converging",
+      current_round: pr.round ?? 1,
+      // Reuse the token the running agent was already handed (recovered from the instance's
+      // `abandonUrl` var) so its abort check keeps resolving; only mint a fresh one when the caller
+      // has no token to preserve (e.g. an old instance predating the `abandonUrl` variable).
+      abandon_token: pr.abandonToken ?? mintAbandonToken(),
+      created_at: ts,
+      updated_at: ts,
+    });
+  } catch (err) {
+    // Lost a race with a concurrent writer (submitPr or another job created the row first): the
+    // parent now exists, which is exactly the goal, so swallow. Only a still-absent row is a real
+    // failure worth surfacing.
+    if (await table.get(pr.prKey)) return;
+    throw err;
+  }
+}
+
 /** Parse "owner/repo#123" or a canonical PR URL into its parts. */
 export function parsePr(input: string): ParsedPr | null {
   const s = input.trim();
@@ -388,11 +446,21 @@ export interface CancelSelector {
   prKey?: string;
 }
 
-/** Cancel a PR's running convergence instance and mark it abandoned. Terminating the engine
- * instance emits no completion event (no worker runs), so the app-tier flips the PR's status
- * here — the same place ADR 0040 puts app-owned rest state. Accepts either selector; a PR
- * already in a terminal state is left untouched so a stale cancel can't overwrite a `converged`
- * outcome with `abandoned`. */
+/** Cancel a run and mark its read-model row abandoned. Two paths converge here:
+ *
+ *  - **Tracked PR** (a `pull_requests` row): the engine instance is terminated (which emits no
+ *    completion event — no worker runs) and this function flips the PR row to `abandoned`
+ *    *synchronously*. The immediacy matters: the agent-abort capability (`app/abandon.ts`) derives
+ *    `abandoned` straight off `pull_requests.status`, so a deferred write would widen the
+ *    check-then-push window a side-effecting agent races against.
+ *  - **Any other instance** (e.g. the cancel button on an Epic/plan row, which POSTs the row's
+ *    `process_key`): the instance is terminated here, and the declarative `instanceTracking`
+ *    reconciler (`nano.app.json`) flips the owning row (`plans`) to abandoned on its next poll.
+ *    That same reconciler is also the safety net for terminations that never reach this function
+ *    at all — an operator terminating the instance directly, or a crash.
+ *
+ * Accepts either selector; a PR already in a terminal state is left untouched so a stale cancel
+ * can't overwrite a `converged` outcome with `abandoned`. */
 export async function cancelRun(data: DataLayer, engine: EngineClient, selector: CancelSelector) {
   const { processInstanceKey, prKey } = selector;
   const table = prs(data);
@@ -423,6 +491,14 @@ export async function cancelRun(data: DataLayer, engine: EngineClient, selector:
     });
     return { ok: true, prKey: pr.pr_key };
   }
+  // No tracked PR for this key. If we were handed a raw instance key (e.g. the cancel button
+  // on an Epic/plan row, which POSTs the row's `process_key`), the instance has still been
+  // terminated above — the declarative `instanceTracking` reconciler (nano.app.json) flips the
+  // owning row (`plans`) to abandoned on its next poll. Report success so the UI does not
+  // surface a misleading 404 for a cancel that actually took effect.
+  if (instanceKey) {
+    return { ok: true, processInstanceKey: instanceKey };
+  }
   return { ok: false, kind: "not_found", reason: "no PR for that selector" };
 }
 

package/deno.json

@@ -6,7 +6,7 @@
     ]
   },
   "imports": {
-    "@nanobpm/urban": "npm:@nanobpm/urban@^0.28.0"
+    "@nanobpm/urban": "npm:@nanobpm/urban@^0.29.0"
   },
   "tasks": {
     "start": "deno run --allow-net --allow-read --allow-write --allow-run=gh --allow-env main.ts",

package/deno.lock

@@ -3,7 +3,7 @@
   "specifiers": {
     "jsr:@std/assert@1": "1.0.19",
     "jsr:@std/internal@^1.0.12": "1.0.14",
-    "npm:@nanobpm/urban@0.28": "0.28.0",
+    "npm:@nanobpm/urban@0.29": "0.29.0",
     "npm:@semantic-release/changelog@^6.0.3": "6.0.3_semantic-release@24.2.9__typescript@5.9.3_typescript@5.9.3",
     "npm:@semantic-release/git@^10.0.1": "10.0.1_semantic-release@24.2.9__typescript@5.9.3_typescript@5.9.3",
     "npm:@semantic-release/npm@^13.1.5": "13.1.5_semantic-release@24.2.9__typescript@5.9.3",
@@ -67,8 +67,8 @@
     "@colors/colors@1.5.0": {
       "integrity": "sha512-ooWCrlZP11i8GImSjTHYHLkvFDP48nS4+204nGb1RiX/WXYHmJA2III9/e2DWVabCESdW7hBAEzHRqUn9OUVvQ=="
     },
-    "@nanobpm/nano-app-schema@0.3.0": {
-      "integrity": "sha512-bz7wqYsfetcSMYIMW2e1rmbE2k844TCtXWwBd+uVV/s3iRsi09Ff0WMaBEZWuvBPopwHhD2JATCNCXdEBULjfA==",
+    "@nanobpm/nano-app-schema@0.4.0": {
+      "integrity": "sha512-/1rXzXVDVglqjNoqrxJ0FjBUKqej3q8R+/3xXXU3cdwRO9QKwDkd3/2K+I0gS1bAiqNI8SWZiH9+pkKiT7I8wQ==",
       "dependencies": [
         "bpmn-moddle@9.0.4",
         "dmn-moddle",
@@ -82,8 +82,8 @@
         "ws"
       ]
     },
-    "@nanobpm/urban@0.28.0": {
-      "integrity": "sha512-rhzgOV+Vb1CPuNoVHVX3OtxjHqzSp2gJIV2pi3EBi245ZjDRN0gSoPGd/MEnJdufxgWwDKuvhyljRDHE8T957w==",
+    "@nanobpm/urban@0.29.0": {
+      "integrity": "sha512-79CMeYpfnPmKSF2x7zRJ6ZcmAimOknCxySFXvg2z0JtS/pTGlUvkzZy87xp5jHB88LZdKsUIuvVnN5hnZKdS+g==",
       "dependencies": [
         "@nanobpm/nano-app-schema",
         "@nanobpm/nano-sdk",
@@ -1757,11 +1757,11 @@
   },
   "workspace": {
     "dependencies": [
-      "npm:@nanobpm/urban@0.28"
+      "npm:@nanobpm/urban@0.29"
     ],
     "packageJson": {
       "dependencies": [
-        "npm:@nanobpm/urban@0.28",
+        "npm:@nanobpm/urban@0.29",
         "npm:@semantic-release/changelog@^6.0.3",
         "npm:@semantic-release/git@^10.0.1",
         "npm:@semantic-release/npm@^13.1.5",

package/nano.app.json

@@ -22,6 +22,43 @@
       }
     }
   },
+  "instanceTracking": [
+    {
+      "table": "pull_requests",
+      "keyField": "process_key",
+      "statusField": "status",
+      "activeStatuses": [
+        "converging",
+        "waiting_review",
+        "escalated",
+        "waiting_deps",
+        "waiting_merge",
+        "waiting_lane",
+        "queued",
+        "merging"
+      ],
+      "onTerminated": {
+        "set": {
+          "status": "abandoned",
+          "open_escalation_id": null,
+          "open_escalation_question": null
+        }
+      },
+      "pollMs": 5000
+    },
+    {
+      "table": "plans",
+      "keyField": "process_key",
+      "statusField": "status",
+      "activeStatuses": ["planning", "dispatched"],
+      "onTerminated": {
+        "set": {
+          "status": "abandoned"
+        }
+      },
+      "pollMs": 5000
+    }
+  ],
   "workers": [
     {
       "taskType": "pr.persist-round",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.32.0",
+  "version": "0.32.2",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",
@@ -40,7 +40,7 @@
     "test": "deno test -A"
   },
   "dependencies": {
-    "@nanobpm/urban": "^0.28.0"
+    "@nanobpm/urban": "^0.29.0"
   },
   "devDependencies": {
     "@semantic-release/changelog": "^6.0.3",

package/workers/finalize/worker.ts

@@ -2,7 +2,8 @@
 // merge stage (start the `merge-loop` process and park the PR in `waiting_deps`) when auto-merge
 // is on, or (b) close the PR out as `converged` (review-only mode).
 import type { AppJobHandler } from "@nanobpm/urban";
-import { AUTO_MERGE, startMerge } from "../../app/service.ts";
+import { AUTO_MERGE, ensurePr, startMerge } from "../../app/service.ts";
+import { abandonTokenFromUrl } from "../../app/abandon.ts";
 import { maybeStartRetro } from "../../app/retro.ts";
 
 // Extends Record so the declared fields are typed while the job may still carry
@@ -14,6 +15,9 @@ interface In extends Record<string, unknown> {
   prUrl: string;
   round: number;
   summary?: string;
+  // The per-PR abandon capability URL the agent was handed; its token is preserved on a heal so
+  // the agent's cooperative-abort check keeps resolving (see ensurePr).
+  abandonUrl?: string;
 }
 
 const AGENT_RESULT_KEY = "io.nanobpm.agentResult";
@@ -26,9 +30,19 @@ const handler: AppJobHandler<In> = async (job, app) => {
   // `summary` is left undefined when absent so the write boundary omits it: the
   // nullable `rounds.summary` stays NULL and `pull_requests.outcome` is untouched
   // rather than being coerced to "".
-  const { prKey, repo, prNumber, prUrl, round, summary } = job.variables;
+  const { prKey, repo, prNumber, prUrl, round, summary, abandonUrl } = job.variables;
   const now = new Date().toISOString();
 
+  // Heal a missing FK parent (engine/app.db desync) before the child `rounds` insert.
+  await ensurePr(app.data, {
+    prKey,
+    repo,
+    number: prNumber,
+    url: prUrl,
+    round,
+    abandonToken: abandonTokenFromUrl(abandonUrl),
+  });
+
   await app.data.table("rounds", "id").insert({
     pr_key: prKey,
     round_no: round,

package/workers/merge/worker.ts

@@ -10,7 +10,8 @@
 // shapes the escalation payload on a block.
 import type { AppJobHandler } from "@nanobpm/urban";
 import { enqueueViaComment, mergePr } from "../../app/github.ts";
-import { MERGE_ADMIN, MERGE_METHOD } from "../../app/service.ts";
+import { MERGE_ADMIN, MERGE_METHOD, ensurePr } from "../../app/service.ts";
+import { abandonTokenFromUrl } from "../../app/abandon.ts";
 import { loadMergeProtocol } from "../../app/mergeProtocol.ts";
 import { checkBaseTarget } from "../../app/baseGuard.ts";
 
@@ -18,6 +19,12 @@ interface In extends Record<string, unknown> {
   prKey: string;
   repo: string;
   prNumber: number;
+  // Carried by the merge-loop instance (startMerge sets it to the converged round); passed to
+  // the heal so a reconstructed row reflects the real round, not a 1-based default.
+  round?: number;
+  // The per-PR abandon capability URL the agent was handed; its token is preserved on a heal so
+  // the agent's cooperative-abort check keeps resolving (see ensurePr).
+  abandonUrl?: string;
 }
 
 interface Out extends Record<string, unknown> {
@@ -27,10 +34,23 @@ interface Out extends Record<string, unknown> {
 }
 
 const handler: AppJobHandler<In, Out> = async (job, app) => {
-  const { prKey, repo, prNumber } = job.variables;
+  const { prKey, repo, prNumber, round, abandonUrl } = job.variables;
   const token = process.env.GITHUB_TOKEN ?? "";
   const now = new Date().toISOString();
 
+  // Heal a missing FK parent (engine/app.db desync) before any child `merges` insert below so a
+  // land attempt never dies with an opaque `FOREIGN KEY constraint failed` incident. The merge-loop
+  // instance carries repo+prNumber (and the converged round) but not prUrl; ensurePr derives the
+  // canonical URL from them, keeps the healed round faithful, and preserves the agent's abandon
+  // token so its cooperative-abort check keeps resolving.
+  await ensurePr(app.data, {
+    prKey,
+    repo,
+    number: prNumber,
+    round,
+    abandonToken: abandonTokenFromUrl(abandonUrl),
+  });
+
   // Dead-end-base guard (#60): never land a PR into a base branch that has itself already merged
   // to the default branch — the merge would land into a dead branch and never reach `main`.
   // GitHub only auto-retargets a PR when its base is *deleted* on merge; a merged-but-undeleted

package/workers/persist-escalation/worker.ts

@@ -3,6 +3,8 @@
 // and the MAX_ROUNDS guard (status = blocked, question set by the process). Returns
 // `escalationId` for the UI.
 import type { AppJobHandler } from "@nanobpm/urban";
+import { ensurePr, parsePr } from "../../app/service.ts";
+import { abandonTokenFromUrl } from "../../app/abandon.ts";
 
 // Extends Record so the declared fields are typed while the job may still carry
 // other process variables (e.g. io.nanobpm.agentResult, read by transcriptOf).
@@ -12,6 +14,14 @@ interface In extends Record<string, unknown> {
   status?: string;
   summary?: string;
   question?: string;
+  // Carried by the convergence-loop instance so a missing `pull_requests` parent can be
+  // reconstructed before the FK-child `rounds`/`escalations` inserts.
+  repo?: string;
+  prNumber?: number;
+  prUrl?: string;
+  // The per-PR abandon capability URL the agent was handed; its token is preserved on a heal so
+  // the agent's cooperative-abort check keeps resolving (see ensurePr).
+  abandonUrl?: string;
   // False on the "review stalled" arm: `persist-round` already recorded this `round` as
   // `addressed`, so this escalation must not insert a second `rounds` row for the same
   // `pr_key`/`round_no` (which would record one round as both addressed and blocked). Absent
@@ -52,7 +62,7 @@ function fabricateQuestion(rawStatus: string | undefined, hasTranscript: boolean
 }
 
 const handler: AppJobHandler<In> = async (job, app) => {
-  const { prKey, round, summary } = job.variables;
+  const { prKey, round, summary, repo, prNumber, prUrl, abandonUrl } = job.variables;
   // `status` drives the escalation kind (control flow); a blank/absent status is an
   // unclassified escalation -> a question needing input. `question` is denormalised
   // onto pull_requests below and bound by the UI answer form, so it must be a
@@ -71,6 +81,25 @@ const handler: AppJobHandler<In> = async (job, app) => {
   const kind = status === "needs_input" ? "question" : "blocker";
   const now = new Date().toISOString();
 
+  // Heal a missing FK parent (engine/app.db desync) before the child `rounds`/`escalations`
+  // inserts so this never dies with an opaque `FOREIGN KEY constraint failed` incident. Prefer
+  // the carried repo/prNumber; if either is missing (an older in-flight instance, or a
+  // process-variable regression) fall back to parsing them out of the canonical `owner/repo#N`
+  // prKey so the heal still runs.
+  const parsed = parsePr(prKey);
+  const healRepo = repo ?? parsed?.repo;
+  const healNumber = typeof prNumber === "number" ? prNumber : parsed?.number;
+  if (healRepo && typeof healNumber === "number") {
+    await ensurePr(app.data, {
+      prKey,
+      repo: healRepo,
+      number: healNumber,
+      url: prUrl,
+      round,
+      abandonToken: abandonTokenFromUrl(abandonUrl),
+    });
+  }
+
   // Skip the round insert when the caller already recorded this round (the "review stalled"
   // arm runs after `persist-round`): re-inserting would duplicate the `pr_key`/`round_no` row.
   if (job.variables.recordRound !== false) {

package/workers/persist-round/worker.ts

@@ -5,6 +5,8 @@
 // Data access goes through the injected app datasource gateway (`app.data.table<T>`), the RAD
 // `Table<T>` surface — `rounds.insert(...)` / `pull_requests.update(...)`, not hand-written SQL.
 import type { AppJobHandler } from "@nanobpm/urban";
+import { ensurePr, parsePr } from "../../app/service.ts";
+import { abandonTokenFromUrl } from "../../app/abandon.ts";
 
 // Extends Record so the declared fields are typed while the job may still carry
 // other process variables (e.g. io.nanobpm.agentResult, read by transcriptOf).
@@ -13,6 +15,14 @@ interface In extends Record<string, unknown> {
   round: number;
   status?: string;
   summary?: string;
+  // Carried by the convergence-loop instance (set at createInstance) so a missing
+  // `pull_requests` parent can be reconstructed before the FK-child `rounds` insert.
+  repo?: string;
+  prNumber?: number;
+  prUrl?: string;
+  // The per-PR abandon capability URL the review agent was handed; its token is preserved on a
+  // heal so the agent's cooperative-abort check keeps resolving (see ensurePr).
+  abandonUrl?: string;
 }
 
 // The harness records the agent's full (byte-capped) stdout on the result envelope; keep it
@@ -27,9 +37,28 @@ const handler: AppJobHandler<In> = async (job, app) => {
   // This worker is the "addressed"/"waiting" path, so `status` resolves to one of those
   // domain values. `summary` is left undefined when absent: the write boundary omits it so the
   // nullable `rounds.summary` column stays NULL rather than being coerced to "".
-  const { prKey, round, status = "addressed", summary } = job.variables;
+  const { prKey, round, status = "addressed", summary, repo, prNumber, prUrl, abandonUrl } = job.variables;
   const now = new Date().toISOString();
 
+  // Heal a missing FK parent (engine/app.db desync) before the child `rounds` insert so this
+  // never dies with an opaque `FOREIGN KEY constraint failed` incident. Prefer the carried
+  // repo/prNumber; if either is missing (an older in-flight instance, or a process-variable
+  // regression) fall back to parsing them out of the canonical `owner/repo#N` prKey so the heal
+  // still runs.
+  const parsed = parsePr(prKey);
+  const healRepo = repo ?? parsed?.repo;
+  const healNumber = typeof prNumber === "number" ? prNumber : parsed?.number;
+  if (healRepo && typeof healNumber === "number") {
+    await ensurePr(app.data, {
+      prKey,
+      repo: healRepo,
+      number: healNumber,
+      url: prUrl,
+      round,
+      abandonToken: abandonTokenFromUrl(abandonUrl),
+    });
+  }
+
   await app.data.table("rounds", "id").insert({
     pr_key: prKey,
     round_no: round,