@seflless/ghosttown 1.6.2 → 1.10.0

package/src/cli.js

@@ -8,7 +8,7 @@
  *   ghosttown [options] [command]
  *
  * Options:
- *   -p, --port <port>    Port to listen on (default: 8080, or PORT env var)
+ *   -p, --port <port>    Port to listen on (default: auto-discover available port)
  *   -n, --name <name>    Give the session a custom name
  *   -k, --kill [session] Kill a session (current if inside one, or specify by name)
  *   -ka, --kill-all      Kill all ghosttown sessions
@@ -50,6 +50,24 @@ import pty from '@lydell/node-pty';
 import { WebSocketServer } from 'ws';
 // ASCII art generator
 import { asciiArt } from '../bin/ascii.js';
+// Session name utilities
+import { displayNameExists, findSession, validateSessionName } from './session-utils.js';
+// Session management - custom PTY session manager (replaces tmux)
+import { SessionManager } from './session/session-manager.js';
+
+// Global SessionManager instance (lazy-initialized)
+let sessionManager = null;
+
+/**
+ * Get or create the SessionManager instance
+ */
+async function getSessionManager() {
+  if (!sessionManager) {
+    sessionManager = new SessionManager();
+    await sessionManager.init();
+  }
+  return sessionManager;
+}
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -73,6 +91,64 @@ const SESSION_EXPIRATION_MS = 3 * 24 * 60 * 60 * 1000;
 const SESSION_FILE_DIR = path.join(homedir(), '.config', 'ghosttown');
 const SESSION_FILE_PATH = path.join(SESSION_FILE_DIR, 'sessions.json');
 
+// Server config file for port discovery (allows CLI to find running server)
+const SERVER_CONFIG_PATH = path.join(SESSION_FILE_DIR, 'server.json');
+
+/**
+ * Write server config to disk for port discovery
+ */
+function writeServerConfig(port) {
+  try {
+    if (!fs.existsSync(SESSION_FILE_DIR)) {
+      fs.mkdirSync(SESSION_FILE_DIR, { recursive: true });
+    }
+    fs.writeFileSync(
+      SERVER_CONFIG_PATH,
+      JSON.stringify({ port, pid: process.pid, startedAt: Date.now() }, null, 2)
+    );
+  } catch (err) {
+    console.error('Warning: Failed to write server config:', err.message);
+  }
+}
+
+/**
+ * Remove server config file on shutdown
+ */
+function removeServerConfig() {
+  try {
+    if (fs.existsSync(SERVER_CONFIG_PATH)) {
+      fs.unlinkSync(SERVER_CONFIG_PATH);
+    }
+  } catch (err) {
+    // Ignore errors during cleanup
+  }
+}
+
+// Preferred ports to try in order before falling back to auto-discovery (port 0)
+// 64057 - strongest visual mapping to "GHOST"
+// 6057  - subtle and clean
+// 4040  - "ghost server not found" energy (404)
+// 1313  - haunted house number energy
+const PREFERRED_PORTS = [64057, 6057, 4040, 1313];
+
+/**
+ * Find an available port from the preferred list, or return 0 for auto-discovery
+ */
+function findPreferredPort() {
+  for (const port of PREFERRED_PORTS) {
+    try {
+      // Quick check if port is in use using lsof
+      execSync(`lsof -i:${port}`, { stdio: 'pipe' });
+      // If lsof succeeds, port is in use, try next
+    } catch (e) {
+      // lsof returns non-zero if port is free - use this port
+      return port;
+    }
+  }
+  // All preferred ports in use, fall back to auto-discovery
+  return 0;
+}
+
 // In-memory session store: Map<token, { username, createdAt, lastActivity }>
 const authSessions = new Map();
 
@@ -422,40 +498,43 @@ function isInsideGhosttownSession() {
   return sessionName && sessionName.startsWith('gt-');
 }
 
+// Note: validateSessionName and displayNameExists are imported from session-utils.js
+// CLI uses getTmuxSessionsForValidation() to adapt tmux sessions to the expected format
+// Web server uses SessionManager directly
+
 /**
- * Validate a session name
- * Returns { valid: true } or { valid: false, error: string }
+ * Parse a ghosttown tmux session name into its components.
+ * Format: gt-<stable-id>-<display-name>
+ * DEPRECATED: Only used by legacy CLI commands that still use tmux
+ *
+ * @param {string} fullName - The full tmux session name
+ * @returns {{ stableId: string|null, displayName: string, fullName: string }|null}
  */
-function validateSessionName(name) {
-  if (!name || name.length === 0) {
-    return { valid: false, error: 'Session name cannot be empty' };
-  }
-  if (name.length > 50) {
-    return { valid: false, error: 'Session name too long (max 50 chars)' };
-  }
-  if (/^[0-9]+$/.test(name)) {
-    return {
-      valid: false,
-      error: 'Session name cannot be purely numeric (conflicts with auto-generated IDs)',
-    };
-  }
-  // Reserved name for background server
-  if (name === 'ghosttown-host') {
-    return { valid: false, error: "'ghosttown-host' is a reserved name" };
+function parseSessionName(fullName) {
+  if (!fullName || !fullName.startsWith('gt-')) {
+    return null;
   }
-  // tmux session names cannot contain: colon, period
-  // We also disallow spaces and special chars for URL safety
-  if (!/^[a-zA-Z0-9_-]+$/.test(name)) {
+  // Format: gt-<stable-id>-<display-name>
+  const match = fullName.match(/^gt-(\d+)-(.+)$/);
+  if (match) {
     return {
-      valid: false,
-      error: 'Session name can only contain letters, numbers, hyphens, and underscores',
+      stableId: match[1],
+      displayName: match[2],
+      fullName: fullName,
     };
   }
-  return { valid: true };
+  // Legacy format: gt-<name> (no stable ID)
+  const legacyName = fullName.slice(3);
+  return {
+    stableId: null,
+    displayName: legacyName,
+    fullName: fullName,
+  };
 }
 
 /**
  * Check if a tmux session with the given name exists
+ * DEPRECATED: Only used by legacy CLI commands that still use tmux
  */
 function sessionExists(sessionName) {
   try {
@@ -473,10 +552,11 @@ function sessionExists(sessionName) {
 }
 
 /**
- * Check if a display name is already used by a ghosttown session
- * Display name is the user-facing part after gt-<id>-
+ * Get tmux sessions in a format compatible with displayNameExists().
+ * Returns array of objects with displayName property.
+ * DEPRECATED: Only used by legacy CLI commands that still use tmux
  */
-function displayNameExists(displayName) {
+function getTmuxSessionsForValidation() {
   try {
     const output = execSync('tmux list-sessions -F "#{session_name}"', {
       encoding: 'utf8',
@@ -484,61 +564,54 @@ function displayNameExists(displayName) {
     });
     return output
       .split('\n')
-      .filter((s) => s.trim())
-      .some((name) => {
+      .filter((name) => name.startsWith('gt-'))
+      .map((name) => {
         const parsed = parseSessionName(name);
-        return parsed && parsed.displayName === displayName;
+        return { displayName: parsed ? parsed.displayName : name.replace('gt-', '') };
       });
   } catch (err) {
-    return false;
+    return [];
   }
 }
 
 /**
- * Parse a ghosttown session name into its components
- * Format: gt-<stable-id>-<display-name>
- * Returns { stableId, displayName, fullName } or null if not a valid gt session
- */
-function parseSessionName(fullName) {
-  if (!fullName || !fullName.startsWith('gt-')) {
-    return null;
-  }
-  // Format: gt-<stable-id>-<display-name>
-  const match = fullName.match(/^gt-(\d+)-(.+)$/);
-  if (match) {
-    return {
-      stableId: match[1],
-      displayName: match[2],
-      fullName: fullName,
-    };
-  }
-  // Legacy format: gt-<name> (no stable ID)
-  // Treat the whole thing after gt- as the display name, no stable ID
-  const legacyName = fullName.slice(3);
-  return {
-    stableId: null,
-    displayName: legacyName,
-    fullName: fullName,
-  };
-}
-
-/**
- * Find a ghosttown session by its stable ID
- * Returns the full session name or null if not found
+ * Find a tmux session by display name or stableId.
+ * Used by CLI commands (attach, rename, kill) that interact with tmux sessions.
+ *
+ * @param {string} identifier - Display name or stableId to search for
+ * @returns {{ displayName: string, stableId: string|null, fullName: string }|null}
  */
-function findSessionByStableId(stableId) {
+function findSessionByDisplayName(identifier) {
   try {
     const output = execSync('tmux list-sessions -F "#{session_name}"', {
       encoding: 'utf8',
       stdio: ['pipe', 'pipe', 'pipe'],
     });
-    const sessions = output.split('\n').filter((s) => s.trim() && s.startsWith('gt-'));
-    for (const name of sessions) {
-      const parsed = parseSessionName(name);
-      if (parsed && parsed.stableId === stableId) {
-        return name;
-      }
+
+    const sessions = output
+      .split('\n')
+      .filter((name) => name.startsWith('gt-') && name !== SERVER_SESSION_NAME)
+      .map((fullName) => {
+        const parsed = parseSessionName(fullName);
+        return {
+          displayName: parsed ? parsed.displayName : fullName.replace('gt-', ''),
+          stableId: parsed ? parsed.stableId : null,
+          fullName,
+        };
+      });
+
+    // Try exact display name match first
+    const byName = sessions.find((s) => s.displayName === identifier);
+    if (byName) {
+      return byName;
+    }
+
+    // Try stableId match (for backwards compatibility)
+    const byId = sessions.find((s) => s.stableId === identifier);
+    if (byId) {
+      return byId;
     }
+
     return null;
   } catch (err) {
     return null;
@@ -621,22 +694,41 @@ function getServerStatus() {
     const isRunning = output.split('\n').includes(SERVER_SESSION_NAME);
 
     if (!isRunning) {
+      // Also clean up stale server.json if tmux session doesn't exist
+      removeServerConfig();
       return { running: false, port: null, useHttp: false };
     }
 
-    // Get the port from tmux environment
-    let port = 8080;
+    // Get the port - prefer server.json (for auto port discovery), fall back to tmux env
+    let port = null;
     try {
-      const envOutput = execSync(`tmux show-environment -t ${SERVER_SESSION_NAME} GHOSTTOWN_PORT`, {
-        encoding: 'utf8',
-        stdio: ['pipe', 'pipe', 'pipe'],
-      });
-      const parsedPort = Number.parseInt(envOutput.split('=')[1], 10);
-      if (!Number.isNaN(parsedPort)) {
-        port = parsedPort;
+      if (fs.existsSync(SERVER_CONFIG_PATH)) {
+        const config = JSON.parse(fs.readFileSync(SERVER_CONFIG_PATH, 'utf8'));
+        if (config.port) {
+          port = config.port;
+        }
       }
     } catch (e) {
-      // Use default port
+      // Failed to read server.json, try tmux env
+    }
+
+    // Fall back to tmux environment if server.json doesn't have the port
+    if (port === null) {
+      try {
+        const envOutput = execSync(
+          `tmux show-environment -t ${SERVER_SESSION_NAME} GHOSTTOWN_PORT`,
+          {
+            encoding: 'utf8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+          }
+        );
+        const parsedPort = Number.parseInt(envOutput.split('=')[1], 10);
+        if (!Number.isNaN(parsedPort) && parsedPort > 0) {
+          port = parsedPort;
+        }
+      } catch (e) {
+        // No port info available
+      }
     }
 
     // Get the protocol from tmux environment (default to HTTPS if not set)
@@ -766,7 +858,7 @@ function createTmuxSession(command, customName = null) {
       process.exit(1);
     }
     // Check if display name already exists
-    if (displayNameExists(customName)) {
+    if (displayNameExists(getTmuxSessionsForValidation(), customName)) {
       console.log('');
       console.log(`   ${RED}Error:${RESET} Session '${customName}' already exists.`);
       console.log('');
@@ -937,32 +1029,13 @@ function attachToSession(sessionName) {
   const RED = '\x1b[31m';
   const BEIGE = '\x1b[38;2;255;220;150m';
 
-  // Add gt- prefix if not present
-  if (!sessionName.startsWith('gt-')) {
-    sessionName = `gt-${sessionName}`;
-  }
-
-  // Check if session exists
-  try {
-    const output = execSync('tmux list-sessions -F "#{session_name}"', {
-      encoding: 'utf8',
-      stdio: ['pipe', 'pipe', 'pipe'],
-    });
-
-    const sessions = output.split('\n').filter((s) => s.trim());
-    if (!sessions.includes(sessionName)) {
-      console.log('');
-      console.log(`   ${RED}Error:${RESET} Session '${sessionName}' not found.`);
-      console.log('');
-      console.log(`   ${BEIGE}No ghosttown sessions are currently running.${RESET}`);
-      console.log('');
-      process.exit(1);
-    }
-  } catch (err) {
+  // Look up session by display name
+  const found = findSessionByDisplayName(sessionName);
+  if (!found) {
     console.log('');
-    console.log(`   ${RED}Error:${RESET} No tmux sessions found.`);
+    console.log(`   ${RED}Error:${RESET} Session '${sessionName}' not found.`);
     console.log('');
-    console.log(`   ${BEIGE}No ghosttown sessions are currently running.${RESET}`);
+    listSessionsInline();
     console.log('');
     process.exit(1);
   }
@@ -971,7 +1044,7 @@ function attachToSession(sessionName) {
   // Use the same pattern as detachFromTmux which works
   const result = spawnSync(
     process.env.SHELL || '/bin/sh',
-    ['-c', `tmux attach-session -t ${sessionName}`],
+    ['-c', `tmux attach-session -t ${found.fullName}`],
     {
       stdio: 'inherit',
     }
@@ -1087,57 +1160,57 @@ function killSession(sessionName) {
     }
 
     sessionName = getCurrentTmuxSessionName();
-  }
-
-  // Add gt- prefix if not present
-  if (!sessionName.startsWith('gt-')) {
-    sessionName = `gt-${sessionName}`;
-  }
+    // sessionName is now the full tmux name (e.g., gt-12-13)
+    const parsed = parseSessionName(sessionName);
 
-  // Check if session exists
-  try {
-    const output = execSync('tmux list-sessions -F "#{session_name}"', {
-      encoding: 'utf8',
-      stdio: ['pipe', 'pipe', 'pipe'],
-    });
+    // Kill the session
+    try {
+      execSync(`tmux kill-session -t ${sessionName}`, {
+        stdio: 'pipe',
+      });
 
-    const sessions = output.split('\n').filter((s) => s.trim());
-    if (!sessions.includes(sessionName)) {
+      const displayName = parsed ? parsed.displayName : sessionName.replace('gt-', '');
       console.log('');
-      console.log(`   ${RED}Error:${RESET} Session '${sessionName}' not found.`);
+      console.log(`   ${BOLD_YELLOW}Session ${displayName} has been killed.${RESET}`);
       console.log('');
-      console.log(`   ${BEIGE}No ghosttown sessions are currently running.${RESET}`);
+      console.log(`   ${CYAN}To list remaining:${RESET}  ${BEIGE}gt list${RESET}`);
+      console.log('');
+      process.exit(0);
+    } catch (err) {
+      const displayName = parsed ? parsed.displayName : sessionName.replace('gt-', '');
+      console.log('');
+      console.log(`   ${RED}Error:${RESET} Failed to kill session '${displayName}'.`);
       console.log('');
       process.exit(1);
     }
-  } catch (err) {
+  }
+
+  // User provided a session name - look it up by display name
+  const found = findSessionByDisplayName(sessionName);
+  if (!found) {
     console.log('');
-    console.log(`   ${RED}Error:${RESET} No tmux sessions found.`);
+    console.log(`   ${RED}Error:${RESET} Session '${sessionName}' not found.`);
     console.log('');
-    console.log(`   ${BEIGE}No ghosttown sessions are currently running.${RESET}`);
+    listSessionsInline();
     console.log('');
     process.exit(1);
   }
 
   // Kill the session
   try {
-    execSync(`tmux kill-session -t ${sessionName}`, {
+    execSync(`tmux kill-session -t ${found.fullName}`, {
       stdio: 'pipe',
     });
 
-    // Extract display name from session name
-    const parsed = parseSessionName(sessionName);
-    const displayName = parsed ? parsed.displayName : sessionName.replace('gt-', '');
-
     console.log('');
-    console.log(`   ${BOLD_YELLOW}Session ${displayName} has been killed.${RESET}`);
+    console.log(`   ${BOLD_YELLOW}Session ${found.displayName} has been killed.${RESET}`);
     console.log('');
     console.log(`   ${CYAN}To list remaining:${RESET}  ${BEIGE}gt list${RESET}`);
     console.log('');
     process.exit(0);
   } catch (err) {
     console.log('');
-    console.log(`   ${RED}Error:${RESET} Failed to kill session '${sessionName}'.`);
+    console.log(`   ${RED}Error:${RESET} Failed to kill session '${found.displayName}'.`);
     console.log('');
     process.exit(1);
   }
@@ -1205,7 +1278,7 @@ function killAllSessions() {
  * @param {number} port - Port to listen on
  * @param {boolean} useHttp - Use HTTP instead of HTTPS (default: false, meaning HTTPS is used)
  */
-function startServerInBackground(port = 8080, useHttp = false) {
+async function startServerInBackground(port = 0, useHttp = false) {
   // Check if tmux is installed
   if (!checkTmuxInstalled()) {
     printTmuxInstallHelp();
@@ -1223,7 +1296,7 @@ function startServerInBackground(port = 8080, useHttp = false) {
     console.log('');
     console.log(`   ${RED}Error:${RESET} A server is already running (port ${status.port}).`);
     console.log('');
-    if (status.port !== port) {
+    if (port !== 0 && status.port !== port) {
       console.log(`   To switch to port ${port}:`);
       console.log(`     ${BEIGE}gt stop && gt start -p ${port}${RESET}`);
     } else {
@@ -1234,18 +1307,20 @@ function startServerInBackground(port = 8080, useHttp = false) {
     process.exit(1);
   }
 
-  // Check if port is already in use by another process
-  try {
-    execSync(`lsof -i:${port}`, { stdio: 'pipe' });
-    // If lsof succeeds, port is in use
-    console.log('');
-    console.log(`   ${RED}Error:${RESET} Port ${port} is already in use.`);
-    console.log('');
-    console.log(`   Try a different port: ${BEIGE}gt start -p <port>${RESET}`);
-    console.log('');
-    process.exit(1);
-  } catch (e) {
-    // lsof returns non-zero if port is free - this is what we want
+  // Check if specific port is already in use by another process (skip for port 0 auto-discovery)
+  if (port !== 0) {
+    try {
+      execSync(`lsof -i:${port}`, { stdio: 'pipe' });
+      // If lsof succeeds, port is in use
+      console.log('');
+      console.log(`   ${RED}Error:${RESET} Port ${port} is already in use.`);
+      console.log('');
+      console.log(`   Try a different port: ${BEIGE}gt start -p <port>${RESET}`);
+      console.log('');
+      process.exit(1);
+    } catch (e) {
+      // lsof returns non-zero if port is free - this is what we want
+    }
   }
 
   try {
@@ -1284,6 +1359,27 @@ function startServerInBackground(port = 8080, useHttp = false) {
       { stdio: 'pipe' }
     );
 
+    // Wait for server to start and get actual port from server.json
+    // The server writes to server.json once it starts listening
+    let actualPort = port;
+    let attempts = 0;
+    const maxAttempts = 30; // 3 seconds max wait
+    while (attempts < maxAttempts) {
+      try {
+        if (fs.existsSync(SERVER_CONFIG_PATH)) {
+          const config = JSON.parse(fs.readFileSync(SERVER_CONFIG_PATH, 'utf8'));
+          if (config.port) {
+            actualPort = config.port;
+            break;
+          }
+        }
+      } catch (e) {
+        // Ignore read errors, keep waiting
+      }
+      await new Promise((resolve) => setTimeout(resolve, 100));
+      attempts++;
+    }
+
     // Get local IPs for display
     const localIPs = getLocalIPs();
     const protocol = useHttp ? 'http' : 'https';
@@ -1291,9 +1387,11 @@ function startServerInBackground(port = 8080, useHttp = false) {
     console.log('');
     console.log(`   ${BOLD_YELLOW}Ghosttown server started!${RESET}`);
     console.log('');
-    console.log(`     ${CYAN}Open:${RESET} ${BEIGE}${protocol}://localhost:${port}${RESET}`);
+    console.log(`     ${CYAN}Open:${RESET} ${BEIGE}${protocol}://localhost:${actualPort}${RESET}`);
     if (localIPs.length > 0) {
-      console.log(`  ${CYAN}Network:${RESET} ${BEIGE}${protocol}://${localIPs[0]}:${port}${RESET}`);
+      console.log(
+        `  ${CYAN}Network:${RESET} ${BEIGE}${protocol}://${localIPs[0]}:${actualPort}${RESET}`
+      );
     }
     console.log('');
     console.log(`   ${CYAN}To stop:${RESET}  ${BEIGE}gt stop${RESET}`);
@@ -1314,38 +1412,53 @@ function startServerInBackground(port = 8080, useHttp = false) {
  * Stop the background server
  */
 function stopServer() {
-  // Check if tmux is installed
-  if (!checkTmuxInstalled()) {
-    printTmuxInstallHelp();
-  }
-
   const RESET = '\x1b[0m';
   const RED = '\x1b[31m';
   const BOLD_YELLOW = '\x1b[1;93m';
   const BEIGE = '\x1b[38;2;255;220;150m';
 
-  const status = getServerStatus();
+  let stopped = false;
 
-  if (!status.running) {
-    console.log('');
-    console.log(`   ${BEIGE}No server is currently running.${RESET}`);
-    console.log('');
-    console.log('   To start: gt start');
-    console.log('');
-    process.exit(0);
+  // First, try to stop using PID from server.json (works for foreground servers)
+  try {
+    if (fs.existsSync(SERVER_CONFIG_PATH)) {
+      const config = JSON.parse(fs.readFileSync(SERVER_CONFIG_PATH, 'utf8'));
+      if (config.pid) {
+        try {
+          process.kill(config.pid, 'SIGTERM');
+          stopped = true;
+        } catch (e) {
+          // Process doesn't exist or can't be killed
+        }
+      }
+    }
+  } catch (e) {
+    // Ignore errors reading config
   }
 
-  try {
-    execSync(`tmux kill-session -t ${SERVER_SESSION_NAME}`, { stdio: 'pipe' });
+  // Also try to kill tmux session (for background servers started with `gt start`)
+  if (checkTmuxInstalled()) {
+    try {
+      execSync(`tmux kill-session -t ${SERVER_SESSION_NAME}`, { stdio: 'pipe' });
+      stopped = true;
+    } catch (err) {
+      // tmux session doesn't exist or can't be killed
+    }
+  }
 
+  // Clean up server.json
+  removeServerConfig();
+
+  if (stopped) {
     console.log('');
     console.log(`   ${BOLD_YELLOW}Server stopped.${RESET}`);
     console.log('');
-  } catch (err) {
+  } else {
     console.log('');
-    console.log(`   ${RED}Error:${RESET} Failed to stop server.`);
+    console.log(`   ${BEIGE}No server is currently running.${RESET}`);
+    console.log('');
+    console.log('   To start: gt start');
     console.log('');
-    process.exit(1);
   }
 
   process.exit(0);
@@ -1442,29 +1555,6 @@ function listSessionsInline() {
   }
 }
 
-/**
- * Find a ghosttown session by display name
- * Returns the parsed session info or null if not found
- */
-function findSessionByDisplayName(displayName) {
-  try {
-    const output = execSync('tmux list-sessions -F "#{session_name}"', {
-      encoding: 'utf8',
-      stdio: ['pipe', 'pipe', 'pipe'],
-    });
-    const sessions = output.split('\n').filter((s) => s.trim() && s.startsWith('gt-'));
-    for (const fullName of sessions) {
-      const parsed = parseSessionName(fullName);
-      if (parsed && parsed.displayName === displayName) {
-        return parsed;
-      }
-    }
-    return null;
-  } catch (err) {
-    return null;
-  }
-}
-
 /**
  * Rename a ghosttown session
  * Usage:
@@ -1540,7 +1630,7 @@ function renameSession(renameArgs) {
   }
 
   // Check new display name doesn't conflict
-  if (displayNameExists(newDisplayName)) {
+  if (displayNameExists(getTmuxSessionsForValidation(), newDisplayName)) {
     console.log('');
     console.log(`   ${RED}Error:${RESET} Session '${newDisplayName}' already exists.`);
     console.log('');
@@ -1571,7 +1661,7 @@ function renameSession(renameArgs) {
 // Parse CLI arguments
 // ============================================================================
 
-function parseArgs(argv) {
+async function parseArgs(argv) {
   const args = argv.slice(2);
   let port = null;
   let command = null;
@@ -1589,7 +1679,7 @@ function parseArgs(argv) {
 Usage: ghosttown [options] [command]
 
 Options:
-  -p, --port <port>    Port to listen on (default: 8080, or PORT env var)
+  -p, --port <port>    Port to listen on (default: auto-discover available port)
   -n, --name <name>    Give the session a custom name (use with a command)
   --http               Use HTTP instead of HTTPS (default is HTTPS)
   --no-auth            Disable authentication (binds to localhost only)
@@ -1599,7 +1689,7 @@ Options:
   -h, --help           Show this help message
 
 Commands:
-  start [-p <port>]  Start the server in the background (default port: 8080)
+  start [-p <port>]  Start the server in the background (auto-discovers available port)
   stop               Stop the background server
   status             Show server status and URLs
   list               List all ghosttown tmux sessions
@@ -1672,8 +1762,7 @@ Aliases:
       if (!sessionArg) {
         console.error('Error: attach requires a session name or ID');
         console.error('Usage: gt attach <name|id>');
-        handled = true;
-        break;
+        process.exit(1);
       }
       handled = true;
       attachToSession(sessionArg);
@@ -1708,7 +1797,7 @@ Aliases:
     // Handle start command
     else if (arg === 'start') {
       // Parse remaining args after 'start' for -p and --http flags
-      let startPort = 8080;
+      let startPort = findPreferredPort(); // Try preferred ports, fall back to auto-discovery
       let startUseHttp = false;
       const remainingArgs = args.slice(i + 1);
       for (let j = 0; j < remainingArgs.length; j++) {
@@ -1728,7 +1817,7 @@ Aliases:
         }
       }
       handled = true;
-      startServerInBackground(startPort, startUseHttp);
+      await startServerInBackground(startPort, startUseHttp);
       // startServerInBackground exits, so this won't be reached
     }
 
@@ -1800,7 +1889,41 @@ Aliases:
 // ============================================================================
 
 function startWebServer(cliArgs) {
-  const HTTP_PORT = cliArgs.port || process.env.PORT || 8080;
+  // ANSI color codes for formatted output
+  const RESET = '\x1b[0m';
+  const RED = '\x1b[31m';
+  const CYAN = '\x1b[36m';
+  const BEIGE = '\x1b[38;2;255;220;150m';
+
+  // Check if a server is already running (prevents multiple instances)
+  try {
+    if (fs.existsSync(SERVER_CONFIG_PATH)) {
+      const config = JSON.parse(fs.readFileSync(SERVER_CONFIG_PATH, 'utf8'));
+      // Check if the PID is still alive
+      if (config.pid) {
+        try {
+          process.kill(config.pid, 0); // Signal 0 = just check if process exists
+          // Process exists - server already running
+          console.log('');
+          console.log(`   ${RED}Error:${RESET} A gt server is already running.`);
+          console.log('');
+          console.log(`   ${CYAN}To stop:${RESET}  ${BEIGE}gt stop${RESET}`);
+          console.log(`   ${CYAN}To check:${RESET} ${BEIGE}gt status${RESET}`);
+          console.log('');
+          process.exit(1);
+        } catch (e) {
+          // Process doesn't exist - stale config, clean it up
+          removeServerConfig();
+        }
+      }
+    }
+  } catch (e) {
+    // Ignore errors reading config
+  }
+
+  // Try preferred ports (64057, 6057, 4040) in order, fall back to auto-discovery (port 0)
+  // if all are in use. User can still override with -p flag or PORT env var.
+  const HTTP_PORT = cliArgs.port || process.env.PORT || findPreferredPort();
   const USE_HTTPS = !cliArgs.useHttp;
   const NO_AUTH = cliArgs.noAuth || false;
   const backgroundMode = cliArgs.serverBackgroundMode || false;
@@ -1978,7 +2101,15 @@ function startWebServer(cliArgs) {
         color: #e5e5e5;
         font-size: 22px;
         font-weight: 600;
-        margin-bottom: 12px;
+        margin-bottom: 4px;
+        text-align: center;
+      }
+
+      .session-card .subtitle {
+        color: #888;
+        font-size: 13px;
+        font-weight: 400;
+        margin-bottom: 16px;
         text-align: center;
       }
 
@@ -2382,6 +2513,7 @@ function startWebServer(cliArgs) {
     <div class="session-list-view" id="session-list-view">
       <div class="session-card">
         <h1>Ghost Town</h1>
+        <p class="subtitle">Choose a terminal to connect to</p>
         <div class="error-message" id="error-message"></div>
         <div class="session-table-header" id="session-table-header" style="display: none;">
           <span class="header-name">Name</span>
@@ -2454,13 +2586,15 @@ function startWebServer(cliArgs) {
       }
 
       // Get session info from URL query parameters
-      // Returns { name, stableId } or null
+      // Returns { sessionId, name, stableId } or null
+      // Supports both new (?sessionId=uuid) and legacy (?session=name&id=stableId) formats
       function getSessionFromUrl() {
         const params = new URLSearchParams(window.location.search);
+        const sessionId = params.get('sessionId');
         const name = params.get('session');
         const stableId = params.get('id');
-        if (name || stableId) {
-          return { name, stableId };
+        if (sessionId || name || stableId) {
+          return { sessionId, name, stableId };
         }
         return null;
       }
@@ -2469,9 +2603,13 @@ function startWebServer(cliArgs) {
       async function initApp() {
         const sessionInfo = getSessionFromUrl();
 
-        if (sessionInfo && sessionInfo.stableId) {
-          // Show terminal view using stable ID
-          requestedSessionName = sessionInfo.name; // Store for error messages
+        if (sessionInfo && sessionInfo.sessionId) {
+          // New format: use UUID sessionId
+          requestedSessionName = sessionInfo.name || sessionInfo.sessionId;
+          showTerminalView(sessionInfo.sessionId);
+        } else if (sessionInfo && sessionInfo.stableId) {
+          // Legacy format: use stable ID
+          requestedSessionName = sessionInfo.name;
           showTerminalView(sessionInfo.stableId);
         } else if (sessionInfo && sessionInfo.name) {
           // Legacy URL with just name - show terminal view
@@ -3356,15 +3494,22 @@ function startWebServer(cliArgs) {
         res.end();
         return;
       }
-      try {
-        const { displayNumber, stableId } = createWebSession();
-        res.writeHead(302, { Location: `/?session=${displayNumber}&id=${stableId}` });
-        res.end();
-      } catch (err) {
-        console.error('Failed to create session:', err);
-        res.writeHead(500, { 'Content-Type': 'text/plain' });
-        res.end('Failed to create session');
-      }
+      (async () => {
+        try {
+          const manager = await getSessionManager();
+          // Create session without starting PTY - it will start on first WebSocket connect
+          const newSession = await manager.createSession({ startProcess: false });
+          // Use sessionId for new format, keep session param for backward compat
+          res.writeHead(302, {
+            Location: `/?sessionId=${newSession.id}&session=${encodeURIComponent(newSession.displayName)}`,
+          });
+          res.end();
+        } catch (err) {
+          console.error('Failed to create session:', err);
+          res.writeHead(500, { 'Content-Type': 'text/plain' });
+          res.end('Failed to create session');
+        }
+      })();
       return;
     }
 
@@ -3403,7 +3548,7 @@ function startWebServer(cliArgs) {
       return;
     }
 
-    // API: List sessions (from tmux) - requires authentication
+    // API: List sessions - requires authentication
     if (pathname === '/api/sessions' && req.method === 'GET') {
       if (!session) {
         res.writeHead(401, { 'Content-Type': 'application/json' });
@@ -3411,40 +3556,31 @@ function startWebServer(cliArgs) {
         return;
       }
       try {
-        const output = execSync(
-          'tmux list-sessions -F "#{session_name}|#{session_activity}|#{session_attached}|#{session_windows}"',
-          { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }
-        );
-
-        const sessionList = output
-          .split('\n')
-          .filter((line) => line.startsWith('gt-'))
-          .map((line) => {
-            const [fullName, activity, attached, windows] = line.split('|');
-            const parsed = parseSessionName(fullName);
-            return {
-              name: parsed ? parsed.displayName : fullName.replace('gt-', ''),
-              stableId: parsed ? parsed.stableId : null,
-              fullName: fullName,
-              lastActivity: Number.parseInt(activity, 10) * 1000,
-              attached: attached === '1',
-              windows: Number.parseInt(windows, 10),
-            };
-          });
+        const manager = await getSessionManager();
+        const sessionList = await manager.listSessions();
+
+        // Map to API response format with backward-compatible fields
+        const response = sessionList.map((s) => ({
+          name: s.displayName,
+          stableId: s.id.slice(0, 8), // Short ID for backward compat
+          id: s.id, // Full UUID (new)
+          lastActivity: s.lastActivity,
+          attached: s.connectionCount > 0, // Backward compat: attached means has connections
+          isRunning: s.isRunning,
+          connectionCount: s.connectionCount,
+        }));
 
-        // Sort by recent activity
-        sessionList.sort((a, b) => b.lastActivity - a.lastActivity);
         res.writeHead(200, { 'Content-Type': 'application/json' });
-        res.end(JSON.stringify({ sessions: sessionList }));
+        res.end(JSON.stringify({ sessions: response }));
       } catch (err) {
-        // No tmux sessions or tmux not running
+        console.error('Error listing sessions:', err);
         res.writeHead(200, { 'Content-Type': 'application/json' });
         res.end(JSON.stringify({ sessions: [] }));
       }
       return;
     }
 
-    // API: Create session (tmux session) - requires authentication
+    // API: Create session - requires authentication
     if (pathname === '/api/sessions/create' && req.method === 'POST') {
       if (!session) {
         res.writeHead(401, { 'Content-Type': 'application/json' });
@@ -3452,10 +3588,18 @@ function startWebServer(cliArgs) {
         return;
       }
       try {
-        const { displayNumber, stableId } = createWebSession();
+        const manager = await getSessionManager();
+        const newSession = await manager.createSession();
         res.writeHead(200, { 'Content-Type': 'application/json' });
-        res.end(JSON.stringify({ name: String(displayNumber), stableId: stableId }));
+        res.end(
+          JSON.stringify({
+            name: newSession.displayName,
+            stableId: newSession.id.slice(0, 8), // Short ID for backward compat
+            id: newSession.id, // Full UUID (new)
+          })
+        );
       } catch (err) {
+        console.error('Error creating session:', err);
         res.writeHead(500, { 'Content-Type': 'application/json' });
         res.end(JSON.stringify({ error: 'Failed to create session' }));
       }
@@ -3472,85 +3616,123 @@ function startWebServer(cliArgs) {
 
       const cols = Number.parseInt(url.searchParams.get('cols') || '80');
       const rows = Number.parseInt(url.searchParams.get('rows') || '24');
-      const requestedSession = url.searchParams.get('session');
-      const requestedName = url.searchParams.get('name'); // Original name from URL (if different from session)
+      // Support both new (sessionId) and legacy (session) parameters
+      const sessionIdParam = url.searchParams.get('sessionId');
+      const legacySession = url.searchParams.get('session');
+      const requestedName = url.searchParams.get('name');
+      const identifier = sessionIdParam || legacySession;
 
-      if (!requestedSession) {
+      if (!identifier) {
         res.writeHead(400, { 'Content-Type': 'application/json' });
         res.end(JSON.stringify({ error: 'Session parameter required' }));
         return;
       }
 
-      // Look up session by stable ID first, then by display name
-      let sessionInfo = findSessionByStableIdWeb(requestedSession);
-      if (!sessionInfo) {
-        sessionInfo = findSessionByDisplayName(requestedSession);
-      }
-      if (!sessionInfo) {
-        // Build error message with both name and id if available
-        let errorMsg;
-        if (requestedName && requestedName !== requestedSession) {
-          errorMsg = `No session found named ${requestedName}, or with id ${requestedSession}`;
-        } else {
-          errorMsg = `No session found named ${requestedSession} or with id ${requestedSession}`;
+      try {
+        const manager = await getSessionManager();
+
+        // Look up session by UUID, short ID, or display name
+        const sessionObj = await findSessionForWeb(identifier);
+        if (!sessionObj) {
+          let errorMsg;
+          if (requestedName && requestedName !== identifier) {
+            errorMsg = `No session found named ${requestedName}, or with id ${identifier}`;
+          } else {
+            errorMsg = `No session found named ${identifier} or with id ${identifier}`;
+          }
+          res.writeHead(404, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ error: errorMsg }));
+          return;
         }
-        res.writeHead(404, { 'Content-Type': 'application/json' });
-        res.end(JSON.stringify({ error: errorMsg }));
-        return;
-      }
 
-      // Generate unique connection ID
-      const connectionId = `sse-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+        // Generate unique connection ID
+        const connectionId = `sse-${Date.now()}-${Math.random().toString(36).slice(2)}`;
 
-      // Set up SSE headers
-      res.writeHead(200, {
-        'Content-Type': 'text/event-stream',
-        'Cache-Control': 'no-cache',
-        Connection: 'keep-alive',
-        'X-SSE-Connection-Id': connectionId,
-      });
+        // Set up SSE headers first
+        res.writeHead(200, {
+          'Content-Type': 'text/event-stream',
+          'Cache-Control': 'no-cache',
+          Connection: 'keep-alive',
+          'X-SSE-Connection-Id': connectionId,
+        });
 
-      // Send session info as first event
-      res.write(
-        `data: ${JSON.stringify({ type: 'session_info', name: sessionInfo.displayName, stableId: sessionInfo.stableId, connectionId })}\n\n`
-      );
+        // Send session info as first event
+        res.write(
+          `data: ${JSON.stringify({ type: 'session_info', name: sessionObj.displayName, stableId: sessionObj.id.slice(0, 8), id: sessionObj.id, connectionId })}\n\n`
+        );
 
-      // Create PTY attached to tmux session
-      const ptyProcess = createTmuxAttachPty(sessionInfo.fullName, cols, rows);
+        // Timeout for closing connection after session exit (30 seconds)
+        const SSE_EXIT_TIMEOUT_MS = 30000;
+        let exitTimeout = null;
+
+        // Set up event handlers BEFORE connecting (to catch early output like shell prompt)
+        const outputHandler = (sid, data) => {
+          if (sid === sessionObj.id && !res.writableEnded) {
+            // Clear exit timeout if session produces output (it restarted)
+            if (exitTimeout) {
+              clearTimeout(exitTimeout);
+              exitTimeout = null;
+            }
+            const encoded = Buffer.from(data).toString('base64');
+            res.write(`data: ${JSON.stringify({ type: 'output', data: encoded })}\n\n`);
+          }
+        };
 
-      // Store connection
-      sseConnections.set(connectionId, {
-        res,
-        pty: ptyProcess,
-        stableId: requestedSession,
-        sessionInfo,
-      });
+        const exitHandler = (sid) => {
+          if (sid === sessionObj.id && !res.writableEnded) {
+            res.write(`data: ${JSON.stringify({ type: 'exit' })}\n\n`);
+            // Set timeout to close connection if session doesn't restart
+            exitTimeout = setTimeout(() => {
+              if (!res.writableEnded) {
+                res.write(
+                  `data: ${JSON.stringify({ type: 'timeout', message: 'Session exited and did not restart' })}\n\n`
+                );
+                res.end();
+                const conn = sseConnections.get(connectionId);
+                if (conn) {
+                  manager.off('session:output', conn.outputHandler);
+                  manager.off('session:exit', conn.exitHandler);
+                  sseConnections.delete(connectionId);
+                }
+              }
+            }, SSE_EXIT_TIMEOUT_MS);
+          }
+        };
 
-      // Stream terminal output as SSE events
-      ptyProcess.onData((data) => {
-        if (!res.writableEnded) {
-          // Base64 encode to handle binary data safely
-          const encoded = Buffer.from(data).toString('base64');
-          res.write(`data: ${JSON.stringify({ type: 'output', data: encoded })}\n\n`);
-        }
-      });
+        manager.on('session:output', outputHandler);
+        manager.on('session:exit', exitHandler);
 
-      ptyProcess.onExit(() => {
-        if (!res.writableEnded) {
-          res.write(`data: ${JSON.stringify({ type: 'exit' })}\n\n`);
-          res.end();
-        }
-        sseConnections.delete(connectionId);
-      });
+        // Store connection
+        sseConnections.set(connectionId, {
+          res,
+          sessionId: sessionObj.id,
+          outputHandler,
+          exitHandler,
+          exitTimeout: () => exitTimeout, // Getter for cleanup
+        });
 
-      // Handle client disconnect
-      req.on('close', () => {
-        const conn = sseConnections.get(connectionId);
-        if (conn) {
-          conn.pty.kill();
-          sseConnections.delete(connectionId);
-        }
-      });
+        // Connect to session (respawns PTY if needed) - after handlers are set up
+        await manager.connectToSession(sessionObj.id);
+        await manager.resizeSession(sessionObj.id, cols, rows);
+
+        // Handle client disconnect
+        req.on('close', () => {
+          const conn = sseConnections.get(connectionId);
+          if (conn) {
+            // Clear any pending exit timeout
+            const timeout = conn.exitTimeout?.();
+            if (timeout) clearTimeout(timeout);
+            manager.off('session:output', conn.outputHandler);
+            manager.off('session:exit', conn.exitHandler);
+            sseConnections.delete(connectionId);
+            // Note: We do NOT kill the PTY - session persists for reconnection
+          }
+        });
+      } catch (err) {
+        console.error('SSE connection error:', err);
+        res.writeHead(500, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: err.message }));
+      }
 
       return;
     }
@@ -3567,7 +3749,7 @@ function startWebServer(cliArgs) {
       req.on('data', (chunk) => {
         body += chunk;
       });
-      req.on('end', () => {
+      req.on('end', async () => {
         try {
           const { connectionId, data, type, cols, rows } = JSON.parse(body);
 
@@ -3578,12 +3760,14 @@ function startWebServer(cliArgs) {
             return;
           }
 
+          const manager = await getSessionManager();
+
           if (type === 'resize' && cols && rows) {
-            conn.pty.resize(cols, rows);
+            await manager.resizeSession(conn.sessionId, cols, rows);
           } else if (data) {
             // Decode base64 input
             const decoded = Buffer.from(data, 'base64').toString('utf8');
-            conn.pty.write(decoded);
+            manager.write(conn.sessionId, decoded);
           }
 
           res.writeHead(200, { 'Content-Type': 'application/json' });
@@ -3620,56 +3804,35 @@ function startWebServer(cliArgs) {
   // WebSocket Server
   // ============================================================================
 
-  // Track active WebSocket connections to tmux sessions
-  // ws -> { pty, sessionName }
+  // Track active WebSocket connections to sessions
+  // ws -> { sessionId, outputHandler, exitHandler }
   const wsConnections = new Map();
 
   // Track active SSE connections (fallback for mobile)
-  // connectionId -> { res, pty, stableId, sessionInfo }
+  // connectionId -> { res, sessionId, outputHandler, exitHandler }
   const sseConnections = new Map();
 
   /**
-   * Find a ghosttown session by stable ID (for web connections)
-   * Returns { fullName, displayName, stableId } or null if not found
+   * Find a session by various identifiers (UUID, short ID, or display name)
+   * Returns session object or null if not found
    */
-  function findSessionByStableIdWeb(stableId) {
-    try {
-      const output = execSync('tmux list-sessions -F "#{session_name}"', {
-        encoding: 'utf8',
-        stdio: ['pipe', 'pipe', 'pipe'],
-      });
-      const sessions = output.split('\n').filter((s) => s.trim() && s.startsWith('gt-'));
-      for (const fullName of sessions) {
-        const parsed = parseSessionName(fullName);
-        if (parsed && parsed.stableId === stableId) {
-          return parsed;
-        }
-      }
-      return null;
-    } catch (err) {
-      return null;
-    }
-  }
+  async function findSessionForWeb(identifier) {
+    const manager = await getSessionManager();
+    const sessions = await manager.listSessions();
 
-  /**
-   * Create a PTY that attaches to a tmux session
-   */
-  function createTmuxAttachPty(fullSessionName, cols, rows) {
-    const ptyProcess = pty.spawn('tmux', ['attach-session', '-t', fullSessionName], {
-      name: 'xterm-256color',
-      cols: cols,
-      rows: rows,
-      cwd: homedir(),
-      env: {
-        ...process.env,
-        TERM: 'xterm-256color',
-        COLORTERM: 'truecolor',
-        LANG: 'en_US.UTF-8',
-        LC_ALL: 'en_US.UTF-8',
-      },
-    });
+    // Try exact UUID match first
+    let session = sessions.find((s) => s.id === identifier);
+    if (session) return manager.getSession(session.id);
 
-    return ptyProcess;
+    // Try short ID prefix match
+    session = sessions.find((s) => s.id.startsWith(identifier));
+    if (session) return manager.getSession(session.id);
+
+    // Try display name match
+    session = sessions.find((s) => s.displayName === identifier);
+    if (session) return manager.getSession(session.id);
+
+    return null;
   }
 
   const wss = new WebSocketServer({ noServer: true });
@@ -3700,106 +3863,137 @@ function startWebServer(cliArgs) {
     }
   });
 
-  wss.on('connection', (ws, req) => {
+  wss.on('connection', async (ws, req) => {
     const url = new URL(req.url, `http://${req.headers.host}`);
     const cols = Number.parseInt(url.searchParams.get('cols') || '80');
     const rows = Number.parseInt(url.searchParams.get('rows') || '24');
-    const requestedSession = url.searchParams.get('session');
+
+    // Support both new (sessionId) and legacy (session) parameters
+    const sessionId = url.searchParams.get('sessionId');
+    const legacySession = url.searchParams.get('session');
     const requestedName = url.searchParams.get('name'); // Original name from URL (if different from session)
+    const identifier = sessionId || legacySession;
 
-    // Session parameter is required (should be stable ID)
-    if (!requestedSession) {
+    // Session parameter is required
+    if (!identifier) {
       ws.send(JSON.stringify({ type: 'error', message: 'Session parameter required' }));
       ws.close();
       return;
     }
 
-    // Look up session by stable ID first, then by display name (for legacy URLs)
-    let sessionInfo = findSessionByStableIdWeb(requestedSession);
-    if (!sessionInfo) {
-      // Try looking up by display name
-      sessionInfo = findSessionByDisplayName(requestedSession);
-    }
-    if (!sessionInfo) {
-      // Build error message with both name and id if available
-      let errorMsg;
-      if (requestedName && requestedName !== requestedSession) {
-        errorMsg = `No session found named ${requestedName}, or with id ${requestedSession}`;
-      } else {
-        errorMsg = `No session found named ${requestedSession} or with id ${requestedSession}`;
+    try {
+      const manager = await getSessionManager();
+
+      // Look up session by UUID, short ID, or display name
+      const session = await findSessionForWeb(identifier);
+
+      if (!session) {
+        // Build error message with both name and id if available
+        let errorMsg;
+        if (requestedName && requestedName !== identifier) {
+          errorMsg = `No session found named ${requestedName}, or with id ${identifier}`;
+        } else {
+          errorMsg = `No session found named ${identifier} or with id ${identifier}`;
+        }
+        ws.send(JSON.stringify({ type: 'error', message: errorMsg }));
+        ws.close();
+        return;
       }
-      ws.send(JSON.stringify({ type: 'error', message: errorMsg }));
-      ws.close();
-      return;
-    }
 
-    // Create a PTY that attaches to the tmux session
-    const ptyProcess = createTmuxAttachPty(sessionInfo.fullName, cols, rows);
+      // Set up event handlers BEFORE connecting (to catch early output like shell prompt)
+      const outputHandler = (sid, data) => {
+        if (sid === session.id && ws.readyState === ws.OPEN) {
+          ws.send(data);
+        }
+      };
 
-    wsConnections.set(ws, { pty: ptyProcess, stableId: requestedSession, sessionInfo });
+      const exitHandler = (sid) => {
+        if (sid === session.id && ws.readyState === ws.OPEN) {
+          ws.send(JSON.stringify({ type: 'session_exit' }));
+          // Don't close - allow reconnect
+        }
+      };
 
-    // Send session info with current display name (may have been renamed)
-    ws.send(
-      JSON.stringify({
-        type: 'session_info',
-        name: sessionInfo.displayName,
-        stableId: sessionInfo.stableId,
-      })
-    );
+      manager.on('session:output', outputHandler);
+      manager.on('session:exit', exitHandler);
 
-    ptyProcess.onData((data) => {
-      if (ws.readyState === ws.OPEN) {
-        ws.send(data);
-      }
-    });
+      wsConnections.set(ws, { sessionId: session.id, outputHandler, exitHandler });
 
-    ptyProcess.onExit(() => {
-      if (ws.readyState === ws.OPEN) {
-        ws.close();
+      // Connect to session (respawns PTY if needed after server restart)
+      await manager.connectToSession(session.id);
+
+      // Resize to requested dimensions
+      await manager.resizeSession(session.id, cols, rows);
+
+      // Send session info with current display name
+      ws.send(
+        JSON.stringify({
+          type: 'session_info',
+          name: session.displayName,
+          stableId: session.id.slice(0, 8), // Backward compat
+          id: session.id, // Full UUID (new)
+        })
+      );
+
+      // Replay scrollback buffer for reconnecting clients
+      const scrollback = await manager.getScrollback(session.id);
+      if (scrollback) {
+        ws.send(scrollback);
       }
-      wsConnections.delete(ws);
-    });
 
-    ws.on('message', (data) => {
-      const message = data.toString('utf8');
+      ws.on('message', (data) => {
+        const message = data.toString('utf8');
 
-      if (message.startsWith('{')) {
-        try {
-          const msg = JSON.parse(message);
-          if (msg.type === 'resize') {
-            ptyProcess.resize(msg.cols, msg.rows);
-            return;
+        if (message.startsWith('{')) {
+          try {
+            const msg = JSON.parse(message);
+            if (msg.type === 'resize') {
+              manager.resizeSession(session.id, msg.cols, msg.rows);
+              return;
+            }
+          } catch (e) {
+            // Not JSON, treat as input
           }
-        } catch (e) {
-          // Not JSON, treat as input
         }
-      }
 
-      ptyProcess.write(message);
-    });
+        // Write to PTY
+        try {
+          manager.write(session.id, message);
+        } catch {
+          // PTY may have exited, that's ok
+        }
+      });
 
-    ws.on('close', () => {
-      const conn = wsConnections.get(ws);
-      if (conn) {
-        conn.pty.kill();
-        wsConnections.delete(ws);
-      }
-    });
+      ws.on('close', () => {
+        const conn = wsConnections.get(ws);
+        if (conn) {
+          manager.off('session:output', conn.outputHandler);
+          manager.off('session:exit', conn.exitHandler);
+          wsConnections.delete(ws);
+          // Note: We do NOT kill the PTY - session persists for reconnection
+        }
+      });
 
-    ws.on('error', () => {
-      const conn = wsConnections.get(ws);
-      if (conn) {
-        conn.pty.kill();
-        wsConnections.delete(ws);
-      }
-    });
+      ws.on('error', () => {
+        const conn = wsConnections.get(ws);
+        if (conn) {
+          manager.off('session:output', conn.outputHandler);
+          manager.off('session:exit', conn.exitHandler);
+          wsConnections.delete(ws);
+        }
+      });
+    } catch (err) {
+      console.error('WebSocket connection error:', err);
+      ws.send(JSON.stringify({ type: 'error', message: err.message }));
+      ws.close();
+    }
   });
 
   // ============================================================================
   // Startup
   // ============================================================================
 
-  function printBanner(url, backgroundMode = false) {
+  function printBanner(url, port, backgroundMode = false) {
     const localIPs = getLocalIPs();
     // ANSI color codes
     const RESET = '\x1b[0m';
@@ -3820,7 +4014,7 @@ function startWebServer(cliArgs) {
         networkCount++;
         const spaces = networkCount !== 1 ? '           ' : '';
         const protocol = USE_HTTPS ? 'https' : 'http';
-        network.push(`${spaces}${BEIGE}${protocol}://${ip}:${HTTP_PORT}${RESET}\n`);
+        network.push(`${spaces}${BEIGE}${protocol}://${ip}:${port}${RESET}\n`);
       }
     }
     console.log(`\n${network.join('')} `);
@@ -3843,6 +4037,8 @@ function startWebServer(cliArgs) {
 
   process.on('SIGINT', () => {
     console.log('\n\nShutting down...');
+    // Clean up server config file for port discovery
+    removeServerConfig();
     for (const [ws, conn] of wsConnections.entries()) {
       conn.pty.kill();
       ws.close();
@@ -3852,6 +4048,12 @@ function startWebServer(cliArgs) {
   });
 
   httpServer.listen(HTTP_PORT, BIND_ADDRESS, async () => {
+    // Get actual port (important when HTTP_PORT is 0 for auto-discovery)
+    const actualPort = httpServer.address().port;
+
+    // Write server config for port discovery by CLI commands
+    writeServerConfig(actualPort);
+
     // Display ASCII art banner
     try {
       const imagePath = path.join(__dirname, '..', 'bin', 'assets', 'ghosts.png');
@@ -3868,7 +4070,7 @@ function startWebServer(cliArgs) {
     }
 
     const protocol = USE_HTTPS ? 'https' : 'http';
-    printBanner(`${protocol}://localhost:${HTTP_PORT}`, backgroundMode);
+    printBanner(`${protocol}://localhost:${actualPort}`, actualPort, backgroundMode);
 
     // Show warning when auth is disabled
     if (NO_AUTH) {
@@ -3881,8 +4083,8 @@ function startWebServer(cliArgs) {
 // Main entry point
 // ============================================================================
 
-export function run(argv) {
-  const cliArgs = parseArgs(argv);
+export async function run(argv) {
+  const cliArgs = await parseArgs(argv);
 
   if (cliArgs.handled) {
     return;