@os-eco/overstory-cli 0.9.4 → 0.11.0

package/src/worktree/manager.test.ts

@@ -1,6 +1,6 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { existsSync, realpathSync } from "node:fs";
-import { mkdir, mkdtemp } from "node:fs/promises";
+import { mkdir, mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { WorktreeError } from "../errors.ts";
@@ -9,6 +9,7 @@ import {
 	commitFile,
 	createTempGitRepo,
 	getDefaultBranch,
+	runGitInDir,
 } from "../test-helpers.ts";
 import {
 	createWorktree,
@@ -16,6 +17,7 @@ import {
 	listWorktrees,
 	removeWorktree,
 	rollbackWorktree,
+	validateWorktreeCreation,
 } from "./manager.ts";
 
 /**
@@ -145,6 +147,61 @@ describe("createWorktree", () => {
 			expect(wtErr.branchName).toBe("overstory/auth-login/bead-abc123");
 		}
 	});
+
+	test("rejects creation when target branch is already checked out elsewhere", async () => {
+		// Pre-check should fail-fast with a precise diagnostic before git
+		// worktree add runs, so the operator sees the actual cause rather
+		// than git's generic "already exists" error or, worse, a silently
+		// half-built worktree (overstory-6878).
+		const first = await createWorktree({
+			repoRoot: repoDir,
+			baseDir: worktreesDir,
+			agentName: "auth-login",
+			baseBranch: defaultBranch,
+			taskId: "bead-abc123",
+		});
+
+		try {
+			await createWorktree({
+				repoRoot: repoDir,
+				baseDir: worktreesDir,
+				agentName: "auth-login",
+				baseBranch: defaultBranch,
+				taskId: "bead-abc123",
+			});
+			expect(true).toBe(false);
+		} catch (err: unknown) {
+			expect(err).toBeInstanceOf(WorktreeError);
+			const wtErr = err as WorktreeError;
+			expect(wtErr.message).toContain("already checked out");
+			expect(wtErr.message).toContain(first.path);
+			expect(wtErr.branchName).toBe("overstory/auth-login/bead-abc123");
+		}
+
+		// The original worktree must remain intact — the pre-check rejected
+		// before any state-mutating git command ran.
+		expect(existsSync(first.path)).toBe(true);
+		const entries = await listWorktrees(repoDir);
+		expect(entries.some((e) => e.path === first.path)).toBe(true);
+	});
+
+	test("post-creation: new worktree is registered and contains tracked files", async () => {
+		const { path: wtPath } = await createWorktree({
+			repoRoot: repoDir,
+			baseDir: worktreesDir,
+			agentName: "auth-login",
+			baseBranch: defaultBranch,
+			taskId: "bead-files",
+		});
+
+		// Registration check — listWorktrees must include the new path
+		const entries = await listWorktrees(repoDir);
+		expect(entries.map((e) => e.path)).toContain(wtPath);
+
+		// File-presence check — git ls-files inside the worktree must be non-empty
+		const lsFiles = await git(wtPath, ["ls-files"]);
+		expect(lsFiles.trim().length).toBeGreaterThan(0);
+	});
 });
 
 describe("listWorktrees", () => {
@@ -501,3 +558,163 @@ describe("rollbackWorktree", () => {
 		expect(branchList).toContain("overstory/auth-login/bead-abc");
 	});
 });
+
+describe("validateWorktreeCreation", () => {
+	let repoDir: string;
+	let worktreesDir: string;
+	let defaultBranch: string;
+
+	beforeEach(async () => {
+		repoDir = realpathSync(await createTempGitRepo());
+		defaultBranch = await getDefaultBranch(repoDir);
+		worktreesDir = join(repoDir, ".overstory", "worktrees");
+		await mkdir(worktreesDir, { recursive: true });
+	});
+
+	afterEach(async () => {
+		await cleanupTempDir(repoDir);
+	});
+
+	test("passes for a normally created worktree", async () => {
+		const { path: wtPath, branch } = await createWorktree({
+			repoRoot: repoDir,
+			baseDir: worktreesDir,
+			agentName: "feature-agent",
+			baseBranch: defaultBranch,
+			taskId: "bead-ok",
+		});
+
+		// Re-running validation against the live worktree should be a no-op
+		await expect(
+			validateWorktreeCreation({
+				repoRoot: repoDir,
+				worktreePath: wtPath,
+				branchName: branch,
+			}),
+		).resolves.toBeUndefined();
+	});
+
+	test("throws when worktree path is not registered with git", async () => {
+		const fakePath = join(worktreesDir, "ghost-agent");
+
+		try {
+			await validateWorktreeCreation({
+				repoRoot: repoDir,
+				worktreePath: fakePath,
+				branchName: "overstory/ghost-agent/bead-missing",
+			});
+			expect(true).toBe(false);
+		} catch (err: unknown) {
+			expect(err).toBeInstanceOf(WorktreeError);
+			const wtErr = err as WorktreeError;
+			expect(wtErr.worktreePath).toBe(fakePath);
+			expect(wtErr.branchName).toBe("overstory/ghost-agent/bead-missing");
+			expect(wtErr.message).toContain("not registered with git");
+		}
+	});
+
+	test("rolls back the dangling branch when validation fails", async () => {
+		// Create a real branch that's not attached to any worktree, then ask
+		// validation to check a path it can't possibly be registered at.
+		await runGitInDir(repoDir, ["branch", "overstory/orphan-agent/bead-x", defaultBranch]);
+		const fakePath = join(worktreesDir, "orphan-agent");
+
+		await expect(
+			validateWorktreeCreation({
+				repoRoot: repoDir,
+				worktreePath: fakePath,
+				branchName: "overstory/orphan-agent/bead-x",
+			}),
+		).rejects.toThrow(WorktreeError);
+
+		// rollbackWorktree should have force-deleted the orphan branch
+		const branchList = await git(repoDir, ["branch", "--list"]);
+		expect(branchList).not.toContain("overstory/orphan-agent/bead-x");
+	});
+
+	test("throws when worktree contains zero tracked files", async () => {
+		// Build a base branch that points at an empty tree, then create a
+		// worktree from it. git happily registers the worktree, but ls-files
+		// returns nothing — the exact silent-failure shape from overstory-6878.
+		const emptyTree = (
+			await runGitInDir(repoDir, ["hash-object", "-t", "tree", "/dev/null"])
+		).trim();
+		const emptyCommit = (
+			await runGitInDir(repoDir, ["commit-tree", emptyTree, "-m", "empty base"])
+		).trim();
+		await runGitInDir(repoDir, ["branch", "empty-base", emptyCommit]);
+
+		const wtPath = join(worktreesDir, "empty-agent");
+		const branchName = "overstory/empty-agent/bead-empty";
+		await runGitInDir(repoDir, ["worktree", "add", "-b", branchName, wtPath, "empty-base"]);
+
+		try {
+			await validateWorktreeCreation({
+				repoRoot: repoDir,
+				worktreePath: wtPath,
+				branchName,
+			});
+			expect(true).toBe(false);
+		} catch (err: unknown) {
+			expect(err).toBeInstanceOf(WorktreeError);
+			const wtErr = err as WorktreeError;
+			expect(wtErr.worktreePath).toBe(wtPath);
+			expect(wtErr.branchName).toBe(branchName);
+			expect(wtErr.message).toContain("zero tracked files");
+		}
+
+		// Rollback removed both worktree and branch
+		expect(existsSync(wtPath)).toBe(false);
+		const branchList = await git(repoDir, ["branch", "--list"]);
+		expect(branchList).not.toContain(branchName);
+	});
+
+	test("createWorktree rejects when base branch has no tracked files", async () => {
+		// End-to-end: createWorktree should surface the same error and clean
+		// up after itself, so sling never sees a half-built worktree.
+		const emptyTree = (
+			await runGitInDir(repoDir, ["hash-object", "-t", "tree", "/dev/null"])
+		).trim();
+		const emptyCommit = (
+			await runGitInDir(repoDir, ["commit-tree", emptyTree, "-m", "empty base"])
+		).trim();
+		await runGitInDir(repoDir, ["branch", "empty-base", emptyCommit]);
+
+		await expect(
+			createWorktree({
+				repoRoot: repoDir,
+				baseDir: worktreesDir,
+				agentName: "empty-agent",
+				baseBranch: "empty-base",
+				taskId: "bead-empty",
+			}),
+		).rejects.toThrow(WorktreeError);
+
+		// Caller observes a clean repo: no worktree dir, no leaked branch
+		expect(existsSync(join(worktreesDir, "empty-agent"))).toBe(false);
+		const branchList = await git(repoDir, ["branch", "--list"]);
+		expect(branchList).not.toContain("overstory/empty-agent/bead-empty");
+	});
+
+	test("createWorktree rejects when target dir pre-exists with files", async () => {
+		// Simulates the witnessed scenario: a stale directory survives at the
+		// target path from a previous run. createWorktree must surface a
+		// WorktreeError rather than returning a path that points at non-git
+		// state — the contract that protects the agent from being trapped.
+		const wtPath = join(worktreesDir, "preexisting-agent");
+		await mkdir(wtPath, { recursive: true });
+		await Bun.write(join(wtPath, "stale.txt"), "leftover from a previous run");
+
+		await expect(
+			createWorktree({
+				repoRoot: repoDir,
+				baseDir: worktreesDir,
+				agentName: "preexisting-agent",
+				baseBranch: defaultBranch,
+				taskId: "bead-pre",
+			}),
+		).rejects.toThrow(WorktreeError);
+
+		await rm(wtPath, { recursive: true, force: true });
+	});
+});

package/src/worktree/manager.ts

@@ -41,6 +41,14 @@ async function runGit(
  * Creates a worktree at `{baseDir}/{agentName}` with a new branch
  * named `overstory/{agentName}/{taskId}` based on `baseBranch`.
  *
+ * Before running `git worktree add`, rejects when the target branch is
+ * already checked out in another worktree — this avoids the silent-overwrite
+ * class of failure entirely. After `git worktree add` returns, validates
+ * that the worktree is actually registered with git AND contains tracked
+ * files; if either check fails, rolls back and throws. sling has previously
+ * hit edge cases where the dir exists but git did not populate it
+ * (overstory-6878), trapping the agent in a non-worktree directory.
+ *
  * @returns The absolute worktree path and branch name.
  */
 export async function createWorktree(options: {
@@ -55,14 +63,61 @@ export async function createWorktree(options: {
 	const worktreePath = join(baseDir, agentName);
 	const branchName = `overstory/${agentName}/${taskId}`;
 
+	const existing = await listWorktrees(repoRoot);
+	const occupied = existing.find((entry) => entry.branch === branchName);
+	if (occupied !== undefined) {
+		throw new WorktreeError(`branch ${branchName} is already checked out at ${occupied.path}`, {
+			worktreePath,
+			branchName,
+		});
+	}
+
 	await runGit(repoRoot, ["worktree", "add", "-b", branchName, worktreePath, baseBranch], {
 		worktreePath,
 		branchName,
 	});
 
+	await validateWorktreeCreation({ repoRoot, worktreePath, branchName });
+
 	return { path: worktreePath, branch: branchName };
 }
 
+/**
+ * Verify that a freshly created worktree is registered with git and contains
+ * tracked files. Throws WorktreeError with a precise diagnostic on failure
+ * and rolls back the worktree + branch so callers don't leak state.
+ *
+ * Exported for direct testing of edge cases (empty base branches, racy
+ * cleanup) that are awkward to provoke through createWorktree end-to-end.
+ */
+export async function validateWorktreeCreation(opts: {
+	repoRoot: string;
+	worktreePath: string;
+	branchName: string;
+}): Promise<void> {
+	const { repoRoot, worktreePath, branchName } = opts;
+
+	const entries = await listWorktrees(repoRoot);
+	const registered = entries.some((entry) => entry.path === worktreePath);
+	if (!registered) {
+		await rollbackWorktree(repoRoot, worktreePath, branchName);
+		throw new WorktreeError(
+			`Worktree creation reported success but path is not registered with git: ${worktreePath}. Possible causes: pre-existing directory, branch already checked out elsewhere, or git worktree add failed silently.`,
+			{ worktreePath, branchName },
+		);
+	}
+
+	const lsFiles = await runGit(worktreePath, ["ls-files"], { worktreePath, branchName });
+	const fileCount = lsFiles.split("\n").filter((line) => line.length > 0).length;
+	if (fileCount === 0) {
+		await rollbackWorktree(repoRoot, worktreePath, branchName);
+		throw new WorktreeError(
+			`Worktree was registered but contains zero tracked files: ${worktreePath}. The base branch may be empty or the working tree was not populated.`,
+			{ worktreePath, branchName },
+		);
+	}
+}
+
 /**
  * Roll back a worktree and its associated branch after a failed spawn.
  *

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

@@ -112,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");
@@ -827,6 +830,22 @@ describe("killSession", () => {
 			expect(agentErr.agentName).toBe("ghost-agent");
 		}
 	});
+
+	test("throws AgentError when called with empty session name", async () => {
+		// Defense in depth (overstory-74ce): tmux's `-t` argument prefix-matches
+		// every session in the server when given an empty string. Without this
+		// guard a regression in any caller would wildcard-kill the entire
+		// overstory swarm. spawn must NOT be invoked.
+		await expect(killSession("")).rejects.toThrow(AgentError);
+		expect(spawnSpy).not.toHaveBeenCalled();
+
+		try {
+			await killSession("");
+		} catch (err: unknown) {
+			const agentErr = err as AgentError;
+			expect(agentErr.message).toContain("wildcard");
+		}
+	});
 });
 
 describe("isSessionAlive", () => {
@@ -866,6 +885,15 @@ describe("isSessionAlive", () => {
 		const cmd = callArgs[0] as string[];
 		expect(cmd).toEqual(["tmux", "-L", "overstory", "has-session", "-t", "my-agent"]);
 	});
+
+	test("returns false for empty session name without calling tmux", async () => {
+		// Defense in depth (overstory-74ce): an empty `-t` argument prefix-matches
+		// every overstory session, so `has-session` would falsely report alive
+		// whenever any agent is running. Short-circuit to false without invoking tmux.
+		const alive = await isSessionAlive("");
+		expect(alive).toBe(false);
+		expect(spawnSpy).not.toHaveBeenCalled();
+	});
 });
 
 describe("checkSessionState", () => {

package/src/worktree/tmux.ts

@@ -149,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),
@@ -397,6 +404,17 @@ function sendSignal(pid: number, signal: "SIGTERM" | "SIGKILL"): void {
  *         failures are silently handled since the goal is best-effort cleanup)
  */
 export async function killSession(name: string): Promise<void> {
+	// Defense in depth: an empty session name passed to `tmux -t` is prefix-matched
+	// against every session in the server, wildcard-killing the entire overstory
+	// swarm (overstory-74ce). Reject empty names at the boundary so a regression in
+	// any caller surfaces loudly instead of silently nuking the tmux server.
+	if (name === "") {
+		throw new AgentError(
+			"killSession called with empty session name (would wildcard-kill all tmux sessions due to prefix matching)",
+			{ agentName: name },
+		);
+	}
+
 	// Step 1: Get the pane PID before killing the tmux session
 	const panePid = await getPanePid(name);
 
@@ -450,6 +468,12 @@ export async function getCurrentSessionName(): Promise<string | null> {
  * @returns true if the session exists, false otherwise
  */
 export async function isSessionAlive(name: string): Promise<boolean> {
+	// Defense in depth: an empty `-t` argument is prefix-matched against every
+	// session, so `has-session` would return true whenever any overstory session
+	// exists. Treat empty as "not alive" without contacting tmux (overstory-74ce).
+	if (name === "") {
+		return false;
+	}
 	const { exitCode } = await runCommand(tmuxCmd("has-session", "-t", name));
 	return exitCode === 0;
 }

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

@@ -25,6 +25,8 @@
 
 {{DISPATCH_OVERRIDES}}
 
+{{SIBLINGS}}
+
 ## Working Directory
 
 Your worktree root is: `{{WORKTREE_PATH}}`
@@ -68,9 +70,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}}