From 2d5696163656ee3d2019b92ccd628fca13135347 Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Fri, 12 Jun 2026 11:07:05 -0700 Subject: [PATCH] feat: hermetic child-env builder for E2E runners Allowlist scrub (basics/network/named-auth kept; CONDUCTOR_*, CLAUDE_*, GSTACK_*, MCP_*, GBRAIN_*, operator credentials dropped), per-runner extraAllow, overrides merge last, EVALS_HERMETIC=0 byte-identical escape hatch read at call time (ESM-hoist safe). Sync memoized singleton temp dirs (/.claude keeps the extractPlanFilePath contract), seeded .claude.json for non-interactive first run, pid-aware GC of crashed runs. 19 free unit tests. Co-Authored-By: Claude Fable 5 --- test/helpers/hermetic-env.test.ts | 254 ++++++++++++++++++++++++++++++ test/helpers/hermetic-env.ts | 253 +++++++++++++++++++++++++++++ 2 files changed, 507 insertions(+) create mode 100644 test/helpers/hermetic-env.test.ts create mode 100644 test/helpers/hermetic-env.ts diff --git a/test/helpers/hermetic-env.test.ts b/test/helpers/hermetic-env.test.ts new file mode 100644 index 000000000..27075a7b8 --- /dev/null +++ b/test/helpers/hermetic-env.test.ts @@ -0,0 +1,254 @@ +/** + * Unit tests for the hermetic child-env builder. Free tier — no API calls. + * + * Pins three contracts: + * 1. Allowlist semantics: contamination vars dropped, basics/auth/network + * kept, overrides merge last, EVALS_HERMETIC=0 is byte-identical legacy. + * 2. Seed-config shape: 20-char key suffix, trusted dirs, undefined-key safe. + * 3. Dir lifecycle: /.claude suffix (extractPlanFilePath contract — + * claude-pty-runner.ts:191), sync singleton reuse, pid-aware GC. + */ + +import { describe, test, expect, afterAll } from 'bun:test'; +import * as fs from 'fs'; +import * as path from 'path'; +import * as os from 'os'; +import { + buildHermeticEnv, + buildSeedConfig, + isHermeticEnabled, + getHermeticDirs, + gcStaleHermeticDirs, + hermeticChildEnv, +} from './hermetic-env'; + +const CONTAMINATED: NodeJS.ProcessEnv = { + PATH: '/usr/bin', HOME: '/Users/op', TMPDIR: '/tmp', TERM: 'xterm', + ANTHROPIC_API_KEY: 'sk-ant-0123456789abcdefghijklmn', + ANTHROPIC_BASE_URL: 'https://proxy.example/api', + ANTHROPIC_MODEL: 'sneaky-model-override', + EVALS_MODEL: 'claude-sonnet-4-6', + GITHUB_ACTIONS: 'true', + HTTPS_PROXY: 'http://corp:3128', + NODE_EXTRA_CA_CERTS: '/etc/corp.pem', + CONDUCTOR_WORKSPACE_PATH: '/Users/op/conductor/ws', + CONDUCTOR_SESSION: '1', + CLAUDECODE: '1', + CLAUDE_CODE_ENTRYPOINT: 'cli', + CLAUDE_CONFIG_DIR: '/Users/op/.claude', + GSTACK_HOME: '/Users/op/.gstack', + GSTACK_HEADLESS_DEFAULT: 'x', + MCP_TIMEOUT: '5000', + GBRAIN_ENDPOINT: 'http://localhost:1234', + OPENAI_API_KEY: 'sk-openai-secret', + VOYAGE_API_KEY: 'vg-secret', + GH_TOKEN: 'gho_secret', + SSH_AUTH_SOCK: '/tmp/ssh.sock', + GIT_AUTHOR_NAME: 'Op', +}; + +const HERMETIC_VARS = { CLAUDE_CONFIG_DIR: '/x/.claude', GSTACK_HOME: '/x/gstack-home' }; + +describe('buildHermeticEnv allowlist', () => { + const env = buildHermeticEnv(CONTAMINATED, HERMETIC_VARS); + + test('keeps process basics, network, CI, and eval knobs', () => { + expect(env.PATH).toBe('/usr/bin'); + expect(env.HOME).toBe('/Users/op'); + expect(env.EVALS_MODEL).toBe('claude-sonnet-4-6'); + expect(env.GITHUB_ACTIONS).toBe('true'); + expect(env.HTTPS_PROXY).toBe('http://corp:3128'); + expect(env.NODE_EXTRA_CA_CERTS).toBe('/etc/corp.pem'); + }); + + test('keeps named auth vars but not the broad ANTHROPIC_ prefix', () => { + expect(env.ANTHROPIC_API_KEY).toBe(CONTAMINATED.ANTHROPIC_API_KEY); + expect(env.ANTHROPIC_BASE_URL).toBe(CONTAMINATED.ANTHROPIC_BASE_URL); + expect(env.ANTHROPIC_MODEL).toBeUndefined(); // behavior knob, not auth + }); + + test('drops session-context and operator-credential vars', () => { + for (const k of [ + 'CONDUCTOR_WORKSPACE_PATH', 'CONDUCTOR_SESSION', 'CLAUDECODE', + 'CLAUDE_CODE_ENTRYPOINT', 'GSTACK_HEADLESS_DEFAULT', 'MCP_TIMEOUT', + 'GBRAIN_ENDPOINT', 'OPENAI_API_KEY', 'VOYAGE_API_KEY', 'GH_TOKEN', + 'SSH_AUTH_SOCK', 'GIT_AUTHOR_NAME', + ]) { + expect(env[k]).toBeUndefined(); + } + }); + + test('redirects CLAUDE_CONFIG_DIR and GSTACK_HOME to hermetic values', () => { + expect(env.CLAUDE_CONFIG_DIR).toBe('/x/.claude'); + expect(env.GSTACK_HOME).toBe('/x/gstack-home'); + }); + + test('overrides merge last — per-test re-contamination is deliberate', () => { + const e = buildHermeticEnv(CONTAMINATED, HERMETIC_VARS, { + CONDUCTOR_WORKSPACE_PATH: '/tmp/test-ws', + GSTACK_HOME: '/tmp/test-home', + GSTACK_HEADLESS: '', + }); + expect(e.CONDUCTOR_WORKSPACE_PATH).toBe('/tmp/test-ws'); + expect(e.GSTACK_HOME).toBe('/tmp/test-home'); + expect(e.GSTACK_HEADLESS).toBe(''); + }); + + test('promotes GSTACK_ANTHROPIC_API_KEY when canonical absent (shared shim fn)', () => { + const base = { ...CONTAMINATED } as NodeJS.ProcessEnv; + delete base.ANTHROPIC_API_KEY; + base.GSTACK_ANTHROPIC_API_KEY = 'sk-ant-promoted-9876543210'; + const e = buildHermeticEnv(base, HERMETIC_VARS); + expect(e.ANTHROPIC_API_KEY).toBe('sk-ant-promoted-9876543210'); + expect(e.GSTACK_ANTHROPIC_API_KEY).toBeUndefined(); // GSTACK_* still dropped + }); + + test('extraAllow re-admits exact names and prefixes per runner', () => { + const e = buildHermeticEnv(CONTAMINATED, HERMETIC_VARS, undefined, { + extraAllow: ['OPENAI_API_KEY', 'GIT_*'], + }); + expect(e.OPENAI_API_KEY).toBe('sk-openai-secret'); + expect(e.GIT_AUTHOR_NAME).toBe('Op'); + expect(e.GH_TOKEN).toBeUndefined(); // not in extraAllow + }); + + test('TERM falls back when base omits it', () => { + const base = { ...CONTAMINATED } as NodeJS.ProcessEnv; + delete base.TERM; + expect(buildHermeticEnv(base, HERMETIC_VARS).TERM).toBe('xterm-256color'); + }); +}); + +describe('EVALS_HERMETIC=0 escape hatch', () => { + test('returns byte-identical legacy env, overrides still last', () => { + const base = { ...CONTAMINATED, EVALS_HERMETIC: '0' } as NodeJS.ProcessEnv; + const e = buildHermeticEnv(base, HERMETIC_VARS, { GSTACK_HEADLESS: '1' }); + // Legacy spread: every base var survives, hermeticVars NOT applied. + expect(e.CONDUCTOR_WORKSPACE_PATH).toBe(CONTAMINATED.CONDUCTOR_WORKSPACE_PATH); + expect(e.CLAUDE_CONFIG_DIR).toBe('/Users/op/.claude'); + expect(e.GSTACK_HOME).toBe('/Users/op/.gstack'); + expect(e.GSTACK_HEADLESS).toBe('1'); + expect(e).toEqual({ ...(base as Record), GSTACK_HEADLESS: '1' }); + }); + + test('isHermeticEnabled reads at call time (ESM-hoist safety)', () => { + const prev = process.env.EVALS_HERMETIC; + try { + process.env.EVALS_HERMETIC = '0'; + expect(isHermeticEnabled()).toBe(false); + process.env.EVALS_HERMETIC = '1'; + expect(isHermeticEnabled()).toBe(true); + delete process.env.EVALS_HERMETIC; + expect(isHermeticEnabled()).toBe(true); + } finally { + if (prev === undefined) delete process.env.EVALS_HERMETIC; + else process.env.EVALS_HERMETIC = prev; + } + }); +}); + +describe('buildSeedConfig', () => { + test('stores only the 20-char key suffix and trusts the given dirs', () => { + const seed = buildSeedConfig({ + apiKey: 'sk-ant-0123456789abcdefghijklmn', + trustedDirs: ['/repo/root'], + }) as any; + expect(seed.hasCompletedOnboarding).toBe(true); + const approved = seed.customApiKeyResponses.approved; + expect(approved).toHaveLength(1); + expect(approved[0]).toHaveLength(20); + expect('sk-ant-0123456789abcdefghijklmn'.endsWith(approved[0])).toBe(true); + expect(seed.projects['/repo/root'].hasTrustDialogAccepted).toBe(true); + expect(seed.projects['/repo/root'].hasCompletedProjectOnboarding).toBe(true); + }); + + test('apiKey undefined → omits customApiKeyResponses, does not throw', () => { + const seed = buildSeedConfig({ apiKey: undefined, trustedDirs: [] }) as any; + expect(seed.customApiKeyResponses).toBeUndefined(); + expect(seed.hasCompletedOnboarding).toBe(true); + }); + + test('no full key material anywhere in the seed', () => { + const key = 'sk-ant-0123456789abcdefghijklmn'; + const json = JSON.stringify(buildSeedConfig({ apiKey: key, trustedDirs: [] })); + expect(json.includes(key)).toBe(false); + }); +}); + +describe('getHermeticDirs lifecycle', () => { + test('configDir ends in /.claude — extractPlanFilePath contract', () => { + // claude-pty-runner.ts:191 anchors plan paths on `.claude/plans/` under + // /var|/tmp prefixes; the dir-name suffix is what keeps PTY plan-mode + // tests extracting hermetic plan files with zero extractor changes. + const dirs = getHermeticDirs(); + expect(dirs.configDir.endsWith(`${path.sep}.claude`)).toBe(true); + expect(dirs.configDir.startsWith(os.tmpdir())).toBe(true); + }); + + test('sync singleton: repeat calls return the same dirs', () => { + expect(getHermeticDirs()).toBe(getHermeticDirs()); + }); + + test('seeds .claude.json in the config dir', () => { + const dirs = getHermeticDirs(); + const seed = JSON.parse(fs.readFileSync(path.join(dirs.configDir, '.claude.json'), 'utf-8')); + expect(seed.hasCompletedOnboarding).toBe(true); + const root = path.resolve(__dirname, '..', '..'); + expect(seed.projects[root].hasTrustDialogAccepted).toBe(true); + }); +}); + +describe('gcStaleHermeticDirs', () => { + test('removes dead-pid dirs, keeps live-pid and foreign dirs', () => { + const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'hermetic-gc-test-')); + // Find a pid that is definitely dead: spawn-and-reap is overkill; use a + // huge pid beyond pid_max on macOS/Linux defaults. + const deadPid = 99999999; + const dead = path.join(tmp, `gstack-hermetic-${deadPid}-abc`); + const live = path.join(tmp, `gstack-hermetic-${process.pid}-abc`); + const foreign = path.join(tmp, 'unrelated-dir'); + const malformed = path.join(tmp, 'gstack-hermetic-notapid-abc'); + for (const d of [dead, live, foreign, malformed]) fs.mkdirSync(d); + + gcStaleHermeticDirs(tmp); + + expect(fs.existsSync(dead)).toBe(false); + expect(fs.existsSync(live)).toBe(true); + expect(fs.existsSync(foreign)).toBe(true); + expect(fs.existsSync(malformed)).toBe(true); // never guess on malformed names + fs.rmSync(tmp, { recursive: true, force: true }); + }); +}); + +describe('hermeticChildEnv composition', () => { + test('hermetic by default: redirects config dirs, drops contamination', () => { + // process.env in a real test run may carry CONDUCTOR_*/CLAUDECODE — the + // composition must scrub them and point at the singleton dirs. + const e = hermeticChildEnv({ GSTACK_HEADLESS: '1' }); + const dirs = getHermeticDirs(); + expect(e.CLAUDE_CONFIG_DIR).toBe(dirs.configDir); + expect(e.GSTACK_HOME).toBe(dirs.gstackHome); + expect(e.GSTACK_HEADLESS).toBe('1'); + expect(e.CLAUDECODE).toBeUndefined(); + expect(e.CONDUCTOR_WORKSPACE_PATH).toBeUndefined(); + }); + + test('EVALS_HERMETIC=0: legacy passthrough of live process.env', () => { + const prev = process.env.EVALS_HERMETIC; + try { + process.env.EVALS_HERMETIC = '0'; + const e = hermeticChildEnv({ EXTRA: 'x' }); + expect(e.PATH).toBe(process.env.PATH as string); + expect(e.EXTRA).toBe('x'); + // No hermetic redirection in legacy mode. + expect(e.CLAUDE_CONFIG_DIR).toBe(process.env.CLAUDE_CONFIG_DIR as any); + } finally { + if (prev === undefined) delete process.env.EVALS_HERMETIC; + else process.env.EVALS_HERMETIC = prev; + } + }); +}); + +afterAll(() => { + // The singleton's own exit hook handles runRoot; nothing else to clean. +}); diff --git a/test/helpers/hermetic-env.ts b/test/helpers/hermetic-env.ts new file mode 100644 index 000000000..dbaa49b51 --- /dev/null +++ b/test/helpers/hermetic-env.ts @@ -0,0 +1,253 @@ +/** + * Hermetic child environment for E2E test runners. + * + * Local E2E runs spawn `claude` (and codex/gemini/SDK) children that, until + * this module, inherited the operator's full session context: ~/.claude + * (user CLAUDE.md, .claude.json MCP servers incl. gbrain + Conductor, + * skills), ~/.gstack decision logs, and CONDUCTOR_-/CLAUDECODE-style env vars. + * CI was hermetic only by accident (fresh Docker /home/runner). This module + * makes local children see a CI-equivalent clean room by default. + * + * operator shell (contaminated) hermetic child env + * ┌─────────────────────────────┐ buildHermeticEnv() + * │ PATH, HOME, TMPDIR, ... │── allowlist ─────────► kept + * │ HTTP(S)_PROXY, SSL_CERT_* │── allowlist ─────────► kept (network) + * │ ANTHROPIC_API_KEY/BASE_URL/ │── named list ────────► kept (auth) + * │ AUTH_TOKEN │ + * │ GSTACK_ANTHROPIC_API_KEY │── promotedEnv() ─────► ANTHROPIC_API_KEY + * │ CONDUCTOR_*, CLAUDECODE, │ + * │ CLAUDE_*, GSTACK_*, MCP_*, │── dropped ───────────► ∅ + * │ GBRAIN_*, GH_TOKEN, ... │ + * └─────────────────────────────┘ + * + per-runner extraAllow (codex: OpenAI vars; gemini: Google vars) + * + CLAUDE_CONFIG_DIR=/.claude GSTACK_HOME=/gstack-home + * + per-test overrides spread LAST + * + * Escape hatch: EVALS_HERMETIC=0 restores the legacy contaminated env + * byte-identically (runners must also gate --strict-mcp-config on + * isHermeticEnabled() so the escape hatch restores args too). + * + * isHermeticEnabled() is evaluated at CALL time, never at module load — + * ESM hoists imports above any in-file `process.env.EVALS_HERMETIC = '0'` + * assignment, so a module-load-time read would silently ignore test pins. + */ + +import * as fs from 'fs'; +import * as path from 'path'; +import * as os from 'os'; +import { promotedEnv } from '../../lib/conductor-env-shim'; +import { isProcessAlive } from '../../browse/src/error-handling'; + +/** Exact env names a hermetic child keeps. Everything not listed (or matched + * by a prefix rule below) is dropped. */ +const ALLOW_EXACT = new Set([ + // Process basics + 'PATH', 'HOME', 'TMPDIR', 'TERM', 'COLORTERM', 'LANG', 'LC_ALL', 'SHELL', + 'USER', 'LOGNAME', 'TZ', 'NODE_ENV', 'CI', + // Browser/runtime caches the child legitimately shares with the operator + 'PLAYWRIGHT_BROWSERS_PATH', + // Network reachability — without these, children on proxied networks can't + // reach the Anthropic API at all + 'HTTP_PROXY', 'HTTPS_PROXY', 'NO_PROXY', + 'http_proxy', 'https_proxy', 'no_proxy', + 'SSL_CERT_FILE', 'SSL_CERT_DIR', 'NODE_EXTRA_CA_CERTS', + // Auth — named, NOT the broad ANTHROPIC_* prefix: a prefix rule would + // smuggle model/beta/debug knobs that change eval behavior + 'ANTHROPIC_API_KEY', // the auth credential evals require + 'ANTHROPIC_BASE_URL', // API endpoint override (corp proxies) + 'ANTHROPIC_AUTH_TOKEN', // bearer-token auth variant +]); + +/** Prefix rules: eval-harness knobs + CI metadata. Deliberately NOT here: + * CONDUCTOR_* / CLAUDE_* (incl. CLAUDECODE, CLAUDE_CODE_ENTRYPOINT) / + * GSTACK_* / MCP_* / GBRAIN_* — session-context contamination; and operator + * credentials (GH_TOKEN, SSH_AUTH_SOCK, GIT_*, OPENAI_API_KEY, + * VOYAGE_API_KEY) — CI doesn't have them and eval children have no business + * using them. A test that legitimately needs one opts in via its own env + * override; a provider runner (codex/gemini) re-admits its auth vars via + * opts.extraAllow. */ +const ALLOW_PREFIXES = ['EVALS_', 'GITHUB_']; + +export interface HermeticEnvOpts { + /** Per-runner additional allowed names (exact match) or prefixes (entries + * ending in '*'). Example: codex runner passes ['OPENAI_API_KEY', 'CODEX_*']. */ + extraAllow?: string[]; +} + +/** EVALS_HERMETIC !== '0'. Read at call time (see module doc — ESM hoist). */ +export function isHermeticEnabled(env: NodeJS.ProcessEnv = process.env): boolean { + return env.EVALS_HERMETIC !== '0'; +} + +/** + * Pure allowlist scrub. No I/O. Overrides spread LAST so per-test env + * (GSTACK_HOME, CONDUCTOR_WORKSPACE_PATH, GSTACK_HEADLESS opt-out) always + * wins over the scrub — that is the documented re-contamination escape and + * the wiring tripwire forbids passing raw process.env through it. + */ +export function buildHermeticEnv( + base: NodeJS.ProcessEnv, + hermeticVars: Record, + overrides?: Record, + opts?: HermeticEnvOpts, +): Record { + if (!isHermeticEnabled(base)) { + // Escape hatch: byte-identical to the legacy spread. + const legacy: Record = {}; + for (const [k, v] of Object.entries(base)) if (v !== undefined) legacy[k] = v; + for (const [k, v] of Object.entries(overrides ?? {})) if (v !== undefined) legacy[k] = v; + return legacy; + } + + const promoted = promotedEnv(base); + const extraExact = new Set(); + const extraPrefixes: string[] = []; + for (const entry of opts?.extraAllow ?? []) { + if (entry.endsWith('*')) extraPrefixes.push(entry.slice(0, -1)); + else extraExact.add(entry); + } + + const out: Record = {}; + for (const [k, v] of Object.entries(promoted)) { + if (v === undefined) continue; + const allowed = + ALLOW_EXACT.has(k) || + extraExact.has(k) || + ALLOW_PREFIXES.some((p) => k.startsWith(p)) || + extraPrefixes.some((p) => k.startsWith(p)); + if (allowed) out[k] = v; + } + if (!out.TERM) out.TERM = 'xterm-256color'; + Object.assign(out, hermeticVars); + for (const [k, v] of Object.entries(overrides ?? {})) if (v !== undefined) out[k] = v; + return out; +} + +export interface SeedConfigOpts { + /** When undefined (operator has no key exported), customApiKeyResponses is + * omitted — the child fails auth exactly as it would today, no throw here. */ + apiKey: string | undefined; + trustedDirs: string[]; +} + +/** + * Minimal $CLAUDE_CONFIG_DIR/.claude.json that gets a fresh-config child past + * first-run prompts non-interactively. Every key here was empirically + * verified against a real ~/.claude.json (2026-06-12, claude 2.1.175): + * - hasCompletedOnboarding: suppresses the onboarding flow + * - customApiKeyResponses.approved: suppresses the "use this API key?" + * prompt; entries are the key's LAST 20 CHARS + * - projects[dir].hasTrustDialogAccepted: pre-trusts repo-cwd PTY sessions + * (print mode skips the dialog; PTY plan-mode tests don't) + * bypassPermissionsModeAccepted was considered and dropped: absent from a + * real config even though --dangerously-skip-permissions is in daily use. + */ +export function buildSeedConfig(opts: SeedConfigOpts): Record { + const seed: Record = { + hasCompletedOnboarding: true, + projects: Object.fromEntries( + opts.trustedDirs.map((dir) => [ + dir, + { hasTrustDialogAccepted: true, hasCompletedProjectOnboarding: true }, + ]), + ), + }; + if (opts.apiKey) { + seed.customApiKeyResponses = { approved: [opts.apiKey.slice(-20)] }; + } + return seed; +} + +export interface HermeticDirs { + /** Ends in `/.claude` — load-bearing: extractPlanFilePath in + * claude-pty-runner.ts:191 anchors plan-file paths on `.claude/plans/` + * under a /var|/tmp prefix. Renaming this segment breaks PTY plan tests. */ + configDir: string; + gstackHome: string; + runRoot: string; +} + +const DIR_PREFIX = 'gstack-hermetic-'; + +let cachedDirs: HermeticDirs | null = null; + +/** Repo root for the trusted-dir seed: test files live in /test/helpers. */ +function repoRoot(): string { + return path.resolve(__dirname, '..', '..'); +} + +/** + * Sync memoized per-process singleton — intentionally NO async gap between + * the cache check and create+seed, so concurrent first calls under + * `bun test --concurrent` cannot double-create or observe a half-seeded dir. + * Shared across all tests in the process: that matches CI's within-job + * shared /home/runner (operator isolation, not per-test isolation). + */ +export function getHermeticDirs(): HermeticDirs { + if (cachedDirs) return cachedDirs; + + gcStaleHermeticDirs(); + + // Embed our pid so the GC of future processes can check liveness. + const runRoot = fs.mkdtempSync(path.join(os.tmpdir(), `${DIR_PREFIX}${process.pid}-`)); + const configDir = path.join(runRoot, '.claude'); + const gstackHome = path.join(runRoot, 'gstack-home'); + + // A half-seeded config dir means children hang on first-run prompts until + // the test timeout — far worse than failing loudly here. No try/catch. + fs.mkdirSync(configDir, { recursive: true }); + fs.mkdirSync(gstackHome, { recursive: true }); + const seed = buildSeedConfig({ + apiKey: process.env.ANTHROPIC_API_KEY ?? process.env.GSTACK_ANTHROPIC_API_KEY, + trustedDirs: [repoRoot()], + }); + fs.writeFileSync(path.join(configDir, '.claude.json'), JSON.stringify(seed, null, 2)); + + process.on('exit', () => { + // Exit handlers cannot await: sync best-effort removal only. Anything + // left behind is reclaimed by the next process's pid-aware GC. + try { fs.rmSync(runRoot, { recursive: true, force: true }); } catch { /* GC reclaims */ } + }); + + cachedDirs = { configDir, gstackHome, runRoot }; + return cachedDirs; +} + +/** + * Reclaim leftovers from crashed runs. Pid-aware, not age-based: a pure + * age cutoff would delete a live >24h eval run's config out from under it. + * Exported for tests. + */ +export function gcStaleHermeticDirs(tmpDir: string = os.tmpdir()): void { + let entries: string[]; + try { entries = fs.readdirSync(tmpDir); } catch { return; } + for (const name of entries) { + if (!name.startsWith(DIR_PREFIX)) continue; + const pidStr = name.slice(DIR_PREFIX.length).split('-')[0]; + const pid = Number(pidStr); + if (!Number.isInteger(pid) || pid <= 0) continue; + if (pid === process.pid || isProcessAlive(pid)) continue; + try { fs.rmSync(path.join(tmpDir, name), { recursive: true, force: true }); } catch { /* best-effort */ } + } +} + +/** + * The composition runners use: scrub process.env, point the child at the + * singleton hermetic dirs, apply per-test overrides last. Returns the legacy + * env untouched when EVALS_HERMETIC=0 (and skips dir creation entirely). + */ +export function hermeticChildEnv( + overrides?: Record, + opts?: HermeticEnvOpts, +): Record { + if (!isHermeticEnabled()) { + return buildHermeticEnv(process.env, {}, overrides, opts); + } + const dirs = getHermeticDirs(); + return buildHermeticEnv( + process.env, + { CLAUDE_CONFIG_DIR: dirs.configDir, GSTACK_HOME: dirs.gstackHome }, + overrides, + opts, + ); +}