@bitkyc08/opencodex 2.80.0 → 2.82.0

package/src/clients/config-export/commandcode.ts

@@ -0,0 +1,131 @@
+// Command Code config export.
+import type { ExportContext, ManagedContribution } from "./contracts";
+import { normalizeExportModels, authoritativeContextWindow, singleFragment } from "./model-metadata";
+import { OPENCODE_PROVIDER_ID, LOOPBACK_API_KEY_PLACEHOLDER } from "./constants";
+import { sanitizeCodexReasoningEfforts } from "../../reasoning-effort";
+
+export interface CommandCodeModelEntry {
+  reasoningEfforts?: string[];
+  contextWindow?: number;
+}
+
+export interface CommandCodeProviderBlock {
+  name: "OpenCodex";
+  api: "openai-completions";
+  baseURL: string;
+  apiKey: string | boolean;
+  models: Record<string, CommandCodeModelEntry>;
+}
+
+export interface CommandCodeGeneratedConfig {
+  provider: Record<string, CommandCodeProviderBlock>;
+  /** The root a pre-existing target already uses; see {@link commandCodeProviderRoot}. */
+  providers?: Record<string, CommandCodeProviderBlock>;
+}
+
+/**
+ * LOSSY spelling-collision key for a routed selector — not model identity.
+ *
+ * One provider model reaches this exporter under interchangeable spellings: the raw
+ * selector keeps inner slashes (`command-code/deepseek/deepseek-v4.1-flash`, what
+ * `/v1/models` publishes) while the Codex-facing form encodes them as dashes
+ * (`command-code/deepseek-deepseek-v4.1-flash`, what `~/.codex/config.toml` stores and
+ * what an operator typing `--model` copies). Command Code addresses models by exact key,
+ * so a catalog that carries both spellings can resolve the active model against one and
+ * miss it in the other.
+ *
+ * The slash is meaningful: it separates the provider from the model id, and a provider id
+ * never contains one. But the encoding is NOT bijective — `p/a/b` and `p/a-b` are
+ * different model ids that encode to the same string. That is the same lossy relation
+ * `slugEquivalenceKey` documents in src/providers/slug-codec.ts and the same ambiguity
+ * `resolveSlugAliasCollisions` guards in the catalog. Callers must therefore never drop
+ * a row on this key alone; buildCommandCodeClientConfig additionally compares provider
+ * and id before folding two rows into one.
+ */
+function canonicalSpellingOf(namespaced: string): string {
+  const slash = namespaced.indexOf("/");
+  if (slash <= 0) return namespaced;
+  return namespaced.slice(0, slash) + "/" + namespaced.slice(slash + 1).replaceAll("/", "-");
+}
+
+export function buildCommandCodeClientConfig(ctx: ExportContext): CommandCodeGeneratedConfig {
+  const models: Record<string, CommandCodeModelEntry> = {};
+  // Fold interchangeable spellings of one model onto a single key. The first
+  // occurrence wins per provider+id identity; distinct model ids that happen to
+  // share a lossy spelling collision must both remain addressable.
+  const emittedIdentitiesByCollision = new Map<string, Set<string>>();
+  for (const model of normalizeExportModels(ctx.models)) {
+    const emittedKey = model.namespaced;
+    const collisionKey = canonicalSpellingOf(model.namespaced);
+    const identity = `${model.provider}\u0000${model.id}`;
+    const identities = emittedIdentitiesByCollision.get(collisionKey) ?? new Set<string>();
+    if (identities.has(identity)) continue;
+    identities.add(identity);
+    emittedIdentitiesByCollision.set(collisionKey, identities);
+    const entry: CommandCodeModelEntry = {};
+    const context = authoritativeContextWindow(model.contextWindow);
+    if (context !== undefined) {
+      entry.contextWindow = context;
+    }
+    const efforts = sanitizeCodexReasoningEfforts(model.reasoningEfforts)
+      ?.filter(effort => ["low", "medium", "high", "xhigh", "max"].includes(effort));
+    if (efforts && efforts.length > 0) {
+      entry.reasoningEfforts = efforts;
+    }
+    models[emittedKey] = entry;
+  }
+  return {
+    provider: {
+      [OPENCODE_PROVIDER_ID]: {
+        name: "OpenCodex",
+        api: "openai-completions",
+        baseURL: ctx.baseUrl.replace(/\/v1\/?$/, "") + "/v1",
+        apiKey: false,
+        models,
+      },
+    },
+  };
+}
+
+/**
+ * The root key Command Code actually reads: `provider`, else `providers`.
+ *
+ * Verified against the published client (`command-code@1.66.0`, `dist/cli.mjs`):
+ * `const o = e.provider ?? e.providers;` — singular wins, and the plural branch is
+ * only reached when the singular root is nullish (`null` or `undefined`). Adding a
+ * singular root to a document that already carries a plural one therefore does not
+ * merge the two: the old entries stay on disk, byte for byte, and become invisible
+ * to the consumer.
+ *
+ * Evaluates nullish precedence before container validation so that non-nullish
+ * invalid singular values (such as strings or arrays) remain selected and are refused
+ * by the container guard rather than falling through to write an unreachable plural block.
+ */
+export function commandCodeProviderRoot(document: unknown): "provider" | "providers" {
+  const doc = document as { provider?: unknown; providers?: unknown } | null | undefined;
+  if (doc?.provider !== undefined && doc?.provider !== null) return "provider";
+  if (doc?.providers !== undefined && doc?.providers !== null) return "providers";
+  // Nothing established yet: the singular root is the one this exporter writes.
+  return "provider";
+}
+
+export function summarizeCommandCode(document: unknown): { modelCount: number; modelsWithoutLimits: number } {
+  const doc = document as CommandCodeGeneratedConfig | undefined;
+  const root = commandCodeProviderRoot(document);
+  const models = Object.values(doc?.[root]?.[OPENCODE_PROVIDER_ID]?.models ?? {}) as CommandCodeModelEntry[];
+  return { modelCount: models.length, modelsWithoutLimits: models.filter(model => model.contextWindow === undefined).length };
+}
+
+/**
+ * The provider block, written under whichever root the target document already uses.
+ *
+ * `ExportContext` carries the parsed target document so the root can be chosen from
+ * what is on disk rather than assumed. A fresh file gets the singular root this
+ * exporter has always written; a document that already carries a plural root keeps
+ * it, so enabling OpenCodex never makes the user's other providers unreadable.
+ */
+export function buildCommandCodeContribution(ctx: ExportContext): ManagedContribution {
+  const doc = buildCommandCodeClientConfig(ctx);
+  const root = commandCodeProviderRoot(ctx.document);
+  return singleFragment("commandcode", [root, OPENCODE_PROVIDER_ID], doc.provider[OPENCODE_PROVIDER_ID]);
+}

package/src/clients/config-export/contracts.ts

@@ -185,6 +185,17 @@ export interface ExportContext {
    */
   config?: OcxConfig;
   droidReasoningDefaults?: DroidReasoningDefaults;
+  /**
+   * The parsed target document, when the caller has one in hand.
+   *
+   * A client whose reader picks between two roots needs the bytes on disk to
+   * choose: Command Code resolves `document.provider ?? document.providers`, so
+   * writing the singular root into a document that already carries the plural one
+   * leaves the user's providers unreadable rather than merging with them. Absent
+   * for `ocx export`, which has no target file — the builder then writes its
+   * default root, exactly as before.
+   */
+  document?: unknown;
 }
 
 /** Namespaced model selector to one of that model's declared reasoning efforts. */
@@ -206,6 +217,7 @@ export type ExportClientId =
   | "raycast"
   | "omo"
   | "cline"
+  | "commandcode"
   | "kilo"
   | "droid";
 

package/src/clients/config-export.ts

@@ -21,7 +21,7 @@
  */
 import { homedir } from "node:os";
 import { existsSync, lstatSync, readFileSync, realpathSync, statSync } from "node:fs";
-import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { basename, dirname, isAbsolute, join, resolve, win32 } from "node:path";
 import { shouldInjectApiAuthHeader, standaloneCodexRoutingTarget } from "../codex/inject";
 import { FORMAT_MEDIA_TYPE, serializeDocument, type ConfigFormat } from "../integrations/serialize";
 import { canonicalizeReasoningEfforts } from "../reasoning-effort";
@@ -69,6 +69,18 @@ import { buildKiloClientConfig, summarizeKilo, buildKiloContribution, kiloConfig
 export { kiloConfigPath, kiloHomeDir, kiloCandidatePath, KILO_CONFIG_CANDIDATES } from "./config-export/kilo";
 export type { KiloGeneratedConfig, KiloProviderBlock, KiloModelEntry } from "./config-export/kilo";
 import { droidConfigPath, buildDroidClientConfig, summarizeDroid, buildDroidContribution } from "./config-export/droid";
+import {
+  buildCommandCodeClientConfig,
+  summarizeCommandCode,
+  buildCommandCodeContribution,
+  commandCodeProviderRoot,
+  type CommandCodeGeneratedConfig,
+  type CommandCodeModelEntry,
+  type CommandCodeProviderBlock,
+} from "./config-export/commandcode";
+
+export type { CommandCodeGeneratedConfig, CommandCodeModelEntry, CommandCodeProviderBlock };
+export { buildCommandCodeClientConfig, summarizeCommandCode, buildCommandCodeContribution, commandCodeProviderRoot };
 
 
 
@@ -474,6 +486,43 @@ export function zcodeConfigPath(env: OpencodeLaunchEnv = process.env, home: stri
   return join(zcodeHomeDir(env, home), "v2", "config.json");
 }
 
+/**
+ * The home directory Command Code itself resolves: `env.HOME ?? env.USERPROFILE`
+ * (`homeDir15` in the published `command-code@1.66.0` bundle).
+ *
+ * On POSIX `os.homedir()` already reads `$HOME`, so the two agree and `home` is
+ * returned as is. On Windows `os.homedir()` reads `%USERPROFILE%` and ignores
+ * `HOME`, which Git for Windows, MSYS2 and Cygwin set, so a user whose `HOME` differs
+ * would get a provider block in a store Command Code never opens. Only the OS-default
+ * home is replaced: a caller that injects a different root (a test, the writer's
+ * `input.home`) keeps it, and a blank or relative value falls back to `home`.
+ */
+export function commandCodeUserHome(env: OpencodeLaunchEnv = process.env, home: string = homedir(), platform: NodeJS.Platform = process.platform): string {
+  if (platform !== "win32" || home !== homedir()) return home;
+  const value = env.HOME ?? env.USERPROFILE;
+  return typeof value === "string" && value.trim() && win32.isAbsolute(value) ? value : home;
+}
+
+/**
+ * Command Code's provider store directory — `.commandcode` under the home the client
+ * resolves (see {@link commandCodeUserHome}), with no override.
+ *
+ * There is deliberately no `COMMANDCODE_HOME` here, unlike the other clients in this
+ * file: `grep -c COMMANDCODE_HOME` over the shipped `dist/cli.mjs` and
+ * `dist/index.mjs` returns 0. An override we honour but the client ignores is worse
+ * than none: `enable` would report success and write a provider block at a path no
+ * Command Code process ever opens, and the user would see an empty model list with no
+ * error anywhere. An apply against a relocated home is instead refused by `detectDir`
+ * not existing.
+ */
+export function commandCodeHomeDir(env: OpencodeLaunchEnv = process.env, home: string = homedir(), platform: NodeJS.Platform = process.platform): string {
+  return join(commandCodeUserHome(env, home, platform), ".commandcode");
+}
+
+export function commandCodeConfigPath(env: OpencodeLaunchEnv = process.env, home: string = homedir(), platform: NodeJS.Platform = process.platform): string {
+  return join(commandCodeHomeDir(env, home, platform), "providers.json");
+}
+
 /**
  * The provider store a current ZCode reads, which is NOT the file above.
  *
@@ -1487,6 +1536,20 @@ export const EXPORT_CLIENTS: Record<ExportClientId, ExportClientSpec> = {
     // remote binds refuse — same reasoning as MCode.
     loopbackOnly: true,
   },
+  commandcode: {
+    id: "commandcode",
+    filename: "providers.json",
+    destination: env => commandCodeConfigPath(env),
+    // No env var exists behind this integration: buildCommandCodeClientConfig
+    // writes `apiKey: false`, the documented keyless form for a loopback endpoint.
+    apiKeyEnv: "",
+    exportHint: "The provider is written with `apiKey: false` — Command Code treats a keyless loopback endpoint as already authenticated. No key is stored or referenced.",
+    build: buildCommandCodeClientConfig,
+    format: "json",
+    summarize: summarizeCommandCode,
+    buildContribution: buildCommandCodeContribution,
+    loopbackOnly: true,
+  },
   prime: {
     id: "prime",
     filename: "prime-models.json",

package/src/clients/lazycodex.ts

@@ -1,6 +1,6 @@
 /**
  * Detection of Codex-based omo (LazyCodex), the variant that reads Codex role files and
- * `codex.agents.<role>.model` in `~/.omo/omo.jsonc`.
+ * `"[codex]".agents.<role>.model` in `~/.omo/omo.jsonc`.
  *
  * "omo" names three products. Pi-based omo (senpi) owns `~/.omo/agent` and is the omo file
  * integration in `src/integrations/registry.ts`; OpenCode-based omo (oh-my-opencode) keeps its

package/src/clients/omo-role-models.ts

@@ -1,5 +1,7 @@
 /**
- * omo (Codex / LazyCodex)'s per-role model setting, `codex.agents.<role>.model` in `~/.omo/omo.jsonc`.
+ * omo (Codex / LazyCodex)'s per-role model setting, `"[codex]".agents.<role>.model` in `~/.omo/omo.jsonc`.
+ * The section name carries its brackets: LazyCodex reads `[codex]`, and its strict loader drops a
+ * bare `codex` key as unknown, so a pick written there never reaches a role.
  *
  * LazyCodex 5.1.1 and later reads it, and callers reach this only after `detectLazyCodex`
  * says LazyCodex is installed. The file is omo's, so this writes only on an explicit
@@ -30,6 +32,17 @@ export function omoJsoncPath(env: NodeJS.ProcessEnv = process.env, home: string
 
 type JsonObject = Record<string, unknown>;
 
+const CODEX_SECTION = "[codex]";
+
+/** The reasoning levels LazyCodex accepts for a role; it names Codex's `none` `off`. */
+const LAZYCODEX_REASONING = new Set(["off", "minimal", "low", "medium", "high", "xhigh", "max"]);
+
+/** The `reasoning` value LazyCodex reads for a Codex effort, or null when it has no such level. */
+export function omoReasoningFor(effort: string): string | null {
+  const level = effort === "none" ? "off" : effort;
+  return LAZYCODEX_REASONING.has(level) ? level : null;
+}
+
 function isObject(value: unknown): value is JsonObject {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -71,7 +84,7 @@ function load(path: string): Loaded {
 }
 
 function agentsOf(doc: JsonObject): JsonObject | null | undefined {
-  const codex = doc.codex;
+  const codex = doc[CODEX_SECTION];
   if (codex === undefined) return undefined;
   if (!isObject(codex)) return null;
   const agents = codex.agents;
@@ -104,21 +117,33 @@ function serialize(text: string, doc: JsonObject): string {
   return text.startsWith("\ufeff") ? `\ufeff${out}` : out;
 }
 
-export function writeOmoRoleModel(role: string, model: string, path: string = omoJsoncPath()): OmoRoleModelWriteStatus {
+/**
+ * `reasoning` left undefined keeps the entry's level; null removes it, so a level LazyCodex cannot
+ * express does not leave a stale one behind for its next install to apply.
+ */
+export function writeOmoRoleModel(
+  role: string,
+  model: string,
+  path: string = omoJsoncPath(),
+  reasoning?: string | null,
+): OmoRoleModelWriteStatus {
   const loaded = load(path);
   if (loaded.kind !== "document") return loaded.kind === "comments" ? "skipped_comments" : loaded.kind;
   const { doc, text } = loaded;
   // Only an absent key is created; an explicit null is a value the reader calls invalid.
-  const codex = doc.codex === undefined ? {} : doc.codex;
+  const codex = doc[CODEX_SECTION] === undefined ? {} : doc[CODEX_SECTION];
   if (!isObject(codex)) return "invalid";
   const agents = codex.agents === undefined ? {} : codex.agents;
   if (!isObject(agents)) return "invalid";
   const entry = agents[role] === undefined ? {} : agents[role];
   if (!isObject(entry)) return "invalid";
-  if (entry.model === model) return "unchanged";
-  agents[role] = { ...entry, model };
+  const next: JsonObject = { ...entry, model };
+  if (reasoning === null) delete next.reasoning;
+  else if (reasoning !== undefined) next.reasoning = reasoning;
+  if (entry.model === model && entry.reasoning === next.reasoning) return "unchanged";
+  agents[role] = next;
   codex.agents = agents;
-  doc.codex = codex;
+  doc[CODEX_SECTION] = codex;
   assertIntegrationWriteOwnership(path);
   atomicWriteFileNoFollowUnclaimed(path, serialize(text, doc));
   return "written";

package/src/codex/auth-api/account-list.ts

@@ -252,6 +252,13 @@ export function reconcileFreshPoolAccountPlans(runtimeConfig: OcxConfig, updates
   }
 }
 
+export interface CodexAuthAccountsListOptions {
+  /** Finish deferred registration; only a dashboard session carries that inference consent. */
+  validatePending?: boolean;
+  /** An operator's explicit refresh command, which may retry a grant already recorded as dead. */
+  explicitRefresh?: boolean;
+}
+
 export interface CodexAuthAccountsSnapshot {
   accounts: CodexAuthAccountDto[];
   mainIdentityGeneration: number;
@@ -260,7 +267,7 @@ export interface CodexAuthAccountsSnapshot {
 export async function listCodexAuthAccountsSnapshot(
   config: OcxConfig,
   forceRefresh = false,
-  options: { validatePending?: boolean } = {},
+  options: CodexAuthAccountsListOptions = {},
 ): Promise<CodexAuthAccountsSnapshot> {
   const runtimeConfig = getRuntimeConfig(config);
   const poolAccounts = (runtimeConfig.codexAccounts ?? []).filter(isSelectableCodexPoolAccount);
@@ -281,7 +288,8 @@ export async function listCodexAuthAccountsSnapshot(
         // identity when the switch is on and nothing has been observed yet.
         const creditsIdentity = runtimeConfig.showCodexCredits === true ? poolQuotaHistoryIdentity(account.id) ?? null : null;
         const creditsUnobserved = creditsIdentity !== null && !hasCodexCreditsObservation(account.id, creditsIdentity);
-        quotaResult = await fetchPoolAccountQuota(account.id, forceRefresh || creditsUnobserved, account.plan, getValidCodexToken, options.validatePending === true);
+        quotaResult = await fetchPoolAccountQuota(account.id, forceRefresh || creditsUnobserved, account.plan, getValidCodexToken,
+          options.validatePending === true, undefined, undefined, options.explicitRefresh === true);
       } catch (error) {
         if (!(error instanceof PoolQuotaProbeBusyError)) throw error;
         quotaResult = {
@@ -447,7 +455,7 @@ export async function refreshCodexQuotaForActivation(config: OcxConfig, accountI
 export async function listCodexAuthAccounts(
   config: OcxConfig,
   forceRefresh = false,
-  options: { validatePending?: boolean } = {},
+  options: CodexAuthAccountsListOptions = {},
 ): Promise<CodexAuthAccountDto[]> {
   return (await listCodexAuthAccountsSnapshot(config, forceRefresh, options)).accounts;
 }

package/src/codex/auth-api/account-selection.ts

@@ -0,0 +1,107 @@
+import type { OcxConfig } from "../../types";
+import { getConfigPath, initializePersistedConfigIfMissing, mutatePersistedConfig } from "../../config";
+import { mergeConfigDefaults, readConfigFileSnapshot, validateConfigCandidate } from "../../config/diagnostics";
+import { adoptPersistedCodexAccountSelection, claudeCodeBaselineArmed } from "../../config/live-reconcile";
+import { deleteConfigTopLevelKey, fileBackedConfigPath, recordFileBackedConfig } from "../../config/rebase-provenance";
+import { MAIN_CODEX_ACCOUNT_ID, hasLegacyMainCodexPoolAccount, isSelectableCodexPoolAccount, isValidCodexAccountId } from "../account-id";
+import { isCodexAccountPaused } from "../account-pause";
+import { readCodexAccountRecord } from "../account-store";
+import { codexAccountPinDrainReason, resetCodexRoutingForManualSelection } from "../routing";
+import { jsonResponse } from "./http";
+
+class SelectionRejected extends Error {
+  constructor(message: string, readonly status: number) { super(message); }
+}
+
+function validateSelection(config: OcxConfig, accountId: string | null): void {
+  if (accountId === null) return;
+  if (accountId === MAIN_CODEX_ACCOUNT_ID && hasLegacyMainCodexPoolAccount(config.codexAccounts)) {
+    throw new SelectionRejected("Remove the legacy __main__ pool row before selecting the Desktop account", 409);
+  }
+  if (isCodexAccountPaused(config, accountId)) throw new SelectionRejected("Account is paused", 409);
+  if (accountId === MAIN_CODEX_ACCOUNT_ID) return;
+  if (!isValidCodexAccountId(accountId)) throw new SelectionRejected("Invalid account id format", 400);
+  if (!(config.codexAccounts ?? []).some(account => isSelectableCodexPoolAccount(account) && account.id === accountId)) {
+    throw new SelectionRejected("Account not found", 400);
+  }
+  if (readCodexAccountRecord(accountId)?.codexValidationPending) {
+    throw new SelectionRejected("Account validation is pending. Refresh quota after recovery to validate it.", 409);
+  }
+}
+
+function applySelection(config: OcxConfig, accountId: string | null): boolean {
+  const changed = config.activeCodexAccountId !== (accountId ?? undefined)
+    || config.activeCodexAccountPinned !== (accountId ?? undefined);
+  if (accountId === null) {
+    deleteConfigTopLevelKey(config, "activeCodexAccountId");
+    deleteConfigTopLevelKey(config, "activeCodexAccountPinned");
+  } else {
+    config.activeCodexAccountId = accountId;
+    config.activeCodexAccountPinned = accountId;
+  }
+  return changed;
+}
+
+/** A manual selection is an explicit command, even when equal to the live merge baseline. */
+export function persistCodexAccountSelection(config: OcxConfig, accountId: string | null): Response {
+  const unknown = () => jsonResponse({
+    error: "Account selection could not be confirmed; reload settings before retrying",
+    code: "account_selection_unavailable",
+  }, 409);
+  const configPath = getConfigPath();
+  const sourcePath = fileBackedConfigPath(config);
+  if (sourcePath !== undefined && sourcePath !== configPath) return unknown();
+  let committed: OcxConfig;
+  let warning = false;
+  try {
+    // Do not activate a newly disk-only account that the running proxy has not adopted.
+    validateSelection(config, accountId);
+    const before = readConfigFileSnapshot();
+    if (before.diagnostics.source === "default" && !fileBackedConfigPath(config) && !claudeCodeBaselineArmed(config)) {
+      // Preserve transient/initial callers without recreating a deleted live configuration.
+      // The create-only owner cannot replace a competing writer's newly published config.
+      const normalized = validateConfigCandidate(mergeConfigDefaults(config));
+      if (!normalized.ok) return unknown();
+      const initial = normalized.config;
+      applySelection(initial, accountId);
+      initializePersistedConfigIfMissing(initial);
+    }
+    const result = mutatePersistedConfig(persisted => {
+      // This callback is re-run under the mutation lock immediately before publication.
+      // A removed or paused account must not be resurrected by a stale UI snapshot.
+      validateSelection(config, accountId);
+      validateSelection(persisted, accountId);
+      return { changed: applySelection(persisted, accountId), value: persisted };
+    });
+    if (result.status === "unavailable") return unknown();
+    committed = result.value;
+  } catch (error) {
+    if (error instanceof SelectionRejected) return jsonResponse({ error: error.message }, error.status);
+    // Atomic publication may succeed before generation/bookkeeping fails. Confirm the exact
+    // durable selection instead of rolling live state back behind an already published write.
+    const snapshot = readConfigFileSnapshot();
+    if (snapshot.raw === undefined) return unknown();
+    try {
+      const strict = validateConfigCandidate(JSON.parse(snapshot.raw.replace(/^\uFEFF/, "")));
+      if (!strict.ok) return unknown();
+      validateSelection(config, accountId);
+      validateSelection(strict.config, accountId);
+      if (strict.config.activeCodexAccountId !== (accountId ?? undefined)
+        || strict.config.activeCodexAccountPinned !== (accountId ?? undefined)) return unknown();
+      committed = strict.config;
+      warning = true;
+    } catch { return unknown(); }
+  }
+  adoptPersistedCodexAccountSelection(config, committed);
+  recordFileBackedConfig(config, configPath);
+  // No failed save may clear affinity, spend the manual preference, or move the RR cursor.
+  resetCodexRoutingForManualSelection(accountId ?? MAIN_CODEX_ACCOUNT_ID);
+  const pinDrainReason = accountId === null ? undefined : codexAccountPinDrainReason(config, accountId);
+  return jsonResponse({
+    ok: true,
+    activeCodexAccountId: config.activeCodexAccountId ?? null,
+    appliesImmediately: true,
+    ...(pinDrainReason !== undefined ? { pinDrained: true, pinDrainReason } : {}),
+    ...(warning ? { warning: "config_bookkeeping_failed" } : {}),
+  });
+}

package/src/codex/auth-api/main-account-probe.ts

@@ -146,6 +146,11 @@ export async function fetchMainAccountInfo(forceRefresh = false, config?: OcxCon
   return (await fetchMainAccountInfoSnapshot(forceRefresh, config)).info;
 }
 
+export interface MainAccountInfoProbeOptions {
+  /** Metadata-only renewal never sets or clears the traffic reauth quarantine. */
+  passive?: boolean;
+}
+
 export const EMPTY_MAIN_ACCOUNT_INFO: MainAccountInfo = { email: null, plan: null, quota: null };
 
 export async function retryMainAccountInfoIfIdentityChanged(
@@ -154,12 +159,13 @@ export async function retryMainAccountInfoIfIdentityChanged(
   nativeMainLease: AdmissionLease,
   explicitRefresh: boolean,
   paced: boolean,
+  options: MainAccountInfoProbeOptions = {},
 ): Promise<MainAccountInfoFetchResult | null> {
   const currentAccountId = getMainChatgptAccountId();
   if (currentAccountId === null || currentAccountId === requestAccountId) return null;
   reconcileMainCodexAccountRuntimeState();
   return retriesRemaining > 0
-    ? fetchMainAccountInfoWhileOwned(true, retriesRemaining - 1, nativeMainLease, explicitRefresh, false, paced)
+    ? fetchMainAccountInfoWhileOwned(true, retriesRemaining - 1, nativeMainLease, explicitRefresh, false, paced, options)
     : { info: EMPTY_MAIN_ACCOUNT_INFO, credentialChecked: true, hasCredential: true };
 }
 
@@ -171,6 +177,7 @@ export async function fetchMainAccountInfoAttempt(
   explicitRefresh: boolean = forceRefresh,
   postReset = false,
   config?: OcxConfig,
+  options: MainAccountInfoProbeOptions = {},
 ): Promise<MainAccountInfoFetchResult> {
   const nativeMainLease = existingNativeMainLease ?? tryAcquireNativeMainProfileClaim();
   if (!nativeMainLease) {
@@ -184,7 +191,7 @@ export async function fetchMainAccountInfoAttempt(
   try {
     const paced = sharedMainQuotaPacingEnabled(config ?? loadConfig());
     const operation = async () => ({
-      ...await fetchMainAccountInfoWhileOwned(forceRefresh, retriesRemaining, nativeMainLease, explicitRefresh, postReset, paced),
+      ...await fetchMainAccountInfoWhileOwned(forceRefresh, retriesRemaining, nativeMainLease, explicitRefresh, postReset, paced, options),
       identityGeneration: captureMainAccountIdentityGeneration(),
     });
     if (nativeMainSharedClaimHeld) return await operation();
@@ -225,6 +232,7 @@ export async function fetchMainAccountInfoWhileOwned(
   /** Reset-credit consume needs a fresh post-spend observation, not an earlier read. */
   postReset = false,
   paced = true,
+  options: MainAccountInfoProbeOptions = {},
 ): Promise<MainAccountInfoFetchResult> {
   const writerGeneration = captureConfigGeneration();
   reconcileMainCodexAccountRuntimeState();
@@ -287,7 +295,16 @@ export async function fetchMainAccountInfoWhileOwned(
         const current = credentialIsCurrent() && writerGeneration === captureConfigGeneration();
         if (!current) return { info: getMainAccountInfoCache() ?? EMPTY_MAIN_ACCOUNT_INFO,
           credentialChecked: true, hasCredential: true };
-        if (explicitRefresh && (admission.result.quotaRefresh?.status === "ok"
+        // Single-flight shares evidence, but each caller retains its own auth behavior.
+        if (!options.passive && admission.result.terminalAuthFailure) {
+          const diagnosticStillLive = admission.result.quotaRefreshGeneration !== undefined
+            && isMainAccountIdentityGenerationLive(admission.result.quotaRefreshGeneration);
+          clearMainAccountInfoCache();
+          markAccountNeedsReauth(MAIN_CODEX_ACCOUNT_ID, writerGeneration);
+          return { ...admission.result, ...(diagnosticStillLive
+            ? { quotaRefreshGeneration: captureMainAccountIdentityGeneration() } : {}) };
+        }
+        if (!options.passive && explicitRefresh && (admission.result.quotaRefresh?.status === "ok"
           || admission.result.quotaRefresh?.status === "not_reported")) clearAccountNeedsReauth(MAIN_CODEX_ACCOUNT_ID);
         return admission.result;
       }
@@ -297,13 +314,13 @@ export async function fetchMainAccountInfoWhileOwned(
       if (!resp.ok) {
         const authFailure = await classifyMainAuthResponse(resp, isMainAccountTokenVerifiablyLive());
         const terminalAuthFailure = authFailure.terminal;
-        const retried = await retryMainAccountInfoIfIdentityChanged(requestAccountId, retriesRemaining, nativeMainLease, explicitRefresh, paced);
+        const retried = await retryMainAccountInfoIfIdentityChanged(requestAccountId, retriesRemaining, nativeMainLease, explicitRefresh, paced, options);
         if (retried) return retried;
         if (!isQuotaDispatchCurrent(dispatchSequence) || !credentialIsCurrent()) {
           return { info: getMainAccountInfoCache() ?? EMPTY_MAIN_ACCOUNT_INFO,
             credentialChecked: true, hasCredential: true };
         }
-        if (terminalAuthFailure) {
+        if (terminalAuthFailure && !options.passive) {
           // Account for this attempt's own synchronous invalidation, never prior external drift.
           const diagnosticStillLive = isMainAccountIdentityGenerationLive(quotaRefreshGeneration);
           clearMainAccountInfoCache();
@@ -324,7 +341,7 @@ export async function fetchMainAccountInfoWhileOwned(
       quotaPhase = "body";
       const data = (await resp.json()) as WhamUsageResponse;
       quotaPhase = "publish";
-      const retried = await retryMainAccountInfoIfIdentityChanged(requestAccountId, retriesRemaining, nativeMainLease, explicitRefresh, paced);
+      const retried = await retryMainAccountInfoIfIdentityChanged(requestAccountId, retriesRemaining, nativeMainLease, explicitRefresh, paced, options);
       if (retried) return retried;
       quotaPhase = "decode";
       if (data === null || typeof data !== "object" || Array.isArray(data)) {
@@ -376,7 +393,7 @@ export async function fetchMainAccountInfoWhileOwned(
       // never settled and the dashboard kept showing nothing — the symptom #327 reported.
       // An explicit refresh is an operator asking to re-evaluate, normally right after
       // signing in again, so it stays authoritative.
-      if (explicitRefresh) clearAccountNeedsReauth(MAIN_CODEX_ACCOUNT_ID);
+      if (explicitRefresh && !options.passive) clearAccountNeedsReauth(MAIN_CODEX_ACCOUNT_ID);
       // Mirror main quota + plan into the shared stores so the rotation engine can
       // score and auto-switch the main account exactly like a pool account (Option A).
       setMainAccountPlan(result.plan);
@@ -398,7 +415,7 @@ export async function fetchMainAccountInfoWhileOwned(
         ...(freshResetCredits !== undefined ? { freshResetCredits } : {}),
       };
     } catch (error) {
-      const retried = await retryMainAccountInfoIfIdentityChanged(requestAccountId, retriesRemaining, nativeMainLease, explicitRefresh, paced);
+      const retried = await retryMainAccountInfoIfIdentityChanged(requestAccountId, retriesRemaining, nativeMainLease, explicitRefresh, paced, options);
       if (retried) return retried;
       if (!credentialIsCurrent()) {
         return { info: getMainAccountInfoCache() ?? EMPTY_MAIN_ACCOUNT_INFO,