@os-eco/overstory-cli 0.9.2 → 0.9.4

package/src/commands/init.ts

@@ -149,6 +149,39 @@ async function onboardTool(
 	}
 }
 
+/**
+ * Known runtime CLI candidates in detection priority order.
+ * First installed runtime wins.
+ */
+const RUNTIME_CANDIDATES: Array<{ name: string; cli: string }> = [
+	{ name: "claude", cli: "claude" },
+	{ name: "copilot", cli: "copilot" },
+	{ name: "gemini", cli: "gemini" },
+	{ name: "opencode", cli: "opencode" },
+	{ name: "sapling", cli: "sp" },
+	{ name: "pi", cli: "pi" },
+];
+
+/**
+ * Detect the default runtime by checking which coding agent CLIs are installed.
+ *
+ * Uses `which <cli>` via the spawner abstraction so detection is testable
+ * without real binaries on PATH. Returns the first installed runtime by
+ * priority order, or "claude" as the safe fallback.
+ *
+ * @param spawner - Spawner abstraction (defaults to Bun.spawn wrapper)
+ * @returns Runtime name suitable for config.runtime.default
+ */
+export async function detectDefaultRuntime(spawner: Spawner): Promise<string> {
+	for (const { name, cli } of RUNTIME_CANDIDATES) {
+		const result = await spawner(["which", cli]);
+		if (result.exitCode === 0) {
+			return name;
+		}
+	}
+	return "claude";
+}
+
 /**
  * Set up .gitattributes with merge=union entries for JSONL files.
  *
@@ -739,6 +772,12 @@ export async function initCommand(opts: InitOptions): Promise<void> {
 	// 2. Detect project info
 	const projectName = opts.name ?? (await detectProjectName(projectRoot));
 	const canonicalBranch = await detectCanonicalBranch(projectRoot);
+	let defaultRuntime = "claude";
+	try {
+		defaultRuntime = await detectDefaultRuntime(spawner);
+	} catch {
+		// Non-fatal: fall back to claude if runtime detection fails
+	}
 
 	process.stdout.write(`Initializing overstory for "${projectName}"...\n\n`);
 
@@ -775,6 +814,9 @@ export async function initCommand(opts: InitOptions): Promise<void> {
 	config.project.name = projectName;
 	config.project.root = projectRoot;
 	config.project.canonicalBranch = canonicalBranch;
+	if (config.runtime) {
+		config.runtime.default = defaultRuntime;
+	}
 
 	const configYaml = serializeConfigToYaml(config);
 	const configPath = join(overstoryPath, "config.yaml");

package/src/commands/inspect.ts

@@ -18,6 +18,7 @@ import { renderHeader, separator, stateIconColored } from "../logging/theme.ts";
 import { createMetricsStore } from "../metrics/store.ts";
 import { openSessionStore } from "../sessions/compat.ts";
 import type { AgentSession, StoredEvent, ToolStats } from "../types.ts";
+import { TMUX_SOCKET } from "../worktree/tmux.ts";
 
 /**
  * Extract current file from most recent Edit/Write/Read tool_start event.
@@ -72,10 +73,13 @@ function summarizeArgs(toolArgs: string | null): string {
  */
 async function captureTmux(sessionName: string, lines: number): Promise<string | null> {
 	try {
-		const proc = Bun.spawn(["tmux", "capture-pane", "-t", sessionName, "-p", "-S", `-${lines}`], {
-			stdout: "pipe",
-			stderr: "pipe",
-		});
+		const proc = Bun.spawn(
+			["tmux", "-L", TMUX_SOCKET, "capture-pane", "-t", sessionName, "-p", "-S", `-${lines}`],
+			{
+				stdout: "pipe",
+				stderr: "pipe",
+			},
+		);
 		const exitCode = await proc.exited;
 		if (exitCode !== 0) {
 			return null;

package/src/commands/monitor.ts

@@ -25,7 +25,14 @@ import { printHint, printSuccess } from "../logging/color.ts";
 import { getRuntime } from "../runtimes/registry.ts";
 import { openSessionStore } from "../sessions/compat.ts";
 import type { AgentSession } from "../types.ts";
-import { createSession, isSessionAlive, killSession, sendKeys } from "../worktree/tmux.ts";
+import {
+	createSession,
+	isSessionAlive,
+	killSession,
+	sanitizeTmuxName,
+	sendKeys,
+	TMUX_SOCKET,
+} from "../worktree/tmux.ts";
 import { isRunningAsRoot } from "./sling.ts";
 
 /** Default monitor agent name. */
@@ -36,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}`;
 }
 
 /**
@@ -215,7 +222,7 @@ async function startMonitor(opts: { json: boolean; attach: boolean }): Promise<v
 		}
 
 		if (shouldAttach) {
-			Bun.spawnSync(["tmux", "attach-session", "-t", tmuxSession], {
+			Bun.spawnSync(["tmux", "-L", TMUX_SOCKET, "attach-session", "-t", tmuxSession], {
 				stdio: ["inherit", "inherit", "inherit"],
 			});
 		}

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";
@@ -806,6 +807,11 @@ export async function slingCommand(taskId: string, opts: SlingOptions): Promise<
 			// Resolve runtime before overlayConfig so we can pass runtime.instructionPath
 			const runtime = getRuntime(opts.runtime, config, capability);
 
+			// Runtime-specific worktree preparation (e.g., Copilot folder trust)
+			if (runtime.prepareWorktree) {
+				await runtime.prepareWorktree(worktreePath);
+			}
+
 			const overlayConfig: OverlayConfig = {
 				agentName: name,
 				taskId: taskId,
@@ -919,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,
@@ -999,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",
@@ -1010,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, {
@@ -1017,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);
 	});
 });