@ornncompute/cli 0.2.11 → 0.2.12

package/README.md

@@ -357,7 +357,19 @@ between Public and Private VPN preserves the peer.
 
 ## Updating
 
-The CLI checks the npm registry for a newer version at most once per day and prints a one-line notice on stderr when one exists. Run `ornn update` to install it (the command detects npm, pnpm, yarn, or bun installs). The check is skipped in CI and non-interactive shells.
+Interactive global installations check for new releases in the background,
+using a daily interval. When a newer release has been discovered, Ornn
+installs it before your next eligible command and then runs that command
+with the updated CLI. The first check has a one-day grace period.
+
+Automatic updates are skipped in CI, with redirected input or output,
+for machine-readable output, and for help or version commands. Project
+dependencies, development checkouts, and package-runner invocations do
+not update automatically. Run `ornn update` to check and update immediately.
+
+If an installation fails, Ornn continues only when it can verify that
+the remaining CLI loads successfully. Otherwise it prints reinstall
+instructions. If another update is running, retry after it finishes.
 
 ## Deployment
 

package/bin/ornn.js

@@ -1,11 +1,3 @@
 #!/usr/bin/env node
-
-import { run } from "../src/cli.mjs";
-
-const exitCode = await run(process.argv.slice(2), {
-  env: process.env,
-  stderr: process.stderr,
-  stdout: process.stdout,
-});
-
-process.exitCode = exitCode;
+import { bootstrap } from "../src/startup.mjs";
+process.exitCode = await bootstrap();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ornncompute/cli",
-  "version": "0.2.11",
+  "version": "0.2.12",
   "description": "Command-line interface for Ornn compute access workflows.",
   "type": "module",
   "bin": {
@@ -33,6 +33,9 @@
   "devDependencies": {
     "@ornn/capabilities": "0.1.0"
   },
+  "dependencies": {
+    "update-notifier": "7.3.1"
+  },
   "engines": {
     "node": ">=20"
   }

package/src/cli.mjs

@@ -51,7 +51,7 @@ import {
   tokensListCommand,
   usersQueryCommand,
 } from "./catalog-dispatch.mjs";
-import { maybeNotifyUpdate, updateCommand } from "./update.mjs";
+import { updateCommand } from "./update.mjs";
 
 const { version: VERSION } = createRequire(import.meta.url)("../package.json");
 const DEFAULT_BUY_NOW_USD_PER_GPU_HOUR = 10;
@@ -358,17 +358,7 @@ const GPU_COMMANDS = new Set(["gpu", "gpus", "reservations"]);
 const RESERVATION_OP_SUBCOMMANDS = new Set(["transfer", "deploy", "commerce"]);
 
 export async function run(argv = [], io = {}) {
-  const exitCode = await dispatch(argv, io);
-  if (argv[0] !== "update") {
-    await maybeNotifyUpdate({
-      binPath: io.binPath ?? process.argv[1],
-      currentVersion: VERSION,
-      env: io.env ?? process.env,
-      fetchImpl: io.fetch ?? fetch,
-      stderr: io.stderr ?? process.stderr,
-    });
-  }
-  return exitCode;
+  return await dispatch(argv, io);
 }
 
 async function dispatch(argv = [], io = {}) {
@@ -3874,7 +3864,7 @@ async function storage(rawArgs, context) {
         status: response.status,
       });
     }
-    // Atomic tmp+rename (same pattern as writeUpdateCache): a mid-stream
+    // Atomic tmp+rename: a mid-stream
     // failure must never truncate or replace an existing file at outputPath.
     const partialPath = `${outputPath}.${process.pid}.partial`;
     try {

package/src/command-entry.mjs

@@ -0,0 +1,13 @@
+import { createRequire } from "node:module";
+
+const { version } = createRequire(import.meta.url)("../package.json");
+
+export async function execute(argv, io) {
+  const { run } = await import("./cli.mjs");
+  return await run(argv, io);
+}
+
+export async function probe() {
+  await import("./cli.mjs");
+  return version;
+}

package/src/signals.mjs

@@ -0,0 +1,17 @@
+export function forwardSignals(signalSource, child, onSignal) {
+  const listeners = ["SIGINT", "SIGTERM"].map((signal) => {
+    const listener = () => {
+      onSignal(signal);
+      try {
+        child?.kill?.(signal);
+      } catch {}
+    };
+    signalSource.once(signal, listener);
+    return [signal, listener];
+  });
+  return () => {
+    for (const [signal, listener] of listeners.splice(0)) {
+      signalSource.off?.(signal, listener) ?? signalSource.removeListener?.(signal, listener);
+    }
+  };
+}

package/src/startup.mjs

@@ -0,0 +1,288 @@
+import { spawn } from "node:child_process";
+import { createRequire } from "node:module";
+import { constants } from "node:os";
+import { dirname, join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { forwardSignals } from "./signals.mjs";
+import {
+  acquireUpdateLock,
+  compareVersions,
+  detectInstallContext,
+  installVersion,
+  isValidReleaseVersion,
+  resolveInstalledBin,
+} from "./update.mjs";
+
+const PACKAGE_NAME = "@ornncompute/cli";
+const { version: VERSION } = createRequire(import.meta.url)("../package.json");
+const UPDATE_CHECK_INTERVAL = 24 * 60 * 60 * 1000;
+const PROBE_TIMEOUT_MS = 5000;
+const PROBE_KILL_GRACE_MS = 250;
+const GLOBAL_INSTALL_KINDS = new Set(["bun", "npm", "pnpm", "yarn"]);
+const REINSTALL_GUIDANCE = `Reinstall with: npm install -g ${PACKAGE_NAME}@latest`;
+const PROBE_PROGRAM = `const entry = await import(process.argv[1]);
+process.stdout.write(await entry.probe());`;
+const RESTART_PROGRAM = `const entry = await import(process.argv[1]);
+process.exitCode = await entry.execute(process.argv.slice(3), {
+  binPath: process.argv[2], env: process.env,
+  stdin: process.stdin, stdout: process.stdout, stderr: process.stderr,
+});`;
+
+function hasHumanOnlyArgument(argv) {
+  return argv.some(
+    (arg) =>
+      arg === "--json" ||
+      arg.startsWith("--json=") ||
+      arg === "--raw" ||
+      arg === "--help" ||
+      arg === "-h" ||
+      arg === "help" ||
+      arg === "--version" ||
+      arg === "-v" ||
+      arg === "version",
+  );
+}
+
+export function shouldAutoUpdate(argv, { env = process.env, stdin, stdout, stderr, context } = {}) {
+  if (!GLOBAL_INSTALL_KINDS.has(context?.kind)) {
+    return false;
+  }
+  if ((env.CI && env.CI !== "false") || !stdin?.isTTY || !stdout?.isTTY || !stderr?.isTTY) {
+    return false;
+  }
+  if (argv.length === 0 || argv[0] === "update" || hasHumanOnlyArgument(argv)) {
+    return false;
+  }
+  return true;
+}
+
+async function defaultNotifierFactory(options) {
+  const { default: updateNotifier } = await import("update-notifier");
+  return updateNotifier(options);
+}
+
+function warning(stderr, message) {
+  stderr?.write(`${message}\n`);
+}
+
+function failedProbe(stderr) {
+  warning(stderr, `The installed ornn CLI could not be verified. ${REINSTALL_GUIDANCE}`);
+  return { kind: "exit", code: 1 };
+}
+
+function unavailableLock(stderr) {
+  warning(
+    stderr,
+    "Automatic update unavailable; retry after any other ornn update finishes. If none is running, remove the stale update-install lock from your Ornn config directory or check that directory's permissions.",
+  );
+  return { kind: "exit", code: 1 };
+}
+
+function exitForSignal(signal) {
+  return { kind: "exit", code: 128 + (constants.signals[signal] ?? 1) };
+}
+
+function entryUrl(binPath) {
+  return pathToFileURL(join(dirname(binPath), "..", "src", "command-entry.mjs")).href;
+}
+
+export async function probeInstalledCli(
+  binPath,
+  { spawnProcess = spawn, env = process.env, signalSource = process, timeoutMs = PROBE_TIMEOUT_MS } = {},
+) {
+  return await new Promise((resolve) => {
+    let output = "";
+    let settled = false;
+    let timedOut = false;
+    let forceKillTimer;
+    let timeoutTimer;
+    const child = spawnProcess(process.execPath, ["--input-type=module", "--eval", PROBE_PROGRAM, entryUrl(binPath)], {
+      env,
+      shell: false,
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    const scheduleForceKill = () => {
+      forceKillTimer ??= setTimeout(() => child.kill?.("SIGKILL"), PROBE_KILL_GRACE_MS);
+    };
+    const removeSignals = forwardSignals(signalSource, child, scheduleForceKill);
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeoutTimer);
+      clearTimeout(forceKillTimer);
+      removeSignals();
+      resolve(result);
+    };
+    timeoutTimer = setTimeout(() => {
+      timedOut = true;
+      child.kill?.("SIGTERM");
+      scheduleForceKill();
+    }, timeoutMs);
+    child.stdout?.on("data", (chunk) => {
+      output += String(chunk);
+    });
+    child.on("error", () => finish({ ok: false, version: null }));
+    child.on("close", (code, signal) => {
+      const version = output.trim();
+      const ok = !timedOut && code === 0 && !signal && isValidReleaseVersion(version);
+      finish({
+        ok,
+        version: ok ? version : null,
+      });
+    });
+  });
+}
+
+export async function restartCli(
+  binPath,
+  argv,
+  { spawnProcess = spawn, env = process.env, signalSource = process } = {},
+) {
+  return await new Promise((resolve, reject) => {
+    let parentSignal = null;
+    const child = spawnProcess(
+      process.execPath,
+      ["--input-type=module", "--eval", RESTART_PROGRAM, entryUrl(binPath), binPath, ...argv],
+      { env, shell: false, stdio: "inherit" },
+    );
+    const removeSignals = forwardSignals(signalSource, child, (signal) => {
+      parentSignal ??= signal;
+    });
+    child.on("error", (error) => {
+      removeSignals();
+      reject(error);
+    });
+    child.on("exit", (code, signal) => {
+      removeSignals();
+      const interruption = parentSignal ?? signal;
+      resolve(interruption ? 128 + (constants.signals[interruption] ?? 1) : (code ?? 1));
+    });
+  });
+}
+
+function unexpectedVersion(stderr, version, currentVersion, target) {
+  const detail = isValidReleaseVersion(version)
+    ? `The installer left ornn CLI at ${version}, expected ${target}.`
+    : "The installer left an invalid ornn CLI version.";
+  const downgrade = isValidReleaseVersion(version) && compareVersions(version, currentVersion) < 0;
+  warning(stderr, `${detail}${downgrade ? ` It is older than ${currentVersion}.` : ""} ${REINSTALL_GUIDANCE}`);
+  return { kind: "exit", code: 1 };
+}
+
+export async function prepareStartup(argv, options = {}) {
+  const env = options.env ?? process.env;
+  const stdin = options.stdin ?? process.stdin;
+  const stdout = options.stdout ?? process.stdout;
+  const stderr = options.stderr ?? process.stderr;
+  const binPath = options.binPath ?? process.argv[1];
+  const context = options.context ?? detectInstallContext(binPath, env);
+
+  if (!shouldAutoUpdate(argv, { env, stdin, stdout, stderr, context })) {
+    return { kind: "continue" };
+  }
+
+  let interruptedSignal = null;
+  const signalSource = options.signalSource ?? process;
+  const removeSignals = forwardSignals(signalSource, null, (signal) => {
+    interruptedSignal ??= signal;
+  });
+  const acquireLock = options.acquireLock ?? acquireUpdateLock;
+  const notifierFactory = options.notifierFactory ?? defaultNotifierFactory;
+  const install = options.install ?? installVersion;
+  const resolveBin = options.resolveBin ?? resolveInstalledBin;
+  const probe = options.probe ?? probeInstalledCli;
+  const subprocessOptions = {
+    env,
+    platform: options.platform ?? process.platform,
+    signalSource,
+    spawnProcess: options.spawnProcess ?? spawn,
+  };
+
+  let release;
+  try {
+    try {
+      release = await acquireLock({ env, binPath: context.binPath ?? binPath });
+    } catch {}
+    if (interruptedSignal) return exitForSignal(interruptedSignal);
+    if (typeof release !== "function") return unavailableLock(stderr);
+
+    let target;
+    try {
+      const notifier = await notifierFactory({
+        pkg: { name: PACKAGE_NAME, version: options.currentVersion },
+        updateCheckInterval: UPDATE_CHECK_INTERVAL,
+        distTag: "latest",
+      });
+      target = notifier?.update?.latest;
+    } catch {}
+    if (interruptedSignal) return exitForSignal(interruptedSignal);
+    if (!isValidReleaseVersion(target) || compareVersions(target, options.currentVersion) <= 0) {
+      return { kind: "continue" };
+    }
+
+    warning(stderr, `Updating ornn CLI ${options.currentVersion} -> ${target}...`);
+    let stableBin;
+    try {
+      stableBin = await resolveBin({ context, ...subprocessOptions });
+    } catch {}
+    if (interruptedSignal) return exitForSignal(interruptedSignal);
+    if (!stableBin) {
+      return failedProbe(stderr);
+    }
+
+    let installResult;
+    try {
+      installResult = await install({ context, version: target, ...subprocessOptions });
+    } catch {}
+    if (interruptedSignal || installResult?.signal) {
+      return exitForSignal(interruptedSignal ?? installResult.signal);
+    }
+
+    let replacementBin;
+    try {
+      replacementBin = await resolveBin({ context, ...subprocessOptions });
+    } catch {}
+    if (interruptedSignal) return exitForSignal(interruptedSignal);
+    if (!replacementBin) {
+      return failedProbe(stderr);
+    }
+
+    let result;
+    try {
+      result = await probe(replacementBin, subprocessOptions);
+    } catch {}
+    if (interruptedSignal) return exitForSignal(interruptedSignal);
+    if (!result?.ok) {
+      return failedProbe(stderr);
+    }
+    if (installResult?.exitCode !== 0) {
+      warning(stderr, "The automatic update failed; restarting the verified installed CLI.");
+      return { kind: "restart", binPath: replacementBin };
+    }
+    if (result.version !== target) {
+      return unexpectedVersion(stderr, result.version, options.currentVersion, target);
+    }
+    return { kind: "restart", binPath: replacementBin };
+  } finally {
+    removeSignals();
+    if (typeof release === "function") await Promise.resolve(release()).catch(() => {});
+  }
+}
+
+export async function bootstrap(argv = process.argv.slice(2), io = {}) {
+  const binPath = io.binPath ?? process.argv[1];
+  const env = io.env ?? process.env;
+  const result = await prepareStartup(argv, { ...io, binPath, currentVersion: VERSION, env });
+  if (result.kind === "exit") {
+    return result.code;
+  }
+  if (result.kind === "restart") {
+    return await restartCli(result.binPath, argv, {
+      env,
+      signalSource: io.signalSource ?? process,
+      spawnProcess: io.spawnProcess ?? spawn,
+    });
+  }
+  const entry = await import("./command-entry.mjs");
+  return await entry.execute(argv, { ...io, binPath, env });
+}

package/src/update.mjs

@@ -1,13 +1,14 @@
+import { createHash, randomUUID } from "node:crypto";
 import { existsSync, realpathSync } from "node:fs";
-import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { mkdir, open, readFile, rm } from "node:fs/promises";
 import { homedir } from "node:os";
-import { dirname, isAbsolute, join } from "node:path";
+import { dirname, isAbsolute, join, posix, win32 } from "node:path";
 import { CliApiError } from "./api-client.mjs";
 import { getAuthConfigDir } from "./auth-store.mjs";
+import { forwardSignals } from "./signals.mjs";
 
-export const UPDATE_CHECK_TTL_MS = 24 * 60 * 60 * 1000;
 export const UPDATE_CHECK_TIMEOUT_MS = 3000;
-const UPDATE_CACHE_FILE = "update-check.json";
+const UPDATE_LOCK_PREFIX = "update-install";
 const PACKAGE_NAME = "@ornncompute/cli";
 const VERSION_PATTERN = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
 const INSTALLED_KINDS = new Set(["bun", "npm", "pnpm", "yarn"]);
@@ -19,6 +20,13 @@ const INSTALL_COMMANDS = {
   yarn: (spec) => ["yarn", ["global", "add", spec]],
 };
 
+const GLOBAL_ROOT_COMMANDS = {
+  bun: ["pm", "ls", "-g"],
+  npm: ["root", "-g"],
+  pnpm: ["root", "-g"],
+  yarn: ["global", "dir"],
+};
+
 function parseVersion(value) {
   if (typeof value !== "string") {
     return null;
@@ -77,6 +85,10 @@ export function compareVersions(a, b) {
   return 0;
 }
 
+export function isValidReleaseVersion(version) {
+  return typeof version === "string" && VERSION_PATTERN.test(version);
+}
+
 export function detectInstallContext(binPath, env = process.env) {
   if (!binPath) {
     return { kind: "unknown", binPath: null };
@@ -100,18 +112,30 @@ export function detectInstallContext(binPath, env = process.env) {
   if (!has("node_modules")) {
     return { kind: "dev", binPath: resolved };
   }
-  if (has(".bun") || isUnderDir(lower, env.BUN_INSTALL)) {
+  if (isBunGlobalInstall(lower, env)) {
     return { kind: "bun", binPath: resolved };
   }
-  if (has(".pnpm") || has("pnpm") || isUnderDir(lower, env.PNPM_HOME)) {
+  if (isPnpmGlobalInstall(lower, env)) {
     return { kind: "pnpm", binPath: resolved };
   }
-  if (has("yarn") || has(".yarn")) {
+  if (isYarnGlobalInstall(lower)) {
     return { kind: "yarn", binPath: resolved };
   }
+  if (isNpmGlobalInstall(lower, env)) {
+    return { kind: "npm", binPath: resolved };
+  }
   if (isProjectInstall(resolved, lower)) {
     return { kind: "project", binPath: resolved };
   }
+  if (has(".bun") || isUnderDir(lower, env.BUN_INSTALL)) {
+    return { kind: "bun", binPath: resolved };
+  }
+  if (has(".pnpm") || has("pnpm") || isUnderDir(lower, env.PNPM_HOME)) {
+    return { kind: "pnpm", binPath: resolved };
+  }
+  if (has("yarn") || has(".yarn")) {
+    return { kind: "yarn", binPath: resolved };
+  }
   return { kind: "npm", binPath: resolved };
 }
 
@@ -136,114 +160,274 @@ function isUnderDir(lowerPath, dir) {
   return lowerPath.startsWith(`${trimmed.replaceAll("\\", "/").toLowerCase().replace(/\/+$/, "")}/`);
 }
 
-export function resolveUpdateRegistry(env = process.env) {
-  const registry = env.npm_config_registry?.trim() || "https://registry.npmjs.org";
-  return registry.replace(/\/+$/, "");
+function isBunGlobalInstall(lowerPath, env) {
+  return (
+    lowerPath.includes("/.bun/install/global/node_modules/") ||
+    (isUnderDir(lowerPath, env.BUN_INSTALL) && lowerPath.includes("/install/global/node_modules/"))
+  );
 }
 
-export async function fetchLatestVersion({
-  env = process.env,
-  fetchImpl = fetch,
-  timeoutMs = UPDATE_CHECK_TIMEOUT_MS,
-} = {}) {
-  try {
-    const response = await fetchImpl(`${resolveUpdateRegistry(env)}/${PACKAGE_NAME}/latest`, {
-      headers: { Accept: "application/json" },
-      signal: AbortSignal.timeout(timeoutMs),
-    });
-    if (!response.ok) {
-      return null;
+function isPnpmGlobalInstall(lowerPath, env) {
+  return /\/pnpm\/global\/\d+\/node_modules\//.test(lowerPath) || isUnderDir(lowerPath, env.PNPM_HOME);
+}
+
+function isYarnGlobalInstall(lowerPath) {
+  return lowerPath.includes("/yarn/global/node_modules/") || lowerPath.includes("/yarn/data/global/node_modules/");
+}
+
+function isNpmGlobalInstall(lowerPath, env) {
+  const configuredPrefix = env.npm_config_prefix?.trim();
+  if (configuredPrefix) {
+    let resolvedPrefix = configuredPrefix;
+    try {
+      resolvedPrefix = realpathSync(configuredPrefix);
+    } catch {}
+    const prefix = resolvedPrefix.replaceAll("\\", "/").toLowerCase().replace(/\/+$/, "");
+    if (lowerPath.startsWith(`${prefix}/node_modules/`) || lowerPath.startsWith(`${prefix}/lib/node_modules/`)) {
+      return true;
     }
-    const payload = await response.json();
-    const version = payload?.version;
-    return typeof version === "string" && VERSION_PATTERN.test(version) ? version : null;
-  } catch {
+  }
+
+  if (process.platform !== "win32") {
+    const executable = realpathSync(process.execPath).replaceAll("\\", "/").toLowerCase();
+    const suffix = "/bin/node";
+    if (executable.endsWith(suffix)) {
+      const prefix = executable.slice(0, -suffix.length);
+      return lowerPath.startsWith(`${prefix}/lib/node_modules/`);
+    }
+  }
+  return false;
+}
+
+function pathApi(platform) {
+  return platform === "win32" ? win32 : posix;
+}
+
+function stableInstallRoot(binPath) {
+  if (!binPath) {
     return null;
   }
+  let resolved = binPath;
+  try {
+    resolved = realpathSync(binPath);
+  } catch {}
+  const normalized = resolved.replaceAll("\\", "/");
+  const markerIndex = normalized.toLowerCase().indexOf("/node_modules/");
+  return markerIndex > 0 ? normalized.slice(0, markerIndex) : null;
 }
 
-function updateCachePath(env) {
-  return join(getAuthConfigDir(env), UPDATE_CACHE_FILE);
+function pathIdentity(path) {
+  const normalized = path.replaceAll("\\", "/").replace(/\/+$/, "");
+  return /^[A-Za-z]:\//.test(normalized) ? normalized.toLowerCase() : normalized;
 }
 
-async function readUpdateCache(path) {
+function canonicalPathIdentity(path) {
   try {
-    const parsed = JSON.parse(await readFile(path, "utf8"));
-    return parsed && typeof parsed === "object" ? parsed : null;
+    return pathIdentity(realpathSync(path));
   } catch {
+    return pathIdentity(path);
+  }
+}
+
+function updateLockPath(env, binPath) {
+  const configDir = getAuthConfigDir(env);
+  const installRoot = stableInstallRoot(binPath);
+  if (!installRoot || !isAbsolute(configDir)) {
     return null;
   }
+  const key = createHash("sha256").update(pathIdentity(installRoot)).digest("hex").slice(0, 24);
+  return join(configDir, `${UPDATE_LOCK_PREFIX}-${key}.lock`);
 }
 
-async function writeUpdateCache(path, payload) {
-  // Atomic tmp+rename: survives concurrent runs and replaces a root-owned file left by a past sudo run.
-  const tmpPath = `${path}.${process.pid}.tmp`;
+export async function acquireUpdateLock({ env = process.env, binPath }) {
+  const lockPath = updateLockPath(env, binPath);
+  if (!lockPath) {
+    return null;
+  }
+
+  let handle;
   try {
-    await mkdir(dirname(path), { mode: 0o700, recursive: true });
-    await writeFile(tmpPath, `${JSON.stringify(payload)}\n`, { encoding: "utf8", mode: 0o600 });
-    await rename(tmpPath, path);
-    return true;
+    await mkdir(dirname(lockPath), { mode: 0o700, recursive: true });
+    handle = await open(lockPath, "wx", 0o600);
   } catch {
-    await rm(tmpPath, { force: true }).catch(() => {});
-    return false;
+    return null;
   }
-}
 
-export async function maybeNotifyUpdate({
-  binPath,
-  currentVersion,
-  env = process.env,
-  fetchImpl = fetch,
-  now = Date.now(),
-  stderr,
-}) {
+  const token = randomUUID();
   try {
-    if (env.CI && env.CI !== "false") {
-      return;
-    }
-    if (!stderr?.isTTY) {
-      return;
-    }
-    if (!INSTALLED_KINDS.has(detectInstallContext(binPath, env).kind)) {
-      return;
-    }
-    const cachePath = updateCachePath(env);
-    if (!isAbsolute(cachePath)) {
+    await handle.writeFile(`${JSON.stringify({ pid: process.pid, token })}\n`, "utf8");
+    await handle.close();
+  } catch {
+    await handle.close().catch(() => {});
+    await rm(lockPath, { force: true }).catch(() => {});
+    return null;
+  }
+
+  let released = false;
+  return async () => {
+    if (released) {
       return;
     }
+    released = true;
+    try {
+      const current = JSON.parse(await readFile(lockPath, "utf8"));
+      if (current?.token === token) {
+        await rm(lockPath);
+      }
+    } catch {}
+  };
+}
 
-    const cache = await readUpdateCache(cachePath);
-    let latestKnown =
-      typeof cache?.latestVersion === "string" && VERSION_PATTERN.test(cache.latestVersion)
-        ? cache.latestVersion
-        : null;
-    const checkedAt = Date.parse(cache?.lastCheckedAt ?? "");
-    const fresh = Number.isFinite(checkedAt) && now - checkedAt >= 0 && now - checkedAt < UPDATE_CHECK_TTL_MS;
-
-    if (!fresh) {
-      // Reserve the TTL before fetching so an unwritable cache disables the check instead of taxing every command.
-      const reserved = await writeUpdateCache(cachePath, {
-        lastCheckedAt: new Date(now).toISOString(),
-        latestVersion: latestKnown,
+function installInvocation(context, version) {
+  if (version !== "latest" && !isValidReleaseVersion(version)) {
+    throw new CliApiError("The update target must be a valid release version.");
+  }
+  const commandFactory = INSTALL_COMMANDS[context?.kind];
+  if (!commandFactory) {
+    throw new CliApiError("Could not determine which package manager should install the update.");
+  }
+  return commandFactory(`${PACKAGE_NAME}@${version}`);
+}
+
+export async function installVersion({
+  context,
+  version,
+  spawnProcess,
+  platform = process.platform,
+  env = process.env,
+  signalSource = process,
+}) {
+  const [command, args] = installInvocation(context, version);
+  return await new Promise((resolve, reject) => {
+    let parentSignal = null;
+    let settled = false;
+    const child = spawnProcess(command, args, {
+      env,
+      shell: platform === "win32",
+      stdio: "inherit",
+    });
+    const cleanup = forwardSignals(signalSource, child, (signal) => {
+      parentSignal ??= signal;
+    });
+    child.on("error", (error) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      reject(
+        new CliApiError(
+          error?.code === "ENOENT"
+            ? `${command} was not found on PATH. Install it or run: npm install -g ${PACKAGE_NAME}@latest`
+            : `Failed to run ${command}: ${error?.message ?? error}`,
+        ),
+      );
+    });
+    child.on("exit", (code, signal) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      resolve({
+        exitCode: parentSignal || signal ? 1 : (code ?? 0),
+        signal: parentSignal ?? signal ?? null,
       });
-      if (!reserved) {
-        return;
-      }
-      const fetched = await fetchLatestVersion({ env, fetchImpl });
-      if (fetched) {
-        latestKnown = fetched;
-        await writeUpdateCache(cachePath, {
-          lastCheckedAt: new Date(now).toISOString(),
-          latestVersion: fetched,
-        });
-      }
-    }
+    });
+  });
+}
+
+async function resolveGlobalRoot({ kind, spawnProcess, env, platform, signalSource }) {
+  return await new Promise((resolve) => {
+    let output = "";
+    let interrupted = false;
+    const child = spawnProcess(kind, GLOBAL_ROOT_COMMANDS[kind], {
+      env,
+      shell: platform === "win32",
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    const cleanup = forwardSignals(signalSource, child, () => {
+      interrupted = true;
+    });
+    child.stdout?.on("data", (chunk) => {
+      output += String(chunk);
+    });
+    child.on("error", () => {
+      cleanup();
+      resolve(null);
+    });
+    child.on("exit", (code, signal) => {
+      cleanup();
+      resolve(code === 0 && !signal && !interrupted ? output.trim() || null : null);
+    });
+  });
+}
 
-    if (latestKnown && compareVersions(latestKnown, currentVersion) > 0) {
-      stderr.write(`Update available: ornn CLI ${currentVersion} -> ${latestKnown}. Run \`ornn update\`.\n`);
+export async function resolveInstalledBin({
+  context,
+  spawnProcess,
+  env = process.env,
+  platform = process.platform,
+  signalSource = process,
+}) {
+  if (!INSTALLED_KINDS.has(context?.kind)) {
+    return null;
+  }
+  const installRoot = stableInstallRoot(context.binPath);
+  if (!installRoot) {
+    return null;
+  }
+
+  const paths = pathApi(platform);
+  const packageRoot = paths.join(installRoot, "node_modules");
+  const output = await resolveGlobalRoot({
+    kind: context.kind,
+    spawnProcess,
+    env,
+    platform,
+    signalSource,
+  });
+  let configuredRoot = output;
+  if (context.kind === "bun") {
+    // Bun lists the effective global directory before its dependency tree.
+    configuredRoot = /^(.+) node_modules \(\d+(?: installed)?\)$/.exec(output?.split(/\r?\n/)[0] ?? "")?.[1];
+  }
+  if (!configuredRoot || !paths.isAbsolute(configuredRoot)) {
+    return null;
+  }
+  if (context.kind === "bun" || context.kind === "yarn") {
+    configuredRoot = paths.join(configuredRoot, "node_modules");
+  }
+  if (canonicalPathIdentity(configuredRoot) !== canonicalPathIdentity(packageRoot)) {
+    return null;
+  }
+
+  const candidate = paths.join(packageRoot, "@ornncompute", "cli", "bin", "ornn.js");
+  if (!paths.isAbsolute(candidate) || !existsSync(candidate)) {
+    return null;
+  }
+  return candidate;
+}
+
+export function resolveUpdateRegistry(env = process.env) {
+  const registry = env.npm_config_registry?.trim() || "https://registry.npmjs.org";
+  return registry.replace(/\/+$/, "");
+}
+
+export async function fetchLatestVersion({
+  env = process.env,
+  fetchImpl = fetch,
+  timeoutMs = UPDATE_CHECK_TIMEOUT_MS,
+} = {}) {
+  try {
+    const response = await fetchImpl(`${resolveUpdateRegistry(env)}/${PACKAGE_NAME}/latest`, {
+      headers: { Accept: "application/json" },
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (!response.ok) {
+      return null;
     }
+    const payload = await response.json();
+    const version = payload?.version;
+    return typeof version === "string" && VERSION_PATTERN.test(version) ? version : null;
   } catch {
-    // Never break or slow the command the notifier rides on.
+    return null;
   }
 }
 
@@ -265,95 +449,91 @@ export async function updateCommand({
     throw new CliApiError("ornn is running from a development checkout; update it with git pull.");
   }
   if (context.kind === "project") {
-    throw new CliApiError("ornn is installed as a project dependency; update it there with: npm update @ornncompute/cli");
+    throw new CliApiError(
+      "ornn is installed as a project dependency; update it there with: npm update @ornncompute/cli",
+    );
   }
   if (context.kind === "unknown") {
-    throw new CliApiError("Could not determine how ornn was installed. Reinstall with: npm install -g @ornncompute/cli@latest");
-  }
-
-  const latest = await fetchLatestVersion({ env, fetchImpl });
-  if (latest && compareVersions(latest, currentVersion) <= 0) {
-    await writeUpdateCache(updateCachePath(env), {
-      lastCheckedAt: new Date().toISOString(),
-      latestVersion: latest,
-    });
-    stdout.write(`ornn CLI is already up to date (${currentVersion}).\n`);
-    return 0;
-  }
-  if (!latest) {
-    stderr.write("Could not check the npm registry for the latest version; attempting the update anyway.\n");
+    throw new CliApiError(
+      "Could not determine how ornn was installed. Reinstall with: npm install -g @ornncompute/cli@latest",
+    );
   }
 
-  const spec = `${PACKAGE_NAME}@${latest ?? "latest"}`;
-  const [command, commandArgs] = INSTALL_COMMANDS[context.kind](spec);
-  stderr.write(`Running: ${command} ${commandArgs.join(" ")}\n`);
-  const exitCode = await new Promise((resolve, reject) => {
-    const child = spawnProcess(command, commandArgs, {
-      shell: platform === "win32",
-      stdio: "inherit",
-    });
-    child.on("error", (error) =>
-      reject(
-        new CliApiError(
-          error?.code === "ENOENT"
-            ? `${command} was not found on PATH. Install it or run: npm install -g ${PACKAGE_NAME}@latest`
-            : `Failed to run ${command}: ${error?.message ?? error}`,
-        ),
-      ),
-    );
-    child.on("exit", (code, signal) => resolve(signal ? 1 : code ?? 0));
-  });
-  if (exitCode !== 0) {
+  const releaseLock = await acquireUpdateLock({ env, binPath: context.binPath });
+  if (!releaseLock) {
+    const lockPath = updateLockPath(env, context.binPath);
     throw new CliApiError(
-      updateFailureMessage({ binPath: context.binPath, command, commandArgs, exitCode, kind: context.kind, platform }),
+      `Could not acquire the update lock. If another ornn update is running, wait for it to finish and retry.${
+        lockPath
+          ? ` Otherwise remove the stale lock at ${lockPath} and retry.`
+          : " Check the config directory permissions and retry."
+      }`,
     );
   }
 
-  if (platform === "win32") {
-    stderr.write("If this terminal reports an error after updating, it is safe to ignore; open a new terminal.\n");
-  }
+  try {
+    const installedBin = await resolveInstalledBin({ context, spawnProcess, env, platform });
+    if (!installedBin) {
+      throw new CliApiError(
+        `Could not verify the ${context.kind} global installation root. No files were changed; reinstall with: npm install -g ${PACKAGE_NAME}@latest`,
+      );
+    }
 
-  if (context.kind === "pnpm") {
-    // pnpm shims pin a versioned store path, so re-reads never see the new version; trust pnpm's exit status.
-    if (latest) {
-      stdout.write(`Updated ornn CLI ${currentVersion} -> ${latest}. Run \`ornn --version\` in a new shell to confirm.\n`);
-    } else {
-      stdout.write("Update finished. Run `ornn --version` in a new shell to confirm the installed version.\n");
+    const latest = await fetchLatestVersion({ env, fetchImpl });
+    if (latest && compareVersions(latest, currentVersion) <= 0) {
+      stdout.write(`ornn CLI is already up to date (${currentVersion}).\n`);
+      return 0;
+    }
+    if (!latest) {
+      stderr.write("Could not check the npm registry for the latest version; attempting the update anyway.\n");
     }
-    await writeUpdateCache(updateCachePath(env), {
-      lastCheckedAt: new Date().toISOString(),
-      latestVersion: latest ?? null,
-    });
-    return 0;
-  }
 
-  // Re-resolve the original bin path so the read sees the freshly installed package.
-  const installedVersion = await readInstalledVersion(binPath ?? context.binPath);
-  if (!installedVersion) {
-    stdout.write("Update finished. Run `ornn --version` to confirm the installed version.\n");
-  } else if (installedVersion === currentVersion && latest) {
-    stderr.write(
-      `The installer exited successfully, but this ornn still runs ${currentVersion} from ${context.binPath}. Your registry mirror may be behind, or another install shadows this one; check your PATH.\n`,
-    );
-    return 1;
-  } else if (installedVersion === currentVersion) {
-    stdout.write(`ornn CLI is still ${currentVersion}; the registry may not have a newer version.\n`);
-  } else if (compareVersions(installedVersion, currentVersion) < 0) {
-    stderr.write(
-      `The installer replaced ornn CLI ${currentVersion} with the older ${installedVersion}; your registry mirror may be behind. Reinstall with: npm install -g ${PACKAGE_NAME}@${currentVersion}\n`,
-    );
-    return 1;
-  } else {
-    stdout.write(`Updated ornn CLI ${currentVersion} -> ${installedVersion}.\n`);
-    if (latest && compareVersions(installedVersion, latest) < 0) {
-      stderr.write(`Note: ${latest} is the latest on the registry; your mirror may be behind.\n`);
+    const version = latest ?? "latest";
+    const [command, commandArgs] = installInvocation(context, version);
+    stderr.write(`Running: ${command} ${commandArgs.join(" ")}\n`);
+    const result = await installVersion({ context, version, spawnProcess, platform, env });
+    if (result.exitCode !== 0) {
+      throw new CliApiError(
+        updateFailureMessage({
+          binPath: context.binPath,
+          command,
+          commandArgs,
+          exitCode: result.exitCode,
+          kind: context.kind,
+          platform,
+        }),
+      );
+    }
+
+    if (platform === "win32") {
+      stderr.write("If this terminal reports an error after updating, it is safe to ignore; open a new terminal.\n");
+    }
+
+    const installedVersion = await readInstalledVersion(installedBin);
+    if (!installedVersion) {
+      stdout.write("Update finished. Run `ornn --version` to confirm the installed version.\n");
+    } else if (installedVersion === currentVersion && latest) {
+      stderr.write(
+        `The installer exited successfully, but this ornn still runs ${currentVersion} from ${context.binPath}. Your registry mirror may be behind, or another install shadows this one; check your PATH.\n`,
+      );
+      return 1;
+    } else if (installedVersion === currentVersion) {
+      stdout.write(`ornn CLI is still ${currentVersion}; the registry may not have a newer version.\n`);
+    } else if (compareVersions(installedVersion, currentVersion) < 0) {
+      stderr.write(
+        `The installer replaced ornn CLI ${currentVersion} with the older ${installedVersion}; your registry mirror may be behind. Reinstall with: npm install -g ${PACKAGE_NAME}@${currentVersion}\n`,
+      );
+      return 1;
+    } else {
+      stdout.write(`Updated ornn CLI ${currentVersion} -> ${installedVersion}.\n`);
+      if (latest && compareVersions(installedVersion, latest) < 0) {
+        stderr.write(`Note: ${latest} is the latest on the registry; your mirror may be behind.\n`);
+      }
     }
+    return 0;
+  } finally {
+    await releaseLock();
   }
-  await writeUpdateCache(updateCachePath(env), {
-    lastCheckedAt: new Date().toISOString(),
-    latestVersion: latest ?? installedVersion ?? null,
-  });
-  return 0;
 }
 
 function updateFailureMessage({ binPath, command, commandArgs, exitCode, kind, platform }) {