fix(codex): harden pool plan refresh under config lock contention

Map credential-writer lock contention to a transient refresh timeout so
request auth cannot mark accounts needsReauth, keep WHAM plan_type in
the accounts DTO when disk persistence fails closed, and surface lock
failures from the detached OAuth task and management write path.

Author: Wibias

src/codex/account-store.ts

@@ -1,7 +1,15 @@
 import { createHash } from "node:crypto";
 import { closeSync, existsSync, readFileSync, mkdirSync, openSync, unlinkSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { getConfigDir, atomicWriteFile, backupInvalidConfig, hardenConfigDir, hardenExistingSecret, withConfigMutationLockSync } from "../config";
+import {
+  ConfigMutationLockError,
+  getConfigDir,
+  atomicWriteFile,
+  backupInvalidConfig,
+  hardenConfigDir,
+  hardenExistingSecret,
+  withConfigMutationLockSync,
+} from "../config";
 import { assertNotRealHomeUnderTest } from "../lib/test-home-guard";
 import type { CodexAccountCredentialRecord, CodexAccountCredentials } from "../types";
 
@@ -121,7 +129,7 @@ export function getCodexAccountCredential(id: string): CodexAccountCredentials |
 }
 
 export function saveCodexAccountCredential(id: string, cred: CodexAccountCredentials): void {
-  withConfigMutationLockSync(() => {
+  withCredentialMutationLockSync(() => {
     const store = loadCodexAccountRecordStore();
     const current = store[id];
     const refreshGrantFingerprint = current?.credential?.refreshToken === cred.refreshToken
@@ -139,7 +147,7 @@ export function saveCodexAccountCredential(id: string, cred: CodexAccountCredent
 }
 
 export function markCodexAccountValidated(id: string, atMs: number = Date.now()): void {
-  withConfigMutationLockSync(() => {
+  withCredentialMutationLockSync(() => {
     const store = loadCodexAccountRecordStore();
     const current = store[id];
     if (!current || current.deletedAt != null || !current.credential) return;
@@ -154,7 +162,7 @@ export function markCodexAccountValidated(id: string, atMs: number = Date.now())
 }
 
 export function markCodexAccountValidationFailed(id: string, reason: string): void {
-  withConfigMutationLockSync(() => {
+  withCredentialMutationLockSync(() => {
     const store = loadCodexAccountRecordStore();
     const current = store[id];
     if (!current || current.deletedAt != null || !current.credential) return;
@@ -189,7 +197,7 @@ export function saveCodexAccountCredentialIfGeneration(
   generation: number,
   cred: CodexAccountCredentials,
 ): boolean {
-  return withConfigMutationLockSync(() => {
+  return withCredentialMutationLockSync(() => {
     const store = loadCodexAccountRecordStore();
     const current = store[id];
     if (!current || current.generation !== generation || current.deletedAt != null || !current.credential) {
@@ -211,7 +219,7 @@ export function saveCodexAccountCredentialIfGeneration(
 }
 
 export function tombstoneCodexAccount(id: string): number {
-  return withConfigMutationLockSync(() => {
+  return withCredentialMutationLockSync(() => {
     const store = loadCodexAccountRecordStore();
     const current = store[id];
     const generation = (current?.generation ?? 0) + 1;
@@ -247,6 +255,16 @@ export class CodexCredentialRefreshLockTimeoutError extends Error {
   }
 }
 
+/** Credential writers share the config mutation coordinator; contention is transient, not reauth. */
+function withCredentialMutationLockSync<T>(fn: () => T): T {
+  try {
+    return withConfigMutationLockSync(fn);
+  } catch (error) {
+    if (error instanceof ConfigMutationLockError) throw new CodexCredentialRefreshLockTimeoutError();
+    throw error;
+  }
+}
+
 type CodexTokenResult = { accessToken: string; chatgptAccountId: string; generation: number };
 type CodexRefreshResult = CodexTokenResult & { credential?: CodexAccountCredentials };
 const refreshLocks = new Map<string, Promise<CodexRefreshResult>>();

src/codex/auth-api.ts

@@ -4,6 +4,7 @@ import {
   getValidCodexToken,
   isCodexAccountGenerationLive,
 } from "./account-store";
+import { ConfigMutationLockError } from "../config";
 import { markAccountNeedsReauth } from "./account-runtime-state";
 import { isCodexAccountUsable } from "./account-usability";
 import { reconcileMainCodexAccountRuntimeState } from "./account-lifecycle";
@@ -180,7 +181,9 @@ export class CodexThreadAffinityExpiredError extends Error {
 }
 
 export function shouldMarkAccountNeedsReauthForCodexAuthFailure(cause: unknown): boolean {
-  return !(cause instanceof CodexCredentialGenerationConflictError) && !(cause instanceof CodexCredentialRefreshLockTimeoutError);
+  return !(cause instanceof CodexCredentialGenerationConflictError)
+    && !(cause instanceof CodexCredentialRefreshLockTimeoutError)
+    && !(cause instanceof ConfigMutationLockError);
 }
 
 export interface ResolveCodexAuthContextOptions {

src/codex/auth-context.ts

@@ -1388,7 +1388,7 @@ export function withConfigMutationLockSync<T>(fn: () => T): T {
     throw error;
   } finally {
     configMutationLockDepth = 0;
-    database.close();
+    try { database.close(); } catch { /* the OS lock is released with the handle */ }
   }
 }
 

src/config.ts

@@ -167,7 +167,20 @@ export async function handleManagementAPI(req: Request, url: URL, config: OcxCon
 
   if (url.pathname.startsWith("/api/codex-auth/")) {
     const { handleCodexAuthAPI } = await import("../codex/auth-api");
-    return handleCodexAuthAPI(req, url, config);
+    const { ConfigMutationLockError } = await import("../config");
+    try {
+      return await handleCodexAuthAPI(req, url, config);
+    } catch (error) {
+      if (error instanceof ConfigMutationLockError) {
+        return jsonResponse(
+          { error: "Configuration is busy; retry shortly", code: "CONFIG_MUTATION_LOCK_UNAVAILABLE" },
+          503,
+          req,
+          config,
+        );
+      }
+      throw error;
+    }
   }
 
   return null;

src/server/management-api.ts

@@ -770,6 +770,27 @@ describe("codex-auth API", () => {
     expect(configCommits).toBe(0);
   });
 
+  test("pool plan refresh persists plan_type when WHAM omits rate_limit windows", async () => {
+    const config = makeConfig();
+    seedPoolAccount(config, {
+      id: "pool-plan-only",
+      email: "pool-plan-only@example.com",
+      plan: "plus",
+    });
+    saveConfig(structuredClone(config));
+    globalThis.fetch = (async () => Response.json({
+      plan_type: "prolite",
+    })) as typeof fetch;
+
+    const req = new Request("http://localhost/api/codex-auth/accounts?refresh=1", { method: "GET" });
+    const resp = await handleCodexAuthAPI(req, new URL(req.url), config);
+    const data = await resp!.json() as { accounts: Array<{ id: string; plan?: string }> };
+
+    expect(data.accounts.find(account => account.id === "pool-plan-only")?.plan).toBe("prolite");
+    expect(config.codexAccounts?.find(account => account.id === "pool-plan-only")?.plan).toBe("prolite");
+    expect(loadConfig().codexAccounts?.find(account => account.id === "pool-plan-only")?.plan).toBe("prolite");
+  });
+
   test("pool plan refresh performs no config write when the authoritative plan is unchanged", async () => {
     const config = makeConfig();
     seedPoolAccount(config, {
@@ -812,7 +833,8 @@ describe("codex-auth API", () => {
     const data = await resp!.json() as { accounts: Array<{ id: string; plan?: string }> };
 
     expect(resp!.status).toBe(200);
-    expect(data.accounts.find(account => account.id === "pool-plan-config-deleted")?.plan).toBe("plus");
+    // Missing config fails closed on disk, but the response still surfaces the WHAM plan.
+    expect(data.accounts.find(account => account.id === "pool-plan-config-deleted")?.plan).toBe("pro");
     expect(config.codexAccounts?.find(account => account.id === "pool-plan-config-deleted")?.plan).toBe("plus");
     expect(existsSync(join(TEST_DIR, "config.json"))).toBe(false);
   });
@@ -1003,7 +1025,7 @@ describe("codex-auth API", () => {
     expect(absentAtRecheck).toBe(true);
     expect(existsSync(getConfigPath())).toBe(false);
     expect(config.codexAccounts?.find(account => account.id === "pool-plan-cas-delete")?.plan).toBe("plus");
-    expect(data.accounts.find(account => account.id === "pool-plan-cas-delete")?.plan).toBe("plus");
+    expect(data.accounts.find(account => account.id === "pool-plan-cas-delete")?.plan).toBe("prolite");
   });
 
   test("pool plan commit leaves config malformed when malformed bytes arrive after its first checks", async () => {
@@ -1028,7 +1050,7 @@ describe("codex-auth API", () => {
     expect(malformedAtRecheck).toBe(true);
     expect(readFileSync(getConfigPath(), "utf8")).toBe(malformed);
     expect(config.codexAccounts?.find(account => account.id === "pool-plan-cas-malformed")?.plan).toBe("plus");
-    expect(data.accounts.find(account => account.id === "pool-plan-cas-malformed")?.plan).toBe("plus");
+    expect(data.accounts.find(account => account.id === "pool-plan-cas-malformed")?.plan).toBe("prolite");
   });
 
   test("pool plan commit rejects an old plan after same-id credential replacement at its commit seam", async () => {
@@ -1102,7 +1124,8 @@ describe("codex-auth API", () => {
       expect(elapsedMs).toBeLessThan(2_000);
       expect(loadConfig().codexAccounts?.find(account => account.id === accountId)?.plan).toBe("plus");
       expect(config.codexAccounts?.find(account => account.id === accountId)?.plan).toBe("plus");
-      expect(data.accounts.find(account => account.id === accountId)?.plan).toBe("plus");
+      // Disk persistence fails closed under lock contention, but the response still reflects WHAM.
+      expect(data.accounts.find(account => account.id === accountId)?.plan).toBe("prolite");
     } finally {
       lockDatabase.exec("ROLLBACK");
       lockDatabase.close();

tests/codex-auth-api.test.ts

@@ -25,6 +25,7 @@ import {
   removeCodexAccountCredential,
   saveCodexAccountCredential,
 } from "../src/codex/account-store";
+import { ConfigMutationLockError } from "../src/config";
 import { MAIN_CODEX_ACCOUNT_ID } from "../src/codex/main-account";
 import { clearAccountNeedsReauth, isAccountNeedsReauth } from "../src/codex/auth-api";
 import {
@@ -519,6 +520,7 @@ describe("Codex auth context", () => {
   test("reauth marking is reserved for real token failures", () => {
     expect(shouldMarkAccountNeedsReauthForCodexAuthFailure(new CodexCredentialGenerationConflictError())).toBe(false);
     expect(shouldMarkAccountNeedsReauthForCodexAuthFailure(new CodexCredentialRefreshLockTimeoutError())).toBe(false);
+    expect(shouldMarkAccountNeedsReauthForCodexAuthFailure(new ConfigMutationLockError("busy"))).toBe(false);
     expect(shouldMarkAccountNeedsReauthForCodexAuthFailure(new Error("bad token"))).toBe(true);
   });
 

tests/codex-auth-context.test.ts

@@ -2,8 +2,8 @@ import { afterEach, beforeEach, expect, test } from "bun:test";
 import { existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { pathToFileURL } from "node:url";
-import { ConfigMutationLockError, loadConfig, saveConfig } from "../src/config";
-import { getCodexAccountCredential, saveCodexAccountCredential } from "../src/codex/account-store";
+import { ConfigMutationLockError, loadConfig, saveConfig, withConfigMutationLockSync } from "../src/config";
+import { CodexCredentialRefreshLockTimeoutError, getCodexAccountCredential, saveCodexAccountCredential } from "../src/codex/account-store";
 import type { OcxConfig } from "../src/types";
 
 let testRoot = "";
@@ -66,15 +66,22 @@ test("a live cross-process holder is not stolen and runtime writers fail immedia
   });
 
   try {
-    await waitForPath(readyPath);
+    try {
+      await waitForPath(readyPath);
+    } catch (error) {
+      child.kill();
+      await child.exited;
+      const stderr = await new Response(child.stderr).text().catch(() => "");
+      throw new Error(`${(error as Error).message}\nchild stderr: ${stderr}`);
+    }
     const startedAt = performance.now();
     expect(() => saveConfig(config(20200))).toThrow(ConfigMutationLockError);
     expect(() => saveCodexAccountCredential("busy-account", {
       accessToken: "busy-access",
       refreshToken: "busy-refresh",
       expiresAt: Date.now() + 60_000,
       chatgptAccountId: "busy-chatgpt-account",
-    })).toThrow(ConfigMutationLockError);
+    })).toThrow(CodexCredentialRefreshLockTimeoutError);
     expect(performance.now() - startedAt).toBeLessThan(1_000);
     expect(loadConfig().port).toBe(10100);
     expect(getCodexAccountCredential("busy-account")).toBeNull();
@@ -119,3 +126,12 @@ test("an abruptly exited holder releases the OS-backed transaction without stale
   expect(() => saveConfig(config(30300))).not.toThrow();
   expect(loadConfig().port).toBe(30300);
 });
+
+test("a throwing mutation releases the lock and leaves writers available", () => {
+  saveConfig(config());
+  expect(() => withConfigMutationLockSync(() => {
+    throw new Error("mutation failed");
+  })).toThrow("mutation failed");
+  expect(() => saveConfig(config(50500))).not.toThrow();
+  expect(loadConfig().port).toBe(50500);
+});