@bitkyc08/opencodex 2.7.39 → 2.7.40-preview.20260725

package/src/codex/catalog/provider-fetch.ts

@@ -14,6 +14,7 @@ import {
   markModelsFetchFailure,
   markProviderDiscoveryFailed,
   markProviderDiscoveryOk,
+  shouldLogDiscoveryFailure,
   setCached,
   type ProviderModelDiscoveryFailure,
 } from "../model-cache";
@@ -302,7 +303,11 @@ export async function fetchProviderModels(name: string, prov: OcxProviderConfig,
     : "provider-models";
   const failedDiscoveryFallback = (
     failure: ProviderModelDiscoveryFailure,
-  ): { models: CatalogModel[]; fallback: "stale" | "configured" } => {
+  ): { models: CatalogModel[]; fallback: "stale" | "configured"; shouldLog: boolean } => {
+    // Decide logging BEFORE recording the new status, so we can compare against the prior one and
+    // suppress an identical repeated failure (#395 log flood). The failure stays observable via the
+    // discovery-status API regardless.
+    const shouldLog = shouldLogDiscoveryFailure(name, failure);
     markModelsFetchFailure(name);
     markProviderDiscoveryFailed(name, failure);
     const stale = getStaleCached(name);
@@ -311,6 +316,7 @@ export async function fetchProviderModels(name: string, prov: OcxProviderConfig,
         ? withVertexDefaultSeed(applyConfigHintsToCachedModels(name, prov, stale, contextCap))
         : failedDiscoveryConfigured,
       fallback: stale ? "stale" : "configured",
+      shouldLog,
     };
   };
   try {
@@ -319,19 +325,23 @@ export async function fetchProviderModels(name: string, prov: OcxProviderConfig,
       allowPrivateNetwork: prov.allowPrivateNetwork,
     });
     if (destinationError) {
-      const { models, fallback } = failedDiscoveryFallback({ reason: "blocked" });
-      console.warn(
-        `[opencodex] Provider model discovery for "${name}" was blocked by destination policy: ${destinationError} [urlClass=${urlClass}, fallback=${fallback}].`,
-      );
+      const { models, fallback, shouldLog } = failedDiscoveryFallback({ reason: "blocked" });
+      if (shouldLog) {
+        console.warn(
+          `[opencodex] Provider model discovery for "${name}" was blocked by destination policy: ${destinationError} [urlClass=${urlClass}, fallback=${fallback}].`,
+        );
+      }
       return models;
     }
 
     const res = await fetch(url, { headers, signal: AbortSignal.timeout(8000) });
     if (!res.ok) {
-      const { models, fallback } = failedDiscoveryFallback({ reason: "http", httpStatus: res.status });
-      console.warn(
-        `[opencodex] Provider model discovery for "${name}" failed with HTTP ${res.status} [urlClass=${urlClass}, fallback=${fallback}].`,
-      );
+      const { models, fallback, shouldLog } = failedDiscoveryFallback({ reason: "http", httpStatus: res.status });
+      if (shouldLog) {
+        console.warn(
+          `[opencodex] Provider model discovery for "${name}" failed with HTTP ${res.status} [urlClass=${urlClass}, fallback=${fallback}].`,
+        );
+      }
       return models;
     }
 
@@ -343,23 +353,27 @@ export async function fetchProviderModels(name: string, prov: OcxProviderConfig,
     try {
       json = JSON.parse(body) as unknown;
     } catch {
-      const { models, fallback } = failedDiscoveryFallback({ reason: "invalid_response" });
+      const { models, fallback, shouldLog } = failedDiscoveryFallback({ reason: "invalid_response" });
       const diagnostic = contentType === "application/json" || contentType.endsWith("+json")
         ? "returned invalid JSON in a 2xx response"
         : "returned a non-JSON 2xx response";
-      console.warn(
-        `[opencodex] Provider model discovery for "${name}" ${diagnostic} [status=${res.status}, contentType=${contentType}, urlClass=${urlClass}, fallback=${fallback}].`,
-      );
+      if (shouldLog) {
+        console.warn(
+          `[opencodex] Provider model discovery for "${name}" ${diagnostic} [status=${res.status}, contentType=${contentType}, urlClass=${urlClass}, fallback=${fallback}].`,
+        );
+      }
       return models;
     }
     const data = json !== null && typeof json === "object" && !Array.isArray(json)
       ? (json as { data?: unknown }).data
       : undefined;
     if (!isProviderModelsApiItems(data)) {
-      const { models, fallback } = failedDiscoveryFallback({ reason: "invalid_response" });
-      console.warn(
-        `[opencodex] Provider model discovery for "${name}" returned malformed 2xx data [status=${res.status}, contentType=${contentType}, urlClass=${urlClass}, fallback=${fallback}].`,
-      );
+      const { models, fallback, shouldLog } = failedDiscoveryFallback({ reason: "invalid_response" });
+      if (shouldLog) {
+        console.warn(
+          `[opencodex] Provider model discovery for "${name}" returned malformed 2xx data [status=${res.status}, contentType=${contentType}, urlClass=${urlClass}, fallback=${fallback}].`,
+        );
+      }
       return models;
     }
     const items = data;
@@ -402,10 +416,12 @@ export async function fetchProviderModels(name: string, prov: OcxProviderConfig,
     setCached(name, live);
     return live;
   } catch (error) {
-    const { models, fallback } = failedDiscoveryFallback({ reason: "network" });
-    console.warn(
-      `[opencodex] Provider model discovery for "${name}" threw ${error instanceof Error ? error.name : "unknown"} [urlClass=${urlClass}, fallback=${fallback}].`,
-    );
+    const { models, fallback, shouldLog } = failedDiscoveryFallback({ reason: "network" });
+    if (shouldLog) {
+      console.warn(
+        `[opencodex] Provider model discovery for "${name}" threw ${error instanceof Error ? error.name : "unknown"} [urlClass=${urlClass}, fallback=${fallback}].`,
+      );
+    }
     return models;
   }
 }
@@ -525,10 +541,13 @@ export async function gatherRoutedModels(config: OcxConfig): Promise<CatalogMode
     else warnUncataloguedComboOnce(id, combo, members);
   }
   all.sort((a, b) => (a.provider === b.provider ? a.id.localeCompare(b.id) : a.provider.localeCompare(b.provider)));
+  // Enriched (registry-hydrated) provider clones, keyed by name — the same view used above so
+  // custom rows get the same noVisionModels / inputModalities treatment as discovered rows.
+  const enrichedByName = new Map(activeProviders);
   const customModels = (config.customModels ?? []).map(cm => {
-    const provider = config.providers[cm.provider] as OcxProviderConfigWithReasoningSummaries | undefined;
-    const supportsReasoningSummaries = modelRecordValue(provider?.modelSupportsReasoningSummaries, cm.modelId);
-    return {
+    const rawProvider = config.providers[cm.provider] as OcxProviderConfigWithReasoningSummaries | undefined;
+    const supportsReasoningSummaries = modelRecordValue(rawProvider?.modelSupportsReasoningSummaries, cm.modelId);
+    const base: CatalogModel = {
       id: cm.modelId,
       provider: cm.provider,
       // Display-only label: never feeds routing (customModels are keyed by routedSlug below).
@@ -537,6 +556,19 @@ export async function gatherRoutedModels(config: OcxConfig): Promise<CatalogMode
       ...(cm.inputModalities ? { inputModalities: cm.inputModalities } : {}),
       ...(typeof supportsReasoningSummaries === "boolean" ? { supportsReasoningSummaries } : {}),
     };
+    // Vision-sidecar coverage ONLY: if the custom model is in the enriched provider's
+    // noVisionModels, advertise image input so the Codex app lets images reach the sidecar
+    // (#349/#344). Deliberately NOT the full applyProviderConfigHints pass — custom rows are a
+    // user override, so their explicit contextWindow / inputModalities / reasoning fields must be
+    // preserved verbatim (the hint pass would cap context and overwrite modalities from registry).
+    const enrichedProvider = enrichedByName.get(cm.provider) ?? rawProvider;
+    if (enrichedProvider && modelInList(enrichedProvider.noVisionModels, base.id)) {
+      const current = base.inputModalities ?? ["text"];
+      if (!current.includes("image")) {
+        return { ...base, inputModalities: [...current, "image"] };
+      }
+    }
+    return base;
   });
   // Custom rows override discovered rows that encode to the same Codex-facing slug.
   const customKeys = new Set(customModels.map(c => routedSlug(c.provider, c.id)));

package/src/codex/model-cache.ts

@@ -63,6 +63,29 @@ export function markProviderDiscoveryFailed(
   discoveryStatus.set(provider, { status: "failed", ...failure });
 }
 
+/**
+ * Decide whether a discovery FAILURE should be logged, to avoid flooding the log with an identical
+ * warning on every poll (#395: an anthropic-adapter baseUrl without `/v1/models`, e.g. Azure AI
+ * Foundry, returns HTTP 404 forever; the 30s cooldown re-probes and previously re-logged each time).
+ *
+ * Returns true only when the failure SIGNATURE changed since the last observed status — i.e. the
+ * previous state was ok/undefined, or a different reason/httpStatus. Repeated identical failures
+ * stay observable through `getProviderDiscoveryStatus()` / the providers API without log spam.
+ * Call this BEFORE `markProviderDiscoveryFailed` so it can see the prior state.
+ */
+export function shouldLogDiscoveryFailure(
+  provider: string,
+  failure: ProviderModelDiscoveryFailure,
+): boolean {
+  const prev = discoveryStatus.get(provider);
+  if (!prev || prev.status !== "failed") return true;
+  if (prev.reason !== failure.reason) return true;
+  if (prev.reason === "http" && failure.reason === "http") {
+    return prev.httpStatus !== failure.httpStatus;
+  }
+  return false;
+}
+
 export function clearProviderDiscoveryStatus(provider: string): void {
   discoveryStatus.delete(provider);
 }

package/src/codex/quota.ts

@@ -28,6 +28,7 @@ type WhamUsageWindow = {
 };
 
 const MONTHLY_WINDOW_MIN_SECONDS = 28 * 24 * 60 * 60;
+const MONTHLY_WINDOW_MIN_MINUTES = MONTHLY_WINDOW_MIN_SECONDS / 60;
 
 const accountQuota = new Map<string, StoredAccountQuota>();
 
@@ -65,6 +66,125 @@ function isExplicitMonthlyWindow(window: WhamUsageWindow | null | undefined): bo
     && seconds >= MONTHLY_WINDOW_MIN_SECONDS;
 }
 
+function isExplicitMonthlyWindowMinutes(windowMinutes: unknown): boolean {
+  const minutes = typeof windowMinutes === "number"
+    ? windowMinutes
+    : typeof windowMinutes === "string" && windowMinutes.trim() !== ""
+      ? Number(windowMinutes)
+      : undefined;
+  return typeof minutes === "number"
+    && Number.isFinite(minutes)
+    && minutes >= MONTHLY_WINDOW_MIN_MINUTES;
+}
+
+
+function snapshotHasWeekly(quota: Omit<StoredAccountQuota, "updatedAt">): boolean {
+  return quota.weeklyPercent !== undefined || quota.weeklyResetAt !== undefined;
+}
+
+function snapshotHasMonthly(quota: Omit<StoredAccountQuota, "updatedAt">): boolean {
+  return quota.monthlyPercent !== undefined || quota.monthlyResetAt !== undefined;
+}
+
+function snapshotHasUsage(quota: Omit<StoredAccountQuota, "updatedAt">): boolean {
+  return snapshotHasWeekly(quota) || snapshotHasMonthly(quota);
+}
+export function setAccountQuotaFromParsed(
+  accountId: string,
+  quota: Omit<StoredAccountQuota, "updatedAt"> | null,
+): void {
+  if (!quota) return;
+  const existing = accountQuota.get(accountId);
+  const next: StoredAccountQuota = { updatedAt: Date.now() };
+  const creditsOnly = quota.resetCredits !== undefined && !snapshotHasUsage(quota);
+
+  if (creditsOnly) {
+    if (existing?.weeklyPercent !== undefined) next.weeklyPercent = existing.weeklyPercent;
+    if (existing?.weeklyResetAt !== undefined) next.weeklyResetAt = existing.weeklyResetAt;
+    if (existing?.monthlyPercent !== undefined) next.monthlyPercent = existing.monthlyPercent;
+    if (existing?.monthlyResetAt !== undefined) next.monthlyResetAt = existing.monthlyResetAt;
+    next.resetCredits = quota.resetCredits;
+    accountQuota.set(accountId, next);
+    return;
+  }
+
+  if (snapshotHasWeekly(quota)) {
+    if (quota.weeklyPercent !== undefined) next.weeklyPercent = quota.weeklyPercent;
+    if (quota.weeklyResetAt !== undefined) next.weeklyResetAt = quota.weeklyResetAt;
+  } else if (snapshotHasMonthly(quota) && !snapshotHasWeekly(quota)) {
+    // Monthly-only snapshots intentionally clear stale weekly values (issue #382).
+  } else if (existing?.weeklyPercent !== undefined) {
+    next.weeklyPercent = existing.weeklyPercent;
+    if (existing.weeklyResetAt !== undefined) next.weeklyResetAt = existing.weeklyResetAt;
+  }
+
+  if (snapshotHasMonthly(quota)) {
+    if (quota.monthlyPercent !== undefined) next.monthlyPercent = quota.monthlyPercent;
+    if (quota.monthlyResetAt !== undefined) next.monthlyResetAt = quota.monthlyResetAt;
+  } else if (snapshotHasWeekly(quota) && existing?.monthlyPercent !== undefined) {
+    next.monthlyPercent = existing.monthlyPercent;
+    if (existing.monthlyResetAt !== undefined) next.monthlyResetAt = existing.monthlyResetAt;
+  }
+
+  if (quota.resetCredits !== undefined) next.resetCredits = quota.resetCredits;
+  else if (existing?.resetCredits !== undefined) next.resetCredits = existing.resetCredits;
+
+  accountQuota.set(accountId, next);
+}
+
+export function parseUpstreamQuotaHeaders(headers: Headers): Omit<StoredAccountQuota, "updatedAt"> | null {
+  const primaryRaw = headers.get("x-codex-primary-used-percent");
+  const secondaryRaw = headers.get("x-codex-secondary-used-percent");
+  const tertiaryRaw = headers.get("x-codex-tertiary-used-percent");
+  const primaryResetRaw = headers.get("x-codex-primary-reset-at");
+  const secondaryResetRaw = headers.get("x-codex-secondary-reset-at");
+  const tertiaryResetRaw = headers.get("x-codex-tertiary-reset-at");
+  const primaryWindowMinutes = headers.get("x-codex-primary-window-minutes");
+  const secondaryWindowMinutes = headers.get("x-codex-secondary-window-minutes");
+
+  const quota: Omit<StoredAccountQuota, "updatedAt"> = {};
+  const primaryPercent = normalizeUsagePercent(primaryRaw);
+  const secondaryPercent = normalizeUsagePercent(secondaryRaw);
+  const tertiaryPercent = normalizeUsagePercent(tertiaryRaw);
+  const primaryResetAt = normalizeResetAt(primaryResetRaw);
+  const secondaryResetAt = normalizeResetAt(secondaryResetRaw);
+  const tertiaryResetAt = normalizeResetAt(tertiaryResetRaw);
+  const primaryIsMonthly = primaryRaw !== null && isExplicitMonthlyWindowMinutes(primaryWindowMinutes);
+
+  if (primaryIsMonthly) {
+    if (primaryPercent !== undefined) {
+      quota.monthlyPercent = primaryPercent;
+      if (primaryResetAt !== undefined) quota.monthlyResetAt = primaryResetAt;
+    }
+    if (secondaryPercent !== undefined) {
+      quota.weeklyPercent = secondaryPercent;
+      if (secondaryResetAt !== undefined) quota.weeklyResetAt = secondaryResetAt;
+    }
+  } else {
+    const weeklyPercent = primaryPercent ?? secondaryPercent;
+    const weeklyResetAt = primaryPercent !== undefined
+      ? primaryResetAt
+      : secondaryResetAt;
+    if (weeklyPercent !== undefined) {
+      quota.weeklyPercent = weeklyPercent;
+      if (weeklyResetAt !== undefined) quota.weeklyResetAt = weeklyResetAt;
+    }
+  }
+
+  if (tertiaryPercent !== undefined && quota.monthlyPercent === undefined) {
+    quota.monthlyPercent = tertiaryPercent;
+    if (tertiaryResetAt !== undefined) quota.monthlyResetAt = tertiaryResetAt;
+  }
+
+  return hasKnownQuotaValue(quota) ? quota : null;
+}
+
+export function applyAccountQuotaFromUpstreamHeaders(accountId: string, headers: Headers): void {
+  const quota = parseUpstreamQuotaHeaders(headers);
+  if (!quota) return;
+  setAccountQuotaFromParsed(accountId, quota);
+}
+
 export function updateAccountQuota(
   accountId: string,
   weekly: unknown,

package/src/codex/routing.ts

@@ -1,3 +1,4 @@
+import { randomUUID } from "node:crypto";
 import { saveConfig } from "../config";
 import { isCodexAccountGenerationLive, readCodexAccountRecord } from "./account-store";
 import { codexAccountLogLabel } from "./account-label";
@@ -31,6 +32,29 @@ type CodexUpstreamHealth = {
   lastFailureAt?: number;
   /** Hard cooldown (quota 429). Survives a later 2xx; blocks auth + selection. */
   cooldownUntil?: number;
+  /** When the current cooldown was recorded; origin of the probe interval clock. */
+  cooldownSince?: number;
+  /**
+   * What produced the cooldown. An explicit Retry-After is a literal retry
+   * directive and is never probed; a quota resetAt only announces a window
+   * refresh, so it may be probed early (#433).
+   */
+  cooldownSource?: CodexCooldownSource;
+  /**
+   * Bumped on every cooldown write. A probe lease records the generation it was
+   * issued for so a lease cannot clear a cooldown that a later 429 replaced.
+   */
+  cooldownGeneration?: number;
+  /**
+   * Identity of the in-flight probe. A cooled-down account sends no traffic, so
+   * no organic 2xx can prove recovery; only the outcome carrying this id may
+   * clear the cooldown.
+   */
+  probeLeaseId?: string;
+  /** Cooldown generation at the moment the lease was granted. */
+  probeLeaseGeneration?: number;
+  /** Last probe grant or conclusion; paces the probe interval. */
+  lastProbeAt?: number;
   /**
    * Soft avoid after connect_error / timeout / transient 5xx. Cleared on 2xx.
    * Blocks pool selection + thread affinity reuse so a sticky session can leave a
@@ -41,6 +65,15 @@ type CodexUpstreamHealth = {
 
 const CODEX_DEFAULT_QUOTA_COOLDOWN_MS = 60_000;
 const CODEX_MAX_QUOTA_COOLDOWN_MS = 24 * 60 * 60_000;
+/**
+ * A weekly/monthly quota `resetAt` announces when the window refreshes; it is not
+ * a "come back after this" directive like Retry-After. Plan quota routinely frees
+ * up long before the advertised reset, so cap reset-derived cooldowns far below
+ * the Retry-After ceiling (#433).
+ */
+const CODEX_MAX_RESET_DERIVED_COOLDOWN_MS = 15 * 60_000;
+/** Minimum gap between probe leases for one cooled-down account. */
+export const CODEX_QUOTA_PROBE_INTERVAL_MS = 5 * 60_000;
 export const CODEX_FAILURE_WINDOW_MS = 5 * 60_000;
 /** How long a transient failure keeps the account out of pool selection. */
 export const CODEX_TRANSIENT_SOFT_AVOID_MS = 30_000;
@@ -60,12 +93,19 @@ const upstreamHealth = new Map<string, CodexUpstreamHealth>();
 
 export type CodexUpstreamOutcome = number | "connect_error" | "timeout";
 export type CodexUpstreamOutcomeClass = "success" | "credential" | "quota" | "transient" | "caller" | "unknown";
+export type CodexCooldownSource = "retry-after" | "reset-derived" | "default";
 export type CodexUpstreamOutcomeMeta = {
   retryAfter?: string | null;
   resetAt?: unknown | unknown[];
   now?: number;
   /** When set, clears affinity for this thread immediately on transient failure. */
   threadId?: string | null;
+  /**
+   * Probe lease held by this request, when it was admitted through an active
+   * quota cooldown. Only the outcome carrying the current lease may clear the
+   * cooldown (#433).
+   */
+  probeLeaseId?: string;
 };
 
 function hasConfiguredPoolAccount(config: OcxConfig, accountId: string): boolean {
@@ -159,17 +199,104 @@ export function parseResetCooldownMs(resetAt: unknown | unknown[] | undefined, n
     if (timestamp === undefined) continue;
     const delay = timestamp - now;
     if (delay <= 0) continue;
-    const clamped = clampCooldownMs(delay);
+    // A far-future reset must not pin the account for the full Retry-After
+    // ceiling: quota usually frees up well before the advertised window (#433).
+    const clamped = Math.min(clampCooldownMs(delay), CODEX_MAX_RESET_DERIVED_COOLDOWN_MS);
     if (best === undefined || clamped < best) best = clamped;
   }
   return best;
 }
 
-export function computeQuotaCooldownUntil(meta: CodexUpstreamOutcomeMeta = {}): number {
+export function computeQuotaCooldown(meta: CodexUpstreamOutcomeMeta = {}): {
+  until: number;
+  source: CodexCooldownSource;
+} {
   const now = meta.now ?? Date.now();
   const retryAfterMs = parseRetryAfterMs(meta.retryAfter, now);
-  const resetCooldownMs = retryAfterMs === undefined ? parseResetCooldownMs(meta.resetAt, now) : undefined;
-  return now + (retryAfterMs ?? resetCooldownMs ?? CODEX_DEFAULT_QUOTA_COOLDOWN_MS);
+  if (retryAfterMs !== undefined) return { until: now + retryAfterMs, source: "retry-after" };
+  const resetCooldownMs = parseResetCooldownMs(meta.resetAt, now);
+  if (resetCooldownMs !== undefined) return { until: now + resetCooldownMs, source: "reset-derived" };
+  return { until: now + CODEX_DEFAULT_QUOTA_COOLDOWN_MS, source: "default" };
+}
+
+export function computeQuotaCooldownUntil(meta: CodexUpstreamOutcomeMeta = {}): number {
+  return computeQuotaCooldown(meta).until;
+}
+
+/**
+ * Grant at most one probe lease per interval for a cooled-down account.
+ *
+ * A cooled-down account is short-circuited locally, so it never sends traffic and
+ * no organic 2xx can prove that upstream quota recovered — the cooldown can only
+ * end by expiry or a proxy restart (#433). Releasing a single probe breaks that
+ * deadlock. Explicit Retry-After cooldowns are excluded: those are literal retry
+ * directives, not window announcements.
+ *
+ * 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;
+  const probeLeaseId = randomUUID();
+  upstreamHealth.set(accountId, {
+    ...health,
+    probeLeaseId,
+    probeLeaseGeneration: health.cooldownGeneration ?? 0,
+    lastProbeAt: now,
+  });
+  return probeLeaseId;
+}
+
+/**
+ * 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.
+ */
+export function releaseCodexQuotaProbeLease(accountId: string, leaseId: string, now = Date.now()): void {
+  const health = upstreamHealth.get(accountId);
+  if (!health || health.probeLeaseId !== leaseId) return;
+  upstreamHealth.set(accountId, withProbeLeaseReleased(health, now));
+}
+
+/**
+ * True when this outcome belongs to the account's in-flight probe. The
+ * undefined-id guard matters: without it an outcome carrying no lease would match
+ * an account holding no lease and be mistaken for the probe owner.
+ */
+function ownsProbeLease(health: CodexUpstreamHealth | undefined, meta: CodexUpstreamOutcomeMeta): boolean {
+  return meta.probeLeaseId !== undefined && meta.probeLeaseId === health?.probeLeaseId;
+}
+
+/**
+ * True when the owning probe may still clear the cooldown. A later 429 bumps the
+ * generation, so a probe that started under an older cooldown must not erase the
+ * newer restriction (which may carry an explicit Retry-After).
+ */
+function probeMayClearCooldown(health: CodexUpstreamHealth | undefined, meta: CodexUpstreamOutcomeMeta): boolean {
+  return ownsProbeLease(health, meta)
+    && (health!.probeLeaseGeneration ?? 0) === (health!.cooldownGeneration ?? 0);
+}
+
+/** Strip the in-flight lease while preserving every hard-cooldown field. */
+function withProbeLeaseReleased(health: CodexUpstreamHealth, now: number): CodexUpstreamHealth {
+  const { probeLeaseId: _id, probeLeaseGeneration: _gen, ...rest } = health;
+  return { ...rest, lastProbeAt: now };
+}
+
+/**
+ * Hard-cooldown bookkeeping that ordinary success/transient transitions rebuild
+ * their health object from. Dropping these would let one late unrelated response
+ * erase a Retry-After source, a cooldown generation, or someone else's live probe.
+ */
+function preservedCooldownFields(health: CodexUpstreamHealth | undefined): Partial<CodexUpstreamHealth> {
+  if (!health) return {};
+  const { consecutiveFailures: _f, consecutiveSuccesses: _s, lastFailureStatus: _st, lastFailureAt: _at, softAvoidUntil: _sa, ...cooldownFields } = health;
+  return cooldownFields;
 }
 
 export function getCodexAccountCooldownUntil(accountId: string, now = Date.now()): number | null {
@@ -459,28 +586,49 @@ export function recordCodexUpstreamOutcome(
   if (outcomeClass === "success") {
     const current = upstreamHealth.get(accountId);
     const cooldownUntil = getCodexAccountCooldownUntil(accountId, now);
+    // A leased probe that is still on its own cooldown generation proves the
+    // account recovered: clear the hard cooldown outright (#433).
+    if (cooldownUntil && probeMayClearCooldown(current, meta)) {
+      upstreamHealth.delete(accountId);
+      return;
+    }
+    // Owning probe on a stale generation: the lease is done, but a newer 429
+    // replaced the cooldown in the meantime, so only give the lease back.
+    // Non-owners keep every hard-cooldown field, including someone else's live lease.
+    const base = ownsProbeLease(current, meta) ? withProbeLeaseReleased(current!, now) : current;
+    const preserved = preservedCooldownFields(base);
     const failoverEnabled = (config.upstreamFailoverThreshold ?? 3) > 0;
     if (failoverEnabled && current && current.consecutiveFailures >= 2) {
       const consecutiveSuccesses = (current.consecutiveSuccesses ?? 0) + 1;
       if (consecutiveSuccesses < 2) {
         upstreamHealth.set(accountId, {
-          ...current,
+          ...base!,
+          ...preserved,
           consecutiveSuccesses,
-          ...(cooldownUntil ? { cooldownUntil } : {}),
         });
         return;
       }
     }
     // Level 1 clears immediately; escalated accounts need two consecutive healthy terminals.
     // Hard quota cooldown intentionally survives either recovery path.
-    if (cooldownUntil) upstreamHealth.set(accountId, { consecutiveFailures: 0, cooldownUntil });
+    if (cooldownUntil) upstreamHealth.set(accountId, { consecutiveFailures: 0, ...preserved });
     else upstreamHealth.delete(accountId);
     return;
   }
-  if (outcomeClass === "caller") return;
+  if (outcomeClass === "caller") {
+    // A 4xx does not change account health, but it does conclude an in-flight
+    // probe — otherwise the lease would never be handed back.
+    const current = upstreamHealth.get(accountId);
+    if (ownsProbeLease(current, meta)) {
+      upstreamHealth.set(accountId, withProbeLeaseReleased(current!, now));
+    }
+    return;
+  }
 
   const lastFailureStatus = typeof outcome === "number" ? outcome : 0;
   if (outcomeClass === "credential") {
+    // 401/403 quarantines the account for reauth. That supersedes quota state
+    // entirely: a cooldown (and any probe lease) on an unusable account is moot.
     upstreamHealth.set(accountId, {
       consecutiveFailures: 1,
       lastFailureStatus,
@@ -492,11 +640,28 @@ export function recordCodexUpstreamOutcome(
   }
 
   if (outcomeClass === "quota") {
+    const prior = upstreamHealth.get(accountId);
+    const { until, source } = computeQuotaCooldown(meta);
+    // Every cooldown write bumps the generation so a probe issued against the
+    // previous cooldown can no longer clear this one (#433).
+    const cooldownGeneration = (prior?.cooldownGeneration ?? 0) + 1;
+    // A failed probe concludes its lease; an unrelated 429 leaves the live probe alone.
+    const ownsLease = ownsProbeLease(prior, meta);
     upstreamHealth.set(accountId, {
       consecutiveFailures: 0,
       lastFailureStatus,
       lastFailureAt: now,
-      cooldownUntil: computeQuotaCooldownUntil(meta),
+      cooldownUntil: until,
+      cooldownSince: now,
+      cooldownSource: source,
+      cooldownGeneration,
+      ...(ownsLease
+        ? { lastProbeAt: now }
+        : {
+          ...(prior?.probeLeaseId !== undefined ? { probeLeaseId: prior.probeLeaseId } : {}),
+          ...(prior?.probeLeaseGeneration !== undefined ? { probeLeaseGeneration: prior.probeLeaseGeneration } : {}),
+          ...(prior?.lastProbeAt !== undefined ? { lastProbeAt: prior.lastProbeAt } : {}),
+        }),
     });
     clearThreadAccountMapForAccount(accountId);
     if (config.activeCodexAccountId === accountId) {
@@ -508,6 +673,9 @@ export function recordCodexUpstreamOutcome(
 
   // transient (connect_error / timeout / 5xx)
   const current = upstreamHealth.get(accountId);
+  // A transient failure concludes an owning probe; an unrelated 5xx must not
+  // consume someone else's live lease or drop hard-cooldown bookkeeping (#433).
+  const transientBase = ownsProbeLease(current, meta) ? withProbeLeaseReleased(current!, now) : current;
   const stale = current?.lastFailureAt ? now - current.lastFailureAt > CODEX_FAILURE_WINDOW_MS : false;
   const hardCooldownUntil = getCodexAccountCooldownUntil(accountId, now) ?? undefined;
   // Soft avoid + affinity clears are part of failover. When threshold is 0, leave
@@ -524,6 +692,7 @@ export function recordCodexUpstreamOutcome(
     )
     : undefined;
   upstreamHealth.set(accountId, {
+    ...preservedCooldownFields(transientBase),
     consecutiveFailures,
     lastFailureStatus,
     lastFailureAt: now,

package/src/config.ts

@@ -7,7 +7,14 @@ import { comboConfigIssues } from "./combos/types";
 import { hardenSecretDir, hardenSecretPath } from "./lib/windows-secret-acl";
 import { providerDestinationConfigError } from "./lib/destination-policy";
 import { openRouterRoutingConfigError } from "./providers/openrouter-routing";
-import { OPENAI_PROVIDER_TIER_VERSION, type OcxConfig } from "./types";
+import {
+  isWirePinnedModel,
+  MODEL_ADAPTER_OVERRIDE_ALLOWED,
+  OPENAI_PROVIDER_TIER_VERSION,
+  type OcxConfig,
+  type OcxProviderConfig,
+} from "./types";
+import { isCanonicalOpenAiForwardProvider } from "./providers/openai-tiers";
 
 let _atomicSeq = 0;
 
@@ -434,6 +441,41 @@ export function booleanRecordConfigError(value: unknown, field: string): string
   return null;
 }
 
+/**
+ * Validate a provider's per-model wire override map (#404).
+ *
+ * Rejects, rather than silently ignoring, configurations the resolver would refuse:
+ * a value outside the allowed wires, a model the upstream pins to one wire, and any
+ * override on a canonical forward provider (where switching wires would drop the
+ * caller's forwarded credential). Silently dropping them would leave the user
+ * believing an override is in effect.
+ */
+export function modelAdapterRecordConfigError(
+  value: unknown,
+  field: string,
+  providerName: string,
+  provider: { adapter?: unknown; authMode?: unknown; baseUrl?: unknown },
+): string | null {
+  if (value === undefined) return null;
+  if (!value || typeof value !== "object" || Array.isArray(value)) return `${field} must be a plain object`;
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) return `${field} must be a plain object with own properties`;
+  const entries = Object.entries(value);
+  if (entries.length > 0 && isCanonicalOpenAiForwardProvider(provider as OcxProviderConfig)) {
+    return `${field} is not supported on the canonical ChatGPT forward provider`;
+  }
+  for (const [key, entry] of entries) {
+    if (!key.trim()) return `${field} keys must be nonblank model ids`;
+    if (typeof entry !== "string" || !MODEL_ADAPTER_OVERRIDE_ALLOWED.has(entry)) {
+      return `${field}.${key} must be one of: ${[...MODEL_ADAPTER_OVERRIDE_ALLOWED].join(", ")}`;
+    }
+    if (isWirePinnedModel(providerName, key.trim())) {
+      return `${field}.${key} cannot be overridden: the upstream only speaks one wire for this model`;
+    }
+  }
+  return null;
+}
+
 const configSchema = z.object({
   port: z.number().int().min(0).max(65535).default(10100),
   providers: z.record(z.string(), providerConfigSchema),
@@ -511,6 +553,19 @@ const configSchema = z.object({
         message: headersError,
       });
     }
+    const modelAdaptersError = modelAdapterRecordConfigError(
+      (provider as { modelAdapters?: unknown }).modelAdapters,
+      "modelAdapters",
+      name,
+      provider,
+    );
+    if (modelAdaptersError) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["providers", name, "modelAdapters"],
+        message: modelAdaptersError,
+      });
+    }
     const maxInputError = positiveIntegerRecordConfigError(
       (provider as { modelMaxInputTokens?: unknown }).modelMaxInputTokens,
       "modelMaxInputTokens",