@os-eco/overstory-cli 0.6.1 → 0.6.5

package/src/agents/lifecycle.test.ts

@@ -23,7 +23,7 @@ describe("lifecycle", () => {
 			agentsDir,
 			agentName: "builder-1",
 			sessionId: "session-100",
-			beadId: "overstory-xyz1",
+			taskId: "overstory-xyz1",
 			reason: "compaction",
 			progressSummary: "Built the widget",
 			pendingWork: "Tests remain",
@@ -56,7 +56,7 @@ describe("lifecycle", () => {
 			agentsDir,
 			agentName: "builder-2",
 			sessionId: "session-200",
-			beadId: "overstory-abc2",
+			taskId: "overstory-abc2",
 			reason: "crash",
 			progressSummary: "Halfway done",
 			pendingWork: "Finish implementation",
@@ -82,7 +82,7 @@ describe("lifecycle", () => {
 			agentsDir,
 			agentName: "builder-3",
 			sessionId: "session-300",
-			beadId: "overstory-def3",
+			taskId: "overstory-def3",
 			reason: "manual",
 			progressSummary: "Done with phase 1",
 			pendingWork: "Phase 2",
@@ -116,7 +116,7 @@ describe("lifecycle", () => {
 			agentsDir,
 			agentName: "builder-4",
 			sessionId: "session-400",
-			beadId: "overstory-ghi4",
+			taskId: "overstory-ghi4",
 			reason: "compaction",
 			progressSummary: "First session work",
 			pendingWork: "Continue",
@@ -137,7 +137,7 @@ describe("lifecycle", () => {
 			agentsDir,
 			agentName: "builder-4",
 			sessionId: "session-401",
-			beadId: "overstory-ghi4",
+			taskId: "overstory-ghi4",
 			reason: "timeout",
 			progressSummary: "Second session work",
 			pendingWork: "Finish up",
@@ -172,7 +172,7 @@ describe("lifecycle", () => {
 			agentsDir,
 			agentName: "builder-5",
 			sessionId: "session-500",
-			beadId: "overstory-jkl5",
+			taskId: "overstory-jkl5",
 			reason: "compaction",
 			progressSummary: "Done",
 			pendingWork: "Nothing",

package/src/agents/lifecycle.ts

@@ -73,7 +73,7 @@ export async function initiateHandoff(options: {
 	agentsDir: string;
 	agentName: string;
 	sessionId: string;
-	beadId: string;
+	taskId: string;
 	reason: SessionHandoff["reason"];
 	progressSummary: string;
 	pendingWork: string;
@@ -83,7 +83,7 @@ export async function initiateHandoff(options: {
 }): Promise<SessionHandoff> {
 	const checkpoint: SessionCheckpoint = {
 		agentName: options.agentName,
-		beadId: options.beadId,
+		taskId: options.taskId,
 		sessionId: options.sessionId,
 		timestamp: new Date().toISOString(),
 		progressSummary: options.progressSummary,

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/agents/overlay.test.ts

@@ -25,7 +25,7 @@ Read your assignment. Execute immediately.
 function makeConfig(overrides?: Partial<OverlayConfig>): OverlayConfig {
 	return {
 		agentName: "test-builder",
-		beadId: "overstory-abc",
+		taskId: "overstory-abc",
 		specPath: ".overstory/specs/overstory-abc.md",
 		branchName: "agent/test-builder/overstory-abc",
 		worktreePath: "/tmp/test-project/.overstory/worktrees/test-builder",
@@ -48,8 +48,8 @@ describe("generateOverlay", () => {
 		expect(output).toContain("my-scout");
 	});
 
-	test("output contains bead ID", async () => {
-		const config = makeConfig({ beadId: "overstory-xyz" });
+	test("output contains task ID", async () => {
+		const config = makeConfig({ taskId: "overstory-xyz" });
 		const output = await generateOverlay(config);
 
 		expect(output).toContain("overstory-xyz");
@@ -261,7 +261,7 @@ describe("generateOverlay", () => {
 		const config = makeConfig({
 			capability: "scout",
 			agentName: "recon-1",
-			beadId: "overstory-task1",
+			taskId: "overstory-task1",
 			parentAgent: "lead-alpha",
 		});
 		const output = await generateOverlay(config);
@@ -419,7 +419,7 @@ describe("generateOverlay", () => {
 	});
 
 	test("default trackerCli renders as bd in quality gates", async () => {
-		const config = makeConfig({ capability: "builder", beadId: "overstory-task1" });
+		const config = makeConfig({ capability: "builder", taskId: "overstory-task1" });
 		const output = await generateOverlay(config);
 
 		expect(output).toContain("bd close overstory-task1");
@@ -429,7 +429,7 @@ describe("generateOverlay", () => {
 		const config = makeConfig({
 			capability: "builder",
 			trackerCli: "sd",
-			beadId: "overstory-test1",
+			taskId: "overstory-test1",
 		});
 		const output = await generateOverlay(config);
 
@@ -451,7 +451,7 @@ describe("generateOverlay", () => {
 		const config = makeConfig({
 			capability: "scout",
 			trackerCli: "sd",
-			beadId: "overstory-test2",
+			taskId: "overstory-test2",
 		});
 		const output = await generateOverlay(config);
 
@@ -482,7 +482,7 @@ describe("generateOverlay", () => {
 	});
 
 	test("defaults backward-compatible: no trackerCli/trackerName produces bd/beads", async () => {
-		const config = makeConfig({ capability: "builder", beadId: "overstory-back" });
+		const config = makeConfig({ capability: "builder", taskId: "overstory-back" });
 		const output = await generateOverlay(config);
 
 		expect(output).toContain("bd close overstory-back");
@@ -521,7 +521,7 @@ describe("writeOverlay", () => {
 		const outputPath = join(worktreePath, ".claude", "CLAUDE.md");
 		const content = await Bun.file(outputPath).text();
 		expect(content).toContain("file-writer-test");
-		expect(content).toContain(config.beadId);
+		expect(content).toContain(config.taskId);
 		expect(content).toContain(config.branchName);
 	});
 

package/src/agents/overlay.ts

@@ -91,7 +91,7 @@ function formatQualityGates(config: OverlayConfig): string {
 			"Before reporting completion:",
 			"",
 			`1. **Record mulch learnings:** \`mulch record <domain> --type <convention|pattern|reference> --description "..."\` — capture reusable knowledge from your work`,
-			`2. **Close issue:** \`${config.trackerCli ?? "bd"} close ${config.beadId} --reason "summary of findings"\``,
+			`2. **Close issue:** \`${config.trackerCli ?? "bd"} close ${config.taskId} --reason "summary of findings"\``,
 			`3. **Send results:** \`overstory mail send --to ${config.parentAgent ?? "coordinator"} --subject "done" --body "Summary" --type result --agent ${config.agentName}\``,
 			"",
 			"You are a read-only agent. Do NOT commit, modify files, or run quality gates.",
@@ -113,8 +113,8 @@ function formatQualityGates(config: OverlayConfig): string {
 		...gateLines,
 		`${gateLines.length + 1}. **Commit:** all changes committed to your branch (${config.branchName})`,
 		`${gateLines.length + 2}. **Record mulch learnings:** \`mulch record <domain> --type <convention|pattern|failure|decision> --description "..." --outcome-status success --outcome-agent ${config.agentName}\` — capture insights from your work`,
-		`${gateLines.length + 3}. **Signal completion:** send \`worker_done\` mail to ${config.parentAgent ?? "coordinator"}: \`overstory mail send --to ${config.parentAgent ?? "coordinator"} --subject "Worker done: ${config.beadId}" --body "Quality gates passed." --type worker_done --agent ${config.agentName}\``,
-		`${gateLines.length + 4}. **Close issue:** \`${config.trackerCli ?? "bd"} close ${config.beadId} --reason "summary of changes"\``,
+		`${gateLines.length + 3}. **Signal completion:** send \`worker_done\` mail to ${config.parentAgent ?? "coordinator"}: \`overstory mail send --to ${config.parentAgent ?? "coordinator"} --subject "Worker done: ${config.taskId}" --body "Quality gates passed." --type worker_done --agent ${config.agentName}\``,
+		`${gateLines.length + 4}. **Close issue:** \`${config.trackerCli ?? "bd"} close ${config.taskId} --reason "summary of changes"\``,
 		"",
 		"Do NOT push to the canonical branch. Your work will be merged by the",
 		"coordinator via `overstory merge`.",
@@ -205,7 +205,7 @@ export async function generateOverlay(config: OverlayConfig): Promise<string> {
 
 	const replacements: Record<string, string> = {
 		"{{AGENT_NAME}}": config.agentName,
-		"{{BEAD_ID}}": config.beadId,
+		"{{BEAD_ID}}": config.taskId,
 		"{{SPEC_PATH}}": config.specPath ?? "No spec file provided",
 		"{{BRANCH_NAME}}": config.branchName,
 		"{{WORKTREE_PATH}}": config.worktreePath,

package/src/commands/agents.test.ts

@@ -97,7 +97,7 @@ describe("discoverAgents", () => {
 			capability: "builder",
 			worktreePath: join(tempDir, ".overstory", "worktrees", "builder-test"),
 			branchName: "overstory/builder-test/task-123",
-			beadId: "task-123",
+			taskId: "task-123",
 			tmuxSession: "overstory-test-builder",
 			state: "working",
 			pid: 12345,
@@ -129,7 +129,7 @@ describe("discoverAgents", () => {
 			capability: "builder",
 			worktreePath: join(tempDir, ".overstory", "worktrees", "builder-test"),
 			branchName: "overstory/builder-test/task-123",
-			beadId: "task-123",
+			taskId: "task-123",
 			tmuxSession: "overstory-test-builder",
 			state: "working",
 			pid: 12345,
@@ -148,7 +148,7 @@ describe("discoverAgents", () => {
 			capability: "scout",
 			worktreePath: join(tempDir, ".overstory", "worktrees", "scout-test"),
 			branchName: "overstory/scout-test/task-456",
-			beadId: "task-456",
+			taskId: "task-456",
 			tmuxSession: "overstory-test-scout",
 			state: "working",
 			pid: 12346,
@@ -180,7 +180,7 @@ describe("discoverAgents", () => {
 			capability: "builder",
 			worktreePath: join(tempDir, ".overstory", "worktrees", "builder-working"),
 			branchName: "overstory/builder-working/task-123",
-			beadId: "task-123",
+			taskId: "task-123",
 			tmuxSession: "overstory-test-working",
 			state: "working",
 			pid: 12345,
@@ -199,7 +199,7 @@ describe("discoverAgents", () => {
 			capability: "builder",
 			worktreePath: join(tempDir, ".overstory", "worktrees", "builder-completed"),
 			branchName: "overstory/builder-completed/task-456",
-			beadId: "task-456",
+			taskId: "task-456",
 			tmuxSession: "overstory-test-completed",
 			state: "completed",
 			pid: null,
@@ -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.
  */
@@ -32,7 +18,7 @@ export interface DiscoveredAgent {
 	agentName: string;
 	capability: string;
 	state: string;
-	beadId: string;
+	taskId: string;
 	branchName: string;
 	parentAgent: string | null;
 	depth: number;
@@ -131,7 +117,7 @@ export async function discoverAgents(
 					agentName: session.agentName,
 					capability: session.capability,
 					state: session.state,
-					beadId: session.beadId,
+					taskId: session.taskId,
 					branchName: session.branchName,
 					parentAgent: session.parentAgent,
 					depth: session.depth,
@@ -180,7 +166,7 @@ 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.beadId}\n`);
+		w(`    State: ${agent.state} | Task: ${agent.taskId}\n`);
 		w(`    Branch: ${agent.branchName}\n`);
 		w(`    Parent: ${agent.parentAgent ?? "none"} | Depth: ${agent.depth}\n`);
 
@@ -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;
 	}
 }