@nanobpm/nano-workforce 0.139.3 → 0.139.4

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.139.4](https://github.com/nanobpm/nano-workforce/compare/v0.139.3...v0.139.4) (2026-08-25)
+
+### Bug Fixes
+
+* **delivery-graph:** honor a wait node's per-node poll.timeoutMs + onTimeout ([#462](https://github.com/nanobpm/nano-workforce/issues/462)) ([#545](https://github.com/nanobpm/nano-workforce/issues/545)) ([f91d456](https://github.com/nanobpm/nano-workforce/commit/f91d4561736e0d7b4bbcaf55a7a4ff61a602b82d)), closes [Magikcraft/nano-bpm#978](https://github.com/Magikcraft/nano-bpm/issues/978)
+
 ## [0.139.3](https://github.com/nanobpm/nano-workforce/compare/v0.139.2...v0.139.3) (2026-08-25)
 
 ### Documentation

package/app/deliveryGraph.test.ts

@@ -718,3 +718,16 @@ test("S7 single-target guarded fan-out is NOT an exclusive split — a node whos
   });
   assertEquals(errors, []);
 });
+
+test("a wait node's onTimeout: fail is rejected (unsupported-on-timeout) while continue/escalate validate (#462)", () => {
+  const waitWith = (onTimeout: string) => ({
+    name: "onTimeout",
+    nodes: [{ id: "g", kind: "wait", wait: { kind: "pr", target: "acme/repo#1", match: { prState: "merged" }, onTimeout } }],
+    edges: [],
+  });
+  const err = hasCode(validateDeliveryGraph(waitWith("fail")), "unsupported-on-timeout");
+  assertEquals(err.path, "nodes[0].wait.onTimeout");
+  // continue + escalate are honored — they must NOT raise the unsupported-on-timeout error.
+  assertEquals(validateDeliveryGraph(waitWith("continue")), []);
+  assertEquals(validateDeliveryGraph(waitWith("escalate")), []);
+});

package/app/deliveryGraph.ts

@@ -83,7 +83,8 @@ export type DeliveryGraphErrorCode =
   | "mixed-fan-out"
   | "multiple-defaults"
   | "non-exhaustive-split"
-  | "exclusive-merge-parity";
+  | "exclusive-merge-parity"
+  | "unsupported-on-timeout";
 
 /** A single semantic validation failure. `path` is a JSON-path-qualified pointer at the offending
  * input (`nodes[2].kind`, `edges[1].from`, `nodes[0].emits[1].name`), `message` is human-actionable,
@@ -342,6 +343,21 @@ export function validateDeliveryGraph(graph: unknown): DeliveryGraphError[] {
             });
           }
         }
+        // A `wait` node's `onTimeout: fail` cannot be honored yet: the compiler would emit a terminate
+        // end on the not-ready-at-boundary path, but the engine treats terminate-end events as
+        // parsed-not-executed (Magikcraft/nano-bpm bpmn.rs), so `fail` would silently degrade to a plain
+        // end — the "declared knob silently ignored" defect class. Reject it loudly (path-qualified)
+        // until engine parity lands (Magikcraft/nano-bpm#978), rather than mis-compile it. `escalate`
+        // (default) and `continue` ARE honored.
+        if (kind === "wait" && config.onTimeout === "fail") {
+          errors.push({
+            path: `${path}.${configKey}.onTimeout`,
+            message:
+              "`onTimeout: fail` on a `wait` node is not yet supported (blocked on engine terminate-end " +
+              "execution, Magikcraft/nano-bpm#978); use `escalate` (default) or `continue`",
+            code: "unsupported-on-timeout",
+          });
+        }
       }
     } else if (rawNode.human !== undefined && !isRecord(rawNode.human)) {
       // `human` config is OPTIONAL (formKey/prompt both resolve to a generic fallback in S3), but

package/app/deliveryGraphCompiler.test.ts

@@ -605,3 +605,45 @@ test("S7 compiler: a post-merge node with an extra always-firing producer joins
   assert(/<bpmn:parallelGateway id="gwj\d+"[^>]*name="join into finalize"/.test(r.bpmn), "finalize joins its always-firing producers on a parallel gateway");
   assert(!/<bpmn:exclusiveGateway id="gwm\d+"[^>]*name="join into finalize"/.test(r.bpmn), "finalize is NOT compiled as an exclusive merge");
 });
+
+test("a wait node's onTimeout: continue proceeds past the gate with NO escalation task; escalate (default) keeps the human stop (#462)", async () => {
+  // AC (#462): `onTimeout: continue` routes the not-ready-at-boundary branch straight to the node end
+  // — no `__esc` escalation user task, no human stop — while the default (`escalate`) parks it on the
+  // escalation task. Two sibling wait nodes, one of each, isolate the difference.
+  const graph = {
+    name: "continue vs escalate",
+    nodes: [
+      { id: "soft", kind: "wait", wait: { kind: "pr", target: "acme/repo#1", match: { prState: "merged" }, onTimeout: "continue" } },
+      { id: "hard", kind: "wait", wait: { kind: "pr", target: "acme/repo#2", match: { prState: "merged" }, onTimeout: "escalate" } },
+    ],
+    edges: [{ from: "soft", to: "hard" }],
+  };
+  const r = await compileOk(graph);
+  const softEl = elementForNode(r.bpmn, "soft");
+  const hardEl = elementForNode(r.bpmn, "hard");
+  // continue: no escalation twin for `soft`, and its not-ready boundary flow lands on the node end.
+  assert(!r.bpmn.includes(`delivery-human-task__${softEl}__esc`), "continue emits no escalation user task");
+  assert(
+    r.bpmn.includes(`<bpmn:sequenceFlow id="${softEl}_i4" name="not ready" sourceRef="${softEl}_lastGw" targetRef="${softEl}_end" />`),
+    "continue routes the not-ready boundary branch to the node end",
+  );
+  // escalate: `hard` keeps its escalation twin and routes not-ready to it.
+  assert(r.bpmn.includes(`delivery-human-task__${hardEl}__esc`), "escalate keeps the escalation user task");
+  assert(
+    r.bpmn.includes(`<bpmn:sequenceFlow id="${hardEl}_i4" name="not ready" sourceRef="${hardEl}_lastGw" targetRef="delivery-human-task__${hardEl}__esc" />`),
+    "escalate routes the not-ready boundary branch to the escalation task",
+  );
+});
+
+test("a wait node's onTimeout: fail is rejected at compile with a path-qualified error (blocked on engine terminate-end, #462/#978)", async () => {
+  const errors = await compileFail({
+    name: "fail not yet supported",
+    nodes: [
+      { id: "g", kind: "wait", wait: { kind: "pr", target: "acme/repo#1", match: { prState: "merged" }, onTimeout: "fail" } },
+    ],
+    edges: [],
+  });
+  const hit = errors.find((e) => e.path === "nodes[0].wait.onTimeout");
+  assert(hit, `expected a path-qualified onTimeout error, got ${JSON.stringify(errors)}`);
+  assert(hit?.message.includes("#978"), `the error names the blocking engine issue, got ${hit?.message}`);
+});

package/app/deliveryGraphCompiler.ts

@@ -953,10 +953,16 @@ function serviceBodyLines(
 /** `wait` body: `start → pr.readiness-probe (poll) → ready? → end`, escalating on not-ready or on the
  * `=probeTimeout` engine bound. The probe polls its OWN target, so an unrelated upstream event can
  * never flip it to ready (#274/S2 concurrency-correctness); the `pr` kind (S2) binds `mergedSha`. */
-function waitBodyLines(el: string, node: DeliveryNode): string[] {
+function waitBodyLines(el: string, node: Extract<DeliveryNode, { kind: "wait" }>): string[] {
   const nodeId = node.id;
   const esc = escalationTaskElement(el);
   const emits = normaliseEmits(node);
+  // `onTimeout` routing (#462): `escalate` (default) parks the not-ready-at-boundary token on a
+  // human-completable escalation task; `continue` proceeds past the gate as not-ready WITHOUT a human
+  // stop (a documented sharp edge — the downstream side-effecting node then runs without the awaited
+  // fact). `fail` is rejected earlier at validation (blocked on engine terminate-end, #978), so it
+  // never reaches here.
+  const continueOnTimeout = node.wait?.onTimeout === "continue";
   // Defect A: read-only probe diagnostics seeded onto the escalation task so the operator/agent can
   // tell a genuine "not published yet" from a transient false-negative — the probe's last detail, the
   // resolved target/match, and a compact summary of the candidate releases the probe observed.
@@ -1033,22 +1039,27 @@ function waitBodyLines(el: string, node: DeliveryNode): string[] {
     `        <bpmn:outgoing>${el}_i7</bpmn:outgoing>`,
     `        <bpmn:outgoing>${el}_i4</bpmn:outgoing>`,
     "      </bpmn:exclusiveGateway>",
-    ...escalationTaskLines(
-      esc,
-      nodeId,
-      [`${el}_i4`],
-      `${el}_i5`,
-      waitEscalationContextFeel(nodeId),
-      { resume: { kind: node.kind, emits }, diagnosticInputs },
-    ),
-    `      <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>`,
+    ...(continueOnTimeout
+      ? []
+      : escalationTaskLines(
+          esc,
+          nodeId,
+          [`${el}_i4`],
+          `${el}_i5`,
+          waitEscalationContextFeel(nodeId),
+          { resume: { kind: node.kind, emits }, diagnosticInputs },
+        )),
+    // On `continue`, the not-ready-at-boundary branch (`_i4`) proceeds straight to the node end (no
+    // human stop, no `_i5` escalation-return flow); on `escalate` it parks on the escalation task,
+    // which returns via `_i5`.
+    `      <bpmn:endEvent id="${el}_end"><bpmn:incoming>${el}_i1</bpmn:incoming>${continueOnTimeout ? `<bpmn:incoming>${el}_i4</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`),
+    `      <bpmn:sequenceFlow id="${el}_i4" name="not ready" sourceRef="${el}_lastGw" targetRef="${continueOnTimeout ? `${el}_end` : esc}" />`,
+    ...(continueOnTimeout ? [] : [flow(`${el}_i5`, esc, `${el}_end`)]),
   ];
 }
 

package/app/deliveryRunner.test.ts

@@ -258,6 +258,51 @@ test("a RUN-LEVEL timeout is normalized (lower-case → canonical) and a malform
   }
 });
 
+test("a wait node's per-node poll.timeoutMs drives its escalation boundary while a sibling keeps the run/default (#462)", async () => {
+  // AC (#462): a `wait` node declaring `poll.timeoutMs` seeds nodeInputs.<el>.probeTimeout derived
+  // from that budget (the compiled `=probeTimeout` boundary), while a sibling wait WITHOUT a declared
+  // timeout keeps the run-level value. Mirrors the per-node `everyMs → probePollEvery` override that
+  // already exists — the escalation boundary is the one budget that was silently ignored, so a 7-day
+  // gate escalated at the 30-minute run default.
+  const graph: DeliveryGraph = {
+    name: "per-node wait timeout",
+    nodes: [
+      { id: "long-gate", kind: "wait", wait: { kind: "pr", target: "owner/repo#1", match: { prState: "merged" }, poll: { timeoutMs: 604_800_000 } } },
+      { id: "default-gate", kind: "wait", wait: { kind: "pr", target: "owner/repo#2", match: { prState: "merged" } } },
+    ],
+    edges: [{ from: "long-gate", to: "default-gate" }],
+  };
+  const p = await prepareOk(graph, { probeTimeout: "PT20M", runKey: "run-462" });
+  const waits = Object.values(p.nodeInputs).filter((v) => "gateKey" in v) as Array<{ gateKey: string; probeTimeout: string }>;
+  const byGate = (suffix: string) => waits.find((w) => w.gateKey.endsWith(suffix));
+  // Element ids are positional by sorted node id: default-gate → n0, long-gate → n1.
+  assertEquals(byGate(":n1")?.probeTimeout, "PT604800S"); // 7 days in seconds — the per-node budget wins
+  assertEquals(byGate(":n0")?.probeTimeout, "PT20M"); // sibling keeps the run-level value
+});
+
+test("an invalid per-node poll.timeoutMs/everyMs falls back to the run-level ctx.* override, not the built-in default (#462)", async () => {
+  // Guard against the JS-truthiness gap: a negative `poll.timeoutMs` (`-1`) is truthy, so a bare
+  // `probe.poll?.timeoutMs ? readinessTimeout(probe, {}) : ctx.probeTimeout` would route to
+  // `readinessTimeout(probe, {})`, which rejects `< 1` and — with `env: {}` — returns the built-in
+  // PT30M default, silently discarding the run/dispatch override. An invalid value must fall through
+  // to `ctx.*` (the run-level value) instead. Same for `everyMs`.
+  const graph: DeliveryGraph = {
+    name: "invalid per-node budget",
+    nodes: [
+      {
+        id: "bad-gate",
+        kind: "wait",
+        wait: { kind: "pr", target: "owner/repo#1", match: { prState: "merged" }, poll: { timeoutMs: -1, everyMs: -5 } },
+      },
+    ],
+    edges: [],
+  };
+  const p = await prepareOk(graph, { probeTimeout: "PT20M", probePollEvery: "PT42S", runKey: "run-462b" });
+  const wait = Object.values(p.nodeInputs).find((v) => "gateKey" in v) as { probeTimeout: string; probePollEvery: string } | undefined;
+  assertEquals(wait?.probeTimeout, "PT20M"); // run-level override, NOT the built-in PT30M default
+  assertEquals(wait?.probePollEvery, "PT42S"); // run-level cadence, NOT DEFAULT_EVERY_MS
+});
+
 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");

package/app/deliveryRunner.ts

@@ -17,7 +17,7 @@ import { createHash, randomUUID } from "node:crypto";
 import type { EngineClient } from "@nanobpm/urban";
 import type { DeliveryFact, DeliveryGraph, DeliveryNode } from "../nano-generated/api-io.d.ts";
 import { assertNever, compileDeliveryGraph, DELIVERY_GRAPH_PROCESS_ID } from "./deliveryGraphCompiler.ts";
-import { DEFAULT_EVERY_MS, msToIsoDuration, parseProbe, readinessPollEvery } from "./readiness.ts";
+import { DEFAULT_EVERY_MS, msToIsoDuration, parseProbe, readinessPollEvery, readinessTimeout } from "./readiness.ts";
 import { isoDuration } from "./reviewWait.ts";
 
 /** The content digest of a compiled graph — `sha256(bpmn)[:12]` — the single source of truth for the
@@ -227,11 +227,25 @@ function buildNodeInput(
     }
     case "wait": {
       const probe = parseProbe(node.wait);
+      // Only a VALID, positive per-node budget overrides the run level. Match the `>= 1` predicate
+      // `readinessTimeout`/`readinessPollEvery` apply internally, rather than a bare JS-truthiness
+      // check on `poll.timeoutMs`/`everyMs`: a negative (`-1`) value is truthy, so a truthiness gate
+      // would route to `readinessTimeout(probe, {})`, which then rejects it (`< 1`) and — because
+      // `env` is `{}` — falls back to the *built-in* default (PT30M / DEFAULT_EVERY_MS), silently
+      // discarding the run/dispatch override in `ctx.*`. Gating on the same validity predicate here
+      // makes an invalid per-node value fall through to `ctx.probeTimeout`/`ctx.probePollEvery`.
+      const declaredTimeout = typeof probe.poll?.timeoutMs === "number" && probe.poll.timeoutMs >= 1;
+      const declaredEvery = typeof probe.poll?.everyMs === "number" && probe.poll.everyMs >= 1;
       return {
         gateKey: `${ctx.runKey}:${ctx.element}`,
         probe: node.wait,
-        probeTimeout: ctx.probeTimeout,
-        probePollEvery: probe.poll?.everyMs ? readinessPollEvery(probe, {}) : ctx.probePollEvery,
+        // Per-node escalation boundary (#462): a `wait` node's declared `poll.timeoutMs` drives its
+        // compiled `=probeTimeout` bound, mirroring the `everyMs → probePollEvery` override below —
+        // otherwise a node's poll budget is honored for the interval but silently ignored for the
+        // boundary (a 7-day gate escalated at the 30-minute run default). Falls back to the run-level
+        // `ctx.probeTimeout` (which itself honors the dispatch override / default) when undeclared.
+        probeTimeout: declaredTimeout ? readinessTimeout(probe, {}) : ctx.probeTimeout,
+        probePollEvery: declaredEvery ? readinessPollEvery(probe, {}) : ctx.probePollEvery,
       };
     }
     case "human":

package/openapi.yaml

@@ -1430,7 +1430,14 @@ components:
       description: >-
         A `wait` node — a durable `ReadinessProbe` (ADR 0001 §2) watching an external fact. Reuses the
         existing `ReadinessProbe` shape verbatim (Decision 3 — never a second wait loop); the `pr`
-        merge-state kind is added to that shape by slice S2 and flows in here automatically.
+        merge-state kind is added to that shape by slice S2 and flows in here automatically. The
+        probe's `poll.timeoutMs` sets THIS node's escalation boundary (how long the gate waits before
+        it acts on `onTimeout`), falling back to the run/default when absent (#462). `onTimeout`
+        `escalate` (default) parks the elapsed gate on a human-completable task; `continue` proceeds
+        past the gate as not-ready with NO human stop (a sharp edge — the downstream side-effecting
+        node then runs without the awaited fact); `fail` is NOT yet supported on a delivery `wait`
+        node (blocked on engine terminate-end execution, Magikcraft/nano-bpm#978) and is rejected at
+        compile with a path-qualified error rather than silently degrading.
       allOf:
         - $ref: "#/components/schemas/DeliveryNodeCommon"
         - type: object

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.139.3",
+  "version": "0.139.4",
   "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",