@commonlyai/cli 0.1.61 → 0.1.64

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commonlyai/cli",
-  "version": "0.1.61",
+  "version": "0.1.64",
   "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 });