context-doctor 0.9.0 → 0.11.0

package/README.md

@@ -88,10 +88,11 @@ Practical upshot: a developer who only wants cheaper, faster API calls never tou
 | Command | What it does |
 |---|---|
 | `context-doctor install` / `uninstall` | Wire (or remove) everything: MCP for Claude Desktop/Code/Cursor, the Agent Skill, the every-prompt hook |
-| `context-doctor analyze <file>` | Profile a conversation: token breakdown, findings, cost + latency estimates |
+| `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; `--strategy prune-history` for consented lossy compaction |
-| `context-doctor session [file]` | Profile a Claude Code session transcript (defaults to your most recent; `--list` to browse) — also reads ChatGPT data exports (`conversations.json`) |
-| `context-doctor report` | Machine-wide impact report: exact proxy savings, hook activity, recoverable waste in recent sessions |
+| `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 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) |
 | `context-doctor watch [file]` | Live monitor of a growing session/agent trace: token/cost line per change, findings as they appear |
 | `context-doctor doctor` | Self-check the whole installation — one pasteable ✓/✗ diagnosis with fixes |
@@ -245,6 +246,8 @@ const { conversation, tokensBefore, tokensAfter } = optimizeConversation(chatJso
 - **Oversized tool results** — the #1 context killer in agent loops
 - **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
+- **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
 - **Long history** past the point where models track the middle
@@ -296,6 +299,36 @@ Drop a `.contextdoctorrc` in a project (or your home directory) and context-doct
 
 The nearest file wins (walking up from the working directory, then `~`). `analyze` and `session` print a budget verdict, the every-prompt hook uses `maxTokens` as its warning threshold and names the breach to the model, and `optimize`/`proxy` pick up the defaults when you do not pass flags.
 
+## Prompt-cache economics (Claude Code sessions)
+
+Caching is the largest lever on LLM cost, and transcripts record exactly how it went — so `session` reports it as fact rather than estimate:
+
+```
+Prompt cache: 95.6% of input served from cache across 1117 requests
+  read 558.6M · written 25.5M · uncached 2k
+  input cost $438.88 — caching saved $2481.89 against $2920.76 uncached (list prices)
+```
+
+A cache read bills at ~10% of input while a write bills at ~125%, so a session that keeps invalidating its prefix can cost *more* than one with no caching at all. context-doctor warns on the two failure modes: a **low hit rate** (something early in the prompt changes every request) and **cache churn** (writes rivalling reads).
+
+## Enforce a budget in CI
+
+```bash
+npx context-doctor analyze conversation.json --fail-over-budget
+```
+
+Exits 1 when the `.contextdoctorrc` budget is breached, so a pull request can be gated on context size the same way it is gated on tests.
+
+## Sharing a profile safely
+
+A profile quotes message previews and file paths, so pasting one into an issue pastes fragments of real work. `--redact` keeps every number and the finding structure but replaces content with `[redacted]` and masks paths:
+
+```bash
+npx context-doctor session --redact
+```
+
+`context-doctor doctor` is safe to paste as-is: it reports integration status, never conversation content.
+
 ## Performance: what context-doctor itself costs
 
 A tool that promises speed must be near-free. Measured overhead per touchpoint:
@@ -306,6 +339,7 @@ A tool that promises speed must be near-free. Measured overhead per touchpoint:
 | MCP server | Spawned once per app session | Tools run only when called; standing instructions cost **~110 tokens per conversation** — deliberately terse |
 | Proxy | Per API request | ~1–3ms of CPU (parse → optimize → re-serialize) against typical model latencies of hundreds of ms; responses stream through chunk-by-chunk, never buffered |
 | Skill | Loads only when relevant | ~1k tokens while active; its always-present description is ~60 tokens |
+| Profiling a session | On demand, and on hook growth events | ~160ms for an 8.5MB / 1,855-message transcript (near-duplicate pairs that cannot clear the similarity bar are skipped without comparison) |
 | CLI / library | Only when you run it | Not in any hot path |
 
 Net effect is strongly negative overhead: the tokens these touchpoints save on every subsequent call dwarf what they cost.
@@ -344,6 +378,10 @@ Known gotcha: if `npm publish` fails with **`404 Not Found - PUT …/context-doc
 
 Also keep the MCP server version in `src/mcp.ts` in sync with `package.json`, and remember `dist/` is committed — run `npm run build` before committing so the CI dist-sync check passes.
 
+## Contributing
+
+Issues and PRs welcome — see [CONTRIBUTING.md](./CONTRIBUTING.md) for the six rules that keep this tool trustworthy (no API keys, nothing leaves the machine, no silent data loss, measurements not guesses, the hot path stays cheap, tests with every change) and a list of good first issues. What is planned next lives in [ROADMAP.md](./ROADMAP.md).
+
 ## License
 
 MIT © [gAI Ventures](https://gai.ventures)

package/dist/cache.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Prompt-cache analysis for Claude Code sessions.
+ *
+ * Transcripts record what the API actually charged per request — including
+ * cache reads and cache writes — so cache behaviour can be reported as fact
+ * rather than estimated. This is usually the largest single lever on cost:
+ * a cached read bills at ~10% of input, while a cache write bills at ~125%,
+ * so a session that keeps invalidating its prefix pays more than one with no
+ * caching at all.
+ */
+export interface CacheUsage {
+    requests: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    uncachedTokens: number;
+    /** Share of input tokens served from cache (0-1). */
+    hitRate: number;
+    model?: string;
+    /** What the input actually cost, at list prices. */
+    paidUsd?: number;
+    /** What the same input would have cost with no caching at all. */
+    uncachedUsd?: number;
+    /** paidUsd vs uncachedUsd — positive means caching is paying off. */
+    savedUsd?: number;
+    /** USD spent on cache writes; high values mean the prefix keeps changing. */
+    writeUsd?: number;
+}
+export declare function analyzeCacheUsage(transcriptPath: string): CacheUsage | null;
+/** One-paragraph verdict for humans, or null when there is nothing to say. */
+export declare function renderCacheReport(usage: CacheUsage | null): string | null;

package/dist/cache.js

@@ -0,0 +1,97 @@
+/**
+ * Prompt-cache analysis for Claude Code sessions.
+ *
+ * Transcripts record what the API actually charged per request — including
+ * cache reads and cache writes — so cache behaviour can be reported as fact
+ * rather than estimated. This is usually the largest single lever on cost:
+ * a cached read bills at ~10% of input, while a cache write bills at ~125%,
+ * so a session that keeps invalidating its prefix pays more than one with no
+ * caching at all.
+ */
+import { readFileSync } from "node:fs";
+import { pricingFor } from "./pricing.js";
+/** Cache pricing multipliers relative to the base input rate. */
+const CACHE_WRITE_MULTIPLIER = 1.25;
+export function analyzeCacheUsage(transcriptPath) {
+    let raw;
+    try {
+        raw = readFileSync(transcriptPath, "utf8");
+    }
+    catch {
+        return null;
+    }
+    let requests = 0;
+    let cacheReadTokens = 0;
+    let cacheWriteTokens = 0;
+    let uncachedTokens = 0;
+    let model;
+    for (const line of raw.split("\n")) {
+        if (!line.trim())
+            continue;
+        let entry;
+        try {
+            entry = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (entry.type !== "assistant" || !entry.message)
+            continue;
+        const usage = entry.message.usage;
+        if (!usage)
+            continue;
+        requests++;
+        cacheReadTokens += usage.cache_read_input_tokens ?? 0;
+        cacheWriteTokens += usage.cache_creation_input_tokens ?? 0;
+        uncachedTokens += usage.input_tokens ?? 0;
+        if (typeof entry.message.model === "string")
+            model = entry.message.model;
+    }
+    if (requests === 0)
+        return null;
+    const totalInput = cacheReadTokens + cacheWriteTokens + uncachedTokens;
+    const usage = {
+        requests,
+        cacheReadTokens,
+        cacheWriteTokens,
+        uncachedTokens,
+        hitRate: totalInput > 0 ? cacheReadTokens / totalInput : 0,
+        model,
+    };
+    const pricing = pricingFor(model);
+    if (pricing) {
+        const perM = (tokens, rate) => (tokens / 1_000_000) * rate;
+        const readUsd = perM(cacheReadTokens, pricing.cacheReadPerM);
+        const writeUsd = perM(cacheWriteTokens, pricing.inputPerM * CACHE_WRITE_MULTIPLIER);
+        const freshUsd = perM(uncachedTokens, pricing.inputPerM);
+        usage.paidUsd = readUsd + writeUsd + freshUsd;
+        usage.uncachedUsd = perM(totalInput, pricing.inputPerM);
+        usage.savedUsd = usage.uncachedUsd - usage.paidUsd;
+        usage.writeUsd = writeUsd;
+    }
+    return usage;
+}
+/** One-paragraph verdict for humans, or null when there is nothing to say. */
+export function renderCacheReport(usage) {
+    if (!usage)
+        return null;
+    const pct = (usage.hitRate * 100).toFixed(1);
+    const lines = [];
+    const fmt = (n) => (n >= 1 ? `$${n.toFixed(2)}` : `$${n.toFixed(3)}`);
+    const tok = (n) => n >= 1e6 ? `${(n / 1e6).toFixed(1)}M` : n >= 1e3 ? `${Math.round(n / 1e3)}k` : String(n);
+    lines.push(`Prompt cache: ${pct}% of input served from cache across ${usage.requests} requests`);
+    lines.push(`  read ${tok(usage.cacheReadTokens)} · written ${tok(usage.cacheWriteTokens)} · uncached ${tok(usage.uncachedTokens)}`);
+    if (usage.paidUsd !== undefined && usage.uncachedUsd !== undefined && usage.savedUsd !== undefined) {
+        lines.push(`  input cost ${fmt(usage.paidUsd)} — caching saved ${fmt(usage.savedUsd)} against ${fmt(usage.uncachedUsd)} uncached (list prices)`);
+    }
+    // A cache write costs 1.25x input while a read costs 0.1x, so writes that
+    // rival reads mean the prefix keeps changing and caching is losing money.
+    const writeShare = usage.cacheReadTokens > 0 ? usage.cacheWriteTokens / usage.cacheReadTokens : Infinity;
+    if (usage.hitRate < 0.5 && usage.requests > 5) {
+        lines.push("  ⚠ Low hit rate: something early in the prompt changes between requests. Keep the system prompt, tool list and reference docs byte-stable and put volatile content last.");
+    }
+    else if (writeShare > 0.5) {
+        lines.push("  ⚠ Cache churn: writes are large relative to reads, and a write costs 1.25x input against 0.1x for a read. The cached prefix is being rebuilt often.");
+    }
+    return lines.join("\n");
+}

package/dist/cli.js

@@ -26,6 +26,7 @@ import { exactTokenCount } from "./exact.js";
 import { checkBudget, loadConfig } from "./config.js";
 import { startDashboard } from "./dashboard.js";
 import { listCursorChats, parseCursorChat } from "./cursor.js";
+import { analyzeCacheUsage, renderCacheReport } from "./cache.js";
 const HELP = `context-doctor — profile and optimize LLM context windows
 
 Usage:
@@ -63,7 +64,11 @@ Options:
   --model <name>          Model name for window-size math (e.g. claude-sonnet-5, gpt-4o)
   --exact                 (analyze) Add an exact token count: Anthropic count-tokens API for
                           Claude models (needs ANTHROPIC_API_KEY), tiktoken for GPT (if installed)
+  --redact                Mask message previews and file paths in the report, so it can be
+                          shared in a bug report without leaking conversation content
   --json                  Machine-readable output
+  --fail-over-budget      (analyze/session) Exit 1 when the .contextdoctorrc budget is
+                          exceeded — lets CI gate a pull request on context size
   --out <file>            (optimize) Write result to file instead of stdout
   --strategy <id>         (optimize) Strategy to run; repeatable.
                           Available: dedupe, trim-tool-results, strip-base64, prune-history
@@ -86,7 +91,7 @@ Examples:
           export OPENAI_BASE_URL=http://localhost:8787/v1
 `;
 function parseArgs(argv) {
-    const args = { json: false, strategies: [], list: false, exact: false };
+    const args = { json: false, strategies: [], list: false, exact: false, redact: false, failOverBudget: false };
     const positional = [];
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
@@ -104,6 +109,12 @@ function parseArgs(argv) {
             case "--exact":
                 args.exact = true;
                 break;
+            case "--redact":
+                args.redact = true;
+                break;
+            case "--fail-over-budget":
+                args.failOverBudget = true;
+                break;
             case "--model":
                 args.model = argv[++i];
                 break;
@@ -148,7 +159,7 @@ function parseArgs(argv) {
 function printBudgetStatus(profile, loaded) {
     const budget = loaded.config.budget;
     if (!budget || !loaded.path)
-        return;
+        return false;
     const verdict = checkBudget(budget, profile);
     console.log("");
     if (verdict.overBudget) {
@@ -159,6 +170,14 @@ function printBudgetStatus(profile, loaded) {
     else {
         console.log(`Within budget (${loaded.path}).`);
     }
+    return verdict.overBudget;
+}
+/** Exit 1 when the caller asked CI to fail on a breach. */
+function applyBudgetGate(overBudget, failOverBudget) {
+    if (overBudget && failOverBudget) {
+        console.error("context-doctor: over budget (--fail-over-budget)");
+        process.exitCode = 1;
+    }
 }
 function readInput(file) {
     if (file === "-")
@@ -214,7 +233,7 @@ function main() {
         }
         else {
             console.log(`Cursor chat: ${chat.title ?? "(untitled)"}\nId:          ${chat.composerId}\n`);
-            console.log(renderProfile(profile));
+            console.log(renderProfile(profile, { redact: args.redact }));
             if (parsed.reportedInputTokens) {
                 console.log("");
                 console.log(`Measured context (reported by the API on the last request): ${parsed.reportedInputTokens} tokens.\n` +
@@ -261,7 +280,7 @@ function main() {
                 console.log(`Note:    ${parsed.compactedAway} earlier message(s) were compacted away and are NOT counted below — this is the live context the model still sees.`);
             }
             console.log("");
-            console.log(renderProfile(profile));
+            console.log(renderProfile(profile, { redact: args.redact }));
             if (parsed.reportedInputTokens) {
                 console.log("");
                 console.log(`Measured context (reported by the API on the last request): ${parsed.reportedInputTokens} tokens.\n` +
@@ -269,7 +288,12 @@ function main() {
                     "transcript does not record — so it is larger than the breakdown above, which covers\n" +
                     "conversation messages only. Findings and savings apply to the messages.");
             }
-            printBudgetStatus(profile, loadConfig(process.cwd(), (m) => console.error(`context-doctor: ${m}`)));
+            const cache = renderCacheReport(analyzeCacheUsage(path));
+            if (cache) {
+                console.log("");
+                console.log(cache);
+            }
+            applyBudgetGate(printBudgetStatus(profile, loadConfig(process.cwd(), (m) => console.error(`context-doctor: ${m}`))), args.failOverBudget);
         }
         return;
     }
@@ -320,9 +344,11 @@ function main() {
     if (args.command === "analyze") {
         const loaded = loadConfig(process.cwd(), (m) => console.error(`context-doctor: ${m}`));
         const profile = profileConversation(parseConversation(input), args.model ?? loaded.config.model);
-        console.log(args.json ? JSON.stringify(profile, null, 2) : renderProfile(profile));
+        console.log(args.json ? JSON.stringify(profile, null, 2) : renderProfile(profile, { redact: args.redact }));
         if (!args.json)
-            printBudgetStatus(profile, loaded);
+            applyBudgetGate(printBudgetStatus(profile, loaded), args.failOverBudget);
+        else
+            applyBudgetGate(checkBudget(loaded.config.budget, profile).overBudget, args.failOverBudget);
         if (args.exact) {
             void exactTokenCount(input, args.model).then((exact) => {
                 if (exact.tokens !== undefined) {

package/dist/impact.js

@@ -68,17 +68,24 @@ export async function buildImpactReport(proxyPort = 8787) {
             optimizeUsd += inputCostUsd(e.saved, pricing);
     }
     const proxy = await fetchProxyStats(proxyPort);
-    const proxySaved = proxy?.tokensSaved ?? 0;
+    // 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 proxySaved = proxyHistoric + (proxy?.tokensSaved ?? 0);
     // -- Headline: what context-doctor has saved ----------------------------------
     const totalSaved = proxySaved + optimizeSaved + totalReduction;
     lines.push("Tokens context-doctor saved (measured)");
     lines.push("─".repeat(56));
     lines.push(`TOTAL: ~${formatTokens(totalSaved)} tokens`);
     if (proxy) {
-        lines.push(`  · proxy (exact, current run): ${formatTokens(proxySaved)} across ${proxy.optimizedRequests}/${proxy.requests} requests ≈ ${formatUsd(proxy.estUsdSaved)}`);
+        lines.push(`  · proxy (exact): ${formatTokens(proxySaved)} — ${formatTokens(proxyHistoric)} from earlier runs, ` +
+            `${formatTokens(proxy.tokensSaved)} live across ${proxy.optimizedRequests}/${proxy.requests} requests ≈ ${formatUsd(proxy.estUsdSaved)}`);
     }
     else {
-        lines.push(`  · proxy: not running on :${proxyPort} (its exact savings appear here while it runs)`);
+        lines.push(proxyHistoric > 0
+            ? `  · proxy (exact, from ${proxyEvents.length} earlier run checkpoint(s)): ${formatTokens(proxyHistoric)} — not running now`
+            : `  · proxy: not running on :${proxyPort} (its exact savings appear here once it runs)`);
     }
     const familyNote = [...savedByFamily.entries()]
         .filter(([, v]) => v > 0)

package/dist/ledger.d.ts

@@ -7,14 +7,17 @@
  *   check    — hook deep-parsed a session   {ev?: undefined|"check", sid, tok, warn}
  *              (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?}
  */
 export interface LedgerEntry {
     ts: number;
-    ev?: "check" | "optimize";
+    ev?: "check" | "optimize" | "proxy";
     sid?: string;
     tok?: number;
     warn?: boolean;
-    src?: "cli" | "mcp";
+    src?: "cli" | "mcp" | "proxy";
+    usd?: number;
+    requests?: number;
     saved?: number;
     model?: string;
 }

package/dist/ledger.js

@@ -7,6 +7,7 @@
  *   check    — hook deep-parsed a session   {ev?: undefined|"check", sid, tok, warn}
  *              (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?}
  */
 import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";

package/dist/mcp.js

@@ -37,7 +37,7 @@ const STRATEGY_IDS = ["dedupe", "trim-tool-results", "strip-base64", "prune-hist
  * recommended pattern.
  */
 function createServer() {
-    const server = new McpServer({ name: "context-doctor", version: "0.9.0" }, { instructions: SERVER_INSTRUCTIONS });
+    const server = new McpServer({ name: "context-doctor", version: "0.11.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/profile.d.ts

@@ -12,7 +12,7 @@ export interface MessageProfile {
     preview: string;
     toolName?: string;
 }
-export type FindingId = "large_tool_result" | "duplicate_content" | "near_duplicate" | "repeated_tool_call" | "base64_blob" | "long_history" | "large_system_prompt" | "cache_ordering" | "near_window_limit";
+export type FindingId = "large_tool_result" | "duplicate_content" | "near_duplicate" | "repeated_tool_call" | "repeated_file_read" | "retained_error_output" | "base64_blob" | "long_history" | "large_system_prompt" | "cache_ordering" | "near_window_limit";
 export interface Finding {
     id: FindingId;
     severity: "info" | "warn" | "high";

package/dist/profile.js

@@ -84,6 +84,8 @@ function sampledShingles(text) {
     }
     return out;
 }
+/** Similarity at or above which two messages count as near-duplicates. */
+const SIMILARITY_THRESHOLD = 0.6;
 function jaccard(a, b) {
     if (a.size === 0 || b.size === 0)
         return 0;
@@ -149,6 +151,11 @@ export function profileConversation(conv, model) {
             .sort((a, b) => b.tokens - a.tokens)
             .slice(0, 150);
         const shingleSets = candidates.map((p) => sampledShingles(p.msg.text));
+        // Jaccard has a hard ceiling of |smaller| / |larger|: two shingle sets of
+        // very different sizes CANNOT reach the threshold, so those pairs are
+        // skipped without intersecting them. Exact, not heuristic — it changes
+        // runtime, never results.
+        const sizes = shingleSets.map((set) => set.size);
         const exactDup = new Set(findings.filter((f) => f.id === "duplicate_content").flatMap((f) => f.messages));
         for (let i = 0; i < candidates.length; i++) {
             for (let j = i + 1; j < candidates.length; j++) {
@@ -156,8 +163,12 @@ export function profileConversation(conv, model) {
                 const b = candidates[j];
                 if (exactDup.has(a.msg.index) && exactDup.has(b.msg.index))
                     continue; // already flagged exactly
+                const small = Math.min(sizes[i], sizes[j]);
+                const large = Math.max(sizes[i], sizes[j]);
+                if (large === 0 || small / large < SIMILARITY_THRESHOLD)
+                    continue; // cannot clear the bar
                 const sim = jaccard(shingleSets[i], shingleSets[j]);
-                if (sim >= 0.6) {
+                if (sim >= SIMILARITY_THRESHOLD) {
                     const smaller = Math.min(a.tokens, b.tokens);
                     const [first, second] = a.msg.index <= b.msg.index ? [a, b] : [b, a];
                     findings.push({
@@ -194,6 +205,58 @@ export function profileConversation(conv, model) {
             });
         }
     }
+    // -- Same file read again and again -----------------------------------------
+    // The dominant waste in agent loops: a file re-read because its earlier
+    // contents scrolled out of attention, leaving several full copies in context.
+    {
+        const readsByPath = new Map();
+        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, indexes] of readsByPath) {
+            if (indexes.length < 3)
+                continue;
+            // Each re-read pulls the file in again; all but the last are recoverable.
+            const resultTokens = perMessage
+                .filter((p) => p.msg.kind === "tool_result" && indexes.some((i) => p.msg.index === i + 1))
+                .reduce((sum, p) => sum + p.tokens, 0);
+            const savings = Math.round((resultTokens * (indexes.length - 1)) / indexes.length);
+            findings.push({
+                id: "repeated_file_read",
+                severity: savings > 4000 ? "high" : "warn",
+                estSavings: savings,
+                message: `${path.split("/").pop()} was read ${indexes.length} times (messages #${indexes.join(", #")}), keeping ${indexes.length} copies in context.`,
+                suggestion: "Re-read a file only after it changes; otherwise refer back to the copy already in context.",
+                messages: indexes,
+            });
+        }
+    }
+    // -- Failed tool output kept verbatim ---------------------------------------
+    // Stack traces and command failures are read once and never again, yet they
+    // are often the largest blocks in an agent transcript.
+    for (const p of perMessage) {
+        if (p.msg.kind !== "tool_result" || p.tokens < 500)
+            continue;
+        const looksFailed = /Traceback \(most recent call last\)|command not found|npm error|ERR!|\bexit code [1-9]|Exception in thread|FAILED|error TS\d+/i.test(p.msg.text);
+        if (!looksFailed)
+            continue;
+        findings.push({
+            id: "retained_error_output",
+            severity: "warn",
+            estSavings: Math.round(p.tokens * 0.85),
+            message: `Message #${p.msg.index} holds ~${p.tokens} tokens of failed tool output (errors, stack trace or non-zero exit).`,
+            suggestion: "Keep the one line that identifies the failure and drop the rest — a full trace has no value once the fix is understood.",
+            messages: [p.msg.index],
+        });
+    }
     // -- Base64 / binary blobs ---------------------------------------------------
     for (const p of perMessage) {
         if (BASE64_RE.test(p.msg.text)) {

package/dist/proxy.js

@@ -15,6 +15,7 @@ import http from "node:http";
 import { optimizeConversation } from "./optimize.js";
 import { formatTokens } from "./tokens.js";
 import { formatUsd, inputCostUsd, pricingFor } from "./pricing.js";
+import { recordLedger } from "./ledger.js";
 /** Connection-level headers that must not be forwarded. */
 const SKIP_REQUEST_HEADERS = new Set(["host", "content-length", "connection", "transfer-encoding", "accept-encoding", "expect"]);
 const SKIP_RESPONSE_HEADERS = new Set(["content-length", "content-encoding", "transfer-encoding", "connection"]);
@@ -208,6 +209,36 @@ export function startProxy(opts = {}) {
             res.end(JSON.stringify({ error: `context-doctor proxy: ${e.message}` }));
         }
     });
+    // Savings live in memory, so a restart would erase the record the dashboard
+    // and report draw on. Checkpoint the delta to the ledger periodically and on
+    // shutdown, so the history survives the process.
+    let checkpointedTokens = 0;
+    let checkpointedUsd = 0;
+    let checkpointedRequests = 0;
+    const checkpoint = () => {
+        const savedDelta = stats.tokensSaved - checkpointedTokens;
+        if (savedDelta <= 0)
+            return;
+        recordLedger({
+            ev: "proxy",
+            src: "proxy",
+            saved: savedDelta,
+            usd: Number((stats.estUsdSaved - checkpointedUsd).toFixed(6)),
+            requests: stats.optimizedRequests - checkpointedRequests,
+        });
+        checkpointedTokens = stats.tokensSaved;
+        checkpointedUsd = stats.estUsdSaved;
+        checkpointedRequests = stats.optimizedRequests;
+    };
+    const checkpointTimer = setInterval(checkpoint, 60_000);
+    checkpointTimer.unref?.(); // never hold the process open on our account
+    for (const signal of ["SIGINT", "SIGTERM"]) {
+        process.once(signal, () => {
+            checkpoint();
+            process.exit(0);
+        });
+    }
+    server.on("close", checkpoint);
     const host = opts.host ?? "127.0.0.1";
     server.listen(port, host, () => {
         console.error(`context-doctor proxy listening on http://${host}:${port}`);

package/dist/report.d.ts

@@ -4,4 +4,12 @@
  * anywhere (terminals, issues, chat).
  */
 import { ContextProfile } from "./profile.js";
-export declare function renderProfile(profile: ContextProfile): string;
+export interface RenderOptions {
+    /**
+     * Replace anything quoted from the conversation with a placeholder, so a
+     * profile can be pasted into a bug report without leaking content. Numbers
+     * and structure — the parts that make a report useful — are kept.
+     */
+    redact?: boolean;
+}
+export declare function renderProfile(profile: ContextProfile, options?: RenderOptions): string;

package/dist/report.js

@@ -18,7 +18,13 @@ function bar(fraction, width = 28) {
     const filled = Math.round(fraction * width);
     return "█".repeat(filled) + "░".repeat(width - filled);
 }
-export function renderProfile(profile) {
+/** Mask filesystem paths and quoted fragments inside a finding's text. */
+function redactText(text) {
+    return text
+        .replace(/(?:\/[\w.@ -]+){2,}/g, "[path]")
+        .replace(/\b[\w.-]+\.(ts|tsx|js|jsx|py|go|rs|java|rb|md|json|ya?ml|sql|sh)\b/gi, "[file]");
+}
+export function renderProfile(profile, options = {}) {
     const lines = [];
     const p = profile;
     lines.push("CONTEXT DOCTOR — profile");
@@ -52,7 +58,9 @@ export function renderProfile(profile) {
     lines.push("─".repeat(56));
     for (const m of p.largestMessages) {
         const label = m.toolName ? `${m.kind}:${m.toolName}` : m.kind;
-        lines.push(`  #${m.index} [${label}] ~${formatTokens(m.tokens)}  ${m.preview}`);
+        // The preview is the only place raw conversation text reaches the report.
+        const body = options.redact ? "[redacted]" : m.preview;
+        lines.push(`  #${m.index} [${label}] ~${formatTokens(m.tokens)}  ${body}`);
     }
     lines.push("");
     // Findings
@@ -61,7 +69,7 @@ export function renderProfile(profile) {
         lines.push("─".repeat(56));
         for (const f of p.findings) {
             const savings = f.estSavings > 0 ? ` [save ~${formatTokens(f.estSavings)}]` : "";
-            lines.push(`${SEVERITY_MARK[f.severity]} ${f.message}${savings}`);
+            lines.push(`${SEVERITY_MARK[f.severity]} ${options.redact ? redactText(f.message) : f.message}${savings}`);
             lines.push(`   → ${f.suggestion}`);
         }
         lines.push("");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "context-doctor",
-  "version": "0.9.0",
+  "version": "0.11.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"
+    "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"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",