@commonlyai/cli 0.1.63 → 0.1.65

package/package.json

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

package/src/commands/agent.js

@@ -46,6 +46,7 @@ import {
   DEFAULT_HOOK_TIMEOUT_MS,
   clampHookTimeoutMs,
   forwardHookEvent,
+  resolveHookToken,
   writeHooksConfig,
 } from '../lib/hooks-config.js';
 import {
@@ -2863,7 +2864,14 @@ Use --local to find the name you'd pass to 'agent run' or 'agent detach'.
       const record = loadAgentToken(name);
       const podId = opts.pod || record?.podId;
       const instanceUrl = record?.instanceUrl || process.env.COMMONLY_API_URL || resolveInstanceUrl(undefined);
-      const token = process.env.COMMONLY_AGENT_TOKEN;
+      // Read the credential the way the runtime that spawned this hook carries
+      // it: the launcher FILE first, the value variable second. Reading the bare
+      // variable is what this did, and `resolveHookToken` therefore existed,
+      // was tested, and never ran on a real hook — so on a seat whose MCP
+      // declaration moved to the file, the token was absent, `forwardHookEvent`
+      // returned `hook_unavailable`, and the hook silently stopped deciding
+      // anything (the fail-open posture makes that a silence, not an error).
+      const token = resolveHookToken({ env: process.env });
       const chunks = [];
       if (!process.stdin.isTTY) {
         for await (const chunk of process.stdin) chunks.push(chunk);

package/src/lib/adapters/claude.js

@@ -72,6 +72,8 @@ import {
   publicClaudeStateRoot,
   wrapArgvWithSeatbelt,
 } from '../sandbox/seatbelt.js';
+import { CREDENTIAL_FILE_VAR, CREDENTIAL_KEY, writeCredentialFile } from '../credential-file.js';
+import { deliverSeatCredential, withholdRuntimeCredential } from '../mcp-credential-delivery.js';
 import { buildMemoryPreamble } from '../memory-bridge.js';
 
 // See codex.js for the rationale on bumping the default + env override.
@@ -176,7 +178,7 @@ const preparePublicClaudeState = async (ctx) => {
   return { statePath, tmpPath, configPath };
 };
 
-const buildClaudeEnv = (input, state, expansionEnv = {}) => {
+const buildClaudeEnv = (input, state, expansionEnv = {}, credentialFile = null) => {
   const source = input || process.env;
   const output = state ? {} : { ...source };
   if (state) {
@@ -190,7 +192,16 @@ const buildClaudeEnv = (input, state, expansionEnv = {}) => {
     output.XDG_DATA_HOME = join(state.statePath, '.local', 'share');
   }
   Object.assign(output, expansionEnv);
-  return output;
+  // `source` is usually the process environment, which is where the documented
+  // bootstrap export lives — so the value has to be taken out here rather than
+  // merely left out of the declaration rewrite. It survives only when THIS
+  // spawn's declaration still references it (claude substitutes args, url and
+  // headers literally, and `buildMcpExpansionEnv` reports that by carrying the
+  // key); the file path goes in either way so a hook child can name it.
+  return withholdRuntimeCredential(output, {
+    credentialFile,
+    keepsValue: expansionEnv[CREDENTIAL_KEY] !== undefined,
+  });
 };
 
 const absoluteToolDeny = (path) => `Read(/${path}/**)`;
@@ -270,19 +281,41 @@ const runClaude = ({ cmd, args, cwd, env, timeoutMs, spawnImpl = childSpawn }) =
 // readable to any co-confined child allowed to read that config directory.
 //
 // Recognised placeholders:
-//   ${COMMONLY_AGENT_TOKEN}   — the per-(agent, pod) cm_agent_* runtime token
+//   ${COMMONLY_TOKEN_FILE}    — the PATH of this spawn's credential file
 //   ${COMMONLY_API_URL}       — the instance URL the agent is attached to
 //   ${COMMONLY_INSTANCE_URL}  — alias for COMMONLY_API_URL (clearer in context)
 //
+// The credential itself is deliberately NOT among these values (TASK-083). It
+// used to be, and that put the bearer token in claude's environment, where every
+// MCP child and every hook inherited it — measured on a live seat: the pi seat's
+// MCP child carried COMMONLY_AGENT_TOKEN and COMMONLY_LITELLM_KEY. What the
+// child gets instead is a path to a 0600 file that only this spawn can name,
+// written into the SAME per-spawn directory claude is already handed for
+// --mcp-config. That directory is not a coincidence: it is the one path outside
+// the workspace that the Seatbelt profile admits (sandbox/seatbelt.js admits
+// `subpath(mcpConfigDir)` and nothing under ~/.commonly but the seat's own
+// statePath), so a credential file placed anywhere else is unreadable by the
+// very child it is written for.
+//
 // Only values actually referenced by this MCP declaration are added to the
 // child environment. Unknown placeholders remain in JSON so Claude's parser
 // fails clearly instead of receiving a silent empty string.
 const buildMcpExpansionEnv = (mcpConfig, ctx) => {
   const serialized = JSON.stringify(mcpConfig);
   const values = {
-    COMMONLY_AGENT_TOKEN: ctx.runtimeToken || '',
+    [CREDENTIAL_FILE_VAR]: ctx.credentialFile || '',
     COMMONLY_API_URL: ctx.instanceUrl || '',
     COMMONLY_INSTANCE_URL: ctx.instanceUrl || '',
+    // Whether THIS one is exposed is decided by the loop below, not here: it is
+    // added only when the value is non-empty AND the declaration still references
+    // it — and `serialized` is the config AFTER the credential rewrite, which is
+    // what moves the default declaration off this value and onto the file. A
+    // reference the rewrite cannot move (args, url, headers, or a string that
+    // merely contains the placeholder) keeps the value for that spawn, because
+    // claude substitutes those literally and there is no file channel for them.
+    // That is the measured carve-out, and createMcpConfig warns when it applies
+    // so the seat still carrying the value is named rather than assumed fixed.
+    COMMONLY_AGENT_TOKEN: ctx.runtimeToken || '',
   };
   const output = {};
   for (const [key, value] of Object.entries(values)) {
@@ -291,7 +324,7 @@ const buildMcpExpansionEnv = (mcpConfig, ctx) => {
   return output;
 };
 
-const buildMcpConfig = (mcpServers) => {
+const buildMcpConfig = (mcpServers, ctx = {}) => {
   // Shape: `{ mcpServers: { <name>: { ... } } }` — the standard MCP client
   // config, which claude's `--mcp-config` reads directly.
   const mcpServersMap = {};
@@ -303,7 +336,15 @@ const buildMcpConfig = (mcpServers) => {
       entry.command = command;
       if (args.length) entry.args = args;
     }
-    if (server.env) entry.env = { ...server.env };
+    // A declared credential is rewritten to the file channel here, in the
+    // 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, {
+        credentialFile: ctx.credentialFile,
+        label: 'claude',
+      }).env;
+    }
     if (server.headers) entry.headers = { ...server.headers };
     mcpServersMap[server.name] = entry;
   }
@@ -318,9 +359,15 @@ const buildMcpConfig = (mcpServers) => {
 const createMcpConfig = async (mcpServers, ctx = {}) => {
   const dir = await mkdtemp(join(tmpdir(), 'commonly-claude-mcp-'));
   const file = join(dir, 'mcp-config.json');
-  const config = buildMcpConfig(mcpServers);
+  let credential = null;
   try {
     await chmod(dir, 0o700);
+    // Written BEFORE the config, because the config may only reference it. It
+    // lives inside `dir` so the spawn's existing finally removes it with the
+    // config — no second lifecycle to get wrong — and so it is inside the one
+    // non-workspace path the Seatbelt profile admits.
+    credential = writeCredentialFile(ctx.runtimeToken, { agentName: ctx.agentName || 'agent', root: dir });
+    const config = buildMcpConfig(mcpServers, { ...ctx, credentialFile: credential?.path || null });
     await writeFile(
       file,
       JSON.stringify(config, null, 2),
@@ -329,11 +376,20 @@ const createMcpConfig = async (mcpServers, ctx = {}) => {
     // writeFile's mode only applies when creating. Pin the final mode too so
     // this stays correct if the implementation ever starts reusing the path.
     await chmod(file, 0o600);
-    return {
-      dir,
-      file,
-      expansionEnv: buildMcpExpansionEnv(config, ctx),
-    };
+    const expansionEnv = buildMcpExpansionEnv(config, {
+      ...ctx,
+      credentialFile: credential?.path || null,
+    });
+    if (expansionEnv[CREDENTIAL_KEY]) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        `[claude] this declaration references ${CREDENTIAL_KEY} in a field claude `
+        + 'substitutes literally (args, url, headers, or a larger string), so the '
+        + "value stays in claude's environment for this spawn and every MCP child "
+        + `inherits it. Put the credential on the entry's env to get the file channel.`,
+      );
+    }
+    return { dir, file, credential, expansionEnv };
   } catch (err) {
     try { await rm(dir, { recursive: true, force: true }); } catch { /* ignore */ }
     throw err;
@@ -610,6 +666,7 @@ export default {
         mcpConfig = await createMcpConfig(ctx.environment.mcp, {
           runtimeToken: ctx.runtimeToken,
           instanceUrl: ctx.instanceUrl,
+          agentName: ctx.agentName,
         });
       }
       const spawnCtx = {
@@ -621,6 +678,7 @@ export default {
           ctx.env,
           publicClaudeState,
           mcpConfig?.expansionEnv,
+          mcpConfig?.credential?.path || null,
         ),
       };
       const { cmd, args, env } = await prepareArgv(baseArgs, spawnCtx);
@@ -654,6 +712,7 @@ export default {
             ctx.env,
             publicClaudeState,
             mcpConfig?.expansionEnv,
+            mcpConfig?.credential?.path || null,
           ),
         });
         const stdout = await runClaude({

package/src/lib/adapters/codex.js

@@ -56,6 +56,8 @@ import {
   join,
   resolve as pathResolve,
 } from 'path';
+import { CREDENTIAL_KEY, writeCredentialFile } from '../credential-file.js';
+import { deliverSeatCredential, withholdRuntimeCredential } from '../mcp-credential-delivery.js';
 import { buildMemoryPreamble } from '../memory-bridge.js';
 import { isLegacySandboxTrust, normalizeSandboxTrust } from '../environment.js';
 
@@ -107,7 +109,7 @@ const buildPrompt = buildMemoryPreamble;
 //     argv override. Command lines are visible to other same-user processes
 //     unless the OS sandbox blocks process inspection; keeping bearer tokens
 //     out of argv is an independent defense.
-const SUBSTITUTION_KEYS = ['COMMONLY_AGENT_TOKEN', 'COMMONLY_API_URL', 'COMMONLY_INSTANCE_URL'];
+const SUBSTITUTION_KEYS = ['COMMONLY_AGENT_TOKEN', 'COMMONLY_TOKEN_FILE', 'COMMONLY_API_URL', 'COMMONLY_INSTANCE_URL'];
 const PLACEHOLDER_RE = /\$\{(COMMONLY_[A-Z_]+)\}/g;
 
 const substitutePlaceholders = (value, ctx) => {
@@ -115,6 +117,10 @@ const substitutePlaceholders = (value, ctx) => {
   if (!value.includes('${COMMONLY_')) return value;
   const subs = {
     COMMONLY_AGENT_TOKEN: ctx.runtimeToken || '',
+    // The path, not the token: a declared server that can open a file reads the
+    // credential from there, and the PATH is not a secret, so it may ride in the
+    // argv override below (TASK-083).
+    COMMONLY_TOKEN_FILE: ctx.credentialFile || '',
     COMMONLY_API_URL: ctx.instanceUrl || '',
     COMMONLY_INSTANCE_URL: ctx.instanceUrl || '',
   };
@@ -131,10 +137,43 @@ const buildMcpOverrideArgs = (mcpServers, ctx = {}) => {
   const flags = [];
   const forwardedEnv = {};
   for (const server of mcpServers || []) {
+    // 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, {
+      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));
+    // 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
+    // substitutes it literally, and a command line is readable by every
+    // same-user process. So an entry that needs the token in its argv is
+    // refused whole (skipped, with the reason) rather than half-wired: emitting
+    // its other flags would leave a server the guard approved and the seat
+    // cannot use, and emitting this one would publish the secret. Measured
+    // before writing this: substitution did put `cm_agent_*` into
+    // `mcp_servers.<name>.args` on the -c command line (TASK-083).
+    const carriesTokenInArgv = (value) => !!ctx.runtimeToken
+      && typeof value === 'string'
+      && value.includes(ctx.runtimeToken);
+    if (carriesTokenInArgv(command) || rest.some(carriesTokenInArgv)) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        `[codex] MCP server ${server.name} wants the seat credential as a command `
+        + 'argument, where codex substitutes a literal and every same-user process '
+        + 'can read it. Skipping that entry: declare the credential on the entry\'s '
+        + 'env, where it rides as a file path instead of a value.',
+      );
+      continue;
+    }
     flags.push('-c', `mcp_servers.${server.name}.command=${toml(command)}`);
     // The user opted into every server present in the environment spec.
     // Public permission profiles + approval_policy=never otherwise auto-deny
@@ -151,7 +190,7 @@ const buildMcpOverrideArgs = (mcpServers, ctx = {}) => {
     }
     const envEntries = [];
     const envVars = [];
-    for (const [key, rawValue] of Object.entries(server.env || {})) {
+    for (const [key, rawValue] of Object.entries(declaredEnv)) {
       const value = substitutePlaceholders(rawValue, ctx);
       const carriesRuntimeToken = !!ctx.runtimeToken
         && typeof value === 'string'
@@ -175,6 +214,19 @@ const buildMcpOverrideArgs = (mcpServers, ctx = {}) => {
       flags.push('-c', `mcp_servers.${server.name}.env_vars=[${envVars.map(toml).join(',')}]`);
     }
   }
+  if (Object.keys(forwardedEnv).length > 0) {
+    // The value is forwarded only for a declaration that needs the token as a
+    // LITERAL somewhere a file path is not a value — command args, or a string
+    // that merely contains it. That is the measured carve-out (TASK-082), and it
+    // is not silent: this is the seat whose environment still carries a secret.
+    // eslint-disable-next-line no-console
+    console.warn(
+      `[codex] this declaration needs ${CREDENTIAL_KEY} as a literal (command args, or a `
+      + 'value that contains it), so the token is forwarded to codex for this spawn '
+      + "and every MCP child inherits it. Put the credential on the entry's env to "
+      + 'get the file channel.',
+    );
+  }
   return { flags, forwardedEnv };
 };
 
@@ -441,11 +493,20 @@ export default {
     // so a crash in the middle of the spawn doesn't leak files in $TMPDIR.
     const dir = await mkdtemp(join(tmpdir(), 'commonly-codex-'));
     const outputFile = join(dir, 'last-message.txt');
+    // Written into the per-spawn directory this adapter already creates and
+    // removes: codex reads and writes inside it for --output-last-message, so a
+    // child it spawns can reach a file there, which is the one property this
+    // file has to have. Outside it the path is an unreadable promise.
+    const credential = writeCredentialFile(ctx.runtimeToken, {
+      agentName: ctx.agentName || 'agent',
+      root: dir,
+    });
 
     try {
       const mcp = buildMcpOverrideArgs(ctx.environment?.mcp, {
         runtimeToken: ctx.runtimeToken,
         instanceUrl: ctx.instanceUrl,
+        credentialFile: credential?.path || null,
       });
       // A derived record stores `trust: 'public'` and no mode (the block is
       // platform-independent; see cli/src/lib/default-environment.js). Codex's
@@ -475,6 +536,15 @@ export default {
         effort: ctx.environment?.effort,
       });
       const childEnv = { ...(ctx.env || process.env), ...mcp.forwardedEnv };
+      // Derived from the process environment, so the bootstrap export has to be
+      // taken back out: the declaration above moved our server onto the file,
+      // and a value left here is a value codex's own children inherit. Kept only
+      // when the substitution genuinely needed it (`forwardedEnv` names that
+      // carve-out, and the warning above it is emitted for the same spawn).
+      withholdRuntimeCredential(childEnv, {
+        credentialFile: credential?.path || null,
+        keepsValue: mcp.forwardedEnv[CREDENTIAL_KEY] !== undefined,
+      });
       if (publicSandboxMode !== null) {
         childEnv.CODEX_HOME = await preparePublicCodexHome(ctx);
       }

package/src/lib/adapters/pi-mcp-client.mjs

@@ -18,10 +18,12 @@
  */
 
 import { spawn } from 'node:child_process';
+import { closeSync, readFileSync } from 'node:fs';
 import {
-  closeSync, readFileSync, existsSync,
-} from 'node:fs';
-import { dirname, join } from 'node:path';
+  MCP_PACKAGE, PIPE_READER_VERSION, describeMcpCommand, versionOlderThan,
+} from '../mcp-server-version.js';
+
+import { CREDENTIAL_FILE_VAR, CREDENTIAL_KEY } from '../credential-file.js';
 
 /**
  * The grant broker's path. wren's ruling for the daemon-side half of TASK-063:
@@ -104,94 +106,90 @@ export const connectMcp = (server, opts = {}) => (typeof server?.url === 'string
  * carries only a pointer to it (`COMMONLY_TOKEN_FD=3`) — not a secret. The
  * child end of that pipe is read to EOF.
  *
+ * WHERE THE TOKEN COMES FROM. The launcher writes a per-spawn 0600 file and the
+ * declaration names it with `${COMMONLY_TOKEN_FILE}` — a PATH, not a secret — so
+ * the runtime's own environment never holds the token (TASK-082/083). A
+ * declaration that instead carries the literal token in `COMMONLY_AGENT_TOKEN`
+ * still works: that is the older channel, and it is the operator's to declare.
+ * Whichever named the credential, the child gets it on the pipe and its own
+ * environment is left clean.
+ *
  * THE PIPE IS ONLY AVAILABLE WHERE WE SPAWN. This is the pi path; claude and
  * codex let their own CLI start the server (claude expands `${VAR}` in its own
- * process env, codex rides `mcp_servers.*.env_vars`), so a pipe opened here
- * never reaches that grandchild. Those two still hand the token over in their
- * runtime's environment, which is a separate, still-open half of the same row.
+ * process env, codex writes a plain `mcp_servers.*.env` entry), so a pipe opened
+ * here never reaches that grandchild. Those two deliver the PATH instead, which
+ * is what let the token leave their runtime environments too.
  *
  * THE OLD SERVER STILL WORKS. `@commonlyai/mcp` only learned to read the pipe in
- * 0.3.11, and a seat may pin an older one — the sprint seats run a staging
- * checkout of 0.3.4 — so a declaration whose command names an older
+ * 0.3.11, and a seat may pin an older one — the five staging seats ran a checkout
+ * of 0.3.7 when this was measured (2026-09-19; the doc here said 0.3.4, which was
+ * true two weeks earlier) — so a declaration whose command names an older
  * `@commonlyai/mcp` keeps the environment variable AS WELL, with a warning that
  * names the pin. An operator can also opt out explicitly with
  * `COMMONLY_TOKEN_CHANNEL=env` in the entry's own env. Otherwise the token is
  * piped and the environment is left clean.
  */
-export const CREDENTIAL_KEY = 'COMMONLY_AGENT_TOKEN';
+export { CREDENTIAL_KEY, CREDENTIAL_FILE_VAR };
+
 export const CREDENTIAL_FD_VAR = 'COMMONLY_TOKEN_FD';
 export const CREDENTIAL_CHANNEL_VAR = 'COMMONLY_TOKEN_CHANNEL';
 export const CREDENTIAL_FD = 3;
 
-/** The `@commonlyai/mcp` release whose `loadConfig` reads the pipe channel. */
-export const PIPE_READER_VERSION = [0, 3, 11];
-
-const MCP_PACKAGE = '@commonlyai/mcp';
-
-const parseVersion = (spec) => {
-  const match = /^(\d+)\.(\d+)\.(\d+)/.exec(String(spec || '').trim());
-  return match ? [Number(match[1]), Number(match[2]), Number(match[3])] : null;
-};
-
-const olderThanPipeReader = (version) => {
-  if (!version) return null;
-  for (let i = 0; i < 3; i += 1) {
-    if (version[i] !== PIPE_READER_VERSION[i]) return version[i] < PIPE_READER_VERSION[i];
-  }
-  return false;
-};
-
 /**
- * What an `@commonlyai/mcp` command would run, or null when the command cannot
- * be identified as that package at all.
+ * The only variables a spawned MCP server inherits from us.
  *
- * 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.
+ * This list is DERIVED, not guessed: each entry exists because a real child
+ * failed without it, and a child that only fails at spawn is the worst failure
+ * shape there is (TASK-083). `PATH` runs the command (and, for a seat, carries
+ * the seat-launch shim directory prepended, so it must be passed through rather
+ * than canonicalised); `HOME` is where `npx` keeps the cache it fetches
+ * `@commonlyai/mcp` into, which a cold start needs; `TMPDIR` was measured in a
+ * live child on macOS, where /var/folders is not /tmp; the proxy and CA names
+ * are absent on this machine, so an operator behind a proxy or a private CA is
+ * the case that cannot be exercised here — including them unset costs nothing,
+ * and without them that operator's cold `npx` would fail in a way that reads as
+ * this change regressing.
  *
- * `{ 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.
+ * Deliberately NOT a prefix match: a variable named `COMMONLY_*` is ours to hand
+ * over explicitly, and a variable named like a secret is exactly what an
+ * allowlist exists to drop.
  */
-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 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.
-    }
+export const CHILD_ENV_ALLOWLIST = Object.freeze([
+  'PATH',
+  'HOME',
+  'TMPDIR',
+  'HTTPS_PROXY',
+  'HTTP_PROXY',
+  'NO_PROXY',
+  'NODE_EXTRA_CA_CERTS',
+]);
+
+/**
+ * The environment a spawned MCP server gets: the allowlist above, then whatever
+ * the entry itself declared, and nothing else. The daemon's environment is not a
+ * channel into a child — `...process.env` used to make it one, which is how a
+ * third-party server came to hold our seat token and the model key.
+ */
+export const buildChildEnv = (parentEnv, declaredEnv) => {
+  const out = {};
+  for (const key of CHILD_ENV_ALLOWLIST) {
+    const value = parentEnv ? parentEnv[key] : undefined;
+    if (value !== undefined) out[key] = value;
   }
-  return null;
+  return Object.assign(out, declaredEnv || {});
 };
 
+/**
+ * The channel predicates live in `../mcp-server-version.js`, because the claude
+ * and codex adapters have to answer the same question and a second copy of it
+ * would drift silently in one of them.
+ */
+export {
+  MCP_PACKAGE, PIPE_READER_VERSION, FILE_READER_VERSION, parseVersion, describeMcpCommand,
+} from '../mcp-server-version.js';
+
+const olderThanPipeReader = (version) => versionOlderThan(version, PIPE_READER_VERSION);
+
 /**
  * Split a declared env map into the child's environment and the credential to
  * hand over the pipe.
@@ -201,16 +199,44 @@ export const describeMcpCommand = (command, { readTextFile = (p) => (existsSync(
  * server, or the declaration opted out explicitly. Everything else gets the
  * pointer variable and no secret.
  */
-export const splitCredential = (env, command, { onWarn = (m) => process.stderr.write(`${m}\n`) } = {}) => {
+export const splitCredential = (env, command, {
+  onWarn = (m) => process.stderr.write(`${m}\n`),
+  readCredentialFile = (path) => readFileSync(path, 'utf8'),
+} = {}) => {
   const declared = { ...(env || {}) };
-  const credential = declared[CREDENTIAL_KEY];
+  const declaredFile = declared[CREDENTIAL_FILE_VAR];
   const requested = String(declared[CREDENTIAL_CHANNEL_VAR] || '').trim().toLowerCase();
   delete declared[CREDENTIAL_CHANNEL_VAR];
+  let credential = null;
+  let fromFile = false;
+  // A declaration that names a file is using the launcher channel, and that is
+  // the one to honour: if it ALSO carries a literal token, the literal is the
+  // leftover of an older declaration, and preferring it would keep the secret in
+  // the very place this exists to empty.
+  if (declaredFile !== undefined && String(declaredFile).trim() !== '') {
+    // The launcher channel: the declaration names a path, and the credential is
+    // read here so the child never needs the file (or the token) at all.
+    const path = String(declaredFile).trim();
+    let raw;
+    try {
+      raw = readCredentialFile(path);
+    } catch (err) {
+      throw new Error(`the declared credential file could not be read: ${path}: ${err.message}`);
+    }
+    credential = String(raw ?? '').trim();
+    if (!credential) throw new Error(`the declared credential file carried nothing: ${path}`);
+    fromFile = true;
+  } else if (declared[CREDENTIAL_KEY]) {
+    credential = declared[CREDENTIAL_KEY];
+  }
   if (!credential) {
     delete declared[CREDENTIAL_KEY];
+    delete declared[CREDENTIAL_FILE_VAR];
     return { env: declared, credential: null, keepInEnv: false };
   }
   if (requested === 'env') {
+    declared[CREDENTIAL_KEY] = credential;
+    delete declared[CREDENTIAL_FILE_VAR];
     return { env: declared, credential: null, keepInEnv: true };
   }
   const server = describeMcpCommand(command);
@@ -223,25 +249,32 @@ export const splitCredential = (env, command, { onWarn = (m) => process.stderr.w
   }
   if (server.version && olderThanPipeReader(server.version) === true) {
     onWarn(`[pi-mcp-client] ${command[0]} runs ${MCP_PACKAGE} ${server.version.join('.')}, which predates the pipe channel (0.3.11): keeping the token in the child environment. Unpin it, or set ${CREDENTIAL_CHANNEL_VAR}=env to say so on purpose.`);
+    declared[CREDENTIAL_KEY] = credential;
+    delete declared[CREDENTIAL_FILE_VAR];
     return { env: declared, credential: null, keepInEnv: true };
   }
   delete declared[CREDENTIAL_KEY];
+  // The pipe carries the credential, so the child needs neither the token nor the
+  // path: one declared channel, and it is the fd.
+  delete declared[CREDENTIAL_FILE_VAR];
   declared[CREDENTIAL_FD_VAR] = String(CREDENTIAL_FD);
-  return { env: declared, credential, keepInEnv: false };
+  return { env: declared, credential, keepInEnv: false, fromFile };
 };
 
 /** A minimal MCP stdio client: initialize, tools/list, tools/call. */
 export const connectStdioMcp = ({
   name, command, env,
 }, {
-  spawnImpl = spawn, timeoutMs = 60_000, onWarn,
+  spawnImpl = spawn, timeoutMs = 60_000, onWarn, parentEnv = process.env, readCredentialFile,
 } = {}) => {
   const [cmd, ...args] = command;
-  const { env: declaredEnv, credential, keepInEnv } = splitCredential(env, command, onWarn ? { onWarn } : {});
-  // The inherited environment is stripped of the key unless an old server has to
-  // read it there: the daemon's own environment is not a channel into a child,
-  // and `...process.env` used to make it one.
-  const childEnv = { ...process.env, ...declaredEnv };
+  const opts = onWarn ? { onWarn } : {};
+  if (readCredentialFile) opts.readCredentialFile = readCredentialFile;
+  const { env: declaredEnv, credential, keepInEnv } = splitCredential(env, command, opts);
+  // The child gets an ALLOWLIST plus its own declaration — never the daemon's
+  // environment. `...process.env` is what let a third-party MCP server inherit
+  // both the seat token and the model key (TASK-083).
+  const childEnv = buildChildEnv(parentEnv, declaredEnv);
   if (!keepInEnv) delete childEnv[CREDENTIAL_KEY];
   const stdio = credential ? ['pipe', 'pipe', 'pipe', 'pipe'] : ['pipe', 'pipe', 'pipe'];
   const proc = spawnImpl(cmd, args, { env: childEnv, stdio });

package/src/lib/adapters/pi.js

@@ -40,6 +40,8 @@ import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
 import { buildMemoryPreamble } from '../memory-bridge.js';
 import { GRANT_BROKER_REFUSAL, isGrantBrokerUrl } from './pi-mcp-client.mjs';
+import { deliverSeatCredential, withholdRuntimeCredential } from '../mcp-credential-delivery.js';
+import { removeCredentialFile, writeCredentialFile } from '../credential-file.js';
 
 const DEFAULT_TIMEOUT_MS = (() => {
   const fallback = 15 * 60 * 1000;
@@ -68,12 +70,17 @@ const BRIDGE_PATH = join(dirname(fileURLToPath(import.meta.url)), 'pi-commonly-m
 // Same substitution contract as claude.js / codex.js: ${COMMONLY_*}
 // placeholders in the declared MCP env are the wrapper's per-(agent, pod)
 // runtime values, filled at spawn time.
-const SUBSTITUTION_KEYS = ['COMMONLY_AGENT_TOKEN', 'COMMONLY_API_URL', 'COMMONLY_INSTANCE_URL'];
+const SUBSTITUTION_KEYS = ['COMMONLY_AGENT_TOKEN', 'COMMONLY_TOKEN_FILE', 'COMMONLY_API_URL', 'COMMONLY_INSTANCE_URL'];
 const PLACEHOLDER_RE = /\$\{(COMMONLY_[A-Z_]+)\}/g;
 const substitutePlaceholders = (value, ctx) => {
   if (typeof value !== 'string' || !value.includes('${COMMONLY_')) return value;
   const subs = {
     COMMONLY_AGENT_TOKEN: ctx.runtimeToken || '',
+    // The PATH of this spawn's credential file. The bridge reads the file and
+    // hands the VALUE to the server on fd 3, so the token still never reaches a
+    // child's environment — but the payload that travels to the bridge carries a
+    // path rather than the secret (TASK-083).
+    COMMONLY_TOKEN_FILE: ctx.credentialFile || '',
     COMMONLY_API_URL: ctx.instanceUrl || '',
     COMMONLY_INSTANCE_URL: ctx.instanceUrl || '',
   };
@@ -198,7 +205,14 @@ export const resolveMcpServers = (mcpServers, ctx = {}) => {
       carried.push({
         name: server.name,
         command: server.command.map((a) => substitutePlaceholders(a, ctx)),
-        env: Object.fromEntries(Object.entries(server.env || {}).map(([k, v]) => [k, substitutePlaceholders(v, 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, {
+            credentialFile: ctx.credentialFile,
+            label: 'pi',
+          }).env,
+        ).map(([k, v]) => [k, substitutePlaceholders(v, ctx)])),
       });
       continue;
     }
@@ -384,27 +398,55 @@ export default {
     const fullPrompt = buildMemoryPreamble(prompt, ctx.memoryLongTerm, { freshSession: !isResume });
     await writeFile(join(agentDir, 'models.json'), `${JSON.stringify(buildModelsJson(provider, model), null, 2)}\n`, { mode: 0o600 });
 
-    const servers = resolveMcpServers(ctx.environment?.mcp, ctx);
-    const childEnv = {
-      ...baseEnv,
-      PI_CODING_AGENT_DIR: agentDir,
-      PI_SKIP_VERSION_CHECK: '1',
-    };
-    const args = buildArgs({
-      prompt: fullPrompt, provider: provider.name, model, thinking, sessionId, isResume, sessionDir,
-      bridge: servers.length ? (ctx._bridgePath || BRIDGE_PATH) : null,
+    // One credential file per spawn, inside this seat's own 0700 home — pi has no
+    // enforced sandbox, so the seat's home is the narrowest place that is still
+    // readable by the bridge. The value the server receives still travels on fd 3
+    // (pi-mcp-client's fd channel); the file is where the launcher puts it.
+    const credential = writeCredentialFile(ctx.runtimeToken, {
+      agentName: ctx.agentName || 'agent',
+      root: join(home, 'credentials'),
     });
+    try {
+      const servers = resolveMcpServers(ctx.environment?.mcp, {
+        ...ctx,
+        credentialFile: credential?.path || null,
+      });
+      const childEnv = {
+        ...baseEnv,
+        PI_CODING_AGENT_DIR: agentDir,
+        PI_SKIP_VERSION_CHECK: '1',
+      };
+      // `baseEnv` is normally the process environment, which carries the
+      // bootstrap export. Nothing below this process needs the value: the bridge
+      // is handed the servers, their resolved values included, over fd 3. It has
+      // to come out rather than merely stop being added, because pi's `bash`
+      // tool spawns children with `{ ...process.env }`, so a copy here is a copy
+      // in the seat's shell — and the file path goes in, so a hook resolves its
+      // credential without the value.
+      withholdRuntimeCredential(childEnv, {
+        credentialFile: credential?.path || null,
+      });
+      const args = buildArgs({
+        prompt: fullPrompt, provider: provider.name, model, thinking, sessionId, isResume, sessionDir,
+        bridge: servers.length ? (ctx._bridgePath || BRIDGE_PATH) : null,
+      });
 
-    const reply = await runPi({
-      args,
-      cwd: ctx.cwd,
-      env: childEnv,
-      payload: servers.length ? JSON.stringify(servers) : undefined,
-      timeoutMs: ctx.timeoutMs || DEFAULT_TIMEOUT_MS,
-      spawnImpl: ctx._spawnImpl, // test seam only — do not use in production
-    });
-    // Empty text with a clean exit is a silent turn; the run loop treats it
-    // as NO_REPLY-shaped and re-delivers on its own rules.
-    return { text: reply.text, newSessionId: sessionId };
+      const reply = await runPi({
+        args,
+        cwd: ctx.cwd,
+        env: childEnv,
+        payload: servers.length ? JSON.stringify(servers) : undefined,
+        timeoutMs: ctx.timeoutMs || DEFAULT_TIMEOUT_MS,
+        spawnImpl: ctx._spawnImpl, // test seam only — do not use in production
+      });
+      // Empty text with a clean exit is a silent turn; the run loop treats it
+      // as NO_REPLY-shaped and re-delivers on its own rules.
+      return { text: reply.text, newSessionId: sessionId };
+    } finally {
+      // Best effort: the bridge has already read what it needs by the time the
+      // turn ends, and a token file that outlives its turn is a token file that
+      // sits in a home for the next one.
+      removeCredentialFile(credential);
+    }
   },
 };

package/src/lib/credential-file.js

@@ -0,0 +1,92 @@
+/**
+ * A per-spawn credential file: the launcher channel for the runtime token
+ * (TASK-082/083, ruled 2026-09-19 — "a credential file, only its PATH in the
+ * env").
+ *
+ * WHY A FILE AND NOT THE ENVIRONMENT. The token used to ride the runtime's own
+ * environment (claude expands `${COMMONLY_AGENT_TOKEN}` from it, codex forwards
+ * it through `mcp_servers.*.env_vars`), which means every child of the runtime
+ * inherited it — measured on 2026-09-19: a `@playwright/mcp` process held the
+ * seat's `COMMONLY_AGENT_TOKEN`, and a pi seat's MCP child held the daemon's
+ * `COMMONLY_LITELLM_KEY`. A PATH is not a secret, so handing the path to the
+ * runtime is safe even though the token it names is not, and an unrelated MCP
+ * server that inherits the runtime's environment gets nothing it can use.
+ *
+ * WHY PER SPAWN. The file lives only as long as one spawn of one runtime, in a
+ * directory only its owner can traverse (0700), with the file itself 0600. A
+ * fixed path would widen the window to "since the first spawn" and would let two
+ * concurrent seats share one credential by accident.
+ *
+ * The caller names the root; this module never invents one, because the only
+ * root it could invent is a directory no adapter cleans up.
+ *
+ * The reader side is `readToken` in `commonly-mcp/src/client.js`, which resolves
+ * fd, then file, then environment — by declaration, and refuses to fall through
+ * from a declared source that cannot be read.
+ */
+import { chmodSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+
+/** The variable a child reads to find the credential. Never carries the token. */
+export const CREDENTIAL_FILE_VAR = 'COMMONLY_TOKEN_FILE';
+
+/**
+ * The variable that USED to carry the token itself, and still does for a server
+ * that cannot read anything else. Kept beside the file var so the two channels
+ * are named in one place rather than one per adapter.
+ */
+export const CREDENTIAL_KEY = 'COMMONLY_AGENT_TOKEN';
+
+/**
+ * Write `token` to a fresh 0600 file under `root` and return its path, or null
+ * when there is no token to write (a seat bootstrapping without one).
+ *
+ * `root` is REQUIRED. It used to default to the CLI's own state directory, which
+ * meant a caller that forgot it wrote a live credential into
+ * `~/.commonly/credentials` — a directory no adapter cleans, because that is not
+ * where adapters put theirs. Measured 2026-09-20: 32 such directories on the
+ * fleet host, 24 of them written by this repo's own harnesses, all holding a
+ * seat credential. A missing root is now an error instead of a silent write into
+ * the operator's home. The token check stays first, so "no token, nothing
+ * written" remains true without a root.
+ *
+ * `fs` is injectable so tests can assert the mode and the path shape without
+ * writing into the operator's home.
+ */
+export const writeCredentialFile = (token, {
+  agentName = 'agent',
+  root,
+  fs = { mkdirSync, writeFileSync, chmodSync, rmSync },
+  now = () => Date.now(),
+  random = () => randomBytes(4).toString('hex'),
+} = {}) => {
+  const value = typeof token === 'string' ? token.trim() : '';
+  if (!value) return null;
+  if (typeof root !== 'string' || !root.trim()) {
+    throw new Error(
+      'writeCredentialFile requires an explicit root: an omitted root used to fall back to '
+      + '~/.commonly/credentials, where nothing sweeps the credential files it writes',
+    );
+  }
+  const dir = join(root, `${agentName}-${now()}-${random()}`);
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const path = join(dir, 'token');
+  fs.writeFileSync(path, value, { mode: 0o600 });
+  // writeFileSync's mode is subject to the process umask, so a 0022 umask still
+  // produces 0644. chmod is the assertion, not a courtesy.
+  fs.chmodSync(path, 0o600);
+  return { path, dir };
+};
+
+/** Best-effort removal once the spawn that owns the file has ended. */
+export const removeCredentialFile = (written, { fs = { rmSync } } = {}) => {
+  const dir = typeof written === 'string' ? dirname(written) : written?.dir;
+  if (!dir) return false;
+  try {
+    fs.rmSync(dir, { recursive: true, force: true });
+    return true;
+  } catch {
+    return false;
+  }
+};

package/src/lib/hooks-config.js

@@ -2,6 +2,7 @@ import { readFileSync, writeFileSync, mkdirSync, existsSync, realpathSync } from
 import { dirname, join, resolve as pathResolve, isAbsolute, relative } from 'path';
 import { homedir } from 'os';
 import { createHash } from 'crypto';
+import { CREDENTIAL_FILE_VAR } from './credential-file.js';
 
 export const HOOK_EVENTS = ['PreToolUse', 'PostToolUse', 'Stop', 'SubagentStop'];
 export const DEFAULT_HOOK_TIMEOUT_MS = 3000;
@@ -155,9 +156,39 @@ export const writeHooksConfig = ({
  * positive decision returned by the Commonly endpoint; D7 does not let a
  * missing/slow ledger become an accidental write blocker.
  */
+/**
+ * The hook's credential, resolved the way the runtime it runs inside resolves it.
+ *
+ * A hook is a child process of the seat's runtime, so it sees that runtime's
+ * environment — which is exactly the environment TASK-083 emptied of the token.
+ * Reading only COMMONLY_AGENT_TOKEN would therefore leave every hook on a
+ * migrated seat with no credential, and because this path fails open by design
+ * (the `hook_unavailable` return below), the symptom would be a tool-policy hook
+ * that silently stopped deciding anything. So the launcher file comes first, and
+ * the value variable stays as the fallback for a seat whose declaration has not
+ * migrated.
+ *
+ * Unlike the MCP reader, a declared-but-unreadable file does NOT throw here: a
+ * hook that dies is a hook the runtime reports as broken, and this function's
+ * documented posture is to fail open rather than become an accidental blocker.
+ */
+export const resolveHookToken = ({
+  env = process.env,
+  readTokenFile = (path) => readFileSync(path, 'utf8'),
+} = {}) => {
+  const path = env[CREDENTIAL_FILE_VAR];
+  if (typeof path === 'string' && path.trim() !== '') {
+    try {
+      const fromFile = readTokenFile(path).trim();
+      if (fromFile) return fromFile;
+    } catch { /* fall through to the value channel */ }
+  }
+  return env.COMMONLY_AGENT_TOKEN;
+};
+
 export const forwardHookEvent = async ({
   endpoint,
-  token = process.env.COMMONLY_AGENT_TOKEN,
+  token = resolveHookToken(),
   input = '',
   timeoutMs = DEFAULT_HOOK_TIMEOUT_MS,
   fetchImpl = globalThis.fetch,

package/src/lib/mcp-credential-delivery.js

@@ -0,0 +1,121 @@
+/**
+ * How a declared MCP server receives the seat credential, for the two adapters
+ * that cannot hand it over on a pipe.
+ *
+ * The pi bridge spawns the server itself, so it can pipe the credential on an
+ * inherited fd (see `pi-mcp-client.mjs`). Claude and codex do not: each of them
+ * starts the server inside its own process tree, so the only two channels
+ * available are (a) a value in the runtime's environment, which the whole
+ * subtree inherits, or (b) a PATH in the declaration that the server itself
+ * reads. (b) is the one that leaves the token where it belongs.
+ *
+ * This module makes that choice in ONE place, because three call sites deciding
+ * version thresholds independently is how one of them ends up handing over the
+ * value while the others hand over the path.
+ *
+ * The rewrite is of the DECLARATION, not of the value: an entry that named
+ * `COMMONLY_AGENT_TOKEN` comes back naming `COMMONLY_TOKEN_FILE`, so the value
+ * never exists in the runtime's environment to be inherited, logged, or dumped
+ * by an unrelated MCP server that a seat was granted.
+ */
+import { CREDENTIAL_FILE_VAR, CREDENTIAL_KEY } from './credential-file.js';
+import {
+  FILE_READER_VERSION, MCP_PACKAGE, describeMcpCommand, versionOlderThan,
+} from './mcp-server-version.js';
+
+/** What a declaration should say to receive the credential as a path. */
+export const CREDENTIAL_FILE_PLACEHOLDER = '${COMMONLY_TOKEN_FILE}';
+
+/**
+ * What a runtime's OWN environment may carry, once the declarations are settled.
+ *
+ * The rewrite above decides what a CHILD is told. It does not decide what the
+ * runtime process itself carries, and that is a separate leak with the same
+ * symptom: the credential is exported for bootstrap (`agent run`, the daemon),
+ * so an adapter that derives its runtime environment from `process.env` hands
+ * the value back to the runtime — and to every MCP child, hook and shell below
+ * it — however the declaration was rewritten. Measured (Vera, 70455): four tests
+ * that pass in a runner without the variable fail with it set, and the value
+ * they saw was the runner's own.
+ *
+ * So the PATH of this spawn's file goes in (a path is not a secret, and a hook
+ * process resolves its credential from it — see `hooks-config.resolveHookToken`)
+ * and the VALUE comes out, unless a carve-out genuinely needs the value here:
+ * a field the adapter substitutes LITERALLY has no file channel, so `keepsValue`
+ * is passed in by the adapter rather than inferred, and the spawn that keeps a
+ * secret says so in its own warning.
+ *
+ * The PATH comes out too when there is no file for THIS spawn. The runtime
+ * environment is derived from `process.env`, so a launcher whose own process was
+ * spawned by another seat inherits that seat's `COMMONLY_TOKEN_FILE` and hands
+ * it to the runtime and every MCP child below it — a path to a credential this
+ * launcher did not mint. The value was already deleted here for that reason; the
+ * path is the same leak with a smaller blast radius.
+ */
+export const withholdRuntimeCredential = (env, { credentialFile = null, keepsValue = false } = {}) => {
+  if (credentialFile) {
+    env[CREDENTIAL_FILE_VAR] = credentialFile;
+  } else {
+    delete env[CREDENTIAL_FILE_VAR];
+  }
+  if (!keepsValue) delete env[CREDENTIAL_KEY];
+  return env;
+};
+
+/** What a declaration says when it asks for the seat credential (the old shape). */
+export const CREDENTIAL_PLACEHOLDER = '${COMMONLY_AGENT_TOKEN}';
+
+/**
+ * Rewrite one server's declared environment so the credential arrives as a path.
+ *
+ * Returns `{ env, delivered }` where `delivered` is one of:
+ *   'path'        — the declaration now names the file; the adapter expands it
+ *   'env'         — the value stays in the environment, deliberately (see below)
+ *   'none'        — nothing to deliver: the entry declares no credential
+ *   'unavailable' — no launcher credential file exists for this spawn
+ *
+ * `env` is a fresh object; the caller's declaration is never mutated.
+ */
+export const deliverSeatCredential = (server, {
+  credentialFile,
+  onWarn = (message) => process.stderr.write(`${message}\n`),
+  label = 'mcp',
+} = {}) => {
+  const env = { ...((server || {}).env || {}) };
+  if (env[CREDENTIAL_FILE_VAR] !== undefined && String(env[CREDENTIAL_FILE_VAR]).trim() !== '') {
+    // Already on the launcher channel — an operator who set this by hand, or a
+    // record written after this shipped. Nothing to rewrite.
+    return { env, delivered: 'path' };
+  }
+  if (env[CREDENTIAL_KEY] === undefined) return { env, delivered: 'none' };
+  if (!credentialFile) {
+    // No launcher wrote a file, so there is nothing to point at. Leave the
+    // declaration exactly as it was rather than handing over a path to nowhere.
+    return { env, delivered: 'unavailable' };
+  }
+  const ours = describeMcpCommand((server || {}).command);
+  if (!ours) {
+    // Somebody else's server. Their declaration is theirs: we do not know their
+    // protocol, so replacing their variable with a path would break a server we
+    // have no business redefining.
+    onWarn(`[${label}] ${server?.name} is not ${MCP_PACKAGE} but declares ${CREDENTIAL_KEY}; leaving that declaration alone. Declare the seat credential on the commonly entry instead.`);
+    return { env, delivered: 'env' };
+  }
+  if (versionOlderThan(ours.version, FILE_READER_VERSION) === true) {
+    // Measured, not hypothetical: five seats run a hand-patched staging checkout
+    // at 0.3.7, whose reader only understands the environment. Handing it a path
+    // it cannot read would take its tools away rather than its secret.
+    onWarn(`[${label}] ${server.name} runs @commonlyai/mcp ${ours.version.join('.')}, which predates the credential file (${FILE_READER_VERSION.join('.')}): keeping the token in the environment. Unpin it, or move that seat off this checkout.`);
+    return { env, delivered: 'env' };
+  }
+  if (String(env[CREDENTIAL_KEY]) !== CREDENTIAL_PLACEHOLDER) {
+    // A literal token in a declaration is stale by construction — seat tokens
+    // rotate, and this one was read when the record was written. Superseding it
+    // with the live credential is a repair, but it IS a change in what the seat
+    // sends, so it is said out loud rather than done quietly.
+    onWarn(`[${label}] ${server.name} declares a literal ${CREDENTIAL_KEY}; superseding it with this spawn's credential file.`);
+  }
+  delete env[CREDENTIAL_KEY];
+  env[CREDENTIAL_FILE_VAR] = CREDENTIAL_FILE_PLACEHOLDER;
+  return { env, delivered: 'path' };
+};

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

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