@nanobpm/nano-workforce 0.120.0 → 0.120.2

package/CHANGELOG.md

@@ -1,3 +1,18 @@
+## [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)
+
+
+### Bug Fixes
+
+* **readiness:** make pr.readiness-probe single-shot; engine owns retry cadence ([#428](https://github.com/nanobpm/nano-workforce/issues/428)) ([#429](https://github.com/nanobpm/nano-workforce/issues/429)) ([07db031](https://github.com/nanobpm/nano-workforce/commit/07db031f0d5e3f63ff47ffa51583bdef3012a2ab))
+
 # [0.120.0](https://github.com/nanobpm/nano-workforce/compare/v0.119.0...v0.120.0) (2026-08-22)
 
 

package/app/capabilityNeed.test.ts

@@ -106,9 +106,11 @@ test("capabilityNeedToProbeInput: maps a need to the readiness-gate capability p
     planKey: "owner/repo#289",
     taskId: "issue-289",
     probeTimeout: "PT12H",
+    probePollEvery: "PT15S",
   });
   assertEquals(input.gateKey, "owner/repo#289:issue-289:nanobpm/nano-ide#274:@nanobpm/urban");
   assertEquals(input.probeTimeout, "PT12H");
+  assertEquals(input.probePollEvery, "PT15S");
   assertEquals(input.onTimeout, "escalate");
   assertEquals(input.probe.kind, "capability");
   assertEquals(input.probe.target, "github-releases:nanobpm/nano-ide");
@@ -121,7 +123,7 @@ test("capabilityNeedToProbeInput: maps a need to the readiness-gate capability p
 test("capabilityNeedToProbeInput: omits verifyCommand when the need has none", () => {
   const input = capabilityNeedToProbeInput(
     { capabilityRef: "nanobpm/nano-ide#274", package: "@nanobpm/urban" },
-    { planKey: "o/r#1", taskId: "t1", probeTimeout: "PT1H" },
+    { planKey: "o/r#1", taskId: "t1", probeTimeout: "PT1H", probePollEvery: "PT15S" },
   );
   assertEquals(input.probe.match?.verifyCommand, undefined);
 });
@@ -131,7 +133,7 @@ test("capabilityNeedToProbeInput: throws when the handle names no releases sourc
     () =>
       capabilityNeedToProbeInput(
         { capabilityRef: "#274", package: "@nanobpm/urban" },
-        { planKey: "o/r#1", taskId: "t1", probeTimeout: "PT1H" },
+        { planKey: "o/r#1", taskId: "t1", probeTimeout: "PT1H", probePollEvery: "PT15S" },
       ),
     UnresolvableCapabilityRefError,
     "names no owner/repo releases source",

package/app/capabilityNeed.ts

@@ -36,6 +36,7 @@ export interface CapabilityNeed {
 export interface ReadinessProbeInput {
   readonly gateKey: string;
   readonly probeTimeout: string;
+  readonly probePollEvery: string;
   readonly onTimeout?: OnTimeout;
   readonly probe: ReadinessProbe;
 }
@@ -152,7 +153,7 @@ export function capabilityTaskBarrierKey(planKey: string, taskId: string): strin
  * the handle names no releases source. */
 export function capabilityNeedToProbeInput(
   need: CapabilityNeed,
-  opts: { planKey: string; taskId: string; probeTimeout: string },
+  opts: { planKey: string; taskId: string; probeTimeout: string; probePollEvery: string },
 ): ReadinessProbeInput {
   const repo = capabilityReleasesRepo(need.capabilityRef);
   if (!repo) throw new UnresolvableCapabilityRefError(need.capabilityRef);
@@ -170,6 +171,7 @@ export function capabilityNeedToProbeInput(
   return {
     gateKey: capabilityGateKey(opts.planKey, opts.taskId, need.capabilityRef, need.package),
     probeTimeout: opts.probeTimeout,
+    probePollEvery: opts.probePollEvery,
     onTimeout: "escalate",
     probe,
   };

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,25 +70,25 @@ 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);
-  // Each of the 4 nodes compiles to an EMBEDDED subProcess (call activities are a no-op on the pinned
+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);
-  assertEquals((r.bpmn.match(/<bpmn:subProcess /g) ?? []).length, 4);
+  assertEquals((r.bpmn.match(/<bpmn:subProcess /g) ?? []).length, 5);
   assert(!r.bpmn.includes("<bpmn:scriptTask"), "no script task is ever emitted");
   // Each node's inner body delegates to an allowlisted engine-native body: a `serviceTask` typed to a
   // worker (agent → its `senior:*` job; wait → `pr.readiness-probe`; connector → `pr.delivery-connector`)
@@ -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";
@@ -604,6 +660,7 @@ function ioMappingLines(w: NodeWiring, boundInputs: readonly BoundInput[]): stri
       inputs.push({ source: cfg("gateKey"), target: "gateKey" });
       inputs.push({ source: cfg("probe"), target: "probe" });
       inputs.push({ source: cfg("probeTimeout"), target: "probeTimeout" });
+      inputs.push({ source: cfg("probePollEvery"), target: "probePollEvery" });
       break;
     case "human":
       inputs.push({ source: cfg("escalationSlaTimeout"), target: "escalationSlaTimeout" });
@@ -712,33 +769,78 @@ function waitBodyLines(el: string, nodeId: string): string[] {
   const esc = escalationTaskElement(el);
   return [
     `      <bpmn:startEvent id="${el}_start"><bpmn:outgoing>${el}_i0</bpmn:outgoing></bpmn:startEvent>`,
-    `      <bpmn:serviceTask id="${el}_task" name="Probe readiness: ${escapeXml(nodeId)}">`,
+    `      <bpmn:subProcess id="${el}_probeLoop" name="Probe readiness loop: ${escapeXml(nodeId)}">`,
+    "        <bpmn:extensionElements>",
+    "          <zeebe:ioMapping>",
+    '            <zeebe:output source="=ready" target="ready" />',
+    '            <zeebe:output source="=if (is defined(detail)) then detail else null" target="detail" />',
+    '            <zeebe:output source="=if (is defined(resolvedArtifact)) then resolvedArtifact else null" target="resolvedArtifact" />',
+    '            <zeebe:output source="=if (is defined(mergedSha)) then mergedSha else null" target="mergedSha" />',
+    "          </zeebe:ioMapping>",
+    "        </bpmn:extensionElements>",
+    `        <bpmn:incoming>${el}_i0</bpmn:incoming>`,
+    `        <bpmn:outgoing>${el}_i1</bpmn:outgoing>`,
+    `        <bpmn:startEvent id="${el}_loopStart"><bpmn:outgoing>${el}_li0</bpmn:outgoing></bpmn:startEvent>`,
+    `        <bpmn:serviceTask id="${el}_task" name="Probe readiness: ${escapeXml(nodeId)}">`,
+    "          <bpmn:extensionElements>",
+    `            <zeebe:taskDefinition type="${DELEGATE_TASK_TYPE.wait}" />`,
+    "            <zeebe:properties>",
+    '              <zeebe:property name="io.nanobpm.dataEnvelope.in" value="ReadinessProbeIn" />',
+    '              <zeebe:property name="io.nanobpm.dataEnvelope.out" value="ReadinessProbeOut" />',
+    "            </zeebe:properties>",
+    "          </bpmn:extensionElements>",
+    `          <bpmn:incoming>${el}_li0</bpmn:incoming>`,
+    `          <bpmn:incoming>${el}_li4</bpmn:incoming>`,
+    `          <bpmn:outgoing>${el}_li1</bpmn:outgoing>`,
+    "        </bpmn:serviceTask>",
+    `        <bpmn:exclusiveGateway id="${el}_gw" name="ready?" default="${el}_li3">`,
+    `          <bpmn:incoming>${el}_li1</bpmn:incoming>`,
+    `          <bpmn:outgoing>${el}_li2</bpmn:outgoing>`,
+    `          <bpmn:outgoing>${el}_li3</bpmn:outgoing>`,
+    "        </bpmn:exclusiveGateway>",
+    `        <bpmn:intermediateCatchEvent id="${el}_waitPoll" name="Wait poll interval">`,
+    `          <bpmn:incoming>${el}_li3</bpmn:incoming>`,
+    `          <bpmn:outgoing>${el}_li4</bpmn:outgoing>`,
+    `          <bpmn:timerEventDefinition id="${el}_pollTed"><bpmn:timeDuration xsi:type="bpmn:tFormalExpression">=probePollEvery</bpmn:timeDuration></bpmn:timerEventDefinition>`,
+    "        </bpmn:intermediateCatchEvent>",
+    `        <bpmn:endEvent id="${el}_loopEnd"><bpmn:incoming>${el}_li2</bpmn:incoming></bpmn:endEvent>`,
+    flow(`${el}_li0`, `${el}_loopStart`, `${el}_task`),
+    flow(`${el}_li1`, `${el}_task`, `${el}_gw`),
+    `      <bpmn:sequenceFlow id="${el}_li2" name="ready" sourceRef="${el}_gw" targetRef="${el}_loopEnd"><bpmn:conditionExpression xsi:type="bpmn:tFormalExpression">=ready = true</bpmn:conditionExpression></bpmn:sequenceFlow>`,
+    `        <bpmn:sequenceFlow id="${el}_li3" name="not ready" sourceRef="${el}_gw" targetRef="${el}_waitPoll" />`,
+    flow(`${el}_li4`, `${el}_waitPoll`, `${el}_task`),
+    "      </bpmn:subProcess>",
+    `      <bpmn:boundaryEvent id="${el}_be" name="Gate timed out" attachedToRef="${el}_probeLoop">`,
+    `        <bpmn:outgoing>${el}_i2</bpmn:outgoing>`,
+    `        <bpmn:timerEventDefinition id="${el}_ted"><bpmn:timeDuration xsi:type="bpmn:tFormalExpression">=probeTimeout</bpmn:timeDuration></bpmn:timerEventDefinition>`,
+    "      </bpmn:boundaryEvent>",
+    `      <bpmn:serviceTask id="${el}_lastAttempt" name="Probe readiness at boundary: ${escapeXml(nodeId)}">`,
     "        <bpmn:extensionElements>",
     `          <zeebe:taskDefinition type="${DELEGATE_TASK_TYPE.wait}" />`,
     "          <zeebe:properties>",
     '            <zeebe:property name="io.nanobpm.dataEnvelope.in" value="ReadinessProbeIn" />',
     '            <zeebe:property name="io.nanobpm.dataEnvelope.out" value="ReadinessProbeOut" />',
     "          </zeebe:properties>",
+    "          <zeebe:ioMapping>",
+    '            <zeebe:input source="=true" target="lastAttempt" />',
+    "          </zeebe:ioMapping>",
     "        </bpmn:extensionElements>",
-    `        <bpmn:incoming>${el}_i0</bpmn:incoming>`,
-    `        <bpmn:outgoing>${el}_i1</bpmn:outgoing>`,
+    `        <bpmn:incoming>${el}_i2</bpmn:incoming>`,
+    `        <bpmn:outgoing>${el}_i6</bpmn:outgoing>`,
     "      </bpmn:serviceTask>",
-    `      <bpmn:boundaryEvent id="${el}_be" name="Gate timed out" attachedToRef="${el}_task">`,
-    `        <bpmn:outgoing>${el}_i2</bpmn:outgoing>`,
-    `        <bpmn:timerEventDefinition id="${el}_ted"><bpmn:timeDuration xsi:type="bpmn:tFormalExpression">=probeTimeout</bpmn:timeDuration></bpmn:timerEventDefinition>`,
-    "      </bpmn:boundaryEvent>",
-    `      <bpmn:exclusiveGateway id="${el}_gw" name="ready?" default="${el}_i4">`,
-    `        <bpmn:incoming>${el}_i1</bpmn:incoming>`,
-    `        <bpmn:outgoing>${el}_i3</bpmn:outgoing>`,
+    `      <bpmn:exclusiveGateway id="${el}_lastGw" name="ready after boundary?" default="${el}_i4">`,
+    `        <bpmn:incoming>${el}_i6</bpmn:incoming>`,
+    `        <bpmn:outgoing>${el}_i7</bpmn:outgoing>`,
     `        <bpmn:outgoing>${el}_i4</bpmn:outgoing>`,
     "      </bpmn:exclusiveGateway>",
-    ...escalationTaskLines(esc, nodeId, [`${el}_i2`, `${el}_i4`], `${el}_i5`),
-    `      <bpmn:endEvent id="${el}_end"><bpmn:incoming>${el}_i3</bpmn:incoming><bpmn:incoming>${el}_i5</bpmn:incoming></bpmn:endEvent>`,
-    flow(`${el}_i0`, `${el}_start`, `${el}_task`),
-    flow(`${el}_i1`, `${el}_task`, `${el}_gw`),
-    flow(`${el}_i2`, `${el}_be`, esc),
-    `      <bpmn:sequenceFlow id="${el}_i3" name="ready" sourceRef="${el}_gw" targetRef="${el}_end"><bpmn:conditionExpression xsi:type="bpmn:tFormalExpression">=ready = true</bpmn:conditionExpression></bpmn:sequenceFlow>`,
-    `      <bpmn:sequenceFlow id="${el}_i4" name="not ready" sourceRef="${el}_gw" targetRef="${esc}" />`,
+    ...escalationTaskLines(esc, nodeId, [`${el}_i4`], `${el}_i5`),
+    `      <bpmn:endEvent id="${el}_end"><bpmn:incoming>${el}_i1</bpmn:incoming><bpmn:incoming>${el}_i5</bpmn:incoming><bpmn:incoming>${el}_i7</bpmn:incoming></bpmn:endEvent>`,
+    flow(`${el}_i0`, `${el}_start`, `${el}_probeLoop`),
+    flow(`${el}_i1`, `${el}_probeLoop`, `${el}_end`),
+    flow(`${el}_i2`, `${el}_be`, `${el}_lastAttempt`),
+    flow(`${el}_i6`, `${el}_lastAttempt`, `${el}_lastGw`),
+    `      <bpmn:sequenceFlow id="${el}_i7" name="ready" sourceRef="${el}_lastGw" targetRef="${el}_end"><bpmn:conditionExpression xsi:type="bpmn:tFormalExpression">=ready = true</bpmn:conditionExpression></bpmn:sequenceFlow>`,
+    `      <bpmn:sequenceFlow id="${el}_i4" name="not ready" sourceRef="${el}_lastGw" targetRef="${esc}" />`,
     flow(`${el}_i5`, esc, `${el}_end`),
   ];
 }

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