@nanobpm/nano-workforce 0.65.0 → 0.67.0

package/AGENTS.md

@@ -142,13 +142,25 @@ instead of rediscovering them:
   per-child isolation in the testkit). Only vars read by an in-subprocess gateway
   need this — output-only vars (e.g. `summary`, `pr`) are fine.
 
-## Data envelopes are scalar-only
-
-`nano:dataEnvelope` shapes support only **scalar** `nano:extend` types
-(`string`, `integer`, `datetime`, `boolean`) — **not arrays**. When a message
-must carry a list (e.g. failing check names), join it to a scalar (e.g.
-`\n`-separated) in the publisher before it crosses the envelope, and split it on
-the far side if needed.
+## Data envelopes: message payloads are scalar-only; worker I/O shapes support arrays
+
+Two different `nano:dataEnvelope` uses have different rules — don't conflate them:
+
+- **Message payloads are scalar-only.** A `nano:dataEnvelope` that crosses the
+  engine's message correlation supports only **scalar** `nano:extend` types
+  (`string`, `integer`, `datetime`, `boolean`) — **not arrays**. When a message
+  must carry a list (e.g. failing check names), join it to a scalar (e.g.
+  `\n`-separated) in the publisher before it crosses the envelope, and split it on
+  the far side if needed.
+- **Worker job-I/O shapes support `list="true"` arrays.** A service task's
+  `io.nanobpm.dataEnvelope.in`/`.out` shape is codegen/typing-only (no runtime
+  filtering), so `nano:extend … list="true"` (scalar arrays, e.g. `dependsOn`)
+  and `nano:reference … list="true"` (object arrays) are supported end-to-end and
+  derive to `T[]` in the generated types (per #211 — e.g.
+  `RecordPlanIn.tasks: RecordPlanTask[]`, `RecordWaveIn.waveResults`). Prefer
+  deriving a worker's array inputs from the model this way over a hand-typed
+  `interface In`; don't "fix" a modelled `list="true"` array back to a joined
+  scalar.
 
 ## Urban page runtime: rendering primitives are not JS-truthy
 

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [0.67.0](https://github.com/nanobpm/nano-workforce/compare/v0.66.0...v0.67.0) (2026-08-14)
+
+
+### Features
+
+* **agentic:** local-first visibility — on by default, security opt-in (hub) ([#218](https://github.com/nanobpm/nano-workforce/issues/218)) ([ffef1d9](https://github.com/nanobpm/nano-workforce/commit/ffef1d9819679cb6995ad2d2825bce5c6cabccb5)), closes [jwulf/c8ctl-plugin-nano#38](https://github.com/jwulf/c8ctl-plugin-nano/issues/38)
+
+# [0.66.0](https://github.com/nanobpm/nano-workforce/compare/v0.65.0...v0.66.0) (2026-08-14)
+
+
+### Features
+
+* derive record-plan/record-wave/record-trial-merge array inputs from the model ([#212](https://github.com/nanobpm/nano-workforce/issues/212)) ([95f1694](https://github.com/nanobpm/nano-workforce/commit/95f16944918b99107e784eed5ab69a5962365ec4)), closes [#211](https://github.com/nanobpm/nano-workforce/issues/211) [#211](https://github.com/nanobpm/nano-workforce/issues/211) [#211](https://github.com/nanobpm/nano-workforce/issues/211) [#211](https://github.com/nanobpm/nano-workforce/issues/211)
+
 # [0.65.0](https://github.com/nanobpm/nano-workforce/compare/v0.64.0...v0.65.0) (2026-08-13)
 
 

package/SPEC.md

@@ -488,9 +488,18 @@ Start(issue) → plan → record-plan → implement (parallel MI) → record-res
   it raises a non-retryable `NO_WORK_DISPATCHED` incident instead of completing
   green — a no-op run must not masquerade as success (issue #86).
 
-**Payloads are untyped** (no `nano:shapes`/`io.nanobpm.dataEnvelope`): the vocab is
-scalar-only and cannot express the `tasks`/`results` lists, so the workers self-type
-`job.variables` inline (like `finalize`). `urban gen` still emits the four task types.
+**App-worker payloads are typed from the model.** Each `pr.*` service task
+(`record-plan`, `record-wave`, `record-trial-merge`, `select-wave`,
+`record-plan-review`, `resolve-trial-attention`, `record-results`, …) carries an
+`io.nanobpm.dataEnvelope.in` shape whose `nano:shapes` express the `tasks`/`results`
+lists directly: worker job-I/O envelopes support `list="true"` arrays — both
+`nano:extend … list="true"` scalar arrays (e.g. `dependsOn`, `conflicts`) and
+`nano:reference … list="true"` object arrays (e.g. `RecordPlanIn.tasks`,
+`RecordWaveIn.waveResults`) — which derive to `T[]` in the generated task types
+(per #211). This job-I/O shape is codegen/typing-only (no runtime filtering); the
+`scalar-only` constraint applies only to **message payload** envelopes that cross
+correlation at runtime, not to these worker in/out shapes. The **agent** tasks
+(`senior:*`) still self-type `job.variables` inline (like `finalize`).
 
 **Domain model** (`db/migrations/004_planning.sql`): `plans` (one row per issue) +
 `plan_tasks` (one row per slice, tracking its `status`/`pr_key`/`summary`).

package/app/agentic/channel.test.ts

@@ -5,10 +5,11 @@
 // hub is visible via `inspect()`, families mount/tear-down through the seam, and shutdown is clean.
 import { type AddressInfo, createServer, type Server } from "node:http";
 import { test } from "node:test";
+import { createLogger } from "@nanobpm/urban/runtime";
 import { WebSocket } from "ws";
 import { assert, assertEquals } from "#test-assert";
 import { noopLog } from "../../test/log.ts";
-import { type AgenticChannelHandle, mountAgenticChannel } from "./channel.ts";
+import { type AgenticChannelHandle, LOCAL_AGENTIC_TOKEN, mountAgenticChannel } from "./channel.ts";
 import { type AgenticContext, AgenticFamilyRegistry } from "./registry.ts";
 
 const SECRET = "test-agentic-secret";
@@ -242,3 +243,119 @@ test("a missing secret is refused (never mount an open channel)", async (t) => {
   assert(threw, "mountAgenticChannel must reject an empty secret");
   assertEquals(port > 0, true);
 });
+
+test("LOCAL mode (secure:false): the well-known token upgrades with NO credential", async (t) => {
+  const { server, port } = await startHttp();
+  // Local-first default-on: no secret, no credential — a `nano work` worker appears live with the
+  // well-known localhost token alone (security opt-in).
+  const channel = await mountAgenticChannel({
+    server,
+    secret: "",
+    secure: false,
+    data: undefined,
+    log: noopLog(),
+  });
+  t.after(async () => {
+    await channel.teardown();
+    await closeServer(server);
+  });
+
+  const ws = await connect(port, `?token=${LOCAL_AGENTIC_TOKEN}`);
+  assertEquals(ws.readyState, WebSocket.OPEN);
+  assertEquals(channel.hub.connectionCount, 1);
+  assertEquals(channel.inspect().mode, "local");
+  ws.close();
+});
+
+test("LOCAL mode still rejects a wrong token (4401)", async (t) => {
+  const { server, port } = await startHttp();
+  const channel = await mountAgenticChannel({
+    server,
+    secret: "",
+    secure: false,
+    data: undefined,
+    log: noopLog(),
+  });
+  t.after(async () => {
+    await channel.teardown();
+    await closeServer(server);
+  });
+
+  const closedCode = await rejectionCode(port, "?token=not-the-local-token");
+  assertEquals(closedCode, 4401);
+  assertEquals(channel.hub.connectionCount, 0);
+});
+
+/** A capturing `Logger`: records every `(level, msg)` pair the sink receives. */
+function capturingLog(): { log: ReturnType<typeof noopLog>; records: Array<{ level: string; msg: string }> } {
+  const records: Array<{ level: string; msg: string }> = [];
+  const log = createLogger((level: string, msg: string) => {
+    records.push({ level, msg });
+  });
+  return { log, records };
+}
+
+test("LOCAL mode warns when the server is bound to a non-loopback interface", async (t) => {
+  const server = createServer((_req, res) => res.end());
+  await new Promise<void>((resolve) => server.listen(0, "0.0.0.0", resolve));
+  const { log, records } = capturingLog();
+  const channel = await mountAgenticChannel({
+    server,
+    secret: "",
+    secure: false,
+    data: undefined,
+    log,
+  });
+  t.after(async () => {
+    await channel.teardown();
+    await closeServer(server);
+  });
+
+  const warned = records.some((r) => r.level === "warn" && r.msg.includes("not bound to loopback"));
+  assert(warned, "LOCAL mode on a non-loopback bind must warn that the well-known token is exposed");
+});
+
+test("LOCAL mode warns when the server bind address is unverifiable (not listening)", async (t) => {
+  const { server } = await startHttp();
+  // Simulate a server whose bind cannot be verified (e.g. mounted before `listen` resolves):
+  // `address()` returns null, so the LOCAL exposure check cannot confirm a loopback-only bind.
+  const realAddress = server.address.bind(server);
+  server.address = () => null;
+  const { log, records } = capturingLog();
+  const channel = await mountAgenticChannel({
+    server,
+    secret: "",
+    secure: false,
+    data: undefined,
+    log,
+  });
+  t.after(async () => {
+    server.address = realAddress;
+    await channel.teardown();
+    await closeServer(server);
+  });
+
+  const warned = records.some(
+    (r) => r.level === "warn" && r.msg.includes("bind address could not be verified"),
+  );
+  assert(warned, "LOCAL mode on an unbound server must warn that the well-known token is unverifiable");
+});
+
+test("LOCAL mode does NOT warn when the server is bound to loopback", async (t) => {
+  const { server } = await startHttp();
+  const { log, records } = capturingLog();
+  const channel = await mountAgenticChannel({
+    server,
+    secret: "",
+    secure: false,
+    data: undefined,
+    log,
+  });
+  t.after(async () => {
+    await channel.teardown();
+    await closeServer(server);
+  });
+
+  const warned = records.some((r) => r.level === "warn" && r.msg.includes("not bound to loopback"));
+  assert(!warned, "a loopback-bound LOCAL channel is the expected safe case and must not warn");
+});

package/app/agentic/channel.ts

@@ -14,6 +14,7 @@
 // Invariants (ADR 0056): app-tier only, never the engine; the Camunda-8 job protocol (worker⇄engine)
 // is untouched; advisory semantics preserved (a family never gates a BPMN sequence flow).
 import type { Server } from "node:http";
+import type { AddressInfo } from "node:net";
 import {
   AgenticHub,
   sharedSecretAuthenticator,
@@ -26,11 +27,47 @@ import { AgenticFamilyRegistry } from "./registry.ts";
 /** The path the agentic channel is served on, on the app's own port. */
 export const AGENTIC_PATH = "/agentic";
 
+/**
+ * The well-known identity token used in LOCAL mode (security opt-in). Nano is local-first: on a
+ * developer's own machine the visibility channel is on by default with no credential friction, so
+ * the hub and the `nano work` worker agree on this constant, well-known localhost token. It is NOT
+ * a secret — it only gates same-machine dev traffic. In secure mode (`secure: true` + a real
+ * `NANO_AGENTIC_SECRET`) this constant is never used and a real ADR 0028 verifier applies. Keep in
+ * lock-step with the worker constant in jwulf/c8ctl-plugin-nano (`c8ctl-plugin.js` LOCAL_AGENTIC_TOKEN).
+ */
+export const LOCAL_AGENTIC_TOKEN = "nano-local";
+
+/**
+ * True if `addr` (from {@link Server.address}) is a loopback / same-machine bind — the safety
+ * assumption LOCAL mode relies on. A string address is a UNIX domain socket / named pipe (same-host
+ * only) and is treated as safe; a TCP bind is loopback only for `127.0.0.0/8` or `::1`. A wildcard
+ * bind (`0.0.0.0` / `::`) or any specific public interface is NOT loopback, so the well-known
+ * {@link LOCAL_AGENTIC_TOKEN} would be reachable off-box. `null` (an unbound / not-yet-listening
+ * server) is NOT treated as safe — the bind is unverifiable, so callers must handle it explicitly
+ * rather than silently skipping the exposure check.
+ */
+function isLoopbackBind(addr: string | AddressInfo | null): boolean {
+  if (addr === null) return false;
+  if (typeof addr === "string") return true;
+  const host = addr.address;
+  return host === "::1" || host === "::ffff:127.0.0.1" || host.startsWith("127.");
+}
+
 export interface MountAgenticChannelOptions {
   /** The app's own `node:http` server (share its port; `app.httpServer` narrowed to `Server`). */
   readonly server: Server;
-  /** The shared-secret ADR 0028 identity token every valid peer must present as `?token=…`. */
+  /** The shared-secret ADR 0028 identity token every valid peer must present as `?token=…`. In LOCAL
+   * mode (`secure: false`) this may be empty — the hub substitutes {@link LOCAL_AGENTIC_TOKEN}. */
   readonly secret: string;
+  /**
+   * Security mode. Nano is local-first, so this defaults to `true` (strict) at the library level to
+   * keep the fail-closed contract for any caller that doesn't opt in — but `main.ts` passes
+   * `secure: false` whenever no `NANO_AGENTIC_SECRET` is configured, mounting an on-by-default LOCAL
+   * channel: a well-known localhost token ({@link LOCAL_AGENTIC_TOKEN}) and NO required capability
+   * credential. Set `secure: true` (with a real secret) to require an ADR 0028 identity token AND a
+   * capability credential on every upgrade.
+   */
+  readonly secure?: boolean;
   /** The app's SQLite data layer, threaded to family modules (may be absent when data isn't mounted). */
   readonly data: DataLayer | undefined;
   /** A structured logger for lifecycle lines. */
@@ -67,21 +104,56 @@ async function discoverRegistry(log: Logger): Promise<AgenticFamilyRegistry> {
 export async function mountAgenticChannel(
   opts: MountAgenticChannelOptions,
 ): Promise<AgenticChannelHandle> {
-  const { server, secret, data, log } = opts;
-  if (!secret) throw new Error("mountAgenticChannel requires a non-empty identity secret");
+  const { server, data, log } = opts;
+  // Local-first: `secure` defaults to true at the library level (fail-closed for callers that don't
+  // opt in), but `main.ts` passes `secure: false` for the on-by-default LOCAL channel. In LOCAL mode
+  // an empty secret is fine — we substitute the well-known localhost token and drop the credential
+  // requirement so a `nano work` worker appears live with zero configuration.
+  const secure = opts.secure ?? true;
+  const secret = opts.secret || (secure ? "" : LOCAL_AGENTIC_TOKEN);
+  if (secure && !secret) {
+    throw new Error("mountAgenticChannel (secure mode) requires a non-empty identity secret");
+  }
 
   const transport = new WebSocketChannelTransport({ server, path: AGENTIC_PATH });
   const hub = new AgenticHub({
     transport,
-    // A valid identity token PLUS a required capability credential upgrades; either missing/invalid
-    // is rejected (4401 / 4403). Swap in a real ADR 0028 verifier later by passing an Authenticator.
-    authenticator: sharedSecretAuthenticator({ secret, requireCredential: true }),
+    // Secure mode: a valid identity token PLUS a required capability credential upgrades; either
+    // missing/invalid is rejected (4401 / 4403). Swap in a real ADR 0028 verifier later by passing an
+    // Authenticator. LOCAL mode: token-only (the well-known localhost token), no credential required.
+    authenticator: sharedSecretAuthenticator({ secret, requireCredential: secure }),
     onError: (err, connectionId) =>
       log.warn("agentic hub error", { connectionId, err: String(err) }),
   });
   // Share the app's port: the transport rode the existing server, so it is already listening.
   await transport.ready();
 
+  // LOCAL mode gates only on the well-known localhost token, so it is safe ONLY while the server is
+  // bound to loopback. The channel rides the app's server and does not own its bind address, so it
+  // cannot enforce this — but if the server is exposed on a wildcard/public interface, the token is
+  // reachable off-box; warn loudly so an operator either binds to loopback or switches to secure mode.
+  // A `null` address (server not listening yet) is unverifiable — warn rather than silently skipping
+  // the exposure check, since the bind could later resolve to a public interface.
+  if (!secure) {
+    const addr = server.address();
+    if (addr === null) {
+      log.warn(
+        "agentic channel is in LOCAL mode but the server bind address could not be verified " +
+          "(the server is not listening yet) — the well-known LOCAL_AGENTIC_TOKEN cannot be " +
+          "confirmed loopback-only. Mount the channel after the server is listening, set " +
+          "NANO_AGENTIC_SECRET for secure mode, or bind the server to 127.0.0.1.",
+        { mode: "local", bind: null },
+      );
+    } else if (!isLoopbackBind(addr)) {
+      log.warn(
+        "agentic channel is in LOCAL mode but the server is not bound to loopback — the well-known " +
+          "LOCAL_AGENTIC_TOKEN is reachable from other hosts. Set NANO_AGENTIC_SECRET for secure " +
+          "mode, or bind the server to 127.0.0.1.",
+        { mode: "local", bind: typeof addr === "object" ? addr.address : String(addr) },
+      );
+    }
+  }
+
   // If discovery or any family mount throws, the transport + hub are already live: tear down whatever
   // mounted (in reverse) and close the hub before rethrowing, so a failed boot never strands upgrade
   // handlers or half-open connections.
@@ -97,6 +169,7 @@ export async function mountAgenticChannel(
 
   log.info("agentic channel mounted", {
     path: AGENTIC_PATH,
+    mode: secure ? "secure" : "local",
     families: registry.names(),
   });
 
@@ -108,6 +181,7 @@ export async function mountAgenticChannel(
     inspect() {
       return {
         path: AGENTIC_PATH,
+        mode: secure ? "secure" : "local",
         families: registry.names(),
         connections: hub.connectionCount,
         address: hub.address,

package/main.ts

@@ -46,24 +46,40 @@ const app = await runFromEnv({ engine, host, port: PORT, handleSignals: false })
 // Agentic visibility channel (ADR 0056, epic #142). Ride the app's OWN HTTP server so the channel
 // shares the app port (no sidecar). This is the ONLY main.ts wiring for the whole epic — sibling
 // slices (H1/H3/H4) extend it by dropping a family module under `app/agentic/families/`, never here.
-// Mount only when a shared identity secret is configured, so the app never exposes an
-// unauthenticated upgrade; `app.httpServer` is a `node:http` Server once started (undefined on hosts
-// that don't surface one, e.g. Deno).
+//
+// Local-first (security opt-in): Nano is designed for local use, so the channel is ON BY DEFAULT.
+//   - No secret configured  -> LOCAL mode: well-known localhost token, no credential required, so a
+//     `nano work` worker appears live with zero configuration.
+//   - `NANO_AGENTIC_SECRET` (or `NANO_PR_WEBHOOK_SECRET`) set -> SECURE mode: ADR 0028 identity token
+//     + capability credential required on every upgrade.
+//   - `NANO_AGENTIC=off` (or 0/false/no) -> disabled entirely.
+// `app.httpServer` is a `node:http` Server once started (undefined on hosts that don't surface one,
+// e.g. Deno).
 let agentic: AgenticChannelHandle | undefined;
 const agenticSecret = envVar("NANO_AGENTIC_SECRET") ?? envVar("NANO_PR_WEBHOOK_SECRET");
+const agenticDisabled = /^(0|off|false|no)$/i.test(envVar("NANO_AGENTIC") ?? "");
 const httpServer = app.httpServer;
 if (httpServer instanceof Server) {
-  if (agenticSecret) {
+  if (agenticDisabled) {
+    app.log.info("agentic channel disabled (NANO_AGENTIC=off)");
+  } else {
+    const secure = Boolean(agenticSecret);
     agentic = await mountAgenticChannel({
       server: httpServer,
-      secret: agenticSecret,
+      secret: agenticSecret ?? "",
+      secure,
       data: app.data,
       log: app.log,
     });
-  } else {
-    app.log.warn("agentic channel not mounted: set NANO_AGENTIC_SECRET (or NANO_PR_WEBHOOK_SECRET)");
+    if (!secure) {
+      app.log.info(
+        "agentic channel mounted in LOCAL mode (on by default, token-only — a well-known localhost " +
+          "token, no capability credential). Set NANO_AGENTIC_SECRET for secure mode, or " +
+          "NANO_AGENTIC=off to disable.",
+      );
+    }
   }
-} else if (agenticSecret) {
+} else if (!agenticDisabled) {
   app.log.warn("agentic channel not mounted: app.httpServer is not a node:http Server on this host");
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.65.0",
+  "version": "0.67.0",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",

package/resources/processes/plan-fanout.bpmn

@@ -12,6 +12,55 @@
           <nano:extend name="repo" type="string" />
           <nano:extend name="baseBranch" type="string" />
         </nano:shape>
+        <nano:shape id="RecordPlanTask" name="Record plan — raw planner task">
+          <nano:extend name="id" type="string" optional="true" />
+          <nano:extend name="title" type="string" optional="true" />
+          <nano:extend name="prompt" type="string" optional="true" />
+          <nano:extend name="dependsOn" type="string" list="true" optional="true" />
+        </nano:shape>
+        <nano:shape id="RecordPlanIn" name="Record plan — input">
+          <nano:extend name="planKey" type="string" />
+          <nano:reference name="tasks" ref="RecordPlanTask" list="true" />
+          <nano:extend name="note" type="string" optional="true" />
+        </nano:shape>
+        <nano:shape id="RecordWaveTaskRef" name="Record wave — task ref">
+          <nano:extend name="id" type="string" optional="true" />
+        </nano:shape>
+        <nano:shape id="RecordWaveDelta" name="Record wave — task delta">
+          <nano:extend name="contractChange" type="string" optional="true" />
+          <nano:extend name="newlyTouches" type="string" list="true" optional="true" />
+          <nano:extend name="affectsTasks" type="string" list="true" optional="true" />
+          <nano:extend name="constraint" type="string" optional="true" />
+        </nano:shape>
+        <nano:shape id="RecordWaveResult" name="Record wave — agent result">
+          <nano:extend name="status" type="string" optional="true" />
+          <nano:extend name="summary" type="string" optional="true" />
+          <nano:extend name="pr" type="string" optional="true" />
+          <nano:extend name="delta" type="RecordWaveDelta" optional="true" />
+        </nano:shape>
+        <nano:shape id="RecordWaveIn" name="Record wave — input">
+          <nano:extend name="planKey" type="string" />
+          <nano:extend name="currentWave" type="integer" />
+          <nano:extend name="waveCount" type="integer" />
+          <nano:reference name="waveTasks" ref="RecordWaveTaskRef" list="true" />
+          <nano:reference name="waveResults" ref="RecordWaveResult" list="true" />
+        </nano:shape>
+        <nano:shape id="RecordTrialMergeHead" name="Record trial merge — open head">
+          <nano:extend name="repo" type="string" />
+          <nano:extend name="prNumber" type="integer" />
+          <nano:extend name="headRef" type="string" optional="true" />
+          <nano:extend name="headSha" type="string" optional="true" />
+        </nano:shape>
+        <nano:shape id="RecordTrialMergeIn" name="Record trial merge — input">
+          <nano:extend name="planKey" type="string" />
+          <nano:extend name="currentWave" type="integer" optional="true" />
+          <nano:extend name="trialMergeWave" type="integer" optional="true" />
+          <nano:reference name="waveOpenHeads" ref="RecordTrialMergeHead" list="true" />
+          <nano:extend name="result" type="string" optional="true" />
+          <nano:extend name="conflicts" type="string" list="true" optional="true" />
+          <nano:extend name="failing" type="string" list="true" optional="true" />
+          <nano:extend name="summary" type="string" optional="true" />
+        </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" />
@@ -68,6 +117,9 @@
     <bpmn:serviceTask id="record-plan" name="Record plan &#38; levelize">
       <bpmn:extensionElements>
         <zeebe:taskDefinition type="pr.record-plan" />
+        <zeebe:properties>
+          <zeebe:property name="io.nanobpm.dataEnvelope.in" value="RecordPlanIn" />
+        </zeebe:properties>
       </bpmn:extensionElements>
       <bpmn:incoming>f_toRecordPlan</bpmn:incoming>
       <bpmn:outgoing>f_toReviewPlan</bpmn:outgoing>
@@ -215,6 +267,9 @@
     <bpmn:serviceTask id="record-wave" name="Record wave &#38; hand off">
       <bpmn:extensionElements>
         <zeebe:taskDefinition type="pr.record-wave" />
+        <zeebe:properties>
+          <zeebe:property name="io.nanobpm.dataEnvelope.in" value="RecordWaveIn" />
+        </zeebe:properties>
       </bpmn:extensionElements>
       <bpmn:incoming>f_toRecordWave</bpmn:incoming>
       <bpmn:outgoing>f_toTrialNeeded</bpmn:outgoing>
@@ -246,6 +301,9 @@
     <bpmn:serviceTask id="record-trial-merge" name="Record trial merge">
       <bpmn:extensionElements>
         <zeebe:taskDefinition type="pr.record-trial-merge" />
+        <zeebe:properties>
+          <zeebe:property name="io.nanobpm.dataEnvelope.in" value="RecordTrialMergeIn" />
+        </zeebe:properties>
       </bpmn:extensionElements>
       <bpmn:incoming>f_toRecordTrialMerge</bpmn:incoming>
       <bpmn:outgoing>f_toGwTrial</bpmn:outgoing>

package/workers/record-plan/worker.ts

@@ -18,21 +18,12 @@
 import type { AppJobHandler } from "@nanobpm/urban";
 import { planTaskDeps, planTasks } from "../../app/plan.ts";
 import { computeWaves, WaveError, type WaveTask } from "../../app/waves.ts";
+import type { WorkerInputs } from "../../nano-generated/worker-io.d.ts";
 
-interface RawTask {
-  id?: unknown;
-  title?: unknown;
-  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[];
-  note?: string;
-}
+// Input typed off the model data envelope (`RecordPlanIn` in plan-fanout.bpmn) — ADR 0040. The
+// `tasks[]` array field is a `nano:reference` to the `RecordPlanTask` shape (`list="true"`), so it
+// resolves to `RecordPlanTask[]` with no hand-written interface.
+type In = WorkerInputs["pr.record-plan"];
 interface NormalTask {
   id: string;
   title: string;

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

@@ -8,21 +8,13 @@ import {
   trialMergeDecision,
   trialMergeTaskId,
 } from "../../app/trialMerge.ts";
+import type { WorkerInputs } from "../../nano-generated/worker-io.d.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;
-  trialMergeWave?: unknown;
-  waveOpenHeads?: unknown;
-  result?: unknown;
-  conflicts?: unknown;
-  failing?: unknown;
-  summary?: unknown;
-}
+// Input typed off the model data envelope (`RecordTrialMergeIn` in plan-fanout.bpmn) — ADR 0040.
+// The `waveOpenHeads[]` array field is a `nano:reference` to the `RecordTrialMergeHead` shape, and
+// `conflicts[]` / `failing[]` are scalar `list="true"` extends, so all three resolve from the model
+// with no hand-written interface.
+type In = WorkerInputs["pr.record-trial-merge"];
 interface Out extends Record<string, unknown> {
   trialMergeRed: boolean;
   question?: string;

package/workers/record-wave/worker.ts

@@ -28,26 +28,13 @@ import {
 import { parsePr, submitPr } from "../../app/service.ts";
 import { parseTaskDelta, readTaskDeltas, recordTaskDelta } from "../../app/taskDelta.ts";
 import { shouldRunTrialMerge, type TrialMergeHead } from "../../app/trialMerge.ts";
+import type { WorkerInputs } from "../../nano-generated/worker-io.d.ts";
 
-interface Result {
-  status?: unknown;
-  summary?: unknown;
-  pr?: unknown;
-  delta?: unknown;
-}
-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;
-  waveCount: number;
-  waveTasks?: WaveTaskIn[];
-  waveResults?: Result[];
-}
+// Input typed off the model data envelope (`RecordWaveIn` in plan-fanout.bpmn) — ADR 0040. The
+// `waveTasks[]` / `waveResults[]` array fields are `nano:reference`s to the `RecordWaveTaskRef` /
+// `RecordWaveResult` shapes (`list="true"`), so they resolve to `<Shape>[]` with no hand-written
+// interface.
+type In = WorkerInputs["pr.record-wave"];
 interface Out extends Record<string, unknown> {
   currentWave: number;
   hasMoreWaves: boolean;