mcp-context-cost 0.18.0 → 0.19.0

package/README.md

@@ -4,9 +4,9 @@
 [![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:
+Three entry points: `audit`, for the config you run (below); a GitHub Action, for the server
+you publish; and the measurement itself, as a library, for anything else. The Action is 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
@@ -24,6 +24,18 @@ gate passed or not, so a later step can comment the number on the PR or publish
 [how the gate decides](#defend-the-number-dont-just-display-it) ·
 [what the number is](docs/METHODOLOGY.md).
 
+As a library, if you want the measurement without either wrapper — the same canonical form,
+the same tokenizer, the same badge:
+
+```js
+import { measureTools, canonicalString, toBadge, METHODOLOGY_VERSION } from "mcp-context-cost";
+```
+
+It is the definition rather than the harness: measurement and canonical bytes, the color
+bands, the badge JSON, the Claude field-selection mapping, and the session-start load. It
+does not launch servers or read your config — that is what `audit` is for. The surface is
+pinned by a test, so a name is added or removed on purpose and says so in the changelog.
+
 **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?**
 
@@ -69,16 +81,15 @@ VS Code (`.vscode/mcp.json`), Windsurf, Codex CLI (`~/.codex/config.toml`), Gemi
 Goose (`~/.config/goose/config.yaml`) — or pass `--config <path>`. Servers are measured by
 the same path as the published leaderboard (dual `tools/list` capture, `o200k_base` over
 canonical JSON), so a server in both places gets the same number. Nothing is written to your
-project, and env var **values** are never read into the output — only their names.
+project, and no **value** an entry carries — an env var, a header — is ever read into the
+output. Only their names are.
 
-A remote entry — `url`, or the client's own spelling of it — is first asked what it says to
-an unauthenticated `initialize`. An endpoint that answers is measured through the
-`mcp-remote` bridge, the path the leaderboard's remote rows already take. One that answers
-`401` or `403` is reported **auth-walled**, quoting the status and the `WWW-Authenticate`
-header it sent, with the URL: a working server this audit holds no credential for, so the
-total above it is a floor. One that answers nothing usable is **unreachable**, with the
-reason. Header values an entry carries are sent and never printed — only their names are —
-and nothing here ever opens a browser.
+A remote entry — `url`, or the client's own spelling of it — is probed before anything is
+launched, and reported as measured, **auth-walled** or **unreachable** depending on what it
+answers; an auth-walled row makes the total above it a floor rather than a number. The probe,
+what each verdict quotes, and why it exists at all are in
+[METHODOLOGY §who pays the number](docs/METHODOLOGY.md#who-pays). Nothing here opens a
+browser.
 
 Totals are reported per config file, never merged: a context window belongs to one client
 session, so summing Cursor's servers into Claude Desktop's total would describe a session
@@ -88,45 +99,18 @@ nobody runs.
 
 Not every client puts every tool definition in context on every request, so the total above
 is not automatically your bill. Which client reads the config decides it, and for Claude Code
-so does how that client is configured **on this machine** — which `audit` reads rather than
-assumes. No other client's posture is readable from a file this opens, so for those the report
-gives what their vendor is on record with, or says there is nothing on record, and claims
-neither as a measurement.
-
-**Clients whose vendor is on record as deferring** — Cursor (*dynamic context discovery*),
-Codex CLI (*tool search*), and VS Code, whose record is a pair of conditions rather than a
-default. For these the report prints what the vendor states, what that record leaves open, and
-the address and date of every source behind it. It stops where Claude Code's entry stops:
-nothing here measured any of them, and no config file this reads states their posture — so the
-total is what the definitions weigh, not a bill every request is known to carry, and not a
-saving either. Cursor's record is the reason this changed: its engineering blog described the
-mechanism on 2026-01-06 while its MCP configuration page, then and now, says nothing, and a
-rule that read only that page reported an absence of a record for eight months.
-
-**Clients with no default deferral on record** — Claude Desktop, Windsurf, Gemini CLI, Zed,
-Kiro, Goose. The total is what every request carries, as in the example above. That sentence is
-an absence of a record about those clients, not a measurement of them, and the report says so
-in those words.
-
-**Claude Code defers MCP tool definitions by default** (its **tool search**): they are not
-in context at session start, and load when the model reaches for one. Three variables move
-that, and `audit` reads all three — from the shell it runs in *and* from the `env` block of
-Claude Code's own settings files (managed, `<cwd>/.claude/settings.local.json`,
-`<cwd>/.claude/settings.json`, `~/.claude/settings.json`), because a machine that switched
-deferral off in a settings file is not a machine running the default:
-
-| setting | what the audit reports |
-|---|---|
-| nothing set (the default) | every definition deferred, at any size — no threshold applies |
-| `ENABLE_TOOL_SEARCH=true` | same: every definition deferred |
-| `ENABLE_TOOL_SEARCH=false` | deferral off — every request carries the full total. In a settings `env` block that is the **string** `"false"`; the JSON boolean `false` is the last row, not this one |
-| `ENABLE_TOOL_SEARCH=auto` / `auto:N` | deferred only once definitions reach 10% / N% of the context window |
-| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` set to `1`, `true`, `yes` or `on` | tool search off — read first, because `ENABLE_TOOL_SEARCH` cannot override it |
-| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` set to `0`, `false`, `no` or `off` | it turned nothing off, so the read moves on and the rows above decide. It is a boolean flag in the client, not a marker whose presence is the signal |
-| `ANTHROPIC_BASE_URL` off `api.anthropic.com` | falls back to loading up front — consulted only while `ENABLE_TOOL_SEARCH` is unset |
-| anything else in `ENABLE_TOOL_SEARCH` | not a documented value, so nothing is claimed from it |
-| any of the three set, in a settings `env` block, to something that is not a string — a JSON boolean, a number, `null` | it is set there and what it is set to is unknown, so no posture is claimed: the report says whether these tokens are deferred cannot be said from it |
-| a server pinned `"alwaysLoad": true` in its entry | loads at session start whatever the setting says — read from the entry, named with its tokens, and left out of any threshold comparison |
+so does how that client is configured **on this machine** — three environment variables and a
+per-server `alwaysLoad` pin, which `audit` reads rather than assumes, from the shell it runs
+in *and* from the `env` block of Claude Code's own settings files. No other client's posture
+is readable from a file this opens, so for those the report gives what the vendor is on record
+with, or says there is nothing on record, and claims neither as a measurement.
+
+**The model is written down once, on the methodology page**, because it gets corrected often
+and a second copy here would be a second place to correct:
+[METHODOLOGY §who pays the number](docs/METHODOLOGY.md#who-pays) carries every variable and
+what it resolves to, the four kinds of first-party record the rule admits, the questions the
+report refuses to answer rather than guess, and the address and date behind every claim. What
+follows is what that model looks like when you run it.
 
 On a machine where none of them is set, the same stack reads:
 
@@ -147,7 +131,7 @@ On a machine where none of them is set, the same stack reads:
     a tool whose _meta carries "anthropic/alwaysLoad": true, which this audit does not read from a capture
 ```
 
-**Do not take that table on trust — your own client will tell you.** Everything above is read
+**Do not take that model on trust — your own client will tell you.** All of it is read
 from Anthropic's documentation, and documentation about someone else's product is exactly the
 kind of claim this project refuses to leave unchecked elsewhere. Claude Code writes its own
 decision to a debug log, before it sends anything, so you can check your machine rather than
@@ -164,7 +148,7 @@ Three line shapes answer three different questions:
 |---|---|
 | `[ToolSearch:optimistic] mode=…, ENABLE_TOOL_SEARCH=…, result=…` | which mode it picked at startup, and the value it read. **Optimistic is its own word for a guess** — it can be revised below |
 | `Dynamic tool loading: 0/N deferred tools included` | the one that settles it: how many of the `N` deferrable tools went into the request. `0/N` is deferral actually happening |
-| `[ToolSearch:optimistic] disabled: ANTHROPIC_BASE_URL=… is not a first-party Anthropic host` | the fallback in the table above, firing, in the client's own words |
+| `[ToolSearch:optimistic] disabled: ANTHROPIC_BASE_URL=… is not a first-party Anthropic host` | the base-URL fallback, firing, in the client's own words |
 
 Read the *later* requests, not the first. A stdio server can finish connecting after the first
 request has already gone, so an early low count is a race rather than a finding.
@@ -177,8 +161,8 @@ a proportionally larger one — pass `--context` to `audit` to compare against t
 actually run.
 
 None of this is free, and it is one trivial request. These are Claude Code's own debug lines
-rather than a documented interface, so they can change; the table above is what this project
-holds to a dated re-read. No other client discovered by `audit` writes anything comparable,
+rather than a documented interface, so they can change; the methodology page is what this
+project holds to a dated re-read. No other client discovered by `audit` writes anything comparable,
 which is why no other row here is a measurement: three of them get their vendor's own record,
 dated and addressed, and the rest an absence of one.
 
@@ -189,22 +173,6 @@ tool names plus the server's `instructions` — is measured per server and publi
 leaderboard's `session start` column, and for at least one server in the published set it
 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.19×–1.93× across 86
-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
-to something that is not a string, and when `ENABLE_TOOL_SEARCH` holds a value Claude Code
-does not document; and it will not pass an absence of a record off as a measurement, or a
-vendor's record off as one either. The first two print as unanswered questions. The third
-prints as an answer that names itself: for the six discovered clients with no default on
-record — `claude-desktop`, `windsurf`, `gemini`, `zed`, `kiro`, `goose` — the tokens are
-counted as loaded up front, and the report says so in those words, "an absence of a record
-about the client, not a measurement of it". For `cursor`, `codex` and `vscode` it prints the
-vendor's record with its dates and everything it leaves open, and claims no side.
-Full model, sources and dates: [METHODOLOGY §who pays the number](docs/METHODOLOGY.md#who-pays).
-
 **In CI**, make it a gate — the bundlesize move for agents:
 
 ```bash
@@ -277,15 +245,14 @@ still match today and silence for the rest. Most installs will show a mix:
 
 ```
   server               tools  tokens   share   claude
-  github                  44  54,422   95.8%   18,406
-  memory                   9   2,378    4.2%       —
+  my-server               18   9,400   79.8%    3,120
+  my-fork                  6   2,380   20.2%       —
 ```
 
-Add `--suggest` to place each of your tools in the measured set's tool-shape distribution
-([method](docs/METHODOLOGY.md#tool-shape)) and get advice only where the data can point at
-something. Only descriptions draw advice — schemas are functional surface; descriptions are
-prose every request carries — and only descriptions at or above the 90th percentile of the
-1,430 measured tools:
+Add `--suggest` to place each of your tools in the measured set's tool-shape distribution and
+get advice only where the data can point at something. What draws a suggestion, what never
+does, and the percentile that decides are in
+[METHODOLOGY §tool shape](docs/METHODOLOGY.md#tool-shape):
 
 ```
   suggest — descriptions at or above the 90th percentile of measured tools
@@ -305,8 +272,8 @@ are not:
 
 ```
   changed — published versions of your servers that have moved since
-  (index 2026-09-04, 2 published captures; matched by canonical hash, never by name):
-    notes (published as obsidian) — you have the capture published 2026-08-19 at 1,132 tokens;
+  (index 2026-09-05, 99 published captures; matched by canonical hash, never by name):
+    notes (published as my-server) — you have the capture published 2026-08-19 at 1,132 tokens;
       the current one is 2,062 (+930, 2026-08-26)
     updating all 1 would add 930 tokens to every request in this client.
 ```
@@ -378,9 +345,10 @@ the method is [Claude divergence](docs/METHODOLOGY.md#claude-divergence).
 
 ## Why trust the number?
 
-Every published number is backed by a `measurement.json` containing the raw `tools/list`
-capture, the SHA-256 of its canonical bytes, the pinned tokenizer (`o200k_base`), and the
-exact launch command. Disputes reduce to a byte-level diff:
+Every published number is backed by a `measurement.json`. What it holds, and the five lines
+that re-derive the number from it, are in
+[METHODOLOGY §reproduce it](docs/METHODOLOGY.md#reproduce-it). Disputes reduce to a byte-level
+diff, and the CLI does that for you:
 
 ```bash
 npx -y mcp-context-cost verify results/github/measurement.json
@@ -418,7 +386,7 @@ number is *not*, config policy, failure taxonomy, frozen color bands, known dive
 | `src/cli.ts` | `audit` (measure your own stack), `verify` (re-derive any published number), `measure` |
 | `spec/fixtures/` | golden vectors shared by the TypeScript and bash implementations |
 | `tools/` | the scripts that call a network API — the Claude divergence run, the adoption reading, the registry scan — 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 |
+| `upstream/` | `badge.sh` + bash tests — the self-serve badge recipe, carried here |
 | `servers.yaml` | 107 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 |
@@ -434,14 +402,12 @@ That prints the number and writes nothing. Published records
 (`results/<name>/measurement.json`, `badges/<name>.json`, the `history.csv`
 row) come from CI: a developer machine is a different architecture under
 different load, and a measurement taken there describes it rather than the
-server. `local-mcp`'s failing record was made on an arm64 laptop, and its
-stderr named an architecture the record itself did not — which is why every
-measurement now records `isolation.arch`. The entry turned out to be
-unavailable on both architectures, and a record that says where it was made
-is what lets that be told from a broken server. To get your server into the
-leaderboard, add an entry to `servers.yaml` and open a pull request; the check
-on that PR measures the entry read-only, and the rotation publishes it after
-merge.
+server. Which machine a number applies to, and the failed record that made it
+a rule, are in
+[METHODOLOGY §which machine a number applies to](docs/METHODOLOGY.md#which-machine-a-number-applies-to).
+To get your server into the leaderboard, add an entry to `servers.yaml` and
+open a pull request; the check on that PR measures the entry read-only, and the
+rotation publishes it after merge.
 
 For a badge on your own README, run the published CLI in your server's own CI
 (the [gate](#defend-the-number-dont-just-display-it) below writes
@@ -469,7 +435,7 @@ cp results/my-server/measurement.json .context-cost/baseline.json
 
 # on every pull request
 npx -y mcp-context-cost measure --name my-server --command "node dist/index.js" \
-  --baseline .context-cost/baseline.json --max-increase 500
+  --baseline .context-cost/baseline.json --max-increase 100
 ```
 
 ```
@@ -483,26 +449,13 @@ INCREASE FAIL: +121 tokens, over the 100 allowed — this change adds that to ev
 
 Both sides are single measurements carrying per-tool counts, so an established
 change is attributed exactly: which tools arrived, which grew, and by how much.
-And `--max-increase` fails on more than the number — a server that stops
-starting on the branch makes the total go *down*, and reporting that as an
-improvement is the one mistake a gate like this must not make, so a change that
-could not be established fails too.
-
-As a GitHub Action, that whole workflow is five lines
-([full example](examples/server-author-ci.yml)):
-
-```yaml
-- uses: athakur3/mcp-context-cost@v1
-  with:
-    name: my-server
-    command: node dist/index.js
-    baseline: .context-cost/baseline.json
-    max-increase: 500
-```
+And `--max-increase` fails on more than the number here too: a change that could
+not be established fails the gate, for the reason the `audit` gate gives above.
 
-It exposes `tokens`, `tools`, `status`, `measurement` and `badge` as outputs —
-available whether the gate passed or not — so a later step can comment the
-number on the pull request or publish the badge.
+As a GitHub Action that whole workflow is the five lines at the top of this page
+([full example](examples/server-author-ci.yml)) — the same inputs, and the same
+outputs written whether the gate passed or not, for a later step to comment on
+the pull request or publish as a badge.
 
 Point the link at the measurement behind the number — for servers in this sweep that is
 `https://athakur3.github.io/mcp-context-cost/servers/<name>.html`; otherwise the
@@ -522,8 +475,8 @@ npx tsc --noEmit                # typecheck
 npm run sweep:all -- --docker   # full curated sweep (Docker isolation)
 ```
 
-Notable engineering choices: the MCP client is a deliberate ~220-line raw-wire
-implementation (SDK schema-parsing can reorder keys, which would corrupt canonical bytes);
+Notable engineering choices: the MCP client is a deliberate raw-wire implementation
+rather than the SDK (schema-parsing can reorder keys, which would corrupt canonical bytes);
 sweep servers run in credential-free Docker containers with recorded isolation; the badge
 color bands are frozen against the observed distribution of the first full sweep.
 

package/dist/audit/audit.d.ts

@@ -25,23 +25,23 @@ export interface AuditServerResult {
     toolCount: number | null;
     /** Share of this config's measured total, 0–1. */
     share: number | null;
-    command?: string;
-    url?: string;
+    command?: string | undefined;
+    url?: string | undefined;
     /** Names only — a server's env values never enter a report. */
     envVarNames: string[];
     /** Names only, and only for a remote entry that carries any — values never enter a report. */
-    headerNames?: string[];
+    headerNames?: string[] | undefined;
     /** Claude Code's `alwaysLoad: true`, read from the entry: loads at session start whatever the setting. */
-    alwaysLoad?: true;
-    canonicalSha256?: string | null;
+    alwaysLoad?: true | undefined;
+    canonicalSha256?: string | null | undefined;
     /**
      * Anthropic-request cost from the published Claude divergence run, only when
      * its captured hash matches this install (`--claude`). `null` means the
      * install doesn't match what was published — silence, not a stale guess.
      * `undefined` means `--claude` wasn't requested at all.
      */
-    claudeTokens?: number | null;
-    notes?: string;
+    claudeTokens?: number | null | undefined;
+    notes?: string | undefined;
 }
 export interface HeaviestTool {
     server: string;
@@ -96,9 +96,9 @@ export interface AuditConfigResult {
     heaviestTools: HeaviestTool[];
     trimAdvice: TrimAdvice | null;
     /** Present only when `--suggest` ran with a usable baseline. */
-    suggestions?: ConfigSuggestions;
+    suggestions?: ConfigSuggestions | undefined;
     /** Present only when `--changed` ran with a usable capture index. */
-    captureVerdicts?: ServerCaptureVerdict[];
+    captureVerdicts?: ServerCaptureVerdict[] | undefined;
     /**
      * Whether this client loads the total up front or defers it, and — when the
      * client decides that by a threshold — which side of it this stack is on.
@@ -171,30 +171,30 @@ export interface AuditReport {
          * against the whole stack and the verdict fails rather than passing on a
          * total that understates by an unknown amount.
          */
-        unestablished?: string[];
+        unestablished?: string[] | undefined;
         /** Present only when over budget: the arithmetic of getting back under it. */
-        fit?: BudgetFit;
+        fit?: BudgetFit | undefined;
     };
     /** Present only when a divergence run was supplied (`--claude`). */
     claudeDivergence?: {
         model: string;
         measuredAt: string;
-    };
+    } | undefined;
     /** Which published tool-shape baseline `--suggest` read its percentiles from. */
     toolShape?: {
         generatedAt: string;
         toolCount: number;
         serverCount: number;
-    };
+    } | undefined;
     /** Which published capture index `--changed` joined against. */
     captureIndex?: {
         generatedAt: string;
         captureCount: number;
-    };
+    } | undefined;
     /** Present only when a baseline report was supplied (`--baseline`). */
-    diff?: AuditDiff;
+    diff?: AuditDiff | undefined;
     /** Present only when `--max-increase` was supplied alongside a baseline. */
-    increaseGate?: IncreaseGate;
+    increaseGate?: IncreaseGate | undefined;
     problems: string[];
 }
 /** Cache key for measurement reuse: the exact argv two configs would spawn. */
@@ -218,38 +218,36 @@ export declare function collapsedKeys(configs: LoadedConfig[]): Set<string>;
  * launching a single server.
  */
 export declare function buildReport(configs: LoadedConfig[], measured: Map<string, Measurement>, opts?: {
-    contextWindow?: number;
-    budget?: number;
-    generatedAt?: string;
+    contextWindow?: number | undefined;
+    budget?: number | undefined;
+    generatedAt?: string | undefined;
     /** Published `tools-delta/v1` run to join against (`--claude`); omit to skip the join. */
-    divergence?: DivergenceRun | null;
+    divergence?: DivergenceRun | null | undefined;
     /** Published `tool-shape/v1` baseline (`--suggest`); omit to skip suggestions. */
-    toolShape?: ToolShapeBaseline | null;
+    toolShape?: ToolShapeBaseline | null | undefined;
     /** Published `capture-index/v1` (`--changed`); omit to skip the version join. */
-    captureIndex?: CaptureIndex | null;
+    captureIndex?: CaptureIndex | null | undefined;
     /**
      * The audited machine's SHELL tool-search variables. Passed in rather than
      * read here so this stays pure and a report is reproducible from its
      * inputs; `runAudit` supplies the real environment. Omitted means the shell
      * set nothing.
      */
-    env?: ToolSearchEnv;
+    env?: ToolSearchEnv | undefined;
     /**
      * The other place those variables come from: Claude Code's own settings
      * files, highest precedence first, as `loadSettingsSources` read them.
      * `runAudit` supplies these. Omitted means they were not read here — which
      * the report says, rather than reporting a default it did not establish.
      */
-    settings?: ToolSearchSource[];
+    settings?: ToolSearchSource[] | undefined;
     /**
      * What each remote endpoint said to an unauthenticated `initialize`, keyed
      * by `serverKey`. `runAudit` supplies it from `probeRemotes`; omitted, a
      * remote entry is reported as not probed rather than as anything else.
      */
-    remotes?: Map<string, RemoteProbe>;
+    remotes?: Map<string, RemoteProbe> | undefined;
 }): AuditReport;
 /** Human output. JSON output is the report object itself. */
 export declare function formatReport(report: AuditReport): string;
-/** Top-level tool list across every config — used by nothing yet, handy for --json consumers. */
-export declare function allHeaviestTools(report: AuditReport, limit?: number): HeaviestTool[];
 export type { ToolMeasurement };

package/dist/audit/audit.js

@@ -18,6 +18,7 @@ import { SUGGEST_DESCRIPTION_PERCENTILE, suggestFor, } from '../core/tool-shape.
 import { identify } from '../core/capture-index.js';
 import { evaluateDeferral, BAND_PRECISION, PUBLISHED_WIRE_TO_CLIENT_RATIO, SHELL_SOURCE, } from './deferral.js';
 import { formatDiff, formatGate } from './diff.js';
+import { signed } from '../core/format.js';
 export const DEFAULT_CONTEXT_WINDOW = 200_000;
 const TRIM_TOOL_COUNT = 3;
 function buildSuggestions(pool, baseline) {
@@ -52,7 +53,7 @@ function buildTrimAdvice(sortedTools, totalTokens) {
 export function planBudgetFit(config, limit) {
     const measured = config.servers
         .filter((srv) => typeof srv.tokens === 'number' && srv.tokens > 0)
-        .sort((a, b) => b.tokens - a.tokens);
+        .toSorted((a, b) => b.tokens - a.tokens);
     const overBy = config.totalTokens - limit;
     const drop = [];
     let remaining = config.totalTokens;
@@ -87,10 +88,14 @@ function envSignature(s) {
     const env = s.env ?? {};
     const headers = s.headers ?? {};
     return JSON.stringify([
-        Object.keys(env).sort().map((k) => [k, env[k]]),
+        Object.keys(env)
+            .toSorted()
+            .map((k) => [k, env[k]]),
         // A remote's headers decide what it serves the way env decides for a
         // process: a bearer token selects an account, and an account its tools.
-        Object.keys(headers).sort().map((k) => [k, headers[k]]),
+        Object.keys(headers)
+            .toSorted()
+            .map((k) => [k, headers[k]]),
     ]);
 }
 /**
@@ -252,7 +257,12 @@ export function buildReport(configs, measured, opts = {}) {
             if (s.transport === 'remote') {
                 const probe = opts.remotes?.get(serverKey(s));
                 if (!probe) {
-                    skipped.push({ ...base, ...none, status: 'unreachable', notes: `${s.url ?? 'url'} — not probed` });
+                    skipped.push({
+                        ...base,
+                        ...none,
+                        status: 'unreachable',
+                        notes: `${s.url ?? 'url'} — not probed`,
+                    });
                     continue;
                 }
                 if (probe.kind === 'auth-walled') {
@@ -283,14 +293,26 @@ export function buildReport(configs, measured, opts = {}) {
                     continue;
                 }
                 if (probe.kind === 'unreachable') {
-                    skipped.push({ ...base, ...none, status: 'unreachable', notes: `${s.url}: ${probe.detail}` });
+                    skipped.push({
+                        ...base,
+                        ...none,
+                        status: 'unreachable',
+                        notes: `${s.url}: ${probe.detail}`,
+                    });
                     continue;
                 }
                 // Open: measured through the bridge, and read below like any launch.
             }
             const m = measured.get(serverKey(s));
             if (!m) {
-                skipped.push({ ...base, status: 'startup-failure', tokens: null, toolCount: null, share: null, notes: 'not measured' });
+                skipped.push({
+                    ...base,
+                    status: 'startup-failure',
+                    tokens: null,
+                    toolCount: null,
+                    share: null,
+                    notes: 'not measured',
+                });
                 continue;
             }
             if (!measuredOk(m)) {
@@ -314,7 +336,11 @@ export function buildReport(configs, measured, opts = {}) {
                 toolCount: m.toolCount,
                 share: null, // filled once the total is known
                 canonicalSha256: m.canonicalSha256,
-                claudeTokens: opts.divergence ? (isCurrent(divRow, m.canonicalSha256 ?? null) ? divRow.claudeDelta : null) : undefined,
+                claudeTokens: opts.divergence
+                    ? isCurrent(divRow, m.canonicalSha256 ?? null)
+                        ? divRow.claudeDelta
+                        : null
+                    : undefined,
                 notes: m.status === 'dynamic' ? redact(m.notes, secrets(s)) : undefined,
             });
             for (const t of m.tools) {
@@ -346,7 +372,10 @@ export function buildReport(configs, measured, opts = {}) {
             trimAdvice: buildTrimAdvice(tools, totalTokens),
             suggestions: opts.toolShape ? buildSuggestions(shapePool, opts.toolShape) : undefined,
             captureVerdicts: opts.captureIndex
-                ? ok.map((s) => ({ name: s.name, verdict: identify(s.canonicalSha256, opts.captureIndex) }))
+                ? ok.map((s) => ({
+                    name: s.name,
+                    verdict: identify(s.canonicalSha256, opts.captureIndex),
+                }))
                 : undefined,
         };
         built.push(result);
@@ -364,7 +393,10 @@ export function buildReport(configs, measured, opts = {}) {
         problems,
     };
     if (opts.divergence) {
-        report.claudeDivergence = { model: opts.divergence.model, measuredAt: opts.divergence.measuredAt };
+        report.claudeDivergence = {
+            model: opts.divergence.model,
+            measuredAt: opts.divergence.measuredAt,
+        };
     }
     if (opts.toolShape) {
         report.toolShape = {
@@ -466,8 +498,9 @@ function postureSourceLines(d) {
             : '';
         const held = r.state === 'unreadable'
             ? 'could not be read — what it sets is unknown'
-            : [r.sets.length ? `sets ${r.sets.join(', ')}` : '', unreadableVars].filter(Boolean).join(', and ') ||
-                'sets none of them';
+            : [r.sets.length ? `sets ${r.sets.join(', ')}` : '', unreadableVars]
+                .filter(Boolean)
+                .join(', and ') || 'sets none of them';
         // Which place the verdict came out of, said once rather than left to a
         // reader to work out from two lists.
         const decided = d.setting?.source === r.source ? ', which decided this' : '';
@@ -477,7 +510,7 @@ function postureSourceLines(d) {
         lines.push(`    ${absent} other settings file(s) it reads are not on this machine`);
     }
     if (!recs.some((r) => r.scope !== 'shell')) {
-        lines.push("    its settings files were NOT read here, so what they set is unknown");
+        lines.push('    its settings files were NOT read here, so what they set is unknown');
     }
     return lines;
 }
@@ -602,8 +635,8 @@ function deferralLines(d, skippedNames) {
     // Read from the entries, so it is stated up front rather than listed among
     // the conditions a reader has to check: whatever the setting says, these load.
     if (d.mechanism === 'tool search' && d.alwaysLoad.servers.length) {
-        const n = d.alwaysLoad.servers.length;
-        lines.push(`  ${n} server${n === 1 ? ' is' : 's are'} pinned "alwaysLoad": true and load${n === 1 ? 's' : ''} at session start whatever`);
+        const pinned = d.alwaysLoad.servers.length;
+        lines.push(`  ${pinned} server${pinned === 1 ? ' is' : 's are'} pinned "alwaysLoad": true and load${pinned === 1 ? 's' : ''} at session start whatever`);
         lines.push(`  the setting says: ${d.alwaysLoad.servers.join(', ')} — ${d.alwaysLoad.tokens.toLocaleString()} wire tokens,`);
         lines.push('  left out of any threshold comparison below.');
     }
@@ -808,8 +841,8 @@ export function formatReport(report) {
             const skippedInScope = report.configs
                 .filter((c) => c.deferral === cfg.deferral)
                 .reduce((a, c) => a + c.skipped.length, 0);
-            for (const line of deferralLines(cfg.deferral, skippedInScope))
-                lines.push(line);
+            for (const deferralLine of deferralLines(cfg.deferral, skippedInScope))
+                lines.push(deferralLine);
         }
         if (cfg.heaviestTools.length) {
             lines.push('');
@@ -848,7 +881,7 @@ export function formatReport(report) {
                     // fact worth seeing rather than one to smooth over.
                     const alias = name === v.server ? name : `${name} (published as ${v.server})`;
                     lines.push(`    ${alias} — you have the capture published ${v.yourDate} at ${n(v.yourTokens)} tokens; ` +
-                        `the current one is ${n(v.currentTokens)} (${v.deltaTokens >= 0 ? '+' : '−'}${n(Math.abs(v.deltaTokens))}, ${v.currentDate})`);
+                        `the current one is ${n(v.currentTokens)} (${signed(v.deltaTokens)}, ${v.currentDate})`);
                 }
                 lines.push(`    updating all ${behind.length} would ${total >= 0 ? 'add' : 'remove'} ${n(Math.abs(total))} tokens ` +
                     `${total >= 0 ? 'to' : 'from'} every request in this client.`);
@@ -971,10 +1004,3 @@ export function formatReport(report) {
         `${PUBLISHED_WIRE_TO_CLIENT_RATIO.high.toFixed(BAND_PRECISION)}× on Anthropic requests. See docs/METHODOLOGY.md §claude-divergence.`);
     return lines.map((l) => l.replace(/\s+$/, '')).join('\n');
 }
-/** Top-level tool list across every config — used by nothing yet, handy for --json consumers. */
-export function allHeaviestTools(report, limit = 10) {
-    return report.configs
-        .flatMap((c) => c.heaviestTools)
-        .sort((a, b) => b.tokens - a.tokens)
-        .slice(0, limit);
-}