@nanobpm/nano-workforce 0.45.0 → 0.46.1

package/workers/persist-plan-escalation/worker.ts

@@ -0,0 +1,73 @@
+// pr.persist-plan-escalation — the adversarial plan-review loop reached its per-epoch budget
+// without approval. Record a plan-level human escalation and park the process until an operator
+// answers with either `revise` (default: loop back to the planner with guidance and a fresh epoch)
+// or `proceed` (explicit override: dispatch the current plan as-is).
+import type { AppJobHandler } from "@nanobpm/urban";
+import { planReviewEscalations, plans } from "../../app/plan.ts";
+
+interface In extends Record<string, unknown> {
+  planKey: string;
+  planFindings?: unknown;
+  planReviewEpoch?: unknown;
+  planReviewRound?: unknown;
+}
+interface Out extends Record<string, unknown> {
+  planEscalationId: number;
+}
+
+// Accept only genuine strings (trimmed); anything else is treated as missing so
+// the explicit planKey guard fires instead of silently coercing (e.g. 123 -> "123")
+// an escalation that BPMN correlation ("owner/repo#N") could never resume.
+const str = (v: unknown): string => (typeof v === "string" ? v.trim() : "");
+const int = (v: unknown): number => {
+  const n = Math.trunc(Number(v));
+  return Number.isFinite(n) && n >= 0 ? n : 0;
+};
+
+const handler: AppJobHandler<In, Out> = async (job, app) => {
+  const planKey = str(job.variables.planKey);
+  if (!planKey) {
+    // No plan binding means we cannot correlate a resume — fail loudly rather
+    // than silently parking a token that can never be answered.
+    throw new Error("persist-plan-escalation: missing planKey in process scope");
+  }
+  const epoch = int(job.variables.planReviewEpoch);
+  const round = int(job.variables.planReviewRound);
+  const findings = str(job.variables.planFindings) || null;
+  const ts = new Date().toISOString();
+
+  const escTable = planReviewEscalations(app.data);
+  const existing = (await escTable.find({ plan_key: planKey, status: "open" }))
+    .sort((a, b) => b.id - a.id)[0];
+  let escalationId: number;
+  if (existing) {
+    await escTable.update(existing.id, { epoch, round, findings });
+    escalationId = existing.id;
+  } else {
+    escalationId = Number(
+      await escTable.insert({
+        plan_key: planKey,
+        epoch,
+        round,
+        findings,
+        status: "open",
+        directive: null,
+        note: null,
+        asked_at: ts,
+        answered_at: null,
+      }),
+    );
+  }
+
+  await plans(app.data).update(planKey, {
+    status: "planning",
+    open_plan_escalation_id: escalationId,
+    open_plan_findings: findings,
+    open_plan_round: round,
+    updated_at: ts,
+  });
+
+  return { planEscalationId: escalationId };
+};
+
+export default handler;

package/workers/persist-task-escalation/worker.ts

@@ -36,6 +36,7 @@ interface In extends Record<string, unknown> {
 }
 interface Out extends Record<string, unknown> {
   escalationId: number;
+  escalationCorrKey: string;
 }
 
 // A non-blank trimmed string, else undefined. A blank question/PR must not reach
@@ -106,7 +107,14 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
   }
 
   await refreshOpenTaskEscalation(app.data, planKey);
-  return { escalationId };
+  // Emit the correlation key as a single scalar so the downstream
+  // `feature-escalation-answered` catch subscribes on `=escalationCorrKey`
+  // (freshly set, in scope) rather than re-deriving `=planKey + ":" + task.id`.
+  // The concatenation form errored to an empty, unmatchable key whenever `task`
+  // was not a Map at subscription-open, parking the token forever (see the
+  // engine incident fix). The value is identical to `featureCorrKey(planKey,
+  // taskId)`, so the app's answer-publish path still matches.
+  return { escalationId, escalationCorrKey: corrKey };
 };
 
 export default handler;

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

@@ -1,80 +1,100 @@
 // 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.
+// The fan-out must never dispatch an unapproved plan automatically. When the per-epoch review cap
+// is reached without approval, record-plan-review now emits `planEscalated` so BPMN parks for a
+// human directive instead of throwing an unhandled incident or proceeding silently.
 import { test } from "node:test";
-import { assertEquals, assertRejects } from "#test-assert";
-import { BpmnError } from "@nanobpm/urban";
+import { assertEquals } from "#test-assert";
 import { noopLog } from "../../test/log.ts";
-import handler from "./worker.ts";
 import { MAX_PLAN_REVIEW_ROUNDS, type PlanReview } from "../../app/plan.ts";
+import handler from "./worker.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);
+function fakeApp(existing: PlanReview[] = [], reviewEscalations: any[] = []) {
+  const reviewRows: PlanReview[] = [...existing];
+  const escalationRows = [...reviewEscalations];
+  const match = (r: Record<string, unknown>, q: Record<string, unknown>) =>
+    Object.entries(q).every(([f, v]) => r[f] === v);
+  const table = (rows: any[]) => ({
+    find: (q: any) => Promise.resolve(rows.filter((r) => match(r, q))),
+    findOne: (q: any) => Promise.resolve(rows.find((r) => match(r, q)) ?? null),
+    count: (q: any) => Promise.resolve(rows.filter((r) => match(r, q)).length),
+    insert: (row: any) => {
+      rows.push(row);
+      return Promise.resolve(row);
+    },
+  });
   return {
     data: {
-      table() {
-        return {
-          findOne: (q: any) => Promise.resolve(rows.find((r) => match(r, q)) ?? null),
-          count: (q: any) => Promise.resolve(rows.filter((r) => match(r, q)).length),
-          insert: (row: PlanReview) => {
-            rows.push(row);
-            return Promise.resolve(row);
-          },
-        };
+      table(name: string) {
+        if (name === "plan_review_escalations") return table(escalationRows);
+        return table(reviewRows);
       },
     },
     log: noopLog(),
-    _rows: rows,
+    _rows: reviewRows,
+    _escalations: escalationRows,
   } 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[] {
+// Seed `n` prior recorded rounds for a plan/epoch so the next job lands on round `n` (0-based).
+function priorRounds(planKey: string, n: number, epoch = 0): PlanReview[] {
   return Array.from({ length: n }, (_, i) => ({
     plan_key: planKey,
+    epoch,
     round: i,
     approved: 0,
     findings: null,
     created_at: "2026-01-01T00:00:00.000Z",
-    job_key: `prior-${i}`,
+    job_key: `prior-${epoch}-${i}`,
   }));
 }
 
 const call = async (app: unknown, vars: Record<string, unknown>, jobKey = "j-new") =>
   await handler({ variables: vars, jobKey } as any, app as any);
 
-test("approved round proceeds (planApproved=true, no throw)", async () => {
+test("approved round proceeds (planApproved=true, no escalation)", 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);
+  assertEquals((out as any).planApproved, true);
+  assertEquals((out as any).planEscalated, false);
 });
 
-test("unapproved, non-final round revises (planApproved=false, no throw)", async () => {
+test("unapproved, non-final round revises (planApproved=false, no escalation)", 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");
+  assertEquals((out as any).planApproved, false);
+  assertEquals((out as any).planEscalated, false);
+  assertEquals((out as any).planFindings, "fix X");
 });
 
-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.
+test("unapproved FINAL round escalates instead of throwing or proceeding", async () => {
+  // Seed cap-1 prior rounds so this job is the last permitted round; unapproved ⇒ human escalation.
   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");
+  const out = await call(app, { planKey: "o/r#3", approved: false, findings: "still wrong" });
+  assertEquals((out as any).planApproved, false);
+  assertEquals((out as any).planEscalated, true);
+  assertEquals((out as any).planReviewRound, MAX_PLAN_REVIEW_ROUNDS - 1);
+  assertEquals((out as any).planFindings, "still wrong");
 });
 
-test("approved on the FINAL round still proceeds (no throw)", async () => {
+test("approved on the FINAL round still proceeds (no escalation)", 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);
+  assertEquals((out as any).planApproved, true);
+  assertEquals((out as any).planEscalated, false);
+});
+
+test("answered plan-review escalation starts a fresh epoch and round budget", async () => {
+  const app = fakeApp(
+    priorRounds("o/r#5", MAX_PLAN_REVIEW_ROUNDS, 0),
+    [{ id: 1, plan_key: "o/r#5", status: "answered" }],
+  );
+  const out = await call(app, { planKey: "o/r#5", approved: false, findings: "new epoch finding" });
+  assertEquals((out as any).planApproved, false);
+  assertEquals((out as any).planEscalated, false);
+  assertEquals((out as any).planReviewEpoch, 1);
+  assertEquals((out as any).planReviewRound, 0);
+  assertEquals(app._rows.at(-1).epoch, 1);
+  assertEquals(app._rows.at(-1).round, 0);
 });

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

@@ -3,23 +3,27 @@
 //
 // The `senior:plan-review` agent critiqued the levelized plan and emitted `{ approved, findings }`.
 // This worker:
-//   • 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,
+//   • derives the current epoch from answered plan-review escalations and the current round from
+//     the append-only `plan_reviews` log for that epoch (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: 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`.
 //
-// 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).
+// When the review-round cap is reached WITHOUT approval, this worker emits `planEscalated` so the
+// BPMN parks on a human plan-review escalation rather than proceeding regardless or raising an
+// unhandled incident. Proceeding used to dispatch an un-vetted plan and — when the plan was empty —
+// let the whole epic complete GREEN having done nothing. A missing/ambiguous `approved` is treated
+// as NOT approved (revise until the cap, then escalate).
 
 import type { AppJobHandler } from "@nanobpm/urban";
-import { BpmnError } from "@nanobpm/urban";
-import { MAX_PLAN_REVIEW_ROUNDS, type PlanReview, planReviews } from "../../app/plan.ts";
+import {
+  currentPlanReviewEpoch,
+  MAX_PLAN_REVIEW_ROUNDS,
+  type PlanReview,
+  planReviews,
+} from "../../app/plan.ts";
 
 interface In extends Record<string, unknown> {
   planKey: string;
@@ -28,7 +32,10 @@ interface In extends Record<string, unknown> {
 }
 interface Out extends Record<string, unknown> {
   planApproved: boolean;
+  planEscalated: boolean;
   planFindings: string;
+  planReviewEpoch: number;
+  planReviewRound: number;
 }
 
 // Only an explicit boolean-true (or the string "true") approves; anything else — including a
@@ -56,17 +63,20 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
   const jobKey = job.jobKey;
 
   const reviews = planReviews(app.data);
+  const epoch = await currentPlanReviewEpoch(app.data, planKey);
 
-  // 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
+  // Idempotency guard: deriving the epoch/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 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.
+  // derive the 0-based next round from the append-only log for the current epoch and record it
+  // under this jobKey.
   const recorded: PlanReview = (await reviews.findOne({ plan_key: planKey, job_key: jobKey })) ??
     await (async () => {
-      const round = await reviews.count({ plan_key: planKey }); // 0-based: next round index
+      const round = await reviews.count({ plan_key: planKey, epoch }); // 0-based: next round index
       const row: PlanReview = {
         plan_key: planKey,
+        epoch,
         round,
         approved: approved ? 1 : 0,
         findings: findings || null,
@@ -78,32 +88,46 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
     })();
 
   const round = recorded.round;
+  const recordedEpoch = recorded.epoch;
   const roundApproved = recorded.approved === 1;
   const roundFindings = recorded.findings ?? "";
 
   if (roundApproved) {
-    return { planApproved: true, planFindings: roundFindings };
+    return {
+      planApproved: true,
+      planEscalated: false,
+      planFindings: roundFindings,
+      planReviewEpoch: recordedEpoch,
+      planReviewRound: round,
+    };
   }
 
-  // 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.
+  // Not approved this round. Escalate once the per-epoch round cap is reached (issue #86):
+  // previously the fan-out PROCEEDED regardless, dispatching an un-vetted 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)`, {
+    app.log.warn(`record-plan-review: ${planKey} not approved after ${MAX_PLAN_REVIEW_ROUNDS} round(s)`, {
+      epoch: recordedEpoch,
       round,
     });
-    throw new BpmnError(
-      "PLAN_REJECTED",
-      `${planKey}: plan not approved after ${MAX_PLAN_REVIEW_ROUNDS} review round(s)`,
-    );
+    return {
+      planApproved: false,
+      planEscalated: true,
+      planFindings: roundFindings,
+      planReviewEpoch: recordedEpoch,
+      planReviewRound: round,
+    };
   }
 
   // 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 };
+  app.log.info(`record-plan-review: ${planKey} epoch ${recordedEpoch} round ${round} — revise`, { approved: false });
+  return {
+    planApproved: false,
+    planEscalated: false,
+    planFindings: roundFindings,
+    planReviewEpoch: recordedEpoch,
+    planReviewRound: round,
+  };
 };
 
 export default handler;