@bitkyc08/opencodex 2.49.0 → 2.51.0

package/src/client/catalog-compatibility.ts

@@ -0,0 +1,192 @@
+/**
+ * #4207: a connected client reported `connected` with a present, freshly synced catalog while
+ * its installed Codex CLI exited before making a request, because the hub's catalog contained a
+ * reasoning level that CLI does not know:
+ *
+ *   failed to parse model_catalog_json ... unknown variant `max`,
+ *   expected one of `none`, `minimal`, `low`, `medium`, `high`, `xhigh`
+ *
+ * The connection state answered a different question from the one the operator was asking. It
+ * proved the hub was reachable and the credential worked; it never proved the selected local
+ * runtime could consume what was downloaded. This module supplies the missing half, and the
+ * connect path fails closed on it: an incompatible catalog is refused before it is written, so
+ * the previous known-good file survives and no success is reported.
+ *
+ * What it deliberately does not do: rewrite the hub's catalog into a locally compatible
+ * projection (the client would then silently disagree with hub truth) and terminate running
+ * Codex processes. Both are ruled out by the issue.
+ */
+import { catalogEffortCompatibility, codexSupportedReasoningEfforts } from "../codex/catalog/effort";
+import type { RawEntry } from "../codex/catalog/parsing";
+
+export type ClientCatalogCompatibility =
+  | { kind: "compatible" }
+  /** The runtime ladder could not be observed, so incompatibility cannot be established. */
+  | { kind: "unverified"; reason: string }
+  | {
+    kind: "incompatible";
+    unsupportedEfforts: readonly string[];
+    affectedModels: readonly string[];
+  };
+
+export interface CatalogCompatibilityDeps {
+  /** Injected in tests; defaults to observing the selected local Codex runtime. */
+  supportedEfforts?: () => ReadonlySet<string> | null;
+}
+
+/** State of the materialized client catalog file, as `ocx connect status` already reports it. */
+export type ClientCatalogFileState = "present" | "missing" | "unsafe";
+
+/**
+ * Whether the selected local Codex runtime can consume the catalog that is *already on disk* —
+ * a different question from the write-time gate, and the one #4207 was actually asking.
+ *
+ * The gate runs once, on bytes about to be written. It cannot speak for a file that predates it,
+ * for a file written while the ladder was {@link ClientCatalogCompatibility} `unverified`, or for
+ * a runtime that was swapped after the write. Those are exactly the states that kept reporting
+ * `connected` while `codex exec` died on `unknown variant \`max\``.
+ *
+ * Only `ready` means ready. `unverified` is not `incompatible`: a client machine may legitimately
+ * have no observable Codex CLI, and calling that an incompatibility would condemn a working
+ * install on absent evidence — the same mistake the write-time gate refuses to make.
+ */
+export type ClientCatalogReadiness =
+  | { kind: "ready" }
+  | { kind: "unverified"; reason: string }
+  | {
+    kind: "incompatible";
+    reason: string;
+    unsupportedEfforts: readonly string[];
+    affectedModels: readonly string[];
+  };
+
+function parseModels(body: string): RawEntry[] | null {
+  try {
+    const parsed = JSON.parse(body) as { models?: unknown };
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+    return Array.isArray(parsed.models) ? parsed.models as RawEntry[] : [];
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Assess a downloaded catalog against the reasoning efforts the selected local Codex runtime
+ * accepts. Unreadable bytes are reported as unverified rather than incompatible: the hub
+ * client already rejects a malformed body, and inventing a second cause for it here would
+ * repeat the mistake #4169 was filed for.
+ */
+export function assessClientCatalogCompatibility(
+  body: string,
+  deps: CatalogCompatibilityDeps = {},
+): ClientCatalogCompatibility {
+  const models = parseModels(body);
+  if (!models) return { kind: "unverified", reason: "the downloaded catalog could not be read" };
+  const supported = (deps.supportedEfforts ?? (() => codexSupportedReasoningEfforts()))();
+  if (!supported) {
+    return {
+      kind: "unverified",
+      reason: "the selected local Codex runtime did not report the reasoning levels it supports",
+    };
+  }
+  const result = catalogEffortCompatibility(models, supported);
+  if (result.compatible) return { kind: "compatible" };
+  return {
+    kind: "incompatible",
+    unsupportedEfforts: result.unsupportedEfforts,
+    affectedModels: result.affectedModels,
+  };
+}
+
+/**
+ * Raised instead of writing an incompatible catalog. It names both remedies the issue asks
+ * for, because the operator cannot act on "incompatible" alone, and it never suggests editing
+ * the hub.
+ */
+export class ClientCatalogIncompatibleError extends Error {
+  readonly unsupportedEfforts: readonly string[];
+  readonly affectedModels: readonly string[];
+
+  constructor(unsupportedEfforts: readonly string[], affectedModels: readonly string[]) {
+    const efforts = unsupportedEfforts.join(", ");
+    const models = affectedModels.length > 3
+      ? `${affectedModels.slice(0, 3).join(", ")} and ${affectedModels.length - 3} more`
+      : affectedModels.join(", ");
+    super(
+      `catalog_incompatible: the hub catalog uses reasoning ${unsupportedEfforts.length === 1 ? "level" : "levels"} `
+      + `${efforts}, which the selected local Codex CLI rejects${models ? ` (${models})` : ""}. `
+      + "The previous catalog was kept and nothing was changed. Upgrade the Codex CLI to a "
+      + "version that supports those levels, or point CODEX_CLI_PATH at one that does and run "
+      + "`ocx sync`, then retry. `ocx doctor` reports which runtime is selected.",
+    );
+    this.name = "ClientCatalogIncompatibleError";
+    this.unsupportedEfforts = unsupportedEfforts;
+    this.affectedModels = affectedModels;
+  }
+}
+
+/** Fail closed: refuse an incompatible catalog before anything is written. */
+export function assertClientCatalogCompatible(body: string, deps: CatalogCompatibilityDeps = {}): void {
+  const assessment = assessClientCatalogCompatibility(body, deps);
+  if (assessment.kind !== "incompatible") return;
+  throw new ClientCatalogIncompatibleError(assessment.unsupportedEfforts, assessment.affectedModels);
+}
+
+/**
+ * Why an already-installed incompatible catalog does not reuse the refusal message above:
+ * nothing was kept back. The unusable bytes are the ones Codex will read on its next launch,
+ * so "the previous catalog was kept" would be false. The two remedies are the same, because
+ * the operator's options do not depend on when the file arrived.
+ */
+function installedCatalogRejectionReason(
+  unsupportedEfforts: readonly string[],
+  affectedModels: readonly string[],
+): string {
+  const models = affectedModels.length > 3
+    ? `${affectedModels.slice(0, 3).join(", ")} and ${affectedModels.length - 3} more`
+    : affectedModels.join(", ");
+  return `the installed catalog uses reasoning ${unsupportedEfforts.length === 1 ? "level" : "levels"} `
+    + `${unsupportedEfforts.join(", ")}, which the selected local Codex CLI rejects`
+    + `${models ? ` (${models})` : ""}. Codex exits before its first request until the CLI is `
+    + "upgraded to a version that supports those levels, or CODEX_CLI_PATH points at one that "
+    + "does and `ocx sync` is run. `ocx doctor` reports which runtime is selected.";
+}
+
+/**
+ * Assess the catalog this machine has already installed, so a surface can stop calling a
+ * connection ready when the local runtime cannot launch against it.
+ *
+ * `body` is the file's bytes, or `null` when they could not be read; `file` is the state the
+ * caller already established by stat. Neither non-present file state is an incompatibility: an
+ * absent or non-regular catalog is a different fault, and this function only ever claims an
+ * incompatibility it has proven.
+ */
+export function inspectClientCatalogReadiness(
+  file: ClientCatalogFileState,
+  body: string | null,
+  deps: CatalogCompatibilityDeps = {},
+): ClientCatalogReadiness {
+  if (file === "missing") {
+    return { kind: "unverified", reason: "no catalog is installed for the local Codex CLI to read" };
+  }
+  if (file === "unsafe") {
+    return { kind: "unverified", reason: "the catalog path is not a regular file, so its bytes were not read" };
+  }
+  if (body === null) return { kind: "unverified", reason: "the installed catalog could not be read" };
+  const assessment = assessClientCatalogCompatibility(body, deps);
+  if (assessment.kind === "compatible") return { kind: "ready" };
+  if (assessment.kind === "unverified") {
+    // assessClientCatalogCompatibility words its parse failure for bytes that have just been
+    // downloaded. These bytes are already installed, so blaming a download would send the
+    // operator to the wrong place; name the file that is actually unusable.
+    return parseModels(body) === null
+      ? { kind: "unverified", reason: "the installed catalog is not readable JSON, so the local Codex CLI cannot parse it either" }
+      : assessment;
+  }
+  return {
+    kind: "incompatible",
+    reason: installedCatalogRejectionReason(assessment.unsupportedEfforts, assessment.affectedModels),
+    unsupportedEfforts: assessment.unsupportedEfforts,
+    affectedModels: assessment.affectedModels,
+  };
+}

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/clients/config-export/zcode.ts

@@ -1,6 +1,7 @@
 // ZCode config export.
 import type { ExportContext, ManagedContribution } from "./contracts";
 import { normalizeExportModels, inputModalitiesForClient, exportModelLabel, authoritativeContextWindow, singleFragment } from "./model-metadata";
+import { sanitizeCodexReasoningEfforts } from "../../reasoning-effort";
 import { OPENCODE_PROVIDER_ID, LOOPBACK_API_KEY_PLACEHOLDER } from "./constants";
 
 
@@ -15,6 +16,16 @@ export interface ZcodeModelEntry {
   name?: string;
   limit?: { context: number; output?: number };
   modalities: { input: string[]; output: string[] };
+  /**
+   * On-disk Thought Level block. ZCode 3.x persists `variants`/`defaultVariant`
+   * and parses them into in-memory `levels`/`defaultLevel`. Omit the field when
+   * the catalog has no selectable ladder, so the picker stays hidden.
+   */
+  reasoning?: {
+    enabled: boolean;
+    variants: string[];
+    defaultVariant?: string;
+  };
 }
 
 export interface ZcodeProviderBlock {
@@ -61,6 +72,19 @@ export function buildZcodeClientConfig(ctx: ExportContext): ZcodeGeneratedConfig
     if (context !== undefined) {
       entry.limit = { context };
     }
+    // `none` is a Codex omit-sentinel, not a ZCode picker option. Keep catalog
+    // `ultra` when present: ZCode forwards the selected variant as
+    // `reasoning_effort`. Set `defaultVariant` only when it survives that filter.
+    const efforts = sanitizeCodexReasoningEfforts(model.reasoningEfforts)
+      ?.filter(effort => effort !== "none");
+    if (efforts && efforts.length > 0) {
+      const defaultVariant = model.defaultReasoningEffort?.trim().toLowerCase();
+      entry.reasoning = {
+        enabled: true,
+        variants: efforts,
+        ...(defaultVariant && efforts.includes(defaultVariant) ? { defaultVariant } : {}),
+      };
+    }
     models[model.namespaced] = entry;
   }
   return {

package/src/codex/account-runtime-state.ts

@@ -60,6 +60,11 @@ export function isAccountNeedsReauth(id: string): boolean {
   return true;
 }
 
-export function clearAccountNeedsReauth(id: string): void {
+export function clearAccountNeedsReauth(id: string, credentialGeneration?: number): void {
+  // A model response proves only the credential it used. Keep account-wide
+  // quarantine and evidence from another generation intact.
+  if (credentialGeneration !== undefined
+    && (reauthAccounts.get(id) !== credentialGeneration
+      || !isCodexAccountGenerationLive(id, credentialGeneration))) return;
   reauthAccounts.delete(id);
 }