@cohortapp/agent-sdk 2.3.0

package/scripts/cost/fleet-digest.mjs

@@ -0,0 +1,407 @@
+#!/usr/bin/env node
+/**
+ * scripts/cost/fleet-digest.mjs — aggregate LLM cost across the agent fleet into
+ * a daily digest (SPEC §8.4, graft #7).
+ *
+ * Two cost sources, additive and fail-open:
+ *   1. the LOCAL router ledger (state/cost-tracking/<day>.jsonl — the file
+ *      budget-guard sums; one row per session/llmTask with agent/model/cache
+ *      token columns), and
+ *   2. OPTIONALLY the Cohort org-wide cost.rollup (lib/org/client costRollup),
+ *      which already aggregates the whole fleet server-side.
+ *
+ * The digest is `{ day, totalUSD, byAgent, byModel, cacheReadRatio, topSpenders,
+ * sessions, source }`. `cacheReadRatio` is the headline KPI (§6.5 rule 5):
+ *   cache_read / (input + cache_read + cache_creation)   target >= 60%.
+ * A regression here is the single most expensive invisible bug in the program,
+ * so it is computed from the raw token columns, not inferred from cost.
+ *
+ * Exposes a cadence-friendly `fleetDigest(o)` (pure over the FS + injected
+ * `rollupImpl`/`fetchImpl`; NEVER throws) AND a CLI:
+ *
+ *     node scripts/cost/fleet-digest.mjs [--day YYYY-MM-DD] [--json] [--org]
+ *
+ * `--org` adds the Cohort rollup leg (requires the agent config + token); without
+ * it the digest is local-only (this agent's ledger). The cost-rollup cadence calls
+ * `fleetDigest({ org:true, cfg })` and posts the result to the first configured
+ * sink (org registry → Slack #fleet-llm-spend → Drive drop) — that posting is the
+ * caller's job; this module only BUILDS the digest.
+ *
+ * House style (lib/org/cost-sync.mjs, scripts/cost/track-claude-usage.mjs): ESM
+ * .mjs, Node builtins + the org client, fail-open, everything injectable.
+ *
+ * @module scripts/cost/fleet-digest
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve as resolvePath, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// ---------------------------------------------------------------------------
+// Local ledger read (mirror of lib/model-router/ledger.mjs / cost-sync.mjs)
+// ---------------------------------------------------------------------------
+
+function ledgerDir(o = {}) {
+  if (o.ledgerDir) return resolvePath(o.ledgerDir);
+  const root =
+    o.agentRoot || process.env.AGENT_ROOT || process.env.AGENT_DIR || resolvePath(__dirname, "..", "..");
+  return join(resolvePath(root), "state", "cost-tracking");
+}
+
+function dayStr(o = {}) {
+  if (o.day) return String(o.day);
+  const now = typeof o.now === "function" ? o.now() : Date.now();
+  return new Date(now).toISOString().slice(0, 10);
+}
+
+function ledgerFile(o = {}) {
+  return join(ledgerDir(o), `${dayStr(o)}.jsonl`);
+}
+
+function readLedgerRows(o = {}) {
+  const file = ledgerFile(o);
+  if (!existsSync(file)) return [];
+  let body;
+  try {
+    body = readFileSync(file, "utf-8");
+  } catch {
+    return [];
+  }
+  const rows = [];
+  for (const line of body.split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      rows.push(JSON.parse(line));
+    } catch {
+      /* skip a corrupt line */
+    }
+  }
+  return rows;
+}
+
+function numOr0(v) {
+  const n = Number(v);
+  return Number.isFinite(n) ? n : 0;
+}
+
+function pickUSD(row) {
+  const est = Number(row.estimated_usd);
+  if (Number.isFinite(est)) return est;
+  const total = Number(row.total_cost_usd);
+  return Number.isFinite(total) ? total : 0;
+}
+
+// ---------------------------------------------------------------------------
+// Aggregation
+// ---------------------------------------------------------------------------
+
+/**
+ * Aggregate an array of ledger-shaped rows into the digest skeleton. PURE. NEVER
+ * throws. Used for both the local leg and a flattened org-rollup leg (the rollup
+ * payload's rows carry the same agent/model/token columns).
+ *
+ * @param {object[]} rows
+ * @returns {{ totalUSD:number, sessions:number, byAgent:Record<string,number>,
+ *             byModel:Record<string,number>, cacheReadRatio:number,
+ *             tokens:{input:number, cache_read:number, cache_creation:number} }}
+ */
+export function aggregateRows(rows) {
+  const list = Array.isArray(rows) ? rows : [];
+  const byAgent = {};
+  const byModel = {};
+  let totalUSD = 0;
+  let sessions = 0;
+  let input = 0;
+  let cacheRead = 0;
+  let cacheCreation = 0;
+
+  for (const row of list) {
+    if (!row || typeof row !== "object") continue;
+    sessions += 1;
+    const usd = pickUSD(row);
+    totalUSD += usd;
+
+    const agent = row.agent || "unknown";
+    byAgent[agent] = round6((byAgent[agent] || 0) + usd);
+
+    const model = row.model || row.backend || "unknown";
+    byModel[model] = round6((byModel[model] || 0) + usd);
+
+    input += numOr0(row.input_tokens);
+    cacheRead += numOr0(row.cache_read_tokens);
+    cacheCreation += numOr0(row.cache_creation_tokens);
+  }
+
+  // cacheReadRatio = cache_read / (input + cache_read + cache_creation).
+  // NOTE: ledger `input_tokens` is the MISS input (the cache_read portion is a
+  // separate column), so the denominator is the sum of all three — the true
+  // total prompt token volume.
+  const denom = input + cacheRead + cacheCreation;
+  const cacheReadRatio = denom > 0 ? round4(cacheRead / denom) : 0;
+
+  return {
+    totalUSD: round6(totalUSD),
+    sessions,
+    byAgent,
+    byModel,
+    cacheReadRatio,
+    tokens: { input, cache_read: cacheRead, cache_creation: cacheCreation },
+  };
+}
+
+/**
+ * Rank agents by spend, descending. PURE.
+ * @param {Record<string,number>} byAgent
+ * @param {number} [limit=5]
+ * @returns {Array<{ agent:string, usd:number }>}
+ */
+export function topSpenders(byAgent, limit = 5) {
+  return Object.entries(byAgent || {})
+    .map(([agent, usd]) => ({ agent, usd: round6(usd) }))
+    .sort((a, b) => b.usd - a.usd)
+    .slice(0, Math.max(0, limit));
+}
+
+// ---------------------------------------------------------------------------
+// fleetDigest — the cadence-friendly entry point
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the daily fleet cost digest. NEVER throws — always resolves a digest;
+ * the org leg fails open (a disabled/unreachable server contributes nothing).
+ *
+ * Source precedence:
+ *   - `org:true` + a reachable Cohort rollup → the rollup is the fleet-wide
+ *     truth (it already aggregates every agent); `source:"org-rollup"`.
+ *   - otherwise → the local ledger only (this agent); `source:"local"`.
+ *   - if BOTH are requested and the rollup is empty/unavailable → fall back to
+ *     local with a note.
+ *
+ * @param {object} o
+ *   @param {string}   [o.day]
+ *   @param {string}   [o.ledgerDir]
+ *   @param {string}   [o.agentRoot]
+ *   @param {()=>number} [o.now]
+ *   @param {boolean}  [o.org]          add the Cohort cost.rollup leg
+ *   @param {object}   [o.cfg]          agent config (for the org client)
+ *   @param {function} [o.rollupImpl]   async (o) => rollup payload — overrides the
+ *                                      org client (tests / alt sinks)
+ *   @param {function} [o.fetchImpl]    passed through to the org client
+ *   @param {number}   [o.topN=5]
+ * @returns {Promise<{
+ *   day:string, totalUSD:number, sessions:number,
+ *   byAgent:Record<string,number>, byModel:Record<string,number>,
+ *   cacheReadRatio:number, cacheReadKpiOk:boolean,
+ *   topSpenders:Array<{agent:string,usd:number}>,
+ *   source:"org-rollup"|"local", notes:string[]
+ * }>}
+ */
+export async function fleetDigest(o = {}) {
+  const day = dayStr(o);
+  const topN = Number.isFinite(o.topN) ? o.topN : 5;
+  const notes = [];
+
+  // Always compute the local leg (cheap, and the fallback).
+  const localRows = readLedgerRows(o);
+  const local = aggregateRows(localRows);
+
+  let chosen = local;
+  let source = "local";
+
+  if (o.org) {
+    const rollup = await fetchRollup(o, day, notes);
+    const agg = rollup ? aggregateFromRollup(rollup) : null;
+    if (agg && agg.sessions > 0) {
+      chosen = agg;
+      source = "org-rollup";
+    } else {
+      notes.push("org rollup unavailable/empty — using local ledger");
+    }
+  }
+
+  const kpiTarget = 0.6;
+  return {
+    day,
+    totalUSD: chosen.totalUSD,
+    sessions: chosen.sessions,
+    byAgent: chosen.byAgent,
+    byModel: chosen.byModel,
+    cacheReadRatio: chosen.cacheReadRatio,
+    cacheReadKpiOk: chosen.cacheReadRatio >= kpiTarget,
+    topSpenders: topSpenders(chosen.byAgent, topN),
+    source,
+    notes,
+  };
+}
+
+/**
+ * Fetch the org-wide cost rollup, fail-open. Prefers an injected `rollupImpl`
+ * (tests / a non-Cohort sink); else uses lib/org/client costRollup when the
+ * agent config enables Cohort. NEVER throws.
+ */
+async function fetchRollup(o, day, notes) {
+  if (typeof o.rollupImpl === "function") {
+    try {
+      return await o.rollupImpl({ ...o, day });
+    } catch {
+      notes.push("rollupImpl threw");
+      return null;
+    }
+  }
+  // Lazy-import the org client so the module loads without org config present.
+  let client;
+  try {
+    client = await import("../../lib/org/client.mjs");
+  } catch {
+    notes.push("org client unavailable");
+    return null;
+  }
+  if (!client.isEnabled || !client.isEnabled(o.cfg)) {
+    notes.push("org (cohort) not enabled");
+    return null;
+  }
+  const c = client.configFromAgent(o.cfg);
+  try {
+    return await client.costRollup({ base: c.base, token: c.token, day, fetchImpl: o.fetchImpl });
+  } catch {
+    notes.push("costRollup threw");
+    return null;
+  }
+}
+
+/**
+ * Normalise an org cost.rollup payload into the aggregate shape. The rollup may
+ * arrive already aggregated (`{ byAgent, byModel, totalUSD, cacheReadRatio }`) OR
+ * as raw rows (`{ rows:[…] }`); we handle both. PURE. NEVER throws.
+ */
+export function aggregateFromRollup(payload) {
+  if (!payload || typeof payload !== "object") {
+    return { totalUSD: 0, sessions: 0, byAgent: {}, byModel: {}, cacheReadRatio: 0, tokens: { input: 0, cache_read: 0, cache_creation: 0 } };
+  }
+  // Raw rows → reuse the row aggregator.
+  if (Array.isArray(payload.rows)) {
+    return aggregateRows(payload.rows);
+  }
+  // Pre-aggregated → trust the server's figures, but recompute the KPI from
+  // tokens when present (so a stale server-side ratio can't mask a regression).
+  const byAgent = sanitizeUsdMap(payload.byAgent || payload.by_agent);
+  const byModel = sanitizeUsdMap(payload.byModel || payload.by_model);
+  const totalUSD = Number.isFinite(Number(payload.totalUSD ?? payload.total_usd))
+    ? round6(Number(payload.totalUSD ?? payload.total_usd))
+    : round6(Object.values(byAgent).reduce((s, v) => s + v, 0));
+  const sessions = Number.isFinite(Number(payload.sessions)) ? Number(payload.sessions) : Object.keys(byAgent).length;
+
+  const tokens = payload.tokens && typeof payload.tokens === "object" ? payload.tokens : null;
+  let cacheReadRatio;
+  if (tokens) {
+    const denom = numOr0(tokens.input) + numOr0(tokens.cache_read) + numOr0(tokens.cache_creation);
+    cacheReadRatio = denom > 0 ? round4(numOr0(tokens.cache_read) / denom) : 0;
+  } else {
+    cacheReadRatio = Number.isFinite(Number(payload.cacheReadRatio ?? payload.cache_read_ratio))
+      ? round4(Number(payload.cacheReadRatio ?? payload.cache_read_ratio))
+      : 0;
+  }
+
+  return {
+    totalUSD,
+    sessions,
+    byAgent,
+    byModel,
+    cacheReadRatio,
+    tokens: tokens || { input: 0, cache_read: 0, cache_creation: 0 },
+  };
+}
+
+function sanitizeUsdMap(m) {
+  const out = {};
+  if (!m || typeof m !== "object") return out;
+  for (const [k, v] of Object.entries(m)) {
+    const n = Number(v);
+    if (Number.isFinite(n)) out[String(k)] = round6(n);
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function round4(n) {
+  return Number(Number(n).toFixed(4));
+}
+function round6(n) {
+  return Number(Number(n).toFixed(6));
+}
+
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+
+function parseArgs(argv) {
+  const o = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--day") o.day = argv[++i];
+    else if (a === "--json") o.json = true;
+    else if (a === "--org") o.org = true;
+    else if (a === "--top") o.topN = Number(argv[++i]);
+  }
+  return o;
+}
+
+async function loadAgentConfig() {
+  // Best-effort: read config/agent.json for the org client (fail-open).
+  const root = process.env.AGENT_ROOT || process.env.AGENT_DIR || resolvePath(__dirname, "..", "..");
+  const p = join(resolvePath(root), "config", "agent.json");
+  if (!existsSync(p)) return null;
+  try {
+    return JSON.parse(readFileSync(p, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+function formatDigest(d) {
+  const pct = (n) => `${(n * 100).toFixed(1)}%`;
+  const lines = [];
+  lines.push(`Fleet LLM spend — ${d.day} (${d.source})`);
+  lines.push(`  total: $${d.totalUSD}   sessions: ${d.sessions}`);
+  lines.push(`  cache-read ratio: ${pct(d.cacheReadRatio)} ${d.cacheReadKpiOk ? "(OK)" : "(BELOW 60% TARGET)"}`);
+  if (d.topSpenders.length) {
+    lines.push("  top spenders:");
+    for (const t of d.topSpenders) lines.push(`    ${t.agent}: $${t.usd}`);
+  }
+  const models = Object.entries(d.byModel).sort((a, b) => b[1] - a[1]);
+  if (models.length) {
+    lines.push("  by model:");
+    for (const [m, usd] of models) lines.push(`    ${m}: $${usd}`);
+  }
+  if (d.notes.length) lines.push(`  notes: ${d.notes.join("; ")}`);
+  return lines.join("\n");
+}
+
+async function main() {
+  const o = parseArgs(process.argv.slice(2));
+  if (o.org) o.cfg = await loadAgentConfig();
+  const digest = await fleetDigest(o);
+  if (o.json) {
+    process.stdout.write(JSON.stringify(digest, null, 2) + "\n");
+  } else {
+    process.stdout.write(formatDigest(digest) + "\n");
+  }
+}
+
+// Run as a CLI only when invoked directly (not when imported by the cadence/tests).
+if (process.argv[1] && resolvePath(process.argv[1]) === resolvePath(__filename)) {
+  main().catch((err) => {
+    process.stderr.write(`fleet-digest failed: ${err && err.message}\n`);
+    process.exitCode = 1;
+  });
+}
+
+export const _internals = { ledgerFile, dayStr, readLedgerRows, pickUSD, formatDigest };
+
+export default { fleetDigest, aggregateRows, aggregateFromRollup, topSpenders };

package/scripts/cost/fleet-digest.test.mjs

@@ -0,0 +1,207 @@
+/**
+ * Tests for scripts/cost/fleet-digest.mjs — the daily fleet cost digest.
+ * Covers: local-ledger aggregation (byAgent/byModel/totalUSD), the cacheReadRatio
+ * KPI computed from raw token columns (incl. the >=60% target flag), top spenders,
+ * and the optional org-rollup leg (injected rollupImpl, both pre-aggregated and
+ * raw-rows shapes) with fail-open fallback to local.
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  fleetDigest,
+  aggregateRows,
+  aggregateFromRollup,
+  topSpenders,
+} from "./fleet-digest.mjs";
+
+const DAY = "2026-06-10";
+
+function tmpLedger(rows, day = DAY) {
+  const dir = mkdtempSync(join(tmpdir(), "fleet-digest-"));
+  const ledgerDir = join(dir, "state", "cost-tracking");
+  mkdirSync(ledgerDir, { recursive: true });
+  writeFileSync(join(ledgerDir, `${day}.jsonl`), rows.map((r) => JSON.stringify(r)).join("\n") + "\n");
+  return { ledgerDir, dir };
+}
+
+// ---------------------------------------------------------------------------
+// aggregateRows — the pure aggregator
+// ---------------------------------------------------------------------------
+
+test("aggregateRows: byAgent + byModel + total", () => {
+  const a = aggregateRows([
+    { agent: "alex", model: "claude-sonnet-4-6", estimated_usd: 2.0 },
+    { agent: "alex", model: "claude-haiku-4-5", estimated_usd: 0.5 },
+    { agent: "robin", model: "claude-sonnet-4-6", estimated_usd: 1.0 },
+  ]);
+  assert.equal(a.totalUSD, 3.5);
+  assert.equal(a.sessions, 3);
+  assert.equal(a.byAgent.alex, 2.5);
+  assert.equal(a.byAgent.robin, 1.0);
+  assert.equal(a.byModel["claude-sonnet-4-6"], 3.0);
+  assert.equal(a.byModel["claude-haiku-4-5"], 0.5);
+});
+
+test("aggregateRows: cacheReadRatio from raw token columns", () => {
+  // input(miss)=200, cache_read=800, cache_creation=0 → 800/1000 = 0.8
+  const a = aggregateRows([
+    { agent: "a", model: "m", estimated_usd: 1, input_tokens: 200, cache_read_tokens: 800, cache_creation_tokens: 0 },
+  ]);
+  assert.equal(a.cacheReadRatio, 0.8);
+  assert.equal(a.tokens.cache_read, 800);
+});
+
+test("aggregateRows: cacheReadRatio denominator includes cache_creation", () => {
+  // input=100, cache_read=100, cache_creation=300 → 100/500 = 0.2
+  const a = aggregateRows([
+    { agent: "a", model: "m", estimated_usd: 1, input_tokens: 100, cache_read_tokens: 100, cache_creation_tokens: 300 },
+  ]);
+  assert.equal(a.cacheReadRatio, 0.2);
+});
+
+test("aggregateRows: no tokens → ratio 0, never NaN", () => {
+  const a = aggregateRows([{ agent: "a", model: "m", estimated_usd: 1 }]);
+  assert.equal(a.cacheReadRatio, 0);
+});
+
+test("aggregateRows: empty input → zeroed digest, never throws", () => {
+  const a = aggregateRows([]);
+  assert.equal(a.totalUSD, 0);
+  assert.equal(a.sessions, 0);
+  assert.deepEqual(a.byAgent, {});
+});
+
+test("aggregateRows: total_cost_usd fallback when estimated_usd absent", () => {
+  const a = aggregateRows([{ agent: "a", model: "m", total_cost_usd: 4.0 }]);
+  assert.equal(a.totalUSD, 4.0);
+});
+
+// ---------------------------------------------------------------------------
+// topSpenders
+// ---------------------------------------------------------------------------
+
+test("topSpenders: ranks descending and limits", () => {
+  const t = topSpenders({ alex: 5, robin: 9, sam: 1 }, 2);
+  assert.deepEqual(t, [{ agent: "robin", usd: 9 }, { agent: "alex", usd: 5 }]);
+});
+
+// ---------------------------------------------------------------------------
+// fleetDigest — local leg
+// ---------------------------------------------------------------------------
+
+test("fleetDigest: local-only digest from a tmp ledger", async () => {
+  const { ledgerDir } = tmpLedger([
+    { agent: "alex", model: "claude-sonnet-4-6", estimated_usd: 3.0, input_tokens: 100, cache_read_tokens: 900, cache_creation_tokens: 0 },
+    { agent: "robin", model: "claude-haiku-4-5", estimated_usd: 1.0, input_tokens: 50, cache_read_tokens: 50, cache_creation_tokens: 0 },
+  ]);
+  const d = await fleetDigest({ ledgerDir, day: DAY });
+  assert.equal(d.source, "local");
+  assert.equal(d.totalUSD, 4.0);
+  assert.equal(d.sessions, 2);
+  assert.equal(d.byAgent.alex, 3.0);
+  assert.equal(d.topSpenders[0].agent, "alex");
+  // combined cache ratio: cache_read=950, denom=100+900+50+50+0 = 1100 → 950/1100
+  assert.equal(d.cacheReadRatio, Number((950 / 1100).toFixed(4)));
+});
+
+test("fleetDigest: cacheReadKpiOk reflects the >=60% target", async () => {
+  const okLedger = tmpLedger([
+    { agent: "a", model: "m", estimated_usd: 1, input_tokens: 100, cache_read_tokens: 900, cache_creation_tokens: 0 },
+  ]);
+  const okDigest = await fleetDigest({ ledgerDir: okLedger.ledgerDir, day: DAY });
+  assert.equal(okDigest.cacheReadKpiOk, true);
+
+  const badLedger = tmpLedger([
+    { agent: "a", model: "m", estimated_usd: 1, input_tokens: 900, cache_read_tokens: 100, cache_creation_tokens: 0 },
+  ]);
+  const badDigest = await fleetDigest({ ledgerDir: badLedger.ledgerDir, day: DAY });
+  assert.equal(badDigest.cacheReadKpiOk, false);
+});
+
+test("fleetDigest: missing ledger → empty digest, never throws", async () => {
+  const d = await fleetDigest({ ledgerDir: "/nonexistent", day: DAY });
+  assert.equal(d.totalUSD, 0);
+  assert.equal(d.sessions, 0);
+  assert.equal(d.source, "local");
+});
+
+// ---------------------------------------------------------------------------
+// fleetDigest — org rollup leg (injected rollupImpl)
+// ---------------------------------------------------------------------------
+
+test("fleetDigest: org leg with pre-aggregated rollup payload", async () => {
+  const { ledgerDir } = tmpLedger([{ agent: "alex", model: "m", estimated_usd: 1.0 }]);
+  const rollupImpl = async () => ({
+    totalUSD: 120.5,
+    byAgent: { alex: 60, robin: 40.5, sam: 20 },
+    byModel: { "claude-sonnet-4-6": 100, "claude-haiku-4-5": 20.5 },
+    sessions: 42,
+    tokens: { input: 1000, cache_read: 4000, cache_creation: 0 }, // 4000/5000 = 0.8
+  });
+  const d = await fleetDigest({ ledgerDir, day: DAY, org: true, rollupImpl });
+  assert.equal(d.source, "org-rollup");
+  assert.equal(d.totalUSD, 120.5);
+  assert.equal(d.sessions, 42);
+  assert.equal(d.cacheReadRatio, 0.8);
+  assert.equal(d.topSpenders[0].agent, "alex");
+  assert.equal(d.topSpenders[0].usd, 60);
+});
+
+test("fleetDigest: org leg with raw-rows rollup payload", async () => {
+  const { ledgerDir } = tmpLedger([{ agent: "x", model: "m", estimated_usd: 999 }]);
+  const rollupImpl = async () => ({
+    rows: [
+      { agent: "alex", model: "claude-sonnet-4-6", estimated_usd: 10, input_tokens: 100, cache_read_tokens: 100, cache_creation_tokens: 0 },
+      { agent: "robin", model: "claude-haiku-4-5", estimated_usd: 5 },
+    ],
+  });
+  const d = await fleetDigest({ ledgerDir, day: DAY, org: true, rollupImpl });
+  assert.equal(d.source, "org-rollup");
+  assert.equal(d.totalUSD, 15); // NOT the local 999
+  assert.equal(d.byAgent.alex, 10);
+});
+
+test("fleetDigest: org leg unavailable → fall back to local with a note", async () => {
+  const { ledgerDir } = tmpLedger([{ agent: "alex", model: "m", estimated_usd: 7.0 }]);
+  const rollupImpl = async () => null; // server down / disabled
+  const d = await fleetDigest({ ledgerDir, day: DAY, org: true, rollupImpl });
+  assert.equal(d.source, "local");
+  assert.equal(d.totalUSD, 7.0);
+  assert.ok(d.notes.some((n) => /unavailable\/empty/.test(n)));
+});
+
+test("fleetDigest: a throwing rollupImpl is caught and falls back to local", async () => {
+  const { ledgerDir } = tmpLedger([{ agent: "alex", model: "m", estimated_usd: 2.0 }]);
+  const d = await fleetDigest({ ledgerDir, day: DAY, org: true, rollupImpl: async () => { throw new Error("boom"); } });
+  assert.equal(d.source, "local");
+  assert.equal(d.totalUSD, 2.0);
+});
+
+// ---------------------------------------------------------------------------
+// aggregateFromRollup — recompute KPI from tokens, ignore stale server ratio
+// ---------------------------------------------------------------------------
+
+test("aggregateFromRollup: recomputes cacheReadRatio from tokens (stale server ratio ignored)", () => {
+  const agg = aggregateFromRollup({
+    totalUSD: 10,
+    byAgent: { a: 10 },
+    cacheReadRatio: 0.99, // server claims 99% ...
+    tokens: { input: 500, cache_read: 500, cache_creation: 0 }, // ... but tokens say 50%
+  });
+  assert.equal(agg.cacheReadRatio, 0.5);
+});
+
+test("aggregateFromRollup: trusts server ratio only when tokens absent", () => {
+  const agg = aggregateFromRollup({ totalUSD: 10, byAgent: { a: 10 }, cache_read_ratio: 0.65 });
+  assert.equal(agg.cacheReadRatio, 0.65);
+});
+
+test("aggregateFromRollup: empty/garbage payload → zeroed, never throws", () => {
+  assert.equal(aggregateFromRollup(null).totalUSD, 0);
+  assert.equal(aggregateFromRollup("nope").sessions, 0);
+});