mcp-context-cost 0.3.0 → 0.5.0

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

@@ -1 +1,19 @@
+/**
+ * A 12-point-max inline trend line, oldest to newest. Muted stroke (this is
+ * texture, not a headline number) with the current value picked out as an
+ * accent dot, per the sparkline spec: de-emphasis hue for the line, accent
+ * for "now". Flat series still draw a level line rather than faking a zero
+ * baseline. Returns '' when there's nothing to trend (0-1 points).
+ */
+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,6 +7,38 @@ 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, plottableSeries } from './history.js';
+/** Longest series a sparkline plots — a stat-tile trend, not a full chart. */
+const SPARK_MAX_POINTS = 12;
+/**
+ * A 12-point-max inline trend line, oldest to newest. Muted stroke (this is
+ * texture, not a headline number) with the current value picked out as an
+ * accent dot, per the sparkline spec: de-emphasis hue for the line, accent
+ * for "now". Flat series still draw a level line rather than faking a zero
+ * baseline. Returns '' when there's nothing to trend (0-1 points).
+ */
+export function renderSparkline(tokens) {
+    const points = tokens.slice(-SPARK_MAX_POINTS);
+    if (points.length < 2)
+        return '';
+    const w = 56;
+    const h = 18;
+    const pad = 3;
+    const min = Math.min(...points);
+    const max = Math.max(...points);
+    const range = max - min;
+    const stepX = (w - pad * 2) / (points.length - 1);
+    const coords = points.map((v, i) => {
+        const x = pad + i * stepX;
+        const y = range === 0 ? h / 2 : pad + (h - pad * 2) * (1 - (v - min) / range);
+        return `${x.toFixed(1)},${y.toFixed(1)}`;
+    });
+    const [lastX, lastY] = coords[coords.length - 1].split(',');
+    return `<svg class="spark" width="${w}" height="${h}" viewBox="0 0 ${w} ${h}" aria-hidden="true" focusable="false">
+    <polyline points="${coords.join(' ')}" fill="none" stroke="var(--muted)" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"/>
+    <circle cx="${lastX}" cy="${lastY}" r="2.2" fill="var(--accent)" stroke="var(--surface)" stroke-width="1"/>
+  </svg>`;
+}
 const esc = (s) => String(s ?? '').replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
 export function generateDashboard(root = process.cwd()) {
     const doc = parse(readFileSync(join(root, 'servers.yaml'), 'utf8'));
@@ -15,6 +47,11 @@ export function generateDashboard(root = process.cwd()) {
         ? JSON.parse(readFileSync(divergencePath, 'utf8'))
         : {};
     const dSrv = divergence.servers ?? {};
+    const historyPath = join(root, 'results', 'history.csv');
+    const history = existsSync(historyPath) ? parseHistory(readFileSync(historyPath, 'utf8')) : [];
+    // 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 };
@@ -39,11 +76,23 @@ export function generateDashboard(root = process.cwd()) {
         const pct = Math.max(1.2, (t / max) * 100);
         const div = dSrv[r.entry.name];
         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);
+        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} · ${esc(r.entry.category)} · ${esc(m.status)}${m.serverVersion ? ' · v' + esc(String(m.serverVersion).replace(/^v/, '')) : ''}">
+        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>
   <span class="name">${esc(r.entry.name)}</span>
   <span class="track"><span class="bar" style="width:${pct.toFixed(1)}%"></span></span>
+  <span class="spark-cell">${spark}</span>
   <span class="val"><span class="dot dot-${band}" aria-hidden="true"></span>${fmt(t)}<span class="bandname">${meta.label}</span></span>
 </a>`;
     })
@@ -59,7 +108,11 @@ export function generateDashboard(root = process.cwd()) {
         .map((r, i) => {
         const m = r.m;
         const div = dSrv[r.entry.name];
-        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></tr>`;
+        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>`;
     })
         .join('\n');
     const specimens = [measured[measured.length - 1], measured[0]]
@@ -117,13 +170,15 @@ export function generateDashboard(root = process.cwd()) {
   .stat .l { font-size: 11px; letter-spacing: 0.08em; text-transform: uppercase; color: var(--muted); }
 
   .board { background: var(--surface); border: 1px solid var(--line); border-radius: 8px; padding: 14px 16px; }
-  .row { display: grid; grid-template-columns: 2ch minmax(120px, 190px) 1fr max-content; gap: 10px; align-items: center; padding: 3px 4px; border-radius: 4px; outline: none; color: inherit; text-decoration: none; }
+  .row { display: grid; grid-template-columns: 2ch minmax(120px, 190px) 1fr 56px max-content; gap: 10px; align-items: center; padding: 3px 4px; border-radius: 4px; outline: none; color: inherit; text-decoration: none; }
   .row:hover, .row:focus-visible { background: var(--accent-soft); }
   .row:hover .name, .row:focus-visible .name { text-decoration: underline; }
   .rank { font-family: ui-monospace, Menlo, monospace; font-size: 11px; color: var(--muted); text-align: right; font-variant-numeric: tabular-nums; }
   .name { font-size: 0.86rem; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
   .track { background: var(--track); border-radius: 3px; height: 12px; overflow: hidden; }
   .bar { display: block; height: 100%; background: var(--accent); border-radius: 3px 3px 3px 3px; min-width: 3px; }
+  .spark-cell { display: flex; align-items: center; justify-content: center; height: 18px; }
+  .spark-cell:empty { visibility: hidden; }
   .val { font-family: ui-monospace, Menlo, monospace; font-variant-numeric: tabular-nums; font-size: 0.82rem; display: flex; align-items: center; gap: 6px; }
   .dot { width: 8px; height: 8px; border-radius: 50%; display: inline-block; box-shadow: 0 0 0 2px var(--surface); }
   .dot-brightgreen { background: var(--b-brightgreen); } .dot-green { background: var(--b-green); }
@@ -172,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). Hover a row for both 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>
@@ -198,7 +253,7 @@ ${barRows || '<p class="h2sub">Sweep in progress — first results land shortly.
 
   <details><summary>Full data table</summary>
   <div class="tablewrap" style="margin-top:10px"><table>
-    <thead><tr><th>#</th><th>server</th><th>tokens (o200k)</th><th>claude req</th><th>tools</th><th>band</th><th>category</th></tr></thead>
+    <thead><tr><th>#</th><th>server</th><th>tokens (o200k)</th><th>claude req</th><th>tools</th><th>band</th><th>category</th><th>trend</th></tr></thead>
     <tbody>${tableRows}</tbody>
   </table></div>
   </details>
@@ -234,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,8 +10,39 @@ 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;
+    /**
+     * Install `git` inside the container before launch. The slim base images
+     * carry no VCS, so `uvx --from git+...` installs fail with "Git executable
+     * not found" — this only prefixes the containerized invocation, never the
+     * recorded `launchCommand`, so the published command stays what a user with
+     * 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,19 +23,26 @@ 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'}`);
     }
-    argv.push(image, 'sh', '-lc', commandLine);
+    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); '
+        : '';
+    argv.push(image, 'sh', '-lc', gitPrefix + commandLine);
     return {
         command: 'docker',
         argv,
@@ -43,7 +50,9 @@ export function dockerize(commandLine, opts = {}) {
             docker: true,
             image,
             network: 'bridge',
-            note: '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[];