@nanobpm/nano-workforce 0.200.0 → 0.200.2

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.200.2](https://github.com/nanobpm/nano-workforce/compare/v0.200.1...v0.200.2) (2026-10-03)
+
+### Documentation
+
+* **agent-guide:** require repository on every delivery-graph agent node ([#851](https://github.com/nanobpm/nano-workforce/issues/851)) ([d6770ae](https://github.com/nanobpm/nano-workforce/commit/d6770ae2f6acc490e102aecaf0cab17ca5d10119)), closes [#850](https://github.com/nanobpm/nano-workforce/issues/850) [#850](https://github.com/nanobpm/nano-workforce/issues/850) [#505](https://github.com/nanobpm/nano-workforce/issues/505) [#850](https://github.com/nanobpm/nano-workforce/issues/850) [739/#776](https://github.com/739/nano-workforce/issues/776) [#505](https://github.com/nanobpm/nano-workforce/issues/505)
+
+## [0.200.1](https://github.com/nanobpm/nano-workforce/compare/v0.200.0...v0.200.1) (2026-10-03)
+
+### Performance Improvements
+
+* **delivery-graph:** run BPMN autolayout off the main thread (worker_threads) so a large graph cannot freeze the app ([#855](https://github.com/nanobpm/nano-workforce/issues/855)) ([d726bca](https://github.com/nanobpm/nano-workforce/commit/d726bcafd1b8e89484c7231a705f287943633a8a)), closes [#852](https://github.com/nanobpm/nano-workforce/issues/852) [#854](https://github.com/nanobpm/nano-workforce/issues/854)
+
 ## [0.200.0](https://github.com/nanobpm/nano-workforce/compare/v0.199.0...v0.200.0) (2026-10-02)
 
 ### Features

package/app/contracts.ts

@@ -104,6 +104,22 @@ export const ENV_CONTRACTS = {
       "Clone timeout in milliseconds emitted as `repository.cloneTimeoutMs` in the agent-task envelope so the c8ctl harness raises its 120s default for large-repo provisioning (branch-scoped blobless clones of big monorepos still approach/exceed 120s; issue #694). Inherited by both the review-round and merge paths via the one `repoEnvelopeVars` builder.",
     default: "600000",
   },
+  NANO_DELIVERY_LAYOUT_TIMEOUT_MS: {
+    category: "env",
+    name: "NANO_DELIVERY_LAYOUT_TIMEOUT_MS",
+    owner: "app/layoutOffThread.ts",
+    semantics:
+      "Bound (ms) on the delivery-graph BPMN autolayout (`layoutBpmn` → `bpmn-auto-layout`), which runs OFF the main event loop in a `node:worker_threads` worker (`layoutBpmnOffThread`, issue #854). On expiry the worker is terminated and the compile/launch fails CLEANLY rather than hanging — the inline layout previously froze the whole app (no HTTP, no poll passes) for the entire superlinear run (#852). Shared by both the dispatch (`dispatchDeliveryGraphRun` → `compileDeliveryGraph`) and preview (`previewProposalBpmn`) paths, which both funnel through the one `layoutDeliveryDiagram` entry point.",
+    default: "300000",
+  },
+  NANO_DELIVERY_LAYOUT_MAX_CONCURRENCY: {
+    category: "env",
+    name: "NANO_DELIVERY_LAYOUT_MAX_CONCURRENCY",
+    owner: "app/layoutOffThread.ts",
+    semantics:
+      "Maximum number of delivery-graph BPMN autolayout workers (`layoutBpmnOffThread`, issue #854) allowed to run CONCURRENTLY. Each layout is a CPU-bound `node:worker_threads` worker running the superlinear `bpmn-auto-layout` pass; overlapping preview/dispatch requests would otherwise spawn an UNBOUNDED number of them and saturate CPU/memory, starving the very event loop this off-thread move exists to protect. Excess layouts queue (FIFO) for a slot via the shared `Semaphore`. Capacity is fixed at first use, so a retune needs a restart (unlike the per-call timeout).",
+    default: "2",
+  },
   NANO_PR_MAX_ROUNDS: {
     category: "env",
     name: "NANO_PR_MAX_ROUNDS",

package/app/deliveryGraphCompiler.ts

@@ -23,7 +23,6 @@
 // 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,
@@ -50,6 +49,7 @@ import {
   validateDeliveryGraph,
 } from "./deliveryGraph.ts";
 import { DELIVERY_HUMAN_ELEMENT, GENERIC_HUMAN_FORM } from "./deliveryHuman.ts";
+import { layoutBpmnOffThread } from "./layoutOffThread.ts";
 import { DEFAULT_BACKOFF, DEFAULT_EVERY_MS, DEFAULT_ON_TIMEOUT, DEFAULT_TIMEOUT_MS, isProbeKind, normalizePoll, redactEmbeddedCredential, redactString } from "./readiness.ts";
 import { AGENT_TASK_NS } from "./repoEnvelope.ts";
 import { isoDuration } from "./reviewWait.ts";
@@ -719,9 +719,15 @@ export async function compileDeliveryGraph(
  * `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". */
+ * Deterministic given identical input, preserving the compiler's "same JSON → byte-identical XML".
+ *
+ * The autolayout itself runs OFF the main event loop in a `node:worker_threads` worker, bounded by a
+ * timeout (`layoutBpmnOffThread` → `app/layoutOffThread.ts`, issue #854): `layoutBpmn` is superlinear
+ * and, run inline here, blocked the whole app (no HTTP, no poll passes) for the entire layout — a hard
+ * lock-up on a large graph (#852). This is the ONE place the layout runs, so hoisting it off-thread
+ * covers BOTH the dispatch and preview paths that funnel through `compileDeliveryGraph`. */
 async function layoutDeliveryDiagram(semanticBpmn: string): Promise<string> {
-  const laidOut = await layoutBpmn(semanticBpmn);
+  const laidOut = await layoutBpmnOffThread(semanticBpmn);
   const start = laidOut.indexOf("<bpmndi:BPMNDiagram");
   const endTag = "</bpmndi:BPMNDiagram>";
   const end = laidOut.lastIndexOf(endTag);

package/app/deliveryGraphVocabulary.test.ts

@@ -6,7 +6,9 @@
 // key sets are byte-identical to the closed sets in `app/deliveryGraph.ts` / `app/readiness.ts` /
 // `app/convergeTargets.ts` (AGENTS.md — "no drift surfaces").
 import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
 import { test } from "node:test";
+import { parse as parseYaml } from "yaml";
 import { CONVERGE_MERGE_TARGET, CONVERGE_TARGET, isConvergeTarget, MERGE_MAIN_TARGET } from "./convergeTargets.ts";
 import { DELIVERY_FACT_TYPES, DELIVERY_GUARD_SCALAR_TYPES, DELIVERY_NODE_KINDS } from "./deliveryGraph.ts";
 import { deliveryGraphVocabulary } from "./deliveryGraphVocabulary.ts";
@@ -100,3 +102,80 @@ test("fact-threading rule names the unbound-pr rejection", () => {
   const vocab = deliveryGraphVocabulary();
   assert.match(vocab.factThreading.rule, /unbound-pr/);
 });
+
+// Resolve a node kind's per-kind CONFIG sub-schema (the authoritative OpenAPI contract for that
+// kind's body) from the parsed spec. `DeliveryNode<Kind>` is `allOf: [DeliveryNodeCommon, { properties:
+// { <configKey>: {…} } }]`, so find the allOf member carrying the `<configKey>` sub-schema and return
+// that member's `<configKey>` VALUE. For most kinds that value is the inline config object; for the
+// `wait` kind it is the `{ $ref: "#/components/schemas/ReadinessProbe" }` object (the config is
+// referenced, not inlined), which this helper returns AS-IS — the caller follows the reference itself.
+// Returns null only when the kind's node schema has NO inline `<configKey>` member at all (which the
+// caller's assert.ok rejects), never for the `wait` kind.
+function nodeConfigSchema(
+  spec: Record<string, any>,
+  nodeSchemaName: string,
+  configKey: string,
+): Record<string, any> | null {
+  const schema = spec?.components?.schemas?.[nodeSchemaName];
+  if (!schema) return null;
+  const sub = (schema.allOf as Array<Record<string, any>> | undefined)?.map((m) => m?.properties?.[configKey]).find(Boolean);
+  return sub ?? null;
+}
+
+/** Derive the (sorted) required + optional field sets from a config sub-schema's own `required`/`properties`. */
+function fieldSets(configSchema: Record<string, any>): { required: string[]; optional: string[] } {
+  const required = [...((configSchema.required as string[] | undefined) ?? [])].sort();
+  const optional = Object.keys((configSchema.properties as Record<string, unknown>) ?? {})
+    .filter((k) => !required.includes(k))
+    .sort();
+  return { required, optional };
+}
+
+test("every node-kind entry's field sets are DERIVED from its OpenAPI DeliveryNode<Kind>.<configKey> contract (#739/#850)", () => {
+  // The #850 failure mode is drift between a `DeliveryNode<Kind>.<configKey>` (the authoritative
+  // OpenAPI contract) and this vocabulary surface. A literal field list duplicated here would NOT
+  // catch it: if OpenAPI adds or removes a config property, a hand-copied list stays green while the
+  // surface lies. So derive the required/optional sets from the PARSED spec and compare the sets
+  // directly — the vocabulary cannot silently drift from the contract it claims to mirror. This
+  // guards EVERY kind, not just `agent`: the connector entry omitting the real `timeout` field
+  // (PR #851 review) is the same drift class the agent-only guard missed.
+  const ROOT = decodeURIComponent(new URL("../", import.meta.url).pathname);
+  const spec = parseYaml(readFileSync(`${ROOT}openapi.yaml`, "utf8")) as Record<string, any>;
+
+  const vocab = deliveryGraphVocabulary();
+  for (const entry of vocab.nodeKinds) {
+    const nodeSchemaName = `DeliveryNode${entry.kind[0]!.toUpperCase()}${entry.kind.slice(1)}`;
+    let configSchema = nodeConfigSchema(spec, nodeSchemaName, entry.configKey);
+    assert.ok(
+      configSchema,
+      `openapi.yaml components.schemas.${nodeSchemaName} must carry an inline '${entry.configKey}' config sub-schema`,
+    );
+    // The `wait` kind's config is `$ref: "#/components/schemas/ReadinessProbe"` — follow the reference.
+    if (typeof configSchema!.$ref === "string") {
+      const refName = configSchema!.$ref.replace(/^#\/components\/schemas\//, "");
+      configSchema = spec?.components?.schemas?.[refName];
+      assert.ok(configSchema?.properties, `${refName} (the wait config contract) must declare its properties`);
+    }
+    const { required, optional } = fieldSets(configSchema!);
+    assert.deepEqual(
+      [...entry.requiredFields].sort(),
+      required,
+      `${entry.kind}.requiredFields drifted from ${nodeSchemaName}.${entry.configKey}.required in openapi.yaml`,
+    );
+    assert.deepEqual(
+      [...entry.optionalFields].sort(),
+      optional,
+      `${entry.kind}.optionalFields drifted from ${nodeSchemaName}.${entry.configKey}'s optional properties in openapi.yaml`,
+    );
+  }
+
+  // The non-obvious rules an authoring agent must learn from the surface prose: an ABSENT repository
+  // is not compile-rejected (a run-level fallback can satisfy it) — it fails at the OPERATOR's
+  // Dispatch; and the per-node SLA timeout override exists.
+  const agent = vocab.nodeKinds.find((n) => n.kind === "agent");
+  assert.ok(agent, "agent node-kind entry must exist");
+  assert.match(agent.summary, /resolve to no repository/, "names the dispatch-time failure the author must pre-empt");
+  assert.match(agent.summary, /invalid-node-repository/, "names the compile-time validation for a present value");
+  assert.match(agent.summary, /repoless/, "names the checkout-less opt-out");
+  assert.match(agent.summary, /per-node ISO-8601 `timeout`/, "names the per-node SLA timeout override (#505)");
+});

package/app/deliveryGraphVocabulary.ts

@@ -105,13 +105,29 @@ const NODE_KIND_DETAIL: Record<string, Omit<NodeKindEntry, "kind">> = {
   agent: {
     configKey: "agent",
     requiredFields: ["jobType"],
-    optionalFields: ["prompt", "converge", "merge"],
+    optionalFields: ["repository", "baseBranch", "prompt", "converge", "merge", "timeout"],
     sideEffecting: true,
     mayEmit: true,
     summary:
-      "A worker runs an agent job type (the fan-out body, e.g. `senior:feature`). First-class " +
+      "A worker runs an agent job type (the fan-out body, e.g. `senior:feature`) in an isolated " +
+      "checkout. Per-node provisioning (#739/#776): declare `repository` (`owner/repo`, no `.git`/URL) " +
+      "on EVERY agent node — the harness clones it at `baseBranch` (omit it to use the run-level " +
+      "dispatch `baseBranch`, else the repo's default branch) and cuts `feat/<node.id>` off it " +
+      "(when that derived ref is a valid Git branch name; an id like `a..b`/`a.lock` yields an " +
+      "ill-formed ref, so the harness omits `branch.create` and the agent cuts its own branch). A node " +
+      "with no `repository` can only be satisfied by the run-level dispatch fallback, so COMPILE " +
+      "stages it without a warning; at Dispatch it resolves to the run-level `repository` + `baseBranch` " +
+      "fallback when the operator supplies one, and the Dispatch fails with `N agent node(s) " +
+      "resolve to no repository (…)` ONLY when neither the node nor the run supplies a repository " +
+      "(a present value IS compile-validated: `invalid-node-repository`/" +
+      "`invalid-node-base-branch`); a genuinely checkout-less graph must be dispatched `repoless: true`, " +
+      "which strips isolation from every node. First-class " +
       "`converge?`/`merge?` cell-policy flags declare review-convergence / landing intent (`merge` " +
       "requires `converge`); a raw `senior:converge`/`senior:merge` jobType is rejected (`raw-converge-node`). " +
+      "An optional per-node ISO-8601 `timeout` (#505) overrides the run-level `nodeTimeout` (and the " +
+      "`PT1H` default) for THIS node's bounded-timeout → escalate boundary, so a legitimately-long node " +
+      "(e.g. a full `senior:feature`) outlasts a quick gate without a spurious escalation; absent → the " +
+      "run/default value. " +
       "An `agent` that opens a PR emits it as a `pr`-typed fact so downstream connector/wait nodes late-bind it.",
   },
   wait: {
@@ -138,14 +154,16 @@ const NODE_KIND_DETAIL: Record<string, Omit<NodeKindEntry, "kind">> = {
   connector: {
     configKey: "connector",
     requiredFields: ["target"],
-    optionalFields: ["dedupeKey", "payload"],
+    optionalFields: ["dedupeKey", "payload", "timeout"],
     sideEffecting: true,
     mayEmit: true,
     summary:
       "An automated, side-effecting outbound action. `payload` for a converge target is " +
       "`{ pr, autoMerge?, dependsOn? }` (`pr` may be a literal `owner/repo#N`, a `<node>.pr` fact " +
       "reference, or omitted to auto-bind the single incoming `pr` fact). Carries a `dedupeKey` " +
-      "(at-least-once safe). See connectorTargets for which targets are real vs. forward-declared.",
+      "(at-least-once safe). An optional per-node ISO-8601 `timeout` (#505) overrides the run-level " +
+      "`nodeTimeout` (and the `PT1H` default) for THIS node's bounded-timeout → escalate boundary; " +
+      "absent → the run/default value. See connectorTargets for which targets are real vs. forward-declared.",
   },
 };
 

package/app/layoutOffThread.test.ts

@@ -0,0 +1,208 @@
+// Guard coverage for the off-main-thread BPMN autolayout (issue #854). `layoutBpmn`
+// (`bpmn-auto-layout`) is superlinear and used to run SYNCHRONOUSLY on the app's event loop inside
+// `compileDeliveryGraph` → `layoutDeliveryDiagram`, freezing the whole app (no HTTP, no poll passes)
+// for the entire layout — a 3287ms single gap locally on the 54-node merlin graph, minutes under load
+// (#852). It now runs in a `node:worker_threads` worker bounded by a timeout. These tests assert:
+//   • the event loop KEEPS TICKING (bounded max gap) while a large graph lays out off-thread — the
+//     core liveness property this fixes,
+//   • the timeout TERMINATES a runaway layout and fails CLEANLY (rejects) rather than hanging,
+//   • the canonical `compileDeliveryGraph` path still produces a diagram through the off-thread bridge.
+import { test } from "node:test";
+import { assert, assertRejects, assertStringIncludes } from "#test-assert";
+import type { DeliveryGraph } from "../nano-generated/api-io.d.ts";
+import { compileDeliveryGraph } from "./deliveryGraphCompiler.ts";
+import { layoutBpmnOffThread, layoutMaxConcurrency, layoutTimeoutMs, Semaphore } from "./layoutOffThread.ts";
+
+/** Build a wide-and-deep delivery graph with `count` agent nodes wired into a chain with periodic
+ * fan-out, so the autolayout has enough nodes/edges to spend real CPU time laying it out. */
+function bigGraph(count: number): DeliveryGraph {
+  const nodes: DeliveryGraph["nodes"] = [];
+  const edges: DeliveryGraph["edges"] = [];
+  for (let i = 0; i < count; i++) {
+    nodes.push({ id: `n${i}`, kind: "agent", agent: { jobType: "senior:feature", prompt: `slice ${i}` } });
+    if (i > 0) edges.push({ from: `n${i - 1}`, to: `n${i}` });
+    // Periodic fan-out to widen the graph (more edges → more layout work).
+    if (i >= 3 && i % 3 === 0) edges.push({ from: `n${i - 3}`, to: `n${i}` });
+  }
+  return { name: "big-layout-graph", nodes, edges } as DeliveryGraph;
+}
+
+test("#854 the main event loop keeps servicing queued work while a large graph lays out off-thread", async () => {
+  const graph = bigGraph(60);
+
+  // ORDER-based liveness proof (not a wall-clock threshold): race a trivial main-thread `setImmediate`
+  // checkpoint against the layout. Off-thread, the loop reaches the next tick and fires the immediate
+  // in microseconds while the worker chews on the superlinear layout for far longer, so the checkpoint
+  // ALWAYS wins. Inline (the regression), `compileDeliveryGraph`'s synchronous `layoutBpmn` call would
+  // block the loop for the whole layout and its promise would then resolve via a microtask BEFORE any
+  // queued `setImmediate` macrotask could run, so the layout would win — failing this test. Because the
+  // worker's real CPU work dwarfs a single queued-tick dispatch by orders of magnitude, the winner is
+  // deterministic under any scheduler load (AGENTS.md deterministic-test rule) — no elapsed-time bound.
+  let compiled: Awaited<ReturnType<typeof compileDeliveryGraph>> | undefined;
+  const checkpoint = new Promise<"checkpoint">((resolve) => {
+    setImmediate(() => resolve("checkpoint"));
+  });
+  const layoutDone = compileDeliveryGraph(graph).then((c): "layout" => {
+    compiled = c;
+    return "layout";
+  });
+
+  const winner = await Promise.race([checkpoint, layoutDone]);
+  assert(
+    winner === "checkpoint",
+    "a queued main-thread setImmediate must win the race against the off-thread layout; if layout ran " +
+      "inline it would block the loop and its promise would resolve before the immediate could fire",
+  );
+
+  await layoutDone; // let the worker finish and tear down so the test leaks no worker/handle
+  assert(compiled !== undefined && compiled.ok, `expected ok:true, got ${JSON.stringify(compiled)}`);
+  assert(compiled.bpmn.includes("<bpmndi:BPMNDiagram"), "off-thread layout should still attach diagram interchange");
+});
+
+test("#854 a layout that exceeds its timeout fails cleanly (rejects) instead of hanging", async () => {
+  // A 1ms bound is unsatisfiable for any real graph, so the worker is terminated and the call rejects.
+  const semantic = "<?xml version=\"1.0\"?><bpmn:definitions xmlns:bpmn=\"http://www.omg.org/spec/BPMN/20100524/MODEL\" id=\"d\"><bpmn:process id=\"p\" isExecutable=\"true\"><bpmn:startEvent id=\"s\"/></bpmn:process></bpmn:definitions>";
+  const err = await assertRejects(() => layoutBpmnOffThread(semantic, 1));
+  assertStringIncludes(err.message, "854");
+});
+
+test("#854 layoutTimeoutMs honours the env knob and ignores garbage", () => {
+  assert(layoutTimeoutMs({}) === 300000, "unset → registered default");
+  assert(layoutTimeoutMs({ NANO_DELIVERY_LAYOUT_TIMEOUT_MS: "90000" }) === 90000, "valid override honoured");
+  assert(layoutTimeoutMs({ NANO_DELIVERY_LAYOUT_TIMEOUT_MS: "nope" }) === 300000, "garbage → default");
+  assert(layoutTimeoutMs({ NANO_DELIVERY_LAYOUT_TIMEOUT_MS: "-5" }) === 300000, "non-positive → default");
+  // Node's setTimeout ceiling is a signed 32-bit ms value (2_147_483_647); a larger delay wraps to
+  // 1ms and would abort every layout immediately, so an overflowing override must degrade to the
+  // registered default rather than be honoured (issue #854 review).
+  assert(layoutTimeoutMs({ NANO_DELIVERY_LAYOUT_TIMEOUT_MS: "2147483647" }) === 2147483647, "ceiling value honoured");
+  assert(layoutTimeoutMs({ NANO_DELIVERY_LAYOUT_TIMEOUT_MS: "2147483648" }) === 300000, "above Node timer ceiling → default");
+  assert(layoutTimeoutMs({ NANO_DELIVERY_LAYOUT_TIMEOUT_MS: "999999999999" }) === 300000, "far above ceiling → default");
+});
+
+test("#854 layoutMaxConcurrency honours the env knob and degrades a bad bound to the default", () => {
+  assert(layoutMaxConcurrency({}) === 2, "unset → registered default");
+  assert(layoutMaxConcurrency({ NANO_DELIVERY_LAYOUT_MAX_CONCURRENCY: "4" }) === 4, "valid override honoured");
+  assert(layoutMaxConcurrency({ NANO_DELIVERY_LAYOUT_MAX_CONCURRENCY: "nope" }) === 2, "garbage → default");
+  assert(layoutMaxConcurrency({ NANO_DELIVERY_LAYOUT_MAX_CONCURRENCY: "0" }) === 2, "zero (unbounded-by-stall) → default");
+  assert(layoutMaxConcurrency({ NANO_DELIVERY_LAYOUT_MAX_CONCURRENCY: "-3" }) === 2, "negative → default");
+  // A fractional bound is not a valid holder count; it must degrade rather than round silently.
+  assert(layoutMaxConcurrency({ NANO_DELIVERY_LAYOUT_MAX_CONCURRENCY: "1.5" }) === 2, "non-integer → default");
+  // An absurdly large bound is effectively "unbounded", which defeats the guard — degrade to default.
+  assert(layoutMaxConcurrency({ NANO_DELIVERY_LAYOUT_MAX_CONCURRENCY: "99999" }) === 2, "above ceiling → default");
+  assert(layoutMaxConcurrency({ NANO_DELIVERY_LAYOUT_MAX_CONCURRENCY: "1024" }) === 1024, "ceiling value honoured");
+});
+
+test("#854 Semaphore rejects a non-positive / non-integer bound (the guard must never be 0/∞)", () => {
+  for (const bad of [0, -1, 1.5, Number.NaN, Number.POSITIVE_INFINITY]) {
+    let threw = false;
+    try {
+      new Semaphore(bad);
+    } catch {
+      threw = true;
+    }
+    assert(threw, `Semaphore(${bad}) should throw — a bad bound would silently defeat the concurrency guard`);
+  }
+});
+
+test("#854 Semaphore bounds concurrency to `max` and admits waiters in FIFO order", async () => {
+  const sem = new Semaphore(2);
+  let active = 0;
+  let peak = 0;
+  const order: number[] = [];
+
+  // A holder records its admission order and the live peak, then yields a few microtasks before
+  // releasing so later acquirers genuinely have to queue behind the first `max`.
+  const run = async (id: number): Promise<void> => {
+    const release = await sem.acquire();
+    order.push(id);
+    active++;
+    peak = Math.max(peak, active);
+    try {
+      for (let i = 0; i < 5; i++) await Promise.resolve();
+    } finally {
+      active--;
+      release();
+    }
+  };
+
+  await Promise.all([run(1), run(2), run(3), run(4), run(5)]);
+
+  assert(peak <= 2, `at most 2 holders may run at once, saw ${peak}`);
+  // First two get the free slots immediately; 3,4,5 queue and are admitted in arrival order.
+  assert(JSON.stringify(order) === JSON.stringify([1, 2, 3, 4, 5]), `expected FIFO admission, got ${order.join(",")}`);
+});
+
+test("#854 Semaphore release is idempotent — a double release cannot over-admit", async () => {
+  const sem = new Semaphore(1);
+  const release = await sem.acquire();
+  release();
+  release(); // must be a no-op, not a second freed slot
+
+  // With max=1, exactly one holder may be active. Acquire twice without releasing the first; the
+  // second must still be waiting (never admitted by the stray double release above).
+  const first = await sem.acquire();
+  let secondAdmitted = false;
+  const second = sem.acquire().then((rel) => {
+    secondAdmitted = true;
+    return rel;
+  });
+  for (let i = 0; i < 10; i++) await Promise.resolve();
+  assert(!secondAdmitted, "the second acquire must block — a double release must not have over-admitted");
+  first();
+  (await second)();
+});
+
+test("#854 a holder that releases in `finally` frees its slot even when its work throws", async () => {
+  // This is the invariant `layoutBpmnOffThread` relies on: it `release()`s in a `finally`, so a
+  // rejecting/terminated layout returns its slot and the next queued layout proceeds instead of the
+  // gate wedging forever behind the failure. Prove it at max=1: a throwing holder that releases in
+  // `finally` must still admit the waiter behind it.
+  const sem = new Semaphore(1);
+  const failing = (async () => {
+    const release = await sem.acquire();
+    try {
+      throw new Error("layout blew up");
+    } finally {
+      release();
+    }
+  })();
+  await assertRejects(() => failing);
+
+  let nextAdmitted = false;
+  const next = sem.acquire().then((rel) => {
+    nextAdmitted = true;
+    rel();
+  });
+  for (let i = 0; i < 10; i++) await Promise.resolve();
+  assert(nextAdmitted, "the slot held by a throwing holder must be freed, admitting the next layout");
+  await next;
+});
+
+test("#854 a synchronous worker-construction failure releases the slot instead of wedging the gate", async () => {
+  // Regression for the review finding: `new Worker(...)` can throw synchronously (e.g.
+  // `ERR_WORKER_INIT_FAILED` under resource pressure). The slot is acquired BEFORE construction, so if
+  // construction isn't inside the release `finally`, each failure permanently consumes a slot and —
+  // after `layoutMaxConcurrency()` failures — every later layout queues on the shared singleton gate
+  // FOREVER. Force construction to throw more times than the bound: with the leak, the (max+1)-th call
+  // hangs on `acquire()` and never reaches the throwing factory; with the fix, every call rejects
+  // promptly. A per-call watchdog turns a wedge into a clean assertion failure rather than a suite hang.
+  const spawnThrows = (): never => {
+    throw new Error("ERR_WORKER_INIT_FAILED (simulated)");
+  };
+  const calls = layoutMaxConcurrency() + 2; // more than the bound, so a leak would exhaust the gate
+  for (let i = 0; i < calls; i++) {
+    const watchdog = new Promise<"hung">((resolve) => {
+      const t = setTimeout(() => resolve("hung"), 2000);
+      t.unref?.();
+    });
+    const attempt = layoutBpmnOffThread("<x/>", 60000, spawnThrows).then(
+      () => "resolved" as const,
+      () => "rejected" as const,
+    );
+    const outcome = await Promise.race([attempt, watchdog]);
+    assert(
+      outcome === "rejected",
+      `construction-failure call #${i + 1} must reject and free its slot, not wedge the gate (got "${outcome}")`,
+    );
+  }
+});

package/app/layoutOffThread.ts

@@ -0,0 +1,182 @@
+// app/layoutOffThread.ts — the ONE canonical off-main-thread bridge to the CPU-bound BPMN autolayout
+// (`layoutBpmn` → `bpmn-auto-layout`), issue #854.
+//
+// WHY: `layoutBpmn` is superlinear in node/edge count and, run inline on the event loop, blocked the
+// whole app (no HTTP, no poll passes) for the entire layout — ~52s on merlin, >4min under load on a
+// 54-node delivery graph, a hard lock-up the operator had to kill mid-launch (#852). This module runs
+// the layout in a `node:worker_threads` worker so the main loop keeps ticking, and BOUNDS it with a
+// timeout that TERMINATES the worker on expiry so a pathological graph fails the launch CLEANLY
+// instead of hanging forever.
+//
+// `layoutDeliveryDiagram` (app/deliveryGraphCompiler.ts) — the single layout entry point BOTH the
+// dispatch path (`dispatchDeliveryGraphRun` → `compileDeliveryGraph`) and the preview path
+// (`previewProposalBpmn` → `compileDeliveryGraph`) funnel through — calls `layoutBpmnOffThread` here,
+// so there is exactly ONE place the autolayout runs and exactly ONE timeout/termination policy.
+
+import { Worker } from "node:worker_threads";
+import { readEnvOr } from "./contracts.ts";
+
+/** Node's `setTimeout` delay ceiling (a signed 32-bit ms value). A delay above this silently wraps to
+ * 1ms (emitting `TimeoutOverflowWarning`), so an over-large override would abort layouts IMMEDIATELY
+ * instead of extending the bound — a value that large is treated as garbage and degrades to the
+ * registered default. */
+const MAX_TIMER_MS = 2_147_483_647;
+
+/** The registered default, resolved once from the schema (empty env ⇒ registry `default`) so the
+ * invalid-override fallback and the timeout message stay single-sourced — not a literal `300000`
+ * duplicated here that would drift from `ENV_CONTRACTS`. Mirrors `cloneTimeoutMs` in
+ * `app/repoEnvelope.ts`. */
+const envDefaultLayoutTimeoutMs = Number(readEnvOr("NANO_DELIVERY_LAYOUT_TIMEOUT_MS", "300000", {}));
+
+/** Resolve the layout timeout (ms) from `NANO_DELIVERY_LAYOUT_TIMEOUT_MS` (registered default 300000
+ * = 5 min), degrading to the registered default for any value that is non-positive, garbage, or above
+ * Node's timer ceiling ({@link MAX_TIMER_MS} — an overflow would wrap to 1ms and abort every layout).
+ * Read per call so an operator can retune it without a restart; the layout is rare (dispatch/preview),
+ * so the lookup cost is irrelevant. */
+export function layoutTimeoutMs(env: Record<string, string | undefined> = process.env): number {
+  const raw = Number(readEnvOr("NANO_DELIVERY_LAYOUT_TIMEOUT_MS", "300000", env));
+  return Number.isFinite(raw) && raw > 0 && raw <= MAX_TIMER_MS ? raw : envDefaultLayoutTimeoutMs;
+}
+
+/** A sanity ceiling on the concurrency bound: a value this large is effectively unbounded and is
+ * treated as garbage (degrading to the registered default) rather than honoured — the whole point of
+ * the bound is to keep concurrent CPU-bound layouts SMALL. */
+const MAX_LAYOUT_CONCURRENCY = 1024;
+
+/** The registered default concurrency, resolved once from the schema (empty env ⇒ registry `default`)
+ * so the invalid-override fallback stays single-sourced — not a literal duplicated here that would
+ * drift from `ENV_CONTRACTS`. Mirrors {@link envDefaultLayoutTimeoutMs}. */
+const envDefaultLayoutMaxConcurrency = Number(readEnvOr("NANO_DELIVERY_LAYOUT_MAX_CONCURRENCY", "2", {}));
+
+/** Resolve the max number of concurrent layout workers from `NANO_DELIVERY_LAYOUT_MAX_CONCURRENCY`
+ * (registered default 2), degrading to the registered default for any value that is non-integer,
+ * non-positive, garbage, or above {@link MAX_LAYOUT_CONCURRENCY}. Mirrors {@link layoutTimeoutMs}'s
+ * fail-safe parsing so a bad override can never make the bound 0/∞ (either of which defeats it). */
+export function layoutMaxConcurrency(env: Record<string, string | undefined> = process.env): number {
+  const raw = Number(readEnvOr("NANO_DELIVERY_LAYOUT_MAX_CONCURRENCY", "2", env));
+  return Number.isInteger(raw) && raw > 0 && raw <= MAX_LAYOUT_CONCURRENCY ? raw : envDefaultLayoutMaxConcurrency;
+}
+
+/** A minimal FIFO counting semaphore: at most `max` holders run concurrently, the rest queue in
+ * arrival order. Bounds how many CPU-bound layout workers exist at once so a burst of overlapping
+ * preview/dispatch layouts cannot spawn an UNBOUNDED number of superlinear workers and saturate
+ * CPU/memory — the very starvation this off-thread move exists to prevent (issue #854). Each
+ * `acquire()` resolves with an idempotent `release` that hands the freed slot to the next waiter. */
+export class Semaphore {
+  private active = 0;
+  private readonly waiters: Array<() => void> = [];
+  private readonly max: number;
+
+  constructor(max: number) {
+    if (!Number.isInteger(max) || max < 1) {
+      throw new Error(`Semaphore: max must be a positive integer, got ${String(max)}`);
+    }
+    this.max = max;
+  }
+
+  /** Wait (FIFO) for a slot, then return a one-shot `release`. Always `release()` in a `finally` so a
+   * rejecting holder cannot leak its slot and wedge every queued layout behind it. */
+  async acquire(): Promise<() => void> {
+    await new Promise<void>((resolve) => {
+      if (this.active < this.max) {
+        this.active++;
+        resolve();
+      } else {
+        this.waiters.push(() => {
+          this.active++;
+          resolve();
+        });
+      }
+    });
+    let released = false;
+    return () => {
+      if (released) return; // idempotent: a double release must not free a slot it never held
+      released = true;
+      this.active--;
+      this.waiters.shift()?.();
+    };
+  }
+}
+
+/** The ONE shared gate bounding concurrent layout workers, sized lazily on first use from
+ * {@link layoutMaxConcurrency}. A singleton so EVERY `layoutBpmnOffThread` call — across both the
+ * dispatch and preview paths — contends for the same small pool of slots. */
+let layoutGate: Semaphore | undefined;
+function layoutConcurrencyGate(): Semaphore {
+  if (!layoutGate) layoutGate = new Semaphore(layoutMaxConcurrency());
+  return layoutGate;
+}
+
+/** The worker message shape: a laid-out XML payload on success, or a server-side error string. */
+type LayoutWorkerMessage = { ok: true; laidOut: string } | { ok: false; error: string };
+
+/** Run `layoutBpmn(semanticBpmn)` in a dedicated `worker_threads` worker, OFF the main event loop,
+ * bounded by `timeoutMs`. Resolves with the laid-out XML; rejects (and TERMINATES the worker — the
+ * bound that stops a runaway layout) on timeout, a worker error, an early exit, or a layout failure
+ * reported by the worker. The worker is always torn down before this resolves/rejects, so no isolate
+ * leaks across calls. At most {@link layoutMaxConcurrency} workers run at once (the shared
+ * {@link Semaphore} gate) — a burst of overlapping preview/dispatch layouts queues for a slot rather
+ * than spawning an unbounded number of superlinear CPU-bound workers that would saturate the host.
+ * The timeout covers only the ACTUAL layout (it starts after a slot is acquired), so queueing behind
+ * other layouts is never charged against a graph's bound.
+ *
+ * `spawnWorker` is an injectable seam (default: the real `layoutWorker.ts` worker) so a test can force
+ * a SYNCHRONOUS construction failure — `new Worker(...)` can throw (e.g. `ERR_WORKER_INIT_FAILED`
+ * under resource pressure) — and prove the slot is still released (see below). */
+export async function layoutBpmnOffThread(
+  semanticBpmn: string,
+  timeoutMs: number = layoutTimeoutMs(),
+  spawnWorker: () => Worker = () =>
+    new Worker(new URL("./layoutWorker.ts", import.meta.url), { workerData: { semanticBpmn } }),
+): Promise<string> {
+  // Acquire the slot, then wrap EVERYTHING — including worker construction — in the release `finally`.
+  // `new Worker(...)` can throw synchronously (e.g. `ERR_WORKER_INIT_FAILED` under resource pressure);
+  // if construction sat outside this guard, each such failure would permanently consume a slot and,
+  // after `max` failures, wedge every later layout waiting on the gate forever (issue #854 review).
+  const release = await layoutConcurrencyGate().acquire();
+  try {
+    const worker = spawnWorker();
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    try {
+      return await new Promise<string>((resolve, reject) => {
+        let settled = false;
+        const settle = (fn: () => void) => {
+          if (settled) return;
+          settled = true;
+          if (timer) clearTimeout(timer);
+          fn();
+        };
+        timer = setTimeout(() => {
+          settle(() =>
+            reject(
+              new Error(
+                `layoutDeliveryDiagram: BPMN autolayout exceeded its ${timeoutMs}ms bound and was aborted — the ` +
+                  "delivery graph is too large/dense to lay out within the timeout (bpmn-auto-layout is superlinear in " +
+                  "node/edge count, issue #854). The launch was failed cleanly rather than hung; retune " +
+                  `\`NANO_DELIVERY_LAYOUT_TIMEOUT_MS\` (default ${envDefaultLayoutTimeoutMs}) or shrink the graph.`,
+              ),
+            ),
+          );
+        }, timeoutMs);
+        // A setTimeout in a hot dispatch path should not itself keep a draining process alive.
+        timer.unref?.();
+        worker.once("message", (msg: LayoutWorkerMessage) => {
+          settle(() => {
+            if (msg.ok) resolve(msg.laidOut);
+            else reject(new Error(msg.error));
+          });
+        });
+        worker.once("error", (err) => settle(() => reject(err)));
+        worker.once("exit", (code) => {
+          if (code === 0) return; // a clean exit after a delivered message is expected on teardown
+          settle(() => reject(new Error(`layoutDeliveryDiagram: layout worker exited early with code ${code}`)));
+        });
+      });
+    } finally {
+      if (timer) clearTimeout(timer);
+      await worker.terminate();
+    }
+  } finally {
+    release(); // hand our slot to the next queued layout — ALWAYS, even on a construction throw/reject/terminate
+  }
+}

package/app/layoutWorker.ts

@@ -0,0 +1,34 @@
+// app/layoutWorker.ts — the `node:worker_threads` entry that runs the CPU-bound BPMN autolayout
+// (`layoutBpmn` → `bpmn-auto-layout`) OFF the app's main event loop (issue #854).
+//
+// `bpmn-auto-layout` is superlinear in node/edge count: on the 54-node merlin delivery graph it ran
+// ~52s on merlin and >4min under real load, and because it ran SYNCHRONOUSLY on the event loop in
+// `layoutDeliveryDiagram`, the whole app served no HTTP and ran no poll passes for that entire window
+// — the operator saw a hard lock-up (#852). Hoisting the layout into this worker keeps the main loop
+// free to serve pages/API/MCP and tick its poll loop while a large graph lays out; the parent bounds
+// the work with a timeout and TERMINATES this worker on expiry (see `app/layoutOffThread.ts`), so a
+// pathological graph fails the launch cleanly instead of hanging forever.
+//
+// Protocol: `workerData.semanticBpmn` carries the pre-layout semantic BPMN; we post back either the
+// laid-out XML (a string) on success or `{ error }` on failure. We never `process.exit` — resolving
+// the message lets the parent `terminate()` us.
+
+import { parentPort, workerData } from "node:worker_threads";
+import { layoutBpmn } from "@nanobpm/urban";
+
+async function run(): Promise<void> {
+  const port = parentPort;
+  if (!port) throw new Error("layoutWorker: must be spawned as a worker_threads worker (no parentPort)");
+  const { semanticBpmn } = workerData ?? {};
+  if (typeof semanticBpmn !== "string") {
+    throw new Error("layoutWorker: workerData.semanticBpmn must be a string");
+  }
+  try {
+    const laidOut = await layoutBpmn(semanticBpmn);
+    port.postMessage({ ok: true, laidOut });
+  } catch (err) {
+    port.postMessage({ ok: false, error: err instanceof Error ? err.message : String(err) });
+  }
+}
+
+void run();

package/docs/agent-guide.md

@@ -564,10 +564,33 @@ layer schedules, it does not re-implement execution):
 
 | kind | config | what it does | may `emits`? |
 |---|---|---|---|
-| `agent` | `agent: { jobType, prompt?, converge?, merge? }` | a worker runs an agent job type (the fan-out body). **Side-effecting.** First-class **`converge?` / `merge?`** cell policy (§9.4) — a **declared, compiler-validated** completion-policy flag that *declares* review-convergence / landing intent (`merge` requires `converge`); a raw `senior:converge`/`senior:merge` job is rejected. This slice adds + validates the flags; the delivery-graph execution wiring that consumes them lands in a follow-up slice. | yes |
+| `agent` | `agent: { jobType, repository?, baseBranch?, prompt?, converge?, merge?, timeout? }` | a worker runs an agent job type (the fan-out body) in a fresh checkout of its `repository` (see *Provision every agent node* below). **Side-effecting.** First-class **`converge?` / `merge?`** cell policy (§9.4) — a **declared, compiler-validated** completion-policy flag that *declares* review-convergence / landing intent (`merge` requires `converge`); a raw `senior:converge`/`senior:merge` job is rejected. This slice adds + validates the flags; the delivery-graph execution wiring that consumes them lands in a follow-up slice. **`timeout?`** is an OPTIONAL per-node ISO-8601 SLA (#505) that overrides the run-level `nodeTimeout` (and the `PT1H` default) for this node's bounded-timeout → escalate boundary, so a legitimately-long node outlasts a quick gate without a spurious escalation. | yes |
 | `wait` | `wait: <ReadinessProbe>` | a durable, bounded readiness probe — kind ∈ `http`, `command`, `npm`, `github-check`, `capability`, `pr`, `epic`. Read-only. | yes (binds observed facts) |
 | `human` | `human?: { formKey?, prompt? }` | a scheduled user task + form (the Tasks inbox, §3). Blocks dependents, SLA-bounded, answerable by a human **or** an agent. | yes |
-| `connector` | `connector: { target, dedupeKey?, payload? }` | an automated, side-effecting outbound action. Carries a `dedupeKey` (at-least-once safe). Three **real targets** ship today — **`converge`**, **`converge-merge`** (unit → base branch) and **`merge-main`** (graph → `main`, the two-level top-level land) (§9.4); other targets are a forward-declared stub. | yes |
+| `connector` | `connector: { target, dedupeKey?, payload?, timeout? }` | an automated, side-effecting outbound action. Carries a `dedupeKey` (at-least-once safe). Three **real targets** ship today — **`converge`**, **`converge-merge`** (unit → base branch) and **`merge-main`** (graph → `main`, the two-level top-level land) (§9.4); other targets are a forward-declared stub. **`timeout?`** — a per-node ISO-8601 SLA (#505), same semantics as the `agent` row. | yes |
+
+> **Provision every `agent` node with a repository — compile will NOT catch it.** Each `agent` cell
+> runs in an isolated checkout: the harness clones the node's **`repository`** (`owner/repo`, no
+> `.git`/URL) at **`baseBranch`** and cuts `feat/<node.id>` off it (#739/#776). `baseBranch` resolves
+> **per field** — the node's own, else the **run-level dispatch `baseBranch`**, else the repo default
+> (an id yielding an ill-formed ref like `a..b`/`a.lock` makes the harness skip `branch.create`, so
+> the agent cuts its own branch). A node with **no `repository`** is staged by compile **without a
+> warning**, then — absent a **run-level fallback** supplied *at dispatch* — Dispatch fails with
+> `N agent node(s) resolve to no repository (…)`. So:
+>
+> - **Declare `repository` on EVERY `agent` node** (and `baseBranch` when it is neither the run-level
+>   base nor the default): a single-repo graph repeats one value; a cross-repo graph names each node's
+>   own repo. Every repo a node's prompt changes must be that node's `repository`.
+> - **`repoless` is a RUN-WIDE mode, not a per-node escape hatch** — it strips isolation from *every*
+>   node. Use it only when **every** `agent` node is checkout-less (pure research/comment work); if
+>   even one needs a checkout, provision repositories instead.
+> - **Self-check before handing over the digest:** every `"kind": "agent"` node has a `repository`;
+>   if you leave some unset, tell the operator which, and that they must pick the run-level
+>   **repository + base-branch fallback** in the Dispatch form (the default mode rejects the graph).
+>
+> A **present** `repository`/`baseBranch` is validated at compile (`invalid-node-repository` /
+> `invalid-node-base-branch`); an **absent `repository`** defers to dispatch (and can fail there); an
+> **absent `baseBranch` is always valid** — it inherits the run-level base, else the repo default.
 
 A **`wait` node's `wait` is a `ReadinessProbe` verbatim** (the same shape feature-run
 intake uses): `{ kind, target, onTimeout?, match?, poll? }`, where `poll` is
@@ -720,12 +743,12 @@ publish and records the version → open+merge PR #303 (repo 3) consuming that v
       "wait": { "kind": "pr", "target": "acme/repo-1#101", "match": { "prState": "merged" },
                 "poll": { "everyMs": 300000, "timeoutMs": 259200000 }, "onTimeout": "escalate" } },
     { "id": "undraft-merge-b", "kind": "agent",
-      "agent": { "jobType": "senior:feature", "converge": true, "merge": true, "prompt": "Take draft PR acme/repo-2#202 out of draft; converge it to green and land it." } },
+      "agent": { "jobType": "senior:feature", "repository": "acme/repo-2", "converge": true, "merge": true, "prompt": "Take draft PR acme/repo-2#202 out of draft; converge it to green and land it." } },
     { "id": "manual-publish", "kind": "human",
       "human": { "prompt": "Run the manual OTP-authenticated `npm publish` for @acme/widget and set up OIDC trusted publishing. Record the exact published version." },
       "emits": [ { "name": "publishedVersion", "type": "version", "description": "The version just published to npm." } ] },
     { "id": "open-pr-c", "kind": "agent",
-      "agent": { "jobType": "senior:feature", "prompt": "Bump @acme/widget to the published version in acme/repo-3 and open PR #303." } },
+      "agent": { "jobType": "senior:feature", "repository": "acme/repo-3", "prompt": "Bump @acme/widget to the published version in acme/repo-3 and open PR #303." } },
     { "id": "merge-c", "kind": "wait",
       "wait": { "kind": "pr", "target": "acme/repo-3#303", "match": { "prState": "merged" },
                 "poll": { "everyMs": 300000, "timeoutMs": 259200000 }, "onTimeout": "escalate" } }
@@ -804,7 +827,7 @@ author never knows the PR number at compose time, so reference it by fact:
   "name": "open → converge+merge → wait merged",
   "nodes": [
     { "id": "open", "kind": "agent",
-      "agent": { "jobType": "senior:feature", "prompt": "Implement the change in acme/repo and open a PR." },
+      "agent": { "jobType": "senior:feature", "repository": "acme/repo", "prompt": "Implement the change in acme/repo and open a PR." },
       "emits": [ { "name": "pr", "type": "pr" } ] },
     { "id": "land", "kind": "connector",
       "connector": { "target": "converge-merge", "payload": { "pr": "open.pr" } } },
@@ -870,7 +893,7 @@ babysitting a `confirm` gate.
                 "onTimeout": "escalate" },
       "emits": [ { "name": "prCount", "type": "number" } ] },
     { "id": "start-b", "kind": "agent",
-      "agent": { "jobType": "senior:feature", "prompt": "Implement nanobpm/nano-workforce#567 and open a PR." } }
+      "agent": { "jobType": "senior:feature", "repository": "nanobpm/nano-workforce", "prompt": "Implement nanobpm/nano-workforce#567 and open a PR." } }
   ],
   "edges": [ { "from": "gate-epic", "to": "start-b" } ]
 }

package/openapi.yaml

@@ -2025,6 +2025,7 @@ components:
             kind: agent
             agent:
               jobType: senior:feature
+              repository: nanobpm/nano-workforce
               prompt: Implement nanobpm/nano-workforce#567 and open a PR.
         edges:
           - { from: gate-epic, to: start-b }
@@ -2406,7 +2407,7 @@ components:
       # cockpit paste). `previewDeliveryGraph` takes `{ "graphJson": "<serialized DeliveryGraph>" }`.
       example:
         graphJson: >-
-          {"name":"start #567 once epic #488 has fully merged","nodes":[{"id":"gate-epic","kind":"wait","wait":{"kind":"epic","target":"nanobpm/nano-ide#488","match":{"epicState":"merged"},"poll":{"everyMs":300000,"timeoutMs":259200000},"onTimeout":"escalate"},"emits":[{"name":"prCount","type":"number"}]},{"id":"start-b","kind":"agent","agent":{"jobType":"senior:feature","prompt":"Implement nanobpm/nano-workforce#567 and open a PR."}}],"edges":[{"from":"gate-epic","to":"start-b"}]}
+          {"name":"start #567 once epic #488 has fully merged","nodes":[{"id":"gate-epic","kind":"wait","wait":{"kind":"epic","target":"nanobpm/nano-ide#488","match":{"epicState":"merged"},"poll":{"everyMs":300000,"timeoutMs":259200000},"onTimeout":"escalate"},"emits":[{"name":"prCount","type":"number"}]},{"id":"start-b","kind":"agent","agent":{"jobType":"senior:feature","repository":"nanobpm/nano-workforce","prompt":"Implement nanobpm/nano-workforce#567 and open a PR."}}],"edges":[{"from":"gate-epic","to":"start-b"}]}
       required:
         - graphJson
       properties:
@@ -5016,6 +5017,7 @@ paths:
                     kind: agent
                     agent:
                       jobType: senior:feature
+                      repository: nanobpm/nano-workforce
                       prompt: Implement nanobpm/nano-workforce#567 and open a PR.
                 edges:
                   - from: gate-epic
@@ -5467,7 +5469,7 @@ paths:
               type: object
               additionalProperties: false
               example:
-                graphJson: '{"name":"start #567 once epic #488 has fully merged","nodes":[{"id":"gate-epic","kind":"wait","wait":{"kind":"epic","target":"nanobpm/nano-ide#488","match":{"epicState":"merged"},"poll":{"everyMs":300000,"timeoutMs":259200000},"onTimeout":"escalate"},"emits":[{"name":"prCount","type":"number"}]},{"id":"start-b","kind":"agent","agent":{"jobType":"senior:feature","prompt":"Implement nanobpm/nano-workforce#567 and open a PR."}}],"edges":[{"from":"gate-epic","to":"start-b"}]}'
+                graphJson: '{"name":"start #567 once epic #488 has fully merged","nodes":[{"id":"gate-epic","kind":"wait","wait":{"kind":"epic","target":"nanobpm/nano-ide#488","match":{"epicState":"merged"},"poll":{"everyMs":300000,"timeoutMs":259200000},"onTimeout":"escalate"},"emits":[{"name":"prCount","type":"number"}]},{"id":"start-b","kind":"agent","agent":{"jobType":"senior:feature","repository":"nanobpm/nano-workforce","prompt":"Implement nanobpm/nano-workforce#567 and open a PR."}}],"edges":[{"from":"gate-epic","to":"start-b"}]}'
               required:
                 - graphJson
               properties:
@@ -5876,10 +5878,10 @@ paths:
                     - kind: agent
                       configKey: agent
                       requiredFields: [jobType]
-                      optionalFields: [prompt, converge, merge]
+                      optionalFields: [repository, baseBranch, prompt, converge, merge, timeout]
                       sideEffecting: true
                       mayEmit: true
-                      summary: "A worker runs an agent job type; an agent that opens a PR emits it as a `pr` fact."
+                      summary: "A worker runs an agent job type in an isolated checkout; declare `repository` (`owner/repo`) on every agent node — the harness clones it at `baseBranch` (else the run-level dispatch base, else the repo default). Optional per-node ISO-8601 `timeout`, plus `converge?`/`merge?` cell-policy flags. An agent that opens a PR emits it as a `pr` fact."
                     - kind: wait
                       configKey: wait
                       requiredFields: [kind, target]
@@ -5890,7 +5892,7 @@ paths:
                     - kind: connector
                       configKey: connector
                       requiredFields: [target]
-                      optionalFields: [dedupeKey, payload]
+                      optionalFields: [dedupeKey, payload, timeout]
                       sideEffecting: true
                       mayEmit: true
                       summary: "An automated outbound action; payload for a converge target is { pr, autoMerge?, dependsOn? }."

package/operations/getAgentInstructions.test.ts

@@ -61,10 +61,15 @@ test("the guide documents the delivery-graph surface (ADR 0005)", async () => {
   // The closed node vocabulary: assert the exact config snippet for each of the four kinds,
   // so the test fails if §9's node-kind table is removed or reworded — not merely if the bare
   // words "agent"/"wait"/"human"/"connector" appear anywhere else in the guide.
-  assert(md.includes("agent: { jobType, prompt?, converge?, merge? }"), "documents the agent node config");
+  assert(md.includes("agent: { jobType, repository?, baseBranch?, prompt?, converge?, merge?, timeout? }"), "documents the agent node config");
+  // Per-node repository provisioning is only enforced at DISPATCH (a run-level fallback can satisfy it),
+  // so compile stages an unprovisioned graph silently — the guide must tell the authoring agent to
+  // declare `repository` on every agent node, or the operator's Dispatch fails out of the agent's loop.
+  assert(md.includes("Provision every `agent` node with a repository"), "documents per-node repository provisioning");
+  assert(md.includes("resolve to no repository"), "quotes the dispatch-time failure the agent must pre-empt");
   assert(md.includes("wait: <ReadinessProbe>"), "documents the wait node config");
   assert(md.includes("human?: { formKey?, prompt? }"), "documents the human node config");
-  assert(md.includes("connector: { target, dedupeKey?, payload? }"), "documents the connector node config");
+  assert(md.includes("connector: { target, dedupeKey?, payload?, timeout? }"), "documents the connector node config");
   // The fact-edge syntax: an edge is `{ from, to }` and `from` may be a qualified `<nodeId>.<fact>`.
   assert(md.includes("each edge is `{ from, to }`"), "documents the edge shape");
   assert(md.includes("qualified `<nodeId>.<fact>`"), "documents the qualified fact-edge syntax");

package/package.json

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

package/test/deliveryGraphVocabulary-mcp.test.ts

@@ -60,3 +60,35 @@ test("the served payload matches the response schema's required keys (data ⇄ c
     assert(key in payload, `served vocabulary is missing required schema key '${key}'`);
   }
 });
+
+test("the worked example's nodeKind field contract cannot drift from the runtime vocabulary", () => {
+  // The spec's `example:` is a hand-authored YAML copy of the served payload (the runtime cannot be
+  // called from a static spec). It is a deliberately curated SUBSET (fewer kinds / terser summaries),
+  // but the per-kind FIELD CONTRACT it advertises is consumer-facing: a stale `optionalFields` makes
+  // agents author nodes that omit real fields (#739/#776 — `repository`/`baseBranch`/`timeout`), and a
+  // stale `configKey`/`sideEffecting`/`mayEmit` misleads them the same way. Guard the class, not one
+  // field: every nodeKind the example shows must carry EXACTLY the runtime kind's whole contract object
+  // — `kind`, `configKey`, `requiredFields`, `optionalFields`, `sideEffecting`, `mayEmit` — so no part
+  // of the two surfaces can drift apart again. Only `summary` is excluded: the example's is a
+  // deliberately terser curated paraphrase of the runtime's (see this block's preamble).
+  const doc = parseYaml(SPEC_TEXT) as Record<string, any>;
+  const exampleKinds = doc.paths["/delivery-graph/vocabulary"].get.responses["200"].content["application/json"].schema
+    .example?.nodeKinds as Array<Record<string, unknown>> | undefined;
+  assert(Array.isArray(exampleKinds) && exampleKinds.length > 0, "the worked example must list nodeKinds");
+
+  // Compare the full per-kind contract minus `summary` (the sole intentionally-divergent field).
+  const contract = ({ summary: _summary, ...rest }: Record<string, unknown>): Record<string, unknown> => rest;
+
+  const runtimeByKind = new Map(
+    (deliveryGraphVocabulary().nodeKinds as Array<Record<string, unknown>>).map((k) => [k.kind, k]),
+  );
+  for (const shown of exampleKinds) {
+    const runtime = runtimeByKind.get(shown.kind);
+    assert(runtime, `example nodeKind '${String(shown.kind)}' is not a real runtime kind (stale/removed)`);
+    assert.deepEqual(
+      contract(shown),
+      contract(runtime!),
+      `example nodeKind '${String(shown.kind)}' field contract (configKey/requiredFields/optionalFields/sideEffecting/mayEmit) drifted from runtime`,
+    );
+  }
+});