@skrr-ai/cli 0.1.45 → 0.1.47

package/dist/lib/update-check.d.ts

@@ -1,11 +1,37 @@
+export type CliInstallKind = 'npm-global' | 'npm-local' | 'dev' | 'bundled' | 'other';
+interface CheckCache {
+    /** Epoch ms of the last successful refresh. */
+    lastCheckAt: number;
+    /** Latest advertised CLI version, or null if the API had none. */
+    latest: string | null;
+    /** npm package to update (advisory copy), or null. */
+    npmPackage: string | null;
+    /** baseURL the cache was fetched against — invalidates on server switch. */
+    baseURL: string;
+    /** Resolved install shape, classified during the last refresh. */
+    install?: {
+        kind: CliInstallKind;
+        writable?: boolean;
+    };
+    /** Recorded BEFORE a background self-update is scheduled. */
+    autoUpdate?: {
+        attemptedAt: number;
+        version: string;
+    };
+}
 /** Trailing-slash- and case-insensitive normalization for baseURL compares. */
 export declare function normalizeBaseUrl(url: string): string;
 /**
  * True when the advisory must stay silent regardless of version state:
- * explicit suppression, or a desktop-app-bundled CLI (which auto-updates
- * with the app and must not be told to `npm update -g`).
+ * 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.
  */
 export declare function isNudgeSuppressed(env?: NodeJS.ProcessEnv): boolean;
+/** 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. */
+export declare function isAutoUpdateSuppressed(env?: NodeJS.ProcessEnv): boolean;
 /**
  * True iff `current` is strictly older than `latest` by numeric release
  * core. Conservative: any unparseable input returns false (no nudge).
@@ -13,19 +39,66 @@ export declare function isNudgeSuppressed(env?: NodeJS.ProcessEnv): boolean;
  * we never nag someone testing a prerelease of the latest line.
  */
 export declare function isOlderVersion(current: string, latest: string): boolean;
+/**
+ * Resolve the package directory this process was launched from when it lives
+ * under `node_modules/@skrr-ai/cli` (any npm install — global or project-local),
+ * or null. Probes both the raw entry path and its realpath because the bin is
+ * usually a symlink into the package.
+ */
+export declare function resolveCliPackageDir(argv?: readonly string[]): string | null;
+/**
+ * Classify how this CLI was installed. `npmGlobalRoot` (from `npm root -g`)
+ * distinguishes a global install — which we may auto-update — from a
+ * project-local dependency, whose bytes belong to that project's package.json.
+ * `dev` is a checkout launched via its own `bin/run.js`: a `src/commands`
+ * dir beside `dist` exists only in a checkout — published packages ship
+ * `dist` and no `src`.
+ */
+export declare function classifyCliInstall(env: NodeJS.ProcessEnv, argv: readonly string[], npmGlobalRoot: string | null): {
+    kind: CliInstallKind;
+    writable?: boolean;
+};
 /**
  * Build the one-line stderr advisory, or null when no nudge is warranted.
- * Exported for direct unit testing without touching disk or the network.
+ * `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.
  */
-export declare function buildNudgeLine(currentVersion: string, latest: string | null, npmPackage: string | null): string | null;
+export declare function buildNudgeLine(currentVersion: string, latest: string | null, npmPackage: string | null, installKind?: CliInstallKind): string | null;
+export type CliUpdateAction = {
+    type: 'nudge';
+    line: string;
+} | {
+    type: 'auto-update';
+    version: string;
+    pkg: string;
+    line: string;
+} | null;
+/**
+ * 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.
+ */
+export declare function decideCliUpdateAction(args: {
+    currentVersion: string;
+    cache: CheckCache | null;
+    env: NodeJS.ProcessEnv;
+    isTTY: boolean;
+    now?: number;
+}): CliUpdateAction;
 /**
  * Entry point, called once per command from `BaseCommand.init()`.
  *
- * Synchronous by design: it decides the nudge 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.
+ * 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.
  */
 export declare function maybeWarnOutdatedCli(opts: {
     currentVersion: string;
     baseURL: string;
 }): void;
+export {};

package/dist/lib/update-check.js

@@ -35,39 +35,73 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.normalizeBaseUrl = normalizeBaseUrl;
 exports.isNudgeSuppressed = isNudgeSuppressed;
+exports.isAutoUpdateSuppressed = isAutoUpdateSuppressed;
 exports.isOlderVersion = isOlderVersion;
+exports.resolveCliPackageDir = resolveCliPackageDir;
+exports.classifyCliInstall = classifyCliInstall;
 exports.buildNudgeLine = buildNudgeLine;
+exports.decideCliUpdateAction = decideCliUpdateAction;
 exports.maybeWarnOutdatedCli = maybeWarnOutdatedCli;
+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_util_1 = require("node:util");
 /**
- * update-check.ts — non-blocking "a newer `skrr` is available" advisory.
+ * 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 self-update path,
- * so a user who installed it via npm has no signal that they are behind.
- * This module is the CLI-side analog of the daemon's server-driven
- * `daemon:update-available` advisory: on every command it decides — from a
- * ~4h on-disk cache, with ZERO added latency — whether to print a single
- * line to stderr, and refreshes that cache in the background.
+ * 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:
  *
- * Hard guarantees (a version advisory must never make the CLI worse):
+ *   - 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 / pipes never see it).
- *   - Never blocks the command: the nudge decision is synchronous off the
- *     cache; the network refresh is fire-and-forget and time-bounded.
+ *   - 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, or read-only home directory can't break a command.
+ *     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 it; `OVERSKY_CLI_BUNDLED=1` (set by the desktop app's `skrr`
- *     wrapper) suppresses it entirely — bundled installs auto-update with
- *     the app, so an "npm update -g" nudge would be actively wrong there.
+ *     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 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 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 execFileAsync = (0, node_util_1.promisify)(node_child_process_1.execFile);
 function cacheFilePath() {
     return path.join(os.homedir(), '.skrr', 'cli-update-check.json');
 }
@@ -80,15 +114,41 @@ function isTruthyEnv(value) {
         return false;
     return ['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());
+}
+/** 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;
+    try {
+        return fs.existsSync(DEDICATED_RUNTIME_ENV_FILE);
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * True when the advisory must stay silent regardless of version state:
- * explicit suppression, or a desktop-app-bundled CLI (which auto-updates
- * with the app and must not be told to `npm update -g`).
+ * 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) ||
-        env.OVERSKY_CLI_BUNDLED === '1');
+        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]`),
@@ -130,18 +190,202 @@ function isOlderVersion(current, latest) {
     }
     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
+ * under `node_modules/@skrr-ai/cli` (any npm install — global or project-local),
+ * or null. Probes both the raw entry path and its realpath because the bin is
+ * usually a symlink into the package.
+ */
+function resolveCliPackageDir(argv = process.argv) {
+    const entry = argv[1];
+    if (!entry)
+        return null;
+    const candidates = [entry];
+    try {
+        candidates.push(fs.realpathSync(entry));
+    }
+    catch {
+        /* entry may be virtual; the raw form is still probed */
+    }
+    for (const candidate of candidates) {
+        const match = candidate.match(CLI_PACKAGE_DIR_RE);
+        if (match)
+            return match[1];
+    }
+    return null;
+}
+function dirWritable(dir) {
+    try {
+        const st = fs.statSync(dir);
+        if (!st.isDirectory())
+            return false;
+        const probe = path.join(dir, `.skrr.write-probe.${process.pid}.${Date.now()}`);
+        fs.closeSync(fs.openSync(probe, 'w', 0o600));
+        fs.unlinkSync(probe);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Classify how this CLI was installed. `npmGlobalRoot` (from `npm root -g`)
+ * distinguishes a global install — which we may auto-update — from a
+ * project-local dependency, whose bytes belong to that project's package.json.
+ * `dev` is a checkout launched via its own `bin/run.js`: a `src/commands`
+ * 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)) {
+        return { kind: 'bundled' };
+    }
+    const packageDir = resolveCliPackageDir(argv);
+    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
+        // `dist` and no `src`). Those bytes belong to git, not npm.
+        const entry = argv[1];
+        if (entry) {
+            try {
+                const cliRoot = path.resolve(path.dirname(entry), '..');
+                if (fs.existsSync(path.join(cliRoot, 'src', 'commands'))) {
+                    return { kind: 'dev' };
+                }
+            }
+            catch {
+                /* fall through to other */
+            }
+        }
+        return { kind: 'other' };
+    }
+    const nodeModulesDir = path.dirname(path.dirname(packageDir)); // …/node_modules
+    if (npmGlobalRoot) {
+        let resolvedGlobal = npmGlobalRoot;
+        try {
+            resolvedGlobal = fs.realpathSync(npmGlobalRoot);
+        }
+        catch {
+            /* compare the raw form */
+        }
+        let resolvedNodeModules = nodeModulesDir;
+        try {
+            resolvedNodeModules = fs.realpathSync(nodeModulesDir);
+        }
+        catch {
+            /* compare the raw form */
+        }
+        if (resolvedNodeModules !== resolvedGlobal)
+            return { kind: 'npm-local' };
+    }
+    else if (!/[/\\](lib|npm)[/\\]node_modules$/.test(nodeModulesDir)) {
+        // `npm root -g` gave no answer, so prove the global shape from the path
+        // instead: npm's unix global root is always `<prefix>/lib/node_modules`
+        // (incl. nvm/volta) and on Windows `%APPDATA%\npm\node_modules`. A
+        // project-local `<project>/node_modules` never matches either — without
+        // proof we must not treat it as ours to auto-update.
+        return { kind: 'npm-local' };
+    }
+    return { kind: 'npm-global', writable: dirWritable(nodeModulesDir) };
+}
+/**
+ * Resolve `npm root -g` for install classification. Runs ONLY inside the
+ * background refresh — never on the command's hot path — and fails soft:
+ * no npm, a timeout, or an odd answer just leaves classification to the
+ * path shape alone.
+ */
+async function resolveNpmGlobalRoot() {
+    try {
+        const npmBin = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+        const { stdout } = await execFileAsync(npmBin, ['root', '-g'], {
+            timeout: NPM_ROOT_TIMEOUT_MS,
+            maxBuffer: 64 * 1024,
+            shell: process.platform === 'win32',
+        });
+        const root = stdout.trim();
+        return root && path.isAbsolute(root) ? root : null;
+    }
+    catch {
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Advisory copy — one line, per install shape
+// ---------------------------------------------------------------------------
 /**
  * Build the one-line stderr advisory, or null when no nudge is warranted.
- * Exported for direct unit testing without touching disk or the network.
+ * `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) {
+function buildNudgeLine(currentVersion, latest, npmPackage, installKind) {
     if (!latest || !isOlderVersion(currentVersion, latest))
         return null;
     const pkg = npmPackage || '@skrr-ai/cli';
-    return (`[skrr] Update available: ${currentVersion} → ${latest}. ` +
-        `Run \`npm update -g ${pkg}\` (or update the skrr app). ` +
-        `Silence with OVERSKY_NO_UPDATE_NUDGE=1.\n`);
+    const prefix = `[skrr] Update available: ${currentVersion} → ${latest}. `;
+    const suffix = ` Silence with OVERSKY_NO_UPDATE_NUDGE=1.\n`;
+    switch (installKind) {
+        case 'npm-local':
+            return `${prefix}Run \`npm update ${pkg}\` in the owning project.${suffix}`;
+        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':
+        case 'bundled':
+        default:
+            return `${prefix}Run \`npm update -g ${pkg}\` (or update the skrr app).${suffix}`;
+    }
 }
+/**
+ * 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 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))
+        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) {
+            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`,
+            };
+        }
+        // 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.
+        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`,
+        };
+    }
+    const line = buildNudgeLine(currentVersion, cache.latest, cache.npmPackage, install.kind);
+    return line ? { type: 'nudge', line } : null;
+}
+// ---------------------------------------------------------------------------
+// Cache I/O
+// ---------------------------------------------------------------------------
 function readCache() {
     try {
         const raw = fs.readFileSync(cacheFilePath(), 'utf8');
@@ -152,6 +396,19 @@ function readCache() {
                 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,
             };
         }
     }
@@ -172,6 +429,13 @@ function writeCache(cache) {
         // Best-effort — a read-only home just means we re-check next run.
     }
 }
+/** 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 } });
+}
 async function refreshCache(baseURL) {
     try {
         const url = `${baseURL.replace(/\/+$/, '')}/api/config/cli-version`;
@@ -182,23 +446,80 @@ async function refreshCache(baseURL) {
         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,
         });
     }
     catch {
         // Offline / timeout / bad payload — leave the old cache, retry later.
     }
 }
+// ---------------------------------------------------------------------------
+// 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', () => {
+        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();
+        }
+        catch {
+            /* a failed self-update just means the nudge returns next run */
+        }
+    });
+}
 /**
  * Entry point, called once per command from `BaseCommand.init()`.
  *
- * Synchronous by design: it decides the nudge 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.
+ * 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) {
     try {
@@ -211,13 +532,24 @@ function maybeWarnOutdatedCli(opts) {
         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 nudge off 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.
+        // 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 line = buildNudgeLine(opts.currentVersion, cache.latest, cache.npmPackage);
-            if (line)
-                process.stderr.write(line);
+            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);
+            }
+            if (action)
+                process.stderr.write(action.line);
         }
         const stale = !cache || cache.baseURL !== normalized || Date.now() - cache.lastCheckAt > CHECK_TTL_MS;
         if (stale) {

package/dist/node_modules/@skrr-ai/auth-core/dist/cjs/firstPartyHarness.d.ts

@@ -313,6 +313,21 @@ declare const ENGINE_ENV_SUFFIXES: Readonly<{
     allowUpstreamEgress: "ALLOW_UPSTREAM_EGRESS";
     compatOpencode: "COMPAT_OPENCODE";
     noCompatPrompts: "NO_COMPAT_PROMPTS";
+    /**
+     * Advisory input-token budget for a managed session, set by the daemon from
+     * the server-issued `requestEnvelope.maxInputTokens` so the engine's
+     * auto-compaction can trigger before the relay refuses the request. The
+     * engine must treat it as a hint: enforcement stays server-side.
+     */
+    maxInputTokens: "MAX_INPUT_TOKENS";
+    /**
+     * The session id the engine stamps into processes it spawns — the one
+     * variable on this table the engine WRITES rather than reads, so a child
+     * process (e.g. `skrr code handover --carry-session`) can name the session it
+     * is running inside without being told. Read with
+     * `readFirstPartyHarnessEngineEnv`: current namespace first, then legacy.
+     */
+    sessionId: "SESSION_ID";
 }>;
 export type FirstPartyHarnessEngineEnvKey = keyof typeof ENGINE_ENV_SUFFIXES;
 /**
@@ -350,7 +365,7 @@ export declare const FIRST_PARTY_HARNESS_ENGINE: Readonly<{
      * `readFirstPartyHarnessEngineEnv` to read one the way the engine does and
      * `firstPartyHarnessEngineEnvEntries` to set one every engine build honours.
      */
-    env: Readonly<Record<"appName" | "serverPassword" | "serverUsername" | "home" | "config" | "scriptName" | "allowUpstreamEgress" | "compatOpencode" | "noCompatPrompts", string>>;
+    env: Readonly<Record<"appName" | "serverPassword" | "serverUsername" | "home" | "config" | "scriptName" | "allowUpstreamEgress" | "compatOpencode" | "noCompatPrompts" | "maxInputTokens" | "sessionId", string>>;
 }>;
 /**
  * Every name the engine reads for one purpose, current namespace first — the

package/dist/node_modules/@skrr-ai/auth-core/dist/cjs/firstPartyHarness.js

@@ -450,6 +450,21 @@ const ENGINE_ENV_SUFFIXES = Object.freeze({
     allowUpstreamEgress: 'ALLOW_UPSTREAM_EGRESS',
     compatOpencode: 'COMPAT_OPENCODE',
     noCompatPrompts: 'NO_COMPAT_PROMPTS',
+    /**
+     * Advisory input-token budget for a managed session, set by the daemon from
+     * the server-issued `requestEnvelope.maxInputTokens` so the engine's
+     * auto-compaction can trigger before the relay refuses the request. The
+     * engine must treat it as a hint: enforcement stays server-side.
+     */
+    maxInputTokens: 'MAX_INPUT_TOKENS',
+    /**
+     * The session id the engine stamps into processes it spawns — the one
+     * variable on this table the engine WRITES rather than reads, so a child
+     * process (e.g. `skrr code handover --carry-session`) can name the session it
+     * is running inside without being told. Read with
+     * `readFirstPartyHarnessEngineEnv`: current namespace first, then legacy.
+     */
+    sessionId: 'SESSION_ID',
 });
 function engineEnvName(appName, key) {
     return `${appName.toUpperCase().replace(/-/g, '_')}_${ENGINE_ENV_SUFFIXES[key]}`;