@cruxy/cli 1.4.0 → 1.5.0

package/dist/agent/status.js

@@ -1,5 +1,32 @@
 import { readContext } from "./context.js";
 import { modeDescription } from "./mode.js";
+import { globalDir } from "../config/paths.js";
+import { GLOBAL_DIR_NAME } from "../constants.js";
+/**
+ * Where the disk figures come from: every declared root, plus `~/.cruxy`.
+ *
+ * The home directory is in the list because it is the one that fills up
+ * invisibly. A root's usage is the user's own files, which they know about;
+ * `~/.cruxy` accumulates session transcripts, the usage store and — the big one
+ * — a checkpoint shadow copy per run. Reporting only the roots would leave the
+ * cruxy-specific half of "why is this disk full" out of cruxy's own status
+ * screen.
+ */
+function diskLocations(roots, disk) {
+    const locations = [];
+    for (const root of roots) {
+        const capacity = disk(root.absPath);
+        if (capacity)
+            locations.push({ label: root.name, capacity });
+    }
+    const home = disk(globalDir());
+    // Labelled `~/.cruxy` rather than the resolved path: the row is 40 columns of
+    // numbers already, and the literal home path adds width without adding a fact
+    // — `/status` prints every root's real path a few lines further down anyway.
+    if (home)
+        locations.push({ label: `~/${GLOBAL_DIR_NAME}`, capacity: home });
+    return locations;
+}
 /** Count real user turns: `role: "user"` with STRING content — tool results
  * are also role "user" but carry blocks, so this counts what the human said. */
 function userTurns(session) {
@@ -13,7 +40,14 @@ export function buildSessionStatus(session, git,
  * on the stream's routing frame — so `/status`, which has no renderer, omits
  * it and shows the configured value alone.
  */
-servedTier) {
+servedTier, 
+/**
+ * Free space where cruxy writes. Omitted rather than defaulted to a live
+ * probe: a caller that doesn't supply one gets no disk rows, which is the
+ * only safe default for a function whose whole contract is that it never
+ * touches the world itself.
+ */
+disk) {
     const toolCtx = session.toolContext;
     const config = toolCtx.config;
     const mode = session.getMode();
@@ -29,6 +63,9 @@ servedTier) {
         };
     });
     const jobs = session.jobs?.list();
+    const locations = disk
+        ? diskLocations(toolCtx.workspace.roots(), disk)
+        : undefined;
     return {
         sessionId: session.sessionId,
         turns: userTurns(session),
@@ -42,6 +79,9 @@ servedTier) {
         sandboxEnabled: Boolean(toolCtx.sandbox),
         ...(toolCtx.sandbox ? { sandboxRuntime: toolCtx.sandbox.runtimeName } : {}),
         checkpoints: Boolean(toolCtx.checkpointsActive),
+        // Absent when nothing could be read, not an empty array — same rule as the
+        // rest of this object: an omitted field is a fact we don't have.
+        ...(locations && locations.length > 0 ? { disk: locations } : {}),
         ...(jobs
             ? {
                 jobs: {

package/dist/cli/commands/run.js

@@ -1,10 +1,12 @@
 import { Command } from "commander";
 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";
 /** Sessions shown in the TUI sidebar — the same depth as the resume picker. */
 const SIDEBAR_SESSIONS = 10;
-import { loadConfig, resolveApiKey } from "../../config/index.js";
+import { globalDir, loadConfig, 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";
@@ -14,7 +16,7 @@ import { SandboxService } from "../../sandbox/index.js";
 import { buildHooksService, buildHooksRouter } from "../../hooks/index.js";
 import { DEFAULT_MODE, } from "../../agent/index.js";
 import { runInteractive } from "../repl.js";
-import { ContextGauge, createKeyLease, createGitView, createOverviewView, createSettingsView, createTasksView, runTui, TuiRenderer, WorkspaceGitCache, } from "../../tui/index.js";
+import { ContextGauge, createKeyLease, createGitView, createOverviewView, createSettingsView, createTasksView, runTui, TuiRenderer, WorkspaceDiskCache, WorkspaceGitCache, } from "../../tui/index.js";
 import { buildAgentSession } from "../session-factory.js";
 import { apiKeyEnvVar, maybeRunOnboarding } from "../onboard.js";
 import { resetLspServices } from "../../lsp/index.js";
@@ -340,6 +342,21 @@ export async function executeRun(promptParts, opts) {
     // provider, where the constructor's static value stands and `/model` declines.
     if (session.model)
         tui?.attachModel(session.model);
+    // The limits rail panel (P9) — the account's headroom, read from the gateway
+    // that enforces it.
+    //
+    // ONLY ON THE CRUXY PROVIDER, and only with a key. `/limits` is a cruxy
+    // gateway endpoint; a bring-your-own-provider session has no such notion, and
+    // pointing this at someone else's base URL would be a request to a stranger.
+    // 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;
+    tui?.attachLimits(new LimitsCache(limitsKey === undefined
+        ? undefined
+        : (signal) => new LimitsClient({
+            apiKey: limitsKey,
+            gatewayUrl: config.cruxy.gatewayUrl,
+        }).read(signal)));
     // The main-pane views (P7). Registered here — the one place that has both the
     // renderer and the session — and after the session exists, because a view
     // reads its live state. Each root gets its own cached git probe: writes fan
@@ -350,8 +367,15 @@ export async function executeRun(promptParts, opts) {
         // a second instance would double the subprocesses to hold two copies of an
         // answer that must agree anyway.
         const workspaceGit = new WorkspaceGitCache(session.toolContext.workspace.roots().map((r) => r.absPath));
+        // Every root, plus `~/.cruxy` — the two kinds of place a run fills up. The
+        // home directory is the one nobody watches: checkpoints shadow-copy the
+        // tree once per run, and they accumulate there rather than in the repo.
+        const workspaceDisk = new WorkspaceDiskCache([
+            ...session.toolContext.workspace.roots().map((r) => r.absPath),
+            globalDir(),
+        ]);
         tui.attachViews([
-            createOverviewView(session, workspaceGit, () => tui.servedTier()),
+            createOverviewView(session, workspaceGit, () => tui.servedTier(), workspaceDisk),
             createGitView(() => session.toolContext.workspace.roots(), workspaceGit),
             // Registered even when background jobs are disabled — the view says so,
             // and a nav whose rows appear and vanish with config is worse than one

package/dist/cli/session-commands.js

@@ -9,6 +9,7 @@ import { contextReportLines } from "../render/context-view.js";
 import { renderUnifiedDiff } from "../render/index.js";
 import { sessionStatusLines } from "../render/status-view.js";
 import { defaultExportName, exportMarkdown } from "../session/index.js";
+import { readDiskCapacitySync } from "../utils/disk.js";
 import { getGitInfo } from "../utils/git.js";
 import { currentBranch, diffAgainst, hasChanges } from "../vcs/git.js";
 import { MODEL_CHOICES, describeModelChoice, parseModelChoice, } from "../routing/index.js";
@@ -373,7 +374,11 @@ function handleStatus(ctx) {
     //
     // Everything else comes from the shared builder, so this and the Overview
     // view cannot drift: they differ in exactly this argument and nowhere else.
-    const status = buildSessionStatus(session, (absPath) => getGitInfo(absPath));
+    const status = buildSessionStatus(session, (absPath) => getGitInfo(absPath), undefined, 
+    // Synchronous here for the same reason git is: the user asked. This one is
+    // a single syscall rather than two subprocesses, so it costs microseconds
+    // on any disk that is answering at all.
+    (path) => readDiskCapacitySync(path));
     for (const line of sessionStatusLines(status, out.theme)) {
         out.print(out.fit(line));
     }

package/dist/errors/constructors.js

@@ -1,4 +1,4 @@
-import { ApiError, AuthError, NetworkError, OverloadedError, RateLimitError, } from "@cruxy/sdk";
+import { ApiError, AuthError, BudgetExhaustedError, NetworkError, OverloadedError, RateLimitError, } from "@cruxy/sdk";
 import { scrubModelNames } from "../brand/index.js";
 import { CruxyError, ErrorCode } from "./types.js";
 /**
@@ -223,14 +223,92 @@ export function apiOverloaded(underlying) {
         underlying,
     });
 }
+/**
+ * A wait, in the largest unit that stays honest: "4h", "12m", "18d".
+ *
+ * `apiRateLimit` renders seconds because a rate-limit wait IS seconds. A budget
+ * window is hours or days, and "~14400s" is a number a human has to do
+ * arithmetic on at the moment they are least inclined to.
+ */
+function humanWait(ms) {
+    const minutes = Math.round(ms / 60_000);
+    if (minutes < 60)
+        return `${Math.max(1, minutes)}m`;
+    const hours = Math.round(minutes / 60);
+    return hours < 48 ? `${hours}h` : `${Math.round(hours / 24)}d`;
+}
+/**
+ * The weighted-pool gate refused the request (429 `budget_exhausted`).
+ *
+ * THIS IS THE POOL, AND ONLY THE POOL. The gateway spends separate codes on the
+ * things a user actually can pay their way out of — `credits_exhausted`,
+ * `key_spend_cap_exceeded`, `workspace_spend_cap_exceeded` — and none of them
+ * arrive here. So the advice this used to give ("top up or raise your budget,
+ * then retry") was wrong in both halves: there is nothing to top up on a
+ * subscription pool, and "retry" against a window that refills on a clock is an
+ * instruction to hammer a gate that will refuse again.
+ *
+ * That wording was harmless while it was unreachable from this CLI. cruxy-ai/api#174
+ * makes a CLI login mint a subscription credential, so it is now the message a
+ * blocked user actually reads — see cruxy-ai/cli#212.
+ *
+ * The error already carries everything needed to say something true, and all of
+ * it used to be discarded:
+ *
+ *  - `miraAvailable` — mira is exempt from the pool kill, so on most denials
+ *    there IS a way to keep working. It goes first: it is the only step that
+ *    unblocks someone now rather than telling them when to come back.
+ *  - `window` — "monthly" and "burst" are different waits (a calendar rollover
+ *    versus a trailing sum sliding back under its cap), so the wait is named.
+ *  - `resetAt` / `retryAfterMs` — WHEN, so the wait is a time rather than a
+ *    vague "later". The window length is deliberately not asserted here; the
+ *    server sends the recovery instant and this reports that.
+ */
 export function budgetExhausted(underlying) {
+    const err = underlying instanceof BudgetExhaustedError ? underlying : undefined;
+    const waitMs = err?.retryAfterMs ??
+        (err?.resetAt !== undefined ? msUntil(err.resetAt) : undefined);
+    const nextSteps = [];
+    // Mira stays available on an exhausted pool (it is the always-available
+    // floor), so when the gateway says so, the first step is the one that gets
+    // the user working again instead of waiting.
+    if (err?.miraAvailable) {
+        nextSteps.push("switch to the mira tier, which stays available: `/model mira`");
+    }
+    const window = err?.window === "burst" ? "burst" : err?.window;
+    const windowPhrase = window ? `your ${window} budget window` : "your budget";
+    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");
     return new CruxyError({
         code: ErrorCode.BudgetExhausted,
-        title: "your Cruxy budget is exhausted",
+        title: window
+            ? `your ${window} Cruxy budget is exhausted`
+            : "your Cruxy budget is exhausted",
         cause: scrubbedMessageOf(underlying),
-        nextSteps: ["top up or raise your budget, then retry"],
+        nextSteps,
         underlying,
-    });
+        meta: err
+            ? {
+                ...(err.window !== undefined ? { window: err.window } : {}),
+                ...(err.resetAt !== undefined ? { resetAt: err.resetAt } : {}),
+                ...(err.miraAvailable !== undefined
+                    ? { miraAvailable: err.miraAvailable }
+                    : {}),
+            }
+            : undefined,
+    });
+}
+/** Milliseconds until an ISO instant, or `undefined` if it is absent/unparseable. */
+function msUntil(iso) {
+    const at = Date.parse(iso);
+    if (Number.isNaN(at))
+        return undefined;
+    return Math.max(0, at - Date.now());
 }
 // ── filesystem (exit 7) ───────────────────────────────────────────────────────
 export function fileNotFound(path, underlying) {
@@ -1309,12 +1387,14 @@ export function classifyProviderError(underlying) {
         return apiOverloaded(underlying);
     if (underlying instanceof NetworkError)
         return gatewayUnreachable(underlying);
-    if (underlying instanceof ApiError) {
-        // BudgetExhaustedError isn't exported by the SDK; match by name.
-        if (underlying.name === "BudgetExhaustedError") {
-            return budgetExhausted(underlying);
-        }
-        return apiError(underlying);
+    // Before the `ApiError` base it extends, like every other subclass here. The
+    // name check this replaces was a workaround for an export that exists — the
+    // SDK's barrel has always re-exported the class — and it silently stopped
+    // matching anything the moment a bundler minified the constructor name.
+    if (underlying instanceof BudgetExhaustedError) {
+        return budgetExhausted(underlying);
     }
+    if (underlying instanceof ApiError)
+        return apiError(underlying);
     return null;
 }

package/dist/limits/cache.js

@@ -0,0 +1,100 @@
+import { reduceLimits } from "./reduce.js";
+/**
+ * How long a probe's answer is treated as current. The pool moves when the user
+ * spends, and the surfaces that spend it (this CLI, web chat, desktop) do so in
+ * turns — so a per-turn refresh is the natural cadence and this floor exists
+ * only to coalesce the several triggers a single turn can produce.
+ */
+const MIN_INTERVAL_MS = 15_000;
+export class LimitsCache {
+    probe;
+    now;
+    minIntervalMs;
+    state;
+    /** The refresh in flight, so concurrent triggers share one request. */
+    inFlight = null;
+    lastAttemptAt = 0;
+    constructor(
+    /**
+     * Absent when there is no credential to ask with. That is not a failure to
+     * report later — it is knowable now, costs no request to determine, and the
+     * panel's answer ("sign in") is the same either way.
+     */
+    probe, opts = {}) {
+        this.probe = probe;
+        this.now = opts.now ?? Date.now;
+        this.minIntervalMs = opts.minIntervalMs ?? MIN_INTERVAL_MS;
+        this.state = probe
+            ? { status: "pending" }
+            : { status: "error", reason: "unauthenticated" };
+    }
+    /** The last settled state — a field read, safe from the paint path. */
+    current() {
+        return this.state;
+    }
+    /** True once a reading has been obtained, whatever has happened since. */
+    hasReading() {
+        return this.state.status === "ready";
+    }
+    /**
+     * Re-read the limits, off the paint path. Coalesces concurrent callers onto
+     * one request and declines to re-probe within {@link minIntervalMs} of the
+     * last attempt.
+     *
+     * Never rejects: a refresh is a background probe for a status panel, and a
+     * caller that has to `.catch` a status update will eventually forget to.
+     */
+    async refresh() {
+        if (!this.probe)
+            return;
+        if (this.inFlight)
+            return this.inFlight;
+        const at = this.now();
+        // The floor applies only once something is on screen. Before the first
+        // answer there is nothing to protect, and rate-limiting our way to a blank
+        // panel would be the floor working against its own purpose.
+        if (this.state.status === "ready" &&
+            at - this.lastAttemptAt < this.minIntervalMs) {
+            return;
+        }
+        this.lastAttemptAt = at;
+        this.inFlight = this.run(this.probe);
+        try {
+            await this.inFlight;
+        }
+        finally {
+            this.inFlight = null;
+        }
+    }
+    async run(probe) {
+        try {
+            const res = await probe();
+            this.state = { status: "ready", reading: reduceLimits(res, this.now()) };
+        }
+        catch (err) {
+            // Keep a good reading rather than blanking a panel that was correct a
+            // 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) };
+        }
+    }
+}
+/**
+ * Why the probe failed, in the three 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
+ * loads. A 404/501 is the interesting case: it means a gateway that does not
+ * 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.
+ */
+function classify(err) {
+    const e = err;
+    if (e?.name === "AuthError")
+        return "unauthenticated";
+    if (e?.status === 404 || e?.status === 501)
+        return "unsupported";
+    return "unreachable";
+}

package/dist/limits/index.js

@@ -0,0 +1,11 @@
+/**
+ * Limits (P9): the gateway's own account of what this credential may spend, and
+ * how much of it is left.
+ *
+ * Three files, one direction: `reduce.ts` turns the wire response into the
+ * closed {@link LimitsReading} union, `cache.ts` owns the network read and the
+ * staleness rules, and `types.ts` holds the union both sides agree on. The
+ * rendering lives in `tui/limits-panel.ts` — nothing here formats anything.
+ */
+export { LimitsCache } from "./cache.js";
+export { reduceLimits, bindingWindow, usedFraction } from "./reduce.js";

package/dist/limits/reduce.js

@@ -0,0 +1,172 @@
+/**
+ * Wire response → {@link LimitsReading}: one place where "which absence means
+ * what" is decided (P9).
+ *
+ * The reduction is driven by `bucket` and NOTHING else. Not by how the user
+ * logged in, not by whether a key looks like `cxy_live_`, not by which config
+ * fields are set — every one of those was a plausible inference and every one of
+ * them is now wrong, because the gateway changed which bucket a CLI login mints
+ * into (cruxy-ai/api#174) without changing anything a client could see locally.
+ * The endpoint is the answer to that question; asking anything else is guessing.
+ */
+/** A cap is only a denominator when it is a positive, finite number. */
+function usableCap(cap) {
+    return Number.isFinite(cap) && cap > 0;
+}
+/**
+ * A weighted-token window, or `undefined` when it cannot serve as a fraction.
+ *
+ * A cap of 0 is dropped rather than rendered as "100% used": zero is what an
+ * unprovisioned or misconfigured plan reports, and dividing by it produces
+ * either a crash or a full red bar, neither of which is a true statement about
+ * what the user may spend.
+ */
+function toWindow(w) {
+    if (!w || !usableCap(w.cap))
+        return undefined;
+    return {
+        cap: w.cap,
+        used: w.used,
+        remaining: w.remaining,
+        ...(w.state !== undefined ? { state: w.state } : {}),
+        ...(w.resets_at !== undefined ? { resetsAt: w.resets_at } : {}),
+    };
+}
+function toSpendCap(c) {
+    if (!c || !usableCap(c.cap))
+        return undefined;
+    return {
+        cap: c.cap,
+        spent: c.spent,
+        remaining: c.remaining,
+        ...(c.resets_at !== undefined ? { resetsAt: c.resets_at } : {}),
+    };
+}
+function toRateWindow(w) {
+    return {
+        limit: w.limit,
+        remaining: w.remaining,
+        windowSeconds: w.window_seconds,
+        ...(w.resets_at !== undefined ? { resetsAt: w.resets_at } : {}),
+    };
+}
+/**
+ * The budget shape for this credential.
+ *
+ * Ordered by bucket, and each branch answers only for its own bucket — a
+ * `subscription` response that somehow also carried `credits` does not get to
+ * fall through into the headless branch. The server decides which section is
+ * authoritative by telling us the bucket; honouring that literally is what keeps
+ * this reduction and the gate in agreement.
+ */
+function reduceBudget(res) {
+    switch (res.bucket) {
+        case "subscription": {
+            const pool = res.token_pool;
+            // No section at all: gated by something we were not told about.
+            if (!pool)
+                return { kind: "unknown" };
+            // Enterprise. The one place "no numbers" is a complete answer.
+            if (!pool.enforced)
+                return { kind: "unenforced" };
+            const monthly = toWindow(pool.monthly);
+            const burst = toWindow(pool.burst);
+            // Enforced, but nothing readable to enforce against. NOT "unenforced":
+            // the pool exists and will stop this user, we just cannot say when.
+            if (!monthly && !burst)
+                return { kind: "unknown" };
+            return {
+                kind: "pool",
+                unit: pool.unit ?? "weighted_tokens",
+                ...(pool.state !== undefined ? { state: pool.state } : {}),
+                ...(monthly ? { monthly } : {}),
+                ...(burst ? { burst } : {}),
+                ...(pool.mira && usableCap(pool.mira.cap)
+                    ? {
+                        mira: {
+                            cap: pool.mira.cap,
+                            used: pool.mira.used,
+                            remaining: pool.mira.remaining,
+                            state: pool.mira.state,
+                            window: pool.mira.window,
+                            ...(pool.mira.resets_at !== undefined
+                                ? { resetsAt: pool.mira.resets_at }
+                                : {}),
+                        },
+                    }
+                    : {}),
+                blockedModels: pool.blocked_models ?? [],
+            };
+        }
+        case "apikey":
+            // `metered: true` is the server's positive statement that there is no pool
+            // to report. Its absence on an apikey bucket means this build is reading a
+            // response it does not fully understand, so it says so.
+            return res.metered === true ? { kind: "metered" } : { kind: "unknown" };
+        case "headless": {
+            const c = res.credits;
+            if (!c)
+                return { kind: "unknown" };
+            return {
+                kind: "credits",
+                plan: c.plan,
+                granted: c.granted,
+                used: c.used,
+                remaining: c.remaining,
+                ...(c.resets_at !== undefined ? { resetsAt: c.resets_at } : {}),
+            };
+        }
+        default:
+            // A bucket added after this build. The tier and the rate limits below are
+            // still real and still reported; only the budget shape is unreadable.
+            return { kind: "unknown" };
+    }
+}
+/** Reduce a wire response to the reading the panel consumes. */
+export function reduceLimits(res, readAt = Date.now()) {
+    const chat = res.rate_limits?.chat;
+    const keySpendCap = toSpendCap(res.key_spend_cap);
+    const workspaceSpendCap = toSpendCap(res.workspace_spend_cap);
+    const rate = chat
+        ? {
+            perKey: toRateWindow(chat.per_key),
+            perOrg: toRateWindow(chat.per_org),
+            maxConcurrentRequests: chat.max_concurrent_requests,
+        }
+        : undefined;
+    return {
+        tier: res.tier,
+        bucket: res.bucket,
+        budget: reduceBudget(res),
+        ...(rate ? { chat: rate } : {}),
+        ...(keySpendCap ? { keySpendCap } : {}),
+        ...(workspaceSpendCap ? { workspaceSpendCap } : {}),
+        readAt,
+    };
+}
+/**
+ * The window that will stop this user FIRST — the one the gate itself calls
+ * binding: whichever of monthly/burst has the smaller REMAINING fraction
+ * (`internal/budget/decide.go`).
+ *
+ * This is what earns the single bar the rail has room for. Drawing the month
+ * because it is the bigger number would routinely show a comfortable 6% while
+ * the trailing-12h window — a quarter of the month's cap on every self-serve
+ * tier — is the one about to refuse the next request.
+ */
+export function bindingWindow(monthly, burst) {
+    if (!monthly)
+        return burst ? { window: burst, name: "burst" } : undefined;
+    if (!burst)
+        return { window: monthly, name: "month" };
+    const frac = (w) => w.remaining / w.cap;
+    return frac(burst) < frac(monthly)
+        ? { window: burst, name: "burst" }
+        : { window: monthly, name: "month" };
+}
+/** The fraction of a cap consumed, clamped to [0,1] for display. */
+export function usedFraction(w) {
+    if (!usableCap(w.cap))
+        return undefined;
+    return Math.min(1, Math.max(0, w.used / w.cap));
+}

package/dist/limits/types.js

@@ -0,0 +1,25 @@
+/**
+ * The CLI's reading of `GET /api/v1/limits` (P9).
+ *
+ * THE WIRE SHAPE IS NOT THE RENDER SHAPE, and the gap between them is the whole
+ * reason this module exists. On the wire a section is present or absent and a
+ * reader must know which absence means what: no `token_pool` on an `apikey` is
+ * normal, no `monthly` inside an enforced pool is a gateway this build cannot
+ * read, and `{enforced: false}` is a definite statement that there is no cap —
+ * three absences with three different meanings, one of which must never be shown
+ * as another.
+ *
+ * So the reduction resolves them ONCE, into a closed union where each variant
+ * carries exactly the numbers that variant may legitimately state. A renderer
+ * handed a {@link Unenforced} has no cap to divide by because the type has no
+ * cap in it — the honesty is structural, not a rule someone has to remember at
+ * the call site.
+ *
+ * WHAT THIS ADDS TO `usage/weighted.ts`, which computes the same unit locally:
+ * that module is explicit that it can state consumption and never headroom,
+ * because a cap needs the user's plan and what every OTHER surface (web chat,
+ * desktop, phone) has already spent — "neither of which is on this machine".
+ * This is the other half arriving over the wire: the denominator, already
+ * inclusive of every surface, from the meter itself.
+ */
+export {};