@nanobpm/nano-workforce 0.178.0 → 0.178.1

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.178.1](https://github.com/nanobpm/nano-workforce/compare/v0.178.0...v0.178.1) (2026-09-03)
+
+### Bug Fixes
+
+* **mcp:** stage delivery graphs on a layout-free fast path so cold heavy tools don't time out ([#718](https://github.com/nanobpm/nano-workforce/issues/718)) ([c94ab00](https://github.com/nanobpm/nano-workforce/commit/c94ab00f091dbc5e529138e6818365c5794a1e25)), closes [#715](https://github.com/nanobpm/nano-workforce/issues/715) [nanobpm/nano-ide#488](https://github.com/nanobpm/nano-ide/issues/488) [#716](https://github.com/nanobpm/nano-workforce/issues/716) [#716](https://github.com/nanobpm/nano-workforce/issues/716) [#716](https://github.com/nanobpm/nano-workforce/issues/716)
+
 ## [0.178.0](https://github.com/nanobpm/nano-workforce/compare/v0.177.0...v0.178.0) (2026-09-03)
 
 ### Features

package/app/deliveryGraphCompiler.ts

@@ -260,23 +260,47 @@ function mustGet<K, V>(map: ReadonlyMap<K, V>, key: K): V {
   return value;
 }
 
+/** The compiler result BEFORE diagram-interchange layout: everything the generated
+ * `CompileDeliveryGraphResult` carries EXCEPT the laid-out `bpmn`, plus the `semanticBpmn` (the
+ * pre-layout, DI-less BPMN). `compileDeliveryGraphSemantic` produces this cheaply (no
+ * `layoutBpmn`); `compileDeliveryGraph` layers the CPU-bound DI layout on top. Because the DI is
+ * DERIVED deterministically from `semanticBpmn`, `semanticBpmn` is the canonical content of a graph —
+ * the source `deliveryGraphDigest` content-addresses (issue #716). */
+export interface CompiledDeliveryGraphSemantic {
+  ok: true;
+  /** A human-readable mermaid `flowchart` of the resolved graph. */
+  diagram: string;
+  /** The compiled one-shot BPMN process definition WITHOUT diagram interchange — the canonical,
+   * layout-independent content of the graph. Deterministic: same input graph → byte-identical XML. */
+  semanticBpmn: string;
+  resolved: CompileDeliveryGraphResult["resolved"];
+  humanNodes: CompileDeliveryGraphResult["humanNodes"];
+  sideEffects: CompileDeliveryGraphResult["sideEffects"];
+}
+
+/** A fully-compiled graph — the generated wire result (`diagram`, laid-out `bpmn`, …) PLUS the
+ * pre-layout `semanticBpmn` the content digest is taken over. */
+export type CompiledDeliveryGraph = CompileDeliveryGraphResult & { semanticBpmn: string };
+
 /**
- * Validate + compile a delivery graph into a PURE preview (ADR 0005 slice S1). Returns
- * `{ ok:true, diagram, bpmn, resolved, humanNodes, sideEffects }` for a well-formed graph, or
- * `{ ok:false, errors }` (each error path-qualified) for a malformed one. NEVER deploys, dispatches,
- * or mutates anything — safe to call repeatedly. Deterministic: identical input JSON yields
- * byte-identical output.
+ * Validate + compile a delivery graph into a PURE preview WITHOUT the CPU-bound diagram-interchange
+ * layout (issue #716). Returns `{ ok:true, diagram, semanticBpmn, resolved, humanNodes, sideEffects }`
+ * for a well-formed graph, or `{ ok:false, errors }` (each error path-qualified) for a malformed one.
+ * NEVER deploys, dispatches, or mutates anything — safe to call repeatedly. Deterministic: identical
+ * input JSON yields byte-identical output.
  *
- * ASYNC because the final step attaches DIAGRAM INTERCHANGE (`bpmndi:BPMNDiagram`) via the toolkit
- * autolayout (`layoutBpmn` — `bpmn-auto-layout`), the SAME pass every AUTHORED process gets from
- * `npm run layout` (`scripts/layout-bpmn.ts`). This is the one BPMN in the system generated at
- * runtime, so without this it was the only one shipping DI-less — unrenderable in the process
- * explorer (#440). `layoutBpmn` is itself deterministic given identical semantic input, so
- * "same JSON → byte-identical XML" still holds with the diagram included.
+ * This is the fast path the agent-facing compile/stage doors (`compileDeliveryGraph` /
+ * `sequenceIssues` → `compileAndStageDeliveryGraph`) take: staging needs only the content digest (taken
+ * over `semanticBpmn`), the mermaid `diagram`, and the resolved model — NOT the laid-out `bpmn`. Skipping
+ * `layoutBpmn` (`bpmn-auto-layout`, superlinear in node/edge count — minutes on a 256-node/1024-edge
+ * graph) keeps a cold MCP tool call well under the client's per-call timeout instead of tripping a
+ * `-32001` that poisons the stateful session (#715). The laid-out `bpmn` is generated lazily, only at the
+ * OPERATOR's preview/dispatch time (`previewProposalBpmn` / `dispatchDeliveryGraph`), which is a cockpit
+ * action, not an MCP call, and so is not timeout-bound.
  */
-export async function compileDeliveryGraph(
+export async function compileDeliveryGraphSemantic(
   graph: unknown,
-): Promise<CompileDeliveryGraphResult | CompileDeliveryGraphErrors> {
+): Promise<CompiledDeliveryGraphSemantic | CompileDeliveryGraphErrors> {
   const validationErrors: DeliveryGraphError[] = validateDeliveryGraph(graph);
   if (validationErrors.length > 0) {
     // Forward every semantic failure verbatim as a wire `{ path, message }` (the stable `code` stays
@@ -509,13 +533,40 @@ export async function compileDeliveryGraph(
   }
 
   const semanticBpmn = renderBpmn(typed, wirings, numberedFlows, startForkGateway, endJoinGateway, boundInputsByElement);
-  const bpmn = await layoutDeliveryDiagram(semanticBpmn);
   const diagram = renderMermaid(typed, wirings, resolvedEdges, elementById);
   const resolved = buildResolved(typed, wirings, resolvedEdges, producersById);
   const humanNodes = buildHumanNodes(nodes);
   const sideEffects = buildSideEffects(nodes);
 
-  return { ok: true, diagram, bpmn, resolved, humanNodes, sideEffects };
+  return { ok: true, diagram, semanticBpmn, resolved, humanNodes, sideEffects };
+}
+
+/**
+ * Validate + compile a delivery graph into a PURE preview INCLUDING diagram interchange (ADR 0005
+ * slice S1). Returns the generated `CompileDeliveryGraphResult` shape (`diagram`, laid-out `bpmn`,
+ * `resolved`, `humanNodes`, `sideEffects`) PLUS the pre-layout `semanticBpmn`, or `{ ok:false, errors }`
+ * for a malformed graph. NEVER deploys, dispatches, or mutates anything. Deterministic: identical input
+ * JSON yields byte-identical output.
+ *
+ * ASYNC because the final step attaches DIAGRAM INTERCHANGE (`bpmndi:BPMNDiagram`) via the toolkit
+ * autolayout (`layoutBpmn` — `bpmn-auto-layout`), the SAME pass every AUTHORED process gets from
+ * `npm run layout` (`scripts/layout-bpmn.ts`). This is the one BPMN in the system generated at
+ * runtime, so without this it was the only one shipping DI-less — unrenderable in the process
+ * explorer (#440). `layoutBpmn` is itself deterministic given identical semantic input, so
+ * "same JSON → byte-identical XML" still holds with the diagram included.
+ *
+ * Callers that only need the content digest / preview (the agent-facing compile+STAGE doors) should
+ * use the cheaper {@link compileDeliveryGraphSemantic} instead — layout here is CPU-bound and
+ * superlinear (issue #716), so it belongs only on the operator's preview/dispatch/deploy paths that
+ * genuinely render or run the BPMN.
+ */
+export async function compileDeliveryGraph(
+  graph: unknown,
+): Promise<CompiledDeliveryGraph | CompileDeliveryGraphErrors> {
+  const semantic = await compileDeliveryGraphSemantic(graph);
+  if (!semantic.ok) return semantic;
+  const bpmn = await layoutDeliveryDiagram(semantic.semanticBpmn);
+  return { ...semantic, bpmn };
 }
 
 /** Attach diagram interchange (`bpmndi:BPMNDiagram`) to the semantic-only compiled BPMN via the

package/app/deliveryGraphDispatch.ts

@@ -63,7 +63,7 @@ export async function dispatchDeliveryGraphRun(
     return { ok: false, errors: compiled.errors };
   }
 
-  const digest = deliveryGraphDigest(compiled.bpmn);
+  const digest = deliveryGraphDigest(compiled.semanticBpmn);
   const runKey = computeRunKey(options.runKey, digest);
   const sideEffecting = compiled.sideEffects.length > 0;
   const explicitTitle = typeof options.title === "string" && options.title.trim() !== "" ? options.title.trim() : "";

package/app/deliveryGraphProposals.ts

@@ -105,8 +105,12 @@ export function isProposalExpired(expiresAtIso: string | null | undefined, at: D
 
 /** Extract the operator-facing preview from a successful compile — the diagram, the side effects a
  * dispatch authorises, and the human stop-points. No BPMN, no digest handle beyond the content
- * address; a preview, not a dispatch affordance. */
-export function buildProposalPreview(compiled: CompileDeliveryGraphResult): DeliveryProposalPreview {
+ * address; a preview, not a dispatch affordance. Accepts either the full compile result or the
+ * layout-free {@link compileDeliveryGraphSemantic} result — the preview reads only `diagram`,
+ * `sideEffects`, and `humanNodes`, none of which need the laid-out `bpmn` (issue #716). */
+export function buildProposalPreview(
+  compiled: Pick<CompileDeliveryGraphResult, "diagram" | "humanNodes" | "sideEffects">,
+): DeliveryProposalPreview {
   return {
     diagram: compiled.diagram,
     sideEffects: compiled.sideEffects,

package/app/deliveryGraphStage.test.ts

@@ -0,0 +1,145 @@
+// Regression coverage for the compile+stage HOT PATH (issue #716, split from #715 gap 4).
+//
+// THE FAILURE MODE
+// ================
+// `compileDeliveryGraph` and `sequenceIssues` (the agent-facing MCP tools) both route through
+// `compileAndStageDeliveryGraph`, which USED to run the full compiler — including the CPU-bound
+// `layoutBpmn` (`bpmn-auto-layout`) diagram-interchange pass. That layout is superlinear in
+// node/edge count: on a large/dense graph (the issue cites up to 256 nodes / 1024 edges) it takes
+// MINUTES, so a cold MCP `tools/call` blew past the client's per-call timeout and returned
+// `-32001 Request timed out` — which (per #715) then poisoned the stateful MCP session.
+//
+// THE FIX
+// =======
+// Staging needs only the content DIGEST, the mermaid `diagram`, and the resolved model — NOT the
+// laid-out `bpmn`. The digest is now taken over the deterministic SEMANTIC BPMN (the DI is derived
+// from it), so `compileAndStageDeliveryGraph` uses the layout-free `compileDeliveryGraphSemantic`
+// and returns in milliseconds. The expensive `layoutBpmn` is deferred to the OPERATOR's
+// preview/dispatch (`previewProposalBpmn` / `dispatchDeliveryGraph`) — cockpit actions, not
+// timeout-bound MCP calls.
+//
+// These tests pin BOTH halves of the fix so it cannot regress:
+//   1. `compileDeliveryGraphSemantic` is layout-free (no `bpmn`, no `bpmndi:` in `semanticBpmn`) and
+//      content-addresses IDENTICALLY to the full compile — so staging and dispatch/preview agree.
+//   2. `compileAndStageDeliveryGraph` on a LARGE/DENSE graph completes fast (a bound the old
+//      layout-on-the-hot-path could never meet) and stages a live proposal whose `digest` is the
+//      SEMANTIC digest (not the laid-out one) — the structural signature of the fast path.
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { after, before, describe, test } from "node:test";
+import assert from "node:assert/strict";
+import { bootTestApp, type TestApp } from "@nanobpm/urban-testkit";
+import { compileDeliveryGraph, compileDeliveryGraphSemantic } from "./deliveryGraphCompiler.ts";
+import { getStagedProposal } from "./deliveryGraphProposals.ts";
+import { compileAndStageDeliveryGraph } from "./deliveryGraphStage.ts";
+import { deliveryGraphDigest } from "./deliveryRunner.ts";
+
+const APP_ROOT = resolve(import.meta.dirname, "..");
+
+/** A large, DENSE delivery graph — `n` agent nodes, each edged from its `fan` predecessors. At
+ * `n=256, fan=4` this is ~1020 edges: the exact class the issue names, and one `layoutBpmn` takes
+ * MINUTES on. The semantic compile of the same graph is ~40ms, so the fast path clears any sane
+ * timing bound by three orders of magnitude. */
+function denseGraph(n: number, fan: number): { name: string; nodes: unknown[]; edges: unknown[] } {
+  const nodes: unknown[] = [];
+  const edges: unknown[] = [];
+  for (let i = 0; i < n; i++) {
+    nodes.push({ id: `n${i}`, kind: "agent", agent: { jobType: "senior:feature", prompt: `task ${i}` } });
+  }
+  for (let i = 1; i < n; i++) {
+    for (let f = 1; f <= fan && i - f >= 0; f++) edges.push({ from: `n${i - f}`, to: `n${i}` });
+  }
+  return { name: "dense bench", nodes, edges };
+}
+
+describe("compileDeliveryGraphSemantic — the layout-free compile", () => {
+  test("produces a DI-less semantic BPMN and NO laid-out bpmn", async () => {
+    const g = denseGraph(8, 2);
+    const semantic = await compileDeliveryGraphSemantic(g);
+    assert(semantic.ok, "a well-formed graph compiles semantically");
+    assert(!("bpmn" in semantic), "the layout-free result carries no laid-out `bpmn`");
+    assert(
+      !semantic.semanticBpmn.includes("bpmndi:"),
+      "the semantic BPMN carries no diagram interchange (that is the layout the fast path skips)",
+    );
+    assert(semantic.semanticBpmn.includes("<bpmn:process"), "it is still a real BPMN process definition");
+  });
+
+  test("content-addresses IDENTICALLY to the full compile (staging and dispatch agree)", async () => {
+    const g = denseGraph(6, 2);
+    const semantic = await compileDeliveryGraphSemantic(g);
+    const full = await compileDeliveryGraph(g);
+    assert(semantic.ok && full.ok, "both compiles succeed");
+    // The full compile exposes the SAME semanticBpmn (it layers DI on top), and the digest is taken
+    // over that — so the fast (stage) path and the full (preview/dispatch) path never drift on how a
+    // graph is addressed.
+    assert.equal(full.semanticBpmn, semantic.semanticBpmn, "full compile reuses the semantic BPMN verbatim");
+    assert.equal(
+      deliveryGraphDigest(semantic.semanticBpmn),
+      deliveryGraphDigest(full.semanticBpmn),
+      "the content digest matches across the fast and full paths",
+    );
+    // Sanity: the laid-out bytes genuinely differ from the semantic bytes (DI was attached), so a
+    // digest taken over the laid-out `bpmn` would be a DIFFERENT value — the thing the fix moves away
+    // from.
+    assert.notEqual(full.bpmn, full.semanticBpmn, "the laid-out bpmn differs from the semantic bpmn");
+    assert.notEqual(
+      deliveryGraphDigest(full.bpmn),
+      deliveryGraphDigest(full.semanticBpmn),
+      "the semantic digest is distinct from the (old) laid-out digest",
+    );
+  });
+});
+
+describe("compileAndStageDeliveryGraph — the agent-facing hot path does not run layout", () => {
+  const dirs: string[] = [];
+  const apps: TestApp[] = [];
+  let app: TestApp;
+  before(async () => {
+    const d = mkdtempSync(join(tmpdir(), "nwf-stage-hotpath-"));
+    dirs.push(d);
+    app = await bootTestApp(APP_ROOT, {
+      env: { NANO_PR_GITHUB_TRANSPORT: "token", GITHUB_TOKEN: "", NANO_APP_DB_URL: `file:${join(d, "app.db")}` },
+    });
+    apps.push(app);
+  });
+  after(async () => {
+    for (const a of apps) await a.stop?.();
+    for (const dir of dirs) rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("stages a 256-node / ~1020-edge graph FAST and content-addresses it by its SEMANTIC digest", async () => {
+    const g = denseGraph(256, 4);
+    assert(g.edges.length > 1000, "the fixture really is dense (the layout-heavy class)");
+
+    const graphJson = JSON.stringify(g);
+    const started = performance.now();
+    const staged = await compileAndStageDeliveryGraph(app.db, g, graphJson, "http://example.test");
+    const elapsedMs = performance.now() - started;
+
+    assert(staged.ok, "the dense graph stages successfully");
+    assert.equal(staged.status, 200);
+    // The whole point of #716: the hot path must NOT run `layoutBpmn` (minutes on this graph). The
+    // layout-free semantic compile is ~40ms; a 20s bound is a 500x margin over the passing path and a
+    // 6x margin UNDER the failing (layout) path, so it separates them without flaking.
+    assert(
+      elapsedMs < 20_000,
+      `staging a dense graph must not pay the layout tax — took ${elapsedMs.toFixed(0)}ms (a layout would take minutes)`,
+    );
+
+    // The staged proposal is content-addressed by the SEMANTIC digest — the structural signature of
+    // the fast path. Before the fix it was the laid-out-bpmn digest (a different value), so this
+    // assertion is red on the old behaviour and green on the new one.
+    const semantic = await compileDeliveryGraphSemantic(g);
+    assert(semantic.ok);
+    const semanticDigest = deliveryGraphDigest(semantic.semanticBpmn);
+    assert.equal(staged.digest, semanticDigest, "staged proposal is addressed by its semantic digest");
+
+    // …and it is actually persisted as a live, dispatchable staged proposal (the operator can find it
+    // and drive the — deferred — layout at preview/dispatch time).
+    const live = await getStagedProposal(app.db, staged.digest);
+    assert(live, "the staged proposal is live in the store");
+    assert.equal(live.node_count, 256);
+  });
+});

package/app/deliveryGraphStage.ts

@@ -2,7 +2,7 @@
 // delivery graph (epic nano-workforce#605). Extracted from `operations/compileDeliveryGraph.ts` (S0)
 // so the intent-shaped generator doors (S4 — `sequenceIssues`) hand their CONSTRUCTED graph to the
 // EXACT same deterministic compile → validate → stage path the raw `compileDeliveryGraph` door uses:
-// one compiler (`compileDeliveryGraph`), one staging path (`stageProposal`), one idempotency/digest
+// one compiler (`compileDeliveryGraphSemantic`), one staging path (`stageProposal`), one idempotency/digest
 // semantics (content-addressed by `deliveryGraphDigest`). Per AGENTS.md "Derivation over duplication:
 // no drift surfaces", a generator MUST NOT re-implement a second runner or a second staging path —
 // it only produces the `DeliveryGraph` and delegates here.
@@ -14,7 +14,7 @@
 // semantic validation. Nothing is staged on a rejected compile.
 import type { DataLayer } from "@nanobpm/urban";
 import type { CompileDeliveryGraphErrors, CompileDeliveryGraphStaged } from "../nano-generated/api-io.d.ts";
-import { compileDeliveryGraph } from "./deliveryGraphCompiler.ts";
+import { compileDeliveryGraphSemantic } from "./deliveryGraphCompiler.ts";
 import {
   buildProposalPreview,
   buildProposalRow,
@@ -64,12 +64,12 @@ export async function compileAndStageDeliveryGraph(
   graphJson: string,
   origin: string,
 ): Promise<StagedResult | StageErrors> {
-  const result = await compileDeliveryGraph(graph);
+  const result = await compileDeliveryGraphSemantic(graph);
   if (!result.ok) {
     return { ok: false, status: 400, body: result };
   }
 
-  const digest = deliveryGraphDigest(result.bpmn);
+  const digest = deliveryGraphDigest(result.semanticBpmn);
   const name =
     typeof result.resolved.name === "string" && result.resolved.name.trim() !== ""
       ? result.resolved.name.trim()

package/app/deliveryGraphTextIngress.ts

@@ -127,7 +127,7 @@ export async function parseAndCompileText(
       },
     };
   }
-  const digest = deliveryGraphDigest(compiled.bpmn);
+  const digest = deliveryGraphDigest(compiled.semanticBpmn);
   const name =
     typeof compiled.resolved.name === "string" && compiled.resolved.name.trim() !== ""
       ? compiled.resolved.name.trim()

package/app/deliveryRunner.ts

@@ -6,7 +6,8 @@
 // runs it); its whole job is deploy + seed + start.
 //
 // Definition lifecycle (the ADR open question, resolved here): the deployed process id is
-// CONTENT-ADDRESSED — `delivery-graph-<sha256(bpmn)[:12]>`. Identical graphs compile byte-identically
+// CONTENT-ADDRESSED — `delivery-graph-<sha256(semanticBpmn)[:12]>` (the pre-layout semantic model, NOT
+// the laid-out `bpmn` — issue #716). Identical graphs compile byte-identically
 // (S1 determinism) → identical id → an idempotent redeploy (the engine versions the same id, never a
 // duplicate definition per run); different graphs get different ids and never collide; and because the
 // id ENCODES its content, a stale one-shot definition is GC-identifiable by a later sweeper (out of
@@ -22,13 +23,21 @@ import { DEFAULT_EVERY_MS, msToIsoDuration, parseProbe, readinessPollEvery, read
 import { repoEnvelopeVars } from "./repoEnvelope.ts";
 import { isoDuration } from "./reviewWait.ts";
 
-/** The content digest of a compiled graph — `sha256(bpmn)[:12]` — the single source of truth for the
- * content-addressed deploy id (`delivery-graph-<digest>`) AND the dispatch fence's default idempotency
- * key + the staged-proposal primary key. The runner (deploy id), `app/deliveryGraphDispatch` (dedupe
- * key), and `app/deliveryGraphProposals` (proposal digest) all derive from THIS one function so they
- * can never drift on how a graph is addressed. */
-export function deliveryGraphDigest(bpmn: string): string {
-  return createHash("sha256").update(bpmn).digest("hex").slice(0, 12);
+/** The content digest of a compiled graph — `sha256(semanticBpmn)[:12]` — the single source of truth
+ * for the content-addressed deploy id (`delivery-graph-<digest>`) AND the dispatch fence's default
+ * idempotency key + the staged-proposal primary key. The runner (deploy id),
+ * `app/deliveryGraphDispatch` (dedupe key), and `app/deliveryGraphProposals` (proposal digest) all
+ * derive from THIS one function so they can never drift on how a graph is addressed.
+ *
+ * The digest is taken over the graph's SEMANTIC BPMN (the pre-layout `compileDeliveryGraphSemantic`
+ * output), NOT the laid-out `bpmn` (issue #716). The diagram interchange is DERIVED deterministically
+ * from the semantic model, so the semantic BPMN is the true canonical content of a graph — and, unlike
+ * the laid-out BPMN, it is available WITHOUT the CPU-bound `layoutBpmn` pass. This lets the agent-facing
+ * compile+stage doors content-address (and stage) a graph on the fast path while the expensive layout is
+ * deferred to the operator's preview/dispatch. Every caller MUST pass a `semanticBpmn` so the address
+ * stays consistent across staging, preview, dispatch, and deploy. */
+export function deliveryGraphDigest(semanticBpmn: string): string {
+  return createHash("sha256").update(semanticBpmn).digest("hex").slice(0, 12);
 }
 
 /** The bounded-timeout / SLA envelope every node inherits (Decision: bounded → escalate). ISO-8601
@@ -120,7 +129,7 @@ export async function prepareDeliveryGraph(
   const compiled = await compileDeliveryGraph(graph);
   if (!compiled.ok) return { ok: false, errors: compiled.errors };
 
-  const digest = deliveryGraphDigest(compiled.bpmn);
+  const digest = deliveryGraphDigest(compiled.semanticBpmn);
   const processDefinitionId = `${DELIVERY_GRAPH_PROCESS_ID}-${digest}`;
   const bpmn = rewriteProcessId(compiled.bpmn, processDefinitionId);
 

package/docs/mcp-runbook.md

@@ -290,6 +290,21 @@ got string`. That retired the nwf-local stringified-body reject mitigation: the
 `e2e/mcp-surface.e2e.ts` now asserts the door faithfully parses a stringified body (the
 `assertObjectBodyAccepted` detector's teeth stay pinned synthetically).
 
+**Heavy compile/stage tools stay under the client timeout (issue #716).** Compiling a large
+delivery graph to laid-out BPMN (`layoutBpmn` / `bpmn-auto-layout`) is CPU-bound and superlinear —
+minutes on a 256-node / 1024-edge graph — so running it inline once tripped a cold
+`sequenceIssues` / `compileDeliveryGraph` call past the client's per-call MCP timeout (`-32001
+Request timed out`, which then poisoned the stateful session, #715). The compile+STAGE hot path
+(`compileAndStageDeliveryGraph`) therefore runs the **layout-free** `compileDeliveryGraphSemantic`:
+staging needs only the content **digest**, the mermaid `diagram`, and the resolved model, so it
+returns in milliseconds. The digest is taken over the deterministic **semantic** BPMN (the diagram
+interchange is derived from it, so it is the canonical content of a graph) — one content address
+shared across staging, `previewProposalBpmn`, `dispatchDeliveryGraph`, and the deploy id, so they
+never drift. The expensive `layoutBpmn` is deferred to the **operator's** preview/dispatch
+(`previewProposalBpmn` recompiles the laid-out BPMN with DI on demand) — a cockpit action, not a
+timeout-bound MCP call. `app/deliveryGraphStage.test.ts` and `e2e/heavy-tool-progress.e2e.ts` pin
+that a large/dense graph stages fast rather than timing out.
+
 ## 5. Fallback
 
 Agents without MCP are unchanged — resolve the instance, then

package/e2e/heavy-tool-progress.e2e.ts

@@ -0,0 +1,86 @@
+// Heavy-tool timeout regression over the REAL runtime-served `/app/mcp` surface (issue #716, split
+// from #715 gap 4).
+//
+// The agent-facing `compileDeliveryGraph` tool used to run the CPU-bound `layoutBpmn` pass inline, so
+// a cold call on a large/dense graph (the issue cites up to 256 nodes / 1024 edges) blew past the
+// client's per-call MCP timeout and returned `-32001 Request timed out` — poisoning the session (#715).
+// The fix stages on a layout-free fast path (the digest is taken over the deterministic semantic BPMN;
+// the expensive layout is deferred to the operator's preview/dispatch).
+//
+// This drives the exact client handshake an agent uses (via the S1 harness) and asserts a large graph
+// gets an IMMEDIATE accepted `status:"ready"` staged response — not a timeout — and that the staged
+// digest is immediately visible over the same surface. It does NOT re-implement the transport (see the
+// harness header's EXTENSION SEAM).
+//
+// Run with `npm run e2e`.
+import assert from "node:assert/strict";
+import { after, before, describe, test } from "node:test";
+import { assertObjectBodyAccepted, bootMcpHarness, type McpHarness } from "./support/mcp-harness.ts";
+
+const TOOL = "compileDeliveryGraph";
+
+/** A large, DENSE delivery graph — `n` agent nodes, each edged from its `fan` predecessors. At
+ * `n=256, fan=4` that is ~1020 edges: the exact class the issue names, and one `layoutBpmn` takes
+ * MINUTES on. The layout-free stage path compiles it in tens of milliseconds. */
+function denseGraph(n: number, fan: number): { name: string; nodes: unknown[]; edges: unknown[] } {
+  const nodes: unknown[] = [];
+  const edges: unknown[] = [];
+  for (let i = 0; i < n; i++) {
+    nodes.push({ id: `n${i}`, kind: "agent", agent: { jobType: "senior:feature", prompt: `task ${i}` } });
+  }
+  for (let i = 1; i < n; i++) {
+    for (let f = 1; f <= fan && i - f >= 0; f++) edges.push({ from: `n${i - f}`, to: `n${i}` });
+  }
+  return { name: "dense mcp bench", nodes, edges };
+}
+
+interface ListBody {
+  count: number;
+  proposals: Array<{ digest: string; title: string | null }>;
+}
+
+describe("#716 — a heavy compile/stage tool returns an accepted response (not a timeout) over MCP", () => {
+  let h: McpHarness;
+  before(async () => {
+    h = await bootMcpHarness();
+  });
+  after(async () => {
+    await h.stop();
+  });
+
+  test("a cold, large/dense compileDeliveryGraph call stages FAST rather than timing out", async () => {
+    const graph = denseGraph(256, 4);
+    assert.ok(graph.edges.length > 1000, "the fixture really is dense (the layout-heavy class)");
+
+    const started = performance.now();
+    const res = await h.callTool(TOOL, { body: graph });
+    const elapsedMs = performance.now() - started;
+
+    // The object body arrived as an object (S0 invariant) and the call SUCCEEDED (a real client would
+    // have timed out with -32001 on the old layout-inline path).
+    assertObjectBodyAccepted(res, TOOL);
+    assert.ok(!res.isError, `${TOOL} on a large graph must stage, not error/time out: ${res.text}`);
+
+    const json = res.json as { status?: string; digest?: string; reviewUrl?: string } | undefined;
+    assert.equal(json?.status, "ready", `${TOOL} must return an accepted staged response: ${res.text}`);
+    assert.ok(typeof json?.digest === "string" && json.digest.length > 0, "the staged response carries a digest");
+
+    // The whole point of #716: the tool must not pay the layout tax (minutes on this graph). The
+    // layout-free path is tens of ms; a 20s bound is a huge margin over the passing path and well under
+    // the failing (layout) path, so it separates them without flaking.
+    assert.ok(
+      elapsedMs < 20_000,
+      `a heavy tool must return promptly — took ${elapsedMs.toFixed(0)}ms (an inline layout would take minutes)`,
+    );
+
+    // The staged proposal is immediately observable over the SAME surface — the operator can find it
+    // and drive the (deferred) layout at preview/dispatch time.
+    const list = await h.callTool("listStagedProposals", {});
+    assert.ok(!list.isError, `listStagedProposals must not error: ${list.text}`);
+    const listed = list.json as ListBody | undefined;
+    assert.ok(
+      listed?.proposals?.some((p) => p.digest === json?.digest),
+      `the staged digest ${json?.digest} must be listed: ${list.text}`,
+    );
+  });
+});

package/operations/previewProposalBpmn.ts

@@ -81,7 +81,7 @@ export default defineOperation("previewProposalBpmn", async ({ body }, app) => {
   // Determinism guard: the recompiled BPMN must content-address back to the requested digest. A mismatch
   // means the stored graph drifted from its digest — refuse rather than serve a diagram that doesn't
   // match the proposal the operator is about to dispatch.
-  const recompiledDigest = deliveryGraphDigest(compiled.bpmn);
+  const recompiledDigest = deliveryGraphDigest(compiled.semanticBpmn);
   if (recompiledDigest !== digest) {
     app.log.error("preview-proposal-bpmn: digest drift", { digest, recompiledDigest });
     return {

package/package.json

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