@os-eco/overstory-cli 0.6.8 → 0.6.9

package/README.md

@@ -105,6 +105,8 @@ ov agents discover               Discover agents by capability/state/parent
 
 ov init                          Initialize .overstory/ in current project
                                         (deploys agent definitions automatically)
+  --yes, -y                              Skip interactive prompts
+  --name <name>                          Set project name (default: auto-detect)
 
 ov coordinator start             Start persistent coordinator agent
   --attach / --no-attach                 TTY-aware tmux attach (default: auto)
@@ -273,13 +275,13 @@ Global Flags:
 - **Dependencies**: Minimal runtime — `chalk` (color output), `commander` (CLI framework), core I/O via Bun built-in APIs
 - **Database**: SQLite via `bun:sqlite` (WAL mode for concurrent access)
 - **Linting**: Biome (formatter + linter)
-- **Testing**: `bun test` (2167 tests across 77 files, colocated with source)
+- **Testing**: `bun test` (2186 tests across 77 files, colocated with source)
 - **External CLIs**: `bd` (beads) or `sd` (seeds), `mulch`, `git`, `tmux` — invoked as subprocesses
 
 ## Development
 
 ```bash
-# Run tests (2167 tests across 77 files)
+# Run tests (2186 tests across 77 files)
 bun test
 
 # Run a single test

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@os-eco/overstory-cli",
-	"version": "0.6.8",
+	"version": "0.6.9",
 	"description": "Multi-agent orchestration for Claude Code — spawn worker agents in git worktrees via tmux, coordinate through SQLite mail, merge with tiered conflict resolution",
 	"author": "Jaymin West",
 	"license": "MIT",

package/src/agents/hooks-deployer.test.ts

@@ -14,6 +14,7 @@ import {
 	getDangerGuards,
 	getPathBoundaryGuards,
 	isOverstoryHookEntry,
+	PATH_PREFIX,
 } from "./hooks-deployer.ts";
 
 describe("deployHooks", () => {
@@ -2115,6 +2116,185 @@ describe("bash path boundary integration", () => {
 	});
 });
 
+describe("PATH_PREFIX", () => {
+	test("PATH_PREFIX is exported and is a non-empty string", () => {
+		expect(typeof PATH_PREFIX).toBe("string");
+		expect(PATH_PREFIX.length).toBeGreaterThan(0);
+	});
+
+	test("PATH_PREFIX contains ~/.bun/bin for bun-installed CLIs", () => {
+		expect(PATH_PREFIX).toContain(".bun/bin");
+	});
+
+	test("PATH_PREFIX extends PATH (not replaces it)", () => {
+		// Must preserve original PATH via :$PATH
+		expect(PATH_PREFIX).toContain(":$PATH");
+	});
+
+	test("PATH_PREFIX sets PATH via export", () => {
+		expect(PATH_PREFIX).toMatch(/^export PATH=/);
+	});
+});
+
+describe("PATH prefix in deployed hooks", () => {
+	let tempDir: string;
+
+	beforeEach(async () => {
+		tempDir = await mkdtemp(join(tmpdir(), "overstory-path-prefix-test-"));
+	});
+
+	afterEach(async () => {
+		await rm(tempDir, { recursive: true, force: true });
+	});
+
+	test("SessionStart hook commands include PATH prefix", async () => {
+		const worktreePath = join(tempDir, "path-ss-wt");
+		await deployHooks(worktreePath, "path-agent");
+
+		const content = await Bun.file(join(worktreePath, ".claude", "settings.local.json")).text();
+		const parsed = JSON.parse(content);
+		for (const entry of parsed.hooks.SessionStart) {
+			for (const hook of entry.hooks) {
+				expect(hook.command).toContain("export PATH=");
+				expect(hook.command).toContain(".bun/bin");
+			}
+		}
+	});
+
+	test("UserPromptSubmit hook commands include PATH prefix", async () => {
+		const worktreePath = join(tempDir, "path-ups-wt");
+		await deployHooks(worktreePath, "path-agent");
+
+		const content = await Bun.file(join(worktreePath, ".claude", "settings.local.json")).text();
+		const parsed = JSON.parse(content);
+		for (const entry of parsed.hooks.UserPromptSubmit) {
+			for (const hook of entry.hooks) {
+				expect(hook.command).toContain("export PATH=");
+			}
+		}
+	});
+
+	test("PostToolUse hook commands include PATH prefix", async () => {
+		const worktreePath = join(tempDir, "path-ptu-wt");
+		await deployHooks(worktreePath, "path-agent");
+
+		const content = await Bun.file(join(worktreePath, ".claude", "settings.local.json")).text();
+		const parsed = JSON.parse(content);
+		for (const entry of parsed.hooks.PostToolUse) {
+			for (const hook of entry.hooks) {
+				expect(hook.command).toContain("export PATH=");
+			}
+		}
+	});
+
+	test("Stop hook commands include PATH prefix", async () => {
+		const worktreePath = join(tempDir, "path-stop-wt");
+		await deployHooks(worktreePath, "path-agent");
+
+		const content = await Bun.file(join(worktreePath, ".claude", "settings.local.json")).text();
+		const parsed = JSON.parse(content);
+		for (const entry of parsed.hooks.Stop) {
+			for (const hook of entry.hooks) {
+				expect(hook.command).toContain("export PATH=");
+				expect(hook.command).toContain(".bun/bin");
+			}
+		}
+	});
+
+	test("PreCompact hook commands include PATH prefix", async () => {
+		const worktreePath = join(tempDir, "path-pc-wt");
+		await deployHooks(worktreePath, "path-agent");
+
+		const content = await Bun.file(join(worktreePath, ".claude", "settings.local.json")).text();
+		const parsed = JSON.parse(content);
+		for (const entry of parsed.hooks.PreCompact) {
+			for (const hook of entry.hooks) {
+				expect(hook.command).toContain("export PATH=");
+			}
+		}
+	});
+
+	test("PATH prefix appears before CLI command in SessionStart", async () => {
+		const worktreePath = join(tempDir, "path-order-wt");
+		await deployHooks(worktreePath, "path-order-agent");
+
+		const content = await Bun.file(join(worktreePath, ".claude", "settings.local.json")).text();
+		const parsed = JSON.parse(content);
+		const cmd = parsed.hooks.SessionStart[0].hooks[0].command as string;
+		// PATH export must come before the CLI invocation
+		const pathIdx = cmd.indexOf("export PATH=");
+		const ovIdx = cmd.indexOf("ov prime");
+		expect(pathIdx).toBeGreaterThanOrEqual(0);
+		expect(ovIdx).toBeGreaterThan(pathIdx);
+	});
+
+	test("PATH prefix appears before ml learn in Stop hook", async () => {
+		const worktreePath = join(tempDir, "path-ml-wt");
+		await deployHooks(worktreePath, "path-ml-agent");
+
+		const content = await Bun.file(join(worktreePath, ".claude", "settings.local.json")).text();
+		const parsed = JSON.parse(content);
+		const stopHooks = parsed.hooks.Stop[0].hooks;
+		// Second Stop hook is "ml learn"
+		const mlCmd = stopHooks[1].command as string;
+		const pathIdx = mlCmd.indexOf("export PATH=");
+		const mlIdx = mlCmd.indexOf("ml learn");
+		expect(pathIdx).toBeGreaterThanOrEqual(0);
+		expect(mlIdx).toBeGreaterThan(pathIdx);
+	});
+
+	test("generated guard commands do NOT have PATH prefix (they use only built-ins)", async () => {
+		const worktreePath = join(tempDir, "path-guards-wt");
+		await deployHooks(worktreePath, "path-guards-agent", "builder");
+
+		const content = await Bun.file(join(worktreePath, ".claude", "settings.local.json")).text();
+		const parsed = JSON.parse(content);
+		const preToolUse = parsed.hooks.PreToolUse;
+
+		// Path boundary guards (Write/Edit/NotebookEdit) are generated — no PATH prefix
+		const writeGuard = preToolUse.find(
+			(h: { matcher: string; hooks: Array<{ command: string }> }) =>
+				h.matcher === "Write" && h.hooks[0]?.command?.includes("OVERSTORY_WORKTREE_PATH"),
+		);
+		expect(writeGuard).toBeDefined();
+		expect(writeGuard.hooks[0].command).not.toContain("export PATH=");
+
+		// Danger guard (generated) — no PATH prefix
+		const dangerGuard = preToolUse.find(
+			(h: { matcher: string; hooks: Array<{ command: string }> }) =>
+				h.matcher === "Bash" && h.hooks[0]?.command?.includes("git reset --hard"),
+		);
+		expect(dangerGuard).toBeDefined();
+		expect(dangerGuard.hooks[0].command).not.toContain("export PATH=");
+	});
+
+	test("re-deployment is idempotent: PATH prefix not duplicated", async () => {
+		const worktreePath = join(tempDir, "path-idem-wt");
+
+		await deployHooks(worktreePath, "path-idem-agent");
+		await deployHooks(worktreePath, "path-idem-agent");
+
+		const content = await Bun.file(join(worktreePath, ".claude", "settings.local.json")).text();
+		const parsed = JSON.parse(content);
+		const cmd = parsed.hooks.SessionStart[0].hooks[0].command as string;
+
+		// PATH prefix should appear exactly once, not doubled
+		const occurrences = cmd.split("export PATH=").length - 1;
+		expect(occurrences).toBe(1);
+	});
+
+	test("PATH prefix uses $HOME expansion (not hardcoded path)", async () => {
+		const worktreePath = join(tempDir, "path-home-wt");
+		await deployHooks(worktreePath, "home-agent");
+
+		const content = await Bun.file(join(worktreePath, ".claude", "settings.local.json")).text();
+		const parsed = JSON.parse(content);
+		const cmd = parsed.hooks.SessionStart[0].hooks[0].command as string;
+		// Should use $HOME not a hardcoded path like /Users/...
+		expect(cmd).toContain("$HOME");
+	});
+});
+
 describe("escapeForSingleQuotedShell", () => {
 	test("no single quotes: string passes through unchanged", () => {
 		expect(escapeForSingleQuotedShell("hello world")).toBe("hello world");

package/src/agents/hooks-deployer.ts

@@ -149,6 +149,22 @@ function getTemplatePath(): string {
  */
 const ENV_GUARD = '[ -z "$OVERSTORY_AGENT_NAME" ] && exit 0;';
 
+/**
+ * PATH setup prefix for hook commands.
+ *
+ * Claude Code executes hook commands via /bin/sh with a minimal PATH
+ * (/usr/bin:/bin:/usr/sbin:/sbin). Bun-installed CLIs — ov, ml, sd, cn, bd —
+ * live in ~/.bun/bin which is absent from that PATH, causing hooks like
+ * `ov prime` (SessionStart) and `ml learn` (Stop) to fail with
+ * "command not found".
+ *
+ * Prepend this to any hook command that invokes one of those CLIs so they
+ * resolve correctly regardless of how Claude Code was launched.
+ *
+ * Exported so tests can verify the exact prefix value.
+ */
+export const PATH_PREFIX = 'export PATH="$HOME/.bun/bin:/usr/local/bin:/opt/homebrew/bin:$PATH";';
+
 /**
  * Build a PreToolUse guard script that validates file paths are within
  * the agent's worktree boundary.
@@ -571,8 +587,23 @@ export async function deployHooks(
 		content = content.replace("{{AGENT_NAME}}", agentName);
 	}
 
-	// Parse the base config and merge guards into PreToolUse
+	// Parse the base config from the template
 	const config = JSON.parse(content) as { hooks: Record<string, HookEntry[]> };
+
+	// Extend PATH in all template hook commands.
+	// Claude Code invokes hooks with PATH=/usr/bin:/bin:/usr/sbin:/sbin — ~/.bun/bin
+	// (where ov, ml, sd, etc. live) is not included. Prepend PATH_PREFIX so CLIs resolve.
+	for (const entries of Object.values(config.hooks)) {
+		for (const entry of entries) {
+			for (const hook of entry.hooks) {
+				hook.command = `${PATH_PREFIX} ${hook.command}`;
+			}
+		}
+	}
+
+	// Merge capability-specific PreToolUse guards into the config.
+	// Guards are generated scripts using only shell built-ins (grep, sed, echo, exit)
+	// and do not require PATH extension.
 	const pathGuards = getPathBoundaryGuards();
 	const dangerGuards = getDangerGuards(agentName);
 	const capabilityGuards = getCapabilityGuards(capability);

package/src/commands/agents.ts

@@ -8,7 +8,8 @@ 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";
+import { jsonOutput } from "../json.ts";
+import { accent, color } from "../logging/color.ts";
 import { openSessionStore } from "../sessions/compat.ts";
 import { type AgentSession, SUPPORTED_CAPABILITIES } from "../types.ts";
 
@@ -166,10 +167,12 @@ function printAgents(agents: DiscoveredAgent[]): void {
 
 	for (const agent of agents) {
 		const icon = getStateIcon(agent.state);
-		w(`  ${icon} ${agent.agentName} [${agent.capability}]\n`);
-		w(`    State: ${agent.state} | Task: ${agent.taskId}\n`);
-		w(`    Branch: ${agent.branchName}\n`);
-		w(`    Parent: ${agent.parentAgent ?? "none"} | Depth: ${agent.depth}\n`);
+		w(`  ${icon} ${accent(agent.agentName)} [${agent.capability}]\n`);
+		w(`    State: ${agent.state} | Task: ${accent(agent.taskId)}\n`);
+		w(`    Branch: ${accent(agent.branchName)}\n`);
+		w(
+			`    Parent: ${agent.parentAgent ? accent(agent.parentAgent) : "none"} | Depth: ${agent.depth}\n`,
+		);
 
 		if (agent.fileScope.length === 0) {
 			w("    Files: (unrestricted)\n");
@@ -220,7 +223,7 @@ export function createAgentsCommand(): Command {
 			});
 
 			if (opts.json) {
-				process.stdout.write(`${JSON.stringify(agents, null, "\t")}\n`);
+				jsonOutput("agents discover", { agents });
 			} else {
 				printAgents(agents);
 			}

package/src/commands/clean.ts

@@ -25,6 +25,7 @@ import { join } from "node:path";
 import { loadConfig } from "../config.ts";
 import { ValidationError } from "../errors.ts";
 import { createEventStore } from "../events/store.ts";
+import { jsonOutput } from "../json.ts";
 import { printHint, printSuccess } from "../logging/color.ts";
 import { createMulchClient } from "../mulch/client.ts";
 import { openSessionStore } from "../sessions/compat.ts";
@@ -518,7 +519,7 @@ export async function cleanCommand(opts: CleanOptions): Promise<void> {
 
 	// Output
 	if (json) {
-		process.stdout.write(`${JSON.stringify(result, null, "\t")}\n`);
+		jsonOutput("clean", { ...result });
 		return;
 	}
 

package/src/commands/completions.ts

@@ -5,6 +5,7 @@
  */
 
 import { Command } from "commander";
+import { printError } from "../logging/color.ts";
 
 interface FlagDef {
 	name: string;
@@ -872,8 +873,7 @@ export function completionsCommand(args: string[]): void {
 	const shell = args[0];
 
 	if (!shell) {
-		process.stderr.write("Error: missing shell argument\n");
-		process.stderr.write("Usage: ov --completions <bash|zsh|fish>\n");
+		printError("missing shell argument", "Usage: ov --completions <bash|zsh|fish>");
 		process.exit(1);
 	}
 
@@ -889,8 +889,7 @@ export function completionsCommand(args: string[]): void {
 			script = generateFish();
 			break;
 		default:
-			process.stderr.write(`Error: unknown shell '${shell}'\n`);
-			process.stderr.write("Supported shells: bash, zsh, fish\n");
+			printError(`unknown shell '${shell}'`, "Supported shells: bash, zsh, fish");
 			process.exit(1);
 	}
 

package/src/commands/coordinator.test.ts

@@ -592,6 +592,8 @@ describe("startCoordinator", () => {
 		}
 
 		const parsed = JSON.parse(output) as Record<string, unknown>;
+		expect(parsed.success).toBe(true);
+		expect(parsed.command).toBe("coordinator start");
 		expect(parsed.agentName).toBe("coordinator");
 		expect(parsed.capability).toBe("coordinator");
 		expect(parsed.tmuxSession).toBe("overstory-test-project-coordinator");
@@ -761,6 +763,8 @@ describe("stopCoordinator", () => {
 
 		const output = await captureStdout(() => coordinatorCommand(["stop", "--json"], deps));
 		const parsed = JSON.parse(output) as Record<string, unknown>;
+		expect(parsed.success).toBe(true);
+		expect(parsed.command).toBe("coordinator stop");
 		expect(parsed.stopped).toBe(true);
 		expect(parsed.sessionId).toBe(session.id);
 	});
@@ -930,6 +934,8 @@ describe("statusCoordinator", () => {
 		const { deps } = makeDeps();
 		const output = await captureStdout(() => coordinatorCommand(["status", "--json"], deps));
 		const parsed = JSON.parse(output) as Record<string, unknown>;
+		expect(parsed.success).toBe(true);
+		expect(parsed.command).toBe("coordinator status");
 		expect(parsed.running).toBe(false);
 	});
 
@@ -951,6 +957,8 @@ describe("statusCoordinator", () => {
 
 		const output = await captureStdout(() => coordinatorCommand(["status", "--json"], deps));
 		const parsed = JSON.parse(output) as Record<string, unknown>;
+		expect(parsed.success).toBe(true);
+		expect(parsed.command).toBe("coordinator status");
 		expect(parsed.running).toBe(true);
 		expect(parsed.sessionId).toBe(session.id);
 		expect(parsed.state).toBe("working");

package/src/commands/coordinator.ts

@@ -20,6 +20,7 @@ import { createIdentity, loadIdentity } from "../agents/identity.ts";
 import { createManifestLoader, resolveModel } from "../agents/manifest.ts";
 import { loadConfig } from "../config.ts";
 import { AgentError, ValidationError } from "../errors.ts";
+import { jsonOutput } from "../json.ts";
 import { printHint, printSuccess, printWarning } from "../logging/color.ts";
 import { openSessionStore } from "../sessions/compat.ts";
 import { createRunStore } from "../sessions/store.ts";
@@ -462,7 +463,7 @@ async function startCoordinator(
 		};
 
 		if (json) {
-			process.stdout.write(`${JSON.stringify(output)}\n`);
+			jsonOutput("coordinator start", output);
 		} else {
 			printSuccess("Coordinator started");
 			process.stdout.write(`  Tmux:    ${tmuxSession}\n`);
@@ -564,9 +565,13 @@ async function stopCoordinator(opts: { json: boolean }, deps: CoordinatorDeps =
 		}
 
 		if (json) {
-			process.stdout.write(
-				`${JSON.stringify({ stopped: true, sessionId: session.id, watchdogStopped, monitorStopped, runCompleted })}\n`,
-			);
+			jsonOutput("coordinator stop", {
+				stopped: true,
+				sessionId: session.id,
+				watchdogStopped,
+				monitorStopped,
+				runCompleted,
+			});
 		} else {
 			printSuccess("Coordinator stopped", session.id);
 			if (watchdogStopped) {
@@ -629,9 +634,7 @@ async function statusCoordinator(
 			session.state === "zombie"
 		) {
 			if (json) {
-				process.stdout.write(
-					`${JSON.stringify({ running: false, watchdogRunning, monitorRunning })}\n`,
-				);
+				jsonOutput("coordinator status", { running: false, watchdogRunning, monitorRunning });
 			} else {
 				printHint("Coordinator is not running");
 				if (watchdogRunning) {
@@ -668,7 +671,7 @@ async function statusCoordinator(
 		};
 
 		if (json) {
-			process.stdout.write(`${JSON.stringify(status)}\n`);
+			jsonOutput("coordinator status", status);
 		} else {
 			const stateLabel = alive ? "running" : session.state;
 			process.stdout.write(`Coordinator: ${stateLabel}\n`);

package/src/commands/costs.test.ts

@@ -116,7 +116,14 @@ describe("costsCommand", () => {
 			await costsCommand(["--json"]);
 			const out = output();
 
-			expect(out).toBe("[]\n");
+			const parsed = JSON.parse(out.trim()) as {
+				success: boolean;
+				command: string;
+				sessions: unknown[];
+			};
+			expect(parsed.success).toBe(true);
+			expect(parsed.command).toBe("costs");
+			expect(parsed.sessions).toEqual([]);
 		});
 	});
 
@@ -149,9 +156,10 @@ describe("costsCommand", () => {
 			await costsCommand(["--json"]);
 			const out = output();
 
-			const parsed = JSON.parse(out.trim()) as unknown[];
-			expect(Array.isArray(parsed)).toBe(true);
-			expect(parsed).toHaveLength(2);
+			const parsed = JSON.parse(out.trim()) as { success: boolean; sessions: unknown[] };
+			expect(parsed.success).toBe(true);
+			expect(Array.isArray(parsed.sessions)).toBe(true);
+			expect(parsed.sessions).toHaveLength(2);
 		});
 
 		test("JSON output includes expected token fields", async () => {
@@ -173,9 +181,12 @@ describe("costsCommand", () => {
 			await costsCommand(["--json"]);
 			const out = output();
 
-			const parsed = JSON.parse(out.trim()) as Record<string, unknown>[];
-			expect(parsed).toHaveLength(1);
-			const session = parsed[0];
+			const parsed = JSON.parse(out.trim()) as {
+				success: boolean;
+				sessions: Record<string, unknown>[];
+			};
+			expect(parsed.sessions).toHaveLength(1);
+			const session = parsed.sessions[0];
 			expect(session).toBeDefined();
 			expect(session?.inputTokens).toBe(100);
 			expect(session?.outputTokens).toBe(50);
@@ -193,8 +204,8 @@ describe("costsCommand", () => {
 			await costsCommand(["--json", "--agent", "nonexistent"]);
 			const out = output();
 
-			const parsed = JSON.parse(out.trim()) as unknown[];
-			expect(parsed).toEqual([]);
+			const parsed = JSON.parse(out.trim()) as { success: boolean; sessions: unknown[] };
+			expect(parsed.sessions).toEqual([]);
 		});
 
 		test("JSON --by-capability outputs grouped object", async () => {
@@ -221,12 +232,12 @@ describe("costsCommand", () => {
 			await costsCommand(["--json", "--by-capability"]);
 			const out = output();
 
-			const parsed = JSON.parse(out.trim()) as Record<string, unknown>;
-			expect(parsed).toBeDefined();
-			expect(parsed.builder).toBeDefined();
-			expect(parsed.scout).toBeDefined();
+			const parsed = JSON.parse(out.trim()) as { grouped: Record<string, unknown> };
+			expect(parsed.grouped).toBeDefined();
+			expect(parsed.grouped.builder).toBeDefined();
+			expect(parsed.grouped.scout).toBeDefined();
 
-			const builderGroup = parsed.builder as Record<string, unknown>;
+			const builderGroup = parsed.grouped.builder as Record<string, unknown>;
 			expect(builderGroup.sessions).toBeDefined();
 			expect(builderGroup.totals).toBeDefined();
 		});
@@ -415,9 +426,9 @@ describe("costsCommand", () => {
 			await costsCommand(["--json", "--agent", "builder-1"]);
 			const out = output();
 
-			const parsed = JSON.parse(out.trim()) as Record<string, unknown>[];
-			expect(parsed).toHaveLength(1);
-			expect(parsed[0]?.agentName).toBe("builder-1");
+			const parsed = JSON.parse(out.trim()) as { sessions: Record<string, unknown>[] };
+			expect(parsed.sessions).toHaveLength(1);
+			expect(parsed.sessions[0]?.agentName).toBe("builder-1");
 		});
 
 		test("returns empty for non-existent agent", async () => {
@@ -429,8 +440,8 @@ describe("costsCommand", () => {
 			await costsCommand(["--json", "--agent", "nonexistent"]);
 			const out = output();
 
-			const parsed = JSON.parse(out.trim()) as unknown[];
-			expect(parsed).toEqual([]);
+			const parsed = JSON.parse(out.trim()) as { sessions: unknown[] };
+			expect(parsed.sessions).toEqual([]);
 		});
 	});
 
@@ -456,9 +467,9 @@ describe("costsCommand", () => {
 			await costsCommand(["--json", "--run", "run-2026-01-01"]);
 			const out = output();
 
-			const parsed = JSON.parse(out.trim()) as Record<string, unknown>[];
-			expect(parsed).toHaveLength(1);
-			expect(parsed[0]?.agentName).toBe("builder-1");
+			const parsed = JSON.parse(out.trim()) as { sessions: Record<string, unknown>[] };
+			expect(parsed.sessions).toHaveLength(1);
+			expect(parsed.sessions[0]?.agentName).toBe("builder-1");
 		});
 
 		test("returns empty when no sessions match run ID", async () => {
@@ -472,8 +483,8 @@ describe("costsCommand", () => {
 			await costsCommand(["--json", "--run", "run-nonexistent"]);
 			const out = output();
 
-			const parsed = JSON.parse(out.trim()) as unknown[];
-			expect(parsed).toEqual([]);
+			const parsed = JSON.parse(out.trim()) as { sessions: unknown[] };
+			expect(parsed.sessions).toEqual([]);
 		});
 	});
 
@@ -557,12 +568,11 @@ describe("costsCommand", () => {
 			await costsCommand(["--json", "--by-capability"]);
 			const out = output();
 
-			const parsed = JSON.parse(out.trim()) as Record<
-				string,
-				{ sessions: unknown[]; totals: Record<string, unknown> }
-			>;
-			expect(parsed.builder?.sessions).toHaveLength(3);
-			expect(parsed.scout?.sessions).toHaveLength(1);
+			const parsed = JSON.parse(out.trim()) as {
+				grouped: Record<string, { sessions: unknown[]; totals: Record<string, unknown> }>;
+			};
+			expect(parsed.grouped.builder?.sessions).toHaveLength(3);
+			expect(parsed.grouped.scout?.sessions).toHaveLength(1);
 		});
 
 		test("empty data shows no session data message", async () => {
@@ -591,8 +601,8 @@ describe("costsCommand", () => {
 			await costsCommand(["--json", "--last", "3"]);
 			const out = output();
 
-			const parsed = JSON.parse(out.trim()) as unknown[];
-			expect(parsed).toHaveLength(3);
+			const parsed = JSON.parse(out.trim()) as { sessions: unknown[] };
+			expect(parsed.sessions).toHaveLength(3);
 		});
 
 		test("default limit is 20", async () => {
@@ -606,8 +616,8 @@ describe("costsCommand", () => {
 			await costsCommand(["--json"]);
 			const out = output();
 
-			const parsed = JSON.parse(out.trim()) as unknown[];
-			expect(parsed).toHaveLength(20);
+			const parsed = JSON.parse(out.trim()) as { sessions: unknown[] };
+			expect(parsed.sessions).toHaveLength(20);
 		});
 	});
 
@@ -705,9 +715,9 @@ describe("costsCommand", () => {
 			await costsCommand(["--json"]);
 			const out = output();
 
-			const parsed = JSON.parse(out.trim()) as SessionMetrics[];
-			const totalInput = parsed.reduce((sum, s) => sum + s.inputTokens, 0);
-			const totalOutput = parsed.reduce((sum, s) => sum + s.outputTokens, 0);
+			const parsed = JSON.parse(out.trim()) as { sessions: SessionMetrics[] };
+			const totalInput = parsed.sessions.reduce((sum, s) => sum + s.inputTokens, 0);
+			const totalOutput = parsed.sessions.reduce((sum, s) => sum + s.outputTokens, 0);
 			expect(totalInput).toBe(300);
 			expect(totalOutput).toBe(150);
 		});
@@ -1106,7 +1116,7 @@ describe("costsCommand", () => {
 			const out = output();
 
 			const parsed = JSON.parse(out.trim()) as Record<string, unknown>;
-			expect(parsed.error).toBe("no_transcript");
+			expect(parsed.error).toBe("No orchestrator transcript found");
 		});
 
 		test("--self in help text", async () => {