@cruxy/cli 1.2.0 → 1.3.0

package/dist/tui/supports.js

@@ -0,0 +1,20 @@
+/**
+ * Whether the environment can host the full-viewport TUI.
+ *
+ * Three requirements, and they are exactly the axes capability detection now
+ * resolves — no re-probing of `process.stdin` or `TERM` here:
+ *
+ * - `interactive` (stdin is a terminal AND the output takes cursor control):
+ *   the TUI both reads keys and repaints, so it needs both halves. This is the
+ *   flag that makes `echo hi | cruxy` fall through to the plain path.
+ * - not `screenReader`: a live full-screen region is precisely what
+ *   screen-reader mode exists to avoid (U.11). Announce-friendly linear output
+ *   wins over the shell, always.
+ *
+ * Capability only. WHETHER a given invocation wants a TUI is an entry-mode
+ * decision (bare `cruxy` does; `cruxy run "task"` does not) and lives with the
+ * caller — see `createRenderer`'s `tui` option.
+ */
+export function supportsTui(caps) {
+    return caps.interactive && !caps.screenReader;
+}

package/dist/tui/tool-versions.js

@@ -0,0 +1,129 @@
+import { execFile } from "node:child_process";
+/**
+ * Host tool versions for the rail (P4 track 5).
+ *
+ * THE COST IS THE DESIGN. Measured warm on a fast Mac: pnpm 584ms, docker
+ * 130ms, tsc 108ms, git 34ms — ~911ms serially, and still ~584ms in parallel
+ * because pnpm alone dominates. That is half a second of dead terminal to
+ * populate a decorative panel, and it is the optimistic case: Windows process
+ * creation is far slower, which this repo has already paid for in CI.
+ *
+ * So nothing here runs at startup, nothing is awaited, and nothing blocks a
+ * paint. {@link ToolVersions.start} fires the probes and returns immediately;
+ * every row renders "…" until its OWN probe lands, independently of the others.
+ * A slow pnpm cannot delay a fast git.
+ *
+ * The shape is `sandbox/detect.ts`'s, which already solved this correctly:
+ * memoized for the process, a hard timeout, ENOENT treated as an answer rather
+ * than a throw, and never rejecting. One deliberate difference — that module
+ * probes `docker version --format {{.Server.Version}}`, which requires a LIVE
+ * DAEMON and reports a stopped Docker as absent. This panel is reporting what
+ * is INSTALLED, so it asks the client (`docker --version`), which answers with
+ * the daemon down.
+ */
+/** Hard ceiling on one probe; a hung binary must never wedge the panel. */
+const PROBE_TIMEOUT_MS = 5000;
+/**
+ * Pull a semantic version out of a tool's `--version` line.
+ *
+ * Every one of these prints something different — "git version 2.50.1 (Apple
+ * Git-155)", "Docker version 29.6.2, build dfc4efb", "Version 5.9.3", a bare
+ * "10.33.2" — so the first `x.y.z` in the output is both the simplest rule and
+ * the most robust one. `null` when there is no version-shaped thing at all,
+ * which is honest: something answered, but not with a version.
+ */
+export function parseVersion(output) {
+    return /\d+\.\d+\.\d+(?:[-+][\w.]+)?/.exec(output)?.[0] ?? null;
+}
+/** Default probe: spawn, capture, and treat any failure as "not installed". */
+const spawnProbe = (bin, args) => new Promise((resolve) => {
+    try {
+        execFile(bin, [...args], { encoding: "utf8", timeout: PROBE_TIMEOUT_MS, windowsHide: true }, (err, stdout, stderr) => {
+            // Some tools print their version to stderr; a non-zero exit with a
+            // parseable version still tells us the tool is there.
+            const text = `${stdout ?? ""}${stderr ?? ""}`;
+            if (err && text.trim() === "")
+                resolve(null);
+            else
+                resolve(text);
+        });
+    }
+    catch {
+        // execFile can throw synchronously on a malformed binary path.
+        resolve(null);
+    }
+});
+/**
+ * The tools reported, in display order.
+ *
+ * Node is NOT here: `process.versions.node` is the running interpreter's own
+ * version, already in memory. Spawning `node --version` to learn something the
+ * process knows about itself would be the most obviously wasteful 55ms in the
+ * list — and it would answer for whichever node is on PATH, which need not be
+ * the one executing this code.
+ */
+const TOOLS = [
+    { name: "tsc", bin: "tsc", args: ["--version"] },
+    { name: "pnpm", bin: "pnpm", args: ["--version"] },
+    { name: "git", bin: "git", args: ["--version"] },
+    // The CLIENT, not `docker version --format {{.Server.Version}}`: this panel
+    // reports what is installed, and a stopped daemon does not uninstall Docker.
+    { name: "docker", bin: "docker", args: ["--version"] },
+];
+export class ToolVersions {
+    probe;
+    versions = new Map();
+    started = false;
+    onSettled;
+    constructor(probe = spawnProbe) {
+        this.probe = probe;
+    }
+    /**
+     * Every row in display order — a pure map read, safe on the paint path.
+     *
+     * Node is resolved here rather than probed: free, exact, and it means the
+     * panel is never completely empty even on the very first frame.
+     */
+    current() {
+        return [
+            { name: "node", version: process.versions.node },
+            ...TOOLS.map((t) => ({
+                name: t.name,
+                version: this.versions.get(t.name),
+            })),
+        ];
+    }
+    /**
+     * Begin probing. Idempotent and memoized: the first call starts every probe,
+     * later calls do nothing, so a panel that repaints 30 times a second cannot
+     * re-spawn anything.
+     *
+     * Returns immediately. Each probe settles on its own and calls `onSettled`,
+     * so a fast git appears while a slow pnpm is still running — the rows are
+     * independent, and the panel fills in rather than arriving all at once.
+     */
+    start(onSettled) {
+        if (onSettled)
+            this.onSettled = onSettled;
+        if (this.started)
+            return;
+        this.started = true;
+        for (const tool of TOOLS) {
+            void this.run(tool);
+        }
+    }
+    async run(tool) {
+        let version = null;
+        try {
+            const output = await this.probe(tool.bin, tool.args);
+            version = output === null ? null : parseVersion(output);
+        }
+        catch {
+            // A probe that rejects is "not installed" for display purposes; it must
+            // never surface as an unhandled rejection from a decorative panel.
+            version = null;
+        }
+        this.versions.set(tool.name, version);
+        this.onSettled?.();
+    }
+}

package/dist/usage/collect.js

@@ -45,15 +45,33 @@ export class UsageCollector {
             tier: req.tier,
             inputTokens: u?.input_tokens,
             outputTokens: u?.output_tokens,
-            // Cache counters are conditionally spread so an unreported field stays
-            // absent from the persisted entry (undefined ≠ 0) — only the Anthropic
-            // dev path ever populates them.
+            // Every additive field below is conditionally spread so an unreported one
+            // stays ABSENT from the persisted entry rather than landing as a 0 that
+            // reads like a measurement (undefined ≠ 0). The reasons absence happens
+            // differ per field — a non-caching provider, a gateway too old to send
+            // billable input, a request the server quoted no cost for — but the entry
+            // records the same thing for all of them: nothing.
             ...(u?.cache_read_input_tokens !== undefined
                 ? { cacheReadTokens: u.cache_read_input_tokens }
                 : {}),
             ...(u?.cache_creation_input_tokens !== undefined
                 ? { cacheCreationTokens: u.cache_creation_input_tokens }
                 : {}),
+            ...(u?.billable_input_tokens !== undefined
+                ? { billableInputTokens: u.billable_input_tokens }
+                : {}),
+            // The server's own cost, persisted verbatim — and now the ONLY source of
+            // the cost `cruxy usage` shows; the user-configured price table it used to
+            // compete with is retired. Amount and currency travel together: a figure
+            // without its unit is not a cost, and the summary refuses to add two
+            // currencies rather than invent a rate. A recorded 0 is a real 0; see
+            // UsageEntry.costAmount for why that must never be read as "unpriced".
+            ...(u?.cost !== undefined
+                ? { costAmount: u.cost.amount, costCurrency: u.cost.currency }
+                : {}),
+            ...(req.routingMode !== undefined
+                ? { routingMode: req.routingMode }
+                : {}),
             at: this.now(),
         });
     }

package/dist/usage/index.js

@@ -7,9 +7,17 @@
  * `@cruxy/sdk` import below is a TYPE-only import (`Usage`), erased at build. A
  * future opt-in remote report would be a new, clearly-named seam — this build
  * ships nothing that sends. Asserted by the runtime + static no-phone-home tests.
+ *
+ * The guarantee survived this module gaining SERVER-SOURCED figures (the
+ * gateway's cost, and weighted tokens in the gateway's own metering unit)
+ * because none of them is fetched here: cost rides in on the chat response the
+ * agent loop was already making, and the weighted multipliers are a compiled-in
+ * constant. Reading a number the server sent is not the same as asking it for
+ * one — the second would be the thing this promise forbids.
  */
 export * from "./types.js";
 export { UsageCollector, accumulateCacheTokens, } from "./collect.js";
-export { costFor, priceForTier } from "./cost.js";
+export { TIER_MULTIPLIERS, multiplierForTier, weightedFor, } from "./weighted.js";
 export { loadUsage, appendRun, usageStorePath } from "./store.js";
-export { summarizeRuns, renderSummary, formatCost, } from "./summary.js";
+export { summarizeRuns, renderSummary, formatCost } from "./summary.js";
+export { runCountLabel, selectRuns, usageReport, } from "./report.js";

package/dist/usage/report.js

@@ -0,0 +1,76 @@
+import { renderSummary, summarizeRuns } from "./summary.js";
+/** Narrow the retained runs to `scope`, newest-last order preserved. */
+export function selectRuns(runs, scope = {}) {
+    let selected = [...runs];
+    if (scope.sessionId !== undefined) {
+        selected = selected.filter((r) => r.sessionId === scope.sessionId);
+    }
+    if (scope.last !== undefined) {
+        // Guarded, not `slice(-last)` alone: `slice(-0)` is `slice(0)` and returns
+        // EVERYTHING, so a zero would quietly widen the scope to the whole store —
+        // the exact opposite of what it asks for.
+        selected = scope.last <= 0 ? [] : selected.slice(-scope.last);
+    }
+    return selected;
+}
+/**
+ * Say what the weighted figure IS, every time it is shown.
+ *
+ * The number is meaningless-to-dangerous without its scope: a reader who assumes
+ * it covers their whole account, or reads it as a remaining balance, has been
+ * misled by a figure that is itself correct. These lines are the only thing
+ * standing between the two readings, which is why they are not optional and not
+ * abbreviated for the in-session surface.
+ */
+function weightedNote(summary, t) {
+    if (summary.totalWeightedTokens !== undefined) {
+        return [
+            t.muted("weighted = (billable input + output) × tier weight — weighted tokens used by\n" +
+                "this CLI, over the runs shown. Not a balance or a limit: it cannot see your\n" +
+                "plan, or what cruxy on the web or desktop used from the same account."),
+        ];
+    }
+    // Absent rather than zero, and the reasons are unguessable from a blank line
+    // — so name them instead of leaving the figure silently missing.
+    return [
+        t.muted([
+            "weighted tokens unavailable for these runs — a request can only be weighed",
+            "when it records a tier and the gateway's billable input count. Runs from an",
+            "older cruxy, or against a non-cruxy provider, carry neither.",
+        ].join("\n")),
+    ];
+}
+/**
+ * The full usage report for `runs`, as lines to print.
+ *
+ * Empty `runs` is a first-class outcome, not an early-return the caller has to
+ * remember: it renders the "nothing yet" answer plus, when tracking is off, the
+ * reason — because "you have run nothing" and "nothing is being recorded" are
+ * different facts with the same blank output.
+ */
+export function usageReport(runs, t, opts) {
+    if (runs.length === 0) {
+        const lines = [t.muted("no usage recorded yet")];
+        if (!opts.trackingEnabled) {
+            lines.push(t.muted("usage tracking is off (usage.enabled = false)"));
+        }
+        return lines;
+    }
+    const summary = summarizeRuns(runs);
+    const lines = [
+        t.heading(`usage — ${opts.scopeLabel}`),
+        renderSummary(summary, t),
+        ...weightedNote(summary, t),
+    ];
+    if (opts.legacyPriceConfig) {
+        lines.push(t.muted([
+            "note: usage.prices / usage.currency are no longer used. Cost is now the",
+            "gateway's own figure. You can remove them from your config.",
+        ].join("\n")));
+    }
+    return lines;
+}
+/** `3 runs` / `1 run` — the countable half of a scope label. */
+export function runCountLabel(n) {
+    return `${n} run${n === 1 ? "" : "s"}`;
+}

package/dist/usage/store.js

@@ -73,7 +73,13 @@ export function appendRun(record, opts = { retention: 50 }) {
     const pruned = runs.slice(-retention); // keep the newest `retention` runs
     try {
         mkdirSync(path.dirname(file), { recursive: true });
-        const body = JSON.stringify({ version: USAGE_FILE_VERSION, runs: pruned }, null, 2);
+        // Spread the loaded file first so any key a NEWER cruxy wrote at the top
+        // level survives this rewrite, the same way unknown keys inside runs and
+        // entries do (see the forward-compatibility note in types.ts). Tolerating a
+        // newer file on read but flattening it on the next append would still lose
+        // the data, just one write later. version/runs are re-stated after the
+        // spread so this build's own values always win.
+        const body = JSON.stringify({ ...loaded.data, version: USAGE_FILE_VERSION, runs: pruned }, null, 2);
         writeFileSync(file, body, { mode: 0o600 });
         return {};
     }

package/dist/usage/summary.js

@@ -1,14 +1,38 @@
 import { formatTokens } from "../render/state.js";
-import { costFor } from "./cost.js";
+import { weightedFor } from "./weighted.js";
+/**
+ * Usage aggregation + rendering (C.22). Aggregation sums only KNOWN figures and
+ * counts the requests that reported none separately, so a total is never
+ * inflated by a fabricated zero — and the renderer ALWAYS surfaces those counts,
+ * so a total can never be misread as complete while requests are silently
+ * excluded. That rule now applies on three independent axes, because a request
+ * can report tokens but no cost, or a cost but nothing weighable:
+ * `requestsWithoutUsage`, `requestsWithoutCost`, `requestsWithoutWeight`.
+ *
+ * Both derived figures come from the server: cost is the gateway's own quote,
+ * weighted tokens are the gateway's own metering formula. Neither is derived
+ * from a user-configured price — there is no longer such a thing here.
+ *
+ * Only tier names ever reach the output (U.8 gag). Pure — no I/O, no network.
+ */
 /** Aggregate one or more run records into a {@link UsageSummary}. */
-export function summarizeRuns(runs, opts) {
+export function summarizeRuns(runs) {
     const byTier = new Map();
     let totalInputTokens;
     let totalOutputTokens;
     let totalCacheReadTokens;
     let totalCacheCreationTokens;
+    let totalBillableInputTokens;
+    let totalWeightedTokens;
+    let totalCost;
     let requests = 0;
     let requestsWithoutUsage = 0;
+    let requestsWithoutWeight = 0;
+    let requestsWithoutCost = 0;
+    // Every distinct currency the gateway stated. Summing across two of them would
+    // require an exchange rate we don't have and would never be told, so the set
+    // is kept and a >1 outcome withholds the total rather than guessing.
+    const currencies = new Set();
     const addKnown = (acc, v) => (v === undefined ? acc : (acc ?? 0) + v);
     for (const run of runs) {
         for (const e of run.entries) {
@@ -16,10 +40,24 @@ export function summarizeRuns(runs, opts) {
             const known = e.inputTokens !== undefined || e.outputTokens !== undefined;
             if (!known)
                 requestsWithoutUsage++;
+            // Weighed per REQUEST, never from the tier's summed totals: the multiplier
+            // is per-tier, but a tier's bucket can mix weighable and unweighable
+            // requests, and multiplying a sum that includes the latter would silently
+            // weigh tokens that were never eligible.
+            const weighted = weightedFor(e.tier, e.billableInputTokens, e.outputTokens);
+            if (weighted === undefined)
+                requestsWithoutWeight++;
+            if (e.costAmount === undefined)
+                requestsWithoutCost++;
+            else if (e.costCurrency !== undefined)
+                currencies.add(e.costCurrency);
             totalInputTokens = addKnown(totalInputTokens, e.inputTokens);
             totalOutputTokens = addKnown(totalOutputTokens, e.outputTokens);
             totalCacheReadTokens = addKnown(totalCacheReadTokens, e.cacheReadTokens);
             totalCacheCreationTokens = addKnown(totalCacheCreationTokens, e.cacheCreationTokens);
+            totalBillableInputTokens = addKnown(totalBillableInputTokens, e.billableInputTokens);
+            totalWeightedTokens = addKnown(totalWeightedTokens, weighted);
+            totalCost = addKnown(totalCost, e.costAmount);
             // Per-tier attribution only for entries that carry a tier. Untiered
             // requests (routing inert) still count toward totals — the total stays
             // honest — but there is no tier label to bucket them under.
@@ -27,42 +65,53 @@ export function summarizeRuns(runs, opts) {
                 const b = byTier.get(e.tier) ?? {
                     requests: 0,
                     requestsWithoutUsage: 0,
+                    requestsWithoutWeight: 0,
                 };
                 b.requests++;
                 if (!known)
                     b.requestsWithoutUsage++;
+                if (weighted === undefined)
+                    b.requestsWithoutWeight++;
                 b.inputTokens = addKnown(b.inputTokens, e.inputTokens);
                 b.outputTokens = addKnown(b.outputTokens, e.outputTokens);
                 b.cacheReadTokens = addKnown(b.cacheReadTokens, e.cacheReadTokens);
                 b.cacheCreationTokens = addKnown(b.cacheCreationTokens, e.cacheCreationTokens);
+                b.billableInputTokens = addKnown(b.billableInputTokens, e.billableInputTokens);
+                b.weightedTokens = addKnown(b.weightedTokens, weighted);
+                b.cost = addKnown(b.cost, e.costAmount);
                 byTier.set(e.tier, b);
             }
         }
     }
+    const costMixedCurrency = currencies.size > 1;
     const perTier = [...byTier.entries()].map(([tier, b]) => ({
         tier,
         inputTokens: b.inputTokens,
         outputTokens: b.outputTokens,
         cacheReadTokens: b.cacheReadTokens,
         cacheCreationTokens: b.cacheCreationTokens,
+        billableInputTokens: b.billableInputTokens,
+        weightedTokens: b.weightedTokens,
         requests: b.requests,
         requestsWithoutUsage: b.requestsWithoutUsage,
-        cost: costFor(tier, b.inputTokens, b.outputTokens, opts.prices),
+        requestsWithoutWeight: b.requestsWithoutWeight,
+        // Withheld under mixed currencies for the same reason the total is: a tier's
+        // requests are not guaranteed to share a currency either.
+        cost: costMixedCurrency ? undefined : b.cost,
     }));
-    const costs = perTier
-        .map((p) => p.cost)
-        .filter((c) => c !== undefined);
-    const priced = costs.length > 0;
-    const totalCost = priced ? costs.reduce((a, c) => a + c, 0) : undefined;
     return {
         perTier,
         totalInputTokens,
         totalOutputTokens,
         totalCacheReadTokens,
         totalCacheCreationTokens,
-        totalCost,
-        priced,
-        currency: opts.currency,
+        totalBillableInputTokens,
+        totalWeightedTokens,
+        requestsWithoutWeight,
+        totalCost: costMixedCurrency ? undefined : totalCost,
+        costCurrency: costMixedCurrency ? undefined : [...currencies][0],
+        costMixedCurrency,
+        requestsWithoutCost,
         requestsWithoutUsage,
         requests,
         runCount: runs.length,
@@ -70,15 +119,27 @@ export function summarizeRuns(runs, opts) {
 }
 /**
  * Format a cost figure honestly: enough precision for small per-run costs,
- * trailing zeros trimmed. Prefixed by the currency label only when one is set
- * (never an assumed symbol). Callers pass a cost only when it was actually
- * computed (priced + known tokens).
+ * trailing zeros trimmed. The currency is the gateway's own code (e.g. "usd"),
+ * so it is appended as a UNIT (`0.0021 USD`) rather than prefixed as a symbol —
+ * a code reads as a suffix, and cruxy no longer has a user-configured symbol to
+ * prefix with. An absent currency renders the bare number rather than assuming
+ * one. Callers pass a cost only when the gateway actually quoted it.
  */
 export function formatCost(n, currency) {
     const abs = Math.abs(n);
     const decimals = abs >= 1 ? 2 : abs >= 0.01 ? 4 : 6;
     const trimmed = n.toFixed(decimals).replace(/\.?0+$/, "");
-    return `${currency}${trimmed === "" || trimmed === "-0" ? "0" : trimmed}`;
+    const amount = trimmed === "" || trimmed === "-0" ? "0" : trimmed;
+    return currency ? `${amount} ${currency.toUpperCase()}` : amount;
+}
+/**
+ * Weighted tokens at status-line width. Rounded to a whole token because the
+ * multipliers are fractional (3.25×, 3.8×) and a `812.5` would imply the meter
+ * counts half-tokens; the unrounded value stays on the summary for anything that
+ * needs the exact arithmetic.
+ */
+function formatWeighted(n) {
+    return formatTokens(Math.round(n));
 }
 /** `↑1.2k ↓340` (worded `up 1.2k down 340` under a screen reader). */
 function tokenText(input, output, t) {
@@ -98,7 +159,9 @@ export function renderSummary(summary, t) {
     for (const p of summary.perTier) {
         const known = p.inputTokens !== undefined || p.outputTokens !== undefined;
         if (known) {
-            const cost = p.cost !== undefined ? ` ${formatCost(p.cost, summary.currency)}` : "";
+            const cost = p.cost !== undefined
+                ? ` ${formatCost(p.cost, summary.costCurrency)}`
+                : "";
             parts.push(`${p.tier} ${tokenText(p.inputTokens, p.outputTokens, t)}${t.muted(cost)}`);
         }
         else {
@@ -111,11 +174,19 @@ export function renderSummary(summary, t) {
     const totalKnown = summary.totalInputTokens !== undefined ||
         summary.totalOutputTokens !== undefined;
     const totalCost = summary.totalCost !== undefined
-        ? ` ${formatCost(summary.totalCost, summary.currency)}`
+        ? ` ${formatCost(summary.totalCost, summary.costCurrency)}`
         : "";
     parts.push(totalKnown
         ? `${t.strong("total")} ${tokenText(summary.totalInputTokens, summary.totalOutputTokens, t)}${t.muted(totalCost)}`
         : `${t.strong("total")} —`);
+    // Weighted tokens — the gateway's own metering unit, computed locally from
+    // billable input + output. Shown only when at least one request could actually
+    // be weighed; the label stays "weighted", never anything implying a balance
+    // (`cruxy usage` carries the fuller wording). A reported 0 IS shown, same rule
+    // as `cached ↻0`: it is a measurement, not an absence.
+    if (summary.totalWeightedTokens !== undefined) {
+        parts.push(t.muted(`weighted ${formatWeighted(summary.totalWeightedTokens)}`));
+    }
     // Cache reads (phase-A caching, Anthropic dev path): shown ONLY when the
     // provider actually reported cache usage — `undefined` on the cruxy gateway
     // and every OpenAI-compat path, so normal users never see this segment. A
@@ -130,6 +201,24 @@ export function renderSummary(summary, t) {
     if (summary.requestsWithoutUsage > 0) {
         parts.push(t.warning(unreported(summary.requestsWithoutUsage)));
     }
+    // Coverage for the two derived figures. Each is emitted only when it says
+    // something the line doesn't already: `requestsWithoutUsage` above already
+    // explains requests that reported nothing at all, so these fire only for the
+    // EXTRA shortfall — requests that did report tokens but still couldn't be
+    // weighed (unknown tier / no billable input) or weren't quoted a cost.
+    const weightShortfall = summary.requestsWithoutWeight - summary.requestsWithoutUsage;
+    if (summary.totalWeightedTokens !== undefined && weightShortfall > 0) {
+        parts.push(t.muted(`${weightShortfall} not weighted`));
+    }
+    const costShortfall = summary.requestsWithoutCost - summary.requestsWithoutUsage;
+    if (summary.totalCost !== undefined && costShortfall > 0) {
+        parts.push(t.muted(`${costShortfall} without cost`));
+    }
+    // Two gateways quoting two currencies: refuse to add them, and say why rather
+    // than just dropping the cost silently.
+    if (summary.costMixedCurrency) {
+        parts.push(t.warning("cost omitted: mixed currencies"));
+    }
     return parts.join(sep);
 }
 /** `2 requests: usage not reported`. */

package/dist/usage/types.js

@@ -8,6 +8,32 @@ import { z } from "zod";
  */
 /** Bump when the on-disk usage file shape changes (enables future migration). */
 export const USAGE_FILE_VERSION = 1;
+/**
+ * FORWARD COMPATIBILITY, and why every schema below is `.passthrough()` rather
+ * than `.strict()`.
+ *
+ * `loadUsage` discards the ENTIRE file on any parse failure (see store.ts) — it
+ * cannot do otherwise, because a file it can't validate is a file it can't
+ * safely append to. Combined with `.strict()`, that made the store hostile to
+ * its own future: the moment a newer cruxy wrote a field an older one didn't
+ * know, the older binary rejected the whole file and the user silently lost
+ * every run of history. Downgrading a CLI, or running two versions against one
+ * home directory, is ordinary — losing accounting for it is not acceptable.
+ *
+ * A version bump alone does NOT fix this: the old binary is already shipped and
+ * still can't parse the new file, whatever the number says. The fix has to be
+ * in the schema that old binaries already run, so it is made here, once, BEFORE
+ * any new field is persisted — that ordering is the whole point.
+ *
+ * `.passthrough()` also PRESERVES unknown keys rather than stripping them, so an
+ * old CLI that loads, prunes and rewrites the file hands a newer CLI's fields
+ * back intact. `.strip()` (zod's default) would tolerate the read and then
+ * quietly erase them on the next write — tolerant to parse, lossy in practice.
+ *
+ * The tradeoff accepted: a typo'd key is no longer a parse error. That is worth
+ * it — this is a local, additive, append-only telemetry file, and every field
+ * the code reads is still fully validated.
+ */
 /**
  * One model request's usage. A request that reported no usage keeps
  * `inputTokens`/`outputTokens` as `undefined` — the honest "unknown", never
@@ -16,7 +42,13 @@ export const USAGE_FILE_VERSION = 1;
  */
 export const UsageEntrySchema = z
     .object({
-    /** The routing tier (C.30) this request ran on; absent when routing is inert. */
+    /**
+     * The tier this request ACTUALLY ran on. Preferentially the tier the gateway
+     * reported serving (v2 `routing.tier`, which resolves `auto` and reflects a
+     * budget downgrade); the client-side routing choice (C.30) only when the
+     * gateway said nothing. Absent when neither is known — e.g. a non-cruxy
+     * provider with routing inert.
+     */
     tier: z.string().optional(),
     /** Provider-reported prompt tokens; `undefined` ⇔ no usage was reported. */
     inputTokens: z.number().int().nonnegative().optional(),
@@ -31,10 +63,47 @@ export const UsageEntrySchema = z
     cacheReadTokens: z.number().int().nonnegative().optional(),
     /** Prompt-cache tokens WRITTEN this request (the ~1.25× write premium); same `undefined`-≠-0 rule. */
     cacheCreationTokens: z.number().int().nonnegative().optional(),
+    /**
+     * Tokens the gateway actually METERED as fresh input — cache-read tokens
+     * excluded, which is what makes the caching win legible. This is the input
+     * term of the weighted-pool formula `(billable_input + output) × multiplier`
+     * that weighted.ts computes, and `inputTokens` is NEVER an acceptable
+     * stand-in for it: substituting a count that includes cache reads overstates
+     * precisely the requests caching made cheaper. Reported by the cruxy v2
+     * wire on every request INCLUDING as a literal `0`, so `undefined` here means
+     * a gateway too old to send it or a provider that never does — unknown, not
+     * zero. Never zero-filled.
+     */
+    billableInputTokens: z.number().int().nonnegative().optional(),
+    /**
+     * The gateway's OWN computed cost for this request (`usage.cost.amount`) and
+     * its currency — the same figure persisted to the server-side ledger, so
+     * client and ledger can never disagree. Recorded verbatim; nothing here is
+     * derived from a user-configured price.
+     *
+     * TWO TRAPS, do not "optimize" either away:
+     *  - `costAmount === 0` is a LEGITIMATE cost (a request that billed nothing),
+     *    NOT a signal that the tier is unpriced. Absence is the only unknown.
+     *  - server-side, an unrecognized model falls through to the mira price rather
+     *    than to no price at all, so a cost is always a real quote for SOME tier —
+     *    you cannot infer "unpriced" from the amount under any circumstances.
+     * Read `costAmount !== undefined` and nothing else.
+     */
+    costAmount: z.number().nonnegative().optional(),
+    /** Currency of {@link costAmount} as the gateway stated it (e.g. "usd"); absent with it. */
+    costCurrency: z.string().optional(),
+    /**
+     * How the served tier was chosen, verbatim from the gateway's `routing.mode`
+     * (`explicit` | `auto` | `auto_degraded`). This is what makes a client/server
+     * tier disagreement explainable after the fact rather than silent: when a
+     * run configured `kavi` but the entry reads `tier: "mira"`, the mode says
+     * whether that was routing working as asked or a budget downgrade.
+     */
+    routingMode: z.string().optional(),
     /** ISO-8601 timestamp the request completed. */
     at: z.string(),
 })
-    .strict();
+    .passthrough();
 /** One run's usage: an ordered list of per-request entries. */
 export const UsageRecordSchema = z
     .object({
@@ -46,11 +115,11 @@ export const UsageRecordSchema = z
     startedAt: z.string(),
     entries: z.array(UsageEntrySchema),
 })
-    .strict();
+    .passthrough();
 /** The persisted store: a bounded, newest-last list of run records. */
 export const UsageFileSchema = z
     .object({
     version: z.literal(USAGE_FILE_VERSION),
     runs: z.array(UsageRecordSchema),
 })
-    .strict();
+    .passthrough();