@skrr-ai/cli 0.1.94 → 0.1.95

package/dist/lib/platform-update.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UPDATE_COMPONENTS = void 0;
+exports.normalizeComponentUpdateStatus = normalizeComponentUpdateStatus;
+exports.runPlatformUpdate = runPlatformUpdate;
+exports.describeComponentUpdate = describeComponentUpdate;
+/** One local update surface; each installation owner still applies its own bytes. */
+exports.UPDATE_COMPONENTS = ['cli', 'code', 'daemon'];
+const optionalString = (value) => typeof value === 'string' && value.length > 0 ? value : null;
+function normalizeComponentUpdateStatus(component, value) {
+    const raw = value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : {};
+    const command = optionalString(raw.command);
+    const commands = Array.isArray(raw.commands)
+        ? raw.commands.filter((item) => typeof item === 'string')
+        : command
+            ? [command]
+            : [];
+    return {
+        component,
+        state: optionalString(raw.state) ?? 'unknown',
+        runningVersion: optionalString(raw.runningVersion),
+        installedVersion: optionalString(raw.installedVersion) ?? optionalString(raw.currentVersion),
+        offeredVersion: optionalString(raw.offeredVersion) ?? optionalString(raw.latestVersion),
+        owner: optionalString(raw.owner) ?? optionalString(raw.installMethod) ?? 'unknown',
+        commands,
+        autoUpdateEnabled: typeof raw.autoUpdateEnabled === 'boolean'
+            ? raw.autoUpdateEnabled
+            : typeof raw.autoUpdateAllowed === 'boolean'
+                ? raw.autoUpdateAllowed
+                : null,
+        lastAttempt: raw.lastAttempt ?? raw.transaction ?? null,
+        detail: optionalString(raw.detail) ?? optionalString(raw.message),
+        status: raw,
+    };
+}
+function failedStatus(component, error) {
+    return normalizeComponentUpdateStatus(component, {
+        state: 'failed',
+        message: error instanceof Error ? error.message : String(error),
+    });
+}
+async function runPlatformUpdate(options, dependencies) {
+    const components = options.component && options.component !== 'all' ? [options.component] : [...exports.UPDATE_COMPONENTS];
+    const run = async (component) => {
+        try {
+            return normalizeComponentUpdateStatus(component, await dependencies[component](options.mode, options));
+        }
+        catch (error) {
+            return failedStatus(component, error);
+        }
+    };
+    // Reads are independent. Writes remain sequential so their results and service
+    // restarts are observable, and a failed component never hides the others.
+    const statuses = [];
+    if (options.mode === 'apply') {
+        for (const component of components)
+            statuses.push(await run(component));
+    }
+    else {
+        statuses.push(...(await Promise.all(components.map(run))));
+    }
+    const failureStates = new Set(['failed', 'check-failed', 'update-failed', 'rollback-failed']);
+    return {
+        schemaVersion: 1,
+        mode: options.mode,
+        components: statuses,
+        ok: statuses.every((item) => !failureStates.has(item.state)),
+    };
+}
+function describeComponentUpdate(status) {
+    const versions = [
+        `running ${status.runningVersion ?? '—'}`,
+        `installed ${status.installedVersion ?? 'unknown'}`,
+        `offered ${status.offeredVersion ?? 'unknown'}`,
+    ].join(' · ');
+    return [
+        `${status.component}: ${status.state} (${status.owner})`,
+        `  ${versions}`,
+        ...(status.detail ? [`  ${status.detail}`] : []),
+        ...status.commands.map((command) => `  ${command}`),
+    ].join('\n');
+}

package/dist/lib/profile-machine-identity-guard.d.ts

@@ -0,0 +1,2 @@
+/** An old profile may still share the default machine row and its device pin. */
+export declare function legacyProfileSharesDefaultMachine(): boolean;

package/dist/lib/profile-machine-identity-guard.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.legacyProfileSharesDefaultMachine = legacyProfileSharesDefaultMachine;
+const machine_uuid_1 = require("@skrr-ai/auth-core/machine-uuid");
+const keychain_1 = require("./keychain");
+/** An old profile may still share the default machine row and its device pin. */
+function legacyProfileSharesDefaultMachine() {
+    const profile = (0, keychain_1.getActiveProfile)();
+    return (!!profile &&
+        profile !== 'default' &&
+        !(0, machine_uuid_1.hostedRuntimeIdOverride)('OVERSKY_MACHINE_UUID') &&
+        (0, machine_uuid_1.getMachineUuid)() === (0, machine_uuid_1.getHardwareMachineUuid)());
+}

package/dist/lib/prompt.d.ts

@@ -7,6 +7,7 @@
  */
 export declare function prompt(question: string, opts?: {
     hidden?: boolean;
+    output?: NodeJS.WritableStream;
 }): Promise<string>;
 /**
  * Ask a yes/no question and return the user's answer.

package/dist/lib/prompt.js

@@ -52,10 +52,11 @@ const readline = __importStar(require("node:readline"));
  */
 function prompt(question, opts = {}) {
     const hidden = opts.hidden ?? false;
+    const output = opts.output ?? process.stdout;
     return new Promise((resolve) => {
         const rl = readline.createInterface({
             input: process.stdin,
-            output: process.stdout,
+            output,
         });
         if (hidden) {
             const rlAny = rl;
@@ -65,12 +66,12 @@ function prompt(question, opts = {}) {
                     rlAny.output.write(char);
                 }
             };
-            process.stdout.write(question);
+            output.write(question);
         }
         rl.question(hidden ? '' : question, (answer) => {
             rl.close();
             if (hidden)
-                process.stdout.write('\n');
+                output.write('\n');
             resolve(answer.trim());
         });
     });

package/dist/lib/task-batch.d.ts

@@ -4,6 +4,7 @@ export type ApiFailure = {
     status?: number;
     code?: string;
     retryable: boolean;
+    requestId?: string;
 };
 /** Normalize a thrown API error (or a per-item batch error) into one shape. */
 export declare function describeApiFailure(err: unknown): ApiFailure;
@@ -39,8 +40,16 @@ export type BatchCreateFailure = {
     key: string;
     /** Not attempted because its parent was not created (or an earlier chunk failed). */
     skipped: boolean;
+    /** Unknown is submitted, not equivalent to not_attempted. */
+    outcome?: 'unknown' | 'not_attempted' | 'failed';
+    externalKey?: string;
     error: ApiFailure;
 };
+/** A lost response is not a lost write. Only READ here; never retry a write. */
+export declare function reconcileSubmittedNodes(nodes: BatchCreateNode[], mapping: Record<string, string>, error: ApiFailure, deadlineAt?: number): Promise<{
+    rows: BatchCreatedRow[];
+    failures: BatchCreateFailure[];
+}>;
 export type BatchCreateOutcome = {
     supported: false;
 } | {

package/dist/lib/task-batch.js

@@ -4,6 +4,7 @@ exports.describeApiFailure = describeApiFailure;
 exports.isBatchRouteMissing = isBatchRouteMissing;
 exports.chunkItems = chunkItems;
 exports.batchIdempotencyKey = batchIdempotencyKey;
+exports.reconcileSubmittedNodes = reconcileSubmittedNodes;
 exports.createNodesViaBatch = createNodesViaBatch;
 exports.patchTasksViaBatch = patchTasksViaBatch;
 /**
@@ -17,9 +18,10 @@ exports.patchTasksViaBatch = patchTasksViaBatch;
  */
 const node_crypto_1 = require("node:crypto");
 const data_provider_1 = require("@skrr-ai/data-provider");
+const tasks_1 = require("./tasks");
 /** Normalize a thrown API error (or a per-item batch error) into one shape. */
 function describeApiFailure(err) {
-    const e = err;
+    const e = (err ?? {});
     let code = e.code;
     let message = e.message ?? String(err);
     if (e.body) {
@@ -37,7 +39,8 @@ function describeApiFailure(err) {
         message,
         ...(status ? { status } : {}),
         ...(code ? { code } : {}),
-        retryable: status === 408 || status === 425 || status === 429 || (status ?? 0) >= 500,
+        ...(e.requestId ? { requestId: e.requestId } : {}),
+        retryable: !status || status === 408 || status === 425 || status === 429 || (status ?? 0) >= 500,
     };
 }
 /**
@@ -66,6 +69,52 @@ function batchIdempotencyKey(kind, items) {
     const digest = (0, node_crypto_1.createHash)('sha256').update((0, data_provider_1.stableJson)(items)).digest('hex').slice(0, 40);
     return `cli-${kind}-batch:${digest}`;
 }
+/** A lost response is not a lost write. Only READ here; never retry a write. */
+async function reconcileSubmittedNodes(nodes, mapping, error, deadlineAt = Date.now() + 5000) {
+    const rows = [];
+    const failures = [];
+    // Limit simultaneous reads: a 100-item batch must not become 100 connections.
+    for (const group of chunkItems(nodes, 4)) {
+        await Promise.all(group.map(async (node) => {
+            const externalKey = typeof node.payload.externalKey === 'string' ? node.payload.externalKey : undefined;
+            if (externalKey && Date.now() < deadlineAt) {
+                let timer;
+                try {
+                    const read = (0, tasks_1.findTaskByExternalKey)({
+                        externalKey, spaceId: node.payload.spaceId, goalId: node.payload.goalId,
+                    });
+                    const existing = await Promise.race([read, new Promise((resolve) => {
+                            timer = setTimeout(() => resolve(null), Math.max(1, deadlineAt - Date.now()));
+                        })]);
+                    if (existing?.task?.externalKey === externalKey && (0, tasks_1.taskId)(existing.task)) {
+                        const id = (0, tasks_1.taskId)(existing.task);
+                        mapping[node.key] = id;
+                        rows.push({ key: node.key, id, status: 'exists', externalKey,
+                            ...(typeof existing.task.identifier === 'string' ? { identifier: existing.task.identifier } : {}),
+                        });
+                        return;
+                    }
+                }
+                catch { /* A failed read does not prove the write failed. */ }
+                finally {
+                    clearTimeout(timer);
+                }
+            }
+            failures.push({ key: node.key, skipped: false, outcome: 'unknown',
+                ...(externalKey ? { externalKey } : {}),
+                error: { ...error, code: 'BATCH_OUTCOME_UNKNOWN', retryable: Boolean(externalKey),
+                    message: `The result for "${node.key}" is unknown. ` +
+                        (externalKey ? `No committed task was confirmed by external key "${externalKey}"; the original write may still finish. Re-run the same keyed tree to reconcile and resume.` :
+                            'This node has no stable external key. Inspect the Space before another write; do not re-run --fresh blindly.'),
+                },
+            });
+        }));
+    }
+    const position = new Map(nodes.map((n, i) => [n.key, i]));
+    rows.sort((a, b) => position.get(a.key) - position.get(b.key));
+    failures.sort((a, b) => position.get(a.key) - position.get(b.key));
+    return { rows, failures };
+}
 /**
  * Create `nodes` (parents before children) in chunks. `mapping` holds key -> id
  * for nodes that already exist and is extended in place. Stops after the first
@@ -117,25 +166,45 @@ async function createNodesViaBatch(nodes, mapping) {
         catch (err) {
             if (chunkIndex === 0 && isBatchRouteMissing(err))
                 return { supported: false };
-            failures.push({ key: sent[0].key, skipped: false, error: describeApiFailure(err) });
-            for (const node of sent.slice(1)) {
-                failures.push({
-                    key: node.key,
-                    skipped: true,
-                    error: {
-                        message: `Not attempted: the batch request containing "${sent[0].key}" failed`,
-                        code: 'BATCH_NOT_ATTEMPTED',
-                        retryable: true,
-                    },
-                });
+            const error = describeApiFailure(err);
+            const uncertain = !error.status || error.status === 408 || error.status >= 500 || error.code === 'IDEMPOTENCY_IN_PROGRESS';
+            if (uncertain) {
+                const recovered = await reconcileSubmittedNodes(sent, mapping, error);
+                rows.push(...recovered.rows);
+                failures.push(...recovered.failures);
+                // Even a fully reconciled chunk stops here: no extra write follows a
+                // lost response during this run. Later chunks are explicitly unstarted.
+                const remaining = nodes.slice((chunkIndex + 1) * (data_provider_1.TASK_BATCH_MAX_ITEMS ?? 100));
+                for (const node of remaining)
+                    failures.push({ key: node.key, skipped: true,
+                        outcome: 'not_attempted', externalKey: node.payload.externalKey,
+                        error: { message: 'Not started after a batch transport failure; resume the same keyed tree.', code: 'BATCH_NOT_ATTEMPTED', retryable: true }, });
+            }
+            else {
+                for (const node of sent)
+                    failures.push({ key: node.key, skipped: false, outcome: 'failed', error });
+                for (const node of nodes.slice((chunkIndex + 1) * (data_provider_1.TASK_BATCH_MAX_ITEMS ?? 100))) {
+                    failures.push({ key: node.key, skipped: true, outcome: 'not_attempted',
+                        error: { message: 'Not started after a batch refusal.', code: 'BATCH_NOT_ATTEMPTED', retryable: true } });
+                }
             }
             break;
         }
         let failed = false;
-        for (const [i, result] of response.results.entries()) {
-            const node = sent[i];
-            if (!node)
+        const reconciliationDeadlineAt = Date.now() + 5000;
+        for (const [i, node] of sent.entries()) {
+            const result = response.results?.find((r) => r.index === i);
+            if (!result || result.status === 'pending' || (result.ok && !result.id) || (result.error?.status ?? 0) >= 500) {
+                const recovered = await reconcileSubmittedNodes([{ ...node, payload: {
+                            ...node.payload, ...(result?.externalKey ? { externalKey: result.externalKey } : {}),
+                        } }], mapping, {
+                    message: 'Batch did not confirm this submitted write', code: 'BATCH_OUTCOME_UNKNOWN', retryable: true,
+                }, reconciliationDeadlineAt);
+                rows.push(...recovered.rows);
+                failures.push(...recovered.failures);
+                failed = true;
                 continue;
+            }
             if (result.ok && result.id) {
                 mapping[node.key] = result.id;
                 rows.push({
@@ -151,6 +220,8 @@ async function createNodesViaBatch(nodes, mapping) {
                 failures.push({
                     key: node.key,
                     skipped: result.status === 'skipped',
+                    outcome: result.status === 'skipped' ? 'not_attempted' : 'failed',
+                    ...(result.externalKey ? { externalKey: result.externalKey } : {}),
                     error: result.error
                         ? {
                             message: result.error.message,
@@ -162,8 +233,14 @@ async function createNodesViaBatch(nodes, mapping) {
                 });
             }
         }
-        if (failed)
+        if (failed) {
+            for (const node of nodes.slice((chunkIndex + 1) * (data_provider_1.TASK_BATCH_MAX_ITEMS ?? 100))) {
+                failures.push({ key: node.key, skipped: true, outcome: 'not_attempted',
+                    externalKey: node.payload.externalKey,
+                    error: { message: 'Not started after an incomplete batch; resume the same keyed tree.', code: 'BATCH_NOT_ATTEMPTED', retryable: true }, });
+            }
             break;
+        }
     }
     return { supported: true, rows, failures };
 }

package/dist/lib/task-instruction-offer.d.ts

@@ -1,5 +1,2 @@
-/**
- * Best-effort contextual activation after a human successfully uses a task
- * command. It must never change the task command's exit status.
- */
+/** Task creation and login share the same machine-bound, provider-scoped offer. */
 export declare function maybeOfferTaskManagementInstructions(log: (message: string) => void): Promise<void>;

package/dist/lib/task-instruction-offer.js

@@ -1,134 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.maybeOfferTaskManagementInstructions = maybeOfferTaskManagementInstructions;
-const auth_core_1 = require("@skrr-ai/auth-core");
-const data_provider_1 = require("@skrr-ai/data-provider");
-const config_1 = require("./config");
-const daemon_target_1 = require("./daemon-target");
-const prompt_1 = require("./prompt");
-const TEMPLATE_KEY = 'oversky-task-management';
-function capabilitiesOf(daemon) {
-    if (Array.isArray(daemon.capabilities))
-        return daemon.capabilities.map(String);
-    if (typeof daemon.capabilities !== 'string')
-        return [];
-    try {
-        const parsed = JSON.parse(daemon.capabilities);
-        if (Array.isArray(parsed))
-            return parsed.map(String);
-    }
-    catch {
-        // Older daemon rows used comma-separated capabilities.
-    }
-    return daemon.capabilities
-        .split(',')
-        .map((capability) => capability.trim())
-        .filter(Boolean);
-}
-function detectedProviders(daemon) {
-    const capabilities = capabilitiesOf(daemon);
-    const providers = [];
-    if (capabilities.includes('claude_session'))
-        providers.push('claude');
-    if (capabilities.includes('codex_session'))
-        providers.push('codex');
-    // A daemon advertises the first-party harness under whichever spelling its
-    // version speaks; any of them means the harness is there, and the offer names
-    // it canonically, which is what the server stores.
-    if (capabilities.some(auth_core_1.isFirstPartyHarnessCapability))
-        providers.push(auth_core_1.FIRST_PARTY_HARNESS_PROVIDER);
-    return providers;
-}
-function providerLabel(provider) {
-    if (provider === 'claude')
-        return 'Claude Code';
-    if (provider === 'codex')
-        return 'Codex';
-    return auth_core_1.FIRST_PARTY_HARNESS.displayName;
-}
-function providerPath(provider) {
-    if (provider === 'claude')
-        return '~/.claude/CLAUDE.md';
-    if (provider === 'codex')
-        return '~/.codex/AGENTS.md';
-    // The engine home follows the ENGINE's namespace, not the provider slug — the
-    // engine reads its managed `AGENTS.md` from there (contract §5).
-    return `~/.skrr/${(0, auth_core_1.firstPartyHarnessHomeDirname)()}/AGENTS.md`;
-}
-function shouldSkipOffer() {
-    return Boolean(!process.stdin.isTTY ||
-        !process.stdout.isTTY ||
-        process.env.CI ||
-        process.env.OVERSKY_HEADLESS ||
-        process.env.OVERSKY_SESSION_TASK_ID ||
-        process.env.OVERSKY_SESSION_AGENT_ID ||
-        process.env.OVERSKY_DISABLE_INSTRUCTION_OFFER === '1');
-}
-/**
- * Best-effort contextual activation after a human successfully uses a task
- * command. It must never change the task command's exit status.
- */
+const managed_instruction_setup_1 = require("./managed-instruction-setup");
+/** Task creation and login share the same machine-bound, provider-scoped offer. */
 async function maybeOfferTaskManagementInstructions(log) {
-    if (shouldSkipOffer())
-        return;
-    try {
-        // The offer speaks of "this machine", so on a Dedicated Runtime guest only the
-        // guest's own daemon may be the candidate — never the first eligible row of the
-        // account, which is the owner's laptop (OSK-8759). A guest whose daemon has
-        // published no id gets no candidate. Off a guest nothing is read here and the
-        // search below is unchanged.
-        const local = (0, daemon_target_1.localMachine)({ baseURL: (0, config_1.loadConfig)().baseURL });
-        if (local.dedicatedRuntime && !local.daemonId)
-            return;
-        const [daemons, offerResponse] = await Promise.all([
-            data_provider_1.dataService.getDaemons(),
-            data_provider_1.dataService.getManagedInstructionOffer(TEMPLATE_KEY),
-        ]);
-        const candidate = daemons.active.find((daemon) => {
-            if (local.dedicatedRuntime && daemon.daemonId !== local.daemonId)
-                return false;
-            if (!detectedProviders(daemon).length)
-                return false;
-            return offerResponse.offers.find((offer) => offer.daemonId === daemon.daemonId)?.eligible;
-        });
-        if (!candidate)
-            return;
-        const providers = detectedProviders(candidate);
-        const labels = providers.map(providerLabel).join(' and ');
-        log('');
-        log(`Let ${labels} manage skrr tasks automatically?`);
-        log('skrr will add a removable managed block to the user-level agent files on this machine.');
-        log('Type v to review the exact instruction, y to install and keep it updated, or press Enter for not now.');
-        const answer = (await (0, prompt_1.prompt)('Install task-management instructions? [y/N/v] ')).toLowerCase();
-        let accepted = answer === 'y' || answer === 'yes';
-        if (answer === 'v' || answer === 'view') {
-            log('');
-            log('--- exact managed instruction ---');
-            log(offerResponse.preset.body);
-            log('--- end instruction ---');
-            log('');
-            log('Targets:');
-            for (const provider of providers) {
-                log(`- ${providerLabel(provider)}: ${providerPath(provider)}`);
-            }
-            accepted = await (0, prompt_1.confirm)('Install this instruction and keep it updated?', true);
-        }
-        if (!accepted) {
-            await data_provider_1.dataService.respondManagedInstructionOffer(TEMPLATE_KEY, {
-                daemonId: candidate.daemonId,
-                action: 'snooze',
-            });
-            log('Not now. skrr will not ask again for 14 days.');
-            return;
-        }
-        await data_provider_1.dataService.acceptManagedInstructionOffer(TEMPLATE_KEY, {
-            daemonId: candidate.daemonId,
-            providers,
-        });
-        log(`Installation queued for ${labels}; check Settings for confirmed file status.`);
-    }
-    catch {
-        // A discovery nudge must never turn a successful task operation into a
-        // failed command. Settings remains the durable recovery/control surface.
-    }
+    await (0, managed_instruction_setup_1.maybeOfferManagedInstructionSetup)({ log, trigger: 'task' });
 }

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

@@ -1,44 +1,66 @@
-export type CliInstallKind = 'npm-global' | 'npm-local' | 'dev' | 'bundled' | 'other';
-interface CheckCache {
-    /** Epoch ms of the last successful refresh. */
+export type CliInstallKind = 'npm-global' | 'npm-local' | 'dev' | 'bundled' | 'image' | 'homebrew' | 'other';
+export interface CliUpdateAttempt {
+    status: 'queued' | 'running' | 'succeeded' | 'failed';
+    version: string;
+    attemptedAt: number;
+    updatedAt?: number;
+    startedAt?: number;
+    finishedAt?: number;
+    installedVersion?: string;
+    message?: string;
+    packageRoot?: string;
+    npmPath?: string;
+    coordinationVersion?: number;
+    workerPid?: number;
+    interrupted?: boolean;
+}
+export interface CheckCache {
     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. */
+    packageRoot?: string;
+    npmGlobalRoot?: string | null;
     autoUpdate?: {
         attemptedAt: number;
         version: string;
+        status?: CliUpdateAttempt['status'];
+        message?: string;
     };
 }
-/** Trailing-slash- and case-insensitive normalization for baseURL compares. */
+export interface CliUpdateOptions {
+    currentVersion: string;
+    baseURL: string;
+    force?: boolean;
+    env?: NodeJS.ProcessEnv;
+    argv?: readonly string[];
+}
+export interface CliUpdateStatus {
+    component: 'cli';
+    runningVersion: string;
+    installedVersion: string | null;
+    offeredVersion: string | null;
+    owner: CliInstallKind;
+    state: 'up-to-date' | 'update-available' | 'pending' | 'restart-pending' | 'failed' | 'managed' | 'unknown' | 'check-failed';
+    autoUpdateAllowed: boolean;
+    autoUpdateReason: string | null;
+    command: string;
+    lastCheckAt: number | null;
+    lastAttempt: CliUpdateAttempt | null;
+    logPath: string;
+    message?: string;
+}
 export declare function normalizeBaseUrl(url: string): string;
-/**
- * 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.
- */
 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).
- * 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.
- */
 export declare function isOlderVersion(current: string, latest: string): boolean;
+/** Per-user leases cannot coordinate a global prefix shared with another OS
+ * user. Only private user-owned prefixes participate in managed replacement. */
+export declare function isPrivateCliPrefix(root: 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),
@@ -54,17 +76,12 @@ export declare function resolveCliPackageDir(argv?: readonly string[]): string |
  * 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): {
+export declare function classifyCliInstall(env: NodeJS.ProcessEnv, argv: readonly string[], npmGlobalRoot: string | null, probeWritable?: boolean): {
     kind: CliInstallKind;
     writable?: boolean;
 };
-/**
- * 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.
- */
-export declare function buildNudgeLine(currentVersion: string, latest: string | null, npmPackage: string | null, installKind?: CliInstallKind): string | null;
+export declare function cliUpdateCommand(owner: CliInstallKind): string;
+export declare function buildNudgeLine(currentVersion: string, latest: string | null, _npmPackage: string | null, installKind?: CliInstallKind): string | null;
 export type CliUpdateAction = {
     type: 'nudge';
     line: string;
@@ -74,15 +91,6 @@ export type CliUpdateAction = {
     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;
@@ -90,15 +98,15 @@ export declare function decideCliUpdateAction(args: {
     isTTY: boolean;
     now?: number;
 }): CliUpdateAction;
-/**
- * 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.
- */
-export declare function maybeWarnOutdatedCli(opts: {
-    currentVersion: string;
-    baseURL: string;
-}): void;
-export {};
+/** Cached, read-only status: no network, child process, lease, or mutation. */
+export declare function readCliUpdateStatus(opts: CliUpdateOptions): CliUpdateStatus;
+/** Bounded discovery, also usable without a daemon, account, or TTY. */
+export declare function checkCliUpdate(opts: CliUpdateOptions): Promise<CliUpdateStatus>;
+/** Queue an exact version through the owning global npm prefix. The current
+ * invocation stays leased, so replacement starts after it and peers exit. */
+export declare function performCliUpdate(opts: CliUpdateOptions): Promise<CliUpdateStatus>;
+/** 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. */
+export declare function maybeWarnOutdatedCli(opts: CliUpdateOptions): Promise<void>;
+export declare function shouldCheckCliUpdateAtStartup(argv: readonly string[], isTTY: boolean, env?: NodeJS.ProcessEnv): boolean;