@trazum/cli 1.10.0 → 1.26.0

package/dist/index.js

@@ -1,14 +1,16 @@
 #!/usr/bin/env node
-import { readFile, stat, writeFile } from 'node:fs/promises';
+import { readdir, readFile, stat, writeFile } from 'node:fs/promises';
 import { join, resolve as resolvePath } from 'node:path';
-import { applyRewrites, BASELINE_FILENAME, BASELINE_VERSION, breaches, cacheableMinimum, cacheHitRate, comparePrompts, compareToBaseline, computeSavings, countTokensAnthropic, DEFAULT_USAGE, detectFromSource, estimateTokens, evaluate, extractPrompts, findExamples, formatBaseline, formatSignedUsd, formatUsd, getMessages, getModel, hasMarker, LOCALES, MAX_BASELINE_BYTES, moneyIsComparable, nearestName, optimize, parseBaseline, PHRASE_LANGUAGES, plannedCalls, profilePrompt, profileUsage, promptId, providerFromEnv, pruneExamples, refineWithLlm, rejectionText, reorderForCache, reviewAgeDays, reviewExamples, RULES, sharedPrefixes, sharesOf, SOURCE_EXTENSIONS, suggestRewrites, toOtlpMetrics, toPromptfoo, UNLABELLED, withExactTokenCounts, } from '@trazum/core';
+import { gunzipSync } from 'node:zlib';
+import { applyRewrites, BASELINE_FILENAME, BASELINE_VERSION, breaches, cacheableMinimum, analyzeCachePrefix, billLevers, cacheEconomics, cacheHitRate, comparePrompts, compareToBaseline, computeSavings, countTokensAnthropic, DEFAULT_USAGE, detectFromSource, driversBetween, estimateTokens, evaluate, extractPrompts, findExamples, formatBaseline, formatSignedUsd, formatUsd, getMessages, getModel, hasMarker, LOCALES, MAX_BASELINE_BYTES, moneyIsComparable, mostSpecificMatch, nearestName, optimize, parseBaseline, PHRASE_LANGUAGES, plannedCalls, profilePrompt, profileToCsv, profileUsage, promptId, providerFromEnv, pruneExamples, refineWithLlm, rejectionText, reorderForCache, repriceProfile, reviewAgeDays, reviewExamples, RULES, sharedPrefixes, sharesOf, SOURCE_EXTENSIONS, suggestRewrites, toOtlpMetrics, toPromptfoo, TTL_1H_MS, UNLABELLED, withExactTokenCounts, } from '@trazum/core';
 import { cacheDir, cacheStats, cachingProvider, clearCache } from './suggest-cache.js';
+import { dayOf, formatGap, median, spanDays } from './time.js';
 // Everything that reads the filesystem, on its own entry point so the web
 // bundle cannot reach it. See packages/core/src/node.ts.
 import { CONFIG_FILENAME, DEFAULT_EXTENSIONS, budgetFor, BUNDLED_CATALOGUE, SAFE_FETCH_INIT, applyPricingOverlay, catalogueFromOverlay, checkedEndpoint, openrouterOverlay, detectHost, loadConfig, walkPrompts, } from '@trazum/core/node';
 import { contentAt, gitAvailable, namesByRevision, pathInRepository, repositoryRoot, revisionsFor, } from './git.js';
 import { detectLocale, getCliMessages } from './i18n/index.js';
-import { MAX_SUMMARY_CHARS, fitWithin, renderBlameMarkdown, renderCheckMarkdown, renderDiffMarkdown, renderRankMarkdown, } from './markdown.js';
+import { MAX_SUMMARY_CHARS, fitWithin, renderBlameMarkdown, renderCheckMarkdown, renderDiffMarkdown, renderRankMarkdown, renderProfileMarkdown, } from './markdown.js';
 // --------------------------------------------------------------------------
 // Presentation
 // --------------------------------------------------------------------------
@@ -22,6 +24,12 @@ const c = {
     cyan: (s) => (useColor ? `\u001b[36m${s}\u001b[39m` : s),
 };
 const VALUE_FLAGS = new Set([
+    'against',
+    // `route` takes a path here, and the flag is deliberately not `--prompt`:
+    // everywhere else in this tool `--prompt` names a marked prompt *inside* a
+    // source file, and reusing it for a path would be a trap laid for the reader.
+    'prompt-file',
+    'label',
     'level',
     'model',
     'calls',
@@ -32,6 +40,15 @@ const VALUE_FLAGS = new Set([
     'cases',
     'concurrency',
     'max-growth',
+    'max-usd',
+    'max-growth-usd',
+    'max-cache-loss-usd',
+    'max-day-usd',
+    'csv-out',
+    'csv-shape',
+    'what-if',
+    'since',
+    'until',
     'export',
     'limit',
     'locale',
@@ -241,7 +258,8 @@ const COMMAND_FLAGS = {
     ],
     check: ['max-tokens', 'level', 'exact-tokens', 'markdown-out', 'baseline'],
     baseline: ['model', 'calls', 'output-tokens', 'cache-hit-rate', 'batch', 'exact-tokens', 'out', 'o'],
-    profile: ['json', 'pricing', 'pricing-live'],
+    profile: ['json', 'pricing', 'pricing-live', 'against', 'what-if', 'markdown-out', 'csv-out', 'csv-shape', 'max-usd', 'max-growth-usd', 'max-cache-loss-usd', 'max-day-usd', 'label', 'since', 'until'],
+    route: ['prompt-file', 'cases', 'label', 'concurrency', 'json', 'yes', 'pricing', 'pricing-live'],
     eval: ['cases', 'level', 'concurrency', 'export', 'out', 'o', 'model'],
     prune: ['cases', 'concurrency', 'json', 'yes'],
     diff: ['level', 'model', 'calls', 'output-tokens', 'batch', 'max-growth', 'optimized', 'markdown-out', 'all', 'prompt'],
@@ -399,7 +417,9 @@ function biggestLever(result, tokensOnly, t) {
         ruleSaving > 0 ? Math.round(best.estimatedMonthlyUsd / ruleSaving) : null),
     };
 }
-function printReport(result, showDiff, t, examplesReview = null, reorder = null, tokensOnly = false, host = { id: 'terminal', displayName: 'terminal', billing: 'unknown', evidence: null }, suggestions = null) {
+function printReport(result, showDiff, t, examplesReview = null, reorder = null, tokensOnly = false, host = { id: 'terminal', displayName: 'terminal', billing: 'unknown', evidence: null }, suggestions = null, 
+/** They named a scenario, and the host is suppressing the money anyway. */
+namedScenario = false) {
     const n = (value) => value.toLocaleString(t.numberLocale);
     const sourceNote = result.tokenSource === 'heuristic'
         ? c.dim(t.report.estimated(offFamilyName(result.usage.model)))
@@ -518,7 +538,7 @@ function printReport(result, showDiff, t, examplesReview = null, reorder = null,
     //
     // What replaces it is the thing that *is* scarce there: the context window.
     if (tokensOnly) {
-        printTokensOnly(result, host, t, n);
+        printTokensOnly(result, host, t, n, namedScenario);
     }
     else {
         printMoney(result, t, n);
@@ -567,6 +587,22 @@ function printReport(result, showDiff, t, examplesReview = null, reorder = null,
     }
     printSuggestions(suggestions, t, n);
     printRest(result, showDiff, t, examplesReview, n);
+    /**
+     * Where the money actually is, said at the front door.
+     *
+     * `optimize` is the first command anybody runs, and it reports the smallest
+     * line item on the bill: measured, about 1% of a monthly figure. Everything
+     * that moves 40% to 80% — which model the call goes to, the Batch API,
+     * caching, what re-sending the conversation costs — lives in `profile`, which
+     * needs a usage log a new reader does not have and has no reason to go looking
+     * for.
+     *
+     * A tool that learned that and only said it in the command you reach last has
+     * not said it. So it prints here, once, at the end, on every run: this is the
+     * small lever, and the big ones are one file away.
+     */
+    console.log();
+    console.log(`  ${c.dim(wrap(tokensOnly ? t.report.beyondThisPromptTokensOnly() : t.report.beyondThisPrompt(), 74, '  '))}`);
 }
 /** The cost section, for anyone billed by the token. */
 function printMoney(result, t, n) {
@@ -596,7 +632,9 @@ function printMoney(result, t, n) {
  * a measurable one, and it is the honest answer to "what did I gain" on a plan
  * that costs the same either way.
  */
-function printTokensOnly(result, host, t, n) {
+function printTokensOnly(result, host, t, n, 
+/** Whether they named a scenario while the money was being withheld. */
+namedScenario = false) {
     const model = getModel(result.usage.model);
     const saved = result.tokensBefore - result.tokensAfter;
     console.log();
@@ -609,10 +647,34 @@ function printTokensOnly(result, host, t, n) {
         : t.report.tokensOnlyAsked()}`);
     console.log();
     console.log(`  ${c.green(t.report.tokensSaved(n(saved)))}`);
-    // Share of the window, which is what a saved token is actually worth here.
+    /**
+     * Share of the window, which is what a saved token is actually worth here.
+     *
+     * A 225-token prompt against a million-token window printed `0.0% → 0.0%`: a
+     * line whose whole job is to say what a token buys, saying nothing twice. When
+     * both sides round to the same figure the honest statement is the other one —
+     * that the window is not the constraint on this prompt.
+     */
     const share = (tokens) => `${((tokens / model.contextWindow) * 100).toFixed(1)}%`;
-    console.log(`  ${c.dim(t.report.windowUse(share(result.tokensBefore), share(result.tokensAfter), model.displayName, n(model.contextWindow)))}`);
-    console.log(`  ${c.dim(t.report.tokensOnlyCost())}`);
+    const before = share(result.tokensBefore);
+    const after = share(result.tokensAfter);
+    /**
+     * Three cases, and the first version had two.
+     *
+     * Equal shares mean either "this prompt is nothing against a million tokens" or
+     * "this prompt is 10% of the window and one token did not move it". Using the
+     * negligible message for both told a reader holding a tenth of a Haiku window
+     * that they were under a tenth of a percent — off by two orders of magnitude,
+     * on a line whose only job is to size the prompt against the window.
+     */
+    const unchanged = before === after;
+    const negligible = after === '0.0%';
+    console.log(`  ${c.dim(!unchanged
+        ? t.report.windowUse(before, after, model.displayName, n(model.contextWindow))
+        : negligible
+            ? t.report.windowNegligible(n(result.tokensAfter), model.displayName, n(model.contextWindow))
+            : t.report.windowUnmoved(after, model.displayName, n(model.contextWindow)))}`);
+    console.log(`  ${c.dim(namedScenario ? t.report.tokensOnlyAskedFor() : t.report.tokensOnlyCost())}`);
 }
 /**
  * The proposed rewrites.
@@ -1116,9 +1178,23 @@ async function commandOptimize(args, config, pricing, t, locale) {
     const tokensOnly = boolFlag(args, 'cost')
         ? false
         : boolFlag(args, 'tokens-only') || host.billing === 'subscription';
+    /**
+     * Whether they named a scenario while the money was being withheld.
+     *
+     * Not a reason to start printing dollars — `--cost` is the documented way to
+     * ask, and `--calls` is a scenario parameter with a default that several
+     * commands take purely to size a finding. Making it imply `--cost` would hand
+     * dollar figures to somebody who put `--calls` in an alias precisely because
+     * they had configured the tool not to show them.
+     *
+     * It is a reason to stop answering with a generic hint. Somebody who typed
+     * `--calls 50000` and read "pass --cost if this prompt is bound for a metered
+     * API" has been told to do a thing they plainly just tried to do.
+     */
+    const namedScenario = args.flags.has('calls') || args.flags.has('output-tokens');
     printReport(result, boolFlag(args, 'diff'), t, examplesReview, reorder, tokensOnly, host, suggestions
         ? { result: suggestions, applied: boolFlag(args, 'apply-suggestions'), locale }
-        : null);
+        : null, namedScenario);
     if (outPath) {
         console.log(c.dim(t.report.wroteTo(outPath)));
         console.log();
@@ -1373,7 +1449,7 @@ function isoDate() {
  * metered API calls somebody was actually billed for — the bill exists wherever
  * Trazum happens to be running, so the host has no bearing on it.
  */
-async function commandProfile(args, pricing, t) {
+async function commandProfile(args, config, pricing, t) {
     const path = args.positional[0];
     if (path === undefined) {
         console.log();
@@ -1381,12 +1457,550 @@ async function commandProfile(args, pricing, t) {
         console.log();
         return;
     }
-    const raw = await readFile(path, 'utf8');
-    const report = profileUsage(raw, { catalogue: pricing });
+    /**
+     * A log, or a directory of them.
+     *
+     * Usage logs rotate: `logs/2026-08-01.jsonl`, `logs/2026-08-02.jsonl`, one
+     * per day for a month. Making somebody `cat` them together before a profile
+     * will read them is a setup cost that gets a tool skipped, and doing it for
+     * them is a directory listing.
+     *
+     * Files are read in name order — which for dated names is time order — and
+     * how many were read is stated, because a report over "the logs" that
+     * silently skipped one is a total that is wrong by an unknown amount. A
+     * directory holding nothing readable is an error naming what it looked for,
+     * not an empty report.
+     */
+    const LOG_EXTENSIONS = ['.jsonl', '.ndjson', '.log', '.json'];
+    /**
+     * The same names, gzipped — which is what a rotated log actually looks like
+     * a day after it rotates.
+     *
+     * `logrotate`, Docker's json-file driver and every cloud log export compress
+     * yesterday's file, so a directory of a month's logs is one plain file and
+     * twenty-nine `.gz` ones. Reading only the plain one and saying nothing
+     * would report a month's bill from a day of it, in the flattering
+     * direction, which is exactly the failure directory mode was added to
+     * prevent.
+     */
+    const GZ_EXTENSIONS = LOG_EXTENSIONS.map((ext) => `${ext}.gz`);
+    const READABLE = [...LOG_EXTENSIONS, ...GZ_EXTENSIONS];
+    const target = await stat(path).catch(() => null);
+    let logFiles = [path];
+    if (target?.isDirectory()) {
+        const entries = await readdir(path, { withFileTypes: true });
+        logFiles = entries
+            .filter((entry) => entry.isFile() && READABLE.some((ext) => entry.name.endsWith(ext)))
+            .map((entry) => join(path, entry.name))
+            .sort((a, b) => a.localeCompare(b));
+        if (logFiles.length === 0) {
+            throw new Error(t.profile.noLogsInDirectory(path, READABLE.join(', ')));
+        }
+    }
+    /**
+     * Gzipped files are decompressed in memory; everything else is read as text.
+     *
+     * Decided by **extension**, not by sniffing the first two bytes: a file
+     * named `.jsonl` whose contents happen to start with 0x1f8b is far more
+     * likely to be a corrupt log than a mislabelled archive, and silently
+     * treating it as one would turn a diagnosable error into an empty report.
+     *
+     * A `.gz` that will not decompress is an error naming the file. The
+     * alternative — skipping it — is a total quietly missing a day, which is
+     * the failure this repository refuses in every other place it can occur.
+     */
+    const readLog = async (file) => {
+        if (!file.endsWith('.gz'))
+            return readFile(file, 'utf8');
+        const compressed = await readFile(file);
+        try {
+            return gunzipSync(compressed).toString('utf8');
+        }
+        catch (error) {
+            throw new Error(t.profile.badGzip(file, error instanceof Error ? error.message : String(error)));
+        }
+    };
+    const logTexts = await Promise.all(logFiles.map((file) => readLog(file)));
+    // A file that does not end in a newline would otherwise glue its last record
+    // to the next file's first one, and both would be reported as unreadable.
+    const raw = logTexts.map((text) => (text.endsWith('\n') ? text : `${text}\n`)).join('');
+    /**
+     * The drill-down. A label that matches nothing is an error naming the labels
+     * that exist — the route command's rule, for the route command's reason: a
+     * report over zero calls silently filtered would read as "this workload is
+     * free".
+     */
+    const onlyLabel = stringFlag(args, 'label');
+    /**
+     * The drill-down in time. `--since`/`--until` take a UTC day or a full
+     * timestamp; a bare day means the whole of it — since its first instant,
+     * until its last — because "--until 2026-08-14" excluding the named day is
+     * a trap sprung on everyone who reads dates the way humans do. Internally
+     * the window is half-open `[since, until)`, so two adjacent windows share
+     * no record.
+     */
+    const now = Date.now();
+    let relativeWindow = false;
+    const parseWhen = (flag, endOfDay) => {
+        const value = stringFlag(args, flag);
+        if (value === undefined)
+            return undefined;
+        /**
+         * A relative window — `7d`, `24h` — because "the last week" is what a
+         * nightly job actually wants, and computing a date in a shell to say it
+         * is the step that gets skipped.
+         *
+         * Relative to **the machine's clock, not the log's**, which is a real
+         * difference: a log exported last month answers `--since 7d` with
+         * nothing, and the report says so rather than reporting $0. That caveat
+         * is stated beside the window line, because a period the reader did not
+         * name is a period they will misread.
+         */
+        const relative = /^(\d+)([dh])$/.exec(value);
+        if (relative) {
+            const amount = Number(relative[1]);
+            if (amount > 0) {
+                relativeWindow = true;
+                const span = relative[2] === 'd' ? 86_400_000 : 3_600_000;
+                return now - amount * span;
+            }
+        }
+        if (/^\d{4}-\d{2}-\d{2}$/.test(value)) {
+            const midnight = Date.parse(`${value}T00:00:00Z`);
+            if (Number.isFinite(midnight))
+                return endOfDay ? midnight + 86_400_000 : midnight;
+        }
+        if (value === 'now')
+            return now;
+        const exact = Date.parse(value);
+        if (Number.isFinite(exact))
+            return exact;
+        throw new Error(t.profile.badWhen(flag, value));
+    };
+    const sinceMs = parseWhen('since', false);
+    const untilMs = parseWhen('until', true);
+    if (sinceMs !== undefined && untilMs !== undefined && sinceMs >= untilMs) {
+        throw new Error(t.profile.sinceAfterUntil());
+    }
+    const windowed = sinceMs !== undefined || untilMs !== undefined;
+    /**
+     * How old the price table behind every dollar below is. Stated only when it
+     * is old enough to matter: `models` and `doctor` always print the date, but
+     * a profile is read for its figures, and the one fact that silently
+     * invalidates all of them is a table the provider has re-priced since.
+     * The threshold is in the sentence, not hidden here.
+     */
+    const STALE_PRICING_DAYS = 45;
+    const pricingAgeDays = reviewAgeDays(pricing.lastReviewed, new Date());
+    const pricingStale = pricingAgeDays !== null && pricingAgeDays > STALE_PRICING_DAYS
+        ? { date: pricing.lastReviewed, days: pricingAgeDays }
+        : null;
+    const report = profileUsage(raw, { catalogue: pricing, label: onlyLabel, sinceMs, untilMs });
+    if (report.total.calls === 0 && report.unpriced.calls === 0) {
+        if (onlyLabel !== undefined || windowed) {
+            // Diagnose against the log without the failed filter, so the error can
+            // name what does exist instead of describing an absence.
+            const unfiltered = profileUsage(raw, { catalogue: pricing });
+            if (unfiltered.total.calls > 0 || unfiltered.unpriced.calls > 0) {
+                if (onlyLabel !== undefined && !unfiltered.byLabel.some((r) => r.label === onlyLabel)) {
+                    const available = unfiltered.byLabel
+                        .map((r) => (r.label === UNLABELLED ? t.profile.unlabelled() : r.label))
+                        .join(', ');
+                    throw new Error(t.route.labelNotFound(onlyLabel, available || '—'));
+                }
+                if (windowed) {
+                    /**
+                     * A window that matches nothing must not become a $0 report — under
+                     * `--max-usd` it would pass a budget gate over a period the log
+                     * simply does not cover, which is the flattering non-answer. The
+                     * error names what the log *does* cover, or says it has no clock at
+                     * all, so the fix is visible in the message.
+                     */
+                    if (unfiltered.span === null)
+                        throw new Error(t.profile.windowNeedsClock());
+                    throw new Error(`${t.profile.windowMatchesNothing(dayOf(unfiltered.span.fromMs), dayOf(unfiltered.span.toMs))}${relativeWindow ? ` ${t.profile.windowRelativeEmpty()}` : ''}`);
+                }
+            }
+        }
+    }
     const n = (value) => value.toLocaleString(t.numberLocale);
     const pct = (share) => `${(share * 100).toFixed(1)}%`;
+    /**
+     * The previous log, loaded before the output paths split so the growth gate
+     * exists under `--json` too — a CI step reads the JSON and trusts the exit
+     * code, and a gate that only arms in the human rendering is a gate CI never
+     * had.
+     */
+    const againstPath = stringFlag(args, 'against');
+    // The same filter on both sides: comparing one workload's bill against the
+    // whole previous log would report every sibling workload as vanished savings.
+    const previous = againstPath !== undefined
+        // The same reader as the log itself, so `--against last-month.jsonl.gz`
+        // works: a comparison that could only read one of the two formats would
+        // be a flag that fails on exactly the rotated file it exists to read.
+        ? profileUsage(await readLog(againstPath), {
+            catalogue: pricing,
+            label: onlyLabel,
+            // The same window on both sides, for the same reason as the label:
+            // a windowed bill against an unwindowed one compares a slice to a
+            // whole and calls the difference growth.
+            sinceMs,
+            untilMs,
+        })
+        : null;
+    const againstDelta = previous !== null && previous.total.calls > 0
+        ? report.total.totalUsd - previous.total.totalUsd
+        : null;
+    /**
+     * The same tokens at another model's rates, computed before the output paths
+     * split so `--json` carries it too.
+     *
+     * An unknown id **throws** rather than printing nothing. A flag that silently
+     * does nothing is worse than a missing feature: the reader typed a question,
+     * got a report with no answer in it, and has no way to tell a typo from a
+     * model this comparison had nothing to say about.
+     */
+    const whatIfModel = stringFlag(args, 'what-if');
+    const whatIf = whatIfModel !== undefined ? repriceProfile(report, whatIfModel, pricing) : null;
+    if (whatIfModel !== undefined && whatIf === null) {
+        throw new Error(t.profile.whatIfUnknown(whatIfModel, pricing.models.map((m) => m.id).join(', ')));
+    }
+    /**
+     * The drivers of the change, per label and per model, computed once here so
+     * the terminal, the JSON and any future rendering describe the same change.
+     * The model half answers the question the label half cannot: "the growth is
+     * traffic moving from Haiku to Opus" is a fact about the mix, invisible in
+     * per-workload rows whose names did not change.
+     */
+    const labelDrivers = previous !== null && previous.total.calls > 0
+        ? driversBetween(previous.byLabel.map((r) => ({ key: r.label, usd: r.breakdown.totalUsd })), report.byLabel.map((r) => ({ key: r.label, usd: r.breakdown.totalUsd })))
+        : [];
+    const modelDrivers = previous !== null && previous.total.calls > 0
+        ? driversBetween(previous.byModel.map((r) => ({ key: r.model, usd: r.breakdown.totalUsd })), report.byModel.map((r) => ({ key: r.model, usd: r.breakdown.totalUsd })))
+        : [];
+    /**
+     * Whether the two logs share any time at all. This comparison is meant for
+     * disjoint periods or snapshots of different systems; when both spans are
+     * known and intersect, the same calls may sit on both sides of the
+     * subtraction and the "growth" is partly the same money counted twice.
+     * Only decidable when both logs carry a clock — three states, as always:
+     * warned, clear, or unknown, and unknown stays silent rather than clear.
+     */
+    const againstOverlap = previous !== null &&
+        previous.total.calls > 0 &&
+        previous.span !== null &&
+        report.span !== null &&
+        Math.min(report.span.toMs, previous.span.toMs) >=
+            Math.max(report.span.fromMs, previous.span.fromMs)
+        ? {
+            fromMs: Math.max(report.span.fromMs, previous.span.fromMs),
+            toMs: Math.min(report.span.toMs, previous.span.toMs),
+        }
+        : null;
+    // A gate flag that silently does nothing is not an answer — same rule as
+    // --apply-suggestions without --suggest.
+    if (typeof args.flags.get('max-growth-usd') === 'string' && againstPath === undefined) {
+        throw new Error(t.profile.maxGrowthNeedsAgainst());
+    }
+    /**
+     * The money gates, armed by flags and applied on every output path.
+     *
+     * `check` gates tokens before the money is spent; these gate the spend
+     * itself, from the provider's own billed counts. No period is assumed —
+     * the budget applies to exactly the log handed in, so a nightly job that
+     * profiles yesterday's log has a daily budget without Trazum ever
+     * guessing what a day is.
+     */
+    const applyGates = () => {
+        /**
+         * Before any verdict: whether the gated figure is the whole bill. A gate
+         * can only judge the money it can see, and three things hide money from
+         * it — unreadable lines, unpriced models, and clockless calls left
+         * outside a window. Passing on a floor is acceptable; passing on a floor
+         * *silently* is the flattering omission this repository refuses, because
+         * an over-budget bill with three corrupt lines would read as green.
+         */
+        const anyGate = typeof args.flags.get('max-usd') === 'string' ||
+            typeof args.flags.get('max-growth-usd') === 'string' ||
+            typeof args.flags.get('max-cache-loss-usd') === 'string' ||
+            typeof args.flags.get('max-day-usd') === 'string' ||
+            config.spend !== undefined;
+        if (anyGate) {
+            const reasons = [];
+            if (report.skippedLines.length > 0)
+                reasons.push(t.profile.floorSkipped(report.skippedLines.length));
+            if (report.unpriced.calls > 0)
+                reasons.push(t.profile.floorUnpriced(report.unpriced.calls));
+            if (report.timeWindow !== null && report.timeWindow.undatedExcluded > 0) {
+                reasons.push(t.profile.floorUndated(report.timeWindow.undatedExcluded));
+            }
+            if (reasons.length > 0) {
+                console.error(c.yellow(t.profile.gateOnFloor(reasons.join('; '))));
+            }
+        }
+        /**
+         * Per-workload budgets from the config — the policy in the repository
+         * rather than in one CI invocation. Each label is gated against its own
+         * spend in the same run, and a budgeted label with no calls in this log
+         * is reported as **not measured**: a workload that did not appear is not
+         * a workload that came in under budget, and printing green over an
+         * absence is exactly the flattering direction this tool refuses.
+         */
+        const byLabel = config.spend?.byLabel;
+        if (byLabel !== undefined && !windowed) {
+            const spent = new Map(report.byLabel.map((r) => [r.label, r.breakdown.totalUsd]));
+            for (const [label, limit] of Object.entries(byLabel)) {
+                const usd = spent.get(label);
+                if (usd === undefined) {
+                    console.error(c.dim(t.profile.labelBudgetMissing(label)));
+                    continue;
+                }
+                if (usd > limit) {
+                    console.error(c.red(t.profile.labelBudgetFailed(label, formatUsd(usd), formatUsd(limit))));
+                    process.exitCode = 1;
+                }
+                else {
+                    console.error(c.dim(t.profile.labelBudgetOk(label, formatUsd(usd), formatUsd(limit))));
+                }
+            }
+        }
+        else if (byLabel !== undefined && windowed) {
+            // A window changes what "this label spent" means, and a budget written
+            // for a period the caller did not name would gate against a slice.
+            console.error(c.dim(t.profile.labelBudgetWindowed()));
+        }
+        if (typeof args.flags.get('max-usd') === 'string' || config.spend?.maxUsd !== undefined) {
+            const maxUsd = typeof args.flags.get('max-usd') === 'string'
+                ? numberFlag(args, 'max-usd', 0, t)
+                : config.spend.maxUsd;
+            if (report.total.totalUsd > maxUsd) {
+                console.error(c.red(t.profile.maxUsdFailed(formatUsd(report.total.totalUsd), formatUsd(maxUsd))));
+                process.exitCode = 1;
+            }
+            else {
+                console.error(c.dim(t.profile.maxUsdOk(formatUsd(report.total.totalUsd), formatUsd(maxUsd))));
+            }
+        }
+        if (typeof args.flags.get('max-growth-usd') === 'string' && againstDelta !== null) {
+            const maxGrowth = numberFlag(args, 'max-growth-usd', 0, t);
+            if (againstDelta > maxGrowth) {
+                console.error(c.red(t.profile.maxGrowthUsdFailed(formatSignedUsd(againstDelta), formatUsd(maxGrowth))));
+                process.exitCode = 1;
+            }
+        }
+        /**
+         * The cache gate, and it reads the worst case on purpose. A log carrying
+         * only the flat cache-write count cannot say which TTL was paid, and the
+         * two verdicts can straddle the limit — a gate reading the flattering
+         * half would pass exactly the bills it exists to catch. The failure
+         * message says which claim fired: a settled loss, or a ceiling only the
+         * missing "cache_creation" field can settle.
+         */
+        if (typeof args.flags.get('max-cache-loss-usd') === 'string') {
+            const maxLoss = numberFlag(args, 'max-cache-loss-usd', 0, t);
+            const gateCache = cacheEconomics(report.total);
+            if (gateCache.deltaUsd > maxLoss) {
+                console.error(c.red(t.profile.maxCacheLossFailed(formatUsd(gateCache.deltaUsd), formatUsd(maxLoss))));
+                process.exitCode = 1;
+            }
+            else if (gateCache.worstCaseDeltaUsd > maxLoss) {
+                console.error(c.red(t.profile.maxCacheLossWorstCase(report.total.assumedWriteTtlCalls, formatUsd(gateCache.worstCaseDeltaUsd), formatUsd(maxLoss))));
+                process.exitCode = 1;
+            }
+            else {
+                console.error(c.dim(t.profile.maxCacheLossOk(formatUsd(Math.max(0, gateCache.worstCaseDeltaUsd)), formatUsd(maxLoss))));
+            }
+        }
+        /**
+         * The per-day gate — the one a total cannot arm.
+         *
+         * A month at $3,000 against a $4,000 budget passes while one afternoon's
+         * runaway agent loop burned $900 of it in four hours. `--max-usd` gates
+         * the sum handed in; this gates the **worst single UTC day inside it**,
+         * which is the shape a loop, a bad deploy or a retry storm actually has.
+         *
+         * Two refusals it inherits from the rest of the tool:
+         *
+         * A log with **no clock at all** cannot be judged by day, and that is an
+         * error rather than a pass. "Not measured" is not "under budget", and a
+         * gate that silently green-lights an unmeasurable log is worse than one
+         * that was never armed.
+         *
+         * The first and last day of a log are usually **partial**, so a day under
+         * the limit here is under it for the hours the log contains. A day *over*
+         * the limit is over it whatever the missing hours held — the failure is
+         * sound in both directions, the pass is a floor, and the pass message
+         * says so when the span does not start and end on a day boundary.
+         */
+        if (typeof args.flags.get('max-day-usd') === 'string') {
+            const maxDay = numberFlag(args, 'max-day-usd', 0, t);
+            if (report.spendByDay.length === 0) {
+                console.error(c.red(t.profile.maxDayNoClock()));
+                process.exitCode = 1;
+            }
+            else {
+                const worst = report.spendByDay.reduce((a, b) => (b.usd > a.usd ? b : a));
+                const suspect = worst.topLabel !== null && report.byLabel.length > 1
+                    ? ` ${t.profile.dayPeakLabel(worst.topLabel === UNLABELLED ? t.profile.unlabelled() : worst.topLabel, formatUsd(worst.topLabelUsd))}`
+                    : '';
+                if (worst.usd > maxDay) {
+                    console.error(c.red(`${t.profile.maxDayFailed(worst.day, formatUsd(worst.usd), formatUsd(maxDay))}${suspect}`));
+                    process.exitCode = 1;
+                }
+                else {
+                    console.error(c.dim(t.profile.maxDayOk(worst.day, formatUsd(worst.usd), formatUsd(maxDay))));
+                    /**
+                     * Calls with no clock are in the bill above and in no day below, so
+                     * the worst day is a floor by exactly that much. Said only on a
+                     * pass: a failure stands whatever the undated calls held.
+                     */
+                    const undated = report.fieldCoverage.parsed - report.fieldCoverage.ts;
+                    if (undated > 0) {
+                        console.error(c.yellow(t.profile.maxDayUndated(n(undated))));
+                    }
+                }
+            }
+        }
+    };
+    /**
+     * The side files the caller asked for. Written on **both** output paths:
+     * under --json the human rendering returns early, and the first version of
+     * --csv-out therefore wrote nothing at all there — a flag that silently did
+     * nothing, which is the fault this repository keeps refusing elsewhere.
+     */
+    const writeSideFiles = async () => {
+        /**
+         * Where the "wrote to" notice goes. Under `--json`, stdout carries the
+         * report and nothing else — a status line there turns a parseable
+         * document into a parse error, which is how a pipeline discovers the
+         * feature. The gates already route their verdicts to stderr for the same
+         * reason.
+         */
+        const notice = boolFlag(args, 'json')
+            ? (message) => console.error(message)
+            : (message) => console.log(message);
+        /**
+           * The same report as GitHub-flavoured markdown, for a job summary or a PR
+           * comment. Written from the same message catalogue the terminal used, because
+           * two renderings of one finding drift the moment they are worded twice.
+           */
+        const markdownOut = stringFlag(args, 'markdown-out');
+        if (markdownOut !== undefined) {
+            await writeFile(markdownOut, renderProfileMarkdown({
+                report,
+                levers,
+                cache,
+                t,
+                ...(windowed
+                    ? { window: { since: stringFlag(args, 'since') ?? '—', until: stringFlag(args, 'until') ?? '—' } }
+                    : {}),
+                ...(pricingStale !== null ? { stalePricing: pricingStale } : {}),
+                // The repricing, when --what-if was given: computed once above and
+                // handed over, so the summary in a pull request cannot disagree
+                // with the terminal about what a move would cost.
+                ...(whatIf !== null ? { whatIf } : {}),
+                // The comparison, when there was one — the same figures and the same
+                // drivers the terminal printed, never re-derived here.
+                ...(previous !== null
+                    ? {
+                        against: {
+                            previousTotalUsd: previous.total.totalUsd,
+                            previousCalls: previous.total.calls,
+                            labelDrivers,
+                            modelDrivers: new Set([
+                                ...previous.byModel.map((r) => r.model),
+                                ...report.byModel.map((r) => r.model),
+                            ]).size > 1
+                                ? modelDrivers
+                                : [],
+                            overlap: againstOverlap !== null
+                                ? { from: dayOf(againstOverlap.fromMs), to: dayOf(againstOverlap.toMs) }
+                                : null,
+                            nothingPriced: previous.total.calls === 0,
+                        },
+                    }
+                    : {}),
+            }), 'utf8');
+            notice(c.dim(t.report.wroteTo(markdownOut)));
+        }
+        /**
+         * The same report as a spreadsheet, one row per label and model — the grain
+         * a routing or budget decision is made at. Deliberately without a total
+         * row: a total inside a data file is summed with the data and doubles every
+         * figure downstream.
+         */
+        const csvOut = stringFlag(args, 'csv-out');
+        if (csvOut !== undefined) {
+            /**
+             * Which table the file holds. One row shape per file on purpose: a
+             * spreadsheet that has to filter before it can sum is a spreadsheet
+             * somebody sums wrong.
+             */
+            const shape = stringFlag(args, 'csv-shape') ?? 'slice';
+            if (shape !== 'slice' && shape !== 'day' && shape !== 'hour') {
+                throw new Error(t.profile.badCsvShape(shape));
+            }
+            await writeFile(csvOut, profileToCsv(report, { unlabelled: t.profile.unlabelled(), shape }), 'utf8');
+            notice(c.dim(t.report.wroteTo(csvOut)));
+        }
+    };
     if (boolFlag(args, 'json')) {
-        console.log(JSON.stringify(report, null, 2));
+        /**
+         * The report, plus everything the human output leads on.
+         *
+         * Additive rather than a reshape: `report` keeps the shape `@trazum/core`
+         * returns. The cache verdict is included because leaving a consumer to
+         * re-derive it means two implementations of a sign convention where positive
+         * means *worse*, and one of them will eventually get it backwards.
+         *
+         * `levers` is included because it was not, and that made the flagship
+         * section terminal-only: "What would actually move this bill" — the reason
+         * the command exists — was invisible to any pipeline, dashboard or CI step
+         * reading the JSON. A finding the machine-readable output omits is a finding
+         * the reader's tooling will never surface.
+         */
+        console.log(JSON.stringify({
+            /**
+             * The contract version, documented in docs/json-output.md and
+             * enforced by json-contract.test.js. It changes only when a
+             * field's meaning changes or one is removed — new findings arrive
+             * as new keys, so a consumer that ignores unknown ones keeps
+             * working. Without it, every dashboard built on this output has to
+             * guess whether a missing key means "old Trazum" or "no data".
+             */
+            schemaVersion: 1,
+            ...report,
+            cache: cacheEconomics(report.total),
+            cacheByLabel: report.byLabel.map((r) => ({
+                label: r.label,
+                cache: cacheEconomics(r.breakdown),
+            })),
+            // The provenance of every dollar above: which price table, how old.
+            pricing: { lastReviewed: pricing.lastReviewed, ageDays: pricingAgeDays },
+            levers: billLevers(report, { catalogue: pricing }),
+            // Present only when --against was passed: null delta means the
+            // previous log had nothing priced, which is a different answer from
+            // zero growth.
+            ...(previous !== null
+                ? {
+                    against: {
+                        previousTotalUsd: previous.total.totalUsd,
+                        deltaUsd: againstDelta,
+                        // The same drivers the terminal names, as data. A finding
+                        // the machine-readable output omits is a finding the
+                        // reader's tooling will never surface.
+                        byLabel: labelDrivers,
+                        byModel: modelDrivers,
+                    },
+                }
+                : {}),
+            // Present only when --what-if was passed. `sameTokensAssumed` rides
+            // along inside it so a consumer cannot print the dollar figure
+            // without the caveat being in the same object.
+            ...(whatIf !== null ? { whatIf } : {}),
+        }, null, 2));
+        await writeSideFiles();
+        applyGates();
         return;
     }
     /**
@@ -1404,7 +2018,7 @@ async function commandProfile(args, pricing, t) {
     if (report.total.calls === 0) {
         console.log();
         console.log(c.dim(report.unpriced.calls === 0 ? t.profile.empty() : t.profile.nothingPriced()));
-        reportProfileGaps(report, t, n);
+        reportProfileGaps(report, t, n, pricingStale);
         return;
     }
     const shares = sharesOf(report.total);
@@ -1416,7 +2030,56 @@ async function commandProfile(args, pricing, t) {
     ];
     console.log();
     console.log(c.bold(t.profile.heading()));
-    console.log(`  ${t.profile.spent(n(report.total.calls), formatUsd(report.total.totalUsd))}`);
+    console.log(`  ${t.profile.spent(t.profile.calls(report.total.calls), formatUsd(report.total.totalUsd))}`);
+    /**
+     * The period, when the log carries a clock — stated, never extrapolated. A
+     * span makes the reader's own monthly arithmetic valid; a per-month figure
+     * printed from a partial month would be this tool doing the guessing it
+     * exists to end. Partial coverage is said in the same breath, because a span
+     * over a third of the calls silently presented as the log's period is a
+     * figure attributed to something it does not describe.
+     */
+    if (report.span !== null) {
+        const totalParsed = report.total.calls + report.unpriced.calls;
+        const partial = report.span.calls < totalParsed
+            ? ` ${t.profile.spanPartial(n(report.span.calls), n(totalParsed))}`
+            : '';
+        console.log(`  ${c.dim(wrap(`${t.profile.spanLine(dayOf(report.span.fromMs), dayOf(report.span.toMs), spanDays(report.span.fromMs, report.span.toMs))}${partial}`, 74, '  '))}`);
+    }
+    // How many files this report covers, when it covers more than one: a total
+    // over "the logs" that silently skipped one is wrong by an unknown amount.
+    if (logFiles.length > 1) {
+        console.log(`  ${c.dim(wrap(t.profile.readFiles(logFiles.length, path), 74, '  '))}`);
+    }
+    /**
+     * A doubled bill, said before anything is believed.
+     *
+     * Reading a directory of rotated logs makes double-counting easy — a log
+     * exported twice, an overlapping export, a copy left in the folder — and
+     * the total then reads high with nothing else able to see it. Only counted
+     * over records with a clock, where an identical line is a claim worth
+     * making. It states the count and the money and stops: whether it is a
+     * double export or a genuinely busy millisecond is the reader's to know.
+     */
+    if (report.duplicateLines.count > 0) {
+        console.log(`  ${c.yellow('!')} ${c.dim(wrap(t.profile.duplicateLines(report.duplicateLines.count, formatUsd(report.duplicateLines.usd)), 74, '    '))}`);
+    }
+    /**
+     * The window, said before any figure is trusted as "the log": everything
+     * below describes a slice, and a slice presented as the whole is a figure
+     * attributed to something it does not describe. The undated count is loud —
+     * those calls' spend is in the log and not in this report, so the window's
+     * figures are a floor on the period, and only this line says so.
+     */
+    if (report.timeWindow !== null) {
+        console.log(`  ${c.dim(wrap(t.profile.windowLine(stringFlag(args, 'since') ?? '—', stringFlag(args, 'until') ?? '—'), 74, '  '))}`);
+        if (relativeWindow) {
+            console.log(`  ${c.dim(wrap(t.profile.windowRelative(), 74, '  '))}`);
+        }
+        if (report.timeWindow.undatedExcluded > 0) {
+            console.log(`  ${c.yellow(wrap(t.profile.windowUndated(report.timeWindow.undatedExcluded), 74, '  '))}`);
+        }
+    }
     console.log();
     // Every part, including the zero ones. A row missing because it was zero reads
     // as a row somebody forgot, and "you are not caching at all" is a finding.
@@ -1439,10 +2102,352 @@ async function commandProfile(args, pricing, t) {
     else {
         console.log(`  ${c.bold(t.profile.biggestPart(biggestName, pct(biggestShare)))}`);
     }
+    /**
+     * The most expensive day, with a suspect attached.
+     *
+     * The shape of a bill over time is the finding the total hides: a steady $3 a
+     * day and a quiet week broken by one $40 spike sum to the same number and call
+     * for opposite responses. Rendered against the **median** day — a mean would
+     * let the spike inflate its own yardstick — and loud only when it clears twice
+     * the median, a threshold stated in the sentence rather than hidden in code.
+     */
+    if (report.spendByDay.length >= 2) {
+        const medianUsd = median(report.spendByDay.map((d) => d.usd));
+        const peak = report.spendByDay.reduce((a, b) => (b.usd > a.usd ? b : a));
+        if (medianUsd > 0) {
+            const ratio = (peak.usd / medianUsd).toFixed(1);
+            const line = t.profile.dayPeak(peak.day, formatUsd(peak.usd), ratio);
+            const labelClause = peak.topLabel !== null && report.byLabel.length > 1
+                ? ` ${t.profile.dayPeakLabel(peak.topLabel === UNLABELLED ? t.profile.unlabelled() : peak.topLabel, formatUsd(peak.topLabelUsd))}`
+                : '';
+            const loud = peak.usd > 2 * medianUsd;
+            const text = wrap(`${line}${labelClause}`, 74, '  ');
+            console.log(`  ${loud ? c.yellow(text) : c.dim(text)}`);
+        }
+    }
+    /**
+     * The shape of the day, and what it says about batching.
+     *
+     * Spend packed into the hours a country is awake is interactive traffic
+     * somebody is waiting on; spend spread evenly across twenty-four is
+     * background work — and background work is what the Batch API halves. The
+     * measure is exact and needs no threshold to state: the **fewest hours that
+     * hold 80% of the spend**. Two or three means concentrated; sixteen means
+     * flat.
+     *
+     * It says what the shape is and stops. Whether a workload can wait is a
+     * product decision Trazum cannot make from counts, so the sentence names
+     * the lever and never claims the saving — the batch figure the levers
+     * section already prints is the one with money attached.
+     */
+    if (report.spendByHour.length >= 4 && report.total.totalUsd > 0) {
+        const sorted = [...report.spendByHour].sort((a, b) => b.usd - a.usd);
+        let covered = 0;
+        let hoursForMost = 0;
+        for (const hour of sorted) {
+            covered += hour.usd;
+            hoursForMost += 1;
+            if (covered >= 0.8 * report.total.totalUsd)
+                break;
+        }
+        const busiest = sorted
+            .slice(0, hoursForMost)
+            .map((hour) => hour.hour)
+            .sort((a, b) => a - b)
+            .map((hour) => `${String(hour).padStart(2, '0')}:00`)
+            .join(', ');
+        console.log();
+        console.log(`  ${c.dim(wrap(hoursForMost <= 8 ? t.profile.hoursConcentrated(n(hoursForMost), busiest) : t.profile.hoursFlat(n(hoursForMost)), 74, '  '))}`);
+    }
+    /**
+     * The hit rate, and then the question the hit rate does not answer.
+     *
+     * `cacheNever()` is keyed off the **verdict**, not off a null hit rate. Those
+     * two came apart on a log whose calls were entirely cache writes with no plain
+     * input: the rate is undefined there — zero reads over zero attempts — while
+     * caching was plainly in use, and the old branch printed "caching was never
+     * used" over a bill made of cache writes.
+     */
+    const cache = cacheEconomics(report.total);
     const hitRate = cacheHitRate(report.total);
-    console.log(hitRate === null
-        ? `  ${c.dim(wrap(t.profile.cacheNever(), 74, '  '))}`
-        : `  ${c.dim(t.profile.cacheHit(pct(hitRate)))}`);
+    if (cache.verdict === 'not-attempted') {
+        console.log(`  ${c.dim(wrap(t.profile.cacheNever(), 74, '  '))}`);
+    }
+    else if (hitRate !== null) {
+        console.log(`  ${c.dim(t.profile.cacheHit(pct(hitRate)))}`);
+    }
+    /**
+     * Whether the caching was worth doing — the one finding here that can
+     * contradict the advice Trazum gives everywhere else.
+     *
+     * A cache write costs 1.25x plain input on Anthropic and 2x at the one-hour
+     * TTL, so a prefix rebuilt faster than it is reused is billed at a premium and
+     * returns nothing: that workload is cheaper with caching switched off. The
+     * counterfactual is exact rather than a projection — caching changes the
+     * multiplier on a token, never the token — so this is the one place in `profile`
+     * where a comparison against what-might-have-been is arithmetic instead of a
+     * guess about a prompt nobody wrote.
+     */
+    /**
+     * The losing labels, **ranked by what caching cost them** and not by bill size.
+     *
+     * `byLabel` arrives sorted by total spend, which is the right order for the
+     * table above and the wrong one here: the worst cache in an estate usually sits
+     * on a small workload, so taking the first three off a spend-ordered list meant
+     * the biggest loser could be the one that went unnamed.
+     */
+    const lostLabels = report.byLabel
+        .map((r) => ({ row: r, cache: cacheEconomics(r.breakdown) }))
+        .filter((r) => r.cache.verdict === 'lost-money')
+        .sort((a, b) => b.cache.deltaUsd - a.cache.deltaUsd);
+    const NAMED = 3;
+    const nameOf = (row) => row.label === UNLABELLED ? t.profile.unlabelled() : row.label;
+    /**
+     * The names, with the ones that did not fit **counted rather than dropped**.
+     *
+     * The first version sliced to three silently while the money beside it was
+     * summed over every loser — so four bleeding labels printed three names and a
+     * figure that charged them with a fourth label's loss. Truncating is fine;
+     * truncating without saying so is the flattering omission this repository keeps
+     * catching itself at, and `reportProfileGaps` already had the pattern.
+     */
+    const listNames = (rows) => {
+        const names = rows.slice(0, NAMED).map((r) => nameOf(r.row)).join(', ');
+        return rows.length <= NAMED
+            ? names
+            : `${names} ${t.profile.andMoreLabels(rows.length - NAMED)}`;
+    };
+    const namedLosers = listNames(lostLabels);
+    const bleeding = lostLabels.reduce((sum, r) => sum + r.cache.deltaUsd, 0);
+    /**
+     * Whether the log can settle the question at all.
+     *
+     * Decided before anything prints, because it governs whether the confident
+     * sentence prints — not merely whether a caveat follows it. The first attempt
+     * added the caveat and left the assertion above it, so the reader met `Caching
+     * took $0.1000 off this bill` and only afterwards learned it might be a $3.65
+     * loss. A finding a later line retracts is still a finding somebody acted on.
+     */
+    const unsettled = cache.worstCaseVerdict !== cache.verdict && report.total.assumedWriteTtlCalls > 0;
+    if (unsettled) {
+        console.log(`  ${c.yellow('!')} ${c.bold(wrap(t.profile.cacheTtlUnsettled(report.total.assumedWriteTtlCalls, formatUsd(-cache.deltaUsd), formatUsd(cache.worstCaseDeltaUsd)), 74, '    '))}`);
+    }
+    else if (cache.verdict === 'lost-money') {
+        console.log(`  ${c.yellow('!')} ${c.bold(wrap(t.profile.cacheLost(formatUsd(cache.deltaUsd), n(report.total.cacheWriteTokens), n(report.total.cacheReadTokens)), 74, '    '))}`);
+        // Only when it narrows the search. One label is the total again, said twice.
+        if (lostLabels.length > 0 && report.byLabel.length > 1) {
+            console.log(`    ${c.dim(wrap(t.profile.cacheLostBy(namedLosers), 74, '    '))}`);
+        }
+    }
+    else {
+        if (cache.verdict === 'paid-off') {
+            console.log(`  ${c.dim(wrap(t.profile.cachePaidOff(formatUsd(-cache.deltaUsd)), 74, '  '))}`);
+        }
+        else if (cache.verdict === 'no-difference') {
+            console.log(`  ${c.dim(wrap(t.profile.cacheNoDifference(), 74, '  '))}`);
+        }
+    }
+    /**
+     * A workload bleeding underneath a total that does not report a loss.
+     *
+     * The case the aggregate is actively hiding, so it prints as a warning: a cache
+     * paying for itself on one label and losing on another nets out to a comfortable
+     * number, and nothing else on screen would say otherwise.
+     *
+     * The sentence deliberately does not restate the total's verdict. It used to
+     * open "Caching pays off overall", which this position cannot claim — it also
+     * runs under `no-difference`, where the line immediately above has just said the
+     * opposite, and under `unsettled`, where there is no verdict to report at all.
+     */
+    if (lostLabels.length > 0 && cache.verdict !== 'lost-money') {
+        console.log(`  ${c.yellow('!')} ${c.dim(wrap(t.profile.cacheLostHidden(formatUsd(bleeding), namedLosers), 74, '    '))}`);
+    }
+    /**
+     * A label that loses money only if its unstated TTL was the long one.
+     *
+     * The same ambiguity one level down, and it hides better here: a total whose
+     * TTLs are mostly recorded reads as settled while one workload inside it is
+     * entirely unstated. Listed apart from the confirmed losers because it is a
+     * different claim — this one is conditional, and merging the two would make
+     * every name in either list mean less.
+     */
+    const maybeLostLabels = report.byLabel
+        .map((r) => ({ row: r, cache: cacheEconomics(r.breakdown) }))
+        .filter((r) => r.cache.verdict !== 'lost-money' && r.cache.worstCaseVerdict === 'lost-money');
+    if (maybeLostLabels.length > 0) {
+        console.log(`  ${c.dim(wrap(t.profile.cacheTtlUnsettledLabels(listNames(maybeLostLabels)), 74, '    '))}`);
+    }
+    /**
+     * Why, read from the prompt file itself — the loop `profile` could not close.
+     *
+     * The log carries counts, so this command can say *that* caching loses money
+     * on a label and nothing more. `labels` in the config maps a label to the
+     * prompt file it sends, and for each mapped label whose cache is failing —
+     * losing money, or never attempted while money sat in cacheable input — the
+     * file is read and the reason named: a prefix under the model's minimum,
+     * stable tokens stranded behind the first placeholder, or a healthy file
+     * whose problem is byte-identity between calls.
+     *
+     * Every sentence carries "as it is today": the file is whatever the
+     * repository holds now, which may not be what produced the log, and a fresh
+     * file presented as the history's explanation would be a figure attributed to
+     * something it does not describe.
+     */
+    const labelMap = config.labels ?? {};
+    for (const { label, model: modelId, breakdown } of report.byLabelAndModel) {
+        const file = labelMap[label];
+        if (file === undefined)
+            continue;
+        const labelCache = cacheEconomics(breakdown);
+        const failing = labelCache.verdict === 'lost-money' ||
+            (labelCache.verdict === 'not-attempted' && breakdown.inputUsd > 0);
+        if (!failing)
+            continue;
+        let text;
+        try {
+            text = await readFile(file, 'utf8');
+        }
+        catch {
+            console.log(`  ${c.dim(wrap(t.profile.labelFileMissing(label, file), 74, '    '))}`);
+            continue;
+        }
+        const model = pricing.byId.get(modelId);
+        if (!model)
+            continue;
+        const analysis = analyzeCachePrefix(text, estimateTokens);
+        const minimum = model.cacheMinTokens;
+        console.log();
+        if (minimum !== null && analysis.stablePrefixTokens < minimum) {
+            console.log(`  ${c.dim(wrap(t.profile.labelPrefixBelowMinimum(file, n(analysis.stablePrefixTokens), n(minimum), model.displayName), 74, '    '))}`);
+        }
+        else if (analysis.staticTokensAfter >= 200) {
+            console.log(`  ${c.dim(wrap(t.profile.labelPrefixMovable(file, n(analysis.staticTokensAfter), n(analysis.stablePrefixTokens)), 74, '    '))}`);
+        }
+        else {
+            console.log(`  ${c.dim(wrap(t.profile.labelPrefixHealthy(file, n(analysis.stablePrefixTokens), n(minimum ?? 0)), 74, '    '))}`);
+        }
+    }
+    /**
+     * The token budget against what actually goes up the wire.
+     *
+     * `budgets` gates a prompt *file*; the log records what the *call* carried —
+     * system prompt, retrieved context, conversation history, tool results. The
+     * two are related only through `labels`, and when the gap is large the gate
+     * is real but tiny: a 2,000-token budget on a workload sending 47,000
+     * tokens a call governs four per cent of what is sent, and nobody looking
+     * at a green build would know it.
+     *
+     * Only stated when both ends are known — a label mapped to a file, and a
+     * budget covering that file — and the share is named as approximate,
+     * because the budget counts the file's tokens with the estimator while the
+     * log counts what the provider billed. It says which part of the bill the
+     * gate can see, and never that the budget is wrong.
+     */
+    const budgetPatterns = Object.keys(config.budgets ?? {});
+    if (budgetPatterns.length > 0) {
+        for (const row of report.byLabel) {
+            const file = labelMap[row.label];
+            if (file === undefined || row.breakdown.calls === 0)
+                continue;
+            const pattern = mostSpecificMatch(budgetPatterns, file);
+            if (pattern === null)
+                continue;
+            const budget = config.budgets[pattern];
+            if (budget <= 0)
+                continue;
+            /**
+             * Input tokens per call over this label — every class that is billed
+             * as input, because a cached token was still sent and still counted
+             * against the model's window.
+             */
+            const perCall = (row.breakdown.inputTokens + row.breakdown.cacheReadTokens + row.breakdown.cacheWriteTokens) /
+                row.breakdown.calls;
+            if (perCall <= 0)
+                continue;
+            const share = budget / perCall;
+            // Only when the gap is wide enough to change what somebody believes.
+            // A budget covering most of the call is doing its job quietly.
+            if (share >= 0.5)
+                continue;
+            console.log();
+            console.log(`  ${c.yellow('!')} ${c.dim(wrap(t.profile.budgetVsWire(row.label === UNLABELLED ? t.profile.unlabelled() : row.label, file, n(budget), n(Math.round(perCall)), pct(share)), 74, '    '))}`);
+        }
+    }
+    /**
+     * Whether the TTL fits how fast the turns arrive — the mechanism behind the
+     * verdict above, readable only when the log carries a clock and a session.
+     *
+     * Rendered as four verdicts plus "could not be measured", the same
+     * three-state discipline truncation uses: a workload with cache writes and no
+     * clock has not been cleared, and silence here would read as fine.
+     */
+    const TTL_SHOWN = 3;
+    for (const fit of report.cacheTtlFit.slice(0, TTL_SHOWN)) {
+        const name = fit.label === UNLABELLED ? t.profile.unlabelled() : fit.label;
+        const gap = formatGap(fit.medianGapMs);
+        if (fit.verdict === 'expires-before-reuse') {
+            const line = fit.medianGapMs > TTL_1H_MS
+                ? t.profile.ttlFitExpiresBoth(name, fit.modelName, gap)
+                : t.profile.ttlFitExpires(name, fit.modelName, gap);
+            console.log(`  ${c.yellow('!')} ${c.bold(wrap(line, 74, '    '))}`);
+        }
+        else if (fit.verdict === 'overlong-ttl') {
+            console.log(`  ${c.yellow('!')} ${c.bold(wrap(t.profile.ttlFitOverlong(name, fit.modelName, gap, formatUsd(fit.overpayUsd)), 74, '    '))}`);
+        }
+        else if (fit.verdict === 'unsettled') {
+            console.log(`  ${c.dim(wrap(t.profile.ttlFitUnsettledGap(name, fit.modelName, gap), 74, '    '))}`);
+        }
+        else {
+            console.log(`  ${c.dim(wrap(t.profile.ttlFitFits(name, fit.modelName, gap), 74, '    '))}`);
+        }
+    }
+    if (report.total.cacheWriteTokens > 0 && report.cacheTtlFit.length === 0) {
+        console.log(`  ${c.dim(wrap(t.profile.ttlFitUnmeasured(), 74, '  '))}`);
+    }
+    /**
+     * Cache writes by conversations that never came back.
+     *
+     * Two sentences for the same tokens, and which one prints is decided by the
+     * slice's own reads: with zero cache reads anywhere in the slice, nothing
+     * read those writes — within the session, across sessions, at all — and the
+     * ceiling collapses into a fact said loudly. With reads present, another
+     * conversation sharing the prefix may have read them, the log cannot see
+     * whose write a read hit, and the figure prints as the ceiling it is.
+     */
+    const LEDGER_SHOWN = 3;
+    if (report.singleTurnCacheWrites.length > 0) {
+        const readsBySlice = new Map(report.byLabelAndModel.map((r) => [`${r.label}\n${r.model}`, r.breakdown.cacheReadTokens]));
+        for (const row of report.singleTurnCacheWrites.slice(0, LEDGER_SHOWN)) {
+            const name = row.label === UNLABELLED ? t.profile.unlabelled() : row.label;
+            const reads = readsBySlice.get(`${row.label}\n${row.model}`) ?? 0;
+            if (reads === 0) {
+                console.log(`  ${c.yellow('!')} ${c.bold(wrap(t.profile.singleTurnConfirmed(name, row.modelName, n(row.singleTurnSessions), n(row.sessions), formatUsd(row.singleTurnWriteUsd)), 74, '    '))}`);
+            }
+            else {
+                console.log(`  ${c.dim(wrap(t.profile.singleTurnCeiling(name, row.modelName, n(row.singleTurnSessions), n(row.sessions), formatUsd(row.singleTurnWriteUsd)), 74, '    '))}`);
+            }
+        }
+    }
+    /**
+     * What one conversation costs — the question a total cannot answer, and the
+     * one a per-seat price or a quota is set from. Median against p95, never a
+     * mean: one runaway agent loop would drag a mean up and hide the ordinary
+     * case, which is the figure somebody is actually pricing.
+     */
+    for (const shape of report.sessionCosts.slice(0, 3)) {
+        const name = shape.label === UNLABELLED ? t.profile.unlabelled() : shape.label;
+        console.log();
+        console.log(`  ${c.dim(wrap(t.profile.sessionCost(name, shape.modelName, n(shape.sessions), formatUsd(shape.medianUsd), n(shape.medianTurns), formatUsd(shape.p95Usd), formatUsd(shape.maxUsd)), 74, '  '))}`);
+        /**
+         * The tail, when there is one. A p95 far above the median is a shape a
+         * quota can fix; a p95 beside it is a workload that is simply expensive,
+         * and saying "hunt the tail" there would send somebody after nothing.
+         * The threshold is in the sentence rather than hidden here.
+         */
+        if (shape.medianUsd > 0 && shape.p95Usd > 10 * shape.medianUsd) {
+            console.log(`  ${c.yellow('!')} ${c.dim(wrap(t.profile.sessionCostTail((shape.p95Usd / shape.medianUsd).toFixed(0)), 74, '    '))}`);
+        }
+    }
     /**
      * A total that assumed a cache-write rate is a floor, and says so.
      *
@@ -1454,6 +2459,377 @@ async function commandProfile(args, pricing, t) {
     if (report.total.assumedWriteTtlCalls > 0) {
         console.log(`  ${c.dim(wrap(t.profile.assumedWriteTtl(report.total.assumedWriteTtlCalls), 74, '  '))}`);
     }
+    /**
+     * The section this command is for, and the answer to the fairest complaint the
+     * product has had: on a bill of twenty thousand, the rules recover two hundred.
+     *
+     * That figure is right — measured, three tokens out of three hundred and six on
+     * an ordinary support prompt. The conclusion is not that the tool is worthless
+     * but that it had been looking at the smallest line item. Which model a call
+     * goes to moves 40% to 80%. The Batch API moves 50% flat. Both are priced here
+     * from the reader's own tokens, at published rates, with no modelling in
+     * between — and printed above the breakdowns, because a lever nobody scrolls to
+     * is a lever nobody pulls.
+     *
+     * The ceiling on prompt shortening prints underneath them on purpose. A 1% win
+     * reported without saying 1% of what is not information, and this repository
+     * would rather say the uncomfortable number itself than let somebody else
+     * discover it.
+     */
+    const levers = billLevers(report, { catalogue: pricing });
+    console.log();
+    console.log(c.bold(t.profile.leversHeading()));
+    /**
+     * Every lever below describes a mixture when nothing carries a label.
+     *
+     * A 2,000-call classifier and a 400-call RAG pipeline merge into one slice, and
+     * the section then offers a single route for two workloads that need different
+     * answers — and `trazum route` would measure one prompt against a figure
+     * covering both. The session case already tells the reader to add the field;
+     * this one named the row `unlabelled` and said nothing, as though that were a
+     * workload.
+     */
+    const unlabelledOnly = report.byLabel.length === 1 && report.byLabel[0].label === UNLABELLED;
+    if (unlabelledOnly && levers.slices.length > 0) {
+        console.log(`  ${c.yellow('!')} ${c.dim(wrap(t.profile.leversUnlabelled(), 74, '    '))}`);
+    }
+    if (levers.slices.length === 0) {
+        console.log(`  ${c.dim(wrap(t.profile.leversNone(), 74, '  '))}`);
+    }
+    else {
+        for (const slice of levers.slices.slice(0, 5)) {
+            const label = slice.label === UNLABELLED ? t.profile.unlabelled() : slice.label;
+            console.log();
+            /**
+             * The headline is the **combined** figure, and the options underneath are
+             * the ways to reach it — not rows to add up. Batching a routed call
+             * discounts the cheaper model's price, so listing them separately printed
+             * $12.60 and $10.50 against a slice that had spent $21.00: a saving larger
+             * than the bill it came from, in the flattering direction.
+             */
+            console.log(`  ${c.green('→')} ${c.bold(wrap(t.profile.leverSlice(label, slice.modelName, formatUsd(slice.combinedUsd), pct(slice.shareOfBill)), 74, '    '))}`);
+            console.log(`    ${c.dim(t.profile.leverCalls(t.profile.calls(slice.calls), formatUsd(slice.spentUsd)))}`);
+            if (slice.route) {
+                console.log(`    ${c.dim('·')} ${c.dim(wrap(t.profile.leverRoute(slice.route.candidate.displayName, formatUsd(slice.route.savingUsd)), 74, '      '))}`);
+            }
+            if (slice.batch) {
+                console.log(`    ${c.dim('·')} ${c.dim(wrap(t.profile.leverBatch(formatUsd(slice.batch.savingUsd)), 74, '      '))}`);
+            }
+            // The arithmetic is exact and the quality question is untouched by it.
+            // Naming the command is the difference between a saving and a gamble.
+            if (slice.route) {
+                console.log(`    ${c.dim(wrap(t.profile.leverRouteVerify(slice.route.candidate.id), 74, '    '))}`);
+            }
+        }
+    }
+    console.log();
+    console.log(`  ${c.dim(wrap(t.profile.leverPromptCeiling(formatUsd(levers.promptCeilingUsd), pct(levers.promptCeilingShare)), 74, '  '))}`);
+    /**
+     * `--what-if <model>`: these exact calls, at another model's rates.
+     *
+     * The levers above pick their own candidate; this answers the question the
+     * reader arrived with. It is multiplication, not advice, and every part of
+     * this section is built so it cannot be read as advice:
+     *
+     * - the caveat line prints **before** the figure, not after it;
+     * - calls the target's context window could not have accepted are named as
+     *   impossible rather than priced as cheap, and their money is in none of
+     *   the totals;
+     * - spend already on the target is stated separately, because a difference
+     *   computed over money that cannot move is a percentage of the wrong
+     *   denominator.
+     */
+    if (whatIf !== null) {
+        console.log();
+        console.log(c.bold(t.profile.whatIfHeading(whatIf.target.displayName)));
+        console.log(`  ${c.dim(wrap(t.profile.whatIfAssumption(), 74, '  '))}`);
+        console.log();
+        if (whatIf.slices.length === 0) {
+            console.log(`  ${c.dim(wrap(t.profile.whatIfNothingToMove(), 74, '  '))}`);
+        }
+        else {
+            const cheaper = whatIf.deltaUsd < 0;
+            const line = t.profile.whatIfTotal(formatUsd(whatIf.currentUsd), formatUsd(whatIf.targetUsd), formatUsd(Math.abs(whatIf.deltaUsd)));
+            console.log(`  ${cheaper ? c.green('→') : c.yellow('!')} ${c.bold(wrap(line, 74, '    '))}`);
+            console.log(`  ${c.dim(wrap(cheaper ? t.profile.whatIfCheaper() : t.profile.whatIfDearer(), 74, '  '))}`);
+            for (const slice of whatIf.slices.slice(0, 5)) {
+                const label = slice.label === UNLABELLED ? t.profile.unlabelled() : slice.label;
+                console.log(`    ${c.dim('·')} ${c.dim(wrap(t.profile.whatIfSlice(label, slice.model, formatUsd(slice.currentUsd), formatUsd(slice.targetUsd)), 74, '      '))}`);
+            }
+        }
+        /**
+         * The refusal, and it is loud. A call larger than the target's window is
+         * not a cheaper call, and a comparison that priced it anyway would report
+         * a saving for traffic that would have failed outright.
+         */
+        for (const slice of whatIf.overContext.slice(0, 3)) {
+            const label = slice.label === UNLABELLED ? t.profile.unlabelled() : slice.label;
+            console.log(`  ${c.yellow('!')} ${c.bold(wrap(t.profile.whatIfOverContext(label, n(slice.maxCallInputTokens), n(whatIf.target.contextWindow), formatUsd(slice.currentUsd)), 74, '    '))}`);
+        }
+        // Money that is already there cannot move, and leaving it out of the
+        // totals above is only honest if the reader is told it exists.
+        if (whatIf.alreadyOnTarget.calls > 0) {
+            console.log(`  ${c.dim(wrap(t.profile.whatIfAlreadyThere(t.profile.calls(whatIf.alreadyOnTarget.calls), formatUsd(whatIf.alreadyOnTarget.usd)), 74, '  '))}`);
+        }
+        // Models with no current price have no difference to state — their target
+        // cost is knowable and the subtraction is not.
+        if (whatIf.unpricedCalls > 0) {
+            console.log(`  ${c.dim(wrap(t.profile.whatIfUnpriced(t.profile.calls(whatIf.unpricedCalls), whatIf.unpricedModels.join(', ')), 74, '  '))}`);
+        }
+    }
+    /**
+     * What re-sending the conversation costs — the line nothing here could see.
+     *
+     * A chat or agent workload sends the whole conversation back on every turn, so
+     * the input grows with the turn count and that growth is routinely the largest
+     * item on the bill. A prompt file shows the system prompt and not the history; a
+     * total shows the sum and not the shape.
+     *
+     * Reported as a **ceiling**, because part of the growth is the user's own new
+     * messages and this reads counts rather than content, so it cannot separate the
+     * two. Saying nothing because the exact split is unknowable would be worse: the
+     * bound is exact, and the reader can act on it.
+     */
+    if (report.conversations.length > 0) {
+        console.log();
+        console.log(c.bold(t.profile.historyHeading()));
+        for (const growth of report.conversations.slice(0, 3)) {
+            const label = growth.label === UNLABELLED ? t.profile.unlabelled() : growth.label;
+            console.log();
+            console.log(`  ${c.bold(wrap(t.profile.historyGrowth(label, growth.modelName, n(Math.round(growth.minTurnTokens)), n(Math.round(growth.maxTurnTokens)), n(growth.longestSession)), 74, '  '))}`);
+            console.log(`  ${c.dim(wrap(t.profile.historyCeiling(formatUsd(growth.growthUsd), pct(growth.shareOfBill), formatUsd(growth.flatUsd), formatUsd(growth.inputUsd)), 74, '  '))}`);
+        }
+    }
+    else if (!report.hasSessions) {
+        /**
+         * Not the same as "no growth". A log without a session field cannot be asked
+         * the question at all, and silence there would read as a clean bill of health
+         * on the line most likely to be the biggest.
+         */
+        console.log();
+        console.log(c.bold(t.profile.historyHeading()));
+        console.log(`  ${c.dim(wrap(t.profile.historyNoSessions(), 74, '  '))}`);
+    }
+    /**
+     * Where the output spend concentrates — the actionable half of "output
+     * dominates", which the headline above could only state as a total.
+     *
+     * Two bills with identical output spend want opposite responses. Six per cent
+     * of calls holding half of it is a tail, and a tail has a cause worth a
+     * morning; forty-five per cent is what evenly spread looks like, and the only
+     * lever there is asking every answer to be shorter. The threshold between the
+     * two is a quarter of the calls — far enough from both shapes that rounding
+     * cannot flip the message, and stated here because it is a presentation choice,
+     * not a measurement.
+     */
+    if (report.outputShapes.length > 0) {
+        console.log();
+        console.log(c.bold(t.profile.outputShapeHeading()));
+        for (const shape of report.outputShapes.slice(0, 3)) {
+            const label = shape.label === UNLABELLED ? t.profile.unlabelled() : shape.label;
+            const isTail = shape.heavyCallShare < 0.25;
+            console.log();
+            if (isTail) {
+                console.log(`  ${c.bold(wrap(t.profile.outputTail(label, shape.modelName, pct(shape.heavyCallShare), pct(shape.heavySpendShare), n(shape.aboveTokens), formatUsd(shape.outputUsd)), 74, '  '))}`);
+                console.log(`  ${c.dim(wrap(t.profile.outputTailAdvice(), 74, '  '))}`);
+            }
+            else {
+                console.log(`  ${c.bold(wrap(t.profile.outputFlat(label, shape.modelName, pct(shape.heavyCallShare), pct(shape.heavySpendShare), formatUsd(shape.outputUsd)), 74, '  '))}`);
+                console.log(`  ${c.dim(wrap(t.profile.outputFlatAdvice(), 74, '  '))}`);
+            }
+            /**
+             * The ceilings a max_tokens cap actually wants, exact over the
+             * histogram: every measured answer at or under the named number is
+             * counted, none interpolated. Omitted when the covering bucket is the
+             * open-ended last one, which has no ceiling to name honestly.
+             */
+            if (shape.medianWithinTokens !== null && shape.p95WithinTokens !== null) {
+                console.log(`  ${c.dim(wrap(t.profile.outputPercentiles(n(shape.medianWithinTokens), n(shape.p95WithinTokens)), 74, '  '))}`);
+            }
+        }
+    }
+    /**
+     * How big the calls themselves are — the other half of the bill.
+     *
+     * The section above describes output; on a RAG or agent workload input is
+     * most of the invoice, and a total could only ever say "input is 63% of
+     * this bill", which nobody can act on. The actionable question is whether
+     * the ordinary call is large or a few calls are enormous, and those two
+     * shapes want opposite responses: a cap on something, or a shorter prompt.
+     *
+     * Loud past **four times** the median — far enough from an even
+     * distribution that a bucket boundary cannot flip the message, and stated
+     * in the sentence rather than hidden here. Both figures are bucket
+     * ceilings, so the ratio is coarse by construction and the copy says so.
+     */
+    if (report.inputShapes.length > 0) {
+        console.log();
+        console.log(c.bold(t.profile.inputShapeHeading()));
+        for (const shape of report.inputShapes.slice(0, 3)) {
+            const label = shape.label === UNLABELLED ? t.profile.unlabelled() : shape.label;
+            console.log();
+            if (shape.medianWithinTokens === null || shape.p95WithinTokens === null || shape.p95OverMedian === null) {
+                /**
+                 * The covering bucket is the open-ended last one, so there is no
+                 * ceiling to name. Said rather than skipped: a slice whose calls are
+                 * all above a million tokens is a finding, and silence would drop it.
+                 */
+                console.log(`  ${c.bold(wrap(t.profile.inputHuge(label, shape.modelName, t.profile.calls(shape.calls), formatUsd(shape.inputUsd)), 74, '  '))}`);
+                continue;
+            }
+            const skewed = shape.p95OverMedian >= 4;
+            const line = skewed
+                ? t.profile.inputSkewed(label, shape.modelName, n(shape.medianWithinTokens), n(shape.p95WithinTokens), shape.p95OverMedian.toFixed(1), formatUsd(shape.inputUsd))
+                : t.profile.inputEven(label, shape.modelName, n(shape.medianWithinTokens), n(shape.p95WithinTokens), formatUsd(shape.inputUsd));
+            console.log(`  ${c.bold(wrap(line, 74, '  '))}`);
+            console.log(`  ${c.dim(wrap(skewed ? t.profile.inputSkewedAdvice() : t.profile.inputEvenAdvice(), 74, '  '))}`);
+            /**
+             * What that size actually costs. A cache read is a tenth of input on
+             * Anthropic, so a large slice reading almost everything from cache is a
+             * very different bill from one paying full rate — and the token counts
+             * alone cannot tell them apart.
+             */
+            if (shape.cachedShare >= 0.5) {
+                console.log(`  ${c.dim(wrap(t.profile.inputMostlyCached(pct(shape.cachedShare)), 74, '  '))}`);
+            }
+            else if (shape.cachedShare < 0.1) {
+                console.log(`  ${c.dim(wrap(t.profile.inputFullRate(), 74, '  '))}`);
+            }
+        }
+    }
+    /**
+     * The same request, sent again a moment later.
+     *
+     * A conversation's input grows with every turn, so two consecutive calls in
+     * one conversation carrying the same size seconds apart is a thing going
+     * wrong rather than a thing working — a retry after a timeout, an agent
+     * step repeating, a loop. Loud, because the money bought nothing, and
+     * hedged, because this reads counts and cannot see content: the sentence
+     * says the pattern is *usually* a retry, never that it is one.
+     */
+    if (report.repeatedTurns.length > 0) {
+        console.log();
+        console.log(c.bold(t.profile.repeatsHeading()));
+        for (const row of report.repeatedTurns.slice(0, 3)) {
+            const label = row.label === UNLABELLED ? t.profile.unlabelled() : row.label;
+            console.log();
+            console.log(`  ${c.yellow('!')} ${c.bold(wrap(t.profile.repeatsFound(label, row.modelName, n(row.repeats), n(row.checkedCalls), n(Math.round(row.withinMs / 1000)), formatUsd(row.usd)), 74, '    '))}`);
+            console.log(`  ${c.dim(wrap(t.profile.repeatsAdvice(), 74, '  '))}`);
+        }
+    }
+    /**
+     * Output spend that bought answers cut off mid-generation — the one slice of
+     * a bill that is waste without a counterpart. Paid in full, frequently
+     * retried and billed again, and the truncated attempt bought nothing.
+     *
+     * Three states, kept apart on purpose: waste found, none found on a log that
+     * measured, and a log that never recorded a stop reason at all — which gets
+     * the missing-field message, because silence there would read as a clean bill
+     * of health on a question the log never asked.
+     */
+    if (report.total.truncatedCalls > 0 && report.total.outputUsd > 0) {
+        console.log();
+        console.log(`  ${c.yellow('!')} ${c.bold(wrap(t.profile.truncatedWaste(t.profile.calls(report.total.truncatedCalls), formatUsd(report.total.truncatedOutputUsd), pct(report.total.truncatedOutputUsd / report.total.outputUsd)), 74, '    '))}`);
+        /**
+         * Which workloads are paying for it, and at what rate — the actionable
+         * half the total hides. A 40% truncation rate is a max_tokens setting
+         * that is simply wrong; 1% is a long tail, and the two call for opposite
+         * responses.
+         *
+         * The rate is over calls that **recorded a stop reason**, never over all
+         * calls: a workload that logs the field on half its traffic must not be
+         * reported as though the unmeasured half completed. Both numbers print,
+         * so the denominator is visible rather than implied.
+         */
+        const truncatedLabels = report.byLabel
+            .filter((row) => row.breakdown.truncatedCalls > 0)
+            .sort((a, b) => b.breakdown.truncatedOutputUsd - a.breakdown.truncatedOutputUsd);
+        if (truncatedLabels.length > 0 && report.byLabel.length > 1) {
+            for (const row of truncatedLabels.slice(0, 3)) {
+                const name = row.label === UNLABELLED ? t.profile.unlabelled() : row.label;
+                console.log(`    ${c.dim(wrap(t.profile.truncatedBy(name, n(row.breakdown.truncatedCalls), n(row.breakdown.stopReasonCalls), pct(row.breakdown.truncatedCalls / row.breakdown.stopReasonCalls), formatUsd(row.breakdown.truncatedOutputUsd)), 74, '    '))}`);
+            }
+        }
+        /**
+         * The ceiling the completed answers actually needed, when the output
+         * shapes measured it: "95% of the answers that finished fit within N
+         * tokens" is the number a max_tokens cap wants, and it sits next to the
+         * evidence that the current cap is too low. Measured on these calls,
+         * promised for nothing.
+         */
+        const ceiling = report.outputShapes.find((shape) => shape.p95WithinTokens !== null);
+        if (ceiling !== undefined) {
+            console.log(`    ${c.dim(wrap(t.profile.truncatedCeiling(n(ceiling.p95WithinTokens)), 74, '    '))}`);
+        }
+    }
+    else if (report.total.stopReasonCalls === 0) {
+        console.log();
+        console.log(`  ${c.dim(wrap(t.profile.truncatedNotRecorded(), 74, '  '))}`);
+    }
+    /**
+     * This bill against the previous one — how spend actually gets out of hand.
+     *
+     * Nobody adds five thousand a month in one day; bills grow four percent a week
+     * while every snapshot looks reasonable. This is the baseline gate the prompts
+     * already had, applied to the money itself. **Positive means the bill grew**
+     * (the diff convention), and every figure is between exactly these two files:
+     * no period is assumed, so the call counts print beside the money for the
+     * reader to judge comparability before judging the trend.
+     */
+    if (previous !== null) {
+        console.log();
+        console.log(c.bold(t.profile.againstHeading()));
+        if (previous.total.calls === 0) {
+            console.log(`  ${c.dim(wrap(t.profile.againstNothingPriced(), 74, '  '))}`);
+        }
+        else {
+            const delta = report.total.totalUsd - previous.total.totalUsd;
+            const growthPct = previous.total.totalUsd > 0
+                ? `${delta >= 0 ? '+' : ''}${((delta / previous.total.totalUsd) * 100).toFixed(1)}%`
+                : '—';
+            console.log(`  ${c.bold(wrap(t.profile.againstTotals(formatUsd(previous.total.totalUsd), formatUsd(report.total.totalUsd), formatSignedUsd(delta), growthPct, t.profile.calls(previous.total.calls), t.profile.calls(report.total.calls)), 74, '  '))}`);
+            // Overlapping spans mean part of this "growth" is the same money on
+            // both sides of the subtraction. Said after the figure it qualifies
+            // and before the drivers built from it.
+            if (againstOverlap !== null) {
+                console.log(`  ${c.yellow('!')} ${c.dim(wrap(t.profile.againstOverlap(dayOf(againstOverlap.fromMs), dayOf(againstOverlap.toMs)), 74, '    '))}`);
+            }
+            // Drivers: per-key contribution to the change, largest magnitude first,
+            // computed once beside the gates so no rendering derives its own.
+            const driverLine = (d, shown) => d.was === null
+                ? t.profile.againstDriverNew(formatSignedUsd(d.delta), shown)
+                : d.now === null
+                    ? t.profile.againstDriverGone(formatSignedUsd(d.delta), shown)
+                    : t.profile.againstDriver(formatSignedUsd(d.delta), shown, formatUsd(d.was), formatUsd(d.now));
+            console.log();
+            for (const d of labelDrivers.slice(0, 5)) {
+                const line = driverLine(d, d.key === UNLABELLED ? t.profile.unlabelled() : d.key);
+                console.log(`  ${d.delta > 0 ? c.yellow(line) : c.dim(line)}`);
+            }
+            if (labelDrivers.length > 5) {
+                console.log(`  ${c.dim(t.profile.andMoreLabels(labelDrivers.length - 5))}`);
+            }
+            /**
+             * The same change, by model — where the mix moved. The label rows cannot
+             * show it: a workload that kept its name and switched from Haiku to Opus
+             * reads as "chat grew", and the reason is the model. Only printed when
+             * more than one model is involved; with one model on both sides, this
+             * section restates the totals line and says nothing new.
+             */
+            const modelsInvolved = new Set([
+                ...previous.byModel.map((r) => r.model),
+                ...report.byModel.map((r) => r.model),
+            ]);
+            if (modelDrivers.length > 0 && modelsInvolved.size > 1) {
+                console.log();
+                console.log(`  ${c.dim(t.profile.againstByModel())}`);
+                for (const d of modelDrivers.slice(0, 3)) {
+                    const line = driverLine(d, d.key);
+                    console.log(`  ${d.delta > 0 ? c.yellow(line) : c.dim(line)}`);
+                }
+            }
+        }
+    }
     for (const [heading, rows] of [
         [t.profile.byLabelHeading(), report.byLabel.map((r) => [r.label === UNLABELLED ? t.profile.unlabelled() : r.label, r.breakdown])],
         [t.profile.byModelHeading(), report.byModel.map((r) => [r.model, r.breakdown])],
@@ -1464,10 +2840,51 @@ async function commandProfile(args, pricing, t) {
         console.log(c.bold(heading));
         for (const [name, breakdown] of rows) {
             const share = report.total.totalUsd > 0 ? breakdown.totalUsd / report.total.totalUsd : 0;
-            console.log(`  ${t.profile.row(name, formatUsd(breakdown.totalUsd), pct(share), n(breakdown.calls))}`);
+            console.log(`  ${t.profile.row(name, formatUsd(breakdown.totalUsd), pct(share), t.profile.calls(breakdown.calls))}`);
+        }
+    }
+    /**
+     * What this log cannot answer, and what would fix it.
+     *
+     * Every finding past the totals needs a field the format does not require,
+     * and a reader who never adds them sees a report quietly missing half of
+     * itself — with no way to tell "nothing to report" from "nothing recorded".
+     * Named with counts rather than booleans: twelve labelled records out of
+     * forty thousand is not a labelled log, and a boolean would call it one.
+     *
+     * Only fields that are actually missing are listed. A complete log gets no
+     * section at all, because a paragraph of things that are fine is the
+     * paragraph readers learn to skip.
+     */
+    const coverage = report.fieldCoverage;
+    if (coverage.parsed > 0) {
+        const missing = [];
+        const partial = (seen) => `${n(seen)}/${n(coverage.parsed)}`;
+        if (coverage.label < coverage.parsed) {
+            missing.push(t.profile.needsLabel(partial(coverage.label)));
+        }
+        if (coverage.session < coverage.parsed) {
+            missing.push(t.profile.needsSession(partial(coverage.session)));
+        }
+        if (coverage.ts < coverage.parsed) {
+            missing.push(t.profile.needsTs(partial(coverage.ts)));
+        }
+        if (coverage.stopReason < coverage.parsed) {
+            missing.push(t.profile.needsStopReason(partial(coverage.stopReason)));
+        }
+        if (coverage.cacheWrites > 0 && coverage.cacheTtl < coverage.cacheWrites) {
+            missing.push(t.profile.needsCacheTtl(`${n(coverage.cacheTtl)}/${n(coverage.cacheWrites)}`));
+        }
+        if (missing.length > 0) {
+            console.log();
+            console.log(c.bold(t.profile.coverageHeading()));
+            for (const line of missing)
+                console.log(`  ${c.dim(wrap(line, 74, '  '))}`);
         }
     }
-    reportProfileGaps(report, t, n);
+    reportProfileGaps(report, t, n, pricingStale);
+    await writeSideFiles();
+    applyGates();
 }
 /**
  * What the profile could not account for, said out loud.
@@ -1476,7 +2893,17 @@ async function commandProfile(args, pricing, t) {
  * silently omits calls is wrong in the flattering direction, which is the fault
  * this repository keeps finding in itself.
  */
-function reportProfileGaps(report, t, n) {
+function reportProfileGaps(report, t, n, stalePricing = null) {
+    /**
+     * The one fact that silently invalidates every dollar above: a price table
+     * the provider may have re-priced since. Loud, because unlike a skipped
+     * line it does not name its own size — the error is exactly whatever the
+     * provider changed, and only refreshing the table can say.
+     */
+    if (stalePricing !== null) {
+        console.log();
+        console.log(`  ${c.yellow('!')} ${c.dim(wrap(t.profile.pricesStale(stalePricing.date, stalePricing.days), 74, '    '))}`);
+    }
     if (report.unpricedModels.length > 0) {
         console.log();
         console.log(`  ${c.yellow('!')} ${c.dim(wrap(t.profile.unpriced(report.unpricedModels.join(', '), report.unpriced.calls), 74, '    '))}`);
@@ -1486,6 +2913,138 @@ function reportProfileGaps(report, t, n) {
         console.log(`  ${c.dim(t.profile.skipped(report.skippedLines.length, report.skippedLines.length > 5 ? `${shown}…` : shown))}`);
     }
 }
+/**
+ * `trazum route <log> --prompt-file <p> --cases <c>` — the loop the levers could
+ * only point at.
+ *
+ * `profile` prices a route exactly and can say nothing whatever about whether the
+ * cheaper model still does the job. So it printed a figure and a homework
+ * assignment, and homework does not get done — the report said "$16.80 available,
+ * go and test it" and the reader closed the terminal.
+ *
+ * This runs the test. Same prompt, two models, judged against **the expensive
+ * model's own run-to-run variance** measured on the same cases in the same run. No
+ * threshold anybody picked: the question is whether the cheaper model agrees with
+ * the original more closely than the original agrees with itself.
+ *
+ * It costs three provider calls per case and says so before spending one of them,
+ * exactly as `prune` does. A command that can spend somebody's money without
+ * telling them first is a command they stop trusting.
+ */
+async function commandRoute(args, pricing, t) {
+    const path = args.positional[0];
+    if (path === undefined) {
+        console.log();
+        console.log(c.dim(wrap(t.route.noTarget(), 74, '  ')));
+        console.log();
+        return;
+    }
+    const promptPath = stringFlag(args, 'prompt-file');
+    const casesPath = stringFlag(args, 'cases');
+    if (!promptPath || !casesPath)
+        throw new Error(t.route.needsPrompt());
+    const report = profileUsage(await readFile(path, 'utf8'), { catalogue: pricing });
+    const levers = billLevers(report, { catalogue: pricing });
+    const wanted = stringFlag(args, 'label');
+    /**
+     * A `--label` nothing carries is a typo, and it gets the typo answer.
+     *
+     * Falling through to the generic "no route clears 1% of the bill: these calls
+     * are already on the cheapest model of their family" asserted two falsehoods
+     * at once when the log had a 60% route under a different name — a verdict
+     * about calls the flag never selected.
+     */
+    if (wanted !== undefined && !report.byLabel.some((r) => r.label === wanted)) {
+        const available = report.byLabel
+            .map((r) => (r.label === UNLABELLED ? t.profile.unlabelled() : r.label))
+            .join(', ');
+        console.log();
+        console.log(c.dim(wrap(t.route.labelNotFound(wanted, available), 74, '  ')));
+        console.log();
+        return;
+    }
+    const slice = levers.slices.find((s) => s.route !== null && (wanted === undefined || s.label === wanted));
+    if (!slice?.route) {
+        console.log();
+        console.log(c.dim(wrap(t.route.noRoute(), 74, '  ')));
+        console.log();
+        return;
+    }
+    const prompt = await readFile(promptPath, 'utf8');
+    const inputs = parseCases(await readFile(casesPath, 'utf8'));
+    if (inputs.length === 0)
+        throw new Error(t.errors.evalNoCases(casesPath));
+    const provider = providerFromEnv();
+    if (!provider)
+        throw new Error(t.errors.llmNotConfigured());
+    /**
+     * The candidate on the same endpoint and key, with the model swapped. Built
+     * through the same factory rather than by hand so a provider that needs more
+     * than a model id — a Bedrock region, a Vertex project — keeps whatever the
+     * environment already gave it.
+     */
+    const candidate = providerFromEnv({
+        ...process.env,
+        TRAZUM_LLM_MODEL: slice.route.candidate.id,
+    });
+    if (!candidate)
+        throw new Error(t.errors.llmNotConfigured());
+    const label = slice.label === UNLABELLED ? t.profile.unlabelled() : slice.label;
+    const worth = formatUsd(slice.route.savingUsd);
+    console.log();
+    console.log(`  ${c.bold(t.route.picked(label, slice.modelName, slice.route.candidate.displayName, worth, `${(slice.shareOfBill * 100).toFixed(1)}%`))}`);
+    /**
+     * The money and the measurement have to describe the same calls.
+     *
+     * An unlabelled slice can hold a classifier and a RAG pipeline at once, and
+     * this measures exactly one prompt. Attributing the verdict to a figure that
+     * covers both is the fault this repository keeps finding in itself — a number
+     * describing something other than what was measured. It cannot be detected from
+     * counts, so it is stated rather than guessed at.
+     */
+    if (slice.label === UNLABELLED) {
+        console.log(`  ${c.yellow('!')} ${c.dim(wrap(t.route.unlabelledSlice(), 74, '    '))}`);
+    }
+    console.log();
+    console.log(`  ${c.dim(wrap(t.route.willSpend(inputs.length * 3, provider.model, candidate.model), 74, '  '))}`);
+    if (!boolFlag(args, 'yes')) {
+        console.log(`  ${c.dim(t.route.dryRun())}`);
+        console.log();
+        return;
+    }
+    console.log(`  ${c.dim(t.route.running(inputs.length))}`);
+    // Same prompt on both sides. The axis under test is the model, and passing the
+    // prompt twice is what says so at the call site.
+    const result = await evaluate(prompt, prompt, inputs, provider, {
+        candidateProvider: candidate,
+        concurrency: numberFlag(args, 'concurrency', 3, t),
+    });
+    if (boolFlag(args, 'json')) {
+        console.log(JSON.stringify({ slice, evaluation: result }, null, 2));
+        return;
+    }
+    const asPct = (v) => `${(v * 100).toFixed(0)}%`;
+    console.log();
+    console.log(`  ${c.dim(wrap(t.route.agreement(asPct(result.crossAgreement), asPct(result.selfAgreement)), 74, '  '))}`);
+    console.log();
+    if (result.verdict === 'inconclusive') {
+        console.log(`  ${c.bold(wrap(t.route.inconclusive(), 74, '  '))}`);
+    }
+    else if (result.verdict === 'diverges') {
+        console.log(`  ${c.yellow('!')} ${c.bold(wrap(t.route.diverges(worth), 74, '    '))}`);
+    }
+    else {
+        console.log(`  ${c.green('✓')} ${c.bold(wrap(t.route.holds(worth), 74, '    '))}`);
+    }
+    /**
+     * Printed on every verdict including the good one. Agreement is not
+     * correctness: this measures whether the answers moved, not whether they were
+     * ever right, and a green tick that let somebody forget that would be the tool
+     * overstating what it knows.
+     */
+    console.log(`  ${c.dim(wrap(t.route.yours(), 74, '  '))}`);
+    console.log();
+}
 /**
  * `trazum baseline <dir>` — record what the estate costs now.
  *
@@ -2584,7 +4143,10 @@ async function main() {
             await commandBaseline(args, config, pricing, t, locale);
             break;
         case 'profile':
-            await commandProfile(args, pricing, t);
+            await commandProfile(args, config, pricing, t);
+            break;
+        case 'route':
+            await commandRoute(args, pricing, t);
             break;
         case 'eval':
             await commandEval(args, config, t, locale);