@cluesmith/codev 2.0.0-rc.60 → 2.0.0-rc.63

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

@@ -6,18 +6,21 @@
 import http from 'node:http';
 import fs from 'node:fs';
 import path from 'node:path';
-import net from 'node:net';
 import crypto from 'node:crypto';
-import { spawn, execSync, spawnSync } from 'node:child_process';
+import { execSync, spawnSync } from 'node:child_process';
 import { homedir, tmpdir } from 'node:os';
 import { fileURLToPath } from 'node:url';
 import { Command } from 'commander';
 import { WebSocketServer, WebSocket } from 'ws';
 import { getGlobalDb } from '../db/index.js';
-import { cleanupStaleEntries } from '../utils/port-registry.js';
 import { parseJsonBody, isRequestAllowed } from '../utils/server-utils.js';
+import { getGateStatusForProject } from '../utils/gate-status.js';
+import { GateWatcher } from '../utils/gate-watcher.js';
+import { saveFileTab as saveFileTabToDb, deleteFileTab as deleteFileTabFromDb, loadFileTabsForProject as loadFileTabsFromDb, } from '../utils/file-tabs.js';
 import { TerminalManager } from '../../terminal/pty-manager.js';
 import { encodeData, encodeControl, decodeFrame } from '../../terminal/ws-protocol.js';
+import { TunnelClient } from '../lib/tunnel-client.js';
+import { readCloudConfig, getCloudConfigPath, maskApiKey } from '../lib/cloud-config.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 // Default port for tower dashboard
@@ -59,6 +62,178 @@ function cleanupRateLimits() {
 // Cleanup stale rate limit entries every 5 minutes
 setInterval(cleanupRateLimits, 5 * 60 * 1000);
 // ============================================================================
+// Cloud Tunnel Client (Spec 0097 Phase 4)
+// ============================================================================
+/** Tunnel client instance — created on startup or via POST /api/tunnel/connect */
+let tunnelClient = null;
+/** Config file watcher — watches cloud-config.json for changes */
+let configWatcher = null;
+/** Debounce timer for config file watcher events */
+let configWatchDebounce = null;
+/** Default tunnel port for codevos.ai */
+// TICK-001: tunnelPort is no longer needed — WebSocket connects on the same port
+/** Periodic metadata refresh interval (re-sends metadata to codevos.ai) */
+let metadataRefreshInterval = null;
+/** Metadata refresh period in milliseconds (30 seconds) */
+const METADATA_REFRESH_MS = 30_000;
+/**
+ * Gather current tower metadata (projects + terminals) for codevos.ai.
+ */
+async function gatherMetadata() {
+    const instances = await getInstances();
+    const projects = instances.map((i) => ({
+        path: i.projectPath,
+        name: i.projectName,
+    }));
+    // Build reverse mapping: terminal ID → project path
+    const terminalToProject = new Map();
+    for (const [projectPath, entry] of projectTerminals) {
+        if (entry.architect)
+            terminalToProject.set(entry.architect, projectPath);
+        for (const termId of entry.builders.values())
+            terminalToProject.set(termId, projectPath);
+        for (const termId of entry.shells.values())
+            terminalToProject.set(termId, projectPath);
+    }
+    const manager = terminalManager;
+    const terminals = [];
+    if (manager) {
+        for (const session of manager.listSessions()) {
+            terminals.push({
+                id: session.id,
+                projectPath: terminalToProject.get(session.id) ?? '',
+            });
+        }
+    }
+    return { projects, terminals };
+}
+/**
+ * Start periodic metadata refresh — re-gathers metadata and pushes to codevos.ai
+ * every METADATA_REFRESH_MS while the tunnel is connected.
+ */
+function startMetadataRefresh() {
+    stopMetadataRefresh();
+    metadataRefreshInterval = setInterval(async () => {
+        try {
+            if (tunnelClient && tunnelClient.getState() === 'connected') {
+                const metadata = await gatherMetadata();
+                tunnelClient.sendMetadata(metadata);
+            }
+        }
+        catch (err) {
+            log('WARN', `Metadata refresh failed: ${err.message}`);
+        }
+    }, METADATA_REFRESH_MS);
+}
+/**
+ * Stop the periodic metadata refresh.
+ */
+function stopMetadataRefresh() {
+    if (metadataRefreshInterval) {
+        clearInterval(metadataRefreshInterval);
+        metadataRefreshInterval = null;
+    }
+}
+/**
+ * Create or reconnect the tunnel client using the given config.
+ * Sets up state change listeners and sends initial metadata.
+ */
+async function connectTunnel(config) {
+    // Disconnect existing client if any
+    if (tunnelClient) {
+        tunnelClient.disconnect();
+    }
+    const client = new TunnelClient({
+        serverUrl: config.server_url,
+        apiKey: config.api_key,
+        towerId: config.tower_id,
+        localPort: port,
+    });
+    client.onStateChange((state, prev) => {
+        log('INFO', `Tunnel: ${prev} → ${state}`);
+        if (state === 'connected') {
+            startMetadataRefresh();
+        }
+        else if (prev === 'connected') {
+            stopMetadataRefresh();
+        }
+        if (state === 'auth_failed') {
+            log('ERROR', 'Cloud connection failed: API key is invalid or revoked. Run \'af tower register --reauth\' to update credentials.');
+        }
+    });
+    // Gather and set initial metadata before connecting
+    const metadata = await gatherMetadata();
+    client.sendMetadata(metadata);
+    tunnelClient = client;
+    client.connect();
+    // Ensure config watcher is running — the config directory now exists.
+    // Handles the case where Tower booted before registration (directory didn't
+    // exist, so startConfigWatcher() silently failed at boot time).
+    startConfigWatcher();
+    return client;
+}
+/**
+ * Start watching cloud-config.json for changes.
+ * On change: reconnect with new credentials.
+ * On delete: disconnect tunnel.
+ */
+function startConfigWatcher() {
+    stopConfigWatcher();
+    const configPath = getCloudConfigPath();
+    const configDir = path.dirname(configPath);
+    const configFile = path.basename(configPath);
+    // Watch the directory (more reliable than watching the file directly)
+    try {
+        configWatcher = fs.watch(configDir, (eventType, filename) => {
+            if (filename !== configFile)
+                return;
+            // Debounce: multiple events fire for a single write
+            if (configWatchDebounce)
+                clearTimeout(configWatchDebounce);
+            configWatchDebounce = setTimeout(async () => {
+                configWatchDebounce = null;
+                try {
+                    const config = readCloudConfig();
+                    if (config) {
+                        log('INFO', `Cloud config changed, reconnecting tunnel (key: ${maskApiKey(config.api_key)})`);
+                        // Reset circuit breaker in case previous key was invalid
+                        if (tunnelClient)
+                            tunnelClient.resetCircuitBreaker();
+                        await connectTunnel(config);
+                    }
+                    else {
+                        // Config deleted or invalid
+                        log('INFO', 'Cloud config removed or invalid, disconnecting tunnel');
+                        if (tunnelClient) {
+                            tunnelClient.disconnect();
+                            tunnelClient = null;
+                        }
+                    }
+                }
+                catch (err) {
+                    log('WARN', `Error handling config change: ${err.message}`);
+                }
+            }, 500);
+        });
+    }
+    catch {
+        // Directory doesn't exist yet — that's fine, user hasn't registered
+    }
+}
+/**
+ * Stop watching cloud-config.json.
+ */
+function stopConfigWatcher() {
+    if (configWatcher) {
+        configWatcher.close();
+        configWatcher = null;
+    }
+    if (configWatchDebounce) {
+        clearTimeout(configWatchDebounce);
+        configWatchDebounce = null;
+    }
+}
+// ============================================================================
 // PHASE 2 & 4: Terminal Management (Spec 0090)
 // ============================================================================
 // Global TerminalManager instance for tower-managed terminals
@@ -66,12 +241,14 @@ setInterval(cleanupRateLimits, 5 * 60 * 1000);
 let terminalManager = null;
 const projectTerminals = new Map();
 /**
- * Get or create project terminal registry entry
+ * Get or create project terminal registry entry.
+ * On first access for a project, hydrates file tabs from SQLite so
+ * persisted tabs are available immediately (not just after /api/state).
  */
 function getProjectTerminalsEntry(projectPath) {
     let entry = projectTerminals.get(projectPath);
     if (!entry) {
-        entry = { builders: new Map(), shells: new Map(), fileTabs: new Map() };
+        entry = { builders: new Map(), shells: new Map(), fileTabs: loadFileTabsForProject(projectPath) };
         projectTerminals.set(projectPath, entry);
     }
     // Migration: ensure fileTabs exists for older entries
@@ -204,6 +381,45 @@ function deleteProjectTerminalSessions(projectPath) {
         log('WARN', `Failed to delete project terminal sessions: ${err.message}`);
     }
 }
+/**
+ * Save a file tab to SQLite for persistence across Tower restarts.
+ * Thin wrapper around utils/file-tabs.ts with error handling and path normalization.
+ */
+function saveFileTab(id, projectPath, filePath, createdAt) {
+    try {
+        const normalizedPath = normalizeProjectPath(projectPath);
+        saveFileTabToDb(getGlobalDb(), id, normalizedPath, filePath, createdAt);
+    }
+    catch (err) {
+        log('WARN', `Failed to save file tab: ${err.message}`);
+    }
+}
+/**
+ * Delete a file tab from SQLite.
+ * Thin wrapper around utils/file-tabs.ts with error handling.
+ */
+function deleteFileTab(id) {
+    try {
+        deleteFileTabFromDb(getGlobalDb(), id);
+    }
+    catch (err) {
+        log('WARN', `Failed to delete file tab: ${err.message}`);
+    }
+}
+/**
+ * Load file tabs for a project from SQLite.
+ * Thin wrapper around utils/file-tabs.ts with error handling and path normalization.
+ */
+function loadFileTabsForProject(projectPath) {
+    try {
+        const normalizedPath = normalizeProjectPath(projectPath);
+        return loadFileTabsFromDb(getGlobalDb(), normalizedPath);
+    }
+    catch (err) {
+        log('WARN', `Failed to load file tabs: ${err.message}`);
+    }
+    return new Map();
+}
 // Whether tmux is available on this system (checked once at startup)
 let tmuxAvailable = false;
 /**
@@ -218,11 +434,23 @@ function checkTmux() {
         return false;
     }
 }
+/**
+ * Sanitize a tmux session name to match what tmux actually creates.
+ * tmux replaces dots with underscores and strips colons from session names.
+ * Without this, stored names won't match actual tmux session names,
+ * causing reconnection to fail (e.g., "builder-codevos.ai-0001" vs "builder-codevos_ai-0001").
+ */
+function sanitizeTmuxSessionName(name) {
+    return name.replace(/\./g, '_').replace(/:/g, '');
+}
 /**
  * Create a tmux session with the given command.
- * Returns true if created successfully, false on failure.
+ * Returns the sanitized session name if created successfully, null on failure.
+ * Session names are sanitized to match tmux behavior (dots → underscores, colons stripped).
  */
 function createTmuxSession(sessionName, command, args, cwd, cols, rows) {
+    // Sanitize to match what tmux actually creates (dots → underscores, colons stripped)
+    sessionName = sanitizeTmuxSessionName(sessionName);
     // Kill any stale session with this name
     if (tmuxSessionExists(sessionName)) {
         killTmuxSession(sessionName);
@@ -240,26 +468,30 @@ function createTmuxSession(sessionName, command, args, cwd, cols, rows) {
         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;
+            return null;
         }
-        // Hide tmux status bar (dashboard has its own tabs), enable mouse, and
-        // use aggressive-resize so tmux sizes to the largest client (not smallest)
+        // Hide tmux status bar (dashboard has its own tabs) and enable mouse.
+        // NOTE: aggressive-resize was removed — it caused resize bouncing and
+        // visual flashing (dots/redraws) when the dashboard sent multiple resize
+        // events during layout settling. Default tmux behavior (size to smallest
+        // client) is more stable since we only have one client per session.
         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;
+        return sessionName;
     }
     catch (err) {
         log('WARN', `Failed to create tmux session "${sessionName}": ${err.message}`);
-        return false;
+        return null;
     }
 }
 /**
- * Check if a tmux session exists
+ * Check if a tmux session exists.
+ * Sanitizes the name to handle legacy entries stored before dot-replacement fix.
  */
 function tmuxSessionExists(sessionName) {
+    const sanitized = sanitizeTmuxSessionName(sessionName);
     try {
-        execSync(`tmux has-session -t "${sessionName}" 2>/dev/null`, { stdio: 'ignore' });
+        execSync(`tmux has-session -t "${sanitized}" 2>/dev/null`, { stdio: 'ignore' });
         return true;
     }
     catch {
@@ -291,90 +523,242 @@ function killTmuxSession(sessionName) {
     }
 }
 /**
- * Reconcile terminal sessions from SQLite against reality on startup.
+ * Parse a codev tmux session name to extract type, project, and role.
+ * Returns null if the name doesn't match any known codev pattern.
  *
- * 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.
+ * Examples:
+ *   "architect-codev-public"           → { type: 'architect', projectBasename: 'codev-public', roleId: null }
+ *   "builder-codevos_ai-0001"          → { type: 'builder', projectBasename: 'codevos_ai', roleId: '0001' }
+ *   "shell-codev-public-shell-1"       → { type: 'shell', projectBasename: 'codev-public', roleId: 'shell-1' }
  */
-async function reconcileTerminalSessions() {
-    const db = getGlobalDb();
-    let sessions;
+function parseTmuxSessionName(name) {
+    // architect-{basename}
+    const architectMatch = name.match(/^architect-(.+)$/);
+    if (architectMatch) {
+        return { type: 'architect', projectBasename: architectMatch[1], roleId: null };
+    }
+    // builder-{basename}-{specId} — specId is always the last segment (digits like "0001")
+    const builderMatch = name.match(/^builder-(.+)-(\d{4,})$/);
+    if (builderMatch) {
+        return { type: 'builder', projectBasename: builderMatch[1], roleId: builderMatch[2] };
+    }
+    // shell-{basename}-{shellId} — shellId is "shell-N" (last two segments)
+    const shellMatch = name.match(/^shell-(.+)-(shell-\d+)$/);
+    if (shellMatch) {
+        return { type: 'shell', projectBasename: shellMatch[1], roleId: shellMatch[2] };
+    }
+    return null;
+}
+/**
+ * List all tmux sessions that match codev naming conventions.
+ * Returns an array of { tmuxName, parsed } for each matching session.
+ */
+// Cache for listCodevTmuxSessions — avoid shelling out on every dashboard poll
+let _tmuxListCache = [];
+let _tmuxListCacheTime = 0;
+const TMUX_LIST_CACHE_TTL = 10_000; // 10 seconds
+function listCodevTmuxSessions(bypassCache = false) {
+    if (!tmuxAvailable)
+        return [];
+    const now = Date.now();
+    if (!bypassCache && now - _tmuxListCacheTime < TMUX_LIST_CACHE_TTL) {
+        return _tmuxListCache;
+    }
     try {
-        sessions = db.prepare('SELECT * FROM terminal_sessions').all();
+        const result = execSync('tmux list-sessions -F "#{session_name}" 2>/dev/null', { encoding: 'utf-8' });
+        const sessions = result.trim().split('\n').filter(Boolean);
+        const codevSessions = [];
+        for (const name of sessions) {
+            const parsed = parseTmuxSessionName(name);
+            if (parsed) {
+                codevSessions.push({ tmuxName: name, parsed });
+            }
+        }
+        _tmuxListCache = codevSessions;
+        _tmuxListCacheTime = now;
+        return codevSessions;
     }
-    catch (err) {
-        log('WARN', `Failed to read terminal sessions for reconciliation: ${err.message}`);
-        return;
+    catch {
+        _tmuxListCache = [];
+        _tmuxListCacheTime = now;
+        return [];
     }
-    if (sessions.length === 0) {
-        log('INFO', 'No terminal sessions to reconcile');
-        return;
+}
+/**
+ * Find the SQLite row that matches a given tmux session name.
+ * Looks up by tmux_session column directly.
+ */
+function findSqliteRowForTmuxSession(tmuxName) {
+    try {
+        const db = getGlobalDb();
+        return db.prepare('SELECT * FROM terminal_sessions WHERE tmux_session = ?').get(tmuxName) || null;
+    }
+    catch {
+        return null;
     }
-    log('INFO', `Reconciling ${sessions.length} terminal sessions from previous run...`);
+}
+/**
+ * Find the full project path for a tmux session's project basename.
+ * Checks known projects (terminal_sessions + in-memory cache) for a matching basename.
+ * Returns null if no match found.
+ */
+function resolveProjectPathFromBasename(projectBasename) {
+    const knownPaths = getKnownProjectPaths();
+    for (const projectPath of knownPaths) {
+        if (path.basename(projectPath) === projectBasename) {
+            return normalizeProjectPath(projectPath);
+        }
+    }
+    return null;
+}
+/**
+ * Reconcile terminal sessions on startup.
+ *
+ * DUAL-SOURCE STRATEGY (tmux + SQLite):
+ *
+ * tmux is the source of truth for LIVENESS (process existence).
+ * SQLite is the source of truth for METADATA (project association, type, role ID).
+ *
+ * This is intentional: tmux sessions survive Tower restarts because they are
+ * OS-level processes independent of Tower. SQLite rows, on the other hand,
+ * cannot track process liveness — a row may exist for a terminal whose process
+ * has long since exited. Therefore:
+ *   - We NEVER trust SQLite alone to determine if a terminal is running.
+ *   - We ALWAYS check tmux for liveness, then use SQLite for enrichment.
+ *
+ * File tabs are the exception: they have no backing process, so SQLite is
+ * the sole source of truth for their persistence (see file_tabs table).
+ *
+ * Phase 1 — tmux-first discovery:
+ *   List all codev tmux sessions. For each, look up SQLite for metadata.
+ *   If SQLite has a matching row → reconnect with full metadata.
+ *   If SQLite has no row (orphaned tmux) → derive metadata from session name, reconnect.
+ *
+ * Phase 2 — SQLite sweep:
+ *   Any SQLite rows not matched to a tmux session are stale → clean up.
+ *   (Also kills orphaned processes that have no tmux backing.)
+ */
+async function reconcileTerminalSessions() {
     const manager = getTerminalManager();
+    const db = getGlobalDb();
+    // Phase 1: Discover living tmux sessions (bypass cache on startup)
+    const liveTmuxSessions = listCodevTmuxSessions(/* bypassCache */ true);
+    // Track which SQLite rows we matched (by tmux_session name)
+    const matchedTmuxNames = new Set();
     let reconnected = 0;
-    let killed = 0;
-    let cleaned = 0;
-    for (const session of sessions) {
-        // 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)})`);
+    let orphanReconnected = 0;
+    if (liveTmuxSessions.length > 0) {
+        log('INFO', `Found ${liveTmuxSessions.length} live codev tmux session(s) — reconnecting...`);
+    }
+    for (const { tmuxName, parsed } of liveTmuxSessions) {
+        // Look up SQLite for this tmux session's metadata
+        const dbRow = findSqliteRowForTmuxSession(tmuxName);
+        matchedTmuxNames.add(tmuxName);
+        // Determine metadata — prefer SQLite, fall back to parsed name
+        const projectPath = dbRow?.project_path || resolveProjectPathFromBasename(parsed.projectBasename);
+        const type = dbRow?.type || parsed.type;
+        const roleId = dbRow?.role_id || parsed.roleId;
+        if (!projectPath) {
+            log('WARN', `Cannot resolve project path for tmux session "${tmuxName}" (basename: ${parsed.projectBasename}) — skipping`);
+            continue;
+        }
+        // Skip sessions whose project path doesn't exist on disk or is in a
+        // temp directory (left over from E2E tests that share global.db/tmux).
+        if (!fs.existsSync(projectPath)) {
+            log('INFO', `Skipping tmux "${tmuxName}" — project path no longer exists: ${projectPath}`);
+            killTmuxSession(tmuxName);
+            if (dbRow)
+                db.prepare('DELETE FROM terminal_sessions WHERE id = ?').run(dbRow.id);
+            continue;
+        }
+        const tmpDirs = ['/tmp', '/private/tmp', '/var/folders', '/private/var/folders'];
+        if (tmpDirs.some(d => projectPath.startsWith(d))) {
+            log('INFO', `Skipping tmux "${tmuxName}" — project is in temp directory: ${projectPath}`);
+            killTmuxSession(tmuxName);
+            if (dbRow)
+                db.prepare('DELETE FROM terminal_sessions WHERE id = ?').run(dbRow.id);
+            continue;
+        }
+        try {
+            const label = type === 'architect' ? 'Architect' : `${type} ${roleId || 'unknown'}`;
+            const newSession = await manager.createSession({
+                command: 'tmux',
+                args: ['attach-session', '-t', tmuxName],
+                cwd: projectPath,
+                label,
+            });
+            // Register in projectTerminals Map
+            const entry = getProjectTerminalsEntry(projectPath);
+            if (type === 'architect') {
+                entry.architect = newSession.id;
+            }
+            else if (type === 'builder') {
+                entry.builders.set(roleId || tmuxName, newSession.id);
+            }
+            else if (type === 'shell') {
+                entry.shells.set(roleId || tmuxName, newSession.id);
+            }
+            // Update SQLite: delete old row (if any), insert fresh one
+            if (dbRow) {
+                db.prepare('DELETE FROM terminal_sessions WHERE id = ?').run(dbRow.id);
+            }
+            saveTerminalSession(newSession.id, projectPath, type, roleId, newSession.pid, tmuxName);
+            if (dbRow) {
+                log('INFO', `Reconnected tmux "${tmuxName}" → terminal ${newSession.id} (${type} for ${path.basename(projectPath)})`);
                 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++;
+            else {
+                log('INFO', `Recovered orphaned tmux "${tmuxName}" → terminal ${newSession.id} (${type} for ${path.basename(projectPath)}) [no SQLite row]`);
+                orphanReconnected++;
             }
         }
-        // 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++;
+        catch (err) {
+            log('WARN', `Failed to reconnect to tmux "${tmuxName}": ${err.message}`);
+        }
+    }
+    // Phase 2: Sweep stale SQLite rows (those with no matching live tmux session)
+    let killed = 0;
+    let cleaned = 0;
+    let allDbSessions;
+    try {
+        allDbSessions = db.prepare('SELECT * FROM terminal_sessions').all();
+    }
+    catch (err) {
+        log('WARN', `Failed to read terminal sessions for sweep: ${err.message}`);
+        allDbSessions = [];
+    }
+    for (const session of allDbSessions) {
+        // Skip rows that were already reconnected in Phase 1
+        if (session.tmux_session && matchedTmuxNames.has(session.tmux_session)) {
+            continue;
+        }
+        // Also skip rows whose terminal is still alive in PtyManager
+        // (non-tmux sessions created during this Tower run)
+        const existing = manager.getSession(session.id);
+        if (existing && existing.status !== 'exited') {
+            continue;
         }
-        else if (session.pid && processExists(session.pid)) {
-            log('INFO', `Found orphaned process: PID ${session.pid} (${session.type} for ${path.basename(session.project_path)})`);
+        // Stale row — kill orphaned process if any, then delete
+        if (session.pid && processExists(session.pid)) {
+            log('INFO', `Killing orphaned process: PID ${session.pid} (${session.type} for ${path.basename(session.project_path)})`);
             try {
                 process.kill(session.pid, 'SIGTERM');
                 killed++;
             }
             catch {
-                // Process may not be killable (different user, etc)
+                // Process may not be killable
             }
         }
-        // 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: ${reconnected} reconnected, ${killed} orphaned killed, ${cleaned} cleaned up`);
+    const total = reconnected + orphanReconnected;
+    if (total > 0 || killed > 0 || cleaned > 0) {
+        log('INFO', `Reconciliation complete: ${reconnected} reconnected, ${orphanReconnected} orphan-recovered, ${killed} killed, ${cleaned} stale rows cleaned`);
+    }
+    else {
+        log('INFO', 'No terminal sessions to reconcile');
+    }
 }
 /**
  * Get terminal sessions from SQLite for a project.
@@ -526,8 +910,19 @@ async function gracefulShutdown(signal) {
         log('INFO', 'Shutting down terminal manager...');
         terminalManager.shutdown();
     }
-    // 4. Stop cloudflared tunnel if running
-    stopTunnel();
+    // 4. Stop gate watcher
+    if (gateWatcherInterval) {
+        clearInterval(gateWatcherInterval);
+        gateWatcherInterval = null;
+    }
+    // 5. Disconnect tunnel (Spec 0097 Phase 4)
+    stopMetadataRefresh();
+    stopConfigWatcher();
+    if (tunnelClient) {
+        log('INFO', 'Disconnecting tunnel...');
+        tunnelClient.disconnect();
+        tunnelClient = null;
+    }
     log('INFO', 'Graceful shutdown complete');
     process.exit(0);
 }
@@ -540,38 +935,26 @@ if (isNaN(port) || port < 1 || port > 65535) {
 }
 log('INFO', `Tower server starting on port ${port}`);
 /**
- * Load port allocations from SQLite database
+ * Get all known project paths from terminal_sessions and in-memory cache
  */
-function loadPortAllocations() {
+function getKnownProjectPaths() {
+    const projectPaths = new Set();
+    // From terminal_sessions table (persists across Tower restarts)
     try {
         const db = getGlobalDb();
-        return db.prepare('SELECT * FROM port_allocations ORDER BY last_used_at DESC').all();
+        const sessions = db.prepare('SELECT DISTINCT project_path FROM terminal_sessions').all();
+        for (const s of sessions) {
+            projectPaths.add(s.project_path);
+        }
     }
-    catch (err) {
-        log('ERROR', `Error loading port allocations: ${err.message}`);
-        return [];
+    catch {
+        // Table may not exist yet
     }
-}
-/**
- * Check if a port is listening
- */
-async function isPortListening(port) {
-    return new Promise((resolve) => {
-        const socket = new net.Socket();
-        socket.setTimeout(1000);
-        socket.on('connect', () => {
-            socket.destroy();
-            resolve(true);
-        });
-        socket.on('timeout', () => {
-            socket.destroy();
-            resolve(false);
-        });
-        socket.on('error', () => {
-            resolve(false);
-        });
-        socket.connect(port, '127.0.0.1');
-    });
+    // From in-memory cache (includes projects activated this session)
+    for (const [projectPath] of projectTerminals) {
+        projectPaths.add(projectPath);
+    }
+    return Array.from(projectPaths);
 }
 /**
  * Get project name from path
@@ -579,88 +962,22 @@ async function isPortListening(port) {
 function getProjectName(projectPath) {
     return path.basename(projectPath);
 }
-/**
- * Get the base port for a project from global.db
- * Returns null if project not found or not running
- */
-async function getBasePortForProject(projectPath) {
-    try {
-        const db = getGlobalDb();
-        const row = db.prepare('SELECT base_port FROM port_allocations WHERE project_path = ?').get(projectPath);
-        if (!row)
-            return null;
-        // Check if actually running
-        const isRunning = await isPortListening(row.base_port);
-        return isRunning ? row.base_port : null;
-    }
-    catch {
-        return null;
-    }
-}
-// Cloudflared tunnel management
-let tunnelProcess = null;
-let tunnelUrl = null;
-function isCloudflaredInstalled() {
-    try {
-        execSync('which cloudflared', { stdio: 'ignore' });
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-function getTunnelStatus() {
-    return {
-        available: isCloudflaredInstalled(),
-        running: tunnelProcess !== null && tunnelUrl !== null,
-        url: tunnelUrl,
-    };
-}
-async function startTunnel(port) {
-    if (!isCloudflaredInstalled()) {
-        return { success: false, error: 'cloudflared not installed. Install with: brew install cloudflared' };
-    }
-    if (tunnelProcess) {
-        return { success: true, url: tunnelUrl || undefined };
-    }
-    return new Promise((resolve) => {
-        tunnelProcess = spawn('cloudflared', ['tunnel', '--url', `http://localhost:${port}`], {
-            stdio: ['ignore', 'pipe', 'pipe'],
-        });
-        const handleOutput = (data) => {
-            const text = data.toString();
-            const match = text.match(/https:\/\/[a-z0-9-]+\.trycloudflare\.com/);
-            if (match && !tunnelUrl) {
-                tunnelUrl = match[0];
-                log('INFO', `Cloudflared tunnel started: ${tunnelUrl}`);
-                resolve({ success: true, url: tunnelUrl });
-            }
-        };
-        tunnelProcess.stdout?.on('data', handleOutput);
-        tunnelProcess.stderr?.on('data', handleOutput);
-        tunnelProcess.on('close', (code) => {
-            log('INFO', `Cloudflared tunnel closed with code ${code}`);
-            tunnelProcess = null;
-            tunnelUrl = null;
-        });
-        // Timeout after 30 seconds
-        setTimeout(() => {
-            if (!tunnelUrl) {
-                tunnelProcess?.kill();
-                tunnelProcess = null;
-                resolve({ success: false, error: 'Tunnel startup timed out' });
-            }
-        }, 30000);
-    });
-}
-function stopTunnel() {
-    if (tunnelProcess) {
-        tunnelProcess.kill();
-        tunnelProcess = null;
-        tunnelUrl = null;
-        log('INFO', 'Cloudflared tunnel stopped');
-    }
-    return { success: true };
+// Spec 0100: Gate watcher for af send notifications
+const gateWatcher = new GateWatcher(log);
+let gateWatcherInterval = null;
+function startGateWatcher() {
+    gateWatcherInterval = setInterval(async () => {
+        const projectPaths = getKnownProjectPaths();
+        for (const projectPath of projectPaths) {
+            try {
+                const gateStatus = getGateStatusForProject(projectPath);
+                await gateWatcher.checkAndNotify(gateStatus, projectPath);
+            }
+            catch (err) {
+                log('WARN', `Gate watcher error for ${projectPath}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }, 10_000);
 }
 const sseClients = [];
 let notificationIdCounter = 0;
@@ -680,37 +997,6 @@ function broadcastNotification(notification) {
         }
     }
 }
-/**
- * Get gate status for a project by querying its dashboard API.
- * Uses timeout to prevent hung projects from stalling tower status.
- */
-async function getGateStatusForProject(basePort) {
-    const controller = new AbortController();
-    const timeout = setTimeout(() => controller.abort(), 2000); // 2-second timeout
-    try {
-        const response = await fetch(`http://localhost:${basePort}/api/status`, {
-            signal: controller.signal,
-        });
-        clearTimeout(timeout);
-        if (!response.ok)
-            return { hasGate: false };
-        const projectStatus = await response.json();
-        // Check if any builder has a pending gate
-        const builderWithGate = projectStatus.builders?.find((b) => b.gateStatus?.waiting || b.status === 'gate-pending');
-        if (builderWithGate) {
-            return {
-                hasGate: true,
-                gateName: builderWithGate.gateStatus?.gateName || builderWithGate.currentGate,
-                builderId: builderWithGate.id,
-                timestamp: builderWithGate.gateStatus?.timestamp || Date.now(),
-            };
-        }
-    }
-    catch {
-        // Project dashboard not responding or timeout
-    }
-    return { hasGate: false };
-}
 /**
  * Get terminal list for a project from tower's registry.
  * Phase 4 (Spec 0090): Tower manages terminals directly, no dashboard-server fetch.
@@ -719,7 +1005,7 @@ async function getGateStatusForProject(basePort) {
 async function getTerminalsForProject(projectPath, proxyUrl) {
     const manager = getTerminalManager();
     const terminals = [];
-    // SQLite is authoritative - query it first (Spec 0090 requirement)
+    // Query SQLite first, then augment with tmux discovery
     const dbSessions = getTerminalSessionsForProject(projectPath);
     // Use normalized path for cache consistency
     const normalizedPath = normalizeProjectPath(projectPath);
@@ -728,30 +1014,35 @@ async function getTerminalsForProject(projectPath, proxyUrl) {
     // 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)
+    // Load file tabs from SQLite (persisted across restarts)
     const existingEntry = projectTerminals.get(normalizedPath);
-    if (existingEntry) {
+    if (existingEntry && existingEntry.fileTabs.size > 0) {
+        // Use in-memory state if already populated (avoids redundant DB reads)
         freshEntry.fileTabs = existingEntry.fileTabs;
     }
+    else {
+        freshEntry.fileTabs = loadFileTabsForProject(projectPath);
+    }
     for (const dbSession of dbSessions) {
         // Verify session still exists in TerminalManager (runtime state)
         let session = manager.getSession(dbSession.id);
-        if (!session && dbSession.tmux_session && tmuxAvailable && tmuxSessionExists(dbSession.tmux_session)) {
+        const sanitizedTmux = dbSession.tmux_session ? sanitizeTmuxSessionName(dbSession.tmux_session) : null;
+        if (!session && sanitizedTmux && tmuxAvailable && tmuxSessionExists(sanitizedTmux)) {
             // PTY session gone but tmux session survives — reconnect on-the-fly
             try {
                 const newSession = await manager.createSession({
                     command: 'tmux',
-                    args: ['attach-session', '-t', dbSession.tmux_session],
+                    args: ['attach-session', '-t', sanitizedTmux],
                     cwd: dbSession.project_path,
                     label: dbSession.type === 'architect' ? 'Architect' : `${dbSession.type} ${dbSession.role_id || dbSession.id}`,
                     env: process.env,
                 });
-                // Update SQLite with new terminal ID
+                // Update SQLite with new terminal ID (use sanitized tmux name)
                 deleteTerminalSession(dbSession.id);
-                saveTerminalSession(newSession.id, dbSession.project_path, dbSession.type, dbSession.role_id, newSession.pid, dbSession.tmux_session);
+                saveTerminalSession(newSession.id, dbSession.project_path, dbSession.type, dbSession.role_id, newSession.pid, sanitizedTmux);
                 dbSession.id = newSession.id;
                 session = manager.getSession(newSession.id);
-                log('INFO', `Reconnected to tmux "${dbSession.tmux_session}" on-the-fly → ${newSession.id}`);
+                log('INFO', `Reconnected to tmux "${sanitizedTmux}" on-the-fly → ${newSession.id}`);
             }
             catch (err) {
                 log('WARN', `Failed to reconnect to tmux "${dbSession.tmux_session}": ${err.message} — will retry on next poll`);
@@ -801,7 +1092,7 @@ async function getTerminalsForProject(projectPath, proxyUrl) {
     if (existingEntry) {
         if (existingEntry.architect && !freshEntry.architect) {
             const session = manager.getSession(existingEntry.architect);
-            if (session) {
+            if (session && session.status === 'running') {
                 freshEntry.architect = existingEntry.architect;
                 terminals.push({
                     type: 'architect',
@@ -815,7 +1106,7 @@ async function getTerminalsForProject(projectPath, proxyUrl) {
         for (const [builderId, terminalId] of existingEntry.builders) {
             if (!freshEntry.builders.has(builderId)) {
                 const session = manager.getSession(terminalId);
-                if (session) {
+                if (session && session.status === 'running') {
                     freshEntry.builders.set(builderId, terminalId);
                     terminals.push({
                         type: 'builder',
@@ -830,7 +1121,7 @@ async function getTerminalsForProject(projectPath, proxyUrl) {
         for (const [shellId, terminalId] of existingEntry.shells) {
             if (!freshEntry.shells.has(shellId)) {
                 const session = manager.getSession(terminalId);
-                if (session) {
+                if (session && session.status === 'running') {
                     freshEntry.shells.set(shellId, terminalId);
                     terminals.push({
                         type: 'shell',
@@ -843,11 +1134,57 @@ async function getTerminalsForProject(projectPath, proxyUrl) {
             }
         }
     }
+    // Phase 3: tmux discovery — find tmux sessions for this project that are
+    // missing from both SQLite and the in-memory cache.
+    // This is the safety net: if SQLite rows got deleted but tmux survived,
+    // the session will still appear in the dashboard.
+    const projectBasename = sanitizeTmuxSessionName(path.basename(normalizedPath));
+    const liveTmux = listCodevTmuxSessions();
+    for (const { tmuxName, parsed } of liveTmux) {
+        // Only process sessions whose sanitized project basename matches
+        if (parsed.projectBasename !== projectBasename)
+            continue;
+        // Skip if we already have this session registered (from SQLite or in-memory)
+        const alreadyRegistered = (parsed.type === 'architect' && freshEntry.architect) ||
+            (parsed.type === 'builder' && parsed.roleId && freshEntry.builders.has(parsed.roleId)) ||
+            (parsed.type === 'shell' && parsed.roleId && freshEntry.shells.has(parsed.roleId));
+        if (alreadyRegistered)
+            continue;
+        // Orphaned tmux session — reconnect it.
+        // Skip architect sessions: launchInstance handles architect creation/reconnection
+        // and has its own exit handler for auto-restart. Reconnecting here races with
+        // the restart logic and can attach to a dead tmux session.
+        if (parsed.type === 'architect')
+            continue;
+        try {
+            const label = `${parsed.type} ${parsed.roleId || 'unknown'}`;
+            const newSession = await manager.createSession({
+                command: 'tmux',
+                args: ['attach-session', '-t', tmuxName],
+                cwd: normalizedPath,
+                label,
+            });
+            const roleId = parsed.roleId;
+            if (parsed.type === 'builder' && roleId) {
+                freshEntry.builders.set(roleId, newSession.id);
+                terminals.push({ type: 'builder', id: roleId, label: `Builder ${roleId}`, url: `${proxyUrl}?tab=builder-${roleId}`, active: true });
+            }
+            else if (parsed.type === 'shell' && roleId) {
+                freshEntry.shells.set(roleId, newSession.id);
+                terminals.push({ type: 'shell', id: roleId, label: `Shell ${roleId.replace('shell-', '')}`, url: `${proxyUrl}?tab=shell-${roleId}`, active: true });
+            }
+            // Persist to SQLite so future polls find it directly
+            saveTerminalSession(newSession.id, normalizedPath, parsed.type, roleId, newSession.pid, tmuxName);
+            log('INFO', `[tmux-discovery] Recovered orphaned tmux "${tmuxName}" → ${newSession.id} (${parsed.type})`);
+        }
+        catch (err) {
+            log('WARN', `[tmux-discovery] Failed to recover tmux "${tmuxName}": ${err.message}`);
+        }
+    }
     // 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 };
+    // Read gate status from porch YAML files
+    const gateStatus = getGateStatusForProject(projectPath);
     return { terminals, gateStatus };
 }
 // Resolve once at module load: both symlinked and real temp dir paths
@@ -870,64 +1207,46 @@ function isTempDirectory(projectPath) {
  * Get all instances with their status
  */
 async function getInstances() {
-    const allocations = loadPortAllocations();
+    const knownPaths = getKnownProjectPaths();
     const instances = [];
-    for (const allocation of allocations) {
+    for (const projectPath of knownPaths) {
         // Skip builder worktrees - they're managed by their parent project
-        if (allocation.project_path.includes('/.builders/')) {
+        if (projectPath.includes('/.builders/')) {
             continue;
         }
         // Skip projects in temp directories (e.g. test artifacts) or whose directories no longer exist
-        if (!allocation.project_path.startsWith('remote:')) {
-            if (!fs.existsSync(allocation.project_path)) {
+        if (!projectPath.startsWith('remote:')) {
+            if (!fs.existsSync(projectPath)) {
                 continue;
             }
-            if (isTempDirectory(allocation.project_path)) {
+            if (isTempDirectory(projectPath)) {
                 continue;
             }
         }
-        const basePort = allocation.base_port;
-        const dashboardPort = basePort;
         // Encode project path for proxy URL
-        const encodedPath = Buffer.from(allocation.project_path).toString('base64url');
+        const encodedPath = Buffer.from(projectPath).toString('base64url');
         const proxyUrl = `/project/${encodedPath}/`;
         // Get terminals and gate status from tower's registry
         // Phase 4 (Spec 0090): Tower manages terminals directly - no separate dashboard server
-        const { terminals, gateStatus } = await getTerminalsForProject(allocation.project_path, proxyUrl);
+        const { terminals, gateStatus } = await getTerminalsForProject(projectPath, proxyUrl);
         // Project is active if it has any terminals (Phase 4: no port check needed)
         const isActive = terminals.length > 0;
-        const ports = [
-            {
-                type: 'Dashboard',
-                port: dashboardPort,
-                url: proxyUrl, // Use tower proxy URL, not raw localhost
-                active: isActive,
-            },
-        ];
         instances.push({
-            projectPath: allocation.project_path,
-            projectName: getProjectName(allocation.project_path),
-            basePort,
-            dashboardPort,
-            architectPort: basePort + 1, // Legacy field for backward compat
-            registered: allocation.registered_at,
-            lastUsed: allocation.last_used_at,
+            projectPath,
+            projectName: getProjectName(projectPath),
             running: isActive,
-            proxyUrl, // Tower proxy URL for dashboard
-            architectUrl: `${proxyUrl}?tab=architect`, // Direct URL to architect terminal
-            terminals, // All available terminals
-            ports,
+            proxyUrl,
+            architectUrl: `${proxyUrl}?tab=architect`,
+            terminals,
             gateStatus,
         });
     }
-    // Sort: running first, then by last used (most recent first)
+    // Sort: running first, then by project name
     instances.sort((a, b) => {
         if (a.running !== b.running) {
             return a.running ? -1 : 1;
         }
-        const aTime = a.lastUsed ? new Date(a.lastUsed).getTime() : 0;
-        const bTime = b.lastUsed ? new Date(b.lastUsed).getTime() : 0;
-        return bTime - aTime;
+        return a.projectName.localeCompare(b.projectName);
     });
     return instances;
 }
@@ -943,6 +1262,10 @@ async function getDirectorySuggestions(inputPath) {
     if (inputPath.startsWith('~')) {
         inputPath = inputPath.replace('~', homedir());
     }
+    // Relative paths are meaningless for the tower daemon — only absolute paths
+    if (!path.isAbsolute(inputPath)) {
+        return [];
+    }
     // Determine the directory to list and the prefix to filter by
     let dirToList;
     let prefix;
@@ -996,8 +1319,6 @@ async function getDirectorySuggestions(inputPath) {
  * Auto-adopts non-codev directories and creates architect terminal
  */
 async function launchInstance(projectPath) {
-    // Clean up stale port allocations before launching (handles machine restarts)
-    cleanupStaleEntries();
     // Validate path exists
     if (!fs.existsSync(projectPath)) {
         return { success: false, error: `Path does not exist: ${projectPath}` };
@@ -1028,38 +1349,8 @@ async function launchInstance(projectPath) {
     // Phase 4 (Spec 0090): Tower manages terminals directly
     // No dashboard-server spawning - tower handles everything
     try {
-        // Clear any stale state file
-        const stateFile = path.join(projectPath, '.agent-farm', 'state.json');
-        if (fs.existsSync(stateFile)) {
-            try {
-                fs.unlinkSync(stateFile);
-            }
-            catch {
-                // Ignore - file might not exist or be locked
-            }
-        }
         // Ensure project has port allocation
         const resolvedPath = fs.realpathSync(projectPath);
-        const db = getGlobalDb();
-        let allocation = db
-            .prepare('SELECT base_port FROM port_allocations WHERE project_path = ? OR project_path = ?')
-            .get(projectPath, resolvedPath);
-        if (!allocation) {
-            // Allocate a new port for this project
-            // Find the next available port block (starting at 4200, incrementing by 100)
-            const existingPorts = db
-                .prepare('SELECT base_port FROM port_allocations ORDER BY base_port')
-                .all();
-            let nextPort = 4200;
-            for (const { base_port } of existingPorts) {
-                if (base_port >= nextPort) {
-                    nextPort = base_port + 100;
-                }
-            }
-            db.prepare("INSERT INTO port_allocations (project_path, project_name, base_port, created_at) VALUES (?, ?, ?, datetime('now'))").run(resolvedPath, path.basename(projectPath), nextPort);
-            allocation = { base_port: nextPort };
-            log('INFO', `Allocated port ${nextPort} for project: ${projectPath}`);
-        }
         // Initialize project terminal entry
         const entry = getProjectTerminalsEntry(resolvedPath);
         // Create architect terminal if not already present
@@ -1086,14 +1377,26 @@ async function launchInstance(projectPath) {
                 let cmdArgs = cmdParts.slice(1);
                 // Wrap in tmux for session persistence across Tower restarts
                 const tmuxName = `architect-${path.basename(projectPath)}`;
+                const sanitizedTmuxName = sanitizeTmuxSessionName(tmuxName);
                 let activeTmuxSession = null;
                 if (tmuxAvailable) {
-                    const tmuxCreated = createTmuxSession(tmuxName, cmd, cmdArgs, projectPath, 200, 50);
-                    if (tmuxCreated) {
+                    // Reuse existing tmux session if it's still alive (e.g., after
+                    // disconnect timeout killed the `tmux attach` process but the
+                    // architect process inside tmux kept running).
+                    if (tmuxSessionExists(sanitizedTmuxName)) {
                         cmd = 'tmux';
-                        cmdArgs = ['attach-session', '-t', tmuxName];
-                        activeTmuxSession = tmuxName;
-                        log('INFO', `Created tmux session "${tmuxName}" for architect`);
+                        cmdArgs = ['attach-session', '-t', sanitizedTmuxName];
+                        activeTmuxSession = sanitizedTmuxName;
+                        log('INFO', `Reconnecting to existing tmux session "${sanitizedTmuxName}" for architect`);
+                    }
+                    else {
+                        const createdName = createTmuxSession(tmuxName, cmd, cmdArgs, projectPath, 200, 50);
+                        if (createdName) {
+                            cmd = 'tmux';
+                            cmdArgs = ['attach-session', '-t', createdName];
+                            activeTmuxSession = createdName;
+                            log('INFO', `Created tmux session "${createdName}" for architect`);
+                        }
                     }
                 }
                 const session = await manager.createSession({
@@ -1106,19 +1409,30 @@ async function launchInstance(projectPath) {
                 entry.architect = session.id;
                 // TICK-001: Save to SQLite for persistence (with tmux session name)
                 saveTerminalSession(session.id, resolvedPath, 'architect', null, session.pid, activeTmuxSession);
-                // Auto-restart architect on exit (restored from pre-Phase 4 dashboard-server.ts)
+                // Auto-restart architect on exit
                 const ptySession = manager.getSession(session.id);
                 if (ptySession) {
                     const startedAt = Date.now();
                     ptySession.on('exit', () => {
-                        entry.architect = undefined;
+                        // Re-read entry from the Map — getTerminalsForProject() periodically
+                        // replaces the Map entry with a fresh object, so the `entry` captured
+                        // in the closure may be stale.
+                        const currentEntry = getProjectTerminalsEntry(resolvedPath);
+                        if (currentEntry.architect === session.id) {
+                            currentEntry.architect = undefined;
+                        }
                         deleteTerminalSession(session.id);
-                        // Kill stale tmux session so restart can create a fresh one
-                        if (activeTmuxSession) {
-                            try {
-                                execSync(`tmux kill-session -t "${activeTmuxSession}" 2>/dev/null`, { stdio: 'ignore' });
-                            }
-                            catch { /* already gone */ }
+                        // Check if the tmux session's inner process is still alive.
+                        // The node-pty process is `tmux attach` — it exits on disconnect
+                        // timeout, but the tmux session (and the architect process inside
+                        // it) may still be running. Only kill tmux if the inner process
+                        // has also exited (e.g., user typed "exit" or process crashed).
+                        const tmuxAlive = activeTmuxSession && tmuxSessionExists(activeTmuxSession);
+                        if (activeTmuxSession && !tmuxAlive) {
+                            log('INFO', `Tmux session "${activeTmuxSession}" already gone for ${projectPath}`);
+                        }
+                        else if (tmuxAlive) {
+                            log('INFO', `Tmux session "${activeTmuxSession}" still alive for ${projectPath}, preserving for reconnect`);
                         }
                         // Only restart if the architect ran for at least 5s (prevents crash loops)
                         const uptime = Date.now() - startedAt;
@@ -1126,6 +1440,12 @@ async function launchInstance(projectPath) {
                             log('INFO', `Architect exited after ${uptime}ms for ${projectPath}, not restarting (too short)`);
                             return;
                         }
+                        // Kill the stale tmux session so launchInstance creates a fresh one
+                        // instead of reconnecting to the dead session.
+                        if (activeTmuxSession && tmuxSessionExists(activeTmuxSession)) {
+                            killTmuxSession(activeTmuxSession);
+                            log('INFO', `Killed stale tmux session "${activeTmuxSession}" before restart`);
+                        }
                         log('INFO', `Architect exited for ${projectPath}, restarting in 2s...`);
                         setTimeout(() => {
                             launchInstance(projectPath).catch((err) => {
@@ -1234,7 +1554,6 @@ const templatePath = findTemplatePath();
 // WebSocket server for terminal connections (Phase 2 - Spec 0090)
 let terminalWss = null;
 // React dashboard dist path (for serving directly from tower)
-// React dashboard dist path (for serving directly from tower)
 // Phase 4 (Spec 0090): Tower serves everything directly, no dashboard-server
 const reactDashboardPath = path.resolve(__dirname, '../../../dashboard/dist');
 const hasReactDashboard = fs.existsSync(reactDashboardPath);
@@ -1320,17 +1639,77 @@ const server = http.createServer(async (req, res) => {
             }));
             return;
         }
+        // =========================================================================
+        // Tunnel Management Endpoints (Spec 0097 Phase 4)
+        // =========================================================================
+        // POST /api/tunnel/connect — Connect or reconnect tunnel to codevos.ai
+        if (req.method === 'POST' && url.pathname === '/api/tunnel/connect') {
+            try {
+                const config = readCloudConfig();
+                if (!config) {
+                    res.writeHead(400, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ success: false, error: 'Not registered. Run \'af tower register\' first.' }));
+                    return;
+                }
+                // Reset circuit breaker if in auth_failed state
+                if (tunnelClient)
+                    tunnelClient.resetCircuitBreaker();
+                const client = await connectTunnel(config);
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ success: true, state: client.getState() }));
+            }
+            catch (err) {
+                log('ERROR', `Tunnel connect failed: ${err.message}`);
+                res.writeHead(500, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ success: false, error: err.message }));
+            }
+            return;
+        }
+        // POST /api/tunnel/disconnect — Disconnect tunnel from codevos.ai
+        if (req.method === 'POST' && url.pathname === '/api/tunnel/disconnect') {
+            if (tunnelClient) {
+                tunnelClient.disconnect();
+                tunnelClient = null;
+            }
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: true }));
+            return;
+        }
+        // GET /api/tunnel/status — Return tunnel connection status
+        if (req.method === 'GET' && url.pathname === '/api/tunnel/status') {
+            let config = null;
+            try {
+                config = readCloudConfig();
+            }
+            catch {
+                // Config file may be corrupted — treat as unregistered
+            }
+            const state = tunnelClient?.getState() ?? 'disconnected';
+            const uptime = tunnelClient?.getUptime() ?? null;
+            const response = {
+                registered: config !== null,
+                state,
+                uptime,
+            };
+            if (config) {
+                response.towerId = config.tower_id;
+                response.towerName = config.tower_name;
+                response.serverUrl = config.server_url;
+                response.accessUrl = `${config.server_url}/t/${config.tower_name}/`;
+            }
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify(response));
+            return;
+        }
         // API: List all projects (Spec 0090 Phase 1)
         if (req.method === 'GET' && url.pathname === '/api/projects') {
             const instances = await getInstances();
             const projects = instances.map((i) => ({
                 path: i.projectPath,
                 name: i.projectName,
-                basePort: i.basePort,
                 active: i.running,
                 proxyUrl: i.proxyUrl,
                 terminals: i.terminals.length,
-                lastUsed: i.lastUsed,
             }));
             res.writeHead(200, { 'Content-Type': 'application/json' });
             res.end(JSON.stringify({ projects }));
@@ -1369,7 +1748,6 @@ const server = http.createServer(async (req, res) => {
                     path: instance.projectPath,
                     name: instance.projectName,
                     active: instance.running,
-                    basePort: instance.basePort,
                     terminals: instance.terminals,
                     gateStatus: instance.gateStatus,
                 }));
@@ -1397,11 +1775,11 @@ const server = http.createServer(async (req, res) => {
             }
             // POST /api/projects/:path/deactivate
             if (req.method === 'POST' && action === 'deactivate') {
-                // Check if project exists in port allocations
-                const allocations = loadPortAllocations();
+                // Check if project is known (has terminals or sessions)
+                const knownPaths = getKnownProjectPaths();
                 const resolvedPath = fs.existsSync(projectPath) ? fs.realpathSync(projectPath) : projectPath;
-                const allocation = allocations.find((a) => a.project_path === projectPath || a.project_path === resolvedPath);
-                if (!allocation) {
+                const isKnown = knownPaths.some((p) => p === projectPath || p === resolvedPath);
+                if (!isKnown) {
                     res.writeHead(404, { 'Content-Type': 'application/json' });
                     res.end(JSON.stringify({ ok: false, error: 'Project not found' }));
                     return;
@@ -1433,13 +1811,13 @@ const server = http.createServer(async (req, res) => {
                 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
+                    const sanitizedName = createTmuxSession(tmuxSession, command, args || [], cwd, cols || 200, rows || 50);
+                    if (sanitizedName) {
+                        // Override: node-pty attaches to the tmux session (use sanitized name)
                         command = 'tmux';
-                        args = ['attach-session', '-t', tmuxSession];
-                        activeTmuxSession = tmuxSession;
-                        log('INFO', `Created tmux session "${tmuxSession}" for terminal`);
+                        args = ['attach-session', '-t', sanitizedName];
+                        activeTmuxSession = sanitizedName;
+                        log('INFO', `Created tmux session "${sanitizedName}" for terminal`);
                     }
                     // If tmux creation failed, fall through to bare node-pty
                 }
@@ -1699,52 +2077,39 @@ const server = http.createServer(async (req, res) => {
         // API: Launch new instance
         if (req.method === 'POST' && url.pathname === '/api/launch') {
             const body = await parseJsonBody(req);
-            const projectPath = body.projectPath;
+            let projectPath = body.projectPath;
             if (!projectPath) {
                 res.writeHead(400, { 'Content-Type': 'application/json' });
                 res.end(JSON.stringify({ success: false, error: 'Missing projectPath' }));
                 return;
             }
+            // Expand ~ to home directory
+            if (projectPath.startsWith('~')) {
+                projectPath = projectPath.replace('~', homedir());
+            }
+            // Reject relative paths — tower daemon CWD is unpredictable
+            if (!path.isAbsolute(projectPath)) {
+                res.writeHead(400, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({
+                    success: false,
+                    error: `Relative paths are not supported. Use an absolute path (e.g., /Users/.../project or ~/Development/project).`,
+                }));
+                return;
+            }
+            // Normalize path (resolve .. segments, trailing slashes)
+            projectPath = path.resolve(projectPath);
             const result = await launchInstance(projectPath);
             res.writeHead(result.success ? 200 : 400, { 'Content-Type': 'application/json' });
             res.end(JSON.stringify(result));
             return;
         }
-        // API: Get tunnel status (cloudflared availability and running tunnel)
-        if (req.method === 'GET' && url.pathname === '/api/tunnel/status') {
-            const status = getTunnelStatus();
-            res.writeHead(200, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify(status));
-            return;
-        }
-        // API: Start cloudflared tunnel
-        if (req.method === 'POST' && url.pathname === '/api/tunnel/start') {
-            const result = await startTunnel(port);
-            res.writeHead(200, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify(result));
-            return;
-        }
-        // API: Stop cloudflared tunnel
-        if (req.method === 'POST' && url.pathname === '/api/tunnel/stop') {
-            const result = stopTunnel();
-            res.writeHead(200, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify(result));
-            return;
-        }
         // API: Stop an instance
-        // Phase 4 (Spec 0090): Accept projectPath or basePort for backwards compat
         if (req.method === 'POST' && url.pathname === '/api/stop') {
             const body = await parseJsonBody(req);
-            let targetPath = body.projectPath;
-            // Backwards compat: if basePort provided, find the project path
-            if (!targetPath && body.basePort) {
-                const allocations = loadPortAllocations();
-                const allocation = allocations.find((a) => a.base_port === body.basePort);
-                targetPath = allocation?.project_path || '';
-            }
+            const targetPath = body.projectPath;
             if (!targetPath) {
                 res.writeHead(400, { 'Content-Type': 'application/json' });
-                res.end(JSON.stringify({ success: false, error: 'Missing projectPath or basePort' }));
+                res.end(JSON.stringify({ success: false, error: 'Missing projectPath' }));
                 return;
             }
             const result = await stopInstance(targetPath);
@@ -1779,8 +2144,8 @@ const server = http.createServer(async (req, res) => {
             const encodedPath = pathParts[2];
             const subPath = pathParts.slice(3).join('/');
             if (!encodedPath) {
-                res.writeHead(400, { 'Content-Type': 'text/plain' });
-                res.end('Missing project path');
+                res.writeHead(400, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: 'Missing project path' }));
                 return;
             }
             // Decode Base64URL (RFC 4648)
@@ -1795,11 +2160,10 @@ const server = http.createServer(async (req, res) => {
                 projectPath = normalizeProjectPath(projectPath);
             }
             catch {
-                res.writeHead(400, { 'Content-Type': 'text/plain' });
-                res.end('Invalid project path encoding');
+                res.writeHead(400, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: 'Invalid project path encoding' }));
                 return;
             }
-            const basePort = await getBasePortForProject(projectPath);
             // Phase 4 (Spec 0090): Tower handles everything directly
             const isApiCall = subPath.startsWith('api/') || subPath === 'api';
             const isWsPath = subPath.startsWith('ws/') || subPath === 'ws';
@@ -1854,66 +2218,64 @@ const server = http.createServer(async (req, res) => {
                 const apiPath = subPath.replace(/^api\/?/, '');
                 // GET /api/state - Return project state (architect, builders, shells)
                 if (req.method === 'GET' && (apiPath === 'state' || apiPath === '')) {
+                    // Refresh cache via getTerminalsForProject (handles SQLite sync,
+                    // tmux reconnection, and tmux discovery in one place)
+                    const encodedPath = Buffer.from(projectPath).toString('base64url');
+                    const proxyUrl = `/project/${encodedPath}/`;
+                    const { gateStatus } = await getTerminalsForProject(projectPath, proxyUrl);
+                    // Now read from the refreshed cache
                     const entry = getProjectTerminalsEntry(projectPath);
                     const manager = getTerminalManager();
-                    // Build state response compatible with React dashboard
                     const state = {
                         architect: null,
                         builders: [],
                         utils: [],
                         annotations: [],
                         projectName: path.basename(projectPath),
+                        gateStatus,
                     };
                     // Add architect if exists
                     if (entry.architect) {
                         const session = manager.getSession(entry.architect);
-                        state.architect = {
-                            port: basePort || 0,
-                            pid: session?.pid || 0,
-                            terminalId: entry.architect,
-                        };
+                        if (session) {
+                            state.architect = {
+                                port: 0,
+                                pid: session.pid || 0,
+                                terminalId: entry.architect,
+                            };
+                        }
                     }
-                    // Add shells (skip stale entries whose terminal session is gone or exited)
-                    const staleShellIds = [];
+                    // Add shells from refreshed cache
                     for (const [shellId, terminalId] of entry.shells) {
                         const session = manager.getSession(terminalId);
-                        if (!session || session.status === 'exited') {
-                            staleShellIds.push(shellId);
-                            continue;
+                        if (session) {
+                            state.utils.push({
+                                id: shellId,
+                                name: `Shell ${shellId.replace('shell-', '')}`,
+                                port: 0,
+                                pid: session.pid || 0,
+                                terminalId,
+                            });
                         }
-                        state.utils.push({
-                            id: shellId,
-                            name: `Shell ${shellId.replace('shell-', '')}`,
-                            port: basePort || 0,
-                            pid: session?.pid || 0,
-                            terminalId,
-                        });
                     }
-                    for (const id of staleShellIds)
-                        entry.shells.delete(id);
-                    // Add builders (skip stale entries whose terminal session is gone or exited)
-                    const staleBuilderIds = [];
+                    // Add builders from refreshed cache
                     for (const [builderId, terminalId] of entry.builders) {
                         const session = manager.getSession(terminalId);
-                        if (!session || session.status === 'exited') {
-                            staleBuilderIds.push(builderId);
-                            continue;
+                        if (session) {
+                            state.builders.push({
+                                id: builderId,
+                                name: `Builder ${builderId}`,
+                                port: 0,
+                                pid: session.pid || 0,
+                                status: 'running',
+                                phase: '',
+                                worktree: '',
+                                branch: '',
+                                type: 'spec',
+                                terminalId,
+                            });
                         }
-                        state.builders.push({
-                            id: builderId,
-                            name: `Builder ${builderId}`,
-                            port: basePort || 0,
-                            pid: session?.pid || 0,
-                            status: 'running',
-                            phase: '',
-                            worktree: '',
-                            branch: '',
-                            type: 'spec',
-                            terminalId,
-                        });
                     }
-                    for (const id of staleBuilderIds)
-                        entry.builders.delete(id);
                     // Add file tabs (Spec 0092 - served through Tower, no separate ports)
                     for (const [tabId, tab] of entry.fileTabs) {
                         state.annotations.push({
@@ -1938,11 +2300,11 @@ const server = http.createServer(async (req, res) => {
                         const tmuxName = `shell-${path.basename(projectPath)}-${shellId}`;
                         let activeTmuxSession = null;
                         if (tmuxAvailable) {
-                            const tmuxCreated = createTmuxSession(tmuxName, shellCmd, shellArgs, projectPath, 200, 50);
-                            if (tmuxCreated) {
+                            const sanitizedName = createTmuxSession(tmuxName, shellCmd, shellArgs, projectPath, 200, 50);
+                            if (sanitizedName) {
                                 shellCmd = 'tmux';
-                                shellArgs = ['attach-session', '-t', tmuxName];
-                                activeTmuxSession = tmuxName;
+                                shellArgs = ['attach-session', '-t', sanitizedName];
+                                activeTmuxSession = sanitizedName;
                             }
                         }
                         // Create terminal session
@@ -1961,7 +2323,7 @@ const server = http.createServer(async (req, res) => {
                         res.writeHead(200, { 'Content-Type': 'application/json' });
                         res.end(JSON.stringify({
                             id: shellId,
-                            port: basePort || 0,
+                            port: 0,
                             name: `Shell ${shellId.replace('shell-', '')}`,
                             terminalId: session.id,
                         }));
@@ -1981,45 +2343,79 @@ const server = http.createServer(async (req, res) => {
                             req.on('data', (chunk) => data += chunk.toString());
                             req.on('end', () => resolve(data));
                         });
-                        const { path: filePath, line } = JSON.parse(body || '{}');
+                        const { path: filePath, line, terminalId } = 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)) {
+                        // Resolve path: use terminal's cwd for relative paths when terminalId is provided
+                        let fullPath;
+                        if (path.isAbsolute(filePath)) {
+                            fullPath = filePath;
+                        }
+                        else if (terminalId) {
+                            const manager = getTerminalManager();
+                            const session = manager.getSession(terminalId);
+                            if (session) {
+                                fullPath = path.join(session.cwd, filePath);
+                            }
+                            else {
+                                log('WARN', `Terminal session ${terminalId} not found, falling back to project root`);
+                                fullPath = path.join(projectPath, filePath);
+                            }
+                        }
+                        else {
+                            fullPath = path.join(projectPath, filePath);
+                        }
+                        // Security: symlink-aware containment check
+                        // For non-existent files, resolve the parent directory to handle
+                        // intermediate symlinks (e.g., /tmp -> /private/tmp on macOS).
+                        let resolvedPath;
+                        try {
+                            resolvedPath = fs.realpathSync(fullPath);
+                        }
+                        catch {
+                            try {
+                                resolvedPath = path.join(fs.realpathSync(path.dirname(fullPath)), path.basename(fullPath));
+                            }
+                            catch {
+                                resolvedPath = path.resolve(fullPath);
+                            }
+                        }
+                        let normalizedProject;
+                        try {
+                            normalizedProject = fs.realpathSync(projectPath);
+                        }
+                        catch {
+                            normalizedProject = path.resolve(projectPath);
+                        }
+                        const isWithinProject = resolvedPath.startsWith(normalizedProject + path.sep)
+                            || resolvedPath === normalizedProject;
+                        if (!isWithinProject) {
                             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;
-                        }
+                        // Non-existent files still create a tab (spec 0101: file viewer shows "File not found")
+                        const fileExists = fs.existsSync(fullPath);
                         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 }));
+                                res.end(JSON.stringify({ id, existing: true, line, notFound: !fileExists }));
                                 return;
                             }
                         }
-                        // Create new file tab
-                        const id = `file-${Date.now().toString(36)}`;
-                        entry.fileTabs.set(id, { id, path: fullPath, createdAt: Date.now() });
+                        // Create new file tab (write-through: in-memory + SQLite)
+                        const id = `file-${crypto.randomUUID()}`;
+                        const createdAt = Date.now();
+                        entry.fileTabs.set(id, { id, path: fullPath, createdAt });
+                        saveFileTab(id, projectPath, fullPath, createdAt);
                         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 }));
+                        res.end(JSON.stringify({ id, existing: false, line, notFound: !fileExists }));
                     }
                     catch (err) {
                         log('ERROR', `Failed to create file tab: ${err.message}`);
@@ -2074,6 +2470,7 @@ const server = http.createServer(async (req, res) => {
                         }
                     }
                     catch (err) {
+                        log('ERROR', `GET /api/file/:id failed: ${err.message}`);
                         res.writeHead(500, { 'Content-Type': 'application/json' });
                         res.end(JSON.stringify({ error: err.message }));
                     }
@@ -2086,8 +2483,8 @@ const server = http.createServer(async (req, res) => {
                     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');
+                        res.writeHead(404, { 'Content-Type': 'application/json' });
+                        res.end(JSON.stringify({ error: 'File tab not found' }));
                         return;
                     }
                     try {
@@ -2101,8 +2498,9 @@ const server = http.createServer(async (req, res) => {
                         res.end(data);
                     }
                     catch (err) {
-                        res.writeHead(500, { 'Content-Type': 'text/plain' });
-                        res.end(err.message);
+                        log('ERROR', `GET /api/file/:id/raw failed: ${err.message}`);
+                        res.writeHead(500, { 'Content-Type': 'application/json' });
+                        res.end(JSON.stringify({ error: err.message }));
                     }
                     return;
                 }
@@ -2135,6 +2533,7 @@ const server = http.createServer(async (req, res) => {
                         res.end(JSON.stringify({ success: true }));
                     }
                     catch (err) {
+                        log('ERROR', `POST /api/file/:id/save failed: ${err.message}`);
                         res.writeHead(500, { 'Content-Type': 'application/json' });
                         res.end(JSON.stringify({ error: err.message }));
                     }
@@ -2146,10 +2545,11 @@ const server = http.createServer(async (req, res) => {
                     const tabId = deleteMatch[1];
                     const entry = getProjectTerminalsEntry(projectPath);
                     const manager = getTerminalManager();
-                    // Check if it's a file tab first (Spec 0092)
+                    // Check if it's a file tab first (Spec 0092, write-through: in-memory + SQLite)
                     if (tabId.startsWith('file-')) {
                         if (entry.fileTabs.has(tabId)) {
                             entry.fileTabs.delete(tabId);
+                            deleteFileTab(tabId);
                             log('INFO', `Deleted file tab: ${tabId}`);
                             res.writeHead(204);
                             res.end();
@@ -2289,7 +2689,8 @@ const server = http.createServer(async (req, res) => {
                         res.end(JSON.stringify({ modified, staged, untracked }));
                     }
                     catch (err) {
-                        // Not a git repo or git command failed
+                        // Not a git repo or git command failed — return graceful degradation with error field
+                        log('WARN', `GET /api/git/status failed: ${err.message}`);
                         res.writeHead(200, { 'Content-Type': 'application/json' });
                         res.end(JSON.stringify({ modified: [], staged: [], untracked: [], error: err.message }));
                     }
@@ -2320,8 +2721,8 @@ const server = http.createServer(async (req, res) => {
                     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');
+                        res.writeHead(404, { 'Content-Type': 'application/json' });
+                        res.end(JSON.stringify({ error: 'File tab not found' }));
                         return;
                     }
                     const filePath = tab.path;
@@ -2339,8 +2740,9 @@ const server = http.createServer(async (req, res) => {
                             res.end(content);
                         }
                         catch (err) {
-                            res.writeHead(500, { 'Content-Type': 'text/plain' });
-                            res.end(err.message);
+                            log('ERROR', `GET /api/annotate/:id/file failed: ${err.message}`);
+                            res.writeHead(500, { 'Content-Type': 'application/json' });
+                            res.end(JSON.stringify({ error: err.message }));
                         }
                         return;
                     }
@@ -2364,8 +2766,9 @@ const server = http.createServer(async (req, res) => {
                             res.end(JSON.stringify({ ok: true }));
                         }
                         catch (err) {
-                            res.writeHead(500, { 'Content-Type': 'text/plain' });
-                            res.end(err.message);
+                            log('ERROR', `POST /api/annotate/:id/save failed: ${err.message}`);
+                            res.writeHead(500, { 'Content-Type': 'application/json' });
+                            res.end(JSON.stringify({ error: err.message }));
                         }
                         return;
                     }
@@ -2377,8 +2780,9 @@ const server = http.createServer(async (req, res) => {
                             res.end(JSON.stringify({ mtime: stat.mtimeMs }));
                         }
                         catch (err) {
-                            res.writeHead(500, { 'Content-Type': 'text/plain' });
-                            res.end(err.message);
+                            log('ERROR', `GET /api/annotate/:id/api/mtime failed: ${err.message}`);
+                            res.writeHead(500, { 'Content-Type': 'application/json' });
+                            res.end(JSON.stringify({ error: err.message }));
                         }
                         return;
                     }
@@ -2395,8 +2799,9 @@ const server = http.createServer(async (req, res) => {
                             res.end(data);
                         }
                         catch (err) {
-                            res.writeHead(500, { 'Content-Type': 'text/plain' });
-                            res.end(err.message);
+                            log('ERROR', `GET /api/annotate/:id/${subRoute} failed: ${err.message}`);
+                            res.writeHead(500, { 'Content-Type': 'application/json' });
+                            res.end(JSON.stringify({ error: err.message }));
                         }
                         return;
                     }
@@ -2484,8 +2889,8 @@ const server = http.createServer(async (req, res) => {
     }
     catch (err) {
         log('ERROR', `Request error: ${err.message}`);
-        res.writeHead(500, { 'Content-Type': 'text/plain' });
-        res.end('Internal server error: ' + err.message);
+        res.writeHead(500, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: err.message }));
     }
 });
 // SECURITY: Bind to localhost only to prevent network exposure
@@ -2496,6 +2901,25 @@ server.listen(port, '127.0.0.1', async () => {
     log('INFO', `tmux available: ${tmuxAvailable}${tmuxAvailable ? '' : ' (terminals will not persist across restarts)'}`);
     // TICK-001: Reconcile terminal sessions from previous run
     await reconcileTerminalSessions();
+    // Spec 0100: Start background gate watcher for af send notifications
+    startGateWatcher();
+    log('INFO', 'Gate watcher started (10s poll interval)');
+    // Spec 0097 Phase 4: Auto-connect tunnel if registered
+    try {
+        const config = readCloudConfig();
+        if (config) {
+            log('INFO', `Cloud config found, connecting tunnel (tower: ${config.tower_name}, key: ${maskApiKey(config.api_key)})`);
+            await connectTunnel(config);
+        }
+        else {
+            log('INFO', 'No cloud config found, operating in local-only mode');
+        }
+    }
+    catch (err) {
+        log('WARN', `Failed to read cloud config: ${err.message}. Operating in local-only mode.`);
+    }
+    // Start watching cloud-config.json for changes
+    startConfigWatcher();
 });
 // Initialize terminal WebSocket server (Phase 2 - Spec 0090)
 terminalWss = new WebSocketServer({ noServer: true });