codex-multi-auth 1.2.5 → 1.2.7

package/README.md

@@ -3,7 +3,7 @@
 [![npm version](https://img.shields.io/npm/v/codex-multi-auth.svg)](https://www.npmjs.com/package/codex-multi-auth)
 [![npm downloads](https://img.shields.io/npm/dw/codex-multi-auth.svg)](https://www.npmjs.com/package/codex-multi-auth)
 
-Codex CLI-first multi-account OAuth manager for the official `@openai/codex` CLI.
+Codex CLI-first multi-account OAuth manager for the official Codex CLI, including the `@openai/codex` npm launcher and native `codex` installs.
 
 <img width="1270" height="729" alt="2026-02-28 12_54_58-prompt txt ‎- Notepads" src="https://github.com/user-attachments/assets/0cecb77e-a6d3-432a-ba48-3577db0c7093" />
 
@@ -11,6 +11,7 @@ Codex CLI-first multi-account OAuth manager for the official `@openai/codex` CLI
 > [!NOTE]
 > Legacy scoped prerelease package `@ndycode/codex-multi-auth` is migration-only.
 > Use `codex-multi-auth` for all new installs.
+
 ## What You Get
 
 - Canonical `codex auth ...` workflow for account login, switching, checks, and diagnostics
@@ -19,7 +20,7 @@ Codex CLI-first multi-account OAuth manager for the official `@openai/codex` CLI
 - Interactive dashboard for account actions and settings
 - Experimental settings tab for staged sync, backup, and refresh-guard controls
 - Forecast, report, fix, and doctor commands for operational safety
-- Runtime request budget, cooldown, and traffic observability in `codex auth status` / `codex auth report`
+- Runtime counters, budget/cooldown state, and multi-auth probe visibility in `codex auth status` / `codex auth report`
 - Flagged account verification and restore flow
 - Session affinity and live account sync controls
 - Proactive refresh and preemptive quota deferral controls
@@ -71,6 +72,8 @@ codex-multi-auth --version
 codex auth status
 ```
 
+Any official install path is fine as long as `codex` is on `PATH`: `npm i -g @openai/codex`, `brew install --cask codex`, or an official release binary.
+
 </details>
 
 <details>
@@ -105,6 +108,13 @@ npm i -g codex-multi-auth
 codex auth login
 ```
 
+If you already installed the official native CLI via Homebrew or a release binary, you only need:
+
+```bash
+npm i -g codex-multi-auth
+codex auth login
+```
+
 Verify the wrapper and the new account:
 
 ```bash
@@ -163,7 +173,7 @@ If browser launch is blocked, use the alternate login paths in [docs/getting-sta
 - active requests use a bounded outbound request budget so one prompt cannot walk the full pool indefinitely
 - repeated cross-account 5xx bursts trigger a short cooldown instead of continuing aggressive rotation
 - proactive refresh is staggered to reduce background refresh bursts
-- `codex auth status` surfaces recent runtime request metrics in text output, and `codex auth report --json` exposes the machine-readable cooldown/runtime snapshot
+- `codex auth status` surfaces recent runtime request metrics in text output, and `codex auth report --json` exposes the machine-readable cooldown/runtime snapshot
 
 ---
 
@@ -196,12 +206,12 @@ If browser launch is blocked, use the alternate login paths in [docs/getting-sta
 | File | Default path |
 | --- | --- |
 | Settings | `~/.codex/multi-auth/settings.json` |
-| Accounts | `~/.codex/multi-auth/openai-codex-accounts.json` |
-| Flagged accounts | `~/.codex/multi-auth/openai-codex-flagged-accounts.json` |
-| Quota cache | `~/.codex/multi-auth/quota-cache.json` |
-| Runtime observability | `~/.codex/multi-auth/runtime-observability.json` |
-| Logs | `~/.codex/multi-auth/logs/codex-plugin/` |
-| Per-project accounts | `~/.codex/multi-auth/projects/<project-key>/openai-codex-accounts.json` |
+| Accounts | `~/.codex/multi-auth/openai-codex-accounts.json` |
+| Flagged accounts | `~/.codex/multi-auth/openai-codex-flagged-accounts.json` |
+| Quota cache | `~/.codex/multi-auth/quota-cache.json` |
+| Runtime observability | `~/.codex/multi-auth/runtime-observability.json` |
+| Logs | `~/.codex/multi-auth/logs/codex-plugin/` |
+| Per-project accounts | `~/.codex/multi-auth/projects/<project-key>/openai-codex-accounts.json` |
 
 Override root with `CODEX_MULTI_AUTH_DIR=<path>`.
 
@@ -273,12 +283,12 @@ codex auth login
 <details>
 <summary><b>Common symptoms</b></summary>
 
-- `codex auth` unrecognized: run `where codex`, then follow `docs/troubleshooting.md` for routing fallback commands
+- `codex auth` unrecognized: run `where codex` or `which codex`, then follow `docs/troubleshooting.md` for routing fallback commands
 - Switch succeeds but wrong account appears active: run `codex auth switch <index>`, then restart session
-- Requests fail fast with a pool cooldown message: wait for the cooldown window or inspect `codex auth status`
-- Requests fail fast after repeated upstream 5xx errors: inspect `codex auth report --json` for runtime traffic and cooldown details
-- Storage cleanup fails with `EBUSY` / `EPERM` (Windows): run `codex auth doctor --fix` to retry, or manually remove `~/.codex/multi-auth/<project-key>/` and re-login
-- OAuth callback on port `1455` fails: free the port and re-run `codex auth login`
+- Requests fail fast with a pool cooldown message: wait for the cooldown window or inspect `codex auth status`
+- Requests fail fast after repeated upstream 5xx errors: inspect `codex auth report --json` for runtime traffic and cooldown details
+- Storage cleanup fails with `EBUSY` / `EPERM` (Windows): run `codex auth doctor --fix` to retry, or manually remove `~/.codex/multi-auth/<project-key>/` and re-login
+- OAuth callback on port `1455` fails: free the port and re-run `codex auth login`
 - Browser launch is blocked or you are in a headless shell: re-run `codex auth login --manual` or set `CODEX_AUTH_NO_BROWSER=1`
 - `missing field id_token` / `token_expired` / `refresh_token_reused`: re-login affected account
 
@@ -321,9 +331,10 @@ codex auth doctor --json
 
 ## Release Notes
 
-- Current stable: [docs/releases/v1.2.4.md](docs/releases/v1.2.4.md)
-- Previous stable: [docs/releases/v1.2.2.md](docs/releases/v1.2.2.md)
-- Earlier stable: [docs/releases/v1.2.1.md](docs/releases/v1.2.1.md)
+- Current stable: [docs/releases/v1.2.7.md](docs/releases/v1.2.7.md)
+- Previous stable: [docs/releases/v1.2.6.md](docs/releases/v1.2.6.md)
+- Earlier stable: [docs/releases/v1.2.5.md](docs/releases/v1.2.5.md)
+- Full release archive: [docs/README.md#release-history](docs/README.md#release-history)
 - Archived prerelease: [docs/releases/v0.1.0-beta.0.md](docs/releases/v0.1.0-beta.0.md)
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "codex-multi-auth",
-	"version": "1.2.5",
+	"version": "1.2.7",
 	"description": "Multi-account OAuth manager and codex auth wrapper for the official @openai/codex CLI, with switching, health checks, and recovery tools",
 	"main": "./dist/index.js",
 	"types": "./dist/index.d.ts",

package/scripts/codex-bin-resolver.js

@@ -1,10 +1,36 @@
 import { spawnSync } from "node:child_process";
-import { existsSync } from "node:fs";
+import { existsSync, realpathSync } from "node:fs";
 import { createRequire } from "node:module";
-import { dirname, join } from "node:path";
+import { basename, delimiter, dirname, extname, join } from "node:path";
 import process from "node:process";
 import { fileURLToPath } from "node:url";
 
+function isJavaScriptEntryPath(candidate) {
+	const extension = extname(candidate).toLowerCase();
+	return extension === ".js" || extension === ".mjs" || extension === ".cjs";
+}
+
+function createResolvedCodexBin(path) {
+	return {
+		path,
+		launchWithNode: isJavaScriptEntryPath(path),
+	};
+}
+
+function normalizeResolvedPath(candidatePath, realpathSyncImpl) {
+	try {
+		return realpathSyncImpl(candidatePath);
+	} catch {
+		return candidatePath;
+	}
+}
+
+function resolveWrapperScriptPath(moduleUrl, realpathSyncImpl) {
+	return normalizeResolvedPath(fileURLToPath(moduleUrl), realpathSyncImpl);
+}
+
+const DEFAULT_WRAPPER_MODULE_URL = new URL("./codex.js", import.meta.url).href;
+
 function defaultResolvePackageBin(moduleUrl) {
 	try {
 		const require = createRequire(moduleUrl);
@@ -26,26 +52,141 @@ function resolveWindowsCmdPath(env) {
 	return "cmd.exe";
 }
 
+export function splitPathEntries(pathValue) {
+	if (typeof pathValue !== "string" || pathValue.trim().length === 0) {
+		return [];
+	}
+	return pathValue
+		.split(delimiter)
+		.map((entry) => entry.trim())
+		.filter((entry) => entry.length > 0);
+}
+
+function resolvePathExecutableName(platform) {
+	return platform === "win32" ? "codex.exe" : "codex";
+}
+
+function resolveCandidateExecutableNames(platform) {
+	if (platform !== "win32") {
+		return [resolvePathExecutableName(platform)];
+	}
+	return ["codex.exe", "codex"];
+}
+
+function resolveCodexExecutableFromPath(
+	pathEntries,
+	platform,
+	existsSyncImpl,
+	selfScriptPath,
+	realpathSyncImpl,
+) {
+	for (const entry of pathEntries) {
+		for (const executableName of resolveCandidateExecutableNames(platform)) {
+			const candidate = join(entry, executableName);
+			if (!existsSyncImpl(candidate)) {
+				continue;
+			}
+			if (
+				selfScriptPath &&
+				normalizeResolvedPath(candidate, realpathSyncImpl) === selfScriptPath
+			) {
+				continue;
+			}
+			return candidate;
+		}
+	}
+	return null;
+}
+
+function normalizeWhereOutput(stdout) {
+	return stdout
+		.split(/\r?\n/)
+		.map((line) => line.trim())
+		.filter((line) => line.length > 0);
+}
+
+function resolveCodexExecutableFromSystemPath(
+	env,
+	platform,
+	spawnSyncImpl,
+	existsSyncImpl,
+	selfScriptPath,
+	realpathSyncImpl,
+) {
+	const pathEntries = splitPathEntries(env.PATH ?? env.Path ?? "");
+	const fromEnvPath = resolveCodexExecutableFromPath(
+		pathEntries,
+		platform,
+		existsSyncImpl,
+		selfScriptPath,
+		realpathSyncImpl,
+	);
+	if (fromEnvPath) {
+		return fromEnvPath;
+	}
+
+	try {
+		const lookupResult =
+			platform === "win32"
+				? spawnSyncImpl(resolveWindowsCmdPath(env), ["/d", "/s", "/c", "where codex"], {
+						encoding: "utf8",
+						env,
+						stdio: ["ignore", "pipe", "ignore"],
+						timeout: 5000,
+						windowsHide: true,
+					})
+				: spawnSyncImpl("which", ["codex"], {
+						encoding: "utf8",
+						env,
+						stdio: ["ignore", "pipe", "ignore"],
+						timeout: 5000,
+					});
+		if (lookupResult.status !== 0) {
+			return null;
+		}
+		for (const candidate of normalizeWhereOutput(lookupResult.stdout)) {
+			if (!existsSyncImpl(candidate)) {
+				continue;
+			}
+			if (
+				selfScriptPath &&
+				normalizeResolvedPath(candidate, realpathSyncImpl) === selfScriptPath
+			) {
+				continue;
+			}
+			const fileName = basename(candidate).toLowerCase();
+			if (fileName === "codex" || fileName === "codex.exe") {
+				return candidate;
+			}
+		}
+	} catch {
+		// Ignore and fall through.
+	}
+
+	return null;
+}
+
 export function resolveRealCodexBin(options = {}) {
 	const {
 		env = process.env,
 		argv = process.argv,
 		platform = process.platform,
-		moduleUrl = import.meta.url,
+		moduleUrl = DEFAULT_WRAPPER_MODULE_URL,
 		existsSyncImpl = existsSync,
+		realpathSyncImpl = realpathSync,
 		spawnSyncImpl = spawnSync,
 		resolvePackageBin = defaultResolvePackageBin,
 	} = options;
 
 	const override = (env.CODEX_MULTI_AUTH_REAL_CODEX_BIN ?? "").trim();
 	if (override.length > 0) {
-		if (existsSyncImpl(override)) return override;
+		if (existsSyncImpl(override)) return createResolvedCodexBin(override);
 		return null;
 	}
 
 	const resolved = resolvePackageBin(moduleUrl);
 	if (typeof resolved === "string" && resolved.length > 0 && existsSyncImpl(resolved)) {
-		return resolved;
+		return createResolvedCodexBin(resolved);
 	}
 
 	const searchRoots = [];
@@ -65,7 +206,7 @@ export function resolveRealCodexBin(options = {}) {
 
 	for (const root of searchRoots) {
 		const candidate = join(root, "@openai", "codex", "bin", "codex.js");
-		if (existsSyncImpl(candidate)) return candidate;
+		if (existsSyncImpl(candidate)) return createResolvedCodexBin(candidate);
 	}
 
 	try {
@@ -88,12 +229,26 @@ export function resolveRealCodexBin(options = {}) {
 			const globalRoot = rootResult.stdout.trim();
 			if (globalRoot.length > 0) {
 				const globalBin = join(globalRoot, "@openai", "codex", "bin", "codex.js");
-				if (existsSyncImpl(globalBin)) return globalBin;
+				if (existsSyncImpl(globalBin)) return createResolvedCodexBin(globalBin);
 			}
 		}
 	} catch {
 		// Ignore and fall through to null.
 	}
 
+	const selfScriptPath = resolveWrapperScriptPath(moduleUrl, realpathSyncImpl);
+
+	const nativeCodexBin = resolveCodexExecutableFromSystemPath(
+		env,
+		platform,
+		spawnSyncImpl,
+		existsSyncImpl,
+		selfScriptPath,
+		realpathSyncImpl,
+	);
+	if (nativeCodexBin) {
+		return createResolvedCodexBin(nativeCodexBin);
+	}
+
 	return null;
 }

package/scripts/codex.js

@@ -18,7 +18,10 @@ import { homedir, tmpdir } from "node:os";
 import { basename, delimiter, dirname, join, resolve as resolvePath } from "node:path";
 import process from "node:process";
 import { fileURLToPath } from "node:url";
-import { resolveRealCodexBin as resolveRealCodexBinFromEnvironment } from "./codex-bin-resolver.js";
+import {
+	resolveRealCodexBin as resolveRealCodexBinFromEnvironment,
+	splitPathEntries,
+} from "./codex-bin-resolver.js";
 import { normalizeAuthAlias, shouldHandleMultiAuthAuth } from "./codex-routing.js";
 
 const RETRYABLE_SHADOW_HOME_CLEANUP_CODES = new Set(["EBUSY", "EPERM", "ENOTEMPTY"]);
@@ -124,11 +127,17 @@ async function autoSyncManagerActiveSelectionIfEnabled() {
 function resolveRealCodexBin() {
 	const override = (process.env.CODEX_MULTI_AUTH_REAL_CODEX_BIN ?? "").trim();
 	if (override.length > 0) {
-		if (existsSync(override)) return override;
-		console.error(
-			`CODEX_MULTI_AUTH_REAL_CODEX_BIN is set but missing: ${override}`,
-		);
-		return null;
+		if (!existsSync(override)) {
+			console.error(
+				`CODEX_MULTI_AUTH_REAL_CODEX_BIN is set but missing: ${override}`,
+			);
+			return null;
+		}
+		return resolveRealCodexBinFromEnvironment({
+			moduleUrl: import.meta.url,
+			env: process.env,
+			existsSyncImpl: existsSync,
+		});
 	}
 
 	return resolveRealCodexBinFromEnvironment({ moduleUrl: import.meta.url });
@@ -145,7 +154,9 @@ function forwardToRealCodex(codexBin, args, env = process.env, cleanup) {
 			resolve(exitCode);
 		};
 
-		const child = spawn(process.execPath, [codexBin, ...args], {
+		const command = codexBin.launchWithNode ? process.execPath : codexBin.path;
+		const commandArgs = codexBin.launchWithNode ? [codexBin.path, ...args] : args;
+		const child = spawn(command, commandArgs, {
 			stdio: "inherit",
 			env,
 		});
@@ -661,6 +672,189 @@ function resolveOriginalMultiAuthDir(env) {
 	return undefined;
 }
 
+async function loadRuntimeObservabilityModule() {
+	try {
+		const mod = await import("../dist/lib/runtime/runtime-observability.js");
+		if (
+			typeof mod.loadPersistedRuntimeObservabilitySnapshot !== "function" ||
+			typeof mod.mutateRuntimeObservabilitySnapshot !== "function"
+		) {
+			return null;
+		}
+		return mod;
+	} catch (error) {
+		if (
+			error &&
+			typeof error === "object" &&
+			"code" in error &&
+			error.code === "ERR_MODULE_NOT_FOUND"
+		) {
+			return null;
+		}
+		throw error;
+	}
+}
+
+function isPureHelpOrVersionArgs(rawArgs) {
+	if (!Array.isArray(rawArgs) || rawArgs.length === 0) {
+		return false;
+	}
+	return rawArgs.every((arg) =>
+		typeof arg === "string" && ["--help", "-h", "--version", "-V"].includes(arg),
+	);
+}
+
+function consumesNextArg(arg) {
+	return new Set([
+		"-c",
+		"--config",
+		"--enable",
+		"--disable",
+		"--remote",
+		"--remote-auth-token-env",
+		"-i",
+		"--image",
+		"-m",
+		"--model",
+		"--local-provider",
+		"-p",
+		"--profile",
+		"-s",
+		"--sandbox",
+		"-a",
+		"--ask-for-approval",
+		"-C",
+		"--cd",
+		"--add-dir",
+		"--output-schema",
+		"--color",
+		"-o",
+		"--output-last-message",
+	]).has(arg);
+}
+
+function shouldTrackForwardedRuntimeObservability(rawArgs) {
+	if (!Array.isArray(rawArgs) || rawArgs.length === 0) {
+		return true;
+	}
+	if (isPureHelpOrVersionArgs(rawArgs)) {
+		return false;
+	}
+
+	const requestCommands = new Set(["exec", "review", "resume", "fork"]);
+	const nonRequestCommands = new Set([
+		"help",
+		"completion",
+		"login",
+		"logout",
+		"mcp",
+		"mcp-server",
+		"app-server",
+		"sandbox",
+		"debug",
+		"apply",
+		"cloud",
+		"features",
+		"auth",
+	]);
+
+	for (let i = 0; i < rawArgs.length; i += 1) {
+		const arg = rawArgs[i];
+		if (typeof arg !== "string" || arg.length === 0) continue;
+		if (arg === "--") {
+			return i + 1 < rawArgs.length;
+		}
+		if (arg.startsWith("--config=")) {
+			continue;
+		}
+		if (arg.startsWith("--") || (arg.startsWith("-") && arg !== "-")) {
+			if (consumesNextArg(arg)) {
+				i += 1;
+			}
+			continue;
+		}
+		if (requestCommands.has(arg)) {
+			return true;
+		}
+		if (nonRequestCommands.has(arg)) {
+			return false;
+		}
+		return true;
+	}
+
+	return true;
+}
+
+function createRuntimeSnapshotChangeToken(snapshot) {
+	return JSON.stringify({
+		updatedAt: snapshot?.updatedAt ?? null,
+		responsesRequests: snapshot?.responsesRequests ?? null,
+		authRefreshRequests: snapshot?.authRefreshRequests ?? null,
+		diagnosticProbeRequests: snapshot?.diagnosticProbeRequests ?? null,
+		totalRequests: snapshot?.runtimeMetrics?.totalRequests ?? null,
+		successfulRequests: snapshot?.runtimeMetrics?.successfulRequests ?? null,
+		failedRequests: snapshot?.runtimeMetrics?.failedRequests ?? null,
+		lastRequestAt: snapshot?.runtimeMetrics?.lastRequestAt ?? null,
+	});
+}
+
+async function loadRuntimeSnapshotWithRetry(runtimeObservabilityModule) {
+	let snapshot = null;
+	for (let attempt = 0; attempt < 5; attempt += 1) {
+		snapshot =
+			(await runtimeObservabilityModule.loadPersistedRuntimeObservabilitySnapshot()) ??
+			null;
+		if (snapshot) {
+			return snapshot;
+		}
+		if (attempt < 4) {
+			await new Promise((resolve) => setTimeout(resolve, 20));
+		}
+	}
+	return snapshot;
+}
+
+async function withForwardedRuntimeObservability(rawArgs, runForwardedCommand) {
+	if (!shouldTrackForwardedRuntimeObservability(rawArgs)) {
+		return runForwardedCommand();
+	}
+
+	const runtimeObservabilityModule = await loadRuntimeObservabilityModule();
+	if (!runtimeObservabilityModule) {
+		return runForwardedCommand();
+	}
+
+	const beforeSnapshot = await loadRuntimeSnapshotWithRetry(runtimeObservabilityModule);
+	const beforeToken = createRuntimeSnapshotChangeToken(beforeSnapshot);
+	const startedAt = Date.now();
+	const exitCode = await runForwardedCommand();
+	const afterSnapshot = await loadRuntimeSnapshotWithRetry(runtimeObservabilityModule);
+	const afterToken = createRuntimeSnapshotChangeToken(afterSnapshot);
+	if (afterToken !== beforeToken) {
+		return exitCode;
+	}
+
+	runtimeObservabilityModule.mutateRuntimeObservabilitySnapshot((snapshot) => {
+		snapshot.currentRequestId = null;
+		snapshot.responsesRequests += 1;
+		snapshot.runtimeMetrics.totalRequests += 1;
+		snapshot.runtimeMetrics.responsesRequests += 1;
+		snapshot.runtimeMetrics.cumulativeLatencyMs += Math.max(0, Date.now() - startedAt);
+		snapshot.runtimeMetrics.lastRequestAt = Date.now();
+		if (!snapshot.runtimeMetrics.startedAt) {
+			snapshot.runtimeMetrics.startedAt = startedAt;
+		}
+		if (exitCode === 0) {
+			snapshot.runtimeMetrics.successfulRequests += 1;
+			snapshot.runtimeMetrics.lastError = null;
+		} else {
+			snapshot.runtimeMetrics.failedRequests += 1;
+			snapshot.runtimeMetrics.lastError = `forwarded-codex-exit:${exitCode}`;
+		}
+	});
+	return exitCode;
+}
+
 function createCompatibilityCodexHome(
 	processedArgs,
 	requestedModel,
@@ -810,16 +1004,6 @@ function shouldInstallWindowsBatchShimGuard() {
 	return override !== "0";
 }
 
-function splitPathEntries(pathValue) {
-	if (typeof pathValue !== "string" || pathValue.trim().length === 0) {
-		return [];
-	}
-	return pathValue
-		.split(delimiter)
-		.map((entry) => entry.trim())
-		.filter((entry) => entry.length > 0);
-}
-
 function resolveWindowsShimDirectoryFromInvocation() {
 	const invokedScript = (process.argv[1] ?? "").trim();
 	if (invokedScript.length === 0) return null;
@@ -955,7 +1139,13 @@ function ensureWindowsShellShim(filePath, desiredContent, options = {}) {
 		}
 		const looksLikeStockOpenAiShim =
 			currentContent.includes("node_modules\\@openai\\codex\\bin\\codex.js") ||
-			currentContent.includes("node_modules/@openai/codex/bin/codex.js");
+			currentContent.includes("node_modules/@openai/codex/bin/codex.js") ||
+			currentContent.includes("@openai\\codex-win32-") ||
+			currentContent.includes("@openai/codex-win32-") ||
+			currentContent.includes("vendor\\x86_64-pc-windows-msvc\\codex\\codex.exe") ||
+			currentContent.includes("vendor\\aarch64-pc-windows-msvc\\codex\\codex.exe") ||
+			currentContent.includes("vendor/x86_64-pc-windows-msvc/codex/codex.exe") ||
+			currentContent.includes("vendor/aarch64-pc-windows-msvc/codex/codex.exe");
 		if (looksLikeStockOpenAiShim) {
 			try {
 				writeFileSync(filePath, desiredContent, { encoding: "utf8", mode: 0o755 });
@@ -1135,9 +1325,9 @@ async function main() {
 	if (!realCodexBin) {
 		console.error(
 			[
-				"Could not locate the official Codex CLI binary (@openai/codex).",
-				"Install it globally: npm install -g @openai/codex",
-				"Or set CODEX_MULTI_AUTH_REAL_CODEX_BIN to a full bin/codex.js path.",
+				"Could not locate the official Codex CLI.",
+				"Install it with npm, Homebrew, or an official native release so `codex` is on PATH.",
+				"Or set CODEX_MULTI_AUTH_REAL_CODEX_BIN to the full path of either codex or @openai/codex/bin/codex.js.",
 			].join("\n"),
 		);
 		return 1;
@@ -1149,11 +1339,13 @@ async function main() {
 		forwardArgs,
 		requestedModel,
 	);
-	return forwardToRealCodex(
-		realCodexBin,
-		compatibility.args,
-		compatibility.env,
-		compatibility.cleanup,
+	return withForwardedRuntimeObservability(rawArgs, () =>
+		forwardToRealCodex(
+			realCodexBin,
+			compatibility.args,
+			compatibility.env,
+			compatibility.cleanup,
+		),
 	);
 }