@nanobpm/nano-workforce 0.31.0 → 0.32.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [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/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 { 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,154 @@ 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");
+});

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 {
@@ -836,6 +843,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 +991,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 +1003,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.31.0",
+  "version": "0.32.0",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",

package/pages/home.page.json

@@ -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" }
           ],