@bitkyc08/opencodex 2.36.0-preview.20260829 → 2.36.0

package/src/service.ts

@@ -7,16 +7,16 @@
  */
 import { execFileSync, execSync, spawnSync } from "node:child_process";
 import { findLiveProxy, proxyIdentityAt, SERVICE_STOP_LIVENESS } from "./server/proxy-liveness";
-import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmdirSync, unlinkSync, writeFileSync } from "node:fs";
+import { accessSync, chmodSync, constants as fsConstants, existsSync, mkdirSync, mkdtempSync, readFileSync, rmdirSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
-import { dirname, join, posix, resolve, win32 } from "node:path";
+import { delimiter, dirname, isAbsolute, join, posix, resolve, win32 } from "node:path";
 import { expandUserPath, getConfigDir, loadConfig } from "./config";
 import { readPid, removePid, removeRuntimePort, verifyPidIdentity } from "./config/process-state";
 import { restoreNativeCodex, restoreNativeCodexAsync } from "./codex/inject";
 import { stripGrokConfig } from "./grok/inject";
 import { isWslRuntime, resolveCodexHomeDir, type CodexHomeDeps } from "./codex/home";
 import { BUN_RUNTIME_PATH_ENV, BUN_RUNTIME_SOURCE_ENV, durableBunRuntime } from "./lib/bun-runtime";
-import type { BunRuntimeSource } from "./lib/bun-runtime";
+import type { BunRuntimeSource, DurableBunRuntime } from "./lib/bun-runtime";
 import { isProcessAlive, stopProxy } from "./lib/process-control";
 import { serviceApiTokenFilePath } from "./lib/service-secrets";
 import { tokenCollidesWithAdmin } from "./lib/admin-secrets";
@@ -49,23 +49,66 @@ import { windowsEnvIndirectBatchPathList, windowsEnvIndirectBatchValue } from ".
 import { recordOwnedConfigPath } from "./lib/config-ownership";
 import { killWindowsSchedulerWrappers } from "./lib/windows-service-wrappers";
 import { maybeShowStarPrompt } from "./cli/star-prompt";
+import { systemdProperty } from "./service-manager-probe";
 
 const LABEL = "com.opencodex.proxy";
 const TASK = "opencodex-proxy";
 
 export type ServiceBackend = "scheduler" | "native";
 
-function cliEntry(): { bun: string; bunRuntimeSource: BunRuntimeSource; cli: string } {
+function cliEntry(runtime: DurableBunRuntime = durableBunRuntime()): { bun: string; bunRuntimeSource: BunRuntimeSource; cli: string } {
   // Bake the bundled Bun (npm global prefix, survives `ocx update`) rather than
   // a transient system Bun, so launchd/systemd/schtasks keep resolving even if a
   // standalone Bun is later removed. The CLI entry lives at src/cli/index.ts.
   //
   // Path and provenance come from ONE resolution so the marker can never describe a
   // different binary than the one actually baked.
-  const runtime = durableBunRuntime();
   return { bun: runtime.path, bunRuntimeSource: runtime.source, cli: join(import.meta.dir, "cli", "index.ts") };
 }
 
+/**
+ * The stable `ocx` launcher to bake into a systemd unit, or null to fall back to the
+ * Bun + CLI pair.
+ *
+ * `cliEntry()` resolves both of its paths from `import.meta.dir`, so they point INSIDE
+ * the installed package tree. Under a version manager that tree is a versioned directory:
+ * `~/.local/share/mise/installs/npm-opencodex/2.35.0/...`. An upgrade installs 2.36.0 and
+ * deletes 2.35.0, after which the unit's `exec <old-bun> <old-cli>` cannot resolve, and
+ * `Restart=on-failure` turns that into a restart loop (#2898). The shim in
+ * `~/.local/share/mise/shims/ocx` survives the upgrade and dispatches to whatever version
+ * is current, so it is the durable thing to name.
+ *
+ * Deliberately LEXICAL. Resolving the symlink would write the versioned target back into
+ * the unit and reintroduce the bug — the indirection is the entire point.
+ *
+ * Only an absolute path is accepted. A bare `ocx` would be re-resolved through `PATH` on
+ * every restart, which turns a service definition into a PATH-hijacking surface; naming
+ * one validated absolute file keeps the target fixed at install time.
+ */
+export function stableLauncherEntry(deps: {
+  env?: NodeJS.ProcessEnv;
+  isExecutableFile?: (path: string) => boolean;
+  pathDelimiter?: string;
+} = {}): string | null {
+  const env = deps.env ?? process.env;
+  const isExecutableFile = deps.isExecutableFile ?? ((path: string): boolean => {
+    try {
+      if (!statSync(path).isFile()) return false;
+      accessSync(path, fsConstants.X_OK);
+      return true;
+    } catch {
+      return false;
+    }
+  });
+  const entries = (env.PATH ?? "").split(deps.pathDelimiter ?? delimiter);
+  for (const entry of entries) {
+    if (!entry || !isAbsolute(entry)) continue;
+    const candidate = join(entry, "ocx");
+    if (isExecutableFile(candidate)) return candidate;
+  }
+  return null;
+}
+
 function plistPath(): string {
   return join(homedir(), "Library", "LaunchAgents", `${LABEL}.plist`);
 }
@@ -154,6 +197,14 @@ export interface ServiceInstallState {
   /** Baked at install; lets status flag paths gone stale after npm prefix/nvm moves. */
   bunPath?: string;
   cliPath?: string;
+  /**
+   * Linux only. The stable `ocx` launcher the unit actually invokes, when one was found.
+   * Present means `bunPath`/`cliPath` are provenance for the install, NOT what systemd
+   * runs — so staleness must be judged against THIS path instead. A version-manager
+   * upgrade replaces the directory those two point into while the launcher survives, and
+   * checking the old pair would report a stale service that is in fact healthy.
+   */
+  launcherPath?: string;
   /** v2: which Windows backend was chosen at install; absent (v1/legacy) means scheduler. */
   backend?: ServiceBackend;
   winswVersion?: string;
@@ -166,7 +217,7 @@ export function parseServiceInstallState(value: unknown): ServiceInstallState |
   if (state.version !== 1 && state.version !== 2) return null;
   if (typeof state.codexHome !== "string" || state.codexHome.length === 0) return null;
   if (typeof state.opencodexHome !== "string" || state.opencodexHome.length === 0) return null;
-  for (const key of ["bunPath", "cliPath", "winswVersion", "winswSha256"] as const) {
+  for (const key of ["bunPath", "cliPath", "launcherPath", "winswVersion", "winswSha256"] as const) {
     if (state[key] !== undefined && (typeof state[key] !== "string" || state[key].length === 0)) return null;
   }
   if (state.version === 1) {
@@ -177,7 +228,7 @@ export function parseServiceInstallState(value: unknown): ServiceInstallState |
   return state as unknown as ServiceInstallState;
 }
 
-function writeServiceInstallState(backend: ServiceBackend = "scheduler"): void {
+function writeServiceInstallState(backend: ServiceBackend = "scheduler", launcherPath?: string | null): void {
   const { bun, cli } = cliEntry();
   const state: ServiceInstallState = {
     version: 2,
@@ -185,6 +236,7 @@ function writeServiceInstallState(backend: ServiceBackend = "scheduler"): void {
     opencodexHome: currentOpenCodexHome(),
     bunPath: bun,
     cliPath: cli,
+    ...(launcherPath ? { launcherPath } : {}),
     backend,
     ...(backend === "native" ? { winswVersion: WINSW_VERSION, winswSha256: WINSW_SHA256 } : {}),
   };
@@ -500,6 +552,17 @@ function buildServiceShellCommand(bun: string, cli: string, port = resolveServic
   return `if [ -f ${shellQuote(tokenFile)} ]; then OPENCODEX_API_AUTH_TOKEN="$(cat ${shellQuote(tokenFile)})"; export OPENCODEX_API_AUTH_TOKEN; fi; exec ${shellQuote(bun)} ${shellQuote(cli)} start --port ${port}`;
 }
 
+/**
+ * The same command shape, launched through a stable `ocx` executable instead of an
+ * explicit Bun + CLI pair. The token-file preamble is identical and deliberately shared
+ * in form: the service still reads the token from disk at start and never carries it in
+ * the unit.
+ */
+function buildServiceLauncherShellCommand(launcher: string, port = resolveServiceListenPort()): string {
+  const tokenFile = serviceApiTokenFilePath();
+  return `if [ -f ${shellQuote(tokenFile)} ]; then OPENCODEX_API_AUTH_TOKEN="$(cat ${shellQuote(tokenFile)})"; export OPENCODEX_API_AUTH_TOKEN; fi; exec ${shellQuote(launcher)} start --port ${port}`;
+}
+
 /**
  * The `--port <n>` actually baked into the installed launchd plist, or null when it
  * cannot be read. macOS only — named for launchd rather than "service" so no caller
@@ -706,12 +769,6 @@ export function resolvedProxyEnv(env: NodeJS.ProcessEnv = process.env): { name:
   return resolved;
 }
 
-function systemdOutputTarget(value: string): string {
-  // StandardOutput/StandardError use output specifiers such as append:/path.
-  // Quoting the full specifier makes systemd reject it as an invalid output target.
-  return value.replace(/%/g, "%%").replace(/\n/g, "\\n");
-}
-
 function sh(cmd: string): string {
   return execSync(cmd, { encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] }).trim();
 }
@@ -2512,6 +2569,14 @@ function uninstallWindows(): void {
  */
 export function bakedServicePathsDiagnostic(): string | null {
   const state = readServiceInstallState();
+  // A launcher install runs the launcher, not the baked pair, so the pair's existence says
+  // nothing about whether the service can start. Judging the recorded launcher is both
+  // necessary (a deleted launcher IS stale) and sufficient (a replaced version directory
+  // is not, which is exactly what #2898 made routine).
+  if (state?.launcherPath) {
+    if (existsSync(state.launcherPath)) return null;
+    return `STALE baked paths (missing: ${state.launcherPath}) — run 'ocx service repair' to re-bake`;
+  }
   if (!state?.bunPath || !state?.cliPath) return null;
   const missing = [state.bunPath, state.cliPath].filter(path => !existsSync(path));
   if (missing.length === 0) return null;
@@ -2532,8 +2597,16 @@ function unitPath(): string {
   return join(unitDir(), `${TASK}.service`);
 }
 
-export function buildUnit(proxyEnv: { name: string; value: string }[] = resolvedProxyEnv()): string {
-  const { bun, bunRuntimeSource, cli } = cliEntry();
+export function buildUnit(
+  proxyEnv: { name: string; value: string }[] = resolvedProxyEnv(),
+  deps: { launcher?: string | null; runtime?: DurableBunRuntime } = {},
+): string {
+  const runtime = deps.runtime ?? durableBunRuntime();
+  const { bun, bunRuntimeSource, cli } = cliEntry(runtime);
+  // Discovery belongs to installSystemd(), which resolves once and passes the same value to
+  // both the unit and install state. Keeping this builder explicit makes tests and diagnostics
+  // independent of the host PATH.
+  const launcher = deps.launcher ?? null;
   const log = logPath();
   const path = process.env.PATH ?? "/usr/local/bin:/usr/bin:/bin";
   const codexHome = systemdEnvironmentAssignment("CODEX_HOME", process.env.CODEX_HOME?.trim());
@@ -2541,14 +2614,23 @@ export function buildUnit(proxyEnv: { name: string; value: string }[] = resolved
   const opencodexHome = systemdEnvironmentAssignment("OPENCODEX_HOME", process.env.OPENCODEX_HOME?.trim());
   const envLines = [
     systemdEnvironmentAssignment("OCX_SERVICE", "1"),
-    systemdEnvironmentAssignment(BUN_RUNTIME_SOURCE_ENV, bunRuntimeSource),
-    systemdEnvironmentAssignment(BUN_RUNTIME_PATH_ENV, bun),
+    ...(launcher ? [] : [
+      systemdEnvironmentAssignment(BUN_RUNTIME_SOURCE_ENV, bunRuntimeSource),
+      systemdEnvironmentAssignment(BUN_RUNTIME_PATH_ENV, bun),
+    ]),
+    // A launcher normally resolves the current package's bundled Bun after every upgrade.
+    // Preserve only a proof-bound shell override; otherwise writing a package-local path here
+    // would recreate the version-manager pin that the launcher mode exists to remove.
+    launcher && runtime.source === "override"
+      ? systemdEnvironmentAssignment(runtime.overrideEnv, runtime.path)
+      : null,
     systemdEnvironmentAssignment("PATH", path),
     codexHome,
     codexSqliteHome,
     opencodexHome,
     ...proxyEnv.map(({ name, value }) => systemdEnvironmentAssignment(name, value)),
   ].filter((line): line is string => Boolean(line)).join("\n");
+  const command = `${launcher ? buildServiceLauncherShellCommand(launcher) : buildServiceShellCommand(bun, cli)} >> ${shellQuote(log)} 2>&1`;
   return `[Unit]
 Description=OpenCodex Proxy Server
 After=network-online.target
@@ -2556,12 +2638,10 @@ Wants=network-online.target
 
 [Service]
 Type=simple
-ExecStart=${systemdQuote("/bin/sh")} -lc ${systemdQuote(buildServiceShellCommand(bun, cli))}
+ExecStart=${systemdQuote("/bin/sh")} -lc ${systemdQuote(command)}
 Restart=on-failure
 RestartSec=5
 ${envLines}
-StandardOutput=${systemdOutputTarget(`append:${log}`)}
-StandardError=${systemdOutputTarget(`append:${log}`)}
 
 [Install]
 WantedBy=default.target
@@ -2608,11 +2688,14 @@ function installSystemd(): void {
   recordOwnedConfigPath(getConfigDir(), serviceStatePath());
   if (!existsSync(getConfigDir())) mkdirSync(getConfigDir(), { recursive: true });
   writeServiceApiTokenFile();
-  writeServiceDefinitionFile(unitPath(), buildUnit(), "utf8");
+  // Resolve ONCE and reuse: the unit and the install state must agree about what is
+  // launched, or the staleness check would validate a path the unit does not run.
+  const launcher = stableLauncherEntry();
+  writeServiceDefinitionFile(unitPath(), buildUnit(resolvedProxyEnv(), { launcher }), "utf8");
   sh("systemctl --user daemon-reload");
   sh(`systemctl --user enable ${TASK}`);
   sh(`systemctl --user restart ${TASK}`);
-  writeServiceInstallState();
+  writeServiceInstallState("scheduler", launcher);
 }
 /**
  * Whether systemd's in-memory unit differs from the file on disk.
@@ -2660,10 +2743,18 @@ function startSystemd(): void {
 }
 function stopSystemd(): void { try { sh(`systemctl --user stop ${TASK}`); } catch { /* not running */ } }
 function statusSystemd(): string { try { return sh(`systemctl --user status ${TASK}`); } catch { return ""; } }
-function uninstallSystemd(): void {
-  try { sh(`systemctl --user disable --now ${TASK}`); } catch { /* absent */ }
-  if (existsSync(unitPath())) unlinkSync(unitPath());
-  try { sh("systemctl --user daemon-reload"); } catch { /* best-effort */ }
+export function uninstallSystemd(deps: {
+  run?: (command: string) => string;
+  unitExists?: () => boolean;
+  removeUnit?: () => void;
+} = {}): void {
+  const run = deps.run ?? sh;
+  try { run(`systemctl --user stop ${TASK}`); } catch { /* not running */ }
+  try { run(`systemctl --user disable ${TASK}`); } catch { /* absent */ }
+  if ((deps.unitExists ?? (() => existsSync(unitPath())))()) {
+    (deps.removeUnit ?? (() => unlinkSync(unitPath())))();
+  }
+  try { run("systemctl --user daemon-reload"); } catch { /* best-effort */ }
 }
 
 type ServiceOps = {
@@ -2676,6 +2767,21 @@ type ServiceInstallCleanupOps = {
   stop: () => void;
 };
 
+export function systemdServiceInstallCleanupOps(deps: {
+  run?: (command: string) => string;
+} = {}): ServiceInstallCleanupOps {
+  const run = deps.run ?? sh;
+  return {
+    status: () => {
+      const output = run(`systemctl --user show -p LoadState ${TASK}`);
+      const loadState = systemdProperty(output, "LoadState")?.toLowerCase();
+      if (!loadState) throw new Error("systemd service status could not be verified.");
+      return loadState === "not-found" ? null : loadState;
+    },
+    stop: () => { run(`systemctl --user stop ${TASK}`); },
+  };
+}
+
 function platformOps(backend: ServiceBackend = "scheduler"): ServiceOps | null {
   if (process.platform === "darwin")
     return { install: installLaunchd, start: startLaunchd, stop: stopLaunchd, status: statusLaunchd, uninstall: uninstallLaunchd };
@@ -2744,20 +2850,13 @@ function platformServiceInstallCleanupOps(backend: ServiceBackend): ServiceInsta
     };
   }
   if (process.platform === "linux") {
-    return {
-      status: () => {
-        // `list-unit-files <name>` exits non-zero when the unit has never been
-        // installed, which made a clean first install look like an unknown manager
-        // failure. `show LoadState` gives us the tri-state we actually need: a
-        // healthy user manager returns `not-found` for a missing unit, while an
-        // unreachable/permission-denied manager still makes `sh()` throw and the
-        // caller therefore fails closed.
-        const loadState = sh(`systemctl --user show ${TASK} --property=LoadState --value`).trim().toLowerCase();
-        if (!loadState) throw new Error("systemd service status could not be verified.");
-        return loadState === "not-found" ? null : loadState;
-      },
-      stop: () => { sh(`systemctl --user stop ${TASK}`); },
-    };
+    // `list-unit-files <name>` exits non-zero when the unit has never been
+    // installed, which made a clean first install look like an unknown manager
+    // failure. `show LoadState` gives us the tri-state we actually need: a
+    // healthy user manager returns `not-found` for a missing unit, while an
+    // unreachable/permission-denied manager still makes `sh()` throw and the
+    // caller therefore fails closed.
+    return systemdServiceInstallCleanupOps();
   }
   return null;
 }

package/src/storage/cleanup.ts

@@ -2578,6 +2578,11 @@ export interface RestoreTestHooks {
    * reconcile, so cleanup can race an in-flight restore.
    */
   holdAfterFileMovesMs?: number;
+  /**
+   * Test-only: publish a ready file after rollout moves, then wait until the
+   * release file exists. This makes cross-thread race tests phase-driven.
+   */
+  pauseAfterFileMoves?: { readyPath: string; releasePath: string };
 }
 
 /**
@@ -2917,6 +2922,11 @@ export function restoreTrashEntry(
     return { ok: false, trashDir: id, ...partialCounts, error };
   };
 
+  if (hooks?.pauseAfterFileMoves) {
+    writeFileSync(hooks.pauseAfterFileMoves.readyPath, "ready\n");
+    while (!existsSync(hooks.pauseAfterFileMoves.releasePath)) Bun.sleepSync(10);
+  }
+
   if (hooks?.holdAfterFileMovesMs !== undefined) {
     const holdMs = Math.max(0, Math.floor(hooks.holdAfterFileMovesMs));
     if (holdMs > 0) {

package/src/storage/storage-mutation-coordinator.ts

@@ -16,6 +16,12 @@ export type StorageMutationBusyError = "storage_mutation_busy";
 export interface StorageMutationCoordinatorTestHooks {
   /** Block after acquiring the slot, before mutation work (race tests). */
   blockMs?: number;
+  /** Test-only cross-thread handshake after one mutation kind acquires its slot. */
+  pauseAfterAcquire?: {
+    kind: StorageMutationKind;
+    readyPath: string;
+    releasePath: string;
+  };
 }
 
 interface ActiveSlot {
@@ -93,7 +99,12 @@ export function endStorageMutation(codexHome?: string): void {
   slot.lease.release();
 }
 
-async function applyCoordinatorBlock(): Promise<void> {
+async function applyCoordinatorBlock(kind: StorageMutationKind): Promise<void> {
+  const pause = testHooks?.pauseAfterAcquire;
+  if (pause?.kind === kind) {
+    await Bun.write(pause.readyPath, "ready\n");
+    while (!Bun.file(pause.releasePath).size) await Bun.sleep(10);
+  }
   const blockMs = testHooks?.blockMs;
   if (typeof blockMs === "number" && Number.isFinite(blockMs) && blockMs > 0) {
     await Bun.sleep(Math.floor(blockMs));
@@ -114,7 +125,7 @@ export async function runPolicyStorageMutation<T>(
     return { ok: false, error: "storage_mutation_busy" };
   }
   try {
-    await applyCoordinatorBlock();
+    await applyCoordinatorBlock("policy");
     return await work();
   } finally {
     gate.lease.release();
@@ -131,7 +142,7 @@ export async function withStorageMutationSlot<T>(
     return { ok: false, error: "storage_mutation_busy" };
   }
   try {
-    await applyCoordinatorBlock();
+    await applyCoordinatorBlock(kind);
     return await work();
   } finally {
     gate.lease.release();

package/src/tray/windows-tray.ps1

@@ -13,6 +13,7 @@ param(
 $ErrorActionPreference = "Stop"
 Add-Type -AssemblyName System.Windows.Forms
 Add-Type -AssemblyName System.Drawing
+try { [System.Windows.Forms.Application]::EnableVisualStyles() } catch { $null = $_ }
 
 # Normalize aliases before deriving singleton/event names. Without this,
 # C:\path and C:\path\. create separate tray instances for the same home.
@@ -68,6 +69,7 @@ if (-not $createdNew) {
   $mutex.Dispose()
   exit 0
 }
+[void]$stopEvent.Reset()
 
 $heartbeatPath = Join-Path $OpenCodexHome "tray-heartbeat.json"
 $actionLogPath = Join-Path $OpenCodexHome "tray-actions.log"
@@ -332,11 +334,15 @@ $notify.add_DoubleClick({ Start-OcxCommand @("gui") })
 $timer = New-Object System.Windows.Forms.Timer
 $timer.Interval = 3000
 $timer.add_Tick({
-  if ($stopEvent.WaitOne(0)) {
-    [System.Windows.Forms.Application]::Exit()
-    return
+  try {
+    if ($stopEvent.WaitOne(0)) {
+      [System.Windows.Forms.Application]::Exit()
+      return
+    }
+    Update-TrayState
+  } catch {
+    try { Write-ActionLog "timer tick failed: $($_.Exception.GetType().Name)" } catch { $null = $_ }
   }
-  Update-TrayState
 })
 $notify.ContextMenuStrip = $menu
 $notify.Icon = $offlineIcon

package/src/tray/windows.ts

@@ -2,7 +2,7 @@ import { execFile, execFileSync, spawn } from "node:child_process";
 import { createHash } from "node:crypto";
 import { chmodSync, existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { join, resolve } from "node:path";
+import { join, resolve, win32 as win32Path } from "node:path";
 import { expandUserPath, getConfigDir } from "../config";
 import { durableBunRuntime } from "../lib/bun-runtime";
 import type { BunRuntimeSource } from "../lib/bun-runtime";
@@ -46,6 +46,12 @@ export interface WindowsTrayStatus {
   summary: string;
 }
 
+export type WindowsTrayLaunchRunner = (
+  file: string,
+  args: readonly string[],
+  options: { stdio: "ignore"; windowsHide: true; timeout: number },
+) => void;
+
 function trayStatePath(): string {
   return join(getConfigDir(), "tray-state.json");
 }
@@ -506,8 +512,10 @@ const DETACHED_TRAY_HOST_LAUNCHER = [
   "$startInfo = New-Object System.Diagnostics.ProcessStartInfo",
   "$startInfo.FileName = $env:OCX_TRAY_HOST_BUN",
   "$startInfo.Arguments = $env:OCX_TRAY_HOST_ARGS",
-  "$startInfo.UseShellExecute = $true",
+  "$startInfo.UseShellExecute = $false",
+  "$startInfo.CreateNoWindow = $true",
   "$startInfo.WindowStyle = [System.Diagnostics.ProcessWindowStyle]::Hidden",
+  "$startInfo.EnvironmentVariables['OCX_TRAY_ENTRY_B64'] = $env:OCX_TRAY_ENTRY_B64",
   "$child = [System.Diagnostics.Process]::Start($startInfo)",
   "if ($null -eq $child) { throw 'Windows tray host did not start.' }",
   "$child.Dispose()",
@@ -537,7 +545,27 @@ export function launchWindowsTrayHost(state: WindowsTrayEntry): void {
   });
 }
 
+export function launchInstalledWindowsTray(
+  launcherPath: string,
+  deps: { systemRoot?: string; run?: WindowsTrayLaunchRunner } = {},
+): void {
+  const wscript = win32Path.join(deps.systemRoot ?? process.env.SystemRoot ?? "C:\\Windows", "System32", "wscript.exe");
+  const run = deps.run ?? ((file, args, options) => {
+    execFileSync(file, [...args], options);
+  });
+  run(wscript, ["//B", "//NoLogo", safePath(launcherPath)], {
+    stdio: "ignore",
+    windowsHide: true,
+    timeout: 15_000,
+  });
+}
+
 function spawnTray(state: WindowsTrayEntry): void {
+  const launcher = installedTrayLauncherPath();
+  if (existsSync(launcher)) {
+    launchInstalledWindowsTray(launcher);
+    return;
+  }
   launchWindowsTrayHost(state);
 }
 

package/src/types/config.ts

@@ -435,17 +435,26 @@ export interface OcxConfig {
   * Shadow call intercept: redirect Codex's hard-coded helper calls (title generation,
   * commit messages, skill orchestration) to a user-chosen model. Default intercepted
   * source models: gpt-5.4-mini (older clients) and gpt-5.6-luna (Codex 0.145.0+).
-  * Opt-in; disabled by default. Matching maintenance/helper requests are forced to low.
-   * All requests for configured shadow source models are intercepted unconditionally.
-   */
-  shadowCallIntercept?: {
-    /** When true, requests for known shadow/helper source models are rewritten to the configured model. */
-    enabled?: boolean;
-    /** Replacement model id (e.g. "gpt-5.5"). */
-    model?: string;
-    /** Optional override of intercepted source-model prefixes (default: gpt-5.4-mini, gpt-5.6-luna). */
-    sourceModels?: string[];
-  };
+  * Opt-in; disabled by default. Matching requests preserve their configured reasoning effort.
+  * All requests for configured shadow source models are intercepted regardless of request kind,
+  * except when the replacement intersects the same provider+model source set.
+  */
+ shadowCallIntercept?: {
+   /** When true, requests for known shadow/helper source models are rewritten to the configured model. */
+   enabled?: boolean;
+   /** Replacement model id (e.g. "gpt-5.5"). */
+   model?: string;
+   /** Optional override of intercepted source-model prefixes (default: gpt-5.4-mini, gpt-5.6-luna). */
+   sourceModels?: string[];
+ };
+  /**
+   * Optional map of blocked model IDs to their replacement model IDs.
+   * When configured, incoming requests targeting a blocked model (including
+   * account-namespaced and concrete routes) are redirected to the replacement
+   * model at the shared routing layer with routeReason "blocked-model-redirect".
+   * Unset or omitted by default.
+   */
+  blockedModelRedirects?: Record<string, string>;
   /**
    * 3-state multi-agent surface override:
    * - "v1": force ALL models to v1 surface (override upstream pins)
@@ -619,6 +628,8 @@ export interface OcxConfig {
     strategy?: OcxAccountPoolRotationStrategy;
     /** Successful new-session binds retained on one round-robin selection. Default 1; range 1..100. */
     stickyLimit?: number;
+    /** Usage window for quota-based scoring. Default "five-hour" (today's behaviour). */
+    quotaWindow?: OcxAccountPoolQuotaWindow;
   };
   /**
    * Generic OAuth multi-account 429 failover (#2568). Presence-driven by default.
@@ -653,19 +664,21 @@ export interface OcxConfig {
 
 export type OcxAccountPoolRotationStrategy = "quota" | "round-robin" | "fill-first";
 
-export type OcxComboStrategy = "failover" | "round-robin";
+export type OcxAccountPoolQuotaWindow = "five-hour" | "weekly" | "max-utilization";
+
+export type OcxComboStrategy = "failover" | "round-robin" | "random" | "least-used" | "reset-window";
 export type OcxComboDefaultEffort = "low" | "medium" | "high" | "xhigh" | "max" | "ultra";
 
 export interface OcxComboTarget {
   provider: string;
   model: string;
-  /** Relative SWRR batch weight. Default 1; valid range 1..10000. */
+  /** Relative target weight for round-robin batches and random selection. Default 1; valid range 1..10000. */
   weight?: number;
 }
 
 export interface OcxComboConfig {
   targets: OcxComboTarget[];
-  /** Ordered failover (default) or deterministic smooth weighted round-robin. */
+  /** Ordered failover (default), round-robin, weighted random, least-used, or quota reset-window selection. */
   strategy?: OcxComboStrategy;
   /** Successful requests retained on one RR selection batch. Default 1; range 1..100. */
   stickyLimit?: number;

package/src/types/provider.ts

@@ -17,6 +17,15 @@ export interface OpenRouterProviderRouting {
   allowFallbacks?: boolean;
 }
 
+export interface VercelGatewayRouting {
+  /** Vercel AI Gateway provider slugs to try first, in priority order. */
+  order?: string[];
+  /** Restrict routing to these Vercel AI Gateway provider slugs. */
+  only?: string[];
+  /** Sort providers by "cost", "ttft", or "tps". */
+  sort?: "cost" | "ttft" | "tps";
+}
+
 export interface ResponsesItemIdRepairConfig {
   /** Exact `message` item ids that the proxy should rewrite to request-local canonical ids. */
   message?: string[];
@@ -32,6 +41,25 @@ export interface ResponsesItemIdRepairConfig {
   repairInvalidIds?: boolean;
 }
 
+/**
+ * Opt-in retry for pre-stream transient upstream statuses (500/502/503/504/520/521/522) on
+ * `providers.<name>.transientRetryOn5xx`.
+ *
+ * Disabled unless the object is present; a bare `{}` opts in with defaults. Separate from
+ * `retryOn429`, which handles rate limiting with its own waits.
+ */
+export interface TransientRetryPolicy {
+  /** Master switch. Presence of the object also enables the policy (default true). */
+  enabled?: boolean;
+  /**
+   * TOTAL upstream sends allowed for one request, including the first (1..10, default 3).
+   *
+   * Not a per-layer retry count: the connection-reset and transient-status recovery layers
+   * share this single budget, so `3` means at most three real requests reach the provider.
+   */
+  attempts?: number;
+}
+
 /**
  * Same-target 429 wait-and-retry policy (`providers.<name>.retryOn429`). When present and not
  * explicitly disabled, the proxy waits and replays the identical request on the same key before
@@ -197,6 +225,16 @@ export interface OcxProviderConfig {
    * preserved after it, and parallel calls stay together with the reasoning turn that produced them.
    */
   requiresAdjacentResponsesToolResults?: boolean;
+  /**
+   * When enabled, a tool result that is present but empty (no usable text or content
+   * part) is rewritten to an explicit annotation before it reaches the upstream wire,
+   * so models do not silently accept an empty result or re-issue the same call.
+   * Non-empty results and missing-result placeholders stay byte-identical.
+   * Seeded true for DeepSeek; absent keeps legacy behavior for every other provider.
+   * Only the OpenAI-family adapters (openai-chat / openai-responses) read this option;
+   * other adapters ignore it.
+   */
+  annotateEmptyToolOutputs?: boolean;
   /**
    * Provider fallback for canonical Fast capability over an OpenAI `service_tier` wire.
    * This pure tri-state feeds catalog publication, routing eligibility, compatibility
@@ -342,6 +380,10 @@ export interface OcxProviderConfig {
   openRouterRouting?: OpenRouterProviderRouting;
   /** Exact model-id overrides for `openRouterRouting`. Each matching entry replaces the default. */
   modelOpenRouterRouting?: Record<string, OpenRouterProviderRouting>;
+  /** Default provider-routing preferences for models sent through Vercel AI Gateway (issue #1406). */
+  vercelGatewayRouting?: VercelGatewayRouting;
+  /** Exact model-id overrides for `vercelGatewayRouting`. Each matching entry replaces the default. */
+  modelVercelGatewayRouting?: Record<string, VercelGatewayRouting>;
   /**
    * "key" (default): authenticate upstream with `apiKey`.
    * "forward": relay the caller's incoming auth headers verbatim (OAuth passthrough; gpt only).
@@ -421,6 +463,12 @@ export interface OcxProviderConfig {
    * passthrough compatibility for OpenAI and unclassified gateways.
    */
   supportsOpenAiWebSearchToolFields?: boolean;
+  /**
+   * Opt xAI Responses destinations into the provider-hosted `x_search` declaration when a live
+   * `web_search` tool survives final request normalization. Disabled by default. This is separate
+   * from the web-search sidecar's `search.xSearch` options and never widens caller tool selectors.
+   */
+  xaiResponsesXSearch?: boolean;
   /**
    * Whether the Responses upstream accepts native custom tools and custom_tool_call items.
    * Set false only for a provider whose native contract rejects them; absence preserves
@@ -537,6 +585,12 @@ export interface OcxProviderConfig {
    * before any response bytes are relayed, so the replay is lossless.
    */
   retryOn429?: RateLimitRetryPolicy;
+  /**
+   * Opt-in retry for pre-stream transient upstream statuses
+   * (`providers.<name>.transientRetryOn5xx`). Disabled unless present; a bare `{}` opts in
+   * with defaults. Key-auth `openai-chat` only.
+   */
+  transientRetryOn5xx?: TransientRetryPolicy;
   /**
    * Model ids whose OpenAI-compatible chat endpoint accepts `reasoning_split: true` and returns
    * thinking separately in `reasoning_content` / `reasoning_details` instead of visible content.