@os-eco/overstory-cli 0.9.3 → 0.10.3

package/src/watchdog/health.test.ts

@@ -103,6 +103,67 @@ describe("evaluateHealth", () => {
 		expect(check.reconciliationNote).toBeNull();
 	});
 
+	// --- ZFC Rule 1 fallback: tmux dead + stale lastActivity → completed ---
+
+	test("ZFC fallback: tmux dead + stale lastActivity (working) → complete (missed signal)", () => {
+		const staleActivity = new Date(Date.now() - 60_000).toISOString();
+		const session = makeSession({ state: "working", lastActivity: staleActivity });
+		const check = evaluateHealth(session, false, THRESHOLDS);
+
+		expect(check.state).toBe("completed");
+		expect(check.action).toBe("complete");
+		expect(check.tmuxAlive).toBe(false);
+		expect(check.processAlive).toBe(false);
+		expect(check.reconciliationNote).toContain("missed session-end signal");
+	});
+
+	test("ZFC fallback: tmux dead + stale lastActivity (stalled) → complete (missed signal)", () => {
+		const staleActivity = new Date(Date.now() - 90_000).toISOString();
+		const session = makeSession({ state: "stalled", lastActivity: staleActivity });
+		const check = evaluateHealth(session, false, THRESHOLDS);
+
+		expect(check.state).toBe("completed");
+		expect(check.action).toBe("complete");
+	});
+
+	test("ZFC: tmux dead + recent lastActivity → still zombie (true crash)", () => {
+		const recentActivity = new Date(Date.now() - 1_000).toISOString();
+		const session = makeSession({ state: "working", lastActivity: recentActivity });
+		const check = evaluateHealth(session, false, THRESHOLDS);
+
+		expect(check.state).toBe("zombie");
+		expect(check.action).toBe("terminate");
+	});
+
+	test("ZFC fallback (headless): pid dead + stale lastActivity → complete", () => {
+		const staleActivity = new Date(Date.now() - 60_000).toISOString();
+		const session = makeSession({
+			state: "working",
+			tmuxSession: "",
+			pid: DEAD_PID,
+			lastActivity: staleActivity,
+		});
+		const check = evaluateHealth(session, false, THRESHOLDS);
+
+		expect(check.state).toBe("completed");
+		expect(check.action).toBe("complete");
+		expect(check.reconciliationNote).toContain("missed session-end signal");
+	});
+
+	test("ZFC (headless): pid dead + recent lastActivity → still zombie", () => {
+		const recentActivity = new Date(Date.now() - 1_000).toISOString();
+		const session = makeSession({
+			state: "working",
+			tmuxSession: "",
+			pid: DEAD_PID,
+			lastActivity: recentActivity,
+		});
+		const check = evaluateHealth(session, false, THRESHOLDS);
+
+		expect(check.state).toBe("zombie");
+		expect(check.action).toBe("terminate");
+	});
+
 	// --- ZFC Rule 2: tmux alive + sessions.json says zombie → investigate ---
 
 	test("ZFC: tmux alive + sessions.json says zombie → investigate (don't auto-kill)", () => {
@@ -432,6 +493,102 @@ describe("headless agents (tmuxSession empty, PID-based lifecycle)", () => {
 	});
 });
 
+// === Spawn-per-turn workers (tmuxSession === '' && pid === null) ===
+
+describe("spawn-per-turn workers (overstory-7a34)", () => {
+	// Spawn-per-turn workers (builder/scout/reviewer/lead/merger under the
+	// headless default) have no persistent process between turns. The previous
+	// "headless" branch only matched pid !== null, so these sessions fell into
+	// the TUI/tmux path where tmuxAlive=false → ZFC Rule 1 → zombie within
+	// seconds of sling, despite being actively executing tools (overstory-7a34).
+
+	test("freshly slung spawn-per-turn lead (booting, no pid, no tmux) → working", () => {
+		const session = makeSession({
+			tmuxSession: "",
+			pid: null,
+			capability: "lead",
+			state: "booting",
+			lastActivity: new Date().toISOString(),
+		});
+		const check = evaluateHealth(session, false, THRESHOLDS);
+
+		expect(check.state).toBe("working");
+		expect(check.action).toBe("none");
+		expect(check.reconciliationNote).toBeNull();
+	});
+
+	test("active spawn-per-turn worker (working, recent activity) → stays working", () => {
+		const session = makeSession({
+			tmuxSession: "",
+			pid: null,
+			capability: "builder",
+			state: "working",
+			lastActivity: new Date(Date.now() - 5_000).toISOString(),
+		});
+		const check = evaluateHealth(session, false, THRESHOLDS);
+
+		expect(check.state).toBe("working");
+		expect(check.action).toBe("none");
+	});
+
+	test("spawn-per-turn worker between turns (state working, very recent) → working, NOT zombie", () => {
+		// Repro: ov sling --capability lead any-task; within ~30s ov dashboard
+		// previously showed state='zombie' while ov feed showed live tool calls.
+		const session = makeSession({
+			tmuxSession: "",
+			pid: null,
+			capability: "lead",
+			state: "working",
+			lastActivity: new Date().toISOString(),
+		});
+		const check = evaluateHealth(session, false, THRESHOLDS);
+
+		expect(check.state).toBe("working");
+		expect(check.action).toBe("none");
+	});
+
+	test("spawn-per-turn worker with stale activity → stalled", () => {
+		const session = makeSession({
+			tmuxSession: "",
+			pid: null,
+			capability: "builder",
+			state: "working",
+			lastActivity: new Date(Date.now() - 60_000).toISOString(),
+		});
+		const check = evaluateHealth(session, false, THRESHOLDS);
+
+		expect(check.state).toBe("stalled");
+		expect(check.action).toBe("escalate");
+	});
+
+	test("spawn-per-turn worker with zombie-level staleness → zombie, terminate", () => {
+		const session = makeSession({
+			tmuxSession: "",
+			pid: null,
+			capability: "builder",
+			state: "working",
+			lastActivity: new Date(Date.now() - 200_000).toISOString(),
+		});
+		const check = evaluateHealth(session, false, THRESHOLDS);
+
+		expect(check.state).toBe("zombie");
+		expect(check.action).toBe("terminate");
+	});
+
+	test("spawn-per-turn worker that already completed → skips monitoring", () => {
+		const session = makeSession({
+			tmuxSession: "",
+			pid: null,
+			capability: "builder",
+			state: "completed",
+		});
+		const check = evaluateHealth(session, false, THRESHOLDS);
+
+		expect(check.state).toBe("completed");
+		expect(check.action).toBe("none");
+	});
+});
+
 // === transitionState ===
 
 describe("transitionState", () => {

package/src/watchdog/health.ts

@@ -30,18 +30,9 @@
  * table are always up-to-date because they reflect real kernel state.
  */
 
+import { isPersistentCapability } from "../agents/capabilities.ts";
 import type { AgentSession, AgentState, HealthCheck } from "../types.ts";
 
-/**
- * Agent capabilities that run as persistent interactive sessions.
- * These agents are expected to have long idle periods (e.g. coordinator waiting
- * for worker mail) and should NOT be flagged stale/zombie based on lastActivity.
- * Only tmux/pid liveness checks apply to them.
- *
- * Shared concept with src/commands/log.ts:PERSISTENT_CAPABILITIES.
- */
-const PERSISTENT_CAPABILITIES = new Set(["coordinator", "orchestrator", "monitor"]);
-
 /** Numeric ordering for forward-only state transitions. */
 const STATE_ORDER: Record<AgentState, number> = {
 	booting: 0,
@@ -71,15 +62,34 @@ export function isProcessRunning(pid: number): boolean {
 }
 
 /**
- * Detect whether a session is a headless agent.
+ * Detect whether a session is a long-lived headless agent.
  *
- * Headless agents are spawned without a tmux session (tmuxSession === '') and
- * are tracked solely by PID. For these agents, PID is the primary liveness signal.
+ * Long-lived headless agents (coordinator, orchestrator, monitor, sapling, etc.)
+ * have no tmux session (tmuxSession === '') but do have a persistent process —
+ * so `session.pid` is non-null and PID is the primary liveness signal.
  */
 function isHeadlessSession(session: AgentSession): boolean {
 	return session.tmuxSession === "" && session.pid !== null;
 }
 
+/**
+ * Detect whether a session is a spawn-per-turn worker between turns.
+ *
+ * Spawn-per-turn workers (task-scoped capabilities under the new headless
+ * default — builder/scout/reviewer/lead/merger) have no tmux session AND no
+ * persistent process: `tmuxSession === ''` and `session.pid === null` from
+ * sling onward. The per-turn claude PID lives in
+ * `.overstory/agents/<name>/turn.pid` only while a turn is in flight.
+ *
+ * "No process" is the normal state between turns, so neither tmux liveness nor
+ * pid liveness can be used as a death signal — only `lastActivity` recency
+ * (refreshed by the turn-runner on every event and by the watchdog from
+ * events.db) can. (overstory-7a34)
+ */
+export function isSpawnPerTurnSession(session: AgentSession): boolean {
+	return session.tmuxSession === "" && session.pid === null;
+}
+
 /**
  * Evaluate time-based health (persistent capability exemptions, stale, zombie thresholds,
  * booting→working transition). Called after liveness is confirmed for both TUI and headless paths.
@@ -98,7 +108,7 @@ function evaluateTimeBased(
 	// Persistent capabilities (coordinator, monitor) are expected to have long idle
 	// periods waiting for mail/events. Skip time-based stale/zombie detection for
 	// them — only tmux/pid liveness matters (checked above).
-	if (PERSISTENT_CAPABILITIES.has(session.capability)) {
+	if (isPersistentCapability(session.capability)) {
 		// Transition booting → working if we reach here (process alive)
 		const state = session.state === "booting" ? "working" : session.state;
 		return {
@@ -165,19 +175,23 @@ function evaluateTimeBased(
  * Decision logic (in priority order):
  *
  * 1. Completed agents skip monitoring entirely.
- * 2. Headless agents (tmuxSession === ''): PID is primary liveness signal.
+ * 2. Spawn-per-turn workers (tmuxSession === '' && pid === null): no
+ *    persistent process between turns — fall straight through to time-based
+ *    checks driven by lastActivity. PID/tmux liveness are meaningless here.
+ * 3. Headless agents with persistent process (tmuxSession === '' && pid !== null):
+ *    PID is primary liveness signal.
  *    - pid dead → zombie, terminate.
  *    - pid alive + state zombie → investigate.
  *    - pid alive → fall through to time-based checks.
- * 3. tmux dead → zombie, terminate (regardless of what sessions.json says).
- * 4. tmux alive + sessions.json says zombie → investigate (don't auto-kill).
+ * 4. tmux dead → zombie, terminate (regardless of what sessions.json says).
+ * 5. tmux alive + sessions.json says zombie → investigate (don't auto-kill).
  *    Something external marked this zombie, but the process is still running.
- * 5. pid dead + tmux alive → zombie, terminate. The agent process exited but
+ * 6. pid dead + tmux alive → zombie, terminate. The agent process exited but
  *    the tmux pane shell survived. The agent is not doing work.
- * 6. lastActivity older than zombieMs → zombie, terminate.
- * 7. lastActivity older than staleMs → stalled, escalate.
- * 8. booting with recent activity → working.
- * 9. Otherwise → working, healthy.
+ * 7. lastActivity older than zombieMs → zombie, terminate.
+ * 8. lastActivity older than staleMs → stalled, escalate.
+ * 9. booting with recent activity → working.
+ * 10. Otherwise → working, healthy.
  *
  * @param session - The agent session to evaluate
  * @param tmuxAlive - Whether the agent's tmux session is still running
@@ -222,10 +236,37 @@ export function evaluateHealth(
 		};
 	}
 
+	// === Spawn-per-turn path: no persistent process between turns ===
+	// For these workers (overstory-7a34) `session.pid` is null by design and
+	// there is no tmux session. Liveness signals reduce to lastActivity
+	// recency: the turn-runner updates it on every parser event during a
+	// turn, and the watchdog refreshes it from events.db between turns. PID
+	// and tmux checks would always say "dead" and false-positive every fresh
+	// agent as zombie within seconds of sling.
+	if (isSpawnPerTurnSession(session)) {
+		return evaluateTimeBased(session, base, elapsedMs, thresholds);
+	}
+
 	// === Headless path: PID is the primary liveness signal ===
 	if (isHeadlessSession(session)) {
-		// pid dead → zombie immediately (equivalent to ZFC Rule 1 for headless)
+		// pid dead: zombie OR completed-with-missed-signal.
+		// Distinguish by lastActivity age — recent activity means the agent
+		// crashed mid-work (true zombie); stale activity means it likely
+		// finished naturally and only the session-end hook didn't deliver
+		// (treat as completed). (overstory-e74b)
 		if (pidAlive === false) {
+			if (
+				elapsedMs > thresholds.staleMs &&
+				(session.state === "working" || session.state === "booting" || session.state === "stalled")
+			) {
+				return {
+					...base,
+					processAlive: false,
+					state: "completed",
+					action: "complete",
+					reconciliationNote: `ZFC: headless pid ${session.pid} dead + stale lastActivity (${Math.round(elapsedMs / 1000)}s ago) — assumed completed (missed session-end signal)`,
+				};
+			}
 			return {
 				...base,
 				processAlive: false,
@@ -253,9 +294,25 @@ export function evaluateHealth(
 
 	// === TUI/tmux path ===
 
-	// ZFC Rule 1: tmux dead → zombie immediately, regardless of recorded state.
-	// Observable state says the process is gone.
+	// ZFC Rule 1: tmux dead → zombie OR completed-with-missed-signal.
+	// Distinguish by lastActivity age — recent activity means the agent
+	// crashed mid-work (true zombie); stale activity means it likely
+	// finished naturally and only the session-end hook didn't deliver
+	// (treat as completed). (overstory-e74b)
 	if (!tmuxAlive) {
+		if (
+			elapsedMs > thresholds.staleMs &&
+			(session.state === "working" || session.state === "booting" || session.state === "stalled")
+		) {
+			return {
+				...base,
+				processAlive: false,
+				state: "completed",
+				action: "complete",
+				reconciliationNote: `ZFC: tmux dead + stale lastActivity (${Math.round(elapsedMs / 1000)}s ago) — assumed completed (missed session-end signal)`,
+			};
+		}
+
 		const note =
 			session.state === "working" || session.state === "booting"
 				? `ZFC: tmux dead but sessions.json says "${session.state}" — marking zombie (observable state wins)`
@@ -323,6 +380,16 @@ export function transitionState(currentState: AgentState, check: HealthCheck): A
 		return currentState;
 	}
 
+	// `complete` is a terminal classification triggered when observable state
+	// proves the agent finished naturally (missed session-end signal —
+	// overstory-e74b). It bypasses the forward-only STATE_ORDER guard because
+	// `completed` (order 2) sits before `stalled` (order 3) and would
+	// otherwise be blocked from advancing the recorded state. The matrix in
+	// SessionStore.tryTransitionState still gates the actual write.
+	if (check.action === "complete") {
+		return check.state;
+	}
+
 	const currentOrder = STATE_ORDER[currentState];
 	const checkOrder = STATE_ORDER[check.state];
 

package/src/worktree/process.test.ts

@@ -2,6 +2,8 @@ import { afterEach, beforeEach, describe, expect, it } from "bun:test";
 import { mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { getConnection, removeConnection } from "../runtimes/connections.ts";
+import { HeadlessClaudeConnection } from "../runtimes/headless-connection.ts";
 import { spawnHeadlessAgent } from "./process.ts";
 
 describe("spawnHeadlessAgent", () => {
@@ -22,6 +24,75 @@ describe("spawnHeadlessAgent", () => {
 		);
 	});
 
+	describe("agentName connection registration", () => {
+		const registeredNames: string[] = [];
+
+		afterEach(() => {
+			for (const name of registeredNames.splice(0)) {
+				removeConnection(name);
+			}
+		});
+
+		it("registers a HeadlessClaudeConnection when agentName is provided", async () => {
+			const agentName = "test-headless-agent-xyz";
+			registeredNames.push(agentName);
+
+			const proc = await spawnHeadlessAgent(["sleep", "5"], {
+				cwd: process.cwd(),
+				env: { ...(process.env as Record<string, string>) },
+				agentName,
+			});
+
+			expect(proc.pid).toBeGreaterThan(0);
+			const conn = getConnection(agentName);
+			expect(conn).toBeDefined();
+			expect(conn).toBeInstanceOf(HeadlessClaudeConnection);
+
+			// Clean up the spawned process
+			try {
+				process.kill(proc.pid, "SIGTERM");
+			} catch {
+				// ignore
+			}
+		});
+
+		it("does not register a connection when agentName is omitted", async () => {
+			const proc = await spawnHeadlessAgent(["echo", "no-register"], {
+				cwd: process.cwd(),
+				env: { ...(process.env as Record<string, string>) },
+			});
+
+			// Drain stdout so process exits cleanly
+			if (proc.stdout) {
+				await new Response(proc.stdout).text();
+			}
+
+			// No connection was registered (use a stable lookup key that was never set)
+			expect(getConnection("never-registered-in-this-test")).toBeUndefined();
+		});
+
+		it("registered connection pid matches the spawned process pid", async () => {
+			const agentName = "test-headless-pid-check-xyz";
+			registeredNames.push(agentName);
+
+			const proc = await spawnHeadlessAgent(["sleep", "5"], {
+				cwd: process.cwd(),
+				env: { ...(process.env as Record<string, string>) },
+				agentName,
+			});
+
+			const conn = getConnection(agentName) as HeadlessClaudeConnection;
+			expect(conn).toBeDefined();
+			expect(conn.pid).toBe(proc.pid);
+
+			try {
+				process.kill(proc.pid, "SIGTERM");
+			} catch {
+				// ignore
+			}
+		});
+	});
+
 	describe("file redirect mode", () => {
 		let tmpDir: string;
 

package/src/worktree/process.ts

@@ -1,15 +1,20 @@
 /**
  * Headless subprocess management for non-tmux agent runtimes.
  *
- * Used by `ov sling` when runtime.headless === true to bypass tmux entirely.
- * Provides spawnHeadlessAgent() for direct Bun.spawn() invocation of
- * headless agent processes (e.g., Sapling running with --json).
+ * Used by long-lived headless runtimes that bypass tmux (e.g., Sapling running
+ * with --json). Provides spawnHeadlessAgent() for direct Bun.spawn() invocation.
+ *
+ * Headless Claude Code does NOT use this path — under spawn-per-turn (Phase 3),
+ * Claude agents have no persistent process; each turn spawns a fresh claude
+ * inside `runTurn` (src/agents/turn-runner.ts). This module remains for
+ * runtimes that genuinely need a long-lived RPC channel.
  *
  * Note: isProcessAlive() and killProcessTree() for headless process lifecycle
  * management already exist in src/worktree/tmux.ts — not duplicated here.
  */
 
 import { AgentError } from "../errors.ts";
+import { registerHeadlessConnection } from "../runtimes/connections.ts";
 
 /**
  * Handle to a spawned headless agent subprocess.
@@ -57,6 +62,15 @@ export interface SpawnHeadlessOptions {
 	 * When set, redirect subprocess stderr to this file path instead of a pipe.
 	 */
 	stderrFile?: string;
+	/**
+	 * When set, registers the spawned process as a `RuntimeConnection` keyed by
+	 * this agent name (sibling of Sapling's RPC connect() flow). Lets `ov nudge`,
+	 * the watchdog's liveness/abort path, etc. find the live process via
+	 * `getConnection(agentName)`.
+	 *
+	 * Same namespace as AgentSession.agentName.
+	 */
+	agentName?: string;
 }
 
 /**
@@ -103,9 +117,15 @@ export async function spawnHeadlessAgent(
 		stdin: "pipe",
 	});
 
-	return {
+	const result: HeadlessProcess = {
 		pid: proc.pid,
-		stdin: proc.stdin,
+		stdin: proc.stdin as HeadlessProcess["stdin"],
 		stdout: opts.stdoutFile ? null : (proc.stdout as ReadableStream<Uint8Array>),
 	};
+
+	if (opts.agentName) {
+		registerHeadlessConnection(opts.agentName, result);
+	}
+
+	return result;
 }

package/src/worktree/tmux.test.ts

@@ -13,6 +13,7 @@ import {
 	killProcessTree,
 	killSession,
 	listSessions,
+	sanitizeTmuxName,
 	sendKeys,
 	waitForTuiReady,
 } from "./tmux.ts";
@@ -111,6 +112,9 @@ describe("createSession", () => {
 		const wrappedCmd = cmd[9] as string;
 		expect(wrappedCmd).toContain("echo hello");
 		expect(wrappedCmd).toContain("export PATH=");
+		// `exec` replaces the bash wrapper with the command so SIGHUP from a
+		// dying tmux server is delivered directly to claude (overstory-505d).
+		expect(wrappedCmd).toContain("exec echo hello");
 
 		const opts = tmuxCallArgs[1] as { cwd: string };
 		expect(opts.cwd).toBe("/work/dir");
@@ -1550,3 +1554,38 @@ describe("ensureTmuxAvailable", () => {
 		}
 	});
 });
+
+describe("sanitizeTmuxName", () => {
+	test("replaces dots with underscores", () => {
+		expect(sanitizeTmuxName("consulting.jayminwest.com")).toBe("consulting_jayminwest_com");
+	});
+
+	test("replaces colons with underscores", () => {
+		expect(sanitizeTmuxName("host:8080")).toBe("host_8080");
+	});
+
+	test("replaces mixed dots and colons", () => {
+		expect(sanitizeTmuxName("my.project:v2.0")).toBe("my_project_v2_0");
+	});
+
+	test("leaves names without special characters unchanged", () => {
+		expect(sanitizeTmuxName("my-project")).toBe("my-project");
+	});
+
+	test("handles empty string", () => {
+		expect(sanitizeTmuxName("")).toBe("");
+	});
+
+	test("handles name with only dots", () => {
+		expect(sanitizeTmuxName("...")).toBe("___");
+	});
+
+	test("produces valid tmux session name components", () => {
+		// A real-world project name that would break tmux target parsing
+		const projectName = "consulting.jayminwest.com";
+		const sessionName = `overstory-${sanitizeTmuxName(projectName)}-coordinator`;
+		expect(sessionName).toBe("overstory-consulting_jayminwest_com-coordinator");
+		// No dots or colons that tmux would interpret as separators
+		expect(sessionName).not.toMatch(/[.:]/);
+	});
+});

package/src/worktree/tmux.ts

@@ -21,6 +21,19 @@ import type { ReadyState } from "../runtimes/types.ts";
  */
 export const TMUX_SOCKET = "overstory";
 
+/**
+ * Sanitize a name component for use in tmux session names.
+ *
+ * Tmux interprets dots (.) as session.window.pane separators and colons (:)
+ * as session:window separators in target strings (`-t`). If a project name
+ * contains these characters (e.g., "consulting.jayminwest.com"), the session
+ * is created fine but subsequent lookups via `-t` parse the dots as delimiters
+ * and fail to find the session. Replace both with underscores.
+ */
+export function sanitizeTmuxName(name: string): string {
+	return name.replace(/[.:]/g, "_");
+}
+
 /**
  * Build a tmux command array with the dedicated server socket.
  * All agent session operations should use this to ensure isolation.
@@ -136,9 +149,16 @@ export async function createSession(
 	// causes the session to die instantly. Single-quote wrapping with escaped
 	// single quotes prevents any intermediate shell from expanding variables
 	// before bash receives them. (GitHub #86)
-	const startupScript = exports.length > 0 ? `${exports.join(" && ")} && ${command}` : command;
-	const wrappedCommand =
-		exports.length > 0 ? `/bin/bash -c '${startupScript.replace(/'/g, "'\\''")}'` : command;
+	//
+	// The `exec` prefix replaces the bash wrapper with the spawned command
+	// so there is no separate wrapper PID to orphan if the tmux server dies
+	// externally. Without exec, bash receives SIGHUP on tmux teardown but its
+	// claude child gets reparented to init and continues running. With exec,
+	// the wrapper IS the command — SIGHUP is delivered directly to claude.
+	// (overstory-505d)
+	const startupScript =
+		exports.length > 0 ? `${exports.join(" && ")} && exec ${command}` : `exec ${command}`;
+	const wrappedCommand = `/bin/bash -c '${startupScript.replace(/'/g, "'\\''")}'`;
 
 	const { exitCode, stderr } = await runCommand(
 		tmuxCmd("new-session", "-d", "-s", name, "-c", cwd, wrappedCommand),

package/templates/CLAUDE.md.tmpl

@@ -6,6 +6,11 @@ This project uses **overstory** for Claude Code agent orchestration. Your sessio
 acts as the orchestrator: you decide what work to delegate, spawn worker agents,
 monitor progress, and merge results.
 
+The **web UI is your primary operator surface** — run `ov serve` and open
+http://localhost:8080 to watch the swarm. Workers spawn headless by default, so
+the UI sees them with full structured-event fidelity. `tmux attach` is the opt-in
+escape hatch when you need to steer a single agent live (`ov sling --no-headless`).
+
 ## Quick Reference
 
 ```bash
@@ -48,9 +53,12 @@ ov log <event> --agent <name>  # Hook-driven event logging
 3. Assign exclusive file scope so agents do not conflict
 4. Spawn: `ov sling <bead-id> --capability <type> --name <unique-name> --files src/foo.ts,src/bar.ts`
 
-Each spawned agent gets its own git worktree, branch, CLAUDE.md overlay, and
-tmux session. Agents communicate via `ov mail` and report completion
-by closing their {{TRACKER_NAME}} issue (`{{TRACKER_CLI}} close <id> --reason "summary"`).
+Each spawned agent gets its own git worktree, branch, and CLAUDE.md overlay.
+Claude agents spawn **headless by default** — the web UI (`ov serve`, then open
+http://localhost:8080) is the primary operator surface. Pass `--no-headless` to
+spawn into a tmux session you can attach to (`tmux attach -t ov-<agent>`).
+Agents communicate via `ov mail` and report completion by closing their
+{{TRACKER_NAME}} issue (`{{TRACKER_CLI}} close <id> --reason "summary"`).
 
 ## Hierarchical Delegation
 
@@ -69,11 +77,14 @@ to track hierarchy.
 
 ## Checking Status
 
-Run `ov status` to see:
-- Active agents and their states (booting, working, stalled, zombie)
-- Worktree locations and branches
-- Beads issue progress
-- Unread mail count
+The web UI (`ov serve`, http://localhost:8080) is the primary view —
+fleet topology, per-agent timelines, mail inbox, and live events.
+
+CLI alternatives for scripting / quick checks:
+
+- `ov status` — active agents and states, worktrees, {{TRACKER_NAME}} progress, unread mail
+- `ov dashboard` — live TUI dashboard if you don't want to leave the terminal
+- `ov inspect <agent>` — deep view of one agent
 
 ## Canonical Branch
 

package/templates/overlay.md.tmpl

@@ -68,9 +68,10 @@ ov mail send --to {{PARENT_AGENT}} --subject "status" \
 ov mail send --to {{PARENT_AGENT}} --subject "question" \
   --body "Your question here" --type question --priority high --agent {{AGENT_NAME}}
 
-# Report completion
+# Report completion (terminal exit signal — workers send worker_done; merger
+# sends merged/merge_failed; see "Constraints" / "Completion" sections below).
 ov mail send --to {{PARENT_AGENT}} --subject "done" \
-  --body "Summary of what was done" --type result --agent {{AGENT_NAME}}
+  --body "Summary of what was done" --type worker_done --agent {{AGENT_NAME}}
 
 # Reply to a message
 ov mail reply <message-id> --body "Your reply" --agent {{AGENT_NAME}}