mcp-context-cost 0.13.2 → 0.15.0

package/dist/audit/deferral.d.ts

@@ -37,11 +37,34 @@
  *     generation; `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` "keeps tool search
  *     off. You can't override it by setting `ENABLE_TOOL_SEARCH` yourself."
  *     A server with `alwaysLoad: true` loads at session start regardless.
+ *   - The same page, re-read 2026-09-06 (the roadmap's dated re-read). The
+ *     value table stands as quoted, and four things moved around it:
+ *     (1) on Google Cloud's Agent Platform, tool search is on by default for
+ *     the Claude 4.5 generation and later "the same as on the Anthropic API"
+ *     — "Before v2.1.221, Claude Code disabled tool search for all models on
+ *     Google Cloud's Agent Platform unless you set ENABLE_TOOL_SEARCH=true";
+ *     the exception below already names only the earlier models. (2) Under
+ *     `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS`, "your organization can keep
+ *     tool search on through managed settings, on Claude Code v2.1.227 or
+ *     later" — on a direct connection or a gateway, not on a cloud provider.
+ *     This audit reads the managed settings file for the three variables and
+ *     nothing else, so that override is not read here and the variable is
+ *     still resolved as "off". (3) `alwaysLoad: true` is an entry field on
+ *     every server type, and a tool can carry `"anthropic/alwaysLoad": true`
+ *     in its `_meta`. The entry form is read from the config now
+ *     (`DeferralServer.alwaysLoad`) and counted rather than listed; the
+ *     per-tool form is still a listed condition. (4) "Claude Code truncates
+ *     tool descriptions and server instructions at 2KB each", which bounds what
+ *     a deferring session loads at start — noted beside the session-start
+ *     metric in METHODOLOGY, not applied to any number here.
  *
- * No default deferral is on record here for the other four clients this tool
- * discovers. That is an absence of a record, not a measurement of those
- * clients, and it is printed as such — the same rule the rest of this project
- * follows for a value it has not observed.
+ * No default deferral is on record here for the other clients this tool
+ * discovers — Claude Desktop, Cursor, VS Code, Windsurf, and from 2026-09-06
+ * Codex CLI, Gemini CLI, Zed, Kiro and Goose, whose configuration pages were
+ * read that day and say nothing about deferring tool definitions. That is an
+ * absence of a record, not a measurement of those clients, and it is printed
+ * as such — the same rule the rest of this project follows for a value it has
+ * not observed.
  */
 import type { DivergenceRun } from '../core/divergence.js';
 /** Share of the context window at which deferral activates under `auto`. */
@@ -267,8 +290,17 @@ export declare const PUBLISHED_WIRE_TO_CLIENT_RATIO: WireToClientRatio;
 export declare function wireToClientRatio(run?: DivergenceRun | null): WireToClientRatio;
 /** One measured server, as the deferral arithmetic needs it. */
 export interface DeferralServer {
+    /** For naming the servers a verdict singles out; the arithmetic never reads it. */
+    name?: string;
     /** o200k tokens over the wire capture — the audit's own unit. */
     tokens: number;
+    /**
+     * The entry is pinned `alwaysLoad: true`, so its tools load at session start
+     * whatever the tool-search setting says, and it does not count toward a
+     * threshold — the documented `auto` mode counts "the tools it would
+     * otherwise defer".
+     */
+    alwaysLoad?: boolean;
     /**
      * Anthropic's own count for this server from a current divergence row, when
      * `--claude` supplied one. `null` means no current match, `undefined` means
@@ -367,6 +399,15 @@ export interface DeferralVerdict {
     sharedMeasurements: number;
     /** Conditions this cannot read, under which a deferring client pays in full. */
     exceptions: string[];
+    /**
+     * Servers in this scope pinned `alwaysLoad: true` in their entry, and their
+     * wire tokens. Read from the config, so it is stated rather than listed as a
+     * condition: whatever the mode, these load at session start.
+     */
+    alwaysLoad: {
+        servers: string[];
+        tokens: number;
+    };
 }
 /**
  * Read one session's deferral position. Pure arithmetic over a built scope — no

package/dist/audit/deferral.js

@@ -286,8 +286,23 @@ export function wireToClientRatio(run) {
         return PUBLISHED_WIRE_TO_CLIENT_RATIO;
     return { low, high, fixedOverhead, servers, source: `the ${run.measuredAt} ${run.model} divergence run` };
 }
-/** Clients this tool discovers that have no default deferral on record. */
-const NO_DEFERRAL_ON_RECORD = new Set(['claude-desktop', 'cursor', 'vscode', 'windsurf']);
+/**
+ * Clients this tool discovers that have no default deferral on record. Each
+ * client's own MCP configuration page was read on the date config.ts gives
+ * and says nothing about deferring tool definitions — Windsurf's states a cap
+ * of 100 tools, which is a different thing and not a deferral.
+ */
+const NO_DEFERRAL_ON_RECORD = new Set([
+    'claude-desktop',
+    'cursor',
+    'vscode',
+    'windsurf',
+    'codex',
+    'gemini',
+    'zed',
+    'kiro',
+    'goose',
+]);
 /**
  * Where deferral does not apply even when the machine's setting says it should.
  * None of these can be read from the config or the environment, so they are
@@ -298,7 +313,7 @@ const EXCEPTIONS = [
     'a Microsoft Foundry deployment hosted on Azure, which rejects tool search server-side',
     "Google Cloud's Agent Platform on a model earlier than the Claude 4.5 generation",
     'a model without support for tool_reference blocks (before Sonnet 4.5 / Haiku 4.5 / Opus 4.5)',
-    'a server pinned with "alwaysLoad": true, whose tools load at session start regardless',
+    'a tool whose _meta carries "anthropic/alwaysLoad": true, which this audit does not read from a capture',
 ];
 function estimate(servers, ratio) {
     let low = 0;
@@ -341,6 +356,11 @@ export function evaluateDeferral(scope, opts) {
     const wireTokens = scope.servers.reduce((a, s) => a + s.tokens, 0);
     const isFloor = scope.skippedCount > 0;
     const sharedMeasurements = scope.sharedMeasurements;
+    const pinned = scope.servers.filter((s) => s.alwaysLoad === true);
+    const alwaysLoad = {
+        servers: pinned.map((s) => s.name ?? '(unnamed)'),
+        tokens: pinned.reduce((a, s) => a + s.tokens, 0),
+    };
     // Every field a verdict carries, at its "nothing to say" value. Each mode
     // below overrides only what it can actually answer.
     const base = {
@@ -364,6 +384,7 @@ export function evaluateDeferral(scope, opts) {
         distanceTokens: null,
         crosses: null,
         exceptions: [],
+        alwaysLoad,
     };
     if (scope.client !== 'claude-code') {
         return {
@@ -422,7 +443,9 @@ export function evaluateDeferral(scope, opts) {
         };
     }
     const ratio = wireToClientRatio(opts.divergence);
-    const clientTokens = estimate(scope.servers, ratio);
+    // Only what the client would otherwise defer is held against the threshold;
+    // a pinned server loads either way and is not part of the question.
+    const clientTokens = estimate(scope.servers.filter((s) => s.alwaysLoad !== true), ratio);
     // At-or-above, on the documented "defers all of them once the definitions
     // reach 10%". A range that is entirely over is over even if it is a floor:
     // more unmeasured tokens cannot take it back under.

package/dist/audit/remote.d.ts

@@ -0,0 +1,56 @@
+/**
+ * What a remote MCP endpoint says to a request that carries no credential.
+ *
+ * `audit` used to skip every `url` entry as `remote-not-measurable`, which
+ * under-counted exactly the stacks the audit is for — vendors are moving to
+ * hosted endpoints. The obvious fix, handing every url to the `mcp-remote`
+ * bridge the sweep already measures open endpoints through, is wrong on a
+ * developer machine: against an OAuth-walled endpoint mcp-remote opens a
+ * browser window and waits for the callback (its README says so), which an
+ * audit has no business doing once per server in someone's config; and in a
+ * headless run it waits until this harness's timeout, so the row would read
+ * `timeout` — a word that blames the clock for a credential.
+ *
+ * So the endpoint is asked first, with the request every MCP session begins
+ * with: `initialize` over streamable HTTP, then a GET with an event-stream
+ * `accept` for an SSE endpoint that refuses POST. Probed 2026-09-06 from this
+ * repository: `mcp.linear.app/mcp`, `mcp.zapier.com/api/mcp/mcp` and
+ * `mcp.vercel.com` each answer `401` with a `WWW-Authenticate: Bearer …`
+ * header naming the OAuth resource; `mcp.deepwiki.com/mcp`, `learn.microsoft.com/api/mcp`,
+ * `docs.mcp.cloudflare.com/sse` and `huggingface.co/mcp` answer `200` with a
+ * session or a stream. Nothing is inferred from a hostname: the status line
+ * and the header are the server's own words, and the report quotes them.
+ *
+ * Only an endpoint that answered without a credential is handed to the
+ * bridge, so the bridge never has a reason to open a browser. Header VALUES a
+ * config carries (a static bearer token) are sent with the probe and the
+ * bridge, exactly as env values are spawned into a stdio server, and never
+ * written to a report — see `ConfiguredServer.headers` in config.ts.
+ */
+export interface RemoteProbe {
+    /**
+     * `open`: answered the unauthenticated request as an MCP endpoint does.
+     * `auth-walled`: answered 401 or 403 — it works, and it wants a credential
+     * this audit does not hold. `unreachable`: no MCP answer arrived — a
+     * connection failure, a timeout, or a status that is neither of the above.
+     */
+    kind: 'open' | 'auth-walled' | 'unreachable';
+    /** The HTTP status that decided it, when a response arrived at all. */
+    status?: number;
+    /** The `WWW-Authenticate` header, verbatim (clipped), when the server sent one. */
+    wwwAuthenticate?: string;
+    /** One line a report can print: the server's own words, or the failure's. */
+    detail: string;
+}
+/** What a probe waits for an answer, unless the caller says otherwise. */
+export declare const DEFAULT_PROBE_TIMEOUT_MS = 15000;
+/**
+ * Ask one endpoint, once, and report what it said.
+ *
+ * Never throws: an endpoint this could not reach is a probe result, not a
+ * crash, because the audit goes on to the next server either way.
+ */
+export declare function probeRemote(url: string, opts?: {
+    headers?: Record<string, string>;
+    timeoutMs?: number;
+}): Promise<RemoteProbe>;

package/dist/audit/remote.js

@@ -0,0 +1,126 @@
+/**
+ * What a remote MCP endpoint says to a request that carries no credential.
+ *
+ * `audit` used to skip every `url` entry as `remote-not-measurable`, which
+ * under-counted exactly the stacks the audit is for — vendors are moving to
+ * hosted endpoints. The obvious fix, handing every url to the `mcp-remote`
+ * bridge the sweep already measures open endpoints through, is wrong on a
+ * developer machine: against an OAuth-walled endpoint mcp-remote opens a
+ * browser window and waits for the callback (its README says so), which an
+ * audit has no business doing once per server in someone's config; and in a
+ * headless run it waits until this harness's timeout, so the row would read
+ * `timeout` — a word that blames the clock for a credential.
+ *
+ * So the endpoint is asked first, with the request every MCP session begins
+ * with: `initialize` over streamable HTTP, then a GET with an event-stream
+ * `accept` for an SSE endpoint that refuses POST. Probed 2026-09-06 from this
+ * repository: `mcp.linear.app/mcp`, `mcp.zapier.com/api/mcp/mcp` and
+ * `mcp.vercel.com` each answer `401` with a `WWW-Authenticate: Bearer …`
+ * header naming the OAuth resource; `mcp.deepwiki.com/mcp`, `learn.microsoft.com/api/mcp`,
+ * `docs.mcp.cloudflare.com/sse` and `huggingface.co/mcp` answer `200` with a
+ * session or a stream. Nothing is inferred from a hostname: the status line
+ * and the header are the server's own words, and the report quotes them.
+ *
+ * Only an endpoint that answered without a credential is handed to the
+ * bridge, so the bridge never has a reason to open a browser. Header VALUES a
+ * config carries (a static bearer token) are sent with the probe and the
+ * bridge, exactly as env values are spawned into a stdio server, and never
+ * written to a report — see `ConfiguredServer.headers` in config.ts.
+ */
+/** The first request of every MCP session, which is all a probe needs to send. */
+const INITIALIZE = JSON.stringify({
+    jsonrpc: '2.0',
+    id: 1,
+    method: 'initialize',
+    params: {
+        protocolVersion: '2025-06-18',
+        capabilities: {},
+        clientInfo: { name: 'mcp-context-cost', version: '0' },
+    },
+});
+/** Long enough to be quoted whole in a report, short enough not to be the report. */
+const CLIP = 300;
+const clip = (s) => {
+    const one = s.replace(/\s+/g, ' ').trim();
+    return one.length > CLIP ? `${one.slice(0, CLIP)}…` : one;
+};
+/** What a probe waits for an answer, unless the caller says otherwise. */
+export const DEFAULT_PROBE_TIMEOUT_MS = 15_000;
+/**
+ * Ask one endpoint, once, and report what it said.
+ *
+ * Never throws: an endpoint this could not reach is a probe result, not a
+ * crash, because the audit goes on to the next server either way.
+ */
+export async function probeRemote(url, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_PROBE_TIMEOUT_MS;
+    const configured = opts.headers ?? {};
+    const attempt = async (init) => {
+        const res = await fetch(url, { ...init, signal: AbortSignal.timeout(timeoutMs), redirect: 'follow' });
+        // The headers are the answer. The body is not read — an event stream
+        // stays open for the life of a session, and this is not a session.
+        try {
+            await res.body?.cancel();
+        }
+        catch {
+            /* a body that refuses to be cancelled changes nothing the headers said */
+        }
+        return res;
+    };
+    try {
+        let res = await attempt({
+            method: 'POST',
+            headers: {
+                ...configured,
+                'content-type': 'application/json',
+                accept: 'application/json, text/event-stream',
+                'mcp-protocol-version': '2025-06-18',
+            },
+            body: INITIALIZE,
+        });
+        // The older SSE transport opens its stream on GET and may refuse the POST
+        // outright; an endpoint that does is asked the way it expects to be.
+        if (res.status === 404 || res.status === 405) {
+            res = await attempt({ method: 'GET', headers: { ...configured, accept: 'text/event-stream' } });
+        }
+        return classify(res);
+    }
+    catch (e) {
+        return { kind: 'unreachable', detail: describeFailure(e, timeoutMs) };
+    }
+}
+function classify(res) {
+    const www = res.headers.get('www-authenticate');
+    const type = (res.headers.get('content-type') ?? '').split(';')[0].trim().toLowerCase();
+    if (res.status === 401 || res.status === 403) {
+        return {
+            kind: 'auth-walled',
+            status: res.status,
+            ...(www ? { wwwAuthenticate: clip(www) } : {}),
+            detail: `HTTP ${res.status}${www ? ` — WWW-Authenticate: ${clip(www)}` : ''}`,
+        };
+    }
+    if (res.ok) {
+        // A JSON-RPC answer or an event stream is what an MCP endpoint sends. A
+        // 200 carrying HTML is a login page or a docs site at that address.
+        if (type === 'application/json' || type === 'text/event-stream') {
+            return { kind: 'open', status: res.status, detail: `HTTP ${res.status} ${type}` };
+        }
+        return {
+            kind: 'unreachable',
+            status: res.status,
+            detail: `HTTP ${res.status} with ${type || 'no content-type'}, which is not an MCP response`,
+        };
+    }
+    return { kind: 'unreachable', status: res.status, detail: `HTTP ${res.status}` };
+}
+function describeFailure(e, timeoutMs) {
+    const err = e;
+    if (err?.name === 'TimeoutError' || err?.name === 'AbortError')
+        return `no answer within ${timeoutMs}ms`;
+    // Node's fetch wraps the socket error: "fetch failed" with the code underneath.
+    const code = err?.cause?.code;
+    if (code)
+        return code;
+    return err?.cause?.message ?? err?.message ?? String(e);
+}

package/dist/audit/run.d.ts

@@ -4,7 +4,8 @@ import { type ToolShapeBaseline } from '../core/tool-shape.js';
 import { type CaptureIndex } from '../core/capture-index.js';
 import { type AuditReport } from './audit.js';
 import { type ToolSearchEnv, type ToolSearchSource } from './deferral.js';
-import { type LoadedConfig } from './config.js';
+import { type RemoteProbe } from './remote.js';
+import { type ConfiguredServer, type LoadedConfig } from './config.js';
 /** Where the published `tools-delta/v1` run lives when `--claude` doesn't override it. */
 export declare const DEFAULT_DIVERGENCE_URL = "https://raw.githubusercontent.com/athakur3/mcp-context-cost/main/results/divergence.json";
 /** Where the published `tool-shape/v1` baseline lives when `--suggest` doesn't override it. */
@@ -45,6 +46,12 @@ export interface AuditOptions {
      * those files off the machine being audited (`discoverSettings`).
      */
     settings?: ToolSearchSource[];
+    /**
+     * What each remote endpoint said to an unauthenticated `initialize`, keyed
+     * like `measureAll`'s map. `runAudit` probes them (`probeRemotes`); a test can
+     * state the answers instead of reaching a network.
+     */
+    remotes?: Map<string, RemoteProbe>;
     onProgress?: (name: string, done: number, total: number) => void;
 }
 /** Fetch and parse the published capture index. Never throws: a failure is a report problem, not a crash. */
@@ -72,6 +79,29 @@ export declare function discover(opts?: AuditOptions): LoadedConfig[];
  * launched this audit answers for the wrong machine.
  */
 export declare function discoverSettings(opts?: AuditOptions): ToolSearchSource[];
-/** Measure every distinct stdio server across the given configs, once each. */
+/**
+ * Ask every distinct remote endpoint what it says to an unauthenticated
+ * `initialize`, once each. This comes before any launch — remote.ts says why an
+ * endpoint is asked before the bridge is pointed at it.
+ */
+export declare function probeRemotes(configs: LoadedConfig[], opts?: AuditOptions): Promise<Map<string, RemoteProbe>>;
+/**
+ * The bridge launch for an endpoint that answered without a credential.
+ *
+ * `argv` is exact, for the host path; `command` is the same launch as one
+ * shell line, for the docker path, which runs it through `sh -lc` (docker.ts).
+ * Both carry the entry's header values, as a stdio launch carries env values.
+ * `display` carries the names only, and is the form a report may print.
+ */
+export declare function bridgeLaunch(s: ConfiguredServer): {
+    argv: string[];
+    command: string;
+    display: string;
+};
+/**
+ * Measure every distinct server across the given configs, once each: each
+ * stdio server by its launch, and each remote endpoint the probe found open
+ * through the bridge. A walled or unreachable endpoint is not launched at all.
+ */
 export declare function measureAll(configs: LoadedConfig[], opts?: AuditOptions): Promise<Map<string, Measurement>>;
 export declare function runAudit(opts?: AuditOptions): Promise<AuditReport>;

package/dist/audit/run.js

@@ -11,6 +11,7 @@ import { parseToolShapeBaseline } from '../core/tool-shape.js';
 import { parseCaptureIndex } from '../core/capture-index.js';
 import { buildReport, serverKey } from './audit.js';
 import { toolSearchEnv } from './deferral.js';
+import { DEFAULT_PROBE_TIMEOUT_MS, probeRemote } from './remote.js';
 import { configCandidates, loadConfigs, loadSettingsSources, settingsCandidates, } from './config.js';
 /** Where the published `tools-delta/v1` run lives when `--claude` doesn't override it. */
 export const DEFAULT_DIVERGENCE_URL = 'https://raw.githubusercontent.com/athakur3/mcp-context-cost/main/results/divergence.json';
@@ -78,12 +79,63 @@ export function discoverSettings(opts = {}) {
     const home = opts.home ?? homedir();
     return loadSettingsSources(settingsCandidates({ home, cwd, platform: process.platform, programData: process.env.ProgramData }));
 }
-/** Measure every distinct stdio server across the given configs, once each. */
+/**
+ * Ask every distinct remote endpoint what it says to an unauthenticated
+ * `initialize`, once each. This comes before any launch — remote.ts says why an
+ * endpoint is asked before the bridge is pointed at it.
+ */
+export async function probeRemotes(configs, opts = {}) {
+    const unique = new Map();
+    for (const cfg of configs) {
+        for (const s of cfg.servers) {
+            if (s.transport !== 'remote' || !s.url)
+                continue;
+            if (!unique.has(serverKey(s)))
+                unique.set(serverKey(s), s);
+        }
+    }
+    const out = new Map();
+    // One HTTP exchange each; the launch timeout is the wrong bound for it.
+    const timeoutMs = Math.min(opts.timeoutMs ?? DEFAULT_PROBE_TIMEOUT_MS, DEFAULT_PROBE_TIMEOUT_MS);
+    await Promise.all([...unique].map(async ([key, s]) => {
+        out.set(key, await probeRemote(s.url, { headers: s.headers, timeoutMs }));
+    }));
+    return out;
+}
+/**
+ * The bridge launch for an endpoint that answered without a credential.
+ *
+ * `argv` is exact, for the host path; `command` is the same launch as one
+ * shell line, for the docker path, which runs it through `sh -lc` (docker.ts).
+ * Both carry the entry's header values, as a stdio launch carries env values.
+ * `display` carries the names only, and is the form a report may print.
+ */
+export function bridgeLaunch(s) {
+    const url = s.url ?? '';
+    const argv = ['npx', '-y', 'mcp-remote', url];
+    const display = [...argv];
+    // mcp-remote refuses a plain-http endpoint unless told it is on purpose.
+    if (/^http:/i.test(url)) {
+        argv.push('--allow-http');
+        display.push('--allow-http');
+    }
+    for (const [k, v] of Object.entries(s.headers ?? {})) {
+        argv.push('--header', `${k}: ${v}`);
+        display.push('--header', k);
+    }
+    const shellQuote = (a) => (/^[A-Za-z0-9_@%+=:,./-]+$/.test(a) ? a : `'${a.replace(/'/g, `'\\''`)}'`);
+    return { argv, command: argv.map(shellQuote).join(' '), display: display.join(' ') };
+}
+/**
+ * Measure every distinct server across the given configs, once each: each
+ * stdio server by its launch, and each remote endpoint the probe found open
+ * through the bridge. A walled or unreachable endpoint is not launched at all.
+ */
 export async function measureAll(configs, opts = {}) {
     const unique = new Map();
     for (const cfg of configs) {
         for (const s of cfg.servers) {
-            if (s.transport !== 'stdio')
+            if (s.transport === 'remote' && opts.remotes?.get(serverKey(s))?.kind !== 'open')
                 continue;
             // Two clients pointing at the same argv are one measurement, not two.
             if (!unique.has(serverKey(s)))
@@ -97,8 +149,9 @@ export async function measureAll(configs, opts = {}) {
     const worker = async () => {
         for (let next = queue.shift(); next; next = queue.shift()) {
             const [key, s] = next;
-            const m = await measureServer(s.name, s.command ?? '', {
-                argv: s.argv,
+            const launch = s.transport === 'remote' ? bridgeLaunch(s) : null;
+            const m = await measureServer(s.name, launch ? launch.command : (s.command ?? ''), {
+                argv: launch ? launch.argv : s.argv,
                 env: s.env,
                 timeoutMs: opts.timeoutMs ?? 60_000,
                 docker: opts.docker,
@@ -113,7 +166,8 @@ export async function measureAll(configs, opts = {}) {
 }
 export async function runAudit(opts = {}) {
     const configs = discover(opts);
-    const measured = await measureAll(configs, opts);
+    const remotes = opts.remotes ?? (await probeRemotes(configs, opts));
+    const measured = await measureAll(configs, { ...opts, remotes });
     let divergence = null;
     let divergenceProblem;
     if (opts.claude) {
@@ -143,6 +197,7 @@ export async function runAudit(opts = {}) {
         captureIndex,
         env: opts.env ?? toolSearchEnv(process.env),
         settings: opts.settings ?? discoverSettings(opts),
+        remotes,
     });
     if (divergenceProblem)
         report.problems.push(divergenceProblem);

package/dist/cli.js

@@ -342,7 +342,8 @@ if (cmd === 'audit') {
             console.error(`no MCP config found at the path(s) given: ${all('config').join(', ')}. ` +
                 `Nothing else was searched, because --config was set.`);
         else
-            console.error(`no MCP config found. Looked in the standard Claude Desktop / Claude Code / Cursor / VS Code / Windsurf locations.${where}\n` +
+            console.error(`no MCP config found. Looked in the standard Claude Desktop / Claude Code / Cursor / VS Code / Windsurf / ` +
+                `Codex CLI / Gemini CLI / Zed / Kiro / Goose locations.${where}\n` +
                 `Point at one explicitly: mcp-context-cost audit --config <path/to/mcp.json>`);
         process.exit(1);
     }

package/dist/sweep/cross-check.js

@@ -28,7 +28,7 @@ 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 { isSelfContainerised, measureServer } from './run.js';
 import { DockerHarnessFault, defaultImageFor, dockerize } from './docker.js';
 import { splitCommand } from './client.js';
 import { selectShard, shardIndexForDate } from './shard.js';
@@ -305,7 +305,7 @@ if (isMain) {
                 console.log(`  ${e.name}: our measurement ${m.status} — recorded, nothing to compare`);
                 continue;
             }
-            const selfDocker = e.command.trimStart().startsWith('docker ');
+            const selfDocker = isSelfContainerised(e.command);
             const out = await runCli(docker && selfDocker ? await hostBin() : binPath, e, {
                 docker: docker && !selfDocker,
                 timeoutMs,

package/dist/sweep/pr-check.d.ts

@@ -0,0 +1,62 @@
+import { type SchemaProblem } from './servers-schema.js';
+import type { ServerEntry } from './report.js';
+import type { Measurement } from '../core/types.js';
+/**
+ * The fields that change what a sweep launches — the option object
+ * sweep-all.ts hands to `measureServer`, plus the timeout it is given. A change
+ * to `metric`, `metricSource`, `category`, `repo`, `package` or `deprecated`
+ * changes a row's text, not its process, and is not re-measured here.
+ */
+export declare const LAUNCH_FIELDS: readonly ["command", "dockerImage", "aptPackages", "needsGit", "env", "envValues", "timeoutSeconds", "notApplicable"];
+/**
+ * How many entries one pull request may launch, at the default budget. The
+ * worst case per entry is a timeout retried on `TIMEOUT_RETRY_FACTOR` times
+ * its budget (run.ts:351-352), so at the workflow's `--default-timeout 240`
+ * one entry can hold the runner for 240 × (1 + 2) = 720s, and this many of
+ * them measured one at a time is what pr-check.yml's `timeout-minutes` is
+ * sized to (`launchBudgetSeconds`).
+ *
+ * The count alone does not hold that bound. An entry's own `timeoutSeconds`
+ * replaces the default (the rotation's rule, kept here), and the schema bounds
+ * it only below — "a whole number of seconds greater than zero"
+ * (servers-schema.ts:166-169) — so one added entry with `timeoutSeconds: 4000`
+ * would cost 12000s under the same count and be killed by the job limit with
+ * no line printed for it. The bound is held because the script also refuses,
+ * before any launch, a selection whose `worstCaseSeconds` exceeds the budget
+ * the count was sized to. A PR that trips either is asked to split or shorten,
+ * rather than have the runner cut it off with the last entries unmeasured and
+ * no line saying so.
+ */
+export declare const DEFAULT_MAX_ENTRIES = 4;
+/** The launched entries among a selection: remote endpoints and self-containerised commands are listed, not spawned. */
+export declare function launchedEntries(entries: ServerEntry[]): ServerEntry[];
+/**
+ * The most seconds a selection can hold the runner: each launched entry's own
+ * budget (`timeoutSeconds`, or the default) once, then `TIMEOUT_RETRY_FACTOR`
+ * times more on the retry. Listed entries cost nothing and are not counted.
+ */
+export declare function worstCaseSeconds(entries: ServerEntry[], defaultTimeout: number): number;
+/** What the job's `timeout-minutes` was sized to: `maxEntries` launches, each at the default budget and its retry. */
+export declare function launchBudgetSeconds(maxEntries: number, defaultTimeout: number): number;
+export interface ServersDiff {
+    /** Head fails the shape check; nothing is diffed from a malformed document. */
+    problems: SchemaProblem[];
+    /** Names present in head and absent from base. */
+    added: ServerEntry[];
+    /** Names in both whose `LAUNCH_FIELDS` projection differs. */
+    relaunched: ServerEntry[];
+}
+/** The part of an entry that decides what gets spawned, as one comparable string. */
+export declare function launchSignature(entry: ServerEntry): string;
+/**
+ * What a pull request adds or relaunches, given the parsed base and head
+ * documents. Head is shape-checked first and returns only problems when it has
+ * any. Base is the committed branch, which `npm test` already holds valid; an
+ * unreadable base is treated as empty, which makes every head entry "added"
+ * and lets the entry cap refuse the run rather than measuring the whole file.
+ */
+export declare function entriesToMeasure(base: unknown, head: unknown): ServersDiff;
+/** The line printed for a launched entry — sweep-all's summary form, with the evidence behind a failure. */
+export declare function summarise(name: string, m: Measurement, secs: number): string;
+/** Whether an outcome fails the check. */
+export declare function failsCheck(status: Measurement['status']): boolean;