rivet-design 0.9.1 → 0.9.3

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

@@ -1,11 +1,21 @@
 "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 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 contracts_1 = require("./contracts");
+const viteReactTs_1 = require("../../services/templates/viteReactTs");
+const designCatalog_1 = require("../../services/templates/designCatalog");
 const log = (0, logger_1.createLogger)('AgentVariantsOrchestrator');
+const FRESH_DEV_SERVER_HOST = '127.0.0.1';
 const NOOP_TELEMETRY = { track: () => undefined };
 /**
  * Wraps SessionStore for the operations that have side effects: approve
@@ -25,6 +35,8 @@ class AgentVariantsOrchestrator {
     adapter;
     resolveEnv;
     telemetry;
+    installDependencies;
+    materializeProject;
     resources = new Map();
     /** Most recent agent-variants sessionId — read by the iframe chip via
      *  GET /api/variants/active. Cleared on cancel or commit. */
@@ -38,6 +50,10 @@ 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;
     }
     // --- Pure delegations (no side effects) ---------------------------------
     propose(args) {
@@ -82,13 +98,9 @@ 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 projectContext = toActiveProjectContext(this.store.getProjectContext(sessionId));
+        const destinationPath = projectContext.kind === 'fresh' ? projectContext.workspacePath : undefined;
         return {
             active: true,
             sessionId,
@@ -97,6 +109,8 @@ class AgentVariantsOrchestrator {
             progress,
             summary,
             variants,
+            projectContext,
+            ...(destinationPath ? { destinationPath } : {}),
         };
     }
     emitChange() {
@@ -109,6 +123,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;
+    }
+    reportSourceContext(args) {
+        const result = this.store.reportSourceContext(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'),
+        });
         this.emitChange();
         return result;
     }
@@ -156,9 +190,77 @@ 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 isSucceeded = variant.status === 'succeeded';
+            const canView = Boolean(preview) || (isSucceeded && Boolean(port));
+            const canCommit = isSucceeded;
+            return {
+                ...variant,
+                design: enrichDesignSource(variant.design),
+                ...(preview ? { preview } : {}),
+                port,
+                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: 'Wait for a successful variant',
+                        },
+                },
+            };
+        });
+    }
     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 +270,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,6 +326,99 @@ 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.count ?? 4;
+        const projectContext = args.projectContext ?? { kind: 'existing' };
+        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),
+        }));
+        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);
         this.emitChange();
@@ -207,6 +431,11 @@ class AgentVariantsOrchestrator {
             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,
@@ -214,9 +443,15 @@ class AgentVariantsOrchestrator {
                 status: args.status,
                 attempt: args.attempt,
                 durationMs,
+                approveToCompleteMs,
                 hasError: Boolean(args.error),
                 errorCode: args.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 +459,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 +471,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) => {
+            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 +511,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
@@ -284,43 +559,74 @@ 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,
+        let payload;
+        let envelopeDestination;
+        let changedFilesCount;
+        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');
+            }
+            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 {
+            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);
+            payload = {
                 kind: 'diff',
                 diff: record.diff,
                 target: input.target,
                 changedFilesCount,
             };
+            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,
         };
@@ -350,24 +656,57 @@ 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);
+        if (entries.length === 0)
+            return;
+        throw new errors_1.AgentVariantsError('DESTINATION_NOT_EMPTY', `Destination ${destinationPath} is not empty (${entries.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 sessions use static_preview as the final deliverable — no
+            // worktrees, no scaffold, no npm install needed.
+            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 +724,143 @@ 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}`);
+        const paths = await createFresh.call(this.worktrees, sessionId, codeGenIds.length, viteReactTs_1.VITE_REACT_TS_TEMPLATE, designContext, sourceContext);
+        resources.scaffoldBaseWorkItemId = scaffoldId;
+        // 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],
+            });
+        }
+        // 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);
+        });
+    }
+    /**
+     * 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 {
+            await Promise.all(worktreePaths.map((p) => 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,
+        });
     }
-    async handleSucceededReport(sessionId, workItemId) {
+    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);
+                    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 +871,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 +885,62 @@ 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;
             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);
         }
     }
+    /**
+     * 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) },
+        };
+    }
     async teardownSession(sessionId, reason) {
         const resources = this.resources.get(sessionId);
         if (!resources)
@@ -464,6 +970,7 @@ class AgentVariantsOrchestrator {
             r = {
                 sessionId,
                 worktrees: new Map(),
+                staticPreviews: new Map(),
                 cleanupStarted: false,
                 committedVariantIds: new Set(),
                 startedAt: Date.now(),
@@ -475,8 +982,260 @@ 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;
 }
+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),
+                },
+            }
+            : {}),
+    };
+};
+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)}`));
+        });
+    });
+};
+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