@os-eco/overstory-cli 0.7.9 → 0.8.2

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);
+	});
+});

package/src/commands/stop.ts

@@ -3,7 +3,8 @@
  *
  * Explicitly terminates a running agent by:
  * 1. Looking up the agent session by name
- * 2. Killing its tmux session (if alive)
+ * 2a. For TUI agents: killing its tmux session (if alive)
+ * 2b. For headless agents (tmuxSession === ''): sending SIGTERM to the process tree
  * 3. Marking it as completed in the SessionStore
  * 4. Optionally removing its worktree (--clean-worktree)
  */
@@ -15,7 +16,7 @@ import { jsonOutput } from "../json.ts";
 import { printSuccess, printWarning } from "../logging/color.ts";
 import { openSessionStore } from "../sessions/compat.ts";
 import { removeWorktree } from "../worktree/manager.ts";
-import { isSessionAlive, killSession } from "../worktree/tmux.ts";
+import { isProcessAlive, isSessionAlive, killProcessTree, killSession } from "../worktree/tmux.ts";
 
 export interface StopOptions {
 	force?: boolean;
@@ -36,6 +37,10 @@ export interface StopDeps {
 			options?: { force?: boolean; forceBranch?: boolean },
 		) => Promise<void>;
 	};
+	_process?: {
+		isAlive: (pid: number) => boolean;
+		killTree: (pid: number) => Promise<void>;
+	};
 }
 
 /**
@@ -43,7 +48,7 @@ export interface StopDeps {
  *
  * @param agentName - Name of the agent to stop
  * @param opts - Command options
- * @param deps - Optional dependency injection for testing (tmux, worktree)
+ * @param deps - Optional dependency injection for testing (tmux, worktree, process)
  */
 export async function stopCommand(
 	agentName: string,
@@ -63,6 +68,7 @@ export async function stopCommand(
 
 	const tmux = deps._tmux ?? { isSessionAlive, killSession };
 	const worktree = deps._worktree ?? { remove: removeWorktree };
+	const proc = deps._process ?? { isAlive: isProcessAlive, killTree: killProcessTree };
 
 	const cwd = process.cwd();
 	const config = await loadConfig(cwd);
@@ -84,10 +90,25 @@ export async function stopCommand(
 			throw new AgentError(`Agent "${agentName}" is already zombie (dead)`, { agentName });
 		}
 
-		// Kill tmux session if alive
-		const alive = await tmux.isSessionAlive(session.tmuxSession);
-		if (alive) {
-			await tmux.killSession(session.tmuxSession);
+		const isHeadless = session.tmuxSession === "" && session.pid !== null;
+
+		let tmuxKilled = false;
+		let pidKilled = false;
+
+		if (isHeadless && session.pid !== null) {
+			// Headless agent: kill via process tree instead of tmux
+			const alive = proc.isAlive(session.pid);
+			if (alive) {
+				await proc.killTree(session.pid);
+				pidKilled = true;
+			}
+		} else {
+			// TUI agent: kill via tmux session
+			const alive = await tmux.isSessionAlive(session.tmuxSession);
+			if (alive) {
+				await tmux.killSession(session.tmuxSession);
+				tmuxKilled = true;
+			}
 		}
 
 		// Mark session as completed
@@ -115,16 +136,25 @@ export async function stopCommand(
 				agentName,
 				sessionId: session.id,
 				capability: session.capability,
-				tmuxKilled: alive,
+				tmuxKilled,
+				pidKilled,
 				worktreeRemoved,
 				force,
 			});
 		} else {
 			printSuccess("Agent stopped", agentName);
-			if (alive) {
-				process.stdout.write(`  Tmux session killed: ${session.tmuxSession}\n`);
+			if (isHeadless) {
+				if (pidKilled) {
+					process.stdout.write(`  Process tree killed: PID ${session.pid}\n`);
+				} else {
+					process.stdout.write(`  Process was already dead (PID ${session.pid})\n`);
+				}
 			} else {
-				process.stdout.write(`  Tmux session was already dead\n`);
+				if (tmuxKilled) {
+					process.stdout.write(`  Tmux session killed: ${session.tmuxSession}\n`);
+				} else {
+					process.stdout.write(`  Tmux session was already dead\n`);
+				}
 			}
 			if (cleanWorktree && worktreeRemoved) {
 				process.stdout.write(`  Worktree removed: ${session.worktreePath}\n`);

package/src/commands/trace.test.ts

@@ -639,6 +639,10 @@ describe("traceCommand", () => {
 				"spawn",
 				"error",
 				"custom",
+				"turn_start",
+				"turn_end",
+				"progress",
+				"result",
 			] as const;
 			for (const eventType of eventTypes) {
 				store.insert(
@@ -664,6 +668,10 @@ describe("traceCommand", () => {
 			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 () => {