@os-eco/overstory-cli 0.9.3 → 0.10.3

package/src/commands/dashboard.test.ts

@@ -295,6 +295,7 @@ function makeDashboardData(
 			worktrees: [],
 			tmuxSessions: [],
 			unreadMailCount: 0,
+			unreadMailScope: "orchestrator",
 			mergeQueueCount: 0,
 			recentMetricsCount: 0,
 		},
@@ -447,6 +448,7 @@ describe("renderAgentPanel", () => {
 				worktrees: [],
 				tmuxSessions: [], // no tmux sessions
 				unreadMailCount: 0,
+				unreadMailScope: "orchestrator",
 				mergeQueueCount: 0,
 				recentMetricsCount: 0,
 			},
@@ -487,6 +489,7 @@ describe("renderAgentPanel", () => {
 				worktrees: [],
 				tmuxSessions: [],
 				unreadMailCount: 0,
+				unreadMailScope: "orchestrator",
 				mergeQueueCount: 0,
 				recentMetricsCount: 0,
 			},
@@ -495,6 +498,191 @@ describe("renderAgentPanel", () => {
 		expect(out).toContain("x");
 		expect(out).toContain("dead-headless");
 	});
+
+	test("renders mixed tmux + headless agents in same frame with correct liveness", () => {
+		const data = {
+			...makeDashboardData({}),
+			status: {
+				currentRunId: null,
+				agents: [
+					{
+						id: "sess-tmux-1",
+						agentName: "pane-agent",
+						capability: "builder",
+						worktreePath: "/tmp/wt/pane-agent",
+						branchName: "overstory/pane-agent/task-t1",
+						taskId: "task-t1",
+						tmuxSession: "overstory-pane-agent",
+						state: "working" as const,
+						pid: 99999,
+						parentAgent: null,
+						depth: 0,
+						runId: null,
+						startedAt: new Date(Date.now() - 10_000).toISOString(),
+						lastActivity: new Date().toISOString(),
+						escalationLevel: 0,
+						stalledSince: null,
+						transcriptPath: null,
+					},
+					{
+						id: "sess-headless-1",
+						agentName: "live-headless",
+						capability: "builder",
+						worktreePath: "/tmp/wt/live-headless",
+						branchName: "overstory/live-headless/task-h1",
+						taskId: "task-h1",
+						tmuxSession: "", // headless
+						state: "working" as const,
+						pid: process.pid, // own PID — guaranteed alive
+						parentAgent: null,
+						depth: 0,
+						runId: null,
+						startedAt: new Date(Date.now() - 10_000).toISOString(),
+						lastActivity: new Date().toISOString(),
+						escalationLevel: 0,
+						stalledSince: null,
+						transcriptPath: null,
+					},
+				],
+				worktrees: [],
+				tmuxSessions: [{ name: "overstory-pane-agent", pid: 99998 }],
+				unreadMailCount: 0,
+				unreadMailScope: "orchestrator",
+				mergeQueueCount: 0,
+				recentMetricsCount: 0,
+			},
+		};
+		const out = renderAgentPanel(data, 100, 12, 3);
+		expect(out).toContain("pane-agent");
+		expect(out).toContain("live-headless");
+		const aliveMarkers = (out.match(/>/g) ?? []).length;
+		expect(aliveMarkers).toBeGreaterThanOrEqual(2);
+		expect(out).not.toContain("x");
+	});
+
+	test("spawn-per-turn worker (no tmux, no pid) renders alive when state is non-terminal (overstory-7a34)", () => {
+		// Repro: freshly slung headless lead has tmuxSession='' and pid=null.
+		// Previously fell into the tmux path → never matched → red "x" while
+		// ov feed showed live tool events from the same agent.
+		const data = {
+			...makeDashboardData({}),
+			status: {
+				currentRunId: null,
+				agents: [
+					{
+						id: "sess-spt-1",
+						agentName: "freshly-slung",
+						capability: "lead",
+						worktreePath: "/tmp/wt/freshly-slung",
+						branchName: "overstory/freshly-slung/task-l1",
+						taskId: "task-l1",
+						tmuxSession: "", // headless
+						state: "working" as const,
+						pid: null, // spawn-per-turn: no persistent process between turns
+						parentAgent: null,
+						depth: 0,
+						runId: null,
+						startedAt: new Date(Date.now() - 5_000).toISOString(),
+						lastActivity: new Date().toISOString(),
+						escalationLevel: 0,
+						stalledSince: null,
+						transcriptPath: null,
+					},
+				],
+				worktrees: [],
+				tmuxSessions: [],
+				unreadMailCount: 0,
+				unreadMailScope: "orchestrator",
+				mergeQueueCount: 0,
+				recentMetricsCount: 0,
+			},
+		};
+		const out = renderAgentPanel(data, 100, 12, 3);
+		expect(out).toContain("freshly-slung");
+		// Green ">" — agent is logically alive between turns
+		expect(out).toContain(">");
+		// No red marker should be present (name 'freshly-slung' has no 'x')
+		expect(out).not.toContain("x");
+	});
+
+	test("spawn-per-turn worker in zombie state renders dead marker (overstory-7a34)", () => {
+		const data = {
+			...makeDashboardData({}),
+			status: {
+				currentRunId: null,
+				agents: [
+					{
+						id: "sess-spt-2",
+						agentName: "abandoned-spt",
+						capability: "builder",
+						worktreePath: "/tmp/wt/abandoned-spt",
+						branchName: "overstory/abandoned-spt/task-a1",
+						taskId: "task-a1",
+						tmuxSession: "",
+						state: "zombie" as const,
+						pid: null,
+						parentAgent: null,
+						depth: 0,
+						runId: null,
+						startedAt: new Date(Date.now() - 600_000).toISOString(),
+						lastActivity: new Date(Date.now() - 600_000).toISOString(),
+						escalationLevel: 0,
+						stalledSince: null,
+						transcriptPath: null,
+					},
+				],
+				worktrees: [],
+				tmuxSessions: [],
+				unreadMailCount: 0,
+				unreadMailScope: "orchestrator",
+				mergeQueueCount: 0,
+				recentMetricsCount: 0,
+			},
+		};
+		const out = renderAgentPanel(data, 100, 12, 3);
+		expect(out).toContain("abandoned-spt");
+		expect(out).toContain("x");
+	});
+
+	test("headless agent renders dead marker when tmux session list is non-empty", () => {
+		const deadPid = 2_147_483_647;
+		const data = {
+			...makeDashboardData({}),
+			status: {
+				currentRunId: null,
+				agents: [
+					{
+						id: "sess-dead-headless-1",
+						agentName: "gone-headless",
+						capability: "builder",
+						worktreePath: "/tmp/wt/gone-headless",
+						branchName: "overstory/gone-headless/task-g1",
+						taskId: "task-g1",
+						tmuxSession: "", // headless
+						state: "working" as const,
+						pid: deadPid,
+						parentAgent: null,
+						depth: 0,
+						runId: null,
+						startedAt: new Date(Date.now() - 10_000).toISOString(),
+						lastActivity: new Date().toISOString(),
+						escalationLevel: 0,
+						stalledSince: null,
+						transcriptPath: null,
+					},
+				],
+				worktrees: [],
+				tmuxSessions: [{ name: "overstory-other-tmux", pid: 11111 }],
+				unreadMailCount: 0,
+				unreadMailScope: "orchestrator",
+				mergeQueueCount: 0,
+				recentMetricsCount: 0,
+			},
+		};
+		const out = renderAgentPanel(data, 100, 12, 3);
+		expect(out).toContain("x");
+		expect(out).toContain("gone-headless");
+	});
 });
 
 describe("openDashboardStores", () => {

package/src/commands/dashboard.ts

@@ -434,6 +434,7 @@ async function loadDashboardData(
 		worktrees,
 		tmuxSessions,
 		unreadMailCount,
+		unreadMailScope: "orchestrator",
 		mergeQueueCount,
 		recentMetricsCount,
 	};
@@ -644,10 +645,19 @@ export function renderAgentPanel(
 				: now;
 		const duration = formatDuration(endTime - new Date(agent.startedAt).getTime());
 		const durationPadded = pad(duration, 9);
+		// Three liveness topologies (overstory-7a34):
+		//   tmux:           tmuxSession !== ""        → tmux session must exist
+		//   long-lived headless: tmuxSession === "" && pid !== null → PID must be alive
+		//   spawn-per-turn: tmuxSession === "" && pid === null   → no process between
+		//     turns is normal, so liveness reduces to "state is non-terminal".
+		//     Time-based stale/zombie classification is handled in evaluateHealth.
 		const isHeadless = agent.tmuxSession === "" && agent.pid !== null;
-		const alive = isHeadless
-			? agent.pid !== null && isProcessAlive(agent.pid)
-			: data.status.tmuxSessions.some((s) => s.name === agent.tmuxSession);
+		const isSpawnPerTurn = agent.tmuxSession === "" && agent.pid === null;
+		const alive = isSpawnPerTurn
+			? agent.state !== "zombie" && agent.state !== "completed"
+			: isHeadless
+				? agent.pid !== null && isProcessAlive(agent.pid)
+				: data.status.tmuxSessions.some((s) => s.name === agent.tmuxSession);
 		const aliveDot = alive ? color.green(">") : color.red("x");
 
 		const lineContent = `${dimBox.vertical} ${stateColorFn(icon)}  ${name} ${capability} ${color.dim(runtime)} ${stateColorFn(state)} ${taskId} ${durationPadded} ${aliveDot}    `;

package/src/commands/doctor.ts

@@ -16,6 +16,7 @@ import { checkEcosystem } from "../doctor/ecosystem.ts";
 import { checkLogs } from "../doctor/logs.ts";
 import { checkMergeQueue } from "../doctor/merge-queue.ts";
 import { checkProviders } from "../doctor/providers.ts";
+import { checkServe } from "../doctor/serve.ts";
 import { checkStructure } from "../doctor/structure.ts";
 import type { DoctorCategory, DoctorCheck, DoctorCheckFn } from "../doctor/types.ts";
 import { checkVersion } from "../doctor/version.ts";
@@ -39,6 +40,7 @@ const ALL_CHECKS: Array<{ category: DoctorCategory; fn: DoctorCheckFn }> = [
 	{ category: "ecosystem", fn: checkEcosystem },
 	{ category: "providers", fn: checkProviders },
 	{ category: "watchdog", fn: checkWatchdog },
+	{ category: "serve", fn: checkServe },
 ];
 
 /**
@@ -158,10 +160,81 @@ export interface DoctorCommandOptions {
 	checkRunners?: Array<{ category: DoctorCategory; fn: DoctorCheckFn }>;
 }
 
+interface DoctorActionOpts {
+	json?: boolean;
+	verbose?: boolean;
+	category?: string;
+	fix?: boolean;
+}
+
 /**
- * Create the Commander command for `overstory doctor`.
+ * Run the doctor checks. Returns true if any check failed.
+ * Shared by both the Commander action and the programmatic entry point so the
+ * exit-code signal never has to travel through `process.exitCode` (which is
+ * global mutable state and races with other tests in parallel bun test runs).
  */
-export function createDoctorCommand(options?: DoctorCommandOptions): Command {
+async function runDoctorChecks(
+	opts: DoctorActionOpts,
+	checkRunners: Array<{ category: DoctorCategory; fn: DoctorCheckFn }>,
+): Promise<boolean> {
+	const json = opts.json ?? false;
+	const verbose = opts.verbose ?? false;
+	const categoryFilter = opts.category;
+	const fix = opts.fix ?? false;
+
+	if (categoryFilter !== undefined) {
+		const validCategories = ALL_CHECKS.map((c) => c.category);
+		if (!validCategories.includes(categoryFilter as DoctorCategory)) {
+			throw new ValidationError(
+				`Invalid category: ${categoryFilter}. Valid categories: ${validCategories.join(", ")}`,
+				{
+					field: "category",
+					value: categoryFilter,
+				},
+			);
+		}
+	}
+
+	const cwd = process.cwd();
+	const config = await loadConfig(cwd);
+	const overstoryDir = join(config.project.root, ".overstory");
+
+	const checksToRun = categoryFilter
+		? checkRunners.filter((c) => c.category === categoryFilter)
+		: checkRunners;
+
+	let results: DoctorCheck[] = [];
+	for (const { fn } of checksToRun) {
+		const checkResults = await fn(config, overstoryDir);
+		results.push(...checkResults);
+	}
+
+	let fixedItems: string[] | undefined;
+	if (fix) {
+		const applied = await applyFixes(results);
+		if (applied.length > 0) {
+			fixedItems = applied;
+			results = [];
+			for (const { fn } of checksToRun) {
+				const checkResults = await fn(config, overstoryDir);
+				results.push(...checkResults);
+			}
+		}
+	}
+
+	if (json) {
+		printJSON(results, fixedItems);
+	} else {
+		printHumanReadable(results, verbose, checkRunners, fixedItems);
+	}
+
+	return results.some((c) => c.status === "fail");
+}
+
+function buildDoctorCommand(
+	onResult: (hasFailures: boolean) => void,
+	checkRunners: Array<{ category: DoctorCategory; fn: DoctorCheckFn }>,
+): Command {
 	return new Command("doctor")
 		.description("Run health checks on overstory setup")
 		.option("--json", "Output as JSON")
@@ -170,75 +243,22 @@ export function createDoctorCommand(options?: DoctorCommandOptions): Command {
 		.option("--fix", "Attempt to auto-fix issues")
 		.addHelpText(
 			"after",
-			"\nCategories: dependencies, structure, config, databases, consistency, agents, merge, logs, version, ecosystem, providers, watchdog",
+			"\nCategories: dependencies, structure, config, databases, consistency, agents, merge, logs, version, ecosystem, providers, watchdog, serve",
 		)
-		.action(
-			async (opts: { json?: boolean; verbose?: boolean; category?: string; fix?: boolean }) => {
-				const json = opts.json ?? false;
-				const verbose = opts.verbose ?? false;
-				const categoryFilter = opts.category;
-				const fix = opts.fix ?? false;
-
-				// Validate category filter if provided
-				if (categoryFilter !== undefined) {
-					const validCategories = ALL_CHECKS.map((c) => c.category);
-					if (!validCategories.includes(categoryFilter as DoctorCategory)) {
-						throw new ValidationError(
-							`Invalid category: ${categoryFilter}. Valid categories: ${validCategories.join(", ")}`,
-							{
-								field: "category",
-								value: categoryFilter,
-							},
-						);
-					}
-				}
-
-				const cwd = process.cwd();
-				const config = await loadConfig(cwd);
-				const overstoryDir = join(config.project.root, ".overstory");
-
-				// Filter checks by category if specified
-				const allChecks = options?.checkRunners ?? ALL_CHECKS;
-				const checksToRun = categoryFilter
-					? allChecks.filter((c) => c.category === categoryFilter)
-					: allChecks;
-
-				// Run all checks sequentially
-				let results: DoctorCheck[] = [];
-				for (const { fn } of checksToRun) {
-					const checkResults = await fn(config, overstoryDir);
-					results.push(...checkResults);
-				}
-
-				// Apply fixes if requested
-				let fixedItems: string[] | undefined;
-				if (fix) {
-					const applied = await applyFixes(results);
-					if (applied.length > 0) {
-						fixedItems = applied;
-						// Re-run all checks to get fresh results after fixes
-						results = [];
-						for (const { fn } of checksToRun) {
-							const checkResults = await fn(config, overstoryDir);
-							results.push(...checkResults);
-						}
-					}
-				}
-
-				// Output results
-				if (json) {
-					printJSON(results, fixedItems);
-				} else {
-					printHumanReadable(results, verbose, allChecks, fixedItems);
-				}
+		.action(async (opts: DoctorActionOpts) => {
+			onResult(await runDoctorChecks(opts, checkRunners));
+		});
+}
 
-				// Set exit code if any check failed
-				const hasFailures = results.some((c) => c.status === "fail");
-				if (hasFailures) {
-					process.exitCode = 1;
-				}
-			},
-		);
+/**
+ * Create the Commander command for `overstory doctor`.
+ */
+export function createDoctorCommand(options?: DoctorCommandOptions): Command {
+	return buildDoctorCommand((hasFailures) => {
+		if (hasFailures) {
+			process.exitCode = 1;
+		}
+	}, options?.checkRunners ?? ALL_CHECKS);
 }
 
 /**
@@ -250,16 +270,15 @@ export async function doctorCommand(
 	args: string[],
 	options?: DoctorCommandOptions,
 ): Promise<number | undefined> {
-	const cmd = createDoctorCommand(options);
+	let hasFailures = false;
+	const cmd = buildDoctorCommand((result) => {
+		hasFailures = result;
+	}, options?.checkRunners ?? ALL_CHECKS);
 	cmd.exitOverride();
 
-	const prevExitCode = process.exitCode as number | undefined;
-	process.exitCode = undefined;
-
 	try {
 		await cmd.parseAsync(args, { from: "user" });
 	} catch (err: unknown) {
-		process.exitCode = prevExitCode;
 		if (err && typeof err === "object" && "code" in err) {
 			const code = (err as { code: string }).code;
 			if (code === "commander.helpDisplayed" || code === "commander.version") {
@@ -269,7 +288,5 @@ export async function doctorCommand(
 		throw err;
 	}
 
-	const exitCode = process.exitCode === 1 ? 1 : undefined;
-	process.exitCode = prevExitCode;
-	return exitCode;
+	return hasFailures ? 1 : undefined;
 }

package/src/commands/group.test.ts

@@ -20,6 +20,7 @@ import {
 	loadGroups,
 	printGroupProgress,
 	removeFromGroup,
+	resolveGroup,
 } from "./group.ts";
 
 let tempDir: string;
@@ -379,3 +380,96 @@ describe("printGroupProgress", () => {
 		expect(output).toContain("2026-01-15T10:00:00.000Z");
 	});
 });
+
+// -- resolveGroup --
+
+describe("resolveGroup", () => {
+	test("resolves by exact UUID", () => {
+		const a = makeGroup({ id: "group-aaaaaaaa", name: "alpha" });
+		const b = makeGroup({ id: "group-bbbbbbbb", name: "beta" });
+		expect(resolveGroup([a, b], "group-aaaaaaaa")).toBe(a);
+	});
+
+	test("resolves by unique name", () => {
+		const a = makeGroup({ id: "group-aaaaaaaa", name: "alpha" });
+		const b = makeGroup({ id: "group-bbbbbbbb", name: "beta" });
+		expect(resolveGroup([a, b], "beta")).toBe(b);
+	});
+
+	test("ID match wins when name === some-other-group's-id", () => {
+		const a = makeGroup({ id: "group-aaaaaaaa", name: "group-bbbbbbbb" });
+		const b = makeGroup({ id: "group-bbbbbbbb", name: "beta" });
+		expect(resolveGroup([a, b], "group-bbbbbbbb")).toBe(b);
+	});
+
+	test("name match prefers the active group when others are completed", () => {
+		const old = makeGroup({ id: "group-aaaaaaaa", name: "dup", status: "completed" });
+		const live = makeGroup({ id: "group-bbbbbbbb", name: "dup", status: "active" });
+		expect(resolveGroup([old, live], "dup")).toBe(live);
+	});
+
+	test("ambiguous when multiple active groups share a name", () => {
+		const x = makeGroup({ id: "group-aaaaaaaa", name: "dup", status: "active" });
+		const y = makeGroup({ id: "group-bbbbbbbb", name: "dup", status: "active" });
+		expect(() => resolveGroup([x, y], "dup")).toThrow(GroupError);
+		try {
+			resolveGroup([x, y], "dup");
+		} catch (err) {
+			expect(err).toBeInstanceOf(GroupError);
+			const message = (err as GroupError).message;
+			expect(message).toContain("ambiguous");
+			expect(message).toContain("group-aaaaaaaa");
+			expect(message).toContain("group-bbbbbbbb");
+		}
+	});
+
+	test("ambiguous when zero active groups share the name", () => {
+		const x = makeGroup({ id: "group-aaaaaaaa", name: "dup", status: "completed" });
+		const y = makeGroup({ id: "group-bbbbbbbb", name: "dup", status: "completed" });
+		expect(() => resolveGroup([x, y], "dup")).toThrow(GroupError);
+	});
+
+	test("throws not-found for unknown identifier", () => {
+		const a = makeGroup({ id: "group-aaaaaaaa", name: "alpha" });
+		expect(() => resolveGroup([a], "nope")).toThrow(/not found/);
+	});
+});
+
+// -- name-or-id lookup in addToGroup / removeFromGroup --
+
+describe("name-or-id lookup", () => {
+	test("addToGroup resolves by name", async () => {
+		const group = makeGroup({ id: "group-aaaaaaaa", name: "alpha", memberIssueIds: ["i1"] });
+		await writeGroups([group]);
+		const tracker = stubTrackerOk();
+		const updated = await addToGroup(tempDir, "alpha", ["i2"], false, tracker);
+		expect(updated.id).toBe("group-aaaaaaaa");
+		expect(updated.memberIssueIds).toEqual(["i1", "i2"]);
+	});
+
+	test("removeFromGroup resolves by name", async () => {
+		const group = makeGroup({ id: "group-aaaaaaaa", name: "alpha", memberIssueIds: ["i1", "i2"] });
+		await writeGroups([group]);
+		const updated = await removeFromGroup(tempDir, "alpha", ["i2"]);
+		expect(updated.id).toBe("group-aaaaaaaa");
+		expect(updated.memberIssueIds).toEqual(["i1"]);
+	});
+});
+
+function stubTrackerOk(): import("../tracker/types.ts").TrackerClient {
+	return {
+		ready: async () => [],
+		show: async (id: string): Promise<TrackerIssue> => ({
+			id,
+			title: id,
+			status: "open",
+			priority: 2,
+			type: "task",
+		}),
+		create: async () => "stub-id",
+		claim: async () => undefined,
+		close: async () => undefined,
+		list: async () => [],
+		sync: async () => undefined,
+	};
+}