@os-eco/overstory-cli 0.9.3 → 0.9.4

package/README.md

@@ -10,6 +10,8 @@ Overstory turns a single coding session into a multi-agent team by spawning work
 
 > **Warning: Agent swarms are not a universal solution.** Do not deploy Overstory without understanding the risks of multi-agent orchestration — compounding error rates, cost amplification, debugging complexity, and merge conflicts are the normal case, not edge cases. Read [STEELMAN.md](STEELMAN.md) for a full risk analysis and the [Agentic Engineering Book](https://github.com/jayminwest/agentic-engineering-book) ([web version](https://jayminwest.com/agentic-engineering-book)) before using this tool in production.
 
+> **Maintenance status.** Overstory is maintained part-time. PRs are reviewed in roughly 2-week batches; PRs inactive for 30+ days are closed (reopen anytime). For features larger than ~200 lines, open an issue or discussion first. See [CONTRIBUTING.md](CONTRIBUTING.md#review-cadence).
+
 ## Install
 
 Requires [Bun](https://bun.sh) v1.0+, git, and tmux. At least one supported agent runtime must be installed:

package/package.json

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

package/src/commands/clean.ts

@@ -37,6 +37,7 @@ import {
 	killProcessTree,
 	killSession,
 	listSessions,
+	sanitizeTmuxName,
 } from "../worktree/tmux.ts";
 
 export interface CleanOptions {
@@ -155,7 +156,7 @@ interface CleanResult {
  */
 async function killAllTmuxSessions(overstoryDir: string, projectName: string): Promise<number> {
 	let killed = 0;
-	const projectPrefix = `overstory-${projectName}-`;
+	const projectPrefix = `overstory-${sanitizeTmuxName(projectName)}-`;
 	try {
 		const tmuxSessions = await listSessions();
 		const overStorySessions = tmuxSessions.filter((s) => s.name.startsWith(projectPrefix));

package/src/commands/completions.test.ts

@@ -12,7 +12,10 @@ import {
 } from "./completions.ts";
 
 afterEach(() => {
-	process.exitCode = undefined;
+	// Use 0 not undefined — Bun doesn't reliably clear a nonzero exitCode when
+	// reassigned to undefined (see prior fix f3fde1a). If the 1 from completion
+	// tests leaks to bun test's shutdown, the suite exits 1 with 0 test failures.
+	process.exitCode = 0;
 });
 
 describe("COMMANDS array", () => {

package/src/commands/coordinator.ts

@@ -37,6 +37,7 @@ import {
 	ensureTmuxAvailable,
 	isSessionAlive,
 	killSession,
+	sanitizeTmuxName,
 	sendKeys,
 	TMUX_SOCKET,
 	waitForTuiReady,
@@ -76,7 +77,7 @@ const ASK_DEFAULT_TIMEOUT_S = 120;
  * Includes the project name to prevent cross-project collisions (overstory-pcef).
  */
 function coordinatorTmuxSession(projectName: string, name: string = COORDINATOR_NAME): string {
-	return `overstory-${projectName}-${name}`;
+	return `overstory-${sanitizeTmuxName(projectName)}-${name}`;
 }
 
 /** Dependency injection for testing. Uses real implementations when omitted. */

package/src/commands/doctor.ts

@@ -158,10 +158,81 @@ export interface DoctorCommandOptions {
 	checkRunners?: Array<{ category: DoctorCategory; fn: DoctorCheckFn }>;
 }
 
+interface DoctorActionOpts {
+	json?: boolean;
+	verbose?: boolean;
+	category?: string;
+	fix?: boolean;
+}
+
 /**
- * Create the Commander command for `overstory doctor`.
+ * Run the doctor checks. Returns true if any check failed.
+ * Shared by both the Commander action and the programmatic entry point so the
+ * exit-code signal never has to travel through `process.exitCode` (which is
+ * global mutable state and races with other tests in parallel bun test runs).
  */
-export function createDoctorCommand(options?: DoctorCommandOptions): Command {
+async function runDoctorChecks(
+	opts: DoctorActionOpts,
+	checkRunners: Array<{ category: DoctorCategory; fn: DoctorCheckFn }>,
+): Promise<boolean> {
+	const json = opts.json ?? false;
+	const verbose = opts.verbose ?? false;
+	const categoryFilter = opts.category;
+	const fix = opts.fix ?? false;
+
+	if (categoryFilter !== undefined) {
+		const validCategories = ALL_CHECKS.map((c) => c.category);
+		if (!validCategories.includes(categoryFilter as DoctorCategory)) {
+			throw new ValidationError(
+				`Invalid category: ${categoryFilter}. Valid categories: ${validCategories.join(", ")}`,
+				{
+					field: "category",
+					value: categoryFilter,
+				},
+			);
+		}
+	}
+
+	const cwd = process.cwd();
+	const config = await loadConfig(cwd);
+	const overstoryDir = join(config.project.root, ".overstory");
+
+	const checksToRun = categoryFilter
+		? checkRunners.filter((c) => c.category === categoryFilter)
+		: checkRunners;
+
+	let results: DoctorCheck[] = [];
+	for (const { fn } of checksToRun) {
+		const checkResults = await fn(config, overstoryDir);
+		results.push(...checkResults);
+	}
+
+	let fixedItems: string[] | undefined;
+	if (fix) {
+		const applied = await applyFixes(results);
+		if (applied.length > 0) {
+			fixedItems = applied;
+			results = [];
+			for (const { fn } of checksToRun) {
+				const checkResults = await fn(config, overstoryDir);
+				results.push(...checkResults);
+			}
+		}
+	}
+
+	if (json) {
+		printJSON(results, fixedItems);
+	} else {
+		printHumanReadable(results, verbose, checkRunners, fixedItems);
+	}
+
+	return results.some((c) => c.status === "fail");
+}
+
+function buildDoctorCommand(
+	onResult: (hasFailures: boolean) => void,
+	checkRunners: Array<{ category: DoctorCategory; fn: DoctorCheckFn }>,
+): Command {
 	return new Command("doctor")
 		.description("Run health checks on overstory setup")
 		.option("--json", "Output as JSON")
@@ -172,73 +243,20 @@ export function createDoctorCommand(options?: DoctorCommandOptions): Command {
 			"after",
 			"\nCategories: dependencies, structure, config, databases, consistency, agents, merge, logs, version, ecosystem, providers, watchdog",
 		)
-		.action(
-			async (opts: { json?: boolean; verbose?: boolean; category?: string; fix?: boolean }) => {
-				const json = opts.json ?? false;
-				const verbose = opts.verbose ?? false;
-				const categoryFilter = opts.category;
-				const fix = opts.fix ?? false;
-
-				// Validate category filter if provided
-				if (categoryFilter !== undefined) {
-					const validCategories = ALL_CHECKS.map((c) => c.category);
-					if (!validCategories.includes(categoryFilter as DoctorCategory)) {
-						throw new ValidationError(
-							`Invalid category: ${categoryFilter}. Valid categories: ${validCategories.join(", ")}`,
-							{
-								field: "category",
-								value: categoryFilter,
-							},
-						);
-					}
-				}
-
-				const cwd = process.cwd();
-				const config = await loadConfig(cwd);
-				const overstoryDir = join(config.project.root, ".overstory");
-
-				// Filter checks by category if specified
-				const allChecks = options?.checkRunners ?? ALL_CHECKS;
-				const checksToRun = categoryFilter
-					? allChecks.filter((c) => c.category === categoryFilter)
-					: allChecks;
-
-				// Run all checks sequentially
-				let results: DoctorCheck[] = [];
-				for (const { fn } of checksToRun) {
-					const checkResults = await fn(config, overstoryDir);
-					results.push(...checkResults);
-				}
-
-				// Apply fixes if requested
-				let fixedItems: string[] | undefined;
-				if (fix) {
-					const applied = await applyFixes(results);
-					if (applied.length > 0) {
-						fixedItems = applied;
-						// Re-run all checks to get fresh results after fixes
-						results = [];
-						for (const { fn } of checksToRun) {
-							const checkResults = await fn(config, overstoryDir);
-							results.push(...checkResults);
-						}
-					}
-				}
-
-				// Output results
-				if (json) {
-					printJSON(results, fixedItems);
-				} else {
-					printHumanReadable(results, verbose, allChecks, fixedItems);
-				}
+		.action(async (opts: DoctorActionOpts) => {
+			onResult(await runDoctorChecks(opts, checkRunners));
+		});
+}
 
-				// Set exit code if any check failed
-				const hasFailures = results.some((c) => c.status === "fail");
-				if (hasFailures) {
-					process.exitCode = 1;
-				}
-			},
-		);
+/**
+ * Create the Commander command for `overstory doctor`.
+ */
+export function createDoctorCommand(options?: DoctorCommandOptions): Command {
+	return buildDoctorCommand((hasFailures) => {
+		if (hasFailures) {
+			process.exitCode = 1;
+		}
+	}, options?.checkRunners ?? ALL_CHECKS);
 }
 
 /**
@@ -250,16 +268,15 @@ export async function doctorCommand(
 	args: string[],
 	options?: DoctorCommandOptions,
 ): Promise<number | undefined> {
-	const cmd = createDoctorCommand(options);
+	let hasFailures = false;
+	const cmd = buildDoctorCommand((result) => {
+		hasFailures = result;
+	}, options?.checkRunners ?? ALL_CHECKS);
 	cmd.exitOverride();
 
-	const prevExitCode = process.exitCode as number | undefined;
-	process.exitCode = undefined;
-
 	try {
 		await cmd.parseAsync(args, { from: "user" });
 	} catch (err: unknown) {
-		process.exitCode = prevExitCode;
 		if (err && typeof err === "object" && "code" in err) {
 			const code = (err as { code: string }).code;
 			if (code === "commander.helpDisplayed" || code === "commander.version") {
@@ -269,7 +286,5 @@ export async function doctorCommand(
 		throw err;
 	}
 
-	const exitCode = process.exitCode === 1 ? 1 : undefined;
-	process.exitCode = prevExitCode;
-	return exitCode;
+	return hasFailures ? 1 : undefined;
 }

package/src/commands/monitor.ts

@@ -29,6 +29,7 @@ import {
 	createSession,
 	isSessionAlive,
 	killSession,
+	sanitizeTmuxName,
 	sendKeys,
 	TMUX_SOCKET,
 } from "../worktree/tmux.ts";
@@ -42,7 +43,7 @@ const MONITOR_NAME = "monitor";
  * Includes the project name to prevent cross-project collisions (overstory-pcef).
  */
 function monitorTmuxSession(projectName: string): string {
-	return `overstory-${projectName}-${MONITOR_NAME}`;
+	return `overstory-${sanitizeTmuxName(projectName)}-${MONITOR_NAME}`;
 }
 
 /**

package/src/commands/sling.test.ts

@@ -1038,6 +1038,18 @@ describe("sling provider env injection building blocks", () => {
 		expect(combined.OVERSTORY_TASK_ID).toBe("overstory-1234");
 	});
 
+	test("env dict includes OVERSTORY_PROJECT_ROOT", () => {
+		const env = { MODEL_KEY: "value" };
+		const combined = {
+			...env,
+			OVERSTORY_AGENT_NAME: "test-builder",
+			OVERSTORY_WORKTREE_PATH: "/path/to/wt",
+			OVERSTORY_TASK_ID: "task-1",
+			OVERSTORY_PROJECT_ROOT: "/path/to/project",
+		};
+		expect(combined.OVERSTORY_PROJECT_ROOT).toBe("/path/to/project");
+	});
+
 	test("resolveModel returns no env for native anthropic provider", () => {
 		const config = makeConfig({ builder: "sonnet" }, { anthropic: { type: "native" } });
 		const manifest = makeManifest();

package/src/commands/sling.ts

@@ -48,6 +48,7 @@ import {
 	ensureTmuxAvailable,
 	isSessionAlive,
 	killSession,
+	sanitizeTmuxName,
 	sendKeys,
 	waitForTuiReady,
 } from "../worktree/tmux.ts";
@@ -924,6 +925,7 @@ export async function slingCommand(taskId: string, opts: SlingOptions): Promise<
 					OVERSTORY_AGENT_NAME: name,
 					OVERSTORY_WORKTREE_PATH: worktreePath,
 					OVERSTORY_TASK_ID: taskId,
+					OVERSTORY_PROJECT_ROOT: config.project.root,
 				};
 				const argv = runtime.buildDirectSpawn({
 					cwd: worktreePath,
@@ -1004,7 +1006,7 @@ export async function slingCommand(taskId: string, opts: SlingOptions): Promise<
 				await ensureTmuxAvailable();
 
 				// 12. Create tmux session running claude in interactive mode
-				const tmuxSessionName = `overstory-${config.project.name}-${name}`;
+				const tmuxSessionName = `overstory-${sanitizeTmuxName(config.project.name)}-${name}`;
 				const spawnCmd = runtime.buildSpawnCommand({
 					model: resolvedModel.model,
 					permissionMode: "bypass",
@@ -1015,6 +1017,7 @@ export async function slingCommand(taskId: string, opts: SlingOptions): Promise<
 						OVERSTORY_AGENT_NAME: name,
 						OVERSTORY_WORKTREE_PATH: worktreePath,
 						OVERSTORY_TASK_ID: taskId,
+						OVERSTORY_PROJECT_ROOT: config.project.root,
 					},
 				});
 				const pid = await createSession(tmuxSessionName, worktreePath, spawnCmd, {
@@ -1022,6 +1025,7 @@ export async function slingCommand(taskId: string, opts: SlingOptions): Promise<
 					OVERSTORY_AGENT_NAME: name,
 					OVERSTORY_WORKTREE_PATH: worktreePath,
 					OVERSTORY_TASK_ID: taskId,
+					OVERSTORY_PROJECT_ROOT: config.project.root,
 				});
 
 				// 13. Record session BEFORE sending the beacon so that hook-triggered

package/src/commands/supervisor.ts

@@ -29,6 +29,7 @@ import {
 	createSession,
 	isSessionAlive,
 	killSession,
+	sanitizeTmuxName,
 	sendKeys,
 	waitForTuiReady,
 } from "../worktree/tmux.ts";
@@ -170,7 +171,7 @@ async function startSupervisor(opts: {
 		// Spawn tmux session at project root with Claude Code (interactive mode).
 		// Inject the supervisor base definition via --append-system-prompt.
 		// Pass file path (not content) to avoid tmux "command too long" (overstory#45).
-		const tmuxSession = `overstory-${config.project.name}-supervisor-${opts.name}`;
+		const tmuxSession = `overstory-${sanitizeTmuxName(config.project.name)}-supervisor-${opts.name}`;
 		const agentDefPath = join(projectRoot, ".overstory", "agent-defs", "supervisor.md");
 		const agentDefFile = Bun.file(agentDefPath);
 		let appendSystemPromptFile: string | undefined;

package/src/commands/watch.test.ts

@@ -27,7 +27,6 @@ describe("watchCommand", () => {
 	let originalStderrWrite: typeof process.stderr.write;
 	let tempDir: string;
 	let originalCwd: string;
-	let originalExitCode: string | number | null | undefined;
 
 	beforeEach(async () => {
 		// Spy on stdout
@@ -46,8 +45,6 @@ describe("watchCommand", () => {
 			return true;
 		}) as typeof process.stderr.write;
 
-		// Save original exitCode
-		originalExitCode = process.exitCode;
 		process.exitCode = 0;
 
 		// Create temp dir with .overstory/config.yaml structure
@@ -66,7 +63,12 @@ describe("watchCommand", () => {
 	afterEach(async () => {
 		process.stdout.write = originalWrite;
 		process.stderr.write = originalStderrWrite;
-		process.exitCode = originalExitCode;
+		// Unconditionally clear to 0 rather than restoring a captured "original" that
+		// could itself have been polluted by a parallel test file in the same bun
+		// process. `watchCommand` sets `process.exitCode = 1` as a side effect, so
+		// without this clear the 1 can leak all the way to bun test's shutdown and
+		// turn a fully-green run into exit 1.
+		process.exitCode = 0;
 		process.chdir(originalCwd);
 		await cleanupTempDir(tempDir);
 	});

package/src/commands/worktree.test.ts

@@ -1,13 +1,14 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import { existsSync, realpathSync } from "node:fs";
-import { mkdir } from "node:fs/promises";
+import { existsSync, mkdirSync, realpathSync } from "node:fs";
+import { mkdir, mkdtemp } from "node:fs/promises";
+import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { ValidationError } from "../errors.ts";
 import { createSessionStore } from "../sessions/store.ts";
 import { cleanupTempDir, commitFile, createTempGitRepo, runGitInDir } from "../test-helpers.ts";
 import type { AgentSession } from "../types.ts";
 import { createWorktree } from "../worktree/manager.ts";
-import { worktreeCommand } from "./worktree.ts";
+import { checkLiveChildren, worktreeCommand } from "./worktree.ts";
 
 /**
  * Tests for `overstory worktree` command.
@@ -974,5 +975,320 @@ describe("worktreeCommand", () => {
 			expect(parsed.cleaned).toContain(branch);
 			expect(parsed.seedsPreserved).toContain(branch);
 		});
+
+		describe("live-children guard", () => {
+			/**
+			 * Write sessions into a nested .overstory/sessions.db inside a worktree.
+			 * Simulates a lead worktree that has spawned builder children.
+			 */
+			function writeNestedSessions(worktreePath: string, sessions: AgentSession[]): void {
+				const nestedOverstory = join(worktreePath, ".overstory");
+				mkdirSync(nestedOverstory, { recursive: true });
+				const store = createSessionStore(join(nestedOverstory, "sessions.db"));
+				for (const s of sessions) {
+					store.upsert(s);
+				}
+				store.close();
+			}
+
+			test("clean skipped when live children present (no --force)", async () => {
+				const worktreesDir = join(tempDir, ".overstory", "worktrees");
+				await mkdir(worktreesDir, { recursive: true });
+
+				const { path: wtPath } = await createWorktree({
+					repoRoot: tempDir,
+					baseDir: worktreesDir,
+					agentName: "lead-with-children",
+					baseBranch: "main",
+					taskId: "task-lead",
+				});
+
+				// Parent session is completed
+				writeSessionsToStore([
+					makeSession({
+						id: "session-lead",
+						agentName: "lead-with-children",
+						capability: "lead",
+						worktreePath: wtPath,
+						branchName: "overstory/lead-with-children/task-lead",
+						taskId: "task-lead",
+						state: "completed",
+					}),
+				]);
+
+				// Nested session with process.pid (guaranteed alive)
+				writeNestedSessions(wtPath, [
+					{
+						id: "nested-builder",
+						agentName: "nested-builder",
+						capability: "builder",
+						worktreePath: join(wtPath, ".overstory", "worktrees", "nested-builder"),
+						branchName: "overstory/nested-builder/task-child",
+						taskId: "task-child",
+						tmuxSession: "overstory-nested-builder-fake",
+						state: "working",
+						pid: process.pid, // current process — guaranteed alive
+						parentAgent: "lead-with-children",
+						depth: 2,
+						runId: null,
+						startedAt: new Date().toISOString(),
+						lastActivity: new Date().toISOString(),
+						escalationLevel: 0,
+						stalledSince: null,
+						transcriptPath: null,
+					},
+				]);
+
+				await worktreeCommand(["clean", "--completed", "--json"]);
+				const out = output();
+
+				const parsed = JSON.parse(out.trim()) as {
+					cleaned: string[];
+					blockedByChildren: string[];
+				};
+
+				expect(parsed.cleaned).toEqual([]);
+				expect(parsed.blockedByChildren).toContain("overstory/lead-with-children/task-lead");
+				// Worktree still exists
+				expect(existsSync(wtPath)).toBe(true);
+			});
+
+			test("clean proceeds when nested sessions are dead (pid unreachable)", async () => {
+				const worktreesDir = join(tempDir, ".overstory", "worktrees");
+				await mkdir(worktreesDir, { recursive: true });
+
+				const { path: wtPath } = await createWorktree({
+					repoRoot: tempDir,
+					baseDir: worktreesDir,
+					agentName: "lead-dead-children",
+					baseBranch: "main",
+					taskId: "task-dead",
+				});
+
+				writeSessionsToStore([
+					makeSession({
+						id: "session-lead-dead",
+						agentName: "lead-dead-children",
+						capability: "lead",
+						worktreePath: wtPath,
+						branchName: "overstory/lead-dead-children/task-dead",
+						taskId: "task-dead",
+						state: "completed",
+					}),
+				]);
+
+				// Nested session with a dead pid (extremely high, will not exist)
+				writeNestedSessions(wtPath, [
+					{
+						id: "nested-dead",
+						agentName: "nested-dead",
+						capability: "builder",
+						worktreePath: join(wtPath, ".overstory", "worktrees", "nested-dead"),
+						branchName: "overstory/nested-dead/task-dead-child",
+						taskId: "task-dead-child",
+						tmuxSession: "overstory-nested-dead-fake",
+						state: "working",
+						pid: 999999999, // dead pid
+						parentAgent: "lead-dead-children",
+						depth: 2,
+						runId: null,
+						startedAt: new Date().toISOString(),
+						lastActivity: new Date().toISOString(),
+						escalationLevel: 0,
+						stalledSince: null,
+						transcriptPath: null,
+					},
+				]);
+
+				await worktreeCommand(["clean", "--completed", "--json"]);
+				const out = output();
+
+				const parsed = JSON.parse(out.trim()) as {
+					cleaned: string[];
+					blockedByChildren: string[];
+				};
+
+				expect(parsed.cleaned).toContain("overstory/lead-dead-children/task-dead");
+				expect(parsed.blockedByChildren).toEqual([]);
+				expect(existsSync(wtPath)).toBe(false);
+			});
+
+			test("--force removes worktree even with live children", async () => {
+				const worktreesDir = join(tempDir, ".overstory", "worktrees");
+				await mkdir(worktreesDir, { recursive: true });
+
+				const { path: wtPath } = await createWorktree({
+					repoRoot: tempDir,
+					baseDir: worktreesDir,
+					agentName: "lead-force",
+					baseBranch: "main",
+					taskId: "task-force-children",
+				});
+
+				writeSessionsToStore([
+					makeSession({
+						id: "session-lead-force",
+						agentName: "lead-force",
+						capability: "lead",
+						worktreePath: wtPath,
+						branchName: "overstory/lead-force/task-force-children",
+						taskId: "task-force-children",
+						state: "completed",
+					}),
+				]);
+
+				// Use a dead pid — avoids actually killing any live process,
+				// but still exercises the --force code path.
+				writeNestedSessions(wtPath, [
+					{
+						id: "nested-force",
+						agentName: "nested-force",
+						capability: "builder",
+						worktreePath: join(wtPath, ".overstory", "worktrees", "nested-force"),
+						branchName: "overstory/nested-force/task-force-child",
+						taskId: "task-force-child",
+						tmuxSession: "overstory-nested-force-fake",
+						state: "working",
+						pid: 999999999, // dead pid, safe to kill
+						parentAgent: "lead-force",
+						depth: 2,
+						runId: null,
+						startedAt: new Date().toISOString(),
+						lastActivity: new Date().toISOString(),
+						escalationLevel: 0,
+						stalledSince: null,
+						transcriptPath: null,
+					},
+				]);
+
+				await worktreeCommand(["clean", "--force", "--json"]);
+				const out = output();
+
+				const parsed = JSON.parse(out.trim()) as {
+					cleaned: string[];
+					blockedByChildren: string[];
+				};
+
+				// Should be cleaned (not blocked) even though nested sessions existed
+				expect(parsed.cleaned).toContain("overstory/lead-force/task-force-children");
+				expect(existsSync(wtPath)).toBe(false);
+			});
+
+			test("no nested .overstory — treated as no live children, clean proceeds", async () => {
+				const worktreesDir = join(tempDir, ".overstory", "worktrees");
+				await mkdir(worktreesDir, { recursive: true });
+
+				const { path: wtPath } = await createWorktree({
+					repoRoot: tempDir,
+					baseDir: worktreesDir,
+					agentName: "lead-no-nested",
+					baseBranch: "main",
+					taskId: "task-no-nested",
+				});
+
+				writeSessionsToStore([
+					makeSession({
+						id: "session-lead-no-nested",
+						agentName: "lead-no-nested",
+						capability: "lead",
+						worktreePath: wtPath,
+						branchName: "overstory/lead-no-nested/task-no-nested",
+						taskId: "task-no-nested",
+						state: "completed",
+					}),
+				]);
+
+				// No nested .overstory/ directory written
+
+				await worktreeCommand(["clean", "--completed", "--json"]);
+				const out = output();
+
+				const parsed = JSON.parse(out.trim()) as {
+					cleaned: string[];
+					blockedByChildren: string[];
+				};
+
+				expect(parsed.cleaned).toContain("overstory/lead-no-nested/task-no-nested");
+				expect(parsed.blockedByChildren).toEqual([]);
+				expect(existsSync(wtPath)).toBe(false);
+			});
+		});
+	});
+});
+
+describe("checkLiveChildren", () => {
+	let tempDir: string;
+
+	beforeEach(async () => {
+		tempDir = await mkdtemp(join(tmpdir(), "overstory-checkchildren-"));
+	});
+
+	afterEach(async () => {
+		await cleanupTempDir(tempDir);
+	});
+
+	test("returns empty array when no nested .overstory/sessions.db", async () => {
+		const result = await checkLiveChildren(tempDir);
+		expect(result).toEqual([]);
+	});
+
+	test("returns empty array when all sessions are completed", async () => {
+		const nestedOverstory = join(tempDir, ".overstory");
+		mkdirSync(nestedOverstory, { recursive: true });
+		const store = createSessionStore(join(nestedOverstory, "sessions.db"));
+		store.upsert({
+			id: "s1",
+			agentName: "done-agent",
+			capability: "builder",
+			worktreePath: "/fake/wt",
+			branchName: "overstory/done/task",
+			taskId: "task",
+			tmuxSession: "",
+			state: "completed",
+			pid: process.pid,
+			parentAgent: null,
+			depth: 2,
+			runId: null,
+			startedAt: new Date().toISOString(),
+			lastActivity: new Date().toISOString(),
+			escalationLevel: 0,
+			stalledSince: null,
+			transcriptPath: null,
+		});
+		store.close();
+
+		const result = await checkLiveChildren(tempDir);
+		expect(result).toEqual([]);
+	});
+
+	test("returns live children when working session with alive pid exists", async () => {
+		const nestedOverstory = join(tempDir, ".overstory");
+		mkdirSync(nestedOverstory, { recursive: true });
+		const store = createSessionStore(join(nestedOverstory, "sessions.db"));
+		store.upsert({
+			id: "s1",
+			agentName: "live-agent",
+			capability: "builder",
+			worktreePath: "/fake/wt",
+			branchName: "overstory/live/task",
+			taskId: "task",
+			tmuxSession: "",
+			state: "working",
+			pid: process.pid, // current process — alive
+			parentAgent: null,
+			depth: 2,
+			runId: null,
+			startedAt: new Date().toISOString(),
+			lastActivity: new Date().toISOString(),
+			escalationLevel: 0,
+			stalledSince: null,
+			transcriptPath: null,
+		});
+		store.close();
+
+		const result = await checkLiveChildren(tempDir);
+		expect(result).toHaveLength(1);
+		expect(result[0]?.agentName).toBe("live-agent");
+		expect(result[0]?.pid).toBe(process.pid);
 	});
 });

package/src/commands/worktree.ts

@@ -6,6 +6,7 @@
  * Logs are never auto-deleted.
  */
 
+import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { Command } from "commander";
 import { loadConfig } from "../config.ts";
@@ -14,6 +15,7 @@ import { jsonOutput } from "../json.ts";
 import { printHint, printSuccess, printWarning } from "../logging/color.ts";
 import { createMailStore } from "../mail/store.ts";
 import { openSessionStore } from "../sessions/compat.ts";
+import { createSessionStore } from "../sessions/store.ts";
 import type { AgentSession } from "../types.ts";
 import {
 	isBranchMerged,
@@ -23,6 +25,51 @@ import {
 } from "../worktree/manager.ts";
 import { isSessionAlive, killSession } from "../worktree/tmux.ts";
 
+/**
+ * Check for live child sessions nested inside a worktree's own .overstory/sessions.db.
+ *
+ * Returns the live children (agentName + pid). Empty array if no nested DB or no live children.
+ */
+export async function checkLiveChildren(
+	worktreePath: string,
+): Promise<{ agentName: string; pid: number }[]> {
+	const nestedDb = join(worktreePath, ".overstory", "sessions.db");
+	if (!existsSync(nestedDb)) {
+		return [];
+	}
+
+	const store = createSessionStore(nestedDb);
+	let sessions: AgentSession[];
+	try {
+		sessions = store.getAll();
+	} finally {
+		store.close();
+	}
+
+	const deadStates = new Set(["completed", "zombie"]);
+	const liveChildren: { agentName: string; pid: number }[] = [];
+
+	for (const session of sessions) {
+		if (deadStates.has(session.state)) continue;
+		if (session.pid === null) continue;
+
+		// process.kill(pid, 0) throws if the process is dead (ESRCH)
+		let alive = false;
+		try {
+			process.kill(session.pid, 0);
+			alive = true;
+		} catch {
+			// ESRCH — process is dead
+		}
+
+		if (alive) {
+			liveChildren.push({ agentName: session.agentName, pid: session.pid });
+		}
+	}
+
+	return liveChildren;
+}
+
 /**
  * Handle `ov worktree list`.
  */
@@ -100,6 +147,7 @@ async function handleClean(
 	const failed: string[] = [];
 	const skipped: string[] = [];
 	const seedsPreserved: string[] = [];
+	const blockedByChildren: string[] = [];
 
 	try {
 		for (const wt of overstoryWts) {
@@ -129,6 +177,33 @@ async function handleClean(
 				}
 			}
 
+			// Live-children guard: refuse to remove a worktree that has active nested agents.
+			// Nested sessions live in {wt.path}/.overstory/sessions.db (lead worktrees).
+			const liveChildren = await checkLiveChildren(wt.path);
+			if (liveChildren.length > 0) {
+				if (!force) {
+					blockedByChildren.push(wt.branch);
+					continue;
+				}
+				// --force: SIGTERM each live child, wait briefly, then proceed.
+				if (!json) {
+					printWarning(
+						`Force-terminating ${liveChildren.length} live child${liveChildren.length === 1 ? "" : "ren"} in ${wt.branch}`,
+					);
+					for (const child of liveChildren) {
+						process.stdout.write(`  ${child.agentName} (pid ${child.pid})\n`);
+					}
+				}
+				for (const child of liveChildren) {
+					try {
+						process.kill(child.pid, "SIGTERM");
+					} catch {
+						// Best effort
+					}
+				}
+				await Bun.sleep(500);
+			}
+
 			// If --all, clean everything
 			// Kill tmux session if still alive
 			if (session?.tmuxSession) {
@@ -243,6 +318,7 @@ async function handleClean(
 				cleaned,
 				failed,
 				skipped,
+				blockedByChildren,
 				pruned: pruneCount,
 				mailPurged,
 				seedsPreserved,
@@ -252,6 +328,7 @@ async function handleClean(
 			pruneCount === 0 &&
 			failed.length === 0 &&
 			skipped.length === 0 &&
+			blockedByChildren.length === 0 &&
 			seedsPreserved.length === 0
 		) {
 			printHint("No worktrees to clean");
@@ -286,6 +363,15 @@ async function handleClean(
 				}
 				printHint("Use --force to delete unmerged branches");
 			}
+			if (blockedByChildren.length > 0) {
+				printWarning(
+					`Skipped ${blockedByChildren.length} worktree${blockedByChildren.length === 1 ? "" : "s"} with live child agents`,
+				);
+				for (const branch of blockedByChildren) {
+					process.stdout.write(`  ${branch}\n`);
+				}
+				printHint("Use --force to cascade-terminate live children");
+			}
 		}
 	} finally {
 		store.close();

package/src/config.test.ts

@@ -1177,6 +1177,84 @@ describe("resolveProjectRoot", () => {
 	});
 });
 
+describe("resolveProjectRoot — env var and walk-up", () => {
+	let tempDir: string;
+	let savedEnv: string | undefined;
+
+	beforeEach(async () => {
+		tempDir = await mkdtemp(join(tmpdir(), "overstory-envtest-"));
+		savedEnv = process.env.OVERSTORY_PROJECT_ROOT;
+		delete process.env.OVERSTORY_PROJECT_ROOT;
+		clearProjectRootOverride();
+	});
+
+	afterEach(async () => {
+		if (savedEnv !== undefined) {
+			process.env.OVERSTORY_PROJECT_ROOT = savedEnv;
+		} else {
+			delete process.env.OVERSTORY_PROJECT_ROOT;
+		}
+		clearProjectRootOverride();
+		await cleanupTempDir(tempDir);
+	});
+
+	test("OVERSTORY_PROJECT_ROOT env var is returned immediately", async () => {
+		await mkdir(join(tempDir, ".overstory"), { recursive: true });
+		await Bun.write(
+			join(tempDir, ".overstory", "config.yaml"),
+			"project:\n  canonicalBranch: main\n",
+		);
+		process.env.OVERSTORY_PROJECT_ROOT = tempDir;
+		const result = await resolveProjectRoot("/some/unrelated/path");
+		expect(result).toBe(tempDir);
+	});
+
+	test("env var beats walk-up worktree resolution", async () => {
+		// Set up a parent root with config.yaml
+		const parentRoot = tempDir;
+		await mkdir(join(parentRoot, ".overstory", "worktrees", "some-agent"), { recursive: true });
+		await Bun.write(
+			join(parentRoot, ".overstory", "config.yaml"),
+			"project:\n  canonicalBranch: main\n",
+		);
+		const worktreePath = join(parentRoot, ".overstory", "worktrees", "some-agent");
+		// Even though walk-up would resolve parentRoot, env var pointing elsewhere wins
+		const envTarget = await mkdtemp(join(tmpdir(), "overstory-envtarget-"));
+		try {
+			process.env.OVERSTORY_PROJECT_ROOT = envTarget;
+			const result = await resolveProjectRoot(worktreePath);
+			expect(result).toBe(envTarget);
+		} finally {
+			await cleanupTempDir(envTarget);
+		}
+	});
+
+	test("walk-up resolves submodule path without git", async () => {
+		// Simulate a submodule worktree: {tempDir}/.overstory/worktrees/my-agent/sub
+		// config.yaml exists at {tempDir}/.overstory/config.yaml
+		const worktreeBase = join(tempDir, ".overstory", "worktrees", "my-agent");
+		const subDir = join(worktreeBase, "sub");
+		await mkdir(subDir, { recursive: true });
+		await mkdir(join(tempDir, ".overstory"), { recursive: true });
+		await Bun.write(
+			join(tempDir, ".overstory", "config.yaml"),
+			"project:\n  canonicalBranch: main\n",
+		);
+		const result = await resolveProjectRoot(subDir);
+		expect(result).toBe(tempDir);
+	});
+
+	test("walk-up is skipped when parent has no config.yaml", async () => {
+		// Same path structure but NO config.yaml at parentRoot
+		const worktreeBase = join(tempDir, ".overstory", "worktrees", "my-agent");
+		await mkdir(worktreeBase, { recursive: true });
+		// No config.yaml written — walk-up guard should prevent false resolution
+		const result = await resolveProjectRoot(worktreeBase);
+		// Falls through to startDir fallback
+		expect(result).toBe(worktreeBase);
+	});
+});
+
 describe("projectRootOverride", () => {
 	let tempDir: string;
 

package/src/config.ts

@@ -905,7 +905,26 @@ export async function resolveProjectRoot(startDir: string): Promise<string> {
 
 	const { existsSync } = require("node:fs") as typeof import("node:fs");
 
-	// Check git worktree FIRST. When running from an agent worktree
+	// Check OVERSTORY_PROJECT_ROOT env var. Zero-heuristic — injected by ov sling
+	// into agent environments so submodule topology doesn't matter.
+	const envRoot = process.env.OVERSTORY_PROJECT_ROOT;
+	if (envRoot && envRoot.length > 0) {
+		return envRoot;
+	}
+
+	// Walk-up worktree-path detection. Topology-independent submodule fix:
+	// if startDir contains /.overstory/worktrees/ as a path segment, the
+	// substring before it is the project root — verify with config.yaml.
+	const WT_SEGMENT = `/${OVERSTORY_DIR}/worktrees/`;
+	const idx = startDir.indexOf(WT_SEGMENT);
+	if (idx > 0) {
+		const parentRoot = startDir.slice(0, idx);
+		if (existsSync(join(parentRoot, OVERSTORY_DIR, CONFIG_FILENAME))) {
+			return parentRoot;
+		}
+	}
+
+	// Check git worktree. When running from an agent worktree
 	// (e.g., .overstory/worktrees/{name}/), the worktree may contain
 	// tracked copies of .overstory/config.yaml. We must resolve to the
 	// main repository root so runtime state (mail.db, metrics.db, etc.)

package/src/doctor/consistency.ts

@@ -3,7 +3,7 @@ import { join } from "node:path";
 import { openSessionStore } from "../sessions/compat.ts";
 import type { AgentSession, OverstoryConfig } from "../types.ts";
 import { listWorktrees } from "../worktree/manager.ts";
-import { isProcessAlive, listSessions } from "../worktree/tmux.ts";
+import { isProcessAlive, listSessions, sanitizeTmuxName } from "../worktree/tmux.ts";
 import type { DoctorCheck } from "./types.ts";
 
 /**
@@ -134,7 +134,7 @@ export async function checkConsistency(
 
 	// 5. Check for orphaned tmux sessions (tmux session exists but no SessionStore entry)
 	const projectName = config.project.name;
-	const overstoryTmuxPrefix = `overstory-${projectName}-`;
+	const overstoryTmuxPrefix = `overstory-${sanitizeTmuxName(projectName)}-`;
 	const overstoryTmuxSessions = tmuxSessions.filter((s) => s.name.startsWith(overstoryTmuxPrefix));
 	const storeTmuxNames = new Set(storeSessions.map((s) => s.tmuxSession));
 

package/src/index.ts

@@ -51,7 +51,7 @@ import { ConfigError, OverstoryError, WorktreeError } from "./errors.ts";
 import { jsonError } from "./json.ts";
 import { brand, chalk, muted, setQuiet } from "./logging/color.ts";
 
-export const VERSION = "0.9.3";
+export const VERSION = "0.9.4";
 
 const rawArgs = process.argv.slice(2);
 

package/src/worktree/tmux.test.ts

@@ -13,6 +13,7 @@ import {
 	killProcessTree,
 	killSession,
 	listSessions,
+	sanitizeTmuxName,
 	sendKeys,
 	waitForTuiReady,
 } from "./tmux.ts";
@@ -1550,3 +1551,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.