context-doctor 0.31.0 → 0.32.0

package/dist/compactwindow.js

@@ -20,22 +20,31 @@
 import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { forEachLine, listSessions } from "./session.js";
-import { pricingFor } from "./pricing.js";
+import { forEachLine, listSessions, replyCounter } from "./session.js";
+import { cacheWriteSplit, pricingFor, writeMultiplier } from "./pricing.js";
+import { realModel } from "./tokens.js";
 import { readJson, writeJsonWithBackup } from "./install.js";
 /** Claude Code compacts at about this share of the window (970k of 1M, measured). */
 const TRIGGER_SHARE = 0.97;
 /** Context right after a compaction: system prompt, tools and the summary (median 75,447, measured). */
 const AFTER_COMPACT = 75_000;
-/** Output tokens a compaction summary costs, priced at output's 5x input rate. */
+/** Output tokens a compaction summary costs, at the model's output price. */
 const SUMMARY_OUTPUT = 20_000;
-const OUTPUT_RATIO = 5;
 const TTL_MS = 3_600_000;
 export const MIN_WINDOW = 100_000;
 export const MAX_WINDOW = 1_000_000;
-function readRequests(path) {
+/**
+ * `writeMult`: what this session pays to write a token to the cache,
+ * relative to input, from the 5-minute and 1-hour writes its usage records.
+ * The replay charges writes that never happened (a cold re-read, a fresh
+ * context after a simulated compaction); the harness would have written
+ * those at the TTL it writes everything else at, mostly 1 hour (2x) for
+ * Claude Code's main thread, not the 1.25x a constant assumed.
+ */
+function readRequests(path, runRows) {
     const reqs = [];
-    let lastId, model;
+    let model, writes5m = 0, writes1h = 0, priced = false;
+    const sighting = replyCounter(runRows);
     forEachLine(path, (line) => {
         let e;
         try {
@@ -47,55 +56,70 @@ function readRequests(path) {
         if (!e || e.isSidechain)
             return;
         if (e.type === "system" && e.subtype === "compact_boundary") {
-            reqs.push("compact");
+            const copy = typeof e.uuid === "string" && !!runRows?.has(e.uuid);
+            if (typeof e.uuid === "string")
+                runRows?.add(e.uuid);
+            reqs.push({ compact: true, copy });
             return;
         }
-        if (e.type !== "assistant" || !e.message || e.message.id === lastId)
+        if (e.type !== "assistant" || !e.message)
+            return;
+        const seen = sighting(e);
+        if (seen === "repeat")
             return;
-        lastId = e.message.id;
         const u = e.message.usage ?? {};
         const prompt = (u.input_tokens ?? 0) + (u.cache_read_input_tokens ?? 0) + (u.cache_creation_input_tokens ?? 0);
         const at = Date.parse(e.timestamp);
-        if (prompt > 0 && Number.isFinite(at)) {
-            reqs.push({ at, prompt });
-            model ??= e.message.model;
-        }
+        if (!(prompt > 0) || !Number.isFinite(at))
+            return;
+        // Each request at its own model's price; "<synthetic>" rows carry no usage.
+        model = realModel(e.message.model) ?? model;
+        const p = pricingFor(model);
+        if (p)
+            priced = true;
+        const w = cacheWriteSplit(u);
+        writes5m += w.fiveMinute;
+        writes1h += w.oneHour;
+        reqs.push({ at, prompt, inPerM: p?.inputPerM ?? 0, readPerM: p?.cacheReadPerM ?? 0, outPerM: p?.outputPerM ?? 0, copy: seen === "copy" });
     });
-    return { model, reqs };
+    return { reqs, writeMult: writeMultiplier(writes5m, writes1h), priced };
 }
 /**
  * Replay one session twice: as it ran, and with compaction whenever the
  * context reaches the window's trigger. Both arms are priced as the prompt
- * cache bills (warm: 0.1x re-read + 1.25x for what is new; cold after an hour
- * idle: 1.25x for everything); each simulated compaction also pays its own
- * request and summary.
- */
-/**
+ * cache bills, in USD at each request's own model (warm: the cache-read rate
+ * on what was there + a write for what is new; cold after an hour idle: a
+ * write for everything, writes at the session's own `writeMult`); each
+ * simulated compaction also pays its own request and summary.
+ *
  * `reread`: tokens a session fetches again after a compaction because the
  * summary dropped them (measured by `context-doctor compactions`). Each
  * simulated compaction writes them to the cache and carries them onward.
  */
-function replay(reqs, window, since, reread = 0) {
+function replay(reqs, window, since, reread = 0, writeMult = 1.25) {
     let base = 0, sim = 0, extra = 0, actual = 0;
     let removed = 0, prevActual, prevSim, prevAt;
     for (const r of reqs) {
-        if (r === "compact") {
-            if (prevAt !== undefined && prevAt >= since)
+        if ("compact" in r) {
+            if (prevAt !== undefined && prevAt >= since && !r.copy)
                 actual++;
             // A real compaction in the transcript: the simulated arm compacts there too.
-            if (prevAt !== undefined && prevAt >= since && removed === 0)
+            if (prevAt !== undefined && prevAt >= since && removed === 0 && !r.copy)
                 extra++;
             removed = 0;
             prevActual = prevSim = undefined;
             continue;
         }
-        const counted = r.at >= since;
+        // Requests before the window, or already counted from a forked copy,
+        // still shape both arms; only the rest are billed.
+        const counted = r.at >= since && !r.copy;
         const cold = prevAt === undefined || r.at - prevAt > TTL_MS;
+        const write = writeMult * r.inPerM;
         const cost = (ctx, prev) => {
             if (cold)
-                return 1.25 * ctx;
+                return write * ctx;
             const fresh = prev === undefined || ctx < prev ? ctx : ctx - prev;
-            return 0.1 * (ctx - fresh) + 1.25 * fresh;
+            return r.readPerM * (ctx - fresh) + write * fresh;
         };
         if (counted)
             base += cost(r.prompt, prevActual);
@@ -109,7 +133,7 @@ function replay(reqs, window, since, reread = 0) {
         let simPrev = prevSim;
         if (ctx >= TRIGGER_SHARE * window) {
             if (counted) {
-                sim += 0.1 * ctx + OUTPUT_RATIO * SUMMARY_OUTPUT + 1.25 * reread;
+                sim += r.readPerM * ctx + r.outPerM * SUMMARY_OUTPUT + write * reread;
                 extra++;
             }
             removed = r.prompt - AFTER_COMPACT - reread;
@@ -129,23 +153,24 @@ export function estimateCompactWindows(windows, days = 30, paths, rereadTokens =
     const targets = paths ?? listSessions(10_000).filter((s) => s.path.includes(".claude") && s.modifiedAt.getTime() >= since).map((s) => s.path);
     const acc = windows.map((w) => ({ window: w, base: 0, sim: 0, extra: 0 }));
     let sessions = 0, actualCompactions = 0;
+    // Shared by every transcript of the run, so a fork's copy counts once.
+    const runRows = new Set();
     for (const p of targets) {
         let parsed;
         try {
-            parsed = readRequests(p);
+            parsed = readRequests(p, runRows);
         }
         catch {
             continue;
         }
-        const perM = pricingFor(parsed.model)?.inputPerM;
-        if (!perM || parsed.reqs.filter((r) => r !== "compact" && r.at >= since).length < 10)
+        if (!parsed.priced || parsed.reqs.filter((r) => !("compact" in r) && r.at >= since && !r.copy).length < 10)
             continue;
         sessions++;
-        actualCompactions += replay(parsed.reqs, Number.MAX_SAFE_INTEGER, since).actual;
+        actualCompactions += replay(parsed.reqs, Number.MAX_SAFE_INTEGER, since, 0, parsed.writeMult).actual;
         for (const a of acc) {
-            const r = replay(parsed.reqs, a.window, since, rereadTokens);
-            a.base += (r.base * perM) / 1e6;
-            a.sim += (r.sim * perM) / 1e6;
+            const r = replay(parsed.reqs, a.window, since, rereadTokens, parsed.writeMult);
+            a.base += r.base / 1e6;
+            a.sim += r.sim / 1e6;
             a.extra += r.extra;
         }
     }

package/dist/config.d.ts

@@ -43,6 +43,12 @@ export interface LoadedConfig {
     path?: string;
     /** Settings that will be silently ignored, if any. */
     warnings?: string[];
+    /**
+     * Set when the rc file at `path` exists but cannot be used at all (not
+     * JSON, or not an object): none of its settings are in effect. `path` is
+     * still given, so a caller can name the file instead of reporting none.
+     */
+    error?: string;
 }
 /**
  * Report anything in an rc file that will be silently ignored.

package/dist/config.js

@@ -119,11 +119,14 @@ export function loadConfig(startDir = process.cwd(), onWarn) {
                 return { config: parsed, path, warnings };
             }
             onWarn?.(`${path}: expected a JSON object — ignoring`);
+            return { config: {}, path, error: "expected a JSON object" };
         }
         catch (e) {
             onWarn?.(`${path}: ${e.message} — ignoring`);
+            // Returning no path made `doctor` report "no .contextdoctorrc" for a
+            // file that exists with a typo in it: the one case worth reporting.
+            return { config: {}, path, error: e.message };
         }
-        return { config: {} };
     }
     return { config: {} };
 }

package/dist/cursor.d.ts

@@ -23,6 +23,15 @@ export declare function findCursorDatabases(): string[];
 interface Row {
     [column: string]: string | number | null;
 }
+/**
+ * This runtime cannot read SQLite at all: no `node:sqlite` and no sqlite3
+ * command. Distinct from one database failing, which listing skips, because
+ * it applies to every database: swallowing it per database showed "No Cursor
+ * chats found" with every chat still there (Node 20, and 22.5-22.12 without
+ * the flag, when sqlite3 is not on PATH).
+ */
+export declare class SqliteUnavailableError extends Error {
+}
 /**
  * Run a read-only query against a Cursor database.
  *

package/dist/cursor.js

@@ -65,6 +65,24 @@ export function findCursorDatabases() {
     }
     return dbs.sort((a, b) => b.mtime - a.mtime).map((d) => d.path);
 }
+/**
+ * This runtime cannot read SQLite at all: no `node:sqlite` and no sqlite3
+ * command. Distinct from one database failing, which listing skips, because
+ * it applies to every database: swallowing it per database showed "No Cursor
+ * chats found" with every chat still there (Node 20, and 22.5-22.12 without
+ * the flag, when sqlite3 is not on PATH).
+ */
+export class SqliteUnavailableError extends Error {
+}
+/** Node's built-in SQLite, when this runtime has it (22.13+, or 22.5+ with --experimental-sqlite). */
+function nodeSqlite() {
+    try {
+        return require("node:sqlite");
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * Run a read-only query against a Cursor database.
  *
@@ -77,31 +95,40 @@ export function findCursorDatabases() {
  * safe while Cursor is running.
  */
 export function queryRows(dbPath, sql) {
-    try {
-        // Preferred: Node's built-in SQLite (22.5+).
-        const { DatabaseSync } = require("node:sqlite");
-        const db = new DatabaseSync(dbPath, { readOnly: true });
+    // Preferred: Node's built-in SQLite (22.5+).
+    const sqlite = nodeSqlite();
+    let nodeSqliteErr;
+    if (sqlite) {
         try {
-            return db.prepare(sql).all();
+            const db = new sqlite.DatabaseSync(dbPath, { readOnly: true });
+            try {
+                return db.prepare(sql).all();
+            }
+            finally {
+                db.close();
+            }
         }
-        finally {
-            db.close();
+        catch (e) {
+            nodeSqliteErr = e;
         }
     }
-    catch (nodeSqliteErr) {
-        // Fallback: the sqlite3 CLI, if the user has it.
-        try {
-            const out = execFileSync("sqlite3", ["-readonly", "-json", dbPath, sql], {
-                encoding: "utf8",
-                maxBuffer: 512 * 1024 * 1024,
-                stdio: ["ignore", "pipe", "ignore"], // a missing table is expected on some DBs
-            });
-            return out.trim() ? JSON.parse(out) : [];
-        }
-        catch {
-            throw new Error("reading Cursor chats needs SQLite: Node 22.5+ (built-in) or the sqlite3 command. " +
-                `Neither worked here (${nodeSqliteErr.message}).`);
+    // Fallback: the sqlite3 CLI, if the user has it.
+    try {
+        const out = execFileSync("sqlite3", ["-readonly", "-json", dbPath, sql], {
+            encoding: "utf8",
+            maxBuffer: 512 * 1024 * 1024,
+            stdio: ["ignore", "pipe", "ignore"], // a missing table is expected on some DBs
+        });
+        return out.trim() ? JSON.parse(out) : [];
+    }
+    catch (cliErr) {
+        // Neither backend exists: the same answer for every database, so say it once.
+        if (!sqlite && cliErr.code === "ENOENT") {
+            throw new SqliteUnavailableError("reading Cursor chats needs SQLite: Node 22.13+ (built-in; 22.5+ with --experimental-sqlite) or the sqlite3 command. " +
+                "Neither is available here.");
         }
+        // A backend ran and this database failed (no such table, locked, corrupt).
+        throw new Error(`${dbPath}: ${(nodeSqliteErr ?? cliErr).message}`);
     }
 }
 /** List Cursor chats, biggest first. */
@@ -121,8 +148,12 @@ export function listCursorChats(limit = 20) {
                 // "No Cursor chats found" with every real chat sitting right there.
                 "FROM cursorDiskKV WHERE key LIKE 'composerData:%' AND json_valid(value)");
         }
-        catch {
-            continue; // no composer table (older Cursor) or no SQLite — skip
+        catch (e) {
+            // No SQLite at all fails every database alike: report it (the CLI says
+            // what to install) instead of "No Cursor chats found".
+            if (e instanceof SqliteUnavailableError)
+                throw e;
+            continue; // no composer table (older Cursor), or this database is unreadable — skip
         }
         for (const row of rows) {
             const count = Number(row.n ?? 0);

package/dist/dashboard.d.ts

@@ -29,6 +29,7 @@ export interface DashboardData {
         model?: string;
     }>;
     proxy: {
+        startedAt?: string;
         requests: number;
         optimizedRequests: number;
         tokensSaved: number;
@@ -41,6 +42,15 @@ export interface DashboardData {
     } | null;
 }
 export declare function collectDashboardData(proxyPort?: number): Promise<DashboardData>;
+/**
+ * Whether a request's Host header names this machine's loopback.
+ *
+ * Listening on 127.0.0.1 is not enough on its own: a web page can rebind its
+ * own hostname to 127.0.0.1 (DNS rebinding) and then read /api/data, session
+ * titles included, as same-origin. Such a request still carries the attacker's
+ * hostname in Host, so only loopback names are answered.
+ */
+export declare function isLoopbackHost(host: string | undefined, port: number): boolean;
 export declare function startDashboard(opts?: {
     port?: number;
     proxyPort?: number;

package/dist/dashboard.js

@@ -13,6 +13,7 @@ import { parseConversation } from "./parse.js";
 import { profileConversation } from "./profile.js";
 import { inputCostUsd, pricingFor } from "./pricing.js";
 import { checkBudget, loadConfig } from "./config.js";
+import { proxySavings } from "./impact.js";
 /** Sessions bigger than this are skipped so the page stays responsive. */
 const MAX_SESSION_BYTES = 30 * 1024 * 1024;
 async function fetchProxyStats(port) {
@@ -86,6 +87,9 @@ export async function collectDashboardData(proxyPort = 8787) {
         }
     }
     const proxy = await fetchProxyStats(proxyPort);
+    // The same lifetime figure `report` prints: ledger checkpoints (so a stopped
+    // proxy's savings still show) plus what the live run has not checkpointed.
+    const proxySaved = proxySavings(ledger, proxy);
     const loaded = loadConfig();
     let budget = null;
     if (loaded.path && loaded.config.budget && sessions.length > 0) {
@@ -98,9 +102,9 @@ export async function collectDashboardData(proxyPort = 8787) {
         totals: {
             // What context-doctor removed itself; compaction shrinkage is reported
             // separately (it was counted here until 0.24, which overclaimed).
-            tokensSaved: optimizeSaved + (proxy?.tokensSaved ?? 0),
+            tokensSaved: optimizeSaved + proxySaved.tokens,
             shrinkage,
-            usdSaved: usdSaved + (proxy?.estUsdSaved ?? 0),
+            usdSaved: usdSaved + proxySaved.usd,
             checks: checks.length + carried.checks,
             warnings: checks.filter((c) => c.warn).length + carried.warnings,
             optimizeRuns: optimizes.length,
@@ -111,9 +115,30 @@ export async function collectDashboardData(proxyPort = 8787) {
         budget,
     };
 }
+/**
+ * Whether a request's Host header names this machine's loopback.
+ *
+ * Listening on 127.0.0.1 is not enough on its own: a web page can rebind its
+ * own hostname to 127.0.0.1 (DNS rebinding) and then read /api/data, session
+ * titles included, as same-origin. Such a request still carries the attacker's
+ * hostname in Host, so only loopback names are answered.
+ */
+export function isLoopbackHost(host, port) {
+    if (!host)
+        return false;
+    const h = host.toLowerCase();
+    return ["127.0.0.1", "localhost", "[::1]"].some((name) => h === name || h === `${name}:${port}`);
+}
 export function startDashboard(opts = {}) {
     const port = opts.port ?? 8790;
     const server = http.createServer(async (req, res) => {
+        // The bound port, not the requested one: port 0 picks a free port.
+        const boundPort = server.address()?.port ?? port;
+        if (!isLoopbackHost(req.headers.host, boundPort)) {
+            res.statusCode = 403;
+            res.end("context-doctor dashboard: open it as http://127.0.0.1 or http://localhost");
+            return;
+        }
         try {
             if ((req.url ?? "").startsWith("/api/data")) {
                 const data = await collectDashboardData(opts.proxyPort);

package/dist/diff.js

@@ -16,10 +16,17 @@ import { profileConversation } from "./profile.js";
 import { parseSessionFile } from "./session.js";
 import { formatTokens } from "./tokens.js";
 import { formatUsd } from "./pricing.js";
-/** Load either a conversation file or a Claude Code / ChatGPT transcript. */
+/**
+ * Load either a conversation file or a Claude Code / Codex / ChatGPT / Gemini
+ * transcript. The session reader goes first whatever the extension: ChatGPT's
+ * conversations.json and Gemini chats are .json, and read as a plain
+ * conversation they became one message of raw text. A file it finds no
+ * messages in is a plain conversation (OpenAI/Anthropic messages JSON), as in
+ * `watch`.
+ */
 function loadProfile(path, model) {
-    if (path.endsWith(".jsonl")) {
-        const session = parseSessionFile(path);
+    const session = parseSessionFile(path);
+    if (session.messageCount > 0) {
         return profileConversation(parseConversation(session.conversationJson), model ?? session.model);
     }
     return profileConversation(parseConversation(readFileSync(path, "utf8")), model);