@os-eco/overstory-cli 0.8.0 → 0.8.3

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/agents/builder.md

@@ -20,7 +20,7 @@ These are named failures. If you catch yourself doing any of these, stop and cor
 
 ## overlay
 
-Your task-specific context (task ID, file scope, spec path, branch name, parent agent) is in `.claude/CLAUDE.md` in your worktree. That file is generated by `ov sling` and tells you WHAT to work on. This file tells you HOW to work.
+Your task-specific context (task ID, file scope, spec path, branch name, parent agent) is in `{{INSTRUCTION_PATH}}` in your worktree. That file is generated by `ov sling` and tells you WHAT to work on. This file tells you HOW to work.
 
 ## constraints
 
@@ -108,7 +108,7 @@ You are an implementation specialist. Given a spec and a set of files you own, y
 
 ## workflow
 
-1. **Read your overlay** at `.claude/CLAUDE.md` in your worktree. This contains your task ID, spec path, file scope, branch name, and agent name.
+1. **Read your overlay** at `{{INSTRUCTION_PATH}}` in your worktree. This contains your task ID, spec path, file scope, branch name, and agent name.
 2. **Read the task spec** at the path specified in your overlay. Understand what needs to be built.
 3. **Load expertise** via `ml prime [domain]` for domains listed in your overlay. Apply existing patterns and conventions.
 4. **Implement the changes:**

package/agents/lead.md

@@ -43,7 +43,7 @@ These are named failures. If you catch yourself doing any of these, stop and cor
 
 ## overlay
 
-Your task-specific context (task ID, spec path, hierarchy depth, agent name, whether you can spawn) is in `.claude/CLAUDE.md` in your worktree. That file is generated by `ov sling` and tells you WHAT to coordinate. This file tells you HOW to coordinate.
+Your task-specific context (task ID, spec path, hierarchy depth, agent name, whether you can spawn) is in `{{INSTRUCTION_PATH}}` in your worktree. That file is generated by `ov sling` and tells you WHAT to coordinate. This file tells you HOW to coordinate.
 
 ## constraints
 
@@ -160,7 +160,7 @@ Action: Full Scout → Build → Verify pipeline. Spawn scouts for exploration,
 
 Delegate exploration to scouts so you can focus on decomposition and planning.
 
-1. **Read your overlay** at `.claude/CLAUDE.md` in your worktree. This contains your task ID, hierarchy depth, and agent name.
+1. **Read your overlay** at `{{INSTRUCTION_PATH}}` in your worktree. This contains your task ID, hierarchy depth, and agent name.
 2. **Load expertise** via `ml prime [domain]` for relevant domains.
 3. **Search mulch for relevant context** before decomposing. Run `ml search <task keywords>` and review failure patterns, conventions, and decisions. Factor these insights into your specs.
 4. **Load file-specific expertise** if files are known. Use `ml prime --files <file1,file2,...>` to get file-scoped context. Note: if your overlay already includes pre-loaded expertise, review it instead of re-fetching.

package/agents/merger.md

@@ -19,7 +19,7 @@ These are named failures. If you catch yourself doing any of these, stop and cor
 
 ## overlay
 
-Your task-specific context (task ID, branches to merge, target branch, merge order, parent agent) is in `.claude/CLAUDE.md` in your worktree. That file is generated by `overstory sling` and tells you WHAT to merge. This file tells you HOW to merge.
+Your task-specific context (task ID, branches to merge, target branch, merge order, parent agent) is in `{{INSTRUCTION_PATH}}` in your worktree. That file is generated by `overstory sling` and tells you WHAT to merge. This file tells you HOW to merge.
 
 ## constraints
 
@@ -97,7 +97,7 @@ You are a branch integration specialist. When workers complete their tasks on se
 
 ## workflow
 
-1. **Read your overlay** at `.claude/CLAUDE.md` in your worktree. This contains your task ID, the branches to merge, the target branch, and your agent name.
+1. **Read your overlay** at `{{INSTRUCTION_PATH}}` in your worktree. This contains your task ID, the branches to merge, the target branch, and your agent name.
 2. **Read the task spec** at the path specified in your overlay. Understand which branches need merging and in what order.
 3. **Review the branches** before merging:
    - `git log <target>..<branch>` to see what each branch contains.

package/agents/orchestrator.md

@@ -31,7 +31,7 @@ These are named failures. If you catch yourself doing any of these, stop and cor
 
 ## overlay
 
-Your task-specific context (task ID, file scope, spec path, branch name, parent agent) is in `.claude/CLAUDE.md` in your worktree. That file is generated by `ov sling` and tells you WHAT to work on. This file tells you HOW to work.
+Your task-specific context (task ID, file scope, spec path, branch name, parent agent) is in `{{INSTRUCTION_PATH}}` in your worktree. That file is generated by `ov sling` and tells you WHAT to work on. This file tells you HOW to work.
 
 ## constraints
 

package/agents/reviewer.md

@@ -16,7 +16,7 @@ These are named failures. If you catch yourself doing any of these, stop and cor
 
 ## overlay
 
-Your task-specific context (task ID, code to review, branch name, parent agent) is in `.claude/CLAUDE.md` in your worktree. That file is generated by `overstory sling` and tells you WHAT to review. This file tells you HOW to review.
+Your task-specific context (task ID, code to review, branch name, parent agent) is in `{{INSTRUCTION_PATH}}` in your worktree. That file is generated by `overstory sling` and tells you WHAT to review. This file tells you HOW to review.
 
 ## constraints
 
@@ -95,7 +95,7 @@ You are a validation specialist. Given code to review, you check it for correctn
 
 ## workflow
 
-1. **Read your overlay** at `.claude/CLAUDE.md` in your worktree. This contains your task ID, the code or branch to review, and your agent name.
+1. **Read your overlay** at `{{INSTRUCTION_PATH}}` in your worktree. This contains your task ID, the code or branch to review, and your agent name.
 2. **Read the task spec** at the path specified in your overlay. Understand what was supposed to be built.
 3. **Load expertise** via `ml prime [domain]` to understand project conventions and standards.
 4. **Review the code changes:**

package/agents/scout.md

@@ -16,7 +16,7 @@ These are named failures. If you catch yourself doing any of these, stop and cor
 
 ## overlay
 
-Your task-specific context (what to explore, who spawned you, your agent name) is in `.claude/CLAUDE.md` in your worktree. That file is generated by `overstory sling` and tells you WHAT to work on. This file tells you HOW to work.
+Your task-specific context (what to explore, who spawned you, your agent name) is in `{{INSTRUCTION_PATH}}` in your worktree. That file is generated by `overstory sling` and tells you WHAT to work on. This file tells you HOW to work.
 
 ## constraints
 
@@ -97,7 +97,7 @@ You perform reconnaissance. Given a research question, exploration target, or an
 
 ## workflow
 
-1. **Read your overlay** at `.claude/CLAUDE.md` in your worktree. This contains your task assignment, spec path, and agent name.
+1. **Read your overlay** at `{{INSTRUCTION_PATH}}` in your worktree. This contains your task assignment, spec path, and agent name.
 2. **Read the task spec** at the path specified in your overlay.
 3. **Load relevant expertise** via `ml prime [domain]` for domains listed in your overlay.
 4. **Explore systematically:**

package/agents/supervisor.md

@@ -31,7 +31,7 @@ These are named failures. If you catch yourself doing any of these, stop and cor
 
 ## overlay
 
-Unlike the coordinator (which has no overlay), you receive your task-specific context via the overlay CLAUDE.md at `.claude/CLAUDE.md` in your worktree root. This file is generated by `ov supervisor start` (or `ov sling` with `--capability supervisor`) and provides:
+Unlike the coordinator (which has no overlay), you receive your task-specific context via the overlay CLAUDE.md at `{{INSTRUCTION_PATH}}` in your worktree root. This file is generated by `ov supervisor start` (or `ov sling` with `--capability supervisor`) and provides:
 
 - **Agent Name** (`$OVERSTORY_AGENT_NAME`) -- your mail address
 - **Task ID** -- the issue you are assigned to
@@ -163,7 +163,7 @@ Before spawning, check `ov status` to ensure non-overlapping file scope across a
 
 ## workflow
 
-1. **Receive the dispatch.** Your overlay (`.claude/CLAUDE.md`) contains your task ID and spec path. The coordinator sends you a `dispatch` mail with task details.
+1. **Receive the dispatch.** Your overlay (`{{INSTRUCTION_PATH}}`) contains your task ID and spec path. The coordinator sends you a `dispatch` mail with task details.
 2. **Read your task spec** at the path specified in your overlay. Understand the full scope of work assigned to you.
 3. **Load expertise** via `ml prime [domain]` for each relevant domain. Check `{{TRACKER_CLI}} show <task-id>` for task details and dependencies.
 4. **Analyze scope and decompose.** Study the codebase with Read/Glob/Grep to understand what needs to change. Determine:
@@ -418,7 +418,7 @@ You are long-lived within a project. You survive across batches and can recover
 - **Checkpoints** are saved to `.overstory/agents/$OVERSTORY_AGENT_NAME/checkpoint.json` before compaction or handoff. The checkpoint contains: agent name, assigned task ID, active worker IDs, task group ID, session ID, progress summary, and files modified.
 - **On recovery**, reload context by:
   1. Reading your checkpoint: `.overstory/agents/$OVERSTORY_AGENT_NAME/checkpoint.json`
-  2. Reading your overlay: `.claude/CLAUDE.md` (task ID, spec path, depth, parent)
+  2. Reading your overlay: `{{INSTRUCTION_PATH}}` (task ID, spec path, depth, parent)
   3. Checking active group: `ov group status <group-id>`
   4. Checking worker states: `ov status`
   5. Checking unread mail: `ov mail check --agent $OVERSTORY_AGENT_NAME`

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@os-eco/overstory-cli",
-	"version": "0.8.0",
+	"version": "0.8.3",
 	"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/agents/overlay.test.ts

@@ -875,6 +875,48 @@ describe("formatQualityGatesCapabilities", () => {
 	});
 });
 
+describe("INSTRUCTION_PATH placeholder", () => {
+	test("defaults to .claude/CLAUDE.md when instructionPath is not set", async () => {
+		const config = makeConfig({
+			baseDefinition: "Read your overlay at {{INSTRUCTION_PATH}} in your worktree.",
+		});
+		const output = await generateOverlay(config);
+
+		expect(output).toContain("Read your overlay at .claude/CLAUDE.md in your worktree.");
+		expect(output).not.toContain("{{INSTRUCTION_PATH}}");
+	});
+
+	test("uses custom instructionPath when set", async () => {
+		const config = makeConfig({
+			instructionPath: "SAPLING.md",
+			baseDefinition: "Read your overlay at {{INSTRUCTION_PATH}} in your worktree.",
+		});
+		const output = await generateOverlay(config);
+
+		expect(output).toContain("Read your overlay at SAPLING.md in your worktree.");
+		expect(output).not.toContain("{{INSTRUCTION_PATH}}");
+		expect(output).not.toContain(".claude/CLAUDE.md");
+	});
+
+	test("INSTRUCTION_PATH in base definition replaced throughout (multiple occurrences)", async () => {
+		const config = makeConfig({
+			instructionPath: "AGENTS.md",
+			baseDefinition: "Step 1: read {{INSTRUCTION_PATH}}.\nContext is in {{INSTRUCTION_PATH}}.",
+		});
+		const output = await generateOverlay(config);
+
+		expect(output).not.toContain("{{INSTRUCTION_PATH}}");
+		expect(output.split("AGENTS.md").length - 1).toBeGreaterThanOrEqual(2);
+	});
+
+	test("no unreplaced INSTRUCTION_PATH placeholders in final output", async () => {
+		const config = makeConfig({ instructionPath: "SAPLING.md" });
+		const output = await generateOverlay(config);
+
+		expect(output).not.toContain("{{INSTRUCTION_PATH}}");
+	});
+});
+
 describe("quality gate placeholders in base definitions", () => {
 	test("QUALITY_GATE_INLINE in base definition gets replaced", async () => {
 		const config = makeConfig({

package/src/agents/overlay.ts

@@ -320,6 +320,7 @@ export async function generateOverlay(config: OverlayConfig): Promise<string> {
 		"{{QUALITY_GATE_CAPABILITIES}}": formatQualityGatesCapabilities(config.qualityGates),
 		"{{TRACKER_CLI}}": config.trackerCli ?? "sd",
 		"{{TRACKER_NAME}}": config.trackerName ?? "seeds",
+		"{{INSTRUCTION_PATH}}": config.instructionPath ?? ".claude/CLAUDE.md",
 	};
 
 	let result = template;

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