@nanobpm/nano-workforce 0.133.1 → 0.134.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.134.0](https://github.com/nanobpm/nano-workforce/compare/v0.133.1...v0.134.0) (2026-08-24)
+
+### Features
+
+* **delivery-graph:** node timeout PT1H default, submission + per-node override ([#505](https://github.com/nanobpm/nano-workforce/issues/505)) ([#507](https://github.com/nanobpm/nano-workforce/issues/507)) ([96fe961](https://github.com/nanobpm/nano-workforce/commit/96fe96165bb898919f7000002e68cb4ba5a925e9))
+
 ## [0.133.1](https://github.com/nanobpm/nano-workforce/compare/v0.133.0...v0.133.1) (2026-08-24)
 
 ### Bug Fixes

package/app/deliveryGraphDispatch.ts

@@ -23,6 +23,7 @@ import {
   DELIVERY_PHASE,
   deliveryGraphRuns,
 } from "./deliveryGraphRun.ts";
+import type { DeliveryRunTimeouts } from "./deliveryRunner.ts";
 import { deliveryGraphDigest, runDeliveryGraph } from "./deliveryRunner.ts";
 
 /** The outcome of a dispatch attempt — mirrors the retained run lifecycle. `ok:false` carries the
@@ -48,7 +49,7 @@ export type DispatchDeliveryGraphResult =
 export async function dispatchDeliveryGraphRun(
   app: Pick<AppApi, "data" | "engine" | "log">,
   graph: unknown,
-  options: { runKey?: string | null; title?: string | null } = {},
+  options: { runKey?: string | null; title?: string | null } & DeliveryRunTimeouts = {},
 ): Promise<DispatchDeliveryGraphResult> {
   const validationErrors = validateDeliveryGraph(graph);
   if (validationErrors.length > 0) {
@@ -130,7 +131,16 @@ export async function dispatchDeliveryGraphRun(
   };
   let launched: Awaited<ReturnType<typeof runDeliveryGraph>>;
   try {
-    launched = await runDeliveryGraph(app.engine, typedGraph, { runKey });
+    // Thread the operator-supplied run-level timeouts (#505) so a submission override reaches every
+    // node's seeded `nodeInputs` (absent → the runner's PT1H/PT30M/P1D defaults).
+    launched = await runDeliveryGraph(app.engine, typedGraph, {
+      runKey,
+      nodeTimeout: options.nodeTimeout,
+      probeTimeout: options.probeTimeout,
+      escalationSlaTimeout: options.escalationSlaTimeout,
+      probePollEvery: options.probePollEvery,
+      escalationAssignee: options.escalationAssignee,
+    });
   } catch (err) {
     await markClaimFailed();
     app.log.error("dispatch-delivery-graph launch threw", { runKey });

package/app/deliveryRunner.test.ts

@@ -138,6 +138,93 @@ test("wait gateKeys default to a fresh per-run token so concurrent runs of one g
   assertEquals(gateKeyOf(seeded), "run-7:n3");
 });
 
+test("the node timeout defaults to PT1H (raised from PT30M) when no option is supplied (#505)", async () => {
+  // #505: the hard PT30M default tripped the boundary timer on legitimately-long implementation nodes.
+  // With no timeout option, every agent/connector node inherits the NEW PT1H run default.
+  const p = await prepareOk(GRAPH);
+  const timeouts = Object.values(p.nodeInputs)
+    .filter((v) => "timeout" in v)
+    .map((v) => (v as { timeout: string }).timeout);
+  assert(timeouts.length === 2, `expected the agent + connector nodes to seed a timeout, got ${timeouts.length}`);
+  for (const t of timeouts) assertEquals(t, "PT1H");
+});
+
+test("a submission nodeTimeout override seeds every agent/connector node with that duration (#505)", async () => {
+  // AC: an operator dispatch that sets nodeTimeout: "PT2H" seeds PT2H for ALL agent/connector nodes.
+  const p = await prepareOk(GRAPH, { nodeTimeout: "PT2H" });
+  const timeouts = Object.values(p.nodeInputs)
+    .filter((v) => "timeout" in v)
+    .map((v) => (v as { timeout: string }).timeout);
+  assert(timeouts.length === 2, `expected two seeded node timeouts, got ${timeouts.length}`);
+  for (const t of timeouts) assertEquals(t, "PT2H");
+});
+
+test("a per-node timeout override wins for its node while siblings keep the run/default value (#505)", async () => {
+  // AC: a node declaring timeout: "PT4H" seeds nodeInputs.<el>.timeout == "PT4H" while its siblings keep
+  // the run-level (here PT2H) value. Asserted positionally on the compiled nodeInputs map.
+  const graph: DeliveryGraph = {
+    name: "per-node override",
+    nodes: [
+      { id: "heavy", kind: "agent", agent: { jobType: "senior:feature", prompt: "long build", timeout: "PT4H" } },
+      { id: "quick", kind: "agent", agent: { jobType: "senior:demo" } },
+      { id: "notify", kind: "connector", connector: { target: "slack:post", dedupeKey: "n-1", timeout: "PT10M" } },
+    ],
+    edges: [
+      { from: "heavy", to: "quick" },
+      { from: "quick", to: "notify" },
+    ],
+  };
+  const p = await prepareOk(graph, { nodeTimeout: "PT2H" });
+  const byJobType = (jt: string) =>
+    Object.values(p.nodeInputs).find((v) => (v as { jobType?: string }).jobType === jt) as { timeout: string } | undefined;
+  const connector = Object.values(p.nodeInputs).find((v) => (v as { target?: string }).target === "slack:post") as
+    | { timeout: string }
+    | undefined;
+
+  assertEquals(byJobType("senior:feature")?.timeout, "PT4H"); // per-node override wins
+  assertEquals(byJobType("senior:demo")?.timeout, "PT2H"); // sibling keeps the run-level value
+  assertEquals(connector?.timeout, "PT10M"); // connector per-node override wins too
+});
+
+test("a per-node timeout is normalized (lower-case → canonical) and a malformed one falls back to the run value (#505)", async () => {
+  // A graph built programmatically (bypassing the OpenAPI pattern) can carry a lower-case or malformed
+  // per-node duration. The runner normalizes it through `isoDuration` so a bad value never bakes an
+  // uninterpretable boundary timer: `pt4h` → `PT4H`, and `nonsense` falls back to the run-level default.
+  const graph: DeliveryGraph = {
+    name: "per-node normalization",
+    nodes: [
+      { id: "lower", kind: "agent", agent: { jobType: "senior:feature", timeout: "pt4h" } },
+      { id: "bad", kind: "connector", connector: { target: "slack:post", dedupeKey: "n-1", timeout: "nonsense" } },
+    ],
+    edges: [{ from: "lower", to: "bad" }],
+  } as unknown as DeliveryGraph;
+  const p = await prepareOk(graph, { nodeTimeout: "PT2H" });
+  const agent = Object.values(p.nodeInputs).find((v) => (v as { jobType?: string }).jobType === "senior:feature") as
+    | { timeout: string }
+    | undefined;
+  const connector = Object.values(p.nodeInputs).find((v) => (v as { target?: string }).target === "slack:post") as
+    | { timeout: string }
+    | undefined;
+
+  assertEquals(agent?.timeout, "PT4H"); // lower-case normalized to canonical form
+  assertEquals(connector?.timeout, "PT2H"); // malformed value rejected → run-level default
+});
+
+test("a RUN-LEVEL timeout is normalized (lower-case → canonical) and a malformed one falls back to the default (#505)", async () => {
+  // A programmatic caller of prepareDeliveryGraph/runDeliveryGraph bypasses the OpenAPI/door validators,
+  // so a lower-case or malformed run-level `nodeTimeout` must not become the fallback baked into a node's
+  // boundary timer FEEL. isoDuration canonicalizes it (`pt3h` → `PT3H`) at the run level too, and a
+  // malformed value falls back to the DEFAULTS run value rather than an uninterpretable duration.
+  const lower = await prepareOk(GRAPH, { nodeTimeout: "pt3h" });
+  for (const v of Object.values(lower.nodeInputs).filter((v) => "timeout" in v)) {
+    assertEquals((v as { timeout: string }).timeout, "PT3H"); // lower-case run value normalized
+  }
+  const bad = await prepareOk(GRAPH, { nodeTimeout: "nonsense" });
+  for (const v of Object.values(bad.nodeInputs).filter((v) => "timeout" in v)) {
+    assertEquals((v as { timeout: string }).timeout, "PT1H"); // malformed run value → PT1H default, never baked raw
+  }
+});
+
 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

@@ -18,6 +18,7 @@ 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 { isoDuration } from "./reviewWait.ts";
 
 /** The content digest of a compiled graph — `sha256(bpmn)[:12]` — the single source of truth for the
  * content-addressed deploy id (`delivery-graph-<digest>`) AND the dispatch fence's default idempotency
@@ -53,7 +54,7 @@ export interface DeliveryRunOptions extends DeliveryRunTimeouts {
 }
 
 const DEFAULTS: Required<Omit<DeliveryRunTimeouts, "escalationAssignee">> = {
-  nodeTimeout: "PT30M",
+  nodeTimeout: "PT1H",
   probeTimeout: "PT30M",
   probePollEvery: msToIsoDuration(DEFAULT_EVERY_MS),
   escalationSlaTimeout: "P1D",
@@ -110,11 +111,14 @@ export async function prepareDeliveryGraph(
   const bpmn = rewriteProcessId(compiled.bpmn, processDefinitionId);
 
   const runKey = options.runKey?.trim() || randomUUID();
+  // Normalize the run-level timeouts through isoDuration so a programmatic caller that bypasses the
+  // OpenAPI/door validators cannot bake a malformed or lower-case duration into a BPMN timer FEEL —
+  // isoDuration canonicalizes case and falls back to the default on a malformed/blank value.
   const timeouts = {
-    nodeTimeout: options.nodeTimeout ?? DEFAULTS.nodeTimeout,
-    probeTimeout: options.probeTimeout ?? DEFAULTS.probeTimeout,
-    probePollEvery: options.probePollEvery ?? DEFAULTS.probePollEvery,
-    escalationSlaTimeout: options.escalationSlaTimeout ?? DEFAULTS.escalationSlaTimeout,
+    nodeTimeout: isoDuration(options.nodeTimeout, DEFAULTS.nodeTimeout),
+    probeTimeout: isoDuration(options.probeTimeout, DEFAULTS.probeTimeout),
+    probePollEvery: isoDuration(options.probePollEvery, DEFAULTS.probePollEvery),
+    escalationSlaTimeout: isoDuration(options.escalationSlaTimeout, DEFAULTS.escalationSlaTimeout),
     escalationAssignee: options.escalationAssignee ?? null,
   };
   const elementByNodeId = new Map(compiled.resolved.nodes.map((n) => [n.id, n.element]));
@@ -174,7 +178,7 @@ function buildNodeInput(
 ): NodeInput {
   switch (node.kind) {
     case "agent":
-      return { jobType: node.agent.jobType, appendPrompt: node.agent.prompt ?? "", timeout: ctx.nodeTimeout };
+      return { jobType: node.agent.jobType, appendPrompt: node.agent.prompt ?? "", timeout: isoDuration(node.agent.timeout, ctx.nodeTimeout) };
     case "wait": {
       const probe = parseProbe(node.wait);
       return {
@@ -201,7 +205,7 @@ function buildNodeInput(
         target: node.connector.target,
         dedupeKey: node.connector.dedupeKey ?? null,
         payload: node.connector.payload ?? null,
-        timeout: ctx.nodeTimeout,
+        timeout: isoDuration(node.connector.timeout, ctx.nodeTimeout),
       };
     default:
       return assertNever(node, "buildNodeInput");

package/app/reviewWait.ts

@@ -20,6 +20,14 @@ export const DEFAULT_REVIEW_WAIT_TIMEOUT = "PT20M";
 // would fail to interpret; not a full grammar (we don't need fractional seconds here).
 const ISO_DURATION = /^P(?!$)(\d+Y)?(\d+M)?(\d+W)?(\d+D)?(T(?=\d)(\d+H)?(\d+M)?(\d+S)?)?$/;
 
+/** True when `raw` is a well-formed ISO-8601 duration under {@link isoDuration}'s grammar — the strict
+ * predicate an operator submission door uses to REJECT a malformed duration (400) rather than silently
+ * fall back to a default. Derives from the same {@link ISO_DURATION} grammar so the accept/reject
+ * decision can never drift from the normalise-or-default one. Case-insensitive (`pt2h` is valid). */
+export function isValidIsoDuration(raw: string): boolean {
+  return ISO_DURATION.test(raw.trim().toUpperCase());
+}
+
 /** Validate an ISO-8601 duration string for a BPMN timer's `<bpmn:timeDuration>`, falling back to
  * `def` when the value is absent, blank, or malformed — a bad env value must never deploy an
  * uninterpretable timer expression into a process. Normalises to upper case (`pt20m` → `PT20M`).

package/openapi.yaml

@@ -1407,6 +1407,15 @@ components:
                   type: string
                   maxLength: 20000
                   description: OPTIONAL steering prompt appended to the node's job brief.
+                timeout:
+                  type: string
+                  pattern: '^[Pp](?!$)(\d+[Yy])?(\d+[Mm])?(\d+[Ww])?(\d+[Dd])?([Tt](?=\d)(\d+[Hh])?(\d+[Mm])?(\d+[Ss])?)?$'
+                  maxLength: 64
+                  description: >-
+                    OPTIONAL per-node ISO-8601 SLA timeout (#505). Overrides the run-level `nodeTimeout`
+                    (and the `PT1H` default) for THIS node's bounded-timeout → escalate boundary timer, so
+                    a legitimately-long node (e.g. a full `senior:feature` implementation) can outlast a
+                    quick gate without a spurious escalation. Absent → the run/default value.
     DeliveryNodeWait:
       description: >-
         A `wait` node — a durable `ReadinessProbe` (ADR 0001 §2) watching an external fact. Reuses the
@@ -1496,6 +1505,14 @@ components:
                   type: object
                   additionalProperties: true
                   description: Minimal forward-declared payload stub — the concrete connector payload schema is deferred (ADR non-goal).
+                timeout:
+                  type: string
+                  pattern: '^[Pp](?!$)(\d+[Yy])?(\d+[Mm])?(\d+[Ww])?(\d+[Dd])?([Tt](?=\d)(\d+[Hh])?(\d+[Mm])?(\d+[Ss])?)?$'
+                  maxLength: 64
+                  description: >-
+                    OPTIONAL per-node ISO-8601 SLA timeout (#505). Overrides the run-level `nodeTimeout`
+                    (and the `PT1H` default) for THIS connector node's bounded-timeout → escalate boundary
+                    timer. Absent → the run/default value.
     DeliveryEdge:
       description: >-
         A dependency edge — "`to` proceeds once fact `from` is observable" (ADR 0005 Decision 3).
@@ -1596,6 +1613,28 @@ components:
           type: string
           maxLength: 255
           description: OPTIONAL idempotency key. A re-dispatch with the same key (or, when omitted, the same digest) does not double-launch. Blank/whitespace is treated as absent.
+        nodeTimeout:
+          type: string
+          pattern: '^[Pp](?!$)(\d+[Yy])?(\d+[Mm])?(\d+[Ww])?(\d+[Dd])?([Tt](?=\d)(\d+[Hh])?(\d+[Mm])?(\d+[Ss])?)?$'
+          maxLength: 64
+          description: >-
+            OPTIONAL run-level ISO-8601 SLA timeout for `agent`/`connector` nodes (#505) — the
+            bounded-timeout → escalate boundary bound every such node inherits unless it declares its own
+            per-node `timeout`. Absent → the `PT1H` default. An invalid duration is rejected at submit.
+        probeTimeout:
+          type: string
+          pattern: '^[Pp](?!$)(\d+[Yy])?(\d+[Mm])?(\d+[Ww])?(\d+[Dd])?([Tt](?=\d)(\d+[Hh])?(\d+[Mm])?(\d+[Ss])?)?$'
+          maxLength: 64
+          description: >-
+            OPTIONAL run-level ISO-8601 poll budget for `wait` gates (#505) before they escalate. Absent →
+            the `PT30M` default. An invalid duration is rejected at submit.
+        escalationSlaTimeout:
+          type: string
+          pattern: '^[Pp](?!$)(\d+[Yy])?(\d+[Mm])?(\d+[Ww])?(\d+[Dd])?([Tt](?=\d)(\d+[Hh])?(\d+[Mm])?(\d+[Ss])?)?$'
+          maxLength: 64
+          description: >-
+            OPTIONAL run-level ISO-8601 SLA for `human` nodes (#505) before they record an `escalated`
+            outcome. Absent → the `P1D` default. An invalid duration is rejected at submit.
     DeliveryGraphProposalBpmnRequest:
       description: >-
         Request the compiled BPMN of a staged delivery-graph proposal for read-only DI PREVIEW. Carries

package/operations/dispatchDeliveryGraph.test.ts

@@ -182,4 +182,69 @@ describe("dispatchDeliveryGraph — operator dispatch by staged-proposal digest"
     assert.equal((await deliveryGraphProposals(app.db).get(digest))?.status, "expired");
     assert.equal((await deliveryGraphRuns(app.db).all()).length, 0);
   });
+
+  test("an invalid run-level nodeTimeout duration is rejected at submit → 400, nothing launched (#505)", async () => {
+    const app = await boot();
+    assert.ok(app.api);
+    const api = app.api;
+    const staged = await api.call<{ digest: string }>("compileDeliveryGraph", { body: HUMAN_ONLY });
+    const res = await api.call<{ ok?: boolean; error?: string; issues?: Array<{ path: string }> }>("dispatchDeliveryGraph", {
+      body: { digest: staged.body.digest, nodeTimeout: "2 hours" },
+    });
+    // Rejected at submit — either by the edge shape-validator (openapi `pattern`) or the door's own
+    // ISO-8601 guard; both surface a 400. Nothing launches and the proposal stays staged (dispatchable).
+    assert.equal(res.status, 400);
+    assert.equal((await deliveryGraphRuns(app.db).all()).length, 0);
+    assert.equal((await deliveryGraphProposals(app.db).get(staged.body.digest))?.status, "staged");
+  });
+
+  test("an oversized invalid duration never bloats the 400 response — rejected with a bounded error, nothing launched (#505)", async () => {
+    const app = await boot();
+    assert.ok(app.api);
+    const api = app.api;
+    const staged = await api.call<{ digest: string }>("compileDeliveryGraph", { body: HUMAN_ONLY });
+    const huge = `PT${"9".repeat(5000)}X`;
+    const res = await api.call<{ ok?: boolean; error?: string }>("dispatchDeliveryGraph", {
+      body: { digest: staged.body.digest, nodeTimeout: huge },
+    });
+    assert.equal(res.status, 400);
+    // The 5000-char blob is never echoed back verbatim — the edge pattern rejects it, and the door's
+    // own guard (`truncateForEcho`) caps the echo when the edge is bypassed. Either way the response
+    // stays bounded, so a malformed input can't bloat logs/response bodies.
+    assert.ok((res.body.error ?? "").length < 300, `error body should be bounded, got ${(res.body.error ?? "").length} chars`);
+    assert.equal((await deliveryGraphRuns(app.db).all()).length, 0);
+  });
+
+  test("a syntactically-valid but oversized duration is rejected at the door → 400, nothing launched (#505)", async () => {
+    const app = await boot();
+    assert.ok(app.api);
+    const api = app.api;
+    const staged = await api.call<{ digest: string }>("compileDeliveryGraph", { body: HUMAN_ONLY });
+    // Matches the ISO-8601 grammar but exceeds the door's MAX_DURATION_LEN (64) — the door re-enforces the
+    // openapi `maxLength: 64` so an oversized value is refused even if the edge validator is bypassed.
+    const longValid = `PT${"9".repeat(70)}H`;
+    const res = await api.call<{ ok?: boolean; error?: string }>("dispatchDeliveryGraph", {
+      body: { digest: staged.body.digest, nodeTimeout: longValid },
+    });
+    assert.equal(res.status, 400);
+    assert.ok((res.body.error ?? "").length < 300, `error body should be bounded, got ${(res.body.error ?? "").length} chars`);
+    assert.equal((await deliveryGraphRuns(app.db).all()).length, 0);
+    assert.equal((await deliveryGraphProposals(app.db).get(staged.body.digest))?.status, "staged");
+  });
+
+  test("a valid run-level nodeTimeout override dispatches the run → 202 running (#505)", async () => {
+    const app = await boot();
+    assert.ok(app.api);
+    const api = app.api;
+    const staged = await api.call<{ digest: string }>("compileDeliveryGraph", { body: HUMAN_ONLY });
+    const res = await api.call<{ ok: boolean; status: string }>("dispatchDeliveryGraph", {
+      body: { digest: staged.body.digest, nodeTimeout: "PT2H" },
+    });
+    assert.equal(res.status, 202);
+    assert.equal(res.body.ok, true);
+    assert.equal(res.body.status, "running");
+    await app.settle();
+    assert.equal((await deliveryGraphRuns(app.db).all()).length, 1);
+    assert.equal((await deliveryGraphProposals(app.db).get(staged.body.digest))?.status, "dispatched");
+  });
 });

package/operations/dispatchDeliveryGraph.ts

@@ -12,9 +12,39 @@
 
 import { dispatchDeliveryGraphRun } from "../app/deliveryGraphDispatch.ts";
 import { getStagedProposal, markProposalDispatched, markProposalExpired } from "../app/deliveryGraphProposals.ts";
+import { isValidIsoDuration } from "../app/reviewWait.ts";
 import type { DeliveryGraphTextResult } from "../nano-generated/api-io.d.ts";
 import { defineOperation } from "../nano-generated/operations.ts";
 
+/** Cap an untrusted, rejected duration string before it is echoed into logs/response bodies. `openapi.yaml`
+ * caps these dispatch duration fields at `maxLength: 64` at the edge, and the door re-enforces that bound
+ * (see `MAX_DURATION_LEN`); this truncation is defense-in-depth for when the edge validator is bypassed,
+ * so a very large malformed value can never bloat either the logs or the response. */
+const MAX_ECHO_LEN = 80;
+function truncateForEcho(value: string): string {
+  return value.length > MAX_ECHO_LEN ? `${value.slice(0, MAX_ECHO_LEN)}… (${value.length} chars)` : value;
+}
+
+/** Door-level cap on a duration override, mirroring the `maxLength: 64` on these fields in `openapi.yaml`.
+ * Re-enforced here so a syntactically-valid-but-oversized duration is still rejected when the edge
+ * validator is bypassed (internal calls/tests), keeping seeded process variables and error/log output bounded. */
+const MAX_DURATION_LEN = 64;
+
+/** Validate an OPTIONAL run-level ISO-8601 duration override off the dispatch body (#505). Blank/
+ * whitespace is treated as absent (→ the runner default). A present-but-malformed value returns
+ * `{ ok: false, invalid }` so the door can reject it at submit rather than silently deploy an
+ * uninterpretable timer. Reuses the canonical `reviewWait` grammar so accept/reject never drifts from
+ * the runner's normalise-or-default one, and enforces `MAX_DURATION_LEN` so an oversized value is
+ * rejected even if the OpenAPI `maxLength` edge check is bypassed. */
+function validateDurationOverride(raw: unknown): { ok: true; value: string | undefined } | { ok: false; invalid: string } {
+  if (raw === undefined || raw === null) return { ok: true, value: undefined };
+  if (typeof raw !== "string") return { ok: false, invalid: String(raw) };
+  const trimmed = raw.trim();
+  if (trimmed === "") return { ok: true, value: undefined };
+  if (trimmed.length > MAX_DURATION_LEN || !isValidIsoDuration(trimmed)) return { ok: false, invalid: trimmed };
+  return { ok: true, value: trimmed.toUpperCase() };
+}
+
 export default defineOperation("dispatchDeliveryGraph", async ({ body }, app) => {
   const digest = body && typeof body === "object" && "digest" in body && typeof body.digest === "string" ? body.digest.trim() : "";
   if (digest === "") {
@@ -24,6 +54,27 @@ export default defineOperation("dispatchDeliveryGraph", async ({ body }, app) =>
   const idemRaw = body && typeof body === "object" && "idempotencyKey" in body && typeof body.idempotencyKey === "string" ? body.idempotencyKey.trim() : "";
   const idempotencyKey = idemRaw !== "" ? idemRaw : undefined;
 
+  // Run-level timeout overrides (#505) — exposed at submission, validated as ISO-8601 durations here so
+  // an invalid value is a clean 400 (never a deployed, uninterpretable timer). Absent → runner defaults.
+  const rawTimeouts: Record<"nodeTimeout" | "probeTimeout" | "escalationSlaTimeout", unknown> =
+    body && typeof body === "object"
+      ? {
+          nodeTimeout: "nodeTimeout" in body ? body.nodeTimeout : undefined,
+          probeTimeout: "probeTimeout" in body ? body.probeTimeout : undefined,
+          escalationSlaTimeout: "escalationSlaTimeout" in body ? body.escalationSlaTimeout : undefined,
+        }
+      : { nodeTimeout: undefined, probeTimeout: undefined, escalationSlaTimeout: undefined };
+  const timeouts: { nodeTimeout?: string; probeTimeout?: string; escalationSlaTimeout?: string } = {};
+  for (const field of ["nodeTimeout", "probeTimeout", "escalationSlaTimeout"] as const) {
+    const parsed = validateDurationOverride(rawTimeouts[field]);
+    if (!parsed.ok) {
+      const shown = truncateForEcho(parsed.invalid);
+      app.log.warn("dispatch-delivery-graph rejected: invalid duration", { field, value: shown, invalidLength: parsed.invalid.length });
+      return { status: 400, body: { ok: false, error: `\`${field}\` must be an ISO-8601 duration (e.g. \`PT2H\`); got \`${shown}\`` } };
+    }
+    if (parsed.value !== undefined) timeouts[field] = parsed.value;
+  }
+
   // Load the live staged proposal for this digest — refuses an unknown/expired/superseded/already-
   // dispatched digest cleanly (no run is launched).
   const proposal = await getStagedProposal(app.data, digest);
@@ -47,7 +98,7 @@ export default defineOperation("dispatchDeliveryGraph", async ({ body }, app) =>
     return { status: 400, body: { ok: false, error: `staged proposal ${digest} is corrupt: ${err instanceof Error ? err.message : String(err)}` } };
   }
 
-  const dispatched = await dispatchDeliveryGraphRun(app, graph, { runKey: idempotencyKey, title: proposal.title });
+  const dispatched = await dispatchDeliveryGraphRun(app, graph, { runKey: idempotencyKey, title: proposal.title, ...timeouts });
   if (!dispatched.ok) {
     app.log.warn("dispatch-delivery-graph refused: compile", { digest, errors: dispatched.errors.length });
     const outBody: DeliveryGraphTextResult = {

package/package.json

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