@nanobpm/nano-workforce 0.57.0 → 0.58.0

package/resources/processes/spine-demo.bpmn

@@ -0,0 +1,72 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<bpmn:definitions xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL" xmlns:bpmndi="http://www.omg.org/spec/BPMN/20100524/DI" xmlns:dc="http://www.omg.org/spec/DD/20100524/DC" xmlns:di="http://www.omg.org/spec/DD/20100524/DI" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:zeebe="http://camunda.org/schema/zeebe/1.0" xmlns:nano="https://nanobpm.io/schema/shapes/1.0" id="Definitions_nano_workforce_spine_demo" targetNamespace="http://nanobpm.io/nano-workforce">
+  <bpmn:process id="spine-demo" name="User-task Spine Demo" isExecutable="true">
+    <bpmn:startEvent id="start">
+      <bpmn:outgoing>flow-to-decide</bpmn:outgoing>
+    </bpmn:startEvent>
+    <bpmn:userTask id="decide" name="Decide">
+      <bpmn:extensionElements>
+        <zeebe:formDefinition formId="spine-demo" />
+        <zeebe:userTask />
+      </bpmn:extensionElements>
+      <bpmn:incoming>flow-to-decide</bpmn:incoming>
+      <bpmn:outgoing>flow-to-gateway</bpmn:outgoing>
+    </bpmn:userTask>
+    <bpmn:exclusiveGateway id="gw-decision" name="decision?" default="flow-rejected">
+      <bpmn:incoming>flow-to-gateway</bpmn:incoming>
+      <bpmn:outgoing>flow-approved</bpmn:outgoing>
+      <bpmn:outgoing>flow-rejected</bpmn:outgoing>
+    </bpmn:exclusiveGateway>
+    <bpmn:endEvent id="end-approved">
+      <bpmn:incoming>flow-approved</bpmn:incoming>
+    </bpmn:endEvent>
+    <bpmn:endEvent id="end-rejected">
+      <bpmn:incoming>flow-rejected</bpmn:incoming>
+    </bpmn:endEvent>
+    <bpmn:sequenceFlow id="flow-to-decide" sourceRef="start" targetRef="decide" />
+    <bpmn:sequenceFlow id="flow-to-gateway" sourceRef="decide" targetRef="gw-decision" />
+    <bpmn:sequenceFlow id="flow-approved" sourceRef="gw-decision" targetRef="end-approved">
+      <bpmn:conditionExpression xsi:type="bpmn:tFormalExpression">=decision = "approve"</bpmn:conditionExpression>
+    </bpmn:sequenceFlow>
+    <bpmn:sequenceFlow id="flow-rejected" sourceRef="gw-decision" targetRef="end-rejected" />
+  </bpmn:process>
+  <bpmndi:BPMNDiagram id="BPMNDiagram_spine-demo">
+    <bpmndi:BPMNPlane id="BPMNPlane_spine-demo" bpmnElement="spine-demo">
+      <bpmndi:BPMNShape id="BPMNShape_start" bpmnElement="start">
+        <dc:Bounds x="80" y="102" width="36" height="36" />
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="BPMNShape_decide" bpmnElement="decide">
+        <dc:Bounds x="216" y="80" width="100" height="80" />
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="BPMNShape_gw-decision" bpmnElement="gw-decision" isMarkerVisible="true">
+        <dc:Bounds x="416" y="95" width="50" height="50" />
+        <bpmndi:BPMNLabel>
+          <dc:Bounds x="408" y="76" width="67" height="14" />
+        </bpmndi:BPMNLabel>
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="BPMNShape_end-approved" bpmnElement="end-approved">
+        <dc:Bounds x="566" y="262" width="36" height="36" />
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="BPMNShape_end-rejected" bpmnElement="end-rejected">
+        <dc:Bounds x="566" y="102" width="36" height="36" />
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNEdge id="BPMNEdge_flow-to-decide" bpmnElement="flow-to-decide">
+        <di:waypoint x="116" y="120" />
+        <di:waypoint x="216" y="120" />
+      </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="BPMNEdge_flow-to-gateway" bpmnElement="flow-to-gateway">
+        <di:waypoint x="316" y="120" />
+        <di:waypoint x="416" y="120" />
+      </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="BPMNEdge_flow-rejected" bpmnElement="flow-rejected">
+        <di:waypoint x="466" y="120" />
+        <di:waypoint x="566" y="120" />
+      </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="BPMNEdge_flow-approved" bpmnElement="flow-approved">
+        <di:waypoint x="441" y="145" />
+        <di:waypoint x="441" y="280" />
+        <di:waypoint x="566" y="280" />
+      </bpmndi:BPMNEdge>
+    </bpmndi:BPMNPlane>
+  </bpmndi:BPMNDiagram>
+</bpmn:definitions>

package/scripts/check-migrations.ts

@@ -0,0 +1,68 @@
+// check-migrations — merge-safety gate for the forward-only SQLite migrations under db/migrations/.
+//
+// Migrations are numbered by a leading 3-digit prefix and applied in prefix order (nano.app.json
+// data.sources.app.migrations). AGENTS.md tells every author to "number a new migration after the
+// current highest prefix" — but that number is computed independently in each worktree. When an
+// epic fans a fleet out across parallel branches, two siblings both take "the next" free prefix
+// and emit e.g. 023_agentic_presence.sql and 023_agentic_transcript.sql. Those filenames don't
+// textually conflict, so git merges both cleanly and the collision is SILENT: two migrations now
+// share an apply-order slot. This exact failure mode already scarred the repo (the historical
+// 004/005/006/007 duplicate pairs) and recurred on epic #142 despite the doc note added by the
+// #160 retro (PR #178) — so we escalate the lesson from a doc line to a mechanical gate.
+//
+// The rule: no two migration files may share a numeric prefix. The pre-existing historical
+// duplicates are forward-only and already applied, so they cannot be renamed — they are
+// grandfathered in GRANDFATHERED_DUPES. Any NEW duplicate prefix fails the build.
+import { readdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const MIGRATIONS_DIR = join(dirname(fileURLToPath(import.meta.url)), "..", "db", "migrations");
+
+// Historical collisions that predate this gate. Forward-only + already applied ⇒ cannot be
+// renumbered. New duplicates are NOT allowed here — fix them before merge.
+const GRANDFATHERED_DUPES: ReadonlySet<string> = new Set(["004", "005", "006", "007"]);
+
+const PREFIX = /^(\d{3})_[^/]*\.sql$/;
+
+function main(): void {
+  const files = readdirSync(MIGRATIONS_DIR)
+    .filter((f) => f.endsWith(".sql"))
+    .sort();
+
+  const errors: string[] = [];
+  const byPrefix = new Map<string, string[]>();
+
+  for (const file of files) {
+    const m = PREFIX.exec(file);
+    if (!m) {
+      errors.push(
+        `  ${file}: does not match the required NNN_name.sql shape (3-digit prefix, underscore, name).`,
+      );
+      continue;
+    }
+    const prefix = m[1];
+    const group = byPrefix.get(prefix) ?? [];
+    group.push(file);
+    byPrefix.set(prefix, group);
+  }
+
+  for (const [prefix, group] of byPrefix) {
+    if (group.length > 1 && !GRANDFATHERED_DUPES.has(prefix)) {
+      errors.push(
+        `  prefix ${prefix} is used by ${group.length} files: ${group.join(", ")} — ` +
+          `two migrations cannot share an apply-order slot. Renumber the newer one to the next ` +
+          `free prefix (check origin/main, not your branch point).`,
+      );
+    }
+  }
+
+  if (errors.length > 0) {
+    console.error(`check-migrations: db/migrations has colliding prefixes:\n${errors.join("\n")}`);
+    process.exit(1);
+  }
+
+  console.log(`check-migrations: OK (${files.length} migrations, no colliding prefixes).`);
+}
+
+main();

package/workers/answer-escalation/worker.ts

@@ -0,0 +1,78 @@
+// pr.answer-escalation — retires the review-loop escalation the operator just answered.
+//
+// The review-loop escalation is a native `wait-answer` userTask (backed by `pr-escalation.form`).
+// Completing that task resumes the token, but the engine folds the completed instance's variables
+// away — so without this step the durable `escalations` audit row raised by `pr.persist-escalation`
+// would stay `status="open"` forever, its `answer`/`answered_at` never recorded. That both loses the
+// Q&A audit trail and (because `activePrs` derives `openEscalation` from the open-row status — the
+// single source of truth, ADR "derivation over duplication") would keep surfacing a phantom open
+// escalation on `/status` after it was answered.
+//
+// This mirrors the merge-loop's message-catch answer path (`answerEscalation` in app/service.ts):
+// both answer the newest still-open `escalations` row, mark any duplicate open rows `stale` (a
+// retry of `pr.persist-escalation` can leave more than one open), AND move the `pull_requests` row
+// off `status="escalated"` back to `"converging"`, so an answered escalation is never left dangling
+// and `/status` never shows an escalated PR with a null question or a phantom open row. The token
+// resume itself is owned by the engine (userTask completion), so this worker only reconciles the
+// durable rows; it returns no variables, leaving the submitted `answer` untouched so it flows on to
+// the next review round.
+import type { AppJobHandler } from "@nanobpm/urban";
+
+interface Escalation extends Record<string, unknown> {
+  id: number;
+  pr_key: string;
+  status: string;
+  answer: string | null;
+  answered_at: string | null;
+}
+
+// The PR-row fields this worker reconciles when an escalation is answered. Only `status`/`updated_at`
+// are written (mirroring `answerEscalation`); the rest of the row is untouched.
+interface PullRequest extends Record<string, unknown> {
+  pr_key: string;
+  status: string;
+  updated_at: string;
+}
+
+interface In extends Record<string, unknown> {
+  prKey: string;
+  answer?: string;
+}
+
+// A string variable, or undefined when it is absent/blank. The form marks `answer` required, so a
+// blank here would be an out-of-band completion; record it as NULL rather than an empty string.
+function nonBlank(v: unknown): string | undefined {
+  return typeof v === "string" && v.trim() !== "" ? v.trim() : undefined;
+}
+
+const handler: AppJobHandler<In> = async (job, app) => {
+  const { prKey } = job.variables;
+  const answer = nonBlank(job.variables.answer);
+  const escs = app.data.table<Escalation>("escalations", "id");
+  // Retire EVERY still-open escalation for this PR. `pr.persist-escalation` always INSERTs a new
+  // open row, so a retry/duplicate activation can leave more than one open — answering only the
+  // newest would leave an older duplicate `open`, a phantom `activePrs` keeps deriving while the PR
+  // is still `escalated`. Answer the newest (it carries the operator's reply) and mark any remaining
+  // open rows `stale`, mirroring `answerEscalation` and `submitPr`'s resubmit cleanup.
+  const open = (await escs.find({ pr_key: prKey, status: "open" })).sort((a, b) => b.id - a.id);
+  if (open.length > 0) {
+    const ts = new Date().toISOString();
+    await escs.update(open[0].id, {
+      answer: answer ?? null,
+      status: "answered",
+      answered_at: ts,
+    });
+    for (const dup of open.slice(1)) {
+      await escs.update(dup.id, { status: "stale" });
+    }
+    // Mirror the merge loop's `answerEscalation`: move the PR off `status="escalated"` back to
+    // `"converging"` now that the question is answered. Without this the row stays `escalated` (with
+    // a now-null derived `openEscalation`) until the re-entered round's `persist-round` runs — a
+    // `/status` inconsistency and a divergence from the merge path both loops are meant to share.
+    const prs = app.data.table<PullRequest>("pull_requests", "pr_key");
+    await prs.update(prKey, { status: "converging", updated_at: ts });
+  }
+  return {};
+};
+
+export default handler;

package/workers/converge-feature/worker.ts

@@ -0,0 +1,51 @@
+// pr.converge-feature — hand a single-issue run's opened PR to the convergence loop (issue #172).
+//
+// Reached only via the `converge?` gateway's true branch (converge requested AND the agent opened a
+// keyed PR). Reuses `submitPr` — the SAME enrollment the epic waves and the standalone
+// `startConvergenceLoop` action use — so a feature run's PR gets identical review-round + merge
+// behaviour with no duplicated machinery. `autoMerge` maps to `submitPr`'s `convergeOnly`
+// (inverted): auto-merge → drive the merge-loop; otherwise stop at `converged`.
+//
+// The feature-run's OWN process ends here; the PR's live convergence/merge state lives on the
+// `pull_requests` row keyed by `pr_key`, which the feature page links to. We therefore leave the
+// `feature_runs` row in the terminal `converging` status (NOT an active status), so the
+// instanceTracking reconciler does not mark it `abandoned` when feature.bpmn completes.
+import type { AppJobHandler } from "@nanobpm/urban";
+import { featureRuns } from "../../app/feature.ts";
+import { MAX_ROUNDS, parsePr, submitPr } from "../../app/service.ts";
+
+interface In extends Record<string, unknown> {
+  featureKey: string;
+  prKey?: unknown;
+  autoMerge?: unknown;
+}
+
+const handler: AppJobHandler<In, Record<string, never>> = async (job, app) => {
+  const featureKey = job.variables.featureKey;
+  const prKey = typeof job.variables.prKey === "string" ? job.variables.prKey.trim() : "";
+  const autoMerge = job.variables.autoMerge === true;
+  const parsed = prKey ? parsePr(prKey) : null;
+  if (!parsed) {
+    // Should not happen — the gateway only routes here when record-feature emitted a parseable
+    // prKey — but never enroll a phantom PR. Leave the row `opened` and end.
+    app.log.warn("converge-feature: no parseable PR key, skipping hand-off", { featureKey, prKey });
+    await featureRuns(app.data).update(featureKey, { status: "opened", updated_at: new Date().toISOString() });
+    return {};
+  }
+  // `convergeOnly` is the inverse of auto-merge: converge-only stops at `converged`; auto-merge lets
+  // the merge-loop drive the merge. `submitPr` is idempotent on the PR key.
+  await submitPr(app.data, app.engine, parsed, [], MAX_ROUNDS, !autoMerge);
+  await featureRuns(app.data).update(featureKey, {
+    status: "converging",
+    pr_key: parsed.prKey,
+    updated_at: new Date().toISOString(),
+  });
+  app.log.info("converge-feature: enrolled PR into convergence loop", {
+    featureKey,
+    prKey: parsed.prKey,
+    convergeOnly: !autoMerge,
+  });
+  return {};
+};
+
+export default handler;

package/workers/finalize/worker.ts

@@ -101,8 +101,6 @@ const handler: AppJobHandler<In> = async (job, app) => {
     outcome: summary,
     converged_at: now,
     updated_at: now,
-    open_escalation_id: null,
-    open_escalation_question: null,
   });
 
   // Only the review-only terminal path ends the PR here as `converged` — in auto-merge mode the

package/workers/mark-merged/worker.ts

@@ -13,8 +13,6 @@ const handler: AppJobHandler<In> = async (job, app) => {
     status: "merged",
     merged_at: now,
     updated_at: now,
-    open_escalation_id: null,
-    open_escalation_question: null,
   });
 
   // If this PR was the last of its epic to land, kick off the retrospective. Best-effort: a

package/workers/merge/worker.ts

@@ -11,9 +11,9 @@
 import type { AppJobHandler } from "@nanobpm/urban";
 import { matchTags, tag } from "@nanobpm/urban/effect";
 import { abandonTokenFromUrl } from "../../app/abandon.ts";
-import { checkBaseTarget } from "../../app/baseGuard.ts";
+import { checkBaseTarget, classifyBaseGuard } from "../../app/baseGuard.ts";
 import { enqueueViaComment, fetchPrState, mergePr } from "../../app/github.ts";
-import { loadMergeProtocol } from "../../app/mergeProtocol.ts";
+import { classifyMergeLanding, DEFAULT_MERGE_PROTOCOL, loadMergeProtocol } from "../../app/mergeProtocol.ts";
 import { ensurePr, MERGE_ADMIN, MERGE_METHOD } from "../../app/service.ts";
 
 interface In extends Record<string, unknown> {
@@ -77,7 +77,7 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
   // base (typical in a stacked epic) stays the target and reads CLEAN, so nothing else catches it.
   // Best-effort: a transport hiccup leaves `deadEnd:false`, so this never blocks a valid merge.
   const guard = await checkBaseTarget(repo, prNumber, token).catch(() => null);
-  if (guard?.deadEnd) {
+  if (guard && classifyBaseGuard(guard) === "decision-required") {
     await app.data.table("merges", "id").insert({
       pr_key: prKey,
       outcome: "blocked",
@@ -112,8 +112,9 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
     outcome = ok ? "queued" : "blocked";
     detail = ok ? `enqueued via "${comment}"` : `failed to post enqueue comment "${comment}"`;
     auditMethod = "queue-comment";
-  } else if (method === "ui") {
-    // The repo requires a human to click Merge; Merlin can't. Escalate rather than pretend.
+  } else if (classifyMergeLanding(protocol ?? DEFAULT_MERGE_PROTOCOL) === "decision-required") {
+    // The repo requires a human to click Merge (`land.method=ui`); Merlin can't. This is the
+    // only decision-required land method — escalate rather than pretend.
     outcome = "blocked";
     detail = "repo merge protocol requires a manual UI merge (land.method=ui)";
     auditMethod = "ui";

package/workers/persist-escalation/worker.ts

@@ -2,8 +2,20 @@
 // row for a human to answer. Handles both the agent-raised path (status = needs_input | blocked)
 // and the MAX_ROUNDS guard (status = blocked, question set by the process). Returns
 // `escalationId` for the UI.
+//
+// A BLANK question is a NON-escalation (nano-workforce ADR 0002 §1): it must never open an
+// answerable escalation. The convergence-loop `gw-status` gateway enforces this upstream — its
+// `f_escalate` arm now requires a non-blank question, so a blank-question round re-enters the
+// durable review wait instead of routing here (see app/roundResultDefault.ts). This worker keeps
+// the same rule as defence-in-depth via the canonical taxonomy: if a blank-question job ever
+// reaches it, it opens NO escalation and reports `escalated:false` rather than FABRICATING a
+// question (the retired failure mode) or throwing an un-remediable incident. The convergence-loop
+// model branches on that `escalated` output (`gw-escalated`): a `false` return re-enters the loop
+// via `gw-guard` instead of flowing into the `wait-answer` catch, so a non-escalation can never
+// wedge a token on a durable wait that has no escalation for a human to answer.
 import type { AppJobHandler } from "@nanobpm/urban";
 import { abandonTokenFromUrl } from "../../app/abandon.ts";
+import { classifyEscalation } from "../../app/escalationTaxonomy.ts";
 import { ensurePr, parsePr } from "../../app/service.ts";
 
 // Extends Record so the declared fields are typed while the job may still carry
@@ -51,42 +63,28 @@ function workerOf(vars: Record<string, unknown>): string | undefined {
   return nonBlank(vars.agent);
 }
 
-// Synthesize a concrete, answerable question when the agent left one blank. A blank question is
-// almost always a *no-result* round: a prompt-less agent that never wrote its result file, so
-// `status` is empty and `gw-status` falls through its default `f_escalate` arm (the empty
-// "(no question provided)" escalations on Magikcraft/nano-bpm #597/#599). Throwing here parked a
-// `JobNoRetries` incident that could NOT be diagnosed or remediated from the UI. Instead we open
-// an escalation a human can actually answer, with the agent's transcript attached below it.
-function fabricateQuestion(rawStatus: string | undefined, hasTranscript: boolean): string {
-  const tail = hasTranscript
-    ? " Review the agent's response shown below, then reply with how it should proceed — or cancel and resubmit."
-    : " No agent response was captured. Reply with how it should proceed, or cancel and resubmit.";
-  if (!rawStatus) {
-    return "The review agent finished without a machine-readable result (no status was reported), " +
-      "so this round could not be classified as converged, addressed, or a specific request." + tail;
-  }
-  return `The review agent reported status "${rawStatus}" without a question, so this round ` +
-    "could not be resolved automatically." + tail;
-}
-
 const handler: AppJobHandler<In> = async (job, app) => {
   const { prKey, round, summary, repo, prNumber, prUrl, abandonUrl } = job.variables;
   // `status` drives the escalation kind (control flow); a blank/absent status is an
-  // unclassified escalation -> a question needing input. `question` is denormalised
-  // onto pull_requests below and bound by the UI answer form, so it must be a
-  // concrete, non-blank value. `summary` is left undefined so the write boundary
-  // omits it and the nullable column stays NULL.
+  // unclassified escalation -> a question needing input. `question` is returned as a
+  // process variable below so the downstream `wait-answer` userTask + `pr-escalation.form`
+  // can display it, so it must be a concrete, non-blank value. `summary` is left undefined
+  // so the write boundary omits it and the nullable column stays NULL.
   const rawStatus = nonBlank(job.variables.status);
   const status = rawStatus ?? "needs_input";
   const transcript = transcriptOf(job.variables);
   const worker = workerOf(job.variables);
-  // A blank question must never open an unanswerable escalation. Every legitimate arm sets a
-  // concrete question — the agent contract requires one for needs_input/blocked, and the
-  // max-rounds + review-timeout arms set a literal via the model. When one is still missing
-  // (a no-result round through the `gw-status` default), fabricate an actionable question that
-  // references the attached transcript rather than throwing (which parked an un-remediable
-  // incident). This keeps the loop recoverable entirely from the UI.
-  const question = nonBlank(job.variables.question) ?? fabricateQuestion(rawStatus, transcript != null);
+  // Classify this job through the single canonical taxonomy (ADR 0002 §1). Only a
+  // decision-required escalation opens an answerable escalation row. A blank question (or any
+  // non-human-blocking status that reached here defensively) is a NON-escalation: open nothing
+  // and report `escalated:false` — never FABRICATE a question and never throw. The `gw-status`
+  // gateway already routes blank-question rounds back into the durable review wait, so this is
+  // defence-in-depth, not the primary guard.
+  const question = nonBlank(job.variables.question);
+  const disposition = classifyEscalation({ kind: "review-round", status: rawStatus, question });
+  if (disposition !== "decision-required" || question === undefined) {
+    return { escalationId: null, escalated: false };
+  }
   const kind = status === "needs_input" ? "question" : "blocker";
   const now = new Date().toISOString();
 
@@ -137,11 +135,9 @@ const handler: AppJobHandler<In> = async (job, app) => {
     status: "escalated",
     current_round: round,
     updated_at: now,
-    open_escalation_id: Number(escalationId),
-    open_escalation_question: question,
   });
 
-  return { escalationId: Number(escalationId) };
+  return { escalationId: Number(escalationId), escalated: true, question };
 };
 
 export default handler;

package/workers/record-feature/worker.ts

@@ -0,0 +1,61 @@
+// pr.record-feature — the single-issue `implement` block has finished (issue #172).
+//
+// The `senior:feature` agent reported one of `opened` / `blocked` / `skipped` (prompts/feature.md);
+// anything else — including a missing status, or an `escalated` status that fell through to abandon
+// (the human abandoned or the SLA fired) — is treated as `blocked`: we must not assume a PR was
+// opened. This worker:
+//   • resolves the run's terminal status from the agent result,
+//   • records the PR key + outcome on the `feature_runs` row,
+//   • emits `featureStatus` + `prKey` so the `converge?` gateway can decide whether to hand the
+//     opened PR off to the convergence loop.
+//
+// Enrollment itself lives in the separate `pr.converge-feature` worker (gated by the `converge?`
+// branch) so the hand-off is legible in the process, not buried in a persistence step.
+import type { AppJobHandler } from "@nanobpm/urban";
+import { type FeatureRunStatus, featureRuns } from "../../app/feature.ts";
+import { parsePr } from "../../app/service.ts";
+
+interface In extends Record<string, unknown> {
+  featureKey: string;
+  status?: unknown;
+  pr?: unknown;
+  summary?: unknown;
+}
+interface Out extends Record<string, unknown> {
+  featureStatus: FeatureRunStatus;
+  prKey: string | null;
+}
+
+const str = (v: unknown): string | undefined =>
+  typeof v === "string" && v.trim().length > 0 ? v.trim() : undefined;
+
+// The implementation agent reports one of these; anything else is `blocked` (we never assume a PR).
+type AgentStatus = "opened" | "blocked" | "skipped";
+const isAgentStatus = (s: string): s is AgentStatus => s === "opened" || s === "blocked" || s === "skipped";
+
+const handler: AppJobHandler<In, Out> = async (job, app) => {
+  const featureKey = job.variables.featureKey;
+  const rawStatus = str(job.variables.status);
+  const status: AgentStatus = rawStatus && isAgentStatus(rawStatus) ? rawStatus : "blocked";
+  const summary = str(job.variables.summary);
+  const prRef = str(job.variables.pr);
+  // Only trust a PR ref when the agent reports it actually opened one.
+  const parsed = status === "opened" && prRef ? parsePr(prRef) : null;
+  // A keyless "opened" cannot be handed off, but a PR was still raised — keep the status `opened`
+  // (the run is complete), just with no `pr_key` to converge.
+  const prKey = parsed?.prKey ?? null;
+  const featureStatus: FeatureRunStatus = status;
+  const ts = new Date().toISOString();
+
+  await featureRuns(app.data).update(featureKey, {
+    status: featureStatus,
+    pr_key: prKey,
+    outcome: summary ?? null,
+    updated_at: ts,
+  });
+  app.log.info("record-feature", { featureKey, featureStatus, prKey });
+
+  return { featureStatus, prKey };
+};
+
+export default handler;

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

@@ -9,9 +9,8 @@ import { noopLog } from "../../test/log.ts";
 import { MAX_PLAN_REVIEW_ROUNDS, type PlanReview } from "../../app/plan.ts";
 import handler from "./worker.ts";
 
-function fakeApp(existing: PlanReview[] = [], reviewEscalations: any[] = []) {
+function fakeApp(existing: PlanReview[] = []) {
   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[]) => ({
@@ -25,14 +24,12 @@ function fakeApp(existing: PlanReview[] = [], reviewEscalations: any[] = []) {
   });
   return {
     data: {
-      table(name: string) {
-        if (name === "plan_review_escalations") return table(escalationRows);
+      table() {
         return table(reviewRows);
       },
     },
     log: noopLog(),
     _rows: reviewRows,
-    _escalations: escalationRows,
   } as any;
 }
 
@@ -85,12 +82,14 @@ test("approved on the FINAL round still proceeds (no escalation)", async () => {
   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" }],
+test("a bumped plan-review epoch starts a fresh round budget", async () => {
+  // The `plan-review-decision` user task bumped `planReviewEpoch` to 1 after a prior epoch's
+  // rounds; the next planner pass records round 0 of the new epoch, resetting the budget.
+  const app = fakeApp(priorRounds("o/r#5", MAX_PLAN_REVIEW_ROUNDS, 0));
+  const out = await call(
+    app,
+    { planKey: "o/r#5", approved: false, findings: "new epoch finding", planReviewEpoch: 1 },
   );
-  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);

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

@@ -3,9 +3,10 @@
 //
 // The `senior:plan-review` agent critiqued the levelized plan and emitted `{ approved, findings }`.
 // This worker:
-//   • 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,
+//   • reads the current epoch from the durable `planReviewEpoch` process variable (bumped by the
+//     `plan-review-decision` user task each time a human answers a plan-review escalation) and
+//     derives 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
@@ -19,7 +20,6 @@
 
 import type { AppJobHandler } from "@nanobpm/urban";
 import {
-  currentPlanReviewEpoch,
   MAX_PLAN_REVIEW_ROUNDS,
   type PlanReview,
   planReviews,
@@ -29,6 +29,7 @@ interface In extends Record<string, unknown> {
   planKey: string;
   approved?: unknown;
   findings?: unknown;
+  planReviewEpoch?: unknown;
 }
 interface Out extends Record<string, unknown> {
   planApproved: boolean;
@@ -43,6 +44,15 @@ interface Out extends Record<string, unknown> {
 const isApproved = (v: unknown): boolean =>
   v === true || (typeof v === "string" && v.trim().toLowerCase() === "true");
 
+// The plan-review epoch is a durable process variable. `startPlan` seeds it to 0 when creating the
+// instance, and the `plan-review-decision` user task bumps it on each human answer. The 0-fallback
+// here is backwards compatibility for older instances created before the variable was seeded (where
+// it is null/absent): coerce anything unexpected to 0 so a round is always recorded under a valid epoch.
+const coerceEpoch = (v: unknown): number => {
+  const n = typeof v === "number" ? v : typeof v === "string" ? Number(v) : Number.NaN;
+  return Number.isInteger(n) && n >= 0 ? n : 0;
+};
+
 export const str = (v: unknown): string => {
   if (typeof v === "string") return v;
   if (v == null) return "";
@@ -63,7 +73,7 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
   const jobKey = job.jobKey;
 
   const reviews = planReviews(app.data);
-  const epoch = await currentPlanReviewEpoch(app.data, planKey);
+  const epoch = coerceEpoch(job.variables.planReviewEpoch);
 
   // 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 —