@cruxy/cli 1.8.0 → 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

@@ -3,10 +3,10 @@ import { randomUUID } from "node:crypto";
 import { LimitsClient } from "@cruxy/sdk";
 import { LimitsCache } from "../../limits/index.js";
 import { logger } from "../../utils/logger.js";
-import { SessionLog, listSessions, resumeById, resumePicker, shortId, } from "../../session/index.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";
@@ -56,6 +56,56 @@ export async function executeRun(promptParts, opts) {
     const t = themeForColor(shouldUseColor(process.stdout));
     const invokedAs = opts.commandName ?? "cruxy run";
     const interactive = prompt === "";
+    // ORDER OF COMPLAINTS (#172 item 3). Three things can refuse this run before
+    // it starts, and they are checked most-specific first:
+    //
+    //   1. a bad `--root`            (the workspace cannot even be built)
+    //   2. a bad `--resume <id>`     (the session named does not exist)
+    //   3. no prompt, and no TTY     (nothing to do, no way to be asked)
+    //
+    // The terminal check USED to come first, which meant
+    // `cruxy --resume no-such-id < /dev/null` was told to add a message — advice
+    // that, followed, only surfaces the real error one run later. `program.ts`
+    // deliberately routes `--resume` past the guidance banner so a bad id fails
+    // loud; the guard sitting in front of it undid exactly that.
+    //
+    // The tradeoff this reordering accepts: `--root` errors now precede the
+    // terminal message too, because id validation needs `primaryRoot` and so the
+    // workspace has to be built first. That is the right way round — a
+    // non-existent root is a more specific complaint than "needs a terminal", and
+    // it was already the first thing to fail on every OTHER path.
+    //
+    // The guard is NOT simply moved below resume resolution instead. That would
+    // put `loadConfig` and the missing-key check in front of it, so a keyless
+    // non-TTY run would be told to authenticate rather than that it has nothing
+    // to do — trading one misleading diagnostic for another.
+    // Declared workspace roots (C.26). This is the ONE place `run` reads the
+    // process working directory — the invocation directory is the base for
+    // resolving `--root` paths and the sole root when none are declared. Every
+    // subsystem below derives its cwd from the WORKSPACE (`primaryRoot`), never
+    // re-reads the invocation directory, so nothing can silently split-brain to
+    // a different dir than the roots the tools see (the guard test pins this).
+    const invocationCwd = process.cwd();
+    // No --root → a trivial single-root workspace (byte-identical to pre-C.26).
+    // --root builds a genuine multi-root Workspace and fails fast HERE — a
+    // missing / non-dir / overlapping root (CRUXY_E_ROOT_OVERLAP) throws before
+    // onboarding or the session starts, never a half-built session.
+    const workspace = opts.root.length
+        ? await buildWorkspace(opts.root, { cwd: invocationCwd })
+        : sessionWorkspace(invocationCwd);
+    const primaryRoot = workspace.primary().absPath;
+    // VALIDATION ONLY — deliberately not the load. `resolveSessionId` answers
+    // "does this id name a session?" from one meta line per file; the replay that
+    // actually restores the conversation happens far below, once we know the run
+    // is going to proceed. A valid `--resume <id> < /dev/null` with no message is
+    // still going to be turned away by the guard just below, and it should not
+    // have paid for a full `replaySession` to get there.
+    //
+    // Bare `--resume` (no id) cannot be validated here and is not: the picker
+    // needs a terminal, so it stays below the guard where it has always been.
+    const resumeTarget = typeof opts.resume === "string" && opts.resume !== ""
+        ? resolveSessionId(primaryRoot, opts.resume)
+        : null;
     // No prompt and stdin isn't a terminal: there's no way to read input and
     // nothing to do — fail fast instead of hanging on a line that never comes.
     //
@@ -78,21 +128,6 @@ export async function executeRun(promptParts, opts) {
     const loaded = loadConfig();
     const { config, sources } = loaded;
     let apiKey = resolveApiKey(config.model.provider);
-    // Declared workspace roots (C.26). This is the ONE place `run` reads the
-    // process working directory — the invocation directory is the base for
-    // resolving `--root` paths and the sole root when none are declared. Every
-    // subsystem below derives its cwd from the WORKSPACE (`primaryRoot`), never
-    // re-reads the invocation directory, so nothing can silently split-brain to
-    // a different dir than the roots the tools see (the guard test pins this).
-    const invocationCwd = process.cwd();
-    // No --root → a trivial single-root workspace (byte-identical to pre-C.26).
-    // --root builds a genuine multi-root Workspace and fails fast HERE — a
-    // missing / non-dir / overlapping root (CRUXY_E_ROOT_OVERLAP) throws before
-    // onboarding or the session starts, never a half-built session.
-    const workspace = opts.root.length
-        ? await buildWorkspace(opts.root, { cwd: invocationCwd })
-        : sessionWorkspace(invocationCwd);
-    const primaryRoot = workspace.primary().absPath;
     logger.info(t.muted(`model:   ${config.model.provider}/${config.model.model}`));
     logger.info(t.muted(`config:  ${sources.project ?? sources.global ?? "defaults"}`));
     // Multi-root honesty (JC-6/C.26): reads fan every root. With per-root
@@ -147,10 +182,12 @@ export async function executeRun(promptParts, opts) {
     // a repo moved would be worse than saying so plainly.
     let resumed = null;
     if (opts.resume !== undefined && opts.resume !== false) {
-        resumed =
-            typeof opts.resume === "string" && opts.resume !== ""
-                ? resumeById(primaryRoot, opts.resume)
-                : await resumePicker(primaryRoot, { logger });
+        // `resumeTarget` is the id already validated above the guard; loading it is
+        // all that is left. Bare `--resume` resolves here, where the TTY it needs is
+        // guaranteed — the guard above turned away every run that lacked one.
+        resumed = resumeTarget
+            ? loadResume(resumeTarget, primaryRoot)
+            : await resumePicker(primaryRoot, { logger });
         if (resumed) {
             for (const warning of resumed.warnings)
                 logger.warn(warning);
@@ -351,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
@@ -498,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";