@os-eco/overstory-cli 0.9.1 → 0.9.3

package/src/beads/client.ts

@@ -194,9 +194,37 @@ export function createBeadsClient(cwd: string): BeadsClient {
 			if (options?.limit !== undefined) {
 				args.push("--limit", String(options.limit));
 			}
-			const { stdout } = await runBd(args, "list");
-			const raw = parseJsonOutput<RawBeadIssue[]>(stdout, "list");
-			return raw.map(normalizeIssue);
+			try {
+				const { stdout } = await runBd(args, "list");
+				const trimmed = stdout.trim();
+				if (trimmed === "") return [];
+				const parsed: unknown = JSON.parse(trimmed);
+				if (Array.isArray(parsed)) {
+					// Flat format: RawBeadIssue[]
+					return (parsed as RawBeadIssue[]).map(normalizeIssue);
+				}
+				if (typeof parsed === "object" && parsed !== null) {
+					// Tree format: { mol: RawBeadIssue[] } — flatten all groups
+					const tree = parsed as Record<string, unknown>;
+					const issues: BeadIssue[] = [];
+					for (const group of Object.values(tree)) {
+						if (Array.isArray(group)) {
+							for (const item of group) {
+								issues.push(normalizeIssue(item as RawBeadIssue));
+							}
+						}
+					}
+					if (issues.length > 0) return issues;
+				}
+			} catch {
+				// fall through to ready fallback
+			}
+			// Fallback: bd ready --json always returns a flat array
+			const { stdout: readyStdout } = await runBd(["ready", "--json"], "ready (list fallback)");
+			const readyTrimmed = readyStdout.trim();
+			if (readyTrimmed === "") return [];
+			const readyRaw = parseJsonOutput<RawBeadIssue[]>(readyTrimmed, "ready (list fallback)");
+			return readyRaw.map(normalizeIssue);
 		},
 	};
 }

package/src/commands/agents.ts

@@ -223,7 +223,7 @@ export function createAgentsCommand(): Command {
 		.description("Find active agents by capability")
 		.option(
 			"--capability <type>",
-			"Filter by capability (builder, scout, reviewer, lead, merger, coordinator, supervisor)",
+			"Filter by capability (builder, scout, reviewer, lead, merger, orchestrator, coordinator, supervisor)",
 		)
 		.option("--all", "Include completed and zombie agents (default: active only)")
 		.option("--json", "Output as JSON")

package/src/commands/clean.test.ts

@@ -792,3 +792,6 @@ describe("--agent", () => {
 		expect(stdoutOutput).toContain("Agent cleaned");
 	});
 });
+
+// fs utility tests (wipeSqliteDb, resetJsonFile, clearDirectory, deleteFile)
+// moved to src/utils/fs.test.ts

package/src/commands/clean.ts

@@ -20,7 +20,6 @@
  */
 
 import { existsSync } from "node:fs";
-import { readdir, rm, unlink } from "node:fs/promises";
 import { join } from "node:path";
 import { loadConfig } from "../config.ts";
 import { AgentError, ValidationError } from "../errors.ts";
@@ -30,6 +29,7 @@ import { printHint, printSuccess } from "../logging/color.ts";
 import { createMulchClient } from "../mulch/client.ts";
 import { openSessionStore } from "../sessions/compat.ts";
 import type { AgentSession, MulchDoctorResult, MulchPruneResult, MulchStatus } from "../types.ts";
+import { clearDirectory, deleteFile, resetJsonFile, wipeSqliteDb } from "../utils/fs.ts";
 import { listWorktrees, removeWorktree } from "../worktree/manager.ts";
 import {
 	isProcessAlive,
@@ -274,63 +274,6 @@ async function deleteOrphanedBranches(root: string): Promise<number> {
 	return deleted;
 }
 
-/**
- * Delete a SQLite database file and its WAL/SHM companions.
- */
-async function wipeSqliteDb(dbPath: string): Promise<boolean> {
-	const extensions = ["", "-wal", "-shm"];
-	let wiped = false;
-	for (const ext of extensions) {
-		try {
-			await unlink(`${dbPath}${ext}`);
-			if (ext === "") wiped = true;
-		} catch {
-			// File may not exist
-		}
-	}
-	return wiped;
-}
-
-/**
- * Reset a JSON file to an empty array.
- */
-async function resetJsonFile(path: string): Promise<boolean> {
-	const file = Bun.file(path);
-	if (await file.exists()) {
-		await Bun.write(path, "[]\n");
-		return true;
-	}
-	return false;
-}
-
-/**
- * Clear all entries inside a directory but keep the directory itself.
- */
-async function clearDirectory(dirPath: string): Promise<boolean> {
-	try {
-		const entries = await readdir(dirPath);
-		for (const entry of entries) {
-			await rm(join(dirPath, entry), { recursive: true, force: true });
-		}
-		return entries.length > 0;
-	} catch {
-		// Directory may not exist
-		return false;
-	}
-}
-
-/**
- * Delete a single file if it exists.
- */
-async function deleteFile(path: string): Promise<boolean> {
-	try {
-		await unlink(path);
-		return true;
-	} catch {
-		return false;
-	}
-}
-
 /**
  * Check mulch repository health and return diagnostic information.
  *

package/src/commands/completions.test.ts

@@ -2,7 +2,7 @@
  * Tests for shell completion generation.
  */
 
-import { describe, expect, it, mock } from "bun:test";
+import { afterEach, describe, expect, it, mock } from "bun:test";
 import {
 	COMMANDS,
 	completionsCommand,
@@ -11,9 +11,13 @@ import {
 	generateZsh,
 } from "./completions.ts";
 
+afterEach(() => {
+	process.exitCode = undefined;
+});
+
 describe("COMMANDS array", () => {
-	it("should have exactly 33 commands", () => {
-		expect(COMMANDS).toHaveLength(33);
+	it("should have exactly 34 commands", () => {
+		expect(COMMANDS).toHaveLength(34);
 	});
 
 	it("should include all expected command names", () => {
@@ -37,6 +41,7 @@ describe("COMMANDS array", () => {
 		expect(names).toContain("costs");
 		expect(names).toContain("metrics");
 		expect(names).toContain("spec");
+		expect(names).toContain("orchestrator");
 		expect(names).toContain("coordinator");
 		expect(names).toContain("supervisor");
 		expect(names).toContain("hooks");
@@ -62,7 +67,7 @@ describe("generateBash", () => {
 		expect(script).toContain("_init_completion");
 	});
 
-	it("should include all 33 command names", () => {
+	it("should include all 34 command names", () => {
 		const script = generateBash();
 		for (const cmd of COMMANDS) {
 			expect(script).toContain(cmd.name);
@@ -96,7 +101,7 @@ describe("generateZsh", () => {
 		expect(script).toContain("_arguments");
 	});
 
-	it("should include all 33 command names", () => {
+	it("should include all 34 command names", () => {
 		const script = generateZsh();
 		for (const cmd of COMMANDS) {
 			expect(script).toContain(cmd.name);
@@ -126,7 +131,7 @@ describe("generateFish", () => {
 		expect(script).toContain("__fish_use_subcommand");
 	});
 
-	it("should include all 33 command names", () => {
+	it("should include all 34 command names", () => {
 		const script = generateFish();
 		for (const cmd of COMMANDS) {
 			expect(script).toContain(cmd.name);
@@ -148,6 +153,13 @@ describe("generateFish", () => {
 		expect(script).toContain("error");
 		expect(script).toContain("worker_done");
 	});
+
+	it("should include orchestrator command with start/stop/status subcommands", () => {
+		const orchestrator = COMMANDS.find((c) => c.name === "orchestrator");
+		expect(orchestrator).toBeDefined();
+		const subcommands = orchestrator?.subcommands?.map((s) => s.name);
+		expect(subcommands).toEqual(["start", "stop", "status"]);
+	});
 });
 
 describe("completionsCommand", () => {

package/src/commands/completions.ts

@@ -44,7 +44,16 @@ export const COMMANDS: readonly CommandDef[] = [
 						name: "--capability",
 						desc: "Filter by capability",
 						takesValue: true,
-						values: ["builder", "scout", "reviewer", "lead", "merger", "coordinator", "supervisor"],
+						values: [
+							"builder",
+							"scout",
+							"reviewer",
+							"lead",
+							"merger",
+							"orchestrator",
+							"coordinator",
+							"supervisor",
+						],
 					},
 					{ name: "--all", desc: "Include completed and zombie agents" },
 					{ name: "--json", desc: "JSON output" },
@@ -343,6 +352,36 @@ export const COMMANDS: readonly CommandDef[] = [
 			},
 		],
 	},
+	{
+		name: "orchestrator",
+		desc: "Persistent ecosystem orchestrator agent",
+		flags: [
+			{ name: "--json", desc: "JSON output" },
+			{ name: "--help", desc: "Show help" },
+		],
+		subcommands: [
+			{
+				name: "start",
+				desc: "Start orchestrator",
+				flags: [
+					{ name: "--attach", desc: "Attach to tmux session" },
+					{ name: "--no-attach", desc: "Do not attach to tmux session" },
+					{ name: "--watchdog", desc: "Auto-start watchdog daemon" },
+					{ name: "--json", desc: "JSON output" },
+				],
+			},
+			{
+				name: "stop",
+				desc: "Stop orchestrator",
+				flags: [{ name: "--json", desc: "JSON output" }],
+			},
+			{
+				name: "status",
+				desc: "Show orchestrator state",
+				flags: [{ name: "--json", desc: "JSON output" }],
+			},
+		],
+	},
 	{
 		name: "coordinator",
 		desc: "Persistent coordinator agent",

package/src/commands/coordinator.test.ts

@@ -29,6 +29,11 @@ import {
 	createCoordinatorCommand,
 	resolveAttach,
 } from "./coordinator.ts";
+import {
+	buildOrchestratorBeacon,
+	createOrchestratorCommand,
+	orchestratorCommand,
+} from "./orchestrator.ts";
 
 // --- Fake Tmux ---
 
@@ -272,14 +277,26 @@ beforeEach(async () => {
 				canSpawn: true,
 				constraints: [],
 			},
+			orchestrator: {
+				file: "orchestrator.md",
+				model: "opus",
+				tools: ["Read", "Bash"],
+				capabilities: ["orchestrate", "coordinate"],
+				canSpawn: true,
+				constraints: [],
+			},
+		},
+		capabilityIndex: {
+			coordinate: ["coordinator", "orchestrator"],
+			orchestrate: ["orchestrator"],
 		},
-		capabilityIndex: { coordinate: ["coordinator"] },
 	};
 	await Bun.write(
 		join(overstoryDir, "agent-manifest.json"),
 		`${JSON.stringify(manifest, null, "\t")}\n`,
 	);
 	await Bun.write(join(agentDefsDir, "coordinator.md"), "# Coordinator\n");
+	await Bun.write(join(agentDefsDir, "orchestrator.md"), "# Orchestrator\n");
 
 	// Override cwd so coordinator commands find our temp project
 	process.chdir(tempDir);
@@ -1255,14 +1272,16 @@ describe("buildCoordinatorBeacon", () => {
 
 	test("includes hierarchy enforcement instruction", () => {
 		const beacon = buildCoordinatorBeacon();
-		expect(beacon).toContain("ONLY spawn leads");
-		expect(beacon).toContain("NEVER spawn non-lead agents directly");
+		expect(beacon).toContain("Default to leads");
+		expect(beacon).toContain("spawn scout/builder directly");
+		expect(beacon).toContain("NEVER spawn reviewer or merger directly");
 	});
 
 	test("includes delegation instruction", () => {
 		const beacon = buildCoordinatorBeacon();
 		expect(beacon).toContain("DELEGATION");
-		expect(beacon).toContain("spawn a lead who will spawn scouts");
+		expect(beacon).toContain("spawn a lead who will handle scouts/builders/reviewers");
+		expect(beacon).toContain("--dispatch-max-agents 1/2");
 	});
 
 	test("parts are joined with em-dash separator", () => {
@@ -1273,6 +1292,60 @@ describe("buildCoordinatorBeacon", () => {
 	});
 });
 
+describe("orchestratorCommand", () => {
+	test("help shows orchestrator command name", async () => {
+		const output = await captureStdout(() => orchestratorCommand(["--help"]));
+		expect(output).toContain("orchestrator");
+	});
+
+	test("start creates orchestrator session with orchestrator capability", async () => {
+		const { deps, calls } = makeDeps({ "overstory-test-project-orchestrator": true });
+		const originalSleep = Bun.sleep;
+		Bun.sleep = (() => Promise.resolve()) as typeof Bun.sleep;
+
+		try {
+			const output = await captureStdout(() =>
+				orchestratorCommand(["start", "--no-attach", "--json"], deps),
+			);
+			const parsed = JSON.parse(output) as Record<string, unknown>;
+
+			expect(parsed.agentName).toBe("orchestrator");
+			expect(parsed.capability).toBe("orchestrator");
+			expect(parsed.tmuxSession).toBe("overstory-test-project-orchestrator");
+			expect(calls.createSession[0]?.name).toBe("overstory-test-project-orchestrator");
+			expect(calls.createSession[0]?.command).toContain("orchestrator.md");
+
+			const session = loadSessionsFromDb().find((entry) => entry.agentName === "orchestrator");
+			expect(session?.capability).toBe("orchestrator");
+		} finally {
+			Bun.sleep = originalSleep;
+		}
+	});
+
+	test("command registration includes orchestrator start/stop/status", () => {
+		const cmd = createOrchestratorCommand({});
+		const subcommandNames = cmd.commands.map((c) => c.name());
+		expect(subcommandNames).toContain("start");
+		expect(subcommandNames).toContain("stop");
+		expect(subcommandNames).toContain("status");
+		expect(subcommandNames).not.toContain("check-complete");
+	});
+});
+
+describe("buildOrchestratorBeacon", () => {
+	test("includes orchestrator identity in header", () => {
+		const beacon = buildOrchestratorBeacon();
+		expect(beacon).toContain("[OVERSTORY] orchestrator (orchestrator)");
+	});
+
+	test("includes ecosystem startup instructions", () => {
+		const beacon = buildOrchestratorBeacon("sd");
+		expect(beacon).toContain("ov mail check --agent orchestrator");
+		expect(beacon).toContain("sd ready");
+		expect(beacon).toContain("inspect ecosystem status");
+	});
+});
+
 describe("resolveAttach", () => {
 	test("--attach flag forces attach regardless of TTY", () => {
 		expect(resolveAttach(["--attach"], false)).toBe(true);