@cruxy/cli 1.9.0 → 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/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/render/limits-report.js

@@ -0,0 +1,213 @@
+import { compactTokens } from "./units.js";
+import { buildLimitsSummary } from "./limits-view.js";
+/**
+ * Rendering `cruxy limits` (cli#138) — the session-less half of the P9 reading.
+ *
+ * WHY A COMMAND AND NOT A COLUMN IN `cruxy usage`. The two answer questions with
+ * no common denominator, and joining them produces a number that reads as
+ * authoritative while being about two different things: `usage/store.ts` counts
+ * this machine's last FIFTY RUNS — a count, not a duration — while the pool is a
+ * calendar month and a trailing 12h window, already inclusive of every other
+ * surface on the account. The gap is not a rounding error. A credential minted
+ * seconds earlier, with zero local runs behind it, reported 63% of its month
+ * already drawn from web chat and desktop; any ratio over those two numerators
+ * would have been wrong by nearly its whole value on day one.
+ *
+ * So `cruxy usage` keeps its local-only guarantee and this command makes the
+ * call. THE COMMAND SPLIT IS THE BOUNDARY, and it is worth saying plainly that
+ * the no-phone-home guard is not: that guard scans a named list of files, this
+ * file is deliberately not on it, and a green run of it proves nothing whatever
+ * about a file it was never pointed at. What keeps `cruxy usage` local is that
+ * the network lives in a different command, not that a test noticed.
+ *
+ * IT NAMES THE WINDOW RATHER THAN THE ABSTRACTION. The rail picks one window
+ * because it has room for one bar, and `session-budget.ts` picks one because
+ * admission has to spend against one — both are right, and both are choices a
+ * SURFACE has to make. A command has room for neither excuse: it prints
+ * `monthly` and `12h burst` by name, in the vocabulary `/budget` already uses,
+ * because "the binding window" is a phrase that at Free tier (where
+ * `burst.cap === monthly.cap`) resolves to the same window essentially always —
+ * an abstraction that never varies, costing the reader the one fact they came
+ * for.
+ */
+/** Bar width. Wider than the rail's twelve cells; a command has the columns. */
+const BAR_CELLS = 24;
+/** The label each window goes by here — see the module comment on naming. */
+const WINDOW_LABEL = {
+    month: "monthly",
+    burst: "12h burst",
+};
+/** Widest label, so every row's bar starts in the same column. */
+const LABEL_COLS = Math.max(...Object.values(WINDOW_LABEL).map((l) => l.length));
+function bar(theme, fraction) {
+    const filled = Math.round(Math.min(1, Math.max(0, fraction)) * BAR_CELLS);
+    return (theme.glyph.barFilled.repeat(filled) +
+        theme.glyph.barEmpty.repeat(BAR_CELLS - filled));
+}
+/**
+ * A percentage, right-aligned to the width of "100%", so the figures beside it
+ * start in the same column on every row. A ragged column reads as two unrelated
+ * numbers rather than one comparison, which is the whole point of stacking the
+ * windows.
+ */
+function pct(fraction) {
+    return `${Math.round(fraction * 100)}%`.padStart(4);
+}
+/** 27.77 → "$27.77", 29 → "$29". Same rule the panel uses. */
+function usd(n) {
+    return Number.isInteger(n) ? `$${n}` : `$${n.toFixed(2)}`;
+}
+/** "in 18d" / "in 4h", or nothing at all when there is no reset to state. */
+function resetLabel(iso, now) {
+    if (!iso)
+        return undefined;
+    const at = Date.parse(iso);
+    if (Number.isNaN(at))
+        return undefined;
+    const ms = at - now;
+    if (ms <= 0)
+        return "resets now";
+    const minutes = Math.floor(ms / 60_000);
+    if (minutes < 60)
+        return `resets in ${Math.max(1, minutes)}m`;
+    const hours = Math.floor(minutes / 60);
+    if (hours < 24)
+        return `resets in ${hours}h`;
+    return `resets in ${Math.floor(hours / 24)}d`;
+}
+/**
+ * How long ago a reading was taken, as a whole sentence.
+ *
+ * "just now" is a real case here and is not one for the rail: the panel only
+ * ever says this past a five-minute staleness threshold, while a command probes
+ * and prints in the same breath. Rounding that up to "1m ago" would age a
+ * reading by a minute it did not have.
+ */
+function readAgeLine(ms) {
+    const minutes = Math.floor(ms / 60_000);
+    if (minutes < 1)
+        return "read just now";
+    if (minutes < 60)
+        return `read ${minutes}m ago`;
+    const hours = Math.floor(minutes / 60);
+    return hours < 24
+        ? `read ${hours}h ago`
+        : `read ${Math.floor(hours / 24)}d ago`;
+}
+/** One window: name, bar, percentage, the figures, and its reset if it has one. */
+function windowLine(theme, w, now) {
+    const style = w.tone === "danger"
+        ? theme.danger
+        : w.tone === "warn"
+            ? theme.warning
+            : theme.strong;
+    const label = WINDOW_LABEL[w.key].padEnd(LABEL_COLS);
+    const figures = `${compactTokens(w.window.used)} / ${compactTokens(w.window.cap)}`;
+    const reset = resetLabel(w.window.resetsAt, now);
+    return (`  ${theme.strong(label)} ${style(bar(theme, w.fraction))} ` +
+        `${style(pct(w.fraction))}  ${theme.muted(figures)}` +
+        (reset ? theme.muted(`${theme.sep}${reset}`) : ""));
+}
+function spendCapLine(theme, label, cap) {
+    const name = label === "ws" ? "workspace spend cap" : "key spend cap";
+    return theme.muted(`  ${name}  ${usd(cap.remaining)} of ${usd(cap.cap)} left`);
+}
+/**
+ * The whole report, or the one honest sentence when there is no reading.
+ *
+ * The three not-a-reading states are said three ways, on the same discipline the
+ * panel keeps: "still asking" must not read as "no limits", and neither may read
+ * as "your key is bad". A command exits after saying it, so each one also gets
+ * the next step rather than leaving the user to infer it from four words.
+ */
+export function limitsReportLines(theme, state, now = Date.now()) {
+    if (state.status === "pending") {
+        return [theme.muted("the limits reading has not arrived yet")];
+    }
+    if (state.status === "error") {
+        switch (state.reason) {
+            case "unauthenticated":
+                return [
+                    theme.warning("not signed in"),
+                    theme.muted("run `cruxy login` to sign in"),
+                ];
+            // A different FACT from "not signed in", and the fact is the point: this
+            // user's setup was right and simply aged out. Sending them to look for
+            // what they configured wrong would be sending them after nothing.
+            case "expired":
+                return [
+                    theme.warning("your sign-in has expired"),
+                    theme.muted("run `cruxy login` to sign in again"),
+                ];
+            // The gateway ANSWERED — it has no limits to report. Telling this user to
+            // check their network would be the wrong errand entirely.
+            case "unsupported":
+                return [
+                    theme.muted("this gateway does not report limits"),
+                    theme.muted("nothing here is wrong with your setup or your network"),
+                ];
+            case "unreachable":
+                return [
+                    theme.warning("could not reach the gateway"),
+                    theme.muted("check your connection and try again"),
+                ];
+        }
+    }
+    const s = buildLimitsSummary(state.reading, now);
+    const lines = [
+        `${theme.heading(s.tier)} ${theme.muted(`${theme.glyph.sep} ${s.bucket}`)}`,
+    ];
+    if (s.windows.length > 0) {
+        lines.push("");
+        for (const w of s.windows)
+            lines.push(windowLine(theme, w, now));
+        // The unit, once, under the windows it applies to. Named because a bare
+        // "942.8k" invites being read as requests or as raw tokens, and it is
+        // neither: it is `(billable_input + output) × tier multiplier`, the unit the
+        // meter counts in and the only one anything enforces.
+        lines.push(theme.muted(`  ${" ".repeat(LABEL_COLS)} weighted tokens`));
+    }
+    // Why there is nothing to draw, for the shapes that have nothing. Stated, not
+    // omitted: an empty section reads as a figure that failed to load.
+    if (s.noAllowance) {
+        lines.push("");
+        lines.push(`  ${theme.muted(s.noAllowance)}`);
+    }
+    // What this credential could have and does not (cli#263). An offer, not a
+    // correction — a deliberate `--paste` user is on an apikey on purpose and
+    // should be able to read this line and correctly ignore it.
+    for (const note of s.notes) {
+        lines.push(`  ${theme.muted(note)}`);
+    }
+    const pool = s.budget;
+    if (pool.kind === "pool") {
+        // Both stated whenever they exist. The rail shows them only when the pool is
+        // already low, because it has five lines; this has a terminal, and "what can
+        // I still run" is a fair question before the answer becomes urgent.
+        if (pool.mira) {
+            lines.push(theme.muted(`  mira  ${compactTokens(pool.mira.remaining)} of ${compactTokens(pool.mira.cap)} requests left${theme.sep}${pool.mira.window}`));
+        }
+        if (pool.blockedModels.length > 0) {
+            lines.push(theme.danger(`  refusing: ${pool.blockedModels.join(", ")}`));
+        }
+    }
+    if (pool.kind === "credits") {
+        lines.push("");
+        lines.push(`  ${theme.strong(usd(pool.remaining))} ${theme.muted(`of ${usd(pool.granted)} left`)}`);
+        const reset = resetLabel(pool.resetsAt, now);
+        if (reset)
+            lines.push(theme.muted(`  ${reset}`));
+    }
+    if (s.rpm) {
+        lines.push(theme.muted(`  rate  ${s.rpm.remaining} of ${s.rpm.limit} requests/min`));
+    }
+    for (const { label, cap } of s.spendCaps) {
+        lines.push(spendCapLine(theme, label, cap));
+    }
+    // Always, not only past a staleness threshold. The rail is repainting and can
+    // afford to stay quiet while a figure is fresh; a command prints once and is
+    // read later, so the reading's age is part of what it said.
+    lines.push("");
+    lines.push(theme.muted(readAgeLine(s.ageMs)));
+    return lines;
+}