Merge remote-tracking branch 'origin/main' into codex/legacy-cleanup-followup-20261022

docs/testing.md

@@ -65,6 +65,18 @@ API dependency, and independent fixture compiler oracles keep their existing
 TypeScript versions.
 
 `npm run build:cached` compiles the CLI/MCP runtime and its packaged skill.
+The build also records `dist/mcp-catalog.json` (compact inputs) and
+`dist/mcp-catalog-full.json` from the canonical SDK registrations and binds
+each to the runtime with its own SHA-256 digest. These are
+runtime artifacts, separate from the test catalog below. Default target-free
+MCP startup serves its schemas without constructing analysis validators;
+the first tool or guided-workflow request materializes the canonical runtime
+on that same SDK server. Explicit compact/full input selections preserve
+their advertised schemas throughout materialization. Initial-target,
+HTTP and output-schema-off startup keep the eager path; source runs without
+recorded artifacts also use eager composition. Compare memory both after discovery and after a completed
+request; report diagnostic GC separately from normal resident memory.
+
 Turbo's strict task environment preserves caller-selected `GOMAXPROCS`,
 `GOMEMLIMIT`, and `UV_THREADPOOL_SIZE` for resource-constrained builds and
 checks. These execution controls do not change artifact content, so changing

experiments/analysis-efficiency/managed-cli-runtime.mjs

@@ -6,8 +6,9 @@ import { join, relative } from "node:path";
 import { fileURLToPath } from "node:url";
 const sha = (value) => createHash("sha256").update(value).digest("hex");
 
-/** Bind a trial to its source checkout and the compiled CLI actually launched. */
-export const captureRuntimeBinding = async (runtime) => {
+/** Bind a trial to its source checkout and compiled runtime, including deferred assets. */
+export const captureRuntimeBinding = async (runtime, kind = "cli") => {
+  assert.ok(kind === "cli" || kind === "mcp", "Unknown runtime entry");
   const root = await realpath(runtime);
   const git = (args) =>
     execFileSync("git", args, { cwd: root, maxBuffer: 16 * 1024 * 1024 });
@@ -50,10 +51,16 @@ export const captureRuntimeBinding = async (runtime) => {
         files.push(relative(root, path));
     }
   };
-  await visit(join(root, "dist/cli-runtime"));
+  // MCP materializes additional workers and reads build-owned JSON after
+  // discovery. Bind every compiled JS/JSON asset, rather than only its entry.
+  await visit(join(root, kind === "mcp" ? "dist" : "dist/cli-runtime"));
   assert.ok(
-    files.includes(join("dist", "cli-runtime", "cli.js")),
-    "Missing compiled CLI entry",
+    files.includes(
+      kind === "mcp"
+        ? join("dist", "mcp", "main.js")
+        : join("dist", "cli-runtime", "cli.js"),
+    ),
+    "Missing compiled runtime entry",
   );
   const hash = createHash("sha256");
   let bytes = 0;
@@ -63,15 +70,23 @@ export const captureRuntimeBinding = async (runtime) => {
     hash.update(JSON.stringify([name, value.length, sha(value)]) + "\n");
   }
   return {
-    binding_version: 1,
+    binding_version: kind === "mcp" ? 2 : 1,
     root,
     node: process.version,
     git_revision: gitRevision,
     source_diff_sha256: sha(sourceDiff),
     untracked_source_sha256: sha(JSON.stringify(untrackedEntries)),
-    compiled_cli_sha256: hash.digest("hex"),
-    compiled_cli_files: files.length,
-    compiled_cli_bytes: bytes,
+    ...(kind === "mcp"
+      ? {
+          compiled_runtime_sha256: hash.digest("hex"),
+          compiled_runtime_files: files.length,
+          compiled_runtime_bytes: bytes,
+        }
+      : {
+          compiled_cli_sha256: hash.digest("hex"),
+          compiled_cli_files: files.length,
+          compiled_cli_bytes: bytes,
+        }),
   };
 };
 
@@ -82,6 +97,10 @@ export const assertRuntimeBinding = (actual, expected, mode) => {
 
 if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
   console.log(
-    JSON.stringify(await captureRuntimeBinding(process.argv[2]), null, 2),
+    JSON.stringify(
+      await captureRuntimeBinding(process.argv[2], process.argv[3]),
+      null,
+      2,
+    ),
   );
 }

experiments/analysis-efficiency/mcp-input-catalog.md

@@ -226,3 +226,8 @@ keeps default valid calls and typed refusals while checking full producer
 constraints separately. Five isolated suites passed 14 tests across call paths,
 ADB start, browser scenarios, source selection and managed analysis. The first
 browser attempt failed and remains recorded; no performance cohort changed.
+
+The subsequent [startup audit](mcp-startup.md) extends this harness with
+source/bundle bindings and a post-materialization directory check. Its new
+measurements are a separate cohort; reproduce this report at its recorded
+revision when comparing the original timing and model-session receipts.

experiments/analysis-efficiency/mcp-input-catalog.mjs

@@ -7,6 +7,10 @@ import { parseArgs } from "node:util";
 import { Client } from "@modelcontextprotocol/client";
 import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";
 import { Ajv2020 } from "ajv/dist/2020.js";
+import {
+  captureRuntimeBinding,
+  assertRuntimeBinding,
+} from "./managed-cli-runtime.mjs";
 
 const { values } = parseArgs({
   options: {
@@ -15,26 +19,68 @@ const { values } = parseArgs({
     oracle: { type: "string" },
     output: { type: "string" },
     profile: { type: "string", default: "default" },
+    phase: { type: "string", default: "analysis" },
+    cache: { type: "string", default: "cold" },
+    "cache-root": { type: "string" },
+    bindings: { type: "string" },
+    role: { type: "string" },
   },
 });
-for (const key of ["runtime", "artifact", "oracle", "output"])
+assert.ok(["analysis", "discovery"].includes(values.phase));
+assert.ok(["cold", "warm"].includes(values.cache));
+for (const key of values.phase === "analysis"
+  ? ["runtime", "artifact", "oracle", "output"]
+  : ["runtime", "output"])
   assert.ok(
     values[key] && resolve(values[key]) === values[key],
     `${key} must be absolute`,
   );
 assert.ok(["default", "full", "compact"].includes(values.profile));
+if (values.cache === "warm")
+  assert.ok(
+    values["cache-root"] &&
+      resolve(values["cache-root"]) === values["cache-root"],
+  );
 await mkdir(values.output, { recursive: false });
 const hash = (value) => createHash("sha256").update(value).digest("hex");
-const oracle = JSON.parse(await readFile(values.oracle, "utf8"));
-const artifactSha = hash(await readFile(values.artifact));
-assert.equal(artifactSha, oracle.artifact_sha256);
+let oracle;
+let artifactSha;
+if (values.phase === "analysis") {
+  oracle = JSON.parse(await readFile(values.oracle, "utf8"));
+  artifactSha = hash(await readFile(values.artifact));
+  assert.equal(artifactSha, oracle.artifact_sha256);
+}
+let expectedBinding;
+let bindingBefore;
+let auditBeforeMs;
+let measurementInputsSha256;
+const producerSources = {};
+if (values.bindings !== undefined) {
+  assert.ok(["baseline", "candidate"].includes(values.role));
+  const inputBytes = await readFile(values.bindings);
+  measurementInputsSha256 = hash(inputBytes);
+  const inputs = JSON.parse(inputBytes.toString("utf8"));
+  for (const name of ["mcp-input-catalog.mjs", "managed-cli-runtime.mjs"]) {
+    producerSources[name] = hash(
+      await readFile(new URL(name, import.meta.url)),
+    );
+    assert.equal(producerSources[name], inputs.harness_sources_sha256[name]);
+  }
+  expectedBinding = inputs.runtime_bindings[values.role];
+  const start = performance.now();
+  bindingBefore = await captureRuntimeBinding(values.runtime, "mcp");
+  auditBeforeMs = performance.now() - start;
+  assertRuntimeBinding(bindingBefore, expectedBinding, values.role);
+}
 const environment = {
   PATH: process.env.PATH,
   HOME: values.output,
   REA_LOG_LEVEL: "silent",
   UV_THREADPOOL_SIZE: "1",
   NODE_OPTIONS: "--max-old-space-size=2048",
-  NODE_DISABLE_COMPILE_CACHE: "1",
+  ...(values.cache === "cold"
+    ? { NODE_DISABLE_COMPILE_CACHE: "1" }
+    : { NODE_COMPILE_CACHE: values["cache-root"] }),
   ...(values.profile === "default"
     ? {}
     : { REA_MCP_INPUT_SCHEMA_PROFILE: values.profile }),
@@ -46,14 +92,29 @@ const transport = new StdioClientTransport({
   env: environment,
   stderr: "pipe",
 });
+const protocolRequests = {};
+const send = transport.send.bind(transport);
+transport.send = (...args) => {
+  const method = args[0].method;
+  if (typeof method === "string")
+    protocolRequests[method] = (protocolRequests[method] ?? 0) + 1;
+  return send(...args);
+};
 const client = new Client({ name: "rea-catalog-task", version: "1" });
 const report = {
   profile: values.profile,
+  phase: values.phase,
+  cache: values.cache,
+  cache_root: values["cache-root"] ?? null,
+  role: values.role,
+  measurement_inputs_sha256: measurementInputsSha256,
+  producer_sources_sha256: producerSources,
   artifact_sha256: artifactSha,
   calls: [],
   checks: [],
   status: "incomplete",
   cleanup_verified: false,
+  protocol_requests: protocolRequests,
 };
 const transcript = [];
 let stderr = "";
@@ -63,6 +124,15 @@ transport.stderr?.on("data", (value) => {
 const began = performance.now();
 try {
   await client.connect(transport);
+  report.protocol_era = client.getProtocolEra();
+  await writeFile(
+    join(values.output, "server.json"),
+    JSON.stringify({
+      info: client.getServerVersion(),
+      capabilities: client.getServerCapabilities(),
+      instructions: client.getInstructions(),
+    }),
+  );
   const catalog = await client.listTools();
   assert.equal(catalog.nextCursor, undefined);
   const definitions = new Map(catalog.tools.map((tool) => [tool.name, tool]));
@@ -73,97 +143,145 @@ try {
       ajv.validateSchema(tool.inputSchema),
       `Invalid schema: ${tool.name}`,
     );
-  await writeFile(join(values.output, "catalog.json"), JSON.stringify(catalog));
+  {
+    const encoded = JSON.stringify(catalog);
+    await writeFile(join(values.output, "catalog.json"), encoded);
+    report.catalog_sha256 = hash(encoded);
+  }
   report.tool_names = [...definitions.keys()];
-  const call = async (name, args) => {
-    const definition = definitions.get(name);
-    assert.ok(definition, `Missing named tool ${name}`);
-    const start = performance.now();
-    const reply = await client.callTool(
-      { name, arguments: args },
-      { toolDefinition: definition },
+  if (values.phase === "discovery") {
+    const prompts = await client.listPrompts();
+    assert.equal(prompts.nextCursor, undefined);
+    await writeFile(
+      join(values.output, "prompts.json"),
+      JSON.stringify(prompts),
     );
-    report.calls.push({
-      name,
-      elapsed_ms: performance.now() - start,
-      is_error: reply.isError === true,
-    });
-    transcript.push({ name, arguments: args, reply });
-    return reply;
-  };
-  const input = {
-    path: values.artifact,
-    view: {
-      collection: "packages",
-      names: ["serde"],
-      fields: ["name", "version", "kind"],
-    },
-  };
-  const first = await call("inspect_rust_binary", input);
-  assert.notEqual(first.isError, true);
-  const selected = first.structuredContent;
-  assert.ok(selected?.normalized_result?.page);
-  assert.deepEqual(selected.normalized_result.page.rows, oracle.serde_rows);
-  assert.equal(selected.subject.digest.sha256, artifactSha);
-  const parentId = selected.normalized_result.parent_evidence_id;
-  for (let index = 0; index < 2; index++) {
-    const reply = await call("inspect_analysis_view", {
-      source: { kind: "retained-evidence", evidence_id: parentId },
+    report.prompts_sha256 = hash(JSON.stringify(prompts));
+    report.answer = {
+      tools: report.tool_names,
+      prompts: prompts.prompts.map((prompt) => prompt.name),
+    };
+    report.status = "passed";
+  } else {
+    const call = async (name, args) => {
+      const definition = definitions.get(name);
+      assert.ok(definition, `Missing named tool ${name}`);
+      const start = performance.now();
+      const reply = await client.callTool(
+        { name, arguments: args },
+        { toolDefinition: definition },
+      );
+      report.calls.push({
+        name,
+        elapsed_ms: performance.now() - start,
+        is_error: reply.isError === true,
+      });
+      transcript.push({ name, arguments: args, reply });
+      return reply;
+    };
+    const input = {
+      path: values.artifact,
       view: {
-        kind: "rust",
         collection: "packages",
         names: ["serde"],
         fields: ["name", "version", "kind"],
       },
+    };
+    const first = await call("inspect_rust_binary", input);
+    assert.notEqual(first.isError, true);
+    const selected = first.structuredContent;
+    assert.ok(selected?.normalized_result?.page);
+    assert.deepEqual(selected.normalized_result.page.rows, oracle.serde_rows);
+    assert.equal(selected.subject.digest.sha256, artifactSha);
+    const parentId = selected.normalized_result.parent_evidence_id;
+    for (let index = 0; index < 2; index++) {
+      const reply = await call("inspect_analysis_view", {
+        source: { kind: "retained-evidence", evidence_id: parentId },
+        view: {
+          kind: "rust",
+          collection: "packages",
+          names: ["serde"],
+          fields: ["name", "version", "kind"],
+        },
+      });
+      assert.notEqual(reply.isError, true);
+      assert.deepEqual(
+        reply.structuredContent.normalized_result.page.rows,
+        oracle.serde_rows,
+      );
+      assert.equal(
+        reply.structuredContent.normalized_result.parent_evidence_id,
+        parentId,
+      );
+    }
+    const malformed = await call("inspect_rust_binary", {
+      path: values.artifact,
+      view: { collection: "packages", offset: -1 },
     });
-    assert.notEqual(reply.isError, true);
+    assert.equal(malformed.isError, true);
+    report.checks.push(
+      "Independent package rows and digest; repeated retained identity; canonical negative-offset refusal",
+    );
+    const exported = await call("export_evidence_bundle", {
+      path: join(values.output, "evidence.json"),
+    });
+    assert.notEqual(exported.isError, true);
+    const bundle = JSON.parse(
+      await readFile(join(values.output, "evidence.json"), "utf8"),
+    );
+    const parent = bundle.records.find(
+      (record) => record.evidence_id === parentId,
+    );
+    assert.ok(parent, "Complete original Evidence is retained");
+    assert.equal(parent.subject.digest.sha256, artifactSha);
     assert.deepEqual(
-      reply.structuredContent.normalized_result.page.rows,
-      oracle.serde_rows,
+      parent.normalized_result.auditable_metadata.packages,
+      oracle.packages,
     );
-    assert.equal(
-      reply.structuredContent.normalized_result.parent_evidence_id,
-      parentId,
+    assert.deepEqual(
+      parent.normalized_result.auditable_metadata.dependency_edges,
+      oracle.edges,
     );
+    report.parent_evidence_id = parentId;
+    report.parent_semantic_sha256 = hash(JSON.stringify(parent));
+    report.answer = oracle.serde_rows;
+    assert.deepEqual(
+      await client.listTools(),
+      catalog,
+      "Advertisement changed after canonical materialization",
+    );
+    report.checks.push(
+      "Catalog remains identical after canonical materialization",
+    );
+    report.status = "passed";
   }
-  const malformed = await call("inspect_rust_binary", {
-    path: values.artifact,
-    view: { collection: "packages", offset: -1 },
-  });
-  assert.equal(malformed.isError, true);
-  report.checks.push(
-    "Independent package rows and digest; repeated retained identity; canonical negative-offset refusal",
-  );
-  const exported = await call("export_evidence_bundle", {
-    path: join(values.output, "evidence.json"),
-  });
-  assert.notEqual(exported.isError, true);
-  const bundle = JSON.parse(
-    await readFile(join(values.output, "evidence.json"), "utf8"),
-  );
-  const parent = bundle.records.find(
-    (record) => record.evidence_id === parentId,
-  );
-  assert.ok(parent, "Complete original Evidence is retained");
-  assert.equal(parent.subject.digest.sha256, artifactSha);
-  assert.deepEqual(
-    parent.normalized_result.auditable_metadata.packages,
-    oracle.packages,
-  );
-  assert.deepEqual(
-    parent.normalized_result.auditable_metadata.dependency_edges,
-    oracle.edges,
-  );
-  report.parent_evidence_id = parentId;
-  report.parent_semantic_sha256 = hash(JSON.stringify(parent));
-  report.answer = oracle.serde_rows;
-  report.status = "passed";
 } finally {
   await client.close();
   await transport.close();
   report.cleanup_verified = transport.pid === null;
   assert.ok(report.cleanup_verified);
   report.elapsed_ms = performance.now() - began;
+  if (expectedBinding !== undefined) {
+    const start = performance.now();
+    const after = await captureRuntimeBinding(values.runtime, "mcp");
+    report.runtime_audit_ms = {
+      before: auditBeforeMs,
+      after: performance.now() - start,
+    };
+    assertRuntimeBinding(after, expectedBinding, values.role);
+    assert.deepEqual(after, bindingBefore);
+    assert.equal(
+      hash(await readFile(values.bindings)),
+      measurementInputsSha256,
+    );
+    for (const [name, digest] of Object.entries(producerSources))
+      assert.equal(
+        hash(await readFile(new URL(name, import.meta.url))),
+        digest,
+      );
+    report.runtime_binding = after;
+    report.runtime_binding_verified = true;
+  }
   await writeFile(
     join(values.output, "report.json"),
     JSON.stringify(report, null, 2) + "\n",

experiments/analysis-efficiency/mcp-startup-costs.py

@@ -0,0 +1,118 @@
+"""Verify paired SDK startup/analysis receipts and account for the whole task."""
+import argparse
+import hashlib
+import importlib.util
+import json
+import statistics
+from pathlib import Path
+
+import tiktoken
+
+parser = argparse.ArgumentParser(description=__doc__)
+parser.add_argument('root', type=Path)
+parser.add_argument('--output', type=Path, required=True)
+args = parser.parse_args()
+root = args.root
+input_bytes = (root / 'measurement-inputs.json').read_bytes()
+inputs = json.loads(input_bytes)
+expected = inputs['runtime_bindings']
+sha = lambda value: hashlib.sha256(value).hexdigest()
+compact = lambda value: json.dumps(value, ensure_ascii=False, separators=(',', ':'), allow_nan=False)
+encoding = tiktoken.get_encoding('cl100k_base')
+count = lambda value: len(encoding.encode(value, disallowed_special=()))
+for role in ['baseline', 'candidate']:
+    assert expected[role]['git_revision'] == inputs[f'{role}_revision']
+    assert expected[role]['source_diff_sha256'] == sha(b'')
+    assert expected[role]['untracked_source_sha256'] == sha(b'[]')
+assert expected['baseline']['root'] != expected['candidate']['root']
+assert expected['baseline']['compiled_runtime_sha256'] != expected['candidate']['compiled_runtime_sha256']
+spec = importlib.util.spec_from_file_location('catalog_costs', Path(__file__).with_name('mcp-input-catalog-costs.py'))
+module = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(module)
+catalogs = {}
+identities = {}
+rows = []
+for case in inputs['cases']:
+    directory = root / case['case']
+    report = json.loads((directory / 'report.json').read_text())
+    assert report['status'] == 'passed' and report['cleanup_verified']
+    assert report['runtime_binding_verified']
+    assert report['measurement_inputs_sha256'] == sha(input_bytes)
+    for name, producer_digest in report['producer_sources_sha256'].items():
+        assert producer_digest == inputs['harness_sources_sha256'][name]
+    assert report['runtime_binding'] == expected[case['role']]
+    for key in ['role', 'cache', 'profile', 'phase']:
+        assert report[key] == case[key]
+    raw = (directory / 'catalog.json').read_bytes()
+    catalog_digest = sha(raw)
+    assert catalog_digest == report['catalog_sha256']
+    profile = case['profile']
+    if profile not in catalogs:
+        catalog = json.loads(raw)
+        definitions = [{key: tool[key] for key in ['name', 'description', 'inputSchema']} for tool in catalog['tools']]
+        catalogs[profile] = {'sha256': catalog_digest, 'tool_count': len(catalog['tools']),
+                             'input_catalog_tokens': count(compact(definitions)),
+                             'raw_catalog_tokens': count(raw.decode()), 'raw_catalog_bytes': len(raw)}
+    assert catalog_digest == catalogs[profile]['sha256'], 'Directory differs across roles or phases'
+    transcript = json.loads((directory / 'transcript.json').read_text())
+    server = json.loads((directory / 'server.json').read_text())
+    tokens = {'question_and_recipe': count(inputs['questions'][case['phase']] + '\n' + inputs['recipes'][case['phase']]),
+              'server_instructions': count(server.get('instructions') or ''),
+              'input_catalog_once': catalogs[profile]['input_catalog_tokens'],
+              'arguments': sum(count(compact({'name': call['name'], 'arguments': call['arguments']})) for call in transcript),
+              'text_replies': sum(count(block['text']) for call in transcript for block in call['reply']['content'] if block['type'] == 'text')}
+    requests = report['protocol_requests']
+    assert requests['initialize'] == 1
+    if case['phase'] == 'analysis':
+        assert len(transcript) == 5 and requests['tools/call'] == 5 and requests['tools/list'] == 2
+        assert report['artifact_sha256'] == inputs['artifacts'][case['artifact']]['sha256']
+        identity = (report['parent_evidence_id'], report['parent_semantic_sha256'], sha(compact(report['answer']).encode()))
+        assert identities.setdefault(case['artifact'], identity) == identity
+        assert sum(call['is_error'] for call in report['calls']) == 1
+    else:
+        assert not transcript and requests.get('tools/call', 0) == 0
+        assert requests['tools/list'] == 1 and requests['prompts/list'] == 1
+        prompts = (directory / 'prompts.json').read_bytes()
+        assert sha(prompts) == report['prompts_sha256']
+        assert identities.setdefault('prompts', report['prompts_sha256']) == report['prompts_sha256']
+        tokens['prompt_directory'] = count(prompts.decode())
+    tokens['whole_task'] = sum(tokens.values())
+    resource = module.resource(directory)
+    for name, guard_digest in resource['guard_sources_sha256'].items():
+        assert guard_digest == inputs['harness_sources_sha256'][name]
+    del resource['guard_sources_sha256']
+    row = {**case, 'runtime_binding_sha256': sha(compact(report['runtime_binding']).encode()), 'runtime_audit_ms': report['runtime_audit_ms'],
+           'catalog_sha256': catalog_digest, 'parent_evidence_id': report.get('parent_evidence_id'),
+           'parent_semantic_sha256': report.get('parent_semantic_sha256'),
+           'answer_sha256': sha(compact(report['answer']).encode()), 'tokens_estimated': tokens,
+           'raw_catalog_result_tokens_all_lists': catalogs[profile]['raw_catalog_tokens'] * requests['tools/list'],
+           'raw_catalog_result_bytes_all_lists': catalogs[profile]['raw_catalog_bytes'] * requests['tools/list'],
+           'actual_model_usage': None, 'protocol_era': report['protocol_era'], 'protocol_requests': requests, 'calls': report['calls'],
+           **resource,
+           'receipt_sha256': {name: sha((directory / name).read_bytes()) for name in ['report.json', 'catalog.json', 'server.json', 'transcript.json']}}
+    assert row['catalog_sha256'] == row['receipt_sha256']['catalog.json'] == catalogs[profile]['sha256']
+    rows.append(row)
+assert len(rows) == 72
+summary = []
+for phase in ['discovery', 'analysis']:
+    for cache in ['cold', 'warm']:
+        for profile in ['default', 'full']:
+            for artifact in ([None] if phase == 'discovery' else ['ripgrep', 'zellij']):
+                item = {'phase': phase, 'cache': cache, 'profile': profile, 'artifact': artifact}
+                for role in ['baseline', 'candidate']:
+                    selected = [row for row in rows if all(row[key] == item[key] for key in ['phase', 'cache', 'profile', 'artifact']) and row['role'] == role]
+                    assert len(selected) == 3
+                    item[role] = {metric: {'median': statistics.median(row[metric] for row in selected),
+                                           'min': min(row[metric] for row in selected), 'max': max(row[metric] for row in selected)}
+                                  for metric in ['wall_seconds', 'cpu_seconds', 'kernel_family_peak_bytes_including_page_cache']}
+                    item[role]['tokens_estimated'] = [row['tokens_estimated']['whole_task'] for row in selected]
+                summary.append(item)
+result = {'status': 'passed', 'tokenizer': f'tiktoken=={tiktoken.__version__}/cl100k_base; estimates, not model usage',
+          'aggregation_sources_sha256': {path.name: sha(path.read_bytes()) for path in [Path(__file__), Path(spec.origin)]},
+          'context_scope': 'Question, explicit recipe, server instructions, one complete name/description/input-schema directory, every tool argument and text reply, plus prompt directory for discovery. This projection assumes the client retains a single unchanged directory. Raw catalog result costs include every observed tools/list result separately, with output schemas and without JSON-RPC envelopes. SDK initialization/framing, reasoning and actual model usage are unmeasured. The analysis task includes retained-read, rejection, export/oracle and post-materialization directory checks.',
+          'cache_scope': 'Cold disables server Node compile cache. Warm enables a prepopulated role/profile-specific cache after one complete analysis priming run. Fresh server/client processes and HOME each trial. Driver compile cache disabled in both cohorts. Cache hit rate and OS page cache are unmeasured; source/runtime audits warm compiled-file pages before startup.',
+          'resource_scope': 'Whole SDK driver, resource observer and owned REA process family. Includes before/after source-and-all-compiled-JS/JSON binding, SDK schema checks, extra validation calls, bundle export and independent oracle checking. Kernel cgroup peak includes file cache. Build/download/oracle preparation and cache priming excluded. Retained V8 heap and forced-GC diagnostics were not separately measured.',
+          'measurement_inputs': inputs, 'catalogs': catalogs, 'summary': summary, 'records': rows,
+          'warmup_receipts': {name: sha((root / name / 'report.json').read_bytes()) for name in [f'warmup-{profile}-{role}' for profile in ['default', 'full'] for role in ['baseline', 'candidate']]}}
+args.output.write_text(json.dumps(result, indent=2) + '\n')
+print(json.dumps(summary, indent=2))

experiments/analysis-efficiency/mcp-startup.md

@@ -0,0 +1,61 @@
+# MCP discovery and complete Rust tasks
+
+Target-free stdio discovery previously constructed the canonical analysis runtime before the client could inspect its directory. The candidate records SDK advertisements at build time for default/explicit compact and explicit full inputs. Its first tool, prompt or completion request materializes canonical validators and handlers on the same SDK server. HTTP, output-schema-off, initial-target and unrecorded source runs retain eager composition.
+
+Pinned baseline: [`main@c465ff5a8`](https://github.com/morluto/rea/commit/c465ff5a814b8e1a386fc547cbcd94df5c35f086). Measured candidate: [`04900abbc`](https://github.com/leeguooooo/rea/commit/04900abbcd3c3438fce4af932ff28400fe744a7d). Both use the same main base and locked dependencies. Before/after source and all compiled JS/JSON bindings identify the exact runtime used in every trial. The input manifest and producer scripts are also hashed and checked.
+
+## Real tasks and independent facts
+
+Official Alpine v3.21 packages supply ripgrep 14.1.1-r0 (3,416,168-byte executable) and Zellij 0.40.0-r0 (17,151,864 bytes). Their download URLs, archive/executable digests and aports revisions are retained in [the measurement data](mcp-startup.json). The independent Python ELF/section/zlib/JSON oracle checks 42 packages and 88 dependency edges for ripgrep, and 422 packages and 1,063 edges for Zellij. Serde versions are 1.0.210 and 1.0.137 respectively; the selected package kind remains explicit unknown (`null`). Verification covers embedded static build metadata; execution and runtime reachability remain unverified.
+
+Each analysis task initializes the actual SDK client, lists and validates the input directory, selects serde name/version/kind, reads the exact retained parent twice, verifies canonical rejection of a negative offset, exports and independently checks the complete package/edge inventory, confirms unchanged advertisements after materialization, then closes. All five tool calls and both directory reads are included in the measured task. Discovery tasks initialize, list tools/prompts, validate the input directory and close without an analysis call.
+
+All 72 paired trials and four priming runs passed. Each artifact has identical answers, parent Evidence IDs and complete semantic hashes across roles, profiles and cache modes. Both profiles retain byte-identical directories across baseline/candidate and before/after canonical materialization. The directory contains 213 tools. Complete Evidence is retained and exported through the existing shared workflow.
+
+## Measured cost
+
+Three alternating pairs per condition; table values are medians. Min/max ranges and individual receipts are in [mcp-startup.json](mcp-startup.json). Each cell is baseline → candidate. Kernel process-family peak includes file cache, SDK driver, observer and REA children.
+
+| Task      | Cache | Inputs            |  Wall seconds | Family CPU seconds | Family peak MiB |
+| --------- | ----- | ----------------- | ------------: | -----------------: | --------------: |
+| Directory | cold  | compact (default) | 5.661 → 2.236 |      5.403 → 2.050 |   559.3 → 248.6 |
+| Directory | cold  | full              | 5.256 → 2.337 |      5.040 → 2.175 |   650.9 → 349.1 |
+| Directory | warm  | compact (default) | 5.056 → 2.236 |      4.800 → 2.015 |   572.8 → 251.4 |
+| Directory | warm  | full              | 4.957 → 2.338 |      4.754 → 2.139 |   672.7 → 349.6 |
+| ripgrep   | cold  | compact (default) | 8.177 → 8.078 |      7.945 → 7.899 |   849.7 → 792.5 |
+| zellij    | cold  | compact (default) | 8.276 → 7.276 |      8.041 → 7.105 |   846.2 → 819.0 |
+| ripgrep   | cold  | full              | 8.180 → 7.483 |      8.000 → 7.312 |   846.5 → 794.4 |
+| zellij    | cold  | full              | 8.484 → 7.776 |      8.284 → 7.514 |   850.4 → 813.1 |
+| ripgrep   | warm  | compact (default) | 7.976 → 6.879 |      7.739 → 6.678 |   826.8 → 802.6 |
+| zellij    | warm  | compact (default) | 8.285 → 7.472 |      8.019 → 7.254 |   882.1 → 811.4 |
+| ripgrep   | warm  | full              | 8.074 → 7.476 |      7.890 → 7.265 |   852.1 → 803.6 |
+| zellij    | warm  | full              | 8.382 → 7.479 |      8.151 → 7.293 |   854.3 → 830.0 |
+
+Discovery improves clearly in this cohort. Completed-task changes depend on the workload: default cold ripgrep is approximately unchanged. Initialization moves into the first actual analysis request; its latency must be assessed with the full workflow.
+
+| Default ripgrep first RPC | Baseline ms | Candidate ms |
+| ------------------------- | ----------: | -----------: |
+| cold                      |       231.5 |       2532.1 |
+| warm                      |       227.1 |       2118.2 |
+
+Within each profile, advertised context remains identical. Input-directory estimates are 49,670 tokens for default compact and 205,744 for full. Whole-task estimates include the supplied question/recipe, server instructions, directory once, every tool argument and text reply, and the prompt directory in discovery tasks. This projection assumes the client retains one unchanged directory; raw catalog result costs count every observed list result separately, including output schemas. These use tiktoken 0.14.0/cl100k_base; actual model usage, reasoning and SDK initialization/framing are unmeasured.
+
+Linux x64 / AMD EPYC 7B12 / kernel 6.1.0-54-cloud-amd64 / Node 24.18.0, npm 11.16.0. Timed SDK tasks negotiated the legacy protocol era; auto/modern correctness is covered separately by compiled boundary tests. Trials run serially under a 1-CPU quota pinned to CPU 15, 4 GiB hard memory / 3 GiB early stop, no swap and 192 tasks. No resource stop, OOM or remaining payload process was observed. Cold disables server Node compile cache; warm uses a role/profile-specific cache populated by one complete task. Fresh processes and HOME are used each trial. Cache hit rate and OS page cache are unmeasured. Runtime audits warm compiled-file pages and are included in whole-task costs. Builds, downloads, oracle generation and cache priming are preparation outside those costs. Retained V8 heap and forced-GC measurements were not separately collected.
+
+## Ownership and validation
+
+`OwnedMcpServers` seals publication before taking its close snapshot, keeps failed exact close capabilities for retry and serves both eager and deferred paths. Deferred startup still joins servers published before an asynchronous serving handle settles. Post-snapshot and post-close factory calls are refused before allocation. Both production-boundary regressions fail with only the shared guard removed and pass restored.
+
+The moved transport/delivery implementation preserves current complete-error retention, escaped-preview fitting, response/string-limit recovery, target-content provenance and native Evidence continuations. Canonical parsers remain authoritative after lazy binding. Both protocol eras, input/output profile choices, invalid input/output, completion cancellation, partial startup and cleanup retry are exercised.
+
+Aggregation keeps catalog, producer-script and guard-script digests in distinct variables. Before publishing a trial it verifies that the catalog digest matches both its catalog-file receipt and the shared profile identity. Deliberately selecting the guard digest for that field is rejected. Regeneration preserves all measured timing, CPU, memory, context and parent-Evidence values.
+
+Executed local gates: 125 focused tests across 14 files; a repeated 22-case schema/profile subset after the pinned main merge; all six static-check tasks plus architecture guards; builds for both pinned runtimes; six documentation checks and five README consistency tests. HTTP coverage includes the real compiled CLI session/replacement/Host tests. Runtime-binding admission rejects a mismatched compiled graph before MCP launch; aggregation rejects a tampered trial binding. The raw receipts remain in `/tmp/rea-perf-mcp-startup-20261022`, identified by hashes in the data. Real initial-target providers, foreign OS runtime behavior and other providers remain outside this measurement.
+
+## Reproduction
+
+Use the pinned Node/npm toolchain and separate clean baseline/candidate checkouts. Build each with `npm ci` and `npm run build:cached` (the measured workspace shared one locked dependency installation). Acquire and verify the official packages listed in the data, extract the named executables and generate independent oracles with `mcp-input-catalog-oracle.py`.
+
+Capture each checkout with `node experiments/analysis-efficiency/managed-cli-runtime.mjs CHECKOUT mcp`. Construct `measurement-inputs.json` using the recorded schema, updating absolute checkout/artifact/oracle paths and their independently verified bindings. Keep it immutable through a cohort; producer source digests cover `mcp-input-catalog.mjs`, `managed-cli-runtime.mjs`, `resource-run.py` and `resource_payload.py`.
+
+Run `mcp-input-catalog.mjs` through `resource-run.py --observe-payload-exit` with `--runtime`, `--output`, `--bindings`, `--role baseline|candidate`, `--profile default|full`, `--phase discovery|analysis` and `--cache cold|warm`. Analysis also takes `--artifact` and `--oracle`; warm requires a role/profile-specific `--cache-root`. Disable the driver compile cache for both cohorts. Prime each warm role/profile once with the complete ripgrep task. Follow the 72-case order in the data, reversing role order in every second pair. Aggregate with `python mcp-startup-costs.py LAB --output mcp-startup.json` using tiktoken 0.14.0. The aggregator verifies every input/runtime/guard binding and completed receipt before producing summaries.

package.json

@@ -305,8 +305,8 @@
     "verify:solidity:metadata": "npm run build:cached && node scripts/verify-solidity-metadata.mjs",
     "verify:recorded:crash": "npm run build:cached && node scripts/verify-recorded-crash.mjs",
     "mcp-catalog:check:built": "node scripts/generate-mcp-tool-catalog.mjs --check",
-    "compile": "node scripts/clean-build-output.mjs && node scripts/run-typescript.mjs -p tsconfig.build.json && node scripts/record-catalog-digests.mjs && node scripts/bundle-runtime.mjs",
-    "compile:termux": "node scripts/clean-build-output.mjs && node --max-old-space-size=3072 node_modules/typescript-termux/lib/tsc.js -p tsconfig.build.json && node scripts/record-catalog-digests.mjs && node scripts/bundle-runtime.mjs",
+    "compile": "node scripts/clean-build-output.mjs && node scripts/run-typescript.mjs -p tsconfig.build.json && node scripts/record-catalog-digests.mjs && node scripts/record-mcp-catalog.mjs && node scripts/bundle-runtime.mjs",
+    "compile:termux": "node scripts/clean-build-output.mjs && node --max-old-space-size=3072 node_modules/typescript-termux/lib/tsc.js -p tsconfig.build.json && node scripts/record-catalog-digests.mjs && node scripts/record-mcp-catalog.mjs && node scripts/bundle-runtime.mjs",
     "artifacts:mcp-catalog": "node scripts/generate-mcp-tool-catalog.mjs",
     "artifacts:skills": "node scripts/generate-skill-metadata.mjs",
     "artifacts:product-catalog": "node scripts/generate-product-catalog.mjs",

scripts/lib/development-tests.mjs

@@ -39,6 +39,7 @@ export const parseDevelopmentTestRequest = (mode, arguments_) => {
 // runtime or typecheck prerequisites. Add a consumer here when it reads one.
 const artifactConsumers = {
   "artifacts:mcp-catalog": [
+    "tests/boundary/mcp/deferredRuntime.test.ts",
     "tests/boundary/mcp/contractPresentation.test.ts",
     "tests/boundary/mcp/toolSchemaValidity.test.ts",
   ],

scripts/record-mcp-catalog.mjs

@@ -0,0 +1,119 @@
+import { createHash } from "node:crypto";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { Client, InMemoryTransport } from "@modelcontextprotocol/client";
+
+// Runtime discovery is generated from the same canonical registrations, after
+// default identity has been recorded and before bundling. Test catalogs stay separate.
+const compiled = resolve(dirname(fileURLToPath(import.meta.url)), "../dist");
+const read = (name) => import(pathToFileURL(join(compiled, name)).href);
+const [
+  { createServer },
+  { createBinarySession },
+  { parseConfig },
+  { silentLogger },
+  { PROMPT_CONTRACTS },
+] = await Promise.all([
+  read("server/createServer.js"),
+  read("composition/binary.js"),
+  read("config/parseConfig.js"),
+  read("logger.js"),
+  read("contracts/promptContracts.js"),
+]);
+const recordCatalog = async (profile) => {
+  // Catalog generation is independent of the host account and user configuration.
+  const home = await mkdtemp(join(tmpdir(), "rea-mcp-catalog-"));
+  const environment = {
+    REA_MCP_INPUT_SCHEMA_PROFILE: profile,
+    HOME: home,
+    USERPROFILE: home,
+    XDG_CONFIG_HOME: join(home, "config"),
+    XDG_CACHE_HOME: join(home, "cache"),
+    XDG_STATE_HOME: join(home, "state"),
+  };
+  const cleanup = [];
+  let producerFailure;
+  try {
+    const config = parseConfig(environment);
+    if (!config.ok) throw config.error;
+    const session = createBinarySession(
+      config.value,
+      silentLogger,
+      environment,
+    );
+    cleanup.push(async () => {
+      const closed = await session.close({ retainProviderDocuments: true });
+      if (!closed.ok) throw closed.error;
+    });
+    const server = createServer({ kind: "session", session }, { environment });
+    cleanup.push(() => server.close());
+    const client = new Client({ name: "rea-catalog-recorder", version: "1" });
+    cleanup.push(() => client.close());
+    const [clientTransport, serverTransport] =
+      InMemoryTransport.createLinkedPair();
+    await server.connect(serverTransport);
+    await client.connect(clientTransport);
+    const tools = (await client.listTools()).tools;
+    const prompts = (await client.listPrompts()).prompts.map((prompt) => {
+      const contract = PROMPT_CONTRACTS.find(
+        (candidate) => candidate.name === prompt.name,
+      );
+      if (contract === undefined)
+        throw new Error(`Missing prompt ${prompt.name}`);
+      return { ...prompt, parameters: contract.arguments };
+    });
+    const catalog = {
+      version: 1,
+      info: client.getServerVersion(),
+      capabilities: client.getServerCapabilities(),
+      instructions: client.getInstructions(),
+      identity: server.catalogIdentity,
+      tools,
+      prompts,
+    };
+    const encoded = JSON.stringify(catalog);
+    const digest = createHash("sha256").update(encoded).digest("hex");
+    await writeFile(
+      join(
+        compiled,
+        profile === "full" ? "mcp-catalog-full.json" : "mcp-catalog.json",
+      ),
+      encoded,
+    );
+    return digest;
+  } catch (cause) {
+    producerFailure = { cause };
+    throw cause;
+  } finally {
+    const results = await Promise.allSettled(
+      cleanup.reverse().map((close) => Promise.resolve().then(close)),
+    );
+    const failures = results.flatMap((result) =>
+      result.status === "rejected" ? [result.reason] : [],
+    );
+    if (failures.length === 0) {
+      try {
+        await rm(home, { recursive: true, force: true });
+      } catch (cause) {
+        failures.push(cause);
+      }
+    }
+    if (failures.length > 0)
+      throw new AggregateError(
+        producerFailure === undefined
+          ? failures
+          : [producerFailure.cause, ...failures],
+        `Catalog cleanup failed; temporary home retained at ${home}`,
+      );
+  }
+};
+
+const digests = {};
+for (const profile of ["compact", "full"])
+  digests[profile] = await recordCatalog(profile);
+await writeFile(
+  join(compiled, "recordedMcpCatalog.js"),
+  `/** Recorded from the compiled runtime; do not edit. */\nexport const RECORDED_MCP_CATALOG_SHA256 = ${JSON.stringify(digests)};\n`,
+);

src/config/mcpInputSchemaProfile.ts

@@ -12,11 +12,16 @@ export const COMPACT_INPUT_SCHEMA_BUDGET_BYTES = 13 * 1024;
 
 export const mcpInputSchemaProfileSchema = z.enum(["full", "compact"]);
 
+/** Resolve the selected advertisement at the configuration boundary. */
+export const resolveMcpInputSchemaProfile = (
+  profile: McpInputSchemaProfile | undefined,
+): McpInputSchemaProfile => profile ?? "compact";
+
 /** Select the default compact advertisement, preserving an explicit full choice. */
 export const compactPresentationForMcpInputSchemaProfile = (
   profile: "full" | "compact" | undefined,
 ): { readonly budgetBytes: number } | undefined =>
-  profile === "full"
+  resolveMcpInputSchemaProfile(profile) === "full"
     ? undefined
     : { budgetBytes: COMPACT_INPUT_SCHEMA_BUDGET_BYTES };
 

src/ghidra/GhidraLanguageCatalog.ts

@@ -1,12 +1,13 @@
-import { open, readdir } from "node:fs/promises";
-import type { FileHandle } from "node:fs/promises";
+import { readdir } from "node:fs/promises";
 import { join } from "node:path";
 import { parseXmlDocument } from "../domain/xmlDocument.js";
 import { decodeXmlPlistText } from "../domain/propertyListXmlText.js";
 
+import type { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";
+import { withArtifactRegularFile } from "../artifacts/ArtifactFileOperation.js";
 import type { GhidraLanguageOverride } from "../config/ghidraLanguageOverride.js";
 import { ConfigurationError } from "../domain/configurationErrors.js";
-import { OwnedFileHandle } from "../filesystem/OwnedFileHandle.js";
+import { RegularFileOperationCancelled } from "../filesystem/RegularFile.js";
 import { readBoundedFileBytes } from "../process/BoundedFileBytes.js";
 
 /** One language definition and the compiler specs it declares. */
@@ -20,62 +21,6 @@ const MAX_LDEFS_BYTES = 4 * 1024 * 1024;
 // Processor modules ship under Processors; installed extensions may add more.
 const LANGUAGE_ROOTS = ["Ghidra/Processors", "Ghidra/Extensions"] as const;
 
-interface RetainedLanguageFile {
-  readonly path: string;
-  readonly owner: OwnedFileHandle<FileHandle>;
-}
-
-/** Language definition handles whose close is unconfirmed but retryable. */
-const pendingLanguageFileCleanup = new Set<RetainedLanguageFile>();
-
-/**
- * Cleanup of one or more language definition handles is unconfirmed. Any
- * read failure that preceded it is kept as the primary failure.
- */
-export class GhidraLanguageCatalogCleanupError extends Error {
-  constructor(
-    readonly paths: readonly string[],
-    readonly causes: readonly unknown[],
-    readonly readFailure?: unknown,
-  ) {
-    super(
-      `Language definition cleanup is unconfirmed: ${paths.join(", ")}`,
-      readFailure === undefined ? undefined : { cause: readFailure },
-    );
-  }
-}
-
-/** Close one owner; retain it only while a later close can still succeed. */
-const closeLanguageFile = async (
-  file: RetainedLanguageFile,
-): Promise<unknown> => {
-  try {
-    await file.owner.close();
-    pendingLanguageFileCleanup.delete(file);
-    return undefined;
-  } catch (cause: unknown) {
-    // Descriptor invalidation does not prove that this owner confirmed close.
-    // Keep even sticky failures in the lifecycle scope so later reads surface
-    // the unresolved cleanup instead of silently abandoning ownership.
-    pendingLanguageFileCleanup.add(file);
-    return cause;
-  }
-};
-
-/** Retry every retained owner before reporting the failures together. */
-const retryLanguageFileCleanup = async (): Promise<void> => {
-  const failed: { readonly path: string; readonly cause: unknown }[] = [];
-  for (const file of pendingLanguageFileCleanup) {
-    const cause = await closeLanguageFile(file);
-    if (cause !== undefined) failed.push({ path: file.path, cause });
-  }
-  if (failed.length > 0)
-    throw new GhidraLanguageCatalogCleanupError(
-      failed.map(({ path }) => path),
-      failed.map(({ cause }) => cause),
-    );
-};
-
 /** Parse the `<language>` elements of one `.ldefs` document. */
 export const parseGhidraLanguageDefinitions = (
   text: string,
@@ -122,61 +67,66 @@ const languageDirectories = async (installDir: string): Promise<string[]> => {
   return directories;
 };
 
-/** Read at most the catalog limit; undefined marks an oversized file. */
-const readLanguageDefinitionFile = async (
+/**
+ * Parse one definition before its final close; an oversized file declares
+ * nothing. The caller's scope owns a descriptor whose close is unconfirmed.
+ */
+const readLanguageDefinitionFile = (
   path: string,
-): Promise<Buffer | undefined> => {
-  await retryLanguageFileCleanup();
-  const file = { path, owner: new OwnedFileHandle(await open(path, "r")) };
-  let read:
-    | { readonly ok: true; readonly bytes: Buffer | undefined }
-    | { readonly ok: false; readonly cause: unknown };
-  try {
-    read = {
-      ok: true,
-      bytes: await readBoundedFileBytes(file.owner.handle, MAX_LDEFS_BYTES),
-    };
-  } catch (cause: unknown) {
-    read = { ok: false, cause };
-  }
-  const cleanup = await closeLanguageFile(file);
-  if (cleanup !== undefined)
-    throw new GhidraLanguageCatalogCleanupError(
-      [path],
-      [cleanup],
-      read.ok ? undefined : read.cause,
-    );
-  if (!read.ok) throw read.cause;
-  return read.bytes;
-};
-
-/** Read every language definition shipped by one Ghidra installation. */
-export const readGhidraLanguageCatalog = async (
-  installDir: string,
-): Promise<readonly GhidraLanguageDefinition[]> => {
-  // Surface retained cleanup even when this catalog has no definitions to read.
-  await retryLanguageFileCleanup();
-  const definitions: GhidraLanguageDefinition[] = [];
-  for (const directory of await languageDirectories(installDir)) {
-    let entries: string[];
-    try {
-      entries = await readdir(directory);
-    } catch {
-      continue;
-    }
-    for (const entry of entries.sort()) {
-      if (!entry.endsWith(".ldefs")) continue;
-      const bytes = await readLanguageDefinitionFile(join(directory, entry));
-      if (bytes === undefined) continue;
+  resources: ArtifactResourceScope,
+  signal: AbortSignal | undefined,
+): Promise<readonly GhidraLanguageDefinition[]> =>
+  withArtifactRegularFile(
+    path,
+    resources,
+    signal,
+    async (file) => {
+      const bytes = await readBoundedFileBytes(file, MAX_LDEFS_BYTES, {
+        signal,
+        cancellationFailure: (reason) =>
+          new RegularFileOperationCancelled(reason),
+      });
       // The XML byte owner validates encoding and declaration before syntax
       // parsing; a literal U+FFFD cannot diagnose invalid source bytes.
-      definitions.push(
-        ...parseGhidraLanguageDefinitions(decodeXmlPlistText(bytes)),
-      );
+      return bytes === undefined
+        ? []
+        : parseGhidraLanguageDefinitions(decodeXmlPlistText(bytes));
+    },
+    "follow",
+  );
+
+/**
+ * Read every language definition shipped by one Ghidra installation. Admission
+ * first retries cleanup the scope retains, so an unconfirmed close blocks reads
+ * only until that exact owner releases.
+ */
+export const readGhidraLanguageCatalog = (
+  installDir: string,
+  resources: ArtifactResourceScope,
+  signal?: AbortSignal,
+): Promise<readonly GhidraLanguageDefinition[]> =>
+  resources.run(async () => {
+    const definitions: GhidraLanguageDefinition[] = [];
+    for (const directory of await languageDirectories(installDir)) {
+      let entries: string[];
+      try {
+        entries = await readdir(directory);
+      } catch {
+        continue;
+      }
+      for (const entry of entries.sort()) {
+        if (!entry.endsWith(".ldefs")) continue;
+        definitions.push(
+          ...(await readLanguageDefinitionFile(
+            join(directory, entry),
+            resources,
+            signal,
+          )),
+        );
+      }
     }
-  }
-  return definitions;
-};
+    return definitions;
+  });
 
 /**
  * Check a configured import language against the installation before launch,

src/ghidra/GhidraLanguageOverride.test.ts

@@ -18,6 +18,7 @@ import {
   readGhidraLanguageCatalog,
 } from "./GhidraLanguageCatalog.js";
 import { GhidraProvider } from "./GhidraProvider.js";
+import { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";
 
 // Abbreviated from Ghidra 12.1.4 Processors/x86/data/languages/x86.ldefs.
 const X86_LDEFS = `<?xml version="1.0" encoding="UTF-8"?>
@@ -197,10 +198,15 @@ describe("Ghidra language catalog", () => {
       },
       { id: "x86:LE:16:Real Mode", compilerSpecIds: ["default"] },
     ]);
-    expect(await readGhidraLanguageCatalog(installDir)).toHaveLength(2);
-    expect(await readGhidraLanguageCatalog(join(installDir, "absent"))).toEqual(
-      [],
-    );
+    expect(
+      await readGhidraLanguageCatalog(installDir, new ArtifactResourceScope()),
+    ).toHaveLength(2);
+    expect(
+      await readGhidraLanguageCatalog(
+        join(installDir, "absent"),
+        new ArtifactResourceScope(),
+      ),
+    ).toEqual([]);
   });
 
   it("reads a UTF-8 signed definition beside an unsigned sibling", async () => {
@@ -219,7 +225,9 @@ describe("Ghidra language catalog", () => {
       ]),
     );
     await writeFile(join(module("x86"), "x86.ldefs"), X86_LDEFS);
-    expect(await readGhidraLanguageCatalog(root)).toEqual([
+    expect(
+      await readGhidraLanguageCatalog(root, new ArtifactResourceScope()),
+    ).toEqual([
       { id: "probe:LE:32:default", compilerSpecIds: [] },
       ...parseGhidraLanguageDefinitions(X86_LDEFS),
     ]);

src/ghidra/GhidraProvider.ts

@@ -40,7 +40,6 @@ import {
 } from "../domain/jsonValue.js";
 import { err, ok, type Result } from "../domain/result.js";
 import { AnalysisError } from "../domain/analysisErrorBase.js";
-import { ProviderAdapterError } from "../domain/providerAdapterError.js";
 import { ProviderCleanupError } from "../domain/providerCleanupError.js";
 import type { Logger } from "pino";
 import { GhidraClient } from "./GhidraClient.js";
@@ -55,9 +54,9 @@ import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
 import { resolveGhidraAnalysisSeeds } from "./GhidraAnalysisSeeds.js";
 import {
   admitGhidraLanguageOverride,
-  GhidraLanguageCatalogCleanupError,
   readGhidraLanguageCatalog,
 } from "./GhidraLanguageCatalog.js";
+import { ghidraFileFailure } from "./GhidraFileArtifacts.js";
 import {
   ghidraProcessorUnsupportedReason,
   isGhidraPspTarget,
@@ -397,31 +396,15 @@ export class GhidraProvider implements AnalysisProviderCandidate {
     if (override !== undefined && installation.status === "available") {
       let catalog: Awaited<ReturnType<typeof readGhidraLanguageCatalog>>;
       try {
-        catalog = await readGhidraLanguageCatalog(installation.installDir);
+        catalog = await readGhidraLanguageCatalog(
+          installation.installDir,
+          this.#inspectionResources,
+          options?.signal,
+        );
       } catch (cause: unknown) {
-        if (cause instanceof GhidraLanguageCatalogCleanupError)
-          return err(
-            new ProviderCleanupError(
-              "ghidra",
-              cause.paths,
-              {
-                reason: cause.message,
-                paths: [...cause.paths],
-                close_failures: cause.causes.map(providerFailureText),
-                ...(cause.readFailure === undefined
-                  ? {}
-                  : { read_failure: providerFailureText(cause.readFailure) }),
-              },
-              { operation: "resolve_analysis_profile", cause },
-            ),
-          );
         return err(
-          new ProviderAdapterError("ghidra", "resolve_analysis_profile", {
-            cause,
-            diagnostics: {
-              reason:
-                "Could not read the installed Ghidra language definitions.",
-            },
+          ghidraFileFailure(cause, "resolve_analysis_profile", {
+            setting: "REA_GHIDRA_LANGUAGE_ID",
           }),
         );
       }

src/main.ts

@@ -8,19 +8,12 @@ import { realpathSync } from "node:fs";
 import { serveStdio } from "@modelcontextprotocol/server/stdio";
 
 import { parseConfig } from "./config/parseConfig.js";
-import { createBinarySession } from "./composition/binary.js";
-import { createLogger } from "./logger.js";
 import { projectAnalysisError } from "./domain/analysisErrorProjection.js";
 import type { RuntimeDependencies } from "./main/types.js";
+import { runDeferred } from "./main/deferredRuntime.js";
+import { RECORDED_MCP_CATALOG_SHA256 } from "./recordedMcpCatalog.js";
 import { SERVER_START_FAILED } from "./main/messages.js";
-import { openInitialTarget } from "./main/startup.js";
-import { startMcpTransport } from "./main/transport.js";
-import {
-  createOptionalObservationFactories,
-  loadOptionalObservationProviders,
-} from "./composition/optionalObservationProviders.js";
-import { createToolResultDelivery } from "./server/toolResult.js";
-import { createShutdown } from "./main/shutdown.js";
+
 import {
   createExitStatus,
   latchSignalShutdown,
@@ -53,6 +46,7 @@ const httpRuntimeDependencies = (
   const base = runtimeDependencies();
   return {
     ...base,
+    transport: "http",
     setExitCode: exit.set,
     serve: async (factory, options) => {
       // Loaded here so the default stdio entry never loads the HTTP listener.
@@ -90,12 +84,7 @@ const httpRuntimeDependencies = (
   };
 };
 
-/**
- * Start the long-lived MCP adapter and install idempotent shutdown handlers.
- * The adapter owns its BinarySession for the process lifetime; stdin EOF on
- * the stdio transport and process signals on either transport close bridge
- * resources without assuming ownership of the Hopper app.
- */
+/** Start discovery without constructing unused analysis validators. */
 export const run = async (
   dependencies: RuntimeDependencies = runtimeDependencies(),
 ): Promise<number> => {
@@ -105,38 +94,23 @@ export const run = async (
     dependencies.writeStderr(`${projectAnalysisError(config.error).message}\n`);
     return 1;
   }
-  const logger = createLogger("mcp", config.value.logLevel);
-  const serverLogger = logger.child({ layer: "server" });
-  const session = createBinarySession(config.value, logger, environment);
-  const opened = await openInitialTarget(
-    session,
+  const fullOutputCatalog =
+    environment.REA_MCP_OUTPUT_SCHEMA_PROFILE === undefined ||
+    environment.REA_MCP_OUTPUT_SCHEMA_PROFILE === "full";
+  if (
+    RECORDED_MCP_CATALOG_SHA256 !== undefined &&
+    dependencies.transport !== "http" &&
+    config.value.hopperTargetPath === undefined &&
+    fullOutputCatalog &&
+    dependencies.createServer === undefined &&
+    dependencies.loadOptionalProviders === undefined
+  ) {
+    return runDeferred({ ...dependencies, env: environment }, config.value);
+  }
+  return (await import("./main/eagerRuntime.js")).runEager(
+    { ...dependencies, env: environment },
     config.value,
-    serverLogger,
-    dependencies.writeStderr,
   );
-  if (!opened.ok) return opened.exitCode;
-  const transport = await startMcpTransport(dependencies, session, {
-    logger,
-    serverLogger,
-    environment,
-    delivery: createToolResultDelivery(config.value.mcpMaxResponseBytes),
-    loadOptionalProviders:
-      dependencies.loadOptionalProviders ??
-      (() =>
-        loadOptionalObservationProviders(
-          createOptionalObservationFactories(environment),
-        )),
-  });
-  if (!transport.ok) return 1;
-  createShutdown({
-    handle: transport.handle,
-    closeAndroid: transport.closeAndroid,
-    closeOptionalProviders: transport.closeOptionalProviders,
-    session,
-    dependencies,
-    serverLogger,
-  });
-  return 0;
 };
 
 /** Run the executable boundary without exposing an unexpected startup cause. */

src/main/OwnedMcpServers.ts

@@ -0,0 +1,26 @@
+/** Own the exact close capabilities of every published SDK instance. */
+export class OwnedMcpServers<Server extends { close(): Promise<void> }> {
+  private readonly servers = new Map<Server, () => Promise<void>>();
+  private accepting = true;
+
+  create(factory: () => Server): Server {
+    if (!this.accepting) throw new Error("MCP connection is closed");
+    const server = factory();
+    const close = server.close.bind(server);
+    const ownedClose = async (): Promise<void> => {
+      await close();
+      this.servers.delete(server);
+    };
+    this.servers.set(server, ownedClose);
+    server.close = ownedClose;
+    return server;
+  }
+
+  /** Seal publication before snapshotting; failed close capabilities stay owned. */
+  closeAll(): Promise<PromiseSettledResult<void>[]> {
+    this.accepting = false;
+    return Promise.allSettled(
+      [...this.servers.values()].map((close) => Promise.resolve().then(close)),
+    );
+  }
+}

src/main/deferredRuntime.ts

@@ -0,0 +1,243 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import {
+  STDIO_DEFAULT_MAX_BUFFER_SIZE,
+  type McpRequestContext,
+} from "@modelcontextprotocol/server";
+import {
+  RECORDED_MCP_CATALOG_SHA256,
+  type RecordedMcpCatalog,
+} from "../recordedMcpCatalog.js";
+import type { AppConfig } from "../config/types.js";
+import {
+  resolveMcpInputSchemaProfile,
+  type McpInputSchemaProfile,
+} from "../config/mcpInputSchemaProfile.js";
+import { DeferredEvidenceMcpServer } from "../server/DeferredEvidenceMcpServer.js";
+import { ToolResultDelivery } from "../server/ToolResultDelivery.js";
+import { createLogger } from "../logger.js";
+import { reportMcpShutdownFailure } from "./shutdown.js";
+import type { McpServerHandle, RuntimeDependencies } from "./types.js";
+import { MCP_CONNECTION_LOST, SERVER_START_FAILED } from "./messages.js";
+import { OwnedMcpServers } from "./OwnedMcpServers.js";
+
+/** Verify the build-owned artifact before trusting its exact typed projection. */
+const readCatalog = (profile: McpInputSchemaProfile): RecordedMcpCatalog => {
+  const bytes = readFileSync(
+    new URL(
+      profile === "full" ? "../mcp-catalog-full.json" : "../mcp-catalog.json",
+      import.meta.url,
+    ),
+  );
+  if (
+    createHash("sha256").update(bytes).digest("hex") !==
+    RECORDED_MCP_CATALOG_SHA256?.[profile]
+  )
+    throw new Error(SERVER_START_FAILED);
+  // The digest binds these bytes to the same compiled producer and SDK converter.
+  const catalog: unknown = JSON.parse(bytes.toString("utf8"));
+  if (
+    typeof catalog !== "object" ||
+    catalog === null ||
+    Reflect.get(catalog, "version") !== 1
+  )
+    throw new Error(SERVER_START_FAILED);
+  return catalog as RecordedMcpCatalog;
+};
+
+const initializeRuntime = async (
+  server: DeferredEvidenceMcpServer,
+  dependencies: RuntimeDependencies,
+  context: McpRequestContext,
+  config: AppConfig,
+  startedAt: string,
+): Promise<void> => {
+  let shutdown: (() => Promise<void>) | undefined;
+  let closeSession: (() => Promise<void>) | undefined;
+  let sessionClosed = false;
+  server.ownRuntimeCleanup(async () => {
+    if (shutdown !== undefined) return shutdown();
+    const results = await Promise.allSettled([
+      server.closePartialRuntime(),
+      (async () => {
+        if (!sessionClosed && closeSession !== undefined) {
+          await closeSession();
+          sessionClosed = true;
+        }
+      })(),
+    ]);
+    const failures = results.flatMap((result) =>
+      result.status === "rejected" ? [result.reason] : [],
+    );
+    if (failures.length > 0)
+      throw new AggregateError(failures, "MCP startup cleanup failed");
+  });
+  const [{ runEager }, { createServer }] = await Promise.all([
+    import("./eagerRuntime.js"),
+    import("../server/createServer.js"),
+  ]);
+  const result = await runEager(
+    {
+      ...dependencies,
+      registerShutdown: () => () => undefined,
+      captureShutdown: (close) => {
+        shutdown = close;
+      },
+      createServer: (source, options) => {
+        if (source.kind === "session")
+          closeSession = async () => {
+            const result = await source.session.close({
+              retainProviderDocuments: true,
+            });
+            if (!result.ok) throw result.error;
+          };
+        return createServer(source, {
+          ...options,
+          mcpServer: server,
+          startedAt,
+        });
+      },
+      serve: (factory) => {
+        let close: (() => Promise<void>) | undefined;
+        server.materialize(() => {
+          const configured = factory(context);
+          if (configured !== server) throw new Error(SERVER_START_FAILED);
+          close = configured.close.bind(configured);
+        });
+        return { close: () => close?.() ?? Promise.resolve() };
+      },
+    },
+    config,
+  );
+  if (result !== 0 || shutdown === undefined)
+    throw new Error(SERVER_START_FAILED);
+};
+
+/** Own every SDK-created server, including discarded discovery instances. */
+export const runDeferred = async (
+  dependencies: RuntimeDependencies,
+  config: AppConfig,
+): Promise<number> => {
+  const serverLogger = createLogger("mcp", config.logLevel).child({
+    layer: "server",
+  });
+  const profile = resolveMcpInputSchemaProfile(config.mcpInputSchemaProfile);
+  let firstCatalog: RecordedMcpCatalog | undefined = readCatalog(profile);
+  const servers = new OwnedMcpServers<DeferredEvidenceMcpServer>();
+  let handle: McpServerHandle | undefined;
+  let attempt: Promise<void> | undefined;
+  let unregister: () => void = () => undefined;
+  let closing = false;
+  let finishServing!: () => void;
+  const serving = new Promise<void>((resolve) => {
+    finishServing = resolve;
+  });
+  const close = (): Promise<void> => {
+    closing = true;
+    attempt ??= Promise.resolve()
+      .then(async () => {
+        // A transport published after shutdown begins is still ours to close.
+        await serving;
+        const ownedHandle = handle;
+        const handleResults = Promise.allSettled([
+          ...(ownedHandle === undefined
+            ? []
+            : [
+                Promise.resolve()
+                  .then(() => ownedHandle.close())
+                  .then(() => {
+                    handle = undefined;
+                  }),
+              ]),
+        ]);
+        // Servers published before the serving handle settles join this owner;
+        // closeAll seals further publication before taking its snapshot.
+        const [handles, instances] = await Promise.all([
+          handleResults,
+          servers.closeAll(),
+        ]);
+        const failures = [...handles, ...instances].flatMap((result) =>
+          result.status === "rejected" ? [result.reason] : [],
+        );
+        if (failures.length > 0)
+          throw new AggregateError(failures, "MCP cleanup failed");
+        unregister();
+      })
+      .catch((cause) => {
+        attempt = undefined;
+        throw cause;
+      });
+    return attempt;
+  };
+  const requestClose = () => {
+    void close().catch((cause) =>
+      reportMcpShutdownFailure(cause, dependencies, serverLogger),
+    );
+  };
+  try {
+    // Keep cleanup reachable even if serve creates a server and then throws.
+    unregister = dependencies.registerShutdown(requestClose);
+    dependencies.captureShutdown?.(close);
+    try {
+      handle = await dependencies.serve(
+        (context) => {
+          const server = servers.create(() => {
+            const catalog = firstCatalog ?? readCatalog(profile);
+            firstCatalog = undefined;
+            const startedAt = new Date().toISOString();
+            const server = new DeferredEvidenceMcpServer(
+              catalog,
+              new ToolResultDelivery(
+                config.mcpMaxResponseBytes ?? STDIO_DEFAULT_MAX_BUFFER_SIZE,
+              ),
+              (target) =>
+                initializeRuntime(
+                  target,
+                  dependencies,
+                  context,
+                  config,
+                  startedAt,
+                ).catch((cause) => {
+                  dependencies.setExitCode(1);
+                  throw cause;
+                }),
+            );
+            return server;
+          });
+          const previous = server.server.onclose;
+          server.server.onclose = () => {
+            previous?.();
+            requestClose();
+          };
+          return server;
+        },
+        {
+          onerror: () => {
+            serverLogger.error(MCP_CONNECTION_LOST);
+            dependencies.writeStderr(`${MCP_CONNECTION_LOST}\n`);
+          },
+        },
+      );
+    } finally {
+      finishServing();
+    }
+  } catch (cause) {
+    finishServing();
+    serverLogger.error(
+      { error: cause instanceof Error ? cause.message : String(cause) },
+      SERVER_START_FAILED,
+    );
+    try {
+      await close();
+    } catch (cleanupCause) {
+      throw new AggregateError(
+        [cause, cleanupCause],
+        "MCP startup and cleanup failed",
+      );
+    }
+    dependencies.writeStderr(`${SERVER_START_FAILED}\n`);
+    return 1;
+  }
+  if (closing) await close();
+  return 0;
+};

src/main/eagerRuntime.ts

@@ -0,0 +1,70 @@
+import { snapshotEnvironment } from "../process/snapshotEnvironment.js";
+
+import type { AppConfig } from "../config/types.js";
+import { ok } from "../domain/result.js";
+import { parseConfig } from "../config/parseConfig.js";
+import { createBinarySession } from "../composition/binary.js";
+import { createLogger } from "../logger.js";
+import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
+import type { RuntimeDependencies } from "./types.js";
+import { openInitialTarget } from "./startup.js";
+import { startMcpTransport } from "./transport.js";
+import {
+  createOptionalObservationFactories,
+  loadOptionalObservationProviders,
+} from "../composition/optionalObservationProviders.js";
+import { createToolResultDelivery } from "../server/toolResult.js";
+import { createShutdown } from "./shutdown.js";
+
+/**
+ * Start the long-lived MCP adapter and install idempotent shutdown handlers.
+ * The adapter owns its BinarySession for the process lifetime; EOF and process
+ * signals close bridge resources without assuming ownership of the Hopper app.
+ */
+export const runEager = async (
+  dependencies: RuntimeDependencies,
+  selectedConfig?: AppConfig,
+): Promise<number> => {
+  const environment = snapshotEnvironment(dependencies.env);
+  const config =
+    selectedConfig === undefined
+      ? parseConfig(environment)
+      : ok(selectedConfig);
+  if (!config.ok) {
+    dependencies.writeStderr(`${projectAnalysisError(config.error).message}\n`);
+    return 1;
+  }
+  const logger = createLogger("mcp", config.value.logLevel);
+  const serverLogger = logger.child({ layer: "server" });
+  const session = createBinarySession(config.value, logger, environment);
+  const opened = await openInitialTarget(
+    session,
+    config.value,
+    serverLogger,
+    dependencies.writeStderr,
+  );
+  if (!opened.ok) return opened.exitCode;
+  const transport = await startMcpTransport(dependencies, session, {
+    logger,
+    serverLogger,
+    environment,
+    delivery: createToolResultDelivery(config.value.mcpMaxResponseBytes),
+    loadOptionalProviders:
+      dependencies.loadOptionalProviders ??
+      (() =>
+        loadOptionalObservationProviders(
+          createOptionalObservationFactories(environment),
+        )),
+  });
+  if (!transport.ok) return 1;
+  const shutdown = createShutdown({
+    handle: transport.handle,
+    closeAndroid: transport.closeAndroid,
+    closeOptionalProviders: transport.closeOptionalProviders,
+    session,
+    dependencies,
+    serverLogger,
+  });
+  dependencies.captureShutdown?.(shutdown.shutdown);
+  return 0;
+};

src/main/shutdown.ts

@@ -78,21 +78,30 @@ export const createShutdown = (input: {
   };
   const requestShutdown = (): void => {
     shutdown().catch((cause: unknown) => {
-      serverLogger.debug(
-        { failure_cause: describeShutdownFailure(cause) },
-        "MCP shutdown rejected",
-      );
-      dependencies.setExitCode(1);
-      serverLogger.error(MCP_SHUTDOWN_FAILED);
-      dependencies.writeStderr(`${MCP_SHUTDOWN_FAILED}\n`);
-      if (cause instanceof AnalysisError)
-        dependencies.writeStderr(`${projectAnalysisError(cause).message}\n`);
+      reportMcpShutdownFailure(cause, dependencies, serverLogger);
     });
   };
   unregisterShutdown = dependencies.registerShutdown(requestShutdown);
   return { shutdown, request: requestShutdown };
 };
 
+/** Preserve the same diagnostics for eager and deferred runtime owners. */
+export const reportMcpShutdownFailure = (
+  cause: unknown,
+  dependencies: Pick<RuntimeDependencies, "writeStderr" | "setExitCode">,
+  serverLogger: Logger,
+): void => {
+  serverLogger.debug(
+    { failure_cause: describeShutdownFailure(cause) },
+    "MCP shutdown rejected",
+  );
+  dependencies.setExitCode(1);
+  serverLogger.error(MCP_SHUTDOWN_FAILED);
+  dependencies.writeStderr(`${MCP_SHUTDOWN_FAILED}\n`);
+  if (cause instanceof AnalysisError)
+    dependencies.writeStderr(`${projectAnalysisError(cause).message}\n`);
+};
+
 const describeShutdownFailure = (
   cause: unknown,
 ): Readonly<Record<string, JsonValue>> =>

src/main/transport.ts

@@ -8,6 +8,7 @@ import { StreamableHttpListenError } from "../server/http/streamableHttpListenEr
 import type { ToolResultDelivery } from "../server/toolResult.js";
 import type { McpServerHandle, RuntimeDependencies } from "./types.js";
 import type { OptionalProviderLoadResult } from "../application/OptionalObservationProviders.js";
+import { OwnedMcpServers } from "./OwnedMcpServers.js";
 import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
 import {
   MCP_CONNECTION_LOST,
@@ -62,11 +63,9 @@ export const startMcpTransport = async (
     );
   }
   const androidProviders: AndroidAnalysisPort[] = [];
-  const servers = new Set<ReturnType<typeof createServer>>();
+  const servers = new OwnedMcpServers<ReturnType<typeof createServer>>();
   const closeServers = async (): Promise<void> => {
-    const results = await Promise.allSettled(
-      [...servers].map((server) => server.close()),
-    );
+    const results = await servers.closeAll();
     const failures = results.flatMap((result) =>
       result.status === "rejected" ? [result.reason] : [],
     );
@@ -110,32 +109,26 @@ export const startMcpTransport = async (
   let handle: McpServerHandle;
   try {
     handle = await dependencies.serve(
-      () => {
-        // The SDK can discard a discovery probe and construct a replacement server.
-        const android = createAndroidAnalysisProvider(
-          serverContext.environment,
-        );
-        androidProviders.push(android);
-        const server = (dependencies.createServer ?? createServer)(
-          { kind: "session", session },
-          {
-            logger: serverContext.logger,
-            environment: serverContext.environment,
-            delivery: serverContext.delivery,
-            ...optionalProviders,
-            optionalObservationProviderOwner: "caller",
-            androidAnalysis: android,
-          },
-        );
-        // The SDK can discard a server even when its provider cleanup failed.
-        servers.add(server);
-        const closeServer = server.close.bind(server);
-        server.close = async () => {
-          await closeServer();
-          servers.delete(server);
-        };
-        return server;
-      },
+      () =>
+        servers.create(() => {
+          // The SDK can discard a discovery probe and construct a replacement server.
+          const android = createAndroidAnalysisProvider(
+            serverContext.environment,
+          );
+          androidProviders.push(android);
+          const server = (dependencies.createServer ?? createServer)(
+            { kind: "session", session },
+            {
+              logger: serverContext.logger,
+              environment: serverContext.environment,
+              delivery: serverContext.delivery,
+              ...optionalProviders,
+              optionalObservationProviderOwner: "caller",
+              androidAnalysis: android,
+            },
+          );
+          return server;
+        }),
       {
         onerror: () => {
           serverLogger.error(MCP_CONNECTION_LOST);

src/main/types.ts

@@ -23,6 +23,9 @@ export type McpServe = (
 ) => McpServerHandle | Promise<McpServerHandle>;
 
 export interface RuntimeDependencies {
+  /** HTTP keeps the eager runtime; deferred materialization is stdio-only. */
+  readonly transport?: "stdio" | "http";
+  readonly captureShutdown?: (shutdown: () => Promise<void>) => void;
   readonly env: NodeJS.ProcessEnv;
   readonly serve: McpServe;
   readonly writeStderr: (text: string) => void;

src/process/ProviderProcess.launcherExit.test.ts

@@ -0,0 +1,240 @@
+import { EventEmitter } from "node:events";
+import { PassThrough } from "node:stream";
+import { afterEach, expect, it, vi } from "vitest";
+import {
+  cleanupOwnedProcessGroup,
+  type OwnedProcessGroup,
+  type ProcessCleanupResult,
+  type ProcessIdentityObservation,
+  type ProcessOwnershipHost,
+  type ProcessTableEntry,
+} from "./ProcessOwnership.js";
+import { ProcessOwnershipEvidenceOwner } from "./ProcessOwnershipEvidence.js";
+import { ProviderProcessSupervisor } from "./ProviderProcess.js";
+
+const JAVA = "/usr/lib/jvm/java-21-openjdk-amd64/bin/java";
+
+const ownership = (): OwnedProcessGroup => ({
+  runId: "run-6134",
+  leaderPid: 910,
+  processGroupId: 910,
+  expectedParentPid: 17,
+  expectedCommand: JAVA,
+  sweepTokenOwnedProcesses: true,
+  evidenceOwner: new ProcessOwnershipEvidenceOwner(),
+});
+
+const launcherRow = (command: string): ProcessTableEntry => ({
+  pid: 910,
+  parentPid: 17,
+  processGroupId: 910,
+  state: "R",
+  command,
+});
+
+const nativeIdentity = (
+  lifecycle: "non-zombie" | "exiting",
+): ProcessIdentityObservation => ({
+  state: "readable",
+  identity: "linux-starttime:4242",
+  lifecycle: { state: "observed", lifecycle },
+  relation: { state: "observed", parentPid: 17, processGroupId: 910 },
+});
+
+/** A launcher child whose exit the supervisor observes only when the test says so. */
+const launcherChild = () => {
+  const child = Object.assign(new EventEmitter(), {
+    stdout: new PassThrough(),
+    stderr: new PassThrough(),
+    exitCode: null,
+    signalCode: null,
+    kill: vi.fn(() => false),
+  });
+  let exited = false;
+  return {
+    child,
+    get exited() {
+      return exited;
+    },
+    exit() {
+      exited = true;
+      child.emit("exit", 0, null);
+      child.stdout.end();
+      child.stderr.end();
+      child.emit("close", 0, null);
+    },
+  };
+};
+
+/** Linux-like host: the launcher row stays listed until the child exits. */
+const hostFor = (
+  launcher: ReturnType<typeof launcherChild>,
+  row: ProcessTableEntry,
+  lifecycle?: "non-zombie" | "exiting",
+): ProcessOwnershipHost => {
+  const host: ProcessOwnershipHost = {
+    platform: "linux",
+    listProcesses: vi.fn(async () => (launcher.exited ? [] : [row])),
+    environment: vi.fn(async () => ({ REA_PROCESS_RUN_ID: "run-6134" })),
+    signalGroup: vi.fn(),
+  };
+  if (lifecycle === undefined) return host;
+  return {
+    ...host,
+    processIdentities: vi.fn(async (rows: readonly ProcessTableEntry[]) => {
+      const observation: ProcessIdentityObservation = launcher.exited
+        ? { state: "absent", reason: "not-found-in-caller-pid-namespace" }
+        : nativeIdentity(lifecycle);
+      return new Map(rows.map(({ pid }) => [pid, observation] as const));
+    }),
+  };
+};
+
+const supervise = (
+  launcher: ReturnType<typeof launcherChild>,
+  host: ProcessOwnershipHost,
+) => {
+  const results: ProcessCleanupResult[] = [];
+  const supervisor = new ProviderProcessSupervisor({
+    process: launcher.child,
+    ownsProcessLifetime: true,
+    ownership: ownership(),
+    cleanup: async () => {
+      const result = await cleanupOwnedProcessGroup(ownership(), host);
+      results.push(result);
+      return result;
+    },
+  });
+  return { supervisor, results };
+};
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+it("re-verifies after the launcher's own exit settles an exiting procps row", async () => {
+  const launcher = launcherChild();
+  const host = hostFor(launcher, launcherRow("[java]"));
+  const { supervisor, results } = supervise(launcher, host);
+  // The JVM finishes tearing down only after the single table refresh.
+  vi.mocked(host.listProcesses).mockImplementation(async () => {
+    if (launcher.exited) return [];
+    setTimeout(() => launcher.exit(), 20);
+    return [launcherRow("[java]")];
+  });
+
+  await expect(supervisor.stop()).resolves.toEqual({
+    status: "verified-cleanup",
+  });
+  expect(results).toEqual([
+    {
+      cleaned: false,
+      reason: `owned launcher command identity did not match (observed=[java]; expected=${JAVA})`,
+    },
+    { cleaned: true, signaled: false },
+  ]);
+  expect(host.signalGroup).not.toHaveBeenCalled();
+  expect(launcher.child.kill).not.toHaveBeenCalled();
+});
+
+it("re-verifies after native exit-in-progress outlasts the settlement deadline", async () => {
+  const launcher = launcherChild();
+  const host = hostFor(launcher, launcherRow("[java]"), "exiting");
+  const { supervisor, results } = supervise(launcher, host);
+  const exitTimer = setTimeout(() => launcher.exit(), 1_200);
+  try {
+    await expect(supervisor.stop({ killGraceMs: 2_000 })).resolves.toEqual({
+      status: "verified-cleanup",
+    });
+  } finally {
+    clearTimeout(exitTimer);
+  }
+  expect(results).toEqual([
+    { cleaned: false, reason: "owned launcher exit could not be confirmed" },
+    { cleaned: true, signaled: false },
+  ]);
+  expect(host.signalGroup).not.toHaveBeenCalled();
+});
+
+it.each([
+  ["identityless", undefined],
+  ["native", "non-zombie"],
+] as const)(
+  "keeps a still-live mismatched %s launcher incomplete without signaling",
+  async (_host, lifecycle) => {
+    const launcher = launcherChild();
+    const host = hostFor(launcher, launcherRow("/usr/bin/other"), lifecycle);
+    const { supervisor, results } = supervise(launcher, host);
+    const started = performance.now();
+
+    const stopped = await supervisor.stop({ killGraceMs: 50 });
+
+    expect(performance.now() - started).toBeGreaterThanOrEqual(45);
+    expect(stopped).toEqual({
+      status: "incomplete",
+      reason: `owned launcher command identity did not match (observed=/usr/bin/other; expected=${JAVA})`,
+      cleanupResult: results[0],
+    });
+    expect(results).toHaveLength(1);
+    expect(host.signalGroup).not.toHaveBeenCalled();
+    expect(launcher.child.kill).not.toHaveBeenCalled();
+    supervisor.dispose();
+  },
+);
+
+it("does not repeat verification without new launcher exit evidence", async () => {
+  const launcher = launcherChild();
+  const cleanup = vi.fn(async (): Promise<ProcessCleanupResult> => ({
+    cleaned: false,
+    reason: "process table could not be inspected: spawn EPERM",
+  }));
+  const supervisor = new ProviderProcessSupervisor({
+    process: launcher.child,
+    ownsProcessLifetime: true,
+    ownership: ownership(),
+    cleanup,
+  });
+  launcher.exit();
+  const started = performance.now();
+
+  await expect(supervisor.stop()).resolves.toMatchObject({
+    status: "incomplete",
+    reason: "process table could not be inspected: spawn EPERM",
+  });
+  expect(cleanup).toHaveBeenCalledOnce();
+  expect(performance.now() - started).toBeLessThan(500);
+});
+
+it("retains the post-exit verification failure for a later owned retry", async () => {
+  const launcher = launcherChild();
+  const outcomes: ProcessCleanupResult[] = [
+    { cleaned: false, reason: "owned launcher exit could not be confirmed" },
+    {
+      cleaned: false,
+      reason: "process ownership could not be revalidated for PID 911: EACCES",
+    },
+    { cleaned: true, signaled: true },
+  ];
+  const cleanup = vi.fn(async (): Promise<ProcessCleanupResult> => {
+    const next = outcomes.shift();
+    if (next === undefined) throw new Error("unexpected cleanup attempt");
+    if (cleanup.mock.calls.length === 1) setTimeout(() => launcher.exit(), 10);
+    return next;
+  });
+  const supervisor = new ProviderProcessSupervisor({
+    process: launcher.child,
+    ownsProcessLifetime: true,
+    ownership: ownership(),
+    cleanup,
+  });
+
+  await expect(supervisor.stop()).resolves.toMatchObject({
+    status: "incomplete",
+    reason: "process ownership could not be revalidated for PID 911: EACCES",
+  });
+  expect(cleanup).toHaveBeenCalledTimes(2);
+  await expect(supervisor.stop()).resolves.toEqual({
+    status: "verified-cleanup",
+  });
+  expect(cleanup).toHaveBeenCalledTimes(3);
+});

src/process/ProviderProcess.ts

@@ -225,6 +225,14 @@ export type ProviderProcessStopResult =
       readonly cleanupResult?: ProcessCleanupFailure;
     };
 
+const incompleteCleanup = (
+  failure: ProcessCleanupFailure,
+): ProviderProcessStopResult => ({
+  status: "incomplete",
+  reason: failure.reason,
+  cleanupResult: failure,
+});
+
 /**
  * Spawn a provider in an owned Windows job or dedicated POSIX process group.
  *
@@ -675,23 +683,24 @@ export class ProviderProcessSupervisor {
     try {
       if (!this.launch.ownsProcessLifetime) return { status: "not-owned" };
       if (this.launch.cleanup !== undefined) {
-        const cleanup = await this.#ownedCleanup(options.cleanupResult);
-        if (!cleanup.cleaned)
-          return {
-            status: "incomplete",
-            reason: cleanup.reason,
-            cleanupResult: cleanup,
-          };
         const graceMs = options.killGraceMs ?? DEFAULT_KILL_GRACE_MS;
+        const exitObservedBeforeCleanup = this.#exitObservation !== undefined;
+        const cleanup = await this.#ownedCleanup(options.cleanupResult);
+        if (!cleanup.cleaned) {
+          // Process tables can show the launcher mid-exit until verification
+          // gives up. The supervisor's own exit observation is positive proof
+          // that verification lacked, so verify again only after it arrives.
+          if (exitObservedBeforeCleanup || !(await this.waitForExit(graceMs)))
+            return incompleteCleanup(cleanup);
+          const settled = await this.launch.cleanup();
+          return settled.cleaned
+            ? { status: "verified-cleanup" }
+            : incompleteCleanup(settled);
+        }
         if (await this.waitForExit(graceMs))
           return { status: "verified-cleanup" };
         const retried = await this.launch.cleanup();
-        if (!retried.cleaned)
-          return {
-            status: "incomplete",
-            reason: retried.reason,
-            cleanupResult: retried,
-          };
+        if (!retried.cleaned) return incompleteCleanup(retried);
         if (await this.waitForExit(graceMs))
           return { status: "verified-cleanup" };
         return {

src/recordedMcpCatalog.ts

@@ -0,0 +1,27 @@
+import type {
+  Implementation,
+  Prompt,
+  ServerCapabilities,
+  Tool,
+} from "@modelcontextprotocol/server";
+import type { createCatalogIdentity } from "./catalogIdentity.js";
+import type { PromptArgumentContract } from "./contracts/promptContracts.js";
+import type { McpInputSchemaProfile } from "./config/mcpInputSchemaProfile.js";
+
+/** Build-owned discovery data; canonical validators remain the runtime authority. */
+export interface RecordedMcpCatalog {
+  readonly version: 1;
+  readonly info: Implementation;
+  readonly capabilities: ServerCapabilities;
+  readonly instructions: string;
+  readonly identity: ReturnType<typeof createCatalogIdentity>;
+  readonly tools: readonly Tool[];
+  readonly prompts: readonly (Prompt & {
+    readonly parameters: Readonly<Record<string, PromptArgumentContract>>;
+  })[];
+}
+
+/** Replaced after compilation by the recorder; source runs use eager composition. */
+export const RECORDED_MCP_CATALOG_SHA256:
+  | Readonly<Record<McpInputSchemaProfile, string>>
+  | undefined = undefined;

src/server/DeferredEvidenceMcpServer.test.ts

@@ -0,0 +1,343 @@
+import { Client, InMemoryTransport } from "@modelcontextprotocol/client";
+import type { Tool, ServerContext } from "@modelcontextprotocol/server";
+import { afterEach, expect, it, vi } from "vitest";
+import { z } from "zod";
+import type { RecordedMcpCatalog } from "../recordedMcpCatalog.js";
+import { DeferredEvidenceMcpServer } from "./DeferredEvidenceMcpServer.js";
+import { ToolResultDelivery } from "./ToolResultDelivery.js";
+import { promptArgumentsSchema } from "./promptArguments.js";
+
+const barrier = () => {
+  let release!: () => void;
+  const promise = new Promise<void>((resolve) => {
+    release = resolve;
+  });
+  return { promise, release };
+};
+const input = z.strictObject({ n: z.number().int().nonnegative().default(3) });
+const output = z.strictObject({ n: z.number().int() });
+const parameters = {
+  document: {
+    description: "Document name",
+    required: true,
+    completion: "document" as const,
+  },
+};
+const catalog: RecordedMcpCatalog = {
+  version: 1,
+  info: { name: "deferred-fixture", version: "1" },
+  instructions: "Fixture",
+  capabilities: {
+    tools: { listChanged: true },
+    prompts: { listChanged: true },
+    completions: {},
+  },
+  identity: {
+    counts: { cli_commands: 0, mcp_tools: 1, mcp_prompts: 1 },
+    digests: {
+      tools_sha256: "fixture",
+      prompts_sha256: "fixture",
+      combined_sha256: "fixture",
+    },
+  },
+  tools: [
+    {
+      name: "fixture",
+      inputSchema: z.toJSONSchema(input, {
+        io: "input",
+      }) as Tool["inputSchema"],
+      outputSchema: z.toJSONSchema(output),
+    },
+  ],
+  prompts: [
+    {
+      name: "explain",
+      title: "Explain",
+      description: "Explain a document",
+      arguments: [
+        { name: "document", description: "Document name", required: true },
+      ],
+      parameters,
+    },
+  ],
+};
+const cleanups: Array<() => Promise<unknown>> = [];
+afterEach(async () => {
+  while (cleanups.length > 0) await cleanups.pop()?.();
+});
+
+const fixture = async (
+  options: {
+    readonly hold?: ReturnType<typeof barrier>;
+    readonly failClose?: () => boolean;
+    readonly failLoad?: boolean;
+    readonly invalidOutput?: boolean;
+    readonly failAfterTool?: boolean;
+  } = {},
+) => {
+  const started = barrier();
+  const calls = vi.fn<(n: number, context: ServerContext) => void>();
+  const closed = vi.fn();
+  let loads = 0;
+  const server = new DeferredEvidenceMcpServer(
+    catalog,
+    new ToolResultDelivery(1024 * 1024),
+    async (target) => {
+      loads++;
+      target.ownRuntimeCleanup(async () => {
+        closed();
+        if (options.failClose?.()) throw new Error("cleanup denied");
+        await target.closePartialRuntime();
+      });
+      started.release();
+      await options.hold?.promise;
+      if (options.failLoad) throw new Error("PRIVATE startup cause");
+      target.materialize(() => {
+        target.registerTool(
+          "fixture",
+          { inputSchema: input, outputSchema: output },
+          async (args, context) => {
+            calls(args.n, context);
+            return {
+              content: [],
+              structuredContent: {
+                n: options.invalidOutput ? "invalid" : args.n,
+              },
+            };
+          },
+        );
+        if (options.failAfterTool)
+          throw new Error("PRIVATE partial startup failure");
+        const completion = target.bindPromptCompletion({
+          complete: async () => ["Example"],
+        });
+        target.registerCanonicalPrompt(
+          "explain",
+          {
+            title: "Explain",
+            description: "Explain a document",
+            argsSchema: promptArgumentsSchema(
+              { arguments: parameters },
+              completion,
+            ),
+          },
+          async (args) => ({
+            messages: [
+              {
+                role: "user",
+                content: { type: "text", text: String(args.document) },
+              },
+            ],
+          }),
+        );
+      });
+    },
+  );
+  const client = new Client({ name: "deferred-fixture-client", version: "1" });
+  const [clientTransport, serverTransport] =
+    InMemoryTransport.createLinkedPair();
+  await server.connect(serverTransport);
+  await client.connect(clientTransport);
+  cleanups.push(async () => {
+    await client.close();
+    await server.close();
+  });
+  return {
+    server,
+    client,
+    serverTransport,
+    started,
+    calls,
+    closed,
+    loads: () => loads,
+  };
+};
+
+it("discovers without initialization, then shares one canonical runtime and preserves request metadata", async () => {
+  const hold = barrier();
+  const f = await fixture({ hold });
+  const before = await f.client.listTools();
+  expect(before.tools).toEqual(catalog.tools);
+  expect((await f.client.listPrompts()).prompts).toEqual(
+    catalog.prompts.map(({ parameters: _parameters, ...prompt }) => prompt),
+  );
+  expect(f.loads()).toBe(0);
+  const changed = vi.fn();
+  f.client.setNotificationHandler("notifications/tools/list_changed", changed);
+  const a = f.client.callTool({
+    name: "fixture",
+    arguments: {},
+    _meta: { caller: "retained" },
+  });
+  await f.started.promise;
+  const b = f.client.callTool({ name: "fixture", arguments: { n: 7 } });
+  hold.release();
+  expect((await a).structuredContent).toEqual({ n: 3 });
+  expect((await b).structuredContent).toEqual({ n: 7 });
+  expect(f.loads()).toBe(1);
+  expect(f.calls.mock.calls[0]?.[1].mcpReq._meta?.caller).toBe("retained");
+  expect(await f.client.listTools()).toEqual(before);
+  expect(changed).not.toHaveBeenCalled();
+  const invalid = await f.client.callTool({
+    name: "fixture",
+    arguments: { n: 1.5 },
+  });
+  expect(invalid.isError).toBe(true);
+  expect(f.calls).toHaveBeenCalledTimes(2);
+});
+
+it("preserves output validation after deferred registration", async () => {
+  const f = await fixture({ invalidOutput: true });
+  const result = await f.client.callTool({ name: "fixture", arguments: {} });
+  expect(result.isError).toBe(true);
+});
+
+it("initializes through prompt retrieval or completion without an internal client", async () => {
+  const f = await fixture();
+  expect(
+    (
+      await f.client.complete({
+        ref: { type: "ref/prompt", name: "explain" },
+        argument: { name: "document", value: "Ex" },
+      })
+    ).completion.values,
+  ).toEqual(["Example"]);
+  expect(
+    (
+      await f.client.getPrompt({
+        name: "explain",
+        arguments: { document: "Example" },
+      })
+    ).messages[0]?.content,
+  ).toEqual({ type: "text", text: "Example" });
+  expect(f.loads()).toBe(1);
+});
+
+it("retrieves a prompt as the first operation", async () => {
+  const f = await fixture();
+  const result = await f.client.getPrompt({
+    name: "explain",
+    arguments: { document: "Example" },
+  });
+  expect(result.messages).toHaveLength(1);
+  expect(f.loads()).toBe(1);
+});
+
+it("does not execute a tool cancelled while canonical loading is pending", async () => {
+  const hold = barrier();
+  const f = await fixture({ hold });
+  const cancelled = barrier();
+  const previous = f.serverTransport.onmessage;
+  f.serverTransport.onmessage = (message, extra) => {
+    previous?.(message, extra);
+    if ("method" in message && message.method === "notifications/cancelled")
+      cancelled.release();
+  };
+  const controller = new AbortController();
+  const pending = f.client.callTool(
+    { name: "fixture", arguments: {} },
+    { signal: controller.signal },
+  );
+  const rejected = expect(pending).rejects.toBeDefined();
+  await f.started.promise;
+  controller.abort();
+  await cancelled.promise;
+  hold.release();
+  await rejected;
+  await f.server.ensureRuntime();
+  expect(f.calls).not.toHaveBeenCalled();
+  expect(
+    (await f.client.callTool({ name: "fixture", arguments: {} })).isError,
+  ).not.toBe(true);
+});
+
+it("keeps an independent caller alive when its peer cancels during shared loading", async () => {
+  const hold = barrier();
+  const f = await fixture({ hold });
+  const secondRequest = barrier();
+  const cancelled = barrier();
+  let toolCalls = 0;
+  const previous = f.serverTransport.onmessage;
+  f.serverTransport.onmessage = (message, extra) => {
+    previous?.(message, extra);
+    if (
+      "method" in message &&
+      message.method === "tools/call" &&
+      ++toolCalls === 2
+    )
+      secondRequest.release();
+    if ("method" in message && message.method === "notifications/cancelled")
+      cancelled.release();
+  };
+  const controller = new AbortController();
+  const a = f.client
+    .callTool({ name: "fixture", arguments: {} }, { signal: controller.signal })
+    .catch(() => undefined);
+  await f.started.promise;
+  const b = f.client.callTool({ name: "fixture", arguments: { n: 8 } });
+  await secondRequest.promise;
+  controller.abort();
+  await cancelled.promise;
+  hold.release();
+  await a;
+  expect((await b).structuredContent).toEqual({ n: 8 });
+  expect(f.calls).toHaveBeenCalledTimes(1);
+  expect(f.loads()).toBe(1);
+});
+
+it("joins late initialization during close and prevents target execution", async () => {
+  const hold = barrier();
+  const f = await fixture({ hold });
+  const pending = f.client
+    .callTool({ name: "fixture", arguments: {} })
+    .catch(() => undefined);
+  await f.started.promise;
+  const closing = f.server.close();
+  hold.release();
+  await closing;
+  await pending;
+  expect(f.calls).not.toHaveBeenCalled();
+  expect(f.closed).toHaveBeenCalledTimes(1);
+  await expect(f.server.ensureRuntime()).rejects.toThrow("closed");
+});
+
+it("retains failed cleanup for retry without loading a replacement runtime", async () => {
+  let denied = true;
+  const f = await fixture({ failClose: () => denied });
+  await f.client.callTool({ name: "fixture", arguments: {} });
+  await expect(f.server.close()).rejects.toThrow("cleanup");
+  await expect(f.server.ensureRuntime()).rejects.toThrow("closed");
+  denied = false;
+  await f.server.close();
+  expect(f.closed).toHaveBeenCalledTimes(2);
+  expect(f.loads()).toBe(1);
+});
+
+it("keeps startup failures redacted and owns partial cleanup", async () => {
+  const f = await fixture({ failLoad: true });
+  const result = await f.client.callTool({ name: "fixture", arguments: {} });
+  expect(result.isError).toBe(true);
+  expect(JSON.stringify(result)).not.toContain("PRIVATE");
+  await f.server.close();
+  expect(f.closed).toHaveBeenCalledTimes(1);
+});
+
+it("closes an unused instance without constructing the runtime", async () => {
+  const f = await fixture();
+  await f.client.listTools();
+  await f.server.close();
+  expect(f.loads()).toBe(0);
+  expect(f.closed).not.toHaveBeenCalled();
+});
+
+it("never executes a partially registered handler after initialization fails", async () => {
+  const f = await fixture({ failAfterTool: true });
+  const first = await f.client.callTool({ name: "fixture", arguments: {} });
+  const retry = await f.client.callTool({ name: "fixture", arguments: {} });
+  expect(first.isError).toBe(true);
+  expect(retry.isError).toBe(true);
+  expect(f.calls).not.toHaveBeenCalled();
+  expect(f.loads()).toBe(1);
+  await f.server.close();
+  expect(f.closed).toHaveBeenCalledTimes(1);
+});

src/server/DeferredEvidenceMcpServer.ts

@@ -0,0 +1,321 @@
+import type {
+  RegisteredTool,
+  RegisteredPrompt,
+  StandardSchemaWithJSON,
+  ToolCallback,
+  PromptCallback,
+} from "@modelcontextprotocol/server";
+import type { PromptCompletionSource } from "./promptCompletion.js";
+import type { RecordedMcpCatalog } from "../recordedMcpCatalog.js";
+import type { ToolResultDelivery } from "./toolResult.js";
+import {
+  EvidenceMcpServerCore,
+  currentMcpRequestSignal,
+  type StandardToolRegistration,
+} from "./EvidenceMcpServerCore.js";
+import { promptArgumentsSchema } from "./promptArguments.js";
+import { SERVER_START_FAILED } from "../main/messages.js";
+
+type ToolConfig = StandardToolRegistration;
+type InputCallback = ToolCallback<StandardSchemaWithJSON>;
+interface DeferredTool {
+  readonly registered: RegisteredTool;
+  readonly input: Record<string, unknown>;
+  readonly output: Record<string, unknown> | undefined;
+  callback?: InputCallback;
+}
+interface DeferredPrompt {
+  readonly registered: RegisteredPrompt;
+  callback?: PromptCallback<StandardSchemaWithJSON>;
+}
+
+/** Borrow the build-owned wire projection while retaining the canonical parser. */
+const recordedProjection = (
+  schema: StandardSchemaWithJSON,
+  projection: Record<string, unknown>,
+): StandardSchemaWithJSON => ({
+  "~standard": {
+    ...schema["~standard"],
+    jsonSchema: { input: () => projection, output: () => projection },
+  },
+});
+
+/** One SDK server, with async canonical validation installed on first use. */
+export class DeferredEvidenceMcpServer extends EvidenceMcpServerCore {
+  private readonly tools = new Map<string, DeferredTool>();
+  private readonly prompts = new Map<string, DeferredPrompt>();
+  private loading: Promise<void> | undefined;
+  private closing = false;
+  private closeAttempt: Promise<void> | undefined;
+  private protocolClosed = false;
+  private runtimeClosed = false;
+  private runtimeCleanup: (() => Promise<void>) | undefined;
+  private partialClose: (() => Promise<void>) | undefined;
+  private materializing = false;
+  private readonly protocolClose = () => super.close();
+
+  constructor(
+    catalog: RecordedMcpCatalog,
+    delivery: ToolResultDelivery,
+    private readonly initialize: (
+      server: DeferredEvidenceMcpServer,
+    ) => Promise<void>,
+  ) {
+    super(
+      catalog.info,
+      {
+        capabilities: catalog.capabilities,
+        instructions: catalog.instructions,
+      },
+      undefined,
+      delivery,
+      undefined,
+      false,
+      catalog.identity,
+    );
+    for (const tool of catalog.tools) {
+      const { name, inputSchema, outputSchema, ...metadata } = tool;
+      let binding: DeferredTool;
+      const input: StandardSchemaWithJSON = {
+        "~standard": {
+          version: 1,
+          vendor: "rea",
+          jsonSchema: { input: () => inputSchema, output: () => inputSchema },
+          validate: async (value) => {
+            await this.ensureRuntime();
+            const canonical = binding.registered.inputSchema;
+            if (canonical === undefined || canonical === input)
+              throw new Error(SERVER_START_FAILED);
+            return canonical["~standard"].validate(value);
+          },
+        },
+      };
+      const output: StandardSchemaWithJSON | undefined =
+        outputSchema === undefined
+          ? undefined
+          : {
+              "~standard": {
+                version: 1,
+                vendor: "rea",
+                jsonSchema: {
+                  input: () => outputSchema,
+                  output: () => outputSchema,
+                },
+                validate: async (value) => {
+                  await this.ensureRuntime();
+                  const canonical = binding.registered.outputSchema;
+                  if (canonical === undefined || canonical === output)
+                    throw new Error(SERVER_START_FAILED);
+                  return canonical["~standard"].validate(value);
+                },
+              },
+            };
+      const registered = super.bindTool(
+        name,
+        {
+          ...metadata,
+          inputSchema: input,
+          ...(output === undefined ? {} : { outputSchema: output }),
+        } as StandardToolRegistration,
+        (async (args, ctx) => {
+          await this.ensureRuntime();
+          ctx.mcpReq.signal.throwIfAborted();
+          if (binding.callback === undefined)
+            throw new Error(SERVER_START_FAILED);
+          return binding.callback(args, ctx);
+        }) as InputCallback,
+      );
+      binding = { registered, input: inputSchema, output: outputSchema };
+      this.tools.set(name, binding);
+    }
+    const completion = {
+      complete: async (
+        ...args: Parameters<
+          NonNullable<typeof this.promptCompletion>["complete"]
+        >
+      ) => {
+        await this.ensureRuntime();
+        currentMcpRequestSignal()?.throwIfAborted();
+        if (this.promptCompletion === undefined)
+          throw new Error(SERVER_START_FAILED);
+        return this.promptCompletion.complete(...args);
+      },
+    };
+    for (const prompt of catalog.prompts) {
+      const { name, parameters, title, description } = prompt;
+      let binding: DeferredPrompt;
+      const argsSchema = promptArgumentsSchema(
+        { arguments: parameters },
+        completion,
+      );
+      const registered = super.registerCanonicalPrompt(
+        name,
+        {
+          ...(title === undefined ? {} : { title }),
+          ...(description === undefined ? {} : { description }),
+          argsSchema,
+        },
+        async (args, ctx) => {
+          await this.ensureRuntime();
+          ctx.mcpReq.signal.throwIfAborted();
+          if (binding.callback === undefined)
+            throw new Error(SERVER_START_FAILED);
+          return binding.callback(args, ctx);
+        },
+      );
+      binding = { registered };
+      this.prompts.set(name, binding);
+    }
+  }
+
+  ensureRuntime(): Promise<void> {
+    if (this.closing)
+      return Promise.reject(new Error("MCP connection is closed"));
+    this.loading ??= Promise.resolve()
+      .then(() => this.initialize(this))
+      .catch(() => {
+        throw new Error(SERVER_START_FAILED);
+      });
+    return this.loading;
+  }
+
+  /** Register an awaitable cleanup capability before runtime startup can fail. */
+  ownRuntimeCleanup(close: () => Promise<void>): void {
+    this.runtimeCleanup = close;
+  }
+
+  /** Canonical composition may wrap close; retain that exact cleanup capability. */
+  materialize(build: () => void): void {
+    const ownedClose = this.close.bind(this);
+    this.materializing = true;
+    this.close = this.protocolClose;
+    try {
+      build();
+      if (this.tools.size !== 0 || this.prompts.size !== 0)
+        throw new Error("MCP catalog does not match runtime registrations");
+    } finally {
+      this.partialClose = this.close.bind(this);
+      this.close = ownedClose;
+      this.materializing = false;
+    }
+  }
+
+  closePartialRuntime(): Promise<void> {
+    return this.partialClose?.() ?? Promise.resolve();
+  }
+
+  protected override bindTool(
+    name: string,
+    config: ToolConfig,
+    callback: ToolCallback<StandardSchemaWithJSON | undefined>,
+  ): RegisteredTool {
+    const binding = this.tools.get(name);
+    if (
+      !this.materializing ||
+      binding === undefined ||
+      config.inputSchema === undefined ||
+      (config.outputSchema === undefined) !== (binding.output === undefined)
+    )
+      throw new Error("Unexpected MCP runtime registration");
+    const canonical = callback as InputCallback;
+    const guarded: InputCallback = async (args, ctx) => {
+      ctx.mcpReq.signal.throwIfAborted();
+      await this.ensureRuntime();
+      ctx.mcpReq.signal.throwIfAborted();
+      return canonical(args, ctx);
+    };
+    binding.callback = guarded;
+    const { inputSchema: _input, outputSchema: _output, ...metadata } = config;
+    binding.registered.update({
+      ...metadata,
+      paramsSchema: recordedProjection(config.inputSchema, binding.input),
+      ...(config.outputSchema === undefined || binding.output === undefined
+        ? {}
+        : {
+            outputSchema: recordedProjection(
+              config.outputSchema,
+              binding.output,
+            ),
+          }),
+      callback: guarded,
+    });
+    this.tools.delete(name);
+    return binding.registered;
+  }
+
+  override registerCanonicalPrompt<Args extends StandardSchemaWithJSON>(
+    name: string,
+    config: { title?: string; description?: string; argsSchema: Args },
+    callback: PromptCallback<Args>,
+  ): RegisteredPrompt {
+    const binding = this.prompts.get(name);
+    if (!this.materializing || binding === undefined)
+      throw new Error("Unexpected MCP runtime prompt");
+    const canonical = callback as PromptCallback<StandardSchemaWithJSON>;
+    binding.callback = async (args, ctx) => {
+      ctx.mcpReq.signal.throwIfAborted();
+      await this.ensureRuntime();
+      ctx.mcpReq.signal.throwIfAborted();
+      return canonical(args, ctx);
+    };
+    binding.registered.update<StandardSchemaWithJSON>({
+      ...config,
+      callback: binding.callback,
+    });
+    this.prompts.delete(name);
+    return binding.registered;
+  }
+
+  override bindPromptCompletion(
+    completion: PromptCompletionSource,
+  ): PromptCompletionSource {
+    return super.bindPromptCompletion({
+      complete: async (...args) => {
+        await this.ensureRuntime();
+        currentMcpRequestSignal()?.throwIfAborted();
+        return completion.complete(...args);
+      },
+    });
+  }
+
+  override sendToolListChanged(): void {
+    if (!this.materializing) super.sendToolListChanged();
+  }
+  override sendPromptListChanged(): void {
+    if (!this.materializing) super.sendPromptListChanged();
+  }
+
+  override close(): Promise<void> {
+    this.closing = true;
+    this.closeAttempt ??= Promise.resolve()
+      .then(() => this.finishClose())
+      .catch((cause) => {
+        this.closeAttempt = undefined;
+        throw cause;
+      });
+    return this.closeAttempt;
+  }
+
+  private async finishClose(): Promise<void> {
+    const errors: unknown[] = [];
+    if (!this.protocolClosed) {
+      try {
+        await this.protocolClose();
+        this.protocolClosed = true;
+      } catch (cause) {
+        errors.push(cause);
+      }
+    }
+    await this.loading?.catch(() => undefined);
+    if (!this.runtimeClosed && this.runtimeCleanup !== undefined) {
+      try {
+        await this.runtimeCleanup();
+        this.runtimeClosed = true;
+      } catch (cause) {
+        errors.push(cause);
+      }
+    }
+    if (errors.length > 0)
+      throw new AggregateError(errors, "MCP runtime cleanup failed");
+  }
+}

src/server/EvidenceMcpServer.ts

@@ -1,643 +1,48 @@
-import { AsyncLocalStorage } from "node:async_hooks";
-
-import {
-  isCallToolResult,
-  isJSONRPCErrorResponse,
-  isJSONRPCRequest,
-  isJSONRPCNotification,
-  isJSONRPCResultResponse,
-  type CallToolResult,
-  type Implementation,
-  type Icon,
-  type JSONRPCMessage,
-  type McpServerOptions,
-  type RegisteredTool,
-  type RequestId,
-  type ScopeChallengeHandler,
-  type StandardSchemaWithJSON,
-  type ToolAnnotations,
-  type ToolCallback,
-  type Transport,
-  type TransportSendOptions,
+import type {
+  Implementation,
+  McpServerOptions,
 } from "@modelcontextprotocol/server";
-
-import { analysisErrorProjectionSchema } from "../contracts/errorSchemas.js";
-import {
-  presentAdvertisedInputSchema,
-  type CompactInputSchemaPresentation,
-} from "../contracts/compactInputSchema.js";
+import type { EvidenceWriter } from "../application/investigation/InvestigationRecordPort.js";
 import {
   FULL_CATALOG_IDENTITY,
   createCatalogIdentity,
 } from "../catalogIdentity.js";
-import { transformAdvertisedInputJsonSchema } from "../contracts/toolSchemaMetadata.js";
-import type { EvidenceWriter } from "../application/investigation/InvestigationRecordPort.js";
+import type { ToolResultDelivery } from "./toolResult.js";
 import {
-  AnalysisInputError,
-  AnalysisResourceConstraintError,
-} from "../domain/analysisErrorCore.js";
-import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
-import { createEvidence } from "../domain/evidence.js";
-import { jsonObjectSchema, type JsonValue } from "../domain/jsonValue.js";
-import {
-  mcpResponseOverflowProjection,
-  type ToolResultDelivery,
-} from "./toolResult.js";
-import { toolReturnsTargetContent } from "../contracts/toolEffects.js";
-import {
-  carriesTargetContentMarker,
-  encodeToolResult,
-  measureMcpResultWithinBudget,
-  TARGET_CONTENT_RESULT_META,
-} from "./toolResultEncoding.js";
-import { RequestTrackingMcpServer } from "./RequestTrackingMcpServer.js";
+  EvidenceMcpServerCore,
+  type CompactInputSchemaPresentation,
+} from "./EvidenceMcpServerCore.js";
 
-export type { CompactInputSchemaPresentation } from "../contracts/compactInputSchema.js";
-
-const currentRequestSignal = new AsyncLocalStorage<AbortSignal>();
-
-/** Signal for the completion request currently being dispatched by the SDK. */
-export const currentMcpRequestSignal = (): AbortSignal | undefined =>
-  currentRequestSignal.getStore();
-
-/** A Zod schema whose standard interface exposes a JSON Schema projection. */
-const hasAdvertisedInputJsonSchema = (value: unknown): boolean => {
-  if (typeof value !== "object" || value === null) return false;
-  const standard = Reflect.get(value, "~standard");
-  if (typeof standard !== "object" || standard === null) return false;
-  const jsonSchema = Reflect.get(standard, "jsonSchema");
-  return (
-    typeof jsonSchema === "object" &&
-    jsonSchema !== null &&
-    Reflect.get(jsonSchema, "input") !== undefined
-  );
-};
-
-const isRecord = (value: unknown): value is Record<string, unknown> =>
-  typeof value === "object" && value !== null && !Array.isArray(value);
-
-/** Recognize the SDK's argument diagnostic after its wire size is checked. */
-const sdkInputValidationDiagnostic = (
-  text: string | undefined,
-  tool: string | undefined,
-): string | undefined => {
-  if (text === undefined || tool === undefined) return undefined;
-  const prefix = `Input validation error: Invalid arguments for tool ${tool}`;
-  if (!text.startsWith(prefix) || text[prefix.length] !== ":") return undefined;
-  const diagnostic = text.slice(prefix.length + 1).trimStart();
-  return diagnostic.length === 0 ? undefined : diagnostic;
-};
-
-/** Replace the tool payload after the SDK codec while retaining its envelope. */
-const replaceToolResultPayload = (
-  original: CallToolResult,
-  replacement: CallToolResult,
-): CallToolResult => {
-  const {
-    content: _content,
-    structuredContent: _structuredContent,
-    isError: _isError,
-    _meta,
-    ...envelope
-  } = original;
-  return {
-    ...envelope,
-    ...replacement,
-    ...(_meta === undefined && replacement._meta === undefined
-      ? {}
-      : { _meta: { ..._meta, ...replacement._meta } }),
-  };
-};
-
-/** Remove only client-facing output schemas; SDK registrations stay canonical. */
-const omitOutputSchemasFromToolsList = (
-  message: JSONRPCMessage,
-  requestId: RequestId,
-): JSONRPCMessage => {
-  if (
-    !isJSONRPCResultResponse(message) ||
-    message.id !== requestId ||
-    !isRecord(message.result) ||
-    !Array.isArray(message.result.tools)
-  )
-    return message;
-  return {
-    ...message,
-    result: {
-      ...message.result,
-      tools: message.result.tools.map((tool: unknown) => {
-        if (!isRecord(tool)) return tool;
-        const { outputSchema: _outputSchema, ...advertisedTool } = tool;
-        return advertisedTool;
-      }),
-    },
-  } as JSONRPCMessage;
-};
-
-/** Release every transport-owned reference for a cancelled/completed request. */
-export const forgetPendingMcpRequest = (
-  pendingTools: Map<RequestId, string>,
-  pendingToolLists: Set<RequestId>,
-  pendingCompletions: Map<RequestId, AbortController>,
-  id: RequestId,
-): void => {
-  pendingTools.delete(id);
-  pendingToolLists.delete(id);
-  pendingCompletions.get(id)?.abort();
-  pendingCompletions.delete(id);
-};
-
-/** Bind oversized MCP error recovery to this server's Evidence ledger. */
-export class EvidenceMcpServer extends RequestTrackingMcpServer {
-  readonly catalogIdentity: ReturnType<typeof createCatalogIdentity>;
-  private readonly compactPresentation:
-    | CompactInputSchemaPresentation
-    | undefined;
+export {
+  forgetPendingMcpRequest,
+  type CompactInputSchemaPresentation,
+} from "./EvidenceMcpServerCore.js";
 
+/** Canonical composition retains the constructor's existing identity defaults. */
+export class EvidenceMcpServer extends EvidenceMcpServerCore {
   constructor(
     info: Implementation,
     options: McpServerOptions,
-    private readonly recordEvidence:
-      | EvidenceWriter["recordEvidence"]
-      | undefined,
-    readonly delivery: ToolResultDelivery,
+    recordEvidence: EvidenceWriter["recordEvidence"] | undefined,
+    delivery: ToolResultDelivery,
     compactPresentation: CompactInputSchemaPresentation | undefined = undefined,
-    private readonly omitOutputSchemas = false,
+    omitOutputSchemas = false,
+    identity?: ReturnType<typeof createCatalogIdentity>,
   ) {
-    super(info, options);
-    this.compactPresentation =
-      compactPresentation === undefined
-        ? undefined
-        : { budgetBytes: compactPresentation.budgetBytes };
-    this.catalogIdentity =
-      this.compactPresentation === undefined && !this.omitOutputSchemas
-        ? FULL_CATALOG_IDENTITY
-        : createCatalogIdentity(
-            this.compactPresentation,
-            this.omitOutputSchemas ? "off" : "full",
-          );
-  }
-
-  /**
-   * Compact advertised input schemas and optionally omit output-schema
-   * advertisements. Canonical parsers and contracts remain registered; the
-   * output-schema-off path validates successful structured results locally.
-   * The signatures mirror the SDK's registrations so call sites keep their
-   * inferred handler argument types.
-   */
-  override registerTool<
-    OutputArgs extends StandardSchemaWithJSON,
-    InputArgs extends StandardSchemaWithJSON | undefined = undefined,
-  >(
-    name: string,
-    config: {
-      title?: string;
-      description?: string;
-      inputSchema?: InputArgs;
-      outputSchema?: OutputArgs;
-      annotations?: ToolAnnotations;
-      icons?: Icon[];
-      scopeChallenge?: ScopeChallengeHandler;
-      _meta?: Record<string, unknown>;
-    },
-    callback: ToolCallback<InputArgs>,
-  ): RegisteredTool {
-    const budget = this.compactPresentation?.budgetBytes;
-    const inputSchema =
-      budget !== undefined &&
-      config !== undefined &&
-      hasAdvertisedInputJsonSchema(config.inputSchema)
-        ? transformAdvertisedInputJsonSchema(
-            config.inputSchema as Parameters<
-              typeof transformAdvertisedInputJsonSchema
-            >[0],
-            (projected) =>
-              presentAdvertisedInputSchema(projected, { budgetBytes: budget }),
-          )
-        : undefined;
-    const registeredConfig =
-      inputSchema === undefined ? config : { ...config, inputSchema };
-    return super.registerTool(
-      name,
-      registeredConfig as never,
-      callback as never,
-    );
-  }
-
-  /** Preserve the SDK transport lifecycle while retaining oversized errors. */
-  override connect(transport: Transport): Promise<void> {
-    return super.connect(
-      new ErrorEvidenceTransport(
-        transport,
-        this.recordEvidence,
-        this.delivery,
-        this.omitOutputSchemas,
-      ),
+    super(
+      info,
+      options,
+      recordEvidence,
+      delivery,
+      compactPresentation,
+      omitOutputSchemas,
+      identity ??
+        (compactPresentation === undefined && !omitOutputSchemas
+          ? FULL_CATALOG_IDENTITY
+          : createCatalogIdentity(
+              compactPresentation,
+              omitOutputSchemas ? "off" : "full",
+            )),
     );
   }
 }
-
-class ErrorEvidenceTransport implements Transport {
-  onclose: Transport["onclose"];
-  onerror: Transport["onerror"];
-  onmessage: Transport["onmessage"];
-  readonly hasPerRequestStream?: boolean;
-  private readonly pendingTools = new Map<RequestId, string>();
-  private readonly pendingToolLists = new Set<RequestId>();
-  private readonly pendingCompletions = new Map<RequestId, AbortController>();
-
-  constructor(
-    private readonly transport: Transport,
-    private readonly recordEvidence:
-      | EvidenceWriter["recordEvidence"]
-      | undefined,
-    private readonly delivery: ToolResultDelivery,
-    private readonly omitOutputSchemas: boolean,
-  ) {
-    if (transport.hasPerRequestStream !== undefined)
-      this.hasPerRequestStream = transport.hasPerRequestStream;
-    transport.onmessage = (message, extra) => {
-      if (
-        isJSONRPCRequest(message) &&
-        message.method === "tools/call" &&
-        typeof message.params?.["name"] === "string"
-      )
-        this.pendingTools.set(message.id, message.params["name"]);
-      if (isJSONRPCRequest(message) && message.method === "tools/list")
-        this.pendingToolLists.add(message.id);
-      if (isJSONRPCRequest(message) && message.method === "completion/complete")
-        this.pendingCompletions.set(message.id, new AbortController());
-      // The SDK suppresses replies after cancellation, so send() cannot release
-      // this bookkeeping. Keep transport authentication outside retained data.
-      if (
-        isJSONRPCNotification(message) &&
-        message.method === "notifications/cancelled"
-      ) {
-        const id = message.params?.["requestId"];
-        if (typeof id === "string" || typeof id === "number")
-          forgetPendingMcpRequest(
-            this.pendingTools,
-            this.pendingToolLists,
-            this.pendingCompletions,
-            id,
-          );
-      }
-      const completion =
-        isJSONRPCRequest(message) && message.method === "completion/complete"
-          ? this.pendingCompletions.get(message.id)
-          : undefined;
-      if (completion === undefined) this.onmessage?.(message, extra);
-      else
-        currentRequestSignal.run(completion.signal, () =>
-          this.onmessage?.(message, extra),
-        );
-    };
-    transport.onerror = (error) => this.onerror?.(error);
-    transport.onclose = () => {
-      this.pendingTools.clear();
-      this.pendingToolLists.clear();
-      for (const completion of this.pendingCompletions.values())
-        completion.abort();
-      this.pendingCompletions.clear();
-      this.onclose?.();
-    };
-  }
-
-  get sessionId(): string | undefined {
-    return this.transport.sessionId;
-  }
-  set sessionId(value: string | undefined) {
-    this.transport.sessionId = value;
-  }
-
-  start(): Promise<void> {
-    return this.transport.start();
-  }
-
-  async close(): Promise<void> {
-    try {
-      await this.transport.close();
-    } finally {
-      this.pendingTools.clear();
-      this.pendingToolLists.clear();
-      for (const completion of this.pendingCompletions.values())
-        completion.abort();
-      this.pendingCompletions.clear();
-    }
-  }
-
-  setProtocolVersion(version: string): void {
-    this.transport.setProtocolVersion?.(version);
-  }
-
-  setSupportedProtocolVersions(versions: string[]): void {
-    this.transport.setSupportedProtocolVersions?.(versions);
-  }
-
-  async send(
-    message: JSONRPCMessage,
-    options?: TransportSendOptions,
-  ): Promise<void> {
-    const id =
-      "id" in message &&
-      (typeof message.id === "string" || typeof message.id === "number")
-        ? message.id
-        : undefined;
-    const tool = id === undefined ? undefined : this.pendingTools.get(id);
-    const omitToolSchemas =
-      this.omitOutputSchemas &&
-      id !== undefined &&
-      this.pendingToolLists.has(id);
-    try {
-      const recovered = this.recoverProtocolError(message, tool);
-      const advertised = omitToolSchemas
-        ? omitOutputSchemasFromToolsList(recovered, id)
-        : recovered;
-      if (
-        isJSONRPCResultResponse(advertised) &&
-        isCallToolResult(advertised.result) &&
-        advertised.result.isError === true
-      ) {
-        // Keep the complete typed JSON in content. Error projections are not
-        // success outputSchema data; oversized recovery must consume their
-        // private structured carrier before it is removed from the wire.
-        const { structuredContent: _diagnostic, ...result } = advertised.result;
-        // Errors the SDK builds itself (input validation, a thrown handler)
-        // bypass ToolResultDelivery; mark them for target-content tools too.
-        const marked =
-          tool !== undefined &&
-          toolReturnsTargetContent(tool) &&
-          !carriesTargetContentMarker(result)
-            ? {
-                ...result,
-                _meta: { ...result._meta, ...TARGET_CONTENT_RESULT_META },
-              }
-            : result;
-        await this.transport.send({ ...advertised, result: marked }, options);
-      } else await this.transport.send(advertised, options);
-    } finally {
-      if (!isJSONRPCRequest(message) && id !== undefined) {
-        forgetPendingMcpRequest(
-          this.pendingTools,
-          this.pendingToolLists,
-          this.pendingCompletions,
-          id,
-        );
-      }
-    }
-  }
-
-  private recoverError(
-    message: JSONRPCMessage,
-    tool: string | undefined,
-  ): JSONRPCMessage {
-    if (
-      !isJSONRPCResultResponse(message) ||
-      !isCallToolResult(message.result) ||
-      message.result.isError !== true
-    )
-      return message;
-    const budget = this.delivery.resultBudgetBytes;
-    // Count the provenance marker exactly as the projected error did, and keep
-    // it on the replacement: the retained original may hold target content.
-    const targetContent =
-      carriesTargetContentMarker(message.result) ||
-      (tool !== undefined && toolReturnsTargetContent(tool));
-    // SDK validation failures have no structured carrier. Size their existing
-    // text-only result without serializing the complete JSON-RPC message.
-    const isStructured = message.result.structuredContent !== undefined;
-    const structured = isStructured
-      ? jsonObjectSchema.parse(message.result.structuredContent)
-      : undefined;
-    const sdkResultWithMarker =
-      !isStructured &&
-      targetContent &&
-      !carriesTargetContentMarker(message.result)
-        ? {
-            ...message.result,
-            _meta: {
-              ...message.result._meta,
-              ...TARGET_CONTENT_RESULT_META,
-            },
-          }
-        : message.result;
-    const sdkDiagnostic = !isStructured
-      ? message.result.content.find((item) => item.type === "text")?.text
-      : undefined;
-    let encoded =
-      structured !== undefined
-        ? encodeToolResult(structured, budget, "error-text", targetContent)
-        : measureMcpResultWithinBudget(sdkResultWithMarker, budget);
-    const normalized = encoded.ok
-      ? this.normalizeSdkValidationError(
-          message,
-          tool,
-          targetContent,
-          sdkInputValidationDiagnostic(sdkDiagnostic, tool),
-        )
-      : undefined;
-    if (
-      normalized !== undefined &&
-      isJSONRPCResultResponse(normalized) &&
-      isCallToolResult(normalized.result)
-    ) {
-      // The structured diagnostic is a private carrier removed before sending.
-      // Measure the actual wire result, including its preserved SDK metadata.
-      const { structuredContent, ...wireResult } = normalized.result;
-      encoded =
-        normalized.result.content.length === 0
-          ? encodeToolResult(
-              jsonObjectSchema.parse(structuredContent),
-              budget,
-              "error-text",
-              targetContent,
-            )
-          : measureMcpResultWithinBudget(wireResult, budget);
-      if (encoded.ok) return normalized;
-      // JSON escaping and recovery fields can exceed the budget even when
-      // the original SDK result fits. Retain that original before replacing it.
-    }
-    if (encoded.ok) return message;
-    const operation = tool ?? "mcp_tool_error";
-    const originalResult = jsonObjectSchema.parse(message.result);
-    const retainedResult = structured ?? originalResult;
-    const originalError = isStructured
-      ? analysisErrorProjectionSchema.safeParse(structured?.["error"])
-      : undefined;
-    // Retain the complete original response, including SDK validation text.
-    // The SDK error contains its rendered issue, not a separate argument bag;
-    // transport authentication and caller arguments are never added here.
-    const evidence = createEvidence(
-      undefined,
-      { id: "rea-mcp", name: "REA MCP delivery", version: "1" },
-      {
-        operation: "mcp_tool_error",
-        parameters: { tool_name: operation },
-        result:
-          sdkDiagnostic === undefined
-            ? retainedResult
-            : {
-                boundary: "sdk-input-validation",
-                diagnostic_preview: sdkDiagnostic.slice(0, 256),
-                diagnostic_truncated: sdkDiagnostic.length > 256,
-              },
-        rawResult: originalResult,
-      },
-    );
-    const recorded = this.recordEvidence?.(evidence);
-    const retained = recorded !== undefined && recorded.ok;
-    const projected = mcpResponseOverflowProjection({
-      completed: false,
-      constraint: encoded.constraint,
-      effectiveResponseBytes: this.delivery.maximumResponseBytes,
-      nextStep: retained
-        ? "Export the retained original error through export_evidence_bundle to a caller-selected path. The connection remains usable."
-        : encoded.constraint === "string-length"
-          ? "The original error could not be retained by this server. Use complete CLI JSON output when the analysis completed. Repeating the unchanged MCP call fails the same way."
-          : "The original error could not be retained by this server. Restart REA with a larger REA_MCP_MAX_RESPONSE_BYTES and a matching client receive buffer, then retry.",
-    });
-    const replacement = this.transportConstraintResult(
-      operation,
-      projected.reason,
-      projected.remediationAction,
-      {
-        boundary: "mcp-response",
-        ...(originalError?.success
-          ? { original_error_code: originalError.data.code }
-          : {}),
-        result_budget_bytes: budget,
-        response_bytes_at_least: encoded.bytesAtLeast,
-        constraint: encoded.constraint,
-        ...(sdkDiagnostic === undefined
-          ? {}
-          : {
-              diagnostic_preview: sdkDiagnostic.slice(0, 256),
-              diagnostic_truncated: sdkDiagnostic.length > 256,
-            }),
-        ...(retained
-          ? {
-              evidence_reference: {
-                kind: "retained-evidence",
-                evidence_id: evidence.evidence_id,
-              },
-            }
-          : { retention: recorded === undefined ? "unavailable" : "failed" }),
-        ...(recorded !== undefined && !recorded.ok
-          ? { retention_error: projectAnalysisError(recorded.error) }
-          : {}),
-      },
-      targetContent,
-    );
-    return {
-      ...message,
-      result: replaceToolResultPayload(message.result, replacement),
-    };
-  }
-
-  /**
-   * Encode a transport-constraint error inside the MCP text budget.
-   * The complete SDK diagnostic stays in retained Evidence. Its character
-   * preview can still expand past the budget when quotes and backslashes are
-   * escaped into that text, so shorten only the preview and keep the reference.
-   */
-  private transportConstraintResult(
-    operation: string,
-    reason: string,
-    remediationAction: string,
-    limits: Readonly<Record<string, JsonValue>>,
-    targetContent: boolean,
-  ): CallToolResult {
-    const deliver = (
-      reportedLimits: Readonly<Record<string, JsonValue>>,
-    ): CallToolResult =>
-      this.delivery.toErrorToolResult(
-        new AnalysisResourceConstraintError(
-          operation,
-          "transport",
-          reason,
-          reportedLimits,
-          { remediationAction },
-        ),
-        targetContent,
-      );
-    const delivered = deliver(limits);
-    const preview = limits.diagnostic_preview;
-    if (delivered.content.length > 0 || typeof preview !== "string")
-      return delivered;
-    let low = 0;
-    let high = preview.length - 1;
-    let fitted: CallToolResult | undefined;
-    let fittedLength = -1;
-    while (low <= high) {
-      const length = Math.floor((low + high) / 2);
-      const candidate = deliver({
-        ...limits,
-        diagnostic_preview: preview.slice(0, length),
-        diagnostic_truncated: true,
-      });
-      if (candidate.content.length > 0) {
-        fitted = candidate;
-        fittedLength = length;
-        low = length + 1;
-      } else high = length - 1;
-    }
-    if (fitted !== undefined && fittedLength > 0) return fitted;
-    const { diagnostic_preview: _preview, ...withoutPreview } = limits;
-    const omitted = deliver({
-      ...withoutPreview,
-      diagnostic_truncated: preview.length > 0,
-    });
-    return omitted.content.length > 0 || fitted === undefined
-      ? omitted
-      : fitted;
-  }
-
-  private normalizeSdkValidationError(
-    message: JSONRPCMessage,
-    tool: string | undefined,
-    targetContent: boolean,
-    diagnostic: string | undefined,
-  ): JSONRPCMessage | undefined {
-    if (
-      tool === undefined ||
-      diagnostic === undefined ||
-      !isJSONRPCResultResponse(message) ||
-      !isCallToolResult(message.result)
-    )
-      return undefined;
-    const error = new AnalysisInputError(
-      tool,
-      {
-        userMessage: `The arguments for MCP tool ${tool} do not match its advertised input schema.`,
-      },
-      [{ path: [], reason: "invalid_value", message: diagnostic }],
-    );
-    const result = this.delivery.toErrorToolResult(error, targetContent);
-    return {
-      ...message,
-      result: replaceToolResultPayload(message.result, result),
-    };
-  }
-
-  private recoverProtocolError(
-    message: JSONRPCMessage,
-    tool: string | undefined,
-  ): JSONRPCMessage {
-    const recovered = this.recoverError(message, tool);
-    if (
-      !isJSONRPCErrorResponse(recovered) ||
-      tool === undefined ||
-      recovered.error.code !== -32602 ||
-      recovered.error.message !== `Tool ${tool} not found`
-    )
-      return recovered;
-    return {
-      ...recovered,
-      error: {
-        ...recovered.error,
-        message:
-          "The requested MCP tool is not advertised by this REA server. Call tools/list, select an advertised tool, and retry; do not repeat the unknown tool name.",
-      },
-    };
-  }
-}

src/server/EvidenceMcpServerCore.ts

@@ -0,0 +1,699 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+
+import {
+  isCallToolResult,
+  isJSONRPCErrorResponse,
+  isJSONRPCRequest,
+  isJSONRPCNotification,
+  isJSONRPCResultResponse,
+  type CallToolResult,
+  type Implementation,
+  type Icon,
+  type JSONRPCMessage,
+  type McpServerOptions,
+  type RegisteredTool,
+  type RegisteredPrompt,
+  type PromptCallback,
+  type RequestId,
+  type ScopeChallengeHandler,
+  type StandardSchemaWithJSON,
+  type ToolAnnotations,
+  type ToolCallback,
+  type Transport,
+  type TransportSendOptions,
+} from "@modelcontextprotocol/server";
+
+import { analysisErrorProjectionSchema } from "../contracts/errorSchemas.js";
+import {
+  presentAdvertisedInputSchema,
+  type CompactInputSchemaPresentation,
+} from "../contracts/compactInputSchema.js";
+import type { createCatalogIdentity } from "../catalogIdentity.js";
+import { transformAdvertisedInputJsonSchema } from "../contracts/toolSchemaMetadata.js";
+import type { EvidenceWriter } from "../application/investigation/InvestigationRecordPort.js";
+import {
+  AnalysisInputError,
+  AnalysisResourceConstraintError,
+} from "../domain/analysisErrorCore.js";
+import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
+import { createEvidence } from "../domain/evidence.js";
+import { jsonObjectSchema, type JsonValue } from "../domain/jsonValue.js";
+import {
+  mcpResponseOverflowProjection,
+  type ToolResultDelivery,
+} from "./ToolResultDelivery.js";
+import { toolReturnsTargetContent } from "../contracts/toolEffects.js";
+import {
+  carriesTargetContentMarker,
+  encodeToolResult,
+  measureMcpResultWithinBudget,
+  TARGET_CONTENT_RESULT_META,
+} from "./toolResultEncoding.js";
+import { RequestTrackingMcpServer } from "./RequestTrackingMcpServer.js";
+
+export type { CompactInputSchemaPresentation } from "../contracts/compactInputSchema.js";
+
+const currentRequestSignal = new AsyncLocalStorage<AbortSignal>();
+
+/** Signal for the completion request currently being dispatched by the SDK. */
+export const currentMcpRequestSignal = (): AbortSignal | undefined =>
+  currentRequestSignal.getStore();
+
+/** A Zod schema whose standard interface exposes a JSON Schema projection. */
+const hasAdvertisedInputJsonSchema = (value: unknown): boolean => {
+  if (typeof value !== "object" || value === null) return false;
+  const standard = Reflect.get(value, "~standard");
+  if (typeof standard !== "object" || standard === null) return false;
+  const jsonSchema = Reflect.get(standard, "jsonSchema");
+  return (
+    typeof jsonSchema === "object" &&
+    jsonSchema !== null &&
+    Reflect.get(jsonSchema, "input") !== undefined
+  );
+};
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+/** Recognize the SDK's argument diagnostic after its wire size is checked. */
+const sdkInputValidationDiagnostic = (
+  text: string | undefined,
+  tool: string | undefined,
+): string | undefined => {
+  if (text === undefined || tool === undefined) return undefined;
+  const prefix = `Input validation error: Invalid arguments for tool ${tool}`;
+  if (!text.startsWith(prefix) || text[prefix.length] !== ":") return undefined;
+  const diagnostic = text.slice(prefix.length + 1).trimStart();
+  return diagnostic.length === 0 ? undefined : diagnostic;
+};
+
+/** Replace the tool payload after the SDK codec while retaining its envelope. */
+const replaceToolResultPayload = (
+  original: CallToolResult,
+  replacement: CallToolResult,
+): CallToolResult => {
+  const {
+    content: _content,
+    structuredContent: _structuredContent,
+    isError: _isError,
+    _meta,
+    ...envelope
+  } = original;
+  return {
+    ...envelope,
+    ...replacement,
+    ...(_meta === undefined && replacement._meta === undefined
+      ? {}
+      : { _meta: { ..._meta, ...replacement._meta } }),
+  };
+};
+
+/** Remove only client-facing output schemas; SDK registrations stay canonical. */
+const omitOutputSchemasFromToolsList = (
+  message: JSONRPCMessage,
+  requestId: RequestId,
+): JSONRPCMessage => {
+  if (
+    !isJSONRPCResultResponse(message) ||
+    message.id !== requestId ||
+    !isRecord(message.result) ||
+    !Array.isArray(message.result.tools)
+  )
+    return message;
+  return {
+    ...message,
+    result: {
+      ...message.result,
+      tools: message.result.tools.map((tool: unknown) => {
+        if (!isRecord(tool)) return tool;
+        const { outputSchema: _outputSchema, ...advertisedTool } = tool;
+        return advertisedTool;
+      }),
+    },
+  } as JSONRPCMessage;
+};
+
+/** Release every transport-owned reference for a cancelled/completed request. */
+export const forgetPendingMcpRequest = (
+  pendingTools: Map<RequestId, string>,
+  pendingToolLists: Set<RequestId>,
+  pendingCompletions: Map<RequestId, AbortController>,
+  id: RequestId,
+): void => {
+  pendingTools.delete(id);
+  pendingToolLists.delete(id);
+  pendingCompletions.get(id)?.abort();
+  pendingCompletions.delete(id);
+};
+import type { PromptCompletionSource } from "./promptCompletion.js";
+
+/** Standard-schema registration boundary shared with deferred SDK bindings. */
+export interface StandardToolRegistration {
+  readonly title?: string;
+  readonly description?: string;
+  readonly inputSchema?: StandardSchemaWithJSON;
+  readonly outputSchema?: StandardSchemaWithJSON;
+  readonly annotations?: ToolAnnotations;
+  readonly icons?: Icon[];
+  readonly scopeChallenge?: ScopeChallengeHandler;
+  readonly _meta?: Record<string, unknown>;
+}
+
+/** Bind oversized MCP error recovery to this server's Evidence ledger. */
+export class EvidenceMcpServerCore extends RequestTrackingMcpServer {
+  private identity: ReturnType<typeof createCatalogIdentity> | undefined;
+
+  /** Composition supplies identity without importing the canonical schema graph. */
+  get catalogIdentity(): ReturnType<typeof createCatalogIdentity> {
+    if (this.identity === undefined)
+      throw new Error("MCP catalog identity has not been configured");
+    return this.identity;
+  }
+
+  /** Attach the process-owned session only after lazy runtime construction. */
+  attachRuntime(
+    recordEvidence: EvidenceWriter["recordEvidence"] | undefined,
+    delivery: ToolResultDelivery,
+    identity: ReturnType<typeof createCatalogIdentity>,
+  ): void {
+    if (
+      this.identity !== undefined &&
+      this.identity.digests.combined_sha256 !== identity.digests.combined_sha256
+    )
+      throw new Error("MCP catalog identity does not match runtime");
+    this.recordEvidence = recordEvidence;
+    this.delivery = delivery;
+    this.identity = identity;
+  }
+
+  protected promptCompletion: PromptCompletionSource | undefined;
+  bindPromptCompletion(
+    completion: PromptCompletionSource,
+  ): PromptCompletionSource {
+    this.promptCompletion = completion;
+    return completion;
+  }
+
+  registerCanonicalPrompt<Args extends StandardSchemaWithJSON>(
+    name: string,
+    config: { title?: string; description?: string; argsSchema: Args },
+    callback: PromptCallback<Args>,
+  ): RegisteredPrompt {
+    return super.registerPrompt(name, config, callback);
+  }
+  private readonly compactPresentation:
+    | CompactInputSchemaPresentation
+    | undefined;
+
+  constructor(
+    info: Implementation,
+    options: McpServerOptions,
+    private recordEvidence: EvidenceWriter["recordEvidence"] | undefined,
+    public delivery: ToolResultDelivery,
+    compactPresentation: CompactInputSchemaPresentation | undefined = undefined,
+    private readonly omitOutputSchemas = false,
+    identity?: ReturnType<typeof createCatalogIdentity>,
+  ) {
+    super(info, options);
+    this.compactPresentation =
+      compactPresentation === undefined
+        ? undefined
+        : { budgetBytes: compactPresentation.budgetBytes };
+    this.identity = identity;
+  }
+
+  /**
+   * Compact advertised input schemas and optionally omit output-schema
+   * advertisements. Canonical parsers and contracts remain registered; the
+   * output-schema-off path validates successful structured results locally.
+   * The signatures mirror the SDK's registrations so call sites keep their
+   * inferred handler argument types.
+   */
+  override registerTool<
+    OutputArgs extends StandardSchemaWithJSON,
+    InputArgs extends StandardSchemaWithJSON | undefined = undefined,
+  >(
+    name: string,
+    config: {
+      title?: string;
+      description?: string;
+      inputSchema?: InputArgs;
+      outputSchema?: OutputArgs;
+      annotations?: ToolAnnotations;
+      icons?: Icon[];
+      scopeChallenge?: ScopeChallengeHandler;
+      _meta?: Record<string, unknown>;
+    },
+    callback: ToolCallback<InputArgs>,
+  ): RegisteredTool {
+    const budget = this.compactPresentation?.budgetBytes;
+    const inputSchema =
+      budget !== undefined &&
+      config !== undefined &&
+      hasAdvertisedInputJsonSchema(config.inputSchema)
+        ? transformAdvertisedInputJsonSchema(
+            config.inputSchema as Parameters<
+              typeof transformAdvertisedInputJsonSchema
+            >[0],
+            (projected) =>
+              presentAdvertisedInputSchema(projected, { budgetBytes: budget }),
+          )
+        : undefined;
+    const registeredConfig =
+      inputSchema === undefined ? config : { ...config, inputSchema };
+    return this.bindTool(name, registeredConfig as never, callback as never);
+  }
+
+  protected bindTool(
+    name: string,
+    config: StandardToolRegistration,
+    callback: ToolCallback<StandardSchemaWithJSON | undefined>,
+  ): RegisteredTool {
+    return super.registerTool(name, config as never, callback as never);
+  }
+
+  /** Preserve the SDK transport lifecycle while retaining oversized errors. */
+  override connect(transport: Transport): Promise<void> {
+    return super.connect(
+      new ErrorEvidenceTransport(
+        transport,
+        () => this.recordEvidence,
+        () => this.delivery,
+        this.omitOutputSchemas,
+      ),
+    );
+  }
+}
+
+class ErrorEvidenceTransport implements Transport {
+  onclose: Transport["onclose"];
+  onerror: Transport["onerror"];
+  onmessage: Transport["onmessage"];
+  readonly hasPerRequestStream?: boolean;
+  private readonly pendingTools = new Map<RequestId, string>();
+  private readonly pendingToolLists = new Set<RequestId>();
+  private readonly pendingCompletions = new Map<RequestId, AbortController>();
+
+  private get recordEvidence(): EvidenceWriter["recordEvidence"] | undefined {
+    return this.currentEvidenceWriter();
+  }
+
+  private get delivery(): ToolResultDelivery {
+    return this.currentDelivery();
+  }
+
+  constructor(
+    private readonly transport: Transport,
+    private readonly currentEvidenceWriter: () =>
+      | EvidenceWriter["recordEvidence"]
+      | undefined,
+    private readonly currentDelivery: () => ToolResultDelivery,
+    private readonly omitOutputSchemas: boolean,
+  ) {
+    if (transport.hasPerRequestStream !== undefined)
+      this.hasPerRequestStream = transport.hasPerRequestStream;
+    transport.onmessage = (message, extra) => {
+      if (
+        isJSONRPCRequest(message) &&
+        message.method === "tools/call" &&
+        typeof message.params?.["name"] === "string"
+      )
+        this.pendingTools.set(message.id, message.params["name"]);
+      if (isJSONRPCRequest(message) && message.method === "tools/list")
+        this.pendingToolLists.add(message.id);
+      if (isJSONRPCRequest(message) && message.method === "completion/complete")
+        this.pendingCompletions.set(message.id, new AbortController());
+      // The SDK suppresses replies after cancellation, so send() cannot release
+      // this bookkeeping. Keep transport authentication outside retained data.
+      if (
+        isJSONRPCNotification(message) &&
+        message.method === "notifications/cancelled"
+      ) {
+        const id = message.params?.["requestId"];
+        if (typeof id === "string" || typeof id === "number")
+          forgetPendingMcpRequest(
+            this.pendingTools,
+            this.pendingToolLists,
+            this.pendingCompletions,
+            id,
+          );
+      }
+      const completion =
+        isJSONRPCRequest(message) && message.method === "completion/complete"
+          ? this.pendingCompletions.get(message.id)
+          : undefined;
+      if (completion === undefined) this.onmessage?.(message, extra);
+      else
+        currentRequestSignal.run(completion.signal, () =>
+          this.onmessage?.(message, extra),
+        );
+    };
+    transport.onerror = (error) => this.onerror?.(error);
+    transport.onclose = () => {
+      this.pendingTools.clear();
+      this.pendingToolLists.clear();
+      for (const completion of this.pendingCompletions.values())
+        completion.abort();
+      this.pendingCompletions.clear();
+      this.onclose?.();
+    };
+  }
+
+  get sessionId(): string | undefined {
+    return this.transport.sessionId;
+  }
+  set sessionId(value: string | undefined) {
+    this.transport.sessionId = value;
+  }
+
+  start(): Promise<void> {
+    return this.transport.start();
+  }
+
+  async close(): Promise<void> {
+    try {
+      await this.transport.close();
+    } finally {
+      this.pendingTools.clear();
+      this.pendingToolLists.clear();
+      for (const completion of this.pendingCompletions.values())
+        completion.abort();
+      this.pendingCompletions.clear();
+    }
+  }
+
+  setProtocolVersion(version: string): void {
+    this.transport.setProtocolVersion?.(version);
+  }
+
+  setSupportedProtocolVersions(versions: string[]): void {
+    this.transport.setSupportedProtocolVersions?.(versions);
+  }
+
+  async send(
+    message: JSONRPCMessage,
+    options?: TransportSendOptions,
+  ): Promise<void> {
+    const id =
+      "id" in message &&
+      (typeof message.id === "string" || typeof message.id === "number")
+        ? message.id
+        : undefined;
+    const tool = id === undefined ? undefined : this.pendingTools.get(id);
+    const omitToolSchemas =
+      this.omitOutputSchemas &&
+      id !== undefined &&
+      this.pendingToolLists.has(id);
+    try {
+      const recovered = this.recoverProtocolError(message, tool);
+      const advertised = omitToolSchemas
+        ? omitOutputSchemasFromToolsList(recovered, id)
+        : recovered;
+      if (
+        isJSONRPCResultResponse(advertised) &&
+        isCallToolResult(advertised.result) &&
+        advertised.result.isError === true
+      ) {
+        // Keep the complete typed JSON in content. Error projections are not
+        // success outputSchema data; oversized recovery must consume their
+        // private structured carrier before it is removed from the wire.
+        const { structuredContent: _diagnostic, ...result } = advertised.result;
+        // Errors the SDK builds itself (input validation, a thrown handler)
+        // bypass ToolResultDelivery; mark them for target-content tools too.
+        const marked =
+          tool !== undefined &&
+          toolReturnsTargetContent(tool) &&
+          !carriesTargetContentMarker(result)
+            ? {
+                ...result,
+                _meta: { ...result._meta, ...TARGET_CONTENT_RESULT_META },
+              }
+            : result;
+        await this.transport.send({ ...advertised, result: marked }, options);
+      } else await this.transport.send(advertised, options);
+    } finally {
+      if (!isJSONRPCRequest(message) && id !== undefined) {
+        forgetPendingMcpRequest(
+          this.pendingTools,
+          this.pendingToolLists,
+          this.pendingCompletions,
+          id,
+        );
+      }
+    }
+  }
+
+  private recoverError(
+    message: JSONRPCMessage,
+    tool: string | undefined,
+  ): JSONRPCMessage {
+    if (
+      !isJSONRPCResultResponse(message) ||
+      !isCallToolResult(message.result) ||
+      message.result.isError !== true
+    )
+      return message;
+    const budget = this.delivery.resultBudgetBytes;
+    // Count the provenance marker exactly as the projected error did, and keep
+    // it on the replacement: the retained original may hold target content.
+    const targetContent =
+      carriesTargetContentMarker(message.result) ||
+      (tool !== undefined && toolReturnsTargetContent(tool));
+    // SDK validation failures have no structured carrier. Size their existing
+    // text-only result without serializing the complete JSON-RPC message.
+    const isStructured = message.result.structuredContent !== undefined;
+    const structured = isStructured
+      ? jsonObjectSchema.parse(message.result.structuredContent)
+      : undefined;
+    const sdkResultWithMarker =
+      !isStructured &&
+      targetContent &&
+      !carriesTargetContentMarker(message.result)
+        ? {
+            ...message.result,
+            _meta: {
+              ...message.result._meta,
+              ...TARGET_CONTENT_RESULT_META,
+            },
+          }
+        : message.result;
+    const sdkDiagnostic = !isStructured
+      ? message.result.content.find((item) => item.type === "text")?.text
+      : undefined;
+    let encoded =
+      structured !== undefined
+        ? encodeToolResult(structured, budget, "error-text", targetContent)
+        : measureMcpResultWithinBudget(sdkResultWithMarker, budget);
+    const normalized = encoded.ok
+      ? this.normalizeSdkValidationError(
+          message,
+          tool,
+          targetContent,
+          sdkInputValidationDiagnostic(sdkDiagnostic, tool),
+        )
+      : undefined;
+    if (
+      normalized !== undefined &&
+      isJSONRPCResultResponse(normalized) &&
+      isCallToolResult(normalized.result)
+    ) {
+      // The structured diagnostic is a private carrier removed before sending.
+      // Measure the actual wire result, including its preserved SDK metadata.
+      const { structuredContent, ...wireResult } = normalized.result;
+      encoded =
+        normalized.result.content.length === 0
+          ? encodeToolResult(
+              jsonObjectSchema.parse(structuredContent),
+              budget,
+              "error-text",
+              targetContent,
+            )
+          : measureMcpResultWithinBudget(wireResult, budget);
+      if (encoded.ok) return normalized;
+      // JSON escaping and recovery fields can exceed the budget even when
+      // the original SDK result fits. Retain that original before replacing it.
+    }
+    if (encoded.ok) return message;
+    const operation = tool ?? "mcp_tool_error";
+    const originalResult = jsonObjectSchema.parse(message.result);
+    const retainedResult = structured ?? originalResult;
+    const originalError = isStructured
+      ? analysisErrorProjectionSchema.safeParse(structured?.["error"])
+      : undefined;
+    // Retain the complete original response, including SDK validation text.
+    // The SDK error contains its rendered issue, not a separate argument bag;
+    // transport authentication and caller arguments are never added here.
+    const evidence = createEvidence(
+      undefined,
+      { id: "rea-mcp", name: "REA MCP delivery", version: "1" },
+      {
+        operation: "mcp_tool_error",
+        parameters: { tool_name: operation },
+        result:
+          sdkDiagnostic === undefined
+            ? retainedResult
+            : {
+                boundary: "sdk-input-validation",
+                diagnostic_preview: sdkDiagnostic.slice(0, 256),
+                diagnostic_truncated: sdkDiagnostic.length > 256,
+              },
+        rawResult: originalResult,
+      },
+    );
+    const recorded = this.recordEvidence?.(evidence);
+    const retained = recorded !== undefined && recorded.ok;
+    const projected = mcpResponseOverflowProjection({
+      completed: false,
+      constraint: encoded.constraint,
+      effectiveResponseBytes: this.delivery.maximumResponseBytes,
+      nextStep: retained
+        ? "Export the retained original error through export_evidence_bundle to a caller-selected path. The connection remains usable."
+        : encoded.constraint === "string-length"
+          ? "The original error could not be retained by this server. Use complete CLI JSON output when the analysis completed. Repeating the unchanged MCP call fails the same way."
+          : "The original error could not be retained by this server. Restart REA with a larger REA_MCP_MAX_RESPONSE_BYTES and a matching client receive buffer, then retry.",
+    });
+    const replacement = this.transportConstraintResult(
+      operation,
+      projected.reason,
+      projected.remediationAction,
+      {
+        boundary: "mcp-response",
+        ...(originalError?.success
+          ? { original_error_code: originalError.data.code }
+          : {}),
+        result_budget_bytes: budget,
+        response_bytes_at_least: encoded.bytesAtLeast,
+        constraint: encoded.constraint,
+        ...(sdkDiagnostic === undefined
+          ? {}
+          : {
+              diagnostic_preview: sdkDiagnostic.slice(0, 256),
+              diagnostic_truncated: sdkDiagnostic.length > 256,
+            }),
+        ...(retained
+          ? {
+              evidence_reference: {
+                kind: "retained-evidence",
+                evidence_id: evidence.evidence_id,
+              },
+            }
+          : { retention: recorded === undefined ? "unavailable" : "failed" }),
+        ...(recorded !== undefined && !recorded.ok
+          ? { retention_error: projectAnalysisError(recorded.error) }
+          : {}),
+      },
+      targetContent,
+    );
+    return {
+      ...message,
+      result: replaceToolResultPayload(message.result, replacement),
+    };
+  }
+
+  /**
+   * Encode a transport-constraint error inside the MCP text budget.
+   * The complete SDK diagnostic stays in retained Evidence. Its character
+   * preview can still expand past the budget when quotes and backslashes are
+   * escaped into that text, so shorten only the preview and keep the reference.
+   */
+  private transportConstraintResult(
+    operation: string,
+    reason: string,
+    remediationAction: string,
+    limits: Readonly<Record<string, JsonValue>>,
+    targetContent: boolean,
+  ): CallToolResult {
+    const deliver = (
+      reportedLimits: Readonly<Record<string, JsonValue>>,
+    ): CallToolResult =>
+      this.delivery.toErrorToolResult(
+        new AnalysisResourceConstraintError(
+          operation,
+          "transport",
+          reason,
+          reportedLimits,
+          { remediationAction },
+        ),
+        targetContent,
+      );
+    const delivered = deliver(limits);
+    const preview = limits.diagnostic_preview;
+    if (delivered.content.length > 0 || typeof preview !== "string")
+      return delivered;
+    let low = 0;
+    let high = preview.length - 1;
+    let fitted: CallToolResult | undefined;
+    let fittedLength = -1;
+    while (low <= high) {
+      const length = Math.floor((low + high) / 2);
+      const candidate = deliver({
+        ...limits,
+        diagnostic_preview: preview.slice(0, length),
+        diagnostic_truncated: true,
+      });
+      if (candidate.content.length > 0) {
+        fitted = candidate;
+        fittedLength = length;
+        low = length + 1;
+      } else high = length - 1;
+    }
+    if (fitted !== undefined && fittedLength > 0) return fitted;
+    const { diagnostic_preview: _preview, ...withoutPreview } = limits;
+    const omitted = deliver({
+      ...withoutPreview,
+      diagnostic_truncated: preview.length > 0,
+    });
+    return omitted.content.length > 0 || fitted === undefined
+      ? omitted
+      : fitted;
+  }
+
+  private normalizeSdkValidationError(
+    message: JSONRPCMessage,
+    tool: string | undefined,
+    targetContent: boolean,
+    diagnostic: string | undefined,
+  ): JSONRPCMessage | undefined {
+    if (
+      tool === undefined ||
+      diagnostic === undefined ||
+      !isJSONRPCResultResponse(message) ||
+      !isCallToolResult(message.result)
+    )
+      return undefined;
+    const error = new AnalysisInputError(
+      tool,
+      {
+        userMessage: `The arguments for MCP tool ${tool} do not match its advertised input schema.`,
+      },
+      [{ path: [], reason: "invalid_value", message: diagnostic }],
+    );
+    const result = this.delivery.toErrorToolResult(error, targetContent);
+    return {
+      ...message,
+      result: replaceToolResultPayload(message.result, result),
+    };
+  }
+
+  private recoverProtocolError(
+    message: JSONRPCMessage,
+    tool: string | undefined,
+  ): JSONRPCMessage {
+    const recovered = this.recoverError(message, tool);
+    if (
+      !isJSONRPCErrorResponse(recovered) ||
+      tool === undefined ||
+      recovered.error.code !== -32602 ||
+      recovered.error.message !== `Tool ${tool} not found`
+    )
+      return recovered;
+    return {
+      ...recovered,
+      error: {
+        ...recovered.error,
+        message:
+          "The requested MCP tool is not advertised by this REA server. Call tools/list, select an advertised tool, and retry; do not repeat the unknown tool name.",
+      },
+    };
+  }
+}

src/server/ToolResultDelivery.ts

@@ -0,0 +1,250 @@
+import type { CallToolResult } from "@modelcontextprotocol/server";
+import { STDIO_DEFAULT_MAX_BUFFER_SIZE } from "@modelcontextprotocol/server";
+
+import type { ToolContract } from "../contracts/toolContractTypes.js";
+import type { Evidence } from "../domain/evidence.js";
+import {
+  projectAnalysisError,
+  type AnalysisErrorProjection,
+} from "../domain/analysisErrorProjection.js";
+import type { AnalysisError } from "../domain/analysisErrorBase.js";
+import { jsonValueSchema, type JsonValue } from "../domain/jsonValue.js";
+import type { Result } from "../domain/result.js";
+import { AnalysisResourceConstraintError } from "../domain/analysisErrorCore.js";
+import {
+  MCP_TRANSPORT_EVIDENCE_DISCOVERY,
+  MCP_TRANSPORT_EVIDENCE_EXPORT,
+} from "../domain/analysisErrorPresentation.js";
+import {
+  nodeStringCeilingRecovery,
+  stdioResponseBudgetRecovery,
+} from "../config/mcpResponseBudget.js";
+import {
+  encodeToolResult,
+  MCP_RESULT_STRING_LIMIT,
+  NODE_MAX_STRING_LENGTH,
+  TARGET_CONTENT_RESULT_META,
+} from "./toolResultEncoding.js";
+
+/** Project a response-budget refusal without labeling REA's reserved string limit as Node's ceiling. */
+export const mcpResponseOverflowProjection = (input: {
+  readonly completed: boolean;
+  readonly constraint: "receive-buffer" | "string-length";
+  readonly effectiveResponseBytes: number;
+  readonly nextStep: string;
+}): { readonly reason: string; readonly remediationAction: string } => {
+  const facts =
+    input.constraint === "string-length"
+      ? nodeStringCeilingRecovery(
+          MCP_RESULT_STRING_LIMIT,
+          NODE_MAX_STRING_LENGTH,
+        )
+      : stdioResponseBudgetRecovery(
+          input.effectiveResponseBytes,
+          MCP_RESULT_STRING_LIMIT,
+          NODE_MAX_STRING_LENGTH,
+        );
+  const summary =
+    input.constraint === "string-length"
+      ? input.completed
+        ? "The operation completed, but its complete MCP response exceeds REA's reserved single-string limit."
+        : "The tool failed, but its complete error response exceeds REA's reserved single-string limit."
+      : input.completed
+        ? "The operation completed, but its complete MCP response exceeds the stdio response budget. The analysis result was not truncated."
+        : "The tool failed, but its complete error response exceeds the MCP response budget.";
+  return {
+    reason: `${summary} ${facts} ${input.nextStep}`,
+    remediationAction: `${input.nextStep} ${facts}`,
+  };
+};
+
+/**
+ * A summary projection has already used `detail: "summary"`.
+ * Export still writes the retained bundle outside one MCP frame.
+ */
+const evidenceBundleSummary = (value: JsonValue): boolean => {
+  const payload =
+    typeof value === "object" &&
+    value !== null &&
+    !Array.isArray(value) &&
+    "result" in value
+      ? value.result
+      : value;
+  return (
+    typeof payload === "object" &&
+    payload !== null &&
+    !Array.isArray(payload) &&
+    payload.kind === "evidence-bundle-summary"
+  );
+};
+
+/** Immutable encoding and recovery policy shared by one MCP server. */
+export class ToolResultDelivery {
+  readonly maximumResponseBytes: number;
+  readonly resultBudgetBytes: number;
+  constructor(
+    maximumResponseBytes: number,
+    private readonly nativeContinuation: (
+      evidence: Evidence,
+    ) => Readonly<Record<string, JsonValue>> = () => ({}),
+  ) {
+    this.maximumResponseBytes = maximumResponseBytes;
+    this.resultBudgetBytes = maximumResponseBytes - 1024;
+    Object.freeze(this);
+  }
+
+  /** Serialize a plain application result or its actionable error. */
+  toCallToolResult(
+    result: Result<JsonValue, AnalysisError>,
+    contract: ToolContract,
+  ): CallToolResult {
+    return result.ok
+      ? this.successResult(
+          contract.kind === "session" ? { result: result.value } : result.value,
+          contract,
+        )
+      : this.toErrorToolResult(result.error, contract.returnsTargetContent);
+  }
+
+  /** Deliver Evidence using the producer's explicit recording acknowledgment. */
+  toEvidenceToolResult(
+    evidence: Evidence,
+    contract: ToolContract,
+    recorded: Result<unknown, AnalysisError> | undefined,
+  ): CallToolResult {
+    return recorded !== undefined && !recorded.ok
+      ? this.toErrorToolResult(recorded.error, contract.returnsTargetContent)
+      : this.successResult(evidence, contract, {
+          evidence_id: evidence.evidence_id,
+          ...(recorded === undefined
+            ? {}
+            : {
+                evidence_reference: {
+                  kind: "retained-evidence",
+                  evidence_id: evidence.evidence_id,
+                },
+                ...this.nativeContinuation(evidence),
+              }),
+        });
+  }
+
+  /**
+   * Project an error without allocating oversized repeated MCP text.
+   * `targetContent` is the failing tool's `returnsTargetContent`: a failure
+   * can carry target-derived text (a message, captured output, or a partial
+   * observation), so it is marked exactly like that tool's successful results.
+   */
+  toErrorToolResult(
+    error: AnalysisError,
+    targetContent: boolean,
+  ): CallToolResult {
+    return this.projectedErrorResult(
+      projectAnalysisError(error),
+      targetContent,
+    );
+  }
+
+  /** Deliver the original failure with the producer-acknowledged partial Evidence reference. */
+  toRecordedPartialErrorToolResult(
+    error: AnalysisError,
+    evidenceId: string,
+    recorded: Result<unknown, AnalysisError>,
+    targetContent: boolean,
+  ): CallToolResult {
+    if (!recorded.ok) return this.toErrorToolResult(error, targetContent);
+    const projected = projectAnalysisError(error);
+    return this.projectedErrorResult(
+      {
+        ...projected,
+        details: {
+          ...projected.details,
+          partial_observation: {
+            kind: "retained-evidence",
+            evidence_id: evidenceId,
+          },
+        },
+      },
+      targetContent,
+    );
+  }
+
+  private projectedErrorResult(
+    projected: AnalysisErrorProjection,
+    targetContent: boolean,
+  ): CallToolResult {
+    const structuredContent = { error: projected };
+    // Errors reach the wire as text only; the structured copy is a private
+    // carrier the transport removes after its own budget check.
+    const encoded = encodeToolResult(
+      structuredContent,
+      this.resultBudgetBytes,
+      "error-text",
+      targetContent,
+    );
+    // The transport retains an oversized projected error before replacing it
+    // with a recoverable delivery constraint, using this same budget.
+    return {
+      content: encoded.ok ? [{ type: "text", text: encoded.text }] : [],
+      structuredContent,
+      isError: true,
+      ...(targetContent ? { _meta: TARGET_CONTENT_RESULT_META } : {}),
+    };
+  }
+
+  private successResult(
+    value: JsonValue,
+    contract: ToolContract,
+    recovery: Readonly<Record<string, JsonValue>> = {},
+  ): CallToolResult {
+    const encoded = encodeToolResult(
+      value,
+      this.resultBudgetBytes,
+      "structured-and-text",
+      contract.returnsTargetContent,
+    );
+    if (encoded.ok)
+      return {
+        content: [{ type: "text", text: encoded.text }],
+        structuredContent: value,
+        ...(contract.returnsTargetContent
+          ? { _meta: TARGET_CONTENT_RESULT_META }
+          : {}),
+      };
+    const retainedEvidence = recovery.evidence_reference !== undefined;
+    const nextStep =
+      recovery.continuation !== undefined
+        ? "Call inspect_analysis_view with the supplied continuation arguments to read retained analysis. Follow coverage.next_offset for subsequent pages; reduce the page limit if needed, or export the complete retained Evidence."
+        : retainedEvidence
+          ? "Export retained evidence to consume the complete analysis, or use complete CLI JSON output."
+          : contract.name === "get_evidence_bundle"
+            ? evidenceBundleSummary(value)
+              ? MCP_TRANSPORT_EVIDENCE_EXPORT
+              : MCP_TRANSPORT_EVIDENCE_DISCOVERY
+            : "Use complete CLI JSON output to consume the analysis.";
+    const projected = mcpResponseOverflowProjection({
+      completed: true,
+      constraint: encoded.constraint,
+      effectiveResponseBytes: this.maximumResponseBytes,
+      nextStep,
+    });
+    return this.toErrorToolResult(
+      new AnalysisResourceConstraintError(
+        contract.name,
+        "transport",
+        projected.reason,
+        {
+          boundary: "mcp-response",
+          default_receive_buffer_bytes: STDIO_DEFAULT_MAX_BUFFER_SIZE,
+          result_budget_bytes: this.resultBudgetBytes,
+          max_string_code_units: MCP_RESULT_STRING_LIMIT,
+          response_bytes_at_least: encoded.bytesAtLeast,
+          response_code_units_at_least: encoded.codeUnitsAtLeast,
+          constraint: encoded.constraint,
+          ...recovery,
+        },
+        { remediationAction: projected.remediationAction },
+      ),
+      contract.returnsTargetContent,
+    );
+  }
+}

src/server/createServer.ts

@@ -48,6 +48,7 @@ import { FridaInstrumentationManager } from "../frida/FridaInstrumentationManage
 import { registerFridaTools } from "./registerFridaTools.js";
 import { createBinaryLayoutService } from "../composition/binaryDiagnostics.js";
 import type { BinaryLayoutService } from "../application/binaryDiagnostics/BinaryLayoutService.js";
+import { createCatalogIdentity } from "../catalogIdentity.js";
 import { EvidenceMcpServer } from "./EvidenceMcpServer.js";
 import {
   createToolResultDelivery,
@@ -161,6 +162,10 @@ const RECOVERY_INSTRUCTIONS =
   "Recovery: For invalid arguments, read the connected tool's input schema (refresh tools/list if stale), fix the reported fields and do not repeat the unchanged call. A returned REA provider_timeout is a server/provider deadline: follow its remediation and reuse accessible partial Evidence. A host error such as 'timed out awaiting tools/call' without a REA result is a client deadline, not proof that work or cleanup stopped. Do not repeat the unchanged analysis. Increase the host's tool deadline with execution/cleanup/delivery headroom; when configuration is not editable, report the required setting (Codex: mcp_servers.<server>.tool_timeout_sec, seconds). Server analysis_timeout_ms, when advertised, is a separate millisecond budget; raising it cannot fix a shorter client deadline. Session state does not establish completion of every target-free operation.";
 
 export interface CreateServerOptions {
+  /** Preserve the connection's creation time when materializing its runtime. */
+  readonly startedAt?: string;
+  /** Existing SDK server whose deferred registrations are being materialized. */
+  readonly mcpServer?: EvidenceMcpServer;
   readonly environment?: Readonly<NodeJS.ProcessEnv>;
   readonly delivery?: ToolResultDelivery;
   readonly packetCapture?: PacketCaptureService;
@@ -298,6 +303,10 @@ const createMcpServer = (
     delivery,
     compactPresentation,
     omitOutputSchemas,
+    createCatalogIdentity(
+      compactPresentation,
+      omitOutputSchemas ? "off" : "full",
+    ),
   );
 
 /**
@@ -361,14 +370,28 @@ export const createServer = (
     webModuleTrace,
     javascriptRecovery,
   };
-  const startedAt = new Date().toISOString();
+  const startedAt = options.startedAt ?? new Date().toISOString();
   const logger = options.logger ?? silentLogger;
-  const server = createMcpServer(
-    session,
-    delivery,
-    selectCompactInputSchemaPresentation(environment),
-    omitOutputSchemas,
-  );
+  const server =
+    options.mcpServer ??
+    createMcpServer(
+      session,
+      delivery,
+      selectCompactInputSchemaPresentation(environment),
+      omitOutputSchemas,
+    );
+  if (options.mcpServer !== undefined) {
+    server.attachRuntime(
+      session === undefined
+        ? undefined
+        : (evidence) => session.recordEvidence(evidence),
+      delivery,
+      createCatalogIdentity(
+        selectCompactInputSchemaPresentation(environment),
+        omitOutputSchemas ? "off" : "full",
+      ),
+    );
+  }
   const gdbSessions = new GdbSessionManager({
     environment: providerEnvironment,
   });

src/server/promptArguments.ts

@@ -0,0 +1,36 @@
+import { completable } from "@modelcontextprotocol/server";
+import { z } from "zod";
+import type {
+  PromptArgumentContract,
+  PromptContract,
+} from "../contracts/promptContracts.js";
+import type { PromptCompletionSource } from "./promptCompletion.js";
+
+export const promptArgumentsSchema = (
+  contract: Pick<PromptContract, "arguments">,
+  completion: PromptCompletionSource,
+) => {
+  const shape: Record<string, z.ZodType> = {};
+  for (const [name, argument] of Object.entries(contract.arguments))
+    shape[name] = argumentSchema(argument, completion);
+  return z.object(shape);
+};
+
+const argumentSchema = (
+  argument: PromptArgumentContract,
+  completion: PromptCompletionSource,
+): z.ZodType => {
+  const value = z
+    .string()
+    .min(1)
+    .refine((value) => value.trim().length > 0)
+    .describe(argument.description);
+  const kind = argument.completion;
+  const completed =
+    kind === undefined
+      ? value
+      : completable(value, async (partial, context) => [
+          ...(await completion.complete(kind, partial, context)),
+        ]);
+  return argument.required ? completed : completed.optional();
+};

src/server/promptCompletion.ts

@@ -8,7 +8,7 @@ import { parseProcessCaptureEvidence } from "../application/process/ProcessEvide
 import type { BinarySessionPort } from "../application/binary/BinarySessionPort.js";
 import type { PromptCompletionKind } from "../contracts/promptContracts.js";
 import { addressedValueSchema } from "../domain/native/nativeInventory.js";
-import { currentMcpRequestSignal } from "./EvidenceMcpServer.js";
+import { currentMcpRequestSignal } from "./EvidenceMcpServerCore.js";
 import { parseArtifactInventoryEvidence } from "../domain/artifactInventoryEvidence.js";
 import { EvidenceIntegrityError } from "../domain/evidenceErrors.js";
 

src/server/registerPrompts.ts

@@ -1,11 +1,7 @@
-import {
-  currentMcpRequestSignal,
-  type EvidenceMcpServer,
-} from "./EvidenceMcpServer.js";
-import {
-  completable,
-  type RegisteredPrompt,
-} from "@modelcontextprotocol/server";
+import { promptArgumentsSchema } from "./promptArguments.js";
+import type { EvidenceMcpServer } from "./EvidenceMcpServer.js";
+import { currentMcpRequestSignal } from "./EvidenceMcpServerCore.js";
+import type { RegisteredPrompt } from "@modelcontextprotocol/server";
 import { z } from "zod";
 
 import type { AnalysisOperationPort } from "../application/AnalysisProvider.js";
@@ -13,7 +9,6 @@ import type { BinarySessionPort } from "../application/binary/BinarySessionPort.
 import {
   PROMPT_CONTRACTS,
   renderGuidedPrompt,
-  type PromptArgumentContract,
   type PromptContract,
 } from "../contracts/promptContracts.js";
 import {
@@ -35,7 +30,7 @@ export const registerGuidedPrompts = (
   session?: BinarySessionPort,
 ): GuidedPromptRegistry => {
   const source = createPromptCompletionSource(analysis, session);
-  const completion: PromptCompletionSource = {
+  const completion = server.bindPromptCompletion({
     async complete(kind, value, context) {
       // Completions can query the same providers as tools. Cancellation alone
       // does not mean their provider cleanup has finished.
@@ -43,7 +38,7 @@ export const registerGuidedPrompts = (
         source.complete(kind, value, context),
       );
     },
-  };
+  });
   const prompts = new Map<string, RegisteredPrompt>();
   for (const contract of PROMPT_CONTRACTS)
     prompts.set(contract.name, registerPrompt(server, contract, completion));
@@ -69,7 +64,7 @@ const registerPrompt = (
   completion: PromptCompletionSource,
 ): RegisteredPrompt => {
   const argsSchema = promptArgumentsSchema(contract, completion);
-  return server.registerPrompt(
+  return server.registerCanonicalPrompt(
     contract.name,
     {
       title: contract.title,
@@ -80,35 +75,6 @@ const registerPrompt = (
   );
 };
 
-const promptArgumentsSchema = (
-  contract: PromptContract,
-  completion: PromptCompletionSource,
-) => {
-  const shape: Record<string, z.ZodType> = {};
-  for (const [name, argument] of Object.entries(contract.arguments))
-    shape[name] = argumentSchema(argument, completion);
-  return z.object(shape);
-};
-
-const argumentSchema = (
-  argument: PromptArgumentContract,
-  completion: PromptCompletionSource,
-): z.ZodType => {
-  const value = z
-    .string()
-    .min(1)
-    .refine((value) => value.trim().length > 0)
-    .describe(argument.description);
-  const kind = argument.completion;
-  const completed =
-    kind === undefined
-      ? value
-      : completable(value, async (partial, context) => [
-          ...(await completion.complete(kind, partial, context)),
-        ]);
-  return argument.required ? completed : completed.optional();
-};
-
 const promptResult = (contract: PromptContract, arguments_: unknown) => {
   const values = promptValuesSchema.parse(arguments_);
   for (const [name, argument] of Object.entries(contract.arguments))

src/server/toolResult.ts

@@ -1,65 +1,17 @@
 import { isNativeInventoryOperation } from "../domain/native/nativeInventory.js";
-import { INSPECT_ANALYSIS_VIEW_OPERATION } from "../domain/analysisView/analysisViewErrors.js";
-import type { CallToolResult } from "@modelcontextprotocol/server";
 import { STDIO_DEFAULT_MAX_BUFFER_SIZE } from "@modelcontextprotocol/server";
-
-import type { ToolContract } from "../contracts/toolContractTypes.js";
-import type { Evidence } from "../domain/evidence.js";
+import { ToolResultDelivery as Delivery } from "./ToolResultDelivery.js";
+import { INSPECT_ANALYSIS_VIEW_OPERATION } from "../domain/analysisView/analysisViewErrors.js";
 import { inspectAnalysisViewInputSchema } from "../domain/analysisView/analysisView.js";
-import {
-  projectAnalysisError,
-  type AnalysisErrorProjection,
-} from "../domain/analysisErrorProjection.js";
-import type { AnalysisError } from "../domain/analysisErrorBase.js";
+import type { Evidence } from "../domain/evidence.js";
 import { jsonValueSchema, type JsonValue } from "../domain/jsonValue.js";
-import type { Result } from "../domain/result.js";
-import { AnalysisResourceConstraintError } from "../domain/analysisErrorCore.js";
-import {
-  MCP_TRANSPORT_EVIDENCE_DISCOVERY,
-  MCP_TRANSPORT_EVIDENCE_EXPORT,
-} from "../domain/analysisErrorPresentation.js";
-import {
-  nodeStringCeilingRecovery,
-  stdioResponseBudgetRecovery,
-} from "../config/mcpResponseBudget.js";
-import {
-  encodeToolResult,
-  MCP_RESULT_STRING_LIMIT,
-  NODE_MAX_STRING_LENGTH,
-  TARGET_CONTENT_RESULT_META,
-} from "./toolResultEncoding.js";
 
-/** Project a response-budget refusal without labeling REA's reserved string limit as Node's ceiling. */
-export const mcpResponseOverflowProjection = (input: {
-  readonly completed: boolean;
-  readonly constraint: "receive-buffer" | "string-length";
-  readonly effectiveResponseBytes: number;
-  readonly nextStep: string;
-}): { readonly reason: string; readonly remediationAction: string } => {
-  const facts =
-    input.constraint === "string-length"
-      ? nodeStringCeilingRecovery(
-          MCP_RESULT_STRING_LIMIT,
-          NODE_MAX_STRING_LENGTH,
-        )
-      : stdioResponseBudgetRecovery(
-          input.effectiveResponseBytes,
-          MCP_RESULT_STRING_LIMIT,
-          NODE_MAX_STRING_LENGTH,
-        );
-  const summary =
-    input.constraint === "string-length"
-      ? input.completed
-        ? "The operation completed, but its complete MCP response exceeds REA's reserved single-string limit."
-        : "The tool failed, but its complete error response exceeds REA's reserved single-string limit."
-      : input.completed
-        ? "The operation completed, but its complete MCP response exceeds the stdio response budget. The analysis result was not truncated."
-        : "The tool failed, but its complete error response exceeds the MCP response budget.";
-  return {
-    reason: `${summary} ${facts} ${input.nextStep}`,
-    remediationAction: `${input.nextStep} ${facts}`,
-  };
-};
+/** Full delivery policy, including canonical native Evidence continuation. */
+export class ToolResultDelivery extends Delivery {
+  constructor(maximumResponseBytes: number) {
+    super(maximumResponseBytes, retainedEvidenceContinuation);
+  }
+}
 
 /** Create one delivery policy from the already selected, parsed response budget. */
 export const createToolResultDelivery = (
@@ -91,188 +43,4 @@ const retainedEvidenceContinuation = (
   };
 };
 
-/**
- * A summary projection has already used `detail: "summary"`.
- * Export still writes the retained bundle outside one MCP frame.
- */
-const evidenceBundleSummary = (value: JsonValue): boolean => {
-  const payload =
-    typeof value === "object" &&
-    value !== null &&
-    !Array.isArray(value) &&
-    "result" in value
-      ? value.result
-      : value;
-  return (
-    typeof payload === "object" &&
-    payload !== null &&
-    !Array.isArray(payload) &&
-    payload.kind === "evidence-bundle-summary"
-  );
-};
-
-/** Immutable encoding and recovery policy shared by one MCP server. */
-export class ToolResultDelivery {
-  readonly maximumResponseBytes: number;
-  readonly resultBudgetBytes: number;
-  constructor(maximumResponseBytes: number) {
-    this.maximumResponseBytes = maximumResponseBytes;
-    this.resultBudgetBytes = maximumResponseBytes - 1024;
-    Object.freeze(this);
-  }
-
-  /** Serialize a plain application result or its actionable error. */
-  toCallToolResult(
-    result: Result<JsonValue, AnalysisError>,
-    contract: ToolContract,
-  ): CallToolResult {
-    return result.ok
-      ? this.successResult(
-          contract.kind === "session" ? { result: result.value } : result.value,
-          contract,
-        )
-      : this.toErrorToolResult(result.error, contract.returnsTargetContent);
-  }
-
-  /** Deliver Evidence using the producer's explicit recording acknowledgment. */
-  toEvidenceToolResult(
-    evidence: Evidence,
-    contract: ToolContract,
-    recorded: Result<unknown, AnalysisError> | undefined,
-  ): CallToolResult {
-    return recorded !== undefined && !recorded.ok
-      ? this.toErrorToolResult(recorded.error, contract.returnsTargetContent)
-      : this.successResult(evidence, contract, {
-          evidence_id: evidence.evidence_id,
-          ...(recorded === undefined
-            ? {}
-            : {
-                evidence_reference: {
-                  kind: "retained-evidence",
-                  evidence_id: evidence.evidence_id,
-                },
-                ...retainedEvidenceContinuation(evidence),
-              }),
-        });
-  }
-
-  /**
-   * Project an error without allocating oversized repeated MCP text.
-   * `targetContent` is the failing tool's `returnsTargetContent`: a failure
-   * can carry target-derived text (a message, captured output, or a partial
-   * observation), so it is marked exactly like that tool's successful results.
-   */
-  toErrorToolResult(
-    error: AnalysisError,
-    targetContent: boolean,
-  ): CallToolResult {
-    return this.projectedErrorResult(
-      projectAnalysisError(error),
-      targetContent,
-    );
-  }
-
-  /** Deliver the original failure with the producer-acknowledged partial Evidence reference. */
-  toRecordedPartialErrorToolResult(
-    error: AnalysisError,
-    evidenceId: string,
-    recorded: Result<unknown, AnalysisError>,
-    targetContent: boolean,
-  ): CallToolResult {
-    if (!recorded.ok) return this.toErrorToolResult(error, targetContent);
-    const projected = projectAnalysisError(error);
-    return this.projectedErrorResult(
-      {
-        ...projected,
-        details: {
-          ...projected.details,
-          partial_observation: {
-            kind: "retained-evidence",
-            evidence_id: evidenceId,
-          },
-        },
-      },
-      targetContent,
-    );
-  }
-
-  private projectedErrorResult(
-    projected: AnalysisErrorProjection,
-    targetContent: boolean,
-  ): CallToolResult {
-    const structuredContent = { error: projected };
-    // Errors reach the wire as text only; the structured copy is a private
-    // carrier the transport removes after its own budget check.
-    const encoded = encodeToolResult(
-      structuredContent,
-      this.resultBudgetBytes,
-      "error-text",
-      targetContent,
-    );
-    // The transport retains an oversized projected error before replacing it
-    // with a recoverable delivery constraint, using this same budget.
-    return {
-      content: encoded.ok ? [{ type: "text", text: encoded.text }] : [],
-      structuredContent,
-      isError: true,
-      ...(targetContent ? { _meta: TARGET_CONTENT_RESULT_META } : {}),
-    };
-  }
-
-  private successResult(
-    value: JsonValue,
-    contract: ToolContract,
-    recovery: Readonly<Record<string, JsonValue>> = {},
-  ): CallToolResult {
-    const encoded = encodeToolResult(
-      value,
-      this.resultBudgetBytes,
-      "structured-and-text",
-      contract.returnsTargetContent,
-    );
-    if (encoded.ok)
-      return {
-        content: [{ type: "text", text: encoded.text }],
-        structuredContent: value,
-        ...(contract.returnsTargetContent
-          ? { _meta: TARGET_CONTENT_RESULT_META }
-          : {}),
-      };
-    const retainedEvidence = recovery.evidence_reference !== undefined;
-    const nextStep =
-      recovery.continuation !== undefined
-        ? "Call inspect_analysis_view with the supplied continuation arguments to read retained analysis. Follow coverage.next_offset for subsequent pages; reduce the page limit if needed, or export the complete retained Evidence."
-        : retainedEvidence
-          ? "Export retained evidence to consume the complete analysis, or use complete CLI JSON output."
-          : contract.name === "get_evidence_bundle"
-            ? evidenceBundleSummary(value)
-              ? MCP_TRANSPORT_EVIDENCE_EXPORT
-              : MCP_TRANSPORT_EVIDENCE_DISCOVERY
-            : "Use complete CLI JSON output to consume the analysis.";
-    const projected = mcpResponseOverflowProjection({
-      completed: true,
-      constraint: encoded.constraint,
-      effectiveResponseBytes: this.maximumResponseBytes,
-      nextStep,
-    });
-    return this.toErrorToolResult(
-      new AnalysisResourceConstraintError(
-        contract.name,
-        "transport",
-        projected.reason,
-        {
-          boundary: "mcp-response",
-          default_receive_buffer_bytes: STDIO_DEFAULT_MAX_BUFFER_SIZE,
-          result_budget_bytes: this.resultBudgetBytes,
-          max_string_code_units: MCP_RESULT_STRING_LIMIT,
-          response_bytes_at_least: encoded.bytesAtLeast,
-          response_code_units_at_least: encoded.codeUnitsAtLeast,
-          constraint: encoded.constraint,
-          ...recovery,
-        },
-        { remediationAction: projected.remediationAction },
-      ),
-      contract.returnsTargetContent,
-    );
-  }
-}
+export { mcpResponseOverflowProjection } from "./ToolResultDelivery.js";

tests/boundary/filesystem/ghidraLanguageCatalogBound.test.ts

@@ -1,7 +1,9 @@
-import { mkdir, writeFile } from "node:fs/promises";
+import { execFileSync } from "node:child_process";
+import { mkdir, symlink, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { afterEach, expect, it, vi } from "vitest";
 
+import { ArtifactResourceScope } from "../../../src/artifacts/ArtifactResourceScope.js";
 import { readGhidraLanguageCatalog } from "../../../src/ghidra/GhidraLanguageCatalog.js";
 import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";
 
@@ -61,9 +63,9 @@ it("skips an oversized definition without buffering it beyond the catalog limit"
     '<language_definitions><language id="x86:LE:32:default"/></language_definitions>',
   );
 
-  expect(await readGhidraLanguageCatalog(root)).toEqual([
-    { id: "x86:LE:32:default", compilerSpecIds: [] },
-  ]);
+  expect(
+    await readGhidraLanguageCatalog(root, new ArtifactResourceScope()),
+  ).toEqual([{ id: "x86:LE:32:default", compilerSpecIds: [] }]);
   expect(readBytes.value).toBeGreaterThan(0);
   expect(readBytes.value).toBeLessThanOrEqual(LIMIT + 1);
 });
@@ -80,7 +82,37 @@ it("keeps a definition at exactly the catalog limit", async () => {
     Buffer.concat([document, Buffer.alloc(LIMIT - document.length, 0x20)]),
   );
 
-  expect(await readGhidraLanguageCatalog(root)).toEqual([
-    { id: "edge:LE:32:default", compilerSpecIds: [] },
-  ]);
+  expect(
+    await readGhidraLanguageCatalog(root, new ArtifactResourceScope()),
+  ).toEqual([{ id: "edge:LE:32:default", compilerSpecIds: [] }]);
 });
+
+it("follows a symlinked definition file", async () => {
+  const root = await createTestTempDirectory("rea-ghidra-ldefs-symlink-");
+  const languages = join(root, "Ghidra/Processors/link/data/languages");
+  await mkdir(languages, { recursive: true });
+  const source = join(root, "source.xml");
+  await writeFile(
+    source,
+    '<language_definitions><language id="link:LE:32:default"/></language_definitions>',
+  );
+  await symlink(source, join(languages, "link.ldefs"));
+  expect(
+    await readGhidraLanguageCatalog(root, new ArtifactResourceScope()),
+  ).toEqual([{ id: "link:LE:32:default", compilerSpecIds: [] }]);
+});
+
+it.skipIf(process.platform === "win32")(
+  "refuses a non-regular definition without waiting for a writer",
+  async () => {
+    const root = await createTestTempDirectory("rea-ghidra-ldefs-fifo-");
+    const languages = join(root, "Ghidra/Processors/pipe/data/languages");
+    await mkdir(languages, { recursive: true });
+    execFileSync("mkfifo", [join(languages, "pipe.ldefs")]);
+    const resources = new ArtifactResourceScope();
+    await expect(
+      readGhidraLanguageCatalog(root, resources),
+    ).rejects.toMatchObject({ code: "ENOTFILE" });
+    expect(resources.hasPending).toBe(false);
+  },
+);

tests/boundary/filesystem/ghidraLanguageCatalogCleanup.test.ts

@@ -3,9 +3,11 @@ import { basename, join } from "node:path";
 import { afterEach, expect, it, vi } from "vitest";
 
 import {
-  GhidraLanguageCatalogCleanupError,
-  readGhidraLanguageCatalog,
-} from "../../../src/ghidra/GhidraLanguageCatalog.js";
+  ArtifactResourceRetryFailure,
+  ArtifactResourceScope,
+} from "../../../src/artifacts/ArtifactResourceScope.js";
+import { ArtifactReaderFailure } from "../../../src/artifacts/ArtifactReader.js";
+import { readGhidraLanguageCatalog } from "../../../src/ghidra/GhidraLanguageCatalog.js";
 import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";
 
 interface FileControl {
@@ -16,6 +18,7 @@ interface FileControl {
   readFails: boolean;
   invalidated: boolean;
   closeCalls: number;
+  opens: number;
 }
 
 // Per-file failure controls, keyed by definition file name, and a barrier
@@ -45,6 +48,7 @@ vi.mock("node:fs/promises", async (importOriginal) => {
       const real = await actual.open(...args);
       const control = controls.get(basename(String(args[0])));
       if (control === undefined) return real;
+      control.opens += 1;
       let released = false;
       const release = async () => {
         if (released) return;
@@ -55,6 +59,8 @@ vi.mock("node:fs/promises", async (importOriginal) => {
         get fd() {
           return control.invalidated ? -1 : real.fd;
         },
+        stat: (...statArgs: Parameters<typeof real.stat>) =>
+          real.stat(...statArgs),
         read: (...readArgs: Parameters<typeof real.read>) =>
           control.readFails
             ? Promise.reject(new Error("definition read failed"))
@@ -77,8 +83,6 @@ vi.mock("node:fs/promises", async (importOriginal) => {
   };
 });
 
-let preserveUnconfirmedOwner = false;
-
 const control = (name: string, overrides: Partial<FileControl> = {}) => {
   const value: FileControl = {
     closeFails: false,
@@ -87,6 +91,7 @@ const control = (name: string, overrides: Partial<FileControl> = {}) => {
     readFails: false,
     invalidated: false,
     closeCalls: 0,
+    opens: 0,
     ...overrides,
   };
   controls.set(name, value);
@@ -104,31 +109,77 @@ const installation = async (name: string): Promise<string> => {
   return root;
 };
 
-// Let every retained owner close, then drain them through a healthy read.
+const scopes: ArtifactResourceScope[] = [];
+const scope = (): ArtifactResourceScope => {
+  const value = new ArtifactResourceScope();
+  scopes.push(value);
+  return value;
+};
+
+// Let every retained owner close through its own scope, except an invalidated
+// descriptor whose close can never be confirmed.
 afterEach(async () => {
-  if (preserveUnconfirmedOwner) {
-    preserveUnconfirmedOwner = false;
-    controls.clear();
-    return;
-  }
-  for (const value of controls.values()) value.closeFails = false;
-  await readGhidraLanguageCatalog(await installation("drain"));
+  for (const value of controls.values())
+    if (!value.invalidateOnFailure) value.closeFails = false;
+  await Promise.allSettled(scopes.map((value) => value.close()));
+  scopes.length = 0;
   controls.clear();
 });
 
-it("retries a retained close before the next read", async () => {
+it("retries the retained close in the caller scope before the next read", async () => {
+  const resources = scope();
   const retained = control("flaky.ldefs", { closeFails: true });
-  await expect(
-    readGhidraLanguageCatalog(await installation("flaky")),
-  ).rejects.toMatchObject({ paths: [expect.stringContaining("flaky.ldefs")] });
+  const failure = await readGhidraLanguageCatalog(
+    await installation("flaky"),
+    resources,
+  ).catch((cause: unknown) => cause);
+  expect(failure).toBeInstanceOf(ArtifactReaderFailure);
+  expect(failure).toMatchObject({
+    cleanup: { resources: [expect.stringContaining("flaky.ldefs")] },
+  });
+  expect(resources.hasPending).toBe(true);
   retained.closeFails = false;
-  expect(await readGhidraLanguageCatalog(await installation("x86"))).toEqual([
-    { id: "x86:LE:32:default", compilerSpecIds: [] },
-  ]);
+  expect(
+    await readGhidraLanguageCatalog(await installation("x86"), resources),
+  ).toEqual([{ id: "x86:LE:32:default", compilerSpecIds: [] }]);
   expect(retained.closeCalls).toBe(2);
+  expect(resources.hasPending).toBe(false);
+});
+
+it("refuses new reads without opening definitions while the retry still fails", async () => {
+  const resources = scope();
+  const retained = control("stuck.ldefs", { closeFails: true });
+  await expect(
+    readGhidraLanguageCatalog(await installation("stuck"), resources),
+  ).rejects.toBeInstanceOf(ArtifactReaderFailure);
+  const next = control("next.ldefs");
+  const refused = await readGhidraLanguageCatalog(
+    await installation("next"),
+    resources,
+  ).catch((cause: unknown) => cause);
+  expect(refused).toBeInstanceOf(ArtifactResourceRetryFailure);
+  expect(refused).toMatchObject({
+    cleanup: { resources: [expect.stringContaining("stuck.ldefs")] },
+  });
+  expect(retained.closeCalls).toBe(2);
+  expect(next.opens).toBe(0);
+  expect(resources.hasPending).toBe(true);
+});
+
+it("keeps one scope's retained close out of another scope", async () => {
+  control("isolated.ldefs", { closeFails: true });
+  const failed = scope();
+  await expect(
+    readGhidraLanguageCatalog(await installation("isolated"), failed),
+  ).rejects.toBeInstanceOf(ArtifactReaderFailure);
+  expect(
+    await readGhidraLanguageCatalog(await installation("x86"), scope()),
+  ).toEqual([{ id: "x86:LE:32:default", compilerSpecIds: [] }]);
+  expect(failed.hasPending).toBe(true);
 });
 
 it("attempts every retained close and reports the remaining failures together", async () => {
+  const resources = scope();
   const first = control("first.ldefs", {
     closeFails: true,
     synchronizedClose: true,
@@ -138,66 +189,72 @@ it("attempts every retained close and reports the remaining failures together",
     synchronizedClose: true,
   });
   barrier.state.expected = 2;
-  // Concurrent resolutions can each retain an owner.
+  // Concurrent resolutions can each retain an owner in the same scope.
   const roots = [await installation("first"), await installation("second")];
   const results = await Promise.allSettled(
-    roots.map((root) => readGhidraLanguageCatalog(root)),
+    roots.map((root) => readGhidraLanguageCatalog(root, resources)),
   );
   expect(results.map(({ status }) => status)).toEqual(["rejected", "rejected"]);
   second.closeFails = false;
   const failure = await readGhidraLanguageCatalog(
     await installation("x86"),
+    resources,
   ).catch((cause: unknown) => cause);
-  expect(failure).toBeInstanceOf(GhidraLanguageCatalogCleanupError);
+  expect(failure).toBeInstanceOf(ArtifactResourceRetryFailure);
   expect(failure).toMatchObject({
-    paths: [expect.stringContaining("first.ldefs")],
+    cleanup: { resources: [expect.stringContaining("first.ldefs")] },
   });
   expect(second.closeCalls).toBe(2);
   expect(first.closeCalls).toBe(2);
 });
 
-it("keeps the read failure when the close also fails", async () => {
+it("keeps the read failure primary when the close also fails", async () => {
   control("damaged.ldefs", { readFails: true, closeFails: true });
   const failure = await readGhidraLanguageCatalog(
     await installation("damaged"),
+    scope(),
   ).catch((cause: unknown) => cause);
-  expect(failure).toBeInstanceOf(GhidraLanguageCatalogCleanupError);
+  expect(failure).toBeInstanceOf(ArtifactReaderFailure);
   expect(failure).toMatchObject({
-    readFailure: expect.objectContaining({ message: "definition read failed" }),
+    message: "definition read failed",
+    cleanup: { resources: [expect.stringContaining("damaged.ldefs")] },
   });
 });
 
 it("reports retained cleanup for a catalog without definitions", async () => {
+  const resources = scope();
   control("pending.ldefs", { closeFails: true });
   await expect(
-    readGhidraLanguageCatalog(await installation("pending")),
-  ).rejects.toBeInstanceOf(GhidraLanguageCatalogCleanupError);
+    readGhidraLanguageCatalog(await installation("pending"), resources),
+  ).rejects.toBeInstanceOf(ArtifactReaderFailure);
   const empty = await createTestTempDirectory("rea-ghidra-ldefs-empty-");
-  await expect(readGhidraLanguageCatalog(empty)).rejects.toMatchObject({
-    paths: [expect.stringContaining("pending.ldefs")],
+  await expect(
+    readGhidraLanguageCatalog(empty, resources),
+  ).rejects.toMatchObject({
+    cleanup: { resources: [expect.stringContaining("pending.ldefs")] },
   });
 });
 
 it("retains an invalidated descriptor owner and keeps later reads blocked", async () => {
+  const resources = scope();
   const broken = control("broken.ldefs", {
     closeFails: true,
     invalidateOnFailure: true,
   });
-  const first = await readGhidraLanguageCatalog(
-    await installation("broken"),
-  ).catch((cause: unknown) => cause);
-  expect(first).toBeInstanceOf(GhidraLanguageCatalogCleanupError);
-  expect(first).toMatchObject({
-    paths: [expect.stringContaining("broken.ldefs")],
+  await expect(
+    readGhidraLanguageCatalog(await installation("broken"), resources),
+  ).rejects.toMatchObject({
+    cleanup: { resources: [expect.stringContaining("broken.ldefs")] },
   });
-
   const later = await readGhidraLanguageCatalog(
     await installation("x86"),
+    resources,
   ).catch((cause: unknown) => cause);
-  expect(later).toBeInstanceOf(GhidraLanguageCatalogCleanupError);
+  expect(later).toBeInstanceOf(ArtifactResourceRetryFailure);
   expect(later).toMatchObject({
-    paths: [expect.stringContaining("broken.ldefs")],
+    cleanup: { resources: [expect.stringContaining("broken.ldefs")] },
   });
+  // The owner refuses to re-close an invalidated descriptor it never confirmed.
   expect(broken.closeCalls).toBe(1);
-  preserveUnconfirmedOwner = true;
+  expect(resources.hasPending).toBe(true);
 });

tests/boundary/filesystem/ghidraLanguageCatalogEncoding.test.ts

@@ -1,6 +1,7 @@
 import { mkdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { expect, it } from "vitest";
+import { ArtifactResourceScope } from "../../../src/artifacts/ArtifactResourceScope.js";
 import { readGhidraLanguageCatalog } from "../../../src/ghidra/GhidraLanguageCatalog.js";
 import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";
 
@@ -57,11 +58,13 @@ it.each([
     await mkdir(directory, { recursive: true });
     await writeFile(join(directory, "toy.ldefs"), bytes);
     if (expectedError === null)
-      expect(await readGhidraLanguageCatalog(root)).toEqual([
-        { id: "toy:LE:32:default", compilerSpecIds: ["default"] },
-      ]);
+      expect(
+        await readGhidraLanguageCatalog(root, new ArtifactResourceScope()),
+      ).toEqual([{ id: "toy:LE:32:default", compilerSpecIds: ["default"] }]);
     else
-      await expect(readGhidraLanguageCatalog(root)).rejects.toMatchObject({
+      await expect(
+        readGhidraLanguageCatalog(root, new ArtifactResourceScope()),
+      ).rejects.toMatchObject({
         reason: expectedError,
       });
   },

tests/boundary/filesystem/ghidraLanguageCatalogRecovery.test.ts

@@ -0,0 +1,262 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { Client, InMemoryTransport } from "@modelcontextprotocol/client";
+import { afterEach, expect, it, onTestFinished, vi } from "vitest";
+import { AnalysisProviderRegistry } from "../../../src/application/binary/AnalysisProviderRegistry.js";
+import { composeBinarySession } from "../../../src/application/binary/BinarySessionComposition.js";
+import { parseConfig } from "../../../src/config/parseConfig.js";
+import type { BinaryTarget } from "../../../src/domain/binaryTargetTypes.js";
+import { ghidraProfileInstallationHost } from "../../../src/ghidra/GhidraInstallation.fixture.js";
+import { GhidraProvider } from "../../../src/ghidra/GhidraProvider.js";
+import { silentLogger } from "../../../src/logger.js";
+import { createServer } from "../../../src/server/createServer.js";
+import { createDeferred } from "../../fixtures/binarySession.js";
+import { parseMcpToolError } from "../../fixtures/mcpToolError.js";
+import { nativeAotPeFixture } from "../../fixtures/nativeaotPe.js";
+import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";
+
+// Fault only the installed x86 language definition; its real descriptor stays
+// open while close is refused, and closes for real once the fault clears.
+const fault = vi.hoisted(() => ({
+  enabled: false,
+  deny: false,
+  opens: 0,
+  closes: 0,
+  onClose: undefined as (() => Promise<void>) | undefined,
+}));
+vi.mock("node:fs/promises", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("node:fs/promises")>();
+  return {
+    ...actual,
+    open: async (...args: Parameters<typeof actual.open>) => {
+      const handle = await actual.open(...args);
+      if (fault.enabled && String(args[0]).endsWith("/x86.ldefs")) {
+        fault.opens++;
+        const close = handle.close.bind(handle);
+        handle.close = async () => {
+          fault.closes++;
+          await fault.onClose?.();
+          if (fault.deny)
+            throw Object.assign(new Error("injected close EIO"), {
+              code: "EIO",
+            });
+          return close();
+        };
+      }
+      return handle;
+    },
+  };
+});
+
+afterEach(() => {
+  Object.assign(fault, {
+    enabled: false,
+    deny: false,
+    opens: 0,
+    closes: 0,
+    onClose: undefined,
+  });
+});
+
+const fixture = async () => {
+  const root = await createTestTempDirectory("rea-ghidra-catalog-close-");
+  const languages = join(root, "Ghidra/Processors/x86/data/languages");
+  const path = join(root, "fixture.exe");
+  await mkdir(languages, { recursive: true });
+  await writeFile(
+    join(languages, "x86.ldefs"),
+    '<language_definitions><language id="x86:LE:64:default"><compiler id="windows"/></language></language_definitions>',
+  );
+  await writeFile(path, nativeAotPeFixture());
+  const config = parseConfig({
+    GHIDRA_INSTALL_DIR: root,
+    REA_GHIDRA_LANGUAGE_ID: "x86:LE:64:default",
+  });
+  if (!config.ok) throw config.error;
+  const provider = new GhidraProvider(
+    config.value,
+    silentLogger,
+    {},
+    ghidraProfileInstallationHost,
+    () => {
+      throw new Error("unexpected engine startup");
+    },
+  );
+  const registry = new AnalysisProviderRegistry([provider]);
+  onTestFinished(async () => {
+    fault.deny = false;
+    fault.onClose = undefined;
+    await registry.closeOwnedResources();
+  });
+  const target: BinaryTarget = {
+    path,
+    sha256: "a".repeat(64),
+    kind: "executable",
+    format: "pe",
+    architecture: "x86_64",
+    availableArchitectures: ["x86_64"],
+    executableRole: "application",
+    managed: false,
+  };
+  return {
+    definition: join(languages, "x86.ldefs"),
+    path,
+    provider,
+    registry,
+    target,
+  };
+};
+
+it("retries the retained catalog close on later MCP admission and reopens the same registry", async () => {
+  const { definition, path, provider, registry } = await fixture();
+  const session = composeBinarySession(registry);
+  const server = createServer(
+    { kind: "session", session },
+    {
+      logger: silentLogger,
+    },
+  );
+  const client = new Client({ name: "catalog-close-recovery", version: "1" });
+  const [clientTransport, serverTransport] =
+    InMemoryTransport.createLinkedPair();
+  const call = (name: "open_binary" | "close_binary") =>
+    client.callTool({
+      name,
+      arguments: name === "open_binary" ? { path, provider_id: "ghidra" } : {},
+    });
+  try {
+    await server.connect(serverTransport);
+    await client.connect(clientTransport);
+    expect((await call("open_binary")).isError).not.toBe(true);
+    expect((await call("close_binary")).isError).not.toBe(true);
+
+    fault.enabled = true;
+    fault.deny = true;
+    const failed = parseMcpToolError(await call("open_binary"));
+    expect(failed.error).toMatchObject({
+      code: "cleanup_incomplete",
+      details: { cleanup: "incomplete", resources: [definition] },
+    });
+    expect(provider.hasPendingOwnedResources()).toBe(true);
+    expect(registry.hasPendingOwnedResources()).toBe(true);
+    expect({ opens: fault.opens, closes: fault.closes }).toEqual({
+      opens: 1,
+      closes: 1,
+    });
+
+    // While the exact owner still refuses close, admission retries it and stays
+    // fail-closed without reading the catalog again.
+    const refused = parseMcpToolError(await call("open_binary"));
+    expect(refused.error).toMatchObject({
+      code: "cleanup_incomplete",
+      details: { cleanup: "incomplete", resources: [definition] },
+    });
+    expect({ opens: fault.opens, closes: fault.closes }).toEqual({
+      opens: 1,
+      closes: 2,
+    });
+    expect(registry.hasPendingOwnedResources()).toBe(true);
+
+    fault.deny = false;
+    expect((await call("open_binary")).isError).not.toBe(true);
+    // The retained owner released once, then a fresh catalog read closed cleanly.
+    expect({ opens: fault.opens, closes: fault.closes }).toEqual({
+      opens: 2,
+      closes: 4,
+    });
+    expect(provider.hasPendingOwnedResources()).toBe(false);
+    expect((await call("close_binary")).isError).not.toBe(true);
+    expect(registry.hasPendingOwnedResources()).toBe(false);
+  } finally {
+    await client.close();
+    await server.close();
+    await session.close();
+  }
+});
+
+it.each(["released", "still failing"] as const)(
+  "finishes the catalog cleanup retry when admission is cancelled during it (%s)",
+  async (outcome) => {
+    const { definition, registry, target } = await fixture();
+    fault.enabled = true;
+    fault.deny = true;
+    const first = await registry.select(target, "ghidra");
+    if (first.ok) throw new Error("Expected incomplete catalog cleanup");
+    expect(first.error.cleanupIncomplete).toBe(true);
+    expect(first.error.cleanupResources).toEqual([definition]);
+
+    const entered = createDeferred<undefined>();
+    const release = createDeferred<undefined>();
+    fault.onClose = async () => {
+      entered.resolve(undefined);
+      await release.promise;
+    };
+    const controller = new AbortController();
+    const reason = { caller: "cancel during catalog cleanup retry" };
+    let settled = false;
+    const admission = registry
+      .select(target, "ghidra", { signal: controller.signal })
+      .finally(() => {
+        settled = true;
+      });
+    await entered.promise;
+    controller.abort(reason);
+    await Promise.resolve();
+    // Cancellation never abandons the in-flight close of the retained owner.
+    expect(settled).toBe(false);
+    if (outcome === "released") fault.deny = false;
+    fault.onClose = undefined;
+    release.resolve(undefined);
+    const cancelled = await admission;
+    if (cancelled.ok) throw new Error("Expected cancelled admission");
+    expect(fault.closes).toBe(2);
+    expect(fault.opens).toBe(1);
+
+    if (outcome === "released") {
+      expect(cancelled.error).toMatchObject({
+        _tag: "AnalysisCancelledError",
+        cause: reason,
+        cleanupIncomplete: false,
+      });
+      expect(first.error.cleanupIncomplete).toBe(false);
+      expect(registry.hasPendingOwnedResources()).toBe(false);
+    } else {
+      expect(cancelled.error.cleanupIncomplete).toBe(true);
+      expect(cancelled.error.cleanupResources).toEqual([definition]);
+      expect(first.error.cleanupIncomplete).toBe(true);
+      expect(registry.hasPendingOwnedResources()).toBe(true);
+      fault.deny = false;
+    }
+    const recovered = await registry.select(target, "ghidra");
+    expect(recovered.ok).toBe(true);
+    expect(first.error.cleanupIncomplete).toBe(false);
+    expect(registry.hasPendingOwnedResources()).toBe(false);
+  },
+);
+
+it("keeps the caller's reason and the catalog owner when cancellation lands during the final close", async () => {
+  const { definition, provider, target } = await fixture();
+  const controller = new AbortController();
+  const reason = { caller: "cancel during final catalog close" };
+  fault.enabled = true;
+  fault.deny = true;
+  fault.onClose = async () => {
+    controller.abort(reason);
+  };
+  const resolved = await provider.resolveAnalysisProfile(target, {
+    signal: controller.signal,
+  });
+  if (resolved.ok) throw new Error("Expected cancelled catalog read");
+  expect(resolved.error).toMatchObject({
+    _tag: "AnalysisCancelledError",
+    cleanupIncomplete: true,
+    cleanupResources: [definition],
+  });
+  expect(JSON.stringify(resolved.error.cause)).toContain(reason.caller);
+  expect(provider.hasPendingOwnedResources()).toBe(true);
+  fault.deny = false;
+  fault.onClose = undefined;
+  expect((await provider.closeOwnedResources()).ok).toBe(true);
+  expect(resolved.error.cleanupIncomplete).toBe(false);
+  expect(provider.hasPendingOwnedResources()).toBe(false);
+});

tests/boundary/mcp/deferredRuntime.test.ts

@@ -0,0 +1,798 @@
+import { Client } from "@modelcontextprotocol/client";
+import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";
+import { spawnSync } from "node:child_process";
+import {
+  cp,
+  mkdir,
+  readFile,
+  readdir,
+  symlink,
+  writeFile,
+} from "node:fs/promises";
+import { resolve, join } from "node:path";
+import { expect, it, onTestFinished } from "vitest";
+import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";
+import { GENERATED_MCP_TOOL_CATALOG } from "../../fixtures/mcpToolCatalog.js";
+import { PROMPT_CONTRACTS } from "../../../src/contracts/promptContracts.js";
+import { evidenceSchema } from "../../../src/domain/evidence.js";
+import { analysisViewResultSchema } from "../../../src/domain/analysisView/analysisView.js";
+import { SERVER_START_FAILED } from "../../../src/main/messages.js";
+
+const connect = async (
+  mode: "legacy" | "auto",
+  environment: Record<string, string> = {},
+  nodeArguments: readonly string[] = [],
+) => {
+  const transport = new StdioClientTransport({
+    command: process.execPath,
+    args: [...nodeArguments, resolve("scripts/rea.mjs"), "mcp"],
+    cwd: process.cwd(),
+    env: {
+      PATH: process.env.PATH ?? "",
+      HOME: process.env.HOME ?? "",
+      REA_LOG_LEVEL: "silent",
+      ...environment,
+    },
+    stderr: "pipe",
+  });
+  let stderr = "";
+  transport.stderr?.on("data", (value) => {
+    stderr += value;
+  });
+  const client = new Client(
+    { name: "deferred-runtime-boundary", version: "1" },
+    { versionNegotiation: { mode } },
+  );
+  onTestFinished(async () => {
+    await client.close();
+    await transport.close();
+  });
+  await client.connect(transport);
+  return { client, stderr: () => stderr };
+};
+
+it.each([
+  { name: "deferred", environment: {}, eager: false },
+  {
+    name: "compact deferred",
+    environment: { REA_MCP_INPUT_SCHEMA_PROFILE: "compact" },
+    eager: false,
+  },
+  {
+    name: "full deferred",
+    environment: { REA_MCP_INPUT_SCHEMA_PROFILE: "full" },
+    eager: false,
+  },
+  {
+    name: "output-off eager",
+    environment: { REA_MCP_OUTPUT_SCHEMA_PROFILE: "off" },
+    eager: true,
+  },
+])(
+  "loads compiled analysis at the intended phase for $name startup",
+  async ({ environment, eager }) => {
+    const directory = await createTestTempDirectory("rea-mcp-module-loads-");
+    const log = join(directory, "loaded.jsonl");
+    await writeFile(log, "");
+    const modules = [
+      "main/eagerRuntime.js",
+      "server/createServer.js",
+      "composition/binary.js",
+      "contracts/toolContracts.js",
+    ];
+    const hook = `data:text/javascript,${encodeURIComponent(`
+import { registerHooks } from "node:module";
+import { appendFileSync } from "node:fs";
+const modules = ${JSON.stringify(modules)};
+registerHooks({
+  load(url, context, next) {
+    const loaded = next(url, context);
+    const source = loaded.source?.toString() ?? "";
+    const names = modules.filter((name) =>
+      url.endsWith("/dist/" + name) || source.includes("//#region dist/" + name + "\\n"));
+    if (url.endsWith("/scripts/rea.mjs")) names.push("entrypoint");
+    for (const name of names)
+      appendFileSync(${JSON.stringify(log)}, JSON.stringify(name) + "\\n");
+    return loaded;
+  },
+});
+`)}`;
+    const loadedModules = async () =>
+      new Set(
+        (await readFile(log, "utf8"))
+          .trim()
+          .split("\n")
+          .filter(Boolean)
+          .map((line): unknown => JSON.parse(line)),
+      );
+    const { client, stderr } = await connect("legacy", environment, [
+      `--import=${hook}`,
+    ]);
+    await client.listTools();
+    await client.listPrompts();
+    expect(await loadedModules()).toEqual(
+      new Set(eager ? ["entrypoint", ...modules] : ["entrypoint"]),
+    );
+    const result = await client.callTool({
+      name: "list_unknowns",
+      arguments: {},
+    });
+    expect(result.isError).not.toBe(true);
+    expect(await loadedModules()).toEqual(new Set(["entrypoint", ...modules]));
+    expect(stderr()).toBe("");
+  },
+);
+
+it.each([
+  { mode: "legacy", profile: "full" },
+  { mode: "auto", profile: "full" },
+  { mode: "legacy", profile: "compact" },
+  { mode: "auto", profile: "compact" },
+] as const)(
+  "serves $profile discovery and canonical handlers over $mode negotiation",
+  async ({ mode, profile }) => {
+    const recorded = JSON.parse(
+      await readFile(
+        profile === "full"
+          ? "dist/mcp-catalog-full.json"
+          : "dist/mcp-catalog.json",
+        "utf8",
+      ),
+    );
+    const { client, stderr } = await connect(mode, {
+      REA_MCP_INPUT_SCHEMA_PROFILE: profile,
+    });
+    const before = await client.listTools();
+    expect(before.tools).toEqual(recorded.tools);
+    const contractProjection = (tool: {
+      name: string;
+      title?: string | undefined;
+      description?: string | undefined;
+      inputSchema: unknown;
+      outputSchema?: unknown;
+      annotations?: unknown;
+    }) => ({
+      name: tool.name,
+      title: tool.title,
+      description: tool.description,
+      inputSchema: tool.inputSchema,
+      outputSchema: tool.outputSchema,
+      annotations: tool.annotations,
+    });
+    if (profile === "full")
+      expect(
+        new Map(
+          before.tools.map((tool) => [tool.name, contractProjection(tool)]),
+        ),
+      ).toEqual(
+        new Map(
+          GENERATED_MCP_TOOL_CATALOG.map((tool) => [
+            tool.name,
+            contractProjection(tool),
+          ]),
+        ),
+      );
+    expect((await client.listPrompts()).prompts).toEqual(
+      PROMPT_CONTRACTS.map((prompt) => ({
+        name: prompt.name,
+        title: prompt.title,
+        description: prompt.description,
+        arguments: Object.entries(prompt.arguments).map(([name, argument]) => ({
+          name,
+          description: argument.description,
+          required: argument.required,
+        })),
+      })),
+    );
+
+    expect((await client.listPrompts()).prompts).toEqual(
+      recorded.prompts.map(
+        ({ parameters: _parameters, ...prompt }: Record<string, unknown>) =>
+          prompt,
+      ),
+    );
+    const results = await Promise.all([
+      client.callTool({ name: "list_unknowns", arguments: {} }),
+      client.callTool({ name: "list_unknowns", arguments: { limit: 1 } }),
+    ]);
+    expect(results.every((result) => result.isError !== true)).toBe(true);
+    expect(results[0]?.structuredContent).toEqual({
+      result: { items: [], total: 0, offset: 0, next_offset: null },
+    });
+    expect(await client.listTools()).toEqual(before);
+    const invalid = await client.callTool({
+      name: "list_unknowns",
+      arguments: { limit: 1.5 },
+    });
+    expect(invalid.isError).toBe(true);
+    expect(invalid._meta?.provenance).toEqual({
+      untrusted_content: true,
+      source: "analysis_target",
+    });
+    expect(client.getProtocolEra()).toBe(mode === "auto" ? "modern" : "legacy");
+    if (mode === "auto")
+      expect(invalid._meta?.["io.modelcontextprotocol/serverInfo"]).toEqual(
+        recorded.info,
+      );
+    expect(stderr()).toBe("");
+  },
+);
+
+it("preserves connection creation time across deferred materialization", async () => {
+  const directory = await createTestTempDirectory("rea-mcp-started-at-");
+  const clock = join(directory, "clock");
+  const startedAt = "2020-01-01T00:00:00.000Z";
+  await writeFile(clock, startedAt);
+  const hook = `data:text/javascript,${encodeURIComponent(`
+import { readFileSync } from "node:fs";
+const NativeDate = Date;
+globalThis.Date = class extends NativeDate {
+  constructor(...args) {
+    super(...(args.length === 0 ? [readFileSync(${JSON.stringify(clock)}, "utf8")] : args));
+  }
+};
+`)}`;
+  const { client } = await connect("legacy", {}, [`--import=${hook}`]);
+  await client.listTools();
+  await writeFile(clock, "2021-01-01T00:00:00.000Z");
+  const first = await client.callTool({
+    name: "binary_session",
+    arguments: {},
+  });
+  expect(first.isError).not.toBe(true);
+  expect(first.structuredContent).toMatchObject({
+    result: { server_identity: { server: { started_at: startedAt } } },
+  });
+  const again = await client.callTool({
+    name: "binary_session",
+    arguments: {},
+  });
+  expect(again.structuredContent).toMatchObject({
+    result: { server_identity: { server: { started_at: startedAt } } },
+  });
+});
+
+it.each([
+  { level: "info", asynchronous: false, errorObject: true },
+  { level: "info", asynchronous: true, errorObject: false },
+  { level: "silent", asynchronous: false, errorObject: true },
+])(
+  "logs deferred startup failure with $level logging and asynchronous=$asynchronous",
+  ({ level, asynchronous, errorObject }) => {
+    const child = spawnSync(
+      process.execPath,
+      [
+        "--input-type=module",
+        "--eval",
+        `
+import assert from "node:assert/strict";
+import { runDeferred } from "./dist/main/deferredRuntime.js";
+import { parseConfig } from "./dist/config/parseConfig.js";
+const config = parseConfig({ HOME: process.env.HOME, REA_LOG_LEVEL: ${JSON.stringify(level)} });
+assert.equal(config.ok, true);
+const output = [];
+let closeCalls = 0;
+let unregistrations = 0;
+const result = await runDeferred({
+  env: {},
+  writeStderr: (text) => output.push(text),
+  setExitCode: () => {},
+  registerShutdown: () => () => { unregistrations++; },
+  serve: (factory) => {
+    const server = factory({});
+    const close = server.server.close.bind(server.server);
+    server.server.close = async () => { closeCalls++; await close(); };
+    const cause = ${errorObject ? 'new Error("transport setup reason")' : '"transport setup reason"'};
+    if (${asynchronous}) return Promise.reject(cause);
+    throw cause;
+  },
+}, config.value);
+console.log(JSON.stringify({ result, output, closeCalls, unregistrations }));
+`,
+      ],
+      { cwd: process.cwd(), encoding: "utf8", timeout: 10000 },
+    );
+    expect(child.error).toBeUndefined();
+    expect(child.status, child.stderr).toBe(0);
+    expect(JSON.parse(child.stdout)).toEqual({
+      result: 1,
+      output: [`${SERVER_START_FAILED}\n`],
+      closeCalls: 1,
+      unregistrations: 1,
+    });
+    if (level === "silent") {
+      expect(child.stderr).toBe("");
+    } else {
+      expect(JSON.parse(child.stderr)).toMatchObject({
+        level: 50,
+        application: "rea",
+        mode: "mcp",
+        layer: "server",
+        error: "transport setup reason",
+        msg: SERVER_START_FAILED,
+      });
+    }
+  },
+);
+
+it("retains process cleanup ownership after partial startup and failed cleanup", () => {
+  const child = spawnSync(
+    process.execPath,
+    [
+      "--input-type=module",
+      "--eval",
+      `
+import assert from "node:assert/strict";
+import { runDeferred } from "./dist/main/deferredRuntime.js";
+import { parseConfig } from "./dist/config/parseConfig.js";
+const config = parseConfig({ HOME: process.env.HOME, REA_LOG_LEVEL: "silent" });
+assert.equal(config.ok, true);
+const handlers = [];
+const calls = [0, 0];
+let unregistrations = 0;
+let captured;
+let registeredBeforeServe;
+const result = await runDeferred({
+  env: {},
+  writeStderr: () => {},
+  setExitCode: () => {},
+  registerShutdown: (handler) => {
+    handlers.push(handler);
+    return () => { unregistrations++; };
+  },
+  captureShutdown: (close) => { captured = close; },
+  serve: (factory) => {
+    registeredBeforeServe = handlers.length;
+    for (let index = 0; index < calls.length; index++) {
+      const server = factory({});
+      const close = server.server.close.bind(server.server);
+      server.server.close = async () => {
+        calls[index]++;
+        if (index === 0 && calls[index] === 1) throw new Error("close denied");
+        await close();
+      };
+    }
+    throw new Error("serve failed after creating servers");
+  },
+}, config.value).then(() => "unexpected success", (cause) => cause);
+assert.ok(result instanceof AggregateError);
+assert.equal(result.errors[0].message, "serve failed after creating servers");
+assert.ok(result.errors[1] instanceof AggregateError);
+assert.match(String(result.errors[1].errors[0].errors[0]), /close denied/);
+assert.equal(registeredBeforeServe, 1);
+assert.deepEqual(calls, [1, 1]);
+assert.equal(unregistrations, 0);
+assert.equal(typeof captured, "function");
+const retry = captured();
+handlers[0]();
+await retry;
+await new Promise((resolve) => setImmediate(resolve));
+assert.deepEqual(calls, [2, 1]);
+assert.equal(unregistrations, 1);
+await captured();
+assert.deepEqual(calls, [2, 1]);
+assert.equal(unregistrations, 1);
+console.log("STARTUP_CLEANUP_RETRIED");
+`,
+    ],
+    { cwd: process.cwd(), encoding: "utf8", timeout: 10000 },
+  );
+  expect(child.error).toBeUndefined();
+  expect(child.status, child.stderr).toBe(0);
+  expect(child.stdout).toBe("STARTUP_CLEANUP_RETRIED\n");
+  expect(child.stderr).toBe("");
+});
+
+it.each(["handle", "server"])(
+  "retries only the failed %s cleanup owner",
+  (failedOwner) => {
+    const child = spawnSync(
+      process.execPath,
+      [
+        "--input-type=module",
+        "--eval",
+        `
+import assert from "node:assert/strict";
+import { runDeferred } from "./dist/main/deferredRuntime.js";
+import { parseConfig } from "./dist/config/parseConfig.js";
+const config = parseConfig({ HOME: process.env.HOME });
+assert.equal(config.ok, true);
+const failedOwner = ${JSON.stringify(failedOwner)};
+const calls = { handle: 0, server: 0 };
+let captured;
+let unregistrations = 0;
+const result = await runDeferred({
+  env: {}, writeStderr: () => {}, setExitCode: () => {},
+  registerShutdown: () => () => { unregistrations++; },
+  captureShutdown: (close) => { captured = close; },
+  serve: (factory) => {
+    const server = factory({});
+    const close = server.server.close.bind(server.server);
+    server.server.close = async () => {
+      calls.server++;
+      if (failedOwner === "server" && calls.server === 1) throw new Error("server denied");
+      await close();
+    };
+    return { close: () => {
+      calls.handle++;
+      if (failedOwner === "handle" && calls.handle === 1) throw new Error("handle denied");
+      // Deliberately not idempotent: a successful handle must never be retried.
+      assert.ok(calls.handle <= (failedOwner === "handle" ? 2 : 1));
+      return Promise.resolve();
+    } };
+  },
+}, config.value);
+assert.equal(result, 0);
+await assert.rejects(captured(), AggregateError);
+assert.deepEqual(calls, { handle: 1, server: 1 });
+assert.equal(unregistrations, 0);
+await captured();
+assert.deepEqual(calls, { handle: failedOwner === "handle" ? 2 : 1, server: failedOwner === "server" ? 2 : 1 });
+assert.equal(unregistrations, 1);
+await captured();
+assert.equal(unregistrations, 1);
+console.log("MIXED_CLEANUP_RETRIED");
+`,
+      ],
+      { cwd: process.cwd(), encoding: "utf8", timeout: 10000 },
+    );
+    expect(child.error).toBeUndefined();
+    expect(child.status, child.stderr).toBe(0);
+    expect(child.stdout).toBe("MIXED_CLEANUP_RETRIED\n");
+    expect(child.stderr).toBe("");
+  },
+);
+
+it("joins shutdown with a transport and server published after shutdown starts", () => {
+  const child = spawnSync(
+    process.execPath,
+    [
+      "--input-type=module",
+      "--eval",
+      `
+import assert from "node:assert/strict";
+import { runDeferred } from "./dist/main/deferredRuntime.js";
+import { parseConfig } from "./dist/config/parseConfig.js";
+const config = parseConfig({ HOME: process.env.HOME });
+assert.equal(config.ok, true);
+const transport = Promise.withResolvers();
+let factory;
+let captured;
+let signal;
+let unregistrations = 0;
+let handleCalls = 0;
+let serverCalls = 0;
+const running = runDeferred({
+  env: {}, writeStderr: () => {}, setExitCode: () => {},
+  registerShutdown: (handler) => {
+    signal = handler;
+    return () => { unregistrations++; };
+  },
+  captureShutdown: (close) => { captured = close; },
+  serve: (create) => { factory = create; return transport.promise; },
+}, config.value);
+signal();
+const closing = captured();
+let closed = false;
+void closing.then(() => { closed = true; });
+await new Promise((resolve) => setImmediate(resolve));
+assert.equal(closed, false);
+assert.equal(unregistrations, 0);
+const server = factory({});
+const close = server.server.close.bind(server.server);
+server.server.close = async () => { serverCalls++; await close(); };
+transport.resolve({ close: async () => { handleCalls++; } });
+assert.equal(await running, 0);
+await closing;
+assert.deepEqual([handleCalls, serverCalls, unregistrations], [1, 1, 1]);
+await captured();
+assert.deepEqual([handleCalls, serverCalls, unregistrations], [1, 1, 1]);
+console.log("LATE_TRANSPORT_CLOSED");
+`,
+    ],
+    { cwd: process.cwd(), encoding: "utf8", timeout: 10000 },
+  );
+  expect(child.error).toBeUndefined();
+  expect(child.status, child.stderr).toBe(0);
+  expect(child.stdout).toBe("LATE_TRANSPORT_CLOSED\n");
+  expect(child.stderr).toBe("");
+});
+
+it("refuses server publication after the shutdown snapshot and completed close", () => {
+  const child = spawnSync(
+    process.execPath,
+    [
+      "--input-type=module",
+      "--eval",
+      `
+import assert from "node:assert/strict";
+import { runDeferred } from "./dist/main/deferredRuntime.js";
+import { parseConfig } from "./dist/config/parseConfig.js";
+const config = parseConfig({ HOME: process.env.HOME });
+assert.equal(config.ok, true);
+const closingHandle = Promise.withResolvers();
+const releaseHandle = Promise.withResolvers();
+let factory;
+let captured;
+let handleCalls = 0;
+let serverCalls = 0;
+let unregistrations = 0;
+const result = await runDeferred({
+  env: {}, writeStderr: () => {}, setExitCode: () => {},
+  registerShutdown: () => () => { unregistrations++; },
+  captureShutdown: (close) => { captured = close; },
+  serve: (create) => {
+    factory = create;
+    const server = factory({});
+    const close = server.server.close.bind(server.server);
+    server.server.close = async () => { serverCalls++; await close(); };
+    return { close: async () => {
+      handleCalls++;
+      closingHandle.resolve();
+      await releaseHandle.promise;
+    } };
+  },
+}, config.value);
+assert.equal(result, 0);
+const closing = captured();
+await closingHandle.promise;
+assert.throws(() => factory({}), /MCP connection is closed/);
+releaseHandle.resolve();
+await closing;
+assert.throws(() => factory({}), /MCP connection is closed/);
+await captured();
+assert.deepEqual([handleCalls, serverCalls, unregistrations], [1, 1, 1]);
+console.log("LATE_PUBLICATION_REFUSED");
+`,
+    ],
+    { cwd: process.cwd(), encoding: "utf8", timeout: 10000 },
+  );
+  expect(child.error).toBeUndefined();
+  expect(child.status, child.stderr).toBe(0);
+  expect(child.stdout).toBe("LATE_PUBLICATION_REFUSED\n");
+  expect(child.stderr).toBe("");
+});
+
+it.each([
+  {},
+  { REA_MCP_INPUT_SCHEMA_PROFILE: "compact" },
+  { REA_MCP_INPUT_SCHEMA_PROFILE: "full" },
+  { REA_MCP_OUTPUT_SCHEMA_PROFILE: "off" },
+])("preserves the configured catalog profile %j", async (environment) => {
+  const { client } = await connect("legacy", environment);
+  const before = await client.listTools();
+  const catalog = JSON.parse(
+    await readFile(
+      environment.REA_MCP_INPUT_SCHEMA_PROFILE === "full"
+        ? "dist/mcp-catalog-full.json"
+        : "dist/mcp-catalog.json",
+      "utf8",
+    ),
+  );
+  expect(before.tools).toHaveLength(catalog.tools.length);
+  const expected =
+    environment.REA_MCP_OUTPUT_SCHEMA_PROFILE === "off"
+      ? catalog.tools.map(
+          ({ outputSchema: _output, ...tool }: Record<string, unknown>) => tool,
+        )
+      : catalog.tools;
+  expect(before.tools).toEqual(expected);
+  const result = await client.callTool({
+    name: "list_unknowns",
+    arguments: {},
+  });
+  expect(result.isError).not.toBe(true);
+  expect(await client.listTools()).toEqual(before);
+});
+
+it("runs the real static artifact workflow after deferred initialization", async () => {
+  const { client } = await connect("legacy");
+  const opened = await client.callTool({
+    name: "open_binary",
+    arguments: { path: resolve("scripts/rea.mjs") },
+  });
+  expect(opened.isError, JSON.stringify(opened)).not.toBe(true);
+  const inspected = await client.callTool({
+    name: "inspect_artifact",
+    arguments: { detail: "summary" },
+  });
+  expect(inspected.isError, JSON.stringify(inspected)).not.toBe(true);
+  const evidence = evidenceSchema.parse(inspected.structuredContent);
+  expect(evidence.operation).toBe("inspect_analysis_view");
+  const view = analysisViewResultSchema.parse(evidence.normalized_result);
+  expect(view.parent_operation).toBe("inspect_artifact");
+  const retained = await client.callTool({
+    name: "inspect_analysis_view",
+    arguments: {
+      source: {
+        kind: "retained-evidence",
+        evidence_id: view.parent_evidence_id,
+      },
+      view: { kind: "summary" },
+    },
+  });
+  expect(retained.isError, JSON.stringify(retained)).not.toBe(true);
+  const closed = await client.callTool({ name: "close_binary", arguments: {} });
+  expect(closed.isError, JSON.stringify(closed)).not.toBe(true);
+});
+
+const copyCompiledPackage = async (prefix: string): Promise<string> => {
+  const directory = await createTestTempDirectory(prefix);
+  await cp(resolve("dist"), join(directory, "dist"), { recursive: true });
+  await mkdir(join(directory, "scripts"));
+  await cp(resolve("scripts/rea.mjs"), join(directory, "scripts/rea.mjs"));
+  await cp(resolve("package.json"), join(directory, "package.json"));
+  await symlink(
+    resolve("node_modules"),
+    join(directory, "node_modules"),
+    process.platform === "win32" ? "junction" : "dir",
+  );
+  return directory;
+};
+
+it("records the canonical catalog without a host account or ambient configuration", async () => {
+  const directory = await copyCompiledPackage("rea-catalog-without-account-");
+  await cp(
+    resolve("scripts/record-mcp-catalog.mjs"),
+    join(directory, "scripts/record-mcp-catalog.mjs"),
+  );
+  const temporary = join(directory, "temporary");
+  await mkdir(temporary);
+  const hook = `data:text/javascript,${encodeURIComponent(`
+import os from "node:os";
+import { syncBuiltinESMExports } from "node:module";
+os.userInfo = () => { throw new Error("Host account is unavailable"); };
+syncBuiltinESMExports();
+`)}`;
+  const child = spawnSync(
+    process.execPath,
+    [`--import=${hook}`, join(directory, "scripts/record-mcp-catalog.mjs")],
+    {
+      cwd: directory,
+      env: {
+        ...process.env,
+        HOME: join(directory, "ambient-home"),
+        USERPROFILE: join(directory, "ambient-home"),
+        TMPDIR: temporary,
+        TMP: temporary,
+        TEMP: temporary,
+        REA_MCP_INPUT_SCHEMA_PROFILE: "compact",
+        REA_MCP_OUTPUT_SCHEMA_PROFILE: "off",
+      },
+      encoding: "utf8",
+      timeout: 30000,
+    },
+  );
+  expect(child.error).toBeUndefined();
+  expect(child.status, child.stderr).toBe(0);
+  expect(child.stdout).toBe("");
+  expect(child.stderr).toBe("");
+  expect(await readFile(join(directory, "dist/mcp-catalog.json"), "utf8")).toBe(
+    await readFile("dist/mcp-catalog.json", "utf8"),
+  );
+  expect(
+    await readFile(join(directory, "dist/recordedMcpCatalog.js"), "utf8"),
+  ).toBe(await readFile("dist/recordedMcpCatalog.js", "utf8"));
+  expect(await readdir(temporary)).toEqual([]);
+});
+
+it.each([
+  { failures: ["client"], producerFails: false },
+  { failures: ["client", "server", "session"], producerFails: false },
+  { failures: ["client"], producerFails: true },
+  { failures: [], producerFails: true },
+])(
+  "preserves producer failure=$producerFails and settles every recorder owner with cleanup failures=$failures",
+  async ({ failures, producerFails }) => {
+    const directory = await copyCompiledPackage("rea-catalog-cleanup-");
+    await cp(
+      resolve("scripts/record-mcp-catalog.mjs"),
+      join(directory, "scripts/record-mcp-catalog.mjs"),
+    );
+    const log = join(directory, "cleanup.jsonl");
+    const temporary = join(directory, "temporary");
+    await mkdir(temporary);
+    // Fault injection tests recorder ownership, not provider or SDK behavior.
+    const close = (owner: string) => `async () => {
+      const { appendFileSync } = await import("node:fs");
+      appendFileSync(${JSON.stringify(log)}, JSON.stringify(${JSON.stringify(owner)}) + "\\n");
+      if (${JSON.stringify(failures)}.includes(${JSON.stringify(owner)}))
+        throw new Error(${JSON.stringify(`${owner} cleanup failed`)});
+      return { ok: true };
+    }`;
+    const replacements = {
+      "/dist/server/createServer.js": `export const createServer = () => ({ connect: async () => {}, close: ${close("server")} });`,
+      "/dist/composition/binary.js": `export const createBinarySession = () => ({ close: ${close("session")} });`,
+      "/dist/config/parseConfig.js":
+        "export const parseConfig = () => ({ ok: true, value: {} });",
+      "/dist/logger.js": "export const silentLogger = {};",
+      "/dist/contracts/promptContracts.js":
+        "export const PROMPT_CONTRACTS = [];",
+    };
+    const clientModule = `data:text/javascript,${encodeURIComponent(`
+export class Client {
+  async connect() {}
+  async listTools() {
+    if (${JSON.stringify(producerFails)}) throw new Error("catalog generation failed");
+    return { tools: [] };
+  }
+  async listPrompts() { return { prompts: [] }; }
+  getServerVersion() {}
+  getServerCapabilities() {}
+  getInstructions() {}
+  close = ${close("client")};
+}
+export const InMemoryTransport = { createLinkedPair: () => [null, null] };
+`)}`;
+    const hook = `data:text/javascript,${encodeURIComponent(`
+import { registerHooks } from "node:module";
+const replacements = ${JSON.stringify(replacements)};
+registerHooks({
+  resolve(specifier, context, next) {
+    return specifier === "@modelcontextprotocol/client"
+      ? { url: ${JSON.stringify(clientModule)}, shortCircuit: true }
+      : next(specifier, context);
+  },
+  load(url, context, next) {
+    const replacement = Object.entries(replacements).find(([path]) => url.endsWith(path));
+    return replacement === undefined ? next(url, context)
+      : { source: replacement[1], format: "module", shortCircuit: true };
+  },
+});
+`)}`;
+    const child = spawnSync(
+      process.execPath,
+      [`--import=${hook}`, join(directory, "scripts/record-mcp-catalog.mjs")],
+      {
+        cwd: directory,
+        env: {
+          ...process.env,
+          TMPDIR: temporary,
+          TMP: temporary,
+          TEMP: temporary,
+        },
+        encoding: "utf8",
+        timeout: 10000,
+      },
+    );
+    expect(child.error).toBeUndefined();
+    expect(child.status).toBe(1);
+    expect(
+      new Set(
+        (await readFile(log, "utf8"))
+          .trim()
+          .split("\n")
+          .map((line): unknown => JSON.parse(line)),
+      ),
+    ).toEqual(new Set(["client", "server", "session"]));
+    for (const owner of failures)
+      expect(child.stderr).toContain(`${owner} cleanup failed`);
+    if (producerFails) {
+      expect(child.stderr).toContain("Error: catalog generation failed");
+      if (failures.length > 0)
+        expect(
+          child.stderr.indexOf("Error: catalog generation failed"),
+        ).toBeLessThan(child.stderr.indexOf(`${failures[0]} cleanup failed`));
+    }
+    if (failures.length > 0)
+      expect(child.stderr).toContain("AggregateError: Catalog cleanup failed");
+    else expect(child.stderr).not.toContain("AggregateError");
+    expect(await readdir(temporary)).toHaveLength(failures.length > 0 ? 1 : 0);
+  },
+);
+
+it("rejects a corrupted build-owned catalog before starting the connection", async () => {
+  const directory = await copyCompiledPackage("rea-corrupted-mcp-catalog-");
+  await writeFile(join(directory, "dist/mcp-catalog.json"), "{}");
+  const child = spawnSync(
+    process.execPath,
+    [join(directory, "scripts/rea.mjs"), "mcp"],
+    { cwd: directory, input: "", encoding: "utf8", timeout: 10000 },
+  );
+  expect(child.error).toBeUndefined();
+  expect(child.status).toBe(1);
+  expect(child.stdout).toBe("");
+  expect(child.stderr).toBe(
+    "REA could not start. Run `rea doctor`, then restart REA from your MCP client.\n",
+  );
+});

tests/boundary/mcp/optionalProviderShutdown.test.ts

@@ -2,7 +2,10 @@ import { afterAll, expect, it, vi } from "vitest";
 import { mkdirSync, mkdtempSync, rmSync } from "node:fs";
 import { resolve } from "node:path";
 
-import { createTestBinarySession } from "../../fixtures/binarySession.js";
+import {
+  createDeferred,
+  createTestBinarySession,
+} from "../../fixtures/binarySession.js";
 import { createBrowserObservationProvider } from "../../../src/composition/browserObservation.js";
 import { createJavaScriptRuntimeObservationProvider } from "../../../src/composition/javascriptRuntimeObservation.js";
 import { run } from "../../../src/main.js";
@@ -25,6 +28,62 @@ for (const path of [
   mkdirSync(path);
 afterAll(() => rmSync(root, { recursive: true, force: true }));
 
+it("refuses eager server publication after the shutdown snapshot and completed close", async () => {
+  const closingHandle = createDeferred<void>();
+  const releaseHandle = createDeferred<void>();
+  const acquired: ReturnType<typeof createServer>[] = [];
+  let publish: (() => unknown) | undefined;
+  let shutdown: (() => Promise<void>) | undefined;
+  let closing: Promise<void> | undefined;
+  let transportCloses = 0;
+  try {
+    expect(
+      await run({
+        env: environment,
+        loadOptionalProviders: async () => ({}),
+        createServer: (source, options) => {
+          const server = createServer(source, options);
+          acquired.push(server);
+          return server;
+        },
+        serve: (factory) => {
+          publish = () => factory({ era: "legacy" });
+          publish();
+          return {
+            close: async () => {
+              transportCloses++;
+              closingHandle.resolve();
+              await releaseHandle.promise;
+            },
+          };
+        },
+        captureShutdown: (close) => {
+          shutdown = close;
+        },
+        registerShutdown: () => () => {},
+        writeStderr: () => {},
+        setExitCode: () => {},
+      }),
+    ).toBe(0);
+    if (shutdown === undefined || publish === undefined)
+      throw new Error("Runtime ownership hooks were not installed");
+    closing = shutdown();
+    await closingHandle.promise;
+    expect(publish).toThrow("MCP connection is closed");
+    releaseHandle.resolve();
+    await closing;
+    expect(publish).toThrow("MCP connection is closed");
+    await shutdown();
+    expect(transportCloses).toBe(1);
+    expect(acquired).toHaveLength(1);
+  } finally {
+    releaseHandle.resolve();
+    await closing;
+    await shutdown?.();
+    for (const server of acquired) await server.close();
+  }
+});
+
 it("retries failed process-owned optional cleanup without reclosing completed peers", async () => {
   const runtime = createJavaScriptRuntimeObservationProvider();
   const browser = createBrowserObservationProvider();

tests/boundary/process/binarySessionCleanupRetry.test.ts

@@ -129,7 +129,12 @@ it("retains Hopper process handles, private files, and lease until an actual ses
   if (runtime === undefined)
     throw new Error("Fixture did not capture its runtime");
   await access(runtime);
-  expect(launcher.cleanupAttempts).toBe(1);
+  // The fixture exits after its shutdown acknowledgement. When the supervisor
+  // observes that exit only after a failed verification began, it verifies
+  // once more; a failed stop never runs more than two verifications.
+  const firstCloseAttempts = launcher.cleanupAttempts;
+  expect(firstCloseAttempts).toBeGreaterThanOrEqual(1);
+  expect(firstCloseAttempts).toBeLessThanOrEqual(2);
   expect(await launcher.acquire("other-owner")).toMatchObject({
     acquired: false,
   });
@@ -138,10 +143,11 @@ it("retains Hopper process handles, private files, and lease until an actual ses
     error: { cleanupIncomplete: true },
   });
   expect(clientsCreated).toBe(1);
-  expect(launcher.cleanupAttempts).toBe(2);
+  // The launcher exit was already observed, so the retry has no new evidence.
+  expect(launcher.cleanupAttempts).toBe(firstCloseAttempts + 1);
   launcher.cleanupAllowed = true;
   expect(await session.close()).toEqual(resultOk(null));
-  expect(launcher.cleanupAttempts).toBe(3);
+  expect(launcher.cleanupAttempts).toBe(firstCloseAttempts + 2);
   await expect(access(runtime)).rejects.toMatchObject({ code: "ENOENT" });
   const replacement = await launcher.acquire("replacement-owner");
   expect(replacement.acquired).toBe(true);

turbo.json

@@ -21,6 +21,7 @@
         "scripts/clean-build-output.mjs",
         "scripts/bundle-runtime.mjs",
         "scripts/record-catalog-digests.mjs",
+        "scripts/record-mcp-catalog.mjs",
         "scripts/generate-package-metadata.mjs",
         "src/**/*.{cts,mts,ts,tsx}",
         "src/**/package.json",