fix(mcpl): scrub host env from stdio MCPL children

[ian-de-marcellus]

Problem. Stdio MCPL server children inherit the host's entire environment. On a multi-resident host the .env carries provider API keys and several bots' tokens, and every connector child can read all of them, including the ones meant for a different server.

Fix. buildChildEnv passes a small allowlist (PATH, HOME, locale/LC_*, TMPDIR, TLS roots, display vars, and Windows equivalents; see CHILD_ENV_ALLOWLIST) plus the server's own configured env. inheritEnv: true on a server config restores full inheritance for servers that genuinely need it.

Breaking for servers that relied on an inherited variable: declare it in the server's env (recipes can ${VAR}-substitute) or set inheritEnv. The changelog fragment is marked breaking.

Tests. test/mcpl-child-env.test.ts covers dropping host secrets while keeping operating vars and LC_*, declared env winning over host values, inheritEnv, and a real spawned stdio child seeing only allowlist + declared env. Full suite: 958 pass / 0 fail.

This has run in production on a 5-resident host since 2026-09-23.

🤖 Generated with Claude Code

[greptile-apps]

Confidence Score: 4/5

[High risk] Changes how child processes inherit environment variables.

The PR should not merge until default stdio children retain required operating variables on Windows.

Findings

1.  Windows operating variables disappear ▶
2.  Probe exit leaves test waiting ▶

Fix with agent prompt

### Issue 1
src/mcpl/transport.ts:133
If a Windows host enumerates variables as `Path`, `SystemRoot`, or `ComSpec`, this exact-case check drops them because the allowlist contains only uppercase spellings. Every default stdio child then starts without variables it previously inherited, so a server that launches tools by name or needs `SystemRoot` can fail. Match these names case-insensitively on Windows while keeping their original spelling.

### Issue 2
test/mcpl-child-env.test.ts:61-65
If the spawned probe exits without printing a line, the transport emits `close`, but this promise listens only for `line` and `error`. The test cannot report the exit as a useful failure or reach `transport.close()`; a child that stays running without output can stall the suite. Handle `close` and ensure cleanup on every outcome.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Summary

The PR limits stdio MCPL children to an operating-variable allowlist plus server-declared variables, and adds an opt-in for full inheritance.

• Adds configuration documentation, a breaking-change notice, and child-environment tests.
• The allowlist needs to account for Windows environment-key casing.

_{Reviews (1) · Last reviewed commit: "fix(mcpl): scrub host env from stdio MCP..."}

[greptile-apps]

Windows operating variables disappear

If a Windows host enumerates variables as Path, SystemRoot, or ComSpec, this exact-case check drops them because the allowlist contains only uppercase spellings. Every default stdio child then starts without variables it previously inherited, so a server that launches tools by name or needs SystemRoot can fail. Match these names case-insensitively on Windows while keeping their original spelling.

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/mcpl/transport.ts
Line: 133

Comment:
**Windows operating variables disappear**

If a Windows host enumerates variables as `Path`, `SystemRoot`, or `ComSpec`, this exact-case check drops them because the allowlist contains only uppercase spellings. Every default stdio child then starts without variables it previously inherited, so a server that launches tools by name or needs `SystemRoot` can fail. Match these names case-insensitively on Windows while keeping their original spelling.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

[greptile-apps]

Probe exit leaves test waiting

If the spawned probe exits without printing a line, the transport emits close, but this promise listens only for line and error. The test cannot report the exit as a useful failure or reach transport.close(); a child that stays running without output can stall the suite. Handle close and ensure cleanup on every outcome.

Prompt To Fix With AI

This is a comment left during a code review.
Path: test/mcpl-child-env.test.ts
Line: 61-65

Comment:
**Probe exit leaves test waiting**

If the spawned probe exits without printing a line, the transport emits `close`, but this promise listens only for `line` and `error`. The test cannot report the exit as a useful failure or reach `transport.close()`; a child that stays running without output can stall the suite. Handle `close` and ensure cleanup on every outcome.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

[slimepriestess]

Review — exact head 81353cba943188527348157676c8e805e090aea9

Disposition: APPROVE for what it does, with one thing the changelog must say (or one lift to take) before that changelog sentence is true, and three non-blocking asks.

What it does. Stdio MCPL children stop inheriting the host's whole environment; buildChildEnv gives them an operating allowlist (CHILD_ENV_ALLOWLIST + LC_*) plus the server's declared env, with inheritEnv: true as the documented way back. The threat is real on a multi-resident host: every connector child could read every other bot's token and the provider keys.

Receipts, worktree on the exact head. mcpl-child-env 4/4. Mutation: put the spawn back to { ...process.env, ...config.env } and only the spawned-child case goes red (the three pure cases stay green, as they should — they test buildChildEnv, not the spawn). Full suite from a clean dist/: 962 tests / 958 pass / 0 fail. Merge-tree against current main 507ea8b: no conflicts. git diff --check clean.

The fix is partial, and the changelog doesn't say so. The framework spawns exactly two kinds of child. This PR fixes one. The other, the python interpreter behind codeExecution (src/code-execution/py-runner.ts, env: { ...process.env, PYTHONUNBUFFERED: '1' }), runs model-authored code, so on a host with code execution enabled any agent can still read every provider key and bot token with one os.environ. That's the same threat this PR names, on a child that deserves the discipline more. Probe on this head: a PyRunner script printing os.environ.get(<host secret>) prints the secret. (Found by the second read on our side; verified here.)

Lift, stacked on this head, yours to cherry-pick: slimepriestess/agent-framework@9e8ec77c790591223199fb797d87a68523842084 (fix/child-env-code-execution). PyRunner builds its env through the same buildChildEnv (allowlist + its own env, inheritEnv as the escape hatch, PYTHONUNBUFFERED kept); CodeExecutionConfig carries env/inheritEnv and both runner sites thread them; the changelog fragment gains the code-execution line. Test code-execution-env: the secret comes back None (red on 81353cb, printed the secret), declared env reaches the interpreter, inheritEnv restores the host env. Suite with the lift: 964 / 960 / 0. If you'd rather keep this PR to MCPL, the changelog sentence "one server's credentials … are no longer readable by another" needs a clause saying code-execution children still inherit until a follow-up.

Impact on the recipes I can see. connectome-host's mcpServers entries resolve to McplServerConfig, so they all go through this transport. clerk and knowledge-miner declare their secrets as ${VAR} in env and set ZULIP_RC_PATH, so the design's own story holds for them. zulip-miner declares no rc path and points at ../zulip-mcp (hyphen) rather than ../zulip_mcp: if that build reads ZULIP_* from env it now starts and then fails auth, which is exactly how this break presents. You've run this on the 5-resident host since 9/23 so you'll know which servers needed inheritEnv; worth one sentence in the fragment naming the symptom (the child starts, its first platform call fails).

Non-blocking asks.

1. Windows casing (Greptile's first finding is right). Object.entries(hostEnv) on Windows yields Path, SystemRoot, ComSpec, and the exact-case membership test drops them. The MCP SDK's getDefaultEnvironment iterates the allowlist and reads process.env[key], which Node resolves case-insensitively on win32. Same shape here, then the LC_* sweep. Its Windows list also carries HOMEDRIVE, HOMEPATH, SYSTEMDRIVE, USERNAME, PROCESSOR_ARCHITECTURE, PROGRAMFILES.
2. Proxy variables. HTTP_PROXY / HTTPS_PROXY / NO_PROXY (and lowercase twins) aren't on the list, and connectors are network clients: behind a proxy the child starts and then can't reach Discord or Zulip, with no hint that the env is why. Operator-level, not another server's credential, inherited before. I'd add them.
3. ()-prefixed values. The SDK skips values starting with () (exported shell functions). Cheap to copy.

Greptile's second finding (the spawned-child probe waits only on line/error, so a child that exits without printing hangs the test) is test hygiene; a close listener that rejects would make a failure legible.

Reviewed from the fork-and-worktree side only; merge is yours/antra's.

[slimepriestess]

Follow-up delivered: the py-runner half of this (the second spawn path, flagged in the review) is now its own PR, rebased onto post-merge main — #193. The stacked lift head 9e8ec77 is superseded by 4ed84f7 there.