mcp-context-cost 0.3.0 → 0.4.0

package/README.md

@@ -3,37 +3,12 @@
 [![npm](https://img.shields.io/npm/v/mcp-context-cost)](https://www.npmjs.com/package/mcp-context-cost)
 [![CI](https://github.com/athakur3/mcp-context-cost/actions/workflows/ci.yml/badge.svg)](https://github.com/athakur3/mcp-context-cost/actions/workflows/ci.yml)
 
-**Reproducible context-cost measurement for MCP servers — for the one you publish, and for
-the stack you actually run.**
+**What do the MCP servers in your config cost you before you type anything — and what did
+that last config change add to every session you will ever run?**
 
-Every MCP server you wire into an agent injects its tool schemas into the model's context
-before any work happens. That cost is invisible — and it varies by **1,700×** across
-popular servers:
-
-| server | context cost | tools |
-|---|---:|---:|
-| github (official) | **54,422 tokens** | 44 |
-| brave-search | 25,456 | 8 |
-| notion | 17,500 | 24 |
-| playwright *(4.8M installs/week)* | 4,024 | 24 |
-| filesystem (reference) | 2,823 | 14 |
-| markitdown | 64 | 1 |
-
-*(57 of 82 popular servers measured, 2026-08-16 sweep — full table in
-[results/leaderboard.md](results/leaderboard.md); every failure is listed with its reason.
-Each measured server also has a [detail page](https://athakur3.github.io/mcp-context-cost/servers/)
-showing which tools its tokens are in.)*
-
-This project makes that cost **legible and disputable**:
-
-```
-[context cost | 12,430 tokens]   ← shields.io badge, linked to the methodology
-```
-
-## What does *your* setup cost?
-
-The leaderboard measures one server at a time. You don't run one server — you run a stack.
-Point `audit` at your own MCP config and it measures every server you actually have installed:
+Every MCP server you wire into an agent injects its tool schemas into the model's context on
+every single request. You pay that whether or not the agent ends up using the tools, and no
+client shows you the number. Point `audit` at your own MCP config:
 
 ```bash
 npx -y mcp-context-cost audit
@@ -55,6 +30,10 @@ claude-desktop  ~/Library/Application Support/Claude/claude_desktop_config.json
   heaviest tools
     sequential-thinking · sequentialthinking      990
     memory · search_nodes                         323
+
+  trim: disabling 3 tools (sequential-thinking·sequentialthinking, memory·search_nodes,
+  memory·open_nodes) would recover 1,635 tokens (20.7% of this config) — if your client
+  supports per-tool filtering.
 ```
 
 It finds configs for Claude Desktop, Claude Code (`~/.claude.json`, `.mcp.json`), Cursor,
@@ -67,6 +46,12 @@ Totals are reported per config file, never merged: a context window belongs to o
 session, so summing Cursor's servers into Claude Desktop's total would describe a session
 nobody runs.
 
+One nuance: Claude Code's tool search (default-on in recent versions) defers full MCP
+schemas until used, loading only tool names at session start. Audit totals are the weight
+of the schema surface itself — what loads upfront in clients without deferral (Claude
+Desktop, Cursor, VS Code, Windsurf today), and what Claude Code's documented fallback
+modes still load. Deferral-aware reporting is on the roadmap.
+
 **In CI**, make it a gate — the bundlesize move for agents:
 
 ```bash
@@ -74,8 +59,107 @@ npx -y mcp-context-cost audit --config .mcp.json --budget 20000
 # exits 1 when the stack exceeds the budget, so a PR adding a 25K-token server fails
 ```
 
-Flags: `--json` (full report on stdout, progress on stderr), `--budget N`, `--context N`
-(default 200,000), `--timeout ms`, `--concurrency N`, `--docker`.
+The budget is an absolute ceiling. What a reviewer actually wants to know is what *this pull
+request* did, so record a baseline and diff against it:
+
+```bash
+npx -y mcp-context-cost audit --config .mcp.json --json > baseline.json          # on main
+npx -y mcp-context-cost audit --config .mcp.json --baseline baseline.json --max-increase 2000
+```
+
+```
+diff vs baseline measured 2026-08-18T01:51:49.555Z (methodology 1.0)
+
+  .mcp.json
+    2,378  →  5,201   +2,823
+
+    added             filesystem          — →     2,823  +2,823
+    (1 server unchanged)
+
+    This change adds 2,823 tokens to every request in this client — 1.2% → 2.6% of a
+    200,000-token context window.
+
+INCREASE FAIL:
+  .mcp.json: +2,823 tokens per request, over the 2,000 allowed
+```
+
+> **Version note.** `--baseline` and `--max-increase` are **not in the published 0.3.0** —
+> they are on `main` and ship in the next release. This matters more than a normal
+> unreleased-feature note: 0.3.0 ignores flags it does not recognise, so running the command
+> above against it produces a plain audit and **exit 0** — a passing CI check on a gate that
+> never ran. Builds after 0.3.0 reject unknown flags with exit 2 instead. Until the next
+> release, pin the gate to a version that has it, or it is not gating anything.
+
+A baseline is just a stored `audit --json` report, so any artifact store works. Without
+`--max-increase` the diff is informational and the exit code is unchanged.
+
+[`examples/github-actions.yml`](examples/github-actions.yml) is the whole thing as a workflow:
+measure the base branch, measure the PR, fail on the difference.
+
+`--max-increase` fails on more than the number — it also fails whenever the increase could
+not be established. A server that measured yesterday and won't start today takes its tokens
+out of the total in exactly the way uninstalling it would, and reporting that as a saving is
+the one mistake this tool must not make. So a server that crossed the measured/unmeasured
+line, a config with no baseline, or a baseline config this run never found each fail the
+gate and name themselves:
+
+```
+    Not a clean comparison: a server changed measured-ness between the two runs.
+    The measured total moved −2,378, but that is not what your config did.
+
+      memory: measured 2,378 in the baseline and could not be measured now — its cost is
+              missing from the total, not gone from your config
+      → true cost is at least 2,378 higher than the 0 measured now.
+
+INCREASE FAIL:
+  .mcp.json: a server changed measured-ness, so the change could not be established exactly
+```
+
+Add `--claude` to annotate each server with its Anthropic-request cost from the published
+[Claude divergence](docs/METHODOLOGY.md#claude-divergence) run — an exact number when the
+published capture hash matches what you have installed, `—` (silence, not a stale guess)
+when it doesn't (today the run covers the top 15 measured servers, so most installs will
+show a mix):
+
+```
+  server               tools  tokens   share   claude
+  github                  44  54,422   95.8%   18,406
+  memory                   9   2,378    4.2%       —
+```
+
+Flags: `--json` (full report on stdout, progress on stderr), `--budget N`,
+`--baseline <report.json>`, `--max-increase N`, `--context N` (default 200,000),
+`--timeout ms`, `--concurrency N`, `--docker`, `--claude`.
+
+## Where the numbers come from
+
+The number `audit` gives you is the same measurement, run across a curated set of public
+servers — which is how you can tell it is a measurement and not this tool's opinion. It also
+shows what you are choosing between: across the 65 servers measured, cost spans **1,700×**,
+from the 32-token `postgres` reference server to github's 54,422. The table below starts at
+markitdown's 64 tokens, an 850× spread; the full range is in
+[results/leaderboard.md](results/leaderboard.md).
+
+| server | context cost | tools |
+|---|---:|---:|
+| github (official) | **54,422 tokens** | 44 |
+| brave-search | 25,456 | 8 |
+| notion | 17,500 | 24 |
+| playwright *(4.8M installs/week)* | 4,024 | 24 |
+| filesystem (reference) | 2,823 | 14 |
+| markitdown | 64 | 1 |
+
+*(65 of 82 popular servers measured, 2026-08-18 sweep — full table in
+[results/leaderboard.md](results/leaderboard.md); every failure is listed with its reason.
+Each measured server also has a [detail page](https://athakur3.github.io/mcp-context-cost/servers/)
+showing which tools its tokens are in.)*
+
+If you publish a server, the same measurement is available as a badge, so your users can see
+the cost before they install rather than after:
+
+```
+[context cost | 12,430 tokens]   ← shields.io badge, linked to the methodology
+```
 
 ## What it costs on Claude
 
@@ -94,9 +178,9 @@ the method is [Claude divergence](docs/METHODOLOGY.md#claude-divergence).
 
 ## Why trust the number?
 
-Every badge is backed by a `measurement.json` containing the raw `tools/list` capture, the
-SHA-256 of its canonical bytes, the pinned tokenizer (`o200k_base`), and the exact launch
-command. Disputes reduce to a byte-level diff:
+Every published number is backed by a `measurement.json` containing the raw `tools/list`
+capture, the SHA-256 of its canonical bytes, the pinned tokenizer (`o200k_base`), and the
+exact launch command. Disputes reduce to a byte-level diff:
 
 ```bash
 npx -y mcp-context-cost verify results/github/measurement.json
@@ -110,6 +194,11 @@ Add `--json` for scripting (`{ ok, serverName, rederivedTokens, rederivedSha, pr
 on stdout, `badge` omitted on failure). Exit codes: `0` ok, `1` verification/measurement
 failed, `2` usage error.
 
+`audit` runs that same code path on your own machine and reports each server's
+`canonicalSha256` in `--json`, so you can check that the version you installed is byte-identical
+to the one that was published — which is exactly what `--claude` uses to decide whether it is
+allowed to show you a number.
+
 Full definition: [docs/METHODOLOGY.md](docs/METHODOLOGY.md) — what is counted, what the
 number is *not*, config policy, failure taxonomy, frozen color bands, known divergences.
 
@@ -119,7 +208,7 @@ number is *not*, config policy, failure taxonomy, frozen color bands, known dive
 |---|---|
 | `src/core/` | the measurement spec, executable — canonical form, tokenizer, bands, badge JSON |
 | `src/sweep/` | raw-wire MCP stdio client + Dockerized batch sweep + leaderboard/dashboard generators |
-| `src/audit/` | client-config discovery (5 clients, JSONC-tolerant) + the per-stack report |
+| `src/audit/` | client-config discovery (5 clients, JSONC-tolerant), the per-stack report, and the baseline diff |
 | `src/cli.ts` | `audit` (measure your own stack), `verify` (re-derive any published number), `measure` |
 | `spec/fixtures/` | golden vectors shared by the TypeScript and bash implementations |
 | `tools/` | the one script that calls a network API (Claude divergence); kept out of the package so the library stays offline |
@@ -152,7 +241,7 @@ Or self-serve from CI via the (staged) mcp-tokens-action badge inputs — see
 ## Development
 
 ```bash
-npm test                        # 105 TS tests incl. golden fixtures + dispute drills
+npm test                        # 158 TS tests incl. golden fixtures + dispute drills
 npx tsc --noEmit                # typecheck
 ./upstream/tests/badge-test.sh  # 21 bash tests — byte-identical to the TS reference
 npm run sweep:all -- --docker   # full curated sweep (Docker isolation)
@@ -165,7 +254,11 @@ color bands are frozen against the observed distribution of the first full sweep
 
 ## Status
 
-Active. The leaderboard refreshes weekly; badge PRs are open across the ecosystem and
+Active. 56 of the 65 numbers come from a single sweep on 2026-08-16, 3 from 2026-08-17, and
+6 from 2026-08-18 (an upstream `mcp` package bump broke the old low-level-`Server` API these
+six relied on; pinning `mcp<2` in their launch commands fixed startup, not this project's code);
+the weekly job currently re-measures one server (`memory`), so treat the leaderboard as a
+dated snapshot rather than a live feed. Badge PRs are open across the ecosystem and
 [sd2k/mcp-tokens-action#5](https://github.com/sd2k/mcp-tokens-action/pull/5) proposes the
 self-serve badge path upstream. See [ROADMAP.md](ROADMAP.md) for what's next —
 contributions welcome, especially new `servers.yaml` entries.

package/dist/audit/audit.d.ts

@@ -1,5 +1,7 @@
+import { type DivergenceRun } from '../core/divergence.js';
 import type { Measurement, MeasurementStatus, ToolMeasurement } from '../core/types.js';
 import type { ConfiguredServer, LoadedConfig } from './config.js';
+import { type AuditDiff, type IncreaseGate } from './diff.js';
 export declare const DEFAULT_CONTEXT_WINDOW = 200000;
 export type AuditStatus = MeasurementStatus | 'remote-not-measurable';
 export interface AuditServerResult {
@@ -15,6 +17,13 @@ export interface AuditServerResult {
     /** Names only — a server's env values never enter a report. */
     envVarNames: string[];
     canonicalSha256?: string | null;
+    /**
+     * Anthropic-request cost from the published Claude divergence run, only when
+     * its captured hash matches this install (`--claude`). `null` means the
+     * install doesn't match what was published — silence, not a stale guess.
+     * `undefined` means `--claude` wasn't requested at all.
+     */
+    claudeTokens?: number | null;
     notes?: string;
 }
 export interface HeaviestTool {
@@ -22,6 +31,17 @@ export interface HeaviestTool {
     tool: string;
     tokens: number;
 }
+/**
+ * What turning off the heaviest few tools would recover, for clients that let
+ * you disable individual tools rather than whole servers (Claude Code's
+ * per-tool permission rules, Cursor's per-tool toggles). `null` when there's
+ * nothing worth trimming (one tool total, or no measured tokens).
+ */
+export interface TrimAdvice {
+    tools: HeaviestTool[];
+    recoverableTokens: number;
+    recoverableShare: number;
+}
 export interface AuditConfigResult {
     client: string;
     source: string;
@@ -32,7 +52,37 @@ export interface AuditConfigResult {
     servers: AuditServerResult[];
     skipped: AuditServerResult[];
     heaviestTools: HeaviestTool[];
+    trimAdvice: TrimAdvice | null;
+}
+export interface BudgetFitStep {
+    name: string;
+    tokens: number;
+    /** What the config still costs after removing this one and everything above it. */
+    remaining: number;
+}
+export interface BudgetFit {
+    /** How far over the limit the worst config starts. */
+    overBy: number;
+    /** Heaviest-first removals until the remainder fits. Empty if nothing can be removed. */
+    drop: BudgetFitStep[];
+    keptCount: number;
+    keptTokens: number;
+    /** False when removing every measured server still would not fit — a limit set too low. */
+    feasible: boolean;
 }
+/**
+ * The smallest heaviest-first set of servers that gets a config under its budget.
+ *
+ * `--budget` used to print "BUDGET FAIL: 84,455 > 20,000" and stop, which tells a reader
+ * they have a problem and nothing about the shape of it. The whole point of the audit
+ * surface is that the person running it is the person paying the tokens, and "you are over"
+ * is a measurement where "these two are why" is a decision.
+ *
+ * Heaviest-first is ONE ordering, not a recommendation: this cannot know which servers you
+ * need, and dropping by weight will sometimes name the one you cannot live without. That
+ * caveat is printed with the result rather than left implied.
+ */
+export declare function planBudgetFit(config: AuditConfigResult, limit: number): BudgetFit;
 export interface AuditReport {
     methodologyVersion: string;
     encoding: 'o200k_base';
@@ -44,7 +94,18 @@ export interface AuditReport {
         worstTotal: number;
         worstSource: string;
         over: boolean;
+        /** Present only when over budget: the arithmetic of getting back under it. */
+        fit?: BudgetFit;
+    };
+    /** Present only when a divergence run was supplied (`--claude`). */
+    claudeDivergence?: {
+        model: string;
+        measuredAt: string;
     };
+    /** Present only when a baseline report was supplied (`--baseline`). */
+    diff?: AuditDiff;
+    /** Present only when `--max-increase` was supplied alongside a baseline. */
+    increaseGate?: IncreaseGate;
     problems: string[];
 }
 /** Cache key for measurement reuse: the exact argv two configs would spawn. */
@@ -58,6 +119,8 @@ export declare function buildReport(configs: LoadedConfig[], measured: Map<strin
     contextWindow?: number;
     budget?: number;
     generatedAt?: string;
+    /** Published `tools-delta/v1` run to join against (`--claude`); omit to skip the join. */
+    divergence?: DivergenceRun | null;
 }): AuditReport;
 /** Human output. JSON output is the report object itself. */
 export declare function formatReport(report: AuditReport): string;

package/dist/audit/audit.js

@@ -13,7 +13,52 @@
  * commands shared by two configs are still only measured once.
  */
 import { METHODOLOGY_VERSION } from '../core/canonical.js';
+import { isCurrent } from '../core/divergence.js';
+import { formatDiff, formatGate } from './diff.js';
 export const DEFAULT_CONTEXT_WINDOW = 200_000;
+const TRIM_TOOL_COUNT = 3;
+function buildTrimAdvice(sortedTools, totalTokens) {
+    if (totalTokens <= 0 || sortedTools.length < 2)
+        return null;
+    const trimmed = sortedTools.slice(0, TRIM_TOOL_COUNT);
+    const recoverableTokens = trimmed.reduce((a, t) => a + t.tokens, 0);
+    return { tools: trimmed, recoverableTokens, recoverableShare: recoverableTokens / totalTokens };
+}
+/**
+ * The smallest heaviest-first set of servers that gets a config under its budget.
+ *
+ * `--budget` used to print "BUDGET FAIL: 84,455 > 20,000" and stop, which tells a reader
+ * they have a problem and nothing about the shape of it. The whole point of the audit
+ * surface is that the person running it is the person paying the tokens, and "you are over"
+ * is a measurement where "these two are why" is a decision.
+ *
+ * Heaviest-first is ONE ordering, not a recommendation: this cannot know which servers you
+ * need, and dropping by weight will sometimes name the one you cannot live without. That
+ * caveat is printed with the result rather than left implied.
+ */
+export function planBudgetFit(config, limit) {
+    const measured = config.servers
+        .filter((srv) => typeof srv.tokens === 'number' && srv.tokens > 0)
+        .sort((a, b) => b.tokens - a.tokens);
+    const overBy = config.totalTokens - limit;
+    const drop = [];
+    let remaining = config.totalTokens;
+    for (const srv of measured) {
+        if (remaining <= limit)
+            break;
+        remaining -= srv.tokens;
+        drop.push({ name: srv.name, tokens: srv.tokens, remaining });
+    }
+    return {
+        overBy,
+        drop,
+        keptCount: measured.length - drop.length,
+        keptTokens: remaining,
+        // Removing everything measured still leaves unmeasured/base cost behind, so the
+        // honest test is whether the remainder actually landed under the limit.
+        feasible: remaining <= limit,
+    };
+}
 /** Cache key for measurement reuse: the exact argv two configs would spawn. */
 export function serverKey(s) {
     return JSON.stringify(s.argv ?? [s.url ?? s.name]);
@@ -73,6 +118,7 @@ export function buildReport(configs, measured, opts = {}) {
                 });
                 continue;
             }
+            const divRow = opts.divergence?.servers[s.name];
             ok.push({
                 ...base,
                 status: m.status,
@@ -80,6 +126,7 @@ export function buildReport(configs, measured, opts = {}) {
                 toolCount: m.toolCount,
                 share: null, // filled once the total is known
                 canonicalSha256: m.canonicalSha256,
+                claudeTokens: opts.divergence ? (isCurrent(divRow, m.canonicalSha256 ?? null) ? divRow.claudeDelta : null) : undefined,
                 notes: m.status === 'dynamic' ? m.notes : undefined,
             });
             for (const t of m.tools)
@@ -105,6 +152,7 @@ export function buildReport(configs, measured, opts = {}) {
             servers: ok,
             skipped,
             heaviestTools: tools.slice(0, 5),
+            trimAdvice: buildTrimAdvice(tools, totalTokens),
         });
     }
     results.sort((a, b) => b.totalTokens - a.totalTokens);
@@ -116,15 +164,20 @@ export function buildReport(configs, measured, opts = {}) {
         configs: results,
         problems,
     };
+    if (opts.divergence) {
+        report.claudeDivergence = { model: opts.divergence.model, measuredAt: opts.divergence.measuredAt };
+    }
     if (typeof opts.budget === 'number') {
         // The worst config is the gate: passing because your *lightest* client fits
         // would be a green check on a session you don't run.
         const worst = results[0];
+        const over = (worst?.totalTokens ?? 0) > opts.budget;
         report.budget = {
             limit: opts.budget,
             worstTotal: worst?.totalTokens ?? 0,
             worstSource: worst?.source ?? '(none)',
-            over: (worst?.totalTokens ?? 0) > opts.budget,
+            over,
+            fit: over && worst ? planBudgetFit(worst, opts.budget) : undefined,
         };
     }
     return report;
@@ -135,6 +188,7 @@ const pct = (x) => `${(x * 100).toFixed(1)}%`;
 export function formatReport(report) {
     const lines = [];
     lines.push(`mcp-context-cost audit · methodology ${report.methodologyVersion} · ${report.encoding} · context window ${n(report.contextWindow)}`);
+    const showClaude = !!report.claudeDivergence;
     for (const cfg of report.configs) {
         lines.push('');
         lines.push(`${cfg.client}  ${cfg.source}`);
@@ -143,18 +197,21 @@ export function formatReport(report) {
             tools: s.toolCount === null ? '—' : String(s.toolCount),
             tokens: s.tokens === null ? '—' : n(s.tokens),
             share: s.share === null ? '—' : pct(s.share),
+            claude: s.claudeTokens == null ? '—' : n(s.claudeTokens),
         }));
         const w = {
             name: Math.max(6, ...rows.map((r) => r.name.length), 'total'.length),
             tools: Math.max(5, ...rows.map((r) => r.tools.length)),
             tokens: Math.max(6, ...rows.map((r) => r.tokens.length), n(cfg.totalTokens).length),
+            claude: Math.max(6, ...rows.map((r) => r.claude.length)),
         };
-        const line = (name, tools, tokens, share) => `  ${name.padEnd(w.name)}  ${tools.padStart(w.tools)}  ${tokens.padStart(w.tokens)}  ${share.padStart(6)}`;
-        lines.push(line('server', 'tools', 'tokens', 'share'));
+        const line = (name, tools, tokens, share, claude) => `  ${name.padEnd(w.name)}  ${tools.padStart(w.tools)}  ${tokens.padStart(w.tokens)}  ${share.padStart(6)}` +
+            (showClaude ? `  ${claude.padStart(w.claude)}` : '');
+        lines.push(line('server', 'tools', 'tokens', 'share', 'claude'));
         for (const r of rows)
-            lines.push(line(r.name, r.tools, r.tokens, r.share));
-        lines.push(`  ${'─'.repeat(w.name + w.tools + w.tokens + 14)}`);
-        lines.push(line('total', String(cfg.toolCount), n(cfg.totalTokens), ''));
+            lines.push(line(r.name, r.tools, r.tokens, r.share, r.claude));
+        lines.push(`  ${'─'.repeat(w.name + w.tools + w.tokens + 14 + (showClaude ? w.claude + 2 : 0))}`);
+        lines.push(line('total', String(cfg.toolCount), n(cfg.totalTokens), '', ''));
         lines.push('');
         lines.push(`  Every request in this client carries ${n(cfg.totalTokens)} tokens of tool schemas — ` +
             `${pct(cfg.contextShare)} of a ${n(report.contextWindow)}-token context window, before you type anything.`);
@@ -166,6 +223,13 @@ export function formatReport(report) {
                 lines.push(`    ${`${t.server} · ${t.tool}`.padEnd(tw)}  ${n(t.tokens).padStart(7)}`);
             }
         }
+        if (cfg.trimAdvice) {
+            const names = cfg.trimAdvice.tools.map((t) => `${t.server}·${t.tool}`).join(', ');
+            lines.push('');
+            lines.push(`  trim: disabling ${cfg.trimAdvice.tools.length} tool${cfg.trimAdvice.tools.length === 1 ? '' : 's'} ` +
+                `(${names}) would recover ${n(cfg.trimAdvice.recoverableTokens)} tokens ` +
+                `(${pct(cfg.trimAdvice.recoverableShare)} of this config) — if your client supports per-tool filtering.`);
+        }
         if (cfg.skipped.length) {
             lines.push('');
             lines.push('  not measured');
@@ -175,6 +239,11 @@ export function formatReport(report) {
             }
         }
     }
+    if (showClaude) {
+        lines.push('');
+        lines.push(`  claude = Anthropic-request cost from the ${report.claudeDivergence.measuredAt} ${report.claudeDivergence.model} ` +
+            `divergence run, shown only where the published capture hash matches this install; '—' means no current match.`);
+    }
     if (report.problems.length) {
         lines.push('');
         lines.push('problems');
@@ -182,10 +251,52 @@ export function formatReport(report) {
             lines.push(`  ${p}`);
     }
     if (report.budget) {
+        const b = report.budget;
+        lines.push('');
+        if (!b.over) {
+            const headroom = b.limit - b.worstTotal;
+            lines.push(`budget ok: ${n(b.worstTotal)} ≤ ${n(b.limit)} — ${n(headroom)} to spare`);
+        }
+        else {
+            lines.push(`BUDGET FAIL: ${n(b.worstTotal)} > ${n(b.limit)} (${b.worstSource})`);
+            const fit = b.fit;
+            if (fit && fit.drop.length) {
+                lines.push('');
+                lines.push(`  over by ${n(fit.overBy)}. Heaviest-first, this is what gets you under:`);
+                for (const step of fit.drop) {
+                    const verdict = step.remaining <= b.limit ? 'fits' : 'still over';
+                    lines.push(`    drop  ${step.name.padEnd(22)} ${n(step.tokens).padStart(9)}  →  ${n(step.remaining).padStart(9)}  ${verdict}`);
+                }
+                lines.push('');
+                if (fit.feasible && fit.keptCount === 0) {
+                    // Arithmetically it fits, and the answer is useless: the only way under this
+                    // limit is to run no servers at all. Saying "fits" here would be true and
+                    // misleading, which is the pair this whole tool exists to keep apart.
+                    lines.push(`  no subset fits: every measured server would have to go. The limit is below`);
+                    lines.push(`  what any one of these servers costs.`);
+                }
+                else if (fit.feasible) {
+                    const share = b.limit > 0 ? ` (${pct(fit.keptTokens / b.limit)} of budget)` : '';
+                    lines.push(`  keeps ${fit.keptCount} server(s) at ${n(fit.keptTokens)} tokens${share}`);
+                }
+                else {
+                    lines.push(`  even removing every measured server leaves ${n(fit.keptTokens)} — the limit is below this config's floor`);
+                }
+                lines.push('');
+                lines.push('  This is arithmetic, not advice: it cannot know which servers you need, and by');
+                lines.push('  weight alone it will sometimes name the one you cannot work without. Use --json');
+                lines.push('  for the full per-server list and pick your own order.');
+            }
+            else if (fit) {
+                lines.push('  nothing measured could be removed to get under the limit.');
+            }
+        }
+    }
+    if (report.diff)
+        lines.push(formatDiff(report.diff, report.contextWindow));
+    if (report.increaseGate) {
         lines.push('');
-        lines.push(report.budget.over
-            ? `BUDGET FAIL: ${n(report.budget.worstTotal)} > ${n(report.budget.limit)} (${report.budget.worstSource})`
-            : `budget ok: ${n(report.budget.worstTotal)} ≤ ${n(report.budget.limit)}`);
+        lines.push(formatGate(report.increaseGate));
     }
     lines.push('');
     lines.push('These are wire tokens — what the server puts on the wire, counted with o200k_base. What your model is billed');

package/dist/audit/diff.d.ts

@@ -0,0 +1,124 @@
+/**
+ * `audit --baseline <report.json>` — what a config change costs every future session.
+ *
+ * `audit` answers "what do my servers cost right now". That is a number a reader
+ * has to have an opinion about. A diff against a stored earlier report answers
+ * the question that needs no opinion at all: *this change adds 17,000 tokens to
+ * every request you will ever send from this client.* Same measurement path,
+ * same per-config discipline — a baseline is just an earlier `audit --json`.
+ *
+ * The trap this file exists to avoid: a server that measured fine before and
+ * fails to start now makes the total go DOWN. Subtracting two totals would
+ * report that as an improvement, which is the flattering reading and the true
+ * one having the same shape. So a server that changed measured-ness is never
+ * given a delta — it is named, its known side is printed, and the direction of
+ * the resulting error is stated ("understates by at least 9,246").
+ */
+import type { AuditConfigResult, AuditReport } from './audit.js';
+export type ServerDeltaKind = 'added' | 'removed' | 'changed' | 'unchanged'
+/** Measured in the baseline, not measurable now — the total understates. */
+ | 'unmeasured-now'
+/** Not measurable in the baseline, measured now — the increase overstates. */
+ | 'unmeasured-before'
+/** Present and unmeasured in both runs — contributes 0 to both totals, but hides cost. */
+ | 'unmeasured-both';
+export interface ServerDelta {
+    name: string;
+    kind: ServerDeltaKind;
+    /** Baseline tokens; `null` when absent from the baseline or unmeasured in it. */
+    before: number | null;
+    /** Current tokens; `null` when gone from the config or unmeasured now. */
+    after: number | null;
+    /** Signed change. `null` whenever the two sides are not the same kind of number. */
+    delta: number | null;
+    /** Why a delta is missing, in a sentence a reader can act on. */
+    note?: string;
+}
+export interface ConfigDiff {
+    client: string;
+    source: string;
+    /** How this config was paired with a baseline config. */
+    matchedBy: 'source' | 'sole-config' | 'unmatched';
+    beforeTotal: number | null;
+    afterTotal: number;
+    /** afterTotal - beforeTotal, or `null` when there is no baseline to subtract. */
+    delta: number | null;
+    beforeShare: number | null;
+    afterShare: number;
+    /**
+     * True when `delta` is the exact change in measured cost. False when a server
+     * crossed the measured/unmeasured line, which moves the total for a reason
+     * that is not a config change.
+     */
+    exact: boolean;
+    /** Tokens the diff is known to be missing, and which way it leans. */
+    understatedBy: number;
+    overstatedBy: number;
+    servers: ServerDelta[];
+}
+export interface AuditDiff {
+    baselineGeneratedAt: string;
+    baselineMethodologyVersion: string;
+    /** False when something makes the two reports incommensurable at all (methodology bump). */
+    comparable: boolean;
+    /** Baseline configs that no current config matched — never silently dropped. */
+    droppedConfigs: {
+        client: string;
+        source: string;
+        totalTokens: number;
+    }[];
+    warnings: string[];
+    configs: ConfigDiff[];
+    /**
+     * The largest per-config increase. Per config, never merged: a context window
+     * belongs to one client session, so a portfolio-wide "total delta" would
+     * describe a session nobody runs. `null` when nothing could be compared.
+     */
+    worstIncrease: {
+        source: string;
+        delta: number;
+    } | null;
+}
+/** Parse and shape-check a stored report. A baseline that cannot be read is never "no change". */
+export declare function parseBaselineReport(text: string): {
+    report: AuditReport | null;
+    problem?: string;
+};
+export declare function diffConfig(before: AuditConfigResult | null, after: AuditConfigResult, matchedBy: ConfigDiff['matchedBy']): ConfigDiff;
+/**
+ * Pair current configs with baseline configs.
+ *
+ * Exact source path first. Then one deliberate fallback: if each side has
+ * exactly one config, they are the same config seen from two machines — the CI
+ * case, where a baseline recorded at /Users/… meets a checkout at /home/runner/….
+ * Anything looser would pair two unrelated clients and call the difference a
+ * change, so everything else stays unmatched and says so.
+ */
+export declare function pairConfigs(before: AuditConfigResult[], after: AuditConfigResult[]): {
+    pairs: {
+        before: AuditConfigResult | null;
+        after: AuditConfigResult;
+        matchedBy: ConfigDiff['matchedBy'];
+    }[];
+    dropped: AuditConfigResult[];
+};
+export declare function buildDiff(baseline: AuditReport, current: AuditReport): AuditDiff;
+export declare function formatDiff(diff: AuditDiff, contextWindow: number): string;
+export interface IncreaseGate {
+    limit: number;
+    pass: boolean;
+    /** The increase the gate measured, when it got far enough to measure one. */
+    increase: number | null;
+    reasons: string[];
+}
+/**
+ * `--max-increase N` — the CI gate. Fails on an increase over the limit, and
+ * equally on any reason the increase could not be established.
+ *
+ * That second half is the point. A gate that passes when a server failed to
+ * start, or when the baseline covered a config this run never found, is a green
+ * check on a question nobody asked. Everything this portfolio has learned says
+ * unchecked must not read as clean, so an inexact diff fails and names why.
+ */
+export declare function evaluateIncreaseGate(diff: AuditDiff, limit: number): IncreaseGate;
+export declare function formatGate(gate: IncreaseGate): string;