@vimoxshah/tokenflow 1.1.1 → 1.2.0

package/src/commands/week.js

@@ -0,0 +1,86 @@
+/**
+ * `tokenflow week` -- "Your AI week": spend this calendar week vs last week,
+ * computed from the same store every other surface reads.
+ *
+ *   tokenflow week                      text summary
+ *   tokenflow week --svg week.svg       a shareable card
+ *   tokenflow week --svg week.svg --png week.png   card + a local screenshot
+ *   tokenflow week --json               everything, machine-readable
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { loadConfig, paths } from '../core/config.js';
+import { readJson } from '../core/store.js';
+import { buildPriceBook } from '../core/pricing.js';
+import { makeRepoResolver } from '../core/repo.js';
+import { weekStart, addDays } from '../analytics/aggregate.js';
+import { loadPrimaryRecords } from './receipt.js';
+import { computeWeek, renderWeekCardSvg } from '../export/week-card.js';
+import { renderSvgToPng } from '../export/receipt-card.js';
+import { usd, pct } from '../core/units.js';
+
+function expandHome(p) {
+  return p && p.startsWith('~') ? path.join(os.homedir(), p.slice(1)) : p;
+}
+
+function renderWeekText(week) {
+  const L = [];
+  L.push(`Your AI week: ${week.thisWeek.from} to ${week.thisWeek.to}`);
+  L.push(`  Spend: ${usd(week.thisWeek.cost, 'n/a')} (last week ${usd(week.lastWeek.cost, 'n/a')})`);
+  if (week.thisWeek.contextShare !== null) L.push(`  Context share: ${pct(week.thisWeek.contextShare, 0, 'n/a')}`);
+  L.push(`  Turns: ${week.thisWeek.turns}   Sessions: ${week.thisWeek.sessions}`);
+  if (week.topBranches.length) {
+    L.push('  Top branches:');
+    for (const b of week.topBranches) L.push(`    ${b.repo}/${b.branch}  ${usd(b.cost)}`);
+  }
+  if (week.maxSession) L.push(`  Most expensive session: ${usd(week.maxSession.cost)}`);
+  L.push(`  ${week.insight}`);
+  return L.join('\n');
+}
+
+/**
+ * @param {object} flags parsed CLI flags
+ * @returns {{text:string, json:object}}
+ */
+export function run(flags = {}) {
+  const cfg = loadConfig();
+  const pricing = readJson(paths().pricing, {});
+  const book = buildPriceBook(pricing);
+  const now = new Date();
+
+  // A single scan covers this week and last week even across a month
+  // boundary; loadPrimaryRecords already prunes shards outside the window.
+  const today = now.toISOString().slice(0, 10);
+  const thisFrom = weekStart(today);
+  const from = addDays(thisFrom, -7);
+  const records = loadPrimaryRecords({ from, to: today });
+
+  const week = computeWeek({ records, now, book, repoOf: makeRepoResolver() });
+
+  const skin = cfg.ui?.skin || 'aurora';
+  const mode = cfg.ui?.mode || cfg.ui?.theme || 'dark';
+  let text = renderWeekText(week);
+
+  if (typeof flags.svg === 'string') {
+    const svgPath = expandHome(flags.svg);
+    fs.writeFileSync(svgPath, renderWeekCardSvg(week, { skin, mode }));
+    text += `\n\nWrote SVG week card to ${svgPath}`;
+    if (typeof flags.png === 'string') {
+      const pngPath = expandHome(flags.png);
+      // Matches renderWeekCardSvg's own default aspect ratio (640x400).
+      const res = renderSvgToPng(svgPath, pngPath, { width: 640, height: 400 });
+      text += res.ok ? `\nWrote PNG week card to ${pngPath}` : `\n${res.message}`;
+    }
+  } else if (typeof flags.png === 'string') {
+    // --png with no --svg: the SVG is written alongside it, and named, so
+    // there is always a deliverable even without a local Chromium.
+    const pngPath = expandHome(flags.png);
+    const svgPath = `${pngPath}.svg`;
+    fs.writeFileSync(svgPath, renderWeekCardSvg(week, { skin, mode }));
+    const res = renderSvgToPng(svgPath, pngPath, { width: 640, height: 400 });
+    text += res.ok ? `\nWrote PNG week card to ${pngPath} (SVG at ${svgPath})` : `\n${res.message}`;
+  }
+
+  return { text, json: week };
+}

package/src/core/annotations.js

@@ -0,0 +1,97 @@
+/**
+ * Day annotations: a small, user-declared list of dated notes ("switched to
+ * Opus 5", "started using subagents") that every daily chart in the dashboard
+ * draws as a marker.
+ *
+ * One flat file, `<paths().root>/annotations.json`, sitting next to
+ * config.yaml rather than under data/ — data/ holds ingested and derived
+ * state that a refresh rebuilds from source records, while annotations are
+ * hand-authored and must survive a `tokenflow refresh --full` or a store
+ * rebuild exactly the way config.yaml does. test/demo-isolation.test.js does
+ * not assert the store's file set (it only checks that nothing lands under
+ * the default home, and that the sandboxed store has a config.yaml), so
+ * nothing there constrains this choice either way.
+ */
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { paths } from './config.js';
+import { readJson, writeJson } from './store.js';
+
+export const ANNOTATIONS_SCHEMA = 1;
+
+/** Sanitized text longer than this is truncated, never rejected. */
+const MAX_TEXT_LENGTH = 140;
+
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+
+function annotationsFile() {
+  return path.join(paths().root, 'annotations.json');
+}
+
+/** True when `date` is a real calendar day in YYYY-MM-DD form (rejects e.g. 2024-02-30). */
+function isValidDate(date) {
+  if (typeof date !== 'string' || !DATE_RE.test(date)) return false;
+  const [y, m, d] = date.split('-').map(Number);
+  const dt = new Date(Date.UTC(y, m - 1, d));
+  return dt.getUTCFullYear() === y && dt.getUTCMonth() === m - 1 && dt.getUTCDate() === d;
+}
+
+/**
+ * Strip ASCII control characters (including DEL) before trimming, so a
+ * control character sitting outside the visible text does not leave stray
+ * whitespace behind once it's gone. Never HTML-escaped: every render path
+ * (the annotations list, the chart label's title) sets textContent, not
+ * innerHTML, so raw text is safe to store as-is.
+ */
+function sanitizeText(text) {
+  return String(text ?? '').replace(/[\x00-\x1F\x7F]/g, '').trim();
+}
+
+/**
+ * Read the annotations file. A missing or corrupt file yields an empty list
+ * rather than throwing — annotations are optional, and a bad file must never
+ * take the dashboard down.
+ * @returns {{schema:number, items:{id:string,date:string,text:string}[]}}
+ */
+export function readAnnotations() {
+  const raw = readJson(annotationsFile(), null);
+  if (!raw || !Array.isArray(raw.items)) return { schema: ANNOTATIONS_SCHEMA, items: [] };
+  return { schema: ANNOTATIONS_SCHEMA, items: raw.items };
+}
+
+function saveAnnotations(items) {
+  writeJson(annotationsFile(), { schema: ANNOTATIONS_SCHEMA, items });
+}
+
+/**
+ * Add one annotation. Throws a plain `Error` with a short, user-safe message
+ * on invalid input; the caller decides how to surface it (the route answers
+ * 400 with it).
+ * @param {{date?:string, text?:string}} input
+ * @returns {{id:string,date:string,text:string}} the stored item
+ */
+export function addAnnotation({ date, text } = {}) {
+  if (!isValidDate(date)) throw new Error(`invalid date "${date}" — expected YYYY-MM-DD`);
+  const clean = sanitizeText(text).slice(0, MAX_TEXT_LENGTH);
+  if (!clean) throw new Error('text is required');
+  const item = { id: randomUUID(), date, text: clean };
+  const { items } = readAnnotations();
+  items.push(item);
+  saveAnnotations(items);
+  return item;
+}
+
+/**
+ * Remove one annotation by id. Idempotent: removing an id that is already
+ * gone is not an error, it just reports nothing was removed.
+ * @param {string} id
+ * @returns {boolean} whether an item was actually removed
+ */
+export function removeAnnotation(id) {
+  if (!id || typeof id !== 'string') throw new Error('id is required');
+  const { items } = readAnnotations();
+  const next = items.filter((it) => it.id !== id);
+  const removed = next.length !== items.length;
+  if (removed) saveAnnotations(next);
+  return removed;
+}

package/src/core/budget.js

@@ -140,3 +140,36 @@ function persist(s) {
 
 /** Reset state (new month detected by callers, or user command). */
 export function resetBudgetState() { try { fs.unlinkSync(STATE_FILE()); } catch { /* absent */ } }
+
+// ------------------------------------------------------- scoped budgets ---
+//
+// Budgets per repo and per team, alongside the single monthly budget above.
+// Config:
+//
+//   budgets:
+//     - id: api-monthly
+//       scope: repo            # total | repo | team
+//       repo: api               # required when scope is repo
+//       monthlyUsd: 150
+//       warnAt: 0.8             # optional, default 0.8 — a fraction, same
+//                                # meaning as `limits[].warnAt`
+//
+// This function is the pure evaluator only: given what was already spent in
+// a scope and its declared cap, decide ok / warn / over. Finding "what was
+// spent" for a repo or a team needs I/O (the store, the sync folder) and
+// lives in src/commands/budget-scopes.js so this module stays dependency-free
+// and unit-testable without a filesystem.
+
+/**
+ * @param {{spentUsd?:number, monthlyUsd?:number, warnAt?:number}} [input]
+ * @returns {{spentUsd:number, monthlyUsd:number, warnAt:number, share:number, state:'ok'|'warn'|'over'}|null}
+ *   null when no positive monthly cap was declared for this scope (including
+ *   when called with nothing at all — the same "no cap" answer).
+ */
+export function scopedBudgetState({ spentUsd, monthlyUsd, warnAt = 0.8 } = {}) {
+  if (!(monthlyUsd > 0)) return null;
+  const spent = spentUsd > 0 ? spentUsd : 0;
+  const share = spent / monthlyUsd;
+  const state = share >= 1 ? 'over' : share >= warnAt ? 'warn' : 'ok';
+  return { spentUsd: spent, monthlyUsd, warnAt, share, state };
+}

package/src/core/bundle.js

@@ -13,9 +13,48 @@ import { Store, readJson } from './store.js';
 import { paths, loadConfig } from './config.js';
 import { summarizeQuality } from './validate.js';
 import { tzOffsetMinutes } from './schema.js';
-import { PRICING_TABLE_VERSION, PRICING_SOURCES, TIER_MULTIPLIERS } from './pricing.js';
+import { PRICING_TABLE_VERSION, PRICING_SOURCES, TIER_MULTIPLIERS, buildPriceBook } from './pricing.js';
+import { decodeRecord } from './store.js';
+import { MEASUREMENT } from './schema.js';
+import { createReceiptBuilder } from '../analytics/receipt.js';
+import { makeRepoResolver } from './repo.js';
+import { readAnnotations } from './annotations.js';
 
-export function buildBundle({ config = loadConfig() } = {}) {
+/**
+ * Receipts for the whole store, attributed per repository and branch. A full
+ * record scan costs seconds on a large store, so the result is cached against
+ * the store's refresh stamp and streamed through the builder rather than
+ * materialized. Shipped in the bundle so the offline snapshot has them too.
+ */
+let receiptsCache = { key: null, value: null };
+export function buildReceiptsForStore(store, pricing) {
+  const key = `${store.state.lastRefresh || ''}|${store.state.records || ''}|${JSON.stringify(pricing || {})}`;
+  if (receiptsCache.key === key) return receiptsCache.value;
+  const t0 = Date.now();
+  const builder = createReceiptBuilder({ book: buildPriceBook(pricing || {}), repoOf: makeRepoResolver() });
+  store.scanRecords((o) => {
+    if (o.ms !== MEASUREMENT.PRIMARY) return;
+    builder.add(decodeRecord(o));
+  });
+  const r = builder.finish();
+  const value = {
+    ...r,
+    computedAt: new Date().toISOString(),
+    computeMs: Date.now() - t0,
+    // The dashboard shows the whole store; the PR join stays a CLI concern
+    // (`tokenflow receipt --gh`) until cached PR lists exist.
+    scope: 'store',
+  };
+  receiptsCache = { key, value };
+  return value;
+}
+
+/**
+ * @param {{config?:object, receipts?:boolean}} [opt] `receipts: false` skips the
+ *   whole-store receipt scan; the watcher's status snapshot and one-line CLI
+ *   summaries never read them, so they should not pay seconds for them.
+ */
+export function buildBundle({ config = loadConfig(), receipts = true } = {}) {
   const store = new Store();
   const p = paths();
   const cube = store.cube();
@@ -85,6 +124,10 @@ export function buildBundle({ config = loadConfig() } = {}) {
     // against the same cube every other surface reads.
     limits: Array.isArray(config.limits) ? config.limits : [],
     health,
+    receipts: receipts ? buildReceiptsForStore(store, pricing) : null,
+    // User-marked calendar days ("switched to Opus 5"), drawn on every daily
+    // chart. A missing annotations.json yields an empty list, never a throw.
+    annotations: readAnnotations().items,
   };
 }
 

package/src/core/ingest.js

@@ -13,6 +13,7 @@
  */
 import fs from 'node:fs';
 import os from 'node:os';
+import path from 'node:path';
 import { Store, encodeRecord, decodeRecord, fileId, compactShards } from './store.js';
 import { createRecord, dateParts, hashId, MEASUREMENT, INTERFACE } from './schema.js';
 import { classifyModel, BUILTIN_MODEL_RULES } from './model-map.js';
@@ -21,6 +22,7 @@ import { buildPriceBook, estimateCost } from './pricing.js';
 import { validateUsage } from './validate.js';
 import { loadConfig, paths } from './config.js';
 import { readJson, writeJson, truncateFile } from './store.js';
+import { repoRootOf } from './repo.js';
 
 /**
  * @param {object} opt
@@ -360,6 +362,37 @@ export function enrich(partial, { ctx, provider, seq = 0, fileRef = null }) {
     metadata: partial.metadata || {},
   };
 
+  // Repository identity from the recorded cwd: a session in
+  // `<repo>/.worktrees/<x>` (or any dir whose `.git` points back into a main
+  // checkout's `.git/worktrees/`) is otherwise filed under `x`, splitting one
+  // repository's spend across every worktree it ever had. `repoRootOf` walks
+  // up to the main checkout; `project` always moves to its basename.
+  // `repository` follows only when the adapter derived it the same way the
+  // broken `project` was derived — null, or equal to the adapter's own
+  // (pre-correction) `project` value, which is how anthropic and git-less
+  // Codex sessions set it (basename of cwd). A `repository` that DIFFERS from
+  // that — e.g. openai's `session_meta.git`-derived name — came from real
+  // evidence (a git remote), not a guess from the directory name, and is left
+  // alone even though the checkout dir the session ran in has another name.
+  // When no repository root is found (cwd outside any git checkout, or
+  // missing), the adapter's own values are kept as-is, and `repoResolved`
+  // records which case this was so the doctor can find sessions that were
+  // never matched to a repo.
+  const cwd = base.metadata && base.metadata.cwd;
+  if (cwd) {
+    ctx.repoCache = ctx.repoCache || new Map();
+    const root = repoRootOf(cwd, ctx.repoCache);
+    if (root) {
+      const name = path.basename(root);
+      const derivedFromDir = base.repository === null || base.repository === undefined || base.repository === base.project;
+      base.project = name;
+      if (derivedFromDir) base.repository = name;
+      base.metadata = { ...base.metadata, repoResolved: true };
+    } else {
+      base.metadata = { ...base.metadata, repoResolved: false };
+    }
+  }
+
   // Cost: a measured cost from the source always wins; otherwise estimate,
   // and leave null when the model has no configured price.
   if (partial.measured_cost !== undefined && partial.measured_cost !== null) {

package/src/core/live-status.js

@@ -19,10 +19,13 @@ import { buildBundle } from './bundle.js';
 import { computeView } from '../analytics/index.js';
 import { filterCube, filterSessions, indexCube, rank, finalize, sumRows, weekStart, addDays } from '../analytics/aggregate.js';
 import { loadConfig, paths, ensureDirs } from './config.js';
-import { readJson } from './store.js';
+import { readJson, Store, decodeRecord } from './store.js';
 import { compact, usd, countdown } from './units.js';
 import { detectMilestones } from '../analytics/milestones.js';
 import { lockIsLive, readLock } from './watch-lock.js';
+import { evaluateGuard, createReceiptBuilder } from '../analytics/receipt.js';
+import { buildPriceBook } from './pricing.js';
+import { MEASUREMENT } from './schema.js';
 
 // Formatting adapters over the shared units.js formatters (which the browser
 // bundle also uses): null means "nothing to show", never "—", never 0.
@@ -57,7 +60,7 @@ function usageSlice(m, extra = {}) {
  */
 export function buildLiveStatus(opt = {}) {
   const config = opt.config || loadConfig();
-  const b = opt.bundle || buildBundle({ config });
+  const b = opt.bundle || buildBundle({ config, receipts: false });
   const nowMs = opt.nowMs ?? Date.now();
   const v = computeView(b, {});
   const ix = indexCube(b.cube);
@@ -208,6 +211,19 @@ export function buildLiveStatus(opt = {}) {
   const ageMs = lastRefresh ? Math.max(0, nowMs - new Date(lastRefresh).getTime()) : null;
   const staleAfterMs = (config.watch?.staleAfterSeconds ?? 600) * 1000;
 
+  // A second, record-level pass: the cube above is pre-aggregated and carries
+  // no session id, branch or per-turn guard verdict, so live sessions,
+  // today's receipts, guard state and sparklines are derived straight from
+  // the store's shard files rather than from `b.cube`.
+  const recent = buildRecentActivity({
+    pricing: b.pricing,
+    guardPolicy: config.guard || {},
+    referenceMs: lastRefresh ? new Date(lastRefresh).getTime() : nowMs,
+    lastRefresh,
+    today,
+    tzOffsetMinutes,
+  });
+
   return {
     schema: STATUS_SCHEMA,
     generatedAt: new Date(nowMs).toISOString(),
@@ -253,6 +269,10 @@ export function buildLiveStatus(opt = {}) {
     })),
     firstSeen: v.firstSeen,
     insights: v.insights.slice(0, 3).map((i) => ({ icon: i.icon, text: i.text })),
+    liveSessions: recent.liveSessions,
+    receiptsToday: recent.receiptsToday,
+    guard: recent.guard,
+    sparklines: recent.sparklines,
   };
 }
 
@@ -279,6 +299,211 @@ function trimLimitState(s) {
   };
 }
 
+// ------------------------------------------------------- recent activity ----
+
+/** Sessions "live" within this many minutes of `asOf` show up in `liveSessions`. */
+const LIVE_WINDOW_MINUTES = 10;
+/** Hourly sparkline depth. */
+const SPARK_HOURS = 24;
+/** `liveSessions.sessions` is capped here — a menu bar row, not a table. */
+const MAX_LIVE_SESSIONS = 8;
+
+/** `YYYY-MM` shard key a UTC instant falls into, in a timezone `offsetMinutes` east of UTC. */
+function monthKeyOf(ms, offsetMs) {
+  return new Date(ms + offsetMs).toISOString().slice(0, 7);
+}
+
+/**
+ * Start-of-local-hour instant (as a UTC epoch ms) containing `ms`, in a
+ * timezone `offsetMs` (== tzOffsetMinutes*60000) east of UTC. Like the
+ * hour-granular windows above, this is a fixed-offset approximation — a
+ * timezone whose offset changes (DST) mid-window is not modelled.
+ */
+function hourStartMs(ms, offsetMs) {
+  return Math.floor((ms + offsetMs) / 3600000) * 3600000 - offsetMs;
+}
+
+const GUARD_LEVEL_RANK = { ok: 0, warn: 1, block: 2 };
+
+/**
+ * Most recently modified guard-cache file's verdict, if the cache stores one.
+ *
+ * As of this writing `tokenflow guard`'s cache (`$TOKENFLOW_HOME/guard/*.json`,
+ * see `src/commands/guard.js`) persists `{offset, state, records, updated}` —
+ * no verdict — so this always falls through to `null` today; the read stays
+ * here so a future cache format that adds one is picked up without a change
+ * here, and `lastVerdict.source` tells a reader which path produced it.
+ * @returns {{level:string, sessionId:string|null, at:string|null, reasons:string[], source:'cache'}|null}
+ */
+function readGuardCacheVerdict() {
+  const dir = path.join(paths().root, 'guard');
+  let files;
+  try { files = fs.readdirSync(dir).filter((f) => f.endsWith('.json')); } catch { return null; }
+  let latest = null;
+  let latestMtime = -1;
+  for (const f of files) {
+    let st;
+    try { st = fs.statSync(path.join(dir, f)); } catch { continue; }
+    if (st.mtimeMs > latestMtime) { latestMtime = st.mtimeMs; latest = f; }
+  }
+  if (!latest) return null;
+  const data = readJson(path.join(dir, latest), null);
+  if (!data || !data.verdict) return null;
+  const v = data.verdict;
+  return {
+    level: v.level ?? 'ok',
+    sessionId: v.sessionId ?? data.records?.[0]?.session_id ?? null,
+    at: data.updated ?? null,
+    reasons: Array.isArray(v.reasons) ? v.reasons : [],
+    source: 'cache',
+  };
+}
+
+/**
+ * Live sessions, today's receipts, guard state and hourly sparklines.
+ *
+ * A second, record-level scan of the store (the cube `buildLiveStatus` reads
+ * above is pre-aggregated and has no session id, branch or per-turn guard
+ * verdict). Restricted to the shards the window can touch — current +
+ * previous month by `referenceMs`, plus `today`'s month if a stale
+ * `lastRefresh` has drifted away from it — and within those shards, to
+ * records timestamped in the last `SPARK_HOURS` hours (sessions + sparklines)
+ * or dated `today` in the dataset timezone (receipts).
+ *
+ * "Live" and every `asOf` here anchor on `referenceMs` (the store's last
+ * refresh, falling back to the current clock only when it has never
+ * refreshed) rather than the real clock: a reader of this file is only ever
+ * as current as the last completed refresh, and the field name says so
+ * rather than quietly assuming "now".
+ *
+ * @param {{pricing:object, guardPolicy:object, referenceMs:number,
+ *   lastRefresh:string|null, today:string, tzOffsetMinutes:number}} opt
+ */
+export function buildRecentActivity(opt) {
+  const { pricing, guardPolicy, referenceMs, lastRefresh, today, tzOffsetMinutes: tzOff } = opt;
+  const offsetMs = (tzOff || 0) * 60000;
+  const book = buildPriceBook(pricing || {});
+  const store = new Store();
+
+  const firstBucket = hourStartMs(referenceMs, offsetMs) - (SPARK_HOURS - 1) * 3600000;
+  const liveCutoffMs = referenceMs - LIVE_WINDOW_MINUTES * 60000;
+  const months = [...new Set([
+    monthKeyOf(firstBucket, offsetMs),
+    monthKeyOf(referenceMs, offsetMs),
+    today.slice(0, 7),
+  ])];
+
+  /** @type {Map<string, {tokens:number[], cost:number[]}>} */
+  const perSource = new Map();
+  const sessions = new Map();
+  const receiptBuilder = createReceiptBuilder({
+    book,
+    repoOf: (rec) => {
+      const raw = rec.repository || rec.project;
+      return raw ? path.basename(raw) : null;
+    },
+  });
+
+  store.scanRecords((o) => {
+    if (o.ms !== MEASUREMENT.PRIMARY) return;
+    const ts = Date.parse(o.ts);
+    if (!Number.isFinite(ts)) return;
+    if (o.d === today) receiptBuilder.add(decodeRecord(o));
+
+    if (ts < firstBucket || ts > referenceMs) return;
+    const src = o.so || 'unknown';
+    let sp = perSource.get(src);
+    if (!sp) { sp = { tokens: new Array(SPARK_HOURS).fill(0), cost: new Array(SPARK_HOURS).fill(0) }; perSource.set(src, sp); }
+    const idx = Math.round((hourStartMs(ts, offsetMs) - firstBucket) / 3600000);
+    if (idx >= 0 && idx < SPARK_HOURS) {
+      sp.tokens[idx] += (o.in || 0) + (o.ou || 0) + (o.cr || 0) + (o.cw || 0);
+      if (o.co !== null && o.co !== undefined && o.cb !== 'measured') sp.cost[idx] += o.co;
+    }
+
+    if (!o.s) return; // no session id: still in the sparklines/receipts above, never a "live session"
+    let e = sessions.get(o.s);
+    if (!e) { e = { records: [], maxTs: -Infinity }; sessions.set(o.s, e); }
+    e.records.push(decodeRecord(o));
+    if (ts > e.maxTs) e.maxTs = ts;
+  }, { months });
+
+  // ---- live sessions ----------------------------------------------------
+  const liveEntries = [...sessions.entries()]
+    .filter(([, e]) => e.maxTs >= liveCutoffMs)
+    .sort((a, b) => b[1].maxTs - a[1].maxTs)
+    .slice(0, MAX_LIVE_SESSIONS);
+
+  const liveSessionsList = liveEntries.map(([sid, e]) => {
+    const recs = e.records.slice().sort((a, b) => (a.timestamp < b.timestamp ? -1 : a.timestamp > b.timestamp ? 1 : 0));
+    const last = recs[recs.length - 1];
+    const v = evaluateGuard(recs, guardPolicy || {}, book);
+    return {
+      sessionId: sid,
+      source: last.source ?? null,
+      provider: last.provider ?? null,
+      model: last.model ?? null,
+      project: last.project ?? null,
+      repository: last.repository ? path.basename(last.repository) : null,
+      branch: last.git_branch ?? null,
+      startedAt: v.first,
+      lastActivityAt: v.last,
+      turns: v.turns,
+      subagentTurns: v.subagentTurns,
+      costUsd: v.cost,
+      coverage: v.coverage,
+      contextTokens: v.contextTokens,
+      contextShare: v.contextShare,
+      guard: { level: v.level, reasons: v.reasons, declared: v.declared },
+    };
+  });
+
+  // ---- today's receipts ---------------------------------------------------
+  const receipts = receiptBuilder.finish();
+  const items = [];
+  for (const R of receipts.repos) {
+    for (const br of R.branches) items.push({ repo: R.repo, branch: br.key, costUsd: br.cost, turns: br.turns, sessions: br.sessions });
+    if (R.unattributed.turns > 0) {
+      items.push({ repo: R.repo, branch: null, costUsd: R.unattributed.cost, turns: R.unattributed.turns, sessions: R.unattributed.sessions });
+    }
+  }
+  items.sort((a, b) => (b.costUsd ?? -1) - (a.costUsd ?? -1));
+
+  // ---- guard ----------------------------------------------------------------
+  const numOrNull = (v) => (typeof v === 'number' && Number.isFinite(v) && v > 0 ? v : null);
+  const gp = guardPolicy || {};
+  const policy = {
+    warnCostUsd: numOrNull(gp.warnCostUsd),
+    maxCostUsd: numOrNull(gp.maxCostUsd),
+    warnContextTokens: numOrNull(gp.warnContextTokens),
+    maxContextTokens: numOrNull(gp.maxContextTokens),
+    warnMarginalUsd: numOrNull(gp.warnMarginalUsd),
+  };
+  const declared = Object.values(policy).some((val) => val !== null);
+
+  /** @type {{level:string, sessionId:string|null, at:string|null, reasons:string[], source:'cache'|'derived'}|null} */
+  let lastVerdict = readGuardCacheVerdict();
+  if (!lastVerdict) {
+    let worst = null;
+    for (const s of liveSessionsList) {
+      if (!worst || GUARD_LEVEL_RANK[s.guard.level] > GUARD_LEVEL_RANK[worst.guard.level]) worst = s;
+    }
+    lastVerdict = worst
+      ? { level: worst.guard.level, sessionId: worst.sessionId, at: worst.lastActivityAt, reasons: worst.guard.reasons, source: 'derived' }
+      : null;
+  }
+
+  return {
+    liveSessions: { asOf: lastRefresh, windowMinutes: LIVE_WINDOW_MINUTES, sessions: liveSessionsList },
+    receiptsToday: { asOf: lastRefresh, totalCostUsd: receipts.totals.cost, items: items.slice(0, 3) },
+    guard: { policy, declared, lastVerdict },
+    sparklines: {
+      hours: Array.from({ length: SPARK_HOURS }, (_, i) => new Date(firstBucket + i * 3600000).toISOString()),
+      bySource: Object.fromEntries([...perSource].map(([k, v]) => [k, v.tokens])),
+      costBySource: Object.fromEntries([...perSource].map(([k, v]) => [k, v.cost.map((n) => Math.round(n * 100) / 100)])),
+    },
+  };
+}
+
 /** Atomic write: tmp file + rename, so readers never see a half-file. */
 export function writeLiveStatus(status) {
   const p = paths();