@nanobpm/nano-workforce 0.63.0 → 0.64.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [0.64.0](https://github.com/nanobpm/nano-workforce/compare/v0.63.0...v0.64.0) (2026-08-13)
+
+
+### Features
+
+* type workers off the generated data envelope ([#201](https://github.com/nanobpm/nano-workforce/issues/201)) ([#208](https://github.com/nanobpm/nano-workforce/issues/208)) ([792083f](https://github.com/nanobpm/nano-workforce/commit/792083f153050862a11224288b0e27e769ab06ba)), closes [nano-ide#225](https://github.com/nano-ide/issues/225) [#225](https://github.com/nanobpm/nano-workforce/issues/225) [#228](https://github.com/nanobpm/nano-workforce/issues/228) [#211](https://github.com/nanobpm/nano-workforce/issues/211) [#211](https://github.com/nanobpm/nano-workforce/issues/211)
+
 # [0.63.0](https://github.com/nanobpm/nano-workforce/compare/v0.62.0...v0.63.0) (2026-08-13)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.63.0",
+  "version": "0.64.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",
@@ -51,7 +51,7 @@
   },
   "dependencies": {
     "@nanobpm/agentic": "^0.1.0",
-    "@nanobpm/urban": "^0.47.0"
+    "@nanobpm/urban": "^0.48.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.11",

package/resources/processes/convergence-loop.bpmn

@@ -28,6 +28,10 @@
           <nano:extend name="round" type="integer" />
           <nano:extend name="status" type="string" optional="true" />
           <nano:extend name="summary" type="string" optional="true" />
+          <nano:extend name="repo" type="string" optional="true" />
+          <nano:extend name="prNumber" type="integer" optional="true" />
+          <nano:extend name="prUrl" type="string" optional="true" />
+          <nano:extend name="abandonUrl" type="string" optional="true" />
         </nano:shape>
         <nano:shape id="EscalationIn" name="Record escalation — input">
           <nano:extend name="prKey" type="string" />
@@ -36,6 +40,10 @@
           <nano:extend name="summary" type="string" optional="true" />
           <nano:extend name="question" type="string" optional="true" />
           <nano:extend name="recordRound" type="boolean" optional="true" />
+          <nano:extend name="repo" type="string" optional="true" />
+          <nano:extend name="prNumber" type="integer" optional="true" />
+          <nano:extend name="prUrl" type="string" optional="true" />
+          <nano:extend name="abandonUrl" type="string" optional="true" />
         </nano:shape>
         <nano:shape id="EscalationOut" name="Record escalation — result">
           <nano:extend name="escalationId" type="integer" optional="true" />
@@ -53,6 +61,8 @@
           <nano:extend name="prUrl" type="string" />
           <nano:extend name="round" type="integer" />
           <nano:extend name="summary" type="string" optional="true" />
+          <nano:extend name="convergeOnly" type="boolean" optional="true" />
+          <nano:extend name="abandonUrl" type="string" optional="true" />
         </nano:shape>
         <nano:shape id="ReviewReady" name="review-ready message payload">
           <nano:extend name="reviewId" type="integer" />

package/resources/processes/feature.bpmn

@@ -1,12 +1,30 @@
 <?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_feature" 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_feature" targetNamespace="http://nanobpm.io/nano-workforce">
   <bpmn:process id="feature" name="Single-issue feature run" isExecutable="true">
+    <bpmn:extensionElements>
+      <nano:shapes>
+        <nano:shape id="RecordFeatureIn" name="Record feature result — input">
+          <nano:extend name="featureKey" type="string" />
+          <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:shape id="ConvergeFeatureIn" name="Converge feature PR — input">
+          <nano:extend name="featureKey" type="string" />
+          <nano:extend name="prKey" type="string" optional="true" />
+          <nano:extend name="autoMerge" type="boolean" optional="true" />
+        </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" />
@@ -59,6 +77,9 @@
     <bpmn:serviceTask id="record-feature" name="Record result">
       <bpmn:extensionElements>
         <zeebe:taskDefinition type="pr.record-feature" />
+        <zeebe:properties>
+          <zeebe:property name="io.nanobpm.dataEnvelope.in" value="RecordFeatureIn" />
+        </zeebe:properties>
       </bpmn:extensionElements>
       <bpmn:incoming>w_done</bpmn:incoming>
       <bpmn:incoming>w_abandon</bpmn:incoming>
@@ -98,6 +119,9 @@
     <bpmn:serviceTask id="converge" name="Hand off to convergence loop">
       <bpmn:extensionElements>
         <zeebe:taskDefinition type="pr.converge-feature" />
+        <zeebe:properties>
+          <zeebe:property name="io.nanobpm.dataEnvelope.in" value="ConvergeFeatureIn" />
+        </zeebe:properties>
       </bpmn:extensionElements>
       <bpmn:incoming>f_converge</bpmn:incoming>
       <bpmn:outgoing>f_toEndConverged</bpmn:outgoing>

package/resources/processes/merge-loop.bpmn

@@ -41,6 +41,8 @@
           <nano:extend name="prKey" type="string" />
           <nano:extend name="repo" type="string" />
           <nano:extend name="prNumber" type="integer" />
+          <nano:extend name="round" type="integer" optional="true" />
+          <nano:extend name="abandonUrl" type="string" optional="true" />
         </nano:shape>
         <nano:shape id="MergeAttemptOut" name="Attempt merge — result">
           <nano:extend name="mergeStatus" type="string" />

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/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;

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;

package/workers/retro-record/worker.ts

@@ -8,16 +8,12 @@
 // exposes the raw transcript under the `io.nanobpm.agentResult` envelope's `.output`.
 import type { AppJobHandler } from "@nanobpm/urban";
 import { recordRetro } from "../../app/retro.ts";
+import type { WorkerInputs } from "../../nano-generated/worker-io.d.ts";
 
 const AGENT_RESULT_KEY = "io.nanobpm.agentResult";
 
-interface In extends Record<string, unknown> {
-  planKey: string;
-  retroLearnings?: number;
-  status?: unknown; // filed | skipped | blocked
-  pr?: unknown; // "<owner>/<repo>#<n>" of the promotion PR, when filed
-  summary?: unknown;
-}
+// Input typed off the model data envelope (`RetroRecordIn` in retro.bpmn) — ADR 0040.
+type In = WorkerInputs["pr.retro-record"];
 
 function asStr(v: unknown): string | null {
   return typeof v === "string" && v.trim() !== "" ? v.trim() : null;
@@ -42,7 +38,7 @@ const handler: AppJobHandler<In> = async (job, app) => {
   const summary = asStr(job.variables.summary);
 
   // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
-  const env = job.variables[AGENT_RESULT_KEY] as { output?: unknown } | undefined;
+  const env = (job.variables as Record<string, unknown>)[AGENT_RESULT_KEY] as { output?: unknown } | undefined;
   const report = typeof env?.output === "string" ? env.output : null;
 
   await recordRetro(app.data, planKey, {

package/workers/select-wave/worker.ts

@@ -16,11 +16,10 @@
 // immediately (the same 0-task path the flat fan-out already relied on).
 import type { AppJobHandler } from "@nanobpm/urban";
 import { plans, planTaskDeps, planTasks } from "../../app/plan.ts";
+import type { WorkerInputs } from "../../nano-generated/worker-io.d.ts";
 
-interface In extends Record<string, unknown> {
-  planKey: string;
-  currentWave: number;
-}
+// Input typed off the model data envelope (`SelectWaveIn` in plan-fanout.bpmn) — ADR 0040.
+type In = WorkerInputs["pr.select-wave"];
 interface WaveTaskOut {
   id: string;
   title: string;