@commonlyai/cli 0.1.100 → 0.1.101

package/package.json

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

package/src/lib/adapters/claude.js

@@ -75,7 +75,7 @@ import {
 import { CREDENTIAL_FILE_VAR, CREDENTIAL_KEY, writeCredentialFile } from '../credential-file.js';
 import { supportedGitHooks } from '../commit-attribution.js';
 import { deliverSeatCredential, withholdRuntimeCredential } from '../mcp-credential-delivery.js';
-import { prepareMcpSpawn } from '../mcp-home.js';
+import { prepareMcpSpawn, PUBLIC_MCP_UNAVAILABLE_NOTICE, selectedMcpVersionDir } from '../mcp-home.js';
 import { buildMemoryPreamble } from '../memory-bridge.js';
 import { adapterFailure, spawnCredentials } from '../upstream-refusal.js';
 
@@ -412,8 +412,14 @@ const buildMcpConfig = (mcpServers, ctx = {}) => {
     // 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 })
+      ? prepareMcpSpawn(server.command, {
+        apiUrl: ctx.instanceUrl, publicSeat: ctx.publicSeat,
+      })
       : null;
+    if (server.command && !spawnCommand) {
+      ctx.unavailableMcp?.push(server.name);
+      continue;
+    }
     const executed = spawnCommand ? { ...server, command: spawnCommand } : server;
     const entry = { type: server.transport || 'stdio' };
     if (server.url) entry.url = server.url;
@@ -439,6 +445,8 @@ const buildMcpConfig = (mcpServers, ctx = {}) => {
     }
     if (headerHelper) entry.headersHelper = headerHelper.command;
     mcpServersMap[server.name] = entry;
+    const versionDir = ctx.publicSeat && selectedMcpVersionDir(spawnCommand);
+    if (versionDir) ctx.mcpReadDirectories?.push(versionDir);
   }
   return { mcpServers: mcpServersMap };
 };
@@ -462,10 +470,14 @@ const createMcpConfig = async (mcpServers, ctx = {}) => {
     const dynamicHeaderHelpers = credential?.path
       ? await createTokenHeaderHelpers(mcpServers, dir)
       : new Map();
+    const unavailableMcp = [];
+    const mcpReadDirectories = [];
     const config = buildMcpConfig(mcpServers, {
       ...ctx,
       credentialFile: credential?.path || null,
       dynamicHeaderHelpers,
+      unavailableMcp,
+      mcpReadDirectories,
     });
     await writeFile(
       file,
@@ -489,7 +501,7 @@ const createMcpConfig = async (mcpServers, ctx = {}) => {
         + `inherits it. Put the credential on the entry's env to get the file channel.`,
       );
     }
-    return { dir, file, credential, expansionEnv };
+    return { dir, file, credential, expansionEnv, unavailableMcp, mcpReadDirectories };
   } catch (err) {
     try { await rm(dir, { recursive: true, force: true }); } catch { /* ignore */ }
     throw err;
@@ -636,6 +648,7 @@ const prepareArgv = async (innerArgv, ctx) => {
       mcpConfigDir: ctx.mcpConfigDir,
       executablePaths: [...mcpExecutables, ...commitHookExecutables, ...originalHookExecutables],
       allowClaudeRuntimeAccess: true,
+      readOnlyDirectories: ctx.mcpReadDirectories || [],
     });
     return {
       cmd: wrapped[0],
@@ -664,7 +677,7 @@ const prepareArgv = async (innerArgv, ctx) => {
     const claudeBin = resolveClaudePath(claudeEnv);
     const wrapped = wrapArgvWithBwrap([claudeBin, ...innerArgv], env, {
       workspacePath: ctx.cwd,
-      readOnlyPaths: [ctx.mcpConfigDir, commitHooksPath, originalHooksPath].filter(Boolean),
+      readOnlyPaths: [ctx.mcpConfigDir, commitHooksPath, originalHooksPath, ...(ctx.mcpReadDirectories || [])].filter(Boolean),
     });
     return { cmd: wrapped[0], args: wrapped.slice(1), env: claudeEnv };
   }
@@ -785,8 +798,12 @@ export default {
           runtimeToken: ctx.runtimeToken,
           instanceUrl: ctx.instanceUrl,
           agentName: ctx.agentName,
+          publicSeat: publicNativeSandbox,
         });
       }
+      if (mcpConfig?.unavailableMcp.length) {
+        baseArgs[1] = `${fullPrompt}\n\n${PUBLIC_MCP_UNAVAILABLE_NOTICE}`;
+      }
       const claudeEnv = buildClaudeEnv(
         ctx.env,
         publicClaudeState,
@@ -800,6 +817,7 @@ export default {
         ...ctx,
         mcpConfigPath: mcpConfig?.file || null,
         mcpConfigDir: mcpConfig?.dir || null,
+        mcpReadDirectories: mcpConfig?.mcpReadDirectories || [],
         publicClaudeState,
         claudeEnv,
       };
@@ -829,11 +847,14 @@ export default {
         // as fresh too: otherwise a session-recovery path is the one fresh
         // session that misses the durable-state cue.
         const freshPrompt = buildPrompt(prompt, ctx.memoryLongTerm, { freshSession: true });
-        const retryBase = ['-p', freshPrompt, '--output-format', 'text', '--session-id', freshId, ...modelArgs];
+        const retryBase = ['-p', mcpConfig?.unavailableMcp.length
+          ? `${freshPrompt}\n\n${PUBLIC_MCP_UNAVAILABLE_NOTICE}` : freshPrompt,
+        '--output-format', 'text', '--session-id', freshId, ...modelArgs];
         const retryCtx = {
           ...ctx,
           mcpConfigPath: mcpConfig?.file || null,
           mcpConfigDir: mcpConfig?.dir || null,
+          mcpReadDirectories: mcpConfig?.mcpReadDirectories || [],
           publicClaudeState,
           claudeEnv: buildClaudeEnv(
             ctx.env,

package/src/lib/adapters/codex.js

@@ -60,7 +60,7 @@ import {
 import { CREDENTIAL_KEY, writeCredentialFile } from '../credential-file.js';
 import { supportedGitHooks } from '../commit-attribution.js';
 import { deliverSeatCredential, withholdRuntimeCredential } from '../mcp-credential-delivery.js';
-import { prepareMcpSpawn } from '../mcp-home.js';
+import { prepareMcpSpawn, PUBLIC_MCP_UNAVAILABLE_NOTICE, selectedMcpVersionDir } from '../mcp-home.js';
 import { buildMemoryPreamble } from '../memory-bridge.js';
 import { isLegacySandboxTrust, normalizeSandboxTrust } from '../environment.js';
 import { adapterFailure, spawnCredentials } from '../upstream-refusal.js';
@@ -140,6 +140,8 @@ const toml = (s) => JSON.stringify(String(s));
 const buildMcpOverrideArgs = (mcpServers, ctx = {}) => {
   const flags = [];
   const forwardedEnv = {};
+  const unavailableMcp = [];
+  const mcpReadDirectories = [];
   for (const server of mcpServers || []) {
     const transport = typeof server?.transport === 'string' ? server.transport.trim().toLowerCase() : 'stdio';
     if (!server?.name || transport !== 'stdio'
@@ -149,7 +151,13 @@ const buildMcpOverrideArgs = (mcpServers, ctx = {}) => {
     // 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 });
+    const spawnCommand = prepareMcpSpawn(server.command, {
+      apiUrl: ctx.instanceUrl, publicSeat: ctx.publicSeat,
+    });
+    if (!spawnCommand) {
+      unavailableMcp.push(server.name);
+      continue;
+    }
     // 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
@@ -185,6 +193,8 @@ const buildMcpOverrideArgs = (mcpServers, ctx = {}) => {
       continue;
     }
     flags.push('-c', `mcp_servers.${server.name}.command=${toml(command)}`);
+    const versionDir = ctx.publicSeat && selectedMcpVersionDir(spawnCommand);
+    if (versionDir) mcpReadDirectories.push(versionDir);
     // The user opted into every server present in the environment spec.
     // Public permission profiles + approval_policy=never otherwise auto-deny
     // side-effecting MCP calls, silently removing the agent's Commonly tools.
@@ -237,7 +247,7 @@ const buildMcpOverrideArgs = (mcpServers, ctx = {}) => {
       + 'get the file channel.',
     );
   }
-  return { flags, forwardedEnv };
+  return { flags, forwardedEnv, unavailableMcp, mcpReadDirectories };
 };
 
 const PUBLIC_PERMISSION_PROFILE = 'commonly_public';
@@ -301,6 +311,7 @@ const preparePublicCodexHome = async (ctx) => {
 const publicPermissionProfileFlags = (
   mode,
   commitAttributionEnv = null,
+  mcpReadDirectories = [],
 ) => {
   if (!PUBLIC_SANDBOX_MODES.has(mode)) {
     throw new Error(
@@ -339,9 +350,10 @@ const publicPermissionProfileFlags = (
     '"~/.aws"="deny"',
     '"~/.config"="deny"',
     '"/private/tmp"="deny"',
-    `":workspace_roots"={"."="${workspaceAccess}",".commonly/**"="deny",".codex/**"="deny","*.env"="deny","*/*.env"="deny","*/*/*.env"="deny"}`,
+    `":workspace_roots"={"."="${workspaceAccess}",".commonly/**"="deny",".codex/**"="deny","*.env"="deny","*/*.env"="deny","*/*/*.env"="deny","**/.npmrc"="deny","**/.yarnrc*"="deny"}`,
     ...(commitHooksPath ? [`${toml(commitHooksPath)}="read"`] : []),
     ...originalHookPaths.map((hookPath) => `${toml(hookPath)}="read"`),
+    ...mcpReadDirectories.map((path) => `${toml(path)}="read"`),
   ].join(',');
   const shellEnvironment = [
     'PATH', 'HOME', 'TMPDIR', 'LANG', 'LC_*',
@@ -391,6 +403,7 @@ const buildArgs = ({
   model = null,
   effort = null,
   commitAttributionEnv = null,
+  mcpReadDirectories = [],
 }) => {
   const publicSandbox = publicSandboxMode !== null;
   // `--dangerously-bypass-approvals-and-sandbox` disables codex CLI's
@@ -413,6 +426,7 @@ const buildArgs = ({
       ...publicPermissionProfileFlags(
         publicSandboxMode,
         commitAttributionEnv,
+        mcpReadDirectories,
       ),
     ]
     : ['--dangerously-bypass-approvals-and-sandbox'];
@@ -588,10 +602,12 @@ export default {
     });
 
     try {
+      const sandbox = normalizeSandboxTrust(ctx.environment?.sandbox);
       const mcp = buildMcpOverrideArgs(ctx.environment?.mcp, {
         runtimeToken: ctx.runtimeToken,
         instanceUrl: ctx.instanceUrl,
         credentialFile: credential?.path || null,
+        publicSeat: sandbox?.trust === 'public',
       });
       // A derived record stores `trust: 'public'` and no mode (the block is
       // platform-independent; see cli/src/lib/default-environment.js). Codex's
@@ -607,15 +623,16 @@ export default {
           + '(Wren 69585).',
         );
       }
-      const sandbox = normalizeSandboxTrust(ctx.environment?.sandbox);
       const publicSandboxMode = sandbox?.trust === 'public'
         ? sandbox?.mode ?? 'workspace'
         : null;
       const args = buildArgs({
         sessionId: ctx.sessionId || null,
-        prompt: fullPrompt,
+        prompt: mcp.unavailableMcp.length
+          ? `${fullPrompt}\n\n${PUBLIC_MCP_UNAVAILABLE_NOTICE}` : fullPrompt,
         outputFile,
         mcpFlags: mcp.flags,
+        mcpReadDirectories: mcp.mcpReadDirectories,
         publicSandboxMode,
         model: ctx.environment?.model,
         effort: ctx.environment?.effort,

package/src/lib/adapters/opencode.js

@@ -39,7 +39,7 @@ import {
 } from 'path';
 import { writeCredentialFile } from '../credential-file.js';
 import { deliverSeatCredential, withholdRuntimeCredential } from '../mcp-credential-delivery.js';
-import { prepareMcpSpawn } from '../mcp-home.js';
+import { prepareMcpSpawn, PUBLIC_MCP_UNAVAILABLE_NOTICE, selectedMcpVersionDir } from '../mcp-home.js';
 import { buildMemoryPreamble } from '../memory-bridge.js';
 import {
   isLegacySandboxTrust,
@@ -82,6 +82,7 @@ const PUBLIC_READ_DENIES = [
   '**/.env.*',
   '**/*.env.*',
 ];
+const PUBLIC_EDIT_DENIES = [...PUBLIC_READ_DENIES, '**/.npmrc', '**/.yarnrc*'];
 const PUBLIC_SAFE_ENV = /^(?:PATH|LANG|LC_[A-Z_]+|TERM|USER|LOGNAME|NO_COLOR|CI|SSL_CERT_FILE|SSL_CERT_DIR)$/;
 
 const statOrNull = async (path) => {
@@ -119,7 +120,13 @@ const buildMcpConfig = (servers, ctx = {}) => {
 
     if (transport === 'stdio') {
       if (!Array.isArray(server.command) || server.command.length === 0) continue;
-      const command = prepareMcpSpawn(server.command, { apiUrl: ctx.instanceUrl });
+      const command = prepareMcpSpawn(server.command, {
+        apiUrl: ctx.instanceUrl, publicSeat: ctx.publicSeat,
+      });
+      if (!command) {
+        ctx.unavailableMcp?.push(server.name);
+        continue;
+      }
       if (runtimeToken && command.some((part) => typeof part === 'string' && part.includes(runtimeToken))) {
         // A bearer token in argv is readable by same-user processes.
         // eslint-disable-next-line no-console
@@ -158,6 +165,8 @@ const buildMcpConfig = (servers, ctx = {}) => {
         ...(Object.keys(env).length ? { environment: env } : {}),
         ...(typeof server.cwd === 'string' ? { cwd: server.cwd } : {}),
       };
+      const versionDir = ctx.publicSeat && selectedMcpVersionDir(command);
+      if (versionDir) ctx.mcpReadDirectories?.push(versionDir);
       continue;
     }
 
@@ -207,8 +216,8 @@ const publicPermissions = (mode, mcpNames) => {
   const edit = { '*': mode === 'read-only' ? 'deny' : 'allow' };
   for (const pattern of PUBLIC_READ_DENIES) {
     read[pattern] = 'deny';
-    edit[pattern] = 'deny';
   }
+  for (const pattern of PUBLIC_EDIT_DENIES) edit[pattern] = 'deny';
   return {
     '*': 'deny',
     read,
@@ -666,10 +675,15 @@ export default {
         ...(stateHome ? [mkdir(stateHome, { recursive: true, mode: 0o700 })] : []),
         ...(cacheHome ? [mkdir(cacheHome, { recursive: true, mode: 0o700 })] : []),
       ]);
+      const unavailableMcp = [];
+      const mcpReadDirectories = [];
       const mcp = buildMcpConfig(ctx.environment?.mcp, {
         runtimeToken: ctx.runtimeToken,
         instanceUrl: ctx.instanceUrl,
         credentialFile: credential?.path || null,
+        publicSeat: isPublic,
+        unavailableMcp,
+        mcpReadDirectories,
       });
       const config = {
         permission: isPublic
@@ -703,7 +717,8 @@ export default {
         credentialFile: credential?.path || null,
       });
       const args = buildArgs({
-        prompt: fullPrompt,
+        prompt: unavailableMcp.length
+          ? `${fullPrompt}\n\n${PUBLIC_MCP_UNAVAILABLE_NOTICE}` : fullPrompt,
         sessionId: ctx.sessionId,
         cwd: ctx.cwd,
         model: qualifiedProviderModel(provider, ctx.environment?.model),
@@ -738,6 +753,7 @@ export default {
             tempDir,
             binary,
             process.execPath,
+            ...mcpReadDirectories,
           ],
         });
         [cmd, ...spawnArgs] = wrapped;
@@ -753,6 +769,7 @@ export default {
           mcpConfigDir: tempDir,
           loopbackNetworkPorts: providerProxy ? [providerProxy.port] : [],
           readOnlyPaths: [],
+          readOnlyDirectories: mcpReadDirectories,
         });
         [cmd, ...spawnArgs] = wrapped;
       }

package/src/lib/adapters/qwen.js

@@ -6,7 +6,7 @@ import { tmpdir } from 'os';
 import { basename, dirname, isAbsolute, join } from 'path';
 import { buildMemoryPreamble } from '../memory-bridge.js';
 import { deliverSeatCredential } from '../mcp-credential-delivery.js';
-import { prepareMcpSpawn } from '../mcp-home.js';
+import { prepareMcpSpawn, PUBLIC_MCP_UNAVAILABLE_NOTICE, selectedMcpVersionDir } from '../mcp-home.js';
 import { writeCredentialFile } from '../credential-file.js';
 import { normalizeSandboxTrust, validateEnvironmentSpec } from '../environment.js';
 import { resolvePublicSandboxMode } from '../sandbox/mode.js';
@@ -88,7 +88,13 @@ export const buildQwenMcpConfig = (servers, ctx) => {
     const transport = server.transport || 'stdio';
     if (transport === 'stdio') {
       if (!Array.isArray(server.command) || !server.command.length) continue;
-      const command = prepareMcpSpawn(server.command, { apiUrl: ctx.instanceUrl });
+      const command = prepareMcpSpawn(server.command, {
+        apiUrl: ctx.instanceUrl, publicSeat: ctx.publicSeat,
+      });
+      if (!command) {
+        ctx.unavailableMcp?.push(server.name);
+        continue;
+      }
       const delivery = deliverSeatCredential({ ...server, command }, {
         credentialFile: ctx.credentialFile,
         label: 'qwen',
@@ -105,6 +111,8 @@ export const buildQwenMcpConfig = (servers, ctx) => {
         command: command[0], args, env,
         ...(server.cwd ? { cwd: server.cwd } : {}),
       };
+      const versionDir = ctx.publicSeat && selectedMcpVersionDir(command);
+      if (versionDir) ctx.mcpReadDirectories?.push(versionDir);
       continue;
     }
     if (transport !== 'http' || typeof server.url !== 'string') {
@@ -271,10 +279,15 @@ export default {
         provider, keyFile, tokenFile: join(tempDir, 'provider-proxy-token'), adapterLabel: 'Qwen',
       });
       const proxyWithBearer = { ...proxy, bearer: (await readFile(proxy.tokenFile, 'utf8')).trim() };
+      const unavailableMcp = [];
+      const mcpReadDirectories = [];
       const mcp = buildQwenMcpConfig(ctx.environment?.mcp, {
         credentialFile: credential?.path || '',
         instanceUrl: ctx.instanceUrl || '',
         runtimeToken: ctx.runtimeToken || '',
+        publicSeat: isPublic,
+        unavailableMcp,
+        mcpReadDirectories,
       });
       await Promise.all([
         writeFile(settingsPath, JSON.stringify({
@@ -294,7 +307,8 @@ export default {
         '--mcp-config', mcpPath, '--exclude-tools', [
           ...EXCLUDED_TOOLS, ...(isPublic ? PUBLIC_READ_TOOLS : []),
         ].join(','),
-        '-o', 'stream-json', '-p', fullPrompt,
+        '-o', 'stream-json', '-p', unavailableMcp.length
+          ? `${fullPrompt}\n\n${PUBLIC_MCP_UNAVAILABLE_NOTICE}` : fullPrompt,
       ];
       let cmd = executable;
       let spawnArgs = args;
@@ -313,7 +327,7 @@ export default {
               ],
             },
           },
-        }, { workspacePath: ctx.cwd, homePath: home, readOnlyPaths: [tempDir, executable, packageDir, process.execPath].filter(Boolean) });
+        }, { workspacePath: ctx.cwd, homePath: home, readOnlyPaths: [tempDir, executable, packageDir, process.execPath, ...mcpReadDirectories].filter(Boolean) });
       } else if (isPublic) {
         if ((ctx._platform || process.platform) !== 'darwin') {
           throw new Error(`public Qwen sandbox.mode=${mode} requires Seatbelt on macOS or bwrap on Linux`);
@@ -325,7 +339,7 @@ export default {
           statePath: home,
           mcpConfigDir: tempDir,
           loopbackNetworkPorts: [proxy.port],
-          readOnlyDirectories: packageDir ? [packageDir] : [],
+          readOnlyDirectories: [...(packageDir ? [packageDir] : []), ...mcpReadDirectories],
         });
       }
       const requestedTimeout = Number(ctx.timeoutMs);

package/src/lib/mcp-home.js

@@ -45,13 +45,14 @@ import {
   existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync,
 } from 'node:fs';
 import { homedir } from 'node:os';
-import { dirname, join, sep } from 'node:path';
+import { dirname, join, relative, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { isShippedCommonlyMcpCommand } from './declared-mcp-guard.js';
 import { MCP_PACKAGE, exactVersion, parseVersion } from './mcp-server-version.js';
 
 /** The env override, so tests (and an operator) can point the home elsewhere. */
 export const MCP_HOME_ENV = 'COMMONLY_MCP_HOME';
+export const PUBLIC_MCP_UNAVAILABLE_NOTICE = 'Commonly runtime notice: An MCP server was not started this turn because no host-prepared executable was ready. Do not claim to have used its tools.';
 
 export const WARM_LOCK_NAME = '.warm.lock';
 export const REGISTRY_CACHE_NAME = '.registry.json';
@@ -324,6 +325,14 @@ export const readBinPath = (home, version, options = {}) => {
   return readBinInPackageDir(packageDirFor(home, version), options);
 };
 
+/** Read grant for only the verified warm build selected for this spawn. */
+export const selectedMcpVersionDir = (command, home = mcpHomeDir()) => {
+  if (!Array.isArray(command) || command.length !== 2 || command[0] !== 'node') return null;
+  const version = relative(home, command[1]).split(sep)[0];
+  if (exactVersion(version) !== version || readBinPath(home, version) !== command[1]) return null;
+  return versionDirFor(home, version);
+};
+
 /**
  * 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
@@ -532,11 +541,14 @@ const lockPresent = (home, { exists = defaultExists } = {}) => exists(lockPathFo
  *
  * 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.
+ * warming, so this spawn just runs the current version. Public seats receive
+ * null if that version is unavailable and the fallback is a package runner;
+ * adapters omit that MCP declaration and tell the seat.
  */
 export const prepareMcpSpawn = (command, {
   home,
   apiUrl = null,
+  publicSeat = false,
   spawnImpl,
   childPath,
   now = Date.now(),
@@ -566,10 +578,15 @@ export const prepareMcpSpawn = (command, {
     const due = !lockPresent(resolvedHome, { exists })
       && warmLooksWanted(resolvedHome, plan.version, { now, readFile });
     if (due) kickWarm({ home: resolvedHome, apiUrl, spawnImpl, childPath });
+    if (publicSeat && resolved[0] === 'npx') {
+      warn('commonly: an MCP server is unavailable for this public turn; no host-prepared executable was ready');
+      return null;
+    }
     return resolved;
   } catch {
-    // A rewrite that throws must not cost the seat its tools: the declaration
-    // is what the guard approved, and it still runs.
+    // Trusted seats retain the declared fallback. A public seat must not
+    // execute a package runner from the workspace even on this failure path.
+    if (publicSeat && command?.[0] === 'npx') return null;
     return command;
   }
 };

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

@@ -107,7 +107,7 @@ export const acquireWarmLock = (home, {
 };
 
 /** Default `npm` runner. Resolves `{ ok, stdout }`; never rejects. */
-export const runCommand = (bin, args, { timeout = REGISTRY_TIMEOUT_MS } = {}) => new Promise((resolve) => {
+export const runCommand = (bin, args, { timeout = REGISTRY_TIMEOUT_MS, cwd } = {}) => new Promise((resolve) => {
   let settled = false;
   let child;
   const done = (result) => {
@@ -116,7 +116,7 @@ export const runCommand = (bin, args, { timeout = REGISTRY_TIMEOUT_MS } = {}) =>
     resolve(result);
   };
   try {
-    child = spawnChild(bin, args, { stdio: ['ignore', 'pipe', 'pipe'], env: process.env });
+    child = spawnChild(bin, args, { stdio: ['ignore', 'pipe', 'pipe'], env: process.env, cwd });
   } catch (error) {
     done({ ok: false, stdout: '', stderr: String(error && error.message) });
     return;
@@ -153,7 +153,9 @@ export const resolveRegistryLatest = async (home, {
       }
     } catch { /* unreadable cache is just a miss */ }
   }
-  const result = await exec('npm', ['view', MCP_PACKAGE, 'version', '--json'], { timeout: REGISTRY_TIMEOUT_MS });
+  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) {
@@ -199,6 +201,7 @@ 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;
@@ -213,6 +216,7 @@ export const probeBin = (binPath, {
   try {
     child = spawnImpl(process.execPath, [binPath], {
       stdio: ['pipe', 'pipe', 'pipe'],
+      cwd,
       env: {
         PATH: process.env.PATH,
         HOME: process.env.HOME,
@@ -343,7 +347,7 @@ export const warmMcpHome = async (home, {
     mkdir(temp);
     const install = await exec('npm', [
       'install', '--prefix', temp, `${MCP_PACKAGE}@${target}`, '--no-save', '--no-audit', '--no-fund',
-    ], { timeout: 5 * 60 * 1000 });
+    ], { timeout: 5 * 60 * 1000, cwd: home });
     if (!install || !install.ok) {
       remove(temp);
       return WARM_RESULTS.INSTALL_FAILED;
@@ -353,7 +357,9 @@ export const warmMcpHome = async (home, {
       remove(temp);
       return WARM_RESULTS.INSTALL_FAILED;
     }
-    const started = await (spawnProbe || probe)(bin, { apiUrl: process.env.COMMONLY_WARM_API_URL });
+    const started = await (spawnProbe || probe)(bin, {
+      apiUrl: process.env.COMMONLY_WARM_API_URL, cwd: home,
+    });
     if (!started) {
       remove(temp);
       return WARM_RESULTS.PROBE_FAILED;