@echomem/mcp 1.4.7 → 1.4.9

package/dist/forensics.js

@@ -18,7 +18,13 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { execFileSync } from "node:child_process";
+import { calculateContextMetrics } from "./context-metrics/calculate.js";
+import { resolveModelContextLimit } from "./context-metrics/model-limits.js";
+import { buildWorkspaceContextReport } from "./context-analysis/workspace-report.js";
+import { buildCanonicalGoldenReport } from "./context-analysis/canonical-golden.js";
 import { eachLine, walk } from "./report.js";
+import { discoverCodexSessionFiles } from "./codex-session-files.js";
+import { resolveClaudeProjectsDir } from "./local-data-paths.js";
 /** Fast, safe per-repo commit count since a date. Metadata only (no diffs) so it stays cheap;
  * `rev-list --count` is git-indexed. Any failure (not a repo, git missing, timeout) → 0. */
 function gitCommitCount(cwd, sinceIso) {
@@ -45,39 +51,96 @@ const FOCUS_DAY_HOURS = 5; // one "focused work day" == 5h of attention, for day
 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.
+// Per-million-token USD. Standard API-equivalent list prices, reviewed 2026-07-12.
+// These are deliberately model-specific: using an Opus fallback for every repo was the source of
+// the old impossible city math where two repo labels alone exceeded TOTAL SPENT.
 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-fable-5": { input: 10, cacheWrite: 12.5, cacheRead: 1, output: 50 },
+    "claude-opus-4-8": { input: 5, cacheWrite: 6.25, cacheRead: 0.5, output: 25 },
+    "claude-opus-4-7": { input: 5, cacheWrite: 6.25, cacheRead: 0.5, output: 25 },
+    "claude-opus-4-6": { input: 5, cacheWrite: 6.25, cacheRead: 0.5, output: 25 },
+    "claude-opus-4-5": { input: 5, cacheWrite: 6.25, cacheRead: 0.5, output: 25 },
     "claude-sonnet-4-6": { input: 3, cacheWrite: 3.75, cacheRead: 0.3, output: 15 },
+    "claude-sonnet-4-5": { 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 CLAUDE_SONNET_5_INTRO = { input: 2, cacheWrite: 2.5, cacheRead: 0.2, output: 10 };
+const CLAUDE_SONNET_5_STANDARD = { input: 3, cacheWrite: 3.75, cacheRead: 0.3, output: 15 };
+const CLAUDE_SONNET_5_STANDARD_START_MS = Date.parse("2026-09-01T00:00:00.000Z");
+const CLAUDE_DEFAULT = CLAUDE_PRICES["claude-sonnet-4-6"];
+// OpenAI/Codex list prices. GPT-5.6 adds explicit cache writes; older Codex logs expose only
+// uncached and cached input, so their cacheWrite rate remains zero.
 const OPENAI_PRICES = {
-    "gpt-5.5": { input: 1.25, cacheWrite: 0, cacheRead: 0.125, output: 10 },
+    "gpt-5.6-terra": { input: 2.5, cacheWrite: 3.125, cacheRead: 0.25, output: 15 },
+    "gpt-5.6-luna": { input: 1, cacheWrite: 1.25, cacheRead: 0.1, output: 6 },
+    "gpt-5.6-sol": { input: 5, cacheWrite: 6.25, cacheRead: 0.5, output: 30 },
+    "gpt-5.6": { input: 5, cacheWrite: 6.25, cacheRead: 0.5, output: 30 },
+    "gpt-5.4-mini": { input: 0.75, cacheWrite: 0, cacheRead: 0.075, output: 4.5 },
+    "gpt-5.4-nano": { input: 0.2, cacheWrite: 0, cacheRead: 0.02, output: 1.25 },
+    "gpt-5.5": { input: 5, cacheWrite: 0, cacheRead: 0.5, output: 30 },
+    "gpt-5.4": { input: 2.5, cacheWrite: 0, cacheRead: 0.25, output: 15 },
     "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) {
+function longestPrefixPrice(table, model) {
+    const key = Object.keys(table)
+        .filter((candidate) => model.startsWith(candidate))
+        .sort((a, b) => b.length - a.length)[0];
+    return key ? table[key] : null;
+}
+function priceFor(model, ms) {
+    if (model.startsWith("claude-sonnet-5")) {
+        const at = typeof ms === "number" && Number.isFinite(ms) ? ms : Date.now();
+        return at < CLAUDE_SONNET_5_STANDARD_START_MS ? CLAUDE_SONNET_5_INTRO : CLAUDE_SONNET_5_STANDARD;
+    }
     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);
+    return table[model] || longestPrefixPrice(table, model) || def;
+}
+function hasOpenAiLongContextPremium(model, inputTokens) {
+    if (inputTokens <= 272_000 || model.startsWith("gpt-5.4-mini") || model.startsWith("gpt-5.4-nano"))
+        return false;
+    return model.startsWith("gpt-5.4") || model.startsWith("gpt-5.5") || model.startsWith("gpt-5.6");
+}
+export function estimateApiEquivalentCost(model, t, ms) {
+    const price = priceFor(model, ms);
+    const inputTokens = (t.cold || 0) + (t.cacheWrite || 0) + (t.cacheRead || 0);
+    const longContextPremiumApplied = hasOpenAiLongContextPremium(model, inputTokens);
+    const inputMultiplier = longContextPremiumApplied ? 2 : 1;
+    const outputMultiplier = longContextPremiumApplied ? 1.5 : 1;
+    const coldInputCost = ((t.cold || 0) * price.input * inputMultiplier) / 1_000_000;
+    const cacheWriteCost = ((t.cacheWrite || 0) * price.cacheWrite * inputMultiplier) / 1_000_000;
+    const cacheReadCost = ((t.cacheRead || 0) * price.cacheRead * inputMultiplier) / 1_000_000;
+    const outputCost = ((t.output || 0) * price.output * outputMultiplier) / 1_000_000;
+    return {
+        coldInputCost,
+        cacheWriteCost,
+        cacheReadCost,
+        outputCost,
+        total: coldInputCost + cacheWriteCost + cacheReadCost + outputCost,
+        longContextPremiumApplied,
+    };
+}
+function emptyCostAccumulator() {
+    return { coldInputCost: 0, cacheWriteCost: 0, cacheReadCost: 0, outputCost: 0, total: 0, longContextRequestCount: 0 };
+}
+function addEstimatedCost(target, value) {
+    target.coldInputCost += value.coldInputCost;
+    target.cacheWriteCost += value.cacheWriteCost;
+    target.cacheReadCost += value.cacheReadCost;
+    target.outputCost += value.outputCost;
+    target.total += value.total;
+    if (value.longContextPremiumApplied)
+        target.longContextRequestCount += 1;
+}
+function addAccumulatedCost(target, value) {
+    target.coldInputCost += value.coldInputCost;
+    target.cacheWriteCost += value.cacheWriteCost;
+    target.cacheReadCost += value.cacheReadCost;
+    target.outputCost += value.outputCost;
+    target.total += value.total;
+    target.longContextRequestCount += value.longContextRequestCount;
 }
 // Files that are "project rules / design principles / repo map" — re-reading these unchanged is the
 // most quotable kind of waste.
@@ -111,6 +174,23 @@ export function repoLabel(cwd) {
     const base = path.basename(m ? m[1] : cwd);
     return base && base !== "." && base !== "/" ? base : "home";
 }
+function fileIdentity(target, cwd) {
+    const value = String(target).trim();
+    if (!value)
+        return "unknown";
+    if (value === "~")
+        return os.homedir();
+    if (value.startsWith(`~${path.sep}`) || value.startsWith("~/")) {
+        return path.normalize(path.join(os.homedir(), value.slice(2)));
+    }
+    if (path.isAbsolute(value))
+        return path.normalize(value);
+    if (cwd && path.isAbsolute(cwd))
+        return path.resolve(cwd, value);
+    // An unknown/relative cwd cannot safely be resolved against the MCP process cwd. Namespace it so
+    // identical relative paths in unrelated workspaces never become the same forensic file.
+    return `${repoLabel(cwd)}::${path.normalize(value)}`;
+}
 function fileLabel(filePath) {
     return path.basename(String(filePath)) || "unknown";
 }
@@ -170,6 +250,8 @@ class Forensics {
     lastReadVersion = new Map();
     fileReadSessions = new Map();
     pendingReads = new Map();
+    latestContextObservation = null;
+    contextObservationSeq = 0;
     hourHistogram = new Array(24).fill(0);
     weekdayCounts = new Map();
     lateNightSessions = new Map();
@@ -182,7 +264,7 @@ class Forensics {
         const key = model || "unknown";
         let m = this.models.get(key);
         if (!m) {
-            m = { messages: 0, cold: 0, cacheWrite: 0, cacheRead: 0, output: 0 };
+            m = { messages: 0, cold: 0, cacheWrite: 0, cacheRead: 0, output: 0, cost: emptyCostAccumulator() };
             this.models.set(key, m);
         }
         return m;
@@ -191,7 +273,7 @@ class Forensics {
         const name = repoLabel(cwd);
         let r = this.repos.get(name);
         if (!r) {
-            r = { name, cwd: null, sessions: new Set(), assistantMessages: 0, cold: 0, cacheWrite: 0, cacheRead: 0, output: 0, codexTokens: 0, claudeTokens: 0, reads: 0, rereads: 0, staleRereads: 0, userTimestamps: [], byDay: new Map() };
+            r = { name, cwd: null, sessions: new Set(), assistantMessages: 0, cold: 0, cacheWrite: 0, cacheRead: 0, output: 0, cost: emptyCostAccumulator(), codexTokens: 0, claudeTokens: 0, reads: 0, rereads: 0, staleRereads: 0, userTimestamps: [], byDay: new Map() };
             this.repos.set(name, r);
         }
         if (cwd && !r.cwd)
@@ -224,37 +306,66 @@ class Forensics {
     /** assistant-turn token usage (already split into cold/cacheWrite/cacheRead/output). */
     recordUsage(model, cwd, session, u, provider, ms) {
         const m = this.modelBucket(model);
+        const estimatedCost = estimateApiEquivalentCost(model, u, ms);
         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;
-            // per-repo provider split → drives the city's per-cube colour (Codex green / Claude orange)
-            const turnTokens = u.cold + u.cacheWrite + u.cacheRead + u.output;
-            if (provider === "codex")
-                r.codexTokens += turnTokens;
-            else
-                r.claudeTokens += turnTokens;
-            if (ms != null && turnTokens > 0) {
-                const d = localDay(ms);
-                r.byDay.set(d, (r.byDay.get(d) || 0) + turnTokens);
-            }
+        addEstimatedCost(m.cost, estimatedCost);
+        // Keep usage with missing legacy cwd metadata in an explicit "home" bucket. Silently omitting it
+        // makes repo/day timelines fail to reconcile with the provider ledger even though scale includes it.
+        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;
+        addEstimatedCost(r.cost, estimatedCost);
+        // per-repo provider split → drives the city's per-cube colour (Codex green / Claude orange)
+        const turnTokens = u.cold + u.cacheWrite + u.cacheRead + u.output;
+        if (provider === "codex")
+            r.codexTokens += turnTokens;
+        else
+            r.claudeTokens += turnTokens;
+        if (ms != null && turnTokens > 0) {
+            const d = localDay(ms);
+            r.byDay.set(d, (r.byDay.get(d) || 0) + turnTokens);
+        }
+    }
+    recordContextObservation(input) {
+        const inputTokens = Math.max(0, Math.round(input.inputTokens || 0));
+        if (inputTokens <= 0)
+            return;
+        const resolvedLimit = resolveModelContextLimit({
+            loggedLimitTokens: input.modelContextLimitTokens ?? null,
+            model: input.model,
+        });
+        const observation = {
+            seq: ++this.contextObservationSeq,
+            model: input.model || "unknown",
+            inputTokens,
+            outputTokens: Math.max(0, Math.round(input.outputTokens || 0)),
+            modelContextLimitTokens: resolvedLimit.tokens,
+            modelContextLimitSource: resolvedLimit.source,
+            ms: input.ms ?? null,
+        };
+        const current = this.latestContextObservation;
+        if (!current ||
+            (observation.ms != null && current.ms != null && observation.ms >= current.ms) ||
+            (observation.ms != null && current.ms == null) ||
+            (observation.ms == null && current.ms == null && observation.seq >= current.seq)) {
+            this.latestContextObservation = observation;
         }
     }
     recordEdit(target, cwd) {
         if (!target)
             return;
-        this.fileVersions.set(target, (this.fileVersions.get(target) || 0) + 1);
-        const rec = this.fileRecord(target, repoLabel(cwd));
+        const identity = fileIdentity(target, cwd);
+        this.fileVersions.set(identity, (this.fileVersions.get(identity) || 0) + 1);
+        const rec = this.fileRecord(identity, repoLabel(cwd));
         rec.everEdited = true;
         rec.editCount += 1;
     }
@@ -263,13 +374,14 @@ class Forensics {
         if (!target)
             return;
         const repo = repoLabel(cwd);
-        const rec = this.fileRecord(target, repo);
+        const identity = fileIdentity(target, cwd);
+        const rec = this.fileRecord(identity, repo);
         const priorReads = rec.totalReads;
-        const currentVersion = this.fileVersions.get(target) || 0;
-        const seenSessions = this.fileReadSessions.get(target) || new Set();
+        const currentVersion = this.fileVersions.get(identity) || 0;
+        const seenSessions = this.fileReadSessions.get(identity) || new Set();
         const isReread = priorReads > 0;
         const crossSession = isReread && !!session && !seenSessions.has(session);
-        const changedSinceLastRead = isReread && currentVersion > (this.lastReadVersion.get(target) || 0);
+        const changedSinceLastRead = isReread && currentVersion > (this.lastReadVersion.get(identity) || 0);
         const stale = isReread && !changedSinceLastRead;
         rec.totalReads += 1;
         if (cwd)
@@ -302,11 +414,11 @@ class Forensics {
             if (!this.nightExample || priorReads > this.nightExample.priorReads)
                 this.nightExample = candidate;
         }
-        if (!this.fileReadSessions.has(target))
-            this.fileReadSessions.set(target, new Set());
+        if (!this.fileReadSessions.has(identity))
+            this.fileReadSessions.set(identity, new Set());
         if (session)
-            this.fileReadSessions.get(target).add(session);
-        this.lastReadVersion.set(target, currentVersion);
+            this.fileReadSessions.get(identity).add(session);
+        this.lastReadVersion.set(identity, currentVersion);
         if (toolId)
             this.pendingReads.set(toolId, { rec, stale });
     }
@@ -362,30 +474,38 @@ class Forensics {
         // ----- tokens + cost -----
         let cold = 0, cacheWrite = 0, cacheRead = 0, output = 0;
         const modelOut = {};
+        const accumulatedCost = emptyCostAccumulator();
         for (const [name, m] of this.models) {
             cold += m.cold;
             cacheWrite += m.cacheWrite;
             cacheRead += m.cacheRead;
             output += m.output;
+            addAccumulatedCost(accumulatedCost, m.cost);
             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),
+                total: m.cold + m.cacheWrite + m.cacheRead + m.output,
+                coldInputCost: round(m.cost.coldInputCost, 2),
+                cacheWriteCost: round(m.cost.cacheWriteCost, 2),
+                cacheReadCost: round(m.cost.cacheReadCost, 2),
+                outputCost: round(m.cost.outputCost, 2),
+                cost: round(m.cost.total, 2),
+                longContextRequestCount: m.cost.longContextRequestCount,
             };
         }
         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,
+            coldInputCost: round(accumulatedCost.coldInputCost, 2),
+            cacheWriteCost: round(accumulatedCost.cacheWriteCost, 2),
+            cacheReadCost: round(accumulatedCost.cacheReadCost, 2),
+            outputCost: round(accumulatedCost.outputCost, 2),
+            total: round(accumulatedCost.total, 2),
+            longContextRequestCount: accumulatedCost.longContextRequestCount,
+            pricingBasis: "standard-api-list-price",
+            pricingAsOf: "2026-07-12",
         };
-        // 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;
@@ -413,7 +533,7 @@ class Forensics {
                 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),
+                cost: round(repo.cost.total, 2),
                 reads: repo.reads, rereads: repo.rereads, staleRereads: repo.staleRereads,
                 dominantProvider: repo.codexTokens >= repo.claudeTokens ? "codex" : "claude",
                 codexTokens: repo.codexTokens, claudeTokens: repo.claudeTokens,
@@ -475,7 +595,9 @@ class Forensics {
         const scanEnd = this.maxTs ?? Date.now();
         const cfDate = scanEnd - daysAgo * 86_400_000;
         return {
-            generatedFrom: ["~/.codex/sessions", "~/.claude/projects"],
+            schemaVersion: 1,
+            dataOrigin: "local-workspace-scan",
+            generatedFrom: [],
             llmCallsUsed: 0,
             transcriptsUploaded: false,
             scanStartDate: this.minTs != null ? localDay(this.minTs) : null,
@@ -510,44 +632,159 @@ class Forensics {
                 crossSessionStaleReads: codeCrossStale, totalReadTokens: codeReadTokens, staleReadTokens: codeStaleReadTokens,
                 staleReadSharePct: Math.round(staleShare * 100),
             },
+            contextWindow: this.buildContextWindowSummary(topModel, staleShare),
             rereadForensics: { topFiles, neverChangedHeavy, principleReads, nightExample: this.nightExample },
-            avoidableWait: { readTokens: codeStaleReadTokens, hours: avoidableWaitHours, days: avoidableWaitDays, cost: round(costOf({ cold: codeStaleReadTokens }, CLAUDE_DEFAULT), 2) },
+            avoidableWait: {
+                readTokens: codeStaleReadTokens,
+                hours: avoidableWaitHours,
+                days: avoidableWaitDays,
+                cost: round(estimateApiEquivalentCost(topModel, { cold: codeStaleReadTokens }, this.maxTs).total, 2),
+            },
             counterfactual: { daysAgo, counterfactualDate: localDay(cfDate), daysGained: avoidableWaitDays, targetScore: Math.min(100, cleanlinessScore + 30) },
         };
     }
+    buildContextWindowSummary(topModel, staleShare) {
+        const latest = this.latestContextObservation;
+        const latestInputTokens = latest?.inputTokens ?? 0;
+        const currentResidentWasteTokens = Math.round(latestInputTokens * Math.max(0, staleShare));
+        return {
+            source: latest ? "latest-observed-input" : "unavailable",
+            model: latest?.model || topModel || "unknown",
+            modelContextLimitSource: latest?.modelContextLimitSource || "unavailable",
+            sampleCount: this.contextObservationSeq,
+            staleReadSharePct: Math.round(staleShare * 100),
+            metrics: calculateContextMetrics({
+                latestInputTokens,
+                modelContextLimitTokens: latest?.modelContextLimitTokens ?? null,
+                currentResidentWasteTokens,
+                newOutputThisTurnTokens: latest?.outputTokens,
+            }),
+        };
+    }
 }
 // ---------------------------------------------------------------------------
 // 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) {
+function sessionTitleFromText(text) {
+    const normalized = text.replace(/<[^>]+>/g, " ").replace(/\s+/g, " ").trim();
+    if (!normalized)
+        return null;
+    const sentence = normalized.split(/(?<=[.!?。！？])\s/)[0] || normalized;
+    return sentence.slice(0, 96);
+}
+/** Parse one Claude Code transcript without mutating global state. Replaying every provider on one
+ * timestamp-ordered timeline prevents a later-scanned file/source from contaminating reread order. */
+function extractClaude(file) {
+    const usageByRequest = new Map();
+    const seenToolUses = new Set();
+    const context = [];
+    const ev = [];
+    let cwd = null;
+    let session = null;
+    let firstTs = null;
+    let lastTs = null;
+    let fallbackTitle = null;
+    let anonymousRequestSeq = 0;
+    const requestKey = (row) => {
+        const messageId = typeof row.message?.id === "string" ? row.message.id.trim() : "";
+        if (messageId)
+            return `message:${messageId}`;
+        const requestId = typeof row.requestId === "string" ? row.requestId.trim() : "";
+        if (requestId)
+            return `request:${requestId}`;
+        const uuid = typeof row.uuid === "string" ? row.uuid.trim() : "";
+        if (uuid)
+            return `event:${uuid}`;
+        // Without a provider identifier it is unsafe to assume two rows are the same request.
+        return `anonymous:${++anonymousRequestSeq}`;
+    };
+    const usageNumber = (value) => (typeof value === "number" && Number.isFinite(value) ? Math.max(0, value) : 0);
+    const toolUseKey = (request, block, index) => {
+        const id = typeof block?.id === "string" ? block.id.trim() : "";
+        if (id)
+            return `id:${id}`;
+        let input = "";
+        try {
+            input = JSON.stringify(block?.input ?? null);
+        }
+        catch {
+            input = "[unserializable]";
+        }
+        // Claude tool_use blocks normally have an id. The positional fingerprint is a conservative
+        // fallback that deduplicates repeated snapshots without collapsing two calls in one request.
+        return `fallback:${request}:${index}:${String(block?.name || "")}:${input}`;
+    };
     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 (Number.isFinite(ts)) {
+            if (firstTs == null || ts < firstTs)
+                firstTs = ts;
+            if (lastTs == null || ts > lastTs)
+                lastTs = ts;
+        }
+        if (!session && typeof o.sessionId === "string")
+            session = o.sessionId;
+        if (!cwd && typeof o.cwd === "string")
+            cwd = o.cwd;
         if (o.type === "assistant" && o.message) {
+            const key = requestKey(o);
             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,
-            }, "claude", Number.isFinite(ts) ? ts : undefined);
+            const model = typeof o.message.model === "string" && o.message.model ? o.message.model : "unknown";
+            const existing = usageByRequest.get(key);
+            const merged = existing || {
+                model,
+                cwd,
+                session,
+                ms: Number.isFinite(ts) ? ts : null,
+                cold: 0,
+                cacheWrite: 0,
+                cacheRead: 0,
+                output: 0,
+            };
+            const candidateCold = usageNumber(u.input_tokens);
+            const candidateCacheWrite = usageNumber(u.cache_creation_input_tokens);
+            const candidateCacheRead = usageNumber(u.cache_read_input_tokens);
+            const candidateInput = candidateCold + candidateCacheWrite + candidateCacheRead;
+            const mergedInput = merged.cold + merged.cacheWrite + merged.cacheRead;
+            if (candidateInput > mergedInput) {
+                // Keep the three input components from one provider snapshot. Taking their independent
+                // maxima can synthesize an official-input total that never appeared in the transcript.
+                merged.cold = candidateCold;
+                merged.cacheWrite = candidateCacheWrite;
+                merged.cacheRead = candidateCacheRead;
+            }
+            merged.output = Math.max(merged.output, usageNumber(u.output_tokens));
+            if (merged.model === "unknown" && model !== "unknown")
+                merged.model = model;
+            if (!merged.cwd && cwd)
+                merged.cwd = cwd;
+            if (!merged.session && session)
+                merged.session = session;
+            if (Number.isFinite(ts) && (merged.ms == null || ts >= merged.ms))
+                merged.ms = ts;
+            usageByRequest.set(key, merged);
             const blocks = Array.isArray(o.message.content) ? o.message.content : [];
-            for (const b of blocks) {
+            for (let index = 0; index < blocks.length; index += 1) {
+                const b = blocks[index];
                 if (b?.type !== "tool_use")
                     continue;
                 const name = String(b.name || "");
+                const toolKey = toolUseKey(key, b, index);
+                if (seenToolUses.has(toolKey))
+                    continue;
                 if (name === "Edit" || name === "Write" || name === "MultiEdit") {
                     const target = b.input?.file_path || b.input?.path;
-                    if (target)
-                        eng.recordEdit(target, cwd);
+                    if (target) {
+                        ev.push({ t: "e", path: target, ms: Number.isFinite(ts) ? ts : null });
+                        seenToolUses.add(toolKey);
+                    }
                 }
                 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);
+                    if (target) {
+                        ev.push({ t: "r", path: target, ms: Number.isFinite(ts) ? ts : null, id: b.id || null });
+                        seenToolUses.add(toolKey);
+                    }
                 }
             }
             return;
@@ -555,17 +792,41 @@ function feedClaude(file, eng) {
         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);
+                if (isRealUserText(content) && Number.isFinite(ts) && !o.isSidechain) {
+                    ev.push({ t: "m", ms: ts });
+                    if (!fallbackTitle)
+                        fallbackTitle = sessionTitleFromText(content);
+                }
             }
             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));
+                    if (b?.type === "tool_result" && b.tool_use_id) {
+                        ev.push({ t: "o", id: b.tool_use_id, chars: contentLength(b.content), ms: Number.isFinite(ts) ? ts : null });
+                    }
                 }
             }
         }
     });
+    const usage = [];
+    // Claude can persist several snapshots of the same provider message. Account official usage once,
+    // retaining the one input tuple with the largest official total.
+    for (const request of usageByRequest.values()) {
+        usage.push({
+            model: request.model,
+            cold: request.cold,
+            cacheWrite: request.cacheWrite,
+            cacheRead: request.cacheRead,
+            output: request.output,
+            ms: request.ms,
+        });
+        context.push({
+            model: request.model,
+            inputTokens: request.cold + request.cacheWrite + request.cacheRead,
+            outputTokens: request.output,
+            ms: request.ms,
+        });
+    }
+    return { source: "claude-code", session, cwd, firstTs, lastTs, fallbackTitle, usage, context, ev };
 }
 /** 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). */
@@ -578,14 +839,17 @@ function extractCodex(file) {
     let prev = { cold: 0, cacheRead: 0, output: 0 }; // last cumulative seen (for deltas)
     let firstTs = null;
     let lastTs = null;
-    const usageByModel = new Map();
+    let fallbackTitle = null;
+    const usage = [];
+    const context = [];
     const ev = [];
     eachLine(file, (o) => {
         const ts = typeof o.timestamp === "string" ? Date.parse(o.timestamp) : NaN;
         if (Number.isFinite(ts)) {
-            if (firstTs == null)
+            if (firstTs == null || ts < firstTs)
                 firstTs = ts;
-            lastTs = ts;
+            if (lastTs == null || ts > lastTs)
+                lastTs = ts;
         }
         const p = o && typeof o.payload === "object" && o.payload ? o.payload : o;
         if (!p || typeof p !== "object")
@@ -595,6 +859,11 @@ function extractCodex(file) {
                 cwd = p.cwd;
             if (typeof p.id === "string" && !session)
                 session = p.id;
+            // Codex records the actual launch time in session metadata. It can precede the first persisted
+            // JSONL event by several seconds, so use it for the semantic start of the timeline when present.
+            const startedAt = typeof p.timestamp === "string" ? Date.parse(p.timestamp) : NaN;
+            if (Number.isFinite(startedAt) && (firstTs == null || startedAt < firstTs))
+                firstTs = startedAt;
             return;
         }
         if (typeof p.model === "string")
@@ -609,12 +878,25 @@ function extractCodex(file) {
                 const dCold = Math.max(0, cold - prev.cold);
                 const dCr = Math.max(0, cacheRead - prev.cacheRead);
                 const dOut = Math.max(0, out - prev.output);
+                const last = p.info?.last_token_usage || {};
+                const lastInput = last.input_tokens || inputTotal;
+                const lastOutput = (last.output_tokens || 0) + (last.reasoning_output_tokens || 0) || dOut;
+                context.push({
+                    model,
+                    inputTokens: lastInput,
+                    outputTokens: lastOutput,
+                    modelContextLimitTokens: p.info?.model_context_window || p.model_context_window || null,
+                    ms: Number.isFinite(ts) ? ts : null,
+                });
                 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);
+                    usage.push({
+                        model,
+                        cold: dCold,
+                        cacheWrite: 0,
+                        cacheRead: dCr,
+                        output: dOut,
+                        ms: Number.isFinite(ts) ? ts : null,
+                    });
                 }
                 prev = { cold, cacheRead, output: out };
             }
@@ -623,11 +905,16 @@ function extractCodex(file) {
         if (p.type === "user_message") {
             if (Number.isFinite(ts))
                 ev.push({ t: "m", ms: ts });
+            if (!fallbackTitle) {
+                const text = typeof p.message === "string" ? p.message : typeof p.content === "string" ? p.content : "";
+                if (text)
+                    fallbackTitle = sessionTitleFromText(text);
+            }
             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 });
+                ev.push({ t: "e", path: target, ms: Number.isFinite(ts) ? ts : null });
             return;
         }
         // older format: exec_command_end with parsed_cmd[].type==='read'
@@ -652,38 +939,54 @@ function extractCodex(file) {
             return;
         }
         if (p.type === "function_call_output" && p.call_id) {
-            ev.push({ t: "o", id: p.call_id, chars: contentLength(p.output) });
+            ev.push({ t: "o", id: p.call_id, chars: contentLength(p.output), ms: Number.isFinite(ts) ? ts : null });
         }
     });
-    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);
-    const provider = fe.source === "codex" ? "codex" : "claude";
-    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 }, provider, fe.firstTs ?? undefined);
-    for (const e of fe.ev) {
+    return { source: "codex", session, cwd, firstTs, lastTs, fallbackTitle, usage, context, ev };
+}
+/** Replay every provider on one semantic timeline. Provider timestamps, not source/path order, drive
+ * daily token buckets and order-dependent edit/reread state across overlapping sessions. */
+function replayTimelineFiles(eng, files) {
+    const orderedEvents = [];
+    const orderedUsage = [];
+    files.forEach(({ fe }, fileOrder) => {
+        if (fe.firstTs != null)
+            eng.noteTs(fe.firstTs);
+        if (fe.lastTs != null)
+            eng.noteTs(fe.lastTs);
+        eng.noteSession(fe.session);
+        (fe.usage || []).forEach((u, usageOrder) => orderedUsage.push({ fe, u, fileOrder, usageOrder }));
+        for (const c of fe.context || [])
+            eng.recordContextObservation(c);
+        (fe.ev || []).forEach((e, eventOrder) => orderedEvents.push({ fe, e, fileOrder, eventOrder }));
+    });
+    orderedUsage.sort((a, b) => (a.u.ms ?? a.fe.firstTs ?? Number.POSITIVE_INFINITY) - (b.u.ms ?? b.fe.firstTs ?? Number.POSITIVE_INFINITY) ||
+        a.fileOrder - b.fileOrder ||
+        a.usageOrder - b.usageOrder);
+    for (const { fe, u } of orderedUsage) {
+        const provider = fe.source === "codex" ? "codex" : "claude";
+        eng.recordUsage(u.model, fe.cwd, fe.session, { cold: u.cold, cacheWrite: u.cacheWrite, cacheRead: u.cacheRead, output: u.output }, provider, u.ms ?? undefined);
+    }
+    const eventMs = (item) => item.e.ms ?? item.fe.firstTs ?? Number.POSITIVE_INFINITY;
+    orderedEvents.sort((a, b) => eventMs(a) - eventMs(b) ||
+        a.fileOrder - b.fileOrder ||
+        a.eventOrder - b.eventOrder);
+    for (const { fe, e } of orderedEvents) {
+        const callId = (id) => id ? `${fe.source}:${fe.session || "unknown"}:${id}` : null;
         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);
+            eng.recordRead(e.path, fe.cwd, fe.session, e.ms, callId(e.id));
         else if (e.t === "o")
-            eng.recordReadOutput(e.id, e.chars);
+            eng.recordReadOutput(callId(e.id) || 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;
+const CACHE_VERSION = 6;
 function forensicCachePath() {
     return path.join(os.homedir(), ".echomem", "forensic-cache.json");
 }
@@ -708,51 +1011,479 @@ function saveForensicCache(files) {
         /* best effort: a cache write failure must never break the scan */
     }
 }
+function loadCodexSessionTitles() {
+    const titles = new Map();
+    try {
+        const indexPath = path.join(os.homedir(), ".codex", "session_index.jsonl");
+        for (const line of fs.readFileSync(indexPath, "utf8").split("\n")) {
+            if (!line.trim())
+                continue;
+            try {
+                const row = JSON.parse(line);
+                if (typeof row.id === "string" && typeof row.thread_name === "string" && row.thread_name.trim()) {
+                    titles.set(row.id, row.thread_name.trim());
+                }
+            }
+            catch {
+                /* Ignore incomplete index rows. */
+            }
+        }
+    }
+    catch {
+        /* Index is optional; transcript-derived titles remain available. */
+    }
+    return titles;
+}
+function loadClaudeSessionTitles() {
+    const titles = new Map();
+    const roots = [
+        path.join(os.homedir(), "Library", "Application Support", "Claude", "claude-code-sessions"),
+        path.join(os.homedir(), "Library", "Application Support", "Claude", "local-agent-mode-sessions"),
+    ];
+    for (const root of roots) {
+        const files = walk(root, (p) => /^local_[0-9a-f-]+\.json$/i.test(path.basename(p)), () => false);
+        for (const file of files) {
+            try {
+                const row = JSON.parse(fs.readFileSync(file, "utf8"));
+                if (typeof row.cliSessionId === "string" && typeof row.title === "string" && row.title.trim()) {
+                    titles.set(row.cliSessionId, row.title.trim());
+                }
+            }
+            catch {
+                /* Ignore incomplete live metadata. */
+            }
+        }
+    }
+    return titles;
+}
+function enrichCanonicalSessionExamples(canonical, timelineFiles) {
+    if (!canonical || "error" in canonical)
+        return;
+    const codexTitles = loadCodexSessionTitles();
+    const claudeTitles = loadClaudeSessionTitles();
+    const records = timelineFiles
+        .filter(({ fe }) => Boolean(fe.session))
+        .sort((a, b) => (a.fe.firstTs ?? Number.POSITIVE_INFINITY) - (b.fe.firstTs ?? Number.POSITIVE_INFINITY));
+    const sourceTotals = {
+        codex: records.filter(({ fe }) => fe.source === "codex").length,
+        "claude-code": records.filter(({ fe }) => fe.source === "claude-code").length,
+    };
+    const sourceOrdinals = { codex: 0, "claude-code": 0 };
+    const sessionMeta = new Map();
+    for (const { fe } of records) {
+        if (!fe.session)
+            continue;
+        sourceOrdinals[fe.source] += 1;
+        const indexedTitle = fe.source === "codex" ? codexTitles.get(fe.session) : claudeTitles.get(fe.session);
+        sessionMeta.set(fe.session, {
+            id: fe.session,
+            title: indexedTitle || fe.fallbackTitle || `${fe.cwd ? path.basename(fe.cwd) : "Local"} session`,
+            ordinal: sourceOrdinals[fe.source],
+            total: sourceTotals[fe.source],
+        });
+    }
+    const reports = [canonical];
+    if (canonical.sourceReports?.codex)
+        reports.push(canonical.sourceReports.codex);
+    if (canonical.sourceReports?.claudeCode)
+        reports.push(canonical.sourceReports.claudeCode);
+    for (const contextReport of reports) {
+        for (const problem of contextReport.problems || []) {
+            for (const example of problem.examples || []) {
+                const exact = sessionMeta.get(example.session);
+                const matched = exact || [...sessionMeta.entries()].find(([id]) => id.startsWith(example.session))?.[1];
+                if (!matched)
+                    continue;
+                example.session = matched.id;
+                example.sessionTitle = matched.title;
+                example.sessionOrdinal = matched.ordinal;
+                example.sourceSessionCount = matched.total;
+            }
+        }
+    }
+}
+export function projectCanonicalWasteToBilledInput(billedInputTokens, summary) {
+    if (!Number.isFinite(billedInputTokens) ||
+        !Number.isFinite(summary.officialInputTokens) ||
+        !Number.isFinite(summary.wasteTokens))
+        return null;
+    const billedInput = Math.round(billedInputTokens);
+    const canonicalInput = Math.round(summary.officialInputTokens);
+    const canonicalWaste = Math.round(summary.wasteTokens);
+    // With aligned source scope, all provider requests must contain at least as many input tokens as
+    // one selected request per human turn. Refuse to manufacture a projection from inverted ledgers.
+    if (billedInput <= 0 ||
+        canonicalInput <= 0 ||
+        canonicalWaste < 0 ||
+        canonicalWaste > canonicalInput ||
+        billedInput < canonicalInput)
+        return null;
+    const billingMultiplier = billedInput / canonicalInput;
+    const projectedWaste = Math.max(0, Math.min(billedInput, Math.round(canonicalWaste * billingMultiplier)));
+    const wastePct = (canonicalWaste / canonicalInput) * 100;
+    return {
+        method: "canonical-window-share-over-provider-input",
+        billedInputTokens: billedInput,
+        canonicalInputTokens: canonicalInput,
+        canonicalUsefulTokens: canonicalInput - canonicalWaste,
+        canonicalWasteTokens: canonicalWaste,
+        billingMultiplier,
+        projectedUsefulTokens: billedInput - projectedWaste,
+        projectedWasteTokens: projectedWaste,
+        usefulPct: 100 - wastePct,
+        wastePct,
+    };
+}
+function recordValue(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : null;
+}
+function nonNegativeInteger(value) {
+    return typeof value === "number" && Number.isFinite(value) && Number.isInteger(value) && value >= 0
+        ? value
+        : null;
+}
+function nonNegativeNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : null;
+}
+function approximatelyEqual(actual, expected, relativeTolerance = 1e-9) {
+    return typeof actual === "number" &&
+        Number.isFinite(actual) &&
+        Math.abs(actual - expected) <= Math.max(1, Math.abs(expected)) * relativeTolerance;
+}
+function invalidSetupReport(code, message) {
+    return { ok: false, code, message };
+}
+/**
+ * Fail-closed boundary between the local scanner and setup UI.
+ *
+ * The setup page must never infer that a fixture, partial scan, or internally inconsistent token
+ * ledger is the user's report. This validator checks the provenance and the cross-ledger identities
+ * the UI relies on before any absolute token number is rendered.
+ */
+export function validateForensicReportForSetup(value) {
+    const report = recordValue(value);
+    if (!report)
+        return invalidSetupReport("REPORT_MALFORMED", "The local report payload is not an object.");
+    if (report.schemaVersion !== 1) {
+        return invalidSetupReport("REPORT_SCHEMA_UNSUPPORTED", "The local report schema is missing or unsupported.");
+    }
+    if (report.dataOrigin !== "local-workspace-scan") {
+        return invalidSetupReport("REPORT_NOT_LOCAL", "The report did not come from this local workspace scan.");
+    }
+    const scale = recordValue(report.scale);
+    const canonical = recordValue(report.canonicalGoldenStandard);
+    const requiredObjects = [
+        report.cost,
+        report.modelUsage,
+        report.userWorkingHours,
+        report.rhythm,
+        report.cleanliness,
+        report.contextWindow,
+        report.rereadForensics,
+        report.avoidableWait,
+        report.counterfactual,
+    ];
+    if (!scale ||
+        !canonical ||
+        !Array.isArray(report.generatedFrom) ||
+        !Array.isArray(report.repos) ||
+        requiredObjects.some((entry) => !recordValue(entry)) ||
+        typeof report.llmCallsUsed !== "number" ||
+        !Number.isFinite(report.llmCallsUsed) ||
+        typeof report.transcriptsUploaded !== "boolean" ||
+        !(report.scanStartDate === null || typeof report.scanStartDate === "string") ||
+        !(report.scanEndDate === null || typeof report.scanEndDate === "string")) {
+        return invalidSetupReport("REPORT_MALFORMED", "The local report is missing required setup fields.");
+    }
+    if (Object.prototype.hasOwnProperty.call(canonical, "error")) {
+        return invalidSetupReport("REPORT_CANONICAL_FAILED", "Canonical context analysis did not complete.");
+    }
+    const summary = recordValue(canonical.summary);
+    if (!summary)
+        return invalidSetupReport("REPORT_MALFORMED", "Canonical context summary is missing.");
+    const sessionCount = nonNegativeInteger(scale.sessionCount);
+    const canonicalSessionCount = nonNegativeInteger(summary.sessionsAnalyzed);
+    const billedInput = nonNegativeInteger(scale.totalInputTokens);
+    const totalTokens = nonNegativeInteger(scale.totalTokens);
+    const coldInput = nonNegativeInteger(scale.coldInputTokens);
+    const cacheWrite = nonNegativeInteger(scale.cacheWriteTokens);
+    const cacheRead = nonNegativeInteger(scale.cacheReadTokens);
+    const output = nonNegativeInteger(scale.outputTokens);
+    const canonicalInput = nonNegativeInteger(summary.officialInputTokens);
+    const canonicalUseful = nonNegativeInteger(summary.usefulTokens);
+    const canonicalWaste = nonNegativeInteger(summary.wasteTokens);
+    if (sessionCount === null ||
+        canonicalSessionCount === null ||
+        billedInput === null ||
+        totalTokens === null ||
+        coldInput === null ||
+        cacheWrite === null ||
+        cacheRead === null ||
+        output === null ||
+        canonicalInput === null ||
+        canonicalUseful === null ||
+        canonicalWaste === null) {
+        return invalidSetupReport("REPORT_USAGE_INVALID", "The report contains invalid token or session totals.");
+    }
+    if (coldInput + cacheWrite + cacheRead !== billedInput || billedInput + output !== totalTokens) {
+        return invalidSetupReport("REPORT_USAGE_INVALID", "Provider token totals do not reconcile.");
+    }
+    const reportCost = recordValue(report.cost);
+    const costByModel = reportCost ? recordValue(reportCost.byModel) : null;
+    const coldInputCost = reportCost ? nonNegativeNumber(reportCost.coldInputCost) : null;
+    const cacheWriteCost = reportCost ? nonNegativeNumber(reportCost.cacheWriteCost) : null;
+    const cacheReadCost = reportCost ? nonNegativeNumber(reportCost.cacheReadCost) : null;
+    const outputCost = reportCost ? nonNegativeNumber(reportCost.outputCost) : null;
+    const totalCost = reportCost ? nonNegativeNumber(reportCost.total) : null;
+    if (!reportCost || !costByModel || coldInputCost === null || cacheWriteCost === null ||
+        cacheReadCost === null || outputCost === null || totalCost === null) {
+        return invalidSetupReport("REPORT_COST_INVALID", "The API-equivalent cost ledger is missing or malformed.");
+    }
+    const componentCost = coldInputCost + cacheWriteCost + cacheReadCost + outputCost;
+    if (Math.abs(componentCost - totalCost) > 0.05) {
+        return invalidSetupReport("REPORT_COST_INVALID", "Cost components do not reconcile with total spend.");
+    }
+    const modelCosts = Object.values(costByModel).map((value) => {
+        const model = recordValue(value);
+        return model ? nonNegativeNumber(model.cost) : null;
+    });
+    if (modelCosts.some((value) => value === null)) {
+        return invalidSetupReport("REPORT_COST_INVALID", "A model cost entry is malformed.");
+    }
+    const modelCostSum = modelCosts.reduce((sum, value) => sum + (value ?? 0), 0);
+    if (Math.abs(modelCostSum - totalCost) > Math.max(0.05, modelCosts.length * 0.011)) {
+        return invalidSetupReport("REPORT_COST_INVALID", "Per-model costs do not reconcile with total spend.");
+    }
+    const repoCosts = report.repos.map((value) => {
+        const repo = recordValue(value);
+        return repo ? nonNegativeNumber(repo.cost) : null;
+    });
+    if (repoCosts.some((value) => value === null)) {
+        return invalidSetupReport("REPORT_COST_INVALID", "A workspace cost entry is malformed.");
+    }
+    const repoCostSum = repoCosts.reduce((sum, value) => sum + (value ?? 0), 0);
+    if (Math.abs(repoCostSum - totalCost) > Math.max(0.05, repoCosts.length * 0.011)) {
+        return invalidSetupReport("REPORT_COST_INVALID", "Per-workspace costs do not reconcile with total spend.");
+    }
+    const diagnostics = canonical.diagnostics === undefined ? null : recordValue(canonical.diagnostics);
+    if (canonical.diagnostics !== undefined && !diagnostics) {
+        return invalidSetupReport("REPORT_MALFORMED", "Canonical scan diagnostics are malformed.");
+    }
+    if (diagnostics) {
+        const skippedSessions = nonNegativeInteger(diagnostics.skippedSessions);
+        const errors = diagnostics.errors;
+        if (skippedSessions === null || !Array.isArray(errors)) {
+            return invalidSetupReport("REPORT_MALFORMED", "Canonical scan diagnostics are malformed.");
+        }
+        if (skippedSessions > 0 || errors.length > 0) {
+            return invalidSetupReport("REPORT_PARTIAL", "Some local sessions could not be analyzed; no partial report was shown.");
+        }
+    }
+    if (sessionCount !== canonicalSessionCount) {
+        return invalidSetupReport("REPORT_COHORT_MISMATCH", "Provider and canonical ledgers cover different session cohorts.");
+    }
+    if (canonicalUseful + canonicalWaste !== canonicalInput) {
+        return invalidSetupReport("REPORT_CANONICAL_INVALID", "Canonical useful and waste totals do not reconcile.");
+    }
+    const canonicalWastePct = canonicalInput > 0 ? (canonicalWaste / canonicalInput) * 100 : 0;
+    const canonicalUsefulPct = canonicalInput > 0 ? (canonicalUseful / canonicalInput) * 100 : 0;
+    if (!approximatelyEqual(summary.wastePct, canonicalWastePct) ||
+        !approximatelyEqual(summary.usefulPct, canonicalUsefulPct)) {
+        return invalidSetupReport("REPORT_CANONICAL_INVALID", "Canonical token percentages do not reconcile with their totals.");
+    }
+    if (sessionCount === 0) {
+        if (totalTokens !== 0 ||
+            billedInput !== 0 ||
+            coldInput !== 0 ||
+            cacheWrite !== 0 ||
+            cacheRead !== 0 ||
+            output !== 0 ||
+            canonicalInput !== 0 ||
+            canonicalUseful !== 0 ||
+            canonicalWaste !== 0) {
+            return invalidSetupReport("REPORT_EMPTY_USAGE_MISMATCH", "An empty scan contains unexpected token usage.");
+        }
+        if (report.billedWasteProjection !== undefined) {
+            return invalidSetupReport("REPORT_PROJECTION_INVALID", "An empty scan must not contain a billed waste projection.");
+        }
+        return { ok: true, kind: "empty", report: report };
+    }
+    const hasRenderableRepo = report.repos.some((value) => {
+        const repo = recordValue(value);
+        return !!repo && typeof repo.name === "string" && repo.name.trim().length > 0 &&
+            nonNegativeInteger(repo.tokens) !== null && Number(repo.tokens) > 0;
+    });
+    if (!hasRenderableRepo) {
+        return invalidSetupReport("REPORT_REPOS_EMPTY", "A non-empty scan has no tokenized local workspace to render.");
+    }
+    if (billedInput <= 0 || canonicalInput <= 0) {
+        return invalidSetupReport("REPORT_USAGE_INVALID", "A non-empty scan must contain positive provider and canonical input totals.");
+    }
+    if (canonicalInput > billedInput) {
+        return invalidSetupReport("REPORT_LEDGER_INVERTED", "Canonical input exceeds provider-billed input for the same sessions.");
+    }
+    const expectedProjection = projectCanonicalWasteToBilledInput(billedInput, {
+        officialInputTokens: canonicalInput,
+        wasteTokens: canonicalWaste,
+    });
+    const projection = recordValue(report.billedWasteProjection);
+    if (!expectedProjection || !projection) {
+        return invalidSetupReport("REPORT_PROJECTION_MISSING", "The billed waste projection is missing for a non-empty scan.");
+    }
+    if (projection.method !== expectedProjection.method ||
+        nonNegativeInteger(projection.billedInputTokens) !== expectedProjection.billedInputTokens ||
+        nonNegativeInteger(projection.canonicalInputTokens) !== expectedProjection.canonicalInputTokens ||
+        nonNegativeInteger(projection.canonicalUsefulTokens) !== expectedProjection.canonicalUsefulTokens ||
+        nonNegativeInteger(projection.canonicalWasteTokens) !== expectedProjection.canonicalWasteTokens ||
+        nonNegativeInteger(projection.projectedUsefulTokens) !== expectedProjection.projectedUsefulTokens ||
+        nonNegativeInteger(projection.projectedWasteTokens) !== expectedProjection.projectedWasteTokens ||
+        !approximatelyEqual(projection.billingMultiplier, expectedProjection.billingMultiplier) ||
+        !approximatelyEqual(projection.usefulPct, expectedProjection.usefulPct) ||
+        !approximatelyEqual(projection.wastePct, expectedProjection.wastePct)) {
+        return invalidSetupReport("REPORT_PROJECTION_INVALID", "The billed waste projection does not reconcile with its source ledgers.");
+    }
+    if (expectedProjection.projectedUsefulTokens + expectedProjection.projectedWasteTokens !== billedInput ||
+        !approximatelyEqual(expectedProjection.projectedWasteTokens / billedInput, canonicalWaste / canonicalInput, 1 / Math.max(1, billedInput))) {
+        return invalidSetupReport("REPORT_PROJECTION_INVALID", "The billed waste projection violates its token-share identity.");
+    }
+    return { ok: true, kind: "ready", report: report };
+}
 /** Scan both sources and build the merged forensic report. Local-only, $0, never throws on bad files. */
-export function buildForensicReport(opts) {
+export async 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 codexDiscovery = sources.includes("codex")
+        ? discoverCodexSessionFiles({ includeArchived: opts?.includeArchivedCodex !== false })
+        : null;
+    const claudeRoot = sources.includes("claude") ? resolveClaudeProjectsDir() : null;
+    // Discovery combines active + archived stores, de-duplicates by stable session identity, and orders
+    // sessions by semantic start time. Canonical human-turn analysis intentionally excludes subagents.
+    const reportCodexSessions = codexDiscovery?.files.filter((file) => file.userInitiated !== false) ?? [];
+    // Keep the canonical denominator on the same top-level-session population as the billed ledger.
+    // Legacy sessions without provenance are already admitted to reportCodexSessions; dropping them
+    // only here creates a small but real numerator/denominator scope mismatch.
+    const canonicalCodexFiles = reportCodexSessions.map((file) => file.path);
+    const codexFiles = reportCodexSessions.map((file) => file.path);
+    // Claude stores subagent/workflow implementation logs separately. They can share a parent
+    // session ID and must not be counted as additional user conversations.
+    const claudeFiles = claudeRoot
+        ? walk(claudeRoot, (p) => p.endsWith(".jsonl"), (name) => name === "subagents" || name === "workflows").sort()
         : [];
     const total = codexFiles.length + claudeFiles.length;
     let done = 0;
-    const tick = () => {
+    const progress = (stage, detail, progressDone = done, progressTotal = total) => {
+        opts?.onProgress?.(progressDone, progressTotal, stage, detail);
+    };
+    progress("reading-transcripts", "finding local Codex and Claude transcript files");
+    const tick = (stage = "reading-transcripts") => {
         done++;
         if (opts?.onProgress && (done % 8 === 0 || done === total))
-            opts.onProgress(done, total);
+            progress(stage);
     };
     // 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.
+    // changed/new sessions reparse; the cross-session state is rebuilt later on one provider timeline.
     const cache = loadForensicCache();
     const nextCache = {};
+    const parsedCodexFiles = [];
+    const discoveredCodexByPath = new Map(codexDiscovery?.files.map((file) => [file.path, file]) ?? []);
     for (const f of codexFiles) {
         let st;
         try {
             st = fs.statSync(f);
         }
         catch {
-            tick();
+            tick("reading-transcripts");
             continue;
         }
         const hit = cache[f];
         const fe = hit && hit.mtimeMs === st.mtimeMs && hit.size === st.size ? hit.fe : extractCodex(f);
+        const discovered = discoveredCodexByPath.get(f);
+        if (!fe.session && discovered)
+            fe.session = discovered.sessionKey;
         nextCache[f] = { mtimeMs: st.mtimeMs, size: st.size, fe };
-        replayFile(eng, fe);
-        tick();
+        parsedCodexFiles.push({ path: f, fe });
+        tick("reading-transcripts");
     }
     if (codexFiles.length)
         saveForensicCache(nextCache);
-    // Claude is fast (~0.6s) — scan live, no cache needed.
+    // Claude is fast (~0.6s) — parse live, then merge its events with Codex before replay.
+    const timelineFiles = [...parsedCodexFiles];
     for (const f of claudeFiles) {
-        feedClaude(f, eng);
-        tick();
+        timelineFiles.push({ path: f, fe: extractClaude(f) });
+        tick("reading-transcripts");
+    }
+    timelineFiles.sort((a, b) => (a.fe.firstTs ?? Number.POSITIVE_INFINITY) - (b.fe.firstTs ?? Number.POSITIVE_INFINITY) ||
+        a.path.localeCompare(b.path));
+    replayTimelineFiles(eng, timelineFiles);
+    progress("building-summary", "aggregating rereads, model usage, cost, and local context signals");
+    const report = eng.build();
+    const firstTimelineSession = timelineFiles.find(({ fe }) => fe.firstTs != null);
+    report.firstSession = firstTimelineSession ? {
+        date: firstTimelineSession.fe.firstTs != null ? new Date(firstTimelineSession.fe.firstTs).toISOString() : null,
+        source: firstTimelineSession.fe.source,
+        repo: firstTimelineSession.fe.cwd ? path.basename(firstTimelineSession.fe.cwd) : "workspace",
+    } : null;
+    const activeCodexCount = reportCodexSessions.filter((file) => file.rootKind === "active").length;
+    report.activeSessionCoverage = {
+        codex: activeCodexCount,
+        claudeCode: claudeFiles.length,
+        total: activeCodexCount + claudeFiles.length,
+    };
+    report.generatedFrom = [
+        ...(codexDiscovery?.roots.map((root) => root.kind === "active" ? "$CODEX_HOME/sessions" : "$CODEX_HOME/archived_sessions") ?? []),
+        ...(claudeRoot ? ["$CLAUDE_CONFIG_DIR/projects"] : []),
+    ];
+    if (codexDiscovery) {
+        report.sourceCoverage = {
+            codex: {
+                activeSessions: reportCodexSessions.filter((file) => file.rootKind === "active").length,
+                archivedSessions: reportCodexSessions.filter((file) => file.rootKind === "archived").length,
+                unclassifiedSessions: reportCodexSessions.filter((file) => file.userInitiated == null).length,
+                duplicateSessionsDiscarded: codexDiscovery.diagnostics.conflicts.length,
+                identityFallbacks: codexDiscovery.diagnostics.filenameIdentityFallbacks + codexDiscovery.diagnostics.pathIdentityFallbacks,
+                timelineBasis: "provider-event-timestamps",
+            },
+        };
+    }
+    if (opts?.includeLegacyGoldenStandard !== false) {
+        try {
+            report.goldenStandard = buildWorkspaceContextReport();
+        }
+        catch (error) {
+            report.goldenStandard = { error: error instanceof Error ? error.message : String(error) };
+        }
+    }
+    try {
+        const canonicalSources = [];
+        if (sources.includes("codex"))
+            canonicalSources.push("codex");
+        if (sources.includes("claude"))
+            canonicalSources.push("claude-code");
+        progress("classifying-repeated-context", "reconstructing context windows and attributing P01/P03/P08/P10/P13 waste");
+        report.canonicalGoldenStandard = await buildCanonicalGoldenReport({
+            sources: canonicalSources,
+            codexSessionPaths: canonicalCodexFiles,
+            claudeSessionPaths: claudeFiles,
+            // These paths were discovered from the user's local roots. One malformed/unsupported session
+            // must become a diagnostic, not erase the canonical report for every other valid session.
+            strictSessionErrors: false,
+            onProgress: (canonicalDone, canonicalTotal) => progress("classifying-repeated-context", "reconstructing context windows and attributing P01/P03/P08/P10/P13 waste", canonicalDone, canonicalTotal),
+        });
+        enrichCanonicalSessionExamples(report.canonicalGoldenStandard, timelineFiles);
+    }
+    catch (error) {
+        report.canonicalGoldenStandard = { error: error instanceof Error ? error.message : String(error) };
+    }
+    if (report.canonicalGoldenStandard &&
+        !("error" in report.canonicalGoldenStandard) &&
+        (report.canonicalGoldenStandard.diagnostics?.skippedSessions ?? 0) === 0 &&
+        report.scale.sessionCount === report.canonicalGoldenStandard.summary.sessionsAnalyzed) {
+        const projection = projectCanonicalWasteToBilledInput(Number(report.scale.totalInputTokens || 0), report.canonicalGoldenStandard.summary);
+        if (projection)
+            report.billedWasteProjection = projection;
     }
-    return eng.build();
+    progress("finalizing-report", "preparing setup page data", total, total);
+    return report;
 }