@nanobpm/nano-workforce 0.31.0 → 0.32.1

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [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)
+
+
+### Features
+
+* **poller:** surface technical incidents on the PR row ([#95](https://github.com/nanobpm/nano-workforce/issues/95)) ([596153c](https://github.com/nanobpm/nano-workforce/commit/596153c0f58a0d511f4a7bac66896dab98a6a5c8)), closes [#94](https://github.com/nanobpm/nano-workforce/issues/94)
+
 # [0.31.0](https://github.com/nanobpm/nano-workforce/compare/v0.30.0...v0.31.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,13 +6,14 @@
 // 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 { submitPr } from "./service.ts";
+import { cancelRun, pollIncidentsImpl, submitPr } from "./service.ts";
 
 // deno-lint-ignore no-explicit-any
 function memTable(rows: any[], key: string) {
   return {
     // deno-lint-ignore no-explicit-any
     get: (k: any) => Promise.resolve(rows.find((r) => r[key] === k) ?? null),
+    all: () => Promise.resolve([...rows]),
     // deno-lint-ignore no-explicit-any
     find: (q: any) =>
       Promise.resolve(rows.filter((r) => Object.entries(q).every(([f, v]) => r[f] === v))),
@@ -99,3 +100,228 @@ Deno.test("re-submit of a cancelled PR clears stale open escalations + the denor
     assertEquals(pr.process_key, "PI-9");
   });
 });
+
+// Red/green regression for technical-incident surfacing (issue #94). A convergence/merge instance
+// can hit an engine incident that parks the token; until `pollIncidents` nothing on the PR row
+// reflected it, so the grid kept showing "converging" while the run was dead in the water. This
+// drives the pass's reconciliation core against a stubbed `/v2/incidents/search`:
+//   1. an ACTIVE incident is mirrored onto `incident_key` + `incident_message` (status untouched),
+//   2. once the engine reports no active incident, the columns are cleared idempotently,
+//   3. a PR with no live instance (no process_key / terminal status) is never queried and any
+//      stale incident on it is cleared.
+function incidentFetch(byInstance: Record<string, unknown[]>) {
+  return (url: string | URL | Request, init?: RequestInit): Promise<Response> => {
+    const u = typeof url === "string" ? url : url.toString();
+    if (!u.endsWith("/incidents/search")) {
+      throw new Error(`unexpected fetch: ${u}`);
+    }
+    const body = JSON.parse(String(init?.body ?? "{}")) as {
+      filter?: { processInstanceKey?: string };
+    };
+    const items = byInstance[body.filter?.processInstanceKey ?? ""] ?? [];
+    return Promise.resolve(
+      new Response(JSON.stringify({ items }), { status: 200, headers: { "content-type": "application/json" } }),
+    );
+  };
+}
+
+Deno.test("pollIncidents mirrors an ACTIVE incident onto the PR row, then clears it, leaving status untouched", async () => {
+  const row = {
+    pr_key: "owner/repo#7",
+    repo: "owner/repo",
+    number: 7,
+    status: "converging",
+    process_key: "PI-7",
+    incident_key: null as string | null,
+    incident_message: null as string | null,
+    updated_at: "t0",
+  };
+  const stores: Record<string, { rows: unknown[]; key: string }> = {
+    pull_requests: { rows: [row], 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 headers = { "content-type": "application/json" };
+
+  const prevFetch = globalThis.fetch;
+
+  // Red-ish: with an ACTIVE incident on the instance, the pass must surface it (before this
+  // feature the columns stayed null and the incident was invisible).
+  globalThis.fetch = incidentFetch({
+    "PI-7": [{ incidentKey: "INC-1", errorMessage: "boom: unhandled error", state: "ACTIVE", creationTime: "2024-01-01T00:00:00Z" }],
+  }) as typeof fetch;
+  try {
+    await pollIncidentsImpl(data, "http://engine/v2", headers);
+  } finally {
+    globalThis.fetch = prevFetch;
+  }
+  assertEquals(row.incident_key, "INC-1");
+  assertEquals(row.incident_message, "boom: unhandled error");
+  assertEquals(row.status, "converging"); // orthogonal: status is never touched
+
+  // Green: once the engine reports no active incident, the columns clear idempotently.
+  globalThis.fetch = incidentFetch({ "PI-7": [] }) as typeof fetch;
+  try {
+    await pollIncidentsImpl(data, "http://engine/v2", headers);
+  } finally {
+    globalThis.fetch = prevFetch;
+  }
+  assertEquals(row.incident_key, null);
+  assertEquals(row.incident_message, null);
+  assertEquals(row.status, "converging");
+});
+
+Deno.test("pollIncidents never queries a PR with no live instance and clears any stale incident", async () => {
+  const noKey = {
+    pr_key: "owner/repo#8",
+    status: "converging",
+    process_key: null as string | null,
+    incident_key: "STALE-A",
+    incident_message: "left over",
+    updated_at: "t0",
+  };
+  const terminal = {
+    pr_key: "owner/repo#9",
+    status: "merged",
+    process_key: "PI-9",
+    incident_key: "STALE-B",
+    incident_message: "left over",
+    updated_at: "t0",
+  };
+  const stores: Record<string, { rows: unknown[]; key: string }> = {
+    pull_requests: { rows: [noKey, terminal], 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 headers = { "content-type": "application/json" };
+
+  const prevFetch = globalThis.fetch;
+  // Any fetch here is a bug — neither PR has a live instance to inspect.
+  globalThis.fetch = (() => {
+    throw new Error("pollIncidents must not query a PR with no live instance");
+  }) as typeof fetch;
+  try {
+    await pollIncidentsImpl(data, "http://engine/v2", headers);
+  } finally {
+    globalThis.fetch = prevFetch;
+  }
+  assertEquals(noKey.incident_key, null);
+  assertEquals(noKey.incident_message, null);
+  assertEquals(terminal.incident_key, null);
+  assertEquals(terminal.incident_message, null);
+});
+
+Deno.test("pollIncidents picks the oldest incident by creationTime, sorting a missing timestamp last", async () => {
+  const row = {
+    pr_key: "owner/repo#11",
+    status: "converging",
+    process_key: "PI-11",
+    incident_key: null as string | null,
+    incident_message: null as string | null,
+    updated_at: "t0",
+  };
+  const stores: Record<string, { rows: unknown[]; key: string }> = {
+    pull_requests: { rows: [row], 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 headers = { "content-type": "application/json" };
+
+  const prevFetch = globalThis.fetch;
+  // A no-`creationTime` incident must not masquerade as the oldest (empty-string sort bug): the
+  // real earliest ISO timestamp wins even when a timestamp-less incident is returned first.
+  globalThis.fetch = incidentFetch({
+    "PI-11": [
+      { incidentKey: "INC-NOTS", errorMessage: "no timestamp", state: "ACTIVE" },
+      { incidentKey: "INC-OLD", errorMessage: "the first fault", state: "ACTIVE", creationTime: "2024-01-01T00:00:00Z" },
+      { incidentKey: "INC-NEW", errorMessage: "a later fault", state: "ACTIVE", creationTime: "2024-06-01T00:00:00Z" },
+    ],
+  }) as typeof fetch;
+  try {
+    await pollIncidentsImpl(data, "http://engine/v2", headers);
+  } finally {
+    globalThis.fetch = prevFetch;
+  }
+  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

@@ -130,6 +130,13 @@ interface PullRequest {
   // running agent curls (GET /hooks/abandon?token=…) to learn whether this run was cancelled before
   // it performs a side effect. Minted at submit, reused across the convergence + merge instances.
   abandon_token: string | null;
+  // Technical-incident surfacing (017_pr_incident.sql, issue #94), written by the poller's
+  // `pollIncidents` pass. `incident_key` is the engine incidentKey of the ACTIVE incident parking
+  // this PR's instance and `incident_message` its errorMessage; both NULL when the instance has no
+  // active incident. Orthogonal to `status` — an incident is a cross-cutting liveness fault, not a
+  // workflow stage.
+  incident_key: string | null;
+  incident_message: string | null;
 }
 
 interface PrDependency {
@@ -381,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);
@@ -416,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" };
 }
 
@@ -836,6 +861,111 @@ async function pollJobActivation(
   }
 }
 
+/** The subset of a Camunda-8 `/v2/incidents/search` result item this app reads. `incidentKey` is
+ * the unique incident id; `errorMessage` is the human-readable fault; `state` is the incident
+ * lifecycle (`ACTIVE` while it parks the token, `RESOLVED` once cleared); `creationTime` orders
+ * concurrent incidents. */
+interface IncidentSearchItem {
+  incidentKey?: string;
+  errorMessage?: string | null;
+  state?: string;
+  creationTime?: string | null;
+}
+
+/** Incident-surfacing poll pass (issue #94). A convergence or merge process instance can hit a
+ * *technical* incident — an unhandled engine error that parks the token — and nothing on the PR
+ * row reflected it: the grid kept showing the last workflow status (`converging`, `merging`, …)
+ * while the run was actually dead in the water (a PR sat "converging" all day on an incident).
+ *
+ * This pass reads the engine's Camunda-8 `/v2/incidents/search` for each PR that still has a live
+ * instance (has a `process_key`, non-terminal status) and mirrors an ACTIVE incident onto two
+ * orthogonal columns — `incident_key` + `incident_message` — leaving `status` untouched. An
+ * incident is a cross-cutting liveness fault, not a workflow stage, so it must not overload the
+ * status machine. Clearing is idempotent: when the instance has no active incident (resolved, or
+ * never had one) the columns are nulled, so an incident raised or resolved out-of-band converges
+ * to the truth on the next pass. Best-effort transport: a failed query leaves the last-known
+ * values untouched and the next pass retries. Updates (and bumps `updated_at`) only on an actual
+ * change so a steady state doesn't churn the grid. */
+async function pollIncidents(
+  data: DataLayer,
+  restAddress: string,
+  engineToken: string | undefined,
+) {
+  const base = restAddress.replace(/\/+$/, "");
+  const headers: Record<string, string> = { "content-type": "application/json" };
+  if (engineToken) headers.authorization = `Bearer ${engineToken}`;
+  await pollIncidentsImpl(data, base, headers);
+}
+
+/** Testable core of {@link pollIncidents}: given the normalised `base` URL and prepared auth
+ * `headers`, reconcile every PR row against the engine's active incidents. Split out so tests can
+ * exercise the reconciliation with a stubbed `fetch` without re-deriving transport wiring. */
+export async function pollIncidentsImpl(
+  data: DataLayer,
+  base: string,
+  headers: Record<string, string>,
+) {
+  const all = await prs(data).all();
+  for (const pr of all) {
+    // No live instance to inspect (never created, mid-transition, or terminal — the run has
+    // finished or was given up, so its instance is gone) → make sure no stale incident lingers on
+    // the row, then move on. Reuses the canonical `TERMINAL_STATUSES` so incident logic can't drift
+    // from the rest of the status machine.
+    if (!pr.process_key || TERMINAL_STATUSES.includes(pr.status)) {
+      if (pr.incident_key || pr.incident_message) {
+        await prs(data).update(pr.pr_key, {
+          incident_key: null,
+          incident_message: null,
+          updated_at: now(),
+        });
+      }
+      continue;
+    }
+
+    let incidentKey: string | null = null;
+    let incidentMessage: string | null = null;
+    try {
+      const res = await fetch(`${base}/incidents/search`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({
+          filter: { processInstanceKey: pr.process_key, state: "ACTIVE" },
+          page: { limit: 20 },
+        }),
+      });
+      if (!res.ok) continue; // engine unhappy → keep last-known, retry next pass
+      const body = (await res.json()) as { items?: IncidentSearchItem[] };
+      // Surface the oldest ACTIVE incident (the first thing that broke — a stable choice if the
+      // instance somehow parks more than one). Re-filter on state defensively in case the wire
+      // filter is ignored. An incident with no `creationTime` sorts *last*, so a missing timestamp
+      // can never masquerade as the oldest.
+      const active = (body.items ?? [])
+        .filter((i) => (i.state ?? "ACTIVE") === "ACTIVE")
+        .sort((a, b) =>
+          (a.creationTime ?? "\uffff").localeCompare(b.creationTime ?? "\uffff")
+        )[0];
+      if (active) {
+        incidentKey = active.incidentKey ?? null;
+        incidentMessage = active.errorMessage ?? null;
+      }
+    } catch (err) {
+      console.error(`[poller] incidents ${pr.pr_key}: ${err}`);
+      continue;
+    }
+
+    if (
+      incidentKey !== (pr.incident_key ?? null) ||
+      incidentMessage !== (pr.incident_message ?? null)
+    ) {
+      await prs(data).update(pr.pr_key, {
+        incident_key: incidentKey,
+        incident_message: incidentMessage,
+        updated_at: now(),
+      });
+    }
+  }
+}
+
 /** Wave-merge barrier poll pass. After `record-wave` hands off a wave that has a successor, the
  * plan-fanout instance parks at the `wait-wave-merged` catch event and `plans.gate_wave` records
  * that wave's index. Here we check whether every OPENED PR in that wave has MERGED and, if so,
@@ -879,9 +1009,9 @@ async function pollWaveGates(data: DataLayer, engine: EngineClient, token: strin
   }
 }
 
-/** One full poll pass: advance the review stage, the merge stage, and (when the engine REST
- * endpoint is supplied) the job-activation visibility pass. Called on the self-scheduling loop
- * in `main.ts`. */
+/** One full poll pass: advance the review stage, the merge stage, the wave-merge barrier, and
+ * (when the engine REST endpoint is supplied) the job-activation visibility pass and the
+ * technical-incident surfacing pass. Called on the self-scheduling loop in `main.ts`. */
 export async function pollOnce(
   data: DataLayer,
   engine: EngineClient,
@@ -891,5 +1021,8 @@ export async function pollOnce(
   await pollReviews(data, engine, token);
   await pollMerges(data, engine, token);
   await pollWaveGates(data, engine, token);
-  if (engineRest) await pollJobActivation(data, engineRest.restAddress, engineRest.token);
+  if (engineRest) {
+    await pollJobActivation(data, engineRest.restAddress, engineRest.token);
+    await pollIncidents(data, engineRest.restAddress, engineRest.token);
+  }
 }

package/db/migrations/017_pr_incident.sql

@@ -0,0 +1,14 @@
+-- Technical-incident surfacing (issue #94). A convergence or merge process instance can hit a
+-- *technical* incident — an unhandled engine error (an expression failure, a job that exhausted
+-- its retries, …) that parks the token — and until now nothing on the PR row reflected it: the
+-- grid kept showing the last workflow status (`converging`, `merging`, …) while the run was
+-- actually stuck. A PR sat "converging" all day while its instance was dead on an incident.
+--
+-- These two orthogonal columns mirror an ACTIVE engine incident onto the PR row, written by the
+-- poller's `pollIncidents` pass from a `/v2/incidents/search` filtered by the PR's `process_key`.
+-- They are deliberately independent of `status`: an incident is a *cross-cutting* liveness fault,
+-- not a workflow stage, so surfacing it must not overload the status machine. NULL means the
+-- instance has no active incident (never had one, or it was resolved) — the poller clears the
+-- columns idempotently, so an incident raised or resolved out-of-band converges on the next pass.
+ALTER TABLE pull_requests ADD COLUMN incident_key TEXT;      -- engine incidentKey of the active incident parking this PR's instance; NULL when none
+ALTER TABLE pull_requests ADD COLUMN incident_message TEXT;  -- the incident's errorMessage, surfaced on the grid; NULL when none

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.31.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",

package/pages/home.page.json

@@ -84,6 +84,7 @@
         "columns": [
           { "field": "pr_key", "header": "PR", "linkField": "url" },
           { "field": "status", "header": "Status" },
+          { "field": "incident_message", "header": "Incident" },
           { "field": "current_round", "header": "Round" },
           { "field": "active_worker", "header": "Agent" },
           { "field": "updated_at", "header": "Updated" }
@@ -103,6 +104,8 @@
             { "field": "number", "label": "PR number" },
             { "field": "active_worker", "label": "Agent (leasing worker)" },
             { "field": "lease_until", "label": "Activation lease until" },
+            { "field": "incident_message", "label": "Incident" },
+            { "field": "incident_key", "label": "Incident key" },
             { "field": "merged_at", "label": "Merged at" },
             { "field": "outcome", "label": "Outcome" }
           ],