Merge pull request #74 from TeigenZhang/refactor/envoverrides-tmux-export

refactor: pass envOverrides via tmux export instead of disk write

Author: Ark0N

src/hooks-config.ts

@@ -84,6 +84,42 @@ export function generateHooksConfig(): { hooks: Record<string, unknown[]> } {
   };
 }
 
+/**
+ * Remove a subset of env keys from .claude/settings.local.json.env if present.
+ * Used during the disk→tmux-setenv migration: when the caller is actively setting
+ * a fresh value for a Codeman-managed key, any stale disk entry for THAT KEY is
+ * superseded and should be removed. Keys NOT in `keysToRemove` are left alone
+ * (they may be user-managed). No-op if the file/keys don't exist.
+ */
+export async function stripCaseEnvKeys(casePath: string, keysToRemove: readonly string[]): Promise<void> {
+  if (keysToRemove.length === 0) return;
+
+  const settingsPath = join(casePath, '.claude', 'settings.local.json');
+  if (!existsSync(settingsPath)) return;
+
+  let existing: Record<string, unknown>;
+  try {
+    existing = JSON.parse(await readFile(settingsPath, 'utf-8'));
+  } catch {
+    return; // Malformed — don't rewrite it
+  }
+
+  const env = existing.env as Record<string, string> | undefined;
+  if (!env) return;
+
+  let changed = false;
+  for (const key of keysToRemove) {
+    if (key in env) {
+      delete env[key];
+      changed = true;
+    }
+  }
+  if (!changed) return;
+
+  existing.env = env;
+  await writeFile(settingsPath, JSON.stringify(existing, null, 2) + '\n');
+}
+
 /**
  * Updates env vars in .claude/settings.local.json for the given case path.
  * Merges with existing env field; removes vars set to empty string.

src/mux-interface.ts

@@ -63,6 +63,8 @@ export interface CreateSessionOptions {
   openCodeConfig?: OpenCodeConfig;
   /** When restoring after reboot, resume a previous Claude conversation by its session ID */
   resumeSessionId?: string;
+  /** Extra env vars exported before launching the CLI (e.g., CLAUDE_CODE_EFFORT_LEVEL). Ephemeral — not written to disk. */
+  envOverrides?: Record<string, string>;
 }
 
 /** Options for respawning a dead pane. */
@@ -77,6 +79,8 @@ export interface RespawnPaneOptions {
   openCodeConfig?: OpenCodeConfig;
   /** Resume a previous Claude conversation when respawning */
   resumeSessionId?: string;
+  /** Extra env vars exported before launching the CLI (preserved across respawns). */
+  envOverrides?: Record<string, string>;
 }
 
 /**

src/session-manager.ts

@@ -152,7 +152,7 @@ export class SessionManager extends EventEmitter {
       await session.start();
 
       this.sessions.set(session.id, session);
-      this.store.setSession(session.id, session.toState());
+      this.updateSessionState(session);
 
       this.emit('sessionStarted', session);
       return session;
@@ -247,7 +247,15 @@ export class SessionManager extends EventEmitter {
   }
 
   private updateSessionState(session: Session): void {
-    this.store.setSession(session.id, session.toState());
+    // envOverrides is intentionally NOT on SessionState (API safety). For disk
+    // persistence we augment the stored object with __envOverrides so reboot
+    // recovery can restore them without leaking through any API serializer.
+    // The key uses the reserved `__` prefix so it is visibly "internal" to any
+    // future reader of state.json.
+    const state = session.toState();
+    const envOverrides = session.getEnvOverridesForPersist();
+    const toStore = envOverrides ? { ...state, __envOverrides: envOverrides } : state;
+    this.store.setSession(session.id, toStore as SessionState);
   }
 
   /** Gets all sessions from persistent storage (including stopped). */

src/session.ts

@@ -273,6 +273,10 @@ export class Session extends EventEmitter {
   private _openCodeConfig: OpenCodeConfig | undefined;
   private _resumeSessionId: string | undefined;
 
+  // Ephemeral env overrides (e.g., CLAUDE_CODE_EFFORT_LEVEL). Exported by tmux at spawn,
+  // preserved across respawns via persisted state. Not written to .claude/settings.local.json.
+  private _envOverrides: Record<string, string> | undefined;
+
   // Session color for visual differentiation
   private _color: import('./types.js').SessionColor = 'default';
 
@@ -332,6 +336,8 @@ export class Session extends EventEmitter {
       openCodeConfig?: OpenCodeConfig;
       /** Resume a previous Claude conversation (used after server reboot) */
       resumeSessionId?: string;
+      /** Extra env vars exported to the CLI at spawn time (no disk persistence) */
+      envOverrides?: Record<string, string>;
     }
   ) {
     super();
@@ -379,6 +385,11 @@ export class Session extends EventEmitter {
       this._openCodeConfig = config.openCodeConfig;
     }
 
+    // Apply env overrides (exported at spawn, not persisted to disk)
+    if (config.envOverrides && Object.keys(config.envOverrides).length > 0) {
+      this._envOverrides = { ...config.envOverrides };
+    }
+
     // Initialize task tracker and forward events (store handlers for cleanup)
     this._taskTracker = new TaskTracker();
     this._taskTrackerHandlers = {
@@ -789,9 +800,29 @@ export class Session extends EventEmitter {
       cliLatestVersion: this._cliLatestVersion || undefined,
       openCodeConfig: this._openCodeConfig,
       resumeSessionId: this._resumeSessionId,
+      // envOverrides intentionally NOT on the public SessionState type — they must not
+      // leak into SSE / GET /api/sessions broadcasts (schema allows OPENCODE_*, which
+      // can carry secrets). For disk persistence, session-manager calls
+      // getEnvOverridesForPersist() and writes alongside state.
     };
   }
 
+  /**
+   * Returns a subset of env overrides safe for disk persistence (state.json).
+   * Only non-sensitive `CLAUDE_CODE_*` keys are included. `OPENCODE_*` keys are
+   * filtered out because the schema permits them and they can carry secrets
+   * (e.g., OPENCODE_API_KEY); secrets must not land in `~/.codeman/state.json`.
+   * Must NOT be included in any API-bound serializer — see toState() comment.
+   */
+  getEnvOverridesForPersist(): Record<string, string> | undefined {
+    if (!this._envOverrides) return undefined;
+    const safe: Record<string, string> = {};
+    for (const [key, value] of Object.entries(this._envOverrides)) {
+      if (key.startsWith('CLAUDE_CODE_')) safe[key] = value;
+    }
+    return Object.keys(safe).length > 0 ? safe : undefined;
+  }
+
   toDetailedState() {
     return {
       ...this.toLightDetailedState(),
@@ -957,6 +988,7 @@ export class Session extends EventEmitter {
             allowedTools: this._allowedTools,
             openCodeConfig: this._openCodeConfig,
             resumeSessionId: this._resumeSessionId,
+            envOverrides: this._envOverrides,
           },
           createSessionOptions: {
             sessionId: this.id,
@@ -969,6 +1001,7 @@ export class Session extends EventEmitter {
             allowedTools: this._allowedTools,
             openCodeConfig: this._openCodeConfig,
             resumeSessionId: this._resumeSessionId,
+            envOverrides: this._envOverrides,
           },
           spawnErrLabel: 'mux attachment',
         });
@@ -1044,7 +1077,8 @@ export class Session extends EventEmitter {
           cols: 120,
           rows: 40,
           cwd: this.workingDir,
-          env: buildClaudeEnv(this.id),
+          // Merge envOverrides after buildClaudeEnv so user settings shadow defaults.
+          env: { ...buildClaudeEnv(this.id), ...(this._envOverrides ?? {}) },
         });
       } catch (spawnErr) {
         console.error('[Session] Failed to spawn Claude PTY:', spawnErr);
@@ -1289,13 +1323,15 @@ export class Session extends EventEmitter {
             workingDir: this.workingDir,
             mode: 'shell',
             niceConfig: this._niceConfig,
+            envOverrides: this._envOverrides,
           },
           createSessionOptions: {
             sessionId: this.id,
             workingDir: this.workingDir,
             mode: 'shell',
             name: this._name,
             niceConfig: this._niceConfig,
+            envOverrides: this._envOverrides,
           },
           spawnErrLabel: 'shell mux attachment',
         });
@@ -1431,7 +1467,8 @@ export class Session extends EventEmitter {
             cols: 120,
             rows: 40,
             cwd: this.workingDir,
-            env: buildClaudeEnv(this.id),
+            // Merge envOverrides after buildClaudeEnv so user settings shadow defaults.
+            env: { ...buildClaudeEnv(this.id), ...(this._envOverrides ?? {}) },
           });
         } catch (spawnErr) {
           console.error('[Session] Failed to spawn Claude PTY for runPrompt:', spawnErr);

src/tmux-manager.ts

@@ -399,6 +399,10 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
   /**
    * Build the array of environment export commands shared by createSession() and respawnPane().
    * Includes locale, mux markers, session identity, and API URL.
+   *
+   * User-supplied envOverrides are NOT inlined here — they go through applyEnvOverrides()
+   * via `tmux setenv` so secret values (e.g., OPENCODE_API_KEY) never appear in the bash
+   * command line (visible in `ps`). This also sidesteps shell-metachar injection via keys.
    */
   private buildEnvExports(sessionId: string, muxName: string, mode: SessionMode): string[] {
     const exports = [
@@ -415,6 +419,35 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
     return exports;
   }
 
+  /**
+   * Apply user-supplied env overrides to a tmux session via `tmux setenv`.
+   * Values stay off the bash command line (not visible in `ps`), and are inherited
+   * by new panes — including `respawn-pane`. Persists at tmux-session level, so
+   * Codeman server restarts don't lose the setting as long as the tmux session lives.
+   *
+   * Key validation is strict (`/^[A-Z_][A-Z0-9_]*$/`) as defense-in-depth against
+   * shell-metachar injection even if upstream schema check is bypassed.
+   */
+  private applyEnvOverrides(muxName: string, envOverrides?: Record<string, string>): void {
+    if (!envOverrides) return;
+    const VALID_KEY = /^[A-Z_][A-Z0-9_]*$/;
+    for (const [key, value] of Object.entries(envOverrides)) {
+      if (!value) continue; // Skip empty — nothing to set
+      if (!VALID_KEY.test(key)) {
+        console.warn(`[TmuxManager] Skipping invalid env override key: ${JSON.stringify(key)}`);
+        continue;
+      }
+      try {
+        execSync(`tmux setenv -t ${shellescape(muxName)} ${key} ${shellescape(value)}`, {
+          timeout: EXEC_TIMEOUT_MS,
+          stdio: ['pipe', 'pipe', 'pipe'],
+        });
+      } catch (err) {
+        console.warn(`[TmuxManager] Failed to set env override ${key}:`, err);
+      }
+    }
+  }
+
   /**
    * Resolve the CLI binary directory and return the PATH export prefix string.
    * Returns '' if no override is needed (shell mode) or the binary dir is not found.
@@ -458,6 +491,7 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
       allowedTools,
       openCodeConfig,
       resumeSessionId,
+      envOverrides,
     } = options;
     const muxName = `codeman-${sessionId.slice(0, 8)}`;
 
@@ -545,6 +579,10 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
         this._configureOpenCode(muxName, openCodeConfig);
       }
 
+      // Apply user-supplied env overrides (e.g., CLAUDE_CODE_EFFORT_LEVEL) via tmux setenv
+      // so secret values stay off the bash command line. Must run before respawn-pane.
+      this.applyEnvOverrides(muxName, envOverrides);
+
       // Replace the shell with the actual command (no echo in terminal)
       execSync(`tmux respawn-pane -k -t "${muxName}" bash -c ${JSON.stringify(fullCmd)}`, {
         timeout: EXEC_TIMEOUT_MS,
@@ -685,6 +723,7 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
       allowedTools,
       openCodeConfig,
       resumeSessionId,
+      envOverrides,
     } = options;
     const session = this.sessions.get(sessionId);
     if (!session) return null;
@@ -716,6 +755,9 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
         this._configureOpenCode(muxName, openCodeConfig);
       }
 
+      // Re-apply user env overrides before respawn so the new shell inherits them.
+      this.applyEnvOverrides(muxName, envOverrides);
+
       await execAsync(`tmux respawn-pane -k -t "${muxName}" bash -c ${JSON.stringify(fullCmd)}`, {
         timeout: EXEC_TIMEOUT_MS,
       });

src/web/public/ralph-wizard.js

@@ -1032,6 +1032,10 @@ Object.assign(CodemanApp.prototype, {
     const enabledItems = config.generatedPlan?.filter(i => i.enabled);
 
     try {
+      const envOverrides = this.buildEnvOverrides(
+        this.getCaseSettings(config.caseName),
+        this.loadAppSettingsFromStorage()
+      );
       const res = await fetch('/api/ralph-loop/start', {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
@@ -1042,6 +1046,7 @@ Object.assign(CodemanApp.prototype, {
           maxIterations: config.maxIterations || null,
           enableRespawn: config.enableRespawn,
           planItems: enabledItems?.length ? enabledItems : undefined,
+          ...(Object.keys(envOverrides).length > 0 ? { envOverrides } : {}),
         }),
       });
       const data = await res.json();

src/web/public/session-ui.js

@@ -12,6 +12,22 @@
  */
 
 Object.assign(CodemanApp.prototype, {
+  /**
+   * Build envOverrides payload from case + global settings.
+   * Single source of truth for the server-side tmux setenv values.
+   * Keys omitted when value is default/falsy — backend treats unset as "no override".
+   */
+  buildEnvOverrides(caseSettings, globalSettings) {
+    const env = {};
+    if (caseSettings?.agentTeams || globalSettings?.agentTeamsEnabled) {
+      env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS = '1';
+    }
+    if (globalSettings?.thinkingEffort) {
+      env.CLAUDE_CODE_EFFORT_LEVEL = globalSettings.thinkingEffort;
+    }
+    return env;
+  },
+
   // ═══════════════════════════════════════════════════════════════
   // Quick Start
   // ═══════════════════════════════════════════════════════════════
@@ -319,14 +335,7 @@ Object.assign(CodemanApp.prototype, {
       // Build env overrides from global + case settings (case overrides global)
       const caseSettings = this.getCaseSettings(caseName);
       const globalSettings = this.loadAppSettingsFromStorage();
-      const envOverrides = {};
-      if (caseSettings.agentTeams || globalSettings.agentTeamsEnabled) {
-        envOverrides.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS = '1';
-      }
-      const thinkingEffort = globalSettings.thinkingEffort;
-      if (thinkingEffort) {
-        envOverrides.CLAUDE_CODE_EFFORT_LEVEL = thinkingEffort;
-      }
+      const envOverrides = this.buildEnvOverrides(caseSettings, globalSettings);
       const hasEnvOverrides = Object.keys(envOverrides).length > 0;
       const useOpus1m = caseSettings.opusContext1m || globalSettings.opusContext1mEnabled;
       const modelOverride = useOpus1m ? 'opus[1m]' : '';
@@ -530,13 +539,15 @@ Object.assign(CodemanApp.prototype, {
       }
 
       // Quick-start with opencode mode (auto-allow tools by default)
+      const envOverrides = this.buildEnvOverrides(this.getCaseSettings(caseName), this.loadAppSettingsFromStorage());
       const res = await fetch('/api/quick-start', {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify({
           caseName,
           mode: 'opencode',
           openCodeConfig: { autoAllowTools: true },
+          ...(Object.keys(envOverrides).length > 0 ? { envOverrides } : {}),
         })
       });
       const data = await res.json();

src/web/public/terminal-ui.js

@@ -953,11 +953,21 @@ Object.assign(CodemanApp.prototype, {
       }
       const name = `w${startNumber}-${dirName}`;
 
-      // Create session with resumeSessionId
+      // Create session with resumeSessionId — include envOverrides so resumed
+      // conversations inherit current UI settings (effort, agent teams, etc.).
+      // Match by path (not basename) so linked/renamed cases still resolve correctly.
+      const matchingCase = (this.cases || []).find((c) => c.path === workingDir);
+      const caseName = matchingCase?.name || workingDir.split('/').pop() || '';
+      const envOverrides = this.buildEnvOverrides(this.getCaseSettings(caseName), this.loadAppSettingsFromStorage());
       const createRes = await fetch('/api/sessions', {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ workingDir, name, resumeSessionId: sessionId }),
+        body: JSON.stringify({
+          workingDir,
+          name,
+          resumeSessionId: sessionId,
+          ...(Object.keys(envOverrides).length > 0 ? { envOverrides } : {}),
+        }),
       });
       const createData = await createRes.json();
       if (!createData.success) throw new Error(createData.error);