@bitkyc08/opencodex 2.7.40 → 2.7.41

package/src/codex/home.ts

@@ -1,7 +1,8 @@
 import { existsSync, readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
 import { homedir } from "node:os";
-import { join, posix, resolve } from "node:path";
+import { join, posix, resolve, win32 } from "node:path";
 import { expandUserPath } from "../config";
+import { redactUserPath } from "../lib/redact";
 
 export type CodexHomeDeps = {
   env?: NodeJS.ProcessEnv;
@@ -144,3 +145,62 @@ export function resolveCodexHomeDir(deps: CodexHomeDeps = {}): string {
   if (raw) return resolve(expandUserPath(raw));
   return defaultCodexHome(deps);
 }
+
+export type OrcaCodexHomeDiagnostic = {
+  applicable: boolean;
+  mismatch: boolean;
+  effectiveCodexHome: string;
+  appCodexHome: string;
+  orcaCodexHome: string | null;
+  warning: string | null;
+  action: string | null;
+};
+
+type OrcaCodexHomeDeps = CodexHomeDeps & {
+  effectiveCodexHome?: string;
+  appCodexHome?: string;
+};
+
+function normalizedWindowsPath(path: string): string {
+  return path.trim().replaceAll("/", "\\").replace(/\\+$/, "").toLowerCase();
+}
+
+/**
+ * High-confidence Orca/ChatGPT dual-home diagnosis. Explicit CODEX_HOME remains
+ * authoritative; this only explains when an Orca-owned shell targets a home the
+ * Windows ChatGPT/Codex app does not read.
+ */
+export function collectOrcaCodexHomeDiagnostic(deps: OrcaCodexHomeDeps = {}): OrcaCodexHomeDiagnostic {
+  const platform = deps.platform ?? process.platform;
+  const env = deps.env ?? process.env;
+  const effectiveCodexHome = deps.effectiveCodexHome ?? resolveCodexHomeDir(deps);
+  const appCodexHome = deps.appCodexHome
+    ?? (platform === "win32" ? win32.join((deps.homedir ?? homedir)(), ".codex") : join((deps.homedir ?? homedir)(), ".codex"));
+  const explicitHome = env.CODEX_HOME?.trim() ?? "";
+  const orcaCodexHome = env.ORCA_CODEX_HOME?.trim() || null;
+  const normalizedEffective = normalizedWindowsPath(effectiveCodexHome);
+  const normalizedOrca = orcaCodexHome ? normalizedWindowsPath(orcaCodexHome) : "";
+  const normalizedApp = normalizedWindowsPath(appCodexHome);
+  const applicable = platform === "win32"
+    && !!explicitHome
+    && !!orcaCodexHome
+    && normalizedEffective === normalizedOrca
+    && /(?:^|\\)orca\\codex-runtime-home\\home$/i.test(normalizedOrca);
+  const mismatch = applicable && normalizedEffective !== normalizedApp;
+  const displayEffective = redactUserPath(effectiveCodexHome);
+  const displayApp = redactUserPath(appCodexHome);
+  const displayOrca = orcaCodexHome ? redactUserPath(orcaCodexHome) : null;
+  return {
+    applicable,
+    mismatch,
+    effectiveCodexHome: displayEffective,
+    appCodexHome: displayApp,
+    orcaCodexHome: displayOrca,
+    warning: mismatch
+      ? `CODEX_HOME targets Orca's runtime home (${displayEffective}), while the Windows ChatGPT/Codex app uses ${displayApp}; OpenCodex injection will not reach that app.`
+      : null,
+    action: mismatch
+      ? "If a service was installed from Orca, run 'ocx service uninstall' in that original Orca shell first. Then in Command Prompt run set \"ORCA_CODEX_HOME=\" and set \"CODEX_HOME=%USERPROFILE%\\.codex\"; or in PowerShell run Remove-Item Env:ORCA_CODEX_HOME -ErrorAction SilentlyContinue; $env:CODEX_HOME = Join-Path $env:USERPROFILE '.codex'. Rerun the command, then reinstall with 'ocx service install'."
+      : null,
+  };
+}

package/src/codex/inject.ts

@@ -3,11 +3,23 @@ import { atomicWriteFile, loadConfig, websocketsEnabled } from "../config";
 import { markJournalInjectedState, removeJournal, restoreJournalState, writeJournal } from "./journal";
 import { restoreCodexCatalog } from "./catalog";
 import { migrateHistoryToOpenai, syncCodexHistoryProvider } from "./history-provider";
+import {
+  OCX_SECTION_MARKER,
+  hasInjectedCodexRouting,
+  hasInjectedOpenaiBaseUrl,
+  isRootOpenaiBaseUrlLine,
+  providerTableStart,
+  providerTableString,
+  rootTomlString,
+  tomlStringPattern,
+} from "./injected-marker";
 import { CODEX_CONFIG_PATH, CODEX_PROFILE_PATH, DEFAULT_CATALOG_PATH, parseTomlString, readRootTomlString, resolveCodexConfigPath, tomlString } from "./paths";
 import { resolveEffectiveProjectModelProvider } from "./project-config-warnings";
 import type { OcxConfig } from "../types";
 
-const OCX_SECTION_MARKER = "# Auto-injected by opencodex";
+// Ownership predicates live in `./injected-marker` so `journal.ts` can reach them
+// without importing this module back. Re-exported for existing external callers.
+export { hasInjectedCodexRouting, hasInjectedOpenaiBaseUrl };
 
 export function externalCodexModelProvider(content: string): string | null {
   const provider = resolveEffectiveProjectModelProvider(content).provider;
@@ -64,12 +76,18 @@ export interface InjectCodexOptions {
  * whatever `[table]` happened to be open last (e.g. `[plugins."chrome@openai-bundled"]`), so Codex
  * never saw a global model_provider and silently fell back to the `openai` (ChatGPT) provider.
  */
-function isLoopbackHostname(hostname: string | undefined): boolean {
+/**
+ * True only for hostnames that bind loopback ONLY. Wildcard binds ("0.0.0.0", "::") are NOT
+ * loopback: they expose the proxy on every interface and therefore require the admission token.
+ * Do not use `providerBaseHost` for this decision — it folds wildcards to 127.0.0.1 because it
+ * answers "what address do I dial", which is a different question from "is this exposed".
+ */
+export function isLoopbackHostname(hostname: string | undefined): boolean {
   const normalized = (hostname ?? "127.0.0.1").trim().toLowerCase();
   return normalized === "" || normalized === "localhost" || normalized === "127.0.0.1" || normalized === "::1" || normalized === "[::1]";
 }
 
-function providerBaseHost(hostname: string | undefined): string {
+export function providerBaseHost(hostname: string | undefined): string {
   const trimmed = (hostname ?? "127.0.0.1").trim();
   const lower = trimmed.toLowerCase();
   // Match what the server actually binds. Writing "localhost" while binding IPv4-only
@@ -106,10 +124,6 @@ export function buildOpenaiBaseUrlLine(port: number, hostname?: string): string
   return `openai_base_url = "http://${providerBaseHost(hostname)}:${port}/v1"`;
 }
 
-function isRootOpenaiBaseUrlLine(line: string): boolean {
-  return /^\s*openai_base_url\s*=/.test(line);
-}
-
 /**
  * Design B root-key injection: place `OCX_SECTION_MARKER` + `openai_base_url` at the document
  * ROOT (before the first table header). Idempotent: an existing marker-owned line is rewritten
@@ -162,55 +176,8 @@ export function stripInjectedOpenaiBaseUrl(content: string): string {
   return lines.filter((_, i) => !drop.has(i)).join("\n");
 }
 
-export function hasInjectedOpenaiBaseUrl(content: string): boolean {
-  const lines = content.split("\n");
-  const firstTable = lines.findIndex(l => /^\s*\[/.test(l));
-  const rootEnd = firstTable === -1 ? lines.length : firstTable;
-  for (let i = 1; i < rootEnd; i++) {
-    if (isRootOpenaiBaseUrlLine(lines[i]) && lines[i - 1].includes(OCX_SECTION_MARKER)) return true;
-  }
-  return false;
-}
-
 export type CodexRoutingKind = "native" | "opencodex-local" | "custom-local" | "custom-remote" | "unknown";
 
-function tomlStringPattern(key: string): RegExp {
-  const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-  const keyToken = `(?:${escaped}|\"${escaped}\"|'${escaped}')`;
-  return new RegExp(`^\\s*${keyToken}\\s*=\\s*[\"']([^\"']+)[\"']\\s*(?:#.*)?$`);
-}
-
-function rootTomlString(content: string, key: string): string | null {
-  const lines = content.split("\n");
-  const firstTable = lines.findIndex(line => /^\s*\[/.test(line));
-  const rootLines = lines.slice(0, firstTable === -1 ? lines.length : firstTable);
-  const pattern = tomlStringPattern(key);
-  for (const line of rootLines) {
-    const match = pattern.exec(line);
-    if (match?.[1]) return match[1].trim();
-  }
-  return null;
-}
-
-function providerTableStart(lines: string[], provider: string): number {
-  const escapedProvider = provider.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-  const providerToken = `(?:${escapedProvider}|\"${escapedProvider}\"|'${escapedProvider}')`;
-  const header = new RegExp(`^\\s*\\[\\s*(?:model_providers|\"model_providers\"|'model_providers')\\s*\\.\\s*${providerToken}\\s*\\]\\s*(?:#.*)?$`);
-  return lines.findIndex(line => header.test(line));
-}
-
-function providerTableString(content: string, provider: string, key: string): string | null {
-  const lines = content.split("\n");
-  const start = providerTableStart(lines, provider);
-  if (start === -1) return null;
-  const pattern = tomlStringPattern(key);
-  for (let index = start + 1; index < lines.length && !/^\s*\[/.test(lines[index]); index += 1) {
-    const match = pattern.exec(lines[index]);
-    if (match?.[1]) return match[1].trim();
-  }
-  return null;
-}
-
 type RoutingEndpointKind = "local" | "remote" | "unknown";
 
 function ipv4Octets(hostname: string): number[] | null {
@@ -271,17 +238,6 @@ export function classifyCodexRouting(content: string): CodexRoutingKind {
   return "native";
 }
 
-/**
- * True when the active Codex config is owned by opencodex routing. Covers the
- * loopback Design B root override and the legacy/non-loopback provider table.
- * A user-owned `openai_base_url` is intentionally not classified as injected.
- */
-export function hasInjectedCodexRouting(content: string): boolean {
-  if (hasInjectedOpenaiBaseUrl(content)) return true;
-  return rootTomlString(content, "model_provider") === "opencodex"
-    && providerTableString(content, "opencodex", "base_url") !== null;
-}
-
 /** Read-only probe used by status, doctor, and the dashboard. */
 export function isCodexRoutingInjected(): boolean {
   const path = CODEX_CONFIG_PATH;
@@ -523,7 +479,13 @@ export async function injectCodexConfig(port: number, config?: OcxConfig, option
     };
   }
 
-  writeJournal();
+  // Classify and journal the same bytes: a native config is a valid original and
+  // supersedes a stale snapshot (#477), while an injected one must never become
+  // one — that is how opencodex routing would survive `ocx stop`.
+  writeJournal({
+    currentStateIsNative: !hasInjectedCodexRouting(rawContent),
+    configContent: rawContent,
+  });
   // EOL boundary: transforms below are LF-pure; preserve the file's dominant ending on write.
   const eol = dominantEol(rawContent);
   let content = applyEol(rawContent, "\n");

package/src/codex/injected-marker.ts

@@ -0,0 +1,72 @@
+/**
+ * Ownership predicates for `~/.codex/config.toml`: does opencodex own the routing
+ * currently written there?
+ *
+ * These live in their own leaf module rather than in `inject.ts` because
+ * `journal.ts` needs them and `inject.ts` already imports `journal.ts`. Keeping
+ * them here breaks that cycle. `inject.ts` imports them back and re-exports the
+ * two public predicates, so external callers see no change.
+ */
+export const OCX_SECTION_MARKER = "# Auto-injected by opencodex";
+
+export function isRootOpenaiBaseUrlLine(line: string): boolean {
+  return /^\s*openai_base_url\s*=/.test(line);
+}
+
+export function tomlStringPattern(key: string): RegExp {
+  const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const keyToken = `(?:${escaped}|"${escaped}"|'${escaped}')`;
+  return new RegExp(`^\\s*${keyToken}\\s*=\\s*["']([^"']+)["']\\s*(?:#.*)?$`);
+}
+
+export function rootTomlString(content: string, key: string): string | null {
+  const lines = content.split("\n");
+  const firstTable = lines.findIndex(line => /^\s*\[/.test(line));
+  const rootLines = lines.slice(0, firstTable === -1 ? lines.length : firstTable);
+  const pattern = tomlStringPattern(key);
+  for (const line of rootLines) {
+    const match = pattern.exec(line);
+    if (match?.[1]) return match[1].trim();
+  }
+  return null;
+}
+
+export function providerTableStart(lines: string[], provider: string): number {
+  const escapedProvider = provider.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const providerToken = `(?:${escapedProvider}|"${escapedProvider}"|'${escapedProvider}')`;
+  const header = new RegExp(`^\\s*\\[\\s*(?:model_providers|"model_providers"|'model_providers')\\s*\\.\\s*${providerToken}\\s*\\]\\s*(?:#.*)?$`);
+  return lines.findIndex(line => header.test(line));
+}
+
+export function providerTableString(content: string, provider: string, key: string): string | null {
+  const lines = content.split("\n");
+  const start = providerTableStart(lines, provider);
+  if (start === -1) return null;
+  const pattern = tomlStringPattern(key);
+  for (let index = start + 1; index < lines.length && !/^\s*\[/.test(lines[index]); index += 1) {
+    const match = pattern.exec(lines[index]);
+    if (match?.[1]) return match[1].trim();
+  }
+  return null;
+}
+
+export function hasInjectedOpenaiBaseUrl(content: string): boolean {
+  const lines = content.split("\n");
+  const firstTable = lines.findIndex(l => /^\s*\[/.test(l));
+  const rootEnd = firstTable === -1 ? lines.length : firstTable;
+  for (let i = 1; i < rootEnd; i++) {
+    if (isRootOpenaiBaseUrlLine(lines[i]!) && lines[i - 1]!.includes(OCX_SECTION_MARKER)) return true;
+  }
+  return false;
+}
+
+/**
+ * True when the active Codex config is owned by opencodex routing. Covers the
+ * loopback Design B root override and the legacy/non-loopback provider table.
+ * A user-owned `openai_base_url` is intentionally not classified as injected.
+ */
+export function hasInjectedCodexRouting(content: string): boolean {
+  if (hasInjectedOpenaiBaseUrl(content)) return true;
+  return rootTomlString(content, "model_provider") === "opencodex"
+    && providerTableString(content, "opencodex", "base_url") !== null;
+}

package/src/codex/journal.ts

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import { existsSync, readFileSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 import { atomicWriteFile } from "../config";
+import { hasInjectedCodexRouting } from "./injected-marker";
 import { CODEX_HOME, CODEX_CONFIG_PATH, CODEX_PROFILE_PATH } from "./paths";
 
 const JOURNAL_PATH = join(CODEX_HOME, "opencodex-journal.json");
@@ -28,10 +29,45 @@ function sha256(content: string | null): string | null {
   return content === null ? null : createHash("sha256").update(content).digest("hex");
 }
 
-export function writeJournal(): void {
-  if (existsSync(JOURNAL_PATH) && readJournal()) return;
+export interface WriteJournalOptions {
+  /**
+   * The caller's verdict on the config it is about to transform: false when
+   * `hasInjectedCodexRouting` matched. This does NOT decide whether the content
+   * may be journaled — that is checked below, from the bytes themselves. It only
+   * authorizes REPLACING an existing snapshot, which is why omitting it still
+   * allows a first snapshot but never an overwrite.
+   */
+  currentStateIsNative?: boolean;
+  /**
+   * The exact bytes the caller classified. Journaling these rather than re-reading
+   * the file keeps the snapshot and the verdict describing the same content when
+   * another process rewrites config.toml mid-flight.
+   */
+  configContent?: string;
+}
+
+/**
+ * Snapshot the pre-injection Codex state.
+ *
+ * Only native (non-opencodex-owned) config may be journaled, and native config
+ * always supersedes an older snapshot. The first half stops a re-inject from
+ * recording opencodex's own routing as the user's original — which would survive
+ * `ocx stop` and make the injection unremovable. The second half is the #477 fix:
+ * without it the first snapshot a machine ever takes is the only one it ever has,
+ * so an unclean shutdown days later replays a day-one config over the user's
+ * plugins, model choice, and trusted projects.
+ */
+export function writeJournal(options: WriteJournalOptions = {}): void {
   if (!existsSync(CODEX_CONFIG_PATH)) return;
-  const config = readFileSync(CODEX_CONFIG_PATH, "utf-8");
+  const config = options.configContent ?? readFileSync(CODEX_CONFIG_PATH, "utf-8");
+  // Ownership is decided HERE, from the bytes about to be journaled — never taken
+  // on the caller's word. A caller that says "native" about injected content would
+  // otherwise make opencodex's own routing the user's permanent "original".
+  if (hasInjectedCodexRouting(config)) return;
+  // The caller's verdict only authorizes REPLACEMENT. It is weaker evidence than
+  // the check above (it may describe bytes read a moment earlier), so an
+  // unclassified call creates a first snapshot but never overwrites one.
+  if (existsSync(JOURNAL_PATH) && readJournal() && options.currentStateIsNative !== true) return;
   const profile = existsSync(CODEX_PROFILE_PATH)
     ? readFileSync(CODEX_PROFILE_PATH, "utf-8")
     : null;

package/src/codex/main-account-cache.ts

@@ -0,0 +1,25 @@
+import type { StoredAccountQuota } from "./quota";
+
+export interface MainAccountInfo {
+  email: string | null;
+  plan: string | null;
+  quota: Omit<StoredAccountQuota, "updatedAt"> | null;
+}
+
+export interface CachedMainAccountInfo extends MainAccountInfo {
+  ts: number;
+}
+
+let cachedMainAccountInfo: CachedMainAccountInfo | null = null;
+
+export function getMainAccountInfoCache(): CachedMainAccountInfo | null {
+  return cachedMainAccountInfo;
+}
+
+export function setMainAccountInfoCache(value: CachedMainAccountInfo): void {
+  cachedMainAccountInfo = value;
+}
+
+export function clearMainAccountInfoCache(): void {
+  cachedMainAccountInfo = null;
+}

package/src/codex/model-cache.ts

@@ -47,13 +47,23 @@ export const MODELS_FETCH_FAILURE_COOLDOWN_MS = 30_000;
 
 const failureAt = new Map<string, number>();
 const discoveryStatus = new Map<string, ProviderModelDiscoveryStatus>();
+/**
+ * How many models the last successful discovery actually returned, before any configured-alias
+ * augmentation or custom-model merge. Consumers cannot recover this by subtracting known custom
+ * ids: a custom id that later also appears upstream would make a real live catalog look
+ * custom-only, and the provider's configured fallback would wrongly stay authoritative.
+ */
+const liveModelCounts = new Map<string, number>();
 
 export function markModelsFetchFailure(provider: string, now = Date.now()): void {
   failureAt.set(provider, now);
 }
 
-export function markProviderDiscoveryOk(provider: string): void {
+/** `liveModelCount` is required so a caller that forgets to pass it fails typecheck instead of
+ * silently recording zero and misclassifying the provider as having no live catalog. */
+export function markProviderDiscoveryOk(provider: string, liveModelCount: number): void {
   discoveryStatus.set(provider, { status: "ok" });
+  liveModelCounts.set(provider, Math.max(0, Math.floor(liveModelCount)));
 }
 
 export function markProviderDiscoveryFailed(
@@ -88,12 +98,19 @@ export function shouldLogDiscoveryFailure(
 
 export function clearProviderDiscoveryStatus(provider: string): void {
   discoveryStatus.delete(provider);
+  liveModelCounts.delete(provider);
 }
 
 export function getProviderDiscoveryStatus(provider: string): ProviderModelDiscoveryStatus | undefined {
   return discoveryStatus.get(provider);
 }
 
+/** Undefined when discovery has never succeeded for this provider. A failed refresh keeps the
+ * last successful count so a stale catalog is still recognised as live-origin. */
+export function getProviderLiveModelCount(provider: string): number | undefined {
+  return liveModelCounts.get(provider);
+}
+
 export function isModelsFetchCoolingDown(provider: string, cooldownMs = MODELS_FETCH_FAILURE_COOLDOWN_MS, now = Date.now()): boolean {
   const at = failureAt.get(provider);
   return at !== undefined && now - at < cooldownMs;
@@ -121,9 +138,11 @@ export function clearModelCache(provider?: string): void {
     cache.delete(provider);
     failureAt.delete(provider);
     discoveryStatus.delete(provider);
+    liveModelCounts.delete(provider);
   } else {
     cache.clear();
     failureAt.clear();
     discoveryStatus.clear();
+    liveModelCounts.clear();
   }
 }

package/src/codex/paths.ts

@@ -29,6 +29,11 @@ export const CODEX_PROFILE_PATH = join(CODEX_HOME, "opencodex.config.toml");
 export const DEFAULT_CATALOG_PATH = join(CODEX_HOME, "opencodex-catalog.json");
 export const CODEX_MODELS_CACHE_PATH = join(CODEX_HOME, "models_cache.json");
 
+/** Runtime CODEX_HOME lookup (honors CODEX_HOME env changes after import). */
+export function getCodexHome(): string {
+  return resolveCodexHome();
+}
+
 export function tomlString(value: string): string {
   return JSON.stringify(value);
 }

package/src/codex/routing.ts

@@ -1,5 +1,5 @@
 import { randomUUID } from "node:crypto";
-import { saveConfig } from "../config";
+import { saveConfigPreservingClaudeCode } from "../config";
 import { isCodexAccountGenerationLive, readCodexAccountRecord } from "./account-store";
 import { codexAccountLogLabel } from "./account-label";
 import { isCodexAccountUsable } from "./account-usability";
@@ -235,14 +235,8 @@ export function computeQuotaCooldownUntil(meta: CodexUpstreamOutcomeMeta = {}):
  * Returns the lease id, or null when no probe may go out right now.
  */
 export function tryAcquireCodexQuotaProbeLease(accountId: string, now = Date.now()): string | null {
-  const health = upstreamHealth.get(accountId);
-  if (!health) return null;
-  const cooldownUntil = health.cooldownUntil;
-  if (typeof cooldownUntil !== "number" || !Number.isFinite(cooldownUntil) || cooldownUntil <= now) return null;
-  if (health.cooldownSource === "retry-after") return null;
-  if (health.probeLeaseId !== undefined) return null;
-  const origin = health.lastProbeAt ?? health.cooldownSince ?? cooldownUntil;
-  if (now - origin < CODEX_QUOTA_PROBE_INTERVAL_MS) return null;
+  if (!canAcquireCodexQuotaProbeLease(accountId, now)) return null;
+  const health = upstreamHealth.get(accountId)!;
   const probeLeaseId = randomUUID();
   upstreamHealth.set(accountId, {
     ...health,
@@ -253,6 +247,18 @@ export function tryAcquireCodexQuotaProbeLease(accountId: string, now = Date.now
   return probeLeaseId;
 }
 
+/** Side-effect-free check mirroring {@link tryAcquireCodexQuotaProbeLease} eligibility. */
+export function canAcquireCodexQuotaProbeLease(accountId: string, now = Date.now()): boolean {
+  const health = upstreamHealth.get(accountId);
+  if (!health) return false;
+  const cooldownUntil = health.cooldownUntil;
+  if (typeof cooldownUntil !== "number" || !Number.isFinite(cooldownUntil) || cooldownUntil <= now) return false;
+  if (health.cooldownSource === "retry-after") return false;
+  if (health.probeLeaseId !== undefined) return false;
+  const origin = health.lastProbeAt ?? health.cooldownSince ?? cooldownUntil;
+  return now - origin >= CODEX_QUOTA_PROBE_INTERVAL_MS;
+}
+
 /**
  * Hand a probe lease back without recording an upstream outcome. Used by paths
  * that take a lease and then fail before any request reaches upstream.
@@ -304,10 +310,63 @@ export function getCodexAccountCooldownUntil(accountId: string, now = Date.now()
   return typeof cooldownUntil === "number" && Number.isFinite(cooldownUntil) && cooldownUntil > now ? cooldownUntil : null;
 }
 
+/** Read-only cooldown snapshot for shared OAuth health projection (no write side effects). */
+export function getCodexAccountHealthSnapshot(accountId: string, now = Date.now()): {
+  cooldownUntil?: number;
+  cooldownSource?: CodexCooldownSource;
+} | null {
+  const cooldownUntil = getCodexAccountCooldownUntil(accountId, now);
+  if (cooldownUntil === null) return null;
+  const source = upstreamHealth.get(accountId)?.cooldownSource;
+  return {
+    cooldownUntil,
+    ...(source ? { cooldownSource: source } : {}),
+  };
+}
+
 export function isCodexAccountInCooldown(accountId: string, now = Date.now()): boolean {
   return getCodexAccountCooldownUntil(accountId, now) !== null;
 }
 
+/**
+ * Manually lift a hard quota cooldown without touching failure history.
+ *
+ * Injected Codex routing makes this proxy the ONLY model path for Codex Desktop, so a
+ * cooldown that outlives the real upstream limit reads to the user as "the whole app is
+ * broken" with no escape but editing config.toml. This is that escape hatch.
+ *
+ * Deliberately narrow:
+ * - Failure counters and softAvoid survive. Clearing a cooldown says "the quota window
+ *   moved", not "this account is healthy"; failover must keep its knowledge.
+ * - Dropping `probeLeaseId` is what stops a stale in-flight probe from later "proving"
+ *   recovery against a NEWER cooldown: {@link ownsProbeLease} needs the id to match.
+ *   `cooldownGeneration` is preserved and bumped as redundancy only — a fresh 429 already
+ *   bumps it in {@link recordCodexUpstreamOutcome}, so the bump here is not load-bearing
+ *   today and is kept so the invariant survives a future change that retains the lease.
+ *
+ * Returns false when the account carried no live cooldown (already expired or never set).
+ */
+export function clearCodexAccountCooldown(accountId: string, now = Date.now()): boolean {
+  const health = upstreamHealth.get(accountId);
+  if (!health) return false;
+  const cooldownUntil = health.cooldownUntil;
+  if (typeof cooldownUntil !== "number" || !Number.isFinite(cooldownUntil) || cooldownUntil <= now) return false;
+  const {
+    cooldownUntil: _until,
+    cooldownSince: _since,
+    cooldownSource: _source,
+    probeLeaseId: _leaseId,
+    probeLeaseGeneration: _leaseGeneration,
+    ...rest
+  } = health;
+  upstreamHealth.set(accountId, {
+    ...rest,
+    cooldownGeneration: (health.cooldownGeneration ?? 0) + 1,
+    lastProbeAt: now,
+  });
+  return true;
+}
+
 export function getCodexAccountSoftAvoidUntil(accountId: string, now = Date.now()): number | null {
   const softAvoidUntil = upstreamHealth.get(accountId)?.softAvoidUntil;
   return typeof softAvoidUntil === "number" && Number.isFinite(softAvoidUntil) && softAvoidUntil > now
@@ -391,7 +450,7 @@ function getEligiblePoolAccounts(config: OcxConfig, excludeId?: string, now = Da
   return ids;
 }
 
-function getPoolAccountPlan(config: OcxConfig, accountId: string): string | undefined {
+export function getPoolAccountPlan(config: OcxConfig, accountId: string): string | undefined {
   if (accountId === MAIN_CODEX_ACCOUNT_ID) return getMainAccountPlan();
   return (config.codexAccounts ?? []).find(account => !account.isMain && account.id === accountId)?.plan;
 }
@@ -425,7 +484,7 @@ export function pickLowestUsageCodexAccount(config: OcxConfig, excludeId?: strin
 function setActiveCodexAccount(config: OcxConfig, accountId: string): void {
   if (config.activeCodexAccountId === accountId) return;
   config.activeCodexAccountId = accountId;
-  saveConfig(config);
+  saveConfigPreservingClaudeCode(config);
 }
 
 function isUnknownUsage(usage: number): boolean {
@@ -499,6 +558,74 @@ export function resolveCodexAccountForThread(
   return resolution.status === "selected" ? resolution.accountId : null;
 }
 
+/**
+ * Side-effect-free preview of the Codex pool account native routing would prefer.
+ * Used for subagent fallback quota decisions before final auth.
+ *
+ * Does not mutate activeCodexAccountId, thread affinity, config on disk, or probe leases.
+ * Mirrors {@link resolveCodexAccountForThreadDetailed} account choice, including returning a
+ * configured cooled account so callers can evaluate probe/quota availability.
+ */
+export function previewCodexAccountForRequest(
+  threadId: string | null,
+  config: OcxConfig,
+  now = Date.now(),
+): string | null {
+  if (threadId && threadAccountMap.has(threadId)) {
+    const entry = threadAccountMap.get(threadId)!;
+    if (
+      !isThreadAffinityExpired(entry, now)
+      && isThreadAffinityGenerationLive(entry)
+      && isCodexAccountSelectable(config, entry.accountId, now)
+      && !shouldFailover(config, entry.accountId, now)
+    ) {
+      const threshold = config.autoSwitchThreshold ?? 80;
+      if (threshold > 0) {
+        const usage = computeCodexUsageScore(
+          getAccountQuota(entry.accountId),
+          getPoolAccountPlan(config, entry.accountId),
+        );
+        if (usage >= threshold) {
+          const best = pickLowerUsageAccount(config, entry.accountId, usage, now);
+          if (best !== entry.accountId) return best;
+        }
+      }
+      return entry.accountId;
+    }
+    // Stale/unusable affinity is ignored for preview (no map mutation).
+  }
+
+  let active = config.activeCodexAccountId ?? null;
+  if (!active) {
+    return pickLowestUsageCodexAccount(config, undefined, now);
+  }
+  if (!isCodexAccountSelectable(config, active, now)) {
+    const fallback = pickLowestUsageCodexAccount(config, active, now);
+    if (fallback) active = fallback;
+    else if (hasConfiguredPoolAccount(config, active)) return active;
+    else return null;
+  }
+
+  const threshold = config.autoSwitchThreshold ?? 80;
+  if (threshold > 0) {
+    const usage = computeCodexUsageScore(getAccountQuota(active), getPoolAccountPlan(config, active));
+    if (usage >= threshold) {
+      active = pickLowerUsageAccount(config, active, usage, now);
+    }
+  }
+  if (shouldFailover(config, active, now)) {
+    const best = pickLowestUsageCodexAccount(config, active, now);
+    if (best) active = best;
+  }
+  if (!isCodexAccountUsable(config, active)) {
+    return hasConfiguredPoolAccount(config, active) ? active : null;
+  }
+  if (isCodexAccountInCooldown(active, now)) {
+    return hasConfiguredPoolAccount(config, active) ? active : null;
+  }
+  return active;
+}
+
 export function resolveCodexAccountForThreadDetailed(
   threadId: string | null,
   config: OcxConfig,