context-doctor 0.13.5 → 0.14.1

package/README.md

@@ -94,6 +94,7 @@ Practical upshot: a developer who only wants cheaper, faster API calls never tou
 | `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**, and **where the wall clock went** per tool (from transcript timestamps, permission waits included and said so). 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 experiment --task "…"` | Run one task twice from the same commit, in a fresh session and forked from an `--existing` one, same model and tools; compare bill, cache split, wall clock, and whether `--check` passed. The only command here that spends money, so it caps spend per arm and refuses a dirty tree |
 | `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) |
@@ -102,6 +103,7 @@ Practical upshot: a developer who only wants cheaper, faster API calls never tou
 | `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 |
 | `context-doctor dashboard` | Local savings dashboard on 127.0.0.1: tokens saved per day, sessions by context in use vs recoverable, budget status |
+| `context-doctor statusline` | Claude Code status bar: live context vs window, cache share, cost. Wired by `install --statusline`; never overwrites a statusLine you already have |
 | `context-doctor hook` | The every-prompt Claude Code hook (registered by `install`; you never run this yourself). Warning threshold tunable via `CONTEXT_DOCTOR_WARN_TOKENS` (default 80000) |
 | `context-doctor-mcp` | The MCP server itself — stdio by default (what the installer wires); `--http [--port 8808] [--host H]` serves streamable HTTP at `/mcp` for URL-based clients like ChatGPT developer-mode connectors |
 
@@ -168,7 +170,7 @@ The proxy dedupes repeated content, trims stale tool results, and strips base64
 [context-doctor] POST /v1/messages → 200 in 842ms | optimized 7.3k → 518 tokens (2 changes) | session total: 6.9k tokens ≈ $0.021 saved
 ```
 
-`GET http://localhost:8787/stats` returns cumulative savings (requests, tokens, estimated USD), **exact upstream usage** read from every response (JSON and SSE), and **prompt-cache advisories** — the proxy watches your real traffic and flags big stable prefixes missing `cache_control` or prefix churn that silently re-bills the cache. Per-model behavior via `--config`:
+`GET http://localhost:8787/stats` returns cumulative savings (requests, tokens, estimated USD), **exact upstream usage** read from every response (JSON and SSE), and **prompt-cache advisories** — the proxy watches your real traffic and flags big stable prefixes missing `cache_control` or prefix churn that silently re-bills the cache. Per-model behavior via `--config`: The advisor now says *where*: for a large system/tools prefix it names the block to mark (the last tool definition, or the last system block), and when the older messages were byte-identical to the previous request it names the exact message to put `cache_control` on, with the token count that run is re-billing each turn. Anyone who already placed breakpoints is left alone.
 
 ```json
 { "routes": [{ "modelPrefix": "gpt", "strategies": ["strip-base64"], "keepRecent": 4 }] }
@@ -246,6 +248,57 @@ const { conversation, tokensBefore, tokensAfter } = optimizeConversation(chatJso
 });
 ```
 
+## Context health in Claude Code's status bar
+
+```bash
+context-doctor install --statusline
+```
+
+Claude Code shows the first line a `statusLine` command prints, on every refresh, while you type. With this on, that line is the number that matters:
+
+```
+ctx 801k/1.0M ▮▮▮▮▮▮▮▮░░ 80% ⚠ · cache 100% · $12.34
+```
+
+Live context against the model's window, a warning mark from 70%, the share served from cache, and the session's cost. It reads the size from the status payload when Claude Code provides it, and otherwise from the last 256KB of the transcript (about 1ms on a 20MB file; 80ms end to end including Node startup). It is opt-in and polite: there is only one status line, so it never overwrites one you already have, and `uninstall` removes only its own. Any failure prints nothing rather than an error.
+
+This is the "editor status bar" roadmap item, delivered for the editor most users of this tool are actually in. A VS Code / Cursor extension for the same number remains future work.
+
+## Does a smaller context actually help? Measure it
+
+Everything else in this tool measures what is *in* the context. None of it can tell you whether the task succeeded, so a smaller transcript can be a cheaper failure. `experiment` is the honest test:
+
+```bash
+context-doctor experiment \
+  --task "Add a null check to parseHeader in src/parse.ts and make the tests pass" \
+  --check "npm test" \
+  --existing 9c6f9dc9-457b-4d09-bf6d-a499c2f2f919 \
+  --model sonnet --budget 1
+```
+
+It runs the task in a **fresh** session, resets the tree to the starting commit, then runs it again **forked from your existing session** (`--resume … --fork-session`, so your real session is never touched), same model, same tools. For each arm it records what you were billed (input, cache read, cache write, output), cost, wall clock, turns, and whether your `--check` command passed, then puts them side by side:
+
+```
+                               fresh      existing
+──────────────────────────────────────────────────
+billed input                     20k           65k
+  of which cache read              0           60k
+  of which cache write          8.0k          4.0k
+cost                          $0.110        $0.420
+wall clock                        4s            9s
+check                           PASS      FAIL (1)
+
+Verdict: fresh was cheaper AND passed; existing failed the check. Clear win for fresh.
+```
+
+The verdict line is the point: cheaper only counts if it also passed. Because this spends your Claude budget it caps spend per arm (`--budget`, default $1), refuses to start on a dirty tree (both arms must begin from one commit, and the tree is reset between them), and refuses to run from inside a Claude Code session, where the CLI cannot start. `--dry-run` shows the exact commands first.
+
+## Exact counts, and what they teach the estimator
+
+The default token count is a chars-per-token heuristic so everything runs with no key and no tokenizer. Its error is content-dependent, and there is no honest way to fix that from transcripts alone (the billed number includes content the transcript never sees). `analyze --exact` fetches a true count for the exact bytes just estimated (Anthropic's count-tokens API with `ANTHROPIC_API_KEY`; tiktoken for GPT if installed) and prints the drift.
+
+Since 0.13.9 it also **remembers the comparison**, per model family, on this machine, and later estimates for that family are scaled by it. Nothing about this is silent: the profile header says `estimates calibrated +12% from 3 exact count(s) you ran on this machine`. No exact count ever run means no calibration and unchanged numbers; out-of-range samples are ignored; `CONTEXT_DOCTOR_NO_CALIBRATION=1` returns to the raw heuristic.
+
 ## What it detects
 
 - **Oversized tool results** — the #1 context killer in agent loops
@@ -270,10 +323,12 @@ const { conversation, tokensBefore, tokensAfter } = optimizeConversation(chatJso
 | `trim-tool-calls` — shrink the arguments of calls that already ran | Mostly no | opt-in |
 | `prune-history` — collapse old turns into a stub for summarization | Yes | opt-in |
 
-`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.
+`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, and that is measured, not cautious: across 42 real sessions, of 73 large writes 18 were later edited and **16 of those edits had no read in between**, meaning the model built the edit from its own earlier `Write` input, at a median distance of 43 messages. Trimming those would turn each into a failed edit plus a recovery read. In the offline optimizer the rest of the conversation is known, so exactly those writes are left intact and the 63% never touched again are trimmed; in the live proxy the future is not known, which is why it stays off there unless you turn it on.
 
 **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.
 
+The step size is a trade-off, not a formula, and it is yours to set: `"trimBoundaryStep": 20` in `.contextdoctorrc` (default 10). Measured on a growing agent session at 400 turns: a step of 10 invalidated the cache on 21% of turns with ~2 stale results waiting on average; 20 gave 12% and ~4; 40 gave 10% and ~9. Adaptive steps were worse everywhere, because a step that changes size moves the boundary by itself. Heavy API users who lean on caching want a bigger step; interactive users who want stale output gone promptly want a smaller one.
+
 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/calibration.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Heuristic calibration from the user's own exact counts.
+ *
+ * The chars-per-token heuristic is what lets everything run with no key and
+ * no tokenizer, and its error is content-dependent: dense JSON tokenizes very
+ * differently from prose. There is no honest way to fix that from transcripts
+ * alone (the billed number includes content the transcript never sees). But
+ * when someone runs `analyze --exact`, they fetch a true count for the exact
+ * bytes the heuristic just estimated — the one clean comparison available.
+ *
+ * So that comparison is remembered, per model family, on this machine, and
+ * applied to later estimates for the same family. Nothing is applied silently:
+ * the profile carries the factor and the sample count, and the report prints
+ * them. No exact count ever run means no calibration, and the numbers are
+ * exactly what they were before.
+ */
+export interface Calibration {
+    /** Multiply heuristic estimates by this. 1 means uncalibrated. */
+    factor: number;
+    samples: number;
+}
+export declare function calibrationPath(): string;
+/** "claude", "gpt", "gemini", … — coarse on purpose; tokenizers are per vendor. */
+export declare function modelFamily(model?: string): string;
+/** Remember one exact-vs-heuristic observation. Best-effort; never throws. */
+export declare function recordCalibration(model: string | undefined, exactTokens: number, heuristicTokens: number): void;
+/** The factor to apply for a model, or 1 with zero samples when there is none. */
+export declare function calibrationFor(model?: string): Calibration;

package/dist/calibration.js

@@ -0,0 +1,75 @@
+/**
+ * Heuristic calibration from the user's own exact counts.
+ *
+ * The chars-per-token heuristic is what lets everything run with no key and
+ * no tokenizer, and its error is content-dependent: dense JSON tokenizes very
+ * differently from prose. There is no honest way to fix that from transcripts
+ * alone (the billed number includes content the transcript never sees). But
+ * when someone runs `analyze --exact`, they fetch a true count for the exact
+ * bytes the heuristic just estimated — the one clean comparison available.
+ *
+ * So that comparison is remembered, per model family, on this machine, and
+ * applied to later estimates for the same family. Nothing is applied silently:
+ * the profile carries the factor and the sample count, and the report prints
+ * them. No exact count ever run means no calibration, and the numbers are
+ * exactly what they were before.
+ */
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { statePath } from "./ledger.js";
+/** Anything outside this is a bad sample, not a calibration. */
+const MIN_FACTOR = 0.5;
+const MAX_FACTOR = 2.0;
+export function calibrationPath() {
+    return join(dirname(statePath()), ".context-doctor-calibration.json");
+}
+/** "claude", "gpt", "gemini", … — coarse on purpose; tokenizers are per vendor. */
+export function modelFamily(model) {
+    const m = (model ?? "").toLowerCase();
+    if (m.includes("claude"))
+        return "claude";
+    if (/gpt|^o\d/.test(m))
+        return "gpt";
+    if (m.includes("gemini"))
+        return "gemini";
+    return m ? m.split(/[-_/]/)[0] : "unknown";
+}
+function readAll() {
+    try {
+        return JSON.parse(readFileSync(calibrationPath(), "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+/** Remember one exact-vs-heuristic observation. Best-effort; never throws. */
+export function recordCalibration(model, exactTokens, heuristicTokens) {
+    if (!(exactTokens > 0) || !(heuristicTokens > 0))
+        return;
+    const ratio = exactTokens / heuristicTokens;
+    if (ratio < MIN_FACTOR || ratio > MAX_FACTOR)
+        return; // a broken sample must not poison the file
+    try {
+        const all = readAll();
+        const key = modelFamily(model);
+        const rec = all[key] ?? { exactSum: 0, heuristicSum: 0, samples: 0 };
+        all[key] = { exactSum: rec.exactSum + exactTokens, heuristicSum: rec.heuristicSum + heuristicTokens, samples: rec.samples + 1 };
+        mkdirSync(dirname(calibrationPath()), { recursive: true });
+        writeFileSync(calibrationPath(), JSON.stringify(all, null, 2));
+    }
+    catch {
+        /* calibration is a refinement; failing to save it must not fail the command */
+    }
+}
+/** The factor to apply for a model, or 1 with zero samples when there is none. */
+export function calibrationFor(model) {
+    if (process.env.CONTEXT_DOCTOR_NO_CALIBRATION)
+        return { factor: 1, samples: 0 };
+    const rec = readAll()[modelFamily(model)];
+    if (!rec || rec.samples < 1 || rec.heuristicSum <= 0)
+        return { factor: 1, samples: 0 };
+    const factor = rec.exactSum / rec.heuristicSum;
+    if (!Number.isFinite(factor) || factor < MIN_FACTOR || factor > MAX_FACTOR)
+        return { factor: 1, samples: 0 };
+    return { factor, samples: rec.samples };
+}

package/dist/cli.js

@@ -24,9 +24,12 @@ import { recordLedger } from "./ledger.js";
 import { runDoctor } from "./doctor.js";
 import { measureAccuracy, renderAccuracy } from "./accuracy.js";
 import { renderDiff } from "./diff.js";
+import { renderExperiment, runExperiment } from "./experiment.js";
+import { runStatusLine } from "./statusline.js";
 import { findPreset, PRESETS, RC_FILENAME } from "./config.js";
 import { runWatch } from "./watch.js";
 import { exactTokenCount } from "./exact.js";
+import { modelFamily, recordCalibration } from "./calibration.js";
 import { checkBudget, loadConfig } from "./config.js";
 import { startDashboard } from "./dashboard.js";
 import { listCursorChats, parseCursorChat } from "./cursor.js";
@@ -45,6 +48,9 @@ Usage:
   context-doctor session [file]                 Profile a Claude Code session transcript or a
                                                 ChatGPT export (default: most recent; --list to browse)
   context-doctor cursor [--list]                Profile a Cursor chat from its local history
+  context-doctor statusline                     Claude Code status bar line: live context size, cache
+                                                share, cost (wired by \`install --statusline\`; reads
+                                                the status JSON on stdin)
   context-doctor hook                           Claude Code UserPromptSubmit hook (installed
                                                 automatically by \`install\`; reads hook JSON on stdin)
   context-doctor report                         Impact report: exact proxy savings, hook activity,
@@ -55,6 +61,9 @@ Usage:
                                                 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 experiment --task "<t>"         Run one task twice from the same commit, in a fresh
+                                                session and forked from an --existing one; compare
+                                                bill, cache, time, and whether --check passed
   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
@@ -88,6 +97,13 @@ Options:
   --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)
+  --check <cmd>           (experiment) Command whose exit code is the pass/fail for each arm
+  --existing <id>         (experiment) Session id to fork the second arm from (never mutated)
+  --budget <usd>          (experiment) Spend cap per arm (default 1)
+  --dry-run               (experiment) Print the claude commands and stop
+  --allow-dirty           (experiment) Skip the clean-tree check (uncommitted changes will be lost)
+  --statusline            (install) Also set Claude Code's statusLine to context-doctor (never
+                          overwrites a statusLine you already have)
   --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":[...],
@@ -104,7 +120,7 @@ Examples:
           export OPENAI_BASE_URL=http://localhost:8787/v1
 `;
 function parseArgs(argv) {
-    const args = { json: false, strategies: [], list: false, exact: false, redact: false, failOverBudget: false };
+    const args = { json: false, strategies: [], list: false, exact: false, redact: false, failOverBudget: false, dryRun: false, allowDirty: false, statusLine: false };
     const positional = [];
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
@@ -152,6 +168,27 @@ function parseArgs(argv) {
             case "--limit":
                 args.limit = Number(argv[++i]);
                 break;
+            case "--task":
+                args.task = argv[++i];
+                break;
+            case "--check":
+                args.check = argv[++i];
+                break;
+            case "--existing":
+                args.existing = argv[++i];
+                break;
+            case "--budget":
+                args.budgetUsd = Number(argv[++i]);
+                break;
+            case "--dry-run":
+                args.dryRun = true;
+                break;
+            case "--allow-dirty":
+                args.allowDirty = true;
+                break;
+            case "--statusline":
+                args.statusLine = true;
+                break;
             case "--host":
                 args.host = argv[++i];
                 break;
@@ -244,6 +281,22 @@ function main() {
         console.log("  Gate a pull request on it with: context-doctor analyze <file> --fail-over-budget");
         return;
     }
+    if (args.command === "statusline") {
+        void runStatusLine();
+        return;
+    }
+    if (args.command === "experiment") {
+        if (!args.task) {
+            console.error('Usage: context-doctor experiment --task "<what to do>" [--check "<cmd>"] [--existing <session-id>] [--model m] [--budget usd] [--dry-run]');
+            process.exit(1);
+        }
+        const opts = { task: args.task, check: args.check, existing: args.existing, model: args.model, budgetUsd: args.budgetUsd, dryRun: args.dryRun, allowDirty: args.allowDirty };
+        const result = runExperiment(opts);
+        console.log(args.json ? JSON.stringify(result, null, 2) : renderExperiment(result, opts));
+        if (result.refused)
+            process.exitCode = 1;
+        return;
+    }
     if (args.command === "diff") {
         const [before, after] = args.positionals ?? [];
         if (!before || !after) {
@@ -367,7 +420,7 @@ function main() {
     if (args.command === "install") {
         // Partial success is still installed, but not silent: any failed target
         // makes the exit code non-zero so automation can react.
-        if (runInstall().failures.length > 0)
+        if (runInstall({ statusLine: args.statusLine }).failures.length > 0)
             process.exitCode = 1;
         return;
     }
@@ -396,6 +449,7 @@ function main() {
             strategies: args.strategies.length > 0 ? args.strategies : loadedRc.config.strategies,
             keepRecent: args.keepRecent ?? loadedRc.config.keepRecent,
             maxToolResultTokens: args.maxToolTokens ?? loadedRc.config.maxToolResultTokens,
+            trimBoundaryStep: loadedRc.config.trimBoundaryStep,
         });
         return; // server keeps the process alive
     }
@@ -424,6 +478,11 @@ function main() {
                 if (exact.tokens !== undefined) {
                     const drift = profile.totalTokens > 0 ? Math.round(((exact.tokens - profile.totalTokens) / exact.tokens) * 100) : 0;
                     console.log(`\nExact input tokens: ${exact.tokens} (${exact.source}) — heuristic was off by ${drift}%`);
+                    // Remember the comparison so the next estimate for this model family
+                    // starts from the user's own ground truth instead of a constant.
+                    const raw = profile.calibration ? profile.totalTokens / profile.calibration.factor : profile.totalTokens;
+                    recordCalibration(args.model ?? profile.model, exact.tokens, raw);
+                    console.log(`Remembered: future ${modelFamily(args.model ?? profile.model)} estimates on this machine are calibrated from this (CONTEXT_DOCTOR_NO_CALIBRATION=1 to disable).`);
                 }
                 else {
                     console.log(`\nExact count unavailable: ${exact.note}`);
@@ -440,6 +499,7 @@ function main() {
                 strategies: args.strategies.length > 0 ? args.strategies : loaded.config.strategies,
                 keepRecent: args.keepRecent ?? loaded.config.keepRecent,
                 maxToolResultTokens: args.maxToolTokens ?? loaded.config.maxToolResultTokens,
+                trimBoundaryStep: loaded.config.trimBoundaryStep,
             });
         }
         catch (e) {

package/dist/config.d.ts

@@ -25,6 +25,8 @@ export interface ContextDoctorConfig {
     strategies?: StrategyId[];
     keepRecent?: number;
     maxToolResultTokens?: number;
+    /** Messages the trim boundary moves at a time; see OptimizeOptions. */
+    trimBoundaryStep?: number;
     /** Proxy per-model overrides, same shape as `proxy --config`. */
     routes?: Array<{
         modelPrefix: string;

package/dist/config.js

@@ -38,7 +38,7 @@ function candidatePaths(startDir) {
  */
 /** 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_KEYS = new Set(["budget", "strategies", "keepRecent", "maxToolResultTokens", "trimBoundaryStep", "routes", "model"]);
 const KNOWN_BUDGET_KEYS = new Set(["maxTokens", "maxCostPerMessageUsd", "maxWindowPct"]);
 /**
  * Report anything in an rc file that will be silently ignored.
@@ -92,7 +92,7 @@ export function validateConfig(config, path) {
             }
         }
     }
-    for (const key of ["keepRecent", "maxToolResultTokens"]) {
+    for (const key of ["keepRecent", "maxToolResultTokens", "trimBoundaryStep"]) {
         const value = c[key];
         if (value === undefined)
             continue;

package/dist/doctor.js

@@ -135,6 +135,25 @@ export async function runDoctor() {
     else {
         checks.push({ label: "Every-prompt hook", status: "skip", detail: "Claude Code not detected" });
     }
+    // Status line (opt-in, so absence is a note, not a failure)
+    if (existsSync(settingsPath)) {
+        try {
+            const settings = JSON.parse(readFileSync(settingsPath, "utf8"));
+            const cmd = settings.statusLine?.command;
+            if (cmd && /context-doctor|cli\.js"?\s+statusline/.test(cmd)) {
+                const missing = hookBinaryMissing(cmd);
+                checks.push(missing
+                    ? { label: "Status line", status: "fail", detail: `configured, but ${missing} no longer exists — re-run: context-doctor install --statusline` }
+                    : { label: "Status line", status: "ok", detail: "live context in Claude Code's status bar" });
+            }
+            else {
+                checks.push({ label: "Status line", status: "skip", detail: cmd ? "you have your own statusLine (left alone)" : "not enabled (optional: context-doctor install --statusline)" });
+            }
+        }
+        catch {
+            /* settings.json unreadable is already reported by the hook check */
+        }
+    }
     // Skill
     const skillPath = join(homedir(), ".claude", "skills", "context-doctor", "SKILL.md");
     checks.push(existsSync(skillPath)

package/dist/experiment.d.ts

@@ -0,0 +1,58 @@
+/**
+ * `context-doctor experiment` — the fresh-vs-existing session harness.
+ *
+ * Everything else in this tool measures what is IN the context. None of it can
+ * say whether the task succeeded, so a smaller transcript can be a cheaper
+ * failure. This runs the same task twice against the same starting commit —
+ * once in a fresh session, once forked from an existing one — with the same
+ * model and tools, records what each was billed and how long it took, runs the
+ * same check command against each result, and puts the two side by side.
+ *
+ * It spends the user's Claude budget, so it refuses to start on a dirty tree,
+ * caps spend per arm, forks the existing session rather than mutating it, and
+ * resets the tree between arms only because it verified the tree was clean.
+ */
+export interface ExperimentOptions {
+    task: string;
+    /** Shell command whose exit code decides pass/fail, e.g. "npm test". */
+    check?: string;
+    /** Session id to fork the "existing" arm from. Omit to run the fresh arm only. */
+    existing?: string;
+    model?: string;
+    /** Spend cap per arm, USD. */
+    budgetUsd?: number;
+    cwd?: string;
+    /** Print the commands and stop. */
+    dryRun?: boolean;
+    /** Skip the clean-tree requirement (you accept the reset that follows). */
+    allowDirty?: boolean;
+}
+export interface ArmResult {
+    arm: "fresh" | "existing";
+    sessionId?: string;
+    costUsd: number;
+    durationMs: number;
+    turns: number;
+    inputTokens: number;
+    cacheRead: number;
+    cacheWrite: number;
+    outputTokens: number;
+    /** Billed input the transcript reports on the last request, when found. */
+    liveContextTokens?: number;
+    check?: {
+        command: string;
+        passed: boolean;
+        exitCode: number;
+    };
+    diffStat?: string;
+    error?: string;
+}
+/** Build the argv for one arm — exported so the dry run and the tests see exactly what runs. */
+export declare function claudeArgs(opts: ExperimentOptions, arm: "fresh" | "existing"): string[];
+export declare function runExperiment(opts: ExperimentOptions): {
+    arms: ArmResult[];
+    startCommit?: string;
+    refused?: string;
+    treeClean?: boolean;
+};
+export declare function renderExperiment(result: ReturnType<typeof runExperiment>, opts: ExperimentOptions): string;

package/dist/experiment.js

@@ -0,0 +1,214 @@
+/**
+ * `context-doctor experiment` — the fresh-vs-existing session harness.
+ *
+ * Everything else in this tool measures what is IN the context. None of it can
+ * say whether the task succeeded, so a smaller transcript can be a cheaper
+ * failure. This runs the same task twice against the same starting commit —
+ * once in a fresh session, once forked from an existing one — with the same
+ * model and tools, records what each was billed and how long it took, runs the
+ * same check command against each result, and puts the two side by side.
+ *
+ * It spends the user's Claude budget, so it refuses to start on a dirty tree,
+ * caps spend per arm, forks the existing session rather than mutating it, and
+ * resets the tree between arms only because it verified the tree was clean.
+ */
+import { execFileSync, spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { parseSessionFile } from "./session.js";
+import { formatTokens } from "./tokens.js";
+import { formatUsd } from "./pricing.js";
+/** Where a test can point at a stub instead of the real CLI. */
+function claudeBinary() {
+    return process.env.CONTEXT_DOCTOR_CLAUDE_BIN ?? "claude";
+}
+function git(cwd, ...args) {
+    return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+}
+function num(v) {
+    return typeof v === "number" && Number.isFinite(v) ? v : 0;
+}
+/** Build the argv for one arm — exported so the dry run and the tests see exactly what runs. */
+export function claudeArgs(opts, arm) {
+    const args = ["-p", opts.task, "--output-format", "json", "--permission-mode", "acceptEdits"];
+    if (opts.model)
+        args.push("--model", opts.model);
+    args.push("--max-budget-usd", String(opts.budgetUsd ?? 1));
+    if (arm === "existing" && opts.existing)
+        args.push("--resume", opts.existing, "--fork-session");
+    return args;
+}
+function findTranscript(sessionId, cwd) {
+    // Claude Code keys project dirs by the cwd with separators replaced.
+    const projectDir = join(homedir(), ".claude", "projects", cwd.replace(/[\\/:]/g, "-"));
+    const candidate = join(projectDir, `${sessionId}.jsonl`);
+    return existsSync(candidate) ? candidate : undefined;
+}
+function runArm(opts, arm, cwd) {
+    const started = Date.now();
+    const proc = spawnSync(claudeBinary(), claudeArgs(opts, arm), {
+        cwd,
+        encoding: "utf8",
+        env: { ...process.env, CLAUDECODE: undefined },
+        maxBuffer: 64 * 1024 * 1024,
+    });
+    const base = {
+        arm, costUsd: 0, durationMs: Date.now() - started, turns: 0,
+        inputTokens: 0, cacheRead: 0, cacheWrite: 0, outputTokens: 0,
+    };
+    if (proc.error)
+        return { ...base, error: `could not run ${claudeBinary()}: ${proc.error.message}` };
+    let parsed;
+    try {
+        parsed = JSON.parse(proc.stdout);
+    }
+    catch {
+        return { ...base, error: `claude did not return JSON (exit ${proc.status}): ${(proc.stderr || proc.stdout).slice(0, 300)}` };
+    }
+    const usage = parsed.usage ?? {};
+    const result = {
+        ...base,
+        sessionId: parsed.session_id,
+        costUsd: num(parsed.total_cost_usd),
+        durationMs: num(parsed.duration_ms) || base.durationMs,
+        turns: num(parsed.num_turns),
+        inputTokens: num(usage.input_tokens),
+        cacheRead: num(usage.cache_read_input_tokens),
+        cacheWrite: num(usage.cache_creation_input_tokens),
+        outputTokens: num(usage.output_tokens),
+        error: parsed.is_error ? `claude reported an error: ${String(parsed.result ?? "").slice(0, 300)}` : undefined,
+    };
+    if (parsed.session_id) {
+        const transcript = findTranscript(parsed.session_id, cwd);
+        if (transcript) {
+            try {
+                result.liveContextTokens = parseSessionFile(transcript).reportedInputTokens;
+            }
+            catch {
+                /* the numbers above stand on their own */
+            }
+        }
+    }
+    if (opts.check) {
+        const check = spawnSync(opts.check, { cwd, shell: true, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+        result.check = { command: opts.check, passed: check.status === 0, exitCode: check.status ?? -1 };
+    }
+    try {
+        result.diffStat = git(cwd, "diff", "--stat") || "(no changes)";
+    }
+    catch {
+        /* not a git repo after all; the arm still ran */
+    }
+    return result;
+}
+export function runExperiment(opts) {
+    const cwd = opts.cwd ?? process.cwd();
+    if (process.env.CLAUDECODE && !opts.dryRun) {
+        return { arms: [], refused: "This runs the claude CLI, which refuses to start inside another Claude Code session. Run the experiment from a regular terminal." };
+    }
+    let startCommit;
+    let clean = false;
+    try {
+        startCommit = git(cwd, "rev-parse", "HEAD");
+        clean = git(cwd, "status", "--porcelain") === "";
+    }
+    catch {
+        return { arms: [], refused: `${cwd} is not a git repository. The experiment needs a commit to reset to between arms.` };
+    }
+    // A dry run touches nothing, so a dirty tree only needs mentioning.
+    if (opts.dryRun)
+        return { arms: [], startCommit, treeClean: clean };
+    if (!clean && !opts.allowDirty) {
+        return { arms: [], refused: "Working tree has uncommitted changes. Both arms must start from the same commit, and the tree is reset between them — commit or stash first (or pass --allow-dirty to accept losing those changes)." };
+    }
+    const arms = [];
+    const reset = () => {
+        // Safe only because the tree was verified clean (or the user opted in).
+        git(cwd, "reset", "--hard", startCommit);
+        git(cwd, "clean", "-fd");
+    };
+    arms.push(runArm(opts, "fresh", cwd));
+    reset();
+    if (opts.existing) {
+        arms.push(runArm(opts, "existing", cwd));
+        reset();
+    }
+    return { arms, startCommit };
+}
+export function renderExperiment(result, opts) {
+    const lines = [];
+    lines.push("CONTEXT DOCTOR — fresh vs existing session");
+    lines.push("═".repeat(56));
+    if (result.refused) {
+        lines.push(`Refused: ${result.refused}`);
+        return lines.join("\n");
+    }
+    lines.push(`task:    ${opts.task}`);
+    if (result.startCommit)
+        lines.push(`commit:  ${result.startCommit.slice(0, 12)} (both arms start here)`);
+    if (opts.model)
+        lines.push(`model:   ${opts.model}`);
+    if (opts.check)
+        lines.push(`check:   ${opts.check}`);
+    lines.push(`budget:  ${formatUsd(opts.budgetUsd ?? 1)} per arm`);
+    if (opts.dryRun) {
+        lines.push("");
+        lines.push("Dry run. Commands that would execute:");
+        lines.push(`  fresh:    claude ${claudeArgs(opts, "fresh").map((a) => (a.includes(" ") ? JSON.stringify(a) : a)).join(" ")}`);
+        if (opts.existing)
+            lines.push(`  existing: claude ${claudeArgs(opts, "existing").map((a) => (a.includes(" ") ? JSON.stringify(a) : a)).join(" ")}`);
+        lines.push("  (tree is reset to the start commit after each arm)");
+        if (result.treeClean === false)
+            lines.push("  NOTE: the tree is dirty right now; a real run would refuse unless you commit, stash, or pass --allow-dirty.");
+        return lines.join("\n");
+    }
+    lines.push("");
+    const col = (s, w = 14) => s.padStart(w);
+    const header = `${"".padEnd(22)}${col("fresh")}${opts.existing ? col("existing") : ""}`;
+    lines.push(header);
+    lines.push("─".repeat(header.length));
+    const row = (label, pick) => {
+        lines.push(`${label.padEnd(22)}${result.arms.map((a) => col(pick(a))).join("")}`);
+    };
+    row("billed input", (a) => formatTokens(a.inputTokens + a.cacheRead + a.cacheWrite));
+    row("  of which cache read", (a) => formatTokens(a.cacheRead));
+    row("  of which cache write", (a) => formatTokens(a.cacheWrite));
+    row("output tokens", (a) => formatTokens(a.outputTokens));
+    row("cost", (a) => formatUsd(a.costUsd));
+    row("wall clock", (a) => `${(a.durationMs / 1000).toFixed(0)}s`);
+    row("turns", (a) => String(a.turns));
+    if (result.arms.some((a) => a.liveContextTokens))
+        row("live context (last)", (a) => (a.liveContextTokens ? formatTokens(a.liveContextTokens) : "—"));
+    if (opts.check)
+        row("check", (a) => (a.check ? (a.check.passed ? "PASS" : `FAIL (${a.check.exitCode})`) : "—"));
+    lines.push("");
+    for (const a of result.arms) {
+        if (a.error)
+            lines.push(`${a.arm}: ${a.error}`);
+        if (a.diffStat && a.diffStat !== "(no changes)")
+            lines.push(`${a.arm} changed:\n${a.diffStat.split("\n").map((l) => "  " + l).join("\n")}`);
+    }
+    // The verdict is the whole point: cheaper is only better if it also passed.
+    if (opts.existing && result.arms.length === 2 && opts.check) {
+        const [fresh, existing] = result.arms;
+        const cheaper = fresh.costUsd <= existing.costUsd ? fresh : existing;
+        const other = cheaper === fresh ? existing : fresh;
+        if (cheaper.check?.passed && !other.check?.passed) {
+            lines.push(`Verdict: ${cheaper.arm} was cheaper AND passed; ${other.arm} failed the check. Clear win for ${cheaper.arm}.`);
+        }
+        else if (cheaper.check?.passed && other.check?.passed) {
+            lines.push(`Verdict: both passed; ${cheaper.arm} was cheaper by ${formatUsd(Math.abs(fresh.costUsd - existing.costUsd))}.`);
+        }
+        else if (!cheaper.check?.passed && other.check?.passed) {
+            lines.push(`Verdict: ${cheaper.arm} was cheaper but FAILED the check. A smaller bill for a wrong answer is not a saving; ${other.arm} wins.`);
+        }
+        else {
+            lines.push("Verdict: neither arm passed the check. Cost comparison is moot until one does.");
+        }
+    }
+    else if (opts.check) {
+        lines.push("One arm only. Pass --existing <session-id> to compare against a forked existing session.");
+    }
+    return lines.join("\n");
+}

package/dist/install.d.ts

@@ -20,6 +20,13 @@ export declare function npxLauncher(platformName: string): {
     command: string;
     args: string[];
 };
+/**
+ * Claude Code's status bar: a `statusLine` command whose stdout is shown while
+ * the user types. Opt-in, because there is only one status line and it may
+ * already be someone's own — this never overwrites a statusLine that is not
+ * ours. Returns what happened so install can print the truth.
+ */
+export declare function installStatusLine(): "installed" | "already" | "kept-foreign" | "no-claude-code";
 /** Outcome of an install run, so the CLI can set a truthful exit code. */
 export interface InstallResult {
     /** Detected targets that could not be configured, with the reason. */
@@ -35,5 +42,7 @@ export interface InstallResult {
  * failed target is a lie that surfaces later as "the tools never showed up".
  * So: keep going, summarize, and return the failures for a non-zero exit.
  */
-export declare function runInstall(): InstallResult;
+export declare function runInstall(options?: {
+    statusLine?: boolean;
+}): InstallResult;
 export declare function runUninstall(): void;

package/dist/install.js

@@ -122,14 +122,54 @@ function isEphemeralPath(path) {
  * prompt. `node` (not process.execPath) keeps it alive across Node upgrades.
  */
 function hookCommand() {
+    return cliCommand("hook");
+}
+/** The same durable command resolution, for any subcommand Claude Code runs for us. */
+function cliCommand(subcommand) {
     const selfDir = dirname(fileURLToPath(import.meta.url));
     const localCli = join(selfDir, "cli.js");
     if (!isEphemeralPath(selfDir + sep) && existsSync(localCli))
-        return `node "${localCli}" hook`;
+        return `node "${localCli}" ${subcommand}`;
     const global = binOnPath("context-doctor");
     if (global)
-        return `"${global}" hook`;
-    return "npx -y context-doctor hook";
+        return `"${global}" ${subcommand}`;
+    return `npx -y context-doctor ${subcommand}`;
+}
+/**
+ * Claude Code's status bar: a `statusLine` command whose stdout is shown while
+ * the user types. Opt-in, because there is only one status line and it may
+ * already be someone's own — this never overwrites a statusLine that is not
+ * ours. Returns what happened so install can print the truth.
+ */
+export function installStatusLine() {
+    const settingsPath = join(homedir(), ".claude", "settings.json");
+    if (!existsSync(join(homedir(), ".claude")))
+        return "no-claude-code";
+    const settings = readJson(settingsPath);
+    const want = cliCommand("statusline");
+    const current = settings.statusLine?.command;
+    if (current === want)
+        return "already";
+    if (current && !isOurStatusLine(current))
+        return "kept-foreign";
+    settings.statusLine = { type: "command", command: want };
+    writeJsonWithBackup(settingsPath, settings);
+    return "installed";
+}
+function isOurStatusLine(command) {
+    return /context-doctor|cli\.js"?\s+statusline\s*$/.test(command);
+}
+function uninstallStatusLine() {
+    const settingsPath = join(homedir(), ".claude", "settings.json");
+    if (!existsSync(settingsPath))
+        return;
+    const settings = readJson(settingsPath);
+    const current = settings.statusLine?.command;
+    if (current && isOurStatusLine(current)) {
+        delete settings.statusLine;
+        writeJsonWithBackup(settingsPath, settings);
+        console.log("✓ Claude Code status line removed");
+    }
 }
 /** True when the hook had to fall back to npx — worth telling the user. */
 function hookUsesNpx() {
@@ -224,7 +264,7 @@ function installSkill() {
  * failed target is a lie that surfaces later as "the tools never showed up".
  * So: keep going, summarize, and return the failures for a non-zero exit.
  */
-export function runInstall() {
+export function runInstall(options = {}) {
     const entry = serverEntry();
     const found = targets().filter((t) => t.detect());
     if (found.length === 0) {
@@ -274,6 +314,28 @@ export function runInstall() {
         console.error(`✗ Claude Code every-prompt hook: ${e.message}`);
         failures.push("Claude Code hook");
     }
+    if (options.statusLine) {
+        try {
+            switch (installStatusLine()) {
+                case "installed":
+                    console.log("✓ Claude Code status line installed — live context size, cache share and cost while you type");
+                    break;
+                case "already":
+                    console.log("✓ Claude Code status line already installed");
+                    break;
+                case "kept-foreign":
+                    console.log("– Claude Code status line left alone: you already have your own statusLine command. Remove it first if you want ours.");
+                    break;
+                case "no-claude-code":
+                    console.log("– status line skipped: Claude Code not detected");
+                    break;
+            }
+        }
+        catch (e) {
+            console.error(`✗ Claude Code status line: ${e.message}`);
+            failures.push("Claude Code status line");
+        }
+    }
     if (failures.length > 0) {
         console.log(`\nDone with ${failures.length} problem(s): ${failures.join(", ")}. See the ✗ lines above.`);
         console.log("Everything else was installed. Exit code is 1 so scripts can tell; fix the file(s) and re-run install.");
@@ -306,6 +368,7 @@ export function runUninstall() {
         console.log("✓ Agent Skill removed");
     }
     uninstallHook();
+    uninstallStatusLine();
     // Remove our bookkeeping files too — uninstall means gone.
     for (const file of [".context-doctor-hook-state.json", ".context-doctor-ledger.jsonl"]) {
         const p = join(homedir(), ".claude", file);

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.13.5" }, { instructions: SERVER_INSTRUCTIONS });
+    const server = new McpServer({ name: "context-doctor", version: "0.14.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.d.ts

@@ -13,6 +13,15 @@ export interface OptimizeOptions {
     keepRecent?: number;
     /** Max tokens a trimmed tool result — or tool-call argument set — keeps. */
     maxToolResultTokens?: number;
+    /**
+     * How many messages the trim boundary moves at a time. Bigger steps keep the
+     * prompt cache alive longer but leave stale results in place longer.
+     * Measured on a growing agent session: at 400 turns a step of 10 invalidated
+     * the cache on 21% of turns with ~2 stale results waiting on average; 20
+     * gave 12% and ~4; 40 gave 10% and ~9. Adaptive steps were worse everywhere,
+     * because a step that changes size moves the boundary by itself. Default 10.
+     */
+    trimBoundaryStep?: number;
 }
 export interface AppliedChange {
     strategy: StrategyId;

package/dist/optimize.js

@@ -9,10 +9,12 @@
 import { createHash } from "node:crypto";
 import { estimateTokens } from "./tokens.js";
 import { hasBase64Blob, stripBase64Blobs } from "./blob.js";
+const TRIM_BOUNDARY_STEP = 10;
 const DEFAULTS = {
     strategies: ["dedupe", "trim-tool-results", "strip-base64"],
     keepRecent: 6,
     maxToolResultTokens: 300,
+    trimBoundaryStep: TRIM_BOUNDARY_STEP,
 };
 /**
  * Shrink the arguments of a tool call that has already run.
@@ -25,6 +27,42 @@ const DEFAULTS = {
  * Keys are preserved (so the call still reads as itself) and only long string
  * values are cut, with an explicit marker so nothing looks silently complete.
  */
+/** The file a Write-like call creates, or null for anything else. */
+function writtenPath(block) {
+    if (block?.name === "Write" && typeof block.input?.file_path === "string")
+        return block.input.file_path;
+    const cmd = block?.name === "Bash" ? String(block.input?.command ?? "") : "";
+    const heredoc = /(?:cat|tee)\s*>+\s*([^\s<]+)\s*<</.exec(cmd);
+    return heredoc ? heredoc[1] : null;
+}
+/**
+ * Does the model later Edit this file without Reading it first? If so it is
+ * relying on the Write input still being in context, and trimming that input
+ * would break the Edit.
+ */
+function editedLaterWithoutRead(messages, writeIndex, path) {
+    if (!path)
+        return false;
+    for (let j = writeIndex + 1; j < messages.length; j++) {
+        const content = messages[j]?.content;
+        if (!Array.isArray(content))
+            continue;
+        for (const b of content) {
+            if (b?.type !== "tool_use")
+                continue;
+            const target = b.input?.file_path;
+            const cmd = b.name === "Bash" ? String(b.input?.command ?? "") : "";
+            const touchesPath = target === path || cmd.includes(path);
+            if (!touchesPath)
+                continue;
+            if (b.name === "Read" || /\b(cat|head|tail|sed|less)\b/.test(cmd))
+                return false; // it re-read: safe
+            if (b.name === "Edit" || b.name === "MultiEdit")
+                return true; // edited blind: keep the Write
+        }
+    }
+    return false;
+}
 function trimCallArguments(input, maxTokens) {
     const budgetChars = maxTokens * 4;
     const out = {};
@@ -54,17 +92,16 @@ function trimCallArguments(input, maxTokens) {
  * 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) {
+function stableCutoff(messageCount, keepRecent, step = TRIM_BOUNDARY_STEP) {
     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)
+    if (raw < step)
         return raw;
-    return Math.floor(raw / TRIM_BOUNDARY_STEP) * TRIM_BOUNDARY_STEP;
+    return Math.floor(raw / step) * step;
 }
 function hash(text) {
     return createHash("sha1").update(text.replace(/\s+/g, " ").trim()).digest("hex");
@@ -171,6 +208,7 @@ export function optimizeConversation(input, options = {}) {
         strategies: options.strategies ?? DEFAULTS.strategies,
         keepRecent: options.keepRecent ?? DEFAULTS.keepRecent,
         maxToolResultTokens: options.maxToolResultTokens ?? DEFAULTS.maxToolResultTokens,
+        trimBoundaryStep: options.trimBoundaryStep && options.trimBoundaryStep > 0 ? Math.floor(options.trimBoundaryStep) : DEFAULTS.trimBoundaryStep,
     };
     let data;
     try {
@@ -216,7 +254,7 @@ export function optimizeConversation(input, options = {}) {
         // 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 cutoff = stableCutoff(messages.length, opts.keepRecent, opts.trimBoundaryStep);
         const seen = new Map();
         messages.forEach((m, i) => {
             const text = textOf(m.content);
@@ -241,7 +279,7 @@ export function optimizeConversation(input, options = {}) {
     }
     // -- trim-tool-results: shrink stale tool output ------------------------------
     if (opts.strategies.includes("trim-tool-results")) {
-        const cutoff = stableCutoff(messages.length, opts.keepRecent);
+        const cutoff = stableCutoff(messages.length, opts.keepRecent, opts.trimBoundaryStep);
         messages.forEach((m, i) => {
             if (i >= cutoff || !isToolResultMessage(m))
                 return;
@@ -266,7 +304,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 = stableCutoff(messages.length, opts.keepRecent);
+        const cutoff = stableCutoff(messages.length, opts.keepRecent, opts.trimBoundaryStep);
         messages.forEach((m, i) => {
             if (i >= cutoff)
                 return;
@@ -276,6 +314,14 @@ export function optimizeConversation(input, options = {}) {
                 for (const b of m.content) {
                     if (b?.type !== "tool_use" || b.input == null || typeof b.input !== "object")
                         continue;
+                    // Measured across 42 real sessions: of 73 large Writes, 18 were later
+                    // Edited and 16 of those Edits had no Read in between — the model
+                    // built old_string from its own Write input, at a median distance of
+                    // 43 messages. Trimming such a Write turns that Edit into a failure
+                    // plus a recovery Read. Offline we can see the future, so leave
+                    // those alone; the 63% never touched again are still pure gain.
+                    if (editedLaterWithoutRead(messages, i, writtenPath(b)))
+                        continue;
                     const before = estimateTokens(JSON.stringify(b.input));
                     if (before <= opts.maxToolResultTokens)
                         continue;

package/dist/profile.d.ts

@@ -51,6 +51,14 @@ export interface ContextProfile {
     /** Present when the model has a known price. All figures are estimates. */
     cost?: CostEstimate;
     sourceFormat: string;
+    /**
+     * Present when estimates were scaled by a factor learned from this machine's
+     * own `--exact` counts for this model family. Absent means raw heuristic.
+     */
+    calibration?: {
+        factor: number;
+        samples: number;
+    };
     /** Propagated from parsing: input could not be read as a conversation. */
     parseWarning?: string;
 }

package/dist/profile.js

@@ -6,6 +6,7 @@ import { createHash } from "node:crypto";
 import { contextWindowFor, estimateTokens, MESSAGE_OVERHEAD_TOKENS, providerFor } from "./tokens.js";
 import { estimatedTtftSeconds, inputCostUsd, pricingFor } from "./pricing.js";
 import { hasBase64Blob } from "./blob.js";
+import { calibrationFor } from "./calibration.js";
 function categoryOf(m) {
     switch (m.kind) {
         case "system": return "system";
@@ -145,9 +146,11 @@ function filesReadBy(toolName, toolCallText) {
     return [...paths];
 }
 export function profileConversation(conv, model) {
+    // Learned from the user's own exact counts, if they ever fetched any.
+    const calibration = calibrationFor(model);
     const perMessage = conv.messages.map((m) => ({
         msg: m,
-        tokens: estimateTokens(m.text) + MESSAGE_OVERHEAD_TOKENS,
+        tokens: Math.round(estimateTokens(m.text) * calibration.factor) + MESSAGE_OVERHEAD_TOKENS,
     }));
     const totalTokens = perMessage.reduce((sum, p) => sum + p.tokens, 0);
     const categories = {
@@ -445,6 +448,7 @@ export function profileConversation(conv, model) {
         totalEstSavings,
         cost,
         sourceFormat: conv.sourceFormat,
+        calibration: calibration.samples > 0 ? calibration : undefined,
         parseWarning: conv.parseWarning,
     };
 }

package/dist/proxy.js

@@ -66,6 +66,8 @@ export function startProxy(opts = {}) {
     };
     /** Last stable-prefix fingerprint per model, for cache-invalidation advice. */
     const prefixFingerprints = new Map();
+    /** Per-message fingerprints of the previous request per model, for breakpoint placement. */
+    const messageFingerprints = new Map();
     const advise = (msg) => {
         if (stats.advice.includes(msg) || stats.advice.length >= 10)
             return;
@@ -117,14 +119,24 @@ export function startProxy(opts = {}) {
                                 strategies: route.strategies ?? opts.strategies,
                                 keepRecent: route.keepRecent ?? opts.keepRecent,
                                 maxToolResultTokens: route.maxToolResultTokens ?? opts.maxToolResultTokens,
+                                trimBoundaryStep: opts.trimBoundaryStep,
                             };
                         }
                         // Prompt-cache advisor (Anthropic requests): the proxy sees real
                         // sequences, so cache-hostile patterns are observable facts here.
                         if (url.startsWith("/v1/messages") && requestModel) {
                             const stablePrefix = JSON.stringify(parsedBody.tools ?? null) + JSON.stringify(parsedBody.system ?? null);
-                            if (stablePrefix.length > 4000 && !body.includes("cache_control")) {
-                                advise(`~${Math.round(stablePrefix.length / 4)}+ tokens of stable system/tools on ${requestModel} without cache_control — adding a breakpoint would cut those to ~10% cost per call`);
+                            const hasBreakpoint = body.includes("cache_control");
+                            if (stablePrefix.length > 4000 && !hasBreakpoint) {
+                                // Say WHERE, not just that. A breakpoint caches everything up
+                                // to and including the block it sits on, so it belongs on the
+                                // LAST stable block: the final tool definition if there are
+                                // tools, otherwise the final system block.
+                                const where = Array.isArray(parsedBody.tools) && parsedBody.tools.length > 0
+                                    ? `the last entry in "tools" (tools come before system in the cached prefix)`
+                                    : `the last block of "system"`;
+                                advise(`~${Math.round(stablePrefix.length / 4)}+ tokens of stable system/tools on ${requestModel} without cache_control. ` +
+                                    `Add {"cache_control":{"type":"ephemeral"}} to ${where}; everything before it then bills at ~10% on every call`);
                             }
                             const fp = fnv1a(stablePrefix);
                             const prev = prefixFingerprints.get(requestModel);
@@ -132,6 +144,31 @@ export function startProxy(opts = {}) {
                                 advise(`system/tools prefix changed between ${requestModel} requests — every change re-bills the whole cached prefix; keep it byte-stable`);
                             }
                             prefixFingerprints.set(requestModel, fp);
+                            // Second breakpoint: the conversation itself. Between two
+                            // consecutive requests the older messages are usually identical;
+                            // that run is cacheable too, and it is what re-bills every turn
+                            // when nothing marks it. Find the longest message prefix that
+                            // survived from the previous request and point at its last message.
+                            const msgs = Array.isArray(parsedBody.messages)
+                                ? parsedBody.messages
+                                : [];
+                            const hashes = msgs.map((m) => fnv1a(JSON.stringify(m)));
+                            const prevHashes = messageFingerprints.get(requestModel);
+                            if (prevHashes && !hasBreakpoint) {
+                                let stable = 0;
+                                while (stable < hashes.length && stable < prevHashes.length && hashes[stable] === prevHashes[stable])
+                                    stable++;
+                                if (stable >= 2) {
+                                    const stableChars = msgs.slice(0, stable).reduce((n, m) => n + JSON.stringify(m).length, 0);
+                                    const stableTokens = Math.round(stableChars / 4);
+                                    // Anthropic will not cache a prefix under ~1024 tokens (2048 on Haiku).
+                                    if (stableTokens >= 1024) {
+                                        advise(`messages #0-#${stable - 1} (~${stableTokens} tokens) were identical to the previous ${requestModel} request and carry no cache_control. ` +
+                                            `Put {"cache_control":{"type":"ephemeral"}} on the last content block of message #${stable - 1}; that run then reads from cache instead of re-billing each turn`);
+                                    }
+                                }
+                            }
+                            messageFingerprints.set(requestModel, hashes);
                         }
                     }
                     catch {

package/dist/report.js

@@ -37,6 +37,11 @@ export function renderProfile(profile, options = {}) {
         lines.push("");
     }
     lines.push(`Total: ~${formatTokens(p.totalTokens)} tokens across ${p.messageCount} messages (${p.sourceFormat} format)`);
+    if (p.calibration) {
+        // Scaled numbers must say so, or they read as the raw heuristic.
+        const pct = Math.round((p.calibration.factor - 1) * 100);
+        lines.push(`       estimates calibrated ${pct >= 0 ? "+" : ""}${pct}% from ${p.calibration.samples} exact count(s) you ran on this machine (analyze --exact)`);
+    }
     if (p.model) {
         const windowNote = p.contextWindow
             ? ` of ${formatTokens(p.contextWindow)} window (${p.usagePct.toFixed(1)}%)`

package/dist/statusline.d.ts

@@ -0,0 +1,44 @@
+/**
+ * `context-doctor statusline` — live context health in Claude Code's status bar.
+ *
+ * Claude Code's `statusLine` setting runs a command on every refresh and shows
+ * its first line of stdout. That is "context health where the work happens"
+ * without an editor extension: the number that matters, visible while typing.
+ *
+ * It has to be fast and silent. Fast: the status payload on stdin carries the
+ * live context size in recent versions; when it does not, only the tail of the
+ * transcript is read (last 256KB, ~1ms on a 20MB file). Silent: any failure
+ * prints nothing at all, because a status line that shows an error is worse
+ * than one that shows nothing.
+ */
+/** The parts of Claude Code's status payload this reads. All optional. */
+interface StatusInput {
+    transcript_path?: string;
+    model?: {
+        id?: string;
+        display_name?: string;
+    };
+    cost?: {
+        total_cost_usd?: number;
+    };
+    context_window?: {
+        total_input_tokens?: number;
+        context_window_size?: number;
+        current_usage?: {
+            input_tokens?: number;
+            cache_read_input_tokens?: number;
+            cache_creation_input_tokens?: number;
+        };
+    };
+}
+interface LiveUsage {
+    tokens: number;
+    cacheShare?: number;
+    model?: string;
+}
+/** Newest assistant usage from the END of a transcript, without reading the file. */
+export declare function tailUsage(path: string, tailBytes?: number): LiveUsage | undefined;
+/** Build the status line, or null when there is nothing trustworthy to show. */
+export declare function renderStatusLine(input: StatusInput): string | null;
+export declare function runStatusLine(): Promise<void>;
+export {};

package/dist/statusline.js

@@ -0,0 +1,104 @@
+/**
+ * `context-doctor statusline` — live context health in Claude Code's status bar.
+ *
+ * Claude Code's `statusLine` setting runs a command on every refresh and shows
+ * its first line of stdout. That is "context health where the work happens"
+ * without an editor extension: the number that matters, visible while typing.
+ *
+ * It has to be fast and silent. Fast: the status payload on stdin carries the
+ * live context size in recent versions; when it does not, only the tail of the
+ * transcript is read (last 256KB, ~1ms on a 20MB file). Silent: any failure
+ * prints nothing at all, because a status line that shows an error is worse
+ * than one that shows nothing.
+ */
+import { closeSync, openSync, readSync, statSync } from "node:fs";
+import { contextWindowFor, formatTokens } from "./tokens.js";
+import { formatUsd } from "./pricing.js";
+/** Newest assistant usage from the END of a transcript, without reading the file. */
+export function tailUsage(path, tailBytes = 256 * 1024) {
+    try {
+        const size = statSync(path).size;
+        const n = Math.min(size, tailBytes);
+        const fd = openSync(path, "r");
+        const buf = Buffer.alloc(n);
+        try {
+            readSync(fd, buf, 0, n, size - n);
+        }
+        finally {
+            closeSync(fd);
+        }
+        for (const line of buf.toString("utf8").split("\n").reverse()) {
+            let entry;
+            try {
+                entry = JSON.parse(line);
+            }
+            catch {
+                continue; // the first line of a tail is usually a partial one
+            }
+            const usage = entry.type === "assistant" ? entry.message?.usage : undefined;
+            if (!usage)
+                continue;
+            const read = usage.cache_read_input_tokens ?? 0;
+            const tokens = (usage.input_tokens ?? 0) + read + (usage.cache_creation_input_tokens ?? 0);
+            if (tokens > 0)
+                return { tokens, cacheShare: read / tokens, model: entry.message?.model };
+        }
+    }
+    catch {
+        /* unreadable: the caller shows nothing */
+    }
+    return undefined;
+}
+/** Ten-cell bar; the visual half of the number. */
+function bar(pct) {
+    const filled = Math.max(0, Math.min(10, Math.round(pct / 10)));
+    return "▮".repeat(filled) + "░".repeat(10 - filled);
+}
+/** Build the status line, or null when there is nothing trustworthy to show. */
+export function renderStatusLine(input) {
+    let live;
+    const cw = input.context_window;
+    const fromPayload = cw?.current_usage
+        ? (cw.current_usage.input_tokens ?? 0) + (cw.current_usage.cache_read_input_tokens ?? 0) + (cw.current_usage.cache_creation_input_tokens ?? 0)
+        : cw?.total_input_tokens;
+    if (fromPayload && fromPayload > 0) {
+        const read = cw?.current_usage?.cache_read_input_tokens;
+        live = { tokens: fromPayload, cacheShare: read !== undefined ? read / fromPayload : undefined, model: input.model?.id };
+    }
+    else if (input.transcript_path) {
+        live = tailUsage(input.transcript_path);
+    }
+    if (!live)
+        return null;
+    const window = cw?.context_window_size ?? contextWindowFor(live.model ?? input.model?.id);
+    const parts = [];
+    if (window) {
+        const pct = (live.tokens / window) * 100;
+        parts.push(`ctx ${formatTokens(live.tokens)}/${formatTokens(window)} ${bar(pct)} ${pct.toFixed(0)}%${pct >= 70 ? " ⚠" : ""}`);
+    }
+    else {
+        parts.push(`ctx ${formatTokens(live.tokens)}`);
+    }
+    if (live.cacheShare !== undefined)
+        parts.push(`cache ${Math.round(live.cacheShare * 100)}%`);
+    if (input.cost?.total_cost_usd && input.cost.total_cost_usd > 0)
+        parts.push(formatUsd(input.cost.total_cost_usd));
+    return parts.join(" · ");
+}
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    return Buffer.concat(chunks).toString("utf8");
+}
+export async function runStatusLine() {
+    try {
+        const input = JSON.parse(await readStdin());
+        const line = renderStatusLine(input);
+        if (line)
+            console.log(line);
+    }
+    catch {
+        /* silent by design */
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "context-doctor",
-  "version": "0.13.5",
+  "version": "0.14.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 test",
     "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 dist/test/accuracy.test.js dist/test/cache-stability.test.js dist/test/ledger.test.js"
+    "test": "npm run build && node scripts/test.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",