@commonlyai/cli 0.1.76 → 0.1.77

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commonlyai/cli",
-  "version": "0.1.76",
+  "version": "0.1.77",
   "license": "Apache-2.0",
   "description": "The Commonly CLI — connect agents, manage pods, iterate fast",
   "type": "module",
@@ -42,6 +42,9 @@
   },
   "jest": {
     "testEnvironment": "node",
+    "setupFiles": [
+      "<rootDir>/jest.setup.cjs"
+    ],
     "transform": {},
     "testMatch": [
       "**/__tests__/**/*.[jt]s?(x)",

package/src/lib/adapters/claude.js

@@ -74,6 +74,7 @@ import {
 } from '../sandbox/seatbelt.js';
 import { CREDENTIAL_FILE_VAR, CREDENTIAL_KEY, writeCredentialFile } from '../credential-file.js';
 import { deliverSeatCredential, withholdRuntimeCredential } from '../mcp-credential-delivery.js';
+import { prepareMcpSpawn } from '../mcp-home.js';
 import { buildMemoryPreamble } from '../memory-bridge.js';
 import { adapterFailure, spawnCredentials } from '../upstream-refusal.js';
 
@@ -341,10 +342,19 @@ const buildMcpConfig = (mcpServers, ctx = {}) => {
   // config, which claude's `--mcp-config` reads directly.
   const mcpServersMap = {};
   for (const server of mcpServers) {
+    // TASK-174: the command this seat will EXECUTE, not the one it declared —
+    // `node <home>/<version>/node_modules/@commonlyai/mcp/<bin>` when the seat's
+    // MCP home has a warmed build, and otherwise the unchanged declaration. The
+    // credential channel below is decided on that same command, so the two can
+    // never disagree about which release is running.
+    const spawnCommand = server.command
+      ? prepareMcpSpawn(server.command, { apiUrl: ctx.instanceUrl })
+      : null;
+    const executed = spawnCommand ? { ...server, command: spawnCommand } : server;
     const entry = { type: server.transport || 'stdio' };
     if (server.url) entry.url = server.url;
-    if (server.command) {
-      const [command, ...args] = server.command;
+    if (spawnCommand) {
+      const [command, ...args] = spawnCommand;
       entry.command = command;
       if (args.length) entry.args = args;
     }
@@ -352,7 +362,7 @@ const buildMcpConfig = (mcpServers, ctx = {}) => {
     // config claude actually reads, so the value never has to exist in the
     // runtime's environment at all (TASK-083).
     if (server.env) {
-      entry.env = deliverSeatCredential(server, {
+      entry.env = deliverSeatCredential(executed, {
         credentialFile: ctx.credentialFile,
         label: 'claude',
       }).env;

package/src/lib/adapters/codex.js

@@ -58,6 +58,7 @@ import {
 } from 'path';
 import { CREDENTIAL_KEY, writeCredentialFile } from '../credential-file.js';
 import { deliverSeatCredential, withholdRuntimeCredential } from '../mcp-credential-delivery.js';
+import { prepareMcpSpawn } from '../mcp-home.js';
 import { buildMemoryPreamble } from '../memory-bridge.js';
 import { isLegacySandboxTrust, normalizeSandboxTrust } from '../environment.js';
 import { adapterFailure, spawnCredentials } from '../upstream-refusal.js';
@@ -138,20 +139,26 @@ const buildMcpOverrideArgs = (mcpServers, ctx = {}) => {
   const flags = [];
   const forwardedEnv = {};
   for (const server of mcpServers || []) {
+    const transport = typeof server?.transport === 'string' ? server.transport.trim().toLowerCase() : 'stdio';
+    if (!server?.name || transport !== 'stdio'
+      || !Array.isArray(server.command) || !server.command.length) continue;
+    // TASK-174: the command that will EXECUTE — the warmed build from the seat's
+    // MCP home when there is one — and the credential channel is decided on that
+    // same command, so the two can never disagree about which release runs. The
+    // rewrite is before `substitutePlaceholders` because it introduces no
+    // placeholder: it is a path this host resolved.
+    const spawnCommand = prepareMcpSpawn(server.command, { apiUrl: ctx.instanceUrl });
     // A declared credential is rewritten to the file channel before anything is
     // substituted, so for our server the token is not token-bearing at all: it
     // lands in `env={...}` as a path and never reaches `env_vars`, which is the
     // one path by which the value ends up in codex's own environment and from
     // there in every MCP child it spawns (TASK-083, measured on a live codex
     // seat before the change).
-    const declaredEnv = deliverSeatCredential(server, {
+    const declaredEnv = deliverSeatCredential({ ...server, command: spawnCommand }, {
       credentialFile: ctx.credentialFile,
       label: 'codex',
     }).env;
-    const transport = typeof server?.transport === 'string' ? server.transport.trim().toLowerCase() : 'stdio';
-    if (!server?.name || transport !== 'stdio'
-      || !Array.isArray(server.command) || !server.command.length) continue;
-    const [command, ...rest] = server.command.map((a) => substitutePlaceholders(a, ctx));
+    const [command, ...rest] = spawnCommand.map((a) => substitutePlaceholders(a, ctx));
     // The doc block above promises bearer tokens never ride in argv, and this is
     // the place that had to hold it: an env value that carries the token is
     // diverted to env_vars, but a COMMAND ARGUMENT has no such route — codex

package/src/lib/adapters/pi.js

@@ -46,6 +46,7 @@ import { buildMemoryPreamble } from '../memory-bridge.js';
 import { effectiveSandboxTrust } from '../environment.js';
 import { GRANT_BROKER_REFUSAL, isGrantBrokerUrl } from './pi-mcp-client.mjs';
 import { deliverSeatCredential, withholdRuntimeCredential } from '../mcp-credential-delivery.js';
+import { prepareMcpSpawn } from '../mcp-home.js';
 import { removeCredentialFile, writeCredentialFile } from '../credential-file.js';
 
 const DEFAULT_TIMEOUT_MS = (() => {
@@ -207,13 +208,17 @@ export const resolveMcpServers = (mcpServers, ctx = {}) => {
         }
         continue;
       }
+      // TASK-174: what will EXECUTE — the warmed build from the seat's MCP home
+      // when there is one — and the credential channel is decided on that same
+      // command, so the two can never disagree about which release runs.
+      const spawnCommand = prepareMcpSpawn(server.command, { apiUrl: ctx.instanceUrl });
       carried.push({
         name: server.name,
-        command: server.command.map((a) => substitutePlaceholders(a, ctx)),
+        command: spawnCommand.map((a) => substitutePlaceholders(a, ctx)),
         // Rewritten before substitution, so our own server is handed the file
         // (whose value the bridge pipes) instead of the token itself.
         env: Object.fromEntries(Object.entries(
-          deliverSeatCredential(server, {
+          deliverSeatCredential({ ...server, command: spawnCommand }, {
             credentialFile: ctx.credentialFile,
             label: 'pi',
           }).env,

package/src/lib/mcp-home.js

@@ -0,0 +1,465 @@
+/**
+ * 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.
+ *
+ * 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, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { isShippedCommonlyMcpCommand } from './declared-mcp-guard.js';
+import { MCP_PACKAGE, 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';
+
+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');
+export const versionDirFor = (home, version) => join(home, version);
+export const packageDirFor = (home, version) => join(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. Best-effort by construction — a home
+ * that cannot be written to costs the seat nothing but its claim.
+ */
+export const claimInUse = ({
+  home,
+  version,
+  pid = process.pid,
+  mkdir = mkdirSync,
+  writeFile = writeFileSync,
+} = {}) => {
+  try {
+    if (!isUsableWarmHome(home) || !parseVersion(version) || parsePid(pid) === null) return false;
+    mkdir(inUseDirFor(home, version), { recursive: true });
+    writeFile(inUseMarkerPath(home, version, pid), '');
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+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 = raw.trim();
+  return parseVersion(version) ? 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 = {}) => {
+  if (!parseVersion(version)) return null;
+  return readBinInPackageDir(packageDirFor(home, version), options);
+};
+
+/**
+ * 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)
+    .filter((name) => parseVersion(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`
+);
+
+/**
+ * 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',
+      };
+    }
+  }
+  return { command, source: 'declared', version: null, reason: 'home-empty' };
+};
+
+/** 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 = parsed && typeof parsed.version === 'string' ? parsed.version : null;
+    const checkedAt = parsed && Number.isFinite(parsed.checkedAt) ? parsed.checkedAt : null;
+    if (!parseVersion(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.
+ */
+export const prepareMcpSpawn = (command, {
+  home,
+  apiUrl = null,
+  spawnImpl,
+  childPath,
+  now = Date.now(),
+  readFile = defaultRead,
+  exists = defaultExists,
+} = {}) => {
+  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.
+    if (plan.source === 'home') claimInUse({ home: resolvedHome, version: plan.version });
+    const due = !lockPresent(resolvedHome, { exists })
+      && warmLooksWanted(resolvedHome, plan.version, { now, readFile });
+    if (due) kickWarm({ home: resolvedHome, apiUrl, spawnImpl, childPath });
+    return plan.command;
+  } catch {
+    // A rewrite that throws must not cost the seat its tools: the declaration
+    // is what the guard approved, and it still runs.
+    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;
+  }
+};

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

@@ -51,40 +51,51 @@ export const versionOlderThan = (version, target) => {
  * `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)) };
   }
-  const scriptPath = parts.find((p) => p.endsWith('.js') || p.endsWith('.mjs'));
-  if (!scriptPath) return null;
-  // `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;
 };

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

@@ -0,0 +1,388 @@
+/**
+ * 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, parseVersion } from './mcp-server-version.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. */
+export const runCommand = (bin, args, { timeout = REGISTRY_TIMEOUT_MS } = {}) => new Promise((resolve) => {
+  let settled = false;
+  let child;
+  const done = (result) => {
+    if (settled) return;
+    settled = true;
+    resolve(result);
+  };
+  try {
+    child = spawnChild(bin, args, { stdio: ['ignore', 'pipe', 'pipe'], env: process.env });
+  } 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);
+      if (parsed && Number.isFinite(parsed.checkedAt) && now - parsed.checkedAt < ttlMs
+        && parseVersion(parsed.version)) {
+        return { version: parsed.version, source: 'cache' };
+      }
+    } catch { /* unreadable cache is just a miss */ }
+  }
+  const result = await exec('npm', ['view', MCP_PACKAGE, 'version', '--json'], { timeout: REGISTRY_TIMEOUT_MS });
+  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, '');
+    }
+  }
+  if (version && parseVersion(version)) {
+    try {
+      writeFile(cachePath, JSON.stringify({ version, checkedAt: now }));
+    } catch { /* a cache we cannot write is not a warm we should fail */ }
+    return { version, 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);
+      if (parseVersion(parsed.version)) return { version: parsed.version, 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,
+} = {}) => 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'],
+      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),
+} = {}) => {
+  const versions = readDir(home).filter((name) => parseVersion(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;
+    const trimmed = raw.trim();
+    return parseVersion(trimmed) ? trimmed : 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 });
+    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 });
+    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; });
+  }
+}