@os-eco/overstory-cli 0.8.0 → 0.8.2

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();

package/src/commands/status.test.ts

@@ -349,6 +349,83 @@ describe("run scoping", () => {
 	});
 });
 
+describe("headless agent alive markers", () => {
+	let chunks: string[];
+	let originalWrite: typeof process.stdout.write;
+
+	beforeEach(() => {
+		chunks = [];
+		originalWrite = process.stdout.write;
+		process.stdout.write = ((chunk: string) => {
+			chunks.push(chunk);
+			return true;
+		}) as typeof process.stdout.write;
+	});
+
+	afterEach(() => {
+		process.stdout.write = originalWrite;
+	});
+
+	function output(): string {
+		return chunks.join("");
+	}
+
+	test("printStatus shows green marker for headless agent with alive PID", () => {
+		// Use own process PID — guaranteed alive
+		const alivePid = process.pid;
+		const agent = makeAgent({
+			agentName: "headless-builder",
+			tmuxSession: "", // headless: no tmux
+			pid: alivePid,
+			state: "working",
+		});
+		const data = makeStatusData({
+			agents: [agent],
+			tmuxSessions: [], // no tmux sessions
+		});
+		printStatus(data);
+		const out = output();
+		// Green marker is ">" — check it appears in the output
+		expect(out).toContain("headless-builder");
+		expect(out).toContain(">");
+	});
+
+	test("printStatus shows red marker for headless agent with dead PID", () => {
+		const deadPid = 2_147_483_647; // max int, virtually guaranteed non-existent
+		const agent = makeAgent({
+			agentName: "dead-headless-builder",
+			tmuxSession: "", // headless: no tmux
+			pid: deadPid,
+			state: "working",
+		});
+		const data = makeStatusData({
+			agents: [agent],
+			tmuxSessions: [],
+		});
+		printStatus(data);
+		const out = output();
+		expect(out).toContain("dead-headless-builder");
+		expect(out).toContain("x");
+	});
+
+	test("printStatus uses tmux check (not PID) for tmux-based agents", () => {
+		const agent = makeAgent({
+			agentName: "tmux-builder",
+			tmuxSession: "overstory-test-builder",
+			pid: process.pid, // alive PID, but should use tmux check
+			state: "working",
+		});
+		// tmuxSessions empty → tmux dead → red marker
+		const data = makeStatusData({
+			agents: [agent],
+			tmuxSessions: [],
+		});
+		printStatus(data);
+		const out = output();
+		expect(out).toContain("x");
+	});
+});
+
 describe("--watch deprecation", () => {
 	test("help text marks --watch as deprecated", async () => {
 		const chunks: string[] = [];

package/src/commands/status.ts

@@ -20,7 +20,7 @@ import { openSessionStore } from "../sessions/compat.ts";
 import type { AgentSession } from "../types.ts";
 import { evaluateHealth } from "../watchdog/health.ts";
 import { listWorktrees } from "../worktree/manager.ts";
-import { listSessions } from "../worktree/tmux.ts";
+import { isProcessAlive, listSessions } from "../worktree/tmux.ts";
 
 // ---------------------------------------------------------------------------
 // Subprocess result cache (TTL-based, module-level)
@@ -260,8 +260,11 @@ export function printStatus(data: StatusData): void {
 					? new Date(agent.lastActivity).getTime()
 					: now;
 			const duration = formatDuration(endTime - new Date(agent.startedAt).getTime());
-			const tmuxAlive = tmuxSessionNames.has(agent.tmuxSession);
-			const aliveMarker = tmuxAlive ? color.green(">") : color.red("x");
+			const isHeadless = agent.tmuxSession === "" && agent.pid !== null;
+			const alive = isHeadless
+				? agent.pid !== null && isProcessAlive(agent.pid)
+				: tmuxSessionNames.has(agent.tmuxSession);
+			const aliveMarker = alive ? color.green(">") : color.red("x");
 			w(`   ${aliveMarker} ${accent(agent.agentName)} [${agent.capability}] `);
 			w(`${agent.state} | ${accent(agent.taskId)} | ${duration}\n`);
 

package/src/commands/stop.test.ts

@@ -20,6 +20,38 @@ import { cleanupTempDir, createTempGitRepo } from "../test-helpers.ts";
 import type { AgentSession } from "../types.ts";
 import { type StopDeps, stopCommand } from "./stop.ts";
 
+// --- Fake Process (for headless agents) ---
+
+/** Track calls to fake process for assertions. */
+interface ProcessCallTracker {
+	isAlive: Array<{ pid: number; result: boolean }>;
+	killTree: Array<{ pid: number }>;
+}
+
+/** Build a fake process DI object with configurable PID liveness. */
+function makeFakeProcess(pidAliveMap: Record<number, boolean> = {}): {
+	proc: NonNullable<StopDeps["_process"]>;
+	calls: ProcessCallTracker;
+} {
+	const calls: ProcessCallTracker = {
+		isAlive: [],
+		killTree: [],
+	};
+
+	const proc: NonNullable<StopDeps["_process"]> = {
+		isAlive: (pid: number): boolean => {
+			const alive = pidAliveMap[pid] ?? false;
+			calls.isAlive.push({ pid, result: alive });
+			return alive;
+		},
+		killTree: async (pid: number): Promise<void> => {
+			calls.killTree.push({ pid });
+		},
+	};
+
+	return { proc, calls };
+}
+
 // --- Fake Tmux ---
 
 /** Track calls to fake tmux for assertions. */
@@ -405,3 +437,105 @@ describe("stopCommand --clean-worktree", () => {
 		expect(parsed.worktreeRemoved).toBe(false);
 	});
 });
+
+describe("stopCommand headless agents", () => {
+	const HEADLESS_PID = 99999;
+
+	function makeHeadlessSession(overrides: Partial<AgentSession> = {}): AgentSession {
+		return makeAgentSession({
+			tmuxSession: "",
+			pid: HEADLESS_PID,
+			...overrides,
+		});
+	}
+
+	function makeHeadlessDeps(
+		pidAliveMap: Record<number, boolean> = {},
+		worktreeConfig?: { shouldFail?: boolean },
+	): {
+		deps: StopDeps;
+		tmuxCalls: TmuxCallTracker;
+		procCalls: ProcessCallTracker;
+		worktreeCalls: WorktreeCallTracker;
+	} {
+		const { tmux, calls: tmuxCalls } = makeFakeTmux({});
+		const { proc, calls: procCalls } = makeFakeProcess(pidAliveMap);
+		const { worktree, calls: worktreeCalls } = makeFakeWorktree(worktreeConfig?.shouldFail);
+		return {
+			deps: { _tmux: tmux, _worktree: worktree, _process: proc },
+			tmuxCalls,
+			procCalls,
+			worktreeCalls,
+		};
+	}
+
+	test("stops headless agent by killing process tree (no tmux interaction)", async () => {
+		const session = makeHeadlessSession({ state: "working" });
+		saveSessionsToDb([session]);
+
+		const { deps, tmuxCalls, procCalls } = makeHeadlessDeps({ [HEADLESS_PID]: true });
+		const output = await captureStdout(() => stopCommand("my-builder", {}, deps));
+
+		// PID was killed
+		expect(procCalls.killTree).toHaveLength(1);
+		expect(procCalls.killTree[0]?.pid).toBe(HEADLESS_PID);
+		// Tmux was NOT touched
+		expect(tmuxCalls.isSessionAlive).toHaveLength(0);
+		expect(tmuxCalls.killSession).toHaveLength(0);
+
+		expect(output).toContain("Agent stopped");
+		expect(output).toContain("Process tree killed");
+		expect(output).toContain(String(HEADLESS_PID));
+
+		const { store } = openSessionStore(overstoryDir);
+		const updated = store.getByName("my-builder");
+		store.close();
+		expect(updated?.state).toBe("completed");
+	});
+
+	test("handles headless agent with already-dead PID gracefully", async () => {
+		const session = makeHeadlessSession({ state: "working" });
+		saveSessionsToDb([session]);
+
+		// PID is NOT alive
+		const { deps, procCalls } = makeHeadlessDeps({ [HEADLESS_PID]: false });
+		const output = await captureStdout(() => stopCommand("my-builder", {}, deps));
+
+		expect(procCalls.killTree).toHaveLength(0);
+		expect(output).toContain("Agent stopped");
+		expect(output).toContain("Process was already dead");
+
+		const { store } = openSessionStore(overstoryDir);
+		const updated = store.getByName("my-builder");
+		store.close();
+		expect(updated?.state).toBe("completed");
+	});
+
+	test("--json output includes pidKilled for headless agent", async () => {
+		const session = makeHeadlessSession({ state: "working" });
+		saveSessionsToDb([session]);
+
+		const { deps } = makeHeadlessDeps({ [HEADLESS_PID]: true });
+		const output = await captureStdout(() => stopCommand("my-builder", { json: true }, deps));
+
+		const parsed = JSON.parse(output.trim()) as Record<string, unknown>;
+		expect(parsed.success).toBe(true);
+		expect(parsed.stopped).toBe(true);
+		expect(parsed.pidKilled).toBe(true);
+		expect(parsed.tmuxKilled).toBe(false);
+		expect(parsed.agentName).toBe("my-builder");
+	});
+
+	test("--clean-worktree works for headless agent", async () => {
+		const session = makeHeadlessSession({ state: "working" });
+		saveSessionsToDb([session]);
+
+		const { deps, worktreeCalls } = makeHeadlessDeps({ [HEADLESS_PID]: true });
+		const output = await captureStdout(() =>
+			stopCommand("my-builder", { cleanWorktree: true }, deps),
+		);
+
+		expect(output).toContain(`Worktree removed: ${session.worktreePath}`);
+		expect(worktreeCalls.remove).toHaveLength(1);
+	});
+});