mcp-context-cost 0.2.0 → 0.4.0

package/dist/audit/config.d.ts

@@ -0,0 +1,53 @@
+export interface ConfiguredServer {
+    name: string;
+    /** Which client's config this came from ('claude-desktop', 'cursor', ...). */
+    client: string;
+    /** Absolute path of the config file. */
+    source: string;
+    transport: 'stdio' | 'remote';
+    /** Display form of the launch command (argv joined) — stdio only. */
+    command?: string;
+    /** Exact argv, so paths containing spaces survive round-tripping. */
+    argv?: string[];
+    envVarNames: string[];
+    /** Values, needed to spawn the server. NEVER serialize this. */
+    env?: Record<string, string>;
+    /** Remote endpoint — recorded so the report can say why it was skipped. */
+    url?: string;
+}
+/**
+ * JSON with comments and trailing commas — VS Code's mcp.json allows both, and
+ * hand-edited Claude/Cursor configs often pick up a trailing comma too. String
+ * literals are tracked so a `//` or `,}` inside a tool description survives.
+ */
+export declare function parseJsonc(text: string): unknown;
+/**
+ * Pull every server out of one parsed config document. `cwd` selects the
+ * project scope in Claude Code's `~/.claude.json`, which keys per-project
+ * servers by absolute directory.
+ */
+export declare function extractServers(doc: unknown, meta: {
+    client: string;
+    source: string;
+    cwd?: string;
+}): ConfiguredServer[];
+export interface ConfigCandidate {
+    client: string;
+    path: string;
+}
+/** Every place a client config is known to live, whether or not it exists. */
+export declare function configCandidates(env: {
+    home: string;
+    cwd: string;
+    platform: NodeJS.Platform;
+    appData?: string;
+}): ConfigCandidate[];
+export interface LoadedConfig {
+    client: string;
+    source: string;
+    servers: ConfiguredServer[];
+    /** Set when the file exists but could not be read/parsed. */
+    error?: string;
+}
+/** Read + parse the candidates that exist. Unreadable files are reported, not thrown. */
+export declare function loadConfigs(candidates: ConfigCandidate[], cwd: string): LoadedConfig[];

package/dist/audit/config.js

@@ -0,0 +1,179 @@
+/**
+ * MCP client config discovery + parsing.
+ *
+ * The leaderboard measures servers one at a time; `audit` measures the set a
+ * person actually has installed. That set lives in a client config file, and
+ * every client spells it slightly differently:
+ *
+ *   Claude Desktop / Claude Code / Cursor / Windsurf   { "mcpServers": { ... } }
+ *   VS Code (.vscode/mcp.json)                         { "servers": { ... } }
+ *   Claude Code (~/.claude.json)                       also { "projects": { "<dir>": { "mcpServers": ... } } }
+ *
+ * Everything here is pure (paths in, servers out) so the discovery rules are
+ * testable without touching a real home directory.
+ *
+ * Env var VALUES are read (a server usually needs its key to start) but are
+ * never written to a report: report builders pick fields explicitly and only
+ * `envVarNames` is ever serialized.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * JSON with comments and trailing commas — VS Code's mcp.json allows both, and
+ * hand-edited Claude/Cursor configs often pick up a trailing comma too. String
+ * literals are tracked so a `//` or `,}` inside a tool description survives.
+ */
+export function parseJsonc(text) {
+    let out = '';
+    let inString = false;
+    let escaped = false;
+    let pendingComma = false;
+    const flush = (next) => {
+        if (!pendingComma)
+            return;
+        // A comma is only trailing if the next real character closes the container.
+        if (next !== '}' && next !== ']')
+            out += ',';
+        pendingComma = false;
+    };
+    for (let i = 0; i < text.length; i++) {
+        const c = text[i];
+        const n = text[i + 1];
+        if (inString) {
+            out += c;
+            if (escaped)
+                escaped = false;
+            else if (c === '\\')
+                escaped = true;
+            else if (c === '"')
+                inString = false;
+            continue;
+        }
+        if (c === '/' && n === '/') {
+            while (i < text.length && text[i] !== '\n')
+                i++;
+            continue;
+        }
+        if (c === '/' && n === '*') {
+            i += 2;
+            while (i < text.length && !(text[i] === '*' && text[i + 1] === '/'))
+                i++;
+            i++;
+            continue;
+        }
+        if (c === ',') {
+            pendingComma = true;
+            continue;
+        }
+        if (/\s/.test(c)) {
+            if (!pendingComma)
+                out += c;
+            continue;
+        }
+        flush(c);
+        out += c;
+        if (c === '"')
+            inString = true;
+    }
+    return JSON.parse(out);
+}
+function toServer(name, raw, client, source) {
+    if (raw.disabled === true)
+        return null;
+    const env = {};
+    for (const [k, v] of Object.entries(raw.env ?? {})) {
+        if (typeof v === 'string')
+            env[k] = v;
+    }
+    const envVarNames = Object.keys(env).sort();
+    // Remote entries carry a url (and sometimes type http/sse) instead of a command.
+    if (!raw.command && typeof raw.url === 'string') {
+        return { name, client, source, transport: 'remote', url: raw.url, envVarNames };
+    }
+    if (typeof raw.command !== 'string' || raw.command.trim() === '')
+        return null;
+    const args = Array.isArray(raw.args) ? raw.args.filter((a) => typeof a === 'string') : [];
+    const argv = [raw.command, ...args];
+    return {
+        name,
+        client,
+        source,
+        transport: 'stdio',
+        // Quote only the args that need it, so the printed command stays copy-pasteable.
+        command: argv.map((a) => (/\s/.test(a) ? JSON.stringify(a) : a)).join(' '),
+        argv,
+        envVarNames,
+        env: envVarNames.length ? env : undefined,
+    };
+}
+/**
+ * Pull every server out of one parsed config document. `cwd` selects the
+ * project scope in Claude Code's `~/.claude.json`, which keys per-project
+ * servers by absolute directory.
+ */
+export function extractServers(doc, meta) {
+    if (!doc || typeof doc !== 'object')
+        return [];
+    const d = doc;
+    const out = [];
+    const addBlock = (block) => {
+        if (!block || typeof block !== 'object')
+            return;
+        for (const [name, raw] of Object.entries(block)) {
+            if (!raw || typeof raw !== 'object')
+                continue;
+            const s = toServer(name, raw, meta.client, meta.source);
+            if (s)
+                out.push(s);
+        }
+    };
+    addBlock(d.mcpServers);
+    addBlock(d.servers); // VS Code
+    if (meta.cwd && d.projects && typeof d.projects === 'object') {
+        const project = d.projects[meta.cwd];
+        if (project && typeof project === 'object')
+            addBlock(project.mcpServers);
+    }
+    // A name can legitimately appear in both blocks of the same file; keep the first.
+    const seen = new Set();
+    return out.filter((s) => (seen.has(s.name) ? false : (seen.add(s.name), true)));
+}
+/** Every place a client config is known to live, whether or not it exists. */
+export function configCandidates(env) {
+    const { home, cwd, platform } = env;
+    const desktop = platform === 'darwin'
+        ? join(home, 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json')
+        : platform === 'win32'
+            ? join(env.appData ?? join(home, 'AppData', 'Roaming'), 'Claude', 'claude_desktop_config.json')
+            : join(home, '.config', 'Claude', 'claude_desktop_config.json');
+    return [
+        { client: 'claude-desktop', path: desktop },
+        { client: 'claude-code', path: join(home, '.claude.json') },
+        { client: 'claude-code', path: join(cwd, '.mcp.json') },
+        { client: 'cursor', path: join(home, '.cursor', 'mcp.json') },
+        { client: 'cursor', path: join(cwd, '.cursor', 'mcp.json') },
+        { client: 'vscode', path: join(cwd, '.vscode', 'mcp.json') },
+        { client: 'windsurf', path: join(home, '.codeium', 'windsurf', 'mcp_config.json') },
+    ];
+}
+/** Read + parse the candidates that exist. Unreadable files are reported, not thrown. */
+export function loadConfigs(candidates, cwd) {
+    const out = [];
+    for (const c of candidates) {
+        if (!existsSync(c.path))
+            continue;
+        try {
+            const doc = parseJsonc(readFileSync(c.path, 'utf8'));
+            const servers = extractServers(doc, { client: c.client, source: c.path, cwd });
+            // A config with no MCP block at all (e.g. a ~/.claude.json holding only
+            // session history) is not worth a line in the report.
+            if (servers.length === 0)
+                continue;
+            out.push({ client: c.client, source: c.path, servers });
+        }
+        catch (e) {
+            out.push({ client: c.client, source: c.path, servers: [], error: e.message });
+        }
+    }
+    return out;
+}

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;

package/dist/audit/diff.js

@@ -0,0 +1,318 @@
+/** Parse and shape-check a stored report. A baseline that cannot be read is never "no change". */
+export function parseBaselineReport(text) {
+    let doc;
+    try {
+        doc = JSON.parse(text);
+    }
+    catch (e) {
+        return { report: null, problem: `baseline is not JSON: ${e.message}` };
+    }
+    if (!doc || typeof doc !== 'object' || Array.isArray(doc)) {
+        return { report: null, problem: 'baseline is not an audit report object' };
+    }
+    const r = doc;
+    if (!Array.isArray(r.configs)) {
+        return { report: null, problem: "baseline has no 'configs' array — is it the output of `audit --json`?" };
+    }
+    if (typeof r.methodologyVersion !== 'string' || typeof r.encoding !== 'string') {
+        return { report: null, problem: 'baseline is missing methodologyVersion/encoding — is it the output of `audit --json`?' };
+    }
+    for (const c of r.configs) {
+        if (!c || typeof c !== 'object' || typeof c.source !== 'string') {
+            return { report: null, problem: 'baseline has a config entry without a source path' };
+        }
+    }
+    return { report: doc };
+}
+function statesOf(cfg) {
+    const out = new Map();
+    for (const s of cfg.servers ?? [])
+        out.set(s.name, { present: true, tokens: typeof s.tokens === 'number' ? s.tokens : null });
+    // A skipped server IS in the config; it just has no number. Keeping it distinct
+    // from absent is the whole reason `removed` and `unmeasured-now` are separate kinds.
+    for (const s of cfg.skipped ?? [])
+        if (!out.has(s.name))
+            out.set(s.name, { present: true, tokens: null });
+    return out;
+}
+export function diffConfig(before, after, matchedBy) {
+    const afterShare = after.contextShare;
+    if (!before) {
+        return {
+            client: after.client,
+            source: after.source,
+            matchedBy: 'unmatched',
+            beforeTotal: null,
+            afterTotal: after.totalTokens,
+            delta: null,
+            beforeShare: null,
+            afterShare,
+            exact: false,
+            understatedBy: 0,
+            overstatedBy: 0,
+            servers: [],
+        };
+    }
+    const b = statesOf(before);
+    const a = statesOf(after);
+    const servers = [];
+    let understatedBy = 0;
+    let overstatedBy = 0;
+    let exact = true;
+    for (const name of new Set([...b.keys(), ...a.keys()])) {
+        const bs = b.get(name);
+        const as = a.get(name);
+        if (bs && !as) {
+            servers.push(bs.tokens === null
+                ? { name, kind: 'removed', before: null, after: null, delta: null, note: 'was in the config but never measured — removing it changed no measured cost' }
+                : { name, kind: 'removed', before: bs.tokens, after: null, delta: -bs.tokens });
+            continue;
+        }
+        if (!bs && as) {
+            servers.push(as.tokens === null
+                ? { name, kind: 'added', before: null, after: null, delta: null, note: 'added but not measurable — its cost is unknown, not zero' }
+                : { name, kind: 'added', before: null, after: as.tokens, delta: as.tokens });
+            continue;
+        }
+        if (!bs || !as)
+            continue;
+        if (bs.tokens !== null && as.tokens !== null) {
+            const delta = as.tokens - bs.tokens;
+            servers.push({ name, kind: delta === 0 ? 'unchanged' : 'changed', before: bs.tokens, after: as.tokens, delta });
+        }
+        else if (bs.tokens !== null && as.tokens === null) {
+            exact = false;
+            understatedBy += bs.tokens;
+            servers.push({
+                name,
+                kind: 'unmeasured-now',
+                before: bs.tokens,
+                after: null,
+                delta: null,
+                note: `measured ${bs.tokens.toLocaleString('en-US')} in the baseline and could not be measured now — its cost is missing from the total, not gone from your config`,
+            });
+        }
+        else if (bs.tokens === null && as.tokens !== null) {
+            exact = false;
+            overstatedBy += as.tokens;
+            servers.push({
+                name,
+                kind: 'unmeasured-before',
+                before: null,
+                after: as.tokens,
+                delta: null,
+                note: `could not be measured in the baseline and measures ${as.tokens.toLocaleString('en-US')} now — this cost is newly visible, not necessarily new`,
+            });
+        }
+        else {
+            servers.push({
+                name,
+                kind: 'unmeasured-both',
+                before: null,
+                after: null,
+                delta: null,
+                note: 'not measurable in either run — contributes 0 to both totals and hides an unknown cost',
+            });
+        }
+    }
+    // Biggest movers first; ties and non-deltas fall to the bottom in name order.
+    servers.sort((x, y) => Math.abs(y.delta ?? 0) - Math.abs(x.delta ?? 0) || x.name.localeCompare(y.name));
+    return {
+        client: after.client,
+        source: after.source,
+        matchedBy,
+        beforeTotal: before.totalTokens,
+        afterTotal: after.totalTokens,
+        delta: after.totalTokens - before.totalTokens,
+        beforeShare: before.contextShare ?? null,
+        afterShare,
+        exact,
+        understatedBy,
+        overstatedBy,
+        servers,
+    };
+}
+/**
+ * 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 function pairConfigs(before, after) {
+    const unusedBefore = new Map(before.map((c) => [c.source, c]));
+    const pairs = [];
+    for (const cur of after) {
+        const hit = unusedBefore.get(cur.source);
+        if (hit) {
+            unusedBefore.delete(cur.source);
+            pairs.push({ before: hit, after: cur, matchedBy: 'source' });
+        }
+        else {
+            pairs.push({ before: null, after: cur, matchedBy: 'unmatched' });
+        }
+    }
+    if (before.length === 1 && after.length === 1 && pairs[0].before === null) {
+        pairs[0] = { before: before[0], after: after[0], matchedBy: 'sole-config' };
+        unusedBefore.delete(before[0].source);
+    }
+    return { pairs, dropped: [...unusedBefore.values()] };
+}
+export function buildDiff(baseline, current) {
+    const warnings = [];
+    let comparable = true;
+    if (baseline.methodologyVersion !== current.methodologyVersion) {
+        comparable = false;
+        warnings.push(`methodology changed (${baseline.methodologyVersion} → ${current.methodologyVersion}) — token counts from the two runs are not the same measurement`);
+    }
+    if (baseline.encoding !== current.encoding) {
+        comparable = false;
+        warnings.push(`encoding changed (${baseline.encoding} → ${current.encoding}) — the counts are in different units`);
+    }
+    if (baseline.contextWindow !== current.contextWindow) {
+        // Shares move, token counts do not. Worth saying, not worth invalidating.
+        warnings.push(`context window changed (${baseline.contextWindow.toLocaleString('en-US')} → ${current.contextWindow.toLocaleString('en-US')}) — shares are not comparable, token counts still are`);
+    }
+    const { pairs, dropped } = pairConfigs(baseline.configs, current.configs);
+    const configs = pairs.map((p) => diffConfig(p.before, p.after, p.matchedBy));
+    for (const c of configs) {
+        if (c.matchedBy === 'unmatched') {
+            warnings.push(`${c.source}: no matching config in the baseline — its ${c.afterTotal.toLocaleString('en-US')} tokens are shown as a total, not a change`);
+        }
+        if (c.matchedBy === 'sole-config' && c.source !== baseline.configs[0]?.source) {
+            warnings.push(`paired ${c.source} with the baseline's ${baseline.configs[0]?.source} — one config on each side, different paths`);
+        }
+    }
+    for (const d of dropped) {
+        warnings.push(`${d.source}: in the baseline (${d.totalTokens.toLocaleString('en-US')} tokens) and not found now — a config that disappeared is not a config that got cheaper`);
+    }
+    const increases = configs.filter((c) => typeof c.delta === 'number' && c.delta > 0);
+    increases.sort((a, b) => b.delta - a.delta);
+    return {
+        baselineGeneratedAt: baseline.generatedAt,
+        baselineMethodologyVersion: baseline.methodologyVersion,
+        comparable,
+        droppedConfigs: dropped.map((d) => ({ client: d.client, source: d.source, totalTokens: d.totalTokens })),
+        warnings,
+        configs,
+        worstIncrease: increases.length ? { source: increases[0].source, delta: increases[0].delta } : null,
+    };
+}
+const n = (x) => x.toLocaleString('en-US');
+const signed = (x) => `${x >= 0 ? '+' : '−'}${n(Math.abs(x))}`;
+const pct = (x) => `${(x * 100).toFixed(1)}%`;
+/** `--config <path>` records the client as 'explicit', which is a parser detail, not a name. */
+const clientLabel = (client) => (client === 'explicit' || !client ? 'this client' : client);
+export function formatDiff(diff, contextWindow) {
+    const lines = [];
+    lines.push('');
+    lines.push(`diff vs baseline measured ${diff.baselineGeneratedAt} (methodology ${diff.baselineMethodologyVersion})`);
+    for (const c of diff.configs) {
+        lines.push('');
+        if (c.matchedBy === 'unmatched' || c.delta === null || c.beforeTotal === null) {
+            lines.push(`  ${c.source}  ${n(c.afterTotal)} tokens — no baseline for this config, so nothing to compare`);
+            continue;
+        }
+        const rows = c.servers.filter((s) => s.kind !== 'unchanged');
+        lines.push(`  ${c.source}`);
+        lines.push(`    ${n(c.beforeTotal)}  →  ${n(c.afterTotal)}   ${signed(c.delta)}`);
+        if (rows.length) {
+            lines.push('');
+            const w = Math.max(...rows.map((r) => r.name.length), 6);
+            for (const r of rows) {
+                const from = r.before === null ? '—' : n(r.before);
+                const to = r.after === null ? '—' : n(r.after);
+                const d = r.delta === null ? '' : `  ${signed(r.delta)}`;
+                lines.push(`    ${r.kind.padEnd(17)} ${r.name.padEnd(w)}  ${from.padStart(9)} → ${to.padStart(9)}${d}`);
+            }
+        }
+        const unchanged = c.servers.length - rows.length;
+        if (unchanged)
+            lines.push(`    (${unchanged} server${unchanged === 1 ? '' : 's'} unchanged)`);
+        lines.push('');
+        if (!c.exact) {
+            // The headline sentence is where a skimmer stops, so it must not assert a change
+            // this run could not establish. A server that died takes its tokens out of the
+            // total exactly like a server you uninstalled — printing "removes 2,378 tokens"
+            // and correcting it two lines down is the flattering reading getting read.
+            lines.push(`    Not a clean comparison: a server changed measured-ness between the two runs.`);
+            lines.push(`    The measured total moved ${signed(c.delta)}, but that is not what your config did.`);
+            lines.push('');
+            for (const r of c.servers) {
+                if (r.kind === 'unmeasured-now' || r.kind === 'unmeasured-before')
+                    lines.push(`      ${r.name}: ${r.note}`);
+            }
+            if (c.understatedBy)
+                lines.push(`      → true cost is at least ${n(c.understatedBy)} higher than the ${n(c.afterTotal)} measured now.`);
+            if (c.overstatedBy)
+                lines.push(`      → up to ${n(c.overstatedBy)} of that movement was already being paid, just unmeasured.`);
+        }
+        else if (c.delta === 0) {
+            lines.push(`    No change: this config costs the same ${n(c.afterTotal)} tokens per request as the baseline.`);
+        }
+        else if (c.delta > 0) {
+            lines.push(`    This change adds ${n(c.delta)} tokens to every request in ${clientLabel(c.client)} — ` +
+                `${pct(c.beforeShare ?? 0)} → ${pct(c.afterShare)} of a ${n(contextWindow)}-token context window.`);
+        }
+        else {
+            lines.push(`    This change removes ${n(Math.abs(c.delta))} tokens from every request in ${clientLabel(c.client)} — ` +
+                `${pct(c.beforeShare ?? 0)} → ${pct(c.afterShare)} of a ${n(contextWindow)}-token context window.`);
+        }
+        const blind = c.servers.filter((r) => r.kind === 'unmeasured-both' || ((r.kind === 'added' || r.kind === 'removed') && r.delta === null));
+        if (blind.length) {
+            lines.push('');
+            for (const r of blind)
+                lines.push(`    ${r.name}: ${r.note}`);
+        }
+    }
+    if (diff.warnings.length) {
+        lines.push('');
+        lines.push('  diff warnings');
+        for (const w of diff.warnings)
+            lines.push(`    ${w}`);
+    }
+    if (!diff.comparable) {
+        lines.push('');
+        lines.push('  The two runs are not the same measurement, so the numbers above are not a change.');
+        lines.push('  Re-record the baseline with this version: mcp-context-cost audit --json > baseline.json');
+    }
+    return lines.join('\n');
+}
+/**
+ * `--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 function evaluateIncreaseGate(diff, limit) {
+    const reasons = [];
+    if (!diff.comparable)
+        reasons.push('the baseline is not the same measurement as this run — nothing was compared');
+    for (const c of diff.configs) {
+        if (c.matchedBy === 'unmatched') {
+            reasons.push(`${c.source}: no baseline to check its ${n(c.afterTotal)} tokens against`);
+        }
+        else if (!c.exact) {
+            reasons.push(`${c.source}: a server changed measured-ness, so the change could not be established exactly`);
+        }
+    }
+    for (const d of diff.droppedConfigs) {
+        reasons.push(`${d.source}: covered by the baseline and not found in this run`);
+    }
+    const increase = diff.worstIncrease?.delta ?? (diff.configs.some((c) => typeof c.delta === 'number') ? 0 : null);
+    if (reasons.length === 0 && increase !== null && increase > limit) {
+        reasons.push(`${diff.worstIncrease.source}: +${n(increase)} tokens per request, over the ${n(limit)} allowed`);
+    }
+    return { limit, pass: reasons.length === 0, increase, reasons };
+}
+export function formatGate(gate) {
+    if (gate.pass) {
+        return `increase ok: ${gate.increase === null ? 'no change to measure' : `${signed(gate.increase)} tokens`} ≤ ${n(gate.limit)} allowed`;
+    }
+    return ['INCREASE FAIL:', ...gate.reasons.map((r) => `  ${r}`)].join('\n');
+}