@bitkyc08/opencodex 2.22.0 → 2.23.0

package/src/codex/catalog/parsing.ts

@@ -266,6 +266,21 @@ export function isNativeOpenAiEntry(entry: RawEntry): boolean {
   return typeof entry.slug === "string" && !entry.slug.includes("/");
 }
 
+/**
+ * Auto-compaction threshold for a native row.
+ *
+ * The usual rule is 90% of the window, but a model whose measured input ceiling sits below
+ * that (GPT-5.6: 922,000 against a 1,050,000 window, where 90% would be 945,000) has to
+ * clamp to the ceiling instead — otherwise the client keeps filling until upstream answers
+ * `context_length_exceeded` and compaction never gets a chance to run.
+ */
+function nativeAutoCompactLimit(contextWindow: number, maxInputTokens: number | undefined, contextCap?: number): number {
+  const ninety = Math.floor(contextWindow * 0.9);
+  if (typeof maxInputTokens !== "number" || maxInputTokens <= 0) return ninety;
+  const cappedMaxInput = applyProviderContextCap(maxInputTokens, contextCap) ?? maxInputTokens;
+  return Math.min(ninety, cappedMaxInput, contextWindow);
+}
+
 export function applyNativeOpenAiContextOverride(entry: RawEntry, contextCap?: number): void {
   const nativeSlug = trustedAccountBoundNativeCatalogSlug(entry)
     ?? (isNativeOpenAiEntry(entry) ? entry.slug as string : undefined);
@@ -275,7 +290,7 @@ export function applyNativeOpenAiContextOverride(entry: RawEntry, contextCap?: n
     if (typeof override.contextWindow === "number") {
       const contextWindow = applyProviderContextCap(override.contextWindow, contextCap) ?? override.contextWindow;
       entry.context_window = contextWindow;
-      entry.auto_compact_token_limit = Math.floor(contextWindow * 0.9);
+      entry.auto_compact_token_limit = nativeAutoCompactLimit(contextWindow, override.maxInputTokens, contextCap);
     }
     if (typeof override.maxContextWindow === "number") {
       entry.max_context_window = applyProviderContextCap(override.maxContextWindow, contextCap) ?? override.maxContextWindow;
@@ -288,7 +303,7 @@ export function applyNativeOpenAiContextOverride(entry: RawEntry, contextCap?: n
   const cappedContext = applyProviderContextCap(currentContext, contextCap);
   if (cappedContext !== currentContext && typeof cappedContext === "number") {
     entry.context_window = cappedContext;
-    entry.auto_compact_token_limit = Math.floor(cappedContext * 0.9);
+    entry.auto_compact_token_limit = nativeAutoCompactLimit(cappedContext, override?.maxInputTokens, contextCap);
   }
   const currentMax = typeof entry.max_context_window === "number" ? entry.max_context_window : undefined;
   const cappedMax = applyProviderContextCap(currentMax, contextCap);
@@ -462,16 +477,15 @@ export function normalizeRoutedCatalogEntry(entry: RawEntry, parallelToolCalls =
   // tool_search round-trip (upstream codex-rs code_mode suite; live canary 2026-08-13: routed
   // kimi/k3 called tools.mcp__node_repl__js → isError:false). Stamping false here instead forces
   // every MCP declaration into exec.description — a measured 2.7x turn-1 payload regression
-  // (96,699 → 258,929 chars; devlog/_plan/260813_tool_catalog_deferral/010). So non-Cursor routed
-  // rows advertise deferred discovery; the #1522 reachability concern is covered by the code-mode
-  // path, not by paying the full-catalog tax. Cursor stays false: its runTurn transport bypasses
-  // the web-search sidecar and has no proven deferred path.
+  // (96,699 → 258,929 chars; devlog/_plan/260813_tool_catalog_deferral/010). So every routed
+  // code-mode row advertises deferred discovery. Cursor still omits hosted web-search metadata below,
+  // but disabling this separate exposure bit can inflate `exec` past Cursor's 120 KB wire cap (#1830).
   if (isCursorEntry) {
     delete entry.web_search_tool_type;
   } else {
     entry.web_search_tool_type = "text_and_image";
   }
-  entry.supports_search_tool = !isCursorEntry;
+  entry.supports_search_tool = true;
   // Cursor's transport already serializes overlapping tool calls into atomic Responses tool events.
   // Advertising parallel calls lets Codex send the same native capability bit it sends for OpenAI.
   // Opt-in providers (OcxProviderConfig.parallelToolCalls, e.g. xAI) advertise it too: the

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

@@ -74,7 +74,7 @@ import { createAdmissionGate, ResourceAdmissionError, type AdmissionMetrics } fr
 
 import { CODEX_CUSTOM_MODEL_CATALOG_KIND, JAWCODE_CATALOG_AUGMENT_PROVIDERS, catalogModelSlug, shouldExposeRoutedModel } from "./parsing";
 import type { CatalogModel } from "./parsing";
-import { disabledNativeSlugs, hasComboTargets, isNativeOpenAiCapabilityAliasModel, nativeDefaultReasoningEffort, nativeInputModalities, nativeOpenAiContextWindow, nativeOpenAiSlugs, nativeParallelToolCalls, nativeReasoningEfforts } from "./metadata";
+import { disabledNativeSlugs, hasComboTargets, isNativeOpenAiCapabilityAliasModel, nativeDefaultReasoningEffort, nativeInputModalities, nativeOpenAiContextWindow, nativeOpenAiMaxInputTokens, nativeOpenAiSlugs, nativeParallelToolCalls, nativeReasoningEfforts } from "./metadata";
 import { deriveComboCatalogModel, normalizedOpenAiApiSignature, openAiApiCollisionWarnings, replaceLastComboCatalogOmissions, warnUncataloguedComboOnce } from "./aggregation";
 import type { ComboCatalogOmission } from "./aggregation";
 import type { CatalogGatherProviderAuthEvidence } from "./filesystem-evidence";
@@ -703,6 +703,8 @@ const COMBO_MEMBER_CONTEXT_FALLBACK = 128_000;
 
 interface ComboCatalogMemberFallback {
   readonly contextWindow?: number;
+  /** Input ceiling when it is lower than the window (native GPT-5.6: 922k under 1.05M). */
+  readonly maxInputTokens?: number;
   readonly inputModalities?: readonly string[];
   readonly reasoningEfforts?: readonly string[];
 }
@@ -744,7 +746,11 @@ export function resolveComboCatalogMember(
     if (!addMaxInput && !addModalities && !addReasoning) return member;
     return {
       ...member,
-      ...(addMaxInput ? { maxInputTokens: contextWindow } : {}),
+      // Never claim a larger input budget than the window, and prefer the model's own
+      // measured ceiling when the fallback carries one.
+      ...(addMaxInput
+        ? { maxInputTokens: Math.min(fallback.maxInputTokens ?? contextWindow!, contextWindow!) }
+        : {}),
       ...(addModalities ? { inputModalities: [...fallback.inputModalities!] } : {}),
       ...(addReasoning ? { reasoningEfforts: [...fallback.reasoningEfforts!] } : {}),
     };
@@ -765,7 +771,7 @@ export function resolveComboCatalogMember(
     }
     const maxInput = typeof existing.maxInputTokens === "number" && existing.maxInputTokens > 0
       ? Math.min(existing.maxInputTokens, capped)
-      : capped;
+      : Math.min(fallback?.maxInputTokens ?? capped, capped);
     return withFallbackMetadata({
       ...existing,
       contextWindow: capped,
@@ -790,6 +796,10 @@ export function resolveComboCatalogMember(
     : (typeof base.maxInputTokens === "number" && base.maxInputTokens > 0
       ? base.maxInputTokens
       : undefined);
+  // Kept OUT of knownMaxInput on purpose: that value doubles as a context-window fallback
+  // below, and a native alias whose input ceiling (922k) is lower than its window (1.05M)
+  // would otherwise shrink the advertised window to the input limit.
+  const fallbackMaxInput = existing || prov ? fallback?.maxInputTokens : undefined;
   // Real discovery/config values win. A native alias is the next fallback tier.
   // The generic 128k/text synthesis from #1305 remains the final fallback.
   const fallbackContext = existing || prov ? fallback?.contextWindow : undefined;
@@ -814,8 +824,11 @@ export function resolveComboCatalogMember(
     ?? (prov ? configuredReasoningEfforts(prov, target.model) : undefined)
     ?? base.reasoningEfforts
     ?? (fallback?.reasoningEfforts ? [...fallback.reasoningEfforts] : undefined);
-  const maxInputTokens = knownMaxInput !== undefined
-    ? Math.min(knownMaxInput, contextWindow)
+  // The model's own measured input ceiling still applies when discovery gave us nothing:
+  // GPT-5.6 advertises a 1.05M window but refuses input past 922k.
+  const effectiveMaxInput = knownMaxInput ?? fallbackMaxInput;
+  const maxInputTokens = effectiveMaxInput !== undefined
+    ? Math.min(effectiveMaxInput, contextWindow)
     : contextWindow;
 
   return {
@@ -1712,7 +1725,9 @@ async function gatherRoutedModelsUncached(
         id: slug,
         owned_by: "openai",
         contextWindow,
-        maxInputTokens: contextWindow,
+        // Input limit, not the total window: GPT-5.6 advertises 1,050,000 but refuses past
+        // 922,000 (measured). Falls back to the window for slugs with no separate ceiling.
+        maxInputTokens: Math.min(nativeOpenAiMaxInputTokens(slug, openaiContextCap) ?? contextWindow, contextWindow),
         inputModalities: nativeInputModalities(slug),
         reasoningEfforts: nativeReasoningEfforts(slug),
         ...(nativeParallelToolCalls(slug) ? { parallelToolCalls: true } : {}),
@@ -1730,11 +1745,15 @@ async function gatherRoutedModelsUncached(
     const combo = getCombo(config, id);
     if (!combo) continue;
     const nativeContextWindow = combo.nativeAlias && combo.alias
-      ? nativeOpenAiContextWindow(combo.alias)
+      ? nativeOpenAiContextWindow(combo.alias, providerContextCap(config, OPENAI_CODEX_PROVIDER_ID))
+      : undefined;
+    const nativeAliasMaxInput = combo.nativeAlias && combo.alias
+      ? nativeOpenAiMaxInputTokens(combo.alias, providerContextCap(config, OPENAI_CODEX_PROVIDER_ID))
       : undefined;
     const nativeAliasFallback = combo.nativeAlias && combo.alias && nativeContextWindow !== undefined
       ? {
         contextWindow: nativeContextWindow,
+        ...(nativeAliasMaxInput !== undefined ? { maxInputTokens: Math.min(nativeAliasMaxInput, nativeContextWindow) } : {}),
         inputModalities: nativeInputModalities(combo.alias),
         reasoningEfforts: nativeReasoningEfforts(combo.alias),
       }
@@ -1788,6 +1807,14 @@ async function gatherRoutedModelsUncached(
         ? Math.min(cm.contextWindow, nativeAliasContextWindow)
         : cm.contextWindow
       : nativeAliasContextWindow;
+    // Input ceiling for a native capability alias, clamped to whatever window we settled on
+    // above. A custom row that lowered the window must not keep the full native input budget.
+    const nativeAliasMaxInputTokens = codexForwardNativeCapabilityAlias
+      ? nativeOpenAiMaxInputTokens(cm.modelId, providerContextCap(config, OPENAI_CODEX_PROVIDER_ID))
+      : undefined;
+    const customMaxInputTokens = nativeAliasMaxInputTokens !== undefined && customContextWindow !== undefined
+      ? Math.min(nativeAliasMaxInputTokens, customContextWindow)
+      : nativeAliasMaxInputTokens;
     const nativeAliasDefaultEffort = codexForwardNativeCapabilityAlias
       ? nativeDefaultReasoningEffort(cm.modelId)
       : undefined;
@@ -1804,6 +1831,7 @@ async function gatherRoutedModelsUncached(
         ? { displayName: cm.displayName }
         : codexForwardNativeCapabilityAlias ? { displayName: "Daybreak Blue" } : {}),
       ...(customContextWindow !== undefined ? { contextWindow: customContextWindow } : {}),
+      ...(customMaxInputTokens !== undefined ? { maxInputTokens: customMaxInputTokens } : {}),
       ...(cm.inputModalities
         ? { inputModalities: cm.inputModalities }
         : codexForwardNativeCapabilityAlias ? { inputModalities: nativeInputModalities(cm.modelId) } : {}),

package/src/codex/catalog/sync.ts

@@ -90,21 +90,36 @@ export type SubagentRosterExclusionReason =
 /**
  * Whether a catalog entry may be offered as a V2 subagent model.
  *
- * Upstream (codex-rs 92938d880) requires `multi_agent_version === "v2"` exactly,
- * because upstream assumes a single backend serves every model. opencodex routes
- * many providers, so that equality would reject the cross-provider spawns this
- * proxy exists to enable.
+ * Upstream changed this rule in codex-rs `6d4d9442c` ("Support leaf models in
+ * multi-agent v2"). `model_supports_multi_agent_backend`
+ * (core/src/tools/handlers/multi_agents_common.rs:36-42) now admits EVERY model
+ * except one explicitly marked `disabled`; the older `== Some(V2)` equality that
+ * `92938d880` introduced is gone.
  *
- * Decision (option B, devlog 260730_codex_rs_upstream_v2_live_handoff/060): any
- * model opencodex actually routes is eligible. An entry pinned to a DIFFERENT
- * multi-agent backend (`v1`) stays excluded, because that pin is a real capability
- * statement rather than an absence of information. An unpinned entry (null or
- * absent) is a routed or unpinned-native model and is allowed. The three-way
- * distinction is the substance; do not flatten it into a truthiness check.
+ * The field no longer answers "may I be a delegation target". It answers "does the
+ * CHILD get collaboration tools": `collab_tools_enabled`
+ * (core/src/tools/spec_plan.rs:599-610) grants a child recursive tools only when its
+ * own catalog value is exactly `Some(V2)`. The three-way distinction survives, but it
+ * now means eligible-recursive / eligible-LEAF / excluded:
+ *
+ * - `"v2"`       -> eligible, and the child may itself delegate.
+ * - `"v1"`       -> eligible LEAF worker. This is upstream's pin for `gpt-5.6-luna`
+ *                   (models-manager/models.json); excluding it here is exactly what
+ *                   kept Luna out of opencodex's roster.
+ * - absent/null  -> eligible LEAF worker (routed or unpinned-native model).
+ * - `"disabled"` -> the sole capability-based exclusion.
+ *
+ * This is the roster filter only. Catalog STAMPING is a separate concern owned by
+ * `applyMultiAgentMode`, including the `keepNativeChatGptOnV1` policy (#1728) that
+ * keeps ChatGPT-native rows on `v1` so a native parent can still spawn a routed child
+ * despite backend-encrypted NEW_TASK bodies (#92). Recognizing those `v1` rows as
+ * eligible leaves here is what makes that policy usable, not a contradiction of it.
+ *
+ * Devlog: 260816_codexrs_multiagent_v2_and_history_perf/011 (C1), superseding the
+ * option-B decision in 260730_codex_rs_upstream_v2_live_handoff/060.
  */
 export function isEligibleV2SubagentEntry(entry: RawEntry): boolean {
-  const pinned = entry.multi_agent_version;
-  return pinned === "v2" || pinned === null || pinned === undefined;
+  return entry.multi_agent_version !== "disabled";
 }
 
 export interface EffectiveSubagentModel {
@@ -343,10 +358,9 @@ export function deriveEntry(
     });
   }
   // Fallback when no template is available (best-effort; strict parser may need more).
-  // Cursor fallback rows mirror normalizeRoutedCatalogEntry: no deferred discovery, no hosted
-  // web-search metadata (runTurn transport bypasses the sidecar). Non-Cursor routed fallbacks
-  // advertise deferred discovery — code mode keeps deferred MCP callable (devlog
-  // 260813_tool_catalog_deferral/010+020); search=false costs a measured 2.7x turn-1 payload.
+  // All routed fallbacks enable deferred code-mode tool exposure; otherwise the nested catalog
+  // expands into `exec.description` and can exceed Cursor's 120 KB serialized tool limit (#1830).
+  // Cursor still omits hosted web-search metadata because runTurn bypasses that separate sidecar.
   const isCursorFallback = isRouted && model?.provider === "cursor";
   const entry: RawEntry = {
     slug, display_name: routedDisplayName(slug), description: desc,
@@ -354,7 +368,7 @@ export function deriveEntry(
     priority, base_instructions: "You are a helpful coding assistant.",
     ...(isRouted
       ? isCursorFallback
-        ? { supports_search_tool: false }
+        ? { supports_search_tool: true }
         : { web_search_tool_type: "text_and_image", supports_search_tool: true }
       : {}),
   };
@@ -1672,8 +1686,16 @@ export async function syncCatalogModels(config: OcxConfig): Promise<RetainedCata
 export function restoreCodexCatalogWithPermit(
   permit: CatalogWritePermit,
   owningCodexHome: string,
+  /**
+   * The catalog this injection actually wrote, when it is known (#1798).
+   *
+   * Re-resolving from the CURRENT config is wrong after a Codex app rewrite that dropped
+   * `model_catalog_json`: that sends restore to the default catalog while the routed file we
+   * really wrote is left untouched. The recorded path is the file whose routing is ours.
+   */
+  injectedCatalogPath?: string | null,
 ): { removed: number; kept: number; path: string } {
-  const catalogPath = readCodexCatalogPath();
+  const catalogPath = injectedCatalogPath ?? readCodexCatalogPath();
   const catalog = readCatalog(catalogPath);
   if (!catalog || !Array.isArray(catalog.models)) return { removed: 0, kept: 0, path: catalogPath };
   const disabledModels = currentDisabledModelsForRestore();

package/src/codex/catalog-refresh-status.ts

@@ -1,4 +1,4 @@
-import type { CatalogDisposition, CatalogNotice } from "./convergence-types";
+import type { CatalogDisposition, CatalogFailureCause, CatalogNotice } from "./convergence-types";
 
 const INVALID_CATALOG_DISPOSITION_FIELD = Symbol("invalid-catalog-disposition-field");
 
@@ -69,11 +69,15 @@ export function normalizeCatalogDisposition(value: unknown): CatalogDisposition
       const phase = ownDataProperty(value, "phase");
       const retryable = ownDataProperty(value, "retryable");
       const partialWrite = ownDataProperty(value, "partialWrite");
-      if ((reason !== "provider-auth" && reason !== "provider-network" && reason !== "disk")
+      if ((reason !== "provider-auth" && reason !== "provider-network" && reason !== "disk"
+        && reason !== "request-invalid" && reason !== "admission" && reason !== "internal")
         || (phase !== "gather" && phase !== "commit")
         || typeof retryable !== "boolean"
         || typeof partialWrite !== "boolean") return null;
-      return { status, reason, phase, retryable, partialWrite };
+      // The cause is rebuilt from closed vocabularies, never copied through: this is the
+      // boundary that keeps a message, path or account id from riding out on a failure.
+      const cause = normalizeCatalogFailureCause(ownDataProperty(value, "cause"));
+      return { status, reason, phase, retryable, partialWrite, ...(cause ? { cause } : {}) };
     }
     return null;
   } catch {
@@ -81,6 +85,20 @@ export function normalizeCatalogDisposition(value: unknown): CatalogDisposition
   }
 }
 
+const FAILURE_CAUSE_KINDS: ReadonlySet<string> = new Set(["invalid-request", "lock-busy", "io", "unknown"]);
+const FAILURE_CAUSE_CODES: ReadonlySet<string> = new Set([
+  "ENOSPC", "EACCES", "EPERM", "EROFS", "ENOENT", "SQLITE_BUSY",
+]);
+
+function normalizeCatalogFailureCause(value: unknown): CatalogFailureCause | undefined {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return undefined;
+  const kind = ownDataProperty(value, "kind");
+  if (typeof kind !== "string" || !FAILURE_CAUSE_KINDS.has(kind)) return undefined;
+  const code = ownDataProperty(value, "code");
+  const safeCode = typeof code === "string" && FAILURE_CAUSE_CODES.has(code) ? code : undefined;
+  return { kind, ...(safeCode ? { code: safeCode } : {}) } as CatalogFailureCause;
+}
+
 /** Whether a persisted mutation still needs a successful catalog commit. */
 export function catalogRefreshIsPending(disposition: CatalogDisposition): boolean {
   return disposition.status !== "committed";

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_OPENAI_CAPABILITY_ALIAS_MODELS, NATIVE_OPENAI_MODELS, configuredNativeAliasSlugs, desktopAllowlistSuppressedNativeSlugs, isNativeAliasCatalogEntry, isNativeOpenAiCapabilityAliasModel, nativeOpenAiCapabilitySourceSlug, nativeOpenAiContextWindow, disabledNativeSlugs, visibleNativeSlugs, desktopVisibleNativeSlugs, nativeModelRows, applyNativeVisibility, observedAccountBoundNativeEntries, observedAccountBoundNativeOpenAiSlugs, upstreamNativeEntry, nativeOpenAiSlugs, listCatalogNativeSlugs, nativeInputModalities, nativeReasoningEfforts, nativeDefaultReasoningEffort, shouldIncludeAccountBoundNativeOpenAi, shouldIncludeNativeOpenAi } from "./catalog/metadata";
+export { accountBoundNativeOpenAiSlugs, accountBoundNativeOpenAiSlugsBySelector, CODEX_NATIVE_ALIAS_CATALOG_KIND, NATIVE_DAYBREAK_BLUE_MODEL, NATIVE_GPT56_MAX_INPUT_TOKENS, NATIVE_OPENAI_CAPABILITY_ALIAS_MODELS, NATIVE_OPENAI_MODELS, configuredNativeAliasSlugs, desktopAllowlistSuppressedNativeSlugs, isNativeAliasCatalogEntry, isNativeOpenAiCapabilityAliasModel, nativeOpenAiCapabilitySourceSlug, nativeOpenAiContextWindow, nativeOpenAiMaxInputTokens, disabledNativeSlugs, visibleNativeSlugs, desktopVisibleNativeSlugs, nativeModelRows, applyNativeVisibility, observedAccountBoundNativeEntries, observedAccountBoundNativeOpenAiSlugs, upstreamNativeEntry, nativeOpenAiSlugs, listCatalogNativeSlugs, nativeInputModalities, nativeReasoningEfforts, nativeDefaultReasoningEffort, shouldIncludeAccountBoundNativeOpenAi, shouldIncludeNativeOpenAi } 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/convergence-types.ts

@@ -161,8 +161,29 @@ export type CatalogDisposition =
   | { status: "skipped";
       reason: "not-requested" | "catalog-unavailable" | "busy" | "stale" | "refused";
       retryable: boolean }
-  | { status: "failed"; reason: "provider-auth" | "provider-network" | "disk";
-      phase: "gather" | "commit"; retryable: boolean; partialWrite: boolean };
+  | { status: "failed";
+      /**
+       * `disk` used to absorb every unclassified failure, so a malformed request and a
+       * genuine ENOSPC were indistinguishable and both reported non-retryable (#1784).
+       */
+      reason: "provider-auth" | "provider-network" | "disk" | "request-invalid" | "admission" | "internal";
+      phase: "gather" | "commit"; retryable: boolean; partialWrite: boolean;
+      /** Allowlisted cause summary. Closed vocabularies only -- never message text. */
+      cause?: CatalogFailureCause };
+
+/**
+ * Why a catalog operation failed, in terms safe to return from the management plane.
+ *
+ * Both fields are closed sets on purpose. An `Error.constructor.name` is dependency- or
+ * input-influenced (any thrown custom class names itself) and an `Error.message` routinely
+ * carries paths, home directories and account identifiers, none of which may cross this
+ * boundary.
+ */
+export type CatalogFailureCause = {
+  kind: "invalid-request" | "lock-busy" | "io" | "unknown";
+  /** Recognized errno/code token, when the underlying error carried one. */
+  code?: "ENOSPC" | "EACCES" | "EPERM" | "EROFS" | "ENOENT" | "SQLITE_BUSY";
+};
 
 /**
  * The ONLY way Codex-owned bytes are written. Startup, ensure, /api/sync, the

package/src/codex/desired-state.ts

@@ -18,7 +18,7 @@
  * depending on the temp root. Convergence takes the write lock; this module only
  * records intent through the config coordinator.
  *
- * Design record: devlog/_plan/260803_codex_desktop_toggle/030_desired_state.md.
+ * Design record: devlog/_fin/260803_codex_desktop_toggle/030_desired_state.md.
  */
 import { loadConfig, mutatePersistedConfig } from "../config";
 import type { OcxClientIntegrationsConfig, OcxConfig } from "../types";

package/src/codex/inject.ts

@@ -30,6 +30,8 @@ import {
 } from "./user-identity";
 import {
   markJournalInjectedState,
+  journaledInjectedOpenaiBaseUrl,
+  journaledInjectedCatalogPath,
   removeJournal,
   restoreJournalState,
   writeJournal,
@@ -52,6 +54,7 @@ import {
   providerTableStart,
   providerTableString,
   rootTomlString,
+  stripJournaledOpenaiBaseUrl,
   tomlStringPattern,
 } from "./injected-marker";
 import {
@@ -1138,12 +1141,18 @@ interface StripOpencodexConfigResult {
  */
 function stripOpencodexConfigResult(
   content: string,
+  journaledBaseUrl: string | null = null,
 ): StripOpencodexConfigResult {
   let out = content;
   const hadRootOcxProvider =
     readRootTomlString(out, "model_provider") === "opencodex";
-  const hadInjectedBaseUrl = hasInjectedOpenaiBaseUrl(out);
+  // #1798: marker adjacency is FORMATTING evidence, and a Codex app rewrite keeps values
+  // while dropping comments. Fall back to VALUE evidence -- the exact URL we recorded
+  // writing -- so an app-rewritten config is still recognized as ours.
+  const hadInjectedBaseUrl = hasInjectedOpenaiBaseUrl(out)
+    || (journaledBaseUrl !== null && rootTomlString(out, "openai_base_url") === journaledBaseUrl);
   out = stripInjectedOpenaiBaseUrl(out); // before removeOcxSection — it keys on the marker line too
+  out = stripJournaledOpenaiBaseUrl(out, journaledBaseUrl);
   if (out.includes("[model_providers.opencodex]")) {
     out = removeOcxSection(out);
   }
@@ -1195,8 +1204,12 @@ export function removeCodexConfig(
   // The unchanged fast path compares in LF space so an untouched file is never rewritten.
   const eol = dominantEol(rawContent);
   const content = applyEol(rawContent, "\n");
-  const had = hasOpencodexRouting(content);
-  const stripped = stripOpencodexConfigResult(content);
+  // Read the recorded injection once: the strip below consumes it, and so does the
+  // ownership verdict, which must agree with what was actually removed.
+  const journaledBaseUrl = journaledInjectedOpenaiBaseUrl();
+  const had = hasOpencodexRouting(content)
+    || (journaledBaseUrl !== null && rootTomlString(content, "openai_base_url") === journaledBaseUrl);
+  const stripped = stripOpencodexConfigResult(content, journaledBaseUrl);
   if (had || stripped.content !== content) {
     atomicWriteFile(CODEX_CONFIG_PATH, applyEol(stripped.content, eol));
   }
@@ -1371,13 +1384,23 @@ function restoreCodexConfigInline(): CodexRestoreConfigResult {
 }
 
 /** The catalog half, always inside its own K acquisition. */
-function restoreCodexCatalogArtifact(revalidateDesiredState: boolean): CodexRestoreCatalogResult {
+/**
+ * The catalog half, always inside its own K acquisition.
+ *
+ * `journaledCatalogPath` must be captured by the CALLER, before the config half runs: a
+ * successful journal restore deletes the journal, and a config restore can remove
+ * `model_catalog_json`. Reading it here would be too late in both cases (#1798).
+ */
+function restoreCodexCatalogArtifact(
+  revalidateDesiredState: boolean,
+  journaledCatalogPath: string | null,
+): CodexRestoreCatalogResult {
   const owningCodexHome = getCodexHome();
   try {
     const restored = withCatalogWriteSerialization(owningCodexHome, permit =>
       revalidateDesiredState && shouldSyncCodexOnStart(loadConfig())
         ? null
-        : restoreCodexCatalogWithPermit(permit, owningCodexHome));
+        : restoreCodexCatalogWithPermit(permit, owningCodexHome, journaledCatalogPath));
     return restored.kind === "completed" && restored.value !== null
       ? { state: "ok", changed: restored.value.removed > 0, ...restored.value, message: "Codex catalog restored." }
       : restored.kind === "completed"
@@ -1435,6 +1458,10 @@ export async function restoreNativeCodexAsync(
     integrationRecord: () => readIntegrationRecord(),
   });
 
+  // Captured before the config half: a successful journal restore DELETES the journal, and
+  // restoring the config can drop `model_catalog_json`. Either one would hide the routed
+  // catalog we actually wrote (#1798).
+  const journaledCatalogPath = journaledInjectedCatalogPath();
   let config: CodexRestoreConfigResult;
   let transitionReceipt: { nativeGeneration: number; currentTxId: string } | undefined;
 
@@ -1511,7 +1538,7 @@ export async function restoreNativeCodexAsync(
     config = restoreCodexConfigInline();
   }
 
-  const catalog = restoreCodexCatalogArtifact(options.revalidateDesiredState === true);
+  const catalog = restoreCodexCatalogArtifact(options.revalidateDesiredState === true, journaledCatalogPath);
   const outcome = await runCodexHistoryJob({
     ...resolveCodexHistoryJobTarget(),
     ...(options.revalidateDesiredState ? { expectedDesiredEnabled: false } : {}),
@@ -1561,8 +1588,12 @@ export function restoreNativeCodex(options: { skipHistory?: boolean; revalidateD
   if (options.revalidateDesiredState && shouldSyncCodexOnStart(loadConfig())) {
     return desiredEnabledRestoreSkip();
   }
+  // Captured before the config half: a successful journal restore DELETES the journal, and
+  // restoring the config can drop `model_catalog_json`. Either one would hide the routed
+  // catalog we actually wrote (#1798).
+  const journaledCatalogPath = journaledInjectedCatalogPath();
   const config = restoreCodexConfigInline();
-  const catalog = restoreCodexCatalogArtifact(options.revalidateDesiredState === true);
+  const catalog = restoreCodexCatalogArtifact(options.revalidateDesiredState === true, journaledCatalogPath);
   // Design B (loopback) steady state: threads are already tagged openai, so prove the
   // no-op with a readonly probe instead of write-opening a DB the Codex app may hold
   // (Windows: WAL writer lock -> seconds of stalling + a false warning on every stop).

package/src/codex/injected-marker.ts

@@ -50,6 +50,34 @@ export function providerTableString(content: string, provider: string, key: stri
   return null;
 }
 
+/**
+ * Drop a root `openai_base_url` whose VALUE is the one a recorded injection wrote.
+ *
+ * #1798: the marker-adjacency rule below is formatting evidence, and the Codex app
+ * reserializes the file -- values kept, comments dropped. This rule is value evidence
+ * instead, so it still recognizes our URL after that rewrite. It is deliberately an
+ * EXACT value match against what we recorded writing: a user gateway we never wrote
+ * cannot match, so restore can never delete a URL that was not ours.
+ */
+export function stripJournaledOpenaiBaseUrl(content: string, injectedUrl: string | null): string {
+  if (!injectedUrl) return content;
+  const lines = content.split(String.fromCharCode(10));
+  const firstTable = lines.findIndex(l => /^\s*\[/.test(l));
+  const rootEnd = firstTable === -1 ? lines.length : firstTable;
+  const drop = new Set<number>();
+  for (let i = 0; i < rootEnd; i++) {
+    const line = lines[i]!;
+    if (!isRootOpenaiBaseUrlLine(line)) continue;
+    if (rootTomlString(line, "openai_base_url") !== injectedUrl) continue;
+    drop.add(i);
+    // Take an ownership marker directly above it too, so repeated cycles cannot
+    // accumulate orphaned comments.
+    if (i > 0 && lines[i - 1]!.includes(OCX_SECTION_MARKER)) drop.add(i - 1);
+  }
+  if (drop.size === 0) return content;
+  return lines.filter((_, i) => !drop.has(i)).join(String.fromCharCode(10));
+}
+
 export function hasInjectedOpenaiBaseUrl(content: string): boolean {
   const lines = content.split("\n");
   const firstTable = lines.findIndex(l => /^\s*\[/.test(l));

package/src/codex/journal.ts

@@ -2,7 +2,7 @@ import { createHash } from "node:crypto";
 import { existsSync, readFileSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 import { atomicWriteFile } from "../config";
-import { hasInjectedCodexRouting } from "./injected-marker";
+import { hasInjectedCodexRouting, rootTomlString } from "./injected-marker";
 import { CODEX_HOME, CODEX_CONFIG_PATH, CODEX_PROFILE_PATH } from "./paths";
 
 /**
@@ -22,6 +22,24 @@ interface Journal {
   originalProfile: string | null;
   injectedConfigHash?: string;
   injectedProfileHash?: string | null;
+  /**
+   * The exact root `openai_base_url` this injection wrote, when it wrote one.
+   *
+   * #1798: ownership used to be inferred from a marker COMMENT on the preceding line,
+   * which a reserializing Codex app deletes while keeping the value. Recording the value
+   * we actually wrote makes ownership provable from evidence rather than from formatting,
+   * and it is what lets restore tell OUR loopback URL apart from a gateway the user set.
+   */
+  injectedOpenaiBaseUrl?: string | null;
+  /**
+   * The catalog path this injection actually wrote to.
+   *
+   * #1798: restore re-resolves the catalog from the CURRENT config, so a Codex app rewrite
+   * that dropped `model_catalog_json` sends restore to the default catalog while the
+   * proxy-written one is left routed. The injected path is the only durable record of which
+   * file we actually touched.
+   */
+  injectedCatalogPath?: string | null;
   pid: number;
   timestamp: string;
 }
@@ -96,9 +114,30 @@ export function markJournalInjectedState(config: string, profile: string | null)
   if (journal.injectedConfigHash) return;
   journal.injectedConfigHash = sha256(config) ?? undefined;
   journal.injectedProfileHash = sha256(profile);
+  // Read from the bytes we are about to install, not from the file: another writer may
+  // already have rewritten it, and then the recorded value would describe their config.
+  journal.injectedOpenaiBaseUrl = rootTomlString(config, "openai_base_url");
+  journal.injectedCatalogPath = rootTomlString(config, "model_catalog_json");
   atomicWriteFile(JOURNAL_PATH, JSON.stringify(journal));
 }
 
+/**
+ * The root `openai_base_url` the last injection wrote, or null when it wrote none.
+ *
+ * #1798: the fallback strip recognizes an injected URL by the marker COMMENT above it,
+ * and a Codex app rewrite keeps values while dropping comments. This is the evidence that
+ * survives such a rewrite, so restore can still prove the URL is ours -- and, just as
+ * importantly, prove that a DIFFERENT URL is not.
+ */
+export function journaledInjectedOpenaiBaseUrl(): string | null {
+  return readJournal()?.injectedOpenaiBaseUrl ?? null;
+}
+
+/** The catalog path the last injection wrote to, or null when none was recorded. */
+export function journaledInjectedCatalogPath(): string | null {
+  return readJournal()?.injectedCatalogPath ?? null;
+}
+
 export function removeJournal(): void {
   try { unlinkSync(JOURNAL_PATH); } catch { /* ignore */ }
 }