@skrr-ai/cli 0.1.94 → 0.1.96

package/dist/lib/update-check.js

@@ -37,91 +37,46 @@ exports.normalizeBaseUrl = normalizeBaseUrl;
 exports.isNudgeSuppressed = isNudgeSuppressed;
 exports.isAutoUpdateSuppressed = isAutoUpdateSuppressed;
 exports.isOlderVersion = isOlderVersion;
+exports.isPrivateCliPrefix = isPrivateCliPrefix;
 exports.resolveCliPackageDir = resolveCliPackageDir;
 exports.classifyCliInstall = classifyCliInstall;
+exports.cliUpdateCommand = cliUpdateCommand;
 exports.buildNudgeLine = buildNudgeLine;
 exports.decideCliUpdateAction = decideCliUpdateAction;
+exports.readCliUpdateStatus = readCliUpdateStatus;
+exports.checkCliUpdate = checkCliUpdate;
+exports.performCliUpdate = performCliUpdate;
 exports.maybeWarnOutdatedCli = maybeWarnOutdatedCli;
+exports.shouldCheckCliUpdateAtStartup = shouldCheckCliUpdateAtStartup;
 const node_child_process_1 = require("node:child_process");
 const fs = __importStar(require("node:fs"));
 const os = __importStar(require("node:os"));
 const path = __importStar(require("node:path"));
+const node_crypto_1 = require("node:crypto");
 const node_util_1 = require("node:util");
-/**
- * update-check.ts — non-blocking "a newer `skrr` is available" advisory AND
- * background self-update for installs we own.
- *
- * The standalone `skrr` CLI (npm `@skrr-ai/cli`) has no in-place update path
- * of its own — the bytes belong to whatever installed them. On every command
- * this module decides — from a ~4h on-disk cache, with ZERO added latency —
- * what to do about version state, and refreshes that cache in the background:
- *
- *   - npm-global, writable install + outdated → AUTO-UPDATE: schedule a
- *     detached `npm install -g @skrr-ai/cli@<latest>` that runs after this
- *     command exits (so a mid-flight command never reads half-swapped files),
- *     once per TTL window, and print one stderr line saying so. If a later
- *     run still sees the old version the attempt failed and we fall back to
- *     the manual nudge.
- *   - every other install shape → NUDGE: a single stderr line telling the
- *     user the right update command for THEIR install (a project-local dep
- *     is updated inside its project; a dev checkout is rebuilt, not npm'd).
- *   - installs we must not touch → silence: the app-bundled CLI updates with
- *     the desktop app; image-baked installs (dedicated-runtime guest) are
- *     owned by the image.
- *
- * Hard guarantees (a version check must never make the CLI worse):
- *   - Writes ONLY to stderr, never stdout, so `--json` output stays clean.
- *   - Prints at most ONE line, and only on an interactive TTY — scripts, CI
- *     and pipes neither see the nudge nor trigger an auto-update.
- *   - Never blocks the command: the decision is synchronous off the cache;
- *     the network refresh and install classification are fire-and-forget
- *     and time-bounded; the actual `npm install` is deferred to process
- *     exit and detached.
- *   - Never throws: every path is wrapped so a malformed cache, offline
- *     API, missing npm, or read-only home directory can't break a command.
- *   - Never escalates: a global prefix we cannot write stays a nudge; the
- *     CLI will not reach for sudo.
- *   - Suppressible: `OVERSKY_NO_UPDATE_NUDGE` / `OVERSKY_SKIP_UPDATE_CHECK`
- *     silence everything; `OVERSKY_CLI_AUTO_UPDATE=0` keeps the nudge but
- *     skips the background install; `OVERSKY_CLI_BUNDLED=1` (set by the
- *     desktop app's `skrr` wrapper) suppresses it entirely.
- */
-/** How long a cached advisory stays fresh before a background refresh. */
-const CHECK_TTL_MS = 4 * 60 * 60 * 1000; // 4h
-/** Hard ceiling on the background refresh request. */
+const auth_core_1 = require("@skrr-ai/auth-core");
+/** One update owner and one startup advisory. npm continues to own npm bytes;
+ * the durable worker waits for cooperating CLI sessions before replacing them.
+ * All update decisions are observable, and checking never schedules a change. */
+const CHECK_TTL_MS = 4 * 60 * 60 * 1000;
 const FETCH_TIMEOUT_MS = 1500;
-/** Hard ceiling on the `npm root -g` classification probe. */
 const NPM_ROOT_TIMEOUT_MS = 1500;
-/** Marker written by the dedicated-runtime image bake — a guest's skrr is
- *  image-pinned and must never be told to `npm update -g`. */
+const CLI_PACKAGE = '@skrr-ai/cli';
 const DEDICATED_RUNTIME_ENV_FILE = '/etc/skrr-dedicated-runtime.env';
-/** Daemon-source values for image-pinned (hosted) runtime contexts. */
-const HOSTED_RUNTIME_SOURCES = new Set([
-    'dedicated-runtime',
-    'hosted-machine',
-    'cloud-coding',
-]);
+const HOSTED_RUNTIME_SOURCES = new Set(['dedicated-runtime', 'hosted-machine', 'cloud-coding']);
 const execFileAsync = (0, node_util_1.promisify)(node_child_process_1.execFile);
-function cacheFilePath() {
-    return path.join(os.homedir(), '.skrr', 'cli-update-check.json');
+function cacheFilePath(env = process.env) {
+    return path.join((0, auth_core_1.resolveConfigRoot)(env), 'cli-update-check.json');
 }
-/** Trailing-slash- and case-insensitive normalization for baseURL compares. */
 function normalizeBaseUrl(url) {
     return url.trim().replace(/\/+$/, '').toLowerCase();
 }
 function isTruthyEnv(value) {
-    if (!value)
-        return false;
-    return ['1', 'true', 'on', 'yes'].includes(value.trim().toLowerCase());
+    return !!value && ['1', 'true', 'on', 'yes'].includes(value.trim().toLowerCase());
 }
 function isDisabledEnv(value) {
-    if (!value)
-        return false;
-    return ['0', 'false', 'off', 'no', 'disabled'].includes(value.trim().toLowerCase());
+    return !!value && ['0', 'false', 'off', 'no', 'disabled'].includes(value.trim().toLowerCase());
 }
-/** True when this process runs on an image-pinned hosted-runtime guest. The
- *  env marker covers the daemon unit's context; the env FILE is the reliable
- *  signal for interactive tenant shells that never inherit it. */
 function isHostedRuntimeGuest(env) {
     if (HOSTED_RUNTIME_SOURCES.has((env.OVERSKY_DAEMON_SOURCE ?? '').trim()))
         return true;
@@ -132,67 +87,44 @@ function isHostedRuntimeGuest(env) {
         return false;
     }
 }
-/**
- * True when the advisory must stay silent regardless of version state:
- * explicit suppression, a desktop-app-bundled CLI (which auto-updates with
- * the app and must not be told to `npm update -g`), or an image-baked install
- * the control plane owns.
- */
 function isNudgeSuppressed(env = process.env) {
     return (isTruthyEnv(env.OVERSKY_NO_UPDATE_NUDGE) ||
         isTruthyEnv(env.OVERSKY_SKIP_UPDATE_CHECK) ||
+        isTruthyEnv(env.OCLIF_SKIP_NEW_VERSION_CHECK) ||
         env.OVERSKY_CLI_BUNDLED === '1' ||
         isHostedRuntimeGuest(env));
 }
-/** True when the background self-update is allowed to run at all. Suppression
- *  implies no auto-update — a user who asked for silence did not ask for a
- *  silent mutation of their global npm. */
 function isAutoUpdateSuppressed(env = process.env) {
-    return isNudgeSuppressed(env) || isDisabledEnv(env.OVERSKY_CLI_AUTO_UPDATE);
-}
-/**
- * Parse the numeric release core of a version (`1.2.3-rc.1` → `[1,2,3]`),
- * padded to three parts. Returns null when the core isn't cleanly numeric,
- * so an unparseable version can only ever DISABLE the nudge, never fire a
- * spurious one.
- */
-function parseVersionCore(version) {
-    const core = version.trim().split(/[-+]/, 1)[0];
-    const parts = core.split('.');
-    if (parts.length === 0 || parts.length > 3)
-        return null;
-    const nums = [];
-    for (const part of parts) {
-        if (!/^\d+$/.test(part))
-            return null;
-        nums.push(Number(part));
-    }
-    while (nums.length < 3)
-        nums.push(0);
-    return [nums[0], nums[1], nums[2]];
+    return (isNudgeSuppressed(env) ||
+        isDisabledEnv(env.OVERSKY_CLI_AUTO_UPDATE) ||
+        env.SKRR_CLI_UPDATE_SESSION_UNAVAILABLE === '1');
 }
-/**
- * True iff `current` is strictly older than `latest` by numeric release
- * core. Conservative: any unparseable input returns false (no nudge).
- * Prerelease suffixes are ignored, so `0.2.0-rc.1` is treated as `0.2.0` —
- * we never nag someone testing a prerelease of the latest line.
- */
 function isOlderVersion(current, latest) {
-    const a = parseVersionCore(current);
-    const b = parseVersionCore(latest);
-    if (!a || !b)
+    return (0, auth_core_1.compareReleaseVersions)(current, latest) === -1;
+}
+/** Per-user leases cannot coordinate a global prefix shared with another OS
+ * user. Only private user-owned prefixes participate in managed replacement. */
+function isPrivateCliPrefix(root) {
+    if (process.platform === 'win32' || typeof process.getuid !== 'function')
         return false;
-    for (let i = 0; i < 3; i++) {
-        if (a[i] < b[i])
-            return true;
-        if (a[i] > b[i])
+    try {
+        const home = fs.realpathSync(os.homedir());
+        let directory = fs.realpathSync(root);
+        if (!directory.startsWith(`${home}${path.sep}`))
             return false;
+        while (directory !== home) {
+            const stat = fs.statSync(directory);
+            if (stat.uid !== process.getuid() || (stat.mode & 0o022) !== 0)
+                return false;
+            directory = path.dirname(directory);
+        }
+        const homeStat = fs.statSync(home);
+        return homeStat.uid === process.getuid() && (homeStat.mode & 0o022) === 0;
+    }
+    catch {
+        return false;
     }
-    return false;
 }
-// ---------------------------------------------------------------------------
-// Install-shape classification
-// ---------------------------------------------------------------------------
 const CLI_PACKAGE_DIR_RE = /^(.*[/\\]node_modules[/\\]@skrr-ai[/\\]cli)[/\\]/;
 /**
  * Resolve the package directory this process was launched from when it lives
@@ -240,11 +172,22 @@ function dirWritable(dir) {
  * dir beside `dist` exists only in a checkout — published packages ship
  * `dist` and no `src`.
  */
-function classifyCliInstall(env, argv, npmGlobalRoot) {
-    if (env.OVERSKY_CLI_BUNDLED === '1' || isHostedRuntimeGuest(env)) {
+function classifyCliInstall(env, argv, npmGlobalRoot, probeWritable = true) {
+    if (isHostedRuntimeGuest(env))
+        return { kind: 'image' };
+    if (env.OVERSKY_CLI_BUNDLED === '1')
         return { kind: 'bundled' };
+    const entry = argv[1];
+    try {
+        if (entry && /[/\\]Cellar[/\\]/.test(fs.realpathSync(entry)))
+            return { kind: 'homebrew' };
+    }
+    catch {
+        /* an unavailable entry remains conservatively classified */
     }
     const packageDir = resolveCliPackageDir(argv);
+    if (packageDir && fs.existsSync(path.join(packageDir, 'src', 'commands')))
+        return { kind: 'dev' };
     if (!packageDir) {
         // A dev checkout launches `cli/bin/run.js` directly — a `src/commands`
         // sibling of `dist` exists only in a checkout (published packages ship
@@ -290,7 +233,19 @@ function classifyCliInstall(env, argv, npmGlobalRoot) {
         // proof we must not treat it as ours to auto-update.
         return { kind: 'npm-local' };
     }
-    return { kind: 'npm-global', writable: dirWritable(nodeModulesDir) };
+    let writable = false;
+    if (probeWritable)
+        writable = dirWritable(nodeModulesDir);
+    else {
+        try {
+            fs.accessSync(nodeModulesDir, fs.constants.W_OK);
+            writable = true;
+        }
+        catch {
+            /* read-only */
+        }
+    }
+    return { kind: 'npm-global', writable };
 }
 /**
  * Resolve `npm root -g` for install classification. Runs ONLY inside the
@@ -298,11 +253,12 @@ function classifyCliInstall(env, argv, npmGlobalRoot) {
  * no npm, a timeout, or an odd answer just leaves classification to the
  * path shape alone.
  */
-async function resolveNpmGlobalRoot() {
+async function resolveNpmGlobalRoot(env = process.env) {
     try {
         const npmBin = process.platform === 'win32' ? 'npm.cmd' : 'npm';
         const { stdout } = await execFileAsync(npmBin, ['root', '-g'], {
             timeout: NPM_ROOT_TIMEOUT_MS,
+            env,
             maxBuffer: 64 * 1024,
             shell: process.platform === 'win32',
         });
@@ -313,253 +269,436 @@ async function resolveNpmGlobalRoot() {
         return null;
     }
 }
-// ---------------------------------------------------------------------------
-// Advisory copy — one line, per install shape
-// ---------------------------------------------------------------------------
-/**
- * Build the one-line stderr advisory, or null when no nudge is warranted.
- * `installKind` tailors the command to the bytes' owner: a project-local dep
- * is updated inside its project, a dev checkout is rebuilt — telling either
- * to `npm update -g` would fix the wrong install.
- */
-function buildNudgeLine(currentVersion, latest, npmPackage, installKind) {
-    if (!latest || !isOlderVersion(currentVersion, latest))
-        return null;
-    const pkg = npmPackage || '@skrr-ai/cli';
-    const prefix = `[skrr] Update available: ${currentVersion} → ${latest}. `;
-    const suffix = ` Silence with OVERSKY_NO_UPDATE_NUDGE=1.\n`;
-    switch (installKind) {
+function cliUpdateCommand(owner) {
+    switch (owner) {
+        case 'npm-global':
+            return `npm install -g ${CLI_PACKAGE}@latest`;
         case 'npm-local':
-            return `${prefix}Run \`npm update ${pkg}\` in the owning project.${suffix}`;
+            return `npm update ${CLI_PACKAGE}`;
         case 'dev':
-            return `${prefix}Rebuild your checkout (\`npm --prefix cli run build\`).${suffix}`;
-        case 'other':
-            return `${prefix}Update via your install method — see https://skrr.ai.${suffix}`;
-        case 'npm-global':
+            return 'npm --prefix cli run build';
         case 'bundled':
+            return 'Update the skrr desktop app';
+        case 'image':
+            return 'Update the managed runtime image';
+        case 'homebrew':
+            return 'brew upgrade skrr';
         default:
-            return `${prefix}Run \`npm update -g ${pkg}\` (or update the skrr app).${suffix}`;
+            return 'Update via your install method — see https://skrr.ai';
     }
 }
-/**
- * Decide, synchronously and from cache alone, what this command should do
- * about its version state. Pure — exported for direct unit testing.
- *
- * AUTO-UPDATE fires at most once per TTL window per target version, and only
- * for a provably writable npm-global install on an interactive TTY. An attempt
- * that didn't take (still outdated next run) falls back to the manual nudge
- * rather than retrying immediately.
- */
+function buildNudgeLine(currentVersion, latest, _npmPackage, installKind = 'npm-global') {
+    if (!latest || !isOlderVersion(currentVersion, latest))
+        return null;
+    const command = installKind === 'npm-global' ? `npm update -g ${CLI_PACKAGE}` : cliUpdateCommand(installKind);
+    const context = installKind === 'npm-local'
+        ? ' in the owning project'
+        : installKind === 'dev'
+            ? ' to rebuild your checkout'
+            : '';
+    return `[skrr] Update available: ${currentVersion} → ${latest}. Run \`${command}\`${context}. Silence with OVERSKY_NO_UPDATE_NUDGE=1.\n`;
+}
 function decideCliUpdateAction(args) {
     const { currentVersion, cache, env, isTTY } = args;
-    const now = args.now ?? Date.now();
-    if (!isTTY || isNudgeSuppressed(env))
-        return null;
-    if (!cache || !cache.latest || !isOlderVersion(currentVersion, cache.latest))
+    if (!isTTY ||
+        isNudgeSuppressed(env) ||
+        !cache?.latest ||
+        !isOlderVersion(currentVersion, cache.latest))
         return null;
     const install = cache.install ?? { kind: 'other' };
-    const pkg = cache.npmPackage || '@skrr-ai/cli';
     const attempt = cache.autoUpdate;
-    const attemptFresh = attempt != null && attempt.version === cache.latest && now - attempt.attemptedAt < CHECK_TTL_MS;
-    if (install.kind === 'npm-global' && install.writable === true && !isAutoUpdateSuppressed(env)) {
-        if (!attemptFresh) {
+    const sameAttempt = attempt?.version === cache.latest;
+    const fresh = sameAttempt && (args.now ?? Date.now()) - attempt.attemptedAt < CHECK_TTL_MS;
+    if (sameAttempt &&
+        ((!attempt.status && fresh) || attempt.status === 'queued' || attempt.status === 'running')) {
+        return {
+            type: 'nudge',
+            line: `[skrr] CLI update to ${cache.latest} ${attempt.status === 'running' ? 'is running' : 'is queued until active CLI sessions exit'}. Inspect \`skrr update --status\`.\n`,
+        };
+    }
+    if (install.kind === 'npm-global' && install.writable && !isAutoUpdateSuppressed(env)) {
+        if (!fresh)
             return {
                 type: 'auto-update',
                 version: cache.latest,
-                pkg,
-                line: `[skrr] Updating ${currentVersion} → ${cache.latest} in the background ` +
-                    `(\`npm install -g ${pkg}@${cache.latest}\`). Disable with OVERSKY_CLI_AUTO_UPDATE=0.\n`,
+                pkg: CLI_PACKAGE,
+                line: `[skrr] CLI update ${currentVersion} → ${cache.latest} queued in the background until active CLI sessions exit. Disable with OVERSKY_CLI_AUTO_UPDATE=0.\n`,
             };
-        }
-        // We already tried this version within the window and the update did not
-        // take — tell the user the manual command instead of retrying every run.
+        if (attempt?.status === 'failed')
+            return {
+                type: 'nudge',
+                line: `[skrr] CLI update to ${cache.latest} failed. Inspect \`skrr update --status\` or run \`${cliUpdateCommand(install.kind)}\`.\n`,
+            };
+    }
+    const line = buildNudgeLine(currentVersion, cache.latest, CLI_PACKAGE, install.kind);
+    return line ? { type: 'nudge', line } : null;
+}
+function readCache(env = process.env) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(cacheFilePath(env), 'utf8'));
+        if (typeof parsed.lastCheckAt !== 'number' || typeof parsed.baseURL !== 'string')
+            return null;
         return {
-            type: 'nudge',
-            line: `[skrr] Update available: ${currentVersion} → ${cache.latest}. ` +
-                `The background update did not take — run \`npm update -g ${pkg}\` manually.` +
-                ` Silence with OVERSKY_NO_UPDATE_NUDGE=1.\n`,
+            ...parsed,
+            latest: typeof parsed.latest === 'string' ? parsed.latest : null,
+            npmPackage: CLI_PACKAGE,
         };
     }
-    const line = buildNudgeLine(currentVersion, cache.latest, cache.npmPackage, install.kind);
-    return line ? { type: 'nudge', line } : null;
+    catch {
+        return null;
+    }
 }
-// ---------------------------------------------------------------------------
-// Cache I/O
-// ---------------------------------------------------------------------------
-function readCache() {
+function writeCache(cache, env) {
+    const file = cacheFilePath(env);
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    const temporary = `${file}.${process.pid}.tmp`;
     try {
-        const raw = fs.readFileSync(cacheFilePath(), 'utf8');
-        const parsed = JSON.parse(raw);
-        if (parsed && typeof parsed.lastCheckAt === 'number' && typeof parsed.baseURL === 'string') {
-            return {
-                lastCheckAt: parsed.lastCheckAt,
-                latest: typeof parsed.latest === 'string' ? parsed.latest : null,
-                npmPackage: typeof parsed.npmPackage === 'string' ? parsed.npmPackage : null,
-                baseURL: parsed.baseURL,
-                install: parsed.install && typeof parsed.install.kind === 'string'
-                    ? {
-                        kind: parsed.install.kind,
-                        writable: typeof parsed.install.writable === 'boolean'
-                            ? parsed.install.writable
-                            : undefined,
-                    }
-                    : undefined,
-                autoUpdate: parsed.autoUpdate &&
-                    typeof parsed.autoUpdate.attemptedAt === 'number' &&
-                    typeof parsed.autoUpdate.version === 'string'
-                    ? { attemptedAt: parsed.autoUpdate.attemptedAt, version: parsed.autoUpdate.version }
-                    : undefined,
-            };
-        }
+        fs.writeFileSync(temporary, JSON.stringify(cache), { mode: 0o600 });
+        fs.renameSync(temporary, file);
+    }
+    finally {
+        fs.rmSync(temporary, { force: true });
+    }
+}
+function packageRoot(argv) {
+    const installed = resolveCliPackageDir(argv);
+    if (installed)
+        return installed;
+    try {
+        if (argv[1])
+            return path.resolve(path.dirname(fs.realpathSync(argv[1])), '..');
     }
     catch {
-        // Missing / corrupt cache → treat as absent; a refresh rebuilds it.
+        /* tests and virtual invocations */
     }
-    return null;
+    return path.resolve(__dirname, '..', '..');
+}
+function runtime() {
+    // The standalone CommonJS bootstrap is also copied outside npm's package tree.
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    return require(path.resolve(__dirname, '..', '..', 'bin', 'update-session.cjs'));
 }
-function writeCache(cache) {
+function attemptFor(argv) {
     try {
-        const file = cacheFilePath();
-        fs.mkdirSync(path.dirname(file), { recursive: true });
-        const tmp = `${file}.${process.pid}.tmp`;
-        fs.writeFileSync(tmp, JSON.stringify(cache), { mode: 0o600 });
-        fs.renameSync(tmp, file);
+        return runtime().readJson(path.join(runtime().runtimeDir(packageRoot(argv)), 'result.json'));
     }
     catch {
-        // Best-effort — a read-only home just means we re-check next run.
+        return null;
     }
 }
-/** Persist the auto-update attempt marker without losing the rest of the cache. */
-function markAutoUpdateAttempt(version) {
-    const cache = readCache();
-    if (!cache)
-        return;
-    writeCache({ ...cache, autoUpdate: { attemptedAt: Date.now(), version } });
+function installedCliVersion(argv, fallback) {
+    try {
+        const pkg = JSON.parse(fs.readFileSync(path.join(packageRoot(argv), 'package.json'), 'utf8'));
+        return pkg.name === CLI_PACKAGE && typeof pkg.version === 'string' ? pkg.version : fallback;
+    }
+    catch {
+        return resolveCliPackageDir(argv) ? null : fallback;
+    }
 }
-async function refreshCache(baseURL) {
+/** Cached, read-only status: no network, child process, lease, or mutation. */
+function readCliUpdateStatus(opts) {
+    const env = opts.env ?? process.env;
+    const argv = opts.argv ?? process.argv;
+    const cache = readCache(env);
+    const matchingCache = cache?.baseURL === normalizeBaseUrl(opts.baseURL) ? cache : null;
+    // Classify the actual executing installation each time; a persisted owner
+    // from another installation/profile must never authorize npm mutation.
+    const install = classifyCliInstall(env, argv, matchingCache?.packageRoot === packageRoot(argv) ? (matchingCache.npmGlobalRoot ?? null) : null, false);
+    const installedVersion = installedCliVersion(argv, opts.currentVersion);
+    const offeredVersion = matchingCache?.latest ?? null;
+    let lastAttempt = attemptFor(argv);
+    if (lastAttempt?.status === 'running' && lastAttempt.workerPid) {
+        const api = runtime();
+        const mutation = api.readJson(path.join(api.runtimeDir(packageRoot(argv)), 'mutation.json'));
+        // Only kill(pid, 0): cached status remains free of subprocess/network work.
+        const activeWorker = api.isAlive({ pid: lastAttempt.workerPid });
+        const activeMutation = mutation && api.isAlive({ pid: mutation.pid, group: mutation.group });
+        if (!activeWorker && !activeMutation)
+            lastAttempt = {
+                ...lastAttempt,
+                interrupted: true,
+                message: 'The updater was interrupted. The next interactive invocation retries this request safely.',
+            };
+    }
+    const newer = !!offeredVersion && !!installedVersion && isOlderVersion(installedVersion, offeredVersion);
+    let state = offeredVersion
+        ? newer
+            ? 'update-available'
+            : 'up-to-date'
+        : 'unknown';
+    if (install.kind === 'bundled' || install.kind === 'image')
+        state = 'managed';
+    else if ((lastAttempt?.status === 'queued' || lastAttempt?.status === 'running') &&
+        installedVersion !== lastAttempt.version)
+        state = 'pending';
+    else if (lastAttempt?.status === 'failed' && newer)
+        state = 'failed';
+    else if (installedVersion && isOlderVersion(opts.currentVersion, installedVersion))
+        state = 'restart-pending';
+    let directory;
     try {
-        const url = `${baseURL.replace(/\/+$/, '')}/api/config/cli-version`;
-        const res = await fetch(url, {
-            signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
-            headers: { accept: 'application/json' },
-        });
-        if (!res.ok)
-            return;
-        const body = (await res.json());
-        // Classify the install shape while we're already off the hot path — the
-        // `npm root -g` probe is the only piece that can cost real time and it is
-        // bounded by NPM_ROOT_TIMEOUT_MS. It only runs when the entry point even
-        // looks like an npm package dir.
-        let install;
-        if (resolveCliPackageDir()) {
-            install = classifyCliInstall(process.env, process.argv, await resolveNpmGlobalRoot());
-        }
-        else {
-            install = classifyCliInstall(process.env, process.argv, null);
-        }
-        // Preserve a pending auto-update marker across refreshes so the
-        // once-per-window gate survives the cache being rewritten.
-        const prior = readCache();
-        writeCache({
-            lastCheckAt: Date.now(),
-            latest: typeof body.latest === 'string' ? body.latest : null,
-            npmPackage: typeof body.npmPackage === 'string' ? body.npmPackage : null,
-            baseURL: normalizeBaseUrl(baseURL),
-            install,
-            autoUpdate: prior?.autoUpdate,
-        });
+        directory = runtime().runtimeDir(packageRoot(argv));
     }
     catch {
-        // Offline / timeout / bad payload — leave the old cache, retry later.
+        directory = path.join(os.homedir(), '.skrr', 'cli-update-runtime');
     }
+    let autoUpdateReason = null;
+    if (install.kind !== 'npm-global')
+        autoUpdateReason = `The ${install.kind} installation is owned by its installer.`;
+    else if (!install.writable)
+        autoUpdateReason = 'The npm global prefix is read-only.';
+    else if (process.platform === 'win32')
+        autoUpdateReason =
+            'Use npm directly on Windows; managed replacement requires POSIX process-group coordination.';
+    else if (!isPrivateCliPrefix(packageRoot(argv)))
+        autoUpdateReason = 'Shared or external npm prefixes require the owning package manager.';
+    else if (env.SKRR_CLI_UPDATE_SESSION_UNAVAILABLE === '1')
+        autoUpdateReason = 'A safe CLI session lease could not be recorded.';
+    else if (isAutoUpdateSuppressed(env))
+        autoUpdateReason = 'Automatic CLI updates are disabled by environment policy.';
+    return {
+        component: 'cli',
+        runningVersion: opts.currentVersion,
+        installedVersion,
+        offeredVersion,
+        owner: install.kind,
+        state,
+        autoUpdateAllowed: autoUpdateReason === null,
+        autoUpdateReason,
+        command: cliUpdateCommand(install.kind),
+        lastCheckAt: matchingCache?.lastCheckAt ?? null,
+        lastAttempt,
+        logPath: path.join(directory, 'update.log'),
+        message: lastAttempt?.message,
+    };
 }
-// ---------------------------------------------------------------------------
-// Deferred self-update
-// ---------------------------------------------------------------------------
-let autoUpdateScheduled = false;
-/**
- * Schedule `npm install -g <pkg>@<version>` to run AFTER this process exits.
- *
- * Why deferred: oclif lazily loads command modules from disk, so swapping the
- * package while a command runs could hand it a mid-replace `dist/`. The child
- * is detached + stdio-ignored so it outlives this process and holds no pipes.
- * `spawn` inside an 'exit' handler works because the fork itself is
- * synchronous; only its events would need the (already drained) loop.
- *
- * The version comes from our own release feed's `latest`, validated to a
- * semver-ish token so the win32 shell path can't smuggle syntax.
- */
-function schedulePostExitSelfUpdate(pkg, version) {
-    if (autoUpdateScheduled)
-        return;
-    // Strict npm-name + semver-ish token validation — the win32 path spawns
-    // through a shell, so nothing with shell syntax may reach the spec.
-    const validPkg = /^@[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._-]*$/i.test(pkg) ||
-        /^[a-z0-9][a-z0-9._-]*$/i.test(pkg);
-    if (!validPkg || !/^[A-Za-z0-9._-]+$/.test(version))
-        return;
-    autoUpdateScheduled = true;
-    process.once('exit', () => {
+/** Bounded discovery, also usable without a daemon, account, or TTY. */
+async function checkCliUpdate(opts) {
+    const env = opts.env ?? process.env;
+    const argv = opts.argv ?? process.argv;
+    const cache = readCache(env);
+    const stale = !cache ||
+        cache.baseURL !== normalizeBaseUrl(opts.baseURL) ||
+        Date.now() - cache.lastCheckAt >= CHECK_TTL_MS;
+    let checkFailed = false;
+    if ((opts.force || stale) && (opts.force || !isTruthyEnv(env.OVERSKY_SKIP_UPDATE_CHECK))) {
         try {
-            const npmBin = process.platform === 'win32' ? 'npm.cmd' : 'npm';
-            const child = (0, node_child_process_1.spawn)(npmBin, ['install', '-g', `${pkg}@${version}`], {
-                detached: true,
-                stdio: 'ignore',
-                shell: process.platform === 'win32',
-            });
-            child.unref();
+            // Independent probes share the same 1.5-second bound rather than adding
+            // an npm probe after the network timeout on every first invocation.
+            const [response, npmRoot] = await Promise.all([
+                fetch(`${opts.baseURL.replace(/\/+$/, '')}/api/config/cli-version`, {
+                    signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+                    headers: { accept: 'application/json' },
+                }),
+                resolveCliPackageDir(argv) ? resolveNpmGlobalRoot(env) : Promise.resolve(null),
+            ]);
+            if (!response.ok)
+                throw new Error(`Version service returned HTTP ${response.status}`);
+            const body = (await response.json());
+            if (typeof body.latest !== 'string' ||
+                (0, auth_core_1.compareReleaseVersions)(body.latest, body.latest) === null)
+                throw new Error('Version service returned an invalid version');
+            writeCache({
+                lastCheckAt: Date.now(),
+                latest: body.latest,
+                npmPackage: CLI_PACKAGE,
+                baseURL: normalizeBaseUrl(opts.baseURL),
+                install: classifyCliInstall(env, argv, npmRoot),
+                packageRoot: packageRoot(argv),
+                npmGlobalRoot: npmRoot,
+                autoUpdate: cache?.autoUpdate,
+            }, env);
+        }
+        catch {
+            checkFailed = true;
+        }
+    }
+    const status = readCliUpdateStatus(opts);
+    if (checkFailed)
+        return {
+            ...status,
+            state: 'check-failed',
+            message: 'Could not check for a newer CLI version. Any offered version is from the last successful check; retry `skrr update --check`.',
+        };
+    return status;
+}
+function npmExecutable(env) {
+    const name = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+    for (const directory of (env.PATH ?? '').split(path.delimiter)) {
+        if (!directory || !path.isAbsolute(directory))
+            continue;
+        try {
+            const candidate = path.join(directory, name);
+            fs.accessSync(candidate, fs.constants.X_OK);
+            return fs.realpathSync(candidate);
         }
         catch {
-            /* a failed self-update just means the nudge returns next run */
+            /* next PATH entry */
         }
+    }
+    return null;
+}
+function updaterEnvironment(env) {
+    // The public npm package update does not require application credentials.
+    return Object.fromEntries(Object.entries(env).filter(([key]) => !/(?:TOKEN|SECRET|PASSWORD|CREDENTIAL|API_KEY|PRIVATE_KEY|AUTH_FD|AUTH_SOCK)/i.test(key) &&
+        !/^(?:SKRR_|OVERSKY_|OPENAI_|ANTHROPIC_|CODEX_|CLAUDE_|NODE_OPTIONS$)/i.test(key)));
+}
+function startWorker(directory, env) {
+    const sourceDir = path.resolve(__dirname, '..', '..', 'bin');
+    const workerBytes = fs.readFileSync(path.join(sourceDir, 'update-worker.cjs'));
+    const helperBytes = fs.readFileSync(path.join(sourceDir, 'update-session.cjs'));
+    const runnerBytes = fs.readFileSync(path.join(sourceDir, 'update-npm-runner.cjs'));
+    const digest = (0, node_crypto_1.createHash)('sha256')
+        .update(workerBytes)
+        .update(helperBytes)
+        .update(runnerBytes)
+        .digest('hex')
+        .slice(0, 24);
+    const immutableDir = path.join(directory, 'workers', digest);
+    fs.mkdirSync(immutableDir, { recursive: true, mode: 0o700 });
+    for (const [file, bytes] of [
+        ['update-worker.cjs', workerBytes],
+        ['update-session.cjs', helperBytes],
+        ['update-npm-runner.cjs', runnerBytes],
+    ]) {
+        const destination = path.join(immutableDir, file);
+        if (!fs.existsSync(destination))
+            fs.writeFileSync(destination, bytes, { mode: 0o600, flag: 'wx' });
+    }
+    const child = (0, node_child_process_1.spawn)(process.execPath, [path.join(immutableDir, 'update-worker.cjs'), directory], {
+        detached: true,
+        stdio: 'ignore',
+        env: updaterEnvironment(env),
+    });
+    child.once('error', () => {
+        /* persisted queue remains retryable */
     });
+    child.unref();
 }
-/**
- * Entry point, called once per command from `BaseCommand.init()`.
- *
- * Synchronous by design: it decides from the cache (no network on the hot
- * path) and only kicks off a background refresh when the cache is stale,
- * missing, or from a different server. Returns immediately.
- */
-function maybeWarnOutdatedCli(opts) {
+/** Queue an exact version through the owning global npm prefix. The current
+ * invocation stays leased, so replacement starts after it and peers exit. */
+async function performCliUpdate(opts) {
+    const env = opts.env ?? process.env;
+    const argv = opts.argv ?? process.argv;
+    const status = await checkCliUpdate({ ...opts, force: opts.force ?? true });
+    if (status.state === 'check-failed')
+        return status;
+    const checkedCache = readCache(env);
+    const install = classifyCliInstall(env, argv, checkedCache?.packageRoot === packageRoot(argv) ? (checkedCache.npmGlobalRoot ?? null) : null);
+    if (install.kind !== 'npm-global' ||
+        install.writable !== true ||
+        !isPrivateCliPrefix(packageRoot(argv)) ||
+        env.SKRR_CLI_UPDATE_SESSION_UNAVAILABLE === '1') {
+        return {
+            ...status,
+            message: `This CLI is owned by ${install.kind}${install.kind === 'npm-global' ? ' in a shared or external prefix' : ''}. ${cliUpdateCommand(install.kind)}.`,
+        };
+    }
+    const recoverableAttempt = status.lastAttempt && ['queued', 'running'].includes(status.lastAttempt.status);
+    if (!status.offeredVersion ||
+        !status.installedVersion ||
+        (!isOlderVersion(status.installedVersion, status.offeredVersion) && !recoverableAttempt))
+        return status;
+    const npmPath = npmExecutable(env);
+    if (!npmPath)
+        return {
+            ...status,
+            state: 'failed',
+            message: 'npm is unavailable; use the package manager that installed this CLI.',
+        };
+    const api = runtime();
+    if (env.SKRR_CLI_UPDATE_SESSION_REGISTERED !== String(process.pid))
+        api.registerSession(packageRoot(argv));
+    const directory = api.runtimeDir(packageRoot(argv));
+    const release = api.acquireLock(path.join(directory, 'request.lock'), 1000);
     try {
-        if (isNudgeSuppressed())
+        const old = attemptFor(argv);
+        if (!old || !['queued', 'running'].includes(old.status)) {
+            api.writeJson(path.join(directory, 'result.json'), {
+                status: 'queued',
+                version: status.offeredVersion,
+                attemptedAt: Date.now(),
+                packageRoot: packageRoot(argv),
+                npmPath,
+                coordinationVersion: api.COORDINATION_VERSION,
+                message: 'Waiting for active CLI sessions to exit; the next invocation uses the new version.',
+            });
+        }
+        startWorker(directory, env);
+    }
+    finally {
+        release();
+    }
+    return readCliUpdateStatus(opts);
+}
+/** One startup advisory across oclif command families. Awaiting bounded
+ * discovery makes the first invocation useful rather than losing its fetch
+ * when a short command exits. No update/check errors can break a command. */
+async function maybeWarnOutdatedCli(opts) {
+    try {
+        const env = opts.env ?? process.env;
+        if (!process.stderr.isTTY || isNudgeSuppressed(env))
             return;
-        // Scripts, pipes, and CI never get the advisory — matches npm/oclif
-        // convention and keeps `sky ... | jq` and captured stderr clean.
-        if (!process.stderr.isTTY)
+        const status = await checkCliUpdate(opts);
+        if (status.state === 'check-failed')
             return;
-        const normalized = normalizeBaseUrl(opts.baseURL);
-        const cache = readCache();
-        // Decide from whatever we last saw. A STALE cache is still a valid
-        // signal — CLI versions only move forward — so we act on it and refresh
-        // in the background for next time. We only trust a cache that was fetched
-        // against the same server the CLI is currently pointed at.
-        if (cache && cache.baseURL === normalized) {
-            const action = decideCliUpdateAction({
-                currentVersion: opts.currentVersion,
-                cache,
-                env: process.env,
-                isTTY: true,
-            });
-            if (action?.type === 'auto-update') {
-                // Record BEFORE scheduling so a same-second second invocation sees the
-                // attempt and doesn't double-spawn.
-                markAutoUpdateAttempt(action.version);
-                schedulePostExitSelfUpdate(action.pkg, action.version);
-            }
+        const cache = readCache(env);
+        if (!cache || cache.baseURL !== normalizeBaseUrl(opts.baseURL))
+            return;
+        const action = decideCliUpdateAction({
+            currentVersion: opts.currentVersion,
+            cache: {
+                ...cache,
+                install: { kind: status.owner, writable: status.autoUpdateAllowed },
+                autoUpdate: status.lastAttempt
+                    ? {
+                        attemptedAt: status.lastAttempt.attemptedAt,
+                        version: status.lastAttempt.version,
+                        status: status.lastAttempt.status,
+                    }
+                    : cache.autoUpdate,
+            },
+            env,
+            isTTY: true,
+        });
+        if (action?.type === 'auto-update') {
+            const queued = await performCliUpdate({ ...opts, force: false });
+            if (queued.state === 'pending')
+                process.stderr.write(`[skrr] CLI update to ${queued.lastAttempt?.version ?? action.version} queued in the background until active CLI sessions exit. Disable with OVERSKY_CLI_AUTO_UPDATE=0.\n`);
+            else if (queued.message)
+                process.stderr.write(`[skrr] ${queued.message}\n`);
+        }
+        else {
+            // Resume a queue whose worker exhausted its bounded wait, without
+            // classifying queued/running work as a failed npm install.
+            if (status.lastAttempt &&
+                ['queued', 'running'].includes(status.lastAttempt.status) &&
+                status.autoUpdateAllowed)
+                await performCliUpdate({ ...opts, force: false });
             if (action)
                 process.stderr.write(action.line);
         }
-        const stale = !cache || cache.baseURL !== normalized || Date.now() - cache.lastCheckAt > CHECK_TTL_MS;
-        if (stale) {
-            // Fire-and-forget. Not awaited, so it adds no latency; if the command
-            // exits before it resolves the refresh is simply dropped and retried
-            // on the next invocation.
-            void refreshCache(opts.baseURL);
-        }
     }
     catch {
-        // A version advisory must never break a command.
+        /* version discovery must never prevent the user's command */
     }
 }
+function shouldCheckCliUpdateAtStartup(argv, isTTY, env = process.env) {
+    if (!isTTY || isNudgeSuppressed(env) || isTruthyEnv(env.CI))
+        return false;
+    if (argv.some((arg) => /^(?:--json(?:=|$)|--help$|-h$|--version$|-v$|--headless$|--print$|-p$|--non-interactive$|--no-interactive$)/.test(arg)))
+        return false;
+    const command = argv
+        .filter((arg) => !arg.startsWith('-'))
+        .slice(0, 2)
+        .join(':');
+    return ![
+        'update',
+        'code:run',
+        'code:acp',
+        'code:update',
+        'code:install',
+        'daemon:update',
+        'daemons:update',
+    ].includes(command);
+}