@bitkyc08/opencodex 2.57.0 → 2.59.0

package/src/codex/auth-context.ts

@@ -97,20 +97,60 @@ function requestOwnedMainPinHasQuotaHeadroom(config: OcxConfig): boolean {
 }
 
 /**
- * Every thread keys as ITSELF, never as its parent (#4546, wp8).
+ * Whether a request carrying its OWN main credential still serves on main because the operator
+ * manually pinned it (#3166), split from the surrounding resolution so request preview can ask
+ * the identical question (#4850).
  *
- * The old rule preferred `x-codex-parent-thread-id`, so every child of one parent bound under
- * the RAW parent id -- one shared entry, unrelated to the root's own `app:HMAC(session, thread)`
- * binding -- and a grandchild keyed on its own parent landed on a key nobody had ever bound.
- * A child therefore started cold while its parent was being served warm somewhere, and no
- * child could hold a binding of its own.
+ * Exported for exactly one reason: two copies of this fence is how #4850 happened. Final
+ * authentication honoured the ownership boundary while request preview, computing its fence from
+ * recovery and drain state alone, still handed pool eligibility the default liveness probe and
+ * opened the physical `auth.json` twice per spawn. A predicate one caller can forget is a
+ * predicate the other caller will eventually disagree with.
  *
- * Now a request with a `thread-id` keys as HMAC(session ?? parent, thread). A root is
- * unchanged, a child gets an independent key, and a request naming only a parent rides the
- * parent's lane under HMAC(parent, parent) -- the same one-to-one lane it always had, minus
- * the caller-supplied identifier that used to sit in Pool state. Which requests produce no
- * key at all is unchanged. First placement for a child is what consults the family, through
- * `recordCodexThreadLineage` below and the placement hook in ./routing.
+ * Read-free by construction, which is what makes it usable on the fenced side. Every input is
+ * config, policy, or in-memory runtime state: the pin fields, the paused list, the cached quota
+ * score, and `callerMatchesObservedMain`, which compares HMAC digests against the observed
+ * credential record in `main-account-cache.ts`. Nothing here opens a file.
+ *
+ * `candidate` is the pin before the hard-lock question, because the caller still owes the
+ * pending-binding check that only final authentication can fail closed on.
+ */
+export function requestOwnedMainPinState(
+  headers: Headers,
+  config: OcxConfig,
+  policy: CodexAuthPolicyConfig,
+  requestScopedMainCredential: boolean,
+  fixedAccountId: string | undefined,
+): { candidate: boolean; preserve: boolean } {
+  const candidate = requestScopedMainCredential
+    && fixedAccountId === undefined
+    && config.activeCodexAccountPinned === MAIN_CODEX_ACCOUNT_ID
+    && isEffectiveCodexAccountPinned(config)
+    && !policy.pausedCodexAccountIds?.includes(MAIN_CODEX_ACCOUNT_ID)
+    && requestOwnedMainPinHasQuotaHeadroom(config);
+  return {
+    candidate,
+    preserve: candidate && !(callerMatchesObservedMain(headers) && isMainAccountHardLocked(policy)),
+  };
+}
+
+/**
+ * One conversation tree keys as ONE cohort (#4780).
+ *
+ * Upstream keys its prompt cache on something the whole tree shares -- `prompt_cache_key` is the
+ * session id, or `{source}:{parent_thread_id}` for an internal session -- and one `AgentControl`
+ * whose `session_id` is the root thread's id is shared with every sub-agent. While the proxy
+ * keyed per thread, two requests could carry an identical `prompt_cache_key` and be served by
+ * different accounts, so the split member asserted a warm prefix that was deterministically cold
+ * on its account. Nothing failed; the prompt was replayed in full and the tokens burned.
+ *
+ * THIS IS NOT A REVERT OF #4546 wp8. wp8 fixed a different defect -- a child bound under the RAW
+ * parent id, an identity unrelated to the root's own binding, so siblings shared an entry the
+ * root was not on and a grandchild landed on a key nobody had bound. A cohort key has no such
+ * incoherence, because the root's own binding IS the cohort key. What wp8 additionally gave each
+ * thread, a binding of its own, is what this deliberately gives up.
+ *
+ * Which requests produce no key at all is unchanged, through both units.
  *
  * The derivation itself lives in ./lineage so a lineage record's conversation key and the key
  * the thread actually binds under can never drift apart.
@@ -816,19 +856,15 @@ export async function resolveCodexAuthContext(
     throw new CodexReserveUnavailableError();
   }
   const fixedAccountId = reserve ? MAIN_CODEX_ACCOUNT_ID : options.accountId;
-  const requestOwnedMainPinCandidate = requestScopedMainCredential
-    && fixedAccountId === undefined
-    && config.activeCodexAccountPinned === MAIN_CODEX_ACCOUNT_ID
-    && isEffectiveCodexAccountPinned(config)
-    && !policy.pausedCodexAccountIds?.includes(MAIN_CODEX_ACCOUNT_ID)
-    && requestOwnedMainPinHasQuotaHeadroom(config);
+  const {
+    candidate: requestOwnedMainPinCandidate,
+    preserve: preserveRequestOwnedMainPin,
+  } = requestOwnedMainPinState(headers, config, policy, requestScopedMainCredential, fixedAccountId);
   // During an owned startup, equality cannot be established until recovery and the
   // memory-only policy binding finish. This read-only fence never probes a foreign home.
   if (policy.codexMainAccountHardLock === true && requestOwnedMainPinCandidate && isMainAccountPolicyBindingPending()) {
     throw new CodexMainProfileDrainingError();
   }
-  const preserveRequestOwnedMainPin = requestOwnedMainPinCandidate
-    && !(callerMatchesObservedMain(headers) && isMainAccountHardLocked(policy));
   if (fixedAccountId !== undefined && options.excludeAccountId !== undefined) {
     throw new Error("Codex auth context cannot select and exclude an account simultaneously");
   }
@@ -1385,6 +1421,7 @@ export function materializeCodexUpstreamAuth(
     if (!stored?.accessToken || !isMainAccountTokenLive()) {
       throw new CodexMainSubstitutionUnavailableError();
     }
+    selected.delete("chatgpt-account-id");
     selected.set("authorization", `Bearer ${stored.accessToken}`);
     if (stored.chatgptAccountId) selected.set("chatgpt-account-id", stored.chatgptAccountId);
     observeSelectedMainCredential(stored, writer);
@@ -1462,6 +1499,7 @@ export async function materializeCodexUpstreamAuthAsync(
     ...(options.nativeMainRefreshDependencies ?? {}),
   });
   if (!stored?.accessToken) throw new CodexMainSubstitutionUnavailableError();
+  selected.delete("chatgpt-account-id");
   selected.set("authorization", `Bearer ${stored.accessToken}`);
   if (stored.chatgptAccountId) selected.set("chatgpt-account-id", stored.chatgptAccountId);
   observeSelectedMainCredential(stored, writer);

package/src/codex/catalog/build-entries.ts

@@ -26,7 +26,7 @@ import {
 } from "./metadata";
 import { resetBundledCatalogCacheForTests } from "./bundled";
 import { isMultiAgentV2Enabled } from "../features";
-import { ensureUltraReasoningLevel, isGpt56NativeSlug } from "./effort";
+import { clampedDefaultEffort, ensureUltraReasoningLevel, isGpt56NativeSlug } from "./effort";
 import { clearGatherRoutedModelsInflight, lastDropWarnSignature } from "./provider-fetch";
 import {
   accountSelectorShadowCollisionWarnings,
@@ -490,10 +490,14 @@ export interface ObservedCatalogMergeInput {
   readonly includeNativeOpenAi: boolean;
   readonly accountBoundEntries: readonly RawEntry[];
   readonly suppressedBareNativeSlugs?: ReadonlySet<string>;
+  /** Routed slugs that must not gain a missing synthetic max rung during retained-row repair. */
+  readonly suppressedSyntheticMaxSlugs?: ReadonlySet<string>;
   readonly policy: ObservedCatalogMergePolicy;
   readonly openaiContextCap?: NativeContextLimitsInput;
   /** Exact display-only labels for bare native OpenAI models. */
   readonly nativeDisplayNames?: Readonly<Record<string, string>>;
+  /** Pristine installed-catalog multi-agent pins; see MultiAgentModeOptions.nativeDefaults. */
+  readonly nativeMultiAgentDefaults?: ReadonlyMap<string, string | null>;
 }
 
 /**
@@ -526,9 +530,11 @@ export function mergeCatalogEntriesFromObservedState({
   includeNativeOpenAi,
   accountBoundEntries,
   suppressedBareNativeSlugs = new Set(),
+  suppressedSyntheticMaxSlugs = new Set(),
   policy,
   openaiContextCap,
   nativeDisplayNames,
+  nativeMultiAgentDefaults,
 }: ObservedCatalogMergeInput): RawEntry[] {
   // Raw catalog rows contain nested arrays/objects that normalization mutates. Detach every row at
   // the observed-core boundary so callers can safely retain evidence objects or repeat the merge.
@@ -860,16 +866,29 @@ export function mergeCatalogEntriesFromObservedState({
     });
     // Mock-max universality (260709): preserved routed entries from disk may predate
     // the max rung — ensure it here so subagent max spawns validate on every
-    // reasoning-capable entry. max only: 5.6 exact ladders (luna: no ultra) stay intact.
+    // reasoning-capable entry. A suppressed preserved row that already contains max keeps it;
+    // without persisted provenance, only a healthy provider rebuild can distinguish and remove
+    // an older synthetic rung from a real provider-declared rung. max only: 5.6 exact ladders
+    // (luna: no ultra) stay intact.
     if (!freshCustomEntries.has(m) && !exactCombo && !reserveProjection && !String(e.slug ?? "").startsWith("opencode-go/")) {
       const levels = Array.isArray(e.supported_reasoning_levels)
         ? e.supported_reasoning_levels as Array<{ effort?: string }>
         : [];
-      if (levels.length > 0 && !levels.some(level => level.effort === "max")) {
+      if (levels.length > 0
+        && !suppressedSyntheticMaxSlugs.has(String(e.slug ?? ""))
+        && !levels.some(level => level.effort === "max")) {
         levels.push(CODEX_REASONING_LEVELS.find(level => level.effort === "max")
           ?? { effort: "max", description: "Maximum reasoning depth for the hardest problems" });
         e.supported_reasoning_levels = levels;
       }
+      if (suppressedSyntheticMaxSlugs.has(String(e.slug ?? ""))
+        && typeof e.default_reasoning_level === "string"
+        && !levels.some(level => level.effort === e.default_reasoning_level)) {
+        e.default_reasoning_level = clampedDefaultEffort(
+          e.default_reasoning_level,
+          levels.flatMap(level => typeof level.effort === "string" ? [level.effort] : []),
+        );
+      }
     }
     if (wsEnabled) e.supports_websockets = true;
     else {
@@ -886,7 +905,7 @@ export function mergeCatalogEntriesFromObservedState({
     applyNativeVisibility(mergedEntries, disabledModels, alignedAccountBoundEntries.length > 0, observedNativeSlugs),
     multiAgentMode,
     multiAgentV2Enabled,
-    { keepNativeChatGptOnV1, preserveDefaultMultiAgentVersion: isReserveCatalogProjection },
+    { keepNativeChatGptOnV1, preserveDefaultMultiAgentVersion: isReserveCatalogProjection, nativeDefaults: nativeMultiAgentDefaults },
   );
   applyFullModelPickerOrder(versionedEntries, modelPickerOrder);
   for (const entry of versionedEntries) {
@@ -937,6 +956,7 @@ export function mergeCatalogEntriesForSync(
   ),
   openaiContextCap?: NativeContextLimitsInput,
   keepNativeChatGptOnV1 = false,
+  nativeMultiAgentDefaults?: ReadonlyMap<string, string | null>,
 ): RawEntry[] {
   // Retained for source compatibility with the original helper contract. Raw provider ids must
   // not suppress same-named native rows; actual admitted combo entries own that decision now.
@@ -973,6 +993,7 @@ export function mergeCatalogEntriesForSync(
     accountBoundEntries,
     suppressedBareNativeSlugs,
     openaiContextCap,
+    nativeMultiAgentDefaults,
     policy: {
       ...CANONICAL_NATIVE_CATALOG_CONTENT_POLICY,
       warningPolicy: "emit",

package/src/codex/catalog/derive-entry.ts

@@ -160,6 +160,7 @@ export function deriveEntry(
         preserveExactReasoning
           || codexForwardNativeCapabilityAlias !== null
           || preservePinnedNativeCustomReasoning(model),
+        model?.suppressSyntheticMax === true,
       );
       // This exact provider/model pair is the ChatGPT/Codex forward surface. Keep the pinned
       // native tool/search/responses-lite contract while preserving the routed slug and wire id.
@@ -208,7 +209,13 @@ export function deriveEntry(
   };
   if (isRouted) {
     applyRoutedCodexToolMode(entry, model?.codexToolMode);
-    applyReasoningLevels(entry, model?.reasoningEfforts, model?.defaultReasoningEffort, preserveExactReasoning || preservePinnedNativeCustomReasoning(model));
+    applyReasoningLevels(
+      entry,
+      model?.reasoningEfforts,
+      model?.defaultReasoningEffort,
+      preserveExactReasoning || preservePinnedNativeCustomReasoning(model),
+      model?.suppressSyntheticMax === true,
+    );
   }
   else {
     applyReasoningLevels(entry, isGpt56NativeSlug(slug) ? undefined : ["low", "medium", "high", "xhigh"]);

package/src/codex/catalog/effort.ts

@@ -226,10 +226,12 @@ export function applyReasoningLevels(
   effortsOverride?: string[],
   defaultOverride?: string,
   preserveExact = false,
+  suppressSyntheticMax = false,
 ): void {
   let efforts = sanitizeCodexReasoningEfforts(effortsOverride) ?? ROUTED_REASONING_LEVELS.map(l => l.effort);
-  // Mock top tiers (user decision 260709): every reasoning-capable model advertises `max`
-  // even when the provider ladder stops lower — subagent spawns pass `max` DIRECTLY
+  // Mock top tiers (user decision 260709): reasoning-capable routed models advertise `max`
+  // even when the provider ladder stops lower, unless the model opts out of that synthesis.
+  // Subagent spawns pass `max` DIRECTLY
   // (no ultra->max client conversion) and codex-rs validates it by catalog membership,
   // so a missing max rung hard-fails spawn_agent effort overrides. The wire stays honest:
   // routed adapters clamp via clampToSupportedCodexEffort and natives via
@@ -237,7 +239,7 @@ export function applyReasoningLevels(
   // reasoning-capable, so it must not grow synthetic top rungs.
   if (!preserveExact && efforts.length > 0 && efforts.some(effort => effort !== "none" && effort !== "minimal")) {
     const additions: string[] = [];
-    if (!efforts.includes("max")) additions.push("max");
+    if (!suppressSyntheticMax && !efforts.includes("max")) additions.push("max");
     if (!efforts.includes("ultra")) additions.push("ultra");
     if (additions.length > 0) efforts = sanitizeCodexReasoningEfforts([...efforts, ...additions]) ?? efforts;
   }
@@ -258,9 +260,11 @@ export function applyReasoningLevels(
   }
   entry.default_reasoning_level = defaultOverride && efforts.includes(defaultOverride)
     ? defaultOverride
-    : efforts.includes("medium") ? "medium" : efforts.includes("high") ? "high"
-    // Sentinels never become the implicit default when real rungs are declared.
-    : efforts.find(effort => effort !== "none" && effort !== "minimal") ?? efforts[0];
+    : suppressSyntheticMax && defaultOverride === "max"
+      ? clampedDefaultEffort(defaultOverride, efforts)
+      : efforts.includes("medium") ? "medium" : efforts.includes("high") ? "high"
+        // Sentinels never become the implicit default when real rungs are declared.
+        : efforts.find(effort => effort !== "none" && effort !== "minimal") ?? efforts[0];
 }
 
 /**

package/src/codex/catalog/gather-capture.ts

@@ -499,6 +499,7 @@ function providerCatalogFingerprint(name: string, prov: OcxProviderConfig): Reco
     inMod: prov.modelInputModalities ?? null,
     capabilities: prov.modelCapabilities ?? null,
     re: prov.modelReasoningEfforts ?? null,
+    suppressMax: prov.modelSuppressSyntheticMax ?? null,
     defRe: prov.modelDefaultReasoningEfforts ?? null,
     rsSum: prov.modelSupportsReasoningSummaries ?? null,
     verbosity: prov.modelSupportsVerbosity ?? null,

package/src/codex/catalog/model-hints.ts

@@ -296,6 +296,7 @@ export function applyProviderConfigHints(
     inputModalities = base.includes("image") ? [...base] : [...base, "image"];
   }
   const reasoningEfforts = configuredReasoningEfforts(prov, model.id);
+  const suppressSyntheticMax = modelRecordValue(prov.modelSuppressSyntheticMax, model.id) === true;
   const defaultReasoningEffort = modelRecordValue(prov.modelDefaultReasoningEfforts, model.id) ?? model.defaultReasoningEffort;
   const supportsReasoningSummaries = configuredReasoningSummarySupport(prov, model.id);
   const supportsVerbosity = configuredVerbositySupport(name, prov, model.id);
@@ -305,6 +306,7 @@ export function applyProviderConfigHints(
     supportsServiceTier: _staleServiceTier,
     fastTierDescription: _staleFastTierDescription,
     providerAlias: _staleProviderAlias,
+    suppressSyntheticMax: _staleSuppressSyntheticMax,
     ...modelWithoutServiceTier
   } = model;
   // 已发现窗口只允许被配置值压低；缺窗口时，已开的 Context cap 就是实际窗口。
@@ -321,6 +323,7 @@ export function applyProviderConfigHints(
     ...(hintedWindow !== undefined ? { contextWindow: hintedWindow } : {}),
     ...(inputModalities ? { inputModalities } : {}),
     ...(reasoningEfforts !== undefined ? { reasoningEfforts } : {}),
+    ...(suppressSyntheticMax ? { suppressSyntheticMax: true } : {}),
     ...(configuredMaxInput !== undefined
       ? {
         maxInputTokens: typeof model.maxInputTokens === "number" && model.maxInputTokens > 0
@@ -394,6 +397,31 @@ export function applyConfigHintsToCachedModels(
 ): CatalogModel[] {
   return models.map(model => applyProviderConfigHints(name, prov, model, contextCap, metadataModelIdCaseFold, effectiveAlias));
 }
+
+/** Catalog slugs whose configured model must not gain a missing synthetic max rung. */
+export function suppressedSyntheticMaxCatalogSlugs(
+  config: Pick<OcxConfig, "providers">,
+  models: readonly CatalogModel[],
+  observedEntries: readonly { slug?: unknown }[] = [],
+): ReadonlySet<string> {
+  const slugs = new Set(models
+    .filter(model => model.suppressSyntheticMax === true)
+    .map(catalogModelSlug));
+  for (const [provider, providerConfig] of Object.entries(config.providers)) {
+    const configured = providerConfig.modelSuppressSyntheticMax ?? {};
+    const encoded = Object.fromEntries(Object.entries(configured)
+      .map(([modelId, suppress]) => [routedSlug(provider, modelId).slice(provider.length + 1), suppress]));
+    for (const [modelId, suppress] of Object.entries(configured)) {
+      if (suppress === true) slugs.add(routedSlug(provider, modelId));
+    }
+    for (const entry of observedEntries) {
+      const slug = typeof entry.slug === "string" ? entry.slug : "";
+      if (!slug.startsWith(`${provider}/`)) continue;
+      if (modelRecordValue(encoded, slug.slice(provider.length + 1)) === true) slugs.add(slug);
+    }
+  }
+  return slugs;
+}
 export const QUIET_AUTHORITATIVE_CATALOG_PROVIDERS = new Set(["kimi", "xai"]);
 
 export const CALLABLE_CONFIGURED_COMPATIBILITY_MODELS: Readonly<Record<string, ReadonlySet<string>>> = {
@@ -582,10 +610,11 @@ function discoveredPricingRate(value: unknown): number | undefined {
 /**
  * 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.
+ * Fail closed. Any positive numeric component proves the model is paid. Calling it free requires
+ * a complete prompt/completion pair and every published pricing component to be a non-negative
+ * numeric zero; an unsupported component is "unknown" because it may describe another charge.
+ * 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
@@ -598,10 +627,13 @@ function discoveredPricingRate(value: unknown): number | undefined {
 export function discoveredPricingStatus(item: ProviderModelsApiItem): "free" | "paid" | "unknown" {
   const pricing = plainRecord(item.pricing) ?? plainRecord(plainRecord(item.metadata)?.pricing);
   if (!pricing) return "unknown";
+  const rates = Object.values(pricing).map(discoveredPricingRate);
+  if (rates.some(rate => rate !== undefined && rate > 0)) return "paid";
+  if (rates.some(rate => rate === undefined)) 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";
+  return "free";
 }
 
 export function catalogHintsFromModelsApiItem(providerName: string, item: ProviderModelsApiItem): Partial<CatalogModel> {

package/src/codex/catalog/parsing.ts

@@ -112,6 +112,8 @@ export interface CatalogModel {
   displayName?: string;
   owned_by?: string;
   reasoningEfforts?: string[];
+  /** Suppress only catalog synthesis of a missing max rung; provider-declared max survives. */
+  suppressSyntheticMax?: boolean;
   defaultReasoningEffort?: string;
   contextWindow?: number;
   maxInputTokens?: number;
@@ -255,12 +257,19 @@ export function readCodexCatalogPath(): string {
   return activeDefaultCatalogPath();
 }
 
-/** Resolve the configured catalog without consulting ambient CODEX_HOME again. */
-export function readCodexCatalogPathForHome(codexHome: string): string {
+/**
+ * Resolve the configured catalog without consulting ambient CODEX_HOME again.
+ *
+ * `configText` is for a caller that has already read that same `config.toml` under
+ * its own constraints - the prompt-text probe reads it bounded, on the request
+ * thread - so resolving the catalog does not cost a second, unbounded read of the
+ * file the caller is holding. Omitting it keeps the original behaviour.
+ */
+export function readCodexCatalogPathForHome(codexHome: string, configText?: string): string {
   try {
     const configPath = join(codexHome, "config.toml");
-    if (existsSync(configPath)) {
-      const toml = readFileSync(configPath, "utf-8");
+    if (configText !== undefined || existsSync(configPath)) {
+      const toml = configText ?? readFileSync(configPath, "utf-8");
       const path = readRootTomlString(toml, "model_catalog_json");
       if (path) return resolve(codexHome, path);
     }
@@ -284,6 +293,30 @@ export function readConfiguredAutoReviewModel(): string | null {
   return null;
 }
 
+/**
+ * Read the root `model` pin from Codex's config.toml (issue #4646).
+ *
+ * Codex starts every new session on this id, and nothing in opencodex checks that the id is one
+ * the proxy actually exposes: the pin lives in Codex's config, while exposure is decided here by
+ * `disabledModels`, provider `selectedModels`, and account entitlements. When the two disagree
+ * every turn fails and no surface says why, which is what the `ocx doctor` section added for
+ * #4646 reports.
+ *
+ * Read-only, and deliberately the same shape and the same swallow-and-return-null error policy as
+ * `readConfiguredAutoReviewModel` above: a diagnostic must degrade to "unknown" on an unreadable
+ * or absent config rather than throw out of the surface that called it.
+ */
+export function readConfiguredDefaultModel(): string | null {
+  try {
+    const configPath = activeCodexConfigPath();
+    if (existsSync(configPath)) {
+      const toml = readFileSync(configPath, "utf-8");
+      return readRootTomlString(toml, "model");
+    }
+  } catch { /* ignore */ }
+  return null;
+}
+
 export function parseCatalogJson(raw: string): RawCatalog | null {
   try {
     const cat = JSON.parse(raw);
@@ -627,6 +660,14 @@ export interface MultiAgentModeOptions {
    * so they can still spawn Grok/Claude — ChatGPT encrypts v2 NEW_TASK bodies.
    */
   keepNativeChatGptOnV1?: boolean;
+  /**
+   * Pristine installed-catalog pins keyed by bare native slug. When provided, the
+   * backup — not the bundled snapshot — is authoritative for the rows it contains,
+   * and a preserved live/native row outside it keeps the pin it already carries:
+   * an absent baseline entry cannot distinguish a stale forced stamp from a
+   * legitimate user- or provider-preserved pin, so the non-destructive read wins.
+   */
+  nativeDefaults?: ReadonlyMap<string, string | null>;
 }
 
 /** Catalog rows that run on the ChatGPT backend (encrypt v2 child tasks). */
@@ -707,13 +748,34 @@ export function applyMultiAgentMode(
         && hasNativeOpenAiCapabilityMetadata(routedNativeSlug)
         ? routedNativeSlug
         : undefined;
+      const accountBoundNativeSlug = trustedAccountBoundNativeCatalogSlug(entry);
+      const nativeLookupSlug = accountBoundNativeSlug ?? slug;
+      // The baseline is built from bare native slugs only, so "absent from the
+      // baseline" is not evidence about a routed row — it is guaranteed. Only a
+      // native row can carry a pin the baseline legitimately failed to mention;
+      // a routed row keeps the documented default-mode normalization.
+      const isNativeCatalogEntry = accountBoundNativeSlug !== undefined || !slug.includes("/");
+      const hasNativeDefault = !nativeAlias
+        && codexForwardCapabilityAlias === undefined
+        && options.nativeDefaults?.has(nativeLookupSlug) === true;
       const upstreamPin = nativeAlias
         ? nativeMultiAgentVersion(slug)
         : codexForwardCapabilityAlias
           ? nativeMultiAgentVersion(codexForwardCapabilityAlias)
-          : UPSTREAM_NATIVE_ENTRIES.get(trustedAccountBoundNativeCatalogSlug(entry) ?? slug)?.multi_agent_version;
+          : hasNativeDefault
+            ? options.nativeDefaults?.get(nativeLookupSlug)
+            : options.nativeDefaults === undefined
+              ? UPSTREAM_NATIVE_ENTRIES.get(nativeLookupSlug)?.multi_agent_version
+              : undefined;
       if (typeof upstreamPin === "string") {
         entry.multi_agent_version = upstreamPin;
+      } else if (options.nativeDefaults !== undefined
+        && !nativeAlias
+        && codexForwardCapabilityAlias === undefined
+        && isNativeCatalogEntry
+        && !hasNativeDefault
+        && typeof entry.multi_agent_version === "string") {
+        continue;
       } else if (v2FeatureEnabled) {
         entry.multi_agent_version = "v2";
       } else {
@@ -888,3 +950,19 @@ export function readNativeBaseline(catalogPath: string): Map<string, number> {
   }
   return out;
 }
+
+/**
+ * Extract the pristine baseline's per-slug multi-agent pins. A bare native row that
+ * carried no pin maps to null so "baseline says unpinned" stays distinguishable
+ * from "baseline never contained this row".
+ */
+export function nativeMultiAgentDefaults(
+  models: readonly Readonly<Record<string, unknown>>[] | null | undefined,
+): Map<string, string | null> {
+  const out = new Map<string, string | null>();
+  for (const entry of models ?? []) {
+    if (typeof entry.slug !== "string" || entry.slug.includes("/")) continue;
+    out.set(entry.slug, typeof entry.multi_agent_version === "string" ? entry.multi_agent_version : null);
+  }
+  return out;
+}

package/src/codex/catalog/reserve-warn.ts

@@ -0,0 +1,96 @@
+import type { OcxConfig } from "../../types";
+import { isEffectiveCodexDesktopAuthless } from "../loopback-target";
+import { NATIVE_RESERVE_MODEL } from "./native-models";
+
+/**
+ * #4811: why an opted-in install still gets no Luna Reserve row.
+ *
+ * The Reserve projection is account-qualified — its slug is `<selector>/gpt-reserve` — so it
+ * cannot be written without a selector that targets the main Codex account. On a fresh authless
+ * install `codexAccountNamespaces` is empty, the account picker is therefore off, no selectors
+ * exist, and `createReserveCatalogProjection` returns `undefined`. Nothing downstream can
+ * explain that: an omitted row has no place to carry a reason, which is exactly the shape of
+ * #4212 for account-gated natives, and the same answer applies — say it once, here, while the
+ * inputs that produced the omission are still in scope.
+ *
+ * Deliberately scoped to an operator who asked for the feature. A default install has
+ * `codexDesktopAuthless` unset, wants no Reserve row, and must not be told about one. An install
+ * that stores the flag on a bind where it cannot take effect is a different silence, already
+ * reported as `inertReason` by `describeCodexDesktopSwitches`, and is not repeated here.
+ */
+export type ReserveCatalogSuppressionReason =
+  | "no-canonical-openai-provider"
+  | "account-picker-disabled"
+  | "no-account-namespaces"
+  | "no-main-account-selector";
+
+type ReserveSuppressionConfig = Pick<
+  OcxConfig,
+  | "runtimeRole"
+  | "hostname"
+  | "unauthenticatedLoopbackListener"
+  | "codexDesktopAuthless"
+  | "codexAccountNamespaces"
+  | "codexAccountPickerEnabled"
+>;
+
+export interface ReserveSuppressionInput {
+  /** Already resolved by the caller; passed in so this module stays off the metadata graph. */
+  includeAccountBoundNativeOpenAi: boolean;
+  /** Selectors that resolved to the main Codex account. A non-empty list means no suppression. */
+  mainSelectors: readonly string[];
+}
+
+export function reserveCatalogSuppressionReason(
+  config: ReserveSuppressionConfig,
+  input: ReserveSuppressionInput,
+): ReserveCatalogSuppressionReason | undefined {
+  if (!isEffectiveCodexDesktopAuthless(config) || input.mainSelectors.length > 0) return undefined;
+  if (!input.includeAccountBoundNativeOpenAi) return "no-canonical-openai-provider";
+  // Checked before the empty-map case: when an operator has explicitly turned the picker off,
+  // naming the empty map would send them to hand-author selectors that the opt-in generates.
+  if (config.codexAccountPickerEnabled === false) return "account-picker-disabled";
+  if (Object.keys(config.codexAccountNamespaces ?? {}).length === 0) return "no-account-namespaces";
+  return "no-main-account-selector";
+}
+
+const SUPPRESSION_TEXT: Readonly<Record<ReserveCatalogSuppressionReason, {
+  cause: string;
+  action: string;
+}>> = {
+  "no-canonical-openai-provider": {
+    cause: "no enabled canonical OpenAI provider can serve account-qualified native routes",
+    action: "Enable the built-in \"openai\" provider with forwarded ChatGPT auth.",
+  },
+  "account-picker-disabled": {
+    cause: "the Codex account picker is turned off (codexAccountPickerEnabled is false)",
+    action: "Set codexAccountPickerEnabled to true to generate the default account selectors.",
+  },
+  "no-account-namespaces": {
+    cause: "no Codex account selectors are configured (codexAccountNamespaces is empty)",
+    action: "Enable the Codex account picker once to generate the default account selectors.",
+  },
+  "no-main-account-selector": {
+    cause: "no configured selector in codexAccountNamespaces targets the main Codex account",
+    action: "Map one selector to the main Codex account.",
+  },
+};
+
+const warnedReserveSuppression = new Set<string>();
+
+/** Test seam: the warn-once memory is process-global, so a case needs to be able to clear it. */
+export function resetReserveSuppressionWarningsForTests(): void {
+  warnedReserveSuppression.clear();
+}
+
+export function warnReserveSuppressedOnce(reason: ReserveCatalogSuppressionReason): void {
+  if (warnedReserveSuppression.has(reason)) return;
+  warnedReserveSuppression.add(reason);
+  const text = SUPPRESSION_TEXT[reason];
+  console.warn(
+    `[opencodex] catalog sync: authless Codex Desktop routing is on, but the Luna Reserve row `
+      + `(<selector>/${NATIVE_RESERVE_MODEL}) is not being written because ${text.cause}. `
+      + `The Reserve projection is account-qualified and needs a selector for the main Codex `
+      + `account. ${text.action}`,
+  );
+}