fix: address remaining PR 387 docs and cleanup comments

Author: ndycode

README.md

@@ -163,7 +163,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` and `codex auth report --json` surface recent runtime request metrics and active cooldown windows
+- `codex auth status` surfaces recent runtime request metrics in text output, and `codex auth report --json` exposes the machine-readable cooldown/runtime snapshot
 
 ---
 
@@ -277,6 +277,7 @@ codex auth login
 - 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`
 - 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

lib/storage/account-clear.ts

@@ -1,5 +1,14 @@
 import { promises as fs } from "node:fs";
 
+function isRetryableFsError(error: unknown): boolean {
+	const code = (error as NodeJS.ErrnoException | undefined)?.code;
+	return code === "EBUSY" || code === "EPERM";
+}
+
+async function sleep(ms: number): Promise<void> {
+	await new Promise((resolve) => setTimeout(resolve, ms));
+}
+
 export async function clearAccountStorageArtifacts(params: {
 	path: string;
 	resetMarkerPath: string;
@@ -12,7 +21,21 @@ export async function clearAccountStorageArtifacts(params: {
 		required: boolean,
 	): Promise<void> => {
 		try {
-			await fs.unlink(targetPath);
+			for (let attempt = 0; attempt < 5; attempt += 1) {
+				try {
+					await fs.unlink(targetPath);
+					return;
+				} catch (error) {
+					const code = (error as NodeJS.ErrnoException).code;
+					if (code === "ENOENT") {
+						return;
+					}
+					if (!isRetryableFsError(error) || attempt >= 4) {
+						throw error;
+					}
+					await sleep(10 * 2 ** attempt);
+				}
+			}
 		} catch (error) {
 			const code = (error as NodeJS.ErrnoException).code;
 			if (code === "ENOENT") {

test/account-clear.test.ts

@@ -1,7 +1,13 @@
-import { describe, expect, it, vi } from "vitest";
+import { promises as fs } from "node:fs";
+import { afterEach, describe, expect, it, vi } from "vitest";
 import { clearAccountStorageArtifacts } from "../lib/storage/account-clear.js";
 
 describe("account clear helper", () => {
+	afterEach(() => {
+		vi.restoreAllMocks();
+		vi.useRealTimers();
+	});
+
 	it("clears primary, wal, and backups after writing marker", async () => {
 		await expect(
 			clearAccountStorageArtifacts({
@@ -13,4 +19,34 @@ describe("account clear helper", () => {
 			}),
 		).resolves.toBeUndefined();
 	});
+
+	it.each(["EBUSY", "EPERM"] as const)(
+		"retries transient %s errors when clearing required artifacts",
+		async (code) => {
+			vi.useFakeTimers();
+			const unlinkSpy = vi.spyOn(fs, "unlink");
+			let attempts = 0;
+			unlinkSpy.mockImplementation(async (targetPath) => {
+				if (String(targetPath).endsWith("tmp-accounts.json") && attempts < 2) {
+					attempts += 1;
+					const error = new Error(code) as NodeJS.ErrnoException;
+					error.code = code;
+					throw error;
+				}
+				return undefined as never;
+			});
+
+			const clearPromise = clearAccountStorageArtifacts({
+				path: `${process.cwd()}/tmp-accounts.json`,
+				resetMarkerPath: `${process.cwd()}/tmp-accounts.marker`,
+				walPath: `${process.cwd()}/tmp-accounts.wal`,
+				backupPaths: [],
+				logError: vi.fn(),
+			});
+
+			await vi.runAllTimersAsync();
+			await expect(clearPromise).resolves.toBeUndefined();
+			expect(unlinkSpy).toHaveBeenCalled();
+		},
+	);
 });

test/codex-manager-report-command.test.ts

@@ -58,6 +58,7 @@ function createDeps(
 			hasResetMarker: false,
 			hasWal: false,
 		})),
+		loadRuntimeObservabilitySnapshot: vi.fn(async () => null),
 		normalizeFailureDetail: vi.fn((message) => message ?? "unknown"),
 		logInfo: vi.fn(),
 		logError: vi.fn(),
@@ -140,6 +141,67 @@ describe("runReportCommand", () => {
 		);
 	});
 
+	it("includes runtime observability fields in json output when snapshot is available", async () => {
+		const deps = createDeps({
+			loadRuntimeObservabilitySnapshot: vi.fn(async () => ({
+				version: 1,
+				updatedAt: 2000,
+				responsesRequests: 4,
+				authRefreshRequests: 2,
+				diagnosticProbeRequests: 1,
+				currentRequestId: "req_123",
+				poolExhaustionCooldownUntil: 9000,
+				serverBurstCooldownUntil: 12000,
+				runtimeMetrics: {
+					startedAt: 1000,
+					totalRequests: 4,
+					successfulRequests: 3,
+					failedRequests: 1,
+					responsesRequests: 4,
+					authRefreshRequests: 2,
+					diagnosticProbeRequests: 1,
+					outboundRequestAttemptBudget: 6,
+					outboundRequestAttemptsConsumed: 5,
+					requestAttemptBudgetExhaustions: 0,
+					poolExhaustionFastFails: 1,
+					serverBurstFastFails: 0,
+					rateLimitedResponses: 1,
+					serverErrors: 0,
+					networkErrors: 0,
+					userAborts: 0,
+					authRefreshFailures: 0,
+					emptyResponseRetries: 0,
+					accountRotations: 1,
+					sameAccountRetries: 0,
+					streamFailoverAttempts: 0,
+					streamFailoverCandidatesConsidered: 0,
+					lastStreamFailoverCandidateCount: 0,
+					streamFailoverRecoveries: 0,
+					streamFailoverCrossAccountRecoveries: 0,
+					cumulativeLatencyMs: 42,
+					lastRequestAt: 1999,
+					lastError: null,
+				},
+			})),
+		});
+
+		const result = await runReportCommand(["--json"], deps);
+
+		expect(result).toBe(0);
+		const jsonOutput = JSON.parse(
+			(deps.logInfo as ReturnType<typeof vi.fn>).mock.calls.at(-1)?.[0] ?? "{}",
+		) as {
+			runtime: {
+				poolExhaustionCooldownUntil: number;
+				serverBurstCooldownUntil: number;
+				runtimeMetrics: Record<string, unknown>;
+			};
+		};
+		expect(jsonOutput.runtime.poolExhaustionCooldownUntil).toBe(9000);
+		expect(jsonOutput.runtime.serverBurstCooldownUntil).toBe(12000);
+		expect(jsonOutput.runtime.runtimeMetrics).toBeDefined();
+	});
+
 	it("respects live probe account and probe budgets", async () => {
 		const deps = createDeps({
 			loadAccounts: vi.fn(async () =>
@@ -285,7 +347,7 @@ describe("runReportCommand", () => {
 		);
 		expect(jsonOutput.forecast.accounts[3]?.liveQuota?.planType).toBe("pro");
 		expect(jsonOutput.forecast.recommendation.selectedReason).toEqual(
-		expect.any(String),
+			"Lowest risk ready account (low, score 0).",
 		);
 	});
 
@@ -497,6 +559,7 @@ describe("runReportCommand", () => {
 
 		expect(result).toBe(0);
 		expect(deps.fetchCodexQuotaSnapshot).not.toHaveBeenCalled();
+		expect(deps.saveAccounts).toHaveBeenCalledTimes(4);
 		const jsonOutput = JSON.parse(
 			(deps.logInfo as ReturnType<typeof vi.fn>).mock.calls.at(-1)?.[0] ?? "{}",
 		) as {

test/config-explain.test.ts

@@ -39,6 +39,10 @@ describe("getPluginConfigExplainReport", () => {
 		delete process.env.CODEX_MODE;
 		delete process.env.CODEX_AUTH_FAST_SESSION_STRATEGY;
 		delete process.env.CODEX_MULTI_AUTH_CONFIG_PATH;
+		delete process.env.CODEX_AUTH_RATE_LIMIT_DEDUP_WINDOW_MS;
+		delete process.env.CODEX_AUTH_RATE_LIMIT_STATE_RESET_MS;
+		delete process.env.CODEX_AUTH_RATE_LIMIT_MAX_BACKOFF_MS;
+		delete process.env.CODEX_AUTH_RATE_LIMIT_SHORT_RETRY_THRESHOLD_MS;
 		for (const configPath of tempConfigPaths) {
 			await removeWithRetry(configPath, { force: true }).catch(() => {});
 		}