rivet-design 0.10.6 → 0.10.8

package/dist/mcp/agent-variants/WorktreeOrchestrator.js

@@ -13,9 +13,11 @@ const path_1 = __importDefault(require("path"));
 const child_process_1 = require("child_process");
 const simple_git_1 = require("simple-git");
 const logger_1 = require("../../utils/logger");
+const devServerError_1 = require("../../utils/devServerError");
 const errors_1 = require("./errors");
 const createProjectArtifacts_1 = require("./createProjectArtifacts");
 const contracts_1 = require("./contracts");
+const runPlan_1 = require("./runPlan");
 const viteReactTs_1 = require("../../services/templates/viteReactTs");
 const StaticPreviewServer_1 = require("../../services/StaticPreviewServer");
 const designCatalog_1 = require("../../services/templates/designCatalog");
@@ -23,6 +25,9 @@ const previewQa_1 = require("./previewQa");
 const VariantHistoryService_1 = require("../../services/VariantHistoryService");
 const log = (0, logger_1.createLogger)('AgentVariantsOrchestrator');
 const FRESH_DEV_SERVER_HOST = '127.0.0.1';
+// Fresh worktrees run the Vite React template, whose dev server defaults to
+// 5173. Used as the scan start when allocating a fresh variant's preview port.
+const FRESH_DEV_SERVER_DEFAULT_PORT = 5173;
 const DESIGN_CONTEXT_ROUTE_SEGMENT = 'design-md';
 const DESIGN_CONTEXT_VIEW_SEGMENT = 'view';
 // Hard ceiling on worktree provisioning so a slow/large host project can never
@@ -323,8 +328,7 @@ class AgentVariantsOrchestrator {
         this.variantHistory = deps.variantHistory ?? new VariantHistoryService_1.VariantHistoryService();
         this.startStaticPreviewServerImpl =
             deps.startStaticPreviewServer ?? StaticPreviewServer_1.startStaticPreviewServer;
-        this.provisionTimeoutMs =
-            deps.provisionTimeoutMs ?? PROVISION_TIMEOUT_MS;
+        this.provisionTimeoutMs = deps.provisionTimeoutMs ?? PROVISION_TIMEOUT_MS;
     }
     // --- Pure delegations (no side effects) ---------------------------------
     propose(args) {
@@ -359,6 +363,47 @@ class AgentVariantsOrchestrator {
             this.events.off('change', listener);
         };
     }
+    /** Number of live Rivet UI clients subscribed to the variants SSE stream.
+     *  A subscribed client means a Rivet page is open in the browser. */
+    uiClientCount = 0;
+    /** Wall-clock of the last UI-client connect/disconnect. `hasUiClients`
+     *  treats a very recent disconnect as still-connected to ride out the brief
+     *  gap when an EventSource drops and auto-reconnects (default retry ~3s) —
+     *  otherwise a `propose`/`start` landing in that window reads zero clients
+     *  and spawns a duplicate browser tab. */
+    lastUiClientActivityAt = 0;
+    /** Grace window covering an EventSource reconnect (its default retry is ~3s;
+     *  the SSE heartbeat is 30s). Long enough to span a reconnect, short enough
+     *  that a genuine page close frees the "reopen on next propose" path quickly. */
+    static UI_CLIENT_GRACE_MS = 6000;
+    /**
+     * Register a live Rivet UI client (called when the variants SSE stream opens).
+     * Returns a release fn to call on disconnect. Used as the "a Rivet page is
+     * already open" signal so the MCP server can avoid spawning a duplicate tab
+     * every time the variants flow re-enters an already-active editor session.
+     */
+    registerUiClient() {
+        this.uiClientCount += 1;
+        this.lastUiClientActivityAt = Date.now();
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            this.uiClientCount = Math.max(0, this.uiClientCount - 1);
+            this.lastUiClientActivityAt = Date.now();
+        };
+    }
+    /** True when at least one Rivet UI page is currently connected — or one
+     *  disconnected within the grace window (an EventSource mid-reconnect). */
+    hasUiClients() {
+        if (this.uiClientCount > 0)
+            return true;
+        if (this.lastUiClientActivityAt === 0)
+            return false;
+        return (Date.now() - this.lastUiClientActivityAt <
+            AgentVariantsOrchestrator.UI_CLIENT_GRACE_MS);
+    }
     /** Build the snapshot the chip cares about. Reads from SessionStore +
      *  per-resource state; safe to call at any time. */
     buildActiveSnapshot() {
@@ -466,18 +511,7 @@ class AgentVariantsOrchestrator {
             if (seenVariantIds.has(target.variantId))
                 continue;
             seenVariantIds.add(target.variantId);
-            const currentHtml = this.resources
-                .get(args.sessionId)
-                ?.staticPreviews.get(target.variantId)?.html ??
-                (() => {
-                    try {
-                        const output = this.store.getWorkItemOutput(args.sessionId, target.variantId);
-                        return output?.html;
-                    }
-                    catch {
-                        return undefined;
-                    }
-                })();
+            const currentHtml = this.getStaticPreviewHtml(args.sessionId, target.variantId);
             try {
                 this.store.createRefineVariantWorkItem({
                     sessionId: args.sessionId,
@@ -532,18 +566,7 @@ class AgentVariantsOrchestrator {
                 throw error;
             }
         }
-        const currentHtml = this.resources
-            .get(args.sessionId)
-            ?.staticPreviews.get(args.variantId)?.html ??
-            (() => {
-                try {
-                    const output = this.store.getWorkItemOutput(args.sessionId, args.variantId);
-                    return output?.html;
-                }
-                catch {
-                    return undefined;
-                }
-            })();
+        const currentHtml = this.getStaticPreviewHtml(args.sessionId, args.variantId);
         const refineItem = this.store.createRefineVariantWorkItem({
             sessionId: args.sessionId,
             variantId: args.variantId,
@@ -614,6 +637,16 @@ class AgentVariantsOrchestrator {
             const isSucceeded = variant.status === 'succeeded';
             const qaFailed = qa?.status === 'failed';
             const canView = Boolean(preview) || (isSucceeded && Boolean(port));
+            // A succeeded variant with no live preview whose dev server we tried and
+            // failed to start: surface the cause so the UI can show an accurate
+            // per-direction message instead of the generic disconnected overlay.
+            const previewFailure = resources?.previewFailures.get(variant.workItemId);
+            const previewUnavailable = !canView && isSucceeded && previewFailure
+                ? {
+                    reason: previewFailure.reason,
+                    ...(previewFailure.portInUse ? { portInUse: true } : {}),
+                }
+                : undefined;
             const canCommit = isSucceeded && !qaFailed;
             const commitDisabledReason = qaFailed
                 ? (qa?.summary ?? 'Variant failed QA')
@@ -624,6 +657,7 @@ class AgentVariantsOrchestrator {
                 ...(preview ? { preview } : {}),
                 port,
                 ...(qa ? { qa } : {}),
+                ...(previewUnavailable ? { previewUnavailable } : {}),
                 actions: {
                     view: canView
                         ? { enabled: true }
@@ -668,14 +702,25 @@ class AgentVariantsOrchestrator {
         return this.resources.get(sessionId)?.worktrees.get(workItemId)?.port;
     }
     getStaticPreviewHtml(sessionId, workItemId) {
-        // Primary: from the staticPreviews Map populated by handleSucceededReport.
-        const fromMap = this.resources
+        // Primary: read the materialized index.html from the variant's per-variant
+        // directory (written by handleSucceededReport). The directory is the source
+        // of truth for the static deliverable.
+        const dir = this.resources
             .get(sessionId)
-            ?.staticPreviews.get(workItemId)?.html;
-        if (fromMap)
-            return fromMap;
+            ?.staticPreviews.get(workItemId)?.assetBase;
+        if (dir) {
+            try {
+                const fromDisk = fs_1.default.readFileSync(path_1.default.join(dir, 'index.html'), 'utf8');
+                if (fromDisk.length > 0)
+                    return fromDisk;
+            }
+            catch {
+                // fall through to the work-item output fallback below
+            }
+        }
         // Fallback: read directly from the work item's stored output — available
-        // as soon as reportComplete runs, before handleSucceededReport fires.
+        // as soon as reportComplete runs, before handleSucceededReport fires (so
+        // the per-variant directory may not exist yet).
         try {
             const output = this.store.getWorkItemOutput(sessionId, workItemId);
             return typeof output?.html === 'string' && output.html.length > 0
@@ -707,7 +752,7 @@ class AgentVariantsOrchestrator {
         const record = this.resources
             .get(sessionId)
             ?.staticPreviews.get(workItemId);
-        return Boolean(record?.assetBase);
+        return Boolean(record?.hasAssets);
     }
     /**
      * Resolve an absolute, sandboxed path for a sibling asset that the
@@ -818,9 +863,10 @@ class AgentVariantsOrchestrator {
      * Supports both existing-project sessions (spawns code_gen work items
      * for the agent to lease) and zero-to-one sessions (spawns
      * static_preview work items; the server runs scaffold_base in the
-     * background). For zero-to-one sessions with source URLs / inspiration
-     * extraction, callers must use create_zero_to_one_project instead —
-     * this method does not run source research.
+     * background). This is the single-call path; source-grounded zero-to-one
+     * sessions (source URLs / inspiration extraction) run through `propose`
+     * instead so the source-research flow can gate generation — start_variants
+     * routes them there. This method does not run source research.
      *
      * Host-agnostic: no LLM calls happen here. The agent (Claude Code,
      * Cursor, Codex) generates the label and code when it leases the
@@ -839,7 +885,11 @@ class AgentVariantsOrchestrator {
             Boolean(sourceContext?.sourceIntent) ||
             Boolean(sourceContext?.artifact);
         if (isSourceGrounded) {
-            throw new errors_1.AgentVariantsError('INVALID_STAGE_ACTION', 'start_variants cannot handle source-grounded sessions. Use create_zero_to_one_project for inspiration-grounded fresh projects.');
+            // startUnified is the single-call path; source-grounded sessions must
+            // run through `propose` so the source-research flow gates generation.
+            // start_variants routes them there before reaching here — this guard is
+            // an internal invariant, not a user-facing dead end.
+            throw new errors_1.AgentVariantsError('INVALID_STAGE_ACTION', 'Source-grounded sessions must run through the source-research flow (propose), not the single-call startUnified path.');
         }
         const proposeResult = this.propose({
             prompt: args.prompt,
@@ -922,6 +972,15 @@ class AgentVariantsOrchestrator {
         };
     }
     async reportComplete(args) {
+        // Cooperative abort short-circuit: if the work item was removed/cancelled
+        // while in flight (delete-while-loading, cancel_variant, session cancel),
+        // skip the schema and QA gates entirely — there is no point validating or
+        // QA-ing output we are about to discard — and hand back the store's
+        // `aborted` signal so the agent stops this work item now.
+        if (this.store.hasSession(args.sessionId) &&
+            this.store.isWorkItemAborted(args.sessionId, args.workItemId)) {
+            return this.store.reportComplete(args);
+        }
         const workItemKind = this.store.hasSession(args.sessionId)
             ? this.store.getWorkItemKind(args.sessionId, args.workItemId)
             : undefined;
@@ -1303,9 +1362,12 @@ class AgentVariantsOrchestrator {
             catch {
                 realDestination = undefined;
             }
-            const freshMode = projectContext.executionPlan?.mode === 'vite_app'
-                ? 'vite_app'
-                : 'static_preview';
+            // Read the commit policy off the canonical run plan rather than
+            // re-deriving from executionPlan.mode. `materialize_project` is the
+            // vite_app lane (rename/copy the whole worktree); `write_static_site`
+            // is the static_preview lane (inline HTML + sibling assets).
+            const commitPolicy = (0, runPlan_1.resolveRunPlanPolicy)(projectContext).commit;
+            const isViteApp = commitPolicy === 'materialize_project';
             // vite_app: strict emptiness check — that lane renames a worktree into
             // destinationPath and would clobber user files.
             // static_preview: the agent intentionally wrote sibling assets under
@@ -1313,7 +1375,7 @@ class AgentVariantsOrchestrator {
             // those per-variant subdirs ARE the deliverable. Allow exactly the
             // assetBase entries known to this session; anything else still
             // triggers DESTINATION_NOT_EMPTY.
-            if (freshMode === 'vite_app') {
+            if (isViteApp) {
                 this.assertDestinationAvailable(destinationPath);
             }
             else {
@@ -1341,7 +1403,7 @@ class AgentVariantsOrchestrator {
                     this.assertDestinationAvailable(destinationPath, allowed);
                 }
             }
-            if (freshMode === 'vite_app') {
+            if (isViteApp) {
                 // Vite_app: the deliverable is the entire variant worktree, not a
                 // single HTML file. When the worktree lives on the same volume as
                 // the destination (the common case — provisionFreshWorktrees scaffolds
@@ -1463,6 +1525,15 @@ class AgentVariantsOrchestrator {
                 // so a process restart between report_variant_complete and commit
                 // doesn't strand the variant.
                 const staticPreview = resources.staticPreviews.get(args.variantId);
+                // Resolve the committed index.html before the flatten step below
+                // moves/removes the per-variant dir. `getStaticPreviewHtml` reads the
+                // materialized `<dir>/index.html` and falls back to the work-item's
+                // stored output (the reported HTML) when the on-disk file is missing
+                // or empty — so a failed materialization still commits real content
+                // rather than an empty file.
+                const htmlFromDir = staticPreview
+                    ? this.getStaticPreviewHtml(args.sessionId, args.variantId)
+                    : undefined;
                 const htmlFromSnapshot = await this.variantHistory.readStaticPreview({
                     projectPath: projectContext.workspaceRoot,
                     sessionId: args.sessionId,
@@ -1545,7 +1616,7 @@ class AgentVariantsOrchestrator {
                             fs_1.default.rmSync(other.assetBase, { recursive: true, force: true });
                         }
                     }
-                    fs_1.default.writeFileSync(path_1.default.join(destinationPath, 'index.html'), staticPreview?.html ?? htmlFromSnapshot ?? '', 'utf8');
+                    fs_1.default.writeFileSync(path_1.default.join(destinationPath, 'index.html'), htmlFromDir ?? htmlFromSnapshot ?? '', 'utf8');
                 }
                 catch (err) {
                     const message = err instanceof Error ? err.message : String(err);
@@ -1731,9 +1802,10 @@ class AgentVariantsOrchestrator {
         const projectContext = this.store.getProjectContext(sessionId);
         const variantCount = approveResult.codeGenWorkItemIds.length +
             (approveResult.scaffoldBaseWorkItemId ? 1 : 0);
-        // Fresh + static_preview provisions nothing (HTML is the deliverable) —
-        // skip the timing/telemetry wrapper so the fast path stays untouched.
-        if (projectContext.kind === 'fresh' && !approveResult.scaffoldBaseWorkItemId) {
+        // Generated + static_preview provisions nothing (HTML is the deliverable)
+        // — skip the timing/telemetry wrapper so the fast path stays untouched.
+        // `provision: 'none'` is exactly the no-scaffold generated-static lane.
+        if ((0, runPlan_1.resolveRunPlanPolicy)(projectContext).provision === 'none') {
             return;
         }
         const startedAt = Date.now();
@@ -1795,7 +1867,7 @@ class AgentVariantsOrchestrator {
                     `project is very large or slow to clone (e.g. a big monorepo, or a ` +
                     `React Native tree with native build dirs that aren't git-ignored). ` +
                     `Try git-ignoring build artifacts, or generate standalone variants ` +
-                    `with create_zero_to_one_project instead of cloning this project.`);
+                    `with start_variants(mode='zero_to_one') instead of cloning this project.`);
             }
             throw err;
         }
@@ -2071,15 +2143,51 @@ class AgentVariantsOrchestrator {
             if (staticPreview) {
                 const input = this.store.getWorkItemInput(sessionId, workItemId);
                 if (input.briefId) {
+                    const projectContext = this.store.getProjectContext(sessionId);
                     const resolvedAssetBase = resolveStaticPreviewAssetBase({
                         assetBase: staticPreview.assetBase,
-                        projectContext: this.store.getProjectContext(sessionId),
+                        projectContext,
                     });
+                    // Materialize the variant into a per-variant directory so every
+                    // static variant is directory-backed (the same shape as the
+                    // worktree-based variants). Reuse the agent's assetBase dir when it
+                    // wrote sibling assets; otherwise create a Rivet-managed per-variant
+                    // dir under workspacePath. `staticPreview.html` is the complete built
+                    // document (html + css + js), written as index.html.
+                    const workspacePath = projectContext.kind === 'fresh'
+                        ? projectContext.workspacePath
+                        : undefined;
+                    let dir = resolvedAssetBase ??
+                        (workspacePath
+                            ? path_1.default.join(workspacePath, `.rivet-preview-${workItemId}`)
+                            : undefined);
+                    if (!dir) {
+                        log.warn(`static preview for ${workItemId} has no workspace dir; skipping`);
+                        return;
+                    }
+                    try {
+                        fs_1.default.mkdirSync(dir, { recursive: true });
+                        // Realpath the dir so it lines up with the realpath'd destination
+                        // the commit emptiness-check compares against (macOS symlinks
+                        // `/var` → `/private/var`). `resolveStaticPreviewAssetBase`
+                        // already realpaths the agent-provided case; do the same for the
+                        // Rivet-created dir.
+                        try {
+                            dir = fs_1.default.realpathSync(dir);
+                        }
+                        catch {
+                            // keep the un-realpath'd path if realpath fails
+                        }
+                        fs_1.default.writeFileSync(path_1.default.join(dir, 'index.html'), staticPreview.html, 'utf8');
+                    }
+                    catch (err) {
+                        log.warn(`failed to materialize static preview index.html for ${workItemId}`, err);
+                    }
                     const record = {
                         workItemId,
                         briefId: input.briefId,
-                        html: staticPreview.html,
-                        ...(resolvedAssetBase ? { assetBase: resolvedAssetBase } : {}),
+                        assetBase: dir,
+                        hasAssets: Boolean(resolvedAssetBase),
                     };
                     resources.staticPreviews.set(workItemId, record);
                     if (this.store.getProjectContext(sessionId).kind === 'fresh') {
@@ -2152,43 +2260,105 @@ class AgentVariantsOrchestrator {
                 log.warn(`persistCompletedFreshVariant failed for ${sessionId}/${workItemId}`, err);
             });
         }
+        // Static existing-mode projects (framework='static', no dev command) have
+        // no per-variant dev server to proxy the iframe at. Serve the variant's
+        // materialized static files directly — the same renderer the chip/iframe
+        // already uses for fresh static_preview variants — so the variant is
+        // viewable/cyclable instead of being silently stuck on "Preview is
+        // unavailable for this variant". When this succeeds there is no dev server
+        // to bring up, so skip the proxy path below.
+        if (!isFresh) {
+            const servedStatic = await this.registerExistingStaticPreview(sessionId, workItemId, record);
+            // Existing projects resolve their preview surface at success time (the
+            // one genuinely-late axis of the run plan): a framework='static' project
+            // materializes static files → static_artifact and needs no dev server;
+            // anything else falls through to the dev-server proxy below.
+            if ((0, runPlan_1.existingPreviewKind)(servedStatic) === 'static_artifact') {
+                this.emitChange();
+                return;
+            }
+        }
         // Bring up a dev server in the variant's worktree so the user can cycle
         // through live variants in the iframe via the chip. Failures here are
         // logged but non-fatal — the user can still pick by reading the diff.
-        try {
-            const port = await this.worktrees.getFreePort();
-            const dev = await this.resolveDevServer(sessionId, record.worktreePath, port, isFresh);
-            const proc = await this.worktrees.startDevServer(dev.cwd, port, dev.cmd, dev.args, dev.env);
-            record.port = port;
-            record.devServerProcess = proc;
-            // If the dev server dies on its own (crash, OOM, Vite hard-fail),
-            // clear the port so the iframe stops routing the chip onto a dead
-            // socket. Without this the proxy retargets onto an unreachable port
-            // and the chip shows "upstream_unreachable" instead of the accurate
-            // "Preview is unavailable for this variant".
-            proc.once('exit', (code, signal) => {
-                if (record.devServerProcess !== proc)
-                    return;
-                record.port = undefined;
-                record.devServerProcess = undefined;
-                log.warn(`Variant ${workItemId} dev server exited unexpectedly (code=${code ?? 'null'}, signal=${signal ?? 'null'}); preview disabled`);
+        //
+        // Pick a sensible port near the framework's default (3000 for Next, 5173
+        // for Vite) and inject it via PORT + the CLI flag (see buildDevServerCommand)
+        // so the server actually binds it — that's what moves a preview off a port
+        // the user's own dev server already holds instead of colliding on it. On a
+        // retry we scan past the port we just tried, so a transient race or a
+        // briefly-held port resolves onto the next free one.
+        const startPort = await this.resolveDevServerStartPort(sessionId, isFresh);
+        let scanFrom = startPort;
+        const maxAttempts = 2;
+        for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+            let port;
+            try {
+                port = await this.worktrees.findFreePortFrom(scanFrom);
+                const dev = await this.resolveDevServer(sessionId, record.worktreePath, port, isFresh);
+                const proc = await this.worktrees.startDevServer(dev.cwd, port, dev.cmd, dev.args, dev.env);
+                record.port = port;
+                record.devServerProcess = proc;
+                // If the dev server dies on its own (crash, OOM, Vite hard-fail),
+                // clear the port so the iframe stops routing the chip onto a dead
+                // socket. Without this the proxy retargets onto an unreachable port
+                // and the chip shows "upstream_unreachable" instead of the accurate
+                // "Preview is unavailable for this variant".
+                proc.once('exit', (code, signal) => {
+                    if (record.devServerProcess !== proc)
+                        return;
+                    record.port = undefined;
+                    record.devServerProcess = undefined;
+                    log.warn(`Variant ${workItemId} dev server exited unexpectedly (code=${code ?? 'null'}, signal=${signal ?? 'null'}); preview disabled`);
+                    this.emitChange();
+                });
                 this.emitChange();
-            });
-            this.emitChange();
-            trackFreshDevServerStarted(this.telemetry, {
-                sessionId,
-                variantId: workItemId,
-                port,
-            });
-            log.info(`Variant ${workItemId} dev server up on port ${port} (worktree ${record.worktreePath}; cmd: ${dev.cmd} ${dev.args.join(' ')})`);
-        }
-        catch (err) {
-            trackFreshDevServerFailed(this.telemetry, {
-                sessionId,
-                variantId: workItemId,
-                errorCode: 'DEV_SERVER_START_FAILED',
-            });
-            log.warn(`Failed to start dev server for variant ${workItemId}; live preview disabled for this variant`, err);
+                trackFreshDevServerStarted(this.telemetry, {
+                    sessionId,
+                    variantId: workItemId,
+                    port,
+                });
+                log.info(`Variant ${workItemId} dev server up on port ${port} (worktree ${record.worktreePath}; cmd: ${dev.cmd} ${dev.args.join(' ')})`);
+                return;
+            }
+            catch (err) {
+                const portInUse = (0, devServerError_1.isDevServerStartError)(err) && err.portInUse;
+                const reason = (0, devServerError_1.isDevServerStartError)(err) ? err.reason : 'unknown';
+                const willRetry = portInUse && attempt < maxAttempts;
+                // Next attempt scans past the port we just tried so we don't re-pick a
+                // port that's persistently held (vs. a transient race that freed it).
+                scanFrom = (port ?? scanFrom) + 1;
+                log.warn(`Failed to start dev server for variant ${workItemId} on port ${port ?? 'unallocated'} ` +
+                    `(attempt ${attempt}/${maxAttempts}, reason=${reason}, portInUse=${portInUse})` +
+                    (willRetry
+                        ? '; retrying on a fresh port'
+                        : '; live preview disabled for this variant'), err);
+                if (willRetry)
+                    continue;
+                // Record the failure so getVariants can tell the UI this direction's
+                // preview couldn't start (and why), then push a snapshot so the chip
+                // updates from "loading" to the accurate per-direction message.
+                this.resources.get(sessionId)?.previewFailures.set(workItemId, {
+                    reason,
+                    portInUse,
+                });
+                trackFreshDevServerFailed(this.telemetry, {
+                    sessionId,
+                    variantId: workItemId,
+                    errorCode: 'DEV_SERVER_START_FAILED',
+                    reason,
+                    portInUse,
+                });
+                this.emitChange();
+                return;
+            }
+            finally {
+                // Hand the reservation back whether the dev server bound the port
+                // (now visible to the listener check, so the reservation is redundant),
+                // it failed (port free again), or we're about to retry on the next port.
+                if (port !== undefined)
+                    this.worktrees.releasePort?.(port);
+            }
         }
     }
     async handleStaticPreviewRefinement(args) {
@@ -2216,23 +2386,37 @@ class AgentVariantsOrchestrator {
         // the refined markup can still reference the original sibling assets
         // (images, GLB, fonts). Fall back to the variant's existing asset base so
         // those relative URLs keep resolving instead of 404ing after the swap.
-        const previousAssetBase = resources.staticPreviews.get(input.variantId)?.assetBase;
-        const assetBase = resolvedAssetBase ?? previousAssetBase;
-        // Swap the served preview to the refined HTML. This is the critical step:
-        // once this is in place the success the caller records (and the snapshot it
-        // emits) never serves stale HTML. It runs before store.reportComplete so a
-        // validation failure above converts to a `failed` report rather than a
-        // success pointing at unrefreshed output.
+        const previousRecord = resources.staticPreviews.get(input.variantId);
+        const dir = resolvedAssetBase ?? previousRecord?.assetBase;
+        // Re-materialize index.html in the per-variant dir FIRST. The directory is
+        // the source of truth (`getStaticPreviewHtml` reads it disk-first), so the
+        // write must succeed before we swap any in-memory / stored-output state to
+        // the refined HTML. If it fails we throw — converting to a `failed` report
+        // rather than a success that still serves the pre-refine document on disk.
+        if (dir) {
+            try {
+                fs_1.default.mkdirSync(dir, { recursive: true });
+                fs_1.default.writeFileSync(path_1.default.join(dir, 'index.html'), parsed.html, 'utf8');
+            }
+            catch (err) {
+                throw new errors_1.AgentVariantsError('RUNTIME_VALIDATION_FAILED', `Failed to materialize refined static preview for ${input.variantId}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        // Swap the served preview to the refined HTML. Runs before
+        // store.reportComplete so any failure above converts to a `failed` report
+        // rather than a success pointing at unrefreshed output.
         this.store.replaceWorkItemOutput(args.sessionId, input.variantId, {
             ...parsed,
-            ...(assetBase ? { assetBase } : {}),
-        });
-        resources.staticPreviews.set(input.variantId, {
-            workItemId: input.variantId,
-            briefId: targetInput.briefId,
-            html: parsed.html,
-            ...(assetBase ? { assetBase } : {}),
+            ...(dir ? { assetBase: dir } : {}),
         });
+        if (dir) {
+            resources.staticPreviews.set(input.variantId, {
+                workItemId: input.variantId,
+                briefId: targetInput.briefId,
+                assetBase: dir,
+                hasAssets: Boolean(resolvedAssetBase) || Boolean(previousRecord?.hasAssets),
+            });
+        }
         // History persistence is best-effort, mirroring handleSucceededReport's
         // fire-and-forget persistence for freshly completed variants. A failure
         // here (e.g. a transient filesystem race) must not fail the refinement or
@@ -2300,6 +2484,81 @@ class AgentVariantsOrchestrator {
             projectKind: 'existing',
         });
     }
+    /**
+     * Existing-mode `framework: 'static'` projects have no dev command, so there
+     * is no per-variant dev server for the iframe to proxy. Register the variant's
+     * materialized static site as a {@link StaticPreviewRecord} so the existing
+     * static-file plumbing — the `/api/variants/:sid/static/:vid[/asset]` routes,
+     * {@link getStaticPreviewHtml}, and {@link getVariants} (preview.kind=
+     * 'static_artifact', view enabled) — all light up exactly as they do for
+     * fresh `static_preview` variants. The entry HTML and its sibling assets are
+     * served straight from the variant's worktree project root (session-scoped,
+     * pre-commit; the persisted `.rivet/variants/.../files/` copy backs the
+     * post-session history route separately).
+     *
+     * Returns `true` when a static preview was registered (caller skips
+     * dev-server startup); `false` for non-static projects (fall back to the
+     * dev-server proxy) or when no renderable entry file is present.
+     */
+    async registerExistingStaticPreview(sessionId, workItemId, record) {
+        let env;
+        try {
+            env = await this.resolveEnv(sessionId);
+        }
+        catch (err) {
+            log.warn(`registerExistingStaticPreview: resolveEnv failed for ${sessionId}`, err);
+            return false;
+        }
+        if (env.framework !== 'static')
+            return false;
+        const resources = this.resources.get(sessionId);
+        if (!resources)
+            return false;
+        const input = this.store.getWorkItemInput(sessionId, workItemId);
+        if (!input.briefId)
+            return false;
+        let projectCwd;
+        try {
+            projectCwd = await this.worktrees.getProjectCwdInWorktree(record.worktreePath);
+        }
+        catch (err) {
+            log.warn(`registerExistingStaticPreview: project cwd failed for ${sessionId}/${workItemId}`, err);
+            return false;
+        }
+        // The materialized worktree IS the per-variant directory. Require its
+        // entry index.html to exist; the directory is then served directly (no
+        // in-memory HTML copy — getStaticPreviewHtml reads index.html from here).
+        const entryFile = path_1.default.join(projectCwd, 'index.html');
+        try {
+            await fs_1.default.promises.access(entryFile, fs_1.default.constants.R_OK);
+        }
+        catch (err) {
+            log.warn(`registerExistingStaticPreview: no entry HTML at ${entryFile} for ${sessionId}/${workItemId}; preview unavailable`, err);
+            return false;
+        }
+        // The dir must be realpath'd so resolveStaticPreviewAssetPath's sandbox
+        // comparison lines up; sibling assets (css/js/images) then resolve from the
+        // same static root the entry HTML lives in.
+        let dir;
+        try {
+            dir = fs_1.default.realpathSync(projectCwd);
+        }
+        catch {
+            // Fall back to the un-realpath'd cwd; serving still works, only the
+            // sandbox symlink-normalization is skipped.
+            dir = projectCwd;
+        }
+        resources.staticPreviews.set(workItemId, {
+            workItemId,
+            briefId: input.briefId,
+            assetBase: dir,
+            // Existing-mode static projects are real multi-file sites — assume
+            // sibling assets so the preview route resolves relative URLs.
+            hasAssets: true,
+        });
+        log.info(`Variant ${workItemId} served as a static preview (existing/static, no dev server; root ${projectCwd})`);
+        return true;
+    }
     /**
      * Persist a completed fresh-project variant into
      * `<projectContext.workspacePath>/.rivet/variants/<sessionId>/<variantId>/`.
@@ -2340,7 +2599,15 @@ class AgentVariantsOrchestrator {
         }
         else if (staticPreview) {
             tmpStagingDir = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), `rivet-variant-${args.workItemId}-`));
-            fs_1.default.writeFileSync(path_1.default.join(tmpStagingDir, 'index.html'), staticPreview.html, 'utf8');
+            // Read the materialized index.html from the variant's per-variant dir.
+            let stagedHtml = '';
+            try {
+                stagedHtml = fs_1.default.readFileSync(path_1.default.join(staticPreview.assetBase, 'index.html'), 'utf8');
+            }
+            catch (err) {
+                log.warn(`persistCompletedFreshVariant: could not read index.html for ${args.workItemId}`, err);
+            }
+            fs_1.default.writeFileSync(path_1.default.join(tmpStagingDir, 'index.html'), stagedHtml, 'utf8');
             fs_1.default.writeFileSync(path_1.default.join(tmpStagingDir, 'brief.md'), `# ${input.briefLabel}\n\n${input.briefBody}\n`, 'utf8');
             sourceDir = tmpStagingDir;
         }
@@ -2521,6 +2788,24 @@ class AgentVariantsOrchestrator {
             return undefined;
         }
     }
+    /**
+     * The port to start scanning from when allocating a variant's preview dev
+     * server. Fresh worktrees run the Vite template (5173); existing projects use
+     * their detected framework's default (3000 for Next, etc.), falling back to
+     * 3000 if detection fails. Scanning upward from here lands the preview on a
+     * sensible, predictable port near the project's normal one.
+     */
+    async resolveDevServerStartPort(sessionId, isFresh) {
+        if (isFresh)
+            return FRESH_DEV_SERVER_DEFAULT_PORT;
+        try {
+            const env = await this.resolveEnv(sessionId);
+            return env.defaultPort ?? 3000;
+        }
+        catch {
+            return 3000;
+        }
+    }
     /**
      * Resolve dev server invocation for a worktree. Fresh-project worktrees
      * always use the Vite template's npm command at the worktree root; existing
@@ -2942,6 +3227,31 @@ class AgentVariantsOrchestrator {
                 log.warn(`cleanupSession (worktree removal) failed for ${sessionId}`, err);
             }
         }
+        // Remove fresh static_preview staging dirs (the per-variant directories
+        // materialized under workspacePath at report time). On 'committed' the
+        // commit flatten already moved/removed them; on cancel/shutdown they'd
+        // otherwise orphan under `.rivet/<slug>/`. Existing-mode static previews
+        // point at worktree dirs (cleaned by cleanupSession above), so scope this
+        // to fresh sessions — where every staticPreviews dir is Rivet staging.
+        if (reason !== 'committed') {
+            let isFresh = false;
+            try {
+                isFresh = this.store.getProjectContext(sessionId).kind === 'fresh';
+            }
+            catch {
+                isFresh = false;
+            }
+            if (isFresh) {
+                for (const sp of resources.staticPreviews.values()) {
+                    try {
+                        fs_1.default.rmSync(sp.assetBase, { recursive: true, force: true });
+                    }
+                    catch (err) {
+                        log.warn(`failed to remove static preview dir ${sp.assetBase} for ${sessionId}`, err);
+                    }
+                }
+            }
+        }
         this.resources.delete(sessionId);
     }
     ensureResources(sessionId) {
@@ -2956,6 +3266,7 @@ class AgentVariantsOrchestrator {
                 startedAt: Date.now(),
                 leasedAt: new Map(),
                 qaResults: new Map(),
+                previewFailures: new Map(),
                 vitePreservedSiblings: false,
             };
             this.resources.set(sessionId, r);
@@ -3711,6 +4022,8 @@ const trackFreshDevServerFailed = (telemetry, data) => {
         session_id: data.sessionId,
         variant_id: data.variantId,
         error_code: data.errorCode,
+        failure_reason: data.reason,
+        port_in_use: data.portInUse,
     });
 };
 const trackStaticPreviewCompleted = (telemetry, data) => {