@os-eco/overstory-cli 0.8.0 → 0.8.2

package/README.md

@@ -19,6 +19,7 @@ Requires [Bun](https://bun.sh) v1.0+, git, and tmux. At least one supported agen
 - [GitHub Copilot](https://github.com/features/copilot) (`copilot` CLI)
 - [Codex](https://github.com/openai/codex) (`codex` CLI)
 - [Gemini CLI](https://github.com/google-gemini/gemini-cli) (`gemini` CLI)
+- [Sapling](https://github.com/nichochar/sapling) (`sp` CLI)
 
 ```bash
 bun install -g @os-eco/overstory-cli
@@ -181,6 +182,7 @@ Overstory is runtime-agnostic. The `AgentRuntime` interface (`src/runtimes/types
 | Copilot | `copilot` | (none — `--allow-all-tools`) | Active development |
 | Codex | `codex` | OS-level sandbox (Seatbelt/Landlock) | Active development |
 | Gemini | `gemini` | `--sandbox` flag | Active development |
+| Sapling | `sp` | `.sapling/guards.json` | Active development |
 
 ## How It Works
 
@@ -280,7 +282,7 @@ overstory/
     metrics/                      SQLite metrics + pricing + transcript parsing
     doctor/                       Health check modules (11 checks)
     insights/                     Session insight analyzer for auto-expertise
-    runtimes/                     AgentRuntime abstraction (registry + adapters: Claude, Pi, Copilot, Codex, Gemini)
+    runtimes/                     AgentRuntime abstraction (registry + adapters: Claude, Pi, Copilot, Codex, Gemini, Sapling)
     tracker/                      Pluggable task tracker (beads + seeds backends)
     mulch/                        mulch client (programmatic API + CLI wrapper)
     e2e/                          End-to-end lifecycle tests

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@os-eco/overstory-cli",
-	"version": "0.8.0",
+	"version": "0.8.2",
 	"description": "Multi-agent orchestration for AI coding agents — spawn workers in git worktrees via tmux, coordinate through SQLite mail, merge with tiered conflict resolution. Pluggable runtime adapters for Claude Code, Pi, and more.",
 	"author": "Jaymin West",
 	"license": "MIT",

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