@nanobpm/nano-workforce 0.30.0 → 0.32.0

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.30.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/epic.page.json

@@ -23,7 +23,7 @@
       "type": "text",
       "id": "subtitle",
       "props": {
-        "text": "Read-only observability over each plan's wave state, merge-exclusion graph, coordination notes, and trial-merge gate results.",
+        "text": "Read-only observability over each plan's review trace, wave state, merge-exclusion graph, coordination notes, and trial-merge gate results.",
         "variant": "sub"
       }
     },
@@ -70,6 +70,27 @@
         }
       }
     },
+    {
+      "type": "dataGrid",
+      "id": "plan-reviews",
+      "props": {
+        "title": "Plan review trace",
+        "refreshMs": 5000,
+        "data": {
+          "kind": "datasource",
+          "source": "app",
+          "table": "plan_reviews",
+          "orderBy": { "field": "round", "dir": "asc" }
+        },
+        "columns": [
+          { "field": "plan_key", "header": "Plan" },
+          { "field": "round", "header": "Round" },
+          { "field": "approved", "header": "Approved? (1/0)" },
+          { "field": "findings", "header": "Reviewer findings" },
+          { "field": "created_at", "header": "Recorded" }
+        ]
+      }
+    },
     {
       "type": "dataGrid",
       "id": "wave-state",

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" }
           ],
@@ -228,6 +231,20 @@
                 { "field": "summary", "header": "Summary" }
               ]
             },
+            {
+              "title": "Plan reviews",
+              "source": "app",
+              "table": "plan_reviews",
+              "parentField": "plan_key",
+              "childField": "plan_key",
+              "orderBy": { "field": "round", "dir": "asc" },
+              "columns": [
+                { "field": "round", "header": "Round" },
+                { "field": "approved", "header": "Approved? (1/0)" },
+                { "field": "findings", "header": "Reviewer findings" },
+                { "field": "created_at", "header": "Recorded" }
+              ]
+            },
             {
               "title": "Escalations",
               "source": "app",

package/resources/processes/plan-fanout.bpmn

@@ -216,7 +216,7 @@
     <bpmn:sequenceFlow id="f_toRecordPlanReview" sourceRef="review-plan" targetRef="record-plan-review" />
     <bpmn:sequenceFlow id="f_toGwPlanReview" sourceRef="record-plan-review" targetRef="gw-plan-review" />
     <bpmn:sequenceFlow id="f_plan_proceed" name="approved" sourceRef="gw-plan-review" targetRef="select-wave">
-      <bpmn:conditionExpression xsi:type="bpmn:tFormalExpression">=planApproved or reviewExhausted</bpmn:conditionExpression>
+      <bpmn:conditionExpression xsi:type="bpmn:tFormalExpression">=planApproved</bpmn:conditionExpression>
     </bpmn:sequenceFlow>
     <bpmn:sequenceFlow id="f_plan_revise" name="revise" sourceRef="gw-plan-review" targetRef="plan" />
     <bpmn:sequenceFlow id="f_toImplement" sourceRef="select-wave" targetRef="implement" />

package/scripts/pages-contract.test.ts

@@ -0,0 +1,228 @@
+// Static contract guard between the declarative pages (`pages/*.page.json`) and the app schema
+// (`db/migrations/*.sql`).
+//
+// The Urban page runtime whitelists every datasource `table` and `column` against the LIVE schema
+// (`PRAGMA table_info`): a grid that binds to a table or column the migrations never created 400s
+// at request time — an invisible, runtime-only failure with no compile or `urban check` signal.
+// This test closes that drift surface: every table and column referenced by any page must be
+// derivable from the migrations, so a rename/typo/removed column fails CI instead of a live page.
+//
+// It also pins the issue #87 surfaces: the plan-review audit log (`plan_reviews`) — which is
+// persisted but was surfaced on no page — must appear on the epic page (flat grid) and inside the
+// home page's plan detail (child grid). Feature coverage so the trace can't silently regress out.
+import { assert } from "jsr:@std/assert@1";
+
+// Percent-decode the pathname: `new URL(..).pathname` can contain encoded characters (e.g. a space
+// as `%20`), which `Deno.readDir`/`readTextFile` would fail to resolve. Matches the repo convention
+// (see scripts/check-agent-prompts.test.ts).
+const ROOT = decodeURIComponent(new URL("../", import.meta.url).pathname);
+
+// ---- migrations -> { table -> Set<column> } -----------------------------------------------------
+
+function parseSchema(sql: string, schema: Map<string, Set<string>>): void {
+  // Strip SQL comments first: an inline `-- ...` trailing one column line would otherwise become
+  // the leading token of the NEXT comma-split fragment, hiding the real column name.
+  sql = sql.replace(/--[^\n]*/g, "").replace(/\/\*[\s\S]*?\*\//g, "");
+  // CREATE TABLE [IF NOT EXISTS] <name> ( <body> )
+  const createRe = /CREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?["`]?(\w+)["`]?\s*\(/gi;
+  let m: RegExpExecArray | null;
+  while ((m = createRe.exec(sql)) !== null) {
+    const table = m[1];
+    const body = balancedBody(sql, createRe.lastIndex - 1); // start at the "("
+    if (body === null) continue;
+    const cols = schema.get(table) ?? new Set<string>();
+    for (const frag of splitTopLevel(body)) {
+      const first = frag.trim().split(/[\s(]/)[0];
+      if (!first) continue;
+      const upper = first.toUpperCase();
+      if (["PRIMARY", "FOREIGN", "UNIQUE", "CHECK", "CONSTRAINT"].includes(upper)) continue;
+      cols.add(first.replace(/["`]/g, ""));
+    }
+    schema.set(table, cols);
+  }
+  // ALTER TABLE <name> ADD [COLUMN] <col>
+  const alterRe = /ALTER\s+TABLE\s+["`]?(\w+)["`]?\s+ADD\s+(?:COLUMN\s+)?["`]?(\w+)["`]?/gi;
+  while ((m = alterRe.exec(sql)) !== null) {
+    const cols = schema.get(m[1]) ?? new Set<string>();
+    cols.add(m[2]);
+    schema.set(m[1], cols);
+  }
+}
+
+// Return the text inside the parentheses whose opener is at `openIdx`, honouring nesting.
+function balancedBody(s: string, openIdx: number): string | null {
+  let depth = 0;
+  for (let i = openIdx; i < s.length; i++) {
+    if (s[i] === "(") depth++;
+    else if (s[i] === ")") {
+      depth--;
+      if (depth === 0) return s.slice(openIdx + 1, i);
+    }
+  }
+  return null;
+}
+
+// Split a CREATE TABLE body on top-level commas (commas inside nested parens stay attached).
+function splitTopLevel(body: string): string[] {
+  const out: string[] = [];
+  let depth = 0, start = 0;
+  for (let i = 0; i < body.length; i++) {
+    const c = body[i];
+    if (c === "(") depth++;
+    else if (c === ")") depth--;
+    else if (c === "," && depth === 0) {
+      out.push(body.slice(start, i));
+      start = i + 1;
+    }
+  }
+  out.push(body.slice(start));
+  return out;
+}
+
+async function loadSchema(): Promise<Map<string, Set<string>>> {
+  const schema = new Map<string, Set<string>>();
+  const files: string[] = [];
+  for await (const e of Deno.readDir(`${ROOT}db/migrations`)) {
+    if (e.isFile && e.name.endsWith(".sql")) files.push(e.name);
+  }
+  files.sort(); // migration order doesn't matter for the union, but keep it deterministic
+  for (const f of files) {
+    parseSchema(await Deno.readTextFile(`${ROOT}db/migrations/${f}`), schema);
+  }
+  return schema;
+}
+
+// ---- pages -> datasource references -------------------------------------------------------------
+
+// deno-lint-ignore no-explicit-any
+type Json = any;
+
+interface Ref {
+  page: string;
+  table: string;
+  source: string;
+  fields: string[]; // every column that must exist on `table` (displayed columns + binding fields)
+  columns: string[]; // only the visibly displayed grid columns (`columns[].field`)
+}
+
+// Pull `field` names out of a `filter` array ([{ field, in/eq/... }, ...]).
+function filterFields(filter: Json): string[] {
+  if (!Array.isArray(filter)) return [];
+  return filter.map((f: Json) => f?.field).filter(Boolean);
+}
+
+function collectRefs(page: string, node: Json, out: Ref[]): void {
+  if (Array.isArray(node)) {
+    for (const v of node) collectRefs(page, v, out);
+    return;
+  }
+  if (!node || typeof node !== "object") return;
+
+  // Top-level datasource grid: the datasource lives at `node.data`, while `columns`, `rowKey`,
+  // `filter`/`tabs`, and `detail` are siblings on the same `node` (the grid props).
+  const data = node.data;
+  if (data && data.kind === "datasource" && typeof data.table === "string") {
+    const columns: string[] = (node.columns ?? []).map((c: Json) => c.field).filter(Boolean);
+    // Every reference that resolves to a column on this table — the runtime 400s on any of them if
+    // it names a column the migrations never created, so all must be guarded, not just displayed
+    // columns. `detail.fields`/`detail.linkField` render columns of the same top-level row.
+    const detail = node.detail ?? {};
+    const fields: string[] = [
+      ...columns,
+      ...(node.columns ?? []).map((c: Json) => c.linkField),
+      node.rowKey,
+      data.orderBy?.field,
+      ...filterFields(data.filter),
+      ...(node.tabs ?? []).flatMap((t: Json) => filterFields(t.filter)),
+      detail.linkField,
+      ...(detail.fields ?? []).flatMap((f: Json) => [f.field, f.linkField]),
+      // `detail.children[].parentField` joins each child grid back to a column on THIS (parent)
+      // table, so a rename/typo there 400s at request time — guard it against the parent schema.
+      ...(detail.children ?? []).map((c: Json) => c.parentField),
+    ].filter(Boolean);
+    out.push({ page, table: data.table, source: data.source ?? "app", fields, columns });
+  }
+
+  // Child grid inside a detail: { table, childField, parentField, orderBy, columns }
+  if (typeof node.table === "string" && typeof node.childField === "string") {
+    const columns: string[] = (node.columns ?? []).map((c: Json) => c.field).filter(Boolean);
+    out.push({
+      page,
+      table: node.table,
+      source: node.source ?? "app",
+      fields: [
+        ...columns,
+        ...(node.columns ?? []).map((c: Json) => c.linkField),
+        node.childField,
+        node.orderBy?.field,
+        node.lazyField?.field,
+      ].filter(Boolean),
+      columns,
+    });
+  }
+
+  for (const v of Object.values(node)) collectRefs(page, v, out);
+}
+
+async function loadRefs(): Promise<Ref[]> {
+  const refs: Ref[] = [];
+  for await (const e of Deno.readDir(`${ROOT}pages`)) {
+    if (!e.isFile || !e.name.endsWith(".page.json")) continue;
+    const page = JSON.parse(await Deno.readTextFile(`${ROOT}pages/${e.name}`));
+    collectRefs(e.name, page, refs);
+  }
+  return refs;
+}
+
+// ---- guards -------------------------------------------------------------------------------------
+
+Deno.test("every page datasource table exists in the migrations", async () => {
+  const schema = await loadSchema();
+  const refs = await loadRefs();
+  assert(refs.length > 0, "no datasource references found — collector or pages are broken");
+  for (const r of refs) {
+    // Only the default app SQLite source is schema-backed; other sources aren't migration-defined.
+    if (r.source !== "app") continue;
+    assert(
+      schema.has(r.table),
+      `${r.page}: datasource table "${r.table}" has no CREATE TABLE in db/migrations/*.sql`,
+    );
+  }
+});
+
+Deno.test("every page datasource column exists on its table", async () => {
+  const schema = await loadSchema();
+  const refs = await loadRefs();
+  for (const r of refs) {
+    if (r.source !== "app") continue;
+    const cols = schema.get(r.table);
+    if (!cols) continue; // table-existence is asserted by the sibling test
+    for (const f of r.fields) {
+      assert(
+        cols.has(f),
+        `${r.page}: column "${f}" referenced on table "${r.table}" is not defined by any migration`,
+      );
+    }
+  }
+});
+
+Deno.test("issue #87: plan_reviews is surfaced on the epic and home pages", async () => {
+  const refs = await loadRefs();
+  const onEpic = refs.some((r) => r.page === "epic.page.json" && r.table === "plan_reviews");
+  const onHome = refs.some((r) => r.page === "home.page.json" && r.table === "plan_reviews");
+  assert(onEpic, "epic.page.json must bind a grid to plan_reviews (plan-review trace)");
+  assert(onHome, "home.page.json plan detail must include a plan_reviews child grid");
+
+  // The trace is only useful with the verdict + critique columns, so pin them. Assert against the
+  // visibly displayed `columns` (not `fields`, which also holds binding refs like orderBy.field) so
+  // a column silently dropped from the grid UI can't pass by being referenced elsewhere.
+  const required = ["round", "approved", "findings"];
+  for (const r of refs.filter((x) => x.table === "plan_reviews")) {
+    for (const col of required) {
+      assert(
+        r.columns.includes(col),
+        `${r.page}: plan_reviews grid must expose the "${col}" column`,
+      );
+    }
+  }
+});

package/workers/record-plan-review/worker.test.ts

@@ -0,0 +1,82 @@
+// Red/green for the plan-review gate (issue #86).
+//
+// Previously the fan-out PROCEEDED when the review-round cap was reached without approval
+// ("proceed regardless rather than dead-lock"). That dispatched an un-vetted plan and — when the
+// plan was empty (e.g. the planner agent couldn't persist its result) — completed the whole epic
+// GREEN having done nothing (instance 21). We now HARD-FAIL: the terminal, unapproved round raises
+// a non-retryable `PLAN_REJECTED` BpmnError (→ incident), so an un-approved plan never dispatches.
+import { assertEquals, assertRejects } from "jsr:@std/assert@1";
+import { BpmnError } from "@nanobpm/urban";
+import handler from "./worker.ts";
+import { MAX_PLAN_REVIEW_ROUNDS, type PlanReview } from "../../app/plan.ts";
+
+function fakeApp(existing: PlanReview[] = []) {
+  const rows: PlanReview[] = [...existing];
+  const match = (r: PlanReview, q: Record<string, unknown>) =>
+    Object.entries(q).every(([f, v]) => (r as unknown as Record<string, unknown>)[f] === v);
+  return {
+    data: {
+      table() {
+        return {
+          // deno-lint-ignore no-explicit-any
+          findOne: (q: any) => Promise.resolve(rows.find((r) => match(r, q)) ?? null),
+          // deno-lint-ignore no-explicit-any
+          count: (q: any) => Promise.resolve(rows.filter((r) => match(r, q)).length),
+          insert: (row: PlanReview) => {
+            rows.push(row);
+            return Promise.resolve(row);
+          },
+        };
+      },
+    },
+    log: () => {},
+    _rows: rows,
+    // deno-lint-ignore no-explicit-any
+  } as any;
+}
+
+// Seed `n` prior recorded rounds for a plan so the next job lands on round `n` (0-based).
+function priorRounds(planKey: string, n: number): PlanReview[] {
+  return Array.from({ length: n }, (_, i) => ({
+    plan_key: planKey,
+    round: i,
+    approved: 0,
+    findings: null,
+    created_at: "2026-01-01T00:00:00.000Z",
+    job_key: `prior-${i}`,
+  }));
+}
+
+const call = async (app: unknown, vars: Record<string, unknown>, jobKey = "j-new") =>
+  // deno-lint-ignore no-explicit-any
+  await handler({ variables: vars, jobKey } as any, app as any);
+
+Deno.test("approved round proceeds (planApproved=true, no throw)", async () => {
+  const app = fakeApp(priorRounds("o/r#1", 0));
+  const out = await call(app, { planKey: "o/r#1", approved: true });
+  assertEquals((out as { planApproved: boolean }).planApproved, true);
+});
+
+Deno.test("unapproved, non-final round revises (planApproved=false, no throw)", async () => {
+  // First round of a 3-round cap: not final, so revise.
+  const app = fakeApp(priorRounds("o/r#2", 0));
+  const out = await call(app, { planKey: "o/r#2", approved: false, findings: "fix X" });
+  assertEquals((out as { planApproved: boolean; planFindings: string }).planApproved, false);
+  assertEquals((out as { planFindings: string }).planFindings, "fix X");
+});
+
+Deno.test("unapproved FINAL round hard-fails with PLAN_REJECTED incident", async () => {
+  // Seed cap-1 prior rounds so this job is the last permitted round; unapproved ⇒ must throw.
+  const app = fakeApp(priorRounds("o/r#3", MAX_PLAN_REVIEW_ROUNDS - 1));
+  const err = await assertRejects(
+    () => call(app, { planKey: "o/r#3", approved: false, findings: "still wrong" }),
+    BpmnError,
+  );
+  assertEquals((err as BpmnError).errorCode, "PLAN_REJECTED");
+});
+
+Deno.test("approved on the FINAL round still proceeds (no throw)", async () => {
+  const app = fakeApp(priorRounds("o/r#4", MAX_PLAN_REVIEW_ROUNDS - 1));
+  const out = await call(app, { planKey: "o/r#4", approved: true });
+  assertEquals((out as { planApproved: boolean }).planApproved, true);
+});

package/workers/record-plan-review/worker.ts

@@ -6,13 +6,17 @@
 //   • derives the current round from the append-only `plan_reviews` log (no counter variable),
 //     using the engine jobKey as an idempotency guard so a retried job reuses its row,
 //   • records this round's verdict + findings,
-//   • decides the loop: `planApproved` (reviewer said yes) and `reviewExhausted` (the round cap
-//     is reached, so we proceed regardless rather than dead-lock on a reviewer that never
-//     approves), and re-emits the findings as `planFindings` so a revise round feeds the planner.
+//   • decides the loop: emits `planApproved` (reviewer said yes → the BPMN gateway proceeds to
+//     `select-wave`) or, when unapproved, re-emits the findings as `planFindings` so a revise
+//     round feeds the planner and loops back to `plan`.
 //
-// The BPMN gateway proceeds to `select-wave` when `planApproved or reviewExhausted`, else loops
-// back to `plan`. A missing/ambiguous `approved` is treated as NOT approved (revise) — but the
-// round cap still bounds the loop, so the plan can never wedge.
+// When the review-round cap is reached WITHOUT approval, this worker HARD-FAILS: it throws a
+// non-retryable `PLAN_REJECTED` BpmnError (→ incident) rather than proceeding regardless
+// (issue #86). Proceeding used to dispatch an un-vetted plan and — when the plan was empty — let
+// the whole epic complete GREEN having done nothing. The cap still bounds the loop; it now bounds
+// it into an incident, not a silent proceed. A missing/ambiguous `approved` is treated as NOT
+// approved (revise until the cap).
+import { BpmnError } from "@nanobpm/urban";
 import type { AppJobHandler } from "@nanobpm/urban";
 import { MAX_PLAN_REVIEW_ROUNDS, type PlanReview, planReviews } from "../../app/plan.ts";
 
@@ -23,7 +27,6 @@ interface In extends Record<string, unknown> {
 }
 interface Out extends Record<string, unknown> {
   planApproved: boolean;
-  reviewExhausted: boolean;
   planFindings: string;
 }
 
@@ -56,7 +59,7 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
   // Idempotency guard: deriving the round from count(plan_reviews) is not retry-safe on its own.
   // A job retried after the insert (crash/timeout post-write) re-runs with the SAME jobKey — if
   // this job already recorded a row, reuse it rather than appending a duplicate, which would
-  // inflate the count and trip `reviewExhausted` early. Otherwise this is the first attempt:
+  // inflate the count and reach the review-round cap early. Otherwise this is the first attempt:
   // derive the 0-based next round from the append-only log and record it under this jobKey.
   const recorded: PlanReview = (await reviews.findOne({ plan_key: planKey, job_key: jobKey })) ??
     await (async () => {
@@ -77,16 +80,29 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
   const roundApproved = recorded.approved === 1;
   const roundFindings = recorded.findings ?? "";
 
-  // Exhausted once this round is the last permitted one (round is 0-based).
-  const reviewExhausted = round + 1 >= MAX_PLAN_REVIEW_ROUNDS;
-  if (!roundApproved) {
-    app.log(reviewExhausted ? "warn" : "info", `record-plan-review: ${planKey} round ${round}`, {
-      approved: roundApproved,
-      reviewExhausted,
+  if (roundApproved) {
+    return { planApproved: true, planFindings: roundFindings };
+  }
+
+  // Not approved this round. Hard-fail once the round cap is reached (issue #86): previously the
+  // fan-out PROCEEDED regardless ("don't dead-lock on a reviewer that never approves"), which
+  // dispatched an un-vetted plan and — when the plan was empty — completed the epic GREEN having
+  // done nothing (instance 21). Instead raise a non-retryable BpmnError: no boundary catches
+  // `PLAN_REJECTED`, so the engine parks the instance on an incident rather than dispatching an
+  // un-approved plan. The round is 0-based, so `round + 1 >= cap` is the last permitted round.
+  if (round + 1 >= MAX_PLAN_REVIEW_ROUNDS) {
+    app.log("error", `record-plan-review: ${planKey} not approved after ${MAX_PLAN_REVIEW_ROUNDS} round(s)`, {
+      round,
     });
+    throw new BpmnError(
+      "PLAN_REJECTED",
+      `${planKey}: plan not approved after ${MAX_PLAN_REVIEW_ROUNDS} review round(s)`,
+    );
   }
 
-  return { planApproved: roundApproved, reviewExhausted, planFindings: roundFindings };
+  // Otherwise loop: the planner revises against this round's findings.
+  app.log("info", `record-plan-review: ${planKey} round ${round} — revise`, { approved: false });
+  return { planApproved: false, planFindings: roundFindings };
 };
 
 export default handler;