@nanobpm/nano-workforce 0.200.0 → 0.200.1

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [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/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/package.json

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