@nanobpm/nano-workforce 0.177.0 → 0.178.1

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [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
+
+* **mcp:** pin the workforce-visible MCP surface — session self-heal, tractable-surface budget, heavy-tool latency ([#717](https://github.com/nanobpm/nano-workforce/issues/717)) ([de55daa](https://github.com/nanobpm/nano-workforce/commit/de55daa1b5fa134c7fc0e08c96041113fecd1481)), closes [488/#501](https://github.com/488/nano-workforce/issues/501) [#715](https://github.com/nanobpm/nano-workforce/issues/715)
+
 ## [0.177.0](https://github.com/nanobpm/nano-workforce/compare/v0.176.1...v0.177.0) (2026-09-02)
 
 ### 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/app/mcpToolSurface.test.ts

@@ -0,0 +1,63 @@
+// Authoring guard for the curated MCP tool subset (`app/mcpToolSurface.ts`, issue #715).
+//
+// The curated `CURATED_MCP_TOOLS` allowlist is the tractable subset a client imports instead of
+// `["*"]`. `e2e/mcp-tractability.e2e.ts` proves every entry projects onto the LIVE surface, but that
+// needs a booted instance. This fast unit guard checks the same list against the SAME framework
+// walker the runtime MCP projector uses (`parseSpec` + `collectOperations`) so an authoring typo —
+// a curated app-tool name that is not an `openapi.yaml` operationId, or one accidentally `x-mcp`-
+// excluded — fails CI in `npm test` without booting anything. Framework `urban_debug_*` tools are
+// not `openapi.yaml` operations, so they are validated by their reserved prefix instead.
+//
+// Derivation over duplication (AGENTS.md): the exclusion/projection rule is NOT re-implemented here —
+// it is read from the framework walker's `mcpExcluded` flag, the exact rule the runtime honours.
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { test } from "node:test";
+import { collectOperations, parseSpec } from "@nanobpm/urban/toolkit";
+import { CURATED_MCP_TOOLS, FRAMEWORK_TOOL_PREFIX } from "../app/mcpToolSurface.ts";
+import { assert } from "#test-assert";
+
+const REPO_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+const SPEC_PATH = join(REPO_ROOT, "openapi.yaml");
+
+function projectedAppTools(): Set<string> {
+  return new Set(
+    collectOperations(parseSpec(readFileSync(SPEC_PATH, "utf8")))
+      .filter((op) => !op.mcpExcluded)
+      .map((op) => op.operationId),
+  );
+}
+
+test("every curated APP tool is a projected (non-x-mcp) openapi operation", () => {
+  const projected = projectedAppTools();
+  for (const name of CURATED_MCP_TOOLS) {
+    if (name.startsWith(FRAMEWORK_TOOL_PREFIX)) continue; // framework tool — validated by prefix below
+    assert(
+      projected.has(name),
+      `curated tool "${name}" is not a projected openapi operation — it is missing from openapi.yaml ` +
+        `or has been x-mcp-excluded. A client importing the curated allowlist would silently not get it.`,
+    );
+  }
+});
+
+test("every curated FRAMEWORK tool carries the reserved urban_debug_ prefix", () => {
+  const projected = projectedAppTools();
+  for (const name of CURATED_MCP_TOOLS) {
+    if (!name.startsWith(FRAMEWORK_TOOL_PREFIX)) continue;
+    // A framework name must NOT also be an app operationId (that would be a namespace collision the
+    // runtime reserves against) — it is owned entirely by the runtime's engine-debug family.
+    assert(
+      !projected.has(name),
+      `curated framework tool "${name}" unexpectedly collides with an openapi operationId.`,
+    );
+  }
+});
+
+test("the curated subset has no duplicate entries", () => {
+  const seen = new Set<string>();
+  for (const name of CURATED_MCP_TOOLS) {
+    assert(!seen.has(name), `CURATED_MCP_TOOLS lists "${name}" more than once.`);
+    seen.add(name);
+  }
+});

package/app/mcpToolSurface.ts

@@ -0,0 +1,112 @@
+// Canonical source of truth for the workforce MCP tool SURFACE budget and the curated driving
+// subset (issue #715, epic #605 "tractable surface").
+//
+// WHY THIS EXISTS
+// ===============
+// The runtime-served MCP surface (`/app/mcp`, ADR 0067) projects EVERY non-`x-mcp` `openapi.yaml`
+// operation — plus the framework-owned `urban_debug_*` engine tools — into a tool. Measured against
+// the deployed surface (issue #715) that is **56 tools / ~79 KB of `tools/list`**: large enough that
+// an agent harness (Copilot CLI and others) DEFERS the whole set behind a tool-search gate, and a
+// client config of `"tools": ["*"]` imports all 56 eagerly. That is the #605 "tractable surface"
+// problem, quantified.
+//
+// The workforce-side lever is TWO-fold, and both live here as one source of truth:
+//
+//   1. A **budget** on the full projected surface (count + bytes), so the surface can only ever
+//      SHRINK below these ceilings — a new door that pushes it over fails CI (`e2e/mcp-tractability.e2e.ts`).
+//      The transport-level count reduction (gating rarely-used framework `urban_debug_*` tools
+//      behind a mode) lives in the urban runtime and is tracked upstream (nano-ide#488); this budget
+//      pins the workforce-visible number so it cannot regress while that lands.
+//   2. A **curated subset** — the tools an agent actually drives/reads with day to day — that a
+//      client imports via its MCP-server `"tools"` allowlist INSTEAD of `["*"]`, so the eagerly-loaded
+//      set is materially smaller than the full surface and stays under the harness deferral threshold.
+//      This is the "documented curated subset" the issue's acceptance allows.
+//
+// DERIVATION OVER DUPLICATION (AGENTS.md)
+// =======================================
+// This list is the ONE authored source. `e2e/mcp-tractability.e2e.ts` asserts every name here
+// actually projects onto the LIVE `/app/mcp` surface (so a curated entry can never go dead), and
+// `scripts/sync-mcp-curated.ts` renders it verbatim into the runbook (`docs/mcp-runbook.md`) — a
+// drift test under `npm test` (`scripts/sync-mcp-curated.test.ts`, which CI runs) and
+// `npm run sync:mcp-curated:check` both fail on any drift. The served "Connect over MCP" page
+// (`pages/mcp.page.json`) carries the concept as prose and points here + at the runbook, so there is
+// no second enumerated copy to drift. Never hand-edit the curated `tools` block in the runbook; edit
+// HERE and re-run `npm run sync:mcp-curated`.
+
+/**
+ * The curated driving/reading subset an MCP client should import via its server entry's `"tools"`
+ * allowlist instead of `["*"]`. Grouped by intent in authoring order; the union is what a workforce
+ * operator/agent needs to drive work, read status, answer escalations, and triage a wedged instance —
+ * WITHOUT eagerly loading the whole 56-tool surface. Every name is asserted to project onto the live
+ * surface by `e2e/mcp-tractability.e2e.ts`.
+ */
+export const CURATED_MCP_TOOLS: readonly string[] = [
+  // ── Drive / act ──────────────────────────────────────────────────────────
+  "startConvergenceLoop",
+  "startPlanFanout",
+  "startEpicSet",
+  "startFeature",
+  "compileDeliveryGraph",
+  "previewDeliveryGraph",
+  "sequenceIssues",
+  "agentCompleteEscalation",
+  "completeUserTask",
+  "cancelInstance",
+  "appendBlackboard",
+  "readBlackboard",
+  // ── Read / orient ────────────────────────────────────────────────────────
+  "getVersion",
+  "getAgentInstructions",
+  "getAgentGuide",
+  "listActivePrs",
+  "listStagedProposals",
+  "listEscalations",
+  "getLineage",
+  "getPrHistory",
+  // ── Engine-truth reads (wedge triage) ────────────────────────────────────
+  "urban_debug_search_process_instances",
+  "urban_debug_search_element_instance_wait_states",
+  "urban_debug_search_incidents",
+  "urban_debug_search_variables",
+  "urban_debug_search_jobs",
+  "urban_debug_instance_state",
+  "urban_debug_open_user_tasks",
+];
+
+/** The framework-reserved namespace for engine-debug tools (mirrors the runtime's `DEBUG_PREFIX`).
+ *  A curated entry with this prefix is a framework tool (not an `openapi.yaml` operation), so the
+ *  spec-level unit guard validates it by prefix rather than against the projected operation set. */
+export const FRAMEWORK_TOOL_PREFIX = "urban_debug_";
+
+/**
+ * Hard CEILING on the projected `tools/list` tool count. The deployed surface measures 56 (issue
+ * #715); this budget forbids GROWTH — a new door that pushes the count over fails CI. It is a
+ * regression guard, not the reduction itself: the reduction an agent actually experiences comes from
+ * importing {@link CURATED_MCP_TOOLS} rather than `["*"]`, and the transport-level shrink of the
+ * framework tool family is tracked upstream (nano-ide#488).
+ */
+export const MCP_TOOL_COUNT_BUDGET = 60;
+
+/**
+ * Hard CEILING on the serialized byte size of the full `tools/list` payload (the schema bytes a
+ * client must parse). The deployed surface measures ~78,962 bytes (issue #715); this ceiling forbids
+ * meaningful growth so a fat new schema cannot silently re-inflate the surface past the harness
+ * deferral point.
+ */
+export const MCP_SURFACE_BYTES_BUDGET = 84_000;
+
+/**
+ * The eagerly-loaded curated subset MUST stay materially smaller than the full surface — otherwise it
+ * is not "tractable". This ceiling pins the curated set at roughly half the full count so a creeping
+ * curation cannot quietly grow back toward `["*"]`.
+ */
+export const CURATED_MCP_TOOLS_BUDGET = 30;
+
+/**
+ * The per-call budget (ms) a heavy tool (synchronous BPMN layout — `compileDeliveryGraph` /
+ * `previewDeliveryGraph` / `sequenceIssues`) must complete within so a cold call does not exceed a
+ * typical MCP client's request timeout and `-32001` (issue #715 gap 4). Measured cold at ~0.5 s in
+ * the hermetic harness; the 4 s ceiling leaves generous headroom while still failing loudly if a
+ * heavy door regresses into a multi-second stall.
+ */
+export const HEAVY_TOOL_BUDGET_MS = 4_000;