rivet-design 0.6.6 → 0.6.8

package/dist/mcp/server.js

@@ -16,7 +16,11 @@ const index_1 = require("../index");
 const skillWriter_1 = require("../utils/skillWriter");
 const portUtils_1 = require("../utils/portUtils");
 const child_process_1 = require("child_process");
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const util_1 = require("util");
 const log = (0, index_core_1.createLogger)('MCPServer');
+const execAsync = (0, util_1.promisify)(child_process_1.exec);
 // Dev server command + default port per framework
 const FRAMEWORK_DEV_CONFIG = {
     nextjs: { devCommand: 'dev', defaultPort: 3000 },
@@ -62,6 +66,244 @@ async function waitForPort(port, host, timeoutMs = 60_000) {
     }
     return false;
 }
+/** Stop a spawned process with graceful SIGTERM and SIGKILL fallback. */
+async function stopChildProcess(child, timeoutMs = DEV_SERVER_STOP_TIMEOUT_MS) {
+    if (child.killed || child.exitCode !== null || child.pid == null) {
+        return;
+    }
+    const waitForExit = new Promise((resolve) => {
+        const onExit = () => {
+            child.off('exit', onExit);
+            child.off('error', onExit);
+            resolve();
+        };
+        child.once('exit', onExit);
+        child.once('error', onExit);
+    });
+    try {
+        child.kill('SIGTERM');
+    }
+    catch {
+        // no-op; fallback still runs below if process persists
+    }
+    const timedOut = await Promise.race([
+        waitForExit.then(() => false),
+        new Promise((resolve) => setTimeout(() => resolve(true), timeoutMs)),
+    ]);
+    if (!timedOut) {
+        return;
+    }
+    try {
+        child.kill('SIGKILL');
+    }
+    catch {
+        // best effort
+    }
+    await waitForExit;
+}
+const DEV_SERVER_STOP_TIMEOUT_MS = 5000;
+function normalizeFilesystemPath(inputPath) {
+    if (!inputPath) {
+        return '';
+    }
+    const resolvedPath = path_1.default.resolve(inputPath);
+    try {
+        return fs_1.default.realpathSync(resolvedPath);
+    }
+    catch {
+        return resolvedPath;
+    }
+}
+function pathsMatchExactly(pathA, pathB) {
+    if (!pathA || !pathB) {
+        return false;
+    }
+    return pathA === pathB;
+}
+async function getListeningPortPids(port) {
+    try {
+        const { stdout } = await execAsync(`lsof -nP -iTCP:${port} -sTCP:LISTEN -Fp`);
+        const pids = stdout
+            .split('\n')
+            .map((line) => line.trim())
+            .filter((line) => line.startsWith('p'))
+            .map((line) => parseInt(line.slice(1), 10))
+            .filter((pid) => Number.isInteger(pid) && pid > 0);
+        return [...new Set(pids)];
+    }
+    catch {
+        return [];
+    }
+}
+async function getProcessCwd(pid) {
+    if (!Number.isInteger(pid) || pid <= 0) {
+        return null;
+    }
+    try {
+        const { stdout } = await execAsync(`lsof -a -p ${pid} -d cwd -Fn`);
+        const cwdLine = stdout
+            .split('\n')
+            .map((line) => line.trim())
+            .find((line) => line.startsWith('n'));
+        if (!cwdLine) {
+            return null;
+        }
+        return cwdLine.slice(1) || null;
+    }
+    catch {
+        return null;
+    }
+}
+async function isPortOwnedByProject(port, projectPath) {
+    if (!Number.isInteger(port) || port <= 0 || port >= 65536) {
+        return {
+            matches: false,
+            reason: `Invalid port ${port} for project validation.`,
+        };
+    }
+    const normalizedProjectPath = normalizeFilesystemPath(projectPath);
+    if (!normalizedProjectPath) {
+        return {
+            matches: false,
+            reason: 'Project path is invalid for strict server validation.',
+        };
+    }
+    const candidatePids = await getListeningPortPids(port);
+    if (candidatePids.length === 0) {
+        return {
+            matches: false,
+            reason: `No listening process found on localhost:${port}.`,
+        };
+    }
+    const observedProcessPaths = [];
+    for (const pid of candidatePids) {
+        const cwd = await getProcessCwd(pid);
+        const normalizedCwd = normalizeFilesystemPath(cwd);
+        if (!normalizedCwd) {
+            observedProcessPaths.push(`${pid}:<unknown_cwd>`);
+            continue;
+        }
+        observedProcessPaths.push(`${pid}:${normalizedCwd}`);
+        if (pathsMatchExactly(normalizedProjectPath, normalizedCwd)) {
+            return {
+                matches: true,
+                reason: `Process ${pid} is running from ${normalizedCwd}.`,
+            };
+        }
+    }
+    return {
+        matches: false,
+        reason: `A server is listening on localhost:${port}, but process paths do not match the selected project path. selected=${normalizedProjectPath}; observed=${observedProcessPaths.join(', ') || '<none>'}`,
+        selectedProjectPath: normalizedProjectPath,
+        observedProcessPaths,
+    };
+}
+function detectFrameworkFromHtml(html) {
+    const lower = html.toLowerCase();
+    const hasViteClient = lower.includes('/@vite/client');
+    const hasViteMarkers = lower.includes('vite') &&
+        (lower.includes('hmr') || lower.includes('/src/main.'));
+    if (hasViteClient || hasViteMarkers) {
+        return 'vite';
+    }
+    const hasNextAssets = lower.includes('/_next/');
+    const hasNextMarkers = lower.includes('__next_data__') || lower.includes('next-route-announcer');
+    if (hasNextAssets || hasNextMarkers) {
+        return 'nextjs';
+    }
+    return 'unknown';
+}
+function normalizeExpectedFramework(framework) {
+    if (!framework)
+        return 'unknown';
+    const lower = framework.toLowerCase();
+    if (lower.includes('vite'))
+        return 'vite';
+    if (lower.includes('next'))
+        return 'nextjs';
+    return 'unknown';
+}
+function isFrameworkCompatible(expected, detected) {
+    if (expected === 'unknown')
+        return true;
+    return expected === detected;
+}
+async function validateProjectServer(options) {
+    const { host, port, framework, projectPath } = options;
+    const signals = [];
+    const isReachable = await waitForPort(port, host, 3000);
+    if (!isReachable) {
+        return {
+            valid: false,
+            reason: `No server is responding on ${host}:${port}.`,
+            detectedFramework: 'unknown',
+            signals,
+        };
+    }
+    signals.push('tcp_reachable');
+    if (projectPath) {
+        const projectMatch = await isPortOwnedByProject(port, projectPath);
+        if (!projectMatch.matches) {
+            return {
+                valid: false,
+                reason: projectMatch.reason,
+                detectedFramework: 'unknown',
+                signals,
+                selectedProjectPath: projectMatch.selectedProjectPath,
+                observedProcessPaths: projectMatch.observedProcessPaths,
+            };
+        }
+        signals.push('path_match');
+    }
+    try {
+        const response = await fetch(`http://${host}:${port}`, {
+            signal: AbortSignal.timeout(3000),
+        });
+        const html = await response.text();
+        const detectedFramework = detectFrameworkFromHtml(html);
+        if (detectedFramework === 'vite') {
+            signals.push('vite_marker');
+        }
+        if (detectedFramework === 'nextjs') {
+            signals.push('next_marker');
+        }
+        const expected = normalizeExpectedFramework(framework);
+        if (!isFrameworkCompatible(expected, detectedFramework)) {
+            return {
+                valid: false,
+                reason: `Expected ${expected}, but detected ${detectedFramework} on ${host}:${port}.`,
+                detectedFramework,
+                signals,
+                statusCode: response.status,
+            };
+        }
+        if (detectedFramework === 'unknown' && expected !== 'unknown') {
+            return {
+                valid: false,
+                reason: 'Server is reachable but did not expose framework markers needed for validation.',
+                detectedFramework,
+                signals,
+                statusCode: response.status,
+            };
+        }
+        return {
+            valid: true,
+            reason: `Validated ${host}:${port} as a project server.`,
+            detectedFramework,
+            signals,
+            statusCode: response.status,
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : 'Unknown error';
+        return {
+            valid: false,
+            reason: `HTTP validation failed: ${message}`,
+            detectedFramework: 'unknown',
+            signals,
+        };
+    }
+}
 /**
  * Starts the Rivet MCP server on stdio transport.
  * Called when the user runs `rivet mcp`.
@@ -146,8 +388,11 @@ const APPLY_GUIDE = 'Read each file in sourceFiles, then apply every change in t
     'If a change has imageCount > 0, the corresponding reference images appear as image content items immediately following this text in the tool result — view them before making changes. ' +
     'CRITICAL WORKFLOW: 1. Use report_feedback to share a brief plan. 2. Edit the files. 3. Use report_feedback with refresh_git: true to summarize what you changed. 4. ONLY THEN wait for the next round.';
 const startMCPServer = async (mcpEditor) => {
-    // Redirect all logging to stderr so stdout is reserved for MCP protocol
+    // Redirect all logging to stderr so stdout is reserved for MCP protocol,
+    // then silence all output — users shouldn't see Rivet logs in their terminal.
+    // Error capture (_onError) still fires for PostHog since it bypasses loglevel.
     (0, index_core_1.redirectLogsToStderr)();
+    (0, index_core_1.setLogLevel)('SILENT');
     const sendButtonLabel = getSendButtonLabel(mcpEditor);
     const bridge = new SessionBridgeService_1.SessionBridgeService();
     const telemetry = new TelemetryService_1.TelemetryService();
@@ -179,8 +424,90 @@ const startMCPServer = async (mcpEditor) => {
     let sessionStartedAt = null;
     // Track a dev server we auto-started so we can kill it on close
     let devServerProcess = null;
-    // Flush telemetry before process exits
+    let devServerOwnership = 'none';
+    let devServerHost = null;
+    let devServerPort = null;
+    let isCleanupRunning = false;
+    const updateBridgeHealth = (reason, isReachable) => {
+        bridge.updateDevServerHealth({
+            reason,
+            isReachable,
+            lastCheckedAt: Date.now(),
+        });
+    };
+    const cleanupSessionResources = async (options) => {
+        if (isCleanupRunning) {
+            return { totalRoundsCompleted: 0, sessionId: null };
+        }
+        isCleanupRunning = true;
+        try {
+            const activeSessionId = bridge.getSessionId();
+            const sessionIdToClose = options?.closeSessionId ??
+                (bridge.isActive() && activeSessionId ? activeSessionId : null);
+            const telemetryContext = bridge.getTelemetryContext();
+            const activeRunCorrelation = bridge.completeActiveRunCorrelation();
+            let totalRoundsCompleted = 0;
+            if (sessionIdToClose && bridge.isActive()) {
+                totalRoundsCompleted = bridge.endSession();
+            }
+            if (serverHandle) {
+                try {
+                    await serverHandle.close();
+                }
+                catch (error) {
+                    log.warn('Error stopping Express server:', error);
+                }
+                serverHandle = null;
+            }
+            if (devServerOwnership === 'rivet_owned' && devServerProcess) {
+                try {
+                    await stopChildProcess(devServerProcess);
+                }
+                catch (error) {
+                    log.warn('Error stopping dev server process:', error);
+                }
+            }
+            devServerProcess = null;
+            devServerOwnership = 'none';
+            devServerHost = null;
+            devServerPort = null;
+            updateBridgeHealth('rivet_unreachable', false);
+            const durationMs = sessionStartedAt ? Date.now() - sessionStartedAt : 0;
+            sessionStartedAt = null;
+            if (options?.trackSessionEnd !== false && sessionIdToClose) {
+                telemetry.trackMCPSessionEnd({
+                    sessionId: sessionIdToClose,
+                    rounds: totalRoundsCompleted,
+                    durationMs,
+                    browserSessionId: telemetryContext?.browserSessionId,
+                    browserDistinctId: telemetryContext?.browserDistinctId,
+                });
+                if (activeRunCorrelation) {
+                    telemetry.trackAgentRunFailed({
+                        traceId: activeRunCorrelation.traceId,
+                        agentRunId: activeRunCorrelation.agentRunId,
+                        sessionId: sessionIdToClose,
+                        posthogSessionId: activeRunCorrelation.browserSessionId,
+                        durationMs: Date.now() - activeRunCorrelation.startedAt,
+                        errorType: 'mcp_session_closed',
+                        errorMessage: 'MCP session closed before apply completion confirmation',
+                        source: 'mcp',
+                    });
+                }
+            }
+            await telemetry.flush();
+            return {
+                totalRoundsCompleted,
+                sessionId: sessionIdToClose,
+            };
+        }
+        finally {
+            isCleanupRunning = false;
+        }
+    };
+    // Flush telemetry + resources before process exits
     const shutdown = async () => {
+        await cleanupSessionResources({ trackSessionEnd: true });
         await telemetry.shutdown();
     };
     process.on('SIGTERM', async () => {
@@ -215,6 +542,18 @@ const startMCPServer = async (mcpEditor) => {
             .number()
             .describe('Preferred starting port for the dev server. Rivet will find the next free port at or above this value. Falls back to the framework default if omitted.')
             .optional(),
+        startupMode: v3_1.z
+            .enum(['manual_existing', 'ai_startup'])
+            .describe('How to connect the dev server: manual_existing uses an already-running server, ai_startup auto-starts one. Optional; if omitted, Rivet defaults to ai_startup.')
+            .optional(),
+        existingPort: v3_1.z
+            .number()
+            .describe('Port of an already-running dev server. Required for startupMode manual_existing, and reused for follow-up calls after nextStep responses.')
+            .optional(),
+        forceAttachExternal: v3_1.z
+            .boolean()
+            .describe('Confirmation flag for startupMode manual_existing when validation reports a project mismatch. Set true only after user confirms attaching anyway.')
+            .optional(),
     };
     const sessionIdArgs = {
         sessionId: v3_1.z
@@ -232,7 +571,7 @@ const startMCPServer = async (mcpEditor) => {
             .optional()
             .describe('How long to wait for the user to send changes (default: 600, max: 600)'),
     };
-    mcp.tool('detect_project', 'Detect the project framework, package manager, dev command, and default port. Also reports whether the dev server is currently running. Call this before open_visual_editor to check if the dev server needs to be started.', detectProjectArgs, async (args) => {
+    mcp.tool('detect_project', 'Detect the project framework, package manager, dev command, and default port. Also checks whether a project dev server is currently reachable and reports its endpoint when found. Call this before open_visual_editor to decide startupMode.', detectProjectArgs, async (args) => {
         const projectPath = args.projectPath || process.cwd();
         const detection = new index_core_1.ProjectDetectionService();
         let framework;
@@ -260,6 +599,9 @@ const startMCPServer = async (mcpEditor) => {
             devCommand: 'dev',
             defaultPort: 3000,
         };
+        const runningServer = framework === 'static'
+            ? null
+            : await detection.findRunningDevServer(projectPath, [index_1.DEFAULT_PORT]);
         return {
             content: [
                 {
@@ -270,6 +612,9 @@ const startMCPServer = async (mcpEditor) => {
                         devCommand: devConfig.devCommand,
                         defaultPort: devConfig.defaultPort,
                         projectPath,
+                        devServerRunning: Boolean(runningServer),
+                        detectedPort: runningServer?.port ?? null,
+                        detectedHost: runningServer?.host ?? null,
                         startCommand: devConfig.devCommand
                             ? `${packageManager} run ${devConfig.devCommand}`
                             : null,
@@ -278,7 +623,7 @@ const startMCPServer = async (mcpEditor) => {
             ],
         };
     });
-    mcp.tool('open_visual_editor', "Start a Rivet visual editing session. Always call detect_project first to get the framework. Rivet will automatically start the dev server on a free port. Opens the browser with Rivet's visual editor. After calling this, use watch_for_changes in a loop to receive changes as the user works.", openEditorArgs, async (args) => {
+    mcp.tool('open_visual_editor', "Start a Rivet visual editing session. Always call detect_project first to get the framework. Supports startupMode manual_existing (validate an existing dev server) or ai_startup (auto-start one on a free port). If startupMode is omitted, Rivet defaults to ai_startup. Some recoverable startup outcomes return a non-error follow-up payload (opened: false, nextStep) rather than failing: nextStep manual_port_required means retry with startupMode manual_existing + existingPort, and nextStep mismatch_confirmation_required means confirm with forceAttachExternal: true before attaching a mismatched server. Opens the browser with Rivet's visual editor when opened is true. After calling this, use watch_for_changes in a loop to receive changes as the user works.", openEditorArgs, async (args) => {
         if (bridge.isActive()) {
             return {
                 content: [
@@ -295,13 +640,18 @@ const startMCPServer = async (mcpEditor) => {
         }
         const projectPath = args.projectPath || process.cwd();
         const framework = args.framework ?? 'nextjs';
-        let devServerPort = 0;
-        const devServerHost = 'localhost';
+        const requestedStartupMode = args.startupMode;
+        const startupMode = requestedStartupMode ?? 'ai_startup';
+        let nextDevServerPort = null;
+        const nextDevServerHost = 'localhost';
+        let nextDevServerOwnership = 'none';
+        const startupModeSelection = requestedStartupMode ? 'explicit' : 'auto';
         if (framework !== 'static') {
             const frameworkConfig = FRAMEWORK_DEV_CONFIG[framework] ?? {
                 devCommand: 'dev',
                 defaultPort: 3000,
             };
+            const detection = new index_core_1.ProjectDetectionService();
             if (!frameworkConfig.devCommand) {
                 return {
                     content: [
@@ -316,51 +666,180 @@ const startMCPServer = async (mcpEditor) => {
                     isError: true,
                 };
             }
-            const detection = new index_core_1.ProjectDetectionService();
-            const packageManager = await detection.detectPackageManager(projectPath);
-            const preferredPort = args.startPort ??
-                detection.readConfiguredPort(projectPath) ??
-                frameworkConfig.defaultPort;
-            devServerPort = await (0, portUtils_1.findAvailablePort)(preferredPort);
-            const { cmd, args: cmdArgs, env, } = buildDevServerCommand(framework, packageManager, frameworkConfig.devCommand, devServerPort);
-            log.info(`Auto-starting dev server: ${cmd} ${cmdArgs.join(' ')} in ${projectPath}`);
-            devServerProcess = (0, child_process_1.spawn)(cmd, cmdArgs, {
-                cwd: projectPath,
-                env: { ...process.env, ...env },
-                stdio: 'pipe',
-                detached: false,
-            });
-            devServerProcess.on('error', (err) => {
-                log.error('Dev server process error:', err);
-            });
-            devServerProcess.on('exit', (code) => {
-                log.info(`Dev server exited with code ${code}`);
-                devServerProcess = null;
-            });
-            devServerProcess.stdout?.on('data', (data) => {
-                log.debug(`[dev-server] ${data.toString().trim()}`);
-            });
-            devServerProcess.stderr?.on('data', (data) => {
-                log.debug(`[dev-server] ${data.toString().trim()}`);
-            });
-            const ready = await waitForPort(devServerPort, devServerHost, 30_000);
-            if (!ready) {
-                devServerProcess?.kill();
-                devServerProcess = null;
-                return {
-                    content: [
-                        {
-                            type: 'text',
-                            text: JSON.stringify({
-                                error: `Dev server did not become ready on port ${devServerPort} within 30s.`,
-                                suggestion: 'Check that the project has a valid dev script in package.json.',
-                            }),
-                        },
-                    ],
-                    isError: true,
-                };
+            if (startupMode === 'manual_existing') {
+                const existingPort = args.existingPort ?? args.startPort ?? null;
+                if (!existingPort) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: JSON.stringify({
+                                    error: 'startupMode manual_existing requires an existingPort value.',
+                                    suggestion: 'Pass existingPort for your running dev server.',
+                                }),
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+                const manualValidation = await validateProjectServer({
+                    host: nextDevServerHost,
+                    port: existingPort,
+                    framework,
+                    projectPath,
+                });
+                if (!manualValidation.valid) {
+                    if (args.forceAttachExternal) {
+                        const isReachable = await waitForPort(existingPort, nextDevServerHost, 3000);
+                        if (!isReachable) {
+                            return {
+                                content: [
+                                    {
+                                        type: 'text',
+                                        text: JSON.stringify({
+                                            error: `Cannot attach to ${nextDevServerHost}:${existingPort} because it is not reachable.`,
+                                            validation: manualValidation,
+                                        }),
+                                    },
+                                ],
+                                isError: true,
+                            };
+                        }
+                        nextDevServerPort = existingPort;
+                        nextDevServerOwnership = 'external';
+                        log.info(`Force-attached to external dev server on ${nextDevServerHost}:${nextDevServerPort}`);
+                        updateBridgeHealth('healthy', true);
+                    }
+                    else if (manualValidation.selectedProjectPath ||
+                        (manualValidation.observedProcessPaths?.length ?? 0) > 0) {
+                        return {
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: JSON.stringify({
+                                        opened: false,
+                                        nextStep: 'mismatch_confirmation_required',
+                                        error: manualValidation.reason,
+                                        existingServerPort: existingPort,
+                                        selectedProjectPath: manualValidation.selectedProjectPath,
+                                        observedProcessPaths: manualValidation.observedProcessPaths,
+                                        validation: manualValidation,
+                                        nextAction: 'If the user confirms, call open_visual_editor again with startupMode: "manual_existing", existingPort, and forceAttachExternal: true. Otherwise ask for another port.',
+                                    }),
+                                },
+                            ],
+                            isError: false,
+                        };
+                    }
+                    else {
+                        return {
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: JSON.stringify({
+                                        error: manualValidation.reason,
+                                        validation: manualValidation,
+                                    }),
+                                },
+                            ],
+                            isError: true,
+                        };
+                    }
+                }
+                if (!nextDevServerPort) {
+                    nextDevServerPort = existingPort;
+                    nextDevServerOwnership = 'external';
+                    log.info(`Using existing dev server on ${nextDevServerHost}:${nextDevServerPort}`);
+                    updateBridgeHealth('healthy', true);
+                }
+            }
+            else {
+                const packageManager = await detection.detectPackageManager(projectPath);
+                const preferredPort = args.startPort ??
+                    detection.readConfiguredPort(projectPath) ??
+                    frameworkConfig.defaultPort;
+                nextDevServerPort = await (0, portUtils_1.findAvailablePort)(preferredPort);
+                const { cmd, args: cmdArgs, env, } = buildDevServerCommand(framework, packageManager, frameworkConfig.devCommand, nextDevServerPort);
+                log.info(`Auto-starting dev server: ${cmd} ${cmdArgs.join(' ')} in ${projectPath}`);
+                devServerProcess = (0, child_process_1.spawn)(cmd, cmdArgs, {
+                    cwd: projectPath,
+                    env: { ...process.env, ...env },
+                    stdio: 'pipe',
+                    detached: false,
+                });
+                nextDevServerOwnership = 'rivet_owned';
+                devServerProcess.on('error', (err) => {
+                    log.error('Dev server process error:', err);
+                });
+                devServerProcess.on('exit', (code) => {
+                    log.info(`Dev server exited with code ${code}`);
+                    devServerProcess = null;
+                    if (bridge.isActive()) {
+                        updateBridgeHealth('upstream_unreachable', false);
+                    }
+                });
+                devServerProcess.stdout?.on('data', (data) => {
+                    log.debug(`[dev-server] ${data.toString().trim()}`);
+                });
+                devServerProcess.stderr?.on('data', (data) => {
+                    log.debug(`[dev-server] ${data.toString().trim()}`);
+                });
+                const ready = await waitForPort(nextDevServerPort, nextDevServerHost, 30_000);
+                if (!ready) {
+                    if (devServerProcess) {
+                        await stopChildProcess(devServerProcess);
+                    }
+                    devServerProcess = null;
+                    const existingServer = await detection.findRunningDevServer(projectPath, [index_1.DEFAULT_PORT]);
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: JSON.stringify({
+                                    opened: false,
+                                    nextStep: 'manual_port_required',
+                                    error: `Dev server did not become ready on port ${nextDevServerPort} within 30s.`,
+                                    existingServerPort: existingServer?.port ?? null,
+                                    validation: null,
+                                    nextAction: 'Call open_visual_editor again with startupMode: "manual_existing" and existingPort set to a running app server port.',
+                                }),
+                            },
+                        ],
+                        isError: false,
+                    };
+                }
+                const startupValidation = await validateProjectServer({
+                    host: nextDevServerHost,
+                    port: nextDevServerPort,
+                    framework,
+                    projectPath,
+                });
+                if (!startupValidation.valid) {
+                    if (devServerProcess) {
+                        await stopChildProcess(devServerProcess);
+                    }
+                    devServerProcess = null;
+                    const existingServer = await detection.findRunningDevServer(projectPath, [index_1.DEFAULT_PORT]);
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: JSON.stringify({
+                                    opened: false,
+                                    nextStep: 'manual_port_required',
+                                    error: startupValidation.reason,
+                                    existingServerPort: existingServer?.port ?? null,
+                                    validation: startupValidation,
+                                    nextAction: 'Call open_visual_editor again with startupMode: "manual_existing" and existingPort set to a running app server port.',
+                                }),
+                            },
+                        ],
+                        isError: false,
+                    };
+                }
+                updateBridgeHealth('healthy', true);
+                log.info(`Dev server ready on ${nextDevServerHost}:${nextDevServerPort}`);
             }
-            log.info(`Dev server ready on ${devServerHost}:${devServerPort}`);
         }
         // Find a free port for Rivet's Express server (avoids conflict with desktop or other Rivet instances)
         let rivetPort;
@@ -381,8 +860,8 @@ const startMCPServer = async (mcpEditor) => {
                 serverHandle = await (0, server_1.startServer)({
                     framework,
                     projectPath,
-                    userPort: devServerPort,
-                    userHost: devServerHost,
+                    userPort: nextDevServerPort ?? 0,
+                    userHost: nextDevServerHost,
                     sessionBridge: bridge,
                     telemetry,
                     mcpEditor,
@@ -399,7 +878,9 @@ const startMCPServer = async (mcpEditor) => {
                 }
                 else {
                     const message = error instanceof Error ? error.message : 'Server start failed';
-                    devServerProcess?.kill();
+                    if (devServerProcess) {
+                        await stopChildProcess(devServerProcess);
+                    }
                     devServerProcess = null;
                     return {
                         content: [
@@ -414,7 +895,9 @@ const startMCPServer = async (mcpEditor) => {
             }
         }
         if (!serverStarted) {
-            devServerProcess?.kill();
+            if (devServerProcess) {
+                await stopChildProcess(devServerProcess);
+            }
             devServerProcess = null;
             return {
                 content: [
@@ -430,6 +913,21 @@ const startMCPServer = async (mcpEditor) => {
         }
         const sessionId = bridge.startSession(projectPath);
         sessionStartedAt = Date.now();
+        devServerOwnership = nextDevServerOwnership;
+        devServerHost = nextDevServerHost;
+        devServerPort = nextDevServerPort;
+        bridge.setDevServerContext({
+            ownership: devServerOwnership,
+            host: devServerHost,
+            port: devServerPort,
+            startedByRivet: devServerOwnership === 'rivet_owned',
+        });
+        if (devServerOwnership === 'none') {
+            updateBridgeHealth('unknown', null);
+        }
+        else {
+            updateBridgeHealth('healthy', true);
+        }
         // Write editor-specific guidance file on first successful open
         if (mcpEditor === 'cursor') {
             (0, skillWriter_1.writeCursorRulesIfNeeded)(projectPath);
@@ -440,7 +938,7 @@ const startMCPServer = async (mcpEditor) => {
         // Track session start
         telemetry.trackMCPSessionStart({
             framework,
-            devServerStarted: framework !== 'static',
+            devServerStarted: devServerOwnership === 'rivet_owned',
             sessionId,
             mcpEditor,
         });
@@ -462,7 +960,12 @@ const startMCPServer = async (mcpEditor) => {
                         projectPath,
                         framework,
                         rivetPort,
-                        devServerPort,
+                        opened: true,
+                        devServerPort: nextDevServerPort,
+                        devServerOwnership: nextDevServerOwnership,
+                        startupMode,
+                        startupModeSelection,
+                        requestedStartupMode,
                         next_step: `IMPORTANT: You must call watch_for_changes({ sessionId: "${sessionId}" }) RIGHT NOW to wait for the user's changes. Do not wait for the user to ask — call it immediately. It will block until they click "${sendButtonLabel}" in the browser.`,
                     }),
                 },
@@ -489,6 +992,7 @@ const startMCPServer = async (mcpEditor) => {
             intent = await bridge.waitForChanges(timeoutMs);
         }
         catch {
+            const health = bridge.getDevServerHealth();
             return {
                 content: [
                     {
@@ -496,6 +1000,7 @@ const startMCPServer = async (mcpEditor) => {
                         text: JSON.stringify({
                             hasChanges: false,
                             message: 'Timed out waiting for changes. Call again to keep waiting.',
+                            devServerHealth: health,
                         }),
                     },
                 ],
@@ -570,51 +1075,10 @@ const startMCPServer = async (mcpEditor) => {
                 isError: true,
             };
         }
-        const telemetryContext = bridge.getTelemetryContext();
-        const activeRunCorrelation = bridge.completeActiveRunCorrelation();
-        const totalRoundsCompleted = bridge.endSession();
-        const durationMs = sessionStartedAt ? Date.now() - sessionStartedAt : 0;
-        sessionStartedAt = null;
-        // Stop the Express server
-        if (serverHandle) {
-            try {
-                await serverHandle.close();
-            }
-            catch (error) {
-                log.warn('Error stopping Express server:', error);
-            }
-            serverHandle = null;
-        }
-        // Kill the dev server if we auto-started it
-        if (devServerProcess) {
-            try {
-                devServerProcess.kill();
-            }
-            catch (error) {
-                log.warn('Error stopping dev server process:', error);
-            }
-            devServerProcess = null;
-        }
-        telemetry.trackMCPSessionEnd({
-            sessionId: args.sessionId,
-            rounds: totalRoundsCompleted,
-            durationMs,
-            browserSessionId: telemetryContext?.browserSessionId,
-            browserDistinctId: telemetryContext?.browserDistinctId,
+        const { totalRoundsCompleted } = await cleanupSessionResources({
+            closeSessionId: args.sessionId,
+            trackSessionEnd: true,
         });
-        if (activeRunCorrelation) {
-            telemetry.trackAgentRunFailed({
-                traceId: activeRunCorrelation.traceId,
-                agentRunId: activeRunCorrelation.agentRunId,
-                sessionId: args.sessionId,
-                posthogSessionId: activeRunCorrelation.browserSessionId,
-                durationMs: Date.now() - activeRunCorrelation.startedAt,
-                errorType: 'mcp_session_closed',
-                errorMessage: 'MCP session closed before apply completion confirmation',
-                source: 'mcp',
-            });
-        }
-        await telemetry.flush();
         return {
             content: [
                 {