octomux 1.0.0

package/dist-server/poller.js

@@ -0,0 +1,170 @@
+import { execFile as execFileCb } from 'child_process';
+import { promisify } from 'util';
+import { getDb } from './db.js';
+import { closeTask } from './task-runner.js';
+import { installHookSettings } from './hook-settings.js';
+import { broadcast } from './events.js';
+const execFile = promisify(execFileCb);
+const STATUS_INTERVAL = process.env.NODE_ENV === 'test' ? 0 : 5000;
+const PR_INTERVAL = process.env.NODE_ENV === 'test' ? 0 : 30000;
+const MERGED_PR_INTERVAL = process.env.NODE_ENV === 'test' ? 0 : 30000;
+let statusTimer = null;
+let prTimer = null;
+let mergedPrTimer = null;
+// ─── Session Status Polling ──────────────────────────────────────────────────
+export async function checkTaskStatus(task) {
+    if (!task.tmux_session)
+        return 'dead';
+    try {
+        await execFile('tmux', ['has-session', '-t', task.tmux_session]);
+        return 'alive';
+    }
+    catch {
+        return 'dead';
+    }
+}
+export async function pollStatuses() {
+    const db = getDb();
+    const runningTasks = db
+        .prepare("SELECT * FROM tasks WHERE status IN ('running', 'setting_up')")
+        .all();
+    const results = await Promise.allSettled(runningTasks.map(async (task) => {
+        const status = await checkTaskStatus(task);
+        return { task, status };
+    }));
+    for (const result of results) {
+        if (result.status !== 'fulfilled')
+            continue;
+        const { task, status } = result.value;
+        if (status === 'dead' && task.status === 'running') {
+            db.prepare(`UPDATE tasks SET status = 'closed', updated_at = datetime('now') WHERE id = ?`).run(task.id);
+            db.prepare(`UPDATE agents SET status = 'stopped', hook_activity = 'idle', hook_activity_updated_at = datetime('now') WHERE task_id = ? AND status = 'running'`).run(task.id);
+            broadcast({ type: 'task:updated', payload: { taskId: task.id } });
+        }
+        else if (status === 'dead' && task.status === 'setting_up') {
+            db.prepare(`UPDATE tasks SET status = 'error', error = 'Setup interrupted', updated_at = datetime('now') WHERE id = ?`).run(task.id);
+            db.prepare(`UPDATE agents SET status = 'stopped', hook_activity = 'idle', hook_activity_updated_at = datetime('now') WHERE task_id = ? AND status = 'running'`).run(task.id);
+            broadcast({ type: 'task:updated', payload: { taskId: task.id } });
+        }
+    }
+}
+// ─── Hook Installation ──────────────────────────────────────────────────────
+/**
+ * Ensure hooks are installed in all running task worktrees.
+ * Handles tasks created before the hook feature existed.
+ */
+export function ensureHooksInstalled() {
+    const db = getDb();
+    const runningTasks = db
+        .prepare("SELECT * FROM tasks WHERE status IN ('running', 'setting_up') AND worktree IS NOT NULL")
+        .all();
+    for (const task of runningTasks) {
+        try {
+            installHookSettings(task.worktree);
+        }
+        catch {
+            // Non-critical — don't crash the poller
+        }
+    }
+}
+// ─── PR Detection ────────────────────────────────────────────────────────────
+export async function detectPR(task) {
+    if (!task.branch || !task.repo_path)
+        return null;
+    try {
+        const { stdout } = await execFile('gh', ['pr', 'list', '--head', task.branch, '--json', 'url,number', '--limit', '1'], {
+            cwd: task.repo_path,
+        });
+        const prs = JSON.parse(stdout.trim() || '[]');
+        if (prs.length > 0) {
+            return { url: prs[0].url, number: prs[0].number };
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function pollPRs() {
+    const db = getDb();
+    const tasks = db
+        .prepare("SELECT * FROM tasks WHERE status IN ('running', 'closed') AND pr_url IS NULL AND branch IS NOT NULL")
+        .all();
+    const results = await Promise.allSettled(tasks.map(async (task) => {
+        const pr = await detectPR(task);
+        return { task, pr };
+    }));
+    for (const result of results) {
+        if (result.status !== 'fulfilled')
+            continue;
+        const { task, pr } = result.value;
+        if (pr) {
+            db.prepare(`UPDATE tasks SET pr_url = ?, pr_number = ?, updated_at = datetime('now') WHERE id = ?`).run(pr.url, pr.number, task.id);
+            broadcast({ type: 'task:updated', payload: { taskId: task.id } });
+        }
+    }
+}
+// ─── Merged PR Detection ────────────────────────────────────────────────────
+export async function checkMergedPRs() {
+    const db = getDb();
+    const tasks = db
+        .prepare("SELECT * FROM tasks WHERE status = 'running' AND pr_number IS NOT NULL")
+        .all();
+    const results = await Promise.allSettled(tasks.map(async (task) => {
+        const { stdout } = await execFile('gh', ['pr', 'view', String(task.pr_number), '--json', 'state'], {
+            cwd: task.repo_path,
+        });
+        const { state } = JSON.parse(stdout.trim());
+        return { task, state };
+    }));
+    for (const result of results) {
+        if (result.status !== 'fulfilled')
+            continue;
+        const { task, state } = result.value;
+        if (state === 'MERGED') {
+            try {
+                await closeTask(task);
+                broadcast({ type: 'task:updated', payload: { taskId: task.id } });
+            }
+            catch {
+                // closeTask failure shouldn't stop processing other tasks
+            }
+        }
+    }
+}
+export async function pollMergedPRs() {
+    try {
+        await checkMergedPRs();
+    }
+    catch (err) {
+        console.error('pollMergedPRs error:', err);
+    }
+}
+// ─── Lifecycle ───────────────────────────────────────────────────────────────
+export function startPolling() {
+    // Install hooks in any running worktrees that might be missing them
+    ensureHooksInstalled();
+    if (STATUS_INTERVAL > 0) {
+        statusTimer = setInterval(pollStatuses, STATUS_INTERVAL);
+    }
+    if (PR_INTERVAL > 0) {
+        prTimer = setInterval(pollPRs, PR_INTERVAL);
+    }
+    if (MERGED_PR_INTERVAL > 0) {
+        mergedPrTimer = setInterval(pollMergedPRs, MERGED_PR_INTERVAL);
+    }
+}
+export function stopPolling() {
+    if (statusTimer) {
+        clearInterval(statusTimer);
+        statusTimer = null;
+    }
+    if (prTimer) {
+        clearInterval(prTimer);
+        prTimer = null;
+    }
+    if (mergedPrTimer) {
+        clearInterval(mergedPrTimer);
+        mergedPrTimer = null;
+    }
+}

package/dist-server/pr-template.d.ts

@@ -0,0 +1,7 @@
+export interface PRPromptContext {
+    taskTitle: string;
+    taskDescription: string;
+    commitLog: string;
+    diffStats: string;
+}
+export declare function buildPRPrompt(context: PRPromptContext): string;

package/dist-server/pr-template.js

@@ -0,0 +1,29 @@
+export function buildPRPrompt(context) {
+    return `Generate a pull request title and description based on the following changes.
+
+Task: ${context.taskTitle}
+Description: ${context.taskDescription}
+
+Commits:
+${context.commitLog}
+
+File changes:
+${context.diffStats}
+
+Requirements:
+- PR title must follow Conventional Commits: <type>(<scope>): <description>
+  Types: feat, fix, refactor, test, docs, chore
+- PR body must use this exact format:
+
+## What
+<1-3 bullet points describing what changed>
+
+## Why
+<1-2 sentences explaining the motivation>
+
+## Testing
+<Bulleted checklist of how to verify the changes>
+
+Return ONLY valid JSON with no other text:
+{"title": "the PR title", "body": "the PR body in markdown"}`;
+}

package/dist-server/task-runner.d.ts

@@ -0,0 +1,28 @@
+import type { Task, Agent } from './types.js';
+/**
+ * Poll tmux pane content until Claude Code's TUI is ready for input.
+ * Detects readiness by looking for the `>` input prompt character that
+ * Claude renders once its ink-based TUI has fully initialized.
+ * Falls back to proceeding after timeout (best-effort).
+ */
+export declare function waitForClaudeReady(session: string, windowIndex: number, timeoutMs?: number): Promise<void>;
+/**
+ * Kill all linked viewer sessions (`<tmuxSession>-v-*`) for a specific task.
+ * Safe to call even if no linked sessions exist.
+ */
+export declare function cleanupLinkedSessions(tmuxSession: string): Promise<void>;
+/**
+ * Clean up orphaned `-v-` viewer sessions from previous runs.
+ * Only kills linked sessions whose parent session no longer exists.
+ */
+export declare function cleanupOrphanedViewerSessions(): Promise<void>;
+/** Generate a git-safe branch slug from a title + task ID suffix. */
+export declare function slugifyTitle(title: string, id: string): string;
+export declare function startTask(task: Task): Promise<void>;
+export declare function addAgent(task: Task, prompt?: string): Promise<Agent>;
+export declare function closeTask(task: Task): Promise<void>;
+export declare function deleteTask(task: Task): Promise<void>;
+export declare function stopAgent(task: Task, agent: Agent): Promise<void>;
+export declare function createUserTerminal(task: Task): Promise<number>;
+export declare function resumeTask(task: Task): Promise<void>;
+export declare function dispatchToWindow(session: string, windowIndex: number, text: string): Promise<void>;

package/dist-server/task-runner.js

@@ -0,0 +1,359 @@
+import { execFile as execFileCb, spawn } from 'child_process';
+import { promisify } from 'util';
+import crypto from 'crypto';
+import path from 'path';
+import fs from 'fs';
+import { nanoid } from 'nanoid';
+import { getDb } from './db.js';
+import { installHookSettings } from './hook-settings.js';
+const execFile = promisify(execFileCb);
+const CLAUDE_READY_TIMEOUT = process.env.NODE_ENV === 'test' ? 0 : 30_000;
+const CLAUDE_READY_POLL_INTERVAL = 500;
+/** Get the active window index of a tmux session. */
+async function getActiveWindowIndex(session) {
+    const { stdout } = await execFile('tmux', [
+        'display-message',
+        '-t',
+        session,
+        '-p',
+        '#{window_index}',
+    ]);
+    return parseInt(stdout.trim(), 10);
+}
+/** Get the index of the last window in a tmux session. */
+async function getLastWindowIndex(session) {
+    const { stdout } = await execFile('tmux', [
+        'list-windows',
+        '-t',
+        session,
+        '-F',
+        '#{window_index}',
+    ]);
+    const indices = stdout.trim().split('\n').map(Number);
+    return Math.max(...indices);
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Poll tmux pane content until Claude Code's TUI is ready for input.
+ * Detects readiness by looking for the `>` input prompt character that
+ * Claude renders once its ink-based TUI has fully initialized.
+ * Falls back to proceeding after timeout (best-effort).
+ */
+export async function waitForClaudeReady(session, windowIndex, timeoutMs = CLAUDE_READY_TIMEOUT) {
+    if (timeoutMs === 0)
+        return; // skip in tests
+    const target = `${session}:${windowIndex}`;
+    const start = Date.now();
+    while (Date.now() - start < timeoutMs) {
+        try {
+            const { stdout } = await execFile('tmux', ['capture-pane', '-t', target, '-p']);
+            // Claude Code renders a "❯" (or ">") prompt when ready for input
+            const lines = stdout.split('\n');
+            if (lines.some((line) => /^\s*[>❯]/.test(line))) {
+                return;
+            }
+        }
+        catch {
+            // pane may not exist yet — keep polling
+        }
+        await sleep(CLAUDE_READY_POLL_INTERVAL);
+    }
+    // Timeout — proceed anyway (best-effort)
+}
+/**
+ * Kill all linked viewer sessions (`<tmuxSession>-v-*`) for a specific task.
+ * Safe to call even if no linked sessions exist.
+ */
+export async function cleanupLinkedSessions(tmuxSession) {
+    let stdout;
+    try {
+        ({ stdout } = await execFile('tmux', ['list-sessions', '-F', '#{session_name}']));
+    }
+    catch {
+        return; // tmux server not running or no sessions
+    }
+    const prefix = `${tmuxSession}-v-`;
+    const linked = stdout
+        .trim()
+        .split('\n')
+        .filter((name) => name.startsWith(prefix));
+    for (const session of linked) {
+        await execFile('tmux', ['kill-session', '-t', session]).catch(() => { });
+    }
+}
+/**
+ * Clean up orphaned `-v-` viewer sessions from previous runs.
+ * Only kills linked sessions whose parent session no longer exists.
+ */
+export async function cleanupOrphanedViewerSessions() {
+    let stdout;
+    try {
+        ({ stdout } = await execFile('tmux', ['list-sessions', '-F', '#{session_name}']));
+    }
+    catch {
+        return;
+    }
+    const sessions = new Set(stdout.trim().split('\n').filter(Boolean));
+    const viewerPattern = /^(octomux-agent-.+)-v-/;
+    for (const name of sessions) {
+        const match = name.match(viewerPattern);
+        if (match) {
+            const parentSession = match[1];
+            if (!sessions.has(parentSession)) {
+                await execFile('tmux', ['kill-session', '-t', name]).catch(() => { });
+            }
+        }
+    }
+}
+/** Generate a git-safe branch slug from a title + task ID suffix. */
+export function slugifyTitle(title, id) {
+    const slug = title
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, '-') // replace non-alphanumeric with hyphens
+        .replace(/-{2,}/g, '-') // collapse consecutive hyphens
+        .replace(/^-|-$/g, '') // trim leading/trailing hyphens
+        .slice(0, 50);
+    const suffix = id.slice(0, 6);
+    return `${slug}-${suffix}`;
+}
+export async function startTask(task) {
+    const db = getDb();
+    const id = task.id;
+    const session = `octomux-agent-${id}`;
+    const slug = slugifyTitle(task.title, id);
+    const branch = task.branch || `agents/${slug}`;
+    const worktreeDir = task.branch || slug;
+    const worktreePath = path.join(task.repo_path, '.worktrees', worktreeDir);
+    try {
+        // 1. Update status to setting_up
+        db.prepare(`UPDATE tasks SET status = ?, tmux_session = ?, branch = ?, worktree = ?, updated_at = datetime('now') WHERE id = ?`).run('setting_up', session, branch, worktreePath, id);
+        // 2. Validate repo path
+        if (!fs.existsSync(task.repo_path)) {
+            throw new Error(`Repository path does not exist: ${task.repo_path}`);
+        }
+        await execFile('git', ['-C', task.repo_path, 'rev-parse', '--is-inside-work-tree']);
+        // 3. Ensure .worktrees directory exists
+        const worktreeBaseDir = path.join(task.repo_path, '.worktrees');
+        fs.mkdirSync(worktreeBaseDir, { recursive: true });
+        // 4. Create worktree (optionally from a base branch)
+        const worktreeArgs = ['-C', task.repo_path, 'worktree', 'add', worktreePath, '-b', branch];
+        if (task.base_branch) {
+            worktreeArgs.push(task.base_branch);
+        }
+        await execFile('git', worktreeArgs);
+        // 5. Copy .claude/settings.local.json if it exists
+        const settingsSrc = path.join(task.repo_path, '.claude', 'settings.local.json');
+        const settingsDst = path.join(worktreePath, '.claude', 'settings.local.json');
+        if (fs.existsSync(settingsSrc)) {
+            fs.mkdirSync(path.dirname(settingsDst), { recursive: true });
+            fs.copyFileSync(settingsSrc, settingsDst);
+        }
+        // 5b. Install hook settings for permission tracking
+        installHookSettings(worktreePath);
+        // 6. Create tmux session
+        await execFile('tmux', ['new-session', '-d', '-s', session, '-c', worktreePath]);
+        // Prevent grouped viewer sessions from constraining window size
+        await execFile('tmux', ['set-option', '-t', session, 'aggressive-resize', 'on']);
+        // 7. Query the actual window index (respects tmux base-index)
+        const windowIndex = await getActiveWindowIndex(session);
+        // 8. Create first agent record with session ID
+        const agentId = nanoid(12);
+        const claudeSessionId = crypto.randomUUID();
+        db.prepare('INSERT INTO agents (id, task_id, window_index, label, claude_session_id) VALUES (?, ?, ?, ?, ?)').run(agentId, id, windowIndex, 'Agent 1', claudeSessionId);
+        // 9. Launch claude in the window with session tracking
+        await execFile('tmux', [
+            'send-keys',
+            '-t',
+            `${session}:${windowIndex}`,
+            `claude --session-id ${claudeSessionId}`,
+            'Enter',
+        ]);
+        // 10. Wait for Claude to be ready, then dispatch initial prompt
+        if (task.initial_prompt) {
+            await waitForClaudeReady(session, windowIndex);
+            await dispatchToWindow(session, windowIndex, task.initial_prompt);
+        }
+        // 12. Mark as running
+        db.prepare(`UPDATE tasks SET status = ?, updated_at = datetime('now') WHERE id = ?`).run('running', id);
+    }
+    catch (err) {
+        db.prepare(`UPDATE tasks SET status = ?, error = ?, updated_at = datetime('now') WHERE id = ?`).run('error', err.message, id);
+    }
+}
+export async function addAgent(task, prompt) {
+    const db = getDb();
+    // Determine label from active (non-stopped) agent count
+    const activeAgents = db
+        .prepare(`SELECT * FROM agents WHERE task_id = ? AND status != 'stopped' ORDER BY window_index`)
+        .all(task.id);
+    const label = `Agent ${activeAgents.length + 1}`;
+    // Create new tmux window
+    await execFile('tmux', ['new-window', '-t', task.tmux_session, '-c', task.worktree]);
+    // Query the actual window index of the newly created window
+    const windowIndex = await getLastWindowIndex(task.tmux_session);
+    // Create agent record with session ID
+    const agentId = nanoid(12);
+    const claudeSessionId = crypto.randomUUID();
+    db.prepare('INSERT INTO agents (id, task_id, window_index, label, claude_session_id) VALUES (?, ?, ?, ?, ?)').run(agentId, task.id, windowIndex, label, claudeSessionId);
+    // Launch claude with session tracking
+    await execFile('tmux', [
+        'send-keys',
+        '-t',
+        `${task.tmux_session}:${windowIndex}`,
+        `claude --session-id ${claudeSessionId}`,
+        'Enter',
+    ]);
+    // Dispatch prompt if provided
+    if (prompt) {
+        await waitForClaudeReady(task.tmux_session, windowIndex);
+        await dispatchToWindow(task.tmux_session, windowIndex, prompt);
+    }
+    return {
+        id: agentId,
+        task_id: task.id,
+        window_index: windowIndex,
+        label,
+        status: 'running',
+        claude_session_id: claudeSessionId,
+        hook_activity: 'active',
+        hook_activity_updated_at: null,
+        created_at: new Date().toISOString(),
+    };
+}
+export async function closeTask(task) {
+    const db = getDb();
+    // Resolve all pending permission prompts for this task
+    db.prepare(`UPDATE permission_prompts SET status = 'resolved', resolved_at = datetime('now')
+     WHERE task_id = ? AND status = 'pending'`).run(task.id);
+    // Mark task as closed and all agents as stopped
+    db.prepare(`UPDATE tasks SET status = 'closed', updated_at = datetime('now') WHERE id = ?`).run(task.id);
+    db.prepare(`UPDATE agents SET status = 'stopped', hook_activity = 'idle', hook_activity_updated_at = datetime('now') WHERE task_id = ?`).run(task.id);
+    // Kill linked viewer sessions, then main tmux session — worktree and branch are preserved for resume
+    if (task.tmux_session) {
+        await cleanupLinkedSessions(task.tmux_session);
+        await execFile('tmux', ['kill-session', '-t', task.tmux_session]).catch(() => { });
+    }
+}
+export async function deleteTask(task) {
+    // Kill linked viewer sessions, then main tmux session
+    if (task.tmux_session) {
+        await cleanupLinkedSessions(task.tmux_session);
+        await execFile('tmux', ['kill-session', '-t', task.tmux_session]).catch(() => { });
+    }
+    // Remove worktree
+    if (task.worktree) {
+        await execFile('git', [
+            '-C',
+            task.repo_path,
+            'worktree',
+            'remove',
+            task.worktree,
+            '--force',
+        ]).catch(() => { });
+    }
+    // Delete branch
+    if (task.branch) {
+        await execFile('git', ['-C', task.repo_path, 'branch', '-D', task.branch]).catch(() => { });
+    }
+}
+export async function stopAgent(task, agent) {
+    const db = getDb();
+    // Resolve pending permission prompts for this agent
+    db.prepare(`UPDATE permission_prompts SET status = 'resolved', resolved_at = datetime('now')
+     WHERE agent_id = ? AND status = 'pending'`).run(agent.id);
+    // Kill the specific tmux window
+    await execFile('tmux', ['kill-window', '-t', `${task.tmux_session}:${agent.window_index}`]).catch(() => { });
+    // Mark agent as stopped and idle
+    db.prepare(`UPDATE agents SET status = 'stopped', hook_activity = 'idle', hook_activity_updated_at = datetime('now') WHERE id = ?`).run(agent.id);
+}
+export async function createUserTerminal(task) {
+    if (task.user_window_index !== null && task.user_window_index !== undefined) {
+        return task.user_window_index;
+    }
+    const db = getDb();
+    await execFile('tmux', ['new-window', '-t', task.tmux_session, '-c', task.worktree]);
+    const windowIndex = await getLastWindowIndex(task.tmux_session);
+    await execFile('tmux', [
+        'send-keys',
+        '-t',
+        `${task.tmux_session}:${windowIndex}`,
+        'nvim .',
+        'Enter',
+    ]);
+    db.prepare(`UPDATE tasks SET user_window_index = ?, updated_at = datetime('now') WHERE id = ?`).run(windowIndex, task.id);
+    return windowIndex;
+}
+export async function resumeTask(task) {
+    const db = getDb();
+    const session = task.tmux_session;
+    try {
+        // 1. Set status synchronously to prevent poller race
+        db.prepare(`UPDATE tasks SET status = 'setting_up', error = NULL, user_window_index = NULL, updated_at = datetime('now') WHERE id = ?`).run(task.id);
+        // 2. Kill any stale linked viewer sessions and tmux session
+        await cleanupLinkedSessions(session);
+        await execFile('tmux', ['kill-session', '-t', session]).catch(() => { });
+        // 3. Create fresh tmux session
+        await execFile('tmux', ['new-session', '-d', '-s', session, '-c', task.worktree]);
+        await execFile('tmux', ['set-option', '-t', session, 'aggressive-resize', 'on']);
+        // 3b. Install hook settings for permission tracking
+        installHookSettings(task.worktree);
+        // 4. Get stopped agents
+        const agents = db
+            .prepare(`SELECT * FROM agents WHERE task_id = ? AND status = 'stopped' ORDER BY window_index`)
+            .all(task.id);
+        for (let i = 0; i < agents.length; i++) {
+            const agent = agents[i];
+            let windowIndex;
+            if (i === 0) {
+                // Use the initial session window
+                windowIndex = await getActiveWindowIndex(session);
+            }
+            else {
+                // Create new window for subsequent agents
+                await execFile('tmux', ['new-window', '-t', session, '-c', task.worktree]);
+                windowIndex = await getLastWindowIndex(session);
+            }
+            // Launch claude with resume or continue
+            let claudeCmd;
+            if (agent.claude_session_id) {
+                claudeCmd = `claude --resume ${agent.claude_session_id}`;
+            }
+            else {
+                const newSessionId = crypto.randomUUID();
+                claudeCmd = `claude --continue --session-id ${newSessionId}`;
+                db.prepare('UPDATE agents SET claude_session_id = ? WHERE id = ?').run(newSessionId, agent.id);
+            }
+            await execFile('tmux', ['send-keys', '-t', `${session}:${windowIndex}`, claudeCmd, 'Enter']);
+            // Update agent record
+            db.prepare(`UPDATE agents SET window_index = ?, status = 'running' WHERE id = ?`).run(windowIndex, agent.id);
+        }
+        // 5. Mark task as running
+        db.prepare(`UPDATE tasks SET status = 'running', updated_at = datetime('now') WHERE id = ?`).run(task.id);
+    }
+    catch (err) {
+        db.prepare(`UPDATE tasks SET status = 'error', error = ?, updated_at = datetime('now') WHERE id = ?`).run(err.message, task.id);
+    }
+}
+export async function dispatchToWindow(session, windowIndex, text) {
+    const target = `${session}:${windowIndex}`;
+    const bufferName = `octomux-${nanoid(8)}`;
+    // Load text into a named tmux buffer (avoids race with concurrent dispatches).
+    // Do NOT append '\n' — send-keys Enter handles submission separately.
+    await new Promise((resolve, reject) => {
+        const proc = spawn('tmux', ['load-buffer', '-b', bufferName, '-']);
+        proc.stdin.write(text);
+        proc.stdin.end();
+        proc.on('close', (code) => {
+            if (code === 0)
+                resolve();
+            else
+                reject(new Error(`tmux load-buffer exited with code ${code}`));
+        });
+    });
+    // Paste named buffer into the target window, -d deletes buffer after paste
+    await execFile('tmux', ['paste-buffer', '-b', bufferName, '-d', '-t', target]);
+    // Press Enter to submit the prompt
+    await execFile('tmux', ['send-keys', '-t', target, 'Enter']);
+}

package/dist-server/terminal.d.ts

@@ -0,0 +1,13 @@
+import { WebSocket } from 'ws';
+import { type IPty } from 'node-pty';
+import type { IncomingMessage } from 'http';
+import type { Duplex } from 'stream';
+interface TerminalConnection {
+    ws: WebSocket;
+    pty: IPty;
+}
+export declare function setupTerminalWebSocket(): void;
+export declare function handleTerminalUpgrade(req: IncomingMessage, socket: Duplex, head: Buffer): boolean;
+export declare function getActiveConnections(): Map<string, TerminalConnection[]>;
+export declare function cleanupAllConnections(): void;
+export {};