@bitkyc08/opencodex 2.10.2 → 2.11.0

package/src/service.ts

@@ -2177,6 +2177,11 @@ type ServiceOps = {
   status: () => string; uninstall: () => void;
 };
 
+type ServiceInstallCleanupOps = {
+  status: () => string | null;
+  stop: () => void;
+};
+
 function platformOps(backend: ServiceBackend = "scheduler"): ServiceOps | null {
   if (process.platform === "darwin")
     return { install: installLaunchd, start: startLaunchd, stop: stopLaunchd, status: statusLaunchd, uninstall: uninstallLaunchd };
@@ -2202,6 +2207,67 @@ function platformOps(backend: ServiceBackend = "scheduler"): ServiceOps | null {
   return null;
 }
 
+/**
+ * Install-only manager operations. Unlike the ordinary status/stop helpers, these
+ * distinguish confirmed absence from a failed manager query and propagate every
+ * non-benign stop failure. Installing new assets is unsafe while either answer is
+ * unknown because an old manager may still respawn a listener on the target port.
+ */
+function platformServiceInstallCleanupOps(backend: ServiceBackend): ServiceInstallCleanupOps | null {
+  if (process.platform === "darwin") {
+    return {
+      status: () => {
+        const listing = sh("launchctl list");
+        return listing.split("\n").some(line => line.includes(LABEL)) ? listing : null;
+      },
+      stop: () => { sh(`launchctl unload "${plistPath()}"`); },
+    };
+  }
+  if (process.platform === "win32") {
+    if (backend === "native") {
+      return {
+        status: () => {
+          const status = statusWinswRaw();
+          if (status === "unknown") throw new Error("Native service status could not be verified.");
+          return status === "nonexistent" ? null : status;
+        },
+        stop: stopWinswService,
+      };
+    }
+    return {
+      status: () => {
+        const probe = probeWindowsSchedulerTask(TASK);
+        if (probe.status === "unknown") throw new Error(`Task Scheduler status could not be verified: ${probe.detail}`);
+        return probe.status === "present" ? "present" : null;
+      },
+      stop: () => {
+        try {
+          schtasks(["/end", "/tn", TASK]);
+        } catch (error) {
+          if (!isWindowsSchedulerEndBenign(error)) throw error;
+        }
+      },
+    };
+  }
+  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}`); },
+    };
+  }
+  return null;
+}
+
 type TrackedProxyCleanupResult = "none" | "stale" | "stopped";
 
 function verifiedKillTarget(pid: number | null | undefined): number | null {
@@ -2297,6 +2363,60 @@ async function stopTrackedProxyForServiceCommand(): Promise<TrackedProxyCleanupR
   }
 }
 
+export interface ServiceInstallPreparationDeps {
+  diagnose?: () => ServiceDiagnostic;
+  managerOps?: (backend: ServiceBackend) => ServiceInstallCleanupOps | null;
+  stopTrackedProxy?: () => Promise<unknown>;
+  platform?: NodeJS.Platform;
+}
+
+/**
+ * Stop every manager that could own the install port, then stop the tracked
+ * standalone listener. Any unknown status or cleanup failure rejects, so callers
+ * cannot write assets or report success over a surviving old listener.
+ */
+export async function prepareServiceInstall(
+  requestedBackend: ServiceBackend,
+  deps: ServiceInstallPreparationDeps = {},
+): Promise<void> {
+  const diagnostic = (deps.diagnose ?? diagnoseService)();
+  const platform = deps.platform ?? process.platform;
+  const resolveOps = deps.managerOps ?? platformServiceInstallCleanupOps;
+  const backends: ServiceBackend[] = [];
+  const addBackend = (backend: ServiceBackend) => {
+    if (!backends.includes(backend)) backends.push(backend);
+  };
+
+  if (platform === "win32") {
+    // The recorded backend owns the old installation and must be stopped first.
+    // A conflicting diagnostic means both managers exist, so stop both even when
+    // the requested backend happens to match the recorded one.
+    if (diagnostic.backend === "scheduler" || diagnostic.backend === "native") {
+      addBackend(diagnostic.backend);
+      if (diagnostic.conflict) addBackend(diagnostic.backend === "scheduler" ? "native" : "scheduler");
+    }
+    addBackend(requestedBackend);
+  } else {
+    addBackend(requestedBackend);
+  }
+
+  for (const backend of backends) {
+    const manager = resolveOps(backend);
+    if (!manager) throw new Error(`Background service manager is unavailable for ${backend}.`);
+    if (manager.status() !== null) manager.stop();
+  }
+  await (deps.stopTrackedProxy ?? stopTrackedProxyIfRunning)();
+}
+
+export async function installServiceSafely(
+  requestedBackend: ServiceBackend,
+  install: () => void | Promise<void>,
+  deps: ServiceInstallPreparationDeps = {},
+): Promise<void> {
+  await prepareServiceInstall(requestedBackend, deps);
+  await install();
+}
+
 /**
  * If a service is installed, stop it so the process manager doesn't respawn after `ocx stop`.
  * Returns true if a service was found and stopped.
@@ -2645,7 +2765,19 @@ export async function serviceCommand(...args: (string | undefined)[]): Promise<v
     case "install":
       assertServiceEnvironmentMatchesInstall();
       assertServiceAuthEnvironment();
-      await ops.install();
+      // A manually started proxy can still own the configured port while the service
+      // registration is absent or unloaded. Stop both the registered manager and any
+      // tracked standalone listener before loading the freshly written service assets.
+      // Otherwise launchd/Task Scheduler can register successfully while its child
+      // restart-loops on EADDRINUSE, and the old standalone process makes the install
+      // verification report a false success.
+      try {
+        await installServiceSafely(backend, ops.install);
+      } catch (error) {
+        console.error(`❌ Service install cleanup failed: ${error instanceof Error ? error.message : String(error)}`);
+        process.exitCode = 1;
+        break;
+      }
       // The wrapper was written moments ago in this process, so the configured port
       // and the baked one cannot have diverged yet — unlike `start`, which reads the
       // installed artifact instead.
@@ -2741,4 +2873,4 @@ export async function serviceCommand(...args: (string | undefined)[]): Promise<v
       console.error("       --native (Windows only): register a real SCM service via WinSW instead of Task Scheduler.");
       process.exit(1);
   }
-}
+}

package/src/storage/worker-lifecycle.ts

@@ -11,10 +11,9 @@
  * time (so we cannot miss `self.close()` / early exit), stays in `liveWorkers`
  * until that close settles, and `drainStorageWorkers()` joins every in-flight
  * terminate. Spawns are serialized through `withStorageWorkerSpawnGate` so the
- * next Worker cannot be created until prior threads have exited. On Windows and
- * macOS, a post-close settle covers the OS join gap Bun does not expose
- * (Windows unbalanced join panic; macOS Silicon balanced-count segfault under
- * `bun test --isolate`).
+ * next Worker cannot be created until prior threads have exited. A post-close
+ * settle covers the OS/runtime join gap Bun does not expose on Windows, macOS,
+ * and Linux (including Bun 1.3.14 isolate crashes and Linux `epoll_ctl` reuse).
  */
 
 import { createAdmissionGate, type AdmissionMetrics, type AdmissionReservation } from "../lib/admission";
@@ -52,15 +51,15 @@ let spawnCancelEpoch = 0;
 /**
  * OS-join gap after the `close` event on platforms where Bun's Worker reclaim
  * races the isolate/file boundary (not a CI job-timeout bump).
- * Windows GHA at 250ms and 750ms still left `workers_spawned(N)
- * workers_terminated(N-1)` panics under isolate (seen mid
- * `storage-mutation-race` with 11/10). 1500ms covers deferred reclaim under
- * stacked policy/restore workers. Darwin uses 250ms.
+ * Windows GHA at 250ms and 750ms still left `workers_spawned(N)`
+ * `workers_terminated(N-1)` panics under isolate, so Windows keeps 1500ms.
+ * Darwin and Linux use a shorter settle for the balanced-count/epoll reclaim
+ * window seen on Bun 1.3.14.
  */
-const WORKER_OS_JOIN_MS = process.platform === "win32" ? 1_500 : 250;
-
-function needsWorkerOsJoinSettle(): boolean {
-  return process.platform === "win32" || process.platform === "darwin";
+export function storageWorkerOsJoinSettleMs(platform = process.platform): number {
+  if (platform === "win32") return 1_500;
+  if (platform === "darwin" || platform === "linux") return 250;
+  return 0;
 }
 
 /** Invalidate spawn callbacks still waiting on the gate (reset / server drain). */
@@ -181,9 +180,10 @@ export function terminateStorageWorker(worker: Worker, timeoutMs = 5_000): Promi
       // only forces `closed`, it does not prove the OS thread has exited.
       // Callers that catch and continue (e.g. drainAndShutdown) still need
       // that gap before the next isolate reclaim or server.stop.
-      if (needsWorkerOsJoinSettle()) {
+      const settleMs = storageWorkerOsJoinSettleMs();
+      if (settleMs > 0) {
         await Bun.sleep(0);
-        await Bun.sleep(WORKER_OS_JOIN_MS);
+        await Bun.sleep(settleMs);
       }
       if (timedOut) {
         throw new Error(`storage worker did not exit within ${timeoutMs}ms`);

package/src/tray/windows-tray.ps1

@@ -84,7 +84,7 @@ function ConvertTo-NativeArgument([string]$Value) {
   return '"' + $Value + '"'
 }
 
-function Start-OcxCommand([string[]]$CommandArgs) {
+function Start-OcxCommand([string[]]$CommandArgs, [switch]$TrackExit) {
   try {
     $allArgs = @($CliPath) + $CommandArgs
     $psi = New-Object System.Diagnostics.ProcessStartInfo
@@ -102,8 +102,10 @@ function Start-OcxCommand([string[]]$CommandArgs) {
       $psi.EnvironmentVariables["OCX_BUN_RUNTIME_PATH"] = $BunPath
     }
     $process = [System.Diagnostics.Process]::Start($psi)
-    if ($null -ne $process) { $process.Dispose() }
+    if ($null -eq $process) { throw "Process did not start" }
     Write-ActionLog "dispatched $($CommandArgs -join ' ')"
+    if ($TrackExit) { return $process }
+    $process.Dispose()
     return $true
   } catch {
     Write-ActionLog "launch failed: $($_.Exception.GetType().Name)"
@@ -172,18 +174,40 @@ $script:pendingAction = $null
 $script:pendingStarted = 0L
 $script:pendingDeadline = 0L
 $script:pendingOldProxyPid = $null
+$script:pendingProcess = $null
 
 function Set-PendingAction([string]$Action, [int]$TimeoutSeconds) {
+  if ($null -ne $script:pendingAction) {
+    Write-ActionLog "$Action ignored because $($script:pendingAction) is still pending"
+    return $false
+  }
+  if ($null -ne $script:pendingProcess) {
+    try {
+      $script:pendingProcess.Dispose()
+    } catch {
+      Write-ActionLog "pending process dispose failed: $($_.Exception.GetType().Name)"
+    }
+    $script:pendingProcess = $null
+  }
   $script:pendingAction = $Action
   $script:pendingStarted = [DateTimeOffset]::UtcNow.ToUnixTimeMilliseconds()
   $script:pendingDeadline = $script:pendingStarted + ($TimeoutSeconds * 1000)
   $script:pendingOldProxyPid = $script:proxyPid
+  return $true
 }
 
 function Complete-PendingAction([bool]$Success) {
   if ($null -eq $script:pendingAction) { return }
   $action = $script:pendingAction
   $script:pendingAction = $null
+  if ($null -ne $script:pendingProcess) {
+    try {
+      $script:pendingProcess.Dispose()
+    } catch {
+      Write-ActionLog "pending process dispose failed: $($_.Exception.GetType().Name)"
+    }
+    $script:pendingProcess = $null
+  }
   if ($Success) {
     Write-ActionLog "$action completed (port=$($script:port), pid=$($script:proxyPid))"
     $notify.ShowBalloonTip(2500, "opencodex", "$action completed.", [System.Windows.Forms.ToolTipIcon]::Info)
@@ -226,6 +250,11 @@ function Update-TrayState {
     $stopItem.Enabled = $false
     $restartItem.Enabled = $false
   }
+  if ($null -ne $script:pendingAction) {
+    $startItem.Enabled = $false
+    $stopItem.Enabled = $false
+    $restartItem.Enabled = $false
+  }
   $heartbeat = @{ pid = $PID; timestamp = [DateTimeOffset]::UtcNow.ToUnixTimeMilliseconds() }
   if ($HostPid -gt 0) { $heartbeat.hostPid = $HostPid }
   $heartbeatJson = $heartbeat | ConvertTo-Json -Compress
@@ -237,26 +266,59 @@ function Update-TrayState {
     $reached = ($script:pendingAction -eq "Start Proxy" -and $script:online) -or
       ($script:pendingAction -eq "Stop Proxy" -and -not $script:online) -or
       ($script:pendingAction -eq "Restart Proxy" -and $elapsed -gt 3000 -and $script:online -and $script:proxyPid -ne $script:pendingOldProxyPid)
-    if ($reached) { Complete-PendingAction $true }
+    $commandFailed = $false
+    if ($null -ne $script:pendingProcess) {
+      try {
+        $commandFailed = $script:pendingProcess.HasExited -and $script:pendingProcess.ExitCode -ne 0
+      } catch {
+        Write-ActionLog "pending process result inspection failed: $($_.Exception.GetType().Name)"
+        # If we cannot inspect the tracked command, we cannot prove it is still
+        # healthy. Fail the pending action instead of silently waiting for a later
+        # timeout and presenting an indeterminate process as success-capable.
+        $commandFailed = $true
+      }
+    }
+    if ($commandFailed) { Complete-PendingAction $false }
+    elseif ($reached) { Complete-PendingAction $true }
     elseif ($now -gt $script:pendingDeadline) { Complete-PendingAction $false }
   }
 }
 
 $openItem.add_Click({ Start-OcxCommand @("gui") })
 $startItem.add_Click({
+  if (-not (Set-PendingAction "Start Proxy" 75)) { return }
   $statusItem.Text = "Proxy: Starting..."
-  Set-PendingAction "Start Proxy" 15
-  if (-not (Start-OcxCommand @("__tray-start"))) { $script:pendingAction = $null }
+  # service start can spend 20s and the CLI then observes health for another 40s.
+  $startProcess = Start-OcxCommand @("__tray-start") -TrackExit
+  if ($startProcess -is [System.Diagnostics.Process]) {
+    $script:pendingProcess = $startProcess
+  } else {
+    Complete-PendingAction $false
+  }
 })
 $stopItem.add_Click({
+  if (-not (Set-PendingAction "Stop Proxy" 15)) { return }
   $statusItem.Text = "Proxy: Stopping..."
-  Set-PendingAction "Stop Proxy" 15
-  if (-not (Start-OcxCommand @("stop"))) { $script:pendingAction = $null }
+  $stopProcess = Start-OcxCommand @("stop") -TrackExit
+  if ($stopProcess -is [System.Diagnostics.Process]) {
+    $script:pendingProcess = $stopProcess
+  } else {
+    Complete-PendingAction $false
+  }
 })
 $restartItem.add_Click({
+  if (-not (Set-PendingAction "Restart Proxy" 160)) { return }
   $statusItem.Text = "Proxy: Restarting..."
-  Set-PendingAction "Restart Proxy" 20
-  if (-not (Start-OcxCommand @("__tray-restart"))) { $script:pendingAction = $null }
+  # /api/system/restart may drain active work for 60s and then spend up to 70s
+  # handing off to an identity-verified replacement. The tray observes health/PID
+  # rather than the detached CLI exit, so keep a watchdog margin around that shared
+  # lifecycle budget. The CLI remains the lifecycle owner; the tray never kills.
+  $restartProcess = Start-OcxCommand @("__tray-restart") -TrackExit
+  if ($restartProcess -is [System.Diagnostics.Process]) {
+    $script:pendingProcess = $restartProcess
+  } else {
+    Complete-PendingAction $false
+  }
 })
 $logsItem.add_Click({
   $psi = New-Object System.Diagnostics.ProcessStartInfo
@@ -289,6 +351,9 @@ try {
   $timer.Stop()
   $timer.Dispose()
   $notify.Visible = $false
+  if ($null -ne $script:pendingProcess) {
+    try { $script:pendingProcess.Dispose() } catch { $null = $_ }
+  }
   $notify.Dispose()
   foreach ($icon in $script:ownedIcons) { $icon.Dispose() }
   $menu.Dispose()

package/src/types.ts

@@ -2,6 +2,8 @@ import type { KiroOAuthMetadata } from "./oauth/types";
 
 export interface OcxParsedRequest {
   modelId: string;
+  /** Client-facing model selector retained for Anthropic routes after wire-model normalization. */
+  _responseModelId?: string;
   /** Selected OpenAI API virtual-model id retained after it rewrites the upstream wire model. */
   _openAiVirtualSelectedModelId?: string;
   previousResponseId?: string;
@@ -164,6 +166,8 @@ export interface OcxTool {
   toolSearch?: boolean;
   /** Tool definition restored from a prior tool_search output; transports may prioritize it when catalogs are bounded. */
   loadedFromToolSearch?: boolean;
+  /** Cursor-only synthetic exact-match edit tool; never inferred from the wire name. */
+  cursorStructuredEdit?: true;
   /** Synthetic web_search tool: the model's call is executed by the gpt-5.4-mini sidecar, not relayed to Codex. */
   webSearch?: boolean;
   /** Synthetic image_gen tool: the model's call is executed by the xAI image bridge sidecar, not relayed to Codex. */
@@ -233,6 +237,20 @@ export interface OcxRequestOptions {
   frequencyPenalty?: number;
   /** Responses prompt-cache affinity key. Passthrough preserves it via _rawBody; routed adapters do not consume it unless their upstream wire supports it. */
   promptCacheKey?: string;
+  /**
+   * Responses `text.format` (json_schema / json_object), preserved for adapters whose
+   * upstream wire has an equivalent. The openai-chat adapter re-nests it as chat
+   * `response_format`, the exact inverse of responseFormatToText in src/chat/inbound.ts.
+   * The native passthrough ignores it (it forwards `_rawBody.text` verbatim) and Kiro
+   * keeps rejecting structured output via `_structuredOutput`.
+   */
+  textFormat?: {
+    type: "json_schema" | "json_object";
+    name?: string;
+    description?: string;
+    schema?: Record<string, unknown>;
+    strict?: boolean;
+  };
 }
 
 export type OcxMessagePhase = "commentary" | "final_answer";
@@ -553,6 +571,8 @@ export interface OcxClientIntegrationsConfig {
   codex?: boolean;
   /** Durable desired state for Grok Build. MISSING MEANS ON. */
   grok?: boolean;
+  /** Durable desired state for Claude Desktop. MISSING MEANS ON. */
+  "claude-desktop"?: boolean;
 }
 
 export interface OcxConfig {
@@ -708,6 +728,30 @@ export interface OcxConfig {
   contextCapValue?: number;
   /** Bind hostname. Default "127.0.0.1" (loopback only). Set "0.0.0.0" to expose on all interfaces. */
   hostname?: string;
+  /**
+   * Optional second listener bound to 127.0.0.1 that admits data-plane requests without a
+   * credential (issue #1102).
+   *
+   * Why a separate listener rather than an exemption on the main one: when `hostname` is a
+   * wildcard, every caller needs `x-opencodex-api-key`, but a `codex app-server` spawned
+   * directly from the resolved entrypoint never goes through the generated shim and so never
+   * inherits the token. Exempting "loopback-looking peers" on the public listener would be
+   * unsound — `requestIP()` only proves the last transport hop, and Docker Desktop port
+   * forwarding, host-network containers, WSL mirrored networking and tunnels all terminate
+   * remote connections locally. Binding a second socket to 127.0.0.1 makes the kernel refuse
+   * remote connections outright, so there is no address to judge.
+   *
+   * The public listener's admission policy is unchanged. This adds an explicit local trust
+   * surface: every process on the machine can reach it, spend account quota, and consume paid
+   * provider credentials. Off by default; not for multi-tenant hosts.
+   *
+   * The port is required when enabled and must differ from the proxy port. An OS-assigned port
+   * would change across restarts, which would break already-running app-servers holding the
+   * previous `base_url` — the exact symptom #1102 reported and we disproved for token rotation.
+   */
+  unauthenticatedLoopbackListener?:
+    | { enabled: false }
+    | { enabled: true; port: number };
   /**
    * Outbound HTTP(S) proxy URL for provider requests (e.g. "http://user:pass@proxy:8080", or
    * "${HTTPS_PROXY}"-style env reference). Mirrored into HTTP_PROXY/HTTPS_PROXY at startup when
@@ -762,12 +806,29 @@ export interface OcxConfig {
   codexAccounts?: CodexAccount[];
   /** Account ids administratively excluded from future pool selection until resumed. */
   pausedCodexAccountIds?: string[];
+  /**
+   * Selection order per account id, higher used earlier; absent = 0. Keyed by id
+   * rather than stored on `codexAccounts` rows so the Desktop login (`__main__`),
+   * which has no row, can be ordered too. Range -100..100.
+   */
+  codexAccountPriorities?: Record<string, number>;
+  /**
+   * Account id the operator last selected by hand. Suppresses upward priority
+   * preemption until that account crosses the auto-switch threshold. Stores the
+   * id (not a flag) so a stale pin cannot outlive the selection it described.
+   */
+  activeCodexAccountPinned?: string;
   /**
    * Public model-selector namespaces bound to one Codex account. Values are stored account ids;
    * `"@main"` selects the Codex Desktop/main auth.json account. Account display aliases
    * are intentionally separate from these selectors.
    */
   codexAccountNamespaces?: Record<string, string>;
+  /**
+   * Picker visibility override for account-qualified native models. When omitted, a non-empty
+   * selector map remains visible for compatibility with hand-written configurations.
+   */
+  codexAccountPickerEnabled?: boolean;
   /** Active pool account id for next session. undefined = main (passthrough as-is). */
   activeCodexAccountId?: string;
   /** Auto-switch threshold (0-100). Default 80. 0 = disabled. */
@@ -778,6 +839,11 @@ export interface OcxConfig {
   accountPoolStickyLimit?: number;
   /** Consecutive non-2xx upstream responses before switching future new threads. Default 3. 0 = disabled. */
   upstreamFailoverThreshold?: number;
+  /**
+   * Opt-in provider-origin circuit threshold for proven pre-connection reachability failures.
+   * Default 0 (disabled); range 0..20. The circuit never counts timeouts or HTTP responses.
+   */
+  upstreamHostCircuitThreshold?: number;
   /**
    * Opt-in Anthropic OAuth account pool (#294). Default OFF.
    * Failover on 429 + sticky affinity; new sessions may pick lowest known 5h usage.
@@ -1139,9 +1205,9 @@ export interface OcxProviderConfig {
    * full set so the user can pick). See devlog issue_052_provider-model-allowlist.
    */
   selectedModels?: string[];
-  /** Provider-wide Codex-visible context-window cap for routed catalog entries. */
+  /** Provider-wide fallback when context metadata is absent; otherwise caps the reported window. */
   contextWindow?: number;
-  /** Model-specific Codex-visible context-window caps. Values cap live metadata, never raise it. */
+  /** Per-model fallback when context metadata is absent; otherwise caps the reported window. */
   modelContextWindows?: Record<string, number>;
   /** Model-specific Codex catalog input modalities, e.g. ["text"] or ["text", "image"]. */
   modelInputModalities?: Record<string, string[]>;

package/src/update/index.ts

@@ -4,6 +4,10 @@ import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
 import { getConfigDir, loadConfig, readPid, readRuntimePort } from "../config";
 import { npmInvocation } from "./npm-invocation.mjs";
+import {
+  npmCachePreflightFailureMessage,
+  runNpmCachePreflight,
+} from "./npm-cache-preflight.mjs";
 import { handoffWindowsTrayForUpdate, planWindowsTrayUpdate } from "./tray-update-plan.mjs";
 import { withProcessRuntimeProvenance } from "../lib/bun-runtime";
 
@@ -178,6 +182,14 @@ export async function runUpdate(): Promise<void> {
     console.log(`Verified ${PKG}@${latest} integrity metadata ${integrity.integrity.slice(0, 24)}…`);
   }
 
+  if (installer === "npm") {
+    const cachePreflight = runNpmCachePreflight();
+    if (!cachePreflight.ok) {
+      console.error(`⚠️  ${npmCachePreflightFailureMessage(cachePreflight.reason)}. Aborting before stopping the proxy.`);
+      process.exit(1);
+    }
+  }
+
   const { bin, args: cmdArgs } = updateCommand(installer, tag, latest);
   const target = updateSpawnTarget(bin, cmdArgs);
   if (!target) {