@skrr-ai/cli 0.1.93 → 0.1.95

package/dist/lib/first-party-harness-startup-update.js

@@ -0,0 +1,166 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.configureCodeStartupChecks = configureCodeStartupChecks;
+exports.shouldCheckCodeAtStartup = shouldCheckCodeAtStartup;
+exports.ttyCodeUpdateAsker = ttyCodeUpdateAsker;
+exports.maybeOfferCodeUpdate = maybeOfferCodeUpdate;
+const node_fs_1 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
+const node_readline_1 = __importDefault(require("node:readline"));
+const auth_core_1 = require("@skrr-ai/auth-core");
+const first_party_harness_update_1 = require("./first-party-harness-update");
+function preferencesPath(env) {
+    return node_path_1.default.join((0, auth_core_1.resolveConfigRoot)(env), 'code-update-preferences.json');
+}
+function readPreferences(env) {
+    try {
+        const value = JSON.parse((0, node_fs_1.readFileSync)(preferencesPath(env), 'utf8'));
+        if (!value || typeof value !== 'object' || Array.isArray(value))
+            return {};
+        const input = value;
+        const skipped = input.skippedVersions;
+        return {
+            ...(typeof input.promptOnStartup === 'boolean'
+                ? { promptOnStartup: input.promptOnStartup }
+                : {}),
+            ...(skipped && typeof skipped === 'object' && !Array.isArray(skipped)
+                ? {
+                    skippedVersions: Object.fromEntries(Object.entries(skipped).filter((entry) => typeof entry[1] === 'string')),
+                }
+                : {}),
+        };
+    }
+    catch {
+        return {};
+    }
+}
+function saveChoice(env, result, choice) {
+    if (choice !== 'version' && choice !== 'disable')
+        return;
+    try {
+        const previous = readPreferences(env);
+        const next = choice === 'disable'
+            ? { ...previous, promptOnStartup: false }
+            : {
+                ...previous,
+                skippedVersions: {
+                    ...previous.skippedVersions,
+                    [result.channel]: result.offeredVersion,
+                },
+            };
+        const file = preferencesPath(env);
+        (0, node_fs_1.mkdirSync)(node_path_1.default.dirname(file), { recursive: true, mode: 0o700 });
+        const staging = `${file}.${process.pid}.tmp`;
+        (0, node_fs_1.writeFileSync)(staging, JSON.stringify(next), { mode: 0o600 });
+        (0, node_fs_1.renameSync)(staging, file);
+    }
+    catch {
+        /* Update preferences must never make a session unavailable. */
+    }
+}
+function configureCodeStartupChecks(enabled, env = process.env) {
+    const file = preferencesPath(env);
+    (0, node_fs_1.mkdirSync)(node_path_1.default.dirname(file), { recursive: true, mode: 0o700 });
+    const staging = `${file}.${process.pid}.tmp`;
+    (0, node_fs_1.writeFileSync)(staging, JSON.stringify({ ...readPreferences(env), promptOnStartup: enabled }), {
+        mode: 0o600,
+    });
+    (0, node_fs_1.renameSync)(staging, file);
+    return { enabled, preferencesPath: file };
+}
+const disabled = (value) => /^(0|false|off|no|disabled)$/i.test(value ?? '');
+const enabled = (value) => /^(1|true|on|yes)$/i.test(value ?? '');
+function shouldCheckCodeAtStartup(input) {
+    const env = input.env ?? process.env;
+    if (!(input.stdinTTY ?? process.stdin.isTTY) ||
+        !(input.stdoutTTY ?? process.stdout.isTTY) ||
+        !(input.stderrTTY ?? process.stderr.isTTY))
+        return false;
+    if (enabled(env.CI) ||
+        disabled(env.SKRR_CODE_UPDATE_CHECK) ||
+        disabled(env.SKRR_CODE_UPDATE_PROMPT) ||
+        enabled(env.OVERSKY_SKIP_UPDATE_CHECK) ||
+        enabled(env.OVERSKY_NO_UPDATE_NUDGE))
+        return false;
+    if ((0, first_party_harness_update_1.localCodeUpdateOwner)(env) !== 'managed' || readPreferences(env).promptOnStartup === false)
+        return false;
+    if (input.argv.some((arg) => /^(--help|-h|--version|-v|--json|--print|-p|--no-tui|--output|--format)(=|$)/.test(arg)))
+        return false;
+    if (/^(run|acp|serve|web|auth|upgrade|update|doctor|install|rollback|export|import|session|models)$/.test(input.argv[0] ?? ''))
+        return false;
+    return true;
+}
+function ttyCodeUpdateAsker() {
+    return (result) => new Promise((resolve) => {
+        const rl = node_readline_1.default.createInterface({ input: process.stdin, output: process.stderr });
+        let settled = false;
+        const finish = (choice) => {
+            if (settled)
+                return;
+            settled = true;
+            rl.close();
+            resolve(choice);
+        };
+        rl.on('close', () => finish('once'));
+        rl.question(`\n${auth_core_1.FIRST_PARTY_HARNESS.displayName} update: ${result.installedVersion ?? 'installed version not recorded'} → ${result.offeredVersion} (${result.channel})\n` +
+            '  [1] Update and start  [2] Skip this time  [3] Skip this version  [4] Disable startup checks\nChoose [2]: ', (reply) => finish(reply.trim() === '1'
+            ? 'update'
+            : reply.trim() === '3'
+                ? 'version'
+                : reply.trim() === '4'
+                    ? 'disable'
+                    : 'once'));
+    });
+}
+/** The only caller is a new interactive TUI launch, before any broker or lease. */
+async function maybeOfferCodeUpdate(input) {
+    if (!shouldCheckCodeAtStartup(input))
+        return;
+    const env = input.env ?? process.env;
+    const controller = new AbortController();
+    let timer;
+    try {
+        // Bound the whole discovery, including feed fallbacks; failed checks remain
+        // inspectable through update --check but do not hold the session open.
+        const timeout = new Promise((resolve) => {
+            timer = setTimeout(() => {
+                controller.abort();
+                resolve(null);
+            }, 1500);
+        });
+        const result = await Promise.race([
+            (input.check ?? first_party_harness_update_1.checkLocalCodeUpdate)({
+                env,
+                signal: controller.signal,
+                manifestTimeoutMs: 1500,
+            }),
+            timeout,
+        ]);
+        if (timer) {
+            clearTimeout(timer);
+            timer = undefined;
+        }
+        if (!result || result.state !== 'update-available' || !result.offeredVersion)
+            return;
+        if (readPreferences(env).skippedVersions?.[result.channel] === result.offeredVersion)
+            return;
+        const choice = await (input.ask ?? ttyCodeUpdateAsker())(result);
+        saveChoice(env, result, choice);
+        if (choice !== 'update')
+            return;
+        const updated = await (input.update ?? first_party_harness_update_1.updateLocalCode)({ env, onProgress: input.say });
+        input.say((0, first_party_harness_update_1.formatLocalCodeUpdate)(updated));
+        if (updated.state === 'failed')
+            input.say('Starting the installed engine. Inspect the update result with `skrr code doctor` or retry `skrr code update`.');
+    }
+    catch (error) {
+        input.say(`${auth_core_1.FIRST_PARTY_HARNESS.displayName} update could not complete: ${error instanceof Error ? error.message : String(error)}. Starting the installed engine.`);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}

package/dist/lib/first-party-harness-update.d.ts

@@ -0,0 +1,46 @@
+import { readFirstPartyHarnessUpdateState } from '@skrr-ai/auth-core/first-party-harness-updater';
+export type CodeUpdateOwner = 'managed' | 'external' | 'desktop' | 'image';
+export interface LocalCodeUpdateStatus {
+    component: 'code';
+    state: 'not-installed' | 'unchecked' | 'up-to-date' | 'update-available' | 'owner-managed' | 'check-failed' | 'installed' | 'failed' | 'rolled-back';
+    runningVersion: null;
+    installedVersion: string | null;
+    offeredVersion: string | null;
+    channel: string;
+    owner: CodeUpdateOwner;
+    activePath: string | null;
+    managedPath: string;
+    installedVerified: boolean;
+    command: string;
+    lastAttempt: ReturnType<typeof readFirstPartyHarnessUpdateState>;
+    message?: string;
+    code?: string;
+}
+export interface LocalCodeUpdateOptions {
+    env?: NodeJS.ProcessEnv;
+    force?: boolean;
+    version?: string;
+    allowDowngrade?: boolean;
+    onProgress?: (line: string) => void;
+    signal?: AbortSignal;
+    manifestTimeoutMs?: number;
+    /** Only an explicit install may adopt an engine currently found on PATH. */
+    install?: boolean;
+}
+export declare function localCodeUpdateOwner(env?: NodeJS.ProcessEnv): CodeUpdateOwner;
+/** Read metadata without networking or executing the engine. External versions are unknown. */
+export declare function getLocalCodeUpdateStatus(env?: NodeJS.ProcessEnv): LocalCodeUpdateStatus;
+export declare function checkLocalCodeUpdate(options?: LocalCodeUpdateOptions): Promise<LocalCodeUpdateStatus>;
+export declare function updateLocalCode(options?: LocalCodeUpdateOptions): Promise<LocalCodeUpdateStatus>;
+export declare function rollbackLocalCode(env?: NodeJS.ProcessEnv): LocalCodeUpdateStatus;
+/** Explicit --no-wait launches the same local command, with a durable private log. */
+export declare function startLocalCodeUpdate(options?: LocalCodeUpdateOptions & {
+    operation?: 'install' | 'update';
+}): Promise<{
+    component: 'code';
+    state: 'queued';
+    pid: number;
+    logPath: string;
+    command: string;
+}>;
+export declare function formatLocalCodeUpdate(result: LocalCodeUpdateStatus): string;

package/dist/lib/first-party-harness-update.js

@@ -0,0 +1,289 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.localCodeUpdateOwner = localCodeUpdateOwner;
+exports.getLocalCodeUpdateStatus = getLocalCodeUpdateStatus;
+exports.checkLocalCodeUpdate = checkLocalCodeUpdate;
+exports.updateLocalCode = updateLocalCode;
+exports.rollbackLocalCode = rollbackLocalCode;
+exports.startLocalCodeUpdate = startLocalCodeUpdate;
+exports.formatLocalCodeUpdate = formatLocalCodeUpdate;
+/** Local Code updates share the daemon's signed installer and never need an account. */
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
+const auth_core_1 = require("@skrr-ai/auth-core");
+const first_party_harness_updater_1 = require("@skrr-ai/auth-core/first-party-harness-updater");
+const first_party_harness_1 = require("./first-party-harness");
+function localCodeUpdateOwner(env = process.env) {
+    if ((0, first_party_harness_1.isDedicatedRuntimeWorkload)(env) ||
+        ['dedicated-runtime', 'hosted-machine', 'cloud-coding'].includes(env.OVERSKY_DAEMON_SOURCE ?? '') ||
+        (0, node_fs_1.existsSync)('/etc/skrr-dedicated-runtime.env'))
+        return 'image';
+    const resolution = (0, first_party_harness_1.resolveEngine)(env);
+    // CLI package ownership and engine ownership are independent: Desktop seeds
+    // the managed engine and intentionally allows it to advance separately.
+    let activePath = resolution.path;
+    try {
+        if (activePath)
+            activePath = (0, node_fs_1.realpathSync)(activePath);
+    }
+    catch {
+        /* Resolution reports a disappearing binary separately. */
+    }
+    if (env.SKRR_FIRST_PARTY_HARNESS_OWNER === 'desktop' ||
+        (activePath && /\.app[/\\]/i.test(activePath)))
+        return 'desktop';
+    return ['managed', 'legacy-managed', 'unresolved'].includes(resolution.source) &&
+        !resolution.envName
+        ? 'managed'
+        : 'external';
+}
+function ownerMessage(owner) {
+    if (owner === 'image')
+        return 'This engine belongs to the runtime image. Update the runtime image to change its engine.';
+    if (owner === 'desktop')
+        return 'This engine belongs to the desktop app. Update the app to change its engine.';
+    if (owner === 'external')
+        return 'The active engine comes from an explicit path or an external installation. Update it with its installer, or unset the path override and run `skrr code install` to use managed releases.';
+    return undefined;
+}
+/** Read metadata without networking or executing the engine. External versions are unknown. */
+function getLocalCodeUpdateStatus(env = process.env) {
+    const resolution = (0, first_party_harness_1.resolveEngine)(env);
+    const owner = localCodeUpdateOwner(env);
+    const installed = (0, first_party_harness_updater_1.getVerifiedInstalledFirstPartyHarness)({ env });
+    const managedActive = owner === 'managed' && ['managed', 'legacy-managed'].includes(resolution.source);
+    const message = ownerMessage(owner);
+    const status = {
+        component: 'code',
+        state: owner !== 'managed' ? 'owner-managed' : resolution.path ? 'unchecked' : 'not-installed',
+        runningVersion: null,
+        installedVersion: managedActive ? installed.version : null,
+        offeredVersion: null,
+        channel: (0, auth_core_1.resolveFirstPartyHarnessChannel)(env).channel,
+        owner,
+        activePath: resolution.path,
+        managedPath: (0, first_party_harness_1.managedEnginePath)(env),
+        installedVerified: managedActive && installed.verified,
+        command: owner === 'managed'
+            ? resolution.path
+                ? 'skrr code update'
+                : 'skrr code install'
+            : owner === 'desktop'
+                ? 'Update the skrr app'
+                : owner === 'image'
+                    ? 'Update the runtime image'
+                    : 'Update the external engine installation',
+        lastAttempt: (0, first_party_harness_updater_1.readFirstPartyHarnessUpdateState)(env),
+        ...(message ? { message } : {}),
+    };
+    if (owner === 'managed') {
+        const cached = readCheckCache(env, checkCacheKey(status, env));
+        if (cached)
+            return {
+                ...status,
+                state: cached.state,
+                offeredVersion: cached.offeredVersion,
+                ...(cached.state === 'check-failed' ? { message: cached.message, code: cached.code } : {}),
+            };
+    }
+    return status;
+}
+const CHECK_TTL_MS = 4 * 60 * 60 * 1000;
+const FAILED_CHECK_TTL_MS = 60_000;
+function checkCachePath(env) {
+    return node_path_1.default.join((0, auth_core_1.resolveConfigRoot)(env), 'code-update-check.json');
+}
+function checkCacheKey(current, env, version) {
+    return JSON.stringify([
+        current.channel,
+        current.installedVersion,
+        current.activePath,
+        (0, auth_core_1.readFirstPartyHarnessEnv)(env, 'updateFeedBase').value,
+        version,
+    ]);
+}
+function readCheckCache(env, key) {
+    try {
+        const cache = JSON.parse((0, node_fs_1.readFileSync)(checkCachePath(env), 'utf8'));
+        const ttl = cache.result?.state === 'check-failed' ? FAILED_CHECK_TTL_MS : CHECK_TTL_MS;
+        if (cache.key === key &&
+            Date.now() - cache.checkedAt >= 0 &&
+            Date.now() - cache.checkedAt < ttl)
+            return cache.result;
+    }
+    catch {
+        /* Missing, invalid and expired caches are a cache miss. */
+    }
+    return null;
+}
+function writeCache(env, cache) {
+    try {
+        const file = checkCachePath(env);
+        (0, node_fs_1.mkdirSync)(node_path_1.default.dirname(file), { recursive: true, mode: 0o700 });
+        const staging = `${file}.${process.pid}.tmp`;
+        (0, node_fs_1.writeFileSync)(staging, JSON.stringify(cache), { mode: 0o600 });
+        (0, node_fs_1.renameSync)(staging, file);
+    }
+    catch {
+        /* A read-only home must not prevent launching an installed engine. */
+    }
+}
+async function checkLocalCodeUpdate(options = {}) {
+    const env = options.env ?? process.env;
+    const current = getLocalCodeUpdateStatus(env);
+    if (current.owner !== 'managed')
+        return current;
+    const key = checkCacheKey(current, env, options.version);
+    if (!options.force) {
+        const cached = readCheckCache(env, key);
+        if (cached)
+            return { ...cached, lastAttempt: current.lastAttempt };
+    }
+    try {
+        const checked = await (0, first_party_harness_updater_1.checkFirstPartyHarnessUpdate)({
+            env,
+            version: options.version,
+            signal: options.signal,
+            manifestTimeoutMs: options.manifestTimeoutMs ?? 5000,
+        });
+        const result = checked.ok
+            ? {
+                ...current,
+                installedVersion: checked.installedVersion,
+                installedVerified: checked.installedVerified,
+                offeredVersion: checked.latestVersion,
+                state: !current.activePath
+                    ? 'not-installed'
+                    : checked.updateAvailable
+                        ? 'update-available'
+                        : 'up-to-date',
+                lastAttempt: checked.lastUpdate,
+            }
+            : { ...current, state: 'check-failed', code: checked.code, message: checked.error };
+        writeCache(env, { checkedAt: Date.now(), key, result });
+        return result;
+    }
+    catch (error) {
+        const result = {
+            ...current,
+            state: 'check-failed',
+            code: 'CHECK_FAILED',
+            message: error instanceof Error ? error.message : String(error),
+        };
+        writeCache(env, { checkedAt: Date.now(), key, result });
+        return result;
+    }
+}
+async function updateLocalCode(options = {}) {
+    const env = options.env ?? process.env;
+    const current = getLocalCodeUpdateStatus(env);
+    if (!current.activePath && current.owner === 'managed' && !options.install) {
+        return {
+            ...current,
+            state: 'failed',
+            code: 'NOT_INSTALLED',
+            message: `${auth_core_1.FIRST_PARTY_HARNESS.displayName} is not installed on this computer. Run \`skrr code install\`.`,
+        };
+    }
+    const adoptingPath = options.install &&
+        current.owner === 'external' &&
+        ['path', 'fallback'].includes((0, first_party_harness_1.resolveEngine)(env).source);
+    if (current.owner !== 'managed' && !adoptingPath)
+        return { ...current, state: 'failed', code: 'ENGINE_UPDATE_OWNER' };
+    const result = await (0, first_party_harness_updater_1.installFirstPartyHarness)({
+        env,
+        version: options.version,
+        allowDowngrade: options.allowDowngrade,
+        onProgress: options.onProgress,
+        signal: options.signal,
+        manifestTimeoutMs: options.manifestTimeoutMs,
+    });
+    if (!result.ok)
+        return {
+            ...getLocalCodeUpdateStatus(env),
+            state: 'failed',
+            code: result.code,
+            message: result.error,
+        };
+    // Only a successful verified install invalidates an offered-version cache.
+    writeCache(env, { checkedAt: 0, key: '', result: current });
+    return {
+        ...getLocalCodeUpdateStatus(env),
+        state: result.changed === false ? 'up-to-date' : 'installed',
+        offeredVersion: result.version ?? null,
+        ...(adoptingPath
+            ? { message: `The managed signed release now takes precedence over ${current.activePath}.` }
+            : {}),
+    };
+}
+function rollbackLocalCode(env = process.env) {
+    const current = getLocalCodeUpdateStatus(env);
+    if (current.owner !== 'managed')
+        return { ...current, state: 'failed', code: 'ENGINE_UPDATE_OWNER' };
+    const result = (0, first_party_harness_updater_1.rollbackFirstPartyHarness)(env);
+    if (!result.ok)
+        return {
+            ...getLocalCodeUpdateStatus(env),
+            state: 'failed',
+            code: result.code,
+            message: result.error,
+        };
+    writeCache(env, { checkedAt: 0, key: '', result: current });
+    return { ...getLocalCodeUpdateStatus(env), state: 'rolled-back', offeredVersion: null };
+}
+/** Explicit --no-wait launches the same local command, with a durable private log. */
+async function startLocalCodeUpdate(options = {}) {
+    const env = options.env ?? process.env;
+    const current = getLocalCodeUpdateStatus(env);
+    const adoptingPath = options.operation === 'install' &&
+        current.owner === 'external' &&
+        ['path', 'fallback'].includes((0, first_party_harness_1.resolveEngine)(env).source);
+    if (current.owner !== 'managed' && !adoptingPath)
+        throw new Error(current.message);
+    const dir = node_path_1.default.join((0, auth_core_1.resolveConfigRoot)(env), 'update-logs');
+    (0, node_fs_1.mkdirSync)(dir, { recursive: true, mode: 0o700 });
+    const logPath = node_path_1.default.join(dir, `code-${Date.now()}-${process.pid}.log`);
+    const fd = (0, node_fs_1.openSync)(logPath, 'wx', 0o600);
+    try {
+        const args = [
+            node_path_1.default.resolve(__dirname, '../../bin/run.js'),
+            'code',
+            options.operation ?? 'update',
+            '--json',
+        ];
+        if (options.version)
+            args.push('--target-version', options.version);
+        if (options.allowDowngrade)
+            args.push('--allow-downgrade');
+        const child = (0, node_child_process_1.spawn)(process.execPath, args, { detached: true, stdio: ['ignore', fd, fd], env });
+        await new Promise((resolve, reject) => {
+            child.once('spawn', resolve);
+            child.once('error', reject);
+        });
+        child.unref();
+        return {
+            component: 'code',
+            state: 'queued',
+            pid: child.pid,
+            logPath,
+            command: 'skrr code doctor',
+        };
+    }
+    finally {
+        (0, node_fs_1.closeSync)(fd);
+    }
+}
+function formatLocalCodeUpdate(result) {
+    const installed = result.installedVersion ?? (result.activePath ? 'version not recorded' : 'not installed');
+    if (result.state === 'failed' || result.state === 'check-failed' || result.owner !== 'managed')
+        return result.message ?? `${result.code}: ${result.command}`;
+    if (result.state === 'rolled-back')
+        return `${auth_core_1.FIRST_PARTY_HARNESS.displayName} rolled back to ${installed}. New sessions use this release; existing sessions continue.`;
+    if (result.state === 'installed')
+        return `${auth_core_1.FIRST_PARTY_HARNESS.displayName} ${installed} is installed. New sessions use this release; existing sessions continue.${result.message ? ` ${result.message}` : ''}`;
+    return `${auth_core_1.FIRST_PARTY_HARNESS.displayName}: ${installed}; channel ${result.channel}${result.offeredVersion ? `; latest ${result.offeredVersion}` : ''}. ${result.state === 'update-available' ? 'Run `skrr code update` to install it.' : result.state === 'not-installed' ? 'Run `skrr code install` to install it.' : result.state === 'unchecked' ? 'Run `skrr code update --check` to check the channel.' : 'Up to date.'}`;
+}

package/dist/lib/first-party-harness.js

@@ -344,10 +344,10 @@ function notInstalledMessage(env = process.env) {
     return [
         `The ${displayName} engine (\`${(0, auth_core_1.firstPartyHarnessBinaryName)()}\`) is not installed on this machine.`,
         '',
-        'Install it through the daemon, which verifies the signed release:',
-        `  • \`${command} install\`  — from here, no browser needed`,
+        'Install a verified signed release on this computer:',
+        `  • \`${command} install\`  — no account or daemon needed`,
         `  • Or in the web app: the runtime menu beside the chat input → ${displayName} → Install`,
-        '  • Either way a daemon must be running here: `skrr daemon status`',
+        '    (the web app installs through a connected daemon)',
         '',
         `Or point the CLI at an existing build:  export ${auth_core_1.FIRST_PARTY_HARNESS_ENV.path.name}=/absolute/path/to/${(0, auth_core_1.firstPartyHarnessBinaryName)()}`,
         '  (an unsigned build runs, and since 2026-08-11 at the same trust tier as a',
@@ -660,6 +660,9 @@ async function execEngine(args, env = process.env, options = {}) {
     const { path: bin } = resolveEngine(env);
     if (!bin)
         throw new Error(exports.ENGINE_NOT_INSTALLED);
+    // Updates switch a symlink to an immutable release. Resolve it before the
+    // asynchronous broker preparation so this launch keeps the release it chose.
+    const pinnedBin = (0, node_fs_1.realpathSync)(bin);
     // Assumed until the spawn tells us otherwise, so a teardown that runs after a
     // spawn ERROR does not claim the run was interrupted.
     const outcome = { interrupted: false };
@@ -672,7 +675,7 @@ async function execEngine(args, env = process.env, options = {}) {
         const spawnArgs = options.finalizeArgs ? options.finalizeArgs([...args]) : args;
         // Read AFTER `prepare`, because that is when the hook knows what it acquired.
         const mode = options.credentialMode?.() ?? 'byok';
-        return await spawnEngine(bin, spawnArgs, env, extraEnv, mode, outcome, options.policyEnv);
+        return await spawnEngine(pinnedBin, spawnArgs, env, extraEnv, mode, outcome, options.policyEnv);
     }
     finally {
         // In a `finally` rather than on `exit`, so a spawn error and a Ctrl-C both

package/dist/lib/managed-instruction-local.d.ts

@@ -0,0 +1,12 @@
+export interface LocalInstructionIdentity {
+    daemonId: string;
+    serverUrl: string;
+    profile: string;
+    connected: boolean;
+    userId?: string;
+}
+/** Cloud ownership never proves locality. Verify the exact profile over loopback. */
+export declare function resolveLocalInstructionDaemon(options?: {
+    waitMs?: number;
+    log?: (message: string) => void;
+}): Promise<string | null>;

package/dist/lib/managed-instruction-local.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveLocalInstructionDaemon = resolveLocalInstructionDaemon;
+const loopback_http_1 = require("@skrr-ai/auth-core/loopback-http");
+const data_provider_1 = require("@skrr-ai/data-provider");
+const config_1 = require("./config");
+const daemonBroker_1 = require("./daemonBroker");
+const keychain_1 = require("./keychain");
+/** Cloud ownership never proves locality. Verify the exact profile over loopback. */
+async function resolveLocalInstructionDaemon(options = {}) {
+    const profile = (0, keychain_1.getActiveProfile)();
+    const serverUrl = (0, config_1.loadConfig)().baseURL;
+    const deadline = Date.now() + (options.waitMs ?? 0);
+    let waiting = false;
+    for (;;) {
+        const daemonId = await inspectLocalInstructionDaemon(profile, serverUrl);
+        if (daemonId)
+            return daemonId;
+        if (Date.now() >= deadline)
+            return null;
+        if (!waiting) {
+            options.log?.('Waiting for the signed-in local daemon before instruction setup...');
+            waiting = true;
+        }
+        await new Promise((resolve) => setTimeout(resolve, Math.min(300, deadline - Date.now())));
+    }
+}
+async function inspectLocalInstructionDaemon(profile, serverUrl) {
+    for (const candidate of (0, daemonBroker_1.resolveExactProfileBootstrapPaths)(profile)) {
+        const bootstrap = (0, daemonBroker_1.readBootstrap)(candidate);
+        if (!bootstrap?.secret)
+            continue;
+        if (bootstrap.serverUrl &&
+            (0, daemonBroker_1.normalizeBaseUrl)(bootstrap.serverUrl) !== (0, daemonBroker_1.normalizeBaseUrl)(serverUrl))
+            continue;
+        try {
+            const response = await (0, loopback_http_1.loopbackFetch)(`http://${bootstrap.host}:${bootstrap.port}/managed-instructions/identity`, { headers: { 'X-Island-Secret': bootstrap.secret }, signal: AbortSignal.timeout(3_000) });
+            if (!response.ok)
+                continue;
+            const identity = (await response.json());
+            if (!identity.daemonId ||
+                identity.connected !== true ||
+                !identity.userId ||
+                (0, daemonBroker_1.normalizeBaseUrl)(identity.serverUrl) !== (0, daemonBroker_1.normalizeBaseUrl)(serverUrl) ||
+                identity.profile !== profile ||
+                (bootstrap.daemonId && identity.daemonId !== bootstrap.daemonId))
+                continue;
+            const user = await data_provider_1.dataService.getUser();
+            if (user.id === identity.userId)
+                return identity.daemonId;
+        }
+        catch {
+            // Old services, reconnecting auth and stale descriptors are recoverable.
+            // Never infer a replacement from other profiles or the account's machines.
+        }
+    }
+    return null;
+}

package/dist/lib/managed-instruction-setup.d.ts

@@ -0,0 +1,35 @@
+import type { ManagedInstructionProvider, ManagedInstructionTarget, ManagedInstructionPrepareResponse } from '@skrr-ai/data-provider';
+type PreparedOffer = ManagedInstructionPrepareResponse;
+export interface InstructionSetupOptions {
+    log: (message: string) => void;
+    trigger: 'manual' | 'login' | 'task';
+    daemonId?: string;
+    providers?: ManagedInstructionProvider[];
+    trackingMode?: 'latest' | 'pinned';
+    yes?: boolean;
+    json?: boolean;
+    review?: boolean;
+    /** Only a successful credential handoff proves a local service is becoming ready. */
+    waitForLocalReady?: boolean;
+}
+export interface InstructionSetupResult {
+    status: 'skipped' | 'unavailable' | 'reviewed' | 'unchanged' | 'decided';
+    daemonId?: string;
+    message?: string;
+    prepared?: PreparedOffer;
+    targets: ManagedInstructionTarget[];
+    installed: ManagedInstructionTarget[];
+    decisions: Array<{
+        provider: ManagedInstructionProvider;
+        action: 'install' | 'snooze' | 'decline' | 'keep';
+    }>;
+}
+export declare function shouldSkipInstructionPrompt(): boolean;
+export declare function instructionProviderLabel(provider: ManagedInstructionProvider): string;
+/** Read-only preflight precedes every consent and every write to the API. */
+export declare function runManagedInstructionSetup(options: InstructionSetupOptions): Promise<InstructionSetupResult>;
+/** Optional onboarding must not change the successful login/task exit status. */
+export declare function maybeOfferManagedInstructionSetup(options: Omit<InstructionSetupOptions, 'trigger'> & {
+    trigger: 'login' | 'task';
+}): Promise<void>;
+export {};