@nanobpm/nano-workforce 0.176.1 → 0.178.0

package/app/agentic/families/claim.family.ts

@@ -0,0 +1,148 @@
+// nano-workforce — the agentic-channel `claim` / `release` job-ownership family (#713).
+//
+// H0 (#143) seam plug-in: ONE new file under `app/agentic/families/`, discovered by the loader's
+// `*.family.ts` convention and mounted by the seam — it never edits `main.ts`, `drainAndExit`, or any
+// shared boot line. It owns the `claim` (wire code 8) and `release` (wire code 9) message families —
+// the explicit job-ownership frames nano-ide#542 appended to `@nanobpm/agentic` — attaching each
+// handler through the hub's `registerFamilyHandler` seam (one family, one owning module), never a
+// shared dispatch switch.
+//
+// What it gives the fleet: a first-class {@link ClaimRegistry} (`instance → set<jobKey>`) that becomes
+// the AUTHORITATIVE source the supply snapshot reads for `jobKeys` — replacing the fragile
+// relay-derived visibility. Each frame carries its OWNING `instance` EXPLICITLY, so attribution reads
+// the frame, NOT the connection id (`conn.id`); that is what lets one per-host supervisor multiplex N
+// distinct workers' ownership over a single connection. On a reconnect the supervisor re-`register`s
+// every worker and re-`claim`s every active jobKey, and the (idempotent) claim handler rebuilds the
+// registry from that resync.
+//
+// Liveness: a worker holding a claim reads "working" even with ZERO transcript — visibility no longer
+// depends on terminal bytes landing/correlating. A bounded-memory maintenance tick reconciles the
+// claim registry against the live presence set so a departed supervisor's claims are reclaimed (the
+// `release` frame is the primary clear; this is the safety net for an unclean drop).
+//
+// Invariants (ADR 0056): app-tier only, never the engine; the Camunda-8 job protocol (worker⇄engine)
+// is untouched; ADVISORY — the registry is a read-only visibility source and NEVER gates a BPMN
+// sequence flow.
+import type { HubConnection } from "@nanobpm/agentic/channel";
+import { type Frame, validatePayload } from "@nanobpm/agentic/protocol";
+import { ClaimRegistry, setCurrentClaimRegistry } from "../claim-registry.ts";
+import type { AgenticContext, AgenticFamily } from "../registry.ts";
+import { currentPresenceRegistry } from "./presence.family.ts";
+
+/** The message-family names this module owns (the two ownership frames). */
+export const CLAIM_FAMILY = "claim";
+export const RELEASE_FAMILY = "release";
+
+/** The reconcile tick runs at a third of the presence TTL — matching the presence-maintenance cadence. */
+const SWEEP_DIVISOR = 3;
+/** Fallback reconcile cadence when no presence registry is mounted to source a TTL. */
+const DEFAULT_RECONCILE_MS = 10_000;
+
+/** Read a string property from an unknown frame payload, or undefined when absent / non-string. */
+function readString(value: unknown, key: string): string | undefined {
+  if (!value || typeof value !== "object") return undefined;
+  if (!Object.hasOwn(value, key)) return undefined;
+  const field = Object.getOwnPropertyDescriptor(value, key)?.value;
+  return typeof field === "string" ? field : undefined;
+}
+
+interface MountState {
+  readonly registry: ClaimRegistry;
+  timer: ReturnType<typeof setTimeout> | undefined;
+  stopped: boolean;
+}
+
+let state: MountState | undefined;
+
+/**
+ * The `claim` / `release` family module. `mount` installs a fresh {@link ClaimRegistry} as the
+ * process-wide singleton, attaches the two frame handlers via the S1 seam, and starts ONE bounded
+ * reconcile tick. `teardown` stops the tick, detaches nothing (the hub owns handler lifetime for the
+ * remount-guarded test path) and clears the singleton.
+ */
+export const family: AgenticFamily = {
+  name: CLAIM_FAMILY,
+
+  mount(ctx: AgenticContext): void {
+    const registry = new ClaimRegistry();
+    setCurrentClaimRegistry(registry);
+
+    // `claim` opens the ownership window; `release` closes it. Attribution reads the frame's EXPLICIT
+    // `instance` — never `conn.id` — so one connection can carry many instances' ownership frames. A
+    // malformed payload is rejected before it touches the registry (advisory: logged, connection
+    // kept). Both mutations are idempotent, matching the wire contract.
+    ctx.hub.registerFamilyHandler(CLAIM_FAMILY, (frame: Frame, _conn: HubConnection) => {
+      const result = validatePayload(CLAIM_FAMILY, frame.payload);
+      if (!result.ok) {
+        ctx.log.warn("agentic claim: malformed payload", { errors: result.errors.map((e) => e.code) });
+        return;
+      }
+      const instance = readString(frame.payload, "instance");
+      const jobKey = readString(frame.payload, "jobKey");
+      if (!instance || !jobKey) return;
+      registry.claim(instance, jobKey);
+    });
+
+    ctx.hub.registerFamilyHandler(RELEASE_FAMILY, (frame: Frame, _conn: HubConnection) => {
+      const result = validatePayload(RELEASE_FAMILY, frame.payload);
+      if (!result.ok) {
+        ctx.log.warn("agentic release: malformed payload", { errors: result.errors.map((e) => e.code) });
+        return;
+      }
+      const instance = readString(frame.payload, "instance");
+      const jobKey = readString(frame.payload, "jobKey");
+      if (!instance || !jobKey) return;
+      registry.release(instance, jobKey);
+    });
+
+    // Bounded-memory reconcile: drop claims whose owning instance no longer has a presence row (a
+    // dropped supervisor / aged-out worker). BOTH the drop-set AND the cadence are recomputed per
+    // tick from the live presence registry via a self-rescheduling timer, so the reconcile is truly
+    // independent of family mount order: whether presence mounts before or after this family, once it
+    // is present each tick reclaims absent instances' claims AND adjusts its cadence to the real TTL
+    // (a fixed-at-mount interval would stay pinned to the fallback cadence when claim mounts first).
+    // Advisory — a fault is logged, never thrown, and the tick never keeps the process alive on its
+    // own.
+    const reconcileMs = (): number => {
+      const presenceTtl = currentPresenceRegistry()?.ttlMs;
+      return Math.max(1, Math.floor((presenceTtl ?? DEFAULT_RECONCILE_MS) / SWEEP_DIVISOR));
+    };
+    const schedule = (): void => {
+      if (!state || state.stopped) return;
+      const timer = setTimeout(tick, reconcileMs());
+      timer.unref?.();
+      state.timer = timer;
+    };
+    const tick = () => {
+      try {
+        const presence = currentPresenceRegistry();
+        if (presence) {
+          const present = new Set(presence.registeredWorkers().map((w) => w.instance));
+          const released = registry.reconcile(present);
+          if (released.length > 0) {
+            ctx.log.info("agentic claim reconcile released absent instances", { released: released.length });
+          }
+        }
+        // else: no presence source → keep claims until one mounts (resync repopulates)
+      } catch (err) {
+        ctx.log.warn("agentic claim reconcile failed", { err: String(err) });
+      }
+      schedule();
+    };
+
+    state = { registry, timer: undefined, stopped: false };
+    schedule();
+    ctx.log.info("agentic claim family mounted", { families: [CLAIM_FAMILY, RELEASE_FAMILY] });
+  },
+
+  teardown(): void {
+    if (state) {
+      state.stopped = true;
+      if (state.timer !== undefined) clearTimeout(state.timer);
+    }
+    state = undefined;
+    setCurrentClaimRegistry(undefined);
+  },
+};
+
+export default family;

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