mcp-context-cost 0.4.0 → 0.6.0

package/dist/sweep/harness-guard.js

@@ -0,0 +1,144 @@
+/**
+ * A broken harness must not republish the whole set as failures.
+ *
+ * `measureServer` already adjudicates a *single* suspicious result — a
+ * startup-failure gets re-attempted off a cold cache, a timeout on double the
+ * budget (see run.ts). Neither retry can see the one failure mode that isn't
+ * about any individual server: the machine doing the measuring is broken.
+ * That is not hypothetical here — an orphaned Docker backend with a wedged
+ * network stack once returned 0/79 uniform timeouts, and every one of those
+ * results was a lie about a working server. The per-server retries make that
+ * case *worse*, not better: each one re-runs through the same broken harness
+ * and comes back failing again, which reads as confirmation.
+ *
+ * The signal a single measurement can't carry is population-level. A wave of
+ * servers that were measuring fine yesterday and all fail at once is a
+ * statement about the harness, not about the servers — upstream breakages
+ * arrive a package at a time, not by the dozen. So: snapshot what was on
+ * record before the sweep, count how many good measurements this sweep turned
+ * into failures, and if that count is both large in absolute terms and a
+ * majority of what it could have broken, refuse to publish, put the previous
+ * results back, and exit non-zero.
+ *
+ * Restoring is what makes this safe to run unattended: `measureServer`
+ * persists each result the moment it has one, so by the time a sweep-level
+ * verdict is possible the damage is already on disk. Holding the prior bytes
+ * in memory turns an irreversible overwrite into a reversible one.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * 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 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 const FAULT_RATIO = 0.5;
+/** Statuses that represent a real number on record — the thing worth protecting. */
+export function isGood(status) {
+    return status === 'measured' || status === 'dynamic';
+}
+/**
+ * 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 function snapshot(names, root = process.cwd()) {
+    return names.map((name) => {
+        const mPath = join(root, 'results', name, 'measurement.json');
+        const bPath = join(root, 'badges', `${name}.json`);
+        const measurementJson = existsSync(mPath) ? readFileSync(mPath, 'utf8') : null;
+        const badgeJson = existsSync(bPath) ? readFileSync(bPath, 'utf8') : null;
+        let status = null;
+        if (measurementJson) {
+            try {
+                status = JSON.parse(measurementJson).status;
+            }
+            catch {
+                // An unreadable prior record is not evidence of anything; treat it as
+                // no record rather than as a good one that just broke.
+                status = null;
+            }
+        }
+        return { name, status, measurementJson, badgeJson };
+    });
+}
+/**
+ * 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 function verdict(prior, current) {
+    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;
+    if (comparable === 0) {
+        return {
+            fault: false,
+            regressed,
+            comparable,
+            // Not a pass — an unavailable reading. Nothing on record measured well
+            // before this sweep, so there is no baseline to judge it against.
+            reason: 'no prior measurement to compare against — harness check not performed',
+        };
+    }
+    const ratio = regressed.length / comparable;
+    const pct = (ratio * 100).toFixed(0);
+    if (regressed.length >= 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, ` +
+                `${(FAULT_RATIO * 100).toFixed(0)}% threshold that reads as a broken harness ` +
+                `rather than broken servers`,
+        };
+    }
+    return {
+        fault: false,
+        regressed,
+        comparable,
+        reason: `${regressed.length} of ${comparable} previously-measured servers (${pct}%) failed in ` +
+            `this sweep — below the harness-fault threshold, publishing normally`,
+    };
+}
+/**
+ * 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 function restore(prior, names, root = process.cwd()) {
+    const wanted = new Set(names);
+    const restored = [];
+    for (const s of prior) {
+        if (!wanted.has(s.name))
+            continue;
+        if (s.measurementJson === null && s.badgeJson === null)
+            continue;
+        if (s.measurementJson !== null) {
+            const dir = join(root, 'results', s.name);
+            mkdirSync(dir, { recursive: true });
+            writeFileSync(join(dir, 'measurement.json'), s.measurementJson);
+        }
+        if (s.badgeJson !== null) {
+            mkdirSync(join(root, 'badges'), { recursive: true });
+            writeFileSync(join(root, 'badges', `${s.name}.json`), s.badgeJson);
+        }
+        restored.push(s.name);
+    }
+    return restored;
+}

package/dist/sweep/history.d.ts

@@ -7,8 +7,18 @@ export interface HistoryRow {
     toolCount: number;
     /** 'measured' or 'dynamic' — dynamic means the tool set moved between captures. */
     status: string;
+    /**
+     * How the measurement was taken: `docker` (isolated container), `host` (bare
+     * machine), or `''` when the row predates this column and the conditions are
+     * not on record. Two numbers taken under different isolation are not
+     * comparable — same server, different node, different resolution of an
+     * `@latest` tag, different ambient env — so a step between them is a property
+     * of the harness, not of the server. Recording it is what lets the trend line
+     * refuse to draw such a step; see `plottableSeries`.
+     */
+    isolation: string;
 }
-export declare const HISTORY_HEADER = "date,server,tokens,toolCount,status";
+export declare const HISTORY_HEADER = "date,server,tokens,toolCount,status,isolation";
 /** Parse history.csv text; malformed or non-numeric rows are dropped, not thrown. */
 export declare function parseHistory(text: string): HistoryRow[];
 export declare function formatHistory(rows: HistoryRow[]): string;
@@ -19,6 +29,7 @@ export declare function upsert(rows: HistoryRow[], row: HistoryRow): HistoryRow[
  * auth walls are recorded in the leaderboard's "not measured" section, and
  * writing them here as zeros would fabricate a drop to zero in the series.
  */
+export declare function isolationOf(m: Measurement): string;
 export declare function rowFor(server: string, m: Measurement): HistoryRow | null;
 /**
  * Fold every results/<server>/measurement.json into results/history.csv.
@@ -28,3 +39,24 @@ export declare function appendHistory(root?: string): {
     rows: number;
     added: number;
 };
+export interface PlottableSeries {
+    /** The rows a trend may be drawn across, oldest first. */
+    rows: HistoryRow[];
+    /** Older rows excluded because they were measured under a different isolation. */
+    dropped: number;
+    /** True when a plotted row's conditions are not on record (a pre-`isolation` write). */
+    conditionsUnknown: boolean;
+}
+/**
+ * The longest run of a server's history, ending at its newest row, that a trend
+ * line may honestly be drawn across.
+ *
+ * Walking back from the newest row, a row stops the run when its isolation is
+ * known, the newest row's isolation is known, and the two differ — a step across
+ * that boundary would say the server changed when what changed is how it was
+ * measured. An *unknown* isolation is not evidence either way, so it stays in
+ * the run and is reported through `conditionsUnknown` instead: the alternative,
+ * treating unknown as its own incompatible value, would silently blank every
+ * series recorded before this column existed.
+ */
+export declare function plottableSeries(rows: HistoryRow[]): PlottableSeries;

package/dist/sweep/history.js

@@ -8,7 +8,7 @@
  */
 import { existsSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-export const HISTORY_HEADER = 'date,server,tokens,toolCount,status';
+export const HISTORY_HEADER = 'date,server,tokens,toolCount,status,isolation';
 function csvCell(s) {
     const v = String(s ?? '');
     return /[",\n]/.test(v) ? `"${v.replace(/"/g, '""')}"` : v;
@@ -48,18 +48,27 @@ export function parseHistory(text) {
     for (const line of text.split('\n')) {
         if (!line.trim() || line.startsWith('date,'))
             continue;
-        const [date, server, tokens, toolCount, status] = splitCsvLine(line);
+        const [date, server, tokens, toolCount, status, isolation] = splitCsvLine(line);
         if (!/^\d{4}-\d{2}-\d{2}$/.test(date ?? '') || !server)
             continue;
         if (!/^\d+$/.test(tokens ?? '') || !/^\d+$/.test(toolCount ?? ''))
             continue;
-        rows.push({ date, server, tokens: Number(tokens), toolCount: Number(toolCount), status: status ?? '' });
+        // A 5-field row is a pre-`isolation` write: its conditions are unknown, and
+        // unknown is recorded as unknown rather than back-filled with a guess.
+        rows.push({
+            date,
+            server,
+            tokens: Number(tokens),
+            toolCount: Number(toolCount),
+            status: status ?? '',
+            isolation: isolation ?? '',
+        });
     }
     return rows;
 }
 export function formatHistory(rows) {
     const sorted = [...rows].sort((a, b) => a.date.localeCompare(b.date) || a.server.localeCompare(b.server));
-    const lines = sorted.map((r) => [csvCell(r.date), csvCell(r.server), r.tokens, r.toolCount, csvCell(r.status)].join(','));
+    const lines = sorted.map((r) => [csvCell(r.date), csvCell(r.server), r.tokens, r.toolCount, csvCell(r.status), csvCell(r.isolation)].join(','));
     return [HISTORY_HEADER, ...lines].join('\n') + '\n';
 }
 /** Upsert one row by (date, server) — the newest write for a day wins. */
@@ -76,6 +85,11 @@ export function upsert(rows, row) {
  * auth walls are recorded in the leaderboard's "not measured" section, and
  * writing them here as zeros would fabricate a drop to zero in the series.
  */
+export function isolationOf(m) {
+    if (!m.isolation)
+        return '';
+    return m.isolation.docker ? 'docker' : 'host';
+}
 export function rowFor(server, m) {
     if (m.status !== 'measured' && m.status !== 'dynamic')
         return null;
@@ -84,7 +98,14 @@ export function rowFor(server, m) {
     const date = String(m.measuredAt ?? '').slice(0, 10);
     if (!/^\d{4}-\d{2}-\d{2}$/.test(date))
         return null;
-    return { date, server, tokens: m.totalTokens, toolCount: m.toolCount, status: m.status };
+    return {
+        date,
+        server,
+        tokens: m.totalTokens,
+        toolCount: m.toolCount,
+        status: m.status,
+        isolation: isolationOf(m),
+    };
 }
 /**
  * Fold every results/<server>/measurement.json into results/history.csv.
@@ -118,3 +139,37 @@ export function appendHistory(root = process.cwd()) {
     writeFileSync(path, formatHistory(rows));
     return { rows: rows.length, added: rows.length - existing.length };
 }
+/**
+ * The longest run of a server's history, ending at its newest row, that a trend
+ * line may honestly be drawn across.
+ *
+ * Walking back from the newest row, a row stops the run when its isolation is
+ * known, the newest row's isolation is known, and the two differ — a step across
+ * that boundary would say the server changed when what changed is how it was
+ * measured. An *unknown* isolation is not evidence either way, so it stays in
+ * the run and is reported through `conditionsUnknown` instead: the alternative,
+ * treating unknown as its own incompatible value, would silently blank every
+ * series recorded before this column existed.
+ */
+export function plottableSeries(rows) {
+    const sorted = [...rows].sort((a, b) => a.date.localeCompare(b.date));
+    if (!sorted.length)
+        return { rows: [], dropped: 0, conditionsUnknown: false };
+    const current = sorted[sorted.length - 1].isolation;
+    let start = 0;
+    if (current) {
+        for (let i = sorted.length - 1; i >= 0; i--) {
+            const iso = sorted[i].isolation;
+            if (iso && iso !== current) {
+                start = i + 1;
+                break;
+            }
+        }
+    }
+    const kept = sorted.slice(start);
+    return {
+        rows: kept,
+        dropped: start,
+        conditionsUnknown: kept.some((r) => !r.isolation),
+    };
+}

package/dist/sweep/regen.js

@@ -1,14 +1,19 @@
-/** Regenerate leaderboard + history + server pages from results/: npx tsx src/sweep/regen.ts */
+/** Regenerate leaderboard + history + server pages + dashboard from results/: npx tsx src/sweep/regen.ts */
 import { readFileSync } from 'node:fs';
 import { parse } from 'yaml';
 import { writeLeaderboard, percentiles } from './report.js';
 import { appendHistory } from './history.js';
 import { writeServerPages } from './server-pages.js';
+import { writeDashboard } from './dashboard.js';
 const doc = parse(readFileSync('servers.yaml', 'utf8'));
 writeLeaderboard(doc.servers);
 // History first: the server pages read history.csv for their over-time table.
 const h = appendHistory();
 const p = writeServerPages(doc.servers);
+// The dashboard reads the same results/ and history.csv as the pages do, so it
+// belongs in the same refresh — see writeDashboard's note on why it wasn't.
+const d = writeDashboard();
 console.log('leaderboard:', JSON.stringify(percentiles(doc.servers)));
 console.log(`history: ${h.rows} rows (${h.added >= 0 ? '+' : ''}${h.added})`);
 console.log(`server pages: ${p.pages}`);
+console.log(`dashboard: ${d.out} (${(d.bytes / 1024).toFixed(0)}KB)`);

package/dist/sweep/report.d.ts

@@ -1,4 +1,5 @@
 import { type DivergenceRun } from '../core/divergence.js';
+import { type SessionStartLoad, type SessionStartRun } from '../core/session-start.js';
 export interface ServerEntry {
     name: string;
     command: string;
@@ -13,11 +14,26 @@ export interface ServerEntry {
     timeoutSeconds?: number;
     /** Launch needs the `git` binary (e.g. `uvx --from git+...`) — absent from the slim isolation images. */
     needsGit?: boolean;
+    /**
+     * Per-var overrides for the literal `dummy` placeholder docker mode injects
+     * for `env` names — for servers that parse a var's shape (URI scheme, URL)
+     * before ever reaching tools/list. See docker.ts `dummyEnvValues`.
+     */
+    envValues?: Record<string, string>;
 }
 /** Neutralize markdown/table syntax in third-party strings (tool names, notes). */
 export declare function mdCell(s: unknown): string;
 /** results/divergence.json if a divergence run has been recorded, else null. */
 export declare function loadDivergence(root?: string): DivergenceRun | null;
+/** results/session-start.json — the instructions backfill, if one exists. */
+export declare function loadSessionStartRun(root?: string): SessionStartRun | null;
+/**
+ * A session-start figure that is a floor reads `>= N`, never a bare `N`. The
+ * marker is half the point of publishing the number: the names half is measured,
+ * the instructions half has not been captured for this server, and a reader has
+ * to be able to tell that from a row where both halves are known.
+ */
+export declare function sessionStartCell(load: SessionStartLoad | null): string;
 export declare function writeLeaderboard(entries: ServerEntry[], root?: string): void;
 /** Percentile helper for freezing color bands against the observed distribution. */
 export declare function percentiles(entries: ServerEntry[], root?: string): Record<string, number>;

package/dist/sweep/report.js

@@ -5,6 +5,7 @@
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { isCurrent, parseDivergence } from '../core/divergence.js';
+import { SESSION_START_METHOD, parseSessionStart, sessionStartLoad, } from '../core/session-start.js';
 /** Neutralize markdown/table syntax in third-party strings (tool names, notes). */
 export function mdCell(s) {
     return String(s ?? '')
@@ -27,9 +28,28 @@ export function loadDivergence(root = process.cwd()) {
     const p = join(root, 'results', 'divergence.json');
     return existsSync(p) ? parseDivergence(readFileSync(p, 'utf8')) : null;
 }
+/** results/session-start.json — the instructions backfill, if one exists. */
+export function loadSessionStartRun(root = process.cwd()) {
+    const p = join(root, 'results', 'session-start.json');
+    return existsSync(p) ? parseSessionStart(readFileSync(p, 'utf8')) : null;
+}
+/**
+ * A session-start figure that is a floor reads `>= N`, never a bare `N`. The
+ * marker is half the point of publishing the number: the names half is measured,
+ * the instructions half has not been captured for this server, and a reader has
+ * to be able to tell that from a row where both halves are known.
+ */
+export function sessionStartCell(load) {
+    if (!load)
+        return '—';
+    return `${load.isFloor ? '≥' : ''}${load.totalTokens.toLocaleString('en-US')}`;
+}
 export function writeLeaderboard(entries, root = process.cwd()) {
     const rows = loadRows(entries, root);
     const div = loadDivergence(root);
+    const ss = loadSessionStartRun(root);
+    /** Session-start load for a row, or null when there is no capture to read. */
+    const session = (r) => r.m ? sessionStartLoad(r.m, ss?.servers[r.entry.name]) : null;
     /** Claude tokens for a row, or null when not measured / stale / errored. */
     const claude = (r) => {
         if (!div || !r.m)
@@ -57,14 +77,57 @@ export function writeLeaderboard(entries, root = process.cwd()) {
             `See [Claude divergence](../docs/METHODOLOGY.md#claude-divergence).`);
         md.push('');
     }
-    md.push(`| # | server | tokens |${div ? ' claude |' : ''} tools | largest tool | status | category |`);
-    md.push(`|---:|---|---:|${div ? '---:|' : ''}---:|---|---|---|`);
+    const floors = measured.filter((r) => session(r)?.isFloor).length;
+    md.push(`The **session start** column is what a client puts in context when it *defers* tool definitions until they ` +
+        `are used: the server's tool names plus the \`instructions\` string it returns from \`initialize\` ` +
+        `(method \`${SESSION_START_METHOD}\`). The tokens column is what a client that loads every definition up ` +
+        `front pays; this one is what the same server costs a client that does not. ` +
+        `See [session-start load](../docs/METHODOLOGY.md#session-start-load).`);
+    md.push('');
+    if (floors > 0) {
+        md.push(`**\`≥\` marks a floor, on ${floors} of ${measured.length} rows.** Tool names are counted exactly from ` +
+            `the published capture, but \`instructions\` is not part of \`tools/list\` and has not been captured for ` +
+            `these servers — so the figure is the names half alone and the true number is that or higher. A row stops ` +
+            `being a floor the first time the server is measured with its instructions.`);
+        md.push('');
+    }
+    // Deferring usually saves almost everything, but it is not guaranteed to save
+    // anything: `instructions` are bytes the headline never counted, and a server
+    // that re-lists its tools in prose can charge a deferring client more than an
+    // eager one. Those rows are the most useful thing this column finds, so they
+    // are named here rather than left for a reader to spot by comparing columns.
+    // Derived on every write — no row is listed by hand, and the paragraph
+    // disappears if the set ever empties, rather than asserting a stale count.
+    const costlier = measured.filter((r) => {
+        const load = session(r);
+        return load !== null && r.m.totalTokens !== null && load.totalTokens >= r.m.totalTokens;
+    });
+    if (costlier.length > 0) {
+        // Server names are backticked, not bolded: the lead sentence is already
+        // bold and a nested `**` would close it early, silently un-bolding the
+        // half of the sentence that carries the finding.
+        const named = costlier
+            .map((r) => {
+            const load = session(r);
+            return `\`${mdCell(r.entry.name)}\` pays ${load.isFloor ? '≥' : ''}${load.totalTokens.toLocaleString('en-US')} at session start against ${r.m.totalTokens.toLocaleString('en-US')} of definitions`;
+        })
+            .join('; ');
+        md.push(`**Deferring costs more than it saves on ${costlier.length} of ${measured.length} rows.** ${named}. ` +
+            `The names half is always a fraction of the headline, but \`instructions\` are bytes the tokens column ` +
+            `never counted and their length is independent of the tool set — so a server that re-lists its tools in ` +
+            `its instructions makes a deferring client pay for a prose copy of the schemas it just skipped. ` +
+            `A client that defers definitions is better off on every other measured row and worse off on ${costlier.length === 1 ? 'this one' : 'these'}.`);
+        md.push('');
+    }
+    md.push(`| # | server | tokens | session start |${div ? ' claude |' : ''} tools | largest tool | status | category |`);
+    md.push(`|---:|---|---:|---:|${div ? '---:|' : ''}---:|---|---|---|`);
     measured.forEach((r, i) => {
         const m = r.m;
         const largest = [...m.tools].sort((a, b) => b.tokens - a.tokens)[0];
         const link = `[${mdCell(r.entry.name)}](../docs/servers/${encodeURIComponent(r.entry.name)}.md)`;
         const c = claude(r);
         md.push(`| ${i + 1} | ${link} | ${m.totalTokens.toLocaleString('en-US')} |` +
+            ` ${sessionStartCell(session(r))} |` +
             (div ? ` ${c === null ? '—' : c.toLocaleString('en-US')} |` : '') +
             ` ${m.toolCount} | ` +
             `${largest ? `${mdCell(largest.name)} (${largest.tokens.toLocaleString('en-US')})` : '—'} | ${m.status} | ${mdCell(r.entry.category)} |`);
@@ -82,12 +145,17 @@ export function writeLeaderboard(entries, root = process.cwd()) {
         md.push('');
     }
     writeFileSync(join(root, 'results', 'leaderboard.md'), md.join('\n') + '\n');
-    // Columns are append-only: consumers key off the header, so adding the Claude
-    // pair at the end leaves every existing parser working.
-    const csv = ['name,tokens,toolCount,status,category,metric,metricSource,claudeTokens,claudeModel'];
+    // Columns are append-only: consumers key off the header, so each new group
+    // (the Claude pair, then the session-start four) goes on the end and leaves
+    // every existing parser working.
+    const csv = [
+        'name,tokens,toolCount,status,category,metric,metricSource,claudeTokens,claudeModel,' +
+            'sessionStartTokens,sessionStartIsFloor,toolNameTokens,instructionsTokens',
+    ];
     for (const r of rows) {
         const m = r.m;
         const c = claude(r);
+        const ssl = session(r);
         csv.push([
             csvCell(r.entry.name),
             m?.totalTokens ?? '',
@@ -98,6 +166,12 @@ export function writeLeaderboard(entries, root = process.cwd()) {
             csvCell(r.entry.metricSource),
             c ?? '',
             c === null ? '' : csvCell(div.model),
+            ssl?.totalTokens ?? '',
+            // Spelled out rather than left implicit: a consumer that ignores this
+            // column and sums the previous one is understating every floor row.
+            ssl ? String(ssl.isFloor) : '',
+            ssl?.toolNameTokens ?? '',
+            ssl?.instructionsTokens ?? '',
         ].join(','));
     }
     writeFileSync(join(root, 'results', 'leaderboard.csv'), csv.join('\n') + '\n');

package/dist/sweep/run.d.ts

@@ -7,6 +7,8 @@ export interface MeasureOptions {
     dockerImage?: string;
     /** env var NAMES to provide as dummy values (docker mode). */
     dummyEnv?: string[];
+    /** Override the literal `dummy` value for specific `dummyEnv` names — see docker.ts. */
+    dummyEnvValues?: Record<string, string>;
     /** Install `git` in the container before launch (docker mode) — see docker.ts. */
     needsGit?: boolean;
     /**
@@ -21,4 +23,43 @@ export interface MeasureOptions {
      */
     persist?: boolean;
 }
+/**
+ * Marks a startup-failure that was re-attempted from a cold package cache and
+ * failed the same way. Its absence on a startup-failure means the retry never
+ * ran (host mode, or a self-containerised command), not that it passed.
+ */
+export declare const RETRY_CONFIRMED_PREFIX = "reproduced with the shared package cache bypassed; ";
+/**
+ * Whether a failed measurement gets a second attempt with the shared package
+ * caches bypassed (see `DockerOptions.noSharedCache`).
+ *
+ * A poisoned cache entry and a genuinely broken server produce the same exit
+ * code, so a `startup-failure` is not published until it reproduces from a cold
+ * cache. Deliberately only `startup-failure`: a `timeout` is usually the slow
+ * install a cold retry would only make slower (it has its own retry — see
+ * `retriesWithLongerTimeout`), `auth-required` is a real answer about the
+ * server, and a command that is already its own `docker run` has no cache mount
+ * to bypass.
+ */
+export declare function retriesWithoutSharedCache(status: Measurement['status'], docker: boolean, command: string): boolean;
+/**
+ * Marks a `timeout` that was re-attempted on a larger budget and timed out
+ * again. Its absence on a timeout means the retry never ran, not that it passed.
+ */
+export declare const TIMEOUT_CONFIRMED_PREFIX = "reproduced on double the timeout budget; ";
+/** A timed-out measurement is re-attempted on this multiple of its budget. */
+export declare const TIMEOUT_RETRY_FACTOR = 2;
+/**
+ * Whether a timed-out measurement gets a second attempt on a larger budget.
+ *
+ * Sweeps and `audit` both run a worker pool, and a server that starts slowly
+ * under that contention is indistinguishable from one that never starts: both
+ * come back `timeout`. Two servers were published as failures for exactly this
+ * reason (`puppeteer` and `kubernetes`, 2026-08-19) and measured normally when
+ * re-run alone, so a timeout is not published until it survives a second, wider
+ * budget. Unlike the cold-cache retry this is isolation-independent — contention
+ * is not a property of the package cache, so host runs and commands that are
+ * their own `docker run` are retried too.
+ */
+export declare function retriesWithLongerTimeout(status: Measurement['status']): boolean;
 export declare function measureServer(name: string, command: string, opts?: MeasureOptions): Promise<Measurement>;