tledger 0.2.0 → 0.3.0

package/bin/token-ledger.mjs

@@ -4,7 +4,6 @@ import { spawnSync } from "node:child_process";
 import { existsSync, realpathSync } from "node:fs";
 import {
   mkdir,
-  readFile,
   stat,
 } from "node:fs/promises";
 import { homedir } from "node:os";
@@ -20,17 +19,32 @@ import {
   renderTrendImage,
   writeTrendPng,
 } from "./token-ledger-trend-image.mjs";
+import { renderCacheReportImage } from "./token-ledger-cache-image.mjs";
 import { renderTrendCombo } from "./token-ledger-trend-terminal.mjs";
 import { startInteractive } from "./token-ledger-tui.mjs";
+import {
+  readPrivateSnapshot,
+  writePrivateSnapshot,
+} from "../lib/token-ledger-snapshot.mjs";
+import {
+  SNAPSHOT_SCHEMA_VERSION,
+  usageBuckets,
+  usageBucketsInRange,
+  usageCallCount,
+  usageThreadIds,
+} from "../lib/token-ledger-usage.mjs";
 
 export const DEFAULT_SNAPSHOT = resolve(
   homedir(),
   ".token-ledger",
-  "token-ledger-snapshot.json",
+  "token-ledger-snapshot-v2.json.gz",
 );
 const DEFAULT_TOP = 10;
 const DEFAULT_TIME_ZONE = Intl.DateTimeFormat().resolvedOptions().timeZone;
 export const SNAPSHOT_CACHE_MAX_AGE_MS = 60 * 60 * 1000;
+export const ROLLING_24_HOURS_MS = 24 * 60 * 60 * 1000;
+const MAX_ROLLING_DAYS = 3_650;
+const DURATION_ALIAS = /^(\d+)(d|w)$/i;
 const ANSI_RESET = "\u001b[0m";
 const MODEL_COLORS = {
   sol: TERMINAL_MODEL_COLORS.sol,
@@ -41,44 +55,111 @@ const MODEL_COLORS = {
   other: TERMINAL_MODEL_COLORS.other,
 };
 
-function usage() {
-  return `Token Ledger terminal usage
+export function usage() {
+  return `Token Ledger
 
 Usage:
-  tledger day <YYYY-MM-DD>
-  tledger week [end-day]
-  tledger trend [7d|14d|30d]
-  tledger report [7d|14d|30d]
-  npm run usage:day -- <YYYY-MM-DD>
-  npm run usage:week -- [end-day]
-
-Options:
-  --date <day>         Date as YYYY-MM-DD, today, or yesterday
-  --period <window>    Trend window: 7d, 14d, or 30d
-  --input <file>       Snapshot to read (default: ~/.token-ledger/token-ledger-snapshot.json)
-  --refresh            Rebuild the default snapshot from CODEX_HOME or ~/.codex
-  --no-refresh         Use the cached snapshot without checking local JSONL files
-  --codex-home <dir>   Codex data root used when refreshing
-  --tz <name>          IANA timezone (default: machine timezone)
-  --top <number>       Number of projects to show (default: 10)
-  --width <number>     Terminal layout width in columns
-  --raw-projects       Keep singleton thread labels instead of grouping them
-  --no-archived        Skip archived_sessions when refreshing
-  --plain              Disable terminal colors
-  --ascii              Use ASCII bars instead of Unicode blocks
-  --static             Print once instead of opening the interactive dashboard
-  --drain               Trend columns show observed limit drain percent instead of token volume
-  --image               Write trend view as a PNG image
-  --image-output <file> PNG output path for trend view
-  --image-width <px>   PNG image width from 900 to 2400 pixels
-  --youplot            Use the legacy single-series YouPlot renderer
-  --help               Show this help
-
-The report command writes the dashboard PNG (same as trend --image) to
-token-ledger-report-<period>.png; use --image-output to choose the path.
-
-The command reads a privacy-reduced Token Ledger snapshot. It never uploads
-the snapshot or prints message bodies, tool payloads, credentials, or paths.`;
+  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 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
+  --image-output <file>     Choose where to save a PNG
+  --no-open                 Do not open a generated PNG
+  -h, --help                Show this quick guide
+  --help-all                Show every command and option
+
+Token Ledger reads local Codex data only. It does not upload your usage.`;
+}
+
+export function advancedUsage() {
+  return `Token Ledger command reference
+
+Terminal commands:
+  tledger 1d                         Rolling 24-hour project breakdown
+  tledger <N>d                       Rolling N-day project breakdown
+  tledger <N>w                       Rolling N-week project breakdown
+  tledger day <YYYY-MM-DD>           One local calendar day
+  tledger week [end-day]             Seven local calendar days
+  tledger trend [Nd|Nw]              Multi-day terminal trend
+
+Report commands:
+  tledger report [Nd|Nw]             Write the usage dashboard PNG
+  tledger report [Nd|Nw] --cache-rate
+                                      Write the cache-only PNG
+
+Dates and ranges:
+  --date <day>               YYYY-MM-DD, today, or yesterday
+  --period <window>          Trend window such as 7d, 14d, or 2w
+  --tz <name>                IANA timezone (default: machine timezone)
+
+Data and refresh:
+  --input <file>             Read an explicit snapshot
+  --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
+  --no-archived              Skip archived sessions when refreshing
+
+Terminal output:
+  --top <number>             Projects to show, from 1 to 100 (default: 10)
+  --width <number>           Layout width, from 40 to 200 columns
+  --raw-projects             Keep singleton thread labels ungrouped
+  --plain                    Disable terminal colors
+  --ascii                    Use ASCII bars instead of Unicode blocks
+  --static                   Print once instead of opening the dashboard
+  --youplot                  Use the legacy single-series renderer
+
+Report output:
+  --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
+  --image-output <file>      Choose the PNG output path
+  --image-width <px>         Set PNG width from 900 to 2400 pixels
+  --no-open                  Do not open the finished PNG
+
+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.
+Token Ledger reads local Codex data only. It does not upload your usage.`;
+}
+
+function durationAlias(value) {
+  const match = DURATION_ALIAS.exec(String(value ?? ""));
+  if (!match) return null;
+  const amount = Number(match[1]);
+  const unit = match[2].toLowerCase();
+  const days = unit === "w" ? amount * 7 : amount;
+  if (
+    !Number.isSafeInteger(amount) ||
+    !Number.isSafeInteger(days) ||
+    amount < 1 ||
+    days > MAX_ROLLING_DAYS
+  ) {
+    throw new Error(
+      `Duration must be between 1d and ${MAX_ROLLING_DAYS}d (or the equivalent in weeks).`,
+    );
+  }
+  const noun = unit === "w"
+    ? amount === 1 ? "week" : "weeks"
+    : amount === 1 ? "day" : "days";
+  return {
+    amount,
+    unit,
+    days,
+    label: `${amount} ${noun}`,
+  };
+}
+
+function rollingRangeDescription(options) {
+  return options.range === "rolling24h"
+    ? "the last 24 hours"
+    : `the last ${options.rollingLabel}`;
 }
 
 function readOption(argv, index, name) {
@@ -90,14 +171,28 @@ function readOption(argv, index, name) {
 }
 
 export function parseArgs(argv) {
-  const command = argv[0] === "week"
-    ? "week"
-    : argv[0] === "trend" || argv[0] === "report"
-      ? "trend"
-      : "day";
+  const helpCommand = argv[0] === "help";
+  const alias = durationAlias(argv[0]);
+  const rolling24hCommand = argv[0] === "1d";
+  const rollingDurationCommand = Boolean(alias) && !rolling24hCommand;
+  const command = rolling24hCommand
+    ? "rolling24h"
+    : rollingDurationCommand
+      ? "rolling"
+    : argv[0] === "week"
+      ? "week"
+      : argv[0] === "trend" || argv[0] === "report"
+        ? "trend"
+        : "day";
   const options = {
     range: command,
     view: 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",
     report: argv[0] === "report",
     trendDays: 7,
     date: null,
@@ -117,17 +212,23 @@ export function parseArgs(argv) {
     image: false,
     imageOutput: null,
     imageWidth: null,
+    openImage: true,
     drain: false,
+    cacheRate: false,
     legacyPlot: false,
-    help: false,
+    help: argv.length === 0 || helpCommand,
+    helpAll: false,
   };
 
   let trendPeriodSeen = false;
-  let index = ["day", "week", "trend", "report"].includes(argv[0]) ? 1 : 0;
+  let index = 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") {
       options.help = true;
+    } else if (argument === "--help-all") {
+      options.help = true;
+      options.helpAll = true;
     } else if (argument === "--date") {
       options.date = readOption(argv, index, "--date");
       index += 1;
@@ -139,10 +240,13 @@ export function parseArgs(argv) {
         throw new Error("Trend period can only be specified once.");
       }
       const value = readOption(argv, index, "--period");
-      if (!["7d", "14d", "30d"].includes(value)) {
-        throw new Error("Trend period must be 7d, 14d, or 30d.");
+      const period = durationAlias(value);
+      if (!period) {
+        throw new Error(
+          "Trend period must use a positive number of days or weeks, such as 7d or 2w.",
+        );
       }
-      options.trendDays = Number.parseInt(value, 10);
+      options.trendDays = period.days;
       trendPeriodSeen = true;
       index += 1;
     } else if (argument === "--input") {
@@ -188,11 +292,21 @@ export function parseArgs(argv) {
         throw new Error("--drain is only available for the trend view.");
       }
       options.drain = true;
+    } else if (argument === "--cache-rate") {
+      if (!options.report) {
+        throw new Error("--cache-rate is only available with the report command.");
+      }
+      options.cacheRate = true;
     } else if (argument === "--image") {
       if (options.view !== "trend") {
         throw new Error("--image is only available for the trend view.");
       }
       options.image = true;
+    } else if (argument === "--no-open") {
+      if (options.view !== "trend") {
+        throw new Error("--no-open is only available for the trend view.");
+      }
+      options.openImage = false;
     } else if (argument === "--image-output") {
       if (options.view !== "trend") {
         throw new Error("--image-output is only available for the trend view.");
@@ -217,14 +331,30 @@ export function parseArgs(argv) {
       index += 1;
     } else if (argument === "--youplot") {
       options.legacyPlot = true;
+    } else if (
+      !argument.startsWith("-") &&
+      options.view === "projects" &&
+      argument === "1d" &&
+      !options.date
+    ) {
+      if (argv[0] !== "day") {
+        throw new Error(
+          "The 1d alias is only available as `tledger 1d` or `tledger day 1d`.",
+        );
+      }
+      options.range = "rolling24h";
+      options.rolling24h = true;
     } else if (!argument.startsWith("-") && options.view === "trend") {
       if (trendPeriodSeen) {
         throw new Error("Trend period can only be specified once.");
       }
-      if (!["7d", "14d", "30d"].includes(argument)) {
-        throw new Error("Trend period must be 7d, 14d, or 30d.");
+      const period = durationAlias(argument);
+      if (!period) {
+        throw new Error(
+          "Trend period must use a positive number of days or weeks, such as 7d or 2w.",
+        );
       }
-      options.trendDays = Number.parseInt(argument, 10);
+      options.trendDays = period.days;
       trendPeriodSeen = true;
     } else if (!argument.startsWith("-") && !options.date) {
       options.date = argument;
@@ -234,10 +364,13 @@ export function parseArgs(argv) {
   }
 
   if (options.report) options.image = true;
+  if (!options.help && (options.rolling24h || options.rollingDuration) && options.date) {
+    throw new Error(`${options.rollingLabel} does not accept --date; its rolling window ends now.`);
+  }
   if (!options.help && !options.date && (options.range === "week" || options.view === "trend")) {
     options.date = "today";
   }
-  if (!options.help && !options.date) {
+  if (!options.help && !options.date && !options.rolling24h && !options.rollingDuration) {
     throw new Error("A day is required, for example: tledger day 2026-08-01");
   }
   if (!options.help && options.refresh && !options.autoRefresh) {
@@ -249,6 +382,9 @@ 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.cacheRate && options.drain) {
+    throw new Error("--cache-rate cannot be combined with --drain.");
+  }
   return options;
 }
 
@@ -364,6 +500,35 @@ export function weekBounds(value, timeZone) {
   };
 }
 
+export function rollingDurationBounds(
+  value = new Date(),
+  timeZone = DEFAULT_TIME_ZONE,
+  rangeDays = 1,
+) {
+  validateTimeZone(timeZone);
+  const end = value instanceof Date ? new Date(value.getTime()) : new Date(value);
+  if (!Number.isFinite(end.getTime())) {
+    throw new Error("Rolling window requires a valid end time.");
+  }
+  const days = Number(rangeDays);
+  if (!Number.isSafeInteger(days) || days < 1 || days > MAX_ROLLING_DAYS) {
+    throw new Error(
+      `Rolling window must be between 1 and ${MAX_ROLLING_DAYS} days.`,
+    );
+  }
+  return {
+    start: new Date(end.getTime() - days * ROLLING_24_HOURS_MS),
+    end,
+    timeZone,
+    rangeHours: days * 24,
+    rangeDays: days,
+  };
+}
+
+export function rolling24hBounds(value = new Date(), timeZone = DEFAULT_TIME_ZONE) {
+  return rollingDurationBounds(value, timeZone, 1);
+}
+
 export function sanitizeTerminalText(value) {
   return String(value ?? "")
     .replace(/\u001b\][^\u0007]*(?:\u0007|\u001b\\)/g, "")
@@ -378,6 +543,62 @@ function cleanLabel(value, fallback) {
   return label || fallback;
 }
 
+const QUOTED_ABSOLUTE_PATH =
+  /(["'])(\/(?!\/)[^"'\r\n]*|(?:\/\/|\\\\)[^"'\r\n]+|[A-Za-z]:[\\/][^"'\r\n]*)\1/g;
+const UNQUOTED_ABSOLUTE_PATH =
+  /(^|[\s([{=])((?:\/(?!\/)|\/\/|\\\\|[A-Za-z]:[\\/])[^\s"'`)\]},;]+)/g;
+
+function isAbsoluteLocalPath(path) {
+  return (
+    path.startsWith("/") ||
+    path.startsWith("\\\\") ||
+    /^[A-Za-z]:[\\/]/.test(path)
+  );
+}
+
+export function safeDisplayLabel(value, fallback = "local path") {
+  const normalized = String(value ?? "").replaceAll("\\", "/");
+  const label = sanitizeTerminalText(basename(normalized))
+    .replace(/\s+/g, " ")
+    .trim();
+  return label && label !== "." && label !== ".." ? label : fallback;
+}
+
+export function redactLocalPaths(value, paths = []) {
+  let redacted = String(value ?? "");
+  const explicitPaths = new Set(
+    paths
+      .filter(Boolean)
+      .map((path) => String(path))
+      .filter(isAbsoluteLocalPath),
+  );
+  const pathsToRedact = [...new Set([
+    ...explicitPaths,
+    homedir(),
+    process.cwd(),
+  ])]
+    .filter((path) => path && path !== "/")
+    .sort((left, right) => right.length - left.length);
+
+  for (const path of pathsToRedact) {
+    redacted = redacted.replaceAll(
+      path,
+      explicitPaths.has(path) ? safeDisplayLabel(path) : "[local path]",
+    );
+  }
+
+  return redacted
+    .replace(QUOTED_ABSOLUTE_PATH, (_match, quote) => `${quote}[local path]${quote}`)
+    .replace(UNQUOTED_ABSOLUTE_PATH, (_match, prefix) => `${prefix}[local path]`);
+}
+
+function safeErrorMessage(error, paths = []) {
+  return redactLocalPaths(
+    error instanceof Error ? error.message : String(error),
+    paths,
+  );
+}
+
 function displayLabel(value) {
   const label = cleanLabel(value, "Unlabelled activity");
   if (label.length <= 30) return label;
@@ -393,7 +614,9 @@ export function oneOffProjects(snapshot) {
     ids.add(threadId);
     threadIdsByProject.set(normalizedProject, ids);
   };
-  for (const event of snapshot.events ?? []) add(event.project, event.threadId);
+  for (const bucket of usageBuckets(snapshot)) {
+    for (const threadId of usageThreadIds(bucket)) add(bucket.project, threadId);
+  }
   for (const thread of snapshot.threads ?? []) add(thread.project, thread.id);
   return new Set(
     [...threadIdsByProject.entries()]
@@ -416,10 +639,7 @@ function modelLabel(value) {
 export function filterDayEvents(snapshot, bounds) {
   const start = bounds.start.getTime();
   const end = bounds.end.getTime();
-  return (snapshot.events ?? []).filter((event) => {
-    const timestamp = new Date(event.timestamp).getTime();
-    return Number.isFinite(timestamp) && timestamp >= start && timestamp < end;
-  });
+  return usageBucketsInRange(snapshot, start, end);
 }
 
 export function aggregateProjects(snapshot, events, options = {}) {
@@ -450,8 +670,8 @@ export function aggregateProjects(snapshot, events, options = {}) {
     row.outputTokens += Number(event.outputTokens) || 0;
     row.reasoningTokens += Number(event.reasoningTokens) || 0;
     row.toolCalls += Number(event.toolCalls) || 0;
-    row.events += 1;
-    if (event.threadId) row.threadIds.add(event.threadId);
+    row.events += usageCallCount(event);
+    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;
@@ -465,7 +685,7 @@ export function aggregateProjects(snapshot, events, options = {}) {
       rateCardCredits: 0,
     };
     modelRow.totalTokens += Number(event.totalTokens) || 0;
-    modelRow.events += 1;
+    modelRow.events += usageCallCount(event);
     if (event.rateCardCredits !== null && Number.isFinite(Number(event.rateCardCredits))) {
       modelRow.rateCardCredits += Number(event.rateCardCredits);
     }
@@ -495,7 +715,10 @@ function totalSummary(events) {
       summary.totalTokens += Number(event.totalTokens) || 0;
       summary.outputTokens += Number(event.outputTokens) || 0;
       summary.toolCalls += Number(event.toolCalls) || 0;
-      if (event.threadId) summary.threadIds.add(event.threadId);
+      summary.calls += usageCallCount(event);
+      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;
@@ -506,6 +729,7 @@ function totalSummary(events) {
       totalTokens: 0,
       outputTokens: 0,
       toolCalls: 0,
+      calls: 0,
       rateCardCredits: 0,
       knownCreditTokens: 0,
       threadIds: new Set(),
@@ -521,12 +745,18 @@ function compact(value, digits = 2) {
     [1_000_000, "M"],
     [1_000, "K"],
   ];
-  for (const [divisor, suffix] of units) {
-    if (absolute >= divisor) {
-      const scaled = value / divisor;
-      const precision = scaled >= 100 ? 0 : scaled >= 10 ? 1 : digits;
-      return `${scaled.toFixed(precision)}${suffix}`;
+  for (let index = 0; index < units.length; index += 1) {
+    const [divisor, suffix] = units[index];
+    if (absolute < divisor) continue;
+    const scaled = value / divisor;
+    const magnitude = Math.abs(scaled);
+    const precision = magnitude >= 100 ? 0 : magnitude >= 10 ? 1 : digits;
+    // Values that round to 1000 of a unit belong to the next unit up
+    // (999,999 → 1.00M, not 1000K).
+    if (index > 0 && Number(magnitude.toFixed(precision)) >= 1_000) {
+      return compact(Math.sign(value) * divisor * 1_000, digits);
     }
+    return `${scaled.toFixed(precision)}${suffix}`;
   }
   return Math.round(value).toLocaleString("en-US");
 }
@@ -582,7 +812,7 @@ function sourceLabel(snapshotPath, snapshot) {
         timeStyle: "short",
       })
     : "unknown time";
-  return `${basename(snapshotPath)} · captured ${generated}`;
+  return `${safeDisplayLabel(snapshotPath, "snapshot")} · captured ${generated}`;
 }
 
 function runYouPlot(rows, options, dateLabel, unit) {
@@ -627,43 +857,78 @@ function runYouPlot(rows, options, dateLabel, unit) {
 }
 
 async function readSnapshot(snapshotPath) {
+  const snapshotLabel = safeDisplayLabel(snapshotPath, "snapshot");
   let parsed;
   try {
-    parsed = JSON.parse(await readFile(snapshotPath, "utf8"));
+    parsed = await readPrivateSnapshot(snapshotPath);
   } catch (error) {
     if (error?.code === "ENOENT") {
-      throw new Error(`Snapshot not found: ${snapshotPath}`);
+      throw new Error(`Snapshot not found: ${snapshotLabel}`);
     }
-    throw new Error(`Could not read snapshot ${snapshotPath}: ${error.message}`);
+    throw new Error(
+      `Could not read snapshot ${snapshotLabel}: ${safeErrorMessage(error, [snapshotPath])}`,
+    );
   }
-  if (!parsed || !Array.isArray(parsed.events)) {
-    throw new Error(`Snapshot is missing its events array: ${snapshotPath}`);
+  if (
+    !parsed ||
+    parsed.schemaVersion !== SNAPSHOT_SCHEMA_VERSION ||
+    !Array.isArray(parsed.events)
+  ) {
+    throw new Error(
+      `Snapshot uses an unsupported schema: ${snapshotLabel}. Rebuild it with --refresh.`,
+    );
   }
   return parsed;
 }
 
 async function refreshSnapshot(options) {
   if (!existsSync(options.codexHome)) {
-    throw new Error(`Codex data directory not found: ${options.codexHome}`);
+    throw new Error(
+      `Codex data directory not found: ${safeDisplayLabel(options.codexHome, "Codex data directory")}`,
+    );
+  }
+  let progressStarted = false;
+  try {
+    const { collectUsage } = await import(
+      "../lib/token-ledger-importer.mjs"
+    );
+    process.stderr.write("Token Ledger: refreshing local snapshot…\n");
+    progressStarted = true;
+    const snapshot = await collectUsage(
+      {
+        output: options.input,
+        codexHome: options.codexHome,
+        includeArchived: options.includeArchived,
+        since: null,
+      },
+      ({ 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;
+    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`,
+    );
+    if (writeResult.bytesWritten / writeResult.maxBytes >= 0.7) {
+      process.stderr.write(
+        "Token Ledger: snapshot is above 70% of its safety limit; older buckets will compact automatically as it grows.\n",
+      );
+    }
+    return storedSnapshot;
+  } 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);
+    }
+    throw new Error(
+      `Could not refresh local snapshot: ${safeErrorMessage(error, [options.input, options.codexHome])}`,
+    );
   }
-  const { collectUsage, writePrivateSnapshot } = await import(
-    "../lib/token-ledger-importer.mjs"
-  );
-  process.stderr.write("Token Ledger: refreshing local snapshot…\n");
-  const snapshot = await collectUsage(
-    {
-      output: options.input,
-      codexHome: options.codexHome,
-      includeArchived: options.includeArchived,
-      since: null,
-    },
-    ({ current, total }) => {
-      process.stderr.write(`\rToken Ledger: scanned ${current}/${total} rollout files`);
-    },
-  );
-  process.stderr.write("\n");
-  await writePrivateSnapshot(options.input, snapshot);
-  return snapshot;
 }
 
 export function snapshotNeedsRefresh(snapshotMtimeMs, latestJsonlMtimeMs) {
@@ -682,13 +947,49 @@ export function snapshotCacheIsFresh(
   );
 }
 
+function snapshotAgeLabel(ageMs) {
+  if (ageMs < 60 * 1_000) return "now";
+  const minutes = Math.floor(ageMs / (60 * 1_000));
+  if (minutes < 60) return `${minutes}m old`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h old`;
+  return `${Math.floor(hours / 24)}d old`;
+}
+
+function primitiveString(value) {
+  try {
+    const text = String.prototype.valueOf.call(value);
+    return text === value ? text : null;
+  } catch {
+    return null;
+  }
+}
+
+export function snapshotFreshness(snapshot = {}, nowMs = Date.now()) {
+  const generatedAt = primitiveString(snapshot.generatedAt);
+  const generatedAtMs = generatedAt === null ? NaN : Date.parse(generatedAt);
+  if (
+    !Number.isFinite(generatedAtMs) ||
+    !Number.isFinite(nowMs) ||
+    generatedAtMs > nowMs
+  ) {
+    return { status: "unknown", ageLabel: "age unknown" };
+  }
+  return {
+    status: snapshotCacheIsFresh(generatedAtMs, nowMs) ? "fresh" : "stale",
+    ageLabel: snapshotAgeLabel(nowMs - generatedAtMs),
+  };
+}
+
 async function loadSnapshot(options) {
   if (options.refresh) {
     return refreshSnapshot(options);
   }
   if (!existsSync(options.input)) {
     if (options.inputExplicit || !options.autoRefresh) {
-      throw new Error(`Snapshot not found: ${options.input}`);
+      throw new Error(
+        `Snapshot not found: ${safeDisplayLabel(options.input, "snapshot")}`,
+      );
     }
     return refreshSnapshot(options);
   }
@@ -696,24 +997,46 @@ async function loadSnapshot(options) {
     return readSnapshot(options.input);
   }
 
-  const snapshotStat = await stat(options.input);
+  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 (snapshotCacheIsFresh(snapshotStat.mtimeMs)) {
     return readSnapshot(options.input);
   }
 
   const { latestSourceModifiedAt } = await import("../lib/token-ledger-importer.mjs");
-  const latestSourceMtimeMs = await latestSourceModifiedAt(
-    options.codexHome,
-    options.includeArchived,
-  );
+  let latestSourceMtimeMs;
+  try {
+    latestSourceMtimeMs = await latestSourceModifiedAt(
+      options.codexHome,
+      options.includeArchived,
+    );
+  } catch (error) {
+    throw new Error(
+      `Could not inspect local Codex source: ${safeErrorMessage(error, [options.codexHome])}`,
+    );
+  }
   if (snapshotNeedsRefresh(snapshotStat.mtimeMs, latestSourceMtimeMs)) {
     return refreshSnapshot(options);
   }
   return readSnapshot(options.input);
 }
 
-function render(options, snapshot, bounds, events, rows, allRows) {
+function render(options, snapshot, bounds, events, rows, allRows, freshness) {
   if (options.view === "trend") {
+    if (options.image && options.cacheRate) {
+      return renderCacheReportImage({
+        snapshot,
+        bounds,
+        days: options.trendDays,
+        options,
+      });
+    }
     const trend = buildUsageTrend(snapshot, bounds);
     if (options.image) {
       return renderTrendImage({
@@ -722,6 +1045,7 @@ function render(options, snapshot, bounds, events, rows, allRows) {
         trend,
         days: options.trendDays,
         options,
+        projectRows: allRows,
       });
     }
     return renderTrendCombo({
@@ -733,20 +1057,32 @@ function render(options, snapshot, bounds, events, rows, allRows) {
     });
   }
   if (!options.legacyPlot) {
-    return renderTerminal({ options, snapshot, bounds, events, rows, allRows });
+    return renderTerminal({
+      options,
+      snapshot,
+      snapshotFreshness: freshness,
+      bounds,
+      events,
+      rows,
+      allRows,
+    });
   }
   const enabled = !options.plain && !process.env.NO_COLOR && Boolean(process.stdout.isTTY);
   const summary = totalSummary(events);
   const totalTokens = summary.totalTokens;
-  const dateLabel = 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);
+  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);
   const unit = chartUnit(rows[0]?.totalTokens ?? 0);
   const shares = rows.map((row) =>
     totalTokens > 0 ? (row.totalTokens / totalTokens) * 100 : 0,
@@ -755,7 +1091,7 @@ function render(options, snapshot, bounds, events, rows, allRows) {
 
   const header = [
     `Token Ledger · ${dateLabel} · ${bounds.timeZone}`,
-    `${compact(totalTokens)} tokens · ${summary.threadIds.size.toLocaleString()} threads · ${events.length.toLocaleString()} calls · ${compact(summary.outputTokens)} output`,
+    `${compact(totalTokens)} tokens · ${summary.threadIds.size.toLocaleString()} threads · ${summary.calls.toLocaleString()} calls · ${compact(summary.outputTokens)} output`,
     `Source: ${sourceLabel(options.input, snapshot)}`,
     "",
     chart,
@@ -774,51 +1110,112 @@ function render(options, snapshot, bounds, events, rows, allRows) {
   return `${header.join("\n")}\n\n${details.join("\n")}`;
 }
 
-export async function run(options) {
-  const bounds = options.view === "trend"
-    ? multiDayBounds(options.date, options.timeZone, options.trendDays)
-    : options.range === "week"
-      ? weekBounds(options.date, options.timeZone)
-      : dayBounds(options.date, options.timeZone);
+function boundsForOptions(options, now = new Date()) {
+  if (options.view === "trend") {
+    return multiDayBounds(options.date, options.timeZone, options.trendDays);
+  }
+  if (options.range === "week") {
+    return weekBounds(options.date, options.timeZone);
+  }
+  if (options.range === "rolling24h") {
+    return rolling24hBounds(now, options.timeZone);
+  }
+  if (options.range === "rolling") {
+    return rollingDurationBounds(now, options.timeZone, options.rollingDays);
+  }
+  return dayBounds(options.date, options.timeZone);
+}
+
+function rangeDescription(options, bounds) {
+  if (options.range === "rolling24h" || options.range === "rolling") {
+    return rollingRangeDescription(options);
+  }
+  if (bounds.startDateString && bounds.endDateString) {
+    return `${bounds.startDateString} through ${bounds.endDateString}`;
+  }
+  return bounds.dateString;
+}
+
+export async function run(options, { nowMs } = {}) {
+  const hasInjectedNow = nowMs !== undefined;
+  const now = new Date(hasInjectedNow ? nowMs : Date.now());
+  const bounds = boundsForOptions(options, now);
   const snapshot = await loadSnapshot(options);
   const events = filterDayEvents(snapshot, bounds);
-  if (events.length === 0) {
-    const rangeDescription = options.range === "week"
-      ? `${bounds.startDateString} through ${bounds.endDateString}`
-      : bounds.dateString;
+  const writingImage = options.view === "trend" && options.image;
+  const writingEmptyCacheReport = writingImage && options.cacheRate;
+  if (events.length === 0 && !writingEmptyCacheReport) {
     return [
-      `No model-call events found for ${rangeDescription} (${bounds.timeZone}).`,
+      `No model-call events found for ${rangeDescription(options, bounds)} (${bounds.timeZone}).`,
       `Source: ${sourceLabel(options.input, snapshot)}`,
     ].join("\n");
   }
-  const allRows = aggregateProjects(snapshot, events, options);
+  const allRows = options.cacheRate
+    ? []
+    : aggregateProjects(snapshot, events, options);
   const rows = allRows.slice(0, options.top);
-  const writingImage = options.view === "trend" && options.image;
   const outputPath = writingImage
     ? options.imageOutput ??
       resolve(
         process.cwd(),
-        `token-ledger-${options.report ? "report" : "trend"}-${options.trendDays}d.png`,
+        `token-ledger-${options.cacheRate ? "cache-report" : options.report ? "report" : "trend"}-${options.trendDays}d.png`,
       )
     : null;
-  const imageLabel = options.report ? "report" : "trend image";
+  const imageLabel = options.cacheRate
+    ? "cache report"
+    : options.report
+      ? "report"
+      : "trend image";
   if (writingImage) {
     process.stderr.write(`Token Ledger: generating ${imageLabel} PNG…\n`);
   }
-  const output = render(options, snapshot, bounds, events, rows, allRows);
+  const output = render(
+    options,
+    snapshot,
+    bounds,
+    events,
+    rows,
+    allRows,
+    snapshotFreshness(
+      snapshot,
+      hasInjectedNow ? now.getTime() : Date.now(),
+    ),
+  );
   if (writingImage) {
     await mkdir(dirname(outputPath), { recursive: true });
     process.stderr.write(`Token Ledger: encoding ${imageLabel} PNG…\n`);
     await writeTrendPng(output, outputPath);
     process.stderr.write(`Token Ledger: finished ${imageLabel} PNG.\n`);
-    return [
-      `Wrote ${options.report ? "report" : "trend image"}: ${outputPath}`,
+    const lines = [
+      `Wrote ${imageLabel}: ${outputPath}`,
       `Range: ${bounds.startDateString} through ${bounds.endDateString} (${bounds.timeZone})`,
-    ].join("\n");
+    ];
+    // Show the finished report on screen right away instead of leaving it to
+    // be dug out of a file browser. Skipped for piped/scripted runs so
+    // automation and CI never pop windows.
+    if (options.openImage && process.stdout.isTTY) {
+      lines.push(
+        openInViewer(outputPath)
+          ? "Opened the report in your default image viewer."
+          : "Could not open a viewer automatically; open the file above to see the report.",
+      );
+    }
+    return lines.join("\n");
   }
   return output;
 }
 
+function openInViewer(path) {
+  const platform = process.platform;
+  const [command, args] = platform === "darwin"
+    ? ["open", [path]]
+    : platform === "win32"
+      ? ["cmd", ["/c", "start", "", path]]
+      : ["xdg-open", [path]];
+  const result = spawnSync(command, args, { stdio: "ignore" });
+  return result.status === 0;
+}
+
 function shouldUseInteractive(options) {
   return Boolean(
     !options.static &&
@@ -832,17 +1229,12 @@ function shouldUseInteractive(options) {
 }
 
 async function runInteractive(options) {
-  const bounds = options.range === "week"
-    ? weekBounds(options.date, options.timeZone)
-    : dayBounds(options.date, options.timeZone);
+  const bounds = boundsForOptions(options);
   const snapshot = await loadSnapshot(options);
   const events = filterDayEvents(snapshot, bounds);
   if (events.length === 0) {
-    const rangeDescription = options.range === "week"
-      ? `${bounds.startDateString} through ${bounds.endDateString}`
-      : bounds.dateString;
     process.stdout.write([
-      `No model-call events found for ${rangeDescription} (${bounds.timeZone}).`,
+      `No model-call events found for ${rangeDescription(options, bounds)} (${bounds.timeZone}).`,
       `Source: ${sourceLabel(options.input, snapshot)}`,
       "",
     ].join("\n"));
@@ -852,6 +1244,7 @@ async function runInteractive(options) {
   await startInteractive({
     options,
     snapshot,
+    snapshotFreshness: snapshotFreshness(snapshot),
     bounds,
     events,
     rows: allRows.slice(0, options.top),
@@ -864,7 +1257,7 @@ async function main() {
   try {
     options = parseArgs(process.argv.slice(2));
     if (options.help) {
-      process.stdout.write(`${usage()}\n`);
+      process.stdout.write(`${options.helpAll ? advancedUsage() : usage()}\n`);
       return;
     }
     if (shouldUseInteractive(options)) {
@@ -873,7 +1266,13 @@ async function main() {
       process.stdout.write(`${await run(options)}\n`);
     }
   } catch (error) {
-    process.stderr.write(`Token Ledger CLI failed: ${error.message}\n\n${usage()}\n`);
+    process.stderr.write(
+      `Token Ledger: ${safeErrorMessage(error, [
+        options?.input,
+        options?.codexHome,
+        options?.imageOutput,
+      ])}\nRun \`tledger --help\` for examples or \`tledger --help-all\` for every option.\n`,
+    );
     process.exitCode = 1;
   }
 }