context-doctor 0.12.2 → 0.13.1

package/README.md

@@ -91,6 +91,9 @@ Practical upshot: a developer who only wants cheaper, faster API calls never tou
 | `context-doctor analyze <file>` | Profile a conversation: token breakdown, findings, cost + latency estimates. `--fail-over-budget` exits 1 on a breach, for CI |
 | `context-doctor optimize <file>` | Apply the safe fixes; add `--strategy trim-tool-calls` for big inline file writes, `--strategy prune-history` for consented lossy compaction |
 | `context-doctor session [file]` | Profile a Claude Code session: live context, findings, **measured tokens and prompt-cache economics**. Also reads ChatGPT data exports (`conversations.json`) |
+| `context-doctor init [preset]` | Write a `.contextdoctorrc` from a preset (`chat`, `agent`, `batch`) — a budget you can adopt in one command and tune later |
+| `context-doctor diff <before> <after>` | Compare two profiles: what moved by category, which findings were resolved or introduced, and what it saves in money and latency |
+| `context-doctor accuracy` | How much of what you are billed for is visible in your transcript — the fixed harness baseline and the per-turn injected content neither you nor the profiler can see |
 | `context-doctor cursor [--list]` | Profile a chat from Cursor's local history (both storage formats) |
 | `context-doctor report` | Machine-wide impact report (proxy savings persist across restarts): exact proxy savings, hook activity, recoverable waste in recent sessions |
 | `context-doctor proxy` | Always-on local proxy that optimizes every Anthropic/OpenAI API request in flight (`/stats` for cumulative savings) |
@@ -244,12 +247,13 @@ const { conversation, tokensBefore, tokensAfter } = optimizeConversation(chatJso
 ## What it detects
 
 - **Oversized tool results** — the #1 context killer in agent loops
+- **Oversized tool calls** — a `Write` or a `cat > file <<EOF` puts the whole file in context permanently. In file-heavy agent work these outweigh every tool result combined, and `--strategy trim-tool-calls` reclaims them
 - **Duplicate content** — the same doc/result pasted twice
 - **Near-duplicates** — the same doc re-pasted with different surrounding words (shingle similarity, ≥60%)
-- **Repeated file reads** — the same file pulled in three or more times, every copy still in context
+- **Repeated file reads** — the same file pulled in three or more times, every copy still in context. Counts shell reads too (`cat`, `head`, `tail`, `less`), which is where most of them hide in agent sessions
 - **Retained error output** — stack traces and failed commands kept verbatim long after the fix landed
 - **Repeated identical tool calls** — a signal your agent forgot earlier results
-- **Base64 / binary blobs** in text content
+- **Base64 / binary blobs** in text content — checked by character distribution, not just alphabet, so hex digests and long identifiers are not mistaken for encoded binary
 - **Long history** past the point where models track the middle
 - **Cache-hostile ordering** — volatile content before stable content breaks prompt caching (Anthropic `cache_control`, OpenAI automatic prefix caching)
 - **Window pressure** — usage % against the target model's real context window
@@ -266,6 +270,8 @@ const { conversation, tokensBefore, tokensAfter } = optimizeConversation(chatJso
 
 `trim-tool-calls` is the big one for agent sessions. Writing a file through a tool call puts the entire file in context permanently, so in file-heavy work the calls outweigh every tool result combined — on a real 278k-token session, the default set reached 248k and adding `trim-tool-calls` reached 102k. It is opt-in because it edits what the model itself wrote.
 
+**Optimization is cache-aware.** Prompt caches match a byte-identical prefix, so editing a message in the middle invalidates everything after it — and the naive "trim everything older than the last N messages" boundary moves every single turn. On a 25-turn agent conversation that invalidated the cached prefix on 22 of 24 turns, paying the 1.25x cache-write price on the whole prefix to save a few hundred tokens. The trim boundary is quantized so it holds still between steps (8 of 24 on the same fixture), while still reaching 15 of 20 tool results.
+
 Everything the optimizer does is inspectable: it prints exactly which messages changed and how many tokens each change saved.
 
 **Summarization without an API key:** when `prune-history` runs through the MCP tools, context-doctor hands a digest of the pruned turns back to the model that called it (the Claude/GPT already running in your app) and asks *it* to write the replacement summary — LLM-quality compaction, zero extra cost, no keys.

package/dist/accuracy.d.ts

@@ -0,0 +1,37 @@
+/**
+ * `context-doctor accuracy` — how much of what you are billed for is actually
+ * visible in your transcript.
+ *
+ * Every profile in this tool describes the CONVERSATION: the messages the
+ * transcript records. Your bill covers the whole request, which also carries
+ * the harness's system prompt, tool schemas, skills, and per-turn injected
+ * content that is never written to the transcript at all.
+ *
+ * Both numbers are correct; they answer different questions. This command
+ * measures the distance between them on your own sessions, so "why is my bill
+ * bigger than the profile?" has an answer with evidence behind it.
+ *
+ * WHAT THIS IS NOT: a tokenizer benchmark. It cannot be — the content behind
+ * the gap is unavailable to us, so the gap cannot be attributed to estimator
+ * drift. To measure the estimator itself, use `analyze --exact`, which counts
+ * the same bytes with the provider's own tokenizer.
+ */
+export interface AccuracyReport {
+    sessionsScanned: number;
+    /** Turn-to-turn observations used. */
+    samples: number;
+    /** Median share of a turn's billed growth that the transcript accounts for. */
+    medianCoverage: number;
+    /** Median tokens per turn billed but absent from the transcript. */
+    medianInvisiblePerTurn: number;
+    /** Median fixed baseline: system prompt + tool schemas, before any turn. */
+    medianBaseline?: number;
+}
+/**
+ * @param limit  How many recent sessions to sample.
+ * @param paths  Explicit transcripts to measure instead of discovering them.
+ *               Callers (and tests) that already know which files they mean
+ *               should not have to impersonate a home directory to say so.
+ */
+export declare function measureAccuracy(limit?: number, paths?: string[]): AccuracyReport;
+export declare function renderAccuracy(report: AccuracyReport): string;

package/dist/accuracy.js

@@ -0,0 +1,124 @@
+/**
+ * `context-doctor accuracy` — how much of what you are billed for is actually
+ * visible in your transcript.
+ *
+ * Every profile in this tool describes the CONVERSATION: the messages the
+ * transcript records. Your bill covers the whole request, which also carries
+ * the harness's system prompt, tool schemas, skills, and per-turn injected
+ * content that is never written to the transcript at all.
+ *
+ * Both numbers are correct; they answer different questions. This command
+ * measures the distance between them on your own sessions, so "why is my bill
+ * bigger than the profile?" has an answer with evidence behind it.
+ *
+ * WHAT THIS IS NOT: a tokenizer benchmark. It cannot be — the content behind
+ * the gap is unavailable to us, so the gap cannot be attributed to estimator
+ * drift. To measure the estimator itself, use `analyze --exact`, which counts
+ * the same bytes with the provider's own tokenizer.
+ */
+import { estimateTokens, formatTokens, MESSAGE_OVERHEAD_TOKENS } from "./tokens.js";
+import { parseConversation } from "./parse.js";
+import { listSessions, parseSessionFile } from "./session.js";
+function median(values) {
+    if (values.length === 0)
+        return 0;
+    const sorted = [...values].sort((a, b) => a - b);
+    const mid = Math.floor(sorted.length / 2);
+    return sorted.length % 2 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
+}
+/** Below this, a turn is too small for the ratio to mean anything. */
+const MIN_DELTA_TOKENS = 200;
+/**
+ * @param limit  How many recent sessions to sample.
+ * @param paths  Explicit transcripts to measure instead of discovering them.
+ *               Callers (and tests) that already know which files they mean
+ *               should not have to impersonate a home directory to say so.
+ */
+export function measureAccuracy(limit = 20, paths) {
+    const coverages = [];
+    const invisible = [];
+    const baselines = [];
+    let scanned = 0;
+    const targets = paths ? paths.map((path) => ({ path })) : listSessions(limit);
+    for (const info of targets) {
+        let parsed;
+        try {
+            parsed = parseSessionFile(info.path);
+        }
+        catch {
+            continue; // an unreadable session is not a measurement
+        }
+        const usage = parsed.usageSamples ?? [];
+        if (usage.length < 2)
+            continue;
+        scanned++;
+        // Estimate through the same parser the profiler uses, with the same
+        // per-message overhead — anything else would measure a different estimator.
+        const normalized = parseConversation(parsed.conversationJson).messages;
+        const estimateAt = (i) => {
+            const m = normalized[i];
+            return m ? estimateTokens(m.text) + MESSAGE_OVERHEAD_TOKENS : 0;
+        };
+        let baseline = usage[0].input;
+        for (let i = 0; i < usage[0].index; i++)
+            baseline -= estimateAt(i);
+        if (baseline > 0)
+            baselines.push(baseline);
+        for (let s = 1; s < usage.length; s++) {
+            const billed = usage[s].input - usage[s - 1].input;
+            if (billed < MIN_DELTA_TOKENS)
+                continue;
+            let visible = 0;
+            for (let i = usage[s - 1].index; i < usage[s].index; i++)
+                visible += estimateAt(i);
+            if (visible <= 0)
+                continue;
+            // A turn cannot be more than fully visible; ratios above 1 mean the
+            // billed figure moved for another reason (a compaction, a schema change).
+            const coverage = visible / billed;
+            if (coverage > 1)
+                continue;
+            coverages.push(coverage);
+            invisible.push(billed - visible);
+        }
+    }
+    return {
+        sessionsScanned: scanned,
+        samples: coverages.length,
+        medianCoverage: median(coverages),
+        medianInvisiblePerTurn: median(invisible),
+        medianBaseline: baselines.length ? median(baselines) : undefined,
+    };
+}
+export function renderAccuracy(report) {
+    const lines = [];
+    lines.push("CONTEXT DOCTOR — billed context vs what your transcript shows");
+    lines.push("═".repeat(56));
+    if (report.samples === 0) {
+        lines.push("No usable samples found.");
+        lines.push("");
+        lines.push("This reads input-token counts recorded in Claude Code transcripts, so it");
+        lines.push("needs local sessions with at least two assistant turns.");
+        return lines.join("\n");
+    }
+    const pct = (n) => `${(n * 100).toFixed(0)}%`;
+    lines.push(`${report.samples} turns across ${report.sessionsScanned} session(s).`);
+    lines.push("");
+    if (report.medianBaseline !== undefined) {
+        lines.push(`Fixed baseline     ~${formatTokens(report.medianBaseline)} tokens before your first turn —`);
+        lines.push("                   system prompt, tool schemas and skills, none of which the");
+        lines.push("                   transcript stores.");
+    }
+    lines.push(`Transcript covers  ${pct(report.medianCoverage)} of a typical turn's billed growth`);
+    lines.push(`Not in transcript  ~${formatTokens(report.medianInvisiblePerTurn)} tokens per turn (injected reminders,`);
+    lines.push("                   skill and file content, and other per-request additions)");
+    lines.push("");
+    lines.push("Both numbers are right. Profiles describe the conversation you can see and");
+    lines.push("act on; your bill covers the whole request. Trimming what the profile shows");
+    lines.push("still saves real money — it just starts from a higher floor than the profile");
+    lines.push("implies.");
+    lines.push("");
+    lines.push("This does NOT measure tokenizer drift: the missing content is not available");
+    lines.push("to compare against. For that, use `analyze --exact` (provider tokenizer).");
+    return lines.join("\n");
+}

package/dist/cli.js

@@ -7,7 +7,8 @@
  *
  * `-` reads from stdin, so you can pipe: `cat chat.json | context-doctor analyze -`
  */
-import { readFileSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
 import process from "node:process";
 import { parseConversation } from "./parse.js";
 import { profileConversation } from "./profile.js";
@@ -21,6 +22,9 @@ import { runHook } from "./hook.js";
 import { buildImpactReport } from "./impact.js";
 import { recordLedger } from "./ledger.js";
 import { runDoctor } from "./doctor.js";
+import { measureAccuracy, renderAccuracy } from "./accuracy.js";
+import { renderDiff } from "./diff.js";
+import { findPreset, PRESETS, RC_FILENAME } from "./config.js";
 import { runWatch } from "./watch.js";
 import { exactTokenCount } from "./exact.js";
 import { checkBudget, loadConfig } from "./config.js";
@@ -48,6 +52,12 @@ Usage:
                                                 MCP handshake) with one pasteable diagnosis
   context-doctor dashboard                      Local savings dashboard on 127.0.0.1 (--port n,
                                                 default 8790) — charts from your own machine only
+  context-doctor init [preset]                  Write a .contextdoctorrc from a preset
+                                                (chat, agent, batch; no argument lists them)
+  context-doctor diff <before> <after>          Compare two profiles: what moved, which findings
+                                                were resolved, and what it saves
+  context-doctor accuracy                       Measure the token heuristic against the API's own
+                                                counts recorded in your transcripts (--limit n)
   context-doctor watch [file]                   Live-monitor a growing session/agent trace: running
                                                 token/cost line per change, new findings as they appear
                                                 (--interval-ms n, default 2000)
@@ -76,6 +86,7 @@ Options:
                           Default: dedupe, trim-tool-results, strip-base64 (lossless-ish set)
   --keep-recent <n>       (optimize) Messages at the tail to leave untouched (default 6)
   --max-tool-tokens <n>   (optimize) Token budget for trimmed tool results (default 300)
+  --limit <n>             (accuracy) Sessions to sample (default 20)
   --port <n>              (proxy) Port to listen on (default 8787)
   --host <addr>           (proxy) Bind address (default 127.0.0.1; use 0.0.0.0 to expose)
   --config <file>         (proxy) Per-route overrides: {"routes":[{"modelPrefix":"gpt","strategies":[...],
@@ -137,6 +148,9 @@ function parseArgs(argv) {
             case "--interval-ms":
                 args.intervalMs = Number(argv[++i]);
                 break;
+            case "--limit":
+                args.limit = Number(argv[++i]);
+                break;
             case "--host":
                 args.host = argv[++i];
                 break;
@@ -154,6 +168,7 @@ function parseArgs(argv) {
     }
     args.command = positional[0];
     args.file = positional[1];
+    args.positionals = positional.slice(1);
     return args;
 }
 /** Print budget status under a profile when a .contextdoctorrc defines one. */
@@ -203,6 +218,51 @@ function main() {
         void runDoctor();
         return;
     }
+    if (args.command === "init") {
+        const requested = args.positionals?.[0];
+        if (!requested || args.list) {
+            console.log("Presets for .contextdoctorrc — pick the one that matches your workload:\n");
+            for (const p of PRESETS)
+                console.log(`  ${p.id.padEnd(7)} ${p.summary}`);
+            console.log("\nThen: context-doctor init <preset>");
+            return;
+        }
+        const preset = findPreset(requested);
+        if (!preset) {
+            console.error(`Unknown preset "${requested}". Available: ${PRESETS.map((p) => p.id).join(", ")}`);
+            process.exit(1);
+        }
+        const target = join(process.cwd(), RC_FILENAME);
+        if (existsSync(target)) {
+            console.error(`${target} already exists — edit it, or delete it first.`);
+            process.exit(1);
+        }
+        writeFileSync(target, JSON.stringify(preset.config, null, 2) + "\n");
+        console.log(`✓ Wrote ${target} (${preset.id}: ${preset.summary})`);
+        console.log("  Budgets are enforced by the every-prompt hook and reported by analyze/session.");
+        console.log("  Gate a pull request on it with: context-doctor analyze <file> --fail-over-budget");
+        return;
+    }
+    if (args.command === "diff") {
+        const [before, after] = args.positionals ?? [];
+        if (!before || !after) {
+            console.error("Usage: context-doctor diff <before> <after>");
+            process.exit(1);
+        }
+        try {
+            console.log(renderDiff(before, after, args.model));
+        }
+        catch (e) {
+            console.error(`Could not diff: ${e.message}`);
+            process.exit(1);
+        }
+        return;
+    }
+    if (args.command === "accuracy") {
+        const report = measureAccuracy(args.limit ?? 20);
+        console.log(args.json ? JSON.stringify(report, null, 2) : renderAccuracy(report));
+        return;
+    }
     if (args.command === "report") {
         void buildImpactReport(args.port).then((r) => console.log(r));
         return;

package/dist/config.d.ts

@@ -39,11 +39,19 @@ export interface LoadedConfig {
     config: ContextDoctorConfig;
     /** Absolute path of the rc file, or undefined when none was found. */
     path?: string;
+    /** Settings that will be silently ignored, if any. */
+    warnings?: string[];
 }
 /**
- * Load the nearest config. Malformed rc files are reported (so a typo is not
- * silently ignored) but never throw — the tool keeps working with defaults.
+ * Report anything in an rc file that will be silently ignored.
+ *
+ * Every invalid value here fails quietly and looks like the feature not
+ * working: `"trim-tool-result"` (missing s) trims nothing, a negative
+ * keepRecent disables trimming entirely, and a budget written as a string is
+ * never compared against. For a tool whose whole job is measurement, silently
+ * doing nothing is the worst available behaviour.
  */
+export declare function validateConfig(config: unknown, path: string): string[];
 export declare function loadConfig(startDir?: string, onWarn?: (msg: string) => void): LoadedConfig;
 export interface BudgetVerdict {
     /** True when any configured limit is exceeded. */
@@ -61,3 +69,19 @@ export declare function checkBudget(budget: ContextBudget | undefined, profile:
         perCallUsd: number;
     };
 }): BudgetVerdict;
+/**
+ * Starting points for `.contextdoctorrc`.
+ *
+ * An empty rc file is technically valid and completely useless: nobody knows
+ * what a reasonable token budget is for their kind of work until they have
+ * blown through one. These encode the three shapes that actually differ —
+ * a chat product, a coding agent, and a batch pipeline — so a budget can be
+ * adopted in one command and tuned later.
+ */
+export interface Preset {
+    id: string;
+    summary: string;
+    config: ContextDoctorConfig;
+}
+export declare const PRESETS: Preset[];
+export declare function findPreset(id: string): Preset | undefined;

package/dist/config.js

@@ -36,14 +36,88 @@ function candidatePaths(startDir) {
  * Load the nearest config. Malformed rc files are reported (so a typo is not
  * silently ignored) but never throw — the tool keeps working with defaults.
  */
+/** Strategy ids the optimizer actually implements. */
+const KNOWN_STRATEGIES = new Set(["dedupe", "trim-tool-results", "trim-tool-calls", "strip-base64", "prune-history"]);
+const KNOWN_KEYS = new Set(["budget", "strategies", "keepRecent", "maxToolResultTokens", "routes", "model"]);
+const KNOWN_BUDGET_KEYS = new Set(["maxTokens", "maxCostPerMessageUsd", "maxWindowPct"]);
+/**
+ * Report anything in an rc file that will be silently ignored.
+ *
+ * Every invalid value here fails quietly and looks like the feature not
+ * working: `"trim-tool-result"` (missing s) trims nothing, a negative
+ * keepRecent disables trimming entirely, and a budget written as a string is
+ * never compared against. For a tool whose whole job is measurement, silently
+ * doing nothing is the worst available behaviour.
+ */
+export function validateConfig(config, path) {
+    const warnings = [];
+    const where = (key) => `${path}: ${key}`;
+    if (!config || typeof config !== "object" || Array.isArray(config)) {
+        return [`${path}: expected a JSON object`];
+    }
+    const c = config;
+    for (const key of Object.keys(c)) {
+        if (!KNOWN_KEYS.has(key)) {
+            warnings.push(`${where(key)} is not a known setting — ignored (known: ${[...KNOWN_KEYS].join(", ")})`);
+        }
+    }
+    if (c.budget !== undefined) {
+        if (typeof c.budget !== "object" || c.budget === null || Array.isArray(c.budget)) {
+            warnings.push(`${where("budget")} must be an object — ignored`);
+        }
+        else {
+            const budget = c.budget;
+            for (const [key, value] of Object.entries(budget)) {
+                if (!KNOWN_BUDGET_KEYS.has(key)) {
+                    warnings.push(`${where(`budget.${key}`)} is not a known budget limit — ignored`);
+                }
+                else if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+                    warnings.push(`${where(`budget.${key}`)} must be a positive number, got ${JSON.stringify(value)} — this limit will never trigger`);
+                }
+            }
+            if (typeof budget.maxWindowPct === "number" && budget.maxWindowPct > 100) {
+                warnings.push(`${where("budget.maxWindowPct")} is above 100 — a percentage of the context window cannot exceed 100`);
+            }
+        }
+    }
+    if (c.strategies !== undefined) {
+        if (!Array.isArray(c.strategies)) {
+            warnings.push(`${where("strategies")} must be an array — ignored`);
+        }
+        else {
+            for (const id of c.strategies) {
+                if (!KNOWN_STRATEGIES.has(String(id))) {
+                    warnings.push(`${where("strategies")}: "${id}" is not a strategy — ignored (known: ${[...KNOWN_STRATEGIES].join(", ")})`);
+                }
+            }
+        }
+    }
+    for (const key of ["keepRecent", "maxToolResultTokens"]) {
+        const value = c[key];
+        if (value === undefined)
+            continue;
+        if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) {
+            warnings.push(`${where(key)} must be a positive whole number, got ${JSON.stringify(value)} — ignored`);
+        }
+    }
+    if (c.routes !== undefined && !Array.isArray(c.routes)) {
+        warnings.push(`${where("routes")} must be an array — ignored`);
+    }
+    return warnings;
+}
 export function loadConfig(startDir = process.cwd(), onWarn) {
     for (const path of candidatePaths(startDir)) {
         if (!existsSync(path))
             continue;
         try {
             const parsed = JSON.parse(readFileSync(path, "utf8"));
-            if (parsed && typeof parsed === "object")
-                return { config: parsed, path };
+            // Arrays are objects too, hence the explicit check.
+            if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                const warnings = validateConfig(parsed, path);
+                for (const warning of warnings)
+                    onWarn?.(warning);
+                return { config: parsed, path, warnings };
+            }
             onWarn?.(`${path}: expected a JSON object — ignoring`);
         }
         catch (e) {
@@ -71,3 +145,43 @@ export function checkBudget(budget, profile) {
     }
     return { overBudget: breaches.length > 0, breaches, maxTokens: budget.maxTokens };
 }
+export const PRESETS = [
+    {
+        id: "chat",
+        summary: "Interactive chat product — short contexts, latency matters most",
+        config: {
+            // Chat turns are small; a context this large means history is not being
+            // summarized, and every extra token is felt directly as time-to-first-token.
+            budget: { maxTokens: 30_000, maxWindowPct: 40, maxCostPerMessageUsd: 0.15 },
+            strategies: ["dedupe", "strip-base64"],
+            keepRecent: 10,
+        },
+    },
+    {
+        id: "agent",
+        summary: "Coding or tool-using agent — long runs, tool output dominates",
+        config: {
+            // Agents legitimately hold a lot of context, so the budget is generous;
+            // the tight controls go on tool traffic, which is where the waste is.
+            budget: { maxTokens: 150_000, maxWindowPct: 70, maxCostPerMessageUsd: 1.5 },
+            strategies: ["dedupe", "trim-tool-results", "strip-base64"],
+            keepRecent: 6,
+            maxToolResultTokens: 300,
+        },
+    },
+    {
+        id: "batch",
+        summary: "Batch or pipeline jobs — cost per call is the whole story",
+        config: {
+            // Nothing is interactive, so aggressive trimming costs nothing in feel
+            // and everything is multiplied by the number of items in the run.
+            budget: { maxTokens: 60_000, maxCostPerMessageUsd: 0.05 },
+            strategies: ["dedupe", "trim-tool-results", "trim-tool-calls", "strip-base64"],
+            keepRecent: 4,
+            maxToolResultTokens: 150,
+        },
+    },
+];
+export function findPreset(id) {
+    return PRESETS.find((p) => p.id === id);
+}

package/dist/dashboard.js

@@ -7,7 +7,7 @@
  * the server reads local files and answers only the loopback interface.
  */
 import http from "node:http";
-import { readLedger } from "./ledger.js";
+import { foldTotals, readLedger } from "./ledger.js";
 import { listSessions, parseSessionFile } from "./session.js";
 import { parseConversation } from "./parse.js";
 import { profileConversation } from "./profile.js";
@@ -28,6 +28,9 @@ async function fetchProxyStats(port) {
 }
 export async function collectDashboardData(proxyPort = 8787) {
     const ledger = readLedger();
+    // Totals folded in when the ledger rotated; excluded from the daily series,
+    // which describes individual days rather than a carried-forward sum.
+    const carried = foldTotals(ledger.filter((e) => e.ev === "rollup"));
     const checks = ledger.filter((e) => e.ev === "check" || e.ev === undefined);
     const optimizes = ledger.filter((e) => e.ev === "optimize");
     // Observed shrinkage: a session getting SMALLER between two deep checks is a
@@ -38,14 +41,14 @@ export async function collectDashboardData(proxyPort = 8787) {
             continue;
         perSession.set(c.sid, [...(perSession.get(c.sid) ?? []), c.tok]);
     }
-    let shrinkage = 0;
+    let shrinkage = carried.shrinkage;
     for (const toks of perSession.values()) {
         for (let i = 1; i < toks.length; i++)
             if (toks[i] < toks[i - 1])
                 shrinkage += toks[i - 1] - toks[i];
     }
-    const optimizeSaved = optimizes.reduce((s, e) => s + (e.saved ?? 0), 0);
-    let usdSaved = 0;
+    const optimizeSaved = optimizes.reduce((s, e) => s + (e.saved ?? 0), 0) + carried.optimizeSaved;
+    let usdSaved = carried.optimizeUsd;
     for (const e of optimizes) {
         const pricing = pricingFor(e.model);
         if (pricing && e.saved)
@@ -93,8 +96,8 @@ export async function collectDashboardData(proxyPort = 8787) {
         totals: {
             tokensSaved: optimizeSaved + shrinkage + (proxy?.tokensSaved ?? 0),
             usdSaved: usdSaved + (proxy?.estUsdSaved ?? 0),
-            checks: checks.length,
-            warnings: checks.filter((c) => c.warn).length,
+            checks: checks.length + carried.checks,
+            warnings: checks.filter((c) => c.warn).length + carried.warnings,
             optimizeRuns: optimizes.length,
         },
         daily,

package/dist/diff.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `context-doctor diff <before> <after>` — compare two profiles.
+ *
+ * Optimization currently has to be taken on trust: you run it, a number
+ * changes, and nothing shows what actually moved. This puts two profiles side
+ * by side, so "we cut the context" becomes a claim with evidence — which
+ * categories shrank, which findings were resolved, and what it means in money
+ * and latency.
+ *
+ * Works on any two inputs `analyze` accepts, plus session transcripts, so it
+ * covers before/after an optimization and one session against another.
+ */
+export declare function renderDiff(beforePath: string, afterPath: string, model?: string): string;

package/dist/diff.js

@@ -0,0 +1,92 @@
+/**
+ * `context-doctor diff <before> <after>` — compare two profiles.
+ *
+ * Optimization currently has to be taken on trust: you run it, a number
+ * changes, and nothing shows what actually moved. This puts two profiles side
+ * by side, so "we cut the context" becomes a claim with evidence — which
+ * categories shrank, which findings were resolved, and what it means in money
+ * and latency.
+ *
+ * Works on any two inputs `analyze` accepts, plus session transcripts, so it
+ * covers before/after an optimization and one session against another.
+ */
+import { readFileSync } from "node:fs";
+import { parseConversation } from "./parse.js";
+import { profileConversation } from "./profile.js";
+import { parseSessionFile } from "./session.js";
+import { formatTokens } from "./tokens.js";
+import { formatUsd } from "./pricing.js";
+/** Load either a conversation file or a Claude Code / ChatGPT transcript. */
+function loadProfile(path, model) {
+    if (path.endsWith(".jsonl")) {
+        const session = parseSessionFile(path);
+        return profileConversation(parseConversation(session.conversationJson), model ?? session.model);
+    }
+    return profileConversation(parseConversation(readFileSync(path, "utf8")), model);
+}
+function signed(n) {
+    return n === 0 ? "±0" : `${n > 0 ? "+" : "−"}${formatTokens(Math.abs(n))}`;
+}
+/** A finding is "the same finding" when its id and message positions match. */
+function findingKey(f) {
+    return `${f.id}:${f.messages.join(",")}`;
+}
+export function renderDiff(beforePath, afterPath, model) {
+    const before = loadProfile(beforePath, model);
+    const after = loadProfile(afterPath, model);
+    const lines = [];
+    lines.push("CONTEXT DOCTOR — diff");
+    lines.push("═".repeat(56));
+    lines.push(`before: ${beforePath}`);
+    lines.push(`after:  ${afterPath}`);
+    lines.push("");
+    const delta = after.totalTokens - before.totalTokens;
+    const pct = before.totalTokens > 0 ? (delta / before.totalTokens) * 100 : 0;
+    lines.push(`Total: ${formatTokens(before.totalTokens)} → ${formatTokens(after.totalTokens)} tokens ` +
+        `(${signed(delta)}, ${pct >= 0 ? "+" : ""}${pct.toFixed(1)}%)`);
+    lines.push(`Messages: ${before.messageCount} → ${after.messageCount}`);
+    if (before.cost && after.cost) {
+        const costDelta = after.cost.per1kCallsUsd - before.cost.per1kCallsUsd;
+        const ttftDelta = after.cost.ttftSeconds - before.cost.ttftSeconds;
+        lines.push(`Cost:  ${formatUsd(before.cost.per1kCallsUsd)} → ${formatUsd(after.cost.per1kCallsUsd)} per 1k calls ` +
+            `(${costDelta <= 0 ? "saves " : "costs "}${formatUsd(Math.abs(costDelta))}), ` +
+            `${Math.abs(ttftDelta).toFixed(1)}s ${ttftDelta <= 0 ? "faster" : "slower"} per call`);
+    }
+    lines.push("");
+    // Where the change actually landed.
+    const categories = Object.keys(before.categories).map((key) => ({ label: key, before: before.categories[key], after: after.categories[key] }));
+    const moved = categories.filter((c) => c.before !== c.after);
+    if (moved.length > 0) {
+        lines.push("Where it changed");
+        lines.push("─".repeat(56));
+        for (const c of moved.sort((a, b) => Math.abs(b.after - b.before) - Math.abs(a.after - a.before))) {
+            lines.push(`  ${c.label.padEnd(14)} ${formatTokens(c.before).padStart(7)} → ${formatTokens(c.after).padStart(7)}  ${signed(c.after - c.before)}`);
+        }
+        lines.push("");
+    }
+    // Findings resolved and introduced — the qualitative half of the story.
+    const beforeKeys = new Map(before.findings.map((f) => [findingKey(f), f]));
+    const afterKeys = new Map(after.findings.map((f) => [findingKey(f), f]));
+    const resolved = [...beforeKeys].filter(([k]) => !afterKeys.has(k)).map(([, f]) => f);
+    const introduced = [...afterKeys].filter(([k]) => !beforeKeys.has(k)).map(([, f]) => f);
+    lines.push(`Findings: ${before.findings.length} → ${after.findings.length}`);
+    lines.push("─".repeat(56));
+    for (const f of resolved.slice(0, 5))
+        lines.push(`  ✓ resolved: ${f.message}`);
+    if (resolved.length > 5)
+        lines.push(`  ✓ … and ${resolved.length - 5} more resolved`);
+    for (const f of introduced.slice(0, 5))
+        lines.push(`  ✗ new:      ${f.message}`);
+    if (introduced.length > 5)
+        lines.push(`  ✗ … and ${introduced.length - 5} more introduced`);
+    if (resolved.length === 0 && introduced.length === 0)
+        lines.push("  (no change in findings)");
+    lines.push("");
+    const verdict = delta < 0
+        ? `Net improvement: ${formatTokens(-delta)} tokens removed, ${resolved.length} finding(s) resolved.`
+        : delta > 0
+            ? `Context grew by ${formatTokens(delta)} tokens.`
+            : "No change in total context.";
+    lines.push(verdict);
+    return lines.join("\n");
+}

package/dist/doctor.js

@@ -11,6 +11,7 @@ import { homedir, platform } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { ledgerPath, recordLedger } from "./ledger.js";
+import { loadConfig } from "./config.js";
 function claudeDesktopConfigPath() {
     switch (platform()) {
         case "darwin": return join(homedir(), "Library", "Application Support", "Claude", "claude_desktop_config.json");
@@ -120,6 +121,18 @@ export async function runDoctor() {
     catch {
         checks.push({ label: "Ledger", status: "fail", detail: `cannot write ${ledgerPath()}` });
     }
+    // Project config: a setting that is silently ignored looks exactly like the
+    // feature being broken, so name it here rather than leaving it to be guessed.
+    const loaded = loadConfig(process.cwd());
+    if (loaded.path) {
+        const warnings = loaded.warnings ?? [];
+        checks.push(warnings.length === 0
+            ? { label: "Project config", status: "ok", detail: `${loaded.path} — all settings understood` }
+            : { label: "Project config", status: "fail", detail: `${warnings.length} setting(s) will be ignored:\n` + warnings.map((w) => `    ${w}`).join("\n") });
+    }
+    else {
+        checks.push({ label: "Project config", status: "skip", detail: "no .contextdoctorrc (optional; create one with: context-doctor init <preset>)" });
+    }
     checks.push(await checkMcpHandshake());
     const mark = { ok: "✓", fail: "✗", skip: "–" };
     console.log("CONTEXT DOCTOR — self-check");

package/dist/hook.js

@@ -10,7 +10,9 @@
  * Registered by `context-doctor install` under hooks.UserPromptSubmit in
  * ~/.claude/settings.json; removed by `context-doctor uninstall`.
  */
-import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { join } from "node:path";
 import { recordLedger, statePath } from "./ledger.js";
 import { parseConversation } from "./parse.js";
 import { profileConversation } from "./profile.js";
@@ -43,6 +45,70 @@ const REGROWTH_FACTOR = 1.4;
 function minBytesForWarn(threshold) {
     return threshold * 4;
 }
+/**
+ * State lives in one small file per session, not one shared map.
+ *
+ * The hook runs once per prompt in every Claude Code window, and people keep
+ * several open. With a shared JSON map, concurrent hooks each read the whole
+ * map and wrote it back, so the last writer erased everyone else: measured,
+ * 12 simultaneous sessions left 4 surviving entries. The cost of losing an
+ * entry is a repeated warning the regrowth gate exists to prevent, plus a full
+ * re-parse of a transcript that can be hundreds of megabytes.
+ *
+ * A process that only ever writes its own session's file cannot race another.
+ */
+function stateDir() {
+    return statePath().replace(/\.json$/, "") + ".d";
+}
+function sessionStatePath(sessionId) {
+    // Session ids are usually uuids, but the fallback id is a filesystem path.
+    // Hashing keeps the filename valid whatever the id looks like.
+    return join(stateDir(), createHash("sha1").update(sessionId).digest("hex").slice(0, 16) + ".json");
+}
+function readSessionState(sessionId) {
+    try {
+        const raw = JSON.parse(readFileSync(sessionStatePath(sessionId), "utf8"));
+        if (typeof raw?.t === "number" && typeof raw?.b === "number")
+            return raw;
+    }
+    catch {
+        /* absent or half-written: treat as a first run */
+    }
+    // Migration: entries written by the shared-map versions are still useful.
+    try {
+        const legacy = JSON.parse(readFileSync(statePath(), "utf8"));
+        const entry = legacy[sessionId];
+        if (typeof entry === "number")
+            return { t: entry, b: 0 };
+        if (entry && typeof entry.t === "number")
+            return { t: entry.t, b: entry.b ?? 0 };
+    }
+    catch {
+        /* no legacy file */
+    }
+    return { t: 0, b: 0 };
+}
+/** Keep the directory from growing without bound as sessions come and go. */
+const MAX_STATE_FILES = 200;
+function writeSessionState(sessionId, state) {
+    const dir = stateDir();
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(sessionStatePath(sessionId), JSON.stringify(state));
+    try {
+        const files = readdirSync(dir);
+        if (files.length <= MAX_STATE_FILES)
+            return;
+        const byAge = files
+            .map((f) => ({ f, t: statSync(join(dir, f)).mtimeMs }))
+            .sort((a, b) => b.t - a.t)
+            .slice(MAX_STATE_FILES);
+        for (const { f } of byAge)
+            rmSync(join(dir, f), { force: true });
+    }
+    catch {
+        /* pruning is housekeeping, never worth failing a prompt over */
+    }
+}
 async function readStdin() {
     const chunks = [];
     for await (const chunk of process.stdin)
@@ -68,16 +134,7 @@ export async function runHook() {
         // since the last full parse, nothing new can trigger — exit without the
         // expensive read. Heavy-but-quiet sessions cost one stat + tiny state read.
         const sessionId = input.session_id ?? transcriptPath;
-        let state = {};
-        try {
-            state = JSON.parse(readFileSync(statePath(), "utf8"));
-        }
-        catch {
-            /* first run */
-        }
-        const rawPrev = state[sessionId];
-        // Migrate pre-0.3.5 numeric entries ({tokens only}) to the new shape.
-        const prev = typeof rawPrev === "number" ? { t: rawPrev, b: 0 } : rawPrev ?? { t: 0, b: 0 };
+        const prev = readSessionState(sessionId);
         if (prev.b > 0 && sizeBytes < prev.b * REGROWTH_FACTOR)
             return;
         // Slow path (growth events only): full parse + profile.
@@ -91,9 +148,7 @@ export async function runHook() {
         const liveTokens = parsed.reportedInputTokens ?? profile.totalTokens;
         // Record this parse so the next prompts take fast path 2.
         const shouldWarn = liveTokens >= threshold && liveTokens >= prev.t * REGROWTH_FACTOR;
-        const nextState = { t: shouldWarn ? liveTokens : prev.t, b: sizeBytes };
-        const entries = Object.entries({ ...state, [sessionId]: nextState });
-        writeFileSync(statePath(), JSON.stringify(Object.fromEntries(entries.slice(-100))));
+        writeSessionState(sessionId, { t: shouldWarn ? liveTokens : prev.t, b: sizeBytes });
         recordLedger({ ev: "check", sid: sessionId.slice(0, 12), tok: liveTokens, warn: shouldWarn });
         if (!shouldWarn)
             return;

package/dist/impact.js

@@ -8,7 +8,7 @@
  * session cannot be re-run without it. The report says so instead of inventing
  * a number.
  */
-import { readLedger } from "./ledger.js";
+import { foldTotals, readLedger } from "./ledger.js";
 import { listSessions, parseSessionFile } from "./session.js";
 import { parseConversation } from "./parse.js";
 import { profileConversation } from "./profile.js";
@@ -32,6 +32,9 @@ export async function buildImpactReport(proxyPort = 8787) {
     lines.push("CONTEXT DOCTOR — impact report");
     lines.push("═".repeat(56));
     const ledger = readLedger();
+    // Rotation folds dropped entries into a rollup. Counting it is what keeps
+    // these lifetime totals from going backwards once the cap is hit.
+    const carried = foldTotals(ledger.filter((e) => e.ev === "rollup"));
     const checks = ledger.filter((e) => e.ev === "check" || e.ev === undefined);
     const optimizes = ledger.filter((e) => e.ev === "optimize");
     // Observed per-session reductions: when a session SHRANK between two deep
@@ -55,9 +58,9 @@ export async function buildImpactReport(proxyPort = 8787) {
         }
         reductionBySession.set(sid, reduction);
     }
-    const totalReduction = [...reductionBySession.values()].reduce((a, b) => a + b, 0);
+    const totalReduction = [...reductionBySession.values()].reduce((a, b) => a + b, 0) + carried.shrinkage;
     // Optimize-event savings, split by model family (claude / gpt / other).
-    const optimizeSaved = optimizes.reduce((s, e) => s + (e.saved ?? 0), 0);
+    const optimizeSaved = optimizes.reduce((s, e) => s + (e.saved ?? 0), 0) + carried.optimizeSaved;
     const savedByFamily = new Map();
     let optimizeUsd = 0;
     for (const e of optimizes) {
@@ -71,7 +74,7 @@ export async function buildImpactReport(proxyPort = 8787) {
     // Persisted checkpoints cover proxy runs that have since exited; the live
     // process reports whatever it has not checkpointed yet.
     const proxyEvents = ledger.filter((e) => e.ev === "proxy");
-    const proxyHistoric = proxyEvents.reduce((s, e) => s + (e.saved ?? 0), 0);
+    const proxyHistoric = proxyEvents.reduce((s, e) => s + (e.saved ?? 0), 0) + carried.proxySaved;
     const proxySaved = proxyHistoric + (proxy?.tokensSaved ?? 0);
     // -- Headline: what context-doctor has saved ----------------------------------
     const totalSaved = proxySaved + optimizeSaved + totalReduction;
@@ -100,8 +103,8 @@ export async function buildImpactReport(proxyPort = 8787) {
     lines.push("Hygiene activity (every-prompt hook)");
     lines.push("─".repeat(56));
     if (checks.length > 0) {
-        const warnings = checks.filter((e) => e.warn).length;
-        lines.push(`${checks.length} deep context checks across ${bySession.size} session(s); ${warnings} warning(s) delivered to the model.`);
+        const warnings = checks.filter((e) => e.warn).length + carried.warnings;
+        lines.push(`${checks.length + carried.checks} deep context checks across ${bySession.size} session(s); ${warnings} warning(s) delivered to the model.`);
         lines.push("(Prompt-level fast checks are not logged — they cost ~1ms and leave no trace by design.)");
     }
     else {

package/dist/ledger.d.ts

@@ -8,10 +8,16 @@
  *              (pre-0.3.6 hook entries have no `ev` field; treated as checks)
  *   optimize — an optimization was applied  {ev: "optimize", src: "cli"|"mcp", saved, model?}
  *   proxy    — proxy savings checkpoint      {ev: "proxy", saved, usd?, requests?}
+ *   rollup   — totals folded in on rotation   {ev: "rollup", ...carried sums}
+ *
+ * The ledger is capped, and everything it feeds is a LIFETIME total. Simply
+ * dropping old lines made those totals go backwards — measured: 1,692,000
+ * tokens saved became 501,000 the moment the cap was hit. So rotation folds
+ * what it drops into a single rollup entry instead of discarding it.
  */
 export interface LedgerEntry {
     ts: number;
-    ev?: "check" | "optimize" | "proxy";
+    ev?: "check" | "optimize" | "proxy" | "rollup";
     sid?: string;
     tok?: number;
     warn?: boolean;
@@ -20,7 +26,30 @@ export interface LedgerEntry {
     requests?: number;
     saved?: number;
     model?: string;
+    /** rollup only: sums carried forward from entries rotation removed. */
+    carried?: CarriedTotals;
+}
+/** Everything the reports total up, preserved across ledger rotation. */
+export interface CarriedTotals {
+    optimizeSaved: number;
+    optimizeUsd: number;
+    proxySaved: number;
+    proxyUsd: number;
+    proxyRequests: number;
+    checks: number;
+    warnings: number;
+    /** Session shrinkage observed between consecutive checks. */
+    shrinkage: number;
+    /** Timestamp of the oldest folded entry, so reports can say "since". */
+    since?: number;
 }
+/**
+ * Reduce a set of entries to the totals the reports care about.
+ *
+ * Absorbs existing rollups, so folding stays correct across any number of
+ * rotations rather than only the first.
+ */
+export declare function foldTotals(entries: LedgerEntry[]): CarriedTotals;
 export declare function statePath(): string;
 export declare function ledgerPath(): string;
 export declare function recordLedger(entry: Omit<LedgerEntry, "ts">): void;

package/dist/ledger.js

@@ -8,10 +8,68 @@
  *              (pre-0.3.6 hook entries have no `ev` field; treated as checks)
  *   optimize — an optimization was applied  {ev: "optimize", src: "cli"|"mcp", saved, model?}
  *   proxy    — proxy savings checkpoint      {ev: "proxy", saved, usd?, requests?}
+ *   rollup   — totals folded in on rotation   {ev: "rollup", ...carried sums}
+ *
+ * The ledger is capped, and everything it feeds is a LIFETIME total. Simply
+ * dropping old lines made those totals go backwards — measured: 1,692,000
+ * tokens saved became 501,000 the moment the cap was hit. So rotation folds
+ * what it drops into a single rollup entry instead of discarding it.
  */
 import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
+const EMPTY_CARRIED = {
+    optimizeSaved: 0, optimizeUsd: 0, proxySaved: 0, proxyUsd: 0,
+    proxyRequests: 0, checks: 0, warnings: 0, shrinkage: 0,
+};
+/**
+ * Reduce a set of entries to the totals the reports care about.
+ *
+ * Absorbs existing rollups, so folding stays correct across any number of
+ * rotations rather than only the first.
+ */
+export function foldTotals(entries) {
+    const out = { ...EMPTY_CARRIED };
+    const perSession = new Map();
+    for (const e of entries) {
+        if (e.ev === "rollup" && e.carried) {
+            out.optimizeSaved += e.carried.optimizeSaved;
+            out.optimizeUsd += e.carried.optimizeUsd;
+            out.proxySaved += e.carried.proxySaved;
+            out.proxyUsd += e.carried.proxyUsd;
+            out.proxyRequests += e.carried.proxyRequests;
+            out.checks += e.carried.checks;
+            out.warnings += e.carried.warnings;
+            out.shrinkage += e.carried.shrinkage;
+            if (e.carried.since)
+                out.since = Math.min(out.since ?? e.carried.since, e.carried.since);
+            continue;
+        }
+        out.since = Math.min(out.since ?? e.ts, e.ts);
+        if (e.ev === "optimize") {
+            out.optimizeSaved += e.saved ?? 0;
+            out.optimizeUsd += e.usd ?? 0;
+        }
+        else if (e.ev === "proxy") {
+            out.proxySaved += e.saved ?? 0;
+            out.proxyUsd += e.usd ?? 0;
+            out.proxyRequests += e.requests ?? 0;
+        }
+        else {
+            out.checks++;
+            if (e.warn)
+                out.warnings++;
+            if (e.sid && typeof e.tok === "number")
+                perSession.set(e.sid, [...(perSession.get(e.sid) ?? []), e.tok]);
+        }
+    }
+    for (const toks of perSession.values()) {
+        for (let i = 1; i < toks.length; i++)
+            if (toks[i] < toks[i - 1])
+                out.shrinkage += toks[i - 1] - toks[i];
+    }
+    return out;
+}
 export function statePath() {
     return process.env.CONTEXT_DOCTOR_HOOK_STATE ?? join(homedir(), ".claude", ".context-doctor-hook-state.json");
 }
@@ -24,10 +82,24 @@ export function recordLedger(entry) {
         // Claude-Desktop-only machines have no ~/.claude — create it so their
         // optimize events count in `context-doctor report` too.
         mkdirSync(dirname(path), { recursive: true });
-        // Cap growth: past ~256KB keep the most recent 500 entries.
+        // Cap growth: past ~256KB keep the most recent 500 entries — but fold the
+        // dropped ones into a rollup first, or every lifetime total in the reports
+        // silently shrinks the moment a heavy user crosses the cap.
         if (existsSync(path) && statSync(path).size > 256 * 1024) {
             const lines = readFileSync(path, "utf8").trimEnd().split("\n");
-            writeFileSync(path, lines.slice(-500).join("\n") + "\n");
+            const parse = (line) => {
+                try {
+                    return [JSON.parse(line)];
+                }
+                catch {
+                    return [];
+                }
+            };
+            const kept = lines.slice(-500);
+            const dropped = lines.slice(0, -500).flatMap(parse);
+            const carried = foldTotals(dropped);
+            const rollup = { ts: Date.now(), ev: "rollup", carried };
+            writeFileSync(path, [JSON.stringify(rollup), ...kept].join("\n") + "\n");
         }
         appendFileSync(path, JSON.stringify({ ts: Date.now(), ...entry }) + "\n");
     }

package/dist/mcp.js

@@ -37,7 +37,7 @@ const STRATEGY_IDS = ["dedupe", "trim-tool-results", "trim-tool-calls", "strip-b
  * recommended pattern.
  */
 function createServer() {
-    const server = new McpServer({ name: "context-doctor", version: "0.12.2" }, { instructions: SERVER_INSTRUCTIONS });
+    const server = new McpServer({ name: "context-doctor", version: "0.13.1" }, { instructions: SERVER_INSTRUCTIONS });
     server.tool("profile_context", "Profile an LLM conversation or prompt: token breakdown by category, largest messages, and actionable findings about wasted context (duplicates, oversized tool results, base64 blobs, cache-unfriendly ordering). Accepts OpenAI/Anthropic conversation JSON or raw text. Call this immediately whenever the user asks about token usage, context size, LLM cost, or latency — and proactively offer it once a conversation grows long or accumulates large pasted content.", {
         conversation: z.string().describe("Conversation JSON (OpenAI or Anthropic format, or bare message array) or raw prompt text"),
         model: z.string().optional().describe("Target model name for context-window math, e.g. claude-sonnet-5 or gpt-4o"),

package/dist/optimize.js

@@ -38,6 +38,34 @@ function trimCallArguments(input, maxTokens) {
     }
     return out;
 }
+/**
+ * Where trimming stops — quantized so the prompt cache survives.
+ *
+ * The obvious boundary, `length - keepRecent`, advances by one on every turn.
+ * That rewrites the message that just aged out of the recent window, and since
+ * prompt caches only match a byte-identical prefix, editing anything in the
+ * middle invalidates the cache from that point on. Measured on a 25-turn agent
+ * conversation, the naive boundary invalidated the cached prefix on 24 of 24
+ * turns: paying the 1.25x cache-write price every turn to save a few hundred
+ * tokens, which is a straight loss on any sizeable context.
+ *
+ * Quantizing means the boundary holds still for STEP turns at a time, so the
+ * prefix stays byte-identical in between and the cache is rebuilt once per
+ * STEP turns instead of once per turn. Older content is trimmed slightly later
+ * than it otherwise would be; that is much cheaper than losing the cache.
+ */
+const TRIM_BOUNDARY_STEP = 10;
+function stableCutoff(messageCount, keepRecent) {
+    const raw = messageCount - keepRecent;
+    if (raw <= 0)
+        return 0;
+    // Below one step there is nothing to quantize to except zero, which would
+    // silently disable trimming on every short conversation. Such a conversation
+    // has no long stable prefix worth protecting anyway.
+    if (raw < TRIM_BOUNDARY_STEP)
+        return raw;
+    return Math.floor(raw / TRIM_BOUNDARY_STEP) * TRIM_BOUNDARY_STEP;
+}
 function hash(text) {
     return createHash("sha1").update(text.replace(/\s+/g, " ").trim()).digest("hex");
 }
@@ -154,11 +182,24 @@ export function optimizeConversation(input, options = {}) {
     }
     // -- dedupe: identical content beyond the first occurrence --------------------
     if (opts.strategies.includes("dedupe")) {
+        // The recent tail is what the model is actually answering. Replacing a
+        // message there with "identical to #0" is technically true and practically
+        // awful: through the proxy, a user who pastes the same document twice has
+        // their CURRENT question swapped for a pointer to a message ten turns back,
+        // and just sees a worse answer with no explanation. Older copies are fair
+        // game; the live turn is not.
+        const cutoff = stableCutoff(messages.length, opts.keepRecent);
         const seen = new Map();
         messages.forEach((m, i) => {
             const text = textOf(m.content);
             if (text.length < 300)
                 return;
+            if (i >= cutoff) {
+                // Still record it, so a later duplicate can point back here.
+                if (!seen.has(hash(text)))
+                    seen.set(hash(text), i);
+                return;
+            }
             const h = hash(text);
             const first = seen.get(h);
             if (first === undefined) {
@@ -172,7 +213,7 @@ export function optimizeConversation(input, options = {}) {
     }
     // -- trim-tool-results: shrink stale tool output ------------------------------
     if (opts.strategies.includes("trim-tool-results")) {
-        const cutoff = messages.length - opts.keepRecent;
+        const cutoff = stableCutoff(messages.length, opts.keepRecent);
         messages.forEach((m, i) => {
             if (i >= cutoff || !isToolResultMessage(m))
                 return;
@@ -192,7 +233,7 @@ export function optimizeConversation(input, options = {}) {
     }
     // -- trim-tool-calls: shrink the arguments of calls that already ran ----------
     if (opts.strategies.includes("trim-tool-calls")) {
-        const cutoff = messages.length - opts.keepRecent;
+        const cutoff = stableCutoff(messages.length, opts.keepRecent);
         messages.forEach((m, i) => {
             if (i >= cutoff)
                 return;

package/dist/profile.js

@@ -96,6 +96,54 @@ function jaccard(a, b) {
             inter++;
     return inter / (a.size + b.size - inter);
 }
+/**
+ * Shell commands that pull a file's contents into context. An agent that runs
+ * `cat config.json` has re-read that file just as surely as one that calls a
+ * Read tool — but the call looks like an opaque Bash invocation, so the
+ * repeated-read detector used to score shell-heavy sessions as clean when they
+ * were the worst offenders.
+ *
+ * Deliberately narrow: only commands whose whole purpose is to emit file
+ * contents, and only when the argument looks like a path rather than a flag or
+ * a glob. `grep` and `ls` are excluded — they summarize, they do not dump.
+ */
+const FILE_DUMPING_COMMANDS = /\b(?:cat|bat|head|tail|less|more|nl)\s+((?:-[^\s;|&]+\s+)*)([^\s|;&><'"`]{3,})/g;
+/**
+ * Does this token name a file, or is it the next shell word?
+ *
+ * `head -20; echo done` used to report a file called "echo": the flag pattern
+ * swallowed the separator and the following command became the target. A real
+ * path has a directory separator or an extension; a bare command word has
+ * neither.
+ */
+function looksLikePath(token) {
+    if (/[*?$]/.test(token) || token.startsWith("-"))
+        return false; // glob or flag
+    if (token === "EOF" || token === "<<")
+        return false; // heredoc, which writes
+    if (!/^[\w./~@+-]+$/.test(token))
+        return false;
+    return token.includes("/") || /\.[A-Za-z0-9]{1,8}$/.test(token);
+}
+/** Extract every file path a tool call reads, whether by tool or by shell. */
+function filesReadBy(toolName, toolCallText) {
+    // Explicit read-style tools name their target in a known argument.
+    if (/read|open|cat|view|get_file/i.test(toolName ?? "")) {
+        const match = /"(?:file_path|filePath|path|file)"\s*:\s*"([^"]{3,})"/.exec(toolCallText);
+        if (match)
+            return [match[1]];
+    }
+    if (!/bash|shell|terminal|exec|run_command/i.test(toolName ?? ""))
+        return [];
+    const paths = new Set();
+    FILE_DUMPING_COMMANDS.lastIndex = 0;
+    for (const match of toolCallText.matchAll(FILE_DUMPING_COMMANDS)) {
+        const candidate = match[2].replace(/\\+$/, "");
+        if (looksLikePath(candidate))
+            paths.add(candidate);
+    }
+    return [...paths];
+}
 export function profileConversation(conv, model) {
     const perMessage = conv.messages.map((m) => ({
         msg: m,
@@ -231,13 +279,9 @@ export function profileConversation(conv, model) {
         for (const p of perMessage) {
             if (p.msg.kind !== "tool_call" || !p.msg.toolCallText)
                 continue;
-            if (!/read|open|cat|view|get_file/i.test(p.msg.toolName ?? ""))
-                continue;
-            const match = /"(?:file_path|filePath|path|file)"\s*:\s*"([^"]{3,})"/.exec(p.msg.toolCallText);
-            if (!match)
-                continue;
-            const path = match[1];
-            readsByPath.set(path, [...(readsByPath.get(path) ?? []), p.msg.index]);
+            for (const path of filesReadBy(p.msg.toolName, p.msg.toolCallText)) {
+                readsByPath.set(path, [...(readsByPath.get(path) ?? []), p.msg.index]);
+            }
         }
         for (const [path, indexes] of readsByPath) {
             if (indexes.length < 3)

package/dist/session.d.ts

@@ -14,6 +14,13 @@ export interface SessionInfo {
     modifiedAt: Date;
     sizeBytes: number;
 }
+/** One API-reported input size, positioned in the message array. */
+export interface UsageSample {
+    /** Index into the live `messages` array of the assistant message reporting it. */
+    index: number;
+    /** input + cache-read + cache-creation tokens for that request. */
+    input: number;
+}
 export interface ParsedSession {
     /**
      * The real input size of the most recent request, as reported by the API
@@ -30,6 +37,15 @@ export interface ParsedSession {
      * was compacted away so the difference can be shown rather than hidden.
      */
     compactedAway?: number;
+    /**
+     * Every API-reported input size in the transcript, tagged with its position
+     * in the live message array. Consecutive samples are what make key-free
+     * accuracy measurement possible: the harness's system prompt and tool
+     * schemas are constant between two calls, so the DIFFERENCE between two
+     * reported figures is the cost of the messages in between — directly
+     * comparable to what the heuristic estimates for those same messages.
+     */
+    usageSamples?: UsageSample[];
     /** Conversation JSON string in Anthropic-ish format, ready for parseConversation(). */
     conversationJson: string;
     title?: string;

package/dist/session.js

@@ -142,6 +142,8 @@ export function parseSessionFile(path) {
     let lastCompactIndex = -1;
     /** Newest API-reported input size, if the transcript carries usage. */
     let reportedInputTokens;
+    /** Every reported size, positioned — the basis for `context-doctor accuracy`. */
+    const usageSamples = [];
     forEachLine(path, (line) => {
         if (!line.trim())
             return;
@@ -169,8 +171,10 @@ export function parseSessionFile(path) {
         const usage = message.usage;
         if (entry.type === "assistant" && usage) {
             const total = (usage.input_tokens ?? 0) + (usage.cache_read_input_tokens ?? 0) + (usage.cache_creation_input_tokens ?? 0);
-            if (total > 0)
+            if (total > 0) {
                 reportedInputTokens = total;
+                usageSamples.push({ index: messages.length, input: total });
+            }
         }
         if (entry.isCompactSummary)
             lastCompactIndex = messages.length;
@@ -188,6 +192,11 @@ export function parseSessionFile(path) {
         messageCount: live.length,
         compactedAway,
         reportedInputTokens,
+        // Samples before the compaction boundary describe a context that no longer
+        // exists; re-base the rest onto the live array.
+        usageSamples: usageSamples
+            .filter((u) => u.index >= compactedAway)
+            .map((u) => ({ index: u.index - compactedAway, input: u.input })),
         path,
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "context-doctor",
-  "version": "0.12.2",
+  "version": "0.13.1",
   "description": "Profile and optimize LLM context windows. See what's eating your tokens and fix it — works with Claude, GPT, Gemini, and any MCP-capable AI app.",
   "keywords": [
     "llm",
@@ -42,7 +42,7 @@
     "build": "tsc && node -e \"const fs=require('fs');['dist/cli.js','dist/mcp.js'].forEach(f=>fs.chmodSync(f,0o755))\"",
     "prepublishOnly": "npm run build",
     "dev": "tsc --watch",
-    "test": "npm run build && node --test dist/test/smoke.test.js dist/test/proxy.test.js dist/test/proxy-abort.test.js dist/test/hook.test.js dist/test/mcp-http.test.js dist/test/doctor.test.js dist/test/watch.test.js dist/test/chatgpt-export.test.js dist/test/config.test.js dist/test/dashboard.test.js dist/test/cursor.test.js dist/test/cache.test.js dist/test/session.test.js"
+    "test": "npm run build && node --test dist/test/smoke.test.js dist/test/proxy.test.js dist/test/proxy-abort.test.js dist/test/hook.test.js dist/test/mcp-http.test.js dist/test/doctor.test.js dist/test/watch.test.js dist/test/chatgpt-export.test.js dist/test/config.test.js dist/test/dashboard.test.js dist/test/cursor.test.js dist/test/cache.test.js dist/test/session.test.js dist/test/accuracy.test.js dist/test/cache-stability.test.js dist/test/ledger.test.js"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",