@ravefox/space 0.0.0-stage → 0.2.1

package/src/lib/mcp-home.js

@@ -0,0 +1,644 @@
+/**
+ * Where a seat's `@commonlyai/mcp` is executed FROM.
+ *
+ * Why this exists (TASK-174). Every seat's default declaration is
+ * `npx -y @commonlyai/mcp@latest` (default-environment.js), and npx names its
+ * cache dir by the hash of the SPEC STRING — npm 11.12.1,
+ * libnpmexec/lib/index.js:238-250, sha512(spec)[0:16]. So
+ * sha512('@commonlyai/mcp@latest')[0:16] = 6d82e98be466b586 is ONE dir shared by
+ * every seat, rewritten in place when the first spawn after a publish sees a new
+ * version, and every npx run does registry + lock work before the server is even
+ * started. Two failures were measured on 2026-09-27: seats lost the server for
+ * minutes after the 0.3.13 publish at 10:47:57Z (the in-place rebuild), and Vera
+ * got a 30 s CONNECT_TIMEOUT with no publish at all (the shared dir's mtime
+ * moves on every npx run, so a slow registry round-trip alone exceeds the
+ * client's connect budget).
+ *
+ * The fix takes npx OFF the spawn path. A spawn executes
+ * `node <home>/<version>/node_modules/@commonlyai/mcp/<bin>` for the version a
+ * pointer file names; versions are installed by EXACT spec into their own
+ * version dir by a background single-flight warm (mcp-warm-child.mjs), and the
+ * pointer moves only after the new bin answers MCP `initialize`.
+ *
+ * The DECLARATION is not touched. `declared-mcp-guard.isShippedCommonlyMcpEntry`
+ * still audits `npx -y @commonlyai/mcp@latest` verbatim (TASK-150) — that guard
+ * judges what an operator declared, and this module only changes what a spawn
+ * executes. A declaration that PINS a version is never rewritten: that is the
+ * operator saying which build to run, and the npx cache already gives a pinned
+ * spec its own dir.
+ *
+ * The cold path is pinned too (TASK-174's second half). A spawn with no usable
+ * home still runs the declaration, but not with the shared `@latest` spec: the
+ * spec this spawn executes is the version the registry already answered with,
+ * read from the warm's own cache, so `@latest`'s one shared npx dir is not on
+ * the spawn path even once. The fallback is the declaration as written, and it
+ * is used exactly when nothing has ever resolved a version on this host — a
+ * fresh machine's first spawn, where `@latest` is also the only spec that could
+ * work — or when the cache is unreadable. Nothing here throws.
+ *
+ * Every filesystem answer here is injected, because the two states that matter
+ * (a home that has never been warmed, and a home whose pointed-at version dir was
+ * deleted under it) cannot both be produced on one host.
+ */
+import { spawn } from 'node:child_process';
+import {
+  existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync,
+} from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, relative, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { isShippedCommonlyMcpCommand } from './declared-mcp-guard.js';
+import { MCP_PACKAGE, exactVersion, parseVersion } from './mcp-server-version.js';
+
+/** The env override, so tests (and an operator) can point the home elsewhere. */
+export const MCP_HOME_ENV = 'COMMONLY_MCP_HOME';
+/**
+ * TASK-273: a public seat whose MCP server has no host-prepared build does not
+ * run the turn. Spawning without its tools left the model nothing to do but
+ * narrate the failure, and the run loop posted that narration to a stranger
+ * (Commonly HQ, 2026-10-15: "The commonly MCP server failed to connect… check
+ * the MCP server config"). Refusing before the model call posts nothing: the
+ * turn fails, the event stays unacked and is retried once the warm finishes,
+ * and the seat log names the reason. Every adapter raises this one error.
+ */
+export const PUBLIC_MCP_UNAVAILABLE_CODE = 'public_mcp_unavailable';
+export const publicMcpUnavailableError = (names) => {
+  const error = new Error(
+    `public seat refused this turn: MCP server ${names.join(', ')} has no host-prepared build yet, `
+    + 'so the model was not run and nothing was posted',
+  );
+  error.code = PUBLIC_MCP_UNAVAILABLE_CODE;
+  return error;
+};
+
+export const WARM_LOCK_NAME = '.warm.lock';
+export const REGISTRY_CACHE_NAME = '.registry.json';
+
+/** How long a cached registry answer is trusted before the warm re-checks. */
+export const REGISTRY_TTL_MS = 15 * 60 * 1000;
+
+/** A lock older than this is a warm that died; reclaim rather than wedge. */
+export const STALE_LOCK_MS = 10 * 60 * 1000;
+
+/**
+ * Version dirs kept after a successful advance.
+ *
+ * This is a DISK BOUND, not the safety rule. Retention by count cannot express
+ * "not while someone is running it": keeping the newest three protects the
+ * newest three, and a seat still executing the fourth-newest dir is exactly the
+ * case that matters. A DIR IS REMOVABLE only when it is not `current`, carries
+ * no LIVE liveness claim, and is past `PRUNE_GRACE_MS` (Vera, 74878/74887).
+ */
+export const KEEP_VERSION_DIRS = 3;
+
+/**
+ * A version dir younger than this is never pruned, even with no live claimant.
+ *
+ * Time, not count, is what bounds the exposure: a dir inside the window may
+ * belong to a spawn that is starting up and has not written its claim yet, or
+ * whose claim was written by a pid the kernel has since recycled.
+ */
+export const PRUNE_GRACE_MS = 24 * 60 * 60 * 1000;
+
+/** Where a spawn records that a process may still be executing from a version. */
+export const IN_USE_DIR_NAME = '.inuse';
+
+/** The warm child's own exit codes, read by the spawn path's logs. */
+export const WARM_RESULTS = Object.freeze({
+  LOCKED: 'locked',
+  CURRENT: 'current',
+  ADVANCED: 'advanced',
+  REGISTRY_UNAVAILABLE: 'registry-unavailable',
+  INSTALL_FAILED: 'install-failed',
+  PROBE_FAILED: 'probe-failed',
+});
+
+export const mcpHomeDir = (env = process.env) => {
+  const configured = env && env[MCP_HOME_ENV];
+  // A DEFECT THIS LITERALLY PREVENTED, 2026-09-27: `process.env.X = undefined`
+  // does not unset X, it sets the STRING "undefined" (Node coerces env values),
+  // so a caller that saved and restored an unset override handed the warm the
+  // home `./undefined/` — which it created, populated and pointed at, inside the
+  // package directory. This value is a PATH; a value that is not a plausible
+  // path is not a home, and the real home is the safe answer.
+  if (typeof configured === 'string' && configured && configured !== 'undefined' && configured !== 'null') {
+    return configured;
+  }
+  return join(homedir(), '.commonly', 'mcp');
+};
+
+/** True for a home a warm may write into: a real, absolute-looking path. */
+export const isUsableWarmHome = (home) => (
+  typeof home === 'string'
+  && home.length > 1
+  && home !== 'undefined'
+  && home !== 'null'
+  && (home.startsWith('/') || /^[A-Za-z]:[\\/]/.test(home))
+);
+
+/** The home a caller asked for, or the configured one — never a junk string. */
+export const resolveHomeDir = (home) => (isUsableWarmHome(home) ? home : mcpHomeDir());
+
+export const currentPointerPath = (home) => join(home, 'current');
+
+/**
+ * Where a version dir name that is not a triple lands: inside the home, and
+ * never a version (a version starts with a digit), so every read of it misses
+ * and the spawn falls back to its declaration. The alternative — building the
+ * path from whatever string arrived — is how `0.3.13/../../../../tmp/x` resolved
+ * outside the home, and #1970's `startsWith(pkgDir)` confinement is computed
+ * FROM that dir, so it would have confined to the wrong place (Vera, 74938).
+ */
+const UNUSABLE_VERSION_DIR = '.unusable-version';
+
+/**
+ * A version dir, built from the parsed triple — and only when the string given
+ * IS that triple.
+ *
+ * Refusing beats rebuilding here: this result is what the warm RENAMES into and
+ * what the pruner REMOVES, so silently rewriting `0.3.14-rc.1` to `0.3.14` would
+ * aim both at a different build. Normalising belongs at the producer of a
+ * version value (`resolveRegistryLatest`, `readCurrentVersion`,
+ * `readRegistryCache`, `pinShippedSpec`), where the choice is deliberate and
+ * visible; a producer that names something else gets a name no version can have.
+ */
+export const versionDirFor = (home, version) => {
+  const triple = exactVersion(version);
+  const name = triple && triple === String(version).trim() ? triple : UNUSABLE_VERSION_DIR;
+  return join(home, name);
+};
+export const packageDirFor = (home, version) => join(versionDirFor(home, version), 'node_modules', MCP_PACKAGE);
+export const lockPathFor = (home) => join(home, WARM_LOCK_NAME);
+
+/** `<home>/<version>/.inuse/` — one empty file per claiming pid. */
+export const inUseDirFor = (home, version) => join(versionDirFor(home, version), IN_USE_DIR_NAME);
+export const inUseMarkerPath = (home, version, pid) => join(inUseDirFor(home, version), String(pid));
+
+/** A pid is a positive integer, or it is not a pid. */
+const parsePid = (value) => {
+  const pid = Number(value);
+  return Number.isInteger(pid) && pid > 0 ? pid : null;
+};
+
+/**
+ * Is this pid still running? `kill(pid, 0)` asks the kernel and sends nothing.
+ *
+ * EPERM means the pid exists and belongs to another user — alive. ESRCH means
+ * gone — dead. Anything else, including a value that was never a pid, is DEAD,
+ * because the two errors are not symmetric: guessing "alive" pins a version dir
+ * forever (unbounded disk with extra steps), while guessing "dead" costs one
+ * reinstall on a later warm.
+ */
+export const isPidAlive = (pid, { kill = process.kill } = {}) => {
+  const parsed = parsePid(pid);
+  if (parsed === null) return false;
+  try {
+    kill(parsed, 0);
+    return true;
+  } catch (error) {
+    return Boolean(error) && error.code === 'EPERM';
+  }
+};
+
+/**
+ * The claimants under a version dir that are still running.
+ *
+ * The marker's PRESENCE is not the signal — a seat that is killed or crashes
+ * leaves its file behind, and a pruner that read presence would never remove
+ * that version again. The check is whether the claimant still exists; a dead or
+ * unparseable marker counts as absent.
+ */
+export const liveInUsePids = (home, version, {
+  readDir = (dir) => {
+    try {
+      return readdirSync(dir);
+    } catch {
+      return [];
+    }
+  },
+  isAlive = isPidAlive,
+} = {}) => readDir(inUseDirFor(home, version))
+  .map(parsePid)
+  .filter((pid) => pid !== null && isAlive(pid));
+
+/**
+ * Claim a version dir for a process that may be executing from it.
+ *
+ * Called by `prepareMcpSpawn`, keyed by THIS process: the MCP server runs as a
+ * descendant of the process that materialised the command, so while that process
+ * lives its version dir must not be pruned. A claim that cannot be written is
+ * reported, never swallowed: `prepareMcpSpawn` refuses to exec from a dir it
+ * could not claim (Vera 74903), because an unclaimed dir is one the pruner is
+ * free to `rm -rf` while this seat is running out of it.
+ */
+export const claimInUse = ({
+  home,
+  version,
+  pid = process.pid,
+  mkdir = mkdirSync,
+  writeFile = writeFileSync,
+} = {}) => {
+  try {
+    if (!isUsableWarmHome(home) || !parseVersion(version) || parsePid(pid) === null) {
+      return { claimed: false, reason: 'not_claimable' };
+    }
+    mkdir(inUseDirFor(home, version), { recursive: true });
+    writeFile(inUseMarkerPath(home, version, pid), '');
+    return { claimed: true, reason: null };
+  } catch (error) {
+    // The errno is the difference between a home nobody can write to and a
+    // `.inuse` path that is a file, and only one of those is worth a log line
+    // that says which.
+    return { claimed: false, reason: (error && error.code) || 'claim_failed' };
+  }
+};
+
+/**
+ * Say it out loud. A seat whose claim failed is still a seat, but it must not be
+ * a silent one: warn() is injectable so a test can hold the sentence.
+ */
+const defaultWarn = (line) => {
+  try {
+    process.stderr.write(`${line}\n`);
+  } catch { /* a seat that cannot warn still runs */ }
+};
+
+const defaultRead = (path) => {
+  try {
+    return existsSync(path) ? readFileSync(path, 'utf8') : null;
+  } catch {
+    return null;
+  }
+};
+
+const defaultExists = (path) => {
+  try {
+    return existsSync(path);
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * The version the pointer file names, or null.
+ *
+ * A pointer that does not parse is treated as no pointer at all: a spawn must
+ * never build a path out of a string it did not validate, and the fallback is
+ * the declared command, not a guess.
+ */
+export const readCurrentVersion = (home, { readFile = defaultRead } = {}) => {
+  const raw = readFile(currentPointerPath(home));
+  if (typeof raw !== 'string') return null;
+  const version = exactVersion(raw.trim());
+  return version || null;
+};
+
+/**
+ * The bin a package.json beside a script names, resolved — never guessed.
+ *
+ * `bin` is `{ 'commonly-mcp': 'src/index.js' }` at 0.3.13 and a bare string in
+ * older releases, so both shapes are read. A dir whose bin is missing on disk is
+ * not a build this seat can run: returning null there is what sends a spawn back
+ * to the declared command instead of exec'ing a path that does not exist.
+ */
+const readBinInPackageDir = (pkgDir, {
+  readFile = defaultRead, exists = defaultExists,
+} = {}) => {
+  const raw = readFile(join(pkgDir, 'package.json'));
+  if (typeof raw !== 'string') return null;
+  let pkg;
+  try {
+    pkg = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!pkg || typeof pkg !== 'object') return null;
+  // A package.json naming another package settles it: this dir is not ours.
+  if (pkg.name !== undefined && pkg.name !== MCP_PACKAGE) return null;
+  const bin = pkg.bin;
+  let relative = null;
+  if (typeof bin === 'string' && bin) {
+    relative = bin;
+  } else if (bin && typeof bin === 'object') {
+    const keys = Object.keys(bin).filter((k) => typeof bin[k] === 'string' && bin[k]);
+    if (keys.length === 1) [relative] = keys.map((k) => bin[k]);
+    else if (typeof bin['commonly-mcp'] === 'string' && bin['commonly-mcp']) relative = bin['commonly-mcp'];
+  }
+  if (!relative) return null;
+  const binPath = join(pkgDir, relative);
+  // `join` resolves `..`, so this is the whole confinement. The package is our
+  // own published build and today `bin` cannot escape — but a check that costs
+  // one line makes the exec path self-evident instead of trusted (Vera, 74880).
+  if (!binPath.startsWith(`${pkgDir}${sep}`)) return null;
+  return exists(binPath) ? binPath : null;
+};
+
+/** The bin of a version dir inside the seat's home. */
+export const readBinPath = (home, version, options = {}) => {
+  // Truthiness of `parseVersion` is truthiness of `exactVersion`; the check that
+  // matters here is `versionDirFor` refusing a name that is not a triple, so a
+  // reader naming `0.3.14-rc.1` gets nothing rather than 0.3.14's build.
+  if (!parseVersion(version)) return null;
+  return readBinInPackageDir(packageDirFor(home, version), options);
+};
+
+/** Read grant for only the verified warm build selected for this spawn. */
+export const selectedMcpVersionDir = (command, home = mcpHomeDir()) => {
+  if (!Array.isArray(command) || command.length !== 2 || command[0] !== 'node') return null;
+  const version = relative(home, command[1]).split(sep)[0];
+  if (exactVersion(version) !== version || readBinPath(home, version) !== command[1]) return null;
+  return versionDirFor(home, version);
+};
+
+/**
+ * Whether the warm build this spawn runs writes the ready file (F421).
+ *
+ * A public OpenCode seat's stream reports nothing about its MCP servers, so the
+ * adapter names a file the Commonly server creates once its host reaches it
+ * (commonly-mcp/src/ready-file.js) and withholds a turn that ends without it.
+ * Only a release that says so in its package.json (`commonly.readyFile`) is
+ * asked: a build from before the file existed would leave every turn withheld.
+ * Anything this cannot read or verify answers false, which keeps the turn as it
+ * was before F421.
+ */
+export const selectedMcpWritesReadyFile = (command, home = mcpHomeDir(), { readFile = defaultRead } = {}) => {
+  if (!selectedMcpVersionDir(command, home)) return false;
+  const version = relative(home, command[1]).split(sep)[0];
+  const raw = readFile(join(packageDirFor(home, version), 'package.json'));
+  if (typeof raw !== 'string') return false;
+  try {
+    const pkg = JSON.parse(raw);
+    return pkg?.name === MCP_PACKAGE && pkg?.commonly?.readyFile === true;
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * The bin of an npm PREFIX dir, which is the shape the warm installs into:
+ * `npm install --prefix <dir>` leaves `<dir>/node_modules/...`, with no version
+ * component in the path. Reading the two shapes with one function would mean
+ * looking for a version dir inside the temp prefix and concluding the install
+ * failed when it did not.
+ */
+export const readBinInPrefix = (prefix, options = {}) => (
+  readBinInPackageDir(join(prefix, 'node_modules', MCP_PACKAGE), options)
+);
+
+/**
+ * The newest version dir in the home that actually has a runnable bin.
+ *
+ * The pointer is only written after a verified warm, so it is normally the whole
+ * answer. This is the recovery path for the case the pointer cannot cover: the
+ * pointed-at version dir deleted under a live seat (hand-pruned, a wiped home,
+ * npm falling back to a reinstall). Falling back to the next-newest local build
+ * keeps the spawn off npx even then, which is the whole point of the change.
+ */
+export const newestInstalledVersion = (home, {
+  readDir = (dir) => {
+    try {
+      return readdirSync(dir);
+    } catch {
+      return [];
+    }
+  },
+  readBin = (h, v) => readBinPath(h, v),
+} = {}) => {
+  const versions = readDir(home)
+    // An exact triple, not a prefix match: a dir literally named `0.3.13-rc.1`
+    // is not `0.3.13`, and normalising the name would point this read at a dir
+    // the caller never mentioned.
+    .filter((name) => exactVersion(name) === name)
+    .filter((name) => readBin(home, name))
+    .sort((a, b) => {
+      const [am, an, ap] = parseVersion(a);
+      const [bm, bn, bp] = parseVersion(b);
+      return (am - bm) || (an - bn) || (ap - bp);
+    });
+  return versions.length ? versions[versions.length - 1] : null;
+};
+
+/** True for the shipped, UNPINNED spec — the only command shape this rewrites. */
+const isUnpinnedShippedSpec = (spec) => (
+  spec === MCP_PACKAGE || spec === `${MCP_PACKAGE}@latest`
+);
+
+/**
+ * The shipped command with its spec pinned to `version`, or the command
+ * unchanged when there is no version to pin to.
+ *
+ * Only slot 2 is touched, and only after `isShippedCommonlyMcpCommand` has
+ * proven the slot is the package spec — so `npx`, its `-y` and every other
+ * entry survive byte-for-byte, and a command that is not the shipped 3-arg form
+ * cannot be rewritten by construction. npx keys its cache dir by the spec
+ * string, which is the whole point: `@latest` is one dir every seat shares and a
+ * publish rewrites in place, while `@0.3.13` is a dir only this version ever
+ * uses.
+ */
+export const pinShippedSpec = (command, version) => {
+  // The triple, not the string: this spec is an argv entry we execute, so a
+  // version carrying a suffix must not reach it.
+  const safe = exactVersion(version);
+  if (!Array.isArray(command) || !safe) return command;
+  let changed = false;
+  const pinned = command.map((part, index) => {
+    // Slot 2 only. `isShippedCommonlyMcpCommand` already proves the package sits
+    // in slot 2 of a 3-arg command, so this bound is not reachable today — it is
+    // here so the function is safe to read on its own, and it is armed in the
+    // tests rather than argued from the shape check (Vera, 74940).
+    if (index !== 2 || !isUnpinnedShippedSpec(String(part))) return part;
+    changed = true;
+    return `${MCP_PACKAGE}@${safe}`;
+  });
+  // The same reference when nothing changed, so a caller can use identity as the
+  // "did this spawn's spec move" check — the convention the rest of this module
+  // already keeps (`ensureCommonlyMcpServer`, `withholdGrantBroker`).
+  return changed ? pinned : command;
+};
+
+/**
+ * What a spawn should execute, and where that decision came from.
+ *
+ * `source: 'home'` — the command is `node <bin>` from the version dir, no npx
+ * and no network. `source: 'declared'` — the declaration runs as written, which
+ * is either an operator's pinned spec or an EMPTY HOME (fresh host, or a home
+ * that was deleted). The empty-home path is the old failure mode and it is
+ * accepted, written down, and once per empty home rather than once per publish.
+ * `reason` names which of those it was, for the spawn path's logs.
+ */
+export const planMcpSpawn = (command, {
+  home,
+  readFile = defaultRead,
+  exists = defaultExists,
+  readBin = (h, v) => readBinPath(h, v, { readFile, exists }),
+  newest = (h) => newestInstalledVersion(h, { readBin }),
+} = {}) => {
+  const target = resolveHomeDir(home);
+  if (!isShippedCommonlyMcpCommand(command) || !isUnpinnedShippedSpec(String(command[2]))) {
+    return { command, source: 'declared', version: null, reason: 'not-the-shipped-unpinned-spec' };
+  }
+  const pointer = readCurrentVersion(target, { readFile });
+  if (pointer) {
+    const bin = readBin(target, pointer);
+    if (bin) return { command: ['node', bin], source: 'home', version: pointer, reason: 'pointer' };
+  }
+  const fallback = newest(target);
+  if (fallback) {
+    const bin = readBin(target, fallback);
+    if (bin) {
+      return {
+        command: ['node', bin],
+        source: 'home',
+        version: fallback,
+        reason: pointer ? 'pointer-bin-missing' : 'no-pointer',
+      };
+    }
+  }
+  // No usable home, so the declaration is what runs — and the one thing worth
+  // changing about it is the spec string. The cached registry answer is used
+  // rather than a fresh lookup because this function is synchronous and on the
+  // spawn's critical path, and the warm refreshes that same cache on the same
+  // TTL (`REGISTRY_TTL_MS`). A stale-but-real version still gives this run its
+  // own npx dir, which `@latest` does not, and a stale cache means the registry
+  // has been answering nothing for a while — the case where `@latest` is least
+  // usable. `pinned` is reported so the caller can log which spec it ran.
+  const cached = readRegistryCache(target, { readFile });
+  const pinned = cached ? pinShippedSpec(command, cached.version) : command;
+  return {
+    command: pinned,
+    source: 'declared',
+    version: null,
+    reason: 'home-empty',
+    pinned: cached ? cached.version : null,
+  };
+};
+
+/** The warm's cached registry answer, with its age. */
+export const readRegistryCache = (home, { readFile = defaultRead } = {}) => {
+  const raw = readFile(join(home, REGISTRY_CACHE_NAME));
+  if (typeof raw !== 'string') return null;
+  try {
+    const parsed = JSON.parse(raw);
+    const version = exactVersion(parsed && parsed.version);
+    const checkedAt = parsed && Number.isFinite(parsed.checkedAt) ? parsed.checkedAt : null;
+    if (!version || checkedAt === null) return null;
+    return { version, checkedAt };
+  } catch {
+    return null;
+  }
+};
+
+/** True when the cached "latest" is newer than what this spawn is about to run. */
+export const warmLooksWanted = (home, version, { now = Date.now(), readFile = defaultRead } = {}) => {
+  const cached = readRegistryCache(home, { readFile });
+  if (!cached) return true;
+  if (now - cached.checkedAt > REGISTRY_TTL_MS) return true;
+  if (!version) return true;
+  const target = parseVersion(cached.version);
+  const running = parseVersion(version);
+  if (!target || !running) return true;
+  return (target[0] > running[0])
+    || (target[0] === running[0] && target[1] > running[1])
+    || (target[0] === running[0] && target[1] === running[1] && target[2] > running[2]);
+};
+
+export const warmChildPath = () => join(dirname(fileURLToPath(import.meta.url)), 'mcp-warm-child.mjs');
+
+/**
+ * Start the warm and walk away. Detached + unref'd, so a seat that spawns and
+ * exits does not wait on it, and the child is written to never throw at the
+ * parent: a warm that fails costs the NEXT spawn nothing but the old version.
+ */
+export const kickWarm = ({
+  home,
+  apiUrl = null,
+  spawnImpl = spawn,
+  childPath = warmChildPath(),
+} = {}) => {
+  try {
+    // argv entries are coerced with String(), so an undefined home reaches the
+    // child as the literal 'undefined' and it warms a directory by that name.
+    const targetHome = resolveHomeDir(home);
+    const child = spawnImpl(process.execPath, [childPath, targetHome], {
+      detached: true,
+      stdio: 'ignore',
+      env: {
+        ...process.env,
+        COMMONLY_MCP_HOME: targetHome,
+        ...(apiUrl ? { COMMONLY_WARM_API_URL: String(apiUrl) } : {}),
+      },
+    });
+    if (child && typeof child.unref === 'function') child.unref();
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+const lockPresent = (home, { exists = defaultExists } = {}) => exists(lockPathFor(home));
+
+/**
+ * The one entry the adapters call: what to execute, plus a warm if one is due.
+ *
+ * Sync and network-free by construction — the registry check, the install and
+ * the probe all live in the child. A lock already held means another spawn is
+ * warming, so this spawn just runs the current version. Public seats receive
+ * null if that version is unavailable and the fallback is a package runner;
+ * adapters omit that MCP declaration and tell the seat.
+ */
+export const prepareMcpSpawn = (command, {
+  home,
+  apiUrl = null,
+  publicSeat = false,
+  spawnImpl,
+  childPath,
+  now = Date.now(),
+  readFile = defaultRead,
+  exists = defaultExists,
+  warn = defaultWarn,
+} = {}) => {
+  const resolvedHome = resolveHomeDir(home);
+  try {
+    const plan = planMcpSpawn(command, { home: resolvedHome, readFile, exists });
+    // Claim the version this spawn is about to execute from, BEFORE returning the
+    // command, so a prune that runs while the seat is starting cannot take it.
+    let resolved = plan.command;
+    if (plan.source === 'home') {
+      const claim = claimInUse({ home: resolvedHome, version: plan.version });
+      // A claim that could not be written means the pruner may take this very
+      // directory out from under the running seat — the hazard the claim exists
+      // for. The declared command is what the guard approved and what no pruner
+      // owns, so the spawn falls back to it rather than executing unprotected,
+      // and says why. The warm still runs: with the seat off the dir, a prune or
+      // a repair is safe.
+      if (!claim.claimed) {
+        warn(`commonly: cannot claim ${versionDirFor(resolvedHome, plan.version)} for pid ${process.pid} (${claim.reason}) — running the declared command instead, because a prune could delete the directory this seat would run from`);
+        resolved = command;
+      }
+    }
+    const due = !lockPresent(resolvedHome, { exists })
+      && warmLooksWanted(resolvedHome, plan.version, { now, readFile });
+    if (due) kickWarm({ home: resolvedHome, apiUrl, spawnImpl, childPath });
+    if (publicSeat && resolved[0] === 'npx') {
+      warn('commonly: an MCP server is unavailable for this public turn; no host-prepared executable was ready');
+      return null;
+    }
+    return resolved;
+  } catch {
+    // Trusted seats retain the declared fallback. A public seat must not
+    // execute a package runner from the workspace even on this failure path.
+    if (publicSeat && command?.[0] === 'npx') return null;
+    return command;
+  }
+};
+
+/** Kept for callers that want the plan and the command in one call. */
+export const resolveMcpSpawnCommand = prepareMcpSpawn;
+
+export const statOrNull = (path) => {
+  try {
+    return statSync(path);
+  } catch {
+    return null;
+  }
+};