context-doctor 0.31.0 → 0.32.0

package/dist/doctor.js

@@ -13,7 +13,7 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { ledgerPath } from "./ledger.js";
 import { loadConfig } from "./config.js";
-import { geminiCliPresent, geminiSettingsPath } from "./install.js";
+import { binOnPath, codexMcpEntry, geminiCliPresent, geminiSettingsPath, launcherNamesMissingPackage } from "./install.js";
 import { describeDesktopUsage, desktopUsage } from "./desktopusage.js";
 function claudeDesktopConfigPath() {
     switch (platform()) {
@@ -22,14 +22,30 @@ function claudeDesktopConfigPath() {
         default: return join(homedir(), ".config", "Claude", "claude_desktop_config.json");
     }
 }
-function checkMcpEntry(appName, configPath) {
+/**
+ * The verdict on a pre-0.31.2 launcher, `npx -y context-doctor-mcp`. No npm
+ * package has that name; npx only falls back to a command of that name on
+ * PATH. With a global install that keeps it working (until that install
+ * goes); without one npm answers 404 and the app shows no tools, no error.
+ */
+function missingPackageCheck(label) {
+    return binOnPath("context-doctor-mcp")
+        ? { label, status: "warn", detail: "MCP entry runs `npx context-doctor-mcp`, which starts only through your global install (no npm package has that name) — re-run: context-doctor install" }
+        : { label, status: "fail", detail: "MCP entry runs `npx context-doctor-mcp`, a package that does not exist on npm, so the server never starts — re-run: context-doctor install" };
+}
+function checkMcpEntry(appName, configPath, plugin = false) {
+    const viaPlugin = { label: appName, status: "ok", detail: "MCP server provided by the context-doctor plugin" };
     if (!existsSync(configPath))
-        return { label: appName, status: "skip", detail: "app not detected (config file absent)" };
+        return plugin ? viaPlugin : { label: appName, status: "skip", detail: "app not detected (config file absent)" };
     try {
         const config = JSON.parse(readFileSync(configPath, "utf8"));
         const entry = config.mcpServers?.["context-doctor"];
+        if (!entry && plugin)
+            return viaPlugin;
         if (!entry)
             return { label: appName, status: "fail", detail: `no context-doctor entry in ${configPath} — run: context-doctor install` };
+        if (launcherNamesMissingPackage(entry))
+            return missingPackageCheck(appName);
         // Absolute-path entries must point at a file that still exists. Launcher
         // forms (npx, and Windows' cmd /c npx) resolve at spawn time, not now.
         const launcher = entry.command === "npx" || entry.command === "cmd";
@@ -70,6 +86,46 @@ function hookBinaryMissing(command) {
     }
     return null;
 }
+/**
+ * Claude Code's settings files, lowest precedence first: user, project,
+ * local. A later file's value for a key wins, as in Claude Code itself.
+ */
+function claudeSettingsLayers() {
+    const paths = [
+        join(homedir(), ".claude", "settings.json"),
+        join(process.cwd(), ".claude", "settings.json"),
+        join(process.cwd(), ".claude", "settings.local.json"),
+    ];
+    return [...new Set(paths)].flatMap((p) => {
+        try {
+            return existsSync(p) ? [JSON.parse(readFileSync(p, "utf8"))] : [];
+        }
+        catch {
+            return []; // an unreadable user settings.json is reported by the hook check
+        }
+    });
+}
+/**
+ * Is the context-doctor plugin enabled? Plugins are switched on with
+ * enabledPlugins: {"<plugin>@<marketplace>": true}; ours is named
+ * context-doctor in whichever marketplace it came from. A plugin brings its
+ * own MCP server and hooks, so neither ~/.claude.json nor settings.json's
+ * hooks mention us, and those checks failed on a working plugin install.
+ */
+function pluginEnabled(layers) {
+    const state = new Map();
+    for (const s of layers) {
+        for (const [key, on] of Object.entries((s.enabledPlugins ?? {}))) {
+            if (key.startsWith("context-doctor@"))
+                state.set(key, on === true);
+        }
+    }
+    return [...state.values()].some(Boolean);
+}
+/** Claude Code's disableAllHooks: when true, no hook of anyone's runs. */
+function hooksDisabled(layers) {
+    return layers.reduce((off, s) => (typeof s.disableAllHooks === "boolean" ? s.disableAllHooks : off), false);
+}
 /** Spawn our own MCP server and run the initialize handshake over stdio. */
 function checkMcpHandshake() {
     const label = "MCP server handshake";
@@ -113,16 +169,31 @@ export async function runDoctor() {
     const desktop = desktopUsage();
     if (desktop)
         checks.push({ label: "Desktop chat tool use", status: "ok", detail: describeDesktopUsage(desktop, recentSurfaces(7).get("claude-desktop") ?? 0) });
-    checks.push(checkMcpEntry("Claude Code", join(homedir(), ".claude.json")));
+    const layers = claudeSettingsLayers();
+    const plugin = pluginEnabled(layers);
+    checks.push(checkMcpEntry("Claude Code", join(homedir(), ".claude.json"), plugin));
     checks.push(checkMcpEntry("Cursor", join(homedir(), ".cursor", "mcp.json")));
-    // Hook registration
+    // Hook registration. ~/.claude without a settings.json is Claude Code with
+    // no hook registered, not Claude Code absent.
     const settingsPath = join(homedir(), ".claude", "settings.json");
-    if (existsSync(settingsPath)) {
+    if (existsSync(settingsPath) || existsSync(join(homedir(), ".claude"))) {
         try {
-            const settings = JSON.parse(readFileSync(settingsPath, "utf8"));
+            const settings = existsSync(settingsPath) ? JSON.parse(readFileSync(settingsPath, "utf8")) : {};
             const entries = settings.hooks?.UserPromptSubmit ?? [];
             const ours = entries.map((e) => e.hooks?.[0]?.command ?? "").find((c) => /context-doctor|cli\.js"?\s+hook/.test(c));
-            if (!ours) {
+            if (hooksDisabled(layers)) {
+                // Registered or not, nothing runs: say that first, it is the fix.
+                checks.push({
+                    label: "Every-prompt hook",
+                    status: "fail",
+                    detail: `${ours || plugin ? "registered" : "not registered"}, and disableAllHooks is true in Claude Code's settings, so Claude Code runs no hooks at all; remove that setting${ours || plugin ? "" : ", then run: context-doctor install"}`,
+                });
+            }
+            else if (!ours && plugin) {
+                checks.push({ label: "Every-prompt hook", status: "ok", detail: "provided by the context-doctor plugin" });
+                checks.push({ label: "Compaction hook", status: "ok", detail: "PreCompact: provided by the context-doctor plugin" });
+            }
+            else if (!ours) {
                 checks.push({ label: "Every-prompt hook", status: "fail", detail: "not registered — run: context-doctor install" });
             }
             else {
@@ -134,7 +205,7 @@ export async function runDoctor() {
                     ? { label: "Every-prompt hook", status: "fail", detail: `registered, but ${missing} no longer exists — re-run: context-doctor install` }
                     : { label: "Every-prompt hook", status: "ok", detail: "registered in ~/.claude/settings.json; command resolves" });
                 const pre = settings.hooks?.PreCompact ?? [];
-                const preOurs = pre.some((e) => /context-doctor|cli\.js"?\s+hook/.test(e.hooks?.[0]?.command ?? ""));
+                const preOurs = plugin || pre.some((e) => /context-doctor|cli\.js"?\s+hook/.test(e.hooks?.[0]?.command ?? ""));
                 checks.push(preOurs
                     ? { label: "Compaction hook", status: "ok", detail: "PreCompact: each compaction's summary keeps the session's files, open tasks, your instructions and failing commands" }
                     : { label: "Compaction hook", status: "warn", detail: "not registered: compactions use generic instructions; run context-doctor install" });
@@ -151,9 +222,14 @@ export async function runDoctor() {
     const codexHome = join(homedir(), ".codex");
     if (existsSync(codexHome)) {
         const toml = existsSync(join(codexHome, "config.toml")) ? readFileSync(join(codexHome, "config.toml"), "utf8") : "";
-        checks.push(toml.includes("[mcp_servers.context-doctor]")
-            ? { label: "Codex MCP", status: "ok", detail: "wired in ~/.codex/config.toml" }
-            : { label: "Codex MCP", status: "fail", detail: "Codex detected but not wired — run: context-doctor install" });
+        // Parsed rather than searched for one exact header: a quoted key or a
+        // trailing comment is the same table to Codex.
+        const codexEntry = codexMcpEntry(toml);
+        checks.push(!codexEntry
+            ? { label: "Codex MCP", status: "fail", detail: "Codex detected but not wired — run: context-doctor install" }
+            : launcherNamesMissingPackage(codexEntry)
+                ? missingPackageCheck("Codex MCP")
+                : { label: "Codex MCP", status: "ok", detail: "wired in ~/.codex/config.toml" });
         try {
             const hooksPath = join(codexHome, "hooks.json");
             const hooks = existsSync(hooksPath) ? JSON.parse(readFileSync(hooksPath, "utf8")) : {};
@@ -181,9 +257,12 @@ export async function runDoctor() {
         try {
             const path = geminiSettingsPath();
             const settings = existsSync(path) ? JSON.parse(readFileSync(path, "utf8")) : {};
-            checks.push(settings.mcpServers?.["context-doctor"]
-                ? { label: "Gemini CLI MCP", status: "ok", detail: "wired in ~/.gemini/settings.json" }
-                : { label: "Gemini CLI MCP", status: "fail", detail: "Gemini CLI detected but not wired — run: context-doctor install" });
+            const geminiEntry = settings.mcpServers?.["context-doctor"];
+            checks.push(!geminiEntry
+                ? { label: "Gemini CLI MCP", status: "fail", detail: "Gemini CLI detected but not wired — run: context-doctor install" }
+                : launcherNamesMissingPackage(geminiEntry)
+                    ? missingPackageCheck("Gemini CLI MCP")
+                    : { label: "Gemini CLI MCP", status: "ok", detail: "wired in ~/.gemini/settings.json" });
             const entries = settings.hooks?.BeforeAgent ?? [];
             const ours = entries.map((e) => e.hooks?.[0]?.command ?? "").find((c) => /context-doctor|cli\.js"?\s+hook/.test(c));
             const missing = ours ? hookBinaryMissing(ours) : undefined;
@@ -229,7 +308,9 @@ export async function runDoctor() {
                 const missing = hookBinaryMissing(cmd);
                 checks.push(missing
                     ? { label: "Status line", status: "fail", detail: `configured, but ${missing} no longer exists — re-run: context-doctor install --statusline` }
-                    : { label: "Status line", status: "ok", detail: "live context in Claude Code's status bar" });
+                    : hooksDisabled(layers)
+                        ? { label: "Status line", status: "fail", detail: "configured, but disableAllHooks also turns off custom status lines" }
+                        : { label: "Status line", status: "ok", detail: "live context in Claude Code's status bar" });
             }
             else {
                 checks.push({ label: "Status line", status: "skip", detail: cmd ? "you have your own statusLine (left alone)" : "not enabled (optional: context-doctor install --statusline)" });
@@ -259,7 +340,12 @@ export async function runDoctor() {
     // Project config: a setting that is silently ignored looks exactly like the
     // feature being broken, so name it here rather than leaving it to be guessed.
     const loaded = loadConfig(process.cwd());
-    if (loaded.path) {
+    if (loaded.path && loaded.error) {
+        // A file with a typo used to read as "no .contextdoctorrc": the budget the
+        // user wrote is silently not in force, which is the case worth naming.
+        checks.push({ label: "Project config", status: "fail", detail: `${loaded.path} cannot be read (${loaded.error}): every setting in it is ignored until it parses as a JSON object` });
+    }
+    else if (loaded.path) {
         const warnings = loaded.warnings ?? [];
         checks.push(warnings.length === 0
             ? { label: "Project config", status: "ok", detail: `${loaded.path} — all settings understood` }
@@ -273,11 +359,40 @@ export async function runDoctor() {
     // dead proxy or a settings file pointing elsewhere is a real problem.
     {
         const paths = autopilotPaths();
+        // A truncated file used to throw at JSON.parse here, before a single line
+        // of the report was printed: one damaged file hid every other check.
+        let cfg;
+        let damage = "";
+        if (existsSync(paths.config)) {
+            try {
+                const parsed = JSON.parse(readFileSync(paths.config, "utf8"));
+                if (typeof parsed?.port === "number")
+                    cfg = parsed;
+                else
+                    damage = "no port in it";
+            }
+            catch (e) {
+                damage = e.message;
+            }
+        }
         if (!existsSync(paths.config)) {
             checks.push({ label: "Autopilot", status: "skip", detail: "off (context-doctor autopilot on: clears stale tool output in every new Claude Code session)" });
         }
+        else if (!cfg) {
+            let routedTo;
+            try {
+                routedTo = JSON.parse(readFileSync(paths.settings, "utf8"))?.env?.ANTHROPIC_BASE_URL;
+            }
+            catch { /* reported by the hook check */ }
+            checks.push({
+                label: "Autopilot",
+                status: "fail",
+                detail: `${paths.config} is damaged (${damage}). Run: context-doctor autopilot off` +
+                    (routedTo ? `, then remove env.ANTHROPIC_BASE_URL (${routedTo}) from ~/.claude/settings.json if it is the proxy` : "") +
+                    "; autopilot on starts it again cleanly",
+            });
+        }
         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;

package/dist/embed.d.ts

@@ -19,6 +19,15 @@ export interface SemanticResult {
     /** Why semantic ranking was not used, or what it did. */
     note: string;
 }
+/**
+ * The URL to reach Ollama at, read from OLLAMA_HOST the way Ollama reads it:
+ * no scheme means http on 11434 (`0.0.0.0`, `localhost:8080`), an explicit
+ * http:// or https:// without a port means 80 or 443. Taking `0.0.0.0` as
+ * `http://0.0.0.0` aimed at port 80, so semantic ranking was silently off for
+ * the most common setting. 0.0.0.0 and :: are where a server listens, not an
+ * address to connect to, so they mean this machine.
+ */
+export declare function ollamaUrl(env?: string | undefined): string;
 /** The embedding model to use: the one asked for, else the first installed model that looks like one. */
 export declare function findEmbeddingModel(preferred?: string): Promise<string | undefined>;
 /**

package/dist/embed.js

@@ -19,12 +19,47 @@ import { join } from "node:path";
 const EMBED_NAME = /embed|bge|e5-|gte|minilm|nomic|mxbai|arctic|snowflake/i;
 const BATCH = 64;
 const CACHE_CAP = 50_000;
-function host() {
-    const h = process.env.OLLAMA_HOST ?? "http://127.0.0.1:11434";
-    return h.startsWith("http") ? h.replace(/\/$/, "") : `http://${h}`;
+/**
+ * The URL to reach Ollama at, read from OLLAMA_HOST the way Ollama reads it:
+ * no scheme means http on 11434 (`0.0.0.0`, `localhost:8080`), an explicit
+ * http:// or https:// without a port means 80 or 443. Taking `0.0.0.0` as
+ * `http://0.0.0.0` aimed at port 80, so semantic ranking was silently off for
+ * the most common setting. 0.0.0.0 and :: are where a server listens, not an
+ * address to connect to, so they mean this machine.
+ */
+export function ollamaUrl(env = process.env.OLLAMA_HOST) {
+    let rest = (env ?? "").trim();
+    let scheme = "http";
+    let port = "11434";
+    const sep = rest.indexOf("://");
+    if (sep >= 0) {
+        scheme = rest.slice(0, sep);
+        rest = rest.slice(sep + 3);
+        if (scheme === "http")
+            port = "80";
+        else if (scheme === "https")
+            port = "443";
+    }
+    const slash = rest.indexOf("/");
+    const path = slash >= 0 ? rest.slice(slash).replace(/\/+$/, "") : "";
+    let host = slash >= 0 ? rest.slice(0, slash) : rest;
+    const m = /^(\[[^\]]*\]|[^:]*):([^:]*)$/.exec(host);
+    if (m) {
+        host = m[1];
+        if (/^\d+$/.test(m[2]) && Number(m[2]) <= 65535)
+            port = m[2];
+    }
+    else if (host.includes(":") && !host.startsWith("[")) {
+        host = `[${host}]`; // a bare IPv6 address
+    }
+    if (!host || host === "0.0.0.0")
+        host = "127.0.0.1";
+    else if (host === "[::]")
+        host = "[::1]";
+    return `${scheme}://${host}:${port}${path}`;
 }
 async function getJson(path, body, timeoutMs = 60_000) {
-    const r = await fetch(host() + path, {
+    const r = await fetch(ollamaUrl() + path, {
         method: body ? "POST" : "GET",
         headers: body ? { "content-type": "application/json" } : undefined,
         body: body ? JSON.stringify(body) : undefined,
@@ -94,7 +129,7 @@ export async function semanticRerank(chunks, query, opts = {}) {
         model = await findEmbeddingModel(opts.model);
     }
     catch {
-        return { used: false, note: `semantic ranking off: no Ollama at ${host()} (keyword ranking only)` };
+        return { used: false, note: `semantic ranking off: no Ollama at ${ollamaUrl()} (keyword ranking only)` };
     }
     if (!model)
         return { used: false, note: "semantic ranking off: Ollama has no embedding model; run `ollama pull nomic-embed-text` (keyword ranking only)" };

package/dist/experiment.d.ts

@@ -49,6 +49,7 @@ export interface ArmResult {
 }
 /** Build the argv for one arm — exported so the dry run and the tests see exactly what runs. */
 export declare function claudeArgs(opts: ExperimentOptions, arm: "fresh" | "existing"): string[];
+export declare function findTranscript(sessionId: string, cwd: string): string | undefined;
 export declare function runExperiment(opts: ExperimentOptions): {
     arms: ArmResult[];
     startCommit?: string;

package/dist/experiment.js

@@ -39,9 +39,12 @@ export function claudeArgs(opts, arm) {
         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, "-"));
+export function findTranscript(sessionId, cwd) {
+    // Claude Code keys project dirs by the cwd with EVERY non-alphanumeric
+    // character replaced (/Users/me/.claude/x_y -> -Users-me--claude-x-y), as
+    // overhead.ts does. Replacing only separators missed any cwd with a dot,
+    // underscore or space, and the "live context" row silently disappeared.
+    const projectDir = join(homedir(), ".claude", "projects", cwd.replace(/[^A-Za-z0-9]/g, "-"));
     const candidate = join(projectDir, `${sessionId}.jsonl`);
     return existsSync(candidate) ? candidate : undefined;
 }

package/dist/hook.js

@@ -21,7 +21,7 @@ import { profileConversation } from "./profile.js";
 import { parseSessionFile } from "./session.js";
 import { formatTokens, CHARS_PER_TOKEN, LARGEST_WINDOW } from "./tokens.js";
 import { ensureProxyUp } from "./autopilot.js";
-import { detectColdResume, renderColdResume, renderColdResumeNotice } from "./coldresume.js";
+import { detectColdResume, renderColdResume, renderColdResumeNotice, sessionWriteMultiplier } from "./coldresume.js";
 import { formatUsd, pricingFor } from "./pricing.js";
 import { checkBudget, loadConfig } from "./config.js";
 import { compactFacts, compactInstructions } from "./precompact.js";
@@ -48,10 +48,21 @@ const REGROWTH_FACTOR = 1.4;
  * hold that many tokens of context. Lean sessions cost one stat() call — the
  * transcript is never even read. (This used 4 bytes per token until 0.19,
  * which let Claude sessions past the threshold take the fast path.)
+ *
+ * The threshold is compared with the API's figure, which also counts what the
+ * transcript never holds: system prompt, tool schemas, memory files. Sized as
+ * if the transcript were the whole context, the gate hid sessions from low
+ * thresholds (a 60k budget saw nothing until 144 KB; half of one machine's
+ * sessions passed 60k live tokens below that). So that front matter is
+ * allowed for first. Measured on 78 Claude Code sessions with several MCP
+ * servers: first requests carried 27k-70k tokens, of which up to 43k could
+ * not have come from the transcript at its densest; 50k covers that. Lean
+ * sessions below the remaining byte count still cost one stat().
  */
 const DENSEST_CHARS_PER_TOKEN = Math.min(...Object.values(CHARS_PER_TOKEN).map((r) => Math.min(r.prose, r.code)));
+const FRONT_MATTER_ALLOWANCE = 50_000;
 function minBytesForWarn(threshold) {
-    return Math.floor(threshold * DENSEST_CHARS_PER_TOKEN);
+    return Math.floor(Math.max(0, threshold - FRONT_MATTER_ALLOWANCE) * DENSEST_CHARS_PER_TOKEN);
 }
 /**
  * State lives in one small file per session, not one shared map.
@@ -237,7 +248,11 @@ export async function runHook() {
         const liveTokens = parsed.reportedInputTokens ?? profile.totalTokens;
         // Record this parse so the next prompts take fast path 2.
         const shouldWarn = liveTokens >= threshold && liveTokens >= prev.t * REGROWTH_FACTOR;
-        writeSessionState(sessionId, { t: shouldWarn ? liveTokens : prev.t, b: sizeBytes, cr });
+        // The regrowth bar follows the context DOWN as well: after a compaction it
+        // is measured from the compacted size. Kept at the old peak, the next
+        // warning needed 1.4x a size the session no longer had (seen: warned at
+        // 843k, compacted, then regrew to 809k without a word).
+        writeSessionState(sessionId, { t: shouldWarn ? liveTokens : Math.min(prev.t, liveTokens), b: sizeBytes, cr });
         recordLedger({ ev: "check", sid: sessionId.slice(0, 12), tok: liveTokens, warn: shouldWarn });
         if (!shouldWarn) {
             emit(notes);
@@ -251,9 +266,13 @@ export async function runHook() {
         // context at the cached rate (0.1x) and pays the full rate only when the
         // cache has expired. Quoting the uncached figure alone overstated the
         // per-message cost tenfold (fixed in 0.22).
+        // An expired cache is re-written at the TTL this session writes at, read
+        // from the transcript's tail: Claude Code's main thread has mostly
+        // written the 1-hour cache, at 2x input, where a flat 1.25x quoted the
+        // cold message 37% low (5-minute writes stay at 1.25x).
         const pricing = pricingFor(model);
         const cachedUsd = pricing ? (liveTokens * pricing.cacheReadPerM) / 1e6 : undefined;
-        const coldUsd = pricing ? (liveTokens * pricing.inputPerM * 1.25) / 1e6 : undefined;
+        const coldUsd = pricing ? (liveTokens * pricing.inputPerM * sessionWriteMultiplier(transcriptPath)) / 1e6 : undefined;
         // Cursor's agent transcript records tool calls but not their output, and
         // keeps turns Cursor has since summarized, so it measures how much the chat
         // has accumulated, not the live context: no window share or price for it.

package/dist/impact.d.ts

@@ -8,4 +8,36 @@
  * session cannot be re-run without it. The report says so instead of inventing
  * a number.
  */
+import { LedgerEntry } from "./ledger.js";
+/** The parts of the proxy's /stats that lifetime savings depend on. */
+export interface LiveProxyStats {
+    startedAt?: string;
+    tokensSaved?: number;
+    estUsdSaved?: number;
+}
+export interface ProxySavings {
+    /** Lifetime tokens the proxy removed: ledger checkpoints plus what the live run has not checkpointed. */
+    tokens: number;
+    usd: number;
+    /** The part of `tokens` from runs before the live one (all of it when none is running). */
+    earlier: number;
+    /** Ledger checkpoints written by those earlier runs. */
+    earlierCheckpoints: number;
+}
+/**
+ * Lifetime proxy savings, for `report` and the dashboard alike.
+ *
+ * A running proxy writes the DELTA of its total to the ledger every 60 s
+ * (proxy.ts, so history survives a restart), while /stats keeps returning the
+ * whole total since its startedAt. Ledger + /stats therefore counted every
+ * checkpointed token twice: one request saving 22k read "~45k" a minute later.
+ * Here every ledger checkpoint counts once, and the live run adds only what its
+ * own checkpoints (entries written since its startedAt) do not hold yet. The
+ * dashboard used to show the live figure alone, so a stopped proxy read 0.
+ *
+ * Known limit: if ledger rotation folds this run's own checkpoints into a
+ * rollup, they can no longer be told apart and count twice again. Only the
+ * proxy can close that (by reporting its checkpointed total in /stats).
+ */
+export declare function proxySavings(ledger: LedgerEntry[], live: LiveProxyStats | null): ProxySavings;
 export declare function buildImpactReport(proxyPort?: number): Promise<string>;

package/dist/impact.js

@@ -17,6 +17,45 @@ import { formatUsd, inputCostUsd, pricingFor } from "./pricing.js";
 import { coldResumeFollowThrough } from "./coldresume.js";
 /** Sessions larger than this are skipped in the report (keeps it snappy). */
 const MAX_SESSION_BYTES = 30 * 1024 * 1024;
+/**
+ * Lifetime proxy savings, for `report` and the dashboard alike.
+ *
+ * A running proxy writes the DELTA of its total to the ledger every 60 s
+ * (proxy.ts, so history survives a restart), while /stats keeps returning the
+ * whole total since its startedAt. Ledger + /stats therefore counted every
+ * checkpointed token twice: one request saving 22k read "~45k" a minute later.
+ * Here every ledger checkpoint counts once, and the live run adds only what its
+ * own checkpoints (entries written since its startedAt) do not hold yet. The
+ * dashboard used to show the live figure alone, so a stopped proxy read 0.
+ *
+ * Known limit: if ledger rotation folds this run's own checkpoints into a
+ * rollup, they can no longer be told apart and count twice again. Only the
+ * proxy can close that (by reporting its checkpointed total in /stats).
+ */
+export function proxySavings(ledger, live) {
+    const carried = foldTotals(ledger.filter((e) => e.ev === "rollup"));
+    const events = ledger.filter((e) => e.ev === "proxy");
+    const sum = (es, pick) => es.reduce((s, e) => s + (pick(e) ?? 0), 0);
+    const recorded = sum(events, (e) => e.saved) + carried.proxySaved;
+    const recordedUsd = sum(events, (e) => e.usd) + carried.proxyUsd;
+    if (!live)
+        return { tokens: recorded, usd: recordedUsd, earlier: recorded, earlierCheckpoints: events.length };
+    // Without a parseable startedAt no checkpoint can be attributed to this run;
+    // count the live total whole, as before.
+    const since = Date.parse(live.startedAt ?? "");
+    const thisRun = Number.isFinite(since) ? events.filter((e) => e.ts >= since) : [];
+    const liveTokens = live.tokensSaved ?? 0;
+    // max(0, …): another proxy checkpointing meanwhile must not make this negative.
+    const pending = Math.max(0, liveTokens - sum(thisRun, (e) => e.saved));
+    const pendingUsd = Math.max(0, (live.estUsdSaved ?? 0) - sum(thisRun, (e) => e.usd));
+    const tokens = recorded + pending;
+    return {
+        tokens,
+        usd: recordedUsd + pendingUsd,
+        earlier: Math.max(0, tokens - liveTokens),
+        earlierCheckpoints: events.length - thisRun.length,
+    };
+}
 async function fetchProxyStats(port) {
     try {
         const res = await fetch(`http://127.0.0.1:${port}/stats`, { signal: AbortSignal.timeout(500) });
@@ -74,11 +113,11 @@ export async function buildImpactReport(proxyPort = 8787) {
             optimizeUsd += inputCostUsd(e.saved, pricing);
     }
     const proxy = await fetchProxyStats(proxyPort);
-    // Persisted checkpoints cover proxy runs that have since exited; the live
-    // process reports whatever it has not checkpointed yet.
-    const proxyEvents = ledger.filter((e) => e.ev === "proxy");
-    const proxyHistoric = proxyEvents.reduce((s, e) => s + (e.saved ?? 0), 0) + carried.proxySaved;
-    const proxySaved = proxyHistoric + (proxy?.tokensSaved ?? 0);
+    // Persisted checkpoints cover earlier runs AND the live one's past minutes;
+    // proxySavings counts each token once.
+    const savedByProxy = proxySavings(ledger, proxy);
+    const proxySaved = savedByProxy.tokens;
+    const proxyHistoric = savedByProxy.earlier;
     // -- Headline: what context-doctor has saved ----------------------------------
     // Only what context-doctor itself removed. Sessions also shrink when Claude
     // Code auto-compacts or the user runs /compact; counting that as our saving
@@ -93,7 +132,7 @@ export async function buildImpactReport(proxyPort = 8787) {
     }
     else {
         lines.push(proxyHistoric > 0
-            ? `  · proxy (exact, from ${proxyEvents.length} earlier run checkpoint(s)): ${formatTokens(proxyHistoric)} — not running now`
+            ? `  · proxy (exact, from ${savedByProxy.earlierCheckpoints} earlier run checkpoint(s)): ${formatTokens(proxyHistoric)} — not running now`
             : `  · proxy: not running on :${proxyPort} (its exact savings appear here once it runs)`);
     }
     const familyNote = [...savedByFamily.entries()]

package/dist/install.d.ts

@@ -17,13 +17,37 @@ export declare function geminiCliPresent(): boolean;
  * wrapper that every working Windows MCP config uses.
  *
  * Exported so the platform branch is testable from any host OS.
+ *
+ * npx resolves its first operand as a PACKAGE name. context-doctor-mcp is
+ * only a bin inside the context-doctor package, so `npx -y context-doctor-mcp`
+ * asked npm for a package that does not exist: unless a global install
+ * happened to put that command on PATH, every app got a server that never
+ * started. The main bin's `mcp` subcommand is the same server.
  */
 export declare function npxLauncher(platformName: string): {
     command: string;
     args: string[];
 };
+/**
+ * True for the launcher installs before 0.31.2 wrote: npx asked to run a
+ * package named context-doctor-mcp, which is not on npm. npx does fall back
+ * to a command of that name already on PATH, so it starts where a global
+ * install provides one; everywhere else npm answers 404.
+ */
+export declare function launcherNamesMissingPackage(entry: {
+    command?: unknown;
+    args?: unknown;
+} | undefined): boolean;
 export declare function readJson(path: string): Record<string, any>;
+/** Copy `path` to its .context-doctor.backup, once per run. */
+export declare function backupOnce(path: string): void;
 export declare function writeJsonWithBackup(path: string, data: Record<string, any>): void;
+/**
+ * Find an executable on PATH without shelling out (works on Windows too).
+ * Used to prefer a global `context-doctor` install for the hook: a stable
+ * location that survives both package updates and Node upgrades.
+ */
+export declare function binOnPath(name: string): string | null;
 /** Paths npm may delete at any time: the npx cache and the npm cache itself. */
 export declare function isEphemeralPath(path: string): boolean;
 /**
@@ -48,13 +72,21 @@ export declare function codexDir(): string;
  * Add or replace our [mcp_servers.context-doctor] table in config.toml without
  * a TOML library: the file is the user's, so everything outside our own table
  * is copied through byte for byte. Our table is delimited by its header and the
- * next header (or EOF).
+ * next header (or EOF). Our subtables (e.g. an env the user added) are kept.
  */
 export declare function upsertCodexMcpTable(toml: string, entry: {
     command: string;
     args: string[];
 }): string;
 export declare function removeCodexMcpTable(toml: string): string;
+/**
+ * The command and args of our Codex server, or undefined when config.toml
+ * does not define one. Reads the inline forms too: Codex runs those fine.
+ */
+export declare function codexMcpEntry(toml: string): {
+    command?: string;
+    args: string[];
+} | undefined;
 /** 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. */
@@ -73,4 +105,4 @@ export interface InstallResult {
 export declare function runInstall(options?: {
     statusLine?: boolean;
 }): InstallResult;
-export declare function runUninstall(): void;
+export declare function runUninstall(): Promise<void>;