@henols/vice-mcp 0.1.12 → 0.2.1

package/version.ts

@@ -0,0 +1,279 @@
+// The ONE authoritative implementation of this project's version-resolution
+// algorithm (D-5). Before this file existed the repo carried FOUR
+// hand-maintained version strings and none of them were true:
+// `.claude/mcp/vice/package.json` and `installer/package.json` were stale
+// placeholders CI never touched between releases, `.claude-plugin/plugin.json`
+// was bumped by NO automation at all, and `vice-proxy.ts`'s own
+// `PROXY_VERSION` literal -- advertised to every MCP client over
+// `initialize` -- sat twelve patches behind npm's actual `latest`. This file
+// exists so there is exactly one place that (a) parses the repo-root
+// `VERSION` template, (b) resolves it against a published version per D-2's
+// four rules, and (c) answers "what version am I, right now, at runtime"
+// (D-4) -- every other consumer (the CLI in `scripts/version.mjs`,
+// `vice-proxy.ts`'s `PROXY_VERSION`, CI's `release-on-merge` job) calls INTO
+// this module rather than re-deriving any part of the algorithm locally.
+//
+// Do NOT reimplement the resolution rules (`pinned` / `no-published` /
+// `prefix-differs` / `prefix-matches`) anywhere else in this repo -- not in
+// `scripts/version.mjs`, not in CI YAML, not in `installer/bin/cli.mjs`.
+// `version.test.ts`'s "single-implementation guard" test greps
+// `scripts/version.mjs` for the rule literals to catch exactly that
+// regression.
+//
+// Do NOT import `repo-root.ts` from this file. That module's `repoRoot()`
+// carries a documented side effect (`ensureResourcesInstalled()`, fired at
+// module-load time) this seam must never trigger just by being imported --
+// `scripts/version.mjs` and any future test that imports this module for
+// its pure functions alone would otherwise deploy host launcher resources as
+// a side effect of asking what version something is. Per this repo's own
+// convention (see `hostpath.ts`/`containerpath.ts`), the workspace root
+// arrives here as an explicit argument (`readTemplate(repoRootDir)`) or a
+// caller-supplied lazy thunk (`runtimeVersion({ repoRoot })`), never as an
+// import this module resolves itself.
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+/** The single self-evident placeholder every derived, publishable version
+ * string (the two npm package.json `.version` fields, the installer's
+ * `@henols/vice-mcp` dependency pin, and the three plugin-manifest version
+ * fields) carries in the working tree (R-2). Valid semver -- `npm pack`
+ * accepts it -- but unmistakably not a release. Overwritten at publish time
+ * by `npm version` (npm packages) or `scripts/version.mjs stamp` (plugin
+ * manifests); never hand-edited. */
+export const DEV_PLACEHOLDER = "0.0.0-dev";
+
+export type ResolveRule = "pinned" | "no-published" | "prefix-differs" | "prefix-matches";
+
+export interface ResolveResult {
+  version: string;
+  rule: ResolveRule;
+  template: string;
+  published: string | null;
+}
+
+// Leading zeros are rejected (bare "0" is the only zero-value exception) --
+// SemVer 2.0.0 SS2 forbids leading-zero numeric identifiers, and this
+// component is echoed VERBATIM into the resolved string for literal (non-`-`)
+// slots, so "1.00.0" must be rejected here rather than surfacing later as an
+// npm-publish-time failure (MED-2).
+const TEMPLATE_COMPONENT = /^(0|[1-9]\d*|-)$/;
+
+/**
+ * Parse a version TEMPLATE (not a resolved version) into its three
+ * dot-separated components. Each component must be either a non-negative
+ * integer literal or the literal string `-` (an auto-managed slot, D-2).
+ * Throws on anything else: wrong component count, a non-numeric/non-`-`
+ * component, a blank/whitespace-only string, OR a literal component
+ * appearing after a `-` component (MED-1) -- D-2's "literal prefix" wording,
+ * and every row of CONTEXT.md's worked-example table, only ever describe
+ * dashes trailing literals, never leading or interleaved. A shape like
+ * "-.2.3" or "0.-.2" has no defined resolution semantics and must be
+ * rejected at the one seam that owns validating the hand-edited VERSION
+ * file, not silently resolved into something CONTEXT.md never specified.
+ */
+export function parseTemplate(raw: string): string[] {
+  const trimmed = raw.trim();
+  if (trimmed === "") {
+    throw new Error(`version.ts: malformed template ${JSON.stringify(raw)} -- empty`);
+  }
+  const parts = trimmed.split(".");
+  if (parts.length !== 3) {
+    throw new Error(
+      `version.ts: malformed template ${JSON.stringify(raw)} -- expected exactly 3 dot-separated components, got ${parts.length}`
+    );
+  }
+  let sawDash = false;
+  for (const part of parts) {
+    if (part === "-") {
+      sawDash = true;
+      continue;
+    }
+    if (sawDash) {
+      throw new Error(
+        `version.ts: malformed template ${JSON.stringify(raw)} -- literal component ${JSON.stringify(part)} cannot follow a "-" component; dashes only trail literals (D-2)`
+      );
+    }
+    if (!TEMPLATE_COMPONENT.test(part)) {
+      throw new Error(
+        `version.ts: malformed template ${JSON.stringify(raw)} -- component ${JSON.stringify(part)} is neither an integer (no leading zeros) nor "-"`
+      );
+    }
+  }
+  return parts;
+}
+
+/**
+ * Parse a PUBLISHED version string into a 3-tuple of numbers, stripping any
+ * `-prerelease` / `+build` suffix first. Returns null (never throws) when
+ * the input is null, not parseable, or does not have exactly 3 numeric
+ * dot-separated components -- callers treat null exactly like "nothing is
+ * published" (D-2 rule 4).
+ */
+function parsePublished(published: string | null): number[] | null {
+  if (published == null) return null;
+  const core = published.split(/[-+]/, 1)[0];
+  const parts = core.split(".");
+  if (parts.length !== 3) return null;
+  // Strict plain-decimal-digit validation (MED-4) -- deliberately NOT
+  // `Number(p)` + `Number.isInteger`, which also accepts hex-like literals
+  // ("0x2" -> 2), exponential notation ("5e2" -> 500), and whitespace-padded
+  // numbers. Those would silently coerce malformed `--published` input or an
+  // unexpected `npm view` response into a number that doesn't reflect the
+  // original text; this must instead fall back to null (== "no-published",
+  // D-2 rule 4) exactly like any other unparseable input, matching the
+  // strict digit validation `parseTemplate`'s `TEMPLATE_COMPONENT` already
+  // uses for the same kind of input.
+  if (!parts.every((p) => /^\d+$/.test(p))) return null;
+  return parts.map((p) => Number(p));
+}
+
+/**
+ * The D-2 resolution algorithm, in full. `template` must already be
+ * well-formed (call `parseTemplate` first, or pass through unchanged --
+ * this function calls it internally so a malformed template always throws
+ * here too). `published` is the raw published-version string (or null);
+ * this function does its own stripping/parsing via `parsePublished`.
+ */
+export function resolveVersion(template: string, published: string | null): ResolveResult {
+  const components = parseTemplate(template);
+
+  if (!components.includes("-")) {
+    return { version: components.join("."), rule: "pinned", template, published };
+  }
+
+  const pub = parsePublished(published);
+
+  if (pub === null) {
+    const resolved = components.map((c) => (c === "-" ? "0" : c));
+    return { version: resolved.join("."), rule: "no-published", template, published };
+  }
+
+  const prefixMatches = components.every((c, i) => c === "-" || Number(c) === pub[i]);
+
+  if (!prefixMatches) {
+    const resolved = components.map((c) => (c === "-" ? "0" : c));
+    return { version: resolved.join("."), rule: "prefix-differs", template, published };
+  }
+
+  let firstDashSeen = false;
+  const resolved = components.map((c, i) => {
+    if (c !== "-") return c;
+    if (!firstDashSeen) {
+      firstDashSeen = true;
+      // Guard (LOW-1): `pub[i] + 1` on a published component at
+      // Number.MAX_SAFE_INTEGER would silently lose precision to float
+      // rounding and could fail to actually increment, violating this
+      // seam's "always publishes something new" invariant. Purely
+      // theoretical for real-world semver (patch counts in the billions are
+      // not realistic) but the arithmetic is load-bearing enough to fail
+      // loud rather than silently miscompute.
+      if (pub[i] >= Number.MAX_SAFE_INTEGER) {
+        throw new Error(
+          `version.ts: published component ${pub[i]} at index ${i} is at or beyond Number.MAX_SAFE_INTEGER -- refusing to increment (would lose precision)`
+        );
+      }
+      return String(pub[i] + 1);
+    }
+    return "0";
+  });
+  return { version: resolved.join("."), rule: "prefix-matches", template, published };
+}
+
+/**
+ * Compare two plain, fully-resolved (no `-`, no prerelease) semver-shaped
+ * version strings as a numeric 3-tuple. Returns -1/0/1. Throws if either
+ * side does not parse as 3 numeric components -- this is for comparing
+ * RESOLVED versions, not templates.
+ */
+export function compareVersions(a: string, b: string): -1 | 0 | 1 {
+  const pa = parsePublished(a);
+  const pb = parsePublished(b);
+  if (pa === null) throw new Error(`version.ts: compareVersions() cannot parse ${JSON.stringify(a)}`);
+  if (pb === null) throw new Error(`version.ts: compareVersions() cannot parse ${JSON.stringify(b)}`);
+  for (let i = 0; i < 3; i++) {
+    if (pa[i] < pb[i]) return -1;
+    if (pa[i] > pb[i]) return 1;
+  }
+  return 0;
+}
+
+/**
+ * Read `<repoRootDir>/VERSION`, trimmed. Returns the empty string for an
+ * existing-but-blank (or whitespace-only) file, and null ONLY when the file
+ * is absent (never throws on either outcome) -- do not treat `=== null` as
+ * the sole "no template" signal; an empty string is also "no usable
+ * template", and every current caller checks for it via truthiness (LOW-3).
+ * Does NOT validate the template shape -- `resolveVersion`/`parseTemplate`
+ * do that; this function's only job is the filesystem read.
+ */
+export function readTemplate(repoRootDir: string): string | null {
+  const path = join(repoRootDir, "VERSION");
+  if (!existsSync(path)) return null;
+  try {
+    return readFileSync(path, "utf8").trim();
+  } catch {
+    return null;
+  }
+}
+
+export interface RuntimeVersionOptions {
+  pkgJsonPath?: string;
+  /** LAZY -- see this file's header and the precedence note below. Only
+   * called when `pkgJsonPath`'s own version is absent or is
+   * DEV_PLACEHOLDER, so a published tarball (which has a real version and
+   * no repo-root VERSION file) never calls this and never risks the
+   * stderr note `repoRoot()` implementations may emit. */
+  repoRoot?: () => string | undefined;
+}
+
+/**
+ * D-4's runtime precedence, synchronous and never throwing:
+ *
+ *   1. `pkgJsonPath`'s own `.version`, when present and not DEV_PLACEHOLDER
+ *      -- the published-tarball path: `npm version` already stamped it.
+ *   2. Otherwise call `opts.repoRoot?.()` and, if it yields a directory,
+ *      read that directory's `VERSION` template. A pinned template (no `-`)
+ *      returns verbatim; a template containing `-` resolves every `-` to 0
+ *      and appends a `-dev` prerelease tag, so a dev checkout never claims
+ *      to be a release build.
+ *   3. Otherwise DEV_PLACEHOLDER.
+ *
+ * The whole body is wrapped in try/catch: any unexpected failure (a
+ * malformed package.json, a repoRoot() thunk that throws, a malformed
+ * VERSION template) degrades to DEV_PLACEHOLDER rather than crashing the
+ * caller -- this is the one runtime-facing entry point in this file, and a
+ * standalone MCP server must never fail to start over a version string.
+ */
+export function runtimeVersion(opts: RuntimeVersionOptions = {}): string {
+  try {
+    if (opts.pkgJsonPath) {
+      try {
+        const raw = readFileSync(opts.pkgJsonPath, "utf8");
+        const pkg = JSON.parse(raw) as { version?: unknown };
+        if (typeof pkg.version === "string" && pkg.version.length > 0 && pkg.version !== DEV_PLACEHOLDER) {
+          return pkg.version;
+        }
+      } catch {
+        // No readable/parseable package.json at pkgJsonPath -- fall through.
+      }
+    }
+
+    const root = opts.repoRoot?.();
+    if (root) {
+      const template = readTemplate(root);
+      if (template) {
+        const components = parseTemplate(template);
+        if (!components.includes("-")) {
+          return components.join(".");
+        }
+        const resolved = components.map((c) => (c === "-" ? "0" : c));
+        return `${resolved.join(".")}-dev`;
+      }
+    }
+  } catch {
+    // Degrade to the placeholder below -- see this function's own doc
+    // comment for why nothing here may throw.
+  }
+
+  return DEV_PLACEHOLDER;
+}

package/vice-proxy.ts

@@ -100,6 +100,10 @@ import {
 // reconnect ladder.
 import { probeInstance, type ProbeResult } from "./vice-probe.ts";
 import { repoRoot } from "./repo-root.ts";
+// The single version-resolution seam (quick-260819-tsz, D-5) -- PROXY_VERSION
+// below is the only consumer in this file; see version.ts's own header for
+// why this file must never re-derive any part of the algorithm itself.
+import { runtimeVersion } from "./version.ts";
 import { hostPath, SET_ENV_HINT } from "./hostpath.ts";
 // The INVERSE direction (host -> container), for inverting a broker grant's
 // own host-local coordinates before useInstance() ever adopts them (this
@@ -176,6 +180,131 @@ import { CallToolRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 // and every call site.
 import * as backendDetect from "./backend-detect.mts";
 import * as stockDispatch from "./stock-dispatch.ts";
+// Plan 08-02: the single per-backend capability lookup (BACK-05), consumed
+// only inside the CallToolRequestSchema override's tools[name] miss branch
+// below, strictly after the DENY_LIST check -- see the comment at that call
+// site for why the ordering is load-bearing.
+import { capabilityRefusalMessage } from "./capability-registry.ts";
+// Plan 11-05: the curated r2000_* tool surface's DEFINITIONS, imported
+// STATICALLY -- registration below happens synchronously at module scope, so
+// a dynamic import cannot serve it. This costs no child process and no
+// socket: the heavy part (the MCP client, the spawned regenerator2000 child)
+// stays behind r2000-tools.ts's own `await import("./r2000-mcp-client.ts")`
+// inside runR2000Tool() itself, reached only when a tool is actually called.
+import { R2000_TOOL_DEFINITIONS, runR2000Tool } from "./r2000-tools.ts";
+
+// ------------------------------------------------------------ r2000 subcommand
+//
+// D-06 / RESEARCH.md Open Question #1 (plan 10-04): `vice-mcp r2000 <verb>` is
+// the ONLY surface that resolves identically across the Claude Code plugin
+// route and both npm-installer routes -- `installer/bin/cli.mjs`'s
+// `viceServerEntry()` always launches this server via `npx` in BOTH
+// npm-installer modes (`--vendor` only pre-resolves the package; it never
+// places `.claude/mcp/vice/*.ts` as plain files inside a consuming project),
+// so any design resolving a filesystem path to the seam would silently fail
+// to resolve for npm-installed users. This bin is the one surface proven to
+// work in all three routes.
+//
+// This branch runs as the first executable statement of the module body,
+// deliberately ABOVE `ACTIVE_BACKEND`'s backend probe (which shells out to a
+// binary's `--help`), above the manifest read, and above
+// `new MCPServer(...)`/`server.startStdio()` far below -- a CLI invocation
+// must never open a socket, never probe a binary, and never write a byte of
+// JSON-RPC to stdout. WHAT NOT TO DO: never let this branch fall through
+// into the server path, and never print anything on stdout on the server
+// path that a CLI caller could confuse for `r2000` output.
+//
+// Ending the process here is deliberate and is NOT a violation of this
+// file's standing "never end the process from a teardown handler" rule (see
+// that handler's own comment further down): that rule protects the
+// long-lived server's lease-release path, and this branch ends the process
+// before any lease, socket or handler exists. A dynamic import is used
+// (not a static one) so the CLI module is not part of the server's startup
+// cost on the normal, non-`r2000` path.
+//
+// IN-01 (10-REVIEW.md; 11.1-CONTEXT.md AUDIT-01, D-11.1-04): `console.log`/
+// `console.error` writes to `process.stdout`/`process.stderr` are
+// ASYNCHRONOUS on POSIX once the fd is a pipe (Node opens pipe/socket fds
+// non-blocking, unlike a TTY or a regular file), so a bare `process.exit()`
+// immediately after can discard whatever write has not yet drained --
+// measured at a 128 KiB truncation point on this host's Node for a single
+// write exceeding the OS pipe's capacity. The reachable trigger is
+// `cmdExportAsm`'s `console.error(result.stderr)` in r2000-cli.ts, which can
+// carry a large diagnostic from the spawned regenerator2000 child: the one
+// case where the user most needs the diagnostic is exactly the case a piped
+// invocation could silently lose it in. `drainStdio()` below explicitly
+// awaits both streams' own pending writes (a `write("", cb)`-style
+// zero-length write's callback fires only once every prior queued write has
+// actually flushed) before the terminating `process.exit(code)`.
+//
+// T-11.1-EXITHANG: the drain is BOUNDED to `R2000_CLI_DRAIN_TIMEOUT_MS`. An
+// exit that hangs forever waiting on a pipe nobody reads is worse than a
+// truncated diagnostic -- this project's standing rule is that a teardown
+// path never becomes a hang (see the "never end the process from a teardown
+// handler" comment above; a BOUNDED drain here does not violate that rule
+// for the same reason the original unbounded `process.exit()` did not: this
+// still runs before any lease, socket or handler exists, and now also can
+// never block indefinitely).
+const R2000_CLI_DRAIN_TIMEOUT_MS = 300;
+
+/** Resolves once `stream`'s own pending writes have flushed, or after
+ * `timeoutMs`, whichever comes first. A zero-length `write("", cb)`'s
+ * callback fires strictly after every write queued ahead of it on the same
+ * stream has completed -- so this is a genuine drain barrier, not a fixed
+ * sleep. Guarded so a stream that is not writable (already closed/ended,
+ * e.g. under `> /dev/null` teardown races) resolves immediately rather than
+ * calling `write()` on it. */
+function drainStdio(stream: NodeJS.WriteStream): Promise<void> {
+  return new Promise((resolve) => {
+    if (!stream.writable) {
+      resolve();
+      return;
+    }
+    const timer = setTimeout(resolve, R2000_CLI_DRAIN_TIMEOUT_MS);
+    stream.write("", () => {
+      clearTimeout(timer);
+      resolve();
+    });
+  });
+}
+
+if (process.argv[2] === "r2000") {
+  // A broken pipe (the reader closing early, e.g. `| head`) makes
+  // `stream.write()` fail with EPIPE. Awaiting `drainStdio()` below gives
+  // that failure the chance to actually surface as Node's stream 'error'
+  // event -- which throws UNCAUGHT and crashes the process if nothing is
+  // listening, converting what used to be a silent (bare `process.exit()`
+  // outran the async error) success into a stack-trace crash. This
+  // mirrors the SAME EPIPE class this file already guards against for the
+  // server path further down (see that handler's own
+  // modelcontextprotocol/typescript-sdk#1564 citation) -- registered here
+  // too because this branch exits long before reaching that one.
+  process.stdout.on("error", () => {});
+  process.stderr.on("error", () => {});
+
+  // Test-only escape hatch, never documented to end users and inert unless
+  // this exact env var is set: writes a deterministic filler payload
+  // through this SAME drained-exit path, so vice-proxy.test.ts can measure
+  // an exact byte count well above any OS pipe capacity without needing a
+  // real regenerator2000 project (empirically, neither `--help`'s ~5.6 KB
+  // USAGE text nor a synthesized/garbage `.regen2000proj` fed to
+  // export-asm's error path scales anywhere near 128 KiB on this host's
+  // regenerator2000 0.9.20 -- both were measured before this hatch was
+  // added; see 11.1-05-SUMMARY.md for the measurements). Never reachable
+  // from a real `r2000 <verb>` invocation: the check is against a specific,
+  // unambiguous env var name no real caller would ever set.
+  const testFillBytes = process.env.VICE_TEST_R2000_CLI_STDOUT_FILL_BYTES;
+  if (testFillBytes) {
+    process.stdout.write("x".repeat(Number(testFillBytes)));
+    await Promise.all([drainStdio(process.stdout), drainStdio(process.stderr)]);
+    process.exit(0);
+  }
+
+  const { runR2000Cli } = await import("./r2000-cli.ts");
+  const code = await runR2000Cli(process.argv.slice(3));
+  await Promise.all([drainStdio(process.stdout), drainStdio(process.stderr)]);
+  process.exit(code);
+}
 
 const HERE_DIR = dirname(fileURLToPath(import.meta.url));
 
@@ -254,8 +383,19 @@ process.stdout.on("error", (err) => {
 // override that preserves this file's own `{content, isError}` wire
 // contract exactly (see this plan's "Ground truth" section for why
 // MCPServer's OWN tools/call dispatch cannot be used as-is). PROXY_VERSION
-// survives unchanged, reused as MCPServer's own `version` field.
-const PROXY_VERSION = "0.1.0";
+// no longer survives as a hand-edited literal (quick-260819-tsz, D-4/D-5):
+// it used to say "0.1.0" while npm's actual `latest` was twelve patches
+// ahead, because nothing updated it. It is now derived through
+// `runtimeVersion()` (the ONE seam, `./version.ts`), which reads this
+// package's own `package.json` first (the published-tarball path, where
+// `npm version` already stamped a real number) and falls back to the
+// repo-root `VERSION` template -- rendered as `<resolved>-dev` -- only in a
+// git checkout, degrading to `0.0.0-dev` if neither is available. Reused,
+// unchanged, as MCPServer's own `version` field below.
+const PROXY_VERSION = runtimeVersion({
+  pkgJsonPath: join(HERE_DIR, "package.json"),
+  repoRoot: () => repoRoot(),
+});
 
 // --------------------------------------------------------------- tools/list
 //
@@ -3176,7 +3316,11 @@ function buildBackendAwareTool(def: ToolDefinition, forkRun: (args: Record<strin
 }
 
 const tools: Record<string, ReturnType<typeof buildViceTool>> = {};
-for (const def of readManifestTools()) {
+// Read ONCE and reused below for both the manifest loop and the two
+// synthetic registrations' own resolveAdvertisedToolDefinition() calls --
+// never re-read per registration (WR-07, plan 07-16).
+const manifestTools = readManifestTools();
+for (const def of manifestTools) {
   if (DENY_LIST.includes(def.name)) continue;
   tools[def.name] = buildBackendAwareTool(def, (args) => forwardToVice(def.name, args));
 }
@@ -3187,9 +3331,41 @@ for (const def of readManifestTools()) {
 tools[RESULT_CONTINUE_TOOL.name] = buildViceTool(RESULT_CONTINUE_TOOL, (args) => Promise.resolve(handleResultContinue(args)));
 // Backend-AWARE (CR-07): both of these gather evidence over the fork's HTTP
 // transport, so on stock they are refused by name rather than advertised and
-// then failed at the wire.
-tools[RECYCLE_TOOL.name] = buildBackendAwareTool(RECYCLE_TOOL, (args) => handleRecycle(args));
-tools[DIAGNOSE_TOOL.name] = buildBackendAwareTool(DIAGNOSE_TOOL, (args) => handleDiagnose(args));
+// then failed at the wire. WR-07 (plan 07-16): the ADVERTISED definition is
+// now also backend-aware -- resolveAdvertisedToolDefinition() picks the
+// corrected stock manifest entry on stock (falling back to the synthetic
+// definition when the manifest has none) and always returns the synthetic
+// definition unchanged on the fork, so RECYCLE_TOOL/DIAGNOSE_TOOL's literal
+// fork-worded text below no longer overwrites the stock manifest's own
+// entry in `tools/list`.
+tools[RECYCLE_TOOL.name] = buildBackendAwareTool(stockDispatch.resolveAdvertisedToolDefinition(RECYCLE_TOOL, ACTIVE_BACKEND.backend, manifestTools), (args) => handleRecycle(args));
+tools[DIAGNOSE_TOOL.name] = buildBackendAwareTool(stockDispatch.resolveAdvertisedToolDefinition(DIAGNOSE_TOOL, ACTIVE_BACKEND.backend, manifestTools), (args) => handleDiagnose(args));
+// Backend-INDEPENDENT by construction (plan 11-05): the r2000_* family never
+// touches VICE at all -- regenerator2000 is a separate, static-analysis child
+// process, so there is no fork/stock distinction to make and
+// buildBackendAwareTool() would be flatly wrong here (there is nothing for it
+// to dispatch to on either backend). The family is in NEITHER
+// tools-manifest.json NOR tools-manifest.stock.json: both are regenerated by
+// refresh-manifest.ts from a live HOST VICE server's own tools/list, and an
+// r2000 child process is never that host -- a hand-added entry in either
+// manifest would be silently wiped on the next refresh. Registered here via
+// buildViceTool() directly (the SAME exception RESULT_CONTINUE_TOOL above
+// is), so no r2000_* runner can ever reach forwardToVice(), call(), or
+// ensureViceSession() -- CLAUDE.md's "derived tools must be intercepted
+// before forwardToVice()" constraint is satisfied by construction for this
+// family, not by an interception, because the runner is never wired to
+// forwardToVice() in the first place.
+// Deliberately NOT named `def` (the manifest loop's own loop variable,
+// above): `stock-dispatch.test.ts`'s `proxyToolRegistrations()` regex-scans
+// this file's own `tools[...] = ...;` lines and keys each one by its raw
+// captured text, so an identically-named loop variable here would make this
+// registration textually indistinguishable from the manifest loop's -- a
+// distinct name (`r2000Def`) keeps the r2000 family's own exemption from
+// `buildBackendAwareTool()` from ever being confused with, or accidentally
+// widened to cover, the manifest loop's registration.
+for (const r2000Def of R2000_TOOL_DEFINITIONS) {
+  tools[r2000Def.name] = buildViceTool(r2000Def, (args) => runR2000Tool(r2000Def.name, args));
+}
 
 const server = new MCPServer({ name: "vice", version: PROXY_VERSION, tools });
 await server.startStdio();
@@ -3243,6 +3419,19 @@ server.getServer().setRequestHandler(CallToolRequestSchema, async (request) => {
   // .planning/todos/pending/2026-08-05-generic-surface-deny-list-gap-tools-call-nested-vice-disk-list.md.
   const tool = tools[name];
   if (!tool || !tool.execute) {
+    // Layer 3 (BACK-05, plan 08-02): fires ONLY when the ACTIVE backend's
+    // trimmed manifest (D-07) never registered this name -- i.e. `tools`
+    // has no key for it -- and MUST stay strictly after the DENY_LIST check
+    // above: those four meta-tool names are a confused-deputy bypass hazard
+    // (01.4-01), not a capability gap, and must never be reachable here.
+    // This lookup renders undefined for a genuinely unknown name (or a
+    // same-backend miss), so a real typo still falls through to the generic
+    // message below unchanged. capability-registry.ts is the ONE place to
+    // edit this data -- never hand-add a per-tool special case here.
+    const capabilityRefusal = capabilityRefusalMessage(name, ACTIVE_BACKEND.backend);
+    if (capabilityRefusal !== undefined) {
+      return { content: [{ type: "text", text: capabilityRefusal }], isError: true };
+    }
     return { content: [{ type: "text", text: `Unknown tool: ${name}` }], isError: true };
   }
   try {