@nanobpm/nano-workforce 0.177.0 → 0.178.0

package/CHANGELOG.md

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

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

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/package.json

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

package/scripts/sync-mcp-curated.test.ts

@@ -0,0 +1,19 @@
+// Drift guard for the curated MCP tool block in the runbook (issue #715).
+//
+// The curated `"tools"` allowlist is authored once in `app/mcpToolSurface.ts` and rendered into
+// `docs/mcp-runbook.md` by `scripts/sync-mcp-curated.ts`. This test — run under `npm test`, which CI
+// already gates — fails if the runbook block drifts from the source of truth, so the enforcement does
+// not depend on a separate workflow step (AGENTS.md: "Derivation over duplication: no drift
+// surfaces"). Run `npm run sync:mcp-curated` to reconcile. Mirrors `scripts/sync-nav.test.ts`.
+import { test } from "node:test";
+import { assert } from "#test-assert";
+import { reconciledRunbook } from "./sync-mcp-curated.ts";
+
+test("docs/mcp-runbook.md curated-tools block is in sync with app/mcpToolSurface.ts", () => {
+  const { current, next } = reconciledRunbook();
+  assert(
+    current === next,
+    "docs/mcp-runbook.md curated-tools block is STALE vs app/mcpToolSurface.ts — " +
+      "run `npm run sync:mcp-curated` and commit the result.",
+  );
+});

package/scripts/sync-mcp-curated.ts

@@ -0,0 +1,77 @@
+// Render the curated MCP tool allowlist (`CURATED_MCP_TOOLS`, app/mcpToolSurface.ts) into the runbook
+// (docs/mcp-runbook.md) between its `curated-tools` sentinels (issue #715).
+//
+// The curated `"tools"` allowlist an MCP client imports instead of `["*"]` (the tractable-surface
+// subset) is authored ONCE in `app/mcpToolSurface.ts`. The runbook shows it as a copyable JSON block;
+// this script derives that block from the source so the two can never drift (AGENTS.md "no drift
+// surfaces"), mirroring the repo's other derive/verify pairs (sync-nav, inline-mcp-bodies, layout-bpmn).
+//
+//   node --experimental-strip-types scripts/sync-mcp-curated.ts          # write the runbook block
+//   node --experimental-strip-types scripts/sync-mcp-curated.ts --check  # verify (CI) — non-zero on drift
+import { readFileSync, writeFileSync } from "node:fs";
+import process from "node:process";
+import { pathToFileURL } from "node:url";
+import { CURATED_MCP_TOOLS } from "../app/mcpToolSurface.ts";
+
+const ROOT = decodeURIComponent(new URL("../", import.meta.url).pathname);
+export const RUNBOOK_PATH = `${ROOT}docs/mcp-runbook.md`;
+
+const BEGIN = "<!-- BEGIN GENERATED: curated-tools (npm run sync:mcp-curated) -->";
+const END = "<!-- END GENERATED: curated-tools -->";
+
+/** The generated block: a fenced JSON array of curated tool names, one per line, in authored order. */
+export function renderBlock(): string {
+  const lines = CURATED_MCP_TOOLS.map((name, i) => {
+    const comma = i === CURATED_MCP_TOOLS.length - 1 ? "" : ",";
+    return `  ${JSON.stringify(name)}${comma}`;
+  });
+  return ["```json", "[", ...lines, "]", "```"].join("\n");
+}
+
+export function replaceBetweenSentinels(source: string, block: string): string {
+  const begin = source.indexOf(BEGIN);
+  const end = source.indexOf(END);
+  if (begin === -1 || end === -1 || end < begin) {
+    throw new Error(
+      `docs/mcp-runbook.md is missing the curated-tools sentinels (${BEGIN} … ${END}). ` +
+        "Restore them so the generated block has a home.",
+    );
+  }
+  const before = source.slice(0, begin + BEGIN.length);
+  const after = source.slice(end);
+  return `${before}\n${block}\n${after}`;
+}
+
+/** The runbook content the generator WOULD write given its current on-disk state. */
+export function reconciledRunbook(): { current: string; next: string } {
+  const current = readFileSync(RUNBOOK_PATH, "utf8");
+  return { current, next: replaceBetweenSentinels(current, renderBlock()) };
+}
+
+function main(): void {
+  const check = process.argv.includes("--check");
+  const { current, next } = reconciledRunbook();
+
+  if (check) {
+    if (current !== next) {
+      console.error(
+        "docs/mcp-runbook.md curated-tools block is STALE vs app/mcpToolSurface.ts. " +
+          "Run `npm run sync:mcp-curated` and commit the result.",
+      );
+      process.exit(1);
+    }
+    console.log("sync:mcp-curated: runbook curated-tools block is up to date.");
+    return;
+  }
+  if (current !== next) {
+    writeFileSync(RUNBOOK_PATH, next);
+    console.log("sync:mcp-curated: wrote curated-tools block into docs/mcp-runbook.md.");
+  } else {
+    console.log("sync:mcp-curated: runbook curated-tools block already up to date.");
+  }
+}
+
+// Run as a CLI only when invoked directly (not when imported by the drift test).
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main();
+}