@bitkyc08/opencodex 2.63.0-preview.20260923 → 2.64.0-preview.20260923

package/src/types/wire.ts

@@ -70,6 +70,67 @@ export function captureWireAdapterHardPins(providerName: string): Readonly<Recor
   return Object.freeze(Object.fromEntries([...models].map(modelId => [modelId, "anthropic"])));
 }
 
+interface WirePinPrefixRule {
+  /** The registry endpoint the rule describes; another destination under the same name is not covered. */
+  readonly endpoint: string;
+  readonly prefixes: Readonly<Record<string, string>>;
+}
+
+/**
+ * Provider-local model-id prefixes whose upstream accepts only one wire, bound to the endpoint that
+ * behaves that way. Command Code's Provider API serves `claude-*` ids only on `/provider/v1/messages`
+ * (live `supported_endpoints` on 2026-09-23 list `/messages` alone; `/chat/completions` answers 400
+ * "must be called via /provider/v1/messages"). A prefix covers Claude ids Command Code adds later.
+ */
+const WIRE_ADAPTER_PIN_PREFIXES: Readonly<Record<string, WirePinPrefixRule>> = Object.freeze({
+  commandcode: Object.freeze({
+    endpoint: "https://api.commandcode.ai/provider/v1",
+    prefixes: Object.freeze({ "claude-": "anthropic" }),
+  }),
+});
+
+/** Just enough of a provider config to tell whether it still points at the pinned endpoint. */
+export interface WirePinProvider {
+  readonly baseUrl?: unknown;
+}
+
+function normalizedEndpoint(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  try {
+    const url = new URL(value.trim());
+    return `${url.protocol}//${url.host}${url.pathname.replace(/\/+$/, "")}`.toLowerCase();
+  } catch {
+    return undefined;
+  }
+}
+
+function prefixPinsFor(providerName: string, provider: WirePinProvider | undefined): Readonly<Record<string, string>> | undefined {
+  if (!provider || !Object.hasOwn(WIRE_ADAPTER_PIN_PREFIXES, providerName)) return undefined;
+  const rule = WIRE_ADAPTER_PIN_PREFIXES[providerName]!;
+  return normalizedEndpoint(provider.baseUrl) === rule.endpoint ? rule.prefixes : undefined;
+}
+
+/**
+ * Detached provider-local prefix pins for pure wire-policy resolution. Empty unless the provider
+ * still points at the endpoint the rule describes.
+ */
+export function captureWireAdapterHardPinPrefixes(
+  providerName: string,
+  provider: WirePinProvider | undefined,
+): Readonly<Record<string, string>> {
+  return Object.freeze({ ...(prefixPinsFor(providerName, provider) ?? {}) });
+}
+
+function prefixedWireAdapter(providerName: string, modelId: string, provider: WirePinProvider | undefined): string | undefined {
+  const prefixes = prefixPinsFor(providerName, provider);
+  if (!prefixes) return undefined;
+  const folded = modelId.toLowerCase();
+  for (const [prefix, adapter] of Object.entries(prefixes)) {
+    if (folded.startsWith(prefix)) return adapter;
+  }
+  return undefined;
+}
+
 /**
  * True when the upstream speaks exactly one wire for this model, so a configured
  * override must not apply.
@@ -78,11 +139,14 @@ export function captureWireAdapterHardPins(providerName: string): Readonly<Recor
  * more than once per request, and a check phrased as "pin differs from the current
  * adapter" would pass on the first pass and then let the override win on the second.
  */
-export function isWirePinnedModel(providerName: string, modelId: string): boolean {
-  return anthropicWireModelsForProvider(providerName)?.has(modelId) ?? false;
+export function isWirePinnedModel(providerName: string, modelId: string, provider?: WirePinProvider): boolean {
+  return (anthropicWireModelsForProvider(providerName)?.has(modelId) ?? false)
+    || prefixedWireAdapter(providerName, modelId, provider) !== undefined;
 }
 
 /** The wire a pinned model must use, or undefined when the model is not pinned. */
-export function pinnedWireAdapter(providerName: string, modelId: string): string | undefined {
-  return isWirePinnedModel(providerName, modelId) ? "anthropic" : undefined;
+export function pinnedWireAdapter(providerName: string, modelId: string, provider?: WirePinProvider): string | undefined {
+  return anthropicWireModelsForProvider(providerName)?.has(modelId)
+    ? "anthropic"
+    : prefixedWireAdapter(providerName, modelId, provider);
 }

package/src/types.ts

@@ -28,6 +28,7 @@ export {
   OPENAI_PROVIDER_TIER_VERSION,
   MODEL_ADAPTER_OVERRIDE_ALLOWED,
   captureWireAdapterHardPins,
+  captureWireAdapterHardPinPrefixes,
   isWirePinnedModel,
   pinnedWireAdapter,
 } from "./types/wire";

package/src/update/job.ts

@@ -24,7 +24,13 @@ import {
 import { stopWinswService } from "../lib/winsw";
 import { listListenPids, reclaimListenPort, scanListenPids, type ListenPidScan } from "../server/port-reclaim";
 import { dropWindowsTcpRowsForLocalPort } from "../server/windows-tcp-drop";
-import { isOpencodexHealthz, probeHostname, proxyIdentityAt, type HealthzIdentity } from "../server/proxy-liveness";
+import {
+  isHealthzVersion,
+  isOpencodexHealthz,
+  probeHostname,
+  proxyIdentityAt,
+  type HealthzIdentity,
+} from "../server/proxy-liveness";
 import { isServiceInstalled, isServiceViable, readServiceBackend, stopWindows } from "../service";
 import { runUpdateRestartWithOwnershipLease, type ServiceOwnershipResolution } from "./restart-ownership";
 import {
@@ -45,6 +51,7 @@ import type { PnpmGlobalOwner } from "./pnpm-global-install.mjs";
 import { isNewer } from "./notify";
 import { isRealBunBinary } from "../lib/bun-binary-validator.mjs";
 import { handoffWindowsTrayForUpdate, planWindowsTrayUpdate } from "./tray-update-plan.mjs";
+import { GUI_UPDATE_FAILURE_NEXT_STEP } from "./update-failure-guidance.mjs";
 import {
   npmCachePreflightFailureMessage,
   runNpmCachePreflight,
@@ -268,19 +275,6 @@ function ensureJobDir(): void {
  * TYPE and size — enough to tell a reader what class of failure occurred — and never its text,
  * which is where the paths and account names live.
  */
-/**
- * A version string we are willing to repeat in a persisted field.
- *
- * Semver plus an optional prerelease/build tail, capped in length. Anything else is dropped
- * rather than logged: `/healthz` is answered by whatever holds the port, so its `version` is
- * external input on the same footing as an error message.
- */
-function isVersionLike(value: unknown): value is string {
-  return typeof value === "string"
-    && value.length <= 64
-    && /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(value);
-}
-
 function withheldSummary(error: unknown): string {
   // `error.name` is writable, so it is external text like the message. A fixed classification
   // is the only part of an unknown error we can state without repeating something we were
@@ -1589,7 +1583,7 @@ async function defaultProbeProxyIdentity(
       // `/healthz` is answered by whatever is listening on that port, so a hostile or confused
       // responder can return any string here — and the restart-evidence reasons below
       // interpolate it into a persisted field. A version is a version or it is nothing.
-      ...(isVersionLike(body?.version) ? { version: body.version } : {}),
+      ...(isHealthzVersion(body?.version) ? { version: body.version } : {}),
     };
   } catch {
     return null;
@@ -1949,7 +1943,7 @@ export async function runGuiUpdateWorker(
         status: "failed",
         exitCode: result.status,
         signal: result.signal,
-        error: `update command failed (${result.status ?? "?"})`,
+        error: `update command failed (${result.status ?? "?"}). ${GUI_UPDATE_FAILURE_NEXT_STEP}`,
       });
       return;
     }

package/src/update/npm-invocation.mjs

@@ -12,21 +12,17 @@ function escapeCmdCommand(command) {
   return command.replace(CMD_META, "^$1");
 }
 
-/**
- * Whether a PATH entry *is* the current directory. The hijack this guards against is
- * cmd.exe resolving a bare `npm` out of the directory opencodex was launched from, so
- * only that exact directory has to be skipped — every candidate we hand to spawn is an
- * absolute path, which is what actually defeats the implicit cwd-first search.
- *
- * Deliberately not a subtree test: npm's default Windows global prefix is
- * `%AppData%\npm` (`C:\Users\x\AppData\Roaming\npm`), so excluding everything under the
- * cwd would fail closed for anyone whose shell sits in their home directory — a normal
- * setup, not the untrusted-project case this hardening is for.
- */
-function isCurrentDirectory(cwd, entry) {
-  const left = win32.resolve(entry);
-  const right = win32.resolve(cwd);
-  return left.toLowerCase() === right.toLowerCase();
+function isInside(root, candidate) {
+  const relative = win32.relative(win32.resolve(root), win32.resolve(candidate));
+  return relative === "" || (
+    relative !== ".."
+    && !relative.startsWith(`..${win32.sep}`)
+    && !win32.isAbsolute(relative)
+  );
+}
+
+function isSamePath(left, right) {
+  return win32.resolve(left).toLowerCase() === win32.resolve(right).toLowerCase();
 }
 
 function cleanPathEntry(entry) {
@@ -43,6 +39,10 @@ export function resolveNpmCommand(
   if (platform !== "win32") return "npm";
   const exists = deps.exists ?? existsSync;
   const cwd = deps.cwd ?? process.cwd();
+  const trustedRoots = [env.APPDATA, env.LOCALAPPDATA, env.ProgramFiles, env["ProgramFiles(x86)"],
+    env.USERPROFILE && win32.join(env.USERPROFILE, "scoop", "shims")]
+    .filter(root => typeof root === "string" && win32.isAbsolute(root));
+  const trustedEntry = entry => trustedRoots.some(root => isInside(root, entry) && !isInside(root, cwd));
   const extensions = (env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD")
     .split(";")
     .filter(Boolean);
@@ -53,7 +53,8 @@ export function resolveNpmCommand(
 
   for (const entry of pathEntries) {
     if (!win32.isAbsolute(entry)) continue;
-    if (isCurrentDirectory(cwd, entry)) continue;
+    if (isSamePath(entry, cwd)) continue;
+    if (isInside(cwd, entry) && !trustedEntry(entry)) continue;
     for (const extension of extensions) {
       const candidate = win32.join(entry, `npm${extension.toLowerCase()}`);
       if (exists(candidate)) return win32.resolve(candidate);

package/src/update/transactional-install.d.mts

@@ -5,6 +5,27 @@ export function bootRestoreProbe(
   packageDir: string,
   deps?: { rename?: (from: string, to: string) => void },
 ): { action: "none" | "reaped" | "restored" | "failed"; count?: number; from?: string; error?: string };
+export type UpdateFsDeps = {
+  rename?: (from: string, to: string) => void;
+  mkdir?: (path: string) => void;
+  rm?: (path: string, options: { recursive: true; force: true }) => void;
+  now?: () => number;
+};
+export const UPDATE_OWNER_MARKER: string;
+export const STALE_STAGE_MIN_AGE_MS: number;
+export function removeOwnedStage(stageRoot: string, deps?: UpdateFsDeps): { removed: boolean; code?: string };
+export function sweepUpdateLeftovers(args: {
+  packageDir: string;
+  pkgName: string;
+  log?: (line: string) => void;
+  deps?: UpdateFsDeps;
+}): {
+  removed: string[];
+  inUse: Array<{ path: string; code: string }>;
+  recent: string[];
+  notOwned: string[];
+};
+export function launcherUsableAfterNpmUpdate(tx: { ok: boolean; phase: string; rolledBack?: boolean } | null | undefined): boolean;
 export function transactionalNpmUpdate(args: {
   packageDir: string;
   pkgName: string;
@@ -12,7 +33,7 @@ export function transactionalNpmUpdate(args: {
   tag: string;
   runNpm: (args: string[]) => { status: number | null };
   log?: (line: string) => void;
-  deps?: { rename?: (from: string, to: string) => void };
+  deps?: UpdateFsDeps;
 }): {
   ok: boolean;
   phase: "stage" | "verify" | "swap-backup" | "swap-live" | "post-verify" | "double-fault" | "done";

package/src/update/transactional-install.mjs

@@ -15,9 +15,15 @@
  *   <scopeDir>/.ocx-staging-<ts>/             npm --prefix root (contains node_modules/...)
  *   <scopeDir>/.ocx-backup-<ts>/opencodex     previous live tree during/after the swap
  *   <scopeDir>/.ocx-recovery.json             double-fault marker with a one-line restore
+ *
+ * A staging directory is created exclusively and immediately carries an ownership marker
+ * (`.ocx-update-owner.json`). Only a marked staging directory is ever swept by a later
+ * update; anything else next to the package — an unmarked stage from an older updater, npm's
+ * own `.<name>-<random>` rename-aside, a link — is reported and left alone (#5624).
  */
 import { spawnSync } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 
 /**
@@ -160,6 +166,146 @@ function stampedName(prefix) {
   return prefix + "-" + new Date().toISOString().replace(/[:.]/g, "-");
 }
 
+export const UPDATE_OWNER_MARKER = ".ocx-update-owner.json";
+const STAGE_PREFIX = ".ocx-staging-";
+/**
+ * A marked stage younger than this is left alone by the sweep. npm's staging install is bounded
+ * at three minutes by the launcher; the floor is far above it so an update running from another
+ * home against the same global prefix never loses its in-flight stage.
+ */
+export const STALE_STAGE_MIN_AGE_MS = 30 * 60 * 1000;
+const RETRYABLE_REMOVE_CODES = new Set(["EPERM", "EBUSY", "EACCES", "ENOTEMPTY"]);
+
+/** Create a fresh staging directory that did not exist before, and mark it as ours. */
+function createOwnedStage(scopeDir, pkgName, deps = {}) {
+  const mkdir = deps.mkdir ?? mkdirSync;
+  const stageRoot = join(scopeDir, stampedName(".ocx-staging") + "-" + randomBytes(4).toString("hex"));
+  // Not recursive: an existing directory of the same name must fail, never be reused.
+  mkdir(stageRoot);
+  try {
+    writeFileSync(join(stageRoot, UPDATE_OWNER_MARKER), JSON.stringify({
+      schema: 1,
+      kind: "staging",
+      pkgName,
+      pid: process.pid,
+      createdAt: (deps.now ?? Date.now)(),
+    }), { flag: "wx" });
+  } catch (error) {
+    // Still empty and created by this call: remove it rather than leave an unmarked stage.
+    try { rmSync(stageRoot, { recursive: true, force: true }); } catch { /* reported by the caller */ }
+    throw error;
+  }
+  return stageRoot;
+}
+
+/** The marker of a real (non-link) staging directory this updater created, or null. */
+function readOwnedStageMarker(dir, pkgName) {
+  try {
+    const dirStat = lstatSync(dir);
+    // A symlink or junction is never ours to delete: removing through it reaches its target.
+    if (!dirStat.isDirectory() || dirStat.isSymbolicLink()) return null;
+    const markerPath = join(dir, UPDATE_OWNER_MARKER);
+    if (!lstatSync(markerPath).isFile()) return null;
+    const marker = JSON.parse(readFileSync(markerPath, "utf8"));
+    if (marker?.schema !== 1 || marker.kind !== "staging" || marker.pkgName !== pkgName) return null;
+    if (typeof marker.createdAt !== "number" || !Number.isFinite(marker.createdAt)) return null;
+    return marker;
+  } catch {
+    return null;
+  }
+}
+
+function removeWithRetry(rm, target, attempts = 3) {
+  for (let attempt = 0; ; attempt += 1) {
+    try {
+      rm(target, { recursive: true, force: true });
+      return null;
+    } catch (error) {
+      const code = typeof error?.code === "string" ? error.code : "EUNKNOWN";
+      if (!RETRYABLE_REMOVE_CODES.has(code) || attempt >= attempts - 1) return code;
+      const until = Date.now() + 100 * (attempt + 1);
+      while (Date.now() < until) { /* brief synchronous backoff, as renameWithRetry */ }
+    }
+  }
+}
+
+/**
+ * Remove an owned staging directory. The marker goes last and only once everything else is
+ * gone, so a tree held open by a running executable (the reported locked `bunx.exe`) stays
+ * provably ours and the next update can finish the job.
+ */
+export function removeOwnedStage(stageRoot, deps = {}) {
+  const rm = deps.rm ?? rmSync;
+  let names;
+  try {
+    names = readdirSync(stageRoot);
+  } catch (error) {
+    return error?.code === "ENOENT" ? { removed: true } : { removed: false, code: error?.code ?? "EUNKNOWN" };
+  }
+  let failure = null;
+  for (const name of names) {
+    if (name === UPDATE_OWNER_MARKER) continue;
+    const code = removeWithRetry(rm, join(stageRoot, name));
+    if (code && !failure) failure = code;
+  }
+  if (failure) return { removed: false, code: failure };
+  const markerCode = removeWithRetry(rm, join(stageRoot, UPDATE_OWNER_MARKER));
+  if (markerCode) return { removed: false, code: markerCode };
+  const dirCode = removeWithRetry(rm, stageRoot);
+  return dirCode ? { removed: false, code: dirCode } : { removed: true };
+}
+
+/**
+ * Clear what earlier update attempts left next to the package, without ever deleting anything
+ * this updater cannot prove it created. Never throws and never fails the update: every stage is
+ * a fresh, uniquely named directory, so a leftover can only cost disk space, not block staging.
+ */
+export function sweepUpdateLeftovers({ packageDir, pkgName, log = () => {}, deps = {} }) {
+  const scopeDir = dirname(packageDir);
+  const now = (deps.now ?? Date.now)();
+  const result = { removed: [], inUse: [], recent: [], notOwned: [] };
+  let names = [];
+  try {
+    names = readdirSync(scopeDir);
+  } catch {
+    return result;
+  }
+  // npm renames a package it is replacing to ".<name>-<random>" during a direct global install.
+  const renameAsidePrefix = "." + basename(packageDir) + "-";
+  for (const name of names.sort()) {
+    const full = join(scopeDir, name);
+    if (name.startsWith(STAGE_PREFIX)) {
+      const marker = readOwnedStageMarker(full, pkgName);
+      if (!marker) {
+        result.notOwned.push(full);
+      } else if (now - marker.createdAt < STALE_STAGE_MIN_AGE_MS) {
+        result.recent.push(full);
+      } else {
+        const removal = removeOwnedStage(full, deps);
+        if (removal.removed) result.removed.push(full);
+        else result.inUse.push({ path: full, code: removal.code });
+      }
+    } else if (name.startsWith(renameAsidePrefix)) {
+      result.notOwned.push(full);
+    }
+  }
+  // Names only: the full path under a user-scoped npm prefix carries the account name, and
+  // this logger is the launcher's console.
+  for (const path of result.removed) log("Removed a staging directory left by an earlier update: " + basename(path));
+  for (const entry of result.inUse) {
+    log("Left an earlier update's staging directory in place (" + entry.code + "; a file inside is still in use); the next update retries it: " + basename(entry.path));
+  }
+  for (const path of result.notOwned) {
+    log("Not removing " + basename(path) + " next to the package: this updater did not create it. Delete it by hand once no OpenCodex process is running from it.");
+  }
+  return result;
+}
+
+/** Whether the launcher that ran this npm update can still drive service/tray recovery. */
+export function launcherUsableAfterNpmUpdate(tx) {
+  return Boolean(tx?.ok || tx?.rolledBack === true || ["stage", "verify", "swap-backup"].includes(tx?.phase));
+}
+
 /** Largest regular file under a directory tree (bounded depth) — locates the Bun binary. */
 function findLargestFile(root, depth = 3) {
   let best;
@@ -247,29 +393,37 @@ export function transactionalNpmUpdate({
 }) {
   const rename = deps.rename ?? renameSync;
   const scopeDir = dirname(packageDir);
-  const stageRoot = join(scopeDir, stampedName(".ocx-staging"));
+  // Leftovers from earlier attempts are cleared or stepped around first; this never fails.
+  try { sweepUpdateLeftovers({ packageDir, pkgName, log, deps }); } catch { /* report-only */ }
+  let stageRoot;
   // GLOBAL-style staging (-g --prefix): npm nests the package's dependencies INSIDE the
   // package dir, exactly like the live global tree this stage will replace. A local-style
   // install would hoist bun/zod to stageRoot/node_modules — siblings that the swap would
   // leave behind, shipping a dependency-less live tree (release-audit blocker).
   // Layout: <stageRoot>/lib/node_modules/<pkg> on POSIX, <stageRoot>/node_modules/<pkg>
   // on Windows.
-  const stagedCandidates = [
-    join(stageRoot, "lib", "node_modules", ...pkgName.split("/")),
-    join(stageRoot, "node_modules", ...pkgName.split("/")),
-  ];
 
   // D1: stage to the side. --prefix keeps npm entirely inside stageRoot; the live tree
   // and the npm bin shims are untouched until the swap. A failure HERE (mkdir EACCES,
   // ENOSPC) must NOT fall back to the destructive legacy install (review High 4): the
   // caller sees a normal phase failure with live untouched.
   try {
-    mkdirSync(stageRoot, { recursive: true });
+    stageRoot = createOwnedStage(scopeDir, pkgName, deps);
   } catch (error) {
     return { ok: false, phase: "stage", error: "could not create staging directory: " + (error?.message ?? String(error)) };
   }
+  const stagedCandidatesIn = root => [
+    join(root, "lib", "node_modules", ...pkgName.split("/")),
+    join(root, "node_modules", ...pkgName.split("/")),
+  ];
+  const discardStage = () => {
+    const removal = removeOwnedStage(stageRoot, deps);
+    if (!removal.removed) {
+      log("Left this update's staging directory in place (" + removal.code + "; a file inside is still in use); the next update removes it: " + basename(stageRoot));
+    }
+  };
   const spec = pkgName + "@" + (targetVersion || tag);
-  log("Staging " + spec + " into " + stageRoot);
+  log("Staging " + spec + " into " + basename(stageRoot) + " next to the package");
   // npm 12 blocks lifecycle scripts by default. Bun's postinstall copies the selected
   // @oven/bun-* executable into bun/bin, so a successful npm exit without this narrow
   // approval leaves the staged tree intentionally incomplete. Allow only the package
@@ -279,19 +433,19 @@ export function transactionalNpmUpdate({
     "--allow-scripts=bun", "--no-audit", "--no-fund", spec,
   ]);
   if (install.status !== 0) {
-    try { rmSync(stageRoot, { recursive: true, force: true }); } catch { /* best effort */ }
+    discardStage();
     return { ok: false, phase: "stage", error: "npm staging install failed (" + (install.status ?? "?") + ")" };
   }
-  const stagedPackage = stagedCandidates.find(dir => existsSync(join(dir, "package.json")));
+  const stagedPackage = stagedCandidatesIn(stageRoot).find(dir => existsSync(join(dir, "package.json")));
   if (!stagedPackage) {
-    try { rmSync(stageRoot, { recursive: true, force: true }); } catch { /* best effort */ }
+    discardStage();
     return { ok: false, phase: "verify", error: "staged package directory not found under " + stageRoot };
   }
 
   // D2: verify INSIDE the stage. Live is still untouched on any failure here.
   const staged = verifyInstallTree(stagedPackage, targetVersion || undefined);
   if (!staged.ok) {
-    try { rmSync(stageRoot, { recursive: true, force: true }); } catch { /* best effort */ }
+    discardStage();
     return { ok: false, phase: "verify", error: "staged tree failed verification: " + staged.failures.join("; ") };
   }
 
@@ -301,13 +455,13 @@ export function transactionalNpmUpdate({
   try {
     mkdirSync(backupRoot, { recursive: true });
   } catch (error) {
-    try { rmSync(stageRoot, { recursive: true, force: true }); } catch { /* best effort */ }
+    discardStage();
     return { ok: false, phase: "swap-backup", error: "could not create backup directory: " + (error?.message ?? String(error)) };
   }
   try {
     renameWithRetry(rename, packageDir, backupPackage);
   } catch (error) {
-    try { rmSync(stageRoot, { recursive: true, force: true }); } catch { /* best effort */ }
+    discardStage();
     try { rmSync(backupRoot, { recursive: true, force: true }); } catch { /* best effort */ }
     return { ok: false, phase: "swap-backup", error: "could not move live tree aside: " + (error?.message ?? String(error)) };
   }
@@ -317,7 +471,7 @@ export function transactionalNpmUpdate({
     // Rollback: reverse the first rename. Double fault leaves the recovery marker.
     try {
       renameWithRetry(rename, backupPackage, packageDir);
-      try { rmSync(stageRoot, { recursive: true, force: true }); } catch { /* best effort */ }
+      discardStage();
       try { rmSync(backupRoot, { recursive: true, force: true }); } catch { /* best effort */ }
       return { ok: false, phase: "swap-live", rolledBack: true, error: "could not place staged tree: " + (error?.message ?? String(error)) };
     } catch (rollbackError) {
@@ -335,9 +489,12 @@ export function transactionalNpmUpdate({
   const liveCheck = verifyInstallTree(packageDir, targetVersion || undefined);
   if (!liveCheck.ok) {
     try {
-      rmSync(packageDir, { recursive: true, force: true });
-      rename(backupPackage, packageDir);
-      try { rmSync(stageRoot, { recursive: true, force: true }); } catch { /* best effort */ }
+      // Move the rejected tree into our own stage instead of deleting it in place: a file held
+      // open there must not turn a clean rollback into a double fault. The stage's marker keeps
+      // it sweepable by the next update.
+      renameWithRetry(rename, packageDir, join(stageRoot, "rejected"));
+      renameWithRetry(rename, backupPackage, packageDir);
+      discardStage();
       try { rmSync(backupRoot, { recursive: true, force: true }); } catch { /* best effort */ }
       return { ok: false, phase: "post-verify", rolledBack: true, error: "live tree failed post-swap verification: " + liveCheck.failures.join("; ") };
     } catch (rollbackError) {
@@ -355,6 +512,6 @@ export function transactionalNpmUpdate({
   // Success: stage scaffolding is disposable now; the backup stays until the next
   // healthy boot reaps it (bootRestoreProbe) — the process that spawned this update may
   // still hold the old cwd.
-  try { rmSync(stageRoot, { recursive: true, force: true }); } catch { /* best effort */ }
+  discardStage();
   return { ok: true, phase: "done", backup: backupPackage };
 }

package/src/update/update-failure-guidance.d.mts

@@ -0,0 +1,8 @@
+export function npmUpdateFailureGuidance(failure: {
+  phase?: string;
+  rolledBack?: boolean;
+  pkgName: string;
+  version?: string;
+  tag?: string;
+}): { previousVersionKept: boolean; lines: string[] };
+export const GUI_UPDATE_FAILURE_NEXT_STEP: string;

package/src/update/update-failure-guidance.mjs

@@ -0,0 +1,47 @@
+/**
+ * What to tell the operator after a failed npm self-update (#5624).
+ *
+ * The transactional updater (`transactional-install.mjs`) either leaves the live package
+ * untouched, rolls it back, or — only on a double fault — leaves it moved aside with a recovery
+ * marker. Each of those needs a different next step, and the one command a user most often
+ * reaches for after a failed update, a bare `npm install -g` under a live proxy, is the one that
+ * fences the proxy (#5496). So the guidance stops the proxy first.
+ *
+ * Plain ESM with no Bun APIs: the Node launcher (`bin/ocx.mjs`) imports it.
+ */
+
+/** Phases in which the live package was never touched. */
+const UNTOUCHED_PHASES = new Set(["stage", "verify", "swap-backup"]);
+
+/**
+ * @param {{ phase?: string; rolledBack?: boolean; pkgName: string; version?: string; tag?: string }} failure
+ * @returns {{ previousVersionKept: boolean; lines: string[] }}
+ */
+export function npmUpdateFailureGuidance({ phase, rolledBack, pkgName, version, tag }) {
+  const reinstall = "npm install -g --allow-scripts=bun " + pkgName + "@" + (version || tag || "latest");
+  const kept = UNTOUCHED_PHASES.has(phase ?? "") || rolledBack === true;
+  if (!kept) {
+    return {
+      previousVersionKept: false,
+      lines: [
+        "The previous version was moved aside and could not be put back automatically.",
+        "Next: run the \"restore\" command recorded in .ocx-recovery.json next to the package, or reinstall with '" + reinstall + "'.",
+      ],
+    };
+  }
+  return {
+    previousVersionKept: true,
+    lines: [
+      "The previous version is still installed.",
+      "Next: run 'ocx update' again. If it fails the same way, run 'ocx stop', then '" + reinstall
+        + "', then 'ocx service restart' ('ocx start' when no background service is installed).",
+    ],
+  };
+}
+
+/**
+ * The dashboard job only sees the launcher's exit status; its output is withheld because it can
+ * carry local paths. Point at the terminal, where the launcher prints the phase-specific step.
+ */
+export const GUI_UPDATE_FAILURE_NEXT_STEP =
+  "Run 'ocx update' in a terminal to see the reason and the exact recovery step.";