context-doctor 0.13.4 → 0.14.1

package/README.md

@@ -92,8 +92,9 @@ Practical upshot: a developer who only wants cheaper, faster API calls never tou
 | `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. `--fail-over-budget` exits 1 on a breach, for CI |
 | `context-doctor optimize <file>` | Apply the safe fixes; add `--strategy trim-tool-calls` for big inline file writes, `--strategy prune-history` for consented lossy compaction |
-| `context-doctor session [file]` | Profile a Claude Code session: live context, findings, **measured tokens and prompt-cache economics**. Also reads ChatGPT data exports (`conversations.json`) |
+| `context-doctor 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
@@ -254,7 +307,7 @@ const { conversation, tokensBefore, tokensAfter } = optimizeConversation(chatJso
 - **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. Counts shell reads too (`cat`, `head`, `tail`, `less`), which is where most of them hide in agent sessions
 - **Retained error output** — stack traces and failed commands kept verbatim long after the fix landed
-- **Repeated identical tool calls** — a signal your agent forgot earlier results
+- **Repeated identical tool calls**, split into the two things they can mean: a **retry** (the same call after a failure, where the fix is in the error text, and three or more is a loop) and a **re-read** (the same call after a success, where the model forgot it already had the answer). Across 42 local sessions that was 15 retries against 151 re-reads, so the old combined advice was wrong for most of them
 - **Base64 / binary blobs** in text content — checked by character distribution, not just alphabet, so hex digests and long identifiers are not mistaken for encoded binary
 - **Long history** past the point where models track the middle
 - **Cache-hostile ordering** — volatile content before stable content breaks prompt caching (Anthropic `cache_control`, OpenAI automatic prefix caching)
@@ -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,13 +24,17 @@ 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";
 import { analyzeCacheUsage, renderCacheReport } from "./cache.js";
+import { renderToolTimings } from "./timing.js";
 const HELP = `context-doctor — profile and optimize LLM context windows
 
 Usage:
@@ -44,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,
@@ -54,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
@@ -87,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":[...],
@@ -103,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];
@@ -151,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;
@@ -243,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) {
@@ -333,7 +387,7 @@ function main() {
         }
         const profile = profileConversation(parseConversation(parsed.conversationJson), args.model ?? parsed.model);
         if (args.json) {
-            console.log(JSON.stringify({ session: { path: parsed.path, title: parsed.title }, profile }, null, 2));
+            console.log(JSON.stringify({ session: { path: parsed.path, title: parsed.title, toolTimings: parsed.toolTimings ?? [] }, profile }, null, 2));
         }
         else {
             console.log(`Session: ${parsed.title ?? "(untitled)"}\nFile:    ${parsed.path}`);
@@ -354,6 +408,11 @@ function main() {
                 console.log("");
                 console.log(cache);
             }
+            const timing = renderToolTimings(parsed.toolTimings ?? []);
+            if (timing) {
+                console.log("");
+                console.log(timing);
+            }
             applyBudgetGate(printBudgetStatus(profile, loadConfig(process.cwd(), (m) => console.error(`context-doctor: ${m}`))), args.failOverBudget);
         }
         return;
@@ -361,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;
     }
@@ -390,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
     }
@@ -418,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}`);
@@ -434,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;