@cruxy/cli 1.8.1 → 1.10.0

package/dist/jobs/manager.js

@@ -1,7 +1,11 @@
 import { runAgent } from "../agent/loop.js";
-import { ApprovalService, classify, serializeGate, } from "../approval/index.js";
+import { ApprovalService, classify, InteractivePolicy, serializeGate, SessionAllowlist, } from "../approval/index.js";
 import { CheckpointGate, withCheckpointGate } from "../checkpoint/index.js";
-import { CruxyError, ErrorCode, approvalRequired, jobLimitExceeded, jobNotFound, jobsDisabled, messageOf, } from "../errors/index.js";
+import { compactTokens } from "../render/units.js";
+import { CruxyError, ErrorCode, approvalRequired, jobLimitExceeded, jobNotFound, jobsDisabled, messageOf, poolDenial, sessionBudgetExhausted, } from "../errors/index.js";
+import { resolveTaskModel } from "../routing/index.js";
+import { UNRESOLVED_TIER } from "../budget/index.js";
+import { UsageCollector } from "../usage/index.js";
 import { Budget, resolveBudget } from "../agent/budget.js";
 import { scopeRegistry } from "../subagent/index.js";
 import { Workspace } from "../workspace/index.js";
@@ -10,6 +14,33 @@ import { JobLogRenderer } from "./log-renderer.js";
 import { isTerminal } from "./types.js";
 /** Longest task excerpt kept as a job label (display, not record). */
 const LABEL_MAX = 60;
+/**
+ * THE ADMISSION FLOOR, in whole requests' worth of fixed payload (cli#245).
+ *
+ * `Budget.exceeded` is checked BEFORE each model turn against the run's
+ * cumulative tokens, so a job's first request always goes out whatever its
+ * ceiling is: at iteration 0 the usage is zero and no cap can trip. A ceiling
+ * the pool narrowed down to a few hundred tokens therefore buys exactly one
+ * request — the system prompt and the whole tool catalogue re-sent, real
+ * weighted tokens drawn from a window that is already refusing — and then stops
+ * the run at the next boundary with `token cap reached`, which `statusFor` maps
+ * to `failed`. The job dispatches, the model is told it started, and it dies a
+ * second later having produced nothing and spent something.
+ *
+ * TWO, not one, and `context.reserveTokens` (4500 by default) is the unit
+ * because it is the figure this repo already keeps for exactly this quantity:
+ * "the built system prompt plus the default tool catalogue". One request's worth
+ * buys a job a single model turn it cannot act on — it can call a tool and never
+ * see the result. Two is the smallest ceiling under which a job can complete one
+ * act-and-report cycle, which is the least a background job can do and still be
+ * worth the tokens. It is a FLOOR and not a promise: input is re-sent every
+ * turn, so two turns cost more than twice the fixed payload.
+ *
+ * Derived from config rather than a literal, so it tracks the prompt: a build
+ * whose catalogue grows raises the floor with it. A config that sets
+ * `reserveTokens` to 0 states that there is no fixed payload, and floors nothing.
+ */
+const MIN_JOB_REQUESTS = 2;
 /**
  * Session-scoped background jobs (C.28). The main agent dispatches a job with
  * `run_in_background`; it runs the SAME agent loop as a subagent but CONCURRENTLY
@@ -32,6 +63,8 @@ export class JobManager {
     idFactory;
     now;
     runAgentFn;
+    /** The last pool denial a job died on, until the foreground takes it. */
+    poolDenied;
     seq = 0;
     constructor(deps) {
         this.deps = deps;
@@ -43,9 +76,21 @@ export class JobManager {
     }
     /**
      * Dispatch a background job (the `run_in_background` seam). Fails loud when the
-     * feature is disabled, when the live-job ceiling is reached, or when a named
-     * root is unknown — all BEFORE the job is registered, so a refused dispatch
-     * leaves no ghost. Returns a view immediately; the job runs asynchronously.
+     * feature is disabled, when the live-job ceiling is reached, when a named
+     * root is unknown, or when the session's weighted budget will not cover the
+     * job — all BEFORE the job is registered, so a refused dispatch leaves no
+     * ghost. Returns a view immediately; the job runs asynchronously.
+     *
+     * ADMISSION HAPPENS HERE, NOT IN `execute` (cli#245). A queued job can sit
+     * behind the shared semaphore for a long time, so "does it fit now" and "does
+     * it fit when it runs" are genuinely different questions when the pool is
+     * moving — and this is the only one of the two the model can be told the
+     * answer to. `dispatch` is synchronous and already throws three coded
+     * refusals that `dispatch-tool.ts` converts into a tool error; a budget
+     * refusal is that same shape, needing no new mechanism. `execute` has no
+     * error channel back to the model at all — only `job.status`, read by a human
+     * later — and by then the turn that dispatched has long returned, having
+     * already been told the job started.
      */
     dispatch(spec) {
         const { config } = this.deps;
@@ -58,7 +103,13 @@ export class JobManager {
         // Resolve (and validate) the job's scope up front — an unknown root name
         // throws CRUXY_E_ROOT_UNKNOWN here, which the dispatch tool surfaces to the
         // model, rather than failing silently inside the background run.
+        //
+        // Before the budget check, deliberately, and for the reason the fan-out
+        // seam orders its two checks the same way: a job naming a root that does
+        // not exist is MALFORMED, and answering it with "your budget is used up"
+        // would report a ceiling instead of the typo.
         const scope = this.jobScope(spec.root);
+        const limits = this.admit(spec);
         const id = this.idFactory();
         const checkpoints = config.checkpoint.enabled
             ? new CheckpointGate({
@@ -78,6 +129,7 @@ export class JobManager {
             controller: new AbortController(),
             checkpoints,
             scope,
+            limits,
             holdsSlot: false,
         };
         this.jobs.set(id, job);
@@ -177,6 +229,14 @@ export class JobManager {
     /** Drive one job to completion, mapping every outcome onto its status. */
     async execute(job) {
         const signal = job.controller.signal;
+        // Per-request usage for THIS job, collected exactly as the parent's turn and
+        // a subagent collect their own. Needed rather than `result.usage` for two
+        // reasons: the weighted arithmetic is per-tier, and a run that THREW has no
+        // result at all while still having spent whatever it spent before it died.
+        // Origin `"job"` on every entry (cli#244): this record is published to the
+        // store in its own right, so its entries have to say what they were.
+        const usage = new UsageCollector(undefined, "job");
+        const startedAt = new Date().toISOString();
         try {
             // Wait for an execution permit — a queued job holds none until a slot frees
             // (the shared cap, contended with subagents). This is the queued→running
@@ -192,7 +252,7 @@ export class JobManager {
             // NEVER again (a pause is not a checkpoint boundary), so pre- and post-pause
             // mutations coalesce and `cruxy rollback <id>` reverts the whole job.
             job.checkpoints?.beginRun(job.spec.task, job.id);
-            const result = await this.runAgentFn(this.runArgs(job, signal));
+            const result = await this.runAgentFn(this.runArgs(job, signal, usage));
             job.iterations = result.iterations;
             job.usage = result.usage;
             job.summary = lastAssistantText(result.messages);
@@ -213,8 +273,31 @@ export class JobManager {
                 job.error = `${err.code}: ${err.title}`;
             }
             else {
+                // THE WEIGHTED POOL REFUSED THIS JOB (429 `budget_exhausted`), and it is
+                // not a per-job outcome (cli#245). Two things used to be lost here, and
+                // they are the same two the fan-out seam recovered in cli#243.
+                //
+                // First the FACTS: `messageOf` flattened the typed error to a string, so
+                // `window`, `resetAt` and `miraAvailable` went with it — the last of
+                // which is the only one that unblocks someone now rather than telling
+                // them when to come back — and a job that died on a 429 read like any
+                // other failure in `/jobs`.
+                //
+                // Second the AUDIENCE. A pool denial is a statement about a denominator
+                // this job shares with the foreground turn, so the foreground is
+                // entitled to it: without the latch the job dies quietly off-screen and
+                // the user walks into their own refusal on the next turn, having been
+                // told nothing. It is the same "N denials for one fact" argument #243
+                // made across siblings, carried across the job/foreground boundary.
+                const denial = poolDenial(err);
                 job.status = "failed";
-                job.error = `${ErrorCode.SubagentFailed}: ${messageOf(err) ?? "unknown error"}`;
+                job.error = denial
+                    ? denialLine(denial)
+                    : `${ErrorCode.SubagentFailed}: ${messageOf(err) ?? "unknown error"}`;
+                if (denial) {
+                    this.poolDenied = denial;
+                    this.abortSiblings(job, denial);
+                }
             }
         }
         finally {
@@ -222,21 +305,90 @@ export class JobManager {
                 this.deps.semaphore.release();
                 job.holdsSlot = false;
             }
+            // JOB SPEND IS SESSION SPEND (cli#245), and in the `finally` because the
+            // tokens are spent on every path out of here — a job that failed, was
+            // cancelled at session exit, or died on a 429 still drew whatever it drew
+            // before it stopped. Without this the admission check above reads a
+            // numerator its own dispatches never move, and a job running across an
+            // idle period stays invisible to `/budget` for the rest of the session.
+            //
+            // AND NOW ALSO WRITTEN TO THE USAGE STORE (cli#244 answered the question
+            // this call site used to defer). One record, handed to both sinks, so
+            // `/budget` and `/usage` can never disagree about what this job drew.
+            //
+            // `job.id` is the run id — stable, already unique, and the thing the user
+            // saw in `/jobs`, so a record in the store can be traced back to the job
+            // that made it rather than to an anonymous UUID.
+            //
+            // The session id is read HERE rather than at construction: see the note on
+            // `sessionId`. Without it the record persists and then hides from every
+            // session-scoped read of the very store it is in.
+            const record = usage.toRecord(job.id, this.deps.sessionId?.(), startedAt);
+            this.deps.budget?.record(record);
+            // Empty records are not published. A job that was cancelled before it
+            // reached the model spent nothing, and a run of no requests is not a run —
+            // it would only pad `runCount` and shorten retention for nothing.
+            if (record.entries.length > 0)
+                this.deps.onRunUsage?.(record);
             this.log(job, "out", `job ${job.status}`);
         }
     }
+    /**
+     * The pool denial a job died on, handed over ONCE (cli#245).
+     *
+     * A latch rather than a push: the foreground drains it where it is idle —
+     * between turns, next to the pending-approval drain — so a background failure
+     * never writes into a live region a turn is painting, and never lands
+     * mid-stream in a shell that is reading a line.
+     *
+     * The newest denial wins. Two jobs refused by one exhausted window are one
+     * fact, and printing it twice is the flood #243 aborted a batch to avoid.
+     */
+    takePoolDenial() {
+        const denial = this.poolDenied;
+        this.poolDenied = undefined;
+        return denial;
+    }
+    /**
+     * ONE POOL DENIAL STOPS EVERY OTHER LIVE JOB (cli#245) — the batch abort #243
+     * made across siblings, carried to the job seam, because the argument is
+     * identical and the denominator is literally the same one.
+     *
+     * A 429 is not a fact about the job that received it. It is a fact about a
+     * window every live job draws on, so the other jobs are not in a different
+     * situation — they are in the same one, a few seconds behind. Left running,
+     * each spends its way to its own refusal: three concurrent jobs discovering
+     * one exhausted window produce three failed jobs, three wasted partial runs,
+     * and three denials for a single fact. Aborting makes the FIRST denial the
+     * session's answer, which is what {@link takePoolDenial} then reports once.
+     *
+     * `abort` and not a status write, so a job stops at its next TURN boundary
+     * exactly as `cruxy cancel` stops it: the in-flight request completes,
+     * whatever checkpoint it took survives for rollback, and its slot is released
+     * through the same `finally`. Aborted jobs land on the `signal.aborted` branch
+     * above and end `cancelled` — honest, and distinct from the one job that
+     * actually was refused, which ends `failed` carrying the denial. They do not
+     * re-latch: the one denial stays the one denial.
+     *
+     * Queued jobs are aborted too. A job still waiting for a slot has spent
+     * nothing yet, and dispatching it into a window that just refused its sibling
+     * is the clearest waste of the set.
+     */
+    abortSiblings(source, denial) {
+        for (const job of this.jobs.values()) {
+            if (job === source || isTerminal(job.status))
+                continue;
+            this.log(job, "out", `cancelling: ${denial.code} — job ${source.id} was refused by the weighted pool`);
+            this.abort(job);
+        }
+    }
     /** Build the {@link runAgent} args for a job: scoped registry, budget, ctx. */
-    runArgs(job, signal) {
+    runArgs(job, signal, usage) {
         const { deps } = this;
         const registry = scopeRegistry(deps.parentRegistry, job.spec.tools);
-        const budget = new Budget(resolveBudget(deps.config.subagent.defaultBudget, {
-            ...(job.spec.budget?.maxIterations !== undefined
-                ? { maxIterations: job.spec.budget.maxIterations }
-                : {}),
-            ...(job.spec.budget?.maxTokens !== undefined
-                ? { maxTokens: job.spec.budget.maxTokens }
-                : {}),
-        }));
+        // The caps admission settled at dispatch — resolved there, not here, so a
+        // ceiling the budget cut is the ceiling the run actually executes under.
+        const budget = new Budget(job.limits);
         const ctx = {
             cwd: job.scope.cwd,
             workspace: job.scope.workspace,
@@ -262,6 +414,7 @@ export class JobManager {
             router: deps.router,
             taskClass: "subagent",
             signal,
+            onRequestUsage: (req) => usage.record(req),
         };
     }
     /**
@@ -277,10 +430,18 @@ export class JobManager {
     makeJobApproval(job) {
         const { approvalQueue, semaphore, approvalMutex, foregroundInteractive } = this.deps;
         const cwd = job.scope.cwd;
+        // THE session allowlist a job's grants actually accumulate in (cli#251).
+        // A job has no factory-built allowlist to share — a child gets the parent's
+        // MODE but not its grants (P5 track 3) — so "allow for this session" taken
+        // inside a job lands here and is spent by this policy alone, for this job's
+        // lifetime. The service used to build this line for us when no policy was
+        // passed, which meant the single call site where the allowlist is
+        // load-bearing looked identical to the ones where it is inert. Written out
+        // so the ownership is readable here rather than inferred from an absence.
         const interactive = new ApprovalService({
             cwd,
             interactive: foregroundInteractive,
-            io: this.deps.promptIO,
+            policy: new InteractivePolicy(new SessionAllowlist(), this.deps.promptIO),
         });
         // The foreground-serviced decision: the interactive U.3 prompt, wrapped in
         // THIS job's checkpoint hook, serialized on the SHARED approval mutex — so a
@@ -321,6 +482,83 @@ export class JobManager {
             }
         };
     }
+    /**
+     * Ask the session budget whether this job fits, and return the caps it may run
+     * under (P10 track 3 / cli#245).
+     *
+     * THE VERDICT HAS ONLY TWO SHAPES HERE, because a job is dispatched ONE at a
+     * time. `spawnMany` can be told "three of your five fit" and hands the parent
+     * a positional `not-admitted` result for each of the two that did not; a
+     * single dispatch has no such slot and needs none — `admit` with `count: 1`
+     * either allows, or narrows to that one run with its token ceiling cut to
+     * what the allowance covers, or refuses outright — and a narrowed ceiling
+     * below the floor (see {@link MIN_JOB_REQUESTS}) collapses into that last
+     * one, because a job cannot use it.
+     *
+     * The refusal is a THROW, so it lands on `dispatch`'s existing coded-error
+     * path and reaches the model through the tool: the same treatment as
+     * `jobsDisabled` / `jobLimitExceeded` / an unknown root.
+     *
+     * Tier: a job routes on the `subagent` task class, exactly as a child does. An
+     * unresolved tier still draws on the pool, so it is weighed at the worst case
+     * rather than skipped; no router at all means a bring-your-own provider whose
+     * tokens never touch the weighted pool, and nothing here bounds them.
+     */
+    admit(spec) {
+        const { budget, config, logger } = this.deps;
+        const resolved = resolveBudget(config.subagent.defaultBudget, {
+            ...(spec.budget?.maxIterations !== undefined
+                ? { maxIterations: spec.budget.maxIterations }
+                : {}),
+            ...(spec.budget?.maxTokens !== undefined
+                ? { maxTokens: spec.budget.maxTokens }
+                : {}),
+        });
+        if (!budget)
+            return resolved;
+        const verdict = budget.admit({
+            count: 1,
+            perRunTokens: resolved.maxTokens,
+            tier: this.jobTier(),
+        });
+        if (verdict.kind === "refused")
+            throw sessionBudgetExhausted(verdict.reason);
+        if (verdict.kind === "allow" || verdict.maxTokens <= 0)
+            return resolved;
+        // A NARROWED CEILING BELOW THE FLOOR IS A REFUSAL (cli#245). `admit` narrows
+        // rather than refuses so that a user with real headroom is never left unable
+        // to ask anything at all, and for the turn that is exactly right: the user is
+        // present, sees the warning, and can shorten the question or raise
+        // `/budget`. A job has none of that. It runs after the turn returned, with
+        // nobody watching, on a task the model already wrote — so the same narrowing
+        // that keeps a turn useful hands a job a ceiling it cannot start under, and
+        // the honest answer is to say so at the seam where the model can still act
+        // on it rather than to dispatch a run that fails a second later.
+        //
+        // Refused HERE and not in the shared rule on purpose: `admit` is one object
+        // answering three callers, and only this one is unattended.
+        const floor = this.deps.config.context.reserveTokens * MIN_JOB_REQUESTS;
+        if (verdict.maxTokens < floor) {
+            throw sessionBudgetExhausted(`${verdict.reason}; a background job needs at least ` +
+                `${compactTokens(floor)} tokens to complete one act-and-report cycle, ` +
+                `so it was refused rather than dispatched to fail on its first turn`);
+        }
+        // Narrowed: the one run is admitted with a cut ceiling. `Math.min` because
+        // `admit` may only ever narrow — a granted figure above the resolved cap
+        // would raise a ceiling the config and the spec already set.
+        logger.warn(verdict.reason);
+        return {
+            ...resolved,
+            maxTokens: Math.min(resolved.maxTokens, verdict.maxTokens),
+        };
+    }
+    /** The tier a job would route to, or the unresolved/no-pool markers. */
+    jobTier() {
+        const router = this.deps.router;
+        if (!router)
+            return undefined; // not a cruxy request — no weighted pool
+        return resolveTaskModel(router, "subagent").tier ?? UNRESOLVED_TIER;
+    }
     /** Resolve a job's scope from an optional root name (fail-loud on unknown). */
     jobScope(rootName) {
         if (rootName === undefined) {
@@ -370,6 +608,20 @@ export class JobManager {
         };
     }
 }
+/**
+ * A job's `error` line for a pool denial, with every fact the 429 carried.
+ *
+ * `job.error` is a string and a `JobView` is what `/jobs` and the Tasks view
+ * read, so the typed error cannot be handed over whole here — but its next
+ * steps are exactly where `miraAvailable` and `resetAt` were rendered into
+ * words, and dropping them is what made a denial indistinguishable from a
+ * crash. The typed object itself still survives, on the latch the foreground
+ * drains (see {@link JobManager.takePoolDenial}).
+ */
+function denialLine(denial) {
+    const steps = denial.nextSteps.join("; ");
+    return `${denial.code}: ${denial.title}${steps ? ` — ${steps}` : ""}`;
+}
 /** One-line task excerpt for a job label. */
 function taskLabel(task) {
     const flat = task.replace(/\s+/g, " ").trim();

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/mcp/client.js

@@ -10,6 +10,22 @@ import { APP_NAME, APP_VERSION } from "../constants.js";
  */
 /** The MCP protocol revision cruxy advertises. */
 const PROTOCOL_VERSION = "2025-06-18";
+/**
+ * The three fields cruxy accepts from an advertised tool — and, by omission, the
+ * enforcement point for everything it refuses.
+ *
+ * `annotations` IS DELIBERATELY ABSENT. MCP lets a server describe its own tool
+ * with `readOnlyHint` / `destructiveHint` / `idempotentHint`, and zod strips
+ * unknown keys, so declaring only these three drops the block here at the wire
+ * boundary rather than carrying it inward for someone downstream to be tempted
+ * by. The spec's own rule is that clients "MUST consider tool annotations to be
+ * untrusted unless they come from trusted servers", and cruxy's MCP trust binds
+ * the INVOCATION rather than the code (`mcp/trust.ts`), so it cannot claim that
+ * exemption. Adding a field here would not merely widen a parse — it would put a
+ * server-controlled boolean within reach of the approval gate. The full argument
+ * is at `mcpRequest` in `approval/classify.ts`; `annotations-untrusted.test.ts`
+ * pins the property at both layers.
+ */
 const RawToolSchema = z.object({
     name: z.string().min(1),
     description: z.string().optional(),

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;