@ebowwa/terminal 0.2.0

package/src/sessions.ts

@@ -0,0 +1,861 @@
+/**
+ * Terminal Session Management
+ * Handles SSH PTY session lifecycle, persistence, and querying
+ * Uses tmux for persistent sessions that survive disconnections
+ */
+
+import path from "node:path";
+import { createOrAttachTmuxSession, killTmuxSession } from "./tmux.js";
+// metadata import for updating bootstrapStatus on terminal connect
+// import { getMetadata, setMetadata } from "cheapspaces/workspace/src/lib/metadata";
+import type { WebSocket, ServerWebSocket, Subprocess } from "bun";
+import { WebSocketCloseCode } from "@ebowwa/codespaces-types/compile";
+
+// Lazy-load metadata functions (Hetzner-specific, optional)
+let metadataModule: {
+  getMetadata: (id: string) => any;
+  setMetadata: (metadata: any) => void;
+} | null = null;
+
+function loadMetadata() {
+  if (metadataModule === null) {
+    try {
+      // Try to import from Hetzner workspace
+      metadataModule = require("@ebowwa/hetzner-workspace-metadata");
+    } catch {
+      // Metadata module not available - bootstrap status tracking will be disabled
+      metadataModule = { getMetadata: null as any, setMetadata: null as any };
+    }
+  }
+  return metadataModule;
+}
+
+/**
+ * Resolve SSH key path to absolute path
+ * Handles legacy relative paths from metadata
+ */
+function resolveKeyPath(keyPath: string | undefined): string | undefined {
+  if (!keyPath) return undefined;
+  if (path.isAbsolute(keyPath)) return keyPath;
+
+  // Legacy relative paths like "../.ssh-keys/..." - resolve from project root
+  const projectRoot = path.resolve(import.meta.dir, "../../com.hetzner.codespaces");
+  if (keyPath.includes(".ssh-keys")) {
+    const keyName = path.basename(keyPath);
+    return path.join(projectRoot, ".ssh-keys", keyName);
+  }
+  return path.resolve(keyPath);
+}
+
+/**
+ * Terminal session interface
+ * Represents an active SSH PTY session
+ */
+export interface TerminalSession {
+  sessionId: string;
+  proc: Subprocess<"pipe", "pipe", "pipe">;
+  stdin: Subprocess<"pipe", "pipe", "pipe">["stdin"];
+  stdout: ReadableStream<Uint8Array>;
+  stderr: ReadableStream<Uint8Array>;
+  host: string;
+  user: string;
+  ws: ServerWebSocket<unknown> | null;
+  createdAt: number;
+  lastUsed: number;
+  reader: ReadableStreamDefaultReader<Uint8Array> | null;
+  stderrReader: ReadableStreamDefaultReader<Uint8Array> | null;
+  writer: WritableStreamDefaultWriter<Uint8Array> | null;
+  closed: boolean;
+  tmuxSessionName?: string; // tmux session name if using tmux
+  bootstrapLogStreamer?: Subprocess; // Cloud-init log tail process
+}
+
+/**
+ * Session info for API responses (safe to expose)
+ */
+export interface SessionInfo {
+  sessionId: string;
+  host: string;
+  user: string;
+  createdAt: number;
+  lastUsed: number;
+  hasActiveWebSocket: boolean;
+  closed: boolean;
+  uptime: number;
+  idleTime: number;
+}
+
+// Active sessions storage
+const terminalSessions = new Map<string, TerminalSession>();
+
+/**
+ * Clean up old sessions (older than specified milliseconds)
+ * Called automatically by interval timer
+ */
+export function cleanupStaleSessions(maxAge: number = 30 * 60 * 1000): string[] {
+  const now = Date.now();
+  const cleaned: string[] = [];
+
+  for (const [id, session] of terminalSessions.entries()) {
+    // Only clean up sessions that have no active WebSocket and are stale
+    if (now - session.lastUsed > maxAge && !session.ws) {
+      console.log(
+        `[Terminal] Cleaning up stale session ${id} (${session.host})`,
+      );
+      closeSession(id);
+      cleaned.push(id);
+    }
+  }
+
+  return cleaned;
+}
+
+/**
+ * Close a specific session
+ */
+export async function closeSession(sessionId: string): Promise<boolean> {
+  const session = terminalSessions.get(sessionId);
+  if (!session) return false;
+
+  session.closed = true;
+
+  // Close stdout reader if exists
+  if (session.reader) {
+    try {
+      session.reader.releaseLock();
+    } catch {
+      // Already released
+    }
+  }
+
+  // Close stderr reader if exists
+  if (session.stderrReader) {
+    try {
+      session.stderrReader.releaseLock();
+    } catch {
+      // Already released
+    }
+  }
+
+  // Close WebSocket if still connected
+  try {
+    session.ws?.close(WebSocketCloseCode.NORMAL_CLOSURE, "Session closed");
+  } catch {
+    // Already closed
+  }
+
+  // Kill bootstrap log streamer if still running
+  if (session.bootstrapLogStreamer) {
+    try {
+      session.bootstrapLogStreamer.kill();
+      console.log(`[Terminal] Killed bootstrap log streamer for ${sessionId}`);
+    } catch {
+      // Already killed
+    }
+  }
+
+  // Kill tmux session if it exists (keep session alive on server)
+  if (session.tmuxSessionName) {
+    console.log(`[Terminal] Leaving tmux session "${session.tmuxSessionName}" alive on server`);
+    // Don't kill tmux session - it persists for reconnection
+  }
+
+  // Kill the SSH process (detaches from tmux but keeps it running)
+  try {
+    session.proc.kill();
+  } catch {
+    // Already terminated
+  }
+
+  terminalSessions.delete(sessionId);
+  console.log(`[Terminal] Session ${sessionId} closed`);
+
+  return true;
+}
+
+/**
+ * Stream cloud-init bootstrap logs from remote server
+ * Spawns a background SSH subprocess that tails the cloud-init output log
+ * @param host - Target server hostname or IP
+ * @param user - SSH user (default: root)
+ * @param keyPath - Optional path to SSH private key
+ * @param onOutput - Callback for each line of log output
+ * @param stopSignal - Object with `stopped: boolean` to signal when to stop streaming
+ * @returns Promise that resolves when streaming stops
+ */
+async function streamCloudInitLogs(
+  host: string,
+  user: string,
+  keyPath: string | undefined,
+  onOutput: (data: string) => void,
+  stopSignal: { stopped: boolean },
+): Promise<Subprocess | null> {
+  try {
+    // Build SSH command for tailing cloud-init logs
+    const sshCmd: string[] = [
+      "ssh",
+      "-F", "/dev/null",  // Skip user SSH config
+      "-o", "StrictHostKeyChecking=no",
+      "-o", "UserKnownHostsFile=/dev/null",
+      "-o", "ServerAliveInterval=30",
+      "-o", "ServerAliveCountMax=3",
+    ];
+
+    if (keyPath) {
+      sshCmd.push("-i", String(keyPath));
+    }
+
+    // Tail cloud-init logs, with fallback to seed-setup log
+    // Using -n +0 to output all existing content, then follow for new lines
+    sshCmd.push(
+      "-p", "22",
+      `${user}@${host}`,
+      "tail -n +0 -f /var/log/cloud-init-output.log 2>/dev/null || tail -n +0 -f /var/log/seed-setup.log 2>/dev/null || echo 'Waiting for bootstrap logs to become available...'"
+    );
+
+    console.log("[Bootstrap] Starting log streamer for", host);
+
+    // Spawn subprocess to tail logs
+    const proc = Bun.spawn(sshCmd, {
+      stdout: "pipe",
+      stderr: "pipe",
+      env: {
+        ...process.env,
+        // Suppress SSH warnings
+        LANG: "en_US.UTF-8",
+      },
+    });
+
+    // Read stdout and send to callback
+    const reader = proc.stdout.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+
+    // Start reading in background
+    (async () => {
+      try {
+        while (!stopSignal.stopped) {
+          const { done, value } = await reader.read();
+          if (done) {
+            console.log("[Bootstrap] Log streamer EOF reached");
+            break;
+          }
+
+          buffer += decoder.decode(value, { stream: true });
+          const lines = buffer.split("\n");
+          buffer = lines.pop() || ""; // Keep partial line in buffer
+
+          for (const line of lines) {
+            if (line) {
+              onOutput(line + "\n");
+            }
+          }
+        }
+      } catch (err) {
+        if (!stopSignal.stopped) {
+          console.log("[Bootstrap] Log streamer error:", err);
+        }
+      } finally {
+        reader.releaseLock();
+      }
+    })();
+
+    return proc;
+  } catch (err) {
+    console.error("[Bootstrap] Failed to start log streamer:", err);
+    return null;
+  }
+}
+
+/**
+ * Find or create a session for a host
+ * If sessionId is provided, try to reuse that specific session
+ * If sessionId is null/undefined, always create a new session (for multiple terminals)
+ * @param onProgress - Optional callback to send progress updates to WebSocket
+ * @param onBootstrapOutput - Optional callback to stream bootstrap log output to WebSocket
+ */
+export async function getOrCreateSession(
+  host: string,
+  user: string = "root",
+  sessionId: string | null = null,
+  keyPath?: string,
+  onProgress?: (message: string, status: "info" | "success" | "error") => void,
+  environmentId?: string,
+  onBootstrapOutput?: (data: string) => void,
+): Promise<TerminalSession> {
+  // Resolve relative key paths to absolute
+  keyPath = resolveKeyPath(keyPath);
+
+  // If specific sessionId requested, try to find and reuse it
+  if (sessionId) {
+    const existing = terminalSessions.get(sessionId);
+    if (existing && !existing.closed && existing.host === host && existing.user === user) {
+      console.log(
+        `[Terminal] Reusing requested session ${sessionId} for ${user}@${host}`,
+      );
+      existing.ws = null; // Will be set by caller
+      existing.lastUsed = Date.now();
+      return existing;
+    }
+    // Requested session not found or invalid - will create new below
+    console.log(
+      `[Terminal] Requested session ${sessionId} not found, creating new one`,
+    );
+  }
+
+  // Create new session (always creates when sessionId is null or not found)
+  const newSessionId = `term-${host.replace(/[^a-zA-Z0-9]/g, "_")}-${Date.now()}-${Math.random().toString(36).substring(2, 8)}`;
+  console.log(
+    `[Terminal] Creating new session ${newSessionId} for ${user}@${host}`,
+  );
+
+  const progress = (msg: string, status: "info" | "success" | "error" = "info") => {
+    console.log(`[Terminal] ${msg}`);
+    onProgress?.(msg, status);
+  };
+
+  // First, verify SSH is reachable before attempting seed installation
+  progress(`Waiting for SSH connection to ${host}...`);
+  let sshReachable = false;
+  let lastError: string | null = null;
+  const timeout = 5;
+  const maxAttempts = 5; // Increased attempts for faster retries
+  const retryDelayMs = 500; // Reduced from 1s to 500ms for faster recovery
+
+  // Resolve and validate SSH key path before connection attempts
+  let resolvedKeyPath: string | null = null;
+  let keyFileExists = false;
+  let keyFilePermissions = null;
+  let keyFileStats = null;
+
+  if (keyPath) {
+    try {
+      resolvedKeyPath = require('path').resolve(keyPath);
+      const keyStats = await import('fs').then(fs => resolvedKeyPath ? fs.promises.stat(resolvedKeyPath).catch(() => null) : null);
+      keyFileExists = keyStats !== null;
+      if (keyStats) {
+        keyFileStats = {
+          size: keyStats.size,
+          mode: keyStats.mode.toString(8),
+          isFile: keyStats.isFile(),
+        };
+        // Extract Unix permissions (last 3 octal digits)
+        keyFilePermissions = (keyStats.mode & parseInt('777', 8)).toString(8);
+      }
+      console.log(`[Terminal] SSH key validation: keyPath=${keyPath}, resolvedPath=${resolvedKeyPath}, exists=${keyFileExists}, permissions=${keyFilePermissions ?? 'N/A'}, stats=${keyFileStats ? JSON.stringify(keyFileStats) : 'N/A'}`);
+    } catch (pathErr) {
+      console.log(`[Terminal] SSH key path resolution failed: keyPath=${keyPath}, error=${pathErr instanceof Error ? pathErr.message : String(pathErr)}`);
+    }
+  } else {
+    console.log(`[Terminal] SSH key validation: no keyPath provided (will attempt ssh-agent)`);
+  }
+
+  console.log(`[Terminal] SSH connection parameters: target=${user}@${host}, timeout=${timeout}s, maxAttempts=${maxAttempts}, retryDelay=${retryDelayMs}ms, keyPath=${keyPath ?? 'none'}, resolvedKeyPath=${resolvedKeyPath ?? 'none'}, keyFileExists=${keyFileExists}, keyFilePermissions=${keyFilePermissions ?? 'N/A'}`);
+
+  // Try up to maxAttempts times with short timeout to check if SSH is reachable
+  for (let i = 0; i < maxAttempts; i++) {
+    const attempt = i + 1;
+    const attemptStart = Date.now();
+    try {
+      console.log(`[Terminal] SSH connection attempt ${attempt}/${maxAttempts} starting (attemptIdx=${i}, sshReachable=${sshReachable}, lastError=${lastError ?? 'null'})`);
+      const { execSSH } = await import("./client.js");
+      // Quick connection test with configurable timeout
+      await execSSH("echo ok", {
+        host,
+        user,
+        keyPath,
+        timeout,
+      });
+      const elapsed = Date.now() - attemptStart;
+      sshReachable = true;
+      console.log(`[Terminal] SSH connection successful on attempt ${attempt}/${maxAttempts} (elapsedMs=${elapsed}, sshReachable=true)`);
+      break;
+    } catch (err) {
+      const elapsed = Date.now() - attemptStart;
+      const errType = err instanceof Error ? err.constructor.name : typeof err;
+      const errorMsg = err instanceof Error ? err.message : String(err);
+      const errName = err instanceof Error ? err.name : 'UnknownError';
+      // Extract cause from SSHError if available
+      const cause = (err as { cause?: unknown }).cause;
+      const causeType = cause instanceof Error ? cause.constructor.name : typeof cause;
+      const causeMsg = cause instanceof Error ? ` (cause: ${cause.message})` : cause ? ` (cause: ${String(cause)})` : "";
+      lastError = `${errorMsg}${causeMsg}`;
+      console.log(`[Terminal] SSH connection attempt ${attempt}/${maxAttempts} failed (elapsedMs=${elapsed}, errType=${errType}, errName=${errName}, causeType=${causeType}, sshReachable=${sshReachable}, lastError=${lastError})`);
+      // If it's a connection error, server might still be booting
+      if (i < maxAttempts - 1) {
+        // Wait a bit before retrying
+        console.log(`[Terminal] Waiting ${retryDelayMs}ms before retry ${attempt + 1}/${maxAttempts}...`);
+        await new Promise(resolve => setTimeout(resolve, retryDelayMs));
+      }
+    }
+  }
+
+  if (sshReachable) {
+    // Check if metadata already says ready — skip polling entirely
+    if (environmentId) {
+      const metadata = loadMetadata();
+      const existing = metadata.getMetadata?.(environmentId);
+      if (existing?.bootstrapStatus === "ready") {
+        progress(`SSH connected. Environment ready.`, "success");
+        // Skip the bootstrap gate entirely
+      } else {
+        // Fall through to polling below
+      }
+    }
+
+    // Only poll if we don't already know the status
+    const metadata = loadMetadata();
+    const knownReady = environmentId && metadata.getMetadata
+      ? metadata.getMetadata(environmentId)?.bootstrapStatus === "ready"
+      : false;
+
+    const bootstrapMaxAttempts = 60; // Poll up to 60 times
+    const bootstrapPollIntervalMs = 5000; // Every 5 seconds = 5 min max
+    let bootstrapComplete = knownReady;
+
+    // Start streaming bootstrap logs if callback provided
+    const stopLogStreaming = { stopped: false };
+    let logStreamer: Subprocess | null = null;
+
+    if (!knownReady) {
+      progress(`SSH connected. Checking bootstrap status...`);
+
+      // Start streaming logs if callback is provided
+      if (onBootstrapOutput) {
+        logStreamer = await streamCloudInitLogs(
+          host,
+          user,
+          keyPath,
+          onBootstrapOutput,
+          stopLogStreaming,
+        );
+      }
+    }
+
+    for (let attempt = 0; !bootstrapComplete && attempt < bootstrapMaxAttempts; attempt++) {
+      try {
+        const { execSSH } = await import("./client.js");
+        const result = await execSSH(
+          "cat /root/.bootstrap-status 2>/dev/null || echo 'status=missing'",
+          { host, user, keyPath, timeout: 10 }
+        );
+
+        const output = (typeof result === "string" ? result : String(result)).trim();
+        // bootstrap-status is appended to — check if the final status= line says complete
+        const statusLines = output.split("\n").filter((l: string) => l.startsWith("status="));
+        const lastStatus = statusLines.length > 0 ? statusLines[statusLines.length - 1] : "";
+
+        if (lastStatus === "status=complete") {
+          bootstrapComplete = true;
+          progress(`Bootstrap complete.`, "success");
+          // Stop log streaming
+          stopLogStreaming.stopped = true;
+          if (logStreamer) {
+            try {
+              logStreamer.kill();
+            } catch {
+              // Already killed
+            }
+          }
+          // Update metadata so the frontend knows this env is ready
+          if (environmentId) {
+            try {
+              const metadata = loadMetadata();
+              const existing = metadata.getMetadata?.(environmentId);
+              if (existing && existing.bootstrapStatus !== "ready" && metadata.setMetadata) {
+                metadata.setMetadata({ ...existing, bootstrapStatus: "ready" });
+              }
+            } catch { /* non-fatal */ }
+          }
+          break;
+        }
+
+        if (lastStatus === "status=missing") {
+          // No bootstrap-status file — server may not use cloud-init, allow through
+          console.log(`[Terminal] No /root/.bootstrap-status found, skipping gate`);
+          bootstrapComplete = true;
+          progress(`No bootstrap status file found — skipping readiness gate.`);
+          // Stop log streaming
+          stopLogStreaming.stopped = true;
+          if (logStreamer) {
+            try {
+              logStreamer.kill();
+            } catch {
+              // Already killed
+            }
+          }
+          if (environmentId) {
+            try {
+              const metadata = loadMetadata();
+              const existing = metadata.getMetadata?.(environmentId);
+              if (existing && existing.bootstrapStatus !== "ready" && metadata.setMetadata) {
+                metadata.setMetadata({ ...existing, bootstrapStatus: "ready" });
+              }
+            } catch { /* non-fatal */ }
+          }
+          break;
+        }
+
+        // Still in progress
+        if (attempt === 0) {
+          progress(`Server is still bootstrapping. Waiting for cloud-init to finish...`);
+        } else if (attempt % 6 === 0) {
+          // Log progress every ~30 seconds
+          progress(`Still bootstrapping... (${attempt * 5}s elapsed)`);
+        }
+      } catch (pollErr) {
+        console.log(`[Terminal] Bootstrap status poll attempt ${attempt + 1} failed: ${pollErr instanceof Error ? pollErr.message : String(pollErr)}`);
+        // SSH might have dropped during heavy bootstrap — keep trying
+      }
+
+      await new Promise(resolve => setTimeout(resolve, bootstrapPollIntervalMs));
+    }
+
+    // Clean up log streamer if still running
+    if (!bootstrapComplete) {
+      stopLogStreaming.stopped = true;
+      if (logStreamer) {
+        try {
+          logStreamer.kill();
+        } catch {
+          // Already killed
+        }
+      }
+      progress(`Bootstrap did not complete within 5 minutes. Connecting anyway...`, "error");
+    }
+  } else {
+    // SSH not reachable - server is likely still booting
+    progress(`Server not ready yet (${lastError}) - tried 3 attempts with ${timeout}s timeout each`, "info");
+    console.log(`[Terminal] All SSH connection attempts exhausted, continuing anyway - frontend will retry`);
+    // Continue to create SSH connection anyway - frontend has retry logic
+  }
+
+  // Use tmux for persistent sessions
+  // This will install tmux if not present, then create/attach to session
+  let sshCmd: string[];
+  let tmuxSessionName: string | undefined;
+
+  try {
+    const tmuxResult = await createOrAttachTmuxSession(host, user, keyPath);
+    sshCmd = tmuxResult.sshArgs;
+    tmuxSessionName = tmuxResult.sessionName;
+    console.log(`[Terminal] Using tmux session: ${tmuxSessionName}${tmuxResult.newlyCreated ? ' (newly created)' : ' (reattached)'}`);
+  } catch (tmuxError) {
+    console.error(`[Terminal] tmux setup failed: ${tmuxError}`);
+    // Fallback to plain SSH without tmux
+    sshCmd = [
+      "ssh",
+      "-F", "/dev/null",  // Skip user SSH config to avoid conflicts
+      "-o", "StrictHostKeyChecking=no",
+      "-o", "UserKnownHostsFile=/dev/null",
+      "-o", "ServerAliveInterval=30",
+      "-o", "ServerAliveCountMax=3",
+      "-p", "22",
+    ];
+    if (keyPath) {
+      // Ensure keyPath is properly escaped for SSH
+      // Bun.spawn() passes args directly without shell, but SSH -i needs proper path handling
+      // When keyPath contains spaces, we need to ensure it's a single argument
+      sshCmd.push("-i", String(keyPath));
+    }
+    sshCmd.push("-t", "-t", `${user}@${host}`);
+  }
+
+  console.log("[Terminal] Spawning SSH:", sshCmd.join(" "));
+
+  const proc = Bun.spawn(sshCmd, {
+    stdin: "pipe",
+    stdout: "pipe",
+    stderr: "pipe",
+    env: {
+      ...process.env,
+      TERM: "xterm-256color",
+    },
+  });
+
+  const stdin = proc.stdin;
+  const stdout = proc.stdout as ReadableStream<Uint8Array>;
+  const stderr = proc.stderr as ReadableStream<Uint8Array>;
+
+  const session: TerminalSession = {
+    sessionId: newSessionId,
+    proc,
+    stdin,
+    stdout,
+    stderr,
+    host,
+    user,
+    ws: null,
+    createdAt: Date.now(),
+    lastUsed: Date.now(),
+    reader: null,
+    stderrReader: null,
+    writer: null,
+    closed: false,
+    tmuxSessionName,
+  };
+
+  terminalSessions.set(newSessionId, session);
+
+  // Handle process exit
+  proc.exited
+    .then((exitCode) => {
+      console.log(
+        `[Terminal] Process for ${newSessionId} exited with code ${exitCode}`,
+      );
+      session.closed = true;
+      try {
+        session.ws?.close(
+          WebSocketCloseCode.NORMAL_CLOSURE,
+          `SSH process exited (code: ${exitCode})`
+        );
+      } catch {
+        // Already closed
+      }
+      terminalSessions.delete(newSessionId);
+    })
+    .catch((err) => {
+      console.log(`[Terminal] Process exit error for ${newSessionId}:`, err);
+      session.closed = true;
+      try {
+        session.ws?.close(
+          WebSocketCloseCode.INTERNAL_ERROR,
+          "SSH process error"
+        );
+      } catch {
+        // Already closed
+      }
+    });
+
+  return session;
+}
+
+/**
+ * Get a session by ID
+ */
+export function getSession(sessionId: string): TerminalSession | undefined {
+  return terminalSessions.get(sessionId);
+}
+
+/**
+ * Get all active sessions
+ */
+export function getAllSessions(): TerminalSession[] {
+  return Array.from(terminalSessions.values());
+}
+
+/**
+ * Get session info for all sessions (safe for API responses)
+ */
+export function getAllSessionInfo(): SessionInfo[] {
+  const now = Date.now();
+  return Array.from(terminalSessions.values()).map((session) => ({
+    sessionId: session.sessionId,
+    host: session.host,
+    user: session.user,
+    createdAt: session.createdAt,
+    lastUsed: session.lastUsed,
+    hasActiveWebSocket: !!session.ws,
+    closed: session.closed,
+    uptime: now - session.createdAt,
+    idleTime: now - session.lastUsed,
+  }));
+}
+
+/**
+ * Get session info for a specific session
+ */
+export function getSessionInfo(sessionId: string): SessionInfo | undefined {
+  const session = terminalSessions.get(sessionId);
+  if (!session) return undefined;
+
+  const now = Date.now();
+  return {
+    sessionId: session.sessionId,
+    host: session.host,
+    user: session.user,
+    createdAt: session.createdAt,
+    lastUsed: session.lastUsed,
+    hasActiveWebSocket: !!session.ws,
+    closed: session.closed,
+    uptime: now - session.createdAt,
+    idleTime: now - session.lastUsed,
+  };
+}
+
+/**
+ * Get the total number of active sessions
+ */
+export function getSessionCount(): number {
+  return terminalSessions.size;
+}
+
+/**
+ * Find sessions by host
+ */
+export function getSessionsByHost(host: string): TerminalSession[] {
+  return Array.from(terminalSessions.values()).filter(
+    (s) => s.host === host && !s.closed
+  );
+}
+
+/**
+ * Attach a WebSocket to a session
+ * Sets up stdin/stdout/stderr streaming
+ */
+export function attachWebSocket(
+  session: TerminalSession,
+  ws: ServerWebSocket<unknown>,
+  wasReused: boolean = false
+): void {
+  session.ws = ws;
+  session.lastUsed = Date.now();
+
+  // Send session info to client
+  ws.send(
+    JSON.stringify({
+      type: "session",
+      sessionId: session.sessionId,
+      existing: wasReused,
+      host: session.host,
+      user: session.user,
+    }),
+  );
+
+  // Start or resume reading stderr
+  if (!session.stderrReader) {
+    const readStderr = async () => {
+      const reader = session.stderr.getReader();
+      session.stderrReader = reader;
+      try {
+        while (!session.closed) {
+          const { value, done } = await reader.read();
+          if (done || session.closed) break;
+          if (value && session.ws) {
+            const text = new TextDecoder().decode(value);
+            console.log(`[Terminal] stderr: ${text.trim()}`);
+            try {
+              session.ws.send(text);
+            } catch {
+              // WebSocket closed, stop reading temporarily
+              session.ws = null;
+            }
+          }
+        }
+      } catch (err) {
+        if (!session.closed) {
+          console.log(`[Terminal] stderr read error:`, err);
+        }
+      } finally {
+        if (session.closed) {
+          session.stderrReader = null;
+          reader.releaseLock();
+        }
+        // Keep reader open for potential reconnection
+      }
+    };
+    readStderr();
+  }
+
+  // Start or resume reading stdout
+  if (!session.reader) {
+    const readOutput = async () => {
+      const reader = session.stdout.getReader();
+      session.reader = reader;
+
+      try {
+        while (!session.closed) {
+          const { value, done } = await reader.read();
+          if (done || session.closed) {
+            console.log(`[Terminal] stdout closed for ${session.sessionId}`);
+            break;
+          }
+
+          if (value) {
+            const text = new TextDecoder().decode(value);
+            if (session.ws) {
+              try {
+                session.ws.send(text);
+              } catch {
+                // WebSocket closed, stop reading temporarily
+                session.ws = null;
+              }
+            }
+          }
+        }
+      } catch (err) {
+        if (!session.closed) {
+          console.log(`[Terminal] stdout read error:`, err);
+        }
+      } finally {
+        if (session.closed) {
+          reader.releaseLock();
+        }
+        // Keep reader open for potential reconnection
+      }
+    };
+    readOutput();
+  }
+}
+
+/**
+ * Write data to a session's stdin
+ */
+export async function writeToSession(
+  sessionId: string,
+  data: string
+): Promise<boolean> {
+  const session = terminalSessions.get(sessionId);
+  if (!session) {
+    console.log(`[Terminal] Write failed: session ${sessionId} not found`);
+    return false;
+  }
+  if (session.closed) {
+    console.log(`[Terminal] Write failed: session ${sessionId} is closed`);
+    return false;
+  }
+
+  try {
+    await session.stdin.write(data);
+    session.lastUsed = Date.now();
+    return true;
+  } catch (err) {
+    console.log(`[Terminal] Write error for ${sessionId}:`, err);
+    return false;
+  }
+}
+
+/**
+ * Resize a session's PTY
+ */
+export async function resizeSession(
+  sessionId: string,
+  rows: number,
+  cols: number
+): Promise<boolean> {
+  const session = terminalSessions.get(sessionId);
+  if (!session || session.closed) return false;
+
+  try {
+    // Send SIGWINCH via escape sequence
+    await session.stdin.write(`\u001B[8;${rows};${cols}t`);
+    session.lastUsed = Date.now();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Detach WebSocket from session (without closing session)
+ */
+export function detachWebSocket(sessionId: string, ws: ServerWebSocket): boolean {
+  const session = terminalSessions.get(sessionId);
+  if (!session || session.ws !== ws) return false;
+
+  session.ws = null;
+  console.log(
+    `[Terminal] Detached WebSocket from session ${sessionId}, keeping SSH alive`,
+  );
+  return true;
+}