@ijfw/memory-server 1.3.0

package/src/cost/aggregator.js

@@ -0,0 +1,229 @@
+/**
+ * IJFW cost/aggregator.js
+ * Combines Claude, Codex, Gemini readers. Groups by day/platform/session/model.
+ * Returns { costs, savings, breakdowns, series } for dashboard endpoints.
+ * Never throws -- failed readers log and return empty.
+ */
+
+import { readClaudeSessions } from './readers/claude.js';
+import { readCodexSessions }  from './readers/codex.js';
+import { readGeminiSessions } from './readers/gemini.js';
+import { computeCost }        from './pricing.js';
+import { computeSavings, getSavingsMethodology } from './savings.js';
+
+const MS_PER_DAY = 86400000;
+
+/**
+ * Read all turns across all platforms, optionally filtered to recent N days.
+ */
+function readAllTurns(days) {
+  const readers = [
+    { fn: readClaudeSessions, label: 'claude' },
+    { fn: readCodexSessions,  label: 'codex'  },
+    { fn: readGeminiSessions, label: 'gemini' },
+  ];
+
+  const cutoff = days ? Date.now() - days * MS_PER_DAY : null;
+  let turns = [];
+
+  for (const { fn, label } of readers) {
+    try {
+      const raw = fn();
+      for (const t of raw) {
+        if (cutoff && t.timestamp) {
+          const ts = new Date(t.timestamp).getTime();
+          if (!isNaN(ts) && ts < cutoff) continue;
+        }
+        turns.push(t);
+      }
+    } catch (err) {
+      // reader failed -- log and continue
+      process.stderr.write(`[ijfw-cost] ${label} reader error: ${err.message}\n`);
+    }
+  }
+
+  return turns;
+}
+
+/**
+ * Annotate each turn with its USD cost and return enriched turns.
+ *
+ * `theoretical_cost_usd` is what equivalent paid-API usage would cost.
+ * `cost_usd` is what the user actually paid: 0 for Max-subscription Claude
+ * sessions, equal to theoretical_cost_usd for paid-API sessions and for
+ * other platforms.
+ */
+function annotateCosts(turns) {
+  return turns.map(t => {
+    const theoretical = computeCost(t.model, t);
+    const real = t.billing_mode === 'max' ? 0 : theoretical;
+    return { ...t, cost_usd: real, theoretical_cost_usd: theoretical };
+  });
+}
+
+/**
+ * Build the main cost + savings response.
+ * @param {number|null} days - rolling window in days (null = all-time)
+ * @param {Array} observations - observation records for savings context
+ */
+export function buildCostReport(days, observations = []) {
+  const raw   = readAllTurns(days);
+  const turns = annotateCosts(raw);
+  const savings = computeSavings(turns, observations);
+
+  // Split measured (real API data) vs estimated (Codex/Gemini char-heuristic)
+  const measuredTurns  = turns.filter(t => !t.estimated);
+  const estimatedTurns = turns.filter(t =>  t.estimated);
+
+  const measuredCost  = measuredTurns.reduce((s, t) => s + t.cost_usd, 0);
+  const estimatedCost = estimatedTurns.reduce((s, t) => s + t.cost_usd, 0);
+  const totalCost     = measuredCost + estimatedCost;
+
+  // Theoretical totals: what equivalent paid-API usage would cost.
+  // For Max sessions this is the value captured by the subscription.
+  const measuredTheoretical  = measuredTurns.reduce((s, t) => s + (t.theoretical_cost_usd || 0), 0);
+  const estimatedTheoretical = estimatedTurns.reduce((s, t) => s + (t.theoretical_cost_usd || 0), 0);
+  const theoreticalTotal     = measuredTheoretical + estimatedTheoretical;
+  const valueCaptured        = theoreticalTotal - totalCost;
+
+  // Token counts from measured turns only (estimated tokens are unreliable)
+  const totalIn        = measuredTurns.reduce((s, t) => s + (t.input_tokens || 0), 0);
+  const totalOut       = measuredTurns.reduce((s, t) => s + (t.output_tokens || 0), 0);
+  const totalCacheRead = measuredTurns.reduce((s, t) => s + (t.cache_read_tokens || 0), 0);
+
+  // Cache hit rate: cache_read / (input + cache_read), measured turns only
+  const denominator = totalIn + totalCacheRead;
+  const cacheHitRate = denominator > 0 ? totalCacheRead / denominator : 0;
+
+  // baseline_cost: what measured turns would have cost without prompt caching
+  const baselineCost = measuredCost + (savings.cache ? savings.cache.value : 0);
+
+  return {
+    measuredCost,
+    estimatedCost,
+    totalCost,
+    // What paid-API equivalent would have cost; for Max users the gap
+    // (theoreticalTotal - totalCost) is the subscription's captured value.
+    theoreticalCost: theoreticalTotal,
+    valueCaptured,
+    estimationConfidence: estimatedTurns.length > 0 ? 'low' : null,
+    // Legacy field kept for callers that haven't migrated yet
+    cost: totalCost,
+    baseline_cost: baselineCost,
+    savings: {
+      ...savings,
+      // Honest framing: cache discount is automatic in Claude Code -- IJFW measures it
+      labelShort: 'Cache efficiency (Claude Code automatic caching)',
+      labelLong: `Cache hit rate: ${(cacheHitRate * 100).toFixed(1)}% of context served from cache. Claude Code caches automatically; IJFW measures the effect.`,
+    },
+    tokens: { input: totalIn, output: totalOut, cache_read: totalCacheRead },
+    cacheHitRate,
+    turnCount: turns.length,
+    measuredTurnCount: measuredTurns.length,
+    estimatedTurnCount: estimatedTurns.length,
+  };
+}
+
+/**
+ * Build a breakdown grouped by a dimension.
+ * dim: 'platform' | 'session' | 'model' | 'tool'
+ */
+export function buildBreakdown(dim, days, _observations = []) {
+  const raw   = readAllTurns(days);
+  const turns = annotateCosts(raw);
+
+  const groups = {};
+  for (const t of turns) {
+    const key = t[dim] || 'unknown';
+    if (!groups[key]) groups[key] = { key, cost_usd: 0, theoretical_cost_usd: 0, input_tokens: 0, output_tokens: 0, cache_read_tokens: 0, count: 0 };
+    groups[key].cost_usd             += t.cost_usd;
+    groups[key].theoretical_cost_usd += t.theoretical_cost_usd || 0;
+    groups[key].input_tokens         += t.input_tokens || 0;
+    groups[key].output_tokens        += t.output_tokens || 0;
+    groups[key].cache_read_tokens    += t.cache_read_tokens || 0;
+    groups[key].count++;
+  }
+
+  // Sort by theoretical cost so Max-session breakdowns still rank by usage
+  // intensity even when cost_usd is uniformly zero.
+  return Object.values(groups).sort((a, b) => b.theoretical_cost_usd - a.theoretical_cost_usd);
+}
+
+/**
+ * Build daily series for sparkline (last N days).
+ */
+export function buildDailySeries(days = 30) {
+  const raw   = readAllTurns(days);
+  const turns = annotateCosts(raw);
+
+  const byDay = {};
+  for (const t of turns) {
+    if (!t.timestamp) continue;
+    const d = t.timestamp.slice(0, 10); // YYYY-MM-DD
+    if (!byDay[d]) byDay[d] = { date: d, cost_usd: 0, theoretical_cost_usd: 0, input_tokens: 0, output_tokens: 0 };
+    byDay[d].cost_usd             += t.cost_usd;
+    byDay[d].theoretical_cost_usd += t.theoretical_cost_usd || 0;
+    byDay[d].input_tokens         += t.input_tokens || 0;
+    byDay[d].output_tokens        += t.output_tokens || 0;
+  }
+
+  // Fill in zeros for missing days
+  const now = new Date();
+  const series = [];
+  for (let i = days - 1; i >= 0; i--) {
+    const d = new Date(now - i * MS_PER_DAY).toISOString().slice(0, 10);
+    series.push(byDay[d] || { date: d, cost_usd: 0, theoretical_cost_usd: 0, input_tokens: 0, output_tokens: 0 });
+  }
+  return series;
+}
+
+/**
+ * Compute the current 5-hour usage block (Anthropic rolling window).
+ * Returns usage within the last 5 hours from Claude turns only.
+ */
+export function buildBlockUsage() {
+  const fiveHoursMs = 5 * 3600000;
+  const cutoff = Date.now() - fiveHoursMs;
+
+  const raw   = readAllTurns(1); // last 24h is enough
+  const turns = annotateCosts(raw.filter(t => t.platform === 'claude'));
+
+  const blockTurns = turns.filter(t => {
+    if (!t.timestamp) return false;
+    return new Date(t.timestamp).getTime() >= cutoff;
+  });
+
+  const usedCost        = blockTurns.reduce((s, t) => s + t.cost_usd, 0);
+  const usedTheoretical = blockTurns.reduce((s, t) => s + (t.theoretical_cost_usd || 0), 0);
+  const usedTok         = blockTurns.reduce((s, t) => s + (t.input_tokens || 0) + (t.output_tokens || 0), 0);
+  const start           = new Date(cutoff).toISOString();
+  const end             = new Date(Date.now()).toISOString();
+
+  return {
+    start,
+    end,
+    window_minutes: 300,
+    used_tok: usedTok,
+    used_usd: usedCost,
+    used_usd_theoretical: usedTheoretical,
+  };
+}
+
+/**
+ * Top tools by token burn.
+ */
+export function buildTopTools(days, limit = 5) {
+  return buildBreakdown('tool_name', days).slice(0, limit);
+}
+
+/**
+ * Alias used by tests and CLI: getPeriodReport(days, observations?)
+ */
+export function getPeriodReport(days, observations = []) {
+  return buildCostReport(days, observations);
+}
+
+/**
+ * Returns the savings methodology doc for /api/savings/methodology.
+ */
+export { getSavingsMethodology };

package/src/cost/pricing.js

@@ -0,0 +1,134 @@
+/**
+ * IJFW cost/pricing.js
+ * Loads vendored model_prices.json and computes per-turn USD cost.
+ * Source: https://github.com/BerriAI/litellm/blob/main/model_prices_and_context_window.json
+ * Zero deps -- node:fs only.
+ */
+
+import { readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PRICES_PATH = join(__dirname, '../../data/model_prices.json');
+
+let _prices = null;
+
+function loadPrices() {
+  if (_prices) return _prices;
+  try {
+    const raw = readFileSync(PRICES_PATH, 'utf8');
+    const data = JSON.parse(raw);
+    _prices = data.models || data;
+  } catch {
+    _prices = {};
+  }
+  return _prices;
+}
+
+/**
+ * Resolve price entry for a model id. Tries exact match, then common aliases.
+ * Returns { in, out, cache_create_5m, cache_create_1h, cache_read } all in USD/token.
+ */
+export function getPricing(modelId) {
+  const prices = loadPrices();
+  const id = (modelId || '').toLowerCase().trim();
+
+  // Exact match
+  let entry = prices[id] || prices[modelId];
+
+  // Fuzzy: strip date suffixes and try again
+  if (!entry) {
+    for (const key of Object.keys(prices)) {
+      if (key.toLowerCase().startsWith(id) || id.startsWith(key.toLowerCase())) {
+        entry = prices[key];
+        break;
+      }
+    }
+  }
+
+  // Model family fallbacks for common Claude Code models
+  if (!entry) {
+    const fallbacks = {
+      'claude-opus-4': 'claude-4-opus-20250514',
+      'claude-sonnet-4': 'claude-4-sonnet-20250514',
+      'claude-haiku-4': 'claude-haiku-4-5',
+      'claude-3-5-sonnet': 'claude-3-5-sonnet-20241022',
+      'claude-3-5-haiku': 'claude-3-5-haiku-20241022',
+      'claude-3-opus': 'claude-3-opus-20240229',
+      'gpt-5': 'gpt-4o',
+      'gpt-4o': 'gpt-4o',
+      'o3': 'o3',
+      'o4': 'o4-mini',
+      'gemini-2': 'gemini/gemini-2.0-flash',
+      'gemini-1.5': 'gemini/gemini-1.5-pro',
+    };
+    for (const [prefix, fallback] of Object.entries(fallbacks)) {
+      if (id.includes(prefix.toLowerCase())) {
+        entry = prices[fallback];
+        if (entry) break;
+      }
+    }
+  }
+
+  if (!entry) {
+    // Unknown model: use claude-sonnet-4 rates as conservative estimate
+    entry = prices['claude-4-sonnet-20250514'] || {
+      input_cost_per_token: 3e-6,
+      output_cost_per_token: 1.5e-5,
+      cache_creation_input_token_cost: 3.75e-6,
+      cache_read_input_token_cost: 3e-7,
+    };
+  }
+
+  const inCost = entry.input_cost_per_token || 0;
+  const outCost = entry.output_cost_per_token || 0;
+  // cache_create_5m: 1.25x input price; cache_create_1h: 2.0x input price
+  // Use vendored values if present, else compute from multipliers
+  const cacheCreate5m = entry.cache_creation_input_token_cost ?? (inCost * 1.25);
+  const cacheCreate1h = inCost * 2.0; // always 2x; LiteLLM doesn't split this
+  const cacheRead = entry.cache_read_input_token_cost ?? (inCost * 0.1);
+
+  return { in: inCost, out: outCost, cache_create_5m: cacheCreate5m, cache_create_1h: cacheCreate1h, cache_read: cacheRead };
+}
+
+/**
+ * Compute cost in USD for a single turn's usage object.
+ * usage: { input_tokens, output_tokens, cache_create_tokens_5m, cache_create_tokens_1h, cache_read_tokens }
+ * Uses correct split for 5m vs 1h cache creation (fixes ccusage bug #899).
+ */
+export function computeCost(modelId, usage) {
+  const p = getPricing(modelId);
+  const {
+    input_tokens = 0,
+    output_tokens = 0,
+    cache_create_tokens_5m = 0,
+    cache_create_tokens_1h = 0,
+    cache_read_tokens = 0,
+  } = usage || {};
+
+  return (
+    input_tokens          * p.in +
+    output_tokens         * p.out +
+    cache_create_tokens_5m * p.cache_create_5m +
+    cache_create_tokens_1h * p.cache_create_1h +
+    cache_read_tokens     * p.cache_read
+  );
+}
+
+/** Return the raw prices table for /api/prices transparency endpoint. */
+export function getPricesTable() {
+  const prices = loadPrices();
+  return {
+    _source: 'https://github.com/BerriAI/litellm/blob/main/model_prices_and_context_window.json',
+    _refreshed: '2026-04-16',
+    formulas: {
+      turn_cost: 'input_tokens*in + output_tokens*out + cache_create_5m*cache_create_5m_price + cache_create_1h*cache_create_1h_price + cache_read*cache_read_price',
+      cache_savings: 'cache_read_tokens (measured, non-estimated only) * in_price * 0.9',
+      memory_savings: 'unique_first_recalls_per_session * 800_tokens * in_price',
+      trident_savings: '$5 per unique HIGH finding pre-ship (capped at 20/week)',
+      terse_savings: 'REMOVED -- prior 1.4x multiplier had no empirical basis',
+    },
+    models: prices,
+  };
+}

package/src/cost/readers/claude.js

@@ -0,0 +1,179 @@
+/**
+ * IJFW cost/readers/claude.js
+ * Reads Claude Code JSONL session files from ~/.claude/projects/<project>/*.jsonl
+ * Extracts per-turn token usage. Never throws on corrupt lines -- logs and skips.
+ * Data approach adapted from ccusage (ryoppippi, MIT) and tokscale (junhoyeo, MIT).
+ */
+
+import { readdirSync, readFileSync, existsSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+const CLAUDE_PROJECTS_DIR = join(homedir(), '.claude', 'projects');
+const TRANSCRIPT_SUMMARY  = join(homedir(), '.ijfw', 'transcript-summary.json');
+
+/**
+ * Detect Claude Code billing mode for the local user.
+ * ANTHROPIC_API_KEY in env is the unambiguous paid-API signal. Without it,
+ * Claude Code is using OAuth (Max/Pro/Team subscription) -- the OAuth token
+ * may live in ~/.claude/.credentials.json (Linux/Windows) or in the macOS
+ * Keychain, both of which Claude Code manages itself. Override with
+ * IJFW_BILLING_MODE=max|api.
+ */
+export function detectBillingMode() {
+  const override = (process.env.IJFW_BILLING_MODE || '').toLowerCase();
+  if (override === 'max' || override === 'api') return override;
+  if (process.env.ANTHROPIC_API_KEY) return 'api';
+  return 'max';
+}
+
+/**
+ * Build a per-session billing_mode map from ~/.ijfw/transcript-summary.json.
+ * The transcript parser stamps the mode at parse time (first-parse-wins),
+ * so this preserves historical billing context across mode switches. Sessions
+ * that have not yet been parsed fall back to current env detection.
+ */
+function loadSessionBillingMap() {
+  if (!existsSync(TRANSCRIPT_SUMMARY)) return null;
+  let data;
+  try { data = JSON.parse(readFileSync(TRANSCRIPT_SUMMARY, 'utf8')); }
+  catch { return null; }
+  const map = new Map();
+  const projects = data && data.projects;
+  if (!projects || typeof projects !== 'object') return map;
+  for (const proj of Object.values(projects)) {
+    if (!proj || !Array.isArray(proj.sessions)) continue;
+    for (const sess of proj.sessions) {
+      if (sess && sess.file && sess.billingMode) {
+        map.set(sess.file.replace(/\.jsonl$/, ''), sess.billingMode);
+      }
+    }
+  }
+  return map;
+}
+
+/**
+ * Walk ~/.claude/projects/<project>/<session>.jsonl and extract usage turns.
+ * Returns array of turn objects.
+ */
+export function readClaudeSessions(projectsDir = CLAUDE_PROJECTS_DIR) {
+  if (!existsSync(projectsDir)) return [];
+
+  // Per-session billing mode preserves historical context across env-mode
+  // switches; current env detection is the fallback for unparsed sessions.
+  const sessionBillingMap = loadSessionBillingMap();
+  const fallbackMode = detectBillingMode();
+  const turns = [];
+  let projectDirs;
+  try {
+    projectDirs = readdirSync(projectsDir);
+  } catch {
+    return [];
+  }
+
+  for (const projectName of projectDirs) {
+    const projectPath = join(projectsDir, projectName);
+    let stat;
+    try { stat = statSync(projectPath); } catch { continue; }
+    if (!stat.isDirectory()) continue;
+
+    let files;
+    try { files = readdirSync(projectPath); } catch { continue; }
+
+    for (const file of files) {
+      if (!file.endsWith('.jsonl')) continue;
+      const filePath = join(projectPath, file);
+      const sessionId = file.replace('.jsonl', '');
+
+      try {
+        const lines = readFileSync(filePath, 'utf8').split('\n').filter(Boolean);
+        for (const line of lines) {
+          try {
+            const record = JSON.parse(line);
+            const turn = extractClaudeTurn(record, sessionId, projectName);
+            if (turn) {
+              turn.billing_mode = (sessionBillingMap && sessionBillingMap.get(sessionId)) || fallbackMode;
+              turns.push(turn);
+            }
+          } catch {
+            // corrupt line -- skip
+          }
+        }
+      } catch {
+        // unreadable file -- skip
+      }
+    }
+
+    // Also walk subagents/ subdirectory
+    const subagentsDir = join(projectPath, 'subagents');
+    if (existsSync(subagentsDir)) {
+      let subfiles;
+      try { subfiles = readdirSync(subagentsDir); } catch { subfiles = []; }
+      for (const file of subfiles) {
+        if (!file.endsWith('.jsonl')) continue;
+        const filePath = join(subagentsDir, file);
+        const sessionId = file.replace('.jsonl', '');
+        try {
+          const lines = readFileSync(filePath, 'utf8').split('\n').filter(Boolean);
+          for (const line of lines) {
+            try {
+              const record = JSON.parse(line);
+              const turn = extractClaudeTurn(record, sessionId, projectName);
+              if (turn) {
+                turn.billing_mode = (sessionBillingMap && sessionBillingMap.get(sessionId)) || fallbackMode;
+                turns.push(turn);
+              }
+            } catch {}
+          }
+        } catch {}
+      }
+    }
+  }
+
+  return turns;
+}
+
+function extractClaudeTurn(record, sessionId, project) {
+  // Claude Code JSONL: assistant messages have message.usage
+  const msg = record.message;
+  if (!msg || msg.role !== 'assistant') return null;
+
+  const usage = msg.usage;
+  if (!usage) return null;
+
+  const inputTokens  = usage.input_tokens || 0;
+  const outputTokens = usage.output_tokens || 0;
+  const cacheRead    = usage.cache_read_input_tokens || 0;
+
+  // Claude Code 3.7+ splits cache creation into 5m and 1h buckets
+  const cacheCreate5m = (usage.cache_creation && usage.cache_creation.ephemeral_5m_input_tokens) ||
+                        (usage.cache_creation_input_tokens || 0); // fallback: pre-3.7
+  const cacheCreate1h = (usage.cache_creation && usage.cache_creation.ephemeral_1h_input_tokens) || 0;
+
+  if (!inputTokens && !outputTokens && !cacheRead && !cacheCreate5m && !cacheCreate1h) return null;
+
+  // Find tool_name from the content blocks if present
+  let toolName = null;
+  if (Array.isArray(msg.content)) {
+    for (const block of msg.content) {
+      if (block && block.type === 'tool_use') {
+        toolName = block.name;
+        break;
+      }
+    }
+  }
+
+  return {
+    platform: 'claude',
+    session_id: sessionId,
+    project,
+    timestamp: record.timestamp || null,
+    model: msg.model || 'claude-unknown',
+    input_tokens: inputTokens,
+    output_tokens: outputTokens,
+    cache_create_tokens_5m: cacheCreate5m,
+    cache_create_tokens_1h: cacheCreate1h,
+    cache_read_tokens: cacheRead,
+    tool_name: toolName,
+  };
+}

package/src/cost/readers/codex.js

@@ -0,0 +1,131 @@
+/**
+ * IJFW cost/readers/codex.js
+ * Reads Codex CLI JSONL session files from ~/.codex/sessions/**\/*.jsonl
+ * Codex uses event_msg/token_count for rate-limit tracking (not per-turn billing).
+ * For cost attribution we use session_meta (model) + response_item messages
+ * and estimate tokens from content length when explicit counts unavailable.
+ * Data approach adapted from tokscale (junhoyeo, MIT).
+ */
+
+import { readdirSync, readFileSync, existsSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+const CODEX_SESSIONS_DIR = join(homedir(), '.codex', 'sessions');
+
+export function readCodexSessions(sessionsDir = CODEX_SESSIONS_DIR) {
+  if (!existsSync(sessionsDir)) return [];
+  const turns = [];
+  walkDir(sessionsDir, turns);
+  return turns;
+}
+
+function walkDir(dir, turns) {
+  let entries;
+  try { entries = readdirSync(dir); } catch { return; }
+
+  for (const entry of entries) {
+    const fullPath = join(dir, entry);
+    let stat;
+    try { stat = statSync(fullPath); } catch { continue; }
+
+    if (stat.isDirectory()) {
+      walkDir(fullPath, turns);
+    } else if (entry.endsWith('.jsonl')) {
+      processCodexFile(fullPath, turns);
+    }
+  }
+}
+
+function processCodexFile(filePath, turns) {
+  let lines;
+  try {
+    lines = readFileSync(filePath, 'utf8').split('\n').filter(Boolean);
+  } catch {
+    return;
+  }
+
+  // Collect session metadata first
+  let sessionMeta = null;
+  let sessionId = null;
+  let model = 'gpt-5'; // codex default
+
+  for (const line of lines) {
+    try {
+      const record = JSON.parse(line);
+      if (record.type === 'session_meta') {
+        sessionMeta = record.payload || {};
+        sessionId = sessionMeta.id || null;
+        model = sessionMeta.collaboration_mode?.settings?.model ||
+                sessionMeta.model || 'gpt-5';
+      }
+    } catch {}
+  }
+
+  if (!sessionId) {
+    // Derive session id from filename
+    const base = filePath.split('/').pop().replace('.jsonl', '');
+    sessionId = base;
+  }
+
+  // Extract timestamp from session path (YYYY/MM/DD/filename)
+  const dateParts = filePath.match(/(\d{4})\/(\d{2})\/(\d{2})/);
+  const datePrefix = dateParts ? `${dateParts[1]}-${dateParts[2]}-${dateParts[3]}` : null;
+
+  // Accumulate per-session totals from response_item/message content
+  // Codex does not expose per-turn token counts in JSONL; we estimate from chars
+  let totalInputChars = 0;
+  let totalOutputChars = 0;
+  let lastTimestamp = datePrefix ? datePrefix + 'T12:00:00.000Z' : null;
+
+  for (const line of lines) {
+    try {
+      const record = JSON.parse(line);
+      if (record.timestamp) lastTimestamp = record.timestamp;
+
+      if (record.type === 'response_item' && record.payload) {
+        const payload = record.payload;
+        const role = payload.role;
+        const content = payload.content;
+        if (!Array.isArray(content)) continue;
+
+        let chars = 0;
+        for (const block of content) {
+          if (block && block.text) chars += block.text.length;
+        }
+
+        if (role === 'user' || role === 'developer') {
+          totalInputChars += chars;
+        } else {
+          totalOutputChars += chars;
+        }
+      }
+    } catch {}
+  }
+
+  // Estimate tokens: 1 token ~= 4 chars (GPT-era heuristic)
+  const inputTokens  = Math.ceil(totalInputChars / 4);
+  const outputTokens = Math.ceil(totalOutputChars / 4);
+
+  if (!inputTokens && !outputTokens) return;
+
+  // Codex does not expose per-turn token counts or cache metrics in JSONL.
+  // Tokens are estimated from content length (1 token ~= 4 chars, GPT-era heuristic).
+  // cache_read_tokens is NOT included -- we cannot distinguish cached vs fresh reads
+  // from Codex JSONL, and fabricating a cache_read number would inflate savings.
+  turns.push({
+    platform: 'codex',
+    session_id: sessionId,
+    project: sessionMeta?.git?.repository_url?.split('/').pop() || null,
+    timestamp: lastTimestamp,
+    model,
+    input_tokens: inputTokens,
+    output_tokens: outputTokens,
+    cache_create_tokens_5m: 0,
+    cache_create_tokens_1h: 0,
+    cache_read_tokens: 0, // not available from Codex JSONL; excluded from savings
+    tool_name: null,
+    estimated: true, // tokens derived from char heuristic, not actual API usage counts
+    estimatedNote: 'Codex CLI does not log per-turn token counts locally. Tokens estimated from content length.',
+  });
+}