@os-eco/overstory-cli 0.6.1 → 0.6.5

package/src/commands/sling.ts

@@ -34,7 +34,7 @@ import type { TrackerIssue } from "../tracker/factory.ts";
 import { createTrackerClient, resolveBackend, trackerCliName } from "../tracker/factory.ts";
 import type { AgentSession, OverlayConfig } from "../types.ts";
 import { createWorktree } from "../worktree/manager.ts";
-import { createSession, sendKeys, waitForTuiReady } from "../worktree/tmux.ts";
+import { createSession, ensureTmuxAvailable, sendKeys, waitForTuiReady } from "../worktree/tmux.ts";
 
 /**
  * Calculate how many milliseconds to sleep before spawning a new agent,
@@ -98,15 +98,17 @@ export function inferDomainsFromFiles(
 	return [...inferred].sort();
 }
 
-/**
- * Parse a named flag value from an args array.
- */
-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];
+export interface SlingOptions {
+	capability?: string;
+	name?: string;
+	spec?: string;
+	files?: string;
+	parent?: string;
+	depth?: string;
+	skipScout?: boolean;
+	skipTaskCheck?: boolean;
+	forceHierarchy?: boolean;
+	json?: boolean;
 }
 
 /**
@@ -159,17 +161,17 @@ export function parentHasScouts(
 }
 
 /**
- * Check if any active agent is already working on the given bead ID.
+ * Check if any active agent is already working on the given task ID.
  * Returns the agent name if locked, or null if the bead is free.
  *
  * @param activeSessions - Currently active (non-zombie) sessions
- * @param beadId - The bead task ID to check for concurrent work
+ * @param taskId - The bead task ID to check for concurrent work
  */
 export function checkBeadLock(
-	activeSessions: ReadonlyArray<{ agentName: string; beadId: string }>,
-	beadId: string,
+	activeSessions: ReadonlyArray<{ agentName: string; taskId: string }>,
+	taskId: string,
 ): string | null {
-	const existing = activeSessions.find((s) => s.beadId === beadId);
+	const existing = activeSessions.find((s) => s.taskId === taskId);
 	return existing?.agentName ?? null;
 }
 
@@ -225,58 +227,26 @@ export function validateHierarchy(
 /**
  * Entry point for `overstory sling <task-id> [flags]`.
  *
- * Flags:
- *   --capability <type>    builder | scout | reviewer | lead | merger
- *   --name <name>          Unique agent name
- *   --spec <path>          Path to task spec file
- *   --files <f1,f2,...>    Exclusive file scope
- *   --parent <agent-name>  Parent agent (for hierarchy tracking)
- *   --depth <n>            Current hierarchy depth (default 0)
- *   --force-hierarchy      Bypass hierarchy validation (debugging only)
+ * @param taskId - The task ID to assign to the agent
+ * @param opts - Command options
  */
-const SLING_HELP = `overstory sling — Spawn a worker agent
-
-Usage: overstory sling <task-id> [flags]
-
-Arguments:
-  <task-id>                  Beads task ID to assign
-
-Options:
-  --capability <type>        Agent type: builder | scout | reviewer | lead | merger (default: builder)
-  --name <name>              Unique agent name (required)
-  --spec <path>              Path to task spec file
-  --files <f1,f2,...>        Exclusive file scope (comma-separated)
-  --parent <agent-name>      Parent agent for hierarchy tracking
-  --depth <n>                Current hierarchy depth (default: 0)
-  --skip-scout                 Skip scout phase for lead agents (jump to build)
-  --skip-task-check              Skip task existence validation (for worktree-created issues)
-  --force-hierarchy            Bypass hierarchy validation (debugging only)
-  --json                     Output result as JSON
-  --help, -h                 Show this help`;
-
-export async function slingCommand(args: string[]): Promise<void> {
-	if (args.includes("--help") || args.includes("-h")) {
-		process.stdout.write(`${SLING_HELP}\n`);
-		return;
-	}
-
-	const taskId = args.find((a) => !a.startsWith("--"));
+export async function slingCommand(taskId: string, opts: SlingOptions): Promise<void> {
 	if (!taskId) {
 		throw new ValidationError("Task ID is required: overstory sling <task-id>", {
 			field: "taskId",
 		});
 	}
 
-	const capability = getFlag(args, "--capability") ?? "builder";
-	const name = getFlag(args, "--name");
-	const specPath = getFlag(args, "--spec") ?? null;
-	const filesRaw = getFlag(args, "--files");
-	const parentAgent = getFlag(args, "--parent") ?? null;
-	const depthStr = getFlag(args, "--depth");
+	const capability = opts.capability ?? "builder";
+	const name = opts.name;
+	const specPath = opts.spec ?? null;
+	const filesRaw = opts.files;
+	const parentAgent = opts.parent ?? null;
+	const depthStr = opts.depth;
 	const depth = depthStr !== undefined ? Number.parseInt(depthStr, 10) : 0;
-	const forceHierarchy = args.includes("--force-hierarchy");
-	const skipScout = args.includes("--skip-scout");
-	const skipTaskCheck = args.includes("--skip-task-check");
+	const forceHierarchy = opts.forceHierarchy ?? false;
+	const skipScout = opts.skipScout ?? false;
+	const skipTaskCheck = opts.skipTaskCheck ?? false;
 
 	if (!name || name.trim().length === 0) {
 		throw new ValidationError("--name is required for sling", { field: "name" });
@@ -423,7 +393,7 @@ export async function slingCommand(args: string[]): Promise<void> {
 			});
 		}
 
-		// 5d. Bead-level locking: prevent concurrent agents on the same bead ID.
+		// 5d. Bead-level locking: prevent concurrent agents on the same task ID.
 		// Exception: the parent agent may delegate its own task to a child.
 		const lockHolder = checkBeadLock(activeSessions, taskId);
 		if (lockHolder !== null && lockHolder !== parentAgent) {
@@ -483,7 +453,7 @@ export async function slingCommand(args: string[]): Promise<void> {
 			baseDir: worktreeBaseDir,
 			agentName: name,
 			baseBranch: config.project.canonicalBranch,
-			beadId: taskId,
+			taskId: taskId,
 		});
 
 		// 8. Generate + write overlay CLAUDE.md
@@ -504,7 +474,7 @@ export async function slingCommand(args: string[]): Promise<void> {
 
 		const overlayConfig: OverlayConfig = {
 			agentName: name,
-			beadId: taskId,
+			taskId: taskId,
 			specPath: absoluteSpecPath,
 			branchName,
 			worktreePath,
@@ -567,6 +537,9 @@ export async function slingCommand(args: string[]): Promise<void> {
 			});
 		}
 
+		// 11b. Preflight: verify tmux is available before attempting session creation
+		await ensureTmuxAvailable();
+
 		// 12. Create tmux session running claude in interactive mode
 		const tmuxSessionName = `overstory-${config.project.name}-${name}`;
 		const { model, env } = resolveModel(config, manifest, capability, agentDef.model);
@@ -587,7 +560,7 @@ export async function slingCommand(args: string[]): Promise<void> {
 			capability,
 			worktreePath,
 			branchName,
-			beadId: taskId,
+			taskId: taskId,
 			tmuxSession: tmuxSessionName,
 			state: "booting",
 			pid,
@@ -645,7 +618,7 @@ export async function slingCommand(args: string[]): Promise<void> {
 			pid,
 		};
 
-		if (args.includes("--json")) {
+		if (opts.json ?? false) {
 			process.stdout.write(`${JSON.stringify(output)}\n`);
 		} else {
 			process.stdout.write(`🚀 Agent "${name}" launched!\n`);

package/src/commands/spec.test.ts

@@ -9,7 +9,7 @@ import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { mkdir } from "node:fs/promises";
 import { join } from "node:path";
 import { cleanupTempDir, createTempGitRepo } from "../test-helpers.ts";
-import { specCommand, writeSpec } from "./spec.ts";
+import { specWriteCommand, writeSpec } from "./spec.ts";
 
 let tempDir: string;
 let overstoryDir: string;
@@ -55,47 +55,21 @@ afterEach(async () => {
 	await cleanupTempDir(tempDir);
 });
 
-// === help ===
-
-describe("help", () => {
-	test("--help shows usage", async () => {
-		await specCommand(["--help"]);
-		expect(stdoutOutput).toContain("overstory spec");
-		expect(stdoutOutput).toContain("write");
-		expect(stdoutOutput).toContain("--body");
-		expect(stdoutOutput).toContain("--agent");
-	});
-
-	test("-h shows usage", async () => {
-		await specCommand(["-h"]);
-		expect(stdoutOutput).toContain("overstory spec");
-	});
-
-	test("no args shows help", async () => {
-		await specCommand([]);
-		expect(stdoutOutput).toContain("overstory spec");
-	});
-});
-
 // === validation ===
 
 describe("validation", () => {
-	test("unknown subcommand throws ValidationError", async () => {
-		await expect(specCommand(["unknown"])).rejects.toThrow("Unknown spec subcommand");
-	});
-
-	test("write without bead-id throws ValidationError", async () => {
-		await expect(specCommand(["write"])).rejects.toThrow("Bead ID is required");
+	test("write without task-id throws ValidationError", async () => {
+		await expect(specWriteCommand("", {})).rejects.toThrow("Task ID is required");
 	});
 
 	test("write without body throws ValidationError", async () => {
-		await expect(specCommand(["write", "task-abc", "--agent", "scout-1"])).rejects.toThrow(
+		await expect(specWriteCommand("task-abc", { agent: "scout-1" })).rejects.toThrow(
 			"Spec body is required",
 		);
 	});
 
 	test("write with empty body throws ValidationError", async () => {
-		await expect(specCommand(["write", "task-abc", "--body", "  "])).rejects.toThrow(
+		await expect(specWriteCommand("task-abc", { body: "  " })).rejects.toThrow(
 			"Spec body is required",
 		);
 	});
@@ -165,11 +139,11 @@ describe("writeSpec", () => {
 	});
 });
 
-// === specCommand (CLI integration) ===
+// === specWriteCommand (CLI integration) ===
 
-describe("specCommand write", () => {
+describe("specWriteCommand (integration)", () => {
 	test("writes spec and prints path", async () => {
-		await specCommand(["write", "task-cmd", "--body", "# CLI Spec"]);
+		await specWriteCommand("task-cmd", { body: "# CLI Spec" });
 
 		// Path may differ due to macOS /var -> /private/var symlink resolution
 		expect(stdoutOutput.trim()).toContain(".overstory/specs/task-cmd.md");
@@ -180,7 +154,7 @@ describe("specCommand write", () => {
 	});
 
 	test("writes spec with agent attribution", async () => {
-		await specCommand(["write", "task-attr", "--body", "# Attributed", "--agent", "scout-2"]);
+		await specWriteCommand("task-attr", { body: "# Attributed", agent: "scout-2" });
 
 		expect(stdoutOutput.trim()).toContain(".overstory/specs/task-attr.md");
 
@@ -190,14 +164,14 @@ describe("specCommand write", () => {
 		expect(content).toContain("# Attributed");
 	});
 
-	test("flags can appear in any order", async () => {
-		await specCommand(["write", "--agent", "scout-3", "--body", "# Content", "task-order"]);
+	test("writes spec without agent when agent is omitted", async () => {
+		await specWriteCommand("task-noagent", { body: "# No Agent" });
 
-		expect(stdoutOutput.trim()).toContain(".overstory/specs/task-order.md");
+		expect(stdoutOutput.trim()).toContain(".overstory/specs/task-noagent.md");
 
 		const specPath = stdoutOutput.trim();
 		const content = await Bun.file(specPath).text();
-		expect(content).toContain("<!-- written-by: scout-3 -->");
-		expect(content).toContain("# Content");
+		expect(content).not.toContain("written-by");
+		expect(content).toBe("# No Agent\n");
 	});
 });

package/src/commands/spec.ts

@@ -12,42 +12,9 @@ import { mkdir } from "node:fs/promises";
 import { join } from "node:path";
 import { ValidationError } from "../errors.ts";
 
-/** Boolean flags that do NOT consume the next arg. */
-const BOOLEAN_FLAGS = new Set(["--help", "-h"]);
-
-/**
- * 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];
-}
-
-/**
- * Extract positional arguments, skipping flag-value pairs.
- */
-function getPositionalArgs(args: string[]): string[] {
-	const positional: string[] = [];
-	let i = 0;
-	while (i < args.length) {
-		const arg = args[i];
-		if (arg?.startsWith("-")) {
-			if (BOOLEAN_FLAGS.has(arg)) {
-				i += 1;
-			} else {
-				i += 2;
-			}
-		} else {
-			if (arg !== undefined) {
-				positional.push(arg);
-			}
-			i += 1;
-		}
-	}
-	return positional;
+export interface SpecWriteOptions {
+	body?: string;
+	agent?: string;
 }
 
 /**
@@ -62,23 +29,6 @@ async function readStdin(): Promise<string> {
 	return await new Response(Bun.stdin.stream()).text();
 }
 
-const SPEC_HELP = `overstory spec -- Manage task specifications
-
-Usage: overstory spec <subcommand> [args...]
-
-Subcommands:
-  write <bead-id>          Write a spec file to .overstory/specs/<bead-id>.md
-
-Options for 'write':
-  --body <content>         Spec content (or pipe via stdin)
-  --agent <name>           Agent writing the spec (for attribution)
-  --help, -h               Show this help
-
-Examples:
-  overstory spec write task-abc --body "# Spec\\nDetails here..."
-  echo "# Spec" | overstory spec write task-abc
-  overstory spec write task-abc --body "..." --agent scout-1`;
-
 /**
  * Write a spec file to .overstory/specs/<bead-id>.md.
  *
@@ -86,7 +36,7 @@ Examples:
  */
 export async function writeSpec(
 	projectRoot: string,
-	beadId: string,
+	taskId: string,
 	body: string,
 	agent?: string,
 ): Promise<string> {
@@ -105,64 +55,45 @@ export async function writeSpec(
 		content += "\n";
 	}
 
-	const specPath = join(specsDir, `${beadId}.md`);
+	const specPath = join(specsDir, `${taskId}.md`);
 	await Bun.write(specPath, content);
 
 	return specPath;
 }
 
 /**
- * Entry point for `overstory spec <subcommand>`.
+ * Entry point for `overstory spec write <bead-id> [flags]`.
+ *
+ * @param taskId - The bead/task ID for the spec file
+ * @param opts - Command options
  */
-export async function specCommand(args: string[]): Promise<void> {
-	if (args.includes("--help") || args.includes("-h") || args.length === 0) {
-		process.stdout.write(`${SPEC_HELP}\n`);
-		return;
+export async function specWriteCommand(taskId: string, opts: SpecWriteOptions): Promise<void> {
+	if (!taskId || taskId.trim().length === 0) {
+		throw new ValidationError(
+			"Task ID is required: overstory spec write <task-id> --body <content>",
+			{ field: "taskId" },
+		);
 	}
 
-	const subcommand = args[0];
-	const subArgs = args.slice(1);
-
-	switch (subcommand) {
-		case "write": {
-			const positional = getPositionalArgs(subArgs);
-			const beadId = positional[0];
-			if (!beadId || beadId.trim().length === 0) {
-				throw new ValidationError(
-					"Bead ID is required: overstory spec write <bead-id> --body <content>",
-					{ field: "beadId" },
-				);
-			}
-
-			const agent = getFlag(subArgs, "--agent");
-			let body = getFlag(subArgs, "--body");
+	let body = opts.body;
 
-			// If no --body flag, try reading from stdin
-			if (body === undefined) {
-				const stdinContent = await readStdin();
-				if (stdinContent.trim().length > 0) {
-					body = stdinContent;
-				}
-			}
-
-			if (body === undefined || body.trim().length === 0) {
-				throw new ValidationError("Spec body is required: use --body <content> or pipe via stdin", {
-					field: "body",
-				});
-			}
-
-			const { resolveProjectRoot } = await import("../config.ts");
-			const projectRoot = await resolveProjectRoot(process.cwd());
-
-			const specPath = await writeSpec(projectRoot, beadId, body, agent);
-			process.stdout.write(`${specPath}\n`);
-			break;
+	// If no --body flag, try reading from stdin
+	if (body === undefined) {
+		const stdinContent = await readStdin();
+		if (stdinContent.trim().length > 0) {
+			body = stdinContent;
 		}
+	}
 
-		default:
-			throw new ValidationError(
-				`Unknown spec subcommand: ${subcommand}. Run 'overstory spec --help' for usage.`,
-				{ field: "subcommand", value: subcommand },
-			);
+	if (body === undefined || body.trim().length === 0) {
+		throw new ValidationError("Spec body is required: use --body <content> or pipe via stdin", {
+			field: "body",
+		});
 	}
+
+	const { resolveProjectRoot } = await import("../config.ts");
+	const projectRoot = await resolveProjectRoot(process.cwd());
+
+	const specPath = await writeSpec(projectRoot, taskId, body, opts.agent);
+	process.stdout.write(`${specPath}\n`);
 }

package/src/commands/status.test.ts

@@ -28,7 +28,7 @@ function makeAgent(overrides: Partial<AgentSession> = {}): AgentSession {
 		capability: "builder",
 		worktreePath: "/tmp/worktrees/test-builder",
 		branchName: "overstory/test-builder/task-1",
-		beadId: "task-1",
+		taskId: "task-1",
 		tmuxSession: "overstory-test-builder",
 		state: "working",
 		pid: 12345,
@@ -398,6 +398,102 @@ describe("--watch deprecation", () => {
 	});
 });
 
+describe("gatherStatus reconciliation", () => {
+	afterEach(() => {
+		invalidateStatusCache();
+	});
+
+	test("booting agent with dead tmux becomes zombie", async () => {
+		const tempDir = await createTempGitRepo();
+		const overstoryDir = join(tempDir, ".overstory");
+		await mkdir(overstoryDir, { recursive: true });
+
+		const store = createSessionStore(join(overstoryDir, "sessions.db"));
+		const now = new Date().toISOString();
+		const session = makeAgent({
+			agentName: "boot-builder",
+			capability: "builder",
+			state: "booting",
+			tmuxSession: "overstory-boot-builder",
+			runId: null,
+		});
+		session.startedAt = now;
+		session.lastActivity = now;
+		store.upsert(session);
+		store.close();
+
+		try {
+			// No real tmux running, so getCachedTmuxSessions() returns empty array
+			// evaluateHealth ZFC Rule 1: tmux dead → zombie
+			const result = await gatherStatus(tempDir, "orchestrator", false, undefined);
+			const agent = result.agents.find((a) => a.agentName === "boot-builder");
+			expect(agent).toBeDefined();
+			expect(agent?.state).toBe("zombie");
+		} finally {
+			await rm(tempDir, { recursive: true, force: true });
+		}
+	});
+
+	test("completed agents skip reconciliation", async () => {
+		const tempDir = await createTempGitRepo();
+		const overstoryDir = join(tempDir, ".overstory");
+		await mkdir(overstoryDir, { recursive: true });
+
+		const store = createSessionStore(join(overstoryDir, "sessions.db"));
+		const now = new Date().toISOString();
+		const session = makeAgent({
+			agentName: "done-builder",
+			capability: "builder",
+			state: "completed",
+			tmuxSession: "overstory-done-builder",
+			runId: null,
+		});
+		session.startedAt = now;
+		session.lastActivity = now;
+		store.upsert(session);
+		store.close();
+
+		try {
+			const result = await gatherStatus(tempDir, "orchestrator", false, undefined);
+			const agent = result.agents.find((a) => a.agentName === "done-builder");
+			expect(agent).toBeDefined();
+			expect(agent?.state).toBe("completed");
+		} finally {
+			await rm(tempDir, { recursive: true, force: true });
+		}
+	});
+
+	test("working agent with dead tmux becomes zombie", async () => {
+		const tempDir = await createTempGitRepo();
+		const overstoryDir = join(tempDir, ".overstory");
+		await mkdir(overstoryDir, { recursive: true });
+
+		const store = createSessionStore(join(overstoryDir, "sessions.db"));
+		const now = new Date().toISOString();
+		const session = makeAgent({
+			agentName: "working-builder",
+			capability: "builder",
+			state: "working",
+			tmuxSession: "overstory-working-builder",
+			runId: null,
+		});
+		session.startedAt = now;
+		session.lastActivity = now;
+		store.upsert(session);
+		store.close();
+
+		try {
+			// No real tmux session → tmux dead → zombie via evaluateHealth ZFC Rule 1
+			const result = await gatherStatus(tempDir, "orchestrator", false, undefined);
+			const agent = result.agents.find((a) => a.agentName === "working-builder");
+			expect(agent).toBeDefined();
+			expect(agent?.state).toBe("zombie");
+		} finally {
+			await rm(tempDir, { recursive: true, force: true });
+		}
+	});
+});
+
 describe("subprocess caching (invalidateStatusCache)", () => {
 	afterEach(() => {
 		invalidateStatusCache();