tledger 0.3.0 → 0.4.0

package/bin/token-ledger.mjs

@@ -4,7 +4,6 @@ import { spawnSync } from "node:child_process";
 import { existsSync, realpathSync } from "node:fs";
 import {
   mkdir,
-  stat,
 } from "node:fs/promises";
 import { homedir } from "node:os";
 import { basename, dirname, resolve } from "node:path";
@@ -14,30 +13,67 @@ import {
   MODEL_COLORS as TERMINAL_MODEL_COLORS,
   renderTerminal,
 } from "./token-ledger-terminal.mjs";
-import { buildUsageTrend, multiDayBounds } from "./token-ledger-trend.mjs";
 import {
-  renderTrendImage,
-  writeTrendPng,
-} from "./token-ledger-trend-image.mjs";
-import { renderCacheReportImage } from "./token-ledger-cache-image.mjs";
+  buildRangeAnalysis,
+  buildUsageTrend,
+  multiDayBounds,
+  priorPeriodBounds,
+} from "./token-ledger-trend.mjs";
+import {
+  resolveEffectiveEnd,
+} from "./token-ledger-report-data.mjs";
 import { renderTrendCombo } from "./token-ledger-trend-terminal.mjs";
+import { renderCostTerminal } from "./token-ledger-cost-terminal.mjs";
 import { startInteractive } from "./token-ledger-tui.mjs";
+import {
+  snapshotFreshnessDetail,
+  sourceStatusLine,
+} from "./token-ledger-source-status.mjs";
+import {
+  createTimeZoneFormatter,
+  formatCalendarDate,
+  localDateBoundary,
+  shiftCalendarDate,
+  todayInTimeZone,
+  validateTimeZone,
+} from "../lib/token-ledger-calendar.mjs";
 import {
   readPrivateSnapshot,
-  writePrivateSnapshot,
+  stagePrivateSnapshot,
 } from "../lib/token-ledger-snapshot.mjs";
+import {
+  collectionScope,
+  historyScopeLabel,
+  normalizeCollectionSince,
+  snapshotCollectionCutoffMs,
+  snapshotCollectionScope,
+  snapshotMatchesCollectionScope,
+} from "../lib/token-ledger-collection.mjs";
 import {
   SNAPSHOT_SCHEMA_VERSION,
+  checkedFiniteAdd,
+  checkedTokenAdd,
+  scaledOutputTokens,
+  tokenValue,
+  MAX_SAFE_TOKEN_COUNT,
   usageBuckets,
   usageBucketsInRange,
   usageCallCount,
   usageThreadIds,
 } from "../lib/token-ledger-usage.mjs";
+import { calculateCodexPurchasedCredits } from "../lib/token-ledger-rates.mjs";
+import { sanitizeTerminalText } from "../lib/token-ledger-terminal-text.mjs";
+import {
+  QUOTA_IDENTITY_CONTRACT_VERSION,
+  snapshotHasCurrentQuotaIdentityContract,
+} from "../lib/token-ledger-quota-contract.mjs";
+
+export { sanitizeTerminalText };
 
 export const DEFAULT_SNAPSHOT = resolve(
   homedir(),
   ".token-ledger",
-  "token-ledger-snapshot-v2.json.gz",
+  "token-ledger-snapshot-v3.json.gz",
 );
 const DEFAULT_TOP = 10;
 const DEFAULT_TIME_ZONE = Intl.DateTimeFormat().resolvedOptions().timeZone;
@@ -47,6 +83,7 @@ const MAX_ROLLING_DAYS = 3_650;
 const DURATION_ALIAS = /^(\d+)(d|w)$/i;
 const ANSI_RESET = "\u001b[0m";
 const MODEL_COLORS = {
+  astra: TERMINAL_MODEL_COLORS.astra,
   sol: TERMINAL_MODEL_COLORS.sol,
   luna: TERMINAL_MODEL_COLORS.luna,
   terra: TERMINAL_MODEL_COLORS.terra,
@@ -55,6 +92,38 @@ const MODEL_COLORS = {
   other: TERMINAL_MODEL_COLORS.other,
 };
 
+function createSharedTokenScale() {
+  return {
+    scale: 1,
+    totalTokens: 0,
+    targets: new Set(),
+  };
+}
+
+function addSharedTokenContribution(state, contribution, targets) {
+  const tokens = tokenValue(contribution, { allowFractional: true });
+  if (!(tokens > 0)) return;
+  const scaledTokens = tokens / state.scale;
+  for (const target of targets) {
+    state.targets.add(target);
+    target.totalTokens += scaledTokens;
+  }
+  state.totalTokens += scaledTokens;
+  const scaleFactor = Math.max(
+    1,
+    state.totalTokens / MAX_SAFE_TOKEN_COUNT,
+  );
+  if (scaleFactor === 1) return;
+  for (const target of state.targets) {
+    target.totalTokens /= scaleFactor;
+    if (target.totalTokens >= MAX_SAFE_TOKEN_COUNT - 2) {
+      target.totalTokens = MAX_SAFE_TOKEN_COUNT;
+    }
+  }
+  state.totalTokens = MAX_SAFE_TOKEN_COUNT;
+  state.scale *= scaleFactor;
+}
+
 export function usage() {
   return `Token Ledger
 
@@ -62,12 +131,16 @@ Usage:
   tledger 1d                         Last 24 hours in the terminal
   tledger week                       Last 7 calendar days in the terminal
   tledger 30d                        Rolling 30 days in the terminal
+  tledger cost 7d --basis api-usd    Hypothetical API-equivalent USD estimate
+  tledger cost week --basis codex-credits
+                                     Codex purchased-credit estimate
   tledger report 7d                  Write the 7-day PNG report
   tledger report 7d --cache-rate     Write the cache-only PNG report
 
 Common options:
   --static                  Print once instead of opening the dashboard
   --refresh                 Rebuild the local usage cache
+  --since <ISO timestamp>   Collect history at or after this timestamp
   --image-output <file>     Choose where to save a PNG
   --no-open                 Do not open a generated PNG
   -h, --help                Show this quick guide
@@ -87,6 +160,12 @@ Terminal commands:
   tledger week [end-day]             Seven local calendar days
   tledger trend [Nd|Nw]              Multi-day terminal trend
 
+Cost commands (basis is required):
+  tledger cost <1d|Nd|Nw|week> --basis api-usd
+                                      Hypothetical API-equivalent USD estimate
+  tledger cost <1d|Nd|Nw|week> --basis codex-credits
+                                      Codex purchased-credit estimate
+
 Report commands:
   tledger report [Nd|Nw]             Write the usage dashboard PNG
   tledger report [Nd|Nw] --cache-rate
@@ -102,6 +181,7 @@ Data and refresh:
   --refresh                  Rebuild the default snapshot from local Codex data
   --no-refresh               Use the cached snapshot without checking source files
   --codex-home <dir>         Codex data root used when refreshing
+  --since <ISO timestamp>    Collect history at or after this timestamp
   --no-archived              Skip archived sessions when refreshing
 
 Terminal output:
@@ -114,6 +194,7 @@ Terminal output:
   --youplot                  Use the legacy single-series renderer
 
 Report output:
+  --private                 Hide project names in the report
   --drain                    Chart estimated meter drain instead of token volume
   --cache-rate               Write the cache-only report (report command only)
   --image                    Write the trend view as a PNG
@@ -125,7 +206,8 @@ Help:
   -h, --help                Show the quick guide
   --help-all                Show this complete reference
 
-The default snapshot is ~/.token-ledger/token-ledger-snapshot-v2.json.gz.
+The default snapshot is ~/.token-ledger/token-ledger-snapshot-v3.json.gz and
+the durable ledger is ~/.token-ledger/token-ledger-ledger.sqlite.
 Token Ledger reads local Codex data only. It does not upload your usage.`;
 }
 
@@ -172,10 +254,22 @@ function readOption(argv, index, name) {
 
 export function parseArgs(argv) {
   const helpCommand = argv[0] === "help";
+  const costCommand = argv[0] === "cost";
+  const costRangeValue = costCommand ? argv[1] : null;
+  const costHelpWithoutRange = costCommand &&
+    ["--help", "-h", "--help-all"].includes(costRangeValue);
+  const costAlias = costCommand && costRangeValue !== "week" && !costHelpWithoutRange
+    ? durationAlias(costRangeValue)
+    : null;
+  const costRangeValid = costRangeValue === "week" || Boolean(costAlias);
   const alias = durationAlias(argv[0]);
-  const rolling24hCommand = argv[0] === "1d";
-  const rollingDurationCommand = Boolean(alias) && !rolling24hCommand;
-  const command = rolling24hCommand
+  const rolling24hCommand = argv[0] === "1d" ||
+    (costCommand && costAlias?.days === 1);
+  const rollingDurationCommand = (Boolean(alias) && argv[0] !== "1d") ||
+    (costCommand && Boolean(costAlias) && costAlias.days !== 1);
+  const command = costCommand && costRangeValue === "week"
+    ? "week"
+    : rolling24hCommand
     ? "rolling24h"
     : rollingDurationCommand
       ? "rolling"
@@ -186,13 +280,14 @@ export function parseArgs(argv) {
         : "day";
   const options = {
     range: command,
-    view: command === "trend" ? "trend" : "projects",
+    view: costCommand ? "cost" : command === "trend" ? "trend" : "projects",
     rolling24h: rolling24hCommand,
     rollingDuration: rollingDurationCommand,
-    rollingDays: alias?.days ?? (rolling24hCommand ? 1 : null),
-    rollingAmount: alias?.amount ?? (rolling24hCommand ? 1 : null),
-    rollingUnit: alias?.unit ?? (rolling24hCommand ? "d" : null),
-    rollingLabel: alias?.label ?? "1 day",
+    rollingDays: (costCommand ? costAlias?.days : alias?.days) ?? (rolling24hCommand ? 1 : null),
+    rollingAmount: (costCommand ? costAlias?.amount : alias?.amount) ?? (rolling24hCommand ? 1 : null),
+    rollingUnit: (costCommand ? costAlias?.unit : alias?.unit) ?? (rolling24hCommand ? "d" : null),
+    rollingLabel: (costCommand ? costAlias?.label : alias?.label) ?? "1 day",
+    basis: null,
     report: argv[0] === "report",
     trendDays: 7,
     date: null,
@@ -201,6 +296,7 @@ export function parseArgs(argv) {
     refresh: false,
     autoRefresh: true,
     codexHome: resolve(process.env.CODEX_HOME || `${homedir()}/.codex`),
+    since: null,
     includeArchived: true,
     timeZone: DEFAULT_TIME_ZONE,
     top: DEFAULT_TOP,
@@ -208,20 +304,24 @@ export function parseArgs(argv) {
     rawProjects: false,
     plain: false,
     ascii: false,
-    static: false,
+    static: costCommand,
     image: false,
     imageOutput: null,
     imageWidth: null,
     openImage: true,
     drain: false,
     cacheRate: false,
+    private: false,
     legacyPlot: false,
     help: argv.length === 0 || helpCommand,
     helpAll: false,
   };
 
   let trendPeriodSeen = false;
-  let index = alias || ["day", "week", "trend", "report", "help"].includes(argv[0]) ? 1 : 0;
+  let basisSeen = false;
+  let index = costCommand
+    ? costHelpWithoutRange ? 1 : 2
+    : alias || ["day", "week", "trend", "report", "help"].includes(argv[0]) ? 1 : 0;
   for (; index < argv.length; index += 1) {
     const argument = argv[index];
     if (argument === "--help" || argument === "-h") {
@@ -249,6 +349,18 @@ export function parseArgs(argv) {
       options.trendDays = period.days;
       trendPeriodSeen = true;
       index += 1;
+    } else if (argument === "--basis") {
+      if (options.view !== "cost") {
+        throw new Error("--basis is only available with the cost command.");
+      }
+      if (basisSeen) throw new Error("Cost basis can only be specified once.");
+      const value = readOption(argv, index, "--basis");
+      if (value !== "codex-credits" && value !== "api-usd") {
+        throw new Error("--basis must be codex-credits or api-usd.");
+      }
+      options.basis = value;
+      basisSeen = true;
+      index += 1;
     } else if (argument === "--input") {
       options.input = resolve(readOption(argv, index, "--input"));
       options.inputExplicit = true;
@@ -260,10 +372,17 @@ export function parseArgs(argv) {
     } else if (argument === "--codex-home") {
       options.codexHome = resolve(readOption(argv, index, "--codex-home"));
       index += 1;
+    } else if (argument === "--since") {
+      const value = readOption(argv, index, "--since");
+      options.since = new Date(normalizeCollectionSince(value));
+      index += 1;
     } else if (argument === "--tz") {
       options.timeZone = readOption(argv, index, "--tz");
       index += 1;
     } else if (argument === "--top") {
+      if (options.view === "cost") {
+        throw new Error("--top is not available with the cost command.");
+      }
       const value = Number(readOption(argv, index, "--top"));
       if (!Number.isInteger(value) || value < 1 || value > 100) {
         throw new Error("--top must be an integer from 1 to 100.");
@@ -271,6 +390,9 @@ export function parseArgs(argv) {
       options.top = value;
       index += 1;
     } else if (argument === "--width") {
+      if (options.view === "cost") {
+        throw new Error("--width is not available with the cost command.");
+      }
       const value = Number(readOption(argv, index, "--width"));
       if (!Number.isInteger(value) || value < 40 || value > 200) {
         throw new Error("--width must be an integer from 40 to 200.");
@@ -284,6 +406,9 @@ export function parseArgs(argv) {
     } else if (argument === "--plain") {
       options.plain = true;
     } else if (argument === "--ascii") {
+      if (options.view === "cost") {
+        throw new Error("--ascii is not available with the cost command.");
+      }
       options.ascii = true;
     } else if (argument === "--static") {
       options.static = true;
@@ -292,6 +417,11 @@ export function parseArgs(argv) {
         throw new Error("--drain is only available for the trend view.");
       }
       options.drain = true;
+    } else if (argument === "--private") {
+      if (!options.report) {
+        throw new Error("--private is only available with the report command.");
+      }
+      options.private = true;
     } else if (argument === "--cache-rate") {
       if (!options.report) {
         throw new Error("--cache-rate is only available with the report command.");
@@ -364,6 +494,12 @@ export function parseArgs(argv) {
   }
 
   if (options.report) options.image = true;
+  if (!options.help && costCommand && !costRangeValid) {
+    throw new Error("Cost range must be 1d, Nd, Nw, or week.");
+  }
+  if (!options.help && costCommand && !options.basis) {
+    throw new Error("The cost command requires --basis codex-credits or --basis api-usd.");
+  }
   if (!options.help && (options.rolling24h || options.rollingDuration) && options.date) {
     throw new Error(`${options.rollingLabel} does not accept --date; its rolling window ends now.`);
   }
@@ -382,92 +518,24 @@ export function parseArgs(argv) {
   if (!options.help && options.view === "trend" && options.legacyPlot) {
     throw new Error("--youplot is only available for the project view.");
   }
+  if (!options.help && options.view === "cost" && options.legacyPlot) {
+    throw new Error("--youplot is not available with the cost command.");
+  }
+  if (!options.help && options.view === "cost" && options.rawProjects) {
+    throw new Error("--raw-projects is not available with the cost command.");
+  }
   if (!options.help && options.cacheRate && options.drain) {
     throw new Error("--cache-rate cannot be combined with --drain.");
   }
   return options;
 }
 
-function numericDateParts(date) {
-  const parts = new Intl.DateTimeFormat("en-US", {
-    timeZone: date.timeZone,
-    year: "numeric",
-    month: "2-digit",
-    day: "2-digit",
-  }).formatToParts(date.value);
-  const values = Object.fromEntries(
-    parts
-      .filter((part) => part.type !== "literal")
-      .map((part) => [part.type, Number(part.value)]),
-  );
-  return values;
-}
-
-function dateStringFromParts(parts) {
-  return [parts.year, parts.month, parts.day]
-    .map((value, index) => (index === 0 ? String(value) : String(value).padStart(2, "0")))
-    .join("-");
-}
-
-function shiftCalendarDate(value, amount) {
-  const date = new Date(`${value}T00:00:00.000Z`);
-  date.setUTCDate(date.getUTCDate() + amount);
-  return date.toISOString().slice(0, 10);
-}
-
-function validateTimeZone(timeZone) {
-  try {
-    new Intl.DateTimeFormat("en-US", { timeZone }).format();
-  } catch {
-    throw new Error(`Unknown IANA timezone: ${timeZone}`);
-  }
-}
-
-function offsetAt(instant, timeZone) {
-  const parts = new Intl.DateTimeFormat("en-US", {
-    timeZone,
-    year: "numeric",
-    month: "2-digit",
-    day: "2-digit",
-    hour: "2-digit",
-    minute: "2-digit",
-    second: "2-digit",
-    hourCycle: "h23",
-  }).formatToParts(instant);
-  const values = Object.fromEntries(
-    parts
-      .filter((part) => part.type !== "literal")
-      .map((part) => [part.type, Number(part.value)]),
-  );
-  return (
-    Date.UTC(
-      values.year,
-      values.month - 1,
-      values.day,
-      values.hour,
-      values.minute,
-      values.second,
-    ) - instant.getTime()
-  );
-}
-
-function zonedMidnight(dateString, timeZone) {
-  const [year, month, day] = dateString.split("-").map(Number);
-  const utcGuess = Date.UTC(year, month - 1, day);
-  let instant = new Date(utcGuess - offsetAt(new Date(utcGuess), timeZone));
-  const refinedOffset = offsetAt(instant, timeZone);
-  instant = new Date(utcGuess - refinedOffset);
-  return instant;
-}
-
 export function dayBounds(value, timeZone) {
   validateTimeZone(timeZone);
+  const formatter = createTimeZoneFormatter(timeZone);
   let dateString = value;
   if (value === "today" || value === "yesterday") {
-    const today = dateStringFromParts(numericDateParts({
-      value: new Date(),
-      timeZone,
-    }));
+    const today = todayInTimeZone(timeZone, formatter);
     dateString = value === "today" ? today : shiftCalendarDate(today, -1);
   }
   if (!/^\d{4}-\d{2}-\d{2}$/.test(dateString)) {
@@ -483,8 +551,8 @@ export function dayBounds(value, timeZone) {
     throw new Error(`Invalid calendar day: ${dateString}`);
   }
   const nextDateString = shiftCalendarDate(dateString, 1);
-  const start = zonedMidnight(dateString, timeZone);
-  const end = zonedMidnight(nextDateString, timeZone);
+  const start = localDateBoundary(dateString, timeZone, formatter);
+  const end = localDateBoundary(nextDateString, timeZone, formatter);
   return { dateString, start, end, timeZone };
 }
 
@@ -495,7 +563,7 @@ export function weekBounds(value, timeZone) {
     ...endDay,
     startDateString,
     endDateString: endDay.dateString,
-    start: zonedMidnight(startDateString, timeZone),
+    start: localDateBoundary(startDateString, timeZone),
     rangeDays: 7,
   };
 }
@@ -529,13 +597,6 @@ export function rolling24hBounds(value = new Date(), timeZone = DEFAULT_TIME_ZON
   return rollingDurationBounds(value, timeZone, 1);
 }
 
-export function sanitizeTerminalText(value) {
-  return String(value ?? "")
-    .replace(/\u001b\][^\u0007]*(?:\u0007|\u001b\\)/g, "")
-    .replace(/\u001b\[[0-?]*[ -/]*[@-~]/g, "")
-    .replace(/[\u0000-\u001f\u007f-\u009f]+/g, " ");
-}
-
 function cleanLabel(value, fallback) {
   const label = sanitizeTerminalText(value)
     .replace(/\s+/g, " ")
@@ -548,6 +609,12 @@ const QUOTED_ABSOLUTE_PATH =
 const UNQUOTED_ABSOLUTE_PATH =
   /(^|[\s([{=])((?:\/(?!\/)|\/\/|\\\\|[A-Za-z]:[\\/])[^\s"'`)\]},;]+)/g;
 
+const QUOTED_FILE_URL_PATH = /(["'])(file:\/\/\/[^"'\r\n]*)\1/gi;
+const UNQUOTED_FILE_URL_PATH =
+  /(^|[\s([{=:])(file:\/\/\/[^\s"'`)\]},;]+)/gi;
+const COLON_PREFIXED_LOCAL_PATH =
+  /(^|:)((?:\/(?!\/)|\\\\|[A-Za-z]:[\\/])[^\s"'`)\]},;]+)/g;
+
 function isAbsoluteLocalPath(path) {
   return (
     path.startsWith("/") ||
@@ -580,6 +647,39 @@ export function redactLocalPaths(value, paths = []) {
     .filter((path) => path && path !== "/")
     .sort((left, right) => right.length - left.length);
 
+  const detectedPathLabel = (detectedPath) => {
+    const candidates = [detectedPath];
+    if (/^file:\/\/\//i.test(detectedPath)) {
+      const filePath = detectedPath.slice("file://".length);
+      candidates.push(filePath);
+      try {
+        candidates.push(decodeURIComponent(filePath));
+      } catch {
+        // Keep the raw file URL as the only candidate when its escape syntax
+        // is malformed; it is still safe to redact as an implicit path.
+      }
+    }
+    const explicit = [...explicitPaths].find((path) => candidates.includes(path));
+    return explicit ? safeDisplayLabel(explicit) : "[local path]";
+  };
+
+  // These forms occur in Node/worker diagnostics but are not covered by the
+  // ordinary absolute-path boundaries below. Handle them before replacing an
+  // explicit path substring so an explicit input still gets its safe filename.
+  redacted = redacted
+    .replace(
+      QUOTED_FILE_URL_PATH,
+      (_match, quote, path) => `${quote}${detectedPathLabel(path)}${quote}`,
+    )
+    .replace(
+      UNQUOTED_FILE_URL_PATH,
+      (_match, prefix, path) => `${prefix}${detectedPathLabel(path)}`,
+    )
+    .replace(
+      COLON_PREFIXED_LOCAL_PATH,
+      (_match, prefix, path) => `${prefix}${detectedPathLabel(path)}`,
+    );
+
   for (const path of pathsToRedact) {
     redacted = redacted.replaceAll(
       path,
@@ -605,7 +705,7 @@ function displayLabel(value) {
   return `${label.slice(0, 14)}…${label.slice(-13)}`;
 }
 
-export function oneOffProjects(snapshot) {
+export function oneOffProjects(snapshot, events = null) {
   const threadIdsByProject = new Map();
   const add = (project, threadId) => {
     if (!project || !threadId) return;
@@ -614,7 +714,7 @@ export function oneOffProjects(snapshot) {
     ids.add(threadId);
     threadIdsByProject.set(normalizedProject, ids);
   };
-  for (const bucket of usageBuckets(snapshot)) {
+  for (const bucket of events ?? usageBuckets(snapshot)) {
     for (const threadId of usageThreadIds(bucket)) add(bucket.project, threadId);
   }
   for (const thread of snapshot.threads ?? []) add(thread.project, thread.id);
@@ -628,6 +728,7 @@ export function oneOffProjects(snapshot) {
 function modelLabel(value) {
   const model = cleanLabel(value, "Unknown model");
   const lower = model.toLowerCase();
+  if (lower.includes("astra")) return "Astra";
   if (lower.includes("sol")) return "Sol";
   if (lower.includes("luna")) return "Luna";
   if (lower.includes("terra")) return "Terra";
@@ -636,17 +737,33 @@ function modelLabel(value) {
   return model;
 }
 
-export function filterDayEvents(snapshot, bounds) {
+function currentRateCardCredits(event) {
+  return calculateCodexPurchasedCredits({
+    model: event?.rateCardModel ?? event?.model,
+    serviceTier: event?.serviceTier,
+    usage: event,
+  });
+}
+
+export function filterDayEvents(snapshot, bounds, analysis = null) {
+  if (analysis !== null) return analysis.currentEvents;
   const start = bounds.start.getTime();
   const end = bounds.end.getTime();
   return usageBucketsInRange(snapshot, start, end);
 }
 
-export function aggregateProjects(snapshot, events, options = {}) {
-  const singletonProjects = options.rawProjects ? new Set() : oneOffProjects(snapshot);
+export function aggregateProjects(snapshot, events, options = {}, analysis = null) {
+  const singletonProjects = options.rawProjects
+    ? new Set()
+    : oneOffProjects(snapshot, analysis?.allEvents);
   const grouped = new Map();
+  const sharedTokenScale = createSharedTokenScale();
 
   for (const event of events) {
+    if (event?.invalidTokenRecord === true) continue;
+    const allowFractional = event?.rangeAllocationEstimated === true;
+    const totalTokens = tokenValue(event.totalTokens, { allowFractional });
+    const estimatedTokenContribution = allowFractional && totalTokens > 0;
     const rawProject = cleanLabel(event.project, "Unlabelled activity");
     const project =
       !options.rawProjects && singletonProjects.has(rawProject)
@@ -665,16 +782,36 @@ export function aggregateProjects(snapshot, events, options = {}) {
         rateCardCredits: 0,
         knownCreditTokens: 0,
         models: new Map(),
+        estimated: false,
       };
-    row.totalTokens += Number(event.totalTokens) || 0;
-    row.outputTokens += Number(event.outputTokens) || 0;
-    row.reasoningTokens += Number(event.reasoningTokens) || 0;
-    row.toolCalls += Number(event.toolCalls) || 0;
-    row.events += usageCallCount(event);
+    row.estimated ||= estimatedTokenContribution;
+    row.outputTokens = checkedTokenAdd(
+      row.outputTokens,
+      tokenValue(event.outputTokens, { allowFractional }),
+      { allowFractional },
+    );
+    row.reasoningTokens = checkedTokenAdd(
+      row.reasoningTokens,
+      tokenValue(event.reasoningTokens, { allowFractional }),
+      { allowFractional },
+    );
+    row.toolCalls = checkedTokenAdd(
+      row.toolCalls,
+      tokenValue(event.toolCalls, { allowFractional }),
+      { allowFractional },
+    );
+    row.events = checkedTokenAdd(row.events, usageCallCount(event), {
+      allowFractional,
+    });
     for (const threadId of usageThreadIds(event)) row.threadIds.add(threadId);
-    if (event.rateCardCredits !== null && Number.isFinite(Number(event.rateCardCredits))) {
-      row.rateCardCredits += Number(event.rateCardCredits);
-      row.knownCreditTokens += Number(event.totalTokens) || 0;
+    const rateCardCredits = currentRateCardCredits(event);
+    if (Number.isFinite(rateCardCredits)) {
+      row.rateCardCredits = checkedFiniteAdd(row.rateCardCredits, rateCardCredits);
+      row.knownCreditTokens = checkedTokenAdd(
+        row.knownCreditTokens,
+        tokenValue(event.totalTokens, { allowFractional }),
+        { allowFractional },
+      );
     }
 
     const model = modelLabel(event.model);
@@ -683,11 +820,22 @@ export function aggregateProjects(snapshot, events, options = {}) {
       totalTokens: 0,
       events: 0,
       rateCardCredits: 0,
+      estimated: false,
     };
-    modelRow.totalTokens += Number(event.totalTokens) || 0;
-    modelRow.events += usageCallCount(event);
-    if (event.rateCardCredits !== null && Number.isFinite(Number(event.rateCardCredits))) {
-      modelRow.rateCardCredits += Number(event.rateCardCredits);
+    modelRow.estimated ||= estimatedTokenContribution;
+    addSharedTokenContribution(
+      sharedTokenScale,
+      totalTokens,
+      [row, modelRow],
+    );
+    modelRow.events = checkedTokenAdd(modelRow.events, usageCallCount(event), {
+      allowFractional,
+    });
+    if (Number.isFinite(rateCardCredits)) {
+      modelRow.rateCardCredits = checkedFiniteAdd(
+        modelRow.rateCardCredits,
+        rateCardCredits,
+      );
     }
     row.models.set(model, modelRow);
     grouped.set(project, row);
@@ -709,19 +857,33 @@ export function aggregateProjects(snapshot, events, options = {}) {
     });
 }
 
-function totalSummary(events) {
-  return events.reduce(
+function totalSummary(events, projectRows) {
+  const summary = events.reduce(
     (summary, event) => {
-      summary.totalTokens += Number(event.totalTokens) || 0;
-      summary.outputTokens += Number(event.outputTokens) || 0;
-      summary.toolCalls += Number(event.toolCalls) || 0;
-      summary.calls += usageCallCount(event);
+      if (event?.invalidTokenRecord === true) return summary;
+      const allowFractional = event?.rangeAllocationEstimated === true;
+      summary.toolCalls = checkedTokenAdd(
+        summary.toolCalls,
+        tokenValue(event.toolCalls, { allowFractional }),
+        { allowFractional },
+      );
+      summary.calls = checkedTokenAdd(summary.calls, usageCallCount(event), {
+        allowFractional,
+      });
       for (const threadId of usageThreadIds(event)) {
         summary.threadIds.add(threadId);
       }
-      if (event.rateCardCredits !== null && Number.isFinite(Number(event.rateCardCredits))) {
-        summary.rateCardCredits += Number(event.rateCardCredits);
-        summary.knownCreditTokens += Number(event.totalTokens) || 0;
+      const rateCardCredits = currentRateCardCredits(event);
+      if (Number.isFinite(rateCardCredits)) {
+        summary.rateCardCredits = checkedFiniteAdd(
+          summary.rateCardCredits,
+          rateCardCredits,
+        );
+        summary.knownCreditTokens = checkedTokenAdd(
+          summary.knownCreditTokens,
+          tokenValue(event.totalTokens, { allowFractional }),
+          { allowFractional },
+        );
       }
       return summary;
     },
@@ -735,6 +897,12 @@ function totalSummary(events) {
       threadIds: new Set(),
     },
   );
+  summary.totalTokens = projectRows.reduce(
+    (sum, row) => sum + row.totalTokens,
+    0,
+  );
+  summary.outputTokens = scaledOutputTokens(events, summary.totalTokens);
+  return summary;
 }
 
 function compact(value, digits = 2) {
@@ -786,6 +954,7 @@ function colorize(value, code, enabled) {
 
 function modelColor(model) {
   const lower = model.toLowerCase();
+  if (lower.includes("astra")) return MODEL_COLORS.astra;
   if (lower.includes("sol")) return MODEL_COLORS.sol;
   if (lower.includes("luna")) return MODEL_COLORS.luna;
   if (lower.includes("terra")) return MODEL_COLORS.terra;
@@ -819,7 +988,7 @@ function runYouPlot(rows, options, dateLabel, unit) {
   const chartInput = [
     "project\tvalue",
     ...rows.map(
-      (row) => `${row.displayProject.replace(/[\t\r\n]+/g, " ")}\t${chartNumber(row.totalTokens, unit.divisor)}`,
+      (row) => `${sanitizeTerminalText(row.displayProject).replace(/[\t\r\n]+/g, " ")}\t${chartNumber(row.totalTokens, unit.divisor)}`,
     ),
   ].join("\n");
   const terminalWidth = Number(process.stdout.columns) || 100;
@@ -881,6 +1050,77 @@ async function readSnapshot(snapshotPath) {
   return parsed;
 }
 
+function snapshotScopeMatchesOptions(snapshot, options) {
+  const requested = collectionScope(options);
+  const actual = snapshotCollectionScope(snapshot);
+  if (!actual) {
+    // Explicit snapshots are deliberate inputs. Preserve the existing
+    // fixture/export workflow when no collection filter was requested, while
+    // refusing to claim that an unknown snapshot satisfies a filter.
+    return requested.since === null && requested.includeArchived;
+  }
+  return snapshotMatchesCollectionScope(snapshot, requested);
+}
+
+function snapshotScopeError(snapshot, options) {
+  const requested = collectionScope(options);
+  const actual = snapshotCollectionScope(snapshot);
+  const describe = (scope) => {
+    if (!scope) return "unknown collection scope";
+    const since = scope.since === null ? "full history" : `since ${scope.since}`;
+    const archives = scope.includeArchived
+      ? "archived sessions included"
+      : "archived sessions excluded";
+    return `${since}; ${archives}`;
+  };
+  const remedy = options.inputExplicit
+    ? "For --input, supply matching --since/--no-archived filters or rebuild that file with the collector; --refresh cannot be combined with --input."
+    : "Rebuild it with --refresh.";
+  return new Error(
+    `Snapshot collection scope does not match the requested filters (requested ${describe(requested)}; found ${describe(actual)}). ${remedy}`,
+  );
+}
+
+async function snapshotAllowsStaleFallback(snapshot, options) {
+  if (!snapshotMatchesCollectionScope(snapshot, collectionScope(options))) {
+    return false;
+  }
+  const { codexHomeFingerprint } = await import(
+    "../lib/token-ledger-ledger.mjs"
+  );
+  return primitiveString(
+    snapshot.metadata?.durableLedger?.codexHomeFingerprint,
+  ) === codexHomeFingerprint(options.codexHome);
+}
+
+function snapshotWithUnavailableUntrustedQuota(snapshot, force = false) {
+  if (!force && snapshotHasCurrentQuotaIdentityContract(snapshot)) return snapshot;
+  return {
+    ...snapshot,
+    coverage: {
+      ...snapshot.coverage,
+      quotaMeterUnavailableReason: "quota-contract-unverified",
+    },
+    quotaObservations: [],
+  };
+}
+
+async function snapshotAndLedgerHaveCurrentQuotaContract(snapshot, options) {
+  if (!snapshotHasCurrentQuotaIdentityContract(snapshot)) return false;
+  const {
+    readDurableLedgerCacheState,
+    resolveDurableLedgerPath,
+  } = await import("../lib/token-ledger-ledger.mjs");
+  const ledgerState = await readDurableLedgerCacheState(
+    resolveDurableLedgerPath({
+      codexHome: options.codexHome,
+      output: options.input,
+    }),
+  );
+  return ledgerState?.quotaIdentityContract ===
+    QUOTA_IDENTITY_CONTRACT_VERSION;
+}
+
 async function refreshSnapshot(options) {
   if (!existsSync(options.codexHome)) {
     throw new Error(
@@ -889,25 +1129,42 @@ async function refreshSnapshot(options) {
   }
   let progressStarted = false;
   try {
-    const { collectUsage } = await import(
+    const {
+      collectUsage,
+      sourceInventory,
+      sourceWatermarksEqual,
+    } = await import(
       "../lib/token-ledger-importer.mjs"
     );
     process.stderr.write("Token Ledger: refreshing local snapshot…\n");
     progressStarted = true;
+    let writeResult = null;
     const snapshot = await collectUsage(
       {
         output: options.input,
         codexHome: options.codexHome,
         includeArchived: options.includeArchived,
-        since: null,
+        since: options.since,
+        stageSnapshot: async (candidate) => {
+          writeResult = await stagePrivateSnapshot(
+            options.input,
+            candidate,
+            options.snapshotWriteOptions,
+          );
+          return writeResult;
+        },
       },
       ({ current, total }) => {
         process.stderr.write(`\rToken Ledger: scanned ${current}/${total} rollout files`);
       },
     );
     process.stderr.write("\n");
-    const writeResult = await writePrivateSnapshot(options.input, snapshot);
-    const storedSnapshot = writeResult.snapshot;
+    const storedSnapshot = snapshot;
+    if (storedSnapshot.coverage.filesReused > 0) {
+      process.stderr.write(
+        `Token Ledger: reused ${storedSnapshot.coverage.filesReused.toLocaleString()} unchanged rollout files from the durable ledger.\n`,
+      );
+    }
     process.stderr.write(
       `Token Ledger: cached ${(writeResult.bytesWritten / 1_000_000).toFixed(1)} MB ${writeResult.encoding} snapshot (${(writeResult.jsonBytes / 1_000_000).toFixed(1)} MB JSON before encoding; ${storedSnapshot.events.length.toLocaleString()} buckets for ${storedSnapshot.coverage.observedModelCalls.toLocaleString()} calls; ${(writeResult.maxBytes / 1_000_000).toFixed(1)} MB limit).\n`,
     );
@@ -916,23 +1173,163 @@ async function refreshSnapshot(options) {
         "Token Ledger: snapshot is above 70% of its safety limit; older buckets will compact automatically as it grows.\n",
       );
     }
-    return storedSnapshot;
+    let sourceStatus = "unchecked-cache";
+    try {
+      const currentInventory = await sourceInventory(
+        options.codexHome,
+        options.includeArchived,
+      );
+      sourceStatus = refreshedSnapshotSourceStatus(
+        storedSnapshot.sourceWatermark,
+        currentInventory.watermark,
+        sourceWatermarksEqual,
+      );
+    } catch (error) {
+      if (!postRefreshStatusAllowsUnchecked(error)) throw error;
+    }
+    return {
+      snapshot: storedSnapshot,
+      sourceStatus,
+    };
   } catch (error) {
     if (progressStarted) process.stderr.write("\n");
     if (error?.code === "ERR_SNAPSHOT_SIZE_LIMIT" && existsSync(options.input)) {
-      process.stderr.write(
-        "Token Ledger: refresh exceeded the safety limit; continuing with the previous cache, which may be stale.\n",
-      );
-      return readSnapshot(options.input);
+      try {
+        const previous = await readSnapshot(options.input);
+        if (await snapshotAllowsStaleFallback(previous, options)) {
+          const quotaContractTrusted =
+            await snapshotAndLedgerHaveCurrentQuotaContract(
+              previous,
+              options,
+            );
+          process.stderr.write(
+            "Token Ledger: refresh exceeded the safety limit; continuing with the previous cache, which may be stale.\n",
+          );
+          return {
+            snapshot: snapshotWithUnavailableUntrustedQuota(
+              previous,
+              !quotaContractTrusted,
+            ),
+            sourceStatus: "stale-fallback",
+          };
+        }
+      } catch {
+        // Preserve the original refresh error when the previous cache cannot
+        // prove its exact collection scope and Codex-home identity.
+      }
     }
-    throw new Error(
+    const wrapped = new Error(
       `Could not refresh local snapshot: ${safeErrorMessage(error, [options.input, options.codexHome])}`,
+      { cause: error },
     );
+    wrapped.code = error?.code;
+    throw wrapped;
   }
 }
 
-export function snapshotNeedsRefresh(snapshotMtimeMs, latestJsonlMtimeMs) {
-  return latestJsonlMtimeMs > snapshotMtimeMs;
+export function refreshedSnapshotSourceStatus(
+  snapshotWatermark,
+  currentWatermark,
+  watermarksEqual,
+) {
+  return watermarksEqual(snapshotWatermark, currentWatermark)
+    ? "verified-current"
+    : "unchecked-cache";
+}
+
+export function postRefreshStatusAllowsUnchecked(error) {
+  return ["ENOENT", "ENOTDIR"].includes(primitiveString(error?.code));
+}
+
+const RECOVERABLE_REFRESH_ERROR_CODES = new Set([
+  "ERR_SNAPSHOT_SIZE_LIMIT",
+  "ERR_SOURCE_CHANGED_DURING_COLLECTION",
+  "SQLITE_BUSY",
+  "SQLITE_LOCKED",
+]);
+const RECOVERABLE_SQLITE_ERROR_CODES = new Set([5, 6]);
+const RECOVERABLE_SQLITE_ERROR_NAMES = new Set([
+  "SQLITE_BUSY",
+  "SQLITE_LOCKED",
+]);
+const HARD_SQLITE_ERROR_CODES = new Set([11, 26]);
+const HARD_SQLITE_ERROR_NAMES = new Set([
+  "SQLITE_CORRUPT",
+  "SQLITE_NOTADB",
+]);
+
+export function refreshFailureAllowsStaleFallback(error) {
+  const seen = new Set();
+  let recoverable = false;
+  let current = error;
+  while (current instanceof Error) {
+    if (seen.has(current)) return false;
+    seen.add(current);
+    const code = primitiveString(current.code);
+    if (RECOVERABLE_REFRESH_ERROR_CODES.has(code)) recoverable = true;
+    if (
+      code?.startsWith("ERR_DURABLE_LEDGER_") ||
+      (
+        code?.startsWith("ERR_SNAPSHOT_") &&
+        code !== "ERR_SNAPSHOT_SIZE_LIMIT"
+      ) ||
+      code === "ERR_BUFFER_TOO_LARGE" ||
+      HARD_SQLITE_ERROR_NAMES.has(code)
+    ) {
+      return false;
+    }
+    if (code === "ERR_SQLITE_ERROR") {
+      if (RECOVERABLE_SQLITE_ERROR_CODES.has(Number(current.errcode))) {
+        recoverable = true;
+      }
+      if (HARD_SQLITE_ERROR_CODES.has(Number(current.errcode))) {
+        return false;
+      }
+      const name = primitiveString(current.errstr)?.toUpperCase();
+      if (RECOVERABLE_SQLITE_ERROR_NAMES.has(name)) recoverable = true;
+      if (HARD_SQLITE_ERROR_NAMES.has(name)) return false;
+    }
+    current = current.cause;
+  }
+  return recoverable;
+}
+
+async function refreshSnapshotOrUseStaleFallback(
+  options,
+  cached,
+  { quotaContractTrusted = true } = {},
+) {
+  try {
+    const refreshed = await refreshSnapshot(options);
+    if (
+      refreshed.sourceStatus === "stale-fallback" &&
+      !quotaContractTrusted
+    ) {
+      return {
+        ...refreshed,
+        snapshot: snapshotWithUnavailableUntrustedQuota(
+          refreshed.snapshot,
+          true,
+        ),
+      };
+    }
+    return refreshed;
+  } catch (error) {
+    // Default to surfacing refresh failures. Only bounded cache growth, source
+    // races, and SQLite lock contention are safe reasons to reuse known-good
+    // cached data; migration, schema, corruption, and unknown failures are not.
+    if (
+      !refreshFailureAllowsStaleFallback(error) ||
+      !(await snapshotAllowsStaleFallback(cached, options))
+    ) throw error;
+    return {
+      snapshot: snapshotWithUnavailableUntrustedQuota(
+        cached,
+        !quotaContractTrusted,
+      ),
+      sourceStatus: "stale-fallback",
+    };
+  }
 }
 
 export function snapshotCacheIsFresh(
@@ -947,6 +1344,14 @@ export function snapshotCacheIsFresh(
   );
 }
 
+export function shouldCheckSourceFreshness(
+  options = {},
+) {
+  // The source manifest is cheap to stat and is the cache's validity anchor.
+  // The full collector only runs when the persisted watermark changes.
+  return options.autoRefresh !== false && options.inputExplicit !== true;
+}
+
 function snapshotAgeLabel(ageMs) {
   if (ageMs < 60 * 1_000) return "now";
   const minutes = Math.floor(ageMs / (60 * 1_000));
@@ -981,7 +1386,10 @@ export function snapshotFreshness(snapshot = {}, nowMs = Date.now()) {
   };
 }
 
-async function loadSnapshot(options) {
+// Resolve the snapshot together with the evidence available for its report
+// cutoff. A cache can be readable without being current, so callers must keep
+// this status separate from the age label shown in terminal output.
+export async function loadSnapshot(options) {
   if (options.refresh) {
     return refreshSnapshot(options);
   }
@@ -993,26 +1401,31 @@ async function loadSnapshot(options) {
     }
     return refreshSnapshot(options);
   }
-  if (!options.autoRefresh || options.inputExplicit) {
-    return readSnapshot(options.input);
+  const cached = await readSnapshot(options.input);
+  if (!snapshotScopeMatchesOptions(cached, options)) {
+    if (options.inputExplicit || !options.autoRefresh) {
+      throw snapshotScopeError(cached, options);
+    }
+    return refreshSnapshot(options);
   }
 
-  let snapshotStat;
-  try {
-    snapshotStat = await stat(options.input);
-  } catch (error) {
-    throw new Error(
-      `Could not inspect snapshot ${safeDisplayLabel(options.input, "snapshot")}: ${safeErrorMessage(error, [options.input])}`,
-    );
+  if (options.inputExplicit) {
+    return { snapshot: cached, sourceStatus: "explicit-snapshot" };
+  }
+  if (!options.autoRefresh) {
+    return { snapshot: cached, sourceStatus: "unchecked-cache" };
   }
-  if (snapshotCacheIsFresh(snapshotStat.mtimeMs)) {
-    return readSnapshot(options.input);
+
+  if (!shouldCheckSourceFreshness(options)) {
+    return { snapshot: cached, sourceStatus: "unchecked-cache" };
   }
 
-  const { latestSourceModifiedAt } = await import("../lib/token-ledger-importer.mjs");
-  let latestSourceMtimeMs;
+  const { sourceInventory, sourceWatermarksEqual } = await import(
+    "../lib/token-ledger-importer.mjs"
+  );
+  let inventory;
   try {
-    latestSourceMtimeMs = await latestSourceModifiedAt(
+    inventory = await sourceInventory(
       options.codexHome,
       options.includeArchived,
     );
@@ -1021,24 +1434,91 @@ async function loadSnapshot(options) {
       `Could not inspect local Codex source: ${safeErrorMessage(error, [options.codexHome])}`,
     );
   }
-  if (snapshotNeedsRefresh(snapshotStat.mtimeMs, latestSourceMtimeMs)) {
+  const {
+    codexHomeFingerprint,
+    readDurableLedgerCacheState,
+    resolveDurableLedgerPath,
+  } = await import("../lib/token-ledger-ledger.mjs");
+  const cachedCodexHomeFingerprint = primitiveString(
+    cached.metadata?.durableLedger?.codexHomeFingerprint,
+  );
+  if (
+    cachedCodexHomeFingerprint !== codexHomeFingerprint(options.codexHome)
+  ) {
     return refreshSnapshot(options);
   }
-  return readSnapshot(options.input);
+  const ledgerState = await readDurableLedgerCacheState(
+    resolveDurableLedgerPath({
+      codexHome: options.codexHome,
+      output: options.input,
+    }),
+  );
+  const quotaContractTrusted =
+    ledgerState?.quotaIdentityContract === QUOTA_IDENTITY_CONTRACT_VERSION &&
+    snapshotHasCurrentQuotaIdentityContract(cached);
+  if (!sourceWatermarksEqual(cached.sourceWatermark, inventory.watermark)) {
+    return refreshSnapshotOrUseStaleFallback(options, cached, {
+      quotaContractTrusted,
+    });
+  }
+  const snapshotRevision = Number(
+    cached.metadata?.durableLedger?.revision,
+  );
+  if (
+    !Number.isSafeInteger(snapshotRevision) ||
+    ledgerState?.revision !== snapshotRevision
+  ) {
+    return refreshSnapshotOrUseStaleFallback(options, cached, {
+      quotaContractTrusted,
+    });
+  }
+  if (!quotaContractTrusted) {
+    return refreshSnapshotOrUseStaleFallback(options, cached, {
+      quotaContractTrusted: false,
+    });
+  }
+  return { snapshot: cached, sourceStatus: "verified-current" };
 }
 
-function render(options, snapshot, bounds, events, rows, allRows, freshness) {
+async function render(
+  options,
+  snapshot,
+  bounds,
+  events,
+  rows,
+  allRows,
+  freshness,
+  report = {},
+  analysis,
+) {
+  if (options.view === "cost") {
+    return renderCostTerminal({
+      events,
+      bounds,
+      basis: options.basis,
+      snapshotFreshness: freshness,
+      sourceStatus: report.sourceStatus ?? "unchecked-cache",
+    });
+  }
   if (options.view === "trend") {
     if (options.image && options.cacheRate) {
+      const { renderCacheReportImage } = await import(
+        "./token-ledger-cache-image.mjs"
+      );
       return renderCacheReportImage({
         snapshot,
         bounds,
         days: options.trendDays,
         options,
+        analysis,
+        sourceStatus: report.sourceStatus ?? "unchecked-cache",
       });
     }
-    const trend = buildUsageTrend(snapshot, bounds);
+    const trend = buildUsageTrend(snapshot, bounds, { analysis });
     if (options.image) {
+      const { renderTrendImage } = await import(
+        "./token-ledger-trend-image.mjs"
+      );
       return renderTrendImage({
         snapshot,
         bounds,
@@ -1046,6 +1526,10 @@ function render(options, snapshot, bounds, events, rows, allRows, freshness) {
         days: options.trendDays,
         options,
         projectRows: allRows,
+        reportTimeMs: report.reportTimeMs ?? null,
+        sourceStatus: report.sourceStatus ?? "unchecked-cache",
+        analysis,
+        reportEvents: events,
       });
     }
     return renderTrendCombo({
@@ -1054,6 +1538,9 @@ function render(options, snapshot, bounds, events, rows, allRows, freshness) {
       trend,
       days: options.trendDays,
       options,
+      analysis,
+      snapshotFreshness: freshness,
+      sourceStatus: report.sourceStatus ?? "unchecked-cache",
     });
   }
   if (!options.legacyPlot) {
@@ -1061,6 +1548,7 @@ function render(options, snapshot, bounds, events, rows, allRows, freshness) {
       options,
       snapshot,
       snapshotFreshness: freshness,
+      sourceStatus: report.sourceStatus ?? "unchecked-cache",
       bounds,
       events,
       rows,
@@ -1068,35 +1556,38 @@ function render(options, snapshot, bounds, events, rows, allRows, freshness) {
     });
   }
   const enabled = !options.plain && !process.env.NO_COLOR && Boolean(process.stdout.isTTY);
-  const summary = totalSummary(events);
+  const summary = totalSummary(events, allRows);
   const totalTokens = summary.totalTokens;
   const dateLabel = options.range === "rolling24h"
     ? "last 24 hours"
     : options.range === "rolling"
       ? `last ${options.rollingLabel}`
       : options.range === "week"
-      ? `${bounds.startDateString} through ${bounds.endDateString}`
-      : new Intl.DateTimeFormat("en-US", {
-        timeZone: bounds.timeZone,
-        weekday: "short",
-        month: "short",
-        day: "numeric",
-        year: "numeric",
-      }).format(bounds.start);
+        ? `${bounds.startDateString} through ${bounds.endDateString}`
+        : formatCalendarDate(bounds.dateString, {
+          weekday: "short",
+          month: "short",
+          day: "numeric",
+          year: "numeric",
+        });
   const unit = chartUnit(rows[0]?.totalTokens ?? 0);
   const shares = rows.map((row) =>
     totalTokens > 0 ? (row.totalTokens / totalTokens) * 100 : 0,
   );
   const chart = runYouPlot(rows, options, dateLabel, unit).trimEnd();
+  const historyScope = historyScopeLabel(snapshot);
 
   const header = [
     `Token Ledger · ${dateLabel} · ${bounds.timeZone}`,
     `${compact(totalTokens)} tokens · ${summary.threadIds.size.toLocaleString()} threads · ${summary.calls.toLocaleString()} calls · ${compact(summary.outputTokens)} output`,
+    ...(historyScope ? [`History: ${historyScope}`] : []),
+    `Snapshot: ${snapshotFreshnessDetail(freshness)}`,
+    sourceStatusLine(report.sourceStatus ?? "unchecked-cache"),
     `Source: ${sourceLabel(options.input, snapshot)}`,
     "",
     chart,
     "",
-    `Model mix · colors: ${colorize("Sol", MODEL_COLORS.sol, enabled)}  ${colorize("Luna", MODEL_COLORS.luna, enabled)}  ${colorize("Terra", MODEL_COLORS.terra, enabled)}  ${colorize("GPT", MODEL_COLORS["gpt-5.5"], enabled)}  ${colorize("Other", MODEL_COLORS.other, enabled)}`,
+    `Model mix · colors: ${colorize("Astra", MODEL_COLORS.astra, enabled)}  ${colorize("Sol", MODEL_COLORS.sol, enabled)}  ${colorize("Luna", MODEL_COLORS.luna, enabled)}  ${colorize("Terra", MODEL_COLORS.terra, enabled)}  ${colorize("GPT", MODEL_COLORS["gpt-5.5"], enabled)}  ${colorize("Other", MODEL_COLORS.other, enabled)}`,
   ];
 
   const details = rows.map((row, index) => {
@@ -1104,7 +1595,7 @@ function render(options, snapshot, bounds, events, rows, allRows, freshness) {
       summary.rateCardCredits > 0 && row.rateCardCredits > 0
         ? ` · ${percent((row.rateCardCredits / summary.rateCardCredits) * 100)} credits`
         : "";
-    return `${String(index + 1).padStart(2, " ")}  ${row.displayProject} · ${compact(row.totalTokens)} · ${percent(shares[index])} · ${row.threads.toLocaleString()} threads${knownCreditShare}\n    ${modelMix(row, enabled)}`;
+    return `${String(index + 1).padStart(2, " ")}  ${sanitizeTerminalText(row.displayProject)} · ${compact(row.totalTokens)} · ${percent(shares[index])} · ${row.threads.toLocaleString()} threads${knownCreditShare}\n    ${modelMix(row, enabled)}`;
   });
 
   return `${header.join("\n")}\n\n${details.join("\n")}`;
@@ -1136,29 +1627,85 @@ function rangeDescription(options, bounds) {
   return bounds.dateString;
 }
 
+function emptyRangeMessage(
+  options,
+  snapshot,
+  bounds,
+  {
+    sourceStatus = "unchecked-cache",
+    reportTimeMs = Date.now(),
+  } = {},
+) {
+  const range = rangeDescription(options, bounds);
+  const cutoffMs = snapshotCollectionCutoffMs(snapshot);
+  const hasUncollectedHistory =
+    Number.isFinite(cutoffMs) && bounds.start.getTime() < cutoffMs;
+  const lines = [
+    hasUncollectedHistory
+      ? `No model-call events were collected for ${range} (${bounds.timeZone}); history before the snapshot cutoff is outside this snapshot and is not a verified zero.`
+      : `No model-call events found for ${range} (${bounds.timeZone}).`,
+  ];
+  const scope = historyScopeLabel(snapshot);
+  if (scope) lines.push(`History: ${scope}`);
+  lines.push(
+    `Snapshot: ${snapshotFreshnessDetail(snapshotFreshness(snapshot, reportTimeMs))}`,
+  );
+  lines.push(sourceStatusLine(sourceStatus));
+  lines.push(`Source: ${sourceLabel(options.input, snapshot)}`);
+  return lines.join("\n");
+}
+
 export async function run(options, { nowMs } = {}) {
   const hasInjectedNow = nowMs !== undefined;
   const now = new Date(hasInjectedNow ? nowMs : Date.now());
+  const reportTimeMs = now.getTime();
   const bounds = boundsForOptions(options, now);
-  const snapshot = await loadSnapshot(options);
-  const events = filterDayEvents(snapshot, bounds);
+  const { snapshot, sourceStatus } = await loadSnapshot(options);
+  const freshnessNowMs = hasInjectedNow ? reportTimeMs : Date.now();
+  const analysis = buildRangeAnalysis(
+    snapshot,
+    bounds,
+    {
+      priorBounds: options.view === "trend"
+        ? priorPeriodBounds(bounds, options.trendDays)
+        : null,
+      includeTrend: options.view === "trend" && !options.cacheRate,
+    },
+  );
+  let events = filterDayEvents(snapshot, bounds, analysis);
   const writingImage = options.view === "trend" && options.image;
   const writingEmptyCacheReport = writingImage && options.cacheRate;
+  if (writingImage && !options.cacheRate) {
+    const effectiveEndMs = resolveEffectiveEnd({
+      snapshot,
+      bounds,
+      reportTimeMs,
+      sourceStatus,
+    });
+    // Keep the terminal aggregation and the report's project breakdown on the
+    // same captured event window. The report view model independently applies
+    // the same bound to raw snapshot events for its other panels.
+    events = usageBucketsInRange(
+      { events },
+      bounds.start.getTime(),
+      effectiveEndMs,
+    );
+  }
   if (events.length === 0 && !writingEmptyCacheReport) {
-    return [
-      `No model-call events found for ${rangeDescription(options, bounds)} (${bounds.timeZone}).`,
-      `Source: ${sourceLabel(options.input, snapshot)}`,
-    ].join("\n");
+    return emptyRangeMessage(options, snapshot, bounds, {
+      sourceStatus,
+      reportTimeMs,
+    });
   }
-  const allRows = options.cacheRate
+  const allRows = options.cacheRate || options.view === "cost"
     ? []
-    : aggregateProjects(snapshot, events, options);
+    : aggregateProjects(snapshot, events, options, analysis);
   const rows = allRows.slice(0, options.top);
   const outputPath = writingImage
     ? options.imageOutput ??
       resolve(
         process.cwd(),
-        `token-ledger-${options.cacheRate ? "cache-report" : options.report ? "report" : "trend"}-${options.trendDays}d.png`,
+        `token-ledger-${options.cacheRate ? "cache-report" : options.report ? "report" : "trend"}-${options.trendDays}d${options.private ? "-private" : ""}.png`,
       )
     : null;
   const imageLabel = options.cacheRate
@@ -1169,7 +1716,7 @@ export async function run(options, { nowMs } = {}) {
   if (writingImage) {
     process.stderr.write(`Token Ledger: generating ${imageLabel} PNG…\n`);
   }
-  const output = render(
+  const output = await render(
     options,
     snapshot,
     bounds,
@@ -1178,12 +1725,15 @@ export async function run(options, { nowMs } = {}) {
     allRows,
     snapshotFreshness(
       snapshot,
-      hasInjectedNow ? now.getTime() : Date.now(),
+      freshnessNowMs,
     ),
+    { sourceStatus, reportTimeMs },
+    analysis,
   );
   if (writingImage) {
     await mkdir(dirname(outputPath), { recursive: true });
     process.stderr.write(`Token Ledger: encoding ${imageLabel} PNG…\n`);
+    const { writeTrendPng } = await import("./token-ledger-trend-image.mjs");
     await writeTrendPng(output, outputPath);
     process.stderr.write(`Token Ledger: finished ${imageLabel} PNG.\n`);
     const lines = [
@@ -1220,6 +1770,7 @@ function shouldUseInteractive(options) {
   return Boolean(
     !options.static &&
       options.view !== "trend" &&
+      options.view !== "cost" &&
       !options.plain &&
       !options.legacyPlot &&
       !process.env.NO_COLOR &&
@@ -1230,21 +1781,23 @@ function shouldUseInteractive(options) {
 
 async function runInteractive(options) {
   const bounds = boundsForOptions(options);
-  const snapshot = await loadSnapshot(options);
-  const events = filterDayEvents(snapshot, bounds);
+  const { snapshot, sourceStatus } = await loadSnapshot(options);
+  const reportTimeMs = Date.now();
+  const analysis = buildRangeAnalysis(snapshot, bounds, { includeTrend: false });
+  const events = filterDayEvents(snapshot, bounds, analysis);
   if (events.length === 0) {
-    process.stdout.write([
-      `No model-call events found for ${rangeDescription(options, bounds)} (${bounds.timeZone}).`,
-      `Source: ${sourceLabel(options.input, snapshot)}`,
-      "",
-    ].join("\n"));
+    process.stdout.write(`${emptyRangeMessage(options, snapshot, bounds, {
+      sourceStatus,
+      reportTimeMs,
+    })}\n`);
     return;
   }
-  const allRows = aggregateProjects(snapshot, events, options);
+  const allRows = aggregateProjects(snapshot, events, options, analysis);
   await startInteractive({
     options,
     snapshot,
-    snapshotFreshness: snapshotFreshness(snapshot),
+    snapshotFreshness: snapshotFreshness(snapshot, reportTimeMs),
+    sourceStatus,
     bounds,
     events,
     rows: allRows.slice(0, options.top),