Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

37.0 KB
Raw Blame
/**
 * Federated AI-usage metrics.
 *
 * PortOS installs are commonly several machines federated as sync peers, and
 * "how much AI did I burn?" is a question about the FLEET, not about whichever
 * box the user happens to have open. This service is the `usage` sync
 * category's store: each instance publishes a digest of its own
 * `data/usage.json` (aggregate counters only — see `buildUsageDigest`) and
 * keeps every peer's digest side by side under `data/peer-usage.json`.
 *
 * Two invariants make that safe to run continuously:
 *
 *  - **Never merged into local usage.** A peer's counters live in their own
 *    per-instance slot. Summing them into `usage.json` would double-count on
 *    the very next round trip (our snapshot would ship the inflated total back)
 *    and would corrupt this machine's own history irreversibly.
 *  - **Idempotent, per-instance LWW.** A digest is replaced whole, keyed by its
 *    origin instanceId and stamped with `capturedAt`. Re-applying the same
 *    snapshot is a no-op, and a node forwards what it knows about third
 *    instances, so a chain (A↔B↔C) converges without A and C ever talking.
 *
 * Privacy: the digest carries provider ids, model ids, token/session/message
 * counts, day+month buckets and an instance name. No prompts, no transcripts,
 * no record contents, no PII — see
 * `docs/decisions/2026-09-01-federated-usage-metrics.md`.
 */

import { join } from 'path';
import { atomicWrite, readJSONFile, dataPath, PATHS } from '../lib/fileUtils.js';
import { isPlainObject, POLLUTING_KEYS } from '../lib/objects.js';
import { createMutex } from '../lib/asyncMutex.js';
import { compareNewerWins, parseTsMs } from '../lib/lwwTimestamp.js';
import { mergeTombstones, normalizeTombstones, recordTombstone, isTombstoned } from '../lib/tombstones.js';
import { canonicalSnapshotChecksum } from '../lib/snapshotChecksum.js';
import { roundCents } from '../lib/subscriptionSavings.js';
import { isFreeProvider } from '../lib/modelPricing.js';
import { familyForProviderId, familyLabel } from '../lib/providerFamilies.js';
import { sanitizeQuotaCards } from '../lib/fleetQuotas.js';
import { buildUsageDigest, buildUsageReport, getUsage, USAGE_FILE } from './usage.js';
import { readLocalQuotaCards, PROVIDER_QUOTAS_FILE } from './providerQuotaShare.js';
import { isNonBlankStr } from '../lib/textUtils.js';
import { readLocalTranscriptUsage, sanitizeTranscriptDays, TRANSCRIPT_USAGE_FILE } from './claudeCodeTranscriptUsage.js';
import { summarizeTranscriptDays, mergeModelRows } from './claudeCodeModelReport.js';

const PEER_USAGE_FILE = join(PATHS.data, 'peer-usage.json');

// Upper bound on stored peer digests. A home federation runs a handful of
// machines; the cap only stops an unbounded file if a peer ever forwards a long
// tail of instance ids that no longer exist. Oldest `capturedAt` is evicted.
const MAX_INSTANCES = 64;

// Structural bounds on ONE peer-supplied digest. The wire shape is fixed and
// shallow (day → provider → model), so it is normalized field-by-field rather
// than stored as it arrived: `canonicalStringify` (used for this category's
// checksum) is a recursive JS function with a far smaller depth budget than
// native JSON.stringify, so a digest nested deeply enough to pass `atomicWrite`
// but blow that recursion would 500 the snapshot endpoint for every peer,
// permanently and across restarts. The caps also stop one peer from growing
// `peer-usage.json` without bound inside its single slot.
const MAX_DAY_BUCKETS = 800;
const MAX_MONTH_BUCKETS = 400;
const MAX_PROVIDERS_PER_BUCKET = 100;
const MAX_MODELS_PER_PROVIDER = 400;

const DAY_KEY_RE = /^\d{4}-\d{2}-\d{2}$/;
const MONTH_KEY_RE = /^\d{4}-\d{2}$/;

const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : 0);
const str = (v, max) => (isNonBlankStr(v) ? v.slice(0, max) : null);

// The media units and long-context subsets are priced at read time (usage.js
// countFields), so a peer's digest has to carry them or its Grok/Antigravity
// images, video seconds and 200k-context premium vanish from the fleet report.
const COUNT_FIELDS = [
  'sessions', 'messages', 'tokens', 'tokensIn', 'tokensOut', 'cacheReadTokens', 'cacheWriteTokens',
  'longTokensIn', 'longTokensOut', 'longCacheReadTokens', 'longCacheWriteTokens',
  'images', 'videoSeconds', 'inputImages'
];

function takeCounts(source, target) {
  for (const field of COUNT_FIELDS) {
    if (typeof source?.[field] === 'number') target[field] = num(source[field]);
  }
  return target;
}

function sanitizeModelBucket(raw) {
  const out = takeCounts(raw, {});
  const source = str(raw?.source, 20);
  if (source) out.source = source;
  return out;
}

function sanitizeProviderBucket(raw) {
  const out = takeCounts(raw, {});
  const name = str(raw?.name, 120);
  if (name) out.name = name;
  const source = str(raw?.source, 20);
  if (source) out.source = source;
  if (isPlainObject(raw?.byModel)) {
    out.byModel = {};
    for (const [model, mRaw] of Object.entries(raw.byModel).slice(0, MAX_MODELS_PER_PROVIDER)) {
      if (!isNonBlankStr(model)) continue;
      out.byModel[model.slice(0, 200)] = sanitizeModelBucket(mRaw);
    }
  }
  return out;
}

function sanitizeActivityBucket(raw) {
  const out = takeCounts(raw, {});
  if (isPlainObject(raw?.byProvider)) {
    out.byProvider = {};
    for (const [pid, pRaw] of Object.entries(raw.byProvider).slice(0, MAX_PROVIDERS_PER_BUCKET)) {
      if (!isNonBlankStr(pid)) continue;
      out.byProvider[pid.slice(0, 200)] = sanitizeProviderBucket(pRaw);
    }
  }
  return out;
}

function sanitizeActivityMap(raw, keyRe, limit) {
  const out = {};
  if (!isPlainObject(raw)) return out;
  for (const [key, bucket] of Object.entries(raw).slice(0, limit)) {
    if (!keyRe.test(key)) continue;
    out[key] = sanitizeActivityBucket(bucket);
  }
  return out;
}

/**
 * Rebuild a peer's digest to the known wire shape, dropping anything else. Depth
 * is therefore fixed by construction — see the bounds above for why that
 * matters more than it looks.
 */
function sanitizeDigest(raw) {
  const hourly = Array.isArray(raw?.hourlyActivity) ? raw.hourlyActivity : [];
  return {
    totalSessions: num(raw?.totalSessions),
    totalMessages: num(raw?.totalMessages),
    totalToolCalls: num(raw?.totalToolCalls),
    totalTokens: { input: num(raw?.totalTokens?.input), output: num(raw?.totalTokens?.output) },
    dailyActivity: sanitizeActivityMap(raw?.dailyActivity, DAY_KEY_RE, MAX_DAY_BUCKETS),
    monthlyActivity: sanitizeActivityMap(raw?.monthlyActivity, MONTH_KEY_RE, MAX_MONTH_BUCKETS),
    hourlyActivity: Array.from({ length: 24 }, (_, i) => num(hourly[i])),
    earliestActivityDay: str(raw?.earliestActivityDay, 10),
    lastUpdated: str(raw?.lastUpdated, 40),
  };
}

const withLock = createMutex();

/**
 * This machine's federation identity, read from the identity leaf
 * (services/instanceIdentity.js, #6836) rather than services/instances.js —
 * that module still drags the peer socket relay / federated-media consumer /
 * tailscale into dataSync's module-load path, the same reason dataSync defers
 * `sharing/peerSync.js`. Kept as a dynamic import to match that call shape,
 * though the leaf itself would no longer need the deferral.
 */
async function readSelfIdentity() {
  const { getSelf, UNKNOWN_INSTANCE_ID } = await import('./instanceIdentity.js');
  const self = await getSelf().catch(() => null);
  const instanceId = isNonBlankStr(self?.instanceId) && self.instanceId !== UNKNOWN_INSTANCE_ID
    ? self.instanceId
    : null;
  return { instanceId, name: isNonBlankStr(self?.name) ? self.name : null };
}

async function readStore() {
  // Retirements are durable tombstones: peers cannot rebuild a deletion that
  // has not propagated yet. Never replace an unreadable store with a new digest.
  const raw = await readJSONFile(PEER_USAGE_FILE, null, { strict: true });
  return {
    instances: isPlainObject(raw?.instances) ? raw.instances : {},
    tombstones: normalizeTombstones(raw?.tombstones, 'instanceId'),
  };
}

/**
 * A peer's Claude Code per-day, per-model token history, or null when it sent
 * none (or an unorderable one). Rebuilt to the fixed day → model → counts shape.
 */
function sanitizeClaudeCode(raw) {
  if (!isPlainObject(raw) || parseTsMs(raw.updatedAt) === null) return null;
  const days = sanitizeTranscriptDays(raw.days);
  return Object.keys(days).length > 0 ? { updatedAt: raw.updatedAt, days } : null;
}

/**
 * Coerce one wire entry into a stored entry, or null when it can't be trusted.
 * Pins identity (the entry must belong to the map key it arrived under),
 * orderability (a parseable stamp), and shape (`sanitizeDigest`).
 */
function sanitizeEntry(entry, expectedId) {
  if (!isPlainObject(entry) || !isPlainObject(entry.usage)) return null;
  // A digest may omit its own id (the key is authoritative), but it may never
  // claim a DIFFERENT one — that would let a peer smuggle a digest in under our
  // id, or overwrite a third instance's slot.
  if (isNonBlankStr(entry.instanceId) && entry.instanceId !== expectedId) return null;
  if (parseTsMs(entry.capturedAt) === null) return null;
  return {
    instanceId: expectedId,
    name: isNonBlankStr(entry.name) ? entry.name.slice(0, 120) : expectedId,
    capturedAt: entry.capturedAt,
    usage: sanitizeDigest(entry.usage),
    // Optional: a peer running an older build publishes no quota readings, and
    // the fleet quota view simply has one fewer contributor.
    quotas: sanitizeQuotaCards(entry.quotas),
    // Optional and additive, like `quotas`: a peer on an older build publishes
    // no Claude Code token history and simply contributes nothing to that report.
    claudeCode: sanitizeClaudeCode(entry.claudeCode),
  };
}

// The self digest is a pure function of (usage counters, today's date) — the
// date because the wire rollup's cutoff moves at midnight. `saveUsage` stamps
// `lastUpdated` on every write, so it doubles as the cache key. Without this
// memo the deep clone + rollup re-ran on every checksum-cache miss AND once per
// probing peer, all producing the identical byte-for-byte digest.
let digestMemo = null;
function selfDigest(usageData) {
  const key = `${usageData?.lastUpdated ?? ''}|${new Date().toISOString().slice(0, 10)}`;
  if (digestMemo?.key !== key) digestMemo = { key, digest: buildUsageDigest(usageData) };
  return digestMemo.digest;
}

/**
 * This instance's own live entry, rebuilt from `usage.json` (and the last quota
 * readings) on every read.
 *
 * `capturedAt` is the LWW stamp AND the manifest fingerprint, so it has to move
 * whenever anything in the entry does — a quota refresh that left it pinned to
 * `usage.lastUpdated` would never be pulled by a peer.
 */
async function buildSelfEntry() {
  const { instanceId, name } = await readSelfIdentity();
  if (!instanceId) return null;
  const usage = selfDigest(getUsage());
  const { quotas, capturedAt: quotasAt } = await readLocalQuotaCards();
  // An unreadable store publishes no history rather than failing every sync read.
  const local = await readLocalTranscriptUsage().catch(() => null);
  const claudeCode = local?.updatedAt && Object.keys(local.days).length > 0 ? local : null;
  // capturedAt is the LWW stamp AND manifest fingerprint: the newest of every
  // component, so a transcript-store refresh alone still gets pulled by peers.
  const capturedAt = [usage.lastUpdated, quotasAt, claudeCode?.updatedAt].reduce(
    (newest, ts) => (compareNewerWins(ts, newest) ? ts : newest));
  return { instanceId, name: name || instanceId, capturedAt, usage, quotas, ...(claudeCode && { claudeCode }) };
}

/**
 * Every instance we can report on: the peer digests we hold, plus our own live
 * entry. Our own slot is always regenerated — a stale copy of us that came back
 * from a peer never wins. A digest with no activity yet has a null
 * `lastUpdated` and is dropped from the wire rather than shipped unorderable.
 */
async function entriesWithSelf() {
  const [store, self] = await Promise.all([readStore(), buildSelfEntry()]);
  const peers = Object.values(store.instances).filter((e) => isPlainObject(e) && isPlainObject(e.usage));
  const publishable = self && isNonBlankStr(self.capturedAt) ? self : null;
  return {
    self: publishable,
    peers: peers.filter((e) => e.instanceId !== self?.instanceId),
    tombstones: store.tombstones,
  };
}

/**
 * The category's version map: `{ <instanceId>: capturedAt }` plus the tombstone
 * list. A few hundred bytes, and the ONLY thing this category's checksum is
 * computed over (see `usageChecksum`).
 */
function manifestOf(self, peers, tombstones) {
  const instances = Object.fromEntries(peers.map((e) => [e.instanceId, e.capturedAt]));
  if (self) instances[self.instanceId] = self.capturedAt;
  return { instances, tombstones };
}

/**
 * CANONICAL: the payload is a map keyed by instance ids arriving over the wire,
 * so two converged peers would otherwise hash differently purely from the order
 * they happened to learn each other — which the sync UI reads as "behind"
 * forever.
 *
 * Hashed over the MANIFEST rather than the digests themselves. The digests are
 * a pure function of the (instanceId, capturedAt) pairs — a slot is replaced
 * whole under that stamp and never edited in place — so the manifest is a
 * faithful fingerprint of the payload, and it is what `getUsageSnapshot`
 * reports too. A peer that only knows `/checksum` + `/snapshot` therefore still
 * sees the checksum change exactly when a slot advances.
 */
const usageChecksum = (manifest) => canonicalSnapshotChecksum(manifest);

/**
 * dataSync `getManifest` for the `usage` category. Served at
 * `/api/sync/usage/manifest` so a puller can fetch only the slots that moved,
 * and read locally (same function, no arguments) as "what do we already hold?"
 * for that diff.
 */
export async function getUsageManifest() {
  const { self, peers, tombstones } = await entriesWithSelf();
  const data = manifestOf(self, peers, tombstones);
  return { data, checksum: usageChecksum(data) };
}

/**
 * dataSync `getSnapshot` for the `usage` category: our own live digest plus
 * every peer digest we hold, so a third instance reachable only through us
 * still propagates.
 *
 * `slots` (a `Set`/array of instance ids, from `?slots=` on the wire) narrows
 * the payload to the digests a manifest-aware puller actually needs. Absent —
 * an older peer, or any caller that skipped the manifest — serves everything,
 * which the receiver merges idempotently. The checksum is the FULL manifest's
 * either way: it describes the category's state, not the slice we happened to
 * serve, so the two endpoints can never disagree.
 */
export async function getUsageSnapshot({ slots = null } = {}) {
  const { self, peers, tombstones } = await entriesWithSelf();
  const wanted = slots instanceof Set ? slots : (Array.isArray(slots) && slots.length > 0 ? new Set(slots) : null);
  const keep = (id) => !wanted || wanted.has(id);
  const instances = Object.fromEntries(peers.filter((e) => keep(e.instanceId)).map((e) => [e.instanceId, e]));
  if (self && keep(self.instanceId)) instances[self.instanceId] = self;
  // Tombstones ride EVERY response (slot-scoped included) so a retirement
  // propagates: an add-only merge alone would let any peer that still holds the
  // digest hand it straight back, and a retirement moves no slot's capturedAt.
  return { data: { instances, tombstones }, checksum: usageChecksum(manifestOf(self, peers, tombstones)) };
}

/**
 * dataSync `applyRemote` for the `usage` category. Per-instance LWW on
 * `capturedAt`; our own slot is skipped outright (we are the authority on our
 * own counters), and nothing is ever summed into `data/usage.json`.
 */
export async function applyUsageRemote(remoteData) {
  const incoming = isPlainObject(remoteData?.instances) ? remoteData.instances : null;
  if (!incoming) return { applied: false, count: 0 };

  const { instanceId: selfId } = await readSelfIdentity();

  return withLock(async () => {
    const store = await readStore();
    // Union the deletion list in BOTH directions, so retiring an instance on one
    // machine retires it everywhere instead of being undone by the next peer that
    // still forwards it.
    const { merged, changed: tombstonesChanged } = mergeTombstones(store.tombstones, remoteData?.tombstones, { keyField: 'instanceId' });
    store.tombstones = merged;
    let changed = 0;

    for (const [key, rawEntry] of Object.entries(incoming)) {
      // A peer-chosen key of `__proto__` would replace this map's prototype on assignment.
      if (!isNonBlankStr(key) || key === selfId || POLLUTING_KEYS.has(key)) continue;
      const entry = sanitizeEntry(rawEntry, key);
      if (!entry) continue;
      // A digest CAPTURED after the deletion is a machine that came back, and
      // supersedes the tombstone. An older one is the retired machine echoing
      // back via a peer that hasn't seen the removal yet.
      if (isTombstoned(store.tombstones, key, entry.capturedAt, 'instanceId')) continue;
      if (!compareNewerWins(entry.capturedAt, store.instances[key]?.capturedAt)) continue;
      store.instances[key] = entry;
      changed++;
    }

    // Adopting a peer's tombstone also retires the local digest it covers.
    for (const key of Object.keys(store.instances)) {
      if (!isTombstoned(store.tombstones, key, store.instances[key]?.capturedAt, 'instanceId')) continue;
      delete store.instances[key];
      changed++;
    }

    if (changed === 0) {
      // A tombstone learned from a peer is still state worth persisting, even
      // when it retired nothing here — otherwise we re-learn it every cycle.
      if (tombstonesChanged) await atomicWrite(PEER_USAGE_FILE, store);
      return { applied: false, count: 0 };
    }

    const ids = Object.keys(store.instances);
    if (ids.length > MAX_INSTANCES) {
      const oldestFirst = ids.sort((a, b) => (parseTsMs(store.instances[a].capturedAt) ?? 0) - (parseTsMs(store.instances[b].capturedAt) ?? 0));
      for (const id of oldestFirst.slice(0, ids.length - MAX_INSTANCES)) delete store.instances[id];
    }

    await atomicWrite(PEER_USAGE_FILE, store);
    console.log(`🔄 Usage sync: updated ${changed} instance digest${changed === 1 ? '' : 's'}`);
    return { applied: true, count: changed };
  });
}

/**
 * Fleet-wide usage for a report window: one row per known instance plus the
 * combined totals.
 *
 * Every row goes through the SAME pure `buildUsageReport` the single-instance
 * page uses, so per-instance and fleet figures are priced identically — and
 * THIS machine's row reads the live activity maps, not its own wire digest. The
 * digest folds days past the wire-retention window into whole months, and
 * `buildUsageReport` includes a month bucket whole whenever its month overlaps
 * the window; routing our own row through it would make the "This machine" row
 * disagree with the headline directly above it on a narrow historical range.
 *
 * Peer rows are as fresh as the last sync, so `capturedAt` is surfaced for the
 * UI to age them rather than implying they are live.
 *
 * `apiBilledInstanceIds` are instances the viewer marked as paying API rates
 * rather than subscriptions. They stay in `instances` (the spend is real) with
 * `usesSubscriptions: false`, but they do not feed the combined `totals`.
 */
/**
 * Keep only month buckets the window covers END TO END. `buildUsageReport`
 * includes an overlapping month whole, so a month the range only clips would
 * contribute days outside it. Unbounded on a side means that side covers
 * everything, so a bucket is dropped only where the given bound cuts into it.
 */
function dropPartiallyCoveredMonths(monthlyActivity, from, to) {
  if (!isPlainObject(monthlyActivity)) return {};
  if (!from && !to) return monthlyActivity;
  const out = {};
  for (const [month, bucket] of Object.entries(monthlyActivity)) {
    // A month is fully covered when the window starts on or before its 1st and
    // ends on or after its last day.
    if (from && from > month + '-01') continue;
    if (to) {
      const [y, m] = month.split('-').map(Number);
      const lastDay = new Date(Date.UTC(y, m, 0)).toISOString().slice(0, 10);
      if (to < lastDay) continue;
    }
    out[month] = bucket;
  }
  return out;
}

function sumFleetTotals(rows) {
  // Derived from the report's own totals rather than a second hardcoded field
  // list, so a field added to `buildUsageReport` can't silently sum to zero here.
  const totals = rows.reduce((acc, r) => {
    for (const [field, value] of Object.entries(r.totals || {})) {
      if (typeof value === 'number') acc[field] = (acc[field] || 0) + value;
    }
    return acc;
  }, {});
  totals.estimatedCost = roundCents(totals.estimatedCost || 0);
  return totals;
}

export async function getFleetUsage({ from = null, to = null, providers = [], apiBilledInstanceIds = [] } = {}) {
  const { self, peers } = await entriesWithSelf();
  if (peers.length === 0) return { instances: [], totals: null };

  // Instances the viewer marked as paying API rates (not subscriptions). They
  // stay in `instances` so the spend is still visible, but they do not feed
  // the combined total. Default ON (not in the set) — a missing id counts.
  const apiBilled = new Set(Array.isArray(apiBilledInstanceIds) ? apiBilledInstanceIds : []);

  const row = ({ instanceId, name, capturedAt, activity, isSelf }) => {
    const report = buildUsageReport(activity.dailyActivity || {}, {
      from,
      to,
      providers,
      // A month bucket is folded in WHOLE whenever its month overlaps the window
      // — fine locally, where months only exist past the 400-day daily retention
      // and so can't land inside a range anyone asks for. A peer's digest rolls
      // up at 120 days, well inside a reachable range, so an explicit narrow
      // from/to over a rolled-up month would silently count days outside it.
      // Drop the partially-covered months rather than over-report; the row's
      // whole-month periods are unaffected.
      monthlyActivity: dropPartiallyCoveredMonths(activity.monthlyActivity, from, to),
      // Same rule as the single-instance summary: the all-time (unbounded)
      // window folds in legacy totals no bucket represents; a bounded window
      // must not, or it attributes all-time residue to the range.
      totalTokens: from || to ? null : activity.totalTokens,
    });
    return {
      instanceId,
      name: name || instanceId,
      self: isSelf,
      capturedAt,
      totals: report.totals,
      usesSubscriptions: !apiBilled.has(instanceId),
    };
  };

  const rows = peers.map((e) => row({ ...e, activity: e.usage, isSelf: false }));
  if (self) rows.unshift(row({ ...self, activity: getUsage(), isSelf: true }));

  rows.sort((a, b) => (b.self ? 1 : 0) - (a.self ? 1 : 0) || b.totals.estimatedCost - a.totals.estimatedCost);

  const included = rows.filter((r) => r.usesSubscriptions);
  return { instances: rows, totals: sumFleetTotals(included) };
}

export const ROLLING_COST_WINDOW_DAYS = 30;
// Points shown per range. `all` starts at the earliest day any instance has.
export const ROLLING_COST_RANGES = { '1m': 30, '3m': 90, '6m': 182, '1y': 365, all: null };

const DAY_MS = 86_400_000;
const utcDay = (ms) => new Date(ms).toISOString().slice(0, 10);
const dayMs = (day) => Date.parse(`${day}T00:00:00Z`);

// Stacked groups beyond this many fold into "Other" so the legend stays short.
const MAX_COST_GROUPS = 5;
const OTHER_GROUP = 'other';

/**
 * A report's cost split by plan: a provider row belongs to its subscription
 * family when it has one (a peer's provider may not be configured here, so the
 * id is tried too), else it stands alone under its own name.
 */
function costByGroup(report, labels) {
  const out = {};
  for (const row of report.providers) {
    if (!(row.estimatedCost > 0)) continue;
    const family = row.family || familyForProviderId(row.id);
    const key = family || `provider:${row.id}`;
    if (!labels.has(key)) labels.set(key, family ? familyLabel(family) : row.name || row.id);
    out[key] = (out[key] || 0) + row.estimatedCost;
  }
  return out;
}

const addInto = (target, source, scale = 1) => {
  for (const [key, cost] of Object.entries(source)) target[key] = (target[key] || 0) + cost * scale;
};

const reportTokens = (row) => row.tokensIn + row.tokensOut + row.cacheReadTokens + row.cacheWriteTokens;

function dailyUsage(report, labels) {
  return {
    costs: costByGroup(report, labels),
    tokens: reportTokens(report.totals),
    claudeTokens: report.providers.reduce((sum, row) => sum + ((row.family || familyForProviderId(row.id)) === 'claude' ? reportTokens(row) : 0), 0),
  };
}

/**
 * Estimated API cost per day for one instance over `span`, split by plan, each
 * day priced on its own through the same `buildUsageReport` as the cost report
 * so the series and the headline agree.
 *
 * Old days survive only as month buckets (a peer's digest rolls up after 120
 * days, this machine's history after 400), so a month bucket's cost is spread
 * evenly over that month's days that no longer have a day bucket. The month's
 * total is exact; its shape within the month is not.
 *
 * Claude Code use outside PortOS also comes from the instance's transcript
 * history (see `withTranscriptClaude`).
 */
function instanceDailyUsage({ daily = {}, monthly = {}, transcript = {} }, span, providers, labels) {
  const missingDays = new Map();
  for (const day of span) {
    const month = day.slice(0, 7);
    if (!daily[day] && monthly[month]) missingDays.set(month, (missingDays.get(month) || 0) + 1);
  }
  const monthShare = new Map();
  for (const [month, count] of missingDays) {
    const report = buildUsageReport({}, { monthlyActivity: { [month]: monthly[month] }, providers });
    // Days of the month outside the span still carry their share, so divide by
    // every rolled-up day of the month, not only the `count` in view.
    const [y, m] = month.split('-').map(Number);
    const daysInMonth = new Date(Date.UTC(y, m, 0)).getUTCDate();
    const rolledDays = daysInMonth - Object.keys(daily).filter((d) => d.startsWith(`${month}-`)).length;
    const divisor = Math.max(rolledDays, count);
    const usage = dailyUsage(report, labels);
    const costs = {};
    addInto(costs, usage.costs, 1 / divisor);
    monthShare.set(month, { costs, tokens: usage.tokens / divisor, claudeTokens: usage.claudeTokens / divisor });
  }
  return span.map((day) => {
    const usage = daily[day]
      ? dailyUsage(buildUsageReport({ [day]: daily[day] }, { from: day, to: day, providers }), labels)
      : monthShare.get(day.slice(0, 7)) || { costs: {}, tokens: 0, claudeTokens: 0 };
    const transcriptTotals = transcript[day] && summarizeTranscriptDays({ [day]: transcript[day] }).totals;
    return {
      costs: withTranscriptClaude({ ...usage.costs }, transcriptTotals?.estimatedCost, labels),
      // Transcript sessions overlap the Claude ledger; reconcile tokens by the
      // same per-day maximum as cost, retaining every other provider's tokens.
      tokens: usage.tokens + Math.max(0, (transcriptTotals?.total || 0) - usage.claudeTokens),
    };
  });
}

/**
 * The Claude Code CLI's own transcripts count every session on the machine —
 * the terminal, the desktop app's Code tab, AND the runs PortOS spawned. The
 * ledger holds PortOS runs plus the terminal sessions the interactive scan
 * billed (usageInteractiveScan.js, which reaches back only ~35 days from its
 * first run), so each is a partial view of the same spend: the day's Claude
 * cost is the larger of the two, never their sum.
 */
function withTranscriptClaude(costs, transcriptCost, labels) {
  if ((transcriptCost || 0) > (costs.claude || 0)) {
    if (!labels.has('claude')) labels.set('claude', familyLabel('claude'));
    costs.claude = transcriptCost;
  }
  return costs;
}

function earliestDay(sources) {
  let earliest = null;
  for (const { daily, monthly, transcript } of sources) {
    for (const day of [...Object.keys(daily || {}), ...Object.keys(transcript || {})]) if (!earliest || day < earliest) earliest = day;
    for (const month of Object.keys(monthly || {})) if (!earliest || `${month}-01` < earliest) earliest = `${month}-01`;
  }
  return earliest;
}

async function usageHistorySources() {
  const { self, peers } = await entriesWithSelf();
  const local = getUsage();
  // An unreadable transcript store charts PortOS runs only rather than failing.
  const localTranscript = await readLocalTranscriptUsage().catch(() => null);
  // This machine always reads its live maps; with no minted identity yet it
  // still has its own history to chart.
  return [
    {
      id: self?.instanceId ?? 'local',
      stamp: [local?.lastUpdated, localTranscript?.updatedAt],
      daily: local?.dailyActivity,
      monthly: local?.monthlyActivity,
      transcript: localTranscript?.days,
    },
    ...peers.map((e) => ({
      id: e.instanceId,
      stamp: e.capturedAt,
      daily: e.usage.dailyActivity,
      monthly: e.usage.monthlyActivity,
      transcript: e.claudeCode?.days,
    })),
  ];
}

function stackCosts(rows, labels) {
  const totals = {};
  for (const costs of rows) addInto(totals, costs);
  const ranked = Object.keys(totals).sort((x, y) => totals[y] - totals[x]);
  const kept = ranked.length > MAX_COST_GROUPS ? ranked.slice(0, MAX_COST_GROUPS - 1) : ranked;
  const groupOf = new Map(ranked.map((key) => [key, kept.includes(key) ? key : OTHER_GROUP]));
  const series = kept.map((key) => ({ key, label: labels.get(key) }));
  if (kept.length < ranked.length) series.push({ key: OTHER_GROUP, label: 'Other' });
  const slot = new Map(series.map((g, i) => [g.key, i]));
  const values = rows.map((costs) => {
    const row = new Array(series.length).fill(0);
    for (const [key, cost] of Object.entries(costs)) row[slot.get(groupOf.get(key))] += cost;
    return row;
  });
  return { series, values };
}

/** Calendar months over the same fleet, ledger and transcript sources as rolling cost. */
export async function getFleetMonthlyUsage({ providers = [], now = new Date() } = {}) {
  const sources = await usageHistorySources();
  const first = earliestDay(sources);
  if (!first) return { instanceCount: sources.length, series: [], history: [] };
  const start = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth() - 11, 1)).getTime();
  const today = utcDay(now.getTime());
  const span = Array.from({ length: Math.floor((dayMs(today) - start) / DAY_MS) + 1 }, (_, i) => utcDay(start + i * DAY_MS));
  const months = new Map();
  for (const day of span) {
    if (day < first) continue;
    const month = day.slice(0, 7);
    if (!months.has(month)) months.set(month, { month, costs: {}, tokens: 0 });
  }
  const labels = new Map();
  for (const source of sources) {
    instanceDailyUsage(source, span, providers, labels).forEach((usage, i) => {
      const month = months.get(span[i].slice(0, 7));
      if (!month) return;
      addInto(month.costs, usage.costs);
      month.tokens += usage.tokens;
    });
  }
  const rows = [...months.values()];
  const { series, values } = stackCosts(rows.map((row) => row.costs), labels);
  const history = rows.map((row, i) => {
    const costs = values[i].map(roundCents);
    return {
      month: row.month,
      estimatedCost: roundCents(costs.reduce((sum, cost) => sum + cost, 0)),
      values: costs,
      tokens: Math.round(row.tokens),
      partial: row.month === today.slice(0, 7) || first > `${row.month}-01`,
    };
  });
  return { instanceCount: sources.length, series, history };
}

let rollingMemo = null;

/**
 * Rolling 30-day estimated API cost summed across EVERY known instance, one
 * point per UTC day over `range` (see ROLLING_COST_RANGES). API-billed
 * instances count here: this is total spend at API rates, not the
 * subscription-covered subset the Across Instances total reports. Peers are as
 * fresh as their last sync.
 */
export async function getFleetRollingCost({ providers = [], range = '3m', now = new Date() } = {}) {
  const sources = await usageHistorySources();

  const todayMs = dayMs(utcDay(now.getTime()));
  const rangeId = Object.hasOwn(ROLLING_COST_RANGES, range) ? range : '3m';
  const fixed = ROLLING_COST_RANGES[rangeId];
  const first = earliestDay(sources);
  const allPoints = first ? Math.floor((todayMs - dayMs(first)) / DAY_MS) + 1 : 2;
  const pointCount = Math.max(2, fixed ?? allPoints);
  const spanLength = pointCount + ROLLING_COST_WINDOW_DAYS - 1;
  const span = Array.from({ length: spanLength }, (_, i) => utcDay(todayMs - (spanLength - 1 - i) * DAY_MS));

  const key = JSON.stringify([rangeId, span[0], span.at(-1), sources.map((s) => [s.id, s.stamp]), providers.map((p) => [p.id, isFreeProvider(p)])]);
  if (rollingMemo?.key === key) return rollingMemo.value;

  const labels = new Map();
  const perDay = span.map(() => ({}));
  for (const source of sources) {
    instanceDailyUsage(source, span, providers, labels).forEach(({ costs }, i) => addInto(perDay[i], costs));
  }

  // Per-day cost in series order, then a trailing-window sum per slot.
  const { series, values: daily } = stackCosts(perDay, labels);
  const running = new Array(series.length).fill(0);
  const points = [];
  for (let i = 0; i < span.length; i++) {
    daily[i].forEach((cost, j) => { running[j] += cost; });
    if (i >= ROLLING_COST_WINDOW_DAYS) daily[i - ROLLING_COST_WINDOW_DAYS].forEach((cost, j) => { running[j] -= cost; });
    if (i < ROLLING_COST_WINDOW_DAYS - 1) continue;
    // Clamp: the add/subtract walk can leave float dust just below zero.
    const values = running.map((v) => Math.max(0, roundCents(v)));
    points.push({ date: span[i], cost: roundCents(values.reduce((sum, v) => sum + v, 0)), values });
  }
  const value = { range: rangeId, windowDays: ROLLING_COST_WINDOW_DAYS, instanceCount: sources.length, series, points };
  rollingMemo = { key, value };
  return value;
}

/**
 * Fleet-wide Claude Code tokens per model, priced at API rates, for a window.
 * One row per instance that has published transcript history (this machine
 * reads its live store), plus a combined per-model list. As with `getFleetUsage`,
 * an instance the viewer marked as API-billed stays listed but does not feed the
 * combined figures. Peer rows are as fresh as the last sync (`capturedAt`).
 */
export async function getFleetClaudeCodeModels({ from = null, to = null, apiBilledInstanceIds = [] } = {}) {
  const { self, peers } = await entriesWithSelf();
  const apiBilled = new Set(Array.isArray(apiBilledInstanceIds) ? apiBilledInstanceIds : []);
  const row = (e, isSelf) => {
    const { models, totals } = summarizeTranscriptDays(e.claudeCode.days, { from, to });
    return { instanceId: e.instanceId, name: e.name || e.instanceId, self: isSelf, capturedAt: e.claudeCode.updatedAt, models, totals, usesSubscriptions: !apiBilled.has(e.instanceId) };
  };
  const instances = [
    ...(self?.claudeCode ? [row(self, true)] : []),
    ...peers.filter((e) => e.claudeCode).map((e) => row(e, false)),
  ];
  const combined = mergeModelRows(instances.filter((i) => i.usesSubscriptions).map((i) => i.models));
  // Peers we know of that published no history (older build, or not scanned yet)
  // — named so the UI can say why they are missing rather than dropping them.
  const pending = peers.filter((e) => !e.claudeCode).map((e) => e.name || e.instanceId);
  return { instances, pendingInstances: pending, ...combined };
}

/**
 * Every OTHER instance's last-known subscription-quota readings, for unifying
 * them with this machine's cards (`lib/fleetQuotas.js`).
 *
 * `excludeInstanceIds` drops instances the viewer marked as paying API rates
 * rather than riding their subscriptions — the same toggle the Across
 * Instances card uses. Those machines meter a different account, so folding
 * their readings into these meters would be a wrong number, not a fuller one.
 */
export async function getFleetQuotaEntries({ excludeInstanceIds = [] } = {}) {
  const { peers } = await entriesWithSelf();
  const excluded = new Set(Array.isArray(excludeInstanceIds) ? excludeInstanceIds : []);
  return peers
    .filter((e) => !excluded.has(e.instanceId) && e.quotas?.length)
    .map(({ instanceId, name, capturedAt, quotas }) => ({ instanceId, name, capturedAt, quotas }));
}

/**
 * Retire an instance's usage digest — called when the user removes that peer.
 *
 * A plain delete is not enough: our snapshot forwards every digest we hold, so a
 * surviving peer would hand the row straight back on the next cycle and a
 * decommissioned machine's spend would sit in the fleet total forever. The
 * tombstone rides the same snapshot and propagates the removal instead. A digest
 * captured AFTER the tombstone still wins, so re-adding the machine later works.
 */
export async function forgetInstanceUsage(instanceId) {
  if (!isNonBlankStr(instanceId)) return { removed: false };
  return withLock(async () => {
    const store = await readStore();
    store.tombstones = recordTombstone(store.tombstones, instanceId, { keyField: 'instanceId' });
    const removed = Object.hasOwn(store.instances, instanceId);
    delete store.instances[instanceId];
    await atomicWrite(PEER_USAGE_FILE, store);
    console.log(`🔄 Usage sync: retired digest for instance ${instanceId}`);
    return { removed };
  });
}

// Files whose fingerprint invalidates the category's checksum cache. The
// instances file is in the set because the manifest is keyed by this instance's
// ID — a re-identified machine must re-checksum even when no counter moved.
export const USAGE_CHECKSUM_PATHS = [USAGE_FILE, PEER_USAGE_FILE, PROVIDER_QUOTAS_FILE, TRANSCRIPT_USAGE_FILE, dataPath('instances.json')];

export { PEER_USAGE_FILE };