@bitkyc08/opencodex 2.49.0 → 2.51.0

package/src/codex/auth-context.ts

@@ -7,6 +7,7 @@ import {
   getCodexAccountCredential,
   getValidCodexToken,
   isCodexAccountGenerationLive,
+  readCodexAccountRecord,
 } from "./account-store";
 import { isAccountNeedsReauth, markAccountNeedsReauth } from "./account-runtime-state";
 import { ConfigMutationLockError } from "../config";
@@ -200,6 +201,19 @@ export class CodexPoolAuthenticationError extends Error {
   }
 }
 
+class CodexAccountValidationPendingError extends CodexPoolAuthenticationError {
+  constructor() {
+    super("Codex account validation is pending; refresh quota after recovery to validate it");
+    this.name = "CodexAccountValidationPendingError";
+  }
+}
+
+function assertCodexAccountValidationReady(accountId: string): void {
+  if (accountId !== MAIN_CODEX_ACCOUNT_ID && readCodexAccountRecord(accountId)?.codexValidationPending) {
+    throw new CodexAccountValidationPendingError();
+  }
+}
+
 export const CODEX_MAIN_PROFILE_MAINTENANCE_MESSAGE =
   "OpenCodex local native-main profile maintenance is active; retry this request";
 
@@ -585,6 +599,7 @@ export class CodexThreadAffinityExpiredError extends Error {
 
 export function shouldMarkAccountNeedsReauthForCodexAuthFailure(cause: unknown): boolean {
   return !(cause instanceof CodexMainAccountHardLockError)
+    && !(cause instanceof CodexAccountValidationPendingError)
     && !(cause instanceof CodexReserveUnavailableError)
     && !(cause instanceof CodexCredentialGenerationConflictError)
     && !(cause instanceof CodexCredentialRefreshLockTimeoutError)
@@ -911,6 +926,9 @@ export async function resolveCodexAuthContext(
   } finally {
     selectionAdmission?.release();
   }
+  // Legacy selectors may retain an unusable account for actionable errors. A
+  // deferred credential must never become request auth through that fallback.
+  assertCodexAccountValidationReady(accountId);
   // Lazy prime: if the selected account has no quota yet, the pool is likely
   // unprimed (dashboard never opened, or startup prime was blocked). Kick a
   // best-effort prime so the NEXT routing decision has real scores. This never
@@ -1006,6 +1024,7 @@ export async function resolveCodexAuthContext(
 
   try {
     const token = await getValidCodexToken(accountId);
+    assertCodexAccountValidationReady(accountId);
     return {
       kind: "pool",
       accountId,
@@ -1045,6 +1064,7 @@ export function applyCodexAuthContextToProvider(
   mode: CodexAccountMode | undefined,
 ): OcxRuntimeProviderConfig {
   if (mode !== "pool" || (ctx.kind !== "pool" && ctx.kind !== "main-pool") || provider.authMode !== "forward") return provider;
+  assertCodexAccountValidationReady(ctx.accountId);
   return {
     ...provider,
     _codexAccountOverride: {
@@ -1087,6 +1107,7 @@ export function materializeCodexUpstreamAuth(
     if (value) selected.set(name, value);
   }
   if (ctx.kind === "pool" || ctx.kind === "main-pool") {
+    assertCodexAccountValidationReady(ctx.accountId);
     selected.set("authorization", `Bearer ${ctx.accessToken}`);
     selected.set("chatgpt-account-id", ctx.chatgptAccountId);
     if (ctx.kind === "main-pool") {

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);

package/src/codex/catalog/parsing.ts

@@ -144,6 +144,29 @@ export interface CatalogModel {
   codexToolMode?: "code_mode_only" | "shell";
   /** Normalized upstream capability names retained for management/API consumers (#485 follow-up). */
   capabilities?: string[];
+  /**
+   * This row is listed but cannot currently serve a request (#1711). Today the only value is
+   * "no_credit", set when every usable target has positive quota-exhaustion evidence.
+   *
+   * It is NOT visibility. The row stays `visibility: "list"` on purpose: the issue explicitly
+   * rejects hiding, and Codex Desktop only understands "list" and "hide" anyway, so hiding would
+   * be the one outcome the reporter asked not to have. An OpenCodex-aware consumer greys the
+   * entry; the native picker ignores the field, which is the honest limit of what a custom
+   * catalog field can do.
+   */
+  quotaInactiveReason?: "no_credit";
+  /**
+   * Discovered per-token cost class for this routed model (#3666). "free" means the provider's
+   * own /models row reported a numeric zero for BOTH the prompt and the completion rate;
+   * "paid" means at least one rate is above zero. ABSENT means unknown — the provider published
+   * no usable pair, or this row never came from a models API at all.
+   *
+   * Fail closed: a partial, non-numeric, or negative rate leaves the field absent, never "free",
+   * because showing a paid model under a Free filter costs the user money while hiding a free
+   * one costs a click. This is a management/Dashboard projection only — deriveEntry never
+   * serializes it into the Codex catalog, and it never affects routing or visibility.
+   */
+  pricingStatus?: "free" | "paid";
   /** OpenCodex-only catalog ownership marker; Codex ignores the serialized extension field. */
   catalogKind?: typeof CODEX_CUSTOM_MODEL_CATALOG_KIND | typeof CODEX_PROVIDER_MODEL_CATALOG_KIND;
 }

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

@@ -60,6 +60,7 @@ import {
   comboModelId,
   getCombo,
   listComboIds,
+  quotaInactiveReason,
   targetKey,
 } from "../../combos";
 import type { NormalizedComboConfig } from "../../combos/types";
@@ -79,6 +80,7 @@ import {
   type ProviderModelsApiItem,
   type ResolvedProviderModelDiscovery,
 } from "../../providers/model-discovery";
+import { extractGoogleAiStudioModelItems } from "../../providers/google-ai-studio-model-discovery";
 import { applyConfiguredHeadersLast, fetchOllamaShowEnrichment, ollamaShowEnrichable } from "../../providers/ollama-show";
 import upstreamModelsSnapshot from "../data/upstream-models.json";
 import { createAdmissionGate, ResourceAdmissionError, type AdmissionMetrics } from "../../lib/admission";
@@ -1400,6 +1402,51 @@ function modelInputModalities(
   return undefined;
 }
 
+/**
+ * A per-token rate exactly as a /models row publishes it, or undefined when the value is not a
+ * usable non-negative number. Providers ship these both as JSON numbers and as decimal strings —
+ * OpenRouter encodes free as the string `"0.00000000"` — so both shapes are accepted and nothing
+ * else is. The explicit numeric-shape test has to run BEFORE any coercion: `Number("")` and
+ * `Number(" ")` are both 0 and `Number(true)` is 1, so a bare `Number(value)` would classify a
+ * row with an empty price string as free.
+ */
+const DISCOVERED_PRICING_RATE_PATTERN = /^-?\d+(?:\.\d+)?(?:[eE][-+]?\d+)?$/;
+
+function discoveredPricingRate(value: unknown): number | undefined {
+  const numeric = typeof value === "number"
+    ? value
+    : typeof value === "string" && DISCOVERED_PRICING_RATE_PATTERN.test(value.trim())
+      ? Number(value.trim())
+      : undefined;
+  if (numeric === undefined || !Number.isFinite(numeric) || numeric < 0) return undefined;
+  return numeric;
+}
+
+/**
+ * Cost class for one discovered row, read from the provider's own `pricing` object (#3666).
+ *
+ * Fail closed. Only a complete pair of non-negative numeric rates classifies at all; a missing,
+ * one-sided, non-numeric, or negative rate is "unknown" and therefore excluded from a free-only
+ * filter. Showing a paid model under a Free filter spends the user's money, while hiding a free
+ * one costs a click.
+ *
+ * Two things that look like evidence and are not. A `:free` id suffix is an OpenRouter naming
+ * convention, not a price — Nous ships `:free` slugs on a provider whose `freeTier` is false on
+ * purpose. And the operator's own `modelCosts` overlay is an estimate they typed, not something
+ * the provider published, so a zeroed overlay never reaches this field either.
+ *
+ * Classification is on numeric zero and never on a unit conversion: OpenRouter quotes USD per
+ * token while the cost overlays and the jawcode bundle quote per 1M, and zero is zero in both.
+ */
+export function discoveredPricingStatus(item: ProviderModelsApiItem): "free" | "paid" | "unknown" {
+  const pricing = plainRecord(item.pricing) ?? plainRecord(plainRecord(item.metadata)?.pricing);
+  if (!pricing) return "unknown";
+  const prompt = discoveredPricingRate(pricing.prompt ?? pricing.input);
+  const completion = discoveredPricingRate(pricing.completion ?? pricing.output);
+  if (prompt === undefined || completion === undefined) return "unknown";
+  return prompt === 0 && completion === 0 ? "free" : "paid";
+}
+
 export function catalogHintsFromModelsApiItem(providerName: string, item: ProviderModelsApiItem): Partial<CatalogModel> {
   const metadata = plainRecord(item.metadata);
   const capabilityRecord = plainRecord(metadata?.capabilities) ?? plainRecord(item.capabilities);
@@ -1464,6 +1511,7 @@ export function catalogHintsFromModelsApiItem(providerName: string, item: Provid
       : undefined;
   const capabilities = modelCapabilities(item);
   const inputModalities = modelInputModalities(item, capabilities);
+  const pricingStatus = discoveredPricingStatus(item);
   return {
     ...(contextWindow && contextWindow > 0 ? { contextWindow } : {}),
     ...(maxInputTokens && maxInputTokens > 0 ? { maxInputTokens } : {}),
@@ -1471,6 +1519,11 @@ export function catalogHintsFromModelsApiItem(providerName: string, item: Provid
     ...(reasoningEfforts !== undefined ? { reasoningEfforts } : {}),
     ...(inputModalities ? { inputModalities } : {}),
     ...(capabilities ? { capabilities } : {}),
+    // Omitted when the classification is "unknown", following this function's existing
+    // contract that an unknown property is absent rather than present-and-empty. Callers
+    // that need to tell "provider published no prices" from "this build does not classify"
+    // call discoveredPricingStatus directly.
+    ...(pricingStatus !== "unknown" ? { pricingStatus } : {}),
   };
 }
 
@@ -1871,7 +1924,14 @@ async function fetchProviderModelsWithAuth(
       markProviderDiscoveryOk(name, live.length);
       return observed(withConfiguredRetention(forCache, { warnDrops: true }), "authoritative");
     }
-    const extracted = extractProviderModelItems(bounded.value, discovery);
+    const googleAiStudio = effectiveGoogleMode(name, prov) === "ai-studio"
+      ? extractGoogleAiStudioModelItems(bounded.value, discovery.maxModels)
+      : undefined;
+    // Native /v1beta/models wins; a google row served by an OpenAI-compatible
+    // gateway keeps the generic data[] / top-level-array contract.
+    const extracted = googleAiStudio?.ok
+      ? googleAiStudio
+      : extractProviderModelItems(bounded.value, discovery);
     if (!extracted.ok) {
       const { models, fallback, shouldLog } = failedDiscoveryFallback({ reason: "invalid_response" });
       const diagnostic: Record<ModelDiscoveryResponseFailure, string> = {
@@ -2622,7 +2682,16 @@ async function gatherRoutedModelsUncached(
   return {
     models: models.map(model => {
       const displayName = aliasDisplayNames.get(`${model.provider}/${model.id}`);
-      return displayName && !model.displayName ? { ...model, displayName } : model;
+      // #1711: one stamping point for every row this gather produces — routed, combo, and custom
+      // alike — because it is the only place that has both the finished list and the config the
+      // quota rules need. A combo votes over its own targets; anything else votes over the single
+      // provider that would serve it.
+      const targets = model.provider === COMBO_NAMESPACE
+        ? config.combos?.[model.id]?.targets ?? []
+        : [{ provider: model.provider }];
+      const inactive = quotaInactiveReason(config, targets);
+      const named = displayName && !model.displayName ? { ...model, displayName } : model;
+      return inactive ? { ...named, quotaInactiveReason: inactive } : named;
     }),
     comboOmissions: localOmissions,
     providerAuthOutcomes: localProviderAuthOutcomes,

package/src/codex/catalog/sync.ts

@@ -42,6 +42,8 @@ import {
   resolveCodexModelEntitlements,
   type CodexModelEntitlementSnapshot,
 } from "../model-entitlements";
+import { isAccountNeedsReauth } from "../account-runtime-state";
+import { codexAccountLogLabel, fallbackCodexAccountLogLabel } from "../account-label";
 
 
 import { CODEX_CUSTOM_MODEL_CATALOG_KIND, CODEX_PROVIDER_MODEL_CATALOG_KIND, activeCodexModelsCachePath, applyCatalogMetadata, applyMultiAgentMode, applyNativeOpenAiContextOverride, applyRoutedCodexToolMode, catalogBackupPathFor, catalogHasRoutedEntries, catalogModelSlug, ensureStrictCatalogFields, findNativeTemplate, findSupportedNativeTemplate, isDefaultCatalogPath, isRoutedModelCompatibilityExcluded, legacyCatalogBackupPath, normalizeRoutedCatalogEntry, normalizeServiceTiers, readCatalog, readCatalogBackup, readCodexCatalogPath, readCodexCatalogPathForHome, readConfiguredAutoReviewModel, readNativeBaseline } from "./parsing";
@@ -99,6 +101,12 @@ export const PICKER_ORDER_PRIORITY_BASE = 1_000;
 // independent of display order. It does not freeze native advertisements. Absent on unmoved rows.
 export const SPAWN_PRIORITY_FIELD = "opencodex_spawn_priority";
 
+// OpenCodex-private catalog field: this row is listed but currently unable to serve (#1711).
+// Codex ignores unknown catalog fields (same as opencodex_catalog_kind and the spawn priority
+// above) and ensureStrictCatalogFields does not strip extras, so this is invisible to the native
+// picker and cannot change what Codex offers. It never touches `visibility`.
+export const CATALOG_INACTIVE_REASON_FIELD = "opencodex_inactive_reason";
+
 export type SpawnAgentSurface = "v1" | "v2";
 
 export type SubagentRosterExclusionReason =
@@ -383,6 +391,10 @@ export function deriveEntry(
       if (model) applyCatalogMetadata(e, model.provider, model.id, model.contextCap);
       applyCatalogModelMetadata(e, model);
       if (model?.catalogKind) e.opencodex_catalog_kind = model.catalogKind;
+      // Additive only. `visibility` is untouched: an inactive row must still be OFFERED, which is
+      // the whole point of #1711 — operator disable is what removes rows, and it stays a separate
+      // path from this one.
+      if (model?.quotaInactiveReason) e[CATALOG_INACTIVE_REASON_FIELD] = model.quotaInactiveReason;
     } else {
       applyNativeOpenAiContextOverride(e, contextCap);
       if (isGpt56NativeSlug(slug)) ensureGpt56ReasoningLevels(e);
@@ -430,6 +442,10 @@ export function deriveEntry(
   if (model && isRouted) applyCatalogMetadata(entry, model.provider, model.id, model.contextCap);
   applyCatalogModelMetadata(entry, model);
   if (model?.catalogKind) entry.opencodex_catalog_kind = model.catalogKind;
+  // Same additive stamp as the templated path above. A routed row that reaches the no-template
+  // fallback is still a served row, so omitting it here would make the field depend on whether a
+  // template happened to be cached — which is exactly what the regression test caught.
+  if (model?.quotaInactiveReason) entry[CATALOG_INACTIVE_REASON_FIELD] = model.quotaInactiveReason;
   if (!isRouted) applyNativeOpenAiContextOverride(entry, contextCap);
   return ensureStrictCatalogFields(normalizeServiceTiers(entry), {
     preserveExactInputModalities: preserveExact,
@@ -1694,6 +1710,75 @@ export function finalizeAutoReviewModelOverride(
   return applyAutoReviewModelOverride(models, readConfiguredAutoReviewModel(), sourceModels);
 }
 
+/**
+ * Why an account-gated native model stopped being offered, but only when the answer is one the
+ * operator can act on.
+ *
+ * Suppression is an omission: the row is never built, so there is no catalog entry for a reason
+ * to ride on and no downstream consumer that could explain it later. #4212's reporter watched
+ * their models disappear and reasonably concluded the proxy was broken, because every surface
+ * that changed said nothing about the account that caused it.
+ *
+ * Returns `undefined` for the ordinary case — an account that is simply not entitled to a gated
+ * model. That is the default state for most installations, it is not news, and warning about it
+ * on every sync would bury the one case that matters. A credential the operator must repair is
+ * the case that matters, so that is the only one this speaks up about.
+ *
+ * Accounts are named with the durable `p`-prefixed log label, the same identifier the dashboard
+ * shows, never the raw pool id or the email.
+ */
+export function gatedNativeReauthSuppressionReason(args: {
+  snapshot: CodexModelEntitlementSnapshot;
+  slug: string;
+  eligibleAccountIds?: ReadonlySet<string>;
+  needsReauth: (accountId: string) => boolean;
+  label: (accountId: string) => string;
+}): string | undefined {
+  const observed = [...args.snapshot.modelsByAccount.keys()]
+    .filter(accountId => !args.eligibleAccountIds || args.eligibleAccountIds.has(accountId))
+    // Only accounts that could actually have served THIS model. An account upstream positively
+    // denied is not why the model is missing, and blaming it would send the operator to repair a
+    // credential that was never going to help. `unknown` has to stay in: an account whose roster
+    // could not be confirmed reports `unknown` rather than `granted`, and a credential stuck on
+    // a failed refresh is exactly that account.
+    .filter(accountId => (
+      codexModelEntitlementStateForAccount(args.snapshot, accountId, args.slug) !== "denied"
+    ));
+  const stuck = observed.filter(accountId => args.needsReauth(accountId));
+  if (stuck.length === 0) return undefined;
+  const names = stuck.map(accountId => args.label(accountId)).sort().join(", ");
+  return stuck.length === observed.length
+    ? `every Codex account that could serve it needs reauthentication (${names})`
+    : `${stuck.length} of ${observed.length} Codex accounts that could serve it need reauthentication (${names})`;
+}
+
+/** Durable, operator-facing label for a pool account id; never the raw id or the email. */
+function gatedNativeAccountLabel(config: OcxConfig, accountId: string): string {
+  // Direct mode narrows eligibility to the native main credential, so this is the account most
+  // likely to be named here. `codexAuthContextLogLabel` calls it "main" everywhere else; hashing
+  // it into a `p`-prefixed digest would name the one account the operator cannot look up.
+  if (accountId === MAIN_CODEX_ACCOUNT_ID) return "main";
+  const account = (config.codexAccounts ?? []).find(candidate => candidate.id === accountId);
+  return account ? codexAccountLogLabel(account) : fallbackCodexAccountLogLabel(accountId);
+}
+
+const warnedGatedNativeSuppression = new Set<string>();
+
+/** Test seam: the warn-once memory is process-global, so a case needs to be able to clear it. */
+export function resetGatedNativeSuppressionWarningsForTests(): void {
+  warnedGatedNativeSuppression.clear();
+}
+
+function warnGatedNativeSuppressedOnce(slug: string, reason: string): void {
+  const signature = `${slug}\u0000${reason}`;
+  if (warnedGatedNativeSuppression.has(signature)) return;
+  warnedGatedNativeSuppression.add(signature);
+  console.warn(
+    `[opencodex] catalog sync: ${slug} is not being offered because ${reason}. `
+      + "Sign in again to restore it.",
+  );
+}
+
 /**
  * Mescla o catálogo retido com os modelos visíveis e as configurações atuais,
  * incluindo os nomes nativos. Tenta preservar o backup original e usa a permissão
@@ -1763,6 +1848,20 @@ function writeRetainedCatalogSync({
   const unavailableGatedNativeSlugs = new Set([...ACCOUNT_GATED_NATIVE_OPENAI_MODELS].filter(slug => (
     !availableBareGatedNativeSlugs.has(slug)
   )));
+  // #4212: this set is the whole record of a model vanishing, and it is a set of strings that
+  // nothing downstream ever asks a question of. Explain it here, while the entitlement snapshot
+  // that produced it is still in scope, because after this point the model is simply absent and
+  // no later surface can tell "never entitled" apart from "the account broke this morning".
+  for (const slug of unavailableGatedNativeSlugs) {
+    const reason = gatedNativeReauthSuppressionReason({
+      snapshot: modelEntitlements,
+      slug,
+      eligibleAccountIds: bareEligibleAccountIds,
+      needsReauth: isAccountNeedsReauth,
+      label: accountId => gatedNativeAccountLabel(config, accountId),
+    });
+    if (reason) warnGatedNativeSuppressedOnce(slug, reason);
+  }
   const suppressedBareNativeSlugs = new Set([
     ...desktopAllowlistSuppressedNativeSlugs(config),
     ...unavailableGatedNativeSlugs,

package/src/codex/codex-write-lock.ts

@@ -66,7 +66,7 @@ export type CodexWriteLockRefusalReason =
 
 export type CodexWriteLockResult<T> =
   | { status: "acquired"; value: T; waitedMs: number; lockId: string }
-  | { status: "skipped"; reason: "desired_disabled" | "desired_enabled"; waitedMs: number }
+  | { status: "skipped"; reason: CodexWriteLockSkipReason; waitedMs: number }
   | { status: "busy"; reason: "deadline" | "cancelled"; retryable: true; waitedMs: number; lockId: string }
   | {
       status: "refused";
@@ -127,9 +127,18 @@ export interface CodexWriteCommitContext {
   readonly coordinator: CodexCoordinatorTransaction;
 }
 
+/**
+ * Why an under-lock policy re-read refused the write.
+ *
+ * `hub-gated` is not the user's switch: a hub declines to rewrite its own local clients, and
+ * reporting that as "integration is OFF" sent operators hunting for a toggle they never set
+ * (#4236).
+ */
+export type CodexWriteLockSkipReason = "desired_disabled" | "desired_enabled" | "hub-gated";
+
 /** A synchronous under-lock policy re-read proved the requested apply stale. */
 export class CodexWriteLockSkipped extends Error {
-  constructor(readonly reason: "desired_disabled" | "desired_enabled") {
+  constructor(readonly reason: CodexWriteLockSkipReason) {
     super(reason);
     this.name = "CodexWriteLockSkipped";
   }

package/src/codex/desired-state.ts

@@ -76,11 +76,57 @@ type LocalClientSyncConfig = Pick<
   "clientIntegrations" | "runtimeRole" | "unauthenticatedLoopbackListener"
 >;
 
-function localClientSyncAllowed(config: LocalClientSyncConfig): boolean {
+export function localClientSyncAllowed(config: LocalClientSyncConfig): boolean {
   return config.runtimeRole !== "hub"
     || config.unauthenticatedLoopbackListener?.enabled === true;
 }
 
+/**
+ * The one sentence every hub-gated skip says (#4236).
+ *
+ * The gate is a reasonable decision; reporting it as "Codex integration is OFF" was not. An
+ * operator whose `clientIntegrations` says nothing — or says `true` — was told their own switch
+ * was off, and `ocx restore back` went further and blamed a competing writer that did not
+ * exist. Name the gate and name the key that opens it.
+ */
+export const HUB_GATED_SKIP_MESSAGE =
+  "This machine is a hub; it does not rewrite its own Codex/Grok/Claude configs unless "
+  + "unauthenticatedLoopbackListener is enabled.";
+
+/** Why a local-client write was skipped. The gate outranks the toggle: it is the surprising one. */
+export type LocalClientSkipReason = "desired_disabled" | "hub-gated";
+
+/**
+ * "hub-gated" is claimed only when the toggle is ON and the gate is what stopped the write.
+ * With the toggle OFF the gate is moot: telling that operator to enable the loopback listener
+ * would send them to a key that cannot make the sync happen — the mirror image of the defect
+ * this reason exists to fix.
+ */
+export function localClientSkipReason(
+  config: LocalClientSyncConfig,
+  client: DurableIntentClientId = "codex",
+): LocalClientSkipReason {
+  return integrationEnabled(config, client) && !localClientSyncAllowed(config)
+    ? "hub-gated"
+    : "desired_disabled";
+}
+
+/**
+ * Pick the skip message for a snapshot: today's toggle text, or the hub-gate sentence.
+ *
+ * `hubSuffix` states what the hub-gated path still did (a catalog refresh, say) so the
+ * composed line stays as informative as the toggle one it replaces.
+ */
+export function localClientSkipMessage(
+  config: LocalClientSyncConfig,
+  integrationOffMessage: string,
+  hubSuffix?: string,
+  client: DurableIntentClientId = "codex",
+): string {
+  if (localClientSkipReason(config, client) !== "hub-gated") return integrationOffMessage;
+  return hubSuffix ? `${HUB_GATED_SKIP_MESSAGE} ${hubSuffix}` : HUB_GATED_SKIP_MESSAGE;
+}
+
 export function shouldSyncCodexOnStart(config: LocalClientSyncConfig): boolean {
   // A hub is a server for OTHER machines: it must not rewrite its own host's
   // Codex/Claude/Grok client configs on startup (interview decision Q6, and the

package/src/codex/inject-coordination.ts

@@ -8,7 +8,8 @@ import { createHash } from "node:crypto";
 import { existsSync, lstatSync, readFileSync } from "node:fs";
 
 import { atomicWriteFile } from "../config";
-import type { CodexWriteLockResult } from "./codex-write-lock";
+import type { CodexWriteLockResult, CodexWriteLockSkipReason } from "./codex-write-lock";
+import { HUB_GATED_SKIP_MESSAGE } from "./desired-state";
 import { inspectCodexCoordinatorPath } from "./coordinator-doctor";
 import { JOURNAL_PATH } from "./journal";
 import { updateIntegrationRecord } from "./integration-record";
@@ -443,16 +444,20 @@ export function recomputeInjectWitness(options: {
 export function codexInjectLockOutcome(
   result: Exclude<CodexWriteLockResult<unknown>, { status: "acquired" }>,
 ): { success: false; message: string; retryable: boolean } | {
-  success: true; status: "skipped"; skippedReason: "desired_disabled" | "desired_enabled"; message: string;
+  success: true; status: "skipped"; skippedReason: CodexWriteLockSkipReason; message: string;
 } {
   if (result.status === "skipped") {
     return {
       success: true,
       status: "skipped",
       skippedReason: result.reason,
-      message: result.reason === "desired_disabled"
-        ? "Codex integration is OFF; no Codex config, catalog, cache, or history was changed."
-        : "Codex integration was re-enabled; native restore was skipped.",
+      // Three distinct facts, three sentences. The hub gate in particular must not borrow the
+      // toggle's wording — that is the phantom "integration is OFF" report from #4236.
+      message: result.reason === "hub-gated"
+        ? `${HUB_GATED_SKIP_MESSAGE} No Codex config, catalog, cache, or history was changed.`
+        : result.reason === "desired_disabled"
+          ? "Codex integration is OFF; no Codex config, catalog, cache, or history was changed."
+          : "Codex integration was re-enabled; native restore was skipped.",
     };
   }
   if (result.status === "busy") {