context-doctor 0.31.1 → 0.32.0

package/dist/autopilot.d.ts

@@ -30,13 +30,26 @@ export declare function autopilotPaths(home?: string): AutopilotPaths;
 export declare function proxyUrl(port: number): string;
 /** The command the service runs. Absolute paths: services start with an empty PATH. */
 export declare function serviceCommand(node: string, cli: string, port: number, paths: AutopilotPaths): string[];
+/**
+ * The service restarts the proxy when it fails, not when it exits 0. The
+ * proxy exits 0 when another context-doctor proxy already serves its port;
+ * with KeepAlive true (Restart=always) launchd restarted it into the same
+ * EADDRINUSE every 5 s, 45 times in one real log.
+ */
 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;
+/**
+ * Runs a service-manager command, true on success. Injectable so tests can
+ * use a throwaway HOME without ever reaching the real launchd, systemd or
+ * Task Scheduler: those name the service globally (a label, a unit name, a
+ * task name), not per HOME.
+ */
+export type ServiceExec = (cmd: string, args: string[]) => boolean;
 /** 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 restartService(home?: string, exec?: ServiceExec): boolean;
 export declare function startDetached(args: string[], log: string): void;
 export interface Health {
     ok: boolean;
@@ -44,6 +57,13 @@ export interface Health {
     version?: string;
 }
 export declare function health(port: number, timeoutMs?: number): Promise<Health>;
+/**
+ * The ANTHROPIC_BASE_URL `off` should restore, decided at `on`: the one an
+ * earlier `on` recorded, else what settings.json holds now, but never our own
+ * proxy's. With the config damaged, settings.json already holds the proxy URL
+ * from the last `on`, and recording that made `off` put the proxy URL back.
+ */
+export declare function baseUrlToRestore(paths: AutopilotPaths, port: number, current: string | null): string | null;
 /** Which Claude Code surfaces ran recent sessions: entrypoint -> count. */
 export declare function recentSurfaces(days?: number, home?: string): Map<string, number>;
 /** Lines explaining which recent sessions autopilot can reach, or nothing when all can. */
@@ -53,11 +73,11 @@ export declare function autopilotOn(port?: number, paths?: AutopilotPaths): Prom
     ok: boolean;
     lines: string[];
 }>;
-export declare function autopilotOff(paths?: AutopilotPaths): Promise<string[]>;
+export declare function autopilotOff(paths?: AutopilotPaths, exec?: ServiceExec): Promise<string[]>;
 export declare function autopilotPause(paused: boolean, paths?: AutopilotPaths): string;
 export declare function autopilotStatus(paths?: AutopilotPaths): Promise<string[]>;
 /**
  * Called by the every-prompt hook: if autopilot is on and the proxy is down,
  * start it before the prompt's request goes out. Returns quickly either way.
  */
-export declare function ensureProxyUp(paths?: AutopilotPaths): Promise<void>;
+export declare function ensureProxyUp(paths?: AutopilotPaths, exec?: ServiceExec): Promise<void>;

package/dist/autopilot.js

@@ -44,6 +44,12 @@ export function proxyUrl(port) {
 export function serviceCommand(node, cli, port, paths) {
     return [node, cli, "proxy", "--autopilot", "--port", String(port), "--autopilot-state", paths.statePath, "--autopilot-pause-file", paths.pauseFile];
 }
+/**
+ * The service restarts the proxy when it fails, not when it exits 0. The
+ * proxy exits 0 when another context-doctor proxy already serves its port;
+ * with KeepAlive true (Restart=always) launchd restarted it into the same
+ * EADDRINUSE every 5 s, 45 times in one real log.
+ */
 export function launchdPlist(args, log) {
     const esc = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
     return `<?xml version="1.0" encoding="UTF-8"?>
@@ -56,7 +62,7 @@ export function launchdPlist(args, log) {
 ${args.map((a) => `    <string>${esc(a)}</string>`).join("\n")}
   </array>
   <key>RunAtLoad</key><true/>
-  <key>KeepAlive</key><true/>
+  <key>KeepAlive</key><dict><key>SuccessfulExit</key><false/></dict>
   <key>ThrottleInterval</key><integer>5</integer>
   <key>StandardOutPath</key><string>${esc(log)}</string>
   <key>StandardErrorPath</key><string>${esc(log)}</string>
@@ -71,7 +77,7 @@ Description=context-doctor proxy (autopilot)
 
 [Service]
 ExecStart=${args.map(q).join(" ")}
-Restart=always
+Restart=on-failure
 RestartSec=2
 StandardOutput=append:${log}
 StandardError=append:${log}
@@ -89,6 +95,10 @@ function servicePaths(home = homedir()) {
         unit: join(home, ".config", "systemd", "user", "context-doctor-proxy.service"),
     };
 }
+/** The home directory a set of autopilot paths belongs to (<home>/.claude/settings.json). */
+function homeOf(paths) {
+    return dirname(dirname(paths.settings));
+}
 function uid() {
     return String(process.getuid?.() ?? "");
 }
@@ -105,9 +115,9 @@ function tryRun(cmd, args) {
     }
 }
 /** Install and start the background service for this platform. */
-function installService(args, log) {
+function installService(args, log, home = homedir()) {
     const os = platform();
-    const sp = servicePaths();
+    const sp = servicePaths(home);
     if (os === "darwin") {
         mkdirSync(dirname(sp.plist), { recursive: true });
         writeFileSync(sp.plist, launchdPlist(args, log));
@@ -133,24 +143,51 @@ function installService(args, log) {
     startDetached(args, log);
     return "detached process";
 }
-function removeService() {
+/**
+ * Stop and remove the service, but only one this HOME installed: launchd,
+ * systemd and Task Scheduler name it globally, so `off` run against another
+ * HOME (a test's throwaway one) would otherwise stop the real service. The
+ * plist or unit file is the proof on macOS and Linux; Windows has no file,
+ * so the caller says whether this HOME's autopilot config exists.
+ */
+function removeService(home, exec, windowsTaskOwned) {
     const os = platform();
-    const sp = servicePaths();
+    const sp = servicePaths(home);
     if (os === "darwin") {
-        tryRun("launchctl", ["bootout", `gui/${uid()}`, sp.plist]);
-        if (existsSync(sp.plist))
-            rmSync(sp.plist);
+        if (!existsSync(sp.plist))
+            return;
+        exec("launchctl", ["bootout", `gui/${uid()}`, sp.plist]);
+        rmSync(sp.plist);
     }
     else if (os === "linux") {
-        tryRun("systemctl", ["--user", "disable", "--now", "context-doctor-proxy.service"]);
-        if (existsSync(sp.unit))
-            rmSync(sp.unit);
-        tryRun("systemctl", ["--user", "daemon-reload"]);
+        if (!existsSync(sp.unit))
+            return;
+        exec("systemctl", ["--user", "disable", "--now", "context-doctor-proxy.service"]);
+        rmSync(sp.unit);
+        exec("systemctl", ["--user", "daemon-reload"]);
     }
     else if (os === "win32") {
-        tryRun("schtasks", ["/Delete", "/F", "/TN", "context-doctor-proxy"]);
+        if (windowsTaskOwned)
+            exec("schtasks", ["/Delete", "/F", "/TN", "context-doctor-proxy"]);
     }
 }
+/**
+ * Start the installed service through its manager, when this HOME has one.
+ * False when there is none or the manager refused, so the caller can start
+ * the proxy itself. kickstart without -k (and systemctl start) leave a
+ * running proxy alone: a /health that was merely slow must not start a
+ * second copy next to the managed one.
+ */
+function startService(home, exec) {
+    const os = platform();
+    const sp = servicePaths(home);
+    if (os === "darwin" && existsSync(sp.plist)) {
+        return exec("launchctl", ["kickstart", `gui/${uid()}/${LABEL}`]) || exec("launchctl", ["bootstrap", `gui/${uid()}`, sp.plist]);
+    }
+    if (os === "linux" && existsSync(sp.unit))
+        return exec("systemctl", ["--user", "start", "context-doctor-proxy.service"]);
+    return false;
+}
 /** Version of the package a CLI path belongs to (dist/cli.js -> ../package.json). */
 export function installedVersion(cli) {
     try {
@@ -174,13 +211,13 @@ function restartDue(paths) {
     }
 }
 /** Restart the installed background service onto the current build (launchd, systemd). */
-export function restartService() {
+export function restartService(home = homedir(), exec = tryRun) {
     const os = platform();
-    const sp = servicePaths();
+    const sp = servicePaths(home);
     if (os === "darwin" && existsSync(sp.plist))
-        return tryRun("launchctl", ["kickstart", "-k", `gui/${uid()}/${LABEL}`]);
+        return exec("launchctl", ["kickstart", "-k", `gui/${uid()}/${LABEL}`]);
     if (os === "linux" && existsSync(sp.unit))
-        return tryRun("systemctl", ["--user", "restart", "context-doctor-proxy.service"]);
+        return exec("systemctl", ["--user", "restart", "context-doctor-proxy.service"]);
     return false;
 }
 export function startDetached(args, log) {
@@ -210,6 +247,29 @@ async function waitHealthy(port, ms) {
         await new Promise((r) => setTimeout(r, 250));
     }
 }
+/**
+ * Whether a base URL is this autopilot's proxy: the configured port's URL, or,
+ * when the config exists but cannot be read (so the port is unknown), any URL
+ * of the exact shape autopilot writes, http://127.0.0.1:<port>.
+ */
+function isOurProxyUrl(url, port, paths) {
+    if (port !== undefined && url === proxyUrl(port))
+        return true;
+    const damaged = existsSync(paths.config) && readConfig(paths) === undefined;
+    return damaged && /^http:\/\/127\.0\.0\.1:\d+$/.test(url);
+}
+/**
+ * The ANTHROPIC_BASE_URL `off` should restore, decided at `on`: the one an
+ * earlier `on` recorded, else what settings.json holds now, but never our own
+ * proxy's. With the config damaged, settings.json already holds the proxy URL
+ * from the last `on`, and recording that made `off` put the proxy URL back.
+ */
+export function baseUrlToRestore(paths, port, current) {
+    const prev = readConfig(paths);
+    if (prev?.previousBaseUrl !== undefined)
+        return prev.previousBaseUrl;
+    return current && isOurProxyUrl(current, port, paths) ? null : current;
+}
 function readConfig(paths) {
     // readJson returns {} for a missing file; only a file with a port is a config.
     if (!existsSync(paths.config))
@@ -322,17 +382,16 @@ export async function autopilotOn(port = DEFAULT_AUTOPILOT_PORT, paths = autopil
         }
     }
     const args = serviceCommand(process.execPath, cli, port, paths);
-    const how = installService(args, paths.log);
+    const how = installService(args, paths.log, homeOf(paths));
     const h = await waitHealthy(port, 15_000);
     if (!h.ok || !h.autopilot) {
-        removeService();
+        removeService(homeOf(paths), tryRun, true);
         return { ok: false, lines: [`✗ The proxy did not come up on port ${port} (log: ${paths.log}). Nothing was changed in Claude Code's settings.`] };
     }
     lines.push(`✓ Proxy running with autopilot on ${proxyUrl(port)} (${how})`);
     const settings = readJson(paths.settings);
     const env = (settings.env ??= {});
-    const prev = readConfig(paths);
-    const previousBaseUrl = prev?.previousBaseUrl !== undefined ? prev.previousBaseUrl : (env.ANTHROPIC_BASE_URL ?? null);
+    const previousBaseUrl = baseUrlToRestore(paths, port, env.ANTHROPIC_BASE_URL ?? null);
     if (previousBaseUrl && previousBaseUrl !== proxyUrl(port)) {
         lines.push(`! settings.json already routed Claude Code to ${previousBaseUrl}; autopilot forwards to api.anthropic.com instead. \`autopilot off\` restores it.`);
     }
@@ -348,14 +407,19 @@ export async function autopilotOn(port = DEFAULT_AUTOPILOT_PORT, paths = autopil
     lines.push(`  GPT apps on your own OpenAI key get the same: export OPENAI_BASE_URL=${proxyUrl(port)}/v1`);
     return { ok: true, lines };
 }
-export async function autopilotOff(paths = autopilotPaths()) {
+export async function autopilotOff(paths = autopilotPaths(), exec = tryRun) {
     const lines = [];
     const cfg = readConfig(paths);
     const settings = readJson(paths.settings);
     const env = settings.env;
-    if (env?.ANTHROPIC_BASE_URL && cfg && env.ANTHROPIC_BASE_URL === proxyUrl(cfg.port)) {
-        if (cfg.previousBaseUrl)
-            env.ANTHROPIC_BASE_URL = cfg.previousBaseUrl;
+    // With the config damaged its port is unknown; the proxy URL in settings
+    // must still go, or every new Claude Code session points at a proxy whose
+    // service is being removed.
+    const ours = env?.ANTHROPIC_BASE_URL ? isOurProxyUrl(env.ANTHROPIC_BASE_URL, cfg?.port, paths) : false;
+    if (env && ours) {
+        const restore = cfg?.previousBaseUrl && !isOurProxyUrl(cfg.previousBaseUrl, cfg.port, paths) ? cfg.previousBaseUrl : undefined;
+        if (restore)
+            env.ANTHROPIC_BASE_URL = restore;
         else
             delete env.ANTHROPIC_BASE_URL;
         if (Object.keys(env).length === 0)
@@ -363,7 +427,7 @@ export async function autopilotOff(paths = autopilotPaths()) {
         writeJsonWithBackup(paths.settings, settings);
         lines.push("✓ Claude Code no longer routed through the proxy (new sessions)");
     }
-    removeService();
+    removeService(homeOf(paths), exec, Boolean(cfg) || existsSync(paths.config));
     if (existsSync(paths.config))
         rmSync(paths.config);
     if (existsSync(paths.pauseFile))
@@ -421,7 +485,7 @@ export async function autopilotStatus(paths = autopilotPaths()) {
  * Called by the every-prompt hook: if autopilot is on and the proxy is down,
  * start it before the prompt's request goes out. Returns quickly either way.
  */
-export async function ensureProxyUp(paths = autopilotPaths()) {
+export async function ensureProxyUp(paths = autopilotPaths(), exec = tryRun) {
     const cfg = readConfig(paths);
     if (!cfg)
         return;
@@ -433,7 +497,14 @@ export async function ensureProxyUp(paths = autopilotPaths()) {
         // 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();
+            restartService(homeOf(paths), exec);
+        return;
+    }
+    // A service manager owns the proxy here: ask it. A detached copy started
+    // because /health missed 300 ms (a busy proxy, not a dead one) took the
+    // port from the managed job, which then crash-looped on EADDRINUSE.
+    if (startService(homeOf(paths), exec)) {
+        await waitHealthy(cfg.port, 2500);
         return;
     }
     if (typeof cfg.node !== "string" || typeof cfg.cli !== "string" || !existsSync(cfg.node) || !existsSync(cfg.cli))

package/dist/cache.d.ts

@@ -4,14 +4,18 @@
  * Transcripts record what the API actually charged per request — including
  * cache reads and cache writes — so cache behaviour can be reported as fact
  * rather than estimated. This is usually the largest single lever on cost:
- * a cached read bills at ~10% of input, while a cache write bills at ~125%,
- * so a session that keeps invalidating its prefix pays more than one with no
+ * a cached read bills at a tenth of input or less, while a cache write bills
+ * at 1.25x (2x at the 1-hour TTL Claude Code's main thread uses), so a
+ * session that keeps invalidating its prefix pays more than one with no
  * caching at all.
  */
 export interface CacheUsage {
+    /** API requests: each reply once, however many transcript rows it was written as. */
     requests: number;
     cacheReadTokens: number;
     cacheWriteTokens: number;
+    /** The part of cacheWriteTokens written at the 1-hour TTL (2x input instead of 1.25x). */
+    cacheWrite1hTokens: number;
     uncachedTokens: number;
     /** Share of input tokens served from cache (0-1). */
     hitRate: number;

package/dist/cache.js

@@ -4,14 +4,15 @@
  * Transcripts record what the API actually charged per request — including
  * cache reads and cache writes — so cache behaviour can be reported as fact
  * rather than estimated. This is usually the largest single lever on cost:
- * a cached read bills at ~10% of input, while a cache write bills at ~125%,
- * so a session that keeps invalidating its prefix pays more than one with no
+ * a cached read bills at a tenth of input or less, while a cache write bills
+ * at 1.25x (2x at the 1-hour TTL Claude Code's main thread uses), so a
+ * session that keeps invalidating its prefix pays more than one with no
  * caching at all.
  */
 import { readFileSync } from "node:fs";
-import { pricingFor } from "./pricing.js";
-/** Cache pricing multipliers relative to the base input rate. */
-const CACHE_WRITE_MULTIPLIER = 1.25;
+import { cacheWriteSplit, pricingFor, usageCost } from "./pricing.js";
+import { replyCounter } from "./session.js";
+import { realModel } from "./tokens.js";
 export function analyzeCacheUsage(transcriptPath) {
     let raw;
     try {
@@ -23,8 +24,17 @@ export function analyzeCacheUsage(transcriptPath) {
     let requests = 0;
     let cacheReadTokens = 0;
     let cacheWriteTokens = 0;
+    let cacheWrite1hTokens = 0;
     let uncachedTokens = 0;
     let model;
+    let priced = 0;
+    let paidUsd = 0;
+    let uncachedUsd = 0;
+    let writeUsd = 0;
+    // Claude Code writes ~2.2 rows per API reply, each carrying the reply's
+    // full usage: counting rows reported 1201 requests for 541 replies on a
+    // real session and more than doubled every total.
+    const sighting = replyCounter();
     for (const line of raw.split("\n")) {
         if (!line.trim())
             continue;
@@ -40,12 +50,29 @@ export function analyzeCacheUsage(transcriptPath) {
         const usage = entry.message.usage;
         if (!usage)
             continue;
+        // "<synthetic>" rows are messages Claude Code writes itself, not requests.
+        if (typeof entry.message.model === "string" && !realModel(entry.message.model))
+            continue;
+        if (sighting(entry) !== "new")
+            continue;
+        model = realModel(entry.message.model) ?? model;
         requests++;
-        cacheReadTokens += usage.cache_read_input_tokens ?? 0;
-        cacheWriteTokens += usage.cache_creation_input_tokens ?? 0;
-        uncachedTokens += usage.input_tokens ?? 0;
-        if (typeof entry.message.model === "string")
-            model = entry.message.model;
+        const read = usage.cache_read_input_tokens ?? 0;
+        const write = usage.cache_creation_input_tokens ?? 0;
+        const fresh = usage.input_tokens ?? 0;
+        cacheReadTokens += read;
+        cacheWriteTokens += write;
+        cacheWrite1hTokens += cacheWriteSplit(usage).oneHour;
+        uncachedTokens += fresh;
+        // Each request at its own model's price: a session can switch models.
+        const pricing = pricingFor(model);
+        if (pricing) {
+            const cost = usageCost(usage, pricing);
+            priced++;
+            paidUsd += cost.promptUsd;
+            writeUsd += cost.writeUsd;
+            uncachedUsd += ((fresh + read + write) * pricing.inputPerM) / 1_000_000;
+        }
     }
     if (requests === 0)
         return null;
@@ -54,19 +81,15 @@ export function analyzeCacheUsage(transcriptPath) {
         requests,
         cacheReadTokens,
         cacheWriteTokens,
+        cacheWrite1hTokens,
         uncachedTokens,
         hitRate: totalInput > 0 ? cacheReadTokens / totalInput : 0,
         model,
     };
-    const pricing = pricingFor(model);
-    if (pricing) {
-        const perM = (tokens, rate) => (tokens / 1_000_000) * rate;
-        const readUsd = perM(cacheReadTokens, pricing.cacheReadPerM);
-        const writeUsd = perM(cacheWriteTokens, pricing.inputPerM * CACHE_WRITE_MULTIPLIER);
-        const freshUsd = perM(uncachedTokens, pricing.inputPerM);
-        usage.paidUsd = readUsd + writeUsd + freshUsd;
-        usage.uncachedUsd = perM(totalInput, pricing.inputPerM);
-        usage.savedUsd = usage.uncachedUsd - usage.paidUsd;
+    if (priced > 0) {
+        usage.paidUsd = paidUsd;
+        usage.uncachedUsd = uncachedUsd;
+        usage.savedUsd = uncachedUsd - paidUsd;
         usage.writeUsd = writeUsd;
     }
     return usage;
@@ -80,18 +103,20 @@ export function renderCacheReport(usage) {
     const fmt = (n) => (n >= 1 ? `$${n.toFixed(2)}` : `$${n.toFixed(3)}`);
     const tok = (n) => n >= 1e6 ? `${(n / 1e6).toFixed(1)}M` : n >= 1e3 ? `${Math.round(n / 1e3)}k` : String(n);
     lines.push(`Prompt cache: ${pct}% of input served from cache across ${usage.requests} requests`);
-    lines.push(`  read ${tok(usage.cacheReadTokens)} · written ${tok(usage.cacheWriteTokens)} · uncached ${tok(usage.uncachedTokens)}`);
+    const oneHour = usage.cacheWrite1hTokens > 0 ? ` (${tok(usage.cacheWrite1hTokens)} at the 1-hour TTL)` : "";
+    lines.push(`  read ${tok(usage.cacheReadTokens)} · written ${tok(usage.cacheWriteTokens)}${oneHour} · uncached ${tok(usage.uncachedTokens)}`);
     if (usage.paidUsd !== undefined && usage.uncachedUsd !== undefined && usage.savedUsd !== undefined) {
         lines.push(`  input cost ${fmt(usage.paidUsd)} — caching saved ${fmt(usage.savedUsd)} against ${fmt(usage.uncachedUsd)} uncached (list prices)`);
     }
-    // A cache write costs 1.25x input while a read costs 0.1x, so writes that
-    // rival reads mean the prefix keeps changing and caching is losing money.
+    // A cache write costs 1.25-2x input while a read costs 0.1x or less, so
+    // writes that rival reads mean the prefix keeps changing and caching is
+    // losing money.
     const writeShare = usage.cacheReadTokens > 0 ? usage.cacheWriteTokens / usage.cacheReadTokens : Infinity;
     if (usage.hitRate < 0.5 && usage.requests > 5) {
         lines.push("  ⚠ Low hit rate: something early in the prompt changes between requests. Keep the system prompt, tool list and reference docs byte-stable and put volatile content last.");
     }
     else if (writeShare > 0.5) {
-        lines.push("  ⚠ Cache churn: writes are large relative to reads, and a write costs 1.25x input against 0.1x for a read. The cached prefix is being rebuilt often.");
+        lines.push("  ⚠ Cache churn: writes are large relative to reads, and a write costs 1.25x input (2x at the 1-hour TTL) against 0.1x or less for a read. The cached prefix is being rebuilt often.");
     }
     return lines.join("\n");
 }

package/dist/cacheplan.d.ts

@@ -4,9 +4,10 @@
  *
  * 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.
+ * sits on, a prefix under the model's minimum (512 to 4,096 tokens, see
+ * minCacheableTokens) 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,
@@ -38,6 +39,7 @@ export interface CachePlan {
     usdWith?: number;
     notes: string[];
 }
+export declare function minCacheableTokens(model?: string): number;
 export declare function planCache(request: unknown, calls?: number, modelOverride?: string): {
     plan: CachePlan;
     apply: () => Record<string, any>;

package/dist/cacheplan.js

@@ -4,9 +4,10 @@
  *
  * 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.
+ * sits on, a prefix under the model's minimum (512 to 4,096 tokens, see
+ * minCacheableTokens) 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,
@@ -21,11 +22,45 @@ import { estimateTokens, formatTokens } from "./tokens.js";
 import { formatUsd, pricingFor } from "./pricing.js";
 const LOOKBACK_BLOCKS = 20;
 const MAX_BREAKPOINTS = 4;
-function blocksOf(req, model) {
+/**
+ * Smallest prefix Anthropic caches, per model (prompt-caching docs, Oct 2026).
+ * Not monotonic across generations: the 5.x models cache from 512 tokens,
+ * Opus 4.6/4.5 and Haiku 4.5 only from 4,096, so one number for every model
+ * (the old "1,024, 2,048 on Haiku") advised breakpoints that could never hit
+ * on some models and called cacheable prompts too small on others.
+ */
+const CACHE_MINIMUMS = {
+    "opus 5.5": 512, "opus 5.0": 512, "fable 5.0": 512, "fable 5.1": 512,
+    "mythos 5.0": 512, "mythos 5.1": 512, "sonnet 5.5": 512, "haiku 5.5": 512,
+    "opus 4.8": 1024, "sonnet 5.0": 1024, "sonnet 4.6": 1024, "sonnet 4.5": 1024,
+    "opus 4.1": 1024, "opus 4.0": 1024, "sonnet 4.0": 1024,
+    "opus 4.7": 2048, "haiku 3.5": 2048, "mythos preview": 2048,
+    "opus 4.6": 4096, "opus 4.5": 4096, "haiku 4.5": 4096,
+};
+/** For a model the table does not know: the most common minimum across generations. */
+const DEFAULT_CACHE_MINIMUM = 1024;
+export function minCacheableTokens(model) {
+    const m = (model ?? "").toLowerCase();
+    if (/mythos-preview/.test(m))
+        return CACHE_MINIMUMS["mythos preview"];
+    // Current ids: claude-<family>-<major>[-<minor>], optionally dated (claude-opus-4-20250514 is
+    // Opus 4.0, so a minor is one or two digits, never the 8-digit date) or with a platform
+    // prefix/suffix (anthropic.claude-...-v1:0, claude-...@20251101).
+    let key;
+    const cur = /(opus|sonnet|haiku|fable|mythos)-(\d+)(?:[-.](\d{1,2}))?(?!\d)/.exec(m);
+    if (cur)
+        key = `${cur[1]} ${cur[2]}.${cur[3] ?? "0"}`;
+    // Claude 3 ids put the version first: claude-3-5-haiku-20241022.
+    const old = /claude-(\d)(?:-(\d))?-(opus|sonnet|haiku)/.exec(m);
+    if (old)
+        key = `${old[3]} ${old[1]}.${old[2] ?? "0"}`;
+    return (key && CACHE_MINIMUMS[key]) || DEFAULT_CACHE_MINIMUM;
+}
+function blocksOf(req, model, longTtl = false) {
     const out = [];
     const mark = (obj) => (on) => {
         if (on)
-            obj.cache_control = obj.cache_control ?? { type: "ephemeral" };
+            obj.cache_control = obj.cache_control ?? (longTtl ? { type: "ephemeral", ttl: "1h" } : { type: "ephemeral" });
         else
             delete obj.cache_control;
     };
@@ -87,9 +122,13 @@ export function planCache(request, calls = 10, modelOverride) {
             apply: () => req,
         };
     }
-    const blocks = blocksOf(req, model);
+    // Cache writes cost 1.25x input at the 5-minute TTL and 2x at one hour. A
+    // request that already uses the hour keeps it on the planned breakpoints, so
+    // the price below is the price of the request apply() returns.
+    const longTtl = /"ttl"\s*:\s*"1h"/.test(JSON.stringify(req));
+    const blocks = blocksOf(req, model, longTtl);
     const total = blocks.reduce((s, b) => s + b.tokens, 0);
-    const minCacheable = /haiku/i.test(model ?? "") ? 2048 : 1024;
+    const minCacheable = minCacheableTokens(model);
     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 = [];
@@ -118,7 +157,6 @@ export function planCache(request, calls = 10, modelOverride) {
         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) {

package/dist/calibration.d.ts

@@ -30,7 +30,12 @@ export interface Calibration {
 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;
+/**
+ * Remember one exact-vs-heuristic observation. Best-effort; never throws.
+ * Returns whether it was saved, so the caller only claims "remembered" when
+ * it was: a rejected sample, the off switch, or a failed write all leave the
+ * file as it was.
+ */
+export declare function recordCalibration(model: string | undefined, exactTokens: number, heuristicTokens: number): boolean;
 /** 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

@@ -50,13 +50,22 @@ function readAll() {
         return {};
     }
 }
-/** Remember one exact-vs-heuristic observation. Best-effort; never throws. */
+/**
+ * Remember one exact-vs-heuristic observation. Best-effort; never throws.
+ * Returns whether it was saved, so the caller only claims "remembered" when
+ * it was: a rejected sample, the off switch, or a failed write all leave the
+ * file as it was.
+ */
 export function recordCalibration(model, exactTokens, heuristicTokens) {
+    // The off switch means off: not applied AND not learned, or a user who set
+    // it would find a calibration waiting the day they unset it.
+    if (process.env.CONTEXT_DOCTOR_NO_CALIBRATION)
+        return false;
     if (!(exactTokens > 0) || !(heuristicTokens > 0))
-        return;
+        return false;
     const ratio = exactTokens / heuristicTokens;
     if (ratio < MIN_FACTOR || ratio > MAX_FACTOR)
-        return; // a broken sample must not poison the file
+        return false; // a broken sample must not poison the file
     try {
         const all = readAll();
         const key = modelFamily(model);
@@ -70,9 +79,11 @@ export function recordCalibration(model, exactTokens, heuristicTokens) {
         };
         mkdirSync(dirname(calibrationPath()), { recursive: true });
         writeFileSync(calibrationPath(), JSON.stringify(all, null, 2));
+        return true;
     }
     catch {
         /* calibration is a refinement; failing to save it must not fail the command */
+        return false;
     }
 }
 /** The factor to apply for a model, or 1 with zero samples when there is none. */