@nanobpm/nano-workforce 0.199.0 → 0.200.1

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [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
+
+* **convergence:** local adversarial-review agent pass before Copilot ([#845](https://github.com/nanobpm/nano-workforce/issues/845)) ([3aec0da](https://github.com/nanobpm/nano-workforce/commit/3aec0da99224dd29f43566a9c75a5cf34dbc843a)), closes [#842](https://github.com/nanobpm/nano-workforce/issues/842) [#844](https://github.com/nanobpm/nano-workforce/issues/844) [#844](https://github.com/nanobpm/nano-workforce/issues/844) [#844](https://github.com/nanobpm/nano-workforce/issues/844) [#822](https://github.com/nanobpm/nano-workforce/issues/822)
+
 ## [0.199.0](https://github.com/nanobpm/nano-workforce/compare/v0.198.1...v0.199.0) (2026-10-02)
 
 ### Features

package/SPEC.md

@@ -110,7 +110,13 @@ known at submit time, carried as a process variable and stored on the DB row.
 │      │                                 → [Escalate: unaddressed comments] (blocked)             │
 │      │                                 → [Wait: wait-answer userTask] ────────────────────────────┤
 │      │                                                                                          │
-│      ├── addressed  → [Record round] → [Check progress] (did the PR head advance?)              │
+│      ├── addressed  → <adversarial pass due? (#844)>                                             │
+│      │  (or waiting)    ├── pass due (addressed, or first push; budget unspent)                  │
+│      │                  │      → [Adversarial review] (service task, taskType: senior:adversarial-review) │
+│      │                  │          → <findings?> ── findings → re-dispatch [Review round] (round unchanged) │
+│      │                  │                          └── clean → [Record round]                    │
+│      │                  └── disabled / budget spent → [Record round]                             │
+│      │                        [Record round] → [Check progress] (did the PR head advance?)       │
 │      │                   ├── progressed → <guard: round ≥ maxRounds → escalate "not converged"> │
 │      │                   │                   → <event-based gateway: review ready or timeout?>   │
 │      │                   │      ├── readiness-ready (msg catch, key = prKey) → round++ ─┐        │
@@ -139,6 +145,21 @@ step, then retry the same round with the human's `answer`. They differ only by e
 which the UI uses to label the card. Neither ends the run — a human always gets
 a chance to unblock and resume.
 
+**Local adversarial-review stage (issue #844).** Before an `addressed` or first-push
+`waiting` round parks on `waiting_review` (the only status the poller solicits a Copilot
+review for), the loop runs a bounded local adversarial pass over the round's diff. The
+`<adversarial pass due?>` gate (`gw-adv-due`) fires when the per-round budget is unspent
+and the round is `addressed` **or** the first push (`advMax != null and advPass < advMax
+and (status != "waiting" or round = 1)`); otherwise (disabled, budget spent) it skips
+straight to `[Record round]`. The `senior:adversarial-review` service task (prompt
+delivered via the `prompts/adversarial-review.md` linked resource) critiques the diff and
+returns `adversarialFindings`. Non-blank findings **re-dispatch `[Review round]` within the
+same round** (round unchanged) with `adversarialFindings` seeded, so the agent fixes them
+before this app's poller solicits the Copilot review (the only `waiting_review` trigger); a
+clean result records the round and proceeds to `[Check progress]`. The pass budget is
+`MAX_ADVERSARIAL_PASSES` (default 1,
+`NANO_PR_MAX_ADVERSARIAL_PASSES=0` disables the stage).
+
 **Durable adjudication auto-resume (issue #806).** A human's answer to a `wait-answer`
 is remembered durably, keyed by `(PR, canonical question fingerprint)` — the
 `record-answer` step persists it (`pr_adjudications`), and before the poller surfaces a
@@ -350,6 +371,7 @@ Notes:
 | `prNumber` | int | |
 | `round` | int | 1-based round counter |
 | `answer` | string? | present only when resuming from an escalation |
+| `adversarialFindings` | string? | present only when the local adversarial-review stage (§4) produced findings on this round's push — the agent is re-dispatched within the same round to address them |
 
 The base instructions are **not** a job variable: they are delivered as a
 **linked resource** on the `senior:pr-review` task —

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",
@@ -140,6 +156,14 @@ export const ENV_CONTRACTS = {
       "Maximum bounded review-round re-dispatches the convergence loop makes to auto-ack unacked suppressed advisories before escalating to a human (#796); 0 escalates on the first ack-only block.",
     default: "2",
   },
+  NANO_PR_MAX_ADVERSARIAL_PASSES: {
+    category: "env",
+    name: "NANO_PR_MAX_ADVERSARIAL_PASSES",
+    owner: "app/service.ts",
+    semantics:
+      "Maximum local adversarial-review agent passes per convergence round before the round parks for a Copilot review (#844); non-blank findings re-dispatch review-round. 0 disables the stage.",
+    default: "1",
+  },
   NANO_PR_MAX_MERGE_STALL_ROUNDS: {
     category: "env",
     name: "NANO_PR_MAX_MERGE_STALL_ROUNDS",

package/app/convergeAdversarial.test.ts

@@ -0,0 +1,294 @@
+// Behavioural coverage for the local adversarial-review pass on the convergence loop's ADDRESSED
+// path (issue #844, sub-issue of #842).
+//
+// Copilot had become our discovery loop: each finding costs a full GitHub re-review round, and many
+// are the obvious "next" finding a second reader would catch locally. So an `addressed` round now
+// runs a separate `senior:adversarial-review` agent BEFORE the round is persisted / parked on
+// `waiting_review` (the only status the poller solicits a Copilot review for). Non-blank findings
+// loop straight back into `review-round` (carrying `adversarialFindings`) — not through
+// `capture-head`, so the round-entry head and the no-progress check still span the whole round.
+// The pass count is BOUNDED per round by `advPass`/`advMax` and reset when a new review lands.
+//
+// These deploy the committed convergence-loop into the real WASM engine and drive tokens through it,
+// asserting what the loop DOES (element run counts, job inputs, the parked wait), not how it is drawn.
+import { after, test } from "node:test";
+import { assert } from "#test-assert";
+import { readFileSync } from "node:fs";
+import { assertThatInstance, byProcessId, createWasmEngineClient, type WasmEngineClient } from "@nanobpm/urban-testkit";
+
+const MODEL = readFileSync("resources/processes/convergence-loop.bpmn", "utf8");
+
+type Output = Record<string, unknown>;
+type Job = { variables: Record<string, unknown> };
+type Responder = Output | Output[] | ((job: Job) => Output);
+
+const ALL_JOB_TYPES = [
+  "senior:pr-review",
+  "senior:adversarial-review",
+  "pr.capture-head",
+  "pr.persist-round",
+  "pr.progress-check",
+  "pr.converge-gate",
+  "senior:scope-classify",
+  "pr.finalize",
+  "pr.persist-escalation",
+  "pr.answer-escalation",
+] as const;
+
+const FINDINGS = "Open: src/a.ts:10 fail-open on unknown input (high)";
+const CLEAN = { adversarialFindings: "", adversarialSummary: "no findings" };
+
+const DEFAULT_RESPONSES: Record<string, Responder> = {
+  "senior:pr-review": { status: "addressed", summary: "fixed" },
+  "senior:adversarial-review": CLEAN,
+  "pr.capture-head": { roundEntryHead: "sha-entry" },
+  "pr.persist-round": {},
+  "pr.progress-check": { progressed: true },
+  "pr.converge-gate": { convergeBlocked: false, convergeBlockReason: "", convergeAckOnly: false },
+  "senior:scope-classify": { scopeBlocked: false, scopeBlockReason: "" },
+  "pr.finalize": {},
+  "pr.persist-escalation": { escalated: true },
+  "pr.answer-escalation": {},
+};
+
+const DEFAULT_VARS: Record<string, unknown> = {
+  prKey: "o/r#1",
+  repo: "o/r",
+  prNumber: 1,
+  prUrl: "https://example.test/pr/1",
+  round: 1,
+  maxRounds: 20,
+  reviewWaitTimeout: "PT30M",
+  ackRetryRound: 0,
+  ackRetryMax: 2,
+  advPass: 0,
+  advMax: 1,
+  abandonBrief: null,
+  status: null,
+  question: null,
+  summary: null,
+  answer: null,
+  scopePending: false,
+  scopeAnswer: null,
+  convergeBlocked: null,
+  convergeBlockReason: null,
+  convergeAckOnly: null,
+  reviewStale: null,
+  roundEntryHead: null,
+  huskRetries: 0,
+  progressed: true,
+  escalated: null,
+};
+
+const engines: WasmEngineClient[] = [];
+after(async () => {
+  await Promise.all(engines.map((e) => e.close()));
+});
+
+/** Boot the loop; records every job's input variables per job type for assertions. */
+async function boot(opts: { responses?: Record<string, Responder>; vars?: Record<string, unknown> } = {}) {
+  const engine = await createWasmEngineClient();
+  engines.push(engine);
+  await engine.deployResources([{ name: "convergence-loop.bpmn", content: MODEL, contentType: "text/xml" }]);
+  const responses = { ...DEFAULT_RESPONSES, ...(opts.responses ?? {}) };
+  const seen: Record<string, Record<string, unknown>[]> = {};
+  for (const jobType of ALL_JOB_TYPES) {
+    const responder = responses[jobType];
+    const queue = Array.isArray(responder) ? [...responder] : null;
+    seen[jobType] = [];
+    await engine.registerWorker(jobType, (job) => {
+      seen[jobType].push({ ...(job as Job).variables });
+      if (queue) return queue.length > 1 ? queue.shift()! : (queue[0] ?? {});
+      if (typeof responder === "function") return responder(job as Job);
+      return responder ?? {};
+    });
+  }
+  await engine.createInstance({
+    processDefinitionId: "convergence-loop",
+    awaitCompletion: false,
+    variables: { ...DEFAULT_VARS, ...(opts.vars ?? {}) },
+  });
+  return { engine, seen };
+}
+
+function completions(engine: WasmEngineClient, elementId: string): number {
+  const snap = engine.snapshot() as { elementStats?: { elementId: string; completed: number }[] };
+  return (snap.elementStats ?? []).find((s) => s.elementId === elementId)?.completed ?? 0;
+}
+function instanceVars(engine: WasmEngineClient): Record<string, unknown> {
+  const snap = engine.snapshot() as { instances?: { variables?: Record<string, unknown> }[] };
+  return snap.instances?.[0]?.variables ?? {};
+}
+function runs(engine: WasmEngineClient): string {
+  return ["review-round", "adversarial-review", "persist-round", "check-progress"]
+    .map((id) => `${id}=${completions(engine, id)}`)
+    .join(" ");
+}
+
+test("addressed + adversarial findings loop back into review-round with the findings, then park for Copilot", async () => {
+  const { engine, seen } = await boot({
+    responses: { "senior:adversarial-review": [{ adversarialFindings: FINDINGS, adversarialSummary: "1 finding" }, CLEAN] },
+    vars: { advMax: 2 },
+  });
+  assertThatInstance(engine, byProcessId("convergence-loop")).isActive().hasNoIncident();
+  assert(completions(engine, "review-round") === 2, `review-round should run twice: ${runs(engine)}`);
+  assert(completions(engine, "adversarial-review") === 2, `adversarial-review should run twice: ${runs(engine)}`);
+  // The round is persisted and progress-checked ONCE, only after the adversarial pass came back clean.
+  assert(completions(engine, "persist-round") === 1, `persist-round once: ${runs(engine)}`);
+  assert(completions(engine, "check-progress") === 1, `check-progress once: ${runs(engine)}`);
+  // The loop goes straight back to review-round, not through capture-head (round-entry head kept).
+  assert(completions(engine, "capture-head") === 1, "the findings loop must not re-capture the round-entry head");
+  const reviewJobs = seen["senior:pr-review"];
+  assert(!reviewJobs[0].adversarialFindings, "the first review-round has no adversarial findings");
+  assert(reviewJobs[1].adversarialFindings === FINDINGS, "the re-dispatched review-round receives the findings");
+  // Parked on the Copilot review wait (the poller solicits only after progress-check parks it).
+  assert(completions(engine, "wait-review") === 0, "must be parked waiting for the review");
+});
+
+test("a clean adversarial pass proceeds straight to persist-round", async () => {
+  const { engine } = await boot();
+  assertThatInstance(engine, byProcessId("convergence-loop")).isActive().hasNoIncident();
+  assert(completions(engine, "review-round") === 1, runs(engine));
+  assert(completions(engine, "adversarial-review") === 1, runs(engine));
+  assert(completions(engine, "persist-round") === 1, runs(engine));
+});
+
+// Regression for Copilot review 5386944381 (round 5): the round-4 verdict reset on
+// `adversarial-review` was UNCONDITIONAL, so it also fired on the clean/default arm
+// (`f_advClean` -> `persist-round`). A first-round `waiting` verdict was therefore blanked before
+// `pr.progress-check` ran; the real worker classifies a blank status as `addressed`, and because the
+// head did not change it routed the initial pass to no-progress escalation instead of parking on
+// `waiting_review` for Copilot. The reset must be findings-ONLY: a clean pass must PRESERVE the
+// review-round verdict (status/summary/question) all the way to persist-round.
+test("a clean adversarial pass preserves a first-round waiting verdict for progress-check", async () => {
+  const { engine, seen } = await boot({
+    responses: {
+      "senior:pr-review": { status: "waiting", summary: "no review yet" },
+      "senior:adversarial-review": CLEAN,
+    },
+  });
+  assertThatInstance(engine, byProcessId("convergence-loop")).isActive().hasNoIncident();
+  assert(completions(engine, "adversarial-review") === 1, runs(engine));
+  assert(completions(engine, "persist-round") === 1, runs(engine));
+  // The clean pass must NOT blank the verdict: persist-round / progress-check see `waiting`, so the
+  // worker parks the PR on `waiting_review` (the only status the poller solicits a review for).
+  const recorded = seen["pr.persist-round"][0];
+  assert(
+    recorded.status === "waiting",
+    `a clean pass must preserve the waiting verdict; status reaching persist-round: ${JSON.stringify(recorded.status)}`,
+  );
+  const progress = seen["pr.progress-check"][0];
+  assert(
+    progress.status === "waiting",
+    `progress-check must see the waiting verdict, not a blanked one: ${JSON.stringify(progress.status)}`,
+  );
+});
+
+test("the adversarial pass is bounded by advMax per round", async () => {
+  const { engine } = await boot({
+    responses: { "senior:adversarial-review": { adversarialFindings: FINDINGS, adversarialSummary: "always" } },
+    vars: { advMax: 2 },
+  });
+  assertThatInstance(engine, byProcessId("convergence-loop")).isActive().hasNoIncident();
+  assert(completions(engine, "adversarial-review") === 2, `cap of 2 passes: ${runs(engine)}`);
+  // 1 initial + 2 findings loops = 3 review-rounds, then the round proceeds despite findings.
+  assert(completions(engine, "review-round") === 3, runs(engine));
+  assert(completions(engine, "persist-round") === 1, runs(engine));
+});
+
+test("advMax=0 disables the adversarial pass", async () => {
+  const { engine } = await boot({ vars: { advMax: 0 } });
+  assertThatInstance(engine, byProcessId("convergence-loop")).isActive().hasNoIncident();
+  assert(completions(engine, "adversarial-review") === 0, runs(engine));
+  assert(completions(engine, "persist-round") === 1, runs(engine));
+});
+
+test("an instance seeded without advPass/advMax (pre-#844 shape) skips the pass, no incident", async () => {
+  const { engine } = await boot({ vars: { advPass: null, advMax: null } });
+  assertThatInstance(engine, byProcessId("convergence-loop")).isActive().hasNoIncident();
+  assert(completions(engine, "adversarial-review") === 0, runs(engine));
+  assert(completions(engine, "persist-round") === 1, runs(engine));
+});
+
+// The FIRST push (#844): a PR enters the loop with no Copilot review yet, so round 1 returns
+// `waiting`. That never-reviewed head is exactly what Copilot would review first, so the adversarial
+// pass runs on it too — before progress-check parks the PR on `waiting_review` (which is what makes
+// the poller solicit the initial Copilot review). This covers every PR entering convergence
+// (feature runs, plan fan-out slices, human-submitted PRs) from the one canonical stage.
+test("the first push (round 1, no review yet) gets an adversarial pass before Copilot is solicited", async () => {
+  const { engine, seen } = await boot({
+    responses: {
+      "senior:pr-review": [{ status: "waiting", summary: "no review yet" }, { status: "addressed", summary: "fixed finding" }],
+      "senior:adversarial-review": [{ adversarialFindings: FINDINGS, adversarialSummary: "1 finding" }],
+    },
+  });
+  assertThatInstance(engine, byProcessId("convergence-loop")).isActive().hasNoIncident();
+  assert(completions(engine, "adversarial-review") === 1, `first push must be adversarially reviewed: ${runs(engine)}`);
+  assert(completions(engine, "review-round") === 2, `findings must re-dispatch review-round: ${runs(engine)}`);
+  assert(seen["senior:pr-review"][1].adversarialFindings === FINDINGS, "the re-dispatch carries the findings");
+  assert(completions(engine, "persist-round") === 1, runs(engine));
+  assert(completions(engine, "capture-head") === 1, "no head re-capture within the round");
+});
+
+test("a later waiting round (round > 1, review still pending) does not re-run the adversarial pass", async () => {
+  const { engine } = await boot({
+    vars: { round: 2 },
+    responses: { "senior:pr-review": { status: "waiting", summary: "review pending" } },
+  });
+  assertThatInstance(engine, byProcessId("convergence-loop")).isActive().hasNoIncident();
+  assert(completions(engine, "adversarial-review") === 0, runs(engine));
+  assert(completions(engine, "persist-round") === 1, runs(engine));
+});
+
+// Issue #822 husk failure mode ON THE FINDINGS BACK-EDGE: the `f_advFindings` edge re-dispatches
+// `review-round` straight from `gw-adv-result`, bypassing `capture-head` — so it must not inherit the
+// PRIOR review-round's verdict. Here round 1 returns `waiting` (no review yet), the adversarial pass
+// finds a finding, and the re-dispatched `review-round` HUSKS (completes with NO result vars). If the
+// back-edge does not reset the round's output vars, the stale `status="waiting"` survives into
+// gw-status / persist-round even though the findings were never handled. The back-edge must clear
+// `status`/`summary`/`question` (a findings-only reset) while PRESERVING `roundEntryHead`, `advPass`
+// and `adversarialFindings` (so the budget and the findings survive the re-dispatch).
+test("a husked re-dispatch on the findings back-edge does not reuse the prior round's verdict", async () => {
+  const { engine, seen } = await boot({
+    responses: {
+      // Round 1 review-round: waiting (no review yet). Re-dispatched review-round: HUSK ({}).
+      "senior:pr-review": [{ status: "waiting", summary: "no review yet" }, {}],
+      "senior:adversarial-review": [{ adversarialFindings: FINDINGS, adversarialSummary: "1 finding" }],
+    },
+    vars: { advMax: 1 },
+  });
+  assertThatInstance(engine, byProcessId("convergence-loop")).isActive().hasNoIncident();
+  assert(completions(engine, "review-round") === 2, `findings re-dispatch review-round: ${runs(engine)}`);
+  assert(completions(engine, "adversarial-review") === 1, runs(engine));
+  assert(completions(engine, "persist-round") === 1, runs(engine));
+  // The findings survived the re-dispatch (the husked review-round received them)...
+  assert(seen["senior:pr-review"][1].adversarialFindings === FINDINGS, "the re-dispatch carries the findings");
+  // ...and the pass budget was consumed (advPass incremented, NOT reset to 0 by a capture-head re-entry).
+  assert(instanceVars(engine).advPass === 1, `advPass preserved across the back-edge: ${instanceVars(engine).advPass}`);
+  // ...but the stale `waiting` verdict did NOT reach persist-round: the back-edge reset it to blank,
+  // so the round is recorded on the safe default rather than the inherited `waiting`.
+  const recorded = seen["pr.persist-round"][0];
+  assert(
+    recorded.status == null || recorded.status === "",
+    `a husked re-dispatch must not record the stale verdict; status reaching persist-round: ${JSON.stringify(recorded.status)}`,
+  );
+});
+
+test("a converged round does not run the adversarial pass", async () => {
+  const { engine } = await boot({ responses: { "senior:pr-review": { status: "converged", summary: "done" } } });
+  assertThatInstance(engine, byProcessId("convergence-loop")).hasCompleted().hasNoIncident();
+  assert(completions(engine, "adversarial-review") === 0, runs(engine));
+});
+
+test("the pass budget resets when the next review lands (new round)", async () => {
+  const { engine } = await boot({
+    responses: { "senior:adversarial-review": { adversarialFindings: FINDINGS, adversarialSummary: "always" } },
+    vars: { advMax: 1 },
+  });
+  assert(completions(engine, "adversarial-review") === 1, runs(engine));
+  assert(instanceVars(engine).advPass === 1, `advPass after round 1: ${instanceVars(engine).advPass}`);
+  await engine.publishMessage({ name: "readiness-ready", correlationKey: "o/r#1", variables: { ready: true } });
+  assertThatInstance(engine, byProcessId("convergence-loop")).isActive().hasNoIncident();
+  // Round 2 gets its own full budget of 1 pass.
+  assert(completions(engine, "adversarial-review") === 2, `round 2 must get a fresh pass: ${runs(engine)}`);
+});

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}")`,
+    );
+  }
+});