context-doctor 0.29.0 → 0.30.0

package/README.md

@@ -35,6 +35,8 @@ Pick where you work. Each takes about a minute and is fully reversible.
 - `overhead`: what every request re-reads before your message (system prompt, tools, MCP servers, CLAUDE.md, rules, memory), each file priced per month.
 - `tasks`: cost per commit, per project, from each session's recorded usage and its own `git commit` calls.
 - `reads`: the files read into session after session, and whether a CLAUDE.md summary or `pack` would pay.
+- `subagents`: whether each subagent was cheaper than doing the same work in the parent session, and by how much.
+- `cache-plan <request.json>`: where an Anthropic API request should carry `cache_control`, and what it saves over N calls; `--out` writes it applied.
 - `session`, `watch`, `analyze`, `report`, `dashboard`: token breakdown and wasted-context findings for any session, conversation file or agent trace.
 
 **Keep waste out of the context**
@@ -177,6 +179,7 @@ MCP servers are part of the same overhead: each one's tool definitions ride on e
 
 ## What's new
 
+- **0.30 Where the money goes, and a self-healing service**: `context-doctor subagents` compares each subagent's bill with the same work done in the parent session; `cache-plan` places Anthropic `cache_control` breakpoints in an API request and prices them. Fixes from a local audit: the autopilot service now restarts itself onto a newly installed version, `doctor` no longer writes fake hook checks into the activity ledger, and `<synthetic>` placeholder messages no longer hide a session's model.
 - **0.29 Python, and where the work goes**: a dependency-free Python package (`python/`) with `pack_documents` for LangChain and LlamaIndex results, `pack_context`, `estimate_tokens` and `profile_messages`, held byte for byte to the TypeScript by parity tests. `context-doctor reads` shows the files read into session after session; `context-doctor tasks` shows cost per commit per project, from your own transcripts.
 - **0.28 Wider reach**: `/context-doctor:overhead` and `/context-doctor:pack` in the Claude Code plugin; `pack` reads a folder inside a git repository the way git does, so `.gitignore`'d build output and secrets stay out; `withContextDoctor` wraps Google's `@google/genai` client too; `overhead` measures the fixed start-of-session cost of Codex and Gemini CLI sessions as well as Claude Code's, priced with each provider's cache rules.
 - **0.27 Keep waste out**: `pack` and the `pack_context` MCP tool put only the chunks of big files (text, code, PDF, Word, PowerPoint) a question needs into the context, within a budget; `overhead` measures and prices the front matter every request re-reads (system prompt, tools, CLAUDE.md, rules, memory, AGENTS.md, Cursor rules, GEMINI.md). MCP servers sized and their use counted; `overhead split` turns a heavy memory file into a lean one plus a reference file. `withContextDoctor(client)` runs autopilot inside an Anthropic or OpenAI SDK client, for apps with no proxy. Gemini joins: `install` wires Gemini CLI's MCP server and every-prompt hook, `session` and `watch` read its chats, and the proxy and autopilot carry Google's Gemini API. A GitHub Action (and `context-doctor ci`) reports memory-file growth on every pull request and gates on a budget. Re-verified on every surface: 229 tests on macOS, Linux and Windows, plus MCP, OpenAI and Gemini end-to-end smoke runs, now in CI, MCP over stdio and HTTP, the OpenAI proxy, and a live `doctor`.

package/dist/autopilot.d.ts

@@ -33,6 +33,10 @@ export declare function serviceCommand(node: string, cli: string, port: number,
 export declare function launchdPlist(args: string[], log: string): string;
 export declare function systemdUnit(args: string[], log: string): string;
 export declare function windowsTaskCommand(args: string[]): string;
+/** Version of the package a CLI path belongs to (dist/cli.js -> ../package.json). */
+export declare function installedVersion(cli: string): string | undefined;
+/** Restart the installed background service onto the current build (launchd, systemd). */
+export declare function restartService(): boolean;
 export declare function startDetached(args: string[], log: string): void;
 export interface Health {
     ok: boolean;

package/dist/autopilot.js

@@ -19,7 +19,7 @@
  * backend, not an API base URL).
  */
 import { execFileSync, spawn } from "node:child_process";
-import { closeSync, existsSync, mkdirSync, openSync, readdirSync, readSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { closeSync, existsSync, mkdirSync, openSync, readdirSync, readFileSync, readSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { homedir, platform } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -151,6 +151,38 @@ function removeService() {
         tryRun("schtasks", ["/Delete", "/F", "/TN", "context-doctor-proxy"]);
     }
 }
+/** Version of the package a CLI path belongs to (dist/cli.js -> ../package.json). */
+export function installedVersion(cli) {
+    try {
+        return JSON.parse(readFileSync(join(dirname(cli), "..", "package.json"), "utf8")).version;
+    }
+    catch {
+        return undefined;
+    }
+}
+function restartDue(paths) {
+    const marker = join(dirname(paths.log), ".context-doctor-proxy-restart");
+    try {
+        if (existsSync(marker) && Date.now() - statSync(marker).mtimeMs < 3_600_000)
+            return false;
+        mkdirSync(dirname(marker), { recursive: true });
+        writeFileSync(marker, String(Date.now()));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Restart the installed background service onto the current build (launchd, systemd). */
+export function restartService() {
+    const os = platform();
+    const sp = servicePaths();
+    if (os === "darwin" && existsSync(sp.plist))
+        return tryRun("launchctl", ["kickstart", "-k", `gui/${uid()}/${LABEL}`]);
+    if (os === "linux" && existsSync(sp.unit))
+        return tryRun("systemctl", ["--user", "restart", "context-doctor-proxy.service"]);
+    return false;
+}
 export function startDetached(args, log) {
     mkdirSync(dirname(log), { recursive: true });
     const out = openSync(log, "a");
@@ -393,8 +425,17 @@ export async function ensureProxyUp(paths = autopilotPaths()) {
     const cfg = readConfig(paths);
     if (!cfg)
         return;
-    if ((await health(cfg.port, 300)).ok)
+    const h = await health(cfg.port, 300);
+    if (h.ok) {
+        // A service keeps running the code it started with: after an update it
+        // answers fine but is still the old version (seen: 0.25 serving for days
+        // after 0.29 was installed). Restart it onto the installed build, at most
+        // once an hour so an install that cannot fix it never loops.
+        const installed = typeof cfg.cli === "string" ? installedVersion(cfg.cli) : undefined;
+        if (installed && h.version && h.version !== installed && restartDue(paths))
+            restartService();
         return;
+    }
     if (typeof cfg.node !== "string" || typeof cfg.cli !== "string" || !existsSync(cfg.node) || !existsSync(cfg.cli))
         return;
     startDetached(serviceCommand(cfg.node, cfg.cli, cfg.port, paths), paths.log);

package/dist/cacheplan.d.ts

@@ -0,0 +1,45 @@
+/**
+ * `context-doctor cache-plan <request.json>`: where an API app should put
+ * Anthropic `cache_control` breakpoints, and what that saves.
+ *
+ * A request is cached as a prefix in a fixed order: tools, then system, then
+ * messages. A breakpoint caches everything up to and including the block it
+ * sits on, a prefix under the model's minimum (1,024 tokens; 2,048 on Haiku)
+ * is not cached at all, a request may carry at most 4 breakpoints, and the
+ * cache looks back at most 20 blocks from a breakpoint for an earlier hit.
+ * The planner places breakpoints at the ends of the stable parts (last tool,
+ * last system block) and on the last block of the conversation, adds a
+ * middle anchor when the conversation is longer than the 20-block lookback,
+ * prices the request sent N times with and without the plan, and with
+ * --out saves the request with the breakpoints in place.
+ *
+ * Pricing assumes the same request is sent N times (an agent loop's steps, a
+ * shared system prompt and document set); cache writes cost 1.25x input
+ * (2x with ttl "1h"), reads 0.1x.
+ */
+export interface Breakpoint {
+    /** Where: "tools[3]", "system[1]", "messages[12].content[0]". */
+    at: string;
+    /** Prefix tokens cached up to and including this point. */
+    prefixTokens: number;
+    why: string;
+}
+export interface CachePlan {
+    provider: "anthropic" | "openai" | "unknown";
+    model?: string;
+    totalTokens: number;
+    minCacheable: number;
+    existing: string[];
+    plan: Breakpoint[];
+    /** Tokens before the last breakpoint of the plan: what later calls read from cache. */
+    cachedTokens: number;
+    calls: number;
+    usdWithout?: number;
+    usdWith?: number;
+    notes: string[];
+}
+export declare function planCache(request: unknown, calls?: number, modelOverride?: string): {
+    plan: CachePlan;
+    apply: () => Record<string, any>;
+};
+export declare function renderCachePlan(p: CachePlan): string;

package/dist/cacheplan.js

@@ -0,0 +1,180 @@
+/**
+ * `context-doctor cache-plan <request.json>`: where an API app should put
+ * Anthropic `cache_control` breakpoints, and what that saves.
+ *
+ * A request is cached as a prefix in a fixed order: tools, then system, then
+ * messages. A breakpoint caches everything up to and including the block it
+ * sits on, a prefix under the model's minimum (1,024 tokens; 2,048 on Haiku)
+ * is not cached at all, a request may carry at most 4 breakpoints, and the
+ * cache looks back at most 20 blocks from a breakpoint for an earlier hit.
+ * The planner places breakpoints at the ends of the stable parts (last tool,
+ * last system block) and on the last block of the conversation, adds a
+ * middle anchor when the conversation is longer than the 20-block lookback,
+ * prices the request sent N times with and without the plan, and with
+ * --out saves the request with the breakpoints in place.
+ *
+ * Pricing assumes the same request is sent N times (an agent loop's steps, a
+ * shared system prompt and document set); cache writes cost 1.25x input
+ * (2x with ttl "1h"), reads 0.1x.
+ */
+import { estimateTokens, formatTokens } from "./tokens.js";
+import { formatUsd, pricingFor } from "./pricing.js";
+const LOOKBACK_BLOCKS = 20;
+const MAX_BREAKPOINTS = 4;
+function blocksOf(req, model) {
+    const out = [];
+    const mark = (obj) => (on) => {
+        if (on)
+            obj.cache_control = obj.cache_control ?? { type: "ephemeral" };
+        else
+            delete obj.cache_control;
+    };
+    const tok = (x) => estimateTokens(typeof x === "string" ? x : JSON.stringify(x ?? ""), model);
+    (Array.isArray(req.tools) ? req.tools : []).forEach((t, i) => {
+        out.push({ at: `tools[${i}]`, tokens: tok(t), section: "tools", hasBreakpoint: Boolean(t?.cache_control), set: mark(t) });
+    });
+    if (typeof req.system === "string" && req.system) {
+        // A string system prompt cannot carry cache_control: it becomes one text block when planned.
+        const holder = { type: "text", text: req.system };
+        out.push({
+            at: "system[0]",
+            tokens: tok(req.system),
+            section: "system",
+            hasBreakpoint: false,
+            set: (on) => {
+                mark(holder)(on);
+                req.system = on ? [holder] : req.system;
+            },
+        });
+    }
+    else if (Array.isArray(req.system)) {
+        req.system.forEach((b, i) => out.push({ at: `system[${i}]`, tokens: tok(b?.text ?? b), section: "system", hasBreakpoint: Boolean(b?.cache_control), set: mark(b) }));
+    }
+    (Array.isArray(req.messages) ? req.messages : []).forEach((m, i) => {
+        if (typeof m?.content === "string") {
+            const holder = { type: "text", text: m.content };
+            out.push({
+                at: `messages[${i}].content[0]`,
+                tokens: tok(m.content) + 4,
+                section: "messages",
+                hasBreakpoint: false,
+                set: (on) => {
+                    mark(holder)(on);
+                    if (on)
+                        m.content = [holder];
+                },
+            });
+        }
+        else if (Array.isArray(m?.content)) {
+            m.content.forEach((b, j) => {
+                const isImage = b?.type === "image";
+                out.push({ at: `messages[${i}].content[${j}]`, tokens: isImage ? 1600 : tok(b?.text ?? b?.content ?? b) + (j === 0 ? 4 : 0), section: "messages", hasBreakpoint: Boolean(b?.cache_control), set: mark(b) });
+            });
+        }
+    });
+    return out;
+}
+export function planCache(request, calls = 10, modelOverride) {
+    const req = (typeof request === "string" ? JSON.parse(request) : request);
+    const model = modelOverride ?? (typeof req.model === "string" ? req.model : undefined);
+    const notes = [];
+    const isOpenAI = Array.isArray(req.input) || (Array.isArray(req.messages) && req.messages.some((m) => m?.role === "system" || m?.role === "developer" || m?.role === "tool"));
+    if (isOpenAI || /gpt|^o\d/i.test(model ?? "")) {
+        const text = JSON.stringify(req.tools ?? "") + JSON.stringify(req.messages ?? req.input ?? "");
+        notes.push("OpenAI caches automatically: any request prefix over 1,024 tokens that matches an earlier one is billed at the cached rate, with no markers to place.", "What you control is order: keep tools, instructions and reference documents first and identical between calls, and put per-call content last.", "Set `prompt_cache_key` to a stable value per conversation or tenant so requests that share a prefix land on the same cache.");
+        return {
+            plan: { provider: "openai", model, totalTokens: estimateTokens(text, model), minCacheable: 1024, existing: [], plan: [], cachedTokens: 0, calls, notes },
+            apply: () => req,
+        };
+    }
+    const blocks = blocksOf(req, model);
+    const total = blocks.reduce((s, b) => s + b.tokens, 0);
+    const minCacheable = /haiku/i.test(model ?? "") ? 2048 : 1024;
+    const prefixAt = (i) => blocks.slice(0, i + 1).reduce((s, b) => s + b.tokens, 0);
+    const lastIndex = (section) => blocks.map((b) => b.section).lastIndexOf(section);
+    const picks = [];
+    const pick = (i, why) => {
+        if (i < 0 || picks.some((p) => p.i === i) || prefixAt(i) < minCacheable)
+            return;
+        picks.push({ i, why });
+    };
+    const lastMsg = lastIndex("messages");
+    pick(lastIndex("tools"), "end of the tool definitions: stable across every call");
+    pick(lastIndex("system"), "end of the system prompt: stable across every call");
+    // The conversation boundary moves forward each turn; a breakpoint on the last block caches the whole history for the next call.
+    pick(lastMsg, "last block of the conversation: the next call reads everything before it from cache");
+    // Beyond 20 blocks back from the moving breakpoint the cache stops looking; anchor the middle.
+    const firstMsg = blocks.findIndex((b) => b.section === "messages");
+    if (firstMsg >= 0 && lastMsg - firstMsg > LOOKBACK_BLOCKS && picks.length < MAX_BREAKPOINTS) {
+        pick(lastMsg - LOOKBACK_BLOCKS, `anchor ${LOOKBACK_BLOCKS} blocks back: the cache only looks back ${LOOKBACK_BLOCKS} blocks from a breakpoint`);
+    }
+    picks.sort((a, b) => a.i - b.i);
+    while (picks.length > MAX_BREAKPOINTS)
+        picks.splice(1, 1);
+    const existing = blocks.filter((b) => b.hasBreakpoint).map((b) => b.at);
+    if (existing.length > MAX_BREAKPOINTS)
+        notes.push(`The request carries ${existing.length} breakpoints; the API rejects more than ${MAX_BREAKPOINTS}.`);
+    if (total < minCacheable)
+        notes.push(`The whole request is ~${formatTokens(total)} tokens, under the ${formatTokens(minCacheable)} minimum ${model ?? "this model"} caches: caching cannot help until it grows.`);
+    const cachedTokens = picks.length ? prefixAt(picks[picks.length - 1].i) : 0;
+    const price = pricingFor(model);
+    const longTtl = /"ttl"\s*:\s*"1h"/.test(JSON.stringify(req));
+    const writeMult = longTtl ? 2 : 1.25;
+    let usdWithout, usdWith;
+    if (price) {
+        const p = price.inputPerM / 1e6;
+        usdWithout = calls * total * p;
+        const rest = total - cachedTokens;
+        usdWith = cachedTokens * writeMult * p + rest * p + (calls - 1) * (cachedTokens * 0.1 * p + rest * p);
+    }
+    return {
+        plan: {
+            provider: "anthropic",
+            model,
+            totalTokens: total,
+            minCacheable,
+            existing,
+            plan: picks.map((p) => ({ at: blocks[p.i].at, prefixTokens: prefixAt(p.i), why: p.why })),
+            cachedTokens,
+            calls,
+            usdWithout,
+            usdWith,
+            notes,
+        },
+        apply: () => {
+            for (const b of blocks)
+                b.set(false);
+            for (const p of picks)
+                blocks[p.i].set(true);
+            return req;
+        },
+    };
+}
+export function renderCachePlan(p) {
+    const out = ["CACHE PLAN", "═".repeat(56)];
+    out.push(`${p.provider === "openai" ? "OpenAI" : "Anthropic"} request${p.model ? ` for ${p.model}` : ""}: ~${formatTokens(p.totalTokens)} tokens.`);
+    if (p.provider === "openai") {
+        out.push("", ...p.notes.map((n) => `• ${n}`));
+        return out.join("\n");
+    }
+    out.push(`Breakpoints now: ${p.existing.length ? p.existing.join(", ") : "none"}.`, "");
+    if (p.plan.length === 0) {
+        out.push("Nothing to place: no stable prefix reaches the caching minimum.");
+    }
+    else {
+        out.push(`Place cache_control on (${p.plan.length} of ${MAX_BREAKPOINTS} allowed):`);
+        for (const b of p.plan)
+            out.push(`  ${b.at.padEnd(26)} prefix ~${formatTokens(b.prefixTokens).padStart(6)}  ${b.why}`);
+    }
+    if (p.usdWithout !== undefined && p.usdWith !== undefined && p.plan.length) {
+        const saved = p.usdWithout - p.usdWith;
+        out.push("", `Sent ${p.calls} times: ${formatUsd(p.usdWithout)} of input without caching, ${formatUsd(p.usdWith)} with this plan (${saved >= 0 ? "saves" : "costs"} ${formatUsd(Math.abs(saved))}, ${Math.round((Math.abs(saved) / p.usdWithout) * 100)}%).`, `(~${formatTokens(p.cachedTokens)} tokens read at 0.1x after the first call, which writes them once at the cache-write rate.)`);
+    }
+    if (p.notes.length)
+        out.push("", ...p.notes.map((n) => `! ${n}`));
+    if (p.usdWithout === undefined && p.plan.length)
+        out.push("", "Pass --model (e.g. claude-sonnet-5) to price it.");
+    if (p.plan.length)
+        out.push("", "--out <file> saves the request with exactly these breakpoints.");
+    return out.join("\n");
+}

package/dist/cli.js

@@ -47,6 +47,8 @@ import { applySplit, planSplit, renderSplit } from "./split.js";
 import { ciReport, renderCiMarkdown, renderCiText } from "./ci.js";
 import { renderReads, repeatedReads } from "./reads.js";
 import { costPerTask, renderTasks } from "./tasks.js";
+import { planCache, renderCachePlan } from "./cacheplan.js";
+import { renderPayback, subagentPayback } from "./subagentpay.js";
 const HELP = `context-doctor — profile and optimize LLM context windows
 
 Usage:
@@ -104,6 +106,11 @@ Usage:
   context-doctor ci [--base <ref>] [--max-tokens n] [--max-increase n] [--markdown]
                                                 For pull requests: memory files (CLAUDE.md, AGENTS.md,
                                                 GEMINI.md, rules) at HEAD vs base; exit 1 over budget
+  context-doctor cache-plan <request.json> [--calls n] [--out file]
+                                                Where an Anthropic request should carry cache_control,
+                                                what it saves over n calls; --out writes it applied
+  context-doctor subagents [--days n]           Which subagents paid for themselves: their bill vs
+                                                what carrying their reads would have cost the parent
   context-doctor tasks [--days n]               Cost per commit, per project: session cost at list
                                                 price vs commits made during the sessions
   context-doctor reads [--days n] [--limit n]   Files read into session after session: reads, tokens,
@@ -290,6 +297,9 @@ function parseArgs(argv) {
             case "--write":
                 args.write = true;
                 break;
+            case "--calls":
+                args.calls = numArg("--calls", argv[++i], { min: 1, integer: true });
+                break;
             case "--semantic":
                 args.semantic = args.semantic || true;
                 break;
@@ -717,6 +727,32 @@ async function main() {
         });
         return; // server keeps the process alive
     }
+    if (args.command === "subagents") {
+        const report = subagentPayback(args.days ?? 30);
+        console.log(args.json ? JSON.stringify(report, null, 2) : renderPayback(report, args.limit ?? 8));
+        return;
+    }
+    if (args.command === "cache-plan") {
+        const file = args.positionals?.[0];
+        if (!file) {
+            console.error("usage: context-doctor cache-plan <request.json|-> [--calls 10] [--out planned.json]");
+            process.exit(1);
+        }
+        let result;
+        try {
+            result = planCache(readInput(file), args.calls ?? 10, args.model);
+        }
+        catch (e) {
+            console.error(`Could not read a request from ${file}: ${e.message}`);
+            process.exit(1);
+        }
+        console.log(args.json ? JSON.stringify(result.plan, null, 2) : renderCachePlan(result.plan));
+        if (args.out) {
+            writeFileSync(args.out, JSON.stringify(result.apply(), null, 2));
+            console.error(`context-doctor: request with the planned breakpoints written to ${args.out}`);
+        }
+        return;
+    }
     if (args.command === "tasks") {
         const report = costPerTask(args.days ?? 30);
         console.log(args.json ? JSON.stringify(report, null, 2) : renderTasks(report, args.limit ?? 12));

package/dist/dashboard.js

@@ -31,7 +31,8 @@ export async function collectDashboardData(proxyPort = 8787) {
     // Totals folded in when the ledger rotated; excluded from the daily series,
     // which describes individual days rather than a carried-forward sum.
     const carried = foldTotals(ledger.filter((e) => e.ev === "rollup"));
-    const checks = ledger.filter((e) => e.ev === "check" || e.ev === undefined);
+    // "doctor-probe" entries came from `doctor` (before 0.30), not from the hook.
+    const checks = ledger.filter((e) => (e.ev === "check" || e.ev === undefined) && e.sid !== "doctor-probe");
     const optimizes = ledger.filter((e) => e.ev === "optimize");
     // Observed shrinkage: a session getting SMALLER between two deep checks is a
     // real reduction, so it counts alongside explicit optimize runs.

package/dist/doctor.js

@@ -5,13 +5,13 @@
  * check, so "it doesn't work" becomes a single pasteable diagnosis. Always
  * exits 0 — absence of an app is a note, not a failure.
  */
-import { autopilotPaths, health, proxyUrl, recentSurfaces } from "./autopilot.js";
+import { autopilotPaths, health, installedVersion, proxyUrl, recentSurfaces } from "./autopilot.js";
 import { spawn } from "node:child_process";
-import { existsSync, readFileSync } from "node:fs";
+import { accessSync, constants as fsConstants, existsSync, mkdirSync, readFileSync } from "node:fs";
 import { homedir, platform } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { ledgerPath, recordLedger } from "./ledger.js";
+import { ledgerPath } from "./ledger.js";
 import { loadConfig } from "./config.js";
 import { geminiCliPresent, geminiSettingsPath } from "./install.js";
 function claudeDesktopConfigPath() {
@@ -234,10 +234,14 @@ export async function runDoctor() {
     checks.push(existsSync(skillPath)
         ? { label: "Agent Skill", status: "ok", detail: skillPath }
         : { label: "Agent Skill", status: "skip", detail: "not installed (run context-doctor install on a Claude Code machine)" });
-    // Ledger writable
+    // Ledger writable. Tested without writing an entry: recordLedger swallows
+    // errors (so this could never fail), and the entry it wrote counted as a
+    // hook check in every report.
     try {
-        recordLedger({ ev: "check", sid: "doctor-probe", tok: 0, warn: false });
-        checks.push({ label: "Ledger", status: "ok", detail: `writable at ${ledgerPath()}` });
+        const lp = ledgerPath();
+        mkdirSync(dirname(lp), { recursive: true });
+        accessSync(existsSync(lp) ? lp : dirname(lp), fsConstants.W_OK);
+        checks.push({ label: "Ledger", status: "ok", detail: `writable at ${lp}` });
     }
     catch {
         checks.push({ label: "Ledger", status: "fail", detail: `cannot write ${ledgerPath()}` });
@@ -264,6 +268,7 @@ export async function runDoctor() {
         }
         else {
             const cfg = JSON.parse(readFileSync(paths.config, "utf8"));
+            const installed = typeof cfg.cli === "string" ? installedVersion(cfg.cli) : undefined;
             const h = await health(cfg.port);
             let routed = false;
             try {
@@ -283,9 +288,11 @@ export async function runDoctor() {
             const desktopOnly = known.length > 0 && known.every((ep) => ep.startsWith("claude-desktop"));
             checks.push(h.ok && h.autopilot && routed && seen === 0 && desktopOnly
                 ? { label: "Autopilot", status: "warn", detail: "running, but it has seen 0 requests: your recent Claude Code sessions all ran in the desktop app, which ignores settings.json's API address. Autopilot only reaches terminal and IDE sessions; for desktop ones, see `context-doctor compact-window`" }
-                : h.ok && h.autopilot && routed
-                    ? { label: "Autopilot", status: "ok", detail: `proxy up on ${proxyUrl(cfg.port)}, Claude Code routed through it${seen >= 0 ? ` (${seen} requests since start)` : ""}${paused ? " (PAUSED: passthrough)" : ""}` }
-                    : { label: "Autopilot", status: "fail", detail: !h.ok ? `proxy not answering on ${proxyUrl(cfg.port)}: the next Claude Code prompt restarts it; or run: context-doctor autopilot on` : "settings.json no longer routes Claude Code to the proxy: run context-doctor autopilot on" });
+                : h.ok && h.autopilot && routed && h.version && installed && h.version !== installed
+                    ? { label: "Autopilot", status: "warn", detail: `proxy is running v${h.version} but v${installed} is installed; the next Claude Code prompt restarts it, or run: context-doctor autopilot on` }
+                    : h.ok && h.autopilot && routed
+                        ? { label: "Autopilot", status: "ok", detail: `proxy up on ${proxyUrl(cfg.port)}, Claude Code routed through it${seen >= 0 ? ` (${seen} requests since start)` : ""}${paused ? " (PAUSED: passthrough)" : ""}` }
+                        : { label: "Autopilot", status: "fail", detail: !h.ok ? `proxy not answering on ${proxyUrl(cfg.port)}: the next Claude Code prompt restarts it; or run: context-doctor autopilot on` : "settings.json no longer routes Claude Code to the proxy: run context-doctor autopilot on" });
         }
     }
     const mark = { ok: "✓", warn: "!", fail: "✗", skip: "–" };
@@ -295,6 +302,11 @@ export async function runDoctor() {
         console.log(`${mark[c.status]} ${c.label.padEnd(22)} ${c.detail}`);
     }
     const fails = checks.filter((c) => c.status === "fail");
+    const warns = checks.filter((c) => c.status === "warn");
     console.log("");
-    console.log(fails.length === 0 ? "All good." : `${fails.length} issue(s) found — fixes suggested above.`);
+    console.log(fails.length > 0
+        ? `${fails.length} issue(s) found — fixes suggested above.`
+        : warns.length > 0
+            ? `No problems; ${warns.length} note(s) marked ! above.`
+            : "All good.");
 }

package/dist/impact.js

@@ -36,7 +36,8 @@ export async function buildImpactReport(proxyPort = 8787) {
     // Rotation folds dropped entries into a rollup. Counting it is what keeps
     // these lifetime totals from going backwards once the cap is hit.
     const carried = foldTotals(ledger.filter((e) => e.ev === "rollup"));
-    const checks = ledger.filter((e) => e.ev === "check" || e.ev === undefined);
+    // "doctor-probe" entries came from `doctor` (before 0.30), not from the hook.
+    const checks = ledger.filter((e) => (e.ev === "check" || e.ev === undefined) && e.sid !== "doctor-probe");
     const optimizes = ledger.filter((e) => e.ev === "optimize");
     // Observed per-session reductions: when a session SHRANK between two deep
     // checks (compaction/cleanup after a warning), that drop is measured fact.

package/dist/index.d.ts

@@ -34,3 +34,5 @@ export * from "./wrap.js";
 export * from "./ci.js";
 export * from "./reads.js";
 export * from "./tasks.js";
+export * from "./cacheplan.js";
+export * from "./subagentpay.js";

package/dist/index.js

@@ -29,3 +29,5 @@ export * from "./wrap.js";
 export * from "./ci.js";
 export * from "./reads.js";
 export * from "./tasks.js";
+export * from "./cacheplan.js";
+export * from "./subagentpay.js";

package/dist/mcp.js

@@ -52,7 +52,7 @@ const STRATEGY_IDS = ["dedupe", "trim-tool-results", "trim-tool-calls", "strip-b
  * recommended pattern.
  */
 function createServer({ fileAccess = true } = {}) {
-    const server = new McpServer({ name: "context-doctor", version: "0.29.0" }, { instructions: SERVER_INSTRUCTIONS });
+    const server = new McpServer({ name: "context-doctor", version: "0.30.0" }, { instructions: SERVER_INSTRUCTIONS });
     server.tool("profile_context", "Profile an LLM conversation or prompt: token breakdown, largest blocks, and actionable findings about wasted context (duplicates, oversized pastes or tool results, base64 blobs, long history). Two inputs, pass ONE: `conversation` (full OpenAI/Anthropic JSON or raw text, for agents, files and proxies) or `sketch` (for chat apps such as Claude Desktop or ChatGPT where you cannot export the conversation: the turn count plus the few blocks that matter, ~120 tokens to write). Call it whenever the user asks about token usage, context size, cost, speed or limits, and on your own once the conversation passes ~30 turns or holds 3+ large pastes. Act on the top finding in your reply.", {
         conversation: z.string().optional().describe("Conversation JSON (OpenAI or Anthropic format, or bare message array) or raw prompt text. Omit in chat apps and pass `sketch`."),
         sketch: z.object({

package/dist/proxy.d.ts

@@ -48,7 +48,7 @@ export interface ProxyOptions extends OptimizeOptions {
     googleUpstream?: string;
 }
 /** Reported by /health so `autopilot status` can tell an outdated service from a current one. */
-export declare const PROXY_VERSION = "0.29.0";
+export declare const PROXY_VERSION = "0.30.0";
 /**
  * Remove a leading `/t/<token>` from a request path, or return undefined when
  * the prefix is absent or the token differs. The comparison is constant time

package/dist/proxy.js

@@ -20,7 +20,7 @@ import { formatTokens, CHARS_PER_TOKEN, providerFor } from "./tokens.js";
 import { formatUsd, inputCostUsd, pricingFor } from "./pricing.js";
 import { recordLedger } from "./ledger.js";
 /** Reported by /health so `autopilot status` can tell an outdated service from a current one. */
-export const PROXY_VERSION = "0.29.0";
+export const PROXY_VERSION = "0.30.0";
 /** Connection-level headers that must not be forwarded. */
 const SKIP_REQUEST_HEADERS = new Set(["host", "content-length", "connection", "transfer-encoding", "accept-encoding", "expect"]);
 const SKIP_RESPONSE_HEADERS = new Set(["content-length", "content-encoding", "transfer-encoding", "connection"]);

package/dist/reads.js

@@ -11,7 +11,7 @@
  * is cheaper left as a read; `pack` can cut it to the part a question needs).
  */
 import { forEachLine, listSessions } from "./session.js";
-import { estimateTokens, formatTokens } from "./tokens.js";
+import { estimateTokens, formatTokens, realModel } from "./tokens.js";
 import { formatUsd, pricingFor } from "./pricing.js";
 const CLAUDE = "claude-opus-5";
 /** An image in a tool result bills as an image (~1.6k tokens for a full-size screenshot), not as its base64. */
@@ -56,8 +56,7 @@ function sessionReads(path) {
         if (!Array.isArray(content))
             return;
         if (e.type === "assistant") {
-            if (typeof e.message.model === "string")
-                model = e.message.model;
+            model = realModel(e.message.model) ?? model;
             for (const b of content) {
                 if (b?.type === "tool_use" && b.name === "Read" && typeof b.input?.file_path === "string")
                     pending.set(b.id, b.input.file_path);

package/dist/session.js

@@ -8,6 +8,7 @@
  * where `message` is in Anthropic Messages format. Everything else
  * (titles, mode changes, hook records) is metadata and skipped.
  */
+import { realModel } from "./tokens.js";
 import { readdirSync, readFileSync, statSync, existsSync, openSync, readSync, closeSync } from "node:fs";
 import { StringDecoder } from "node:string_decoder";
 import { homedir } from "node:os";
@@ -371,8 +372,7 @@ export function parseSessionFile(path) {
         const message = entry.message;
         if (!message.role || message.content == null)
             return;
-        if (typeof message.model === "string")
-            model = message.model;
+        model = realModel(message.model) ?? model;
         const usage = message.usage;
         if (entry.type === "assistant" && usage) {
             // Coerce, do not trust: a transcript whose usage numbers are STRINGS

package/dist/subagentpay.d.ts

@@ -0,0 +1,46 @@
+/**
+ * `context-doctor subagents`: which subagent tasks pay for themselves.
+ *
+ * The work costs money either way; the question is where it is cheaper. Done
+ * in a subagent it costs the subagent's bill. Done in the parent, the same
+ * steps would have run (at the parent's model price) with the parent's whole
+ * context re-read on every step, and what they read would have stayed in the
+ * parent for its later requests. Per subagent, all measured:
+ *
+ *   in a subagent = its bill
+ *   in the parent = (bill - its own startup context) x parent/subagent price
+ *                 + parent context at launch x steps x 0.1 x parent input price
+ *                 + (read - returned) x (1.25 + 0.1 x later parent requests) x parent input price
+ *
+ * "Read" is the tool output the subagent pulled in; "returned" is what the
+ * parent received (tool result, or a background agent's task notification);
+ * "later requests" run to the next compaction. Measured from transcripts and
+ * subagents/<agent>.meta.json; nothing is sent anywhere.
+ *
+ * It ignores what a subagent buys besides context (parallel time, a clean
+ * window for a hard task) and what the parent would have spent on its own tool
+ * calls, so "did not pay" means "did not pay in context", not "was a mistake".
+ */
+export interface SubagentPayback {
+    id: string;
+    type: string;
+    task: string;
+    costUsd: number;
+    /** What the same work would have cost in the parent. */
+    inParentUsd: number;
+    steps: number;
+    parentContextTokens: number;
+    readTokens: number;
+    returnedTokens: number;
+    laterRequests: number;
+    /** What carrying (read - returned) would have cost the parent. */
+    avoidedUsd: number;
+    netUsd: number;
+}
+export interface PaybackReport {
+    days: number;
+    sessions: number;
+    subagents: SubagentPayback[];
+}
+export declare function subagentPayback(days?: number, paths?: string[]): PaybackReport;
+export declare function renderPayback(r: PaybackReport, top?: number): string;

package/dist/subagentpay.js

@@ -0,0 +1,227 @@
+/**
+ * `context-doctor subagents`: which subagent tasks pay for themselves.
+ *
+ * The work costs money either way; the question is where it is cheaper. Done
+ * in a subagent it costs the subagent's bill. Done in the parent, the same
+ * steps would have run (at the parent's model price) with the parent's whole
+ * context re-read on every step, and what they read would have stayed in the
+ * parent for its later requests. Per subagent, all measured:
+ *
+ *   in a subagent = its bill
+ *   in the parent = (bill - its own startup context) x parent/subagent price
+ *                 + parent context at launch x steps x 0.1 x parent input price
+ *                 + (read - returned) x (1.25 + 0.1 x later parent requests) x parent input price
+ *
+ * "Read" is the tool output the subagent pulled in; "returned" is what the
+ * parent received (tool result, or a background agent's task notification);
+ * "later requests" run to the next compaction. Measured from transcripts and
+ * subagents/<agent>.meta.json; nothing is sent anywhere.
+ *
+ * It ignores what a subagent buys besides context (parallel time, a clean
+ * window for a hard task) and what the parent would have spent on its own tool
+ * calls, so "did not pay" means "did not pay in context", not "was a mistake".
+ */
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { forEachLine, listSessions } from "./session.js";
+import { estimateTokens, formatTokens, realModel } from "./tokens.js";
+import { formatUsd, pricingFor } from "./pricing.js";
+const CLAUDE = "claude-opus-5";
+const IMAGE_TOKENS = 1600;
+function blockTokens(content) {
+    if (typeof content === "string")
+        return estimateTokens(content, CLAUDE);
+    if (!Array.isArray(content))
+        return estimateTokens(JSON.stringify(content ?? ""), CLAUDE);
+    let n = 0;
+    for (const p of content) {
+        if (p?.type === "image")
+            n += IMAGE_TOKENS;
+        else if (typeof p?.text === "string")
+            n += estimateTokens(p.text, CLAUDE);
+        else
+            n += estimateTokens(JSON.stringify(p ?? ""), CLAUDE);
+    }
+    return n;
+}
+/** A subagent's bill (usage priced as the cache bills it), steps, startup context, start time and the tool output it read. */
+function scanSubagent(path) {
+    let costUsd = 0, readTokens = 0, task = "", lastId, model;
+    let steps = 0, startup = 0, start = Infinity;
+    forEachLine(path, (line) => {
+        let e;
+        try {
+            e = JSON.parse(line);
+        }
+        catch {
+            return;
+        }
+        const content = e?.message?.content;
+        if (e?.type === "user") {
+            if (!task && typeof content === "string")
+                task = content;
+            if (Array.isArray(content))
+                for (const b of content)
+                    if (b?.type === "tool_result")
+                        readTokens += blockTokens(b.content);
+            return;
+        }
+        if (e?.type !== "assistant" || !e.message?.usage || e.message.id === lastId)
+            return;
+        lastId = e.message.id;
+        model = realModel(e.message.model) ?? model;
+        const u = e.message.usage;
+        const n = (k) => (typeof u[k] === "number" && u[k] > 0 ? u[k] : 0);
+        const at = Date.parse(e.timestamp);
+        if (Number.isFinite(at))
+            start = Math.min(start, at);
+        if (steps === 0)
+            startup = n("input_tokens") + n("cache_creation_input_tokens") + n("cache_read_input_tokens");
+        steps++;
+        const price = pricingFor(e.message.model ?? model);
+        if (!price)
+            return;
+        costUsd += (n("input_tokens") * price.inputPerM + n("cache_creation_input_tokens") * price.inputPerM * 1.25 +
+            n("cache_read_input_tokens") * price.cacheReadPerM + n("output_tokens") * price.outputPerM) / 1e6;
+    });
+    return { costUsd, readTokens, task: task.replace(/\s+/g, " ").slice(0, 90), steps, startup, start, model };
+}
+function scanParent(path, ids) {
+    const view = { requests: [], prompts: [], compactions: [], returns: new Map() };
+    let lastId;
+    forEachLine(path, (line) => {
+        const hits = [...ids].filter((id) => line.includes(id));
+        const isUsage = line.includes('"usage"');
+        const isCompact = line.includes('"compact_boundary"');
+        if (!hits.length && !isUsage && !isCompact)
+            return;
+        let e;
+        try {
+            e = JSON.parse(line);
+        }
+        catch {
+            return;
+        }
+        const at = Date.parse(e?.timestamp);
+        if (isCompact && e?.subtype === "compact_boundary" && Number.isFinite(at))
+            view.compactions.push(at);
+        // Placeholder messages Claude Code writes itself ("<synthetic>") are not API requests.
+        if (e?.type === "assistant" && !e.isSidechain && e.message?.usage && e.message.id !== lastId && realModel(e.message.model)) {
+            lastId = e.message.id;
+            if (Number.isFinite(at)) {
+                const u = e.message.usage;
+                view.requests.push(at);
+                view.prompts.push((u.input_tokens ?? 0) + (u.cache_creation_input_tokens ?? 0) + (u.cache_read_input_tokens ?? 0));
+            }
+            view.model = realModel(e.message.model) ?? view.model;
+            return;
+        }
+        if (!hits.length || !Number.isFinite(at) || e?.type === "assistant")
+            return;
+        // Background agents report through a task notification; foreground ones through the tool result.
+        const content = e?.message?.content ?? e?.content;
+        const tokens = blockTokens(Array.isArray(content) ? content.map((b) => (b?.type === "tool_result" ? { text: typeof b.content === "string" ? b.content : JSON.stringify(b.content) } : b)) : content);
+        for (const id of hits) {
+            const prev = view.returns.get(id);
+            if (!prev || tokens > prev.tokens)
+                view.returns.set(id, { tokens, at });
+        }
+    });
+    return view;
+}
+export function subagentPayback(days = 30, paths) {
+    const since = Date.now() - days * 86_400_000;
+    const sessions = paths ?? listSessions(10_000).filter((s) => s.path.includes(".claude") && s.modifiedAt.getTime() >= since).map((s) => s.path);
+    const out = [];
+    let withSubagents = 0;
+    for (const parent of sessions) {
+        const dir = join(parent.replace(/\.jsonl$/, ""), "subagents");
+        if (!existsSync(dir))
+            continue;
+        const agents = readdirSync(dir).filter((f) => /^agent-.+\.jsonl$/.test(f));
+        if (!agents.length)
+            continue;
+        withSubagents++;
+        const metas = agents.map((f) => {
+            const id = basename(f, ".jsonl").replace(/^agent-/, "");
+            let meta = {};
+            try {
+                meta = JSON.parse(readFileSync(join(dir, `agent-${id}.meta.json`), "utf8"));
+            }
+            catch { /* older Claude Code: no meta */ }
+            return { id, file: join(dir, f), meta };
+        });
+        const ids = new Set(metas.flatMap((m) => [m.id, m.meta.toolUseId].filter((x) => Boolean(x))));
+        const view = scanParent(parent, ids);
+        const price = pricingFor(view.model);
+        for (const m of metas) {
+            const s = scanSubagent(m.file);
+            const ret = [m.id, m.meta.toolUseId].map((k) => (k ? view.returns.get(k) : undefined)).filter(Boolean).sort((a, b) => b.tokens - a.tokens)[0];
+            const returnedTokens = ret?.tokens ?? 0;
+            const from = ret?.at ?? Infinity;
+            const until = Math.min(...view.compactions.filter((c) => c > from), Infinity);
+            const laterRequests = view.requests.filter((t) => t > from && t < until).length;
+            const carried = Math.max(0, s.readTokens - returnedTokens);
+            // The parent's context when the subagent started: its last request before then.
+            let parentContextTokens = 0;
+            for (let i = 0; i < view.requests.length && view.requests[i] <= s.start; i++)
+                parentContextTokens = view.prompts[i];
+            const sub = pricingFor(s.model) ?? price;
+            let inParentUsd = s.costUsd, avoidedUsd = 0;
+            if (price && sub) {
+                const startupUsd = (s.startup * (1.25 + 0.1 * Math.max(0, s.steps - 1)) * sub.inputPerM) / 1e6;
+                const work = Math.max(0, s.costUsd - startupUsd) * (price.inputPerM / sub.inputPerM);
+                const rideAlong = (parentContextTokens * s.steps * price.cacheReadPerM) / 1e6;
+                avoidedUsd = (carried * (1.25 + 0.1 * laterRequests) * price.inputPerM) / 1e6;
+                inParentUsd = work + rideAlong + avoidedUsd;
+            }
+            out.push({
+                id: m.id,
+                type: m.meta.agentType ?? "unknown",
+                task: m.meta.description ?? s.task,
+                costUsd: s.costUsd,
+                inParentUsd,
+                steps: s.steps,
+                parentContextTokens,
+                readTokens: s.readTokens,
+                returnedTokens,
+                laterRequests,
+                avoidedUsd,
+                netUsd: inParentUsd - s.costUsd,
+            });
+        }
+    }
+    return { days, sessions: withSubagents, subagents: out };
+}
+export function renderPayback(r, top = 8) {
+    const out = ["DO SUBAGENTS PAY FOR THEMSELVES?", "═".repeat(56)];
+    const all = r.subagents;
+    if (!all.length)
+        return [...out, `No subagents in the last ${r.days} days.`].join("\n");
+    const cost = all.reduce((s, a) => s + a.costUsd, 0);
+    const inParent = all.reduce((s, a) => s + a.inParentUsd, 0);
+    const paid = all.filter((a) => a.netUsd > 0);
+    out.push(`Last ${r.days} days: ${all.length} subagents in ${r.sessions} sessions cost ${formatUsd(cost)} at list price.`, `The same work done in the parent would have cost ~${formatUsd(inParent)}: ${paid.length} of ${all.length} were cheaper as subagents, net ${inParent - cost >= 0 ? "+" : "−"}${formatUsd(Math.abs(inParent - cost))}.`, "");
+    const byType = new Map();
+    for (const a of all) {
+        const t = byType.get(a.type) ?? { n: 0, cost: 0, net: 0, paid: 0 };
+        t.n++;
+        t.cost += a.costUsd;
+        t.net += a.netUsd;
+        if (a.netUsd > 0)
+            t.paid++;
+        byType.set(a.type, t);
+    }
+    out.push("  by type                     count      cost    paid off   net");
+    for (const [type, t] of [...byType.entries()].sort((a, b) => b[1].cost - a[1].cost)) {
+        out.push(`  ${type.slice(0, 26).padEnd(26)} ${String(t.n).padStart(6)} ${formatUsd(t.cost).padStart(9)} ${`${t.paid}/${t.n}`.padStart(10)}   ${t.net >= 0 ? "+" : "−"}${formatUsd(Math.abs(t.net))}`);
+    }
+    const worst = [...all].sort((a, b) => a.netUsd - b.netUsd).slice(0, top).filter((a) => a.netUsd < 0);
+    if (worst.length) {
+        out.push("", "Would have been cheaper in the parent:");
+        for (const a of worst)
+            out.push(`  −${formatUsd(-a.netUsd).padEnd(8)} ${String(a.steps).padStart(3)} steps, parent at ~${formatTokens(a.parentContextTokens)}, read ~${formatTokens(a.readTokens)}  ${a.task}`);
+    }
+    out.push("", "Counts context only: a subagent can still be worth it for parallel time or a clean window on a hard task.", "Subagents pay most when the parent is already large (every step there re-reads it) and least for short tasks from a small parent.");
+    return out.join("\n");
+}

package/dist/tasks.js

@@ -16,6 +16,7 @@
  * history showed hundreds). Commits made by hand are not counted, nor is
  * subagent traffic.
  */
+import { realModel } from "./tokens.js";
 import { basename } from "node:path";
 import { forEachLine, listSessions } from "./session.js";
 import { formatUsd, pricingFor } from "./pricing.js";
@@ -65,8 +66,7 @@ export function sessionCost(path) {
             start = Math.min(start, at);
             end = Math.max(end, at);
         }
-        if (typeof e.message.model === "string")
-            model = e.message.model;
+        model = realModel(e.message.model) ?? model;
         const price = pricingFor(e.message.model ?? model);
         if (!price)
             return;

package/dist/tokens.d.ts

@@ -47,3 +47,10 @@ export declare function estimateTokens(text: string, model?: string): number;
 /** Per-message structural overhead (role markers, delimiters) is roughly constant. */
 export declare const MESSAGE_OVERHEAD_TOKENS = 4;
 export declare function formatTokens(n: number): string;
+/**
+ * A transcript's model field, unless it is a placeholder: Claude Code writes
+ * "<synthetic>" on messages it generates itself (errors, interruptions), and
+ * taking the last model seen made a session's model unknown to pricing and
+ * window math whenever one came last.
+ */
+export declare function realModel(model: unknown): string | undefined;

package/dist/tokens.js

@@ -114,3 +114,12 @@ export function formatTokens(n) {
         return `${(n / 1000).toFixed(1)}k`;
     return String(n);
 }
+/**
+ * A transcript's model field, unless it is a placeholder: Claude Code writes
+ * "<synthetic>" on messages it generates itself (errors, interruptions), and
+ * taking the last model seen made a session's model unknown to pricing and
+ * window math whenever one came last.
+ */
+export function realModel(model) {
+    return typeof model === "string" && model && !model.startsWith("<") ? model : undefined;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "context-doctor",
-  "version": "0.29.0",
+  "version": "0.30.0",
   "description": "Cut your Claude Code bill, measured on your own sessions: `npx context-doctor savings` shows what each lever saves, then the hook, autopilot and an earlier auto-compact window do it. Also Cursor, Codex, Claude Desktop and any Anthropic or OpenAI API app. MCP server and Claude Code plugin.",
   "keywords": [
     "agent",