Skip to content

an open-source alternative to the dots, bots and muses of the world, run an office of claude code/codex like agents on your laptop, sandboxes or anywhere, uses your existing subscriptions

fix(cost): report lifetime spend, not spend since the last app restart

Chaitanya Giri6c19ede14355
diff --git a/package.json b/package.json
index 97bb375a..57c57119 100644
--- a/package.json
+++ b/package.json
@@ -19,7 +19,7 @@
"typecheck:node": "tsc --noEmit -p tsconfig.node.json",
"typecheck:web": "tsc --noEmit -p tsconfig.web.json",
"typecheck": "npm run typecheck:node && npm run typecheck:web",
- "test:focused": "node --test test/codex-remote.test.cjs test/control.test.cjs test/provider-automation.test.cjs test/provider-config.test.cjs test/queue-delivery.test.cjs test/terminal-automation.test.cjs test/terminal-recovery.test.cjs test/terminal-selection.test.cjs test/roster.test.cjs test/proc-kill.test.cjs test/expand-tilde.test.cjs test/hive-cwd.test.cjs test/hive-task-mutation.test.cjs test/hive-hook-node.test.cjs test/hive-roster-injection.test.cjs test/hive-runtime-path.test.cjs test/cli-install-ladder.test.cjs test/node-install.test.cjs test/office-gl-recovery.test.cjs test/update-state.test.cjs test/release-notes.test.cjs test/transcript-project-dir.test.cjs test/commit-graph.test.cjs test/ide-image.test.cjs test/win-cmd-shim.test.cjs test/hive-windows-prompt.test.cjs test/release-drop.test.cjs test/skills.test.cjs test/skills-install.test.cjs test/hero-payload.test.cjs",
+ "test:focused": "node --test test/codex-remote.test.cjs test/control.test.cjs test/provider-automation.test.cjs test/provider-config.test.cjs test/queue-delivery.test.cjs test/terminal-automation.test.cjs test/terminal-recovery.test.cjs test/terminal-selection.test.cjs test/roster.test.cjs test/proc-kill.test.cjs test/expand-tilde.test.cjs test/hive-cwd.test.cjs test/hive-task-mutation.test.cjs test/hive-hook-node.test.cjs test/hive-roster-injection.test.cjs test/hive-runtime-path.test.cjs test/cli-install-ladder.test.cjs test/node-install.test.cjs test/office-gl-recovery.test.cjs test/update-state.test.cjs test/release-notes.test.cjs test/transcript-project-dir.test.cjs test/commit-graph.test.cjs test/ide-image.test.cjs test/win-cmd-shim.test.cjs test/hive-windows-prompt.test.cjs test/release-drop.test.cjs test/skills.test.cjs test/skills-install.test.cjs test/hero-payload.test.cjs test/cost-lifetime.test.cjs",
"check:links": "node tools/check-release-links.cjs",
"dist": "npm run build && electron-builder",
"dist:mac": "npm run build && electron-builder --mac",
diff --git a/src/main/costLifetime.ts b/src/main/costLifetime.ts
new file mode 100644
index 00000000..f8276649
--- /dev/null
+++ b/src/main/costLifetime.ts
@@ -0,0 +1,208 @@
+/**
+ * Lifetime cost, recovered from `cost-ledger.jsonl`.
+ *
+ * WHY THIS EXISTS
+ * ───────────────
+ * `AgentUsageSample.usd` is a CUMULATIVE-SINCE-PROCESS-START counter, not a
+ * lifetime one. `TelemetryCollector` accumulates into in-memory maps
+ * (`sessions` / `agentSessions`), so an app restart rebuilds them empty and the
+ * counter restarts at ~0 under the SAME `session_id` (the agent resumes; only
+ * our accumulator forgot). Every consumer that reads the LAST value therefore
+ * understates spend for any agent that has been through a restart.
+ *
+ * Measured on the live ledger 2026-08-21: 38 such resets, last-value total
+ * $987.04 against a true $2,406.64, i.e. 59% of spend invisible.
+ *
+ * THE RECOVERY
+ * ────────────
+ * The ledger keeps every line, so the pre-reset peaks are still on disk. Within
+ * one (agent, session) the counter only ever climbs, so a DECREASE is the reset
+ * signature and nothing else. Lifetime is then:
+ *
+ * sum(peak of each closed segment) + peak of the open segment
+ *
+ * Any decrease counts, with only a float-noise epsilon. A dollar threshold was
+ * considered and rejected: two genuine restarts in the live ledger drop from
+ * $0.92 and $0.73 straight to $0.00, and a $1 threshold silently misses both.
+ * A cumulative counter has no legitimate reason to go down, so the magic number
+ * bought nothing and cost coverage.
+ *
+ * COST / SHAPE
+ * ────────────
+ * The ledger is append-only and already 32MB (162k lines, 126 distinct
+ * agent+session keys). A full fold is ~800ms, which must NOT land on the
+ * Electron main thread, so folding is async and INCREMENTAL: each pass reads
+ * only the bytes appended since the last one and keeps the running segment
+ * state. Steady-state cost per pass is a few hundred bytes.
+ *
+ * Read-only: this module never writes to the ledger.
+ */
+
+import { createReadStream, statSync } from 'fs';
+
+/** Per (agent, session) fold state: closed segments plus the open one. */
+interface Segment {
+ /** Sum of the peaks of every segment already closed by a reset. */
+ committed: number;
+ /** High-water mark of the segment currently open. */
+ peak: number;
+}
+
+/** Float noise guard. Real resets drop by cents at minimum, so anything below
+ * this is arithmetic dust rather than a restart. */
+const EPS = 1e-9;
+
+/** Cap per pass so a cold start cannot stall behind one enormous read. The
+ * fold simply resumes on the next call. */
+const MAX_BYTES_PER_PASS = 8 * 1024 * 1024;
+
+export class CostLedgerTotals {
+ /** Bytes of the ledger already folded. */
+ private offset = 0;
+ /** Trailing partial line, kept as BYTES so a multi-byte character split
+ * across a read boundary is never decoded in half. */
+ private tail: Buffer = Buffer.alloc(0);
+ /** `agentId \t sessionId` → fold state. */
+ private readonly seg = new Map<string, Segment>();
+ /** agentId → lifetime usd. Recomputed after each pass. */
+ private totals = new Map<string, number>();
+ /** One pass at a time; a timer must never stack folds on itself. */
+ private folding = false;
+ /** True once a full pass has completed, so callers can tell "no spend" from
+ * "not read yet" instead of reporting a confident $0. */
+ private warm = false;
+
+ /** Lifetime usd for one agent, or null when the ledger has not been folded
+ * yet. Null rather than 0 so a caller never publishes a cold zero as fact. */
+ usdFor(agentId: string): number | null {
+ if (!this.warm) return null;
+ return this.totals.get(agentId) ?? 0;
+ }
+
+ /** Every agent's lifetime usd. Empty until the first pass completes. */
+ all(): Map<string, number> {
+ return new Map(this.totals);
+ }
+
+ /** Has at least one full pass completed? */
+ get ready(): boolean {
+ return this.warm;
+ }
+
+ /** True lifetime spend across every agent in the ledger. */
+ floorTotal(): number {
+ let t = 0;
+ for (const v of this.totals.values()) t += v;
+ return t;
+ }
+
+ /**
+ * Fold whatever has been appended since the last pass. Returns immediately;
+ * the work happens off the caller's stack. Safe to call from a timer and
+ * never throws (a ledger we cannot read just leaves the last good totals in
+ * place, same contract as the other best-effort writers here).
+ */
+ refresh(ledgerPath: string): Promise<void> {
+ if (this.folding) return Promise.resolve();
+ this.folding = true;
+ return this.fold(ledgerPath)
+ .catch(() => { /* keep last good totals */ })
+ .finally(() => { this.folding = false; });
+ }
+
+ /** Fold repeatedly until caught up to EOF. Convenience for callers that want
+ * the number now rather than over the next few timer ticks. */
+ async refreshFully(ledgerPath: string): Promise<void> {
+ for (let i = 0; i < 4096; i++) {
+ await this.refresh(ledgerPath);
+ if (this.warm) return;
+ }
+ }
+
+ private async fold(ledgerPath: string): Promise<void> {
+ let size: number;
+ try { size = statSync(ledgerPath).size; } catch { return; }
+
+ // Truncated or rotated underneath us: the offset now points past the end,
+ // so every segment we hold is suspect. Start clean.
+ if (size < this.offset) this.reset();
+ if (size === this.offset) { this.warm = true; return; }
+
+ const end = Math.min(size, this.offset + MAX_BYTES_PER_PASS) - 1;
+ const from = this.offset;
+
+ await new Promise<void>((resolve, reject) => {
+ const stream = createReadStream(ledgerPath, { start: from, end });
+ stream.on('data', (chunk: string | Buffer) => {
+ const buf = typeof chunk === 'string' ? Buffer.from(chunk) : chunk;
+ this.consume(buf);
+ });
+ stream.on('error', reject);
+ stream.on('end', () => resolve());
+ });
+
+ this.offset = end + 1;
+ this.recompute();
+ // Only "warm" once we have caught up to EOF; a capped pass is still behind.
+ if (this.offset >= size) this.warm = true;
+ }
+
+ /** Fold one buffer, holding back any incomplete trailing line. */
+ private consume(chunk: Buffer): void {
+ const buf = this.tail.length ? Buffer.concat([this.tail, chunk]) : chunk;
+ const cut = buf.lastIndexOf(0x0a); // '\n'
+ if (cut === -1) { this.tail = buf; return; }
+ this.tail = buf.subarray(cut + 1);
+ for (const line of buf.subarray(0, cut).toString('utf8').split('\n')) {
+ if (line) this.foldLine(line);
+ }
+ }
+
+ private foldLine(line: string): void {
+ let row: { agent_id?: string; session_id?: string; usd?: number };
+ try { row = JSON.parse(line); } catch { return; } // half-written tail line
+ if (!row || typeof row.agent_id !== 'string') return;
+ const usd = typeof row.usd === 'number' && Number.isFinite(row.usd) ? row.usd : 0;
+
+ const key = `${row.agent_id}\t${row.session_id ?? ''}`;
+ let s = this.seg.get(key);
+ if (!s) { s = { committed: 0, peak: 0 }; this.seg.set(key, s); }
+
+ if (usd < s.peak - EPS) {
+ // Counter went backwards: the previous segment ended at its peak.
+ s.committed += s.peak;
+ s.peak = usd;
+ } else if (usd > s.peak) {
+ s.peak = usd;
+ }
+ }
+
+ private recompute(): void {
+ const next = new Map<string, number>();
+ for (const [key, s] of this.seg) {
+ const agentId = key.slice(0, key.indexOf('\t'));
+ next.set(agentId, (next.get(agentId) ?? 0) + s.committed + s.peak);
+ }
+ this.totals = next;
+ }
+
+ private reset(): void {
+ this.offset = 0;
+ this.tail = Buffer.alloc(0);
+ this.seg.clear();
+ this.totals = new Map();
+ this.warm = false;
+ }
+}
+
+/**
+ * One-shot fold of a ledger already in memory. Used by tests and by any caller
+ * that wants the number without holding an incremental reader.
+ */
+export function lifetimeUsdFromLedger(text: string): Map<string, number> {
+ const t = new CostLedgerTotals();
+ // Reuse the exact same fold path so the two can never disagree.
+ (t as unknown as { consume(b: Buffer): void }).consume(Buffer.from(text.endsWith('\n') ? text : `${text}\n`));
+ (t as unknown as { recompute(): void }).recompute();
+ return t.all();
+}
diff --git a/src/main/index.ts b/src/main/index.ts
index 45d288e4..7b902b47 100644
--- a/src/main/index.ts
+++ b/src/main/index.ts
@@ -53,6 +53,7 @@ import { registerRealtimeActionIpc } from './realtimeActions';
import { initCompletionWatcher } from './realtimeCompletionWatcher';
import type { TaskCard, InboxMessage } from './realtimeCompletionWatcher';
import { TelemetryCollector } from './telemetry';
+import { CostLedgerTotals } from './costLifetime';
import { analytics } from './analytics';
import { IntegrationBroker } from './integrationBroker';
import * as integrations from './integrations';
@@ -1106,6 +1107,11 @@ function runBreakerBeat(progressWindowMs: number): void {
}
}
+/** Lifetime spend, folded from cost-ledger.jsonl. `telemetry`'s usd counter is
+ * cumulative-since-process-start and restarts at ~0 on every app restart, so
+ * it cannot answer "what has this agent cost us". See costLifetime.ts. */
+const costTotals = new CostLedgerTotals();
+
/** Build + write the live fleet snapshot Michael reads (`<hive>/fleet.json`).
* Always-on (independent of the heartbeat) since `claude agents` can't see the
* hive's sibling sessions. PII-free; never throws (called from a timer). */
@@ -1116,12 +1122,19 @@ function writeFleetSnapshot(): void {
const snap = telemetry.snapshot();
const usageById = new Map(snap.usage.map((u) => [u.agentId, u]));
const now = Date.now();
+ // Async + incremental; returns immediately and never throws into the timer.
+ const hiveRoot = hive.root();
+ if (hiveRoot) void costTotals.refresh(join(hiveRoot, 'cost-ledger.jsonl'));
const agents = Object.entries(reg.agents)
.filter(([, a]) => !a.archived)
.map(([id, a]) => {
const u = usageById.get(id);
const spans = snap.spans[id] ?? [];
const tokens = u ? u.input + u.output + u.cacheRead + u.cacheCreation : 0;
+ // `usd` is LIFETIME (reset-corrected). Until the first fold completes we
+ // fall back to the session figure rather than publishing a cold $0.
+ const lifetime = costTotals.usdFor(id);
+ const sessionUsd = u ? Number(u.usd.toFixed(4)) : 0;
return {
id,
name: a.name,
@@ -1130,7 +1143,8 @@ function writeFleetSnapshot(): void {
isGod: !!a.isGod,
breaker: breaker.levelFor(id),
tokens,
- usd: u ? Number(u.usd.toFixed(4)) : 0,
+ usd: lifetime === null ? sessionUsd : Number(lifetime.toFixed(4)),
+ sessionUsd,
lastTool: spans.length ? spans[spans.length - 1].tool : null,
lastActiveSecAgo: u ? Math.round((now - u.ts) / 1000) : null,
inboxBacklog: hive.inboxBacklog(id)
diff --git a/test/cost-lifetime.test.cjs b/test/cost-lifetime.test.cjs
new file mode 100644
index 00000000..b631ce7c
--- /dev/null
+++ b/test/cost-lifetime.test.cjs
@@ -0,0 +1,168 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const loadTs = require('./load-ts.cjs');
+
+const { CostLedgerTotals } = loadTs('src/main/costLifetime.ts');
+
+/** One ledger row in the exact shape appendCostLedger writes. */
+function row(agent, session, usd) {
+ return JSON.stringify({
+ agent_id: agent, session_id: session, ts: 0,
+ input: 0, output: 0, cache_read: 0, cache_creation: 0, model: '', usd
+ });
+}
+
+function ledgerWith(lines) {
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'md-cost-'));
+ const p = path.join(dir, 'cost-ledger.jsonl');
+ fs.writeFileSync(p, lines.length ? `${lines.join('\n')}\n` : '');
+ return p;
+}
+
+async function totalsFor(lines) {
+ const t = new CostLedgerTotals();
+ await t.refreshFully(ledgerWith(lines));
+ return t;
+}
+
+test('no reset: lifetime is simply the last cumulative value', async () => {
+ const t = await totalsFor([row('a', 's1', 1), row('a', 's1', 5), row('a', 's1', 9.25)]);
+ assert.equal(t.usdFor('a'), 9.25);
+});
+
+test('one reset: the pre-reset peak is added to the open segment', async () => {
+ // climbs to 20, restarts at 0, climbs to 3 -> 23, not 3
+ const t = await totalsFor([
+ row('a', 's1', 8), row('a', 's1', 20),
+ row('a', 's1', 0), row('a', 's1', 3)
+ ]);
+ assert.equal(t.usdFor('a'), 23);
+});
+
+test('several resets in one session all accumulate', async () => {
+ const t = await totalsFor([
+ row('a', 's1', 10), row('a', 's1', 0),
+ row('a', 's1', 7), row('a', 's1', 0),
+ row('a', 's1', 2)
+ ]);
+ assert.equal(t.usdFor('a'), 19);
+});
+
+test('a sub-dollar reset still counts (a $1 threshold would miss this)', async () => {
+ // Both of these occur in the live ledger: 0.92 -> 0.00 and 0.73 -> 0.00.
+ const t = await totalsFor([
+ row('a', 's1', 0.92), row('a', 's1', 0), row('a', 's1', 0.4)
+ ]);
+ assert.equal(Number(t.usdFor('a').toFixed(4)), 1.32);
+});
+
+test('the reset keeps the SAME session_id, which is the whole bug', async () => {
+ const t = await totalsFor([row('a', 'same', 30), row('a', 'same', 0), row('a', 'same', 1)]);
+ assert.equal(t.usdFor('a'), 31);
+});
+
+test('separate sessions for one agent sum together', async () => {
+ const t = await totalsFor([row('a', 's1', 4), row('a', 's2', 6)]);
+ assert.equal(t.usdFor('a'), 10);
+});
+
+test('agents are kept apart, and floorTotal sums the floor', async () => {
+ const t = await totalsFor([
+ row('a', 's1', 10), row('a', 's1', 0), row('a', 's1', 1),
+ row('b', 's2', 5)
+ ]);
+ assert.equal(t.usdFor('a'), 11);
+ assert.equal(t.usdFor('b'), 5);
+ assert.equal(t.floorTotal(), 16);
+});
+
+test('an unknown agent is 0 once warm, and null before any fold', async () => {
+ const cold = new CostLedgerTotals();
+ assert.equal(cold.usdFor('nobody'), null, 'cold must not claim $0 as fact');
+ assert.equal(cold.ready, false);
+ const t = await totalsFor([row('a', 's1', 1)]);
+ assert.equal(t.ready, true);
+ assert.equal(t.usdFor('nobody'), 0);
+});
+
+test('INCREMENTAL: folding in two passes equals folding in one', async () => {
+ const first = [row('a', 's1', 8), row('a', 's1', 20)];
+ const rest = [row('a', 's1', 0), row('a', 's1', 3)];
+
+ const p = ledgerWith(first);
+ const t = new CostLedgerTotals();
+ await t.refreshFully(p);
+ assert.equal(t.usdFor('a'), 20);
+
+ fs.appendFileSync(p, `${rest.join('\n')}\n`);
+ await t.refreshFully(p);
+ assert.equal(t.usdFor('a'), 23, 'appended lines must fold onto existing state');
+
+ const oneShot = await totalsFor([...first, ...rest]);
+ assert.equal(t.usdFor('a'), oneShot.usdFor('a'));
+});
+
+test('INCREMENTAL: a half-written trailing line is not lost or double counted', async () => {
+ const p = ledgerWith([row('a', 's1', 5)]);
+ const partial = row('a', 's1', 11);
+ fs.appendFileSync(p, partial.slice(0, 20)); // torn mid-write, no newline
+
+ const t = new CostLedgerTotals();
+ await t.refreshFully(p);
+ assert.equal(t.usdFor('a'), 5, 'the torn line must not be parsed');
+
+ fs.appendFileSync(p, `${partial.slice(20)}\n`); // writer finishes the line
+ await t.refreshFully(p);
+ assert.equal(t.usdFor('a'), 11, 'the completed line must be folded exactly once');
+});
+
+test('re-reading an unchanged ledger does not double count', async () => {
+ const p = ledgerWith([row('a', 's1', 10), row('a', 's1', 0), row('a', 's1', 4)]);
+ const t = new CostLedgerTotals();
+ await t.refreshFully(p);
+ await t.refreshFully(p);
+ await t.refreshFully(p);
+ assert.equal(t.usdFor('a'), 14);
+});
+
+test('truncation or rotation rebuilds from scratch instead of going negative', async () => {
+ const p = ledgerWith([row('a', 's1', 10), row('a', 's1', 25)]);
+ const t = new CostLedgerTotals();
+ await t.refreshFully(p);
+ assert.equal(t.usdFor('a'), 25);
+
+ fs.writeFileSync(p, `${row('a', 's1', 2)}\n`); // rotated: smaller than the offset
+ await t.refreshFully(p);
+ assert.equal(t.usdFor('a'), 2, 'stale offset must not survive a truncation');
+});
+
+test('malformed and empty lines are skipped, not fatal', async () => {
+ const p = ledgerWith([row('a', 's1', 3)]);
+ fs.appendFileSync(p, '\nnot json at all\n{"agent_id":null}\n');
+ fs.appendFileSync(p, `${row('a', 's1', 7)}\n`);
+ const t = new CostLedgerTotals();
+ await t.refreshFully(p);
+ assert.equal(t.usdFor('a'), 7);
+});
+
+test('a missing ledger leaves the last good totals in place', async () => {
+ const p = ledgerWith([row('a', 's1', 9)]);
+ const t = new CostLedgerTotals();
+ await t.refreshFully(p);
+ await t.refresh(path.join(path.dirname(p), 'does-not-exist.jsonl'));
+ assert.equal(t.usdFor('a'), 9);
+});
+
+test('a non-numeric usd is treated as 0 rather than NaN-poisoning the total', async () => {
+ const p = ledgerWith([row('a', 's1', 5)]);
+ fs.appendFileSync(p, `${JSON.stringify({ agent_id: 'a', session_id: 's1', usd: 'lots' })}\n`);
+ const t = new CostLedgerTotals();
+ await t.refreshFully(p);
+ assert.equal(Number.isFinite(t.usdFor('a')), true);
+ assert.equal(t.usdFor('a'), 5);
+});