rivet-design 0.9.2 → 0.9.4

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

@@ -1,11 +1,191 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AgentVariantsOrchestrator = void 0;
+const crypto_1 = require("crypto");
 const events_1 = require("events");
+const fs_1 = __importDefault(require("fs"));
+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 errors_1 = require("./errors");
+const createProjectArtifacts_1 = require("./createProjectArtifacts");
 const contracts_1 = require("./contracts");
+const viteReactTs_1 = require("../../services/templates/viteReactTs");
+const designCatalog_1 = require("../../services/templates/designCatalog");
+const previewQa_1 = require("./previewQa");
 const log = (0, logger_1.createLogger)('AgentVariantsOrchestrator');
+const FRESH_DEV_SERVER_HOST = '127.0.0.1';
+/**
+ * Allowlist of asset file extensions an agent-planned source may have.
+ * `assetPlan` is sized for large local *assets* (3D models, images,
+ * audio, video, fonts) — never code, dotfiles, secrets, or arbitrary
+ * configs. The check is defense-in-depth alongside the path / symlink
+ * filters in `copyAssetIntoWorktree`; without it, a prompt-injected
+ * source plan could copy readable host files such as SSH keys or
+ * project secrets into the generated app.
+ *
+ * Intentionally excludes `.json`, `.txt`, `.md`, `.csv`: these are
+ * common carriers for credentials (`credentials.json`, `.aws/config`,
+ * shell history `.txt`, README-shaped secrets) and have no legitimate
+ * use as binary preview assets. If a future flow needs structured data
+ * it should ship it through the manifest instead of file copy.
+ */
+const ALLOWED_ASSET_EXTENSIONS = new Set([
+    // 3D / models
+    '.glb', '.gltf', '.obj', '.fbx', '.usdz',
+    // images
+    '.png', '.jpg', '.jpeg', '.gif', '.webp', '.svg', '.avif', '.bmp', '.ico',
+    // video
+    '.mp4', '.webm', '.mov',
+    // audio
+    '.mp3', '.wav', '.ogg', '.m4a',
+    // fonts
+    '.woff', '.woff2', '.ttf', '.otf', '.eot',
+    // PDFs
+    '.pdf',
+]);
+/**
+ * Reject paths that traverse through a "sensitive" directory anywhere
+ * in their ancestry — `.ssh`, `.aws`, `.config`, `.gnupg`, etc. Even if
+ * a copy passes the extension allowlist, an agent-controlled source
+ * resolving inside `~/.ssh/` is almost certainly an exfiltration
+ * attempt rather than a legitimate asset reference.
+ */
+const SENSITIVE_PATH_SEGMENTS = new Set([
+    '.ssh',
+    '.aws',
+    '.gnupg',
+    '.kube',
+    '.docker',
+    '.config',
+    '.npm',
+    '.cargo',
+    '.gem',
+    '.netrc',
+    'private',
+    'secrets',
+    'credentials',
+]);
+function hasSensitivePathSegment(absolutePath) {
+    // Split on any path separator; check each segment case-insensitively.
+    const segments = absolutePath.split(/[/\\]/).filter(Boolean);
+    return segments.some((segment) => SENSITIVE_PATH_SEGMENTS.has(segment.toLowerCase()));
+}
+/**
+ * Returns true when `absolutePath` is the root itself or one of its
+ * descendants after both paths have been resolved.
+ */
+function isPathWithinRoot(absolutePath, root) {
+    const relative = path_1.default.relative(root, absolutePath);
+    return (relative === '' ||
+        (relative.length > 0 &&
+            !relative.startsWith('..') &&
+            !path_1.default.isAbsolute(relative)));
+}
+/**
+ * Copy one agent-planned asset file into a variant worktree at the
+ * project-relative `destination`. The agent decides routing
+ * (`destination` like `public/assets/avatar.glb`) so all variants share
+ * a consistent layout. Fails loudly when the source is missing or the
+ * destination tries to escape the worktree — silent fallbacks here
+ * would re-introduce the broken-asset failure mode this routing is
+ * supposed to prevent.
+ *
+ * Security: `entry.source` comes from `report_source_plan` and is
+ * agent-controlled. To prevent a prompt-injected source plan from
+ * exfiltrating arbitrary readable host files (SSH keys, dotfiles,
+ * cloud credentials, project secrets) into the generated app, the
+ * source must (1) be an absolute path that resolves via realpath
+ * (no traversal, no symlinks pointing outside the resolved location),
+ * (2) be a regular file (not a device, socket, fifo, or directory),
+ * (3) live under the approved asset root, (4) have an extension on the
+ * asset allowlist.
+ */
+function copyAssetIntoWorktree(worktreePath, entry, assetSourceRoot) {
+    if (!assetSourceRoot) {
+        throw new errors_1.AgentVariantsError('RUNTIME_VALIDATION_FAILED', `assetPlan.source requires an approved asset root before copying '${entry.source}'`);
+    }
+    if (!path_1.default.isAbsolute(assetSourceRoot)) {
+        throw new errors_1.AgentVariantsError('RUNTIME_VALIDATION_FAILED', `assetSourceRoot must be an absolute path, got '${assetSourceRoot}'`);
+    }
+    if (!path_1.default.isAbsolute(entry.source)) {
+        throw new errors_1.AgentVariantsError('RUNTIME_VALIDATION_FAILED', `assetPlan.source must be an absolute path, got '${entry.source}'`);
+    }
+    const ext = path_1.default.extname(entry.source).toLowerCase();
+    if (!ALLOWED_ASSET_EXTENSIONS.has(ext)) {
+        throw new errors_1.AgentVariantsError('RUNTIME_VALIDATION_FAILED', `assetPlan.source extension '${ext || '(none)'}' is not on the allowlist (got '${entry.source}'). Only inert media/font/document assets may be copied.`);
+    }
+    // lstat first: a symlink whose target lies outside the source path
+    // could otherwise smuggle in arbitrary files. Reject symlinks outright;
+    // realpath would resolve them but the user-visible intent of an
+    // assetPlan entry is to name a concrete file.
+    let lstat;
+    try {
+        lstat = fs_1.default.lstatSync(entry.source);
+    }
+    catch {
+        throw new errors_1.AgentVariantsError('RUNTIME_VALIDATION_FAILED', `assetPlan.source not found on disk: ${entry.source}`);
+    }
+    if (lstat.isSymbolicLink()) {
+        throw new errors_1.AgentVariantsError('RUNTIME_VALIDATION_FAILED', `assetPlan.source must not be a symlink: ${entry.source}`);
+    }
+    if (!lstat.isFile()) {
+        throw new errors_1.AgentVariantsError('RUNTIME_VALIDATION_FAILED', `assetPlan.source must be a regular file: ${entry.source}`);
+    }
+    // Resolve realpath as additional defense: even with no symlinks at the
+    // leaf, an intermediate directory could be a symlink. Cross-check the
+    // file kind on the resolved path.
+    let resolvedSource;
+    try {
+        resolvedSource = fs_1.default.realpathSync(entry.source);
+    }
+    catch {
+        throw new errors_1.AgentVariantsError('RUNTIME_VALIDATION_FAILED', `assetPlan.source could not be resolved: ${entry.source}`);
+    }
+    let resolvedAssetSourceRoot;
+    try {
+        resolvedAssetSourceRoot = fs_1.default.realpathSync(assetSourceRoot);
+    }
+    catch {
+        throw new errors_1.AgentVariantsError('RUNTIME_VALIDATION_FAILED', `assetSourceRoot could not be resolved: ${assetSourceRoot}`);
+    }
+    const resolvedStat = fs_1.default.statSync(resolvedSource);
+    if (!resolvedStat.isFile()) {
+        throw new errors_1.AgentVariantsError('RUNTIME_VALIDATION_FAILED', `assetPlan.source resolved target must be a regular file: ${entry.source}`);
+    }
+    // Symlinked parent directory defense: even though we rejected a symlink
+    // leaf and confirmed the resolved file is regular, an intermediate dir
+    // could have been a symlink that quietly forwards into a sensitive
+    // ancestor (e.g. `<asset-root>/avatar -> ~/.ssh`). Cross-check that
+    // NEITHER the user-supplied path NOR its realpath traverses a known
+    // sensitive segment such as `.ssh`, `.aws`, `credentials`, etc. Also
+    // re-verify the extension on the resolved path so a `.glb` symlink
+    // chain cannot smuggle in a `.json` realpath.
+    if (hasSensitivePathSegment(entry.source) ||
+        hasSensitivePathSegment(resolvedSource)) {
+        throw new errors_1.AgentVariantsError('RUNTIME_VALIDATION_FAILED', `assetPlan.source traverses a sensitive directory and is refused: ${entry.source}`);
+    }
+    if (!isPathWithinRoot(resolvedSource, resolvedAssetSourceRoot)) {
+        throw new errors_1.AgentVariantsError('RUNTIME_VALIDATION_FAILED', `assetPlan.source must stay inside the approved asset root: ${entry.source}`);
+    }
+    const resolvedExt = path_1.default.extname(resolvedSource).toLowerCase();
+    if (!ALLOWED_ASSET_EXTENSIONS.has(resolvedExt)) {
+        throw new errors_1.AgentVariantsError('RUNTIME_VALIDATION_FAILED', `assetPlan.source resolved extension '${resolvedExt || '(none)'}' is not on the allowlist (resolved from '${entry.source}').`);
+    }
+    const normalizedDest = path_1.default.normalize(entry.destination);
+    if (normalizedDest.startsWith('..') ||
+        path_1.default.isAbsolute(normalizedDest)) {
+        throw new errors_1.AgentVariantsError('RUNTIME_VALIDATION_FAILED', `assetPlan.destination must stay inside the worktree, got '${entry.destination}'`);
+    }
+    const absDest = path_1.default.join(worktreePath, normalizedDest);
+    fs_1.default.mkdirSync(path_1.default.dirname(absDest), { recursive: true });
+    fs_1.default.copyFileSync(resolvedSource, absDest);
+}
+const defaultPreviewQaRunner = ({ html }) => (0, previewQa_1.runPreviewQa)({ html });
 const NOOP_TELEMETRY = { track: () => undefined };
 /**
  * Wraps SessionStore for the operations that have side effects: approve
@@ -25,7 +205,31 @@ class AgentVariantsOrchestrator {
     adapter;
     resolveEnv;
     telemetry;
+    installDependencies;
+    materializeProject;
+    previewQaRunner;
+    switchPreviewPort;
     resources = new Map();
+    /**
+     * Committed dev servers from prior sessions that survived teardown. The
+     * orchestrator outlives any single session — once a new session starts, the
+     * prior committed dev server is no longer needed (the next session opens
+     * its own preview chip), so stop it before the new session's first preview
+     * goes live. Keyed by sessionId for diagnostics; values are kept alive
+     * intentionally between commit and next `propose` / `shutdown`.
+     */
+    lingeringCommittedDevServers = new Map();
+    /**
+     * Per-session in-flight commit chain. Two overlapping commitVariant calls
+     * would otherwise both pass the `getVariantPick` idempotency check (the
+     * pick isn't recorded until after `applyDiffToProject`) and double-invoke
+     * `git apply` — which corrupts the working tree on the second run. The
+     * chain serializes commits per session so the second caller waits for the
+     * first to finish and then hits the idempotency check (returning
+     * `duplicate: true` for the same variantId, or `PENDING_CHANGE_CONFLICT`
+     * for a different one).
+     */
+    inflightCommits = new Map();
     /** Most recent agent-variants sessionId — read by the iframe chip via
      *  GET /api/variants/active. Cleared on cancel or commit. */
     activeSessionId = null;
@@ -38,9 +242,21 @@ class AgentVariantsOrchestrator {
         this.adapter = deps.pendingChangesAdapter;
         this.resolveEnv = deps.resolveProjectEnvironment;
         this.telemetry = deps.telemetry ?? NOOP_TELEMETRY;
+        this.installDependencies =
+            deps.installDependencies ?? defaultInstallDependencies;
+        this.materializeProject =
+            deps.materializeProject ?? defaultMaterializeProject;
+        this.previewQaRunner = deps.previewQaRunner ?? defaultPreviewQaRunner;
+        this.switchPreviewPort = deps.switchPreviewPort;
     }
     // --- Pure delegations (no side effects) ---------------------------------
     propose(args) {
+        // A new session means any lingering committed dev server from a prior
+        // session is no longer needed — the next session opens its own preview.
+        // Best-effort stop; failures here don't block propose.
+        void this.stopLingeringCommittedDevServers().catch((err) => {
+            log.warn('Stopping lingering committed dev servers failed', err);
+        });
         const result = this.store.propose(args);
         this.activeSessionId = result.sessionId;
         this.ensureResources(result.sessionId);
@@ -82,13 +298,11 @@ class AgentVariantsOrchestrator {
             stage === 'cancelled'
             ? this.store.getSummary(sessionId)
             : null;
-        const variants = (summary?.variants ?? []).map((v) => ({
-            workItemId: v.workItemId,
-            status: v.status,
-            label: v.label,
-            previewPort: this.getDevServerPort(sessionId, v.workItemId),
-            worktreePath: this.getWorktreePath(sessionId, v.workItemId),
-        }));
+        const variants = this.getVariants(sessionId);
+        const sessionProjectContext = this.store.getProjectContext(sessionId);
+        const projectContext = toActiveProjectContext(sessionProjectContext);
+        const destinationPath = projectContext.kind === 'fresh' ? projectContext.workspacePath : undefined;
+        const artifacts = buildSessionArtifacts(sessionProjectContext);
         return {
             active: true,
             sessionId,
@@ -97,6 +311,9 @@ class AgentVariantsOrchestrator {
             progress,
             summary,
             variants,
+            projectContext,
+            ...(destinationPath ? { destinationPath } : {}),
+            ...(artifacts.length > 0 ? { artifacts } : {}),
         };
     }
     emitChange() {
@@ -109,6 +326,26 @@ class AgentVariantsOrchestrator {
     }
     reportBriefs(args) {
         const result = this.store.reportBriefs(args);
+        const evidenceBackedCount = result.briefs.filter((brief) => /\b(source|evidence|preserve|borrow)\b/i.test(brief.body)).length;
+        const shortBriefCount = result.briefs.filter((brief) => brief.body.length <= 200).length;
+        this.telemetry.trackAgentVariantsBriefQuality?.({
+            sessionId: args.sessionId,
+            briefCount: result.briefs.length,
+            evidenceBackedCount,
+            shortBriefCount,
+        });
+        this.emitChange();
+        return result;
+    }
+    reportSourcePlan(args) {
+        const result = this.store.reportSourcePlan(args);
+        this.telemetry.trackAgentVariantsSourceContextQuality?.({
+            sessionId: args.sessionId,
+            sourceUrlCount: args.sourcePlan.sourceIntent.sources.length,
+            artifactCount: args.sourcePlan.sourceContext.sourceFindings.length,
+            hasScreenshotReferences: (args.sourcePlan.sourceContext.screenshotReferences?.length ?? 0) > 0,
+            preserveBrand: args.sourcePlan.sourceContext.sourceRoles.some((entry) => entry.role === 'primary'),
+        });
         this.emitChange();
         return result;
     }
@@ -156,9 +393,83 @@ class AgentVariantsOrchestrator {
     getSummary(sessionId) {
         return this.store.getSummary(sessionId);
     }
+    getVariants(sessionId) {
+        const resources = this.resources.get(sessionId);
+        return this.store.getVariants(sessionId).map((variant) => {
+            const port = this.getDevServerPort(sessionId, variant.workItemId);
+            // For fresh sessions, static_preview items ARE the variants — look up
+            // directly by workItemId. Fall back to briefId search for existing-project
+            // sessions where code_gen items were paired with companion static_preview items.
+            const staticPreview = resources?.staticPreviews.get(variant.workItemId) ??
+                this.getStaticPreviewByBriefId(sessionId, variant.briefId);
+            let preview;
+            if (staticPreview) {
+                preview = {
+                    kind: 'static_artifact',
+                    url: this.buildStaticPreviewUrl(sessionId, staticPreview.workItemId),
+                };
+            }
+            else if (!port) {
+                // handleSucceededReport is fire-and-forget so staticPreviews may not be
+                // populated yet when getVariants is called (e.g. in the terminal response).
+                // item.output is set synchronously by store.reportComplete, so it's always
+                // available. Read it directly as a fallback so previewUrls in terminal
+                // responses include the variant that just triggered terminal state.
+                try {
+                    const output = this.store.getWorkItemOutput(sessionId, variant.workItemId);
+                    if (typeof output?.html === 'string' && output.html.length > 0) {
+                        preview = {
+                            kind: 'static_artifact',
+                            url: this.buildStaticPreviewUrl(sessionId, variant.workItemId),
+                        };
+                    }
+                }
+                catch { /* work item may not exist in edge cases */ }
+            }
+            if (!preview && port) {
+                preview = { kind: 'dev_server', port };
+            }
+            const qa = resources?.qaResults.get(variant.workItemId);
+            const isSucceeded = variant.status === 'succeeded';
+            const qaFailed = qa?.status === 'failed';
+            const canView = Boolean(preview) || (isSucceeded && Boolean(port));
+            const canCommit = isSucceeded && !qaFailed;
+            const commitDisabledReason = qaFailed
+                ? qa?.summary ?? 'Variant failed QA'
+                : 'Wait for a successful variant';
+            return {
+                ...variant,
+                design: enrichDesignSource(variant.design),
+                ...(preview ? { preview } : {}),
+                port,
+                ...(qa ? { qa } : {}),
+                actions: {
+                    view: canView
+                        ? { enabled: true }
+                        : {
+                            enabled: false,
+                            reason: isSucceeded
+                                ? 'Preview is unavailable for this variant'
+                                : 'Variant is still running',
+                        },
+                    commit: canCommit
+                        ? { enabled: true }
+                        : {
+                            enabled: false,
+                            reason: commitDisabledReason,
+                        },
+                },
+            };
+        });
+    }
     hasSession(sessionId) {
         return this.store.hasSession(sessionId);
     }
+    /** Read the projectContext for a session — used by Express routes that
+     *  build the chip snapshot via `stateForSession`. */
+    getProjectContext(sessionId) {
+        return this.store.getProjectContext(sessionId);
+    }
     /** Resolve a worktree path for a code-gen work item, if provisioned. */
     getWorktreePath(sessionId, workItemId) {
         return this.resources.get(sessionId)?.worktrees.get(workItemId)
@@ -168,16 +479,45 @@ class AgentVariantsOrchestrator {
     getDevServerPort(sessionId, workItemId) {
         return this.resources.get(sessionId)?.worktrees.get(workItemId)?.port;
     }
+    getStaticPreviewHtml(sessionId, workItemId) {
+        // Primary: from the staticPreviews Map populated by handleSucceededReport.
+        const fromMap = this.resources.get(sessionId)?.staticPreviews.get(workItemId)?.html;
+        if (fromMap)
+            return fromMap;
+        // Fallback: read directly from the work item's stored output — available
+        // as soon as reportComplete runs, before handleSucceededReport fires.
+        try {
+            const output = this.store.getWorkItemOutput(sessionId, workItemId);
+            return typeof output?.html === 'string' && output.html.length > 0
+                ? buildStaticPreviewDocument({ html: output.html })
+                : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    getStaticPreviewByBriefId(sessionId, briefId) {
+        const resources = this.resources.get(sessionId);
+        if (!resources)
+            return undefined;
+        return [...resources.staticPreviews.values()].find((preview) => preview.briefId === briefId);
+    }
+    buildStaticPreviewUrl(sessionId, workItemId) {
+        const safeSessionId = encodeURIComponent(sessionId);
+        const safeWorkItemId = encodeURIComponent(workItemId);
+        return `/api/variants/${safeSessionId}/static/${safeWorkItemId}`;
+    }
     // --- Mutation wrappers (state + side effects) ---------------------------
     async approve(args) {
         const result = this.store.approve(args);
-        this.ensureResources(args.sessionId);
+        const resources = this.ensureResources(args.sessionId);
+        resources.approveStartedAt = Date.now();
         this.telemetry.track('agent_variants.approved', {
             source: 'mcp',
             sessionId: args.sessionId,
             approvedCount: result.approvedCount,
             totalBriefs: result.totalCount,
-            isFresh: Boolean(result.scaffoldBaseWorkItemId),
+            isFresh: this.store.getProjectContext(args.sessionId).kind === 'fresh',
         });
         this.emitChange();
         // Await provisioning before returning so request_work always sees a
@@ -195,28 +535,153 @@ class AgentVariantsOrchestrator {
         }
         return result;
     }
+    /**
+     * Unified one-call kickoff that collapses propose → report_briefs →
+     * approve. Synthesizes placeholder briefs server-side (the agent's
+     * streamed first-line label replaces them in the UI) and immediately
+     * approves so the session lands in `work_items_ready`.
+     *
+     * 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.
+     *
+     * Host-agnostic: no LLM calls happen here. The agent (Claude Code,
+     * Cursor, Codex) generates the label and code when it leases the
+     * work items via continue_variants(action="request_work").
+     */
+    async startUnified(args) {
+        const count = args.briefs?.length ?? args.count ?? 4;
+        const projectContext = args.projectContext ?? { kind: 'existing' };
+        const sourceContext = projectContext.kind === 'fresh' ? projectContext.sourceContext : undefined;
+        const isSourceGrounded = Boolean(sourceContext?.sourceUrls?.length) ||
+            Boolean(sourceContext?.sourceArtifacts?.length) ||
+            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.');
+        }
+        const proposeResult = this.propose({
+            prompt: args.prompt,
+            count,
+            target: args.target,
+            projectContext,
+        });
+        if (proposeResult.stage !== 'awaiting_briefs' ||
+            !proposeResult.briefWorkItem) {
+            throw new errors_1.AgentVariantsError('INVALID_STAGE_ACTION', `start_variants expected awaiting_briefs from propose, got ${proposeResult.stage}`);
+        }
+        const briefs = args.briefs
+            ? args.briefs.map((b, i) => ({
+                briefId: `v${i + 1}`,
+                label: b.label,
+                body: b.body,
+                ...(b.visualReferenceUrl
+                    ? { visualReferenceUrl: b.visualReferenceUrl }
+                    : {}),
+            }))
+            : Array.from({ length: count }, (_, i) => ({
+                briefId: `v${i + 1}`,
+                label: `Variant ${i + 1}`,
+                body: synthesizeUnifiedBriefBody(args.prompt, i + 1, count),
+            }));
+        this.store.reportBriefs({
+            sessionId: proposeResult.sessionId,
+            workItemId: proposeResult.briefWorkItem.id,
+            attempt: proposeResult.briefWorkItem.attempt,
+            briefs,
+        });
+        const approveResult = await this.approve({
+            sessionId: proposeResult.sessionId,
+            selections: briefs.map((b) => ({ briefId: b.briefId })),
+        });
+        this.telemetry.track('agent_variants.unified_started', {
+            source: 'mcp',
+            sessionId: proposeResult.sessionId,
+            count,
+            hasTarget: Boolean(args.target),
+            targetType: args.target?.type ?? null,
+            projectContextKind: projectContext.kind,
+        });
+        // For existing-project sessions, approve() returns the new code_gen
+        // ids in codeGenWorkItemIds. For zero-to-one, approve() spawns
+        // static_preview items instead — those ids aren't in codeGenWorkItemIds,
+        // so read them out of the active-variants snapshot which covers both
+        // kinds. Snapshot order mirrors brief order (insertion order).
+        const variantIds = projectContext.kind === 'fresh'
+            ? this.store
+                .getVariants(proposeResult.sessionId)
+                .map((v) => v.workItemId)
+            : approveResult.codeGenWorkItemIds;
+        const variants = variantIds.map((workItemId, i) => ({
+            variantId: workItemId,
+            briefId: briefs[i].briefId,
+            label: briefs[i].label,
+            status: 'pending',
+        }));
+        let leaseId;
+        let leaseTtlMs;
+        let leasedWorkItems;
+        if (args.leaseOwner) {
+            const lease = this.requestWork({
+                sessionId: proposeResult.sessionId,
+                leaseOwner: args.leaseOwner,
+            });
+            leaseId = lease.leaseId;
+            leaseTtlMs = lease.leaseTtlMs;
+            leasedWorkItems = lease.leasedWorkItems;
+        }
+        return {
+            sessionId: proposeResult.sessionId,
+            variants,
+            scaffoldBaseWorkItemId: approveResult.scaffoldBaseWorkItemId ?? null,
+            leaseId,
+            leaseTtlMs,
+            leasedWorkItems,
+        };
+    }
     async reportComplete(args) {
-        const result = this.store.reportComplete(args);
+        // QA gate: for `succeeded` static_preview reports, run preview QA
+        // synchronously before recording success in the store. A failed QA
+        // verdict converts the report to `failed` with code `VARIANT_QA_FAILED`
+        // so the variant never reaches `ready` and `getVariants` can disable
+        // its commit action.
+        const qaOverride = await this.evaluateQaForReport(args);
+        const effectiveArgs = qaOverride?.overrideArgs ?? args;
+        const result = this.store.reportComplete(effectiveArgs);
         this.emitChange();
         // Per-variant telemetry on terminal item statuses (skip 'running'
         // heartbeats and the brief work item — only code_gen / scaffold_base
         // matter for the funnel).
-        if (args.status === 'succeeded' ||
-            args.status === 'failed' ||
-            args.status === 'cancelled') {
+        if (effectiveArgs.status === 'succeeded' ||
+            effectiveArgs.status === 'failed' ||
+            effectiveArgs.status === 'cancelled') {
             const resources = this.resources.get(args.sessionId);
             const leasedAt = resources?.leasedAt.get(args.workItemId);
             const durationMs = leasedAt !== undefined ? Date.now() - leasedAt : null;
+            const approveStartedAt = resources?.approveStartedAt;
+            const approveToCompleteMs = approveStartedAt !== undefined ? Date.now() - approveStartedAt : null;
+            // Byte size of generated output for HTML vs full-stack comparison.
+            const outputBytes = estimateOutputBytes(args.output);
+            const projectContextKind = this.store.getProjectContext(args.sessionId).kind;
             this.telemetry.track('agent_variants.variant_completed', {
                 source: 'mcp',
                 sessionId: args.sessionId,
                 workItemId: args.workItemId,
-                status: args.status,
+                status: effectiveArgs.status,
                 attempt: args.attempt,
                 durationMs,
-                hasError: Boolean(args.error),
-                errorCode: args.error?.code ?? null,
+                approveToCompleteMs,
+                hasError: Boolean(effectiveArgs.error),
+                errorCode: effectiveArgs.error?.code ?? null,
                 isScaffold: resources?.scaffoldBaseWorkItemId === args.workItemId,
+                projectContextKind,
+                tokensIn: args.tokensIn ?? null,
+                tokensOut: args.tokensOut ?? null,
+                model: args.model ?? null,
+                outputBytes,
             });
         }
         if (contracts_1.TERMINAL_STAGES.has(result.stage)) {
@@ -224,6 +689,9 @@ class AgentVariantsOrchestrator {
             if (resources && resources.terminalAt === undefined) {
                 resources.terminalAt = Date.now();
                 const totalLatencyMs = resources.terminalAt - resources.startedAt;
+                const approveToTerminalMs = resources.approveStartedAt !== undefined
+                    ? resources.terminalAt - resources.approveStartedAt
+                    : null;
                 const summary = result.summary ?? this.store.getSummary(args.sessionId);
                 this.telemetry.track('agent_variants.terminal_state', {
                     source: 'mcp',
@@ -233,11 +701,17 @@ class AgentVariantsOrchestrator {
                     failureCount: summary.failureCount,
                     cancelledCount: summary.cancelledCount,
                     totalLatencyMs,
+                    approveToTerminalMs,
+                    projectContextKind: this.store.getProjectContext(args.sessionId).kind,
                 });
             }
         }
-        if (args.status === 'succeeded') {
-            void this.handleSucceededReport(args.sessionId, args.workItemId).catch((err) => {
+        if (effectiveArgs.status === 'succeeded') {
+            void this.handleSucceededReport({
+                sessionId: args.sessionId,
+                workItemId: args.workItemId,
+                output: args.output,
+            }).catch((err) => {
                 log.error(`handleSucceededReport failed for ${args.sessionId}/${args.workItemId}`, err);
             });
         }
@@ -267,6 +741,37 @@ class AgentVariantsOrchestrator {
         });
         return result;
     }
+    /**
+     * Cancel a single variant within a session. Siblings continue. Idempotent
+     * on terminal states. Per-variant worktree teardown is deferred to a
+     * follow-up; the lease is released, so requestWork won't re-surface this
+     * variant and the agent's report_variant_complete for it (if it lands
+     * after cancellation) is rejected by the stale-lease check.
+     */
+    async cancelVariant(args) {
+        const result = this.store.cancelWorkItem({
+            sessionId: args.sessionId,
+            workItemId: args.variantId,
+            reason: args.reason,
+        });
+        this.telemetry.track('agent_variants.variant_cancelled', {
+            source: 'mcp',
+            sessionId: args.sessionId,
+            variantId: args.variantId,
+            finalStatus: result.finalStatus,
+            sessionStage: result.sessionStage,
+            alreadyTerminal: result.alreadyTerminal,
+            reason: args.reason ?? null,
+        });
+        this.emitChange();
+        return {
+            sessionId: args.sessionId,
+            variantId: args.variantId,
+            finalStatus: result.finalStatus,
+            sessionStage: result.sessionStage,
+            alreadyTerminal: result.alreadyTerminal,
+        };
+    }
     /**
      * User has reviewed the rendered variants in chat and picked one. Look up
      * the captured diff, build a VariantPickEnvelope, and enqueue to the
@@ -274,6 +779,29 @@ class AgentVariantsOrchestrator {
      * the call returns duplicate=true without re-enqueueing.
      */
     async commitVariant(args) {
+        // Serialize per-session so two overlapping commits can't both run
+        // `applyDiffToProject` (or the fresh rename) before the first records
+        // its pick. The second caller waits for the first to settle, then runs
+        // commitVariantImpl which hits the idempotency check in
+        // `getVariantPick` / `recordVariantPick`.
+        const prior = this.inflightCommits.get(args.sessionId);
+        const run = (async () => {
+            if (prior) {
+                await prior.catch(() => undefined);
+            }
+            return this.commitVariantImpl(args);
+        })();
+        this.inflightCommits.set(args.sessionId, run);
+        try {
+            return await run;
+        }
+        finally {
+            if (this.inflightCommits.get(args.sessionId) === run) {
+                this.inflightCommits.delete(args.sessionId);
+            }
+        }
+    }
+    async commitVariantImpl(args) {
         // Idempotent path — SessionStore.recordVariantPick is the source of truth
         // for which variant the user picked. If the same variant is being
         // committed again, replay the previously stored envelope's metadata
@@ -284,43 +812,212 @@ class AgentVariantsOrchestrator {
                 enqueued: false,
                 duplicate: true,
                 changedFilesCount: existingPick.changedFilesCount,
+                payloadKind: existingPick.payload.kind === 'new-project'
+                    ? 'project-created'
+                    : existingPick.payload.kind,
+                destinationPath: existingPick.destinationPath,
             };
         }
         const resources = this.resources.get(args.sessionId);
         if (!resources) {
             throw new errors_1.AgentVariantsError('SESSION_NOT_FOUND', `No live resources for session ${args.sessionId} (already torn down?)`);
         }
-        const record = resources.worktrees.get(args.variantId);
-        if (!record) {
-            throw new errors_1.AgentVariantsError('WORK_ITEM_NOT_FOUND', `Unknown variantId ${args.variantId} for session ${args.sessionId}`);
-        }
-        if (record.diff === undefined) {
-            throw new errors_1.AgentVariantsError('INVALID_STAGE_ACTION', `Variant ${args.variantId} has no captured diff yet — wait for report_variant_complete(succeeded) first`);
+        const variantSnapshot = this.getVariants(args.sessionId).find((variant) => variant.workItemId === args.variantId);
+        if (!variantSnapshot || variantSnapshot.actions?.commit?.enabled !== true) {
+            throw new errors_1.AgentVariantsError('INVALID_STAGE_ACTION', variantSnapshot?.actions?.commit?.reason ?? 'Variant is not committable');
         }
-        const env = await this.resolveEnv(args.sessionId);
         const input = this.store.getWorkItemInput(args.sessionId, args.variantId);
         const projectContext = this.store.getProjectContext(args.sessionId);
-        const changedFilesCount = countDiffFiles(record.diff);
-        const payload = projectContext.kind === 'fresh'
-            ? {
-                kind: 'new-project',
-                destinationPath: projectContext.workspacePath,
-                sourceWorktreePath: record.worktreePath,
-                changedFilesCount,
+        let payload;
+        let envelopeDestination;
+        let changedFilesCount;
+        let freshVariantFolderName;
+        if (projectContext.kind === 'fresh') {
+            const destinationPath = projectContext.workspacePath;
+            this.assertDestinationAvailable(destinationPath);
+            const variantFolderName = this.getFreshVariantFolderName({
+                sessionId: args.sessionId,
+                variantId: args.variantId,
+                variantName: input.briefLabel,
+            });
+            freshVariantFolderName = variantFolderName;
+            const freshMode = projectContext.executionPlan?.mode === 'vite_app'
+                ? 'vite_app'
+                : 'static_preview';
+            if (freshMode === 'vite_app') {
+                // 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
+                // under destinationParent/.rivet-variants/) we can rename it into
+                // place. That moves the entire tree — including the materialized
+                // node_modules — in O(1) with no copy, and the rename is atomic.
+                // For cross-volume cases (user passed a destinationParent on a
+                // different mount than the .rivet-variants dir, e.g. tests stubbing
+                // workspacePath to a tmp dir), fall back to the recursive-copy +
+                // background-install path so the feature still works.
+                const record = resources.worktrees.get(args.variantId);
+                if (!record) {
+                    throw new errors_1.AgentVariantsError('WORK_ITEM_NOT_FOUND', `Unknown variantId ${args.variantId} for session ${args.sessionId}`);
+                }
+                let usedRename = false;
+                let isDependencyInstallRequired = false;
+                try {
+                    if (areSameVolume(record.worktreePath, destinationPath)) {
+                        // Vite's dev server writes its module cache to `<worktreePath>/.vite/`
+                        // and recreates that directory on the fly whenever it's missing. If
+                        // we rename a worktree out from under a running dev server, Vite
+                        // will materialize an empty `.vite/` shell back at the OLD path —
+                        // leaving behind orphan stub dirs in `.rivet-variants/` and
+                        // confusing later cleanup. Stop every variant's dev server first
+                        // (including the chosen variant, which is about to move) so no
+                        // process is holding the old paths open during the rename.
+                        //
+                        // We stop them eagerly here rather than relying on teardownSession
+                        // because teardown runs AFTER the rename — too late to prevent the
+                        // stub-dir race.
+                        await this.stopAllDevServersForSession(resources);
+                        // node_modules in fresh variants 1..N is a symlink into variant 0
+                        // (see runBackgroundInstall). After rename, variant 0's
+                        // node_modules vanishes during cleanup of the sibling worktrees,
+                        // leaving the chosen variant with a dangling link. Resolve the
+                        // symlink to a real directory first so the destination has real
+                        // deps and the rename is self-contained.
+                        isDependencyInstallRequired = await resolveNodeModulesSymlink(record.worktreePath);
+                        await this.renameWorktreeIntoDestination(record.worktreePath, destinationPath);
+                        usedRename = true;
+                    }
+                    else {
+                        await this.materializeProject(record.worktreePath, destinationPath);
+                    }
+                }
+                catch (err) {
+                    const message = err instanceof Error ? err.message : String(err);
+                    throw new errors_1.AgentVariantsError('RUNTIME_VALIDATION_FAILED', `Failed to materialize vite_app variant to ${destinationPath}: ${message}`);
+                }
+                changedFilesCount = countWorktreeFiles(destinationPath);
+                if (!usedRename) {
+                    // Cross-volume fallback: materializeProject excludes node_modules
+                    // so we have to re-install at the destination. Don't await the
+                    // install — the agent's commit_variant call should return
+                    // immediately — but chain the dev-server start to it so the iframe
+                    // recovers without manual intervention once deps are ready.
+                    void this.installDependencies(destinationPath)
+                        .then(() => this.startCommittedDevServer({
+                        resources,
+                        destinationPath,
+                    }))
+                        .catch((err) => {
+                        log.warn(`Background install + committed dev server start after vite_app commit failed for ${destinationPath}`, err);
+                    });
+                }
+                else if (isDependencyInstallRequired) {
+                    await this.installDependencies(destinationPath);
+                }
+                if (usedRename) {
+                    // Preserve the unchosen variants as runnable siblings of the
+                    // chosen project. Best-effort: failures here log and continue so
+                    // a partial history never blocks the commit handoff.
+                    try {
+                        this.preserveUnchosenVariants({
+                            sessionId: args.sessionId,
+                            chosenVariantId: args.variantId,
+                            destinationPath,
+                        });
+                    }
+                    catch (err) {
+                        log.warn(`preserveUnchosenVariants failed for session ${args.sessionId}; continuing without history`, err);
+                    }
+                    // Stopped every dev server pre-rename to dodge the .vite/ stub-dir
+                    // race. The iframe is still pointed at the (now-dead) chosen
+                    // variant's port via the proxy, so without a fresh server at the
+                    // destination the user would see "preview disconnected" the moment
+                    // they commit. Spawn one and retarget the proxy. Best-effort: if
+                    // it fails, the user can `npm run dev` themselves at destination.
+                    await this.startCommittedDevServer({
+                        resources,
+                        destinationPath,
+                    });
+                }
+                payload = {
+                    kind: 'project-created',
+                    destinationPath,
+                    changedFilesCount,
+                    note: usedRename
+                        ? 'Vite app moved to destinationPath (rename); node_modules came along.'
+                        : 'Vite app materialized at destinationPath; `npm install` running in the background.',
+                };
+                envelopeDestination = destinationPath;
+            }
+            else {
+                // Static_preview: HTML is the entire deliverable. Write index.html.
+                const staticPreview = resources.staticPreviews.get(args.variantId);
+                const persistedSnapshotIndexPath = (0, createProjectArtifacts_1.createProjectVariantIndexPath)(destinationPath, variantFolderName);
+                const htmlFromSnapshot = fs_1.default.existsSync(persistedSnapshotIndexPath)
+                    ? fs_1.default.readFileSync(persistedSnapshotIndexPath, 'utf8')
+                    : null;
+                if (!staticPreview && !htmlFromSnapshot) {
+                    throw new errors_1.AgentVariantsError('INVALID_STAGE_ACTION', `No static preview found for variant ${args.variantId} — wait for report_variant_complete(succeeded) first`);
+                }
+                try {
+                    fs_1.default.mkdirSync(destinationPath, { recursive: true });
+                    fs_1.default.writeFileSync(path_1.default.join(destinationPath, 'index.html'), staticPreview?.html ?? htmlFromSnapshot ?? '', 'utf8');
+                }
+                catch (err) {
+                    const message = err instanceof Error ? err.message : String(err);
+                    throw new errors_1.AgentVariantsError('RUNTIME_VALIDATION_FAILED', `Failed to write static preview to ${destinationPath}: ${message}`);
+                }
+                changedFilesCount = 1;
+                payload = {
+                    kind: 'project-created',
+                    destinationPath,
+                    changedFilesCount,
+                    note: 'Static preview written to index.html at destinationPath.',
+                };
+                envelopeDestination = destinationPath;
+            }
+        }
+        else {
+            // Existing project: diff against the user's repo. resolveEnv lives in
+            // this branch only — fresh sessions don't have a user-supplied project
+            // and the bridge.getProjectPath() it reads from would either be stale
+            // or empty for them.
+            const env = await this.resolveEnv(args.sessionId);
+            const record = resources.worktrees.get(args.variantId);
+            if (!record) {
+                throw new errors_1.AgentVariantsError('WORK_ITEM_NOT_FOUND', `Unknown variantId ${args.variantId} for session ${args.sessionId}`);
+            }
+            if (record.diff === undefined) {
+                throw new errors_1.AgentVariantsError('INVALID_STAGE_ACTION', `Variant ${args.variantId} has no captured diff yet — wait for report_variant_complete(succeeded) first`);
+            }
+            changedFilesCount = countDiffFiles(record.diff);
+            // Apply the diff to the user's working tree right now so the variant
+            // lands on the current branch (uncommitted). Previously this just
+            // enqueued the diff for an agent to apply; non-MCP sessions had no
+            // agent and the variant was effectively lost.
+            if (!this.worktrees.applyDiffToProject) {
+                throw new errors_1.AgentVariantsError('RUNTIME_VALIDATION_FAILED', 'WorktreeManager does not support applying diffs to the project tree');
+            }
+            try {
+                await this.worktrees.applyDiffToProject(record.diff, env.projectPath);
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                throw new errors_1.AgentVariantsError('RUNTIME_VALIDATION_FAILED', `Failed to apply variant ${args.variantId} to ${env.projectPath}: ${message}`);
             }
-            : {
-                kind: 'diff',
+            payload = {
+                kind: 'diff-applied',
                 diff: record.diff,
                 target: input.target,
                 changedFilesCount,
+                note: 'Variant diff applied to the user\'s working tree (uncommitted).',
             };
+            envelopeDestination = env.projectPath;
+        }
         const envelope = {
             sourceSessionId: args.sessionId,
             variantId: args.variantId,
             variantLabel: input.briefLabel,
-            destinationPath: projectContext.kind === 'fresh'
-                ? projectContext.workspacePath
-                : env.projectPath,
+            destinationPath: envelopeDestination,
             changedFilesCount,
             payload,
         };
@@ -331,6 +1028,27 @@ class AgentVariantsOrchestrator {
             sessionId: args.sessionId,
             envelope,
         });
+        if (projectContext.kind === 'fresh') {
+            // Manifest persistence is bookkeeping for the .rivet/ artifacts and must
+            // never strand the session — `recordVariantPick` above has already marked
+            // this variant as the selection, so a retry would short-circuit via the
+            // `duplicate: true` path and skip the enqueue below. Catch and log
+            // instead of letting a filesystem hiccup block the handoff to pending-
+            // changes.
+            try {
+                this.persistFreshSelectionMetadata({
+                    sessionId: args.sessionId,
+                    variantId: args.variantId,
+                    variantName: input.briefLabel,
+                    projectPath: projectContext.workspacePath,
+                    variantFolderName: freshVariantFolderName ?? (0, createProjectArtifacts_1.createProjectVariantSlug)(input.briefLabel),
+                    changedFilesCount,
+                });
+            }
+            catch (err) {
+                log.warn(`persistFreshSelectionMetadata failed for session ${args.sessionId} variant ${args.variantId} — continuing with enqueue`, err);
+            }
+        }
         const enqueueResult = this.adapter.enqueue(envelope);
         resources.committedVariantIds.add(args.variantId);
         if (this.activeSessionId === args.sessionId) {
@@ -350,24 +1068,63 @@ class AgentVariantsOrchestrator {
         });
         this.emitChange();
         log.info(`Variant ${args.variantId} (${input.briefLabel}) committed by user → enqueued=${enqueueResult.enqueued}`);
-        // Once a variant is committed, the unpicked worktrees are no longer
-        // useful. Schedule teardown in the background so the agent's
-        // commit_variant call returns immediately.
-        void this.teardownSession(args.sessionId, 'committed').catch((err) => {
-            log.warn(`teardownSession after commit failed for ${args.sessionId}`, err);
-        });
+        if (!args.skipTeardown) {
+            // Once a variant is committed, the unpicked worktrees are no longer
+            // useful. Schedule teardown in the background so the agent's
+            // commit_variant call returns immediately.
+            void this.teardownSession(args.sessionId, 'committed').catch((err) => {
+                log.warn(`teardownSession after commit failed for ${args.sessionId}`, err);
+            });
+        }
         return {
             enqueued: enqueueResult.enqueued,
             duplicate: enqueueResult.duplicate,
             changedFilesCount,
+            payloadKind: payload.kind,
+            destinationPath: envelopeDestination,
         };
     }
+    async cleanupCommittedSession(sessionId) {
+        await this.teardownSession(sessionId, 'committed');
+    }
+    /**
+     * Ensure the user-facing destination path can receive the new project.
+     * Rejects when the path exists and is non-empty.
+     */
+    assertDestinationAvailable(destinationPath) {
+        if (!fs_1.default.existsSync(destinationPath))
+            return;
+        const entries = fs_1.default.readdirSync(destinationPath);
+        const userVisibleEntries = entries.filter((entry) => entry !== '.rivet');
+        if (userVisibleEntries.length === 0)
+            return;
+        throw new errors_1.AgentVariantsError('DESTINATION_NOT_EMPTY', `Destination ${destinationPath} is not empty (${userVisibleEntries.length} entries) — refuse to materialize.`);
+    }
     /** Read the captured diff for a code-gen variant, if available. */
     getVariantDiff(sessionId, variantId) {
         return this.resources.get(sessionId)?.worktrees.get(variantId)?.diff;
     }
     // --- Side-effect implementations ----------------------------------------
     async provisionWorktrees(sessionId, approveResult) {
+        const projectContext = this.store.getProjectContext(sessionId);
+        if (projectContext.kind === 'fresh') {
+            // Fresh + static_preview: no worktrees, no scaffold, HTML is the
+            // deliverable. Fresh + vite_app: provision a Vite skeleton per variant
+            // and copy the agent-planned assetPlan files before the agent leases
+            // its code_gen items.
+            if (approveResult.scaffoldBaseWorkItemId) {
+                await this.provisionFreshWorktrees(sessionId, approveResult, projectContext);
+            }
+            return;
+        }
+        await this.provisionExistingWorktrees(sessionId, approveResult);
+    }
+    /**
+     * Existing-project flow: clone the user's repo N times via git worktree.
+     * Runs synchronously because the operation is fast (no install needed —
+     * node_modules is symlinked from the source project).
+     */
+    async provisionExistingWorktrees(sessionId, approveResult) {
         const resources = this.ensureResources(sessionId);
         const totalCount = approveResult.codeGenWorkItemIds.length +
             (approveResult.scaffoldBaseWorkItemId ? 1 : 0);
@@ -385,14 +1142,268 @@ class AgentVariantsOrchestrator {
             cursor += 1;
         }
         for (const id of approveResult.codeGenWorkItemIds) {
-            const path = paths[cursor];
+            const p = paths[cursor];
             cursor += 1;
-            resources.worktrees.set(id, { workItemId: id, worktreePath: path });
+            resources.worktrees.set(id, { workItemId: id, worktreePath: p });
+        }
+    }
+    /**
+     * Fresh-project flow: scaffold one template per variant + DESIGN.md per
+     * slot synchronously (fast — just file writes + git init), then dispatch a
+     * background `npm install` task per worktree. Returns immediately so the
+     * `approve_variant_briefs` MCP tool doesn't time out on cold installs.
+     *
+     * On install success: `sessionStore.completeInternal(scaffold_base)` runs,
+     * which unblocks the dependent code_gen items.
+     *
+     * On install failure: the scaffold_base work item is marked failed via
+     * `failInternal`, which cascades DEPENDENCY_FAILED to all dependent
+     * code_gen items so the session degrades cleanly.
+     */
+    async provisionFreshWorktrees(sessionId, approveResult, projectContext) {
+        const resources = this.ensureResources(sessionId);
+        const scaffoldId = approveResult.scaffoldBaseWorkItemId;
+        if (!scaffoldId) {
+            throw new errors_1.AgentVariantsError('INVALID_STAGE_ACTION', `Fresh session ${sessionId} approved without a scaffold_base item`);
+        }
+        const codeGenIds = approveResult.codeGenWorkItemIds;
+        if (codeGenIds.length === 0)
+            return;
+        const designContext = projectContext.designContext
+            ? codeGenIds.map((codeGenId) => {
+                const input = this.store.getWorkItemInput(sessionId, codeGenId);
+                return input.designContextEntry;
+            })
+            : undefined;
+        const sourceContext = projectContext.sourceContext;
+        const createFresh = this.worktrees.createFreshWorktrees;
+        if (!createFresh) {
+            throw new errors_1.AgentVariantsError('RUNTIME_VALIDATION_FAILED', 'worktreeManager does not implement createFreshWorktrees');
+        }
+        const scaffoldStartedAt = Date.now();
+        trackScaffoldStarted(this.telemetry, {
+            sessionId,
+            variantCount: codeGenIds.length,
+            designContext: summarizeDesignContext(designContext),
+        });
+        log.info(`Provisioning ${codeGenIds.length} fresh worktree(s) for session ${sessionId}`);
+        // destinationParent for fresh worktrees: same parent the materialized
+        // project will land in. Keeping the worktree on the same volume turns
+        // commit into a directory rename instead of a recursive copy.
+        const destinationParent = path_1.default.dirname(projectContext.workspacePath);
+        const paths = await createFresh.call(this.worktrees, sessionId, codeGenIds.length, viteReactTs_1.VITE_REACT_TS_TEMPLATE, designContext, sourceContext, destinationParent);
+        resources.scaffoldBaseWorkItemId = scaffoldId;
+        resources.freshDestinationParent = destinationParent;
+        // Each code_gen item maps 1:1 to a fresh worktree. The scaffold_base
+        // work item is internal — no dedicated worktree.
+        for (let i = 0; i < codeGenIds.length; i++) {
+            resources.worktrees.set(codeGenIds[i], {
+                workItemId: codeGenIds[i],
+                worktreePath: paths[i],
+            });
+        }
+        // Copy agent-planned assets (e.g. avatar.glb) into each worktree so
+        // generated code can reference them via plan.referenceAs. Done before
+        // the background install so the assets are on disk by the time the
+        // agent leases its code_gen item.
+        // If copy throws (e.g. source asset deleted between planning and
+        // provisioning), fail scaffold_base immediately so dependent code_gen
+        // items cascade DEPENDENCY_FAILED instead of leaving the session
+        // permanently stuck in `work_items_ready`.
+        const assetPlan = projectContext.executionPlan?.assetPlan ?? [];
+        if (assetPlan.length > 0) {
+            try {
+                for (const worktreePath of paths) {
+                    for (const entry of assetPlan) {
+                        copyAssetIntoWorktree(worktreePath, entry, projectContext.assetSourceRoot);
+                    }
+                }
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                log.warn(`asset copy failed for session ${sessionId}; marking scaffold_base failed`, err);
+                trackScaffoldFailed(this.telemetry, {
+                    sessionId,
+                    errorCode: 'SCAFFOLD_FAILED',
+                    durationMs: Date.now() - scaffoldStartedAt,
+                });
+                try {
+                    this.store.failInternal({
+                        sessionId,
+                        workItemId: scaffoldId,
+                        error: { code: 'SCAFFOLD_FAILED', message },
+                    });
+                    this.emitChange();
+                }
+                catch (storeErr) {
+                    log.error(`failInternal failed for ${sessionId}/${scaffoldId}`, storeErr);
+                }
+                return;
+            }
         }
+        // Background install: don't await. The orchestrator finishes the
+        // approve→provision call immediately; the agent polls for scaffold
+        // completion via continue_variants(action='check').
+        void this.runBackgroundInstall(sessionId, scaffoldId, paths, scaffoldStartedAt).catch((err) => {
+            log.error(`runBackgroundInstall failed for session ${sessionId}`, err);
+        });
     }
-    async handleSucceededReport(sessionId, workItemId) {
+    /**
+     * Run `npm install` in parallel across all fresh worktrees. On all-success,
+     * mark scaffold_base succeeded via `completeInternal`. On any failure,
+     * mark scaffold_base failed via `failInternal` and emit telemetry.
+     */
+    async runBackgroundInstall(sessionId, scaffoldWorkItemId, worktreePaths, scaffoldStartedAt) {
+        const installStartedAt = Date.now();
+        try {
+            const [firstWorktree, ...rest] = worktreePaths;
+            await this.installDependencies(firstWorktree);
+            await Promise.all(rest.map(async (p) => {
+                const target = path_1.default.join(firstWorktree, 'node_modules');
+                const link = path_1.default.join(p, 'node_modules');
+                // The fresh template has no node_modules until install runs, so
+                // the link target is guaranteed absent in `p` — no need to remove
+                // first.
+                try {
+                    fs_1.default.symlinkSync(target, link, 'dir');
+                }
+                catch (symlinkErr) {
+                    log.warn(`Symlink node_modules failed for ${p}, falling back to install`, symlinkErr);
+                    await this.installDependencies(p);
+                }
+            }));
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            log.warn(`npm install failed for session ${sessionId}; marking scaffold_base failed`, err);
+            trackScaffoldFailed(this.telemetry, {
+                sessionId,
+                errorCode: 'SCAFFOLD_FAILED',
+                durationMs: Date.now() - scaffoldStartedAt,
+            });
+            try {
+                this.store.failInternal({
+                    sessionId,
+                    workItemId: scaffoldWorkItemId,
+                    error: { code: 'SCAFFOLD_FAILED', message },
+                });
+                this.emitChange();
+            }
+            catch (storeErr) {
+                log.error(`failInternal failed for ${sessionId}/${scaffoldWorkItemId}`, storeErr);
+            }
+            return;
+        }
+        try {
+            this.store.completeInternal({
+                sessionId,
+                workItemId: scaffoldWorkItemId,
+                output: { worktreePaths },
+            });
+            this.emitChange();
+        }
+        catch (err) {
+            log.warn(`completeInternal failed for ${sessionId}/${scaffoldWorkItemId}`, err);
+        }
+        trackScaffoldCompleted(this.telemetry, {
+            sessionId,
+            durationMs: Date.now() - scaffoldStartedAt,
+            installDurationMs: Date.now() - installStartedAt,
+            variantCount: worktreePaths.length,
+        });
+    }
+    /**
+     * Gate `succeeded` reports for `static_preview` items through preview QA
+     * before they reach the store. Returns either `null` (caller continues
+     * with the original args — non-static-preview report, non-succeeded
+     * status, no parseable HTML, or QA passed) or an override carrying a
+     * `failed` rewrite of the report. The QA result is also memoized on the
+     * session resources so `getVariants` can surface it.
+     *
+     * Only fresh-project sessions go through this gate today; existing-
+     * project `code_gen` variants produce a diff with no preview document
+     * to inspect, so they skip QA and behave exactly as before.
+     */
+    async evaluateQaForReport(args) {
+        if (args.status !== 'succeeded')
+            return null;
+        if (!this.store.hasSession(args.sessionId))
+            return null;
+        const projectContext = this.store.getProjectContext(args.sessionId);
+        if (projectContext.kind !== 'fresh')
+            return null;
+        const parsed = parseStaticPreviewOutput(normalizeOutput(args.output));
+        if (!parsed)
+            return null;
+        let qa;
+        try {
+            qa = await this.previewQaRunner({
+                sessionId: args.sessionId,
+                workItemId: args.workItemId,
+                html: parsed.html,
+            });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            qa = {
+                status: 'failed',
+                issues: [
+                    {
+                        kind: 'preview_unavailable',
+                        detail: 'qa_runner_error',
+                        message,
+                    },
+                ],
+                summary: `Preview QA runner threw: ${message}`,
+            };
+        }
+        const resources = this.ensureResources(args.sessionId);
+        resources.qaResults.set(args.workItemId, qa);
+        if (qa.status === 'failed') {
+            return {
+                qa,
+                overrideArgs: {
+                    ...args,
+                    status: 'failed',
+                    error: { code: 'VARIANT_QA_FAILED', message: qa.summary },
+                },
+            };
+        }
+        return { qa };
+    }
+    async handleSucceededReport(args) {
+        const { sessionId, workItemId } = args;
         const resources = this.resources.get(sessionId);
         const record = resources?.worktrees.get(workItemId);
+        if (resources && !record) {
+            const staticPreview = parseStaticPreviewOutput(normalizeOutput(args.output));
+            if (staticPreview) {
+                const input = this.store.getWorkItemInput(sessionId, workItemId);
+                if (input.briefId) {
+                    const record = {
+                        workItemId,
+                        briefId: input.briefId,
+                        html: staticPreview.html,
+                    };
+                    resources.staticPreviews.set(workItemId, record);
+                    if (this.store.getProjectContext(sessionId).kind === 'fresh') {
+                        this.persistFreshVariantArtifacts({
+                            sessionId,
+                            workItemId,
+                            html: staticPreview.html,
+                        });
+                    }
+                    const leasedAt = resources.leasedAt.get(workItemId);
+                    trackStaticPreviewCompleted(this.telemetry, {
+                        sessionId,
+                        variantId: workItemId,
+                        durationMs: leasedAt !== undefined ? Date.now() - leasedAt : null,
+                    });
+                    this.emitChange();
+                }
+                return;
+            }
+        }
         if (!resources || !record) {
             log.warn(`No worktree record for ${sessionId}/${workItemId}; skipping diff capture`);
             return;
@@ -403,6 +1414,8 @@ class AgentVariantsOrchestrator {
             log.info(`scaffold_base ${workItemId} succeeded; awaiting dependent code-gen`);
             return;
         }
+        const projectContext = this.store.getProjectContext(sessionId);
+        const isFresh = projectContext.kind === 'fresh';
         try {
             record.diff = await this.worktrees.getDiff(record.worktreePath);
             log.info(`Variant ${workItemId} diff captured (${countDiffFiles(record.diff)} files)`);
@@ -415,26 +1428,457 @@ class AgentVariantsOrchestrator {
         // 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 env = await this.resolveEnv(sessionId);
             const port = await this.worktrees.getFreePort();
-            const cwd = await this.worktrees.getProjectCwdInWorktree(record.worktreePath);
-            const { cmd, args, env: spawnEnv } = env.buildDevCommand
-                ? env.buildDevCommand(port)
-                : {
-                    cmd: env.packageManager,
-                    args: [env.devCommand, '--port', String(port)],
-                    env: { PORT: String(port) },
-                };
-            const proc = await this.worktrees.startDevServer(cwd, port, cmd, args, spawnEnv);
+            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();
-            log.info(`Variant ${workItemId} dev server up on port ${port} (worktree ${record.worktreePath}; cmd: ${cmd} ${args.join(' ')})`);
+            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);
         }
     }
+    persistFreshVariantArtifacts(args) {
+        const projectContext = this.store.getProjectContext(args.sessionId);
+        if (projectContext.kind !== 'fresh') {
+            return;
+        }
+        const projectPath = projectContext.workspacePath;
+        const now = new Date().toISOString();
+        const projectManifestPath = (0, createProjectArtifacts_1.createProjectManifestPath)(projectPath);
+        const existingProjectManifest = this.readManifest(projectManifestPath);
+        (0, createProjectArtifacts_1.writeCreateProjectManifestFile)(projectManifestPath, (0, createProjectArtifacts_1.createProjectManifest)({
+            createdAt: existingProjectManifest?.createdAt ?? now,
+            selectedDesignSlug: existingProjectManifest?.selectedDesignSlug,
+            latestVariantSessionId: args.sessionId,
+            selectedVariantId: existingProjectManifest?.selectedVariantId,
+        }));
+        const briefInput = this.store.getWorkItemInput(args.sessionId, args.workItemId);
+        const variantFolderName = this.getFreshVariantFolderName({
+            sessionId: args.sessionId,
+            variantId: args.workItemId,
+            variantName: briefInput.briefLabel,
+        });
+        const snapshotPath = (0, createProjectArtifacts_1.createProjectVariantSnapshotPath)(projectPath, variantFolderName);
+        fs_1.default.rmSync(snapshotPath, { recursive: true, force: true });
+        fs_1.default.mkdirSync(snapshotPath, { recursive: true });
+        const briefPath = (0, createProjectArtifacts_1.createProjectVariantBriefPath)(projectPath, variantFolderName);
+        fs_1.default.writeFileSync(briefPath, `# ${briefInput.briefLabel}\n\n${briefInput.briefBody}\n`, 'utf8');
+        const variantManifestPath = (0, createProjectArtifacts_1.createProjectVariantManifestPath)(projectPath, variantFolderName);
+        (0, createProjectArtifacts_1.writeCreateProjectManifestFile)(variantManifestPath, {
+            schemaVersion: createProjectArtifacts_1.CREATE_PROJECT_MANIFEST_SCHEMA_VERSION,
+            createdAt: now,
+            sessionId: args.sessionId,
+            variantId: args.workItemId,
+            variantName: briefInput.briefLabel,
+            variantFolderName,
+            changedFilesCount: 1,
+        });
+        fs_1.default.writeFileSync((0, createProjectArtifacts_1.createProjectVariantIndexPath)(projectPath, variantFolderName), args.html, 'utf8');
+    }
+    persistFreshSelectionMetadata(args) {
+        const now = new Date().toISOString();
+        const projectManifestPath = (0, createProjectArtifacts_1.createProjectManifestPath)(args.projectPath);
+        const existingProjectManifest = this.readManifest(projectManifestPath);
+        (0, createProjectArtifacts_1.writeCreateProjectManifestFile)(projectManifestPath, (0, createProjectArtifacts_1.createProjectManifest)({
+            createdAt: existingProjectManifest?.createdAt ?? now,
+            selectedDesignSlug: existingProjectManifest?.selectedDesignSlug,
+            latestVariantSessionId: args.sessionId,
+            selectedVariantId: args.variantId,
+        }));
+        const variantManifestPath = (0, createProjectArtifacts_1.createProjectVariantManifestPath)(args.projectPath, args.variantFolderName);
+        const existingVariantManifest = this.readManifest(variantManifestPath);
+        (0, createProjectArtifacts_1.writeCreateProjectManifestFile)(variantManifestPath, {
+            ...existingVariantManifest,
+            schemaVersion: createProjectArtifacts_1.CREATE_PROJECT_MANIFEST_SCHEMA_VERSION,
+            createdAt: existingVariantManifest?.createdAt ?? now,
+            sessionId: args.sessionId,
+            variantId: args.variantId,
+            variantName: args.variantName,
+            variantFolderName: args.variantFolderName,
+            changedFilesCount: args.changedFilesCount,
+            selectedVariantId: args.variantId,
+        });
+    }
+    getFreshVariantFolderName(args) {
+        const baseSlug = (0, createProjectArtifacts_1.createProjectVariantSlug)(args.variantName);
+        const variants = this.store.getVariants(args.sessionId);
+        const matchingVariants = variants.filter((variant) => {
+            const input = this.store.getWorkItemInput(args.sessionId, variant.workItemId);
+            return (0, createProjectArtifacts_1.createProjectVariantSlug)(input.briefLabel ?? '') === baseSlug;
+        });
+        const index = matchingVariants.findIndex((variant) => variant.workItemId === args.variantId);
+        if (index <= 0) {
+            return baseSlug;
+        }
+        return `${baseSlug}-${index + 1}`;
+    }
+    readManifest(manifestPath) {
+        if (!fs_1.default.existsSync(manifestPath)) {
+            return undefined;
+        }
+        try {
+            const raw = fs_1.default.readFileSync(manifestPath, 'utf8');
+            return JSON.parse(raw);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * Resolve dev server invocation for a worktree. Fresh-project worktrees
+     * always use the Vite template's npm command at the worktree root; existing
+     * projects defer to the user's framework/packageManager config.
+     */
+    async resolveDevServer(sessionId, worktreePath, port, isFresh) {
+        if (isFresh) {
+            return {
+                cwd: worktreePath,
+                cmd: 'npm',
+                args: [
+                    'run',
+                    'dev',
+                    '--',
+                    '--port',
+                    String(port),
+                    '--host',
+                    FRESH_DEV_SERVER_HOST,
+                ],
+                env: { PORT: String(port) },
+            };
+        }
+        const env = await this.resolveEnv(sessionId);
+        const cwd = await this.worktrees.getProjectCwdInWorktree(worktreePath);
+        if (env.buildDevCommand) {
+            return { cwd, ...env.buildDevCommand(port) };
+        }
+        return {
+            cwd,
+            cmd: env.packageManager,
+            args: [env.devCommand, '--port', String(port)],
+            env: { PORT: String(port) },
+        };
+    }
+    /**
+     * After the chosen variant has been renamed into `destinationPath`, move
+     * each unchosen sibling worktree into a `<destinationParent>/<slug>-variants/NN-<label>/`
+     * folder and repoint its `node_modules` symlink at the chosen project's
+     * real install. Writes a manifest documenting all 5 variants (the chosen
+     * one with `folder: null` and `chosenPath: '../<slug>'`).
+     *
+     * Sets `vitePreservedSiblings = true` on session resources so the
+     * subsequent teardown skips `cleanupFreshWorktrees` (which would otherwise
+     * delete the just-preserved history). Dev servers still get stopped.
+     */
+    preserveUnchosenVariants(args) {
+        const resources = this.resources.get(args.sessionId);
+        if (!resources)
+            return;
+        const destinationParent = path_1.default.dirname(args.destinationPath);
+        const projectSlug = path_1.default.basename(args.destinationPath);
+        const historyDir = (0, createProjectArtifacts_1.createVariantsHistoryPath)(destinationParent, projectSlug);
+        const sharedNodeModulesAbs = path_1.default.join(args.destinationPath, 'node_modules');
+        const briefs = this.store.getBriefs(args.sessionId);
+        const variants = this.store.getVariants(args.sessionId);
+        const briefIndexById = new Map(briefs.map((b, i) => [b.briefId, i]));
+        const manifestEntries = [];
+        let chosenSlug = '';
+        for (const variant of variants) {
+            const input = this.store.getWorkItemInput(args.sessionId, variant.workItemId);
+            const label = input.briefLabel ?? variant.label ?? 'variant';
+            const slug = (0, createProjectArtifacts_1.createProjectVariantSlug)(label);
+            const briefIdx = briefIndexById.get(variant.briefId) ?? 0;
+            const numericPrefix = String(briefIdx + 1).padStart(2, '0');
+            const folderName = `${numericPrefix}-${slug}`;
+            if (variant.workItemId === args.chosenVariantId) {
+                chosenSlug = slug;
+                manifestEntries.push({
+                    variantId: variant.workItemId,
+                    label,
+                    slug,
+                    folder: null,
+                    isChosen: true,
+                    chosenPath: `../${projectSlug}`,
+                });
+                continue;
+            }
+            const record = resources.worktrees.get(variant.workItemId);
+            if (!record) {
+                // No worktree (e.g. failed variant) — still list it in manifest with
+                // null folder so the user can see why it's absent.
+                manifestEntries.push({
+                    variantId: variant.workItemId,
+                    label,
+                    slug,
+                    folder: null,
+                    isChosen: false,
+                });
+                continue;
+            }
+            if (!fs_1.default.existsSync(record.worktreePath)) {
+                manifestEntries.push({
+                    variantId: variant.workItemId,
+                    label,
+                    slug,
+                    folder: null,
+                    isChosen: false,
+                });
+                continue;
+            }
+            try {
+                const newPath = this.worktrees.moveWorktreeToHistory
+                    ? this.worktrees.moveWorktreeToHistory(record.worktreePath, historyDir, folderName)
+                    : (() => {
+                        fs_1.default.mkdirSync(historyDir, { recursive: true });
+                        const dest = path_1.default.join(historyDir, folderName);
+                        fs_1.default.renameSync(record.worktreePath, dest);
+                        return dest;
+                    })();
+                // Repoint node_modules at the chosen project's real install.
+                try {
+                    if (this.worktrees.repointNodeModulesSymlink) {
+                        this.worktrees.repointNodeModulesSymlink(newPath, sharedNodeModulesAbs);
+                    }
+                    else {
+                        const link = path_1.default.join(newPath, 'node_modules');
+                        try {
+                            fs_1.default.rmSync(link, { force: true, recursive: true });
+                        }
+                        catch {
+                            /* may not exist */
+                        }
+                        const target = path_1.default.relative(path_1.default.dirname(link), sharedNodeModulesAbs);
+                        fs_1.default.symlinkSync(target, link, 'dir');
+                    }
+                }
+                catch (err) {
+                    log.warn(`repointNodeModulesSymlink failed for ${newPath}; variant still runnable after npm install`, err);
+                }
+                // Update the in-memory record so teardown doesn't try to operate on
+                // the stale path.
+                record.worktreePath = newPath;
+                manifestEntries.push({
+                    variantId: variant.workItemId,
+                    label,
+                    slug,
+                    folder: folderName,
+                    isChosen: false,
+                });
+            }
+            catch (err) {
+                log.warn(`moveWorktreeToHistory failed for variant ${variant.workItemId}`, err);
+                manifestEntries.push({
+                    variantId: variant.workItemId,
+                    label,
+                    slug,
+                    folder: null,
+                    isChosen: false,
+                });
+            }
+        }
+        const manifest = {
+            schemaVersion: createProjectArtifacts_1.CREATE_PROJECT_MANIFEST_SCHEMA_VERSION,
+            createdAt: new Date().toISOString(),
+            sessionId: args.sessionId,
+            chosenVariantId: args.chosenVariantId,
+            chosenSlug: chosenSlug || projectSlug,
+            variants: manifestEntries,
+        };
+        try {
+            (0, createProjectArtifacts_1.writeCreateProjectManifestFile)((0, createProjectArtifacts_1.createVariantsHistoryManifestPath)(destinationParent, projectSlug), manifest);
+        }
+        catch (err) {
+            log.warn(`Writing variants history manifest failed for ${historyDir}`, err);
+        }
+        resources.vitePreservedSiblings = true;
+    }
+    /**
+     * Rename `sourceWorktreePath` into `destinationPath`, then replace the
+     * worktree's `.git` with a fresh-history init + initial commit. Matches
+     * the historical materializeProject behavior of "user sees a fresh repo
+     * at destinationPath" so we don't surprise them with a `rivet: variant
+     * baseline` commit they didn't intend.
+     *
+     * The rename is the load-bearing operation: it moves the entire variant
+     * tree (template files + materialized node_modules) in O(1) when the
+     * source and destination share a volume. The git reset that follows is
+     * best-effort housekeeping; a failure there leaves files in place.
+     */
+    async renameWorktreeIntoDestination(sourceWorktreePath, destinationPath) {
+        // destinationPath must not exist for fs.rename to behave as a move.
+        // assertDestinationAvailable already enforced that any existing directory
+        // contains only `.rivet`, which we preserve across the move.
+        const destinationParent = path_1.default.dirname(destinationPath);
+        await fs_1.default.promises.mkdir(destinationParent, { recursive: true });
+        let preservedRivetParent;
+        const existingRivetPath = path_1.default.join(destinationPath, '.rivet');
+        if (fs_1.default.existsSync(destinationPath)) {
+            preservedRivetParent = await fs_1.default.promises.mkdtemp(path_1.default.join(destinationParent, '.rivet-preserve-'));
+            if (fs_1.default.existsSync(existingRivetPath)) {
+                await fs_1.default.promises.rename(existingRivetPath, path_1.default.join(preservedRivetParent, '.rivet'));
+            }
+            await fs_1.default.promises.rm(destinationPath, { recursive: true, force: true });
+        }
+        try {
+            await fs_1.default.promises.rename(sourceWorktreePath, destinationPath);
+        }
+        catch (err) {
+            if (preservedRivetParent && !fs_1.default.existsSync(destinationPath)) {
+                await fs_1.default.promises.mkdir(destinationPath, { recursive: true });
+                const preservedRivetPath = path_1.default.join(preservedRivetParent, '.rivet');
+                if (fs_1.default.existsSync(preservedRivetPath)) {
+                    await fs_1.default.promises.rename(preservedRivetPath, existingRivetPath);
+                }
+            }
+            throw err;
+        }
+        if (preservedRivetParent) {
+            const preservedRivetPath = path_1.default.join(preservedRivetParent, '.rivet');
+            if (fs_1.default.existsSync(preservedRivetPath)) {
+                await fs_1.default.promises.rename(preservedRivetPath, existingRivetPath);
+            }
+            await fs_1.default.promises.rm(preservedRivetParent, {
+                recursive: true,
+                force: true,
+            });
+        }
+        // Replace the variant-baseline git history with a fresh init so the
+        // user doesn't inherit a `rivet: variant baseline` commit.
+        const dotGit = path_1.default.join(destinationPath, '.git');
+        try {
+            fs_1.default.rmSync(dotGit, { recursive: true, force: true });
+        }
+        catch {
+            // Best-effort — leaving the baseline .git is preferable to failing
+            // the commit after we've moved the tree.
+        }
+        try {
+            const git = (0, simple_git_1.simpleGit)(destinationPath);
+            await git.raw(['init']);
+            await git.raw(['add', '-A']);
+            await git
+                .raw([
+                '-c',
+                'user.name=Rivet',
+                '-c',
+                'user.email=hello@tryrivet.design',
+                'commit',
+                '--no-gpg-sign',
+                '-m',
+                'Initial commit (created with Rivet)',
+            ])
+                .catch(() => {
+                // Best-effort: missing user identity or empty tree leaves the
+                // commit step un-applied. Files are still in place.
+            });
+        }
+        catch (err) {
+            log.warn(`Initial git history setup at ${destinationPath} failed`, err);
+        }
+    }
+    /**
+     * Stop every variant dev server currently running for `resources`. Clears
+     * the `devServerProcess` / `port` fields on each record so subsequent
+     * teardown logic doesn't try to stop them a second time. Called from
+     * `commitVariant` (vite_app rename path) BEFORE the worktree directory is
+     * renamed — leaving Vite alive across the rename leaks empty `.vite/`
+     * stub dirs at the old paths.
+     */
+    async stopAllDevServersForSession(resources) {
+        const stops = [];
+        for (const record of resources.worktrees.values()) {
+            if (!record.devServerProcess)
+                continue;
+            const proc = record.devServerProcess;
+            stops.push(this.worktrees
+                .stopDevServer(proc)
+                .catch((err) => log.warn(`stopDevServer pre-commit failed for ${resources.sessionId}/${record.workItemId}`, err)));
+            record.devServerProcess = undefined;
+            record.port = undefined;
+        }
+        await Promise.all(stops);
+    }
+    /**
+     * Spawn a fresh dev server at the user-facing destinationPath and retarget
+     * the proxy so the iframe stays live across commit. Stores the process on
+     * `resources.committedDevServer` so teardown can hand it off to the
+     * lingering registry instead of killing it. Best-effort: a failure here is
+     * non-fatal — the commit still succeeds; the user just has to run
+     * `npm run dev` themselves to bring the preview back.
+     */
+    async startCommittedDevServer(args) {
+        try {
+            const port = await this.worktrees.getFreePort();
+            const proc = await this.worktrees.startDevServer(args.destinationPath, port, 'npm', [
+                'run',
+                'dev',
+                '--',
+                '--port',
+                String(port),
+                '--host',
+                FRESH_DEV_SERVER_HOST,
+            ], { PORT: String(port) });
+            args.resources.committedDevServer = {
+                proc,
+                port,
+                path: args.destinationPath,
+            };
+            try {
+                this.switchPreviewPort?.(port);
+            }
+            catch (err) {
+                log.warn(`switchPreviewPort(${port}) after committed dev server start failed`, err);
+            }
+            log.info(`Committed dev server up at ${args.destinationPath} on port ${port}`);
+        }
+        catch (err) {
+            log.warn(`Failed to start committed dev server at ${args.destinationPath} — iframe may show "preview disconnected" until user runs npm run dev`, err);
+        }
+    }
+    /**
+     * Stop any committed dev servers that were left alive past their session's
+     * teardown. Called at the start of a new `propose` (so the next session's
+     * preview doesn't compete with stale processes) and exposed for explicit
+     * shutdown hooks. Best-effort: per-server failures are logged but don't
+     * propagate.
+     */
+    async stopLingeringCommittedDevServers() {
+        const entries = [...this.lingeringCommittedDevServers.entries()];
+        this.lingeringCommittedDevServers.clear();
+        await Promise.all(entries.map(async ([sessionId, entry]) => {
+            try {
+                await this.worktrees.stopDevServer(entry.proc);
+            }
+            catch (err) {
+                log.warn(`stopDevServer for lingering committed server (session ${sessionId}, port ${entry.port}) failed`, err);
+            }
+        }));
+    }
     async teardownSession(sessionId, reason) {
         const resources = this.resources.get(sessionId);
         if (!resources)
@@ -444,17 +1888,46 @@ class AgentVariantsOrchestrator {
         resources.cleanupStarted = true;
         log.info(`Tearing down session ${sessionId} (reason: ${reason})`);
         // Stop dev servers in parallel; ignore individual failures.
+        // NOTE: For the fresh vite_app rename path, commitVariant already stopped
+        // these dev servers BEFORE the rename (so Vite couldn't recreate `.vite/`
+        // stub dirs at the old worktree paths). In that case devServerProcess is
+        // already cleared and this loop is a no-op — exactly the desired behavior.
         const stops = [...resources.worktrees.values()]
             .filter((r) => r.devServerProcess)
             .map((r) => this.worktrees
             .stopDevServer(r.devServerProcess)
             .catch((err) => log.warn(`stopDevServer failed for ${sessionId}/${r.workItemId}`, err)));
         await Promise.all(stops);
-        try {
-            await this.worktrees.cleanupSession(sessionId);
+        // The committed dev server (spawned at destinationPath after a fresh
+        // vite_app commit) intentionally outlives this teardown — the iframe is
+        // pointed at it via the proxy and the user just chose this project. Hand
+        // it off to the lingering registry; it'll be stopped on the next
+        // `propose` or explicit shutdown.
+        if (resources.committedDevServer && reason === 'committed') {
+            this.lingeringCommittedDevServers.set(sessionId, resources.committedDevServer);
         }
-        catch (err) {
-            log.warn(`cleanupSession (worktree removal) failed for ${sessionId}`, err);
+        else if (resources.committedDevServer) {
+            // Non-committed teardown (cancel/shutdown) with a committed dev server
+            // shouldn't happen in current code paths, but stop it defensively so we
+            // don't leak procs.
+            try {
+                await this.worktrees.stopDevServer(resources.committedDevServer.proc);
+            }
+            catch (err) {
+                log.warn(`stopDevServer for committed dev server (session ${sessionId}) failed`, err);
+            }
+        }
+        // When a vite_app commit already moved the unchosen worktrees into a
+        // sibling history dir, calling cleanupSession would re-delete them. Skip
+        // the worktree removal step in that case — the move already cleared the
+        // .rivet-variants/ entries for the chosen + preserved variants.
+        if (!resources.vitePreservedSiblings) {
+            try {
+                await this.worktrees.cleanupSession(sessionId, resources.freshDestinationParent);
+            }
+            catch (err) {
+                log.warn(`cleanupSession (worktree removal) failed for ${sessionId}`, err);
+            }
         }
         this.resources.delete(sessionId);
     }
@@ -464,10 +1937,13 @@ class AgentVariantsOrchestrator {
             r = {
                 sessionId,
                 worktrees: new Map(),
+                staticPreviews: new Map(),
                 cleanupStarted: false,
                 committedVariantIds: new Set(),
                 startedAt: Date.now(),
                 leasedAt: new Map(),
+                qaResults: new Map(),
+                vitePreservedSiblings: false,
             };
             this.resources.set(sessionId, r);
         }
@@ -475,8 +1951,456 @@ class AgentVariantsOrchestrator {
     }
 }
 exports.AgentVariantsOrchestrator = AgentVariantsOrchestrator;
+/** MCP bridges sometimes serialize the output field as a JSON string instead
+ *  of a parsed object. Normalize it before field-level inspection. */
+/** Rough byte-size of the agent's output. Used as a proxy for "how much
+ *  code did the agent write" when comparing HTML vs full-stack flows. */
+function estimateOutputBytes(output) {
+    if (output === undefined || output === null)
+        return 0;
+    try {
+        return typeof output === 'string'
+            ? output.length
+            : JSON.stringify(output).length;
+    }
+    catch {
+        return 0;
+    }
+}
+function normalizeOutput(output) {
+    if (typeof output === 'string') {
+        try {
+            return JSON.parse(output);
+        }
+        catch {
+            return output;
+        }
+    }
+    return output;
+}
+function parseStaticPreviewOutput(output) {
+    if (!output || typeof output !== 'object')
+        return null;
+    const html = output.html;
+    if (typeof html !== 'string' || html.trim().length === 0)
+        return null;
+    const css = output.css;
+    const js = output.js;
+    return {
+        html: buildStaticPreviewDocument({
+            html,
+            css: typeof css === 'string' ? css : undefined,
+            js: typeof js === 'string' ? js : undefined,
+        }),
+    };
+}
+function buildStaticPreviewDocument(input) {
+    if (/<!doctype html>|<html[\s>]/i.test(input.html)) {
+        return input.html;
+    }
+    const style = input.css ? `<style>\n${input.css}\n</style>` : '';
+    const script = input.js ? `<script>\n${input.js}\n</script>` : '';
+    return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    ${style}
+  </head>
+  <body>
+${input.html}
+    ${script}
+  </body>
+</html>`;
+}
 function countDiffFiles(diff) {
     // Each file in a unified diff starts with "diff --git ".
     return (diff.match(/^diff --git /gm) ?? []).length;
 }
+/**
+ * Count source files under a materialized fresh-project destination,
+ * skipping install artifacts (`node_modules`, `.git`, build outputs) so the
+ * commit telemetry / chip count reflects the agent-visible surface area
+ * rather than the install footprint.
+ */
+function countWorktreeFiles(destinationPath) {
+    let count = 0;
+    const walk = (dir) => {
+        let entries;
+        try {
+            entries = fs_1.default.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (MATERIALIZE_EXCLUDE.has(entry.name))
+                continue;
+            const full = path_1.default.join(dir, entry.name);
+            if (entry.isDirectory())
+                walk(full);
+            else if (entry.isFile())
+                count += 1;
+        }
+    };
+    walk(destinationPath);
+    return count;
+}
+const enrichDesignSource = (design) => {
+    if (!design || design.kind !== 'slug')
+        return design;
+    return {
+        ...design,
+        displayName: (0, designCatalog_1.getDesignSystemBySlug)(design.slug)?.name ?? design.slug,
+    };
+};
+const toActiveProjectContext = (projectContext) => {
+    if (projectContext.kind === 'existing') {
+        return { kind: 'existing' };
+    }
+    return {
+        kind: 'fresh',
+        workspacePath: projectContext.workspacePath,
+        framework: projectContext.framework,
+        designContext: projectContext.designContext?.map((entry) => entry.kind === 'slug'
+            ? { kind: 'slug', slug: entry.slug }
+            : { kind: 'markdown', label: entry.label }),
+        ...(projectContext.sourceContext
+            ? {
+                sourceContext: {
+                    sourceCount: projectContext.sourceContext.sourceUrls?.length ?? 0,
+                    isSourceGrounded: Boolean(projectContext.sourceContext.artifact),
+                },
+            }
+            : {}),
+        ...(projectContext.executionPlan
+            ? {
+                executionPlan: {
+                    mode: projectContext.executionPlan.mode,
+                    confidence: projectContext.executionPlan.confidence,
+                    reason: projectContext.executionPlan.reason,
+                    assetCount: projectContext.executionPlan.assetPlan?.length ?? 0,
+                    runtimeRequirementCount: projectContext.executionPlan.runtimeRequirements?.length ?? 0,
+                },
+            }
+            : {}),
+    };
+};
+/**
+ * Resolve the user-facing supporting artifacts for a session.
+ *
+ * For 0→1 (`fresh`) sessions with a populated `designContext`, each slot is
+ * turned into a `design_context` artifact carrying the full DESIGN.md
+ * markdown:
+ *   - `slug` entries resolve bundled catalog markdown via the design catalog.
+ *   - `markdown` entries (Agent Browser / inspiration extractor output) carry
+ *     their stored markdown verbatim.
+ * Slots whose markdown can't be resolved are skipped so the UI never renders
+ * a metadata-only DESIGN.md row.
+ */
+const buildSessionArtifacts = (projectContext) => {
+    if (projectContext.kind !== 'fresh')
+        return [];
+    const designContext = projectContext.designContext;
+    if (!designContext || designContext.length === 0)
+        return [];
+    const artifactsByContent = new Map();
+    designContext.forEach((entry, slot) => {
+        if (!entry)
+            return;
+        if (entry.kind === 'slug') {
+            const markdown = (0, designCatalog_1.loadDesignSystemMarkdown)(entry.slug);
+            if (!markdown)
+                return;
+            const catalogEntry = (0, designCatalog_1.getDesignSystemBySlug)(entry.slug);
+            addDesignContextArtifact(artifactsByContent, {
+                id: `design_context:${slot}:${entry.slug}`,
+                kind: 'design_context',
+                label: catalogEntry?.name ?? entry.slug,
+                ...(catalogEntry?.description ? { summary: catalogEntry.description } : {}),
+                status: 'ready',
+                source: 'static',
+                contentType: 'text/markdown',
+                content: markdown,
+            });
+            return;
+        }
+        if (!entry.content)
+            return;
+        addDesignContextArtifact(artifactsByContent, {
+            id: `design_context:${slot}:${entry.label}`,
+            kind: 'design_context',
+            label: entry.label,
+            status: 'ready',
+            source: 'agent_browser',
+            contentType: 'text/markdown',
+            content: entry.content,
+        });
+    });
+    return [...artifactsByContent.values()].map((artifact) => {
+        if (artifact.usedByVariantCount <= 1)
+            return artifact;
+        return {
+            ...artifact,
+            summary: artifact.summary
+                ? `${artifact.summary} Used by ${artifact.usedByVariantCount} variants.`
+                : `Used by ${artifact.usedByVariantCount} variants.`,
+        };
+    });
+};
+const addDesignContextArtifact = (artifactsByContent, artifact) => {
+    if (!artifact.content)
+        return;
+    const existing = artifactsByContent.get(artifact.content);
+    if (existing) {
+        existing.usedByVariantCount += 1;
+        return;
+    }
+    artifactsByContent.set(artifact.content, {
+        ...artifact,
+        usedByVariantCount: 1,
+    });
+};
+const summarizeDesignContext = (designContext) => {
+    if (!designContext)
+        return null;
+    return designContext.reduce((entries, entry, slot) => {
+        if (!entry)
+            return entries;
+        if (entry.kind === 'slug') {
+            entries.push({ slot, kind: 'slug', slug: entry.slug });
+            return entries;
+        }
+        entries.push({
+            slot,
+            kind: 'markdown',
+            markdownLabel: entry.label,
+        });
+        return entries;
+    }, []);
+};
+const trackScaffoldStarted = (telemetry, data) => {
+    if (telemetry.trackAgentVariantsScaffoldStarted) {
+        telemetry.trackAgentVariantsScaffoldStarted(data);
+        return;
+    }
+    telemetry.track('agent_variants.scaffold_started', {
+        source: 'mcp',
+        session_id: data.sessionId,
+        variant_count: data.variantCount,
+        design_context: data.designContext ?? null,
+    });
+};
+const trackScaffoldCompleted = (telemetry, data) => {
+    if (telemetry.trackAgentVariantsScaffoldCompleted) {
+        telemetry.trackAgentVariantsScaffoldCompleted(data);
+        return;
+    }
+    telemetry.track('agent_variants.scaffold_completed', {
+        source: 'mcp',
+        session_id: data.sessionId,
+        duration_ms: data.durationMs,
+        install_duration_ms: data.installDurationMs,
+        variant_count: data.variantCount,
+    });
+};
+const trackScaffoldFailed = (telemetry, data) => {
+    if (telemetry.trackAgentVariantsScaffoldFailed) {
+        telemetry.trackAgentVariantsScaffoldFailed(data);
+        return;
+    }
+    telemetry.track('agent_variants.scaffold_failed', {
+        source: 'mcp',
+        session_id: data.sessionId,
+        error_code: data.errorCode,
+        duration_ms: data.durationMs,
+    });
+};
+const trackFreshDevServerStarted = (telemetry, data) => {
+    if (telemetry.trackAgentVariantsFreshDevServerStarted) {
+        telemetry.trackAgentVariantsFreshDevServerStarted(data);
+        return;
+    }
+    telemetry.track('agent_variants.fresh_dev_server_started', {
+        source: 'mcp',
+        session_id: data.sessionId,
+        variant_id: data.variantId,
+        port: data.port,
+    });
+};
+const trackFreshDevServerFailed = (telemetry, data) => {
+    if (telemetry.trackAgentVariantsFreshDevServerFailed) {
+        telemetry.trackAgentVariantsFreshDevServerFailed(data);
+        return;
+    }
+    telemetry.track('agent_variants.fresh_dev_server_failed', {
+        source: 'mcp',
+        session_id: data.sessionId,
+        variant_id: data.variantId,
+        error_code: data.errorCode,
+    });
+};
+const trackStaticPreviewCompleted = (telemetry, data) => {
+    if (telemetry.trackAgentVariantsStaticPreviewCompleted) {
+        telemetry.trackAgentVariantsStaticPreviewCompleted(data);
+        return;
+    }
+    telemetry.track('agent_variants.static_preview_completed', {
+        source: 'mcp',
+        session_id: data.sessionId,
+        variant_id: data.variantId,
+        duration_ms: data.durationMs,
+    });
+};
+const MATERIALIZE_EXCLUDE = new Set([
+    'node_modules',
+    '.git',
+    'dist',
+    '.next',
+    '.cache',
+    '.vite',
+]);
+const defaultInstallDependencies = (worktreePath) => {
+    return new Promise((resolve, reject) => {
+        const proc = (0, child_process_1.spawn)('npm', ['install', '--no-audit', '--no-fund', '--ignore-scripts'], {
+            cwd: worktreePath,
+            stdio: ['ignore', 'ignore', 'pipe'],
+        });
+        let stderr = '';
+        proc.stderr.on('data', (chunk) => {
+            stderr += chunk.toString();
+        });
+        proc.on('error', reject);
+        proc.on('exit', (code) => {
+            if (code === 0) {
+                resolve();
+                return;
+            }
+            reject(new Error(`npm install in ${worktreePath} failed (code ${code}): ${stderr.slice(-512)}`));
+        });
+    });
+};
+/**
+ * True when `a` and `b` (or the closest existing ancestor of each) live on
+ * the same filesystem volume. Used by commitVariant to decide between an
+ * O(1) rename and a recursive copy-with-reinstall fallback.
+ *
+ * `destinationPath` for fresh sessions does not exist yet (we'd fail the
+ * "destination must be empty" guard otherwise), so we compare against its
+ * parent directory which is guaranteed to exist (createZeroToOneTool either
+ * created it or validated it).
+ */
+function areSameVolume(a, b) {
+    try {
+        const statA = fs_1.default.statSync(a);
+        const parentB = fs_1.default.existsSync(b) ? b : path_1.default.dirname(b);
+        const statB = fs_1.default.statSync(parentB);
+        return statA.dev === statB.dev;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Materialize node_modules from symlink → real directory at the given path,
+ * so a subsequent rename of that path leaves a self-contained tree.
+ *
+ * Fresh worktrees 1..N share variant 0's node_modules via a symlink (see
+ * runBackgroundInstall). When the user picks variant K and we rename it
+ * into the destination, the sibling worktrees get torn down — which would
+ * otherwise leave a dangling symlink in the destination if variant K was
+ * the one with the symlink (K > 0).
+ *
+ * Returns true when the destination must run a dependency install after the
+ * rename because node_modules is missing or points nowhere.
+ */
+async function resolveNodeModulesSymlink(worktreePath) {
+    const nodeModulesPath = path_1.default.join(worktreePath, 'node_modules');
+    let lstat;
+    try {
+        lstat = await fs_1.default.promises.lstat(nodeModulesPath);
+    }
+    catch {
+        return true;
+    }
+    if (!lstat.isSymbolicLink())
+        return false;
+    let target;
+    try {
+        target = await fs_1.default.promises.realpath(nodeModulesPath);
+    }
+    catch {
+        await fs_1.default.promises.rm(nodeModulesPath, { force: true });
+        return true;
+    }
+    // Stage the copy under a sibling temp name so a mid-copy failure (disk
+    // full, EACCES, etc.) leaves the original symlink intact rather than
+    // wiping it and leaving the worktree with no node_modules at all.
+    // The final swap is then atomic on the same filesystem (rename + unlink).
+    const stagingPath = `${nodeModulesPath}.materializing-${(0, crypto_1.randomBytes)(4).toString('hex')}`;
+    try {
+        await fs_1.default.promises.cp(target, stagingPath, {
+            recursive: true,
+            dereference: false,
+        });
+    }
+    catch (err) {
+        // Best-effort cleanup of the partial staging dir; leave the symlink
+        // intact so the caller can re-run materialization.
+        await fs_1.default.promises
+            .rm(stagingPath, { recursive: true, force: true })
+            .catch(() => { });
+        throw err;
+    }
+    // Swap: remove the symlink, then rename the staging dir into place.
+    // Both operations are local fs ops on the same parent — fast and
+    // unlikely to fail independently, but if the rename fails the symlink
+    // is already gone, so prefer to leave the staging dir on disk over a
+    // half-broken worktree (the caller will surface the throw).
+    await fs_1.default.promises.rm(nodeModulesPath, { force: true });
+    await fs_1.default.promises.rename(stagingPath, nodeModulesPath);
+    return false;
+}
+const defaultMaterializeProject = async (sourceWorktreePath, destinationPath) => {
+    await fs_1.default.promises.mkdir(destinationPath, { recursive: true });
+    await fs_1.default.promises.cp(sourceWorktreePath, destinationPath, {
+        recursive: true,
+        filter: (sourcePath) => {
+            const rel = path_1.default.relative(sourceWorktreePath, sourcePath);
+            if (!rel)
+                return true;
+            const top = rel.split(path_1.default.sep)[0];
+            return !MATERIALIZE_EXCLUDE.has(top);
+        },
+    });
+    const git = (0, simple_git_1.simpleGit)(destinationPath);
+    await git.raw(['init']);
+    await git.raw(['add', '-A']);
+    await git
+        .raw([
+        '-c',
+        'user.name=Rivet',
+        '-c',
+        'user.email=hello@tryrivet.design',
+        'commit',
+        '--no-gpg-sign',
+        '-m',
+        'Initial commit (created with Rivet)',
+    ])
+        .catch(() => {
+        // Best-effort: a missing user identity or empty tree leaves the
+        // commit step un-applied. The destination still has the files.
+    });
+};
+/**
+ * Synthesize a placeholder brief body for a unified start_variants slot.
+ * The body must fit `briefSchema.body` (≤ 200 chars, ≥ 1 char). The agent's
+ * streamed first-line label replaces this in the UI once code_gen output
+ * arrives. Index/total are unused for now but kept in the signature so
+ * future diversity hints can be added without a call-site change.
+ */
+function synthesizeUnifiedBriefBody(prompt, _index, _total) {
+    const trimmed = prompt.trim().replace(/\s+/g, ' ').slice(0, 200);
+    return trimmed.length > 0 ? trimmed : 'variant';
+}
 //# sourceMappingURL=WorktreeOrchestrator.js.map