@os-eco/overstory-cli 0.7.9 → 0.8.2

package/src/commands/coordinator.ts

@@ -21,6 +21,8 @@ import { loadConfig } from "../config.ts";
 import { AgentError, ValidationError } from "../errors.ts";
 import { jsonOutput } from "../json.ts";
 import { printHint, printSuccess, printWarning } from "../logging/color.ts";
+import { createMailClient } from "../mail/client.ts";
+import { createMailStore } from "../mail/store.ts";
 import { getRuntime } from "../runtimes/registry.ts";
 import { openSessionStore } from "../sessions/compat.ts";
 import { createRunStore } from "../sessions/store.ts";
@@ -29,6 +31,7 @@ import type { AgentSession } from "../types.ts";
 import { isProcessRunning } from "../watchdog/health.ts";
 import type { SessionState } from "../worktree/tmux.ts";
 import {
+	capturePaneContent,
 	checkSessionState,
 	createSession,
 	ensureTmuxAvailable,
@@ -37,11 +40,18 @@ import {
 	sendKeys,
 	waitForTuiReady,
 } from "../worktree/tmux.ts";
+import { nudgeAgent } from "./nudge.ts";
 import { isRunningAsRoot } from "./sling.ts";
 
 /** Default coordinator agent name. */
 const COORDINATOR_NAME = "coordinator";
 
+/** Poll interval for the ask subcommand reply loop. */
+const ASK_POLL_INTERVAL_MS = 2_000;
+
+/** Default timeout in seconds for the ask subcommand. */
+const ASK_DEFAULT_TIMEOUT_S = 120;
+
 /**
  * Build the tmux session name for the coordinator.
  * Includes the project name to prevent cross-project collisions (overstory-pcef).
@@ -81,6 +91,15 @@ export interface CoordinatorDeps {
 		stop: () => Promise<boolean>;
 		isRunning: () => Promise<boolean>;
 	};
+	_nudge?: (
+		projectRoot: string,
+		agentName: string,
+		message: string,
+		force: boolean,
+	) => Promise<{ delivered: boolean; reason?: string }>;
+	_capturePaneContent?: (name: string, lines?: number) => Promise<string | null>;
+	/** Override poll interval for ask subcommand (default: ASK_POLL_INTERVAL_MS). Used in tests. */
+	_pollIntervalMs?: number;
 }
 
 /**
@@ -738,6 +757,303 @@ async function statusCoordinator(
 	}
 }
 
+/**
+ * Send a fire-and-forget message to the running coordinator.
+ *
+ * Sends a mail message (from: operator, type: dispatch) and auto-nudges the
+ * coordinator via tmux sendKeys. Replaces the two-step `ov mail send + ov nudge` pattern.
+ */
+async function sendToCoordinator(
+	body: string,
+	opts: { subject: string; json: boolean },
+	deps: CoordinatorDeps = {},
+): Promise<void> {
+	const tmux = deps._tmux ?? {
+		createSession,
+		isSessionAlive,
+		checkSessionState,
+		killSession,
+		sendKeys,
+		waitForTuiReady,
+		ensureTmuxAvailable,
+	};
+	const nudge = deps._nudge ?? nudgeAgent;
+
+	const { subject, json } = opts;
+	const cwd = process.cwd();
+	const config = await loadConfig(cwd);
+	const projectRoot = config.project.root;
+
+	const overstoryDir = join(projectRoot, ".overstory");
+	const { store } = openSessionStore(overstoryDir);
+	try {
+		const session = store.getByName(COORDINATOR_NAME);
+
+		if (
+			!session ||
+			session.capability !== "coordinator" ||
+			session.state === "completed" ||
+			session.state === "zombie"
+		) {
+			throw new AgentError("No active coordinator session found", {
+				agentName: COORDINATOR_NAME,
+			});
+		}
+
+		const alive = await tmux.isSessionAlive(session.tmuxSession);
+		if (!alive) {
+			store.updateState(COORDINATOR_NAME, "zombie");
+			store.updateLastActivity(COORDINATOR_NAME);
+			throw new AgentError(`Coordinator tmux session "${session.tmuxSession}" is not alive`, {
+				agentName: COORDINATOR_NAME,
+			});
+		}
+
+		// Send mail
+		const mailDbPath = join(overstoryDir, "mail.db");
+		const mailStore = createMailStore(mailDbPath);
+		const mailClient = createMailClient(mailStore);
+		let id: string;
+		try {
+			id = mailClient.send({
+				from: "operator",
+				to: COORDINATOR_NAME,
+				subject,
+				body,
+				type: "dispatch",
+				priority: "normal",
+			});
+		} finally {
+			mailClient.close();
+		}
+
+		// Auto-nudge (fire-and-forget)
+		const nudgeMessage = `[DISPATCH] ${subject}: ${body.slice(0, 500)}`;
+		let nudged = false;
+		try {
+			const nudgeResult = await nudge(projectRoot, COORDINATOR_NAME, nudgeMessage, true);
+			nudged = nudgeResult.delivered;
+		} catch {
+			// Nudge is fire-and-forget — silently ignore errors
+		}
+
+		if (json) {
+			jsonOutput("coordinator send", { id, nudged });
+		} else {
+			printSuccess("Sent to coordinator", id);
+		}
+	} finally {
+		store.close();
+	}
+}
+
+/**
+ * Send a synchronous request to the coordinator and wait for a reply.
+ *
+ * Sends a mail message (from: operator, type: dispatch) with a correlationId,
+ * auto-nudges the coordinator via tmux, then polls mail.db for a reply in the
+ * same thread. Prints the reply body (or structured JSON) and exits.
+ * Throws AgentError if no reply arrives before the timeout.
+ */
+export async function askCoordinator(
+	body: string,
+	opts: { subject: string; timeout: number; json: boolean },
+	deps: CoordinatorDeps = {},
+): Promise<void> {
+	const tmux = deps._tmux ?? {
+		createSession,
+		isSessionAlive,
+		checkSessionState,
+		killSession,
+		sendKeys,
+		waitForTuiReady,
+		ensureTmuxAvailable,
+	};
+	const nudge = deps._nudge ?? nudgeAgent;
+	const pollIntervalMs = deps._pollIntervalMs ?? ASK_POLL_INTERVAL_MS;
+
+	const { subject, timeout, json } = opts;
+	const cwd = process.cwd();
+	const config = await loadConfig(cwd);
+	const projectRoot = config.project.root;
+
+	const overstoryDir = join(projectRoot, ".overstory");
+	const { store } = openSessionStore(overstoryDir);
+	try {
+		const session = store.getByName(COORDINATOR_NAME);
+
+		if (
+			!session ||
+			session.capability !== "coordinator" ||
+			session.state === "completed" ||
+			session.state === "zombie"
+		) {
+			throw new AgentError("No active coordinator session found", {
+				agentName: COORDINATOR_NAME,
+			});
+		}
+
+		const alive = await tmux.isSessionAlive(session.tmuxSession);
+		if (!alive) {
+			store.updateState(COORDINATOR_NAME, "zombie");
+			store.updateLastActivity(COORDINATOR_NAME);
+			throw new AgentError(`Coordinator tmux session "${session.tmuxSession}" is not alive`, {
+				agentName: COORDINATOR_NAME,
+			});
+		}
+
+		// Generate correlation ID for tracking this request/response pair
+		const correlationId = crypto.randomUUID();
+
+		// Send mail with correlationId in payload
+		const mailDbPath = join(overstoryDir, "mail.db");
+		const mailStore = createMailStore(mailDbPath);
+		const mailClient = createMailClient(mailStore);
+		let sentId: string;
+		try {
+			sentId = mailClient.send({
+				from: "operator",
+				to: COORDINATOR_NAME,
+				subject,
+				body,
+				type: "dispatch",
+				priority: "normal",
+				payload: JSON.stringify({ correlationId }),
+			});
+		} finally {
+			mailClient.close();
+		}
+
+		// Auto-nudge (fire-and-forget)
+		const nudgeMessage = `[ASK] ${subject}: ${body.slice(0, 500)}`;
+		try {
+			await nudge(projectRoot, COORDINATOR_NAME, nudgeMessage, true);
+		} catch {
+			// Nudge is fire-and-forget — silently ignore errors
+		}
+
+		// Poll for a reply in the same thread
+		const deadline = Date.now() + timeout * 1000;
+		while (Date.now() < deadline) {
+			await Bun.sleep(pollIntervalMs);
+			// Open a fresh store connection each cycle so we see the latest committed writes
+			const pollStore = createMailStore(mailDbPath);
+			let reply: import("../types.ts").MailMessage | undefined;
+			try {
+				const replies = pollStore.getByThread(sentId);
+				reply = replies.find((m) => m.from === COORDINATOR_NAME && m.to === "operator");
+			} finally {
+				pollStore.close();
+			}
+			if (reply) {
+				if (json) {
+					jsonOutput("coordinator ask", {
+						correlationId,
+						sentId,
+						replyId: reply.id,
+						subject: reply.subject,
+						body: reply.body,
+						payload: reply.payload,
+					});
+				} else {
+					process.stdout.write(`${reply.body}\n`);
+				}
+				return;
+			}
+		}
+
+		throw new AgentError(
+			`Timed out after ${timeout}s waiting for coordinator reply (correlationId: ${correlationId})`,
+			{ agentName: COORDINATOR_NAME },
+		);
+	} finally {
+		store.close();
+	}
+}
+
+/**
+ * Show recent coordinator tmux pane content without attaching.
+ *
+ * Wraps capturePaneContent() from tmux.ts. Supports --follow for continuous polling.
+ */
+async function outputCoordinator(
+	opts: { follow: boolean; lines: number; interval: number; json: boolean },
+	deps: CoordinatorDeps = {},
+): Promise<void> {
+	const tmux = deps._tmux ?? {
+		createSession,
+		isSessionAlive,
+		checkSessionState,
+		killSession,
+		sendKeys,
+		waitForTuiReady,
+		ensureTmuxAvailable,
+	};
+	const capturePane = deps._capturePaneContent ?? capturePaneContent;
+
+	const { follow, lines, interval, json } = opts;
+	const cwd = process.cwd();
+	const config = await loadConfig(cwd);
+	const projectRoot = config.project.root;
+
+	const overstoryDir = join(projectRoot, ".overstory");
+	const { store } = openSessionStore(overstoryDir);
+	try {
+		const session = store.getByName(COORDINATOR_NAME);
+
+		if (
+			!session ||
+			session.capability !== "coordinator" ||
+			session.state === "completed" ||
+			session.state === "zombie"
+		) {
+			throw new AgentError("No active coordinator session found", {
+				agentName: COORDINATOR_NAME,
+			});
+		}
+
+		const alive = await tmux.isSessionAlive(session.tmuxSession);
+		if (!alive) {
+			store.updateState(COORDINATOR_NAME, "zombie");
+			store.updateLastActivity(COORDINATOR_NAME);
+			throw new AgentError(`Coordinator tmux session "${session.tmuxSession}" is not alive`, {
+				agentName: COORDINATOR_NAME,
+			});
+		}
+
+		const tmuxSession = session.tmuxSession;
+
+		if (follow) {
+			// Set up SIGINT handler for clean exit
+			let running = true;
+			process.once("SIGINT", () => {
+				running = false;
+			});
+
+			while (running) {
+				const content = await capturePane(tmuxSession, lines);
+				if (json) {
+					jsonOutput("coordinator output", { content, lines });
+				} else {
+					process.stdout.write(content ?? "");
+				}
+				if (running) {
+					await Bun.sleep(interval);
+				}
+			}
+		} else {
+			const content = await capturePane(tmuxSession, lines);
+			if (json) {
+				jsonOutput("coordinator output", { content, lines });
+			} else {
+				process.stdout.write(content ?? "");
+			}
+		}
+	} finally {
+		store.close();
+	}
+}
+
 /**
  * Create the Commander command for `ov coordinator`.
  */
@@ -784,6 +1100,56 @@ export function createCoordinatorCommand(deps: CoordinatorDeps = {}): Command {
 			await statusCoordinator({ json: opts.json ?? false }, deps);
 		});
 
+	cmd
+		.command("send")
+		.description("Send a message to the coordinator (fire-and-forget)")
+		.requiredOption("--body <text>", "Message body")
+		.option("--subject <text>", "Message subject", "operator dispatch")
+		.option("--json", "Output as JSON")
+		.action(async (opts: { body: string; subject: string; json?: boolean }) => {
+			await sendToCoordinator(opts.body, { subject: opts.subject, json: opts.json ?? false }, deps);
+		});
+
+	cmd
+		.command("ask")
+		.description("Send a request to the coordinator and wait for a reply")
+		.requiredOption("--body <text>", "Message body")
+		.option("--subject <text>", "Message subject", "operator request")
+		.option("--timeout <seconds>", "Timeout in seconds", String(ASK_DEFAULT_TIMEOUT_S))
+		.option("--json", "Output as JSON")
+		.action(async (opts: { body: string; subject: string; timeout?: string; json?: boolean }) => {
+			await askCoordinator(
+				opts.body,
+				{
+					subject: opts.subject,
+					timeout: Number.parseInt(opts.timeout ?? String(ASK_DEFAULT_TIMEOUT_S), 10),
+					json: opts.json ?? false,
+				},
+				deps,
+			);
+		});
+
+	cmd
+		.command("output")
+		.description("Show recent coordinator output (tmux pane content)")
+		.option("--follow, -f", "Continuously poll for new output")
+		.option("--lines <n>", "Number of lines to capture", "50")
+		.option("--interval <ms>", "Poll interval in milliseconds (with --follow)", "2000")
+		.option("--json", "Output as JSON")
+		.action(
+			async (opts: { follow?: boolean; lines?: string; interval?: string; json?: boolean }) => {
+				await outputCoordinator(
+					{
+						follow: opts.follow ?? false,
+						lines: Number.parseInt(opts.lines ?? "50", 10),
+						interval: Number.parseInt(opts.interval ?? "2000", 10),
+						json: opts.json ?? false,
+					},
+					deps,
+				);
+			},
+		);
+
 	return cmd;
 }
 

package/src/commands/dashboard.test.ts

@@ -409,6 +409,92 @@ describe("renderAgentPanel", () => {
 		// dimBox.vertical is a dimmed ANSI string — present in output
 		expect(out).toContain(dimBox.vertical);
 	});
+
+	test("renders Live column header (not Tmux)", () => {
+		const data = makeDashboardData({});
+		const out = renderAgentPanel(data, 100, 12, 3);
+		expect(out).toContain("Live");
+		expect(out).not.toContain("Tmux");
+	});
+
+	test("shows green dot for headless agent with alive PID", () => {
+		const alivePid = process.pid; // own PID — guaranteed alive
+		const data = {
+			...makeDashboardData({}),
+			status: {
+				currentRunId: null,
+				agents: [
+					{
+						id: "sess-h1",
+						agentName: "headless-worker",
+						capability: "builder",
+						worktreePath: "/tmp/wt/headless",
+						branchName: "overstory/headless/task-1",
+						taskId: "task-h1",
+						tmuxSession: "", // headless
+						state: "working" as const,
+						pid: alivePid,
+						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: [], // no tmux sessions
+				unreadMailCount: 0,
+				mergeQueueCount: 0,
+				recentMetricsCount: 0,
+			},
+		};
+		const out = renderAgentPanel(data, 100, 12, 3);
+		// Green ">" for alive headless agent
+		expect(out).toContain(">");
+		expect(out).toContain("headless-worker");
+	});
+
+	test("shows red dot for headless agent with dead PID", () => {
+		const deadPid = 2_147_483_647;
+		const data = {
+			...makeDashboardData({}),
+			status: {
+				currentRunId: null,
+				agents: [
+					{
+						id: "sess-h2",
+						agentName: "dead-headless", // short enough to not be truncated
+						capability: "builder",
+						worktreePath: "/tmp/wt/dead-headless",
+						branchName: "overstory/dead-headless/task-2",
+						taskId: "task-h2",
+						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: [],
+				unreadMailCount: 0,
+				mergeQueueCount: 0,
+				recentMetricsCount: 0,
+			},
+		};
+		const out = renderAgentPanel(data, 100, 12, 3);
+		expect(out).toContain("x");
+		expect(out).toContain("dead-headless");
+	});
 });
 
 describe("openDashboardStores", () => {

package/src/commands/dashboard.ts

@@ -42,6 +42,7 @@ import { createTrackerClient, resolveBackend } from "../tracker/factory.ts";
 import type { TrackerIssue } from "../tracker/types.ts";
 import type { EventStore, MailMessage, StoredEvent } from "../types.ts";
 import { evaluateHealth } from "../watchdog/health.ts";
+import { isProcessAlive } from "../worktree/tmux.ts";
 import { getCachedTmuxSessions, getCachedWorktrees, type StatusData } from "./status.ts";
 
 const pkgPath = resolve(import.meta.dir, "../../package.json");
@@ -555,7 +556,7 @@ export function renderAgentPanel(
 	output += `${CURSOR.cursorTo(startRow, 1)}${headerLine}${headerPadding}${dimBox.vertical}\n`;
 
 	// Column headers
-	const colStr = `${dimBox.vertical} St Name            Capability    State      Task ID          Duration  Tmux `;
+	const colStr = `${dimBox.vertical} St Name            Capability    State      Task ID          Duration  Live `;
 	const colPadding = " ".repeat(
 		Math.max(0, leftWidth - visibleLength(colStr) - visibleLength(dimBox.vertical)),
 	);
@@ -595,10 +596,13 @@ export function renderAgentPanel(
 				: now;
 		const duration = formatDuration(endTime - new Date(agent.startedAt).getTime());
 		const durationPadded = pad(duration, 9);
-		const tmuxAlive = data.status.tmuxSessions.some((s) => s.name === agent.tmuxSession);
-		const tmuxDot = tmuxAlive ? color.green(">") : color.red("x");
+		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 aliveDot = alive ? color.green(">") : color.red("x");
 
-		const lineContent = `${dimBox.vertical} ${stateColorFn(icon)}  ${name} ${capability} ${stateColorFn(state)} ${taskId} ${durationPadded} ${tmuxDot}    `;
+		const lineContent = `${dimBox.vertical} ${stateColorFn(icon)}  ${name} ${capability} ${stateColorFn(state)} ${taskId} ${durationPadded} ${aliveDot}    `;
 		const linePadding = " ".repeat(
 			Math.max(0, leftWidth - visibleLength(lineContent) - visibleLength(dimBox.vertical)),
 		);

package/src/commands/feed.test.ts

@@ -469,6 +469,10 @@ describe("feedCommand", () => {
 				"spawn",
 				"error",
 				"custom",
+				"turn_start",
+				"turn_end",
+				"progress",
+				"result",
 			] as const;
 			for (const eventType of eventTypes) {
 				store.insert(
@@ -494,6 +498,10 @@ describe("feedCommand", () => {
 			expect(out).toContain("SPAWN");
 			expect(out).toContain("ERROR");
 			expect(out).toContain("CUSTM");
+			expect(out).toContain("TURN+");
+			expect(out).toContain("TURN-");
+			expect(out).toContain("PROG ");
+			expect(out).toContain("RSULT");
 		});
 	});
 

package/src/commands/init.test.ts

@@ -26,6 +26,7 @@ const AGENT_DEF_FILES = [
 	"merger.md",
 	"coordinator.md",
 	"monitor.md",
+	"orchestrator.md",
 ];
 
 /** Resolve the source agents directory (same logic as init.ts). */
@@ -52,7 +53,7 @@ describe("initCommand: agent-defs deployment", () => {
 		await cleanupTempDir(tempDir);
 	});
 
-	test("creates .overstory/agent-defs/ with all 7 agent definition files (supervisor deprecated)", async () => {
+	test("creates .overstory/agent-defs/ with all 8 agent definition files (supervisor deprecated)", async () => {
 		await initCommand({ _spawner: noopSpawner });
 
 		const agentDefsDir = join(tempDir, ".overstory", "agent-defs");

package/src/commands/init.ts

@@ -324,7 +324,7 @@ function formatYamlValue(value: unknown): string {
 /**
  * Build the starter agent manifest.
  */
-function buildAgentManifest(): AgentManifest {
+export function buildAgentManifest(): AgentManifest {
 	const agents: AgentManifest["agents"] = {
 		scout: {
 			file: "scout.md",
@@ -407,7 +407,7 @@ function buildAgentManifest(): AgentManifest {
  * {{AGENT_NAME}} placeholders and space indentation). Uses tab indentation
  * to match Biome formatting rules.
  */
-function buildHooksJson(): string {
+export function buildHooksJson(): string {
 	// Tool name extraction: reads hook stdin JSON and extracts tool_name field.
 	// Claude Code sends {"tool_name":"Bash","tool_input":{...}} on stdin for
 	// PreToolUse/PostToolUse hooks.