@echomem/mcp 1.3.1 → 1.3.2

package/dist/forensics.js

@@ -0,0 +1,717 @@
+/**
+ * Local "Context Doctor" forensic report — the pre-auth onboarding payload.
+ *
+ * Scans the user's LOCAL coding-agent transcripts (Claude Code under ~/.claude/projects AND Codex
+ * rollouts under ~/.codex/sessions) and turns them into a single MERGED workspace physical-exam:
+ * accomplishment (days/repos/tokens/cost/attention), the cost split (cold/cache/output per model),
+ * and the waste (token-reread forensics + a Context Cleanliness score). Everything is local; nothing
+ * leaves the machine and no model is called.
+ *
+ * Output shape mirrors the yeahecho `onboarding-two` ContextDoctorTwo report so the same UI renders it.
+ * Two source adapters feed ONE source-agnostic engine, so the reread/cleanliness logic is written once.
+ *
+ * Honesty (the team sanity-checks this): cost is an API-EQUIVALENT estimate at list prices, NOT a
+ * subscription bill; `time.*`/avoidableWait are ESTIMATES labeled as such; re-read % is a TOKEN share.
+ * Time-of-day buckets use the USER's LOCAL timezone (not a hardcoded one).
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { eachLine, walk } from "./report.js";
+// ---------------------------------------------------------------------------
+// Constants (named on purpose — no magic numbers downstream)
+// ---------------------------------------------------------------------------
+const WORK_BLOCK_GAP_MS = 30 * 60 * 1000; // >30min gap between real user prompts => new work block
+const FOCUS_DAY_HOURS = 5; // one "focused work day" == 5h of attention, for day-equivalent math
+const CONTEXT_REACQUISITION_FRACTION = 0.5; // ESTIMATE: share of stale-reread time felt as avoidable wait
+const NIGHT_HOURS = new Set([22, 23, 0, 1, 2, 3]); // late-night grind window (local tz)
+const CHARS_PER_TOKEN = 4; // rough token estimate for read (tool-result) output size
+// Per-million-token USD. API-equivalent ESTIMATE at list prices.
+const CLAUDE_PRICES = {
+    "claude-opus-4-8": { input: 15, cacheWrite: 18.75, cacheRead: 1.5, output: 75 },
+    "claude-opus-4-7": { input: 15, cacheWrite: 18.75, cacheRead: 1.5, output: 75 },
+    "claude-sonnet-4-6": { input: 3, cacheWrite: 3.75, cacheRead: 0.3, output: 15 },
+    "claude-haiku-4-5": { input: 1, cacheWrite: 1.25, cacheRead: 0.1, output: 5 },
+    "claude-fable-5": { input: 15, cacheWrite: 18.75, cacheRead: 1.5, output: 75 },
+};
+const CLAUDE_DEFAULT = CLAUDE_PRICES["claude-opus-4-8"];
+// OpenAI/Codex list-price ESTIMATE (no cache-write line; cached input billed ~10% of input).
+const OPENAI_PRICES = {
+    "gpt-5.5": { input: 1.25, cacheWrite: 0, cacheRead: 0.125, output: 10 },
+    "gpt-5": { input: 1.25, cacheWrite: 0, cacheRead: 0.125, output: 10 },
+    "gpt-5-codex": { input: 1.25, cacheWrite: 0, cacheRead: 0.125, output: 10 },
+};
+const OPENAI_DEFAULT = OPENAI_PRICES["gpt-5"];
+function priceFor(model) {
+    const table = model.startsWith("gpt") || model.startsWith("o1") || model.startsWith("o3") ? OPENAI_PRICES : CLAUDE_PRICES;
+    const def = table === OPENAI_PRICES ? OPENAI_DEFAULT : CLAUDE_DEFAULT;
+    if (table[model])
+        return table[model];
+    // Prefix match so dated ids (claude-haiku-4-5-20251001) get the family price.
+    for (const k of Object.keys(table))
+        if (model.startsWith(k))
+            return table[k];
+    return def;
+}
+function costOf(t, price) {
+    return (((t.cold || 0) * price.input +
+        (t.cacheWrite || 0) * price.cacheWrite +
+        (t.cacheRead || 0) * price.cacheRead +
+        (t.output || 0) * price.output) /
+        1_000_000);
+}
+// Files that are "project rules / design principles / repo map" — re-reading these unchanged is the
+// most quotable kind of waste.
+const PRINCIPLE_FILE_RE = /(^claude\.md$|^agents\.md$|^tokens\.css$|^readme|cursorrules|^foundations|principle)/i;
+const IMAGE_FILE_RE = /\.(png|jpe?g|gif|webp|svg|ico|avif|bmp|mp4|mov)$/i;
+// Shell read commands whose target file we try to extract for Codex reread forensics.
+const SHELL_READ_BINS = new Set(["cat", "head", "tail", "less", "more", "bat", "nl", "sed", "awk", "od", "strings"]);
+// ---------------------------------------------------------------------------
+// Local-time helpers (USER's tz — never hardcode a zone)
+// ---------------------------------------------------------------------------
+const WEEKDAYS = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
+function localDay(ms) {
+    const d = new Date(ms);
+    const m = String(d.getMonth() + 1).padStart(2, "0");
+    const day = String(d.getDate()).padStart(2, "0");
+    return `${d.getFullYear()}-${m}-${day}`;
+}
+const localHour = (ms) => new Date(ms).getHours();
+const localWeekday = (ms) => WEEKDAYS[new Date(ms).getDay()];
+function round(value, digits = 1) {
+    const f = 10 ** digits;
+    return Math.round((Number(value) || 0) * f) / f;
+}
+function tokensFromChars(chars = 0) {
+    return Math.round((chars || 0) / CHARS_PER_TOKEN);
+}
+function repoLabel(cwd) {
+    if (!cwd)
+        return "home";
+    const m = cwd.match(/worktrees\/[^/]+\/(.+)$/);
+    const base = path.basename(m ? m[1] : cwd);
+    return base && base !== "." && base !== "/" ? base : "home";
+}
+function fileLabel(filePath) {
+    return path.basename(String(filePath)) || "unknown";
+}
+function contentLength(content) {
+    if (content == null)
+        return 0;
+    if (typeof content === "string")
+        return content.length;
+    try {
+        return JSON.stringify(content).length;
+    }
+    catch {
+        return 0;
+    }
+}
+function isRealUserText(text) {
+    if (typeof text !== "string")
+        return false;
+    const t = text.trim();
+    if (!t)
+        return false;
+    if (t.startsWith("<"))
+        return false; // <system-reminder>, <command-…, <local-command…
+    if (t.startsWith("Caveat:"))
+        return false;
+    if (t.startsWith("[Request interrupted"))
+        return false;
+    if (t.startsWith("This session is being continued"))
+        return false;
+    if (t.includes("<command-name>") || t.includes("<local-command"))
+        return false;
+    return true;
+}
+/** Best-effort: pull the file a Codex read-style shell command targets (cat/sed/head FILE). */
+function extractReadPath(cmd) {
+    const tokens = String(cmd).trim().split(/\s+/);
+    let bin = (tokens[0] || "").split("/").pop() || "";
+    if (bin === "sudo")
+        bin = (tokens[1] || "").split("/").pop() || "";
+    if (!SHELL_READ_BINS.has(bin))
+        return null;
+    // last token that looks like a path (has a / or a file extension, not a flag/number)
+    for (let i = tokens.length - 1; i >= 1; i--) {
+        const t = tokens[i].replace(/['"]/g, "");
+        if (!t || t.startsWith("-"))
+            continue;
+        if (t.includes("/") || /\.[A-Za-z0-9]{1,6}$/.test(t))
+            return t;
+    }
+    return null;
+}
+class Forensics {
+    models = new Map();
+    repos = new Map();
+    files = new Map();
+    fileVersions = new Map();
+    lastReadVersion = new Map();
+    fileReadSessions = new Map();
+    pendingReads = new Map();
+    hourHistogram = new Array(24).fill(0);
+    weekdayCounts = new Map();
+    lateNightSessions = new Map();
+    allSessionIds = new Set();
+    realUserTurns = 0;
+    minTs = null;
+    maxTs = null;
+    nightExample = null;
+    modelBucket(model) {
+        const key = model || "unknown";
+        let m = this.models.get(key);
+        if (!m) {
+            m = { messages: 0, cold: 0, cacheWrite: 0, cacheRead: 0, output: 0 };
+            this.models.set(key, m);
+        }
+        return m;
+    }
+    repoBucket(cwd) {
+        const name = repoLabel(cwd);
+        let r = this.repos.get(name);
+        if (!r) {
+            r = { name, sessions: new Set(), assistantMessages: 0, cold: 0, cacheWrite: 0, cacheRead: 0, output: 0, reads: 0, rereads: 0, staleRereads: 0, userTimestamps: [] };
+            this.repos.set(name, r);
+        }
+        return r;
+    }
+    fileRecord(p, repo) {
+        let rec = this.files.get(p);
+        if (!rec) {
+            const label = fileLabel(p);
+            rec = {
+                label, repo, isPrinciple: PRINCIPLE_FILE_RE.test(label), isImage: IMAGE_FILE_RE.test(label),
+                totalReads: 0, rereads: 0, staleRereads: 0, crossSessionRereads: 0, everEdited: false, editCount: 0,
+                readTokens: 0, staleReadTokens: 0, perSession: new Map(), days: new Set(), nightReads: 0,
+            };
+            this.files.set(p, rec);
+        }
+        return rec;
+    }
+    noteTs(ms) {
+        if (this.minTs == null || ms < this.minTs)
+            this.minTs = ms;
+        if (this.maxTs == null || ms > this.maxTs)
+            this.maxTs = ms;
+    }
+    noteSession(id) {
+        if (id)
+            this.allSessionIds.add(id);
+    }
+    /** assistant-turn token usage (already split into cold/cacheWrite/cacheRead/output). */
+    recordUsage(model, cwd, session, u) {
+        const m = this.modelBucket(model);
+        m.messages += 1;
+        m.cold += u.cold;
+        m.cacheWrite += u.cacheWrite;
+        m.cacheRead += u.cacheRead;
+        m.output += u.output;
+        if (cwd) {
+            const r = this.repoBucket(cwd);
+            if (session)
+                r.sessions.add(session);
+            r.assistantMessages += 1;
+            r.cold += u.cold;
+            r.cacheWrite += u.cacheWrite;
+            r.cacheRead += u.cacheRead;
+            r.output += u.output;
+        }
+    }
+    recordEdit(target, cwd) {
+        if (!target)
+            return;
+        this.fileVersions.set(target, (this.fileVersions.get(target) || 0) + 1);
+        const rec = this.fileRecord(target, repoLabel(cwd));
+        rec.everEdited = true;
+        rec.editCount += 1;
+    }
+    /** A file read; decides stale/cross-session at read time and parks the token settle by toolId. */
+    recordRead(target, cwd, session, ms, toolId) {
+        if (!target)
+            return;
+        const repo = repoLabel(cwd);
+        const rec = this.fileRecord(target, repo);
+        const priorReads = rec.totalReads;
+        const currentVersion = this.fileVersions.get(target) || 0;
+        const seenSessions = this.fileReadSessions.get(target) || new Set();
+        const isReread = priorReads > 0;
+        const crossSession = isReread && !!session && !seenSessions.has(session);
+        const changedSinceLastRead = isReread && currentVersion > (this.lastReadVersion.get(target) || 0);
+        const stale = isReread && !changedSinceLastRead;
+        rec.totalReads += 1;
+        if (cwd)
+            this.repoBucket(cwd).reads += 1;
+        if (isReread) {
+            rec.rereads += 1;
+            if (cwd)
+                this.repoBucket(cwd).rereads += 1;
+        }
+        if (crossSession)
+            rec.crossSessionRereads += 1;
+        if (stale) {
+            rec.staleRereads += 1;
+            if (cwd)
+                this.repoBucket(cwd).staleRereads += 1;
+        }
+        const day = ms != null ? localDay(ms) : "unknown";
+        const hour = ms != null ? localHour(ms) : 12;
+        const isNight = NIGHT_HOURS.has(hour);
+        rec.days.add(day);
+        if (isNight)
+            rec.nightReads += 1;
+        const ps = rec.perSession.get(session || "") || { count: 0, day, nightCount: 0 };
+        ps.count += 1;
+        if (isNight)
+            ps.nightCount += 1;
+        rec.perSession.set(session || "", ps);
+        if (stale && isNight) {
+            const candidate = { file: rec.label, path: target, repo, day, hour, sessionShort: (session || "").slice(0, 8), priorReads };
+            if (!this.nightExample || priorReads > this.nightExample.priorReads)
+                this.nightExample = candidate;
+        }
+        if (!this.fileReadSessions.has(target))
+            this.fileReadSessions.set(target, new Set());
+        if (session)
+            this.fileReadSessions.get(target).add(session);
+        this.lastReadVersion.set(target, currentVersion);
+        if (toolId)
+            this.pendingReads.set(toolId, { rec, stale });
+    }
+    recordReadOutput(toolId, chars) {
+        const pending = this.pendingReads.get(toolId);
+        if (!pending)
+            return;
+        const tokens = tokensFromChars(chars);
+        pending.rec.readTokens += tokens;
+        if (pending.stale)
+            pending.rec.staleReadTokens += tokens;
+        this.pendingReads.delete(toolId);
+    }
+    recordUserMsg(cwd, session, ms) {
+        this.realUserTurns += 1;
+        const hour = localHour(ms);
+        this.hourHistogram[hour] += 1;
+        const wd = localWeekday(ms);
+        this.weekdayCounts.set(wd, (this.weekdayCounts.get(wd) || 0) + 1);
+        if (cwd)
+            this.repoBucket(cwd).userTimestamps.push(ms);
+        if (NIGHT_HOURS.has(hour) && session) {
+            const ln = this.lateNightSessions.get(session) || { repo: repoLabel(cwd), day: localDay(ms), nightMsgs: 0 };
+            ln.nightMsgs += 1;
+            this.lateNightSessions.set(session, ln);
+        }
+    }
+    // ----- work blocks (real attention hours) -----
+    workBlocks(timestamps) {
+        const sorted = [...timestamps].sort((a, b) => a - b);
+        const blocks = [];
+        let start = null;
+        let last = null;
+        for (const ms of sorted) {
+            if (start == null) {
+                start = ms;
+                last = ms;
+                continue;
+            }
+            if (ms - last > WORK_BLOCK_GAP_MS) {
+                blocks.push({ start, end: last });
+                start = ms;
+            }
+            last = ms;
+        }
+        if (start != null)
+            blocks.push({ start, end: last });
+        const attentionHours = blocks.reduce((s, b) => s + (b.end - b.start) / 3_600_000, 0);
+        const days = new Set(blocks.map((b) => localDay(b.start)));
+        return { blocks, attentionHours, activeDays: days.size };
+    }
+    build() {
+        // ----- tokens + cost -----
+        let cold = 0, cacheWrite = 0, cacheRead = 0, output = 0;
+        const modelOut = {};
+        for (const [name, m] of this.models) {
+            cold += m.cold;
+            cacheWrite += m.cacheWrite;
+            cacheRead += m.cacheRead;
+            output += m.output;
+            if (name === "<synthetic>" || m.cold + m.cacheWrite + m.cacheRead + m.output === 0)
+                continue;
+            const price = priceFor(name);
+            modelOut[name] = {
+                messages: m.messages, cold: m.cold, cacheWrite: m.cacheWrite, cacheRead: m.cacheRead, output: m.output,
+                total: m.cold + m.cacheWrite + m.cacheRead + m.output, cost: round(costOf(m, price), 2),
+            };
+        }
+        const totalInput = cold + cacheWrite + cacheRead;
+        const totalTokens = totalInput + output;
+        const cost = {
+            coldInputCost: round((cold / 1e6) * CLAUDE_DEFAULT.input, 2),
+            cacheWriteCost: round((cacheWrite / 1e6) * CLAUDE_DEFAULT.cacheWrite, 2),
+            cacheReadCost: round((cacheRead / 1e6) * CLAUDE_DEFAULT.cacheRead, 2),
+            outputCost: round((output / 1e6) * CLAUDE_DEFAULT.output, 2),
+            total: 0,
+        };
+        // total cost = sum of per-model costs (so mixed providers price correctly)
+        cost.total = round(Object.values(modelOut).reduce((s, m) => s + m.cost, 0), 2);
+        const rankedModels = Object.entries(modelOut).sort((a, b) => b[1].total - a[1].total);
+        const topModel = rankedModels[0]?.[0] || "unknown";
+        const topShare = totalTokens ? Math.round(((rankedModels[0]?.[1].total || 0) / totalTokens) * 100) : 0;
+        let identityLabel = "workspace power user";
+        if (topShare >= 95)
+            identityLabel = "all-in frontier-model builder";
+        else if (rankedModels.length >= 3)
+            identityLabel = "multi-model operator";
+        else if (topShare >= 75)
+            identityLabel = "primary-model power user";
+        // ----- per-repo attention + global -----
+        const allUserTimestamps = [];
+        const dayAttention = new Map();
+        const repoOut = [];
+        for (const repo of this.repos.values()) {
+            allUserTimestamps.push(...repo.userTimestamps);
+            const wb = this.workBlocks(repo.userTimestamps);
+            repoOut.push({
+                name: repo.name, sessions: repo.sessions.size, assistantMessages: repo.assistantMessages,
+                attentionHours: round(wb.attentionHours, 1), activeAttentionDays: wb.activeDays,
+                dailyFocusHours: wb.activeDays ? round(wb.attentionHours / wb.activeDays, 2) : 0,
+                equivalentFocusDays: round(wb.attentionHours / FOCUS_DAY_HOURS, 1), workBlocks: wb.blocks.length,
+                tokens: repo.cold + repo.cacheWrite + repo.cacheRead + repo.output,
+                cost: round(costOf({ cold: repo.cold, cacheWrite: repo.cacheWrite, cacheRead: repo.cacheRead, output: repo.output }, CLAUDE_DEFAULT), 2),
+                reads: repo.reads, rereads: repo.rereads, staleRereads: repo.staleRereads,
+            });
+            for (const b of wb.blocks) {
+                const d = localDay(b.start);
+                dayAttention.set(d, (dayAttention.get(d) || 0) + (b.end - b.start) / 3_600_000);
+            }
+        }
+        repoOut.sort((a, b) => b.attentionHours - a.attentionHours || b.tokens - a.tokens);
+        const globalBlocks = this.workBlocks(allUserTimestamps);
+        const userAttentionHours = round(globalBlocks.attentionHours, 1);
+        const activeAttentionDays = globalBlocks.activeDays;
+        const dayHoursList = [...dayAttention.entries()].sort((a, b) => b[1] - a[1]);
+        const peakDay = dayHoursList[0] ? { date: dayHoursList[0][0], hours: round(dayHoursList[0][1], 1) } : null;
+        // ----- rhythm -----
+        const sumHours = (hrs) => hrs.reduce((s, h) => s + this.hourHistogram[h], 0);
+        const totalMsgForShare = Math.max(this.realUserTurns, 1);
+        const busiestWeekday = [...this.weekdayCounts.entries()].sort((a, b) => b[1] - a[1])[0]?.[0] || null;
+        const lateNightSessionList = [...this.lateNightSessions.entries()]
+            .map(([id, v]) => ({ session: id.slice(0, 8), repo: v.repo, day: v.day, nightMsgs: v.nightMsgs }))
+            .sort((a, b) => b.nightMsgs - a.nightMsgs)
+            .slice(0, 6);
+        // ----- cleanliness (token-weighted; non-image code/text reads only) -----
+        const codeFiles = [...this.files.values()].filter((f) => !f.isImage && f.totalReads > 0);
+        const codeReadTokens = codeFiles.reduce((s, f) => s + f.readTokens, 0);
+        const codeStaleReadTokens = codeFiles.reduce((s, f) => s + f.staleReadTokens, 0);
+        const codeReads = codeFiles.reduce((s, f) => s + f.totalReads, 0);
+        const codeRereads = codeFiles.reduce((s, f) => s + f.rereads, 0);
+        const codeStaleRereads = codeFiles.reduce((s, f) => s + f.staleRereads, 0);
+        const codeCrossStale = codeFiles.reduce((s, f) => s + f.crossSessionRereads, 0);
+        const staleShare = codeReadTokens ? codeStaleReadTokens / codeReadTokens : 0;
+        const cleanlinessScore = Math.max(0, Math.min(100, Math.round(100 * (1 - staleShare))));
+        // ----- reread forensics -----
+        const ranked = [...this.files.values()]
+            .filter((f) => f.totalReads > 0 && !f.isImage)
+            .sort((a, b) => b.crossSessionRereads - a.crossSessionRereads || b.perSession.size - a.perSession.size || b.rereads - a.rereads || b.totalReads - a.totalReads);
+        const topFiles = ranked.slice(0, 12).map((f) => ({
+            file: f.label, repo: f.repo, isPrinciple: f.isPrinciple, totalReads: f.totalReads, rereads: f.rereads,
+            staleRereads: f.staleRereads, crossSessionRereads: f.crossSessionRereads, everChanged: f.everEdited,
+            editCount: f.editCount, sessionsTouched: f.perSession.size, daysTouched: f.days.size, nightReads: f.nightReads,
+            readTokens: f.readTokens, staleReadTokens: f.staleReadTokens,
+            perSession: [...f.perSession.entries()].map(([id, v]) => ({ session: (id || "").slice(0, 8), count: v.count, day: v.day, nightCount: v.nightCount })).sort((a, b) => b.count - a.count).slice(0, 6),
+        }));
+        const neverChangedHeavy = ranked.filter((f) => !f.everEdited && f.rereads >= 2).slice(0, 8).map((f) => ({
+            file: f.label, repo: f.repo, isPrinciple: f.isPrinciple, totalReads: f.totalReads,
+            sessionsTouched: f.perSession.size, daysTouched: f.days.size, nightReads: f.nightReads, staleReadTokens: f.staleReadTokens,
+        }));
+        const principleReads = ranked.filter((f) => f.isPrinciple && f.rereads > 0).sort((a, b) => b.staleReadTokens - a.staleReadTokens).slice(0, 6).map((f) => ({
+            file: f.label, repo: f.repo, totalReads: f.totalReads, staleReadTokens: f.staleReadTokens, sessionsTouched: f.perSession.size,
+        }));
+        // ----- avoidable wait + counterfactual (ESTIMATES) -----
+        const dailyFocus = activeAttentionDays ? userAttentionHours / activeAttentionDays : repoOut[0]?.dailyFocusHours || 0;
+        const avoidableWaitHours = round(userAttentionHours * staleShare * CONTEXT_REACQUISITION_FRACTION, 1);
+        const avoidableWaitDays = dailyFocus ? round(avoidableWaitHours / dailyFocus, 1) : 0;
+        const daysAgo = Math.max(1, Math.round(avoidableWaitDays));
+        const scanEnd = this.maxTs ?? Date.now();
+        const cfDate = scanEnd - daysAgo * 86_400_000;
+        return {
+            generatedFrom: ["~/.codex/sessions", "~/.claude/projects"],
+            llmCallsUsed: 0,
+            transcriptsUploaded: false,
+            scanStartDate: this.minTs != null ? localDay(this.minTs) : null,
+            scanEndDate: this.maxTs != null ? localDay(this.maxTs) : null,
+            scale: {
+                sessionCount: this.allSessionIds.size,
+                repoCount: repoOut.length,
+                activeDays: activeAttentionDays,
+                totalTokens, totalInputTokens: totalInput, coldInputTokens: cold, cacheWriteTokens: cacheWrite,
+                cacheReadTokens: cacheRead, outputTokens: output,
+                inputPct: totalTokens ? Math.round((totalInput / totalTokens) * 100) : 0,
+            },
+            cost: { ...cost, byModel: modelOut },
+            modelUsage: { topModel, topModelShare: topShare, identityLabel },
+            userWorkingHours: {
+                realUserTurns: this.realUserTurns, userAttentionHours, activeAttentionDays,
+                averageDailyAttentionHours: activeAttentionDays ? round(userAttentionHours / activeAttentionDays, 2) : 0,
+                maxDailyAttentionHours: peakDay ? peakDay.hours : 0, peakDay, workBlocks: globalBlocks.blocks.length,
+            },
+            repos: repoOut,
+            rhythm: {
+                hourHistogram: this.hourHistogram,
+                morningShare: Math.round((sumHours([5, 6, 7, 8, 9, 10, 11]) / totalMsgForShare) * 100),
+                eveningShare: Math.round((sumHours([18, 19, 20, 21]) / totalMsgForShare) * 100),
+                lateNightShare: Math.round((sumHours([22, 23, 0, 1, 2, 3]) / totalMsgForShare) * 100),
+                lateNightSessionCount: this.lateNightSessions.size, lateNightSessions: lateNightSessionList,
+                busiestWeekday, peakDay,
+            },
+            cleanliness: {
+                score: cleanlinessScore, totalReads: codeReads, rereads: codeRereads, staleRereads: codeStaleRereads,
+                crossSessionStaleReads: codeCrossStale, totalReadTokens: codeReadTokens, staleReadTokens: codeStaleReadTokens,
+                staleReadSharePct: Math.round(staleShare * 100),
+            },
+            rereadForensics: { topFiles, neverChangedHeavy, principleReads, nightExample: this.nightExample },
+            avoidableWait: { readTokens: codeStaleReadTokens, hours: avoidableWaitHours, days: avoidableWaitDays, cost: round(costOf({ cold: codeStaleReadTokens }, CLAUDE_DEFAULT), 2) },
+            counterfactual: { daysAgo, counterfactualDate: localDay(cfDate), daysGained: avoidableWaitDays, targetScore: Math.min(100, cleanlinessScore + 30) },
+        };
+    }
+}
+// ---------------------------------------------------------------------------
+// Source adapters — translate each log schema into engine calls
+// ---------------------------------------------------------------------------
+/** Claude Code (~/.claude/projects). usage is per assistant turn; tools live in message.content. */
+function feedClaude(file, eng) {
+    eachLine(file, (o) => {
+        const ts = typeof o.timestamp === "string" ? Date.parse(o.timestamp) : NaN;
+        if (Number.isFinite(ts))
+            eng.noteTs(ts);
+        const session = o.sessionId || null;
+        eng.noteSession(session);
+        const cwd = o.cwd || null;
+        if (o.type === "assistant" && o.message) {
+            const u = o.message.usage || {};
+            eng.recordUsage(o.message.model || "unknown", cwd, session, {
+                cold: u.input_tokens || 0, cacheWrite: u.cache_creation_input_tokens || 0,
+                cacheRead: u.cache_read_input_tokens || 0, output: u.output_tokens || 0,
+            });
+            const blocks = Array.isArray(o.message.content) ? o.message.content : [];
+            for (const b of blocks) {
+                if (b?.type !== "tool_use")
+                    continue;
+                const name = String(b.name || "");
+                if (name === "Edit" || name === "Write" || name === "MultiEdit") {
+                    const target = b.input?.file_path || b.input?.path;
+                    if (target)
+                        eng.recordEdit(target, cwd);
+                }
+                else if (name === "Read") {
+                    const target = b.input?.file_path;
+                    if (target)
+                        eng.recordRead(target, cwd, session, Number.isFinite(ts) ? ts : null, b.id || null);
+                }
+            }
+            return;
+        }
+        if (o.type === "user" && o.message) {
+            const content = o.message.content;
+            if (typeof content === "string") {
+                if (isRealUserText(content) && Number.isFinite(ts) && !o.isSidechain)
+                    eng.recordUserMsg(cwd, session, ts);
+            }
+            else if (Array.isArray(content)) {
+                for (const b of content) {
+                    if (b?.type === "tool_result" && b.tool_use_id)
+                        eng.recordReadOutput(b.tool_use_id, contentLength(b.content));
+                }
+            }
+        }
+    });
+}
+/** Parse one Codex rollout into a compact, cacheable FileEvents. token_count is CUMULATIVE (delta'd);
+ * edits arrive via patch_apply_end; reads are exec_command shell commands (path extracted best-effort). */
+function extractCodex(file) {
+    let cwd = null;
+    let session = null;
+    // Default to a Codex/OpenAI model so token counts logged before the model field appears are priced
+    // as OpenAI (not the Claude opus default) — the real model overrides this as soon as it's seen.
+    let model = "gpt-5-codex";
+    let prev = { cold: 0, cacheRead: 0, output: 0 }; // last cumulative seen (for deltas)
+    let firstTs = null;
+    let lastTs = null;
+    const usageByModel = new Map();
+    const ev = [];
+    eachLine(file, (o) => {
+        const ts = typeof o.timestamp === "string" ? Date.parse(o.timestamp) : NaN;
+        if (Number.isFinite(ts)) {
+            if (firstTs == null)
+                firstTs = ts;
+            lastTs = ts;
+        }
+        const p = o && typeof o.payload === "object" && o.payload ? o.payload : o;
+        if (!p || typeof p !== "object")
+            return;
+        if (o.type === "session_meta") {
+            if (typeof p.cwd === "string")
+                cwd = p.cwd;
+            if (typeof p.id === "string" && !session)
+                session = p.id;
+            return;
+        }
+        if (typeof p.model === "string")
+            model = p.model;
+        if (p.type === "token_count") {
+            const u = p.info?.total_token_usage;
+            if (u) {
+                const inputTotal = u.input_tokens || 0;
+                const cacheRead = u.cached_input_tokens || 0;
+                const cold = Math.max(0, inputTotal - cacheRead);
+                const out = (u.output_tokens || 0) + (u.reasoning_output_tokens || 0);
+                const dCold = Math.max(0, cold - prev.cold);
+                const dCr = Math.max(0, cacheRead - prev.cacheRead);
+                const dOut = Math.max(0, out - prev.output);
+                if (dCold || dCr || dOut) {
+                    const acc = usageByModel.get(model) || { cold: 0, cacheRead: 0, output: 0 };
+                    acc.cold += dCold;
+                    acc.cacheRead += dCr;
+                    acc.output += dOut;
+                    usageByModel.set(model, acc);
+                }
+                prev = { cold, cacheRead, output: out };
+            }
+            return;
+        }
+        if (p.type === "user_message") {
+            if (Number.isFinite(ts))
+                ev.push({ t: "m", ms: ts });
+            return;
+        }
+        if (p.type === "patch_apply_end" && p.changes && typeof p.changes === "object") {
+            for (const target of Object.keys(p.changes))
+                ev.push({ t: "e", path: target });
+            return;
+        }
+        // older format: exec_command_end with parsed_cmd[].type==='read'
+        if (p.type === "exec_command_end" && Array.isArray(p.parsed_cmd)) {
+            for (const c of p.parsed_cmd) {
+                if (c?.type === "read" && typeof c.path === "string")
+                    ev.push({ t: "r", path: c.path, ms: Number.isFinite(ts) ? ts : null, id: p.call_id || null });
+            }
+            return;
+        }
+        // newer format: reads are exec_command function_calls; extract the path best-effort
+        if (p.type === "function_call" && (p.name === "exec_command" || p.name === "shell")) {
+            try {
+                const args = JSON.parse(typeof p.arguments === "string" ? p.arguments : "{}");
+                const target = typeof args.cmd === "string" ? extractReadPath(args.cmd) : null;
+                if (target)
+                    ev.push({ t: "r", path: target, ms: Number.isFinite(ts) ? ts : null, id: p.call_id || null });
+            }
+            catch {
+                /* skip */
+            }
+            return;
+        }
+        if (p.type === "function_call_output" && p.call_id) {
+            ev.push({ t: "o", id: p.call_id, chars: contentLength(p.output) });
+        }
+    });
+    const usage = [...usageByModel.entries()].map(([m, u]) => ({ model: m, cold: u.cold, cacheRead: u.cacheRead, output: u.output }));
+    return { source: "codex", session, cwd, firstTs, lastTs, usage, ev };
+}
+/** Replay a parsed FileEvents into the engine. Usage is order-independent; reads/edits keep file order
+ * so cross-session reread detection is identical to a live scan of the same files in the same order. */
+function replayFile(eng, fe) {
+    if (fe.firstTs != null)
+        eng.noteTs(fe.firstTs);
+    if (fe.lastTs != null)
+        eng.noteTs(fe.lastTs);
+    eng.noteSession(fe.session);
+    for (const u of fe.usage)
+        eng.recordUsage(u.model, fe.cwd, fe.session, { cold: u.cold, cacheWrite: 0, cacheRead: u.cacheRead, output: u.output });
+    for (const e of fe.ev) {
+        if (e.t === "m")
+            eng.recordUserMsg(fe.cwd, fe.session, e.ms);
+        else if (e.t === "e")
+            eng.recordEdit(e.path, fe.cwd);
+        else if (e.t === "r")
+            eng.recordRead(e.path, fe.cwd, fe.session, e.ms, e.id);
+        else if (e.t === "o")
+            eng.recordReadOutput(e.id, e.chars);
+    }
+}
+// ---------------------------------------------------------------------------
+// Per-file parse cache — keyed by path+mtime+size so re-runs only reparse changed/new Codex files.
+// ---------------------------------------------------------------------------
+const CACHE_VERSION = 1;
+function forensicCachePath() {
+    return path.join(os.homedir(), ".echomem", "forensic-cache.json");
+}
+function loadForensicCache() {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(forensicCachePath(), "utf8"));
+        if (parsed && parsed.v === CACHE_VERSION && parsed.files && typeof parsed.files === "object")
+            return parsed.files;
+    }
+    catch {
+        /* no cache yet, or a stale/corrupt one — rebuild */
+    }
+    return {};
+}
+function saveForensicCache(files) {
+    try {
+        const p = forensicCachePath();
+        fs.mkdirSync(path.dirname(p), { recursive: true });
+        fs.writeFileSync(p, JSON.stringify({ v: CACHE_VERSION, files }));
+    }
+    catch {
+        /* best effort: a cache write failure must never break the scan */
+    }
+}
+/** Scan both sources and build the merged forensic report. Local-only, $0, never throws on bad files. */
+export function buildForensicReport(opts) {
+    const sources = opts?.sources ?? ["codex", "claude"];
+    const eng = new Forensics();
+    // Path-sorted within each source so the order-dependent reread/version state is deterministic.
+    const codexFiles = sources.includes("codex")
+        ? walk(path.join(os.homedir(), ".codex", "sessions"), (p) => /rollout-.*\.jsonl$/.test(p), () => false).sort()
+        : [];
+    // Include ALL Claude transcripts (subagents/workflows too): their reads/tokens are real agent activity.
+    const claudeFiles = sources.includes("claude")
+        ? walk(path.join(os.homedir(), ".claude", "projects"), (p) => p.endsWith(".jsonl"), () => false).sort()
+        : [];
+    const total = codexFiles.length + claudeFiles.length;
+    let done = 0;
+    const tick = () => {
+        done++;
+        if (opts?.onProgress && (done % 8 === 0 || done === total))
+            opts.onProgress(done, total);
+    };
+    // Codex is the slow source (GB-scale rollouts). Cache each file's parse by mtime+size so only
+    // changed/new sessions reparse; the cross-session reread state is rebuilt from the cached events in
+    // the same file order, so the result is identical to a live scan.
+    const cache = loadForensicCache();
+    const nextCache = {};
+    for (const f of codexFiles) {
+        let st;
+        try {
+            st = fs.statSync(f);
+        }
+        catch {
+            tick();
+            continue;
+        }
+        const hit = cache[f];
+        const fe = hit && hit.mtimeMs === st.mtimeMs && hit.size === st.size ? hit.fe : extractCodex(f);
+        nextCache[f] = { mtimeMs: st.mtimeMs, size: st.size, fe };
+        replayFile(eng, fe);
+        tick();
+    }
+    if (codexFiles.length)
+        saveForensicCache(nextCache);
+    // Claude is fast (~0.6s) — scan live, no cache needed.
+    for (const f of claudeFiles) {
+        feedClaude(f, eng);
+        tick();
+    }
+    return eng.build();
+}