mcp-context-cost 0.12.0 → 0.13.0

package/README.md

@@ -2,6 +2,27 @@
 
 [![npm](https://img.shields.io/npm/v/mcp-context-cost)](https://www.npmjs.com/package/mcp-context-cost)
 [![CI](https://github.com/athakur3/mcp-context-cost/actions/workflows/ci.yml/badge.svg)](https://github.com/athakur3/mcp-context-cost/actions/workflows/ci.yml)
+[![GitHub Marketplace](https://img.shields.io/badge/GitHub%20Marketplace-MCP%20context%20cost-blue?logo=github)](https://github.com/marketplace/actions/mcp-context-cost)
+
+Two entry points: `audit`, for the config you run (below), and a GitHub Action, for the
+server you publish — five lines in a workflow that fail a pull request adding more context
+cost than you meant to ship:
+
+```yaml
+- uses: athakur3/mcp-context-cost@v1
+  with:
+    name: my-server
+    command: node dist/index.js
+    baseline: .context-cost/baseline.json
+    max-increase: 500
+```
+
+Inputs: `name`, `command` or `remote`, `baseline`, `max-increase`, `budget`, `timeout`,
+`version`. Outputs: `tokens`, `tools`, `status`, `measurement`, `badge` — written whether the
+gate passed or not, so a later step can comment the number on the PR or publish the badge.
+[Full workflow](examples/server-author-ci.yml) ·
+[how the gate decides](#defend-the-number-dont-just-display-it) ·
+[what the number is](docs/METHODOLOGY.md).
 
 **What do the MCP servers in your config cost you before you type anything — and what did
 that last config change add to every session you will ever run?**
@@ -105,7 +126,7 @@ costs **more** than loading the definitions would.
 
 Three things the report will not do: it will not convert between units silently (in
 threshold mode the stack is compared as a range, because the audit counts wire bytes and the
-threshold is counted in what the client sends to the API — measured at 0.20×–1.92× across 20
+threshold is counted in what the client sends to the API — measured at 0.20×–1.92× across 23
 servers); it will not claim a posture the machine did not state readably, which is four
 refusals and not one — when two places set the same variable to different values, when a
 settings file exists and cannot be read, when the place that would decide sets the variable
@@ -183,8 +204,8 @@ INCREASE FAIL:
 Add `--claude` to annotate each server with its Anthropic-request cost from the published
 [Claude divergence](docs/METHODOLOGY.md#claude-divergence) run — an exact number when the
 published capture hash matches what you have installed, `—` (silence, not a stale guess)
-when it doesn't. The run holds 20 rows — the top 20 measured servers by tokens when it ran —
-and [results/leaderboard.md](results/leaderboard.md) prints a claude number for the 12 that
+when it doesn't. The run holds 23 rows — the measured servers it covered when it last ran —
+and [results/leaderboard.md](results/leaderboard.md) prints a claude number for the 15 that
 still match today and silence for the rest. Most installs will show a mix:
 
 ```
@@ -235,7 +256,7 @@ Flags: `--json` (full report on stdout, progress on stderr), `--budget N`,
 
 The number `audit` gives you is the same measurement, run across a curated set of public
 servers — which is how you can tell it is a measurement and not this tool's opinion. It also
-shows what you are choosing between: across the 83 servers measured, cost spans **1,700×**,
+shows what you are choosing between: across the 86 servers measured, cost spans **1,700×**,
 from `postgres` at 32 tokens to `github` at 54,622. The table below is a
 sample of that range; the full range is in
 [results/leaderboard.md](results/leaderboard.md).
@@ -250,7 +271,7 @@ sample of that range; the full range is in
 | filesystem (reference) | 2,823 | 14 |
 | markitdown | 64 | 1 |
 
-*(83 of 106 popular servers measured, each row dated by its own most recent sweep — full table in
+*(86 of 106 popular servers measured, each row dated by its own most recent sweep — full table in
 [results/leaderboard.md](results/leaderboard.md); every failure is listed with its reason.
 Each measured server also has a [detail page](https://athakur3.github.io/mcp-context-cost/servers/)
 showing which tools its tokens are in.)*
@@ -328,7 +349,7 @@ number is *not*, config policy, failure taxonomy, frozen color bands, known dive
 | `spec/fixtures/` | golden vectors shared by the TypeScript and bash implementations |
 | `tools/` | the one script that calls a network API (Claude divergence); kept out of the package so the library stays offline |
 | `upstream/` | `badge.sh` + composite-action patch + bash tests — the self-serve badge recipe, carried here |
-| `servers.yaml` | 82 curated candidates with live install metrics and provenance |
+| `servers.yaml` | 106 curated candidates with live install metrics and provenance |
 | `results/` · `badges/` | measurements, leaderboard, history series, shields endpoint JSONs |
 | `docs/` | methodology, dashboard, and a generated page per measured server |
 
@@ -350,11 +371,11 @@ Then in your README:
 
 A badge says what your server costs today; it does nothing about the release
 that adds 1,200 tokens to every user's context next month. Across the servers
-measured here, that release is the norm rather than the exception — the
-[movement report](results/regressions.md) has nine servers ratcheting upward
-against one that got cheaper, and none of those maintainers had a check that
-would have said so first. `measure` takes the same gate flags `audit` does, so
-your own CI can be that check:
+measured here most costs hold steady from sweep to sweep, but when a cost does
+move it usually moves up: the [movement report](results/regressions.md) has 11
+servers ratcheting upward against 6 that got cheaper, and none of those
+maintainers had a check that would have said so first. `measure` takes the same
+gate flags `audit` does, so your own CI can be that check:
 
 ```bash
 # on your default branch, once — commit the result

package/dist/audit/deferral.js

@@ -229,7 +229,20 @@ export function resolveToolSearchSources(sources) {
 export const PUBLISHED_WIRE_TO_CLIENT_RATIO = {
     low: 0.2,
     high: 1.92,
-    servers: 20,
+    // A snapshot of the run this package was cut against, which is what `source`
+    // below says it is — the installed package has no `results/` to read, so when
+    // a live run is supplied `wireToClientRatio` uses that instead and this is
+    // never consulted. It may therefore lag the run on trunk, and a test holds it
+    // to the two things that matter: the band must still be accurate to the
+    // precision it is published at, because a wrong band gives a wrong
+    // above/below verdict, and the count must never *exceed* the run, because
+    // that would be a claim about servers nobody measured.
+    //
+    // It read 20 from the day the run covered the top 20 until the run widened to
+    // every measured server on 2026-09-05, with nothing comparing the two. The
+    // band had not moved — the servers added sat inside it — which is exactly how
+    // a number like this goes wrong quietly.
+    servers: 23,
     source: 'the published claude-opus-5 divergence run',
 };
 /** Derive the band from a supplied divergence run, falling back to the published one. */

package/dist/core/regression.d.ts

@@ -42,6 +42,8 @@ export interface DatedMeasurement {
     tokens: number;
     toolCount: number;
     status: string;
+    /** What the server called itself at `initialize`, or `''` when not recorded. */
+    version?: string;
 }
 /** Method identifier, versioned independently of METHODOLOGY_VERSION. */
 export declare const REGRESSION_METHOD = "cost-regression/v1";
@@ -67,6 +69,14 @@ export interface ToolVectorEntry {
     canonicalSha256: string;
     totalTokens: number;
     tools: ToolVector[];
+    /**
+     * The version the server reported at `initialize`, absent when it reported
+     * none or when the entry was stored before this field existed. Entries are
+     * deduped by capture and never rewritten, so an existing one does not gain a
+     * version retroactively — which is correct: identical bytes are the same
+     * definitions, and what upstream called them that day is not on record.
+     */
+    version?: string;
 }
 export interface ToolVectorFile {
     method: string;
@@ -150,6 +160,17 @@ export interface CostChange {
     fromToolCount: number;
     toToolCount: number;
     deltaTools: number;
+    /**
+     * What the server called itself on each side, or `''` where the row does not
+     * say. Never inferred: a movement whose earlier row predates the version
+     * column names no release, because nothing on disk records which one it was.
+     *
+     * The two being *equal* is a reading in its own right, and a common one —
+     * the cost moved while the version did not, which means the change came from
+     * a dependency the server does not pin rather than from its own release.
+     */
+    fromVersion: string;
+    toVersion: string;
     mechanism: Mechanism;
     /** True when the movement clears both thresholds. */
     significant: boolean;
@@ -162,11 +183,44 @@ export interface CostChange {
     /** Per-tool breakdown, or null when the two captures are not both on record. */
     attribution: ToolAttribution | null;
 }
+/**
+ * A cost that has been measured more than once, under the same isolation, and
+ * has not moved.
+ *
+ * Published because it is a measured fact and not the absence of one. The
+ * report used to swallow it: `latestChange` returned null both for this and
+ * for "there is nothing to compare", and the page counted every null the same
+ * way — so a number four sweeps had confirmed read exactly like a number
+ * measured once.
+ */
+export interface UnchangedSeries {
+    server: string;
+    tokens: number;
+    toolCount: number;
+    /** The first date this cost was recorded — when it became this, not when it was last looked at. */
+    since: string;
+    /** The newest measurement on record. */
+    measuredThrough: string;
+    /** How many comparable measurements carry this same cost, `since` included. */
+    sweeps: number;
+}
+/**
+ * What one server's series supports. Three readings, and they are three
+ * different claims: the cost moved, the cost was confirmed and held, or there
+ * is not yet a second comparable measurement to say either.
+ */
+export type SeriesReading = {
+    kind: 'changed';
+    change: CostChange;
+} | {
+    kind: 'unchanged';
+    held: UnchangedSeries;
+} | {
+    kind: 'incomparable';
+};
 export declare function isSignificant(deltaTokens: number, deltaPct: number): boolean;
 /**
- * The most recent comparable *movement* for one server, or null when there
- * isn't one: fewer than two comparable measurements, or a series that has never
- * changed.
+ * What one server's history supports, as one of three readings.
  *
  * Deliberately not "the newest pair". A server that grew 82% one week and held
  * that cost since has a newest pair of zero, and reporting only that would hide
@@ -176,10 +230,23 @@ export declare function isSignificant(deltaTokens: number, deltaPct: number): bo
  * actually happened — `2026-08-19 → 2026-08-26`, not a span up to today.
  * `measuredThrough` then carries how long the new cost has held.
  *
+ * Where that walk ends decides the reading. Reaching the start of the series
+ * means every comparable measurement agrees, which is `unchanged` — a fact
+ * about the server. Having fewer than two comparable rows to walk means there
+ * is nothing to compare, which is `incomparable` — an absence. The two used
+ * to share one `null` return, and the report counted them together.
+ *
  * `rows` is that server's history, already narrowed to the run a trend may be
  * drawn across (`plottableSeries`), so the isolation rule is applied once, in
  * the place that owns it.
  */
+export declare function readSeries(server: string, rows: DatedMeasurement[], vectors?: ToolVectorFile | null): SeriesReading;
+/**
+ * The most recent comparable movement, or null when there was none. Kept as
+ * the narrow question `readSeries` answers in full, for the callers that only
+ * ever wanted a movement — but a caller that publishes a count must ask
+ * `readSeries`, because null here is two different facts.
+ */
 export declare function latestChange(server: string, rows: DatedMeasurement[], vectors?: ToolVectorFile | null): CostChange | null;
 export interface RegressionSummary {
     changes: CostChange[];
@@ -188,7 +255,22 @@ export interface RegressionSummary {
     significant: number;
     /** Net tokens the measured set gained (or lost) across every listed movement. */
     netTokens: number;
-    /** Servers with a measurement but no second comparable one to diff against. */
+    /**
+     * Servers measured more than once under the same isolation whose cost has
+     * not moved. Counted apart from `withoutComparison`, which they were folded
+     * into while both readings shared one `null`.
+     */
+    unchanged: UnchangedSeries[];
+    /**
+     * Servers with no second comparable measurement to diff against — a first
+     * measurement, or every earlier run taken under different isolation. Not
+     * "has not moved": that is `unchanged`.
+     */
     withoutComparison: number;
 }
-export declare function summarize(changes: CostChange[], withoutComparison: number): RegressionSummary;
+/**
+ * `unchanged` is required rather than defaulted: every reading a caller
+ * classifies belongs to exactly one of the three, and a default would let a
+ * caller that forgot them publish a total that quietly does not sum.
+ */
+export declare function summarize(changes: CostChange[], withoutComparison: number, unchanged: UnchangedSeries[]): RegressionSummary;

package/dist/core/regression.js

@@ -38,6 +38,7 @@ export function parseToolVectorFile(text) {
             date: e.date,
             canonicalSha256: e.canonicalSha256,
             totalTokens: e.totalTokens,
+            ...(typeof e.version === 'string' && e.version ? { version: e.version } : {}),
             tools: e.tools
                 .filter((t) => !!t && typeof t.name === 'string' && typeof t.tokens === 'number')
                 .map((t) => ({ name: t.name, tokens: t.tokens })),
@@ -62,6 +63,7 @@ export function vectorEntryOf(m) {
         date,
         canonicalSha256: m.canonicalSha256,
         totalTokens: m.totalTokens,
+        ...(m.serverVersion ? { version: m.serverVersion } : {}),
         tools: m.tools.map((t) => ({ name: t.name, tokens: t.tokens })),
     };
 }
@@ -139,9 +141,7 @@ export function isSignificant(deltaTokens, deltaPct) {
     return Math.abs(deltaPct) >= SIGNIFICANT_PCT && Math.abs(deltaTokens) >= SIGNIFICANT_TOKENS;
 }
 /**
- * The most recent comparable *movement* for one server, or null when there
- * isn't one: fewer than two comparable measurements, or a series that has never
- * changed.
+ * What one server's history supports, as one of three readings.
  *
  * Deliberately not "the newest pair". A server that grew 82% one week and held
  * that cost since has a newest pair of zero, and reporting only that would hide
@@ -151,14 +151,20 @@ export function isSignificant(deltaTokens, deltaPct) {
  * actually happened — `2026-08-19 → 2026-08-26`, not a span up to today.
  * `measuredThrough` then carries how long the new cost has held.
  *
+ * Where that walk ends decides the reading. Reaching the start of the series
+ * means every comparable measurement agrees, which is `unchanged` — a fact
+ * about the server. Having fewer than two comparable rows to walk means there
+ * is nothing to compare, which is `incomparable` — an absence. The two used
+ * to share one `null` return, and the report counted them together.
+ *
  * `rows` is that server's history, already narrowed to the run a trend may be
  * drawn across (`plottableSeries`), so the isolation rule is applied once, in
  * the place that owns it.
  */
-export function latestChange(server, rows, vectors) {
+export function readSeries(server, rows, vectors) {
     const usable = rows.filter((r) => r.status === 'measured' || r.status === 'dynamic');
     if (usable.length < 2)
-        return null;
+        return { kind: 'incomparable' };
     const newest = usable[usable.length - 1];
     // Walk back over measurements identical to the newest: the first of that run
     // is when the current cost arrived.
@@ -169,14 +175,26 @@ export function latestChange(server, rows, vectors) {
             break;
         toIdx--;
     }
+    /** The trailing run reaches back this far, and every row in it agrees. */
+    const held = () => ({
+        kind: 'unchanged',
+        held: {
+            server,
+            tokens: newest.tokens,
+            toolCount: newest.toolCount,
+            since: usable[toIdx].date,
+            measuredThrough: newest.date,
+            sweeps: usable.length - toIdx,
+        },
+    });
     if (toIdx === 0)
-        return null; // the series has never changed
+        return held(); // every comparable measurement agrees
     const to = usable[toIdx];
     const from = usable[toIdx - 1];
     const deltaTokens = to.tokens - from.tokens;
     const deltaTools = to.toolCount - from.toolCount;
     if (deltaTokens === 0 && deltaTools === 0)
-        return null;
+        return held();
     const deltaPct = from.tokens > 0 ? (deltaTokens / from.tokens) * 100 : 0;
     // Attribution needs both sides on record. Matched by *cost as of that date*,
     // not by date equality: vectors are deduped by capture and keep the first
@@ -209,23 +227,43 @@ export function latestChange(server, rows, vectors) {
         attribution = attribute(fromVec, toVec, deltaTokens);
     }
     return {
-        server,
-        fromDate: from.date,
-        toDate: to.date,
-        fromTokens: from.tokens,
-        toTokens: to.tokens,
-        deltaTokens,
-        deltaPct,
-        fromToolCount: from.toolCount,
-        toToolCount: to.toolCount,
-        deltaTools,
-        mechanism: mechanismOf(deltaTokens, deltaTools),
-        significant: isSignificant(deltaTokens, deltaPct),
-        measuredThrough: newest.date,
-        attribution,
+        kind: 'changed',
+        change: {
+            server,
+            fromDate: from.date,
+            toDate: to.date,
+            fromTokens: from.tokens,
+            toTokens: to.tokens,
+            deltaTokens,
+            deltaPct,
+            fromToolCount: from.toolCount,
+            toToolCount: to.toolCount,
+            deltaTools,
+            fromVersion: from.version ?? '',
+            toVersion: to.version ?? '',
+            mechanism: mechanismOf(deltaTokens, deltaTools),
+            significant: isSignificant(deltaTokens, deltaPct),
+            measuredThrough: newest.date,
+            attribution,
+        },
     };
 }
-export function summarize(changes, withoutComparison) {
+/**
+ * The most recent comparable movement, or null when there was none. Kept as
+ * the narrow question `readSeries` answers in full, for the callers that only
+ * ever wanted a movement — but a caller that publishes a count must ask
+ * `readSeries`, because null here is two different facts.
+ */
+export function latestChange(server, rows, vectors) {
+    const reading = readSeries(server, rows, vectors);
+    return reading.kind === 'changed' ? reading.change : null;
+}
+/**
+ * `unchanged` is required rather than defaulted: every reading a caller
+ * classifies belongs to exactly one of the three, and a default would let a
+ * caller that forgot them publish a total that quietly does not sum.
+ */
+export function summarize(changes, withoutComparison, unchanged) {
     const sorted = [...changes].sort((a, b) => Math.abs(b.deltaPct) - Math.abs(a.deltaPct));
     return {
         changes: sorted,
@@ -233,6 +271,9 @@ export function summarize(changes, withoutComparison) {
         shrank: sorted.filter((c) => c.deltaTokens < 0).length,
         significant: sorted.filter((c) => c.significant).length,
         netTokens: sorted.reduce((a, c) => a + c.deltaTokens, 0),
+        // Longest-held first: the sentence this section exists to publish is "this
+        // number has been the same since <date>", so the oldest `since` leads.
+        unchanged: [...unchanged].sort((a, b) => a.since.localeCompare(b.since) || b.tokens - a.tokens),
         withoutComparison,
     };
 }

package/dist/core/types.d.ts

@@ -56,10 +56,10 @@ export interface Measurement {
         /**
          * The architecture the measurement ran on, as `<platform>/<arch>` (e.g.
          * `linux/amd64`). Part of the isolation because some packages ship builds
-         * for only some of them: `local-mcp` was published as a startup failure
-         * for weeks on the strength of a run whose real finding was "this laptop
-         * is arm64 and the package has no arm64 runtime" — a fact about the
-         * machine that the record gave no way to see.
+         * for only some of them: `local-mcp` was published as a startup failure on
+         * the strength of a run whose real finding was "this laptop is arm64 and
+         * the package has no arm64 runtime" — a fact about the machine that the
+         * record gave no way to see.
          *
          * Absent on records written before this was captured, which is why it is
          * optional; absence means unknown, never "the same as yours".

package/dist/sweep/cross-check.js

@@ -162,6 +162,7 @@ export function runCli(binPath, entry, opts) {
             dummyEnv: entry.env ?? [],
             dummyEnvValues: entry.envValues,
             needsGit: entry.needsGit,
+            aptPackages: entry.aptPackages,
             containerName,
             binds: [`${binPath}:/opt/mcp-tokens:ro`],
         });
@@ -287,6 +288,8 @@ if (isMain) {
                     dummyEnv: e.env ?? [],
                     dummyEnvValues: e.envValues,
                     needsGit: e.needsGit,
+                    aptPackages: e.aptPackages,
+                    notApplicable: e.notApplicable,
                     persist: false, // the measurements on disk are not this run's to rewrite
                 });
             }

package/dist/sweep/dashboard.js

@@ -66,7 +66,22 @@ export function generateDashboard(root = process.cwd()) {
     const median = totals.length ? totals.slice().sort((a, b) => a - b)[Math.floor(totals.length / 2)] : 0;
     const max = totals.length ? Math.max(...totals) : 1;
     const fmt = (n) => n.toLocaleString('en-US');
-    const now = new Date().toISOString().slice(0, 16).replace('T', ' ') + ' UTC';
+    /**
+     * The stamp is the newest measurement on the page, not the moment the page
+     * was written.
+     *
+     * A wall-clock stamp made `docs/dashboard.html` differ on every regeneration,
+     * so the scheduled jobs' "no change to publish" guard could never fire: one
+     * file that always diffs is enough to publish a commit that says nothing
+     * happened. Dated to the data instead, the page changes when the data does —
+     * and the line now answers the question a reader actually has, which is how
+     * fresh these numbers are, not when the HTML was rendered.
+     */
+    const dates = rows
+        .map((r) => String(r.m?.measuredAt ?? '').slice(0, 10))
+        .filter((d) => /^\d{4}-\d{2}-\d{2}$/.test(d))
+        .sort();
+    const newestMeasurement = dates[dates.length - 1] ?? null;
     const barRows = measured
         .map((r, i) => {
         const m = r.m;
@@ -225,7 +240,7 @@ export function generateDashboard(root = process.cwd()) {
 </style>
 <div class="wrap">
   <header>
-    <p class="eyebrow">methodology v1.0 · o200k_base · generated ${now}</p>
+    <p class="eyebrow">methodology v1.0 · o200k_base · newest measurement ${newestMeasurement ?? 'not yet taken'}</p>
     <h1>mcp-context-cost</h1>
     <p class="sub">What popular MCP servers cost in context tokens before the agent does any work — measured from raw <code>tools/list</code> captures, every number re-derivable from its published measurement file.</p>
   </header>

package/dist/sweep/docker.d.ts

@@ -30,6 +30,23 @@ export interface DockerOptions {
      * git already on PATH would actually run.
      */
     needsGit?: boolean;
+    /**
+     * Debian packages to install before launch, for a server whose runtime needs
+     * a native library the slim base image does not carry.
+     *
+     * The same argument as `needsGit`, and the same shape: these are libraries a
+     * user's own machine already has, so installing them moves the container
+     * *towards* the conditions a plain `npx -y` run would find rather than away
+     * from them. `azure` is the case — a .NET server that fails on
+     * `node:22-slim` with "Couldn't find a valid ICU package", and again on
+     * libssl once ICU is satisfied. With both present it measures.
+     *
+     * Distinct from an env var that changes the server's own behaviour (see
+     * `elasticsearch` and `OTEL_SDK_DISABLED`), which is a different decision.
+     * The isolation record names what was installed either way, so a reader can
+     * see that the container was not the plain one.
+     */
+    aptPackages?: string[];
     /**
      * Extra `-v` bind mounts, verbatim (`host:container:ro`). Used to hand a
      * host-verified binary into the container (the cross-check CLI); mounts here
@@ -82,6 +99,7 @@ export interface EnsureImageOptions {
     /** Run one docker invocation — injectable so tests never need a daemon. */
     run?: (args: string[]) => Promise<{
         code: number | null;
+        stdout?: string;
         stderr: string;
     }>;
     /** Waits between pull attempts; attempts = delays + 1. */
@@ -101,6 +119,34 @@ export interface EnsureImageOptions {
  * re-attempted by every remaining server in the sweep.
  */
 export declare function ensureImage(image: string, opts?: EnsureImageOptions): Promise<void>;
+/** Parse `uname -sm` output into `<platform>/<arch>`, or null if it is not that. */
+export declare function platformFromUname(output: string): string | null;
+/**
+ * The platform a container for this image actually runs as, asked of a
+ * container rather than inferred from the machine that starts one.
+ *
+ * `isolation.arch` exists to tell a broken server apart from one that ships no
+ * build for the architecture it was tried on, and it was being derived instead
+ * of observed: the platform half was assumed to be `linux` and the
+ * architecture half was the *host's* `process.arch`. Nothing here passes
+ * `--platform`, but `docker run` honours `DOCKER_DEFAULT_PLATFORM` and an
+ * image with no manifest for the host is emulated — so an amd64 container on
+ * an Apple Silicon laptop recorded `linux/arm64`. A field that can be wrong
+ * about the one thing it exists to establish is worse than no field.
+ *
+ * The obvious cheap answer does not work, which is why this starts a
+ * container. `docker image inspect` reports the variant the local store
+ * prefers, and on this machine 2026-09-05 it answered `linux/arm64` for a tag
+ * whose container, under `DOCKER_DEFAULT_PLATFORM=linux/amd64`, came up as
+ * `x86_64` — the same wrong answer as the host inference, reached a different
+ * way. Only the container knows.
+ *
+ * One `docker run` per image, memoized for the life of the process, so a sweep
+ * pays it about twice: once for the node base and once for the python one.
+ * Returns null when docker cannot say, leaving `arch` absent — which the
+ * record already documents as "unknown, never the same as yours".
+ */
+export declare function containerPlatform(image: string, opts?: EnsureImageOptions): Promise<string | null>;
 export interface IsolationRecord {
     docker: boolean;
     image?: string;

package/dist/sweep/docker.js

@@ -33,12 +33,15 @@ export function isDockerRunFailure(message) {
 }
 function runDocker(args) {
     return import('node:child_process').then(({ spawn }) => new Promise((resolve) => {
-        const child = spawn('docker', args, { stdio: ['ignore', 'ignore', 'pipe'] });
+        const child = spawn('docker', args, { stdio: ['ignore', 'pipe', 'pipe'] });
+        let stdout = '';
         let stderr = '';
+        child.stdout.setEncoding('utf8');
+        child.stdout.on('data', (chunk) => (stdout = (stdout + chunk).slice(-4000)));
         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 }));
+        child.on('error', (err) => resolve({ code: null, stdout, stderr: String(err.message) }));
+        child.on('exit', (code) => resolve({ code, stdout, stderr }));
     }));
 }
 async function ensureImageOnce(image, opts) {
@@ -92,6 +95,71 @@ export function ensureImage(image, opts = {}) {
     }
     return p;
 }
+/**
+ * `uname` names, in Docker's vocabulary. Explicit rather than derived: an
+ * unrecognised machine name returns nothing, because a mapping guessed from a
+ * pattern would be the same kind of inference this function exists to remove.
+ */
+const UNAME_ARCH = {
+    x86_64: 'amd64',
+    amd64: 'amd64',
+    aarch64: 'arm64',
+    arm64: 'arm64',
+    armv7l: 'arm/v7',
+    armv6l: 'arm/v6',
+    i386: '386',
+    i686: '386',
+    ppc64le: 'ppc64le',
+    s390x: 's390x',
+    riscv64: 'riscv64',
+};
+/** Parse `uname -sm` output into `<platform>/<arch>`, or null if it is not that. */
+export function platformFromUname(output) {
+    const [kernel, machine] = output.trim().split(/\s+/);
+    const arch = UNAME_ARCH[(machine ?? '').toLowerCase()];
+    if (!kernel || !arch)
+        return null;
+    return `${kernel.toLowerCase()}/${arch}`;
+}
+/**
+ * The platform a container for this image actually runs as, asked of a
+ * container rather than inferred from the machine that starts one.
+ *
+ * `isolation.arch` exists to tell a broken server apart from one that ships no
+ * build for the architecture it was tried on, and it was being derived instead
+ * of observed: the platform half was assumed to be `linux` and the
+ * architecture half was the *host's* `process.arch`. Nothing here passes
+ * `--platform`, but `docker run` honours `DOCKER_DEFAULT_PLATFORM` and an
+ * image with no manifest for the host is emulated — so an amd64 container on
+ * an Apple Silicon laptop recorded `linux/arm64`. A field that can be wrong
+ * about the one thing it exists to establish is worse than no field.
+ *
+ * The obvious cheap answer does not work, which is why this starts a
+ * container. `docker image inspect` reports the variant the local store
+ * prefers, and on this machine 2026-09-05 it answered `linux/arm64` for a tag
+ * whose container, under `DOCKER_DEFAULT_PLATFORM=linux/amd64`, came up as
+ * `x86_64` — the same wrong answer as the host inference, reached a different
+ * way. Only the container knows.
+ *
+ * One `docker run` per image, memoized for the life of the process, so a sweep
+ * pays it about twice: once for the node base and once for the python one.
+ * Returns null when docker cannot say, leaving `arch` absent — which the
+ * record already documents as "unknown, never the same as yours".
+ */
+export async function containerPlatform(image, opts = {}) {
+    const run = opts.run ?? runDocker;
+    if (!opts.run) {
+        const cached = platforms.get(image);
+        if (cached !== undefined)
+            return cached;
+    }
+    const r = await run(['run', '--rm', '--pull=missing', image, 'uname', '-sm']);
+    const platform = r.code === 0 ? platformFromUname(String(r.stdout ?? '')) : null;
+    if (!opts.run)
+        platforms.set(image, platform);
+    return platform;
+}
+const platforms = new Map();
 /**
  * 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).
@@ -135,7 +203,14 @@ export function dockerize(commandLine, opts = {}) {
     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);
+    // Package names are validated by the schema check before they reach here, and
+    // they are joined into a shell word list — so the schema's character class is
+    // what keeps this from being an injection point.
+    const packages = opts.aptPackages ?? [];
+    const aptPrefix = packages.length
+        ? `apt-get update -qq >/dev/null 2>&1 && apt-get install -y -qq --no-install-recommends ${packages.join(' ')} >/dev/null 2>&1; `
+        : '';
+    argv.push(image, 'sh', '-lc', gitPrefix + aptPrefix + commandLine);
     return {
         command: 'docker',
         argv,
@@ -145,6 +220,9 @@ export function dockerize(commandLine, opts = {}) {
             network: 'bridge',
             note: 'network enabled for package fetch; clean FS, no host credentials' +
                 (opts.needsGit ? ', git installed' : '') +
+                // Named rather than summarised: a record whose container carried extra
+                // libraries has to say which, or the number is not reproducible from it.
+                (packages.length ? `, installed ${packages.join(' ')}` : '') +
                 (opts.noSharedCache ? ', shared package cache bypassed' : ''),
         },
     };