@bitkyc08/opencodex 2.7.36 → 2.7.37

package/src/cli/doctor.ts

@@ -10,13 +10,22 @@
 import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { getConfigDir, getConfigPath, readConfigDiagnostics, readPid, resolveEnvValue } from "../config";
+import { getConfigDir, getConfigPath, readConfigDiagnostics, readPid, readRuntimePort, resolveEnvValue } from "../config";
+import { gracefulStopHost } from "../lib/process-control";
+import { loadServiceTokenFromFile } from "../lib/service-secrets";
 import { readCodexTokens } from "../codex/auth-collision";
 import { resolveCodexHomeDir as resolveCodexHomeDirImpl, isWslRuntime, listWslWindowsCodexHomes, wslAutomountRoot, type CodexHomeDeps } from "../codex/home";
 import { findCodexOnPath, isWindowsInteropDir } from "../codex/shim";
 import { countPendingOpencodexHistory } from "../codex/history-provider";
 import { collectProjectCodexConfigWarnings, formatProjectCodexConfigWarningsForDoctor } from "../codex/project-config-warnings";
 import { collectStartupHealth, startupHealthSummary } from "../codex/autostart-health";
+import {
+  displayCodexRuntimePath,
+  loadLastEffortClamp,
+  persistCodexRuntime,
+  resolveAndPersistCodexRuntime,
+  resolveCodexRuntime,
+} from "../codex/runtime";
 export { resolveCodexHomeDir } from "../codex/home";
 
 const WHAM_USAGE_URL = "https://chatgpt.com/backend-api/wham/usage";
@@ -319,9 +328,149 @@ export async function probeWham(fetchImpl: typeof fetch = fetch): Promise<WhamPr
   }
 }
 
-export async function runDoctor(): Promise<void> {
+/**
+ * Service-process memory/runtime introspection (#314 WP4).
+ *
+ * Doctor runs in its OWN Bun process; the only honest source for the SERVICE
+ * process identity (Bun version, RSS, stream-mode gate decision) is the
+ * authed management endpoint added in WP3. Observe-only: failures render as
+ * honest status lines, never as fake data, and never fail the command.
+ */
+export type ServiceMemoryData = {
+  pid: number;
+  bunVersion: string;
+  platform: string;
+  rss: number;
+  heapUsed: number;
+  jscHeap: { heapSize: number } | null;
+  streamMode: string;
+  eagerRelay: { useEagerRelay: boolean; reason: string } | null;
+  watchdog: { warnThresholdBytes: number; lastWarnAt: number | null } | null;
+};
+
+export type ServiceMemoryReport =
+  | { status: "ok"; data: ServiceMemoryData }
+  | { status: "unauthorized" }
+  | { status: "unreachable"; error: string };
+
+const SERVICE_MEMORY_TIMEOUT_MS = 2000;
+const DEFAULT_MEMORY_THRESHOLD_BYTES = 4 * 1024 ** 3;
+
+export async function fetchServiceMemory(
+  host: string,
+  port: number,
+  token: string | null,
+  fetchImpl: typeof fetch = fetch,
+): Promise<ServiceMemoryReport> {
+  try {
+    const res = await fetchImpl(`http://${host}:${port}/api/system/memory`, {
+      headers: token ? { "x-opencodex-api-key": token } : {},
+      signal: AbortSignal.timeout(SERVICE_MEMORY_TIMEOUT_MS),
+    });
+    if (res.status === 401 || res.status === 403) return { status: "unauthorized" };
+    if (!res.ok) return { status: "unreachable", error: `http ${res.status}` };
+    const body = await res.json() as Partial<ServiceMemoryData>;
+    if (typeof body.pid !== "number" || typeof body.bunVersion !== "string" || typeof body.rss !== "number") {
+      return { status: "unreachable", error: "malformed response" };
+    }
+    return {
+      status: "ok",
+      data: {
+        pid: body.pid,
+        bunVersion: body.bunVersion,
+        platform: typeof body.platform === "string" ? body.platform : "unknown",
+        rss: body.rss,
+        heapUsed: typeof body.heapUsed === "number" ? body.heapUsed : 0,
+        jscHeap: body.jscHeap && typeof body.jscHeap.heapSize === "number" ? { heapSize: body.jscHeap.heapSize } : null,
+        streamMode: typeof body.streamMode === "string" ? body.streamMode : "auto",
+        eagerRelay: body.eagerRelay && typeof body.eagerRelay.reason === "string"
+          ? { useEagerRelay: body.eagerRelay.useEagerRelay === true, reason: body.eagerRelay.reason }
+          : null,
+        watchdog: body.watchdog && typeof body.watchdog.warnThresholdBytes === "number"
+          ? { warnThresholdBytes: body.watchdog.warnThresholdBytes, lastWarnAt: body.watchdog.lastWarnAt ?? null }
+          : null,
+      },
+    };
+  } catch (err) {
+    return { status: "unreachable", error: err instanceof Error ? err.name : "fetch failed" };
+  }
+}
+
+const mb = (bytes: number): string => `${Math.round(bytes / (1024 * 1024))}MB`;
+
+/** Render the doctor "Memory / runtime" section lines (testable without console capture). */
+export function formatServiceMemoryLines(report: ServiceMemoryReport): string[] {
+  const lines: string[] = [];
+  lines.push(`  --     doctor process Bun ${Bun.version} (this is NOT the service process)`);
+  if (report.status === "unauthorized") {
+    lines.push("  --     proxy reachable but rejected the request — set OPENCODEX_API_AUTH_TOKEN to match the service");
+    return lines;
+  }
+  if (report.status === "unreachable") {
+    lines.push(`  --     proxy not reachable (not running?) [${report.error}]`);
+    return lines;
+  }
+  const d = report.data;
+  lines.push(`  ok     service pid ${d.pid}: Bun ${d.bunVersion} on ${d.platform}`);
+  lines.push(`         rss=${mb(d.rss)}, heapUsed=${mb(d.heapUsed)}${d.jscHeap ? `, jscHeap=${mb(d.jscHeap.heapSize)}` : ""}`);
+  lines.push(`         streamMode=${d.streamMode}${d.eagerRelay ? ` (eager relay: ${d.eagerRelay.useEagerRelay ? "on" : "off"}, ${d.eagerRelay.reason})` : ""}`);
+  if (d.watchdog) {
+    lines.push(`         watchdog threshold=${mb(d.watchdog.warnThresholdBytes)}${d.watchdog.lastWarnAt ? `, last warn ${new Date(d.watchdog.lastWarnAt).toISOString()}` : ", no warnings"}`);
+  }
+  // Interpretation rule (devlog 040): reuse the watchdog's own threshold so
+  // doctor and watchdog never disagree about "high"; jsShare discriminates
+  // JS-heap growth from native runtime growth (the #314 shape).
+  const threshold = d.watchdog?.warnThresholdBytes ?? DEFAULT_MEMORY_THRESHOLD_BYTES;
+  const jsShare = d.rss > 0 ? Math.max(d.heapUsed, d.jscHeap?.heapSize ?? 0) / d.rss : 0;
+  if (d.rss < threshold) {
+    lines.push("         memory usage looks normal");
+  } else if (jsShare < 0.25) {
+    lines.push("  !!     high RSS with a small JS heap — native-side growth (Bun runtime buffers/handles). See docs: troubleshooting/windows-memory");
+  } else if (jsShare >= 0.5) {
+    lines.push("  !!     high RSS dominated by the JS heap — likely an opencodex bug; please report it");
+  } else {
+    lines.push("  !!     high RSS, indeterminate split — capture two doctor runs over time to see the trend");
+  }
+  // Version-claiming (never binary-claiming): the endpoint cannot distinguish
+  // the bundled binary from an OPENCODEX_BUN_PATH override of the same version.
+  if (d.platform === "win32" && d.eagerRelay?.reason === "auto-known-bad") {
+    lines.push(`         service is running Bun ${d.bunVersion} on Windows — a version affected by the upstream Bun memory issue.`);
+    lines.push("         Options: wait for a bundled runtime update, or set OPENCODEX_BUN_PATH to a runtime you trust (unvalidated — own risk),");
+    lines.push("         or opt into streamMode \"eager-relay\" via PUT /api/settings (crash risk on this runtime; see docs).");
+  }
+  return lines;
+}
+
+export async function runDoctor(args: string[] = []): Promise<void> {
+  if (args.includes("--fix-codex-runtime")) {
+    const resolved = resolveCodexRuntime();
+    if (!resolved.newerAvailable) {
+      console.log("No newer Codex runtime found; keeping current selection.");
+      const current = resolveAndPersistCodexRuntime();
+      console.log(`Selected: ${displayCodexRuntimePath(current.runtime.command)} (${current.runtime.version ?? "unknown"})`);
+      return;
+    }
+    if (resolved.runtime.source === "environment") {
+      console.log("CODEX_CLI_PATH currently overrides configured runtimes.");
+      console.log(`Unset or update CODEX_CLI_PATH to use ${displayCodexRuntimePath(resolved.newerAvailable.command)} (${resolved.newerAvailable.version ?? "unknown"}).`);
+      console.log("Then run ocx sync.");
+      return;
+    }
+    persistCodexRuntime({
+      command: resolved.newerAvailable.command,
+      version: resolved.newerAvailable.version,
+      source: "configured",
+    });
+    console.log(`Updated Codex runtime to ${displayCodexRuntimePath(resolved.newerAvailable.command)} (${resolved.newerAvailable.version ?? "unknown"}).`);
+    console.log("Run ocx sync to refresh the catalog against this runtime.");
+    return;
+  }
+
   console.log("opencodex doctor\n");
 
+  // Ordering note: the memory/runtime section renders after "Running proxy
+  // process proxy env" below; helpers live above runDoctor for testability.
+
   const paths = collectPaths();
   const mounts = readMounts();
   console.log("Paths");
@@ -337,6 +486,35 @@ export async function runDoctor(): Promise<void> {
   console.log(`  ${startup.rebootSafe ? "ok " : "!! "} ${startupHealthSummary(startup)}`);
   console.log(`       routing=${startup.routingKind}, service=${startup.serviceViable ? "viable" : startup.serviceInstalled ? "installed-but-unhealthy" : "absent"}, shim=${startup.shimHealthy ? "healthy" : startup.shimInstalled ? "stale" : "absent"}`);
 
+  console.log("\nCodex runtime selection");
+  {
+    const resolved = resolveCodexRuntime();
+    const selected = resolved.runtime;
+    console.log(`  ok  Selected runtime: ${displayCodexRuntimePath(selected.command)} (${selected.version ?? "unknown"}, source=${selected.source})`);
+    const envFailures = resolved.failures.filter(item => item.source === "environment");
+    for (const failure of envFailures) {
+      console.log(`  !!  Invalid CODEX_CLI_PATH: ${failure.reason}`);
+    }
+    const shimFailures = resolved.failures.filter(item => item.source === "shim");
+    if (shimFailures.length > 0) {
+      console.log(`  !!  Stale shim target rejected (${shimFailures.length})`);
+    }
+    if (resolved.replacedConfigured) {
+      console.log(`  !!  Preferred runtime unavailable; fell back to ${displayCodexRuntimePath(selected.command)}`);
+    }
+    if (resolved.newerAvailable) {
+      console.log(`  !!  Multiple Codex installations found.`);
+      console.log(`  ok  Newer usable runtime found: ${displayCodexRuntimePath(resolved.newerAvailable.command)} (${resolved.newerAvailable.version ?? "unknown"})`);
+      console.log("       Suggested: set CODEX_CLI_PATH to the desired binary and run ocx sync.");
+      console.log("       Optional: ocx doctor --fix-codex-runtime");
+    }
+    const lastClamp = loadLastEffortClamp();
+    if (lastClamp && lastClamp.removedEfforts.length > 0) {
+      console.log(`  !!  ${lastClamp.removedEfforts.join(" and ")} were removed during catalog sync.`);
+      console.log("       Suggested: set CODEX_CLI_PATH to a newer Codex binary and run ocx sync.");
+    }
+  }
+
   const currentProxyEnv = collectProxyEnv();
   const configuredProxy = collectConfiguredProxy();
   const runningProxyEnv = collectRunningProxyEnv();
@@ -361,6 +539,23 @@ export async function runDoctor(): Promise<void> {
     }
   }
 
+  // #314: service-process memory/runtime identity via the authed management
+  // endpoint. readPid() FIRST (liveness), then the pid-scoped runtime record —
+  // readRuntimePort alone can serve a stale file pointing at a foreign port.
+  console.log("\nMemory / runtime");
+  {
+    const livePid = readPid();
+    const runtime = livePid ? readRuntimePort(livePid) : null;
+    if (!runtime) {
+      console.log(`  --     doctor process Bun ${Bun.version} (this is NOT the service process)`);
+      console.log("  --     no running ocx proxy found (no live pid/runtime record)");
+    } else {
+      const token = process.env.OPENCODEX_API_AUTH_TOKEN ?? loadServiceTokenFromFile(process.env);
+      const report = await fetchServiceMemory(gracefulStopHost(runtime.hostname), runtime.port, token);
+      for (const line of formatServiceMemoryLines(report)) console.log(line);
+    }
+  }
+
   console.log("\nWHAM reachability");
   const probe = await probeWham();
   const detail = probe.status !== null ? `status=${probe.status}` : `error=${probe.classification}`;

package/src/cli/index.ts

@@ -36,6 +36,7 @@ import { buildDesktop3pRegistry } from "../claude/desktop-3p";
 import { installShellHook, uninstallShellHook } from "../server/system-env";
 import { startTokenGuardian } from "../oauth/token-guardian";
 import { startHistoryMigrationGuardian } from "../codex/history-migration-guardian";
+import { maybeAutoRestoreCodexShim } from "./codex-shim-autorestore";
 import { maybeShowStarPrompt } from "./star-prompt";
 import { maybeShowUpdatePrompt } from "../update/notify";
 import { syncModelsToCodex } from "../codex/sync";
@@ -49,8 +50,9 @@ if (command === "--version" || command === "-v" || command === "version") {
   process.exit(0);
 }
 
-if (command === "help" && args[1]) {
-  printSubcommandUsage(args[1]);
+if (command === undefined || command === "help" || command === "--help" || command === "-h") {
+  if (command === "help" && args[1]) printSubcommandUsage(args[1]);
+  else printUsage();
   process.exit(0);
 }
 
@@ -59,6 +61,8 @@ if (command !== undefined && command !== "help" && hasHelpFlag(args.slice(1))) {
   process.exit(0);
 }
 
+maybeAutoRestoreCodexShim(command, args);
+
 function parsePortOption(): number | undefined {
   if (args.length === 1) return undefined;
   if (args.length !== 3 || args[1] !== "--port") {
@@ -507,6 +511,16 @@ async function handleStatus() {
   console.log(`   Restart safety: ${startupHealthSummary(status.json.startup)}`);
   console.log(`   Service: ${status.json.service.summary}`);
   console.log(`   ${status.json.codexShim.summary}`);
+  console.log(`   Codex runtime: ${status.json.codexRuntime.path}`);
+  console.log(`   Codex version: ${status.json.codexRuntime.version ?? "unknown"}`);
+  console.log(`   Codex source: ${status.json.codexRuntime.source}`);
+  console.log(`   Catalog clamp: ${status.json.codexRuntime.catalogClamp.active ? "active" : "inactive"}`);
+  if (status.json.codexRuntime.catalogClamp.removedEfforts.length > 0) {
+    console.log(`   Removed efforts: ${status.json.codexRuntime.catalogClamp.removedEfforts.join(", ")}`);
+  }
+  if (status.json.codexRuntime.warning) {
+    console.log(`   ⚠️  ${status.json.codexRuntime.warning}`);
+  }
   if (status.json.codexPlugins.applicable) {
     const icon = status.json.codexPlugins.stale ? "⚠️ " : "✅";
     console.log(`   ${icon} Codex bundled plugins: ${status.json.codexPlugins.summary}`);
@@ -581,7 +595,7 @@ switch (command) {
     break;
   case "doctor": {
     const { runDoctor } = await import("./doctor");
-    await runDoctor();
+    await runDoctor(args.slice(1));
     break;
   }
   case "debug": {

package/src/cli/status.ts

@@ -7,6 +7,8 @@ import { diagnoseService } from "../service";
 import { collectStartupHealth, type StartupHealth } from "../codex/autostart-health";
 import { getCodexRoutingKind } from "../codex/inject";
 import { diagnoseCodexShim } from "../codex/shim";
+import { displayCodexRuntimePath, effortClampAppliesToRuntime, loadLastEffortClamp, resolveCodexRuntime } from "../codex/runtime";
+import { redactSecretString, redactUserPath } from "../lib/redact";
 
 type HealthCheck = {
   ok: boolean;
@@ -51,6 +53,18 @@ export type CliStatusJson = {
   service: { summary: string };
   codexShim: { summary: string };
   codexPlugins: CodexPluginsDiagnostic;
+  codexRuntime: {
+    path: string;
+    version: string | null;
+    source: string;
+    newerAvailable: { path: string; version: string | null } | null;
+    warning: string | null;
+    catalogClamp: {
+      active: boolean;
+      removedEfforts: string[];
+      runtimeVersion: string | null;
+    };
+  };
 };
 
 export type CliStatusView = {
@@ -129,6 +143,71 @@ export async function collectStatus(): Promise<CliStatusView> {
     routingKind: getCodexRoutingKind(),
   });
   const codexPlugins = diagnoseCodexBundledPlugins();
+  const resolvedRuntime = (() => {
+    try {
+      return resolveCodexRuntime();
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      const redacted = redactUserPath(redactSecretString(message)).slice(0, 160);
+      return {
+        runtime: { command: "codex", version: null, source: "fallback" as const },
+        failures: [{
+          command: "codex",
+          source: "fallback" as const,
+          reason: `resolve threw: ${redacted}`,
+        }],
+        replacedConfigured: undefined,
+        newerAvailable: undefined,
+      };
+    }
+  })();
+  const lastClamp = loadLastEffortClamp();
+  const clampActive = effortClampAppliesToRuntime(lastClamp, resolvedRuntime.runtime);
+  const warningParts: string[] = [];
+  if (
+    resolvedRuntime.replacedConfigured
+    && resolvedRuntime.replacedConfigured.from.command !== resolvedRuntime.runtime.command
+  ) {
+    warningParts.push(
+      `Preferred Codex runtime is unavailable; using ${displayCodexRuntimePath(resolvedRuntime.runtime.command)} instead. Run ocx doctor for diagnosis and recovery.`,
+    );
+  } else if (
+    resolvedRuntime.runtime.source === "fallback"
+    && resolvedRuntime.failures.length > 0
+    && !resolvedRuntime.runtime.version
+  ) {
+    const detail = resolvedRuntime.failures[0]?.reason;
+    warningParts.push(
+      detail
+        ? `No validated Codex runtime found (${detail}); falling back to \`codex\`. Run ocx doctor for diagnosis and recovery.`
+        : "No validated Codex runtime found; falling back to `codex`. Run ocx doctor for diagnosis and recovery.",
+    );
+  }
+  if (resolvedRuntime.newerAvailable) {
+    warningParts.push("OpenCodex is using an older Codex binary. Run ocx doctor for diagnosis and recovery.");
+  }
+  if (clampActive) {
+    warningParts.push(
+      `Catalog clamp removed: ${lastClamp!.removedEfforts.join(", ")}. Run ocx doctor for diagnosis and recovery.`,
+    );
+  }
+  const codexRuntime = {
+    path: displayCodexRuntimePath(resolvedRuntime.runtime.command),
+    version: resolvedRuntime.runtime.version,
+    source: resolvedRuntime.runtime.source,
+    newerAvailable: resolvedRuntime.newerAvailable
+      ? {
+        path: displayCodexRuntimePath(resolvedRuntime.newerAvailable.command),
+        version: resolvedRuntime.newerAvailable.version,
+      }
+      : null,
+    warning: warningParts.length > 0 ? warningParts.join(" ") : null,
+    catalogClamp: {
+      active: clampActive,
+      removedEfforts: clampActive ? (lastClamp?.removedEfforts ?? []) : [],
+      runtimeVersion: clampActive ? (lastClamp?.runtimeVersion ?? null) : null,
+    },
+  };
   const proxyLabel = pid && health.ok
     ? `running (PID ${pid})`
     : pid
@@ -176,6 +255,7 @@ export async function collectStatus(): Promise<CliStatusView> {
       service: { summary: serviceSummary },
       codexShim: { summary: codexShimSummary },
       codexPlugins,
+      codexRuntime,
     },
   };
 }

package/src/cli/v2.ts

@@ -15,6 +15,7 @@ import { getLogicalMaxThreads, hasAgentsMaxThreads, isMultiAgentV2Enabled, trans
 
 import { commandInvocation, type SpawnInvocation } from "../lib/win-exec";
 import { loadConfig, saveConfig } from "../config";
+import { resolveAndPersistCodexRuntime, type ResolveCodexRuntimeDeps } from "../codex/runtime";
 
 export interface V2CliDeps {
   execFile?: (file: string, args: string[], options?: SpawnInvocation["options"]) => void;
@@ -24,6 +25,10 @@ export interface V2CliDeps {
   log?: Pick<Console, "log" | "error">;
 }
 
+export type CodexFeaturesInvocationDeps =
+  & Parameters<typeof commandInvocation>[3]
+  & Pick<ResolveCodexRuntimeDeps, "existsSync" | "execFileSync" | "configDir" | "readFileSync">;
+
 /**
  * Shared invocation for `codex features enable|disable multi_agent_v2` — the single
  * source of truth for the CLI and the management API fallback. Windows npm installs
@@ -33,9 +38,16 @@ export interface V2CliDeps {
 export function codexFeaturesInvocation(
   action: "enable" | "disable",
   platform: NodeJS.Platform = process.platform,
-  deps: Parameters<typeof commandInvocation>[3] = {},
+  deps: CodexFeaturesInvocationDeps = {},
 ): SpawnInvocation {
-  const command = (deps.env ?? process.env).CODEX_CLI_PATH?.trim() || "codex";
+  const command = resolveAndPersistCodexRuntime({
+    env: deps.env ?? process.env,
+    platform,
+    existsSync: deps.existsSync,
+    execFileSync: deps.execFileSync,
+    configDir: deps.configDir,
+    readFileSync: deps.readFileSync,
+  }).runtime.command || "codex";
   return commandInvocation(command, ["features", action, "multi_agent_v2"], platform, deps);
 }
 

package/src/codex/auth-context.ts

@@ -7,7 +7,11 @@ import {
 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 {
+  getCodexAccountCooldownUntil,
+  pickLowestUsageCodexAccount,
+  resolveCodexAccountForThreadDetailed,
+} from "./routing";
 import { getAccountQuota } from "./quota";
 import type { CodexAccountMode, OcxConfig, OcxProviderConfig } from "../types";
 import { FORWARD_HEADERS } from "../adapters/openai-responses";
@@ -89,17 +93,29 @@ export function shouldMarkAccountNeedsReauthForCodexAuthFailure(cause: unknown):
   return !(cause instanceof CodexCredentialGenerationConflictError) && !(cause instanceof CodexCredentialRefreshLockTimeoutError);
 }
 
+export interface ResolveCodexAuthContextOptions {
+  excludeAccountId?: string;
+}
+
 export async function resolveCodexAuthContext(
   headers: Headers,
   config: OcxConfig,
   mode: CodexAccountMode,
+  options: ResolveCodexAuthContextOptions = {},
 ): Promise<CodexAuthContext> {
   if (mode === "direct") {
     if (!hasCallerCodexBearer(headers)) throw new CodexDirectAuthenticationError();
     return { kind: "main", accountId: null };
   }
   const threadId = headers.get("x-codex-parent-thread-id");
-  const resolution = resolveCodexAccountForThreadDetailed(threadId, config);
+  const resolution = options.excludeAccountId
+    ? (() => {
+        const accountId = pickLowestUsageCodexAccount(config, options.excludeAccountId);
+        return accountId
+          ? { status: "selected" as const, accountId }
+          : { status: "none" as const };
+      })()
+    : resolveCodexAccountForThreadDetailed(threadId, config);
   if (resolution.status === "expired") throw new CodexThreadAffinityExpiredError(resolution.accountId);
   const accountId = resolution.status === "selected" ? resolution.accountId : null;
   if (!accountId) throw new CodexPoolAuthenticationError();

package/src/codex/catalog/bundled.ts

@@ -33,16 +33,31 @@ import upstreamModelsSnapshot from "../data/upstream-models.json";
 
 import { activeCodexModelsCachePath, catalogBackupPathFor, findNativeTemplate, isDefaultCatalogPath, legacyCatalogBackupPath, parseCatalogJson, readCatalog, readCatalogBackup, readCodexCatalogPath } from "./parsing";
 import type { RawCatalog, RawEntry } from "./parsing";
+import { codexExecInvocation, isSpawnableCodexCandidate } from "../exec-invocation";
+import { resolveAndPersistCodexRuntime } from "../runtime";
+import type { EffortClampDiagnostic } from "../runtime";
+
+export { isSpawnableCodexCandidate, codexExecInvocation } from "../exec-invocation";
 
 export const BUNDLED_CATALOG_CACHE_MS = 60_000;
 
-export let bundledCatalogCache: { expiresAt: number; value: RawCatalog | null } | null = null;
+export let bundledCatalogCache: {
+  /** Selected runtime identity; must change when doctor/sync picks a different binary. */
+  key: string;
+  expiresAt: number;
+  value: RawCatalog | null;
+} | null = null;
 
 /** Test-only: clear the bundled-catalog cache (owned here; sync.ts calls this instead of assigning the import). */
 export function resetBundledCatalogCacheForTests(): void {
   bundledCatalogCache = null;
 }
 
+/** Drop the process-local bundled catalog memo (e.g. after runtime selection changes). */
+export function invalidateBundledCatalogCache(): void {
+  bundledCatalogCache = null;
+}
+
 export type ExecFile = (
   file: string,
   args: string[],
@@ -52,12 +67,21 @@ export type ExecFile = (
     timeout: number;
     windowsHide: boolean;
     shell?: boolean;
+    windowsVerbatimArguments?: boolean;
   },
 ) => string;
 
 export interface BundledCatalogDeps {
   commandCandidates?: () => string[];
   execFileSync?: ExecFile;
+  onEffortClamp?: (diagnostic: EffortClampDiagnostic) => void;
+  configDir?: string;
+  env?: NodeJS.ProcessEnv;
+  platform?: NodeJS.Platform;
+  existsSync?: (path: string) => boolean;
+  readFileSync?: (path: string, encoding: "utf8") => string;
+  now?: () => number;
+  discoverAlternatives?: boolean;
 }
 
 export function unique(values: string[]): string[] {
@@ -77,11 +101,6 @@ export function codexCommandCandidates(): string[] {
   return unique(candidates);
 }
 
-export function isSpawnableCodexCandidate(path: string, platform: NodeJS.Platform = process.platform): boolean {
-  if (platform !== "win32") return true;
-  return /\.(cmd|bat|exe|com)$/i.test(path);
-}
-
 export function codexShimCommandCandidates(): string[] {
   try {
     const state = JSON.parse(readFileSync(join(getConfigDir(), "codex-shim.json"), "utf8")) as {
@@ -105,45 +124,82 @@ export function codexShimCommandCandidates(): string[] {
   }
 }
 
-export function codexExecInvocation(
+export function runCodexDebugModels(
   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 };
-}
-
-export function runCodexDebugModels(command: string, execFile: ExecFile): string {
+  execFile: ExecFile,
+  deps: Pick<BundledCatalogDeps, "env" | "platform" | "existsSync"> = {},
+): string {
   const args = ["debug", "models", "--bundled"];
-  const invocation = codexExecInvocation(command);
-  return execFile(invocation.file, args, {
+  const invocation = codexExecInvocation(command, args, deps.platform ?? process.platform, {
+    env: deps.env,
+    exists: deps.existsSync,
+  });
+  return execFile(invocation.file, invocation.args, {
     encoding: "utf8" as const,
     stdio: ["ignore", "pipe", "ignore"] as ["ignore", "pipe", "ignore"],
     timeout: 10_000,
     windowsHide: true,
-    shell: invocation.shell,
+    ...invocation.options,
   });
 }
 
 export function loadBundledCodexCatalog(deps: BundledCatalogDeps = {}): RawCatalog | null {
-  const useCache = !deps.commandCandidates && !deps.execFileSync;
-  if (useCache && bundledCatalogCache && bundledCatalogCache.expiresAt > Date.now()) {
+  const useCache = !deps.commandCandidates && !deps.execFileSync && !deps.configDir && !deps.env;
+  const execFile = deps.execFileSync ?? (execFileSync as unknown as ExecFile);
+  // Prefer the single resolved runtime so sync/clamp never probe a different binary
+  // than OpenCodex will launch. Tests may inject commandCandidates to stub probing.
+  let cacheKey: string | null = null;
+  const candidates = deps.commandCandidates?.() ?? (() => {
+    const resolved = resolveAndPersistCodexRuntime({
+      execFileSync: execFile,
+      configDir: deps.configDir,
+      env: deps.env,
+      platform: deps.platform,
+      existsSync: deps.existsSync,
+      readFileSync: deps.readFileSync,
+      now: deps.now,
+      discoverAlternatives: deps.discoverAlternatives,
+    });
+    if (useCache) {
+      cacheKey = [
+        resolved.runtime.command,
+        resolved.runtime.version ?? "",
+        process.env.OPENCODEX_HOME ?? "",
+      ].join("\0");
+    }
+    return [resolved.runtime.command];
+  })();
+  if (
+    useCache
+    && cacheKey
+    && bundledCatalogCache
+    && bundledCatalogCache.key === cacheKey
+    && bundledCatalogCache.expiresAt > Date.now()
+  ) {
     return bundledCatalogCache.value;
   }
-  const candidates = deps.commandCandidates?.() ?? codexCommandCandidates();
-  const execFile = deps.execFileSync ?? (execFileSync as unknown as ExecFile);
-  for (const command of candidates) {
+  for (const command of unique(candidates)) {
     try {
-      const catalog = parseCatalogJson(runCodexDebugModels(command, execFile));
+      const catalog = parseCatalogJson(runCodexDebugModels(command, execFile, deps));
       if (catalog && findNativeTemplate(catalog)) {
-        if (useCache) bundledCatalogCache = { expiresAt: Date.now() + BUNDLED_CATALOG_CACHE_MS, value: catalog };
+        if (useCache && cacheKey) {
+          bundledCatalogCache = {
+            key: cacheKey,
+            expiresAt: Date.now() + BUNDLED_CATALOG_CACHE_MS,
+            value: catalog,
+          };
+        }
         return catalog;
       }
     } catch { /* try next candidate */ }
   }
-  if (useCache) bundledCatalogCache = { expiresAt: Date.now() + BUNDLED_CATALOG_CACHE_MS, value: null };
+  if (useCache && cacheKey) {
+    bundledCatalogCache = {
+      key: cacheKey,
+      expiresAt: Date.now() + BUNDLED_CATALOG_CACHE_MS,
+      value: null,
+    };
+  }
   return null;
 }