rivet-design 0.9.3 → 0.9.4

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

@@ -4,6 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (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"));
@@ -11,11 +12,180 @@ 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
@@ -37,7 +207,29 @@ class AgentVariantsOrchestrator {
     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;
@@ -54,9 +246,17 @@ class AgentVariantsOrchestrator {
             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);
@@ -99,8 +299,10 @@ class AgentVariantsOrchestrator {
             ? this.store.getSummary(sessionId)
             : null;
         const variants = this.getVariants(sessionId);
-        const projectContext = toActiveProjectContext(this.store.getProjectContext(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,
@@ -111,6 +313,7 @@ class AgentVariantsOrchestrator {
             variants,
             projectContext,
             ...(destinationPath ? { destinationPath } : {}),
+            ...(artifacts.length > 0 ? { artifacts } : {}),
         };
     }
     emitChange() {
@@ -134,14 +337,14 @@ class AgentVariantsOrchestrator {
         this.emitChange();
         return result;
     }
-    reportSourceContext(args) {
-        const result = this.store.reportSourceContext(args);
+    reportSourcePlan(args) {
+        const result = this.store.reportSourcePlan(args);
         this.telemetry.trackAgentVariantsSourceContextQuality?.({
             sessionId: args.sessionId,
-            sourceUrlCount: args.sourceContext.sourceRoles.length,
-            artifactCount: args.sourceContext.sourceFindings.length,
-            hasScreenshotReferences: (args.sourceContext.screenshotReferences?.length ?? 0) > 0,
-            preserveBrand: args.sourceContext.sourceRoles.some((entry) => entry.role === 'primary'),
+            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;
@@ -226,14 +429,20 @@ class AgentVariantsOrchestrator {
             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;
+            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 }
@@ -247,7 +456,7 @@ class AgentVariantsOrchestrator {
                         ? { enabled: true }
                         : {
                             enabled: false,
-                            reason: 'Wait for a successful variant',
+                            reason: commitDisabledReason,
                         },
                 },
             };
@@ -344,26 +553,40 @@ class AgentVariantsOrchestrator {
      * work items via continue_variants(action="request_work").
      */
     async startUnified(args) {
-        const count = args.count ?? 4;
+        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_source_research') {
-            throw new errors_1.AgentVariantsError('INVALID_STAGE_ACTION', 'start_variants cannot handle source-research sessions. Use create_zero_to_one_project for inspiration-grounded fresh projects.');
-        }
         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 = Array.from({ length: count }, (_, i) => ({
-            briefId: `v${i + 1}`,
-            label: `Variant ${i + 1}`,
-            body: synthesizeUnifiedBriefBody(args.prompt, i + 1, count),
-        }));
+        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,
@@ -420,14 +643,21 @@ class AgentVariantsOrchestrator {
         };
     }
     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;
@@ -440,12 +670,12 @@ class AgentVariantsOrchestrator {
                 source: 'mcp',
                 sessionId: args.sessionId,
                 workItemId: args.workItemId,
-                status: args.status,
+                status: effectiveArgs.status,
                 attempt: args.attempt,
                 durationMs,
                 approveToCompleteMs,
-                hasError: Boolean(args.error),
-                errorCode: args.error?.code ?? null,
+                hasError: Boolean(effectiveArgs.error),
+                errorCode: effectiveArgs.error?.code ?? null,
                 isScaffold: resources?.scaffoldBaseWorkItemId === args.workItemId,
                 projectContextKind,
                 tokensIn: args.tokensIn ?? null,
@@ -476,7 +706,7 @@ class AgentVariantsOrchestrator {
                 });
             }
         }
-        if (args.status === 'succeeded') {
+        if (effectiveArgs.status === 'succeeded') {
             void this.handleSucceededReport({
                 sessionId: args.sessionId,
                 workItemId: args.workItemId,
@@ -549,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
@@ -573,39 +826,162 @@ class AgentVariantsOrchestrator {
         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);
         let payload;
         let envelopeDestination;
         let changedFilesCount;
+        let freshVariantFolderName;
         if (projectContext.kind === 'fresh') {
-            // Fresh sessions: static preview HTML is the deliverable. Write index.html
-            // to the destination directory.
             const destinationPath = projectContext.workspacePath;
             this.assertDestinationAvailable(destinationPath);
-            const staticPreview = resources.staticPreviews.get(args.variantId);
-            if (!staticPreview) {
-                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, 'utf8');
+            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;
             }
-            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}`);
+            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;
             }
-            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}`);
@@ -614,11 +990,26 @@ class AgentVariantsOrchestrator {
                 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}`);
+            }
             payload = {
-                kind: 'diff',
+                kind: 'diff-applied',
                 diff: record.diff,
                 target: input.target,
                 changedFilesCount,
+                note: 'Variant diff applied to the user\'s working tree (uncommitted).',
             };
             envelopeDestination = env.projectPath;
         }
@@ -637,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) {
@@ -683,9 +1095,10 @@ class AgentVariantsOrchestrator {
         if (!fs_1.default.existsSync(destinationPath))
             return;
         const entries = fs_1.default.readdirSync(destinationPath);
-        if (entries.length === 0)
+        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 (${entries.length} entries) — refuse to materialize.`);
+        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) {
@@ -695,8 +1108,13 @@ class AgentVariantsOrchestrator {
     async provisionWorktrees(sessionId, approveResult) {
         const projectContext = this.store.getProjectContext(sessionId);
         if (projectContext.kind === 'fresh') {
-            // Fresh sessions use static_preview as the final deliverable — no
-            // worktrees, no scaffold, no npm install needed.
+            // 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);
@@ -769,8 +1187,13 @@ class AgentVariantsOrchestrator {
             designContext: summarizeDesignContext(designContext),
         });
         log.info(`Provisioning ${codeGenIds.length} fresh worktree(s) for session ${sessionId}`);
-        const paths = await createFresh.call(this.worktrees, sessionId, codeGenIds.length, viteReactTs_1.VITE_REACT_TS_TEMPLATE, designContext, sourceContext);
+        // 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++) {
@@ -779,6 +1202,45 @@ class AgentVariantsOrchestrator {
                 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').
@@ -794,7 +1256,22 @@ class AgentVariantsOrchestrator {
     async runBackgroundInstall(sessionId, scaffoldWorkItemId, worktreePaths, scaffoldStartedAt) {
         const installStartedAt = Date.now();
         try {
-            await Promise.all(worktreePaths.map((p) => this.installDependencies(p)));
+            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);
@@ -835,6 +1312,65 @@ class AgentVariantsOrchestrator {
             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);
@@ -850,6 +1386,13 @@ class AgentVariantsOrchestrator {
                         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,
@@ -890,6 +1433,19 @@ class AgentVariantsOrchestrator {
             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();
             trackFreshDevServerStarted(this.telemetry, {
                 sessionId,
@@ -907,6 +1463,93 @@ class AgentVariantsOrchestrator {
             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
@@ -941,6 +1584,301 @@ class AgentVariantsOrchestrator {
             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)
@@ -950,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);
     }
@@ -975,6 +1942,8 @@ class AgentVariantsOrchestrator {
                 committedVariantIds: new Set(),
                 startedAt: Date.now(),
                 leasedAt: new Map(),
+                qaResults: new Map(),
+                vitePreservedSiblings: false,
             };
             this.resources.set(sessionId, r);
         }
@@ -1048,6 +2017,35 @@ 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;
@@ -1075,8 +2073,94 @@ const toActiveProjectContext = (projectContext) => {
                 },
             }
             : {}),
+        ...(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;
@@ -1196,6 +2280,87 @@ const defaultInstallDependencies = (worktreePath) => {
         });
     });
 };
+/**
+ * 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, {