fix(forecast,runtime): review fixes for #670 and #671 — keep the default forecast on codex, harden the pinned-503 reset

docs/reference/error-contracts.md

@@ -120,11 +120,21 @@ The default-on localhost Responses proxy returns JSON error payloads with a stab
 | `runtime_rotation_proxy_unauthorized` | `401` | Local request did not include the per-process proxy client key |
 | `runtime_rotation_proxy_payload_too_large` | `413` | Request body exceeded the proxy safety cap |
 | `codex_runtime_rotation_pool_exhausted` | `429` or `503` | No managed account can currently service the runtime request |
-| `codex_pinned_account_unavailable` | `503` | A manual pin is set (via `codex-multi-auth switch`) but the pinned account is rate-limited, cooling down, disabled, or blocked by policy. Run `codex-multi-auth status` for details, or `codex-multi-auth unpin` to allow rotation |
+| `codex_pinned_account_unavailable` | `503` | A pin is in force — either a manual pin (`codex-multi-auth switch`) or a forced per-invocation pin (`--account` / `CODEX_MULTI_AUTH_FORCE_ACCOUNT_INDEX`) — but the pinned account is rate-limited, cooling down, disabled, or blocked by policy. The remedy depends on `pin_source` (see below) |
 | `codex_runtime_rotation_proxy_error` | `500` | Proxy failed before forwarding the request |
 
 Pool exhaustion includes a `reason`, `retry_after_ms`, and a hint to run `codex-multi-auth rotation status`. Pinned-account-unavailable responses include a `pinnedAccountIndex` field identifying the pinned account, a structured `reason` field carrying the runtime skip reason (for example `rate-limited`, `cooling-down:auth-failure`, `circuit-open`, `disabled`, `workspace-disabled`, `policy-blocked`, `missing`, `already-attempted`) or `null` when no reason was recorded, and an `account_skip_reasons` map keyed by account index that mirrors the pool-exhausted response shape. The human-readable `message` appends the same reason in parentheses when present (see issue #486).
 
+Pinned-account-unavailable responses also carry:
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `pin_source` | `"forced"`, `"manual"`, or `null` | `"forced"` when the pin came from `--account` / `CODEX_MULTI_AUTH_FORCE_ACCOUNT_INDEX`, `"manual"` when it came from `codex-multi-auth switch`. `unpin` clears only a manual pin, so the `message` tells a forced-pin caller to relaunch instead |
+| `reset_at` | ISO-8601 string or `null` | When the blocking state ends — the latest of the gating rate-limit record, the account cooldown, and the circuit-breaker deadline. `null` under a permanent blocker (`disabled`, `workspace-disabled`, `policy-blocked`, `missing`, invalidated auth) or when nothing bounds recovery |
+| `retry_after_ms` | number or `null` | `reset_at` expressed as a delay from the moment the response was built; `null` whenever `reset_at` is `null` |
+
+When `reset_at` is present the `message` appends `; the recorded limit resets at <ISO>`.
+
 Account policy pause/drain is enforced through runtime policy evaluation and contributes to selection skip reasons such as `policy-blocked`.
 
 ---

lib/accounts.ts

@@ -1294,6 +1294,22 @@ export class AccountManager {
 		return getCircuitBreaker(getAccountCircuitKey(account)).isAvailable();
 	}
 
+	/**
+	 * When the account's circuit breaker will admit an attempt again, as an
+	 * epoch-ms deadline — null when it already would. Lets the pinned-503
+	 * recovery metadata cover circuit-open skips, whose deadline lives in the
+	 * breaker rather than the persisted account record.
+	 */
+	getCircuitRecoveryTime(
+		account: ManagedAccount,
+		now = Date.now(),
+	): number | null {
+		const waitMs = getCircuitBreaker(
+			getAccountCircuitKey(account),
+		).getTimeUntilAvailable(now);
+		return waitMs > 0 ? now + waitMs : null;
+	}
+
 	incrementAuthFailures(account: ManagedAccount): number {
 		account.consecutiveAuthFailures =
 			(account.consecutiveAuthFailures ?? 0) + 1;

lib/codex-manager/commands/best.ts

@@ -1,6 +1,10 @@
 import type { ForecastAccountResult } from "../../forecast.js";
 import { type CodexQuotaSnapshot, describeCodexProbeFailure } from "../../quota-probe.js";
-import { resolveNormalizedModel } from "../../request/helpers/model-map.js";
+import {
+	getModelProfile,
+	type ModelFamily,
+	resolveNormalizedModel,
+} from "../../request/helpers/model-map.js";
 import type { AccountStorageV3 } from "../../storage.js";
 import type { TokenFailure, TokenResult } from "../../types.js";
 import { DEFAULT_LIVE_PROBE_MODEL } from "../quota-cache-helpers.js";
@@ -123,6 +127,7 @@ export interface BestCommandDeps {
 			now: number;
 			refreshFailure?: TokenFailure;
 			liveQuota?: CodexQuotaSnapshot;
+			family?: ModelFamily;
 		}>,
 	) => ForecastAccountResult[];
 	recommendForecastAccount: (results: ForecastAccountResult[]) => {
@@ -282,13 +287,24 @@ export async function runBestCommand(
 		}
 	}
 
+	// Resolved once, not once per account. Only an EXPLICIT `--model` may move
+	// the availability family: DEFAULT_LIVE_PROBE_MODEL is `gpt-5.6-sol`, whose
+	// prompt family is `gpt-5.2`, so deriving it unconditionally would let a bare
+	// `best` recommend an account that is rate-limited on the codex family the
+	// wrapper actually routes — and every Codex request would then 503 off the
+	// pin that recommendation produced.
+	const forecastFamily = options.modelProvided
+		? getModelProfile(probeModel).promptFamily
+		: undefined;
+	const forecastActiveIndex = deps.resolveActiveIndex(storage, "codex");
 	const forecastInputs = storage.accounts.map((account, index) => ({
 		index,
 		account,
-		isCurrent: index === deps.resolveActiveIndex(storage, "codex"),
+		isCurrent: index === forecastActiveIndex,
 		now,
 		refreshFailure: refreshFailures.get(index),
 		liveQuota: liveQuotaByIndex.get(index),
+		family: forecastFamily,
 	}));
 	const forecastResults = deps.evaluateForecastAccounts(forecastInputs);
 	const recommendation = deps.recommendForecastAccount(forecastResults);

lib/codex-manager/commands/forecast.ts

@@ -14,7 +14,12 @@ import {
 } from "../forecast-report-shared.js";
 import type { QuotaCacheData } from "../../quota-cache.js";
 import { type CodexQuotaSnapshot, describeCodexProbeFailure } from "../../quota-probe.js";
-import { DEFAULT_PROBE_MODEL, resolveNormalizedModel } from "../../request/helpers/model-map.js";
+import {
+	DEFAULT_PROBE_MODEL,
+	getModelProfile,
+	type ModelFamily,
+	resolveNormalizedModel,
+} from "../../request/helpers/model-map.js";
 import { type AccountMetadataV3, type AccountStorageV3 } from "../../storage.js";
 import type { TokenFailure, TokenResult } from "../../types.js";
 
@@ -23,6 +28,14 @@ interface ForecastCliOptions {
 	json: boolean;
 	explain: boolean;
 	model: string;
+	/**
+	 * True only when the invocation actually carried `--model`. `model` always
+	 * holds a value (it falls back to DEFAULT_PROBE_MODEL so the probe and the
+	 * header have something to name), so it cannot distinguish an explicit
+	 * request from the default — and the availability family must never follow a
+	 * default the user did not ask for.
+	 */
+	modelProvided: boolean;
 	runtimeOverlay: boolean;
 }
 
@@ -85,6 +98,7 @@ export interface ForecastCommandDeps {
 			quotaCache?: QuotaCacheData | null;
 			allAccounts?: readonly AccountMetadataV3[];
 			runtimeOverlay?: RuntimeForecastOverlay | null;
+			family?: ModelFamily;
 		}>,
 	) => ForecastAccountResult[];
 	summarizeForecast: (results: ForecastAccountResult[]) => {
@@ -150,6 +164,7 @@ function parseForecastArgs(
 		json: false,
 		explain: false,
 		model: DEFAULT_PROBE_MODEL,
+		modelProvided: false,
 		runtimeOverlay: true,
 	};
 
@@ -178,6 +193,7 @@ function parseForecastArgs(
 				return { ok: false, message: "Missing value for --model" };
 			}
 			options.model = value;
+			options.modelProvided = true;
 			i += 1;
 			continue;
 		}
@@ -187,6 +203,7 @@ function parseForecastArgs(
 				return { ok: false, message: "Missing value for --model" };
 			}
 			options.model = value;
+			options.modelProvided = true;
 			continue;
 		}
 		return { ok: false, message: `Unknown option: ${arg}` };
@@ -217,6 +234,18 @@ export async function runForecastCommand(
 	const options = parsedArgs.options;
 	const requestedModel = options.model?.trim() || DEFAULT_PROBE_MODEL;
 	const probeModel = resolveNormalizedModel(requestedModel);
+	// Resolved once, not once per account: getModelProfile re-parses and
+	// re-resolves the model string on every call.
+	//
+	// Only an EXPLICIT `--model` may move the availability family. The default
+	// probe model is `gpt-5.6-sol`, whose prompt family is `gpt-5.2`, so
+	// deriving the family unconditionally would flip a bare `forecast` off the
+	// codex family and report a codex-rate-limited account as `ready` — the
+	// exact forecast/runtime desync this threading exists to remove, aimed at
+	// the default invocation instead.
+	const forecastFamily = options.modelProvided
+		? getModelProfile(requestedModel).promptFamily
+		: undefined;
 	const display = deps.loadDashboardDisplaySettings
 		? (await deps.loadDashboardDisplaySettings().catch(() => null)) ??
 			deps.defaultDisplay
@@ -368,6 +397,7 @@ export async function runForecastCommand(
 		quotaCache,
 		allAccounts: storage.accounts,
 		runtimeOverlay,
+		family: forecastFamily,
 	}));
 	const forecastResults = deps.evaluateForecastAccounts(forecastInputs);
 	const summary = deps.summarizeForecast(forecastResults);

lib/codex-manager/commands/report.ts

@@ -46,6 +46,14 @@ interface ReportCliOptions {
 	json: boolean;
 	explain: boolean;
 	model: string;
+	/**
+	 * True only when the invocation actually carried `--model`. `model` always
+	 * holds a value (it falls back to DEFAULT_PROBE_MODEL for the probe and the
+	 * `modelSelection` block), so it cannot distinguish an explicit request from
+	 * the default — and the availability family must never follow a default the
+	 * user did not ask for.
+	 */
+	modelProvided: boolean;
 	maxAccounts?: number;
 	maxProbes?: number;
 	cachedOnly: boolean;
@@ -144,6 +152,7 @@ function parseReportArgs(args: string[]): ParsedArgsResult<ReportCliOptions> {
 		json: false,
 		explain: false,
 		model: DEFAULT_PROBE_MODEL,
+		modelProvided: false,
 		cachedOnly: false,
 	};
 
@@ -172,6 +181,7 @@ function parseReportArgs(args: string[]): ParsedArgsResult<ReportCliOptions> {
 				return { ok: false, message: "Missing value for --model" };
 			}
 			options.model = value;
+			options.modelProvided = true;
 			i += 1;
 			continue;
 		}
@@ -181,6 +191,7 @@ function parseReportArgs(args: string[]): ParsedArgsResult<ReportCliOptions> {
 				return { ok: false, message: "Missing value for --model" };
 			}
 			options.model = value;
+			options.modelProvided = true;
 			continue;
 		}
 		if (arg === "--max-accounts") {
@@ -462,6 +473,16 @@ export async function runReportCommand(
 		}
 	}
 
+	// `inspectRequestedModel` already resolved the profile, so reuse its
+	// `promptFamily` instead of re-resolving the model once per account.
+	//
+	// Only an EXPLICIT `--model` may move the availability family: the default
+	// probe model is `gpt-5.6-sol`, whose prompt family is `gpt-5.2`, so
+	// deriving it unconditionally would make a bare `report` describe gpt-5.2
+	// availability while the wrapper routes codex-family traffic.
+	const forecastFamily = options.modelProvided
+		? modelInspection.promptFamily
+		: undefined;
 	const forecastResults = storage
 		? evaluateForecastAccounts(
 				storage.accounts.map((account, index) => ({
@@ -474,6 +495,7 @@ export async function runReportCommand(
 					quotaCache,
 					allAccounts: storage.accounts,
 					runtimeOverlay: runtimeSnapshot,
+					family: forecastFamily,
 				})),
 			)
 		: [];

lib/forecast.ts

@@ -10,6 +10,7 @@ import {
 	isQuotaCacheEntryExhausted,
 	quotaUsedPercentIsExhausted,
 } from "./quota-readiness.js";
+import type { ModelFamily } from "./request/helpers/model-map.js";
 import { getRateLimitResetTimeForFamily } from "./runtime/account-status.js";
 import type { AccountMetadataV3 } from "./storage.js";
 import type { TokenFailure } from "./types.js";
@@ -27,6 +28,12 @@ export interface ForecastAccountInput {
 	quotaCache?: QuotaCacheData | null;
 	allAccounts?: readonly AccountMetadataV3[];
 	runtimeOverlay?: RuntimeForecastOverlay | null;
+	/**
+	 * Prompt family whose per-family rate-limit records gate this forecast.
+	 * Callers with a model in hand resolve it via getModelProfile; the codex
+	 * default preserves the historical behavior for model-less surfaces.
+	 */
+	family?: ModelFamily;
 }
 
 export interface RuntimeForecastOverlay {
@@ -245,7 +252,7 @@ export function evaluateForecastAccount(
 	const rateLimitResetAt = getRateLimitResetTimeForFamily(
 		account,
 		now,
-		"codex",
+		input.family ?? "codex",
 	);
 	if (typeof rateLimitResetAt === "number") {
 		const remaining = Math.max(0, rateLimitResetAt - now);
@@ -298,7 +305,10 @@ export function evaluateForecastAccount(
 	// drop the overlay reason when the condition it describes is no longer
 	// active. Each reason validates only against its own backing disk state
 	// ("rate-limited" -> rateLimitResetTimes, "cooling-down" -> coolingDownUntil)
-	// so we never substitute a misleading reason string. Non-time-bounded
+	// so we never substitute a misleading reason string. The rate-limited
+	// cross-check is family-aware through rateLimitResetAt above: a record for
+	// the forecast's own family keeps the reason, while a record for another
+	// family neither sustains it nor gates this model's availability. Non-time-bounded
 	// reasons ("circuit-open", "token-exhausted", "policy-blocked") have no disk
 	// expiry to check and are always applied.
 	const coolingDownActive =

lib/request/rate-limit-decision.ts

@@ -185,12 +185,34 @@ export interface PinnedUnavailableErrorBody {
 	code: "codex_pinned_account_unavailable";
 	pinnedAccountIndex: number | null;
 	reason: string | null;
+	/** How the pin was set; forced pins are not cleared by `unpin`. */
+	pin_source: "forced" | "manual" | null;
+	/** When the blocking record ends, when the skip reason is time-bounded. */
+	reset_at: string | null;
+	retry_after_ms: number | null;
 	account_skip_reasons: Record<string, string>;
 }
 
+/** Largest epoch-ms a `Date` can represent; beyond it `toISOString()` throws. */
+const MAX_ECMASCRIPT_TIME_MS = 8.64e15;
+
+export interface PinnedUnavailableContext {
+	/**
+	 * "forced" when the pin came from the wrapper's forced-account mode
+	 * (`--account` / CODEX_MULTI_AUTH_FORCE_ACCOUNT_INDEX), "manual" when it
+	 * came from `switch`. `unpin` clears only the manual kind, so the remedy
+	 * line must not suggest it for a forced pin.
+	 */
+	pinSource?: "forced" | "manual" | null;
+	/** Epoch ms when the blocking record ends (rate limit or cooldown). */
+	resetAtMs?: number | null;
+	now?: number;
+}
+
 export function buildPinnedUnavailableErrorBody(
 	pinnedIndex: number | null | undefined,
 	accountSkipReasons: ReadonlyMap<number, string>,
+	context?: PinnedUnavailableContext,
 ): PinnedUnavailableErrorBody {
 	const normalizedPinnedIndex =
 		typeof pinnedIndex === "number" ? pinnedIndex : null;
@@ -205,11 +227,39 @@ export function buildPinnedUnavailableErrorBody(
 		normalizedPinnedIndex === null
 			? "The pinned account"
 			: `Pinned account ${normalizedPinnedIndex + 1}`;
+	const pinSource = context?.pinSource ?? null;
+	const resetAtMs =
+		typeof context?.resetAtMs === "number" &&
+		Number.isFinite(context.resetAtMs) &&
+		context.resetAtMs > 0 &&
+		// `new Date(x).toISOString()` throws RangeError past the ECMAScript time
+		// range. The deadline is read from persisted account state
+		// (`rateLimitResetTimes`, `coolingDownUntil`) which a corrupted or
+		// hand-edited storage file can carry out of range, and this builder runs
+		// on the 503 path: a throw here would drop the pin diagnostics entirely
+		// and surface the proxy's generic 500 instead.
+		context.resetAtMs <= MAX_ECMASCRIPT_TIME_MS
+			? context.resetAtMs
+			: null;
+	const now = context?.now ?? Date.now();
+	const retryAfterMs = resetAtMs !== null ? Math.max(0, resetAtMs - now) : null;
+	const resetAt = resetAtMs !== null ? new Date(resetAtMs).toISOString() : null;
+	const waitSuffix =
+		resetAt !== null ? `; the recorded limit resets at ${resetAt}` : "";
+	// A forced pin belongs to the launching process, not to the persisted pin
+	// state, so `unpin` would clear nothing — say what actually helps.
+	const remedy =
+		pinSource === "forced"
+			? "the pin was set by this session's launcher, so relaunch to select a different account"
+			: "run `codex-multi-auth status` for details, or `codex-multi-auth unpin` to allow rotation";
 	return {
-		message: `${accountPhrase} is currently unavailable${reasonSuffix}; run \`codex-multi-auth status\` for details, or \`codex-multi-auth unpin\` to allow rotation.`,
+		message: `${accountPhrase} is currently unavailable${reasonSuffix}${waitSuffix}; ${remedy}.`,
 		code: "codex_pinned_account_unavailable",
 		pinnedAccountIndex: normalizedPinnedIndex,
 		reason: skipReason,
+		pin_source: pinSource,
+		reset_at: resetAt,
+		retry_after_ms: retryAfterMs,
 		account_skip_reasons: Object.fromEntries(
 			[...accountSkipReasons.entries()].map(([index, reason]) => [
 				String(index),