@ravefox/space 0.2.0 → 0.3.0

package/src/lib/mcp-ready.js

@@ -1,68 +0,0 @@
-/**
- * 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

@@ -1,123 +0,0 @@
-/**
- * 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

@@ -1,36 +0,0 @@
-/**
- * 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

@@ -1,412 +0,0 @@
-/**
- * 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; });
-  }
-}