codex-multi-auth 2.1.13-beta.2 → 2.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "codex-multi-auth",
-	"version": "2.1.13-beta.2",
+	"version": "2.2.1",
 	"description": "Codex CLI multi-account OAuth manager with account switching, health checks, runtime rotation, diagnostics, and recovery tools for @openai/codex",
 	"main": "./dist/index.js",
 	"types": "./dist/index.d.ts",
@@ -114,11 +114,13 @@
 		"prepare": "husky"
 	},
 	"bin": {
+		"mcodex": "scripts/mcodex.js",
 		"codex-multi-auth-codex": "scripts/codex.js",
 		"codex-multi-auth-app-launcher": "scripts/codex-app-launcher.js",
 		"codex-multi-auth": "scripts/codex-multi-auth.js"
 	},
 	"files": [
+		".codex-plugin/plugin.json",
 		"dist/",
 		"assets/",
 		"config/",
@@ -128,6 +130,7 @@
 		"scripts/codex-bin-resolver.js",
 		"scripts/codex-multi-auth.js",
 		"scripts/codex-routing.js",
+		"scripts/mcodex.js",
 		"scripts/install-codex-auth-utils.js",
 		"scripts/postinstall.js",
 		"scripts/preuninstall.js",
@@ -137,7 +140,8 @@
 		"LICENSE"
 	],
 	"bundleDependencies": [
-		"@codex-ai/plugin"
+		"@codex-ai/plugin",
+		"@codex-ai/sdk"
 	],
 	"lint-staged": {
 		"*.ts": [
@@ -154,23 +158,23 @@
 		"typescript": "^5"
 	},
 	"devDependencies": {
-		"@codex-ai/sdk": "file:vendor/codex-ai-sdk",
 		"@fast-check/vitest": "^0.2.4",
 		"@types/node": "^25.3.0",
 		"@typescript-eslint/eslint-plugin": "^8.56.0",
 		"@typescript-eslint/parser": "^8.56.0",
-		"@vitest/coverage-v8": "^4.0.18",
-		"@vitest/ui": "^4.0.18",
+		"@vitest/coverage-v8": "^4.1.8",
+		"@vitest/ui": "^4.1.8",
 		"eslint": "^10.0.0",
 		"fast-check": "^4.5.3",
 		"husky": "^9.1.7",
 		"lint-staged": "^16.2.7",
 		"typescript": "^5.9.3",
 		"typescript-language-server": "^5.1.3",
-		"vitest": "^4.0.18"
+		"vitest": "^4.1.8"
 	},
 	"dependencies": {
 		"@codex-ai/plugin": "file:vendor/codex-ai-plugin",
+		"@codex-ai/sdk": "file:vendor/codex-ai-sdk",
 		"@openauthjs/openauth": "^0.4.3",
 		"hono": "4.12.18",
 		"undici": "6.25.0",

package/scripts/codex-bin-resolver.js

@@ -1,7 +1,7 @@
 import { spawnSync } from "node:child_process";
 import { existsSync, realpathSync } from "node:fs";
 import { createRequire } from "node:module";
-import { basename, delimiter, dirname, extname, join } from "node:path";
+import { basename, delimiter, dirname, extname, isAbsolute, join, relative } from "node:path";
 import process from "node:process";
 import { fileURLToPath } from "node:url";
 
@@ -25,6 +25,21 @@ function normalizeResolvedPath(candidatePath, realpathSyncImpl) {
 	}
 }
 
+// Defense-in-depth self-recursion guard. The exact-realpath check only blocks
+// the wrapper's own codex.js (the POSIX symlink case). If the wrapper were ever
+// exposed as a native codex/codex.exe sitting alongside it, that exact-path
+// check would miss it. Skipping any candidate that resolves inside the
+// wrapper's own directory closes that latent self-loop.
+function isWithinDirectory(candidatePath, directoryPath, realpathSyncImpl) {
+	if (!directoryPath) return false;
+	const resolvedCandidate = normalizeResolvedPath(candidatePath, realpathSyncImpl);
+	const relativePath = relative(directoryPath, resolvedCandidate);
+	return (
+		relativePath === "" ||
+		(!relativePath.startsWith("..") && !isAbsolute(relativePath))
+	);
+}
+
 function resolveWrapperScriptPath(moduleUrl, realpathSyncImpl) {
 	return normalizeResolvedPath(fileURLToPath(moduleUrl), realpathSyncImpl);
 }
@@ -92,6 +107,12 @@ function resolveCodexExecutableFromPath(
 			) {
 				continue;
 			}
+			if (
+				selfScriptPath &&
+				isWithinDirectory(candidate, dirname(selfScriptPath), realpathSyncImpl)
+			) {
+				continue;
+			}
 			return candidate;
 		}
 	}
@@ -154,6 +175,12 @@ function resolveCodexExecutableFromSystemPath(
 			) {
 				continue;
 			}
+			if (
+				selfScriptPath &&
+				isWithinDirectory(candidate, dirname(selfScriptPath), realpathSyncImpl)
+			) {
+				continue;
+			}
 			const fileName = basename(candidate).toLowerCase();
 			if (fileName === "codex" || fileName === "codex.exe") {
 				return candidate;

package/scripts/codex-routing.js

@@ -3,6 +3,8 @@ const AUTH_SUBCOMMANDS = new Set([
 	"list",
 	"status",
 	"switch",
+	"unpin",
+	"workspace",
 	"best",
 	"check",
 	"features",
@@ -13,6 +15,7 @@ const AUTH_SUBCOMMANDS = new Set([
 	"report",
 	"fix",
 	"doctor",
+	"uninstall",
 	"account",
 	"budget",
 	"bridge",

package/scripts/codex.js

@@ -18,9 +18,10 @@ import {
 	symlinkSync,
 	writeFileSync,
 } from "node:fs";
+import { rm as rmAsync } from "node:fs/promises";
 import { createRequire } from "node:module";
 import { homedir, tmpdir } from "node:os";
-import { basename, delimiter, dirname, join, resolve as resolvePath } from "node:path";
+import { basename, delimiter, dirname, join, resolve as resolvePath, sep } from "node:path";
 import process from "node:process";
 import { StringDecoder } from "node:string_decoder";
 import { fileURLToPath, pathToFileURL } from "node:url";
@@ -81,6 +82,9 @@ const APP_RUNTIME_HELPER_LAUNCH_TIMEOUT_MS = 15_000;
 const APP_SERVER_SHIM_DIR_NAME = "app-server-shims";
 const APP_SERVER_SHIM_HELPER_PREFIX = "helper-";
 const DEFAULT_STARTUP_UPDATE_NOTICE_BUDGET_MS = 3_000;
+const DEFAULT_STATUS_QUOTA_REFRESH_INTERVAL_MS = 10 * 60 * 1000;
+const STATUS_QUOTA_REFRESH_LOCK_STALE_MS = 10 * 60 * 1000;
+const STATUS_QUOTA_REFRESH_LOCK_DIR = "status-quota-refresh.lock";
 const STARTUP_UPDATE_NOTICE_TIMED_OUT = Symbol("startup-update-notice-timed-out");
 let shadowHomeCleanupBusyFailuresRemaining = Number.parseInt(
 	process.env.CODEX_MULTI_AUTH_TEST_SHADOW_CLEANUP_BUSY_FAILURES ?? "0",
@@ -163,6 +167,28 @@ function removeDirectoryWithRetry(targetPath) {
 	}
 }
 
+/**
+ * Best-effort async directory removal for hot-path callbacks (e.g. the
+ * status-refresh child's close/error handlers, which fire on the PARENT event
+ * loop while Codex is running). Unlike removeDirectoryWithRetry this never calls
+ * the Atomics.wait-backed sleepSync, so a retryable Windows lock (EBUSY/EPERM/
+ * ENOTEMPTY) can't stall the event loop for up to ~200ms. fsPromises.rm has its
+ * own internal retry (maxRetries) and yields between attempts. On persistent
+ * failure we give up silently — the 10-minute stale-lock recovery reclaims it.
+ */
+async function removeDirectoryBestEffortAsync(targetPath) {
+	try {
+		await rmAsync(targetPath, {
+			recursive: true,
+			force: true,
+			maxRetries: 3,
+			retryDelay: 20,
+		});
+	} catch {
+		// Best-effort; stale-lock recovery handles any leftover.
+	}
+}
+
 function hydrateCliVersionEnv() {
 	try {
 		const require = createRequire(import.meta.url);
@@ -176,6 +202,485 @@ function hydrateCliVersionEnv() {
 	}
 }
 
+function readJsonFileQuiet(path) {
+	try {
+		if (!existsSync(path)) return null;
+		return JSON.parse(readFileSync(path, "utf8"));
+	} catch {
+		return null;
+	}
+}
+
+function resolveMultiAuthDirFromEnv(env = process.env) {
+	const configured = (env.CODEX_MULTI_AUTH_DIR ?? "").trim();
+	if (configured.length > 0) return configured;
+	return join(resolveCodexHomeDir(env), "multi-auth");
+}
+
+function resolveAccountsPath(env = process.env, dir = resolveMultiAuthDirFromEnv(env)) {
+	return join(dir, "openai-codex-accounts.json");
+}
+
+function resolveQuotaCachePath(env = process.env, dir = resolveMultiAuthDirFromEnv(env)) {
+	return join(dir, "quota-cache.json");
+}
+
+function resolveRuntimeObservabilityPath(env = process.env, dir = resolveMultiAuthDirFromEnv(env)) {
+	return join(dir, "runtime-observability.json");
+}
+
+/**
+ * Resolve the multi-auth dir the status line should read ACCOUNTS from, mirroring
+ * the runtime's own account scoping (lib/runtime/account-scope.ts):
+ *   - when perProjectAccounts is enabled, Codex CLI sync is OFF, an explicit
+ *     CODEX_MULTI_AUTH_DIR is NOT set, and the cwd resolves to a git/project root,
+ *     accounts live in the per-project pool at
+ *     <configDir>/projects/<project-key>/openai-codex-accounts.json;
+ *   - otherwise the global dir is used.
+ * Only the ACCOUNTS pool is per-project; quota-cache.json and
+ * runtime-observability.json remain global (lib: getCodexMultiAuthDir). Reusing
+ * the built dist helpers (never re-deriving project keys from raw paths, per
+ * AGENTS.md) keeps the status line consistent with what Codex routes through.
+ * Any failure falls back to the global dir so the launcher never breaks.
+ */
+async function resolveStatusAccountsDir(env = process.env) {
+	const globalDir = resolveMultiAuthDirFromEnv(env);
+	try {
+		const [configMod, pathsMod, stateMod] = await Promise.all([
+			import("../dist/lib/config.js"),
+			import("../dist/lib/storage/paths.js"),
+			import("../dist/lib/codex-cli/state.js"),
+		]);
+		if (
+			typeof configMod.loadPluginConfig !== "function" ||
+			typeof configMod.getPerProjectAccounts !== "function" ||
+			typeof pathsMod.findProjectRoot !== "function" ||
+			typeof pathsMod.resolveProjectStorageIdentityRoot !== "function" ||
+			typeof pathsMod.getProjectGlobalConfigDir !== "function"
+		) {
+			return globalDir;
+		}
+		const pluginConfig = configMod.loadPluginConfig();
+		if (configMod.getPerProjectAccounts(pluginConfig) !== true) return globalDir;
+		// Codex CLI sync forces the global pool (account-scope.ts), so honor that.
+		if (typeof stateMod.isCodexCliSyncEnabled === "function" && stateMod.isCodexCliSyncEnabled()) {
+			return globalDir;
+		}
+		const projectRoot = pathsMod.findProjectRoot(process.cwd());
+		if (!projectRoot) return globalDir;
+		// getProjectGlobalConfigDir grounds the per-project pool in the dist config
+		// dir, which itself honors CODEX_MULTI_AUTH_DIR / CODEX_HOME — so the pool is
+		// nested under an explicit dir exactly as the runtime writes it. No special
+		// casing of CODEX_MULTI_AUTH_DIR here, or the status line would diverge.
+		const identityRoot = pathsMod.resolveProjectStorageIdentityRoot(projectRoot);
+		return pathsMod.getProjectGlobalConfigDir(identityRoot);
+	} catch {
+		return globalDir;
+	}
+}
+
+function normalizeAccountIdentifier(value) {
+	return typeof value === "string" && value.trim().length > 0
+		? value.trim().toLowerCase()
+		: "";
+}
+
+function findAccountIndexByIdOrEmail(accounts, id, email) {
+	const normalizedId = normalizeAccountIdentifier(id);
+	const normalizedEmail = normalizeAccountIdentifier(email);
+	for (let index = 0; index < accounts.length; index += 1) {
+		const account = accounts[index];
+		if (!account || typeof account !== "object") continue;
+		if (
+			normalizedId &&
+			normalizeAccountIdentifier(account.accountId) === normalizedId
+		) {
+			return index;
+		}
+		if (
+			normalizedEmail &&
+			normalizeAccountIdentifier(account.email) === normalizedEmail
+		) {
+			return index;
+		}
+	}
+	return -1;
+}
+
+function resolveModelFamilyForStatus(model) {
+	const normalized = typeof model === "string" ? model.trim().toLowerCase() : "";
+	if (normalized.startsWith("gpt-5.2")) return "gpt-5.2";
+	if (normalized.startsWith("gpt-5.1")) return "gpt-5.1";
+	if (normalized.includes("codex-max")) return "codex-max";
+	if (normalized.includes("codex")) return "codex";
+	if (normalized.startsWith("gpt-5")) return "gpt-5-codex";
+	return null;
+}
+
+function resolveStatusAccountIndex(storage, runtime, model) {
+	const accounts = Array.isArray(storage?.accounts) ? storage.accounts : [];
+	if (accounts.length === 0) return -1;
+
+	const runtimeUpdatedAt =
+		typeof runtime?.lastAccountUpdatedAt === "number"
+			? runtime.lastAccountUpdatedAt
+			: typeof runtime?.updatedAt === "number"
+				? runtime.updatedAt
+				: 0;
+	if (Date.now() - runtimeUpdatedAt <= 60 * 60 * 1000) {
+		const runtimeIndex = findAccountIndexByIdOrEmail(
+			accounts,
+			runtime?.lastAccountId,
+			runtime?.lastAccountEmail,
+		);
+		if (runtimeIndex >= 0) return runtimeIndex;
+		if (
+			typeof runtime?.lastAccountIndex === "number" &&
+			runtime.lastAccountIndex >= 0 &&
+			runtime.lastAccountIndex < accounts.length
+		) {
+			return runtime.lastAccountIndex;
+		}
+	}
+
+	const family = resolveModelFamilyForStatus(model);
+	const familyIndex =
+		family && storage?.activeIndexByFamily && typeof storage.activeIndexByFamily[family] === "number"
+			? storage.activeIndexByFamily[family]
+			: undefined;
+	if (
+		typeof familyIndex === "number" &&
+		familyIndex >= 0 &&
+		familyIndex < accounts.length
+	) {
+		return familyIndex;
+	}
+	if (
+		typeof storage?.activeIndex === "number" &&
+		storage.activeIndex >= 0 &&
+		storage.activeIndex < accounts.length
+	) {
+		return storage.activeIndex;
+	}
+	return 0;
+}
+
+function extractConfigAssignmentValue(rawConfig, key) {
+	const pattern = new RegExp(`^\\s*${key}\\s*=\\s*([^\\n#]+)`, "m");
+	const match = rawConfig.match(pattern);
+	if (!match) return null;
+	const rawValue = (match[1] ?? "").trim();
+	const quoted = rawValue.match(/^["'](.*)["']$/);
+	return (quoted ? quoted[1] : rawValue).trim() || null;
+}
+
+function readCodexConfigValue(env, key) {
+	const configPath = join(resolveCodexHomeDir(env), "config.toml");
+	try {
+		if (!existsSync(configPath)) return null;
+		return extractConfigAssignmentValue(readFileSync(configPath, "utf8"), key);
+	} catch {
+		return null;
+	}
+}
+
+function extractArgValue(args, longName, shortName) {
+	for (let index = 0; index < args.length; index += 1) {
+		const arg = args[index];
+		if (arg === longName || (shortName && arg === shortName)) {
+			const next = args[index + 1];
+			return typeof next === "string" ? next : null;
+		}
+		if (arg.startsWith(`${longName}=`)) {
+			return arg.slice(longName.length + 1);
+		}
+	}
+	return null;
+}
+
+function extractConfigOverrideValue(args, key) {
+	for (let index = 0; index < args.length; index += 1) {
+		const arg = args[index];
+		let assignment = null;
+		if (arg === "-c" || arg === "--config") {
+			assignment = args[index + 1] ?? null;
+		} else if (arg.startsWith("-c=")) {
+			assignment = arg.slice(3);
+		} else if (arg.startsWith("--config=")) {
+			assignment = arg.slice("--config=".length);
+		}
+		if (typeof assignment !== "string") continue;
+		const separator = assignment.indexOf("=");
+		if (separator <= 0) continue;
+		if (assignment.slice(0, separator).trim() !== key) continue;
+		return assignment
+			.slice(separator + 1)
+			.trim()
+			.replace(/^["']|["']$/g, "");
+	}
+	return null;
+}
+
+function resolveStatusModel(args, env = process.env) {
+	return (
+		extractArgValue(args, "--model", "-m") ??
+		extractConfigOverrideValue(args, "model") ??
+		readCodexConfigValue(env, "model") ??
+		"unknown-model"
+	);
+}
+
+function resolveStatusReasoningEffort(args, env = process.env) {
+	return (
+		extractConfigOverrideValue(args, "model_reasoning_effort") ??
+		readCodexConfigValue(env, "model_reasoning_effort") ??
+		"unknown"
+	);
+}
+
+function formatStatusPath(cwd = process.cwd(), home = homedir()) {
+	const resolvedCwd = resolvePath(cwd);
+	const resolvedHome = resolvePath(home);
+	if (resolvedCwd === resolvedHome) return "~";
+	// Use the platform separator, not a hardcoded "/": on Windows resolvePath
+	// returns backslash paths (C:\Users\user\project), so the old "/"-anchored
+	// prefix check never matched and the cwd was never abbreviated to ~. `sep`
+	// keeps the boundary check correct on both POSIX and Windows.
+	const prefix = `${resolvedHome}${sep}`;
+	if (resolvedCwd.startsWith(prefix)) {
+		// Normalize the remainder to forward slashes for a stable, readable status
+		// line regardless of the host separator.
+		return `~/${resolvedCwd.slice(prefix.length).split(sep).join("/")}`;
+	}
+	return resolvedCwd;
+}
+
+function formatStatusResetTime(resetAtMs) {
+	if (typeof resetAtMs !== "number" || !Number.isFinite(resetAtMs) || resetAtMs <= 0) {
+		return null;
+	}
+	const date = new Date(resetAtMs);
+	if (!Number.isFinite(date.getTime())) return null;
+	return date.toLocaleTimeString([], { hour: "2-digit", minute: "2-digit", hour12: false });
+}
+
+function formatStatusResetDate(resetAtMs) {
+	if (typeof resetAtMs !== "number" || !Number.isFinite(resetAtMs) || resetAtMs <= 0) {
+		return null;
+	}
+	const date = new Date(resetAtMs);
+	if (!Number.isFinite(date.getTime())) return null;
+	return date.toLocaleDateString([], { month: "short", day: "numeric" });
+}
+
+function formatCacheAge(updatedAt) {
+	if (typeof updatedAt !== "number" || !Number.isFinite(updatedAt) || updatedAt <= 0) {
+		return "stale";
+	}
+	const ageMs = Math.max(0, Date.now() - updatedAt);
+	if (ageMs < 60_000) return "now";
+	if (ageMs < 60 * 60_000) return `${Math.floor(ageMs / 60_000)}m`;
+	return `${Math.floor(ageMs / (60 * 60_000))}h`;
+}
+
+function getQuotaEntryForAccount(quotaCache, account) {
+	const byAccountId =
+		quotaCache && typeof quotaCache === "object" && quotaCache.byAccountId
+			? quotaCache.byAccountId
+			: {};
+	const byEmail =
+		quotaCache && typeof quotaCache === "object" && quotaCache.byEmail
+			? quotaCache.byEmail
+			: {};
+	const accountId = typeof account?.accountId === "string" ? account.accountId : "";
+	const email = typeof account?.email === "string" ? account.email.toLowerCase() : "";
+	return byAccountId?.[accountId] ?? byEmail?.[email] ?? null;
+}
+
+function formatUsageWindow(label, window, resetFormatter) {
+	const used =
+		typeof window?.usedPercent === "number" && Number.isFinite(window.usedPercent)
+			? Math.max(0, Math.min(100, Math.round(window.usedPercent)))
+			: null;
+	const reset = resetFormatter(window?.resetAtMs);
+	if (used === null && !reset) return null;
+	if (used === null) return `${label} resets ${reset}`;
+	if (!reset) return `${label} ${used}%`;
+	return `${label} ${used}% ${reset}`;
+}
+
+function formatUsageSegment(entry) {
+	const primary = formatUsageWindow("5h", entry?.primary, formatStatusResetTime);
+	const secondary = formatUsageWindow("week", entry?.secondary, formatStatusResetDate);
+	const parts = [primary, secondary].filter(Boolean);
+	return parts.length > 0 ? parts.join(" | ") : "usage cached";
+}
+
+function formatPlan(planType) {
+	if (typeof planType !== "string" || planType.trim().length === 0) return "Plan?";
+	const normalized = planType.trim();
+	if (normalized.length <= 1) return normalized.toUpperCase();
+	return `${normalized[0].toUpperCase()}${normalized.slice(1).toLowerCase()}`;
+}
+
+function shouldShowForwardStatus(args, env = process.env) {
+	const override = (env.CODEX_MULTI_AUTH_STATUSLINE ?? "").trim().toLowerCase();
+	if (new Set(["0", "false", "no", "off"]).has(override)) return false;
+	if (new Set(["1", "true", "yes", "on"]).has(override)) return true;
+	if ((env.CODEX_MULTI_AUTH_STATUS_REFRESH_CHILD ?? "").trim() === "1") return false;
+	if (args.some((arg) => arg === "--help" || arg === "-h" || arg === "--version" || arg === "-V")) {
+		return false;
+	}
+	return process.stderr.isTTY === true;
+}
+
+function formatForwardStatusLine(rawArgs, env = process.env, accountsDir = resolveMultiAuthDirFromEnv(env)) {
+	// Only the accounts pool is per-project; quota-cache.json and
+	// runtime-observability.json are global (lib: getCodexMultiAuthDir), so read
+	// accounts from the (possibly project-scoped) dir and the rest from global.
+	const storage = readJsonFileQuiet(resolveAccountsPath(env, accountsDir));
+	const accounts = Array.isArray(storage?.accounts) ? storage.accounts : [];
+	if (accounts.length === 0) return null;
+
+	const runtime = readJsonFileQuiet(resolveRuntimeObservabilityPath(env));
+	const quotaCache = readJsonFileQuiet(resolveQuotaCachePath(env));
+	const model = resolveStatusModel(rawArgs, env);
+	const effort = resolveStatusReasoningEffort(rawArgs, env);
+	const accountIndex = resolveStatusAccountIndex(storage, runtime, model);
+	const account = accounts[accountIndex];
+	if (!account || typeof account !== "object") return null;
+
+	const quotaEntry = getQuotaEntryForAccount(quotaCache, account);
+	const email = typeof account.email === "string" && account.email.trim()
+		? account.email.trim()
+		: `Account ${accountIndex + 1}`;
+	const plan = formatPlan(quotaEntry?.planType);
+	const usage = formatUsageSegment(quotaEntry);
+	const cacheAge = formatCacheAge(quotaEntry?.updatedAt);
+	const parts = [
+		"codex-multi-auth",
+		`${model} ${effort}`,
+		formatStatusPath(),
+		`Account ${accountIndex + 1}`,
+		usage,
+		`${email}(${plan})`,
+		`cache ${cacheAge}`,
+	];
+	return parts.join(" | ");
+}
+
+async function maybePrintForwardStatusLine(rawArgs, env = process.env) {
+	if (!shouldShowForwardStatus(rawArgs, env)) return;
+	const accountsDir = await resolveStatusAccountsDir(env);
+	const line = formatForwardStatusLine(rawArgs, env, accountsDir);
+	if (!line) return;
+	process.stderr.write(`${line}\n`);
+}
+
+function parseDurationMs(value, fallback) {
+	const trimmed = typeof value === "string" ? value.trim() : "";
+	if (trimmed.length === 0) return fallback;
+	const parsed = Number.parseInt(trimmed, 10);
+	if (!Number.isFinite(parsed) || parsed < 0) return fallback;
+	return parsed;
+}
+
+function quotaCacheNeedsRefresh(env = process.env) {
+	const intervalMs = parseDurationMs(
+		env.CODEX_MULTI_AUTH_STATUS_QUOTA_REFRESH_INTERVAL_MS,
+		DEFAULT_STATUS_QUOTA_REFRESH_INTERVAL_MS,
+	);
+	if (intervalMs <= 0) return false;
+	const cache = readJsonFileQuiet(resolveQuotaCachePath(env));
+	const entries = [
+		...Object.values(cache?.byAccountId ?? {}),
+		...Object.values(cache?.byEmail ?? {}),
+	].filter((entry) => entry && typeof entry === "object");
+	if (entries.length === 0) return true;
+	const newest = Math.max(
+		...entries.map((entry) =>
+			typeof entry.updatedAt === "number" && Number.isFinite(entry.updatedAt)
+				? entry.updatedAt
+				: 0,
+		),
+	);
+	return newest <= 0 || Date.now() - newest >= intervalMs;
+}
+
+function acquireStatusRefreshLock(env = process.env) {
+	const lockPath = join(resolveMultiAuthDirFromEnv(env), STATUS_QUOTA_REFRESH_LOCK_DIR);
+	try {
+		mkdirSync(dirname(lockPath), { recursive: true, mode: 0o700 });
+		mkdirSync(lockPath);
+		writeFileSync(
+			join(lockPath, "owner.json"),
+			`${JSON.stringify({ pid: process.pid, createdAt: Date.now() })}\n`,
+			{ mode: 0o600 },
+		);
+		return { lockPath, acquired: true };
+	} catch {
+		try {
+			const stat = statSync(lockPath);
+			if (Date.now() - stat.mtimeMs > STATUS_QUOTA_REFRESH_LOCK_STALE_MS) {
+				// Known, bounded TOCTOU: two processes that both observe a stale lock
+				// will both rmSync({force:true}) (both succeed) then race on mkdirSync;
+				// only one wins, so dual lock acquisition is still prevented. The
+				// residual risk is evicting a refresh owner that is merely SLOW (alive,
+				// holding the lock past the stale threshold) rather than dead, which can
+				// briefly yield two `forecast --live --json` children. That is benign
+				// here — the refresh is idempotent, read-mostly, and rate-limited by the
+				// cache TTL — so we accept it rather than add a heavier liveness probe.
+				removeDirectoryWithRetry(lockPath);
+				mkdirSync(lockPath);
+				writeFileSync(
+					join(lockPath, "owner.json"),
+					`${JSON.stringify({ pid: process.pid, createdAt: Date.now(), recovered: true })}\n`,
+					{ mode: 0o600 },
+				);
+				return { lockPath, acquired: true };
+			}
+		} catch {
+			// Another process can win the race; skip refresh.
+		}
+	}
+	return { lockPath, acquired: false };
+}
+
+function maybeRefreshQuotaCacheInBackground(env = process.env) {
+	if ((env.CODEX_MULTI_AUTH_STATUS_REFRESH_CHILD ?? "").trim() === "1") return;
+	if (!quotaCacheNeedsRefresh(env)) return;
+	const { lockPath, acquired } = acquireStatusRefreshLock(env);
+	if (!acquired) return;
+
+	const scriptPath = join(dirname(fileURLToPath(import.meta.url)), "codex-multi-auth.js");
+	// Note: the child is detached + unref'd so it outlives this short-lived launcher
+	// process. The close/error handlers below remove the lock dir, but if the parent
+	// exits before the child settles they will NOT fire — in that case the lock is
+	// reclaimed by the 10-minute stale-lock recovery in acquireStatusRefreshLock.
+	const child = spawn(
+		process.execPath,
+		[scriptPath, "forecast", "--live", "--json"],
+		{
+			env: {
+				...env,
+				CODEX_MULTI_AUTH_STATUS_REFRESH_CHILD: "1",
+				CODEX_MULTI_AUTH_STATUSLINE: "0",
+			},
+			stdio: "ignore",
+			detached: true,
+		},
+	);
+	child.once("close", () => {
+		// Async, non-blocking: these handlers fire on the parent event loop while
+		// Codex is running, so the cleanup must never block it on a Windows lock.
+		void removeDirectoryBestEffortAsync(lockPath);
+	});
+	child.once("error", () => {
+		void removeDirectoryBestEffortAsync(lockPath);
+	});
+	child.unref();
+}
+
 function isRotationEnableCommand(args) {
 	return args[0] === "auth" && args[1] === "rotation" && args[2] === "enable";
 }
@@ -4262,6 +4767,8 @@ async function main() {
 	}
 
 	await autoSyncManagerActiveSelectionIfEnabled();
+	await maybePrintForwardStatusLine(rawArgs);
+	maybeRefreshQuotaCacheInBackground();
 	try {
 		return await withForwardedRuntimeObservability(rawArgs, () =>
 			forwardToRealCodex(realCodexBin, rawArgs),