UNPKG

@bitkyc08/opencodex

Version:

Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code

1,096 lines • 57.1 kB
import { guardedRenameSync, ownedArtifactRm } from "./mutation-guard.mjs";
/**
 * 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
 *
 * A staging directory is created exclusively and immediately carries an ownership marker
 * (`.ocx-update-owner.json`). Later updates report leftovers but do not delete them: a marker
 * proves provenance only while this process owns the fresh path, not after another local
 * process could have replaced it. Other neighbouring entries are likewise left alone (#5624).
 */
import { probeSpawnSync } from "./mutation-guard.mjs";
import { randomBytes } from "node:crypto";
import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, realpathSync, statSync, writeFileSync } from "node:fs";
import { basename, delimiter, dirname, isAbsolute, join, parse, relative, resolve, sep } from "node:path";
import { isInMarkedPnpmCustomStore } from "./pnpm-store-layout.mjs";

/**
 * Dependency lookup confined to the candidate's OWN tree. This is the npm contract and it
 * must stay lexical: Node's resolver walks the ancestor directory chain, so a global npm
 * candidate at <prefix>/lib/node_modules/@scope/pkg could satisfy its bundled-Bun
 * requirement from <prefix>/lib/node_modules/bun, which belongs to a different package.
 * That verdict is not cosmetic — it accepts a stage that cannot start (D2), skips the
 * post-swap rollback, and lets bootRestoreProbe reap the only known-good backup.
 */
function candidateTreeDependencyDir(packageDir, name) {
  const dir = join(packageDir, "node_modules", ...name.split("/"));
  return existsSync(join(dir, "package.json")) ? dir : undefined;
}

/**
 * The candidate's own bun directory, whether or not it carries a readable package.json.
 * The size gate keys on the DIRECTORY, matching the pre-carry verifier: a half-extracted
 * node_modules/bun holding a truncated binary and no manifest is still a broken tree, and
 * bun is not always among the sentinels, so the sentinel loop cannot be relied on to catch it.
 */
function ownTreeBunDir(packageDir) {
  const dir = join(packageDir, "node_modules", "bun");
  return existsSync(dir) ? dir : undefined;
}

/** The node_modules directory a package sits directly inside, or undefined. */
function enclosingNodeModules(packageDir) {
  const parent = dirname(packageDir);
  if (basename(parent) === "node_modules") return parent;
  // Scoped packages live one level deeper: <node_modules>/@scope/name.
  const grandparent = dirname(parent);
  if (basename(parent).startsWith("@") && basename(grandparent) === "node_modules") return grandparent;
  return undefined;
}

/** pnpm's own bookkeeping at the root of a node_modules tree it manages. */
function isPnpmManagedRoot(nodeModulesDir) {
  if (!nodeModulesDir) return false;
  if (nodeModulesDir.split(/[\\/]/).includes(".pnpm")) return true;
  return existsSync(join(nodeModulesDir, ".pnpm")) || existsSync(join(nodeModulesDir, ".modules.yaml"));
}

/**
 * Containment is checked on canonical paths, with a separator boundary rather than a
 * string prefix so a sibling with a similar name cannot count as part of the store.
 */
function inside(path, root) {
  const rel = relative(root, path);
  return rel === "" || (rel !== ".." && !rel.startsWith(".." + sep) && !isAbsolute(rel));
}

/**
 * Follow one link's own text component by component, as the operating system does. Collapsing ".."
 * first would hide a relay such as `../outside/relay/../../store/...`. A step down must land inside
 * an allowed root or on an ancestor of one (pnpm's relative links climb through those ancestors); a
 * step through another link before the last component is refused, because ".." after it would be
 * resolved from that link's target rather than from the spelling checked here.
 */
function followLinkText(linkPath, text, spellings) {
  const raw = String(text);
  const root = isAbsolute(raw) ? parse(raw).root : "";
  const parts = raw.slice(root.length).split(sep === "\\" ? /[\\/]+/ : /\/+/).filter(part => part && part !== ".");
  let current = root ? resolve(root) : dirname(linkPath);
  for (let index = 0; index < parts.length; index += 1) {
    if (parts[index] === "..") { current = dirname(current); continue; }
    current = join(current, parts[index]);
    if (!spellings.some(root => inside(current, root) || inside(root, current))) throw new Error("link is outside the selected store");
    if (index < parts.length - 1) {
      let stat;
      try { stat = lstatSync(current); } catch { throw new Error("link is outside the selected store"); }
      if (stat.isSymbolicLink()) throw new Error("link is outside the selected store");
    }
  }
  return current;
}

/** Resolve every link after entering a store; an external hop cannot vouch for a later return. */
function resolveStoreLinkChain(path, store, alias, alternateRoot, alternateAlias) {
  const roots = alternateRoot ? [store, alternateRoot] : [store];
  const spellings = [store, alias, alternateRoot, alternateAlias].filter(Boolean);
  const normalize = value => {
    const target = resolve(value);
    if (alias && inside(target, alias)) return resolve(store, relative(alias, target));
    if (alternateAlias && inside(target, alternateAlias)) return resolve(alternateRoot, relative(alternateAlias, target));
    return target;
  };
  let pending = normalize(path), hops = 0;
  for (;;) {
    const root = roots.find(candidate => inside(pending, candidate));
    if (!root) throw new Error("link is outside the selected store");
    const parts = relative(root, pending).split(sep).filter(Boolean);
    let prefix = root, changed = false;
    for (let index = 0; index < parts.length; index += 1) {
      prefix = join(prefix, parts[index]);
      if (!lstatSync(prefix).isSymbolicLink()) continue;
      if (++hops > 64) throw new Error("too many store link hops");
      const target = normalize(followLinkText(prefix, readlinkSync(prefix), spellings));
      if (!roots.some(candidate => inside(target, candidate))) throw new Error("link is outside the selected store");
      pending = resolve(target, ...parts.slice(index + 1));
      changed = true;
      break;
    }
    if (!changed) return prefix;
  }
}

/** "none" without a v<N>/links component, "isolated" when a .pnpm store sits below the last one, else "links". */
function linksComponentState(path) {
  const parts = String(path).split(/[\\/]+/);
  let links = -1;
  for (let i = 1; i < parts.length; i += 1) {
    if (/^links$/i.test(parts[i]) && /^v\d+$/i.test(parts[i - 1])) links = i;
  }
  if (links < 0) return "none";
  for (let i = links + 1; i < parts.length - 1; i += 1) {
    if (/^node_modules$/i.test(parts[i]) && /^\.pnpm$/i.test(parts[i + 1])) return "isolated";
  }
  return "links";
}

/** The spelling up to and including its last v<N>/links component, or null without one. */
function linksRoot(path) {
  const parts = String(path).split(/[\\/]+/);
  let links = -1;
  for (let i = 1; i < parts.length; i += 1) {
    if (/^links$/i.test(parts[i]) && /^v\d+$/i.test(parts[i - 1])) links = i;
  }
  return links < 0 ? null : parts.slice(0, links + 1).join(sep) || sep;
}

/** Retain intermediate spellings: realpath alone hides a links directory behind another symlink. */
function packagePathUsesGlobalLinks(packageDir, store, storeAlias = store) {
  let path = resolve(packageDir);
  let found = false;
  // Spellings with a v<N>/links component. Each classifies unless the package finally lands in an isolated
  // install (a node_modules/.pnpm store) inside that same links directory: an isolated group's top-level link
  // into its own .pnpm store is not a global-store link, while a link that leaves for anywhere else is.
  const linkRoots = [];
  for (let hop = 0; hop < 64; hop += 1) {
    if (store && (inside(path, store) || (storeAlias && inside(path, storeAlias)))) {
      resolveStoreLinkChain(path, store, storeAlias);
    }
    // Every effective spelling, the listed one first, is judged. The isolated-install exception covers the
    // default store/v<N>/links spelling too: a global-store link instance never contains node_modules/.pnpm
    // below its links directory.
    const state = linksComponentState(path);
    if (state === "links") linkRoots.push(linksRoot(path));
    found ||= state === "none" && Boolean(store && inside(path, join(store, "links")));
    // Store markers classify on every effective spelling, not only the final realpath, so a listed path below a
    // marked store whose package link points elsewhere still demands the store proof.
    found ||= isInMarkedPnpmCustomStore(path.replaceAll("\\", "/"), existsSync);
    const root = parse(path).root;
    const parts = path.slice(root.length).split(sep).filter(Boolean);
    let prefix = root, changed = false;
    for (let i = 0; i < parts.length; i += 1) {
      prefix = join(prefix, parts[i]);
      if (lstatSync(prefix).isSymbolicLink()) {
        const target = resolve(dirname(prefix), readlinkSync(prefix));
        const remaining = parts.slice(i + 1);
        // Judge the effective spelling (target plus the rest of the path), so a package reached through a
        // group link classifies exactly as the same location reached directly.
        path = resolve(target, ...remaining);
        changed = true;
        break;
      }
    }
    // The joined spelling after a hop is judged at the top of the next iteration; the final location was
    // judged in this one (owner decision B: a package listed directly inside v<N>/links needs the proof).
    if (!changed) {
      const isolated = linksComponentState(path) === "isolated";
      return found || linkRoots.some(root => !(isolated && inside(path, root)));
    }
  }
  throw new Error("pnpm package symlink chain is too long");
}

/**
 * True unless this root spelling is canonical: no "." or ".." segment (path.resolve would delete them
 * without visiting the links they cross), no link or junction component, and realpath returns the same
 * path (case folded; a case-only symlink is caught by the component walk).
 */
function spellingHasLinkComponent(path) {
  const raw = String(path);
  const { root } = parse(raw);
  const parts = raw.slice(root.length).split(/[\\/]+/).filter(Boolean);
  if (!root || parts.some(part => part === "." || part === "..")) return true;
  let current = root;
  for (const part of parts) {
    current = join(current, part);
    if (lstatSync(current).isSymbolicLink()) return true;
  }
  const fold = value => resolve(value).replaceAll("\\", "/").replace(/\/+$/, "").toLowerCase();
  return fold(realpathSync.native(raw)) !== fold(raw);
}

/**
 * Whether any spelling of this package passes through pnpm store links. This only classifies which
 * proof the updater must obtain; it never accepts a package. An unreadable chain throws.
 */
export function pnpmPackageUsesGlobalStoreLinks(packageDir) {
  if (packagePathUsesGlobalLinks(packageDir, undefined)) return true;
  // A configured virtual-store directory inside a custom store has no \`links\` component; pnpm's
  // store markers route it to the same store proof.
  return isInMarkedPnpmCustomStore(realpathSync(packageDir).replaceAll("\\", "/"), existsSync);
}

/**
 * Dependency roots this package INSTANCE owns. pnpm exposes dependencies in several shapes —
 * symlinks inside the package's own node_modules, a package root that is itself a symlink into
 * the virtual store, or a hoisted group root — so the npm rule alone rejects healthy trees.
 * Ownership is still bounded: an enclosing node_modules counts only when pnpm's own metadata
 * says pnpm manages it, or when the package's realpath group sits in pnpm's global virtual
 * store, which keeps an unrelated ancestor installation out.
 */
function ownedDependencyRoots(packageDir, store) {
  const roots = [];
  const add = dir => { if (dir && !roots.includes(dir)) roots.push(dir); };
  const lexicalGroup = enclosingNodeModules(packageDir);
  add(join(packageDir, "node_modules"));
  let real;
  try { real = realpathSync(packageDir); } catch { /* keep the lexical path only */ }
  if (real && real !== packageDir) add(join(real, "node_modules"));
  if (isPnpmManagedRoot(lexicalGroup)) add(lexicalGroup);
  const realGroup = real ? enclosingNodeModules(real) : undefined;
  if (isPnpmManagedRoot(realGroup) || (store && realGroup && inside(realGroup, store))) add(realGroup);
  return roots;
}

/**
 * pnpm dependency lookup. Probing the owned roots directly, rather than filtering whatever
 * Node's resolver returned, is deliberate: require.resolve reports the REALPATH of the
 * resolved file, so a dependency reached through pnpm's own node_modules symlink comes back
 * as a virtual-store path that no lexical ownership test can recognise. existsSync follows
 * the symlink, which is exactly the pnpm graph edge that proves ownership.
 */
function pnpmOwnedDependencyDir(packageDir, name, store, globalLinks, escaped, roots = ownedDependencyRoots(packageDir, store), storeAlias = store) {
  let matched;
  for (const root of roots) {
    const dir = join(root, ...name.split("/"));
    if (globalLinks) {
      if (name.startsWith("@") && name.includes("/")) {
        const scope = join(root, name.split("/")[0]);
        let scopeStat;
        try { scopeStat = lstatSync(scope); } catch (error) {
          if (error?.code !== "ENOENT" && error?.code !== "ENOTDIR") escaped.add("pnpm dependency link could not be resolved: " + name);
          continue;
        }
        if (scopeStat.isSymbolicLink()) {
          try { if (!inside(realpathSync(scope), store)) { escaped.add("pnpm dependency link escapes the selected store: " + name); continue; } }
          catch { escaped.add("pnpm dependency link could not be resolved: " + name); continue; }
        }
      }
      try { lstatSync(dir); } catch (error) {
        if (error?.code !== "ENOENT" && error?.code !== "ENOTDIR") escaped.add("pnpm dependency link could not be resolved: " + name);
        continue;
      }
      try {
        const realRoot = realpathSync(root);
        if (!inside(realRoot, store)) { escaped.add("pnpm dependency root is outside the selected store: " + name); continue; }
        if (!inside(realpathSync(dir), store)) { escaped.add("pnpm dependency link escapes the selected store: " + name); continue; }
        if (!inside(resolveStoreLinkChain(join(realRoot, ...name.split("/")), store, storeAlias), store)) { escaped.add("pnpm dependency link escapes the selected store: " + name); continue; }
      } catch (error) {
        escaped.add(error?.message === "link is outside the selected store"
          ? "pnpm dependency link escapes the selected store: " + name : "pnpm dependency link could not be resolved: " + name);
        continue;
      }
    }
    if (globalLinks) {
      try {
        if (statSync(dir).isDirectory() && !existsSync(join(dir, "package.json"))) {
          escaped.add("pnpm dependency manifest could not be read: " + name); continue;
        }
      } catch { escaped.add("pnpm dependency link could not be resolved: " + name); continue; }
    }
    if (!matched && existsSync(join(dir, "package.json"))) matched = dir;
  }
  return matched;
}

/** A missing owned entry may still resolve through Node's ancestor lookup. */
function inspectAncestorDependency(packageDir, name, store, escaped) {
  for (let parent = dirname(packageDir); ; parent = dirname(parent)) {
    const candidate = join(parent, "node_modules", ...name.split("/"));
    for (const path of [candidate, candidate + ".js", candidate + ".json", candidate + ".node"]) {
      try { lstatSync(path); } catch (error) {
        if (error?.code !== "ENOENT" && error?.code !== "ENOTDIR") escaped.add("pnpm dependency fallback could not be inspected: " + name);
        continue;
      }
      try {
        const resolved = realpathSync(path);
        escaped.add(inside(resolved, store) ? "pnpm dependency resolves outside its package group: " + name
          : "pnpm dependency can resolve outside the selected store: " + name);
      } catch { escaped.add("pnpm dependency fallback could not be resolved: " + name); }
      return;
    }
    if (parent === dirname(parent)) return;
  }
}

/**
 * Ancestor node_modules inside the store must keep their links in the store. Above the store the walk
 * stops: a user's ~/node_modules is not part of the package. A declared dependency that is missing in
 * the store and resolves from outside is refused separately (inspectAncestorDependency). With
 * preserved symlinks Node walks the lexical ancestors, so that walk keeps every root.
 */
function inspectAncestorRoots(packageDir, store, escaped, preserved = false, storeAlias = store, metadataSeen) {
  for (let parent = dirname(packageDir); ; parent = dirname(parent)) {
    if (!preserved && !inside(parent, store)) return;
    if (basename(parent) !== "node_modules") {
      const root = join(parent, "node_modules");
      let exists = true;
      try { lstatSync(root); } catch (error) {
        exists = false;
        if (error?.code !== "ENOENT" && error?.code !== "ENOTDIR") escaped.add("pnpm ancestor dependency root could not be resolved");
      }
      if (exists) {
        try {
          if (!inside(realpathSync(root), store)) escaped.add(preserved
            ? "pnpm preserved-symlink lookup root is outside the selected store" : "pnpm ancestor dependency root is outside the selected store");
          else {
            resolveStoreLinkChain(root, store, storeAlias);
            inspectPnpmMetadata(root, store, escaped, "ancestor dependency lookup", storeAlias, metadataSeen);
          }
        }
        catch { escaped.add("pnpm ancestor dependency root could not be resolved"); }
      }
    }
    if (parent === dirname(parent)) return;
  }
}

/** Resolve existing ancestors too, so a missing entry cannot hide an escaping symlink. */
function canonicalProspectivePath(path) {
  const missing = [];
  for (let current = path; ; current = dirname(current)) {
    try { return resolve(realpathSync(current), ...missing.reverse()); }
    catch (error) {
      if ((error?.code !== "ENOENT" && error?.code !== "ENOTDIR") || current === dirname(current)) throw error;
      missing.push(basename(current));
    }
  }
}

function inspectPackageEntries(packageDir, manifest, store, escaped, alternateRoot) {
  const values = [manifest.main, manifest.module, manifest.bin, manifest.exports];
  const pending = [...values];
  while (pending.length) {
    const entry = pending.pop();
    if (entry && typeof entry === "object") { pending.push(...Object.values(entry)); continue; }
    if (typeof entry !== "string" || !entry) continue;
    try {
      const target = canonicalProspectivePath(resolve(packageDir, entry));
      if (!inside(target, store) && (!alternateRoot || !inside(target, alternateRoot))) {
        escaped.add("pnpm package entry point is outside the selected store");
      }
    } catch { escaped.add("pnpm package entry point could not be resolved"); }
  }
}

/** pnpm's metadata and executable directories are not packages, but their links still must stay inside the store. */
function inspectPnpmMetadata(path, store, escaped, kind, storeAlias = store, seen = new Set()) {
  const pending = [path];
  while (pending.length) {
    const current = pending.pop();
    let real;
    try {
      if (inside(current, store) && (current === path || lstatSync(current).isSymbolicLink())) {
        resolveStoreLinkChain(current, store, storeAlias);
      }
      real = realpathSync(current);
    }
    catch (error) {
      escaped.add("pnpm " + kind + (error?.message === "link is outside the selected store"
        ? " link escapes the selected store: " : " link could not be resolved: ") + basename(current));
      continue;
    }
    if (!inside(real, store)) { escaped.add("pnpm " + kind + " link escapes the selected store: " + basename(current)); continue; }
    if (seen.has(real)) continue;
    if (seen.size >= 10000) { escaped.add("pnpm metadata graph exceeds verification limit"); return; }
    seen.add(real);
    try {
      if (statSync(real).isDirectory()) for (const entry of readdirSync(real, { withFileTypes: true })) {
        if (!entry.isFile()) pending.push(join(real, entry.name));
      }
    }
    catch { escaped.add("pnpm " + kind + " link could not be resolved: " + basename(current)); }
  }
}

/**
 * Node's built-in global lookup paths, computed the way Node's module loader builds Module.globalPaths
 * (before NODE_PATH): $HOME/.node_modules and $HOME/.node_libraries (USERPROFILE on Windows), then
 * <prefix>/lib/node, where prefix is the executable's directory on Windows and its parent elsewhere.
 */
function nodeGlobalLookupPaths() {
  const home = process.platform === "win32" ? process.env.USERPROFILE : process.env.HOME;
  const prefix = process.platform === "win32" ? resolve(process.execPath, "..") : resolve(process.execPath, "..", "..");
  return [...(home ? [resolve(home, ".node_modules"), resolve(home, ".node_libraries")] : []), resolve(prefix, "lib", "node")];
}

/**
 * Node's global search paths (Module.globalPaths, NODE_PATH) that lie inside the store must keep their
 * links there. Paths outside the store are the user's environment, not the package: they are not
 * evidence that the package left its store, and a missing declared dependency they could supply is
 * refused by inspectAncestorDependency's missing-dependency rule.
 */
function inspectGlobalLookupRoots(store, escaped, storeAlias = store) {
  const lookupRoots = new Set([...nodeGlobalLookupPaths(), ...String(process.env.NODE_PATH ?? "").split(delimiter).filter(Boolean)]);
  for (const raw of lookupRoots) {
    const root = resolve(raw);
    try { lstatSync(root); } catch (error) {
      if (error?.code !== "ENOENT" && error?.code !== "ENOTDIR") escaped.add("pnpm global dependency lookup root could not be resolved");
      continue;
    }
    try {
      let real;
      // A dangling entry supplies nothing, like a missing one.
      try { real = realpathSync(root); } catch (error) { if (error?.code === "ENOENT" || error?.code === "ENOTDIR") continue; throw error; }
      // Only a root whose own spelling lies in the store is part of it; an outside link into the store is
      // the user's environment, like any other outside entry. An in-store spelling must stay in the store.
      if (!(inside(root, store) || (storeAlias && inside(root, resolve(storeAlias))))) continue;
      if (!inside(real, store)) { escaped.add("pnpm global dependency lookup root is outside the selected store"); continue; }
      resolveStoreLinkChain(root, store, storeAlias);
    } catch { escaped.add("pnpm global dependency lookup root could not be resolved"); continue; }
    inspectPnpmMetadata(root, store, escaped, "global dependency lookup", storeAlias);
  }
}

/** Find nested module roots and validate package links without following them outside the store. */
function nestedPnpmRoots(packageDir, store, escaped, budget, storeAlias = store) {
  const pending = [packageDir], seen = new Set(), roots = [];
  while (pending.length) {
    const current = pending.pop();
    let real;
    try { real = realpathSync(current); } catch { escaped.add("pnpm package path could not be resolved"); continue; }
    if (!inside(real, store)) { escaped.add("pnpm package link escapes the selected store"); continue; }
    const manifestPath = join(current, "package.json");
    try {
      lstatSync(manifestPath);
      try {
        const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
        inspectPackageEntries(current, manifest, store, escaped);
        if (current !== real) inspectPackageEntries(real, manifest, store, escaped);
      } catch { escaped.add("pnpm nested package manifest could not be read"); }
    } catch (error) {
      if (error?.code !== "ENOENT") escaped.add("pnpm nested package manifest could not be read");
    }
    if (seen.has(real)) continue;
    if (budget.remaining-- <= 0) { escaped.add("pnpm package traversal exceeds verification limit"); return roots; }
    seen.add(real);
    try {
      for (const entry of readdirSync(real, { withFileTypes: true })) {
        const child = join(current, entry.name);
        if (entry.name === "node_modules") {
          try { roots.push(resolveStoreLinkChain(child, store, storeAlias)); }
          catch { escaped.add("pnpm dependency root could not be resolved"); }
          continue;
        }
        // On Windows readdir reports junctions and directory symlinks as directories; lstat decides there.
        let isLink = entry.isSymbolicLink();
        if (!isLink && entry.isDirectory() && process.platform === "win32") {
          try { isLink = lstatSync(join(real, entry.name)).isSymbolicLink(); }
          catch { escaped.add("pnpm package link could not be resolved"); continue; }
        }
        if (!isLink && entry.isDirectory()) pending.push(child);
        else if (isLink) {
          try {
            const target = resolveStoreLinkChain(child, store, storeAlias);
            if (!inside(target, store)) escaped.add("pnpm package link escapes the selected store");
            else if (statSync(target).isDirectory()) pending.push(target);
          } catch (error) { escaped.add(error?.message === "link is outside the selected store"
            ? "pnpm package link escapes the selected store" : "pnpm package link could not be resolved"); }
        }
      }
    } catch { escaped.add("pnpm package directory could not be inspected"); }
  }
  return roots;
}

/** Check reachable global-store package roots and declared dependency links, including cycles. */
function inspectGlobalPnpmGraph(packageDir, store, escaped, storeAlias = store) {
  const pending = [packageDir], seen = new Set(), enumeratedRoots = new Set();
  const ancestorMetadataSeen = new Set(), metadataSeen = new Map(), budget = { remaining: 100000 };
  inspectGlobalLookupRoots(store, escaped, storeAlias);
  while (pending.length) {
    const spelling = pending.pop();
    let path;
    try { path = realpathSync(spelling); } catch { escaped.add("pnpm dependency package could not be resolved"); continue; }
    let manifest;
    try { manifest = JSON.parse(readFileSync(join(spelling, "package.json"), "utf8")); }
    catch { escaped.add("pnpm dependency manifest could not be read"); continue; }
    inspectPackageEntries(spelling, manifest, store, escaped);
    if (path !== spelling) inspectPackageEntries(path, manifest, store, escaped);
    if (seen.has(path)) continue;
    if (seen.size >= 10000) { escaped.add("pnpm dependency graph exceeds verification limit"); return; }
    seen.add(path);
    inspectAncestorRoots(path, store, escaped, false, storeAlias, ancestorMetadataSeen);
    const names = new Set();
    const nestedRoots = nestedPnpmRoots(spelling, store, escaped, budget, storeAlias);
    const ownRoot = join(path, "node_modules"), groupRoot = enclosingNodeModules(path);
    const enqueueRootEntry = (root, name) => {
      const dependency = pnpmOwnedDependencyDir(path, name, store, true, escaped, [root], storeAlias);
      if (dependency) pending.push(dependency);
    };
    for (const root of [...new Set([ownRoot, groupRoot, ...nestedRoots])]) {
      if (!root) continue;
      try { lstatSync(root); } catch (error) {
        if (error?.code !== "ENOENT" && error?.code !== "ENOTDIR") escaped.add("pnpm dependency root could not be resolved");
        continue;
      }
      try {
        const realRoot = realpathSync(root);
        if (!inside(realRoot, store)) { escaped.add("pnpm dependency root is outside the selected store"); continue; }
        if (inside(root, store) || (storeAlias && inside(root, storeAlias))) resolveStoreLinkChain(root, store, storeAlias);
        // Link hops for each spelling were checked above; expand the physical group once.
        if (enumeratedRoots.has(realRoot)) continue;
        enumeratedRoots.add(realRoot);
        for (const name of readdirSync(root)) {
          if ([".bin", ".pnpm", ".modules.yaml"].includes(name)) {
            const kind = name === ".bin" ? "binary" : "metadata";
            if (!metadataSeen.has(kind)) metadataSeen.set(kind, new Set());
            inspectPnpmMetadata(join(root, name), store, escaped, kind, storeAlias, metadataSeen.get(kind));
            continue;
          }
          if (!name.startsWith("@")) { enqueueRootEntry(root, name); continue; }
          const scope = join(root, name);
          try {
            if (!inside(realpathSync(scope), store)) { escaped.add("pnpm dependency scope is outside the selected store: " + name); continue; }
            if (statSync(scope).isDirectory()) for (const child of readdirSync(scope)) enqueueRootEntry(root, name + "/" + child);
          } catch { escaped.add("pnpm dependency scope could not be resolved: " + name); }
        }
      } catch { escaped.add("pnpm dependency root could not be resolved"); }
    }
    for (const name of [...Object.keys(manifest.dependencies ?? {}), ...Object.keys(manifest.optionalDependencies ?? {}), ...Object.keys(manifest.peerDependencies ?? {})]) names.add(name);
    for (const name of names) {
      const dependency = pnpmOwnedDependencyDir(path, name, store, true, escaped, undefined, storeAlias);
      if (dependency) pending.push(dependency);
      for (const root of nestedRoots) {
        if (root === ownRoot || root === groupRoot) continue;
        const nested = pnpmOwnedDependencyDir(path, name, store, true, escaped, [root], storeAlias);
        if (nested) pending.push(nested);
      }
      if (!dependency) {
        // pnpm can leave even non-optional peers absent when peer auto-install and strict checking are disabled.
        const required = Object.hasOwn(manifest.dependencies ?? {}, name) && !Object.hasOwn(manifest.optionalDependencies ?? {}, name);
        if (required) {
          escaped.add("pnpm required dependency is missing from the selected store: " + name);
        }
        if (Object.hasOwn(manifest.dependencies ?? {}, name) || Object.hasOwn(manifest.optionalDependencies ?? {}, name)
          || Object.hasOwn(manifest.peerDependencies ?? {}, name)) inspectAncestorDependency(path, name, store, escaped);
      }
    }
  }
}

/** Verification manifest for a staged (or live) package tree. */
function verifyTreeWithDependencyLookup(packageDir, expectedVersion, dependencyDir, inspectAllLinks = false) {
  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 = dependencyDir(packageDir, "bun") ?? ownTreeBunDir(packageDir);
  if (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 ?? {});
  if (inspectAllLinks) for (const name of new Set([...deps, ...Object.keys(pkg.optionalDependencies ?? {})])) dependencyDir(packageDir, name);
  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) {
    if (!dependencyDir(packageDir, name)) failures.push("sentinel dependency missing: " + name);
  }
  return failures.length === 0 ? { ok: true, failures: [] } : { ok: false, failures };
}

/**
 * npm (and every recovery decision): the candidate must be self-contained. Used by
 * transactionalNpmUpdate's stage and post-swap checks and by bootRestoreProbe.
 */
export function verifyInstallTree(packageDir, expectedVersion) {
  return verifyTreeWithDependencyLookup(packageDir, expectedVersion, candidateTreeDependencyDir);
}

/**
 * Verify a package exposed through pnpm's global virtual store. pnpm 10/11 may use an
 * isolated virtual store, a custom virtualStoreDir, global virtual-store links, or a
 * hoisted linker, so the dependency may sit outside the package directory — but it must
 * still be reachable through a root this package instance owns.
 */
export function verifyPnpmInstallTree(packageDir, expectedVersion, store, globalRoot, lexicalStore = store) {
  let real, canonicalGlobalRoot;
  try { real = realpathSync(packageDir); } catch { return { ok: false, failures: ["pnpm package path could not be resolved"] }; }
  try { if (store) store = realpathSync(store); } catch { return { ok: false, failures: ["pnpm configured store could not be resolved"] }; }
  if (globalRoot && (!store || !inside(real, store))) {
    try {
      canonicalGlobalRoot = realpathSync(globalRoot);
      if (!inside(real, canonicalGlobalRoot)) return { ok: false, failures: ["pnpm package is outside the selected store and global group"] };
    } catch { return { ok: false, failures: ["pnpm global group could not be resolved"] }; }
  }
  let globalLinks;
  try {
    globalLinks = packagePathUsesGlobalLinks(packageDir, store, lexicalStore) || (store && inside(real, store));
  } catch (error) { return { ok: false, failures: [error?.message === "link is outside the selected store"
    ? "pnpm global links are outside the selected store" : "pnpm package symlink chain could not be resolved"] }; }
  if (globalLinks && (!store || !inside(real, store))) {
    return { ok: false, failures: ["pnpm global links are outside the selected store"] };
  }
  if (globalLinks) {
    // The reported package spelling is walked as written below; resolve() would delete "." and ".."
    // segments without visiting the links they cross, so such a spelling is refused first.
    if (String(packageDir).split(/[\\/]+/).some(part => part === "." || part === "..")) {
      return { ok: false, failures: ["pnpm package path is not canonical"] };
    }
    // Hop roots are only as narrow as their spelling: a link component in the lexical store or global
    // group would make its target, and any relay below it, count as inside.
    for (const root of [lexicalStore, globalRoot]) {
      // A missing group authorizes nothing (see below), so only an existing spelling is inspected.
      if (!root || !existsSync(root)) continue;
      try { if (spellingHasLinkComponent(root)) return { ok: false, failures: ["pnpm store or global group path is not canonical"] }; }
      catch { return { ok: false, failures: ["pnpm store or global group path could not be resolved"] }; }
    }
    // Every hop from the reported spelling to the package must stay inside the selected global group
    // or the selected store; a relay elsewhere cannot vouch for a link that later returns to the store.
    // A group that cannot be resolved authorizes nothing: the path must then start inside the store.
    let canonicalGroup;
    try { if (globalRoot) canonicalGroup = realpathSync(globalRoot); } catch { canonicalGroup = undefined; }
    try {
      const end = canonicalGroup
        ? resolveStoreLinkChain(resolve(packageDir), store, lexicalStore, canonicalGroup, resolve(globalRoot))
        : resolveStoreLinkChain(resolve(packageDir), store, lexicalStore);
      if (!inside(end, store)) throw new Error("link is outside the selected store");
    } catch (error) {
      return { ok: false, failures: [error?.message === "link is outside the selected store"
        ? "pnpm global links are outside the selected store" : "pnpm package symlink chain could not be resolved"] };
    }
  }
  const escaped = new Set();
  if (globalLinks && /(?:^|[\s"'])--preserve-symlinks(?:-main)?(?=$|[\s"'])/.test([...process.execArgv, process.env.NODE_OPTIONS ?? ""].join(" "))) {
    inspectAncestorRoots(resolve(packageDir), store, escaped, true, lexicalStore);
  }
  const result = verifyTreeWithDependencyLookup(packageDir, expectedVersion,
    (path, name) => pnpmOwnedDependencyDir(path, name, store, globalLinks, escaped, undefined, lexicalStore), globalLinks);
  if (globalLinks) inspectGlobalPnpmGraph(real, store, escaped, lexicalStore);
  if (escaped.size) return { ok: false, failures: [...escaped].concat(result.failures) };
  return result;
}

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 reported as recent. npm's staging install is bounded at
 * three minutes by the launcher; the floor distinguishes likely in-flight work from leftovers.
 */
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" });
    // npm's strict script policy plans the global tree before it creates the prefix layout, so
    // `-g --prefix` into a bare stage fails with ENOENT on <stage>/lib (#5760). POSIX global
    // prefixes keep packages under lib/; Windows installs into the prefix itself.
    if (process.platform !== "win32") mkdir(join(stageRoot, "lib"));
  } catch (error) {
    // Created by this call and not yet handed to npm: remove it rather than leave a partial stage.
    try { ownedArtifactRm(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 {
      ownedArtifactRm(target, { recursive: true, force: true }, rm);
      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;
  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 };
}

/**
 * Report what earlier update attempts left next to the package. A marker is forgeable and a
 * pathname can be replaced after inspection, so no later process may recursively delete a
 * leftover by that pathname. Never throws or fails the update: fresh unique stages step around it.
 */
export function sweepUpdateLeftovers({ packageDir, pkgName, log = () => {}, deps = {} }) {
  const scopeDir = dirname(packageDir);
  const now = (deps.now ?? Date.now)();
  const result = { 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 {
        result.inUse.push({ path: full, code: "ESTALE" });
      }
    } 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 entry of result.inUse) {
    log(entry.code === "ESTALE"
      ? "Left an earlier update's staging directory in place; delete it by hand once no OpenCodex process is running from it: " + basename(entry.path)
      : "Left an earlier update's staging directory in place (could not remove it: " + entry.code + "): " + 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", "authorize", "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;
  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, authorize = () => true, attempts = 5) {
  for (let attempt = 0; ; attempt += 1) {
    try {
      guardedRenameSync(authorize, from, to, rename);
      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;
  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 { ownedArtifactRm(join(scopeDir, name), { recursive: true, force: true }); } catch { /* keep */ }
    }
    try { ownedArtifactRm(recoveryMarkerPath(scopeDir), { force: true }); } catch { /* keep */ }
    return { action: "reaped", count: backups.length };
  }
  if (!existsSync(join(newestBackup, "package.json"))) return { action: "none" };
  try {
    try { ownedArtifactRm(packageDir, { recursive: true, force: true }); } catch { /* may not exist */ }
    guardedRenameSync(() => true, newestBackup, packageDir, rename);
    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.
 */
function* npmUpdateTransaction({
  packageDir,
  pkgName,
  targetVersion,
  tag,
  cachePath,
  mayReplacePackage = () => true,
  log = () => {},
  deps = {},
}) {
  const rename = deps.rename;
  const scopeDir = dirname(packageDir);
  // Leftovers from earlier attempts are only reported; fresh unique stages step around them. 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.

  // 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 {
    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) {
      // EACCES/EUNKNOWN do not prove an open file, so the message names the failure
      // without blaming a process; the code stays for whoever reads the log.
      log("Left this update's staging directory in place (could not remove it: " + removal.code + "); later updates will not remove it either — delete it by hand once no OpenCodex process is running from it: " + basename(stageRoot));
    }
  };
  const spec = pkgName + "@" + (targetVersion || tag);
  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
  // whose executable the manifest verifies below; never broaden this to all scripts.
  // --prefix <stage> also moves npm's globalconfig to <stage>/etc/npmrc, so a `cache=` from the
  // operator's global npmrc would be dropped and npm would fall back to its default root. Pin
  // the cache the pre-flight resolved and checked, so staging uses that exact root (#6288).
  const cacheArgs = typeof cachePath === "string" && cachePath.length > 0 ? ["--cache", cachePath] : [];
  const install = yield [
    "install", "-g", "--prefix", stageRoot, ...cacheArgs,
    "--allow-scripts=bun", "--no-audit", "--no-fund", spec,
  ];
  if (install.status !== 0 || install.error || install.processTreeExited === false) {
    if (install.processTreeExited === false) {
      log("Left this update's staging directory in place: process-tree exit was not confirmed; stop the installer before removing " + basename(stageRoot));
    } else discardStage();
    const detail = install.error
      ? [install.error.code, install.error.message].filter(Boolean).join(": ")
      : install.signal ?? install.status ?? "?";
    return { ok: false, phase: "stage", ...(install.processTreeExited === false ? { processTreeExited: false } : {}), error: "npm staging install failed (" + detail + ")" };
  }
  const stagedPackage = stagedCandidatesIn(stageRoot).find(dir => existsSync(join(dir, "package.json")));
  if (!stagedPackage) {
    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) {
    discardStage();
    return { ok: false, phase: "verify", error: "staged tree failed verification: " + staged.failures.join("; ") };
  }

  // The installer may have awaited a supervisor. Only a synchronous true authorizes
  // the live swap; errors, promises and refusals leave live untouched.
  let authorized = false;
  try { authorized = mayReplacePackage() === true; } catch { /* fail closed */ }
  if (!authorized) {
    discardStage();
    return { ok: false, phase: "authorize", error: "package replacement authority changed; rerun from the beginning" };
  }
  // 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) {
    discardStage();
    return { ok: false, phase: "swap-backup", error: "could not create backup directory: " + (error?.message ?? String(error)) };
  }
  try {
    renameWithRetry(rename, packageDir, backupPackage, () => mayReplacePackage() === true);
  } catch (error) {
    discardStage();
    try { ownedArtifactRm(backupRoot, { recursive: true, force: true }); } catch { /* best effort */ }
    return { ok: false, phase: error?.code === "EUPDATEAUTHORITY" ? "authorize" : "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);
      discardStage();
      try { ownedArtifactRm(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 {
      // 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 { ownedArtifactRm(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.
  discardStage();
  return { ok: true, phase: "done", backup: backupPackage };
}

/** Keep synchronous callers while the Node launcher awaits the install/exit barrier. */
export function transactionalNpmUpdate(options) {
  const transaction = npmUpdateTransaction(options);
  const step = transaction.next();
  if (step.done) return step.value;
  // Preserve the legacy status-only transaction on POSIX and for existing callers.
  const install = options.runNpm(step.value);
  return transaction.next({ status: install.status }).value;
}

export async function transactionalNpmUpdateAsync(options) {
  const transaction = npmUpdateTransaction(options);
  const step = transaction.next();
  if (step.done) return step.value;
  let install;
  try { install = await options.runNpm(step.value); }
  catch (error) { install = { status: null, error, processTreeExited: false }; }
  if (install.processTreeExited !== true && !(install.groupExited === true && typeof install.status === "number")) install = { ...install, status: null, processTreeExited: false,
    error: install.error ?? { code: "EINSTALLJOIN", message: "npm process-tree exit was not confirmed" } };
  return transaction.next(install).value;
}