context-doctor 0.12.1 → 0.13.0

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

@@ -61,3 +61,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

@@ -71,3 +71,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/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/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.1" }, { instructions: SERVER_INSTRUCTIONS });
+    const server = new McpServer({ name: "context-doctor", version: "0.13.0" }, { 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");
 }
@@ -127,6 +155,14 @@ export function optimizeConversation(input, options = {}) {
     if (!Array.isArray(messages)) {
         throw new Error("No `messages` array found in input");
     }
+    // Null / non-object entries occur in truncated and hand-edited files; every
+    // strategy below would throw on them. Drop them IN PLACE rather than working
+    // on a copy — prune-history splices this same array, and the returned
+    // conversation is the caller's original object.
+    for (let i = messages.length - 1; i >= 0; i--) {
+        if (!messages[i] || typeof messages[i] !== "object")
+            messages.splice(i, 1);
+    }
     const tokensBefore = messages.reduce((s, m) => s + estimateTokens(textOf(m.content)), 0);
     const applied = [];
     // -- strip-base64: replace inline blobs with a placeholder --------------------
@@ -164,7 +200,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;
@@ -184,7 +220,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/parse.js

@@ -62,7 +62,10 @@ function flattenContent(content) {
     }
     return { text, hasBinary, toolName, kind, toolCallText: toolCallText || undefined };
 }
-function normalizeMessage(raw, index) {
+function normalizeMessage(rawInput, index) {
+    // A null or non-object entry appears in truncated and hand-edited files.
+    // Treat it as an empty message rather than throwing a stack at the user.
+    const raw = rawInput && typeof rawInput === "object" ? rawInput : {};
     const role = String(raw.role ?? "user");
     const flat = flattenContent(raw.content);
     let kind = flat.kind ?? (["system", "user", "assistant"].includes(role) ? role : "other");
@@ -73,8 +76,10 @@ function normalizeMessage(raw, index) {
     if (role === "tool") {
         kind = "tool_result";
     }
-    const toolCalls = raw.tool_calls;
-    if (Array.isArray(toolCalls) && toolCalls.length > 0) {
+    const rawToolCalls = raw.tool_calls;
+    // Entries can be null or malformed in hand-edited or truncated exports.
+    const toolCalls = Array.isArray(rawToolCalls) ? rawToolCalls.filter((tc) => tc && typeof tc === "object") : undefined;
+    if (toolCalls && toolCalls.length > 0) {
         kind = "tool_call";
         toolName = toolCalls[0]?.function?.name ?? toolCalls[0]?.name;
         const calls = toolCalls
@@ -118,7 +123,12 @@ export function parseConversation(input) {
         };
     }
     const obj = data;
-    const rawMessages = obj.messages ?? [];
+    const rawField = obj.messages;
+    const rawMessages = Array.isArray(rawField)
+        ? rawField
+        : [];
+    // `messages` present but not an array is a malformed file, not an empty chat.
+    const malformedMessages = rawField != null && !Array.isArray(rawField);
     const messages = [];
     // Anthropic keeps the system prompt outside the messages array.
     if (obj.system != null) {
@@ -127,9 +137,11 @@ export function parseConversation(input) {
     }
     messages.push(...rawMessages.map((m, i) => normalizeMessage(m, i)));
     const isAnthropic = obj.system != null ||
-        rawMessages.some((m) => Array.isArray(m.content) && m.content.some((b) => b?.type === "tool_use" || b?.type === "tool_result"));
-    const parseWarning = messages.length === 0
-        ? "This JSON has no `messages` array (and no `system`) — it does not look like a conversation. Expected {\"messages\":[{\"role\":…,\"content\":…}]}."
-        : undefined;
+        rawMessages.some((m) => Array.isArray(m?.content) && m.content.some((b) => b?.type === "tool_use" || b?.type === "tool_result"));
+    const parseWarning = malformedMessages
+        ? `\`messages\` is a ${typeof rawField}, not an array — this file is malformed.`
+        : messages.length === 0
+            ? "This JSON has no `messages` array (and no `system`) — it does not look like a conversation. Expected {\"messages\":[{\"role\":…,\"content\":…}]}."
+            : undefined;
     return { sourceFormat: isAnthropic ? "anthropic" : "openai", parseWarning, messages };
 }

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.1",
+  "version": "0.13.0",
   "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/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"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",