context-doctor 0.13.4 → 0.14.1

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.4" }, { 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/parse.d.ts

@@ -22,6 +22,13 @@ export interface NormalizedMessage {
     toolCallText?: string;
     /** True when the content contained non-text blocks (images, documents). */
     hasBinary: boolean;
+    /**
+     * For tool results: the tool reported failure (Anthropic `is_error`).
+     * What separates a retry from a re-read: the same call after an error is
+     * the model trying again; the same call after a success is the model having
+     * forgotten it already had the answer. Different problems, different fixes.
+     */
+    isError?: boolean;
 }
 export interface NormalizedConversation {
     messages: NormalizedMessage[];

package/dist/parse.js

@@ -18,6 +18,7 @@ function flattenContent(content) {
     let toolName;
     let kind;
     let toolCallText = "";
+    let isError;
     for (const block of content) {
         if (block == null || typeof block !== "object") {
             text += String(block ?? "");
@@ -41,6 +42,8 @@ function flattenContent(content) {
                 const inner = flattenContent(b.content);
                 hasBinary = hasBinary || inner.hasBinary;
                 text += inner.text;
+                if (b.is_error === true)
+                    isError = true;
                 break;
             }
             case "image":
@@ -60,7 +63,7 @@ function flattenContent(content) {
                 text += JSON.stringify(b);
         }
     }
-    return { text, hasBinary, toolName, kind, toolCallText: toolCallText || undefined };
+    return { text, hasBinary, toolName, kind, toolCallText: toolCallText || undefined, isError };
 }
 function normalizeMessage(rawInput, index) {
     // A null or non-object entry appears in truncated and hand-edited files.
@@ -88,7 +91,7 @@ function normalizeMessage(rawInput, index) {
         text += calls;
         toolCallText = (toolCallText ?? "") + calls;
     }
-    return { index, role, kind, text, toolName, toolCallText, hasBinary: flat.hasBinary };
+    return { index, role, kind, text, toolName, toolCallText, hasBinary: flat.hasBinary, isError: flat.isError };
 }
 export function parseConversation(input) {
     let data;

package/dist/profile.d.ts

@@ -12,7 +12,7 @@ export interface MessageProfile {
     preview: string;
     toolName?: string;
 }
-export type FindingId = "large_tool_result" | "large_tool_call" | "duplicate_content" | "near_duplicate" | "repeated_tool_call" | "repeated_file_read" | "retained_error_output" | "base64_blob" | "long_history" | "large_system_prompt" | "cache_ordering" | "near_window_limit";
+export type FindingId = "large_tool_result" | "large_tool_call" | "duplicate_content" | "near_duplicate" | "repeated_tool_call" | "retried_tool_call" | "repeated_file_read" | "retained_error_output" | "base64_blob" | "long_history" | "large_system_prompt" | "cache_ordering" | "near_window_limit";
 export interface Finding {
     id: FindingId;
     severity: "info" | "warn" | "high";
@@ -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 = {
@@ -259,14 +262,38 @@ export function profileConversation(conv, model) {
         list.push(p.msg.index);
         callSeen.set(key, list);
     }
+    // Identical calls come in two kinds that look the same and mean the
+    // opposite. If the previous attempt FAILED, the repeat is a retry: the fix is
+    // in the error text, and hammering the same command is the waste. If the
+    // previous attempt SUCCEEDED, the repeat is a re-read: the model forgot it
+    // already had the answer, and the earlier result is what should have stayed
+    // in view. Lumping them together gave the wrong advice to both.
+    const resultAfter = (callIndex) => perMessage.find((p) => p.msg.index > callIndex && p.msg.kind === "tool_result")?.msg;
     for (const [, idxs] of callSeen) {
-        if (idxs.length > 1) {
+        if (idxs.length < 2)
+            continue;
+        // Each repeat is classified by what happened to the attempt just before it.
+        const retries = idxs.slice(1).filter((_, i) => resultAfter(idxs[i])?.isError === true).length;
+        const rereads = idxs.length - 1 - retries;
+        if (retries > 0) {
+            findings.push({
+                id: "retried_tool_call",
+                severity: retries >= 3 ? "warn" : "info",
+                estSavings: 0,
+                message: `The same tool call was retried ${retries} time(s) after it failed (messages #${idxs.join(", #")}).`,
+                suggestion: retries >= 3
+                    ? "Three or more identical retries of a failing command is a loop. Each attempt keeps its error output in context; the answer is in the first error, not in the fourth attempt."
+                    : "A retry after a failure is normal once. The failed attempt's output stays in context though, so once the fix is understood the earlier error can go.",
+                messages: idxs,
+            });
+        }
+        if (rereads > 0) {
             findings.push({
                 id: "repeated_tool_call",
                 severity: "info",
                 estSavings: 0,
-                message: `The same tool call (with identical arguments) appears ${idxs.length} times (messages #${idxs.join(", #")}).`,
-                suggestion: "Repeated identical calls usually mean the earlier result scrolled out of the model's attention — cache results or surface them in a compact recap instead of re-calling.",
+                message: `The same tool call (with identical arguments) was repeated ${rereads} time(s) after it had already succeeded (messages #${idxs.join(", #")}).`,
+                suggestion: "Repeating a call that already succeeded means the earlier result scrolled out of the model's attention — keep results in a compact recap instead of re-calling.",
                 messages: idxs,
             });
         }
@@ -421,6 +448,7 @@ export function profileConversation(conv, model) {
         totalEstSavings,
         cost,
         sourceFormat: conv.sourceFormat,
+        calibration: calibration.samples > 0 ? calibration : undefined,
         parseWarning: conv.parseWarning,
     };
 }