@os-eco/overstory-cli 0.8.0 → 0.8.2

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 () => {

package/src/index.ts

@@ -49,7 +49,7 @@ import { ConfigError, OverstoryError, WorktreeError } from "./errors.ts";
 import { jsonError } from "./json.ts";
 import { brand, chalk, muted, setQuiet } from "./logging/color.ts";
 
-export const VERSION = "0.8.0";
+export const VERSION = "0.8.2";
 
 const rawArgs = process.argv.slice(2);
 

package/src/logging/theme.ts

@@ -66,6 +66,10 @@ const EVENT_LABELS: Record<EventType, EventLabel> = {
 	spawn: { compact: "SPAWN", full: "SPAWN     ", color: color.magenta },
 	error: { compact: "ERROR", full: "ERROR     ", color: color.red },
 	custom: { compact: "CUSTM", full: "CUSTOM    ", color: color.gray },
+	turn_start: { compact: "TURN+", full: "TURN START", color: color.green },
+	turn_end: { compact: "TURN-", full: "TURN END  ", color: color.yellow },
+	progress: { compact: "PROG ", full: "PROGRESS  ", color: color.cyan },
+	result: { compact: "RSULT", full: "RESULT    ", color: color.green },
 };
 
 /** Returns the EventLabel for a given event type. */

package/src/runtimes/connections.test.ts

@@ -0,0 +1,74 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { getConnection, removeConnection, setConnection } from "./connections.ts";
+import type { ConnectionState, RuntimeConnection } from "./types.ts";
+
+/** Minimal RuntimeConnection stub for testing the registry. */
+function makeConn(onClose?: () => void): RuntimeConnection {
+	return {
+		sendPrompt: async (_text: string) => {},
+		followUp: async (_text: string) => {},
+		abort: async () => {},
+		getState: async (): Promise<ConnectionState> => ({ status: "idle" }),
+		close: () => {
+			if (onClose) onClose();
+		},
+	};
+}
+
+describe("connection registry", () => {
+	// Reset registry between tests by removing any entries set during each test.
+	// We track names used so we can clean up without affecting other entries.
+	const usedNames: string[] = [];
+
+	afterEach(() => {
+		for (const name of usedNames.splice(0)) {
+			const conn = getConnection(name);
+			if (conn) {
+				removeConnection(name);
+			}
+		}
+	});
+
+	test("set and get returns the registered connection", () => {
+		const conn = makeConn();
+		usedNames.push("agent-alpha");
+		setConnection("agent-alpha", conn);
+		expect(getConnection("agent-alpha")).toBe(conn);
+	});
+
+	test("get unknown returns undefined", () => {
+		expect(getConnection("does-not-exist-xyz")).toBeUndefined();
+	});
+
+	test("removeConnection calls close() on the connection", () => {
+		let closed = false;
+		const conn = makeConn(() => {
+			closed = true;
+		});
+		usedNames.push("agent-beta");
+		setConnection("agent-beta", conn);
+		removeConnection("agent-beta");
+		expect(closed).toBe(true);
+	});
+
+	test("removeConnection deletes the entry (get returns undefined after)", () => {
+		const conn = makeConn();
+		usedNames.push("agent-gamma");
+		setConnection("agent-gamma", conn);
+		removeConnection("agent-gamma");
+		expect(getConnection("agent-gamma")).toBeUndefined();
+	});
+
+	test("removeConnection on unknown name is a no-op (does not throw)", () => {
+		expect(() => removeConnection("never-registered-xyz")).not.toThrow();
+	});
+
+	test("setConnection overwrites an existing entry", () => {
+		const conn1 = makeConn();
+		const conn2 = makeConn();
+		usedNames.push("agent-delta");
+		setConnection("agent-delta", conn1);
+		setConnection("agent-delta", conn2);
+		expect(getConnection("agent-delta")).toBe(conn2);
+	});
+});

package/src/runtimes/connections.ts

@@ -0,0 +1,34 @@
+/**
+ * Module-level connection registry for active RuntimeConnection instances.
+ *
+ * Tracks RPC connections to headless agent processes (e.g., Sapling).
+ * Keyed by agent name — same namespace as AgentSession.agentName.
+ *
+ * Thread safety: single-threaded Bun runtime; no locking needed.
+ */
+
+import type { RuntimeConnection } from "./types.ts";
+
+const connections = new Map<string, RuntimeConnection>();
+
+/** Retrieve the active connection for a given agent, or undefined if none. */
+export function getConnection(agentName: string): RuntimeConnection | undefined {
+	return connections.get(agentName);
+}
+
+/** Register a connection for a given agent. Overwrites any existing entry. */
+export function setConnection(agentName: string, conn: RuntimeConnection): void {
+	connections.set(agentName, conn);
+}
+
+/**
+ * Remove the connection for a given agent, calling close() first.
+ * Safe to call if no connection exists (no-op).
+ */
+export function removeConnection(agentName: string): void {
+	const conn = connections.get(agentName);
+	if (conn) {
+		conn.close();
+		connections.delete(agentName);
+	}
+}

package/src/runtimes/registry.test.ts

@@ -22,7 +22,7 @@ describe("getRuntime", () => {
 
 	it("throws with a helpful message for an unknown runtime", () => {
 		expect(() => getRuntime("unknown-runtime")).toThrow(
-			'Unknown runtime: "unknown-runtime". Available: claude, codex, pi, copilot, gemini',
+			'Unknown runtime: "unknown-runtime". Available: claude, codex, pi, copilot, gemini, sapling',
 		);
 	});
 

package/src/runtimes/registry.ts

@@ -7,6 +7,7 @@ import { CodexRuntime } from "./codex.ts";
 import { CopilotRuntime } from "./copilot.ts";
 import { GeminiRuntime } from "./gemini.ts";
 import { PiRuntime } from "./pi.ts";
+import { SaplingRuntime } from "./sapling.ts";
 import type { AgentRuntime } from "./types.ts";
 
 /** Registry of config-independent runtime adapters (name → factory). */
@@ -16,6 +17,7 @@ const runtimes = new Map<string, () => AgentRuntime>([
 	["pi", () => new PiRuntime()],
 	["copilot", () => new CopilotRuntime()],
 	["gemini", () => new GeminiRuntime()],
+	["sapling", () => new SaplingRuntime()],
 ]);
 
 /**