fix(core): load every .env on the search path, not just the first found (INT-3256) (#382)

loadEnvFile() returned as soon as it found ANY .env file, so a project
with its own (older) .env never even looked at the global
~/.config/openswarm/.env — any credential that lives only in the
global file was invisible to that project. ATLAS_CLOUD_API_KEY is
global-only, so `openswarm review --max` from a repo with its own
.env (e.g. STONKS) failed every subagent's auth instantly, project-
wide, while the same command worked fine from a repo whose .env
already had every key.

Now iterates the full search path and applies each file's keys only
when not already set, preserving shell-wins/first-file-wins
precedence but no longer stopping after the first file that exists.
EnvLoadResult.path (string | null) -> paths (string[]); the one real
caller (src/index.ts) updated to log the joined list.

Author: unohee

src/core/envFile.test.ts

@@ -1,9 +1,20 @@
-import { afterEach, describe, expect, it } from 'vitest';
-import { mkdtempSync, readFileSync, writeFileSync, statSync, rmSync } from 'node:fs';
-import { tmpdir, platform } from 'node:os';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { mkdtempSync, mkdirSync, readFileSync, writeFileSync, statSync, rmSync } from 'node:fs';
+import { tmpdir, platform, homedir as realHomedir } from 'node:os';
 import { join } from 'node:path';
 import { writeEnvVars } from './envFile.js';
 
+vi.mock('node:os', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('node:os')>();
+  return { ...actual, homedir: () => mockedHome };
+});
+
+// Reassigned per-test by loadEnvFileWith(); the node:os mock above reads it
+// live, so tests never touch the real home directory.
+let mockedHome = '';
+
+const { loadEnvFile } = await import('./envFile.js');
+
 let dir: string | null = null;
 function freshEnvPath(): string {
   dir = mkdtempSync(join(tmpdir(), 'env-write-'));
@@ -55,3 +66,66 @@ describe('writeEnvVars', () => {
     expect(statSync(p).mode & 0o777).toBe(0o600);
   });
 });
+
+// Regression for INT-3247: a project with its own (older) .env silently hid
+// every key that only lived in the global ~/.config/openswarm/.env, because
+// loadEnvFile returned after the FIRST file it found instead of layering
+// all of them. `openswarm review --max` from such a project failed every
+// subagent instantly — ATLASCLOUD_API_KEY was global-only.
+describe('loadEnvFile', () => {
+  let projectDir: string;
+  const savedEnv: Record<string, string | undefined> = {};
+
+  function stashEnv(...keys: string[]) {
+    for (const k of keys) savedEnv[k] = process.env[k];
+  }
+
+  afterEach(() => {
+    if (projectDir) rmSync(projectDir, { recursive: true, force: true });
+    if (mockedHome && mockedHome !== realHomedir()) rmSync(mockedHome, { recursive: true, force: true });
+    for (const [k, v] of Object.entries(savedEnv)) {
+      if (v === undefined) delete process.env[k];
+      else process.env[k] = v;
+    }
+    vi.restoreAllMocks();
+  });
+
+  it('falls back to a global .env key the project-local .env does not define', () => {
+    projectDir = mkdtempSync(join(tmpdir(), 'env-project-'));
+    mockedHome = mkdtempSync(join(tmpdir(), 'env-home-'));
+    const configDir = join(mockedHome, '.config', 'openswarm');
+    mkdirSync(configDir, { recursive: true });
+
+    writeFileSync(join(projectDir, '.env'), 'PROJECT_ONLY=local\n');
+    writeFileSync(join(configDir, '.env'), 'GLOBAL_ONLY=global\nPROJECT_ONLY=should-not-win\n');
+
+    stashEnv('PROJECT_ONLY', 'GLOBAL_ONLY', 'OPENSWARM_ENV', 'OPENSWARM_CONFIG');
+    delete process.env.OPENSWARM_ENV;
+    delete process.env.OPENSWARM_CONFIG;
+    delete process.env.PROJECT_ONLY;
+    delete process.env.GLOBAL_ONLY;
+    vi.spyOn(process, 'cwd').mockReturnValue(projectDir);
+
+    const result = loadEnvFile();
+
+    expect(process.env.PROJECT_ONLY).toBe('local'); // local file wins the shared key
+    expect(process.env.GLOBAL_ONLY).toBe('global'); // global-only key still gets picked up
+    expect(result.paths).toEqual([join(projectDir, '.env'), join(configDir, '.env')]);
+  });
+
+  it('a pre-existing process.env value beats every file', () => {
+    projectDir = mkdtempSync(join(tmpdir(), 'env-project-'));
+    mockedHome = mkdtempSync(join(tmpdir(), 'env-home-'));
+    writeFileSync(join(projectDir, '.env'), 'SHELL_WINS=from-file\n');
+
+    stashEnv('SHELL_WINS', 'OPENSWARM_ENV', 'OPENSWARM_CONFIG');
+    delete process.env.OPENSWARM_ENV;
+    delete process.env.OPENSWARM_CONFIG;
+    process.env.SHELL_WINS = 'from-shell';
+    vi.spyOn(process, 'cwd').mockReturnValue(projectDir);
+
+    loadEnvFile();
+
+    expect(process.env.SHELL_WINS).toBe('from-shell');
+  });
+});

src/core/envFile.ts

@@ -2,18 +2,21 @@
 // OpenSwarm - .env auto-loader
 // ============================================
 //
-// Minimal, zero-dependency .env loader. Populates process.env with entries
-// from the first .env file found, searching locations parallel to the config
+// Minimal, zero-dependency .env loader. Populates process.env by layering
+// every .env file found across the search path (project-local first, then
+// the global fallbacks), searching locations parallel to the config
 // resolver. Existing process.env values are never overwritten — a shell
-// export always wins over the file.
+// export always wins over any file, and a key already set by an
+// earlier (more specific) file wins over the same key in a later,
+// more general one.
 
 import { existsSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { atomicWriteFileSync } from '../support/atomicFile.js';
 
 export interface EnvLoadResult {
-  path: string | null;
+  paths: string[];
   loadedKeys: string[];
 }
 
@@ -124,17 +127,27 @@ export function writeEnvVars(path: string, kv: Record<string, string>): void {
 }
 
 /**
- * Load the first discovered .env file into process.env without overwriting
- * existing values. Returns the path loaded (or null) and the list of keys
- * that were newly applied — callers can log this for diagnostics.
+ * Load every discovered .env file into process.env without overwriting
+ * existing values. A project-local `.env` shadows the global fallback ones
+ * key-by-key, not file-by-file — a repo whose own `.env` predates a
+ * credential that only lives in `~/.config/openswarm/.env` still picks that
+ * credential up, instead of the global file being skipped entirely because
+ * the local one was found first. (INT-3256: `ATLASCLOUD_API_KEY` set only in
+ * the global .env was invisible to every run from a repo with its own,
+ * older `.env` — every subagent failed auth instantly, project-wide.)
+ *
+ * Returns the paths actually read (in precedence order) and the list of
+ * keys that were newly applied — callers can log this for diagnostics.
  */
 export function loadEnvFile(): EnvLoadResult {
+  const paths: string[] = [];
+  const loadedKeys: string[] = [];
+
   for (const path of getSearchPaths()) {
     if (!existsSync(path)) continue;
+    paths.push(path);
 
     const content = readFileSync(path, 'utf8');
-    const loadedKeys: string[] = [];
-
     for (const rawLine of content.split(/\r?\n/)) {
       const parsed = parseLine(rawLine);
       if (parsed === null) continue;
@@ -143,9 +156,7 @@ export function loadEnvFile(): EnvLoadResult {
       process.env[key] = value;
       loadedKeys.push(key);
     }
-
-    return { path, loadedKeys };
   }
 
-  return { path: null, loadedKeys: [] };
+  return { paths, loadedKeys };
 }

src/index.ts

@@ -12,8 +12,8 @@ dns.setDefaultResultOrder('ipv4first');
 // launched from a non-interactive shell without those vars exported.
 import { loadEnvFile } from './core/envFile.js';
 const envLoad = loadEnvFile();
-if (envLoad.path !== null) {
-  console.log(`Loaded env from: ${envLoad.path} (${envLoad.loadedKeys.length} keys)`);
+if (envLoad.paths.length > 0) {
+  console.log(`Loaded env from: ${envLoad.paths.join(', ')} (${envLoad.loadedKeys.length} keys)`);
 }
 
 // Strip Claude Code session markers so child processes (worker, planner) can launch Claude CLI