@os-eco/overstory-cli 0.6.1 → 0.6.5

package/src/commands/costs.test.ts

@@ -22,7 +22,7 @@ import { costsCommand } from "./costs.ts";
 function makeMetrics(overrides: Partial<SessionMetrics> = {}): SessionMetrics {
 	return {
 		agentName: "builder-1",
-		beadId: "task-001",
+		taskId: "task-001",
 		capability: "builder",
 		startedAt: new Date().toISOString(),
 		completedAt: new Date().toISOString(),
@@ -86,7 +86,7 @@ describe("costsCommand", () => {
 			await costsCommand(["--help"]);
 			const out = output();
 
-			expect(out).toContain("overstory costs");
+			expect(out).toContain("costs");
 			expect(out).toContain("--agent");
 			expect(out).toContain("--run");
 			expect(out).toContain("--by-capability");
@@ -98,7 +98,7 @@ describe("costsCommand", () => {
 			await costsCommand(["-h"]);
 			const out = output();
 
-			expect(out).toContain("overstory costs");
+			expect(out).toContain("costs");
 		});
 	});
 
@@ -142,8 +142,8 @@ describe("costsCommand", () => {
 		test("outputs valid JSON array with sessions", async () => {
 			const dbPath = join(tempDir, ".overstory", "metrics.db");
 			const store = createMetricsStore(dbPath);
-			store.recordSession(makeMetrics({ agentName: "builder-1", beadId: "t1" }));
-			store.recordSession(makeMetrics({ agentName: "scout-1", beadId: "t2", capability: "scout" }));
+			store.recordSession(makeMetrics({ agentName: "builder-1", taskId: "t1" }));
+			store.recordSession(makeMetrics({ agentName: "scout-1", taskId: "t2", capability: "scout" }));
 			store.close();
 
 			await costsCommand(["--json"]);
@@ -160,7 +160,7 @@ describe("costsCommand", () => {
 			store.recordSession(
 				makeMetrics({
 					agentName: "builder-1",
-					beadId: "t1",
+					taskId: "t1",
 					inputTokens: 100,
 					outputTokens: 50,
 					cacheReadTokens: 30,
@@ -187,7 +187,7 @@ describe("costsCommand", () => {
 		test("JSON output returns empty array when no sessions match", async () => {
 			const dbPath = join(tempDir, ".overstory", "metrics.db");
 			const store = createMetricsStore(dbPath);
-			store.recordSession(makeMetrics({ agentName: "builder-1", beadId: "t1" }));
+			store.recordSession(makeMetrics({ agentName: "builder-1", taskId: "t1" }));
 			store.close();
 
 			await costsCommand(["--json", "--agent", "nonexistent"]);
@@ -203,7 +203,7 @@ describe("costsCommand", () => {
 			store.recordSession(
 				makeMetrics({
 					agentName: "builder-1",
-					beadId: "t1",
+					taskId: "t1",
 					capability: "builder",
 					inputTokens: 100,
 				}),
@@ -211,7 +211,7 @@ describe("costsCommand", () => {
 			store.recordSession(
 				makeMetrics({
 					agentName: "scout-1",
-					beadId: "t2",
+					taskId: "t2",
 					capability: "scout",
 					inputTokens: 50,
 				}),
@@ -238,7 +238,7 @@ describe("costsCommand", () => {
 		test("shows Cost Summary header", async () => {
 			const dbPath = join(tempDir, ".overstory", "metrics.db");
 			const store = createMetricsStore(dbPath);
-			store.recordSession(makeMetrics({ agentName: "builder-1", beadId: "t1" }));
+			store.recordSession(makeMetrics({ agentName: "builder-1", taskId: "t1" }));
 			store.close();
 
 			await costsCommand([]);
@@ -250,7 +250,7 @@ describe("costsCommand", () => {
 		test("shows column headers", async () => {
 			const dbPath = join(tempDir, ".overstory", "metrics.db");
 			const store = createMetricsStore(dbPath);
-			store.recordSession(makeMetrics({ agentName: "builder-1", beadId: "t1" }));
+			store.recordSession(makeMetrics({ agentName: "builder-1", taskId: "t1" }));
 			store.close();
 
 			await costsCommand([]);
@@ -270,7 +270,7 @@ describe("costsCommand", () => {
 			store.recordSession(
 				makeMetrics({
 					agentName: "builder-1",
-					beadId: "t1",
+					taskId: "t1",
 					capability: "builder",
 				}),
 			);
@@ -286,7 +286,7 @@ describe("costsCommand", () => {
 		test("shows separator line", async () => {
 			const dbPath = join(tempDir, ".overstory", "metrics.db");
 			const store = createMetricsStore(dbPath);
-			store.recordSession(makeMetrics({ agentName: "builder-1", beadId: "t1" }));
+			store.recordSession(makeMetrics({ agentName: "builder-1", taskId: "t1" }));
 			store.close();
 
 			await costsCommand([]);
@@ -298,7 +298,7 @@ describe("costsCommand", () => {
 		test("shows Total row", async () => {
 			const dbPath = join(tempDir, ".overstory", "metrics.db");
 			const store = createMetricsStore(dbPath);
-			store.recordSession(makeMetrics({ agentName: "builder-1", beadId: "t1" }));
+			store.recordSession(makeMetrics({ agentName: "builder-1", taskId: "t1" }));
 			store.close();
 
 			await costsCommand([]);
@@ -329,7 +329,7 @@ describe("costsCommand", () => {
 			store.recordSession(
 				makeMetrics({
 					agentName: "builder-1",
-					beadId: "t1",
+					taskId: "t1",
 					inputTokens: 12345,
 					outputTokens: 5678,
 				}),
@@ -349,7 +349,7 @@ describe("costsCommand", () => {
 			store.recordSession(
 				makeMetrics({
 					agentName: "builder-1",
-					beadId: "t1",
+					taskId: "t1",
 					estimatedCostUsd: 0.42,
 				}),
 			);
@@ -367,7 +367,7 @@ describe("costsCommand", () => {
 			store.recordSession(
 				makeMetrics({
 					agentName: "builder-1",
-					beadId: "t1",
+					taskId: "t1",
 					inputTokens: 0,
 					outputTokens: 0,
 					cacheReadTokens: 0,
@@ -389,7 +389,7 @@ describe("costsCommand", () => {
 			store.recordSession(
 				makeMetrics({
 					agentName: "builder-1",
-					beadId: "t1",
+					taskId: "t1",
 					estimatedCostUsd: null,
 				}),
 			);
@@ -408,8 +408,8 @@ describe("costsCommand", () => {
 		test("filters sessions by agent name", async () => {
 			const dbPath = join(tempDir, ".overstory", "metrics.db");
 			const store = createMetricsStore(dbPath);
-			store.recordSession(makeMetrics({ agentName: "builder-1", beadId: "t1", inputTokens: 100 }));
-			store.recordSession(makeMetrics({ agentName: "scout-1", beadId: "t2", inputTokens: 200 }));
+			store.recordSession(makeMetrics({ agentName: "builder-1", taskId: "t1", inputTokens: 100 }));
+			store.recordSession(makeMetrics({ agentName: "scout-1", taskId: "t2", inputTokens: 200 }));
 			store.close();
 
 			await costsCommand(["--json", "--agent", "builder-1"]);
@@ -423,7 +423,7 @@ describe("costsCommand", () => {
 		test("returns empty for non-existent agent", async () => {
 			const dbPath = join(tempDir, ".overstory", "metrics.db");
 			const store = createMetricsStore(dbPath);
-			store.recordSession(makeMetrics({ agentName: "builder-1", beadId: "t1" }));
+			store.recordSession(makeMetrics({ agentName: "builder-1", taskId: "t1" }));
 			store.close();
 
 			await costsCommand(["--json", "--agent", "nonexistent"]);
@@ -441,12 +441,12 @@ describe("costsCommand", () => {
 			const dbPath = join(tempDir, ".overstory", "metrics.db");
 			const store = createMetricsStore(dbPath);
 			store.recordSession(
-				makeMetrics({ agentName: "builder-1", beadId: "task-001", runId: "run-2026-01-01" }),
+				makeMetrics({ agentName: "builder-1", taskId: "task-001", runId: "run-2026-01-01" }),
 			);
 			store.recordSession(
 				makeMetrics({
 					agentName: "scout-1",
-					beadId: "task-002",
+					taskId: "task-002",
 					capability: "scout",
 					runId: "run-other",
 				}),
@@ -465,7 +465,7 @@ describe("costsCommand", () => {
 			const dbPath = join(tempDir, ".overstory", "metrics.db");
 			const store = createMetricsStore(dbPath);
 			store.recordSession(
-				makeMetrics({ agentName: "builder-1", beadId: "t1", runId: "run-2026-01-01" }),
+				makeMetrics({ agentName: "builder-1", taskId: "t1", runId: "run-2026-01-01" }),
 			);
 			store.close();
 
@@ -484,7 +484,7 @@ describe("costsCommand", () => {
 			const dbPath = join(tempDir, ".overstory", "metrics.db");
 			const store = createMetricsStore(dbPath);
 			store.recordSession(
-				makeMetrics({ agentName: "builder-1", beadId: "t1", capability: "builder" }),
+				makeMetrics({ agentName: "builder-1", taskId: "t1", capability: "builder" }),
 			);
 			store.close();
 
@@ -498,7 +498,7 @@ describe("costsCommand", () => {
 			const dbPath = join(tempDir, ".overstory", "metrics.db");
 			const store = createMetricsStore(dbPath);
 			store.recordSession(
-				makeMetrics({ agentName: "builder-1", beadId: "t1", capability: "builder" }),
+				makeMetrics({ agentName: "builder-1", taskId: "t1", capability: "builder" }),
 			);
 			store.close();
 
@@ -514,7 +514,7 @@ describe("costsCommand", () => {
 			store.recordSession(
 				makeMetrics({
 					agentName: "builder-1",
-					beadId: "t1",
+					taskId: "t1",
 					capability: "builder",
 					inputTokens: 1000,
 				}),
@@ -522,7 +522,7 @@ describe("costsCommand", () => {
 			store.recordSession(
 				makeMetrics({
 					agentName: "builder-2",
-					beadId: "t2",
+					taskId: "t2",
 					capability: "builder",
 					inputTokens: 2000,
 				}),
@@ -530,7 +530,7 @@ describe("costsCommand", () => {
 			store.recordSession(
 				makeMetrics({
 					agentName: "scout-1",
-					beadId: "t3",
+					taskId: "t3",
 					capability: "scout",
 					inputTokens: 500,
 				}),
@@ -548,10 +548,10 @@ describe("costsCommand", () => {
 		test("shows correct session count per capability", async () => {
 			const dbPath = join(tempDir, ".overstory", "metrics.db");
 			const store = createMetricsStore(dbPath);
-			store.recordSession(makeMetrics({ agentName: "b1", beadId: "t1", capability: "builder" }));
-			store.recordSession(makeMetrics({ agentName: "b2", beadId: "t2", capability: "builder" }));
-			store.recordSession(makeMetrics({ agentName: "b3", beadId: "t3", capability: "builder" }));
-			store.recordSession(makeMetrics({ agentName: "s1", beadId: "t4", capability: "scout" }));
+			store.recordSession(makeMetrics({ agentName: "b1", taskId: "t1", capability: "builder" }));
+			store.recordSession(makeMetrics({ agentName: "b2", taskId: "t2", capability: "builder" }));
+			store.recordSession(makeMetrics({ agentName: "b3", taskId: "t3", capability: "builder" }));
+			store.recordSession(makeMetrics({ agentName: "s1", taskId: "t4", capability: "scout" }));
 			store.close();
 
 			await costsCommand(["--json", "--by-capability"]);
@@ -584,7 +584,7 @@ describe("costsCommand", () => {
 			const dbPath = join(tempDir, ".overstory", "metrics.db");
 			const store = createMetricsStore(dbPath);
 			for (let i = 0; i < 10; i++) {
-				store.recordSession(makeMetrics({ agentName: `agent-${i}`, beadId: `t-${i}` }));
+				store.recordSession(makeMetrics({ agentName: `agent-${i}`, taskId: `t-${i}` }));
 			}
 			store.close();
 
@@ -599,7 +599,7 @@ describe("costsCommand", () => {
 			const dbPath = join(tempDir, ".overstory", "metrics.db");
 			const store = createMetricsStore(dbPath);
 			for (let i = 0; i < 25; i++) {
-				store.recordSession(makeMetrics({ agentName: `agent-${i}`, beadId: `t-${i}` }));
+				store.recordSession(makeMetrics({ agentName: `agent-${i}`, taskId: `t-${i}` }));
 			}
 			store.close();
 
@@ -620,7 +620,7 @@ describe("costsCommand", () => {
 			store.recordSession(
 				makeMetrics({
 					agentName: "builder-1",
-					beadId: "t1",
+					taskId: "t1",
 					inputTokens: 0,
 					outputTokens: 0,
 					cacheReadTokens: 0,
@@ -644,7 +644,7 @@ describe("costsCommand", () => {
 			store.recordSession(
 				makeMetrics({
 					agentName: "builder-1",
-					beadId: "t1",
+					taskId: "t1",
 					estimatedCostUsd: null,
 				}),
 			);
@@ -664,7 +664,7 @@ describe("costsCommand", () => {
 			store.recordSession(
 				makeMetrics({
 					agentName: "builder-1",
-					beadId: "t1",
+					taskId: "t1",
 					cacheReadTokens: 8000,
 					cacheCreationTokens: 901,
 				}),
@@ -684,7 +684,7 @@ describe("costsCommand", () => {
 			store.recordSession(
 				makeMetrics({
 					agentName: "builder-1",
-					beadId: "t1",
+					taskId: "t1",
 					inputTokens: 100,
 					outputTokens: 50,
 					estimatedCostUsd: 0.1,
@@ -693,7 +693,7 @@ describe("costsCommand", () => {
 			store.recordSession(
 				makeMetrics({
 					agentName: "scout-1",
-					beadId: "t2",
+					taskId: "t2",
 					capability: "scout",
 					inputTokens: 200,
 					outputTokens: 100,
@@ -716,10 +716,10 @@ describe("costsCommand", () => {
 			const dbPath = join(tempDir, ".overstory", "metrics.db");
 			const store = createMetricsStore(dbPath);
 			store.recordSession(
-				makeMetrics({ agentName: "builder-1", beadId: "t1", capability: "builder" }),
+				makeMetrics({ agentName: "builder-1", taskId: "t1", capability: "builder" }),
 			);
 			store.recordSession(
-				makeMetrics({ agentName: "builder-2", beadId: "t2", capability: "builder" }),
+				makeMetrics({ agentName: "builder-2", taskId: "t2", capability: "builder" }),
 			);
 			store.close();
 
@@ -759,7 +759,7 @@ describe("costsCommand", () => {
 				capability: "builder",
 				worktreePath: "/tmp/wt1",
 				branchName: "feat/task1",
-				beadId: "task-001",
+				taskId: "task-001",
 				tmuxSession: "tmux-001",
 				state: "working",
 				pid: 12345,
@@ -815,7 +815,7 @@ describe("costsCommand", () => {
 				capability: "builder",
 				worktreePath: "/tmp/wt1",
 				branchName: "feat/task1",
-				beadId: "task-001",
+				taskId: "task-001",
 				tmuxSession: "tmux-001",
 				state: "working",
 				pid: 12345,
@@ -879,7 +879,7 @@ describe("costsCommand", () => {
 				capability: "builder",
 				worktreePath: "/tmp/wt1",
 				branchName: "feat/task1",
-				beadId: "task-001",
+				taskId: "task-001",
 				tmuxSession: "tmux-001",
 				state: "working",
 				pid: 12345,
@@ -897,7 +897,7 @@ describe("costsCommand", () => {
 				capability: "scout",
 				worktreePath: "/tmp/wt2",
 				branchName: "feat/task2",
-				beadId: "task-002",
+				taskId: "task-002",
 				tmuxSession: "tmux-002",
 				state: "working",
 				pid: 12346,
@@ -956,7 +956,7 @@ describe("costsCommand", () => {
 				capability: "builder",
 				worktreePath: "/tmp/wt1",
 				branchName: "feat/task1",
-				beadId: "task-001",
+				taskId: "task-001",
 				tmuxSession: "tmux-001",
 				state: "working",
 				pid: 12345,

package/src/commands/costs.ts

@@ -8,6 +8,7 @@
 
 import { readdir, stat } from "node:fs/promises";
 import { join } from "node:path";
+import { Command } from "commander";
 import { loadConfig } from "../config.ts";
 import { ValidationError } from "../errors.ts";
 import { color } from "../logging/color.ts";
@@ -16,21 +17,6 @@ import { estimateCost, parseTranscriptUsage } from "../metrics/transcript.ts";
 import { openSessionStore } from "../sessions/compat.ts";
 import type { SessionMetrics } from "../types.ts";
 
-/**
- * Parse a named flag value from args.
- */
-function getFlag(args: string[], flag: string): string | undefined {
-	const idx = args.indexOf(flag);
-	if (idx === -1 || idx + 1 >= args.length) {
-		return undefined;
-	}
-	return args[idx + 1];
-}
-
-function hasFlag(args: string[], flag: string): boolean {
-	return args.includes(flag);
-}
-
 /** Format a number with thousands separators (e.g., 12345 -> "12,345"). */
 function formatNumber(n: number): string {
 	return n.toLocaleString("en-US");
@@ -156,11 +142,11 @@ function printCostSummary(sessions: SessionMetrics[]): void {
 	const w = process.stdout.write.bind(process.stdout);
 	const separator = "\u2500".repeat(70);
 
-	w(`${color.bold}Cost Summary${color.reset}\n`);
+	w(`${color.bold("Cost Summary")}\n`);
 	w(`${"=".repeat(70)}\n`);
 
 	if (sessions.length === 0) {
-		w(`${color.dim}No session data found.${color.reset}\n`);
+		w(`${color.dim("No session data found.")}\n`);
 		return;
 	}
 
@@ -169,7 +155,7 @@ function printCostSummary(sessions: SessionMetrics[]): void {
 			`${padLeft("Input", 10)}${padLeft("Output", 10)}` +
 			`${padLeft("Cache", 10)}${padLeft("Cost", 10)}\n`,
 	);
-	w(`${color.dim}${separator}${color.reset}\n`);
+	w(`${color.dim(separator)}\n`);
 
 	for (const s of sessions) {
 		const cacheTotal = s.cacheReadTokens + s.cacheCreationTokens;
@@ -183,13 +169,17 @@ function printCostSummary(sessions: SessionMetrics[]): void {
 	}
 
 	const totals = computeTotals(sessions);
-	w(`${color.dim}${separator}${color.reset}\n`);
+	w(`${color.dim(separator)}\n`);
 	w(
-		`${color.green}${color.bold}${padRight("Total", 31)}` +
-			`${padLeft(formatNumber(totals.inputTokens), 10)}` +
-			`${padLeft(formatNumber(totals.outputTokens), 10)}` +
-			`${padLeft(formatNumber(totals.cacheTokens), 10)}` +
-			`${padLeft(formatCost(totals.costUsd), 10)}${color.reset}\n`,
+		`${color.green(
+			color.bold(
+				padRight("Total", 31) +
+					padLeft(formatNumber(totals.inputTokens), 10) +
+					padLeft(formatNumber(totals.outputTokens), 10) +
+					padLeft(formatNumber(totals.cacheTokens), 10) +
+					padLeft(formatCost(totals.costUsd), 10),
+			),
+		)}\n`,
 	);
 }
 
@@ -198,11 +188,11 @@ function printByCapability(sessions: SessionMetrics[]): void {
 	const w = process.stdout.write.bind(process.stdout);
 	const separator = "\u2500".repeat(70);
 
-	w(`${color.bold}Cost by Capability${color.reset}\n`);
+	w(`${color.bold("Cost by Capability")}\n`);
 	w(`${"=".repeat(70)}\n`);
 
 	if (sessions.length === 0) {
-		w(`${color.dim}No session data found.${color.reset}\n`);
+		w(`${color.dim("No session data found.")}\n`);
 		return;
 	}
 
@@ -211,7 +201,7 @@ function printByCapability(sessions: SessionMetrics[]): void {
 			`${padLeft("Input", 10)}${padLeft("Output", 10)}` +
 			`${padLeft("Cache", 10)}${padLeft("Cost", 10)}\n`,
 	);
-	w(`${color.dim}${separator}${color.reset}\n`);
+	w(`${color.dim(separator)}\n`);
 
 	const groups = groupByCapability(sessions);
 
@@ -227,47 +217,39 @@ function printByCapability(sessions: SessionMetrics[]): void {
 	}
 
 	const totals = computeTotals(sessions);
-	w(`${color.dim}${separator}${color.reset}\n`);
+	w(`${color.dim(separator)}\n`);
 	w(
-		`${color.green}${color.bold}${padRight("Total", 14)}` +
-			`${padLeft(formatNumber(sessions.length), 10)}` +
-			`${padLeft(formatNumber(totals.inputTokens), 10)}` +
-			`${padLeft(formatNumber(totals.outputTokens), 10)}` +
-			`${padLeft(formatNumber(totals.cacheTokens), 10)}` +
-			`${padLeft(formatCost(totals.costUsd), 10)}${color.reset}\n`,
+		`${color.green(
+			color.bold(
+				padRight("Total", 14) +
+					padLeft(formatNumber(sessions.length), 10) +
+					padLeft(formatNumber(totals.inputTokens), 10) +
+					padLeft(formatNumber(totals.outputTokens), 10) +
+					padLeft(formatNumber(totals.cacheTokens), 10) +
+					padLeft(formatCost(totals.costUsd), 10),
+			),
+		)}\n`,
 	);
 }
 
-const COSTS_HELP = `overstory costs -- Token/cost analysis and breakdown
-
-Usage: overstory costs [options]
-
-Options:
-  --live                 Show real-time token usage for active agents
-  --self                 Show cost for the current orchestrator session
-  --agent <name>         Filter by agent name
-  --run <id>             Filter by run ID
-  --by-capability        Group results by capability with subtotals
-  --last <n>             Number of recent sessions (default: 20)
-  --json                 Output as JSON
-  --help, -h             Show this help`;
-
-/**
- * Entry point for `overstory costs [--agent <name>] [--run <id>] [--by-capability] [--last <n>] [--self] [--json]`.
- */
-export async function costsCommand(args: string[]): Promise<void> {
-	if (args.includes("--help") || args.includes("-h")) {
-		process.stdout.write(`${COSTS_HELP}\n`);
-		return;
-	}
+interface CostsOpts {
+	live?: boolean;
+	self?: boolean;
+	byCapability?: boolean;
+	agent?: string;
+	run?: string;
+	last?: string;
+	json?: boolean;
+}
 
-	const json = hasFlag(args, "--json");
-	const live = hasFlag(args, "--live");
-	const self = hasFlag(args, "--self");
-	const byCapability = hasFlag(args, "--by-capability");
-	const agentName = getFlag(args, "--agent");
-	const runId = getFlag(args, "--run");
-	const lastStr = getFlag(args, "--last");
+async function executeCosts(opts: CostsOpts): Promise<void> {
+	const json = opts.json ?? false;
+	const live = opts.live ?? false;
+	const self = opts.self ?? false;
+	const byCapability = opts.byCapability ?? false;
+	const agentName = opts.agent;
+	const runId = opts.run;
+	const lastStr = opts.last;
 
 	if (lastStr !== undefined) {
 		const parsed = Number.parseInt(lastStr, 10);
@@ -323,17 +305,17 @@ export async function costsCommand(args: string[]): Promise<void> {
 			const w = process.stdout.write.bind(process.stdout);
 			const separator = "\u2500".repeat(70);
 
-			w(`${color.bold}Orchestrator Session Cost${color.reset}\n`);
+			w(`${color.bold("Orchestrator Session Cost")}\n`);
 			w(`${"=".repeat(70)}\n`);
 			w(`${padRight("Model:", 12)}${usage.modelUsed ?? "unknown"}\n`);
 			w(`${padRight("Transcript:", 12)}${transcriptPath}\n`);
-			w(`${color.dim}${separator}${color.reset}\n`);
+			w(`${color.dim(separator)}\n`);
 			w(`${padRight("Input tokens:", 22)}${padLeft(formatNumber(usage.inputTokens), 12)}\n`);
 			w(`${padRight("Output tokens:", 22)}${padLeft(formatNumber(usage.outputTokens), 12)}\n`);
 			w(`${padRight("Cache tokens:", 22)}${padLeft(formatNumber(cacheTotal), 12)}\n`);
-			w(`${color.dim}${separator}${color.reset}\n`);
+			w(`${color.dim(separator)}\n`);
 			w(
-				`${color.green}${color.bold}${padRight("Estimated cost:", 22)}${padLeft(formatCost(cost), 12)}${color.reset}\n`,
+				`${color.green(color.bold(padRight("Estimated cost:", 22) + padLeft(formatCost(cost), 12)))}\n`,
 			);
 		}
 		return;
@@ -463,14 +445,14 @@ export async function costsCommand(args: string[]): Promise<void> {
 				const w = process.stdout.write.bind(process.stdout);
 				const separator = "\u2500".repeat(70);
 
-				w(`${color.bold}Live Token Usage (${agentData.length} active agents)${color.reset}\n`);
+				w(`${color.bold(`Live Token Usage (${agentData.length} active agents)`)}\n`);
 				w(`${"=".repeat(70)}\n`);
 				w(
 					`${padRight("Agent", 19)}${padRight("Capability", 12)}` +
 						`${padLeft("Input", 10)}${padLeft("Output", 10)}` +
 						`${padLeft("Cache", 10)}${padLeft("Cost", 10)}\n`,
 				);
-				w(`${color.dim}${separator}${color.reset}\n`);
+				w(`${color.dim(separator)}\n`);
 
 				for (const agent of agentData) {
 					const cacheTotal = agent.cacheReadTokens + agent.cacheCreationTokens;
@@ -483,13 +465,17 @@ export async function costsCommand(args: string[]): Promise<void> {
 					);
 				}
 
-				w(`${color.dim}${separator}${color.reset}\n`);
+				w(`${color.dim(separator)}\n`);
 				w(
-					`${color.green}${color.bold}${padRight("Total", 31)}` +
-						`${padLeft(formatNumber(totalInput), 10)}` +
-						`${padLeft(formatNumber(totalOutput), 10)}` +
-						`${padLeft(formatNumber(totalCacheTokens), 10)}` +
-						`${padLeft(formatCost(totalCost), 10)}${color.reset}\n\n`,
+					`${color.green(
+						color.bold(
+							padRight("Total", 31) +
+								padLeft(formatNumber(totalInput), 10) +
+								padLeft(formatNumber(totalOutput), 10) +
+								padLeft(formatNumber(totalCacheTokens), 10) +
+								padLeft(formatCost(totalCost), 10),
+						),
+					)}\n\n`,
 				);
 
 				// Format elapsed time
@@ -562,3 +548,38 @@ export async function costsCommand(args: string[]): Promise<void> {
 		metricsStore.close();
 	}
 }
+
+export function createCostsCommand(): Command {
+	return new Command("costs")
+		.description("Token/cost analysis and breakdown")
+		.option("--live", "Show real-time token usage for active agents")
+		.option("--self", "Show cost for the current orchestrator session")
+		.option("--agent <name>", "Filter by agent name")
+		.option("--run <id>", "Filter by run ID")
+		.option("--by-capability", "Group results by capability with subtotals")
+		.option("--last <n>", "Number of recent sessions (default: 20)")
+		.option("--json", "Output as JSON")
+		.action(async (opts: CostsOpts) => {
+			await executeCosts(opts);
+		});
+}
+
+export async function costsCommand(args: string[]): Promise<void> {
+	const cmd = createCostsCommand();
+	cmd.exitOverride();
+	try {
+		await cmd.parseAsync(args, { from: "user" });
+	} catch (err: unknown) {
+		if (err && typeof err === "object" && "code" in err) {
+			const code = (err as { code: string }).code;
+			if (code === "commander.helpDisplayed" || code === "commander.version") {
+				return;
+			}
+			if (code.startsWith("commander.")) {
+				const message = err instanceof Error ? err.message : String(err);
+				throw new ValidationError(message, { field: "args" });
+			}
+		}
+		throw err;
+	}
+}

package/src/commands/dashboard.test.ts

@@ -51,7 +51,7 @@ describe("dashboardCommand", () => {
 		await dashboardCommand(["--help"]);
 		const out = output();
 
-		expect(out).toContain("overstory dashboard");
+		expect(out).toContain("dashboard");
 		expect(out).toContain("--interval");
 		expect(out).toContain("Ctrl+C");
 	});
@@ -60,7 +60,7 @@ describe("dashboardCommand", () => {
 		await dashboardCommand(["-h"]);
 		const out = output();
 
-		expect(out).toContain("overstory dashboard");
+		expect(out).toContain("dashboard");
 		expect(out).toContain("--interval");
 		expect(out).toContain("Ctrl+C");
 	});