@cruxy/cli 1.8.1 → 1.9.0

package/dist/cli/commands/login.js

@@ -5,15 +5,27 @@ import { logger } from "../../utils/logger.js";
 import { loadConfig } from "../../config/index.js";
 import { createDefaultDeps, defaultOnboardingIO, runOnboarding, } from "../../onboarding/index.js";
 /**
- * `cruxy login` — set or replace the API key on demand (U.6). Runs the key step
- * of onboarding (always, even if a key already resolves — this is how you
- * re-key / switch), validates it live, and persists it to the credentials store.
+ * `cruxy login` — sign in and persist a credential on demand (U.6). Runs the key
+ * step of onboarding (always, even if a key already resolves — this is how you
+ * re-key / switch) and persists the result to the credentials store.
  * Non-interactive invocations fail loud rather than hang.
+ *
+ * THE DEFAULT IS THE DEVICE FLOW: approve in a browser, and the gateway mints a
+ * subscription-bucket credential that draws on the plan pool the same human's
+ * web chat and desktop already use. A pasted key cannot be one — the admin
+ * issue-key route it comes from refuses to produce that kind — so the paste path
+ * is kept as a fallback rather than the front door.
+ *
+ * `--paste` keeps that fallback reachable, because the device flow cannot serve
+ * every case: an air-gapped machine has no browser to approve in, and someone
+ * deliberately using a long-lived admin key does not want a 90-day device
+ * credential written over it.
  */
 export function loginCommand() {
     return new Command("login")
-        .description("set or replace your API key (validated, saved to ~/.cruxy)")
-        .action(async () => {
+        .description("set or replace your cruxy credential (saved to ~/.cruxy)")
+        .option("--paste", "paste an existing API key instead of approving in a browser")
+        .action(async (opts) => {
         const t = themeForColor(shouldUseColor(process.stdout));
         if (!process.stdin.isTTY) {
             logger.print(t.muted("cruxy login is interactive — run it in a terminal, or export your key as an environment variable."));
@@ -27,6 +39,7 @@ export function loginCommand() {
             forceKey: true,
             offerFirstWin: false,
             offerScaffold: false,
+            preferPaste: opts.paste === true,
             io: defaultOnboardingIO(),
             deps: createDefaultDeps({ config, cwd: process.cwd() }),
         });

package/dist/cli/commands/run.js

@@ -6,7 +6,7 @@ import { logger } from "../../utils/logger.js";
 import { SessionLog, listSessions, loadResume, resolveSessionId, resumePicker, shortId, } from "../../session/index.js";
 /** Sessions shown in the TUI sidebar — the same depth as the resume picker. */
 const SIDEBAR_SESSIONS = 10;
-import { globalDir, loadConfig, resolveApiKey } from "../../config/index.js";
+import { classifyCredentialLifetime, globalDir, loadConfig, readCredentialMeta, resolveApiKey, } from "../../config/index.js";
 import { agentIncomplete, authMissingKey, shouldUseColor, usageError, } from "../../errors/index.js";
 import { createRenderer } from "../../render/index.js";
 import { themeForColor } from "../../theme/index.js";
@@ -388,13 +388,26 @@ export async function executeRun(promptParts, opts) {
     // The cache is still attached without a key so the panel can say "not signed
     // in" — a fact worth stating, and one that costs no request to establish.
     const limitsKey = config.model.provider === "cruxy" ? apiKey : undefined;
+    // The stored expiry of the credential in use, read lazily. It is what lets a
+    // 401 be reported as "your sign-in expired" instead of "your key is wrong" —
+    // the gateway refuses both identically and will not say which.
+    const credentialExpiresAt = () => readCredentialMeta(config.model.provider)?.expiresAt;
     const limits = new LimitsCache(limitsKey === undefined
         ? undefined
         : (signal) => new LimitsClient({
             apiKey: limitsKey,
             gatewayUrl: config.cruxy.gatewayUrl,
-        }).read(signal));
+        }).read(signal), { credentialExpiresAt });
     tui?.attachLimits(limits);
+    // Say it BEFORE the session starts, while a re-login is a 30-second detour
+    // rather than an interruption. A device credential is minted with a finite
+    // lifetime and the gateway echoes it back precisely so a client can do this;
+    // the alternative is the user meeting their expiry mid-turn, as a 401.
+    //
+    // Only when we actually know: an absent or unparseable expiry classifies as
+    // `unknown` and says nothing, which is the right answer for every pasted key
+    // and every credential stored before expiries were recorded.
+    noteCredentialExpiry(credentialExpiresAt());
     // The SAME cache backs the session's weighted-token budget (P10 track 3), so
     // the rail's headroom bar and `/budget`'s server line are one reading rather
     // than two probes that can disagree — and so admission control at the fan-out
@@ -535,3 +548,24 @@ function printRunUsage(record) {
     const t = themeForColor(shouldUseColor(process.stdout));
     logger.print(renderSummary(summarizeRuns([record]), t));
 }
+/**
+ * Warn, once per run and before the session starts, that the stored credential
+ * is about to expire.
+ *
+ * ONLY IN THE `expiring` WINDOW. `live` is silent because a warning 80 days out
+ * is noise that trains people to ignore the line, and `expired` is silent here
+ * because a request is about to fail with a far better message than a preamble
+ * could give — `authExpired` names the date and the fix. `unknown` is silent
+ * because it is the honest state for every pasted key and every credential
+ * stored before expiries were recorded, and nagging those users about a lifetime
+ * nobody ever stated is exactly the false alarm this whole distinction exists to
+ * avoid.
+ */
+function noteCredentialExpiry(expiresAt) {
+    const lifetime = classifyCredentialLifetime(expiresAt);
+    if (lifetime.state !== "expiring")
+        return;
+    const t = themeForColor(shouldUseColor(process.stdout));
+    const days = Math.max(1, Math.round(lifetime.msRemaining / 86_400_000));
+    logger.print(t.warning(`your cruxy sign-in expires in ${days} day${days === 1 ? "" : "s"}`) + t.muted(" — run `cruxy login` to renew it"));
+}

package/dist/config/credential-lifetime.js

@@ -0,0 +1,42 @@
+/**
+ * How close a stored credential is to the end of its life — a pure function of a
+ * timestamp and a clock.
+ *
+ * IT LIVES IN ITS OWN MODULE, AND IMPORTS NOTHING, so that `errors/` can reach
+ * it. `config/credentials.ts` imports `errors/` (for the unprotected-store
+ * refusal), so an error constructor importing the credentials store back would
+ * close a cycle. The rule this module needs to state is not about the store at
+ * all — it is arithmetic on one timestamp — so it sits below both and each side
+ * imports it directly.
+ *
+ * ONE CLASSIFIER, because every caller that acts on expiry must reach the same
+ * verdict from the same value: the 401 classifier deciding whether to say "your
+ * key is wrong" or "your login expired", the pre-session nudge deciding whether
+ * to warn, and the limits panel deciding what to render. Three private
+ * `Date.parse` comparisons would be three chances to disagree about whether a
+ * credential is dead.
+ */
+/**
+ * How long before expiry a credential is worth mentioning.
+ *
+ * Seven days against the gateway's 90-day device-key lifetime: long enough that
+ * someone who uses cruxy weekly sees the notice at least once before anything
+ * breaks, short enough that it is not background noise for the other 83 days.
+ */
+export const CREDENTIAL_EXPIRY_WARNING_MS = 7 * 24 * 60 * 60 * 1000;
+export function classifyCredentialLifetime(expiresAt, now = Date.now(), warnWithinMs = CREDENTIAL_EXPIRY_WARNING_MS) {
+    if (expiresAt === undefined || expiresAt === "")
+        return { state: "unknown" };
+    const at = Date.parse(expiresAt);
+    // A timestamp this build cannot read is a thing we do not know, not a thing
+    // that has happened.
+    if (Number.isNaN(at))
+        return { state: "unknown" };
+    const msRemaining = at - now;
+    if (msRemaining <= 0)
+        return { state: "expired", expiresAt };
+    if (msRemaining <= warnWithinMs) {
+        return { state: "expiring", expiresAt, msRemaining };
+    }
+    return { state: "live", expiresAt, msRemaining };
+}

package/dist/config/credentials.js

@@ -3,8 +3,13 @@ import { dirname, join } from "node:path";
 import { CREDENTIALS_FILE_NAME } from "../constants.js";
 import { credentialsUnprotected } from "../errors/index.js";
 import { logger } from "../utils/logger.js";
+import { classifyCredentialLifetime, } from "./credential-lifetime.js";
 import { enforceOwnerOnly, isOwnerOnly } from "./owner-only.js";
 import { globalDir } from "./paths.js";
+// Re-exported so `config/index.js` remains the one import site for credential
+// concerns; the classifier itself lives in a leaf module that imports nothing,
+// because `errors/` needs it too and this file imports `errors/`.
+export { classifyCredentialLifetime, CREDENTIAL_EXPIRY_WARNING_MS, } from "./credential-lifetime.js";
 /**
  * The credentials store (U.6) — the one place a provider API key is persisted.
  * It lives **outside** `config.json` on purpose: config is secret-free by design
@@ -89,15 +94,76 @@ export function writeMcpCredential(ref, token, file = credentialsPath()) {
         store.mcp[ref] = token;
     }, "mcp");
 }
+/**
+ * What we know about the stored key for `provider`, or `undefined`.
+ *
+ * Tolerant of a store written by a newer build or corrupted by hand: an entry
+ * that is not an object, or whose fields are the wrong type, reads as absent
+ * rather than throwing. This backs an expiry warning, and a warning that can
+ * crash the CLI is worse than no warning. Never throws.
+ */
+export function readCredentialMeta(provider, file = credentialsPath()) {
+    const store = readStore(file);
+    const raw = store?.keyMeta?.[provider];
+    if (raw === null || typeof raw !== "object")
+        return undefined;
+    const entry = raw;
+    const meta = {};
+    if (typeof entry.expiresAt === "string" && entry.expiresAt !== "") {
+        meta.expiresAt = entry.expiresAt;
+    }
+    if (typeof entry.keyId === "string" && entry.keyId !== "") {
+        meta.keyId = entry.keyId;
+    }
+    if (entry.source === "device" || entry.source === "paste") {
+        meta.source = entry.source;
+    }
+    return meta;
+}
 /**
  * Persist `key` for `provider`, merging into any existing store. Written
  * owner-only (see {@link writeInto}); refuses loudly if that can't be enforced.
+ *
+ * A bare write CLEARS any metadata held for that provider, because a write with
+ * nothing to say about the key's lifetime is a statement that we do not know it.
+ * The alternative — leaving whatever was there — is the one way this store can
+ * lie: paste an eternal admin key over a slot a device login used, and the
+ * stale 90-day expiry would have us announce that a perfectly good credential
+ * had died. Key and metadata therefore only ever move together, through
+ * {@link writeCredentialWithMeta}.
  */
 export function writeCredential(provider, key, file = credentialsPath()) {
+    writeCredentialWithMeta(provider, key, {}, file);
+}
+/** Persist `key` for `provider` together with what is known about it. */
+export function writeCredentialWithMeta(provider, key, meta, file = credentialsPath()) {
     writeInto(file, (store) => {
         store.keys[provider] = key;
+        const entry = {};
+        if (meta.expiresAt)
+            entry.expiresAt = meta.expiresAt;
+        if (meta.keyId)
+            entry.keyId = meta.keyId;
+        if (meta.source)
+            entry.source = meta.source;
+        if (Object.keys(entry).length === 0) {
+            // Nothing known. Drop any prior entry rather than keeping a fact about
+            // a key that no longer exists in this slot.
+            if (store.keyMeta) {
+                delete store.keyMeta[provider];
+                if (Object.keys(store.keyMeta).length === 0)
+                    delete store.keyMeta;
+            }
+            return;
+        }
+        store.keyMeta ??= {};
+        store.keyMeta[provider] = entry;
     }, "provider");
 }
+/** The lifetime of the credential currently stored for `provider`. */
+export function credentialLifetime(provider, now = Date.now(), file = credentialsPath()) {
+    return classifyCredentialLifetime(readCredentialMeta(provider, file)?.expiresAt, now);
+}
 /**
  * Merge `mutate` into the store and persist it owner-only. The one write path
  * shared by every credential namespace, and the single place the owner-only

package/dist/errors/boundary.js

@@ -1,5 +1,5 @@
 import { CommanderError } from "commander";
-import { classifyProviderError, internal, usageError } from "./constructors.js";
+import { classifyProviderError, internal, usageError, } from "./constructors.js";
 import { shouldUseColor, terminalFormatter } from "./format.js";
 import { CruxyError } from "./types.js";
 /**
@@ -16,13 +16,13 @@ import { CruxyError } from "./types.js";
  * - a known provider/transport error → its mapped code;
  * - anything else → CRUXY_E_INTERNAL, preserving the original as `underlying`.
  */
-export function fromUnknown(err) {
+export function fromUnknown(err, ctx = {}) {
     if (err instanceof CruxyError)
         return err;
     if (err instanceof CommanderError) {
         return usageError(stripErrorPrefix(err.message));
     }
-    return classifyProviderError(err) ?? internal(err);
+    return classifyProviderError(err, ctx) ?? internal(err);
 }
 /** A Commander "error" that's actually success (`--help`, `--version`). */
 export function isCommanderSuccess(err) {
@@ -34,7 +34,7 @@ export function isCommanderSuccess(err) {
  * touching the real process.
  */
 export function handleFatal(err, opts = {}) {
-    const cruxy = fromUnknown(err);
+    const cruxy = fromUnknown(err, opts.context ?? {});
     const verbose = opts.verbose ?? isVerbose();
     const color = opts.color ?? shouldUseColor();
     const formatter = opts.formatter ?? terminalFormatter;

package/dist/errors/constructors.js

@@ -1,5 +1,9 @@
 import { ApiError, AuthError, BudgetExhaustedError, InvalidRequestError, NetworkError, OverloadedError, RateLimitError, } from "@cruxy/sdk";
 import { scrubModelNames } from "../brand/index.js";
+// Imported from the leaf module DIRECTLY, not via `config/index.js`:
+// `config/credentials.ts` imports this file, so going through the barrel would
+// close an import cycle. `credential-lifetime.ts` imports nothing.
+import { classifyCredentialLifetime } from "../config/credential-lifetime.js";
 import { CruxyError, ErrorCode } from "./types.js";
 /**
  * Helper constructors for {@link CruxyError}. Each encodes the title, the human
@@ -137,11 +141,36 @@ export function authInvalid(underlying) {
         cause: scrubbedMessageOf(underlying),
         nextSteps: [
             "verify your API key is correct and active",
+            "run `cruxy login` to sign in again and replace it",
             "re-export the key and try again",
         ],
         underlying,
     });
 }
+/**
+ * The credential expired. The 401 that surfaced it is byte-identical to the one
+ * a wrong key produces (see {@link ErrorCode.AuthExpired}); what separates them
+ * is the expiry this CLI stored when the key was minted, so this constructor is
+ * only ever reached by a caller that checked it.
+ *
+ * `expiresAt` is echoed because "it expired" invites "when?", and a user who
+ * sees a date three weeks past recognises immediately that this is not a key
+ * they typed wrong today.
+ */
+export function authExpired(expiresAt, underlying) {
+    const when = expiresAt ? ` on ${expiresAt}` : "";
+    return new CruxyError({
+        code: ErrorCode.AuthExpired,
+        title: "your cruxy login has expired",
+        cause: `the stored credential reached the end of its lifetime${when}, and the gateway now refuses it`,
+        nextSteps: [
+            "run `cruxy login` to sign in again — it mints a fresh credential",
+            "or export a long-lived key as CRUXY_API_KEY (the environment always wins over the store)",
+        ],
+        underlying,
+        meta: expiresAt !== undefined ? { expiresAt } : undefined,
+    });
+}
 /**
  * A credential could not be persisted with owner-only permissions, so it was
  * NOT written (C.27c). Chiefly a Windows case: the store's ACL could not be
@@ -360,25 +389,61 @@ export function budgetExhausted(underlying) {
     if (err?.miraAvailable) {
         nextSteps.push("switch to the mira tier, which stays available: `/model mira`");
     }
+    // WHICH CEILING BOUND. The gateway renders three of them through one body,
+    // separated only by `code`, so this is the one place that can tell them apart —
+    // and they take genuinely different advice. "Move to a higher plan" is right
+    // for the subscription pool and WRONG for a per-key cap: a device-login
+    // credential carries its own monthly ceiling stamped on it at mint, and no
+    // plan a user buys will raise it. Saying so anyway sends someone to spend
+    // money on something that cannot fix their problem.
+    const ceiling = err?.apiType;
+    const isKeyCap = ceiling === "key_spend_cap_exceeded";
+    const isWorkspaceCap = ceiling === "workspace_spend_cap_exceeded";
     const window = err?.window === "burst" ? "burst" : err?.window;
-    const windowPhrase = window ? `your ${window} budget window` : "your budget";
+    const windowPhrase = isKeyCap
+        ? "this key's monthly spend cap"
+        : isWorkspaceCap
+            ? "the workspace's monthly spend cap"
+            : window
+                ? `your ${window} budget window`
+                : "your budget";
+    // "resets" for a cap (a calendar ceiling that refills on the 1st) and
+    // "recovers" for the pool (a window that trickles back) — each the verb that
+    // is actually true of the ceiling being described.
+    const verb = isKeyCap || isWorkspaceCap ? "reset" : "recover";
     nextSteps.push(waitMs !== undefined && waitMs > 0
-        ? `wait ~${humanWait(waitMs)} — ${windowPhrase} recovers then`
-        : `wait for ${windowPhrase} to recover`);
-    // Only where it is true. A subscription pool is not something a user can add
-    // to; a plan change is the only lever, and it is a different action from
-    // "top up" with a different place to do it.
-    nextSteps.push("or move to a higher plan for a larger allowance");
+        ? `wait ~${humanWait(waitMs)} — ${windowPhrase} ${verb}s then`
+        : `wait for ${windowPhrase} to ${verb}`);
+    if (isKeyCap) {
+        // Deliberately NOT "run `cruxy login` for a fresh key". A new credential
+        // would carry a new counter, which is cap evasion dressed up as
+        // troubleshooting — and the cap exists to bound a leaked key.
+        nextSteps.push("or ask an org admin to raise this key's spend cap — a plan upgrade does not lift a per-key ceiling");
+    }
+    else if (isWorkspaceCap) {
+        nextSteps.push("or ask an org admin to raise the workspace's spend cap — a plan upgrade does not lift it");
+    }
+    else {
+        // Only where it is true. A subscription pool is not something a user can add
+        // to; a plan change is the only lever, and it is a different action from
+        // "top up" with a different place to do it.
+        nextSteps.push("or move to a higher plan for a larger allowance");
+    }
     return new CruxyError({
         code: ErrorCode.BudgetExhausted,
-        title: window
-            ? `your ${window} Cruxy budget is exhausted`
-            : "your Cruxy budget is exhausted",
+        title: isKeyCap
+            ? "this API key's monthly spend cap is reached"
+            : isWorkspaceCap
+                ? "this workspace's monthly spend cap is reached"
+                : window
+                    ? `your ${window} Cruxy budget is exhausted`
+                    : "your Cruxy budget is exhausted",
         cause: scrubbedMessageOf(underlying),
         nextSteps,
         underlying,
         meta: err
             ? {
+                ...(ceiling !== undefined ? { ceiling } : {}),
                 ...(err.window !== undefined ? { window: err.window } : {}),
                 ...(err.resetAt !== undefined ? { resetAt: err.resetAt } : {}),
                 ...(err.miraAvailable !== undefined
@@ -1502,9 +1567,18 @@ export function agentIncomplete(info) {
  * {@link CruxyError}, or `null` if it isn't one. Order matters: specific
  * subclasses before the `ApiError` base.
  */
-export function classifyProviderError(underlying) {
-    if (underlying instanceof AuthError)
-        return authInvalid(underlying);
+export function classifyProviderError(underlying, ctx = {}) {
+    if (underlying instanceof AuthError) {
+        // An expired credential and a wrong one produce the SAME 401 — the auth gate
+        // refuses both without saying which, so that a prober cannot learn a key was
+        // ever valid. The expiry we recorded at login is the only evidence there is,
+        // and without it a user whose 90-day device login simply ran out is told to
+        // go check a key they never mistyped.
+        const lifetime = classifyCredentialLifetime(ctx.credentialExpiresAt?.(), ctx.now);
+        return lifetime.state === "expired"
+            ? authExpired(lifetime.expiresAt, underlying)
+            : authInvalid(underlying);
+    }
     if (underlying instanceof RateLimitError)
         return apiRateLimit(underlying);
     if (underlying instanceof OverloadedError)

package/dist/errors/types.js

@@ -32,6 +32,23 @@ export const ErrorCode = {
     // auth (exit 4)
     AuthMissingKey: "CRUXY_E_AUTH_MISSING_KEY",
     AuthInvalid: "CRUXY_E_AUTH_INVALID",
+    /**
+     * The stored credential's own lifetime has run out.
+     *
+     * A DISTINCT CODE FROM {@link AuthInvalid} because the two take opposite
+     * advice. "Your key is wrong" sends someone to check what they pasted; this
+     * one is a key that was right, worked for months, and reached the expiry the
+     * server stamped on it at login — the fix is to log in again, and telling that
+     * user to double-check their key sends them looking for a mistake they did not
+     * make.
+     *
+     * IT IS DECIDED CLIENT-SIDE, and it has to be. An expired key falls out of the
+     * auth gate's query exactly as a revoked or fabricated one does, and answers
+     * with the same bare 401 — deliberately, so a prober cannot learn that a key
+     * was ever valid. The server will never say "expired", so the only evidence is
+     * the expiry we stored when the credential was minted.
+     */
+    AuthExpired: "CRUXY_E_AUTH_EXPIRED",
     ForgeAuth: "CRUXY_E_FORGE_AUTH",
     /** A credential could not be persisted with owner-only permissions (C.27c) —
      * e.g. on Windows the store's ACL could not be restricted to the current user
@@ -296,6 +313,7 @@ const EXIT_CODES = {
     [ErrorCode.ConfigInvalid]: 3,
     [ErrorCode.AuthMissingKey]: 4,
     [ErrorCode.AuthInvalid]: 4,
+    [ErrorCode.AuthExpired]: 4,
     [ErrorCode.ForgeAuth]: 4,
     [ErrorCode.CredentialsUnprotected]: 4,
     [ErrorCode.GatewayUnreachable]: 5,

package/dist/index.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { buildProgram } from "./cli/program.js";
+import { loadConfig, readCredentialMeta } from "./config/index.js";
 import { handleFatal, isCommanderSuccess, isVerbose } from "./errors/index.js";
 async function main() {
     const program = buildProgram();
@@ -12,5 +13,30 @@ main().catch((err) => {
     // with the raw stack shown only under --verbose.
     if (isCommanderSuccess(err))
         process.exit(0);
-    handleFatal(err, { verbose: isVerbose() });
+    handleFatal(err, {
+        verbose: isVerbose(),
+        context: {
+            // Resolved LAZILY — the classifier calls this only when the failure turns
+            // out to be a 401, so a run that fails any other way never reads config or
+            // the credentials store.
+            //
+            // It is needed because the gateway refuses an expired credential with
+            // exactly the 401 a wrong one gets, and deliberately will not say which.
+            // The expiry recorded at login is the only thing that can turn "your key
+            // is wrong" into "your login expired, run `cruxy login`".
+            //
+            // Wrapped, because this runs while we are already reporting a failure: an
+            // unreadable config or store here must not replace the user's real error
+            // with a crash inside the error handler.
+            credentialExpiresAt: () => {
+                try {
+                    const { config } = loadConfig();
+                    return readCredentialMeta(config.model.provider)?.expiresAt;
+                }
+                catch {
+                    return undefined;
+                }
+            },
+        },
+    });
 });

package/dist/limits/cache.js

@@ -1,3 +1,4 @@
+import { classifyCredentialLifetime } from "../config/credential-lifetime.js";
 import { reduceLimits } from "./reduce.js";
 /**
  * How long a probe's answer is treated as current. The pool moves when the user
@@ -9,6 +10,7 @@ const MIN_INTERVAL_MS = 15_000;
 export class LimitsCache {
     probe;
     now;
+    credentialExpiresAt;
     minIntervalMs;
     state;
     /** The refresh in flight, so concurrent triggers share one request. */
@@ -23,6 +25,7 @@ export class LimitsCache {
     probe, opts = {}) {
         this.probe = probe;
         this.now = opts.now ?? Date.now;
+        this.credentialExpiresAt = opts.credentialExpiresAt;
         this.minIntervalMs = opts.minIntervalMs ?? MIN_INTERVAL_MS;
         this.state = probe
             ? { status: "pending" }
@@ -76,12 +79,15 @@ export class LimitsCache {
             // moment ago; only report an error when there is nothing else to say.
             if (this.state.status === "ready")
                 return;
-            this.state = { status: "error", reason: classify(err) };
+            this.state = {
+                status: "error",
+                reason: classify(err, this.credentialExpiresAt, this.now()),
+            };
         }
     }
 }
 /**
- * Why the probe failed, in the three distinctions a user can act on.
+ * Why the probe failed, in the distinctions a user can act on.
  *
  * Matched on the SDK's error class names rather than `instanceof`, so this stays
  * a pure classification with no import of the transport into a module the TUI
@@ -89,11 +95,21 @@ export class LimitsCache {
  * serve `/limits` at all — an older deployment, or a base URL pointed somewhere
  * else entirely — and telling that user "you are offline" would send them
  * debugging a network that is working fine.
+ *
+ * A 401 SPLITS ON EVIDENCE THE SERVER DOES NOT PROVIDE. The auth gate refuses an
+ * expired credential with exactly the 401 a wrong one gets, and says nothing
+ * about which — deliberately, so a prober cannot learn that a key was ever
+ * valid. So the split is made from the expiry the CLI recorded at login, and
+ * `expired` is claimed ONLY when that stored timestamp has actually passed:
+ * absence, or a timestamp this build cannot parse, leaves the answer as
+ * `unauthenticated` rather than guessing at a lifetime nobody stated.
  */
-function classify(err) {
+function classify(err, credentialExpiresAt, now) {
     const e = err;
-    if (e?.name === "AuthError")
-        return "unauthenticated";
+    if (e?.name === "AuthError") {
+        const lifetime = classifyCredentialLifetime(credentialExpiresAt?.(), now);
+        return lifetime.state === "expired" ? "expired" : "unauthenticated";
+    }
     if (e?.status === 404 || e?.status === 501)
         return "unsupported";
     return "unreachable";

package/dist/onboarding/flow.js

@@ -1,8 +1,8 @@
-import { AuthError, NetworkError, createProvider } from "@cruxy/sdk";
+import { AuthError, DeviceLoginClient, NetworkError, createProvider, } from "@cruxy/sdk";
 import { themeForColor } from "../theme/index.js";
-import { resolveApiKey, writeCredential } from "../config/index.js";
+import { apiKeyEnvVar, readCredential, resolveApiKey, writeCredential, writeCredentialWithMeta, } from "../config/index.js";
 import { newOnboardingState, readOnboardingState, writeOnboardingState, } from "./detect.js";
-import { acquireKeyStep, firstWinStep, scaffoldStep } from "./steps.js";
+import { acquireKeyStep, deviceLoginStep, firstWinStep, scaffoldStep, } from "./steps.js";
 /**
  * Orchestrate the onboarding steps (U.6) — resumable and idempotent. The key
  * step is skipped when a key already resolves; the completion marker is written
@@ -17,14 +17,27 @@ export async function runOnboarding(opts) {
     let apiKey = deps.resolveApiKey(provider);
     // ── key (mandatory; skipped if already resolvable unless forceKey) ─────────
     if (!apiKey || opts.forceKey) {
-        const result = await acquireKeyStep(io, deps, provider);
+        warnAboutOverwrite(io, deps);
+        // Device login is the default; paste stays reachable behind `--paste`, and
+        // is the only path when there is no device flow to run (a non-cruxy
+        // provider, whose keys these gateway routes know nothing about).
+        const useDevice = !opts.preferPaste && deps.deviceLogin !== undefined;
+        const result = useDevice
+            ? await deviceLoginStep(io, deps, provider)
+            : await acquireKeyStep(io, deps, provider);
         if (result.status === "aborted") {
             return { completed: false, aborted: true };
         }
         if (result.status !== "ok") {
-            // Failed (unreachable / rejected) — surface guidance, no marker.
+            // Failed (unreachable / rejected / declined) — surface guidance, no marker.
             if (result.message)
                 io.write(`${t.muted(result.message)}\n`);
+            if (useDevice) {
+                // The paste path exists for exactly the cases the device flow cannot
+                // serve, and someone who has just watched it fail is precisely who needs
+                // to know it is there.
+                io.write(t.muted("if you can't approve in a browser, `cruxy login --paste` takes a key directly.\n"));
+            }
             return { completed: false, aborted: false };
         }
         apiKey = result.apiKey;
@@ -46,14 +59,53 @@ export async function runOnboarding(opts) {
     io.write(`${t.success(t.strong(`${t.glyph.success} all set`))} — happy hacking.\n`);
     return { completed: true, aborted: false, apiKey };
 }
+/**
+ * Say, BEFORE anything is overwritten, the two things a login silently does.
+ *
+ * Both are facts a user cannot see and would otherwise discover the hard way:
+ * that this replaces a saved credential with no undo, and that an exported key
+ * will go on winning over whatever is saved here, so a perfectly successful
+ * login can change nothing at all about the next request.
+ */
+function warnAboutOverwrite(io, deps) {
+    const t = themeForColor(io.color);
+    const status = deps.credentialStatus?.();
+    if (!status)
+        return;
+    if (status.storedKey) {
+        io.write(t.muted("\nthis replaces the credential currently saved in ~/.cruxy — there is no undo.\n"));
+    }
+    if (status.shadowingEnvVar) {
+        io.write(t.warning(`\n${status.shadowingEnvVar} is set in your environment, and the environment always wins over the saved credential.\n`) +
+            t.muted(`whatever you sign in with will be saved, but your requests will keep using ${status.shadowingEnvVar} until you unset it.\n`));
+    }
+}
 /**
  * Build the production {@link OnboardingDeps}: live gateway validation, the
  * credentials store, real state persistence, and a wall-clock timestamp.
  */
 export function createDefaultDeps(opts) {
+    const provider = opts.config.model.provider;
+    // ONLY ON THE CRUXY PROVIDER, on the same reasoning `run.ts` uses to gate the
+    // limits probe: `/device/*` are cruxy gateway routes, and a
+    // bring-your-own-provider setup has no notion of them. Pointing them at
+    // someone else's base URL would be a request to a stranger — so there is no
+    // device flow to offer, and the key step falls through to the paste prompt.
+    const deviceLogin = provider === "cruxy"
+        ? (io) => runDeviceLogin(opts.config, io)
+        : undefined;
     return {
-        validateKey: (provider, apiKey) => validateKeyLive(provider, apiKey, opts.config),
+        validateKey: (p, apiKey) => validateKeyLive(p, apiKey, opts.config),
         writeCredential,
+        writeCredentialWithMeta,
+        ...(deviceLogin ? { deviceLogin } : {}),
+        credentialStatus: () => {
+            const envVar = apiKeyEnvVar(provider);
+            return {
+                storedKey: readCredential(provider) !== undefined,
+                ...(process.env[envVar] ? { shadowingEnvVar: envVar } : {}),
+            };
+        },
         resolveApiKey,
         readState: () => readOnboardingState(),
         writeState: (state) => writeOnboardingState(state),
@@ -62,6 +114,69 @@ export function createDefaultDeps(opts) {
         now: () => new Date().toISOString(),
     };
 }
+/**
+ * Drive one real device login against the gateway.
+ *
+ * Everything that can go wrong on the wire collapses to `unreachable` here,
+ * because from the user's seat there is one answer to all of it — try again —
+ * and the flow's own outcomes (denied, expired, invalid) are the states that
+ * genuinely differ. The credential is returned, never written: persisting is the
+ * step's job, so there is exactly one place that decides what lands in the store.
+ */
+async function runDeviceLogin(config, io) {
+    const client = new DeviceLoginClient({ gatewayUrl: config.cruxy.gatewayUrl });
+    let session;
+    try {
+        session = await client.start();
+    }
+    catch (err) {
+        return { status: "unreachable", message: unreachableMessage(err) };
+    }
+    io.prompt({
+        userCode: session.userCode,
+        verificationUri: session.verificationUri,
+        ...(session.verificationUriComplete !== undefined
+            ? { verificationUriComplete: session.verificationUriComplete }
+            : {}),
+        expiresInMs: session.expiresInMs,
+    });
+    let outcome;
+    try {
+        outcome = await client.poll(session, {
+            onProgress: (p) => io.waiting({
+                remainingMs: p.remainingMs,
+                ...(p.throttled !== undefined ? { throttled: p.throttled } : {}),
+            }),
+        });
+    }
+    catch (err) {
+        return { status: "unreachable", message: unreachableMessage(err) };
+    }
+    switch (outcome.status) {
+        case "approved":
+            return {
+                status: "ok",
+                apiKey: outcome.credential.accessToken,
+                ...(outcome.credential.expiresAt !== undefined
+                    ? { expiresAt: outcome.credential.expiresAt }
+                    : {}),
+                ...(outcome.credential.keyId !== undefined
+                    ? { keyId: outcome.credential.keyId }
+                    : {}),
+            };
+        case "denied":
+            return { status: "denied" };
+        case "expired":
+            return { status: "expired" };
+        case "invalid":
+            return { status: "invalid" };
+    }
+}
+function unreachableMessage(err) {
+    return err instanceof NetworkError
+        ? "couldn't reach the gateway — check your connection and run `cruxy login` again"
+        : "the gateway answered unexpectedly — run `cruxy login` to try again";
+}
 /**
  * Validate a key with one cheap live call: start a 1-token stream and look at the
  * first event. `AuthError` ⇒ invalid (bad key), `NetworkError` ⇒ unreachable;

package/dist/onboarding/steps.js

@@ -8,6 +8,118 @@ import { loadProjectInstructions, scaffoldProjectInstructions, } from "../config
  */
 const MAX_KEY_ATTEMPTS = 3;
 const c = (io) => themeForColor(io.color);
+/**
+ * Sign in by approving in a browser — the default path.
+ *
+ * WHY IT IS THE DEFAULT, and why it is not merely a nicer prompt: a pasted key
+ * is minted through the admin issue-key route, which cannot produce a
+ * subscription credential — asking for one there is explicitly refused. So every
+ * pasted CLI key lands in the metered `apikey` bucket with no token pool, while
+ * the same human's web chat and desktop draw on their plan. One human, two
+ * budgets. The device flow mints through the login issuer, which is the only
+ * path to the subscription bucket, so the credential it produces draws on the
+ * pool the user already has.
+ *
+ * THE KEY IS NOT RE-VALIDATED. The gateway minted it seconds ago and returned it
+ * over the same connection; a `validateKey` call here would spend a real,
+ * billable request to re-prove a fact we were just told — against the very pool
+ * this step exists to establish. The paste path validates because there a key is
+ * an unverified claim by the user; here it is the gateway's own answer.
+ *
+ * Every outcome is reported, never thrown: a denial and an expiry are the flow
+ * working correctly, and both leave the existing credential untouched.
+ */
+export async function deviceLoginStep(io, deps, provider) {
+    const col = c(io);
+    if (!deps.deviceLogin)
+        return { status: "skipped" };
+    const outcome = await deps.deviceLogin(deviceIO(io));
+    switch (outcome.status) {
+        case "ok": {
+            deps.writeCredentialWithMeta(provider, outcome.apiKey, {
+                ...(outcome.expiresAt !== undefined
+                    ? { expiresAt: outcome.expiresAt }
+                    : {}),
+                ...(outcome.keyId !== undefined ? { keyId: outcome.keyId } : {}),
+                source: "device",
+            });
+            io.write(`${col.success(col.glyph.success)} signed in — credential saved to ~/.cruxy\n`);
+            if (outcome.expiresAt) {
+                io.write(col.muted(`  it expires on ${formatExpiry(outcome.expiresAt)}; run \`cruxy login\` again before then.\n`));
+            }
+            return {
+                status: "ok",
+                apiKey: outcome.apiKey,
+                ...(outcome.expiresAt !== undefined
+                    ? { expiresAt: outcome.expiresAt }
+                    : {}),
+                ...(outcome.keyId !== undefined ? { keyId: outcome.keyId } : {}),
+            };
+        }
+        case "denied":
+            io.write(`${col.danger(col.glyph.failure)} the sign-in was declined in the browser.\n`);
+            return { status: "failed", message: "sign-in declined" };
+        case "expired":
+            io.write(`${col.danger(col.glyph.failure)} the code expired before it was approved.\n`);
+            return {
+                status: "failed",
+                message: "the code expired — run `cruxy login` to get a new one",
+            };
+        case "invalid":
+            // The gateway collapses four causes into one code on purpose and tells us
+            // nothing about which; all four are answered by starting over.
+            io.write(`${col.danger(col.glyph.failure)} that sign-in could not be completed.\n`);
+            return {
+                status: "failed",
+                message: "sign-in could not be completed — run `cruxy login` to retry",
+            };
+        case "unreachable":
+            io.write(`${col.danger(col.glyph.failure)} couldn't reach the gateway to sign in.\n`);
+            return { status: "failed", message: outcome.message };
+    }
+}
+/** Render the device flow's two messages onto the onboarding IO. */
+function deviceIO(io) {
+    const col = c(io);
+    let lastNote = "";
+    return {
+        prompt: (session) => {
+            const link = session.verificationUriComplete ?? session.verificationUri;
+            io.write(`\nTo sign in, open ${col.accent(link)}\n` +
+                `and enter the code ${col.strong(session.userCode)}\n\n` +
+                col.muted(`waiting for approval (expires in ${humanDuration(session.expiresInMs)})…\n`));
+        },
+        waiting: (info) => {
+            // Only the throttle is worth saying out loud, and only once: a line per
+            // poll would scroll a quiet wait off the screen, and "still waiting" adds
+            // nothing to the "waiting for approval" already on it.
+            if (!info.throttled || lastNote === "throttled")
+                return;
+            lastNote = "throttled";
+            io.write(col.muted("  the gateway asked us to slow down; still waiting…\n"));
+        },
+    };
+}
+/** "2 days", "9 minutes" — coarse on purpose; this is a reassurance, not a timer. */
+function humanDuration(ms) {
+    const minutes = Math.round(ms / 60_000);
+    if (minutes < 1)
+        return "less than a minute";
+    if (minutes < 60)
+        return `${minutes} minute${minutes === 1 ? "" : "s"}`;
+    const hours = Math.round(minutes / 60);
+    if (hours < 24)
+        return `${hours} hour${hours === 1 ? "" : "s"}`;
+    const days = Math.round(hours / 24);
+    return `${days} day${days === 1 ? "" : "s"}`;
+}
+/** The date part of an RFC 3339 expiry, or the raw string if it will not parse. */
+function formatExpiry(expiresAt) {
+    const at = Date.parse(expiresAt);
+    if (Number.isNaN(at))
+        return expiresAt;
+    return new Date(at).toISOString().slice(0, 10);
+}
 /**
  * Acquire and persist a provider key: print the create-key URL, read it masked,
  * validate it live, and **only then** write it to the credentials store. Loops on

package/dist/tui/limits-panel.js

@@ -241,6 +241,15 @@ export function limitsPanelLines(theme, state, now = Date.now()) {
         switch (state.reason) {
             case "unauthenticated":
                 return [theme.muted("not signed in"), theme.muted("run cruxy login")];
+            case "expired":
+                // The same remedy as "not signed in", but a different fact — and the
+                // fact is the point. "Sign-in expired" tells someone their setup was
+                // right and simply aged out; "not signed in" invites them to go looking
+                // for what they configured wrong.
+                return [
+                    theme.warning("sign-in expired"),
+                    theme.muted("run cruxy login"),
+                ];
             case "unsupported":
                 // The gateway answered — it simply has no limits to report. Sending this
                 // user to debug their network would be the wrong errand entirely.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cruxy/cli",
-  "version": "1.8.1",
+  "version": "1.9.0",
   "description": "an agentic coding CLI",
   "type": "module",
   "bin": {
@@ -36,7 +36,7 @@
     "undici": "^6.21.0",
     "zod": "^3.23.8",
     "zod-to-json-schema": "^3.23.5",
-    "@cruxy/sdk": "0.6.0"
+    "@cruxy/sdk": "0.7.0"
   },
   "optionalDependencies": {
     "better-sqlite3": "^12.11.1"