mcp-context-cost 0.8.0 → 0.10.0

package/README.md

@@ -183,10 +183,9 @@ INCREASE FAIL:
 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. The run holds 20 rows — the top 20 measured servers by tokens; 19 of them
-still match the capture on disk here, which is why
-[results/leaderboard.md](results/leaderboard.md) prints a claude number for 19 and leaves the
-twentieth blank rather than stale. Most installs will show a mix:
+when it doesn't. The run holds 20 rows — the top 20 measured servers by tokens when it ran —
+and [results/leaderboard.md](results/leaderboard.md) prints a claude number for the 16 that
+still match today and silence for the rest. Most installs will show a mix:
 
 ```
   server               tools  tokens   share   claude
@@ -194,22 +193,39 @@ twentieth blank rather than stale. Most installs will show a mix:
   memory                   9   2,378    4.2%       —
 ```
 
+Add `--suggest` to place each of your tools in the measured set's tool-shape distribution
+([method](docs/METHODOLOGY.md#tool-shape)) and get advice only where the data can point at
+something. Only descriptions draw advice — schemas are functional surface; descriptions are
+prose every request carries — and only descriptions at or above the 90th percentile of the
+1,150 measured tools:
+
+```
+  suggest — descriptions at or above the 90th percentile of measured tools
+  (baseline 2026-09-03: 1,150 tools across 81 measured servers):
+    stub · wordy — 345 tokens: description 321 (p92), schema 14
+      rewriting the description toward the measured median (27) would recover ≈294 tokens on every request
+    1 of 2 tools sit inside the distribution — no advice where nothing is measurably unusual.
+```
+
+A config where nothing is out of distribution is told that in those words, and a baseline
+that cannot be fetched is a named problem, never a silently skipped check.
+
 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`.
+`--timeout ms`, `--concurrency N`, `--docker`, `--claude`, `--suggest`.
 
 ## 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 69 servers measured, cost spans **1,700×**,
-from the 32-token `postgres` reference server to github's 54,422. The table below is a
+shows what you are choosing between: across the 81 servers measured, cost spans **1,700×**,
+from `postgres` at 32 tokens to `github` at 54,622. The table below is a
 sample of that range; the full range is in
 [results/leaderboard.md](results/leaderboard.md).
 
 | server | context cost | tools |
 |---|---:|---:|
-| github (official) | **54,422 tokens** | 44 |
+| github (official) | **54,622 tokens** | 44 |
 | xcodebuildmcp | 26,594 | 24 |
 | brave-search | 25,456 | 8 |
 | notion | 17,500 | 24 |
@@ -217,7 +233,7 @@ sample of that range; the full range is in
 | filesystem (reference) | 2,823 | 14 |
 | markitdown | 64 | 1 |
 
-*(69 of 82 popular servers measured, sweeps of 2026-08-18 and 2026-08-19 — full table in
+*(81 of 106 popular servers measured, each row dated by its own most recent 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.)*
@@ -252,7 +268,7 @@ exact launch command. Disputes reduce to a byte-level diff:
 
 ```bash
 npx -y mcp-context-cost verify results/github/measurement.json
-# OK github-mcp-server: 54422 tokens (o200k_base, methodology 1.0) — capture, hash, and count all agree
+# OK github-mcp-server: 54622 tokens (o200k_base, methodology 1.0) — capture, hash, and count all agree
 
 # or point it at a published measurement.json directly, no clone required
 npx -y mcp-context-cost verify --remote https://raw.githubusercontent.com/athakur3/mcp-context-cost/main/results/github/measurement.json
@@ -267,6 +283,12 @@ failed, `2` usage error.
 to the one that was published — which is exactly what `--claude` uses to decide whether it is
 allowed to show you a number.
 
+The number is also cross-checked against the other CLI that measures this,
+[`sd2k/mcp-tokens`](https://github.com/sd2k/mcp-tokens): the leaderboard's **mcp-tokens**
+column publishes its count beside ours wherever both tools saw the same tool set — same
+o200k encoding, differences documented, the divergence published rather than left to be
+discovered. Method: [CLI cross-check](docs/METHODOLOGY.md#cli-cross-check).
+
 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.
 
@@ -324,7 +346,10 @@ color bands are frozen against the observed distribution of the first full sweep
 
 ## Status
 
-Active. 46 of the 69 numbers come from the sweep of 2026-08-19 and 23 from 2026-08-18. Two
+Active. Every row carries the date of its own most recent measurement, and what the data
+says as a whole is written up, dated, in
+[The State of MCP Context Cost](https://athakur3.github.io/mcp-context-cost/state-of-mcp-context-cost)
+(September 2026). Two
 weekly jobs re-measure the set — the `memory` reference server on Mondays, and a rotating
 sixth of the list on Wednesdays, so every row comes round within six weeks. Read each row's
 date as the date it means, and don't take the cadence on trust — the build history is

package/dist/audit/audit.d.ts

@@ -1,4 +1,5 @@
 import { type DivergenceRun } from '../core/divergence.js';
+import { type ToolShapeBaseline, type ToolSuggestion } from '../core/tool-shape.js';
 import type { Measurement, MeasurementStatus, ToolMeasurement } from '../core/types.js';
 import type { ConfiguredServer, LoadedConfig } from './config.js';
 import { type DeferralVerdict, type ToolSearchEnv, type ToolSearchSource } from './deferral.js';
@@ -43,6 +44,19 @@ export interface TrimAdvice {
     recoverableTokens: number;
     recoverableShare: number;
 }
+/**
+ * `--suggest`: this config's tools placed in the measured set's tool-shape
+ * distribution. Only descriptions draw advice (schemas are functional surface;
+ * descriptions are prose every request carries), and only descriptions the
+ * baseline puts at or above the threshold percentile — a config where nothing
+ * is measurably unusual gets that said in those words, not advice invented to
+ * have some.
+ */
+export interface ConfigSuggestions {
+    /** Heaviest-recovery first. */
+    outOfDistribution: ToolSuggestion[];
+    checkedTools: number;
+}
 export interface AuditConfigResult {
     client: string;
     source: string;
@@ -54,6 +68,8 @@ export interface AuditConfigResult {
     skipped: AuditServerResult[];
     heaviestTools: HeaviestTool[];
     trimAdvice: TrimAdvice | null;
+    /** Present only when `--suggest` ran with a usable baseline. */
+    suggestions?: ConfigSuggestions;
     /**
      * Whether this client loads the total up front or defers it, and — when the
      * client decides that by a threshold — which side of it this stack is on.
@@ -128,6 +144,12 @@ export interface AuditReport {
         model: string;
         measuredAt: string;
     };
+    /** Which published tool-shape baseline `--suggest` read its percentiles from. */
+    toolShape?: {
+        generatedAt: string;
+        toolCount: number;
+        serverCount: number;
+    };
     /** Present only when a baseline report was supplied (`--baseline`). */
     diff?: AuditDiff;
     /** Present only when `--max-increase` was supplied alongside a baseline. */
@@ -160,6 +182,8 @@ export declare function buildReport(configs: LoadedConfig[], measured: Map<strin
     generatedAt?: string;
     /** Published `tools-delta/v1` run to join against (`--claude`); omit to skip the join. */
     divergence?: DivergenceRun | null;
+    /** Published `tool-shape/v1` baseline (`--suggest`); omit to skip suggestions. */
+    toolShape?: ToolShapeBaseline | null;
     /**
      * The audited machine's SHELL tool-search variables. Passed in rather than
      * read here so this stays pure and a report is reproducible from its

package/dist/audit/audit.js

@@ -14,10 +14,21 @@
  */
 import { METHODOLOGY_VERSION } from '../core/canonical.js';
 import { isCurrent } from '../core/divergence.js';
+import { SUGGEST_DESCRIPTION_PERCENTILE, suggestFor, } from '../core/tool-shape.js';
 import { evaluateDeferral, PUBLISHED_WIRE_TO_CLIENT_RATIO, SHELL_SOURCE, } from './deferral.js';
 import { formatDiff, formatGate } from './diff.js';
 export const DEFAULT_CONTEXT_WINDOW = 200_000;
 const TRIM_TOOL_COUNT = 3;
+function buildSuggestions(pool, baseline) {
+    const outOfDistribution = [];
+    for (const { server, t } of pool) {
+        const s = suggestFor(server, t, baseline);
+        if (s)
+            outOfDistribution.push(s);
+    }
+    outOfDistribution.sort((a, b) => b.approxRecoverableTokens - a.approxRecoverableTokens);
+    return { outOfDistribution, checkedTools: pool.length };
+}
 function buildTrimAdvice(sortedTools, totalTokens) {
     if (totalTokens <= 0 || sortedTools.length < 2)
         return null;
@@ -189,6 +200,7 @@ export function buildReport(configs, measured, opts = {}) {
         const ok = [];
         const skipped = [];
         const tools = [];
+        const shapePool = [];
         // Counted only for servers that put a number into the total: a twin that
         // failed to launch is already a floor, and adds nothing to a sum.
         let sharedHere = 0;
@@ -240,8 +252,11 @@ export function buildReport(configs, measured, opts = {}) {
                 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)
+            for (const t of m.tools) {
                 tools.push({ server: s.name, tool: t.name, tokens: t.tokens });
+                if (opts.toolShape)
+                    shapePool.push({ server: s.name, t });
+            }
         }
         const totalTokens = ok.reduce((a, s) => a + (s.tokens ?? 0), 0);
         const toolCount = ok.reduce((a, s) => a + (s.toolCount ?? 0), 0);
@@ -264,6 +279,7 @@ export function buildReport(configs, measured, opts = {}) {
             skipped,
             heaviestTools: tools.slice(0, 5),
             trimAdvice: buildTrimAdvice(tools, totalTokens),
+            suggestions: opts.toolShape ? buildSuggestions(shapePool, opts.toolShape) : undefined,
         };
         built.push(result);
         shared.set(result, sharedHere);
@@ -282,6 +298,13 @@ export function buildReport(configs, measured, opts = {}) {
     if (opts.divergence) {
         report.claudeDivergence = { model: opts.divergence.model, measuredAt: opts.divergence.measuredAt };
     }
+    if (opts.toolShape) {
+        report.toolShape = {
+            generatedAt: opts.toolShape.generatedAt,
+            toolCount: opts.toolShape.toolCount,
+            serverCount: opts.toolShape.serverCount,
+        };
+    }
     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.
@@ -617,6 +640,35 @@ export function formatReport(report) {
                 `(${names}) would recover ${n(cfg.trimAdvice.recoverableTokens)} tokens ` +
                 `(${pct(cfg.trimAdvice.recoverableShare)} of this config) — if your client supports per-tool filtering.`);
         }
+        if (cfg.suggestions) {
+            const sg = cfg.suggestions;
+            const base = report.toolShape
+                ? `baseline ${report.toolShape.generatedAt}: ${n(report.toolShape.toolCount)} tools across ` +
+                    `${report.toolShape.serverCount} measured servers`
+                : 'published baseline';
+            lines.push('');
+            if (sg.outOfDistribution.length === 0) {
+                lines.push(`  suggest: every description in this config sits inside the measured distribution — ` +
+                    `nothing the data can point at (${sg.checkedTools} tools against ${base}).`);
+            }
+            else {
+                lines.push(`  suggest — descriptions at or above the ${SUGGEST_DESCRIPTION_PERCENTILE}th percentile of ` +
+                    `measured tools (${base}):`);
+                const shown = sg.outOfDistribution.slice(0, 8);
+                for (const s of shown) {
+                    lines.push(`    ${s.server} · ${s.tool} — ${n(s.tokens)} tokens: description ${n(s.descriptionTokens)} ` +
+                        `(p${s.descriptionPercentile}), schema ${n(s.inputSchemaTokens)}`);
+                    lines.push(`      rewriting the description toward the measured median (${n(s.medianDescriptionTokens)}) ` +
+                        `would recover ≈${n(s.approxRecoverableTokens)} tokens on every request`);
+                }
+                if (sg.outOfDistribution.length > shown.length) {
+                    lines.push(`    …and ${sg.outOfDistribution.length - shown.length} more above the threshold.`);
+                }
+                const within = sg.checkedTools - sg.outOfDistribution.length;
+                lines.push(`    ${within} of ${sg.checkedTools} tools sit inside the distribution — ` +
+                    `no advice where nothing is measurably unusual.`);
+            }
+        }
         if (cfg.skipped.length) {
             lines.push('');
             lines.push('  not measured');

package/dist/audit/run.d.ts

@@ -1,10 +1,13 @@
 import type { Measurement } from '../core/types.js';
 import { type DivergenceRun } from '../core/divergence.js';
+import { type ToolShapeBaseline } from '../core/tool-shape.js';
 import { type AuditReport } from './audit.js';
 import { type ToolSearchEnv, type ToolSearchSource } from './deferral.js';
 import { type LoadedConfig } from './config.js';
 /** Where the published `tools-delta/v1` run lives when `--claude` doesn't override it. */
 export declare const DEFAULT_DIVERGENCE_URL = "https://raw.githubusercontent.com/athakur3/mcp-context-cost/main/results/divergence.json";
+/** Where the published `tool-shape/v1` baseline lives when `--suggest` doesn't override it. */
+export declare const DEFAULT_TOOL_SHAPE_URL = "https://raw.githubusercontent.com/athakur3/mcp-context-cost/main/results/tool-shape.json";
 export interface AuditOptions {
     /** Explicit config path(s); when empty, every known client location is tried. */
     configPaths?: string[];
@@ -19,6 +22,10 @@ export interface AuditOptions {
     claude?: boolean;
     /** Override the divergence.json source — mainly for tests and self-hosted mirrors. */
     divergenceUrl?: string;
+    /** Place this config's tools in the published tool-shape distribution and advise where the data can. */
+    suggest?: boolean;
+    /** Override the tool-shape.json source — mainly for tests and self-hosted mirrors. */
+    toolShapeUrl?: string;
     /**
      * The tool-search variables as this process's SHELL has them. Defaults to
      * this process's environment. Overridable so a test can state a machine
@@ -33,6 +40,11 @@ export interface AuditOptions {
     settings?: ToolSearchSource[];
     onProgress?: (name: string, done: number, total: number) => void;
 }
+/** Fetch and parse the published tool-shape baseline. Never throws: a failure is a report problem, not a crash. */
+export declare function fetchToolShape(url: string): Promise<{
+    baseline: ToolShapeBaseline | null;
+    problem?: string;
+}>;
 /** Fetch and parse the published divergence run. Never throws: a failure is a report problem, not a crash. */
 export declare function fetchDivergence(url: string): Promise<{
     run: DivergenceRun | null;

package/dist/audit/run.js

@@ -7,11 +7,27 @@
 import { homedir } from 'node:os';
 import { measureServer } from '../sweep/run.js';
 import { parseDivergence } from '../core/divergence.js';
+import { parseToolShapeBaseline } from '../core/tool-shape.js';
 import { buildReport, serverKey } from './audit.js';
 import { toolSearchEnv } from './deferral.js';
 import { configCandidates, loadConfigs, loadSettingsSources, settingsCandidates, } from './config.js';
 /** Where the published `tools-delta/v1` run lives when `--claude` doesn't override it. */
 export const DEFAULT_DIVERGENCE_URL = 'https://raw.githubusercontent.com/athakur3/mcp-context-cost/main/results/divergence.json';
+/** Where the published `tool-shape/v1` baseline lives when `--suggest` doesn't override it. */
+export const DEFAULT_TOOL_SHAPE_URL = 'https://raw.githubusercontent.com/athakur3/mcp-context-cost/main/results/tool-shape.json';
+/** Fetch and parse the published tool-shape baseline. Never throws: a failure is a report problem, not a crash. */
+export async function fetchToolShape(url) {
+    try {
+        const res = await fetch(url, { signal: AbortSignal.timeout(15_000) });
+        if (!res.ok)
+            return { baseline: null, problem: `tool shape: HTTP ${res.status} fetching ${url}` };
+        const baseline = parseToolShapeBaseline(await res.text());
+        return baseline ? { baseline } : { baseline: null, problem: `tool shape: malformed data at ${url}` };
+    }
+    catch (e) {
+        return { baseline: null, problem: `tool shape: failed to fetch ${url}: ${e.message}` };
+    }
+}
 /** Fetch and parse the published divergence run. Never throws: a failure is a report problem, not a crash. */
 export async function fetchDivergence(url) {
     try {
@@ -89,14 +105,24 @@ export async function runAudit(opts = {}) {
         divergence = fetched.run;
         divergenceProblem = fetched.problem;
     }
+    let toolShape = null;
+    let toolShapeProblem;
+    if (opts.suggest) {
+        const fetched = await fetchToolShape(opts.toolShapeUrl ?? DEFAULT_TOOL_SHAPE_URL);
+        toolShape = fetched.baseline;
+        toolShapeProblem = fetched.problem;
+    }
     const report = buildReport(configs, measured, {
         contextWindow: opts.contextWindow,
         budget: opts.budget,
         divergence,
+        toolShape,
         env: opts.env ?? toolSearchEnv(process.env),
         settings: opts.settings ?? discoverSettings(opts),
     });
     if (divergenceProblem)
         report.problems.push(divergenceProblem);
+    if (toolShapeProblem)
+        report.problems.push(toolShapeProblem);
     return report;
 }

package/dist/cli.js

@@ -99,8 +99,8 @@ function rejectUnknownFlags(cmd, argv, spec) {
 const [, , cmd, ...rest] = process.argv;
 if (cmd === 'audit') {
     rejectUnknownFlags('audit', rest, {
-        value: ['config', 'budget', 'baseline', 'max-increase', 'context', 'timeout', 'concurrency', 'divergence-url'],
-        boolean: ['json', 'docker', 'claude'],
+        value: ['config', 'budget', 'baseline', 'max-increase', 'context', 'timeout', 'concurrency', 'divergence-url', 'tool-shape-url'],
+        boolean: ['json', 'docker', 'claude', 'suggest'],
     });
     const argOf = (name) => {
         const i = rest.indexOf(`--${name}`);
@@ -159,18 +159,35 @@ if (cmd === 'audit') {
     }
     const { runAudit } = await import('./audit/run.js');
     const { formatReport } = await import('./audit/audit.js');
-    const report = await runAudit({
-        configPaths: all('config'),
-        budget,
-        contextWindow: numeric('context'),
-        timeoutMs: numeric('timeout'),
-        concurrency: numeric('concurrency'),
-        docker: rest.includes('--docker'),
-        claude: rest.includes('--claude'),
-        divergenceUrl: argOf('divergence-url'),
-        // Progress goes to stderr so `--json` stdout stays a single parseable object.
-        onProgress: json ? undefined : (name, done, total) => process.stderr.write(`  [${done}/${total}] ${name}\n`),
-    });
+    const { DockerHarnessFault } = await import('./sweep/docker.js');
+    let report;
+    try {
+        report = await runAudit({
+            configPaths: all('config'),
+            budget,
+            contextWindow: numeric('context'),
+            timeoutMs: numeric('timeout'),
+            concurrency: numeric('concurrency'),
+            docker: rest.includes('--docker'),
+            claude: rest.includes('--claude'),
+            divergenceUrl: argOf('divergence-url'),
+            suggest: rest.includes('--suggest'),
+            toolShapeUrl: argOf('tool-shape-url'),
+            // Progress goes to stderr so `--json` stdout stays a single parseable object.
+            onProgress: json ? undefined : (name, done, total) => process.stderr.write(`  [${done}/${total}] ${name}\n`),
+        });
+    }
+    catch (e) {
+        // Docker failing as docker means every measurement through it would be a
+        // statement about this machine, so the audit refuses whole rather than
+        // reporting each server as broken.
+        if (e instanceof DockerHarnessFault) {
+            console.error(`audit --docker cannot answer for this machine: ${e.message}`);
+            console.error('Fix Docker here, or run without --docker.');
+            process.exit(1);
+        }
+        throw e;
+    }
     if (report.configs.length === 0) {
         const where = report.problems.length ? `\n${report.problems.map((p) => `  ${p}`).join('\n')}` : '';
         const empty = report.emptyConfigs ?? [];

package/dist/core/cross-check.d.ts

@@ -0,0 +1,93 @@
+import type { Measurement } from './types.js';
+/** Method identifier, versioned independently of METHODOLOGY_VERSION. */
+export declare const CROSS_CHECK_METHOD = "cli-cross-check/v1";
+/** The CLI being cross-checked against, and the release this run pins. */
+export declare const CROSS_CHECK_CLI = "sd2k/mcp-tokens";
+export declare const CROSS_CHECK_CLI_VERSION = "v0.2.5";
+/**
+ * The exact analyze invocation, recorded in every run. `--model gpt-4o` is
+ * load-bearing: tiktoken-rs maps it to o200k_base, and without a model the CLI
+ * falls back to cl100k_base — a systematic difference that would swamp the one
+ * being measured (spec/upstream-notes.md, finding 1).
+ */
+export declare const CROSS_CHECK_CLI_ARGS: readonly ['analyze', '--provider', 'tiktoken', '--model', 'gpt-4o', '--format', 'json'];
+export interface CrossCheckRow {
+    /** o200k count of our fresh canonical capture from this run — the headline. */
+    ourTokens: number;
+    /**
+     * o200k count of the same capture's name/description/input_schema
+     * projection — what the CLI's structs actually model, and therefore the
+     * number its count is compared against.
+     */
+    ourMappedTokens: number;
+    /** The CLI's `.tools.total` for the same server, launched by the CLI itself. */
+    cliTokens: number;
+    ourToolCount: number;
+    cliToolCount: number;
+    /** Both tools saw the same tool names (order-insensitive) — the comparison is between like and like. */
+    toolSetMatches: boolean;
+    /**
+     * Our fresh measurement listed dynamically (tools/list differed between its
+     * own two captures). The CLI's launch is a third capture, so even with
+     * matching names its residual mixes content drift with counter disagreement
+     * — recorded, never printed.
+     */
+    dynamic: boolean;
+    /** canonicalSha256 of our capture in this run; null when our measurement failed. */
+    capturedSha256: string | null;
+    /** Set when either side could not produce a number; nothing is published from the row. */
+    error?: string;
+}
+export interface CrossCheckRun {
+    method: string;
+    cli: string;
+    cliVersion: string;
+    /** The analyze invocation, verbatim, so the encoding choice is auditable. */
+    cliArgs: string[];
+    /** UTC day the run was taken (YYYY-MM-DD). */
+    measuredAt: string;
+    isolation: string;
+    servers: Record<string, CrossCheckRow>;
+}
+export declare function parseCrossCheck(text: string): CrossCheckRun | null;
+/** What the CLI's JSON report contributes to a row. */
+export interface CliReport {
+    total: number;
+    count: number;
+    names: string[];
+}
+/**
+ * Read the CLI's `--format json` report. The report is that CLI's contract, not
+ * ours, so this is deliberately narrow: `.tools.total` (the number the CLI's
+ * own action publishes), `.tools.count`, and the per-tool names — and a report
+ * that does not carry a usable total is a named problem, never a zero.
+ */
+export declare function parseCliReport(text: string): {
+    report?: CliReport;
+    problem?: string;
+};
+/** Order-insensitive equality of the two tool-name lists, repeats included. */
+export declare function sameToolSet(ours: string[], theirs: string[]): boolean;
+/**
+ * Build a row from our fresh measurement and the CLI's report. The caller
+ * decides whether to run the CLI at all; a failed side arrives here as an
+ * `error`, and the row keeps whatever the other side established.
+ */
+export declare function toCrossCheckRow(m: Measurement, cli: {
+    report?: CliReport;
+    problem?: string;
+}): CrossCheckRow;
+/**
+ * A row is only printable while it compares like with like: no error on either
+ * side, the same tool names seen by both tools, and our capture still the one
+ * published — the exact staleness rule the claude column follows.
+ */
+export declare function isComparable(row: CrossCheckRow | undefined, canonicalSha256: string | null): row is CrossCheckRow;
+/**
+ * Signed divergence of the CLI's count from our count of the projection it
+ * models, in percent. Against the mapped number and not the headline: the gap
+ * to the headline is field selection, published separately per server, and
+ * folding it in here would bury the number this column exists to check —
+ * whether two independent counters agree on the fields both count.
+ */
+export declare function divergencePct(row: CrossCheckRow): number | null;