@bitkyc08/opencodex 2.26.0 → 2.27.0

package/src/codex/app-server-processes.ts

@@ -7,7 +7,7 @@
  * Never match broad `*codex*` patterns that hit unrelated tools such as
  * `hermes-codex-bridge-mcp`.
  */
-import { execFileSync } from "node:child_process";
+import { execFile, execFileSync, type ExecFileException } from "node:child_process";
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { isProcessAlive, waitForExit } from "../lib/process-control";
 import {
@@ -98,9 +98,30 @@ export interface CodexAppServerProcessIo {
   waitExit?: (pid: number, timeoutMs: number) => boolean;
   now?: () => number;
   readStartMs?: (pid: number) => number | null;
+  /** Async process-list seam used by the request-path Windows collector. */
+  listSnapshotsAsync?: () => Promise<ProcessSnapshot[]>;
+  /** Async batch start-time seam used by the request-path Windows collector. */
+  readStartMsBatchAsync?: (pids: readonly number[]) => Promise<Map<number, number | null>>;
   catalogMtimeMs?: () => number | null;
 }
 
+function execFileTextAsync(
+  file: string,
+  args: readonly string[],
+  timeoutMs: number,
+): Promise<string> {
+  return new Promise((resolve, reject) => {
+    execFile(file, [...args], {
+      encoding: "utf-8",
+      timeout: timeoutMs,
+      windowsHide: true,
+    }, (error: ExecFileException | null, stdout: string) => {
+      if (error) reject(error);
+      else resolve(stdout);
+    });
+  });
+}
+
 /** Split a process command line into argv-like tokens (handles simple quotes). */
 export function tokenizeCommandLine(commandLine: string): string[] {
   const tokens: string[] = [];
@@ -375,7 +396,7 @@ export function parseWindowsSnapshotOutput(output: string): ProcessSnapshot[] {
   return out;
 }
 
-export function listWindowsSnapshots(runPowerShell?: (psCommand: string) => string): ProcessSnapshot[] {
+function windowsSnapshotPowerShellCommand(): string {
   // Newlines keep -Command as a real script (space-joined statements need ';').
   // Double-quoted format string so `t expands to a real tab.
   // Codex candidates only: basename token codex / codex.exe / codex.cmd /
@@ -384,7 +405,7 @@ export function listWindowsSnapshots(runPowerShell?: (psCommand: string) => stri
   // path with "opencodex".
   const basenameMatch = powerShellSingleQuotedIgnoreCaseMatch(WINDOWS_CODEX_BASENAME_CANDIDATE_RE.source);
   const codeModeMatch = powerShellSingleQuotedIgnoreCaseMatch(WINDOWS_CODEX_CODE_MODE_HOST_CANDIDATE_RE.source);
-  const psCommand = [
+  return [
     "$ErrorActionPreference='SilentlyContinue'",
     "$me=[System.Security.Principal.WindowsIdentity]::GetCurrent().Name",
     // -ErrorAction Stop plus the outer try is what makes a TOP-LEVEL query failure
@@ -412,9 +433,13 @@ export function listWindowsSnapshots(runPowerShell?: (psCommand: string) => stri
     "}",
     "} catch { \"__OCX_ENUM_INCOMPLETE__\" }",
   ].join("\n");
+}
+
+export function listWindowsSnapshots(runPowerShell?: (psCommand: string) => string): ProcessSnapshot[] {
   // Top-level exec failure propagates (see listDarwinSnapshots note). The
   // executable resolves from the trusted System32 directory (never PATH), and
   // windowsHide keeps the enumeration console-less on desktop sessions (#1278).
+  const psCommand = windowsSnapshotPowerShellCommand();
   const output = runPowerShell
     ? runPowerShell(psCommand)
     : execFileSync(resolveTrustedWindowsPowerShellExe(), [
@@ -425,6 +450,15 @@ export function listWindowsSnapshots(runPowerShell?: (psCommand: string) => stri
   return parseWindowsSnapshotOutput(output);
 }
 
+async function listWindowsSnapshotsAsync(): Promise<ProcessSnapshot[]> {
+  const output = await execFileTextAsync(resolveTrustedWindowsPowerShellExe(), [
+    "-NoProfile", "-NoLogo", "-NonInteractive",
+    "-Command",
+    windowsSnapshotPowerShellCommand(),
+  ], 8_000);
+  return parseWindowsSnapshotOutput(output);
+}
+
 function defaultListSnapshots(platform: NodeJS.Platform, getuid: () => number | undefined): ProcessSnapshot[] {
   if (platform === "win32") return listWindowsSnapshots();
   if (platform === "darwin") return listDarwinSnapshots(getuid());
@@ -533,6 +567,41 @@ export function readProcessStartMs(pid: number, platform: NodeJS.Platform = proc
   return readLinuxProcStartMs(pid);
 }
 
+function windowsProcessStartPowerShellCommand(pids: readonly number[]): string {
+  const filter = pids.map(pid => `ProcessId=${pid}`).join(" OR ");
+  return `Get-CimInstance Win32_Process -Filter "${filter}" | ForEach-Object { "$($_.ProcessId)\t$($_.CreationDate.ToUniversalTime().ToString("o"))" }`;
+}
+
+function parseWindowsProcessStartTimes(
+  stdout: string,
+  pids: readonly number[],
+): Map<number, number | null> {
+  const byPid = new Map<number, number>();
+  for (const line of stdout.split(/\r?\n/)) {
+    const tab = line.indexOf("\t");
+    if (tab <= 0) continue;
+    const pid = Number(line.slice(0, tab));
+    const parsed = Date.parse(line.slice(tab + 1).trim());
+    if (Number.isSafeInteger(pid) && Number.isFinite(parsed)) byPid.set(pid, parsed);
+  }
+  return new Map(pids.map(pid => [pid, byPid.get(pid) ?? null]));
+}
+
+async function readWindowsProcessStartMsBatchAsync(
+  pids: readonly number[],
+): Promise<Map<number, number | null>> {
+  try {
+    const stdout = await execFileTextAsync(resolveTrustedWindowsPowerShellExe(), [
+      "-NoProfile", "-NoLogo", "-NonInteractive",
+      "-Command",
+      windowsProcessStartPowerShellCommand(pids),
+    ], 5_000);
+    return parseWindowsProcessStartTimes(stdout, pids);
+  } catch {
+    return new Map(pids.map(pid => [pid, null]));
+  }
+}
+
 /**
  * Start times for many pids in ONE platform call where possible, so the
  * staleness check does not serialize per-process ps/PowerShell invocations
@@ -568,22 +637,12 @@ export function readProcessStartMsBatch(
   }
   if (platform === "win32") {
     try {
-      const filter = pids.map(pid => `ProcessId=${pid}`).join(" OR ");
       const stdout = execFileSync(resolveTrustedWindowsPowerShellExe(), [
         "-NoProfile", "-NoLogo", "-NonInteractive",
         "-Command",
-        `Get-CimInstance Win32_Process -Filter "${filter}" | ForEach-Object { "$($_.ProcessId)\t$($_.CreationDate.ToUniversalTime().ToString("o"))" }`,
+        windowsProcessStartPowerShellCommand(pids),
       ], { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"], timeout: 5_000, windowsHide: true });
-      const byPid = new Map<number, number>();
-      for (const line of stdout.split(/\r?\n/)) {
-        const tab = line.indexOf("\t");
-        if (tab <= 0) continue;
-        const pid = Number(line.slice(0, tab));
-        const parsed = Date.parse(line.slice(tab + 1).trim());
-        if (Number.isSafeInteger(pid) && Number.isFinite(parsed)) byPid.set(pid, parsed);
-      }
-      for (const pid of pids) out.set(pid, byPid.get(pid) ?? null);
-      return out;
+      return parseWindowsProcessStartTimes(stdout, pids);
     } catch {
       for (const pid of pids) out.set(pid, null);
       return out;
@@ -610,9 +669,65 @@ function defaultCatalogMtimeMs(): number | null {
   }
 }
 
+function codexAppServerProcessesFromSnapshots(
+  snapshots: readonly ProcessSnapshot[],
+): CodexAppServerProcess[] {
+  const processes: CodexAppServerProcess[] = [];
+  const seen = new Set<number>();
+  for (const snapshot of snapshots) {
+    if (seen.has(snapshot.pid)) continue;
+    if (!isCodexAppServerCommandLine(snapshot.commandLine, snapshot.executable)) continue;
+    seen.add(snapshot.pid);
+    processes.push({ pid: snapshot.pid, commandLine: snapshot.commandLine });
+  }
+  return processes;
+}
+
+function catalogStatusFromProcesses(
+  processes: readonly CodexAppServerProcess[],
+  catalogMtimeMs: number | null,
+  starts: ReadonlyMap<number, number | null>,
+): CodexAppServerCatalogStatus {
+  const withStarts = processes.map(proc => ({
+    pid: proc.pid,
+    startedAtMs: starts.get(proc.pid) ?? null,
+  }));
+  if (catalogMtimeMs === null || withStarts.some(proc => proc.startedAtMs === null)) {
+    return { state: "unknown", processes: withStarts, catalogMtimeMs };
+  }
+  // `<=` is deliberate: coarse clocks (ps lstart is second-granularity) can
+  // report equal values when the catalog actually changed after startup.
+  const stale = withStarts.some(proc => proc.startedAtMs! <= catalogMtimeMs);
+  return { state: stale ? "stale" : "fresh", processes: withStarts, catalogMtimeMs };
+}
+
 // Short TTL: process listing + stat run once per window even under per-turn
 // guidance calls (#857).
 let catalogStateCache: { atMs: number; status: CodexAppServerCatalogStatus } | null = null;
+interface RequestCatalogStateIdentity {
+  platform: NodeJS.Platform;
+  listSnapshots?: CodexAppServerProcessIo["listSnapshots"];
+  listSnapshotsAsync?: CodexAppServerProcessIo["listSnapshotsAsync"];
+  readStartMs?: CodexAppServerProcessIo["readStartMs"];
+  readStartMsBatchAsync?: CodexAppServerProcessIo["readStartMsBatchAsync"];
+  catalogMtimeMs?: CodexAppServerProcessIo["catalogMtimeMs"];
+  now?: CodexAppServerProcessIo["now"];
+}
+
+interface RequestCatalogStateFlight {
+  generation: number;
+  identity: RequestCatalogStateIdentity;
+  promise: Promise<CodexAppServerCatalogStatus>;
+}
+
+let requestCatalogStateGeneration = 0;
+let requestCatalogStateCache: {
+  generation: number;
+  identity: RequestCatalogStateIdentity;
+  atMs: number;
+  status: CodexAppServerCatalogStatus;
+} | null = null;
+let requestCatalogStateFlight: RequestCatalogStateFlight | null = null;
 const CATALOG_STATE_TTL_MS = 5_000;
 /**
  * `unknown` is a failure to observe, not an observation, so it gets a much shorter
@@ -627,6 +742,19 @@ export function catalogStateTtlMs(state: CodexAppServerCatalogState): number {
   return state === "unknown" ? CATALOG_STATE_UNKNOWN_TTL_MS : CATALOG_STATE_TTL_MS;
 }
 
+function sameRequestCatalogStateIdentity(
+  left: RequestCatalogStateIdentity,
+  right: RequestCatalogStateIdentity,
+): boolean {
+  return left.platform === right.platform
+    && left.listSnapshots === right.listSnapshots
+    && left.listSnapshotsAsync === right.listSnapshotsAsync
+    && left.readStartMs === right.readStartMs
+    && left.readStartMsBatchAsync === right.readStartMsBatchAsync
+    && left.catalogMtimeMs === right.catalogMtimeMs
+    && left.now === right.now;
+}
+
 /**
  * Compare the on-disk catalog mtime against the start time of running Codex
  * app-servers (#857): a server that started before the catalog changed keeps
@@ -676,33 +804,17 @@ export function collectCodexAppServerCatalogState(
       snapshots = [];
       enumerationFailed = true;
     }
-    const processes: CodexAppServerProcess[] = [];
-    const seen = new Set<number>();
-    for (const snapshot of snapshots) {
-      if (seen.has(snapshot.pid)) continue;
-      if (!isCodexAppServerCommandLine(snapshot.commandLine, snapshot.executable)) continue;
-      seen.add(snapshot.pid);
-      processes.push({ pid: snapshot.pid, commandLine: snapshot.commandLine });
-    }
+    const processes = codexAppServerProcessesFromSnapshots(snapshots);
     if (processes.length === 0) {
       return enumerationFailed
         ? { state: "unknown", processes: [], catalogMtimeMs: null }
         : { state: "not_running", processes: [], catalogMtimeMs: null };
     }
     const catalogMtimeMs = (io.catalogMtimeMs ?? defaultCatalogMtimeMs)();
-    const withStarts = io.readStartMs
-      ? processes.map(proc => ({ pid: proc.pid, startedAtMs: io.readStartMs!(proc.pid) }))
-      : (() => {
-        const batch = readProcessStartMsBatch(processes.map(proc => proc.pid), platform);
-        return processes.map(proc => ({ pid: proc.pid, startedAtMs: batch.get(proc.pid) ?? null }));
-      })();
-    if (catalogMtimeMs === null || withStarts.some(proc => proc.startedAtMs === null)) {
-      return { state: "unknown", processes: withStarts, catalogMtimeMs };
-    }
-    // `<=` is deliberate: coarse clocks (ps lstart is second-granularity) can
-    // report equal values when the catalog actually changed after startup.
-    const stale = withStarts.some(proc => proc.startedAtMs! <= catalogMtimeMs);
-    return { state: stale ? "stale" : "fresh", processes: withStarts, catalogMtimeMs };
+    const starts = io.readStartMs
+      ? new Map(processes.map(proc => [proc.pid, io.readStartMs!(proc.pid)] as const))
+      : readProcessStartMsBatch(processes.map(proc => proc.pid), platform);
+    return catalogStatusFromProcesses(processes, catalogMtimeMs, starts);
   };
   const status = compute();
   if (fullyDefault) {
@@ -711,9 +823,129 @@ export function collectCodexAppServerCatalogState(
   return status;
 }
 
-/** Test hook: drop the memoized catalog state. */
+/**
+ * Request-path catalog state collector.
+ *
+ * [Decision Log]
+ * - 목적과 의도: keep Windows CIM discovery from blocking Bun's event loop while v2 guidance is built.
+ * - 기존 구현 및 제약 조건: CLI/service operations still need the synchronous, fail-closed collector; the request path needs only advisory state.
+ * - 검토한 주요 대안: remove stale-catalog guidance, move all process work to workers, or add a Windows-only async boundary.
+ * - 선택한 방식: retain the synchronous API and use async PowerShell plus an identity-scoped in-flight refresh, short cache, and invalidation generation only for Windows requests.
+ * - 다른 대안 대신 이 방식을 선택한 이유: it fixes unrelated `/healthz` starvation without widening the process-matching or restart contract.
+ * - 장점, 단점 및 영향: concurrent turns share one CIM walk, invalidated pre-write results cannot repopulate the cache, and the event loop stays responsive; a cold v2 turn can still await the bounded advisory probe.
+ */
+export async function collectCodexAppServerCatalogStateForRequest(
+  io: CodexAppServerProcessIo = {},
+): Promise<CodexAppServerCatalogStatus> {
+  const platform = io.platform ?? process.platform;
+  if (platform !== "win32") return collectCodexAppServerCatalogState(io);
+
+  const now = (io.now ?? Date.now)();
+  const generation = requestCatalogStateGeneration;
+  const identity: RequestCatalogStateIdentity = {
+    platform,
+    listSnapshots: io.listSnapshots,
+    listSnapshotsAsync: io.listSnapshotsAsync,
+    readStartMs: io.readStartMs,
+    readStartMsBatchAsync: io.readStartMsBatchAsync,
+    catalogMtimeMs: io.catalogMtimeMs,
+    now: io.now,
+  };
+  if (requestCatalogStateCache
+    && requestCatalogStateCache.generation === generation
+    && sameRequestCatalogStateIdentity(requestCatalogStateCache.identity, identity)
+    && now - requestCatalogStateCache.atMs < catalogStateTtlMs(requestCatalogStateCache.status.state)) {
+    return requestCatalogStateCache.status;
+  }
+  if (requestCatalogStateFlight
+    && requestCatalogStateFlight.generation === generation
+    && sameRequestCatalogStateIdentity(requestCatalogStateFlight.identity, identity)) {
+    return requestCatalogStateFlight.promise;
+  }
+
+  const refresh = async (): Promise<CodexAppServerCatalogStatus> => {
+    let snapshots: ProcessSnapshot[];
+    try {
+      snapshots = io.listSnapshotsAsync
+        ? await io.listSnapshotsAsync()
+        : io.listSnapshots
+          ? io.listSnapshots()
+          : await listWindowsSnapshotsAsync();
+    } catch {
+      return { state: "unknown", processes: [], catalogMtimeMs: null };
+    }
+    const processes = codexAppServerProcessesFromSnapshots(snapshots);
+    if (processes.length === 0) {
+      return { state: "not_running", processes: [], catalogMtimeMs: null };
+    }
+    let catalogMtimeMs: number | null;
+    try {
+      catalogMtimeMs = (io.catalogMtimeMs ?? defaultCatalogMtimeMs)();
+    } catch {
+      catalogMtimeMs = null;
+    }
+    const pids = processes.map(proc => proc.pid);
+    const starts = io.readStartMsBatchAsync
+      ? await io.readStartMsBatchAsync(pids)
+      : io.readStartMs
+        ? new Map(pids.map(pid => [pid, io.readStartMs!(pid)] as const))
+        : await readWindowsProcessStartMsBatchAsync(pids);
+    return catalogStatusFromProcesses(processes, catalogMtimeMs, starts);
+  };
+
+  const pending = refresh().catch(() => ({
+    state: "unknown" as const,
+    processes: [],
+    catalogMtimeMs: null,
+  }));
+  let flight: RequestCatalogStateFlight;
+  const promise = pending.then(status => {
+    // A catalog write can invalidate while slow CIM is still running. The result
+    // describes the PRE-write world, so it must neither repopulate the post-write
+    // cache nor reach the caller.
+    //
+    // Suppressing only the cache write is not enough. The awaiting request still
+    // received `fresh`, and `fresh` is the one state that authorizes positive
+    // guidance (`src/server/responses/collaboration.ts:279-280` returns null for
+    // `stale`/`unknown` but describes the catalog for `fresh`). So the request
+    // would advertise the newly written disk catalog to an app-server whose
+    // in-memory copy the write just made stale — a wrong answer, which is worse
+    // than the slow answer this whole change exists to fix.
+    //
+    // Degrade to `unknown` instead: it is the honest description of what an
+    // invalidated observation knows, and the guidance path already treats it as
+    // "say nothing positive".
+    if (requestCatalogStateGeneration !== generation) {
+      return { state: "unknown" as const, processes: [], catalogMtimeMs: null };
+    }
+    if (requestCatalogStateFlight === flight) {
+      requestCatalogStateCache = {
+        generation,
+        identity,
+        atMs: (io.now ?? Date.now)(),
+        status,
+      };
+    }
+    return status;
+  }).finally(() => {
+    if (requestCatalogStateFlight === flight) requestCatalogStateFlight = null;
+  });
+  flight = { generation, identity, promise };
+  requestCatalogStateFlight = flight;
+  return flight.promise;
+}
+
+/**
+ * Drop memoized catalog state after a relevant catalog/cache write and before
+ * the post-write state read. Advancing the generation prevents an older
+ * in-flight Windows CIM refresh from publishing its pre-write result after the
+ * write has completed.
+ */
 export function resetCodexAppServerCatalogStateCache(): void {
   catalogStateCache = null;
+  requestCatalogStateGeneration += 1;
+  requestCatalogStateCache = null;
+  requestCatalogStateFlight = null;
 }
 
 export interface RestartCodexAppServersResult {

package/src/codex/auth-context.ts

@@ -12,7 +12,8 @@ import { ConfigMutationLockError } from "../config";
 import { isCodexAccountUsable } from "./account-usability";
 import { reconcileMainCodexAccountRuntimeState } from "./account-lifecycle";
 import { MAIN_CODEX_ACCOUNT_ID, getMainAccountToken, isMainAccountTokenLive } from "./main-account";
-import { isNativeMainTrafficBlocked } from "./native-profile-startup";
+import { isNativeMainTrafficBlocked, nativeMainStartupGateSnapshot } from "./native-profile-startup";
+import type { NativeMainStartupBlockReason } from "./native-profile-startup";
 import {
   codexQuotaScopeForModel,
   getCodexQuotaHealthSnapshot,
@@ -116,12 +117,63 @@ export const CODEX_MAIN_PROFILE_MAINTENANCE_MESSAGE =
   "OpenCodex local native-main profile maintenance is active; retry this request";
 
 export class CodexMainProfileDrainingError extends Error {
+  /**
+   * Which startup-gate state fenced this request, when one did. Undefined means the
+   * fence came from somewhere other than the startup gate — the turn-drain claim race
+   * throws this same error while the gate reads `ready`, and inventing a reason there
+   * would point the next report at a gate that never closed.
+   *
+   * Captured here rather than at the throw sites because this is the last moment it is
+   * both in scope and still true: every catch site has already lost it, and re-reading
+   * the gate later can observe a recovery that completed in between (#2108).
+   */
+  readonly reason?: NativeMainStartupBlockReason;
+
   constructor() {
     super(CODEX_MAIN_PROFILE_MAINTENANCE_MESSAGE);
     this.name = "CodexMainProfileDrainingError";
+    const gate = nativeMainStartupGateSnapshot();
+    if (gate.status !== "blocked") return;
+    this.reason = gate.reason;
+    reportNativeMainFenceReason(gate.reason);
   }
 }
 
+/**
+ * #2108: a reboot could leave this fence closed until `ocx restart`, and the report was
+ * unactionable because the settled reason was never written anywhere. It cannot ride the
+ * message (claude-messages.ts matches that string exactly to keep the fence a 503 rather
+ * than an Anthropic 529) and it cannot ride a header (/api/logs reads only error.message
+ * from the body, and the Claude surface rebuilds its response headers from scratch), so
+ * stdout is the one surface that covers every path this fence fires on.
+ *
+ * Deduped per distinct reason: the original report shows three 503s in eleven seconds and
+ * a real client retries harder than that, so a per-request line would bury the signal.
+ * Only the reason is emitted; the snapshot's homeId is derived from a profile directory.
+ */
+const reportedFenceReasons = new Set<NativeMainStartupBlockReason>();
+
+function reportNativeMainFenceReason(reason: NativeMainStartupBlockReason): void {
+  if (reportedFenceReasons.has(reason)) return;
+  reportedFenceReasons.add(reason);
+  console.warn(
+    `native-main admission is fenced (reason: ${reason}); native model requests return 503 until it clears`,
+  );
+}
+
+/**
+ * Test-only reset for the dedup set above.
+ *
+ * The dedup is process-lifetime module state, so it is order-sensitive across test files
+ * sharing one Bun process: whichever file constructs this error first consumes the one-shot
+ * warn, and a later file asserting on it would see nothing and pass vacuously. Any test that
+ * asserts on the warn must call this first — an `afterEach` in the asserting file is not
+ * enough on its own, because the consuming file may not be the asserting one.
+ */
+export function __resetNativeMainFenceReasonLog(): void {
+  reportedFenceReasons.clear();
+}
+
 export function codexMainProfileDrainingResponse(): Response {
   const response = formatErrorResponse(503, "server_busy", CODEX_MAIN_PROFILE_MAINTENANCE_MESSAGE);
   const headers = new Headers(response.headers);

package/src/codex/catalog/aggregation.ts

@@ -183,6 +183,9 @@ export function deriveComboCatalogModel(
         ? { supportsServiceTier: false }
         : {}),
     ...(members.some(member => member.supportsReasoningSummaries === false) ? { supportsReasoningSummaries: false } : {}),
+    ...(members.every(member => member.codexToolMode === "shell")
+      ? { codexToolMode: "shell" as const }
+      : {}),
   };
 }
 

package/src/codex/catalog/parsing.ts

@@ -126,6 +126,12 @@ export interface CatalogModel {
   /** Whether this exact routed model has a verified OpenAI-compatible service tier. */
   supportsServiceTier?: boolean;
   supportsReasoningSummaries?: boolean;
+  /**
+   * Codex tool calling mode for this routed model.
+   * "code_mode_only" (default) sets entry.tool_mode = "code_mode_only".
+   * "shell" leaves tool_mode unset so Codex declares top-level shell tools (exec_command).
+   */
+  codexToolMode?: "code_mode_only" | "shell";
   /** Normalized upstream capability names retained for management/API consumers (#485 follow-up). */
   capabilities?: string[];
   /** OpenCodex-only catalog ownership marker; Codex ignores the serialized extension field. */
@@ -423,7 +429,14 @@ export function catalogEntryIsNativeChatGpt(entry: RawEntry): boolean {
 
 export const ROUTED_CODEX_TOOL_MODE = "code_mode_only";
 
-export function applyRoutedCodexToolMode(entry: RawEntry): RawEntry {
+export function applyRoutedCodexToolMode(
+  entry: RawEntry,
+  toolMode?: "code_mode_only" | "shell" | string,
+): RawEntry {
+  if (toolMode === "shell") {
+    delete entry.tool_mode;
+    return entry;
+  }
   entry.tool_mode = ROUTED_CODEX_TOOL_MODE;
   return entry;
 }
@@ -490,10 +503,14 @@ export function applyMultiAgentMode(
   return entries;
 }
 
-export function normalizeRoutedCatalogEntry(entry: RawEntry, parallelToolCalls = false): RawEntry {
+export function normalizeRoutedCatalogEntry(
+  entry: RawEntry,
+  parallelToolCalls = false,
+  toolMode?: "code_mode_only" | "shell" | string,
+): RawEntry {
   delete entry.model_messages;
   delete entry.tool_mode;
-  applyRoutedCodexToolMode(entry);
+  applyRoutedCodexToolMode(entry, toolMode);
   delete entry.multi_agent_version;
   delete entry.use_responses_lite;
   delete entry.supports_websockets;

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

@@ -413,6 +413,7 @@ function captureProviderGather(
     name,
     provider,
     registryTransportMatch,
+    configured,
   );
   const observedAuth = authResolver.kind === "observed"
     && provider.authMode !== "forward"
@@ -676,6 +677,7 @@ export function applyProviderConfigHints(name: string, prov: OcxProviderConfig,
     ...(prov.parallelToolCalls === true || (prov.adapter === "openai-chat" && prov.parallelToolCalls !== false)
       ? { parallelToolCalls: true }
       : {}),
+    ...(prov.codexToolMode !== undefined ? { codexToolMode: prov.codexToolMode } : {}),
   };
   const capped = applyProviderContextCap(hinted.contextWindow, providerCap);
   if (providerCap !== undefined && capped !== hinted.contextWindow) {
@@ -1881,6 +1883,11 @@ async function gatherRoutedModelsUncached(
       ...(Array.isArray(cm.reasoningEfforts) ? { reasoningEfforts: [...cm.reasoningEfforts] } : {}),
       ...(cm.defaultReasoningEffort ? { defaultReasoningEffort: cm.defaultReasoningEffort } : {}),
       ...(typeof supportsServiceTier === "boolean" ? { supportsServiceTier } : {}),
+      ...(cm.codexToolMode !== undefined
+        ? { codexToolMode: cm.codexToolMode }
+        : effectiveProvider?.codexToolMode !== undefined
+          ? { codexToolMode: effectiveProvider.codexToolMode }
+          : {}),
     };
     // #962: the dedupe below drops the provider-derived row this custom row replaces. Inherit that
     // row's provider capability metadata (reasoning ladder, default effort, parallel tool calls,
@@ -1905,6 +1912,7 @@ async function gatherRoutedModelsUncached(
       ...(base.parallelToolCalls === undefined && replaced.parallelToolCalls !== undefined ? { parallelToolCalls: replaced.parallelToolCalls } : {}),
       ...(base.supportsVerbosity === undefined && replaced.supportsVerbosity !== undefined ? { supportsVerbosity: replaced.supportsVerbosity } : {}),
       ...(base.supportsReasoningSummaries === undefined && replaced.supportsReasoningSummaries !== undefined ? { supportsReasoningSummaries: replaced.supportsReasoningSummaries } : {}),
+      ...(base.codexToolMode === undefined && replaced.codexToolMode !== undefined ? { codexToolMode: replaced.codexToolMode } : {}),
       ...(base.capabilities === undefined && replaced.capabilities !== undefined ? { capabilities: replaced.capabilities } : {}),
     } : base;
     // Vision-sidecar coverage ONLY: if the custom model is in the enriched provider's

package/src/codex/catalog/sync.ts

@@ -331,7 +331,9 @@ export function deriveEntry(
       // This exact provider/model pair is the ChatGPT/Codex forward surface. Keep the pinned
       // native tool/search/responses-lite contract while preserving the routed slug and wire id.
       if (!codexForwardNativeCapabilityAlias) {
-        normalizeRoutedCatalogEntry(e, model?.parallelToolCalls === true);
+        normalizeRoutedCatalogEntry(e, model?.parallelToolCalls === true, model?.codexToolMode);
+      } else if (model?.codexToolMode !== undefined) {
+        applyRoutedCodexToolMode(e, model.codexToolMode);
       }
       if (model) applyCatalogMetadata(e, model.provider, model.id, model.contextCap);
       applyCatalogModelMetadata(e, model);
@@ -358,8 +360,8 @@ export function deriveEntry(
     });
   }
   // Fallback when no template is available (best-effort; strict parser may need more).
-  // All routed fallbacks enable deferred code-mode tool exposure; otherwise the nested catalog
-  // expands into `exec.description` and can exceed Cursor's 120 KB serialized tool limit (#1830).
+  // Routed fallbacks default to code-mode tool exposure (or shell mode when codexToolMode === "shell");
+  // otherwise the nested catalog expands into `exec.description` and can exceed Cursor's 120 KB serialized tool limit (#1830).
   // Cursor still omits hosted web-search metadata because runTurn bypasses that separate sidecar.
   const isCursorFallback = isRouted && model?.provider === "cursor";
   const entry: RawEntry = {
@@ -373,7 +375,7 @@ export function deriveEntry(
       : {}),
   };
   if (isRouted) {
-    applyRoutedCodexToolMode(entry);
+    applyRoutedCodexToolMode(entry, model?.codexToolMode);
     applyReasoningLevels(entry, model?.reasoningEfforts, model?.defaultReasoningEffort, preserveExact);
   }
   else {

package/src/codex/log-guard/path-safety.ts

@@ -1,5 +1,5 @@
-import { realpathSync } from "node:fs";
-import { resolve, sep } from "node:path";
+import { lstatSync, realpathSync } from "node:fs";
+import { dirname, resolve, sep } from "node:path";
 
 import { samePathIdentity } from "../user-identity";
 
@@ -35,5 +35,54 @@ export function normalizeTrustedDarwinSystemAlias(path: string): string {
  * Arbitrary ancestor symlinks remain refused.
  */
 export function sameLogGuardPathIdentity(realPath: string, requestedPath: string): boolean {
-  return samePathIdentity(realPath, normalizeTrustedDarwinSystemAlias(requestedPath));
+  const requested = normalizeTrustedDarwinSystemAlias(requestedPath);
+  if (samePathIdentity(realPath, requested)) return true;
+  return sameWindowsCanonicalPath(realPath, requested);
+}
+
+/**
+ * On Windows, is the difference between these two spellings the OS canonicalizing the
+ * request rather than a redirection?
+ *
+ * `realpathSync.native` expands 8.3 short components — the `RUNNER~1` form that appears
+ * throughout `%TEMP%` — so the canonical path and the requested path can disagree as
+ * strings while naming the same file. Reading that as an ancestor-symlink redirection made
+ * every Log Guard mutation refuse with `unsafe_path` on Windows, which is what the CI shards
+ * were reporting.
+ *
+ * The first version of this re-canonicalized the requested path and compared the two
+ * canonical forms. That was wrong, and the Windows shard proved it: the caller already
+ * passes `realpathSync.native(requested)` as `realPath`, so re-resolving the request
+ * produced the same value on BOTH sides and a symlinked database compared equal. The
+ * widening let through exactly what the guard exists to refuse.
+ *
+ * The comparison is therefore link-aware. A short-name expansion rewrites the spelling of
+ * components that are all still directories on the same chain, so it is enough to require
+ * that no component of the request is a link: with none present, any remaining difference
+ * is the OS's own canonical spelling. A symlink or junction anywhere in the chain fails
+ * closed as before.
+ */
+function sameWindowsCanonicalPath(realPath: string, requestedPath: string): boolean {
+  if (process.platform !== "win32") return false;
+  try {
+    if (pathChainContainsLink(requestedPath)) return false;
+    return samePathIdentity(realPath, realpathSync.native(requestedPath));
+  } catch {
+    return false;
+  }
+}
+
+/** Is any component of this path a symlink or junction? Fails closed on an unreadable one. */
+function pathChainContainsLink(path: string): boolean {
+  let current = resolve(path);
+  for (;;) {
+    try {
+      if (lstatSync(current).isSymbolicLink()) return true;
+    } catch {
+      return true;
+    }
+    const parent = dirname(current);
+    if (parent === current) return false;
+    current = parent;
+  }
 }