mcp-context-cost 0.11.2 → 0.12.0

package/README.md

@@ -184,7 +184,7 @@ Add `--claude` to annotate each server with its Anthropic-request cost from the
 [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 when it ran —
-and [results/leaderboard.md](results/leaderboard.md) prints a claude number for the 16 that
+and [results/leaderboard.md](results/leaderboard.md) prints a claude number for the 12 that
 still match today and silence for the rest. Most installs will show a mix:
 
 ```
@@ -235,7 +235,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 81 servers measured, cost spans **1,700×**,
+shows what you are choosing between: across the 83 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).
@@ -244,13 +244,13 @@ sample of that range; the full range is in
 |---|---:|---:|
 | github (official) | **54,622 tokens** | 44 |
 | xcodebuildmcp | 26,594 | 24 |
-| brave-search | 25,456 | 8 |
+| brave-search | 25,487 | 8 |
 | notion | 17,500 | 24 |
 | playwright *(4.8M installs/week)* | 4,024 | 24 |
 | filesystem (reference) | 2,823 | 14 |
 | markitdown | 64 | 1 |
 
-*(81 of 106 popular servers measured, each row dated by its own most recent sweep — full table in
+*(83 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.)*
@@ -260,7 +260,7 @@ answers a question no client asks: **what did this server cost last month?**
 [results/regressions.md](results/regressions.md) reports each server's most recent movement —
 dated to when it happened, separated into *shipped more tools* versus *same tools, rewritten*,
 and compared only within one isolation. The ecosystem ratchets upward: of the servers whose
-cost has moved at all, 9 moved up against 1 that moved down. Method:
+cost has moved at all, 11 moved up against 6 that moved down. Method:
 [cost movement](docs/METHODOLOGY.md#cost-movement).
 
 If you publish a server, the same measurement is available as a badge, so your users can see

package/dist/audit/audit.js

@@ -179,6 +179,13 @@ export function buildReport(configs, measured, opts = {}) {
     const contextWindow = opts.contextWindow ?? DEFAULT_CONTEXT_WINDOW;
     const problems = [];
     const emptyConfigs = [];
+    // canonicalSha256 → the divergence row computed from it, so a server can be
+    // identified by its bytes whatever the local config calls it.
+    const divByHash = new Map();
+    for (const row of Object.values(opts.divergence?.servers ?? {})) {
+        if (row?.capturedSha256)
+            divByHash.set(row.capturedSha256, row);
+    }
     const built = [];
     // Across every config at once: a twin in one client's file is measured for
     // the other client's entry just the same.

package/dist/audit/config.js

@@ -182,9 +182,18 @@ export function configCandidates(env) {
 /** Read + parse the candidates that exist. Unreadable files are reported, not thrown. */
 export function loadConfigs(candidates, cwd) {
     const out = [];
+    // Running from your home directory nominates `~/.cursor/mcp.json` twice —
+    // once as the home candidate, once as the cwd one. Loaded twice it is
+    // reported twice, doubles that client's deferral scope, and under
+    // `--baseline` the second copy pairs with nothing and fails the gate. One
+    // path is one config however many ways it was nominated.
+    const seen = new Set();
     for (const c of candidates) {
         if (!existsSync(c.path))
             continue;
+        if (seen.has(c.path))
+            continue;
+        seen.add(c.path);
         try {
             const doc = parseJsonc(readFileSync(c.path, 'utf8'));
             const { servers, disabled } = extractDeclaration(doc, { client: c.client, source: c.path, cwd });

package/dist/audit/diff.js

@@ -181,7 +181,15 @@ export function pairConfigs(before, after) {
             pairs.push({ before: null, after: cur, matchedBy: 'unmatched' });
         }
     }
-    if (before.length === 1 && after.length === 1 && pairs[0].before === null) {
+    // One on each side reads as the same config seen from two machines, where the
+    // path legitimately differs (a laptop's baseline against a CI checkout). It
+    // does not survive the clients differing: a Claude Desktop baseline against a
+    // Claude Code run compares two unrelated stacks, and the gate then rests on
+    // that difference. The paths may differ; what they are configs *for* may not.
+    if (before.length === 1 &&
+        after.length === 1 &&
+        pairs[0].before === null &&
+        before[0].client === after[0].client) {
         pairs[0] = { before: before[0], after: after[0], matchedBy: 'sole-config' };
         unusedBefore.delete(before[0].source);
     }

package/dist/cli.js

@@ -45,6 +45,19 @@ export function slugFromUrl(url) {
     const host = new URL(url).hostname.replace(/^(www|mcp)\./, '');
     return host.replace(/[^a-z0-9]+/gi, '-').replace(/^-+|-+$/g, '').toLowerCase() || 'remote';
 }
+/**
+ * Report a `verify` failure and exit 1, in whichever shape the caller asked
+ * for. `--json` is documented as putting `{ ok, rederivedTokens, rederivedSha,
+ * problems }` on stdout; a script reading that gets nothing from a thrown
+ * exception, so every failure path goes through here.
+ */
+function failVerify(json, problem) {
+    if (json)
+        console.log(JSON.stringify({ ok: false, rederivedTokens: null, rederivedSha: null, problems: [problem] }));
+    else
+        console.error(problem);
+    process.exit(1);
+}
 /** Installed version, for error messages that need to say which one you are running. */
 export function cliVersion() {
     try {
@@ -322,6 +335,12 @@ if (cmd === 'audit') {
                 `${where}\n` +
                 `${empty.length === 1 ? 'It was' : 'They were'} read and parsed; there is simply nothing declared to measure.\n` +
                 `Declare a server in one of them, or point at a different config: mcp-context-cost audit --config <path/to/mcp.json>`);
+        else if (all('config').length)
+            // A path the user named is not a discovery miss. Saying "looked in the
+            // standard locations" describes something the command did not do, and
+            // then advises doing the thing they just did.
+            console.error(`no MCP config found at the path(s) given: ${all('config').join(', ')}. ` +
+                `Nothing else was searched, because --config was set.`);
         else
             console.error(`no MCP config found. Looked in the standard Claude Desktop / Claude Code / Cursor / VS Code / Windsurf locations.${where}\n` +
                 `Point at one explicitly: mcp-context-cost audit --config <path/to/mcp.json>`);
@@ -355,18 +374,29 @@ else if (cmd === 'verify') {
             raw = await res.text();
         }
         catch (e) {
-            const problem = `failed to fetch ${remoteUrl}: ${e.message}`;
-            if (json)
-                console.log(JSON.stringify({ ok: false, rederivedTokens: null, rederivedSha: null, problems: [problem] }));
-            else
-                console.error(problem);
-            process.exit(1);
+            failVerify(json, `failed to fetch ${remoteUrl}: ${e.message}`);
         }
     }
     else {
-        raw = readFileSync(path, 'utf8');
+        try {
+            raw = readFileSync(path, 'utf8');
+        }
+        catch (e) {
+            // The remote branch above reports a failed fetch in the documented shape;
+            // this one used to throw, so `--json` produced a stack trace on stderr and
+            // nothing at all on stdout — the contract a script parses.
+            failVerify(json, `cannot read ${path}: ${e.message}`);
+        }
+    }
+    let m;
+    try {
+        m = JSON.parse(raw);
+    }
+    catch (e) {
+        // Reachable remotely: a proxy, a captive portal or an HTML error page
+        // served with status 200 passes the `res.ok` check above and arrives here.
+        failVerify(json, `${remoteUrl ?? path} is not valid JSON: ${e.message}`);
     }
-    const m = JSON.parse(raw);
     const r = verifyMeasurement(m);
     if (json) {
         console.log(JSON.stringify({ serverName: m.serverName, ...r, badge: r.ok ? toBadge(m) : undefined }));

package/dist/core/adoption.d.ts

@@ -143,6 +143,14 @@ export declare function decodeLoose(text: string): string;
 export interface EndpointBadge {
     url: string;
     linkTarget: string | null;
+    /**
+     * The badge's own label — markdown alt text or an `<img alt>`. What the badge
+     * calls itself is the only thing in a README that distinguishes *this*
+     * project's badge from any other shields endpoint badge, since the JSON can
+     * be hosted anywhere (the staged action publishes to a gist, with no path
+     * shape to recognise).
+     */
+    alt: string | null;
 }
 /**
  * Every shields endpoint badge in a file, decoded, each paired with its own
@@ -172,6 +180,21 @@ export declare function linksBackToProject(target: string, src?: BadgeSource): b
  * measurement here. See the header for why both count and why the link is
  * paired with the image rather than looked for anywhere in the file.
  */
+/**
+ * Whether a badge calls itself this project's badge.
+ *
+ * The self-hosted branch below used to accept the link alone and look at
+ * nothing else, so *any* shields endpoint badge — a coverage badge, say —
+ * wrapped in a link to this repository counted as displaying ours. That
+ * inflates the one number this project keeps about itself, which is the last
+ * place it can afford a generous reading.
+ *
+ * The URL cannot decide it: self-hosted JSON lives wherever its author put it,
+ * and the staged action publishes to a gist. What every published snippet does
+ * carry is the label — `context cost` — so that is what is read, tolerantly
+ * enough to accept `Context-Cost` and strictly enough to reject `coverage`.
+ */
+export declare function namesThisBadge(alt: string | null): boolean;
 export declare function displaysBadge(text: string, src?: BadgeSource): boolean;
 /**
  * Every shields endpoint `url` in a file whose JSON is served from this

package/dist/core/adoption.js

@@ -137,7 +137,11 @@ export function endpointBadges(text) {
             if (last && !before.slice(last.index ?? 0).includes('</a>'))
                 linkTarget = last[1];
         }
-        out.push({ url: m[1], linkTarget });
+        // Markdown puts the alt before the image; HTML puts it in the same tag.
+        const beforeAlt = decoded.slice(Math.max(0, start - LINK_WINDOW), start);
+        const mdAlt = beforeAlt.match(/!\[([^\]]*)\]\(\s*[^\s)]*$/);
+        const tagAlt = after.match(/^[^<>]*?\balt\s*=\s*["']([^"']*)["']/i);
+        out.push({ url: m[1], linkTarget, alt: mdAlt ? mdAlt[1] : tagAlt ? tagAlt[1] : null });
     }
     return out;
 }
@@ -169,8 +173,28 @@ export function linksBackToProject(target, src = BADGE_SOURCE) {
  * measurement here. See the header for why both count and why the link is
  * paired with the image rather than looked for anywhere in the file.
  */
+/**
+ * Whether a badge calls itself this project's badge.
+ *
+ * The self-hosted branch below used to accept the link alone and look at
+ * nothing else, so *any* shields endpoint badge — a coverage badge, say —
+ * wrapped in a link to this repository counted as displaying ours. That
+ * inflates the one number this project keeps about itself, which is the last
+ * place it can afford a generous reading.
+ *
+ * The URL cannot decide it: self-hosted JSON lives wherever its author put it,
+ * and the staged action publishes to a gist. What every published snippet does
+ * carry is the label — `context cost` — so that is what is read, tolerantly
+ * enough to accept `Context-Cost` and strictly enough to reject `coverage`.
+ */
+export function namesThisBadge(alt) {
+    if (!alt)
+        return false;
+    return alt.toLowerCase().replace(/[^a-z]/g, '').includes('contextcost');
+}
 export function displaysBadge(text, src = BADGE_SOURCE) {
-    return endpointBadges(text).some((b) => hostedHere(b.url, src) || (b.linkTarget !== null && linksBackToProject(b.linkTarget, src)));
+    return endpointBadges(text).some((b) => hostedHere(b.url, src) ||
+        (namesThisBadge(b.alt) && b.linkTarget !== null && linksBackToProject(b.linkTarget, src)));
 }
 /**
  * Every shields endpoint `url` in a file whose JSON is served from this

package/dist/core/capture-index.js

@@ -72,14 +72,18 @@ export function identify(canonicalSha256, index) {
     if (!mine)
         return { kind: 'unknown' };
     const currentSha = index.current[mine.server];
-    if (!currentSha || currentSha === canonicalSha256) {
+    if (currentSha === canonicalSha256) {
         return { kind: 'current', server: mine.server, date: mine.date, tokens: mine.totalTokens };
     }
-    const current = index.captures[currentSha];
-    // A `current` pointer with no capture behind it describes nothing; treat the
-    // version as identified but with nothing to compare it against.
+    // The bytes are identified, but what is current for this server is not: the
+    // pointer is missing, or points at a capture the index dropped as ambiguous.
+    // `current` would be an affirmative claim that nothing has moved, which the
+    // audit prints as "no server here is running a published capture that has
+    // since moved" — told to someone who may be far behind. Unknown currency
+    // reads as unknown, which is the discipline the rest of this module keeps.
+    const current = currentSha ? index.captures[currentSha] : undefined;
     if (!current)
-        return { kind: 'current', server: mine.server, date: mine.date, tokens: mine.totalTokens };
+        return { kind: 'unknown' };
     return {
         kind: 'behind',
         server: mine.server,

package/dist/core/cross-check.js

@@ -160,6 +160,9 @@ export function isComparable(row, canonicalSha256) {
         canonicalSha256 !== null &&
         row.capturedSha256 === canonicalSha256 &&
         row.ourTokens > 0 &&
+        // A report that parsed but carries `total: 0` is not a measurement of
+        // anything; published, it renders as a −100% divergence.
+        row.cliTokens > 0 &&
         row.ourMappedTokens > 0);
 }
 /**

package/dist/core/divergence.js

@@ -55,6 +55,14 @@ export function mappedTokens(raw) {
 export function fieldSelectionShare(row) {
     if (row.o200kFull <= 0)
         return null;
+    // The projection can add bytes rather than remove them — `inputSchema`
+    // becomes the longer `input_schema`, and a tool with no description gains
+    // `description: ""` — so a server with almost no metadata to drop can map
+    // *larger* than it measured. There is no share of the payload removed in that
+    // case, and publishing a negative one reads as "−11.1% of the capture is
+    // MCP-only metadata", which is not a thing.
+    if (row.o200kMapped > row.o200kFull)
+        return null;
     return (row.o200kFull - row.o200kMapped) / row.o200kFull;
 }
 /**

package/dist/core/regression.d.ts

@@ -124,7 +124,20 @@ export interface ToolAttribution {
      */
     unexplainedTokens: number;
 }
-export declare function attribute(from: ToolVectorEntry, to: ToolVectorEntry, deltaTokens: number): ToolAttribution;
+/**
+ * Per-tool attribution, or null when the names cannot carry it.
+ *
+ * The breakdown matches tools by name, so a name that appears twice on either
+ * side makes the maps below lose one of them silently — and the lost tokens
+ * resurface as `unexplainedTokens`, which the report explains to the reader as
+ * canonical-array framing bytes. That is a confident false explanation. Two
+ * ways it happens: a server that ships duplicate or namespaced-collapsed tool
+ * names, and `measureTools` recording every nameless tool as the single key
+ * `(unnamed)` — an invented name, where `toolNames` and `toAnthropicTools`
+ * deliberately drop nameless tools rather than invent one. Where the names
+ * cannot identify the tools, there is no attribution to give.
+ */
+export declare function attribute(from: ToolVectorEntry, to: ToolVectorEntry, deltaTokens: number): ToolAttribution | null;
 export interface CostChange {
     server: string;
     fromDate: string;

package/dist/core/regression.js

@@ -87,7 +87,23 @@ export function mechanismOf(deltaTokens, deltaTools) {
     // and rewritten, and the totals cannot separate the two.
     return 'mixed';
 }
+/**
+ * Per-tool attribution, or null when the names cannot carry it.
+ *
+ * The breakdown matches tools by name, so a name that appears twice on either
+ * side makes the maps below lose one of them silently — and the lost tokens
+ * resurface as `unexplainedTokens`, which the report explains to the reader as
+ * canonical-array framing bytes. That is a confident false explanation. Two
+ * ways it happens: a server that ships duplicate or namespaced-collapsed tool
+ * names, and `measureTools` recording every nameless tool as the single key
+ * `(unnamed)` — an invented name, where `toolNames` and `toAnthropicTools`
+ * deliberately drop nameless tools rather than invent one. Where the names
+ * cannot identify the tools, there is no attribution to give.
+ */
 export function attribute(from, to, deltaTokens) {
+    const unique = (ts) => new Set(ts.map((t) => t.name)).size === ts.length;
+    if (!unique(from.tools) || !unique(to.tools))
+        return null;
     const before = new Map(from.tools.map((t) => [t.name, t.tokens]));
     const after = new Map(to.tools.map((t) => [t.name, t.tokens]));
     const added = [];

package/dist/core/tool-shape.js

@@ -23,10 +23,18 @@ export function quantileTable(values) {
  * checkable by anyone holding the same JSON.
  */
 export function percentileOf(quantiles, value) {
+    // The LOWEST percentile whose quantile the value reaches, not the highest.
+    // Taking the highest reports a value tied with half the measured set as p100
+    // — "heavier than 100% of measured tools" about something exactly average for
+    // its tie — because every percentile across the tie carries the same
+    // quantile. The lowest names where the tie begins, which is what "heavier
+    // than P% of tools" means.
     let p = 0;
     for (let i = 0; i <= 100; i++) {
-        if (quantiles[i] <= value)
-            p = i;
+        if (quantiles[i] <= value) {
+            if (quantiles[i] < value || i === 0 || quantiles[i - 1] < quantiles[i])
+                p = i;
+        }
         else
             break;
     }

package/dist/core/types.d.ts

@@ -1,5 +1,15 @@
 /** Status taxonomy — every swept server gets exactly one; no silent drops. */
-export type MeasurementStatus = 'measured' | 'auth-required' | 'startup-failure' | 'timeout' | 'dynamic' | 'remote-auth-wall';
+export type MeasurementStatus = 'measured' | 'auth-required' | 'startup-failure' | 'timeout'
+/**
+ * This harness cannot run the server, for a reason that is a property of the
+ * harness rather than of the software: an OS or architecture the package does
+ * not ship for, or a backing service the isolation deliberately does not
+ * provide. Distinct from `startup-failure`, which asserts the server did not
+ * come up — a claim about someone else's code that these entries do not
+ * support. Only ever set when the entry declares the reason AND the failure's
+ * own text corroborates it (see `notApplicable` in report.ts).
+ */
+ | 'not-applicable' | 'dynamic' | 'remote-auth-wall';
 export interface ToolMeasurement {
     name: string;
     /** Tokens of the whole tool object, canonically serialized. */
@@ -43,6 +53,18 @@ export interface Measurement {
         image?: string;
         network?: string;
         note?: string;
+        /**
+         * The architecture the measurement ran on, as `<platform>/<arch>` (e.g.
+         * `linux/amd64`). Part of the isolation because some packages ship builds
+         * for only some of them: `local-mcp` was published as a startup failure
+         * for weeks on the strength of a run whose real finding was "this laptop
+         * is arm64 and the package has no arm64 runtime" — a fact about the
+         * machine that the record gave no way to see.
+         *
+         * Absent on records written before this was captured, which is why it is
+         * optional; absence means unknown, never "the same as yours".
+         */
+        arch?: string;
     };
     /** Request timeout in force during this measurement. */
     timeoutMs?: number;

package/dist/sweep/client.d.ts

@@ -13,6 +13,28 @@ export interface WireCapture {
     instructions: string | null;
     stderrTail: string;
 }
+/**
+ * The part of a dead server's stderr worth keeping as evidence.
+ *
+ * A failure record is only useful if it contains the failure, and a plain tail
+ * reliably keeps the least useful part. `npx` prints a deprecation warning per
+ * transitive dependency and a version notice at the end, and a crashing process
+ * prints its message *before* the stack — so the last N characters of stderr
+ * are npm warnings and stack frames on exactly the servers whose failure needs
+ * explaining. Several published records ended up saying nothing about why the
+ * server did not start.
+ *
+ * This is not cosmetic. `run.ts` classifies a failure by reading these words:
+ * a record whose message was cut off is filed as `startup-failure` — the server
+ * is broken — when the surviving text would have said `auth-required`. Spending
+ * the budget on the message rather than the frames is what keeps the published
+ * taxonomy describing the server.
+ *
+ * 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.
+ */
+export declare function evidenceTail(stderr: string, limit?: number): string;
 export declare class McpStdioClient {
     private child;
     private buffer;

package/dist/sweep/client.js

@@ -6,6 +6,92 @@
  */
 import { spawn } from 'node:child_process';
 const PROTOCOL_VERSION = '2025-06-18';
+/**
+ * The part of a dead server's stderr worth keeping as evidence.
+ *
+ * A failure record is only useful if it contains the failure, and a plain tail
+ * reliably keeps the least useful part. `npx` prints a deprecation warning per
+ * transitive dependency and a version notice at the end, and a crashing process
+ * prints its message *before* the stack — so the last N characters of stderr
+ * are npm warnings and stack frames on exactly the servers whose failure needs
+ * explaining. Several published records ended up saying nothing about why the
+ * server did not start.
+ *
+ * This is not cosmetic. `run.ts` classifies a failure by reading these words:
+ * a record whose message was cut off is filed as `startup-failure` — the server
+ * is broken — when the surviving text would have said `auth-required`. Spending
+ * the budget on the message rather than the frames is what keeps the published
+ * taxonomy describing the server.
+ *
+ * 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.
+ */
+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);
+}
+/**
+ * Keep the start and the end, eliding the middle.
+ *
+ * Dropping npm noise and stack frames is not enough on its own: a CLI that
+ * rejects its environment often prints one line saying why and then its entire
+ * usage screen, which is neither. kubernetes-mcp-server does exactly that, and
+ * a tail-only budget kept forty lines of flag documentation while discarding
+ * "no current-context is set and no contexts are defined in kubeconfig" — the
+ * only sentence in the output that explained anything.
+ *
+ * Failures put their explanation at one end or the other — a crash message
+ * above its aftermath, or an error at the end of a log — so both ends are kept
+ * 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) {
+    if (text.length <= limit)
+        return text;
+    const elision = '\n […] \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
+    // corruption and loses the token an evidence string would match on.
+    const take = (from, to, cap, fromEnd) => {
+        const out = [];
+        let used = 0;
+        for (let i = fromEnd ? to : from; fromEnd ? i >= from : i <= to; i += fromEnd ? -1 : 1) {
+            const cost = lines[i].length + 1;
+            if (used + cost > cap)
+                break;
+            fromEnd ? out.unshift(lines[i]) : out.push(lines[i]);
+            used += cost;
+        }
+        return { out, used };
+    };
+    const headCap = Math.ceil(budget * 0.6);
+    const head = take(0, lines.length - 1, headCap, false);
+    // Whole lines, except when the first line alone overruns the budget. A server
+    // that logs structured JSON puts its entire message on one line, so that line
+    // is both the most informative thing in the output and the only one that can
+    // never fit — slack-mcp-server's `{"level":"fatal","message":"Authentication
+    // required: ..."}` was dropped in full, and the record it left behind said a
+    // child process exited. Truncated evidence beats none.
+    const headText = head.out.length > 0 ? head.out.join('\n') : lines[0].slice(0, headCap);
+    const headUsed = head.out.length > 0 ? head.used : headText.length;
+    const tailFrom = head.out.length > 0 ? head.out.length : 1;
+    const tail = take(tailFrom, lines.length - 1, budget - headUsed, true);
+    if (headText === '' && tail.out.length === 0)
+        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) {
+    const kept = text
+        .split('\n')
+        .filter((l) => !isNoise(l.trim()))
+        .join('\n')
+        .trim();
+    return kept || text.trim();
+}
 export class McpStdioClient {
     child;
     buffer = '';
@@ -37,7 +123,7 @@ export class McpStdioClient {
                 resolve();
             });
             this.child.on('exit', (code) => {
-                const tail = this.stderrTail.slice(-600);
+                const tail = evidenceTail(this.stderrTail);
                 this.deadReason = `server exited (code ${code})${tail ? `; stderr tail: ${tail}` : ''}`;
                 for (const p of this.pending.values())
                     p.reject(new Error(this.deadReason));
@@ -95,7 +181,12 @@ export class McpStdioClient {
         return new Promise((resolve, reject) => {
             const timer = setTimeout(() => {
                 this.pending.delete(id);
-                reject(new Error(`timeout after ${timeoutMs}ms waiting for ${method}`));
+                // A process that is killed mid-hang never reaches the exit handler, so
+                // 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);
+                reject(new Error(`timeout after ${timeoutMs}ms waiting for ${method}${tail ? `; stderr tail: ${tail}` : ''}`));
             }, timeoutMs);
             this.pending.set(id, {
                 resolve: (v) => {

package/dist/sweep/dashboard.js

@@ -7,6 +7,7 @@ import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { parse } from 'yaml';
 import { isCurrent } from '../core/divergence.js';
+import { loadRows } from './report.js';
 import { bandColor, BAND_META } from '../core/bands.js';
 import { parseHistory, plottableSeries } from './history.js';
 /** Longest series a sparkline plots — a stat-tile trend, not a full chart. */
@@ -53,10 +54,9 @@ export function generateDashboard(root = process.cwd()) {
     // Only the run of sweeps taken under the same isolation is plotted: a step
     // across an isolation change is the harness moving, not the server.
     const seriesFor = (name) => plottableSeries(history.filter((h) => h.server === name));
-    const rows = doc.servers.map((entry) => {
-        const p = join(root, 'results', entry.name, 'measurement.json');
-        return { entry, m: existsSync(p) ? JSON.parse(readFileSync(p, 'utf8')) : null };
-    });
+    // Shared with the leaderboard rather than re-read here: one definition of how
+    // a measurement is loaded, including its tolerance for a half-written file.
+    const rows = loadRows(doc.servers, root);
     const measured = rows
         .filter((r) => r.m && (r.m.status === 'measured' || r.m.status === 'dynamic') && r.m.totalTokens !== null)
         .sort((a, b) => (b.m.totalTokens ?? 0) - (a.m.totalTokens ?? 0));

package/dist/sweep/harness-guard.d.ts

@@ -47,7 +47,15 @@ export interface Verdict {
  * `current` maps server name to the status it just measured at. Servers absent
  * from it were not swept and are ignored.
  */
-export declare function verdict(prior: Snapshot[], current: Map<string, MeasurementStatus>): Verdict;
+export declare function verdict(prior: Snapshot[], current: Map<string, MeasurementStatus>, 
+/**
+ * Servers this sweep could not measure because docker itself failed. They
+ * never reached a status, so they are absent from `current` and invisible to
+ * the comparison below — but they are the same fact it is looking for: a
+ * server that could have produced a number and did not. Counted here so the
+ * two symptoms share one threshold instead of being each other's blind spot.
+ */
+dockerFaults?: number): Verdict;
 /**
  * Put the snapshotted artifacts back, byte for byte. Only servers named in
  * `names` are touched, and only where a prior file existed — a server whose

package/dist/sweep/harness-guard.js

@@ -78,12 +78,21 @@ export function snapshot(names, root = process.cwd()) {
  * `current` maps server name to the status it just measured at. Servers absent
  * from it were not swept and are ignored.
  */
-export function verdict(prior, current) {
+export function verdict(prior, current, 
+/**
+ * Servers this sweep could not measure because docker itself failed. They
+ * never reached a status, so they are absent from `current` and invisible to
+ * the comparison below — but they are the same fact it is looking for: a
+ * server that could have produced a number and did not. Counted here so the
+ * two symptoms share one threshold instead of being each other's blind spot.
+ */
+dockerFaults = 0) {
     const comparableNames = prior
         .filter((s) => s.status !== null && isGood(s.status) && current.has(s.name))
         .map((s) => s.name);
     const regressed = comparableNames.filter((n) => !isGood(current.get(n)));
-    const comparable = comparableNames.length;
+    const failed = regressed.length + dockerFaults;
+    const comparable = comparableNames.length + dockerFaults;
     if (comparable === 0) {
         return {
             fault: false,
@@ -94,15 +103,16 @@ export function verdict(prior, current) {
             reason: 'no prior measurement to compare against — harness check not performed',
         };
     }
-    const ratio = regressed.length / comparable;
+    const ratio = failed / comparable;
     const pct = (ratio * 100).toFixed(0);
-    if (regressed.length >= MIN_REGRESSIONS && ratio >= FAULT_RATIO) {
+    const how = dockerFaults > 0 ? ` (${regressed.length} regressed, ${dockerFaults} unmeasurable)` : '';
+    if (failed >= MIN_REGRESSIONS && ratio >= FAULT_RATIO) {
         return {
             fault: true,
             regressed,
             comparable,
-            reason: `${regressed.length} of ${comparable} previously-measured servers (${pct}%) failed in ` +
-                `this sweep — at or above the ${MIN_REGRESSIONS}-server, ` +
+            reason: `${failed} of ${comparable} previously-measured servers (${pct}%) produced no number in ` +
+                `this sweep${how} — at or above the ${MIN_REGRESSIONS}-server, ` +
                 `${(FAULT_RATIO * 100).toFixed(0)}% threshold that reads as a broken harness ` +
                 `rather than broken servers`,
         };
@@ -111,8 +121,8 @@ export function verdict(prior, current) {
         fault: false,
         regressed,
         comparable,
-        reason: `${regressed.length} of ${comparable} previously-measured servers (${pct}%) failed in ` +
-            `this sweep — below the harness-fault threshold, publishing normally`,
+        reason: `${failed} of ${comparable} previously-measured servers (${pct}%) produced no number in ` +
+            `this sweep${how} — below the harness-fault threshold, publishing normally`,
     };
 }
 /**

package/dist/sweep/report.d.ts

@@ -23,6 +23,22 @@ export interface ServerEntry {
      * before ever reaching tools/list. See docker.ts `dummyEnvValues`.
      */
     envValues?: Record<string, string>;
+    /**
+     * Declares that a failure of this entry is this harness's limitation, not the
+     * server's — an OS or architecture the package does not ship for, or a
+     * backing service the isolation deliberately does not provide.
+     *
+     * `evidence` is what keeps the declaration honest. The status only becomes
+     * `not-applicable` when the failure's own text contains that substring, so an
+     * annotation left behind after upstream changes cannot quietly absorb a real
+     * breakage: the server fails a different way, the evidence stops matching,
+     * and it is published as the failure it actually is. The entry is still
+     * attempted every sweep, so the day it starts working it simply measures.
+     */
+    notApplicable?: {
+        reason: string;
+        evidence: string;
+    };
 }
 export interface Row {
     entry: ServerEntry;

package/dist/sweep/report.js

@@ -21,7 +21,20 @@ function csvCell(s) {
 export function loadRows(entries, root = process.cwd()) {
     return entries.map((entry) => {
         const p = join(root, 'results', entry.name, 'measurement.json');
-        return { entry, m: existsSync(p) ? JSON.parse(readFileSync(p, 'utf8')) : null };
+        if (!existsSync(p))
+            return { entry, m: null };
+        try {
+            return { entry, m: JSON.parse(readFileSync(p, 'utf8')) };
+        }
+        catch {
+            // The same tolerance `appendHistory` states for the same file: a sweep
+            // killed mid-write leaves a truncated measurement, and every generator
+            // reads through here. Throwing meant one such file broke the leaderboard,
+            // the server pages, the dashboard, the tool-shape baseline and the
+            // published-stats check at once — weekly, with a SyntaxError that named
+            // no file. A server with no readable record reads as one with no record.
+            return { entry, m: null };
+        }
     });
 }
 /** results/divergence.json if a divergence run has been recorded, else null. */

package/dist/sweep/run.d.ts

@@ -1,4 +1,40 @@
 import type { Measurement } from '../core/types.js';
+/**
+ * Which kind of failure a dead server's own words describe.
+ *
+ * The distinction is the published one: `auth-required` says the server works
+ * and this harness has no credentials for it, `startup-failure` says the server
+ * did not come up. Only the text decides, so it matters that the text reaching
+ * here is the part that explains the failure rather than whatever happened to
+ * fall in the last few hundred bytes — see `evidenceTail` in client.ts, which
+ * exists because a truncated message was being filed as a broken server.
+ */
+export declare function classifyFailure(msg: string): 'timeout' | 'auth-required' | 'startup-failure';
+/**
+ * The architecture a measurement ran on, in Docker's vocabulary (`linux/amd64`).
+ *
+ * Worth recording because a package can ship builds for some architectures and
+ * not others, and then the *machine* decides the result. `local-mcp` sat
+ * published as a startup failure on the strength of a run whose actual finding
+ * was that the laptop was arm64 and the package ships no arm64 runtime — and
+ * the record gave a reader no way to notice.
+ *
+ * Containers are linux whatever the host is; with no explicit `--platform` they
+ * take the host's architecture, so that is the half worth reporting.
+ */
+export declare function measuringArch(docker: boolean): string;
+/**
+ * The declared reason, when this failure is the one the entry warned about.
+ *
+ * Corroboration is the whole point: an entry may declare that this harness
+ * cannot run it, but only the failure's own words can confirm that *this*
+ * failure is that one. A macOS-only package that starts failing for some new
+ * reason stops matching, and is published as the failure it actually is.
+ */
+export declare function notApplicableReason(declared: {
+    reason: string;
+    evidence: string;
+} | undefined, msg: string): string | null;
 export interface MeasureOptions {
     timeoutMs?: number;
     env?: Record<string, string>;
@@ -11,6 +47,11 @@ export interface MeasureOptions {
     dummyEnvValues?: Record<string, string>;
     /** Install `git` in the container before launch (docker mode) — see docker.ts. */
     needsGit?: boolean;
+    /** Declared harness limitation for this entry — see `notApplicable` in report.ts. */
+    notApplicable?: {
+        reason: string;
+        evidence: string;
+    };
     /**
      * Exact argv, when the caller already has it (client configs store command and
      * args separately). Avoids re-splitting a joined string on spaces, which would

package/dist/sweep/run.js

@@ -11,6 +11,56 @@ import { captureTools } from './client.js';
 import { DockerHarnessFault, defaultImageFor, dockerize, ensureImage, isDockerRunFailure } from './docker.js';
 import { measureTools, failedMeasurement, canonicalString } from '../core/canonical.js';
 import { toBadge } from '../core/badge.js';
+/**
+ * Which kind of failure a dead server's own words describe.
+ *
+ * The distinction is the published one: `auth-required` says the server works
+ * and this harness has no credentials for it, `startup-failure` says the server
+ * did not come up. Only the text decides, so it matters that the text reaching
+ * here is the part that explains the failure rather than whatever happened to
+ * fall in the last few hundred bytes — see `evidenceTail` in client.ts, which
+ * exists because a truncated message was being filed as a broken server.
+ */
+export function classifyFailure(msg) {
+    // Matched against this harness's own phrasing, not the bare word: these
+    // messages carry the server's stderr, and a server that prints "connection
+    // timeout" before dying did not time out — it exited, and saying otherwise
+    // blames the clock for a breakage.
+    if (/timeout after \d+ms waiting for/.test(msg))
+        return 'timeout';
+    return /auth|unauthorized|401|forbidden|credential|api.?key|token/i.test(msg)
+        ? 'auth-required'
+        : 'startup-failure';
+}
+/**
+ * The architecture a measurement ran on, in Docker's vocabulary (`linux/amd64`).
+ *
+ * Worth recording because a package can ship builds for some architectures and
+ * not others, and then the *machine* decides the result. `local-mcp` sat
+ * published as a startup failure on the strength of a run whose actual finding
+ * was that the laptop was arm64 and the package ships no arm64 runtime — and
+ * the record gave a reader no way to notice.
+ *
+ * Containers are linux whatever the host is; with no explicit `--platform` they
+ * take the host's architecture, so that is the half worth reporting.
+ */
+export function measuringArch(docker) {
+    const arch = process.arch === 'x64' ? 'amd64' : process.arch;
+    return `${docker ? 'linux' : process.platform}/${arch}`;
+}
+/**
+ * The declared reason, when this failure is the one the entry warned about.
+ *
+ * Corroboration is the whole point: an entry may declare that this harness
+ * cannot run it, but only the failure's own words can confirm that *this*
+ * failure is that one. A macOS-only package that starts failing for some new
+ * reason stops matching, and is published as the failure it actually is.
+ */
+export function notApplicableReason(declared, msg) {
+    if (!declared?.evidence)
+        return null;
+    return msg.toLowerCase().includes(declared.evidence.toLowerCase()) ? declared.reason : null;
+}
 function arg(name) {
     const i = process.argv.indexOf(`--${name}`);
     return i >= 0 ? process.argv[i + 1] : undefined;
@@ -135,14 +185,17 @@ export async function measureServer(name, command, opts = {}) {
             if (dockerWrapped && isDockerRunFailure(msg)) {
                 throw new DockerHarnessFault(`docker could not run the container for ${name}: ${msg.slice(0, 400)}`);
             }
-            const status = msg.includes('timeout')
-                ? 'timeout'
-                : /auth|unauthorized|401|forbidden|credential|api.?key|token/i.test(msg)
-                    ? 'auth-required'
-                    : 'startup-failure';
-            r = failedMeasurement(status, { serverName: name, launchCommand: command, notes: msg.slice(0, 700) });
+            const declared = notApplicableReason(opts.notApplicable, msg);
+            r = failedMeasurement(declared ? 'not-applicable' : classifyFailure(msg), {
+                serverName: name,
+                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),
+            });
         }
-        r.isolation = isolation;
+        const iso = isolation ?? { docker: false };
+        r.isolation = { ...iso, arch: measuringArch(iso.docker) };
         r.timeoutMs = attemptOpts.timeoutMs ?? 60_000;
         return r;
     }

package/dist/sweep/session-start.js

@@ -25,6 +25,7 @@ import { join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parse } from 'yaml';
 import { measureServer } from './run.js';
+import { DockerHarnessFault } from './docker.js';
 import { SESSION_START_METHOD, parseSessionStart, toSessionStartRow, } from '../core/session-start.js';
 export function loadSessionStart(root = process.cwd()) {
     const p = join(root, 'results', 'session-start.json');
@@ -63,15 +64,36 @@ if (isMain) {
     const queue = [...entries];
     async function worker() {
         for (let e = queue.shift(); e; e = queue.shift()) {
-            const m = await measureServer(e.name, e.command, {
-                timeoutMs: (e.timeoutSeconds ?? defaultTimeout) * 1000,
-                docker,
-                dockerImage: e.dockerImage,
-                dummyEnv: e.env ?? [],
-                dummyEnvValues: e.envValues,
-                needsGit: e.needsGit,
-                persist: false, // the measurements on disk are not this run's to rewrite
-            });
+            let m;
+            try {
+                m = await measureServer(e.name, e.command, {
+                    timeoutMs: (e.timeoutSeconds ?? defaultTimeout) * 1000,
+                    docker,
+                    dockerImage: e.dockerImage,
+                    dummyEnv: e.env ?? [],
+                    dummyEnvValues: e.envValues,
+                    needsGit: e.needsGit,
+                    persist: false, // the measurements on disk are not this run's to rewrite
+                });
+            }
+            catch (err) {
+                // One thrown error used to reject Promise.all and end the process
+                // before anything was written, discarding every capture the run had
+                // already completed — and skipping the `finally` that force-removes
+                // containers, orphaning the in-flight ones. A machine fault on one
+                // server is recorded against that server; the rest of the run stands.
+                if (!(err instanceof DockerHarnessFault))
+                    throw err;
+                servers[e.name] = {
+                    instructions: '',
+                    instructionsTokens: 0,
+                    instructionsSha256: '',
+                    capturedSha256: null,
+                    error: `docker harness fault: ${err.message.slice(0, 200)}`,
+                };
+                console.log(`  ${e.name}: docker harness fault — recorded, run continues`);
+                continue;
+            }
             if (m.status !== 'measured' && m.status !== 'dynamic') {
                 servers[e.name] = {
                     instructions: '',

package/dist/sweep/sweep-all.js

@@ -18,7 +18,7 @@ import { DockerHarnessFault } from './docker.js';
 import { writeLeaderboard } from './report.js';
 import { appendHistory } from './history.js';
 import { appendToolVectors, writeRegressions } from './regressions.js';
-import { FAULT_RATIO, MIN_REGRESSIONS, snapshot, verdict, restore } from './harness-guard.js';
+import { MIN_REGRESSIONS, snapshot, verdict, restore } from './harness-guard.js';
 import { selectShard, shardIndexForDate } from './shard.js';
 function arg(name) {
     const i = process.argv.indexOf(`--${name}`);
@@ -55,6 +55,18 @@ if (shards !== undefined) {
     const index = shardIndexArg ?? shardIndexForDate(new Date(), shards);
     entries = selectShard(sweepable, shards, index);
     shardLabel = `, shard ${index + 1}/${shards}`;
+    // The harness guard needs MIN_REGRESSIONS previously-good servers to fail
+    // together before it will call a broken runner rather than broken servers.
+    // A slice smaller than that floor can never reach it, so a wedged Docker
+    // daemon would publish the whole slice as startup failures with nothing to
+    // trip. `--shards` is the one knob that can shrink a slice under the floor
+    // unattended, so it refuses here instead of measuring through it.
+    if (entries.length < MIN_REGRESSIONS) {
+        console.error(`--shards ${shards} cuts a ${entries.length}-server slice, below the ` +
+            `${MIN_REGRESSIONS}-server floor the harness guard needs to tell a broken runner ` +
+            `from broken servers. Use a smaller --shards, or --only to measure a handful by name.`);
+        process.exit(2);
+    }
     console.log(`shard ${index + 1}/${shards} of ${sweepable.length} sweepable: ${entries.map((e) => e.name).join(', ')}`);
 }
 console.log(`sweeping ${entries.length} servers (docker=${docker}, concurrency=${concurrency}${shardLabel})`);
@@ -81,6 +93,7 @@ async function worker() {
                 dummyEnv: e.env ?? [],
                 dummyEnvValues: e.envValues,
                 needsGit: e.needsGit,
+                notApplicable: e.notApplicable,
             });
         }
         catch (err) {
@@ -101,24 +114,25 @@ async function worker() {
     }
 }
 await Promise.all(Array.from({ length: Math.max(1, concurrency) }, () => worker()));
-// A docker fault on most of the slice is the harness-fault story with an
-// earlier symptom — the guard below can't see it (nothing regressed on disk;
-// the throws happened before anything was written), so it is judged here by
-// the guard's own thresholds. Below them, the sweep publishes what it did
-// measure and the faulted servers wait for the next cycle.
-if (dockerFaults.size >= MIN_REGRESSIONS && dockerFaults.size / entries.length >= FAULT_RATIO) {
-    console.error(`\nHARNESS FAULT — docker could not run for ${dockerFaults.size} of ${entries.length} servers; ` +
-        `refusing to publish this sweep.\n` +
-        [...dockerFaults].map(([n, msg]) => `  ${n}: ${msg}`).join('\n') +
-        `\n  Nothing was overwritten — every previous record stands. ` +
-        `Check the Docker daemon and registry path, then re-run.`);
-    process.exit(1);
-}
 // Before publishing anything: is this sweep a statement about the servers, or
 // about the machine that measured them?
-const v = verdict(prior, statuses);
+//
+// The two symptoms are counted together, against one denominator. Judged apart
+// they were each other's blind spot: a flaky daemon that throws for 6 of 14
+// servers (6 ≥ 5, but 43% of the slice) and times out 4 more (4 < 5) trips
+// neither threshold, and the sweep publishes with 10 of 14 servers producing no
+// number and four good records overwritten with failures. A server that could
+// have produced a number and didn't is one fact, however it failed.
+const v = verdict(prior, statuses, dockerFaults.size);
 console.log(`harness check: ${v.reason}`);
+if (dockerFaults.size > 0 && !v.fault) {
+    console.warn(`  (${dockerFaults.size} docker fault(s) counted toward that check; those servers were not measured)`);
+}
 if (v.fault) {
+    if (dockerFaults.size) {
+        console.error(`\ndocker could not run for ${dockerFaults.size} server(s):\n` +
+            [...dockerFaults].map(([n, msg]) => `  ${n}: ${msg}`).join('\n'));
+    }
     const restored = restore(prior, v.regressed);
     console.error(`\nHARNESS FAULT — refusing to publish this sweep.\n` +
         `  regressed: ${v.regressed.join(', ')}\n` +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-context-cost",
-  "version": "0.11.2",
+  "version": "0.12.0",
   "description": "Measure what your MCP servers cost in context tokens — audit your own config, or badge the server you publish",
   "type": "module",
   "license": "MIT",