@nanobpm/nano-workforce 0.176.1 → 0.178.0

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/getAgenticSupply.test.ts

@@ -12,7 +12,9 @@ import { encodeFrame, type Frame } from "@nanobpm/agentic/protocol";
 import type { SqliteDb } from "@nanobpm/agentic/presence";
 import type { AppApi, DataLayer } from "@nanobpm/urban";
 import { assert, assertEquals } from "#test-assert";
+import { currentClaimRegistry } from "../app/agentic/claim-registry.ts";
 import { currentCorrelation } from "../app/agentic/correlation.ts";
+import { family as claimFamily } from "../app/agentic/families/claim.family.ts";
 import { family as correlationFamily } from "../app/agentic/families/correlation.family.ts";
 import { family } from "../app/agentic/families/presence.family.ts";
 import type { AgenticContext } from "../app/agentic/registry.ts";
@@ -154,7 +156,32 @@ test("shared-secret guard rejects a missing secret when configured", async () =>
   }
 });
 
-test("H6: with the correlation family mounted, jobKeys populate, stream repoints, and correlations are reported", async () => {
+test("#713: a claim populates jobKeys and repoints the drill stream with ZERO transcript (claim is the visibility source)", async () => {
+  const hub = await mountPresence(memSqlite());
+  const ctx: AgenticContext = { hub, registry: hub.registry, transport: undefined as never, data: undefined, log: noopLog() };
+  claimFamily.mount(ctx);
+  const claims = currentClaimRegistry();
+  assert(claims !== undefined, "the claim family installs the singleton");
+  // An explicit claim — no relay produce frame, no correlation link, zero transcript.
+  claims.claim("wk-a", "8420");
+  try {
+    const res = (await handler(input(), app)) as {
+      status: number;
+      body: { workers: Array<Record<string, unknown>>; correlations: unknown[] };
+    };
+    assertEquals(res.status, 200);
+    const w = res.body.workers[0];
+    assertEquals(w.jobKeys, ["8420"], "the claim registry feeds the jobKeys seam");
+    assertEquals(w.stream, "job:8420", "the drill stream repoints at the claimed job, keyed by the claim");
+    assertEquals(res.body.correlations.length, 0, "no correlation context until a terminal lands (drill-in only)");
+  } finally {
+    claimFamily.teardown?.();
+    family.teardown?.();
+    await hub.close();
+  }
+});
+
+test("#713: the correlation registry is demoted to drill-in context — a link alone no longer feeds jobKeys", async () => {
   const hub = await mountPresence(memSqlite());
   correlationFamily.mount({
     hub,
@@ -165,6 +192,7 @@ test("H6: with the correlation family mounted, jobKeys populate, stream repoints
   });
   const correlation = currentCorrelation();
   assert(correlation !== undefined, "the correlation family installs the singleton");
+  // A correlation link (drill-in context) WITHOUT a claim: visibility must NOT light up from it.
   correlation.link("wk-a", "6494", { processInstanceKey: "4612", bpmnProcessId: "plan-fanout", elementId: "implement-task", planKey: "o/r#142" });
   try {
     const res = (await handler(input(), app)) as {
@@ -176,8 +204,9 @@ test("H6: with the correlation family mounted, jobKeys populate, stream repoints
     };
     assertEquals(res.status, 200);
     const w = res.body.workers[0];
-    assertEquals(w.jobKeys, ["6494"], "the correlation registry feeds the jobKeys seam");
-    assertEquals(w.stream, "job:6494", "the drill stream repoints at the live job's stream");
+    assertEquals(w.jobKeys, [], "correlation alone no longer feeds jobKeys (relay demoted)");
+    assertEquals(w.stream, "wk-a", "the drill stream stays instance-keyed without a claim");
+    // The correlation context is still reported for drill-in.
     assertEquals(res.body.correlations.length, 1);
     const c = res.body.correlations[0];
     assertEquals(c.jobKey, "6494");

package/operations/getAgenticSupply.ts

@@ -3,11 +3,14 @@
 // worker list — family, host, current jobs, liveness — grouped by leaf token, sourced from the H1
 // presence registry (#144). Read-only projection; it NEVER gates control flow (advisory-only, ADR 0056).
 //
-// H6 (#149) closes the loop: the correlation registry (`app/agentic/correlation.ts`) supplies the
-// `jobKeysFor` resolver the presence snapshot exposes as a seam, so each worker's current jobKeys light
-// up; each worker's drill `stream` is repointed at its jobKey-scoped relay stream (`job:<jobKey>`); and
-// the report carries the `correlations` — the process-instance / plan context for every current job —
-// so the cockpit lines a worker's terminal up with "that process instance / this plan".
+// H6/#713 closes the loop with an EXPLICIT claim registry (`app/agentic/claim-registry.ts`): it is the
+// AUTHORITATIVE source the presence snapshot's `jobKeysFor` seam resolves against, so each worker's
+// current jobKeys light up from `claim` frames — not inferred from the relay terminal — and appear even
+// with ZERO transcript. Each worker's drill `stream` is repointed at its claimed jobKey-scoped relay
+// stream (`job:<jobKey>`), keyed by the CLAIM (explicit instance+jobKey), not by a connection. The
+// relay correlation registry is DEMOTED to drill-in context only: it still supplies the `correlations`
+// — the process-instance / plan context for a job's terminal — so the cockpit lines a worker's terminal
+// up with "that process instance / this plan", but it is no longer the visibility source.
 //
 // This is the supply half of the visibility plane only. The demand×supply matrix, missing-agent-type
 // reds, and diversity-SLO lights are DE-SCOPED to the enrolment epic #152 — this report carries no
@@ -16,7 +19,8 @@
 // The optional shared-secret guard stays HERE (the runtime does not enforce OpenAPI `security`): when
 // NANO_PR_WEBHOOK_SECRET is set, callers must present it via the x-hook-secret header. Unset → open.
 
-import { type CorrelationRegistry, currentCorrelation, type JobCorrelation } from "../app/agentic/correlation.ts";
+import { type ClaimRegistry, currentClaimRegistry } from "../app/agentic/claim-registry.ts";
+import { currentCorrelation, type JobCorrelation } from "../app/agentic/correlation.ts";
 import { currentPresenceRegistry, type SupplyWorker } from "../app/agentic/families/presence.family.ts";
 import { envVar } from "../app/version.ts";
 import type { AgenticJobCorrelation, AgenticSupplyReport, AgenticSupplyWorker } from "../nano-generated/api-io.d.ts";
@@ -27,13 +31,14 @@ import { defineOperation } from "../nano-generated/operations.ts";
 const SECRET = envVar("NANO_PR_WEBHOOK_SECRET") ?? "";
 
 // Project a presence-registry row to the wire worker. The drill `stream` defaults to the worker
-// instance (H5) but is repointed at the worker's jobKey-scoped relay stream (`job:<jobKey>`) when the
-// correlation registry knows a current job for it (H6) — so drilling in opens the LIVE job's terminal.
-function toWorker(w: SupplyWorker, correlation: CorrelationRegistry | undefined): AgenticSupplyWorker {
+// instance (H5) but is repointed at the worker's claimed jobKey-scoped relay stream (`job:<jobKey>`)
+// when the claim registry knows a current claim for it (#713) — keyed by the CLAIM, not by the
+// connection — so drilling in opens the LIVE job's terminal even before any transcript lands.
+function toWorker(w: SupplyWorker, claims: ClaimRegistry | undefined): AgenticSupplyWorker {
   const out: AgenticSupplyWorker = {
     instance: w.instance,
     identity: w.identity,
-    stream: correlation?.primaryStreamFor(w.instance) ?? w.instance,
+    stream: claims?.primaryStreamFor(w.instance) ?? w.instance,
     jobKeys: [...w.jobKeys],
     live: w.live,
     staleMs: w.staleMs,
@@ -67,15 +72,19 @@ export default defineOperation("getAgenticSupply", async ({ req }, app) => {
     return { status: 200, body: empty };
   }
 
-  // Thread the H6 correlation registry (if mounted) as the presence snapshot's jobKeysFor resolver so a
-  // worker's current jobKeys populate; absent → jobKeys stay empty (advisory, never an error).
+  // #713: the CLAIM registry (if mounted) is the authoritative `jobKeysFor` source the presence
+  // snapshot resolves against — a worker's current jobKeys come from explicit `claim` frames, not the
+  // relay terminal, so they populate with zero transcript. Absent → jobKeys stay empty (advisory).
+  const claims = currentClaimRegistry();
+  // The correlation registry is demoted to drill-in context only: it still carries the per-job
+  // process-instance / plan context surfaced in `correlations`, but no longer feeds visibility.
   const correlation = currentCorrelation();
-  const snapshot = registry.snapshot(correlation ? { jobKeysFor: (instance) => correlation.jobKeysFor(instance) } : {});
+  const snapshot = registry.snapshot(claims ? { jobKeysFor: (instance) => claims.jobKeysFor(instance) } : {});
   const report: AgenticSupplyReport = {
     count: snapshot.count,
     generatedAt: new Date().toISOString(),
-    workers: snapshot.workers.map((w) => toWorker(w, correlation)),
-    leaves: snapshot.leaves.map((leaf) => ({ token: leaf.token, workers: leaf.workers.map((w) => toWorker(w, correlation)) })),
+    workers: snapshot.workers.map((w) => toWorker(w, claims)),
+    leaves: snapshot.leaves.map((leaf) => ({ token: leaf.token, workers: leaf.workers.map((w) => toWorker(w, claims)) })),
     correlations: correlation ? correlation.snapshot().correlations.map(toCorrelation) : [],
   };
   return { status: 200, body: report };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.176.1",
+  "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",
@@ -62,7 +64,7 @@
     "lint:fix": "biome check --write app operations workers pages components scripts e2e main.ts"
   },
   "dependencies": {
-    "@nanobpm/agentic": "^0.10.0",
+    "@nanobpm/agentic": "^0.11.0",
     "@nanobpm/urban": "^0.90.0",
     "bpmn-auto-layout": "^2.0.0-alpha.2"
   },

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();
+}

package/test/agentic-e2e.test.ts

@@ -154,6 +154,7 @@ test("E2E: the whole visibility plane wires up — presence, correlation, supply
   assert(names.includes("presence"), "H1 presence family is discovered by the H0 seam");
   assert(names.includes("relay"), "H3 relay family is discovered by the H0 seam");
   assert(names.includes("correlation"), "H6 correlation family is discovered by the H0 seam");
+  assert(names.includes("claim"), "#713 claim family is discovered by the H0 seam");
 
   // ── H1: a worker connects and REGISTERs; a live presence row appears with its family/host. ──
   const worker = conn("wk-conn-1", "leafA");
@@ -162,7 +163,14 @@ test("E2E: the whole visibility plane wires up — presence, correlation, supply
   worker.feed({ lane: "control", family: "register", seq: 1, payload: { instance: "wk-a", capability: { family: "opus", host: "boxA" } } });
   await flush();
 
-  // ── H6: the orchestrator links the worker's active jobKey to its process instance / plan. ──
+  // ── #713: the worker CLAIMs its active jobKey — the authoritative visibility source (explicit
+  // instance, no relay/connection inference). This is what lights up jobKeys, even before any
+  // transcript lands. ──
+  worker.feed({ lane: "control", family: "claim", seq: 2, payload: { instance: "wk-a", jobKey: JOB } });
+  await flush();
+
+  // ── H6: the orchestrator links the worker's active jobKey to its process instance / plan (drill-in
+  // context only, since #713 — no longer the visibility source). ──
   const correlation = currentCorrelation();
   assert(correlation !== undefined, "the correlation family installed the singleton");
   correlation.link("wk-a", JOB, { processInstanceKey: "4612", bpmnProcessId: "plan-fanout", elementId: "implement-task", planKey: "nanobpm/nano-workforce#142" });
@@ -179,8 +187,8 @@ test("E2E: the whole visibility plane wires up — presence, correlation, supply
     assertEquals(w.instance, "wk-a");
     assertEquals(w.family, "opus");
     assertEquals(w.host, "boxA");
-    assertEquals(w.jobKeys, [JOB], "H1×H6: the correlation registry feeds the presence jobKeys seam");
-    assertEquals(w.stream, STREAM, "H6: the drill stream repoints at the live job's stream");
+    assertEquals(w.jobKeys, [JOB], "#713: the claim registry feeds the presence jobKeys seam");
+    assertEquals(w.stream, STREAM, "#713: the drill stream repoints at the claimed job's stream");
     assertEquals(res.body.correlations.length, 1);
     const c = res.body.correlations[0];
     assertEquals(c.jobKey, JOB);