@nanobpm/nano-workforce 0.177.0 → 0.178.1

package/docs/mcp-runbook.md

@@ -69,6 +69,82 @@ copilot mcp add --transport http workforce-merlin http://merlin.local:3000/app/m
 Tool calls are namespaced per server entry, so the instance you name is the instance
 you drive.
 
+### Import a curated subset, not `["*"]` (tractable surface — issue #715)
+
+The full projected surface is **~56 tools / ~79 KB** of `tools/list` (app operations + the
+framework `urban_debug_*` engine family). That is large enough that a coding-agent harness
+**defers the whole set behind a tool-search gate**, and `"tools": ["*"]` imports every one of
+them eagerly — so an agent may not see nwf's tools until it searches. Until the runtime shrinks
+the framework tool family behind a mode (tracked upstream, nano-ide#488), the workforce-side lever
+is to import a **curated allowlist** of the tools you actually drive/read with, instead of `["*"]`:
+
+```json
+"workforce-local": {
+  "type": "http",
+  "url": "http://localhost:3000/app/mcp",
+  "tools": <curated list below>
+}
+```
+
+The curated list is the single source of truth in **`app/mcpToolSurface.ts`**
+(`CURATED_MCP_TOOLS`) — `e2e/mcp-tractability.e2e.ts` asserts every entry projects onto the live
+surface, and `npm run sync:mcp-curated:check` (also asserted by a drift test under `npm test`, which
+CI runs) fails if the block below drifts from the source. Never hand-edit it; edit
+`app/mcpToolSurface.ts` and run `npm run sync:mcp-curated`.
+
+<!-- BEGIN GENERATED: curated-tools (npm run sync:mcp-curated) -->
+```json
+[
+  "startConvergenceLoop",
+  "startPlanFanout",
+  "startEpicSet",
+  "startFeature",
+  "compileDeliveryGraph",
+  "previewDeliveryGraph",
+  "sequenceIssues",
+  "agentCompleteEscalation",
+  "completeUserTask",
+  "cancelInstance",
+  "appendBlackboard",
+  "readBlackboard",
+  "getVersion",
+  "getAgentInstructions",
+  "getAgentGuide",
+  "listActivePrs",
+  "listStagedProposals",
+  "listEscalations",
+  "getLineage",
+  "getPrHistory",
+  "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"
+]
+```
+<!-- END GENERATED: curated-tools -->
+
+Keeping `["*"]` still works and is fine on a client that does not defer — the curated import is the
+recommended default for a harness that gates on tool count. The full surface (including any
+`urban_debug_*` tool not in the curated set) stays reachable; drop back to `["*"]`, or add the
+specific extra tool name to the entry, whenever you need one outside the curated set.
+
+### Recover a lost session — re-`initialize` on `-32000` (issue #715, gap 1)
+
+The `/app/mcp` transport is **stateful streamable-HTTP**: every `tools/call` carries an
+`mcp-session-id`, and a call with a missing / stale / idle-dropped / proxy-reset / LRU-evicted
+session id is refused with `-32000 "Bad Request: no valid session id, and not an initialize
+request."` A client that does not re-handshake then sees the **whole surface** report "tool does not
+exist" until it re-`initialize`s — a single hiccup (notably a heavy-tool timeout, gap 4 below) can
+brick every tool. The **self-heal** is a fresh `initialize` handshake, which mints a new session and
+restores the entire catalogue in one round trip; a well-behaved MCP client does this automatically on
+a `-32000`. The stateless/resumable transport that would remove the session dependency entirely is
+tracked upstream (nano-ide#488); `e2e/mcp-session-selfheal.e2e.ts` pins the workforce-visible
+requirement — a killed session (stale id **and** a server-side `DELETE`) bricks a call `-32000`, and
+one re-`initialize` brings the full surface back.
+
 ### Instance behind Basic Auth? You need *both* headers
 
 Two different layers. `x-hook-secret` is the **app's own** guard (checked by nwf in
@@ -214,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/e2e/mcp-session-selfheal.e2e.ts

@@ -0,0 +1,113 @@
+// Session self-heal regression — the dominant #715 gap (gap 1).
+//
+// WHAT THIS PINS
+// ==============
+// The runtime-served MCP surface (`/app/mcp`, ADR 0067) is a **stateful streamable-HTTP** transport:
+// every `tools/call` MUST carry a valid `mcp-session-id`, and a call with a missing / stale / evicted
+// / deleted session id is refused with JSON-RPC `-32000 "Bad Request: no valid session id, and not an
+// initialize request."` (mcp.ts). In the field (issue #715) a single hiccup — a heavy-tool timeout,
+// an idle drop, a proxy reset, or LRU eviction (`MAX_SESSIONS`) — loses the session and then bricks
+// the ENTIRE surface for a client that does not re-`initialize`: every subsequent tool reads as
+// "tool does not exist". The stateless/resumable transport that would remove the session dependency
+// lives in the urban runtime and is tracked upstream (nano-ide#488); until it lands, the
+// **workforce-visible requirement** (this issue) is that the surface is RECOVERABLE — a client that
+// re-`initialize`s after a `-32000` gets the WHOLE surface back in one round trip, not a degraded one.
+//
+// This is the acceptance regression: "kill the session mid-flight and assert the next call still
+// works." It kills the session two faithful ways — an unknown/stale id, and a server-side `DELETE`
+// (the spec session-termination verb) of a live id — asserts each bricks a call with the exact
+// `-32000` signature, then asserts a single client `reinitialize()` fully restores the surface
+// (a working `tools/call` AND the complete `tools/list`). If a future runtime makes the transport
+// stateless/resumable (nano-ide#488), the stale-id call simply stops erroring — this test then
+// tightens to that stronger contract with a one-line change, never silently passing on a regression.
+//
+// Run with `npm run e2e`.
+import assert from "node:assert/strict";
+import { randomUUID } from "node:crypto";
+import { after, before, describe, test } from "node:test";
+import { bootMcpHarness, type McpHarness } from "./support/mcp-harness.ts";
+
+/** The exact runtime signature of a lost/absent session (mcp.ts). A recovered surface must NOT
+ *  answer with this after a re-`initialize`. */
+const NO_SESSION_SIGNATURE = "no valid session id";
+
+/** Any "the session is gone" refusal: the runtime's own `-32000` "no valid session id" (unknown id)
+ *  OR the SDK transport's "Session not found" (a terminated/DELETEd id). Either proves the call was
+ *  refused because the session no longer exists — the field failure #715 gap 1 is about. */
+const SESSION_GONE = /no valid session id|session not found/i;
+
+/** A safe, side-effect-free read used as the "does the surface answer?" probe. */
+const PROBE_TOOL = "getVersion";
+
+describe("#715 gap 1 — a lost MCP session self-heals on client re-initialize", () => {
+  let h: McpHarness;
+  before(async () => {
+    h = await bootMcpHarness();
+  });
+  after(async () => {
+    await h.stop();
+  });
+
+  test("baseline: a call on the live session works", async () => {
+    const res = await h.callTool(PROBE_TOOL);
+    assert(!res.isError, `baseline ${PROBE_TOOL} should succeed on a live session: ${res.text}`);
+  });
+
+  test("an unknown/stale session id bricks a call with -32000, and re-initialize restores the surface", async () => {
+    // A stale id models an evicted (LRU / idle-dropped) or proxy-reset session the client still holds.
+    const staleId = `stale-${randomUUID()}`;
+    const bricked = await h.callToolAs(staleId, PROBE_TOOL);
+    assert(bricked.isError, "a call carrying a stale session id must be refused, not answered");
+    assert(
+      bricked.text.includes(NO_SESSION_SIGNATURE),
+      `a stale-session call must fail with the "${NO_SESSION_SIGNATURE}" signature, got: ${bricked.text}`,
+    );
+
+    // Client self-heal: re-run the handshake. The pinned runtime is stateful, so this is how a real
+    // client recovers (nano-ide#488 would make it unnecessary).
+    const newId = await h.reinitialize();
+    assert(newId && newId !== staleId, "reinitialize must mint a fresh session id");
+
+    // The NEXT call works — the whole surface is back, not a degraded subset.
+    const healed = await h.callTool(PROBE_TOOL);
+    assert(!healed.isError, `after reinitialize the surface must answer again: ${healed.text}`);
+    assert(
+      !healed.text.includes(NO_SESSION_SIGNATURE),
+      "a healed call must not still report a missing session",
+    );
+
+    // And the FULL projected catalogue is restored — the field failure was "every tool vanished".
+    const tools = await h.listTools();
+    assert(tools.length > 1, `the full tools/list must be restored after self-heal, got ${tools.length}`);
+    assert(
+      tools.some((t) => t.name === PROBE_TOOL),
+      `the restored catalogue must still project ${PROBE_TOOL}`,
+    );
+  });
+
+  test("a server-side DELETE ends the session mid-flight; the old id then bricks and re-initialize heals it", async () => {
+    // Prove the harness's current session is live first.
+    const before = await h.callTool(PROBE_TOOL);
+    assert(!before.isError, `session should be live before DELETE: ${before.text}`);
+    const killedId = h.sessionId;
+
+    // Kill it the spec way — DELETE terminates the session server-side (mcp.ts: "POST, DELETE").
+    const status = await h.deleteSession(killedId);
+    assert(status < 500, `DELETE session should not server-error, got ${status}`);
+
+    // The now-terminated id bricks a call — the mid-flight hiccup. A terminated session surfaces the
+    // SDK transport's "Session not found"; an unknown id surfaces the runtime's "no valid session id"
+    // — both mean the session is gone and the call was refused, not answered.
+    const bricked = await h.callToolAs(killedId, PROBE_TOOL);
+    assert(bricked.isError, "a call on a DELETEd session id must be refused");
+    assert(
+      SESSION_GONE.test(bricked.text),
+      `a DELETEd-session call must be refused as a gone session, got: ${bricked.text}`,
+    );
+
+    // Client re-initialize → the very next call works again.
+    await h.reinitialize();
+    const healed = await h.callTool(PROBE_TOOL);
+    assert(!healed.isError, `after reinitialize the surface must answer again: ${healed.text}`);
+  });
+});

package/e2e/mcp-tractability.e2e.ts

@@ -0,0 +1,114 @@
+// Tractable-surface + heavy-tool budget guards (#715 gaps 2 & 4).
+//
+// WHAT THIS PINS
+// ==============
+// Gap 2 — the projected `/app/mcp` `tools/list` surface measures 56 tools / ~79 KB against the
+// deployed instance (issue #715): large enough that an agent harness DEFERS the whole set behind a
+// tool-search gate, and a client `"tools": ["*"]` imports all of it eagerly. Two workforce-visible
+// guards keep it tractable, both derived from the ONE source of truth (`app/mcpToolSurface.ts`):
+//
+//   • a BUDGET on the full surface (count + serialized bytes) so it can only shrink below the pinned
+//     ceilings — a fat new door that re-inflates it fails the build here;
+//   • a CURATED subset (`CURATED_MCP_TOOLS`) a client imports instead of `["*"]` — asserted to be
+//     materially smaller than the full surface AND to consist only of names that actually project,
+//     so the recommended allowlist can never point at a dead/renamed tool.
+//
+// Gap 4 — a cold heavy tool (synchronous BPMN layout: `previewDeliveryGraph` / `compileDeliveryGraph`)
+// must complete well within a typical MCP client's per-call timeout, so a cold `tools/call` no longer
+// `-32001`s (which then trips gap 1 by poisoning the session). Asserted against `HEAVY_TOOL_BUDGET_MS`.
+//
+// The full object-body / schema-self-containment contract (gap 3, nano-ide#501/#503) is pinned by the
+// sibling `e2e/mcp-surface.e2e.ts`; this file adds only the tractability + latency dimensions.
+//
+// Run with `npm run e2e`.
+import assert from "node:assert/strict";
+import { after, before, describe, test } from "node:test";
+import {
+  CURATED_MCP_TOOLS,
+  CURATED_MCP_TOOLS_BUDGET,
+  HEAVY_TOOL_BUDGET_MS,
+  MCP_SURFACE_BYTES_BUDGET,
+  MCP_TOOL_COUNT_BUDGET,
+} from "../app/mcpToolSurface.ts";
+import { bootMcpHarness, type McpHarness, type McpTool } from "./support/mcp-harness.ts";
+
+describe("#715 gaps 2 & 4 — tractable MCP surface + heavy-tool latency budget", () => {
+  let h: McpHarness;
+  let tools: McpTool[];
+  before(async () => {
+    h = await bootMcpHarness();
+    tools = await h.listTools();
+  });
+  after(async () => {
+    await h.stop();
+  });
+
+  test("the full tools/list stays within the pinned count budget", () => {
+    assert(
+      tools.length <= MCP_TOOL_COUNT_BUDGET,
+      `projected MCP tool count ${tools.length} exceeds the budget ${MCP_TOOL_COUNT_BUDGET} — the ` +
+        `surface must not grow past the harness deferral point (issue #715). Either curate a door off ` +
+        `the surface (x-mcp) or, if this growth is intended, raise MCP_TOOL_COUNT_BUDGET deliberately ` +
+        `in app/mcpToolSurface.ts. Tools: ${tools.map((t) => t.name).sort().join(", ")}`,
+    );
+  });
+
+  test("the full tools/list stays within the pinned byte budget", () => {
+    const bytes = Buffer.byteLength(JSON.stringify(tools), "utf8");
+    assert(
+      bytes <= MCP_SURFACE_BYTES_BUDGET,
+      `serialized tools/list is ${bytes} bytes, over the budget ${MCP_SURFACE_BYTES_BUDGET} — a fat ` +
+        `new schema is re-inflating the surface (issue #715). Trim the schema, curate the door off, or ` +
+        `raise MCP_SURFACE_BYTES_BUDGET deliberately in app/mcpToolSurface.ts.`,
+    );
+  });
+
+  test("every curated tool actually projects onto the live surface (no dead allowlist entries)", () => {
+    const live = new Set(tools.map((t) => t.name));
+    const dead = CURATED_MCP_TOOLS.filter((name) => !live.has(name));
+    assert.deepEqual(
+      dead,
+      [],
+      `CURATED_MCP_TOOLS names ${JSON.stringify(dead)} do not project onto the live /app/mcp surface — ` +
+        `the recommended allowlist has drifted from the real tool set. Fix app/mcpToolSurface.ts.`,
+    );
+  });
+
+  test("the curated subset is materially smaller than the full surface (tractable import)", () => {
+    assert(
+      CURATED_MCP_TOOLS.length <= CURATED_MCP_TOOLS_BUDGET,
+      `the curated subset (${CURATED_MCP_TOOLS.length}) exceeds its budget ${CURATED_MCP_TOOLS_BUDGET} — ` +
+        `it is creeping back toward "*". Keep it to the tools an agent actually drives/reads.`,
+    );
+    assert(
+      CURATED_MCP_TOOLS.length < tools.length,
+      `the curated subset (${CURATED_MCP_TOOLS.length}) must be smaller than the full surface ` +
+        `(${tools.length}); otherwise importing it buys nothing over "*".`,
+    );
+  });
+
+  test("curated entries carry no duplicates", () => {
+    const seen = new Set<string>();
+    const dupes: string[] = [];
+    for (const name of CURATED_MCP_TOOLS) {
+      if (seen.has(name)) dupes.push(name);
+      seen.add(name);
+    }
+    assert.deepEqual(dupes, [], `CURATED_MCP_TOOLS has duplicate entries: ${JSON.stringify(dupes)}`);
+  });
+
+  test("a cold heavy tool (previewDeliveryGraph) completes within the client budget — no -32001", async () => {
+    // A minimal valid graph → real synchronous BPMN layout, the exact heavy path issue #715 saw
+    // time out cold. Pure door (nothing staged), so this is safe and repeatable.
+    const graphJson = JSON.stringify({ nodes: [{ id: "h", kind: "human" }] });
+    const t0 = Date.now();
+    const res = await h.callTool("previewDeliveryGraph", { body: { graphJson } });
+    const elapsed = Date.now() - t0;
+    assert(!res.isError, `previewDeliveryGraph should succeed on a valid graph: ${res.text}`);
+    assert(
+      elapsed <= HEAVY_TOOL_BUDGET_MS,
+      `cold previewDeliveryGraph took ${elapsed}ms, over the client budget ${HEAVY_TOOL_BUDGET_MS}ms — ` +
+        `a heavy synchronous door this slow risks the client -32001 that poisons the session (issue #715).`,
+    );
+  });
+});

package/e2e/support/mcp-harness.ts

@@ -121,13 +121,31 @@ export interface McpHarness {
   /** The underlying booted app — exposed for a slice that needs to seed/inspect the app DB or drive
    *  an operator-only (`x-mcp`-excluded) cleanup route the MCP surface does not expose. */
   readonly app: TestApp;
-  /** The negotiated MCP session id (the captured `Mcp-Session-Id`). */
+  /** The CURRENT negotiated MCP session id (the captured `Mcp-Session-Id`). Tracks the live session,
+   *  so after {@link McpHarness.reinitialize} it reflects the NEW id, not the original. */
   readonly sessionId: string;
   /** `tools/list` — the projected tool catalogue (app operations + framework debug tools). */
   listTools(): Promise<McpTool[]>;
   /** `tools/call` — invoke a tool by name with its argument object. Optional `extraHeaders` are
    *  overlaid on the POST (e.g. an `x-hook-secret` shared-secret credential for a gated mutation). */
   callTool(name: string, args?: Record<string, unknown>, extraHeaders?: Record<string, string>): Promise<McpToolResult>;
+  /** `tools/call` against an EXPLICIT session id (not the harness's live one) — used to exercise the
+   *  session-loss path: a call carrying a stale/unknown/deleted `mcp-session-id` must be refused with
+   *  the runtime's `-32000` "no valid session id" error (issue #715, gap 1 self-heal regression). */
+  callToolAs(sessionId: string, name: string, args?: Record<string, unknown>): Promise<McpToolResult>;
+  /** Re-run the full client handshake (`initialize` → `notifications/initialized`), minting a FRESH
+   *  session and adopting it as the harness's live session. This is the client-side SELF-HEAL a real
+   *  MCP client performs after its session is lost (timeout, idle drop, proxy reset, LRU eviction):
+   *  the pinned runtime is session-stateful (a stateless/resumable transport is tracked upstream in
+   *  nano-ide#488), so re-initialising is how a client recovers the surface. Returns the new id. */
+  reinitialize(): Promise<string>;
+  /** End a session server-side via the transport's `DELETE` (the spec session-termination verb). With
+   *  no argument, ends the harness's current session; pass an id to end a specific one. After this the
+   *  ended id is unknown to the server, so a subsequent {@link McpHarness.callToolAs} with it is
+   *  refused `-32000`. Optional `extraHeaders` are overlaid on the DELETE (e.g. an `x-hook-secret`
+   *  shared-secret credential) exactly as {@link McpHarness.callTool} does, so this helper stays
+   *  usable on a shared-secret-guarded surface. Returns the DELETE's transport status. */
+  deleteSession(sessionId?: string, extraHeaders?: Record<string, string>): Promise<number>;
   /** A raw JSON-RPC request against `/app/mcp` (escape hatch for a bespoke case). `params` omitted →
    *  no `params` field; a `notifications/*` method is sent as a notification (no `id`, no response). */
   rpc(method: string, params?: unknown): Promise<McpRpcResult>;
@@ -221,9 +239,11 @@ export async function bootMcpHarness(opts: BootMcpHarnessOptions = {}): Promise<
     rmSync(dbDir, { recursive: true, force: true });
   };
 
-  let sessionId: string;
-  try {
-    // 1. initialize — capture the runtime-minted session id.
+  /** Run the full client handshake against the live surface and return the freshly-minted session id:
+   *  `initialize` (capture the `Mcp-Session-Id`) → `notifications/initialized`. Reused by the initial
+   *  boot AND by {@link McpHarness.reinitialize} so the self-heal path exercises the SAME real
+   *  handshake, never a shortcut. */
+  const doInitialize = async (): Promise<string> => {
     const initRes = await rpc("initialize", {
       protocolVersion: PROTOCOL_VERSION,
       capabilities: {},
@@ -240,10 +260,36 @@ export async function bootMcpHarness(opts: BootMcpHarnessOptions = {}): Promise<
         `MCP initialize returned no ${SESSION_HEADER} header — headers: ${JSON.stringify(initRes.headers)}`,
       );
     }
-    sessionId = mintedId;
+    // notifications/initialized — the client's post-init notification (no response expected).
+    await rpc("notifications/initialized", undefined, mintedId);
+    return mintedId;
+  };
+
+  /** Parse a `tools/call` JSON-RPC envelope into the client-visible {@link McpToolResult}. Shared by
+   *  `callTool` and `callToolAs` so both surface a JSON-RPC-level error (e.g. `-32000` no-session) and
+   *  a tool-level `isError` identically. */
+  const parseCallResult = (res: McpRpcResult): McpToolResult => {
+    const body = res.body as
+      | { result?: { isError?: boolean; content?: Array<{ type: string; text?: string }> }; error?: { message?: string } }
+      | undefined;
+    if (body?.error) {
+      const text = body.error.message ?? JSON.stringify(body.error);
+      return { isError: true, text, json: safeParse(text), httpStatus: res.httpStatus, raw: body };
+    }
+    const first = body?.result?.content?.find((c) => c.type === "text");
+    const text = first?.text ?? "";
+    return {
+      isError: body?.result?.isError === true,
+      text,
+      json: safeParse(text),
+      httpStatus: res.httpStatus,
+      raw: body,
+    };
+  };
 
-    // 2. notifications/initialized — the client's post-init notification (no response expected).
-    await rpc("notifications/initialized", undefined, sessionId);
+  let currentSessionId: string;
+  try {
+    currentSessionId = await doInitialize();
   } catch (err) {
     await teardown();
     throw err;
@@ -252,10 +298,12 @@ export async function bootMcpHarness(opts: BootMcpHarnessOptions = {}): Promise<
   let stopped = false;
   const harness: McpHarness = {
     app,
-    sessionId,
-    rpc: (method, params) => rpc(method, params, sessionId),
+    get sessionId(): string {
+      return currentSessionId;
+    },
+    rpc: (method, params) => rpc(method, params, currentSessionId),
     async listTools(): Promise<McpTool[]> {
-      const res = await rpc("tools/list", {}, sessionId);
+      const res = await rpc("tools/list", {}, currentSessionId);
       const body = res.body as { result?: { tools?: McpTool[] }; error?: unknown } | undefined;
       if (!body?.result?.tools) {
         throw new Error(`tools/list returned no result.tools: ${JSON.stringify(body)}`);
@@ -263,25 +311,30 @@ export async function bootMcpHarness(opts: BootMcpHarnessOptions = {}): Promise<
       return body.result.tools;
     },
     async callTool(name, args = {}, extraHeaders): Promise<McpToolResult> {
-      const res = await rpc("tools/call", { name, arguments: args }, sessionId, extraHeaders);
-      const body = res.body as
-        | { result?: { isError?: boolean; content?: Array<{ type: string; text?: string }> }; error?: { message?: string } }
-        | undefined;
-      if (body?.error) {
-        // A JSON-RPC-level error (e.g. an unknown tool name / protocol error) — distinct from a
-        // tool-level `isError` door failure. Surface it as an errored result carrying the message.
-        const text = body.error.message ?? JSON.stringify(body.error);
-        return { isError: true, text, json: safeParse(text), httpStatus: res.httpStatus, raw: body };
-      }
-      const first = body?.result?.content?.find((c) => c.type === "text");
-      const text = first?.text ?? "";
-      return {
-        isError: body?.result?.isError === true,
-        text,
-        json: safeParse(text),
-        httpStatus: res.httpStatus,
-        raw: body,
+      return parseCallResult(await rpc("tools/call", { name, arguments: args }, currentSessionId, extraHeaders));
+    },
+    async callToolAs(sessionId, name, args = {}): Promise<McpToolResult> {
+      return parseCallResult(await rpc("tools/call", { name, arguments: args }, sessionId));
+    },
+    async reinitialize(): Promise<string> {
+      currentSessionId = await doInitialize();
+      return currentSessionId;
+    },
+    async deleteSession(sessionId = currentSessionId, extraHeaders): Promise<number> {
+      const headers: Record<string, string> = {
+        accept: "application/json, text/event-stream",
       };
+      // Overlay caller headers FIRST, then set the session header authoritatively — a caller passing
+      // auth headers (e.g. `x-hook-secret`) must not clobber the `mcp-session-id` being terminated.
+      if (extraHeaders) Object.assign(headers, extraHeaders);
+      headers[SESSION_HEADER] = sessionId;
+      const res = await app.ui.call({
+        method: "DELETE",
+        path: MCP_PATH,
+        headers,
+        body: "",
+      });
+      return res.status ?? 200;
     },
     async stop(): Promise<void> {
       if (stopped) return;

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.177.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",
@@ -51,6 +51,8 @@
     "sync:nav:check": "node --experimental-strip-types scripts/sync-nav.ts --check",
     "gen:mcp-bodies": "node --experimental-strip-types scripts/inline-mcp-bodies.ts",
     "check:mcp-bodies": "node --experimental-strip-types scripts/inline-mcp-bodies.ts --check",
+    "sync:mcp-curated": "node --experimental-strip-types scripts/sync-mcp-curated.ts",
+    "sync:mcp-curated:check": "node --experimental-strip-types scripts/sync-mcp-curated.ts --check",
     "gen:cockpit-browser": "node --experimental-strip-types scripts/build-cockpit-browser.ts",
     "check:cockpit-browser": "node --experimental-strip-types scripts/build-cockpit-browser.ts --check",
     "dev": "urban dev",

package/pages/mcp.page.json

@@ -106,6 +106,32 @@
         }
       }
     },
+    {
+      "type": "text",
+      "id": "tractable-heading",
+      "props": { "text": "Import a curated tool set (tractable surface)", "variant": "heading" }
+    },
+    {
+      "type": "text",
+      "id": "tractable-body",
+      "props": {
+        "text": "The full projected surface is ~56 tools / ~79 KB of tools/list (app operations plus the framework urban_debug_* engine family) \u2014 large enough that a coding-agent harness may defer the whole set behind a tool-search gate, and \"tools\": [\"*\"] imports every one eagerly. Prefer a curated allowlist of the tools you actually drive and read with: set the server entry's \"tools\" to the curated subset instead of [\"*\"]. The curated list is maintained as the single source of truth in the repo (app/mcpToolSurface.ts, CURATED_MCP_TOOLS) and rendered as a copyable JSON block in the runbook \u2014 see docs/mcp-runbook.md \u00a7\"Import a curated subset\". [\"*\"] still works where the client does not defer; the full surface stays reachable either way.",
+        "variant": "sub"
+      }
+    },
+    {
+      "type": "text",
+      "id": "session-recovery-heading",
+      "props": { "text": "Recover a lost session (re-initialize on -32000)", "variant": "heading" }
+    },
+    {
+      "type": "text",
+      "id": "session-recovery-body",
+      "props": {
+        "text": "The /app/mcp transport is stateful streamable-HTTP: every tool call carries an mcp-session-id, and a call with a missing / stale / idle-dropped / proxy-reset / evicted session id is refused with -32000 \"no valid session id, and not an initialize request.\" A client that does not re-handshake then sees the whole surface report \"tool does not exist\" until it re-initializes \u2014 a single hiccup (notably a heavy-tool timeout) can brick every tool. The self-heal is a fresh initialize handshake, which mints a new session and restores the entire catalogue in one round trip; a well-behaved MCP client does this automatically on a -32000. A stateless/resumable transport that removes the session dependency is tracked upstream (nano-ide#488).",
+        "variant": "sub"
+      }
+    },
     {
       "type": "text",
       "id": "secret-heading",