@skrr-ai/cli 0.1.11 → 0.1.13

package/dist/commands/daemon/index.js

@@ -10,7 +10,10 @@ const exec_oversky_1 = require("../../lib/exec-oversky");
  * quick install check.
  */
 class Daemon extends core_1.Command {
-    static description = 'Manage the local skrr runtime. Wraps the `skrrd` binary.';
+    // "Wraps the `skrrd` binary" read, cold, as though you must already HAVE one —
+    // the opposite of what `skrr daemon install` does now that it fetches the
+    // signed release. Dogfooding 0.1.12 hit exactly that reading.
+    static description = 'Manage the local skrr runtime — install it, sign it in, and check on it.';
     static examples = [
         '<%= config.bin %> daemon install',
         '<%= config.bin %> daemon status',

package/dist/commands/daemon/install.d.ts

@@ -10,6 +10,20 @@ import { Command } from '@oclif/core';
  * A thin proxy, like every other verb here: the service-management logic stays
  * in the runtime, which is the only component that knows its own service label
  * on each platform.
+ *
+ * WITH ONE ADDITION: it fetches the runtime first when there isn't one.
+ *
+ * Before that, this command refused with "install it with brew" whenever
+ * `skrrd` was absent — so the command whose entire job is to set the machine up
+ * required the machine to already be set up, and onboarding's first step was a
+ * second install from a second distribution channel, before the user had signed
+ * in or seen anything work. npm is the front door: `npm i -g @skrr-ai/cli`
+ * gives you `skrr`, and `skrr daemon install` gets the daemon.
+ *
+ * The download is verified against the same pinned ed25519 keys the daemon's
+ * own self-updater uses — see `daemon-installer.ts`. It is deliberately NOT a
+ * silent side effect: the fetch is announced, because a command that installs
+ * an executable should say so.
  */
 export default class DaemonInstall extends Command {
     static aliases: string[];

package/dist/commands/daemon/install.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const core_1 = require("@oclif/core");
 const exec_oversky_1 = require("../../lib/exec-oversky");
 const daemon_binding_1 = require("../../lib/daemon-binding");
+const daemon_installer_1 = require("../../lib/daemon-installer");
 /**
  * `skrr daemon install` — install the local runtime's OS service.
  *
@@ -14,6 +15,20 @@ const daemon_binding_1 = require("../../lib/daemon-binding");
  * A thin proxy, like every other verb here: the service-management logic stays
  * in the runtime, which is the only component that knows its own service label
  * on each platform.
+ *
+ * WITH ONE ADDITION: it fetches the runtime first when there isn't one.
+ *
+ * Before that, this command refused with "install it with brew" whenever
+ * `skrrd` was absent — so the command whose entire job is to set the machine up
+ * required the machine to already be set up, and onboarding's first step was a
+ * second install from a second distribution channel, before the user had signed
+ * in or seen anything work. npm is the front door: `npm i -g @skrr-ai/cli`
+ * gives you `skrr`, and `skrr daemon install` gets the daemon.
+ *
+ * The download is verified against the same pinned ed25519 keys the daemon's
+ * own self-updater uses — see `daemon-installer.ts`. It is deliberately NOT a
+ * silent side effect: the fetch is announced, because a command that installs
+ * an executable should say so.
  */
 class DaemonInstall extends core_1.Command {
     // `skrr daemons <sub>` — the plural is advertised as an alias for the
@@ -34,6 +49,24 @@ class DaemonInstall extends core_1.Command {
         // own comment records `skrr code run -m <model>` dying the same way. Same
         // mistake, one directory over.
         const argv = this.argv;
+        // Bootstrap only when there is nothing to forward to. An existing runtime —
+        // brew, the script installer, a dev checkout — is left exactly alone; this
+        // is a floor under the missing case, not a second update channel competing
+        // with the daemon's own.
+        if (!(0, exec_oversky_1.findOverskyBinary)()) {
+            this.log('No local skrr runtime found. Fetching the signed release...');
+            const outcome = await (0, daemon_installer_1.installDaemon)();
+            if (!outcome.ok) {
+                this.log('');
+                this.log(`  Could not install the runtime: ${outcome.error}`);
+                this.log('');
+                this.log('  You can install it directly instead:');
+                this.log('    macOS:   brew install dush1023/oversky/oversky');
+                this.log('    Linux:   curl -fsSL https://raw.githubusercontent.com/dush1023/OverSky/main/scripts/install-daemon.sh | bash');
+                this.exit(1);
+            }
+            this.log(`  Installed skrrd ${outcome.version} (${outcome.platformKey}) at ${outcome.binaryPath}`);
+        }
         try {
             // Bind the new daemon to the deployment and profile the CLI is on,
             // for whichever of those the user did not state. Installing is the
@@ -45,7 +78,10 @@ class DaemonInstall extends core_1.Command {
         }
         catch (err) {
             if (err.message === 'oversky-not-installed') {
-                this.log((0, exec_oversky_1.notInstalledMessage)());
+                // Reachable only if the runtime vanished between the bootstrap above
+                // and this line. Saying so beats repeating install instructions for
+                // something that was just installed.
+                this.log('The skrr runtime disappeared between installing it and running it.');
                 this.exit(127);
             }
             throw err;

package/dist/commands/login.js

@@ -5,6 +5,7 @@ const data_provider_1 = require("@skrr-ai/data-provider");
 const auth_core_1 = require("@skrr-ai/auth-core");
 const base_command_1 = require("../base-command");
 const daemonHandoff_1 = require("../lib/daemonHandoff");
+const daemon_setup_1 = require("../lib/daemon-setup");
 const config_1 = require("../lib/config");
 const keychain_1 = require("../lib/keychain");
 const login_1 = require("../lib/login");
@@ -179,7 +180,29 @@ class Login extends base_command_1.BaseCommand {
                 // and a failure here must not fail it or discard what the user just earned.
                 // It degrades to exactly the old behaviour, with a hint naming the command
                 // that finishes the job.
-                const handoff = await (0, daemonHandoff_1.handOffToLocalDaemon)(process.env, { loginFlow: result.flow });
+                let handoff = await (0, daemonHandoff_1.handOffToLocalDaemon)(process.env, { loginFlow: result.flow });
+                // Nothing to hand a credential TO. This is the first moment we can fix
+                // that correctly — installing the daemon binds it to a deployment and a
+                // profile, and until this login there was no session to take them from.
+                // Keyed off `reason` rather than the sentence in `detail`, which is
+                // written for a person and expected to be reworded.
+                if (handoff.reason === 'no-binary' || handoff.reason === 'no-service') {
+                    const setup = await (0, daemon_setup_1.offerDaemonSetup)({
+                        binaryPresent: handoff.reason === 'no-service',
+                        log: (line) => this.log(line),
+                    });
+                    if (setup.status === 'installed') {
+                        // Re-run rather than duplicating the mint here: it is the same act
+                        // it always was, and now it has somewhere to land.
+                        handoff = await (0, daemonHandoff_1.handOffToLocalDaemon)(process.env, { loginFlow: result.flow });
+                    }
+                    else if (setup.status === 'failed') {
+                        this.log(`Could not set up the runtime: ${setup.detail}.`);
+                    }
+                    else {
+                        this.log(`This machine is not set up — ${setup.detail}.`);
+                    }
+                }
                 if (handoff.status === 'delivered') {
                     this.log(`The local daemon was signed in too — ${handoff.detail}.`);
                 }

package/dist/help.d.ts

@@ -20,8 +20,27 @@ import { Help } from '@oclif/core';
  * before running it. The audience most likely to need the good message was the
  * audience reliably denied it.
  *
- * Only the not-found path is overridden. Real help output is untouched.
+ * It also puts a GETTING STARTED block at the top of `skrr --help`.
+ *
+ * Dogfooding 0.1.12 found the root help teaching neither of the two commands
+ * the release exists to deliver: ~50 topics in alphabetical order, with `login`
+ * between `list-tokens` and `logout`, and nothing saying a runtime is needed or
+ * that `skrr` can fetch one. The shortest path to a working machine was
+ * undiscoverable from inside the tool that provides it — findable only by
+ * someone who read the docs, which is what the two-command flow exists to make
+ * unnecessary.
+ *
+ * Printed BEFORE the standard output rather than appended, because the thing it
+ * competes with is a fifty-line topic list. A signpost below that is a signpost
+ * for people who already knew.
  */
 export default class SkrrHelp extends Help {
+    /**
+     * The two commands, before the topic list rather than after it.
+     *
+     * Deliberately not a tutorial: two lines, both runnable, in the order a new
+     * machine needs them.
+     */
+    protected showRootHelp(): Promise<void>;
     showHelp(argv: string[]): Promise<void>;
 }

package/dist/help.js

@@ -23,9 +23,34 @@ const command_miss_1 = require("./lib/command-miss");
  * before running it. The audience most likely to need the good message was the
  * audience reliably denied it.
  *
- * Only the not-found path is overridden. Real help output is untouched.
+ * It also puts a GETTING STARTED block at the top of `skrr --help`.
+ *
+ * Dogfooding 0.1.12 found the root help teaching neither of the two commands
+ * the release exists to deliver: ~50 topics in alphabetical order, with `login`
+ * between `list-tokens` and `logout`, and nothing saying a runtime is needed or
+ * that `skrr` can fetch one. The shortest path to a working machine was
+ * undiscoverable from inside the tool that provides it — findable only by
+ * someone who read the docs, which is what the two-command flow exists to make
+ * unnecessary.
+ *
+ * Printed BEFORE the standard output rather than appended, because the thing it
+ * competes with is a fifty-line topic list. A signpost below that is a signpost
+ * for people who already knew.
  */
 class SkrrHelp extends core_1.Help {
+    /**
+     * The two commands, before the topic list rather than after it.
+     *
+     * Deliberately not a tutorial: two lines, both runnable, in the order a new
+     * machine needs them.
+     */
+    async showRootHelp() {
+        this.log('GETTING STARTED');
+        this.log('  skrr login             Sign in. Offers to set this machine up if it has no runtime.');
+        this.log('  skrr daemon install    Install the runtime by hand (fetches the signed release).');
+        this.log('');
+        return super.showRootHelp();
+    }
     async showHelp(argv) {
         // Mirror oclif's own id resolution: the topic separator is a space here, so
         // the id is the leading non-flag tokens joined with `:`.

package/dist/lib/daemon-installer.d.ts

@@ -0,0 +1,62 @@
+import { type DaemonVersionManifest, type ReleaseKey } from '@skrr-ai/auth-core';
+/** Public CloudFront feed. Mirrors the daemon's own `CLOUDFRONT_FEED_BASE`. */
+export declare const DEFAULT_DAEMON_FEED_BASE = "https://updates.oversky.ai/daemon";
+/** Same override the daemon honours, so one env var steers both. */
+export declare const DAEMON_FEED_BASE_ENV = "OVERSKY_DAEMON_UPDATE_FEED_BASE";
+export type DaemonInstallFailureCode = 'unsupported_platform' | 'manifest_unreachable' | 'manifest_malformed' | 'manifest_unsigned' | 'platform_missing' | 'untrusted_artifact_origin' | 'download_failed' | 'checksum_mismatch' | 'artifact_unsigned' | 'write_failed';
+export type DaemonInstallResult = {
+    ok: true;
+    version: string;
+    platformKey: string;
+    binaryPath: string;
+} | {
+    ok: false;
+    code: DaemonInstallFailureCode;
+    error: string;
+};
+export interface DaemonInstallOptions {
+    env?: NodeJS.ProcessEnv;
+    /** Override the feed root. Tests point this at a local fixture server. */
+    feedBase?: string;
+    /** Injected for tests; defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+    /**
+     * Trust anchors. Defaults to the pinned production set; tests substitute a
+     * generated keypair, exactly as the sky-code installer does. Passing an EMPTY
+     * set does not disable verification here — every non-`ok` verdict is a
+     * refusal, so an unconfigured trust root turns installs off rather than
+     * turning checking off.
+     */
+    keys?: readonly ReleaseKey[];
+}
+export declare function daemonFeedBase(env?: NodeJS.ProcessEnv): string;
+/**
+ * Where the fetched binary lands. `exec-oversky.ts` already looks here, so a
+ * daemon installed by this path is found by every `skrr daemon *` command
+ * without the user touching PATH.
+ */
+export declare function daemonBinaryPath(env?: NodeJS.ProcessEnv): string;
+/**
+ * `<platform>-<arch>`, the manifest's `platforms` key. Returns null for a
+ * combination the release does not build, which is a clearer refusal than a
+ * missing-key lookup one step later.
+ */
+export declare function daemonPlatformKey(platform?: string, arch?: string): string | null;
+/**
+ * True when `candidate` may serve an artifact for a feed rooted at `feedBase`.
+ * Same rule as the daemon's `isTrustedArtifactOrigin`: a signed manifest still
+ * does not get to point the download at another origin.
+ */
+export declare function isTrustedArtifactOrigin(candidate: string, feedBase: string): boolean;
+/** Fetch `<feedBase>/latest/daemon-version.json` and verify its signature. */
+export declare function fetchVerifiedDaemonManifest(opts?: DaemonInstallOptions): Promise<{
+    ok: true;
+    manifest: DaemonVersionManifest;
+} | (DaemonInstallResult & {
+    ok: false;
+})>;
+/**
+ * Download, verify and install the daemon binary. Returns a tagged result; it
+ * never throws, so the caller can render one refusal for every failure mode.
+ */
+export declare function installDaemon(opts?: DaemonInstallOptions): Promise<DaemonInstallResult>;

package/dist/lib/daemon-installer.js

@@ -0,0 +1,247 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DAEMON_FEED_BASE_ENV = exports.DEFAULT_DAEMON_FEED_BASE = void 0;
+exports.daemonFeedBase = daemonFeedBase;
+exports.daemonBinaryPath = daemonBinaryPath;
+exports.daemonPlatformKey = daemonPlatformKey;
+exports.isTrustedArtifactOrigin = isTrustedArtifactOrigin;
+exports.fetchVerifiedDaemonManifest = fetchVerifiedDaemonManifest;
+exports.installDaemon = installDaemon;
+/**
+ * daemon-installer.ts — fetch, verify and place the signed `skrrd` binary.
+ *
+ * ## Why this exists
+ *
+ * `skrr daemon install` forwarded to `skrrd install`, and `findOverskyBinary()`
+ * refused with "install it with brew" when there was no `skrrd` to forward to.
+ * So the one command whose job is to set the machine up required the machine to
+ * already be set up, and onboarding's first step was a second install from a
+ * second distribution channel — before the user had signed in or seen anything
+ * work.
+ *
+ * npm is the front door now. `npm i -g @skrr-ai/cli` gives you `skrr`, and
+ * `skrr daemon install` gets the daemon itself.
+ *
+ * ## Why it downloads a binary instead of shipping one
+ *
+ * The daemon is a compiled per-platform executable that is codesigned,
+ * notarized, and auto-updates itself in the field from a signed CloudFront feed
+ * with rollout cohorts. Vendoring five platform binaries into an npm tarball
+ * would bloat every install to serve one platform, and — worse — would freeze a
+ * copy that the daemon's own updater cannot replace, because that updater swaps
+ * a binary in its release slot, not a file inside a node_modules tree. Fetching
+ * from the same feed the updater uses keeps ONE distribution channel for the
+ * daemon and leaves its update story intact.
+ *
+ * ## Trust
+ *
+ * This is the CLI downloading an executable and putting it on disk, so every
+ * gate the daemon's own self-updater applies is applied here too, against the
+ * SAME pinned keys (`@skrr-ai/auth-core`, moved there for this reason — a
+ * mirrored trust root is a second array that can be emptied):
+ *
+ *   1. the manifest's ed25519 signature, fail-closed;
+ *   2. the artifact URL must share the feed's origin. The signature already
+ *      covers the URL, so this is not about forgery — it bounds where a
+ *      LEGITIMATELY signed manifest can send us, which is what protects against
+ *      operator error and against a signer coerced into signing a redirect;
+ *   3. sha256 of the received bytes;
+ *   4. the artifact's own ed25519 signature over (platform, version, sha256, url).
+ *
+ * TLS alone is explicitly not enough: the sha256 travels in the same document
+ * over the same channel, so it defends against corruption in transit, not
+ * against a spoofed feed. (3) without (4) would be the same mistake.
+ *
+ * The write is staged then renamed, so an interrupted download can never leave
+ * a half-written executable at the path the CLI will later exec.
+ */
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const auth_core_1 = require("@skrr-ai/auth-core");
+/** Public CloudFront feed. Mirrors the daemon's own `CLOUDFRONT_FEED_BASE`. */
+exports.DEFAULT_DAEMON_FEED_BASE = 'https://updates.oversky.ai/daemon';
+/** Same override the daemon honours, so one env var steers both. */
+exports.DAEMON_FEED_BASE_ENV = 'OVERSKY_DAEMON_UPDATE_FEED_BASE';
+/** Refuse a manifest larger than this. It is a small JSON document. */
+const MAX_MANIFEST_BYTES = 1_024 * 1_024;
+/** Refuse an artifact larger than this regardless of what the manifest claims. */
+const MAX_ARTIFACT_BYTES = 256 * 1_024 * 1_024;
+const MANIFEST_TIMEOUT_MS = 30_000;
+const ARTIFACT_TIMEOUT_MS = 10 * 60_000;
+function daemonFeedBase(env = process.env) {
+    return (env[exports.DAEMON_FEED_BASE_ENV]?.trim() || exports.DEFAULT_DAEMON_FEED_BASE).replace(/\/+$/, '');
+}
+/**
+ * Where the fetched binary lands. `exec-oversky.ts` already looks here, so a
+ * daemon installed by this path is found by every `skrr daemon *` command
+ * without the user touching PATH.
+ */
+function daemonBinaryPath(env = process.env) {
+    const home = env.HOME || env.USERPROFILE || node_os_1.default.homedir();
+    const exe = process.platform === 'win32' ? 'skrrd.exe' : 'skrrd';
+    return node_path_1.default.join(home, '.skrr', 'bin', exe);
+}
+/**
+ * `<platform>-<arch>`, the manifest's `platforms` key. Returns null for a
+ * combination the release does not build, which is a clearer refusal than a
+ * missing-key lookup one step later.
+ */
+function daemonPlatformKey(platform = process.platform, arch = process.arch) {
+    const supported = new Set([
+        'darwin-arm64',
+        'darwin-x64',
+        'linux-arm64',
+        'linux-x64',
+        'win32-x64',
+    ]);
+    const key = `${platform}-${arch}`;
+    return supported.has(key) ? key : null;
+}
+/**
+ * True when `candidate` may serve an artifact for a feed rooted at `feedBase`.
+ * Same rule as the daemon's `isTrustedArtifactOrigin`: a signed manifest still
+ * does not get to point the download at another origin.
+ */
+function isTrustedArtifactOrigin(candidate, feedBase) {
+    try {
+        return new URL(candidate).origin === new URL(feedBase).origin;
+    }
+    catch {
+        return false;
+    }
+}
+function fail(code, error) {
+    return { ok: false, code, error };
+}
+async function getWithTimeout(url, timeoutMs, fetchImpl) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        return await fetchImpl(url, {
+            signal: controller.signal,
+            headers: { 'User-Agent': 'skrr-cli (daemon install)' },
+        });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** Fetch `<feedBase>/latest/daemon-version.json` and verify its signature. */
+async function fetchVerifiedDaemonManifest(opts = {}) {
+    const env = opts.env ?? process.env;
+    const feedBase = opts.feedBase ?? daemonFeedBase(env);
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const keys = opts.keys ?? auth_core_1.OVERSKY_RELEASE_PUBLIC_KEYS;
+    const url = `${feedBase}/latest/daemon-version.json`;
+    let res;
+    try {
+        res = await getWithTimeout(url, MANIFEST_TIMEOUT_MS, fetchImpl);
+    }
+    catch (err) {
+        return fail('manifest_unreachable', `${url}: ${err.message}`);
+    }
+    if (!res.ok) {
+        return fail('manifest_unreachable', `${url} returned HTTP ${res.status}`);
+    }
+    const text = await res.text();
+    if (text.length > MAX_MANIFEST_BYTES) {
+        return fail('manifest_malformed', 'release manifest is implausibly large');
+    }
+    let manifest;
+    try {
+        manifest = JSON.parse(text);
+    }
+    catch {
+        return fail('manifest_malformed', `${url} did not return JSON`);
+    }
+    if (!manifest || typeof manifest.version !== 'string' || !manifest.platforms) {
+        return fail('manifest_malformed', 'release manifest is missing version/platforms');
+    }
+    // Fail-closed by construction: the pinned key set is non-empty, so `disabled`
+    // cannot be reached here. Treating it as a refusal anyway means emptying that
+    // array turns installs OFF rather than turning verification off silently.
+    const verdict = (0, auth_core_1.verifyManifest)(manifest, keys);
+    if (!('ok' in verdict) || verdict.ok !== true) {
+        const reason = 'reason' in verdict ? verdict.reason : 'no release signing key is pinned';
+        return fail('manifest_unsigned', `release manifest failed verification: ${reason}`);
+    }
+    return { ok: true, manifest };
+}
+/**
+ * Download, verify and install the daemon binary. Returns a tagged result; it
+ * never throws, so the caller can render one refusal for every failure mode.
+ */
+async function installDaemon(opts = {}) {
+    const env = opts.env ?? process.env;
+    const feedBase = opts.feedBase ?? daemonFeedBase(env);
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const keys = opts.keys ?? auth_core_1.OVERSKY_RELEASE_PUBLIC_KEYS;
+    const platformKey = daemonPlatformKey();
+    if (!platformKey) {
+        return fail('unsupported_platform', `no daemon build for ${process.platform}-${process.arch}`);
+    }
+    const fetched = await fetchVerifiedDaemonManifest({ env, feedBase, fetchImpl, keys });
+    if (!('manifest' in fetched))
+        return fetched;
+    const { manifest } = fetched;
+    const artifact = manifest.platforms[platformKey];
+    if (!artifact?.url || !artifact.sha256) {
+        return fail('platform_missing', `release ${manifest.version} publishes no artifact for ${platformKey}`);
+    }
+    if (!isTrustedArtifactOrigin(artifact.url, feedBase)) {
+        return fail('untrusted_artifact_origin', `manifest points ${platformKey} at ${artifact.url}, which is not on the feed's origin`);
+    }
+    const artifactVerdict = (0, auth_core_1.verifyArtifact)(platformKey, manifest.version, artifact, keys);
+    if (!('ok' in artifactVerdict) || artifactVerdict.ok !== true) {
+        const reason = 'reason' in artifactVerdict ? artifactVerdict.reason : 'no key pinned';
+        return fail('artifact_unsigned', `${platformKey} artifact failed verification: ${reason}`);
+    }
+    if (typeof artifact.size === 'number' && artifact.size > MAX_ARTIFACT_BYTES) {
+        return fail('download_failed', `manifest declares an implausible size (${artifact.size} bytes)`);
+    }
+    let bytes;
+    try {
+        const res = await getWithTimeout(artifact.url, ARTIFACT_TIMEOUT_MS, fetchImpl);
+        if (!res.ok) {
+            return fail('download_failed', `${artifact.url} returned HTTP ${res.status}`);
+        }
+        const buf = Buffer.from(await res.arrayBuffer());
+        if (buf.byteLength > MAX_ARTIFACT_BYTES) {
+            return fail('download_failed', 'downloaded artifact exceeds the size ceiling');
+        }
+        bytes = buf;
+    }
+    catch (err) {
+        return fail('download_failed', `${artifact.url}: ${err.message}`);
+    }
+    const actual = (0, node_crypto_1.createHash)('sha256').update(bytes).digest('hex');
+    if (actual !== artifact.sha256.toLowerCase()) {
+        return fail('checksum_mismatch', `sha256 mismatch for ${platformKey}: expected ${artifact.sha256}, received ${actual}`);
+    }
+    // Staged then renamed. A rename within one directory is atomic, so the path
+    // the CLI later execs is either the previous binary or the fully-written new
+    // one — never a truncated download wearing the executable bit.
+    const binaryPath = daemonBinaryPath(env);
+    const stagingPath = `${binaryPath}.staging-${process.pid}`;
+    try {
+        (0, node_fs_1.mkdirSync)(node_path_1.default.dirname(binaryPath), { recursive: true });
+        (0, node_fs_1.writeFileSync)(stagingPath, bytes, { mode: 0o755 });
+        (0, node_fs_1.chmodSync)(stagingPath, 0o755);
+        (0, node_fs_1.renameSync)(stagingPath, binaryPath);
+    }
+    catch (err) {
+        try {
+            (0, node_fs_1.rmSync)(stagingPath, { force: true });
+        }
+        catch {
+            /* best-effort staging cleanup */
+        }
+        return fail('write_failed', `could not install to ${binaryPath}: ${err.message}`);
+    }
+    return { ok: true, version: manifest.version, platformKey, binaryPath };
+}

package/dist/lib/daemon-setup.d.ts

@@ -0,0 +1,49 @@
+/**
+ * daemon-setup.ts — offer to set this machine up, at the moment we can.
+ *
+ * ## Why login and not `npm install`
+ *
+ * The obvious way to remove a step is a `postinstall` that installs the daemon
+ * when the CLI is installed. It cannot work, and the reason is specific rather
+ * than aesthetic: installing the daemon BINDS it to a deployment and profile,
+ * taken from the CLI's session (`bindToCliSession`, OSK-279 — a daemon on a
+ * different deployment than its CLI is the failure that binding exists to
+ * prevent). At `npm install` time there is no session.
+ *
+ * It would not even fail loudly. With no config on disk `loadConfig()` returns
+ * DEFAULT_CONFIG, whose baseURL is the DEV deployment — so a postinstall would
+ * quietly bind the machine to dev, and the first `skrr login` against
+ * production would produce exactly the split. That is the default path on a
+ * clean machine, not an edge case.
+ *
+ * Login is the first moment the answer exists. It is also where the credential
+ * handoff already runs, so this is not a new path through the program; it is
+ * the branch where that path used to give up.
+ *
+ * ## Why it asks
+ *
+ * Signing in and "run a process on this machine that can execute bash, read and
+ * write files, and drive a browser" are not the same size of decision. Doing
+ * the second as a silent consequence of the first is the class of surprise this
+ * whole area has been removing. So: asked when there is someone to ask, skipped
+ * with an instruction when there is not, and never on the opt-out.
+ */
+import { confirm } from './prompt';
+export interface DaemonSetupOutcome {
+    status: 'installed' | 'declined' | 'skipped' | 'failed';
+    detail: string;
+}
+export interface DaemonSetupOptions {
+    env?: NodeJS.ProcessEnv;
+    /** True when only the OS service is missing and the binary is already here. */
+    binaryPresent?: boolean;
+    /** Injected by tests. */
+    confirmImpl?: typeof confirm;
+    interactive?: boolean;
+    log?: (line: string) => void;
+}
+/**
+ * Ask, then install. Returns without touching anything when there is nobody to
+ * ask or the operator has opted out.
+ */
+export declare function offerDaemonSetup(opts?: DaemonSetupOptions): Promise<DaemonSetupOutcome>;