tledger 0.2.0 → 0.2.1

package/README.md

@@ -46,6 +46,8 @@ is interactive; press `q` or `esc` to exit.
 Other common views:
 
 ```bash
+tledger 1d
+tledger 1d --static
 tledger day 2026-08-05
 tledger week --top 5
 tledger week --static
@@ -54,6 +56,10 @@ tledger trend 7d --image --image-output artifacts/token-ledger-trend-7d.png
 tledger report 7d
 ```
 
+`tledger 1d` shows the `TOKENS BY PROJECT` breakdown for the rolling 24 hours
+ending when the command starts. It is different from `tledger day today`, which
+covers the current calendar day from local midnight.
+
 `tledger report [7d|14d|30d]` is the one-step report output: it writes the
 dashboard PNG (identical to `trend --image`) to
 `token-ledger-report-<period>.png` in the current directory. It accepts the
@@ -107,6 +113,12 @@ The first refresh may scan historical rollout files; later runs use the cache
 for one hour before checking source freshness again. Use `--refresh` when you
 need to force an immediate rebuild.
 
+The `1d` project dashboard shows a compact snapshot-age line such as
+`SNAPSHOT · fresh · 12m old`. `fresh` means the snapshot is within the
+one-hour cache window, `stale` means it is older, and `age unknown` means the
+snapshot has no usable capture-time metadata. The indicator does not print a
+local path or trigger another source scan.
+
 Useful overrides:
 
 ```bash
@@ -139,19 +151,29 @@ writes its privacy-reduced cache to:
 
 The collector does not export message bodies, reasoning text, tool arguments or
 results, credentials, file contents, or full local paths. Display titles may
-contain user-written text. The CLI makes no network requests.
+contain user-written text. CLI errors and empty-state source labels show only a
+safe filename label, not an absolute input or source path. When a PNG or report
+is written, the explicit output path is reported so you can find the file. The
+CLI makes no network requests.
 
 ## Keyboard controls
 
 In the interactive dashboard:
 
 - `↑` / `↓` or `j` / `k` moves between projects.
-- `q` or `esc` exits.
+- `q`, `Q`, `Esc`, or `Ctrl-C` exits.
+- Enter does not inspect a project, and `d` / `w` / `m` do not change the
+  range; choose the desired range in the command instead.
 
 ## Verify from source
 
 ```bash
 npm test
 npm run lint
-npm pack --dry-run
+npm run verify:release
+npm pack --dry-run --json
 ```
+
+`npm run verify:release` packs the allowlisted artifact, installs that tarball
+in a clean temporary directory with no network or Codex data access, and runs
+the installed `tledger --help` and synthetic `tledger 1d --static` smoke checks.

package/bin/token-ledger-controls.mjs

@@ -0,0 +1,24 @@
+export const INTERACTIVE_KEY_INPUTS = Object.freeze({
+  up: Object.freeze(["\u001b[A", "k"]),
+  down: Object.freeze(["\u001b[B", "j"]),
+  quit: Object.freeze(["q", "Q", "\u0003", "\u001b"]),
+});
+
+export const INTERACTIVE_FOOTER = Object.freeze({
+  ascii: "[j/k] select   [q/Q/esc/ctrl-c] quit",
+  unicode: "[↑↓/j/k] select   [q/Q/esc/ctrl-c] quit",
+});
+
+export const INTERACTIVE_HELP = "↑/↓ or j/k move   •   q/Q, esc, or ctrl-c quit";
+
+export function actionFor(input) {
+  const value = String(input);
+  if (value.includes(INTERACTIVE_KEY_INPUTS.up[0]) || value === INTERACTIVE_KEY_INPUTS.up[1]) {
+    return "up";
+  }
+  if (value.includes(INTERACTIVE_KEY_INPUTS.down[0]) || value === INTERACTIVE_KEY_INPUTS.down[1]) {
+    return "down";
+  }
+  if (INTERACTIVE_KEY_INPUTS.quit.includes(value)) return "quit";
+  return null;
+}

package/bin/token-ledger-terminal.mjs

@@ -2,6 +2,10 @@ import {
   normalizeQuotaTimeline,
   weeklyQuotaObservations,
 } from "./token-ledger-trend.mjs";
+import {
+  INTERACTIVE_FOOTER,
+  INTERACTIVE_HELP,
+} from "./token-ledger-controls.mjs";
 
 const RESET = "\u001b[0m";
 const PRIMARY_STYLE = [38, 2, 255, 255, 255];
@@ -128,6 +132,7 @@ function displayProject(row) {
 }
 
 function dateLabel(bounds, range = "day") {
+  if (range === "rolling24h") return "LAST 24 HOURS";
   if (range === "week" && bounds.startDateString && bounds.endDateString) {
     const startParts = bounds.startDateString.split("-").map(Number);
     const endParts = bounds.endDateString.split("-").map(Number);
@@ -496,10 +501,22 @@ function panel(leftLines, rightLines, leftWidth, rightWidth, enabled, ascii) {
   return [top, ...body, bottom];
 }
 
-function headerLines(stats, bounds, frameWidth, options, enabled) {
+function snapshotLine(freshness, enabled) {
+  const detail = freshness?.status === "fresh" || freshness?.status === "stale"
+    ? `${freshness.status} · ${freshness.ageLabel}`
+    : "age unknown";
+  return `${colorize("SNAPSHOT", ACCENT_STYLE, enabled)} ${colorize("·", SECONDARY_STYLE, enabled)} ${colorize(detail, SECONDARY_STYLE, enabled)}`;
+}
+
+function headerLines(stats, bounds, frameWidth, options, enabled, freshness) {
   const left = colorize("TOKEN LEDGER", TITLE_STYLE, enabled);
   const date = colorize(dateLabel(bounds, options.range), TEXT_STYLE, enabled);
-  const mode = colorize(options.range === "week" ? "7 DAYS" : "DAY", [1, ...ACCENT_STYLE], enabled);
+  const modeLabel = options.range === "rolling24h"
+    ? "24 HOURS"
+    : options.range === "week"
+      ? "7 DAYS"
+      : "DAY";
+  const mode = colorize(modeLabel, [1, ...ACCENT_STYLE], enabled);
   const metric = (value, label) =>
     `${colorize(String(value), TITLE_STYLE, enabled)} ${colorize(label, SECONDARY_STYLE, enabled)}`;
   const separator = colorize("·", SECONDARY_STYLE, enabled);
@@ -515,13 +532,19 @@ function headerLines(stats, bounds, frameWidth, options, enabled) {
     metric(stats.projectCount.toLocaleString("en-US"), "PROJECTS"),
   ].join(join);
   if (visibleLength(fullLine) < frameWidth) {
-    return [alignHeader(fullLine)];
+    const lines = [alignHeader(fullLine)];
+    if (options.range === "rolling24h") lines.push(alignHeader(snapshotLine(freshness, enabled)));
+    return lines;
   }
 
   const compactDate = dateLabel(bounds, options.range)
     .replace(/ 20\d{2}$/, "")
     .replace(" – ", "–");
-  const compactMode = options.range === "week" ? "7D" : "DAY";
+  const compactMode = options.range === "rolling24h"
+    ? "24H"
+    : options.range === "week"
+      ? "7D"
+      : "DAY";
   const compactLine = [
     left,
     colorize(compactDate, TEXT_STYLE, enabled),
@@ -532,7 +555,9 @@ function headerLines(stats, bounds, frameWidth, options, enabled) {
     metric(stats.projectCount.toLocaleString("en-US"), "P"),
   ].join(join);
   if (visibleLength(compactLine) < frameWidth) {
-    return [alignHeader(compactLine)];
+    const lines = [alignHeader(compactLine)];
+    if (options.range === "rolling24h") lines.push(alignHeader(snapshotLine(freshness, enabled)));
+    return lines;
   }
 
   const minimalTitle = colorize(frameWidth >= 45 ? "LEDGER" : "L", TITLE_STYLE, enabled);
@@ -545,10 +570,20 @@ function headerLines(stats, bounds, frameWidth, options, enabled) {
     compact(stats.threads),
     compact(stats.projectCount),
   ].join(" ");
-  return [alignHeader(minimalLine)];
+  const lines = [alignHeader(minimalLine)];
+  if (options.range === "rolling24h") lines.push(alignHeader(snapshotLine(freshness, enabled)));
+  return lines;
 }
 
-export function renderTerminal({ options, snapshot, bounds, events, rows, allRows }) {
+export function renderTerminal({
+  options,
+  snapshot,
+  snapshotFreshness,
+  bounds,
+  events,
+  rows,
+  allRows,
+}) {
   const enabled = colorsEnabled(options);
   const stats = summary(events);
   const quota = quotaCycleSummary(snapshot, events);
@@ -561,7 +596,7 @@ export function renderTerminal({ options, snapshot, bounds, events, rows, allRow
   const left = panelLines(rows, allRows, stats.totalTokens, leftWidth, options, enabled);
   const right = sideBySide ? sidebarLines(stats, sideWidth, enabled, options, quota) : null;
   const lines = [
-    ...headerLines(stats, bounds, frameWidth, options, enabled),
+    ...headerLines(stats, bounds, frameWidth, options, enabled, snapshotFreshness),
     ...panel(left, right, leftWidth, sideWidth, enabled, options.ascii),
   ];
   if (!sideBySide) {
@@ -571,9 +606,7 @@ export function renderTerminal({ options, snapshot, bounds, events, rows, allRow
   lines.push("");
   lines.push(
     colorize(
-      options.ascii
-        ? "[j/k] select   [enter] inspect   [d/w/m] range   [q] quit"
-        : "[↑↓] select   [enter] inspect   [d/w/m] range   [q] quit",
+      options.ascii ? INTERACTIVE_FOOTER.ascii : INTERACTIVE_FOOTER.unicode,
       SECONDARY_STYLE,
       enabled,
     ),
@@ -591,7 +624,17 @@ function paintFullscreenLine(line, width, background, enabled) {
   return `${background}${restored}${RESET}`;
 }
 
-export function renderFullscreen({ options, snapshot, bounds, events, rows, allRows, width, height }) {
+export function renderFullscreen({
+  options,
+  snapshot,
+  snapshotFreshness,
+  bounds,
+  events,
+  rows,
+  allRows,
+  width,
+  height,
+}) {
   const enabled = options.forceColor ?? colorsEnabled(options);
   const columns = Math.max(40, Number(width) || Number(process.stdout.columns) || 120);
   const screenHeight = Math.max(1, Number(height) || Number(process.stdout.rows) || 32);
@@ -606,6 +649,7 @@ export function renderFullscreen({ options, snapshot, bounds, events, rows, allR
       width: frameWidth + 2,
     },
     snapshot,
+    snapshotFreshness,
     bounds,
     events,
     rows,
@@ -615,7 +659,7 @@ export function renderFullscreen({ options, snapshot, bounds, events, rows, allR
   staticLines.pop();
   if (staticLines.at(-1) === "") staticLines.pop();
   const summaryLine = staticLines.shift() ?? "";
-  const help = colorize("↑/↓ move   •   j/k move   •   q/esc quit", SECONDARY_STYLE, enabled);
+  const help = colorize(INTERACTIVE_HELP, SECONDARY_STYLE, enabled);
   const content = [
     { line: summaryLine, background: SCREEN_BASE },
     ...staticLines.map((line) => ({ line, background: PANEL_BASE })),

package/bin/token-ledger-tui.mjs

@@ -1,4 +1,7 @@
 import { renderFullscreen, SCREEN_BASE } from "./token-ledger-terminal.mjs";
+import { actionFor } from "./token-ledger-controls.mjs";
+
+export { actionFor };
 
 const ENTER_ALT_SCREEN = "\u001b[?1049h";
 const EXIT_ALT_SCREEN = "\u001b[?1049l";
@@ -7,17 +10,16 @@ const SHOW_CURSOR = "\u001b[?25h";
 const CLEAR_SCREEN = "\u001b[2J\u001b[H";
 const RESET = "\u001b[0m";
 
-function actionFor(input) {
-  const value = String(input);
-  if (value.includes("\u001b[A") || value === "k") return "up";
-  if (value.includes("\u001b[B") || value === "j") return "down";
-  if (value === "q" || value === "Q" || value === "\u0003" || value === "\u001b") return "quit";
-  if (value === "\r" || value === "\n") return "inspect";
-  return null;
-}
-
 export function startInteractive(view) {
-  const { options, snapshot, bounds, events, rows, allRows } = view;
+  const {
+    options,
+    snapshot,
+    snapshotFreshness,
+    bounds,
+    events,
+    rows,
+    allRows,
+  } = view;
   const stdin = process.stdin;
   const stdout = process.stdout;
   if (!stdin.isTTY || !stdout.isTTY || typeof stdin.setRawMode !== "function") {
@@ -34,6 +36,7 @@ export function startInteractive(view) {
       const screen = renderFullscreen({
         options: { ...options, forceColor: true, selectedIndex },
         snapshot,
+        snapshotFreshness,
         bounds,
         events,
         rows,
@@ -74,7 +77,6 @@ export function startInteractive(view) {
         draw();
         return;
       }
-      if (action === "inspect") draw();
     };
 
     stdin.setRawMode(true);

package/bin/token-ledger.mjs

@@ -31,6 +31,7 @@ export const DEFAULT_SNAPSHOT = resolve(
 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 ANSI_RESET = "\u001b[0m";
 const MODEL_COLORS = {
   sol: TERMINAL_MODEL_COLORS.sol,
@@ -45,6 +46,7 @@ function usage() {
   return `Token Ledger terminal usage
 
 Usage:
+  tledger 1d                 Rolling 24-hour project breakdown (ends now)
   tledger day <YYYY-MM-DD>
   tledger week [end-day]
   tledger trend [7d|14d|30d]
@@ -78,7 +80,8 @@ 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.`;
+the snapshot or prints message bodies, tool payloads, credentials, or local
+input/source paths. Explicit PNG output paths are reported after writing.`;
 }
 
 function readOption(argv, index, name) {
@@ -90,14 +93,18 @@ function readOption(argv, index, name) {
 }
 
 export function parseArgs(argv) {
-  const command = argv[0] === "week"
-    ? "week"
-    : argv[0] === "trend" || argv[0] === "report"
-      ? "trend"
-      : "day";
+  const rolling24hCommand = argv[0] === "1d";
+  const command = rolling24hCommand
+    ? "rolling24h"
+    : argv[0] === "week"
+      ? "week"
+      : argv[0] === "trend" || argv[0] === "report"
+        ? "trend"
+        : "day";
   const options = {
     range: command,
     view: command === "trend" ? "trend" : "projects",
+    rolling24h: rolling24hCommand,
     report: argv[0] === "report",
     trendDays: 7,
     date: null,
@@ -123,7 +130,7 @@ export function parseArgs(argv) {
   };
 
   let trendPeriodSeen = false;
-  let index = ["day", "week", "trend", "report"].includes(argv[0]) ? 1 : 0;
+  let index = ["1d", "day", "week", "trend", "report"].includes(argv[0]) ? 1 : 0;
   for (; index < argv.length; index += 1) {
     const argument = argv[index];
     if (argument === "--help" || argument === "-h") {
@@ -217,6 +224,19 @@ 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.");
@@ -234,10 +254,13 @@ export function parseArgs(argv) {
   }
 
   if (options.report) options.image = true;
+  if (!options.help && options.rolling24h && options.date) {
+    throw new Error("1d 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) {
     throw new Error("A day is required, for example: tledger day 2026-08-01");
   }
   if (!options.help && options.refresh && !options.autoRefresh) {
@@ -364,6 +387,20 @@ export function weekBounds(value, timeZone) {
   };
 }
 
+export function rolling24hBounds(value = new Date(), timeZone = DEFAULT_TIME_ZONE) {
+  validateTimeZone(timeZone);
+  const end = value instanceof Date ? new Date(value.getTime()) : new Date(value);
+  if (!Number.isFinite(end.getTime())) {
+    throw new Error("Rolling 24-hour window requires a valid end time.");
+  }
+  return {
+    start: new Date(end.getTime() - ROLLING_24_HOURS_MS),
+    end,
+    timeZone,
+    rangeHours: 24,
+  };
+}
+
 export function sanitizeTerminalText(value) {
   return String(value ?? "")
     .replace(/\u001b\][^\u0007]*(?:\u0007|\u001b\\)/g, "")
@@ -378,6 +415,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;
@@ -582,7 +675,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 +720,57 @@ 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"));
   } 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}`);
+    throw new Error(`Snapshot is missing its events array: ${snapshotLabel}`);
   }
   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, writePrivateSnapshot } = 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");
+    await writePrivateSnapshot(options.input, snapshot);
+    return snapshot;
+  } catch (error) {
+    if (progressStarted) process.stderr.write("\n");
+    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 +789,41 @@ 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`;
+}
+
+export function snapshotFreshness(snapshot = {}, nowMs = Date.now()) {
+  const generatedAtMs = typeof snapshot.generatedAt === "string"
+    ? Date.parse(snapshot.generatedAt)
+    : NaN;
+  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,23 +831,37 @@ 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") {
     const trend = buildUsageTrend(snapshot, bounds);
     if (options.image) {
@@ -733,20 +882,30 @@ 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 === "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,
@@ -774,20 +933,36 @@ 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);
+  }
+  return dayBounds(options.date, options.timeZone);
+}
+
+function rangeDescription(options, bounds) {
+  if (options.range === "rolling24h") return "the last 24 hours";
+  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;
     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");
   }
@@ -805,7 +980,18 @@ export async function run(options) {
   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`);
@@ -832,17 +1018,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 +1033,7 @@ async function runInteractive(options) {
   await startInteractive({
     options,
     snapshot,
+    snapshotFreshness: snapshotFreshness(snapshot),
     bounds,
     events,
     rows: allRows.slice(0, options.top),
@@ -873,7 +1055,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 CLI failed: ${safeErrorMessage(error, [
+        options?.input,
+        options?.codexHome,
+        options?.imageOutput,
+      ])}\n\n${usage()}\n`,
+    );
     process.exitCode = 1;
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tledger",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "A local-only terminal dashboard for Codex token usage",
   "license": "MIT",
   "keywords": [
@@ -40,7 +40,8 @@
     "usage:snapshot": "node lib/token-ledger-importer.mjs --output outputs/token-ledger-snapshot.json",
     "usage:day": "node bin/token-ledger.mjs day",
     "usage:week": "node bin/token-ledger.mjs week",
-    "prepublishOnly": "npm test"
+    "verify:release": "node tools/verify-release.mjs",
+    "prepublishOnly": "npm test && npm run verify:release"
   },
   "devDependencies": {
     "eslint": "9.39.4"