mcp-context-cost 0.4.0 → 0.6.0

package/dist/core/canonical.js

@@ -52,6 +52,9 @@ export function measureTools(tools, meta) {
         serverVersion: meta.serverVersion,
         launchCommand: meta.launchCommand,
         envVarNames: meta.envVarNames,
+        // Left undefined (and so absent from the JSON) when the caller had nothing
+        // to record, which is exactly how a pre-field measurement reads.
+        serverInstructions: meta.instructions,
     };
 }
 export function failedMeasurement(status, meta) {

package/dist/core/index.d.ts

@@ -1,6 +1,7 @@
 export * from './types.js';
 export * from './canonical.js';
 export * from './divergence.js';
+export * from './session-start.js';
 export * from './bands.js';
 export * from './badge.js';
 export * from './snippet.js';

package/dist/core/index.js

@@ -1,6 +1,7 @@
 export * from './types.js';
 export * from './canonical.js';
 export * from './divergence.js';
+export * from './session-start.js';
 export * from './bands.js';
 export * from './badge.js';
 export * from './snippet.js';

package/dist/core/session-start.d.ts

@@ -0,0 +1,102 @@
+import type { Measurement } from './types.js';
+/** Method identifier, versioned independently of METHODOLOGY_VERSION. */
+export declare const SESSION_START_METHOD = "deferred-load/v1";
+/**
+ * Tool names in server-returned order. A tool without a usable name is dropped
+ * rather than given a placeholder — the same rule `toAnthropicTools` follows,
+ * for the same reason: an invented name would change the count being published.
+ */
+export declare function toolNames(raw: unknown[]): string[];
+/**
+ * o200k count of the canonical tool-name list: `JSON.stringify` over the name
+ * array, the same serialization discipline as the headline number, so both
+ * re-derive from the same capture with the same five lines.
+ */
+export declare function toolNameTokens(raw: unknown[]): number;
+/**
+ * The two halves are counted separately and added, rather than counted over one
+ * concatenated string. Concatenation would let boundary tokens merge across the
+ * seam, so the published total would not equal the sum of the parts printed
+ * beside it — a discrepancy of a token or two that no reader could account for.
+ */
+export declare function sessionStartTokens(raw: unknown[], instructions: string | null): number;
+/** One server's instructions, captured beside — not inside — a measurement. */
+export interface SessionStartRow {
+    /** Exactly what `initialize` returned; '' when the server returned none. */
+    instructions: string;
+    instructionsTokens: number;
+    /** SHA-256 of the instructions bytes — the dispute artifact, as ever. */
+    instructionsSha256: string;
+    /**
+     * `canonicalSha256` of the measurement this capture stood beside. A re-sweep
+     * moves that hash, which marks the row stale: instructions are a property of
+     * the same server build that produced the tools, so a changed tool set is
+     * reason enough to stop trusting the instructions captured with the old one.
+     */
+    capturedSha256: string | null;
+    serverVersion?: string;
+    /** Set when the server could not be reached; no numbers are published. */
+    error?: string;
+}
+export interface SessionStartRun {
+    method: string;
+    /** UTC day the instructions were captured (YYYY-MM-DD). */
+    measuredAt: string;
+    /** How the servers were isolated during the capture. */
+    isolation?: string;
+    servers: Record<string, SessionStartRow>;
+}
+/** Where the instructions half of a figure came from — or that it is missing. */
+export type InstructionsSource = 'measurement' | 'capture' | 'not-captured';
+export interface SessionStartLoad {
+    toolCount: number;
+    toolNameTokens: number;
+    /** null when instructions have never been captured for this server. */
+    instructionsTokens: number | null;
+    /** Names plus instructions; names alone when instructions are unknown. */
+    totalTokens: number;
+    /** True when `totalTokens` is a lower bound, not a measurement. */
+    isFloor: boolean;
+    instructionsSource: InstructionsSource;
+}
+/**
+ * The instructions recorded *inside* a measurement, distinguishing three states
+ * that JSON round-trips faithfully:
+ *   - a string  → captured, the server sent this
+ *   - null      → captured, the server sent none
+ *   - undefined → never captured (every measurement predating the field)
+ *
+ * Absent-means-unknown rather than absent-means-zero, on the precedent set by
+ * history.csv's `isolation` column: an old row reads as unknown and is never
+ * back-filled from a value it did not record.
+ */
+export declare function measuredInstructions(m: Measurement): string | undefined;
+/**
+ * Resolve one server's session-start load from its measurement and, if it has
+ * one, the instructions captured beside it.
+ *
+ * Precedence is measurement over capture and never the other way round: the
+ * measurement's instructions came off the same server process as its tools, in
+ * the same run, so it cannot be stale relative to itself. The side capture is
+ * the backfill for measurements taken before the field existed, and it is used
+ * only while it still points at the measurement on disk.
+ *
+ * Returns null for a measurement with no capture to read names from — a
+ * `startup-failure` has no session-start load because it has no session.
+ */
+export declare function sessionStartLoad(m: Measurement, row?: SessionStartRow): SessionStartLoad | null;
+/**
+ * A side capture is usable only if it carries a number and still points at the
+ * measurement on disk. Unlike a stale divergence row — which is hidden, because
+ * there is nothing else to print — a stale row here degrades the figure to its
+ * names-only floor. The column never blanks; it only ever stops claiming to
+ * know the half it no longer knows.
+ */
+export declare function isCurrentInstructions(row: SessionStartRow | undefined, canonicalSha256: string | null): row is SessionStartRow;
+/** Build a row from a freshly captured instructions string. */
+export declare function toSessionStartRow(instructions: string | null, meta: {
+    capturedSha256: string | null;
+    serverVersion?: string;
+}): SessionStartRow;
+/** Parse results/session-start.json; anything malformed yields null, never throws. */
+export declare function parseSessionStart(text: string): SessionStartRun | null;

package/dist/core/session-start.js

@@ -0,0 +1,186 @@
+/**
+ * Session-start load — what a client actually puts in context when it defers
+ * tool definitions until they are used.
+ *
+ * The headline number counts every byte of `tools/list`, because that is what a
+ * client loading definitions eagerly pays. Clients increasingly do not: they put
+ * a *list of names* in context and fetch the definition only when the model
+ * reaches for the tool. That client pays a different bill at session start, and
+ * the headline number says nothing about it.
+ *
+ * Different, and usually far smaller — but *not* smaller by construction, and
+ * nothing here may claim it is. Only one of the two halves below is bounded by
+ * the definitions being deferred. Instructions are separate bytes that no part
+ * of the headline counts, and their length has nothing to do with the size of
+ * the tool set, so a server that re-lists its tools in its `instructions`
+ * charges a deferring client *more* than an eager one. That is not
+ * hypothetical: it is true of a server on the published leaderboard, which is
+ * the most useful thing this measurement has found, and every renderer of these
+ * numbers is expected to let the reader see it rather than smooth it away.
+ *
+ * Two quantities make up that bill, and only one of them is in the published
+ * capture:
+ *
+ * 1. **Tool names.** Derivable from `rawToolsCapture` — no re-measurement
+ *    needed, and re-derivable by anyone from the same published bytes.
+ * 2. **Server instructions.** The `instructions` string a server returns from
+ *    `initialize`. It is *not* part of `tools/list` and so is absent from every
+ *    measurement recorded before this field existed.
+ *
+ * Which means a row can be in one of two honest states, and they are not the
+ * same claim: an exact figure (both halves known), or a **floor** (names
+ * measured, instructions never captured). A floor published as a figure is the
+ * failure mode this module exists to prevent — see `isFloor`, which every
+ * renderer must carry through to the reader.
+ *
+ * Versioned independently of the o200k methodology, on the same reasoning as
+ * `tools-delta/v1`: this adds a second published number and does not touch the
+ * definition of the first. No `totalTokens` and no canonical hash moves.
+ */
+import { countTokens, sha256Hex } from './canonical.js';
+/** Method identifier, versioned independently of METHODOLOGY_VERSION. */
+export const SESSION_START_METHOD = 'deferred-load/v1';
+/**
+ * Tool names in server-returned order. A tool without a usable name is dropped
+ * rather than given a placeholder — the same rule `toAnthropicTools` follows,
+ * for the same reason: an invented name would change the count being published.
+ */
+export function toolNames(raw) {
+    const out = [];
+    for (const t of raw) {
+        const name = (t ?? {}).name;
+        if (typeof name === 'string' && name !== '')
+            out.push(name);
+    }
+    return out;
+}
+/**
+ * o200k count of the canonical tool-name list: `JSON.stringify` over the name
+ * array, the same serialization discipline as the headline number, so both
+ * re-derive from the same capture with the same five lines.
+ */
+export function toolNameTokens(raw) {
+    return countTokens(JSON.stringify(toolNames(raw)));
+}
+/**
+ * The two halves are counted separately and added, rather than counted over one
+ * concatenated string. Concatenation would let boundary tokens merge across the
+ * seam, so the published total would not equal the sum of the parts printed
+ * beside it — a discrepancy of a token or two that no reader could account for.
+ */
+export function sessionStartTokens(raw, instructions) {
+    return toolNameTokens(raw) + (instructions ? countTokens(instructions) : 0);
+}
+/**
+ * The instructions recorded *inside* a measurement, distinguishing three states
+ * that JSON round-trips faithfully:
+ *   - a string  → captured, the server sent this
+ *   - null      → captured, the server sent none
+ *   - undefined → never captured (every measurement predating the field)
+ *
+ * Absent-means-unknown rather than absent-means-zero, on the precedent set by
+ * history.csv's `isolation` column: an old row reads as unknown and is never
+ * back-filled from a value it did not record.
+ */
+export function measuredInstructions(m) {
+    if (typeof m.serverInstructions === 'string')
+        return m.serverInstructions;
+    if (m.serverInstructions === null)
+        return '';
+    return undefined;
+}
+/**
+ * Resolve one server's session-start load from its measurement and, if it has
+ * one, the instructions captured beside it.
+ *
+ * Precedence is measurement over capture and never the other way round: the
+ * measurement's instructions came off the same server process as its tools, in
+ * the same run, so it cannot be stale relative to itself. The side capture is
+ * the backfill for measurements taken before the field existed, and it is used
+ * only while it still points at the measurement on disk.
+ *
+ * Returns null for a measurement with no capture to read names from — a
+ * `startup-failure` has no session-start load because it has no session.
+ */
+export function sessionStartLoad(m, row) {
+    if (!Array.isArray(m.rawToolsCapture))
+        return null;
+    const names = toolNameTokens(m.rawToolsCapture);
+    const toolCount = toolNames(m.rawToolsCapture).length;
+    const inMeasurement = measuredInstructions(m);
+    if (inMeasurement !== undefined) {
+        const t = inMeasurement ? countTokens(inMeasurement) : 0;
+        return {
+            toolCount,
+            toolNameTokens: names,
+            instructionsTokens: t,
+            totalTokens: names + t,
+            isFloor: false,
+            instructionsSource: 'measurement',
+        };
+    }
+    if (isCurrentInstructions(row, m.canonicalSha256)) {
+        return {
+            toolCount,
+            toolNameTokens: names,
+            instructionsTokens: row.instructionsTokens,
+            totalTokens: names + row.instructionsTokens,
+            isFloor: false,
+            instructionsSource: 'capture',
+        };
+    }
+    return {
+        toolCount,
+        toolNameTokens: names,
+        instructionsTokens: null,
+        totalTokens: names,
+        isFloor: true,
+        instructionsSource: 'not-captured',
+    };
+}
+/**
+ * A side capture is usable only if it carries a number and still points at the
+ * measurement on disk. Unlike a stale divergence row — which is hidden, because
+ * there is nothing else to print — a stale row here degrades the figure to its
+ * names-only floor. The column never blanks; it only ever stops claiming to
+ * know the half it no longer knows.
+ */
+export function isCurrentInstructions(row, canonicalSha256) {
+    if (!row || row.error)
+        return false;
+    if (typeof row.instructionsTokens !== 'number')
+        return false;
+    return !!canonicalSha256 && row.capturedSha256 === canonicalSha256;
+}
+/** Build a row from a freshly captured instructions string. */
+export function toSessionStartRow(instructions, meta) {
+    const text = instructions ?? '';
+    return {
+        instructions: text,
+        instructionsTokens: text ? countTokens(text) : 0,
+        instructionsSha256: sha256Hex(text),
+        capturedSha256: meta.capturedSha256,
+        serverVersion: meta.serverVersion,
+    };
+}
+/** Parse results/session-start.json; anything malformed yields null, never throws. */
+export function parseSessionStart(text) {
+    let run;
+    try {
+        run = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    const r = run;
+    if (!r || typeof r.measuredAt !== 'string')
+        return null;
+    if (!r.servers || typeof r.servers !== 'object')
+        return null;
+    return {
+        method: typeof r.method === 'string' ? r.method : SESSION_START_METHOD,
+        measuredAt: r.measuredAt,
+        isolation: typeof r.isolation === 'string' ? r.isolation : undefined,
+        servers: r.servers,
+    };
+}

package/dist/core/types.d.ts

@@ -23,6 +23,14 @@ export interface Measurement {
     canonicalSha256: string | null;
     /** The tools array exactly as returned by tools/list, all pages concatenated. */
     rawToolsCapture: unknown[] | null;
+    /**
+     * The `instructions` string returned by `initialize` — half of the
+     * session-start load (see core/session-start.ts). Three states, and they are
+     * different claims: a string (the server sent this), `null` (the server sent
+     * none), absent (never captured — every measurement predating this field).
+     * Absent is never read as zero.
+     */
+    serverInstructions?: string | null;
     measuredAt: string;
     serverName: string;
     serverVersion?: string;

package/dist/sweep/client.d.ts

@@ -5,7 +5,12 @@ export interface WireCapture {
     };
     protocolVersion?: string;
     tools: unknown[];
-    /** true when a second tools/list returned a different tool set */
+    /**
+     * The `instructions` string from the initialize result — half of the
+     * session-start load. `null` means the server returned none, which is a
+     * different fact from never having asked, so the two are never conflated.
+     */
+    instructions: string | null;
     stderrTail: string;
 }
 export declare class McpStdioClient {

package/dist/sweep/client.js

@@ -164,6 +164,7 @@ export async function captureTools(spec, opts = {}) {
             serverInfo: init?.serverInfo,
             protocolVersion: init?.protocolVersion,
             tools,
+            instructions: typeof init?.instructions === 'string' ? init.instructions : null,
             stderrTail: client.stderrTail,
         };
     }

package/dist/sweep/dashboard.d.ts

@@ -7,3 +7,13 @@
  */
 export declare function renderSparkline(tokens: number[]): string;
 export declare function generateDashboard(root?: string): string;
+/**
+ * Render and write the dashboard. Exported so `regen.ts` refreshes it alongside
+ * the leaderboard and the server pages: this is the published Pages surface, and
+ * when only the CLI wrote it every sweep updated `results/` and `docs/servers/`
+ * while the page people actually open kept the previous run's numbers.
+ */
+export declare function writeDashboard(root?: string, out?: string): {
+    out: string;
+    bytes: number;
+};

package/dist/sweep/dashboard.js

@@ -7,7 +7,7 @@ import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { parse } from 'yaml';
 import { bandColor, BAND_META } from '../core/bands.js';
-import { parseHistory } from './history.js';
+import { parseHistory, plottableSeries } from './history.js';
 /** Longest series a sparkline plots — a stat-tile trend, not a full chart. */
 const SPARK_MAX_POINTS = 12;
 /**
@@ -49,10 +49,9 @@ export function generateDashboard(root = process.cwd()) {
     const dSrv = divergence.servers ?? {};
     const historyPath = join(root, 'results', 'history.csv');
     const history = existsSync(historyPath) ? parseHistory(readFileSync(historyPath, 'utf8')) : [];
-    const seriesFor = (name) => history
-        .filter((h) => h.server === name)
-        .sort((a, b) => a.date.localeCompare(b.date))
-        .map((h) => h.tokens);
+    // 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 };
@@ -78,8 +77,16 @@ export function generateDashboard(root = process.cwd()) {
         const div = dSrv[r.entry.name];
         const claudeTip = div ? ` · in a Claude request: ${fmt(div.claudeDelta)} tok` : '';
         const series = seriesFor(r.entry.name);
-        const spark = renderSparkline(series);
-        const trendTip = series.length > 1 ? ` · ${series.length}-sweep trend: ${series[0].toLocaleString('en-US')} → ${series[series.length - 1].toLocaleString('en-US')}` : '';
+        const tokens = series.rows.map((h) => h.tokens);
+        const spark = renderSparkline(tokens);
+        const trendTip = tokens.length > 1
+            ? ` · ${tokens.length}-sweep trend: ${tokens[0].toLocaleString('en-US')} → ${tokens[tokens.length - 1].toLocaleString('en-US')}` +
+                (series.dropped
+                    ? ` (${series.dropped} earlier sweep${series.dropped === 1 ? '' : 's'} measured under different isolation, not plotted)`
+                    : '')
+            : series.dropped
+                ? ` · earlier sweeps were measured under different isolation, so no trend is plotted`
+                : '';
         // The whole row is the link to the server's detail page (docs/servers/).
         return `<a class="row" href="servers/${encodeURIComponent(r.entry.name)}.html" data-tip="${esc(m.toolCount)} tools · largest: ${esc(largest?.name)} (${fmt(largest?.tokens ?? 0)} tok)${claudeTip}${trendTip} · ${esc(r.entry.category)} · ${esc(m.status)}${m.serverVersion ? ' · v' + esc(String(m.serverVersion).replace(/^v/, '')) : ''}">
   <span class="rank">${i + 1}</span>
@@ -101,9 +108,9 @@ export function generateDashboard(root = process.cwd()) {
         .map((r, i) => {
         const m = r.m;
         const div = dSrv[r.entry.name];
-        const series = seriesFor(r.entry.name);
-        const trend = series.length > 1
-            ? `${series[series.length - 1] - series[0] >= 0 ? '+' : ''}${fmt(series[series.length - 1] - series[0])} / ${series.length}d`
+        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`
             : '—';
         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>`;
     })
@@ -220,7 +227,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. 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 (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>
   <div class="board">
 ${barRows || '<p class="h2sub">Sweep in progress — first results land shortly.</p>'}
   </div>
@@ -282,12 +289,21 @@ ${barRows || '<p class="h2sub">Sweep in progress — first results land shortly.
 </script>
 `;
 }
+/**
+ * Render and write the dashboard. Exported so `regen.ts` refreshes it alongside
+ * the leaderboard and the server pages: this is the published Pages surface, and
+ * when only the CLI wrote it every sweep updated `results/` and `docs/servers/`
+ * while the page people actually open kept the previous run's numbers.
+ */
+export function writeDashboard(root = process.cwd(), out = 'docs/dashboard.html') {
+    const html = generateDashboard(root);
+    mkdirSync(dirname(out), { recursive: true });
+    writeFileSync(out, html);
+    return { out, bytes: html.length };
+}
 const isMain = process.argv[1]?.endsWith('dashboard.ts') || process.argv[1]?.endsWith('dashboard.js');
 if (isMain) {
     const i = process.argv.indexOf('--out');
-    const out = i >= 0 ? process.argv[i + 1] : 'docs/dashboard.html';
-    const html = generateDashboard();
-    mkdirSync(dirname(out), { recursive: true });
-    writeFileSync(out, html);
-    console.log(`wrote ${out} (${(html.length / 1024).toFixed(0)}KB)`);
+    const w = writeDashboard(process.cwd(), i >= 0 ? process.argv[i + 1] : 'docs/dashboard.html');
+    console.log(`wrote ${w.out} (${(w.bytes / 1024).toFixed(0)}KB)`);
 }

package/dist/sweep/docker.d.ts

@@ -10,6 +10,16 @@ export interface DockerOptions {
     image?: string;
     /** Extra env var NAMES to pass through with dummy values. */
     dummyEnv?: string[];
+    /**
+     * Override the literal `dummy` value for specific `dummyEnv` names. Some
+     * servers parse an env var's shape before ever reaching tools/list (a URI
+     * scheme, a URL) and crash on a value that isn't real-looking rather than
+     * a value that isn't a real credential — e.g. `NEO4J_URI=dummy` fails
+     * `neo4j.exceptions.ConfigurationError` before the driver is even asked to
+     * connect. A locally-scoped placeholder (`bolt://localhost:7687`) clears
+     * that parse step without providing a working credential.
+     */
+    dummyEnvValues?: Record<string, string>;
     /** Container name, so a timed-out container can be force-removed. */
     containerName?: string;
     /**
@@ -20,6 +30,19 @@ export interface DockerOptions {
      * git already on PATH would actually run.
      */
     needsGit?: boolean;
+    /**
+     * Skip the shared npm/uv cache volumes, paying a cold install for a clean one.
+     *
+     * The caches are what make a re-sweep minutes instead of hours, but a cache
+     * entry can go bad and stay bad: npm remembers a failed postinstall, and every
+     * later install that resolves through it fails the same way. Observed
+     * 2026-08-19 — a cached `esbuild@0.25.12` whose postinstall exits 1 made
+     * `npx -y @shopify/dev-mcp@latest` exit 1 with no output, against a server that
+     * installs and answers fine from an empty cache. Nothing in the exit code tells
+     * that apart from a genuinely broken server, so the sweep retries here rather
+     * than publishing the downgrade.
+     */
+    noSharedCache?: boolean;
 }
 export declare const DEFAULT_NODE_IMAGE = "public.ecr.aws/docker/library/node:22-slim";
 export declare const DEFAULT_PYTHON_IMAGE = "ghcr.io/astral-sh/uv:python3.12-bookworm-slim";

package/dist/sweep/docker.js

@@ -23,17 +23,21 @@ export function dockerize(commandLine, opts = {}) {
         '-w',
         '/tmp',
         // Shared package caches across containers — packages only, no credentials.
-        '-v',
-        'mcp-ctx-npm-cache:/tmp/.npm-cache',
-        '-e',
-        'npm_config_cache=/tmp/.npm-cache',
-        '-v',
-        'mcp-ctx-uv-cache:/tmp/.uv-cache',
-        '-e',
-        'UV_CACHE_DIR=/tmp/.uv-cache',
+        ...(opts.noSharedCache
+            ? []
+            : [
+                '-v',
+                'mcp-ctx-npm-cache:/tmp/.npm-cache',
+                '-e',
+                'npm_config_cache=/tmp/.npm-cache',
+                '-v',
+                'mcp-ctx-uv-cache:/tmp/.uv-cache',
+                '-e',
+                'UV_CACHE_DIR=/tmp/.uv-cache',
+            ]),
     ];
     for (const name of opts.dummyEnv ?? []) {
-        argv.push('-e', `${name}=dummy`);
+        argv.push('-e', `${name}=${opts.dummyEnvValues?.[name] ?? 'dummy'}`);
     }
     const gitPrefix = opts.needsGit
         ? 'command -v git >/dev/null 2>&1 || (apt-get update -qq && apt-get install -y -qq --no-install-recommends git >/dev/null 2>&1); '
@@ -46,9 +50,9 @@ export function dockerize(commandLine, opts = {}) {
             docker: true,
             image,
             network: 'bridge',
-            note: opts.needsGit
-                ? 'network enabled for package fetch; clean FS, no host credentials, git installed'
-                : 'network enabled for package fetch; clean FS, no host credentials',
+            note: 'network enabled for package fetch; clean FS, no host credentials' +
+                (opts.needsGit ? ', git installed' : '') +
+                (opts.noSharedCache ? ', shared package cache bypassed' : ''),
         },
     };
 }

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

@@ -0,0 +1,57 @@
+import type { MeasurementStatus } from '../core/types.js';
+/**
+ * Below this many regressions the population signal doesn't exist yet, and a
+ * deliberately narrow sweep (`--only redis,serena`, two servers known to be
+ * shaky) must never be able to trip a fault by failing completely.
+ */
+export declare const MIN_REGRESSIONS = 5;
+/**
+ * Share of the previously-good servers in this sweep that must regress before
+ * the harness is the likelier explanation. The largest genuine simultaneous
+ * upstream breakage on record here is a handful of PyPI servers that shared
+ * one unbounded dependency — single digits against ~65 measured, well under
+ * 10%. A harness fault, by contrast, takes everything it touches: the Docker
+ * outage above scored 100%. A majority sits far from the former and catches
+ * every instance of the latter this project has actually seen.
+ */
+export declare const FAULT_RATIO = 0.5;
+/** Statuses that represent a real number on record — the thing worth protecting. */
+export declare function isGood(status: MeasurementStatus): boolean;
+/** The bytes of one server's published artifacts, exactly as they were pre-sweep. */
+export interface Snapshot {
+    name: string;
+    status: MeasurementStatus | null;
+    /** Raw file contents, so a restore is byte-identical rather than re-serialized. */
+    measurementJson: string | null;
+    badgeJson: string | null;
+}
+/**
+ * Read what is currently published for each server. Called before the sweep
+ * starts; a server with nothing on record snapshots as `null` status, which no
+ * verdict counts either way.
+ */
+export declare function snapshot(names: string[], root?: string): Snapshot[];
+export interface Verdict {
+    /** True when the sweep looks like a broken harness rather than broken servers. */
+    fault: boolean;
+    /** Servers that went from a real number to a failure in this sweep. */
+    regressed: string[];
+    /** How many servers had a real number on record and could therefore regress. */
+    comparable: number;
+    /** Human-readable reason, printed either way — a pass says why it passed. */
+    reason: string;
+}
+/**
+ * Compare pre-sweep snapshots against this sweep's outcomes.
+ *
+ * `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;
+/**
+ * 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
+ * first-ever measurement failed has nothing to restore and keeps its new
+ * (honest) failure record.
+ */
+export declare function restore(prior: Snapshot[], names: string[], root?: string): string[];