@skrr-ai/cli 0.1.8

package/dist/lib/sky-code.d.ts

@@ -0,0 +1,240 @@
+/**
+ * WL-2.2 — locate and forward to the local `sky-code` engine.
+ *
+ * The same `gh → git` shape `exec-oversky.ts` uses, for the same reason: the
+ * Sky CLI is a REST client, the engine is a separately-built, separately-
+ * released binary with its own lifetime and failure model. Unifying them at
+ * the command surface (`skrr code`) gives users one thing to type without
+ * coupling the two release cycles.
+ *
+ * The naming constraint from the plan (§3) is load-bearing and easy to get
+ * wrong: skrr already publishes `oversky` (daemon) and `skrr` (control
+ * plane). This must NOT become a third top-level executable. `sky-code` is an
+ * internal binary name; `skrr code` is the only public entry point.
+ */
+/** Env override, mirroring the daemon's `OVERSKY_SKY_CODE_PATH`. */
+export declare const ENGINE_PATH_ENV = "OVERSKY_SKY_CODE_PATH";
+/**
+ * The engine's user-state root. skrr Code's child of skrr's `~/.skrr/`.
+ *
+ * Honours `OVERSKY_CONFIG_DIR`, the same root override the daemon reads
+ * (`daemon/src/bun-entry.ts`). Without it the CLI would keep looking under
+ * `$HOME` for a user who relocated their skrr root, and would resolve a
+ * different engine than the daemon — the exact divergence the managed-first
+ * ordering below exists to prevent.
+ */
+export declare function engineHome(env?: NodeJS.ProcessEnv): string;
+/** The user-level instruction root owned by skrr Code. */
+export declare function skyCodeInstructionHome(env?: NodeJS.ProcessEnv): string;
+/**
+ * The managed install location — where the daemon, the Desktop app, and
+ * `scripts/sky-code/build.mjs --install` all put the engine.
+ */
+export declare function managedEnginePath(exeName: string, env?: NodeJS.ProcessEnv): string;
+export interface EngineResolution {
+    path: string | null;
+    source: 'env' | 'path' | 'managed' | 'fallback' | 'unresolved';
+}
+/**
+ * Resolve the engine binary, reporting WHERE it came from.
+ *
+ * The source is not decoration — `skrr code doctor` prints it, and "which
+ * binary am I actually running" is the first question when a managed session
+ * and an interactive session behave differently.
+ *
+ * `env` is checked first and is absolute-only. A relative `OVERSKY_SKY_CODE_PATH`
+ * would resolve against the caller's cwd, which for an agent-invoked command is
+ * attacker-influenced: a repo containing `./sky-code` could hijack the engine.
+ *
+ * **Order: env → managed → PATH → well-known (WL-6.2).**
+ *
+ * The managed location beating `PATH` is the load-bearing part, and it is a
+ * deliberate reversal of the obvious ordering.
+ *
+ * WL-6.2's acceptance criterion is that "Desktop-bundled and standalone
+ * installations resolve the same version deterministically". With `PATH` first
+ * they do not: a Desktop app that ships a pinned, signed engine into
+ * `~/.skrr/sky-code/bin` silently loses to whatever `sky-code` happens to sit
+ * earlier on the user's `PATH` — a months-old dev build, a Homebrew copy of a
+ * different version, a shim from an uninstalled package manager. The user sees
+ * one product and gets two engines depending on their shell, and the daemon
+ * (which resolves managed-first) and the CLI disagree about what is running.
+ *
+ * So: if skrr installed an engine, that is the engine. `PATH` remains the
+ * answer for a standalone install where nothing is managed, and the explicit
+ * env override still beats everything — which is the escape hatch for the
+ * developer case this ordering would otherwise make awkward.
+ *
+ * `skrr code doctor` prints the winning `source`, so a surprising resolution is
+ * one command away from being explained rather than being a mystery.
+ */
+export declare function resolveEngine(env?: NodeJS.ProcessEnv): EngineResolution;
+/**
+ * Build the engine argv for a `skrr code` invocation.
+ *
+ * Exported and pure so the forwarding contract is unit-testable without an
+ * oclif runtime or a real binary — the convention `buildOverskyLogsArgs` uses.
+ *
+ * `subcommand === null` means bare `skrr code`, which launches the interactive
+ * TUI: the engine takes no subcommand for that, and passing one would put it
+ * into a mode the user did not ask for.
+ */
+export declare function buildEngineArgs(subcommand: string | null, passthrough: readonly string[]): string[];
+/**
+ * Message shown when no engine is installed.
+ *
+ * Points at the DAEMON's managed installer rather than at a package manager.
+ * The earlier version of this text offered `brew install
+ * dush1023/oversky/sky-code` and `curl .../sky-code/install.sh | bash`; neither
+ * exists — the tap carries only the `oversky` formula and the feed serves no
+ * install script — so a user following it hit a 404 and a 403 and reasonably
+ * concluded the engine was not real.
+ *
+ * The managed path is also the only one that establishes provenance: it
+ * verifies the signed manifest and writes the sidecar the daemon reads before
+ * it will hand the engine a platform credential. A hand-placed binary works, and
+ * since the owner decision of 2026-08-11 it runs at the SAME tier as a managed
+ * one — the daemon's floor for `sky-code` is Tier 1 regardless of provenance
+ * (OSK-3894; this said "stays at Tier 2"). The managed path is still the
+ * recommendation, but the reason is now "you can prove which bytes ran" rather
+ * than "otherwise you get a weaker credential".
+ *
+ * Keep this in step with what actually ships. An install instruction that does
+ * not work is worse than none: it moves the failure from "I could not find how
+ * to install it" to "I did what it said and it broke".
+ */
+export declare function notInstalledMessage(): string;
+/**
+ * Spawn the engine with stdio inherited, resolving with its exit code.
+ *
+ * stdio inheritance is required, not incidental: the engine is a TUI, and
+ * piping its stdio would break the terminal it is trying to draw. It is also
+ * what makes `skrr code acp` usable — the daemon speaks ACP over the engine's
+ * stdin/stdout, so anything in between would corrupt the protocol.
+ */
+/**
+ * How the engine's run ENDED, for hooks that tear down what `prepare` acquired.
+ *
+ * `interrupted` exists because the server's lease-release endpoint takes a
+ * reason from a fixed allow-list, and "the human hit Ctrl-C" is a different
+ * operational fact from "the session finished" — an operator greps those. It is
+ * true when a signal reached this process while the engine ran OR when the
+ * engine itself died on one; a SIGKILL from the OOM killer therefore reads as an
+ * interrupt, which is the honest answer at this altitude (something stopped the
+ * run from outside).
+ */
+export interface EngineExitOutcome {
+    interrupted: boolean;
+}
+export interface EngineSpawnOptions {
+    /**
+     * OSK-3892 — run before the engine is spawned, to acquire whatever the child
+     * needs. Returns env to layer over the parent's.
+     *
+     * Async, which is why this function is no longer a bare `new Promise` executor:
+     * that shape cannot `await`, and a managed session has to reach the API before
+     * the engine exists.
+     */
+    prepare?: () => Promise<Record<string, string>>;
+    /** Always run, on every exit path. Tear down anything `prepare` created. */
+    cleanup?: (outcome: EngineExitOutcome) => Promise<void>;
+    /**
+     * OSK-3892 — the final argv, recomputed AFTER `prepare`.
+     *
+     * Needed because a managed session learns its MODEL from the server: the lease
+     * binds exactly one, the broker refuses any other, and a standalone CLI has no
+     * ACP handshake to convey it — so the admitted model has to reach the engine as
+     * its own `--model` flag, and it is not known until `prepare` has run.
+     *
+     * A hook rather than a mutable array: `prepare` reaching back into the caller's
+     * `args` would work by reference and be invisible at this call site, which is
+     * the kind of coupling that survives a refactor as a silent bug.
+     */
+    finalizeArgs?: (args: string[]) => string[];
+    /**
+     * Which credential this run uses — DECLARED by whoever prepared it, never
+     * inferred from `prepare`'s env.
+     *
+     * This is the gate on re-admitting the operator's ambient provider keys, so it
+     * is security-relevant and must not be guessable. The first cut read the
+     * managed marker back out of the returned env map, which is wrong twice: the
+     * producer of that marker is a DIFFERENT module (the broker package writes it;
+     * this file read it through a second, independent copy of the string), and a
+     * missing marker fell into the BYOK branch — the fail-OPEN direction, handing
+     * a managed engine the user's real `ANTHROPIC_API_KEY` alongside a loopback
+     * base URL.
+     *
+     * The managed hooks answer it from their own live session handle, which is
+     * exactly the condition under which re-admission is dangerous: a broker is
+     * running and a loopback base URL is set. Absent, the run is BYOK — correct for
+     * every caller that never attempts acquisition, and harmless because no broker
+     * exists to be shadowed.
+     */
+    credentialMode?: () => 'managed' | 'byok';
+}
+/**
+ * The provider credentials this environment offers a BYOK run, by name.
+ *
+ * Exported because two callers need ONE answer to "does this machine have a
+ * provider key at all": this module, to decide what the engine inherits, and the
+ * BYOK fallback line in `sky-code-broker.ts`, which used to promise "continuing
+ * with your own provider credentials" on a machine that had none (invariant I4 —
+ * managed, BYOK and offline must never be confused). Two definitions of that
+ * question is how the promise and the reality drift apart.
+ */
+export declare function inheritedProviderCredentials(env: NodeJS.ProcessEnv): Record<string, string>;
+/** Whether an unmanaged run has anything to authenticate with. */
+export declare function hasProviderCredential(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * The environment the engine actually receives.
+ *
+ * ── Invariant I1: no cloud-reusable credential enters the engine ────────────
+ *
+ * The engine is a model-driven process with tool execution, and it opens
+ * repositories authored by other people. It used to receive `process.env`
+ * VERBATIM, so `OVERSKY_TOKEN` — the platform credential the acquisition itself
+ * authenticates with, which authorizes every `/api/*` call as the human — was
+ * one `printenv` away from a repository plugin. `daemon/src/backends/acp.ts`
+ * spawns THE SAME binary through `sanitizeSpawnEnv` and always has; the CLI
+ * simply had no equivalent.
+ *
+ * ── Why BYOK re-admits what the sanitizer just stripped ────────────────────
+ *
+ * The shared sanitizer is written for a parent that delivers a child's model
+ * credential explicitly (`cred.env`, after the daemon's trust gate), so it
+ * strips provider keys. `skrr code` has a second supported mode where ambient
+ * inheritance IS the design: BYOK, where the user's own key is exactly what the
+ * run is meant to spend. Stripping it there would not harden anything — it would
+ * turn every unmanaged run into an opaque provider auth error while the CLI
+ * cheerfully announced it was "continuing with your own provider credentials".
+ *
+ * So the layering is: sanitized parent → the user's own model credential (BYOK
+ * only) → `extraEnv`. `extraEnv` is LAST for the reason it always was: a managed
+ * session's relay values must OVERWRITE an inherited key rather than lose to it.
+ * And a managed run re-admits nothing, which closes the other half of the defect
+ * — the broker sets `ANTHROPIC_AUTH_TOKEN`, so a surviving real
+ * `ANTHROPIC_API_KEY` gave the engine's Anthropic adapter a live `x-api-key` to
+ * prefer over the loopback bearer, and every turn could 401 inside a session the
+ * user was told was managed.
+ *
+ * DECLARED by the caller (`EngineSpawnOptions.credentialMode`), not detected.
+ *
+ * This paragraph used to describe reading the broker's managed marker back out
+ * of the environment `prepare` returned. That design was replaced precisely
+ * because it was wrong twice over: the marker is written by a DIFFERENT module,
+ * and a missing marker fell into the BYOK branch — the fail-OPEN direction,
+ * handing a live managed session the user's real `ANTHROPIC_API_KEY` next to a
+ * loopback base URL. The mode is now answered from the broker session handle,
+ * the presence of a broker being exactly the condition that makes inheritance
+ * dangerous: a security-relevant branch may not be decided by sniffing a value
+ * some other module wrote into a shared namespace.
+ *
+ * One sharp edge to know about before adding a subcommand: the shared sanitizer
+ * strips anything ending in `_PASSWORD`, which includes the engine's own
+ * `SKY_CODE_SERVER_PASSWORD` (Basic auth for `sky-code serve` / `web`). No
+ * `skrr code` subcommand reaches those today — they are run against the engine
+ * binary directly — so nothing regresses; a future `skrr code serve` would have to
+ * pass that credential deliberately rather than rely on inheritance.
+ */
+export declare function engineSpawnEnv(env: NodeJS.ProcessEnv, extraEnv: Record<string, string>, mode: 'managed' | 'byok'): NodeJS.ProcessEnv;
+export declare function execEngine(args: string[], env?: NodeJS.ProcessEnv, options?: EngineSpawnOptions): Promise<number>;

package/dist/lib/sky-code.js

@@ -0,0 +1,410 @@
+"use strict";
+/**
+ * WL-2.2 — locate and forward to the local `sky-code` engine.
+ *
+ * The same `gh → git` shape `exec-oversky.ts` uses, for the same reason: the
+ * Sky CLI is a REST client, the engine is a separately-built, separately-
+ * released binary with its own lifetime and failure model. Unifying them at
+ * the command surface (`skrr code`) gives users one thing to type without
+ * coupling the two release cycles.
+ *
+ * The naming constraint from the plan (§3) is load-bearing and easy to get
+ * wrong: skrr already publishes `oversky` (daemon) and `skrr` (control
+ * plane). This must NOT become a third top-level executable. `sky-code` is an
+ * internal binary name; `skrr code` is the only public entry point.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ENGINE_PATH_ENV = void 0;
+exports.engineHome = engineHome;
+exports.skyCodeInstructionHome = skyCodeInstructionHome;
+exports.managedEnginePath = managedEnginePath;
+exports.resolveEngine = resolveEngine;
+exports.buildEngineArgs = buildEngineArgs;
+exports.notInstalledMessage = notInstalledMessage;
+exports.inheritedProviderCredentials = inheritedProviderCredentials;
+exports.hasProviderCredential = hasProviderCredential;
+exports.engineSpawnEnv = engineSpawnEnv;
+exports.execEngine = execEngine;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = __importDefault(require("node:path"));
+const auth_core_1 = require("@skrr-ai/auth-core");
+// Deliberately does NOT import the managed marker any more. This module used to
+// read it to decide whether a run was managed; that decision now arrives as a
+// declared `credentialMode`, and re-introducing the import here would be the first
+// step back toward inferring a security-relevant fact from a string.
+/** Env override, mirroring the daemon's `OVERSKY_SKY_CODE_PATH`. */
+exports.ENGINE_PATH_ENV = 'OVERSKY_SKY_CODE_PATH';
+/**
+ * The engine's user-state root. skrr Code's child of skrr's `~/.skrr/`.
+ *
+ * Honours `OVERSKY_CONFIG_DIR`, the same root override the daemon reads
+ * (`daemon/src/bun-entry.ts`). Without it the CLI would keep looking under
+ * `$HOME` for a user who relocated their skrr root, and would resolve a
+ * different engine than the daemon — the exact divergence the managed-first
+ * ordering below exists to prevent.
+ */
+function engineHome(env = process.env) {
+    const root = env.OVERSKY_CONFIG_DIR?.trim();
+    return node_path_1.default.join(root || node_path_1.default.join((0, node_os_1.homedir)(), '.skrr'), 'sky-code');
+}
+/** The user-level instruction root owned by skrr Code. */
+function skyCodeInstructionHome(env = process.env) {
+    const configured = env.SKY_CODE_HOME?.trim();
+    if (!configured)
+        return node_path_1.default.join((0, node_os_1.homedir)(), '.skrr', 'sky-code');
+    if (configured === '~')
+        return (0, node_os_1.homedir)();
+    if (configured.startsWith('~/'))
+        return node_path_1.default.join((0, node_os_1.homedir)(), configured.slice(2));
+    return node_path_1.default.resolve(configured);
+}
+/**
+ * The managed install location — where the daemon, the Desktop app, and
+ * `scripts/sky-code/build.mjs --install` all put the engine.
+ */
+function managedEnginePath(exeName, env = process.env) {
+    return node_path_1.default.join(engineHome(env), 'bin', exeName);
+}
+/**
+ * Unmanaged well-known locations, checked after PATH.
+ *
+ * These are standalone installs — Homebrew, a curl script, a hand-copied
+ * binary. They are the fallback, not the intent.
+ */
+function fallbackPaths(exeName) {
+    return [
+        node_path_1.default.join('/opt/homebrew/bin', exeName),
+        node_path_1.default.join('/usr/local/bin', exeName),
+        node_path_1.default.join((0, node_os_1.homedir)(), '.local', 'bin', exeName),
+    ];
+}
+function isExecutable(p) {
+    try {
+        (0, node_fs_1.accessSync)(p, node_fs_1.constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolve the engine binary, reporting WHERE it came from.
+ *
+ * The source is not decoration — `skrr code doctor` prints it, and "which
+ * binary am I actually running" is the first question when a managed session
+ * and an interactive session behave differently.
+ *
+ * `env` is checked first and is absolute-only. A relative `OVERSKY_SKY_CODE_PATH`
+ * would resolve against the caller's cwd, which for an agent-invoked command is
+ * attacker-influenced: a repo containing `./sky-code` could hijack the engine.
+ *
+ * **Order: env → managed → PATH → well-known (WL-6.2).**
+ *
+ * The managed location beating `PATH` is the load-bearing part, and it is a
+ * deliberate reversal of the obvious ordering.
+ *
+ * WL-6.2's acceptance criterion is that "Desktop-bundled and standalone
+ * installations resolve the same version deterministically". With `PATH` first
+ * they do not: a Desktop app that ships a pinned, signed engine into
+ * `~/.skrr/sky-code/bin` silently loses to whatever `sky-code` happens to sit
+ * earlier on the user's `PATH` — a months-old dev build, a Homebrew copy of a
+ * different version, a shim from an uninstalled package manager. The user sees
+ * one product and gets two engines depending on their shell, and the daemon
+ * (which resolves managed-first) and the CLI disagree about what is running.
+ *
+ * So: if skrr installed an engine, that is the engine. `PATH` remains the
+ * answer for a standalone install where nothing is managed, and the explicit
+ * env override still beats everything — which is the escape hatch for the
+ * developer case this ordering would otherwise make awkward.
+ *
+ * `skrr code doctor` prints the winning `source`, so a surprising resolution is
+ * one command away from being explained rather than being a mystery.
+ */
+function resolveEngine(env = process.env) {
+    const exeName = process.platform === 'win32' ? 'sky-code.exe' : 'sky-code';
+    const override = env[exports.ENGINE_PATH_ENV];
+    if (override && override.trim()) {
+        const candidate = override.trim();
+        if (!node_path_1.default.isAbsolute(candidate))
+            return { path: null, source: 'unresolved' };
+        return isExecutable(candidate)
+            ? { path: candidate, source: 'env' }
+            : { path: null, source: 'unresolved' };
+    }
+    const managed = managedEnginePath(exeName, env);
+    if (isExecutable(managed))
+        return { path: managed, source: 'managed' };
+    const PATH = env.PATH ?? '';
+    const sep = process.platform === 'win32' ? ';' : ':';
+    const exeNames = process.platform === 'win32' ? ['sky-code.exe', 'sky-code.cmd'] : ['sky-code'];
+    for (const dir of PATH.split(sep)) {
+        if (!dir)
+            continue;
+        for (const name of exeNames) {
+            const candidate = node_path_1.default.join(dir, name);
+            if (isExecutable(candidate))
+                return { path: candidate, source: 'path' };
+        }
+    }
+    for (const candidate of fallbackPaths(exeName)) {
+        if (isExecutable(candidate))
+            return { path: candidate, source: 'fallback' };
+    }
+    return { path: null, source: 'unresolved' };
+}
+/**
+ * Build the engine argv for a `skrr code` invocation.
+ *
+ * Exported and pure so the forwarding contract is unit-testable without an
+ * oclif runtime or a real binary — the convention `buildOverskyLogsArgs` uses.
+ *
+ * `subcommand === null` means bare `skrr code`, which launches the interactive
+ * TUI: the engine takes no subcommand for that, and passing one would put it
+ * into a mode the user did not ask for.
+ */
+function buildEngineArgs(subcommand, passthrough) {
+    return subcommand === null ? [...passthrough] : [subcommand, ...passthrough];
+}
+/**
+ * Message shown when no engine is installed.
+ *
+ * Points at the DAEMON's managed installer rather than at a package manager.
+ * The earlier version of this text offered `brew install
+ * dush1023/oversky/sky-code` and `curl .../sky-code/install.sh | bash`; neither
+ * exists — the tap carries only the `oversky` formula and the feed serves no
+ * install script — so a user following it hit a 404 and a 403 and reasonably
+ * concluded the engine was not real.
+ *
+ * The managed path is also the only one that establishes provenance: it
+ * verifies the signed manifest and writes the sidecar the daemon reads before
+ * it will hand the engine a platform credential. A hand-placed binary works, and
+ * since the owner decision of 2026-08-11 it runs at the SAME tier as a managed
+ * one — the daemon's floor for `sky-code` is Tier 1 regardless of provenance
+ * (OSK-3894; this said "stays at Tier 2"). The managed path is still the
+ * recommendation, but the reason is now "you can prove which bytes ran" rather
+ * than "otherwise you get a weaker credential".
+ *
+ * Keep this in step with what actually ships. An install instruction that does
+ * not work is worse than none: it moves the failure from "I could not find how
+ * to install it" to "I did what it said and it broke".
+ */
+function notInstalledMessage() {
+    return [
+        'The skrr Code engine (`sky-code`) is not installed on this machine.',
+        '',
+        'Install it through the daemon, which verifies the signed release:',
+        '  • In the web app: the runtime menu beside the chat input → skrr Code → Install',
+        '  • Make sure a daemon is running here first: `oversky status`',
+        '',
+        `Or point the CLI at an existing build:  export ${exports.ENGINE_PATH_ENV}=/absolute/path/to/sky-code`,
+        '  (an unsigned build runs, and since 2026-08-11 at the same trust tier as a',
+        '   signed one — see `skrr code doctor` under trust-tier)',
+        '',
+        'Run `skrr code doctor` for a full diagnosis, including which channel this',
+        'machine follows and whether that channel has a published release.',
+    ].join('\n');
+}
+/**
+ * Credential-shaped variables the engine may inherit as its OWN model credential.
+ *
+ * The suffix rule rather than a provider list, for the reason `SENSITIVE_ENV_SUFFIXES`
+ * gives: a list is never complete, and here an omission would silently break a
+ * BYOK user of whichever provider was forgotten. `HUGGINGFACE_HUB_TOKEN` is named
+ * because it is the one provider variable in the shared deny-list that matches no
+ * credential suffix.
+ */
+const BYOK_CREDENTIAL_SUFFIXES = ['_API_KEY', '_AUTH_TOKEN'];
+const BYOK_CREDENTIAL_NAMES = new Set(['HUGGINGFACE_HUB_TOKEN']);
+/**
+ * …and these are never inherited, whatever they look like.
+ *
+ * The shared deny-list mixes two classes: PLATFORM credentials (skrr's own
+ * token, an AWS role, a package-publish token, the gateway master key) and MODEL
+ * credentials. Only the second class is ever something a `skrr code` run is
+ * supposed to spend, so only the second class comes back below. `OVERSKY_TOKEN`
+ * is the one this whole filter exists for and is covered twice — by name and by
+ * the `OVERSKY_` prefix — on purpose.
+ */
+const ENGINE_NEVER_INHERITS = new Set([
+    'OVERSKY_TOKEN',
+    'CLAUDE_CODE_OAUTH_TOKEN',
+    'LITELLM_MASTER_KEY',
+    'GH_TOKEN',
+    'GITHUB_TOKEN',
+    'NPM_TOKEN',
+]);
+const ENGINE_NEVER_INHERITS_PREFIXES = ['OVERSKY_', 'AWS_'];
+/**
+ * The provider credentials this environment offers a BYOK run, by name.
+ *
+ * Exported because two callers need ONE answer to "does this machine have a
+ * provider key at all": this module, to decide what the engine inherits, and the
+ * BYOK fallback line in `sky-code-broker.ts`, which used to promise "continuing
+ * with your own provider credentials" on a machine that had none (invariant I4 —
+ * managed, BYOK and offline must never be confused). Two definitions of that
+ * question is how the promise and the reality drift apart.
+ */
+function inheritedProviderCredentials(env) {
+    const out = {};
+    for (const [key, value] of Object.entries(env)) {
+        if (typeof value !== 'string' || !value)
+            continue;
+        if (ENGINE_NEVER_INHERITS.has(key))
+            continue;
+        if (ENGINE_NEVER_INHERITS_PREFIXES.some((prefix) => key.startsWith(prefix)))
+            continue;
+        if (BYOK_CREDENTIAL_NAMES.has(key) || BYOK_CREDENTIAL_SUFFIXES.some((s) => key.endsWith(s))) {
+            out[key] = value;
+        }
+    }
+    return out;
+}
+/** Whether an unmanaged run has anything to authenticate with. */
+function hasProviderCredential(env = process.env) {
+    return Object.keys(inheritedProviderCredentials(env)).length > 0;
+}
+/**
+ * The environment the engine actually receives.
+ *
+ * ── Invariant I1: no cloud-reusable credential enters the engine ────────────
+ *
+ * The engine is a model-driven process with tool execution, and it opens
+ * repositories authored by other people. It used to receive `process.env`
+ * VERBATIM, so `OVERSKY_TOKEN` — the platform credential the acquisition itself
+ * authenticates with, which authorizes every `/api/*` call as the human — was
+ * one `printenv` away from a repository plugin. `daemon/src/backends/acp.ts`
+ * spawns THE SAME binary through `sanitizeSpawnEnv` and always has; the CLI
+ * simply had no equivalent.
+ *
+ * ── Why BYOK re-admits what the sanitizer just stripped ────────────────────
+ *
+ * The shared sanitizer is written for a parent that delivers a child's model
+ * credential explicitly (`cred.env`, after the daemon's trust gate), so it
+ * strips provider keys. `skrr code` has a second supported mode where ambient
+ * inheritance IS the design: BYOK, where the user's own key is exactly what the
+ * run is meant to spend. Stripping it there would not harden anything — it would
+ * turn every unmanaged run into an opaque provider auth error while the CLI
+ * cheerfully announced it was "continuing with your own provider credentials".
+ *
+ * So the layering is: sanitized parent → the user's own model credential (BYOK
+ * only) → `extraEnv`. `extraEnv` is LAST for the reason it always was: a managed
+ * session's relay values must OVERWRITE an inherited key rather than lose to it.
+ * And a managed run re-admits nothing, which closes the other half of the defect
+ * — the broker sets `ANTHROPIC_AUTH_TOKEN`, so a surviving real
+ * `ANTHROPIC_API_KEY` gave the engine's Anthropic adapter a live `x-api-key` to
+ * prefer over the loopback bearer, and every turn could 401 inside a session the
+ * user was told was managed.
+ *
+ * DECLARED by the caller (`EngineSpawnOptions.credentialMode`), not detected.
+ *
+ * This paragraph used to describe reading the broker's managed marker back out
+ * of the environment `prepare` returned. That design was replaced precisely
+ * because it was wrong twice over: the marker is written by a DIFFERENT module,
+ * and a missing marker fell into the BYOK branch — the fail-OPEN direction,
+ * handing a live managed session the user's real `ANTHROPIC_API_KEY` next to a
+ * loopback base URL. The mode is now answered from the broker session handle,
+ * the presence of a broker being exactly the condition that makes inheritance
+ * dangerous: a security-relevant branch may not be decided by sniffing a value
+ * some other module wrote into a shared namespace.
+ *
+ * One sharp edge to know about before adding a subcommand: the shared sanitizer
+ * strips anything ending in `_PASSWORD`, which includes the engine's own
+ * `SKY_CODE_SERVER_PASSWORD` (Basic auth for `sky-code serve` / `web`). No
+ * `skrr code` subcommand reaches those today — they are run against the engine
+ * binary directly — so nothing regresses; a future `skrr code serve` would have to
+ * pass that credential deliberately rather than rely on inheritance.
+ */
+function engineSpawnEnv(env, extraEnv, 
+// Required, not defaulted: the safe value differs per call and a parameter that
+// can be forgotten on a security boundary will be.
+mode) {
+    return {
+        ...(0, auth_core_1.sanitizeSpawnEnv)(env),
+        ...(mode === 'managed' ? {} : inheritedProviderCredentials(env)),
+        ...extraEnv,
+    };
+}
+async function execEngine(args, env = process.env, options = {}) {
+    // Resolve the binary FIRST, before `prepare` runs.
+    //
+    // Order matters: a caller learns "not installed" from here, and starting a
+    // broker before this check would leak a socket and a live credential for an
+    // engine that never runs.
+    const { path: bin } = resolveEngine(env);
+    if (!bin)
+        throw new Error('sky-code-not-installed');
+    const extraEnv = options.prepare ? await options.prepare() : {};
+    // A copy, so a hook cannot mutate the caller's array as a side effect.
+    const spawnArgs = options.finalizeArgs ? options.finalizeArgs([...args]) : args;
+    // 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 };
+    // Read AFTER `prepare`, because that is when the hook knows what it acquired.
+    const mode = options.credentialMode?.() ?? 'byok';
+    try {
+        return await spawnEngine(bin, spawnArgs, env, extraEnv, mode, outcome);
+    }
+    finally {
+        // In a `finally` rather than on `exit`, so a spawn error and a Ctrl-C both
+        // release what `prepare` acquired. The socket directory outliving the
+        // process is the failure this closes.
+        await options.cleanup?.(outcome);
+    }
+}
+function spawnEngine(bin, args, env, extraEnv, mode, 
+// Written into rather than returned, so the `finally` above can read it on
+// every path — including one where this promise rejects.
+outcome) {
+    return new Promise((resolve, reject) => {
+        const isWinShim = process.platform === 'win32' && /\.(cmd|bat)$/i.test(bin);
+        const child = (0, node_child_process_1.spawn)(bin, args, {
+            stdio: 'inherit',
+            env: engineSpawnEnv(env, extraEnv, mode),
+            ...(isWinShim ? { shell: true } : {}),
+        });
+        // `stdio: 'inherit'` puts the child in this process group, so Ctrl-C reaches
+        // both and the child exits on its own. These handlers exist so the CLI's own
+        // `finally` still runs when the signal arrives here first — without them the
+        // process can die with a socket directory still on disk.
+        const onSignal = (signal) => () => {
+            outcome.interrupted = true;
+            if (!child.killed)
+                child.kill(signal);
+        };
+        const onInt = onSignal('SIGINT');
+        const onTerm = onSignal('SIGTERM');
+        process.once('SIGINT', onInt);
+        process.once('SIGTERM', onTerm);
+        const detach = () => {
+            process.off('SIGINT', onInt);
+            process.off('SIGTERM', onTerm);
+        };
+        child.on('error', (err) => {
+            detach();
+            reject(err);
+        });
+        child.on('exit', (code, signal) => {
+            detach();
+            if (signal) {
+                // Something outside the run stopped it — the user, a supervisor, the OOM
+                // killer. The distinction the release ledger cares about is "ended" vs
+                // "interrupted", and all three are the latter.
+                outcome.interrupted = true;
+                const map = {
+                    SIGINT: 2,
+                    SIGQUIT: 3,
+                    SIGKILL: 9,
+                    SIGTERM: 15,
+                };
+                resolve(128 + (map[signal] ?? 0));
+                return;
+            }
+            resolve(code ?? 0);
+        });
+    });
+}