@os-eco/overstory-cli 0.6.1 → 0.6.4

package/README.md

@@ -127,6 +127,7 @@ overstory sling <task-id>              Spawn a worker agent
   --parent <agent-name>                  Parent (for hierarchy tracking)
   --depth <n>                            Current hierarchy depth
   --skip-scout                           Skip scout phase (passed to lead overlay)
+  --skip-task-check                      Skip task existence validation
   --json                                 JSON output
 
 overstory stop <agent-name>            Terminate a running agent
@@ -269,16 +270,16 @@ Global Flags:
 ## Tech Stack
 
 - **Runtime**: Bun (TypeScript directly, no build step)
-- **Dependencies**: Zero runtime dependencies — only Bun built-in APIs
+- **Dependencies**: Minimal runtime — `chalk` (color output), 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` (2087 tests across 75 files, colocated with source)
+- **Testing**: `bun test` (2128 tests across 76 files, colocated with source)
 - **External CLIs**: `bd` (beads) or `sd` (seeds), `mulch`, `git`, `tmux` — invoked as subprocesses
 
 ## Development
 
 ```bash
-# Run tests (2087 tests across 75 files)
+# Run tests (2128 tests across 76 files)
 bun test
 
 # Run a single test
@@ -307,14 +308,14 @@ Use the bump script to update both:
 bun run version:bump <major|minor|patch>
 ```
 
-Git tags are created automatically by GitHub Actions when a version bump is pushed to `main`.
+Git tags, npm publishing, and GitHub releases are handled automatically by the `publish.yml` workflow when a version bump is pushed to `main`.
 
 ## Project Structure
 
 ```
 overstory/
   src/
-    index.ts                      CLI entry point (command router)
+    index.ts                      CLI entry point (Commander.js program)
     types.ts                      Shared types and interfaces
     config.ts                     Config loader + validation
     errors.ts                     Custom error types
@@ -322,7 +323,7 @@ overstory/
       agents.ts                   Agent discovery and querying
       coordinator.ts              Persistent orchestrator lifecycle
       supervisor.ts               Team lead management
-      dashboard.ts                Live TUI dashboard (ANSI, zero deps)
+      dashboard.ts                Live TUI dashboard (ANSI via Chalk)
       hooks.ts                    Orchestrator hooks management
       sling.ts                    Agent spawning
       group.ts                    Task group batch tracking

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@os-eco/overstory-cli",
-	"version": "0.6.1",
+	"version": "0.6.4",
 	"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",
@@ -21,10 +21,15 @@
 		"developer-tools"
 	],
 	"bin": {
-		"overstory": "./src/index.ts"
+		"overstory": "./src/index.ts",
+		"ov": "./src/index.ts"
 	},
 	"main": "src/index.ts",
-	"files": ["src", "agents", "templates"],
+	"files": [
+		"src",
+		"agents",
+		"templates"
+	],
 	"publishConfig": {
 		"access": "public"
 	},
@@ -38,7 +43,10 @@
 		"typecheck": "tsc --noEmit",
 		"version:bump": "bun scripts/version-bump.ts"
 	},
-	"dependencies": {},
+	"dependencies": {
+		"chalk": "^5.6.2",
+		"commander": "^14.0.3"
+	},
 	"devDependencies": {
 		"@types/bun": "latest",
 		"typescript": "^5.9.0",

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

@@ -894,35 +894,37 @@ describe("isOverstoryHookEntry", () => {
 describe("getCapabilityGuards", () => {
 	// 10 native team tool blocks apply to ALL capabilities
 	const NATIVE_TEAM_TOOL_COUNT = 10;
+	// 3 interactive tool blocks (AskUserQuestion, EnterPlanMode, EnterWorktree) apply to ALL capabilities
+	const INTERACTIVE_TOOL_COUNT = 3;
 
-	test("returns 14 guards for scout (10 team + 3 tool blocks + 1 bash file guard)", () => {
+	test("returns 17 guards for scout (10 team + 3 interactive + 3 tool blocks + 1 bash file guard)", () => {
 		const guards = getCapabilityGuards("scout");
-		expect(guards.length).toBe(NATIVE_TEAM_TOOL_COUNT + 4);
+		expect(guards.length).toBe(NATIVE_TEAM_TOOL_COUNT + INTERACTIVE_TOOL_COUNT + 4);
 	});
 
-	test("returns 14 guards for reviewer (10 team + 3 tool blocks + 1 bash file guard)", () => {
+	test("returns 17 guards for reviewer (10 team + 3 interactive + 3 tool blocks + 1 bash file guard)", () => {
 		const guards = getCapabilityGuards("reviewer");
-		expect(guards.length).toBe(NATIVE_TEAM_TOOL_COUNT + 4);
+		expect(guards.length).toBe(NATIVE_TEAM_TOOL_COUNT + INTERACTIVE_TOOL_COUNT + 4);
 	});
 
-	test("returns 14 guards for lead (10 team + 3 tool blocks + 1 bash file guard)", () => {
+	test("returns 17 guards for lead (10 team + 3 interactive + 3 tool blocks + 1 bash file guard)", () => {
 		const guards = getCapabilityGuards("lead");
-		expect(guards.length).toBe(NATIVE_TEAM_TOOL_COUNT + 4);
+		expect(guards.length).toBe(NATIVE_TEAM_TOOL_COUNT + INTERACTIVE_TOOL_COUNT + 4);
 	});
 
-	test("returns 11 guards for builder (10 team + 1 bash path boundary)", () => {
+	test("returns 14 guards for builder (10 team + 3 interactive + 1 bash path boundary)", () => {
 		const guards = getCapabilityGuards("builder");
-		expect(guards.length).toBe(NATIVE_TEAM_TOOL_COUNT + 1);
+		expect(guards.length).toBe(NATIVE_TEAM_TOOL_COUNT + INTERACTIVE_TOOL_COUNT + 1);
 	});
 
-	test("returns 11 guards for merger (10 team + 1 bash path boundary)", () => {
+	test("returns 14 guards for merger (10 team + 3 interactive + 1 bash path boundary)", () => {
 		const guards = getCapabilityGuards("merger");
-		expect(guards.length).toBe(NATIVE_TEAM_TOOL_COUNT + 1);
+		expect(guards.length).toBe(NATIVE_TEAM_TOOL_COUNT + INTERACTIVE_TOOL_COUNT + 1);
 	});
 
-	test("returns 10 guards for unknown capability (10 team tool blocks only)", () => {
+	test("returns 13 guards for unknown capability (10 team + 3 interactive tool blocks)", () => {
 		const guards = getCapabilityGuards("unknown");
-		expect(guards.length).toBe(NATIVE_TEAM_TOOL_COUNT);
+		expect(guards.length).toBe(NATIVE_TEAM_TOOL_COUNT + INTERACTIVE_TOOL_COUNT);
 	});
 
 	test("builder gets Bash path boundary guard", () => {
@@ -1039,14 +1041,90 @@ describe("getCapabilityGuards", () => {
 		expect(taskGuard?.hooks[0]?.command).toContain('[ -z "$OVERSTORY_AGENT_NAME" ] && exit 0;');
 	});
 
-	test("coordinator gets 14 guards (10 team + 3 tool blocks + 1 bash file guard)", () => {
+	test("coordinator gets 17 guards (10 team + 3 interactive + 3 tool blocks + 1 bash file guard)", () => {
 		const guards = getCapabilityGuards("coordinator");
-		expect(guards.length).toBe(NATIVE_TEAM_TOOL_COUNT + 4);
+		expect(guards.length).toBe(NATIVE_TEAM_TOOL_COUNT + INTERACTIVE_TOOL_COUNT + 4);
 	});
 
-	test("supervisor gets 14 guards (10 team + 3 tool blocks + 1 bash file guard)", () => {
+	test("supervisor gets 17 guards (10 team + 3 interactive + 3 tool blocks + 1 bash file guard)", () => {
 		const guards = getCapabilityGuards("supervisor");
-		expect(guards.length).toBe(NATIVE_TEAM_TOOL_COUNT + 4);
+		expect(guards.length).toBe(NATIVE_TEAM_TOOL_COUNT + INTERACTIVE_TOOL_COUNT + 4);
+	});
+
+	test("all capabilities get AskUserQuestion blocked", () => {
+		for (const cap of [
+			"scout",
+			"reviewer",
+			"lead",
+			"coordinator",
+			"supervisor",
+			"builder",
+			"merger",
+			"unknown",
+		]) {
+			const guards = getCapabilityGuards(cap);
+			const guard = guards.find((g) => g.matcher === "AskUserQuestion");
+			expect(guard).toBeDefined();
+			expect(guard?.hooks[0]?.command).toContain("human interaction");
+			expect(guard?.hooks[0]?.command).toContain("overstory mail");
+		}
+	});
+
+	test("all capabilities get EnterPlanMode blocked", () => {
+		for (const cap of [
+			"scout",
+			"reviewer",
+			"lead",
+			"coordinator",
+			"supervisor",
+			"builder",
+			"merger",
+			"unknown",
+		]) {
+			const guards = getCapabilityGuards(cap);
+			const guard = guards.find((g) => g.matcher === "EnterPlanMode");
+			expect(guard).toBeDefined();
+			expect(guard?.hooks[0]?.command).toContain("human interaction");
+			expect(guard?.hooks[0]?.command).toContain("overstory mail");
+		}
+	});
+
+	test("all capabilities get EnterWorktree blocked", () => {
+		for (const cap of [
+			"scout",
+			"reviewer",
+			"lead",
+			"coordinator",
+			"supervisor",
+			"builder",
+			"merger",
+			"unknown",
+		]) {
+			const guards = getCapabilityGuards(cap);
+			const guard = guards.find((g) => g.matcher === "EnterWorktree");
+			expect(guard).toBeDefined();
+			expect(guard?.hooks[0]?.command).toContain("human interaction");
+			expect(guard?.hooks[0]?.command).toContain("overstory mail");
+		}
+	});
+
+	test("interactive guards include env var guard prefix", () => {
+		const guards = getCapabilityGuards("builder");
+		for (const tool of ["AskUserQuestion", "EnterPlanMode", "EnterWorktree"]) {
+			const guard = guards.find((g) => g.matcher === tool);
+			expect(guard).toBeDefined();
+			expect(guard?.hooks[0]?.command).toContain('[ -z "$OVERSTORY_AGENT_NAME" ] && exit 0;');
+		}
+	});
+
+	test("interactive guard block reason mentions tool name", () => {
+		const guards = getCapabilityGuards("scout");
+		const askGuard = guards.find((g) => g.matcher === "AskUserQuestion");
+		expect(askGuard?.hooks[0]?.command).toContain("AskUserQuestion");
+		const planGuard = guards.find((g) => g.matcher === "EnterPlanMode");
+		expect(planGuard?.hooks[0]?.command).toContain("EnterPlanMode");
+		const worktreeGuard = guards.find((g) => g.matcher === "EnterWorktree");
+		expect(worktreeGuard?.hooks[0]?.command).toContain("EnterWorktree");
 	});
 });
 

package/src/agents/hooks-deployer.ts

@@ -46,6 +46,13 @@ const NATIVE_TEAM_TOOLS = [
 	"TaskStop",
 ];
 
+/**
+ * Tools that require human interaction and block indefinitely in non-interactive
+ * tmux sessions. Agents run non-interactively and must never call these tools.
+ * Use overstory mail (--type question) to escalate to the orchestrator instead.
+ */
+const INTERACTIVE_TOOLS = ["AskUserQuestion", "EnterPlanMode", "EnterWorktree"];
+
 /** Tools that non-implementation agents must not use. */
 const WRITE_TOOLS = ["Write", "Edit", "NotebookEdit"];
 
@@ -445,6 +452,17 @@ export function getCapabilityGuards(capability: string): HookEntry[] {
 	);
 	guards.push(...teamToolGuards);
 
+	// Block interactive tools for ALL overstory agents.
+	// These tools require a human to respond and block indefinitely in tmux sessions.
+	// Agents must use overstory mail (--type question) to escalate instead.
+	const interactiveGuards = INTERACTIVE_TOOLS.map((tool) =>
+		blockGuard(
+			tool,
+			`${tool} requires human interaction -- agents run non-interactively. Use overstory mail (--type question) to escalate`,
+		),
+	);
+	guards.push(...interactiveGuards);
+
 	if (NON_IMPLEMENTATION_CAPABILITIES.has(capability)) {
 		const toolGuards = WRITE_TOOLS.map((tool) =>
 			blockGuard(tool, `${capability} agents cannot modify files — ${tool} is not allowed`),

package/src/agents/manifest.test.ts

@@ -635,6 +635,40 @@ describe("resolveModel", () => {
 		const result = resolveModel(config, baseManifest, "coordinator", "opus");
 		expect(result).toEqual({ model: "native-gw/claude-3-5-sonnet" });
 	});
+
+	test("handles deeply nested model ID (slashes in model name)", () => {
+		const config = makeConfig(
+			{ coordinator: "openrouter/openai/gpt-5.3" },
+			{
+				openrouter: {
+					type: "gateway",
+					baseUrl: "https://openrouter.ai/api/v1",
+					authTokenEnv: "OPENROUTER_API_KEY",
+				},
+			},
+		);
+		const result = resolveModel(config, baseManifest, "coordinator", "opus");
+		// First "/" splits provider "openrouter" from model ID "openai/gpt-5.3"
+		expect(result.model).toBe("sonnet");
+		expect(result.env?.ANTHROPIC_DEFAULT_SONNET_MODEL).toBe("openai/gpt-5.3");
+	});
+
+	test("handles model ID with multiple slashes after provider", () => {
+		const config = makeConfig(
+			{ coordinator: "mygateway/org/model/version" },
+			{
+				mygateway: {
+					type: "gateway",
+					baseUrl: "https://mygateway.example.com",
+					authTokenEnv: "MYGATEWAY_KEY",
+				},
+			},
+		);
+		const result = resolveModel(config, baseManifest, "coordinator", "opus");
+		// Provider is "mygateway", model ID is everything after the first "/"
+		expect(result.model).toBe("sonnet");
+		expect(result.env?.ANTHROPIC_DEFAULT_SONNET_MODEL).toBe("org/model/version");
+	});
 });
 
 describe("resolveProviderEnv", () => {
@@ -704,6 +738,58 @@ describe("resolveProviderEnv", () => {
 		);
 		expect(result).not.toHaveProperty("ANTHROPIC_AUTH_TOKEN");
 	});
+
+	test("env always sets ANTHROPIC_API_KEY to empty string", () => {
+		const result = resolveProviderEnv(
+			"openrouter",
+			"openai/gpt-5.3",
+			{
+				openrouter: {
+					type: "gateway",
+					baseUrl: "https://openrouter.ai/api/v1",
+					authTokenEnv: "OPENROUTER_API_KEY",
+				},
+			},
+			{ OPENROUTER_API_KEY: "my-token" },
+		);
+		expect(result).not.toBeNull();
+		expect(result?.ANTHROPIC_API_KEY).toBe("");
+	});
+
+	test("handles authTokenEnv pointing to undefined env var", () => {
+		const result = resolveProviderEnv(
+			"openrouter",
+			"openai/gpt-5.3",
+			{
+				openrouter: {
+					type: "gateway",
+					baseUrl: "https://openrouter.ai/api/v1",
+					authTokenEnv: "MISSING_VAR",
+				},
+			},
+			{},
+		);
+		expect(result).not.toBeNull();
+		expect(result).not.toHaveProperty("ANTHROPIC_AUTH_TOKEN");
+	});
+
+	test("handles authTokenEnv field being undefined", () => {
+		const result = resolveProviderEnv(
+			"mygw",
+			"some-model",
+			{
+				mygw: {
+					type: "gateway",
+					baseUrl: "https://mygw.example.com",
+				},
+			},
+			{},
+		);
+		expect(result).not.toBeNull();
+		expect(result?.ANTHROPIC_BASE_URL).toBe("https://mygw.example.com");
+		expect(result?.ANTHROPIC_API_KEY).toBe("");
+		expect(result).not.toHaveProperty("ANTHROPIC_AUTH_TOKEN");
+	});
 });
 
 describe("manifest validation accepts arbitrary model strings", () => {

package/src/commands/agents.test.ts

@@ -300,18 +300,18 @@ logging:
 
 	it("should show help with --help flag", async () => {
 		await agentsCommand(["--help"]);
-		expect(stdoutBuffer).toContain("overstory agents");
+		expect(stdoutBuffer).toContain("agents");
 		expect(stdoutBuffer).toContain("discover");
 	});
 
 	it("should show help with no subcommand", async () => {
 		await agentsCommand([]);
-		expect(stdoutBuffer).toContain("overstory agents");
+		expect(stdoutBuffer).toContain("agents");
 		expect(stdoutBuffer).toContain("discover");
 	});
 
 	it("should error on unknown subcommand", async () => {
-		await expect(agentsCommand(["unknown"])).rejects.toThrow("Unknown subcommand");
+		await expect(agentsCommand(["unknown"])).rejects.toThrow("unknown command");
 	});
 
 	afterEach(async () => {

package/src/commands/agents.ts

@@ -5,26 +5,12 @@
  */
 
 import { join } from "node:path";
+import { Command } from "commander";
 import { loadConfig } from "../config.ts";
 import { ValidationError } from "../errors.ts";
 import { openSessionStore } from "../sessions/compat.ts";
 import { type AgentSession, SUPPORTED_CAPABILITIES } 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);
-}
-
 /**
  * Discovered agent information including file scope.
  */
@@ -194,94 +180,79 @@ function printAgents(agents: DiscoveredAgent[]): void {
 	}
 }
 
-const DISCOVER_HELP = `overstory agents discover — Find active agents by capability
-
-Usage: overstory agents discover [--capability <type>] [--all] [--json]
-
-Options:
-  --capability <type>   Filter by capability (builder, scout, reviewer, lead, merger, coordinator, supervisor)
-  --all                 Include completed and zombie agents (default: active only)
-  --json                Output as JSON
-  --help, -h            Show this help`;
-
-const AGENTS_HELP = `overstory agents — Discover and query agents
-
-Usage: overstory agents <subcommand> [options]
-
-Subcommands:
-  discover              Find active agents by capability
-
-Options:
-  --json                Output as JSON
-  --help, -h            Show this help
-
-Run 'overstory agents <subcommand> --help' for subcommand-specific help.`;
-
 /**
- * Handle the 'discover' subcommand.
+ * Create the Commander command for `overstory agents`.
  */
-async function discoverCommand(args: string[]): Promise<void> {
-	if (hasFlag(args, "--help") || hasFlag(args, "-h")) {
-		process.stdout.write(`${DISCOVER_HELP}\n`);
-		return;
-	}
+export function createAgentsCommand(): Command {
+	const cmd = new Command("agents").description("Discover and query agents");
+
+	cmd
+		.command("discover")
+		.description("Find active agents by capability")
+		.option(
+			"--capability <type>",
+			"Filter by capability (builder, scout, reviewer, lead, merger, coordinator, supervisor)",
+		)
+		.option("--all", "Include completed and zombie agents (default: active only)")
+		.option("--json", "Output as JSON")
+		.action(async (opts: { capability?: string; all?: boolean; json?: boolean }) => {
+			const capability = opts.capability;
+
+			// Validate capability if provided
+			if (capability && !SUPPORTED_CAPABILITIES.includes(capability as never)) {
+				throw new ValidationError(
+					`Invalid capability: ${capability}. Must be one of: ${SUPPORTED_CAPABILITIES.join(", ")}`,
+					{
+						field: "capability",
+						value: capability,
+					},
+				);
+			}
 
-	const json = hasFlag(args, "--json");
-	const includeAll = hasFlag(args, "--all");
-	const capability = getFlag(args, "--capability");
-
-	// Validate capability if provided
-	if (capability && !SUPPORTED_CAPABILITIES.includes(capability as never)) {
-		throw new ValidationError(
-			`Invalid capability: ${capability}. Must be one of: ${SUPPORTED_CAPABILITIES.join(", ")}`,
-			{
-				field: "capability",
-				value: capability,
-			},
-		);
-	}
+			const cwd = process.cwd();
+			const config = await loadConfig(cwd);
+			const root = config.project.root;
 
-	const cwd = process.cwd();
-	const config = await loadConfig(cwd);
-	const root = config.project.root;
+			const agents = await discoverAgents(root, {
+				capability,
+				includeAll: opts.all ?? false,
+			});
 
-	const agents = await discoverAgents(root, { capability, includeAll });
+			if (opts.json) {
+				process.stdout.write(`${JSON.stringify(agents, null, "\t")}\n`);
+			} else {
+				printAgents(agents);
+			}
+		});
 
-	if (json) {
-		process.stdout.write(`${JSON.stringify(agents, null, "\t")}\n`);
-	} else {
-		printAgents(agents);
-	}
+	return cmd;
 }
 
 /**
  * Entry point for `overstory agents <subcommand>`.
  */
 export async function agentsCommand(args: string[]): Promise<void> {
-	if (hasFlag(args, "--help") || hasFlag(args, "-h")) {
-		process.stdout.write(`${AGENTS_HELP}\n`);
-		return;
-	}
+	const cmd = createAgentsCommand();
+	cmd.exitOverride();
 
-	// Extract subcommand: first arg that is not a flag
-	const subcommand = args.find((arg) => !arg.startsWith("-"));
-
-	if (!subcommand) {
-		process.stdout.write(`${AGENTS_HELP}\n`);
+	if (args.length === 0) {
+		process.stdout.write(cmd.helpInformation());
 		return;
 	}
 
-	// Remove the subcommand from args before passing to handler
-	const subArgs = args.filter((arg) => arg !== subcommand);
-
-	switch (subcommand) {
-		case "discover":
-			await discoverCommand(subArgs);
-			break;
-		default:
-			throw new ValidationError(`Unknown subcommand: ${subcommand}`, {
-				field: "subcommand",
-				value: subcommand,
-			});
+	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 === "commander.unknownCommand") {
+				const message = err instanceof Error ? err.message : String(err);
+				throw new ValidationError(message, { field: "subcommand" });
+			}
+		}
+		throw err;
 	}
 }