@nanobpm/nano-workforce 0.120.1 → 0.120.2

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+## [0.120.2](https://github.com/nanobpm/nano-workforce/compare/v0.120.1...v0.120.2) (2026-08-22)
+
+
+### Bug Fixes
+
+* **delivery-graph:** attach DI to compiled BPMN via layoutBpmn ([#440](https://github.com/nanobpm/nano-workforce/issues/440)) ([#444](https://github.com/nanobpm/nano-workforce/issues/444)) ([ed87208](https://github.com/nanobpm/nano-workforce/commit/ed87208e3c4d941a88a36ec5cad6c2661e15d587)), closes [#34](https://github.com/nanobpm/nano-workforce/issues/34)
+* **tasks:** surface delivery-graph human gates in the Tasks inbox ([#442](https://github.com/nanobpm/nano-workforce/issues/442)) ([#443](https://github.com/nanobpm/nano-workforce/issues/443)) ([a550e77](https://github.com/nanobpm/nano-workforce/commit/a550e7730fe496f34e1a1017fb84d448a2840f15))
+
 ## [0.120.1](https://github.com/nanobpm/nano-workforce/compare/v0.120.0...v0.120.1) (2026-08-22)
 
 

package/app/deliveryGraphCompiler.test.ts

@@ -16,15 +16,15 @@ import { assert, assertEquals } from "#test-assert";
 import { compileDeliveryGraph } from "./deliveryGraphCompiler.ts";
 
 /** Compile and assert success, returning the narrowed ok-result. */
-function compileOk(graph: unknown) {
-  const r = compileDeliveryGraph(graph);
+async function compileOk(graph: unknown) {
+  const r = await compileDeliveryGraph(graph);
   assert(r.ok, `expected ok:true, got ${JSON.stringify(r)}`);
   return r;
 }
 
 /** Compile and assert failure, returning the errors. */
-function compileFail(graph: unknown) {
-  const r = compileDeliveryGraph(graph);
+async function compileFail(graph: unknown) {
+  const r = await compileDeliveryGraph(graph);
   assert(!r.ok, `expected ok:false, got ${JSON.stringify(r)}`);
   return r.errors;
 }
@@ -57,8 +57,8 @@ const RELEASE_RUNBOOK = {
   ],
 };
 
-test("happy path: a well-formed graph compiles to a full preview with no side effects", () => {
-  const r = compileOk(RELEASE_RUNBOOK);
+test("happy path: a well-formed graph compiles to a full preview with no side effects", async () => {
+  const r = await compileOk(RELEASE_RUNBOOK);
   assertEquals(r.ok, true);
   assert(r.bpmn.includes("<bpmn:process id=\"delivery-graph\""), "bpmn carries the compiled process");
   assert(r.diagram.startsWith("flowchart TD"), "diagram is a mermaid flowchart");
@@ -70,21 +70,21 @@ test("happy path: a well-formed graph compiles to a full preview with no side ef
   assertEquals(r.sideEffects.length, 2);
 });
 
-test("determinism: the same JSON always yields byte-identical bpmn/diagram/resolved", () => {
-  const a = compileOk(RELEASE_RUNBOOK);
-  const b = compileOk(RELEASE_RUNBOOK);
+test("determinism: the same JSON always yields byte-identical bpmn/diagram/resolved", async () => {
+  const a = await compileOk(RELEASE_RUNBOOK);
+  const b = await compileOk(RELEASE_RUNBOOK);
   assertEquals(a.bpmn, b.bpmn);
   assertEquals(a.diagram, b.diagram);
   assertEquals(JSON.stringify(a.resolved), JSON.stringify(b.resolved));
   // Node ORDER in the input must not change the artifact (nodes are sorted by id).
   const shuffled = { ...RELEASE_RUNBOOK, nodes: [...RELEASE_RUNBOOK.nodes].reverse() };
-  const c = compileOk(shuffled);
+  const c = await compileOk(shuffled);
   assertEquals(c.bpmn, a.bpmn);
   assertEquals(c.diagram, a.diagram);
 });
 
-test("trust bound: every node inlines an embedded subProcess delegating to an allowlisted body — no other activity type", () => {
-  const r = compileOk(RELEASE_RUNBOOK);
+test("trust bound: every node inlines an embedded subProcess delegating to an allowlisted body — no other activity type", async () => {
+  const r = await compileOk(RELEASE_RUNBOOK);
   // Each of the 4 nodes compiles to an EMBEDDED subProcess; wait adds one nested retry-loop subProcess (call activities are a no-op on the pinned
   // WASM engine, so delegation is an inlined subProcess sharing the parent scope — never a callActivity).
   assertEquals((r.bpmn.match(/<bpmn:callActivity/g) ?? []).length, 0);
@@ -103,8 +103,8 @@ test("trust bound: every node inlines an embedded subProcess delegating to an al
   assert(/<bpmn:userTask id="delivery-human-task__n\d+__esc"/.test(r.bpmn), "a bounded node inlines an escalation user task");
 });
 
-test("late-binding: a fact-qualified edge threads a boundFacts input into the consumer subProcess", () => {
-  const r = compileOk(RELEASE_RUNBOOK);
+test("late-binding: a fact-qualified edge threads a boundFacts input into the consumer subProcess", async () => {
+  const r = await compileOk(RELEASE_RUNBOOK);
   // `publish.resolvedArtifact -> consume`: the connector subProcess receives the human's emitted fact as
   // a boundFacts list entry, read from the flat `<producerElement>_<fact>` variable the producer publishes.
   // FEEL string literals must use single-quote XML-attribute delimiters (the engine deploy path drops
@@ -114,8 +114,8 @@ test("late-binding: a fact-qualified edge threads a boundFacts input into the co
   assert(boundInput, `boundFacts is a single-quoted FEEL list literal, got: ${r.bpmn.match(/source='[^']*' target="boundFacts"/)?.[0] ?? r.bpmn.match(/source="[^"]*" target="boundFacts"/)?.[0]}`);
 });
 
-test("rejects unknown kind (by construction) with a path-qualified error, nothing compiled", () => {
-  const errors = compileFail({
+test("rejects unknown kind (by construction) with a path-qualified error, nothing compiled", async () => {
+  const errors = await compileFail({
     nodes: [{ id: "x", kind: "deploy", deploy: { target: "prod" } }],
   });
   const e = errors.find((err) => err.path === "nodes[0].kind");
@@ -123,8 +123,8 @@ test("rejects unknown kind (by construction) with a path-qualified error, nothin
   assert(e.message.length > 0);
 });
 
-test("rejects a dependency cycle with a path-qualified error", () => {
-  const errors = compileFail({
+test("rejects a dependency cycle with a path-qualified error", async () => {
+  const errors = await compileFail({
     nodes: [
       { id: "a", kind: "agent", agent: { jobType: "j" } },
       { id: "b", kind: "agent", agent: { jobType: "j" } },
@@ -137,14 +137,14 @@ test("rejects a dependency cycle with a path-qualified error", () => {
   assert(errors.some((e) => /cycle/i.test(e.message)), `expected a cycle error, got ${JSON.stringify(errors)}`);
 });
 
-test("rejects a dangling edge and a bad fact reference, each path-qualified", () => {
-  const dangling = compileFail({
+test("rejects a dangling edge and a bad fact reference, each path-qualified", async () => {
+  const dangling = await compileFail({
     nodes: [{ id: "a", kind: "agent", agent: { jobType: "j" } }],
     edges: [{ from: "a", to: "ghost" }],
   });
   assert(dangling.some((e) => e.path === "edges[0].to"));
 
-  const badFrom = compileFail({
+  const badFrom = await compileFail({
     nodes: [
       { id: "a", kind: "wait", wait: { kind: "http", target: "u" }, emits: [{ name: "x", type: "string" }] },
       { id: "b", kind: "agent", agent: { jobType: "j" } },
@@ -154,8 +154,8 @@ test("rejects a dangling edge and a bad fact reference, each path-qualified", ()
   assert(badFrom.some((e) => e.path === "edges[0].from"));
 });
 
-test("fan-in: a node with two producers gets a parallel JOIN gateway", () => {
-  const r = compileOk({
+test("fan-in: a node with two producers gets a parallel JOIN gateway", async () => {
+  const r = await compileOk({
     nodes: [
       { id: "a", kind: "agent", agent: { jobType: "j" } },
       { id: "b", kind: "agent", agent: { jobType: "j" } },
@@ -171,8 +171,8 @@ test("fan-in: a node with two producers gets a parallel JOIN gateway", () => {
   assertEquals(cNode?.dependsOn, ["a", "b"]);
 });
 
-test("fan-out: a node with two consumers gets a parallel FORK gateway", () => {
-  const r = compileOk({
+test("fan-out: a node with two consumers gets a parallel FORK gateway", async () => {
+  const r = await compileOk({
     nodes: [
       { id: "a", kind: "agent", agent: { jobType: "j" } },
       { id: "b", kind: "agent", agent: { jobType: "j" } },
@@ -186,8 +186,8 @@ test("fan-out: a node with two consumers gets a parallel FORK gateway", () => {
   assert(r.bpmn.includes('name="fan out of a"'), "a fork gateway for node a is emitted");
 });
 
-test("multiple roots fork from Start and multiple leaves join into End", () => {
-  const r = compileOk({
+test("multiple roots fork from Start and multiple leaves join into End", async () => {
+  const r = await compileOk({
     nodes: [
       { id: "r1", kind: "agent", agent: { jobType: "j" } },
       { id: "r2", kind: "agent", agent: { jobType: "j" } },
@@ -198,8 +198,8 @@ test("multiple roots fork from Start and multiple leaves join into End", () => {
   assert(r.bpmn.includes('id="gwj_end"'), "an end join gateway for multiple leaves");
 });
 
-test("humanNodes: extracts prompt/formKey/emits; a click-done node emits nothing", () => {
-  const r = compileOk({
+test("humanNodes: extracts prompt/formKey/emits; a click-done node emits nothing", async () => {
+  const r = await compileOk({
     nodes: [
       {
         id: "publish",
@@ -220,8 +220,8 @@ test("humanNodes: extracts prompt/formKey/emits; a click-done node emits nothing
   assertEquals(ack?.prompt, undefined);
 });
 
-test("sideEffects: agent + connector only; connector carries its dedupeKey", () => {
-  const r = compileOk(RELEASE_RUNBOOK);
+test("sideEffects: agent + connector only; connector carries its dedupeKey", async () => {
+  const r = await compileOk(RELEASE_RUNBOOK);
   const agent = r.sideEffects.find((s) => s.nodeId === "open-b");
   assertEquals(agent?.kind, "agent");
   assert(agent?.description.includes("senior:feature"));
@@ -233,8 +233,8 @@ test("sideEffects: agent + connector only; connector carries its dedupeKey", ()
   assert(!r.sideEffects.some((s) => s.nodeId === "publish"));
 });
 
-test("resolved edges carry the resolved fromNode and the referenced fact", () => {
-  const r = compileOk(RELEASE_RUNBOOK);
+test("resolved edges carry the resolved fromNode and the referenced fact", async () => {
+  const r = await compileOk(RELEASE_RUNBOOK);
   const factEdge = r.resolved.edges.find((e) => e.from === "watch-b.mergedSha");
   assertEquals(factEdge?.fromNode, "watch-b");
   assertEquals(factEdge?.fromFact, "mergedSha");
@@ -243,8 +243,8 @@ test("resolved edges carry the resolved fromNode and the referenced fact", () =>
   assertEquals(plainEdge?.fromFact, undefined);
 });
 
-test("BPMN is structurally coherent: one process start, one process end, every flow endpoint declared", () => {
-  const r = compileOk(RELEASE_RUNBOOK);
+test("BPMN is structurally coherent: one process start, one process end, every flow endpoint declared", async () => {
+  const r = await compileOk(RELEASE_RUNBOOK);
   // The TOP-LEVEL process has exactly one Start and one End (each inlined subProcess has its OWN
   // start/end events, so a raw `<bpmn:startEvent>` count is not the process boundary — the fixed ids are).
   assertEquals((r.bpmn.match(/ id="Start"/g) ?? []).length, 1);
@@ -257,12 +257,12 @@ test("BPMN is structurally coherent: one process start, one process end, every f
   }
 });
 
-test("duplicate fact-qualified edges between the same node pair collapse to ONE sequence flow", () => {
+test("duplicate fact-qualified edges between the same node pair collapse to ONE sequence flow", async () => {
   // `src` emits two facts, both feeding `b` (`src.x -> b` and `src.y -> b`). Adjacency is de-duped by
   // node id, so no fork/join gateway is inserted — the producer wires straight to the consumer. The
   // compiler must therefore collapse the two edges into a SINGLE sequenceFlow so `b` is not scheduled
   // twice (multiple outgoing flows without a diverging gateway is invalid/double-executing BPMN).
-  const r = compileOk({
+  const r = await compileOk({
     nodes: [
       {
         id: "src",
@@ -289,9 +289,37 @@ test("duplicate fact-qualified edges between the same node pair collapse to ONE
   assert(!r.bpmn.includes("<bpmn:parallelGateway"), "no gateway for a single de-duplicated producer/consumer pair");
 });
 
-test("a non-object / empty body is a clean ok:false, never a throw", () => {
-  assert(!compileDeliveryGraph(undefined).ok);
-  assert(!compileDeliveryGraph(null).ok);
-  assert(!compileDeliveryGraph({}).ok);
-  assert(!compileDeliveryGraph({ nodes: [] }).ok);
+test("a non-object / empty body is a clean ok:false, never a throw", async () => {
+  assert(!(await compileDeliveryGraph(undefined)).ok);
+  assert(!(await compileDeliveryGraph(null)).ok);
+  assert(!(await compileDeliveryGraph({})).ok);
+  assert(!(await compileDeliveryGraph({ nodes: [] })).ok);
+});
+
+test("DI (#440): the compiled bpmn carries an auto-laid-out bpmndi:BPMNDiagram — a shape per element, an edge per flow", async () => {
+  // The delivery-graph compiler is the ONE BPMN generated at runtime; every AUTHORED process gets DI
+  // from `npm run layout` (`layoutBpmn`), and before #440 this generated one skipped that pass and
+  // shipped DI-less — a compiled/running graph rendered positionless in the process explorer. The
+  // compiler now runs the SAME `layoutBpmn` autolayout, so the preview `bpmn` (what actually deploys)
+  // carries diagram interchange. This RED/GREEN guard fails on the old DI-less output.
+  const r = await compileOk(RELEASE_RUNBOOK);
+  assert(r.bpmn.includes("<bpmndi:BPMNDiagram"), "compiled bpmn carries a bpmndi:BPMNDiagram");
+  assert(r.bpmn.includes("<bpmndi:BPMNPlane"), "the diagram has a plane");
+  // The top-level plane references the compiled process, so the process explorer can render it.
+  assert(r.bpmn.includes('bpmnElement="delivery-graph"'), "the top-level plane binds to the process id");
+  // A shape per BPMN element and an edge per sequence flow — the same "N shapes + M edges" accounting
+  // `scripts/layout-bpmn.ts` reports. Every declared sequenceFlow gets a BPMNEdge.
+  const shapes = (r.bpmn.match(/<bpmndi:BPMNShape\b/g) ?? []).length;
+  const edges = (r.bpmn.match(/<bpmndi:BPMNEdge\b/g) ?? []).length;
+  const flows = (r.bpmn.match(/<bpmn:sequenceFlow\b/g) ?? []).length;
+  assert(shapes > 0, "at least one BPMNShape is drawn");
+  assertEquals(edges, flows, "every sequence flow gets exactly one BPMNEdge");
+});
+
+test("DI (#440) is deterministic: identical JSON yields byte-identical laid-out bpmn", async () => {
+  // `layoutBpmn` (bpmn-auto-layout) is deterministic given identical semantic input, so adding the
+  // diagram must not break the compiler's "same JSON → byte-identical XML" trust property.
+  const a = await compileOk(RELEASE_RUNBOOK);
+  const b = await compileOk(RELEASE_RUNBOOK);
+  assertEquals(a.bpmn, b.bpmn);
 });

package/app/deliveryGraphCompiler.ts

@@ -23,6 +23,7 @@
 // parallel gateways for genuine fan-out (>1 downstream) and fan-in (>1 upstream). This slice targets
 // the WIRING/SHAPE — the concrete node bodies land in S4.
 
+import { layoutBpmn } from "@nanobpm/urban";
 import type {
   CompileDeliveryGraphErrors,
   CompileDeliveryGraphResult,
@@ -212,8 +213,17 @@ function mustGet<K, V>(map: ReadonlyMap<K, V>, key: K): V {
  * `{ ok:false, errors }` (each error path-qualified) for a malformed one. NEVER deploys, dispatches,
  * or mutates anything — safe to call repeatedly. Deterministic: identical input JSON yields
  * byte-identical output.
+ *
+ * ASYNC because the final step attaches DIAGRAM INTERCHANGE (`bpmndi:BPMNDiagram`) via the toolkit
+ * autolayout (`layoutBpmn` — `bpmn-auto-layout`), the SAME pass every AUTHORED process gets from
+ * `npm run layout` (`scripts/layout-bpmn.ts`). This is the one BPMN in the system generated at
+ * runtime, so without this it was the only one shipping DI-less — unrenderable in the process
+ * explorer (#440). `layoutBpmn` is itself deterministic given identical semantic input, so
+ * "same JSON → byte-identical XML" still holds with the diagram included.
  */
-export function compileDeliveryGraph(graph: unknown): CompileDeliveryGraphResult | CompileDeliveryGraphErrors {
+export async function compileDeliveryGraph(
+  graph: unknown,
+): Promise<CompileDeliveryGraphResult | CompileDeliveryGraphErrors> {
   const validationErrors: DeliveryGraphError[] = validateDeliveryGraph(graph);
   if (validationErrors.length > 0) {
     // Forward every semantic failure verbatim as a wire `{ path, message }` (the stable `code` stays
@@ -354,7 +364,8 @@ export function compileDeliveryGraph(graph: unknown): CompileDeliveryGraphResult
     list.sort((a, b) => byCodeUnit(a.producerElement, b.producerElement) || byCodeUnit(a.fact, b.fact));
   }
 
-  const bpmn = renderBpmn(typed, wirings, numberedFlows, startForkGateway, endJoinGateway, boundInputsByElement);
+  const semanticBpmn = renderBpmn(typed, wirings, numberedFlows, startForkGateway, endJoinGateway, boundInputsByElement);
+  const bpmn = await layoutDeliveryDiagram(semanticBpmn);
   const diagram = renderMermaid(typed, wirings, resolvedEdges, elementById);
   const resolved = buildResolved(typed, wirings, resolvedEdges, producersById);
   const humanNodes = buildHumanNodes(nodes);
@@ -363,6 +374,48 @@ export function compileDeliveryGraph(graph: unknown): CompileDeliveryGraphResult
   return { ok: true, diagram, bpmn, resolved, humanNodes, sideEffects };
 }
 
+/** Attach diagram interchange (`bpmndi:BPMNDiagram`) to the semantic-only compiled BPMN via the
+ * toolkit autolayout — the SAME `layoutBpmn` (`bpmn-auto-layout`) pass `npm run layout` runs over
+ * every authored process (`scripts/layout-bpmn.ts`), so there is ONE layout source, not two. Without
+ * it, a compiled/running delivery graph rendered positionless in the process explorer (#440).
+ *
+ * We do NOT return `layoutBpmn`'s serialized output directly: its moddle round-trip re-serializes the
+ * semantic model, and in doing so normalizes attribute quoting — a single-quote-delimited attribute
+ * with literal double-quotes inside becomes a double-quoted attribute with `&#34;` entities. The
+ * compiler deliberately emits FEEL string literals (`boundFacts`) with SINGLE-quote delimiters because
+ * the WASM engine deploy path does NOT decode those entities before FEEL parsing (see `attr`), so a
+ * round-trip would silently blank every late-bound fact. Instead we keep the compiler's carefully
+ * encoded semantic XML BYTE-FOR-BYTE and graft only the computed `<bpmndi:BPMNDiagram>` block(s) onto
+ * it — the diagram references element ids `layoutBpmn` leaves untouched, so the graft is sound.
+ *
+ * `bpmn-auto-layout` is a real runtime dependency of `@nanobpm/urban` (which re-exports `layoutBpmn`),
+ * but the toolkit no-ops layout (semantic model unchanged, no DI) when it is somehow absent. That
+ * silent no-op is exactly the DI-less bug this fixes, so we FAIL LOUD if the pass produced no diagram.
+ * Deterministic given identical input, preserving the compiler's "same JSON → byte-identical XML". */
+async function layoutDeliveryDiagram(semanticBpmn: string): Promise<string> {
+  const laidOut = await layoutBpmn(semanticBpmn);
+  const start = laidOut.indexOf("<bpmndi:BPMNDiagram");
+  const endTag = "</bpmndi:BPMNDiagram>";
+  const end = laidOut.lastIndexOf(endTag);
+  if (start === -1 || end === -1) {
+    throw new Error(
+      "compileDeliveryGraph: layoutBpmn produced no bpmndi:BPMNDiagram, so the compiled graph would " +
+        "deploy DI-less and render positionless in the process explorer (#440). This usually means the " +
+        "`bpmn-auto-layout` toolkit peer is missing (the toolkit then silently no-ops layout), but it " +
+        "can also indicate a change in `layoutBpmn` output (different namespace prefix/serialization) or " +
+        "an internal layout failure returning semantic-only XML. Ensure `bpmn-auto-layout` is installed " +
+        "as a runtime dependency and that `layoutBpmn` still emits a `<bpmndi:BPMNDiagram>` block.",
+    );
+  }
+  const diagram = laidOut.slice(start, end + endTag.length);
+  const closing = "</bpmn:definitions>";
+  const insertAt = semanticBpmn.lastIndexOf(closing);
+  if (insertAt === -1) {
+    throw new Error("compileDeliveryGraph: compiled BPMN has no </bpmn:definitions> to graft DI into");
+  }
+  return `${semanticBpmn.slice(0, insertAt)}  ${diagram}\n${semanticBpmn.slice(insertAt)}`;
+}
+
 /** Push `value` into `list` (may be undefined for a dangling target, already reported by the
  * validator) only when not already present — keeps adjacency de-duplicated. */
 function pushUnique(list: string[] | undefined, value: string): void {
@@ -485,6 +538,9 @@ function renderBpmn(
     '<bpmn:definitions xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL" ' +
       'xmlns:zeebe="http://camunda.org/schema/zeebe/1.0" ' +
       '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" ' +
       'id="Definitions_delivery_graph" targetNamespace="http://nanobpm.io/nano-workforce">',
   );
   const processName = graph.name ?? "Delivery graph";

package/app/deliveryGraphRun.test.ts

@@ -179,7 +179,7 @@ test("isDeliveryGraphApproved: a side-effecting graph dispatches ONLY with the m
 });
 
 // ── buildHumanLabels / parseHumanLabels ───────────────────────────────────────
-test("buildHumanLabels: maps each human node's compiled user-task element id → its instruction label", () => {
+test("buildHumanLabels: maps each human node's compiled user-task element id → its instruction label", async () => {
   const graph = {
     nodes: [
       { id: "open-b", kind: "agent", agent: { jobType: "j" } },
@@ -188,7 +188,7 @@ test("buildHumanLabels: maps each human node's compiled user-task element id →
     ],
     edges: [{ from: "open-b", to: "publish" }, { from: "publish", to: "ack" }],
   };
-  const compiled = compileDeliveryGraph(graph);
+  const compiled = await compileDeliveryGraph(graph);
   assertEquals(compiled.ok, true);
   if (!compiled.ok) return;
   const labels = buildHumanLabels(compiled);

package/app/deliveryRunner.test.ts

@@ -29,31 +29,42 @@ const GRAPH: DeliveryGraph = {
   ],
 };
 
-function prepareOk(graph: DeliveryGraph, options = {}) {
-  const r = prepareDeliveryGraph(graph, options);
+async function prepareOk(graph: DeliveryGraph, options = {}) {
+  const r = await prepareDeliveryGraph(graph, options);
   assert(r.ok, `expected ok:true, got ${JSON.stringify(r)}`);
   return r.prepared;
 }
 
-test("content-addressed id: deterministic for the same graph, content-sensitive across graphs", () => {
-  const a = prepareOk(GRAPH);
-  const b = prepareOk(GRAPH);
+test("content-addressed id: deterministic for the same graph, content-sensitive across graphs", async () => {
+  const a = await prepareOk(GRAPH);
+  const b = await prepareOk(GRAPH);
   assert(/^delivery-graph-[0-9a-f]{12}$/.test(a.processDefinitionId), `id is content-addressed, got ${a.processDefinitionId}`);
   assertEquals(a.processDefinitionId, b.processDefinitionId);
 
   // A structurally different graph gets a DIFFERENT id (no collision / no accidental redeploy-as-same).
-  const other = prepareOk({ ...GRAPH, nodes: [...GRAPH.nodes, { id: "extra", kind: "agent", agent: { jobType: "senior:feature" } }], edges: [...GRAPH.edges, { from: "consume", to: "extra" }] });
+  const other = await prepareOk({ ...GRAPH, nodes: [...GRAPH.nodes, { id: "extra", kind: "agent", agent: { jobType: "senior:feature" } }], edges: [...GRAPH.edges, { from: "consume", to: "extra" }] });
   assert(other.processDefinitionId !== a.processDefinitionId, "a different graph yields a different id");
 });
 
-test("the deployable BPMN rewrites the base process id to the content-addressed deploy id", () => {
-  const p = prepareOk(GRAPH);
+test("the deployable BPMN rewrites the base process id to the content-addressed deploy id", async () => {
+  const p = await prepareOk(GRAPH);
   assert(p.bpmn.includes(`<bpmn:process id="${p.processDefinitionId}"`), "process id is the content-addressed id");
   assert(!p.bpmn.includes('<bpmn:process id="delivery-graph"'), "the base id no longer appears as the process id");
 });
 
-test("nodeInputs seeds the exact per-kind fields each node's subProcess ioMapping reads", () => {
-  const p = prepareOk(GRAPH, { nodeTimeout: "PT10M", probeTimeout: "PT20M", escalationSlaTimeout: "PT2H", escalationAssignee: "alice", runKey: "run-7" });
+test("DI (#440): the deployable definition carries diagram interchange bound to the rewritten process id", async () => {
+  // The DEPLOYED definition (not just the compile preview) must render in the process explorer, so it
+  // carries the auto-laid-out `bpmndi:BPMNDiagram`. The top-level plane's `bpmnElement` reference is
+  // rewritten in lock-step with the process id, otherwise the deployed diagram would dangle and render
+  // positionless — the exact bug #440 fixes.
+  const p = await prepareOk(GRAPH);
+  assert(p.bpmn.includes("<bpmndi:BPMNDiagram"), "deployable bpmn carries a diagram");
+  assert(p.bpmn.includes(`bpmnElement="${p.processDefinitionId}"`), "the plane binds to the content-addressed id");
+  assert(!p.bpmn.includes('bpmnElement="delivery-graph"'), "no dangling reference to the base process id remains");
+});
+
+test("nodeInputs seeds the exact per-kind fields each node's subProcess ioMapping reads", async () => {
+  const p = await prepareOk(GRAPH, { nodeTimeout: "PT10M", probeTimeout: "PT20M", escalationSlaTimeout: "PT2H", escalationAssignee: "alice", runKey: "run-7" });
   // Element ids are positional by sorted node id: consume, open-b, publish, watch-b → n0..n3.
   const inputs = p.nodeInputs;
   const byField = (pred: (v: Record<string, unknown>) => boolean) => Object.values(inputs).find((v) => pred(v as Record<string, unknown>)) as Record<string, unknown> | undefined;
@@ -74,12 +85,12 @@ test("nodeInputs seeds the exact per-kind fields each node's subProcess ioMappin
   assertEquals(connector, { target: "npm:install", dedupeKey: "consume-1", payload: null, timeout: "PT10M" });
 });
 
-test("wait gateKeys default to a fresh per-run token so concurrent runs of one graph never cross-correlate", () => {
-  const gateKeyOf = (p: ReturnType<typeof prepareOk>) =>
+test("wait gateKeys default to a fresh per-run token so concurrent runs of one graph never cross-correlate", async () => {
+  const gateKeyOf = (p: Awaited<ReturnType<typeof prepareOk>>) =>
     (Object.values(p.nodeInputs).find((v) => "gateKey" in v) as { gateKey?: string } | undefined)?.gateKey;
 
-  const a = prepareOk(GRAPH);
-  const b = prepareOk(GRAPH);
+  const a = await prepareOk(GRAPH);
+  const b = await prepareOk(GRAPH);
   assert(gateKeyOf(a) && gateKeyOf(b), "each run seeds a wait gateKey");
   assert(gateKeyOf(a) !== gateKeyOf(b), "two runs of the same graph get DISTINCT default gate scopes");
   // The gate key must NOT be derived from the (shared) content digest — that is the bug this guards.
@@ -89,12 +100,12 @@ test("wait gateKeys default to a fresh per-run token so concurrent runs of one g
   assertEquals(a.bpmn, b.bpmn);
 
   // An explicit runKey is honoured verbatim (reproducible seed).
-  const seeded = prepareOk(GRAPH, { runKey: "run-7" });
+  const seeded = await prepareOk(GRAPH, { runKey: "run-7" });
   assertEquals(gateKeyOf(seeded), "run-7:n3");
 });
 
-test("a malformed graph returns the S1 compile errors and prepares nothing", () => {
-  const r = prepareDeliveryGraph({ nodes: [{ id: "a", kind: "agent", agent: { jobType: "j" } }], edges: [{ from: "a", to: "ghost" }] } as unknown as DeliveryGraph);
+test("a malformed graph returns the S1 compile errors and prepares nothing", async () => {
+  const r = await prepareDeliveryGraph({ nodes: [{ id: "a", kind: "agent", agent: { jobType: "j" } }], edges: [{ from: "a", to: "ghost" }] } as unknown as DeliveryGraph);
   assert(!r.ok, "a dangling edge fails to prepare");
   assert(r.errors.some((e) => e.path === "edges[0].to"), `expected a dangling-edge error, got ${JSON.stringify(r.errors)}`);
 });

package/app/deliveryRunner.ts

@@ -97,8 +97,11 @@ export type RunDeliveryResult =
  * so each call's `wait` `gateKey`s differ (two concurrent runs of the same graph never cross-correlate);
  * pass an explicit `runKey` for a reproducible seed. Returns the S1 compile errors verbatim for a
  * malformed graph. */
-export function prepareDeliveryGraph(graph: DeliveryGraph, options: DeliveryRunOptions = {}): PrepareDeliveryResult {
-  const compiled = compileDeliveryGraph(graph);
+export async function prepareDeliveryGraph(
+  graph: DeliveryGraph,
+  options: DeliveryRunOptions = {},
+): Promise<PrepareDeliveryResult> {
+  const compiled = await compileDeliveryGraph(graph);
   if (!compiled.ok) return { ok: false, errors: compiled.errors };
 
   const digest = deliveryGraphDigest(compiled.bpmn);
@@ -132,7 +135,7 @@ export async function runDeliveryGraph(
   graph: DeliveryGraph,
   options: DeliveryRunOptions = {},
 ): Promise<RunDeliveryResult> {
-  const prep = prepareDeliveryGraph(graph, options);
+  const prep = await prepareDeliveryGraph(graph, options);
   if (!prep.ok) return prep;
   const { processDefinitionId, bpmn, nodeInputs } = prep.prepared;
 
@@ -150,10 +153,16 @@ export async function runDeliveryGraph(
 }
 
 /** Rewrite the compiled BPMN's base `bpmn:process` id to the content-addressed deploy id. The base id
- * appears exactly once — as the process element's `id` attribute (element ids are `n<i>`/`gw*`/`Start`/
- * `End`, never the process id) — so a single targeted replacement is unambiguous. */
+ * appears exactly once as the process element's `id` attribute (element ids are `n<i>`/`gw*`/`Start`/
+ * `End`, never the process id), and once more as the top-level `bpmndi:BPMNPlane`'s `bpmnElement`
+ * reference back to that process (the diagram interchange the compiler now attaches, #440). Both must
+ * move together, otherwise the deployed definition carries a DANGLING plane reference and renders
+ * positionless — the very bug DI was added to fix. Nested sub-process planes reference `n<i>` element
+ * ids, which are untouched. */
 function rewriteProcessId(bpmn: string, processDefinitionId: string): string {
-  return bpmn.replace(`id="${DELIVERY_GRAPH_PROCESS_ID}"`, `id="${processDefinitionId}"`);
+  return bpmn
+    .replace(`id="${DELIVERY_GRAPH_PROCESS_ID}"`, `id="${processDefinitionId}"`)
+    .replace(`bpmnElement="${DELIVERY_GRAPH_PROCESS_ID}"`, `bpmnElement="${processDefinitionId}"`);
 }
 
 /** Build the `nodeInputs.<element>` seed for one node, per its kind — the exact fields the compiled

package/app/pollUserTasks.test.ts

@@ -535,4 +535,52 @@ test("pollUserTasks (engine-first): pages through a large open set (no first-pag
   }
 
   assertEquals((stores.user_tasks ?? []).length, 150);
-});
+});
+test("pollUserTasks (engine-first): surfaces an inlined delivery-graph human task, enriched + bucketed as `delivery` (issue #442)", async () => {
+  // A delivery-graph `human` node is compiled (S4) as an INLINED user task with a per-node id
+  // `delivery-human-task__<node>` — the bare `delivery-human-task` never appears at runtime. The poller's
+  // leak guards must recognise it through the single-source-of-truth predicate (`userTaskKindLabel` /
+  // `isDeliveryHumanElement`), NOT exact `USER_TASK_KIND_LABELS` membership — else every delivery-graph
+  // human gate is silently dropped from the Tasks inbox and no operator can tick it off (merlin task 35002).
+  const { data, stores } = memData({
+    delivery_graph_runs: [
+      { run_key: "delivery-graph-403eb22e", process_key: "dg-1", status: "running", title: "release runbook" },
+    ],
+  });
+  const restore = stubUserTaskSearch([
+    { userTaskKey: "35002", elementId: "delivery-human-task__n1", processInstanceKey: "dg-1", state: "CREATED" },
+  ]);
+  try {
+    await pollUserTasks(data, fakeEngine({}), REST);
+  } finally {
+    restore();
+  }
+
+  const byKey = Object.fromEntries((stores.user_tasks ?? []).map((r) => [r.user_task_key, r]));
+  assertEquals(Object.keys(byKey), ["35002"]);
+  assertEquals(byKey["35002"].element_id, "delivery-human-task__n1");
+  assertEquals(byKey["35002"].kind_label, "Delivery: human step");
+  assertEquals(byKey["35002"].subject_type, "delivery");
+  assertEquals(byKey["35002"].subject_key, "delivery-graph-403eb22e");
+  assertEquals(byKey["35002"].subject_title, "release runbook");
+});
+
+test("pollUserTasks (engine-first): a delivery-human task on an UNTRACKED run still surfaces (bucketed `delivery`, instance fallback) (issue #442)", async () => {
+  // Even with no `delivery_graph_runs` row referencing the instance, the kind implies its aggregate, so
+  // the row renders and stays answerable — mirroring the orphaned-escalation guarantee (#358).
+  const { data, stores } = memData({});
+  const restore = stubUserTaskSearch([
+    { userTaskKey: "35002", elementId: "delivery-human-task__n1", processInstanceKey: "dg-9", state: "CREATED" },
+  ]);
+  try {
+    await pollUserTasks(data, fakeEngine({}), REST);
+  } finally {
+    restore();
+  }
+
+  const byKey = Object.fromEntries((stores.user_tasks ?? []).map((r) => [r.user_task_key, r]));
+  assertEquals(Object.keys(byKey), ["35002"]);
+  assertEquals(byKey["35002"].kind_label, "Delivery: human step");
+  assertEquals(byKey["35002"].subject_type, "delivery");
+  assertEquals(byKey["35002"].subject_key, "dg-9"); // instance fallback — non-blank so it renders
+});

package/app/service.ts

@@ -29,6 +29,7 @@ import {
 import { isUniqueConstraintFence } from "./dbFence.ts";
 import { deriveDelivery, TERMINAL_STATUSES } from "./delivery.ts";
 import { deliveryGraphRuns, deriveDeliveryPhase, parseHumanLabels } from "./deliveryGraphRun.ts";
+import { isDeliveryHumanElement } from "./deliveryHuman.ts";
 import { fleetSupportsDurableResume } from "./durableResume.ts";
 import { backfillFeatureStages, deriveFeatureDelivery, FEATURE_BLOCKED_ELEMENT, FEATURE_ESCALATION_ELEMENT, FEATURE_RUN_STATUSES, type FeatureRunStatus, featureEscalations, featureRuns } from "./feature.ts";
 import {
@@ -87,9 +88,9 @@ import {
   prEscalations,
   reconcileUserTasks,
   TRIAL_MERGE_ELEMENT,
-  USER_TASK_KIND_LABELS,
   type UserTaskContext,
   type UserTaskRow,
+  userTaskKindLabel,
   userTasks,
 } from "./userTasks.ts";
 import { deriveWaitGate } from "./waitGate.ts";
@@ -2166,7 +2167,7 @@ async function sweepOpenEscalationTasks(base: string, headers: Record<string, st
       // answerable, so a lagging COMPLETED/CANCELED read must never surface a dead affordance (#294).
       if (typeof it.state === "string" && it.state.toUpperCase() !== "CREATED") continue;
       const elementId = typeof it.elementId === "string" ? it.elementId : undefined;
-      if (!elementId || !Object.hasOwn(USER_TASK_KIND_LABELS, elementId)) continue;
+      if (!elementId || userTaskKindLabel(elementId) === undefined) continue;
       const userTaskKey = it.userTaskKey == null ? "" : String(it.userTaskKey);
       if (!userTaskKey || seen.has(userTaskKey)) continue;
       seen.add(userTaskKey);
@@ -2254,7 +2255,7 @@ export async function pollUserTasks(
   // summary for the `conformance-escalation` ack (its instance is tracked on `plan_conformance`, not a
   // delivery aggregate).
   interface Subject {
-    type: "feature" | "plan" | "pr";
+    type: "feature" | "plan" | "pr" | "delivery";
     key: string;
     title?: string | null;
     url?: string | null;
@@ -2278,6 +2279,13 @@ export async function pollUserTasks(
     const plan = await plans(data).get(review.plan_key);
     subjectByInstance.set(review.process_key, { type: "plan", key: review.plan_key, title: plan?.title ?? null, url: plan?.issue_url ?? null, conformanceSummary: review.summary });
   }
+  // A delivery-graph `human` node parks on its run's engine instance; enrich from the run row so the
+  // Tasks inbox shows the graph's title (its `run_key` as the stable subject key), mirroring the
+  // feature/plan/pr enrichment. The row's inlined `delivery-human-task__<node>` id is recognised by
+  // the shared `userTaskKindLabel` predicate, and buckets as `delivery` (below).
+  for (const run of await deliveryGraphRuns(data).all()) {
+    if (run.process_key) subjectByInstance.set(run.process_key, { type: "delivery", key: run.run_key, title: run.title, url: null });
+  }
 
   // Per-element subject type for an ORPHANED task (no subject row) — the kind implies its aggregate even
   // when tracking is lost, so the fallback row still buckets correctly on the page.
@@ -2296,9 +2304,12 @@ export async function pollUserTasks(
   // when the instance is tracked or a per-kind fallback when it is orphaned. Returns `null` for a
   // non-escalation element (the leak guard) so an arbitrary internal user task can never reach the inbox.
   const contextFor = async (elementId: string, userTaskKey: string, processInstanceKey: string): Promise<UserTaskContext | null> => {
-    if (!Object.hasOwn(USER_TASK_KIND_LABELS, elementId)) return null;
+    if (userTaskKindLabel(elementId) === undefined) return null;
     const subj = subjectByInstance.get(processInstanceKey);
-    const subjectType = subj?.type ?? DEFAULT_SUBJECT_TYPE[elementId] ?? "plan";
+    // Orphaned-task fallback: the kind implies its aggregate even when no subject row references the
+    // instance. A delivery-human node's id is inlined (`delivery-human-task__<node>`), so its bucket is
+    // derived from the predicate rather than the static per-element table.
+    const subjectType = subj?.type ?? DEFAULT_SUBJECT_TYPE[elementId] ?? (isDeliveryHumanElement(elementId) ? "delivery" : "plan");
     const subjectKey = subj?.key ?? processInstanceKey;
     let question: string | null = null;
     switch (elementId) {

package/operations/compileDeliveryGraph.test.ts

@@ -29,6 +29,9 @@ test("compile-delivery-graph: a well-formed graph → 200 with the pure preview"
   assertEquals(res.status, 200);
   assertEquals(res.body.ok, true);
   assert(typeof res.body.bpmn === "string" && res.body.bpmn.length > 0);
+  // The compile preview must show what actually deploys — including the auto-laid-out diagram
+  // interchange (#440), so the process explorer can render the previewed graph.
+  assert(res.body.bpmn.includes("<bpmndi:BPMNDiagram"), "the previewed bpmn carries diagram interchange");
   assert(typeof res.body.diagram === "string" && res.body.diagram.length > 0);
   assertEquals(res.body.resolved.nodes.length, 2);
   assertEquals(res.body.humanNodes.length, 1);

package/operations/compileDeliveryGraph.ts

@@ -20,7 +20,7 @@ export default defineOperation("compileDeliveryGraph", async ({ body }, app) =>
   // the SEMANTIC checks (acyclicity, edge integrity, fact resolution) the schema cannot express. A
   // directly-invoked delegate could still pass `undefined` — the compiler reads its input as
   // `unknown` and maps that to a clean `ok:false`, never a 500.
-  const result = compileDeliveryGraph(body);
+  const result = await compileDeliveryGraph(body);
   if (!result.ok) {
     app.log.warn("compile-delivery-graph rejected", { errors: result.errors.length });
     return { status: 400, body: result };

package/operations/dispatchDeliveryGraph.ts

@@ -37,7 +37,7 @@ export default defineOperation("dispatchDeliveryGraph", async (input, app) => {
   // dispatches. A compile failure here surfaces as a clean 400 rather than reaching the start door.
   let approvalToken: string | undefined;
   if (approve) {
-    const compiled = compileDeliveryGraph(parsed.graph);
+    const compiled = await compileDeliveryGraph(parsed.graph);
     if (!compiled.ok) {
       app.log.warn("dispatch-delivery-graph rejected: compile", { errors: compiled.errors.length });
       return {

package/operations/previewDeliveryGraph.ts

@@ -22,7 +22,7 @@ export default defineOperation("previewDeliveryGraph", async ({ body }, app) =>
     app.log.warn("preview-delivery-graph rejected: parse", { message: parsed.error });
     return { status: 400, body: { ok: false, error: parsed.error } };
   }
-  const compiled = compileDeliveryGraph(parsed.graph);
+  const compiled = await compileDeliveryGraph(parsed.graph);
   if (!compiled.ok) {
     app.log.warn("preview-delivery-graph rejected: compile", { errors: compiled.errors.length });
     return {

package/operations/startDeliveryGraph.ts

@@ -56,7 +56,7 @@ export default defineOperation("startDeliveryGraph", async ({ body }, app) => {
 
   // 2) Compile via S1. This yields the deterministic BPMN (→ the content digest / approval token) plus
   //    the graph's shape: its side effects (whether approval is required), human stops, and node count.
-  const compiled = compileDeliveryGraph(graph);
+  const compiled = await compileDeliveryGraph(graph);
   if (!compiled.ok) {
     app.log.warn("start-delivery-graph rejected: compile", { count: compiled.errors.length });
     return { status: 400, body: { ok: false, errors: compiled.errors } };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.120.1",
+  "version": "0.120.2",
   "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",
@@ -59,7 +59,8 @@
   },
   "dependencies": {
     "@nanobpm/agentic": "^0.1.0",
-    "@nanobpm/urban": "^0.75.0"
+    "@nanobpm/urban": "^0.75.0",
+    "bpmn-auto-layout": "^2.0.0-alpha.2"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.11",