@skrr-ai/cli 0.1.28 → 0.1.29

package/dist/lib/dedicated-wait.js

@@ -32,8 +32,26 @@ function progressOf(lease) {
  * reading that cannot turn into the goal without someone acting again; anything
  * that might still settle is `pending`, and the caller's timeout decides how long
  * that is worth watching.
+ *
+ * Reaching the goal is not the end of the wait while the lease's operation is
+ * still in progress: `--wait` promises the operation has FINISHED, and the
+ * server refuses the next one until it has. A create read `ready` the moment its
+ * guest registered and returned, and the restart that followed was refused for
+ * minutes (OSK-8775). A server that does not report the operation is judged on
+ * the goal alone, as before.
  */
 function evaluateDedicatedWait(goal, lease) {
+    const verdict = evaluateDedicatedWaitGoal(goal, lease);
+    if (verdict.status !== 'done' || lease?.operation?.status !== 'in_progress') {
+        return verdict;
+    }
+    const action = lease.operation.action;
+    return {
+        status: 'pending',
+        progress: `${progressOf(lease)} · ${action ? `${action} ` : 'operation '}still finishing`,
+    };
+}
+function evaluateDedicatedWaitGoal(goal, lease) {
     if (!lease) {
         return { status: 'failed', reason: 'the lease is no longer visible' };
     }
@@ -89,6 +107,40 @@ function evaluateDedicatedWait(goal, lease) {
                 reason: `the snapshot ended (${state}) without recording a new recovery point`,
             };
         }
+        case 'image_updated': {
+            // Running says nothing: a machine returned to its previous image runs too.
+            // The update's own record does, once the platform has judged it — and only
+            // an update that started after the request (the 202 carries the one before).
+            if (DEAD_STATES.has(state) || state === 'archived' || state === 'terminating') {
+                return { status: 'failed', reason: `the machine is ${state}` };
+            }
+            const last = lease.health?.image?.lastUpdate;
+            const fresh = Boolean(last?.startedAt) && last?.startedAt !== goal.previousUpdateStartedAt;
+            if (fresh && last?.status === 'succeeded' && RUNNING_STATES.has(state)) {
+                return { status: 'done' };
+            }
+            // Nothing was left to move by the time the update ran (the image it was
+            // asked for stopped being newer): the machine is back, as it was.
+            if (!fresh && RUNNING_STATES.has(state) && lease.health?.image?.updateAvailable === false) {
+                return { status: 'done' };
+            }
+            if (fresh && (last?.status === 'rolled_back' || last?.status === 'failed')) {
+                return {
+                    status: 'failed',
+                    reason: last.status === 'rolled_back'
+                        ? 'the current image did not come back healthy; the machine is back on its previous image, files kept'
+                        : 'the update did not complete on either image; files are kept',
+                };
+            }
+            let moving = 'update requested';
+            if (fresh) {
+                moving =
+                    last?.status === 'rolling_back'
+                        ? 'returning to the previous image'
+                        : 'moving onto the current image';
+            }
+            return { status: 'pending', progress: `${progressOf(lease)} · ${moving}` };
+        }
         case 'grown': {
             const size = lease.resources?.storageGb;
             if (typeof size === 'number' && size >= goal.storageGb)

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

@@ -38,9 +38,20 @@ export interface DeviceCodePollerOptions {
     onStart?: (start: DeviceCodeStart) => void;
     /**
      * Called on every poll tick before the HTTP call. Returns false to
-     * cancel — used so SIGINT can break the loop without leaking timers.
+     * cancel.
      */
     shouldContinue?: () => boolean;
+    /**
+     * Cancels the poll at once — the request in flight and the wait between
+     * ticks — with DeviceCodeLoginCancelledError. What Ctrl-C uses.
+     */
+    signal?: AbortSignal;
+}
+/** The person stopped waiting for approval. Exits 130, as the Ctrl-C that caused it would. */
+export declare class DeviceCodeLoginCancelledError extends Error {
+    readonly code = "LOGIN_CANCELLED";
+    readonly exitCode = 130;
+    constructor();
 }
 /**
  * Issue a device code from the server.

package/dist/lib/device-code.js

@@ -21,12 +21,23 @@
  *     → 404 { error: 'Device code expired or not found' }
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.DeviceCodeLoginCancelledError = void 0;
 exports.startDeviceCode = startDeviceCode;
 exports.pollDeviceCode = pollDeviceCode;
 exports.revokeDeviceRefreshToken = revokeDeviceRefreshToken;
 const DEFAULT_POLL_INTERVAL_MS = 2_000;
 /** Server-side TTL is 300s; we add a small safety margin for clock drift. */
 const DEFAULT_OVERALL_TIMEOUT_MS = 320_000;
+/** The person stopped waiting for approval. Exits 130, as the Ctrl-C that caused it would. */
+class DeviceCodeLoginCancelledError extends Error {
+    code = 'LOGIN_CANCELLED';
+    exitCode = 130;
+    constructor() {
+        super('Login cancelled before the device code was approved; nothing was saved.');
+        this.name = 'DeviceCodeLoginCancelledError';
+    }
+}
+exports.DeviceCodeLoginCancelledError = DeviceCodeLoginCancelledError;
 /**
  * Issue a device code from the server.
  *
@@ -69,18 +80,21 @@ async function pollDeviceCode(baseURL, code, opts = {}) {
     const interval = opts.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
     const timeout = opts.overallTimeoutMs ?? DEFAULT_OVERALL_TIMEOUT_MS;
     const shouldContinue = opts.shouldContinue ?? (() => true);
+    const { signal } = opts;
     const deadline = Date.now() + timeout;
     while (Date.now() < deadline) {
-        if (!shouldContinue()) {
-            throw new Error('Device-code login cancelled');
+        if (signal?.aborted || !shouldContinue()) {
+            throw new DeviceCodeLoginCancelledError();
         }
         let res;
         try {
-            res = await fetch(`${baseURL.replace(/\/$/, '')}/api/daemons/device-code/${encodeURIComponent(code)}/status`, { method: 'GET', headers: { Accept: 'application/json' } });
+            res = await fetch(`${baseURL.replace(/\/$/, '')}/api/daemons/device-code/${encodeURIComponent(code)}/status`, { method: 'GET', headers: { Accept: 'application/json' }, ...(signal ? { signal } : {}) });
         }
         catch {
+            if (signal?.aborted)
+                throw new DeviceCodeLoginCancelledError();
             // Transient network error — wait and retry.
-            await sleep(interval);
+            await sleep(interval, signal);
             continue;
         }
         if (res.status === 404) {
@@ -88,21 +102,29 @@ async function pollDeviceCode(baseURL, code, opts = {}) {
         }
         if (res.status === 429) {
             // Server is asking us to slow down. Double the wait this round.
-            await sleep(interval * 2);
+            await sleep(interval * 2, signal);
             continue;
         }
         if (!res.ok) {
             const body = await res.text().catch(() => '');
             throw new Error(`Poll failed: HTTP ${res.status} ${body.slice(0, 200)}`);
         }
-        const data = (await res.json());
+        let data;
+        try {
+            data = (await res.json());
+        }
+        catch (err) {
+            if (signal?.aborted)
+                throw new DeviceCodeLoginCancelledError();
+            throw err;
+        }
         if (data.status === 'approved') {
             if (!('token' in data) || !data.token) {
                 throw new Error('Server reported approval without a token');
             }
             return data;
         }
-        await sleep(interval);
+        await sleep(interval, signal);
     }
     throw new Error('Device-code login timed out waiting for approval');
 }
@@ -133,13 +155,26 @@ async function revokeDeviceRefreshToken(baseURL, refreshToken) {
         clearTimeout(timer);
     }
 }
-function sleep(ms) {
+function sleep(ms, signal) {
     // Do NOT unref — pollDeviceCode is the only thing keeping the event
     // loop alive during device-code login, so an unref'd timer lets Node
     // exit cleanly mid-poll (process exits with code 0 after the first
     // sleep, never reaching approval). Mirrors the same intentional
     // non-unref in loginLocalhost.ts:419.
     return new Promise((resolve) => {
-        setTimeout(resolve, ms);
+        if (signal?.aborted) {
+            resolve();
+            return;
+        }
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', wake);
+            resolve();
+        }, ms);
+        // A cancelled login wakes now; the loop's next check throws.
+        const wake = () => {
+            clearTimeout(timer);
+            resolve();
+        };
+        signal?.addEventListener('abort', wake, { once: true });
     });
 }

package/dist/lib/harnesses.d.ts

@@ -57,6 +57,19 @@ export interface Harness {
      */
     metadata?: Record<string, unknown>;
 }
+/**
+ * A machine's health reason codes as the sentences a person reads, from the
+ * copy map the web renders too (`describeMachineHealthReasons`,
+ * `@skrr-ai/data-provider`). Every CLI surface that explains why a lease cannot
+ * take work goes through this: `machines dedicated` and `harnesses leases show`.
+ *
+ * With the lease `state`, reasons that only follow from a lease at rest or in
+ * transition are left out: an archived machine is archived, and that it has not
+ * checked in is the same fact. A code this build has no words for keeps its code
+ * in parentheses, so the fallback sentence can still be traced. Empty when there
+ * is nothing to say. Scripts read the codes from `--json`, never from this.
+ */
+export declare function describeHealthReasonSentences(reasons: unknown, state?: unknown): string;
 /**
  * One open lease, as `/api/machines/leases` actually returns it.
  *

package/dist/lib/harnesses.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HARNESS_LEASE_ACTIONS = void 0;
+exports.describeHealthReasonSentences = describeHealthReasonSentences;
 exports.listHarnesses = listHarnesses;
 exports.getHarness = getHarness;
 exports.getHarnessModels = getHarnessModels;
@@ -22,7 +23,30 @@ exports.getHarnessLease = getHarnessLease;
 exports.releaseHarnessLease = releaseHarnessLease;
 exports.performHarnessLeaseAction = performHarnessLeaseAction;
 exports.setHarnessLeaseBilling = setHarnessLeaseBilling;
+const data_provider_1 = require("@skrr-ai/data-provider");
 const api_fetch_1 = require("./api-fetch");
+/**
+ * A machine's health reason codes as the sentences a person reads, from the
+ * copy map the web renders too (`describeMachineHealthReasons`,
+ * `@skrr-ai/data-provider`). Every CLI surface that explains why a lease cannot
+ * take work goes through this: `machines dedicated` and `harnesses leases show`.
+ *
+ * With the lease `state`, reasons that only follow from a lease at rest or in
+ * transition are left out: an archived machine is archived, and that it has not
+ * checked in is the same fact. A code this build has no words for keeps its code
+ * in parentheses, so the fallback sentence can still be traced. Empty when there
+ * is nothing to say. Scripts read the codes from `--json`, never from this.
+ */
+function describeHealthReasonSentences(reasons, state) {
+    const { lines } = (0, data_provider_1.describeMachineHealthReasons)(reasons, {
+        state: typeof state === 'string' ? state : undefined,
+    });
+    return lines
+        .map((line) => line.known || line.codes.length === 0
+        ? line.sentence
+        : `${line.sentence.replace(/\.$/, '')} (${line.codes.join(', ')}).`)
+        .join(' ');
+}
 /**
  * Every action `POST /api/machines/leases/:id/actions/:action` accepts —
  * `MACHINE_LEASE_ACTIONS` in MachineLeaseService. Which of them a given lease

package/dist/lib/login.js

@@ -402,16 +402,17 @@ async function runDeviceCode(serverUrl, cliId, reason, ssh, errorMessage) {
         openBrowserPlatform(start.verificationUrl);
     }
     console.log('  Waiting for approval — this command will continue automatically.');
-    let cancelled = false;
-    const onSigint = () => {
-        cancelled = true;
-    };
+    // Ctrl-C stops the wait at once — the status request in flight and the pause
+    // between polls — and the command exits 130 (DeviceCodeLoginCancelledError).
+    // This listener only started running with OSK-8708: auth-core's lock handler
+    // used to exit the process first. A flag checked on the next tick would now
+    // leave Ctrl-C waiting out a poll and ending as an ordinary error.
+    const cancel = new AbortController();
+    const onSigint = () => cancel.abort();
     process.on('SIGINT', onSigint);
     let approved;
     try {
-        approved = await (0, device_code_1.pollDeviceCode)(serverUrl, start.code, {
-            shouldContinue: () => !cancelled,
-        });
+        approved = await (0, device_code_1.pollDeviceCode)(serverUrl, start.code, { signal: cancel.signal });
     }
     finally {
         process.off('SIGINT', onSigint);

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

@@ -50,6 +50,12 @@
  * refusals already carry codes (`model-denied`, `budget-exhausted`,
  * `policy-unavailable`, `session-lease-exists`, …); this module forwards them
  * verbatim and adds its own for the local preconditions.
+ *
+ * The code is also what decides whether there is a fallback at all. A refusal
+ * that is a DECISION about the account (`plan-allowance-exhausted`,
+ * `balance-exhausted`, …) stops the run instead (OSK-8822): switching to the
+ * user's own key because their plan said no is the silent mode switch I4
+ * forbids, and without a key it only starts an engine that cannot run.
  */
 import { buildManagedInferenceRelayCredential, startManagedInferenceBroker, type RenewalStopReason } from '@skrr-ai/inference-broker';
 import { type ApiFetchOptions } from './api-fetch';
@@ -237,10 +243,17 @@ export interface ManagedEngineHooksInput {
  * engine binary FIRST and refuses a missing one before `prepare` runs. Acquiring
  * earlier would mint a lease and open a socket for an engine that never starts.
  *
- * `prepare` cannot throw. `execEngine` awaits it OUTSIDE its try/finally, so a
- * throw here would abort the run and skip `cleanup` — turning "we could not get
- * you a managed session" into the hard failure invariant I4 forbids. Every
- * failure is therefore caught, said once, and answered with `{}` (BYOK).
+ * `prepare` rejects for exactly one reason. Any rejection aborts the run, so a
+ * failure that merely means "we could not get you a managed session" must not
+ * reject — that would be the hard failure invariant I4 forbids. Those are caught,
+ * said once, and answered with `{}` (BYOK).
+ *
+ * The one reason is a refusal that is a DECISION about the account (OSK-8822).
+ * There, starting the engine is the wrong answer whether or not a provider key
+ * exists — with one it silently moves the spend to a different billing boundary
+ * because the plan said no, and without one it starts an engine whose first
+ * request fails — so it is said once and rejected with `EngineStartRefusedError`,
+ * which `execEngine` answers by not spawning at all.
  */
 export declare function createManagedEngineHooks(input: ManagedEngineHooksInput): ManagedEngineHooks;
 /**
@@ -269,5 +282,33 @@ export declare function createManagedEngineHooks(input: ManagedEngineHooksInput)
  * Returns null when there is nothing worth saying.
  */
 export declare function managedRenewalStoppedLine(reason: RenewalStopReason, detail?: string): string | null;
-export declare function managedFallbackLine(err: unknown, env?: NodeJS.ProcessEnv): string;
+export type ManagedAcquisitionFailure = 
+/** The server decided about the account. The engine must not start. */
+{
+    action: 'refuse';
+    code: string;
+    line: string;
+}
+/** Nothing was decided about the account. The run continues without a broker. */
+ | {
+    action: 'fallback';
+    code?: string;
+    line: string;
+};
+/**
+ * What a failed acquisition does next, and the ONE line that says so.
+ *
+ * One function for both because they must never disagree: a line promising
+ * "continuing with your own provider credentials" over a run that was stopped,
+ * or "did not start the engine" over one that started, is the confusion between
+ * managed, BYOK and offline that I4 forbids.
+ *
+ * The line names the machine-readable code as well as the sentence: the codes
+ * are the server's typed refusals (`model-denied`, `budget-exhausted`,
+ * `policy-unavailable` …) and "which of those happened" is the first thing
+ * support asks. It ends by saying what is about to happen instead, reading the
+ * environment for whether "your own key" is a thing that exists here, because
+ * naming the wrong one of managed / BYOK / offline is the same failure.
+ */
+export declare function managedAcquisitionFailure(err: unknown, env?: NodeJS.ProcessEnv): ManagedAcquisitionFailure;
 export {};

package/dist/lib/sky-code-broker.js

@@ -51,6 +51,12 @@
  * refusals already carry codes (`model-denied`, `budget-exhausted`,
  * `policy-unavailable`, `session-lease-exists`, …); this module forwards them
  * verbatim and adds its own for the local preconditions.
+ *
+ * The code is also what decides whether there is a fallback at all. A refusal
+ * that is a DECISION about the account (`plan-allowance-exhausted`,
+ * `balance-exhausted`, …) stops the run instead (OSK-8822): switching to the
+ * user's own key because their plan said no is the silent mode switch I4
+ * forbids, and without a key it only starts an engine that cannot run.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ManagedAcquisitionError = void 0;
@@ -59,7 +65,7 @@ exports.hasLocalCredential = hasLocalCredential;
 exports.managedLeaseClockLine = managedLeaseClockLine;
 exports.createManagedEngineHooks = createManagedEngineHooks;
 exports.managedRenewalStoppedLine = managedRenewalStoppedLine;
-exports.managedFallbackLine = managedFallbackLine;
+exports.managedAcquisitionFailure = managedAcquisitionFailure;
 const node_crypto_1 = require("node:crypto");
 const auth_core_1 = require("@skrr-ai/auth-core");
 const inference_broker_1 = require("@skrr-ai/inference-broker");
@@ -970,10 +976,17 @@ function fallbackTail(env) {
  * engine binary FIRST and refuses a missing one before `prepare` runs. Acquiring
  * earlier would mint a lease and open a socket for an engine that never starts.
  *
- * `prepare` cannot throw. `execEngine` awaits it OUTSIDE its try/finally, so a
- * throw here would abort the run and skip `cleanup` — turning "we could not get
- * you a managed session" into the hard failure invariant I4 forbids. Every
- * failure is therefore caught, said once, and answered with `{}` (BYOK).
+ * `prepare` rejects for exactly one reason. Any rejection aborts the run, so a
+ * failure that merely means "we could not get you a managed session" must not
+ * reject — that would be the hard failure invariant I4 forbids. Those are caught,
+ * said once, and answered with `{}` (BYOK).
+ *
+ * The one reason is a refusal that is a DECISION about the account (OSK-8822).
+ * There, starting the engine is the wrong answer whether or not a provider key
+ * exists — with one it silently moves the spend to a different billing boundary
+ * because the plan said no, and without one it starts an engine whose first
+ * request fails — so it is said once and rejected with `EngineStartRefusedError`,
+ * which `execEngine` answers by not spawning at all.
  */
 function createManagedEngineHooks(input) {
     const env = input.env ?? process.env;
@@ -1043,7 +1056,13 @@ function createManagedEngineHooks(input) {
                 return handle.env;
             }
             catch (err) {
-                log(managedFallbackLine(err, env));
+                // ONE classification decides both the sentence and the action, so the line
+                // cannot promise a fallback the run does not take, or the reverse.
+                const failure = managedAcquisitionFailure(err, env);
+                log(failure.line);
+                if (failure.action === 'refuse') {
+                    throw new sky_code_1.EngineStartRefusedError(failure.code, failure.line);
+                }
                 return {};
             }
         },
@@ -1170,29 +1189,33 @@ function managedRenewalStoppedLine(reason, detail) {
                 'your own key.');
     }
 }
-/**
- * The ONE line a failed acquisition prints.
- *
- * Names the machine-readable code as well as the sentence: the codes are the
- * server's typed refusals (`model-denied`, `budget-exhausted`, `policy-unavailable`
- * …) and "which of those happened" is the first thing support asks. Ends by saying
- * what is about to happen instead, because a user who does not know they switched
- * to their own key is the failure mode I4 exists to prevent — and by reading the
- * environment for whether "your own key" is a thing that exists here, because
- * naming the wrong one of managed / BYOK / offline is the same failure.
- */
 /**
  * Refusals that are a DECISION about the account, not the service being down.
  *
- * The server answers these with 402 and a sentence that already says what is
- * wrong and what to do — 1408f64ab4 changed them from `503
+ * The server answers these with a status that is not a 5xx (402 where money or
+ * an allowance is the remedy, 403 for a model the plan excludes, 429 for the
+ * plan's concurrent-session ceiling) and a sentence that already says what is
+ * wrong and what to do — 1408f64ab4 and OSK-8780 moved them off `503
  * admission-unavailable` precisely so a short account would stop reading as an
  * outage. Prefixing "Managed inference unavailable" put the outage back on:
  * the reader was told the platform was broken and, underneath, that their
  * balance was empty, and the first sentence is the one people act on.
  *
- * Everything else keeps the cautious wording, which is right for something this
- * CLI does not recognise.
+ * Mirrored from `sessionInferenceRelay.js`, which declares them inline: no
+ * package owns this vocabulary, so there is nothing to import it from. A new
+ * account-decision code the server adds and this set lacks degrades to the
+ * cautious wording AND the fallback — exactly what OSK-8822 reported for the four
+ * plan codes — so it belongs here in the same change.
+ *
+ * Membership STOPS the run (OSK-8822), not only words it: a decision about the
+ * account is not answered by starting the engine on some other credential.
+ * Everything else keeps the cautious wording and the fallback, which is right
+ * for something this CLI does not recognise.
+ *
+ * `plan-concurrency-exhausted` clears on its own and is here anyway: the server
+ * READ the plan and named the remedy (end another session), and falling back
+ * would move this session's spend onto the user's own key because a different
+ * session holds the slot.
  *
  * `budget-exhausted` is deliberately NOT here. It reports a lease's budget or
  * concurrency slot being held — including the case where a user who quit and
@@ -1201,14 +1224,61 @@ function managedRenewalStoppedLine(reason, detail) {
  * the answer. Widening this set to a code whose semantics are inferred rather
  * than read is how honest copy drifts back into vague copy.
  */
-const ACCOUNT_DECISION_CODES = new Set(['balance-exhausted', 'billing-account-missing']);
-function managedFallbackLine(err, env = process.env) {
+const ACCOUNT_DECISION_CODES = new Set([
+    'balance-exhausted',
+    'billing-account-missing',
+    'plan-allowance-exhausted',
+    'plan-model-denied',
+    'plan-window-exhausted',
+    'plan-concurrency-exhausted',
+]);
+/**
+ * What a failed acquisition does next, and the ONE line that says so.
+ *
+ * One function for both because they must never disagree: a line promising
+ * "continuing with your own provider credentials" over a run that was stopped,
+ * or "did not start the engine" over one that started, is the confusion between
+ * managed, BYOK and offline that I4 forbids.
+ *
+ * The line names the machine-readable code as well as the sentence: the codes
+ * are the server's typed refusals (`model-denied`, `budget-exhausted`,
+ * `policy-unavailable` …) and "which of those happened" is the first thing
+ * support asks. It ends by saying what is about to happen instead, reading the
+ * environment for whether "your own key" is a thing that exists here, because
+ * naming the wrong one of managed / BYOK / offline is the same failure.
+ */
+function managedAcquisitionFailure(err, env = process.env) {
     const code = errorCodeOf(err);
     if (code && ACCOUNT_DECISION_CODES.has(code)) {
         // No "unavailable": nothing is down. The server's sentence names the pot
         // and the remedy, so it leads.
-        return `Managed inference was refused (${code}): ${describe(err)}. ${fallbackTail(env)}`;
+        return {
+            action: 'refuse',
+            code,
+            line: `Managed inference was refused (${code}): ${describe(err)}. ${refusalTail(env)}`,
+        };
+    }
+    return {
+        action: 'fallback',
+        ...(code ? { code } : {}),
+        line: `Managed inference unavailable${code ? ` (${code})` : ''}: ${describe(err)}. ` +
+            fallbackTail(env),
+    };
+}
+/**
+ * What a refused run says where a fallback would have said where it was going.
+ *
+ * The remedy is the server's sentence, which comes first; this adds only what the
+ * server cannot know. That the engine did not start, so a reader who next sees a
+ * shell prompt does not wonder whether the task ran. And, when this machine HAS a
+ * provider key, how to spend it deliberately — the managed opt-out, which makes
+ * BYOK a declared mode instead of something a plan refusal switched on. Never
+ * offered where there is no key to spend.
+ */
+function refusalTail(env) {
+    if ((0, sky_code_1.hasProviderCredential)(env)) {
+        return ('`skrr code` did not start the engine; to run on your own provider key instead, ' +
+            `set ${sky_code_managed_1.MANAGED_ENV_FLAG}=0.`);
     }
-    return (`Managed inference unavailable${code ? ` (${code})` : ''}: ${describe(err)}. ` +
-        fallbackTail(env));
+    return '`skrr code` did not start the engine.';
 }

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

@@ -169,6 +169,36 @@ export declare function notInstalledMessage(env?: NodeJS.ProcessEnv): string;
 export interface EngineExitOutcome {
     interrupted: boolean;
 }
+/**
+ * OSK-8822 — the run was REFUSED before the engine started.
+ *
+ * `prepare` used to have exactly one way to answer: an env map, where `{}` means
+ * "run on the operator's own credentials". So when the server refused the
+ * ACCOUNT — a plan allowance used up, a model the plan does not include — the
+ * refusal could only become a BYOK run, and the engine started with no
+ * credential and failed a second time with a generic error, exiting with the
+ * same `1` as a task that ran and failed.
+ *
+ * A distinct type rather than a sentinel env, so the one outcome that must stop
+ * the run cannot be produced by accident and cannot be mistaken for an ordinary
+ * `prepare` failure. Whoever throws it has already told the user why: it is a
+ * control signal, and its message is for logs, not for printing a second time.
+ */
+export declare class EngineStartRefusedError extends Error {
+    /** The refusal's machine-readable code, e.g. `plan-allowance-exhausted`. */
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/**
+ * The exit code of a refused run: sysexits' `EX_NOPERM`, the one that means
+ * "not permitted" rather than "not available".
+ *
+ * CLI-owned, like `127` for a missing engine, because nothing ran to report one.
+ * It has to differ from `1`, which is what an engine that started and failed
+ * reports — the production case this exists for exited `1`, and CI could not tell
+ * "your plan refused this" from "the task failed".
+ */
+export declare const ENGINE_START_REFUSED_EXIT_CODE = 77;
 export interface EngineSpawnOptions {
     /**
      * OSK-3892 — run before the engine is spawned, to acquire whatever the child
@@ -177,6 +207,9 @@ export interface EngineSpawnOptions {
      * 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.
+     *
+     * Rejecting with {@link EngineStartRefusedError} refuses the run: the engine is
+     * never spawned, `cleanup` still runs, and the error reaches the caller.
      */
     prepare?: () => Promise<Record<string, string>>;
     /** Always run, on every exit path. Tear down anything `prepare` created. */