fix(claude): stop a project dotenv from overriding claude.ai subscription auth

Closes #701.

The bundled Bun runtime auto-loads a project `.env`/`.env.local` before any
opencodex code evaluates, so an `ANTHROPIC_API_KEY` sitting in whatever
directory the user launched from was indistinguishable from a deliberate shell
export by the time buildClaudeEnv read process.env. Claude Code disables
claude.ai connectors the moment either token slot is populated, so a healthy
subscription silently fell through to API billing and reported a credit-balance
error.

The npm launcher runs under Node, which does NOT auto-load dotenv, so it is the
last point that still knows the difference. It now records which Anthropic slots
were already non-empty in `OCX_PRE_BUN_ANTHROPIC_ENV` and passes that to the Bun
child; buildClaudeEnv drops any slot populated now but absent then, and deletes
the marker before it reaches Claude Code. A genuine shell export still wins, in
every auth mode, so auto-mode API-key auth keeps working.

Two details the audit forced:

- The discriminator is provenance, not `authMode === "subscription"`. Auto is
  stored as an ABSENT key and is the GUI default, and auto+present resolves to
  subscription, so keying off the literal would have missed most affected users.
- Auth detection is rebound to the sanitized env. Leaving it on the raw base let
  a credential the child never receives decide the marker, which left an
  auto-mode user with no credential AND no PROXY_MARKER.

A global `--no-env-file` was rejected: config interpolation and provider
settings legitimately read the project environment.

The transport test spawns real processes because the empty-string marker ("the
launcher ran and saw no slots") must stay distinct from an absent one ("no
launcher, change nothing"); the unit tests inject that marker directly and would
stay green if a platform ever collapsed the two.

Author: lidge-jun

bin/ocx.mjs

@@ -361,7 +361,25 @@ const bun = resolveBun();
 // signal delivered only to this launcher (Codex app, IDE terminal, service wrapper,
 // or `kill -INT <launcherPid>`) killed the launcher and ORPHANED the Bun proxy —
 // port left bound, pid/runtime-port files left behind, Codex config not restored.
-const child = spawn(bun, [cliPath, ...process.argv.slice(2)], { stdio: "inherit" });
+//
+// Provenance seam for issue #701: THIS launcher runs under Node, which does not
+// auto-load a project `.env`/`.env.local`; the Bun child does, before any opencodex
+// code evaluates. So this is the last point that can still tell a real shell export
+// from a working-directory dotenv value, and we record which Anthropic credential
+// slots already existed. `src/cli/claude.ts` then treats anything present in the Bun
+// child but missing from this list as ambient project pollution rather than user auth,
+// which stopped a project dotenv from silently moving a claude.ai subscriber onto API
+// billing. An EMPTY value is meaningful (the launcher ran and saw no slots) and is
+// distinct from the variable being absent (no launcher at all — change nothing), so
+// this must stay a plain assignment and never be collapsed to a falsy check.
+// Disabling Bun's dotenv wholesale with --no-env-file is NOT an option: config
+// interpolation and provider settings legitimately read the project environment.
+const preBunAnthropicSlots = ["ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN"]
+  .filter(name => typeof process.env[name] === "string" && process.env[name] !== "");
+const child = spawn(bun, [cliPath, ...process.argv.slice(2)], {
+  stdio: "inherit",
+  env: { ...process.env, OCX_PRE_BUN_ANTHROPIC_ENV: preBunAnthropicSlots.join(",") },
+});
 
 // Windows has no real POSIX signals (no SIGHUP); forwarding is best-effort there.
 const FORWARDED = process.platform === "win32" ? ["SIGINT", "SIGTERM"] : ["SIGINT", "SIGTERM", "SIGHUP"];

docs-site/src/content/docs/guides/claude-code.md

@@ -55,6 +55,14 @@ ocx claude
 | `CLAUDE_CODE_MAX_CONTEXT_TOKENS` / `DISABLE_COMPACT` | Legacy context override when `maxContextTokens` is set (conditional) |
 Variables you export yourself always win. Extra arguments pass through: `ocx claude -p "hello"`.
 
+One exception is about *where* a variable comes from, not about precedence. The bundled Bun
+runtime auto-loads a project `.env` / `.env.local`, so a stray `ANTHROPIC_API_KEY` in the
+directory you happen to launch from used to look identical to a deliberate export — and it
+silently disabled a healthy claude.ai subscription in favour of API billing. `ocx claude` now
+ignores Anthropic credentials that only a project dotenv introduced. A value you exported in
+your shell still wins, in every auth mode. To use an API key deliberately, export it
+(`export ANTHROPIC_API_KEY=...`) rather than leaving it in a project file.
+
 ## Auth mode
 
 Claude Code needs a token in `ANTHROPIC_AUTH_TOKEN` to talk to a gateway, but setting that

src/cli/claude.ts

@@ -48,6 +48,27 @@ export function buildClaudeEnv(
   // leaving the child with no token at all (audit R2-1). It is opencodex state, never
   // user auth, so dropping it unconditionally is safe.
   if (env.ANTHROPIC_AUTH_TOKEN === PROXY_MARKER) delete env.ANTHROPIC_AUTH_TOKEN;
+  // Step 1b — drop Anthropic credentials that the bundled Bun runtime synthesized from a
+  // project `.env`/`.env.local` (issue #701). Claude Code disables claude.ai connectors the
+  // moment either token slot is populated, so an ambient project file silently moved a
+  // subscriber onto API billing while their OAuth login stayed healthy. The npm launcher
+  // runs under Node, which does NOT auto-load dotenv, so it records the slots that existed
+  // before Bun started; anything populated now but absent then came from the working
+  // directory, not from the user. A genuine shell export is still honored, which keeps
+  // auto-mode API-key auth working. An ABSENT marker means provenance is unknowable
+  // (a direct `bun src/cli/index.ts` run, a test, or an older launcher), and then we
+  // change nothing rather than guess — an EMPTY marker is different: the launcher ran
+  // and saw no pre-existing slots.
+  const preBunSlots = base.OCX_PRE_BUN_ANTHROPIC_ENV;
+  if (preBunSlots !== undefined) {
+    const exported = new Set(preBunSlots.split(",").filter(name => name.length > 0));
+    for (const name of ["ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN"] as const) {
+      const value = env[name];
+      if (value !== undefined && value !== "" && !exported.has(name)) delete env[name];
+    }
+  }
+  // Never forward the seam itself to Claude Code.
+  delete env.OCX_PRE_BUN_ANTHROPIC_ENV;
   const setDefault = (name: string, value: string | undefined) => {
     if (value === undefined || value.length === 0) return;
     if (env[name] !== undefined && env[name] !== "") return; // user wins
@@ -76,15 +97,19 @@ export function buildClaudeEnv(
   if ((config.apiKeys?.length ?? 0) > 0) {
     setDefault("ANTHROPIC_AUTH_TOKEN", config.apiKeys![0].key);
   }
-  // Detection reads the SAME base env this launch will use, so the resolver and the
-  // spawned process cannot disagree. Injected deps are spread FIRST and `env` bound
-  // LAST, and the injection type excludes `env`, so a test fake cannot break that.
-  // `ownTokens` is bound last for the same reason: it is config-derived, and a fake
-  // that replaced it could make our own admission key look like user auth.
+  // Detection reads the SANITIZED launch env — the exact object spawned below — so the
+  // resolver and the spawned process cannot disagree. It deliberately does NOT read the
+  // raw base: the provenance strip above already removed dotenv-only credentials, and
+  // letting a value the child never receives decide the marker left an auto-mode user
+  // with neither the credential NOR the proxy marker (#701 audit round 2). Injected deps
+  // are spread FIRST and `env` bound LAST, and the injection type excludes `env`, so a
+  // test fake cannot break that. `ownTokens` is bound last for the same reason: it is
+  // config-derived, and a fake that replaced it could make our own admission key look
+  // like user auth.
   const resolved = resolveClaudeAuthMode(config, detectClaudeAuth({
-    ...defaultAuthDetectDeps(base as NodeJS.ProcessEnv),
+    ...defaultAuthDetectDeps(env as NodeJS.ProcessEnv),
     ...(deps.authDetect ?? {}),
-    env: () => base as NodeJS.ProcessEnv,
+    env: () => env as NodeJS.ProcessEnv,
     ownTokens: ownAdmissionTokens(config),
   }));
   if (!env.ANTHROPIC_AUTH_TOKEN && resolved.markerMode === "proxy") {

tests/claude-auth-mode.test.ts

@@ -124,8 +124,8 @@ test("auto-absent emits both the marker and the host assertion", () => {
   expect(env.CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST).toBe("1");
 });
 
-// A user-exported API key is auth: detection sees it through the base-env binding,
-// so no proxy token is injected and no auth-conflict warning is provoked.
+// A user-exported API key is auth: detection sees it through the sanitized launch-env
+// binding, so no proxy token is injected and no auth-conflict warning is provoked.
 test("an exported ANTHROPIC_API_KEY keeps the token slot untouched", () => {
   const env = buildClaudeEnv(
     cfg(), 10100,
@@ -147,6 +147,89 @@ test("manual subscription withholds the marker even when auth is absent", () =>
   expect(env.ANTHROPIC_AUTH_TOKEN).toBeUndefined();
 });
 
+// ---------------------------------------------------------------------------
+// #701 — project dotenv must not outrank a claude.ai subscription.
+//
+// Bun auto-loads `.env`/`.env.local` before any opencodex code runs, so process.env alone
+// cannot tell ambient pollution from a real shell export. The Node launcher runs BEFORE
+// that and records which slots already existed; these tests drive that marker directly.
+// An absent marker means provenance is unknowable, so behavior must not change.
+const PRE_BUN = "OCX_PRE_BUN_ANTHROPIC_ENV";
+
+// The reported failure: auto mode, healthy claude.ai login, key only from the dotenv.
+test("auto mode drops an Anthropic key that only Bun's dotenv introduced", () => {
+  const env = buildClaudeEnv(
+    cfg(), 10100,
+    { ANTHROPIC_API_KEY: "sk-ant-from-project-dotenv", [PRE_BUN]: "" },
+    {},
+    { authDetect: fileAuth("present") },
+  );
+  expect(env.ANTHROPIC_API_KEY).toBeUndefined();
+  expect(env[PRE_BUN]).toBeUndefined();
+});
+
+// A real shell export must still win — that is auto-mode API-key auth, which is supported.
+test("a shell-exported Anthropic key survives the dotenv strip", () => {
+  const env = buildClaudeEnv(
+    cfg(), 10100,
+    { ANTHROPIC_API_KEY: "sk-ant-user", [PRE_BUN]: "ANTHROPIC_API_KEY" },
+    {},
+    { authDetect: fileAuth("present") },
+  );
+  expect(env.ANTHROPIC_API_KEY).toBe("sk-ant-user");
+  expect(env[PRE_BUN]).toBeUndefined();
+});
+
+test("explicit subscription mode also drops a dotenv-only credential", () => {
+  const env = buildClaudeEnv(
+    cfg({ authMode: "subscription" }), 10100,
+    { ANTHROPIC_API_KEY: "sk-ant-from-project-dotenv", ANTHROPIC_AUTH_TOKEN: "token-from-dotenv", [PRE_BUN]: "" },
+    {},
+    { authDetect: fileAuth("present") },
+  );
+  expect(env.ANTHROPIC_API_KEY).toBeUndefined();
+  expect(env.ANTHROPIC_AUTH_TOKEN).toBeUndefined();
+});
+
+// The admission key is opencodex's own gate, not user auth: it is injected after the strip.
+test("the configured admission key survives the dotenv strip", () => {
+  const env = buildClaudeEnv(
+    cfg(undefined, [{ key: "admission-key" }]), 10100,
+    { ANTHROPIC_API_KEY: "sk-ant-from-project-dotenv", [PRE_BUN]: "" },
+    {},
+    { authDetect: fileAuth("present") },
+  );
+  expect(env.ANTHROPIC_API_KEY).toBeUndefined();
+  expect(env.ANTHROPIC_AUTH_TOKEN).toBe("admission-key");
+  expect(env.CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST).toBe("1");
+});
+
+// Without the launcher marker (direct `bun src/cli/index.ts`, or an older launcher)
+// provenance is unknowable, so an inherited key keeps its current meaning.
+test("without the launcher marker an inherited key is left alone", () => {
+  const env = buildClaudeEnv(
+    cfg(), 10100,
+    { ANTHROPIC_API_KEY: "sk-ant-user" },
+    {},
+    { authDetect: fileAuth("present") },
+  );
+  expect(env.ANTHROPIC_API_KEY).toBe("sk-ant-user");
+});
+
+// Stripping the key must ALSO flip detection to absent so the proxy marker is injected.
+// Binding detection to the pre-strip base left this user with no credential and no marker.
+test("a stripped dotenv key lets detection fall through to the proxy marker", () => {
+  const env = buildClaudeEnv(
+    cfg(), 10100,
+    { ANTHROPIC_API_KEY: "sk-ant-from-project-dotenv", [PRE_BUN]: "" },
+    {},
+    { authDetect: fileAuth("absent") },
+  );
+  expect(env.ANTHROPIC_API_KEY).toBeUndefined();
+  expect(env.ANTHROPIC_AUTH_TOKEN).toBe(PROXY_MARKER);
+  expect(env.CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST).toBe("1");
+});
+
 // ---------------------------------------------------------------------------
 // H2 (040_hardening): the settings.json env-hijack defence, proven per resolution.
 //

tests/claude-dotenv-provenance-transport.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, test } from "bun:test";
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+/**
+ * #701 transport proof.
+ *
+ * The dotenv-provenance fix rests on one runtime assumption: an EMPTY-STRING environment
+ * value survives a spawn and stays distinguishable from an absent variable. The whole
+ * design hinges on it, because "the launcher ran and saw zero pre-existing Anthropic
+ * slots" is encoded as `OCX_PRE_BUN_ANTHROPIC_ENV=""` while "no launcher at all, change
+ * nothing" is encoded as the variable being absent.
+ *
+ * The unit tests in claude-auth-mode.test.ts inject that marker directly into a plain
+ * object, so they would stay green even if a platform collapsed `""` to unset in real
+ * process spawning — and the production fix would silently become a no-op for exactly
+ * the case that matters most. This test spawns real processes instead, so the assumption
+ * is proven by execution on whatever platform CI runs (Linux, Windows, macOS).
+ */
+describe("empty-string env transport across a real spawn (#701)", () => {
+  const dir = mkdtempSync(join(tmpdir(), "ocx-dotenv-provenance-"));
+  const probe = join(dir, "probe.mjs");
+  writeFileSync(
+    probe,
+    'const v = process.env.OCX_PRE_BUN_ANTHROPIC_ENV;\n'
+      + 'process.stdout.write(JSON.stringify({ type: typeof v, value: v ?? null, own: "OCX_PRE_BUN_ANTHROPIC_ENV" in process.env }));\n',
+  );
+
+  function probeWith(env: NodeJS.ProcessEnv | undefined): { type: string; value: string | null; own: boolean } {
+    const result = spawnSync(process.execPath, [probe], {
+      encoding: "utf8",
+      ...(env ? { env } : {}),
+    });
+    expect(result.status).toBe(0);
+    return JSON.parse(result.stdout) as { type: string; value: string | null; own: boolean };
+  }
+
+  test("an empty marker arrives as an own property whose value is the empty string", () => {
+    const seen = probeWith({ ...process.env, OCX_PRE_BUN_ANTHROPIC_ENV: "" });
+    expect(seen.type).toBe("string");
+    expect(seen.value).toBe("");
+    expect(seen.own).toBe(true);
+  });
+
+  test("a populated marker arrives verbatim", () => {
+    const seen = probeWith({ ...process.env, OCX_PRE_BUN_ANTHROPIC_ENV: "ANTHROPIC_API_KEY" });
+    expect(seen.value).toBe("ANTHROPIC_API_KEY");
+  });
+
+  // The distinction the fix depends on: absent is NOT the same as empty.
+  test("an absent marker stays absent rather than becoming an empty string", () => {
+    const inherited = { ...process.env };
+    delete inherited.OCX_PRE_BUN_ANTHROPIC_ENV;
+    const seen = probeWith(inherited);
+    expect(seen.type).toBe("undefined");
+    expect(seen.own).toBe(false);
+  });
+});

tests/ocx-launcher-source.test.ts

@@ -22,4 +22,16 @@ describe("ocx.mjs npm launcher (source invariants)", () => {
     expect(source).toContain('if (explicit === "preview" || explicit === "latest") return explicit;');
     expect(source).not.toMatch(/if \(tagIndex !== -1 && process\.argv\[tagIndex \+ 1\]\) return process\.argv/);
   });
+
+  // #701: the launcher is the only place that still knows whether an Anthropic credential
+  // came from a real shell export or from a project dotenv, because Node does not
+  // auto-load `.env` while the Bun child does. Losing this half silently returns the
+  // proxy to billing a subscriber's API key from an ambient file, and the runtime half in
+  // src/cli/claude.ts would keep passing its own unit tests while doing nothing.
+  test("the Bun child receives the pre-Bun Anthropic provenance marker", () => {
+    expect(source).toContain("const preBunAnthropicSlots = [\"ANTHROPIC_API_KEY\", \"ANTHROPIC_AUTH_TOKEN\"]");
+    expect(source).toContain("OCX_PRE_BUN_ANTHROPIC_ENV: preBunAnthropicSlots.join(\",\")");
+    // The marker must be computed from the launcher's OWN env, before Bun's dotenv load.
+    expect(source).toContain("typeof process.env[name] === \"string\" && process.env[name] !== \"\"");
+  });
 });