@bitkyc08/opencodex 2.6.26-preview.20260705 → 2.6.28-preview.20260707

package/src/{codex-auth-api.ts → codex/auth-api.ts}

@@ -1,5 +1,5 @@
-import { loadConfig, saveConfig } from "./config";
-import { withCodexAccountLogLabel } from "./codex-account-label";
+import { loadConfig, saveConfig } from "../config";
+import { withCodexAccountLogLabel } from "./account-label";
 import {
   getCodexAccountCredential,
   getValidCodexToken,
@@ -7,12 +7,12 @@ import {
   CodexCredentialGenerationConflictError,
   CodexCredentialRefreshLockTimeoutError,
   TokenRefreshError,
-} from "./codex-account-store";
-import { deleteCodexAccount } from "./codex-account-lifecycle";
-import { checkAccountIdCollision, readCodexTokens } from "./codex-auth-collision";
-export { checkAccountIdCollision, getMainChatgptAccountId } from "./codex-auth-collision";
-export { clearAccountNeedsReauth, isAccountNeedsReauth, markAccountNeedsReauth } from "./codex-account-runtime-state";
-import { clearAccountNeedsReauth, isAccountNeedsReauth } from "./codex-account-runtime-state";
+} from "./account-store";
+import { deleteCodexAccount } from "./account-lifecycle";
+import { checkAccountIdCollision, readCodexTokens } from "./auth-collision";
+export { checkAccountIdCollision, getMainChatgptAccountId } from "./auth-collision";
+export { clearAccountNeedsReauth, isAccountNeedsReauth, markAccountNeedsReauth } from "./account-runtime-state";
+import { clearAccountNeedsReauth, isAccountNeedsReauth } from "./account-runtime-state";
 import {
   clearAccountQuota,
   getAccountQuota,
@@ -21,13 +21,13 @@ import {
   updateAccountQuota,
   type StoredAccountQuota,
   type WhamUsageResponse,
-} from "./codex-quota";
-export { clearAccountQuota, getAccountQuota, parseUsageQuota, updateAccountQuota } from "./codex-quota";
-import { extractAccountId, decodeJwtPayload } from "./oauth/chatgpt";
-import { MAIN_CODEX_ACCOUNT_ID, setMainAccountPlan } from "./codex-main-account";
-import { maskEmail } from "./privacy";
-export { maskEmail } from "./privacy";
-import type { CodexAccount, OcxConfig } from "./types";
+} from "./quota";
+export { clearAccountQuota, getAccountQuota, parseUsageQuota, updateAccountQuota } from "./quota";
+import { extractAccountId, decodeJwtPayload } from "../oauth/chatgpt";
+import { MAIN_CODEX_ACCOUNT_ID, setMainAccountPlan } from "./main-account";
+import { maskEmail } from "../lib/privacy";
+export { maskEmail } from "../lib/privacy";
+import type { CodexAccount, OcxConfig } from "../types";
 
 function jsonResponse(data: unknown, status = 200): Response {
   return new Response(JSON.stringify(data), {
@@ -541,7 +541,7 @@ export async function handleCodexAuthAPI(
     }
     const flowId = `flow-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
     try {
-      const { startLoginFlow, getLoginStatus } = await import("./oauth/index");
+      const { startLoginFlow, getLoginStatus } = await import("../oauth");
       const result = await startLoginFlow("chatgpt", { forceLogin: true });
 
       (async () => {
@@ -550,7 +550,7 @@ export async function handleCodexAuthAPI(
           await new Promise(r => setTimeout(r, 2000));
           const st = getLoginStatus("chatgpt");
           if (st.done && st.loggedIn) {
-            const { getCredential } = await import("./oauth/store");
+            const { getCredential } = await import("../oauth/store");
             const cred = getCredential("chatgpt");
             if (cred) {
               const oauthAccountId = cred.accountId;
@@ -652,7 +652,7 @@ export async function handleCodexAuthAPI(
 
   if (url.pathname === "/api/codex-auth/login/cancel" && req.method === "POST") {
     const body = (await req.json().catch(() => ({}))) as { flowId?: string };
-    const { cancelLoginFlow } = await import("./oauth/index");
+    const { cancelLoginFlow } = await import("../oauth");
     const cancelled = cancelLoginFlow("chatgpt");
     expireCodexAuthFlow(body.flowId ?? null);
     return jsonResponse({ ok: true, cancelled });

package/src/{codex-auth-collision.ts → codex/auth-collision.ts}

@@ -1,9 +1,9 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import { getCodexAccountCredential } from "./codex-account-store";
-import { loadConfig } from "./config";
-import { resolveCodexHomeDir } from "./codex-home";
-import { extractAccountId } from "./oauth/chatgpt";
+import { getCodexAccountCredential } from "./account-store";
+import { loadConfig } from "../config";
+import { resolveCodexHomeDir } from "./home";
+import { extractAccountId } from "../oauth/chatgpt";
 
 export function readCodexTokens(): { access_token: string; account_id: string; id_token?: string } | null {
   try {

package/src/{codex-auth-context.ts → codex/auth-context.ts}

@@ -3,14 +3,14 @@ import {
   CodexCredentialRefreshLockTimeoutError,
   getValidCodexToken,
   isCodexAccountGenerationLive,
-} from "./codex-account-store";
-import { markAccountNeedsReauth } from "./codex-account-runtime-state";
-import { isCodexAccountUsable } from "./codex-account-usability";
-import { MAIN_CODEX_ACCOUNT_ID, getMainAccountToken } from "./codex-main-account";
-import { getCodexAccountCooldownUntil, resolveCodexAccountForThreadDetailed } from "./codex-routing";
-import { getAccountQuota } from "./codex-quota";
-import type { OcxConfig, OcxProviderConfig } from "./types";
-import { FORWARD_HEADERS } from "./adapters/openai-responses";
+} from "./account-store";
+import { markAccountNeedsReauth } from "./account-runtime-state";
+import { isCodexAccountUsable } from "./account-usability";
+import { MAIN_CODEX_ACCOUNT_ID, getMainAccountToken } from "./main-account";
+import { getCodexAccountCooldownUntil, resolveCodexAccountForThreadDetailed } from "./routing";
+import { getAccountQuota } from "./quota";
+import type { OcxConfig, OcxProviderConfig } from "../types";
+import { FORWARD_HEADERS } from "../adapters/openai-responses";
 
 export type CodexAuthContext =
   | { kind: "main"; accountId: null }
@@ -83,7 +83,7 @@ export async function resolveCodexAuthContext(headers: Headers, config: OcxConfi
   // blocks the current request, and the helper's single-flight guard collapses
   // repeated triggers into one pass.
   if (!getAccountQuota(accountId)) {
-    import("./codex-auth-api")
+    import("./auth-api")
       .then(({ primeCodexPoolQuotas }) => primeCodexPoolQuotas(config, "pre-route"))
       .catch(() => {});
   }

package/src/{codex-catalog.ts → codex/catalog.ts}

@@ -2,18 +2,19 @@ import { execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { copyFileSync, existsSync, mkdirSync, readFileSync, realpathSync } from "node:fs";
 import { delimiter, dirname, join, resolve } from "node:path";
-import { atomicWriteFile, expandUserPath, getConfigDir, websocketsEnabled } from "./config";
-import { CODEX_CONFIG_PATH, CODEX_MODELS_CACHE_PATH, DEFAULT_CATALOG_PATH, readRootTomlString, resolveCodexConfigPath } from "./codex-paths";
+import { atomicWriteFile, expandUserPath, getConfigDir, websocketsEnabled } from "../config";
+import { CODEX_CONFIG_PATH, CODEX_MODELS_CACHE_PATH, DEFAULT_CATALOG_PATH, readRootTomlString, resolveCodexConfigPath } from "./paths";
 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";
+import { buildModelsRequest, resolveModelsAuthToken } from "../oauth";
+import { effectiveGoogleMode } from "../providers/registry";
+import type { OcxConfig, OcxProviderConfig } from "../types";
+import { modelInList } from "../types";
+import { CODEX_REASONING_LEVELS, configuredReasoningEfforts, modelRecordValue, sanitizeCodexReasoningEfforts } from "../reasoning-effort";
+import { getJawcodeModelMetadata, getJawcodeModelMetadataCaseInsensitive, listJawcodeModelMetadata, resolveJawcodeProvider } from "../generated/jawcode-model-metadata";
+import { enrichProviderFromRegistry, shouldCaseFoldMetadataModelId } from "../providers/derive";
+import { applyProviderContextCap, providerContextCap } from "../providers/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;
@@ -103,7 +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.4": { contextWindow: 1_000_000, maxContextWindow: 1_000_000 },
   "gpt-5.3-codex-spark": { contextWindow: 128_000, maxContextWindow: 128_000 },
 };
 
@@ -273,13 +274,21 @@ export function normalizeRoutedCatalogEntry(entry: RawEntry): RawEntry {
   delete entry.service_tier;
   delete entry.service_tiers;
   delete entry.default_service_tier;
+  const isCursorEntry = typeof entry.slug === "string" && entry.slug.startsWith("cursor/");
   // Routed providers use opencodex sidecars and client-executed tool discovery. The sidecar
-  // 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;
+  // runs through native gpt-5.4-mini, so image search is available and verbalized for text-only
+  // models. EXCEPT cursor: its runTurn transport bypasses the web-search plan entirely and
+  // rejects server search queries — advertising the tool would make models call into a void.
+  if (isCursorEntry) {
+    delete entry.web_search_tool_type;
+    entry.supports_search_tool = false;
+  } else {
+    entry.web_search_tool_type = "text_and_image";
+    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.
-  entry.supports_parallel_tool_calls = typeof entry.slug === "string" && entry.slug.startsWith("cursor/");
+  entry.supports_parallel_tool_calls = isCursorEntry;
   return ensureStrictCatalogFields(entry);
 }
 
@@ -365,7 +374,7 @@ 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
+ * Route those through the shell (repo convention — see src/update/index.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 `"`.
  */
@@ -677,10 +686,18 @@ function configuredInputModalities(prov: OcxProviderConfig, id: string): string[
   return Array.isArray(modalities) && modalities.length > 0 ? [...modalities] : undefined;
 }
 
-function applyProviderConfigHints(name: string, prov: OcxProviderConfig, model: CatalogModel, providerCap?: number): CatalogModel {
+export function applyProviderConfigHints(name: string, prov: OcxProviderConfig, model: CatalogModel, providerCap?: number): CatalogModel {
   void name;
   const configuredCap = configuredContextWindow(prov, model.id);
-  const inputModalities = configuredInputModalities(prov, model.id);
+  let inputModalities = configuredInputModalities(prov, model.id);
+  // Vision-sidecar coverage: `noVisionModels` marks models whose images the PROXY describes
+  // (src/vision/index.ts). The catalog must still advertise image input for them — the Codex app
+  // gates attachments client-side on input_modalities, and a text-only entry would block images
+  // before the sidecar ever runs ("This model does not support image inputs").
+  if (modelInList(prov.noVisionModels, model.id)) {
+    const base = inputModalities ?? model.inputModalities ?? ["text"];
+    inputModalities = base.includes("image") ? [...base] : [...base, "image"];
+  }
   const reasoningEfforts = configuredReasoningEfforts(prov, model.id);
   const hinted = {
     ...model,
@@ -847,7 +864,19 @@ export function filterCatalogVisibleModels(
  */
 export async function gatherRoutedModels(config: OcxConfig): Promise<CatalogModel[]> {
   const ttlMs = config.modelCacheTtlMs ?? DEFAULT_MODEL_CACHE_TTL_MS;
-  const activeProviders = Object.entries(config.providers).filter(([, prov]) => prov.disabled !== true);
+  // Persisted provider entries can predate newer registry fields (noVisionModels,
+  // modelInputModalities, ...). The ROUTER merges registry seeds at request time
+  // (routedProviderConfig), so the proxy behaves correctly — the catalog listing must see the
+  // same merged view or its advertisements drift from actual proxy behavior (e.g. a
+  // vision-sidecar model advertised text-only, blocking image attachments app-side).
+  // Enrich a CLONE: hydrated defaults must never leak into the persisted config.
+  const activeProviders = Object.entries(config.providers)
+    .filter(([, prov]) => prov.disabled !== true)
+    .map(([name, prov]): [string, OcxProviderConfig] => {
+      const enriched = { ...prov };
+      enrichProviderFromRegistry(name, enriched);
+      return [name, enriched];
+    });
   const lists = await Promise.all(
     activeProviders.map(([name, prov]) => fetchProviderModels(name, prov, ttlMs, providerContextCap(config, name))),
   );

package/src/codex/history-migration-guardian.ts

@@ -0,0 +1,102 @@
+import { countPendingOpencodexHistory, migrateHistoryToOpenai } from "./history-provider";
+
+/**
+ * Daemon-side retry for the one-time Design-B history migration.
+ *
+ * Most upgrades run `ocx start` while the Codex app still holds `state_5.sqlite`,
+ * so the inject-time migration often fails on the FIRST start — exactly the moment
+ * every legacy thread is still tagged `opencodex` and invisible to the app. Instead
+ * of asking the user to close the app and rerun start, this guardian keeps retrying
+ * in the background until the migration lands.
+ *
+ * Design constraints (audit-driven):
+ * - Ticks use `{ attempts: 1 }`: no sleepSync inside the daemon event loop; the tick
+ *   cadence IS the retry. Worst case per tick is one sqlite busy wait.
+ * - Timers are unref'd so the guardian never keeps the process alive.
+ * - Started ONLY from `ocx start` (cli handleStart), never from injectCodexConfig —
+ *   `/api/sync` re-runs inject and must not double-start loops.
+ */
+
+export interface HistoryMigrationGuardianHandle {
+  stop(): void;
+}
+
+export interface HistoryMigrationGuardianDeps {
+  countFn?: typeof countPendingOpencodexHistory;
+  migrateFn?: () => ReturnType<typeof migrateHistoryToOpenai>;
+  log?: Pick<Console, "log">;
+  tickMs?: number;
+  maxTicks?: number;
+  /** Test hook: schedule fn after ms; return a cancel handle. Defaults to setTimeout. */
+  scheduleFn?: (fn: () => void, ms: number) => { cancel(): void };
+}
+
+const DEFAULT_TICK_MS = 60_000;
+const DEFAULT_MAX_TICKS = 60; // give up after ~an hour; doctor still surfaces the pending state
+
+function defaultSchedule(fn: () => void, ms: number): { cancel(): void } {
+  const timer = setTimeout(fn, ms);
+  if (typeof timer.unref === "function") timer.unref();
+  return { cancel: () => clearTimeout(timer) };
+}
+
+export function startHistoryMigrationGuardian(deps: HistoryMigrationGuardianDeps = {}): HistoryMigrationGuardianHandle {
+  const countFn = deps.countFn ?? countPendingOpencodexHistory;
+  const migrateFn = deps.migrateFn ?? (() => migrateHistoryToOpenai(undefined, undefined, { attempts: 1 }));
+  const log = deps.log ?? console;
+  const tickMs = deps.tickMs ?? DEFAULT_TICK_MS;
+  const maxTicks = deps.maxTicks ?? DEFAULT_MAX_TICKS;
+
+  let stopped = false;
+  let pending: { cancel(): void } | undefined;
+  let ticks = 0;
+
+  const schedule = () => {
+    if (stopped) return;
+    pending = (deps.scheduleFn ?? defaultSchedule)(tick, tickMs);
+  };
+
+  const tick = () => {
+    if (stopped) return;
+    ticks++;
+    try {
+      const count = countFn();
+      if (!count.failed && count.pendingRows === 0 && count.backupEntries === 0) {
+        stopped = true; // nothing left to migrate — normal steady state, no log noise
+        return;
+      }
+      // Locked probe or pending work: attempt one migration pass.
+      const result = migrateFn();
+      if (!result.failed) {
+        const moved = result.rows + (result.ejectedRows ?? 0);
+        if (moved > 0) {
+          log.log(`🩹 history-migration: ${moved} legacy opencodex thread(s) migrated back to openai.`);
+        }
+        // A "successful" zero-row migration can also mean the DB does not exist YET while a
+        // backup manifest still holds restore work (fresh reinstall race). Only stop when a
+        // re-count proves nothing is pending; otherwise keep ticking within the budget.
+        const after = countFn();
+        if (moved > 0 || (!after.failed && after.pendingRows === 0 && after.backupEntries === 0)) {
+          stopped = true;
+          return;
+        }
+      }
+    } catch {
+      /* hard errors are not retryable state — fall through to the tick budget */
+    }
+    if (ticks >= maxTicks) {
+      stopped = true;
+      log.log("⚠️ history-migration: Codex history DB stayed locked; legacy threads not yet migrated. Close the Codex app and run 'ocx sync' (or check 'ocx doctor').");
+      return;
+    }
+    schedule();
+  };
+
+  schedule();
+  return {
+    stop() {
+      stopped = true;
+      pending?.cancel();
+    },
+  };
+}

package/src/{codex-history-provider.ts → codex/history-provider.ts}

@@ -2,8 +2,8 @@ import { createHash } from "node:crypto";
 import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, readSync, unlinkSync, writeSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { Database } from "bun:sqlite";
-import { CODEX_HOME } from "./codex-paths";
-import { atomicWriteFile, getConfigDir } from "./config";
+import { CODEX_HOME } from "./paths";
+import { atomicWriteFile, getConfigDir } from "../config";
 
 const STATE_DB_PATH = join(CODEX_HOME, "state_5.sqlite");
 function historyBackupPathFor(stateDbPath: string): string {
@@ -20,10 +20,21 @@ const RESUMABLE_SOURCES = ["cli", "vscode"] as const;
  * connection pool into a half-applied checkpoint. The app opens this DB with `busy_timeout=5s`
  * (see codex-rs `state::runtime::base_sqlite_options`); we mirror that here.
  */
+let historyDbBusyTimeoutMs = 5000;
+
+/**
+ * Test-only knob: Windows CI can spend the FULL busy timeout on a transient file lock, which
+ * alone exceeds bun's 5s default per-test timeout. Tests shrink this so a busy DB fails fast
+ * into withHistoryRetry instead of stalling; production keeps the codex-rs-matching 5s.
+ */
+export function setHistoryDbBusyTimeoutForTests(ms: number): void {
+  historyDbBusyTimeoutMs = ms;
+}
+
 function openStateDb(stateDbPath: string): Database {
   const db = new Database(stateDbPath);
   try {
-    db.exec("PRAGMA busy_timeout = 5000");
+    db.exec(`PRAGMA busy_timeout = ${historyDbBusyTimeoutMs}`);
   } catch {
     /* best-effort: an older sqlite without busy_timeout still works, just less politely */
   }
@@ -369,6 +380,7 @@ export function isRecoverableHistoryError(error: unknown): boolean {
 }
 
 const HISTORY_RETRY_DELAY_MS = 500;
+const HISTORY_RETRY_ATTEMPTS = 2;
 
 /**
  * Run a history mutation with one retry across recoverable lock/busy errors (the app's own
@@ -377,20 +389,47 @@ const HISTORY_RETRY_DELAY_MS = 500;
  * 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 {
+export function withHistoryRetry<T>(fn: () => T, io: { sleepFn?: (ms: number) => void; attempts?: number; delayMs?: number } = {}): T | null {
   const sleepFn = io.sleepFn ?? Bun.sleepSync;
+  const attempts = Math.max(1, io.attempts ?? HISTORY_RETRY_ATTEMPTS);
+  const delayMs = io.delayMs ?? HISTORY_RETRY_DELAY_MS;
   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 */ }
+      if (attempt >= attempts - 1) return null;
+      try { sleepFn(delayMs); } catch { /* sleep is best-effort */ }
     }
   }
 }
 
-export function syncCodexHistoryProvider(provider: CodexHistoryProvider, stateDbPath = STATE_DB_PATH, backupPath = HISTORY_BACKUP_PATH): CodexHistorySyncResult {
+/**
+ * True when a READONLY probe proves the openai-direction restore would be a no-op:
+ * zero threads still tagged opencodex AND an empty backup manifest. Used to skip the
+ * write-open entirely in the Design B steady state — on Windows the Codex app holds
+ * `state_5.sqlite` (WAL, busy_timeout 5s), so an unnecessary write open can stall for
+ * seconds and surface a false lock warning, while WAL always admits readers. A failed
+ * probe (locked even for readers / schema drift) returns false so callers fall through
+ * to the write attempt and keep today's behavior for genuinely unknown state.
+ */
+function openaiRestoreIsNoop(stateDbPath: string, backupPath: string): boolean {
+  const pending = countPendingOpencodexHistory(stateDbPath, backupPath);
+  return !pending.failed && pending.pendingRows === 0 && pending.backupEntries === 0;
+}
+
+export function syncCodexHistoryProvider(
+  provider: CodexHistoryProvider,
+  stateDbPath = STATE_DB_PATH,
+  backupPath = HISTORY_BACKUP_PATH,
+  opts: { skipWhenProvablyNoop?: boolean } = {},
+): CodexHistorySyncResult {
+  // Opt-in steady-state gate (Design B loopback callers only): default semantics of
+  // this exported API are unchanged — legacy stop/restore paths never pass the flag.
+  if (opts.skipWhenProvablyNoop && provider === "openai" && existsSync(stateDbPath)
+    && openaiRestoreIsNoop(stateDbPath, backupPath)) {
+    return { rows: 0, files: 0 };
+  }
   return withHistoryRetry(() => syncCodexHistoryProviderUnsafe(provider, stateDbPath, backupPath))
     ?? { rows: 0, files: 0, failed: true };
 }
@@ -526,3 +565,68 @@ export function restoreLegacyOpenaiHistory(stateDbPath = STATE_DB_PATH): { rows:
     }
   }) ?? { rows: 0, files: 0, failed: true };
 }
+
+/**
+ * One-time Design-B migration: restore backed-up originals, then eject any remaining
+ * opencodex-tagged threads to openai. Thin wrapper over the restore path with a
+ * configurable retry budget — the daemon migration guardian uses `{ attempts: 1 }`
+ * per tick so a locked DB never stalls the event loop beyond one sqlite busy wait.
+ */
+export function migrateHistoryToOpenai(
+  stateDbPath = STATE_DB_PATH,
+  backupPath = HISTORY_BACKUP_PATH,
+  opts: { attempts?: number; delayMs?: number; sleepFn?: (ms: number) => void } = {},
+): CodexHistorySyncResult {
+  if (!existsSync(stateDbPath)) return { rows: 0, files: 0 };
+  // Steady-state gate: this migration is Design-B-specific (inject + guardian callers),
+  // and after the one-time migration every start would otherwise write-open the DB for
+  // nothing. A missing DB with a leftover backup manifest does NOT satisfy the gate
+  // (backupEntries > 0), so the guardian's fresh-reinstall re-count protection holds.
+  if (openaiRestoreIsNoop(stateDbPath, backupPath)) return { rows: 0, files: 0 };
+  return withHistoryRetry(() => syncCodexHistoryProviderUnsafe("openai", stateDbPath, backupPath), opts)
+    ?? { rows: 0, files: 0, failed: true };
+}
+
+export interface PendingHistoryCount {
+  /** Threads still tagged opencodex that the eject path WOULD move (mirrors its WHERE). */
+  pendingRows: number;
+  /** Entries still recorded in the backup manifest (restore targets). */
+  backupEntries: number;
+  /** Set when the DB could not be opened/read (locked); counts are then unknown, not zero. */
+  failed?: true;
+}
+
+/**
+ * Read-only migration progress probe for the guardian and `ocx doctor`. Opens sqlite
+ * readonly with a SHORT busy timeout so a locked DB cannot stall a daemon tick. The
+ * pending predicate mirrors ejectRemainingOpencodexHistory exactly — rows eject ignores
+ * (empty first_user_message) are not counted, so 0 really means "migration done".
+ */
+export function countPendingOpencodexHistory(stateDbPath = STATE_DB_PATH, backupPath = HISTORY_BACKUP_PATH): PendingHistoryCount {
+  let backupEntries = 0;
+  try {
+    const manifest = readBackup(backupPath, stateDbPath);
+    backupEntries = Object.keys(manifest.entries).length;
+  } catch { /* unreadable manifest counts as 0 — restore treats it the same way */ }
+
+  if (!existsSync(stateDbPath)) return { pendingRows: 0, backupEntries };
+  try {
+    const db = new Database(stateDbPath, { readonly: true });
+    try {
+      db.exec("PRAGMA busy_timeout = 100");
+      const row = db.query<{ n: number }, []>(`
+        SELECT count(*) AS n
+        FROM threads
+        WHERE model_provider = 'opencodex'
+          AND trim(coalesce(first_user_message, '')) != ''
+      `).get();
+      return { pendingRows: row?.n ?? 0, backupEntries };
+    } finally {
+      db.close();
+    }
+  } catch (error) {
+    if (isRecoverableHistoryError(error)) return { pendingRows: 0, backupEntries, failed: true };
+    // Schema drift (e.g. a future codex renames the table) is a "cannot know" too, not a crash.
+    return { pendingRows: 0, backupEntries, failed: true };
+  }
+}

package/src/{codex-home.ts → codex/home.ts}

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
-import { expandUserPath } from "./config";
+import { expandUserPath } from "../config";
 
 export type CodexHomeDeps = {
   env?: NodeJS.ProcessEnv;