@skrr-ai/cli 0.1.8

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

@@ -0,0 +1,1148 @@
+"use strict";
+/**
+ * OSK-3892 — the ACQUISITION half: turn a logged-in CLI into a managed session.
+ *
+ * Four steps, in this order, none of which may be reordered:
+ *
+ *   1. mint an `agst_` session capability for a fresh sessionId, bound to an agent
+ *      and to THIS process start;
+ *   2. admit an interactive reservation with it, which reserves budget and issues
+ *      the gateway lease server-side;
+ *   3. build the public relay credential from the non-secret model contract;
+ *   4. start the loopback broker, which is what the engine actually talks to.
+ *
+ * ── Invariant I1: the engine gets a socket, never a credential ──────────────
+ *
+ * The `agst_` token authenticates the RELAY, which lives in this process. What
+ * crosses into the engine's environment is `session.env` — loopback base URLs, a
+ * per-session random secret meaningful only to our own socket, and the managed
+ * marker. That is true by construction in `startManagedInferenceBroker`, which
+ * never puts the upstream key in the returned env; this module simply must not
+ * add one, and does not.
+ *
+ * ── Why the admit call does not go through `apiFetch` ───────────────────────
+ *
+ * `apiFetch` owns the HUMAN credential: on a 401 it force-refreshes the user's
+ * CLI token and rotates the refresh family. Handing it an `agst_` token would make
+ * an expired session capability trigger a rotation of an unrelated credential. The
+ * mint (a user-JWT call) uses `apiFetch`; everything authenticated by the session
+ * token uses plain `fetch` against a URL derived from the same base — exactly the
+ * split `daemon/src/session-wrapper-token-issuer.ts` makes. That includes the
+ * capability REFRESH below, which is the one call most likely to meet an expired
+ * token and therefore the one that must never reach `apiFetch`'s 401 path.
+ *
+ * ── The capability is bounded by the lease, so it must track the lease ──────
+ *
+ * The `agst_` token minted in step 1 lives an hour; a supervised policy profile
+ * buys a lease ceiling of about two. Nothing used to refresh the token, so at
+ * ~60 minutes the relay 401ed, this module's own lease heartbeat 401ed, and the
+ * user got one warning line and a live TUI that could no longer infer — while the
+ * money behind it was still authorized. The heartbeat now refreshes BOTH: the
+ * capability's new expiry comes from the server (which clamps it to the lease's
+ * remaining ceiling), and the refreshed token is written back into the one
+ * variable every later call reads — including the release at teardown, which past
+ * the first hour would otherwise authenticate with a dead token and leak the
+ * reservation to the reaper.
+ *
+ * ── Why every failure is typed ─────────────────────────────────────────────
+ *
+ * `skrr code` must fall back to BYOK with ONE line naming the reason (invariant
+ * I4), and it must not do that by pattern-matching server prose. The server's
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ManagedAcquisitionError = void 0;
+exports.acquireManagedSession = acquireManagedSession;
+exports.hasLocalCredential = hasLocalCredential;
+exports.createManagedEngineHooks = createManagedEngineHooks;
+exports.managedRenewalStoppedLine = managedRenewalStoppedLine;
+exports.managedFallbackLine = managedFallbackLine;
+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");
+const api_fetch_1 = require("./api-fetch");
+const auth_storage_1 = require("./auth-storage");
+const auth_core_init_1 = require("./auth-core-init");
+const config_1 = require("./config");
+const cred_envelope_1 = require("./cred-envelope");
+const device_id_1 = require("./device-id");
+const sky_code_1 = require("./sky-code");
+const sky_code_agent_1 = require("./sky-code-agent");
+const sky_code_managed_1 = require("./sky-code-managed");
+/**
+ * Harness selections the POLICY resolves, mirroring the server's own set.
+ *
+ * Sent when the user named no model: the control plane picks
+ * `policy.defaultModel`, which is the only party that knows which models are
+ * priced and allowed. Guessing one here would be an admission for a model the
+ * policy may refuse.
+ */
+const AUTOMATIC_MODEL = 'default';
+/**
+ * How long the WHOLE acquisition may take before this run is BYOK.
+ *
+ * One bound for all three round trips (agent resolution, mint, admit), not one
+ * per hop: what the user is promised is "`skrr code` starts, or tells you why,
+ * within fifteen seconds", and three 15s hops is a 45s promise. Bounding each
+ * call separately also missed the case this number exists for — a host that
+ * completes a TCP handshake and then never answers (captive portal, half-open
+ * VPN), where every hop burns its own full budget.
+ */
+const ACQUISITION_TIMEOUT_MS = 15_000;
+/**
+ * And a much tighter one for handing the lease BACK.
+ *
+ * A release runs on a teardown path with the human already waiting for their
+ * prompt, and the thing it protects against — a lease renewing itself against
+ * budget nobody is using — is bounded by the server's own reaper. Waiting 15s to
+ * be tidy is the wrong trade; the server's idempotency makes a missed release
+ * recoverable, and a hung teardown is not.
+ */
+const RELEASE_TIMEOUT_MS = 5_000;
+/**
+ * And one for the capability refresh, which runs INSIDE the lease heartbeat.
+ *
+ * It has to be short for that reason: the refresh is awaited before the tick's
+ * lease renewal, so a hung one does not merely delay a token — it delays the
+ * renewal that keeps the lease alive. Ten seconds fits inside the slack the
+ * heartbeat's 60%-of-window cadence leaves on the windows this path actually gets
+ * (a 120s lease is renewed with ~48s to spare, a 5-minute one with ~2 minutes),
+ * and is far under undici's 300s `headersTimeout` — which is what an unbounded
+ * fetch would really wait.
+ */
+const CAPABILITY_REFRESH_TIMEOUT_MS = 10_000;
+/**
+ * The fence refusal that means the session's authorized ceiling has passed.
+ *
+ * The server derives its wire code as `session-token-renewal-<fence reason>`, so
+ * this is the one string that distinguishes "your authorized time is up" from
+ * every other refusal — and those two must not read the same to a user. Matched
+ * exactly rather than by prefix: a code we do not recognise still stops the loop,
+ * just with the more cautious sentence.
+ */
+const CAPABILITY_CEILING_CODE = 'session-token-renewal-lease_ceiling_reached';
+/**
+ * The 401 that means OUR OWN token died, rather than that we were refused.
+ *
+ * `requireSessionScopedAuth` answers 401 for BOTH an expired and a revoked
+ * capability, and those are opposite events: one is a server decision about this
+ * session, the other is a clock. The code separates them, which is why it is
+ * matched rather than the status.
+ */
+const CAPABILITY_EXPIRED_CODE = 'session-token-expired';
+class ManagedAcquisitionError extends Error {
+    /** Machine-classifiable: either a server refusal code or one of ours. */
+    code;
+    /**
+     * The gateway model alias of a lease that WAS reserved server-side, when the
+     * failure happened after admission.
+     *
+     * Carried on the error because that is the only place the caller can learn it:
+     * a refusal thrown from inside `admitLease` has already cost budget, an active
+     * reservation, and a live gateway key, and releasing it needs the alias the
+     * relay resolves authority by. Absent means "nothing to hand back".
+     */
+    reservedModel;
+    constructor(code, message, reservedModel) {
+        super(message);
+        this.name = 'ManagedAcquisitionError';
+        this.code = code;
+        if (reservedModel)
+            this.reservedModel = reservedModel;
+    }
+}
+exports.ManagedAcquisitionError = ManagedAcquisitionError;
+/**
+ * Acquire a managed session, or throw a typed `ManagedAcquisitionError`.
+ *
+ * Throwing rather than returning null: the caller's only correct response to any
+ * failure is the same one-line BYOK fallback, and a null that means six different
+ * things is a null whose message has to be reconstructed by the caller.
+ */
+async function acquireManagedSession(input = {}, deps = {}) {
+    const newId = deps.newId ?? (() => (0, node_crypto_1.randomUUID)());
+    const fetchImpl = deps.fetchImpl ?? ((url, init) => fetch(url, init));
+    const api = deps.api ?? ((path, opts) => (0, api_fetch_1.apiFetch)(path, opts));
+    const serverUrl = (deps.serverUrl ?? (() => (0, sky_code_managed_1.skyCodeServerUrl)(input.env ?? process.env)))();
+    // Envelope-wrapped credentials are unreadable until this has run: without it
+    // `readFromBackend` returns a null plaintext and the whole bundle is dropped, so
+    // a signed-in user looks signed out. `BaseCommand` awaits it for the same reason
+    // before resolving a credential; `skrr code` does not extend `BaseCommand`, so it
+    // is awaited here.
+    await (deps.prefetchAuth ?? auth_core_init_1.prefetchCliAuth)();
+    // Checked locally, BEFORE any network. A fresh machine that has never run
+    // `skrr login` must fall back to BYOK without a round trip and without a 401 that
+    // would drag `apiFetch`'s refresh machinery in behind it.
+    let localCredentialAvailable;
+    if (deps.hasCredential) {
+        localCredentialAvailable = deps.hasCredential();
+    }
+    else {
+        (0, cred_envelope_1.consumeEncryptedCredentialReadWhileInactive)();
+        localCredentialAvailable = hasLocalCredential();
+        if (!localCredentialAvailable && (0, cred_envelope_1.consumeEncryptedCredentialReadWhileInactive)()) {
+            await (0, auth_core_init_1.waitForCliCredentialEnvelope)();
+            localCredentialAvailable = hasLocalCredential();
+        }
+    }
+    if (!localCredentialAvailable) {
+        throw new ManagedAcquisitionError('not-signed-in', 'no skrr session on this machine — run `skrr login`');
+    }
+    const sessionId = newId();
+    // The interactive `attemptId` surrogate is derived from this server-side. Two
+    // concurrent turns in one session therefore need two process starts to be
+    // distinguishable, which is exactly what one CLI process is.
+    const processStartId = newId();
+    // ONE deadline for the whole handshake, armed here and disarmed once the last
+    // round trip has answered. Everything the acquisition does over the network is
+    // inside it, including agent resolution — which is one to two `/api/agents`
+    // calls and, before this, was unbounded.
+    const acquisition = new AbortController();
+    const deadline = setTimeout(() => acquisition.abort(), ACQUISITION_TIMEOUT_MS);
+    /** Turn an abort into the ONE code the fallback line should name. */
+    const timedOut = () => new ManagedAcquisitionError('acquisition-timeout', `the skrr control plane did not answer within ${Math.round(ACQUISITION_TIMEOUT_MS / 1000)}s`);
+    /**
+     * Hand a lease back after it has been reserved but before anything can use it.
+     *
+     * Not conditional on the failure KIND: every path from here to a live broker
+     * leaves the same debris (reserved budget, an `active`/`issued` reservation, a
+     * minted gateway key) and the server's release is idempotent, so attempting it
+     * once too often costs a 200 with `released:false`.
+     */
+    const compensate = async (model, sessionToken) => {
+        if (!model)
+            return;
+        await releaseLease({ serverUrl, sessionId, sessionToken, model, reason: 'cli_broker_failed' }, fetchImpl, input.log);
+    };
+    let agent;
+    /**
+     * The live capability. A `let` because the heartbeat REPLACES it: `compensate`,
+     * the relay credential and `stop()`'s release all read it, and the last of those
+     * runs long after the token minted below has expired.
+     */
+    let sessionToken;
+    /** What the SERVER said that capability expires at. Absent means no refresh. */
+    let capabilityExpiresAtMs;
+    let lease;
+    try {
+        agent = await (deps.resolveAgent ??
+            ((ref, signal) => (0, sky_code_agent_1.resolveSkyCodeAgent)(ref, {}, signal ? { signal } : {})))(input.agentRef, acquisition.signal);
+        // Say it exactly once, on the run that actually minted it.
+        //
+        // A user who never chose an agent is about to have a new one appear in their
+        // agent list, and their session's spend is going to land on it. That is not
+        // something to discover later from a bill — but it is also not worth a line
+        // on every subsequent session, which is why the server distinguishes created
+        // from found rather than the CLI guessing from a timestamp.
+        if (agent.createdNow) {
+            input.log?.(`Created "${agent.name ?? agent.id}" as your default skrr Code agent — ` +
+                'this session, and future ones, are attributed to it. ' +
+                'Change it with `skrr code oversky-agent --set <id-or-name>`.');
+        }
+        const minted = await mintSessionToken({ sessionId, processStartId, agentId: agent.id, actorId: newId() }, api, acquisition.signal);
+        sessionToken = minted.token;
+        capabilityExpiresAtMs = minted.expiresAtMs;
+        try {
+            lease = await admitLease({
+                serverUrl,
+                sessionId,
+                sessionToken,
+                model: input.model?.trim() || AUTOMATIC_MODEL,
+                localRuntimeId: (deps.localRuntimeId ?? localRuntimeId)(),
+                machineUuid: (deps.machineUuid ?? auth_core_1.ensureMachineDaemonId)(),
+            }, fetchImpl, acquisition.signal);
+        }
+        catch (err) {
+            // An admission that reserved budget and then failed its own completeness
+            // check has already spent something. `reservedModel` is set exactly when
+            // that happened; a refused admission carries nothing to release.
+            await compensate(err instanceof ManagedAcquisitionError ? err.reservedModel : undefined, sessionToken);
+            throw err;
+        }
+        // OSK-3924 — the capability above was minted BEFORE this lease existed.
+        //
+        // `…/session-token/issue` mints an unclamped `DEFAULT_TTL_S`, and
+        // structurally must: at that instant there is no reservation to clamp it
+        // against, because admission is authenticated BY the capability. Now there
+        // is one. If the capability we are already holding would outlive the money
+        // behind it, spend one round trip to shorten it — the renewal path clamps to
+        // `min(DEFAULT_TTL_S, remaining ceiling)`, so asking is the whole fix.
+        //
+        // CONDITIONAL rather than unconditional, which is the difference between a
+        // fix and a tax. Under the shipped supervised profile (120s × 60 → a ~2h02m
+        // ceiling) a 1h capability already sits well inside it, so on the common
+        // path this compares two numbers and makes no request at all. It fires only
+        // for a reviewed policy that grants a session less total time than the
+        // capability's own TTL — which is exactly the case where the two clocks
+        // disagree.
+        //
+        // BEST-EFFORT, and it must be: acquisition has already succeeded here, the
+        // lease is reserved and budget is committed. A failure leaves precisely
+        // today's behaviour — an over-long capability that can authenticate and that
+        // `assertReservationIdentity` still refuses to let spend past the lease — so
+        // it must not be able to fail a session that is otherwise fine. It is also
+        // the first call in the renewal rate-limiter's 30s window, and the scheduled
+        // refresh that follows is due no sooner than minutes later.
+        if (capabilityExpiresAtMs !== undefined &&
+            lease.ceilingAtMs !== undefined &&
+            capabilityExpiresAtMs > lease.ceilingAtMs) {
+            const clamped = await refreshSessionCapability({ serverUrl, sessionId, sessionToken, capabilityExpiresAtMs }, fetchImpl).catch(() => null);
+            // Both or neither, for the same reason the scheduled refresh writes both:
+            // an expiry left behind would judge every later 401 against a window that
+            // closed refreshes ago.
+            if (clamped?.ok && clamped.token) {
+                sessionToken = clamped.token;
+                capabilityExpiresAtMs = clamped.expiresAtMs;
+            }
+        }
+    }
+    catch (err) {
+        // The bound is user-visible, so it gets its own code rather than arriving as
+        // whatever `AbortError` the transport happened to produce.
+        if (acquisition.signal.aborted)
+            throw timedOut();
+        throw err;
+    }
+    finally {
+        clearTimeout(deadline);
+    }
+    const releaseModel = lease.modelScope.gatewayModelAlias;
+    /**
+     * Latched, so a RUN of transient refresh failures produces one line rather than
+     * one per heartbeat tick.
+     */
+    let saidRefreshIsFailing = false;
+    // The one configuration relation nothing else pins.
+    //
+    // The capability refresh can only fire on a lease tick, so it lands before
+    // expiry only while the token window is wider than 1.5x the lease window. Both
+    // sides are server environment set independently — `OVERSKY_SESSION_TOKEN_TTL_S`
+    // and `OVERSKY_GATEWAY_KEY_TTL` — and at the supported 15-minute gateway TTL a
+    // token TTL of 1350s or less means the FIRST refresh presents an already-dead
+    // token. The feature then silently does not apply, in a deployment that looks
+    // configured, and the only symptom is a session that dies at its token TTL.
+    //
+    // A warning rather than a refusal: an ill-timed refresh may still land if a tick
+    // happens to fall right, and declining to try would make a survivable
+    // misconfiguration fatal.
+    if (capabilityExpiresAtMs !== undefined) {
+        const capabilityWindowMs = capabilityExpiresAtMs - Date.now();
+        // The RENEWAL window, not the admission one (OSK-3937).
+        //
+        // `minimumCapabilityWindowMs`'s docstring says so, and the warning text
+        // below says so too — "1.5x its OVERSKY_GATEWAY_KEY_TTL". The call passed
+        // `leaseExpiresInMs`, which is the 120s admission window, so the check
+        // demanded 180s where the true requirement is 450s at the default gateway
+        // TTL and 1350s at the supported maximum. That made the warning INERT in the
+        // exact configuration it was written for: at `OVERSKY_GATEWAY_KEY_TTL=15m`
+        // with a 1350s token TTL, nothing printed and the session lost the model
+        // mid-run.
+        //
+        // Falls back to the admission window only for a server that predates the
+        // field. That is the old, too-permissive behaviour — kept because a warning
+        // that cannot be computed should not become a refusal, and an older server
+        // is not a misconfiguration.
+        const requiredMs = (0, inference_broker_1.minimumCapabilityWindowMs)(lease.renewalWindowMs ?? lease.leaseExpiresInMs);
+        if (capabilityWindowMs <= requiredMs) {
+            input.log?.('Managed inference cannot refresh its session credential in time: the capability ' +
+                `window (${Math.round(capabilityWindowMs / 1_000)}s) is not wider than the ` +
+                `${Math.round(requiredMs / 1_000)}s this lease heartbeat needs. Set the server's ` +
+                'OVERSKY_SESSION_TOKEN_TTL_S above 1.5x its OVERSKY_GATEWAY_KEY_TTL. This session ' +
+                'will lose access to the model when its credential expires.');
+        }
+    }
+    let session;
+    try {
+        const credential = (deps.buildRelayCredential ?? inference_broker_1.buildManagedInferenceRelayCredential)({ modelScope: lease.modelScope }, { serverUrl, sessionId, sessionToken });
+        session = await (deps.startBroker ?? inference_broker_1.startManagedInferenceBroker)({
+            credential,
+            modelScope: lease.modelScope,
+            leaseExpiresInMs: lease.leaseExpiresInMs,
+            // Both or neither. A schedule without a refresher does nothing, and a
+            // refresher without a server-stated expiry has no honest moment to fire: the
+            // server owns this TTL and clamps it to the lease ceiling, so any lead the
+            // CLI invented would be wrong in exactly the window that matters.
+            ...(capabilityExpiresAtMs
+                ? {
+                    capabilityExpiresAtMs,
+                    refreshCapability: async () => {
+                        const outcome = await refreshSessionCapability(
+                        // Read at CALL time, so the Nth refresh presents the (N-1)th token
+                        // rather than the one minted at acquisition — and reports the
+                        // expiry of THAT token, which is what makes a 401 classifiable.
+                        {
+                            serverUrl,
+                            sessionId,
+                            sessionToken,
+                            ...(capabilityExpiresAtMs !== undefined ? { capabilityExpiresAtMs } : {}),
+                        }, fetchImpl);
+                        // The write-back. The broker swaps its own copy — what the relay and
+                        // the lease renewal send — and this is the copy `stop()` releases
+                        // with. Updating only one of the two is the failure that looks fixed.
+                        if (outcome.ok && outcome.token) {
+                            sessionToken = outcome.token;
+                            // The expiry moves with the token. Left behind, the next 401 would
+                            // be judged against a window that closed refreshes ago and every
+                            // later refusal would read as a lapse.
+                            capabilityExpiresAtMs = outcome.expiresAtMs;
+                        }
+                        else if (isTransientRefresh(outcome) && !saidRefreshIsFailing) {
+                            // ONCE. Every transient refresh failure used to be completely
+                            // silent — no log, no readout field, no stop reason — while the
+                            // status readout kept showing a healthy lease, so a session that
+                            // was quietly running out of credential looked fine right up to the
+                            // moment it stopped. Not repeated per retry: this is a breadcrumb
+                            // for the user who later asks why their session ended, and if it
+                            // never recovers the stop reason says so in its own line.
+                            saidRefreshIsFailing = true;
+                            input.log?.(`Managed inference could not refresh its session credential (${outcome.reason ?? 'unknown error'}). ` +
+                                'Retrying — the session continues for now.');
+                        }
+                        return outcome;
+                    },
+                }
+                : {}),
+            ...(input.onLeaseRenewalStopped
+                ? { onLeaseRenewalStopped: input.onLeaseRenewalStopped }
+                : {}),
+        });
+    }
+    catch (err) {
+        // The asymmetry this closes: `admitLease` has already reserved budget and
+        // minted a live gateway key, and the caller's answer to a broker failure is a
+        // one-line BYOK fallback — so without this the lease stays `active` /
+        // `leaseStatus: 'issued'` with nothing pointing at it until the reaper.
+        // Reachable from a mkdtemp/chmod failure, an EADDRINUSE, and from a base URL
+        // carrying userinfo/query/fragment: that passes the CLI's protocol-only HTTPS
+        // check and is refused by `buildManagedInferenceRelayCredential`.
+        await compensate(releaseModel, sessionToken);
+        throw err;
+    }
+    return {
+        env: session.env,
+        socketPath: session.socketPath,
+        sessionId,
+        agent,
+        reservationId: lease.reservationId,
+        model: lease.model,
+        ...(session.clientModelId ? { clientModelId: session.clientModelId } : {}),
+        authorizedUsd: lease.authorizedUsd,
+        leaseExpiresInMs: lease.leaseExpiresInMs,
+        stop: async (reason = 'cli_session_ended') => {
+            try {
+                // The broker FIRST, because `stop()` stops the renewal loop: releasing
+                // while a heartbeat is in flight risks the renewal re-extending the lease
+                // we just ended, which would leave exactly the debris this call removes.
+                await session.stop();
+            }
+            finally {
+                // In a `finally`: a broker that fails to shut down cleanly is a local
+                // problem, while a lease left renewing itself is a billed one. The
+                // original error still propagates to the caller's teardown log.
+                await releaseLease({ serverUrl, sessionId, sessionToken, model: releaseModel, reason }, fetchImpl, input.log);
+            }
+        },
+    };
+}
+/**
+ * OSK-3892 — end the lease, or say once that we could not.
+ *
+ * `POST …/inference/release` is idempotent and answers `{ok: true, released:
+ * false}` when there is no live lease, so calling it twice, or after expiry, or
+ * on a reservation the reaper already took, is not an error. That is what makes
+ * it safe to call from both a compensating path and a normal teardown without
+ * either having to know what the other did.
+ *
+ * Never throws. Every caller is on a path where the outcome is already decided —
+ * a fallback to BYOK, or an engine that has exited with a code the user cares
+ * about — and a teardown error that replaces either is a strictly worse answer
+ * than a lease the server's reaper collects a couple of minutes later.
+ */
+async function releaseLease(input, fetchImpl, log) {
+    const url = `${input.serverUrl.replace(/\/+$/, '')}` +
+        `/api/agentic/sessions/${encodeURIComponent(input.sessionId)}/inference/release`;
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), RELEASE_TIMEOUT_MS);
+    try {
+        const response = await fetchImpl(url, {
+            method: 'POST',
+            headers: {
+                Accept: 'application/json',
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${input.sessionToken}`,
+            },
+            body: JSON.stringify({ model: input.model, reason: input.reason }),
+            signal: controller.signal,
+        });
+        if (!response.ok) {
+            // Only a 503 `release-unavailable` is a real failure; the refusals that
+            // mean "nothing to release" come back 200. Reported either way, because a
+            // client that cannot tell the server it is done is worth one line.
+            const refusal = await readRefusal(response);
+            log?.(`Managed inference lease was not released (HTTP ${response.status}` +
+                `${refusal.code ? ` ${refusal.code}` : ''}) — the control plane will reclaim it.`);
+        }
+    }
+    catch (err) {
+        log?.(`Managed inference lease was not released (${describe(err)}) — ` +
+            'the control plane will reclaim it.');
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+/**
+ * Mint the session capability.
+ *
+ * `agentId` is what makes the server mint a DEFAULT INTERACTIVE claim
+ * (`capabilities: ['submit_interactive']`); without it the token is claimless and
+ * the relay refuses every call. `processStartId` is what makes the interactive
+ * attempt surrogate exist, and admission refuses a token that lacks one.
+ *
+ * `spaceId` is deliberately NOT sent. The mint puts a space id into the claim's
+ * WORKSPACE slot, which would make the reservation bill to
+ * `workspace:<spaceId>` — a tenant that does not exist. The server cannot tell the
+ * two id namespaces apart, so not sending one is the only defence.
+ *
+ * The response's `expiresAt` used to be dropped on the floor. It is the only
+ * statement of when this capability dies — the TTL is server env, so the CLI
+ * cannot derive it — and without it there is nothing to schedule a refresh
+ * against. A mint that omits it is not an error: the session simply behaves as it
+ * did before refresh existed.
+ */
+async function mintSessionToken(input, api, signal) {
+    let response;
+    try {
+        response = await api(`/api/agentic/sessions/${encodeURIComponent(input.sessionId)}/session-token/issue`, {
+            method: 'POST',
+            body: {
+                actorId: input.actorId,
+                agentId: input.agentId,
+                processStartId: input.processStartId,
+            },
+            ...(signal ? { signal } : {}),
+        });
+    }
+    catch (err) {
+        throw new ManagedAcquisitionError(errorCodeOf(err) ?? 'session-token-refused', `the server would not issue a session capability — ${describe(err)}`);
+    }
+    const token = typeof response?.token === 'string' ? response.token.trim() : '';
+    if (!token) {
+        throw new ManagedAcquisitionError('session-token-missing', 'the server issued no session capability');
+    }
+    const expiresAtMs = coerceExpiresAtMs(response?.expiresAt);
+    return { token, ...(expiresAtMs !== undefined ? { expiresAtMs } : {}) };
+}
+/**
+ * Refresh the session capability, presenting the CURRENT one.
+ *
+ * `POST …/session-token/renew` re-mints with every claim copied verbatim —
+ * including `processStartId`, which is what keeps the refreshed token bound to the
+ * same interactive reservation — and the server clamps the new TTL to what remains
+ * of that reservation's immutable ceiling. So this call cannot widen anything: the
+ * most it can do is extend the credential up to the money that was already
+ * authorized for it.
+ *
+ * Classified per STATUS, never per status class. The four outcomes below are
+ * genuinely different events and the 4xx/5xx split gets three of them wrong: a 429
+ * is the most retryable failure there is, the ceiling is the one refusal that has
+ * a specific and actionable thing to tell the user, and a 401 against a token that
+ * was ALREADY DEAD is not a refusal at all — nothing was evaluated.
+ *
+ * Never throws. A refresh failure is the heartbeat's decision to make, and the
+ * heartbeat is what keeps the lease — the half of the session that costs money —
+ * alive.
+ */
+async function refreshSessionCapability(input, fetchImpl) {
+    const url = `${input.serverUrl.replace(/\/+$/, '')}` +
+        `/api/agentic/sessions/${encodeURIComponent(input.sessionId)}/session-token/renew`;
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), CAPABILITY_REFRESH_TIMEOUT_MS);
+    try {
+        const response = await fetchImpl(url, {
+            method: 'POST',
+            headers: {
+                Accept: 'application/json',
+                // The session capability, not the user's login credential. The route is
+                // session-scoped auth, and `apiFetch` would answer a 401 here by rotating
+                // an unrelated refresh family.
+                Authorization: `Bearer ${input.sessionToken}`,
+            },
+            signal: controller.signal,
+        });
+        if (response.ok) {
+            const payload = (await response.json().catch(() => null));
+            const token = typeof payload?.token === 'string' ? payload.token.trim() : '';
+            const expiresAtMs = coerceExpiresAtMs(payload?.expiresAt);
+            if (!token.startsWith('agst_') || expiresAtMs === undefined) {
+                // A 200 we cannot use. Retryable rather than terminal: killing a session
+                // that is otherwise healthy over one malformed answer is the worse trade,
+                // and the heartbeat still holds a working token until its real expiry.
+                return {
+                    ok: false,
+                    reason: 'the server renewed the capability without a usable token or expiry',
+                };
+            }
+            return { ok: true, token, expiresAtMs };
+        }
+        // Read BEFORE the body: `readRefusal` consumes it.
+        const retryAfter = retryAfterMs(response);
+        const refusal = await readRefusal(response);
+        const reason = refusal.code ?? `capability refresh HTTP ${response.status}`;
+        if (response.status === 429) {
+            // One refresh per 30s per session, and the heartbeat's own retries fire with
+            // no backoff — so this is reachable, and reading it as a refusal would end a
+            // session over a limiter doing its job.
+            return {
+                ok: false,
+                ...(retryAfter !== undefined ? { retryAfterMs: retryAfter } : {}),
+                reason,
+            };
+        }
+        if (refusal.code === CAPABILITY_CEILING_CODE) {
+            // Prefer the INSTANT over the code here, and only here: this is the one
+            // refusal whose useful detail is not "which rule fired" — the user knows the
+            // rule, they want to know when their window ended.
+            return {
+                ok: false,
+                ceiling: true,
+                reason: refusal.ceilingAt ? `authorized through ${refusal.ceilingAt}` : reason,
+            };
+        }
+        if (response.status === 401 &&
+            (refusal.code === CAPABILITY_EXPIRED_CODE || credentialAlreadyLapsed(input))) {
+            // The modal cause is a LAPTOP SUSPEND. Timers do not fire while asleep, so
+            // the loop wakes hours late and presents a token that died in the meantime —
+            // and calling that "renewal was refused" attributes to the server a decision
+            // it never made, sending the user to look for a policy problem that is not
+            // there. Terminal either way (there is nothing left to authenticate with),
+            // and a REVOKED token is deliberately not folded in here: that one is a real
+            // decision and keeps reading as `denied`.
+            return {
+                ok: false,
+                expired: true,
+                reason: input.capabilityExpiresAtMs
+                    ? `the session capability expired at ${new Date(input.capabilityExpiresAtMs).toISOString()}`
+                    : 'the session capability expired',
+            };
+        }
+        // 5xx includes the fence's own `lease_state_unavailable`, which is explicitly
+        // a fail-closed-but-retryable answer: the ceiling could not be READ, which is
+        // not the same as having been reached.
+        if (response.status >= 500)
+            return { ok: false, reason };
+        return { ok: false, denied: true, reason };
+    }
+    catch (err) {
+        return { ok: false, reason: describe(err) };
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+/**
+ * A refresh failure the heartbeat will try again — as opposed to one that ends it.
+ *
+ * Read off the same three terminal flags the loop reads, so "the loop will keep
+ * going" and "we said something about it" cannot disagree.
+ */
+function isTransientRefresh(outcome) {
+    return !outcome.ok && !outcome.ceiling && !outcome.denied && !outcome.expired;
+}
+/**
+ * Whether the credential we just presented was already past its stated expiry.
+ *
+ * No skew allowance in either direction. Our clock and the server's agreeing that
+ * the token is dead is what makes "it lapsed" the honest reading; a token the
+ * server killed EARLY still reads as a refusal, which is correct, because the
+ * server really did decide something.
+ */
+function credentialAlreadyLapsed(input) {
+    return input.capabilityExpiresAtMs !== undefined && Date.now() >= input.capabilityExpiresAtMs;
+}
+/**
+ * `Retry-After`, in ms.
+ *
+ * Only the delta-seconds form, which is what this route sends. An HTTP-date would
+ * read as `NaN` and fall back to the heartbeat's own floor, which is the safe
+ * direction: waiting the rate-limit window is never wrong.
+ */
+function retryAfterMs(response) {
+    const header = response.headers.get('retry-after');
+    const seconds = header ? Number(header) : Number.NaN;
+    return Number.isFinite(seconds) && seconds > 0 ? Math.ceil(seconds * 1_000) : undefined;
+}
+/**
+ * Read an `expiresAt` the server stated, or nothing.
+ *
+ * Epoch ms today; the string forms are tolerated for the same reason
+ * `daemon/src/session-token-expiry.ts` tolerates them — a JSON number that has been
+ * through a proxy or a serializer is not always still a number. Anything else is
+ * `undefined`, which the caller reads as "no schedule", never as "no bound".
+ */
+function coerceExpiresAtMs(value) {
+    if (typeof value === 'number' && Number.isFinite(value) && value > 0)
+        return value;
+    if (typeof value === 'string' && value.length > 0) {
+        const numeric = Number(value);
+        if (Number.isFinite(numeric) && numeric > 0)
+            return numeric;
+        const parsed = Date.parse(value);
+        if (Number.isFinite(parsed) && parsed > 0)
+            return parsed;
+    }
+    return undefined;
+}
+/**
+ * Admit the interactive reservation.
+ *
+ * The body carries WORK and local runtime identity only: userId, sessionId,
+ * agentId, workspaceId and processStartId are read from the token by the server,
+ * and the run/attempt identity is DERIVED from the session and the process. A
+ * caller that could name those could attribute its spend to someone else's run.
+ *
+ * `localRuntimeId` must carry the `cli_` namespace — `describeLocalRuntimeIdentity`
+ * refuses an unprefixed id for kind `cli` — and it is self-asserted on this path
+ * by design: there is no server-side registry of CLI installations, locatability
+ * is scoped to the authenticated user, and requiring an enrolled daemon record
+ * would break the standalone case the feature exists for.
+ */
+async function admitLease(input, fetchImpl, 
+// The acquisition-wide deadline, not one of this call's own: a hung control
+// plane must not hold an interactive command open when a perfectly good BYOK
+// path is one line away, and the user was promised one number for the whole
+// handshake rather than one per hop.
+signal) {
+    const url = `${input.serverUrl.replace(/\/+$/, '')}` +
+        `/api/agentic/sessions/${encodeURIComponent(input.sessionId)}/inference/admit`;
+    let response;
+    try {
+        response = await fetchImpl(url, {
+            method: 'POST',
+            headers: {
+                Accept: 'application/json',
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${input.sessionToken}`,
+            },
+            body: JSON.stringify({
+                model: input.model,
+                localRuntimeId: input.localRuntimeId,
+                machineUuid: input.machineUuid,
+            }),
+            ...(signal ? { signal } : {}),
+        });
+    }
+    catch (err) {
+        throw new ManagedAcquisitionError('admission-unreachable', `could not reach the skrr control plane — ${describe(err)}`);
+    }
+    if (!response.ok) {
+        const refusal = await readRefusal(response);
+        throw new ManagedAcquisitionError(refusal.code ?? `admission-http-${response.status}`, refusal.message ?? `the control plane refused admission (HTTP ${response.status})`);
+    }
+    const payload = (await response.json().catch(() => null));
+    const modelScope = payload?.modelScope;
+    const model = typeof payload?.model === 'string' ? payload.model.trim() : '';
+    // The alias the RELAY resolves authority by, which is also the only handle a
+    // compensating release has. Read before the refusals below so a lease that was
+    // reserved and is then rejected here can still be handed back.
+    const reservedModel = typeof modelScope?.gatewayModelAlias === 'string' ? modelScope.gatewayModelAlias : undefined;
+    // Validated rather than trusted: the broker needs an exact immutable lease, and a
+    // truncated one would surface later as a rejected turn rather than as a clear
+    // refusal here. `isManagedInferenceModelScope` is the package's own predicate,
+    // but re-deriving the fields we depend on keeps the error message specific.
+    if (!payload?.reservationId || !model || !modelScope || modelScope.version !== 1) {
+        throw new ManagedAcquisitionError('admission-incomplete', 'the control plane admitted a session without a usable model lease', reservedModel);
+    }
+    const leaseExpiresInMs = Number(payload.leaseExpiresInMs);
+    // Same refusal as a missing `modelScope`, for the same reason.
+    //
+    // `startManagedInferenceBroker` arms its renewal heartbeat only when this is a
+    // positive number, so a missing, null or non-numeric value produced a broker
+    // with NO heartbeat and no `onLeaseRenewalStopped` — the session then died
+    // silently at the 120s money clock and every later turn 403'd, with nothing on
+    // screen ever naming the cause. A lease with no renewable window is not a
+    // usable supervised lease; it is an incomplete admission that happens to have
+    // all its other fields.
+    if (!Number.isFinite(leaseExpiresInMs) || leaseExpiresInMs <= 0) {
+        throw new ManagedAcquisitionError('admission-incomplete', 'the control plane admitted a session with no renewable lease window', reservedModel);
+    }
+    // The immutable ceiling, stamped to an ABSOLUTE instant here (OSK-3914's rule:
+    // a relative duration decays from the moment it arrives, and this one is
+    // compared against another clock several statements later). Optional — a
+    // pre-OSK-3888 reservation reports none, and a server that predates OSK-3924
+    // sends none either, in which case the capability clamp below simply does not
+    // run and behaviour is exactly what it was.
+    //
+    // The wire name and the field name differ ON PURPOSE, and the difference is
+    // the conversion: the server sends `maxExpiresInMs` (relative, so its clock is
+    // the authority, matching `leaseExpiresInMs`) and this stores `ceilingAtMs`
+    // (absolute, so it cannot decay while it waits to be compared). Reading the
+    // wire field off a widened type keeps `AdmittedLease` describing what this
+    // module HOLDS rather than what the server SAID.
+    const maxExpiresInMs = Number(payload.maxExpiresInMs);
+    const reportedRenewalWindowMs = Number(payload.renewalWindowMs);
+    return {
+        reservationId: String(payload.reservationId),
+        model,
+        modelScope,
+        leaseExpiresInMs,
+        ...(Number.isFinite(maxExpiresInMs) && maxExpiresInMs > 0
+            ? { ceilingAtMs: Date.now() + maxExpiresInMs }
+            : {}),
+        ...(Number.isFinite(reportedRenewalWindowMs) && reportedRenewalWindowMs > 0
+            ? { renewalWindowMs: reportedRenewalWindowMs }
+            : {}),
+        authorizedUsd: Number(payload.authorizedUsd ?? 0),
+    };
+}
+/**
+ * Read `{error: {code, message}}` without letting a hostile/huge body matter.
+ *
+ * Plus the one refusal FIELD this module needs beyond the code: `fence.maxExpiresAt`,
+ * the lease ceiling the token-renewal fence echoes when it refuses. Read here rather
+ * than by a second parse of the same body, since the body can be read only once —
+ * and it is the difference between telling a user that their authorized window ended
+ * and telling them only that something was refused.
+ */
+async function readRefusal(response) {
+    try {
+        const raw = (await response.text()).slice(0, 2048);
+        const parsed = JSON.parse(raw);
+        const code = parsed?.error?.code ?? parsed?.code;
+        const message = parsed?.error?.message ?? parsed?.message;
+        const ceilingAt = parsed?.fence?.maxExpiresAt;
+        return {
+            ...(typeof code === 'string' && code ? { code } : {}),
+            ...(typeof message === 'string' && message ? { message } : {}),
+            ...(typeof ceilingAt === 'string' && ceilingAt ? { ceilingAt } : {}),
+        };
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Whether a credential exists on this machine, without a network call.
+ *
+ * Reads the same two slots the resolver's non-interactive path reads: the auth
+ * backend (keychain or `cli-auth.json`, origin-checked) and the env overlay that
+ * `OVERSKY_TOKEN` lands in. Deliberately NOT `resolveCredential()`, which may
+ * spawn an auth helper or prompt — a precondition check must not have side
+ * effects.
+ */
+function hasLocalCredential() {
+    try {
+        const cfg = (0, config_1.loadConfig)();
+        if (cfg.token)
+            return true;
+        return Boolean((0, auth_storage_1.readFromBackend)(cfg.baseURL).bundle?.token);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * This installation's runtime id.
+ *
+ * Persisted at first login as `cliId`; regenerated deterministically when absent
+ * (same hostname+user always yields the same value), matching `daemonBroker.ts`
+ * and `refresh.ts`. Normalized to the `cli_` namespace the server requires,
+ * because `OVERSKY_CLI_ID` is overlaid verbatim with no format check and a
+ * hand-set value would otherwise come back as an opaque
+ * `runtime-id-namespace-mismatch`.
+ */
+function localRuntimeId() {
+    const configured = (() => {
+        try {
+            return (0, config_1.loadConfig)().cliId?.trim();
+        }
+        catch {
+            return undefined;
+        }
+    })();
+    if (configured?.startsWith('cli_'))
+        return configured;
+    return (0, device_id_1.generateCliId)();
+}
+function errorCodeOf(err) {
+    const code = err?.code;
+    return typeof code === 'string' && code ? code : undefined;
+}
+function describe(err) {
+    const text = err instanceof Error ? err.message : String(err);
+    return text.trim() || 'unknown error';
+}
+/**
+ * What is ACTUALLY about to happen instead — which is not always BYOK.
+ *
+ * Every fallback line used to end in a fixed "Continuing with your own provider
+ * credentials", without checking that any existed. On the exact machine this
+ * feature targets — `skrr login` done, no provider key exported, no daemon — the
+ * user was told the run continues on their own credentials, the engine started
+ * with none, and the next thing they saw was a provider auth error that reads
+ * like a broken engine rather than like a mode switch. Invariant I4 requires
+ * managed, BYOK and offline never be confused, and a sentence that names the
+ * wrong one of the three is the confusion, not a mitigation of it.
+ *
+ * The predicate is `hasProviderCredential`, the same one that decides what the
+ * engine actually inherits (`sky-code.ts`), so the sentence and the spawn cannot
+ * disagree.
+ */
+function fallbackTail(env) {
+    if ((0, sky_code_1.hasProviderCredential)(env))
+        return 'Continuing with your own provider credentials.';
+    return ('No provider credential is set here either, so the engine will start without one and ' +
+        'its first request will fail — set OPENROUTER_API_KEY, or resolve the reason above ' +
+        '(`skrr code doctor`).');
+}
+/**
+ * Build the three `execEngine` hooks for one `skrr code` invocation.
+ *
+ * The whole managed path is expressed as hooks rather than as work done before
+ * `execEngine` because of an ordering that matters: `execEngine` resolves the
+ * 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).
+ */
+function createManagedEngineHooks(input) {
+    const env = input.env ?? process.env;
+    const log = input.log ?? ((line) => process.stderr.write(`${line}\n`));
+    const acquire = input.acquire ?? acquireManagedSession;
+    const requestedModel = (0, sky_code_managed_1.namedEngineModel)(input.passthrough);
+    let handle = null;
+    /**
+     * Set the instant teardown begins, so a renewal refusal our OWN release caused
+     * is not reported to the user as a decision about their account (OSK-3961).
+     */
+    let tearingDown = false;
+    return {
+        session: () => handle,
+        // A live handle means a broker is running and the engine's base URLs point at
+        // it, which is exactly when re-admitting an ambient provider key would let the
+        // engine bypass the relay (or 401 preferring a stale `x-api-key`). No handle
+        // means acquisition was skipped or failed, the run genuinely IS BYOK, and the
+        // user was told so.
+        credentialMode: () => (handle ? 'managed' : 'byok'),
+        prepare: async () => {
+            const skip = (0, sky_code_managed_1.managedSkipReason)(env);
+            if (skip) {
+                if (skip.announce)
+                    log(`Managed inference not used: ${skip.detail}. ${fallbackTail(env)}`);
+                return {};
+            }
+            try {
+                handle = await acquire({
+                    ...(input.agentRef ? { agentRef: input.agentRef } : {}),
+                    ...(requestedModel ? { model: requestedModel } : {}),
+                    env,
+                    // The acquisition's own best-effort teardown line (a lease it could not
+                    // hand back) goes to the same place as the fallback line.
+                    log,
+                    onLeaseRenewalStopped: (reason, detail) => {
+                        // Said as it happens rather than at the end: once renewal stops the
+                        // relay will refuse the next turn, and a user staring at a hung TUI
+                        // deserves the reason — and WHICH reason, because "your authorized time
+                        // is up" and "the server refused" call for different next moves.
+                        // Silent once teardown has begun (OSK-3961).
+                        //
+                        // Observed on ~50% of clean exits against deployed dev:
+                        //   "Managed inference renewal was refused (denied: lease-revoked)."
+                        // `denied` is the arm that means a decision was made about YOUR
+                        // ACCOUNT, so it is the worst available sentence for a session that
+                        // worked and is shutting down normally.
+                        //
+                        // The loop is stopped before the release and `finish()` latches, so a
+                        // refusal cannot arrive after `stop()` RESOLVES — which means this is
+                        // a renewal already on the wire when teardown began, racing the
+                        // revoke that teardown itself performs. That race is inherent: the
+                        // request left before we decided to stop, and the release must revoke.
+                        //
+                        // Gated on the TIME OF TEARDOWN rather than on the reason, because
+                        // any refusal caused by our own shutdown tells the user nothing they
+                        // can act on — while a refusal arriving mid-session is real and must
+                        // still speak.
+                        if (tearingDown)
+                            return;
+                        const line = managedRenewalStoppedLine(reason, detail);
+                        if (line)
+                            log(line);
+                    },
+                });
+                return handle.env;
+            }
+            catch (err) {
+                log(managedFallbackLine(err, env));
+                return {};
+            }
+        },
+        finalizeArgs: (args) => 
+        // Only when WE resolved the model. A user-named model is already in the argv.
+        (0, sky_code_managed_1.withManagedModel)(input.subcommand, args, handle && !requestedModel ? (handle.clientModelId ?? handle.model) : undefined),
+        cleanup: async (outcome) => {
+            const live = handle;
+            handle = null;
+            if (!live)
+                return;
+            tearingDown = true;
+            try {
+                // A Ctrl-C reaches this same path: `stdio: 'inherit'` puts the engine in
+                // this process group, the CLI's own handler kills it, and `execEngine`'s
+                // `finally` still runs — so the only thing missing was telling the server
+                // WHICH of the two endings this was.
+                await live.stop(outcome?.interrupted ? 'cli_session_interrupted' : 'cli_session_ended');
+            }
+            catch (err) {
+                // `cleanup` runs in `execEngine`'s `finally`, so throwing here would
+                // replace the engine's own exit reason with a teardown error.
+                log(`Managed inference broker did not shut down cleanly: ${describe(err)}`);
+            }
+        },
+    };
+}
+/**
+ * What a stopped renewal heartbeat tells the user — or, once, nothing.
+ *
+ * Five events used to print one sentence with the reason word interpolated into
+ * it, which made the ones that matter indistinguishable in the only way a user
+ * reads them:
+ *
+ *   `ceiling`     the session spent the whole window its policy authorized. Not a
+ *                 failure, not something to retry, and the only one with a useful
+ *                 next step. On the shipped profile this is the ORDINARY ending of
+ *                 a long supervised session, which is why it must not read like a
+ *                 fault.
+ *   `expired`     OUR credential lapsed while this process was not running — a
+ *                 laptop suspend, almost always. The server refused nothing,
+ *                 because it was never really asked.
+ *   `denied`      the server evaluated this session and refused it — a revoked
+ *                 lease, an exhausted budget, a scope that no longer holds.
+ *   `unavailable` we could not reach the control plane. Nothing was decided.
+ *   `stopped`     WE stopped it, on the way out. Nothing happened TO the session,
+ *                 so saying "this session will lose access shortly" while the user
+ *                 is already at their shell is noise that trains them to ignore
+ *                 the other four.
+ *
+ * Returns null when there is nothing worth saying.
+ */
+function managedRenewalStoppedLine(reason, detail) {
+    const because = detail ? `: ${detail}` : '';
+    switch (reason) {
+        case 'stopped':
+            return null;
+        case 'ceiling':
+            // The detail is a parenthetical rather than the `(reason: detail)` shape the
+            // others use, because "ceiling" is already the subject of the sentence and
+            // the useful detail here is WHEN the window ended, not which rule fired.
+            return ('Managed inference reached the limit this session was authorized for' +
+                `${detail ? ` (${detail})` : ''}. ` +
+                'It cannot be extended further — start a new `skrr code` session to continue.');
+        case 'expired':
+            // Deliberately names the cause rather than only the fact. A user who was
+            // told "renewal was refused" goes looking for a policy or budget problem;
+            // the actual event is that their machine slept through the refresh window,
+            // and the fix is the same one-liner as the ceiling's.
+            return ('Managed inference lost its session credential before it could be refreshed' +
+                `${detail ? ` (${detail})` : ''} — this usually means the machine slept. ` +
+                'Start a new `skrr code` session to continue.');
+        case 'exhausted': {
+            // OSK-3932 — the money, which until now could only reach the user as
+            // `denied` ("something is wrong with your access") or, worse, as nothing at
+            // all while the badge went on reporting a healthy lease.
+            //
+            // TWO sentences, because the two exhaustions have genuinely different
+            // remedies and telling a human to wait for a reset that will not restore
+            // their session is worse than saying nothing about time.
+            //
+            // The detail carries the reset INSTANT when the server sent one and the
+            // refusal code when it did not, so a parseable date is exactly the signal
+            // that waiting helps. Sniffed rather than flagged because `onStop` carries
+            // one string; a code never parses as a date, so the test is total.
+            const resetAt = detail && Number.isFinite(Date.parse(detail)) ? detail : null;
+            if (resetAt) {
+                return (`Managed inference stopped: your account's budget for the current window is spent (resets ${resetAt}). ` +
+                    'This session will lose access to the model shortly. Wait for the reset, ' +
+                    'or export OPENROUTER_API_KEY to continue on your own key.');
+            }
+            return ('Managed inference stopped: this session spent the budget it was authorized. ' +
+                'Waiting will not restore it — start a new `skrr code` session to continue, ' +
+                'or export OPENROUTER_API_KEY to continue on your own key.');
+        }
+        case 'denied':
+            // Names what to do next, like `ceiling` and `expired` already do.
+            //
+            // §9 of the architecture record promised this arm would name
+            // `oversky byok set <provider>` — "never a silent stall, and never a silent
+            // mode switch". It never shipped, and naming that command would have been
+            // WRONG ADVICE anyway: its credential is deliberately non-injectable into a
+            // standalone engine (`provider-credentials.ts`), and `hasProviderCredential`
+            // reads the environment only. So the doc was the stale artifact, not the
+            // code, and §9 has been amended to match what actually works (OSK-3942).
+            //
+            // A refusal is about the ACCOUNT, so unlike the ceiling a new session may
+            // hit the same answer — saying so is the difference between a remedy and a
+            // loop.
+            return (`Managed inference renewal was refused (${reason}${because}). ` +
+                'This session will lose access to the model shortly. This is an answer about ' +
+                'your account rather than the clock, so a new session may get it again — run ' +
+                '`skrr code doctor`, or export OPENROUTER_API_KEY to continue on your own key.');
+        default:
+            // `unavailable`, and any reason a future package version adds: the cautious
+            // sentence is the right default for something this CLI does not recognise.
+            //
+            // Distinct from `denied` on purpose: this one is usually the network or the
+            // service, so retrying is reasonable and a BYOK key is the fallback rather
+            // than the fix.
+            return (`Managed inference could not renew its lease (${reason}${because}). ` +
+                'This session will lose access to the model shortly. If it does not recover, ' +
+                'start a new `skrr code` session, or export OPENROUTER_API_KEY to continue on ' +
+                '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
+ * 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.
+ *
+ * `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
+ * restarted inside the release window is refused on a lease they just gave back
+ * — so it is transient in a way a balance is not, and retrying really can be
+ * 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 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 (`Managed inference unavailable${code ? ` (${code})` : ''}: ${describe(err)}. ` +
+        fallbackTail(env));
+}