Fix #1219: sanitize inherited CLAUDE_CODE_* env at every Tower spawn

[waleedkadous]

Fixes #1219

Summary

A Tower started from inside a Claude Code session inherits that session's identity markers and hands them to every agent it spawns. Each agent then believes it is a nested child session, disables transcript saving, and becomes unresumable — silently, until crash recovery fails. This routes every Tower-descendant spawn through one sanitizer that strips per-session identity, and adds a codev doctor check for daemons that are already contaminated.

Root Cause

Claude Code plants session markers — CLAUDE_CODE_CHILD_SESSION, CLAUDE_CODE_SESSION_ID, CLAUDE_CODE_ENTRYPOINT, CLAUDE_CODE_EXECPATH, and friends — into every subprocess it creates, so a nested claude can tell it was launched from inside another session. Tower is a daemon, but it inherits the environment of whoever started it, and starting Tower from inside a Claude Code session is routine (afx tower start, pnpm -w run local-install, an architect recovering from a crash). The markers cascade:

claude session → Bash → afx tower start → Tower → shellper → agent claude

Confirmed on a live install rather than assumed: ps eww on two running Tower daemons showed the full marker set, inherited from the shell that started them.

Three code shapes, none of which handled CLAUDE_CODE_*:

1. towerStart() daemonized with env: process.env (agent-farm/commands/tower.ts).
2. Six Tower spawn sites built { ...process.env } and deleted only CLAUDECODE — tower-instances.ts ×2, tower-terminals.ts ×2, tower-routes.ts ×2.
3. createPtySession() sends no env, so builder terminals took the env || process.env branch in handleTerminalCreate and received Tower's whole environment.

shellper-main passes its config env straight to node-pty, which replaces the child environment wholesale — so the env Tower hands to SessionManager.createSession is the agent's env. That makes (2)+(3) load-bearing and (1) the upstream source.

Fix

New packages/codev/src/lib/agent-env.ts with a single sanitizeAgentEnv(): strip what is per-session identity, keep everything else.

Identity is a small, stable, nameable set — four prefix families (CLAUDE_CODE_SESSION_, CLAUDE_CODE_REMOTE_SESSION_, CLAUDE_CODE_BRIDGE_, CLAUDE_CODE_MESSAGING_) plus ten individual names, including the CHILD_SESSION / ENTRYPOINT / EXECPATH nesting triple this issue is about. Configuration is not a nameable set, so it is not enumerated.

Every Tower-descendant spawn routes through it — the daemon spawn, both architect-launch sites, both architect-reconnect sites, terminal-create and shell-create (plus their non-persistent fallbacks), the shellper daemon spawn, and cron task execution. The six hand-rolled delete cleanEnv['CLAUDECODE'] copies collapse into the one helper. afx tower start logs what it scrubbed, and codev doctor grows a Tower Environment section that reads the running daemon's env via ps eww — a daemon started before this fix stays contaminated until restarted, and that was previously invisible.

A supporting commit moves getProcessesOnPort to a leaf agent-farm/utils/port.ts (re-exported, no consumer moves): importing it from the command module dragged utils/shell.ts's module-scope promisify(exec) into the doctor tests, whose node:child_process mock has no exec export.

Why not deny the whole CLAUDE_CODE_* namespace

The first version did exactly that, with a short allowlist, on the theory that a missed marker is worse than a missed config var. The codex CMAP lane rejected it and was right. Checking the shipped claude binary (2.1.261) settled it: it reads 594 distinct CLAUDE_CODE_* variables, overwhelmingly configuration. The allowlist would have silently dropped USE_FOUNDRY, USE_MANTLE, USE_ANTHROPIC_AWS, USE_GATEWAY, SKIP_FOUNDRY_AUTH, SKIP_MANTLE_AUTH, OAUTH_REFRESH_TOKEN, OAUTH_SCOPES, OAUTH_CLIENT_ID, API_BASE_URL, PROXY_URL, HTTPS_PROXY, CLIENT_CERT, MANAGED_SETTINGS_PATH and more.

The original reasoning was wrong about the failure mode: dropping a config var is not harmless. It points an agent at the wrong provider, or strips its subscription credential and reroutes CMAP to the metered API — the #985 scar. No hand-maintained allowlist survives 594 variables.

CLAUDE_PID disposition

Checked against the shipped binary the same way as the 594: CLAUDE_PID is stripped.

It is not read for nested-session detection — its only reader is the pkill guard in the Bash tool's shell prelude, which refuses a pattern matching the Claude CLI's own pid. But it is per-session identity by construction, planted in the same object literal as the marker this issue is about:

function qOe(e){let t={CLAUDECODE:"1", CLAUDE_CODE_SESSION_ID:e.sessionId,
                       CLAUDE_CODE_CHILD_SESSION:"1", CLAUDE_PID:String(process.pid)};
  if(e.source==="agent") t.AI_AGENT=…;
  if(e.effortLevel!==void 0) t.CLAUDE_EFFORT=e.effortLevel; …}

String(process.pid) of one specific process is identity by any reading, and an inherited stale value points that pkill guard at a dead or unrelated pid. So it is in the denylist despite sitting outside the CLAUDE_CODE_ namespace.

CLAUDE_EFFORT is planted by that same function and is deliberately not stripped — which is the useful part of the check: "Claude Code sets it" is not the test. It carries a setting, not an identity, so it is configuration and passes through.

Test Plan

• Regression test added — bugfix-1219-claude-env-leak.test.ts, 31 cases. 9 assertions fail with the spawn-site changes reverted to the pre-fix commit and pass with them; reverting just one of tower-routes.ts's four sites fails 2.
• Build passes
• All tests pass — 5739 passing, 48 skipped

Covered by the regression test:

• Every marker observed on a real contaminated Tower is stripped.
• Whole session families are stripped, not just the names seen so far.
• A MUST_SURVIVE fixture of 24 provider / auth / routing / policy variables — each verified present in the shipped binary, including the Foundry, Mantle, Anthropic-AWS and refresh-token cases — is preserved intact.
• An unrecognised CLAUDE_CODE_* variable is kept, not dropped.
• Every listed spawn site calls the sanitizer the expected number of times, and carries none of the raw-environment shapes a reverted or copy-pasted site would take.
• codev doctor warns when Tower is clean but shellpers it spawned earlier still carry markers, and never claims a plain Tower restart is sufficient on its own.

Verified beyond the suite:

• Doctor check against live processes: a real contaminated Tower → warn naming all 7 markers; a dead pid → skipped. On this machine the session check found the exact case it exists for — 71 shellpers running, 5 still carrying markers, Tower itself clean, which the daemon-only version called ok.
• End to end: a Tower started from a shell carrying 7 markers logged Scrubbed inherited Claude Code session markers: … and came up with a clean environment. That run is the incident described below — it is reported there rather than claimed here as a clean result. Field verification will be redone after merge via local-install on main.

Incident during verification

While verifying this fix I took down every terminal on the development machine. Recording it here because it is the kind of failure this PR's own subject matter — processes quietly attaching to state they should not touch — is about.

I started a test Tower on port 14733 to confirm the daemon scrub end to end, and exported AGENT_FARM_DIR to isolate it. That is not the override. The real one is CODEV_AGENT_FARM_DIR (packages/core/src/constants.ts:18, added by #1515). So my test Tower opened the production ~/.agent-farm/global.db and appended to the production tower.log.

Its startup reconcile then found the 56 live terminal rows and connected to every production shellper socket. A shellper holds one client, so the real Tower on 4100 lost all of them; the two Towers fought over reconnects, and the reconcile's stale-row path deleted 53 of the 56 rows. When I killed the test Tower those sessions were orphaned: 60 unregistered shellpers, and every architect terminal across 12 workspaces gone from the dashboard — including the architect's own. The architect restored the rows by hand from the checkpointed DB file and restarted Tower.

The log corroborates it: 56 reconcile-adopt lines at 18:26:59.4xx, then 54 Session … removed but shellper pid=… is alive; preserving socket lines by 18:27:02.5xx.

My gate message described this as having "briefly contended with the live Tower for the cloud tunnel. It recovered." That was wrong — I reported the tunnel flapping I had noticed and not the session loss I had not looked for, which made a fleet-wide outage read as a transient blip.

#1629 is filed for the systemic defects, and they are the real lesson: a second Tower must not be able to open a live global.db and adopt rows owned by a running Tower (owner lock, or refuse to adopt), and an isolation env var whose misspelling silently means "use production" is a trap rather than a safeguard. My mistake was the trigger; neither of those should be reachable by one wrong variable name.

No Tower has been started from this lane since. Field verification of the daemon scrub is deferred to local-install on main after merge.

Known follow-ups (filed, not in this PR)

• tower: afx architect spawns claude without sanitizing inherited CLAUDE_CODE_* env #1627 — afx architect spawns claude unsanitized. Pre-existing and outside Tower (it never stripped CLAUDECODE either), so an architect started from inside a Claude session still nests.
• codev doctor: Tower env check misses custom ports and costs ~2 ps spawns per shellper #1628 — codev doctor inspects only DEFAULT_TOWER_PORT, and the session scan costs ~2 ps spawns per shellper (~142 on a 71-shellper machine); both fixable, neither worth widening this PR for.

One limit worth stating rather than filing: codev doctor classifies with the same list the sanitizer uses, so it cannot backstop a marker Claude Code adds that this list has not caught up with. Claude Code's own "transcript saving is off" banner remains the only signal for that case — it is how this issue was found.

🤖 Generated with Claude Code

https://claude.ai/code/session_01ApsmgthG7VWgMM2JaizWD6