rivet-design 0.11.16 → 0.12.0

package/dist/mcp/server.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.startMCPServer = exports.createRivetMcp = exports.ackVariantBridgeLease = exports.ackApplyBridgeLease = exports.createVariantRequestLeaseTracker = exports.buildLeasedVariantResponse = exports.buildStaticPreviewRefineResponse = exports.collectStaticPreviewRefineTargetInstructions = exports.buildApplyChangesResponse = exports.buildNoPendingChangesResponse = exports.leaseAvailableBatchForPoll = exports.resolveLeasePickupRequestId = exports.buildVariantRequestBatchResponse = exports.buildMixedVariantBatchResponse = exports.startParentProcessMonitor = exports.buildVisualEditorWatchAction = exports.configureMcpStdioLogging = void 0;
+exports.startMCPServer = exports.createRivetMcp = exports.canReuseExistingProjectVisualEditor = exports.closeDetachedVisualEditorServer = exports.getActiveVisualEditorProjectAction = exports.buildVariantAckFailedResponse = exports.buildVariantManualAckBlockedResponse = exports.ackVariantBridgeLease = exports.ackApplyBridgeLease = exports.createVariantRequestLeaseTracker = exports.buildLeasedVariantResponse = exports.buildStaticPreviewRefineResponse = exports.collectStaticPreviewRefineTargetInstructions = exports.buildApplyChangesResponse = exports.buildNoPendingChangesResponse = exports.leaseAvailableBatchForPoll = exports.resolveLeasePickupRequestId = exports.buildVariantRequestBatchResponse = exports.buildMixedVariantBatchResponse = exports.startParentProcessMonitor = exports.buildVisualEditorWatchAction = exports.configureMcpStdioLogging = void 0;
 const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
 const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
 const v3_1 = require("zod/v3");
@@ -720,6 +720,39 @@ const variantRequestWorkKey = (sessionId, workItemId) => `${sessionId}:${workIte
 const createVariantRequestLeaseTracker = (params) => {
     const trackedByWorkItem = new Map();
     const trackedByRequest = new Map();
+    const finishedVariantWorkByRequest = new Map();
+    const markGeneratedWorkFinished = (lease) => {
+        finishedVariantWorkByRequest.set(lease.requestId, lease.leaseId);
+    };
+    const hasFinishedGeneratedWork = (lease) => finishedVariantWorkByRequest.get(lease.requestId) === lease.leaseId;
+    const findTrackedLease = (args) => {
+        if (args.requestId) {
+            const tracked = trackedByRequest.get(args.requestId);
+            if (tracked) {
+                return tracked;
+            }
+        }
+        if (args.leaseId) {
+            for (const tracked of trackedByRequest.values()) {
+                if (tracked.leaseId === args.leaseId) {
+                    return tracked;
+                }
+            }
+        }
+        return null;
+    };
+    const findActiveVariantLease = (args) => {
+        const activeLeases = params.activeVariantLeases?.() ?? [];
+        return (activeLeases.find((lease) => {
+            if (lease.kind !== 'variant') {
+                return false;
+            }
+            if (args.leaseId && lease.leaseId === args.leaseId) {
+                return true;
+            }
+            return Boolean(args.requestId && lease.requestId === args.requestId);
+        }) ?? null);
+    };
     return {
         claim(args) {
             if (!args.requestId) {
@@ -733,12 +766,14 @@ const createVariantRequestLeaseTracker = (params) => {
                 if (trackedByRequest.has(lease.requestId)) {
                     return;
                 }
+                markGeneratedWorkFinished(lease);
                 params.ackRequest({
                     leaseId: lease.leaseId,
                     requestId: lease.requestId,
                 });
                 return;
             }
+            finishedVariantWorkByRequest.delete(lease.requestId);
             const tracked = trackedByRequest.get(lease.requestId) ??
                 {
                     leaseId: lease.leaseId,
@@ -767,11 +802,36 @@ const createVariantRequestLeaseTracker = (params) => {
                 return;
             }
             trackedByRequest.delete(tracked.requestId);
+            markGeneratedWorkFinished(tracked);
             params.ackRequest({
                 leaseId: tracked.leaseId,
                 requestId: tracked.requestId,
             });
         },
+        getManualAckBlock(args) {
+            const tracked = findTrackedLease(args);
+            if (!tracked || tracked.remainingWorkItemIds.size === 0) {
+                const activeLease = findActiveVariantLease(args);
+                if (!activeLease) {
+                    return null;
+                }
+                if (hasFinishedGeneratedWork(activeLease)) {
+                    return null;
+                }
+                return {
+                    reason: 'variant_work_unclaimed',
+                    leaseId: activeLease.leaseId,
+                    requestId: activeLease.requestId,
+                    remainingWorkItemIds: [],
+                };
+            }
+            return {
+                reason: 'variant_work_unfinished',
+                leaseId: tracked.leaseId,
+                requestId: tracked.requestId,
+                remainingWorkItemIds: [...tracked.remainingWorkItemIds],
+            };
+        },
     };
 };
 exports.createVariantRequestLeaseTracker = createVariantRequestLeaseTracker;
@@ -801,8 +861,13 @@ const ackApplyBridgeLease = (args) => {
 };
 exports.ackApplyBridgeLease = ackApplyBridgeLease;
 const ackVariantBridgeLease = (args) => {
-    if (!args.leaseId)
-        return;
+    if (!args.leaseId) {
+        return {
+            ok: false,
+            reason: 'missing_lease_id',
+            requestId: args.requestId,
+        };
+    }
     const ackResult = args.bridge.ackBatch({
         leaseId: args.leaseId,
         requestId: args.requestId,
@@ -816,7 +881,12 @@ const ackVariantBridgeLease = (args) => {
             changeCount: ackResult.mergedRequestIds.length,
             sessionId,
         });
-        return;
+        return {
+            ok: true,
+            leaseId: args.leaseId,
+            requestId: args.requestId ?? ackResult.mergedRequestIds[0],
+            changeCount: ackResult.mergedRequestIds.length,
+        };
     }
     args.telemetry.trackMCPChangeAckFailed({
         channel: 'variant',
@@ -826,8 +896,82 @@ const ackVariantBridgeLease = (args) => {
         sessionId,
         failureReason: 'ack_failed',
     });
+    return {
+        ok: false,
+        reason: 'ack_failed',
+        leaseId: args.leaseId,
+        requestId: args.requestId,
+    };
 };
 exports.ackVariantBridgeLease = ackVariantBridgeLease;
+/** Builds the MCP error returned when generated variant work still owns a lease. */
+const buildVariantManualAckBlockedResponse = (block) => ({
+    content: [
+        {
+            type: 'text',
+            text: JSON.stringify({
+                error: 'variant_ack_blocked',
+                reason: block.reason,
+                message: block.reason === 'variant_work_unfinished'
+                    ? 'This variant request still has unfinished generated work. Finish it with report_variant_complete; do not use ack_batch to skip or finish generated variant work.'
+                    : 'This UI variant request has an active lease, but generated work has not claimed it yet. Process it through start_variants or scoped continue_variants({ action: "request_work", workItemIds }) and finish with report_variant_complete; do not use ack_batch to skip variant work.',
+                leaseId: block.leaseId,
+                requestId: block.requestId,
+                remainingWorkItemIds: block.remainingWorkItemIds,
+            }),
+        },
+    ],
+    isError: true,
+});
+exports.buildVariantManualAckBlockedResponse = buildVariantManualAckBlockedResponse;
+/** Builds the MCP error returned when ack_batch does not match an active variant lease. */
+const buildVariantAckFailedResponse = (result) => ({
+    content: [
+        {
+            type: 'text',
+            text: JSON.stringify({
+                error: 'variant_ack_failed',
+                reason: result.reason,
+                message: result.reason === 'missing_lease_id'
+                    ? 'ack_batch requires the leaseId from the variant batch.'
+                    : 'No active variant lease matched this ack_batch request.',
+                ...(result.leaseId ? { leaseId: result.leaseId } : {}),
+                ...(result.requestId ? { requestId: result.requestId } : {}),
+            }),
+        },
+    ],
+    isError: true,
+});
+exports.buildVariantAckFailedResponse = buildVariantAckFailedResponse;
+/**
+ * Chooses how an active visual editor session should handle a project change.
+ */
+const getActiveVisualEditorProjectAction = (args) => {
+    if (args.activeProjectPath === args.requestedProjectPath) {
+        return 'attach';
+    }
+    if (args.devServerOwnership === 'none') {
+        return 'rebind';
+    }
+    return 'restart';
+};
+exports.getActiveVisualEditorProjectAction = getActiveVisualEditorProjectAction;
+/**
+ * Closes a Rivet server handle that is no longer attached to a bridge session.
+ */
+const closeDetachedVisualEditorServer = async (args) => {
+    if (!args.serverHandle || args.isBridgeActive) {
+        return false;
+    }
+    await args.cleanup();
+    return true;
+};
+exports.closeDetachedVisualEditorServer = closeDetachedVisualEditorServer;
+/**
+ * Existing-project variants need a mounted upstream for the Original preview.
+ */
+const canReuseExistingProjectVisualEditor = (args) => Boolean(args.attachment && args.devServerOwnership !== 'none');
+exports.canReuseExistingProjectVisualEditor = canReuseExistingProjectVisualEditor;
 /**
  * Builds the fully configured Rivet MCP server (tools, auth gating, session
  * bridge, telemetry) without binding it to a transport. Shared by the stdio
@@ -916,6 +1060,13 @@ const createRivetMcp = (options) => {
         }
         return (0, exports.buildStaticPreviewRefineResponse)(consumedRequest, droppedRefinements, createdWorkItemIds, lease);
     };
+    /** Release a variant bridge lease after tracked generated work has finished. */
+    const ackGeneratedVariantBridgeLease = (args) => {
+        const result = (0, exports.ackVariantBridgeLease)({ bridge, telemetry, ...args });
+        if (!result.ok) {
+            log.warn(`Failed to release generated variant bridge lease ${args.leaseId}: ${result.reason}`);
+        }
+    };
     /** Complete an apply lease and refresh git status in the Rivet UI. */
     const handleApplyAck = (sessionId, args) => {
         const leaseId = args.leaseId ?? bridge.findActiveApplyLease()?.leaseId ?? undefined;
@@ -933,11 +1084,20 @@ const createRivetMcp = (options) => {
     };
     /** Release a variant lease after the agent finishes the batch. */
     const handleVariantAck = (args) => {
-        (0, exports.ackVariantBridgeLease)({ bridge, telemetry, ...args });
+        const manualAckBlock = variantRequestLeaseTracker.getManualAckBlock(args);
+        if (manualAckBlock) {
+            return (0, exports.buildVariantManualAckBlockedResponse)(manualAckBlock);
+        }
+        const result = (0, exports.ackVariantBridgeLease)({ bridge, telemetry, ...args });
+        if (!result.ok) {
+            return (0, exports.buildVariantAckFailedResponse)(result);
+        }
+        return null;
     };
     const variantRequestLeaseTracker = (0, exports.createVariantRequestLeaseTracker)({
         leaseRequest: (requestId) => bridge.leaseBatch(requestId),
-        ackRequest: handleVariantAck,
+        ackRequest: ackGeneratedVariantBridgeLease,
+        activeVariantLeases: () => getActiveLeaseMetadata(bridge),
     });
     /** Complete the active run correlation and refresh git status in the Rivet UI. */
     const handleRefreshGit = (sessionId) => {
@@ -1178,6 +1338,71 @@ const createRivetMcp = (options) => {
             await shutdown();
         });
     }
+    /** Returns an attachment for the current visual editor session, if one exists. */
+    const attachActiveVisualEditor = async (projectPath) => {
+        if (!bridge.isActive()) {
+            return null;
+        }
+        if (!rivetServerUrl || rivetServerPort === null) {
+            throw new Error('Rivet visual editor session is active but URL metadata is unavailable');
+        }
+        const activeEditorSessionId = bridge.getSessionId();
+        if (!activeEditorSessionId) {
+            throw new Error('Rivet visual editor session is active but has no session ID');
+        }
+        const projectAction = (0, exports.getActiveVisualEditorProjectAction)({
+            activeProjectPath: bridge.getProjectPath(),
+            requestedProjectPath: projectPath,
+            devServerOwnership,
+        });
+        if (projectAction === 'restart') {
+            await cleanupSessionResources({ trackSessionEnd: false });
+            return null;
+        }
+        if (projectAction === 'rebind') {
+            bridge.rebindProjectPath(projectPath);
+        }
+        // Don't spawn a duplicate tab when a Rivet page is already open. The
+        // variants flow re-enters this path on every propose/start call; calling
+        // `open()` again opens a fresh tab in most browsers rather than focusing
+        // the existing one. Only (re)open when no UI client is connected — i.e.
+        // the user closed the page and needs it back.
+        if (!agentVariantsOrchestrator.hasUiClients()) {
+            try {
+                await (0, open_1.default)(rivetServerUrl);
+            }
+            catch {
+                log.warn('Failed to focus existing Rivet browser automatically');
+            }
+        }
+        return {
+            sessionId: activeEditorSessionId,
+            url: rivetServerUrl,
+            rivetPort: rivetServerPort,
+            opened: false,
+            attached: true,
+        };
+    };
+    /** Reads feature flags for a visual editor session without blocking startup on flag failures. */
+    const resolveSessionGitEnabled = async () => {
+        try {
+            const featureFlags = await (0, evaluateFlags_1.getFeatureFlags)();
+            return featureFlags.gitUi.isEnabled;
+        }
+        catch (error) {
+            log.warn('Failed to evaluate feature flags for MCP session startup; defaulting git to enabled:', error);
+            return true;
+        }
+    };
+    /** Writes editor-specific guidance once a visual editor session is ready. */
+    const writeEditorGuidance = (projectPath) => {
+        if (mcpEditor === 'cursor') {
+            (0, skillWriter_1.writeCursorRulesIfNeeded)(projectPath);
+        }
+        else if (mcpEditor === 'claude' || mcpEditor === undefined) {
+            (0, skillWriter_1.writeSkillFileIfNeeded)();
+        }
+    };
     /**
      * Ensure zero-to-one variant sessions have a Rivet UI shell subscribed to
      * the shared variants orchestrator. Fresh projects do not have a base app
@@ -1188,38 +1413,17 @@ const createRivetMcp = (options) => {
         // The bridge tracks the generated project folder. That keeps /api/config,
         // history reads, and the committed preview focused on the same folder.
         const { projectPath } = input;
-        if (bridge.isActive()) {
-            if (!rivetServerUrl || rivetServerPort === null) {
-                throw new Error('Rivet visual editor session is active but URL metadata is unavailable');
-            }
-            const activeEditorSessionId = bridge.getSessionId();
-            if (!activeEditorSessionId) {
-                throw new Error('Rivet visual editor session is active but has no session ID');
-            }
-            if (bridge.getProjectPath() !== projectPath) {
-                bridge.rebindProjectPath(projectPath);
-            }
-            // Don't spawn a duplicate tab when a Rivet page is already open. The
-            // variants flow re-enters this path on every propose/start call; calling
-            // `open()` again opens a fresh tab in most browsers rather than focusing
-            // the existing one. Only (re)open when no UI client is connected — i.e.
-            // the user closed the page and needs it back.
-            if (!agentVariantsOrchestrator.hasUiClients()) {
-                try {
-                    await (0, open_1.default)(rivetServerUrl);
-                }
-                catch {
-                    log.warn('Failed to focus existing Rivet browser automatically');
-                }
-            }
-            return {
-                sessionId: activeEditorSessionId,
-                url: rivetServerUrl,
-                rivetPort: rivetServerPort,
-                opened: false,
-                attached: true,
-            };
-        }
+        const activeAttachment = await attachActiveVisualEditor(projectPath);
+        if (activeAttachment) {
+            return activeAttachment;
+        }
+        await (0, exports.closeDetachedVisualEditorServer)({
+            isBridgeActive: bridge.isActive(),
+            serverHandle,
+            cleanup: async () => {
+                await cleanupSessionResources({ trackSessionEnd: false });
+            },
+        });
         let nextRivetPort;
         try {
             nextRivetPort = await (0, portUtils_1.findAvailablePort)(index_1.DEFAULT_PORT);
@@ -1282,12 +1486,210 @@ const createRivetMcp = (options) => {
         // of through the open_visual_editor tool, so without this the
         // SKILL.md / rivet.mdc file would never be rewritten when only
         // start_variants is used.
-        if (mcpEditor === 'cursor') {
-            (0, skillWriter_1.writeCursorRulesIfNeeded)(input.projectPath);
+        writeEditorGuidance(input.projectPath);
+        const url = `http://localhost:${nextRivetPort}/rivet`;
+        rivetServerPort = nextRivetPort;
+        rivetServerUrl = url;
+        try {
+            await (0, open_1.default)(url);
         }
-        else if (mcpEditor === 'claude' || mcpEditor === undefined) {
-            (0, skillWriter_1.writeSkillFileIfNeeded)();
+        catch {
+            log.warn('Failed to open browser automatically');
         }
+        return {
+            sessionId: editorSessionId,
+            url,
+            rivetPort: nextRivetPort,
+            opened: true,
+            attached: false,
+        };
+    };
+    /**
+     * Ensure existing-project variant sessions have the base app mounted as the
+     * default preview upstream before variant preview targets are selected.
+     */
+    const ensureExistingVisualEditorOpen = async (input) => {
+        const { projectPath } = input;
+        const activeAttachment = await attachActiveVisualEditor(projectPath);
+        if (activeAttachment &&
+            (0, exports.canReuseExistingProjectVisualEditor)({
+                attachment: activeAttachment,
+                devServerOwnership,
+            })) {
+            return activeAttachment;
+        }
+        if (activeAttachment) {
+            await cleanupSessionResources({ trackSessionEnd: false });
+        }
+        await (0, exports.closeDetachedVisualEditorServer)({
+            isBridgeActive: bridge.isActive(),
+            serverHandle,
+            cleanup: async () => {
+                await cleanupSessionResources({ trackSessionEnd: false });
+            },
+        });
+        const detection = new index_core_1.ProjectDetectionService();
+        let nextDevServerPort = null;
+        let nextDevServerHost = 'localhost';
+        let nextDevServerOwnership = 'none';
+        let staticTarget = null;
+        if (input.framework === 'static') {
+            staticTarget = (0, staticProjectTarget_1.resolveStaticProjectTarget)({ targetPath: projectPath });
+            if ((0, staticProjectTarget_1.needsStaticEntryPath)(staticTarget)) {
+                throw new Error('Static folder has multiple HTML files and no index.html. Open the visual editor with a specific entry path before starting variants.');
+            }
+            const entryFullPath = path_1.default.join(projectPath, staticTarget.entryPath);
+            const didWriteStarter = staticTarget.htmlEntryFiles.length === 0
+                ? (0, staticStarter_1.ensureStaticStarterCanvas)(projectPath)
+                : false;
+            const hasStaticEntry = fs_1.default.existsSync(entryFullPath) ||
+                (didWriteStarter && staticTarget.entryPath === 'index.html');
+            if (hasStaticEntry) {
+                nextDevServerHost = '127.0.0.1';
+                nextDevServerPort = await (0, portUtils_1.findAvailablePort)(index_1.DEFAULT_USER_PORT);
+                devServerProcess = await (0, StaticPreviewServer_1.startStaticPreviewServer)({
+                    rootPath: projectPath,
+                    port: nextDevServerPort,
+                    host: nextDevServerHost,
+                });
+                nextDevServerOwnership = 'rivet_owned';
+                devServerProcess.on('exit', (code) => {
+                    log.info(`Static preview server exited with code ${code}`);
+                    devServerProcess = null;
+                    if (bridge.isActive()) {
+                        updateBridgeHealth('upstream_unreachable', false);
+                    }
+                });
+                updateBridgeHealth('healthy', true);
+                log.info(`Static preview server ready on ${nextDevServerHost}:${nextDevServerPort}`);
+            }
+        }
+        else {
+            const frameworkConfig = devServerCommand_1.FRAMEWORK_DEV_CONFIG[input.framework];
+            const packageManager = await detection.detectPackageManager(projectPath);
+            const preferredPort = detection.readConfiguredPort(projectPath) ?? frameworkConfig.defaultPort;
+            nextDevServerPort = await (0, portUtils_1.findAvailablePort)(preferredPort);
+            const { cmd, args: cmdArgs, env, } = (0, devServerCommand_1.buildDevServerCommand)(input.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.warn('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;
+                throw new Error(`Dev server did not become ready on port ${nextDevServerPort} within 30s.`);
+            }
+            const startupValidation = await validateProjectServer({
+                host: nextDevServerHost,
+                port: nextDevServerPort,
+                framework: input.framework,
+                projectPath,
+            });
+            if (!startupValidation.valid) {
+                if (devServerProcess) {
+                    await stopChildProcess(devServerProcess);
+                }
+                devServerProcess = null;
+                throw new Error(startupValidation.reason);
+            }
+            updateBridgeHealth('healthy', true);
+            log.info(`Dev server ready on ${nextDevServerHost}:${nextDevServerPort}`);
+        }
+        let nextRivetPort;
+        try {
+            nextRivetPort = await (0, portUtils_1.findAvailablePort)(index_1.DEFAULT_PORT);
+        }
+        catch (error) {
+            log.warn(`Port discovery failed for existing-project editor, falling back to ${index_1.DEFAULT_PORT}:`, error);
+            nextRivetPort = index_1.DEFAULT_PORT;
+        }
+        let retries = 0;
+        const maxRetries = 5;
+        const isGitEnabledForSession = await resolveSessionGitEnabled();
+        while (!serverHandle && retries < maxRetries) {
+            try {
+                serverHandle = await (0, server_1.startServer)({
+                    framework: input.framework,
+                    projectPath,
+                    staticEntry: staticTarget?.entryPath,
+                    userPort: nextDevServerPort ?? 0,
+                    userHost: nextDevServerHost,
+                    sessionBridge: bridge,
+                    agentVariantsOrchestrator,
+                    telemetry,
+                    mcpEditor,
+                    skipProcessHandlers: true,
+                    rivetPort: nextRivetPort,
+                    isGitEnabled: isGitEnabledForSession,
+                });
+            }
+            catch (error) {
+                if (error?.code !== 'EADDRINUSE') {
+                    if (devServerProcess) {
+                        await stopChildProcess(devServerProcess);
+                    }
+                    devServerProcess = null;
+                    throw error;
+                }
+                retries++;
+                nextRivetPort = await (0, portUtils_1.findAvailablePort)(nextRivetPort + 1);
+                log.debug(`Existing-project editor port in use, retrying with port ${nextRivetPort} (attempt ${retries}/${maxRetries})`);
+            }
+        }
+        if (!serverHandle) {
+            if (devServerProcess) {
+                await stopChildProcess(devServerProcess);
+            }
+            devServerProcess = null;
+            throw new Error(`Could not start Rivet server after ${maxRetries} attempts.`);
+        }
+        const editorSessionId = 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);
+        }
+        telemetry.trackMCPSessionStart({
+            framework: input.framework,
+            devServerStarted: devServerOwnership === 'rivet_owned',
+            sessionId: editorSessionId,
+            mcpEditor,
+        });
+        writeEditorGuidance(projectPath);
         const url = `http://localhost:${nextRivetPort}/rivet`;
         rivetServerPort = nextRivetPort;
         rivetServerUrl = url;
@@ -1854,7 +2256,7 @@ const createRivetMcp = (options) => {
             ],
         };
     });
-    guardedMcp.tool('watch_for_changes', `Required visual-editor watch loop. Call immediately after a successful open_visual_editor response, or after a start_variants response that includes editorNextAction/visualEditor. It blocks until the user sends a change batch, then returns a leased payload with leaseId and kind. After editing files (apply) call watch_for_changes again with refresh_git: true and the leaseId to release the lease and refresh git. After variant batches call watch_for_changes with ack_batch: true and the leaseId. If it times out (hasChanges: false), call it again to keep waiting.`, {
+    guardedMcp.tool('watch_for_changes', `Required visual-editor watch loop. Call immediately after a successful open_visual_editor response, or after a start_variants response that includes editorNextAction/visualEditor. It blocks until the user sends a change batch, then returns a leased payload with leaseId and kind. After editing files (apply), call watch_for_changes again with refresh_git: true and the leaseId to release the apply lease and refresh git. For UI-originated variant_request/static_preview_refine batches, lease the exact workItemIds and finish generated work with report_variant_complete; do not use ack_batch to skip or finish generated variant work. If it times out (hasChanges: false), call it again to keep waiting.`, {
         sessionId: v3_1.z
             .string()
             .describe('The session ID returned by open_visual_editor'),
@@ -1875,7 +2277,7 @@ const createRivetMcp = (options) => {
         ack_batch: v3_1.z
             .boolean()
             .optional()
-            .describe('After completing a variant lease: set true with leaseId to release the leased batch'),
+            .describe('Only for variant leases that are not tied to generated work items. UI-originated variant_request/static_preview_refine work is released by report_variant_complete; unclaimed or unfinished generated work rejects ack_batch.'),
         leaseId: v3_1.z
             .string()
             .optional()
@@ -1907,10 +2309,13 @@ const createRivetMcp = (options) => {
             });
         }
         if (args.ack_batch) {
-            handleVariantAck({
+            const ackError = handleVariantAck({
                 leaseId: args.leaseId,
                 requestId: args.requestId,
             });
+            if (ackError) {
+                return ackError;
+            }
         }
         // `handleApplyAck` sets READY so the UI can clear comment markers. Do not
         // overwrite it synchronously — the UI polls `/api/mcp/status` and needs
@@ -1942,7 +2347,7 @@ const createRivetMcp = (options) => {
             activeLeases: getActiveLeaseMetadata(bridge),
         });
     });
-    guardedMcp.tool('get_pending_changes', `Pick up pending design changes from the Rivet visual editor. Returns a leased batch with leaseId and kind when work is queued. After editing files (apply), call again with refresh_git: true and leaseId to ack and refresh git. After variant batches, call with ack_batch: true and leaseId. Returns hasChanges: false if no changes are queued yet.`, {
+    guardedMcp.tool('get_pending_changes', `Pick up pending design changes from the Rivet visual editor. Returns a leased batch with leaseId and kind when work is queued. After editing files (apply), call again with refresh_git: true and leaseId to ack and refresh git. For UI-originated variant_request/static_preview_refine batches, lease the exact workItemIds and finish generated work with report_variant_complete; do not use ack_batch to skip or finish generated variant work. Returns hasChanges: false if no changes are queued yet.`, {
         sessionId: v3_1.z
             .string()
             .describe('The session ID returned by open_visual_editor'),
@@ -1957,7 +2362,7 @@ const createRivetMcp = (options) => {
         ack_batch: v3_1.z
             .boolean()
             .optional()
-            .describe('After completing a variant lease: set true with leaseId to release the leased batch'),
+            .describe('Only for variant leases that are not tied to generated work items. UI-originated variant_request/static_preview_refine work is released by report_variant_complete; unclaimed or unfinished generated work rejects ack_batch.'),
         leaseId: v3_1.z
             .string()
             .optional()
@@ -1988,10 +2393,13 @@ const createRivetMcp = (options) => {
             });
         }
         if (args.ack_batch) {
-            handleVariantAck({
+            const ackError = handleVariantAck({
                 leaseId: args.leaseId,
                 requestId: args.requestId,
             });
+            if (ackError) {
+                return ackError;
+            }
         }
         const routed = leaseAndRouteBatch(args.sessionId, (0, exports.resolveLeasePickupRequestId)(args));
         if (routed) {
@@ -2035,6 +2443,7 @@ const createRivetMcp = (options) => {
         orchestrator: agentVariantsOrchestrator,
         leaseOwner: () => 'mcp-server',
         ensureVisualEditorOpen: ensureZeroToOneVisualEditorOpen,
+        ensureExistingVisualEditorOpen,
         getProjectPath: () => bridge.getProjectPath(),
         resolveVariantRequestProjectPath: (requestId) => bridge.resolveVariantRequestProjectPath(requestId),
         pendingVariantRequestCount: () => bridge.pendingVariantRequestCount(),