@bitkyc08/opencodex 2.50.0 → 2.52.0-preview.20260911

package/src/client/connect.ts

@@ -67,6 +67,8 @@ import {
   readClientConnectionState,
   assertNoClientDisconnectPending, assertClientConnectionUnchanged, sameClientConnectionOwner,
 } from "./state";
+import { assertClientCatalogCompatible, type CatalogCompatibilityDeps } from "./catalog-compatibility";
+import { hubStateCachePath } from "./hub-state";
 
 class RotationRecoveryRequiredError extends Error {
   constructor(message: string, options?: ErrorOptions) {
@@ -89,6 +91,7 @@ export interface ClientConnectDeps {
   fetchImpl?: typeof fetch;
   now?: () => Date;
   lifecycleLockDeps?: ClientLifecycleLockDeps;
+  catalogCompatibility?: CatalogCompatibilityDeps;
 }
 
 export interface RotateClientOptions {
@@ -543,6 +546,12 @@ export async function connectClient(
       fetchImpl: deps.fetchImpl,
       timeoutMs: options.catalogTimeoutMs,
     });
+    // Fail closed BEFORE the write (#4207). The hub being reachable and the credential working
+    // does not mean the selected local Codex runtime can consume what arrived: an older CLI
+    // exits on an unknown reasoning level before making a single request, while connect
+    // reports success. Refusing here leaves the previous catalog in place untouched, rather
+    // than writing one and restoring it afterwards.
+    assertClientCatalogCompatible(catalog.body, deps.catalogCompatibility);
     writtenCatalogFingerprint = withClientLifecycleSync(() => withConfigMutationLockSync(() => {
       assertConnectingState(persisted.fingerprint);
       atomicWriteFile(DEFAULT_CATALOG_PATH, catalog.body);
@@ -659,6 +668,10 @@ export async function syncConnectedClient(
     if (!transient) throw error;
     stale = true;
   }
+  // Same gate as connect (#4207): a sync must never replace a catalog the local CLI can parse
+  // with one it cannot. Refusing leaves the connection and the existing catalog exactly as
+  // they were, which is the known-good state.
+  if (downloaded) assertClientCatalogCompatible(downloaded.body, deps.catalogCompatibility);
   const next = withClientLifecycleSync(() => withConfigMutationLockSync(() => {
     assertClientConnectionUnchanged(initial.connection);
     const token = readServiceApiTokenState();
@@ -879,6 +892,7 @@ export async function disconnectClient(
     if (!disconnectAtLeast(receipt, "clearing_connection")) advance("clearing_connection");
     if (clearClientConnection(receipt.owner) === "conflict") throw new Error("client_disconnect_owner_changed");
     if (!disconnectAtLeast(receipt, "connection_cleared")) advance("connection_cleared");
+    removeHubStateCache();
     requireDesktopResult(finishRemoteDesktopCleanup(held, receipt.owner));
     if (receipt.phase !== "complete") advance("complete");
     return {
@@ -890,6 +904,23 @@ export async function disconnectClient(
   }), deps.lifecycleLockDeps);
 }
 
+/**
+ * Drop the cached hub-state document (#4236).
+ *
+ * It is derived data from a connection that no longer exists, and it is owner-stamped, so a
+ * reader would reject it anyway — but leaving it behind means `<OPENCODEX_HOME>/hub-state.json`
+ * keeps naming the previous hub's providers and logins on a machine that is no longer connected
+ * to anything, which is exactly the wrong artifact to leave where someone might read it.
+ *
+ * Best effort and unconditional on the phase: the disconnect has already succeeded by this point,
+ * and a cache file that cannot be removed must not fail it or block a retry.
+ */
+function removeHubStateCache(): void {
+  try {
+    unlinkSync(hubStateCachePath());
+  } catch { /* absent, or not ours to remove */ }
+}
+
 export async function revokeConnectedClientKey(
   credential: { kind: "admin"; value: Uint8Array },
   deps: ClientConnectDeps = {},

package/src/client/hub-client.ts

@@ -1,4 +1,5 @@
 import { MAX_REMOTE_CATALOG_BYTES } from "../server/catalog-download";
+import { MAX_HUB_STATE_BYTES, parseHubStateBody, type HubStateDTO } from "../remote/hub-state";
 import { readBoundedResponseBytes } from "../lib/bounded-body";
 import { clearableDeadline } from "../lib/abort";
 import type { Desktop3pModelEntry } from "../claude/desktop-3p";
@@ -471,6 +472,57 @@ export async function downloadClientCatalog(
   return { kind: "fresh", body, ...(keyId ? { keyId } : {}) };
 }
 
+/**
+ * Read the hub's provider/login/roster state with the per-client DATA key (#4236).
+ *
+ * Sits beside `downloadClientCatalog` because it is the same kind of call: one bounded,
+ * schema-validated, unconditional GET on the data plane with the credential the client already
+ * holds. It deliberately has no management variant — the client has no hub management
+ * credential, and handing it one to read a list of booleans is the trade #809 already refused.
+ *
+ * A hub too old to serve the route answers 404, which surfaces as `hub_state_unsupported`. The
+ * caller must report that as "state unavailable" and MUST NOT fall back to the client's own
+ * local provider/login state: that silent fallback is the defect this route exists to fix.
+ */
+export async function fetchHubState(
+  serverUrl: string,
+  admissionToken: string,
+  options: { timeoutMs?: number; fetchImpl?: typeof fetch } = {},
+): Promise<HubStateDTO> {
+  const origin = normalizeHubOrigin(serverUrl);
+  const response = await fetchBounded(options.fetchImpl ?? fetch, `${origin}/v1/hub-state`, {
+    method: "GET",
+    headers: new Headers({ Accept: "application/json", "x-opencodex-api-key": admissionToken }),
+  }, options.timeoutMs, "headers");
+  if (response.status === 404) {
+    try { await response.body?.cancel(); } catch { /* best effort */ }
+    throw new HubClientError("hub_state_unsupported", "Hub does not serve /v1/hub-state; upgrade the hub", 404);
+  }
+  if (!response.ok) {
+    const code = response.status === 401 ? "hub_state_unauthorized" : `hub_state_http_${response.status}`;
+    try { await response.body?.cancel(); } catch { /* best effort */ }
+    throw new HubClientError(code, `Hub state request failed (${response.status})`, response.status);
+  }
+  if (!jsonCompatibleContentType(response)) {
+    try { await response.body?.cancel(); } catch { /* best effort */ }
+    throw new HubClientError("hub_state_content_type_invalid", "Hub state response was not JSON", response.status);
+  }
+  let text: string;
+  try {
+    text = await boundedText(response, MAX_HUB_STATE_BYTES, {
+      inactivityTimeoutMs: safeTimeout(options.timeoutMs),
+    });
+  } catch (error) {
+    if (error instanceof DOMException && error.name === "TimeoutError") {
+      throw new HubClientError("unreachable", "Hub state read stalled", undefined, { cause: error });
+    }
+    throw error;
+  }
+  const parsed = parseHubStateBody(parseJson(text, "hub_state_invalid"));
+  if (!parsed) throw new HubClientError("hub_state_schema_invalid", "Hub state response was invalid", response.status);
+  return parsed;
+}
+
 function desktopSnapshotModels(value: unknown): Desktop3pModelEntry[] {
   const invalid = () => new HubClientError("desktop_snapshot_invalid", "Hub Desktop model snapshot was invalid");
   if (!value || typeof value !== "object" || Array.isArray(value)) throw invalid();

package/src/client/hub-state.ts

@@ -0,0 +1,214 @@
+/**
+ * A connected client's view of its hub's provider, login and roster state (#4236).
+ *
+ * The rule this module exists to enforce: on a connected client, the hub is the authority, and
+ * when the hub cannot be read the answer is "unavailable" — never the client's own local
+ * credential store. That store is empty by design, and reporting it as the truth is what made an
+ * agent on a connected machine conclude the hub could not serve grok while the hub was serving
+ * grok. Every failure path here therefore lands on `stateSource: "unavailable"` with a reason a
+ * human can act on, and none of them reaches back into local config.
+ *
+ * The last good response is cached at `<OPENCODEX_HOME>/hub-state.json`, 0600, stamped with the
+ * connection that produced it. The owner stamp is not decoration: after `ocx disconnect` and a
+ * reconnect to a different hub (or a key rotation that changes `apiKeyId`), a stale file would
+ * otherwise be presented as this hub's state. `sameClientConnectionOwner` is the same triple
+ * (`serverUrl`, `apiKeyId`, `connectedAt`) the rest of the client lifecycle compares on.
+ */
+import { existsSync, lstatSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { getConfigDir } from "../config";
+import { atomicWriteFile } from "../config/atomic-write";
+import { parseHubStateBody, type HubStateDTO } from "../remote/hub-state";
+import type { OcxClientConnectionConfig } from "../types";
+import { fetchHubState, HubClientError } from "./hub-client";
+import { sameClientConnectionOwner } from "./state";
+
+/** Bound the status path: `ocx status` must answer even when the hub is gone. */
+const DEFAULT_HUB_STATE_TIMEOUT_MS = 3_000;
+/** The cache document plus its stamp; the DTO itself is already capped by its own contract. */
+const MAX_CACHE_BYTES = 128 * 1024;
+
+export type HubStateOwner = Pick<OcxClientConnectionConfig, "serverUrl" | "apiKeyId" | "connectedAt">;
+
+/** Where the state came from. "unavailable" is a reportable outcome, not a fallback to local. */
+export type HubStateSource = "hub" | "cache" | "unavailable";
+
+export interface HubStateResolution {
+  stateSource: HubStateSource;
+  state: HubStateDTO | null;
+  /** Present whenever the live read did not succeed. Short, operator-facing. */
+  reason?: string;
+  /** ISO timestamp of the response this state came from. */
+  fetchedAt?: string;
+  ageSeconds?: number;
+}
+
+export function hubStateCachePath(): string {
+  return join(getConfigDir(), "hub-state.json");
+}
+
+interface CacheDocument {
+  version: 1;
+  owner: HubStateOwner;
+  fetchedAt: string;
+  state: HubStateDTO;
+}
+
+function readCacheDocument(): CacheDocument | null {
+  const path = hubStateCachePath();
+  if (!existsSync(path)) return null;
+  try {
+    const stat = lstatSync(path);
+    // A symlink or an oversized file is refused rather than followed: this file is written
+    // 0600 by us, and anything else about it is someone else's doing.
+    if (stat.isSymbolicLink() || !stat.isFile() || stat.size > MAX_CACHE_BYTES) return null;
+    const raw = JSON.parse(readFileSync(path, "utf8")) as unknown;
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+    const doc = raw as Record<string, unknown>;
+    if (doc.version !== 1) return null;
+    const owner = doc.owner;
+    if (!owner || typeof owner !== "object" || Array.isArray(owner)) return null;
+    const ownerRow = owner as Record<string, unknown>;
+    if (typeof ownerRow.serverUrl !== "string" || typeof ownerRow.apiKeyId !== "string"
+      || typeof ownerRow.connectedAt !== "string") return null;
+    if (typeof doc.fetchedAt !== "string" || Number.isNaN(Date.parse(doc.fetchedAt))) return null;
+    const state = parseHubStateBody(doc.state);
+    if (!state) return null;
+    return {
+      version: 1,
+      owner: {
+        serverUrl: ownerRow.serverUrl,
+        apiKeyId: ownerRow.apiKeyId,
+        connectedAt: ownerRow.connectedAt,
+      },
+      fetchedAt: doc.fetchedAt,
+      state,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/** The cached state for THIS connection, or null when absent, malformed, or another hub's. */
+export function readCachedHubState(owner: HubStateOwner): { state: HubStateDTO; fetchedAt: string } | null {
+  const doc = readCacheDocument();
+  if (!doc) return null;
+  if (!sameClientConnectionOwner(doc.owner, owner)) return null;
+  return { state: doc.state, fetchedAt: doc.fetchedAt };
+}
+
+/** Best-effort: a cache that cannot be written must never fail the command that asked. */
+export function writeCachedHubState(owner: HubStateOwner, state: HubStateDTO, fetchedAt: string): boolean {
+  try {
+    const document: CacheDocument = {
+      version: 1,
+      owner: { serverUrl: owner.serverUrl, apiKeyId: owner.apiKeyId, connectedAt: owner.connectedAt },
+      fetchedAt,
+      state,
+    };
+    atomicWriteFile(hubStateCachePath(), `${JSON.stringify(document, null, 2)}\n`);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Why the live read did not land, in words an operator can act on.
+ *
+ * `hub_state_unsupported` is the version-skew case and gets an explicit upgrade instruction:
+ * left as a bare code it reads like a bug in the client.
+ *
+ * Every code `fetchHubState` can throw has a sentence here, including the open-ended
+ * `hub_state_http_<status>` family. This reason is printed in the `ocx status` banner, and a
+ * banner reading `state unavailable (hub_state_http_507)` sends the reader looking for a client
+ * bug when the hub has in fact answered and said something.
+ */
+export function hubStateFailureReason(error: unknown): string {
+  if (error instanceof HubClientError) {
+    switch (error.code) {
+      case "hub_state_unsupported":
+        return "this hub is too old to report its state; upgrade the hub";
+      case "hub_state_unauthorized":
+        return "the hub rejected this client's data key";
+      case "hub_state_schema_invalid":
+      case "hub_state_invalid":
+        return "the hub returned an unreadable hub-state document";
+      case "hub_state_content_type_invalid":
+        // Usually a captive portal, a TLS-terminating proxy or an error page in front of the
+        // hub: the request reached SOMETHING, and that something is not the hub's API.
+        return "the hub's state response was not JSON";
+      case "body_too_large":
+        return "the hub's state response exceeded the allowed size";
+      case "unreachable":
+        return "the hub is unreachable";
+      case "redirect_refused":
+        return "the hub redirected the state request";
+      default: {
+        const status = error.code.startsWith("hub_state_http_")
+          ? error.code.slice("hub_state_http_".length)
+          : null;
+        return status && /^\d+$/.test(status)
+          ? `the hub answered HTTP ${status} to the state request`
+          : error.code;
+      }
+    }
+  }
+  return "the hub state could not be read";
+}
+
+export interface ResolveHubStateOptions {
+  owner: HubStateOwner;
+  /** The per-client data key. Null when the token file is missing or unsafe. */
+  token: string | null;
+  timeoutMs?: number;
+  fetchImpl?: typeof fetch;
+  now?: number;
+  /** False reads only the cache — for paths that must not make a network call. */
+  allowNetwork?: boolean;
+  /** False skips the cache write, for read-only callers. */
+  persist?: boolean;
+}
+
+function withAge(
+  source: HubStateSource,
+  state: HubStateDTO | null,
+  fetchedAt: string | undefined,
+  now: number,
+  reason?: string,
+): HubStateResolution {
+  const ageSeconds = fetchedAt ? Math.max(0, Math.floor((now - Date.parse(fetchedAt)) / 1000)) : undefined;
+  return {
+    stateSource: source,
+    state,
+    ...(reason ? { reason } : {}),
+    ...(fetchedAt ? { fetchedAt } : {}),
+    ...(ageSeconds === undefined || Number.isNaN(ageSeconds) ? {} : { ageSeconds }),
+  };
+}
+
+export async function resolveHubState(options: ResolveHubStateOptions): Promise<HubStateResolution> {
+  const now = options.now ?? Date.now();
+  const fromCache = (reason: string): HubStateResolution => {
+    const cached = readCachedHubState(options.owner);
+    return cached
+      ? withAge("cache", cached.state, cached.fetchedAt, now, reason)
+      : withAge("unavailable", null, undefined, now, reason);
+  };
+  if (!options.token) return fromCache("this client has no usable data-plane token");
+  if (options.allowNetwork === false) return fromCache("a live hub read was not attempted");
+  let state: HubStateDTO;
+  try {
+    state = await fetchHubState(options.owner.serverUrl, options.token, {
+      timeoutMs: options.timeoutMs ?? DEFAULT_HUB_STATE_TIMEOUT_MS,
+      ...(options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}),
+    });
+  } catch (error) {
+    // Deliberately no local-state fallback here. A stale cache is still the HUB's state; the
+    // client's own providers and logins are not, at any age.
+    return fromCache(hubStateFailureReason(error));
+  }
+  const fetchedAt = new Date(now).toISOString();
+  if (options.persist !== false) writeCachedHubState(options.owner, state, fetchedAt);
+  return withAge("hub", state, fetchedAt, now);
+}

package/src/codex/account-usability.ts

@@ -20,34 +20,70 @@ export interface CodexAccountUsabilityOptions {
   modelEligibleAccountIds?: ReadonlySet<string>;
 }
 
-export function isCodexAccountUsable(
+/**
+ * Why an account was refused, in the order the checks run. This is the attribution half of
+ * selection: an operator whose model quietly disappeared needs to know that one account fell out
+ * and why, not merely that the pool got smaller (#4212).
+ */
+export type CodexAccountUnusableReason =
+  | "model_not_entitled"
+  | "main_hard_locked"
+  | "main_traffic_blocked"
+  | "legacy_pool_sentinel"
+  | "needs_reauth"
+  | "main_credential_unavailable"
+  | "not_in_pool"
+  | "missing_credential"
+  | "deleted"
+  | "validation_pending";
+
+/**
+ * The single source of truth for both selection and its explanation. `isCodexAccountUsable()` is
+ * this function's boolean projection rather than a parallel copy of the same branches, so a reason
+ * can never claim an account is fine while routing drops it, or name a cause routing did not use.
+ */
+export function codexAccountUnusableReason(
   config: OcxConfig,
   accountId: string,
   options: CodexAccountUsabilityOptions = {},
-): boolean {
-  if (options.modelEligibleAccountIds && !options.modelEligibleAccountIds.has(accountId)) return false;
+): CodexAccountUnusableReason | undefined {
+  if (options.modelEligibleAccountIds && !options.modelEligibleAccountIds.has(accountId)) {
+    return "model_not_entitled";
+  }
   if (accountId === MAIN_CODEX_ACCOUNT_ID) {
-    if (isMainAccountHardLocked(config)) return false;
+    if (isMainAccountHardLocked(config)) return "main_hard_locked";
     // Startup recovery owns the physical auth/vault boundary. Never parse or select
     // native __main__ while an encrypted switch journal is pending or inconclusive.
-    if (!options.nativeMainSelectionOnly && isNativeMainTrafficBlocked()) return false;
+    if (!options.nativeMainSelectionOnly && isNativeMainTrafficBlocked()) return "main_traffic_blocked";
     // A legacy pool row with the sentinel makes an active `__main__` ambiguous.
     // Fail closed until the authenticated compatibility-delete path removes it.
-    if (hasLegacyMainCodexPoolAccount(config.codexAccounts)) return false;
-    if (isAccountNeedsReauth(accountId) && !hasMainAccountRefreshGrant()) return false;
+    if (hasLegacyMainCodexPoolAccount(config.codexAccounts)) return "legacy_pool_sentinel";
+    if (isAccountNeedsReauth(accountId) && !hasMainAccountRefreshGrant()) return "needs_reauth";
     // A selection-only caller owns the recovery/drain fence and will reject main
     // before reservation or token materialization. Treat cached main as a routing
     // candidate without touching the credential file so affinity is not rebound.
-    if (options.nativeMainSelectionOnly) return true;
+    if (options.nativeMainSelectionOnly) return undefined;
     // Main account: a refresh grant is enough to route; materialization refreshes before I/O.
-    return options.isMainAccountTokenLive
+    const mainLive = options.isMainAccountTokenLive
       ? options.isMainAccountTokenLive()
       : isMainAccountCredentialUsable();
+    return mainLive ? undefined : "main_credential_unavailable";
   }
   const exists = (config.codexAccounts ?? [])
     .some(account => isSelectableCodexPoolAccount(account) && account.id === accountId);
-  if (!exists) return false;
-  if (isAccountNeedsReauth(accountId)) return false;
+  if (!exists) return "not_in_pool";
+  if (isAccountNeedsReauth(accountId)) return "needs_reauth";
   const record = readCodexAccountRecord(accountId);
-  return !!record?.credential && record.deletedAt == null && !record.codexValidationPending;
+  if (!record?.credential) return "missing_credential";
+  if (record.deletedAt != null) return "deleted";
+  if (record.codexValidationPending) return "validation_pending";
+  return undefined;
+}
+
+export function isCodexAccountUsable(
+  config: OcxConfig,
+  accountId: string,
+  options: CodexAccountUsabilityOptions = {},
+): boolean {
+  return codexAccountUnusableReason(config, accountId, options) === undefined;
 }

package/src/codex/auth-api.ts

@@ -116,7 +116,7 @@ import type { CodexQuotaRefreshOutcome } from "./quota-refresh-outcome";
 import { getMainAccountHardLockStatus, type MainAccountHardLockStatus } from "./main-account-hard-lock";
 import { observeMainReserveRevocation } from "./reserve-availability";
 import { emailMaskingEnabled, projectEmail } from "../lib/privacy";
-import { codexWarmupFailureReason, warmCodexAccount } from "./warmup";
+import { codexWarmupFailureReason, isCodexWarmupProvisioningFailure, warmCodexAccount } from "./warmup";
 export { maskEmail } from "../lib/privacy";
 import type { CodexAccount, CodexAccountCredentials, OcxConfig } from "../types";
 import type { CatalogDisposition } from "./convergence-types";
@@ -364,6 +364,20 @@ function mainQuotaWithCarriedResetCredits(
   };
 }
 
+/**
+ * Why an account needs the operator. `missing_credential`, `refresh_failed`, and
+ * `quota_unauthorized` are the three causes this surface tells apart on its own. `unauthorized`
+ * and `forbidden` exist because the shared health projection may return them; today
+ * `projectCodexAccountHealth` only ever produces `refresh_failed`, so accepting the full union
+ * keeps this field correct if that projection widens rather than silently dropping a reason.
+ */
+export type CodexAccountReauthReason =
+  | "missing_credential"
+  | "refresh_failed"
+  | "quota_unauthorized"
+  | "unauthorized"
+  | "forbidden";
+
 function poolAccountDto(
   account: CodexAccount,
   quotaResult: PoolQuotaResult,
@@ -374,8 +388,19 @@ function poolAccountDto(
 ): CodexAuthAccountDto {
   const plan = codexPlanValue(account.plan);
   const quota = quotaForPlan(quotaResult.quota, plan);
-  const needsReauth = !hasCredential || quotaResult.needsReauth || isAccountNeedsReauth(account.id);
+  const runtimeReauth = isAccountNeedsReauth(account.id);
+  const needsReauth = !hasCredential || quotaResult.needsReauth || runtimeReauth;
   const health = projectCodexAccountHealth({ accountId: account.id, needsReauth });
+  // `needsReauth` is an OR of three independent causes plus a persisted verdict resolved inside the
+  // health projection. Emitting only the boolean is what left #4212's reporter guessing which
+  // account took their model away and why, so name the cause they actually have to act on.
+  const reauthReason: CodexAccountReauthReason | undefined = !hasCredential
+    ? "missing_credential"
+    : runtimeReauth
+      ? "refresh_failed"
+      : quotaResult.needsReauth
+        ? "quota_unauthorized"
+        : health.status === "reauth_required" ? health.reason : undefined;
   return {
     id: account.id,
     email: projectEmail(account.email, maskEmails) ?? account.email,
@@ -387,6 +412,7 @@ function poolAccountDto(
     priority,
     quota: quota ? { ...quota } : null,
     needsReauth: needsReauth || health.status === "reauth_required",
+    ...(reauthReason !== undefined ? { reauthReason } : {}),
     hasCredential,
     ...(quotaResult.quotaProbeSkipped ? { quotaProbeSkipped: true as const } : {}),
     ...oauthAccountHealthFields("codex", account.id, health),
@@ -588,7 +614,11 @@ async function verifyCodexAccountWarmup(
     return {
       ok: false,
       response: jsonResponse({
-        error: "Codex account warmup failed. Reauthenticate the account and try again.",
+        // Every fallback model was refused for a provisioning reason, so telling the operator to
+        // reauthenticate sends them back through a login that already succeeded.
+        error: isCodexWarmupProvisioningFailure(err)
+          ? "Codex account warmup failed. Verify account model access or provisioning and try again."
+          : "Codex account warmup failed. Reauthenticate the account and try again.",
         code: "codex_warmup_failed",
         reason,
         accountId,
@@ -1157,6 +1187,11 @@ export interface CodexAuthAccountDto {
   priority: number;
   quota: (StoredAccountQuota | (Omit<StoredAccountQuota, "updatedAt"> & { updatedAt: number })) | null;
   needsReauth?: boolean;
+  /**
+   * Which of the independent causes behind `needsReauth` fired. Present only when the account
+   * needs the operator; `/api/oauth/accounts` already carries the same field name.
+   */
+  reauthReason?: CodexAccountReauthReason;
   hasCredential: boolean;
   health: OAuthAccountHealth;
   healthLabel: OAuthHealthLabel;
@@ -2005,12 +2040,20 @@ export async function listCodexAuthAccountsSnapshot(
   const hasMainCredential = mainSnapshotLive && mainResult.credentialChecked
     ? mainResult.hasCredential
     : getMainAccountCredentialPresence() ?? false;
-  const mainNeedsReauth = (mainSnapshotLive && mainResult.credentialChecked && !hasMainCredential)
-    || isAccountNeedsReauth(MAIN_CODEX_ACCOUNT_ID);
+  const mainMissingCredential = mainSnapshotLive && mainResult.credentialChecked && !hasMainCredential;
+  const mainNeedsReauth = mainMissingCredential || isAccountNeedsReauth(MAIN_CODEX_ACCOUNT_ID);
   const mainHealth = projectCodexAccountHealth({
     accountId: MAIN_CODEX_ACCOUNT_ID,
     needsReauth: mainNeedsReauth,
   });
+  // The main row carries the same attribution as a pool row. Reaching this point without
+  // `mainMissingCredential` means the runtime reauth flag is what set `mainNeedsReauth`, so the
+  // cause is a refresh that did not complete.
+  const mainReauthReason: CodexAccountReauthReason | undefined = mainMissingCredential
+    ? "missing_credential"
+    : mainNeedsReauth
+      ? "refresh_failed"
+      : mainHealth.status === "reauth_required" ? mainHealth.reason : undefined;
   const main: CodexAuthAccountDto = {
     id: MAIN_CODEX_ACCOUNT_ID,
     email: projectEmail(mainInfo.email, maskEmails) ?? "Codex App login",
@@ -2025,6 +2068,7 @@ export async function listCodexAuthAccountsSnapshot(
     priority: getCodexAccountPriority(runtimeConfig, MAIN_CODEX_ACCOUNT_ID),
     hasCredential: hasMainCredential,
     needsReauth: mainNeedsReauth,
+    ...(mainReauthReason !== undefined ? { reauthReason: mainReauthReason } : {}),
     quota: mainInfo.quota ? {
       ...quotaForPlan(mainQuotaWithCarriedResetCredits(mainInfo.quota), mainInfo.plan),
     } : null,

package/src/codex/catalog/effort.ts

@@ -46,6 +46,7 @@ import {
   displayCodexRuntimePath,
   persistEffortClamp,
   resolveAndPersistCodexRuntime,
+  UNCLAMPABLE_REASONING_EFFORTS,
   type EffortClampDiagnostic,
 } from "../runtime";
 
@@ -354,7 +355,13 @@ export function clampEntryToCodexSupportedEfforts(
     ? entry.supported_reasoning_levels as Array<{ effort?: string }>
     : null;
   if (levels && levels.length > 0) {
-    const kept = levels.filter(level => typeof level?.effort === "string" && supported.has(level.effort));
+    // A rung survives when the observed runtime offers it OR when it is one of the rungs the
+    // clamp no longer removes (max/ultra, per the unconditional-emission ruling): CLI versions
+    // that genuinely lack them are out of support, and hiding them from current clients costs
+    // more than it buys. Hub admission is a different question and stays fail-closed in
+    // `catalogEffortCompatibility` below.
+    const kept = levels.filter(level => typeof level?.effort === "string"
+      && (supported.has(level.effort) || UNCLAMPABLE_REASONING_EFFORTS.has(level.effort)));
     if (requiresExactReserveEfforts(entry)) {
       entry.supported_reasoning_levels = kept;
       if (kept.length === 0) {
@@ -375,12 +382,19 @@ export function clampEntryToCodexSupportedEfforts(
         .map(level => ({ ...level }));
   }
   const currentDefault = entry.default_reasoning_level;
-  if (typeof currentDefault === "string" && !supported.has(currentDefault)) {
-    const surviving = (Array.isArray(entry.supported_reasoning_levels) ? entry.supported_reasoning_levels : [])
-      .flatMap(level => typeof (level as { effort?: string })?.effort === "string"
-        ? [(level as { effort: string }).effort]
-        : []);
-    entry.default_reasoning_level = clampedDefaultEffort(currentDefault, surviving);
+  const surviving = (Array.isArray(entry.supported_reasoning_levels) ? entry.supported_reasoning_levels : [])
+    .flatMap(level => typeof (level as { effort?: string })?.effort === "string"
+      ? [(level as { effort: string }).effort]
+      : []);
+  // An exempt default survives only when the surviving ladder actually advertises it;
+  // otherwise the row would name a default the client cannot select (review: PR #4257).
+  if (typeof currentDefault === "string"
+    && !supported.has(currentDefault)) {
+    const exemptAndAdvertised = UNCLAMPABLE_REASONING_EFFORTS.has(currentDefault)
+      && surviving.includes(currentDefault);
+    if (!exemptAndAdvertised) {
+      entry.default_reasoning_level = clampedDefaultEffort(currentDefault, surviving);
+    }
   }
 }
 
@@ -389,6 +403,47 @@ export interface ObservedCatalogEffortClamp {
   readonly affectedModels: readonly string[];
 }
 
+export interface CatalogEffortCompatibility {
+  readonly compatible: boolean;
+  readonly unsupportedEfforts: readonly string[];
+  readonly affectedModels: readonly string[];
+}
+
+/**
+ * Report which reasoning efforts in a catalog the local Codex runtime would reject, without
+ * changing anything.
+ *
+ * The clamp above is mutate-and-continue, which is right when this process owns the file it
+ * is about to write. It is wrong for a catalog downloaded from a hub: rewriting it locally
+ * would make the client disagree with hub truth, and #4207 asks for the opposite — establish
+ * compatibility first, and refuse rather than materialise a catalog the local CLI cannot
+ * parse. `supported` of null means the runtime ladder could not be observed, which is not
+ * evidence of incompatibility, so nothing is reported.
+ */
+export function catalogEffortCompatibility(
+  models: readonly RawEntry[],
+  supported: ReadonlySet<string> | null,
+): CatalogEffortCompatibility {
+  if (!supported) return { compatible: true, unsupportedEfforts: [], affectedModels: [] };
+  const unsupported = new Set<string>();
+  const affected: string[] = [];
+  for (const entry of models) {
+    const rejected = catalogEntryEfforts(entry).filter(effort => !supported.has(effort));
+    const fallback = typeof entry.default_reasoning_level === "string"
+      && !supported.has(entry.default_reasoning_level)
+      ? [entry.default_reasoning_level]
+      : [];
+    if (rejected.length === 0 && fallback.length === 0) continue;
+    for (const effort of [...rejected, ...fallback]) unsupported.add(effort);
+    if (typeof entry.slug === "string") affected.push(entry.slug);
+  }
+  return {
+    compatible: unsupported.size === 0,
+    unsupportedEfforts: [...unsupported].sort(),
+    affectedModels: affected,
+  };
+}
+
 /** Apply an already-observed runtime ladder without probing, logging, or writing diagnostics. */
 export function clampCatalogModelsToObservedCodexSupport(
   models: RawEntry[],
@@ -425,7 +480,11 @@ export function clampCatalogModelsToObservedCodexSupport(
     const omitted = requiresExactReserveEfforts(entry) && hadLadder && after.size === 0;
     if (lost.length > 0 || defaultClamped || omitted) {
       for (const effort of lost) removed.add(effort);
-      if (defaultClamped && beforeDefault) removed.add(beforeDefault);
+      // An orphaned exempt default (ultra with no ultra rung in the ladder) is repaired for
+      // coherence, but nothing was removed from the offering — do not name it in the diagnostic.
+      if (defaultClamped && beforeDefault && !UNCLAMPABLE_REASONING_EFFORTS.has(beforeDefault)) {
+        removed.add(beforeDefault);
+      }
       if (typeof entry.slug === "string") affected.push(entry.slug);
     }
     if (omitted) models.splice(index, 1);