@bitkyc08/opencodex 2.39.0 → 2.40.0

package/src/codex/auth-context.ts

@@ -10,6 +10,7 @@ import {
 import { isAccountNeedsReauth, markAccountNeedsReauth } from "./account-runtime-state";
 import { isCodexAccountPaused } from "./account-pause";
 import { ConfigMutationLockError } from "../config";
+import { NativeProfileError } from "./native-profile-types";
 import { isCodexAccountUsable } from "./account-usability";
 import { reconcileMainCodexAccountRuntimeState } from "./account-lifecycle";
 import {
@@ -25,7 +26,9 @@ import { isNativeMainTrafficBlocked, nativeMainStartupGateSnapshot } from "./nat
 import type { NativeMainStartupBlockReason } from "./native-profile-startup";
 import {
   codexQuotaScopeForModel,
+  computeCodexUsageScore,
   getCodexQuotaHealthSnapshot,
+  isEffectiveCodexAccountPinned,
   releaseCodexQuotaProbeLease,
   releaseCodexQuotaScopeProbeLease,
   tryAcquireCodexQuotaProbeLease,
@@ -42,7 +45,7 @@ import { ACCOUNT_GATED_NATIVE_OPENAI_MODELS } from "./catalog/native-models";
 import type { CodexCooldownSource, CodexQuotaScope } from "./routing";
 import { maskAccountId } from "../lib/privacy";
 import { formatErrorResponse } from "../bridge";
-import { getAccountQuota } from "./quota";
+import { CODEX_UNKNOWN_USAGE_SCORE, getAccountQuota } from "./quota";
 import type { CodexAccountMode, OcxConfig, OcxProviderConfig } from "../types";
 import { FORWARD_HEADERS } from "../adapters/openai-responses";
 import { captureConfigGeneration } from "../lib/state-store-sweeper";
@@ -52,6 +55,21 @@ import { extractAccountId } from "../oauth/chatgpt";
 const CODEX_AFFINITY_COMPONENT_MAX_BYTES = 512;
 const CODEX_APP_AFFINITY_KEY = randomBytes(32);
 
+/**
+ * A request-owned bearer cannot inspect the physical main credential for its plan, but cached
+ * WHAM usage is still valid routing evidence for the same logical main account. Score it with
+ * the conservative unknown-plan rule: an unobserved governing window preserves the pin, while
+ * any known weekly/monthly/short value at the threshold releases it through the ordinary Pool
+ * path. This keeps the keyring boundary intact instead of reading auth.json just to classify a
+ * request that already brought its own credential (#3157).
+ */
+function requestOwnedMainPinHasQuotaHeadroom(config: OcxConfig): boolean {
+  const threshold = config.autoSwitchThreshold ?? 80;
+  if (threshold <= 0) return true;
+  const usage = computeCodexUsageScore(getAccountQuota(MAIN_CODEX_ACCOUNT_ID));
+  return usage >= CODEX_UNKNOWN_USAGE_SCORE || usage < threshold;
+}
+
 function boundedCodexAffinityComponent(value: string | null): string | undefined {
   const normalized = value?.trim();
   if (!normalized) return undefined;
@@ -328,6 +346,8 @@ export function shouldMarkAccountNeedsReauthForCodexAuthFailure(cause: unknown):
     && !(cause instanceof CodexCredentialRefreshStaleError)
     && !(cause instanceof MainAuthJsonChangedDuringRefreshError)
     && !(cause instanceof MainAccountTokenRefreshError && cause.reason === "transient")
+    && !(cause instanceof NativeProfileError && cause.retryable)
+    && !(cause instanceof DOMException && cause.name === "AbortError")
     && !(cause instanceof ConfigMutationLockError);
 }
 
@@ -372,6 +392,12 @@ export async function resolveCodexAuthContext(
   const requestScopedMainCredential = options.requestScopedMainCredential === true
     && hasCallerCodexBearer(headers);
   const fixedAccountId = options.accountId;
+  const preserveRequestOwnedMainPin = requestScopedMainCredential
+    && fixedAccountId === undefined
+    && config.activeCodexAccountPinned === MAIN_CODEX_ACCOUNT_ID
+    && isEffectiveCodexAccountPinned(config)
+    && !isCodexAccountPaused(config, MAIN_CODEX_ACCOUNT_ID)
+    && requestOwnedMainPinHasQuotaHeadroom(config);
   if (fixedAccountId !== undefined && options.excludeAccountId !== undefined) {
     throw new Error("Codex auth context cannot select and exclude an account simultaneously");
   }
@@ -425,6 +451,19 @@ export async function resolveCodexAuthContext(
       directSelectionAdmission.release();
     }
   };
+  // Pool discovery excludes request-owned main credentials by design: they must never be folded
+  // into stored-account entitlement, affinity, or persistence state. An effective manual main pin
+  // is the one exception where that exclusion is selection evidence in the opposite direction.
+  // Validate the caller's own gated-model roster before using it, and fall through to a Pool model
+  // detour when it lacks the grant. This branch performs no physical-main credential read.
+  if (preserveRequestOwnedMainPin) {
+    const callerEntitled = !options.modelId
+      || !ACCOUNT_GATED_NATIVE_OPENAI_MODELS.has(options.modelId)
+      || await (
+        options.isDirectCallerEntitledToCodexModel ?? isDirectCallerEntitledToCodexModel
+      )(headers, options.modelId);
+    if (callerEntitled) return { kind: "main", accountId: null };
+  }
   // An explicit namespace binding is stronger than the provider's default mode. It must use the
   // selected stored credential even while the canonical OpenAI provider is globally Direct.
   // A request-owned bearer is deliberately not represented as `main-pool`: Pool account ids own
@@ -455,6 +494,7 @@ export async function resolveCodexAuthContext(
     const excludeAccountIds = nativeMainReadsForbidden
       ? new Set([MAIN_CODEX_ACCOUNT_ID])
       : undefined;
+    const mainModelGrantUnobserved = excludeAccountIds?.has(MAIN_CODEX_ACCOUNT_ID) === true;
     const entitlementSnapshot = options.modelId && ACCOUNT_GATED_NATIVE_OPENAI_MODELS.has(options.modelId)
       ? await (options.resolveCodexModelEntitlements ?? resolveCodexModelEntitlements)(config, {
         excludeAccountIds,
@@ -473,7 +513,10 @@ export async function resolveCodexAuthContext(
       // it. Retained recovery makes main wholly ineligible so pool routing continues.
       nativeMainSelectionOnly,
       isMainAccountTokenLive: requestScopedMainCredential
-        ? () => false
+        // Main stays excluded from this request's model roster below. This synthetic liveness is
+        // consulted only by shared-state preservation, so a caller-owned pin survives a model
+        // detour without reading or selecting the physical main credential.
+        ? () => preserveRequestOwnedMainPin
         : options.isMainAccountTokenLive,
       modelEligibleAccountIds,
     };
@@ -507,7 +550,15 @@ export async function resolveCodexAuthContext(
     if (resolution.status === "expired") throw new CodexThreadAffinityExpiredError(resolution.accountId);
     const selected = resolution.status === "selected" ? resolution.accountId : null;
     if (!selected) {
-      if (requestScopedMainCredential && fixedAccountId === undefined && !options.excludeAccountId) {
+      // A retry that excluded a failed Pool account may still use the validated caller-owned
+      // main credential. Treating every exclusion as if main itself had failed strands a healthy
+      // native bearer after the first Pool attempt. Preserve the exactly-once boundary by refusing
+      // this fallback only when the excluded credential is main.
+      if (
+        requestScopedMainCredential
+        && fixedAccountId === undefined
+        && options.excludeAccountId !== MAIN_CODEX_ACCOUNT_ID
+      ) {
         return await resolveCallerOwnedMainContext();
       }
       if (fixedAccountId !== undefined) {
@@ -527,7 +578,11 @@ export async function resolveCodexAuthContext(
         throw new CodexMainProfileDrainingError();
       }
       throw new CodexPoolAuthenticationError(
-        modelEligibleAccountIds ? "No eligible Codex account supports this model" : undefined,
+        modelEligibleAccountIds === undefined
+          ? undefined
+          : entitledAccountIds?.size === 0 && !mainModelGrantUnobserved
+          ? "No eligible Codex account supports this model"
+          : "Codex accounts that support this model are currently unavailable",
       );
     }
     accountId = selected;
@@ -615,7 +670,7 @@ export async function resolveCodexAuthContext(
     } catch (cause) {
       if (probeLeaseId && probeQuotaScope) releaseCodexQuotaScopeProbeLease(accountId, probeQuotaScope, probeLeaseId);
       else if (probeLeaseId) releaseCodexQuotaProbeLease(accountId, probeLeaseId);
-      if (shouldMarkAccountNeedsReauthForCodexAuthFailure(cause)) {
+      if (!options.signal?.aborted && shouldMarkAccountNeedsReauthForCodexAuthFailure(cause)) {
         markAccountNeedsReauth(accountId, writerGeneration);
       }
       throw new CodexAuthContextError(accountId, cause);
@@ -660,7 +715,7 @@ export async function resolveCodexAuthContext(
   } catch (cause) {
     if (probeLeaseId && probeQuotaScope) releaseCodexQuotaScopeProbeLease(accountId, probeQuotaScope, probeLeaseId);
     else if (probeLeaseId) releaseCodexQuotaProbeLease(accountId, probeLeaseId);
-    if (shouldMarkAccountNeedsReauthForCodexAuthFailure(cause)) {
+    if (!options.signal?.aborted && shouldMarkAccountNeedsReauthForCodexAuthFailure(cause)) {
       markAccountNeedsReauth(accountId, writerGeneration);
     }
     throw new CodexAuthContextError(accountId, cause);

package/src/codex/catalog/aggregation.ts

@@ -8,7 +8,7 @@ import { clearModelCache, DEFAULT_MODEL_CACHE_TTL_MS, getFreshCached, getStaleCa
 import { buildModelsRequest, resolveModelsAuthToken } from "../../oauth";
 import type { OcxConfig, OcxProviderConfig } from "../../types";
 import { modelInList } from "../../types";
-import { CODEX_REASONING_LEVELS, codexEffortRank, configuredReasoningEfforts, modelRecordValue, sanitizeCodexReasoningEfforts } from "../../reasoning-effort";
+import { CODEX_REASONING_LEVELS, codexEffortRank, configuredReasoningEfforts, modelRecordValue, resolveEffortAtOrBelow, sanitizeCodexReasoningEfforts } from "../../reasoning-effort";
 import { getModelMetadata, getModelMetadataCaseInsensitive, listModelMetadata, resolveMetadataProvider } from "../../generated/model-metadata";
 import { enrichProviderFromRegistry, shouldCaseFoldMetadataModelId } from "../../providers/derive";
 import { getProviderRegistryEntry } from "../../providers/registry";
@@ -77,20 +77,16 @@ export function intersectStrings(values: readonly string[][]): string[] {
   return [...new Set(values[0])].filter(value => rest.every(set => set.has(value)));
 }
 
+/**
+ * The catalog's view of a combo's default effort. Delegates to the shared leaf
+ * resolver so the request path (src/combos/request.ts) cannot drift from what the
+ * catalog advertised (#3108).
+ */
 export function effectiveComboDefault(
   configured: string | null | undefined,
   common: readonly string[],
 ): string | undefined {
-  if (!configured) return undefined;
-  if (configured && common.includes(configured)) return configured;
-  const requestedRank = codexEffortRank(configured);
-  const ranked = common
-    .map(effort => ({ effort, rank: codexEffortRank(effort) }))
-    .filter(item => item.rank >= 0)
-    .sort((a, b) => a.rank - b.rank);
-  if (ranked.length === 0) return undefined;
-  const atOrBelow = ranked.filter(item => item.rank <= requestedRank);
-  return atOrBelow.at(-1)?.effort ?? ranked[0]!.effort;
+  return resolveEffortAtOrBelow(configured, common);
 }
 
 /**
@@ -138,10 +134,18 @@ export function deriveComboCatalogModel(
     : derivedInputModalities;
   if (inputModalities.length === 0) return null;
   // Unknown ladders (`undefined`) are wildcards for catalog derivation — same
-  // boundary as the GUI picker. An explicit empty ladder still constrains.
-  const advertisedLadders = members
+  // boundary as the GUI picker. Under the default `strict` mode an explicit empty
+  // ladder still constrains, so one target that advertises no effort control empties
+  // the whole combo's picker. `adaptive` is the opt-in for mixed-capability groups:
+  // empty ladders drop out of the published intersection while non-empty ladders
+  // still define it. Dispatch is unaffected either way — each concrete target
+  // resolves its own effort at request time.
+  const knownLadders = members
     .map(member => member.reasoningEfforts)
     .filter((ladder): ladder is string[] => ladder !== undefined);
+  const advertisedLadders = combo.reasoningEffortMode === "adaptive"
+    ? knownLadders.filter(ladder => ladder.length > 0)
+    : knownLadders;
   const reasoningEfforts = advertisedLadders.length === 0
     ? []
     : intersectStrings(advertisedLadders);

package/src/codex/catalog/metadata.ts

@@ -271,6 +271,34 @@ export function nativeOpenAiContextWindow(slug: string, limits?: NativeContextLi
   return narrowToLimits(raw, slug, limits);
 }
 
+/**
+ * Long-context tier for a native slug as a (default, long) pair, for clients that let the user
+ * pick a window per request (Cursor's local-agent "Context" selector). The pair is the family's
+ * pinned default window and its opt-in ceiling, independent of whether the operator has
+ * already opted the proxy into the long window: the selector exists so the client can choose.
+ * Any user lever below the long window removes the tier: a per-model window override, the
+ * provider-level window override, or a provider context cap. A lever at or above it leaves the
+ * tier intact (the 922k/1050k opt-in values are the levers, not a request to shrink). Undefined
+ * when the family has no separate tier or when the two windows coincide.
+ */
+export function nativeOpenAiContextTier(
+  slug: string,
+  limits?: NativeContextLimitsInput,
+): { defaultWindow: number; longWindow: number } | undefined {
+  const override = NATIVE_OPENAI_CONTEXT_OVERRIDES[slug];
+  const defaultWindow = positiveInt(override?.contextWindow);
+  const longWindow = positiveInt(override?.maxContextWindow);
+  if (defaultWindow === undefined || longWindow === undefined || longWindow <= defaultWindow) return undefined;
+  const resolved = asLimits(limits);
+  const levers = [
+    positiveInt(resolved.modelWindows?.[slug]),
+    positiveInt(resolved.providerWindow),
+    positiveInt(resolved.cap),
+  ];
+  if (levers.some(lever => lever !== undefined && lever < longWindow)) return undefined;
+  return { defaultWindow, longWindow };
+}
+
 /**
  * Largest input a native slug accepts, or undefined when no separate limit is known
  * (the caller then falls back to the context window).

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

@@ -2,7 +2,8 @@ import { execFileSync } from "node:child_process";
 import { createHash, createHmac, randomBytes } from "node:crypto";
 import { copyFileSync, existsSync, mkdirSync, readFileSync, realpathSync } from "node:fs";
 import { delimiter, dirname, join, resolve } from "node:path";
-import { atomicWriteFile, expandUserPath, getConfigDir, resolveEnvValue, websocketsEnabled } from "../../config";
+import { atomicWriteFile, expandUserPath, getConfigDir, websocketsEnabled } from "../../config";
+import { resolveProviderApiKey } from "../../providers/key-store";
 import { CODEX_CONFIG_PATH, CODEX_MODELS_CACHE_PATH, DEFAULT_CATALOG_PATH, readRootTomlString, resolveCodexConfigPath } from "../paths";
 import {
   clearModelCache,
@@ -571,7 +572,9 @@ function providerCatalogFingerprint(name: string, prov: OcxProviderConfig): Reco
     base: prov.baseUrl ?? "",
     adapter: prov.adapter ?? "",
     models: [...(prov.models ?? [])].sort(),
+    retain: [...(prov.retainModels ?? [])].sort(),
     selected: [...(prov.selectedModels ?? [])].sort(),
+    displayNames: prov.modelDisplayNames ?? null,
     defaultModel: prov.defaultModel ?? null,
     ctx: prov.contextWindow ?? null,
     ctxW: prov.modelContextWindows ?? null,
@@ -627,6 +630,16 @@ export function configuredInputModalities(prov: OcxProviderConfig, id: string):
   return Array.isArray(modalities) && modalities.length > 0 ? [...modalities] : undefined;
 }
 
+/** Exact display-only override for one provider-native model id. */
+export function configuredModelDisplayName(
+  prov: OcxProviderConfig,
+  id: string,
+): string | undefined {
+  if (!prov.modelDisplayNames || !Object.hasOwn(prov.modelDisplayNames, id)) return undefined;
+  const value = prov.modelDisplayNames[id];
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
 export function configuredMaxInputTokens(prov: OcxProviderConfig, id: string): number | undefined {
   const configured = modelRecordValue(prov.modelMaxInputTokens, id);
   return typeof configured === "number" && configured > 0 ? configured : undefined;
@@ -667,6 +680,7 @@ function configuredVerbositySupport(name: string, prov: OcxProviderConfig | unde
 }
 
 export function applyProviderConfigHints(name: string, prov: OcxProviderConfig, model: CatalogModel, providerCap?: number): CatalogModel {
+  const displayName = configuredModelDisplayName(prov, model.id);
   const configuredCap = configuredContextWindow(prov, model.id);
   const configuredMaxInput = configuredMaxInputTokens(prov, model.id);
   const configuredAutoCompact = configuredAutoCompactTokenLimit(prov, model.id);
@@ -702,6 +716,7 @@ export function applyProviderConfigHints(name: string, prov: OcxProviderConfig,
     : (configuredCap ?? (providerCap !== undefined ? resolveUnknownRoutedContextWindow(providerCap) : undefined));
   const hinted = {
     ...modelWithoutServiceTier,
+    ...(displayName !== undefined ? { displayName } : {}),
     ...(hintedWindow !== undefined ? { contextWindow: hintedWindow } : {}),
     ...(inputModalities ? { inputModalities } : {}),
     ...(reasoningEfforts !== undefined ? { reasoningEfforts } : {}),
@@ -1195,9 +1210,15 @@ export function catalogHintsFromModelsApiItem(providerName: string, item: Provid
   const metadata = plainRecord(item.metadata);
   const capabilityRecord = plainRecord(metadata?.capabilities) ?? plainRecord(item.capabilities);
   const limits = plainRecord(metadata?.limits);
+  const capabilityLimits = plainRecord(plainRecord(item.capabilities)?.limits);
   const contextWindow =
     positiveSafeInteger(
       limits?.max_context_length,
+      // GitHub Copilot reports the live context window here instead of in the metadata or
+      // top-level fields used by other OpenAI-compatible catalogs (#3156). Keep the existing
+      // metadata field authoritative when both are present: adding this provider-specific
+      // fallback must not change previously recognized providers.
+      capabilityLimits?.max_context_window_tokens,
       metadata?.context_length,
       item.context_length,
       item.context_size,
@@ -1262,7 +1283,7 @@ function observedModelsAuthResolver(
     resolve(name, provider) {
       if (provider.authMode === "forward") return { apiKey: undefined, observed: true };
       if (provider.authMode !== "oauth") {
-        return { apiKey: resolveEnvValue(provider.apiKey), observed: true };
+        return { apiKey: resolveProviderApiKey(provider.apiKey), observed: true };
       }
 
       const observation = observeActiveOAuthAccessToken(name, authStoreBuffer);
@@ -1298,7 +1319,14 @@ async function fetchProviderModelsWithAuth(
     && prov.googleMode === "vertex"
     && (prov.models?.length ?? 0) === 0
     && Boolean(prov.defaultModel);
-  const configuredIds = seedVertexDefault && prov.defaultModel ? [prov.defaultModel] : (prov.models ?? []);
+  // Ordered dedupe union: Vertex seed, then `models`, then `retainModels`. `configured` is the
+  // single seed for the static path, the degraded fallback, drop diagnostics, and provider hints,
+  // so a retain-only id must enter here or it never exists to be retained (#1690).
+  const configuredIds = [...new Set([
+    ...(seedVertexDefault && prov.defaultModel ? [prov.defaultModel] : []),
+    ...(prov.models ?? []),
+    ...(prov.retainModels ?? []),
+  ])];
   const configured: CatalogModel[] = configuredIds.map(id => ({
     id,
     provider: name,
@@ -1694,9 +1722,14 @@ export function shouldExposeProviderModel(providerName: string, modelId: string)
   return true;
 }
 
-export function shouldRetainConfiguredProviderModel(providerName: string, modelId: string): boolean {
+export function shouldRetainConfiguredProviderModel(
+  providerName: string,
+  modelId: string,
+  prov?: OcxProviderConfig,
+): boolean {
   if (CALLABLE_CONFIGURED_COMPATIBILITY_MODELS[providerName]?.has(modelId)) return true;
   if (providerName === "opencode-free") return modelId === "big-pickle" || modelId.endsWith("-free");
+  if (modelInList(prov?.retainModels, modelId)) return true;
   return false;
 }
 
@@ -1742,7 +1775,7 @@ export function mergeConfiguredModelsIntoLiveCatalog(opts: {
     }
     if (
       seedVertexDefault === true
-      || shouldRetainConfiguredProviderModel(name, candidate.id)
+      || shouldRetainConfiguredProviderModel(name, candidate.id, prov)
       || (retainComboTargets && retainConfiguredModelIds?.has(candidate.id) === true)
     ) {
       out.push(candidate);

package/src/codex/catalog.ts

@@ -2,7 +2,7 @@
 // Public surface preserved exactly; importers keep using "src/codex/catalog".
 export { isMediaGenerationModelId, shouldExposeRoutedModel, readCodexCatalogPath, readCatalog, normalizeRoutedCatalogEntry, catalogModelSlug, filterSupportedNativeSlugs, catalogModelSupportsReasoningSummaries } from "./catalog/parsing";
 export type { CatalogModel, MultiAgentMode } from "./catalog/parsing";
-export { accountBoundNativeOpenAiSlugs, accountBoundNativeOpenAiSlugsBySelector, CODEX_NATIVE_ALIAS_CATALOG_KIND, NATIVE_DAYBREAK_BLUE_MODEL, NATIVE_GPT56_CONTEXT_WINDOW, NATIVE_GPT56_MAX_INPUT_TOKENS, NATIVE_GPT56_OPT_IN_CONTEXT_WINDOW, NATIVE_OPENAI_CAPABILITY_ALIAS_MODELS, NATIVE_OPENAI_MODELS, configuredNativeAliasSlugs, desktopAllowlistSuppressedNativeSlugs, isNativeAliasCatalogEntry, isNativeOpenAiCapabilityAliasModel, nativeContextLimits, nativeOpenAiCapabilitySourceSlug, nativeOpenAiContextWindow, nativeOpenAiMaxInputTokens, disabledNativeSlugs, visibleNativeSlugs, desktopVisibleNativeSlugs, nativeModelRows, applyNativeVisibility, observedAccountBoundNativeEntries, observedAccountBoundNativeOpenAiSlugs, upstreamNativeEntry, nativeOpenAiSlugs, listCatalogNativeSlugs, nativeInputModalities, nativeReasoningEfforts, nativeDefaultReasoningEffort, shouldIncludeAccountBoundNativeOpenAi, shouldIncludeNativeOpenAi, type NativeContextLimits, type NativeContextLimitsInput } from "./catalog/metadata";
+export { accountBoundNativeOpenAiSlugs, accountBoundNativeOpenAiSlugsBySelector, CODEX_NATIVE_ALIAS_CATALOG_KIND, NATIVE_DAYBREAK_BLUE_MODEL, NATIVE_GPT56_CONTEXT_WINDOW, NATIVE_GPT56_MAX_INPUT_TOKENS, NATIVE_GPT56_OPT_IN_CONTEXT_WINDOW, NATIVE_OPENAI_CAPABILITY_ALIAS_MODELS, NATIVE_OPENAI_MODELS, configuredNativeAliasSlugs, desktopAllowlistSuppressedNativeSlugs, isNativeAliasCatalogEntry, isNativeOpenAiCapabilityAliasModel, nativeContextLimits, nativeOpenAiCapabilitySourceSlug, nativeOpenAiContextWindow, nativeOpenAiMaxInputTokens, nativeOpenAiContextTier, disabledNativeSlugs, visibleNativeSlugs, desktopVisibleNativeSlugs, nativeModelRows, applyNativeVisibility, observedAccountBoundNativeEntries, observedAccountBoundNativeOpenAiSlugs, upstreamNativeEntry, nativeOpenAiSlugs, listCatalogNativeSlugs, nativeInputModalities, nativeReasoningEfforts, nativeDefaultReasoningEffort, shouldIncludeAccountBoundNativeOpenAi, shouldIncludeNativeOpenAi, type NativeContextLimits, type NativeContextLimitsInput } from "./catalog/metadata";
 export { isSpawnableCodexCandidate, codexExecInvocation, loadBundledCodexCatalog, materializeBundledCodexCatalog, loadCatalogTemplate } from "./catalog/bundled";
 export { nativeEffortClamp, shouldApplyNativeEffortClamp, catalogModelEfforts, codexSupportedReasoningEfforts, clampedDefaultEffort, clampEntryToCodexSupportedEfforts, clampCatalogModelsToCodexSupport } from "./catalog/effort";
 export { applyProviderConfigHints, isDatedVariantId, filterCatalogVisibleModels, gatherRoutedModels, clearGatherRoutedModelsInflight, augmentRoutedModelsWithRegistryOpenAiApiRows, augmentRoutedModelsWithMetadata, resolveComboCatalogMember, configuredComboTargetModelsByProvider } from "./catalog/provider-fetch";

package/src/codex/desired-state.ts

@@ -71,7 +71,14 @@ export function codexIntegrationEnabled(config: Pick<OcxConfig, "clientIntegrati
 }
 
 /** Whether a Codex sync is permitted for this admitted config snapshot. */
-export function shouldSyncCodexOnStart(config: Pick<OcxConfig, "clientIntegrations">): boolean {
+export function shouldSyncCodexOnStart(config: Pick<OcxConfig, "clientIntegrations" | "runtimeRole">): 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
+  // first clisu-oracle dogfood boot proved the failure mode — the hub marked
+  // /readyz failed because it tried to run the full local client sync).
+  // "Hub is also a client" stays possible by explicitly enabling integrations
+  // later; the ROLE alone never injects.
+  if (config.runtimeRole === "hub") return false;
   return codexIntegrationEnabled(config);
 }
 
@@ -182,7 +189,7 @@ export function setClaudeDesktopIntegrationEnabled(enabled: boolean): CodexDesir
  */
 export async function syncCodexOnStartIfEnabled(
   port: number,
-  config: Pick<OcxConfig, "clientIntegrations">,
+  config: Pick<OcxConfig, "clientIntegrations" | "runtimeRole">,
   sync: CodexStartupSync = defaultStartupSync,
   readinessGate?: ReadinessGate,
 ): Promise<{ ran: boolean; catalogWritten: boolean; cacheSynced: boolean }> {
@@ -225,6 +232,9 @@ async function defaultStartupSync(port: number): Promise<CodexStartupSyncOutcome
  * startup and its diagnostic is worth printing. This only answers whether to
  * attempt the sync at all.
  */
-export function shouldSyncGrokOnStart(config: Pick<OcxConfig, "clientIntegrations">): boolean {
+export function shouldSyncGrokOnStart(config: Pick<OcxConfig, "clientIntegrations" | "runtimeRole">): boolean {
+  // Same hub rule as shouldSyncCodexOnStart: the hub role never rewrites its
+  // host's client configs on startup.
+  if (config.runtimeRole === "hub") return false;
   return grokIntegrationEnabled(config);
 }