@bitkyc08/opencodex 2.75.0 → 2.76.0

package/src/service-manager-probe.ts

@@ -32,6 +32,7 @@ import { BUN_RUNTIME_PATH_ENV, BUN_RUNTIME_SOURCE_ENV } from "./lib/bun-runtime"
 import { WINDOWS_WRAPPER_PROTOCOL_ENV, WINDOWS_WRAPPER_STAY_OUT_EXIT_CODE } from "./service/windows-wrapper-exit";
 import { buildWindowsServiceScript, windowsTaskActionMatches } from "./service/windows-taskxml";
 import { inspectServiceStateEvidence, serviceStatePathsForOpenCodexHome } from "./service/state";
+import { parseSystemdUnitHomes } from "./service/systemd-env";
 
 /** Short: this runs inside admission, and a slow answer is the same as none. */
 export const SERVICE_PROBE_TIMEOUT_MS = 2_000;
@@ -238,21 +239,23 @@ function unknown(reason: string): ServiceManagerInstallation {
   return { kind: "unknown", reason };
 }
 
+/** Decode the entities buildPlist's plistString applies. `&` goes last so a
+ *  literal `<` written by a double-escaped value stays `<`. */
+function plistStringValue(raw: string): string {
+  return raw
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, "\"")
+    .replace(/&apos;/g, "'")
+    .replace(/&amp;/g, "&");
+}
+
 /** Pull `<key>NAME</key><string>VALUE</string>` out of a plist body. */
 function plistEnvValue(body: string, key: string): string | null {
   const match = body.match(
     new RegExp(`<key>\\s*${key}\\s*</key>\\s*<string>([^<]*)</string>`),
   );
-  return match ? match[1] : null;
-}
-
-/** Pull `Environment="NAME=VALUE"` (quoted or bare) out of a systemd unit. */
-function unitEnvValue(body: string, key: string): string | null {
-  for (const line of body.split("\n")) {
-    const match = line.match(new RegExp(`^\\s*Environment=\\s*"?${key}=([^"\\n]*)"?\\s*$`));
-    if (match) return match[1];
-  }
-  return null;
+  return match ? plistStringValue(match[1]) : null;
 }
 
 /**
@@ -321,15 +324,14 @@ function inspectSystemdOffline(home: string): ServiceManagerInstallation {
   } catch (error) {
     return unknown(`the session bus is unreachable and the systemd unit could not be read: ${String(error)}`);
   }
+  const parsed = parseSystemdUnitHomes(body);
+  if (parsed.kind === "invalid") return unknown("the systemd unit has unsupported or ambiguous environment assignments");
   return {
     kind: "present",
     claims: [{
       backend: "systemd",
       definitionPath,
-      homes: {
-        codexHome: unitEnvValue(body, "CODEX_HOME"),
-        opencodexHome: unitEnvValue(body, "OPENCODEX_HOME"),
-      },
+      homes: parsed.homes,
       registration: "absent",
     }],
   };
@@ -463,16 +465,14 @@ function inspectSystemd(deps: Required<Pick<ProbeDeps, "run" | "home">>): Servic
   } catch (error) {
     return unknown(`the systemd unit exists but could not be read: ${String(error)}`);
   }
-
+  const parsed = parseSystemdUnitHomes(body);
+  if (parsed.kind === "invalid") return unknown("the systemd unit has unsupported or ambiguous environment assignments");
   return {
     kind: "present",
     claims: [{
       backend: "systemd",
       definitionPath,
-      homes: {
-        codexHome: unitEnvValue(body, "CODEX_HOME"),
-        opencodexHome: unitEnvValue(body, "OPENCODEX_HOME"),
-      },
+      homes: parsed.homes,
       registration,
     }],
   };
@@ -801,6 +801,59 @@ function probeWinswRegistration(
   return /\b1060\b/.test(text) ? "absent" : "unknown";
 }
 
+/**
+ * The `BINARY_PATH_NAME` value from `sc.exe qc` output, or null when the line is missing.
+ * `sc qc` field names are not localized; the value may be quoted and carry arguments.
+ */
+export function parseScQcBinaryPathName(output: string): string | null {
+  const match = /^[ \t]*BINARY_PATH_NAME[ \t]*:[ \t]*([^\r\n]*)$/m.exec(output);
+  const value = match?.[1]?.trim();
+  return value ? value : null;
+}
+
+function normalizeWindowsExecutablePath(path: string): string {
+  const stripped = path.startsWith("\\\\?\\") ? path.slice(4) : path;
+  return win32Path.normalize(stripped).toLowerCase();
+}
+
+/**
+ * Whether an SCM `BINARY_PATH_NAME` launches exactly `exePath`. A quoted value names the
+ * text between its quotes; an unquoted value names the text through the first `.exe`
+ * followed by whitespace or the end. Comparison is Windows path-normalized and case-insensitive.
+ */
+export function scBinaryPathNamesExecutable(binaryPathName: string, exePath: string): boolean {
+  const value = binaryPathName.trim();
+  let executable: string | null;
+  if (value.startsWith("\"")) {
+    const end = value.indexOf("\"", 1);
+    executable = end > 1 ? value.slice(1, end) : null;
+  } else {
+    executable = /^(.*?\.exe)(?=\s|$)/i.exec(value)?.[1] ?? null;
+  }
+  if (!executable || !exePath.trim()) return false;
+  return normalizeWindowsExecutablePath(executable) === normalizeWindowsExecutablePath(exePath.trim());
+}
+
+/**
+ * The registered WinSW service's `BINARY_PATH_NAME` through trusted System32 `sc.exe qc`,
+ * bounded like every other probe query. Null on any failure; the WinSW executable is never run.
+ */
+export function queryWinswBinaryPathName(
+  deps: Pick<ProbeDeps, "runRaw" | "windowsLocale"> = {},
+): string | null {
+  let sc: string;
+  try {
+    sc = join(resolveTrustedWindowsSystemDirectory(), "sc.exe");
+    if (artifactPresence(sc) !== "present") return null;
+  } catch {
+    return null;
+  }
+  const runRaw = deps.runRaw ?? defaultRawProbeRunner;
+  const queried = runRaw(sc, ["qc", WINSW_SERVICE_ID]);
+  if (queried.spawnFailed || queried.timedOut || queried.status !== 0) return null;
+  return parseScQcBinaryPathName(decodeWindowsTextBytes(queried.stdout, { locale: deps.windowsLocale }));
+}
+
 function inspectWindows(
   deps: Required<Pick<ProbeDeps, "runRaw" | "home">>
     & Pick<ProbeDeps, "configDir" | "winswStatus" | "windowsLocale" | "windowsTaskListingCache" | "statePaths">,

package/src/types/config.ts

@@ -495,6 +495,8 @@ export interface OcxClientConnectionConfig {
 }
 
 export interface OcxConfig {
+  /** Experimental macOS app-server stdout shim; absent or false disables it. */
+  chatgptDesktop?: { appServerShim?: boolean };
   port: number;
   /** Runtime topology role. Absence preserves the historical standalone behavior. */
   runtimeRole?: OcxRuntimeRole;
@@ -576,13 +578,15 @@ export interface OcxConfig {
    */
   ultraFastTier?: boolean;
   /**
-   * Stop new identity-matched main-account requests at observed 98% usage (#5694).
+   * Stop new identity-matched main-account requests at configured window usage (#5694).
    *
    * On by default: an absent key and `true` both enable it, and only an explicit `false`
    * opts out. While it blocks, the main account's Luna Reserve cannot activate, so an operator
    * who wants Reserve has to turn the setting off rather than delete the key.
    */
   codexMainAccountHardLock?: boolean;
+  /** Per-window percentages: short defaults to 90, long to 98; integers 80..100, short <= long. */
+  codexMainAccountHardLockThresholds?: { short?: number; long?: number };
   /** Explicit top-level deletion intent used by stale whole-config rebases. */
   configRebaseProvenance?: OcxConfigRebaseProvenance | Record<string, unknown>;
   /** OpenAI provider-contract migration marker (v2 = single `openai` provider with account mode). */
@@ -651,6 +655,11 @@ export interface OcxConfig {
    * reject the whole role file as an unknown field (#1190).
    */
   subagentModelFallbackByModel?: Record<string, string[]>;
+  /**
+   * Capability tier of named models for Codex role auto-assign, overriding its price-rank
+   * classification. Models no list names and no price covers are never proposed.
+   */
+  codexRoleTiers?: { fast?: string[]; standard?: string[]; frontier?: string[] };
   /**
    * TTL (ms) for cached sub-agent model availability probes. Default 60_000.
    */
@@ -1015,6 +1024,12 @@ export interface OcxConfig {
   codexAccounts?: CodexAccount[];
   /** Account ids administratively excluded from future pool selection until resumed. */
   pausedCodexAccountIds?: string[];
+  /**
+   * Account ids, `__main__` included, allowed to keep serving from ChatGPT credits once one of
+   * their usage windows is full. Every other account is skipped by selection at 100% until its
+   * window resets, so spending credits is opt-in.
+   */
+  creditCodexAccountIds?: string[];
   /**
    * Codex pool selection policy. Absent means no policy, so an existing install rotates exactly
    * as before.
@@ -1342,6 +1357,21 @@ export interface OcxComboConfig {
   nativeAlias?: boolean;
   /** Display-only label for the public catalog row. Required for native aliases. */
   displayName?: string;
+  /**
+   * `strategy: "jev"` only: provider id of the decision service. Omitted or `"jev"` uses the
+   * canonical TypeSafe endpoint; any other id must name a configured `adapter: "jev-decision"`
+   * row, such as a self-hosted Ollama `tev1` endpoint. That row's baseUrl is the full decision
+   * endpoint and only its own apiKey is sent there.
+   */
+  decisionProvider?: string | null;
+  /** JEV only: an ordinary model route for decisions; null explicitly clears management input. */
+  decisionModel?: string | null;
+  /**
+   * `strategy: "jev"` only: decision deadline in milliseconds before failing open to the first
+   * eligible target. Default 4000; range 1000..120000. Raise it for a self-hosted decision model
+   * whose first call may include a cold model load.
+   */
+  decisionTimeoutMs?: number;
 }
 
 export type OcxRoutingUnknownEvidenceMode = "allow" | "penalize" | "exclude";

package/src/types/provider.ts

@@ -274,6 +274,8 @@ export interface ModelCapabilities {
 }
 
 export interface OcxProviderConfig {
+  /** Optional browser-compatible outbound TLS profile; disabled by default. */
+  tlsProfile?: "antigravity-browser";
   /** Optional short provider namespace used only at request/catalog presentation time. */
   alias?: string;
   /** Native model id -> short, slash-free request alias. */

package/src/types/request.ts

@@ -116,6 +116,8 @@ export interface OcxParsedRequest {
   _cursorIsolateConversation?: boolean;
   /** Account-scoped, non-secret Kiro request metadata selected with the OAuth access token. */
   _kiroAuthContext?: Pick<KiroOAuthMetadata, "profileArn" | "apiRegion" | "ssoRegion" | "authType">;
+  /** Account-scoped Zed user identity paired with the long-lived access token. */
+  _zedAuthContext?: { userId: string };
   /** Provider-private continuation metadata resolved from the Responses previous_response_id chain. */
   _providerContinuation?: OcxProviderContinuationState;
   /** Persisted continuation considered only after the final physical route is known. */

package/src/update/index.ts

@@ -570,12 +570,23 @@ export async function runUpdate(): Promise<void> {
   };
   const recoverStoppedRuntime = async (reason: string): Promise<void> => {
     try {
-      const current = await resolvedRuntimeOwnership();
-      const recovery = planStoppedRuntimeRecovery({
-        stopAttempted, ...current, sameOwner: sameOwner(current),
-        liveness: currentPackageRuntimeLiveness(), serviceInstalled: serviceWasInstalled,
-        launcherUsable: postUpdateLauncherUsable && existsSync(postUpdateLauncher), hadRuntimeState,
-      });
+      const planRecovery = async () => {
+        const current = await resolvedRuntimeOwnership();
+        return planStoppedRuntimeRecovery({
+          stopAttempted, ...current, sameOwner: sameOwner(current),
+          liveness: currentPackageRuntimeLiveness(), serviceInstalled: serviceWasInstalled,
+          launcherUsable: postUpdateLauncherUsable && existsSync(postUpdateLauncher), hadRuntimeState,
+        });
+      };
+      let recovery = await planRecovery();
+      if (recovery.action === "service") {
+        // The service manager starts the proxy outside this process tree, so it
+        // cannot join this lease, and holding it through the repair's health wait
+        // keeps that proxy from starting (#5760). Release it, then decide again —
+        // a claim could have landed while the repair ran unleased.
+        mutation.release();
+        recovery = await planRecovery();
+      }
       if (recovery.action === "manual") {
         console.warn(`⚠️  ${reason}; runtime recovery requires manual review (${recovery.reason}).`);
       } else if (recovery.action === "service") {
@@ -585,6 +596,9 @@ export async function runUpdate(): Promise<void> {
           env: mutation.controlEnvironment({ ...process.env, OCX_BAKE_PORT: String(capturedListen.port) }),
         });
         if (service.status !== 0 || !isServiceViable()) {
+          // The refresh ran unleased; a claim could have landed meanwhile, so take
+          // the lease back before re-reading ownership and authorizing a direct start.
+          mutation.reacquire();
           const nowOwned = await resolvedRuntimeOwnership();
           const fallback = planStoppedRuntimeRecovery({
             stopAttempted, ...nowOwned, sameOwner: sameOwner(nowOwned),
@@ -595,6 +609,8 @@ export async function runUpdate(): Promise<void> {
           else console.warn("⚠️  Service recovery was not confirmed; no second proxy was started.");
         }
       } else if (recovery.action === "direct") {
+        // No-op while the lease is held; re-locks if the service branch released it.
+        mutation.reacquire();
         await startProxyDirectly();
       }
     } catch {
@@ -815,6 +831,11 @@ export async function runUpdate(): Promise<void> {
       if (!freed) {
         console.warn(`⚠️  Port ${capturedListen.port} still busy after 30s; repairing service with pinned --port ${capturedListen.port} anyway (refusing to hop).`);
       }
+      // `service repair` re-activates a manager whose `ocx start` child is not a
+      // process descendant and cannot join this lease; held through its serving
+      // wait, the lease makes that child die at the acquire deadline (#5760).
+      // The kill-authorizing reclaim above already ran under the lease.
+      mutation.release();
       const prevBake = process.env.OCX_BAKE_PORT;
       process.env.OCX_BAKE_PORT = String(capturedListen.port);
       try {
@@ -855,6 +876,18 @@ export async function runUpdate(): Promise<void> {
             // Re-read rather than reuse the plan from before the package install: the app can
             // claim the runtime during an update that takes minutes, and the refusal the
             // repair above just returned is indistinguishable from any other failure here.
+            // The refresh above ran outside the lease — take it back so this re-read and
+            // the direct start stay serialized with a claim that landed in that window.
+            // A claim that outlasts the wait is reported here: the package is already
+            // swapped, so the unexpected-failure recovery below would run a second,
+            // unleased repair and surface the raw lock error instead.
+            try {
+              mutation.reacquire();
+            } catch {
+              console.warn("⚠️  Updated, but another process kept the runtime ownership lease claimed, so no proxy was started.");
+              console.warn(`   Run 'ocx service repair', then 'ocx start --port ${capturedListen.port}'.`);
+              return 1;
+            }
             const nowOwned = planUpdateRuntimeHandling({
               ...(await resolvedRuntimeOwnership()),
               serviceInstalled: true,

package/src/update/job.ts

@@ -238,9 +238,8 @@ async function waitForGhostListenClear(
 }
 
 function packageLauncherPath(): string {
-  // This module lives at src/update/job.ts — the launcher is <pkg-root>/bin/ocx.mjs.
-  // After `npm install -g`, import.meta.url can still point at npm's renamed temp
-  // tree (`@bitkyc08/.opencodex-*`). Prefer the live package path when that happens.
+  // The launcher is <pkg-root>/bin/ocx.mjs. After `npm install -g`, import.meta.url
+  // can still point at npm's renamed temp tree — prefer the live package path then.
   const fromMeta = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "bin", "ocx.mjs");
   if (!/[\\/]\.opencodex-/i.test(fromMeta) && existsSync(fromMeta)) return fromMeta;
   const live = fromMeta.replace(/[\\/]@bitkyc08[\\/]\.opencodex-[^\\/]+/i, `${sep}@bitkyc08${sep}opencodex`);
@@ -470,17 +469,16 @@ export function restartCommand(
   const startArgs = pinPort
     ? [launcher, "start", "--port", String(Math.trunc(port))]
     : [launcher, "start"];
-  // Default to the in-place refresh: `install` always registers, while repair reuses a healthy
-  // Windows scheduler definition and re-registers only when the live definition is stale.
+  // Default to repair, which reuses a healthy registration and re-registers only a stale one.
   const svcArgs = serviceInstalled ? [launcher, ...(serviceArgs ?? ["service", "repair"])] : startArgs;
   if (usesNodeLauncher(installer)) {
     const bin = nodeBin();
     const args = svcArgs;
     return { mode, bin, args, display: formatCommand(bin, args) };
   }
-  // bun/source installs: restart via the current runtime executable + package launcher (both real
-  // .exe files), NOT the `ocx.cmd` shim. Spawning a `.cmd` shell-less throws EINVAL on Windows
-  // Node/Bun ≥18.20/20.12 (CVE-2024-27980 hardening) — the same class the npm path (nodeBin) avoids.
+  // bun/source installs restart via the runtime executable + package launcher (real
+  // .exe files), not `ocx.cmd` — shell-less `.cmd` spawn throws EINVAL on Windows
+  // (CVE-2024-27980 hardening), the same class the npm path avoids.
   const bin = process.execPath;
   const args = svcArgs;
   return { mode, bin, args, display: formatCommand(bin, args) };
@@ -873,9 +871,8 @@ export function summarizeCommandOutput(
   const parts: string[] = [];
   parts.push(signal ? `terminated by ${signal}` : `exit ${status ?? "null"}`);
 
-  // Read npm's own named fields rather than reproducing its text. This is what makes a failed
-  // update diagnosable again: `code: E404 · 404: 404 Not Found - GET https://registry...` tells
-  // a user exactly what happened, and none of it can be a local path.
+  // Read npm's own named fields rather than reproducing its text — `code: E404 ·
+  // 404: ...` tells a user exactly what happened and none of it can be a local path.
   const fields = npmDiagnosticFields(`${stderr}\n${stdout}`);
   if (fields.length > 0) parts.push(...fields);
 
@@ -1001,6 +998,13 @@ export interface RestartIo {
    * to a direct proxy start so dashboard updates never leave /healthz dead.
    */
   serviceViableFn?: () => boolean;
+  /**
+   * Free the ownership-mutation lease before a service-manager-mediated start that
+   * cannot join it (#5760); wired by runUpdateRestartWithOwnershipLease.
+   */
+  releaseForServiceManagerFn?: () => void;
+  /** Re-acquire the lease for the direct-start fallthrough, then re-run the veto; a notice stops the restart. */
+  reacquireForDirectStartFn?: () => { readonly notice: string; readonly failed: boolean } | null;
   probeProxy?: (port: number, hostname?: string) => Promise<boolean>;
   /** Richer /healthz read for update-correlated restart evidence (pid + version). */
   probeProxyIdentity?: (port: number, hostname?: string) => Promise<RestartProxyIdentity | null>;
@@ -1031,7 +1035,7 @@ export interface RestartIo {
     job: UpdateJobState,
     captured?: { port: number; hostname: string; oldPid?: number },
     io?: RestartIo,
-  ) => Promise<void>;
+  ) => Promise<false | void>;
   /**
    * PIDs currently LISTENing on the captured port. Used to widen the post-update
    * kill allowlist beyond the pre-update PID (Windows often leaves a respawned
@@ -1055,9 +1059,8 @@ export interface RestartIo {
  * window: being wrong here costs one extra start attempt; being wrong the other way
  * leaves the user with no proxy at all.
  *
- * It runs AFTER the child's own 20s install probe (SERVICE_INSTALL_HEALTH_MS on
- * macOS/Linux), so a reinstall that exits 0 but never serves spends up to 45s before
- * the fallback — inside RESTART_TIMEOUT_MS of 60s. That is why this is 25s, not more.
+ * It runs AFTER the child's own 20s install probe, so a reinstall that exits 0 but
+ * never serves spends up to 45s before the fallback — inside the 60s restart budget.
  */
 export const SERVICE_RECOVERY_HEALTH_MS = 25_000;
 
@@ -1095,12 +1098,11 @@ async function restartAfterUpdate(
   job: UpdateJobState,
   captured?: { port: number; hostname: string; oldPid?: number },
   io: RestartIo = {},
-): Promise<void> {
+): Promise<false | void> {
   const serviceInstalled = (io.serviceInstalledFn ?? isServiceInstalled)();
   const config = loadConfig();
-  // The stop-first update flow has already cleared pid/runtime state by the time we run,
-  // so the pre-update capture (taken before the update command) is the authoritative
-  // port to wait on; config is only the cold-start fallback.
+  // Stop-first update already cleared pid/runtime state, so the pre-update capture is
+  // the authoritative port to wait on; config is only the cold-start fallback.
   const port = captured?.port ?? config.port ?? 10100;
   const hostname = captured?.hostname ?? config.hostname ?? "127.0.0.1";
   const oldPid = typeof captured?.oldPid === "number" && captured.oldPid > 0
@@ -1119,10 +1121,9 @@ async function restartAfterUpdate(
   const listPids = io.listListenPidsFn ?? listListenPids;
   const verifyOcx = io.verifyOcxFn ?? verifyPidIdentity;
   const aliveFn = io.isAliveFn ?? isProcessAlive;
-  // Pre-update PID plus any ocx still LISTENing on the captured port. After a
-  // stop-first package-manager self-update Windows often leaves a respawned bun/node child
-  // that is not the captured PID; treating it as protected blocks reclaim and
-  // the direct-start fallback never binds.
+  // Pre-update PID plus any ocx still LISTENing on the captured port: a self-update
+  // often leaves a respawned bun/node child that is not the captured PID, and
+  // treating it as protected blocks reclaim so the direct start never binds.
   const reclaimKillAllowlist = (): number[] => {
     const allow = new Set<number>();
     if (oldPid != null) allow.add(oldPid);
@@ -1137,30 +1138,24 @@ async function restartAfterUpdate(
     intervalMs: 100,
     scanIntervalMs: 500,
     killOcxHolders: true,
-    // Windows scheduler wrappers can mint a *new* bun PID during the wait; keep
-    // killing every ocx listener on this port, not only the pre-wait snapshot.
-    // npm rename trees under `@bitkyc08/.opencodex-*` are classified as ocx by
-    // isOcxStartCommandLine — never kill unknown foreign claimants on this port.
+    // Scheduler wrappers mint new ocx PIDs during the wait — kill every ocx
+    // listener, not only the pre-wait snapshot; foreign claimants stay protected.
     killAllOcxOnPort: true,
     onlyKillPids,
   });
 
   if (serviceInstalled) {
     // schtasks /end often leaves the hidden cmd/wscript wrapper alive; its :loop
-    // respawns `ocx start` a few seconds later and races port reclaim. End the
-    // task again and best-effort kill those wrappers before we touch the socket.
+    // respawns `ocx start` a few seconds later and races port reclaim, so end the
+    // task again and kill those wrappers before touching the socket, then reclaim it
+    // for wrappers that bake `--port`.
     stopWindowsServiceWrappersBestEffort();
-    // Stop-first update already unloaded the service; reclaim the socket, then
-    // reinstall wrappers that bake `--port`.
     const preServiceAllow = reclaimKillAllowlist();
     const freed = await waitFn(port, hostname, reclaimOptsFor(preServiceAllow));
     let skipServiceInstall = false;
-    // This skip existed because refresh ran `ocx service install`, whose Windows path always
-    // registers. `service repair` normally reuses the live task and can refresh a stale
-    // definition through its guarded create/elevation path, so the install-only skip no longer
-    // applies and would leave the common dashboard update with stale service assets.
-    //
-    // Only a caller that still passes install argv keeps the old behavior.
+    // `service repair` reuses the live task and refreshes a stale definition through
+    // its guarded create/elevation path, so the old install-only skip no longer
+    // applies; only a caller that still passes install argv keeps that behavior.
     const refreshRegisters = (svcArgs ?? []).includes("install");
     if ((io.platform ?? process.platform) === "win32" && process.env.OCX_SERVICE === "1" && refreshRegisters) {
       updateJob(job, {}, "Skipping service re-registration from the non-elevated update worker; falling back to a direct proxy start.");
@@ -1183,13 +1178,17 @@ async function restartAfterUpdate(
         ? liveScan.pids.filter(pid => pid !== process.pid && aliveFn(pid))
         : null;
       if (liveAfter !== null && liveAfter.length === 0) {
-        // Non-elevated `service install` will UAC-fail anyway; skip straight to
-        // the direct-start fallthrough instead of burning another minute on it.
+        // Non-elevated `service install` will UAC-fail anyway; go straight to the
+        // direct-start fallthrough instead of burning another minute on it.
         updateJob(job, {}, "Skipping service reinstall after reclaim timeout with no live holders; falling back to a direct proxy start.");
         skipServiceInstall = true;
       }
     }
     if (!skipServiceInstall) {
+      // `service repair` re-activates a manager whose `ocx start` child is not a
+      // process descendant and cannot join this lease; held through its serving
+      // wait, the lease makes that child die at the acquire deadline (#5760).
+      io.releaseForServiceManagerFn?.();
       const prevBake = process.env.OCX_BAKE_PORT;
       process.env.OCX_BAKE_PORT = String(Math.trunc(port));
       let serviceOk = false;
@@ -1211,13 +1210,9 @@ async function restartAfterUpdate(
               + "Run 'ocx service status', then 'ocx service repair' by hand.",
             );
           }
-          // The refresh that just failed was `ocx service repair` (serviceReinstallArgs).
-          // It normally reuses a healthy registration, but a stale definition may have tried
-          // guarded re-registration/elevation. Advising `install` here would unconditionally
-          // send the user to re-registration — a UAC prompt on
-          // Windows and a possible WinSW-to-scheduler backend switch — to fix a service
-          // that is already registered. Point at the same command that failed so its
-          // output explains why, on every platform.
+          // The refresh that just failed was `ocx service repair`. Advising `install`
+          // here would send the user to re-registration (UAC, possible WinSW backend
+          // switch) for a service that is already registered; name the failed command.
           updateJob(
             job,
             {},
@@ -1230,13 +1225,10 @@ async function restartAfterUpdate(
         else process.env.OCX_BAKE_PORT = prevBake;
       }
       if (serviceOk) {
-        // Exit 0 is not enough, and neither is `viable`. Registration state cannot
-        // distinguish a serving supervisor from one that registered and bound nothing:
-        // `launchctl list` reports both, and `schtasks` reports a task whose child
-        // exited immediately. Since WP2 the child asserts the port itself on
-        // macOS/Linux, but Windows still reports success from registration alone, a
-        // flapping supervisor can satisfy one probe, and the child may be an older CLI.
-        // Ask the port before skipping the fallback this branch exists to protect.
+        // Registration state cannot distinguish a serving supervisor from one that
+        // registered and bound nothing — `launchctl list` reports both, `schtasks`
+        // reports a task whose child exited immediately, a flapping supervisor can
+        // satisfy one probe — so ask the port before skipping the fallback.
         const viable = (io.serviceViableFn ?? isServiceViable)();
         if (viable) {
           if (await serviceRestartServed(job, port, hostname, io)) return;
@@ -1256,9 +1248,13 @@ async function restartAfterUpdate(
         }
       }
     }
-    // Fall through to the direct proxy start below so the update never leaves the
-    // proxy stopped when the service reinstall could not run or did not leave a
-    // viable supervisor.
+  }
+
+  // The service refresh ran outside the lease; take it back so the veto and the kills/start below stay serialized.
+  const restartVeto = io.reacquireForDirectStartFn?.();
+  if (restartVeto) {
+    updateJob(job, restartVeto.failed ? { status: "failed", restarted: false, error: restartVeto.notice } : { status: "succeeded", restarted: false }, restartVeto.notice);
+    return false;
   }
 
   const pid = readPid();
@@ -1272,9 +1268,8 @@ async function restartAfterUpdate(
     }
   }
   if (serviceInstalled) stopWindowsServiceWrappersBestEffort();
-  // Reclaim the captured port before the pinned start. Spawning `--port` while the old
-  // socket is still busy is how Windows updates used to fail health checks (or hop).
-  // killAllOcxOnPort covers wrapper-respawned bun PIDs minted during the wait.
+  // Reclaim before the pinned start: spawning `--port` while the old socket is busy
+  // is how updates used to fail health checks or hop ports.
   const directAllow = reclaimKillAllowlist();
   const freed = await waitFn(port, hostname, reclaimOptsFor(directAllow));
   if (!freed) {
@@ -1459,7 +1454,7 @@ export function restartAfterUpdateForTests(
   job: UpdateJobState,
   captured: { port: number; hostname: string; oldPid?: number },
   io: RestartIo,
-): Promise<void> {
+): Promise<false | void> {
   return restartAfterUpdate(job, captured, io);
 }
 
@@ -1734,7 +1729,7 @@ export async function finishGuiUpdateRestart(
     }
   }
   const restartFn = io.restartAfterUpdateFn ?? restartAfterUpdate;
-  await restartFn(job, captured, io);
+  if ((await restartFn(job, captured, io)) === false) return false;
   if (!usesNodeLauncher(installer)) {
     // Bun/source: health alone remains enough unless a richer identity probe is supplied.
     if (!io.probeProxyIdentity) return confirmRestartedProxy(job, captured, io);
@@ -1975,9 +1970,14 @@ export async function runGuiUpdateWorker(
     }
 
     if (restart) {
-      const outcome = await runUpdateRestartWithOwnershipLease(io.resolveOwnershipFn, async () => {
+      const outcome = await runUpdateRestartWithOwnershipLease(io.resolveOwnershipFn, async lease => {
         job = updateJob(job!, { status: "restarting" }, "Update installed. Restarting proxy...");
-        return finishGuiUpdateRestart(job!, captured, check.installer, { ...io.restartIo, packageLauncherPathFn: () => activeLauncher });
+        return finishGuiUpdateRestart(job!, captured, check.installer, {
+          ...io.restartIo,
+          releaseForServiceManagerFn: lease.releaseForServiceManager,
+          reacquireForDirectStartFn: lease.reacquireForDirectStart,
+          packageLauncherPathFn: () => activeLauncher,
+        });
       });
       if (outcome.kind === "veto") { updateJob(job, { status: "succeeded", restarted: false }, outcome.notice); return; }
       if (!outcome.value) return;

package/src/update/npm-cache-preflight.d.mts

@@ -5,10 +5,11 @@ export type NpmCachePreflightReason =
   | "cache_entry_foreign_owner"
   | "cache_entry_inaccessible"
   | "cache_path_malformed"
+  | "cache_root_dangling_link"
+  | "cache_root_not_directory"
   | "inspection_incomplete"
   | "npm_config_failed"
   | "npm_unavailable"
-  | "windows_skip"
   | "worker_failed"
   | "worker_output_malformed"
   | "worker_timeout";
@@ -20,17 +21,23 @@ export interface NpmCachePreflightResult {
 
 export interface NpmCacheInspectionOptions {
   expectedUid?: number;
+  /** Test seam: lstat used by the cache-root check. Defaults to lstatSync. */
+  lstatFn?: (path: string) => { isSymbolicLink(): boolean; isDirectory(): boolean };
   maxDepth?: number;
   maxEntries?: number;
   nowMs?: () => number;
   /** Test seam: resolve a symlinked cache root. Defaults to realpathSync. */
   realpathFn?: (path: string) => string;
+  /** Test seam: stat (following links) used by the cache-root check. Defaults to statSync. */
+  statFn?: (path: string) => { isDirectory(): boolean };
   /** Test seam: resolve an entry's owner uid. Defaults to the lstat result. */
   uidOf?: (path: string, stat: { uid: number }) => number;
   timeoutMs?: number;
 }
 
 export interface NpmCachePreflightOptions {
+  /** Inspect this resolved cache root instead of letting the worker resolve npm's cache. */
+  cachePath?: string;
   env?: NodeJS.ProcessEnv;
   execPath?: string;
   platform?: NodeJS.Platform;
@@ -38,6 +45,31 @@ export interface NpmCachePreflightOptions {
   timeoutMs?: number;
 }
 
+export type NpmCachePathResolution =
+  | { ok: true; path: string }
+  | { ok: false; reason: "npm_unavailable" | "npm_config_failed" | "cache_path_malformed" };
+
+export interface NpmCachePathOptions {
+  /** Working directory for `npm config get`; defaults to the home directory. */
+  cwd?: string;
+  env?: NodeJS.ProcessEnv;
+  invocationFn?: (
+    args: string[],
+    platform: NodeJS.Platform,
+    env: NodeJS.ProcessEnv,
+  ) => { file: string; args: string[]; options?: Record<string, unknown> } | null;
+  platform?: NodeJS.Platform;
+  spawnSyncFn?: typeof spawnSync;
+  timeoutMs?: number;
+}
+
+export function inspectNpmCacheRoot(
+  cachePath: string,
+  options?: Pick<NpmCacheInspectionOptions, "lstatFn" | "statFn">,
+): NpmCachePreflightResult;
+
+export function resolveNpmCachePath(options?: NpmCachePathOptions): NpmCachePathResolution;
+
 export function inspectNpmCacheDirectory(
   cachePath: string,
   options?: NpmCacheInspectionOptions,