mcp-context-cost 0.7.0 → 0.9.0

package/dist/sweep/cross-check.js

@@ -0,0 +1,342 @@
+/**
+ * CLI cross-check runner — measure each server twice in one sitting, once with
+ * our client and once with `sd2k/mcp-tokens`, and file the pair under the
+ * capture our side took:
+ *   npx tsx src/sweep/cross-check.ts [--docker] [--only a,b] [--concurrency 3]
+ *                                    [--shards N [--shard-index K]]
+ *                                    [--default-timeout 60]
+ *
+ * Writes results/cross-check.json and nothing else — the measurements on disk
+ * keep their numbers, hashes and dates (the session-start discipline). Our
+ * measurement is taken fresh through `measureServer` — same isolation, same
+ * dummy env, same retries as a sweep — because the row is only worth publishing
+ * while it compares like with like: the fresh capture's `canonicalSha256` is
+ * what the row is filed under, and the CLI's tool names are checked against the
+ * capture's, so a server that changed between the two launches records data but
+ * prints silence.
+ *
+ * The CLI is a pinned release binary, fetched once into a host cache and
+ * verified against the release's own SHA-256 before it is ever executed; in
+ * docker mode it is bind-mounted read-only into the same image, limits and
+ * package-cache volumes a sweep uses, so the server it launches runs under the
+ * exact isolation every published measurement ran under.
+ */
+import { chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { homedir, tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parse } from 'yaml';
+import { measureServer } from './run.js';
+import { DockerHarnessFault, defaultImageFor, dockerize } from './docker.js';
+import { splitCommand } from './client.js';
+import { selectShard, shardIndexForDate } from './shard.js';
+import { CROSS_CHECK_CLI, CROSS_CHECK_CLI_ARGS, CROSS_CHECK_CLI_VERSION, CROSS_CHECK_METHOD, divergencePct, parseCliReport, parseCrossCheck, toCrossCheckRow, } from '../core/cross-check.js';
+export function loadCrossCheck(root = process.cwd()) {
+    const p = join(root, 'results', 'cross-check.json');
+    return existsSync(p) ? parseCrossCheck(readFileSync(p, 'utf8')) : null;
+}
+export function writeCrossCheck(run, root = process.cwd()) {
+    // Key order sorted so a re-run of the same servers produces no diff noise.
+    const servers = {};
+    for (const name of Object.keys(run.servers).sort())
+        servers[name] = run.servers[name];
+    writeFileSync(join(root, 'results', 'cross-check.json'), JSON.stringify({ ...run, servers }, null, 2) + '\n');
+}
+/** Release-asset triple for where the CLI will actually run. */
+export function cliTriple(docker, platform = process.platform, arch = process.arch) {
+    if (docker) {
+        // The container is Linux whatever the host is; its architecture is the host's.
+        return arch === 'arm64' ? 'aarch64-unknown-linux-gnu' : 'x86_64-unknown-linux-gnu';
+    }
+    const cpu = arch === 'arm64' ? 'aarch64' : 'x86_64';
+    if (platform === 'darwin')
+        return `${cpu}-apple-darwin`;
+    if (platform === 'linux')
+        return `${cpu}-unknown-linux-gnu`;
+    throw new Error(`no ${CROSS_CHECK_CLI} release asset for ${platform}/${arch} — run with --docker`);
+}
+function sh(command, args) {
+    return new Promise((resolvePromise) => {
+        const child = spawn(command, args, { stdio: ['ignore', 'ignore', 'pipe'] });
+        let stderr = '';
+        child.stderr.setEncoding('utf8');
+        child.stderr.on('data', (chunk) => (stderr = (stderr + chunk).slice(-4000)));
+        child.on('error', (err) => resolvePromise({ code: null, stderr: String(err.message) }));
+        child.on('exit', (code) => resolvePromise({ code, stderr }));
+    });
+}
+/**
+ * Fetch the pinned CLI release for `triple` into a host cache, verifying the
+ * archive against the release's own `.sha256` before anything is extracted or
+ * executed. `MCP_TOKENS_BIN` overrides the whole dance — that is how the tests
+ * substitute a shim, and how an airgapped machine supplies its own copy.
+ */
+export async function ensureCliBinary(triple) {
+    const override = process.env.MCP_TOKENS_BIN;
+    if (override)
+        return override;
+    const cacheDir = join(homedir(), '.cache', 'mcp-context-cost', 'mcp-tokens', `${CROSS_CHECK_CLI_VERSION}-${triple}`);
+    const binPath = join(cacheDir, 'mcp-tokens');
+    if (existsSync(binPath))
+        return binPath;
+    const asset = `mcp-tokens-${triple}.tar.xz`;
+    const base = `https://github.com/${CROSS_CHECK_CLI}/releases/download/${CROSS_CHECK_CLI_VERSION}`;
+    const fetchBytes = async (url) => {
+        const res = await fetch(url);
+        if (!res.ok)
+            throw new Error(`GET ${url}: HTTP ${res.status}`);
+        return Buffer.from(await res.arrayBuffer());
+    };
+    const archive = await fetchBytes(`${base}/${asset}`);
+    const sumFile = (await fetchBytes(`${base}/${asset}.sha256`)).toString('utf8');
+    const expected = sumFile.trim().split(/\s+/)[0]?.toLowerCase();
+    const actual = createHash('sha256').update(archive).digest('hex');
+    if (!expected || expected !== actual) {
+        throw new Error(`${asset}: SHA-256 mismatch — expected ${expected ?? '(unparseable)'}, got ${actual}; refusing to run it`);
+    }
+    const work = join(tmpdir(), `mcp-tokens-${process.pid}-${Math.floor(Math.random() * 1e6)}`);
+    mkdirSync(work, { recursive: true });
+    try {
+        const archivePath = join(work, asset);
+        writeFileSync(archivePath, archive);
+        const tar = await sh('tar', ['-xJf', archivePath, '-C', work]);
+        if (tar.code !== 0)
+            throw new Error(`tar failed extracting ${asset}: ${tar.stderr.slice(-200)}`);
+        const found = findFile(work, 'mcp-tokens');
+        if (!found)
+            throw new Error(`${asset} did not contain an mcp-tokens binary`);
+        mkdirSync(cacheDir, { recursive: true });
+        chmodSync(found, 0o755);
+        renameSync(found, binPath);
+    }
+    finally {
+        rmSync(work, { recursive: true, force: true });
+    }
+    return binPath;
+}
+function findFile(dir, name) {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        const p = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            const hit = findFile(p, name);
+            if (hit)
+                return hit;
+        }
+        else if (entry.name === name) {
+            return p;
+        }
+    }
+    return null;
+}
+/**
+ * Run the CLI against one server, host or containerized. In docker mode the
+ * binary is bind-mounted read-only and the CLI launches the server inside the
+ * container — same image, limits, dummy env and shared package caches as the
+ * measurement that just ran, so the npx install it pays is already warm.
+ */
+export function runCli(binPath, entry, opts) {
+    // The CLI's own deadline gets the entry's budget — its default is 30s, which
+    // published as a failure for a server (postgres-mcp) that legitimately takes
+    // longer to start and measures fine on the same budget our client gets. Its
+    // --timeout is in seconds, for server startup.
+    const cliArgs = [...CROSS_CHECK_CLI_ARGS, '--timeout', String(Math.ceil(opts.timeoutMs / 1000))];
+    let command = binPath;
+    let argv = [...cliArgs, '--', ...splitCommand(entry.command)];
+    let containerName = null;
+    if (opts.docker) {
+        containerName = `mcp-ctx-xchk-${entry.name}-${process.pid}-${Math.floor(Math.random() * 1e6)}`;
+        // The slim images carry no OpenSSL shared library and the CLI's linux-gnu
+        // build links libssl.so.3 — installed inside the container before launch,
+        // the same shape as dockerize's needsGit: it prefixes the containerized
+        // invocation only and is never part of any recorded command.
+        const sslPrefix = 'ldconfig -p 2>/dev/null | grep -q libssl.so.3 || ' +
+            '(apt-get update -qq && apt-get install -y -qq --no-install-recommends libssl3 >/dev/null 2>&1); ';
+        const d = dockerize(`${sslPrefix}/opt/mcp-tokens ${cliArgs.join(' ')} -- ${entry.command}`, {
+            // Explicit, from the SERVER's command: dockerize's image sniffing reads
+            // the front of the command line, which here is the ssl prefix and the
+            // CLI, not the `uvx …` it is about to launch — left implicit, every
+            // Python server's CLI run would land in the node image, uvx-less.
+            image: entry.dockerImage ?? defaultImageFor(entry.command),
+            dummyEnv: entry.env ?? [],
+            dummyEnvValues: entry.envValues,
+            needsGit: entry.needsGit,
+            containerName,
+            binds: [`${binPath}:/opt/mcp-tokens:ro`],
+        });
+        command = d.command;
+        argv = d.argv;
+    }
+    return new Promise((resolvePromise) => {
+        const child = spawn(command, argv, {
+            stdio: ['ignore', 'pipe', 'pipe'],
+            env: { PATH: process.env.PATH, HOME: process.env.HOME },
+        });
+        let stdout = '';
+        let stderr = '';
+        let timedOut = false;
+        child.stdout.setEncoding('utf8');
+        child.stdout.on('data', (chunk) => (stdout += chunk));
+        child.stderr.setEncoding('utf8');
+        child.stderr.on('data', (chunk) => (stderr = (stderr + chunk).slice(-4000)));
+        // Grace beyond the CLI's own deadline: startup is what its timeout covers,
+        // and the counting that follows deserves to finish rather than be killed
+        // at the exact same instant.
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill('SIGKILL');
+            if (containerName)
+                spawn('docker', ['rm', '-f', containerName], { stdio: 'ignore' }).on('error', () => { });
+        }, opts.timeoutMs + (opts.graceMs ?? 30_000));
+        child.on('error', (err) => {
+            clearTimeout(timer);
+            resolvePromise({ code: null, stdout, stderr: String(err.message), timedOut });
+        });
+        child.on('exit', (code) => {
+            clearTimeout(timer);
+            resolvePromise({ code, stdout, stderr, timedOut });
+        });
+    });
+}
+function arg(name) {
+    const i = process.argv.indexOf(`--${name}`);
+    return i >= 0 ? process.argv[i + 1] : undefined;
+}
+// Exact path match, for the reason src/sweep/run.ts states: any other file whose
+// name merely ends the same way would otherwise run this block.
+const isMain = process.argv[1] !== undefined && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+    const doc = parse(readFileSync('servers.yaml', 'utf8'));
+    const only = arg('only')?.split(',');
+    const docker = process.argv.includes('--docker');
+    const concurrency = Number(arg('concurrency') ?? 3);
+    const defaultTimeout = Number(arg('default-timeout') ?? 60);
+    const shards = arg('shards') === undefined ? undefined : Number(arg('shards'));
+    const shardIndexArg = arg('shard-index') === undefined ? undefined : Number(arg('shard-index'));
+    if (shards !== undefined && only) {
+        // Same refusal as sweep-all, same reason: a slice that belongs to no cycle
+        // must not be producible by accident.
+        console.error('--shards and --only both select servers; pass one or the other');
+        process.exit(2);
+    }
+    if (shardIndexArg !== undefined && shards === undefined) {
+        console.error('--shard-index needs --shards');
+        process.exit(2);
+    }
+    let entries = doc.servers.filter((s) => {
+        if (only && !only.includes(s.name))
+            return false;
+        return !s.remote; // a remote server never reaches tools/list without credentials
+    });
+    if (shards !== undefined) {
+        const index = shardIndexArg ?? shardIndexForDate(new Date(), shards);
+        entries = selectShard(entries, shards, index);
+        console.log(`shard ${index + 1}/${shards}: ${entries.map((e) => e.name).join(', ')}`);
+    }
+    // A row can only ever print by matching the hash of a published measurement,
+    // so a server with no good number on record has no comparison to make — the
+    // launches would be spent on a row that cannot become printable until a
+    // sweep publishes a capture for it. Skipped after shard selection, so the
+    // slice stays the sweep's slice.
+    const skipped = [];
+    entries = entries.filter((e) => {
+        const p = join(process.cwd(), 'results', e.name, 'measurement.json');
+        if (!existsSync(p)) {
+            skipped.push(e.name);
+            return false;
+        }
+        try {
+            const status = JSON.parse(readFileSync(p, 'utf8')).status;
+            if (status === 'measured' || status === 'dynamic')
+                return true;
+        }
+        catch {
+            // An unreadable record is not a good number on record.
+        }
+        skipped.push(e.name);
+        return false;
+    });
+    if (skipped.length > 0) {
+        console.log(`skipping ${skipped.length} with no published number to compare against: ${skipped.join(', ')}`);
+    }
+    const triple = cliTriple(docker);
+    const binPath = await ensureCliBinary(triple);
+    // A command that is already its own `docker run` cannot have the CLI
+    // containerized around it — that would be docker from inside docker — so for
+    // those entries the CLI runs host-side and the server still runs in its own
+    // container, the same shape measureServer records for these commands.
+    let hostBinPromise = null;
+    const hostBin = () => (hostBinPromise ??= ensureCliBinary(cliTriple(false)));
+    console.log(`cross-checking ${entries.length} servers against ${CROSS_CHECK_CLI} ${CROSS_CHECK_CLI_VERSION} ` +
+        `(${triple}, docker=${docker}, concurrency=${concurrency})`);
+    // Merged, not replaced: a run over `--only` or one shard must not delete the
+    // rows it did not visit. A row it did visit is overwritten, errors included.
+    const prior = loadCrossCheck();
+    const servers = { ...(prior?.servers ?? {}) };
+    const queue = [...entries];
+    async function worker() {
+        for (let e = queue.shift(); e; e = queue.shift()) {
+            const timeoutMs = (e.timeoutSeconds ?? defaultTimeout) * 1000;
+            let m;
+            try {
+                m = await measureServer(e.name, e.command, {
+                    timeoutMs,
+                    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) {
+                if (!(err instanceof DockerHarnessFault))
+                    throw err;
+                // A machine fault is not a fact about the server: leave its prior row alone.
+                console.log(`  ${e.name}: docker harness fault — skipped, prior row untouched`);
+                continue;
+            }
+            if (m.status !== 'measured' && m.status !== 'dynamic') {
+                servers[e.name] = toCrossCheckRow(m, {});
+                console.log(`  ${e.name}: our measurement ${m.status} — recorded, nothing to compare`);
+                continue;
+            }
+            const selfDocker = e.command.trimStart().startsWith('docker ');
+            const out = await runCli(docker && selfDocker ? await hostBin() : binPath, e, {
+                docker: docker && !selfDocker,
+                timeoutMs,
+            });
+            const cli = out.timedOut
+                ? { problem: `timeout after ${timeoutMs}ms` }
+                : out.code !== 0
+                    ? { problem: `exited ${out.code}: ${out.stderr.slice(-200)}` }
+                    : parseCliReport(out.stdout);
+            const row = toCrossCheckRow(m, cli);
+            servers[e.name] = row;
+            const pct = divergencePct(row);
+            console.log(`  ${e.name}: ours ${row.ourTokens} (mapped ${row.ourMappedTokens}), cli ${row.cliTokens}` +
+                (row.error
+                    ? ` — ${row.error}`
+                    : !row.toolSetMatches
+                        ? ` — tool sets differ (${row.ourToolCount} vs ${row.cliToolCount} tools), not comparable`
+                        : row.dynamic
+                            ? ` (${pct !== null && pct >= 0 ? '+' : ''}${pct?.toFixed(1)}% vs mapped) — dynamic listing, recorded but never printed`
+                            : ` (${pct !== null && pct >= 0 ? '+' : ''}${pct?.toFixed(1)}% vs mapped)`));
+        }
+    }
+    await Promise.all(Array.from({ length: Math.max(1, concurrency) }, () => worker()));
+    writeCrossCheck({
+        method: CROSS_CHECK_METHOD,
+        cli: CROSS_CHECK_CLI,
+        cliVersion: CROSS_CHECK_CLI_VERSION,
+        cliArgs: [...CROSS_CHECK_CLI_ARGS],
+        measuredAt: new Date().toISOString().slice(0, 10),
+        isolation: (docker ? 'docker (same images, limits and package caches as a sweep)' : 'host process (no container)') +
+            (process.env.MCP_TOKENS_BIN ? '; binary supplied via MCP_TOKENS_BIN' : ''),
+        servers,
+    });
+    const rows = Object.values(servers);
+    const clean = rows.filter((r) => !r.error && r.toolSetMatches && !r.dynamic);
+    console.log(`done: ${clean.length}/${rows.length} rows comparable; results/cross-check.json written`);
+}

package/dist/sweep/docker.d.ts

@@ -30,6 +30,13 @@ export interface DockerOptions {
      * git already on PATH would actually run.
      */
     needsGit?: boolean;
+    /**
+     * Extra `-v` bind mounts, verbatim (`host:container:ro`). Used to hand a
+     * host-verified binary into the container (the cross-check CLI); mounts here
+     * should be read-only so the isolation claim — clean FS, no host credentials
+     * — survives them.
+     */
+    binds?: string[];
     /**
      * Skip the shared npm/uv cache volumes, paying a cold install for a clean one.
      *
@@ -46,6 +53,54 @@ export interface DockerOptions {
 }
 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";
+/** The image a launch command gets when the entry does not name one. */
+export declare function defaultImageFor(commandLine: string): string;
+/**
+ * Docker failed, not the server. A measurement that ends this way is a
+ * statement about this machine — the daemon, the registry, the network — and
+ * must never be recorded as the server's startup-failure: the 2026-08-26
+ * re-sweep published exactly that lie about `sequential-thinking` when the
+ * runner could not pull the base image, and the harness guard never saw it
+ * because it watches for populations of regressions, not single rows.
+ */
+export declare class DockerHarnessFault extends Error {
+}
+/**
+ * Whether a capture-failure message describes `docker run` failing as docker
+ * rather than the contained server failing as itself.
+ *
+ * Docker reserves exit code 125 for its own failures, but a contained process
+ * that exits 125 passes that code through indistinguishably — so the code alone
+ * is not enough, and docker's own stderr voice ("Unable to find image …",
+ * "docker: Error response from daemon: …", "docker: Cannot connect …") is
+ * required alongside it. Only meaningful for a command this code wrapped in
+ * `docker run` itself; a config whose command is already `docker run …` owns
+ * its exit codes.
+ */
+export declare function isDockerRunFailure(message: string): boolean;
+export interface EnsureImageOptions {
+    /** Run one docker invocation — injectable so tests never need a daemon. */
+    run?: (args: string[]) => Promise<{
+        code: number | null;
+        stderr: string;
+    }>;
+    /** Waits between pull attempts; attempts = delays + 1. */
+    delaysMs?: number[];
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * Make sure a base image is present before any container needs it, retrying the
+ * pull. `docker run --pull=missing` pulls lazily, so a transient registry
+ * failure lands mid-measurement and gets read as the server refusing to start —
+ * pulling up front, with retries, is what keeps a registry hiccup from ever
+ * reaching a measurement. Failures throw `DockerHarnessFault`.
+ *
+ * Results are memoized per image for the life of the process (only on the real
+ * docker path — injected runners are for tests), so concurrent sweep workers
+ * share one pull, and an image that could not be pulled after retries is not
+ * re-attempted by every remaining server in the sweep.
+ */
+export declare function ensureImage(image: string, opts?: EnsureImageOptions): Promise<void>;
 export interface IsolationRecord {
     docker: boolean;
     image?: string;

package/dist/sweep/docker.js

@@ -2,12 +2,102 @@
 // on this machine 2026-08-16: hub pulls stall indefinitely while ECR works).
 export const DEFAULT_NODE_IMAGE = 'public.ecr.aws/docker/library/node:22-slim';
 export const DEFAULT_PYTHON_IMAGE = 'ghcr.io/astral-sh/uv:python3.12-bookworm-slim';
+/** The image a launch command gets when the entry does not name one. */
+export function defaultImageFor(commandLine) {
+    return commandLine.trimStart().startsWith('uvx') ? DEFAULT_PYTHON_IMAGE : DEFAULT_NODE_IMAGE;
+}
+/**
+ * Docker failed, not the server. A measurement that ends this way is a
+ * statement about this machine — the daemon, the registry, the network — and
+ * must never be recorded as the server's startup-failure: the 2026-08-26
+ * re-sweep published exactly that lie about `sequential-thinking` when the
+ * runner could not pull the base image, and the harness guard never saw it
+ * because it watches for populations of regressions, not single rows.
+ */
+export class DockerHarnessFault extends Error {
+}
+/**
+ * Whether a capture-failure message describes `docker run` failing as docker
+ * rather than the contained server failing as itself.
+ *
+ * Docker reserves exit code 125 for its own failures, but a contained process
+ * that exits 125 passes that code through indistinguishably — so the code alone
+ * is not enough, and docker's own stderr voice ("Unable to find image …",
+ * "docker: Error response from daemon: …", "docker: Cannot connect …") is
+ * required alongside it. Only meaningful for a command this code wrapped in
+ * `docker run` itself; a config whose command is already `docker run …` owns
+ * its exit codes.
+ */
+export function isDockerRunFailure(message) {
+    return /server exited \(code 125\)/.test(message) && /Unable to find image|docker: /.test(message);
+}
+function runDocker(args) {
+    return import('node:child_process').then(({ spawn }) => new Promise((resolve) => {
+        const child = spawn('docker', args, { stdio: ['ignore', 'ignore', 'pipe'] });
+        let stderr = '';
+        child.stderr.setEncoding('utf8');
+        child.stderr.on('data', (chunk) => (stderr = (stderr + chunk).slice(-4000)));
+        child.on('error', (err) => resolve({ code: null, stderr: String(err.message) }));
+        child.on('exit', (code) => resolve({ code, stderr }));
+    }));
+}
+async function ensureImageOnce(image, opts) {
+    const run = opts.run ?? runDocker;
+    const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const delays = opts.delaysMs ?? [2_000, 8_000];
+    const noDocker = (stderr) => new DockerHarnessFault(`docker is not runnable on this machine: ${stderr.trim() || 'spawn docker failed'}`);
+    const inspect = await run(['image', 'inspect', image]);
+    if (inspect.code === 0)
+        return;
+    if (inspect.code === null && /ENOENT/i.test(inspect.stderr))
+        throw noDocker(inspect.stderr);
+    let lastStderr = '';
+    for (let attempt = 1; attempt <= delays.length + 1; attempt++) {
+        const pull = await run(['pull', image]);
+        if (pull.code === 0)
+            return;
+        lastStderr = pull.stderr;
+        // A missing docker binary cannot appear on a later attempt.
+        if (pull.code === null && /ENOENT/i.test(pull.stderr))
+            throw noDocker(pull.stderr);
+        if (attempt <= delays.length)
+            await sleep(delays[attempt - 1]);
+    }
+    throw new DockerHarnessFault(`could not pull ${image} after ${delays.length + 1} attempts — ` +
+        `a statement about this machine and its registry path, not about any server: ${lastStderr.slice(-300).trim()}`);
+}
+const ensured = new Map();
+/**
+ * Make sure a base image is present before any container needs it, retrying the
+ * pull. `docker run --pull=missing` pulls lazily, so a transient registry
+ * failure lands mid-measurement and gets read as the server refusing to start —
+ * pulling up front, with retries, is what keeps a registry hiccup from ever
+ * reaching a measurement. Failures throw `DockerHarnessFault`.
+ *
+ * Results are memoized per image for the life of the process (only on the real
+ * docker path — injected runners are for tests), so concurrent sweep workers
+ * share one pull, and an image that could not be pulled after retries is not
+ * re-attempted by every remaining server in the sweep.
+ */
+export function ensureImage(image, opts = {}) {
+    if (opts.run)
+        return ensureImageOnce(image, opts);
+    let p = ensured.get(image);
+    if (!p) {
+        p = ensureImageOnce(image, opts);
+        // Mark handled so a memoized rejection never trips unhandled-rejection
+        // before the next caller awaits it.
+        p.catch(() => { });
+        ensured.set(image, p);
+    }
+    return p;
+}
 /**
  * Wrap a launch command line in `docker run`. The inner command is passed to
  * `sh -lc` inside the container; quoting is preserved by argv (no host shell).
  */
 export function dockerize(commandLine, opts = {}) {
-    const image = opts.image ?? (commandLine.trimStart().startsWith('uvx') ? DEFAULT_PYTHON_IMAGE : DEFAULT_NODE_IMAGE);
+    const image = opts.image ?? defaultImageFor(commandLine);
     const argv = [
         'run',
         '--rm',
@@ -36,6 +126,9 @@ export function dockerize(commandLine, opts = {}) {
                 'UV_CACHE_DIR=/tmp/.uv-cache',
             ]),
     ];
+    for (const bind of opts.binds ?? []) {
+        argv.push('-v', bind);
+    }
     for (const name of opts.dummyEnv ?? []) {
         argv.push('-e', `${name}=${opts.dummyEnvValues?.[name] ?? 'dummy'}`);
     }

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

@@ -0,0 +1,114 @@
+import { type ServerEntry } from './report.js';
+export interface PublishedStats {
+    candidateTotal: number;
+    measuredCount: number;
+    max: {
+        name: string;
+        tokens: number;
+    };
+    second: {
+        name: string;
+        tokens: number;
+    };
+    min: {
+        name: string;
+        tokens: number;
+    };
+    /** max/min, floored to two significant digits — a span claim must not overstate. */
+    spanTimes: number;
+    /** The heaviest server's share of the default context window, rounded %. */
+    maxContextSharePct: number;
+    /** The servers README's sample table names, with their current numbers. */
+    sample: Record<string, {
+        tokens: number;
+        tools: number;
+    }>;
+    claude: {
+        runSize: number;
+        /** Rows the leaderboard prints a claude number for: measured AND capture-current. */
+        currentCount: number;
+        heaviestClaudeName: string | null;
+        github: {
+            badgeTokens: number;
+            mappedTokens: number;
+            claudeTokens: number;
+            droppedPct: number;
+        };
+        notion: {
+            badgeTokens: number;
+            claudeTokens: number;
+        };
+        /** Field-selection share across the run's rows, as fractions of the payload. */
+        shareMin: number;
+        shareMax: number;
+        /** claudeDelta / o200kFull across the run's rows that carry a number. */
+        ratioMin: number;
+        ratioMax: number;
+    };
+    deferralCostlierCount: number;
+    verify: {
+        serverName: string;
+        tokens: number;
+    };
+}
+/** Named in README's sample table — the choice is editorial, the numbers are not. */
+export declare const SAMPLE_SERVERS: readonly ['github', 'xcodebuildmcp', 'brave-search', 'notion', 'playwright', 'filesystem', 'markitdown'];
+export declare function floorToTwoSignificant(n: number): number;
+export declare function computePublishedStats(entries: ServerEntry[], root?: string): PublishedStats;
+export type PageFile = 'README.md' | 'docs/index.md' | 'docs/METHODOLOGY.md';
+export declare const PAGE_FILES: PageFile[];
+/**
+ * One maintained sentence. `template` is its exact words with slots — `{n}` a
+ * comma-formatted count, `{d}` a bare integer, `{f}` a decimal, `{w}` a server
+ * or package name — and `values` is what the slots must hold for the data on
+ * disk.
+ */
+export interface Claim {
+    file: PageFile;
+    id: string;
+    template: string;
+    values(stats: PublishedStats): string[];
+}
+export declare const PAGE_CLAIMS: Claim[];
+/**
+ * Claims whose truth the data decides but whose words no template can rewrite —
+ * prose whose shape would have to change with the answer. These are asserted in
+ * the suite, never patched: if one goes false a person rewrites the sentence.
+ */
+export interface CheckClaim {
+    file: PageFile;
+    id: string;
+    /** The page's words, template-escaped like any claim (wrapping-tolerant). */
+    words: string;
+    /** null when the data agrees with the words; otherwise why it does not. */
+    holds(stats: PublishedStats): string | null;
+}
+export declare const CHECK_CLAIMS: CheckClaim[];
+/** Fixed words with `\s+` for every gap (prose wraps; a claim is its words, not its layout). */
+export declare function compileTemplate(template: string): RegExp;
+export interface ClaimApplication {
+    text: string;
+    /** Why the claim could not be applied — a missing or ambiguous anchor. */
+    problem: string | null;
+    /** True when a slot was rewritten. */
+    changed: boolean;
+}
+/** Apply one claim: find its anchor exactly once, splice the slots to `want`, touch nothing else. */
+export declare function applyClaim(text: string, claim: Pick<Claim, 'file' | 'id' | 'template'>, want: string[]): ClaimApplication;
+export interface PagePatch {
+    text: string;
+    problems: string[];
+    /** Claim ids whose slots were rewritten. */
+    updated: string[];
+}
+/** Apply every claim for one page to its text. Slots are spliced in place; anchors are never rewritten. */
+export declare function patchPageText(file: PageFile, text: string, stats: PublishedStats): PagePatch;
+export interface PublishedStatsResult {
+    problems: string[];
+    updated: string[];
+    changedFiles: PageFile[];
+}
+/** Compute stats and report what regen would rewrite, without writing anything. */
+export declare function verifyPublishedPages(entries: ServerEntry[], root?: string): PublishedStatsResult;
+/** Compute stats and rewrite the pages in place. Returns what changed and any refusals. */
+export declare function applyPublishedStats(entries: ServerEntry[], root?: string): PublishedStatsResult;