@katyella/legio 0.1.0

package/src/worktree/tmux.ts

@@ -0,0 +1,644 @@
+/**
+ * Tmux session management for legio agent workers.
+ *
+ * All operations use child_process.spawn to call the tmux CLI directly.
+ * Session naming convention: `legio-{projectName}-{agentName}`.
+ * The project name prefix prevents cross-project tmux session collisions
+ * and enables project-scoped cleanup (legio-pcef).
+ */
+
+import { spawn } from "node:child_process";
+import { mkdir, readFile, stat } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { setTimeout } from "node:timers/promises";
+import { AgentError } from "../errors.ts";
+
+/**
+ * Run a shell command and capture its output.
+ */
+async function runCommand(
+	cmd: string[],
+	cwd?: string,
+): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+	const [command, ...args] = cmd;
+	if (!command) throw new Error("Empty command");
+	return new Promise(
+		(resolve: (value: { stdout: string; stderr: string; exitCode: number }) => void, reject) => {
+			const proc = spawn(command, args, {
+				cwd,
+				stdio: ["ignore", "pipe", "pipe"],
+			});
+			const chunks: { stdout: Buffer[]; stderr: Buffer[] } = { stdout: [], stderr: [] };
+			proc.stdout.on("data", (data: Buffer) => chunks.stdout.push(data));
+			proc.stderr.on("data", (data: Buffer) => chunks.stderr.push(data));
+			proc.on("error", reject);
+			proc.on("close", (code) => {
+				resolve({
+					stdout: Buffer.concat(chunks.stdout).toString(),
+					stderr: Buffer.concat(chunks.stderr).toString(),
+					exitCode: code ?? 1,
+				});
+			});
+		},
+	);
+}
+
+/**
+ * Detect the directory containing the legio binary.
+ *
+ * Checks process.argv[0] first (the node executable path won't help,
+ * but process.argv[1] is the script path for `npm run`), then falls back
+ * to `which legio` to find it on the current PATH.
+ *
+ * Returns null if detection fails.
+ */
+async function detectLegioBinDir(): Promise<string | null> {
+	// process.argv[1] is the script entry point (e.g., /path/to/legio/src/index.ts)
+	// The legio binary resolves to a bin dir
+	// Try `which legio` for the most reliable result
+	try {
+		const result = await runCommand(["which", "legio"]);
+		if (result.exitCode === 0) {
+			const binPath = result.stdout.trim();
+			if (binPath.length > 0) {
+				return dirname(resolve(binPath));
+			}
+		}
+	} catch {
+		// which not available or legio not on PATH
+	}
+
+	// Fallback: if process.argv[1] points to legio's own entry point (src/index.ts),
+	// derive the bin dir from the node binary that's running it
+	const scriptPath = process.argv[1];
+	if (scriptPath?.includes("legio")) {
+		const nodePath = process.argv[0];
+		if (nodePath) {
+			return dirname(resolve(nodePath));
+		}
+	}
+
+	return null;
+}
+
+/**
+ * Create a new detached tmux session running the given command.
+ *
+ * @param name - Session name (e.g., "legio-myproject-auth-login")
+ * @param cwd - Working directory for the session
+ * @param command - Command to execute inside the session
+ * @param env - Optional environment variables to export in the session
+ * @returns The PID of the tmux server process for this session
+ * @throws AgentError if tmux is not installed or session creation fails
+ */
+export async function createSession(
+	name: string,
+	cwd: string,
+	command: string,
+	env?: Record<string, string>,
+): Promise<number> {
+	// Clear Claude Code nesting detection so child Claude Code instances
+	// don't refuse to start with "cannot be launched inside another session".
+	// This MUST be part of the shell command (not tmux -e) because we need
+	// to *unset* vars inherited from the parent process environment.
+	const shellPrefix = "unset CLAUDECODE CLAUDE_CODE_ENTRYPOINT";
+	const wrappedCommand = `${shellPrefix} && ${command}`;
+
+	// Build tmux args. Environment variables are passed via `-e KEY=VALUE`
+	// flags (tmux 3.2+) instead of shell `export` commands to avoid
+	// ERR_STREAM_DESTROYED in Claude Code v2.1.50, which is triggered when
+	// shell variable expansion (e.g., $PATH) produces very long command
+	// strings that corrupt the internal TUI stream.
+	const tmuxArgs = ["new-session", "-d", "-s", name, "-c", cwd];
+
+	// Ensure PATH includes the legio binary directory so hooks can find `legio`
+	const legioBinDir = await detectLegioBinDir();
+	if (legioBinDir) {
+		const currentPath = process.env.PATH ?? "";
+		tmuxArgs.push("-e", `PATH=${legioBinDir}:${currentPath}`);
+	}
+
+	// Pass additional environment variables
+	if (env) {
+		for (const [key, value] of Object.entries(env)) {
+			tmuxArgs.push("-e", `${key}=${value}`);
+		}
+	}
+
+	tmuxArgs.push(wrappedCommand);
+
+	const { exitCode, stderr } = await runCommand(["tmux", ...tmuxArgs], cwd);
+
+	if (exitCode !== 0) {
+		throw new AgentError(`Failed to create tmux session "${name}": ${stderr.trim()}`, {
+			agentName: name,
+		});
+	}
+
+	// Retrieve the actual PID of the process running inside the tmux pane
+	const pidResult = await runCommand(["tmux", "list-panes", "-t", name, "-F", "#{pane_pid}"]);
+
+	if (pidResult.exitCode !== 0) {
+		throw new AgentError(
+			`Created tmux session "${name}" but failed to retrieve PID: ${pidResult.stderr.trim()}`,
+			{ agentName: name },
+		);
+	}
+
+	const pidStr = pidResult.stdout.trim().split("\n")[0];
+	if (pidStr) {
+		const pid = Number.parseInt(pidStr, 10);
+		if (!Number.isNaN(pid)) {
+			return pid;
+		}
+	}
+
+	throw new AgentError(`Created tmux session "${name}" but could not find its pane PID`, {
+		agentName: name,
+	});
+}
+
+/**
+ * List all active tmux sessions.
+ *
+ * @returns Array of session name/pid pairs
+ * @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}",
+	]);
+
+	// Exit code 1 with "no server running" means no sessions exist — not an error
+	if (exitCode !== 0) {
+		if (stderr.includes("no server running") || stderr.includes("no sessions")) {
+			return [];
+		}
+		throw new AgentError(`Failed to list tmux sessions: ${stderr.trim()}`);
+	}
+
+	const sessions: Array<{ name: string; pid: number }> = [];
+	const lines = stdout.trim().split("\n");
+
+	for (const line of lines) {
+		if (line.trim() === "") continue;
+		const sepIndex = line.indexOf(":");
+		if (sepIndex === -1) continue;
+
+		const name = line.slice(0, sepIndex);
+		const pidStr = line.slice(sepIndex + 1);
+		if (name && pidStr) {
+			const pid = Number.parseInt(pidStr, 10);
+			if (!Number.isNaN(pid)) {
+				sessions.push({ name, pid });
+			}
+		}
+	}
+
+	return sessions;
+}
+
+/**
+ * Grace period (ms) between SIGTERM and SIGKILL during process cleanup.
+ */
+const KILL_GRACE_PERIOD_MS = 2000;
+
+/**
+ * Get the pane PID for a tmux session.
+ *
+ * @param name - Tmux session name
+ * @returns The PID of the process running in the session's pane, or null if
+ *          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}",
+	]);
+
+	if (exitCode !== 0) {
+		return null;
+	}
+
+	const pidStr = stdout.trim();
+	if (pidStr.length === 0) {
+		return null;
+	}
+
+	const pid = Number.parseInt(pidStr, 10);
+	return Number.isNaN(pid) ? null : pid;
+}
+
+/**
+ * Recursively collect all descendant PIDs of a given process.
+ *
+ * Uses `pgrep -P <pid>` to find direct children, then recurses into each child.
+ * Returns PIDs in depth-first order (deepest descendants first), which is the
+ * correct order for sending signals — kill children before parents so processes
+ * don't get reparented to init (PID 1).
+ *
+ * @param pid - The root process PID to walk from
+ * @returns Array of descendant PIDs, deepest-first
+ */
+export async function getDescendantPids(pid: number): Promise<number[]> {
+	const { exitCode, stdout } = await runCommand(["pgrep", "-P", String(pid)]);
+
+	// pgrep exits 1 when no children found — not an error
+	if (exitCode !== 0 || stdout.trim().length === 0) {
+		return [];
+	}
+
+	const childPids: number[] = [];
+	for (const line of stdout.trim().split("\n")) {
+		const childPid = Number.parseInt(line.trim(), 10);
+		if (!Number.isNaN(childPid)) {
+			childPids.push(childPid);
+		}
+	}
+
+	// Recurse into each child to get their descendants first (depth-first)
+	const allDescendants: number[] = [];
+	for (const childPid of childPids) {
+		const grandchildren = await getDescendantPids(childPid);
+		allDescendants.push(...grandchildren);
+	}
+
+	// Append the direct children after their descendants (deepest-first order)
+	allDescendants.push(...childPids);
+
+	return allDescendants;
+}
+
+/**
+ * Check if a process is still alive.
+ *
+ * @param pid - Process ID to check
+ * @returns true if the process exists, false otherwise
+ */
+export function isProcessAlive(pid: number): boolean {
+	try {
+		// signal 0 doesn't send a signal but checks if the process exists
+		process.kill(pid, 0);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Kill a process tree: SIGTERM deepest-first, wait grace period, SIGKILL survivors.
+ *
+ * Follows gastown's KillSessionWithProcesses pattern:
+ * 1. Walk descendant tree from the root PID
+ * 2. Send SIGTERM to all descendants (deepest-first so children die before parents)
+ * 3. Wait a grace period for processes to clean up
+ * 4. Send SIGKILL to any survivors
+ *
+ * Handles edge cases:
+ * - Already-dead processes (ESRCH) — silently ignored
+ * - Reparented processes (PPID=1) — caught in the initial tree walk
+ * - Permission errors — silently ignored (process belongs to another user)
+ *
+ * @param rootPid - The root PID whose descendants should be killed
+ * @param gracePeriodMs - Time to wait between SIGTERM and SIGKILL (default 2000ms)
+ */
+export async function killProcessTree(
+	rootPid: number,
+	gracePeriodMs: number = KILL_GRACE_PERIOD_MS,
+): Promise<void> {
+	const descendants = await getDescendantPids(rootPid);
+
+	if (descendants.length === 0) {
+		// No descendants — just try to kill the root process
+		sendSignal(rootPid, "SIGTERM");
+		return;
+	}
+
+	// Phase 1: SIGTERM all descendants (deepest-first, then root)
+	for (const pid of descendants) {
+		sendSignal(pid, "SIGTERM");
+	}
+	sendSignal(rootPid, "SIGTERM");
+
+	// Phase 2: Wait grace period for processes to clean up
+	await setTimeout(gracePeriodMs);
+
+	// Phase 3: SIGKILL any survivors (same order: deepest-first, then root)
+	for (const pid of descendants) {
+		if (isProcessAlive(pid)) {
+			sendSignal(pid, "SIGKILL");
+		}
+	}
+	if (isProcessAlive(rootPid)) {
+		sendSignal(rootPid, "SIGKILL");
+	}
+}
+
+/**
+ * Send a signal to a process, ignoring errors for already-dead or inaccessible processes.
+ *
+ * @param pid - Process ID to signal
+ * @param signal - Signal name (e.g., "SIGTERM", "SIGKILL")
+ */
+function sendSignal(pid: number, signal: "SIGTERM" | "SIGKILL"): void {
+	try {
+		process.kill(pid, signal);
+	} catch {
+		// Process already dead (ESRCH), permission denied (EPERM), or invalid PID — all OK
+	}
+}
+
+/**
+ * Kill a tmux session by name, with proper process tree cleanup.
+ *
+ * Before killing the tmux session, walks the descendant process tree from the
+ * pane PID, sends SIGTERM to all descendants (deepest-first), waits a grace
+ * period, then sends SIGKILL to survivors. This ensures child processes
+ * (git, npm test, biome, etc.) are properly cleaned up rather than being
+ * orphaned or reparented to init.
+ *
+ * @param name - Session name to kill
+ * @throws AgentError if the tmux session cannot be killed (process cleanup
+ *         failures are silently handled since the goal is best-effort cleanup)
+ */
+export async function killSession(name: string): Promise<void> {
+	// Step 1: Get the pane PID before killing the tmux session
+	const panePid = await getPanePid(name);
+
+	// Step 2: If we have a pane PID, walk and kill the process tree
+	if (panePid !== null) {
+		await killProcessTree(panePid);
+	}
+
+	// Step 2b: Stop pipe-pane streaming (best-effort, ignore errors)
+	await stopPipePane(name);
+
+	// Step 3: Kill the tmux session itself
+	const { exitCode, stderr } = await runCommand(["tmux", "kill-session", "-t", name]);
+
+	if (exitCode !== 0) {
+		// If the session is already gone (e.g., died during process cleanup), that's fine
+		if (stderr.includes("session not found") || stderr.includes("can't find session")) {
+			return;
+		}
+		throw new AgentError(`Failed to kill tmux session "${name}": ${stderr.trim()}`, {
+			agentName: name,
+		});
+	}
+}
+
+/**
+ * Detect the current tmux session name.
+ *
+ * Returns the session name if running inside tmux, null otherwise.
+ * Used by `legio prime` to register the orchestrator's tmux session
+ * so agents can nudge the orchestrator when they have results.
+ */
+export async function getCurrentSessionName(): Promise<string | null> {
+	if (!process.env.TMUX) {
+		return null;
+	}
+	const { exitCode, stdout } = await runCommand([
+		"tmux",
+		"display-message",
+		"-p",
+		"#{session_name}",
+	]);
+	if (exitCode !== 0) {
+		return null;
+	}
+	const name = stdout.trim();
+	return name.length > 0 ? name : null;
+}
+
+/**
+ * Check whether a tmux session is still alive.
+ *
+ * @param name - Session name to check
+ * @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]);
+	return exitCode === 0;
+}
+
+/**
+ * Throw a typed AgentError for send-keys failures, differentiating known tmux errors.
+ */
+function throwSendKeysError(name: string, stderr: string): never {
+	if (stderr.includes("no server running")) {
+		throw new AgentError(`Tmux server not running — cannot send keys to session "${name}"`, {
+			agentName: name,
+		});
+	}
+	if (stderr.includes("session not found") || stderr.includes("can't find session")) {
+		throw new AgentError(`Session "${name}" not found — cannot send keys`, { agentName: name });
+	}
+	throw new AgentError(`Failed to send keys to tmux session "${name}": ${stderr.trim()}`, {
+		agentName: name,
+	});
+}
+
+/**
+ * Send keys to a tmux session.
+ *
+ * Uses two separate tmux calls: first sends text with the `-l` (literal) flag
+ * so tmux treats the content as literal characters rather than key names, then
+ * sends Enter separately to trigger submission. This prevents tmux from
+ * interpreting key names embedded in the text (e.g. "Enter", "Escape") and
+ * ensures the TUI has received the full text before the submit signal arrives.
+ *
+ * When `keys` is empty (follow-up submission), skips the text step and only
+ * sends Enter.
+ *
+ * @param name - Session name to send keys to
+ * @param keys - The keys/text to send
+ * @throws AgentError if the session does not exist or send fails
+ */
+export async function sendKeys(name: string, keys: string): Promise<void> {
+	// Flatten newlines to spaces — multiline text via tmux send-keys causes
+	// Claude Code's TUI to receive embedded Enter keystrokes which prevent
+	// the final "Enter" from triggering message submission (legio-y2ob).
+	const flatKeys = keys.replace(/\n/g, " ");
+
+	// Step 1: Send text with -l (literal) flag so tmux treats it as literal
+	// characters, not key names. Skip this step for empty strings (follow-up
+	// submissions that only need Enter).
+	if (flatKeys.length > 0) {
+		const textResult = await runCommand(["tmux", "send-keys", "-t", name, "-l", flatKeys]);
+		if (textResult.exitCode !== 0) {
+			throwSendKeysError(name, textResult.stderr);
+		}
+	}
+
+	// Step 2: Send Enter separately to trigger submission.
+	const enterResult = await runCommand(["tmux", "send-keys", "-t", name, "Enter"]);
+	if (enterResult.exitCode !== 0) {
+		throwSendKeysError(name, enterResult.stderr);
+	}
+}
+
+/**
+ * Capture the current visible content of a tmux pane.
+ *
+ * @param name - Session name to capture from
+ * @returns The current pane content, or empty string if the session does not exist or capture fails
+ */
+export async function capturePaneContent(name: string): Promise<string> {
+	const { exitCode, stdout } = await runCommand(["tmux", "capture-pane", "-t", name, "-p"]);
+	if (exitCode !== 0) {
+		return "";
+	}
+	return stdout;
+}
+
+/**
+ * Start continuous terminal output streaming for a tmux session via pipe-pane.
+ *
+ * Runs `tmux pipe-pane -t sessionName 'cat >> logPath'` to append all pane
+ * output to a log file. Creates the log directory if it does not exist.
+ *
+ * @param sessionName - Tmux session name to pipe output from
+ * @param logPath - Absolute path to the log file to write output to
+ * @throws AgentError if pipe-pane fails to start
+ */
+export async function startPipePane(sessionName: string, logPath: string): Promise<void> {
+	await mkdir(dirname(logPath), { recursive: true });
+	const { exitCode, stderr } = await runCommand([
+		"tmux",
+		"pipe-pane",
+		"-t",
+		sessionName,
+		`cat >> ${logPath}`,
+	]);
+	if (exitCode !== 0) {
+		throw new AgentError(
+			`Failed to start pipe-pane for session "${sessionName}": ${stderr.trim()}`,
+			{ agentName: sessionName },
+		);
+	}
+}
+
+/**
+ * Stop continuous terminal output streaming for a tmux session.
+ *
+ * Runs `tmux pipe-pane -t sessionName` with no command to close any active
+ * pipe. Errors are silently ignored — the session may not have an active
+ * pipe or may already be gone.
+ *
+ * @param sessionName - Tmux session name to stop piping output from
+ */
+export async function stopPipePane(sessionName: string): Promise<void> {
+	// tmux pipe-pane with no command closes any active pipe
+	await runCommand(["tmux", "pipe-pane", "-t", sessionName]);
+}
+
+/**
+ * Read the last N lines from a terminal log file.
+ *
+ * Returns null if the log file does not exist. Returns the full content
+ * if tailLines is not specified.
+ *
+ * @param logPath - Absolute path to the terminal log file
+ * @param tailLines - Number of trailing lines to return (default: all lines)
+ * @returns The log content, or null if the file does not exist
+ */
+export async function readTerminalLog(logPath: string, tailLines?: number): Promise<string | null> {
+	try {
+		await stat(logPath);
+	} catch {
+		return null;
+	}
+	const content = await readFile(logPath, "utf-8");
+	if (tailLines === undefined) {
+		return content;
+	}
+	// Split lines, accounting for optional trailing newline so the empty string
+	// after a trailing \n doesn't count as an extra line.
+	const hasTrailingNewline = content.endsWith("\n");
+	const lines = content.split("\n");
+	const effectiveLines = hasTrailingNewline ? lines.slice(0, -1) : lines;
+	if (effectiveLines.length <= tailLines) {
+		return content;
+	}
+	const tailed = effectiveLines.slice(-tailLines).join("\n");
+	return hasTrailingNewline ? `${tailed}\n` : tailed;
+}
+
+/**
+ * Strings that indicate Claude Code's TUI is rendered and ready.
+ *
+ * These markers appear in the pane once Claude Code has initialized its TUI:
+ * - Permission mode prompt text
+ * - Box-drawing characters used in the TUI chrome (separators, borders)
+ *
+ * Checking for these avoids false-positive ready detection on the bare shell
+ * prompt that appears before Claude Code starts.
+ */
+const TUI_READY_MARKERS = [
+	"bypass permissions", // Permission mode prompt
+	"─", // Unicode box-drawing horizontal line (TUI separator)
+	"━", // Bold box-drawing horizontal line (TUI separator variant)
+	"╭", // Box-drawing top-left corner
+	"╰", // Box-drawing bottom-left corner
+];
+
+/**
+ * Check whether pane content contains Claude Code TUI markers.
+ *
+ * @param content - Pane content to check
+ * @returns true if any TUI marker is present
+ */
+export function hasTuiMarkers(content: string): boolean {
+	return TUI_READY_MARKERS.some((marker) => content.includes(marker));
+}
+
+/**
+ * Poll a tmux pane until Claude Code's TUI has rendered its chrome, indicating
+ * it is ready to accept input.
+ *
+ * Waits for TUI-specific markers (box-drawing characters, permission prompts)
+ * rather than any non-empty content, preventing false-positive ready detection
+ * on the shell prompt that appears before Claude Code initializes.
+ *
+ * After markers are detected, an additional `postReadyDelay` (default 500ms)
+ * is applied as defense in depth to let the TUI finish initialization.
+ *
+ * If the timeout expires before markers appear, a warning is emitted to stderr
+ * and the function resolves normally (graceful fallback — the caller proceeds).
+ *
+ * @param sessionName - Tmux session name to poll
+ * @param opts.timeout - Maximum time to wait in ms (default: 15_000)
+ * @param opts.interval - Polling interval in ms (default: 500)
+ * @param opts.postReadyDelay - Extra delay after marker detection in ms (default: 500)
+ */
+export async function waitForTuiReady(
+	sessionName: string,
+	opts?: { timeout?: number; interval?: number; postReadyDelay?: number },
+): Promise<void> {
+	const timeoutMs = opts?.timeout ?? 15_000;
+	const intervalMs = opts?.interval ?? 500;
+	const postReadyDelayMs = opts?.postReadyDelay ?? 500;
+	const deadline = Date.now() + timeoutMs;
+
+	while (Date.now() < deadline) {
+		const content = await capturePaneContent(sessionName);
+		if (hasTuiMarkers(content)) {
+			// Defense in depth: wait for TUI to finish initialization
+			await setTimeout(postReadyDelayMs);
+			return;
+		}
+		await setTimeout(intervalMs);
+	}
+
+	process.stderr.write(
+		`⚠️  Warning: TUI for session "${sessionName}" did not become ready within ${timeoutMs}ms — proceeding anyway\n`,
+	);
+}