upfynai-code 2.9.1 → 2.9.2

package/server/index.js

@@ -0,0 +1,3799 @@
+#!/usr/bin/env node
+// Load environment variables before other imports execute
+import './load-env.js';
+
+// Strip Claude Code session markers so spawned CLI processes don't fail with
+// "cannot be launched inside another Claude Code session" errors.
+delete process.env.CLAUDECODE;
+delete process.env.CLAUDE_CODE;
+import crypto from 'crypto';
+import fs from 'fs';
+import path from 'path';
+import jwt from 'jsonwebtoken';
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Read version from package.json at startup
+const SERVER_VERSION = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8')).version;
+
+// ANSI color codes for terminal output
+const colors = {
+    reset: '\x1b[0m',
+    bright: '\x1b[1m',
+    cyan: '\x1b[36m',
+    green: '\x1b[32m',
+    yellow: '\x1b[33m',
+    blue: '\x1b[34m',
+    dim: '\x1b[2m',
+};
+
+const c = {
+    info: (text) => `${colors.cyan}${text}${colors.reset}`,
+    ok: (text) => `${colors.green}${text}${colors.reset}`,
+    warn: (text) => `${colors.yellow}${text}${colors.reset}`,
+    tip: (text) => `${colors.blue}${text}${colors.reset}`,
+    bright: (text) => `${colors.bright}${text}${colors.reset}`,
+    dim: (text) => `${colors.dim}${text}${colors.reset}`,
+};
+
+// PORT read from env (no log)
+
+import express from 'express';
+import { WebSocketServer, WebSocket } from 'ws';
+import os from 'os';
+import http from 'http';
+import cors from 'cors';
+import cookieParser from 'cookie-parser';
+import { promises as fsPromises } from 'fs';
+import { spawn } from 'child_process';
+// node-pty: conditionally imported (not available on Vercel serverless)
+let pty = null;
+try {
+  pty = (await import('node-pty')).default;
+} catch (e) {
+  console.warn('[WARN] node-pty not available. Shell tab requires relay connection.');
+}
+// Node 22+ has built-in fetch — no need for node-fetch
+import mime from 'mime-types';
+
+import { getProjects, getSessions, getSessionMessages, renameProject, deleteSession, deleteProject, addProjectManually, extractProjectDirectory, clearProjectDirectoryCache, setCloudUserId } from './projects.js';
+import { queryClaudeSDK, abortClaudeSDKSession, isClaudeSDKSessionActive, getActiveClaudeSDKSessions, resolveToolApproval, loadGitagentContext, clearGitagentCache, extractTokenBudget } from './claude-sdk.js';
+import { buildSystemPromptAppendix } from '../shared/gitagent/prompt-builder.js';
+import { spawnCursor, abortCursorSession, isCursorSessionActive, getActiveCursorSessions } from './cursor-cli.js';
+import { queryCodex, abortCodexSession, isCodexSessionActive, getActiveCodexSessions } from './openai-codex.js';
+import { queryOpenRouter, OPENROUTER_MODELS } from './openrouter.js';
+import { createMcpServer, mountMcpServer } from './mcp-server.js';
+import gitRoutes from './routes/git.js';
+import authRoutes from './routes/auth.js';
+import mcpRoutes from './routes/mcp.js';
+import cursorRoutes from './routes/cursor.js';
+import taskmasterRoutes from './routes/taskmaster.js';
+import mcpUtilsRoutes from './routes/mcp-utils.js';
+import commandsRoutes from './routes/commands.js';
+import settingsRoutes from './routes/settings.js';
+import agentRoutes from './routes/agent.js';
+import projectsRoutes, { WORKSPACES_ROOT, validateWorkspacePath } from './routes/projects.js';
+import cliAuthRoutes from './routes/cli-auth.js';
+import userRoutes from './routes/user.js';
+import codexRoutes from './routes/codex.js';
+import paymentRoutes from './routes/payments.js';
+import webhookRoutes from './routes/webhooks.js';
+import workflowRoutes from './routes/workflows.js';
+import voiceRoutes from './routes/voice.js';
+import dashboardRoutes from './routes/dashboard.js';
+import keysRoutes from './routes/keys.js';
+import assistantRoutes from './routes/vapi-chat.js';
+import canvasRoutes from './routes/canvas.js';
+import composioRoutes from './routes/composio.js';
+import sessionRoutes from './routes/sessions.js';
+import { handleSandboxWebSocketCommand } from './middleware/sandboxRouter.js';
+import { createRelayMiddleware } from './middleware/relayHelpers.js';
+import { initScheduler } from './services/workflowScheduler.js';
+import { initializeDatabase, relayTokensDb, subscriptionDb, credentialsDb, userDb, fileVersionDb, sessionUsageDb, connectionDb, projectDb, voiceCallDb } from './database/db.js';
+import { validateApiKey, authenticateToken, authenticateWebSocket, JWT_SECRET } from './middleware/auth.js';
+import { IS_PLATFORM, IS_LOCAL } from './constants/config.js';
+import { sandboxClient } from './sandbox.js';
+import { execSync } from 'child_process';
+
+// ─── Project ownership middleware (user isolation) ──────────────────────────────
+// Ensures the requesting user owns the project before allowing access.
+// In cloud mode: checks user_projects table. In local mode: always passes (single user).
+const IS_CLOUD_ENV = !!(process.env.TURSO_DATABASE_URL && !process.env.IS_LOCAL_SERVER);
+
+function authorizeProject(req, res, next) {
+    const projectName = req.params.projectName;
+    if (!projectName) return next();
+
+    // Local mode — single user, no isolation needed
+    if (!IS_CLOUD_ENV) return next();
+
+    const userId = req.user?.id || req.user?.userId;
+    if (!userId) return res.status(401).json({ error: 'Authentication required' });
+
+    // Check user_projects table for ownership
+    projectDb.getAll(userId).then(projects => {
+        const owns = projects.some(p => p.project_name === projectName || p.original_path === projectName);
+        if (!owns) {
+            return res.status(403).json({ error: 'Access denied — you do not own this project' });
+        }
+        next();
+    }).catch(() => {
+        res.status(500).json({ error: 'Internal server error' });
+    });
+}
+
+// File system watchers for provider project/session folders
+const PROVIDER_WATCH_PATHS = [
+    { provider: 'claude', rootPath: path.join(os.homedir(), '.claude', 'projects') },
+    { provider: 'cursor', rootPath: path.join(os.homedir(), '.cursor', 'chats') },
+    { provider: 'codex', rootPath: path.join(os.homedir(), '.codex', 'sessions') }
+];
+const WATCHER_IGNORED_PATTERNS = [
+    '**/node_modules/**',
+    '**/.git/**',
+    '**/dist/**',
+    '**/build/**',
+    '**/*.tmp',
+    '**/*.swp',
+    '**/.DS_Store'
+];
+const WATCHER_DEBOUNCE_MS = 300;
+let projectsWatchers = [];
+let projectsWatcherDebounceTimer = null;
+const connectedClients = new Set();
+let isGetProjectsRunning = false; // Flag to prevent reentrant calls
+
+// Relay connections: Maps userId → { ws, capabilities, user }
+// Connects user's local machine to the hosted server
+const relayConnections = new Map();
+// Pending relay requests: Maps requestId → { resolve, reject, timeout }
+const pendingRelayRequests = new Map();
+// Relay session tracking: Maps sessionId → { userId, requestId } (for abort forwarding)
+const relaySessionRequests = new Map();
+// Sandbox cleanup timers: Maps userId → timeout (grace period before sandbox destroy)
+const sandboxCleanupTimers = new Map();
+const SANDBOX_GRACE_PERIOD_MS = 5 * 60 * 1000; // 5 minutes
+
+// ─── Relay Security ──────────────────────────────────────────────────────────
+
+// Allowed relay actions — only these can be sent to user's machine.
+// Anything not on this list is rejected to prevent arbitrary command execution.
+const ALLOWED_RELAY_ACTIONS = new Set([
+    'claude-query', 'codex-query', 'cursor-query',
+    'claude-task-query', // Sub-agent: read-only research (opencode pattern)
+    'exec', 'shell-command', 'shell-session-start', // Shell execution & interactive terminal
+    'file-read', 'file-write', 'file-tree',
+    'browse-dirs', 'validate-path', 'create-folder',
+    'git-operation', 'detect-agents',
+    'gitagent-detect', 'gitagent-parse', // Gitagent directory structure detection
+]);
+
+// Dangerous shell patterns — block injection attempts in shell-command payloads.
+// These patterns catch common shell injection techniques: pipes, chaining,
+// backtick execution, subshells, redirection to sensitive files, etc.
+const DANGEROUS_SHELL_PATTERNS = [
+    /;\s*(rm|del|format|mkfs|dd)\b/i,      // destructive chained commands
+    /\|\s*(bash|sh|cmd|powershell|nc|ncat|curl\s.*\|)/i, // pipe to shell/reverse-shell
+    /`[^`]*`/,                               // backtick command substitution
+    /\$\([^)]*\)/,                           // $() command substitution
+    />\s*\/etc\//,                           // redirect to system files
+    />\s*C:\\Windows\\/i,                    // redirect to Windows system
+    /&&\s*(rm|del|format|shutdown|reboot)\b/i, // chain destructive commands
+    /\|\|\s*(rm|del|format)\b/i,             // fallback destructive
+    /;\s*(curl|wget|nc)\s.*\s*\|/i,          // download-and-execute
+    /eval\s*\(/,                             // eval injection
+    /\bsudo\b/,                              // privilege escalation
+    /\bchmod\s+[0-7]*[67][0-7]*\s/,         // making files world-writable
+];
+
+/**
+ * Extract real client IP from request (respects proxy headers on Railway/Vercel).
+ * Railway sets x-forwarded-for; we trust the first IP in the chain.
+ */
+function extractClientIp(request) {
+    const forwarded = request?.headers?.['x-forwarded-for'];
+    if (forwarded) {
+        // x-forwarded-for may be comma-separated; first is the real client
+        return forwarded.split(',')[0].trim();
+    }
+    return request?.socket?.remoteAddress || request?.connection?.remoteAddress || 'unknown';
+}
+
+/**
+ * Validate a relay command payload for safety.
+ * Returns { valid: true } or { valid: false, reason: string }.
+ */
+function validateRelayPayload(action, payload) {
+    if (!ALLOWED_RELAY_ACTIONS.has(action)) {
+        return { valid: false, reason: `Unknown relay action: ${action}` };
+    }
+
+    // For shell-command, validate the command string
+    if (action === 'shell-command' && payload?.command) {
+        const cmd = payload.command;
+
+        // Must be a string
+        if (typeof cmd !== 'string') {
+            return { valid: false, reason: 'Command must be a string' };
+        }
+
+        // Max command length (prevent buffer overflow attempts)
+        if (cmd.length > 10000) {
+            return { valid: false, reason: 'Command too long' };
+        }
+
+        // Only allow git commands and known safe commands via shell-command
+        // This is the key security gate: shell-command is only used for git operations
+        // and system commands like mkdir, rm (for discard). Block everything else.
+        const allowedPrefixes = ['git ', 'mkdir ', 'rm ', 'wmic ', 'dir ', 'claude ', 'codex ', 'npm '];
+        const isAllowedCommand = allowedPrefixes.some(prefix => cmd.trimStart().startsWith(prefix));
+        if (!isAllowedCommand) {
+            return { valid: false, reason: `Shell command not allowed: ${cmd.substring(0, 50)}` };
+        }
+
+        // Check for dangerous patterns even in allowed commands
+        for (const pattern of DANGEROUS_SHELL_PATTERNS) {
+            if (pattern.test(cmd)) {
+                return { valid: false, reason: 'Dangerous command pattern detected' };
+            }
+        }
+    }
+
+    // For file operations, validate paths
+    if (['file-read', 'file-write', 'file-tree', 'create-folder'].includes(action)) {
+        const filePath = payload?.filePath || payload?.dirPath || payload?.folderPath;
+        if (filePath && typeof filePath === 'string') {
+            // Block path traversal attempts
+            if (filePath.includes('..') && (filePath.includes('/etc/') || filePath.includes('/proc/') || filePath.includes('\\Windows\\System32'))) {
+                return { valid: false, reason: 'Path traversal blocked' };
+            }
+        }
+    }
+
+    return { valid: true };
+}
+
+// Session-tab locking: Maps sessionId → WebSocket connection
+// Prevents the same session from being active in multiple tabs
+const sessionLocks = new Map();
+
+// Session-to-user ownership map — tracks which userId owns each sessionId
+// Used by session REST routes to enforce user isolation
+const sessionOwners = new Map();
+
+// Session busy detection (opencode pattern: IsSessionBusy)
+// Maps sessionId → true when a query is being processed
+const busySessions = new Map();
+
+function markSessionBusy(sessionId) {
+    if (!sessionId) return true;
+    if (busySessions.has(sessionId)) return false; // already busy
+    busySessions.set(sessionId, true);
+    return true;
+}
+
+function markSessionFree(sessionId) {
+    if (sessionId) busySessions.delete(sessionId);
+}
+
+function acquireSessionLock(sessionId, ws) {
+    if (!sessionId) return true; // New sessions don't need locks yet
+    const existingWs = sessionLocks.get(sessionId);
+    if (existingWs && existingWs !== ws && existingWs.readyState === 1) {
+        return false; // Another tab has this session locked
+    }
+    sessionLocks.set(sessionId, ws);
+    return true;
+}
+
+function releaseSessionLock(sessionId, ws) {
+    const lockedWs = sessionLocks.get(sessionId);
+    if (lockedWs === ws) {
+        sessionLocks.delete(sessionId);
+    }
+}
+
+function releaseAllLocksForWs(ws) {
+    for (const [sessionId, lockedWs] of sessionLocks.entries()) {
+        if (lockedWs === ws) {
+            sessionLocks.delete(sessionId);
+        }
+    }
+}
+
+// Session subscribers: Maps sessionId → Set<WebSocket>
+// Allows multiple tabs to READ output from an active session
+const sessionSubscribers = new Map();
+
+function subscribeToSession(sessionId, ws) {
+    if (!sessionId) return;
+    if (!sessionSubscribers.has(sessionId)) {
+        sessionSubscribers.set(sessionId, new Set());
+    }
+    sessionSubscribers.get(sessionId).add(ws);
+}
+
+function unsubscribeFromSession(sessionId, ws) {
+    const subs = sessionSubscribers.get(sessionId);
+    if (subs) {
+        subs.delete(ws);
+        if (subs.size === 0) sessionSubscribers.delete(sessionId);
+    }
+}
+
+function unsubscribeAllForWs(ws) {
+    for (const [sessionId, subs] of sessionSubscribers.entries()) {
+        subs.delete(ws);
+        if (subs.size === 0) sessionSubscribers.delete(sessionId);
+    }
+}
+
+function broadcastToSessionSubscribers(sessionId, message) {
+    const subs = sessionSubscribers.get(sessionId);
+    if (!subs) return;
+    const payload = typeof message === 'string' ? message : JSON.stringify(message);
+    for (const ws of subs) {
+        if (ws.readyState === 1) {
+            ws.send(payload);
+        }
+    }
+}
+
+// Broadcast progress to all connected WebSocket clients
+function broadcastProgress(progress) {
+    const message = JSON.stringify({
+        type: 'loading_progress',
+        ...progress
+    });
+    connectedClients.forEach(client => {
+        if (client.readyState === WebSocket.OPEN) {
+            client.send(message);
+        }
+    });
+}
+
+// Setup file system watchers for Claude, Cursor, and Codex project/session folders
+async function setupProjectsWatcher() {
+    const chokidar = (await import('chokidar')).default;
+
+    if (projectsWatcherDebounceTimer) {
+        clearTimeout(projectsWatcherDebounceTimer);
+        projectsWatcherDebounceTimer = null;
+    }
+
+    await Promise.all(
+        projectsWatchers.map(async (watcher) => {
+            try {
+                await watcher.close();
+            } catch (error) {
+                // watcher close error handled silently
+            }
+        })
+    );
+    projectsWatchers = [];
+
+    const debouncedUpdate = (eventType, filePath, provider, rootPath) => {
+        if (projectsWatcherDebounceTimer) {
+            clearTimeout(projectsWatcherDebounceTimer);
+        }
+
+        projectsWatcherDebounceTimer = setTimeout(async () => {
+            // Prevent reentrant calls
+            if (isGetProjectsRunning) {
+                return;
+            }
+
+            try {
+                isGetProjectsRunning = true;
+
+                // Clear project directory cache when files change
+                clearProjectDirectoryCache();
+
+                // Get updated projects list
+                const updatedProjects = await getProjects(broadcastProgress);
+
+                // Notify connected clients about project changes (per-user filtered)
+                const basePayload = {
+                    type: 'projects_updated',
+                    timestamp: new Date().toISOString(),
+                    changeType: eventType,
+                    changedFile: path.relative(rootPath, filePath),
+                    watchProvider: provider
+                };
+
+                // Build per-user project lists, then send to all their clients
+                const userProjectsCache = new Map();
+                for (const client of connectedClients) {
+                    if (client.readyState !== WebSocket.OPEN) continue;
+                    const uid = client._wsUser?.userId;
+                    if (!uid) {
+                        // No auth — local mode, send all projects
+                        client.send(JSON.stringify({ ...basePayload, projects: updatedProjects }));
+                        continue;
+                    }
+                    try {
+                        if (!userProjectsCache.has(uid)) {
+                            userProjectsCache.set(uid, await getProjects(null, uid));
+                        }
+                        client.send(JSON.stringify({ ...basePayload, projects: userProjectsCache.get(uid) }));
+                    } catch { /* ignore per-user fetch errors */ }
+                }
+
+            } catch (error) {
+                // project change error handled silently
+            } finally {
+                isGetProjectsRunning = false;
+            }
+        }, WATCHER_DEBOUNCE_MS);
+    };
+
+    for (const { provider, rootPath } of PROVIDER_WATCH_PATHS) {
+        try {
+            // chokidar v4 emits ENOENT via the "error" event for missing roots and will not auto-recover.
+            // Ensure provider folders exist before creating the watcher so watching stays active.
+            await fsPromises.mkdir(rootPath, { recursive: true });
+
+            // Initialize chokidar watcher with optimized settings
+            const watcher = chokidar.watch(rootPath, {
+                ignored: WATCHER_IGNORED_PATTERNS,
+                persistent: true,
+                ignoreInitial: true, // Don't fire events for existing files on startup
+                followSymlinks: false,
+                depth: 10, // Reasonable depth limit
+                awaitWriteFinish: {
+                    stabilityThreshold: 100, // Wait 100ms for file to stabilize
+                    pollInterval: 50
+                }
+            });
+
+            // Set up event listeners
+            watcher
+                .on('add', (filePath) => debouncedUpdate('add', filePath, provider, rootPath))
+                .on('change', (filePath) => debouncedUpdate('change', filePath, provider, rootPath))
+                .on('unlink', (filePath) => debouncedUpdate('unlink', filePath, provider, rootPath))
+                .on('addDir', (dirPath) => debouncedUpdate('addDir', dirPath, provider, rootPath))
+                .on('unlinkDir', (dirPath) => debouncedUpdate('unlinkDir', dirPath, provider, rootPath))
+                .on('error', (error) => {
+                    // provider watcher error handled silently
+                })
+                .on('ready', () => {
+                });
+
+            projectsWatchers.push(watcher);
+        } catch (error) {
+            // provider watcher setup error handled silently
+        }
+    }
+
+    if (projectsWatchers.length === 0) {
+        // no provider watchers available
+    }
+}
+
+
+const app = express();
+
+// On Vercel serverless, we don't need an HTTP server or WebSocket server
+const server = process.env.VERCEL ? null : http.createServer(app);
+
+const ptySessionsMap = new Map();
+const PTY_SESSION_TIMEOUT = 30 * 60 * 1000;
+const SHELL_URL_PARSE_BUFFER_LIMIT = 32768;
+const ANSI_ESCAPE_SEQUENCE_REGEX = /\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~]|\][^\x07]*(?:\x07|\x1B\\))/g;
+const TRAILING_URL_PUNCTUATION_REGEX = /[)\]}>.,;:!?]+$/;
+
+function stripAnsiSequences(value = '') {
+    return value.replace(ANSI_ESCAPE_SEQUENCE_REGEX, '');
+}
+
+function normalizeDetectedUrl(url) {
+    if (!url || typeof url !== 'string') return null;
+
+    const cleaned = url.trim().replace(TRAILING_URL_PUNCTUATION_REGEX, '');
+    if (!cleaned) return null;
+
+    try {
+        const parsed = new URL(cleaned);
+        if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+            return null;
+        }
+        return parsed.toString();
+    } catch {
+        return null;
+    }
+}
+
+function extractUrlsFromText(value = '') {
+    const directMatches = value.match(/https?:\/\/[^\s<>"'`\\\x1b\x07]+/gi) || [];
+
+    // Handle wrapped terminal URLs split across lines by terminal width.
+    const wrappedMatches = [];
+    const continuationRegex = /^[A-Za-z0-9\-._~:/?#\[\]@!$&'()*+,;=%]+$/;
+    const lines = value.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i].trim();
+        const startMatch = line.match(/https?:\/\/[^\s<>"'`\\\x1b\x07]+/i);
+        if (!startMatch) continue;
+
+        let combined = startMatch[0];
+        let j = i + 1;
+        while (j < lines.length) {
+            const continuation = lines[j].trim();
+            if (!continuation) break;
+            if (!continuationRegex.test(continuation)) break;
+            combined += continuation;
+            j++;
+        }
+
+        wrappedMatches.push(combined.replace(/\r?\n\s*/g, ''));
+    }
+
+    return Array.from(new Set([...directMatches, ...wrappedMatches]));
+}
+
+function shouldAutoOpenUrlFromOutput(value = '') {
+    const normalized = value.toLowerCase();
+    return (
+        normalized.includes('browser didn\'t open') ||
+        normalized.includes('open this url') ||
+        normalized.includes('continue in your browser') ||
+        normalized.includes('press enter to open') ||
+        normalized.includes('open_url:')
+    );
+}
+
+// Single WebSocket server that handles both paths (skip on Vercel serverless)
+let wss = null;
+if (server) {
+    wss = new WebSocketServer({
+        server,
+        verifyClient: (info, done) => {
+            const reqUrl = info.req.url || '';
+            const origin = info.req.headers?.origin || 'no-origin';
+            authenticateWebSocket(info.req).then(user => {
+                if (!user) {
+                    done(false, 401, 'Unauthorized');
+                    return;
+                }
+                info.req.user = user;
+                done(true);
+            }).catch(err => {
+                console.error(`[WS] Auth ERROR for ${reqUrl}:`, err.message);
+                done(false, 500, 'Auth error');
+            });
+        }
+    });
+}
+
+// Make WebSocket server available to routes
+app.locals.wss = wss;
+
+// Security headers — protect against common web attacks
+app.use((req, res, next) => {
+  res.setHeader('X-Content-Type-Options', 'nosniff');
+  // Allow framing from our own frontend domains (Vercel embeds Railway in an iframe)
+  const allowedFrameOrigins = (process.env.CORS_ORIGINS || '').split(',').map(s => s.trim()).filter(Boolean);
+  if (allowedFrameOrigins.length > 0) {
+    res.setHeader('Content-Security-Policy', `frame-ancestors 'self' ${allowedFrameOrigins.join(' ')}`);
+  } else {
+    res.setHeader('X-Frame-Options', 'SAMEORIGIN');
+  }
+  res.setHeader('X-XSS-Protection', '1; mode=block');
+  res.setHeader('Referrer-Policy', 'strict-origin-when-cross-origin');
+  if (process.env.NODE_ENV === 'production') {
+    res.setHeader('Strict-Transport-Security', 'max-age=31536000; includeSubDomains');
+  }
+  next();
+});
+
+// CORS: require explicit CORS_ORIGINS in production, restrict to same-origin otherwise
+const CORS_ORIGINS = process.env.CORS_ORIGINS
+  ? process.env.CORS_ORIGINS.split(',').map(o => o.trim())
+  : (process.env.NODE_ENV === 'production' ? ['https://cli.upfyn.com'] : true);
+app.use(cors({ origin: CORS_ORIGINS, credentials: true }));
+app.use(cookieParser());
+app.use(express.json({
+  limit: '50mb',
+  type: (req) => {
+    // Skip multipart/form-data requests (for file uploads like images)
+    const contentType = req.headers['content-type'] || '';
+    if (contentType.includes('multipart/form-data')) {
+      return false;
+    }
+    return contentType.includes('json');
+  }
+}));
+app.use(express.urlencoded({ limit: '50mb', extended: true }));
+
+// Rate limiting for auth endpoints — prevent brute force attacks
+const authRateLimitMap = new Map();
+const AUTH_RATE_WINDOW = 15 * 60 * 1000; // 15 minutes
+const AUTH_RATE_MAX = 10; // max attempts per window
+
+function authRateLimit(req, res, next) {
+  const key = req.ip || req.connection.remoteAddress || 'unknown';
+  const now = Date.now();
+  const entry = authRateLimitMap.get(key);
+
+  if (entry) {
+    // Clean expired entries
+    if (now - entry.windowStart > AUTH_RATE_WINDOW) {
+      authRateLimitMap.set(key, { windowStart: now, count: 1 });
+      return next();
+    }
+    entry.count++;
+    if (entry.count > AUTH_RATE_MAX) {
+      return res.status(429).json({ error: 'Too many attempts. Please try again later.' });
+    }
+  } else {
+    authRateLimitMap.set(key, { windowStart: now, count: 1 });
+  }
+  next();
+}
+
+// Clean up stale rate limit entries every 30 minutes
+setInterval(() => {
+  const now = Date.now();
+  for (const [key, entry] of authRateLimitMap) {
+    if (now - entry.windowStart > AUTH_RATE_WINDOW) {
+      authRateLimitMap.delete(key);
+    }
+  }
+}, 30 * 60 * 1000);
+
+app.locals.authRateLimit = authRateLimit;
+
+// Vercel serverless: lazy DB initialization on first request
+let dbInitialized = false;
+if (process.env.VERCEL) {
+    app.use(async (req, res, next) => {
+        if (!dbInitialized) {
+            try {
+                await initializeDatabase();
+                dbInitialized = true;
+            } catch (err) {
+                // DB init error handled silently
+                return res.status(500).json({ error: 'Service temporarily unavailable' });
+            }
+        }
+        next();
+    });
+}
+
+// Public health check endpoint (no authentication required)
+app.get('/health', (req, res) => {
+  res.json({
+    status: 'ok',
+    version: SERVER_VERSION,
+    timestamp: new Date().toISOString()
+  });
+});
+
+// Optional API key validation (if configured)
+app.use('/api', validateApiKey);
+
+// Authentication routes (public)
+app.use('/api/auth', authRoutes);
+
+// Relay middleware — injects req.isCloud, req.hasRelay(), req.sendRelay(), req.requireRelay()
+// Must be created after hasActiveRelay/sendRelayCommand are defined (they're hoisted functions)
+const relayMiddleware = createRelayMiddleware(hasActiveRelay, sendRelayCommand, withRetry);
+
+// Projects API Routes (protected + relay-aware)
+app.use('/api/projects', authenticateToken, relayMiddleware, projectsRoutes);
+
+// Git API Routes (protected + relay-aware)
+app.use('/api/git', authenticateToken, relayMiddleware, gitRoutes);
+
+// MCP API Routes (protected + relay-aware)
+app.use('/api/mcp', authenticateToken, relayMiddleware, mcpRoutes);
+
+// Cursor API Routes (protected + relay-aware)
+app.use('/api/cursor', authenticateToken, relayMiddleware, cursorRoutes);
+
+// TaskMaster API Routes (protected)
+app.use('/api/taskmaster', authenticateToken, taskmasterRoutes);
+
+// MCP utilities
+app.use('/api/mcp-utils', authenticateToken, relayMiddleware, mcpUtilsRoutes);
+
+// Upfyn-Code MCP Server — exposes app capabilities to any MCP client (ChatGPT, Claude Desktop, Cursor, etc.)
+const mcpDeps = {
+    getProjects,
+    getSessions,
+    getSessionMessages,
+    queryClaudeSDK,
+    abortClaudeSDKSession,
+    getActiveClaudeSDKSessions,
+    connectedClients,
+};
+const mcpAppServer = createMcpServer(mcpDeps);
+const mcpServerFactory = () => createMcpServer(mcpDeps);
+mountMcpServer(app, mcpAppServer, mcpServerFactory).catch(err => console.error('[MCP] Failed to mount:', err.message));
+
+// Commands API Routes (protected + relay-aware)
+app.use('/api/commands', authenticateToken, relayMiddleware, commandsRoutes);
+
+// Settings API Routes (protected)
+app.use('/api/settings', authenticateToken, settingsRoutes);
+
+// CLI Authentication API Routes (protected)
+app.use('/api/cli', authenticateToken, cliAuthRoutes);
+
+// User API Routes (protected)
+app.use('/api/user', authenticateToken, userRoutes);
+
+// Codex API Routes (protected + relay-aware)
+app.use('/api/codex', authenticateToken, relayMiddleware, codexRoutes);
+
+// Payment & Subscription Routes (protected)
+app.use('/api/payments', authenticateToken, paymentRoutes);
+app.use('/api/webhooks', authenticateToken, webhookRoutes);
+app.use('/api/workflows', authenticateToken, workflowRoutes);
+app.use('/api/voice', authenticateToken, voiceRoutes);
+app.use('/api/dashboard', authenticateToken, dashboardRoutes);
+// Inject sessionOwners map so session routes can filter by userId
+app.use('/api/sessions', authenticateToken, (req, _res, next) => {
+    req.sessionOwners = sessionOwners;
+    next();
+}, sessionRoutes);
+app.use('/api/keys', authenticateToken, keysRoutes);
+app.use('/api/assistant', assistantRoutes);
+app.use('/api/canvas', authenticateToken, canvasRoutes);
+app.use('/api/composio', authenticateToken, composioRoutes);
+app.use('/api/vapi', assistantRoutes); // Alias: VAPI dashboard webhook points to /api/vapi/webhook
+
+// Voice call history endpoints (per-user isolated)
+app.get('/api/voice/calls', authenticateToken, async (req, res) => {
+    try {
+        const userId = req.user.id || req.user.userId;
+        const limit = Math.min(parseInt(req.query.limit) || 20, 100);
+        const offset = parseInt(req.query.offset) || 0;
+        const calls = await voiceCallDb.getByUser(userId, limit, offset);
+        const stats = await voiceCallDb.getUserStats(userId);
+        res.json({ calls, stats });
+    } catch {
+        res.status(500).json({ error: 'Failed to fetch voice call history' });
+    }
+});
+
+// Agent API Routes (uses API key authentication)
+app.use('/api/agent', agentRoutes);
+
+// Relay token management routes
+app.get('/api/relay/tokens', authenticateToken, async (req, res) => {
+    try {
+        const tokens = await relayTokensDb.getTokens(req.user.id);
+        res.json(tokens.map(t => ({ ...t, token: t.token.slice(0, 10) + '...' }))); // mask tokens
+    } catch (err) {
+        res.status(500).json({ error: 'Failed to fetch relay tokens' });
+    }
+});
+
+app.post('/api/relay/tokens', authenticateToken, async (req, res) => {
+    try {
+        const name = req.body.name || 'default';
+        const result = await relayTokensDb.createToken(req.user.id, name);
+        res.json(result); // returns full token only on creation
+    } catch (err) {
+        res.status(500).json({ error: 'Failed to create relay token' });
+    }
+});
+
+app.delete('/api/relay/tokens/:id', authenticateToken, async (req, res) => {
+    try {
+        await relayTokensDb.deleteToken(req.user.id, req.params.id);
+        res.json({ success: true });
+    } catch (err) {
+        res.status(500).json({ error: 'Failed to delete relay token' });
+    }
+});
+
+app.get('/api/relay/status', authenticateToken, async (req, res) => {
+    // In local mode, always connected — SDK runs directly on this machine
+    if (IS_LOCAL) {
+        return res.json({ connected: true, local: true, connectedAt: Date.now() });
+    }
+    const relay = relayConnections.get(Number(req.user.id));
+    const connected = !!(relay && relay.ws.readyState === 1);
+
+    // Ensure relay CWD is registered as a project (handles post-deploy filesystem wipe)
+    if (connected && relay.cwd) {
+        try { await addProjectManually(relay.cwd, null, req.user.id); } catch { /* already exists */ }
+    }
+
+    // Check if sandbox is alive (even if relay is disconnected — grace period)
+    let sandboxActive = false;
+    try {
+        const sbStatus = await sandboxClient.getStatus(req.user.id).catch(() => null);
+        sandboxActive = !!(sbStatus?.running);
+    } catch { /* ignore */ }
+
+    // Get last connection info from DB for reconnection context
+    let lastConnection = null;
+    if (!connected) {
+        try {
+            const active = await connectionDb.getActive(String(req.user.id));
+            if (active.length === 0) {
+                // Check recent disconnections
+                const all = await connectionDb.getAllActive();
+                lastConnection = all.find(c => c.user_id === String(req.user.id)) || null;
+            }
+        } catch { /* ignore */ }
+    }
+
+    res.json({
+        connected,
+        connectedAt: relay?.connectedAt || null,
+        cwd: connected ? relay.cwd : null,
+        machine: connected ? relay.machine : null,
+        platform: connected ? relay.platform : null,
+        version: connected ? relay.version : null,
+        sandboxActive,
+        lastConnection: lastConnection ? {
+            cwd: lastConnection.last_cwd,
+            machine: lastConnection.last_machine,
+            platform: lastConnection.last_platform,
+            disconnectedAt: lastConnection.disconnected_at,
+        } : null,
+        // Mask the IP — only show last octet for user verification
+        clientIp: connected && relay.clientIp ? relay.clientIp.replace(/(\d+\.\d+\.\d+\.)(\d+)/, '$1***') : null,
+    });
+});
+
+// POST /api/relay/disconnect — user-initiated disconnect (saves state, destroys sandbox)
+app.post('/api/relay/disconnect', authenticateToken, async (req, res) => {
+    const userId = Number(req.user.id);
+    const relay = relayConnections.get(userId);
+    if (!relay || relay.ws.readyState !== 1) {
+        return res.json({ success: false, error: 'No active relay connection' });
+    }
+
+    // Cancel any pending sandbox grace period
+    const pending = sandboxCleanupTimers.get(userId);
+    if (pending) { clearTimeout(pending); sandboxCleanupTimers.delete(userId); }
+
+    // Save sandbox state to connection record before destroying
+    try {
+        const sbStatus = await sandboxClient.getStatus(userId).catch(() => null);
+        await connectionDb.disconnect(String(userId), 'relay');
+    } catch { /* non-critical */ }
+
+    // Destroy sandbox immediately (user-initiated = no grace period)
+    try { await sandboxClient.destroySandbox(userId); } catch { /* best-effort */ }
+
+    // Close the relay WebSocket
+    try {
+        relay.ws.send(JSON.stringify({ type: 'server-disconnect', reason: 'User disconnected from web UI' }));
+        relay.ws.close();
+    } catch { /* may already be closing */ }
+
+    res.json({ success: true, message: 'Relay disconnected' });
+});
+
+// ─── Sandbox API endpoints ──────────────────────────────────────────────────
+
+// Initialize sandbox for user
+app.post('/api/sandbox/init', authenticateToken, async (req, res) => {
+    try {
+        const result = await sandboxClient.initSandbox(req.user.id);
+        res.json(result);
+    } catch (err) {
+        res.status(503).json({ error: err.message });
+    }
+});
+
+// Get sandbox status
+app.get('/api/sandbox/status', authenticateToken, async (req, res) => {
+    try {
+        const result = await sandboxClient.getStatus(req.user.id);
+        res.json(result);
+    } catch (err) {
+        res.status(503).json({ error: err.message });
+    }
+});
+
+// ─── System update endpoint ─────────────────────────────────────────────────
+// Runs npm update on the user's machine. Only available in self-hosted mode.
+// Platform users (cli.upfyn.com) don't see update notifications — the server auto-deploys.
+app.post('/api/system/update', authenticateToken, async (req, res) => {
+    try {
+        if (IS_LOCAL) {
+            // Self-hosted: run locally
+            const { execSync } = await import('child_process');
+            const output = execSync('npm install -g upfynai-code@latest', { encoding: 'utf8', timeout: 120000 });
+            res.json({ output, exitCode: 0 });
+        } else {
+            // Platform mode: server is managed by Railway, no user action needed
+            res.status(400).json({ error: 'Server updates are automatic on the platform. No action needed.' });
+        }
+    } catch (err) {
+        res.status(500).json({ error: err.message || 'Update failed' });
+    }
+});
+
+// Execute command in sandbox
+app.post('/api/sandbox/exec', authenticateToken, async (req, res) => {
+    try {
+        const { command, cwd, timeout } = req.body;
+        // Get user's BYOK keys for sandbox env
+        const userKeys = {};
+        try {
+            const anthropicKey = await credentialsDb.getCredentialByType(req.user.id, 'anthropic_key');
+            if (anthropicKey) userKeys.anthropic_key = anthropicKey.credential_value;
+            const openaiKey = await credentialsDb.getCredentialByType(req.user.id, 'openai_key');
+            if (openaiKey) userKeys.openai_key = openaiKey.credential_value;
+        } catch { /* no keys */ }
+        const result = await sandboxClient.exec(req.user.id, command, { cwd, timeout, userKeys });
+        res.json(result);
+    } catch (err) {
+        res.status(500).json({ error: err.message });
+    }
+});
+
+// Read file from sandbox
+app.post('/api/sandbox/file/read', authenticateToken, async (req, res) => {
+    try {
+        const result = await sandboxClient.readFile(req.user.id, req.body.filePath);
+        res.json(result);
+    } catch (err) {
+        const status = err.message?.includes('Access denied') ? 403
+            : err.message?.includes('ENOENT') || err.message?.includes('404') ? 404 : 500;
+        res.status(status).json({ error: err.message });
+    }
+});
+
+// Write file to sandbox
+app.post('/api/sandbox/file/write', authenticateToken, async (req, res) => {
+    try {
+        const result = await sandboxClient.writeFile(req.user.id, req.body.filePath, req.body.content);
+        res.json(result);
+    } catch (err) {
+        res.status(500).json({ error: err.message });
+    }
+});
+
+// File tree from sandbox
+app.post('/api/sandbox/file/tree', authenticateToken, async (req, res) => {
+    try {
+        const result = await sandboxClient.getFileTree(req.user.id, req.body.dirPath, req.body.depth);
+        res.json(result);
+    } catch (err) {
+        res.status(500).json({ error: err.message });
+    }
+});
+
+// Git operation in sandbox
+app.post('/api/sandbox/git', authenticateToken, async (req, res) => {
+    try {
+        const result = await sandboxClient.gitOperation(req.user.id, req.body.gitCommand, req.body.cwd);
+        res.json(result);
+    } catch (err) {
+        res.status(500).json({ error: err.message });
+    }
+});
+
+// Destroy sandbox
+app.delete('/api/sandbox', authenticateToken, async (req, res) => {
+    try {
+        const result = await sandboxClient.destroySandbox(req.user.id);
+        res.json(result);
+    } catch (err) {
+        res.status(500).json({ error: err.message });
+    }
+});
+
+/**
+ * Detect installed AI CLI agents on the local machine (server-side).
+ * Used in self-hosted/local mode where no relay is needed.
+ */
+let cachedLocalAgents = null;
+let localAgentsCacheTime = 0;
+function detectLocalAgents() {
+    // Cache for 60 seconds
+    if (cachedLocalAgents && Date.now() - localAgentsCacheTime < 60000) {
+        return cachedLocalAgents;
+    }
+    const isWindows = process.platform === 'win32';
+    const whichCmd = isWindows ? 'where' : 'which';
+    const agents = [
+        { name: 'claude', binary: 'claude', label: 'Claude Code' },
+        { name: 'codex', binary: 'codex', label: 'OpenAI Codex' },
+        { name: 'cursor', binary: 'cursor-agent', label: 'Cursor Agent' },
+    ];
+    const detected = {};
+    for (const agent of agents) {
+        try {
+            const result = execSync(`${whichCmd} ${agent.binary}`, { stdio: 'pipe', timeout: 5000 }).toString().trim();
+            detected[agent.name] = { installed: true, path: result.split('\n')[0].trim(), label: agent.label };
+        } catch {
+            detected[agent.name] = { installed: false, label: agent.label };
+        }
+    }
+    cachedLocalAgents = detected;
+    localAgentsCacheTime = Date.now();
+    return detected;
+}
+
+// Connection status — alias at path the frontend expects
+app.get('/api/auth/connection-status', authenticateToken, async (req, res) => {
+    const relay = relayConnections.get(Number(req.user.id));
+    const connected = !!(relay && relay.ws.readyState === 1);
+
+    // In local mode, always "connected" — SDK runs directly on this machine
+    if (IS_LOCAL) {
+        const agents = detectLocalAgents();
+        return res.json({
+            connected: true,
+            local: true,
+            connectedAt: Date.now(),
+            agents,
+            machine: {
+                hostname: os.hostname(),
+                platform: process.platform,
+                cwd: process.cwd(),
+            }
+        });
+    }
+
+    // Check sandbox service availability when no relay
+    let sandboxAvailable = false;
+    let sandboxInfo = null;
+    if (!connected) {
+        try {
+            sandboxAvailable = await sandboxClient.isAvailable();
+            if (sandboxAvailable) {
+                sandboxInfo = await sandboxClient.getStatus(req.user.id);
+            }
+        } catch { /* sandbox service unreachable */ }
+    }
+
+    res.json({
+        connected,
+        local: false,
+        connectedAt: relay?.connectedAt || null,
+        agents: connected ? (relay.agents || null) : null,
+        machine: connected ? {
+            hostname: relay.machine,
+            platform: relay.platform,
+            cwd: relay.cwd,
+            version: relay.version,
+        } : null,
+        sandbox: {
+            available: sandboxAvailable,
+            active: sandboxInfo?.exists || false,
+            diskUsage: sandboxInfo?.exists ? {
+                usedMB: sandboxInfo.usedMB,
+                maxMB: sandboxInfo.maxMB,
+            } : null,
+        },
+    });
+});
+
+// Serve public files (like api-docs.html)
+app.use(express.static(path.join(__dirname, '../client/public')));
+
+// Static files served after API routes
+// Add cache control: HTML files should not be cached, but assets can be cached
+app.use(express.static(path.join(__dirname, '../client/dist'), {
+  setHeaders: (res, filePath) => {
+    if (filePath.endsWith('.html')) {
+      // Prevent HTML caching to avoid service worker issues after builds
+      res.setHeader('Cache-Control', 'no-cache, no-store, must-revalidate');
+      res.setHeader('Pragma', 'no-cache');
+      res.setHeader('Expires', '0');
+    } else if (filePath.match(/\.(js|css|woff2?|ttf|eot|svg|png|jpg|jpeg|gif|ico)$/)) {
+      // Cache static assets for 1 year (they have hashed names)
+      res.setHeader('Cache-Control', 'public, max-age=31536000, immutable');
+    }
+  }
+}));
+
+// API Routes (protected)
+// /api/config endpoint removed - no longer needed
+// Frontend now uses window.location for WebSocket URLs
+
+// System update endpoint — REMOVED for security (shell command execution risk)
+// Use `uc update` from CLI instead
+
+app.get('/api/projects', authenticateToken, async (req, res) => {
+    try {
+        const projects = await getProjects(broadcastProgress, req.user.id);
+        res.json(projects);
+    } catch (error) {
+        res.status(500).json({ error: 'Internal server error' });
+    }
+});
+
+app.get('/api/projects/:projectName/sessions', authenticateToken, authorizeProject, async (req, res) => {
+    try {
+        const { limit = 5, offset = 0 } = req.query;
+        const result = await getSessions(req.params.projectName, parseInt(limit), parseInt(offset));
+        res.json(result);
+    } catch (error) {
+        res.status(500).json({ error: 'Internal server error' });
+    }
+});
+
+// Get messages for a specific session
+app.get('/api/projects/:projectName/sessions/:sessionId/messages', authenticateToken, authorizeProject, async (req, res) => {
+    try {
+        const { projectName, sessionId } = req.params;
+        const { limit, offset } = req.query;
+
+        const parsedLimit = limit ? parseInt(limit, 10) : null;
+        const parsedOffset = offset ? parseInt(offset, 10) : 0;
+
+        const result = await getSessionMessages(projectName, sessionId, parsedLimit, parsedOffset);
+
+        if (Array.isArray(result)) {
+            res.json({ messages: result });
+        } else {
+            res.json(result);
+        }
+    } catch (error) {
+        res.status(500).json({ error: 'Internal server error' });
+    }
+});
+
+// Rename project endpoint
+app.put('/api/projects/:projectName/rename', authenticateToken, authorizeProject, async (req, res) => {
+    try {
+        const { displayName } = req.body;
+        await renameProject(req.params.projectName, displayName, req.user.id);
+        res.json({ success: true });
+    } catch (error) {
+        res.status(500).json({ error: 'Internal server error' });
+    }
+});
+
+// Delete session endpoint
+app.delete('/api/projects/:projectName/sessions/:sessionId', authenticateToken, authorizeProject, async (req, res) => {
+    try {
+        const { projectName, sessionId } = req.params;
+        await deleteSession(projectName, sessionId);
+        res.json({ success: true });
+    } catch (error) {
+        res.status(500).json({ error: 'Internal server error' });
+    }
+});
+
+// Delete project endpoint (force=true to delete with sessions)
+app.delete('/api/projects/:projectName', authenticateToken, authorizeProject, async (req, res) => {
+    try {
+        const { projectName } = req.params;
+        const force = req.query.force === 'true';
+        await deleteProject(projectName, force, req.user.id);
+        res.json({ success: true });
+    } catch (error) {
+        res.status(500).json({ error: 'Internal server error' });
+    }
+});
+
+// Read CLAUDE.md for a project
+app.get('/api/projects/:projectName/claude-md', authenticateToken, authorizeProject, async (req, res) => {
+    try {
+        const projectDir = await extractProjectDirectory(req.params.projectName);
+        if (!projectDir) {
+            return res.json({ content: null, path: null, error: 'Could not resolve project path' });
+        }
+
+        const claudeMdPath = path.join(projectDir, 'CLAUDE.md');
+
+        if (IS_CLOUD_ENV) {
+            const userId = req.user?.id || req.user?.userId;
+            if (!hasActiveRelay(Number(userId))) {
+                return res.json({ content: null, path: claudeMdPath, error: 'No machine connected' });
+            }
+            try {
+                const result = await sendRelayCommand(Number(userId), 'file-read', { filePath: claudeMdPath }, null, 10000);
+                return res.json({ content: result?.data?.content || null, path: claudeMdPath });
+            } catch {
+                return res.json({ content: null, path: claudeMdPath });
+            }
+        }
+
+        // Local mode
+        try {
+            const content = await fsPromises.readFile(claudeMdPath, 'utf8');
+            res.json({ content, path: claudeMdPath });
+        } catch {
+            res.json({ content: null, path: claudeMdPath });
+        }
+    } catch {
+        res.json({ content: null, path: null });
+    }
+});
+
+// Create project endpoint
+app.post('/api/projects/create', authenticateToken, async (req, res) => {
+    try {
+        const { path: projectPath } = req.body;
+
+        if (!projectPath || !projectPath.trim()) {
+            return res.status(400).json({ error: 'Project path is required' });
+        }
+
+        const project = await addProjectManually(projectPath.trim(), null, req.user.id);
+        res.json({ success: true, project });
+    } catch (error) {
+        // project creation error handled silently
+        res.status(500).json({ error: 'Internal server error' });
+    }
+});
+
+// ── Gitagent API endpoints ──────────────────────────────────────────
+
+// Get parsed gitagent definition + system prompt preview for a project
+app.get('/api/projects/:projectName/gitagent', authenticateToken, authorizeProject, async (req, res) => {
+    try {
+        const projectDir = await extractProjectDirectory(req.params.projectName);
+        if (!projectDir) return res.status(404).json({ error: 'Project not found' });
+
+        const ctx = await loadGitagentContext(projectDir);
+        if (!ctx) return res.json({ detected: false });
+
+        res.json({
+            detected: true,
+            definition: ctx.definition,
+            systemPromptPreview: ctx.systemPromptAppendix,
+            model: ctx.model,
+            allowedTools: ctx.allowedTools,
+            runtime: ctx.runtime,
+        });
+    } catch {
+        res.status(500).json({ error: 'Internal server error' });
+    }
+});
+
+// Clear cache and re-parse gitagent for a project
+app.post('/api/projects/:projectName/gitagent/refresh', authenticateToken, authorizeProject, async (req, res) => {
+    try {
+        const projectDir = await extractProjectDirectory(req.params.projectName);
+        if (!projectDir) return res.status(404).json({ error: 'Project not found' });
+
+        clearGitagentCache(projectDir);
+        const ctx = await loadGitagentContext(projectDir);
+        if (!ctx) return res.json({ detected: false });
+
+        res.json({
+            detected: true,
+            definition: ctx.definition,
+            systemPromptPreview: ctx.systemPromptAppendix,
+            model: ctx.model,
+            allowedTools: ctx.allowedTools,
+            runtime: ctx.runtime,
+        });
+    } catch {
+        res.status(500).json({ error: 'Internal server error' });
+    }
+});
+
+const expandWorkspacePath = (inputPath) => {
+    if (!inputPath) return inputPath;
+    if (inputPath === '~') {
+        return WORKSPACES_ROOT;
+    }
+    if (inputPath.startsWith('~/') || inputPath.startsWith('~\\')) {
+        return path.join(WORKSPACES_ROOT, inputPath.slice(2));
+    }
+    return inputPath;
+};
+
+// Browse filesystem endpoint for project suggestions
+// When relay is connected, proxies to user's local machine; otherwise uses server filesystem
+app.get('/api/browse-filesystem', authenticateToken, relayMiddleware, async (req, res) => {
+    try {
+        const { path: dirPath } = req.query;
+
+        // Cloud mode: always use relay
+        if (req.isCloud) {
+            if (!req.hasRelay()) {
+                return res.status(503).json({
+                    error: 'Machine not connected',
+                    message: 'Run "uc connect" on your local machine to use this feature.',
+                    code: 'RELAY_NOT_CONNECTED'
+                });
+            }
+            try {
+                const result = await req.sendRelay('browse-dirs', { dirPath: dirPath || '~' }, 15000);
+                return res.json(result);
+            } catch (err) {
+                return res.status(500).json({ error: err.message || 'Failed to browse filesystem via relay' });
+            }
+        }
+
+        // Local mode: if relay is connected, prefer it
+        if (req.hasRelay()) {
+            try {
+                const result = await req.sendRelay('browse-dirs', { dirPath: dirPath || '~' }, 15000);
+                return res.json(result);
+            } catch (err) {
+                return res.status(500).json({ error: err.message || 'Failed to browse filesystem via relay' });
+            }
+        }
+
+        // Fallback: browse server filesystem (local/self-hosted mode)
+        const defaultRoot = WORKSPACES_ROOT || os.homedir();
+        let targetPath = dirPath ? expandWorkspacePath(dirPath) : defaultRoot;
+
+        // Resolve and normalize the path
+        targetPath = path.resolve(targetPath);
+
+        // Security check - ensure path is within allowed workspace root
+        const validation = await validateWorkspacePath(targetPath);
+        if (!validation.valid) {
+            return res.status(403).json({ error: validation.error });
+        }
+        const resolvedPath = validation.resolvedPath || targetPath;
+
+        // Security check - ensure path is accessible
+        try {
+            await fs.promises.access(resolvedPath);
+            const stats = await fs.promises.stat(resolvedPath);
+
+            if (!stats.isDirectory()) {
+                return res.status(400).json({ error: 'Path is not a directory' });
+            }
+        } catch (err) {
+            return res.status(404).json({ error: 'Directory not accessible' });
+        }
+
+        // Use existing getFileTree function with shallow depth (only direct children)
+        const fileTree = await getFileTree(resolvedPath, 1, 0, false); // maxDepth=1, showHidden=false
+
+        // Filter only directories and format for suggestions
+        const directories = fileTree
+            .filter(item => item.type === 'directory')
+            .map(item => ({
+                path: item.path,
+                name: item.name,
+                type: 'directory'
+            }))
+            .sort((a, b) => {
+                const aHidden = a.name.startsWith('.');
+                const bHidden = b.name.startsWith('.');
+                if (aHidden && !bHidden) return 1;
+                if (!aHidden && bHidden) return -1;
+                return a.name.localeCompare(b.name);
+            });
+
+        // Add common directories if browsing home directory
+        const suggestions = [];
+        let resolvedWorkspaceRoot = defaultRoot;
+        try {
+            resolvedWorkspaceRoot = await fsPromises.realpath(defaultRoot);
+        } catch (error) {
+            // Use default root as-is if realpath fails
+        }
+        if (resolvedPath === resolvedWorkspaceRoot) {
+            const commonDirs = ['Desktop', 'Documents', 'Projects', 'Development', 'Dev', 'Code', 'workspace'];
+            const existingCommon = directories.filter(dir => commonDirs.includes(dir.name));
+            const otherDirs = directories.filter(dir => !commonDirs.includes(dir.name));
+            
+            suggestions.push(...existingCommon, ...otherDirs);
+        } else {
+            suggestions.push(...directories);
+        }
+        
+        res.json({
+            path: resolvedPath,
+            suggestions: suggestions
+        });
+        
+    } catch (error) {
+        // filesystem browse error handled silently
+        res.status(500).json({ error: 'Failed to browse filesystem' });
+    }
+});
+
+app.post('/api/create-folder', authenticateToken, relayMiddleware, async (req, res) => {
+    try {
+        const { path: folderPath } = req.body;
+        if (!folderPath) {
+            return res.status(400).json({ error: 'Path is required' });
+        }
+
+        // Cloud mode: create folder via relay on user's machine
+        if (req.isCloud) {
+            if (!req.requireRelay()) return;
+            try {
+                const result = await req.sendRelay('create-folder', { folderPath }, 15000);
+                return res.json(result);
+            } catch (err) {
+                return res.status(500).json({ error: err.message || 'Failed to create folder via relay' });
+            }
+        }
+
+        // Local mode
+        const expandedPath = expandWorkspacePath(folderPath);
+        const resolvedInput = path.resolve(expandedPath);
+        const validation = await validateWorkspacePath(resolvedInput);
+        if (!validation.valid) {
+            return res.status(403).json({ error: validation.error });
+        }
+        const targetPath = validation.resolvedPath || resolvedInput;
+        const parentDir = path.dirname(targetPath);
+        try {
+            await fs.promises.access(parentDir);
+        } catch (err) {
+            return res.status(404).json({ error: 'Parent directory does not exist' });
+        }
+        try {
+            await fs.promises.access(targetPath);
+            return res.status(409).json({ error: 'Folder already exists' });
+        } catch (err) {
+            // Folder doesn't exist, which is what we want
+        }
+        try {
+            await fs.promises.mkdir(targetPath, { recursive: false });
+            res.json({ success: true, path: targetPath });
+        } catch (mkdirError) {
+            if (mkdirError.code === 'EEXIST') {
+                return res.status(409).json({ error: 'Folder already exists' });
+            }
+            throw mkdirError;
+        }
+    } catch (error) {
+        // folder creation error handled silently
+        res.status(500).json({ error: 'Failed to create folder' });
+    }
+});
+
+// Read file content endpoint
+app.get('/api/projects/:projectName/file', authenticateToken, authorizeProject, relayMiddleware, async (req, res) => {
+    try {
+        const { projectName } = req.params;
+        const { filePath } = req.query;
+
+        if (!filePath) {
+            return res.status(400).json({ error: 'Invalid file path' });
+        }
+
+        const projectRoot = await extractProjectDirectory(projectName).catch(() => null);
+        if (!projectRoot) {
+            return res.status(404).json({ error: 'Project not found' });
+        }
+
+        // Cloud mode: read file via relay on user's machine
+        if (req.isCloud) {
+            if (!req.requireRelay()) return;
+            try {
+                // Construct full path: project root + relative file path
+                const fullPath = filePath.startsWith('/') || /^[A-Za-z]:/.test(filePath)
+                    ? filePath
+                    : `${projectRoot}/${filePath}`;
+                const result = await req.sendRelay('file-read', { filePath: fullPath }, 15000);
+                return res.json({ content: result.content, path: fullPath });
+            } catch (err) {
+                if (err.message?.includes('ENOENT') || err.message?.includes('not found')) {
+                    return res.status(404).json({ error: 'File not found' });
+                }
+                return res.status(500).json({ error: err.message || 'Failed to read file via relay' });
+            }
+        }
+
+        // Local mode
+        const resolved = path.resolve(projectRoot, filePath);
+        const normalizedRoot = path.resolve(projectRoot) + path.sep;
+        if (!resolved.startsWith(normalizedRoot) && resolved !== path.resolve(projectRoot)) {
+            return res.status(403).json({ error: 'Access denied' });
+        }
+
+        const content = await fsPromises.readFile(resolved, 'utf8');
+        res.json({ content, path: resolved });
+    } catch (error) {
+        if (error.code === 'ENOENT') {
+            res.status(404).json({ error: 'File not found' });
+        } else if (error.code === 'EACCES') {
+            res.status(403).json({ error: 'Permission denied' });
+        } else {
+            res.status(500).json({ error: 'Internal server error' });
+        }
+    }
+});
+
+// Serve binary file content endpoint (for images, etc.)
+app.get('/api/projects/:projectName/files/content', authenticateToken, authorizeProject, relayMiddleware, async (req, res) => {
+    try {
+        const { projectName } = req.params;
+        const { path: filePath } = req.query;
+
+        if (!filePath) {
+            return res.status(400).json({ error: 'Invalid file path' });
+        }
+
+        const projectRoot = await extractProjectDirectory(projectName).catch(() => null);
+        if (!projectRoot) {
+            return res.status(404).json({ error: 'Project not found' });
+        }
+
+        // Cloud mode: read binary file via relay (base64 encoded)
+        if (req.isCloud) {
+            if (!req.requireRelay()) return;
+            try {
+                const fullPath = filePath.startsWith('/') || /^[A-Za-z]:/.test(filePath)
+                    ? filePath
+                    : `${projectRoot}/${filePath}`;
+                const result = await req.sendRelay('file-read', { filePath: fullPath, encoding: 'base64' }, 30000);
+                const mimeType = mime.lookup(fullPath) || 'application/octet-stream';
+                res.setHeader('Content-Type', mimeType);
+                return res.send(Buffer.from(result.content, 'base64'));
+            } catch (err) {
+                if (err.message?.includes('ENOENT') || err.message?.includes('not found')) {
+                    return res.status(404).json({ error: 'File not found' });
+                }
+                return res.status(500).json({ error: err.message || 'Failed to read file via relay' });
+            }
+        }
+
+        // Local mode
+        const resolved = path.resolve(projectRoot, filePath);
+        const normalizedRoot = path.resolve(projectRoot) + path.sep;
+        if (!resolved.startsWith(normalizedRoot) && resolved !== path.resolve(projectRoot)) {
+            return res.status(403).json({ error: 'Access denied' });
+        }
+
+        try {
+            await fsPromises.access(resolved);
+        } catch (error) {
+            return res.status(404).json({ error: 'File not found' });
+        }
+
+        const mimeType = mime.lookup(resolved) || 'application/octet-stream';
+        res.setHeader('Content-Type', mimeType);
+
+        const fileStream = fs.createReadStream(resolved);
+        fileStream.pipe(res);
+
+        fileStream.on('error', (error) => {
+            if (!res.headersSent) {
+                res.status(500).json({ error: 'Error reading file' });
+            }
+        });
+
+    } catch (error) {
+        if (!res.headersSent) {
+            res.status(500).json({ error: 'Internal server error' });
+        }
+    }
+});
+
+// Save file content endpoint
+app.put('/api/projects/:projectName/file', authenticateToken, authorizeProject, relayMiddleware, async (req, res) => {
+    try {
+        const { projectName } = req.params;
+        const { filePath, content } = req.body;
+
+        if (!filePath) {
+            return res.status(400).json({ error: 'Invalid file path' });
+        }
+
+        if (content === undefined) {
+            return res.status(400).json({ error: 'Content is required' });
+        }
+
+        const projectRoot = await extractProjectDirectory(projectName).catch(() => null);
+        if (!projectRoot) {
+            return res.status(404).json({ error: 'Project not found' });
+        }
+
+        // Cloud mode: write file via relay on user's machine
+        if (req.isCloud) {
+            if (!req.requireRelay()) return;
+            try {
+                const fullPath = filePath.startsWith('/') || /^[A-Za-z]:/.test(filePath)
+                    ? filePath
+                    : `${projectRoot}/${filePath}`;
+                const result = await req.sendRelay('file-write', { filePath: fullPath, content }, 15000);
+                // Track file version in Turso
+                try { await fileVersionDb.save(req.user.userId || req.user.id, projectName, filePath, content, 'edit'); } catch { /* non-critical */ }
+                return res.json({ success: true, path: fullPath, message: 'File saved successfully' });
+            } catch (err) {
+                return res.status(500).json({ error: err.message || 'Failed to write file via relay' });
+            }
+        }
+
+        // Local mode
+        const resolved = path.resolve(projectRoot, filePath);
+        const normalizedRoot = path.resolve(projectRoot) + path.sep;
+        if (!resolved.startsWith(normalizedRoot) && resolved !== path.resolve(projectRoot)) {
+            return res.status(403).json({ error: 'Access denied' });
+        }
+
+        await fsPromises.writeFile(resolved, content, 'utf8');
+        // Track file version
+        try { await fileVersionDb.save(req.user?.userId || req.user?.id || 'local', projectName, filePath, content, 'edit'); } catch { /* non-critical */ }
+
+        res.json({
+            success: true,
+            path: resolved,
+            message: 'File saved successfully'
+        });
+    } catch (error) {
+        if (error.code === 'ENOENT') {
+            res.status(404).json({ error: 'File or directory not found' });
+        } else if (error.code === 'EACCES') {
+            res.status(403).json({ error: 'Permission denied' });
+        } else {
+            res.status(500).json({ error: 'Internal server error' });
+        }
+    }
+});
+
+// File version history endpoint
+app.get('/api/projects/:projectName/files/versions', authenticateToken, authorizeProject, async (req, res) => {
+    try {
+        const { projectName } = req.params;
+        const { path: filePath, limit } = req.query;
+        if (filePath) {
+            const versions = await fileVersionDb.getVersions(projectName, filePath, parseInt(limit) || 20);
+            return res.json({ versions });
+        }
+        // No path — return all files with versions in this project
+        const files = await fileVersionDb.getSessionFiles(projectName);
+        res.json({ files });
+    } catch (error) {
+        res.status(500).json({ error: 'Internal server error' });
+    }
+});
+
+// Usage stats endpoint
+app.get('/api/usage', authenticateToken, async (req, res) => {
+    try {
+        const userId = req.user.userId || req.user.id;
+        const days = parseInt(req.query.days) || 30;
+        const usage = await sessionUsageDb.getUserUsage(userId, days);
+        const sessions = await sessionUsageDb.getUserSessions(userId, parseInt(req.query.limit) || 20);
+        res.json({ usage, sessions });
+    } catch (error) {
+        res.status(500).json({ error: 'Internal server error' });
+    }
+});
+
+app.get('/api/projects/:projectName/files', authenticateToken, authorizeProject, relayMiddleware, async (req, res) => {
+    try {
+        let actualPath;
+        try {
+            actualPath = await extractProjectDirectory(req.params.projectName);
+        } catch (error) {
+            actualPath = req.params.projectName.replace(/-/g, '/');
+        }
+
+        // Cloud mode: get file tree via relay on user's machine
+        if (req.isCloud) {
+            if (!req.requireRelay()) return;
+            try {
+                // In cloud mode, actualPath comes from extractProjectDirectory (which stores the original
+                // Windows/Unix path from when the project was added via relay CWD). If that failed and
+                // fell back to dash-replacement, use the relay connection's CWD as a better fallback.
+                const relay = relayConnections.get(Number(req.user?.id));
+                const relayCwd = relay?.cwd;
+                const dirPath = actualPath && actualPath !== req.params.projectName.replace(/-/g, '/')
+                    ? actualPath
+                    : (relayCwd || actualPath);
+                const result = await req.sendRelay('file-tree', { dirPath, maxDepth: 10 }, 30000);
+                return res.json(result.files || result);
+            } catch (err) {
+                return res.status(500).json({ error: err.message || 'Failed to get file tree via relay' });
+            }
+        }
+
+        // Local mode
+        try {
+            await fsPromises.access(actualPath);
+        } catch (e) {
+            return res.status(404).json({ error: `Project path not found: ${actualPath}` });
+        }
+
+        const files = await getFileTree(actualPath, 10, 0, true);
+        res.json(files);
+    } catch (error) {
+        res.status(500).json({ error: 'Internal server error' });
+    }
+});
+
+// WebSocket connection handler that routes based on URL path (skip on Vercel)
+if (wss) wss.on('connection', (ws, request) => {
+    const url = request.url;
+    // Client connected
+
+    // Parse URL to get pathname without query parameters
+    const urlObj = new URL(url, 'http://localhost');
+    const pathname = urlObj.pathname;
+
+    if (pathname === '/shell') {
+        handleShellConnection(ws, request);
+    } else if (pathname === '/ws') {
+        handleChatConnection(ws, request);
+    } else if (pathname === '/relay') {
+        handleRelayConnection(ws, urlObj.searchParams.get('token'), request);
+    } else {
+        // unknown WebSocket path
+        ws.close();
+    }
+});
+
+/**
+ * WebSocket Writer - Wrapper for WebSocket to match SSEStreamWriter interface
+ */
+class WebSocketWriter {
+  constructor(ws) {
+    this.ws = ws;
+    this.sessionId = null;
+    this.isWebSocketWriter = true;  // Marker for transport detection
+  }
+
+  send(data) {
+    if (this.ws.readyState === 1) { // WebSocket.OPEN
+      // Providers send raw objects, we stringify for WebSocket
+      this.ws.send(JSON.stringify(data));
+    }
+  }
+
+  setSessionId(sessionId) {
+    this.sessionId = sessionId;
+  }
+
+  getSessionId() {
+    return this.sessionId;
+  }
+}
+
+/**
+ * Look up a user's stored API key for a given provider.
+ * Falls back to server env vars if user has none stored.
+ * @param {number} userId
+ * @param {string} providerType - e.g. 'anthropic_key', 'openai_key', 'openrouter_key', 'google_key'
+ * @returns {Promise<string|null>}
+ */
+async function getUserProviderKey(userId, providerType) {
+    if (!userId) return null;
+    try {
+        const creds = await credentialsDb.getCredentials(userId, providerType);
+        const active = creds.find(c => c.is_active);
+        return active?.credential_value || null;
+    } catch { return null; }
+}
+
+/**
+ * Temporarily set environment variable for an AI SDK call, then restore.
+ * @param {string} envKey - e.g. 'ANTHROPIC_API_KEY'
+ * @param {string|null} userKey - user's BYOK key, null to skip
+ * @param {Function} fn - async function to execute with the key set
+ */
+async function withUserApiKey(envKey, userKey, fn) {
+    if (!userKey) return fn();
+    const prev = process.env[envKey];
+    process.env[envKey] = userKey;
+    try {
+        return await fn();
+    } finally {
+        if (prev !== undefined) process.env[envKey] = prev;
+        else delete process.env[envKey];
+    }
+}
+
+// Handle chat WebSocket connections
+function handleChatConnection(ws, request) {
+    // chat WebSocket connected
+    const wsUser = request?.user || null;
+
+    // Add to connected clients for project updates + tag with user for permission routing
+    ws._wsUser = wsUser;
+    connectedClients.add(ws);
+
+    // Wrap WebSocket with writer for consistent interface with SSEStreamWriter
+    const writer = new WebSocketWriter(ws);
+
+    // Track which sessions this WebSocket has locked
+    const lockedSessionsForThisWs = new Set();
+
+    // Track usage per-query for sessionUsageDb
+    let lastTokenBudget = null;
+    let lastCompletedSessionId = null;
+
+    // Wrap the original writer.send to capture session-created events for auto-locking
+    const originalSend = writer.send.bind(writer);
+    writer.send = (data) => {
+        // When a new session is created, auto-lock it to this WebSocket + track ownership
+        if (data.type === 'session-created' && data.sessionId) {
+            sessionLocks.set(data.sessionId, ws);
+            lockedSessionsForThisWs.add(data.sessionId);
+            if (wsUser?.userId) sessionOwners.set(data.sessionId, wsUser.userId);
+        }
+        // Capture token usage for tracking
+        if (data.type === 'token-budget' && data.data) {
+            lastTokenBudget = data.data;
+            if (data.sessionId) lastCompletedSessionId = data.sessionId;
+        }
+        originalSend(data);
+    };
+
+    ws.on('message', async (message) => {
+        try {
+            const data = JSON.parse(message);
+
+            // Handle session lock request (tab claiming a session)
+            if (data.type === 'lock-session') {
+                const sid = data.sessionId;
+                if (!sid) return;
+                if (acquireSessionLock(sid, ws)) {
+                    lockedSessionsForThisWs.add(sid);
+                    writer.send({ type: 'session-locked', sessionId: sid, success: true });
+                    // session locked to tab
+                } else {
+                    writer.send({ type: 'session-locked', sessionId: sid, success: false,
+                        error: 'Session is already open in another tab' });
+                    // session lock denied
+                }
+                return;
+            }
+
+            // Handle session unlock request
+            if (data.type === 'unlock-session') {
+                const sid = data.sessionId;
+                if (sid) {
+                    releaseSessionLock(sid, ws);
+                    lockedSessionsForThisWs.delete(sid);
+                    writer.send({ type: 'session-unlocked', sessionId: sid });
+                    // session unlocked
+                }
+                return;
+            }
+
+            if (data.type === 'shell-exec') {
+                const { command, cwd } = data;
+                if (!command) {
+                    writer.send({ type: 'shell-exec-output', output: 'No command provided.', exitCode: 1, status: 'error' });
+                    return;
+                }
+
+                if (hasActiveRelay(wsUser?.userId)) {
+                    try {
+                        const result = await sendRelayCommand(Number(wsUser.userId), 'exec', { command, cwd }, null, 30000);
+                        const output = result?.data?.stdout || result?.data?.output || result?.data?.stderr || '';
+                        writer.send({ type: 'shell-exec-output', output, exitCode: result?.data?.exitCode ?? 0, status: 'complete' });
+                    } catch (err) {
+                        writer.send({ type: 'shell-exec-output', output: err.message || 'Command execution failed.', exitCode: 1, status: 'error' });
+                    }
+                } else {
+                    writer.send({ type: 'shell-exec-output', output: 'No machine connected. Use `uc connect` to bridge your local machine.', exitCode: 1, status: 'error' });
+                }
+                return;
+            }
+
+            if (data.type === 'claude-command') {
+                const sid = data.options?.sessionId;
+
+                // Session-tab locking: check if this session is locked by another tab
+                if (sid && !acquireSessionLock(sid, ws)) {
+                    writer.send({
+                        type: 'session-lock-denied',
+                        sessionId: sid,
+                        error: 'This session is already active in another tab. Close it there first.'
+                    });
+                    return;
+                }
+                if (sid) lockedSessionsForThisWs.add(sid);
+
+                // Session busy detection (opencode pattern: prevent duplicate requests)
+                if (sid && !markSessionBusy(sid)) {
+                    writer.send({
+                        type: 'session-busy',
+                        sessionId: sid,
+                        error: 'This session is already processing a request. Wait for it to finish or abort it first.'
+                    });
+                    return;
+                }
+
+                try {
+                // Check if user has active relay → route to local machine
+                if (hasActiveRelay(wsUser?.userId)) {
+                    // Lightweight gitagent check — 1.5s timeout, non-blocking on failure
+                    if (data.options?.cwd) {
+                      try {
+                        const gaResult = await sendRelayCommand(Number(wsUser.userId), 'gitagent-parse', { projectPath: data.options.cwd }, null, 1500);
+                        if (gaResult?.data?.definition) {
+                          const appendix = buildSystemPromptAppendix(gaResult.data.definition);
+                          data.command = `<gitagent-context>\n${appendix}\n</gitagent-context>\n\n${data.command}`;
+                        }
+                      } catch { /* not gitagent or timed out — proceed without delay */ }
+                    }
+                    await routeViaRelay(wsUser.userId, 'claude-query', data, writer, {
+                        response: 'claude-response',
+                        complete: 'claude-complete',
+                        error: 'claude-error'
+                    });
+                } else {
+                    // No relay — try sandbox fallback, then server-side SDK
+                    try {
+                        const sandboxHandled = wsUser?.userId
+                            ? await handleSandboxWebSocketCommand(wsUser.userId, 'claude-command', { ...data, sessionId: data.options?.sessionId }, writer)
+                            : false;
+
+                        if (!sandboxHandled) {
+                            // Fall back to server-side SDK
+                            const userAnthropicKey = wsUser?.userId
+                                ? await getUserProviderKey(wsUser.userId, 'anthropic_key')
+                                : null;
+
+                            await withUserApiKey('ANTHROPIC_API_KEY', userAnthropicKey, () =>
+                                queryClaudeSDK(data.command, data.options, writer)
+                            );
+                        }
+                    } catch {
+                        // SDK fallback failed — send claude-error (not generic error)
+                        // so the frontend stops the spinner instead of hanging forever
+                        writer.send({
+                            type: 'claude-error',
+                            error: 'No machine connected and server-side AI is unavailable. Please connect with "uc connect" and try again.',
+                            sessionId: sid
+                        });
+                    }
+                }
+                } finally {
+                    markSessionFree(sid);
+                    // Track session usage in Turso
+                    if (wsUser?.userId && lastTokenBudget) {
+                        const usageSessionId = lastCompletedSessionId || sid || 'unknown';
+                        try {
+                            await sessionUsageDb.upsert(wsUser.userId, usageSessionId, {
+                                provider: 'claude',
+                                promptTokens: lastTokenBudget.used || 0,
+                                completionTokens: 0,
+                                costCents: 0,
+                                model: data.options?.model || null,
+                            });
+                        } catch { /* non-critical */ }
+                        lastTokenBudget = null;
+                        lastCompletedSessionId = null;
+                    }
+                }
+            } else if (data.type === 'cursor-command') {
+                // Check if user has active relay → route to local machine
+                if (hasActiveRelay(wsUser?.userId)) {
+                    await routeViaRelay(wsUser.userId, 'cursor-query', data, writer, {
+                        response: 'cursor-response',
+                        complete: 'cursor-complete',
+                        error: 'cursor-error'
+                    });
+                } else {
+                    await spawnCursor(data.command, data.options, writer);
+                }
+            } else if (data.type === 'codex-command') {
+                // Check if user has active relay → route to local machine
+                if (hasActiveRelay(wsUser?.userId)) {
+                    await routeViaRelay(wsUser.userId, 'codex-query', data, writer, {
+                        response: 'codex-response',
+                        complete: 'codex-complete',
+                        error: 'codex-error'
+                    });
+                } else {
+                    const userOpenaiKey = wsUser?.userId
+                        ? await getUserProviderKey(wsUser.userId, 'openai_key')
+                        : null;
+
+                    await withUserApiKey('OPENAI_API_KEY', userOpenaiKey, () =>
+                        queryCodex(data.command, data.options, writer)
+                    );
+                }
+            } else if (data.type === 'openrouter-command') {
+                // BYOK: OpenRouter requires user's own API key
+                const userOrKey = wsUser?.userId
+                    ? await getUserProviderKey(wsUser.userId, 'openrouter_key')
+                    : null;
+
+                await queryOpenRouter(data.command, {
+                    ...data.options,
+                    apiKey: userOrKey,
+                }, writer);
+            } else if (data.type === 'cursor-resume') {
+                // Backward compatibility: treat as cursor-command with resume and no prompt
+                // cursor resume session
+                await spawnCursor('', {
+                    sessionId: data.sessionId,
+                    resume: true,
+                    cwd: data.options?.cwd
+                }, writer);
+            } else if (data.type === 'abort-session') {
+                // abort session request
+                const provider = data.provider || 'claude';
+                let success;
+
+                // Check if this is a relay session first (opencode pattern: cancel propagation)
+                const relayInfo = relaySessionRequests.get(data.sessionId);
+                if (relayInfo) {
+                    const relay = relayConnections.get(relayInfo.userId);
+                    if (relay && relay.ws.readyState === 1) {
+                        // Forward abort to CLI via relay WebSocket
+                        relay.ws.send(JSON.stringify({
+                            type: 'relay-abort',
+                            requestId: relayInfo.requestId,
+                        }));
+                        // Clean up pending relay request
+                        const pending = pendingRelayRequests.get(relayInfo.requestId);
+                        if (pending) {
+                            clearTimeout(pending.timeout);
+                            pending.resolve({ exitCode: -1, aborted: true });
+                            pendingRelayRequests.delete(relayInfo.requestId);
+                        }
+                        relaySessionRequests.delete(data.sessionId);
+                        success = true;
+                    } else {
+                        success = false;
+                    }
+                } else if (provider === 'cursor') {
+                    success = abortCursorSession(data.sessionId);
+                } else if (provider === 'codex') {
+                    success = abortCodexSession(data.sessionId);
+                } else {
+                    // Use Claude Agents SDK
+                    success = await abortClaudeSDKSession(data.sessionId);
+                }
+
+                writer.send({
+                    type: 'session-aborted',
+                    sessionId: data.sessionId,
+                    provider,
+                    success
+                });
+            } else if (data.type === 'claude-permission-response') {
+                // Relay UI approval decisions back into the SDK control flow.
+                // This does not persist permissions; it only resolves the in-flight request,
+                // introduced so the SDK can resume once the user clicks Allow/Deny.
+                if (data.requestId) {
+                    resolveToolApproval(data.requestId, {
+                        allow: Boolean(data.allow),
+                        updatedInput: data.updatedInput,
+                        message: data.message,
+                        rememberEntry: data.rememberEntry
+                    });
+                }
+            } else if (data.type === 'relay-permission-response') {
+                // Forward permission response from browser → CLI relay (opencode pattern)
+                if (wsUser?.userId && hasActiveRelay(wsUser.userId)) {
+                    const relay = relayConnections.get(Number(wsUser.userId));
+                    if (relay?.ws?.readyState === 1) {
+                        relay.ws.send(JSON.stringify({
+                            type: 'relay-permission-response',
+                            permissionId: data.permissionId,
+                            approved: data.approved,
+                        }));
+                    }
+                }
+            } else if (data.type === 'cursor-abort') {
+                // abort cursor session
+                const success = abortCursorSession(data.sessionId);
+                writer.send({
+                    type: 'session-aborted',
+                    sessionId: data.sessionId,
+                    provider: 'cursor',
+                    success
+                });
+            } else if (data.type === 'check-session-status') {
+                // Check if a specific session is currently processing
+                const provider = data.provider || 'claude';
+                const sessionId = data.sessionId;
+                let isActive;
+
+                if (provider === 'cursor') {
+                    isActive = isCursorSessionActive(sessionId);
+                } else if (provider === 'codex') {
+                    isActive = isCodexSessionActive(sessionId);
+                } else {
+                    // Use Claude Agents SDK
+                    isActive = isClaudeSDKSessionActive(sessionId);
+                }
+
+                writer.send({
+                    type: 'session-status',
+                    sessionId,
+                    provider,
+                    isProcessing: isActive
+                });
+            } else if (data.type === 'get-active-sessions') {
+                // Get all currently active sessions
+                const activeSessions = {
+                    claude: getActiveClaudeSDKSessions(),
+                    cursor: getActiveCursorSessions(),
+                    codex: getActiveCodexSessions()
+                };
+                writer.send({
+                    type: 'active-sessions',
+                    sessions: activeSessions
+                });
+            } else if (data.type === 'subscribe-session') {
+                // Multi-tab read access: subscribe to session output without locking
+                const sid = data.sessionId;
+                if (sid) {
+                    subscribeToSession(sid, ws);
+                    writer.send({ type: 'session-subscribed', sessionId: sid });
+                }
+            } else if (data.type === 'unsubscribe-session') {
+                const sid = data.sessionId;
+                if (sid) {
+                    unsubscribeFromSession(sid, ws);
+                    writer.send({ type: 'session-unsubscribed', sessionId: sid });
+                }
+            }
+        } catch (error) {
+            // chat WebSocket error
+            writer.send({
+                type: 'error',
+                error: 'An unexpected error occurred'
+            });
+        }
+    });
+
+    ws.on('close', () => {
+        // Chat client disconnected
+        // Release all session locks held by this WebSocket
+        releaseAllLocksForWs(ws);
+        unsubscribeAllForWs(ws);
+        // Remove from connected clients
+        connectedClients.delete(ws);
+    });
+}
+
+// Handle relay WebSocket connections (local machine ↔ server bridge)
+async function handleRelayConnection(ws, token, request) {
+    if (!token) {
+        ws.send(JSON.stringify({ type: 'error', error: 'Relay token required. Use ?token=upfyn_xxx' }));
+        ws.close();
+        return;
+    }
+
+    // Extract and pin client IP for this relay session
+    const clientIp = extractClientIp(request);
+
+    const tokenData = await relayTokensDb.validateToken(token, clientIp);
+    if (!tokenData) {
+        ws.send(JSON.stringify({ type: 'error', error: 'Invalid or expired relay token' }));
+        ws.close();
+        return;
+    }
+
+    const userId = Number(tokenData.user_id);
+    const username = tokenData.username;
+
+    // Reject if another relay is already connected for this user from a DIFFERENT IP
+    // This prevents session hijacking — only the original machine can hold the relay
+    const existingRelay = relayConnections.get(userId);
+    if (existingRelay && existingRelay.ws.readyState === 1 && existingRelay.clientIp !== clientIp) {
+        ws.send(JSON.stringify({
+            type: 'error',
+            error: 'Another machine is already connected for this account. Disconnect it first or use a different token.'
+        }));
+        ws.close();
+        return;
+    }
+
+    // Extract optional headers from relay handshake
+    const anthropicApiKey = request?.headers?.['x-anthropic-api-key'] || null;
+    const relayVersion = request?.headers?.['x-upfyn-version'] || null;
+    const relayMachine = request?.headers?.['x-upfyn-machine'] || null;
+    const relayPlatform = request?.headers?.['x-upfyn-platform'] || null;
+    const relayCwd = request?.headers?.['x-upfyn-cwd'] || null;
+
+    // Store relay connection with IP pinning — all commands must originate from authenticated user
+    // API key is held per-user in the relay connection, NOT in process.env
+    relayConnections.set(userId, {
+        ws, user: tokenData, connectedAt: Date.now(), anthropicApiKey,
+        version: relayVersion, machine: relayMachine, platform: relayPlatform, cwd: relayCwd,
+        agents: null, // populated when client sends agent-capabilities
+        lastPong: Date.now(),
+        clientIp,     // Pinned IP — used for security validation
+        tokenId: tokenData.id, // Token ID used for this connection
+    });
+
+    ws.send(JSON.stringify({
+        type: 'relay-connected',
+        message: `Connected as ${username}. Your local machine is now bridged to the server.`
+    }));
+
+    // Auto-add relay CWD as a project so the user lands with a ready workspace
+    if (relayCwd) {
+        try {
+            await addProjectManually(relayCwd, null, userId);
+        } catch { /* project may already exist, ignore */ }
+    }
+
+    // Cancel any pending sandbox cleanup (user reconnected within grace period)
+    const pendingCleanup = sandboxCleanupTimers.get(userId);
+    if (pendingCleanup) {
+        clearTimeout(pendingCleanup);
+        sandboxCleanupTimers.delete(userId);
+    }
+
+    // Initialize sandbox for user isolation (reuses existing if still alive)
+    let sandboxActive = false;
+    try {
+        // Check if sandbox is still running from previous session
+        const status = await sandboxClient.getStatus(userId).catch(() => null);
+        if (status?.running) {
+            sandboxActive = true;
+        } else {
+            await sandboxClient.initSandbox(userId, { projectName: relayCwd });
+            sandboxActive = true;
+        }
+    } catch { /* sandbox is optional — don't block relay */ }
+
+    // Track active connection in Turso (with last cwd/machine/platform for smooth reconnection)
+    try { await connectionDb.connect(String(userId), relayCwd, 'relay', sandboxActive ? String(userId) : null, { cwd: relayCwd, machine: relayMachine, platform: relayPlatform }); } catch { /* non-critical */ }
+
+    // Broadcast relay status to this user's browser clients only
+    for (const client of connectedClients) {
+        try {
+            if (client.readyState === 1 && client._wsUser?.userId === userId) {
+                client.send(JSON.stringify({
+                    type: 'relay-status',
+                    userId,
+                    connected: true,
+                    cwd: relayCwd,
+                    machine: relayMachine,
+                    platform: relayPlatform,
+                    sandboxActive,
+                }));
+            }
+        } catch (e) { /* ignore */ }
+    }
+
+    // Native WebSocket pong handler — Railway proxy recognizes protocol-level
+    // ping/pong as keepalive, preventing idle connection termination
+    ws.on('pong', () => {
+        const relay = relayConnections.get(userId);
+        if (relay && relay.ws === ws) relay.lastPong = Date.now();
+    });
+
+    ws.on('message', async (message) => {
+        try {
+            const data = JSON.parse(message);
+
+            // Relay response from local machine → resolve pending request
+            if (data.type === 'relay-response' && data.requestId) {
+                const pending = pendingRelayRequests.get(data.requestId);
+                if (pending) {
+                    clearTimeout(pending.timeout);
+                    pendingRelayRequests.delete(data.requestId);
+                    // If CLI sent an error, reject; otherwise unwrap data.data
+                    if (data.error) {
+                        pending.reject(new Error(data.error));
+                    } else {
+                        pending.resolve(data.data || data);
+                    }
+                }
+                return;
+            }
+
+            // Relay stream chunk from local machine → forward to browser WebSocket
+            if (data.type === 'relay-stream' && data.requestId) {
+                const pending = pendingRelayRequests.get(data.requestId);
+                if (pending && pending.onStream) {
+                    pending.onStream(data.data);
+                }
+                return;
+            }
+
+            // Relay complete signal
+            if (data.type === 'relay-complete' && data.requestId) {
+                const pending = pendingRelayRequests.get(data.requestId);
+                if (pending) {
+                    clearTimeout(pending.timeout);
+                    pendingRelayRequests.delete(data.requestId);
+                    pending.resolve(data);
+                }
+                return;
+            }
+
+            // Permission request from CLI → forward to browser (opencode pattern)
+            if (data.type === 'relay-permission-request') {
+                for (const client of connectedClients) {
+                    try {
+                        if (client.readyState === 1 && client._wsUser?.userId === userId) {
+                            client.send(JSON.stringify({
+                                type: 'relay-permission-request',
+                                ...data,
+                            }));
+                        }
+                    } catch { /* ignore */ }
+                }
+                return;
+            }
+
+            // Agent capabilities report from relay client
+            if (data.type === 'agent-capabilities') {
+                const relay = relayConnections.get(userId);
+                if (relay) {
+                    relay.agents = data.agents || {};
+                    relay.machine = data.machine || relay.machine;
+                }
+                // Broadcast agent info to this user's browser clients only
+                for (const client of connectedClients) {
+                    try {
+                        if (client.readyState === 1 && client._wsUser?.userId === userId) {
+                            client.send(JSON.stringify({
+                                type: 'relay-agents',
+                                userId,
+                                agents: data.agents || {},
+                                machine: data.machine || {}
+                            }));
+                        }
+                    } catch (e) { /* ignore */ }
+                }
+                return;
+            }
+
+            // Relay shell output from CLI → forward to browser shell WebSocket
+            if (data.type === 'relay-shell-output' && data.shellSessionId) {
+                const browserWs = relayShellBrowserSockets.get(data.shellSessionId);
+                if (browserWs?.readyState === 1) {
+                    browserWs.send(JSON.stringify({ type: 'output', data: data.data }));
+                }
+                return;
+            }
+
+            // Relay shell exited on CLI
+            if (data.type === 'relay-shell-exited' && data.shellSessionId) {
+                const browserWs = relayShellBrowserSockets.get(data.shellSessionId);
+                if (browserWs?.readyState === 1) {
+                    browserWs.send(JSON.stringify({
+                        type: 'output',
+                        data: `\r\n\x1b[33mProcess exited with code ${data.exitCode ?? 0}\x1b[0m\r\n`
+                    }));
+                }
+                relayShellBrowserSockets.delete(data.shellSessionId);
+                return;
+            }
+
+            // Relay shell auth URL detected
+            if (data.type === 'relay-shell-auth-url' && data.shellSessionId) {
+                const browserWs = relayShellBrowserSockets.get(data.shellSessionId);
+                if (browserWs?.readyState === 1) {
+                    browserWs.send(JSON.stringify({ type: 'auth_url', url: data.url, autoOpen: data.autoOpen }));
+                }
+                return;
+            }
+
+            // Relay init: CLI sends working directory after connect
+            // Auto-register CWD as default project so user lands with a ready workspace
+            if (data.type === 'relay-init') {
+                const relay = relayConnections.get(userId);
+                if (relay) {
+                    relay.cwd = data.cwd || relay.cwd;
+                    relay.platform = data.platform || relay.platform;
+                    relay.machine = data.hostname || relay.machine;
+                }
+                // Auto-add CWD as project (pass userId for cloud DB storage)
+                if (data.cwd) {
+                    try {
+                        await addProjectManually(data.cwd, null, userId);
+                    } catch { /* already exists */ }
+                }
+                // Broadcast to browser so it auto-selects this project
+                for (const client of connectedClients) {
+                    try {
+                        if (client.readyState === 1) {
+                            client.send(JSON.stringify({
+                                type: 'relay-init',
+                                userId,
+                                cwd: data.cwd,
+                                dirName: data.dirName,
+                                platform: data.platform,
+                            }));
+                        }
+                    } catch { /* ignore */ }
+                }
+                return;
+            }
+
+            // Heartbeat
+            if (data.type === 'ping') {
+                const relay = relayConnections.get(userId);
+                if (relay) relay.lastPong = Date.now();
+                ws.send(JSON.stringify({ type: 'pong' }));
+                return;
+            }
+        } catch (e) {
+            // relay message processing error
+        }
+    });
+
+    // Server-side heartbeat: ping relay client every 25s, terminate if no pong in 60s
+    const relayHeartbeat = setInterval(() => {
+        const relay = relayConnections.get(userId);
+        if (!relay || relay.ws !== ws) {
+            clearInterval(relayHeartbeat);
+            return;
+        }
+        // If no ping received from client in 60s, consider connection stale
+        if (Date.now() - relay.lastPong > 60000) {
+            clearInterval(relayHeartbeat);
+            ws.terminate();
+            return;
+        }
+        // Send native WebSocket ping frame — recognized by Railway proxy as keepalive
+        try { ws.ping(); } catch { /* ignore */ }
+        // Also send JSON-level ping to keep application-layer alive
+        try {
+            if (ws.readyState === 1) {
+                ws.send(JSON.stringify({ type: 'server-ping' }));
+            }
+        } catch { /* ignore */ }
+    }, 25000);
+
+    ws.on('close', async () => {
+        clearInterval(relayHeartbeat);
+
+        // Guard: only delete if THIS ws is still the active relay for this user.
+        // Prevents race condition where CLI reconnects quickly and the old close
+        // handler fires after the new connection is stored, wiping it out.
+        const currentRelay = relayConnections.get(userId);
+        if (!currentRelay || currentRelay.ws !== ws) {
+            // New connection already replaced this one — skip all cleanup
+            return;
+        }
+
+        relayConnections.delete(userId);
+
+        // Clean up pending requests for this user (relay is truly gone)
+        for (const [reqId, pending] of pendingRelayRequests) {
+            if (pending.userId === userId) {
+                clearTimeout(pending.timeout);
+                pending.reject(new Error('Relay disconnected'));
+                pendingRelayRequests.delete(reqId);
+            }
+        }
+
+        // Track disconnection in Turso (but keep sandbox alive for grace period)
+        try { await connectionDb.disconnect(String(userId), 'relay'); } catch { /* non-critical */ }
+
+        // Schedule sandbox cleanup after grace period (5 min)
+        // If user reconnects within this window, the timer is cancelled and sandbox reused
+        const cleanupTimer = setTimeout(async () => {
+            sandboxCleanupTimers.delete(userId);
+            // Only destroy if user hasn't reconnected
+            if (!relayConnections.has(userId)) {
+                try { await sandboxClient.destroySandbox(userId); } catch { /* best-effort */ }
+            }
+        }, SANDBOX_GRACE_PERIOD_MS);
+        sandboxCleanupTimers.set(userId, cleanupTimer);
+
+        // Broadcast relay disconnect to this user's browser clients only
+        // Note: sandboxActive stays true during grace period (sandbox is still alive)
+        for (const client of connectedClients) {
+            try {
+                if (client.readyState === 1 && client._wsUser?.userId === userId) {
+                    client.send(JSON.stringify({ type: 'relay-status', userId, connected: false, sandboxActive: true }));
+                }
+            } catch (e) { /* ignore */ }
+        }
+    });
+
+    ws.on('error', () => {
+        clearInterval(relayHeartbeat);
+    });
+}
+
+/**
+ * Retry helper with exponential backoff (opencode pattern)
+ * Only retries on transient errors (timeout, disconnection). Not for validation/security.
+ */
+async function withRetry(fn, { maxRetries = 3, baseDelayMs = 2000, jitter = 0.2 } = {}) {
+    let lastError;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+            return await fn();
+        } catch (err) {
+            lastError = err;
+            const msg = err.message || '';
+            const isTransient = msg.includes('timed out') || msg.includes('disconnected');
+            if (!isTransient || attempt === maxRetries) throw err;
+            const delay = baseDelayMs * Math.pow(2, attempt) * (1 + (Math.random() * jitter * 2 - jitter));
+            await new Promise(r => setTimeout(r, delay));
+        }
+    }
+    throw lastError;
+}
+
+/**
+ * Send a command to a user's relay and wait for response
+ * @param {number} userId - User ID
+ * @param {string} action - Action type (claude-query, shell-command, file-read, etc.)
+ * @param {object} payload - Action payload
+ * @param {function} onStream - Optional callback for streaming chunks
+ * @param {number} timeoutMs - Timeout in milliseconds (default 5 min)
+ * @returns {Promise<object>} Relay response
+ */
+function sendRelayCommand(userId, action, payload, onStream = null, timeoutMs = 300000, externalRequestId = null) {
+    return new Promise((resolve, reject) => {
+        const relay = relayConnections.get(userId);
+        if (!relay || relay.ws.readyState !== 1) {
+            reject(new Error('No relay connection. Run "uc connect" on your local machine.'));
+            return;
+        }
+
+        // Security: validate action is in allowlist and payload is safe
+        const validation = validateRelayPayload(action, payload);
+        if (!validation.valid) {
+            reject(new Error(`Relay command blocked: ${validation.reason}`));
+            return;
+        }
+
+        // Use external requestId if provided (for abort tracking), else generate
+        const requestId = externalRequestId || crypto.randomUUID();
+        const timeout = setTimeout(() => {
+            pendingRelayRequests.delete(requestId);
+            reject(new Error('Relay request timed out'));
+        }, timeoutMs);
+
+        pendingRelayRequests.set(requestId, { resolve, reject, timeout, userId, onStream });
+
+        relay.ws.send(JSON.stringify({
+            type: 'relay-command',
+            requestId,
+            action,
+            ...payload
+        }));
+    });
+}
+
+/**
+ * Check if a user has an active relay connection
+ */
+function hasActiveRelay(userId) {
+    if (!userId) return false;
+    const relay = relayConnections.get(Number(userId));
+    return relay && relay.ws.readyState === 1;
+}
+
+/**
+ * Route a chat command through the user's relay connection to their local machine.
+ * Translates relay-stream/relay-complete events into the format the frontend expects.
+ *
+ * @param {number} userId - User ID
+ * @param {string} action - Relay action (claude-query, codex-query, cursor-query)
+ * @param {object} data - Original command data from the browser
+ * @param {object} writer - WebSocket writer to send events to browser
+ * @param {object} eventMap - Maps relay stream data types to chat event types
+ */
+async function routeViaRelay(userId, action, data, writer, eventMap = {}) {
+    const sessionId = data.options?.sessionId || `relay-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+
+    // Generate requestId upfront so we can track it for abort (opencode pattern)
+    const requestId = crypto.randomUUID();
+
+    // Track relay session → requestId mapping for abort forwarding
+    relaySessionRequests.set(sessionId, { userId: Number(userId), requestId });
+
+    // Send session-created so the frontend can track this query
+    writer.send({ type: 'session-created', sessionId });
+
+    // Determine event types from the provider
+    const responseType = eventMap.response || 'claude-response';
+    const completeType = eventMap.complete || 'claude-complete';
+    const errorType = eventMap.error || 'claude-error';
+
+    let fullContent = '';
+    let capturedCliSessionId = null;
+    let usedSDKFormat = false;
+
+    try {
+        const result = await sendRelayCommand(
+            Number(userId),
+            action,
+            {
+                command: data.command,
+                options: data.options || {}
+            },
+            // onStream callback — translates relay events to chat events
+            (streamData) => {
+                // ── NEW: Handle SDK messages from upgraded CLI agent ──
+                // The CLI now uses @anthropic-ai/claude-agent-sdk query() which
+                // sends rich typed messages (tool_use, tool_result, text, system, result).
+                // Forward them directly — same format as queryClaudeSDK() in claude-sdk.js.
+                if (streamData.type === 'claude-sdk-message') {
+                    const sdkMessage = streamData.data;
+                    if (!sdkMessage) return;
+
+                    // Capture session ID from SDK messages
+                    if (sdkMessage.session_id && !capturedCliSessionId) {
+                        capturedCliSessionId = sdkMessage.session_id;
+
+                        // Send session-created with the real CLI session ID
+                        writer.send({
+                            type: 'relay-session-id',
+                            sessionId,
+                            cliSessionId: capturedCliSessionId,
+                            model: sdkMessage.model,
+                            cwd: sdkMessage.cwd,
+                        });
+                    }
+
+                    // Transform parent_tool_use_id for subagent grouping (match queryClaudeSDK format)
+                    const transformedMessage = sdkMessage.parent_tool_use_id
+                        ? { ...sdkMessage, parentToolUseId: sdkMessage.parent_tool_use_id }
+                        : sdkMessage;
+
+                    // Forward SDK message — SAME format as queryClaudeSDK()
+                    writer.send({
+                        type: responseType,
+                        data: transformedMessage,
+                        sessionId: capturedCliSessionId || sessionId || null,
+                    });
+
+                    // Extract and send token budget from result messages
+                    if (sdkMessage.type === 'result' && sdkMessage.modelUsage) {
+                        const tokenBudget = extractTokenBudget(sdkMessage);
+                        if (tokenBudget) {
+                            writer.send({
+                                type: 'token-budget',
+                                data: tokenBudget,
+                                sessionId: capturedCliSessionId || sessionId || null,
+                            });
+                        }
+                    }
+
+                    // Track that SDK format was used (skip content_block_stop on completion)
+                    usedSDKFormat = true;
+                    if (sdkMessage.type === 'assistant' || sdkMessage.type === 'result') {
+                        fullContent += '1'; // Mark that we got content
+                    }
+
+                    return;
+                }
+
+                // ── LEGACY: Handle old CLI format (backward compat with pre-SDK CLI versions) ──
+                // Capture CLI-reported session ID for resume support
+                // Forward immediately so frontend can use it for --continue
+                if (streamData.type === 'claude-system' && streamData.sessionId) {
+                    capturedCliSessionId = streamData.sessionId;
+                    writer.send({
+                        type: 'relay-session-id',
+                        sessionId,
+                        cliSessionId: capturedCliSessionId,
+                        model: streamData.model,
+                        cwd: streamData.cwd,
+                    });
+                }
+
+                if (streamData.type === 'claude-response' || streamData.type === 'codex-response' || streamData.type === 'cursor-response') {
+                    const chunk = streamData.content || '';
+                    if (chunk) {
+                        fullContent += chunk;
+                        // Send in content_block_delta format — matches what useChatRealtimeHandlers expects
+                        writer.send({
+                            type: responseType,
+                            data: { type: 'content_block_delta', delta: { text: chunk } },
+                            sessionId
+                        });
+                    }
+                } else if (streamData.type === 'claude-error' || streamData.type === 'codex-error' || streamData.type === 'cursor-error') {
+                    const errChunk = streamData.content || '';
+                    if (errChunk) {
+                        writer.send({
+                            type: responseType,
+                            data: { type: 'content_block_delta', delta: { text: errChunk } },
+                            sessionId
+                        });
+                    }
+                } else if (streamData.type === 'claude-result') {
+                    // Result event from stream-json — capture session ID
+                    if (streamData.sessionId) capturedCliSessionId = streamData.sessionId;
+                }
+            },
+            600000, // 10 minute timeout for AI queries
+            requestId // Pass pre-generated requestId for abort tracking
+        );
+
+        // Clean up relay session tracking
+        relaySessionRequests.delete(sessionId);
+
+        // Finalize any open streaming message before sending complete
+        // (only for legacy text-streaming mode — SDK messages are self-contained)
+        if (fullContent && !usedSDKFormat) {
+            writer.send({ type: responseType, data: { type: 'content_block_stop' }, sessionId });
+        }
+
+        // Send completion event
+        writer.send({
+            type: completeType,
+            sessionId,
+            cliSessionId: capturedCliSessionId || null,
+            exitCode: result?.exitCode ?? 0,
+            isNewSession: !data.options?.sessionId,
+            viaRelay: true
+        });
+    } catch (error) {
+        relaySessionRequests.delete(sessionId);
+        const isRelayLost = error.message?.includes('Relay disconnected') || error.message?.includes('No relay connection') || error.message?.includes('Relay request timed out');
+        writer.send({
+            type: errorType,
+            error: isRelayLost
+                ? 'Your machine disconnected. Please reconnect with "uc connect" and try again.'
+                : 'An error occurred while processing your request',
+            sessionId,
+            relayDisconnected: isRelayLost
+        });
+    }
+}
+
+// Handle shell WebSocket connections
+/**
+ * Bridge a browser shell WebSocket to the user's local machine via relay.
+ * Creates a relay shell session on the CLI and forwards I/O bidirectionally.
+ */
+function handleRelayShell(browserWs, userId) {
+    const relay = relayConnections.get(userId);
+    if (!relay || relay.ws.readyState !== 1) {
+        browserWs.send(JSON.stringify({ type: 'output', data: '\r\n\x1b[31m[Error] Relay connection lost. Reconnect with "uc connect".\x1b[0m\r\n' }));
+        browserWs.close();
+        return;
+    }
+
+    const shellSessionId = `relay-shell-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+
+    browserWs.send(JSON.stringify({ type: 'output', data: '\x1b[36m[Connected to local machine via relay]\x1b[0m\r\n' }));
+
+    // Forward browser shell messages to relay CLI
+    browserWs.on('message', async (message) => {
+        try {
+            const data = JSON.parse(message);
+
+            if (data.type === 'init') {
+                // Auto-register project path so it appears in sidebar
+                if (data.projectPath) {
+                    try { await addProjectManually(data.projectPath, null, userId); } catch { /* exists */ }
+                    // Notify browser clients — if this is a Claude/Cursor/Codex session,
+                    // tell the frontend to auto-select this project and open a new chat
+                    const isAgentSession = data.provider && data.provider !== 'plain-shell';
+                    for (const client of connectedClients) {
+                        try {
+                            if (client.readyState === 1 && client._wsUser?.userId === userId) {
+                                if (isAgentSession) {
+                                    client.send(JSON.stringify({
+                                        type: 'shell-project-selected',
+                                        projectPath: data.projectPath,
+                                        provider: data.provider,
+                                    }));
+                                } else {
+                                    client.send(JSON.stringify({ type: 'projects_updated' }));
+                                }
+                            }
+                        } catch { /* ignore */ }
+                    }
+                }
+                // Start relay shell session on CLI
+                const relayConn = relayConnections.get(userId);
+                if (relayConn?.ws?.readyState === 1) {
+                    relayConn.ws.send(JSON.stringify({
+                        type: 'relay-command',
+                        requestId: shellSessionId,
+                        action: 'shell-session-start',
+                        projectPath: data.projectPath,
+                        cols: data.cols || 80,
+                        rows: data.rows || 24,
+                        shellType: data.shellType,
+                        initialCommand: data.initialCommand,
+                        provider: data.provider,
+                        sessionId: data.sessionId,
+                        hasSession: data.hasSession,
+                        isPlainShell: data.isPlainShell,
+                    }));
+                }
+            } else if (data.type === 'input') {
+                // Forward keystroke to CLI shell
+                const relayConn = relayConnections.get(userId);
+                if (relayConn?.ws?.readyState === 1) {
+                    relayConn.ws.send(JSON.stringify({
+                        type: 'relay-shell-input',
+                        shellSessionId,
+                        data: data.data,
+                    }));
+                }
+            } else if (data.type === 'resize') {
+                // Forward resize to CLI shell
+                const relayConn = relayConnections.get(userId);
+                if (relayConn?.ws?.readyState === 1) {
+                    relayConn.ws.send(JSON.stringify({
+                        type: 'relay-shell-resize',
+                        shellSessionId,
+                        cols: data.cols,
+                        rows: data.rows,
+                    }));
+                }
+            }
+        } catch { /* ignore parse errors */ }
+    });
+
+    // Listen for relay shell output → forward to browser
+    // We tag this browser WS so the relay message handler can find it
+    browserWs._relayShellSessionId = shellSessionId;
+    browserWs._relayShellUserId = userId;
+
+    // Register this shell WS for output routing
+    if (!relayShellBrowserSockets) {
+        // Will be initialized below
+    }
+    relayShellBrowserSockets.set(shellSessionId, browserWs);
+
+    browserWs.on('close', () => {
+        relayShellBrowserSockets.delete(shellSessionId);
+        // Tell CLI to kill the shell session
+        const relayConn = relayConnections.get(userId);
+        if (relayConn?.ws?.readyState === 1) {
+            relayConn.ws.send(JSON.stringify({
+                type: 'relay-shell-kill',
+                shellSessionId,
+            }));
+        }
+    });
+}
+
+// Maps shellSessionId → browser WebSocket (for routing relay shell output)
+const relayShellBrowserSockets = new Map();
+
+function handleShellConnection(ws, request) {
+    const shellUserId = request?.user?.id || request?.user?.userId || null;
+
+    // ── Relay mode: bridge shell WebSocket to user's local machine ─────────
+    if (shellUserId && hasActiveRelay(Number(shellUserId))) {
+        handleRelayShell(ws, Number(shellUserId));
+        return;
+    }
+
+    if (!pty) {
+        ws.send(JSON.stringify({ type: 'output', data: '\r\n[Shell unavailable] node-pty not installed. Use relay connection for shell access.\r\n' }));
+        ws.close();
+        return;
+    }
+    // Shell client connected
+    let shellProcess = null;
+    let ptySessionKey = null;
+    let urlDetectionBuffer = '';
+    const announcedAuthUrls = new Set();
+
+    ws.on('message', async (message) => {
+        try {
+            const data = JSON.parse(message);
+            // Shell message received
+
+            if (data.type === 'init') {
+                const projectPath = data.projectPath || process.cwd();
+                const sessionId = data.sessionId;
+                const hasSession = data.hasSession;
+                const provider = data.provider || 'claude';
+                const initialCommand = data.initialCommand;
+                const isPlainShell = data.isPlainShell || (!!initialCommand && !hasSession) || provider === 'plain-shell';
+                const shellType = data.shellType || null;
+                urlDetectionBuffer = '';
+                announcedAuthUrls.clear();
+
+                // Login commands (Claude/Cursor auth) should never reuse cached sessions
+                const isLoginCommand = initialCommand && (
+                    initialCommand.includes('setup-token') ||
+                    initialCommand.includes('cursor-agent login') ||
+                    initialCommand.includes('auth login')
+                );
+
+                // Include command hash in session key so different commands get separate sessions
+                const commandSuffix = isPlainShell && initialCommand
+                    ? `_cmd_${Buffer.from(initialCommand).toString('base64').slice(0, 16)}`
+                    : '';
+                ptySessionKey = `${shellUserId || 'anon'}_${projectPath}_${sessionId || 'default'}${commandSuffix}`;
+
+                // Kill any existing login session before starting fresh
+                if (isLoginCommand) {
+                    const oldSession = ptySessionsMap.get(ptySessionKey);
+                    if (oldSession) {
+                        // cleaning up existing session
+                        if (oldSession.timeoutId) clearTimeout(oldSession.timeoutId);
+                        if (oldSession.pty && oldSession.pty.kill) oldSession.pty.kill();
+                        ptySessionsMap.delete(ptySessionKey);
+                    }
+                }
+
+                const existingSession = isLoginCommand ? null : ptySessionsMap.get(ptySessionKey);
+                if (existingSession) {
+                    // reconnecting to existing PTY session
+                    shellProcess = existingSession.pty;
+
+                    clearTimeout(existingSession.timeoutId);
+
+                    ws.send(JSON.stringify({
+                        type: 'output',
+                        data: `\x1b[36m[Reconnected to existing session]\x1b[0m\r\n`
+                    }));
+
+                    if (existingSession.buffer && existingSession.buffer.length > 0) {
+                        // sending buffered messages
+                        existingSession.buffer.forEach(bufferedData => {
+                            ws.send(JSON.stringify({
+                                type: 'output',
+                                data: bufferedData
+                            }));
+                        });
+                    }
+
+                    existingSession.ws = ws;
+
+                    return;
+                }
+
+                // shell start path logged silently
+                // shell session started
+                // provider info logged silently
+                if (initialCommand) {
+                    // initial command logged silently
+                }
+
+                // First send a welcome message
+                let welcomeMsg;
+                if (isPlainShell) {
+                    welcomeMsg = `\x1b[36mStarting terminal in: ${projectPath}\x1b[0m\r\n`;
+                } else {
+                    const providerName = provider === 'cursor' ? 'Cursor' : 'Claude';
+                    welcomeMsg = hasSession ?
+                        `\x1b[36mResuming ${providerName} session ${sessionId} in: ${projectPath}\x1b[0m\r\n` :
+                        `\x1b[36mStarting new ${providerName} session in: ${projectPath}\x1b[0m\r\n`;
+                }
+
+                ws.send(JSON.stringify({
+                    type: 'output',
+                    data: welcomeMsg
+                }));
+
+                try {
+                    // Prepare the shell command adapted to the platform and provider
+                    let shellCommand;
+                    if (isPlainShell) {
+                        // Plain shell mode - run initial command or open interactive shell
+                        const usesPowerShell = !shellType || shellType === 'powershell';
+                        if (initialCommand) {
+                            if (usesPowerShell) {
+                                shellCommand = `Set-Location -Path "${projectPath}"; ${initialCommand}`;
+                            } else {
+                                shellCommand = `cd "${projectPath}" && ${initialCommand}`;
+                            }
+                        } else {
+                            // Interactive shell tab — spawn shell directly (no command wrapper)
+                            shellCommand = null;
+                        }
+                    } else if (provider === 'cursor') {
+                        // Use cursor-agent command
+                        if (os.platform() === 'win32') {
+                            if (hasSession && sessionId) {
+                                shellCommand = `Set-Location -Path "${projectPath}"; cursor-agent --resume="${sessionId}"`;
+                            } else {
+                                shellCommand = `Set-Location -Path "${projectPath}"; cursor-agent`;
+                            }
+                        } else {
+                            if (hasSession && sessionId) {
+                                shellCommand = `cd "${projectPath}" && cursor-agent --resume="${sessionId}"`;
+                            } else {
+                                shellCommand = `cd "${projectPath}" && cursor-agent`;
+                            }
+                        }
+                    } else {
+                        // Use claude command (default) or initialCommand if provided
+                        const command = initialCommand || 'claude';
+                        if (os.platform() === 'win32') {
+                            if (hasSession && sessionId) {
+                                // Try to resume session, but with fallback to new session if it fails
+                                shellCommand = `Set-Location -Path "${projectPath}"; claude --resume ${sessionId}; if ($LASTEXITCODE -ne 0) { claude }`;
+                            } else {
+                                shellCommand = `Set-Location -Path "${projectPath}"; ${command}`;
+                            }
+                        } else {
+                            if (hasSession && sessionId) {
+                                shellCommand = `cd "${projectPath}" && claude --resume ${sessionId} || claude`;
+                            } else {
+                                shellCommand = `cd "${projectPath}" && ${command}`;
+                            }
+                        }
+                    }
+
+                    // shell command logged silently
+
+                    // Use appropriate shell based on platform and requested shellType
+                    const shellMap = {
+                        'powershell': { cmd: 'powershell.exe', args: ['-Command'] },
+                        'cmd': { cmd: 'cmd.exe', args: ['/c'] },
+                        'bash': { cmd: 'bash', args: ['-c'] },
+                    };
+                    const defaultShell = os.platform() === 'win32'
+                        ? { cmd: 'powershell.exe', args: ['-Command'] }
+                        : { cmd: 'bash', args: ['-c'] };
+                    const selectedShell = (shellType && shellMap[shellType]) || defaultShell;
+                    const shell = selectedShell.cmd;
+                    // If shellCommand is null, spawn an interactive shell with no args
+                    const shellArgs = shellCommand ? [...selectedShell.args, shellCommand] : [];
+
+                    // Use terminal dimensions from client if provided, otherwise use defaults
+                    const termCols = data.cols || 80;
+                    const termRows = data.rows || 24;
+                    // terminal dimensions logged silently
+
+                    shellProcess = pty.spawn(shell, shellArgs, {
+                        name: 'xterm-256color',
+                        cols: termCols,
+                        rows: termRows,
+                        cwd: shellCommand ? os.homedir() : projectPath,
+                        env: {
+                            ...process.env,
+                            TERM: 'xterm-256color',
+                            COLORTERM: 'truecolor',
+                            FORCE_COLOR: '3'
+                        }
+                    });
+
+                    // shell process started
+
+                    ptySessionsMap.set(ptySessionKey, {
+                        pty: shellProcess,
+                        ws: ws,
+                        buffer: [],
+                        timeoutId: null,
+                        projectPath,
+                        sessionId
+                    });
+
+                    // Handle data output
+                    shellProcess.onData((data) => {
+                        const session = ptySessionsMap.get(ptySessionKey);
+                        if (!session) return;
+
+                        if (session.buffer.length < 5000) {
+                            session.buffer.push(data);
+                        } else {
+                            session.buffer.shift();
+                            session.buffer.push(data);
+                        }
+
+                        if (session.ws && session.ws.readyState === WebSocket.OPEN) {
+                            let outputData = data;
+
+                            const cleanChunk = stripAnsiSequences(data);
+                            urlDetectionBuffer = `${urlDetectionBuffer}${cleanChunk}`.slice(-SHELL_URL_PARSE_BUFFER_LIMIT);
+
+                            outputData = outputData.replace(
+                                /OPEN_URL:\s*(https?:\/\/[^\s\x1b\x07]+)/g,
+                                '[INFO] Opening in browser: $1'
+                            );
+
+                            const emitAuthUrl = (detectedUrl, autoOpen = false) => {
+                                const normalizedUrl = normalizeDetectedUrl(detectedUrl);
+                                if (!normalizedUrl) return;
+
+                                const isNewUrl = !announcedAuthUrls.has(normalizedUrl);
+                                if (isNewUrl) {
+                                    announcedAuthUrls.add(normalizedUrl);
+                                    session.ws.send(JSON.stringify({
+                                        type: 'auth_url',
+                                        url: normalizedUrl,
+                                        autoOpen
+                                    }));
+                                }
+
+                            };
+
+                            const normalizedDetectedUrls = extractUrlsFromText(urlDetectionBuffer)
+                                .map((url) => normalizeDetectedUrl(url))
+                                .filter(Boolean);
+
+                            // Prefer the most complete URL if shorter prefix variants are also present.
+                            const dedupedDetectedUrls = Array.from(new Set(normalizedDetectedUrls)).filter((url, _, urls) =>
+                                !urls.some((otherUrl) => otherUrl !== url && otherUrl.startsWith(url))
+                            );
+
+                            dedupedDetectedUrls.forEach((url) => emitAuthUrl(url, false));
+
+                            if (shouldAutoOpenUrlFromOutput(cleanChunk) && dedupedDetectedUrls.length > 0) {
+                                const bestUrl = dedupedDetectedUrls.reduce((longest, current) =>
+                                    current.length > longest.length ? current : longest
+                                );
+                                emitAuthUrl(bestUrl, true);
+                            }
+
+                            // Send regular output
+                            session.ws.send(JSON.stringify({
+                                type: 'output',
+                                data: outputData
+                            }));
+                        }
+                    });
+
+                    // Handle process exit
+                    shellProcess.onExit((exitCode) => {
+                        // shell process exited
+                        const session = ptySessionsMap.get(ptySessionKey);
+                        if (session && session.ws && session.ws.readyState === WebSocket.OPEN) {
+                            session.ws.send(JSON.stringify({
+                                type: 'output',
+                                data: `\r\n\x1b[33mProcess exited with code ${exitCode.exitCode}${exitCode.signal ? ` (${exitCode.signal})` : ''}\x1b[0m\r\n`
+                            }));
+                        }
+                        if (session && session.timeoutId) {
+                            clearTimeout(session.timeoutId);
+                        }
+                        ptySessionsMap.delete(ptySessionKey);
+                        shellProcess = null;
+                    });
+
+                } catch (spawnError) {
+                    // process spawn error handled silently
+                    ws.send(JSON.stringify({
+                        type: 'output',
+                        data: `\r\n\x1b[31mError: ${spawnError.message}\x1b[0m\r\n`
+                    }));
+                }
+
+            } else if (data.type === 'input') {
+                // Send input to shell process
+                if (shellProcess && shellProcess.write) {
+                    try {
+                        shellProcess.write(data.data);
+                    } catch (error) {
+                        // shell write error handled silently
+                    }
+                } else {
+                    // no active shell process
+                }
+            } else if (data.type === 'resize') {
+                // Handle terminal resize
+                if (shellProcess && shellProcess.resize) {
+                    // terminal resize handled
+                    shellProcess.resize(data.cols, data.rows);
+                }
+            }
+        } catch (error) {
+            // shell WebSocket error
+            if (ws.readyState === WebSocket.OPEN) {
+                ws.send(JSON.stringify({
+                    type: 'output',
+                    data: `\r\n\x1b[31mError: ${error.message}\x1b[0m\r\n`
+                }));
+            }
+        }
+    });
+
+    ws.on('close', () => {
+        // shell client disconnected
+
+        if (ptySessionKey) {
+            const session = ptySessionsMap.get(ptySessionKey);
+            if (session) {
+                // PTY session kept alive
+                session.ws = null;
+
+                session.timeoutId = setTimeout(() => {
+                    // PTY session timeout
+                    if (session.pty && session.pty.kill) {
+                        session.pty.kill();
+                    }
+                    ptySessionsMap.delete(ptySessionKey);
+                }, PTY_SESSION_TIMEOUT);
+            }
+        }
+    });
+
+    ws.on('error', (error) => {
+        // shell error
+    });
+}
+// Audio transcription endpoint
+// Priority: 1) Self-hosted Whisper (WHISPER_URL), 2) BYOK OpenAI key, 3) Server OpenAI key
+app.post('/api/transcribe', authenticateToken, async (req, res) => {
+    try {
+        const multer = (await import('multer')).default;
+        const upload = multer({ storage: multer.memoryStorage(), limits: { fileSize: 25 * 1024 * 1024 } });
+
+        upload.single('audio')(req, res, async (err) => {
+            if (err) {
+                return res.status(400).json({ error: 'Failed to process audio file' });
+            }
+
+            if (!req.file) {
+                return res.status(400).json({ error: 'No audio file provided' });
+            }
+
+            const mode = req.body?.mode || 'default';
+            let transcribedText = '';
+
+            try {
+                const FormData = (await import('form-data')).default;
+
+                // --- Strategy 1: Self-hosted Whisper (no API key needed) ---
+                const whisperUrl = process.env.WHISPER_URL;
+                if (whisperUrl) {
+                    try {
+                        const formData = new FormData();
+                        formData.append('file', req.file.buffer, {
+                            filename: req.file.originalname || 'audio.webm',
+                            contentType: req.file.mimetype || 'audio/webm'
+                        });
+                        formData.append('model', 'whisper-1');
+                        formData.append('response_format', 'json');
+                        formData.append('language', 'en');
+
+                        const endpoint = whisperUrl.replace(/\/+$/, '') + '/v1/audio/transcriptions';
+                        const response = await fetch(endpoint, {
+                            method: 'POST',
+                            headers: formData.getHeaders(),
+                            body: formData
+                        });
+
+                        if (response.ok) {
+                            const data = await response.json();
+                            transcribedText = data.text || '';
+                        }
+                    } catch {
+                        // Self-hosted whisper failed, try next strategy
+                    }
+                }
+
+                // --- Strategy 2: OpenAI Whisper API (BYOK or server key) ---
+                if (!transcribedText) {
+                    const userOpenaiKey = req.user?.id
+                        ? await getUserProviderKey(req.user.id, 'openai_key')
+                        : null;
+                    const apiKey = userOpenaiKey || process.env.OPENAI_API_KEY;
+
+                    if (apiKey) {
+                        const formData = new FormData();
+                        formData.append('file', req.file.buffer, {
+                            filename: req.file.originalname || 'audio.webm',
+                            contentType: req.file.mimetype || 'audio/webm'
+                        });
+                        formData.append('model', 'whisper-1');
+                        formData.append('response_format', 'json');
+                        formData.append('language', 'en');
+
+                        const response = await fetch('https://api.openai.com/v1/audio/transcriptions', {
+                            method: 'POST',
+                            headers: {
+                                'Authorization': `Bearer ${apiKey}`,
+                                ...formData.getHeaders()
+                            },
+                            body: formData
+                        });
+
+                        if (response.ok) {
+                            const data = await response.json();
+                            transcribedText = data.text || '';
+                        }
+                    }
+                }
+
+                // No STT engine worked
+                if (!transcribedText) {
+                    return res.status(500).json({ error: 'Speech recognition is temporarily unavailable. Please try again.' });
+                }
+
+                // Default mode — return raw transcription
+                if (mode === 'default') {
+                    return res.json({ text: transcribedText });
+                }
+
+                // Enhancement modes (prompt, vibe, architect) — use OpenAI GPT if available
+                try {
+                    const userOpenaiKey = req.user?.id
+                        ? await getUserProviderKey(req.user.id, 'openai_key')
+                        : null;
+                    const enhanceKey = userOpenaiKey || process.env.OPENAI_API_KEY;
+
+                    if (enhanceKey) {
+                        const OpenAI = (await import('openai')).default;
+                        const openai = new OpenAI({ apiKey: enhanceKey });
+
+                        let prompt, systemMessage, temperature = 0.7, maxTokens = 800;
+
+                        switch (mode) {
+                            case 'prompt':
+                                systemMessage = 'You are an expert prompt engineer who creates clear, detailed, and effective prompts.';
+                                prompt = `Transform the following rough instruction into a clear, detailed, and context-aware AI prompt.\n\nYour enhanced prompt should:\n1. Be specific and unambiguous\n2. Include relevant context and constraints\n3. Specify the desired output format\n4. Use clear, actionable language\n\nRough instruction: "${transcribedText}"\n\nEnhanced prompt:`;
+                                break;
+                            case 'vibe':
+                            case 'instructions':
+                            case 'architect':
+                                systemMessage = 'You are a helpful assistant that formats ideas into clear, actionable instructions for AI agents.';
+                                temperature = 0.5;
+                                prompt = `Transform the following idea into clear, well-structured instructions that an AI agent can easily understand and execute.\n\nIMPORTANT RULES:\n- Format as clear, step-by-step instructions\n- Add reasonable implementation details based on common patterns\n- Only include details directly related to what was asked\n- Do NOT add features or functionality not mentioned\n- Keep the original intent and scope intact\n\nIdea: "${transcribedText}"\n\nAgent instructions:`;
+                                break;
+                        }
+
+                        if (prompt) {
+                            const completion = await openai.chat.completions.create({
+                                model: 'gpt-4o-mini',
+                                messages: [
+                                    { role: 'system', content: systemMessage },
+                                    { role: 'user', content: prompt }
+                                ],
+                                temperature,
+                                max_tokens: maxTokens
+                            });
+                            transcribedText = completion.choices[0]?.message?.content || transcribedText;
+                        }
+                    }
+                    // If no OpenAI key for enhancement, just return raw transcription
+                } catch {
+                    // Enhancement failed silently — return raw transcription
+                }
+
+                res.json({ text: transcribedText });
+
+            } catch {
+                res.status(500).json({ error: 'Transcription failed. Please try again.' });
+            }
+        });
+    } catch {
+        res.status(500).json({ error: 'Internal server error' });
+    }
+});
+
+// Image upload endpoint
+app.post('/api/projects/:projectName/upload-images', authenticateToken, authorizeProject, async (req, res) => {
+    try {
+        const multer = (await import('multer')).default;
+        const path = (await import('path')).default;
+        const fs = (await import('fs')).promises;
+        const os = (await import('os')).default;
+
+        // Configure multer for image uploads
+        const storage = multer.diskStorage({
+            destination: async (req, file, cb) => {
+                const uploadDir = path.join(os.tmpdir(), 'claude-ui-uploads', String(req.user.id));
+                await fs.mkdir(uploadDir, { recursive: true });
+                cb(null, uploadDir);
+            },
+            filename: (req, file, cb) => {
+                const uniqueSuffix = Date.now() + '-' + Math.round(Math.random() * 1E9);
+                const sanitizedName = file.originalname.replace(/[^a-zA-Z0-9.-]/g, '_');
+                cb(null, uniqueSuffix + '-' + sanitizedName);
+            }
+        });
+
+        const fileFilter = (req, file, cb) => {
+            const allowedMimes = ['image/jpeg', 'image/png', 'image/gif', 'image/webp', 'image/svg+xml'];
+            if (allowedMimes.includes(file.mimetype)) {
+                cb(null, true);
+            } else {
+                cb(new Error('Invalid file type. Only JPEG, PNG, GIF, WebP, and SVG are allowed.'));
+            }
+        };
+
+        const upload = multer({
+            storage,
+            fileFilter,
+            limits: {
+                fileSize: 5 * 1024 * 1024, // 5MB
+                files: 5
+            }
+        });
+
+        // Handle multipart form data
+        upload.array('images', 5)(req, res, async (err) => {
+            if (err) {
+                const uploadError = err.code === 'LIMIT_FILE_SIZE' ? 'File too large (max 5MB)' : err.code === 'LIMIT_FILE_COUNT' ? 'Too many files (max 5)' : 'Invalid file upload';
+                return res.status(400).json({ error: uploadError });
+            }
+
+            if (!req.files || req.files.length === 0) {
+                return res.status(400).json({ error: 'No image files provided' });
+            }
+
+            try {
+                // Process uploaded images
+                const processedImages = await Promise.all(
+                    req.files.map(async (file) => {
+                        // Read file and convert to base64
+                        const buffer = await fs.readFile(file.path);
+                        const base64 = buffer.toString('base64');
+                        const mimeType = file.mimetype;
+
+                        // Clean up temp file immediately
+                        await fs.unlink(file.path);
+
+                        return {
+                            name: file.originalname,
+                            data: `data:${mimeType};base64,${base64}`,
+                            size: file.size,
+                            mimeType: mimeType
+                        };
+                    })
+                );
+
+                res.json({ images: processedImages });
+            } catch (error) {
+                // image processing error handled silently
+                // Clean up any remaining files
+                await Promise.all(req.files.map(f => fs.unlink(f.path).catch(() => { })));
+                res.status(500).json({ error: 'Failed to process images' });
+            }
+        });
+    } catch (error) {
+        // image upload error handled silently
+        res.status(500).json({ error: 'Internal server error' });
+    }
+});
+
+// Get token usage for a specific session
+app.get('/api/projects/:projectName/sessions/:sessionId/token-usage', authenticateToken, authorizeProject, async (req, res) => {
+  try {
+    const { projectName, sessionId } = req.params;
+    const { provider = 'claude' } = req.query;
+    const homeDir = os.homedir();
+
+    // Allow only safe characters in sessionId
+    const safeSessionId = String(sessionId).replace(/[^a-zA-Z0-9._-]/g, '');
+    if (!safeSessionId) {
+      return res.status(400).json({ error: 'Invalid sessionId' });
+    }
+
+    // Handle Cursor sessions - they use SQLite and don't have token usage info
+    if (provider === 'cursor') {
+      return res.json({
+        used: 0,
+        total: 0,
+        breakdown: { input: 0, cacheCreation: 0, cacheRead: 0 },
+        unsupported: true,
+        message: 'Token usage tracking not available for Cursor sessions'
+      });
+    }
+
+    // Handle Codex sessions
+    if (provider === 'codex') {
+      const codexSessionsDir = path.join(homeDir, '.codex', 'sessions');
+
+      // Find the session file by searching for the session ID
+      const findSessionFile = async (dir) => {
+        try {
+          const entries = await fsPromises.readdir(dir, { withFileTypes: true });
+          for (const entry of entries) {
+            const fullPath = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+              const found = await findSessionFile(fullPath);
+              if (found) return found;
+            } else if (entry.name.includes(safeSessionId) && entry.name.endsWith('.jsonl')) {
+              return fullPath;
+            }
+          }
+        } catch (error) {
+          // Skip directories we can't read
+        }
+        return null;
+      };
+
+      const sessionFilePath = await findSessionFile(codexSessionsDir);
+
+      if (!sessionFilePath) {
+        return res.status(404).json({ error: 'Codex session file not found', sessionId: safeSessionId });
+      }
+
+      // Read and parse the Codex JSONL file
+      let fileContent;
+      try {
+        fileContent = await fsPromises.readFile(sessionFilePath, 'utf8');
+      } catch (error) {
+        if (error.code === 'ENOENT') {
+          return res.status(404).json({ error: 'Session file not found', path: sessionFilePath });
+        }
+        throw error;
+      }
+      const lines = fileContent.trim().split('\n');
+      let totalTokens = 0;
+      let contextWindow = 200000; // Default for Codex/OpenAI
+
+      // Find the latest token_count event with info (scan from end)
+      for (let i = lines.length - 1; i >= 0; i--) {
+        try {
+          const entry = JSON.parse(lines[i]);
+
+          // Codex stores token info in event_msg with type: "token_count"
+          if (entry.type === 'event_msg' && entry.payload?.type === 'token_count' && entry.payload?.info) {
+            const tokenInfo = entry.payload.info;
+            if (tokenInfo.total_token_usage) {
+              totalTokens = tokenInfo.total_token_usage.total_tokens || 0;
+            }
+            if (tokenInfo.model_context_window) {
+              contextWindow = tokenInfo.model_context_window;
+            }
+            break; // Stop after finding the latest token count
+          }
+        } catch (parseError) {
+          // Skip lines that can't be parsed
+          continue;
+        }
+      }
+
+      return res.json({
+        used: totalTokens,
+        total: contextWindow
+      });
+    }
+
+    // Handle Claude sessions (default)
+    // Extract actual project path
+    let projectPath;
+    try {
+      projectPath = await extractProjectDirectory(projectName);
+    } catch (error) {
+      // project dir extraction error handled silently
+      return res.status(500).json({ error: 'Failed to determine project path' });
+    }
+
+    // Construct the JSONL file path
+    // Claude stores session files in ~/.claude/projects/[encoded-project-path]/[session-id].jsonl
+    // The encoding replaces /, spaces, ~, and _ with -
+    const encodedPath = projectPath.replace(/[\\/:\s~_]/g, '-');
+    const projectDir = path.join(homeDir, '.claude', 'projects', encodedPath);
+
+    const jsonlPath = path.join(projectDir, `${safeSessionId}.jsonl`);
+
+    // Constrain to projectDir
+    const rel = path.relative(path.resolve(projectDir), path.resolve(jsonlPath));
+    if (rel.startsWith('..') || path.isAbsolute(rel)) {
+      return res.status(400).json({ error: 'Invalid path' });
+    }
+
+    // Read and parse the JSONL file
+    let fileContent;
+    try {
+      fileContent = await fsPromises.readFile(jsonlPath, 'utf8');
+    } catch (error) {
+      if (error.code === 'ENOENT') {
+        return res.status(404).json({ error: 'Session file not found', path: jsonlPath });
+      }
+      throw error; // Re-throw other errors to be caught by outer try-catch
+    }
+    const lines = fileContent.trim().split('\n');
+
+    const parsedContextWindow = parseInt(process.env.CONTEXT_WINDOW, 10);
+    const contextWindow = Number.isFinite(parsedContextWindow) ? parsedContextWindow : 160000;
+    let inputTokens = 0;
+    let cacheCreationTokens = 0;
+    let cacheReadTokens = 0;
+
+    // Find the latest assistant message with usage data (scan from end)
+    for (let i = lines.length - 1; i >= 0; i--) {
+      try {
+        const entry = JSON.parse(lines[i]);
+
+        // Only count assistant messages which have usage data
+        if (entry.type === 'assistant' && entry.message?.usage) {
+          const usage = entry.message.usage;
+
+          // Use token counts from latest assistant message only
+          inputTokens = usage.input_tokens || 0;
+          cacheCreationTokens = usage.cache_creation_input_tokens || 0;
+          cacheReadTokens = usage.cache_read_input_tokens || 0;
+
+          break; // Stop after finding the latest assistant message
+        }
+      } catch (parseError) {
+        // Skip lines that can't be parsed
+        continue;
+      }
+    }
+
+    // Calculate total context usage (excluding output_tokens, as per ccusage)
+    const totalUsed = inputTokens + cacheCreationTokens + cacheReadTokens;
+
+    res.json({
+      used: totalUsed,
+      total: contextWindow,
+      breakdown: {
+        input: inputTokens,
+        cacheCreation: cacheCreationTokens,
+        cacheRead: cacheReadTokens
+      }
+    });
+  } catch (error) {
+    // token usage read error
+    res.status(500).json({ error: 'Failed to read session token usage' });
+  }
+});
+
+// Serve React app for all other routes (excluding static files and API routes)
+app.get('*', (req, res) => {
+  // Skip API routes — they should be handled by their own routers
+  if (req.path.startsWith('/api/') || req.path === '/mcp' || req.path === '/relay' || req.path === '/health') {
+    return res.status(404).json({ error: 'Not found' });
+  }
+  // Skip requests for static assets (files with extensions)
+  if (path.extname(req.path)) {
+    return res.status(404).send('Not found');
+  }
+
+  // If a JWT token is in the query param and no session cookie exists,
+  // set the cookie now so the client-side AuthContext can authenticate on subsequent API calls.
+  if (req.query?.token && !req.cookies?.session) {
+    try {
+      const decoded = jwt.verify(req.query.token, JWT_SECRET);
+      if (decoded?.userId) {
+        const isSecure = process.env.NODE_ENV === 'production' || !!process.env.RAILWAY_ENVIRONMENT;
+        res.cookie('session', req.query.token, {
+          httpOnly: true,
+          secure: isSecure,
+          sameSite: isSecure ? 'none' : 'strict',
+          maxAge: 30 * 24 * 60 * 60 * 1000,
+          path: '/',
+        });
+      }
+    } catch (e) {
+      // Invalid token — just serve the page without setting cookie
+    }
+  }
+
+  // Only serve index.html for HTML routes, not for static assets
+  // Static assets should already be handled by express.static middleware above
+  const indexPath = path.join(__dirname, '../client/dist/index.html');
+
+  // Check if dist/index.html exists (production build available)
+  if (fs.existsSync(indexPath)) {
+    // Set no-cache headers for HTML to prevent service worker issues
+    res.setHeader('Cache-Control', 'no-cache, no-store, must-revalidate');
+    res.setHeader('Pragma', 'no-cache');
+    res.setHeader('Expires', '0');
+    res.sendFile(indexPath);
+  } else {
+    // In development, redirect to Vite dev server only if dist doesn't exist
+    res.redirect(`http://localhost:${process.env.VITE_PORT || 5173}`);
+  }
+});
+
+// Helper function to convert permissions to rwx format
+function permToRwx(perm) {
+    const r = perm & 4 ? 'r' : '-';
+    const w = perm & 2 ? 'w' : '-';
+    const x = perm & 1 ? 'x' : '-';
+    return r + w + x;
+}
+
+async function getFileTree(dirPath, maxDepth = 3, currentDepth = 0, showHidden = true) {
+    // Using fsPromises from import
+    const items = [];
+
+    try {
+        const entries = await fsPromises.readdir(dirPath, { withFileTypes: true });
+
+        for (const entry of entries) {
+            // Debug: log all entries including hidden files
+
+
+            // Skip heavy build directories and VCS directories
+            if (entry.name === 'node_modules' ||
+                entry.name === 'dist' ||
+                entry.name === 'build' ||
+                entry.name === '.git' ||
+                entry.name === '.svn' ||
+                entry.name === '.hg') continue;
+
+            const itemPath = path.join(dirPath, entry.name);
+            const item = {
+                name: entry.name,
+                path: itemPath,
+                type: entry.isDirectory() ? 'directory' : 'file'
+            };
+
+            // Get file stats for additional metadata
+            try {
+                const stats = await fsPromises.stat(itemPath);
+                item.size = stats.size;
+                item.modified = stats.mtime.toISOString();
+
+                // Convert permissions to rwx format
+                const mode = stats.mode;
+                const ownerPerm = (mode >> 6) & 7;
+                const groupPerm = (mode >> 3) & 7;
+                const otherPerm = mode & 7;
+                item.permissions = ((mode >> 6) & 7).toString() + ((mode >> 3) & 7).toString() + (mode & 7).toString();
+                item.permissionsRwx = permToRwx(ownerPerm) + permToRwx(groupPerm) + permToRwx(otherPerm);
+            } catch (statError) {
+                // If stat fails, provide default values
+                item.size = 0;
+                item.modified = null;
+                item.permissions = '000';
+                item.permissionsRwx = '---------';
+            }
+
+            if (entry.isDirectory() && currentDepth < maxDepth) {
+                // Recursively get subdirectories but limit depth
+                try {
+                    // Check if we can access the directory before trying to read it
+                    await fsPromises.access(item.path, fs.constants.R_OK);
+                    item.children = await getFileTree(item.path, maxDepth, currentDepth + 1, showHidden);
+                } catch (e) {
+                    // Silently skip directories we can't access (permission denied, etc.)
+                    item.children = [];
+                }
+            }
+
+            items.push(item);
+        }
+    } catch (error) {
+        // Only log non-permission errors to avoid spam
+        if (error.code !== 'EACCES' && error.code !== 'EPERM') {
+            // directory read error handled silently
+        }
+    }
+
+    return items.sort((a, b) => {
+        if (a.type !== b.type) {
+            return a.type === 'directory' ? -1 : 1;
+        }
+        return a.name.localeCompare(b.name);
+    });
+}
+
+const PORT = process.env.PORT || 3001;
+
+// Initialize database and start server
+async function startServer() {
+    try {
+        // Initialize authentication database
+        await initializeDatabase();
+
+        // In local mode, ensure a default user exists (no signup needed)
+        if (IS_LOCAL) {
+            const hasUsers = await userDb.hasUsers();
+            if (!hasUsers) {
+                const localUsername = os.userInfo().username || 'local';
+                const dummyHash = crypto.randomBytes(32).toString('hex');
+                await userDb.createUser(localUsername, dummyHash);
+                console.log(`${c.ok('[LOCAL]')} Created local user: ${c.bright(localUsername)}`);
+            }
+            console.log(`${c.info('[MODE]')} Running in ${c.bright('LOCAL')} mode (no login required)`);
+        }
+
+        // Check if running in production mode (dist folder exists OR NODE_ENV/RAILWAY set)
+        const distIndexPath = path.join(__dirname, '../client/dist/index.html');
+        const isProduction = fs.existsSync(distIndexPath) || process.env.NODE_ENV === 'production' || !!process.env.RAILWAY_ENVIRONMENT;
+
+        // Log Claude implementation mode
+        console.log(`${c.info('[INFO]')} Using Claude Agents SDK for Claude integration`);
+        console.log(`${c.info('[INFO]')} Running in ${c.bright(isProduction ? 'PRODUCTION' : 'DEVELOPMENT')} mode`);
+
+        if (!isProduction) {
+            console.log(`${c.warn('[WARN]')} Note: Requests will be proxied to Vite dev server at ${c.dim('http://localhost:' + (process.env.VITE_PORT || 5173))}`);
+        }
+
+        server.listen(PORT, '0.0.0.0', async () => {
+            const appInstallPath = path.join(__dirname, '..');
+
+            console.log('');
+            console.log(c.dim('═'.repeat(63)));
+            console.log(`  ${c.bright('Upfyn-Code Server - Ready')}`);
+            console.log(c.dim('═'.repeat(63)));
+            console.log('');
+            console.log(`${c.info('[INFO]')} Server URL:  ${c.bright('http://0.0.0.0:' + PORT)}`);
+            console.log(`${c.info('[INFO]')} MCP Server:  ${c.bright('http://0.0.0.0:' + PORT + '/mcp')}`);
+            console.log(`${c.info('[INFO]')} Installed at: ${c.dim(appInstallPath)}`);
+            console.log(`${c.tip('[TIP]')}  Run "uc status" for full configuration details`);
+
+            // Start workflow cron scheduler
+            initScheduler().catch(err => console.warn('[Scheduler]', err.message));
+            console.log('');
+
+            // Start watching the projects folder for changes (skip on Vercel)
+            if (!process.env.VERCEL) {
+                await setupProjectsWatcher();
+            }
+        });
+    } catch (error) {
+        console.error('[ERROR] Failed to start server:', error);
+        process.exit(1);
+    }
+}
+
+// Only start server when not running on Vercel (Vercel uses the exported app)
+if (!process.env.VERCEL) {
+    startServer();
+}
+
+// Export for Vercel serverless and testing
+export default app;
+export { app, server, relayConnections, sendRelayCommand };