claude-agent-ledger 0.4.1 → 0.7.1

package/README.md

@@ -5,6 +5,10 @@
 [![npm](https://img.shields.io/npm/v/claude-agent-ledger.svg)](https://www.npmjs.com/package/claude-agent-ledger)
 [![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
 
+> Use `--anonymize` before sharing output. It replaces project paths and
+> session IDs, but it does not rename subagent or tool names — review those
+> before you post a screenshot.
+
 ---
 
 ## Why
@@ -23,19 +27,40 @@ If you run **seven** subagents daily (reliability, release, review, iOS factory,
 
 ## Install
 
+Requires [Bun](https://bun.sh/) 1.1 or newer. The CLI is Bun-native even when
+you install it from npm.
+
 ```bash
-npm install -g claude-agent-ledger
-# or: bun install -g claude-agent-ledger
+bun install -g claude-agent-ledger
+# or, with Bun already available: npm install -g claude-agent-ledger
 
 agent-ledger week --summary        # the dashboard (start here)
-agent-ledger week --by model       # which Claude model burned the budget
+agent-ledger week --tree           # parent → child subagent attribution
+agent-ledger week --by tool        # which tool ate the budget (Read/Bash/Grep/MCP)
+agent-ledger week --by model       # opus vs sonnet vs haiku
 agent-ledger week --by project     # which project ate your tokens
 agent-ledger week --by session     # which single sessions went sideways
 agent-ledger week --by day         # daily bar chart with peak/avg/variance
+agent-ledger today --budget 50     # CI gate: exit 2 if today > $50
+agent-ledger week --json | jq      # JSON output for any view, including summary
 agent-ledger month --md > report.md
+
+# Live tail — polling delta meter
+agent-ledger watch                          # refresh every 10s
+agent-ledger watch 4                        # refresh every 4s
+
+# Root-cause analysis on a single expensive session
+agent-ledger explain <session-id>           # heuristic: top-3 turns + tool/model breakdown
+ANTHROPIC_API_KEY=sk-ant-... agent-ledger explain <session-id>
+                                            # LLM mode: Haiku 4.5 ≤4-bullet root cause (typically <$0.005/run)
 ```
 
-No server. No account. No data leaves your machine.
+All aggregate commands run locally, require no account, and make no network
+requests. `explain` is also local by default. If you explicitly set
+`ANTHROPIC_API_KEY`, it sends derived session metrics — subagent/model/tool
+names, timestamps, token counts, and cost totals — to the
+Anthropic API. The session identifier is redacted. It does **not** send prompts,
+responses, tool content, or project paths.
 
 ## Why this and not `/cost`?
 
@@ -54,78 +79,24 @@ Claude Code's built-in `/cost` shows the **current session** cost. That's it.
 
 Run `agent-ledger week --summary` once and decide.
 
-## Example output (real, from the author's machine)
+## Example
 
-### `--summary` (the dashboard)
+This is deterministic output from the repository's synthetic fixture, using the
+price snapshot documented below:
 
-```
-agent-ledger week summary  2026-04-15 → 2026-04-22
-
-  Shadow cost           $13,450.05
-  Sessions              219
-  Projects              9
-  Plan reference        $200/mo (Max)
-  Multiplier            252× vs Max plan
-
-  Top subagent          (main)            $12,787.19 (95%)
-  Top model             claude-opus-4-7   $7,278.87 (54%)
-  Top project           ~/clawbot         $6,657.93 (50%)
-  Peak day              2026-04-15        $3,679.16
-
-  Project mix
-    ~/clawbot                      $6,657.93 (50%)
-    ~/clawbot-work                 $4,433.32 (33%)
-    ~/ZStack-zstack-workspace      $1,890.02 (14%)
-
-  Cache 1h writes       119.65M tokens · $3589.46
-  Cache reads           5.59B tokens · $8236.15
-  Cache reuse           38× reads/writes
-  Server tools          none
-```
+```text
+agent-ledger today summary
 
-### Default — by subagent
+  Shadow cost           $0.08
+  Sessions              2
+  Projects              1
 
-```
-agent-ledger week · 2026-04-14 → 2026-04-21
-
-  subagent              sess      tokens(in/out)         cache tokens (1h/5m/read)       cost
-  ───────────────────────────────────────────────────────────────────────────────────────────
-  (main)                  28       514K / 15.87M  1h:116.10M 5m:      0 r:5229.48M  $12524.97
-  general-purpose        148         113K / 955K  1h:      0 5m: 20.67M r: 183.94M    $599.97
-  Swift Developer         13           4K / 574K  1h:      0 5m:  1.61M r:  47.55M     $28.93
-  Market Researcher       10          107K / 74K  1h:      0 5m:   863K r:   8.61M      $7.26
-  Explore                 13          176K / 77K  1h:      0 5m:  2.60M r:  22.38M      $6.47
-  zstackws                 3           232 / 20K  1h:      0 5m:   829K r:   3.52M      $4.47
-  claude-code-guide        1             2K / 2K  1h:      0 5m:    56K r:    223K      $0.08
-  ───────────────────────────────────────────────────────────────────────────────────────────
-  total                  216       916K / 17.57M  1h:116.10M 5m: 26.62M r:5495.71M  $13172.14
+  Top subagent          Reality Checker  $0.06 (74%)
+  Top model             claude-sonnet-4-6  $0.06 (74%)
+  Cache reads           56K tokens · $0.02
+  Cache reuse           28× reads/writes
 ```
 
-### `--by model`
-
-```
-  subagent              sess      tokens(in/out)         cache tokens (1h/5m/read)       cost
-  ───────────────────────────────────────────────────────────────────────────────────────────
-  claude-opus-4-7         16        59K / 8.35M   1h: 61.15M 5m:  2.32M r:2974.59M   $6967.29
-  claude-opus-4-6        127       544K / 8.25M   1h: 55.02M 5m: 13.30M r:2422.18M   $6160.46
-  claude-sonnet-4-6       65        135K / 946K   1h:      0 5m:  8.81M r:  98.12M     $77.07
-  claude-haiku-4-5        13        178K /  67K   1h:      0 5m:  2.19M r:  21.57M      $4.33
-```
-
-### `--by day` (ASCII bar chart)
-
-```
-  2026-04-15   $3749.84  ████████████████████████████████████ (18 sess)
-  2026-04-16   $2492.99  ████████████████████████             (175 sess)
-  2026-04-17   $2111.63  ████████████████████                 (9 sess)
-  2026-04-18   $1840.02  ██████████████████                   (18 sess)
-  2026-04-19    $644.97  ██████                               (5 sess)
-  2026-04-20   $1095.58  ███████████                          (6 sess)
-  2026-04-21   $1273.55  ████████████                         (9 sess)
-```
-
-Yes those are real numbers. Yes it's a lot. See [Shadow cost vs actual bill](#shadow-cost-vs-actual-bill).
-
 ## Shadow cost vs actual bill
 
 The `cost` column shows what you **would** pay at Anthropic's pay-as-you-go API rates.
@@ -135,9 +106,13 @@ If you're on a fixed-price subscription (Claude Pro / Max / Claude Code plan), y
 - Understanding where time-and-token budget goes, regardless of how you pay
 - Spotting runaway agents (a 10× spike is still a 10× spike, capped or not)
 - Deciding when to downshift to Haiku or up to Opus per task
-- Justifying a Max subscription internally ("our shadow cost is $13K/wk, Max is $200/mo — that's a 65× discount")
+- Comparing usage concentration with a fixed-price plan. Shadow cost is an
+  estimate, not a claim that subscription usage is interchangeable with raw API
+  capacity.
 
-If you're on pay-as-you-go, the `cost` column is roughly your bill (±5–10% depending on tier / geography / `server_tool_use` calibration).
+If you're on pay-as-you-go, treat the `cost` column as a directional estimate.
+Batch discounts, long-context premiums, provider-specific rates, retries, and
+future price changes can make an invoice differ.
 
 ## How it works
 
@@ -147,10 +122,10 @@ and any `server_tool_use` (web_search / web_fetch) requests. Subagent invocation
 under `<session>/subagents/agent-*.jsonl`, with a sidecar `.meta.json` carrying the real
 subagent name (e.g. `Reality Checker`, `ios-factory`).
 
-`claude-agent-ledger` walks the tree, resolves subagent types from the sidecar metadata,
-and aggregates by your chosen key (subagent, model, or day). Pricing is applied locally
-from `src/pricing.ts`. Nothing is sent anywhere — the tool never touches the network
-after install.
+`claude-agent-ledger` walks the tree, resolves subagent types from the sidecar
+metadata, and aggregates by your chosen key. Pricing is applied locally from
+`src/pricing.ts`. Aggregate commands never touch the network after install; the
+optional API-backed `explain` mode is disclosed in [Install](#install).
 
 ### Cache accounting
 
@@ -166,24 +141,31 @@ Naive trackers lump these together as "input" and either overstate (by counting
 
 ### Server tool pricing
 
-`web_search_requests` and `web_fetch_requests` are counted at $0.01/request and shown in a footer when present:
+`web_search_requests` cost $0.01/request. `web_fetch_requests` are counted for
+observability but have no per-request charge; fetched content still contributes
+normal token costs. Both appear in the footer:
 
 ```
   server tools: web_search ×7, web_fetch ×0  ($0.07)
 ```
 
-If Anthropic's actual rate differs (or web_fetch has its own price), open an issue.
+Rates were checked against Anthropic's official pricing page on 2026-07-23.
+If a log contains a model ID without a verified rate, the CLI warns on stderr
+and leaves that model's token cost at `$0.00` instead of guessing.
 
 ## Flags
 
 | Flag | What it does |
 |---|---|
 | `--summary` | One-screen dashboard with all the headline numbers |
-| `--by <subagent\|model\|day\|project\|session>` | Group rows. Default: `subagent`. `day` renders as ASCII bar chart. |
+| `--by <subagent\|model\|day\|project\|session\|tool>` | Group rows. Default: `subagent`. `day` renders as ASCII bar chart. |
+| `--tree` | Render parent → child subagent cost attribution |
+| `--budget <USD>` | Exit with code 2 when estimated cost exceeds the threshold |
 | `--anonymize` | Replace project paths and session ids with `~/repo-A`, `sess-A`, ... so you can share screenshots without doxing your employer / private repos. |
 | `--md` | Markdown table output (good for committing or sharing) |
 | `--json` | Raw JSON output (pipe into jq) |
-| `--plan pro\|max` | Hide dollar columns; show token utilization only |
+| `--plan pro\|max` | Mask estimated costs in grouped table views; `--summary` and `--tree` keep their cost-oriented output |
+| `--verbose` | Print parse counts and elapsed time to stderr |
 
 | Env | What it does |
 |---|---|
@@ -205,11 +187,16 @@ If Anthropic's actual rate differs (or web_fetch has its own price), open an iss
 
 ## Status
 
-`v0.2.0` shipped 2026-04-21. Validated on ~200K turns of real Claude Code logs.
-Pricing matches Anthropic published rates as of 2026-04-21. Shadow cost values
-may drift ±5-10% from Anthropic's actual invoice in edge cases (retries, tier
-bumps, `server_tool_use` calibration). Calibration PRs welcome — see issue
-templates.
+The npm badge above reports the current published version. See
+[`CHANGELOG.md`](CHANGELOG.md) for release history.
+
+The source price table was checked against Anthropic's published rates on
+2026-07-23. Sonnet 5 automatically switches from its introductory rate to the
+published standard rate on 2026-09-01. Pricing can change, so shadow costs are
+estimates rather than invoice replicas; check
+[`src/pricing.ts`](src/pricing.ts) and the
+[official pricing page](https://platform.claude.com/docs/en/about-claude/pricing)
+before making billing decisions.
 
 - [x] Log parser (JSONL streaming, recursive subagent discovery)
 - [x] Per-subagent aggregation
@@ -219,7 +206,7 @@ templates.
 - [x] ANSI color, TTY-aware
 - [x] Cache 1h/5m TTL split pricing
 - [x] `--plan pro|max` to mask shadow cost
-- [x] `server_tool_use` pricing (web_search, web_fetch)
+- [x] `server_tool_use` accounting (paid web search, no-fee web fetch)
 - [ ] Cost forecasting (trailing 7-day burn rate)
 - [ ] Calibration against real Anthropic invoices
 - [ ] Homebrew tap
@@ -237,14 +224,15 @@ agent-ledger today
 ## Development
 
 ```bash
-bun test           # 22 pass, 0 fail
+bun test           # 35 pass, 0 fail
 bun run typecheck
+bun run build
 ```
 
 ## Author
 
-Built by [@XJM-free](https://jiexiang.dev) while running seven production Claude Code
-subagents for infrastructure work. More context coming on the blog.
+Built by [Jie Xiang](https://jiexiang.dev)
+([@XJM-free](https://github.com/XJM-free)).
 
 ## License
 

package/bin/agent-ledger.ts

@@ -1,8 +1,11 @@
 #!/usr/bin/env bun
-import { aggregate, type GroupKey } from '../src/aggregator.ts';
+import { Aggregator, type GroupKey, SubagentGraph } from '../src/aggregator.ts';
+import { analyzeSession, formatHeuristic, llmExplain } from '../src/explain.ts';
 import { formatMarkdown, formatSummary, formatTable, formatTrend } from '../src/format.ts';
 import { parseAll } from '../src/parser.ts';
-import type { LedgerReport, SessionTurn } from '../src/types.ts';
+import { isKnownModel } from '../src/pricing.ts';
+import { formatTree, formatTreeMarkdown } from '../src/tree.ts';
+import type { LedgerReport, SubagentTreeNode } from '../src/types.ts';
 
 type Period = 'today' | 'week' | 'month';
 type Plan = 'payg' | 'pro' | 'max';
@@ -14,7 +17,10 @@ interface Args {
 	plan: Plan;
 	by: GroupKey;
 	summary: boolean;
+	tree: boolean;
 	anonymize: boolean;
+	budget?: number; // USD threshold; non-zero exit if exceeded
+	verbose: boolean;
 }
 
 function periodRange(period: Period): { from: Date; to: Date } {
@@ -33,35 +39,39 @@ function periodRange(period: Period): { from: Date; to: Date } {
 }
 
 function usage(): never {
-	console.error(`Usage: agent-ledger <today|week|month> [flags]
+	console.error(`Usage:
+  agent-ledger <today|week|month> [flags]    — aggregate views
+  agent-ledger explain <sessionId>           — root-cause why one session was expensive (new in 0.6)
 
 Flags:
-  --summary                   One-screen dashboard: total + top subagent + top
-                              model + peak day + cache reuse + leverage vs $200/mo plan
-  --by <subagent|model|day|project|session>
+  --summary                   One-screen dashboard (start here).
+  --by <subagent|model|day|project|session|tool>
                               Group rows by:
                                 subagent  (default) — agent attribution
                                 model     — opus vs sonnet vs haiku
                                 day       — daily ASCII bar chart
                                 project   — by Claude Code project (decoded path)
                                 session   — by session id (top spenders)
+                                tool      — by Read/Bash/Write/Grep — what your turns burn on
+  --tree                      Subagent graph: parent→child cost attribution.
+                              The MOAT view: orchestrator → 3×researcher + 6×swift-dev = $312.
+  --budget <USD>              Exit non-zero (code 2) if total cost > USD. Pipe-friendly.
   --md                        Markdown table output (good for sharing / commits)
-  --json                      Raw JSON output (for piping into jq)
-  --plan pro|max              Suppress dollar columns (token utilization only)
-  --anonymize                 Replace project paths and session ids with safe
-                              placeholders (~/repo-A, sess-A) so the output is
-                              shareable without doxing yourself.
+  --json                      Raw JSON output (also works with --summary now)
+  --plan pro|max              Mask estimated costs in grouped table views.
+  --anonymize                 Replace project paths and session ids with safe placeholders.
+  --verbose                   Print parse stats (files, turns, elapsed) to stderr.
 
 Environment:
   NO_COLOR=1                  Disable ANSI colors
   FORCE_COLOR=1               Force colors when piping
 
 Examples:
-  agent-ledger week --summary           # the dashboard
-  agent-ledger week --by day            # daily bar chart
-  agent-ledger week --by model          # which Claude model burned the budget
-  agent-ledger month --md > month.md
+  agent-ledger week --summary               # the dashboard
+  agent-ledger week --tree                  # subagent fan-out tree
+  agent-ledger week --by tool               # which Claude tool ate the budget
   agent-ledger week --json | jq '.total.cost.totalCost'
+  agent-ledger today --budget 50            # CI gate: fail if today > $50
 `);
 	process.exit(1);
 }
@@ -72,6 +82,7 @@ function parseArgs(argv: string[]): Args {
 
 	let plan: Plan = 'payg';
 	let by: GroupKey = 'subagent';
+	let budget: number | undefined;
 	for (let i = 0; i < rest.length; i++) {
 		const flag = rest[i];
 		if (flag === '--plan') {
@@ -89,13 +100,34 @@ function parseArgs(argv: string[]): Args {
 				next === 'model' ||
 				next === 'day' ||
 				next === 'project' ||
-				next === 'session'
+				next === 'session' ||
+				next === 'tool'
 			) {
 				by = next;
 				i++;
 			} else {
+				console.error(`agent-ledger: unknown --by value '${next}'`);
 				usage();
 			}
+		} else if (flag === '--budget') {
+			const next = rest[i + 1];
+			const n = Number(next);
+			if (!Number.isFinite(n) || n <= 0) {
+				console.error(`agent-ledger: --budget requires a positive number (got '${next}')`);
+				usage();
+			}
+			budget = n;
+			i++;
+		} else if (
+			flag !== '--md' &&
+			flag !== '--json' &&
+			flag !== '--summary' &&
+			flag !== '--tree' &&
+			flag !== '--anonymize' &&
+			flag !== '--verbose'
+		) {
+			console.error(`agent-ledger: unknown flag '${flag}'`);
+			usage();
 		}
 	}
 	return {
@@ -105,19 +137,17 @@ function parseArgs(argv: string[]): Args {
 		plan,
 		by,
 		summary: rest.includes('--summary'),
+		tree: rest.includes('--tree'),
 		anonymize: rest.includes('--anonymize'),
+		budget,
+		verbose: rest.includes('--verbose'),
 	};
 }
 
-// Replace identifying labels with safe placeholders. Run after aggregation,
-// before formatting. We anonymize project paths (which leak employer + repo
-// names) and session ids; leave subagent / model / day untouched (those are
-// either public Anthropic info or generic agent type names).
 function anonymizeReport(report: LedgerReport, group: GroupKey): LedgerReport {
 	if (group !== 'project' && group !== 'session') return report;
 	const prefix = group === 'project' ? '~/repo-' : 'sess-';
 	const labelFor = (i: number): string => {
-		// Use A..Z then AA..ZZ for many entries
 		if (i < 26) return prefix + String.fromCharCode(65 + i);
 		return prefix + String.fromCharCode(65 + Math.floor(i / 26) - 1) + String.fromCharCode(65 + (i % 26));
 	};
@@ -125,9 +155,27 @@ function anonymizeReport(report: LedgerReport, group: GroupKey): LedgerReport {
 	return { ...report, rows: newRows };
 }
 
-// For --summary we may need to anonymize multiple sub-reports.
-function anonymizeForSummary(byProject: LedgerReport): LedgerReport {
-	return anonymizeReport(byProject, 'project');
+function anonymizeTrees(roots: SubagentTreeNode[]): SubagentTreeNode[] {
+	const labels = new Map<string, string>();
+	const labelFor = (sessionId: string): string => {
+		const existing = labels.get(sessionId);
+		if (existing) return existing;
+		const i = labels.size;
+		const suffix =
+			i < 26
+				? String.fromCharCode(65 + i)
+				: String.fromCharCode(65 + Math.floor(i / 26) - 1) +
+					String.fromCharCode(65 + (i % 26));
+		const label = `sess-${suffix}`;
+		labels.set(sessionId, label);
+		return label;
+	};
+	const visit = (node: SubagentTreeNode): SubagentTreeNode => ({
+		...node,
+		sessionId: labelFor(node.sessionId),
+		children: node.children.map(visit),
+	});
+	return roots.map(visit);
 }
 
 function planMask(report: LedgerReport, plan: Plan): LedgerReport {
@@ -148,49 +196,188 @@ function planMask(report: LedgerReport, plan: Plan): LedgerReport {
 	};
 }
 
-// Materialize once so --summary can re-aggregate by 3 dimensions cheaply.
-async function collectTurns(opts: { from: Date; to: Date }): Promise<SessionTurn[]> {
-	const out: SessionTurn[] = [];
-	for await (const t of parseAll(opts)) out.push(t);
-	return out;
+// `--watch` live-tail mode. Re-aggregates "today" every N seconds and
+// prints a clean delta meter. Polling-based (no inotify) so it works on
+// any platform Bun runs on. Ctrl-C to exit.
+async function watchCmd(intervalSec: number): Promise<void> {
+	const interval = Math.max(2, intervalSec);
+	let prevCost = 0;
+	let prevTurnCount = 0;
+	const t0 = Date.now();
+	console.log(`agent-ledger watch — refreshing every ${interval}s · Ctrl-C to exit`);
+	console.log('');
+	const tick = async () => {
+		const { from, to } = periodRange('today');
+		const agg = new Aggregator('subagent', from, to);
+		let turns = 0;
+		for await (const turn of parseAll({ from, to })) {
+			turns++;
+			agg.add(turn);
+		}
+		const report = agg.finalize();
+		const cost = report.total.cost.totalCost;
+		const dCost = cost - prevCost;
+		const dTurns = turns - prevTurnCount;
+		const elapsedMin = ((Date.now() - t0) / 60000).toFixed(1);
+		const arrow = dCost > 0 ? '↑' : dCost < 0 ? '↓' : '·';
+		const ts = new Date().toISOString().slice(11, 19);
+		const top = report.rows[0];
+		const topLabel = top ? `top: ${top.subagent} ${fmtUsdInline(top.cost.totalCost)}` : 'no data';
+		console.log(
+			`[${ts}] today $${cost.toFixed(2)}  ${arrow} +$${dCost.toFixed(2)}  · ${turns} turns (Δ${dTurns}) · ${topLabel} · live ${elapsedMin}m`,
+		);
+		prevCost = cost;
+		prevTurnCount = turns;
+	};
+	await tick();
+	const id = setInterval(() => {
+		tick().catch((e) => console.error('watch tick error:', e));
+	}, interval * 1000);
+	process.on('SIGINT', () => {
+		clearInterval(id);
+		console.log('\nagent-ledger watch — exiting');
+		process.exit(0);
+	});
+	// Keep process alive
+	await new Promise(() => {});
 }
 
-async function* iterTurns(turns: SessionTurn[]): AsyncGenerator<SessionTurn> {
-	for (const t of turns) yield t;
+const fmtUsdInline = (n: number): string => '$' + n.toFixed(n < 0.01 ? 4 : 2);
+
+async function explainCmd(sessionPrefix: string | undefined): Promise<void> {
+	if (!sessionPrefix) {
+		console.error('agent-ledger explain: missing sessionId argument');
+		console.error('Usage: agent-ledger explain <sessionId>');
+		console.error('       (sessionId can be a full uuid or 8-char prefix)');
+		process.exit(1);
+	}
+	const analysis = await analyzeSession(sessionPrefix);
+	if (!analysis) {
+		console.error(`agent-ledger explain: no session found matching '${sessionPrefix}'`);
+		console.error('  (try the 8-char prefix from `agent-ledger week --by session`)');
+		process.exit(1);
+	}
+	const heuristic = formatHeuristic(analysis);
+	console.log(heuristic);
+	const llm = await llmExplain(analysis);
+	if (llm) {
+		console.log('');
+		console.log(llm);
+	} else if (!process.env.ANTHROPIC_API_KEY) {
+		console.log('');
+		console.log(
+			'💡 Set ANTHROPIC_API_KEY to enable LLM root-cause analysis (typically <$0.005/run via Haiku 4.5)',
+		);
+	}
 }
 
 async function main(): Promise<void> {
+	// Subcommand dispatch.
+	if (process.argv[2] === 'explain') {
+		return explainCmd(process.argv[3]);
+	}
+	if (process.argv[2] === 'watch') {
+		const interval = Number(process.argv[3]) || 10;
+		return watchCmd(interval);
+	}
 	const args = parseArgs(process.argv.slice(2));
 	const { from, to } = periodRange(args.period);
-	const turns = await collectTurns({ from, to });
-
-	if (args.summary) {
-		const [bySub, byMod, byDay, byProjRaw] = await Promise.all([
-			aggregate(iterTurns(turns), from, to, 'subagent'),
-			aggregate(iterTurns(turns), from, to, 'model'),
-			aggregate(iterTurns(turns), from, to, 'day'),
-			aggregate(iterTurns(turns), from, to, 'project'),
-		]);
-		const byProj = args.anonymize ? anonymizeForSummary(byProjRaw) : byProjRaw;
-		console.log(formatSummary(bySub, byMod, byDay, byProj, args.period));
-		return;
+	const t0 = Date.now();
+
+	// Determine which aggregators we need based on flags.
+	// Single parser pass dispatches to all in parallel — no buffering.
+	const aggBySub = new Aggregator('subagent', from, to);
+	const aggByMod = args.summary ? new Aggregator('model', from, to) : undefined;
+	const aggByDay = args.summary ? new Aggregator('day', from, to) : undefined;
+	const aggByProj = args.summary ? new Aggregator('project', from, to) : undefined;
+	const aggUser = !args.summary && !args.tree ? new Aggregator(args.by, from, to) : undefined;
+	const graph = args.tree ? new SubagentGraph() : undefined;
+
+	let turnCount = 0;
+	const unknownModels = new Set<string>();
+	for await (const turn of parseAll({ from, to })) {
+		turnCount++;
+		if (turn.model && !isKnownModel(turn.model)) {
+			unknownModels.add(turn.model);
+		}
+		aggBySub.add(turn);
+		aggByMod?.add(turn);
+		aggByDay?.add(turn);
+		aggByProj?.add(turn);
+		aggUser?.add(turn);
+		graph?.add(turn);
+	}
+
+	if (unknownModels.size > 0) {
+		console.error(
+			'agent-ledger: no verified price for model(s): ' +
+				[...unknownModels].sort().join(', ') +
+				'; their token cost is shown as $0.00',
+		);
 	}
 
-	let report = await aggregate(iterTurns(turns), from, to, args.by);
-	if (args.anonymize) report = anonymizeReport(report, args.by);
-	report = planMask(report, args.plan);
-
-	let output: string;
-	if (args.json) {
-		output = JSON.stringify(report, null, 2);
-	} else if (args.markdown) {
-		output = formatMarkdown(report, args.period);
-	} else if (args.by === 'day') {
-		output = formatTrend(report, args.period);
+	if (args.verbose) {
+		const elapsed = Date.now() - t0;
+		console.error(
+			`agent-ledger: parsed ${turnCount} turns from ~/.claude/projects in ${elapsed}ms`,
+		);
+	}
+
+	let totalCost = aggBySub.finalize().total.cost.totalCost;
+
+	if (args.tree) {
+		const rawRoots = graph!.finalize(20);
+		const roots = args.anonymize ? anonymizeTrees(rawRoots) : rawRoots;
+		totalCost = roots.reduce((s, r) => s + r.totalCost, 0);
+		const out =
+			args.json
+				? JSON.stringify({ roots, totalCost }, null, 2)
+				: args.markdown
+					? formatTreeMarkdown(roots, totalCost)
+					: formatTree(roots, totalCost);
+		console.log(out);
+	} else if (args.summary) {
+		const bySubR = aggBySub.finalize();
+		const byModR = aggByMod!.finalize();
+		const byDayR = aggByDay!.finalize();
+		let byProjR = aggByProj!.finalize();
+		if (args.anonymize) byProjR = anonymizeReport(byProjR, 'project');
+		totalCost = bySubR.total.cost.totalCost;
+		if (args.json) {
+			console.log(
+				JSON.stringify(
+					{ subagent: bySubR, model: byModR, day: byDayR, project: byProjR, totalCost },
+					null,
+					2,
+				),
+			);
+		} else {
+			console.log(formatSummary(bySubR, byModR, byDayR, byProjR, args.period));
+		}
 	} else {
-		output = formatTable(report, args.period, args.by);
+		let report = aggUser!.finalize();
+		if (args.anonymize) report = anonymizeReport(report, args.by);
+		// Keep the unmasked estimate for --budget even when --plan hides it.
+		totalCost = report.total.cost.totalCost;
+		report = planMask(report, args.plan);
+		const output =
+			args.json
+				? JSON.stringify(report, null, 2)
+				: args.markdown
+					? formatMarkdown(report, args.period)
+					: args.by === 'day'
+						? formatTrend(report, args.period)
+						: formatTable(report, args.period, args.by);
+		console.log(output);
+	}
+
+	// Budget gate — non-zero exit code so this can be a CI/shell hook.
+	if (args.budget !== undefined && totalCost > args.budget) {
+		console.error(
+			`agent-ledger: BUDGET EXCEEDED — total $${totalCost.toFixed(2)} > budget $${args.budget.toFixed(2)}`,
+		);
+		process.exit(2);
 	}
-	console.log(output);
 }
 
 main().catch((err) => {