@cluesmith/codev 2.0.0-rc.55 → 2.0.0-rc.57

package/dist/agent-farm/servers/tower-server.js

@@ -8,7 +8,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import net from 'node:net';
 import crypto from 'node:crypto';
-import { spawn, execSync } from 'node:child_process';
+import { spawn, execSync, spawnSync } from 'node:child_process';
 import { homedir } from 'node:os';
 import { fileURLToPath } from 'node:url';
 import { Command } from 'commander';
@@ -71,11 +71,40 @@ const projectTerminals = new Map();
 function getProjectTerminalsEntry(projectPath) {
     let entry = projectTerminals.get(projectPath);
     if (!entry) {
-        entry = { builders: new Map(), shells: new Map() };
+        entry = { builders: new Map(), shells: new Map(), fileTabs: new Map() };
         projectTerminals.set(projectPath, entry);
     }
+    // Migration: ensure fileTabs exists for older entries
+    if (!entry.fileTabs) {
+        entry.fileTabs = new Map();
+    }
     return entry;
 }
+/**
+ * Get language identifier for syntax highlighting
+ */
+function getLanguageForExt(ext) {
+    const langMap = {
+        js: 'javascript', ts: 'typescript', jsx: 'javascript', tsx: 'typescript',
+        py: 'python', sh: 'bash', bash: 'bash', md: 'markdown',
+        html: 'markup', css: 'css', json: 'json', yaml: 'yaml', yml: 'yaml',
+        rs: 'rust', go: 'go', java: 'java', c: 'c', cpp: 'cpp', h: 'c',
+    };
+    return langMap[ext] || ext || 'plaintext';
+}
+/**
+ * Get MIME type for file
+ */
+function getMimeTypeForFile(filePath) {
+    const ext = path.extname(filePath).slice(1).toLowerCase();
+    const mimeTypes = {
+        png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg',
+        gif: 'image/gif', webp: 'image/webp', svg: 'image/svg+xml',
+        mp4: 'video/mp4', webm: 'video/webm', mov: 'video/quicktime',
+        pdf: 'application/pdf', txt: 'text/plain',
+    };
+    return mimeTypes[ext] || 'application/octet-stream';
+}
 /**
  * Generate next shell ID for a project
  */
@@ -139,6 +168,7 @@ function saveTerminalSession(terminalId, projectPath, type, roleId, pid, tmuxSes
       INSERT OR REPLACE INTO terminal_sessions (id, project_path, type, role_id, pid, tmux_session)
       VALUES (?, ?, ?, ?, ?, ?)
     `).run(terminalId, normalizedPath, type, roleId, pid, tmuxSession);
+        log('INFO', `Saved terminal session to SQLite: ${terminalId} (${type}) for ${path.basename(normalizedPath)}`);
     }
     catch (err) {
         log('WARN', `Failed to save terminal session: ${err.message}`);
@@ -174,6 +204,56 @@ function deleteProjectTerminalSessions(projectPath) {
         log('WARN', `Failed to delete project terminal sessions: ${err.message}`);
     }
 }
+// Whether tmux is available on this system (checked once at startup)
+let tmuxAvailable = false;
+/**
+ * Check if tmux is installed and available
+ */
+function checkTmux() {
+    try {
+        execSync('tmux -V', { stdio: 'ignore' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Create a tmux session with the given command.
+ * Returns true if created successfully, false on failure.
+ */
+function createTmuxSession(sessionName, command, args, cwd, cols, rows) {
+    // Kill any stale session with this name
+    if (tmuxSessionExists(sessionName)) {
+        killTmuxSession(sessionName);
+    }
+    try {
+        // Use spawnSync with array args to avoid shell injection via project paths
+        const tmuxArgs = [
+            'new-session', '-d',
+            '-s', sessionName,
+            '-c', cwd,
+            '-x', String(cols),
+            '-y', String(rows),
+            command, ...args,
+        ];
+        const result = spawnSync('tmux', tmuxArgs, { stdio: 'ignore' });
+        if (result.status !== 0) {
+            log('WARN', `tmux new-session exited with code ${result.status} for "${sessionName}"`);
+            return false;
+        }
+        // Hide tmux status bar (dashboard has its own tabs), enable mouse, and
+        // use aggressive-resize so tmux sizes to the largest client (not smallest)
+        spawnSync('tmux', ['set-option', '-t', sessionName, 'status', 'off'], { stdio: 'ignore' });
+        spawnSync('tmux', ['set-option', '-t', sessionName, 'mouse', 'on'], { stdio: 'ignore' });
+        spawnSync('tmux', ['set-option', '-t', sessionName, 'aggressive-resize', 'on'], { stdio: 'ignore' });
+        return true;
+    }
+    catch (err) {
+        log('WARN', `Failed to create tmux session "${sessionName}": ${err.message}`);
+        return false;
+    }
+}
 /**
  * Check if a tmux session exists
  */
@@ -213,9 +293,9 @@ function killTmuxSession(sessionName) {
 /**
  * Reconcile terminal sessions from SQLite against reality on startup.
  *
- * DESTRUCTIVE: Since we can't re-attach to PTY sessions after restart,
- * any surviving tmux sessions are orphaned and must be killed.
- * This ensures clean state and prevents zombie terminals.
+ * For sessions with surviving tmux sessions: re-attach via new node-pty,
+ * register in projectTerminals, and update SQLite with new terminal ID.
+ * For dead sessions: clean up SQLite rows and kill orphaned processes.
  */
 async function reconcileTerminalSessions() {
     const db = getGlobalDb();
@@ -232,18 +312,54 @@ async function reconcileTerminalSessions() {
         return;
     }
     log('INFO', `Reconciling ${sessions.length} terminal sessions from previous run...`);
+    const manager = getTerminalManager();
+    let reconnected = 0;
     let killed = 0;
     let cleaned = 0;
     for (const session of sessions) {
-        // Check if tmux session exists (can survive Tower restart)
-        if (session.tmux_session && tmuxSessionExists(session.tmux_session)) {
-            // DESTRUCTIVE: Kill the orphaned tmux session since we can't re-attach
-            // Without the PTY object, we have no way to control this session
-            log('INFO', `Found orphaned tmux session: ${session.tmux_session} (${session.type} for ${path.basename(session.project_path)})`);
+        // Can we reconnect to a surviving tmux session?
+        if (session.tmux_session && tmuxAvailable && tmuxSessionExists(session.tmux_session)) {
+            try {
+                // Create new node-pty that attaches to the surviving tmux session
+                const newSession = await manager.createSession({
+                    command: 'tmux',
+                    args: ['attach-session', '-t', session.tmux_session],
+                    cwd: session.project_path,
+                    label: session.type === 'architect' ? 'Architect' : `${session.type} ${session.role_id || session.id}`,
+                });
+                // Register in projectTerminals Map
+                const entry = getProjectTerminalsEntry(session.project_path);
+                if (session.type === 'architect') {
+                    entry.architect = newSession.id;
+                }
+                else if (session.type === 'builder') {
+                    const builderId = session.role_id || session.id;
+                    entry.builders.set(builderId, newSession.id);
+                }
+                else if (session.type === 'shell') {
+                    const shellId = session.role_id || session.id;
+                    entry.shells.set(shellId, newSession.id);
+                }
+                // Update SQLite: delete old row, insert new with new terminal ID
+                db.prepare('DELETE FROM terminal_sessions WHERE id = ?').run(session.id);
+                saveTerminalSession(newSession.id, session.project_path, session.type, session.role_id, newSession.pid, session.tmux_session);
+                log('INFO', `Reconnected to tmux session "${session.tmux_session}" → terminal ${newSession.id} (${session.type} for ${path.basename(session.project_path)})`);
+                reconnected++;
+                continue;
+            }
+            catch (err) {
+                log('WARN', `Failed to reconnect to tmux session "${session.tmux_session}": ${err.message}`);
+                // Fall through to cleanup
+                killTmuxSession(session.tmux_session);
+                killed++;
+            }
+        }
+        // No tmux or tmux session dead — check for orphaned processes
+        else if (session.tmux_session && tmuxSessionExists(session.tmux_session)) {
+            // tmux exists but tmuxAvailable is false (shouldn't happen, but be safe)
             killTmuxSession(session.tmux_session);
             killed++;
         }
-        // Check if process still running (kill if we can)
         else if (session.pid && processExists(session.pid)) {
             log('INFO', `Found orphaned process: PID ${session.pid} (${session.type} for ${path.basename(session.project_path)})`);
             try {
@@ -254,11 +370,11 @@ async function reconcileTerminalSessions() {
                 // Process may not be killable (different user, etc)
             }
         }
-        // Always clean up the DB row - we start fresh after restart
+        // Clean up the DB row for sessions we couldn't reconnect
         db.prepare('DELETE FROM terminal_sessions WHERE id = ?').run(session.id);
         cleaned++;
     }
-    log('INFO', `Reconciliation complete: ${killed} orphaned processes killed, ${cleaned} DB rows cleaned`);
+    log('INFO', `Reconciliation complete: ${reconnected} reconnected, ${killed} orphaned killed, ${cleaned} cleaned up`);
 }
 /**
  * Get terminal sessions from SQLite for a project.
@@ -601,16 +717,32 @@ async function getGateStatusForProject(basePort) {
  * Returns architect, builders, and shells with their URLs.
  */
 function getTerminalsForProject(projectPath, proxyUrl) {
-    const entry = projectTerminals.get(projectPath);
     const manager = getTerminalManager();
     const terminals = [];
-    if (!entry) {
-        return { terminals: [], gateStatus: { hasGate: false } };
-    }
-    // Add architect terminal
-    if (entry.architect) {
-        const session = manager.getSession(entry.architect);
-        if (session) {
+    // SQLite is authoritative - query it first (Spec 0090 requirement)
+    const dbSessions = getTerminalSessionsForProject(projectPath);
+    // Use normalized path for cache consistency
+    const normalizedPath = normalizeProjectPath(projectPath);
+    // Build a fresh entry from SQLite, then replace atomically to avoid
+    // destroying in-memory state that was registered via POST /api/terminals.
+    // Previous approach cleared the cache then rebuilt, which lost terminals
+    // if their SQLite rows were deleted by external interference (e.g., tests).
+    const freshEntry = { builders: new Map(), shells: new Map(), fileTabs: new Map() };
+    // Preserve file tabs from existing entry (not stored in SQLite)
+    const existingEntry = projectTerminals.get(normalizedPath);
+    if (existingEntry) {
+        freshEntry.fileTabs = existingEntry.fileTabs;
+    }
+    for (const dbSession of dbSessions) {
+        // Verify session still exists in TerminalManager (runtime state)
+        const session = manager.getSession(dbSession.id);
+        if (!session) {
+            // Stale row in SQLite - clean it up
+            deleteTerminalSession(dbSession.id);
+            continue;
+        }
+        if (dbSession.type === 'architect') {
+            freshEntry.architect = dbSession.id;
             terminals.push({
                 type: 'architect',
                 id: 'architect',
@@ -619,39 +751,78 @@ function getTerminalsForProject(projectPath, proxyUrl) {
                 active: true,
             });
         }
+        else if (dbSession.type === 'builder') {
+            const builderId = dbSession.role_id || dbSession.id;
+            freshEntry.builders.set(builderId, dbSession.id);
+            terminals.push({
+                type: 'builder',
+                id: builderId,
+                label: `Builder ${builderId}`,
+                url: `${proxyUrl}?tab=builder-${builderId}`,
+                active: true,
+            });
+        }
+        else if (dbSession.type === 'shell') {
+            const shellId = dbSession.role_id || dbSession.id;
+            freshEntry.shells.set(shellId, dbSession.id);
+            terminals.push({
+                type: 'shell',
+                id: shellId,
+                label: `Shell ${shellId.replace('shell-', '')}`,
+                url: `${proxyUrl}?tab=shell-${shellId}`,
+                active: true,
+            });
+        }
     }
-    // Add builder terminals
-    for (const [builderId] of entry.builders) {
-        const terminalId = entry.builders.get(builderId);
-        if (terminalId) {
-            const session = manager.getSession(terminalId);
+    // Also merge in-memory entries that may not be in SQLite yet
+    // (e.g., registered via POST /api/terminals but SQLite row was lost)
+    if (existingEntry) {
+        if (existingEntry.architect && !freshEntry.architect) {
+            const session = manager.getSession(existingEntry.architect);
             if (session) {
+                freshEntry.architect = existingEntry.architect;
                 terminals.push({
-                    type: 'builder',
-                    id: builderId,
-                    label: `Builder ${builderId}`,
-                    url: `${proxyUrl}?tab=builder-${builderId}`,
+                    type: 'architect',
+                    id: 'architect',
+                    label: 'Architect',
+                    url: `${proxyUrl}?tab=architect`,
                     active: true,
                 });
             }
         }
-    }
-    // Add shell terminals
-    for (const [shellId] of entry.shells) {
-        const terminalId = entry.shells.get(shellId);
-        if (terminalId) {
-            const session = manager.getSession(terminalId);
-            if (session) {
-                terminals.push({
-                    type: 'shell',
-                    id: shellId,
-                    label: `Shell ${shellId.replace('shell-', '')}`,
-                    url: `${proxyUrl}?tab=shell-${shellId}`,
-                    active: true,
-                });
+        for (const [builderId, terminalId] of existingEntry.builders) {
+            if (!freshEntry.builders.has(builderId)) {
+                const session = manager.getSession(terminalId);
+                if (session) {
+                    freshEntry.builders.set(builderId, terminalId);
+                    terminals.push({
+                        type: 'builder',
+                        id: builderId,
+                        label: `Builder ${builderId}`,
+                        url: `${proxyUrl}?tab=builder-${builderId}`,
+                        active: true,
+                    });
+                }
+            }
+        }
+        for (const [shellId, terminalId] of existingEntry.shells) {
+            if (!freshEntry.shells.has(shellId)) {
+                const session = manager.getSession(terminalId);
+                if (session) {
+                    freshEntry.shells.set(shellId, terminalId);
+                    terminals.push({
+                        type: 'shell',
+                        id: shellId,
+                        label: `Shell ${shellId.replace('shell-', '')}`,
+                        url: `${proxyUrl}?tab=shell-${shellId}`,
+                        active: true,
+                    });
+                }
             }
         }
     }
+    // Atomically replace the cache entry
+    projectTerminals.set(normalizedPath, freshEntry);
     // Gate status - builders don't have gate tracking yet in tower
     // TODO: Add gate status tracking when porch integration is updated
     const gateStatus = { hasGate: false };
@@ -864,8 +1035,20 @@ async function launchInstance(projectPath) {
             try {
                 // Parse command string to separate command and args
                 const cmdParts = architectCmd.split(/\s+/);
-                const cmd = cmdParts[0];
-                const cmdArgs = cmdParts.slice(1);
+                let cmd = cmdParts[0];
+                let cmdArgs = cmdParts.slice(1);
+                // Wrap in tmux for session persistence across Tower restarts
+                const tmuxName = `architect-${path.basename(projectPath)}`;
+                let activeTmuxSession = null;
+                if (tmuxAvailable) {
+                    const tmuxCreated = createTmuxSession(tmuxName, cmd, cmdArgs, projectPath, 200, 50);
+                    if (tmuxCreated) {
+                        cmd = 'tmux';
+                        cmdArgs = ['attach-session', '-t', tmuxName];
+                        activeTmuxSession = tmuxName;
+                        log('INFO', `Created tmux session "${tmuxName}" for architect`);
+                    }
+                }
                 const session = await manager.createSession({
                     command: cmd,
                     args: cmdArgs,
@@ -874,8 +1057,8 @@ async function launchInstance(projectPath) {
                     env: process.env,
                 });
                 entry.architect = session.id;
-                // TICK-001: Save to SQLite for persistence
-                saveTerminalSession(session.id, resolvedPath, 'architect', null, session.pid, null);
+                // TICK-001: Save to SQLite for persistence (with tmux session name)
+                saveTerminalSession(session.id, resolvedPath, 'architect', null, session.pid, activeTmuxSession);
                 log('INFO', `Created architect terminal for project: ${projectPath}`);
             }
             catch (err) {
@@ -922,6 +1105,11 @@ async function stopInstance(projectPath) {
     // Get project terminals
     const entry = projectTerminals.get(resolvedPath) || projectTerminals.get(projectPath);
     if (entry) {
+        // Query SQLite for tmux session names BEFORE deleting rows
+        const dbSessions = getTerminalSessionsForProject(resolvedPath);
+        const tmuxSessions = dbSessions
+            .filter(s => s.tmux_session)
+            .map(s => s.tmux_session);
         // Kill architect
         if (entry.architect) {
             const session = manager.getSession(entry.architect);
@@ -946,6 +1134,10 @@ async function stopInstance(projectPath) {
                 stopped.push(session.pid);
             }
         }
+        // Kill tmux sessions (node-pty kill only detaches, tmux keeps running)
+        for (const tmuxName of tmuxSessions) {
+            killTmuxSession(tmuxName);
+        }
         // Clear project from registry
         projectTerminals.delete(resolvedPath);
         projectTerminals.delete(projectPath);
@@ -1093,6 +1285,8 @@ const server = http.createServer(async (req, res) => {
                 if (!projectPath || (!projectPath.startsWith('/') && !/^[A-Za-z]:[\\/]/.test(projectPath))) {
                     throw new Error('Invalid path');
                 }
+                // Normalize to resolve symlinks (e.g. /var/folders → /private/var/folders on macOS)
+                projectPath = normalizeProjectPath(projectPath);
             }
             catch {
                 res.writeHead(400, { 'Content-Type': 'application/json' });
@@ -1165,17 +1359,58 @@ const server = http.createServer(async (req, res) => {
             try {
                 const body = await parseJsonBody(req);
                 const manager = getTerminalManager();
-                const info = await manager.createSession({
-                    command: typeof body.command === 'string' ? body.command : undefined,
-                    args: Array.isArray(body.args) ? body.args : undefined,
-                    cols: typeof body.cols === 'number' ? body.cols : undefined,
-                    rows: typeof body.rows === 'number' ? body.rows : undefined,
-                    cwd: typeof body.cwd === 'string' ? body.cwd : undefined,
-                    env: typeof body.env === 'object' && body.env !== null ? body.env : undefined,
-                    label: typeof body.label === 'string' ? body.label : undefined,
-                });
+                // Parse request fields
+                let command = typeof body.command === 'string' ? body.command : undefined;
+                let args = Array.isArray(body.args) ? body.args : undefined;
+                const cols = typeof body.cols === 'number' ? body.cols : undefined;
+                const rows = typeof body.rows === 'number' ? body.rows : undefined;
+                const cwd = typeof body.cwd === 'string' ? body.cwd : undefined;
+                const env = typeof body.env === 'object' && body.env !== null ? body.env : undefined;
+                const label = typeof body.label === 'string' ? body.label : undefined;
+                // Optional tmux wrapping: create tmux session, then node-pty attaches to it
+                const tmuxSession = typeof body.tmuxSession === 'string' ? body.tmuxSession : null;
+                let activeTmuxSession = null;
+                if (tmuxSession && tmuxAvailable && command && cwd) {
+                    const tmuxCreated = createTmuxSession(tmuxSession, command, args || [], cwd, cols || 200, rows || 50);
+                    if (tmuxCreated) {
+                        // Override: node-pty attaches to the tmux session
+                        command = 'tmux';
+                        args = ['attach-session', '-t', tmuxSession];
+                        activeTmuxSession = tmuxSession;
+                        log('INFO', `Created tmux session "${tmuxSession}" for terminal`);
+                    }
+                    // If tmux creation failed, fall through to bare node-pty
+                }
+                let info;
+                try {
+                    info = await manager.createSession({ command, args, cols, rows, cwd, env, label });
+                }
+                catch (createErr) {
+                    // Clean up orphaned tmux session if node-pty creation failed
+                    if (activeTmuxSession) {
+                        killTmuxSession(activeTmuxSession);
+                        log('WARN', `Cleaned up orphaned tmux session "${activeTmuxSession}" after node-pty failure`);
+                    }
+                    throw createErr;
+                }
+                // Optional project association: register terminal with project state
+                const projectPath = typeof body.projectPath === 'string' ? body.projectPath : null;
+                const termType = typeof body.type === 'string' && ['builder', 'shell'].includes(body.type) ? body.type : null;
+                const roleId = typeof body.roleId === 'string' ? body.roleId : null;
+                if (projectPath && termType && roleId) {
+                    const entry = getProjectTerminalsEntry(normalizeProjectPath(projectPath));
+                    if (termType === 'builder') {
+                        entry.builders.set(roleId, info.id);
+                    }
+                    else {
+                        entry.shells.set(roleId, info.id);
+                    }
+                    saveTerminalSession(info.id, projectPath, termType, roleId, info.pid, activeTmuxSession);
+                    log('INFO', `Registered terminal ${info.id} as ${termType} "${roleId}" for project ${projectPath}${activeTmuxSession ? ` (tmux: ${activeTmuxSession})` : ''}`);
+                }
+                // Return tmuxSession so caller knows whether tmux is backing this terminal
                 res.writeHead(201, { 'Content-Type': 'application/json' });
-                res.end(JSON.stringify({ ...info, wsPath: `/ws/terminal/${info.id}` }));
+                res.end(JSON.stringify({ ...info, wsPath: `/ws/terminal/${info.id}`, tmuxSession: activeTmuxSession }));
             }
             catch (err) {
                 const message = err instanceof Error ? err.message : 'Unknown error';
@@ -1494,6 +1729,8 @@ const server = http.createServer(async (req, res) => {
                 if (!projectPath || (!projectPath.startsWith('/') && !/^[A-Za-z]:[\\/]/.test(projectPath))) {
                     throw new Error('Invalid project path');
                 }
+                // Normalize to resolve symlinks (e.g. /var/folders → /private/var/folders on macOS)
+                projectPath = normalizeProjectPath(projectPath);
             }
             catch {
                 res.writeHead(400, { 'Content-Type': 'text/plain' });
@@ -1504,6 +1741,27 @@ const server = http.createServer(async (req, res) => {
             // Phase 4 (Spec 0090): Tower handles everything directly
             const isApiCall = subPath.startsWith('api/') || subPath === 'api';
             const isWsPath = subPath.startsWith('ws/') || subPath === 'ws';
+            // GET /file?path=<relative-path> — Read project file by path (for StatusPanel project list)
+            if (req.method === 'GET' && subPath === 'file' && url.searchParams.has('path')) {
+                const relPath = url.searchParams.get('path');
+                const fullPath = path.resolve(projectPath, relPath);
+                // Security: ensure resolved path stays within project directory
+                if (!fullPath.startsWith(projectPath + path.sep) && fullPath !== projectPath) {
+                    res.writeHead(403, { 'Content-Type': 'text/plain' });
+                    res.end('Forbidden');
+                    return;
+                }
+                try {
+                    const content = fs.readFileSync(fullPath, 'utf-8');
+                    res.writeHead(200, { 'Content-Type': 'text/plain; charset=utf-8' });
+                    res.end(content);
+                }
+                catch {
+                    res.writeHead(404, { 'Content-Type': 'text/plain' });
+                    res.end('Not found');
+                }
+                return;
+            }
             // Serve React dashboard static files directly if:
             // 1. Not an API call
             // 2. Not a WebSocket path
@@ -1580,6 +1838,15 @@ const server = http.createServer(async (req, res) => {
                             terminalId,
                         });
                     }
+                    // Add file tabs (Spec 0092 - served through Tower, no separate ports)
+                    for (const [tabId, tab] of entry.fileTabs) {
+                        state.annotations.push({
+                            id: tabId,
+                            file: tab.path,
+                            port: 0, // No separate port - served through Tower
+                            pid: 0, // No separate process
+                        });
+                    }
                     res.writeHead(200, { 'Content-Type': 'application/json' });
                     res.end(JSON.stringify(state));
                     return;
@@ -1589,10 +1856,23 @@ const server = http.createServer(async (req, res) => {
                     try {
                         const manager = getTerminalManager();
                         const shellId = getNextShellId(projectPath);
+                        // Wrap in tmux for session persistence
+                        let shellCmd = process.env.SHELL || '/bin/bash';
+                        let shellArgs = [];
+                        const tmuxName = `shell-${path.basename(projectPath)}-${shellId}`;
+                        let activeTmuxSession = null;
+                        if (tmuxAvailable) {
+                            const tmuxCreated = createTmuxSession(tmuxName, shellCmd, shellArgs, projectPath, 200, 50);
+                            if (tmuxCreated) {
+                                shellCmd = 'tmux';
+                                shellArgs = ['attach-session', '-t', tmuxName];
+                                activeTmuxSession = tmuxName;
+                            }
+                        }
                         // Create terminal session
                         const session = await manager.createSession({
-                            command: process.env.SHELL || '/bin/bash',
-                            args: [],
+                            command: shellCmd,
+                            args: shellArgs,
                             cwd: projectPath,
                             label: `Shell ${shellId.replace('shell-', '')}`,
                             env: process.env,
@@ -1601,7 +1881,7 @@ const server = http.createServer(async (req, res) => {
                         const entry = getProjectTerminalsEntry(projectPath);
                         entry.shells.set(shellId, session.id);
                         // TICK-001: Save to SQLite for persistence
-                        saveTerminalSession(session.id, projectPath, 'shell', shellId, session.pid, null);
+                        saveTerminalSession(session.id, projectPath, 'shell', shellId, session.pid, activeTmuxSession);
                         res.writeHead(200, { 'Content-Type': 'application/json' });
                         res.end(JSON.stringify({
                             id: shellId,
@@ -1617,12 +1897,193 @@ const server = http.createServer(async (req, res) => {
                     }
                     return;
                 }
-                // DELETE /api/tabs/:id - Delete a terminal tab
+                // POST /api/tabs/file - Create a file tab (Spec 0092)
+                if (req.method === 'POST' && apiPath === 'tabs/file') {
+                    try {
+                        const body = await new Promise((resolve) => {
+                            let data = '';
+                            req.on('data', (chunk) => data += chunk.toString());
+                            req.on('end', () => resolve(data));
+                        });
+                        const { path: filePath, line } = JSON.parse(body || '{}');
+                        if (!filePath || typeof filePath !== 'string') {
+                            res.writeHead(400, { 'Content-Type': 'application/json' });
+                            res.end(JSON.stringify({ error: 'Missing path parameter' }));
+                            return;
+                        }
+                        // Resolve path relative to project
+                        const fullPath = path.isAbsolute(filePath)
+                            ? filePath
+                            : path.join(projectPath, filePath);
+                        // Security: ensure path is within project or is absolute path user provided
+                        const normalizedFull = path.normalize(fullPath);
+                        const normalizedProject = path.normalize(projectPath);
+                        if (!normalizedFull.startsWith(normalizedProject) && !path.isAbsolute(filePath)) {
+                            res.writeHead(403, { 'Content-Type': 'application/json' });
+                            res.end(JSON.stringify({ error: 'Path outside project' }));
+                            return;
+                        }
+                        // Check file exists
+                        if (!fs.existsSync(fullPath)) {
+                            res.writeHead(404, { 'Content-Type': 'application/json' });
+                            res.end(JSON.stringify({ error: 'File not found' }));
+                            return;
+                        }
+                        const entry = getProjectTerminalsEntry(projectPath);
+                        // Check if already open
+                        for (const [id, tab] of entry.fileTabs) {
+                            if (tab.path === fullPath) {
+                                res.writeHead(200, { 'Content-Type': 'application/json' });
+                                res.end(JSON.stringify({ id, existing: true, line }));
+                                return;
+                            }
+                        }
+                        // Create new file tab
+                        const id = `file-${Date.now().toString(36)}`;
+                        entry.fileTabs.set(id, { id, path: fullPath, createdAt: Date.now() });
+                        log('INFO', `Created file tab: ${id} for ${path.basename(fullPath)}`);
+                        res.writeHead(200, { 'Content-Type': 'application/json' });
+                        res.end(JSON.stringify({ id, existing: false, line }));
+                    }
+                    catch (err) {
+                        log('ERROR', `Failed to create file tab: ${err.message}`);
+                        res.writeHead(500, { 'Content-Type': 'application/json' });
+                        res.end(JSON.stringify({ error: err.message }));
+                    }
+                    return;
+                }
+                // GET /api/file/:id - Get file content as JSON (Spec 0092)
+                const fileGetMatch = apiPath.match(/^file\/([^/]+)$/);
+                if (req.method === 'GET' && fileGetMatch) {
+                    const tabId = fileGetMatch[1];
+                    const entry = getProjectTerminalsEntry(projectPath);
+                    const tab = entry.fileTabs.get(tabId);
+                    if (!tab) {
+                        res.writeHead(404, { 'Content-Type': 'application/json' });
+                        res.end(JSON.stringify({ error: 'File tab not found' }));
+                        return;
+                    }
+                    try {
+                        const ext = path.extname(tab.path).slice(1).toLowerCase();
+                        const isText = !['png', 'jpg', 'jpeg', 'gif', 'webp', 'svg', 'mp4', 'webm', 'mov', 'pdf'].includes(ext);
+                        if (isText) {
+                            const content = fs.readFileSync(tab.path, 'utf-8');
+                            res.writeHead(200, { 'Content-Type': 'application/json' });
+                            res.end(JSON.stringify({
+                                path: tab.path,
+                                name: path.basename(tab.path),
+                                content,
+                                language: getLanguageForExt(ext),
+                                isMarkdown: ext === 'md',
+                                isImage: false,
+                                isVideo: false,
+                            }));
+                        }
+                        else {
+                            // For binary files, just return metadata
+                            const stat = fs.statSync(tab.path);
+                            const isImage = ['png', 'jpg', 'jpeg', 'gif', 'webp', 'svg'].includes(ext);
+                            const isVideo = ['mp4', 'webm', 'mov'].includes(ext);
+                            res.writeHead(200, { 'Content-Type': 'application/json' });
+                            res.end(JSON.stringify({
+                                path: tab.path,
+                                name: path.basename(tab.path),
+                                content: null,
+                                language: ext,
+                                isMarkdown: false,
+                                isImage,
+                                isVideo,
+                                size: stat.size,
+                            }));
+                        }
+                    }
+                    catch (err) {
+                        res.writeHead(500, { 'Content-Type': 'application/json' });
+                        res.end(JSON.stringify({ error: err.message }));
+                    }
+                    return;
+                }
+                // GET /api/file/:id/raw - Get raw file content (for images/video) (Spec 0092)
+                const fileRawMatch = apiPath.match(/^file\/([^/]+)\/raw$/);
+                if (req.method === 'GET' && fileRawMatch) {
+                    const tabId = fileRawMatch[1];
+                    const entry = getProjectTerminalsEntry(projectPath);
+                    const tab = entry.fileTabs.get(tabId);
+                    if (!tab) {
+                        res.writeHead(404, { 'Content-Type': 'text/plain' });
+                        res.end('File tab not found');
+                        return;
+                    }
+                    try {
+                        const data = fs.readFileSync(tab.path);
+                        const mimeType = getMimeTypeForFile(tab.path);
+                        res.writeHead(200, {
+                            'Content-Type': mimeType,
+                            'Content-Length': data.length,
+                            'Cache-Control': 'no-cache',
+                        });
+                        res.end(data);
+                    }
+                    catch (err) {
+                        res.writeHead(500, { 'Content-Type': 'text/plain' });
+                        res.end(err.message);
+                    }
+                    return;
+                }
+                // POST /api/file/:id/save - Save file content (Spec 0092)
+                const fileSaveMatch = apiPath.match(/^file\/([^/]+)\/save$/);
+                if (req.method === 'POST' && fileSaveMatch) {
+                    const tabId = fileSaveMatch[1];
+                    const entry = getProjectTerminalsEntry(projectPath);
+                    const tab = entry.fileTabs.get(tabId);
+                    if (!tab) {
+                        res.writeHead(404, { 'Content-Type': 'application/json' });
+                        res.end(JSON.stringify({ error: 'File tab not found' }));
+                        return;
+                    }
+                    try {
+                        const body = await new Promise((resolve) => {
+                            let data = '';
+                            req.on('data', (chunk) => data += chunk.toString());
+                            req.on('end', () => resolve(data));
+                        });
+                        const { content } = JSON.parse(body || '{}');
+                        if (typeof content !== 'string') {
+                            res.writeHead(400, { 'Content-Type': 'application/json' });
+                            res.end(JSON.stringify({ error: 'Missing content parameter' }));
+                            return;
+                        }
+                        fs.writeFileSync(tab.path, content, 'utf-8');
+                        log('INFO', `Saved file: ${tab.path}`);
+                        res.writeHead(200, { 'Content-Type': 'application/json' });
+                        res.end(JSON.stringify({ success: true }));
+                    }
+                    catch (err) {
+                        res.writeHead(500, { 'Content-Type': 'application/json' });
+                        res.end(JSON.stringify({ error: err.message }));
+                    }
+                    return;
+                }
+                // DELETE /api/tabs/:id - Delete a terminal or file tab
                 const deleteMatch = apiPath.match(/^tabs\/(.+)$/);
                 if (req.method === 'DELETE' && deleteMatch) {
                     const tabId = deleteMatch[1];
                     const entry = getProjectTerminalsEntry(projectPath);
                     const manager = getTerminalManager();
+                    // Check if it's a file tab first (Spec 0092)
+                    if (tabId.startsWith('file-')) {
+                        if (entry.fileTabs.has(tabId)) {
+                            entry.fileTabs.delete(tabId);
+                            log('INFO', `Deleted file tab: ${tabId}`);
+                            res.writeHead(204);
+                            res.end();
+                        }
+                        else {
+                            res.writeHead(404, { 'Content-Type': 'application/json' });
+                            res.end(JSON.stringify({ error: 'File tab not found' }));
+                        }
+                        return;
+                    }
                     // Find and delete the terminal
                     let terminalId;
                     if (tabId.startsWith('shell-')) {
@@ -1678,6 +2139,241 @@ const server = http.createServer(async (req, res) => {
                     res.end(JSON.stringify({ ok: true }));
                     return;
                 }
+                // GET /api/files - Return project directory tree for file browser (Spec 0092)
+                if (req.method === 'GET' && apiPath === 'files') {
+                    const maxDepth = parseInt(url.searchParams.get('depth') || '3', 10);
+                    const ignore = new Set(['.git', 'node_modules', '.builders', 'dist', '.agent-farm', '.next', '.cache', '__pycache__']);
+                    function readTree(dir, depth) {
+                        if (depth <= 0)
+                            return [];
+                        try {
+                            const entries = fs.readdirSync(dir, { withFileTypes: true });
+                            return entries
+                                .filter(e => !e.name.startsWith('.') || e.name === '.env.example')
+                                .filter(e => !ignore.has(e.name))
+                                .sort((a, b) => {
+                                // Directories first, then alphabetical
+                                if (a.isDirectory() && !b.isDirectory())
+                                    return -1;
+                                if (!a.isDirectory() && b.isDirectory())
+                                    return 1;
+                                return a.name.localeCompare(b.name);
+                            })
+                                .map(e => {
+                                const fullPath = path.join(dir, e.name);
+                                const relativePath = path.relative(projectPath, fullPath);
+                                if (e.isDirectory()) {
+                                    return { name: e.name, path: relativePath, type: 'directory', children: readTree(fullPath, depth - 1) };
+                                }
+                                return { name: e.name, path: relativePath, type: 'file' };
+                            });
+                        }
+                        catch {
+                            return [];
+                        }
+                    }
+                    const tree = readTree(projectPath, maxDepth);
+                    res.writeHead(200, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify(tree));
+                    return;
+                }
+                // GET /api/git/status - Return git status for file browser (Spec 0092)
+                if (req.method === 'GET' && apiPath === 'git/status') {
+                    try {
+                        // Get git status in porcelain format for parsing
+                        const result = execSync('git status --porcelain', {
+                            cwd: projectPath,
+                            encoding: 'utf-8',
+                            timeout: 5000,
+                        });
+                        // Parse porcelain output: XY filename
+                        // X = staging area status, Y = working tree status
+                        const modified = [];
+                        const staged = [];
+                        const untracked = [];
+                        for (const line of result.split('\n')) {
+                            if (!line)
+                                continue;
+                            const x = line[0]; // staging area
+                            const y = line[1]; // working tree
+                            const filepath = line.slice(3);
+                            if (x === '?' && y === '?') {
+                                untracked.push(filepath);
+                            }
+                            else {
+                                if (x !== ' ' && x !== '?') {
+                                    staged.push(filepath);
+                                }
+                                if (y !== ' ' && y !== '?') {
+                                    modified.push(filepath);
+                                }
+                            }
+                        }
+                        res.writeHead(200, { 'Content-Type': 'application/json' });
+                        res.end(JSON.stringify({ modified, staged, untracked }));
+                    }
+                    catch (err) {
+                        // Not a git repo or git command failed
+                        res.writeHead(200, { 'Content-Type': 'application/json' });
+                        res.end(JSON.stringify({ modified: [], staged: [], untracked: [], error: err.message }));
+                    }
+                    return;
+                }
+                // GET /api/files/recent - Return recently opened file tabs (Spec 0092)
+                if (req.method === 'GET' && apiPath === 'files/recent') {
+                    const entry = getProjectTerminalsEntry(projectPath);
+                    // Get all file tabs sorted by creation time (most recent first)
+                    const recentFiles = Array.from(entry.fileTabs.values())
+                        .sort((a, b) => b.createdAt - a.createdAt)
+                        .slice(0, 10) // Limit to 10 most recent
+                        .map(tab => ({
+                        id: tab.id,
+                        path: tab.path,
+                        name: path.basename(tab.path),
+                        relativePath: path.relative(projectPath, tab.path),
+                    }));
+                    res.writeHead(200, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify(recentFiles));
+                    return;
+                }
+                // GET /api/annotate/:tabId/* — Serve rich annotator template and sub-APIs
+                const annotateMatch = apiPath.match(/^annotate\/([^/]+)(\/(.*))?$/);
+                if (annotateMatch) {
+                    const tabId = annotateMatch[1];
+                    const subRoute = annotateMatch[3] || '';
+                    const entry = getProjectTerminalsEntry(projectPath);
+                    const tab = entry.fileTabs.get(tabId);
+                    if (!tab) {
+                        res.writeHead(404, { 'Content-Type': 'text/plain' });
+                        res.end('File tab not found');
+                        return;
+                    }
+                    const filePath = tab.path;
+                    const ext = path.extname(filePath).slice(1).toLowerCase();
+                    const isImage = ['png', 'jpg', 'jpeg', 'gif', 'webp', 'svg'].includes(ext);
+                    const isVideo = ['mp4', 'webm', 'mov'].includes(ext);
+                    const is3D = ['stl', '3mf'].includes(ext);
+                    const isMarkdown = ext === 'md';
+                    // Sub-route: GET /file — re-read file content from disk
+                    if (req.method === 'GET' && subRoute === 'file') {
+                        try {
+                            const content = fs.readFileSync(filePath, 'utf-8');
+                            res.writeHead(200, { 'Content-Type': 'text/plain; charset=utf-8' });
+                            res.end(content);
+                        }
+                        catch (err) {
+                            res.writeHead(500, { 'Content-Type': 'text/plain' });
+                            res.end(err.message);
+                        }
+                        return;
+                    }
+                    // Sub-route: POST /save — save file content
+                    if (req.method === 'POST' && subRoute === 'save') {
+                        try {
+                            const body = await new Promise((resolve) => {
+                                let data = '';
+                                req.on('data', (chunk) => data += chunk.toString());
+                                req.on('end', () => resolve(data));
+                            });
+                            const parsed = JSON.parse(body || '{}');
+                            const fileContent = parsed.content;
+                            if (typeof fileContent !== 'string') {
+                                res.writeHead(400, { 'Content-Type': 'text/plain' });
+                                res.end('Missing content');
+                                return;
+                            }
+                            fs.writeFileSync(filePath, fileContent, 'utf-8');
+                            res.writeHead(200, { 'Content-Type': 'application/json' });
+                            res.end(JSON.stringify({ ok: true }));
+                        }
+                        catch (err) {
+                            res.writeHead(500, { 'Content-Type': 'text/plain' });
+                            res.end(err.message);
+                        }
+                        return;
+                    }
+                    // Sub-route: GET /api/mtime — file modification time
+                    if (req.method === 'GET' && subRoute === 'api/mtime') {
+                        try {
+                            const stat = fs.statSync(filePath);
+                            res.writeHead(200, { 'Content-Type': 'application/json' });
+                            res.end(JSON.stringify({ mtime: stat.mtimeMs }));
+                        }
+                        catch (err) {
+                            res.writeHead(500, { 'Content-Type': 'text/plain' });
+                            res.end(err.message);
+                        }
+                        return;
+                    }
+                    // Sub-route: GET /api/image, /api/video, /api/model — raw binary content
+                    if (req.method === 'GET' && (subRoute === 'api/image' || subRoute === 'api/video' || subRoute === 'api/model')) {
+                        try {
+                            const data = fs.readFileSync(filePath);
+                            const mimeType = getMimeTypeForFile(filePath);
+                            res.writeHead(200, {
+                                'Content-Type': mimeType,
+                                'Content-Length': data.length,
+                                'Cache-Control': 'no-cache',
+                            });
+                            res.end(data);
+                        }
+                        catch (err) {
+                            res.writeHead(500, { 'Content-Type': 'text/plain' });
+                            res.end(err.message);
+                        }
+                        return;
+                    }
+                    // Default: serve the annotator HTML template
+                    if (req.method === 'GET' && (subRoute === '' || subRoute === undefined)) {
+                        try {
+                            const templateFile = is3D ? '3d-viewer.html' : 'open.html';
+                            const tplPath = path.resolve(__dirname, `../../../templates/${templateFile}`);
+                            let html = fs.readFileSync(tplPath, 'utf-8');
+                            const fileName = path.basename(filePath);
+                            const fileSize = fs.statSync(filePath).size;
+                            if (is3D) {
+                                html = html.replace(/\{\{FILE\}\}/g, fileName);
+                                html = html.replace(/\{\{FILE_PATH_JSON\}\}/g, JSON.stringify(filePath));
+                                html = html.replace(/\{\{FORMAT\}\}/g, ext);
+                            }
+                            else {
+                                html = html.replace(/\{\{FILE\}\}/g, fileName);
+                                html = html.replace(/\{\{FILE_PATH\}\}/g, filePath);
+                                html = html.replace(/\{\{BUILDER_ID\}\}/g, '');
+                                html = html.replace(/\{\{LANG\}\}/g, getLanguageForExt(ext));
+                                html = html.replace(/\{\{IS_MARKDOWN\}\}/g, String(isMarkdown));
+                                html = html.replace(/\{\{IS_IMAGE\}\}/g, String(isImage));
+                                html = html.replace(/\{\{IS_VIDEO\}\}/g, String(isVideo));
+                                html = html.replace(/\{\{FILE_SIZE\}\}/g, String(fileSize));
+                                // Inject initialization script (template loads content via fetch)
+                                let initScript;
+                                if (isImage) {
+                                    initScript = `initImage(${fileSize});`;
+                                }
+                                else if (isVideo) {
+                                    initScript = `initVideo(${fileSize});`;
+                                }
+                                else {
+                                    initScript = `fetch('file').then(r=>r.text()).then(init);`;
+                                }
+                                html = html.replace('// FILE_CONTENT will be injected by the server', initScript);
+                            }
+                            // Handle ?line= query param for scroll-to-line
+                            const lineParam = url.searchParams.get('line');
+                            if (lineParam) {
+                                const scrollScript = `<script>window.addEventListener('load',()=>{setTimeout(()=>{const el=document.querySelector('[data-line="${lineParam}"]');if(el){el.scrollIntoView({block:'center'});el.classList.add('highlighted-line');}},200);})</script>`;
+                                html = html.replace('</body>', `${scrollScript}</body>`);
+                            }
+                            res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+                            res.end(html);
+                        }
+                        catch (err) {
+                            res.writeHead(500, { 'Content-Type': 'text/plain' });
+                            res.end(`Failed to serve annotator: ${err.message}`);
+                        }
+                        return;
+                    }
+                }
                 // Unhandled API route
                 res.writeHead(404, { 'Content-Type': 'application/json' });
                 res.end(JSON.stringify({ error: 'API endpoint not found', path: apiPath }));
@@ -1714,6 +2410,9 @@ const server = http.createServer(async (req, res) => {
 // SECURITY: Bind to localhost only to prevent network exposure
 server.listen(port, '127.0.0.1', async () => {
     log('INFO', `Tower server listening at http://localhost:${port}`);
+    // Check tmux availability once at startup
+    tmuxAvailable = checkTmux();
+    log('INFO', `tmux available: ${tmuxAvailable}${tmuxAvailable ? '' : ' (terminals will not persist across restarts)'}`);
     // TICK-001: Reconcile terminal sessions from previous run
     await reconcileTerminalSessions();
 });
@@ -1762,6 +2461,8 @@ server.on('upgrade', async (req, socket, head) => {
         if (!projectPath || (!projectPath.startsWith('/') && !/^[A-Za-z]:[\\/]/.test(projectPath))) {
             throw new Error('Invalid project path');
         }
+        // Normalize to resolve symlinks (e.g. /var/folders → /private/var/folders on macOS)
+        projectPath = normalizeProjectPath(projectPath);
     }
     catch {
         socket.write('HTTP/1.1 400 Bad Request\r\n\r\n');