@os-eco/overstory-cli 0.9.2 → 0.9.4

package/src/worktree/tmux.test.ts

@@ -13,6 +13,7 @@ import {
 	killProcessTree,
 	killSession,
 	listSessions,
+	sanitizeTmuxName,
 	sendKeys,
 	waitForTuiReady,
 } from "./tmux.ts";
@@ -102,13 +103,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 +137,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 +249,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 +370,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 +400,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 +705,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 +713,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 +726,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 +736,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 +748,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 +762,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 +771,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 +793,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 +808,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 +864,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 +935,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 +957,8 @@ describe("sendKeys", () => {
 		const cmd = callArgs[0] as string[];
 		expect(cmd).toEqual([
 			"tmux",
+			"-L",
+			"overstory",
 			"send-keys",
 			"-t",
 			"overstory-agent",
@@ -956,7 +995,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 +1087,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 +1107,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 +1180,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 +1232,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 +1250,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 +1272,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 +1288,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 +1304,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 +1329,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 +1338,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 +1352,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 +1369,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 +1380,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 +1391,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 +1417,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 +1428,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 +1439,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 +1484,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 +1493,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);
 			}
@@ -1433,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

@@ -11,6 +11,37 @@ 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";
+
+/**
+ * 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.
+ */
+function tmuxCmd(...args: string[]): string[] {
+	return ["tmux", "-L", TMUX_SOCKET, ...args];
+}
+
 /**
  * Detect the directory containing the overstory binary.
  *
@@ -123,7 +154,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 +169,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 +201,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 +247,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 +406,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 +450,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 +479,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 +495,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 +601,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 +652,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();