@iislee/opencodex 2.11.0 → 2.35.0

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

@@ -7,13 +7,18 @@
  * 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 {
+  resolveTrustedWindowsPowerShellExe,
+  resolveTrustedWindowsTaskkillExe,
+} from "../lib/windows-elevation";
 import { readCodexCatalogPath } from "./catalog/parsing";
 
 export const STALE_CODEX_APP_SERVER_HINT =
-  "If Codex still shows an older model list, restart its long-lived app-server process after sync (ocx sync --restart-codex).";
+  "If Codex still shows an older model list, restart its long-lived app-server process after sync (ocx sync --restart-codex). "
+  + "On Windows the desktop app itself may also need a full restart (ocx sync --restart-desktop-app).";
 
 /** Attach the shared dashboard hint only after a catalog or models_cache write. */
 export function attachStaleAppServerHint<T extends {
@@ -71,6 +76,7 @@ export interface CodexAppServerProcess {
 export interface ProcessSnapshot {
   pid: number;
   commandLine: string;
+  executable?: string;
   uid?: number;
   owner?: string;
   startedAtMs?: number;
@@ -82,12 +88,41 @@ export interface CodexAppServerProcessIo {
   listSnapshots?: () => ProcessSnapshot[];
   isAlive?: (pid: number) => boolean;
   kill?: (pid: number, signal: NodeJS.Signals) => void;
+  /** Windows termination seam: drives the taskkill branch without a real exec. */
+  execFile?: (file: string, args: readonly string[]) => void;
+  /**
+   * Signal seam for the Unix branch and the taskkill fallback. Without it,
+   * injecting `kill` bypasses defaultKillCodexAppServer entirely, so the
+   * fallback could never be observed.
+   */
+  processKill?: (pid: number, signal: NodeJS.Signals) => void;
   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[] = [];
@@ -211,13 +246,37 @@ export function codexAppServerProcessIdentity(proc: Pick<CodexAppServerProcess,
 }
 
 /** True when the command line is a Codex app-server (or code-mode host) worth restarting. */
-export function isCodexAppServerCommandLine(commandLine: string): boolean {
-  const tokens = tokenizeCommandLine(commandLine.trim());
+export function isCodexAppServerCommandLine(commandLine: string, executable?: string): boolean {
+  const trimmed = commandLine.trim();
+  let tokens = tokenizeCommandLine(trimmed);
+  if (executable) {
+    if (isCodeModeHostToken(executable)) return true;
+    if (isCodexExecutableToken(executable)) {
+      let remainder = trimmed;
+      if (remainder.startsWith(executable)) remainder = remainder.slice(executable.length).trimStart();
+      else if (remainder.startsWith(`"${executable}"`)) remainder = remainder.slice(executable.length + 2).trimStart();
+      tokens = [executable, ...tokenizeCommandLine(remainder)];
+    }
+  }
   if (tokens.length === 0) return false;
   if (isCodeModeHostProcess(tokens)) return true;
-
-  // Require Codex as argv0 so later-argument occurrences stay unmatched
-  // (e.g. `node worker.js codex app-server`).
+  // An npm-installed Codex runs as a PAIR: `node /usr/local/bin/codex app-server` and the
+  // vendored native binary that wrapper spawns. Only the child used to match, so
+  // `--restart-codex` signalled the child while its supervisor kept holding the socket -
+  // which is what "PID(s) still running after SIGTERM" was reporting on Linux.
+  //
+  // The codex-shaped token must be IMMEDIATELY next. Skipping interpreter flags to reach
+  // it looks tempting and is wrong: interpreter options take values, so a generic skip
+  // reads the value of `node --require codex app-server worker.js` as the entrypoint.
+  // Supporting flags needs a real Node/Bun/Deno entrypoint parser, not a loop over
+  // hyphens; the observed wrappers put the path first, so this stays narrow on purpose.
+  //
+  // Dropping only the interpreter and re-running the ordinary scan is what preserves the
+  // subcommand discipline below: `node <codex> exec 'hi'` stays unmatched exactly like
+  // `codex exec 'hi'` does.
+  if (isInterpreterToken(tokens[0]!) && tokens.length > 1 && isCodexExecutableToken(tokens[1]!)) {
+    tokens = tokens.slice(1);
+  }
   if (!isCodexExecutableToken(tokens[0]!)) return false;
 
   let i = 1;
@@ -227,7 +286,6 @@ export function isCodexAppServerCommandLine(commandLine: string): boolean {
       i = advancePastCodexGlobalOption(tokens, i);
       continue;
     }
-    // First non-option after globals is the Codex subcommand.
     return token.toLowerCase() === "app-server";
   }
   return false;
@@ -253,12 +311,13 @@ function listUnixProcSnapshots(uid: number | undefined): ProcessSnapshot[] {
       const status = readFileSync(`/proc/${pid}/status`, "utf8");
       const processUid = parseUnixProcStatusUid(status);
       if (uid !== undefined && processUid !== undefined && processUid !== uid) continue;
-      const commandLine = readFileSync(`/proc/${pid}/cmdline`)
+      const argv = readFileSync(`/proc/${pid}/cmdline`)
         .toString("utf8")
-        .replace(/\0/g, " ")
-        .trim();
+        .split("\0")
+        .filter(Boolean);
+      const commandLine = argv.join(" ").trim();
       if (!commandLine) continue;
-      out.push({ pid, commandLine, uid: processUid });
+      out.push({ pid, commandLine, executable: argv[0], uid: processUid });
     } catch {
       /* process exited mid-scan */
     }
@@ -268,20 +327,29 @@ function listUnixProcSnapshots(uid: number | undefined): ProcessSnapshot[] {
 
 function listDarwinSnapshots(uid: number | undefined): ProcessSnapshot[] {
   const out: ProcessSnapshot[] = [];
-  // Top-level exec failure propagates: callers decide their own safe default
-  // (restart flow → treat as none; staleness check → unknown, never "fresh").
-  const output = uid !== undefined
-    ? execFileSync("ps", ["-u", String(uid), "-o", "pid=,command="], {
-      encoding: "utf-8",
-      stdio: ["ignore", "pipe", "ignore"],
-      timeout: 5_000,
+  const commandOutput = uid !== undefined
+    ? execFileSync("/bin/ps", ["-u", String(uid), "-o", "pid=,command="], {
+      encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"], timeout: 5_000,
     })
-    : execFileSync("ps", ["-axo", "pid=,uid=,command="], {
-      encoding: "utf-8",
-      stdio: ["ignore", "pipe", "ignore"],
-      timeout: 5_000,
+    : execFileSync("/bin/ps", ["-axo", "pid=,uid=,command="], {
+      encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"], timeout: 5_000,
+    });
+  const executableOutput = uid !== undefined
+    ? execFileSync("/bin/ps", ["-u", String(uid), "-o", "pid=,comm="], {
+      encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"], timeout: 5_000,
+    })
+    : execFileSync("/bin/ps", ["-axo", "pid=,comm="], {
+      encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"], timeout: 5_000,
     });
-  for (const raw of output.split(/\r?\n/)) {
+  const executableByPid = new Map<number, string>();
+  for (const raw of executableOutput.split(/\r?\n/)) {
+    const match = /^\s*(\d+)\s+(.+)$/.exec(raw);
+    if (!match) continue;
+    const pid = Number(match[1]);
+    const executable = match[2]?.trim() ?? "";
+    if (Number.isSafeInteger(pid) && pid > 0 && executable) executableByPid.set(pid, executable);
+  }
+  for (const raw of commandOutput.split(/\r?\n/)) {
     const line = raw.trim();
     if (!line) continue;
     if (uid !== undefined) {
@@ -289,8 +357,8 @@ function listDarwinSnapshots(uid: number | undefined): ProcessSnapshot[] {
       if (!match) continue;
       const pid = Number(match[1]);
       const commandLine = match[2]?.trim() ?? "";
-      if (!Number.isSafeInteger(pid) || pid <= 1 || !commandLine) continue;
-      out.push({ pid, commandLine, uid });
+      if (!Number.isSafeInteger(pid) || pid <= 0 || !commandLine) continue;
+      out.push({ pid, commandLine, executable: executableByPid.get(pid), uid });
       continue;
     }
     const match = /^(\d+)\s+(\d+)\s+(.*)$/.exec(line);
@@ -298,8 +366,11 @@ function listDarwinSnapshots(uid: number | undefined): ProcessSnapshot[] {
     const pid = Number(match[1]);
     const processUid = Number(match[2]);
     const commandLine = match[3]?.trim() ?? "";
-    if (!Number.isSafeInteger(pid) || pid <= 1 || !commandLine) continue;
-    out.push({ pid, commandLine, uid: Number.isSafeInteger(processUid) ? processUid : undefined });
+    if (!Number.isSafeInteger(pid) || pid <= 0 || !commandLine) continue;
+    out.push({
+      pid, commandLine, executable: executableByPid.get(pid),
+      uid: Number.isSafeInteger(processUid) ? processUid : undefined,
+    });
   }
   return out;
 }
@@ -316,8 +387,34 @@ function listDarwinSnapshots(uid: number | undefined): ProcessSnapshot[] {
  * Exported for the Windows integration regression that exercises the real
  * PowerShell enumeration.
  */
-export function listWindowsSnapshots(): ProcessSnapshot[] {
+/**
+ * Turn one PowerShell enumeration's stdout into snapshots.
+ *
+ * Split out from the spawn so the failure contract is testable off-Windows: the
+ * sentinel path is the difference between "no Codex process is running" and "we could
+ * not read the process list", and only one of those is safe to act on.
+ */
+export function parseWindowsSnapshotOutput(output: string): ProcessSnapshot[] {
   const out: ProcessSnapshot[] = [];
+  for (const line of output.split(/\r?\n/)) {
+    // A candidate whose owner could not be verified — or a top-level query that
+    // failed outright — makes the whole enumeration incomplete. The staleness
+    // collector must not read the partial result as "nothing running".
+    if (line.trim() === "__OCX_ENUM_INCOMPLETE__") throw new Error("windows_enum_incomplete");
+    const tab = line.indexOf("\t");
+    if (tab <= 0) continue;
+    const tab2 = line.indexOf("\t", tab + 1);
+    if (tab2 <= tab) continue;
+    const pid = Number(line.slice(0, tab));
+    const commandLine = line.slice(tab + 1, tab2).trim();
+    const owner = line.slice(tab2 + 1).trim();
+    if (!Number.isSafeInteger(pid) || pid <= 1 || !commandLine || !owner) continue;
+    out.push({ pid, commandLine, owner });
+  }
+  return out;
+}
+
+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 /
@@ -326,10 +423,18 @@ export function listWindowsSnapshots(): ProcessSnapshot[] {
   // 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",
-    "Get-CimInstance Win32_Process | Where-Object {",
+    // -ErrorAction Stop plus the outer try is what makes a TOP-LEVEL query failure
+    // observable. Under SilentlyContinue alone, a failing Get-CimInstance emits nothing
+    // and the enumeration is indistinguishable from "no Codex process is running" —
+    // the parse loop finds no rows, no sentinel is produced, and the staleness collector
+    // reports not_running for a machine whose process list it never actually read.
+    // The per-process catch below cannot cover this: it only runs once the pipeline has
+    // objects to iterate.
+    "try {",
+    "Get-CimInstance Win32_Process -ErrorAction Stop | Where-Object {",
     "  -not [string]::IsNullOrWhiteSpace($_.CommandLine) -and (",
     `    $_.CommandLine -match ${basenameMatch} -or`,
     `    $_.CommandLine -match ${codeModeMatch}`,
@@ -344,29 +449,32 @@ export function listWindowsSnapshots(): ProcessSnapshot[] {
     "    \"{0}`t{1}`t{2}\" -f $_.ProcessId, $cmd, $owner",
     "  } catch { \"__OCX_ENUM_INCOMPLETE__\" }",
     "}",
+    "} catch { \"__OCX_ENUM_INCOMPLETE__\" }",
   ].join("\n");
-  // Top-level exec failure propagates (see listDarwinSnapshots note).
-  const output = execFileSync("powershell.exe", [
-    "-NoProfile", "-NoLogo", "-NonInteractive", "-WindowStyle", "Hidden",
+}
+
+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(), [
+      "-NoProfile", "-NoLogo", "-NonInteractive",
+      "-Command",
+      psCommand,
+    ], { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"], timeout: 8_000, windowsHide: true });
+  return parseWindowsSnapshotOutput(output);
+}
+
+async function listWindowsSnapshotsAsync(): Promise<ProcessSnapshot[]> {
+  const output = await execFileTextAsync(resolveTrustedWindowsPowerShellExe(), [
+    "-NoProfile", "-NoLogo", "-NonInteractive",
     "-Command",
-    psCommand,
-  ], { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"], timeout: 8_000, windowsHide: true });
-  for (const line of output.split(/\r?\n/)) {
-    // A candidate whose owner could not be verified makes the whole
-    // enumeration incomplete — the staleness collector must not read the
-    // partial result as "nothing running".
-    if (line.trim() === "__OCX_ENUM_INCOMPLETE__") throw new Error("windows_enum_incomplete");
-    const tab = line.indexOf("\t");
-    if (tab <= 0) continue;
-    const tab2 = line.indexOf("\t", tab + 1);
-    if (tab2 <= tab) continue;
-    const pid = Number(line.slice(0, tab));
-    const commandLine = line.slice(tab + 1, tab2).trim();
-    const owner = line.slice(tab2 + 1).trim();
-    if (!Number.isSafeInteger(pid) || pid <= 1 || !commandLine || !owner) continue;
-    out.push({ pid, commandLine, owner });
-  }
-  return out;
+    windowsSnapshotPowerShellCommand(),
+  ], 8_000);
+  return parseWindowsSnapshotOutput(output);
 }
 
 function defaultListSnapshots(platform: NodeJS.Platform, getuid: () => number | undefined): ProcessSnapshot[] {
@@ -400,19 +508,22 @@ export function listCodexAppServerProcesses(io: CodexAppServerProcessIo = {}): C
   const matched: CodexAppServerProcess[] = [];
   for (const snapshot of snapshots) {
     if (seen.has(snapshot.pid)) continue;
-    if (!isCodexAppServerCommandLine(snapshot.commandLine)) continue;
+    if (!isCodexAppServerCommandLine(snapshot.commandLine, snapshot.executable)) continue;
     seen.add(snapshot.pid);
     matched.push({ pid: snapshot.pid, commandLine: snapshot.commandLine });
   }
   return matched;
 }
 
-export function formatStaleCodexAppServerWarning(processes: readonly CodexAppServerProcess[]): string {
+export function formatStaleCodexAppServerWarning(
+  processes: readonly { pid: number }[],
+): string {
   const pids = processes.map(process => process.pid).join(", ");
   return (
     `WARNING: ${processes.length} Codex app-server process(es) still running (PID${processes.length === 1 ? "" : "s"}: ${pids}). `
     + "Disk catalog/cache were updated, but Codex may keep showing the old model list until those processes restart. "
     + "Re-run with `ocx sync --restart-codex` (or `ocx sync-cache --restart-codex`) to send SIGTERM only to matching app-server processes. "
+    + "On Windows the desktop app itself may also need a full restart (`ocx sync --restart-desktop-app`). "
     + "Active turns may be interrupted."
   );
 }
@@ -439,7 +550,7 @@ function readLinuxProcStartMs(pid: number): number | null {
 /** `ps` lstart → epoch ms, or null (macOS). */
 function readDarwinProcStartMs(pid: number): number | null {
   try {
-    const out = execFileSync("ps", ["-o", "lstart=", "-p", String(pid)], {
+    const out = execFileSync("/bin/ps", ["-o", "lstart=", "-p", String(pid)], {
       encoding: "utf-8",
       stdio: ["ignore", "pipe", "ignore"],
       timeout: 4_000,
@@ -455,8 +566,8 @@ function readDarwinProcStartMs(pid: number): number | null {
 /** Win32_Process.CreationDate → epoch ms, or null (Windows). */
 function readWindowsProcStartMs(pid: number): number | null {
   try {
-    const out = execFileSync("powershell.exe", [
-      "-NoProfile", "-NoLogo", "-NonInteractive", "-WindowStyle", "Hidden",
+    const out = execFileSync(resolveTrustedWindowsPowerShellExe(), [
+      "-NoProfile", "-NoLogo", "-NonInteractive",
       "-Command",
       `(Get-CimInstance Win32_Process -Filter "ProcessId=${pid}").CreationDate.ToUniversalTime().ToString("o")`,
     ], { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"], timeout: 8_000, windowsHide: true }).trim();
@@ -475,6 +586,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
@@ -488,7 +634,7 @@ export function readProcessStartMsBatch(
   if (pids.length === 0) return out;
   if (platform === "darwin") {
     try {
-      const stdout = execFileSync("ps", ["-o", "pid=,lstart=", "-p", pids.join(",")], {
+      const stdout = execFileSync("/bin/ps", ["-o", "pid=,lstart=", "-p", pids.join(",")], {
         encoding: "utf-8",
         stdio: ["ignore", "pipe", "ignore"],
         timeout: 3_000,
@@ -510,22 +656,12 @@ export function readProcessStartMsBatch(
   }
   if (platform === "win32") {
     try {
-      const filter = pids.map(pid => `ProcessId=${pid}`).join(" OR ");
-      const stdout = execFileSync("powershell.exe", [
-        "-NoProfile", "-NoLogo", "-NonInteractive", "-WindowStyle", "Hidden",
+      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;
@@ -552,10 +688,113 @@ 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
+ * window than a real reading. At the full 5s a single transient enumeration failure
+ * suppresses guidance for every call in that window, and the retry that would have
+ * succeeded never runs. Keeping a brief window still collapses a burst of per-turn
+ * calls into one probe, which is what the cache is for.
+ */
+const CATALOG_STATE_UNKNOWN_TTL_MS = 250;
+
+/**
+ * How long a real observation may still be SERVED after it expires, while a refresh
+ * runs behind it (#2499).
+ *
+ * The probe is advisory and, on Windows, slow: `Invoke-CimMethod GetOwner` costs
+ * ~0.4s per candidate process, so a cold probe routinely outlives the 5s TTL and
+ * every turn that misses the cache pays for it on the request path. Serving the
+ * previous reading immediately keeps that cost off the turn without pretending it is
+ * fresh -- the refresh it triggers is what makes the next reading current.
+ *
+ * Measured from expiry rather than from when the reading was taken, so a `fresh`
+ * entry stays servable for its own TTL plus this bound. Anchoring it to expiry keeps
+ * the stale window independent of the TTL -- a cap on total age would quietly turn
+ * this path off if the TTL were ever raised past it.
+ *
+ * Bounded rather than unlimited: if the refresh keeps failing, an observation this
+ * old stops being evidence about the machine and it is better to wait for a real one.
+ * `unknown` is never served this way -- it is a failure to observe, not an
+ * observation, and it already has its own short window for exactly that reason.
+ */
+export const CATALOG_STATE_MAX_STALE_MS = 60_000;
+
+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
@@ -580,7 +819,8 @@ export function collectCodexAppServerCatalogState(
   const fullyDefault = !io.listSnapshots && !io.readStartMs && !io.catalogMtimeMs
     && !io.platform && !io.getuid && !io.now;
   if (fullyDefault
-    && catalogStateCache && now - catalogStateCache.atMs < CATALOG_STATE_TTL_MS) {
+    && catalogStateCache
+    && now - catalogStateCache.atMs < catalogStateTtlMs(catalogStateCache.status.state)) {
     return catalogStateCache.status;
   }
   const compute = (): CodexAppServerCatalogStatus => {
@@ -594,45 +834,28 @@ export function collectCodexAppServerCatalogState(
     });
     let snapshots: ProcessSnapshot[];
     let enumerationFailed = false;
-    if (io.listSnapshots) {
-      snapshots = io.listSnapshots();
-    } else {
-      try {
-        snapshots = defaultListSnapshots(platform, getuid);
-      } catch {
-        // Enumeration failure must never read as "nothing running" — that
-        // would let positive model guidance through on guesswork (#857).
-        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)) continue;
-      seen.add(snapshot.pid);
-      processes.push({ pid: snapshot.pid, commandLine: snapshot.commandLine });
+    const enumerate = io.listSnapshots ?? (() => defaultListSnapshots(platform, getuid));
+    try {
+      snapshots = enumerate();
+    } catch {
+      // Enumeration failure must never read as "nothing running" — that would let
+      // positive model guidance through on guesswork (#857). The injected seam gets
+      // the same contract as the default path: whoever enumerates, a failure to read
+      // the process list is unknown, not an empty machine.
+      snapshots = [];
+      enumerationFailed = true;
     }
+    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) {
@@ -641,9 +864,164 @@ 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.
+ *
+ * [Decision Log · #2499]
+ * - 목적과 의도: a cold probe outlives its own 5s TTL on Windows (~435ms per candidate process for `Invoke-CimMethod GetOwner`), so the cache expires before it can serve and the miss lands on a turn.
+ * - 기존 구현 및 제약 조건: the reading is advisory, and only `fresh` authorizes positive guidance (`src/server/responses/collaboration.ts`); `unknown` is a failure to observe rather than an observation.
+ * - 검토한 주요 대안: drop the per-process GetOwner fan-out (issue suggestion 1), or widen the TTL past the probe duration (suggestion 3).
+ * - 선택한 방식: serve an expired reading immediately when its generation still matches, bounded by `CATALOG_STATE_MAX_STALE_MS`, never for `unknown`, and refresh behind it; a failed refresh no longer evicts the reading it was refreshing.
+ * - 다른 대안 대신 이 방식을 선택한 이유: the fan-out change alters what "could not verify the owner" means for the current-user scoping contract and needs its own ground-truth comparison; a wider TTL still pays the probe on every human-paced turn.
+ * - 장점, 단점 및 영향: after the first probe the request path never waits; a server that stopped between readings can be described as `fresh` for up to the stale bound; a catalog write still invalidates immediately through the generation, and the cold path is unchanged.
+ */
+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,
+  };
+  const cached = requestCatalogStateCache
+    && requestCatalogStateCache.generation === generation
+    && sameRequestCatalogStateIdentity(requestCatalogStateCache.identity, identity)
+    ? requestCatalogStateCache
+    : null;
+  if (cached && now - cached.atMs < catalogStateTtlMs(cached.status.state)) {
+    return cached.status;
+  }
+  // An expired real reading is still worth handing back while the refresh runs. It
+  // cannot have been invalidated by an ocx catalog write: every such write calls
+  // `resetCodexAppServerCatalogStateCache`, which advances the generation and drops
+  // this entry, so a generation match means no write has landed since it was taken.
+  // What it can miss is an app-server that started or stopped meanwhile -- and a
+  // server started after the reading is newer than the catalog, which is the `fresh`
+  // this entry already says.
+  const servableStale = cached
+    && cached.status.state !== "unknown"
+    && now - cached.atMs < catalogStateTtlMs(cached.status.state) + CATALOG_STATE_MAX_STALE_MS
+    ? cached.status
+    : null;
+  if (requestCatalogStateFlight
+    && requestCatalogStateFlight.generation === generation
+    && sameRequestCatalogStateIdentity(requestCatalogStateFlight.identity, identity)) {
+    return servableStale ?? 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 };
+    }
+    // A refresh that failed must not evict a real reading. Before this function
+    // served stale entries, caching `unknown` cost at most the 250ms that state
+    // is allowed to live. Now that an expired observation is what callers are
+    // handed, overwriting one with `unknown` would take the answer AWAY from
+    // them on a transient failure -- `unknown` is not servable, so the next
+    // caller waits for a probe instead of getting the reading it would have had.
+    // Keep the observation and let its own age retire it.
+    const wouldEvictAnObservation = status.state === "unknown"
+      && requestCatalogStateCache?.generation === generation
+      && requestCatalogStateCache.status.state !== "unknown"
+      && sameRequestCatalogStateIdentity(requestCatalogStateCache.identity, identity);
+    if (requestCatalogStateFlight === flight && !wouldEvictAnObservation) {
+      requestCatalogStateCache = {
+        generation,
+        identity,
+        atMs: (io.now ?? Date.now)(),
+        status,
+      };
+    }
+    return status;
+  }).finally(() => {
+    if (requestCatalogStateFlight === flight) requestCatalogStateFlight = null;
+  });
+  flight = { generation, identity, promise };
+  requestCatalogStateFlight = flight;
+  // `promise` already absorbs its own failures, so leaving it unawaited here cannot
+  // surface as an unhandled rejection; the next caller picks up whatever it stored.
+  return servableStale ?? 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 {
@@ -653,13 +1031,57 @@ export interface RestartCodexAppServersResult {
   failed: Array<{ pid: number; error: string }>;
 }
 
+/**
+ * Platform-appropriate termination for a matched app-server.
+ *
+ * On Windows `process.kill(pid, "SIGTERM")` is not a graceful signal — it is an
+ * unconditional terminate of that one process, and it leaves the process tree
+ * behind. `taskkill /T /F` is therefore not an escalation there: the kill was
+ * hard either way, and `/T` adds the child cleanup that keeps an app-server's
+ * children from being orphaned when the window is closed without a quit
+ * affordance. That matters most on Windows precisely because there is no Ctrl+Q.
+ *
+ * The asymmetry with Unix is deliberate and must not be "fixed" into symmetry:
+ * on Unix, SIGTERM really is graceful, and following it with SIGKILL would ask a
+ * harsher consent than a restart click gives. Survivors are reported instead.
+ *
+ * The executable is resolved from a trusted system directory rather than PATH,
+ * matching how this file already resolves PowerShell — an unqualified
+ * `taskkill` is a hijack surface.
+ */
+function defaultKillCodexAppServer(
+  pid: number,
+  signal: NodeJS.Signals,
+  io: CodexAppServerProcessIo = {},
+): void {
+  const platform = io.platform ?? process.platform;
+  const signalProcess = io.processKill ?? ((target: number, sig: NodeJS.Signals) => {
+    process.kill(target, sig);
+  });
+  if (platform !== "win32") {
+    signalProcess(pid, signal);
+    return;
+  }
+  const exec = io.execFile ?? ((file: string, args: readonly string[]) => {
+    execFileSync(file, [...args], { stdio: "ignore", timeout: 5_000, windowsHide: true });
+  });
+  try {
+    exec(resolveTrustedWindowsTaskkillExe(), ["/PID", String(pid), "/T", "/F"]);
+  } catch {
+    // Fall back to the previous behavior rather than reporting a failure the old
+    // code would not have reported.
+    signalProcess(pid, signal);
+  }
+}
+
+
 /** Send SIGTERM to matched processes and wait briefly; never escalates to SIGKILL. */
 export function restartCodexAppServers(
   processes: readonly CodexAppServerProcess[] = listCodexAppServerProcesses(),
   io: CodexAppServerProcessIo = {},
 ): RestartCodexAppServersResult {
   const isAlive = io.isAlive ?? isProcessAlive;
-  const kill = io.kill ?? ((pid, signal) => { process.kill(pid, signal); });
+  const kill = io.kill ?? ((pid, signal) => { defaultKillCodexAppServer(pid, signal, io); });
   const wait = io.waitExit ?? waitForExit;
   const now = io.now ?? Date.now;
   const requested = processes.map(process => process.pid);
@@ -754,3 +1176,44 @@ export function afterCatalogWriteHandleAppServers(
   }
   return { processes, warned: false, restart, hint };
 }
+
+/**
+ * Startup-safe counterpart to {@link afterCatalogWriteHandleAppServers} (#1046).
+ *
+ * Service startup rewrites the catalog and the models cache, but an app-server
+ * that booted earlier keeps an in-memory model list — Codex builds a static
+ * manager from the catalog once and never rereads the file — so the picker shows
+ * a roster that no longer exists on disk. Every check a user runs reads the file;
+ * the picker renders memory.
+ *
+ * Two things this deliberately does NOT do, both of which the `--restart-codex`
+ * path does:
+ *
+ * - It never signals anything. Killing an app-server on an unattended boot would
+ *   interrupt whatever turn the user has in flight. A human typing
+ *   `ocx sync --restart-codex` is consenting to that; a login is not.
+ * - It never warns about a merely-running app-server. It asks the mtime
+ *   classifier whether one is actually stale, so a boot with Codex open and a
+ *   current catalog stays quiet.
+ *
+ * Failure is swallowed: startup synchronization is best-effort and must not stop
+ * the proxy from coming up.
+ *
+ * The memoized state is dropped first. {@link collectCodexAppServerCatalogState}
+ * caches for 5s when every io field is defaulted, so a `fresh` reading taken
+ * before the write would otherwise be replayed after it and this would stay
+ * silent about the very staleness it exists to report.
+ */
+export function warnIfStaleCodexAppServersAfterStartupWrite(
+  options: { log?: Pick<Console, "error">; io?: CodexAppServerProcessIo } = {},
+): { warned: boolean } {
+  try {
+    resetCodexAppServerCatalogStateCache();
+    const status = collectCodexAppServerCatalogState(options.io ?? {});
+    if (status.state !== "stale") return { warned: false };
+    options.log?.error(formatStaleCodexAppServerWarning(status.processes));
+    return { warned: true };
+  } catch {
+    return { warned: false };
+  }
+}