refactor: extend .env strip to all tmux spawns and address review

- extract leaked-key stripping into shared adapters/project-env
- strip project keys in terminal.ts tmux/PTY spawns (close born-clean gap)
- use Bun.env; also strip WEBMUX_PROJECT_ENV_KEYS marker itself
- gate global-env scrub to once per backend process
- add project-env unit tests and a scrub-in-isolation integration test

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: centdix

backend/src/__tests__/project-env.test.ts

@@ -0,0 +1,42 @@
+import { afterEach, describe, expect, it } from "bun:test";
+import { leakedProjectEnvKeys, stripProjectEnv } from "../adapters/project-env";
+
+const original = process.env.WEBMUX_PROJECT_ENV_KEYS;
+
+afterEach(() => {
+  if (original === undefined) delete process.env.WEBMUX_PROJECT_ENV_KEYS;
+  else process.env.WEBMUX_PROJECT_ENV_KEYS = original;
+});
+
+describe("leakedProjectEnvKeys", () => {
+  it("returns an empty set when no project env keys were loaded", () => {
+    delete process.env.WEBMUX_PROJECT_ENV_KEYS;
+    expect(leakedProjectEnvKeys().size).toBe(0);
+  });
+
+  it("includes the listed keys plus the marker var itself, trimming blanks", () => {
+    process.env.WEBMUX_PROJECT_ENV_KEYS = "SUPABASE_URL, SUPABASE_ANON_KEY ,";
+    expect(leakedProjectEnvKeys()).toEqual(
+      new Set(["WEBMUX_PROJECT_ENV_KEYS", "SUPABASE_URL", "SUPABASE_ANON_KEY"]),
+    );
+  });
+});
+
+describe("stripProjectEnv", () => {
+  it("removes the launch project's keys and the marker, keeping unrelated vars", () => {
+    process.env.WEBMUX_PROJECT_ENV_KEYS = "SUPABASE_URL";
+    const result = stripProjectEnv({
+      SUPABASE_URL: "secret",
+      WEBMUX_PROJECT_ENV_KEYS: "SUPABASE_URL",
+      PATH: "/usr/bin",
+      HOME: "/root",
+      UNSET: undefined,
+    });
+    expect(result).toEqual({ PATH: "/usr/bin", HOME: "/root" });
+  });
+
+  it("returns a full copy of defined vars when there is nothing to strip", () => {
+    delete process.env.WEBMUX_PROJECT_ENV_KEYS;
+    expect(stripProjectEnv({ A: "1", B: "2", C: undefined })).toEqual({ A: "1", B: "2" });
+  });
+});

backend/src/__tests__/tmux-adapter.test.ts

@@ -364,6 +364,62 @@ describe("BunTmuxGateway", () => {
     }
   });
 
+  it("scrubs launch-project .env keys left in the global env by an already-running server", async () => {
+    const testRoot = await mkdtemp(join(tmpdir(), "webmux-tmux-env-scrub-"));
+    const projectRoot = join(testRoot, "repo");
+    const runnerPath = join(testRoot, "scrub.ts");
+    const tmuxModuleUrl = new URL("../adapters/tmux.ts", import.meta.url).href;
+    await mkdir(projectRoot, { recursive: true });
+    await Bun.write(
+      runnerPath,
+      [
+        `import { BunTmuxGateway } from ${JSON.stringify(tmuxModuleUrl)};`,
+        "",
+        "function run(args: string[], env?: Record<string, string>): void {",
+        '  const result = Bun.spawnSync(args, { stdout: "pipe", stderr: "pipe", ...(env ? { env } : {}) });',
+        "  if (result.exitCode !== 0) {",
+        "    const stderr = new TextDecoder().decode(result.stderr).trim();",
+        '    throw new Error(`${args.join(" ")} failed: ${stderr || `exit ${result.exitCode}`}`);',
+        "  }",
+        "}",
+        "",
+        "function globalHasLeaked(): boolean {",
+        '  const result = Bun.spawnSync(["tmux", "show-environment", "-g"], { stdout: "pipe", stderr: "pipe" });',
+        '  return new TextDecoder().decode(result.stdout).split("\\n").some((line) => line.startsWith("LEAKED_PROJECT_SECRET="));',
+        "}",
+        "",
+        "const projectRoot = process.argv[2];",
+        'if (!projectRoot) throw new Error("expected projectRoot");',
+        // Simulate a server started before the stripped-env fix: its global env
+        // captured the leaked key. gateway commands never spawn with it set, so
+        // only the scrub can remove it. destroy-unattached off keeps this
+        // detached session (and thus the server + its global env) alive even when
+        // the tmux config enables destroy-unattached.
+        'run(["tmux", "new-session", "-d", "-s", "preexisting", "-c", projectRoot, ";", "set-option", "-t", "preexisting", "destroy-unattached", "off"], { ...process.env, LEAKED_PROJECT_SECRET: "service-role-key" } as Record<string, string>);',
+        "const before = globalHasLeaked();",
+        "const gateway = new BunTmuxGateway();",
+        "gateway.ensureServer();",
+        'gateway.ensureSession("wm-scrub", projectRoot);',
+        "console.log(JSON.stringify({ before, after: globalHasLeaked() }));",
+      ].join("\n"),
+    );
+
+    try {
+      const output = readWithIsolatedTmux(
+        ["bun", runnerPath, projectRoot],
+        buildEnv({ WEBMUX_PROJECT_ENV_KEYS: "LEAKED_PROJECT_SECRET" }),
+      );
+      const value: unknown = JSON.parse(output);
+      const { before, after } = value as { before?: unknown; after?: unknown };
+      // The pre-existing server really did leak the key into the global env...
+      expect(before).toBe(true);
+      // ...and ensureSession's self-heal scrub removed it.
+      expect(after).toBe(false);
+    } finally {
+      await rm(testRoot, { recursive: true, force: true });
+    }
+  });
+
   it("treats missing windows, sessions, and servers as already closed", async () => {
     const testRoot = await mkdtemp(join(tmpdir(), "webmux-tmux-kill-window-"));
     const projectRoot = join(testRoot, "repo");

backend/src/adapters/project-env.ts

@@ -0,0 +1,31 @@
+/** The launch project's `.env`/`.env.local` keys that webmux's CLI loaded into
+ *  its own process env, passed down to the backend as a comma-separated list in
+ *  WEBMUX_PROJECT_ENV_KEYS. These are application secrets webmux does not need in
+ *  the tmux server: if the tmux *global* environment ever captures them (the
+ *  server inherits webmux's env from whatever process first starts it) they leak
+ *  into every session and pane of every project. WEBMUX_PROJECT_ENV_KEYS itself
+ *  is stripped too — it only holds key *names*, not values, but there is no
+ *  reason to let a webmux-internal marker reach the global env either. */
+export function leakedProjectEnvKeys(): Set<string> {
+  const raw = Bun.env.WEBMUX_PROJECT_ENV_KEYS;
+  if (!raw) return new Set();
+  const keys = new Set<string>(["WEBMUX_PROJECT_ENV_KEYS"]);
+  for (const key of raw.split(",").map((entry) => entry.trim()).filter(Boolean)) {
+    keys.add(key);
+  }
+  return keys;
+}
+
+/** Copy `base` (typically `Bun.env`) with the launch project's `.env` keys
+ *  removed, so a tmux server or client spawned by webmux never carries — nor
+ *  captures into its global environment — another project's secrets. Snapshots
+ *  `base` at call time; the leaked keys are fixed at launch, so a later mutation
+ *  to one of those vars is intentionally not reflected. */
+export function stripProjectEnv(base: Record<string, string | undefined>): Record<string, string> {
+  const keys = leakedProjectEnvKeys();
+  const env: Record<string, string> = {};
+  for (const [key, val] of Object.entries(base)) {
+    if (val !== undefined && !keys.has(key)) env[key] = val;
+  }
+  return env;
+}

backend/src/adapters/terminal.ts

@@ -1,4 +1,5 @@
 import { log } from "../lib/log";
+import { stripProjectEnv } from "./project-env";
 
 interface PtyProcess {
   pid: number;
@@ -77,11 +78,15 @@ const defaultSpawnTmuxProcess: SpawnTmuxProcess = (args, opts = {}) =>
     stdin: opts.stdin ?? "ignore",
     stdout: "ignore",
     stderr: "pipe",
+    // Strip the launch project's `.env` keys: if one of these commands is ever
+    // the first to reach a not-yet-running server it must not birth it with
+    // another project's secrets in the global env (see project-env.ts).
+    env: stripProjectEnv(Bun.env),
   });
 const defaultSleep: Sleep = (ms) => Bun.sleep(ms);
 
 const defaultSpawnSyncCommand: SpawnSyncCommand = (args, opts = {}) => {
-  const result = Bun.spawnSync(args, opts);
+  const result = Bun.spawnSync(args, { ...opts, env: opts.env ?? stripProjectEnv(Bun.env) });
   return {
     exitCode: result.exitCode,
     stdout: result.stdout ?? new Uint8Array(),
@@ -242,7 +247,7 @@ export async function attach(
     initialPane,
   });
 
-  const proc = spawnPtyProcess(buildPtyArgs(cmd), { ...Bun.env, TERM: "xterm-256color" });
+  const proc = spawnPtyProcess(buildPtyArgs(cmd), { ...stripProjectEnv(Bun.env), TERM: "xterm-256color" });
 
   const session: TerminalSession = {
     proc,

backend/src/adapters/tmux.ts

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import { basename, resolve } from "node:path";
 import type { PaneSplit } from "../domain/config";
+import { leakedProjectEnvKeys, stripProjectEnv } from "./project-env";
 
 export interface TmuxWindowSummary {
   sessionName: string;
@@ -41,40 +42,21 @@ export interface TmuxGateway {
   killPane(target: string): void;
 }
 
-/** Keys webmux's launcher loaded from the serve directory's `.env`/`.env.local`
- *  into its own process env (comma-separated in WEBMUX_PROJECT_ENV_KEYS). These
- *  are the launch project's application secrets; webmux does not need them in the
- *  tmux server. When webmux starts the tmux server it inherits webmux's env, and
- *  the server captures that as its *global* environment — which every session and
- *  pane of every project then inherits. Stripping these keys from the env used to
- *  spawn tmux keeps a webmux-created server from ever being born with one
- *  project's secrets visible to all the others. */
-function leakedProjectEnvKeys(): Set<string> {
-  const raw = Bun.env.WEBMUX_PROJECT_ENV_KEYS;
-  if (!raw) return new Set();
-  return new Set(raw.split(",").map((key) => key.trim()).filter(Boolean));
-}
-
 let cachedTmuxSpawnEnv: { value: Record<string, string> | undefined } | null = null;
+let globalEnvScrubbed = false;
 
 /** Environment for spawning tmux control commands, stripped of the launch
- *  project's `.env` keys. Whichever tmux command first starts the server fixes
- *  the global environment for the server's lifetime, so every tmux invocation
- *  must use the stripped env. Returns `undefined` (inherit the process env
- *  unchanged) when there is nothing to strip. */
+ *  project's `.env` keys (see {@link stripProjectEnv}). Whichever tmux command
+ *  first starts the server fixes the global environment for the server's
+ *  lifetime, so every tmux invocation must use the stripped env. Returns
+ *  `undefined` (inherit the process env unchanged) on the common path where no
+ *  project keys were loaded, so tmux spawns don't copy the whole env for
+ *  nothing. */
 function tmuxSpawnEnv(): Record<string, string> | undefined {
   if (cachedTmuxSpawnEnv) return cachedTmuxSpawnEnv.value;
-  const keys = leakedProjectEnvKeys();
-  if (keys.size === 0) {
-    cachedTmuxSpawnEnv = { value: undefined };
-    return undefined;
-  }
-  const env: Record<string, string> = {};
-  for (const [key, val] of Object.entries(process.env)) {
-    if (val !== undefined && !keys.has(key)) env[key] = val;
-  }
-  cachedTmuxSpawnEnv = { value: env };
-  return env;
+  const value = Bun.env.WEBMUX_PROJECT_ENV_KEYS ? stripProjectEnv(Bun.env) : undefined;
+  cachedTmuxSpawnEnv = { value };
+  return value;
 }
 
 function runTmux(args: string[]): { stdout: string; stderr: string; exitCode: number } {
@@ -180,8 +162,14 @@ export class BunTmuxGateway implements TmuxGateway {
    *  environment cleans every pane created afterwards, in existing and new
    *  sessions alike. Runs once the server is known to be up (`exit-empty` means a
    *  server only persists after a session exists). Tolerant: unsetting a key that
-   *  is absent is a no-op. */
+   *  is absent is a no-op.
+   *
+   *  Runs at most once per backend process: once the global env is scrubbed,
+   *  stripped-env spawns keep it clean, so re-scrubbing on every session-ensure /
+   *  reconciliation pass would be pure overhead (a tmux spawn per leaked key). */
   private scrubLeakedGlobalEnv(): void {
+    if (globalEnvScrubbed) return;
+    globalEnvScrubbed = true;
     for (const key of leakedProjectEnvKeys()) {
       runTmux(["set-environment", "-gu", key]);
     }