@nanobpm/nano-workforce 0.32.0 → 0.32.1

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+## [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/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/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

@@ -388,11 +388,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 +433,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.1",
   "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",