@iislee/opencodex 2.11.0 → 2.31.0

package/src/update/notify.ts

@@ -4,6 +4,7 @@ import { join } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { atomicWriteFile, getConfigDir } from "../config";
 import { hasStarPromptRun } from "../cli/star-prompt";
+import { selfLaunchArgv } from "../lib/self-launch-argv";
 import {
   type Channel,
   currentVersion,
@@ -83,8 +84,12 @@ function gt(a: number[], b: number[]): boolean {
 
 /**
  * Channel-aware "is latest newer than current?".
- * - latest channel: compare maj.min.pat only; prereleases are never "newer"
- *   (parity with codex-rs), so stable users are not pushed onto previews.
+ * - latest channel: compare maj.min.pat only; prerelease TARGETS are never
+ *   "newer" (parity with codex-rs), so stable users are not pushed onto
+ *   previews. An installed preview CURRENT compares by its maj.min.pat core,
+ *   so a stable release with a strictly higher base is offered (same base is
+ *   content-lateral promotion and stays not-newer, mirroring the preview
+ *   channel's O3 rule).
  * - preview channel: preview-vs-preview compares the trailing -preview.N; a
  *   stable release with a strictly higher base counts as newer (O3), while a
  *   stable release with the same base as the current preview does not.
@@ -92,7 +97,7 @@ function gt(a: number[], b: number[]): boolean {
 export function isNewer(latest: string, current: string, channel: Channel): boolean {
   if (channel === "latest") {
     const l = parseStable(latest);
-    const c = parseStable(current);
+    const c = parseStable(current) ?? parsePreview(current)?.slice(0, 3);
     if (!l || !c) return false;
     return gt(l, c);
   }
@@ -162,9 +167,10 @@ function cacheIsStale(cache: VersionCache | null): boolean {
 export function triggerBackgroundRefreshIfStale(channel: Channel, cache: VersionCache | null): void {
   if (!cacheIsStale(cache)) return;
   try {
-    const entry = process.argv[1];
-    if (!entry || !existsSync(entry)) return;
-    const child = spawn(process.execPath, [entry, "__refresh-version", channel], {
+    const commandArgs = ["__refresh-version", channel];
+    const args = selfLaunchArgv(commandArgs);
+    if (args.length > commandArgs.length && (!args[0] || !existsSync(args[0]))) return;
+    const child = spawn(process.execPath, args, {
       detached: true,
       stdio: "ignore",
       windowsHide: true,

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

@@ -0,0 +1,47 @@
+import type { spawnSync } from "node:child_process";
+
+export type NpmCachePreflightReason =
+  | "cache_accessible"
+  | "cache_entry_foreign_owner"
+  | "cache_entry_inaccessible"
+  | "cache_path_malformed"
+  | "inspection_incomplete"
+  | "npm_config_failed"
+  | "npm_unavailable"
+  | "windows_skip"
+  | "worker_failed"
+  | "worker_output_malformed"
+  | "worker_timeout";
+
+export interface NpmCachePreflightResult {
+  ok: boolean;
+  reason: NpmCachePreflightReason;
+}
+
+export interface NpmCacheInspectionOptions {
+  expectedUid?: number;
+  maxDepth?: number;
+  maxEntries?: number;
+  nowMs?: () => number;
+  /** Test seam: resolve a symlinked cache root. Defaults to realpathSync. */
+  realpathFn?: (path: string) => string;
+  /** 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 {
+  env?: NodeJS.ProcessEnv;
+  execPath?: string;
+  platform?: NodeJS.Platform;
+  spawnSyncFn?: typeof spawnSync;
+  timeoutMs?: number;
+}
+
+export function inspectNpmCacheDirectory(
+  cachePath: string,
+  options?: NpmCacheInspectionOptions,
+): NpmCachePreflightResult;
+
+export function runNpmCachePreflight(options?: NpmCachePreflightOptions): NpmCachePreflightResult;
+export function npmCachePreflightFailureMessage(reason: NpmCachePreflightReason): string;

package/src/update/npm-cache-preflight.mjs

@@ -0,0 +1,201 @@
+import { lstatSync, readdirSync, realpathSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { isAbsolute, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { npmInvocation } from "./npm-invocation.mjs";
+
+const WORKER_ARG = "--ocx-npm-cache-preflight-worker";
+const PROTOCOL_VERSION = 1;
+const WORKER_TIMEOUT_MS = 10_000;
+const NPM_CONFIG_TIMEOUT_MS = 5_000;
+const INSPECTION_TIMEOUT_MS = 7_500;
+const MAX_ENTRIES = 100_000;
+const MAX_DEPTH = 64;
+
+const RESULT_REASONS = new Set([
+  "cache_accessible",
+  "cache_entry_foreign_owner",
+  "cache_entry_inaccessible",
+  "cache_path_malformed",
+  "inspection_incomplete",
+  "npm_config_failed",
+  "npm_unavailable",
+]);
+
+function inaccessibleByMode(stat) {
+  if (stat.isSymbolicLink()) return false;
+  const ownerBits = stat.mode & 0o700;
+  if (stat.isDirectory()) return (ownerBits & 0o700) !== 0o700;
+  return (ownerBits & 0o400) === 0;
+}
+
+/**
+ * Inspect an existing Unix npm cache without following symlinks. The limits are
+ * deliberately part of the result contract: an incomplete inspection cannot prove
+ * that replacing the live package will succeed.
+ */
+export function inspectNpmCacheDirectory(cachePath, options = {}) {
+  const expectedUid = options.expectedUid ?? process.getuid?.();
+  const deadline = (options.nowMs ?? Date.now)() + (options.timeoutMs ?? INSPECTION_TIMEOUT_MS);
+  const maxEntries = options.maxEntries ?? MAX_ENTRIES;
+  const maxDepth = options.maxDepth ?? MAX_DEPTH;
+  const nowMs = options.nowMs ?? Date.now;
+  // Injected uid seam. A test cannot create a genuinely foreign-owned file without a second
+  // account, and without this the symlink-before-ownership rule cannot be pinned: `!isDirectory`
+  // skips a link anyway, so removing the rule leaves every assertion green.
+  const uidOf = options.uidOf ?? ((_path, stat) => stat.uid);
+  const stack = [{ path: cachePath, depth: 0 }];
+  let inspected = 0;
+  let rootResolved = false;
+
+  while (stack.length > 0) {
+    // Budget exhausted is NOT a failure. A mature npm cache legitimately holds hundreds of
+    // thousands of entries — this machine's has ~256k — and treating "we ran out of time to
+    // look" as "your cache is broken" would block updates for ordinary users, which is worse
+    // than the bug this preflight exists to prevent. We looked at a bounded prefix, found
+    // nothing wrong, and let the update proceed.
+    if (inspected >= maxEntries || nowMs() > deadline) {
+      return { ok: true, reason: "inspection_incomplete" };
+    }
+    const current = stack.pop();
+    let stat;
+    try {
+      stat = lstatSync(current.path);
+    } catch (error) {
+      if (current.depth === 0 && error?.code === "ENOENT") {
+        return { ok: true, reason: "cache_accessible" };
+      }
+      return { ok: false, reason: "cache_entry_inaccessible" };
+    }
+    inspected += 1;
+
+    // A symlinked cache ROOT used to be rejected outright, but pointing ~/.npm at another volume
+    // is ordinary npm configuration, and blocking those users would be the same false-positive
+    // failure this preflight exists to avoid. Resolve the root once and inspect the target;
+    // only an unresolvable root is a real problem. Nested links are still never followed.
+    if (current.depth === 0 && stat.isSymbolicLink()) {
+      // Resolve exactly once. realpath already collapses a chain, so a second pass would only
+      // happen if the target is itself reported as a link — treat that as unresolvable rather
+      // than looping.
+      if (rootResolved) return { ok: false, reason: "cache_entry_inaccessible" };
+      rootResolved = true;
+      let resolved;
+      try {
+        resolved = (options.realpathFn ?? realpathSync)(current.path);
+      } catch {
+        return { ok: false, reason: "cache_entry_inaccessible" };
+      }
+      stack.push({ path: resolved, depth: 0 });
+      continue;
+    }
+    // A nested symlink is not. npm creates them constantly below _npx, node_modules and .bin,
+    // and we never follow them — so its owner is irrelevant and must not abort the update.
+    // This has to come BEFORE the ownership check: a foreign-owned but never-followed link is
+    // exactly the false positive that made the previous attempt at this feature unusable.
+    if (stat.isSymbolicLink()) continue;
+
+    if (expectedUid !== undefined && uidOf(current.path, stat) !== expectedUid) {
+      return { ok: false, reason: "cache_entry_foreign_owner" };
+    }
+    if (inaccessibleByMode(stat)) {
+      return { ok: false, reason: "cache_entry_inaccessible" };
+    }
+    if (!stat.isDirectory()) continue;
+    // Same reasoning as the entry budget: too deep to finish is not evidence of a bad cache.
+    if (current.depth >= maxDepth) return { ok: true, reason: "inspection_incomplete" };
+
+    let entries;
+    try {
+      entries = readdirSync(current.path, { withFileTypes: true });
+    } catch {
+      return { ok: false, reason: "cache_entry_inaccessible" };
+    }
+    for (const entry of entries) {
+      stack.push({ path: resolve(current.path, entry.name), depth: current.depth + 1 });
+    }
+  }
+
+  return { ok: true, reason: "cache_accessible" };
+}
+
+function workerResult() {
+  const invocation = npmInvocation(["config", "get", "cache"]);
+  if (!invocation) return { ok: false, reason: "npm_unavailable" };
+  const npm = spawnSync(invocation.file, invocation.args, {
+    encoding: "utf8",
+    timeout: NPM_CONFIG_TIMEOUT_MS,
+    windowsHide: true,
+    ...invocation.options,
+  });
+  if (npm.status !== 0) return { ok: false, reason: "npm_config_failed" };
+
+  const output = typeof npm.stdout === "string" ? npm.stdout.trim() : "";
+  if (!output || output.length > 4096 || output.includes("\0") || /[\r\n]/.test(output) || !isAbsolute(output)) {
+    return { ok: false, reason: "cache_path_malformed" };
+  }
+  return inspectNpmCacheDirectory(output);
+}
+
+// Reasons that legitimately accompany `ok: true`. The parser below cross-checks the flag against
+// this set so a worker cannot claim success with a failure reason (or the reverse). It is a SET,
+// not a single value: a bounded inspection that ran out of budget without finding a problem is a
+// pass, and hardcoding `cache_accessible` here silently rejected exactly that — the pass never
+// reached the caller and every large cache still failed, as `worker_output_malformed`.
+const OK_REASONS = new Set([
+  "cache_accessible",
+  "inspection_incomplete",
+  "windows_skip",
+]);
+
+function parseWorkerOutput(stdout) {
+  if (typeof stdout !== "string" || stdout.length > 1024) return null;
+  try {
+    const parsed = JSON.parse(stdout);
+    if (!parsed || parsed.protocol !== PROTOCOL_VERSION || typeof parsed.ok !== "boolean") return null;
+    if (typeof parsed.reason !== "string" || !RESULT_REASONS.has(parsed.reason)) return null;
+    if (parsed.ok !== OK_REASONS.has(parsed.reason)) return null;
+    if (Object.keys(parsed).sort().join(",") !== "ok,protocol,reason") return null;
+    return { ok: parsed.ok, reason: parsed.reason };
+  } catch {
+    return null;
+  }
+}
+
+/** Run the bounded cache inspection in an isolated, synchronously-timeboxed worker. */
+export function runNpmCachePreflight(options = {}) {
+  if ((options.platform ?? process.platform) === "win32") {
+    return { ok: true, reason: "windows_skip" };
+  }
+  const spawn = options.spawnSyncFn ?? spawnSync;
+  const result = spawn(
+    options.execPath ?? process.execPath,
+    [fileURLToPath(import.meta.url), WORKER_ARG],
+    {
+      encoding: "utf8",
+      timeout: options.timeoutMs ?? WORKER_TIMEOUT_MS,
+      windowsHide: true,
+      env: options.env ?? process.env,
+    },
+  );
+  if (result.status === null) return { ok: false, reason: "worker_timeout" };
+  if (result.status !== 0) return { ok: false, reason: "worker_failed" };
+  return parseWorkerOutput(result.stdout) ?? { ok: false, reason: "worker_output_malformed" };
+}
+
+/** Fixed operator guidance; worker/npm output is intentionally never interpolated. */
+export function npmCachePreflightFailureMessage(reason) {
+  return `npm cache access pre-flight failed (${reason}); fix cache ownership and permissions, then retry`;
+}
+
+const isWorker = process.argv[1]
+  && resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+  && process.argv[2] === WORKER_ARG;
+if (isWorker) {
+  let result;
+  try {
+    result = workerResult();
+  } catch {
+    result = { ok: false, reason: "cache_entry_inaccessible" };
+  }
+  process.stdout.write(JSON.stringify({ protocol: PROTOCOL_VERSION, ...result }));
+}

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

@@ -0,0 +1,22 @@
+export type InstallTreeVerification = { ok: boolean; failures: string[] };
+export function verifyInstallTree(packageDir: string, expectedVersion?: string): InstallTreeVerification;
+export function bootRestoreProbe(
+  packageDir: string,
+  deps?: { rename?: (from: string, to: string) => void },
+): { action: "none" | "reaped" | "restored" | "failed"; count?: number; from?: string; error?: string };
+export function transactionalNpmUpdate(args: {
+  packageDir: string;
+  pkgName: string;
+  targetVersion?: string;
+  tag: string;
+  runNpm: (args: string[]) => { status: number | null };
+  log?: (line: string) => void;
+  deps?: { rename?: (from: string, to: string) => void };
+}): {
+  ok: boolean;
+  phase: "stage" | "verify" | "swap-backup" | "swap-live" | "post-verify" | "double-fault" | "done";
+  error?: string;
+  rolledBack?: boolean;
+  backup?: string;
+};
+

package/src/update/transactional-install.mjs

@@ -0,0 +1,259 @@
+/**
+ * Transactional npm self-update: stage -> verify -> swap -> rollback (#1942 / #1849).
+ *
+ * The legacy path ran `npm install -g` straight into the live global tree, so a
+ * failure after npm removed the old files left a file-less package skeleton with no
+ * recovery. This module stages the new version into a SIBLING directory of the live
+ * package (same volume, so directory renames are atomic-ish and never cross devices),
+ * verifies the staged tree with a manifest before anything live is touched, then swaps
+ * live -> backup -> stage-into-live with a reverse-rename rollback on failure and a
+ * recovery marker on double fault.
+ *
+ * Layout (siblings, never children — a child would travel WITH the live rename and the
+ * live dir cannot move into its own subtree):
+ *   <scopeDir>/opencodex                      live package
+ *   <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
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+/** Verification manifest for a staged (or live) package tree. */
+export function verifyInstallTree(packageDir, expectedVersion) {
+  const failures = [];
+  let pkg;
+  try {
+    pkg = JSON.parse(readFileSync(join(packageDir, "package.json"), "utf8"));
+  } catch (error) {
+    return { ok: false, failures: ["package.json unreadable: " + (error?.message ?? String(error))] };
+  }
+  if (expectedVersion && pkg.version !== expectedVersion) {
+    failures.push("package.json version " + pkg.version + " != expected " + expectedVersion);
+  }
+  const launcher = join(packageDir, "bin", "ocx.mjs");
+  try {
+    const st = statSync(launcher);
+    if (!st.isFile() || st.size < 1024) failures.push("bin/ocx.mjs missing or truncated");
+  } catch {
+    failures.push("bin/ocx.mjs absent");
+  }
+  // The bundled Bun binary is the load-bearing artifact: without it the launcher exits
+  // before serving anything, and a boot probe that called this tree healthy would reap
+  // the only backup (review High 3). Size-gate the real binary, not just its package.json.
+  const bunPkgDir = join(packageDir, "node_modules", "bun");
+  if (existsSync(bunPkgDir)) {
+    const bunBinary = findLargestFile(bunPkgDir);
+    if (!bunBinary || bunBinary.size < 10 * 1024 * 1024) {
+      failures.push("bundled Bun binary missing or truncated (< 10MB)");
+    }
+  }
+  // Sentinel direct deps: each must have an intact package.json. The bundled Bun dep is
+  // the load-bearing one — without it the launcher cannot start the proxy at all.
+  const deps = Object.keys(pkg.dependencies ?? {});
+  const sentinels = deps.filter(name => name === "bun" || name === "zod").length > 0
+    ? deps.filter(name => name === "bun" || name === "zod")
+    : deps.slice(0, 2);
+  for (const name of sentinels) {
+    const depPkg = join(packageDir, "node_modules", ...name.split("/"), "package.json");
+    if (!existsSync(depPkg)) failures.push("sentinel dependency missing: " + name);
+  }
+  return failures.length === 0 ? { ok: true, failures: [] } : { ok: false, failures };
+}
+
+function stampedName(prefix) {
+  return prefix + "-" + new Date().toISOString().replace(/[:.]/g, "-");
+}
+
+/** Largest regular file under a directory tree (bounded depth) — locates the Bun binary. */
+function findLargestFile(root, depth = 3) {
+  let best;
+  let names = [];
+  try { names = readdirSync(root); } catch { return undefined; }
+  for (const name of names) {
+    const full = join(root, name);
+    let st;
+    try { st = statSync(full); } catch { continue; }
+    if (st.isFile()) {
+      if (!best || st.size > best.size) best = { path: full, size: st.size };
+    } else if (st.isDirectory() && depth > 0) {
+      const sub = findLargestFile(full, depth - 1);
+      if (sub && (!best || sub.size > best.size)) best = sub;
+    }
+  }
+  return best;
+}
+
+/** Bounded Windows-class rename retry: EPERM/EBUSY/EACCES from AV/indexers clears in ms. */
+function renameWithRetry(rename, from, to, attempts = 5) {
+  for (let attempt = 0; ; attempt += 1) {
+    try {
+      rename(from, to);
+      return;
+    } catch (error) {
+      const code = error?.code;
+      const retryable = code === "EPERM" || code === "EBUSY" || code === "EACCES";
+      if (!retryable || attempt >= attempts - 1) throw error;
+      // Synchronous bounded backoff (launcher context has no async loop here).
+      const until = Date.now() + 100 * (attempt + 1);
+      while (Date.now() < until) { /* spin briefly; total worst case ~1.5s */ }
+    }
+  }
+}
+
+function recoveryMarkerPath(scopeDir) {
+  return join(scopeDir, ".ocx-recovery.json");
+}
+
+/** Startup probe: restore a backup when the live tree is broken (D4 power-loss rows). */
+export function bootRestoreProbe(packageDir, deps = {}) {
+  const rename = deps.rename ?? renameSync;
+  const scopeDir = dirname(packageDir);
+  let backups = [];
+  try {
+    backups = readdirSync(scopeDir).filter(name => name.startsWith(".ocx-backup-")).sort();
+  } catch {
+    return { action: "none" };
+  }
+  if (backups.length === 0) return { action: "none" };
+  const liveOk = existsSync(join(packageDir, "package.json"))
+    && verifyInstallTree(packageDir).ok;
+  const newestBackup = join(scopeDir, backups[backups.length - 1], "opencodex");
+  if (liveOk) {
+    // Live is healthy: the backups are leftovers from a completed swap. Reap them.
+    for (const name of backups) {
+      try { rmSync(join(scopeDir, name), { recursive: true, force: true }); } catch { /* keep */ }
+    }
+    try { rmSync(recoveryMarkerPath(scopeDir), { force: true }); } catch { /* keep */ }
+    return { action: "reaped", count: backups.length };
+  }
+  if (!existsSync(join(newestBackup, "package.json"))) return { action: "none" };
+  try {
+    try { rmSync(packageDir, { recursive: true, force: true }); } catch { /* may not exist */ }
+    rename(newestBackup, packageDir);
+    return { action: "restored", from: newestBackup };
+  } catch (error) {
+    return { action: "failed", error: error?.message ?? String(error) };
+  }
+}
+
+/**
+ * Run the transactional update. `runNpm(args, opts)` is injected so the caller keeps
+ * its hardened npm resolution (npm-invocation.mjs) and logging.
+ */
+export function transactionalNpmUpdate({
+  packageDir,
+  pkgName,
+  targetVersion,
+  tag,
+  runNpm,
+  log = () => {},
+  deps = {},
+}) {
+  const rename = deps.rename ?? renameSync;
+  const scopeDir = dirname(packageDir);
+  const stageRoot = join(scopeDir, stampedName(".ocx-staging"));
+  // 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 });
+  } catch (error) {
+    return { ok: false, phase: "stage", error: "could not create staging directory: " + (error?.message ?? String(error)) };
+  }
+  const spec = pkgName + "@" + (targetVersion || tag);
+  log("Staging " + spec + " into " + stageRoot);
+  const install = runNpm(["install", "-g", "--prefix", stageRoot, "--no-audit", "--no-fund", spec]);
+  if (install.status !== 0) {
+    try { rmSync(stageRoot, { recursive: true, force: true }); } catch { /* best effort */ }
+    return { ok: false, phase: "stage", error: "npm staging install failed (" + (install.status ?? "?") + ")" };
+  }
+  const stagedPackage = stagedCandidates.find(dir => existsSync(join(dir, "package.json")));
+  if (!stagedPackage) {
+    try { rmSync(stageRoot, { recursive: true, force: true }); } catch { /* best effort */ }
+    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 */ }
+    return { ok: false, phase: "verify", error: "staged tree failed verification: " + staged.failures.join("; ") };
+  }
+
+  // D3: swap. live -> backup, stage -> live, re-verify live, rollback on failure.
+  const backupRoot = join(scopeDir, stampedName(".ocx-backup"));
+  const backupPackage = join(backupRoot, "opencodex");
+  try {
+    mkdirSync(backupRoot, { recursive: true });
+  } catch (error) {
+    try { rmSync(stageRoot, { recursive: true, force: true }); } catch { /* best effort */ }
+    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 */ }
+    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)) };
+  }
+  try {
+    renameWithRetry(rename, stagedPackage, packageDir);
+  } catch (error) {
+    // 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 */ }
+      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) {
+      writeFileSync(recoveryMarkerPath(scopeDir), JSON.stringify({
+        at: new Date().toISOString(),
+        backup: backupPackage,
+        live: packageDir,
+        restore: 'move "' + backupPackage + '" back to "' + packageDir + '"',
+        error: String(error?.message ?? error),
+        rollbackError: String(rollbackError?.message ?? rollbackError),
+      }, null, 2));
+      return { ok: false, phase: "double-fault", rolledBack: false, error: "swap and rollback both failed; recovery marker written at " + recoveryMarkerPath(scopeDir) };
+    }
+  }
+  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 */ }
+      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) {
+      writeFileSync(recoveryMarkerPath(scopeDir), JSON.stringify({
+        at: new Date().toISOString(),
+        backup: backupPackage,
+        live: packageDir,
+        restore: 'move "' + backupPackage + '" back to "' + packageDir + '"',
+        error: "post-swap verification failed: " + liveCheck.failures.join("; "),
+        rollbackError: String(rollbackError?.message ?? rollbackError),
+      }, null, 2));
+      return { ok: false, phase: "double-fault", rolledBack: false, error: "post-verify rollback failed; recovery marker written" };
+    }
+  }
+  // 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 */ }
+  return { ok: true, phase: "done", backup: backupPackage };
+}