@bitkyc08/opencodex 2.25.0 → 2.26.0

package/src/codex/inject.ts

@@ -227,9 +227,13 @@ export function buildProviderTableBlock(
     "requires_openai_auth = true",
   ];
   if (includeApiAuthHeader) {
-    lines.push(
-      'env_http_headers = { "x-opencodex-api-key" = "OPENCODEX_API_AUTH_TOKEN" }',
-    );
+    // codex-cli 0.146+ contract (#2073): env_key sends Authorization: Bearer $VAR and
+    // hard-errors on a missing/empty variable instead of silently omitting auth. It
+    // coexists with requires_openai_auth (env_key wins wire auth; the flag keeps the
+    // login/account UX), and the server substitutes stored main auth for our admission
+    // bearer (#1686), so the modern form is strictly better than the legacy
+    // env_http_headers table this line used to emit.
+    lines.push('env_key = "OPENCODEX_API_AUTH_TOKEN"');
   }
   if (supportsWebsockets) lines.push("supports_websockets = true");
   return lines.join("\n") + "\n";
@@ -735,7 +739,7 @@ export async function injectCodexConfig(
   // Design B form FIRST: removeOcxSection also keys on the marker line, so a root-level
   // marker + openai_base_url pair must be gone before it scans or it would swallow root keys.
   content = stripInjectedOpenaiBaseUrl(content);
-  if (content.includes("[model_providers.opencodex]")) {
+  if (hasOcxProviderTable(content)) {
     content = removeOcxSection(content);
   }
   content = removeProfileSection(content);
@@ -1095,6 +1099,30 @@ export async function injectCodexConfig(
   };
 }
 
+/**
+ * Sub-table headers like `[model_providers.opencodex.env_http_headers]` appear when a Codex app
+ * config rewrite re-serializes the provider's inline `env_http_headers` table. They define the
+ * same `model_providers.opencodex` provider, so cleanup must remove them too — otherwise the
+ * provider survives with no `name` and Codex rejects the whole config
+ * ("provider name must not be empty"). The dot terminator keeps a user's
+ * `[model_providers.opencodex_backup]`-style tables out of scope.
+ */
+function isOcxProviderHeaderLine(trimmedLine: string): boolean {
+  // Root form matched by regex, not equality: TOML v1.0 allows a trailing comment
+  // (`[model_providers.opencodex] # comment`), and an exact compare would miss that form.
+  // The sub-table prefix check already tolerates trailing comments by construction.
+  return (
+    /^\[model_providers\.opencodex\]\s*(?:#.*)?$/.test(trimmedLine) ||
+    trimmedLine.startsWith("[model_providers.opencodex.")
+  );
+}
+
+function hasOcxProviderTable(content: string): boolean {
+  return content
+    .split("\n")
+    .some((line) => isOcxProviderHeaderLine(line.trim()));
+}
+
 function removeOcxSection(content: string): string {
   const lines = content.split("\n");
   const filtered: string[] = [];
@@ -1102,18 +1130,16 @@ function removeOcxSection(content: string): string {
   for (const line of lines) {
     if (
       line.includes(OCX_SECTION_MARKER) ||
-      line.trim() === "[model_providers.opencodex]"
+      isOcxProviderHeaderLine(line.trim())
     ) {
       inOcxSection = true;
       continue;
     }
     if (inOcxSection) {
-      // End the injected section at the next table header that ISN'T our own — exact match so a
-      // user's "[model_providers.opencodex_backup]" (or similar) is preserved, not swallowed.
-      if (
-        /^\s*\[/.test(line) &&
-        line.trim() !== "[model_providers.opencodex]"
-      ) {
+      // End the injected section at the next table header that ISN'T our own. Exact match on the
+      // provider name (plus our own sub-tables) so a user's
+      // "[model_providers.opencodex_backup]" (or similar) is preserved, not swallowed.
+      if (/^\s*\[/.test(line) && !isOcxProviderHeaderLine(line.trim())) {
         inOcxSection = false;
         filtered.push(line);
       }
@@ -1153,7 +1179,7 @@ function stripOpencodexConfigResult(
     || (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]")) {
+  if (hasOcxProviderTable(out)) {
     out = removeOcxSection(out);
   }
   out = removeProfileSection(out);
@@ -1182,7 +1208,7 @@ export function stripOpencodexConfig(content: string): string {
 
 function hasOpencodexRouting(content: string): boolean {
   return (
-    content.includes("[model_providers.opencodex]") ||
+    hasOcxProviderTable(content) ||
     /^\s*model_provider\s*=\s*"opencodex"/m.test(content) ||
     hasInjectedOpenaiBaseUrl(content)
   );

package/src/codex/main-account.ts

@@ -1,5 +1,6 @@
 import { readCodexTokens } from "./auth-collision";
 import { decodeJwtPayload } from "../oauth/chatgpt";
+import { extractChatgptPlanType } from "./plan";
 import { MAIN_CODEX_ACCOUNT_ID } from "./account-id";
 
 export { MAIN_CODEX_ACCOUNT_ID } from "./account-id";
@@ -10,13 +11,23 @@ export { MAIN_CODEX_ACCOUNT_ID } from "./account-id";
  * percent, matching pool-account behavior.
  */
 let mainAccountPlan: string | null = null;
+let jwtPlanAttempted = false;
 
 export function setMainAccountPlan(plan: string | null): void {
   mainAccountPlan = plan;
+  if (plan === null) jwtPlanAttempted = false;
 }
 
 export function getMainAccountPlan(): string | undefined {
-  return mainAccountPlan ?? undefined;
+  if (mainAccountPlan) return mainAccountPlan;
+  if (jwtPlanAttempted) return undefined;
+  jwtPlanAttempted = true;
+  const tokens = readCodexTokens();
+  const jwtPlan = tokens
+    ? extractChatgptPlanType(tokens.id_token, tokens.access_token)
+    : undefined;
+  if (jwtPlan) mainAccountPlan = jwtPlan;
+  return jwtPlan;
 }
 
 /** Read-only main account token from ~/.codex/auth.json, or null when not logged in. */
@@ -38,3 +49,20 @@ export function isMainAccountTokenLive(now = Date.now()): boolean {
   const exp = typeof payload?.exp === "number" ? payload.exp * 1000 : undefined;
   return exp === undefined || exp > now;
 }
+
+/**
+ * Strict liveness for auth-terminality decisions: true only when the access-token JWT
+ * carries a decodable `exp` that is still in the future.
+ *
+ * Unlike {@link isMainAccountTokenLive}, an undecodable `exp` counts as NOT live here.
+ * This gate decides whether a bare WHAM 401 is downgraded to a transient failure; if an
+ * undecodable token could vouch for itself, a genuinely dead credential would keep every
+ * 401 "transient" and needsReauth could never flip.
+ */
+export function isMainAccountTokenVerifiablyLive(now = Date.now()): boolean {
+  const tokens = readCodexTokens();
+  if (!tokens?.access_token) return false;
+  const payload = decodeJwtPayload(tokens.access_token);
+  const exp = typeof payload?.exp === "number" ? payload.exp * 1000 : undefined;
+  return exp !== undefined && exp > now;
+}

package/src/codex/plan-from-token.ts

@@ -0,0 +1,140 @@
+import {
+  ConfigMutationLockError,
+  loadConfig,
+  mutatePersistedConfig,
+} from "../config";
+import type { CodexAccount, OcxConfig } from "../types";
+import { isSelectableCodexPoolAccount, isValidCodexAccountId } from "./account-id";
+import {
+  getCodexAccountCredential,
+  isCodexAccountGenerationLive,
+  readCodexAccountRecord,
+} from "./account-store";
+import { extractChatgptPlanType, codexPlanValue } from "./plan";
+
+interface FreshPoolPlanUpdate {
+  accountId: string;
+  plan: string;
+  credentialGeneration: number;
+}
+
+function configuredPoolAccount(config: OcxConfig, accountId: string): CodexAccount | null {
+  if (!isValidCodexAccountId(accountId)) return null;
+  return (config.codexAccounts ?? [])
+    .find(account => account.id === accountId && isSelectableCodexPoolAccount(account)) ?? null;
+}
+
+function jwtPlanFromPoolCredential(accountId: string): string | undefined {
+  const cred = getCodexAccountCredential(accountId);
+  return cred ? extractChatgptPlanType(undefined, cred.accessToken) : undefined;
+}
+
+/**
+ * WHAM-wins gate (release-audit fix). A JWT-derived plan may be persisted only when no
+ * WHAM-sourced plan exists for the CURRENT credential generation. A token refresh bumps the
+ * generation, and the refreshed JWT is then genuinely newer information than the previous
+ * generation's WHAM read, so it may write again until WHAM re-observes. Records without
+ * provenance (legacy) stay writable so the original #1989 recovery still works.
+ */
+function jwtMayWritePlan(account: CodexAccount, generation: number): boolean {
+  if (account.planSource !== "wham") return true;
+  const whamGeneration = account.planCredentialGeneration;
+  return whamGeneration !== undefined && generation > whamGeneration;
+}
+
+function collectJwtPoolPlanUpdates(runtimeConfig: OcxConfig): FreshPoolPlanUpdate[] {
+  const updates: FreshPoolPlanUpdate[] = [];
+  for (const account of (runtimeConfig.codexAccounts ?? []).filter(isSelectableCodexPoolAccount)) {
+    const jwtPlan = jwtPlanFromPoolCredential(account.id);
+    if (!jwtPlan || codexPlanValue(account.plan) === jwtPlan) continue;
+    const generation = readCodexAccountRecord(account.id)?.generation;
+    if (generation === undefined) continue;
+    if (!jwtMayWritePlan(account, generation)) continue;
+    updates.push({ accountId: account.id, plan: jwtPlan, credentialGeneration: generation });
+  }
+  return updates;
+}
+
+const appliedJwtPlans = new Map<string, string>();
+
+function persistJwtPlanUpdates(runtimeConfig: OcxConfig, updates: FreshPoolPlanUpdate[]): void {
+  if (updates.length === 0) return;
+  let outcome: ReturnType<typeof mutatePersistedConfig<FreshPoolPlanUpdate[]>>;
+  try {
+    outcome = mutatePersistedConfig(persistedConfig => {
+      const accepted: FreshPoolPlanUpdate[] = [];
+      let changed = false;
+      for (const update of updates) {
+        if (!isCodexAccountGenerationLive(update.accountId, update.credentialGeneration)) continue;
+        const liveAccount = configuredPoolAccount(runtimeConfig, update.accountId);
+        const persistedAccount = configuredPoolAccount(persistedConfig, update.accountId);
+        if (!liveAccount || !persistedAccount) continue;
+        // Re-check against the PERSISTED row: another process may have landed a WHAM
+        // observation between collect and this mutation.
+        if (!jwtMayWritePlan(persistedAccount, update.credentialGeneration)) continue;
+        accepted.push(update);
+        if (persistedAccount.plan !== update.plan) {
+          persistedAccount.plan = update.plan;
+          changed = true;
+        }
+        if (persistedAccount.planSource !== "jwt" || persistedAccount.planCredentialGeneration !== update.credentialGeneration) {
+          persistedAccount.planSource = "jwt";
+          persistedAccount.planCredentialGeneration = update.credentialGeneration;
+          changed = true;
+        }
+      }
+      return { changed, value: accepted };
+    });
+  } catch (error) {
+    if (error instanceof ConfigMutationLockError) return;
+    throw error;
+  }
+  if (outcome.status === "unavailable") return;
+  for (const update of outcome.value) {
+    if (!isCodexAccountGenerationLive(update.accountId, update.credentialGeneration)) continue;
+    const liveAccount = configuredPoolAccount(runtimeConfig, update.accountId);
+    if (liveAccount) {
+      liveAccount.plan = update.plan;
+      liveAccount.planSource = "jwt";
+      liveAccount.planCredentialGeneration = update.credentialGeneration;
+      appliedJwtPlans.set(update.accountId, update.plan);
+    }
+  }
+}
+
+/**
+ * Persist JWT `chatgpt_plan_type` onto `codexAccounts[].plan` when it contradicts the stored
+ * label. Generation-gated, same fail-closed lock policy as the WHAM plan patch. Does not
+ * overwrite a plan that already matches the token.
+ */
+export function reconcileCodexPlansFromTokens(runtimeConfig: OcxConfig = loadConfig()): void {
+  persistJwtPlanUpdates(runtimeConfig, collectJwtPoolPlanUpdates(runtimeConfig));
+}
+
+export function resetJwtPlanNotesForTests(): void {
+  appliedJwtPlans.clear();
+}
+
+/** Apply one account's live token claim without blocking the credential read path. */
+export function noteCodexAccountAccessToken(
+  accountId: string,
+  accessToken: string,
+  credentialGeneration: number,
+): void {
+  const jwtPlan = extractChatgptPlanType(undefined, accessToken);
+  if (!jwtPlan) return;
+  if (appliedJwtPlans.get(accountId) === jwtPlan) return;
+  try {
+    const runtimeConfig = loadConfig();
+    const live = configuredPoolAccount(runtimeConfig, accountId);
+    if (!live || codexPlanValue(live.plan) === jwtPlan) {
+      appliedJwtPlans.set(accountId, jwtPlan);
+      return;
+    }
+    if (!jwtMayWritePlan(live, credentialGeneration)) return;
+    persistJwtPlanUpdates(runtimeConfig, [{ accountId, plan: jwtPlan, credentialGeneration }]);
+    if (codexPlanValue(live.plan) === jwtPlan) appliedJwtPlans.set(accountId, jwtPlan);
+  } catch {
+    appliedJwtPlans.delete(accountId);
+  }
+}

package/src/codex/plan.ts

@@ -1,3 +1,5 @@
+import { decodeJwtPayload } from "../oauth/chatgpt";
+
 /** Preserve user/provider plan labels only when they are usable strings. */
 export function codexPlanValue(value: unknown): string | undefined {
   if (typeof value !== "string") return undefined;
@@ -13,3 +15,26 @@ export function isThirtyDayOnlyCodexPlan(value: unknown): boolean {
   const key = codexPlanKey(value);
   return key === "go" || key === "free";
 }
+
+/**
+ * ChatGPT plan label from a live access/id token (`chatgpt_plan_type`).
+ * Used when WHAM has not run yet so a stale stored `free` cannot outrank the token (#1989).
+ */
+export function extractChatgptPlanType(idToken?: string, accessToken?: string): string | undefined {
+  for (const token of [idToken, accessToken]) {
+    if (!token) continue;
+    const payload = decodeJwtPayload(token);
+    if (!payload) continue;
+    if (typeof payload.chatgpt_plan_type === "string") {
+      const plan = codexPlanValue(payload.chatgpt_plan_type);
+      if (plan) return plan;
+    }
+    const ns = payload["https://api.openai.com/auth"];
+    if (ns && typeof ns === "object") {
+      const nested = (ns as Record<string, unknown>).chatgpt_plan_type;
+      const plan = codexPlanValue(nested);
+      if (plan) return plan;
+    }
+  }
+  return undefined;
+}

package/src/codex/prompt-journal.ts

@@ -19,10 +19,11 @@
  * concrete: crash after writing config.toml, user or Codex then edits it,
  * recovery sees a mismatch and overwrites their work with a stale image.
  */
-import { existsSync, mkdirSync, openSync, closeSync, fsyncSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, openSync, closeSync, fsyncSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { createHash, randomBytes } from "node:crypto";
 import { forgetEphemeralSecretPath, hardenSecretPath, windowsSecretAclApplies } from "../lib/windows-secret-acl";
+import { renameAtomicFile } from "../lib/windows-atomic-replace";
 
 const FILE_MODE = 0o600;
 const DIR_MODE = 0o700;
@@ -79,7 +80,10 @@ export function durableWrite(path: string, content: string): void {
     fsyncSync(fd);
     closeSync(fd);
     fd = undefined;
-    renameSync(tmp, path);
+    // Windows can refuse the replace with EBUSY/EPERM/EACCES while a scanner
+    // still holds the target; the shared helper retries that briefly. Losing
+    // this publish breaks journal restore, so it should not fail on a blink.
+    renameAtomicFile(tmp, path, undefined, "prompt-journal");
     // The temp is renamed away: proven absent — release its ACL memos.
     forgetEphemeralSecretPath(tmp);
     fsyncDir(path);

package/src/codex/quota-rejection.ts

@@ -71,15 +71,29 @@ async function denialFromResponse(
   }
 }
 
-/** Own-property `code` lookup at the top level or under `error`. No coercion, no accessors. */
+function ownStringField(container: Record<string, unknown>, field: string): string | undefined {
+  const descriptor = Object.getOwnPropertyDescriptor(container, field);
+  return descriptor && "value" in descriptor && typeof descriptor.value === "string"
+    ? descriptor.value
+    : undefined;
+}
+
+/** Own-property `code` lookup at the top level or under `error` / `detail`. No coercion or accessors. */
 function structuredDenialCode(payload: unknown): string | undefined {
   if (payload === null || typeof payload !== "object" || Array.isArray(payload)) return undefined;
-  const direct = (payload as Record<string, unknown>).code;
-  if (typeof direct === "string") return direct;
-  const error = (payload as Record<string, unknown>).error;
-  if (error === null || typeof error !== "object" || Array.isArray(error)) return undefined;
-  const nested = (error as Record<string, unknown>).code;
-  return typeof nested === "string" ? nested : undefined;
+  const record = payload as Record<string, unknown>;
+  const direct = ownStringField(record, "code");
+  if (direct !== undefined) return direct;
+
+  for (const field of ["error", "detail"] as const) {
+    const descriptor = Object.getOwnPropertyDescriptor(record, field);
+    if (!descriptor || !("value" in descriptor)) continue;
+    const nested = descriptor.value;
+    if (nested === null || typeof nested !== "object" || Array.isArray(nested)) continue;
+    const code = ownStringField(nested as Record<string, unknown>, "code");
+    if (code !== undefined) return code;
+  }
+  return undefined;
 }
 
 const RESET_ELIGIBLE_CODES: ReadonlySet<string> = new Set(RESET_ELIGIBLE_CODE_VALUES);

package/src/codex/refresh.ts

@@ -4,6 +4,7 @@ import type { ComboCatalogOmission } from "./catalog/aggregation";
 import { CODEX_MODELS_CACHE_PATH } from "./paths";
 import { atomicWriteFile } from "../config";
 import type { OcxConfig } from "../types";
+import type { CodexCatalogSyncOptions } from "./catalog/sync";
 
 export interface CodexCatalogRefreshResult {
   added: number;
@@ -42,8 +43,9 @@ export function syncCodexModelsCacheFromCatalog(catalogPath: string): void {
 export async function refreshCodexModelCatalog(
   config: OcxConfig,
   deps: RefreshDeps = defaultDeps,
+  options?: CodexCatalogSyncOptions,
 ): Promise<CodexCatalogRefreshResult> {
-  const result = await deps.syncCatalogModels(config);
+  const result = await deps.syncCatalogModels(config, options);
   const catalogExists = deps.existsSync(result.path);
   const catalogWritten = result.catalogWritten === true;
   const comboOmissions = result.comboOmissions ?? [];
@@ -55,6 +57,6 @@ export async function refreshCodexModelCatalog(
   if (!catalogExists) {
     return { ...result, catalogExists, catalogWritten: false, cacheSynced: false, comboOmissions };
   }
-  const cacheSynced = deps.invalidateCodexModelsCache();
+  const cacheSynced = deps.invalidateCodexModelsCache(options);
   return { ...result, catalogExists, catalogWritten, cacheSynced, comboOmissions };
 }

package/src/codex/sync.ts

@@ -7,10 +7,15 @@ import { collectOrcaCodexHomeDiagnostic } from "./home";
 import { summarizeComboCatalogOmissions, type ComboCatalogOmission } from "./catalog/aggregation";
 import { shouldSyncCodexOnStart } from "./desired-state";
 import { admitCodexWrite, type CodexAdmission } from "./admission";
+import type { CodexCatalogSyncOptions } from "./catalog/sync";
 
 export interface CodexSyncResult {
-  /** `skipped` is policy truth, never evidence that Codex was written. */
-  status: "applied" | "skipped" | "refused";
+  /**
+   * `skipped` is policy truth, never evidence that Codex was written.
+   * `catalog-only` means an explicit sync refreshed the catalog/cache while
+   * Codex injection stayed OFF; config and history were not touched.
+   */
+  status: "applied" | "skipped" | "catalog-only" | "refused";
   ok: boolean;
   skippedReason?: "desired_disabled";
   /** Present when unattended convergence refused another service's native home. */
@@ -28,6 +33,17 @@ export interface CodexSyncResult {
   projectConfigGrouped?: { path: string; issues: string[]; bypass: string }[];
 }
 
+export interface CodexSyncOptions {
+  /**
+   * Explicit `ocx sync` is also the refresh path for side profiles that consume
+   * the OpenCodex catalog without injection. When set, the sync still refreshes
+   * the catalog and models cache even if the Codex integration toggle is OFF or
+   * an external `model_provider` owns config.toml. Config/history injection is
+   * skipped in those cases, so the behavior is harmless to a native home.
+   */
+  catalogEvenWhenNotInjected?: boolean;
+}
+
 type CodexSyncAdmission = Extract<CodexAdmission, { kind: "refused" }> | { readonly kind: "admitted" };
 
 interface CodexSyncDeps {
@@ -62,12 +78,15 @@ export async function syncModelsToCodex(
   config: OcxConfig = loadConfig(),
   log: Pick<Console, "log" | "error"> | null = console,
   deps: CodexSyncDeps = defaultDeps,
+  options: CodexSyncOptions = {},
 ): Promise<CodexSyncResult> {
   // `config` can be the server's startup object. The decision, however, is a
   // durable user switch and must be read again at this production boundary: a
   // PUT OFF while provider discovery is in flight cannot be allowed to commit
   // through an older captured object.
-  if (!shouldSyncCodexOnStart(loadConfig())) {
+  const desiredDisabled = !shouldSyncCodexOnStart(loadConfig());
+  const catalogEvenWhenNotInjected = options.catalogEvenWhenNotInjected === true;
+  if (desiredDisabled && !catalogEvenWhenNotInjected) {
     return {
       status: "skipped",
       skippedReason: "desired_disabled",
@@ -99,7 +118,44 @@ export async function syncModelsToCodex(
   }
   const p = port ?? config.port ?? 10100;
   const externalProvider = (deps.currentExternalCodexModelProvider ?? currentExternalCodexModelProvider)();
+
+  if (desiredDisabled && catalogEvenWhenNotInjected) {
+    // Explicit `ocx sync` with the integration OFF: refresh the catalog/cache so
+    // side profiles that route to the proxy keep their model list current, but
+    // never touch config, journal, or history.
+    applyProxyEnv(config);
+    const refreshed = await refreshCatalogForSync(config, deps, { allowWhenDesiredDisabled: true }, log);
+    const message = refreshed.catalogWritten || refreshed.cacheSynced
+      ? "Codex integration is OFF; catalog and models cache refreshed, Codex config untouched."
+      : "Codex integration is OFF; catalog refresh skipped, Codex config untouched.";
+    return {
+      status: "catalog-only",
+      ok: true,
+      ...refreshed,
+      message,
+      ...(refreshed.comboOmissions.length > 0 ? { comboOmissions: refreshed.comboOmissions } : {}),
+    };
+  }
+
   if (externalProvider) {
+    if (catalogEvenWhenNotInjected) {
+      // External providers own config.toml, and the injector removes the OpenCodex
+      // journal for external providers (inject.ts). This explicit catalog-only sync
+      // must not touch config, journal, or history, so refresh the catalog/cache and
+      // return without injection.
+      applyProxyEnv(config);
+      const refreshed = await refreshCatalogForSync(config, deps, undefined, log);
+      const message = refreshed.catalogWritten || refreshed.cacheSynced
+        ? "External provider owns config.toml; catalog and models cache refreshed, Codex config/journal untouched."
+        : "External provider owns config.toml; catalog refresh skipped, Codex config/journal untouched.";
+      return {
+        status: "catalog-only",
+        ok: true,
+        ...refreshed,
+        message,
+        ...(refreshed.comboOmissions.length > 0 ? { comboOmissions: refreshed.comboOmissions } : {}),
+      };
+    }
     const result = await deps.injectCodexConfig(p, config, {});
     if (result.success) log?.log(result.message);
     else log?.error(result.message);
@@ -214,3 +270,50 @@ export async function syncModelsToCodex(
     } : {}),
   };
 }
+
+async function refreshCatalogForSync(
+  config: OcxConfig,
+  deps: CodexSyncDeps,
+  catalogOptions: CodexCatalogSyncOptions | undefined,
+  log: Pick<Console, "log" | "error"> | null,
+): Promise<{
+  added: number;
+  catalogPath: string | null;
+  catalogExists: boolean;
+  catalogWritten: boolean;
+  cacheSynced: boolean;
+  comboOmissions: ComboCatalogOmission[];
+  warning?: string;
+}> {
+  let added = 0;
+  let catalogPath: string | null = null;
+  let catalogExists = false;
+  let catalogWritten = false;
+  let cacheSynced = false;
+  let warning: string | undefined;
+  let comboOmissions: ComboCatalogOmission[] = [];
+  try {
+    const cat = await deps.refreshCodexModelCatalog(config, undefined, catalogOptions);
+    added = cat.added;
+    catalogExists = cat.catalogExists;
+    catalogWritten = cat.catalogWritten;
+    cacheSynced = cat.cacheSynced;
+    catalogPath = cat.catalogExists ? cat.path : null;
+    comboOmissions = cat.comboOmissions ?? [];
+    if (cat.added > 0) {
+      log?.log(`   + ${cat.added} models appended to Codex catalog (${cat.path})`);
+    } else if (!cat.catalogExists) {
+      warning = "catalog sync skipped: no Codex catalog source found; keeping Codex's native catalog.";
+      log?.error(warning);
+    }
+    if (comboOmissions.length > 0) {
+      const summary = summarizeComboCatalogOmissions(comboOmissions);
+      log?.error(summary);
+      warning = warning ? `${warning} ${summary}` : summary;
+    }
+  } catch (e) {
+    warning = `catalog sync skipped: ${e instanceof Error ? e.message : String(e)}`;
+    log?.error(warning);
+  }
+  return { added, catalogPath, catalogExists, catalogWritten, cacheSynced, comboOmissions, ...(warning ? { warning } : {}) };
+}