@os-eco/overstory-cli 0.10.3 → 0.11.0

package/src/watchdog/daemon.ts

@@ -487,12 +487,17 @@ export function startDaemon(options: DaemonOptions & { intervalMs: number }): {
  * Prefers runtime-agnostic `conn.abort()` when a RuntimeConnection is registered.
  * If abort() succeeds, returns immediately — no PID/tmux kill needed.
  * If abort() throws (e.g. process already exited), falls through to the
- * defense-in-depth path: PID kill for headless agents, tmux kill for TUI agents.
+ * defense-in-depth path below.
  *
- * Headless agents without a connection (tmuxSession === "" && pid !== null) are
- * killed via PID process tree. TUI agents are killed via their named tmux session
- * (only if tmuxAlive). This prevents the blast-radius bug where killSession("")
- * with tmux prefix matching would kill ALL tmux sessions.
+ * Branching after abort:
+ *   - tmuxSession === "" (headless): never call tmux.killSession — an empty `-t`
+ *     prefix-matches every session in the tmux server, wildcard-killing the entire
+ *     overstory swarm (overstory-74ce). Branch by pid:
+ *       - pid !== null  → kill the process tree (long-lived headless capability).
+ *       - pid === null  → no-op (spawn-per-turn agent between turns; the in-flight
+ *         process, if any, was already handled by the abort/connection path).
+ *   - tmuxSession !== "" (TUI): kill the named tmux session, but only when
+ *     `tmuxAlive` to avoid spurious "session not found" errors.
  */
 async function killAgent(ctx: {
 	session: AgentSession;
@@ -503,7 +508,6 @@ async function killAgent(ctx: {
 	removeConnection: (name: string) => void;
 }): Promise<void> {
 	const { session, tmuxAlive, tmux, process: proc, getConnection, removeConnection } = ctx;
-	const isHeadless = session.tmuxSession === "" && session.pid !== null;
 
 	// Prefer runtime-agnostic abort() when a connection is registered.
 	const conn = getConnection(session.agentName);
@@ -522,13 +526,24 @@ async function killAgent(ctx: {
 		// abort() threw — fall through to PID/tmux kill below as defense-in-depth
 	}
 
-	if (isHeadless && session.pid !== null) {
-		try {
-			await proc.killTree(session.pid);
-		} catch {
-			// Already exited — not an error
+	// Headless agents (no tmux session) must never reach tmux.killSession.
+	// An empty `-t` argument is prefix-matched and would kill every overstory
+	// tmux session in the server (overstory-74ce).
+	if (session.tmuxSession === "") {
+		if (session.pid !== null) {
+			try {
+				await proc.killTree(session.pid);
+			} catch {
+				// Already exited — not an error
+			}
 		}
-	} else if (tmuxAlive) {
+		// pid === null: spawn-per-turn agent between turns. Any in-flight process
+		// was handled by abort/connection above. No-op — next dispatch will spawn fresh.
+		return;
+	}
+
+	// Named tmux session path (TUI agents).
+	if (tmuxAlive) {
 		try {
 			await tmux.killSession(session.tmuxSession);
 		} catch {

package/src/watchdog/health.test.ts

@@ -502,7 +502,11 @@ describe("spawn-per-turn workers (overstory-7a34)", () => {
 	// 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", () => {
+	test("freshly slung spawn-per-turn lead (booting, no pid, no tmux) → between_turns (overstory-3087)", () => {
+		// Spec change: spawn-per-turn workers report `between_turns` instead
+		// of `working` for the healthy classification, including the booting
+		// → healthy transition. The turn-runner authoritatively writes
+		// `in_turn` once the first parser event of a turn arrives.
 		const session = makeSession({
 			tmuxSession: "",
 			pid: null,
@@ -512,12 +516,18 @@ describe("spawn-per-turn workers (overstory-7a34)", () => {
 		});
 		const check = evaluateHealth(session, false, THRESHOLDS);
 
-		expect(check.state).toBe("working");
+		expect(check.state).toBe("between_turns");
 		expect(check.action).toBe("none");
 		expect(check.reconciliationNote).toBeNull();
 	});
 
-	test("active spawn-per-turn worker (working, recent activity) → stays working", () => {
+	test("legacy spawn-per-turn worker still at 'working' is reported as between_turns (overstory-3087)", () => {
+		// A row that predates the substate split (state=working) gets
+		// reclassified to `between_turns` by the watchdog's healthy-state
+		// reporter. transitionState then promotes the row forward (working
+		// and between_turns share rank 1 in STATE_ORDER, so the actual
+		// promotion happens via tryTransitionState elsewhere — here we just
+		// verify the check itself reports the new substate).
 		const session = makeSession({
 			tmuxSession: "",
 			pid: null,
@@ -527,13 +537,16 @@ describe("spawn-per-turn workers (overstory-7a34)", () => {
 		});
 		const check = evaluateHealth(session, false, THRESHOLDS);
 
-		expect(check.state).toBe("working");
+		expect(check.state).toBe("between_turns");
 		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.
+	test("spawn-per-turn worker between turns (recent activity) → between_turns, NOT zombie (overstory-3087)", () => {
+		// Repro of overstory-7a34: ov sling --capability lead any-task; within
+		// ~30s ov dashboard previously showed state='zombie' while ov feed
+		// showed live tool calls. The healthy classification now lands
+		// between_turns; the test still verifies that recent activity does
+		// not trigger zombie classification.
 		const session = makeSession({
 			tmuxSession: "",
 			pid: null,
@@ -543,7 +556,7 @@ describe("spawn-per-turn workers (overstory-7a34)", () => {
 		});
 		const check = evaluateHealth(session, false, THRESHOLDS);
 
-		expect(check.state).toBe("working");
+		expect(check.state).toBe("between_turns");
 		expect(check.action).toBe("none");
 	});
 
@@ -587,6 +600,53 @@ describe("spawn-per-turn workers (overstory-7a34)", () => {
 		expect(check.state).toBe("completed");
 		expect(check.action).toBe("none");
 	});
+
+	test("preserves in_turn for healthy spawn-per-turn worker (overstory-3087)", () => {
+		// A spawn-per-turn worker the turn-runner has marked in_turn must
+		// have its state preserved by the health evaluation when activity is
+		// recent — otherwise the watchdog would stomp the substate back to
+		// `working` and the UI would lose the distinction between mid-turn
+		// and idling.
+		const session = makeSession({
+			tmuxSession: "",
+			pid: null,
+			capability: "builder",
+			state: "in_turn",
+			lastActivity: new Date().toISOString(),
+		});
+		const check = evaluateHealth(session, false, THRESHOLDS);
+
+		expect(check.state).toBe("in_turn");
+		expect(check.action).toBe("none");
+	});
+
+	test("preserves between_turns for healthy spawn-per-turn worker (overstory-3087)", () => {
+		const session = makeSession({
+			tmuxSession: "",
+			pid: null,
+			capability: "builder",
+			state: "between_turns",
+			lastActivity: new Date().toISOString(),
+		});
+		const check = evaluateHealth(session, false, THRESHOLDS);
+
+		expect(check.state).toBe("between_turns");
+		expect(check.action).toBe("none");
+	});
+
+	test("escalates an in_turn worker with stale activity to stalled (overstory-3087)", () => {
+		const session = makeSession({
+			tmuxSession: "",
+			pid: null,
+			capability: "builder",
+			state: "in_turn",
+			lastActivity: new Date(Date.now() - 60_000).toISOString(),
+		});
+		const check = evaluateHealth(session, false, THRESHOLDS);
+
+		expect(check.state).toBe("stalled");
+		expect(check.action).toBe("escalate");
+	});
 });
 
 // === transitionState ===
@@ -702,4 +762,69 @@ describe("transitionState", () => {
 		// the state should NOT advance
 		expect(transitionState("working", check)).toBe("working");
 	});
+
+	// --- in_turn / between_turns coexist with working at the active rank (overstory-3087) ---
+
+	test("preserves in_turn when watchdog reports a healthy 'working' check", () => {
+		// The watchdog's healthy-classification check returns state=working;
+		// since in_turn shares rank 1 with working, transitionState must not
+		// advance and the spawn-per-turn substate the turn-runner wrote stays.
+		const check = {
+			state: "working" as const,
+			agentName: "a",
+			timestamp: "",
+			tmuxAlive: true,
+			pidAlive: true as boolean | null,
+			lastActivity: "",
+			processAlive: true,
+			action: "none" as const,
+			reconciliationNote: null,
+		};
+		expect(transitionState("in_turn", check)).toBe("in_turn");
+	});
+
+	test("preserves between_turns when watchdog reports a healthy 'working' check", () => {
+		const check = {
+			state: "working" as const,
+			agentName: "a",
+			timestamp: "",
+			tmuxAlive: true,
+			pidAlive: true as boolean | null,
+			lastActivity: "",
+			processAlive: true,
+			action: "none" as const,
+			reconciliationNote: null,
+		};
+		expect(transitionState("between_turns", check)).toBe("between_turns");
+	});
+
+	test("advances in_turn → stalled when the watchdog escalates", () => {
+		const check = {
+			state: "stalled" as const,
+			agentName: "a",
+			timestamp: "",
+			tmuxAlive: true,
+			pidAlive: true as boolean | null,
+			lastActivity: "",
+			processAlive: true,
+			action: "escalate" as const,
+			reconciliationNote: null,
+		};
+		expect(transitionState("in_turn", check)).toBe("stalled");
+	});
+
+	test("advances between_turns → zombie when the watchdog terminates", () => {
+		const check = {
+			state: "zombie" as const,
+			agentName: "a",
+			timestamp: "",
+			tmuxAlive: false,
+			pidAlive: false as boolean | null,
+			lastActivity: "",
+			processAlive: false,
+			action: "terminate" as const,
+			reconciliationNote: null,
+		};
+		expect(transitionState("between_turns", check)).toBe("zombie");
+	});
 });

package/src/watchdog/health.ts

@@ -33,10 +33,22 @@
 import { isPersistentCapability } from "../agents/capabilities.ts";
 import type { AgentSession, AgentState, HealthCheck } from "../types.ts";
 
-/** Numeric ordering for forward-only state transitions. */
+/**
+ * Numeric ordering for forward-only state transitions.
+ *
+ * `in_turn` and `between_turns` share the `working` rank (1) because, from
+ * the watchdog's perspective, all three are "agent is alive and active" —
+ * they only differ in whether the spawn-per-turn worker is currently
+ * mid-execution or idling between mail batches (overstory-3087). Same rank
+ * means a healthy-classification check (`check.state === "working"`) will
+ * not stomp on the more specific in_turn/between_turns states the
+ * turn-runner has already written.
+ */
 const STATE_ORDER: Record<AgentState, number> = {
 	booting: 0,
 	working: 1,
+	in_turn: 1,
+	between_turns: 1,
 	completed: 2,
 	stalled: 3,
 	zombie: 4,
@@ -145,22 +157,42 @@ function evaluateTimeBased(
 		};
 	}
 
-	// booting → transition to working once there's recent activity
+	// Spawn-per-turn workers (overstory-3087): healthy classification reports
+	// `between_turns` instead of `working`, including the booting → healthy
+	// transition. The turn-runner authoritatively writes `in_turn` /
+	// `between_turns` while a turn is alive; in_turn is preserved here when
+	// already set so a watchdog tick mid-turn does not overwrite it.
+	const isSpawnPerTurn = isSpawnPerTurnSession(session);
+
+	// booting → transition to the healthy state once there's recent activity.
 	if (session.state === "booting") {
 		return {
 			...base,
 			processAlive: true,
-			state: "working",
+			state: isSpawnPerTurn ? "between_turns" : "working",
 			action: "none",
 			reconciliationNote: null,
 		};
 	}
 
-	// Default: healthy and working
+	// Default: healthy active state. For spawn-per-turn workers report the
+	// existing in_turn/between_turns substate; for tmux/long-lived agents
+	// report `working`. The turn-runner is authoritative for in_turn ↔
+	// between_turns transitions, so the watchdog must not stomp the more
+	// specific state — same rank in STATE_ORDER ensures `transitionState`
+	// also leaves the row alone.
+	let healthyState: AgentState;
+	if (session.state === "in_turn" || session.state === "between_turns") {
+		healthyState = session.state;
+	} else if (isSpawnPerTurn) {
+		healthyState = "between_turns";
+	} else {
+		healthyState = "working";
+	}
 	return {
 		...base,
 		processAlive: true,
-		state: "working",
+		state: healthyState,
 		action: "none",
 		reconciliationNote: null,
 	};

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/tmux.test.ts

@@ -830,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", () => {
@@ -869,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", () => {