@os-eco/overstory-cli 0.7.9 → 0.8.2

package/src/commands/inspect.test.ts

@@ -18,7 +18,7 @@ import { createMetricsStore } from "../metrics/store.ts";
 import { createSessionStore } from "../sessions/store.ts";
 import { cleanupTempDir } from "../test-helpers.ts";
 import type { InsertEvent, SessionMetrics } from "../types.ts";
-import { gatherInspectData, inspectCommand } from "./inspect.ts";
+import { gatherInspectData, inspectCommand, printInspectData } from "./inspect.ts";
 
 /** Helper to create an InsertEvent with sensible defaults. */
 function makeEvent(overrides: Partial<InsertEvent> = {}): InsertEvent {
@@ -565,6 +565,161 @@ describe("inspectCommand", () => {
 		});
 	});
 
+	// === Headless agent support ===
+
+	describe("headless agent support", () => {
+		test("gatherInspectData skips tmux capture for headless agents (empty tmuxSession)", async () => {
+			const overstoryDir = join(tempDir, ".overstory");
+			const sessionsDbPath = join(overstoryDir, "sessions.db");
+			const store = createSessionStore(sessionsDbPath);
+			store.upsert({
+				id: "sess-h1",
+				agentName: "headless-agent",
+				capability: "builder",
+				worktreePath: "/tmp/wt",
+				branchName: "overstory/headless/task-1",
+				taskId: "overstory-h01",
+				tmuxSession: "", // headless
+				state: "working",
+				pid: process.pid,
+				parentAgent: null,
+				depth: 0,
+				runId: null,
+				startedAt: new Date().toISOString(),
+				lastActivity: new Date().toISOString(),
+				escalationLevel: 0,
+				stalledSince: null,
+				transcriptPath: null,
+			});
+			store.close();
+
+			// noTmux=false but tmuxSession="" — should skip tmux capture without error
+			const data = await gatherInspectData(tempDir, "headless-agent", { noTmux: false });
+			// tmuxOutput is null (no tmux) and no events yet → no fallback either
+			expect(data.session.agentName).toBe("headless-agent");
+			expect(data.session.tmuxSession).toBe("");
+			// tmuxOutput may be null (no events) or a string (fallback) — must not throw
+		});
+
+		test("gatherInspectData provides event-based output for headless agents with tool calls", async () => {
+			const overstoryDir = join(tempDir, ".overstory");
+			const sessionsDbPath = join(overstoryDir, "sessions.db");
+			const eventsDbPath = join(overstoryDir, "events.db");
+
+			const store = createSessionStore(sessionsDbPath);
+			store.upsert({
+				id: "sess-h2",
+				agentName: "headless-events",
+				capability: "builder",
+				worktreePath: "/tmp/wt",
+				branchName: "overstory/headless/task-2",
+				taskId: "overstory-h02",
+				tmuxSession: "", // headless
+				state: "working",
+				pid: process.pid,
+				parentAgent: null,
+				depth: 0,
+				runId: null,
+				startedAt: new Date().toISOString(),
+				lastActivity: new Date().toISOString(),
+				escalationLevel: 0,
+				stalledSince: null,
+				transcriptPath: null,
+			});
+			store.close();
+
+			const eventStore = createEventStore(eventsDbPath);
+			eventStore.insert(
+				makeEvent({ agentName: "headless-events", toolName: "Read", toolDurationMs: 50 }),
+			);
+			eventStore.insert(
+				makeEvent({ agentName: "headless-events", toolName: "Edit", toolDurationMs: 100 }),
+			);
+			eventStore.close();
+
+			const data = await gatherInspectData(tempDir, "headless-events", { noTmux: false });
+
+			// Should have fallback output
+			expect(data.tmuxOutput).not.toBeNull();
+			expect(data.tmuxOutput).toContain("Headless agent");
+			expect(data.tmuxOutput).toContain("Read");
+		});
+
+		test("printInspectData shows PID instead of tmux session for headless agents", () => {
+			const data = {
+				session: {
+					id: "sess-h3",
+					agentName: "headless-display",
+					capability: "builder",
+					worktreePath: "/tmp/wt",
+					branchName: "overstory/headless/task-3",
+					taskId: "overstory-h03",
+					tmuxSession: "", // headless
+					state: "working" as const,
+					pid: 99999,
+					parentAgent: null,
+					depth: 0,
+					runId: null,
+					startedAt: new Date().toISOString(),
+					lastActivity: new Date().toISOString(),
+					escalationLevel: 0,
+					stalledSince: null,
+					transcriptPath: null,
+				},
+				timeSinceLastActivity: 5000,
+				recentToolCalls: [],
+				currentFile: null,
+				toolStats: [],
+				tokenUsage: null,
+				tmuxOutput: null,
+			};
+
+			printInspectData(data);
+
+			const out = output();
+			expect(out).toContain("Process: PID");
+			expect(out).toContain("99999");
+			expect(out).toContain("headless");
+			expect(out).not.toContain("Tmux:");
+		});
+
+		test("printInspectData shows Recent Activity header for headless agents with tmuxOutput", () => {
+			const data = {
+				session: {
+					id: "sess-h4",
+					agentName: "headless-activity",
+					capability: "builder",
+					worktreePath: "/tmp/wt",
+					branchName: "overstory/headless/task-4",
+					taskId: "overstory-h04",
+					tmuxSession: "", // headless
+					state: "working" as const,
+					pid: 99998,
+					parentAgent: null,
+					depth: 0,
+					runId: null,
+					startedAt: new Date().toISOString(),
+					lastActivity: new Date().toISOString(),
+					escalationLevel: 0,
+					stalledSince: null,
+					transcriptPath: null,
+				},
+				timeSinceLastActivity: 5000,
+				recentToolCalls: [],
+				currentFile: null,
+				toolStats: [],
+				tokenUsage: null,
+				tmuxOutput: "[Headless agent — showing recent tool events]",
+			};
+
+			printInspectData(data);
+
+			const out = output();
+			expect(out).toContain("Recent Activity (headless)");
+			expect(out).not.toContain("Live Tmux Output");
+		});
+	});
+
 	// === Human-readable output ===
 
 	describe("human-readable output", () => {

package/src/commands/inspect.ts

@@ -193,13 +193,24 @@ export async function gatherInspectData(
 			}
 		}
 
-		// tmux capture
+		// tmux capture (skipped for headless agents where tmuxSession is empty)
 		let tmuxOutput: string | null = null;
 		if (!opts.noTmux && session.tmuxSession) {
 			const lines = opts.tmuxLines ?? 30;
 			tmuxOutput = await captureTmux(session.tmuxSession, lines);
 		}
 
+		// Headless fallback: show recent events as live output when no tmux
+		if (!tmuxOutput && session.tmuxSession === "" && recentToolCalls.length > 0) {
+			const lines: string[] = ["[Headless agent — showing recent tool events]", ""];
+			for (const call of recentToolCalls.slice(0, 15)) {
+				const time = new Date(call.timestamp).toLocaleTimeString();
+				const dur = call.durationMs !== null ? `${call.durationMs}ms` : "pending";
+				lines.push(`  [${time}] ${call.toolName.padEnd(15)} ${dur}`);
+			}
+			tmuxOutput = lines.join("\n");
+		}
+
 		return {
 			session,
 			timeSinceLastActivity,
@@ -233,7 +244,11 @@ export function printInspectData(data: InspectData): void {
 		w(`Parent: ${accent(session.parentAgent)} (depth: ${session.depth})\n`);
 	}
 	w(`Started: ${session.startedAt}\n`);
-	w(`Tmux: ${accent(session.tmuxSession)}\n`);
+	if (session.tmuxSession) {
+		w(`Tmux: ${accent(session.tmuxSession)}\n`);
+	} else if (session.pid !== null) {
+		w(`Process: PID ${accent(String(session.pid))} (headless)\n`);
+	}
 	w("\n");
 
 	// Current file
@@ -287,9 +302,9 @@ export function printInspectData(data: InspectData): void {
 		w("\n");
 	}
 
-	// tmux output
+	// tmux output (or headless fallback)
 	if (data.tmuxOutput) {
-		w("Live Tmux Output\n");
+		w(data.session.tmuxSession ? "Live Tmux Output\n" : "Recent Activity (headless)\n");
 		w(`${separator()}\n`);
 		w(`${data.tmuxOutput}\n`);
 		w(`${separator()}\n`);

package/src/commands/replay.test.ts

@@ -701,6 +701,10 @@ describe("replayCommand", () => {
 				"spawn",
 				"error",
 				"custom",
+				"turn_start",
+				"turn_end",
+				"progress",
+				"result",
 			] as const;
 			for (const eventType of eventTypes) {
 				store.insert(
@@ -724,6 +728,10 @@ describe("replayCommand", () => {
 			expect(out).toContain("SPAWN");
 			expect(out).toContain("ERROR");
 			expect(out).toContain("CUSTOM");
+			expect(out).toContain("TURN START");
+			expect(out).toContain("TURN END");
+			expect(out).toContain("PROGRESS");
+			expect(out).toContain("RESULT");
 		});
 
 		test("long data values are truncated", async () => {

package/src/commands/sling.ts

@@ -18,6 +18,7 @@
  * 14. Return AgentSession
  */
 
+import { mkdirSync } from "node:fs";
 import { mkdir } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { createIdentity, loadIdentity } from "../agents/identity.ts";
@@ -31,6 +32,7 @@ import { printSuccess } from "../logging/color.ts";
 import { createMailClient } from "../mail/client.ts";
 import { createMailStore } from "../mail/store.ts";
 import { createMulchClient } from "../mulch/client.ts";
+import { setConnection } from "../runtimes/connections.ts";
 import { getRuntime } from "../runtimes/registry.ts";
 import { openSessionStore } from "../sessions/compat.ts";
 import { createRunStore } from "../sessions/store.ts";
@@ -38,6 +40,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 { spawnHeadlessAgent } from "../worktree/process.ts";
 import {
 	capturePaneContent,
 	createSession,
@@ -836,142 +839,236 @@ export async function slingCommand(taskId: string, opts: SlingOptions): Promise<
 			}
 		}
 
-		// 11c. Preflight: verify tmux is available before attempting session creation
-		await ensureTmuxAvailable();
+		// 11c. Spawn: headless runtimes bypass tmux entirely; tmux path is unchanged.
+		if (runtime.headless === true && runtime.buildDirectSpawn) {
+			const directEnv = {
+				...runtime.buildEnv(resolvedModel),
+				OVERSTORY_AGENT_NAME: name,
+				OVERSTORY_WORKTREE_PATH: worktreePath,
+			};
+			const argv = runtime.buildDirectSpawn({
+				cwd: worktreePath,
+				env: directEnv,
+				model: resolvedModel.model,
+				instructionPath: runtime.instructionPath,
+			});
+
+			// Create a timestamped log dir for this headless agent session.
+			// Redirecting stdout/stderr to files prevents OS pipe buffer backpressure:
+			// when nobody reads the pipe, the child blocks on write() after ~64 KB and
+			// becomes a zombie. File writes have no such limit.
+			//
+			// Exception: RPC-capable runtimes need a live stdout pipe to receive
+			// JSON-RPC 2.0 responses (getState). In that case stdoutFile is omitted
+			// and the caller consumes the stream via the RuntimeConnection.
+			const hasRpcConnect = typeof runtime.connect === "function";
+			const logTimestamp = new Date().toISOString().replace(/[:.]/g, "-");
+			const agentLogDir = join(overstoryDir, "logs", name, logTimestamp);
+			mkdirSync(agentLogDir, { recursive: true });
+
+			const headlessProc = await spawnHeadlessAgent(argv, {
+				cwd: worktreePath,
+				env: { ...(process.env as Record<string, string>), ...directEnv },
+				stdoutFile: hasRpcConnect ? undefined : join(agentLogDir, "stdout.log"),
+				stderrFile: join(agentLogDir, "stderr.log"),
+			});
+
+			// Wire up RPC connection for runtimes that support it (e.g., Sapling).
+			// The connection is stored in the module-level registry so the watchdog
+			// and other subsystems can call getState() for health checks.
+			if (hasRpcConnect && headlessProc.stdout && runtime.connect) {
+				const connection = runtime.connect({
+					stdin: headlessProc.stdin,
+					stdout: headlessProc.stdout,
+				});
+				setConnection(name, connection);
+			}
 
-		// 12. Create tmux session running claude in interactive mode
-		const tmuxSessionName = `overstory-${config.project.name}-${name}`;
-		const spawnCmd = runtime.buildSpawnCommand({
-			model: resolvedModel.model,
-			permissionMode: "bypass",
-			cwd: worktreePath,
-			env: {
+			// 13. Record session with empty tmuxSession (no tmux pane for headless agents).
+			const session: AgentSession = {
+				id: `session-${Date.now()}-${name}`,
+				agentName: name,
+				capability,
+				worktreePath,
+				branchName,
+				taskId: taskId,
+				tmuxSession: "",
+				state: "booting",
+				pid: headlessProc.pid,
+				parentAgent: parentAgent,
+				depth,
+				runId,
+				startedAt: new Date().toISOString(),
+				lastActivity: new Date().toISOString(),
+				escalationLevel: 0,
+				stalledSince: null,
+				transcriptPath: null,
+			};
+			store.upsert(session);
+
+			const runStore = createRunStore(join(overstoryDir, "sessions.db"));
+			try {
+				runStore.incrementAgentCount(runId);
+			} finally {
+				runStore.close();
+			}
+
+			// 14. Output result (headless)
+			if (opts.json ?? false) {
+				jsonOutput("sling", {
+					agentName: name,
+					capability,
+					taskId,
+					branch: branchName,
+					worktree: worktreePath,
+					tmuxSession: "",
+					pid: headlessProc.pid,
+				});
+			} else {
+				printSuccess("Agent launched (headless)", name);
+				process.stdout.write(`   Task:     ${taskId}\n`);
+				process.stdout.write(`   Branch:   ${branchName}\n`);
+				process.stdout.write(`   Worktree: ${worktreePath}\n`);
+				process.stdout.write(`   PID:      ${headlessProc.pid}\n`);
+			}
+		} else {
+			// 11c. 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 spawnCmd = runtime.buildSpawnCommand({
+				model: resolvedModel.model,
+				permissionMode: "bypass",
+				cwd: worktreePath,
+				env: {
+					...runtime.buildEnv(resolvedModel),
+					OVERSTORY_AGENT_NAME: name,
+					OVERSTORY_WORKTREE_PATH: worktreePath,
+				},
+			});
+			const pid = await createSession(tmuxSessionName, worktreePath, spawnCmd, {
 				...runtime.buildEnv(resolvedModel),
 				OVERSTORY_AGENT_NAME: name,
 				OVERSTORY_WORKTREE_PATH: worktreePath,
-			},
-		});
-		const pid = await createSession(tmuxSessionName, worktreePath, spawnCmd, {
-			...runtime.buildEnv(resolvedModel),
-			OVERSTORY_AGENT_NAME: name,
-			OVERSTORY_WORKTREE_PATH: worktreePath,
-		});
+			});
 
-		// 13. Record session BEFORE sending the beacon so that hook-triggered
-		// updateLastActivity() can find the entry and transition booting->working.
-		// Without this, a race exists: hooks fire before the session is persisted,
-		// leaving the agent stuck in "booting" (overstory-036f).
-		const session: AgentSession = {
-			id: `session-${Date.now()}-${name}`,
-			agentName: name,
-			capability,
-			worktreePath,
-			branchName,
-			taskId: taskId,
-			tmuxSession: tmuxSessionName,
-			state: "booting",
-			pid,
-			parentAgent: parentAgent,
-			depth,
-			runId,
-			startedAt: new Date().toISOString(),
-			lastActivity: new Date().toISOString(),
-			escalationLevel: 0,
-			stalledSince: null,
-			transcriptPath: null,
-		};
+			// 13. Record session BEFORE sending the beacon so that hook-triggered
+			// updateLastActivity() can find the entry and transition booting->working.
+			// Without this, a race exists: hooks fire before the session is persisted,
+			// leaving the agent stuck in "booting" (overstory-036f).
+			const session: AgentSession = {
+				id: `session-${Date.now()}-${name}`,
+				agentName: name,
+				capability,
+				worktreePath,
+				branchName,
+				taskId: taskId,
+				tmuxSession: tmuxSessionName,
+				state: "booting",
+				pid,
+				parentAgent: parentAgent,
+				depth,
+				runId,
+				startedAt: new Date().toISOString(),
+				lastActivity: new Date().toISOString(),
+				escalationLevel: 0,
+				stalledSince: null,
+				transcriptPath: null,
+			};
 
-		store.upsert(session);
+			store.upsert(session);
 
-		// Increment agent count for the run
-		const runStore = createRunStore(join(overstoryDir, "sessions.db"));
-		try {
-			runStore.incrementAgentCount(runId);
-		} finally {
-			runStore.close();
-		}
+			// Increment agent count for the run
+			const runStore = createRunStore(join(overstoryDir, "sessions.db"));
+			try {
+				runStore.incrementAgentCount(runId);
+			} finally {
+				runStore.close();
+			}
 
-		// 13b. Give slow shells time to finish initializing before polling for TUI readiness.
-		const shellDelay = config.runtime?.shellInitDelayMs ?? 0;
-		if (shellDelay > 0) {
-			await Bun.sleep(shellDelay);
-		}
+			// 13b. Give slow shells time to finish initializing before polling for TUI readiness.
+			const shellDelay = config.runtime?.shellInitDelayMs ?? 0;
+			if (shellDelay > 0) {
+				await Bun.sleep(shellDelay);
+			}
 
-		// Wait for Claude Code TUI to render before sending input.
-		// Polling capture-pane is more reliable than a fixed sleep because
-		// TUI init time varies by machine load and model state.
-		await waitForTuiReady(tmuxSessionName, (content) => runtime.detectReady(content));
-		// Buffer for the input handler to attach after initial render
-		await Bun.sleep(1_000);
+			// Wait for Claude Code TUI to render before sending input.
+			// Polling capture-pane is more reliable than a fixed sleep because
+			// TUI init time varies by machine load and model state.
+			await waitForTuiReady(tmuxSessionName, (content) => runtime.detectReady(content));
+			// Buffer for the input handler to attach after initial render
+			await Bun.sleep(1_000);
 
-		const beacon = buildBeacon({
-			agentName: name,
-			capability,
-			taskId,
-			parentAgent,
-			depth,
-			instructionPath: runtime.instructionPath,
-		});
-		await sendKeys(tmuxSessionName, beacon);
-
-		// 13c. Follow-up Enters with increasing delays to ensure submission.
-		// Claude Code's TUI may consume early Enters during late initialization
-		// (overstory-yhv6). An Enter on an empty input line is harmless.
-		for (const delay of [1_000, 2_000, 3_000, 5_000]) {
-			await Bun.sleep(delay);
-			await sendKeys(tmuxSessionName, "");
-		}
+			const beacon = buildBeacon({
+				agentName: name,
+				capability,
+				taskId,
+				parentAgent,
+				depth,
+				instructionPath: runtime.instructionPath,
+			});
+			await sendKeys(tmuxSessionName, beacon);
+
+			// 13c. Follow-up Enters with increasing delays to ensure submission.
+			// Claude Code's TUI may consume early Enters during late initialization
+			// (overstory-yhv6). An Enter on an empty input line is harmless.
+			for (const delay of [1_000, 2_000, 3_000, 5_000]) {
+				await Bun.sleep(delay);
+				await sendKeys(tmuxSessionName, "");
+			}
 
-		// 13d. Verify beacon was received — if pane still shows the welcome
-		// screen (detectReady returns "ready"), resend the beacon. Claude Code's TUI
-		// sometimes consumes the Enter keystroke during late initialization, swallowing
-		// the beacon text entirely (overstory-3271).
-		//
-		// Skipped for runtimes that return false from requiresBeaconVerification().
-		// Pi's TUI idle and processing states are indistinguishable via detectReady
-		// (both show "pi v..." header and the token-usage status bar), so the loop
-		// would incorrectly conclude the beacon was not received and spam duplicate
-		// startup messages.
-		const needsVerification =
-			!runtime.requiresBeaconVerification || runtime.requiresBeaconVerification();
-		if (needsVerification) {
-			const verifyAttempts = 5;
-			for (let v = 0; v < verifyAttempts; v++) {
-				await Bun.sleep(2_000);
-				const paneContent = await capturePaneContent(tmuxSessionName);
-				if (paneContent) {
-					const readyState = runtime.detectReady(paneContent);
-					if (readyState.phase !== "ready") {
-						break; // Agent is processing — beacon was received
+			// 13d. Verify beacon was received — if pane still shows the welcome
+			// screen (detectReady returns "ready"), resend the beacon. Claude Code's TUI
+			// sometimes consumes the Enter keystroke during late initialization, swallowing
+			// the beacon text entirely (overstory-3271).
+			//
+			// Skipped for runtimes that return false from requiresBeaconVerification().
+			// Pi's TUI idle and processing states are indistinguishable via detectReady
+			// (both show "pi v..." header and the token-usage status bar), so the loop
+			// would incorrectly conclude the beacon was not received and spam duplicate
+			// startup messages.
+			const needsVerification =
+				!runtime.requiresBeaconVerification || runtime.requiresBeaconVerification();
+			if (needsVerification) {
+				const verifyAttempts = 5;
+				for (let v = 0; v < verifyAttempts; v++) {
+					await Bun.sleep(2_000);
+					const paneContent = await capturePaneContent(tmuxSessionName);
+					if (paneContent) {
+						const readyState = runtime.detectReady(paneContent);
+						if (readyState.phase !== "ready") {
+							break; // Agent is processing — beacon was received
+						}
 					}
+					// Still at welcome/idle screen — resend beacon
+					await sendKeys(tmuxSessionName, beacon);
+					await Bun.sleep(1_000);
+					await sendKeys(tmuxSessionName, ""); // Follow-up Enter
 				}
-				// Still at welcome/idle screen — resend beacon
-				await sendKeys(tmuxSessionName, beacon);
-				await Bun.sleep(1_000);
-				await sendKeys(tmuxSessionName, ""); // Follow-up Enter
 			}
-		}
-
-		// 14. Output result
-		const output = {
-			agentName: name,
-			capability,
-			taskId,
-			branch: branchName,
-			worktree: worktreePath,
-			tmuxSession: tmuxSessionName,
-			pid,
-		};
 
-		if (opts.json ?? false) {
-			jsonOutput("sling", output);
-		} else {
-			printSuccess("Agent launched", name);
-			process.stdout.write(`   Task:     ${taskId}\n`);
-			process.stdout.write(`   Branch:   ${branchName}\n`);
-			process.stdout.write(`   Worktree: ${worktreePath}\n`);
-			process.stdout.write(`   Tmux:     ${tmuxSessionName}\n`);
-			process.stdout.write(`   PID:      ${pid}\n`);
+			// 14. Output result
+			const output = {
+				agentName: name,
+				capability,
+				taskId,
+				branch: branchName,
+				worktree: worktreePath,
+				tmuxSession: tmuxSessionName,
+				pid,
+			};
+
+			if (opts.json ?? false) {
+				jsonOutput("sling", output);
+			} else {
+				printSuccess("Agent launched", name);
+				process.stdout.write(`   Task:     ${taskId}\n`);
+				process.stdout.write(`   Branch:   ${branchName}\n`);
+				process.stdout.write(`   Worktree: ${worktreePath}\n`);
+				process.stdout.write(`   Tmux:     ${tmuxSessionName}\n`);
+				process.stdout.write(`   PID:      ${pid}\n`);
+			}
 		}
 	} finally {
 		store.close();