@henols/vice-mcp 0.1.4

package/README.md

@@ -0,0 +1,66 @@
+# @henols/vice-mcp
+
+A stdio [MCP](https://modelcontextprotocol.io) server that exposes a running
+[VICE](https://vice-emu.sourceforge.io/) Commodore 64 emulator to an MCP client
+(such as Claude Code) for reverse-engineering work. It forwards `vice` tool calls
+to a **host** VICE MCP server, and on first use deploys the host launcher scripts
+it needs into `<project>/tools/`.
+
+This package is normally installed for you by the
+[`@henols/c64-re-tools`](https://www.npmjs.com/package/@henols/c64-re-tools)
+installer, which also drops the matching skills into your project. It is published
+separately so it can be launched directly by an MCP client.
+
+## Requirements
+
+- **Node.js ≥ 22.18** (or ≥ 23.6). The server ships as TypeScript and runs under
+  Node's native type-stripping — no build step, no flags. Older Node needs
+  `--experimental-strip-types` and is unsupported.
+- A **host** with VICE (`x64sc`) available, reachable from wherever the MCP client
+  runs. The server talks to the host VICE MCP server over HTTP (default
+  `http://host.docker.internal:6510/mcp` in a container, `http://127.0.0.1:6510/mcp`
+  otherwise); override with `VICE_MCP_URL` / `VICE_MCP_HOST`.
+
+## Use as an MCP server
+
+Add it to your MCP client configuration and let the client launch it:
+
+```json
+{
+  "mcpServers": {
+    "vice": {
+      "command": "npx",
+      "args": ["-y", "@henols/vice-mcp"],
+      "timeout": 150000,
+      "env": { "MASTRA_TELEMETRY_DISABLED": "1" }
+    }
+  }
+}
+```
+
+The bin (`vice-mcp`) speaks the MCP stdio protocol. `initialize` and `tools/list`
+are answered locally (from `tools-manifest.json`); `tools/call` forwards to the host
+VICE MCP server.
+
+## Environment
+
+| Variable | Purpose |
+| --- | --- |
+| `VICE_MCP_URL` | Full host MCP endpoint (overrides host/port derivation). |
+| `VICE_MCP_HOST` | Host to reach the VICE MCP server on. |
+| `VICE_SKIP_RESOURCE_INSTALL=1` | Disable deploying host launcher scripts into `<project>/tools/`. |
+| `MASTRA_TELEMETRY_DISABLED=1` | Disable Mastra telemetry. |
+
+## Development
+
+```sh
+npm ci
+npm run typecheck
+npm test
+npm run smoke     # boots the server and completes an MCP initialize + tools/list handshake
+npm run build     # recompiles the host-bound .mts launchers into resources/
+```
+
+## License
+
+MIT © Henrik Olsson

package/build.ts

@@ -0,0 +1,268 @@
+// build.ts
+//
+// Compiles the host-bound TypeScript sources (today: vice-broker.mts only --
+// see tsconfig.build.json's `include`, which IS the definition of host-bound)
+// into banner-marked, committed JavaScript under resources/. Run directly as
+// `node build.ts` (native type stripping, no tsc needed to run THIS file --
+// only to run the compiler it shells out to).
+//
+// This file itself must stay inside erasableSyntaxOnly's restrictions (no
+// enum/namespace/constructor parameter properties) so it can run unflagged
+// under bare `node`, exactly like vice-broker.mts.
+import { execFileSync } from "node:child_process";
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+  statSync,
+} from "node:fs";
+import { dirname, join, resolve as resolvePath } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+/** Resolves an `outDir` option (or the CLI's `--out-dir` flag) to an absolute
+ * path: an absolute input is used as-is, a relative one is joined against
+ * this module's own directory. Shared by build() and the CLI success
+ * message below so the two never drift apart. */
+function resolveOutDirAbs(outDir: string): string {
+  return resolvePath(outDir).startsWith("/") && outDir.startsWith("/") ? outDir : join(HERE, outDir);
+}
+
+/** The literal expected emitted relative paths -- today exactly the one
+ * broker artifact. This list IS the host-bound artifact set: build() asserts
+ * the emitted file set equals this exactly, so an unexpected addition or a
+ * silent omission both fail loudly rather than deploying something nobody
+ * reviewed. */
+export const HOST_BOUND_ARTIFACTS: string[] = [
+  "vice-broker.mjs",
+  "container-guard.mjs",
+  "broker-state.mjs",
+  "broker-launch.mjs",
+  "broker-kill.mjs",
+  "broker-epoch.mjs",
+  "broker-control.mjs",
+];
+
+/** The generated-file banner (01.6-RESEARCH.md §F), a function of the
+ * source's relative path. Prepended to every emitted file by build() below --
+ * this is the ONLY place that produces this text, so a sync test built
+ * against the same build() entry point can never observe a second,
+ * independently-drifted banner implementation. */
+export function GENERATED_BANNER(relSourcePath: string): string {
+  return (
+    "// GENERATED FILE -- DO NOT EDIT.\n" +
+    `// Compiled by \`tsc\` from ${relSourcePath}. Edit the TypeScript source and rebuild;\n` +
+    "// changes made directly to this file are silently overwritten by the next build, and are never\n" +
+    "// deployed to the host on their own -- install-resources.mjs copies THIS file's on-disk contents\n" +
+    "// verbatim to tools/, so an edit made only here reaches the host but is lost on the very next\n" +
+    "// rebuild.\n"
+  );
+}
+
+/** Recursive walk of `dir`, returning every `.mjs` file's relative (posix,
+ * "/"-joined) path underneath it. Mirrors install-resources.mjs's own walk()
+ * shape -- a real directory listing, not a hardcoded list. */
+function emittedMjsFilesUnder(dir: string, base = ""): string[] {
+  if (!existsSync(dir)) return [];
+  const out: string[] = [];
+  for (const dirent of readdirSync(dir, { withFileTypes: true })) {
+    const rel = base ? `${base}/${dirent.name}` : dirent.name;
+    const abs = join(dir, dirent.name);
+    if (dirent.isDirectory()) {
+      out.push(...emittedMjsFilesUnder(abs, rel));
+    } else if (dirent.isFile() && dirent.name.endsWith(".mjs")) {
+      out.push(rel);
+    }
+  }
+  return out.sort();
+}
+
+/** Maps an emitted `.mjs` relative path back to the `.mts` source path the
+ * banner should name -- the only mapping this build knows (rootDir "." means
+ * emitted layout mirrors source layout 1:1, with the .mts->.mjs extension
+ * swap tsc performs automatically for module: nodenext). */
+function sourceRelForEmitted(emittedRel: string): string {
+  return emittedRel.replace(/\.mjs$/, ".mts");
+}
+
+export interface BuildOptions {
+  outDir?: string;
+}
+
+/**
+ * Runs the pinned compiler against tsconfig.build.json into a private,
+ * same-filesystem staging directory, asserts the emitted file set is
+ * EXACTLY HOST_BOUND_ARTIFACTS (catches both a missing artifact and an
+ * unexpected one), prepends the generated-file banner to each artifact
+ * WHILE STILL STAGED, then atomically `rename()`s each finished artifact
+ * into `outDir` (default "resources", relative to this module's own
+ * directory or an absolute path).
+ *
+ * Nothing lands at a path inside `outDir` until that path's final bytes
+ * (compiled output plus banner) already exist complete elsewhere, so a
+ * reader of `outDir` -- including a sibling `build()` call's own
+ * resources-sync-style comparison, or a process that spawns an artifact
+ * straight out of `outDir` -- can never observe a partial or banner-less
+ * file. This is per-file atomic replacement, not a lock: no caller in this
+ * repo mutates the .mts sources between builds, so every concurrent build
+ * emits byte-identical output and there is no "which generation wins"
+ * question to answer, only "never expose a half-written file", which
+ * `rename()` onto a fully-finished path already guarantees.
+ *
+ * The staging directory is a SIBLING of `outDir` (never inside it -- a
+ * directory walk over `outDir`, such as resources-sync.test.ts's, must
+ * never see it) on `outDir`'s own filesystem (never `os.tmpdir()`, which
+ * may be a different mount and would make the final rename fail EXDEV). Its
+ * name carries exactly one leading dot and no dot in the tail, so it stays
+ * invisible to this directory's shallow extension-filtered listing gates
+ * (`/\.[cm]?[jt]s$/`). It is removed on every path, success or failure.
+ *
+ * Takes an --out-dir-shaped option rather than always writing to
+ * resources/, so the sync test can build into a scratch directory through
+ * this EXACT code path -- the banner must never exist in two
+ * implementations.
+ */
+/** Where to stage a build before renaming artifacts into `outDirAbs`.
+ *
+ * Two constraints pull in opposite directions, which is why this is its own
+ * function rather than an inline `join`:
+ *
+ * 1. **Same filesystem as `outDirAbs`.** The atomic-replacement guarantee is a
+ *    `renameSync()` per artifact, and `rename(2)` fails `EXDEV` across mounts.
+ *    That is why the original implementation staged at `dirname(outDirAbs)`.
+ * 2. **Outside any directory a test walks.** Staging at `dirname(outDirAbs)`
+ *    put a transient `.build-tmp-*` inside `.claude/mcp/vice/`, and
+ *    `vice-mcp-selector-docs.test.ts`'s `walkFiles()` recurses through every
+ *    directory there except `node_modules` — so a concurrent walk descended
+ *    into the staging dir and died `ENOENT` when the rename removed it. That
+ *    is a race this very function introduced while fixing a different one
+ *    (quick-260804-o09), and constraint 1 is why the obvious fix of "just move
+ *    it somewhere else" is not obvious.
+ *
+ * `node_modules/.cache/` satisfies both **when the default `outDir` is in
+ * play**: it is under `HERE`, so same-filesystem; it is the one directory that
+ * walk structurally excludes; and `build()` already requires
+ * `node_modules/.bin/tsc` to exist, so it can never be absent when a build can
+ * run at all.
+ *
+ * When a caller passes an `outDir` on a *different* device — `resources-sync`
+ * builds into a scratch dir, which may be another mount — the preferred
+ * location would make every `renameSync()` throw `EXDEV`, so this falls back
+ * to the adjacent sibling. That fallback keeps correctness and gives up only
+ * walk-invisibility, which costs nothing there: no test walks a scratch dir's
+ * parent. Device identity is compared via `statSync().dev` rather than assumed
+ * from the path shape. */
+export function resolveStagingParent(outDirAbs: string): string {
+  const adjacent = dirname(outDirAbs);
+  const preferred = join(HERE, "node_modules", ".cache");
+  try {
+    mkdirSync(preferred, { recursive: true });
+    if (statSync(preferred).dev === statSync(adjacent).dev) return preferred;
+  } catch {
+    // node_modules absent or unwritable -- fall through to the adjacent
+    // sibling, which is where this always used to stage.
+  }
+  return adjacent;
+}
+
+export function build({ outDir = "resources" }: BuildOptions = {}): void {
+  const outDirAbs = resolveOutDirAbs(outDir);
+  // Runs first, and MUST: when resolveStagingParent() falls back to the
+  // adjacent sibling, recursive mkdirSync of outDirAbs is what guarantees that
+  // parent directory exists before mkdtempSync needs it.
+  mkdirSync(outDirAbs, { recursive: true });
+
+  const stagingDir = mkdtempSync(join(resolveStagingParent(outDirAbs), ".build-tmp-" + process.pid + "-"));
+  try {
+    const tscBin = join(HERE, "node_modules", ".bin", "tsc");
+    execFileSync(tscBin, ["-p", join(HERE, "tsconfig.build.json"), "--outDir", stagingDir], {
+      cwd: HERE,
+      stdio: "inherit",
+    });
+
+    const emitted = emittedMjsFilesUnder(stagingDir);
+    const expected = [...HOST_BOUND_ARTIFACTS].sort();
+    const missing = expected.filter((f) => !emitted.includes(f));
+    const unexpected = emitted.filter((f) => !expected.includes(f));
+
+    if (missing.length > 0 || unexpected.length > 0) {
+      throw new Error(
+        "build: emitted file set does not match HOST_BOUND_ARTIFACTS.\n" +
+          `  expected:   ${JSON.stringify(expected)}\n` +
+          `  emitted:    ${JSON.stringify(emitted)}\n` +
+          `  missing:    ${JSON.stringify(missing)}\n` +
+          `  unexpected: ${JSON.stringify(unexpected)}`
+      );
+    }
+
+    // Banner every staged artifact BEFORE any rename -- a half-bannered
+    // file must never become reachable at an `outDir` path.
+    for (const rel of HOST_BOUND_ARTIFACTS) {
+      const staged = join(stagingDir, rel);
+      const banner = GENERATED_BANNER(sourceRelForEmitted(rel));
+      const content = readFileSync(staged, "utf8");
+      if (!content.startsWith(banner)) {
+        writeFileSync(staged, banner + content);
+      }
+    }
+
+    // Move each finished artifact into place. Iterates the artifact list,
+    // not a walk of stagingDir, so a hand-authored file that also lives
+    // under outDir (resources/vice-launcher.sh) is never a rename source or
+    // target -- it was never staged and is left untouched.
+    for (const rel of HOST_BOUND_ARTIFACTS) {
+      const from = join(stagingDir, rel);
+      const to = join(outDirAbs, rel);
+      try {
+        renameSync(from, to);
+      } catch (e) {
+        const detail = (e as NodeJS.ErrnoException).code === "EXDEV" ? " (EXDEV: staging dir and outDir are on different filesystems -- outDir must be reachable via a same-filesystem sibling)" : "";
+        throw new Error(`build: failed to move staged artifact into place: ${from} -> ${to}${detail}`, { cause: e });
+      }
+    }
+
+    // tsc emits exactly HOST_BOUND_ARTIFACTS today (verified). A leftover
+    // here means the compiler started emitting something this list does not
+    // describe -- fail loudly rather than silently drop a file that used to
+    // reach outDir.
+    const leftovers = readdirSync(stagingDir);
+    if (leftovers.length > 0) {
+      throw new Error(
+        `build: staging directory still holds file(s) after moving every HOST_BOUND_ARTIFACTS entry -- ` +
+          `the compiler emitted something not in that list: ${JSON.stringify(leftovers)}`
+      );
+    }
+  } finally {
+    rmSync(stagingDir, { recursive: true, force: true });
+  }
+}
+
+// -------------------------------------------------------------------- CLI
+function parseCliArgs(argv: string[]): BuildOptions {
+  let outDir: string | undefined;
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === "--out-dir") {
+      outDir = argv[i + 1];
+      i++;
+    }
+  }
+  return outDir ? { outDir } : {};
+}
+
+if (process.argv[1] && resolvePath(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const opts = parseCliArgs(process.argv.slice(2));
+  try {
+    build(opts);
+    const outDirAbs = resolveOutDirAbs(opts.outDir ?? "resources");
+    process.stderr.write(`build: wrote ${HOST_BOUND_ARTIFACTS.length} artifact(s) to ${outDirAbs}\n`);
+  } catch (e) {
+    process.stderr.write(`build: FAILED -- ${(e as Error).message}\n`);
+    process.exitCode = 1;
+  }
+}

package/container-guard.mts

@@ -0,0 +1,226 @@
+// container-guard.mts
+//
+// PD-03: TypeScript port of resources/lib/container-guard.sh's five
+// container-detection signals, checked at broker PROCESS STARTUP -- not
+// only at vice-launcher.sh's shell wrapper. This closes the
+// invocation-scoped hole recorded in RE-FINDINGS.md (2026-08-03): running
+// the compiled broker directly (bypassing the launcher) was previously
+// unguarded, since the bash guard only ever ran inside the scripts that
+// sourced it.
+//
+// Every dependency this needs (filesystem existence/reads, the environment,
+// a subprocess runner for systemd-detect-virt) is injected with real
+// defaults, so every signal is exercised in a test without a real
+// /proc/1/cgroup or a real systemd-detect-virt binary on the machine
+// running the test.
+import { existsSync, readFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+
+export interface ContainerSignal {
+  description: string;
+  fired: boolean;
+  evidence: string;
+}
+
+export interface ContainerGuardDeps {
+  fileExists: (path: string) => boolean;
+  readFile: (path: string) => string;
+  env: NodeJS.ProcessEnv;
+  runSystemdDetectVirt: () => string | null; // null = binary not present or errored
+}
+
+const defaultDeps: ContainerGuardDeps = {
+  fileExists: (path) => existsSync(path),
+  readFile: (path) => readFileSync(path, "utf8"),
+  env: process.env,
+  runSystemdDetectVirt: () => {
+    try {
+      return execFileSync("systemd-detect-virt", ["--container"], { encoding: "utf8" }).trim();
+    } catch {
+      return null;
+    }
+  },
+};
+
+/** Matches container-guard.sh's own awk cgroup matcher: the field after the
+ * LAST colon on any /proc/1/cgroup line, tested against a container-naming
+ * path component. Deliberately does NOT match a systemd host's
+ * `0::/init.scope`, a bare root cgroup, or the Docker daemon's own
+ * `/system.slice/docker.service` cgroup -- only `/docker/<id>`,
+ * `/system.slice/docker-<id>.scope`, `/kubepods/...`, `/libpod-...` and
+ * `/lxc/...` match. */
+function cgroupNamesContainer(cgroupText: string): string | null {
+  const CONTAINER_PATH = /(^|\/)(docker|lxc|kubepods|libpod)(\/|-|$)/;
+  for (const line of cgroupText.split("\n")) {
+    const idx = line.lastIndexOf(":");
+    if (idx === -1) continue;
+    const path = line.slice(idx + 1);
+    if (CONTAINER_PATH.test(path)) return line;
+  }
+  return null;
+}
+
+/** Evaluates all five signals and returns one ContainerSignal per signal
+ * (fired or not, with its evidence) -- the same two-array shape
+ * container_guard_evaluate() builds (CONTAINER_SIGNALS/CONTAINER_REPORT),
+ * as one typed return value.
+ *
+ * REMOVED, DO NOT RE-ADD: a `grep docker /proc/self/mountinfo` signal used
+ * to exist here (ported from the bash guard's own header). It answers "is
+ * Docker installed on this machine", not "is THIS process inside a
+ * container" -- it fires on the real host (which runs the devcontainer
+ * daemon) and refuses to launch on exactly the machine this guard exists to
+ * allow. Not fixable by tightening the pattern; the signal itself is
+ * invalid. It is gone in the bash version and must not come back here
+ * either. */
+export function evaluateContainerSignals(deps: ContainerGuardDeps = defaultDeps): ContainerSignal[] {
+  const signals: ContainerSignal[] = [];
+
+  signals.push({
+    description: "/.dockerenv exists",
+    fired: deps.fileExists("/.dockerenv"),
+    evidence: "",
+  });
+
+  signals.push({
+    description: "/run/.containerenv exists (podman)",
+    fired: deps.fileExists("/run/.containerenv"),
+    evidence: "",
+  });
+
+  const workspacePath = deps.env.CONTAINER_WORKSPACE_PATH;
+  signals.push({
+    description: "CONTAINER_WORKSPACE_PATH is set (this devcontainer sets it)",
+    fired: Boolean(workspacePath),
+    evidence: workspacePath ?? "",
+  });
+
+  const detectedVirt = deps.runSystemdDetectVirt();
+  const virtFired = detectedVirt !== null && detectedVirt !== "" && detectedVirt !== "none";
+  signals.push({
+    description: "systemd-detect-virt --container",
+    fired: virtFired,
+    evidence: detectedVirt === null ? "binary not present, signal skipped" : `reports: ${detectedVirt || "none"}`,
+  });
+
+  let cgroupMatch: string | null = null;
+  if (deps.fileExists("/proc/1/cgroup")) {
+    try {
+      cgroupMatch = cgroupNamesContainer(deps.readFile("/proc/1/cgroup"));
+    } catch {
+      cgroupMatch = null;
+    }
+  }
+  signals.push({
+    description: "/proc/1/cgroup path names a container",
+    fired: cgroupMatch !== null,
+    evidence: cgroupMatch ?? "no container path component in PID 1's cgroup",
+  });
+
+  return signals;
+}
+
+/** Prints one report line per signal to stderr and returns 3 in a container
+ * (>=1 signal fired), 0 on a host (none fired) -- mirrors
+ * container_guard_report()'s exit-code contract exactly. Never calls
+ * process.exit() itself (D-4 discipline this module tree observes
+ * throughout): the caller (vice-broker.mts's CLI wrapper) turns the
+ * returned code into process.exitCode. */
+export function containerGuardReport(deps: ContainerGuardDeps = defaultDeps): number {
+  const signals = evaluateContainerSignals(deps);
+  process.stderr.write("vice-broker: container guard evaluation\n");
+  for (const s of signals) {
+    if (s.fired) {
+      process.stderr.write(`  [FIRED] ${s.description}${s.evidence ? ` -- evidence: ${s.evidence}` : ""}\n`);
+    } else {
+      process.stderr.write(`  [clear] ${s.description}${s.evidence ? ` (${s.evidence})` : ""}\n`);
+    }
+  }
+  const fired = signals.filter((s) => s.fired);
+  if (fired.length > 0) {
+    process.stderr.write(`verdict: CONTAINER (${fired.length} signal(s) fired) -- the guard would refuse here.\n`);
+    return 3;
+  }
+  process.stderr.write("verdict: HOST (no signals fired) -- the guard would allow x64sc to launch here.\n");
+  return 0;
+}
+
+/** Evaluates the guard and, if any signal fired, writes a FATAL block naming
+ * every fired signal and returns 2 -- UNLESS VICE_SUPERVISOR_ALLOW_CONTAINER
+ * is EXACTLY "1" (testing only; never set it to actually run VICE). On a
+ * clear host verdict, returns 0 and writes nothing. Mirrors
+ * container_guard_enforce()'s escape hatch, wording and exit-code contract
+ * verbatim -- never calls process.exit() itself, matching
+ * containerGuardReport()'s own posture above. */
+export function containerGuardEnforce(deps: ContainerGuardDeps = defaultDeps): number {
+  const signals = evaluateContainerSignals(deps);
+  const fired = signals.filter((s) => s.fired);
+  if (fired.length > 0 && deps.env.VICE_SUPERVISOR_ALLOW_CONTAINER !== "1") {
+    process.stderr.write("FATAL: vice-broker refuses to run inside a container.\n");
+    process.stderr.write("This process is HOST-ONLY. Signals that fired:\n");
+    for (const s of fired) {
+      process.stderr.write(`  - ${s.description}${s.evidence ? ` -- ${s.evidence}` : ""}\n`);
+    }
+    process.stderr.write("\n");
+    process.stderr.write("If you believe this IS the host, run --check-container for the full\n");
+    process.stderr.write("per-signal breakdown and report which signal is wrong.\n");
+    process.stderr.write("\n");
+    process.stderr.write("This cannot work in here: there is no x64sc binary, no display, and\n");
+    process.stderr.write("the entire point of this process is to launch or supervise a process\n");
+    process.stderr.write("the container has no access to in the first place.\n");
+    process.stderr.write("\n");
+    process.stderr.write("Escape hatch (TESTING ONLY -- never to actually run VICE):\n");
+    process.stderr.write("  VICE_SUPERVISOR_ALLOW_CONTAINER=1\n");
+    process.stderr.write("\n");
+    process.stderr.write("Run this broker on the HOST instead, from the host workspace.\n");
+    return 2;
+  }
+  return 0;
+}
+
+// -------------------------------------------------- environment predicate
+//
+// containerGuardReport()/containerGuardEnforce() above answer "should this
+// process REFUSE to run here". This answers the different question "which
+// environment am I in", for callers that must CHOOSE behaviour rather than
+// refuse -- specifically vice.ts's mcpHost(), which has to return the
+// container-visible bridge alias inside a container and a loopback address
+// on a host, because `host.docker.internal` is a Docker-provided alias that
+// does not resolve on the host at all.
+//
+// It shares this module's detection deliberately rather than growing a
+// second, weaker copy. That is the exact mistake this file's own header
+// records for the REMOVED /proc/self/mountinfo signal: an independent
+// "looks dockery" heuristic fired on the real host -- the machine running
+// the devcontainer daemon -- and so answered the wrong question. Any new
+// detector would risk re-earning that bug; this one is already calibrated
+// against precisely the host-versus-container distinction being asked here.
+//
+// The verdict rule is not invented here: it is the one containerGuardReport()
+// and containerGuardEnforce() both state -- >=1 signal fired means CONTAINER,
+// none fired means HOST.
+
+/** Memoised verdict for the default-deps path only. */
+let cachedDefaultVerdict: boolean | null = null;
+
+/** True inside a container, false on a host.
+ *
+ * MEMOISED on the default-deps path, deliberately: one of the five signals
+ * shells out to `systemd-detect-virt`, and mcpHost() is read fresh on EVERY
+ * forwarded tool call -- spawning a subprocess per call would be a real cost
+ * for an answer that cannot change. Container membership is fixed for a
+ * process lifetime, so caching the verdict is safe. Note what is NOT cached:
+ * the caller's own env-var read (`VICE_MCP_HOST`) stays fresh, preserving the
+ * override-sensitivity mcpHost()'s comment says a module-level constant would
+ * have silently destroyed.
+ *
+ * Passing explicit deps ALWAYS re-evaluates and never touches the cache, so
+ * tests can drive both branches in-process, in any order, without one test's
+ * verdict leaking into another's. */
+export function isInsideContainer(deps?: ContainerGuardDeps): boolean {
+  if (deps) return evaluateContainerSignals(deps).some((s) => s.fired);
+  if (cachedDefaultVerdict === null) {
+    cachedDefaultVerdict = evaluateContainerSignals(defaultDeps).some((s) => s.fired);
+  }
+  return cachedDefaultVerdict;
+}