mcp-context-cost 0.11.1 → 0.11.3

package/README.md

@@ -278,7 +278,7 @@ now measured against a pinned model and published beside the badge, and they do
 
 | server | badge (o200k) | Claude (`claude-opus-5`) | |
 |---|---:|---:|---|
-| github | 54,422 | **18,406** | 81% of the capture is `annotations`/`outputSchema` metadata Claude never sees |
+| github | 54,622 | **—** | 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/audit.d.ts

@@ -151,6 +151,13 @@ export interface AuditReport {
         worstTotal: number;
         worstSource: string;
         over: boolean;
+        /**
+         * Servers in the audited configs with no number, when there are any. Their
+         * cost is missing from `worstTotal`, so the budget could not be checked
+         * against the whole stack and the verdict fails rather than passing on a
+         * total that understates by an unknown amount.
+         */
+        unestablished?: string[];
         /** Present only when over budget: the arithmetic of getting back under it. */
         fit?: BudgetFit;
     };

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.
@@ -319,12 +326,21 @@ export function buildReport(configs, measured, opts = {}) {
         // The worst config is the gate: passing because your *lightest* client fits
         // would be a green check on a session you don't run.
         const worst = results[0];
+        // A total is only a ceiling to compare against if it is the whole cost. A
+        // server that failed to start contributes 0, so the stack reads lighter
+        // than it is and the budget passes on a number that is missing a server —
+        // exactly the PR the README says this gate catches. The server-level gate
+        // (core/server-diff.ts) already refuses this; so does this one now.
+        const unestablished = results.flatMap((c) => c.skipped.filter((s) => s.status !== 'remote-not-measurable').map((s) => `${c.source}: ${s.name} (${s.status})`));
         const over = (worst?.totalTokens ?? 0) > opts.budget;
         report.budget = {
             limit: opts.budget,
             worstTotal: worst?.totalTokens ?? 0,
             worstSource: worst?.source ?? '(none)',
-            over,
+            over: over || unestablished.length > 0,
+            // Named so the reader knows which way the number is wrong: the total
+            // understates by however much these cost, which nobody knows.
+            unestablished: unestablished.length ? unestablished : undefined,
             fit: over && worst ? planBudgetFit(worst, opts.budget) : undefined,
         };
     }
@@ -739,6 +755,15 @@ export function formatReport(report) {
             const headroom = b.limit - b.worstTotal;
             lines.push(`budget ok: ${n(b.worstTotal)} ≤ ${n(b.limit)} — ${n(headroom)} to spare`);
         }
+        else if (b.unestablished && b.worstTotal <= b.limit) {
+            // Under the line on what was measured, but not everything was: say which
+            // way the number is wrong rather than passing on it.
+            lines.push(`BUDGET FAIL: ${n(b.worstTotal)} ≤ ${n(b.limit)}, but the budget could not be checked against the ` +
+                `whole stack — ${b.unestablished.length} server(s) produced no number, so this total understates ` +
+                `by however much they cost:`);
+            for (const u of b.unestablished)
+                lines.push(`  ${u}`);
+        }
         else {
             lines.push(`BUDGET FAIL: ${n(b.worstTotal)} > ${n(b.limit)} (${b.worstSource})`);
             const fit = b.fit;

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

@@ -21,6 +21,17 @@ export function parseBaselineReport(text) {
         if (!c || typeof c !== 'object' || typeof c.source !== 'string') {
             return { report: null, problem: 'baseline has a config entry without a source path' };
         }
+        // The number the diff subtracts from. Unchecked, a hand-trimmed or
+        // jq-filtered baseline yields `after - undefined === NaN`, and `typeof NaN`
+        // is 'number' — so the gate reported an increase of 0 and passed. A
+        // baseline that cannot be read is never "no change".
+        const total = c.totalTokens;
+        if (typeof total !== 'number' || !Number.isFinite(total)) {
+            return {
+                report: null,
+                problem: `baseline config ${c.source} has no usable totalTokens — is it the output of \`audit --json\`?`,
+            };
+        }
     }
     return { report: doc };
 }
@@ -69,9 +80,25 @@ export function diffConfig(before, after, matchedBy) {
             continue;
         }
         if (!bs && as) {
-            servers.push(as.tokens === null
-                ? { name, kind: 'added', before: null, after: null, delta: null, note: 'added but not measurable — its cost is unknown, not zero' }
-                : { name, kind: 'added', before: null, after: as.tokens, delta: as.tokens });
+            if (as.tokens === null) {
+                // Unknown, not zero — so the total this diff subtracts from does not
+                // contain it and the increase understates. Marking the config inexact
+                // is what stops `--max-increase` from passing: a server added in a PR
+                // and unmeasurable in CI (no credential — the ordinary case) otherwise
+                // reads as +0 and clears even a zero-token allowance.
+                exact = false;
+                servers.push({
+                    name,
+                    kind: 'added',
+                    before: null,
+                    after: null,
+                    delta: null,
+                    note: 'added but not measurable — its cost is unknown, not zero',
+                });
+            }
+            else {
+                servers.push({ name, kind: 'added', before: null, after: as.tokens, delta: as.tokens });
+            }
             continue;
         }
         if (!bs || !as)
@@ -154,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);
     }
@@ -298,13 +333,17 @@ export function evaluateIncreaseGate(diff, limit) {
             reasons.push(`${c.source}: no baseline to check its ${n(c.afterTotal)} tokens against`);
         }
         else if (!c.exact) {
-            reasons.push(`${c.source}: a server changed measured-ness, so the change could not be established exactly`);
+            reasons.push(`${c.source}: a server's cost is not established on both sides, so the change could not be established exactly`);
         }
     }
     for (const d of diff.droppedConfigs) {
         reasons.push(`${d.source}: covered by the baseline and not found in this run`);
     }
-    const increase = diff.worstIncrease?.delta ?? (diff.configs.some((c) => typeof c.delta === 'number') ? 0 : null);
+    // `Number.isFinite`, not `typeof === 'number'`: NaN passes the latter and
+    // then compares false against every limit, which is a silent pass.
+    const anyDelta = diff.configs.some((c) => Number.isFinite(c.delta));
+    const worst = diff.worstIncrease?.delta;
+    const increase = Number.isFinite(worst) ? worst : anyDelta ? 0 : null;
     if (reasons.length === 0 && increase !== null && increase > limit) {
         reasons.push(`${diff.worstIncrease.source}: +${n(increase)} tokens per request, over the ${n(limit)} allowed`);
     }

package/dist/cli.d.ts

@@ -27,6 +27,11 @@ export declare function unknownFlags(argv: string[], spec: {
     value: string[];
     boolean: string[];
 }): string[];
+/** Every flag name a command accepts — what tells a value apart from the next flag. */
+export declare const knownFlagNames: (spec: {
+    value: string[];
+    boolean: string[];
+}) => Set<string>;
 /**
  * Every value a value-taking flag was given, in either accepted spelling:
  * `--flag value` and `--flag=value`.
@@ -37,9 +42,9 @@ export declare function unknownFlags(argv: string[], spec: {
  * matched the bare token, so the gate it asked for silently did not run and the
  * command exited 0 — a green check on a check that never happened.
  */
-export declare function flagValues(argv: string[], name: string): string[];
+export declare function flagValues(argv: string[], name: string, known?: Set<string>): string[];
 /** The last value given for a flag, or undefined when the flag is absent. */
-export declare function flagValue(argv: string[], name: string): string | undefined;
+export declare function flagValue(argv: string[], name: string, known?: Set<string>): string | undefined;
 /**
  * Value-taking flags that appear with no usable value.
  *

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 {
@@ -85,6 +98,21 @@ export function unknownFlags(argv, spec) {
     }
     return unknown;
 }
+/**
+ * Whether a token is another flag of *this* command, rather than a value that
+ * merely looks like one.
+ *
+ * The distinction is load-bearing: `--command "--weird"` is a legitimate launch
+ * command this CLI has always accepted, while `--max-increase --json` is a
+ * value slot swallowed by the next flag. Deciding on the `--` prefix alone
+ * cannot tell them apart; deciding against the command's own flag list can, and
+ * the list is already declared at every call site.
+ */
+function isKnownFlagToken(tok, known) {
+    return tok.startsWith('--') && known.has(tok.slice(2).split('=')[0]);
+}
+/** Every flag name a command accepts — what tells a value apart from the next flag. */
+export const knownFlagNames = (spec) => new Set([...spec.value, ...spec.boolean]);
 /**
  * Every value a value-taking flag was given, in either accepted spelling:
  * `--flag value` and `--flag=value`.
@@ -95,15 +123,15 @@ export function unknownFlags(argv, spec) {
  * matched the bare token, so the gate it asked for silently did not run and the
  * command exited 0 — a green check on a check that never happened.
  */
-export function flagValues(argv, name) {
+export function flagValues(argv, name, known = new Set()) {
     const out = [];
     for (let i = 0; i < argv.length; i++) {
         const tok = argv[i];
         if (tok === `--${name}`) {
             const next = argv[i + 1];
-            // A following flag is not this flag's value; that case is a usage error,
-            // caught by `valuelessFlags`, and must not be read as a value here.
-            if (next !== undefined && !next.startsWith('--'))
+            // Another flag of this command is not this flag's value; that case is a
+            // usage error, caught by `valuelessFlags`, and never read as a value.
+            if (next !== undefined && !isKnownFlagToken(next, known))
                 out.push(next);
             continue;
         }
@@ -113,8 +141,8 @@ export function flagValues(argv, name) {
     return out;
 }
 /** The last value given for a flag, or undefined when the flag is absent. */
-export function flagValue(argv, name) {
-    const values = flagValues(argv, name);
+export function flagValue(argv, name, known = new Set()) {
+    const values = flagValues(argv, name, known);
     return values.length ? values[values.length - 1] : undefined;
 }
 /**
@@ -128,6 +156,7 @@ export function flagValue(argv, name) {
  * so it is refused in the same place and with the same severity.
  */
 export function valuelessFlags(argv, spec) {
+    const known = knownFlagNames(spec);
     const bad = [];
     for (let i = 0; i < argv.length; i++) {
         const tok = argv[i];
@@ -142,7 +171,7 @@ export function valuelessFlags(argv, spec) {
             continue;
         }
         const next = argv[i + 1];
-        if (next === undefined || next.startsWith('--'))
+        if (next === undefined || isKnownFlagToken(next, known))
             bad.push(`--${name}`);
         else
             i++; // consume the value, so `--command "--weird"` is not re-read as a flag
@@ -169,7 +198,7 @@ function rejectUnknownFlags(cmd, argv, spec) {
 }
 const [, , cmd, ...rest] = process.argv;
 if (cmd === 'audit') {
-    rejectUnknownFlags('audit', rest, {
+    const spec = {
         value: [
             'config',
             'budget',
@@ -183,9 +212,14 @@ if (cmd === 'audit') {
             'capture-index-url',
         ],
         boolean: ['json', 'docker', 'claude', 'suggest', 'changed'],
-    });
-    const argOf = (name) => flagValue(rest, name);
-    const all = (name) => flagValues(rest, name);
+    };
+    rejectUnknownFlags('audit', rest, spec);
+    // The same flag list the rejection used, so a value that merely looks like a
+    // flag (`--command "--weird"`) is told apart from a value slot swallowed by
+    // the next flag.
+    const known = knownFlagNames(spec);
+    const argOf = (name) => flagValue(rest, name, known);
+    const all = (name) => flagValues(rest, name, known);
     const json = rest.includes('--json');
     const numeric = (name) => {
         const raw = argOf(name);
@@ -301,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>`);
@@ -315,9 +355,10 @@ if (cmd === 'audit') {
     process.exit(report.budget?.over || report.increaseGate?.pass === false ? 1 : 0);
 }
 else if (cmd === 'verify') {
-    rejectUnknownFlags('verify', rest, { value: ['remote'], boolean: ['json'] });
+    const spec = { value: ['remote'], boolean: ['json'] };
+    rejectUnknownFlags('verify', rest, spec);
     const json = rest.includes('--json');
-    const remoteUrl = flagValue(rest, 'remote');
+    const remoteUrl = flagValue(rest, 'remote', knownFlagNames(spec));
     const path = rest.find((a) => !a.startsWith('--') && a !== remoteUrl);
     if (!remoteUrl && !path) {
         console.error('usage: mcp-context-cost verify <measurement.json> [--json]');
@@ -333,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 }));
@@ -361,11 +413,13 @@ else if (cmd === 'verify') {
     process.exit(1);
 }
 else if (cmd === 'measure') {
-    rejectUnknownFlags('measure', rest, {
+    const spec = {
         value: ['name', 'command', 'remote', 'timeout', 'docker-image', 'baseline', 'max-increase', 'budget'],
         boolean: ['docker'],
-    });
-    const argOf = (name) => flagValue(rest, name);
+    };
+    rejectUnknownFlags('measure', rest, spec);
+    const known = knownFlagNames(spec);
+    const argOf = (name) => flagValue(rest, name, known);
     const command = argOf('command');
     const remoteUrl = argOf('remote');
     if (remoteUrl && !/^https?:\/\//i.test(remoteUrl)) {

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 = [];
@@ -162,13 +178,36 @@ export function latestChange(server, rows, vectors) {
     if (deltaTokens === 0 && deltaTools === 0)
         return null;
     const deltaPct = from.tokens > 0 ? (deltaTokens / from.tokens) * 100 : 0;
-    // Attribution needs both sides on record, matched by date. A vector file that
-    // only holds the newer capture explains nothing about how the server got there.
+    // Attribution needs both sides on record. Matched by *cost as of that date*,
+    // not by date equality: vectors are deduped by capture and keep the first
+    // date a capture was seen, while `from` is the last row of the previous
+    // plateau — so the two dates coincide only when the previous cost was
+    // measured exactly once. With weekly sweeps and less frequent releases they
+    // almost never do, and a date-equality join therefore reported "only one of
+    // the two captures is on record" while holding both. The vector in force on a
+    // given day is the newest one recorded on or before it.
     let attribution = null;
-    const fromVec = vectors?.entries.find((e) => e.date === from.date);
-    const toVec = vectors?.entries.find((e) => e.date === to.date);
-    if (fromVec && toVec)
+    const inForceOn = (date, tokensThatDay) => {
+        const upto = (vectors?.entries ?? []).filter((e) => e.date <= date);
+        // A same-day re-sweep replaces that day's history row but *appends* a
+        // capture, so one date can carry two. Only one of them is the one the row
+        // describes: prefer the capture whose total is the number history recorded.
+        const agreeing = upto.filter((e) => e.totalTokens === tokensThatDay);
+        const pool = agreeing.length > 0 ? agreeing : upto;
+        return pool.reduce((best, e) => (!best || e.date >= best.date ? e : best), undefined);
+    };
+    const fromVec = inForceOn(from.date, from.tokens);
+    const toVec = inForceOn(to.date, to.tokens);
+    // A vector only explains the row it agrees with. If the totals disagree the
+    // file does not cover this change — say so rather than attributing a delta
+    // to the wrong capture and publishing the mismatch as framing bytes.
+    if (fromVec &&
+        toVec &&
+        fromVec.canonicalSha256 !== toVec.canonicalSha256 &&
+        fromVec.totalTokens === from.tokens &&
+        toVec.totalTokens === to.tokens) {
         attribution = attribute(fromVec, toVec, deltaTokens);
+    }
     return {
         server,
         fromDate: from.date,

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/sweep/dashboard.js

@@ -6,6 +6,8 @@
 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. */
@@ -52,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));
@@ -74,7 +75,12 @@ export function generateDashboard(root = process.cwd()) {
         const meta = BAND_META[band];
         const largest = [...m.tools].sort((a, b) => b.tokens - a.tokens)[0];
         const pct = Math.max(1.2, (t / max) * 100);
-        const div = dSrv[r.entry.name];
+        // Gated on the capture it was computed from, exactly as the leaderboard
+        // gates it: four rows here were publishing a Claude cost derived from
+        // bytes that no longer exist, while leaderboard.md printed `—` for the
+        // same four.
+        const dRaw = dSrv[r.entry.name];
+        const div = isCurrent(dRaw, m.canonicalSha256 ?? null) ? dRaw : undefined;
         const claudeTip = div ? ` · in a Claude request: ${fmt(div.claudeDelta)} tok` : '';
         const series = seriesFor(r.entry.name);
         const tokens = series.rows.map((h) => h.tokens);
@@ -107,10 +113,15 @@ export function generateDashboard(root = process.cwd()) {
     const tableRows = measured
         .map((r, i) => {
         const m = r.m;
-        const div = dSrv[r.entry.name];
+        // Gated on the capture it was computed from, exactly as the leaderboard
+        // gates it: four rows here were publishing a Claude cost derived from
+        // bytes that no longer exist, while leaderboard.md printed `—` for the
+        // same four.
+        const dRaw = dSrv[r.entry.name];
+        const div = isCurrent(dRaw, m.canonicalSha256 ?? null) ? dRaw : undefined;
         const tokens = seriesFor(r.entry.name).rows.map((h) => h.tokens);
         const trend = tokens.length > 1
-            ? `${tokens[tokens.length - 1] - tokens[0] >= 0 ? '+' : ''}${fmt(tokens[tokens.length - 1] - tokens[0])} / ${tokens.length}d`
+            ? `${tokens[tokens.length - 1] - tokens[0] >= 0 ? '+' : ''}${fmt(tokens[tokens.length - 1] - tokens[0])} over ${tokens.length} sweeps`
             : '—';
         return `<tr><td>${i + 1}</td><td>${esc(r.entry.name)}</td><td class="num">${fmt(m.totalTokens)}</td><td class="num">${div ? fmt(div.claudeDelta) : '—'}</td><td class="num">${esc(m.toolCount)}</td><td>${esc(BAND_META[bandColor(m.totalTokens)].label)}</td><td>${esc(r.entry.category)}</td><td class="num">${trend}</td></tr>`;
     })
@@ -227,7 +238,7 @@ export function generateDashboard(root = process.cwd()) {
   </div>
 
   <h2>Leaderboard</h2>
-  <p class="h2sub">Tokens = o200k_base count of the canonical <code>tools/list</code> bytes — the wire payload. What a <em>Claude request</em> actually carries can differ sharply (github: 54,422 on the wire, ${dSrv['github'] ? fmt(dSrv['github'].claudeDelta) : '…'} in a request — 80% of its schema bytes are fields no Anthropic request sends). The trend line plots tokens across every sweep date on record (oldest→newest, dot = current); servers with one sweep so far show no line yet, and a sweep taken under different isolation than the current one is left out rather than drawn as a change in the server. Hover a row for exact numbers; <a href="METHODOLOGY.html#claude-divergence">method</a>.</p>
+  <p class="h2sub">Tokens = o200k_base count of the canonical <code>tools/list</code> bytes — the wire payload. What a <em>Claude request</em> actually carries can differ sharply (a server can spend most of its schema bytes on fields no Anthropic request sends, and the denser tokenizer can push the rest back up). The trend line plots tokens across every sweep date on record (oldest→newest, dot = current); servers with one sweep so far show no line yet, and a sweep taken under different isolation than the current one is left out rather than drawn as a change in the server. Hover a row for exact numbers; <a href="METHODOLOGY.html#claude-divergence">method</a>.</p>
   <div class="board">
 ${barRows || '<p class="h2sub">Sweep in progress — first results land shortly.</p>'}
   </div>

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/published-stats.d.ts

@@ -28,17 +28,22 @@ export interface PublishedStats {
         /** Rows the leaderboard prints a claude number for: measured AND capture-current. */
         currentCount: number;
         heaviestClaudeName: string | null;
+        /** `claudeTokens` is null when the published row no longer matches the capture on disk. */
         github: {
             badgeTokens: number;
-            mappedTokens: number;
-            claudeTokens: number;
-            droppedPct: number;
+            claudeTokens: number | null;
         };
         notion: {
             badgeTokens: number;
-            claudeTokens: number;
+            claudeTokens: number | null;
         };
-        /** Field-selection share across the run's rows, as fractions of the payload. */
+        /** The current row showing the largest field-selection effect, and its two counts. */
+        widest: {
+            server: string;
+            full: number;
+            mapped: number;
+        };
+        /** Field-selection share across the run's *current* rows, as fractions of the payload. */
         shareMin: number;
         shareMax: number;
         /** claudeDelta / o200kFull across the run's rows that carry a number. */

package/dist/sweep/published-stats.js

@@ -75,25 +75,48 @@ export function computePublishedStats(entries, root = process.cwd()) {
     }
     if (!div)
         throw new Error('results/divergence.json is missing — README states its numbers');
-    const divRow = (name) => {
+    /**
+     * A divergence row only where it still describes the capture on disk.
+     *
+     * The staleness gate is the whole discipline of this column, and skipping it
+     * here is how README came to print two different costs for github on one
+     * page: 54,422 from a row computed against bytes that no longer existed,
+     * beside 54,622 from the measurement. `withClaude` below already applied
+     * `isCurrent` to the very same run — the rule guarded one number and not its
+     * neighbour.
+     */
+    const currentDivRow = (name) => {
         const d = div.servers[name];
         if (!d)
             throw new Error(`README's Claude table names ${name}, which is not in the divergence run`);
-        return d;
+        const onDisk = rows.find((r) => r.entry.name === name)?.m?.canonicalSha256 ?? null;
+        return isCurrent(d, onDisk) ? d : null;
     };
-    const github = divRow('github');
-    const notion = divRow('notion');
-    const githubShare = fieldSelectionShare(github);
-    if (githubShare === null)
-        throw new Error('divergence run carries no o200k counts for github');
-    const runRows = Object.values(div.servers);
-    const shares = runRows.map((r) => fieldSelectionShare(r)).filter((s) => s !== null);
-    const ratios = runRows
-        .filter((r) => typeof r.claudeDelta === 'number' && r.claudeDelta > 0 && r.o200kFull > 0)
-        .map((r) => r.claudeDelta / r.o200kFull);
+    /** The badge number comes from the measurement, never from a divergence row's copy of it. */
+    const badgeTokensOf = (name) => {
+        const r = measured.find((x) => x.entry.name === name);
+        if (!r)
+            throw new Error(`README's Claude table names ${name}, which has no current measurement`);
+        return r.m.totalTokens;
+    };
+    // Ranges are stated over the rows that are still current, for the same
+    // reason: a range whose endpoint comes from a superseded capture describes a
+    // set that no longer exists.
+    const currentRows = Object.entries(div.servers).filter(([name, r]) => isCurrent(r, rows.find((x) => x.entry.name === name)?.m?.canonicalSha256 ?? null));
+    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) {
-        throw new Error('divergence run carries no usable rows — METHODOLOGY states its ranges');
+        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
+    // current row shows it most, rather than a server hardcoded into the prose.
+    const widest = currentRows
+        .filter(([, r]) => (fieldSelectionShare(r) ?? -1) >= 0)
+        .sort((a, b) => (fieldSelectionShare(b[1]) ?? 0) - (fieldSelectionShare(a[1]) ?? 0))[0];
     const withClaude = measured.filter((r) => isCurrent(div.servers[r.entry.name], r.m.canonicalSha256));
     const heaviest = [...withClaude].sort((a, b) => div.servers[b.entry.name].claudeDelta - div.servers[a.entry.name].claudeDelta)[0];
     const costlier = measured.filter((r) => {
@@ -118,13 +141,9 @@ export function computePublishedStats(entries, root = process.cwd()) {
             runSize: Object.keys(div.servers).length,
             currentCount: withClaude.length,
             heaviestClaudeName: heaviest?.entry.name ?? null,
-            github: {
-                badgeTokens: github.o200kFull,
-                mappedTokens: github.o200kMapped,
-                claudeTokens: github.claudeDelta,
-                droppedPct: Math.round(githubShare * 100),
-            },
-            notion: { badgeTokens: notion.o200kFull, claudeTokens: notion.claudeDelta },
+            github: { badgeTokens: badgeTokensOf('github'), claudeTokens: currentDivRow('github')?.claudeDelta ?? null },
+            notion: { badgeTokens: badgeTokensOf('notion'), claudeTokens: currentDivRow('notion')?.claudeDelta ?? null },
+            widest: { server: widest[0], full: widest[1].o200kFull, mapped: widest[1].o200kMapped },
             shareMin: Math.min(...shares),
             shareMax: Math.max(...shares),
             ratioMin: Math.min(...ratios),
@@ -140,6 +159,8 @@ export function computePublishedStats(entries, root = process.cwd()) {
 }
 export const PAGE_FILES = ['README.md', 'docs/index.md', 'docs/METHODOLOGY.md'];
 const fmt = (n) => n.toLocaleString('en-US');
+/** A number, or the em-dash that means "no current measurement" everywhere else here. */
+const q = (n) => (n === null ? '—' : fmt(n));
 export const PAGE_CLAIMS = [
     {
         file: 'README.md',
@@ -210,14 +231,14 @@ export const PAGE_CLAIMS = [
     {
         file: 'README.md',
         id: 'claude-table:github',
-        template: '| github | {n} | **{n}** | {d}% of the capture is `annotations`/`outputSchema` metadata Claude never sees |',
-        values: (s) => [fmt(s.claude.github.badgeTokens), fmt(s.claude.github.claudeTokens), String(s.claude.github.droppedPct)],
+        template: '| github | {n} | **{q}** | most of the capture is `annotations`/`outputSchema` metadata Claude never sees |',
+        values: (s) => [fmt(s.claude.github.badgeTokens), q(s.claude.github.claudeTokens)],
     },
     {
         file: 'README.md',
         id: 'claude-table:notion',
-        template: '| notion | {n} | **{n}** | almost no metadata to drop, so the tokenizer difference dominates |',
-        values: (s) => [fmt(s.claude.notion.badgeTokens), fmt(s.claude.notion.claudeTokens)],
+        template: '| notion | {n} | **{q}** | almost no metadata to drop, so the tokenizer difference dominates |',
+        values: (s) => [fmt(s.claude.notion.badgeTokens), q(s.claude.notion.claudeTokens)],
     },
     {
         file: 'README.md',
@@ -252,12 +273,15 @@ export const PAGE_CLAIMS = [
     {
         file: 'docs/METHODOLOGY.md',
         id: 'divergence:share-range',
-        template: 'this removes between {f}% and **{f}%** of the payload (github: {n} → {n} tokens).',
+        template: 'this removes between {f}% and **{f}%** of the payload ({w}: {n} → {n} tokens).',
+        // The exemplar is whichever current row shows the effect most, not a server
+        // named in the prose — a hardcoded name goes stale the week it is re-swept.
         values: (s) => [
             (s.claude.shareMin * 100).toFixed(1),
             (s.claude.shareMax * 100).toFixed(1),
-            fmt(s.claude.github.badgeTokens),
-            fmt(s.claude.github.mappedTokens),
+            s.claude.widest.server,
+            fmt(s.claude.widest.full),
+            fmt(s.claude.widest.mapped),
         ],
     },
     {
@@ -303,7 +327,7 @@ const escapeLiteral = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&').replace(/\
 export function compileTemplate(template) {
     let source = '';
     let last = 0;
-    for (const slot of template.matchAll(/\{[ndwf]\}/g)) {
+    for (const slot of template.matchAll(/\{[ndwfq]\}/g)) {
         source += escapeLiteral(template.slice(last, slot.index));
         source +=
             slot[0] === '{n}'
@@ -312,7 +336,11 @@ export function compileTemplate(template) {
                     ? '(\\d+)'
                     : slot[0] === '{f}'
                         ? '(\\d+\\.\\d+)'
-                        : '([A-Za-z0-9._-]+)';
+                        : // `{q}` is a number that may not exist: the em-dash the leaderboard
+                            // already prints for a row whose capture has moved on.
+                            slot[0] === '{q}'
+                                ? '([\\d,]+|—)'
+                                : '([A-Za-z0-9._-]+)';
         last = slot.index + slot[0].length;
     }
     source += escapeLiteral(template.slice(last));

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/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 { snapshot, verdict, restore } from './harness-guard.js';
 import { selectShard, shardIndexForDate } from './shard.js';
 function arg(name) {
     const i = process.argv.indexOf(`--${name}`);
@@ -101,24 +101,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.1",
+  "version": "0.11.3",
   "description": "Measure what your MCP servers cost in context tokens — audit your own config, or badge the server you publish",
   "type": "module",
   "license": "MIT",