@vimoxshah/tokenflow 1.1.2 → 1.2.0

package/src/analytics/rhythm.js

@@ -0,0 +1,184 @@
+/**
+ * Rhythm: how the work happens — focus, switching, and when a turn costs
+ * most.
+ *
+ * Pure functions over two shapes only:
+ *  - a session (src/core/store.js `sessionList()`): `{ d, pj, total,
+ *    durationMs, req, ... }`.
+ *  - a per-hour rollup (src/analytics/token-usage.js
+ *    `calculateHourlyUsage()` bucket): `{ hour, total, req, cost, costReq,
+ *    ... }`.
+ *
+ * No Node imports (besides the shared, dependency-free formatter module), so
+ * this runs the same in the browser, the CLI and the offline snapshot.
+ */
+import { pct, usd, compact, hourLabel, shortDate } from '../core/units.js';
+
+/** A deep-work session runs this long or longer without a break. */
+export const DEEP_WORK_MS = 45 * 60 * 1000;
+/** ...or, when duration cannot be measured, spans at least this many turns. */
+export const DEEP_WORK_TURNS = 40;
+
+function hasKnownDuration(s) {
+  return Number.isFinite(s.durationMs);
+}
+
+function isDeepWork(s) {
+  if (hasKnownDuration(s)) return s.durationMs >= DEEP_WORK_MS;
+  const turns = Number.isFinite(s.req) ? s.req : 0;
+  return turns >= DEEP_WORK_TURNS;
+}
+
+/**
+ * Deep-work sessions: count, share of sessions, share of tokens, longest.
+ * A deep-work session runs 45 minutes or longer of continuous activity, or —
+ * when duration is unknown — spans 40 or more turns (requests).
+ * @param {any[]} sessions
+ * @returns {{count:number, total:number, shareOfSessions:number|null, shareOfTokens:number|null, longest:any|null}}
+ */
+export function deepWork(sessions) {
+  if (!sessions || !sessions.length) {
+    return { count: 0, total: 0, shareOfSessions: null, shareOfTokens: null, longest: null };
+  }
+  const flagged = sessions.filter(isDeepWork);
+  const totalTokens = sessions.reduce((a, s) => a + (s.total || 0), 0);
+  const deepTokens = flagged.reduce((a, s) => a + (s.total || 0), 0);
+  let longest = null;
+  for (const s of sessions) {
+    if (!hasKnownDuration(s)) continue;
+    if (!longest || s.durationMs > longest.durationMs) longest = s;
+  }
+  return {
+    count: flagged.length,
+    total: sessions.length,
+    shareOfSessions: sessions.length ? flagged.length / sessions.length : null,
+    shareOfTokens: totalTokens > 0 ? deepTokens / totalTokens : null,
+    longest,
+  };
+}
+
+/**
+ * Project-switching per day: distinct projects touched that day, minus one.
+ * Only days that actually have a session are counted — a day with no
+ * sessions has no measurable switching, which is not the same as zero
+ * switching, so it is left out rather than filled in as a fabricated 0.
+ * @param {any[]} sessions
+ * @returns {{days:{date:string, projects:number, switches:number}[], average:number|null, worst:{date:string, projects:number, switches:number}|null}}
+ */
+export function switching(sessions) {
+  if (!sessions || !sessions.length) return { days: [], average: null, worst: null };
+  const byDay = new Map();
+  for (const s of sessions) {
+    const day = s.d;
+    if (day === null || day === undefined) continue;
+    let set = byDay.get(day);
+    if (!set) { set = new Set(); byDay.set(day, set); }
+    set.add(s.pj ?? 'unknown');
+  }
+  const days = [...byDay.entries()]
+    .map(([date, projects]) => ({ date, projects: projects.size, switches: Math.max(0, projects.size - 1) }))
+    .sort((a, b) => (a.date < b.date ? -1 : a.date > b.date ? 1 : 0));
+  if (!days.length) return { days, average: null, worst: null };
+  const total = days.reduce((a, d) => a + d.switches, 0);
+  const average = total / days.length;
+  let worst = days[0];
+  for (const d of days.slice(1)) {
+    if (d.switches > worst.switches || (d.switches === worst.switches && d.date > worst.date)) worst = d;
+  }
+  return { days, average, worst };
+}
+
+/**
+ * Cost (or, failing that, tokens) per request by hour of day, from the
+ * per-hour rollups behind `ctx.view` (the `hourly.buckets` this dashboard
+ * already computes). The rows are shape-detected rather than assumed:
+ *  - carries `cost` and `costReq` (requests a price could be assigned to) ->
+ *    estimated cost per PRICED request, metric `'cost'`.
+ *  - carries `total`/`tokens` and `req` only -> tokens per request, metric
+ *    `'tokens'`.
+ *  - neither -> `null`, so the caller can say "not derivable from the
+ *    aggregate" instead of guessing.
+ *
+ * `costReq`, not `req`, is the denominator for the cost metric: `cost` is a
+ * sum over priced requests only (src/core/store.js addToCube), so dividing
+ * by every request would silently treat unpriced traffic as free — a false
+ * zero, not a real one. When an hour has requests but none of them priced,
+ * its `value` is `null` rather than 0.
+ * @param {any[]} rows
+ * @returns {{metric:'cost'|'tokens', hours:{hour:number, value:number|null, requests:number}[], costliest:{hour:number, value:number, requests:number}|null} | null}
+ */
+export function costliestHour(rows) {
+  if (!Array.isArray(rows) || !rows.length) return null;
+  const sample = rows[0];
+  /** @type {'cost'|'tokens'} */
+  let metric;
+  if ('cost' in sample && 'costReq' in sample) metric = 'cost';
+  else if (('total' in sample || 'tokens' in sample) && 'req' in sample) metric = 'tokens';
+  else return null;
+
+  const hours = rows.map((r) => {
+    const denom = metric === 'cost' ? (r.costReq || 0) : (r.req || 0);
+    const numer = metric === 'cost' ? (r.cost || 0) : (r.total ?? r.tokens ?? 0);
+    return { hour: r.hour, value: denom > 0 ? numer / denom : null, requests: denom };
+  });
+  const ranked = hours.filter((h) => h.value !== null);
+  const costliest = ranked.length ? ranked.reduce((a, b) => (b.value > a.value ? b : a)) : null;
+  return { metric, hours, costliest };
+}
+
+/**
+ * Days ranked by the share of that day's tokens spent in deep-work sessions,
+ * top 5. Days with zero tokens are excluded — a 0/0 share is not a real 0%.
+ * @param {any[]} sessions
+ * @returns {{date:string, total:number, deepTokens:number, sessions:number, share:number}[]}
+ */
+export function focusDays(sessions) {
+  if (!sessions || !sessions.length) return [];
+  const byDay = new Map();
+  for (const s of sessions) {
+    const day = s.d;
+    if (day === null || day === undefined) continue;
+    let acc = byDay.get(day);
+    if (!acc) { acc = { date: day, total: 0, deepTokens: 0, sessions: 0 }; byDay.set(day, acc); }
+    const tokens = s.total || 0;
+    acc.total += tokens;
+    acc.sessions += 1;
+    if (isDeepWork(s)) acc.deepTokens += tokens;
+  }
+  const days = [...byDay.values()]
+    .filter((d) => d.total > 0)
+    .map((d) => ({ ...d, share: d.deepTokens / d.total }));
+  days.sort((a, b) => b.share - a.share || (a.date < b.date ? -1 : 1));
+  return days.slice(0, 5);
+}
+
+/**
+ * Three story-strip sentences summarizing the rhythm of work, in the style
+ * of the Overview's insight cards.
+ * @param {{deep:ReturnType<typeof deepWork>, switching:ReturnType<typeof switching>, costliest:ReturnType<typeof costliestHour>}} o
+ * @returns {string[]}
+ */
+export function rhythmSummary({ deep, switching: sw, costliest }) {
+  const s1 = deep.count > 0
+    ? `Deep-work sessions were ${pct(deep.shareOfSessions, 1, 'n/a')} of sessions and ${pct(deep.shareOfTokens, 1, 'n/a')} of tokens.`
+    : 'No deep-work sessions (45+ minutes, or 40+ turns when duration is unknown) in this slice.';
+
+  const s2 = sw.days.length
+    ? `Projects switched ${sw.average.toFixed(1)} times a day on average, worst was ${sw.worst.switches} switch${sw.worst.switches === 1 ? '' : 'es'} on ${shortDate(sw.worst.date)}.`
+    : 'No sessions with a known day, so project switching cannot be measured.';
+
+  let s3;
+  if (!costliest) {
+    s3 = 'Cost per request by hour is not derivable from the aggregate.';
+  } else if (!costliest.costliest) {
+    s3 = costliest.metric === 'cost'
+      ? 'No priced requests in this slice, so cost per request by hour is not shown.'
+      : 'No requests in this slice, so tokens per request by hour is not shown.';
+  } else if (costliest.metric === 'cost') {
+    s3 = `The costliest hour was ${hourLabel(costliest.costliest.hour)}:00, at ${usd(costliest.costliest.value)} per priced request.`;
+  } else {
+    s3 = `The heaviest hour was ${hourLabel(costliest.costliest.hour)}:00, at ${compact(costliest.costliest.value)} tokens per request.`;
+  }
+
+  return [s1, s2, s3];
+}

package/src/analytics/whatif.js

@@ -0,0 +1,263 @@
+/**
+ * What-if repricing: take the tokens a model already used and price them
+ * again at another model's published rates.
+ *
+ * This says nothing about quality, latency or output length. It only prices.
+ * It answers "what would this same traffic have cost at model B's rates
+ * instead of model A's", nothing more.
+ *
+ * ## Method
+ *
+ * Both the "current" and "what-if" figures are recomputed here from the raw
+ * token counts times `book.lookup(...)`, never read off the row's own
+ * `cost` field. That is deliberate: the per-model aggregate the Cost view
+ * shows (`view.dimensions.models[*].cost`) already applied each request's
+ * service-tier multiplier (Anthropic Batch, OpenAI Fast/priority, ...), but
+ * an aggregated model row only carries token totals, not a per-tier
+ * breakdown, so there is nothing left here to multiply. Recomputing "current"
+ * through the exact same code path as "what-if" is what makes an identity
+ * mapping (source === target) provably yield a zero delta, and it is also
+ * why a heavily-tiered slice will show a "current" here that sits a little
+ * off the Cost tab's tier-aware number for the same model. That is a known,
+ * reported simplification, not a bug.
+ *
+ * ## Missing rates
+ *
+ * `book.lookup(model, provider)` returns `null` when the model has no price
+ * at all: both "current" and "what-if" are `null` (n/a) for that model, and
+ * it is excluded from every overall total (current, what-if AND delta).
+ * Folding an unknown number into a sum by pretending it is zero would just
+ * be a wrong number wearing a confident face. When the model *does* have a
+ * price but one token kind on it does not (a partial user override, for
+ * example), that one kind reports `null` and the model's total is flagged
+ * `partial`; the kinds that ARE known still sum into the total.
+ */
+
+/** Token kinds priced individually. Reasoning tokens are a subset of output
+ * tokens (see core/schema.js) and the shipped price table has no separate
+ * reasoning rate, so there is no fifth kind to compute today. A future rate
+ * that names one would show up as `rate.reasoning`, which nothing here reads
+ * yet, by design: inventing a reasoning charge the table does not publish
+ * would be exactly the kind of invented price this module exists to avoid. */
+const KIND_KEYS = ['input', 'cacheRead', 'cacheWrite', 'output'];
+
+/**
+ * Price one model's cache-write tokens, splitting the long-TTL (refresh)
+ * subset from the short-TTL rest exactly as `core/pricing.js`'s
+ * `estimateCost` does, but folded into the single "cache write" kind the
+ * spec lists (no separate "cache refresh" row).
+ * @param {{cacheWrite:number, cacheRefresh:number}} tok
+ * @param {{cacheWrite:number|null|undefined, cacheRefresh:number|null|undefined}} rate
+ * @returns {{value:number|null, partial:boolean}}
+ */
+function priceCacheWrite(tok, rate) {
+  const refresh = tok.cacheRefresh || 0;
+  const write = tok.cacheWrite || 0;
+  const shortWrite = Math.max(0, write - refresh);
+  const haveRefreshRate = rate.cacheRefresh !== null && rate.cacheRefresh !== undefined;
+  const haveWriteRate = rate.cacheWrite !== null && rate.cacheWrite !== undefined;
+  if (haveRefreshRate && haveWriteRate) {
+    return { value: (shortWrite / 1e6) * rate.cacheWrite + (refresh / 1e6) * rate.cacheRefresh, partial: false };
+  }
+  if (haveWriteRate) {
+    // No distinct refresh rate published: bill the whole write total,
+    // refresh subset included, at the plain write rate. This is the same
+    // fallback core/pricing.js's estimateCost takes.
+    return { value: (write / 1e6) * rate.cacheWrite, partial: false };
+  }
+  return { value: write > 0 ? null : 0, partial: write > 0 };
+}
+
+/**
+ * Price one model's token counts against one resolved rate entry.
+ * @param {{input:number, output:number, cacheRead:number, cacheWrite:number, cacheRefresh:number}} tok
+ * @param {{in:number, out:number, cacheRead:number|null, cacheWrite:number|null, cacheRefresh:number|null}|null} rate
+ * @returns {{byKind:Record<string, number|null>, total:number|null, partial:boolean}}
+ */
+function priceTokens(tok, rate) {
+  if (!rate) {
+    const na = Object.fromEntries(KIND_KEYS.map((k) => [k, null]));
+    return { byKind: na, total: null, partial: false };
+  }
+  /** @type {Record<string, number|null>} */
+  const byKind = {};
+  let total = 0;
+  let partial = false;
+  const simple = (key, tokens, r) => {
+    const t = tokens || 0;
+    if (r === null || r === undefined || !Number.isFinite(r)) {
+      byKind[key] = t > 0 ? null : 0;
+      if (t > 0) partial = true;
+      return;
+    }
+    const cost = (t / 1e6) * r;
+    byKind[key] = cost;
+    total += cost;
+  };
+  simple('input', tok.input, rate.in);
+  simple('output', tok.output, rate.out);
+  simple('cacheRead', tok.cacheRead, rate.cacheRead);
+  const cw = priceCacheWrite(tok, rate);
+  byKind.cacheWrite = cw.value;
+  if (cw.value !== null) total += cw.value;
+  if (cw.partial) partial = true;
+  return { byKind, total, partial };
+}
+
+/**
+ * Reprice a set of per-model aggregate rows at another model's rates.
+ *
+ * @param {{
+ *   rows: {key:string, provider:string, total:number, requests:number,
+ *          input:number, output:number, cacheRead:number, cacheWrite:number,
+ *          cacheRefresh:number}[],
+ *   book: {lookup:(model:string, provider:string)=>({in:number,out:number,
+ *          cacheRead:number|null,cacheWrite:number|null,cacheRefresh:number|null}|null)},
+ *   mapping?: Record<string,string>,
+ * }} args `rows` is the per-model aggregate the Cost view already computes
+ *   (`view.dimensions.models`, or any subset of it for the current filters).
+ *   `mapping` is `{ fromModel: toModel }`; a model absent from `mapping`
+ *   reprices against itself (identity, zero delta).
+ * @returns {{
+ *   models: {model:string, provider:string, target:string, tokens:number,
+ *     requests:number, current:number|null, currentByKind:Record<string,number|null>,
+ *     whatif:number|null, whatifByKind:Record<string,number|null>,
+ *     delta:number|null, partial:boolean}[],
+ *   overall: {current:number|null, whatif:number|null, delta:number|null,
+ *     excluded:number, partial:boolean},
+ * }}
+ */
+export function reprice({ rows, book, mapping = {} }) {
+  const models = (rows || []).map((row) => {
+    const target = mapping[row.key] ?? row.key;
+    const tok = {
+      input: row.input, output: row.output,
+      cacheRead: row.cacheRead, cacheWrite: row.cacheWrite, cacheRefresh: row.cacheRefresh,
+    };
+    const fromRate = book.lookup(row.key, row.provider);
+    const toRate = book.lookup(target, row.provider);
+    const cur = priceTokens(tok, fromRate);
+    const wi = priceTokens(tok, toRate);
+    const delta = cur.total !== null && wi.total !== null ? wi.total - cur.total : null;
+    return {
+      model: row.key,
+      provider: row.provider,
+      target,
+      tokens: row.total,
+      requests: row.requests,
+      current: cur.total,
+      currentByKind: cur.byKind,
+      whatif: wi.total,
+      whatifByKind: wi.byKind,
+      delta,
+      // A gap on either side of the mapping is still a gap: either number
+      // being incomplete makes the pairing incomplete.
+      partial: cur.partial || wi.partial,
+    };
+  });
+
+  // A model missing on either side cannot honestly contribute to an overall
+  // current/what-if/delta trio: the three must stay `delta === whatif -
+  // current`, which only holds over the same set of rows on all three.
+  const comparable = models.filter((m) => m.current !== null && m.whatif !== null);
+  const sum = (get) => comparable.reduce((a, m) => a + get(m), 0);
+  const overall = {
+    current: comparable.length ? sum((m) => m.current) : null,
+    whatif: comparable.length ? sum((m) => m.whatif) : null,
+    delta: comparable.length ? sum((m) => m.delta) : null,
+    excluded: models.length - comparable.length,
+    partial: models.length > comparable.length || models.some((m) => m.partial),
+  };
+  return { models, overall };
+}
+
+// ---------------------------------------------------------- target list ----
+
+const SRC_PROVIDER = {
+  anthropic: 'Anthropic',
+  openai: 'OpenAI',
+  'openai-thirdparty': 'OpenAI',
+  deepseek: 'DeepSeek',
+  zai: 'Z.ai',
+  google: 'Google',
+};
+
+/** Prefix fallback for entries whose `src` does not name a provider directly
+ * (`legacy`, `user`): only changes which optgroup a name is filed under, not
+ * any rate, since every shipped rate is looked up by model name alone. */
+function inferProvider(name) {
+  if (/^claude/i.test(name)) return 'Anthropic';
+  if (/^(gpt|o3|o4|chat)/i.test(name)) return 'OpenAI';
+  if (/^deepseek/i.test(name)) return 'DeepSeek';
+  if (/^gemini/i.test(name)) return 'Google';
+  if (/^glm/i.test(name)) return 'Z.ai';
+  return 'Other';
+}
+
+/**
+ * The first top-level alternative of a regex source string: the substring
+ * up to the first `|` that sits outside any `(...)` group.
+ * @param {string} pattern
+ * @returns {string}
+ */
+function firstTopLevelAlt(pattern) {
+  let depth = 0;
+  for (let i = 0; i < pattern.length; i++) {
+    const ch = pattern[i];
+    if (ch === '\\') { i++; continue; }
+    if (ch === '(') depth++;
+    else if (ch === ')') depth--;
+    else if (ch === '|' && depth === 0) return pattern.slice(0, i);
+  }
+  return pattern;
+}
+
+/**
+ * Turn one `BUILTIN_PRICES`-style `match` regex into one representative,
+ * literal model name: take the first top-level alternative, drop the
+ * anchors, and resolve every `(...)` group to its own first alternative. An
+ * alternative that is bare `$` (an end-of-string anchor standing in for
+ * "nothing more") resolves to the empty string, not the literal text "$".
+ * @param {string} pattern
+ * @returns {string}
+ */
+export function deriveModelName(pattern) {
+  let s = firstTopLevelAlt(pattern);
+  s = s.replace(/^\^/, '').replace(/\$$/, '');
+  s = s.replace(/\(([^()]*)\)/g, (_, inner) => {
+    const alt = firstTopLevelAlt(inner);
+    return alt === '$' ? '' : alt;
+  });
+  s = s.replace(/\\(.)/g, '$1');
+  return s;
+}
+
+/**
+ * Every target a "reprice at" select may offer: one representative name per
+ * price-table entry (builtin and user overrides), unioned with every priced
+ * model actually seen in the dataset. That way migrating *to* a model you
+ * have never used is possible, and a model an imperfect regex-derivation
+ * missed is not silently dropped just because it showed up in real usage.
+ * Every name is round-tripped through `book.lookup` before being offered, so
+ * a derivation slip never produces an option that reprices to n/a.
+ * @param {{book:object, seenModels?:({value:string}|string)[]}} args
+ * @returns {{name:string, provider:string}[]} sorted by provider, then name.
+ */
+export function targetModelOptions({ book, seenModels = [] }) {
+  const byName = new Map();
+  for (const e of book.entries || []) {
+    const name = e.origin === 'user' ? e.key : deriveModelName(e.match);
+    if (!name || byName.has(name)) continue;
+    if (!book.lookup(name, 'unknown')) continue;
+    byName.set(name, SRC_PROVIDER[e.src] || inferProvider(name));
+  }
+  for (const s of seenModels) {
+    const name = typeof s === 'string' ? s : s.value;
+    if (!name || byName.has(name)) continue;
+    if (!book.lookup(name, 'unknown')) continue;
+    byName.set(name, inferProvider(name));
+  }
+  return [...byName.entries()]
+    .map(([name, provider]) => ({ name, provider }))
+    .sort((a, b) => (a.provider === b.provider ? a.name.localeCompare(b.name) : a.provider.localeCompare(b.provider)));
+}

package/src/commands/budget-scopes.js

@@ -0,0 +1,133 @@
+/**
+ * `tokenflow budget` scoped budgets — repo and team caps alongside the single
+ * monthly budget in src/core/budget.js.
+ *
+ * Config (config.yaml):
+ *
+ *   budgets:
+ *     - id: api-monthly
+ *       scope: repo            # total | repo | team
+ *       repo: api                # required when scope is repo; matched against
+ *                                # the same repository identity `receipt` uses
+ *                                # (worktrees folded into their main checkout)
+ *       monthlyUsd: 150
+ *       warnAt: 0.8             # optional, default 0.8 (a fraction, like limits[].warnAt)
+ *
+ * "Spent" per scope, this calendar month (UTC date, same convention `tokenflow
+ * budget` already uses for the single monthly cap):
+ *   - total: every priced turn in the store this month.
+ *   - repo:  turns this month attributed to that repository, resolved the same
+ *            way `tokenflow receipt` resolves it (worktrees folded into their
+ *            main checkout) — a plain `project`/`repository` field match would
+ *            split one repo's spend across every worktree it ever had.
+ *   - team:  this machine's shared sync folder (`sync.dir`), if enabled; the
+ *            budget engine never invents a team total nobody's synced.
+ *
+ * Repo/team scope needs a fresh, month-bounded receipt pass (buildReceiptsForStore
+ * caches the *whole* store with no date window, so it cannot answer "this
+ * month" by itself) — built here with the exact same pieces buildReceiptsForStore
+ * uses internally (createReceiptBuilder + makeRepoResolver). buildReceiptsForStore
+ * itself is still called, to tell "this repo has no spend yet this month" apart
+ * from "this repo has never been seen in the store" in the row's note.
+ */
+import { paths } from '../core/config.js';
+import { Store, readJson, decodeRecord } from '../core/store.js';
+import { buildPriceBook } from '../core/pricing.js';
+import { MEASUREMENT } from '../core/schema.js';
+import { makeRepoResolver } from '../core/repo.js';
+import { createReceiptBuilder } from '../analytics/receipt.js';
+import { buildReceiptsForStore } from '../core/bundle.js';
+import { isEnabled, syncDir } from '../core/sync.js';
+import { aggregate } from '../core/team.js';
+import { scopedBudgetState } from '../core/budget.js';
+import { usd, pct } from '../core/units.js';
+
+function monthWindow(now) {
+  const d = now instanceof Date ? now : new Date(now || Date.now());
+  const today = d.toISOString().slice(0, 10);
+  return { from: `${today.slice(0, 7)}-01`, to: today };
+}
+
+/**
+ * @param {object} b configured budget entry
+ * @param {{spentUsd:number, note?:string}} extra
+ */
+function row(b, { spentUsd, note }) {
+  const st = scopedBudgetState({
+    spentUsd,
+    monthlyUsd: b.monthlyUsd,
+    warnAt: typeof b.warnAt === 'number' ? b.warnAt : 0.8,
+  });
+  const label = b.scope === 'repo' ? (b.repo || b.id) : b.scope === 'team' ? 'Team' : 'Total';
+  return {
+    id: b.id,
+    scope: b.scope,
+    label,
+    spentUsd: st.spentUsd,
+    monthlyUsd: st.monthlyUsd,
+    share: st.share,
+    state: st.state,
+    note: note || null,
+  };
+}
+
+/**
+ * Evaluate every configured scoped budget against this month's spend.
+ * @param {{config?:object, store?:object, now?:Date|string}} [opt]
+ * @returns {object[]} rows: `{id, scope, label, spentUsd, monthlyUsd, share, state, note}`
+ */
+export function evaluateScopedBudgets({ config, store, now } = {}) {
+  const cfg = config || {};
+  const budgets = Array.isArray(cfg.budgets) ? cfg.budgets : [];
+  const valid = budgets.filter((b) => b && b.id && b.scope && b.monthlyUsd > 0);
+  if (!valid.length) return [];
+
+  const st = store || new Store();
+  const { from, to } = monthWindow(now);
+  const pricing = readJson(paths().pricing, {});
+  const book = buildPriceBook(pricing);
+
+  // One month-bounded receipts pass, reused by every total/repo row below.
+  const builder = createReceiptBuilder({ book, repoOf: makeRepoResolver() });
+  st.scanRecords((o) => {
+    if (o.ms !== MEASUREMENT.PRIMARY) return;
+    if (o.d < from || o.d > to) return;
+    builder.add(decodeRecord(o));
+  });
+  const scoped = builder.finish();
+
+  const rows = [];
+  for (const b of valid) {
+    if (b.scope === 'total') {
+      rows.push(row(b, { spentUsd: scoped.totals.cost ?? 0 }));
+    } else if (b.scope === 'repo') {
+      const R = scoped.repos.find((r) => r.repo === b.repo);
+      if (R) {
+        rows.push(row(b, { spentUsd: R.cost ?? 0 }));
+      } else {
+        const allTime = buildReceiptsForStore(st, pricing);
+        const known = allTime.repos.some((r) => r.repo === b.repo);
+        rows.push(row(b, { spentUsd: 0, note: known ? 'no spend this month' : 'repository not seen in the store' }));
+      }
+    } else if (b.scope === 'team') {
+      if (!isEnabled(cfg)) { rows.push(row(b, { spentUsd: 0, note: 'no team data' })); continue; }
+      const dir = syncDir(cfg);
+      const team = aggregate(dir, { from, to });
+      if (!team) { rows.push(row(b, { spentUsd: 0, note: 'no team data' })); continue; }
+      rows.push(row(b, { spentUsd: team.totals.estCostUsd || 0 }));
+    }
+  }
+  return rows;
+}
+
+/** @param {object[]} rows from evaluateScopedBudgets() */
+export function renderScopedBudgets(rows) {
+  if (!rows.length) return 'No scoped budgets configured. Add one to config.yaml under `budgets:`.';
+  const L = [];
+  for (const r of rows) {
+    const tag = r.state === 'over' ? 'OVER' : r.state === 'warn' ? 'WARN' : 'ok';
+    const shareTxt = pct(r.share, 0, 'n/a');
+    L.push(`[${tag}] ${r.label} (${r.scope}): ${usd(r.spentUsd, 'n/a')} of ${usd(r.monthlyUsd, 'n/a')} (${shareTxt})${r.note ? `  ${r.note}` : ''}`);
+  }
+  return L.join('\n');
+}