@os-eco/overstory-cli 0.9.3 → 0.10.3

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

@@ -90,6 +90,7 @@ export const DEFAULT_CONFIG: OverstoryConfig = {
 		rpcTimeoutMs: 5_000, // 5 seconds for RPC getState() calls
 		triageTimeoutMs: 30_000, // 30 seconds for Tier 1 AI triage calls
 		maxEscalationLevel: 3, // Maximum escalation level before termination
+		notifyParentOnDeath: true, // Send worker_died mail to parent when watchdog terminates a child
 	},
 	coordinator: {
 		exitTriggers: {
@@ -633,6 +634,16 @@ function validateConfig(config: OverstoryConfig): void {
 		}
 	}
 
+	if (
+		config.watchdog.notifyParentOnDeath !== undefined &&
+		typeof config.watchdog.notifyParentOnDeath !== "boolean"
+	) {
+		throw new ValidationError("watchdog.notifyParentOnDeath must be a boolean", {
+			field: "watchdog.notifyParentOnDeath",
+			value: config.watchdog.notifyParentOnDeath,
+		});
+	}
+
 	// mulch.primeFormat must be one of the valid options
 	const validFormats = ["markdown", "xml", "json"] as const;
 	if (!validFormats.includes(config.mulch.primeFormat as (typeof validFormats)[number])) {
@@ -774,6 +785,18 @@ function validateConfig(config: OverstoryConfig): void {
 		}
 	}
 
+	// runtime.claudeHeadlessByDefault: must be a boolean if present
+	if (
+		config.runtime?.claudeHeadlessByDefault !== undefined &&
+		typeof config.runtime.claudeHeadlessByDefault !== "boolean"
+	) {
+		process.stderr.write(
+			`[overstory] WARNING: runtime.claudeHeadlessByDefault must be a boolean. Got: ${typeof config
+				.runtime.claudeHeadlessByDefault}. Ignoring.\n`,
+		);
+		config.runtime.claudeHeadlessByDefault = undefined;
+	}
+
 	if (config.runtime?.capabilities) {
 		for (const [cap, runtimeName] of Object.entries(config.runtime.capabilities)) {
 			if (runtimeName !== undefined && (typeof runtimeName !== "string" || runtimeName === "")) {
@@ -905,7 +928,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.)