@os-eco/overstory-cli 0.9.2 → 0.9.3

package/src/worktree/tmux.test.ts

@@ -102,13 +102,13 @@ describe("createSession", () => {
 		const tmuxCallArgs = spawnSpy.mock.calls[1] as unknown[];
 		const cmd = tmuxCallArgs[0] as string[];
 		expect(cmd[0]).toBe("tmux");
-		expect(cmd[1]).toBe("new-session");
-		expect(cmd[3]).toBe("-s");
-		expect(cmd[4]).toBe("my-session");
-		expect(cmd[5]).toBe("-c");
-		expect(cmd[6]).toBe("/work/dir");
+		expect(cmd[3]).toBe("new-session");
+		expect(cmd[5]).toBe("-s");
+		expect(cmd[6]).toBe("my-session");
+		expect(cmd[7]).toBe("-c");
+		expect(cmd[8]).toBe("/work/dir");
 		// The command should be wrapped with PATH export
-		const wrappedCmd = cmd[7] as string;
+		const wrappedCmd = cmd[9] as string;
 		expect(wrappedCmd).toContain("echo hello");
 		expect(wrappedCmd).toContain("export PATH=");
 
@@ -136,7 +136,16 @@ describe("createSession", () => {
 		expect(spawnSpy).toHaveBeenCalledTimes(3);
 		const thirdCallArgs = spawnSpy.mock.calls[2] as unknown[];
 		const cmd = thirdCallArgs[0] as string[];
-		expect(cmd).toEqual(["tmux", "list-panes", "-t", "test-agent", "-F", "#{pane_pid}"]);
+		expect(cmd).toEqual([
+			"tmux",
+			"-L",
+			"overstory",
+			"list-panes",
+			"-t",
+			"test-agent",
+			"-F",
+			"#{pane_pid}",
+		]);
 	});
 
 	test("throws AgentError if session creation fails", async () => {
@@ -239,7 +248,7 @@ describe("createSession", () => {
 		// Call 0: which ov, Call 1: which overstory, Call 2: tmux new-session
 		const tmuxCallArgs = spawnSpy.mock.calls[2] as unknown[];
 		const cmd = tmuxCallArgs[0] as string[];
-		const tmuxCmd = cmd[7] as string;
+		const tmuxCmd = cmd[9] as string;
 		expect(tmuxCmd).toContain("echo test");
 	});
 
@@ -360,7 +369,14 @@ describe("listSessions", () => {
 		expect(spawnSpy).toHaveBeenCalledTimes(1);
 		const callArgs = spawnSpy.mock.calls[0] as unknown[];
 		const cmd = callArgs[0] as string[];
-		expect(cmd).toEqual(["tmux", "list-sessions", "-F", "#{session_name}:#{pid}"]);
+		expect(cmd).toEqual([
+			"tmux",
+			"-L",
+			"overstory",
+			"list-sessions",
+			"-F",
+			"#{session_name}:#{pid}",
+		]);
 	});
 });
 
@@ -383,7 +399,16 @@ describe("getPanePid", () => {
 		expect(pid).toBe(42);
 		const callArgs = spawnSpy.mock.calls[0] as unknown[];
 		const cmd = callArgs[0] as string[];
-		expect(cmd).toEqual(["tmux", "display-message", "-p", "-t", "overstory-auth", "#{pane_pid}"]);
+		expect(cmd).toEqual([
+			"tmux",
+			"-L",
+			"overstory",
+			"display-message",
+			"-p",
+			"-t",
+			"overstory-auth",
+			"#{pane_pid}",
+		]);
 	});
 
 	test("returns null when session does not exist", async () => {
@@ -679,7 +704,7 @@ describe("killSession", () => {
 			const cmd = args[0] as string[];
 			cmds.push(cmd);
 
-			if (cmd[0] === "tmux" && cmd[1] === "display-message") {
+			if (cmd[0] === "tmux" && cmd[3] === "display-message") {
 				// getPanePid → returns PID 500
 				return mockSpawnResult("500\n", "", 0);
 			}
@@ -687,7 +712,7 @@ describe("killSession", () => {
 				// getDescendantPids → no children
 				return mockSpawnResult("", "", 1);
 			}
-			if (cmd[0] === "tmux" && cmd[1] === "kill-session") {
+			if (cmd[0] === "tmux" && cmd[3] === "kill-session") {
 				return mockSpawnResult("", "", 0);
 			}
 			return mockSpawnResult("", "", 0);
@@ -700,6 +725,8 @@ describe("killSession", () => {
 		// Should have called: tmux display-message, pgrep, tmux kill-session
 		expect(cmds[0]).toEqual([
 			"tmux",
+			"-L",
+			"overstory",
 			"display-message",
 			"-p",
 			"-t",
@@ -708,7 +735,7 @@ describe("killSession", () => {
 		]);
 		expect(cmds[1]).toEqual(["pgrep", "-P", "500"]);
 		const lastCmd = cmds[cmds.length - 1];
-		expect(lastCmd).toEqual(["tmux", "kill-session", "-t", "overstory-auth"]);
+		expect(lastCmd).toEqual(["tmux", "-L", "overstory", "kill-session", "-t", "overstory-auth"]);
 
 		// Should have sent SIGTERM to root PID 500
 		expect(killSpy).toHaveBeenCalledWith(500, "SIGTERM");
@@ -720,11 +747,11 @@ describe("killSession", () => {
 			const cmd = args[0] as string[];
 			cmds.push(cmd);
 
-			if (cmd[0] === "tmux" && cmd[1] === "display-message") {
+			if (cmd[0] === "tmux" && cmd[3] === "display-message") {
 				// getPanePid → session not found
 				return mockSpawnResult("", "can't find session", 1);
 			}
-			if (cmd[0] === "tmux" && cmd[1] === "kill-session") {
+			if (cmd[0] === "tmux" && cmd[3] === "kill-session") {
 				return mockSpawnResult("", "", 0);
 			}
 			return mockSpawnResult("", "", 0);
@@ -734,8 +761,8 @@ describe("killSession", () => {
 
 		// Should go straight to tmux kill-session (no pgrep calls)
 		expect(cmds).toHaveLength(2);
-		expect(cmds[0]?.[1]).toBe("display-message");
-		expect(cmds[1]?.[1]).toBe("kill-session");
+		expect(cmds[0]?.[3]).toBe("display-message");
+		expect(cmds[1]?.[3]).toBe("kill-session");
 		// No process.kill calls since we had no PID
 		expect(killSpy).not.toHaveBeenCalled();
 	});
@@ -743,13 +770,13 @@ describe("killSession", () => {
 	test("succeeds silently when session is already gone after process cleanup", async () => {
 		spawnSpy.mockImplementation((...args: unknown[]) => {
 			const cmd = args[0] as string[];
-			if (cmd[0] === "tmux" && cmd[1] === "display-message") {
+			if (cmd[0] === "tmux" && cmd[3] === "display-message") {
 				return mockSpawnResult("500\n", "", 0);
 			}
 			if (cmd[0] === "pgrep") {
 				return mockSpawnResult("", "", 1);
 			}
-			if (cmd[0] === "tmux" && cmd[1] === "kill-session") {
+			if (cmd[0] === "tmux" && cmd[3] === "kill-session") {
 				// Session already gone after process cleanup
 				return mockSpawnResult("", "can't find session: overstory-auth", 1);
 			}
@@ -765,10 +792,10 @@ describe("killSession", () => {
 	test("throws AgentError on unexpected tmux kill-session failure", async () => {
 		spawnSpy.mockImplementation((...args: unknown[]) => {
 			const cmd = args[0] as string[];
-			if (cmd[0] === "tmux" && cmd[1] === "display-message") {
+			if (cmd[0] === "tmux" && cmd[3] === "display-message") {
 				return mockSpawnResult("", "can't find session", 1);
 			}
-			if (cmd[0] === "tmux" && cmd[1] === "kill-session") {
+			if (cmd[0] === "tmux" && cmd[3] === "kill-session") {
 				return mockSpawnResult("", "server exited unexpectedly", 1);
 			}
 			return mockSpawnResult("", "", 0);
@@ -780,10 +807,10 @@ describe("killSession", () => {
 	test("AgentError contains session name on failure", async () => {
 		spawnSpy.mockImplementation((...args: unknown[]) => {
 			const cmd = args[0] as string[];
-			if (cmd[0] === "tmux" && cmd[1] === "display-message") {
+			if (cmd[0] === "tmux" && cmd[3] === "display-message") {
 				return mockSpawnResult("", "error", 1);
 			}
-			if (cmd[0] === "tmux" && cmd[1] === "kill-session") {
+			if (cmd[0] === "tmux" && cmd[3] === "kill-session") {
 				return mockSpawnResult("", "server exited unexpectedly", 1);
 			}
 			return mockSpawnResult("", "", 0);
@@ -836,7 +863,7 @@ describe("isSessionAlive", () => {
 		expect(spawnSpy).toHaveBeenCalledTimes(1);
 		const callArgs = spawnSpy.mock.calls[0] as unknown[];
 		const cmd = callArgs[0] as string[];
-		expect(cmd).toEqual(["tmux", "has-session", "-t", "my-agent"]);
+		expect(cmd).toEqual(["tmux", "-L", "overstory", "has-session", "-t", "my-agent"]);
 	});
 });
 
@@ -907,7 +934,16 @@ describe("sendKeys", () => {
 		expect(spawnSpy).toHaveBeenCalledTimes(1);
 		const callArgs = spawnSpy.mock.calls[0] as unknown[];
 		const cmd = callArgs[0] as string[];
-		expect(cmd).toEqual(["tmux", "send-keys", "-t", "overstory-auth", "echo hello world", "Enter"]);
+		expect(cmd).toEqual([
+			"tmux",
+			"-L",
+			"overstory",
+			"send-keys",
+			"-t",
+			"overstory-auth",
+			"echo hello world",
+			"Enter",
+		]);
 	});
 
 	test("flattens newlines in keys to spaces", async () => {
@@ -920,6 +956,8 @@ describe("sendKeys", () => {
 		const cmd = callArgs[0] as string[];
 		expect(cmd).toEqual([
 			"tmux",
+			"-L",
+			"overstory",
 			"send-keys",
 			"-t",
 			"overstory-agent",
@@ -956,7 +994,16 @@ describe("sendKeys", () => {
 		expect(spawnSpy).toHaveBeenCalledTimes(1);
 		const callArgs = spawnSpy.mock.calls[0] as unknown[];
 		const cmd = callArgs[0] as string[];
-		expect(cmd).toEqual(["tmux", "send-keys", "-t", "overstory-agent", "", "Enter"]);
+		expect(cmd).toEqual([
+			"tmux",
+			"-L",
+			"overstory",
+			"send-keys",
+			"-t",
+			"overstory-agent",
+			"",
+			"Enter",
+		]);
 	});
 
 	test("throws descriptive error when tmux server is not running", async () => {
@@ -1039,7 +1086,17 @@ describe("capturePaneContent", () => {
 
 		const callArgs = spawnSpy.mock.calls[0] as unknown[];
 		const cmd = callArgs[0] as string[];
-		expect(cmd).toEqual(["tmux", "capture-pane", "-t", "my-session", "-p", "-S", "-100"]);
+		expect(cmd).toEqual([
+			"tmux",
+			"-L",
+			"overstory",
+			"capture-pane",
+			"-t",
+			"my-session",
+			"-p",
+			"-S",
+			"-100",
+		]);
 	});
 
 	test("uses default 50 lines when not specified", async () => {
@@ -1049,7 +1106,7 @@ describe("capturePaneContent", () => {
 
 		const callArgs = spawnSpy.mock.calls[0] as unknown[];
 		const cmd = callArgs[0] as string[];
-		expect(cmd[6]).toBe("-50");
+		expect(cmd[8]).toBe("-50");
 	});
 
 	test("returns null when capture-pane fails", async () => {
@@ -1122,7 +1179,7 @@ describe("waitForTuiReady", () => {
 		let captureCallCount = 0;
 		spawnSpy.mockImplementation((...args: unknown[]) => {
 			const cmd = args[0] as string[];
-			if (cmd[1] === "capture-pane") {
+			if (cmd[3] === "capture-pane") {
 				captureCallCount++;
 				if (captureCallCount <= 3) {
 					// First 3 capture-pane polls: empty pane (TUI still loading)
@@ -1174,7 +1231,7 @@ describe("waitForTuiReady", () => {
 		// capture-pane fails (session dead), has-session also fails (session dead)
 		spawnSpy.mockImplementation((...args: unknown[]) => {
 			const cmd = args[0] as string[];
-			if (cmd[1] === "capture-pane") {
+			if (cmd[3] === "capture-pane") {
 				return mockSpawnResult("", "can't find session", 1);
 			}
 			// has-session: session is dead
@@ -1192,7 +1249,7 @@ describe("waitForTuiReady", () => {
 		let captureCallCount = 0;
 		spawnSpy.mockImplementation((...args: unknown[]) => {
 			const cmd = args[0] as string[];
-			if (cmd[1] === "capture-pane") {
+			if (cmd[3] === "capture-pane") {
 				captureCallCount++;
 				// Pane stays empty for all polls (session alive but TUI not rendered yet)
 				return mockSpawnResult("", "", 0);
@@ -1214,7 +1271,7 @@ describe("waitForTuiReady", () => {
 		// Pane always shows prompt indicator but never shows status bar text
 		spawnSpy.mockImplementation((...args: unknown[]) => {
 			const cmd = args[0] as string[];
-			if (cmd[1] === "capture-pane") {
+			if (cmd[3] === "capture-pane") {
 				return mockSpawnResult("Welcome to Claude Code!\n\u276f", "", 0);
 			}
 			// has-session: session is alive
@@ -1230,7 +1287,7 @@ describe("waitForTuiReady", () => {
 		// Pane always shows status bar but never shows prompt indicator
 		spawnSpy.mockImplementation((...args: unknown[]) => {
 			const cmd = args[0] as string[];
-			if (cmd[1] === "capture-pane") {
+			if (cmd[3] === "capture-pane") {
 				return mockSpawnResult("bypass permissions", "", 0);
 			}
 			// has-session: session is alive
@@ -1246,7 +1303,7 @@ describe("waitForTuiReady", () => {
 		let captureCallCount = 0;
 		spawnSpy.mockImplementation((...args: unknown[]) => {
 			const cmd = args[0] as string[];
-			if (cmd[1] === "capture-pane") {
+			if (cmd[3] === "capture-pane") {
 				captureCallCount++;
 				if (captureCallCount <= 2) {
 					// First 2 polls: only prompt indicator visible (phase 1 only)
@@ -1271,7 +1328,7 @@ describe("waitForTuiReady", () => {
 		let captureCallCount = 0;
 		spawnSpy.mockImplementation((...args: unknown[]) => {
 			const cmd = args[0] as string[];
-			if (cmd[1] === "capture-pane") {
+			if (cmd[3] === "capture-pane") {
 				captureCallCount++;
 				if (captureCallCount === 1) {
 					// First poll: trust dialog is showing
@@ -1280,7 +1337,7 @@ describe("waitForTuiReady", () => {
 				// Subsequent polls: trust confirmed, real TUI with both indicators
 				return mockSpawnResult('Try "help"\nshift+tab', "", 0);
 			}
-			if (cmd[1] === "send-keys") {
+			if (cmd[3] === "send-keys") {
 				sendKeysCalls.push(cmd);
 				return mockSpawnResult("", "", 0);
 			}
@@ -1294,7 +1351,16 @@ describe("waitForTuiReady", () => {
 		// sendKeys should have been called once to confirm the trust dialog
 		expect(sendKeysCalls).toHaveLength(1);
 		const trustCall = sendKeysCalls[0];
-		expect(trustCall).toEqual(["tmux", "send-keys", "-t", "overstory-agent", "", "Enter"]);
+		expect(trustCall).toEqual([
+			"tmux",
+			"-L",
+			"overstory",
+			"send-keys",
+			"-t",
+			"overstory-agent",
+			"",
+			"Enter",
+		]);
 	});
 
 	test("detects bypass permissions dialog and types 2 before Enter", async () => {
@@ -1302,7 +1368,7 @@ describe("waitForTuiReady", () => {
 		let captureCallCount = 0;
 		spawnSpy.mockImplementation((...args: unknown[]) => {
 			const cmd = args[0] as string[];
-			if (cmd[1] === "capture-pane") {
+			if (cmd[3] === "capture-pane") {
 				captureCallCount++;
 				if (captureCallCount === 1) {
 					return mockSpawnResult(
@@ -1313,7 +1379,7 @@ describe("waitForTuiReady", () => {
 				}
 				return mockSpawnResult('Try "help"\nshift+tab', "", 0);
 			}
-			if (cmd[1] === "send-keys") {
+			if (cmd[3] === "send-keys") {
 				sendKeysCalls.push(cmd);
 				return mockSpawnResult("", "", 0);
 			}
@@ -1324,8 +1390,25 @@ describe("waitForTuiReady", () => {
 
 		expect(ready).toBe(true);
 		expect(sendKeysCalls).toHaveLength(2);
-		expect(sendKeysCalls[0]).toEqual(["tmux", "send-keys", "-t", "overstory-agent", "2"]);
-		expect(sendKeysCalls[1]).toEqual(["tmux", "send-keys", "-t", "overstory-agent", "", "Enter"]);
+		expect(sendKeysCalls[0]).toEqual([
+			"tmux",
+			"-L",
+			"overstory",
+			"send-keys",
+			"-t",
+			"overstory-agent",
+			"2",
+		]);
+		expect(sendKeysCalls[1]).toEqual([
+			"tmux",
+			"-L",
+			"overstory",
+			"send-keys",
+			"-t",
+			"overstory-agent",
+			"",
+			"Enter",
+		]);
 	});
 
 	test("retries typed bypass dialog action when the same dialog persists", async () => {
@@ -1333,7 +1416,7 @@ describe("waitForTuiReady", () => {
 		let captureCallCount = 0;
 		spawnSpy.mockImplementation((...args: unknown[]) => {
 			const cmd = args[0] as string[];
-			if (cmd[1] === "capture-pane") {
+			if (cmd[3] === "capture-pane") {
 				captureCallCount++;
 				if (captureCallCount <= 3) {
 					return mockSpawnResult(
@@ -1344,7 +1427,7 @@ describe("waitForTuiReady", () => {
 				}
 				return mockSpawnResult('Try "help"\nshift+tab', "", 0);
 			}
-			if (cmd[1] === "send-keys") {
+			if (cmd[3] === "send-keys") {
 				sendKeysCalls.push(cmd);
 				return mockSpawnResult("", "", 0);
 			}
@@ -1355,10 +1438,44 @@ describe("waitForTuiReady", () => {
 
 		expect(ready).toBe(true);
 		expect(sendKeysCalls).toHaveLength(4);
-		expect(sendKeysCalls[0]).toEqual(["tmux", "send-keys", "-t", "overstory-agent", "2"]);
-		expect(sendKeysCalls[1]).toEqual(["tmux", "send-keys", "-t", "overstory-agent", "", "Enter"]);
-		expect(sendKeysCalls[2]).toEqual(["tmux", "send-keys", "-t", "overstory-agent", "2"]);
-		expect(sendKeysCalls[3]).toEqual(["tmux", "send-keys", "-t", "overstory-agent", "", "Enter"]);
+		expect(sendKeysCalls[0]).toEqual([
+			"tmux",
+			"-L",
+			"overstory",
+			"send-keys",
+			"-t",
+			"overstory-agent",
+			"2",
+		]);
+		expect(sendKeysCalls[1]).toEqual([
+			"tmux",
+			"-L",
+			"overstory",
+			"send-keys",
+			"-t",
+			"overstory-agent",
+			"",
+			"Enter",
+		]);
+		expect(sendKeysCalls[2]).toEqual([
+			"tmux",
+			"-L",
+			"overstory",
+			"send-keys",
+			"-t",
+			"overstory-agent",
+			"2",
+		]);
+		expect(sendKeysCalls[3]).toEqual([
+			"tmux",
+			"-L",
+			"overstory",
+			"send-keys",
+			"-t",
+			"overstory-agent",
+			"",
+			"Enter",
+		]);
 	});
 
 	test("handles trust dialog only once (trustHandled flag)", async () => {
@@ -1366,7 +1483,7 @@ describe("waitForTuiReady", () => {
 		let captureCallCount = 0;
 		spawnSpy.mockImplementation((...args: unknown[]) => {
 			const cmd = args[0] as string[];
-			if (cmd[1] === "capture-pane") {
+			if (cmd[3] === "capture-pane") {
 				captureCallCount++;
 				if (captureCallCount <= 3) {
 					// Multiple polls still show trust dialog (slow dialog dismissal)
@@ -1375,7 +1492,7 @@ describe("waitForTuiReady", () => {
 				// Eventually TUI loads with both indicators
 				return mockSpawnResult('Try "help"\nbypass permissions', "", 0);
 			}
-			if (cmd[1] === "send-keys") {
+			if (cmd[3] === "send-keys") {
 				sendKeysCalls.push(cmd);
 				return mockSpawnResult("", "", 0);
 			}

package/src/worktree/tmux.ts

@@ -11,6 +11,24 @@ import { dirname, resolve } from "node:path";
 import { AgentError } from "../errors.ts";
 import type { ReadyState } from "../runtimes/types.ts";
 
+/**
+ * Dedicated tmux server socket name for agent session isolation.
+ *
+ * All overstory agent sessions use `tmux -L overstory` so they run on a
+ * separate server from the user's personal tmux. This prevents user tmux
+ * config (themes, plugins, keybindings) from interfering with agent spawn.
+ * See GitHub #93.
+ */
+export const TMUX_SOCKET = "overstory";
+
+/**
+ * Build a tmux command array with the dedicated server socket.
+ * All agent session operations should use this to ensure isolation.
+ */
+function tmuxCmd(...args: string[]): string[] {
+	return ["tmux", "-L", TMUX_SOCKET, ...args];
+}
+
 /**
  * Detect the directory containing the overstory binary.
  *
@@ -123,7 +141,7 @@ export async function createSession(
 		exports.length > 0 ? `/bin/bash -c '${startupScript.replace(/'/g, "'\\''")}'` : command;
 
 	const { exitCode, stderr } = await runCommand(
-		["tmux", "new-session", "-d", "-s", name, "-c", cwd, wrappedCommand],
+		tmuxCmd("new-session", "-d", "-s", name, "-c", cwd, wrappedCommand),
 		cwd,
 	);
 
@@ -138,7 +156,7 @@ export async function createSession(
 	// the session exists but the pane hasn't been registered yet (#73).
 	let pidResult: { stdout: string; stderr: string; exitCode: number } | undefined;
 	for (let attempt = 0; attempt < maxRetries; attempt++) {
-		pidResult = await runCommand(["tmux", "list-panes", "-t", name, "-F", "#{pane_pid}"]);
+		pidResult = await runCommand(tmuxCmd("list-panes", "-t", name, "-F", "#{pane_pid}"));
 		if (pidResult.exitCode === 0) break;
 		await Bun.sleep(250 * (attempt + 1));
 	}
@@ -170,12 +188,9 @@ export async function createSession(
  * @throws AgentError if tmux is not installed
  */
 export async function listSessions(): Promise<Array<{ name: string; pid: number }>> {
-	const { exitCode, stdout, stderr } = await runCommand([
-		"tmux",
-		"list-sessions",
-		"-F",
-		"#{session_name}:#{pid}",
-	]);
+	const { exitCode, stdout, stderr } = await runCommand(
+		tmuxCmd("list-sessions", "-F", "#{session_name}:#{pid}"),
+	);
 
 	// Exit code 1 with "no server running" means no sessions exist — not an error
 	if (exitCode !== 0) {
@@ -219,14 +234,9 @@ const KILL_GRACE_PERIOD_MS = 2000;
  *          the session doesn't exist or the PID can't be determined
  */
 export async function getPanePid(name: string): Promise<number | null> {
-	const { exitCode, stdout } = await runCommand([
-		"tmux",
-		"display-message",
-		"-p",
-		"-t",
-		name,
-		"#{pane_pid}",
-	]);
+	const { exitCode, stdout } = await runCommand(
+		tmuxCmd("display-message", "-p", "-t", name, "#{pane_pid}"),
+	);
 
 	if (exitCode !== 0) {
 		return null;
@@ -383,7 +393,7 @@ export async function killSession(name: string): Promise<void> {
 	}
 
 	// Step 3: Kill the tmux session itself
-	const { exitCode, stderr } = await runCommand(["tmux", "kill-session", "-t", name]);
+	const { exitCode, stderr } = await runCommand(tmuxCmd("kill-session", "-t", name));
 
 	if (exitCode !== 0) {
 		// If the session is already gone (e.g., died during process cleanup), that's fine
@@ -427,7 +437,7 @@ export async function getCurrentSessionName(): Promise<string | null> {
  * @returns true if the session exists, false otherwise
  */
 export async function isSessionAlive(name: string): Promise<boolean> {
-	const { exitCode } = await runCommand(["tmux", "has-session", "-t", name]);
+	const { exitCode } = await runCommand(tmuxCmd("has-session", "-t", name));
 	return exitCode === 0;
 }
 
@@ -456,7 +466,7 @@ export type SessionState = "alive" | "dead" | "no_server";
  * @returns The session state
  */
 export async function checkSessionState(name: string): Promise<SessionState> {
-	const { exitCode, stderr } = await runCommand(["tmux", "has-session", "-t", name]);
+	const { exitCode, stderr } = await runCommand(tmuxCmd("has-session", "-t", name));
 	if (exitCode === 0) return "alive";
 	if (stderr.includes("no server running") || stderr.includes("no sessions")) {
 		return "no_server";
@@ -472,15 +482,9 @@ export async function checkSessionState(name: string): Promise<SessionState> {
  * @returns The trimmed pane content, or null if capture fails
  */
 export async function capturePaneContent(name: string, lines = 50): Promise<string | null> {
-	const { exitCode, stdout } = await runCommand([
-		"tmux",
-		"capture-pane",
-		"-t",
-		name,
-		"-p",
-		"-S",
-		`-${lines}`,
-	]);
+	const { exitCode, stdout } = await runCommand(
+		tmuxCmd("capture-pane", "-t", name, "-p", "-S", `-${lines}`),
+	);
 	if (exitCode !== 0) {
 		return null;
 	}
@@ -584,14 +588,9 @@ export async function sendKeys(name: string, keys: string, maxRetries = 3): Prom
 	const flatKeys = keys.replace(/\n/g, " ");
 
 	for (let attempt = 0; attempt <= maxRetries; attempt++) {
-		const { exitCode, stderr } = await runCommand([
-			"tmux",
-			"send-keys",
-			"-t",
-			name,
-			flatKeys,
-			"Enter",
-		]);
+		const { exitCode, stderr } = await runCommand(
+			tmuxCmd("send-keys", "-t", name, flatKeys, "Enter"),
+		);
 
 		if (exitCode === 0) {
 			return;
@@ -640,7 +639,7 @@ export async function sendKeys(name: string, keys: string, maxRetries = 3): Prom
 
 async function sendRawKeys(name: string, keys: string): Promise<void> {
 	const flatKeys = keys.replace(/\n/g, " ");
-	const { exitCode, stderr } = await runCommand(["tmux", "send-keys", "-t", name, flatKeys]);
+	const { exitCode, stderr } = await runCommand(tmuxCmd("send-keys", "-t", name, flatKeys));
 
 	if (exitCode !== 0) {
 		const trimmedStderr = stderr.trim();

package/templates/copilot-hooks.json.tmpl

@@ -0,0 +1,13 @@
+{
+	"_comment": "Copilot CLI lifecycle hooks — schema reverse-engineered from copilot CLI behavior. Key differences from Claude Code: event names are camelCase (onSessionStart, onToolUse, onError), no matcher field, hook entries are { command } only (no type field).",
+	"hooks": {
+		"onSessionStart": [
+			{
+				"command": "[ -z \"$OVERSTORY_AGENT_NAME\" ] && exit 0; ov prime --agent {{AGENT_NAME}}"
+			},
+			{
+				"command": "[ -z \"$OVERSTORY_AGENT_NAME\" ] && exit 0; ov mail check --inject --agent {{AGENT_NAME}}"
+			}
+		]
+	}
+}