@nanobpm/nano-workforce 0.63.0 → 0.65.0

package/resources/processes/plan-fanout.bpmn

@@ -1,17 +1,46 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<bpmn:definitions xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 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:zeebe="http://camunda.org/schema/zeebe/1.0" id="Definitions_nano_workforce_plan" targetNamespace="http://nanobpm.io/nano-workforce">
+<bpmn:definitions xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 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:zeebe="http://camunda.org/schema/zeebe/1.0" xmlns:nano="https://nanobpm.io/schema/shapes/1.0" id="Definitions_nano_workforce_plan" targetNamespace="http://nanobpm.io/nano-workforce">
   <bpmn:message id="Message_waveMerged" name="wave-merged">
     <bpmn:extensionElements>
       <zeebe:subscription correlationKey="=planKey" />
     </bpmn:extensionElements>
   </bpmn:message>
   <bpmn:process id="plan-fanout" name="Agent Fleet — plan &#38; implement" isExecutable="true">
+    <bpmn:extensionElements>
+      <nano:shapes>
+        <nano:shape id="EnsureBaseBranchIn" name="Ensure base branch — input">
+          <nano:extend name="repo" type="string" />
+          <nano:extend name="baseBranch" type="string" />
+        </nano:shape>
+        <nano:shape id="RecordPlanReviewIn" name="Record plan review — input">
+          <nano:extend name="planKey" type="string" />
+          <nano:extend name="approved" type="boolean" optional="true" />
+          <nano:extend name="findings" type="string" optional="true" />
+          <nano:extend name="planReviewEpoch" type="integer" optional="true" />
+        </nano:shape>
+        <nano:shape id="SelectWaveIn" name="Select wave — input">
+          <nano:extend name="planKey" type="string" />
+          <nano:extend name="currentWave" type="integer" />
+        </nano:shape>
+        <nano:shape id="ResolveTrialAttentionIn" name="Clear trial attention — input">
+          <nano:extend name="planKey" type="string" />
+          <nano:extend name="currentWave" type="integer" optional="true" />
+          <nano:extend name="trialMergeWave" type="integer" optional="true" />
+        </nano:shape>
+        <nano:shape id="RecordResultsIn" name="Finalize plan — input">
+          <nano:extend name="planKey" type="string" />
+        </nano:shape>
+      </nano:shapes>
+    </bpmn:extensionElements>
     <bpmn:startEvent id="Start" name="Issue submitted">
       <bpmn:outgoing>f_toEnsureBase</bpmn:outgoing>
     </bpmn:startEvent>
     <bpmn:serviceTask id="ensure-base-branch" name="Ensure base branch">
       <bpmn:extensionElements>
         <zeebe:taskDefinition type="pr.ensure-base-branch" />
+        <zeebe:properties>
+          <zeebe:property name="io.nanobpm.dataEnvelope.in" value="EnsureBaseBranchIn" />
+        </zeebe:properties>
         <zeebe:ioMapping>
           <zeebe:input source="=repo" target="repo" />
           <zeebe:input source="=baseBranch" target="baseBranch" />
@@ -56,6 +85,9 @@
     <bpmn:serviceTask id="record-plan-review" name="Record review &#38; decide">
       <bpmn:extensionElements>
         <zeebe:taskDefinition type="pr.record-plan-review" />
+        <zeebe:properties>
+          <zeebe:property name="io.nanobpm.dataEnvelope.in" value="RecordPlanReviewIn" />
+        </zeebe:properties>
       </bpmn:extensionElements>
       <bpmn:incoming>f_toRecordPlanReview</bpmn:incoming>
       <bpmn:outgoing>f_toGwPlanReview</bpmn:outgoing>
@@ -93,6 +125,9 @@
     <bpmn:serviceTask id="select-wave" name="Select wave">
       <bpmn:extensionElements>
         <zeebe:taskDefinition type="pr.select-wave" />
+        <zeebe:properties>
+          <zeebe:property name="io.nanobpm.dataEnvelope.in" value="SelectWaveIn" />
+        </zeebe:properties>
       </bpmn:extensionElements>
       <bpmn:incoming>f_plan_proceed</bpmn:incoming>
       <bpmn:incoming>f_plan_answer_proceed</bpmn:incoming>
@@ -238,6 +273,9 @@
     <bpmn:serviceTask id="resolve-trial-attention" name="Clear trial attention">
       <bpmn:extensionElements>
         <zeebe:taskDefinition type="pr.resolve-trial-attention" />
+        <zeebe:properties>
+          <zeebe:property name="io.nanobpm.dataEnvelope.in" value="ResolveTrialAttentionIn" />
+        </zeebe:properties>
       </bpmn:extensionElements>
       <bpmn:incoming>f_toGwTrialAnswer</bpmn:incoming>
       <bpmn:outgoing>f_resolveToTrialAnswer</bpmn:outgoing>
@@ -263,6 +301,9 @@
     <bpmn:serviceTask id="record-results" name="Finalize plan">
       <bpmn:extensionElements>
         <zeebe:taskDefinition type="pr.record-results" />
+        <zeebe:properties>
+          <zeebe:property name="io.nanobpm.dataEnvelope.in" value="RecordResultsIn" />
+        </zeebe:properties>
       </bpmn:extensionElements>
       <bpmn:incoming>f_done</bpmn:incoming>
       <bpmn:incoming>f_trialAnswerAbandon</bpmn:incoming>

package/resources/processes/retro.bpmn

@@ -1,12 +1,29 @@
 <?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_retro" targetNamespace="http://nanobpm.io/nano-workforce">
   <bpmn:process id="retro" name="Epic Retrospective" isExecutable="true">
+    <bpmn:extensionElements>
+      <nano:shapes>
+        <nano:shape id="RetroGatherIn" name="Gather learnings — input">
+          <nano:extend name="planKey" type="string" />
+        </nano:shape>
+        <nano:shape id="RetroRecordIn" name="Record retro — input">
+          <nano:extend name="planKey" type="string" />
+          <nano:extend name="retroLearnings" type="integer" optional="true" />
+          <nano:extend name="status" type="string" optional="true" />
+          <nano:extend name="pr" type="string" optional="true" />
+          <nano:extend name="summary" type="string" optional="true" />
+        </nano:shape>
+      </nano:shapes>
+    </bpmn:extensionElements>
     <bpmn:startEvent id="Start" name="Epic complete">
       <bpmn:outgoing>f_start</bpmn:outgoing>
     </bpmn:startEvent>
     <bpmn:serviceTask id="gather" name="Gather learnings">
       <bpmn:extensionElements>
         <zeebe:taskDefinition type="pr.retro-gather" />
+        <zeebe:properties>
+          <zeebe:property name="io.nanobpm.dataEnvelope.in" value="RetroGatherIn" />
+        </zeebe:properties>
       </bpmn:extensionElements>
       <bpmn:incoming>f_start</bpmn:incoming>
       <bpmn:outgoing>f_toSynthesize</bpmn:outgoing>
@@ -27,6 +44,9 @@
     <bpmn:serviceTask id="record" name="Record retro">
       <bpmn:extensionElements>
         <zeebe:taskDefinition type="pr.retro-record" />
+        <zeebe:properties>
+          <zeebe:property name="io.nanobpm.dataEnvelope.in" value="RetroRecordIn" />
+        </zeebe:properties>
       </bpmn:extensionElements>
       <bpmn:incoming>f_toRecord</bpmn:incoming>
       <bpmn:outgoing>f_toEnd</bpmn:outgoing>

package/scripts/pages-contract.test.ts

@@ -267,7 +267,7 @@ test("issue #205: overview is the landing page and first nav item", async () =>
       "merging",
     ],
     plans: ["planning", "dispatched"],
-    feature_runs: ["running", "awaiting_operator"],
+    feature_runs: ["running", "escalated", "awaiting_operator"],
   };
   const grids = (overview.nodes ?? []).filter((n: Json) => n.type === "dataGrid");
   for (const [table, statuses] of Object.entries(expected)) {

package/workers/answer-escalation/worker.ts

@@ -17,6 +17,7 @@
 // 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";
+import type { WorkerInputs } from "../../nano-generated/worker-io.d.ts";
 
 interface Escalation extends Record<string, unknown> {
   id: number;
@@ -34,11 +35,8 @@ interface PullRequest extends Record<string, unknown> {
   updated_at: string;
 }
 
-interface In extends Record<string, unknown> {
-  prKey: string;
-  answer?: string;
-}
-
+// Input typed off the model data envelope (`PrAnswerEscalationIn` in convergence-loop.bpmn) — ADR 0040.
+type In = WorkerInputs["pr.answer-escalation"];
 // 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 {

package/workers/arm-merge/worker.ts

@@ -2,10 +2,10 @@
 // evaluates its mergeability and correlates `merge-ready`. Reached both on entry to the merge
 // stage (after dependencies clear) and after a human answers a merge escalation (re-check).
 import type { AppJobHandler } from "@nanobpm/urban";
+import type { WorkerInputs } from "../../nano-generated/worker-io.d.ts";
 
-interface In extends Record<string, unknown> {
-  prKey: string;
-}
+// Input typed off the model data envelope (`MergeArmIn` in merge-loop.bpmn) — ADR 0040.
+type In = WorkerInputs["pr.arm-merge"];
 
 const handler: AppJobHandler<In> = async (job, app) => {
   await app.data.table("pull_requests", "pr_key").update(job.variables.prKey, {

package/workers/converge-feature/worker.ts

@@ -13,12 +13,10 @@
 import type { AppJobHandler } from "@nanobpm/urban";
 import { featureRuns } from "../../app/feature.ts";
 import { MAX_ROUNDS, parsePr, submitPr } from "../../app/service.ts";
+import type { WorkerInputs } from "../../nano-generated/worker-io.d.ts";
 
-interface In extends Record<string, unknown> {
-  featureKey: string;
-  prKey?: unknown;
-  autoMerge?: unknown;
-}
+// Input typed off the model data envelope (`ConvergeFeatureIn` in feature.bpmn) — ADR 0040.
+type In = WorkerInputs["pr.converge-feature"];
 
 const handler: AppJobHandler<In, Record<string, never>> = async (job, app) => {
   const featureKey = job.variables.featureKey;

package/workers/ensure-base-branch/worker.ts

@@ -10,11 +10,10 @@
 // wrong-rooted branch).
 import type { AppJobHandler } from "@nanobpm/urban";
 import { type EnsureBaseBranchResult, ensureBaseBranch } from "../../app/github.ts";
+import type { WorkerInputs } from "../../nano-generated/worker-io.d.ts";
 
-interface In extends Record<string, unknown> {
-  repo: string;
-  baseBranch: string;
-}
+// Input typed off the model data envelope (`EnsureBaseBranchIn` in plan-fanout.bpmn) — ADR 0040.
+type In = WorkerInputs["pr.ensure-base-branch"];
 interface Out extends Record<string, unknown> {
   baseBranchResult: EnsureBaseBranchResult;
 }

package/workers/finalize/worker.ts

@@ -5,23 +5,11 @@ import type { AppJobHandler } from "@nanobpm/urban";
 import { abandonTokenFromUrl } from "../../app/abandon.ts";
 import { maybeStartRetro } from "../../app/retro.ts";
 import { AUTO_MERGE, ensurePr, startMerge } from "../../app/service.ts";
+import type { WorkerInputs } from "../../nano-generated/worker-io.d.ts";
 
-// Extends Record so the declared fields are typed while the job may still carry
-// other process variables (e.g. io.nanobpm.agentResult, read by transcriptOf).
-interface In extends Record<string, unknown> {
-  prKey: string;
-  repo: string;
-  prNumber: number;
-  prUrl: string;
-  round: number;
-  summary?: string;
-  // Per-request review-only override: when true, stop at `converged` and never hand off to the
-  // merge-loop even if auto-merge is on globally. Set at submit time, carried on the instance.
-  convergeOnly?: boolean;
-  // The per-PR abandon capability URL the agent was handed; its token is preserved on a heal so
-  // the agent's cooperative-abort check keeps resolving (see ensurePr).
-  abandonUrl?: string;
-}
+// Input typed off the model data envelope (`PrFinalizeIn` in convergence-loop.bpmn) — ADR 0040.
+// Framework-injected `io.nanobpm.agentResult` is read through the `Record`-typed `transcriptOf`.
+type In = WorkerInputs["pr.finalize"];
 
 const AGENT_RESULT_KEY = "io.nanobpm.agentResult";
 function transcriptOf(vars: Record<string, unknown>): string | null {

package/workers/mark-merged/worker.ts

@@ -2,10 +2,10 @@
 // `merged` state; the merge audit trail is written by pr.merge, so this only closes the row out.
 import type { AppJobHandler } from "@nanobpm/urban";
 import { maybeStartRetro } from "../../app/retro.ts";
+import type { WorkerInputs } from "../../nano-generated/worker-io.d.ts";
 
-interface In extends Record<string, unknown> {
-  prKey: string;
-}
+// Input typed off the model data envelope (`MarkMergedIn` in merge-loop.bpmn) — ADR 0040.
+type In = WorkerInputs["pr.mark-merged"];
 
 const handler: AppJobHandler<In> = async (job, app) => {
   const now = new Date().toISOString();

package/workers/merge/worker.ts

@@ -15,18 +15,10 @@ import { checkBaseTarget, classifyBaseGuard } from "../../app/baseGuard.ts";
 import { enqueueViaComment, fetchPrState, mergePr } from "../../app/github.ts";
 import { classifyMergeLanding, DEFAULT_MERGE_PROTOCOL, loadMergeProtocol } from "../../app/mergeProtocol.ts";
 import { ensurePr, MERGE_ADMIN, MERGE_METHOD } from "../../app/service.ts";
+import type { WorkerInputs } from "../../nano-generated/worker-io.d.ts";
 
-interface In extends Record<string, unknown> {
-  prKey: string;
-  repo: string;
-  prNumber: number;
-  // Carried by the merge-loop instance (startMerge sets it to the converged round); passed to
-  // the heal so a reconstructed row reflects the real round, not a 1-based default.
-  round?: number;
-  // The per-PR abandon capability URL the agent was handed; its token is preserved on a heal so
-  // the agent's cooperative-abort check keeps resolving (see ensurePr).
-  abandonUrl?: string;
-}
+// Input typed off the model data envelope (`MergeAttemptIn` in merge-loop.bpmn) — ADR 0040.
+type In = WorkerInputs["pr.merge"];
 
 interface Out extends Record<string, unknown> {
   mergeStatus: "merged" | "queued" | "blocked";

package/workers/persist-escalation/worker.ts

@@ -17,29 +17,12 @@ 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";
+import type { WorkerInputs } from "../../nano-generated/worker-io.d.ts";
 
-// Extends Record so the declared fields are typed while the job may still carry
-// other process variables (e.g. io.nanobpm.agentResult, read by transcriptOf).
-interface In extends Record<string, unknown> {
-  prKey: string;
-  round: number;
-  status?: string;
-  summary?: string;
-  question?: string;
-  // Carried by the convergence-loop instance so a missing `pull_requests` parent can be
-  // reconstructed before the FK-child `rounds`/`escalations` inserts.
-  repo?: string;
-  prNumber?: number;
-  prUrl?: string;
-  // The per-PR abandon capability URL the agent was handed; its token is preserved on a heal so
-  // the agent's cooperative-abort check keeps resolving (see ensurePr).
-  abandonUrl?: string;
-  // False on the "review stalled" arm: `persist-round` already recorded this `round` as
-  // `addressed`, so this escalation must not insert a second `rounds` row for the same
-  // `pr_key`/`round_no` (which would record one round as both addressed and blocked). Absent
-  // on the agent-raised / max-rounds arms, where no prior round row exists — so it defaults on.
-  recordRound?: boolean;
-}
+// Input typed off the model data envelope (`EscalationIn` in convergence-loop.bpmn) — ADR 0040.
+// Framework-injected variables (`io.nanobpm.agentResult`, `agent`) are read through the
+// `Record`-typed helpers below rather than the envelope.
+type In = WorkerInputs["pr.persist-escalation"];
 
 // A string variable, or undefined when it is absent, empty, or whitespace-only.
 // The write boundary owns *type* defaults (undefined -> column DEFAULT/NULL); this

package/workers/persist-round/worker.ts

@@ -7,23 +7,13 @@
 import type { AppJobHandler } from "@nanobpm/urban";
 import { abandonTokenFromUrl } from "../../app/abandon.ts";
 import { ensurePr, parsePr } from "../../app/service.ts";
+import type { WorkerInputs } from "../../nano-generated/worker-io.d.ts";
 
-// Extends Record so the declared fields are typed while the job may still carry
-// other process variables (e.g. io.nanobpm.agentResult, read by transcriptOf).
-interface In extends Record<string, unknown> {
-  prKey: string;
-  round: number;
-  status?: string;
-  summary?: string;
-  // Carried by the convergence-loop instance (set at createInstance) so a missing
-  // `pull_requests` parent can be reconstructed before the FK-child `rounds` insert.
-  repo?: string;
-  prNumber?: number;
-  prUrl?: string;
-  // The per-PR abandon capability URL the review agent was handed; its token is preserved on a
-  // heal so the agent's cooperative-abort check keeps resolving (see ensurePr).
-  abandonUrl?: string;
-}
+// Input is typed off the model data envelope (`PrPersistRoundIn` in convergence-loop.bpmn),
+// the single source of truth for this worker's wire contract (ADR 0040). Framework-injected
+// variables the handler still reads (`io.nanobpm.agentResult`, `agent`) are accessed through the
+// `Record<string, unknown>`-typed helpers below rather than the envelope.
+type In = WorkerInputs["pr.persist-round"];
 
 // The harness records the agent's full (byte-capped) stdout on the result envelope; keep it
 // for audit so a human can see what the agent did this round.

package/workers/record-dependency/worker.ts

@@ -13,11 +13,12 @@
 // already-recorded edge is a no-op.
 import type { AppJobHandler } from "@nanobpm/urban";
 import { ensurePr, parsePr } from "../../app/service.ts";
+import type { WorkerInputs } from "../../nano-generated/worker-io.d.ts";
 
-interface In extends Record<string, unknown> {
-  prKey: string;
-  dependsOn?: unknown;
-}
+// Input typed off the model data envelope (`RecordDepIn` in merge-loop.bpmn) — ADR 0040. The
+// scalar `dependsOn` carries the agent's `owner/repo#N` refs as one string; `parseDependsOn` below
+// still tolerates the legacy array shape defensively.
+type In = WorkerInputs["pr.record-dependency"];
 
 interface DependencyRow {
   pr_key: string;

package/workers/record-feature/worker.ts

@@ -14,13 +14,10 @@
 import type { AppJobHandler } from "@nanobpm/urban";
 import { type FeatureRunStatus, featureRuns } from "../../app/feature.ts";
 import { parsePr } from "../../app/service.ts";
+import type { WorkerInputs } from "../../nano-generated/worker-io.d.ts";
 
-interface In extends Record<string, unknown> {
-  featureKey: string;
-  status?: unknown;
-  pr?: unknown;
-  summary?: unknown;
-}
+// Input typed off the model data envelope (`RecordFeatureIn` in feature.bpmn) — ADR 0040.
+type In = WorkerInputs["pr.record-feature"];
 interface Out extends Record<string, unknown> {
   featureStatus: FeatureRunStatus;
   prKey: string | null;
@@ -57,6 +54,12 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
     status: rowStatus,
     pr_key: prKey,
     outcome: summary ?? null,
+    // The run has left the `feature-escalation` wait (answered → abandon, SLA auto-abandon, or the
+    // agent finished without escalating), so clear the denormalised escalation pointer the pages gate
+    // on. pollFeatureEscalations only sweeps `running`/`escalated` runs, so a terminal-ward transition
+    // through here must clear it itself or the stale question would linger on the row.
+    escalation_question: null,
+    escalation_user_task_key: null,
     updated_at: ts,
   });
   app.log.info("record-feature", { featureKey, featureStatus, rowStatus, prKey });

package/workers/record-feature-escalation/worker.test.ts

@@ -0,0 +1,74 @@
+// Unit coverage for pr.record-feature-escalation — a feature run parked on the native
+// `feature-escalation` user task (issue #210). Runs on the `escalated` arm, before the user task
+// exists, and must flip the row to the non-terminal `escalated` status and persist the agent's
+// `question` so the nwf UI can surface it (the poller can't read task-local vars, so this is the
+// question's source of truth). It clears the completable-task pointer to NULL (the task does not
+// exist yet, so any non-null value is stale); the poller fills the real key once it is observable.
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import { noopLog } from "../../test/log.ts";
+import handler from "./worker.ts";
+
+// biome-ignore lint/suspicious/noExplicitAny: tiny in-memory app double, mirrors record-blocked-ack.worker.test
+function fakeApp(rows: Record<string, unknown>[]): any {
+  const stores: Record<string, Record<string, unknown>[]> = { feature_runs: rows };
+  return {
+    data: {
+      table(name: string, key: string) {
+        const store = (stores[name] ??= []);
+        return {
+          // biome-ignore lint/suspicious/noExplicitAny: test double
+          get: (k: any) => Promise.resolve(store.find((r) => r[key] === k)),
+          // biome-ignore lint/suspicious/noExplicitAny: test double
+          find: (q: any) => Promise.resolve(store.filter((r) => Object.entries(q).every(([f, v]) => r[f] === v))),
+          // biome-ignore lint/suspicious/noExplicitAny: test double
+          insert: (row: any) => {
+            store.push(row);
+            return Promise.resolve(store.length);
+          },
+          // biome-ignore lint/suspicious/noExplicitAny: test double
+          update: (k: any, patch: any) => {
+            const row = store.find((r) => r[key] === k);
+            if (row) Object.assign(row, patch);
+            return Promise.resolve(row);
+          },
+        };
+      },
+    },
+    log: noopLog(),
+  };
+}
+
+test("record-feature-escalation: flips the run to escalated and persists the question", async () => {
+  const rows = [{ feature_key: "owner/repo#7", status: "running", escalation_question: null, escalation_user_task_key: null }];
+  const app = fakeApp(rows);
+  const out = await handler(
+    { variables: { featureKey: "owner/repo#7", question: "Which API should I use?" } } as never,
+    app,
+  );
+  assertEquals(out, {});
+  assertEquals(rows[0].status, "escalated");
+  assertEquals(rows[0].escalation_question, "Which API should I use?");
+  // The user task does not exist yet — the pointer is cleared to NULL here (poller fills the real key).
+  assertEquals(rows[0].escalation_user_task_key, null);
+});
+
+test("record-feature-escalation: clears a stale completable-task pointer at escalation entry", async () => {
+  // The task does not exist yet here, so a non-null key can only be stale (a prior escalation's key
+  // left behind, a manual DB repair, etc). Leaving it would bind the pages' answer/abandon affordance
+  // to the wrong task until the poller overwrites it; clear it so the row reads "key unknown here".
+  const rows = [{ feature_key: "owner/repo#9", status: "running", escalation_question: null, escalation_user_task_key: "stale-ut" }];
+  const app = fakeApp(rows);
+  await handler({ variables: { featureKey: "owner/repo#9", question: "Q?" } } as never, app);
+  assertEquals(rows[0].status, "escalated");
+  assertEquals(rows[0].escalation_question, "Q?");
+  assertEquals(rows[0].escalation_user_task_key, null);
+});
+
+test("record-feature-escalation: a blank/absent question is persisted as NULL (badge/affordance stay off)", async () => {
+  const rows = [{ feature_key: "owner/repo#8", status: "running", escalation_question: null }];
+  const app = fakeApp(rows);
+  await handler({ variables: { featureKey: "owner/repo#8", question: "   " } } as never, app);
+  assertEquals(rows[0].status, "escalated");
+  assertEquals(rows[0].escalation_question, null);
+});

package/workers/record-feature-escalation/worker.ts

@@ -0,0 +1,42 @@
+// pr.record-feature-escalation — a feature run has parked on the native `feature-escalation`
+// user task (the agent reported `status:"escalated"` with a non-blank `question`). This service
+// task runs on the `escalated` arm, immediately BEFORE the user task is created, and persists the
+// escalation onto the `feature_runs` row so the nwf UI can surface it (issue #210):
+//   • flips `status` to the non-terminal `escalated` so status-based views and counts flag it, and
+//   • denormalises the agent's `question` for the Escalation column + the answer affordance.
+//
+// It deliberately does NOT record a REAL completable `userTaskKey` — the task does not exist yet at
+// this point — and clears any stale pointer so the row reads "key unknown until observed".
+// `pollFeatureEscalations` (app/service.ts) fills that pointer in once the user task is
+// observable via `searchUserTasks`, which is also the reason the question is captured HERE rather
+// than by the poller: the WASM testkit engine does not surface a user task's ioMapping-mapped local
+// variables through `searchUserTasks`, so the process variable must be persisted while it is still
+// in scope on the job.
+import type { AppJobHandler } from "@nanobpm/urban";
+import { featureRuns } from "../../app/feature.ts";
+import type { WorkerInputs } from "../../nano-generated/worker-io.d.ts";
+
+// Input typed off the model data envelope (`RecordFeatureEscalationIn` in feature.bpmn) — ADR 0040.
+type In = WorkerInputs["pr.record-feature-escalation"];
+
+const nonBlank = (v: unknown): string | null =>
+  typeof v === "string" && v.trim().length > 0 ? v.trim() : null;
+
+const handler: AppJobHandler<In> = async (job, app) => {
+  const featureKey = job.variables.featureKey;
+  const question = nonBlank(job.variables.question);
+  await featureRuns(app.data).update(featureKey, {
+    status: "escalated",
+    escalation_question: question,
+    // The user task does not exist yet, so any non-null pointer here can only be stale (a prior
+    // escalation's key, a manual DB repair). Clear it so the row reads "key unknown until observed"
+    // and the pages don't bind the answer/abandon affordance to a dead task; the poller re-fills the
+    // real key (it can always re-derive it from `searchUserTasks`), so this clear is never lossy.
+    escalation_user_task_key: null,
+    updated_at: new Date().toISOString(),
+  });
+  app.log.info("record-feature-escalation", { featureKey, hasQuestion: question !== null });
+  return {};
+};
+
+export default handler;

package/workers/record-plan/worker.ts

@@ -25,6 +25,9 @@ interface RawTask {
   prompt?: unknown;
   dependsOn?: unknown;
 }
+// NOTE (issue #211): this worker reads an ARRAY input (`tasks: RawTask[]`), which the scalar-only
+// `nano:dataEnvelope` cannot express, so it keeps a hand-written `interface In` pending a decision
+// on extending the envelope schema to arrays. See the PR body's "array inputs" escalation.
 interface In extends Record<string, unknown> {
   planKey: string;
   tasks?: RawTask[];

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

@@ -24,13 +24,10 @@ import {
   type PlanReview,
   planReviews,
 } from "../../app/plan.ts";
+import type { WorkerInputs } from "../../nano-generated/worker-io.d.ts";
 
-interface In extends Record<string, unknown> {
-  planKey: string;
-  approved?: unknown;
-  findings?: unknown;
-  planReviewEpoch?: unknown;
-}
+// Input typed off the model data envelope (`RecordPlanReviewIn` in plan-fanout.bpmn) — ADR 0040.
+type In = WorkerInputs["pr.record-plan-review"];
 interface Out extends Record<string, unknown> {
   planApproved: boolean;
   planEscalated: boolean;

package/workers/record-results/worker.ts

@@ -14,10 +14,10 @@
 import type { AppJobHandler } from "@nanobpm/urban";
 import { BpmnError } from "@nanobpm/urban";
 import { planTasks } from "../../app/plan.ts";
+import type { WorkerInputs } from "../../nano-generated/worker-io.d.ts";
 
-interface In extends Record<string, unknown> {
-  planKey: string;
-}
+// Input typed off the model data envelope (`RecordResultsIn` in plan-fanout.bpmn) — ADR 0040.
+type In = WorkerInputs["pr.record-results"];
 
 const handler: AppJobHandler<In> = async (job, app) => {
   const { planKey } = job.variables;

package/workers/record-trial-merge/worker.ts

@@ -9,6 +9,10 @@ import {
   trialMergeTaskId,
 } from "../../app/trialMerge.ts";
 
+// NOTE (issue #211): this worker reads ARRAY inputs (`waveOpenHeads`, `conflicts`, `failing`), which
+// the scalar-only `nano:dataEnvelope` cannot express, so it keeps a hand-written `interface In`
+// pending a decision on extending the envelope schema to arrays. See the PR body's "array inputs"
+// escalation.
 interface In extends Record<string, unknown> {
   planKey: string;
   currentWave?: unknown;

package/workers/record-wave/worker.ts

@@ -38,6 +38,9 @@ interface Result {
 interface WaveTaskIn {
   id?: unknown;
 }
+// NOTE (issue #211): this worker reads ARRAY inputs (`waveTasks[]`, `waveResults[]`), which the
+// scalar-only `nano:dataEnvelope` cannot express, so it keeps a hand-written `interface In` pending
+// a decision on extending the envelope schema to arrays. See the PR body's "array inputs" escalation.
 interface In extends Record<string, unknown> {
   planKey: string;
   currentWave: number;

package/workers/resolve-trial-attention/worker.ts

@@ -14,12 +14,10 @@
 // and logged rather than thrown.
 import type { AppJobHandler } from "@nanobpm/urban";
 import { resolveTrialMergeAttention } from "../../app/trialMerge.ts";
+import type { WorkerInputs } from "../../nano-generated/worker-io.d.ts";
 
-interface In extends Record<string, unknown> {
-  planKey: string;
-  currentWave?: unknown;
-  trialMergeWave?: unknown;
-}
+// Input typed off the model data envelope (`ResolveTrialAttentionIn` in plan-fanout.bpmn) — ADR 0040.
+type In = WorkerInputs["pr.resolve-trial-attention"];
 
 const waveNo = (v: unknown): number => {
   const n = Math.trunc(Number(v));

package/workers/retro-gather/worker.ts

@@ -5,10 +5,10 @@
 // agent reflects on real material rather than re-deriving it.
 import type { AppJobHandler } from "@nanobpm/urban";
 import { gatherRetro, renderRetroBrief } from "../../app/retro.ts";
+import type { WorkerInputs } from "../../nano-generated/worker-io.d.ts";
 
-interface In extends Record<string, unknown> {
-  planKey: string;
-}
+// Input typed off the model data envelope (`RetroGatherIn` in retro.bpmn) — ADR 0040.
+type In = WorkerInputs["pr.retro-gather"];
 
 interface Out extends Record<string, unknown> {
   retroDigest: string;