@ravefox/space 0.0.0-stage → 0.2.1

package/src/lib/mcp-ready.js

@@ -0,0 +1,68 @@
+/**
+ * Ready files for a public seat's MCP servers (F421, F460).
+ *
+ * The Commonly MCP server reads the seat credential once, at start, and
+ * creates the file named in COMMONLY_MCP_READY_FILE on its host's first
+ * `tools/list` (commonly-mcp/src/ready-file.js); the grant-broker bridge does
+ * the same (codex-broker-bridge.mjs). So once every ready file a spawn named
+ * exists, nothing in that spawn still needs the credential file, and
+ * `armCredentialRelease` (credential-file.js) deletes it.
+ *
+ * A seat names files only when the spawn has a ready folder, which the adapter
+ * creates for a public seat alone. A public seat whose Commonly server can't
+ * be shown to write one is refused: a warm build from before ready files, or
+ * our package run from a path outside the host-prepared MCP home (a checkout).
+ * Without the file its credential would stay readable to the deadline on every
+ * turn, or, named by nothing, be gone before that server read it.
+ */
+import { randomUUID } from 'node:crypto';
+import { join } from 'node:path';
+import { CREDENTIAL_FILE_VAR } from './credential-file.js';
+import { isShippedCommonlyMcpCommand } from './declared-mcp-guard.js';
+import { selectedMcpWritesReadyFile } from './mcp-home.js';
+import { describeMcpCommand } from './mcp-server-version.js';
+
+export const MCP_READY_FILE_ENV = 'COMMONLY_MCP_READY_FILE';
+
+const nameReadyFile = (name, ctx) => {
+  const path = join(ctx.readyFileDir, randomUUID());
+  ctx.readyFiles.push({ name, path });
+  return path;
+};
+
+export const publicMcpOutdatedError = (name) => new Error(
+  `public seats need a Space MCP server that reports when it has started, and the one this seat runs for `
+  + `${name} does not (a build from before that, or one run from outside the host-prepared MCP home); `
+  + 'update @commonlyai/mcp',
+);
+
+export const publicMcpUnreportedReaderError = (name) => new Error(
+  `public seats hand the runtime credential only to the Space MCP server, which reports when it has read it; `
+  + `${name} is another server declaring ${CREDENTIAL_FILE_VAR}, so it would lose the credential before reading it. `
+  + 'Remove that declaration, or run this server on a private seat',
+);
+
+/**
+ * The ready file for `server` (as declared), run as `spawnCommand` (the warm
+ * build it resolved to), or null when this spawn names none for it.
+ */
+export const commonlyMcpReadyFile = (server, spawnCommand, ctx, {
+  writesReadyFile = selectedMcpWritesReadyFile,
+  describe = describeMcpCommand,
+  env = null,
+} = {}) => {
+  if (!ctx?.readyFileDir) return null;
+  const ours = isShippedCommonlyMcpCommand(server?.command) || Boolean(describe(spawnCommand)?.isCommonly);
+  if (!ours) {
+    // `env` is the entry's environment after credential delivery: a server that
+    // is not ours but was handed the credential path names no ready file, so
+    // the release would not wait for it.
+    if (env && String(env[CREDENTIAL_FILE_VAR] ?? '').trim()) throw publicMcpUnreportedReaderError(server?.name);
+    return null;
+  }
+  if (!writesReadyFile(spawnCommand)) throw publicMcpOutdatedError(server.name);
+  return nameReadyFile(server.name, ctx);
+};
+
+/** The broker bridge ships with this CLI, so it always writes one. */
+export const bridgeReadyFile = (server, ctx) => (ctx?.readyFileDir ? nameReadyFile(server.name, ctx) : null);

package/src/lib/mcp-server-version.js

@@ -0,0 +1,123 @@
+/**
+ * Which `@commonlyai/mcp` a declared MCP command would run, and which channels
+ * that release understands.
+ *
+ * Shared by the pi bridge (which decides whether to pipe a credential) and by
+ * the claude and codex adapters (which decide whether to hand over a PATH or the
+ * value): one predicate, because three copies of "is this old enough" would
+ * drift, and the drift would be silent in exactly one adapter.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+export const MCP_PACKAGE = '@commonlyai/mcp';
+
+/** The release whose reader accepts the credential on an inherited fd. */
+export const PIPE_READER_VERSION = [0, 3, 11];
+
+/** The release whose reader accepts `COMMONLY_TOKEN_FILE` (a PATH, not a secret). */
+export const FILE_READER_VERSION = [0, 3, 12];
+
+export const parseVersion = (spec) => {
+  const match = /^(\d+)\.(\d+)\.(\d+)/.exec(String(spec || '').trim());
+  return match ? [Number(match[1]), Number(match[2]), Number(match[3])] : null;
+};
+
+/**
+ * The version as a bare triple — or null when there is none to build.
+ *
+ * `parseVersion` is a PREFIX test, which is right for ordering two versions and
+ * wrong for building anything out of one: it accepts `0.3.13/../../../../tmp/x`,
+ * so a version read out of a file (`~/.commonly/mcp/.registry.json`, the
+ * `current` pointer) or out of `npm view` could become a path or an npm SPEC
+ * ARGUMENT that leaves the seat's home. Everything that turns a version into a
+ * STRING used outside this module's own comparisons goes through here instead,
+ * and the string it builds is the parsed triple, so no suffix can travel.
+ *
+ * The cost is deliberate and one-directional: a prerelease (`0.3.13-rc.1`)
+ * becomes `0.3.13` rather than falling back to `@latest` — the stable release of
+ * the same triple, which is a real published version, and strictly better than
+ * the shared `@latest` dir this whole change exists to get off. Anchoring the
+ * regex at the end instead would reject the prerelease and leave it unpinned.
+ */
+export const exactVersion = (spec) => {
+  const triple = parseVersion(spec);
+  return triple ? triple.join('.') : null;
+};
+
+/**
+ * True when `version` is older than `target`; null when there is no version to
+ * judge (an unpinned `@latest` tracks the published release, so it is never
+ * treated as old).
+ */
+export const versionOlderThan = (version, target) => {
+  if (!version) return null;
+  for (let i = 0; i < 3; i += 1) {
+    if (version[i] !== target[i]) return version[i] < target[i];
+  }
+  return false;
+};
+
+/**
+ * What an `@commonlyai/mcp` command would run, or null when the command cannot
+ * be identified as that package at all.
+ *
+ * Two shapes matter: `npx [-y] @commonlyai/mcp@<spec>` (a spec is a version, or
+ * `latest`/absent, which resolves to whatever is published — never treated as
+ * old), and a local checkout, `node <path>/src/index.js`, which is what the
+ * staging seats run; for that one the package.json beside it is the only honest
+ * answer, and a package.json naming something else means this is not our server.
+ *
+ * `{ isCommonly: true, version: null }` means "our server, version unknown" —
+ * an unpinned npx spec, whose whole point is that it tracks the published one.
+ * `null` as the return value means "not identifiable as our server", which is a
+ * different answer and takes a different branch: a stranger's server gets its
+ * declaration honoured unchanged.
+ *
+ * The ENTRY SCRIPT is checked first, and that ordering is load-bearing since
+ * TASK-174. A seat home runs `node <home>/<version>/node_modules/@commonlyai/mcp/<bin>`,
+ * and that path CONTAINS the package name — so a spec-first order matched the
+ * path, took the `@` of `@commonlyai/mcp` for the version separator, and returned
+ * `{ version: null }` ("unpinned, so never old") for every home build. The
+ * version then decided nothing: measured, a home holding 0.3.7 was handed the
+ * credential FILE channel, whose reader does not exist before 0.3.12. Nor is
+ * "a spec has no slash" a usable rule — a SCOPED spec is `@commonlyai/mcp`.
+ */
+export const describeMcpCommand = (command, {
+  readTextFile = (p) => (existsSync(p) ? readFileSync(p, 'utf8') : null),
+} = {}) => {
+  if (!Array.isArray(command) || command.length === 0) return null;
+  const parts = command.map(String);
+  const scriptPath = parts.find((p) => p.endsWith('.js') || p.endsWith('.mjs'));
+  if (scriptPath) {
+    // `src/index.js` → `../package.json`; also try one level further up, because
+    // a bin shim can live in `bin/` beside `src/`.
+    for (const candidate of [join(dirname(scriptPath), '..', 'package.json'), join(dirname(scriptPath), 'package.json')]) {
+      let raw;
+      try {
+        raw = readTextFile(candidate);
+      } catch {
+        raw = null;
+      }
+      if (!raw) continue;
+      try {
+        const pkg = JSON.parse(raw);
+        if (!pkg || typeof pkg !== 'object') continue;
+        if (pkg.name === MCP_PACKAGE) return { isCommonly: true, version: parseVersion(pkg.version) };
+        // A package.json that names another package settles it: not ours, so its
+        // declaration is none of this function's business.
+        return null;
+      } catch {
+        // A malformed package.json is not an answer; keep looking.
+      }
+    }
+    return null;
+  }
+  const pkgArg = parts.find((p) => p.includes(MCP_PACKAGE));
+  if (pkgArg) {
+    const at = pkgArg.lastIndexOf('@');
+    if (at <= pkgArg.indexOf(MCP_PACKAGE)) return { isCommonly: true, version: null };
+    return { isCommonly: true, version: parseVersion(pkgArg.slice(at + 1)) };
+  }
+  return null;
+};

package/src/lib/mcp-token.js

@@ -0,0 +1,36 @@
+/**
+ * The 0600 copy of an agent's runtime token that `commonly mcp config` points
+ * COMMONLY_TOKEN_FILE at (TASK-666). It is a second live secret, so the agent
+ * token's lifecycle owns it: save refreshes it, delete removes it.
+ */
+import { chmodSync, existsSync, mkdirSync, rmSync, writeFileSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+
+export const validMcpTokenName = (name) => typeof name === 'string' && /^[A-Za-z0-9._-]+$/.test(name) && !name.startsWith('.');
+
+export const mcpTokenPath = (name) => {
+  if (!validMcpTokenName(name)) throw new Error(`Invalid agent name '${name}'`);
+  return join(homedir(), '.commonly', 'mcp', `${name}.token`);
+};
+
+// Remove first, then create exclusively at 0600: no write into a looser-mode file or through a symlink.
+export const writeMcpTokenCopy = (name, token) => {
+  const dir = join(homedir(), '.commonly', 'mcp');
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  chmodSync(dir, 0o700);
+  const path = mcpTokenPath(name);
+  rmSync(path, { force: true });
+  writeFileSync(path, `${token}\n`, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+  return path;
+};
+
+// A bad name never has a copy, so remove and refresh are no-ops for it and cannot block detach or save.
+export const removeMcpTokenCopy = (name) => {
+  if (validMcpTokenName(name)) rmSync(mcpTokenPath(name), { force: true });
+};
+
+// Reattach mints a new token; a copy that already exists must follow it.
+export const refreshMcpTokenCopy = (name, token) => {
+  if (token && validMcpTokenName(name) && existsSync(mcpTokenPath(name))) writeMcpTokenCopy(name, token);
+};

package/src/lib/mcp-warm-child.mjs

@@ -0,0 +1,412 @@
+/**
+ * The background warm for the seat MCP home — see mcp-home.js for why.
+ *
+ * This runs as a DETACHED child, never on a spawn path, because everything it
+ * does is slow or networked: a registry lookup, an `npm install`, and an MCP
+ * `initialize` handshake against the freshly installed bin. The spawn path only
+ * reads a pointer file and exec's `node <bin>`.
+ *
+ * Order of operations is the contract: install into `.tmp-<version>-<pid>`,
+ * PROBE the bin inside that temp dir, and only then `rename` it into
+ * `<home>/<version>` and move the pointer. So a version dir in the home is a
+ * version that answered the protocol at least once, and a half-installed or
+ * non-starting build can never become what seats execute.
+ *
+ * Single-flight by lock file (O_EXCL), so concurrent spawns on a fresh host
+ * trigger exactly one install. A lock older than STALE_LOCK_MS is a warm that
+ * died (a laptop sleeping mid-install is the normal way) and is reclaimed rather
+ * than allowed to wedge the home forever.
+ *
+ * The probe's env is measured, not assumed: at 0.3.13 the bin exits 1 with
+ * "[commonly-mcp] fatal: COMMONLY_API_URL is required" and, with that set, exits
+ * 1 again on "No runtime token". With both present as PLACEHOLDERS it answers
+ * `initialize` with a result — the boot check is presence-only and `initialize`
+ * does not touch the network (both measured on this host 2026-09-27), which is
+ * what makes a credential-free probe honest rather than a stub.
+ */
+import { spawn as spawnChild } from 'node:child_process';
+import {
+  closeSync, existsSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync,
+} from 'node:fs';
+import { join } from 'node:path';
+import {
+  KEEP_VERSION_DIRS, PRUNE_GRACE_MS, REGISTRY_CACHE_NAME, REGISTRY_TTL_MS, STALE_LOCK_MS,
+  WARM_RESULTS, currentPointerPath, isUsableWarmHome, liveInUsePids, lockPathFor,
+  readBinInPrefix, versionDirFor,
+} from './mcp-home.js';
+import { MCP_PACKAGE, exactVersion, parseVersion } from './mcp-server-version.js';
+import { resolveLaunch } from './windows-command.js';
+
+export const PROBE_API_URL_PLACEHOLDER = 'http://127.0.0.1:1';
+export const PROBE_TOKEN_PLACEHOLDER = 'cm_agent_warm_probe';
+export const PROBE_TIMEOUT_MS = 10 * 1000;
+export const REGISTRY_TIMEOUT_MS = 20 * 1000;
+
+const INITIALIZE_REQUEST = JSON.stringify({
+  jsonrpc: '2.0',
+  id: 1,
+  method: 'initialize',
+  params: {
+    protocolVersion: '2024-11-05',
+    capabilities: {},
+    clientInfo: { name: 'commonly-cli-warm', version: '1' },
+  },
+});
+
+const exists = (path) => {
+  try {
+    return existsSync(path);
+  } catch {
+    return false;
+  }
+};
+
+const readIfAny = (path) => {
+  try {
+    return existsSync(path) ? readFileSync(path, 'utf8') : null;
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * Take the warm lock, reclaiming one that is too old to belong to a live warm.
+ *
+ * Returns the open fd, or null when another process holds a fresh lock.
+ */
+export const acquireWarmLock = (home, {
+  now = Date.now(),
+  open = (path) => openSync(path, 'wx'),
+  stat = (path) => statSync(path),
+  remove = (path) => unlinkSync(path),
+  staleMs = STALE_LOCK_MS,
+} = {}) => {
+  const lockPath = lockPathFor(home);
+  try {
+    return open(lockPath);
+  } catch (error) {
+    if (error && error.code !== 'EEXIST') return null;
+  }
+  let age;
+  try {
+    age = now - stat(lockPath).mtimeMs;
+  } catch {
+    return null; // vanished between EEXIST and stat: not ours to break
+  }
+  if (age <= staleMs) return null;
+  try {
+    remove(lockPath);
+  } catch {
+    return null;
+  }
+  try {
+    return open(lockPath);
+  } catch {
+    // Lost the reclaim race to another spawn's warm. Fine: that one is working.
+    return null;
+  }
+};
+
+/**
+ * Default `npm` runner. Resolves `{ ok, stdout }`; never rejects. On Windows
+ * `npm` is npm.cmd, which Node cannot spawn without a shell, so the name goes
+ * through the resolver the adapters use (npm.cmd becomes node.exe npm-cli.js).
+ * Off Windows it is spawned as given. `resolution` is the resolver's test seam.
+ */
+export const runCommand = (bin, args, {
+  timeout = REGISTRY_TIMEOUT_MS, cwd, resolution,
+} = {}) => new Promise((resolve) => {
+  let settled = false;
+  let child;
+  const done = (result) => {
+    if (settled) return;
+    settled = true;
+    resolve(result);
+  };
+  try {
+    // The child runs in `cwd`, so a relative PATH entry is read there.
+    const launch = resolveLaunch(bin, args, { cwd, ...resolution });
+    child = spawnChild(launch.command, launch.args, { stdio: ['ignore', 'pipe', 'pipe'], env: process.env, cwd });
+  } catch (error) {
+    done({ ok: false, stdout: '', stderr: String(error && error.message) });
+    return;
+  }
+  let stdout = '';
+  let stderr = '';
+  child.stdout.on('data', (d) => { stdout += String(d); });
+  child.stderr.on('data', (d) => { stderr += String(d); });
+  const timer = setTimeout(() => {
+    try {
+      child.kill('SIGKILL');
+    } catch { /* already gone */ }
+    done({ ok: false, stdout, stderr: `${stderr}\n[commonly] timed out after ${timeout}ms` });
+  }, timeout);
+  child.on('error', (error) => { clearTimeout(timer); done({ ok: false, stdout, stderr: String(error && error.message) }); });
+  child.on('close', (code) => { clearTimeout(timer); done({ ok: code === 0, code, stdout, stderr }); });
+});
+
+/** The registry's current version for the package, cached on disk with a TTL. */
+export const resolveRegistryLatest = async (home, {
+  now = Date.now(),
+  exec = runCommand,
+  ttlMs = REGISTRY_TTL_MS,
+  writeFile = (path, text) => writeFileSync(path, text),
+} = {}) => {
+  const cachePath = join(home, REGISTRY_CACHE_NAME);
+  const cached = readIfAny(cachePath);
+  if (cached) {
+    try {
+      const parsed = JSON.parse(cached);
+      const cachedVersion = parsed ? exactVersion(parsed.version) : null;
+      if (cachedVersion && Number.isFinite(parsed.checkedAt) && now - parsed.checkedAt < ttlMs) {
+        return { version: cachedVersion, source: 'cache' };
+      }
+    } catch { /* unreadable cache is just a miss */ }
+  }
+  const result = await exec('npm', ['view', MCP_PACKAGE, 'version', '--json'], {
+    timeout: REGISTRY_TIMEOUT_MS, cwd: home,
+  });
+  const raw = result && result.ok ? String(result.stdout || '').trim() : '';
+  let version = null;
+  if (raw) {
+    try {
+      const parsed = JSON.parse(raw);
+      version = typeof parsed === 'string' ? parsed : null;
+    } catch {
+      version = raw.replace(/^"|"$/g, '');
+    }
+  }
+  // This answer is both persisted and, downstream, an argv entry
+  // (`npm install <pkg>@<version>`) and a path (`<home>/<version>`, the temp
+  // prefix). Rebuild it as a triple here, at the one place it enters, so the
+  // rest of the warm can keep treating a version as a name.
+  const safe = exactVersion(version);
+  if (safe) {
+    try {
+      writeFile(cachePath, JSON.stringify({ version: safe, checkedAt: now }));
+    } catch { /* a cache we cannot write is not a warm we should fail */ }
+    return { version: safe, source: 'registry' };
+  }
+  // Registry down: the last known answer is better than none, and better than
+  // moving the pointer backwards.
+  if (cached) {
+    try {
+      const parsed = JSON.parse(cached);
+      const stale = parsed ? exactVersion(parsed.version) : null;
+      if (stale) return { version: stale, source: 'stale-cache' };
+    } catch { /* fall through */ }
+  }
+  return { version: null, source: 'unavailable' };
+};
+
+/**
+ * Does the installed bin start and speak the protocol?
+ *
+ * Accepts a JSON-RPC response to id 1 whether it is a `result` or an `error`:
+ * what this proves is that the build runs and answers `initialize`, which is
+ * exactly what the pointer's contract claims. It is not an authorization check —
+ * the seat's own token is what makes calls work.
+ */
+export const probeBin = (binPath, {
+  spawnImpl = spawnChild,
+  timeoutMs = PROBE_TIMEOUT_MS,
+  apiUrl = process.env.COMMONLY_WARM_API_URL || PROBE_API_URL_PLACEHOLDER,
+  cwd,
+} = {}) => new Promise((resolve) => {
+  let settled = false;
+  let child;
+  const done = (ok) => {
+    if (settled) return;
+    settled = true;
+    try {
+      if (child) child.kill('SIGKILL');
+    } catch { /* already gone */ }
+    resolve(ok);
+  };
+  try {
+    child = spawnImpl(process.execPath, [binPath], {
+      stdio: ['pipe', 'pipe', 'pipe'],
+      cwd,
+      env: {
+        PATH: process.env.PATH,
+        HOME: process.env.HOME,
+        COMMONLY_API_URL: String(apiUrl),
+        COMMONLY_AGENT_TOKEN: PROBE_TOKEN_PLACEHOLDER,
+      },
+    });
+  } catch {
+    resolve(false);
+    return;
+  }
+  const timer = setTimeout(() => done(false), timeoutMs);
+  let seen = '';
+  const onData = (chunk) => {
+    seen += String(chunk);
+    if (/"id"\s*:\s*1/.test(seen)) {
+      clearTimeout(timer);
+      done(true);
+    }
+  };
+  child.stdout.on('data', onData);
+  child.on('error', () => { clearTimeout(timer); done(false); });
+  child.on('close', () => { clearTimeout(timer); done(false); });
+  try {
+    child.stdin.write(`${INITIALIZE_REQUEST}\n`);
+  } catch {
+    clearTimeout(timer);
+    done(false);
+  }
+});
+
+const writePointerAtomic = (home, version, { writeTemp = writeFileSync } = {}) => {
+  const target = currentPointerPath(home);
+  const temp = join(home, `.current-${process.pid}`);
+  writeTemp(temp, `${version}\n`);
+  renameSync(temp, target);
+};
+
+/** Keep the newest N version dirs; the current one is never a candidate. */
+export const pruneVersionDirs = (home, current, {
+  keep = KEEP_VERSION_DIRS,
+  grace = PRUNE_GRACE_MS,
+  now = Date.now(),
+  readDir = (dir) => {
+    try {
+      return readdirSync(dir);
+    } catch {
+      return [];
+    }
+  },
+  remove = (path) => rmSync(path, { recursive: true, force: true }),
+  mtime = (path) => {
+    try {
+      return statSync(path).mtimeMs;
+    } catch {
+      return null;
+    }
+  },
+  livePids = (version) => liveInUsePids(home, version),
+} = {}) => {
+  // Exact triples only, for the same reason `newestInstalledVersion` uses them:
+  // a dir named `0.3.13-rc.1` is not the dir `0.3.13`, and this loop REMOVES what
+  // it names.
+  const versions = readDir(home).filter((name) => exactVersion(name) === name);
+  versions.sort((a, b) => {
+    const [am, an, ap] = parseVersion(a);
+    const [bm, bn, bp] = parseVersion(b);
+    return (bm - am) || (bn - an) || (bp - ap);
+  });
+  const removed = [];
+  versions.slice(keep).forEach((name) => {
+    if (name === current) return;
+    // A live claimant outranks the count: this dir may be executing right now.
+    if (livePids(name).length > 0) return;
+    // And time outranks the count too — a dir inside the grace window may belong
+    // to a spawn that has not written its claim yet. An unreadable/absent mtime
+    // is not evidence of age, so it is left alone.
+    const installedAt = mtime(versionDirFor(home, name));
+    if (typeof installedAt !== 'number' || now - installedAt < grace) return;
+    try {
+      remove(versionDirFor(home, name));
+      removed.push(name);
+    } catch { /* a dir we cannot remove is not a failed warm */ }
+  });
+  return removed;
+};
+
+/**
+ * The whole warm, in one function so a test can drive every branch with injected
+ * I/O. Returns one of WARM_RESULTS — never throws, because it runs unattended.
+ */
+export const warmMcpHome = async (home, {
+  now = Date.now(),
+  exec = runCommand,
+  probe = probeBin,
+  spawnProbe,
+  lock = () => acquireWarmLock(home, { now }),
+  closeLock = (fd) => closeSync(fd),
+  mkdir = (dir) => mkdirSync(dir, { recursive: true }),
+  remove = (path) => rmSync(path, { recursive: true, force: true }),
+  rename = (from, to) => renameSync(from, to),
+  readBin = (prefix) => readBinInPrefix(prefix),
+  readCurrent = (h) => {
+    const raw = readIfAny(currentPointerPath(h));
+    if (typeof raw !== 'string') return null;
+    return exactVersion(raw.trim()) || null;
+  },
+  keep = KEEP_VERSION_DIRS,
+} = {}) => {
+  mkdir(home);
+  const fd = lock();
+  if (fd === null) return WARM_RESULTS.LOCKED;
+  try {
+    const latest = await resolveRegistryLatest(home, { now, exec });
+    if (!latest.version) return WARM_RESULTS.REGISTRY_UNAVAILABLE;
+    const target = latest.version;
+    const current = readCurrent(home);
+    if (current && current === target) return WARM_RESULTS.CURRENT;
+    if (current && parseVersion(current) && parseVersion(target)) {
+      const [tm, tn, tp] = parseVersion(target);
+      const [cm, cn, cp] = parseVersion(current);
+      if ((tm < cm) || (tm === cm && tn < cn) || (tm === cm && tn === cn && tp <= cp)) {
+        return WARM_RESULTS.CURRENT;
+      }
+    }
+    const temp = join(home, `.tmp-${target}-${process.pid}`);
+    remove(temp);
+    mkdir(temp);
+    const install = await exec('npm', [
+      'install', '--prefix', temp, `${MCP_PACKAGE}@${target}`, '--no-save', '--no-audit', '--no-fund',
+    ], { timeout: 5 * 60 * 1000, cwd: home });
+    if (!install || !install.ok) {
+      remove(temp);
+      return WARM_RESULTS.INSTALL_FAILED;
+    }
+    const bin = readBin(temp);
+    if (!bin) {
+      remove(temp);
+      return WARM_RESULTS.INSTALL_FAILED;
+    }
+    const started = await (spawnProbe || probe)(bin, {
+      apiUrl: process.env.COMMONLY_WARM_API_URL, cwd: home,
+    });
+    if (!started) {
+      remove(temp);
+      return WARM_RESULTS.PROBE_FAILED;
+    }
+    const destination = versionDirFor(home, target);
+    if (exists(destination)) remove(temp);
+    else rename(temp, destination);
+    writePointerAtomic(home, target);
+    pruneVersionDirs(home, target, { keep });
+    return WARM_RESULTS.ADVANCED;
+  } catch {
+    return WARM_RESULTS.INSTALL_FAILED;
+  } finally {
+    try {
+      closeLock(fd);
+    } catch { /* nothing to close */ }
+    try {
+      rmSync(lockPathFor(home), { force: true });
+    } catch { /* lock is best-effort cleanup */ }
+  }
+};
+
+const invokedDirectly = process.argv[1] && /mcp-warm-child\.mjs$/.test(process.argv[1]);
+if (invokedDirectly) {
+  // Validated, not trusted: argv entries are coerced with String(), so a parent
+  // that passed an undefined home sends the literal 'undefined' and this child
+  // would otherwise create and populate a directory by that name (which is how
+  // one appeared inside the package directory on 2026-09-27).
+  const home = process.argv[2];
+  if (isUsableWarmHome(home)) {
+    warmMcpHome(home, { now: Date.now() })
+      .then((result) => {
+        // A warm runs with stdio ignored; this is for a human running it by hand
+        // and for `--verbose` debugging, and it must never be on a spawn path.
+        if (process.env.COMMONLY_WARM_VERBOSE) process.stdout.write(`${result}\n`);
+        process.exitCode = 0;
+      })
+      .catch(() => { process.exitCode = 0; });
+  }
+}