mcp-context-cost 0.13.0 → 0.13.2

package/README.md

@@ -126,7 +126,7 @@ costs **more** than loading the definitions would.
 
 Three things the report will not do: it will not convert between units silently (in
 threshold mode the stack is compared as a range, because the audit counts wire bytes and the
-threshold is counted in what the client sends to the API — measured at 0.20×–1.92× across 23
+threshold is counted in what the client sends to the API — measured at 0.19×–1.93× across 86
 servers); it will not claim a posture the machine did not state readably, which is four
 refusals and not one — when two places set the same variable to different values, when a
 settings file exists and cannot be read, when the place that would decide sets the variable
@@ -204,8 +204,8 @@ 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 23 rows — the measured servers it covered when it last ran —
-and [results/leaderboard.md](results/leaderboard.md) prints a claude number for the 15 that
+when it doesn't. The run holds 87 rows — the measured servers it covered when it last ran —
+and [results/leaderboard.md](results/leaderboard.md) prints a claude number for the 86 that
 still match today and silence for the rest. Most installs will show a mix:
 
 ```
@@ -218,11 +218,11 @@ Add `--suggest` to place each of your tools in the measured set's tool-shape dis
 ([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:
+1,430 measured tools:
 
 ```
   suggest — descriptions at or above the 90th percentile of measured tools
-  (baseline 2026-09-03: 1,150 tools across 81 measured servers):
+  (baseline 2026-09-05: 1,430 tools across 87 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.
@@ -256,7 +256,7 @@ Flags: `--json` (full report on stdout, progress on stderr), `--budget N`,
 
 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 86 servers measured, cost spans **1,700×**,
+shows what you are choosing between: across the 87 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).
@@ -271,7 +271,7 @@ sample of that range; the full range is in
 | filesystem (reference) | 2,823 | 14 |
 | markitdown | 64 | 1 |
 
-*(86 of 106 popular servers measured, each row dated by its own most recent sweep — full table in
+*(87 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.)*
@@ -299,7 +299,7 @@ now measured against a pinned model and published beside the badge, and they do
 
 | server | badge (o200k) | Claude (`claude-opus-5`) | |
 |---|---:|---:|---|
-| github | 54,622 | **—** | most of the capture is `annotations`/`outputSchema` metadata Claude never sees |
+| github | 54,622 | **18,728** | most of the capture is `annotations`/`outputSchema` metadata Claude never sees |
 | notion | 17,500 | **33,560** | almost no metadata to drop, so the tokenizer difference dominates |
 
 So the heaviest server on the badge is not the heaviest server on Claude. Per-server

package/dist/audit/deferral.d.ts

@@ -219,24 +219,48 @@ export declare function resolveToolSearchSources(sources: ToolSearchSource[]): R
  * threshold is a share of the context window measured in what the client
  * actually sends to the API — the name/description/input_schema projection,
  * counted by Anthropic's tokenizer, plus the tool framework overhead. Those are
- * not the same number and the gap is not small: across the published
- * divergence run it runs from 0.20× to 1.92×, so a single stack total maps to a
- * range roughly ten times as wide as itself. Comparing the wire number directly
- * against the threshold understates the deferrable side for schema-heavy
- * servers and overstates it for metadata-heavy ones, in one direction each.
+ * not the same number and the gap is not small; the fields below carry it, and
+ * the pages state it from the run rather than from here. Comparing the wire
+ * number directly against the threshold understates the deferrable side for
+ * schema-heavy servers and overstates it for metadata-heavy ones, in one
+ * direction each.
+ *
+ * The band is **marginal**: it converts a server's own bytes and excludes the
+ * tool framework overhead, which `fixedOverhead` carries separately because the
+ * API charges it once per request however many servers are attached. Keeping
+ * them together was wrong in a way that stayed invisible while the divergence
+ * run sampled the heavy end — on a 54,000-token server a fixed 328 is noise. On
+ * 2026-09-05 the run widened to every measured server and reached `postgres` at
+ * 32 tokens on the wire, where 328 of its 348 Claude tokens *are* the overhead:
+ * a per-server ratio of 10.88× that says nothing about converting bytes. Folded
+ * into the band it took the published upper bound from 1.92× to 10.88× and made
+ * the audit refuse threshold questions it had been answering correctly. Held
+ * apart, the band across the same 86 rows is 0.19×–1.93× — which is where it
+ * already was, from a sample a quarter the size.
  */
 export interface WireToClientRatio {
     low: number;
     high: number;
+    /**
+     * Tokens the tool framework costs once per request, whatever is attached.
+     * Added to a stack a single time; never multiplied by anything.
+     */
+    fixedOverhead: number;
     /** How many servers the band was measured across, for the printed caveat. */
     servers: number;
     /** The run it came from, so a reader can date it. */
     source: string;
 }
 /**
- * The band as published in this repository's own `results/divergence.json`
- * (claude-opus-5, 2026-08-19, 20 servers). Used when no divergence run was
- * supplied; `--claude` recomputes it from the run it fetched.
+ * The band as published in this repository's own `results/divergence.json`.
+ * Used when no divergence run was supplied; `--claude` recomputes it from the
+ * run it fetched.
+ *
+ * The model, the date and the count deliberately are not restated here. This
+ * docblock said `(claude-opus-5, 2026-08-19, 20 servers)` while the field below
+ * read 23 and the run on disk held 24 — prose beside a number, drifting from
+ * it, which is the same failure this constant's own guard exists to catch one
+ * level down. The fields are the record; `source` dates them.
  */
 export declare const PUBLISHED_WIRE_TO_CLIENT_RATIO: WireToClientRatio;
 /** Derive the band from a supplied divergence run, falling back to the published one. */

package/dist/audit/deferral.js

@@ -222,13 +222,20 @@ export function resolveToolSearchSources(sources) {
     return { ...resolved, source: resolved.readFromMachine ? (base?.source ?? null) : null };
 }
 /**
- * The band as published in this repository's own `results/divergence.json`
- * (claude-opus-5, 2026-08-19, 20 servers). Used when no divergence run was
- * supplied; `--claude` recomputes it from the run it fetched.
+ * The band as published in this repository's own `results/divergence.json`.
+ * Used when no divergence run was supplied; `--claude` recomputes it from the
+ * run it fetched.
+ *
+ * The model, the date and the count deliberately are not restated here. This
+ * docblock said `(claude-opus-5, 2026-08-19, 20 servers)` while the field below
+ * read 23 and the run on disk held 24 — prose beside a number, drifting from
+ * it, which is the same failure this constant's own guard exists to catch one
+ * level down. The fields are the record; `source` dates them.
  */
 export const PUBLISHED_WIRE_TO_CLIENT_RATIO = {
-    low: 0.2,
-    high: 1.92,
+    low: 0.19,
+    high: 1.93,
+    fixedOverhead: 328,
     // A snapshot of the run this package was cut against, which is what `source`
     // below says it is — the installed package has no `results/` to read, so when
     // a live run is supplied `wireToClientRatio` uses that instead and this is
@@ -242,27 +249,42 @@ export const PUBLISHED_WIRE_TO_CLIENT_RATIO = {
     // every measured server on 2026-09-05, with nothing comparing the two. The
     // band had not moved — the servers added sat inside it — which is exactly how
     // a number like this goes wrong quietly.
-    servers: 23,
+    //
+    // The widening then moved it by a hair rather than by the fivefold the first
+    // reading suggested: 0.20×–1.92× over 23 servers, 0.19×–1.93× over 86. That a
+    // quarter of the set predicted the whole of it is the interesting part, and it
+    // is only true of the marginal band — see the interface above for what folding
+    // the fixed overhead in did to the same numbers.
+    servers: 86,
     source: 'the published claude-opus-5 divergence run',
 };
 /** Derive the band from a supplied divergence run, falling back to the published one. */
 export function wireToClientRatio(run) {
     if (!run)
         return PUBLISHED_WIRE_TO_CLIENT_RATIO;
+    // `probeDelta` is the run's own reading of the fixed overhead: one tiny tool
+    // attached, minus the same request with none. An upper bound, and the only
+    // measurement of it there is. A run that does not carry one converts as it
+    // always did rather than guessing at a correction.
+    const fixedOverhead = typeof run.probeDelta === 'number' && run.probeDelta > 0 ? run.probeDelta : 0;
     let low = Infinity;
     let high = -Infinity;
     let servers = 0;
     for (const row of Object.values(run.servers)) {
         if (!row || row.error || typeof row.claudeDelta !== 'number' || !(row.o200kFull > 0))
             continue;
-        const ratio = row.claudeDelta / row.o200kFull;
+        const ratio = (row.claudeDelta - fixedOverhead) / row.o200kFull;
+        // A server whose entire Claude cost is the overhead says nothing about
+        // converting bytes, and a negative ratio is not a conversion at all.
+        if (!(ratio > 0))
+            continue;
         low = Math.min(low, ratio);
         high = Math.max(high, ratio);
         servers++;
     }
     if (servers === 0)
         return PUBLISHED_WIRE_TO_CLIENT_RATIO;
-    return { low, high, servers, source: `the ${run.measuredAt} ${run.model} divergence run` };
+    return { low, high, fixedOverhead, servers, source: `the ${run.measuredAt} ${run.model} divergence run` };
 }
 /** Clients this tool discovers that have no default deferral on record. */
 const NO_DEFERRAL_ON_RECORD = new Set(['claude-desktop', 'cursor', 'vscode', 'windsurf']);
@@ -299,6 +321,15 @@ function estimate(servers, ratio) {
             estimated++;
         }
     }
+    // Once per request, not once per server — the band is marginal precisely so
+    // that this is added here and exactly one time. A published Anthropic count
+    // already carries a copy of it, which is why a stack holding one is left
+    // alone: adding another would be the same double count in the other
+    // direction.
+    if (exact === 0 && estimated > 0) {
+        low += ratio.fixedOverhead;
+        high += ratio.fixedOverhead;
+    }
     return { low: Math.round(low), high: Math.round(high), exact, estimated };
 }
 /**

package/dist/core/divergence.d.ts

@@ -67,5 +67,25 @@ export declare function claudeRatio(row: DivergenceRow): number | null;
  * caveat: a wrong number next to a fresh badge is worse than no number.
  */
 export declare function isCurrent(row: DivergenceRow | undefined, canonicalSha256: string | null): row is DivergenceRow;
+/**
+ * Drop rows that have stopped describing the capture they were computed from.
+ *
+ * The companion to `isCurrent`, one layer earlier. `isCurrent` stops a stale row
+ * reaching a page; this stops it being carried forward in the first place. A
+ * selection preserves every row it does not measure, and a re-sweep moves the
+ * capture of every server it re-measures — so between the two, a row outside the
+ * selection can go on being merged forward long after the capture it describes
+ * is gone. Eight of twenty-four rows had reached that state by 2026-09-05, and
+ * nothing said so: the cells were hidden, so the file looked complete while the
+ * count of rows had stopped meaning the count of usable rows.
+ *
+ * `captureSha` returns the canonical hash of what is on disk today, or undefined
+ * when there is no capture at all — which is also a reason to drop, because a
+ * row about a server that no longer measures is a row nothing can confirm.
+ */
+export declare function dropStaleRows(servers: Record<string, DivergenceRow>, captureSha: (name: string) => string | undefined): {
+    kept: Record<string, DivergenceRow>;
+    dropped: string[];
+};
 /** Parse results/divergence.json; anything malformed yields null, never throws. */
 export declare function parseDivergence(text: string): DivergenceRun | null;

package/dist/core/divergence.js

@@ -86,6 +86,33 @@ export function isCurrent(row, canonicalSha256) {
         return false;
     return !!canonicalSha256 && row.capturedSha256 === canonicalSha256;
 }
+/**
+ * Drop rows that have stopped describing the capture they were computed from.
+ *
+ * The companion to `isCurrent`, one layer earlier. `isCurrent` stops a stale row
+ * reaching a page; this stops it being carried forward in the first place. A
+ * selection preserves every row it does not measure, and a re-sweep moves the
+ * capture of every server it re-measures — so between the two, a row outside the
+ * selection can go on being merged forward long after the capture it describes
+ * is gone. Eight of twenty-four rows had reached that state by 2026-09-05, and
+ * nothing said so: the cells were hidden, so the file looked complete while the
+ * count of rows had stopped meaning the count of usable rows.
+ *
+ * `captureSha` returns the canonical hash of what is on disk today, or undefined
+ * when there is no capture at all — which is also a reason to drop, because a
+ * row about a server that no longer measures is a row nothing can confirm.
+ */
+export function dropStaleRows(servers, captureSha) {
+    const kept = {};
+    const dropped = [];
+    for (const [name, row] of Object.entries(servers)) {
+        if (row.capturedSha256 && row.capturedSha256 === captureSha(name))
+            kept[name] = row;
+        else
+            dropped.push(name);
+    }
+    return { kept, dropped };
+}
 /** Parse results/divergence.json; anything malformed yields null, never throws. */
 export function parseDivergence(text) {
     let run;

package/dist/sweep/client.d.ts

@@ -33,16 +33,43 @@ export interface WireCapture {
  * Noise is only dropped while something else survives. A package that fails
  * *inside* npm (EBADPLATFORM, a failed postinstall) has npm's own lines as its
  * only evidence, and a server whose whole output is a stack keeps the stack.
+ *
+ * `required` is the phrase a declared entry's published status depends on
+ * (`notApplicable.evidence` in servers.yaml). Everything else here is a budget
+ * decision — how much of a long failure is worth publishing — but this one is
+ * not. The entry says "this failure is the harness's, and here is the sentence
+ * that proves it", and `notApplicableReason` re-reads that sentence out of what
+ * survives: elide it and the declaration turns itself off, the row reverts to
+ * `startup-failure`, and this project publishes that someone else's working
+ * software is broken. The evidence is therefore kept whatever the budget, and
+ * everything else competes for what is left — the rule the old one lacked, and
+ * the reason it depended on how much the server happened to print.
+ */
+export declare function evidenceTail(stderr: string, limit?: number, required?: string): string;
+/**
+ * Cut a record's notes to `limit` without cutting away the evidence its own
+ * status rests on.
+ *
+ * The same rule as `evidenceTail`, one layer up and for a different reason. The
+ * classifier reads the message *before* this cut, so this one cannot change a
+ * published status — it can only leave a record asserting `not-applicable` with
+ * the sentence that justifies it deleted, which is a claim published without its
+ * evidence. `windows-mcp` sits at exactly the cap today, so the margin here is
+ * one character of growth in somebody else's error message.
  */
-export declare function evidenceTail(stderr: string, limit?: number): string;
+export declare function clampNotes(text: string, limit: number, required?: string): string;
 export declare class McpStdioClient {
+    /** Phrase this entry's declared status depends on — see `evidenceTail`. */
+    private keepEvidence?;
     private child;
     private buffer;
     private nextId;
     private pending;
     private stderrChunks;
     private exited;
-    constructor(command: string, args: string[], env: Record<string, string | undefined>);
+    constructor(command: string, args: string[], env: Record<string, string | undefined>, 
+    /** Phrase this entry's declared status depends on — see `evidenceTail`. */
+    keepEvidence?: string | undefined);
     private onData;
     private send;
     private deadReason;
@@ -61,6 +88,7 @@ export declare function captureTools(spec: string | {
 }, opts?: {
     timeoutMs?: number;
     env?: Record<string, string>;
+    keepEvidence?: string;
 }): Promise<WireCapture>;
 /** Shell-free command splitting: honors single/double quotes, no expansion. */
 export declare function splitCommand(line: string): string[];

package/dist/sweep/client.js

@@ -6,6 +6,8 @@
  */
 import { spawn } from 'node:child_process';
 const PROTOCOL_VERSION = '2025-06-18';
+/** How an elided middle is marked, in every layout here. */
+const ELISION = ' […] ';
 /**
  * The part of a dead server's stderr worth keeping as evidence.
  *
@@ -26,11 +28,24 @@ const PROTOCOL_VERSION = '2025-06-18';
  * Noise is only dropped while something else survives. A package that fails
  * *inside* npm (EBADPLATFORM, a failed postinstall) has npm's own lines as its
  * only evidence, and a server whose whole output is a stack keeps the stack.
+ *
+ * `required` is the phrase a declared entry's published status depends on
+ * (`notApplicable.evidence` in servers.yaml). Everything else here is a budget
+ * decision — how much of a long failure is worth publishing — but this one is
+ * not. The entry says "this failure is the harness's, and here is the sentence
+ * that proves it", and `notApplicableReason` re-reads that sentence out of what
+ * survives: elide it and the declaration turns itself off, the row reverts to
+ * `startup-failure`, and this project publishes that someone else's working
+ * software is broken. The evidence is therefore kept whatever the budget, and
+ * everything else competes for what is left — the rule the old one lacked, and
+ * the reason it depended on how much the server happened to print.
  */
-export function evidenceTail(stderr, limit = 600) {
-    const withoutNoise = drop(stderr, (l) => /^npm (warn|notice)\b/.test(l));
-    const withoutFrames = drop(withoutNoise, (l) => /^at\s/.test(l));
-    return bothEnds(withoutFrames, limit);
+export function evidenceTail(stderr, limit = 600, required) {
+    const needle = required ? required.toLowerCase() : undefined;
+    const protect = (l) => needle !== undefined && l.toLowerCase().includes(needle);
+    const withoutNoise = drop(stderr, (l) => /^npm (warn|notice)\b/.test(l), protect);
+    const withoutFrames = drop(withoutNoise, (l) => /^at\s/.test(l), protect);
+    return bothEnds(withoutFrames, limit, needle);
 }
 /**
  * Keep the start and the end, eliding the middle.
@@ -47,10 +62,23 @@ export function evidenceTail(stderr, limit = 600) {
  * and the middle is what goes. The split leans towards the head because a
  * message that precedes its own noise is the more common shape here.
  */
-function bothEnds(text, limit) {
+function bothEnds(text, limit, needle) {
+    const kept = bothEndsPlain(text, limit);
+    if (needle === undefined)
+        return kept;
+    // Only pay for the anchored layout when the ordinary one lost the phrase and
+    // the raw text actually had it. An entry whose evidence never appeared is a
+    // declaration that does not hold, and must keep failing as one.
+    if (kept.toLowerCase().includes(needle))
+        return kept;
+    if (!text.toLowerCase().includes(needle))
+        return kept;
+    return aroundRequired(text, limit, needle);
+}
+function bothEndsPlain(text, limit) {
     if (text.length <= limit)
         return text;
-    const elision = '\n […] \n';
+    const elision = `\n${ELISION}\n`;
     const budget = Math.max(0, limit - elision.length);
     const lines = text.split('\n');
     // Whole lines only: a boundary cut mid-word ("ool/prompt change") reads as
@@ -83,23 +111,119 @@ function bothEnds(text, limit) {
         return text.slice(0, budget) + elision;
     return `${headText}${elision}${tail.out.join('\n')}`;
 }
-/** Drop matching lines, keeping the input whole if that would leave nothing. */
-function drop(text, isNoise) {
+/**
+ * Keep the line the declared evidence is on, then spend what is left on context.
+ *
+ * Head before tail, the same lean `bothEndsPlain` takes and for the same reason:
+ * an explanation usually precedes its own aftermath. The elisions are marked, so
+ * a reader of the record can see that something was dropped around the sentence
+ * that was not.
+ */
+function aroundRequired(text, limit, needle) {
+    const lines = text.split('\n');
+    const k = lines.findIndex((l) => l.toLowerCase().includes(needle));
+    // Both elisions and the newlines joining at most five chunks, reserved before
+    // the anchor is sized: the budget is a published-record limit, and a layout
+    // that keeps the evidence by overrunning it has only moved the problem.
+    const reserve = 2 * ELISION.length + 4;
+    const anchor = windowAround(lines[k], needle, Math.max(needle.length, limit - reserve));
+    let budget = limit - anchor.length - reserve;
+    const head = [];
+    for (let i = 0; i < k; i++) {
+        const cost = lines[i].length + 1;
+        if (cost > budget)
+            break;
+        head.push(lines[i]);
+        budget -= cost;
+    }
+    const tail = [];
+    for (let i = lines.length - 1; i > k; i--) {
+        const cost = lines[i].length + 1;
+        if (cost > budget)
+            break;
+        tail.unshift(lines[i]);
+        budget -= cost;
+    }
+    const chunks = [];
+    if (head.length)
+        chunks.push(head.join('\n'));
+    if (head.length < k)
+        chunks.push(ELISION);
+    chunks.push(anchor);
+    if (tail.length < lines.length - 1 - k)
+        chunks.push(ELISION);
+    if (tail.length)
+        chunks.push(tail.join('\n'));
+    return chunks.join('\n');
+}
+/**
+ * A single line that alone overruns the budget, kept as a window around the
+ * match rather than from its start — a structured log puts the whole message on
+ * one line, and the phrase that matters can sit anywhere in it.
+ */
+function windowAround(line, needle, limit) {
+    if (line.length <= limit)
+        return line;
+    const at = line.toLowerCase().indexOf(needle);
+    const lead = Math.max(0, Math.floor((limit - needle.length) / 2));
+    const start = Math.max(0, Math.min(at - lead, line.length - limit));
+    return line.slice(start, start + limit);
+}
+/**
+ * Cut a record's notes to `limit` without cutting away the evidence its own
+ * status rests on.
+ *
+ * The same rule as `evidenceTail`, one layer up and for a different reason. The
+ * classifier reads the message *before* this cut, so this one cannot change a
+ * published status — it can only leave a record asserting `not-applicable` with
+ * the sentence that justifies it deleted, which is a claim published without its
+ * evidence. `windows-mcp` sits at exactly the cap today, so the margin here is
+ * one character of growth in somebody else's error message.
+ */
+export function clampNotes(text, limit, required) {
+    if (text.length <= limit)
+        return text;
+    const plain = text.slice(0, limit);
+    if (!required)
+        return plain;
+    const needle = required.toLowerCase();
+    if (plain.toLowerCase().includes(needle))
+        return plain;
+    const at = text.toLowerCase().indexOf(needle);
+    if (at < 0)
+        return plain;
+    const room = Math.max(0, limit - ELISION.length);
+    const width = Math.min(room, Math.max(needle.length, Math.floor(room / 2)));
+    const start = Math.max(0, Math.min(at - Math.floor((width - needle.length) / 2), text.length - width));
+    return text.slice(0, Math.max(0, room - width)) + ELISION + text.slice(start, start + width);
+}
+/**
+ * Drop matching lines, keeping the input whole if that would leave nothing.
+ *
+ * `isProtected` outranks `isNoise`: safari-mcp declares `EBADPLATFORM`, which npm
+ * prints on a line of its own, and a filter that reaches it first would delete
+ * the evidence before any budget was even applied.
+ */
+function drop(text, isNoise, isProtected = () => false) {
     const kept = text
         .split('\n')
-        .filter((l) => !isNoise(l.trim()))
+        .filter((l) => isProtected(l.trim()) || !isNoise(l.trim()))
         .join('\n')
         .trim();
     return kept || text.trim();
 }
 export class McpStdioClient {
+    keepEvidence;
     child;
     buffer = '';
     nextId = 1;
     pending = new Map();
     stderrChunks = [];
     exited;
-    constructor(command, args, env) {
+    constructor(command, args, env, 
+    /** Phrase this entry's declared status depends on — see `evidenceTail`. */
+    keepEvidence) {
+        this.keepEvidence = keepEvidence;
         this.child = spawn(command, args, {
             env: { ...env },
             stdio: ['pipe', 'pipe', 'pipe'],
@@ -123,7 +247,7 @@ export class McpStdioClient {
                 resolve();
             });
             this.child.on('exit', (code) => {
-                const tail = evidenceTail(this.stderrTail);
+                const tail = evidenceTail(this.stderrTail, undefined, this.keepEvidence);
                 this.deadReason = `server exited (code ${code})${tail ? `; stderr tail: ${tail}` : ''}`;
                 for (const p of this.pending.values())
                     p.reject(new Error(this.deadReason));
@@ -185,7 +309,7 @@ export class McpStdioClient {
                 // without this a timed-out record carries no evidence at all — it says
                 // only that we waited. What the server managed to print before it
                 // stopped answering is usually the whole explanation.
-                const tail = evidenceTail(this.stderrTail);
+                const tail = evidenceTail(this.stderrTail, undefined, this.keepEvidence);
                 reject(new Error(`timeout after ${timeoutMs}ms waiting for ${method}${tail ? `; stderr tail: ${tail}` : ''}`));
             }, timeoutMs);
             this.pending.set(id, {
@@ -222,11 +346,7 @@ export class McpStdioClient {
 export async function captureTools(spec, opts = {}) {
     const timeoutMs = opts.timeoutMs ?? 60_000;
     const [cmd, ...args] = typeof spec === 'string' ? splitCommand(spec) : [spec.command, ...spec.argv];
-    const client = new McpStdioClient(cmd, args, {
-        PATH: process.env.PATH,
-        HOME: process.env.HOME,
-        ...opts.env,
-    });
+    const client = new McpStdioClient(cmd, args, { PATH: process.env.PATH, HOME: process.env.HOME, ...opts.env }, opts.keepEvidence);
     try {
         const init = await client.request('initialize', {
             protocolVersion: PROTOCOL_VERSION,

package/dist/sweep/published-stats.d.ts

@@ -49,6 +49,20 @@ export interface PublishedStats {
         /** claudeDelta / o200kFull across the run's rows that carry a number. */
         ratioMin: number;
         ratioMax: number;
+        /** How many rows produced the band — see where it is set. */
+        ratioServers: number;
+    };
+    /**
+     * The published tool-shape baseline, which README quotes twice — once in
+     * prose and once inside the `--suggest` sample output. Both were hand-written
+     * and `STATIC_COUNTS` excused them as regen-maintained, which was not true of
+     * either: the file said 1,430 tools across 87 servers while the page said
+     * 1,150 across 81, and every test passed.
+     */
+    toolShape: {
+        toolCount: number;
+        serverCount: number;
+        generatedAt: string;
     };
     deferralCostlierCount: number;
     /** Servers whose most recent cost movement went up / down (cost-regression/v1). */

package/dist/sweep/published-stats.js

@@ -25,9 +25,10 @@
  * never a silent skip), and only the slots are ever rewritten — spliced in
  * place, so the page's own line wrapping survives.
  */
-import { readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { DEFAULT_CONTEXT_WINDOW } from '../audit/audit.js';
+import { wireToClientRatio } from '../audit/deferral.js';
 import { fieldSelectionShare, isCurrent } from '../core/divergence.js';
 import { sessionStartLoad } from '../core/session-start.js';
 import { isGood } from './harness-guard.js';
@@ -106,10 +107,13 @@ export function computePublishedStats(entries, root = process.cwd()) {
     const shares = currentRows
         .map(([, r]) => fieldSelectionShare(r))
         .filter((s) => s !== null && s >= 0);
-    const ratios = currentRows
-        .filter(([, r]) => typeof r.claudeDelta === 'number' && r.claudeDelta > 0 && r.o200kFull > 0)
-        .map(([, r]) => r.claudeDelta / r.o200kFull);
-    if (shares.length === 0 || ratios.length === 0) {
+    // Asked of the same function the audit converts with, rather than recomputed
+    // here. Two derivations of one band is how a page ends up describing a
+    // conversion the tool does not perform — and these two differed twice over:
+    // this one worked from the rows whose capture is still current, and it divided
+    // by a delta that still had the fixed tool overhead in it.
+    const band = wireToClientRatio(div);
+    if (shares.length === 0 || band.servers === 0) {
         throw new Error('no current divergence row — METHODOLOGY states ranges over them; run `npm run divergence`');
     }
     // The exemplar METHODOLOGY names for the field-selection effect is whichever
@@ -128,7 +132,15 @@ export function computePublishedStats(entries, root = process.cwd()) {
     if (!githubRow?.m || typeof githubRow.m.totalTokens !== 'number') {
         throw new Error('README quotes `verify` on results/github, which has no current measurement');
     }
+    const shape = (() => {
+        const p = join(root, 'results', 'tool-shape.json');
+        if (!existsSync(p))
+            throw new Error('results/tool-shape.json is missing — README states its numbers');
+        const j = JSON.parse(readFileSync(p, 'utf8'));
+        return { toolCount: j.toolCount, serverCount: j.serverCount, generatedAt: j.generatedAt };
+    })();
     return {
+        toolShape: shape,
         candidateTotal: rows.length,
         measuredCount: measured.length,
         max,
@@ -146,8 +158,13 @@ export function computePublishedStats(entries, root = process.cwd()) {
             widest: { server: widest[0], full: widest[1].o200kFull, mapped: widest[1].o200kMapped },
             shareMin: Math.min(...shares),
             shareMax: Math.max(...shares),
-            ratioMin: Math.min(...ratios),
-            ratioMax: Math.max(...ratios),
+            ratioMin: band.low,
+            ratioMax: band.high,
+            // What produced the band, never `runSize`: a row can sit in the run and
+            // contribute nothing to it — `gitlab` is there with an API error and a
+            // zero delta. "Across {runSize} servers" states the band was measured over
+            // one more server than measured it.
+            ratioServers: band.servers,
         },
         deferralCostlierCount: costlier.length,
         movement: { grew: movement.grew, shrank: movement.shrank },
@@ -223,7 +240,21 @@ export const PAGE_CLAIMS = [
         // page-number guard: three numbers written by hand beside the two
         // sentences regen already kept true.
         template: 'measured at {f}×–{f}× across {n} servers)',
-        values: (s) => [s.claude.ratioMin.toFixed(2), s.claude.ratioMax.toFixed(2), fmt(s.claude.runSize)],
+        values: (s) => [s.claude.ratioMin.toFixed(2), s.claude.ratioMax.toFixed(2), fmt(s.claude.ratioServers)],
+    },
+    {
+        file: 'README.md',
+        id: 'tool-shape:prose',
+        template: 'only descriptions at or above the 90th percentile of the {n} measured tools:',
+        values: (s) => [fmt(s.toolShape.toolCount)],
+    },
+    {
+        file: 'README.md',
+        id: 'tool-shape:sample-header',
+        // Inside the `--suggest` sample block. A reader compares their own output
+        // against it, so a stale baseline line there is read as a current one.
+        template: '(baseline {w}: {n} tools across {n} measured servers):',
+        values: (s) => [s.toolShape.generatedAt, fmt(s.toolShape.toolCount), fmt(s.toolShape.serverCount)],
     },
     {
         file: 'README.md',
@@ -317,11 +348,23 @@ export const PAGE_CLAIMS = [
             fmt(s.claude.widest.mapped),
         ],
     },
+    {
+        file: 'docs/METHODOLOGY.md',
+        id: 'divergence:band-parenthetical',
+        // The deferral section's own copy of the band. It was hand-written and held
+        // to `PUBLISHED_WIRE_TO_CLIENT_RATIO` by a test, which worked only while the
+        // constant tracked the run exactly — and the constant is a release-time
+        // snapshot that is deliberately allowed to lag. Two pages quoting two
+        // different sources for one number is the drift this file exists to end, so
+        // both pages state the run and the constant is guarded separately.
+        template: 'band ({f}×–{f}×\nacross {n} servers)',
+        values: (s) => [s.claude.ratioMin.toFixed(2), s.claude.ratioMax.toFixed(2), fmt(s.claude.ratioServers)],
+    },
     {
         file: 'docs/METHODOLOGY.md',
         id: 'divergence:ratio-range',
         template: 'it ranged from {f}× to {f}× across the {n} servers in the run,',
-        values: (s) => [s.claude.ratioMin.toFixed(2), s.claude.ratioMax.toFixed(2), fmt(s.claude.runSize)],
+        values: (s) => [s.claude.ratioMin.toFixed(2), s.claude.ratioMax.toFixed(2), fmt(s.claude.ratioServers)],
     },
     {
         file: 'docs/METHODOLOGY.md',

package/dist/sweep/regressions.js

@@ -103,9 +103,19 @@ export function writeCaptureIndex(entries, root = process.cwd()) {
     }
     for (const sha of ambiguous)
         delete captures[sha];
+    // Dated by the newest capture it indexes, not by the moment it was written —
+    // the same rule the dashboard was moved to. A clock stamp makes the file
+    // claim to be as fresh as the run that regenerated it, when what a reader
+    // needs to know is how far the data behind it reaches. It also means
+    // regenerating over unchanged vectors produces no diff, which is what lets a
+    // release gate ask "is anything derived here stale?" and get a real answer.
+    const newest = Object.values(captures)
+        .map((c) => c.date)
+        .sort()
+        .pop();
     const index = {
         method: CAPTURE_INDEX_METHOD,
-        generatedAt: new Date().toISOString().slice(0, 10),
+        generatedAt: newest ?? '',
         // Key order sorted so a re-run over unchanged vectors produces no diff noise.
         captures: Object.fromEntries(Object.entries(captures).sort(([a], [b]) => a.localeCompare(b))),
         current: Object.fromEntries(Object.entries(current).sort(([a], [b]) => a.localeCompare(b))),

package/dist/sweep/run.js

@@ -7,7 +7,7 @@
 import { mkdirSync, writeFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { captureTools } from './client.js';
+import { captureTools, clampNotes } from './client.js';
 import { DockerHarnessFault, defaultImageFor, dockerize, ensureImage, containerPlatform, isDockerRunFailure, } from './docker.js';
 import { measureTools, failedMeasurement, canonicalString } from '../core/canonical.js';
 import { toBadge } from '../core/badge.js';
@@ -206,8 +206,12 @@ export async function measureServer(name, command, opts = {}) {
                 : opts;
         let r;
         try {
-            const first = await captureTools(buildSpec(noSharedCache), attemptOpts);
-            const second = await captureTools(buildSpec(noSharedCache), attemptOpts);
+            // The declared evidence travels with the launch, because the truncation
+            // that could lose it happens inside the client, before anything here sees
+            // the message it will be classified from.
+            const captureOpts = { ...attemptOpts, keepEvidence: opts.notApplicable?.evidence };
+            const first = await captureTools(buildSpec(noSharedCache), captureOpts);
+            const second = await captureTools(buildSpec(noSharedCache), captureOpts);
             r = measureTools(first.tools, {
                 serverName: first.serverInfo?.name ?? name,
                 serverVersion: first.serverInfo?.version,
@@ -236,7 +240,7 @@ export async function measureServer(name, command, opts = {}) {
                 launchCommand: command,
                 // The declared reason leads, but the raw failure stays behind it: the
                 // record has to remain checkable against the run that produced it.
-                notes: (declared ? `${declared} — ${msg}` : msg).slice(0, 700),
+                notes: clampNotes(declared ? `${declared} — ${msg}` : msg, 700, opts.notApplicable?.evidence),
             });
         }
         const iso = isolation ?? { docker: false };

package/dist/sweep/tool-shape.js

@@ -11,6 +11,7 @@ import { buildToolShapeBaseline } from '../core/tool-shape.js';
 import { loadRows } from './report.js';
 export function writeToolShapeBaseline(entries, root = process.cwd()) {
     const tools = [];
+    const dates = [];
     let serverCount = 0;
     for (const r of loadRows(entries, root)) {
         if (!r.m || (r.m.status !== 'measured' && r.m.status !== 'dynamic'))
@@ -19,8 +20,20 @@ export function writeToolShapeBaseline(entries, root = process.cwd()) {
             continue;
         serverCount++;
         tools.push(...r.m.tools);
+        const day = String(r.m.measuredAt ?? '').slice(0, 10);
+        if (/^\d{4}-\d{2}-\d{2}$/.test(day))
+            dates.push(day);
     }
-    const baseline = buildToolShapeBaseline(tools, { serverCount, methodologyVersion: METHODOLOGY_VERSION });
+    // Dated by the newest measurement it summarises rather than by the clock, so
+    // the file says how far its data reaches and a re-derivation over unchanged
+    // measurements produces no diff. `buildToolShapeBaseline` still defaults to
+    // today when nobody supplies one, for callers with no measurement dates.
+    const generatedAt = dates.sort().pop();
+    const baseline = buildToolShapeBaseline(tools, {
+        serverCount,
+        methodologyVersion: METHODOLOGY_VERSION,
+        ...(generatedAt ? { generatedAt } : {}),
+    });
     writeFileSync(join(root, 'results', 'tool-shape.json'), JSON.stringify(baseline, null, 2) + '\n');
     return baseline;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-context-cost",
-  "version": "0.13.0",
+  "version": "0.13.2",
   "description": "Measure what your MCP servers cost in context tokens — audit your own config, or badge the server you publish",
   "type": "module",
   "license": "MIT",
@@ -43,7 +43,9 @@
     "session-start": "tsx src/sweep/session-start.ts",
     "sweep": "tsx src/sweep/run.ts",
     "sweep:all": "tsx src/sweep/sweep-all.ts",
-    "verify": "tsx src/cli.ts verify"
+    "verify": "tsx src/cli.ts verify",
+    "check:release": "tsx tools/release-readiness.ts",
+    "cut": "tsx tools/cut-changelog.ts"
   },
   "engines": {
     "node": ">=20"