@bitkyc08/opencodex 2.6.17 → 2.6.18

package/src/codex-catalog.ts

@@ -1,17 +1,19 @@
 import { execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
-import { copyFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, realpathSync } from "node:fs";
 import { delimiter, dirname, join, resolve } from "node:path";
-import { atomicWriteFile, getConfigDir, websocketsEnabled } from "./config";
+import { atomicWriteFile, expandUserPath, getConfigDir, websocketsEnabled } from "./config";
 import { CODEX_CONFIG_PATH, CODEX_MODELS_CACHE_PATH, DEFAULT_CATALOG_PATH, readRootTomlString, resolveCodexConfigPath } from "./codex-paths";
-import { DEFAULT_MODEL_CACHE_TTL_MS, getFreshCached, getStaleCached, setCached } from "./model-cache";
+import { DEFAULT_MODEL_CACHE_TTL_MS, getFreshCached, getStaleCached, isModelsFetchCoolingDown, markModelsFetchFailure, setCached } from "./model-cache";
 import { buildModelsRequest, resolveModelsAuthToken } from "./oauth/index";
+import { effectiveGoogleMode } from "./providers/registry";
 import type { OcxConfig, OcxProviderConfig } from "./types";
 import { CODEX_REASONING_LEVELS, configuredReasoningEfforts, modelRecordValue, sanitizeCodexReasoningEfforts } from "./reasoning-effort";
 import { getJawcodeModelMetadata, getJawcodeModelMetadataCaseInsensitive, listJawcodeModelMetadata, resolveJawcodeProvider } from "./generated/jawcode-model-metadata";
 import { shouldCaseFoldMetadataModelId } from "./providers/derive";
 import { applyProviderContextCap, providerContextCap } from "./provider-context-cap";
 import { CODEX_GPT5_IDENTITY_LINE } from "./adapters/identity";
+import { fetchCursorUsableModels } from "./adapters/cursor/live-models";
 
 const BUNDLED_CATALOG_CACHE_MS = 60_000;
 let bundledCatalogCache: { expiresAt: number; value: RawCatalog | null } | null = null;
@@ -32,8 +34,39 @@ function samePath(a: string, b: string): boolean {
   return process.platform === "win32" ? left.toLowerCase() === right.toLowerCase() : left === right;
 }
 
+function activeCodexHome(): string | null {
+  const raw = process.env.CODEX_HOME?.trim();
+  if (!raw) return null;
+  const path = resolve(expandUserPath(raw));
+  try {
+    return realpathSync.native(path);
+  } catch {
+    return path;
+  }
+}
+
+function activeCodexConfigPath(): string {
+  const home = activeCodexHome();
+  return home ? join(home, "config.toml") : CODEX_CONFIG_PATH;
+}
+
+function activeDefaultCatalogPath(): string {
+  const home = activeCodexHome();
+  return home ? join(home, "opencodex-catalog.json") : DEFAULT_CATALOG_PATH;
+}
+
+function activeCodexModelsCachePath(): string {
+  const home = activeCodexHome();
+  return home ? join(home, "models_cache.json") : CODEX_MODELS_CACHE_PATH;
+}
+
+function resolveActiveCodexConfigPath(path: string): string {
+  const home = activeCodexHome();
+  return home ? resolve(home, path) : resolveCodexConfigPath(path);
+}
+
 function isDefaultCatalogPath(path: string): boolean {
-  return samePath(path, DEFAULT_CATALOG_PATH);
+  return samePath(path, activeDefaultCatalogPath());
 }
 
 /**
@@ -71,6 +104,7 @@ function isUnsupportedOpenAiNativeSlug(slug: string): boolean {
 const NATIVE_OPENAI_CONTEXT_OVERRIDES: Record<string, { contextWindow?: number; maxContextWindow?: number }> = {
   "gpt-5.5": { contextWindow: 272_000, maxContextWindow: 272_000 },
   "gpt-5.4": { maxContextWindow: 1_000_000 },
+  "gpt-5.3-codex-spark": { contextWindow: 128_000, maxContextWindow: 128_000 },
 };
 
 /**
@@ -121,16 +155,22 @@ export function isMediaGenerationModelId(id: string): boolean {
   return MEDIA_GEN_ID_RE.test(id);
 }
 
+function shouldExposeRoutedModel(model: CatalogModel): boolean {
+  if (model.provider === "cursor" && model.id === "gemini-3-pro-image-preview") return true;
+  return !isMediaGenerationModelId(model.id);
+}
+
 /** Resolve the `model_catalog_json` path from Codex config.toml, else the default. */
 export function readCodexCatalogPath(): string {
   try {
-    if (existsSync(CODEX_CONFIG_PATH)) {
-      const toml = readFileSync(CODEX_CONFIG_PATH, "utf-8");
+    const configPath = activeCodexConfigPath();
+    if (existsSync(configPath)) {
+      const toml = readFileSync(configPath, "utf-8");
       const path = readRootTomlString(toml, "model_catalog_json");
-      if (path) return resolveCodexConfigPath(path);
+      if (path) return resolveActiveCodexConfigPath(path);
     }
   } catch { /* ignore */ }
-  return DEFAULT_CATALOG_PATH;
+  return activeDefaultCatalogPath();
 }
 
 function parseCatalogJson(raw: string): RawCatalog | null {
@@ -237,7 +277,9 @@ export function normalizeRoutedCatalogEntry(entry: RawEntry): RawEntry {
   // runs through native gpt-5.4-mini, so image search is available and verbalized for text-only models.
   entry.web_search_tool_type = "text_and_image";
   entry.supports_search_tool = true;
-  entry.supports_parallel_tool_calls = false;
+  // 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.
+  entry.supports_parallel_tool_calls = typeof entry.slug === "string" && entry.slug.startsWith("cursor/");
   return ensureStrictCatalogFields(entry);
 }
 
@@ -270,6 +312,7 @@ type ExecFile = (
     stdio: ["ignore", "pipe", "ignore"];
     timeout: number;
     windowsHide: boolean;
+    shell?: boolean;
   },
 ) => string;
 
@@ -318,13 +361,33 @@ function codexShimCommandCandidates(): string[] {
   }
 }
 
+/**
+ * `.cmd`/`.bat` launchers (npm's `codex.cmd`) cannot be spawned shell-less — Node ≥18.20
+ * and Bun refuse with EINVAL (CVE-2024-27980 hardening), which the probe loop silently
+ * swallowed, so npm-only Codex installs never loaded the bundled catalog on Windows.
+ * Route those through the shell (repo convention — see src/update.ts, bin/ocx.mjs) and
+ * pre-quote the path: shell:true joins file+args verbatim, so an unquoted path with
+ * spaces (`C:\Users\John Doe\...`) would split. Windows paths cannot contain `"`.
+ */
+export function codexExecInvocation(
+  command: string,
+  platform: NodeJS.Platform = process.platform,
+): { file: string; shell: boolean } {
+  if (platform === "win32" && /\.(cmd|bat)$/i.test(command)) {
+    return { file: `"${command.replace(/"/g, "")}"`, shell: true };
+  }
+  return { file: command, shell: false };
+}
+
 function runCodexDebugModels(command: string, execFile: ExecFile): string {
   const args = ["debug", "models", "--bundled"];
-  return execFile(command, args, {
+  const invocation = codexExecInvocation(command);
+  return execFile(invocation.file, args, {
     encoding: "utf8" as const,
     stdio: ["ignore", "pipe", "ignore"] as ["ignore", "pipe", "ignore"],
     timeout: 10_000,
     windowsHide: true,
+    shell: invocation.shell,
   });
 }
 
@@ -367,7 +430,7 @@ function loadCatalogForSync(path: string): RawCatalog | null {
   if (catalog && findNativeTemplate(catalog)) return catalog;
   return readCatalog(catalogBackupPathFor(path))
     ?? (isDefaultCatalogPath(path) ? readCatalog(legacyCatalogBackupPath()) : null)
-    ?? readCatalog(CODEX_MODELS_CACHE_PATH)
+    ?? readCatalog(activeCodexModelsCachePath())
     ?? materializeBundledCodexCatalog(path)
     ?? catalog;
 }
@@ -376,7 +439,7 @@ function readCurrentCatalogOrCache(): RawCatalog | null {
   const path = readCodexCatalogPath();
   return (isDefaultCatalogPath(path) ? loadBundledCodexCatalog() : null)
     ?? readCatalog(path)
-    ?? readCatalog(CODEX_MODELS_CACHE_PATH);
+    ?? readCatalog(activeCodexModelsCachePath());
 }
 
 /**
@@ -388,7 +451,7 @@ export function loadCatalogTemplate(): RawEntry | null {
   const catalogPath = readCodexCatalogPath();
   const native = findNativeTemplate(readCatalog(catalogPath))
     ?? findNativeTemplate(readCatalogBackup(catalogPath))
-    ?? findNativeTemplate(readCatalog(CODEX_MODELS_CACHE_PATH))
+    ?? findNativeTemplate(readCatalog(activeCodexModelsCachePath()))
     ?? findNativeTemplate(loadBundledCodexCatalog());
   return native ? JSON.parse(JSON.stringify(native)) : null;
 }
@@ -585,6 +648,25 @@ type ProviderModelsApiItem = {
   };
 };
 
+/** Generative Language API `models.list` item (`{ models: [...] }`, not OpenAI's `{ data }`). */
+type GoogleModelsApiModel = {
+  name?: string;
+  inputTokenLimit?: number;
+  supportedGenerationMethods?: string[];
+};
+
+function googleModelsToApiItems(models: GoogleModelsApiModel[]): ProviderModelsApiItem[] {
+  return models
+    // Keep chat-capable models only; a model missing the field stays (defensive).
+    .filter(m => m.supportedGenerationMethods?.includes("generateContent") ?? true)
+    .map(m => ({
+      id: (m.name ?? "").replace(/^models\//, ""),
+      owned_by: "google",
+      ...(typeof m.inputTokenLimit === "number" && m.inputTokenLimit > 0 ? { context_length: m.inputTokenLimit } : {}),
+    }))
+    .filter(m => m.id.length > 0);
+}
+
 function configuredContextWindow(prov: OcxProviderConfig, id: string): number | undefined {
   const configured = modelRecordValue(prov.modelContextWindows, id) ?? prov.contextWindow;
   return typeof configured === "number" && configured > 0 ? configured : undefined;
@@ -668,26 +750,54 @@ function catalogHintsFromModelsApiItem(providerName: string, item: ProviderModel
 async function fetchProviderModels(name: string, prov: OcxProviderConfig, ttlMs: number, contextCap?: number): Promise<CatalogModel[]> {
   if (prov.authMode === "forward") return []; // ChatGPT backend has no /models
   const apiKey = await resolveModelsAuthToken(name, prov);
-  if (prov.authMode === "oauth" && !apiKey) return []; // not logged in → skip
   const configured: CatalogModel[] = (prov.models ?? []).map(id => ({
     id,
     provider: name,
     ...catalogHintsFromProviderConfig(name, prov, id, contextCap),
   }));
+  if (prov.adapter === "cursor") {
+    if (prov.liveModels === false || !apiKey) return configured;
+    // Cursor uses a bespoke GetUsableModels RPC (not /models), returning the full effort-suffixed
+    // variants this PLAN can use. Keep the base-model UX (the request builder appends the effort
+    // suffix) but filter the static seed to the bases the account actually has — so models not on the
+    // plan (e.g. claude-fable-5) drop out instead of failing ERROR_BAD_MODEL_NAME. Fall back to the seed.
+    const cachedCursor = getFreshCached(name, ttlMs);
+    if (cachedCursor) return applyConfigHintsToCachedModels(name, prov, cachedCursor);
+    const liveIds = await fetchCursorUsableModels({ apiKey, baseUrl: prov.baseUrl });
+    if (liveIds) {
+      const available = configured.filter(m => liveIds.some(id => id === m.id || id.startsWith(`${m.id}-`)));
+      const result = available.length > 0 ? available : configured;
+      setCached(name, result);
+      return result;
+    }
+    const staleCursor = getStaleCached(name);
+    return staleCursor ? applyConfigHintsToCachedModels(name, prov, staleCursor) : configured;
+  }
+  if (prov.authMode === "oauth" && !apiKey) return []; // not logged in → skip
   if (prov.liveModels === false) {
     return configured;
   }
   const fresh = getFreshCached(name, ttlMs);
   if (fresh) return applyConfigHintsToCachedModels(name, prov, fresh, contextCap); // dedups Codex's frequent /v1/models polling within the TTL
-  const { url, headers } = buildModelsRequest(prov, apiKey);
+  if (isModelsFetchCoolingDown(name)) {
+    // A recently-failed provider (unreachable API, missing proxy, bad key) must not re-pay the
+    // fetch timeout on every catalog poll — the dashboard polls this path per page load.
+    const stale = getStaleCached(name);
+    return stale ? applyConfigHintsToCachedModels(name, prov, stale, contextCap) : configured;
+  }
+  const { url, headers } = buildModelsRequest(prov, apiKey, name);
   try {
     const res = await fetch(url, { headers, signal: AbortSignal.timeout(8000) });
     if (!res.ok) {
+      markModelsFetchFailure(name);
       const stale = getStaleCached(name);
       return stale ? applyConfigHintsToCachedModels(name, prov, stale, contextCap) : configured;
     }
-    const json = await res.json() as { data?: ProviderModelsApiItem[] };
-    const live = (json.data ?? []).map(m => applyProviderConfigHints(name, prov, {
+    const json = await res.json() as { data?: ProviderModelsApiItem[]; models?: GoogleModelsApiModel[] };
+    const items: ProviderModelsApiItem[] = effectiveGoogleMode(name, prov) === "ai-studio" && Array.isArray(json.models)
+      ? googleModelsToApiItems(json.models)
+      : (json.data ?? []);
+    const live = items.map(m => applyProviderConfigHints(name, prov, {
       id: m.id,
       provider: name,
       owned_by: m.owned_by,
@@ -699,6 +809,7 @@ async function fetchProviderModels(name: string, prov: OcxProviderConfig, ttlMs:
     setCached(name, merged);
     return merged;
   } catch {
+    markModelsFetchFailure(name);
     const stale = getStaleCached(name);
     return stale ? applyConfigHintsToCachedModels(name, prov, stale, contextCap) : configured;
   }
@@ -717,9 +828,10 @@ export async function gatherRoutedModels(config: OcxConfig): Promise<CatalogMode
     activeProviders.map(([name, prov]) => fetchProviderModels(name, prov, ttlMs, providerContextCap(config, name))),
   );
   const all = augmentRoutedModelsWithJawcodeMetadata(lists.flat(), activeProviders.map(([name]) => name), config.providers, config)
-    // Drop image/video generation models (e.g. Grok image/video) — they are not usable by Codex and
-    // must not surface in the dashboard, /v1/models, or the routed catalog. Single choke point.
-    .filter(m => !isMediaGenerationModelId(m.id));
+    // Drop image/video generation models (e.g. Grok image/video) by default. Cursor's static catalog
+    // intentionally mirrors Cursor's public model table, including Gemini image preview, so the
+    // exposure decision goes through shouldExposeRoutedModel (single choke point).
+    .filter(shouldExposeRoutedModel);
   all.sort((a, b) => (a.provider === b.provider ? a.id.localeCompare(b.id) : a.provider.localeCompare(b.provider)));
   return all;
 }
@@ -775,6 +887,77 @@ export function orderForSubagents(goModels: CatalogModel[], featured?: string[])
   });
 }
 
+export function mergeCatalogEntriesForSync(
+  catalogModels: RawEntry[],
+  routedEntries: RawEntry[],
+  baseline: Map<string, number>,
+  featured: string[],
+  wsEnabled: boolean,
+  goIds: Set<string> = new Set(),
+  template: RawEntry | null = null,
+  gatheredProviderNames: Set<string> = new Set(routedEntries.flatMap(entry => {
+    const slug = typeof entry.slug === "string" ? entry.slug : "";
+    const slash = slug.indexOf("/");
+    return slash > 0 ? [slug.slice(0, slash)] : [];
+  })),
+): RawEntry[] {
+  const rank = new Map(featured.map((slug, i) => [slug, i] as const));
+  const native = catalogModels
+    .filter(m => typeof m.slug === "string"
+      && !(m.slug as string).includes("/")
+      && !goIds.has(m.slug as string)
+      && !isUnsupportedOpenAiNativeSlug(m.slug as string))
+    .map(m => {
+      const slug = m.slug as string;
+      // Featured models rank first (rank order); non-featured natives are pushed below the featured
+      // block when any model is featured, else keep their pristine baseline priority.
+      const baselinePriority = baseline.get(slug) ?? (m.priority as number);
+      const priority = rank.has(slug)
+        ? rank.get(slug)!
+        : featured.length > 0
+          ? Math.max(typeof baselinePriority === "number" ? baselinePriority : 9, featured.length + 100)
+          : baselinePriority;
+      return normalizeServiceTiers({ ...m, priority });
+    });
+
+  // Backfill any native OpenAI slug that the on-disk catalog is missing (e.g. gpt-5.5), so a
+  // routed provider exposing the same id can never delete the native OpenAI/Codex base row.
+  const nativeSlugs = new Set(native.flatMap(m => typeof m.slug === "string" ? [m.slug] : []));
+  for (const slug of nativeOpenAiSlugs()) {
+    if (nativeSlugs.has(slug)) continue;
+    nativeSlugs.add(slug);
+    const priority = rank.has(slug)
+      ? rank.get(slug)!
+      : featured.length > 0
+        ? featured.length + 100
+        : 9;
+    native.push(deriveEntry(template ? JSON.parse(JSON.stringify(template)) : null, slug, "OpenAI native model (Codex OAuth passthrough).", priority));
+  }
+
+  let finalRoutedEntries = routedEntries;
+  if (routedEntries.length === 0 && catalogModels.some(m => typeof m.slug === "string" && (m.slug as string).includes("/"))) {
+    finalRoutedEntries = catalogModels.filter(m => typeof m.slug === "string" && (m.slug as string).includes("/"));
+    console.warn(`[opencodex] catalog sync: routed model fetch returned empty; preserving ${finalRoutedEntries.length} existing routed entr${finalRoutedEntries.length === 1 ? "y" : "ies"} on disk.`);
+  } else {
+    const freshSlugs = new Set(routedEntries.flatMap(entry => typeof entry.slug === "string" ? [entry.slug] : []));
+    const preservedForeignRouted = catalogModels.filter(m => {
+      if (typeof m.slug !== "string" || !m.slug.includes("/")) return false;
+      const provider = m.slug.slice(0, m.slug.indexOf("/"));
+      return !gatheredProviderNames.has(provider) && !freshSlugs.has(m.slug);
+    });
+    finalRoutedEntries = [...routedEntries, ...preservedForeignRouted];
+  }
+
+  return [...native, ...finalRoutedEntries].map(m => {
+    const normalized = normalizeServiceTiers(m);
+    applyNativeOpenAiContextOverride(normalized);
+    const e = ensureStrictCatalogFields(normalized);
+    if (wsEnabled) e.supports_websockets = true;
+    else delete e.supports_websockets;
+    return e;
+  });
+}
+
 /**
  * Merge namespaced routed-model entries into the on-disk Codex catalog.
  * Idempotent + non-destructive:
@@ -803,64 +986,23 @@ export async function syncCatalogModels(config: OcxConfig): Promise<{ added: num
   const disabled = new Set(config.disabledModels ?? []);
   const enabledGo = goModels.filter(m => !disabled.has(`${m.provider}/${m.id}`));
   const featured = config.subagentModels ?? [];
-  const rank = new Map(featured.map((slug, i) => [slug, i] as const));
   const orderedGoModels = orderForSubagents(enabledGo, featured); // stable tie-break among equal priorities
   const goEntries = buildCatalogEntries(template ? JSON.parse(JSON.stringify(template)) : null, [], orderedGoModels, featured, websocketsEnabled(config));
-  // Keep genuine native entries (gpt-*, codex-*) with their real per-model fields, but drop bare
-  // duplicates of routed models (replaced by namespaced entries) + any prior "/" entries. Re-derive
-  // each native's priority from the pristine baseline so featuring a native is reversible.
+  // Keep genuine native entries (gpt-*, codex-*) with their real per-model fields and append
+  // routed providers as namespaced slugs. Cursor and other adopted providers can expose model ids
+  // like `gpt-5.5`; those must not delete the native OpenAI/Codex base row.
   const baseline = readNativeBaseline(catalogPath);
   const goIds = new Set(enabledGo.map(m => m.id));
-  const native = (catalog.models ?? [])
-    .filter(m => typeof m.slug === "string"
-      && !(m.slug as string).includes("/")
-      && !goIds.has(m.slug as string)
-      // Gap B: drop legacy/internal OpenAI-family natives (gpt-5.2, gpt-5.3-codex,
-      // codex-auto-review, …) from the on-disk catalog too, matching the live /v1/models
-      // allowlist. Genuine user-added natives (non gpt-/codex- slugs) are preserved.
-      && !isUnsupportedOpenAiNativeSlug(m.slug as string))
-    .map(m => {
-      const slug = m.slug as string;
-      const baselinePriority = baseline.get(slug) ?? (m.priority as number);
-      const priority = rank.has(slug)
-        ? rank.get(slug)!
-        : featured.length > 0
-          ? Math.max(typeof baselinePriority === "number" ? baselinePriority : 9, featured.length + 100)
-          : baselinePriority;
-      return normalizeServiceTiers({ ...m, priority });
-    });
-  const nativeSlugs = new Set(native.flatMap(m => typeof m.slug === "string" ? [m.slug] : []));
-  for (const slug of nativeOpenAiSlugs()) {
-    if (nativeSlugs.has(slug)) continue;
-    nativeSlugs.add(slug);
-    const priority = rank.has(slug)
-      ? rank.get(slug)!
-      : featured.length > 0
-        ? featured.length + 100
-        : 9;
-    native.push(deriveEntry(template ? JSON.parse(JSON.stringify(template)) : null, slug, "OpenAI native model (Codex OAuth passthrough).", priority));
-  }
+  const gatheredProviderNames = new Set(
+    Object.entries(config.providers ?? {})
+      .filter(([, prov]) => prov.disabled !== true)
+      .map(([name]) => name),
+  );
   // Central WS capability override on the FINAL on-disk catalog (the file Codex reads). Applies to
   // native AND routed so the advertised flag matches the implemented endpoint (phase 120.4) and a
   // native template can never leak supports_websockets while the flag is off.
   const wsEnabled = websocketsEnabled(config);
-  // Gap A: never let a transient EMPTY routed fetch wipe routed entries that were on disk. If
-  // gatherRoutedModels returned nothing (provider down / flaky / cache miss) but the pre-sync
-  // catalog DID carry routed entries, preserve those prior routed entries instead of overwriting
-  // them with an empty set — otherwise the Codex picker silently loses kiro/opencode-go models.
-  let routedEntries = goEntries;
-  if (goEntries.length === 0 && catalogHasRoutedEntries(catalog)) {
-    routedEntries = (catalog.models ?? []).filter(m => typeof m.slug === "string" && (m.slug as string).includes("/"));
-    console.warn(`[opencodex] catalog sync: routed model fetch returned empty; preserving ${routedEntries.length} existing routed entr${routedEntries.length === 1 ? "y" : "ies"} on disk.`);
-  }
-  catalog.models = [...native, ...routedEntries].map(m => {
-    const normalized = normalizeServiceTiers(m);
-    applyNativeOpenAiContextOverride(normalized);
-    const e = ensureStrictCatalogFields(normalized);
-    if (wsEnabled) e.supports_websockets = true;
-    else delete e.supports_websockets;
-    return e;
-  });
+  catalog.models = mergeCatalogEntriesForSync(catalog.models ?? [], goEntries, baseline, featured, wsEnabled, goIds, template, gatheredProviderNames);
 
   atomicWriteFile(catalogPath, JSON.stringify(catalog, null, 2) + "\n");
   return { added: goEntries.length, path: catalogPath };
@@ -915,6 +1057,6 @@ export function invalidateCodexModelsCache(): void {
       client_version: "0.0.0",
       models,
     };
-    atomicWriteFile(CODEX_MODELS_CACHE_PATH, JSON.stringify(wrapper, null, 2) + "\n");
+    atomicWriteFile(activeCodexModelsCachePath(), JSON.stringify(wrapper, null, 2) + "\n");
   } catch { /* best-effort */ }
 }

package/src/codex-history-provider.ts

@@ -144,6 +144,8 @@ export interface CodexHistorySyncResult {
   rows: number;
   files: number;
   ejectedRows?: number;
+  /** Set when a lock/busy error survived retries and the sync was SKIPPED, not empty. */
+  failed?: true;
 }
 
 interface ThreadRow {
@@ -351,7 +353,7 @@ function ejectRemainingOpencodexHistory(db: Database): { rows: number; files: nu
   return { rows: rows.length, files };
 }
 
-function isRecoverableHistoryError(error: unknown): boolean {
+export function isRecoverableHistoryError(error: unknown): boolean {
   const code = typeof error === "object" && error && "code" in error ? String((error as { code?: unknown }).code) : "";
   const message = error instanceof Error ? error.message.toLowerCase() : String(error).toLowerCase();
   return code === "SQLITE_BUSY"
@@ -366,15 +368,33 @@ function isRecoverableHistoryError(error: unknown): boolean {
     || message.includes("permission denied");
 }
 
-export function syncCodexHistoryProvider(provider: CodexHistoryProvider, stateDbPath = STATE_DB_PATH, backupPath = HISTORY_BACKUP_PATH): CodexHistorySyncResult {
-  try {
-    return syncCodexHistoryProviderUnsafe(provider, stateDbPath, backupPath);
-  } catch (error) {
-    if (isRecoverableHistoryError(error)) return { rows: 0, files: 0 };
-    throw error;
+const HISTORY_RETRY_DELAY_MS = 500;
+
+/**
+ * Run a history mutation with one retry across recoverable lock/busy errors (the app's own
+ * connection holds `state_5.sqlite` in WAL with a 5 s busy_timeout; a transient writer
+ * usually clears within that window). Returns null when both attempts hit a recoverable
+ * error — callers surface that as `failed: true` instead of a silent no-op. Hard errors
+ * (corruption, programming bugs) still throw.
+ */
+export function withHistoryRetry<T>(fn: () => T, io: { sleepFn?: (ms: number) => void } = {}): T | null {
+  const sleepFn = io.sleepFn ?? Bun.sleepSync;
+  for (let attempt = 0; ; attempt++) {
+    try {
+      return fn();
+    } catch (error) {
+      if (!isRecoverableHistoryError(error)) throw error;
+      if (attempt >= 1) return null;
+      try { sleepFn(HISTORY_RETRY_DELAY_MS); } catch { /* sleep is best-effort */ }
+    }
   }
 }
 
+export function syncCodexHistoryProvider(provider: CodexHistoryProvider, stateDbPath = STATE_DB_PATH, backupPath = HISTORY_BACKUP_PATH): CodexHistorySyncResult {
+  return withHistoryRetry(() => syncCodexHistoryProviderUnsafe(provider, stateDbPath, backupPath))
+    ?? { rows: 0, files: 0, failed: true };
+}
+
 function syncCodexHistoryProviderUnsafe(provider: CodexHistoryProvider, stateDbPath: string, backupPath: string): CodexHistorySyncResult {
   if (!existsSync(stateDbPath)) return { rows: 0, files: 0 };
   if (provider === "openai") return restoreCodexHistoryProvider(stateDbPath, backupPath);
@@ -495,17 +515,14 @@ function restoreCodexHistoryProvider(stateDbPath: string, backupPath: string): C
   }
 }
 
-export function restoreLegacyOpenaiHistory(stateDbPath = STATE_DB_PATH): { rows: number; files: number } {
-  try {
-    if (!existsSync(stateDbPath)) return { rows: 0, files: 0 };
+export function restoreLegacyOpenaiHistory(stateDbPath = STATE_DB_PATH): { rows: number; files: number; failed?: true } {
+  if (!existsSync(stateDbPath)) return { rows: 0, files: 0 };
+  return withHistoryRetry(() => {
     const db = openStateDb(stateDbPath);
     try {
       return ejectRemainingOpencodexHistory(db);
     } finally {
       db.close();
     }
-  } catch (error) {
-    if (isRecoverableHistoryError(error)) return { rows: 0, files: 0 };
-    throw error;
-  }
+  }) ?? { rows: 0, files: 0, failed: true };
 }

package/src/codex-inject.ts

@@ -32,7 +32,11 @@ function isLoopbackHostname(hostname: string | undefined): boolean {
 
 function providerBaseHost(hostname: string | undefined): string {
   const trimmed = (hostname ?? "127.0.0.1").trim();
-  if (isLoopbackHostname(trimmed) || trimmed === "0.0.0.0" || trimmed === "::" || trimmed === "[::]") return "localhost";
+  const lower = trimmed.toLowerCase();
+  // Match what the server actually binds. Writing "localhost" while binding IPv4-only
+  // 127.0.0.1 breaks on Windows, where localhost commonly resolves to ::1 first.
+  if (lower === "::1" || lower === "[::1]") return "[::1]";
+  if (isLoopbackHostname(trimmed) || trimmed === "0.0.0.0" || trimmed === "::" || trimmed === "[::]") return "127.0.0.1";
   if (trimmed.startsWith("[") && trimmed.endsWith("]")) return trimmed;
   return trimmed.includes(":") ? `[${trimmed}]` : trimmed;
 }
@@ -283,9 +287,11 @@ export async function injectCodexConfig(port: number, config?: OcxConfig, option
   const catalogMessage = catalogPath
     ? `  Codex model catalog: ${catalogPath}\n`
     : `  Codex model catalog not injected because no opencodex catalog file exists yet.\n`;
-  const historyMessage = config?.syncResumeHistory !== false
-    ? `  Codex resume history: ${history.rows} thread(s) made visible for opencodex; originals backed up for restore.\n`
-    : `  Codex resume history: left unchanged (syncResumeHistory=false).\n`;
+  const historyMessage = config?.syncResumeHistory === false
+    ? `  Codex resume history: left unchanged (syncResumeHistory=false).\n`
+    : history.failed
+      ? `  ⚠️ Codex resume history sync SKIPPED: the history DB is locked (Codex app/IDE open?). Close it and rerun 'ocx start'.\n`
+      : `  Codex resume history: ${history.rows} thread(s) made visible for opencodex; originals backed up for restore.\n`;
   return {
     success: true,
     message: `Injected opencodex as default provider into Codex config.\n` +
@@ -376,11 +382,13 @@ export function restoreNativeCodex(): { success: boolean; message: string } {
   const msg = cat.removed > 0
     ? `${cfg.message} Catalog restored to ${cat.kept} native model(s) (dropped ${cat.removed} proxy-routed).`
     : cfg.message;
-  const historyMsg = history.rows > 0
-    ? ` Resume history restored from opencodex backup (${history.rows} thread(s)).`
-    : history.ejectedRows
-      ? ` ${history.ejectedRows} opencodex history thread(s) were ejected to openai so native Codex can resume them.`
-      : "";
+  const historyMsg = history.failed
+    ? ` ⚠️ Codex resume history could NOT be restored — the Codex app appears to be holding the history DB. Close the Codex app/IDE and run 'ocx stop' again; until then routed threads stay hidden in the native app.`
+    : history.rows > 0
+      ? ` Resume history restored from opencodex backup (${history.rows} thread(s)).`
+      : history.ejectedRows
+        ? ` ${history.ejectedRows} opencodex history thread(s) were ejected to openai so native Codex can resume them.`
+        : "";
   return { success: cfg.success, message: `${msg}${historyMsg}` };
 }
 

package/src/codex-paths.ts

@@ -1,11 +1,12 @@
 import { realpathSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { isAbsolute, join, resolve } from "node:path";
+import { expandUserPath } from "./config";
 
 function resolveCodexHome(): string {
   const raw = process.env.CODEX_HOME?.trim();
   if (raw) {
-    const path = resolve(raw);
+    const path = resolve(expandUserPath(raw));
     let stat;
     try {
       stat = statSync(path);