@commonlyai/cli 0.1.77 → 0.1.79

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commonlyai/cli",
-  "version": "0.1.77",
+  "version": "0.1.79",
   "license": "Apache-2.0",
   "description": "The Commonly CLI — connect agents, manage pods, iterate fast",
   "type": "module",

package/src/lib/mcp-home.js

@@ -27,6 +27,15 @@
  * operator saying which build to run, and the npx cache already gives a pinned
  * spec its own dir.
  *
+ * The cold path is pinned too (TASK-174's second half). A spawn with no usable
+ * home still runs the declaration, but not with the shared `@latest` spec: the
+ * spec this spawn executes is the version the registry already answered with,
+ * read from the warm's own cache, so `@latest`'s one shared npx dir is not on
+ * the spawn path even once. The fallback is the declaration as written, and it
+ * is used exactly when nothing has ever resolved a version on this host — a
+ * fresh machine's first spawn, where `@latest` is also the only spec that could
+ * work — or when the cache is unreadable. Nothing here throws.
+ *
  * Every filesystem answer here is injected, because the two states that matter
  * (a home that has never been warmed, and a home whose pointed-at version dir was
  * deleted under it) cannot both be produced on one host.
@@ -39,7 +48,7 @@ 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';
+import { MCP_PACKAGE, exactVersion, parseVersion } from './mcp-server-version.js';
 
 /** The env override, so tests (and an operator) can point the home elsewhere. */
 export const MCP_HOME_ENV = 'COMMONLY_MCP_HOME';
@@ -113,8 +122,34 @@ export const isUsableWarmHome = (home) => (
 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);
+
+/**
+ * Where a version dir name that is not a triple lands: inside the home, and
+ * never a version (a version starts with a digit), so every read of it misses
+ * and the spawn falls back to its declaration. The alternative — building the
+ * path from whatever string arrived — is how `0.3.13/../../../../tmp/x` resolved
+ * outside the home, and #1970's `startsWith(pkgDir)` confinement is computed
+ * FROM that dir, so it would have confined to the wrong place (Vera, 74938).
+ */
+const UNUSABLE_VERSION_DIR = '.unusable-version';
+
+/**
+ * A version dir, built from the parsed triple — and only when the string given
+ * IS that triple.
+ *
+ * Refusing beats rebuilding here: this result is what the warm RENAMES into and
+ * what the pruner REMOVES, so silently rewriting `0.3.14-rc.1` to `0.3.14` would
+ * aim both at a different build. Normalising belongs at the producer of a
+ * version value (`resolveRegistryLatest`, `readCurrentVersion`,
+ * `readRegistryCache`, `pinShippedSpec`), where the choice is deliberate and
+ * visible; a producer that names something else gets a name no version can have.
+ */
+export const versionDirFor = (home, version) => {
+  const triple = exactVersion(version);
+  const name = triple && triple === String(version).trim() ? triple : UNUSABLE_VERSION_DIR;
+  return join(home, name);
+};
+export const packageDirFor = (home, version) => join(versionDirFor(home, version), 'node_modules', MCP_PACKAGE);
 export const lockPathFor = (home) => join(home, WARM_LOCK_NAME);
 
 /** `<home>/<version>/.inuse/` — one empty file per claiming pid. */
@@ -173,8 +208,10 @@ export const liveInUsePids = (home, version, {
  *
  * 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.
+ * lives its version dir must not be pruned. A claim that cannot be written is
+ * reported, never swallowed: `prepareMcpSpawn` refuses to exec from a dir it
+ * could not claim (Vera 74903), because an unclaimed dir is one the pruner is
+ * free to `rm -rf` while this seat is running out of it.
  */
 export const claimInUse = ({
   home,
@@ -184,15 +221,30 @@ export const claimInUse = ({
   writeFile = writeFileSync,
 } = {}) => {
   try {
-    if (!isUsableWarmHome(home) || !parseVersion(version) || parsePid(pid) === null) return false;
+    if (!isUsableWarmHome(home) || !parseVersion(version) || parsePid(pid) === null) {
+      return { claimed: false, reason: 'not_claimable' };
+    }
     mkdir(inUseDirFor(home, version), { recursive: true });
     writeFile(inUseMarkerPath(home, version, pid), '');
-    return true;
-  } catch {
-    return false;
+    return { claimed: true, reason: null };
+  } catch (error) {
+    // The errno is the difference between a home nobody can write to and a
+    // `.inuse` path that is a file, and only one of those is worth a log line
+    // that says which.
+    return { claimed: false, reason: (error && error.code) || 'claim_failed' };
   }
 };
 
+/**
+ * Say it out loud. A seat whose claim failed is still a seat, but it must not be
+ * a silent one: warn() is injectable so a test can hold the sentence.
+ */
+const defaultWarn = (line) => {
+  try {
+    process.stderr.write(`${line}\n`);
+  } catch { /* a seat that cannot warn still runs */ }
+};
+
 const defaultRead = (path) => {
   try {
     return existsSync(path) ? readFileSync(path, 'utf8') : null;
@@ -219,8 +271,8 @@ const defaultExists = (path) => {
 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;
+  const version = exactVersion(raw.trim());
+  return version || null;
 };
 
 /**
@@ -265,6 +317,9 @@ const readBinInPackageDir = (pkgDir, {
 
 /** The bin of a version dir inside the seat's home. */
 export const readBinPath = (home, version, options = {}) => {
+  // Truthiness of `parseVersion` is truthiness of `exactVersion`; the check that
+  // matters here is `versionDirFor` refusing a name that is not a triple, so a
+  // reader naming `0.3.14-rc.1` gets nothing rather than 0.3.14's build.
   if (!parseVersion(version)) return null;
   return readBinInPackageDir(packageDirFor(home, version), options);
 };
@@ -300,7 +355,10 @@ export const newestInstalledVersion = (home, {
   readBin = (h, v) => readBinPath(h, v),
 } = {}) => {
   const versions = readDir(home)
-    .filter((name) => parseVersion(name))
+    // An exact triple, not a prefix match: a dir literally named `0.3.13-rc.1`
+    // is not `0.3.13`, and normalising the name would point this read at a dir
+    // the caller never mentioned.
+    .filter((name) => exactVersion(name) === name)
     .filter((name) => readBin(home, name))
     .sort((a, b) => {
       const [am, an, ap] = parseVersion(a);
@@ -315,6 +373,39 @@ const isUnpinnedShippedSpec = (spec) => (
   spec === MCP_PACKAGE || spec === `${MCP_PACKAGE}@latest`
 );
 
+/**
+ * The shipped command with its spec pinned to `version`, or the command
+ * unchanged when there is no version to pin to.
+ *
+ * Only slot 2 is touched, and only after `isShippedCommonlyMcpCommand` has
+ * proven the slot is the package spec — so `npx`, its `-y` and every other
+ * entry survive byte-for-byte, and a command that is not the shipped 3-arg form
+ * cannot be rewritten by construction. npx keys its cache dir by the spec
+ * string, which is the whole point: `@latest` is one dir every seat shares and a
+ * publish rewrites in place, while `@0.3.13` is a dir only this version ever
+ * uses.
+ */
+export const pinShippedSpec = (command, version) => {
+  // The triple, not the string: this spec is an argv entry we execute, so a
+  // version carrying a suffix must not reach it.
+  const safe = exactVersion(version);
+  if (!Array.isArray(command) || !safe) return command;
+  let changed = false;
+  const pinned = command.map((part, index) => {
+    // Slot 2 only. `isShippedCommonlyMcpCommand` already proves the package sits
+    // in slot 2 of a 3-arg command, so this bound is not reachable today — it is
+    // here so the function is safe to read on its own, and it is armed in the
+    // tests rather than argued from the shape check (Vera, 74940).
+    if (index !== 2 || !isUnpinnedShippedSpec(String(part))) return part;
+    changed = true;
+    return `${MCP_PACKAGE}@${safe}`;
+  });
+  // The same reference when nothing changed, so a caller can use identity as the
+  // "did this spawn's spec move" check — the convention the rest of this module
+  // already keeps (`ensureCommonlyMcpServer`, `withholdGrantBroker`).
+  return changed ? pinned : command;
+};
+
 /**
  * What a spawn should execute, and where that decision came from.
  *
@@ -353,7 +444,23 @@ export const planMcpSpawn = (command, {
       };
     }
   }
-  return { command, source: 'declared', version: null, reason: 'home-empty' };
+  // No usable home, so the declaration is what runs — and the one thing worth
+  // changing about it is the spec string. The cached registry answer is used
+  // rather than a fresh lookup because this function is synchronous and on the
+  // spawn's critical path, and the warm refreshes that same cache on the same
+  // TTL (`REGISTRY_TTL_MS`). A stale-but-real version still gives this run its
+  // own npx dir, which `@latest` does not, and a stale cache means the registry
+  // has been answering nothing for a while — the case where `@latest` is least
+  // usable. `pinned` is reported so the caller can log which spec it ran.
+  const cached = readRegistryCache(target, { readFile });
+  const pinned = cached ? pinShippedSpec(command, cached.version) : command;
+  return {
+    command: pinned,
+    source: 'declared',
+    version: null,
+    reason: 'home-empty',
+    pinned: cached ? cached.version : null,
+  };
 };
 
 /** The warm's cached registry answer, with its age. */
@@ -362,9 +469,9 @@ export const readRegistryCache = (home, { readFile = defaultRead } = {}) => {
   if (typeof raw !== 'string') return null;
   try {
     const parsed = JSON.parse(raw);
-    const version = parsed && typeof parsed.version === 'string' ? parsed.version : null;
+    const version = exactVersion(parsed && parsed.version);
     const checkedAt = parsed && Number.isFinite(parsed.checkedAt) ? parsed.checkedAt : null;
-    if (!parseVersion(version) || checkedAt === null) return null;
+    if (!version || checkedAt === null) return null;
     return { version, checkedAt };
   } catch {
     return null;
@@ -435,17 +542,31 @@ export const prepareMcpSpawn = (command, {
   now = Date.now(),
   readFile = defaultRead,
   exists = defaultExists,
+  warn = defaultWarn,
 } = {}) => {
   const resolvedHome = resolveHomeDir(home);
   try {
     const plan = planMcpSpawn(command, { home: resolvedHome, readFile, exists });
     // Claim the version this spawn is about to execute from, BEFORE returning the
     // command, so a prune that runs while the seat is starting cannot take it.
-    if (plan.source === 'home') claimInUse({ home: resolvedHome, version: plan.version });
+    let resolved = plan.command;
+    if (plan.source === 'home') {
+      const claim = claimInUse({ home: resolvedHome, version: plan.version });
+      // A claim that could not be written means the pruner may take this very
+      // directory out from under the running seat — the hazard the claim exists
+      // for. The declared command is what the guard approved and what no pruner
+      // owns, so the spawn falls back to it rather than executing unprotected,
+      // and says why. The warm still runs: with the seat off the dir, a prune or
+      // a repair is safe.
+      if (!claim.claimed) {
+        warn(`commonly: cannot claim ${versionDirFor(resolvedHome, plan.version)} for pid ${process.pid} (${claim.reason}) — running the declared command instead, because a prune could delete the directory this seat would run from`);
+        resolved = command;
+      }
+    }
     const due = !lockPresent(resolvedHome, { exists })
       && warmLooksWanted(resolvedHome, plan.version, { now, readFile });
     if (due) kickWarm({ home: resolvedHome, apiUrl, spawnImpl, childPath });
-    return plan.command;
+    return resolved;
   } catch {
     // A rewrite that throws must not cost the seat its tools: the declaration
     // is what the guard approved, and it still runs.

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

@@ -23,6 +23,28 @@ export const parseVersion = (spec) => {
   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

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

@@ -34,7 +34,7 @@ import {
   WARM_RESULTS, currentPointerPath, isUsableWarmHome, liveInUsePids, lockPathFor,
   readBinInPrefix, versionDirFor,
 } from './mcp-home.js';
-import { MCP_PACKAGE, parseVersion } from './mcp-server-version.js';
+import { MCP_PACKAGE, exactVersion, 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';
@@ -147,9 +147,9 @@ export const resolveRegistryLatest = async (home, {
   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' };
+      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 */ }
   }
@@ -164,18 +164,24 @@ export const resolveRegistryLatest = async (home, {
       version = raw.replace(/^"|"$/g, '');
     }
   }
-  if (version && parseVersion(version)) {
+  // 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, checkedAt: now }));
+      writeFile(cachePath, JSON.stringify({ version: safe, checkedAt: now }));
     } catch { /* a cache we cannot write is not a warm we should fail */ }
-    return { version, source: 'registry' };
+    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);
-      if (parseVersion(parsed.version)) return { version: parsed.version, source: 'stale-cache' };
+      const stale = parsed ? exactVersion(parsed.version) : null;
+      if (stale) return { version: stale, source: 'stale-cache' };
     } catch { /* fall through */ }
   }
   return { version: null, source: 'unavailable' };
@@ -267,7 +273,10 @@ export const pruneVersionDirs = (home, current, {
   },
   livePids = (version) => liveInUsePids(home, version),
 } = {}) => {
-  const versions = readDir(home).filter((name) => parseVersion(name));
+  // 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);
@@ -309,8 +318,7 @@ export const warmMcpHome = async (home, {
   readCurrent = (h) => {
     const raw = readIfAny(currentPointerPath(h));
     if (typeof raw !== 'string') return null;
-    const trimmed = raw.trim();
-    return parseVersion(trimmed) ? trimmed : null;
+    return exactVersion(raw.trim()) || null;
   },
   keep = KEEP_VERSION_DIRS,
 } = {}) => {