rivet-design 0.9.4 → 0.9.6

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

@@ -4,9 +4,11 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AgentVariantsOrchestrator = void 0;
+exports.buildStaticPreviewDocument = buildStaticPreviewDocument;
 const crypto_1 = require("crypto");
 const events_1 = require("events");
 const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
 const path_1 = __importDefault(require("path"));
 const child_process_1 = require("child_process");
 const simple_git_1 = require("simple-git");
@@ -17,8 +19,11 @@ 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 VariantHistoryService_1 = require("../../services/VariantHistoryService");
 const log = (0, logger_1.createLogger)('AgentVariantsOrchestrator');
 const FRESH_DEV_SERVER_HOST = '127.0.0.1';
+const DESIGN_CONTEXT_ROUTE_SEGMENT = 'design-md';
+const DESIGN_CONTEXT_VIEW_SEGMENT = 'view';
 /**
  * Allowlist of asset file extensions an agent-planned source may have.
  * `assetPlan` is sized for large local *assets* (3D models, images,
@@ -36,15 +41,36 @@ const FRESH_DEV_SERVER_HOST = '127.0.0.1';
  */
 const ALLOWED_ASSET_EXTENSIONS = new Set([
     // 3D / models
-    '.glb', '.gltf', '.obj', '.fbx', '.usdz',
+    '.glb',
+    '.gltf',
+    '.obj',
+    '.fbx',
+    '.usdz',
     // images
-    '.png', '.jpg', '.jpeg', '.gif', '.webp', '.svg', '.avif', '.bmp', '.ico',
+    '.png',
+    '.jpg',
+    '.jpeg',
+    '.gif',
+    '.webp',
+    '.svg',
+    '.avif',
+    '.bmp',
+    '.ico',
     // video
-    '.mp4', '.webm', '.mov',
+    '.mp4',
+    '.webm',
+    '.mov',
     // audio
-    '.mp3', '.wav', '.ogg', '.m4a',
+    '.mp3',
+    '.wav',
+    '.ogg',
+    '.m4a',
     // fonts
-    '.woff', '.woff2', '.ttf', '.otf', '.eot',
+    '.woff',
+    '.woff2',
+    '.ttf',
+    '.otf',
+    '.eot',
     // PDFs
     '.pdf',
 ]);
@@ -177,8 +203,7 @@ function copyAssetIntoWorktree(worktreePath, entry, assetSourceRoot) {
         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)) {
+    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);
@@ -209,6 +234,7 @@ class AgentVariantsOrchestrator {
     materializeProject;
     previewQaRunner;
     switchPreviewPort;
+    variantHistory;
     resources = new Map();
     /**
      * Committed dev servers from prior sessions that survived teardown. The
@@ -248,6 +274,7 @@ class AgentVariantsOrchestrator {
             deps.materializeProject ?? defaultMaterializeProject;
         this.previewQaRunner = deps.previewQaRunner ?? defaultPreviewQaRunner;
         this.switchPreviewPort = deps.switchPreviewPort;
+        this.variantHistory = deps.variantHistory ?? new VariantHistoryService_1.VariantHistoryService();
     }
     // --- Pure delegations (no side effects) ---------------------------------
     propose(args) {
@@ -301,8 +328,10 @@ class AgentVariantsOrchestrator {
         const variants = this.getVariants(sessionId);
         const sessionProjectContext = this.store.getProjectContext(sessionId);
         const projectContext = toActiveProjectContext(sessionProjectContext);
-        const destinationPath = projectContext.kind === 'fresh' ? projectContext.workspacePath : undefined;
-        const artifacts = buildSessionArtifacts(sessionProjectContext);
+        const destinationPath = projectContext.kind === 'fresh'
+            ? projectContext.workspacePath
+            : undefined;
+        const artifacts = buildSessionArtifacts(sessionId, sessionProjectContext);
         return {
             active: true,
             sessionId,
@@ -424,7 +453,9 @@ class AgentVariantsOrchestrator {
                         };
                     }
                 }
-                catch { /* work item may not exist in edge cases */ }
+                catch {
+                    /* work item may not exist in edge cases */
+                }
             }
             if (!preview && port) {
                 preview = { kind: 'dev_server', port };
@@ -435,7 +466,7 @@ class AgentVariantsOrchestrator {
             const canView = Boolean(preview) || (isSucceeded && Boolean(port));
             const canCommit = isSucceeded && !qaFailed;
             const commitDisabledReason = qaFailed
-                ? qa?.summary ?? 'Variant failed QA'
+                ? (qa?.summary ?? 'Variant failed QA')
                 : 'Wait for a successful variant';
             return {
                 ...variant,
@@ -481,7 +512,9 @@ class AgentVariantsOrchestrator {
     }
     getStaticPreviewHtml(sessionId, workItemId) {
         // Primary: from the staticPreviews Map populated by handleSucceededReport.
-        const fromMap = this.resources.get(sessionId)?.staticPreviews.get(workItemId)?.html;
+        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
@@ -496,6 +529,16 @@ class AgentVariantsOrchestrator {
             return undefined;
         }
     }
+    /** Resolve the DESIGN.md markdown behind an artifact link. */
+    getDesignContextMarkdown(sessionId, artifactId) {
+        const artifact = findDesignContextArtifact(this.store.getProjectContext(sessionId), artifactId);
+        return artifact?.content;
+    }
+    /** Build the raw-plus-rendered DesignMD document for an artifact link. */
+    getDesignContextViewerHtml(sessionId, artifactId) {
+        const artifact = findDesignContextArtifact(this.store.getProjectContext(sessionId), artifactId);
+        return artifact ? buildDesignContextViewerDocument(artifact) : undefined;
+    }
     getStaticPreviewByBriefId(sessionId, briefId) {
         const resources = this.resources.get(sessionId);
         if (!resources)
@@ -554,8 +597,12 @@ class AgentVariantsOrchestrator {
      */
     async startUnified(args) {
         const count = args.briefs?.length ?? args.count ?? 4;
-        const projectContext = args.projectContext ?? { kind: 'existing' };
-        const sourceContext = projectContext.kind === 'fresh' ? projectContext.sourceContext : undefined;
+        const 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) ||
@@ -736,6 +783,9 @@ class AgentVariantsOrchestrator {
             fromStage: stageBefore,
         });
         this.emitChange();
+        void this.markPersistedVariantsCancelled(args.sessionId).catch((err) => {
+            log.warn(`markPersistedVariantsCancelled failed for ${args.sessionId}`, err);
+        });
         void this.teardownSession(args.sessionId, 'cancel').catch((err) => {
             log.error(`teardownSession failed for ${args.sessionId}`, err);
         });
@@ -763,6 +813,11 @@ class AgentVariantsOrchestrator {
             alreadyTerminal: result.alreadyTerminal,
             reason: args.reason ?? null,
         });
+        if (!result.alreadyTerminal) {
+            void this.markPersistedVariantCancelled(args.sessionId, args.variantId).catch((err) => {
+                log.warn(`markPersistedVariantCancelled failed for ${args.sessionId}/${args.variantId}`, err);
+            });
+        }
         this.emitChange();
         return {
             sessionId: args.sessionId,
@@ -808,6 +863,38 @@ class AgentVariantsOrchestrator {
         // without going back through resources (which may have been torn down).
         const existingPick = this.store.getVariantPick(args.sessionId);
         if (existingPick && existingPick.variantId === args.variantId) {
+            // Retry-safe history flip. If the first commit attempt enqueued
+            // successfully but the history-persist task crashed (it's
+            // fire-and-forget — see persistVariantHistoryAtCommit call site),
+            // the chosen variant stays at `completed` instead of `committed`
+            // on disk. Re-run the flip on every duplicate attempt; the
+            // terminal-status guard in `markStatus` makes this safely
+            // idempotent.
+            const projectContext = this.store.getProjectContext(args.sessionId);
+            let historyProjectPath;
+            if (projectContext.kind === 'fresh') {
+                historyProjectPath = projectContext.workspaceRoot;
+            }
+            else {
+                try {
+                    historyProjectPath = (await this.resolveEnv(args.sessionId))
+                        ?.projectPath;
+                }
+                catch {
+                    historyProjectPath = undefined;
+                }
+            }
+            if (historyProjectPath) {
+                void this.persistVariantHistoryAtCommit({
+                    sessionId: args.sessionId,
+                    chosenVariantId: args.variantId,
+                    projectPath: historyProjectPath,
+                    projectKind: projectContext.kind,
+                    destinationPath: existingPick.destinationPath ?? historyProjectPath,
+                }).catch((err) => {
+                    log.warn(`persistVariantHistoryAtCommit (duplicate retry) failed for session ${args.sessionId}`, err);
+                });
+            }
             return {
                 enqueued: false,
                 duplicate: true,
@@ -824,23 +911,18 @@ class AgentVariantsOrchestrator {
         }
         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');
+            throw new errors_1.AgentVariantsError('INVALID_STAGE_ACTION', variantSnapshot?.actions?.commit?.reason ??
+                'Variant is not committable');
         }
         const input = this.store.getWorkItemInput(args.sessionId, args.variantId);
         const projectContext = this.store.getProjectContext(args.sessionId);
         let payload;
         let envelopeDestination;
         let changedFilesCount;
-        let freshVariantFolderName;
+        let runnablePaths;
         if (projectContext.kind === 'fresh') {
             const destinationPath = projectContext.workspacePath;
             this.assertDestinationAvailable(destinationPath);
-            const variantFolderName = this.getFreshVariantFolderName({
-                sessionId: args.sessionId,
-                variantId: args.variantId,
-                variantName: input.briefLabel,
-            });
-            freshVariantFolderName = variantFolderName;
             const freshMode = projectContext.executionPlan?.mode === 'vite_app'
                 ? 'vite_app'
                 : 'static_preview';
@@ -918,7 +1000,7 @@ class AgentVariantsOrchestrator {
                     // chosen project. Best-effort: failures here log and continue so
                     // a partial history never blocks the commit handoff.
                     try {
-                        this.preserveUnchosenVariants({
+                        runnablePaths = this.preserveUnchosenVariants({
                             sessionId: args.sessionId,
                             chosenVariantId: args.variantId,
                             destinationPath,
@@ -950,11 +1032,16 @@ class AgentVariantsOrchestrator {
             }
             else {
                 // Static_preview: HTML is the entire deliverable. Write index.html.
+                // Prefer the in-memory record; fall back to the persisted history at
+                // `<workspaceRoot>/.rivet/variants/<sessionId>/<variantId>/files/index.html`
+                // so a process restart between report_variant_complete and commit
+                // doesn't strand the variant.
                 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;
+                const htmlFromSnapshot = await this.variantHistory.readStaticPreview({
+                    projectPath: projectContext.workspaceRoot,
+                    sessionId: args.sessionId,
+                    variantId: args.variantId,
+                });
                 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`);
                 }
@@ -1009,7 +1096,7 @@ class AgentVariantsOrchestrator {
                 diff: record.diff,
                 target: input.target,
                 changedFilesCount,
-                note: 'Variant diff applied to the user\'s working tree (uncommitted).',
+                note: "Variant diff applied to the user's working tree (uncommitted).",
             };
             envelopeDestination = env.projectPath;
         }
@@ -1028,30 +1115,37 @@ 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);
-            }
-        }
+        // History: flip every persisted variant in this session to its terminal
+        // status. Variants were persisted at code_gen success time; this only
+        // patches the status (+ destinationPath on the chosen one). For fresh
+        // sessions, history lives at `<workspaceRoot>/.rivet/variants/` — the
+        // user's working dir — so all variants from any session in the workspace
+        // accumulate in one place, not per-subproject. Best-effort, never blocks
+        // the commit.
+        const historyProjectPath = projectContext.kind === 'fresh'
+            ? projectContext.workspaceRoot
+            : envelopeDestination;
+        void this.persistVariantHistoryAtCommit({
+            sessionId: args.sessionId,
+            chosenVariantId: args.variantId,
+            projectPath: historyProjectPath,
+            projectKind: projectContext.kind,
+            destinationPath: envelopeDestination,
+            runnablePaths,
+        }).catch((err) => {
+            log.warn(`persistVariantHistoryAtCommit failed for session ${args.sessionId}`, err);
+        });
         const enqueueResult = this.adapter.enqueue(envelope);
         resources.committedVariantIds.add(args.variantId);
-        if (this.activeSessionId === args.sessionId) {
+        // For fresh `new-project` commits the committed variant IS the user's
+        // final result — there's no dev server to fall back to. Keep the session
+        // active so SSE keeps pushing snapshots with the chosen variant; the UI's
+        // iframe stays on it instead of unmounting to about:blank (which would
+        // surface a misleading "Preview isn't connected" overlay). For diff /
+        // diff-applied commits the user moves on to their own dev server, so
+        // clearing is correct — that's the original behavior preserved below.
+        if (this.activeSessionId === args.sessionId &&
+            payload.kind !== 'project-created') {
             this.activeSessionId = null;
         }
         const dwellMsFromTerminal = resources.terminalAt
@@ -1090,12 +1184,17 @@ class AgentVariantsOrchestrator {
     /**
      * Ensure the user-facing destination path can receive the new project.
      * Rejects when the path exists and is non-empty.
+     *
+     * `.rivet/` (pre-commit snapshots + history manifests) and `.gitignore`
+     * (written by VariantHistoryService.ensureGitignore when variants persist
+     * at success time) are both tolerated — neither is user-authored content
+     * that would be clobbered by the materialize step.
      */
     assertDestinationAvailable(destinationPath) {
         if (!fs_1.default.existsSync(destinationPath))
             return;
         const entries = fs_1.default.readdirSync(destinationPath);
-        const userVisibleEntries = entries.filter((entry) => entry !== '.rivet');
+        const userVisibleEntries = entries.filter((entry) => entry !== '.rivet' && entry !== '.gitignore');
         if (userVisibleEntries.length === 0)
             return;
         throw new errors_1.AgentVariantsError('DESTINATION_NOT_EMPTY', `Destination ${destinationPath} is not empty (${userVisibleEntries.length} entries) — refuse to materialize.`);
@@ -1187,10 +1286,16 @@ class AgentVariantsOrchestrator {
             designContext: summarizeDesignContext(designContext),
         });
         log.info(`Provisioning ${codeGenIds.length} fresh worktree(s) for session ${sessionId}`);
-        // destinationParent for fresh worktrees: same parent the materialized
-        // project will land in. Keeping the worktree on the same volume turns
-        // commit into a directory rename instead of a recursive copy.
-        const destinationParent = path_1.default.dirname(projectContext.workspacePath);
+        // destinationParent for fresh worktrees: the user's workspace root
+        // (sibling to `.rivet/`). Keeping the worktree on the same volume as
+        // the materialize destination turns commit into a directory rename
+        // instead of a recursive copy. `path.dirname(workspacePath)` *used*
+        // to equal `workspaceRoot`, but after nesting subprojects under
+        // `<workspaceRoot>/.rivet/<slug>/` the dirname is now `.rivet/`,
+        // which would stage worktrees inside `.rivet/.rivet-variants/`.
+        // Use workspaceRoot directly so staging lives at
+        // `<workspaceRoot>/.rivet-variants/` as originally intended.
+        const destinationParent = projectContext.workspaceRoot;
         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;
@@ -1387,10 +1492,17 @@ class AgentVariantsOrchestrator {
                     };
                     resources.staticPreviews.set(workItemId, record);
                     if (this.store.getProjectContext(sessionId).kind === 'fresh') {
-                        this.persistFreshVariantArtifacts({
+                        // History at `<workspaceRoot>/.rivet/variants/<sessionId>/<variantId>/`
+                        // is the sole on-disk record. The legacy per-subproject snapshot
+                        // tree (`<slug>/.rivet/<variantName>/`) is no longer written —
+                        // it duplicated this data in a parallel layout and cluttered
+                        // `.rivet/` with slug-named directories before the user ever
+                        // committed.
+                        this.persistCompletedFreshVariant({
                             sessionId,
                             workItemId,
-                            html: staticPreview.html,
+                        }).catch((err) => {
+                            log.warn(`persistCompletedFreshVariant failed for ${sessionId}/${workItemId}`, err);
                         });
                     }
                     const leasedAt = resources.leasedAt.get(workItemId);
@@ -1424,6 +1536,31 @@ class AgentVariantsOrchestrator {
         catch (err) {
             log.warn(`getDiff failed for ${record.worktreePath}`, err);
         }
+        // History: persist every completed variant immediately to
+        // `<projectPath>/.rivet/variants/`. Existing projects pass the captured
+        // diff (or an empty string when capture itself failed — the variant
+        // still succeeded code-gen-wise, and the history row is the only
+        // record the UI has). Fresh-project variants copy their worktree
+        // (vite_app) or the staged HTML (static_preview). Best-effort — a
+        // failure here must never block dev-server startup or the user's pick
+        // flow.
+        if (!isFresh) {
+            this.persistCompletedExistingVariant({
+                sessionId,
+                workItemId,
+                diff: record.diff ?? '',
+            }).catch((err) => {
+                log.warn(`persistCompletedExistingVariant failed for ${sessionId}/${workItemId}`, err);
+            });
+        }
+        else {
+            this.persistCompletedFreshVariant({
+                sessionId,
+                workItemId,
+            }).catch((err) => {
+                log.warn(`persistCompletedFreshVariant failed for ${sessionId}/${workItemId}`, err);
+            });
+        }
         // Bring up a dev server in the variant's worktree so the user can cycle
         // through live variants in the iframe via the chip. Failures here are
         // logged but non-fatal — the user can still pick by reading the diff.
@@ -1463,80 +1600,229 @@ class AgentVariantsOrchestrator {
             log.warn(`Failed to start dev server for variant ${workItemId}; live preview disabled for this variant`, err);
         }
     }
-    persistFreshVariantArtifacts(args) {
+    /**
+     * Persist a completed existing-project code_gen variant into
+     * `<env.projectPath>/.rivet/variants/<sessionId>/<variantId>/`. Called from
+     * `handleSucceededReport` once the worktree diff has been captured but
+     * before the user picks. Status is `completed` until `commitVariant` or a
+     * cancellation transitions it.
+     */
+    async persistCompletedExistingVariant(args) {
         const projectContext = this.store.getProjectContext(args.sessionId);
-        if (projectContext.kind !== 'fresh') {
+        if (projectContext.kind !== 'existing')
             return;
+        let env;
+        try {
+            env = await this.resolveEnv(args.sessionId);
         }
-        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,
+        catch (err) {
+            log.warn(`persistCompletedExistingVariant: resolveEnv failed for ${args.sessionId}`, err);
+            return;
+        }
+        const record = this.resources.get(args.sessionId)?.worktrees.get(args.workItemId);
+        let sourceDir;
+        if (env.framework === 'static' && record) {
+            try {
+                sourceDir = await this.worktrees.getProjectCwdInWorktree(record.worktreePath);
+            }
+            catch (err) {
+                log.warn(`persistCompletedExistingVariant: static snapshot path failed for ${args.sessionId}/${args.workItemId}`, err);
+            }
+        }
+        const input = this.store.getWorkItemInput(args.sessionId, args.workItemId);
+        const sessionPrompt = this.store.getPrompt(args.sessionId);
+        await this.variantHistory.persistVariant({
+            projectPath: env.projectPath,
             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,
+            label: input.briefLabel,
+            brief: input.briefBody,
+            sessionPrompt,
+            kind: 'diff',
+            diff: args.diff,
+            sourceDir,
+            preview: sourceDir
+                ? { kind: 'static', entryPath: 'index.html' }
+                : { kind: 'none', reason: 'diff_only' },
+            changedFilesCount: countDiffFiles(args.diff),
+            projectKind: 'existing',
         });
     }
-    getFreshVariantFolderName(args) {
-        const baseSlug = (0, createProjectArtifacts_1.createProjectVariantSlug)(args.variantName);
+    /**
+     * Persist a completed fresh-project variant into
+     * `<projectContext.workspacePath>/.rivet/variants/<sessionId>/<variantId>/`.
+     * Called from `handleSucceededReport` right after the per-variant snapshot
+     * lands on disk — for static_preview that's the `.rivet/<slug>/` snapshot
+     * dir; for vite_app fresh variants it's the worktree itself. Status starts
+     * as 'completed' and transitions to 'committed' / 'rejected' / 'cancelled'
+     * via `markStatus` at commit or teardown time.
+     *
+     * Running at success time (rather than commit time) means the history panel
+     * populates live as variants generate — including when the user never picks
+     * one. Mirrors the existing-project persistCompletedExistingVariant flow.
+     */
+    async persistCompletedFreshVariant(args) {
+        const projectContext = this.store.getProjectContext(args.sessionId);
+        if (projectContext.kind !== 'fresh')
+            return;
+        // Variant history lives at the workspace root — the user's working
+        // dir (e.g. `fable-eng-demo/`). All variants from any session in this
+        // workspace accumulate at
+        // `<workspaceRoot>/.rivet/variants/<sessionId>/<variantId>/`.
+        const historyProjectPath = projectContext.workspaceRoot;
+        const input = this.store.getWorkItemInput(args.sessionId, args.workItemId);
+        const sessionPrompt = this.store.getPrompt(args.sessionId);
+        const designArtifact = resolveDesignArtifact(input.designContextEntry);
+        const resources = this.resources.get(args.sessionId);
+        const worktreeRecord = resources?.worktrees.get(args.workItemId);
+        const staticPreview = resources?.staticPreviews.get(args.workItemId);
+        // Vite_app deliverables are full scaffolded worktrees — pass the worktree
+        // directory as sourceDir and let copyDirFiltered handle it (excludes
+        // node_modules, .rivet, etc). Static_preview deliverables are inline HTML
+        // captured in `resources.staticPreviews`; stage them in a tmp dir so the
+        // existing copy path works without poking the user's workspace.
+        let sourceDir = null;
+        let tmpStagingDir = null;
+        if (worktreeRecord && fs_1.default.existsSync(worktreeRecord.worktreePath)) {
+            sourceDir = worktreeRecord.worktreePath;
+        }
+        else if (staticPreview) {
+            tmpStagingDir = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), `rivet-variant-${args.workItemId}-`));
+            fs_1.default.writeFileSync(path_1.default.join(tmpStagingDir, 'index.html'), staticPreview.html, 'utf8');
+            fs_1.default.writeFileSync(path_1.default.join(tmpStagingDir, 'brief.md'), `# ${input.briefLabel}\n\n${input.briefBody}\n`, 'utf8');
+            sourceDir = tmpStagingDir;
+        }
+        if (!sourceDir) {
+            log.warn(`persistCompletedFreshVariant: no source for ${args.workItemId} (session ${args.sessionId}); skipping`);
+            return;
+        }
+        // For static_preview, only `index.html` is a real deliverable — `brief.md`
+        // is implementation-detail staging that we copy alongside it. Hardcode
+        // the count so the history row matches what `commit_variant` reports
+        // (always 1) instead of double-counting the brief.
+        const changedFilesCount = staticPreview ? 1 : countWorktreeFiles(sourceDir);
+        const preview = staticPreview
+            ? { kind: 'static', entryPath: 'index.html' }
+            : {
+                kind: 'dev-server',
+                command: {
+                    cwd: '.',
+                    packageManager: 'npm',
+                    script: 'dev',
+                },
+            };
+        try {
+            await this.variantHistory.persistVariant({
+                projectPath: historyProjectPath,
+                sessionId: args.sessionId,
+                variantId: args.workItemId,
+                label: input.briefLabel,
+                brief: input.briefBody,
+                sessionPrompt,
+                kind: 'project-created',
+                sourceDir,
+                preview,
+                changedFilesCount,
+                projectKind: 'fresh',
+                designMarkdown: designArtifact?.markdown,
+                designSource: designArtifact?.source,
+            });
+        }
+        finally {
+            if (tmpStagingDir) {
+                try {
+                    fs_1.default.rmSync(tmpStagingDir, { recursive: true, force: true });
+                }
+                catch (err) {
+                    log.warn(`Failed to clean up variant staging dir ${tmpStagingDir}: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+        }
+    }
+    /**
+     * At commit time, flip persisted variant manifests to terminal statuses
+     * ('committed' for the chosen, 'rejected' for the rest). Both existing- and
+     * fresh-project variants have already been persisted at code_gen success
+     * time, so this is a pure status update — no source-dir copy required.
+     * Also records the destination path on the chosen variant so history can
+     * surface "this variant became <path>".
+     */
+    async persistVariantHistoryAtCommit(args) {
         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;
+        for (const variant of variants) {
+            if (variant.status !== 'succeeded')
+                continue;
+            const workItemId = variant.workItemId;
+            const isChosen = workItemId === args.chosenVariantId;
+            const status = isChosen
+                ? 'committed'
+                : 'rejected';
+            await this.variantHistory.markStatus({
+                projectPath: args.projectPath,
+                sessionId: args.sessionId,
+                variantId: workItemId,
+                status,
+                destinationPath: isChosen ? args.destinationPath : undefined,
+                runnablePath: args.runnablePaths?.get(workItemId),
+            });
+        }
+    }
+    /**
+     * Flip persisted variant manifests to status='cancelled' for every variant
+     * in the session that was already snapshotted to disk. Fresh- and existing-
+     * project variants both persist at success time now, so both need their
+     * manifests flipped here. Best-effort — missing manifests are silently
+     * skipped by VariantHistoryService.markStatus.
+     */
+    async markPersistedVariantsCancelled(sessionId) {
+        if (!this.store.hasSession(sessionId))
+            return;
+        const projectPath = await this.resolveHistoryProjectPath(sessionId);
+        if (!projectPath)
+            return;
+        const variants = this.store.getVariants(sessionId);
+        for (const variant of variants) {
+            await this.variantHistory.markStatus({
+                projectPath,
+                sessionId,
+                variantId: variant.workItemId,
+                status: 'cancelled',
+            });
+        }
+    }
+    async markPersistedVariantCancelled(sessionId, variantId) {
+        if (!this.store.hasSession(sessionId))
+            return;
+        const projectPath = await this.resolveHistoryProjectPath(sessionId);
+        if (!projectPath)
+            return;
+        await this.variantHistory.markStatus({
+            projectPath,
+            sessionId,
+            variantId,
+            status: 'cancelled',
         });
-        const index = matchingVariants.findIndex((variant) => variant.workItemId === args.variantId);
-        if (index <= 0) {
-            return baseSlug;
+    }
+    /**
+     * Resolve the project path that owns `.rivet/variants/` for a session.
+     * Existing sessions: the user's project (via `resolveEnv`). Fresh sessions:
+     * the *workspace root*, which is the parent of `workspacePath` — variants
+     * accumulate there across sessions instead of being scattered under each
+     * subproject. Must match what `persistCompletedFreshVariant` writes to.
+     */
+    async resolveHistoryProjectPath(sessionId) {
+        const projectContext = this.store.getProjectContext(sessionId);
+        if (projectContext.kind === 'fresh') {
+            return projectContext.workspaceRoot;
+        }
+        try {
+            const env = await this.resolveEnv(sessionId);
+            return env.projectPath;
+        }
+        catch (err) {
+            log.warn(`resolveHistoryProjectPath: resolveEnv failed for ${sessionId}`, err);
+            return null;
         }
-        return `${baseSlug}-${index + 1}`;
     }
     readManifest(manifestPath) {
         if (!fs_1.default.existsSync(manifestPath)) {
@@ -1597,8 +1883,9 @@ class AgentVariantsOrchestrator {
      */
     preserveUnchosenVariants(args) {
         const resources = this.resources.get(args.sessionId);
+        const runnablePaths = new Map();
         if (!resources)
-            return;
+            return runnablePaths;
         const destinationParent = path_1.default.dirname(args.destinationPath);
         const projectSlug = path_1.default.basename(args.destinationPath);
         const historyDir = (0, createProjectArtifacts_1.createVariantsHistoryPath)(destinationParent, projectSlug);
@@ -1617,6 +1904,7 @@ class AgentVariantsOrchestrator {
             const folderName = `${numericPrefix}-${slug}`;
             if (variant.workItemId === args.chosenVariantId) {
                 chosenSlug = slug;
+                runnablePaths.set(variant.workItemId, projectSlug);
                 manifestEntries.push({
                     variantId: variant.workItemId,
                     label,
@@ -1682,6 +1970,7 @@ class AgentVariantsOrchestrator {
                 // Update the in-memory record so teardown doesn't try to operate on
                 // the stale path.
                 record.worktreePath = newPath;
+                runnablePaths.set(variant.workItemId, `${path_1.default.basename(historyDir)}/${folderName}`);
                 manifestEntries.push({
                     variantId: variant.workItemId,
                     label,
@@ -1716,6 +2005,7 @@ class AgentVariantsOrchestrator {
             log.warn(`Writing variants history manifest failed for ${historyDir}`, err);
         }
         resources.vitePreservedSiblings = true;
+        return runnablePaths;
     }
     /**
      * Rename `sourceWorktreePath` into `destinationPath`, then replace the
@@ -1995,11 +2285,33 @@ function parseStaticPreviewOutput(output) {
     };
 }
 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>` : '';
+    if (/<!doctype html>|<html[\s>]/i.test(input.html)) {
+        // Full document: inject css before </head> and js before </body>. The
+        // agent often passes a complete `<!doctype html>...` blob with css/js
+        // alongside; without this they're silently dropped and the variant ships
+        // unstyled and non-interactive. Falls back to appending to the end if
+        // the closing tag isn't found.
+        let doc = input.html;
+        if (style) {
+            if (/<\/head>/i.test(doc)) {
+                doc = doc.replace(/<\/head>/i, () => `${style}\n</head>`);
+            }
+            else {
+                doc += `\n${style}`;
+            }
+        }
+        if (script) {
+            if (/<\/body>/i.test(doc)) {
+                doc = doc.replace(/<\/body>/i, () => `${script}\n</body>`);
+            }
+            else {
+                doc += `\n${script}`;
+            }
+        }
+        return doc;
+    }
     return `<!doctype html>
 <html lang="en">
   <head>
@@ -2061,6 +2373,7 @@ const toActiveProjectContext = (projectContext) => {
     return {
         kind: 'fresh',
         workspacePath: projectContext.workspacePath,
+        workspaceRoot: projectContext.workspaceRoot,
         framework: projectContext.framework,
         designContext: projectContext.designContext?.map((entry) => entry.kind === 'slug'
             ? { kind: 'slug', slug: entry.slug }
@@ -2090,15 +2403,26 @@ const toActiveProjectContext = (projectContext) => {
  * 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:
+ * turned into a `design_context` artifact that links to Rivet-hosted
+ * DESIGN.md views:
  *   - `slug` entries resolve bundled catalog markdown via the design catalog.
  *   - `markdown` entries (Agent Browser / inspiration extractor output) carry
- *     their stored markdown verbatim.
+ *     their stored markdown when the linked route is requested.
  * Slots whose markdown can't be resolved are skipped so the UI never renders
  * a metadata-only DESIGN.md row.
  */
-const buildSessionArtifacts = (projectContext) => {
+const buildSessionArtifacts = (sessionId, projectContext) => {
+    const artifacts = buildResolvedDesignContextArtifacts(projectContext);
+    return artifacts.map(({ content: _content, ...artifact }) => ({
+        ...artifact,
+        rawUrl: buildDesignContextRawUrl(sessionId, artifact.id),
+        viewUrl: buildDesignContextViewUrl(sessionId, artifact.id),
+    }));
+};
+const findDesignContextArtifact = (projectContext, artifactId) => {
+    return buildResolvedDesignContextArtifacts(projectContext).find((artifact) => artifact.id === artifactId);
+};
+const buildResolvedDesignContextArtifacts = (projectContext) => {
     if (projectContext.kind !== 'fresh')
         return [];
     const designContext = projectContext.designContext;
@@ -2117,7 +2441,9 @@ const buildSessionArtifacts = (projectContext) => {
                 id: `design_context:${slot}:${entry.slug}`,
                 kind: 'design_context',
                 label: catalogEntry?.name ?? entry.slug,
-                ...(catalogEntry?.description ? { summary: catalogEntry.description } : {}),
+                ...(catalogEntry?.description
+                    ? { summary: catalogEntry.description }
+                    : {}),
                 status: 'ready',
                 source: 'static',
                 contentType: 'text/markdown',
@@ -2149,8 +2475,6 @@ const buildSessionArtifacts = (projectContext) => {
     });
 };
 const addDesignContextArtifact = (artifactsByContent, artifact) => {
-    if (!artifact.content)
-        return;
     const existing = artifactsByContent.get(artifact.content);
     if (existing) {
         existing.usedByVariantCount += 1;
@@ -2161,6 +2485,340 @@ const addDesignContextArtifact = (artifactsByContent, artifact) => {
         usedByVariantCount: 1,
     });
 };
+const buildDesignContextRawUrl = (sessionId, artifactId) => {
+    return `/api/variants/${encodeURIComponent(sessionId)}/${DESIGN_CONTEXT_ROUTE_SEGMENT}/${encodeURIComponent(artifactId)}`;
+};
+const buildDesignContextViewUrl = (sessionId, artifactId) => {
+    return `${buildDesignContextRawUrl(sessionId, artifactId)}/${DESIGN_CONTEXT_VIEW_SEGMENT}`;
+};
+const buildDesignContextViewerDocument = (artifact) => {
+    const title = `${artifact.label} DESIGN.md`;
+    const visualHtml = renderDesignMarkdown(artifact.content);
+    const rawMarkdown = escapeHtml(artifact.content);
+    return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>${escapeHtml(title)}</title>
+  <style>
+    :root {
+      color-scheme: light;
+      --ink: #201b16;
+      --muted: #75695e;
+      --paper: #fbf7ef;
+      --panel: #fffdf8;
+      --rule: #eadfcf;
+      --accent: #e45d2f;
+      --accent-soft: #ffe0d3;
+      --code: #2a2521;
+    }
+    * { box-sizing: border-box; }
+    body {
+      margin: 0;
+      min-height: 100vh;
+      background:
+        radial-gradient(circle at top left, rgba(228, 93, 47, 0.18), transparent 36rem),
+        linear-gradient(135deg, #fbf7ef 0%, #f2eadc 100%);
+      color: var(--ink);
+      font-family: ui-serif, Georgia, Cambria, "Times New Roman", serif;
+    }
+    main {
+      width: min(1440px, calc(100vw - 40px));
+      margin: 0 auto;
+      padding: 40px 0;
+    }
+    header {
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      gap: 24px;
+      margin-bottom: 24px;
+      border-bottom: 1px solid var(--rule);
+      padding-bottom: 18px;
+    }
+    h1 {
+      margin: 0;
+      max-width: 780px;
+      font-size: clamp(2rem, 5vw, 4.5rem);
+      letter-spacing: -0.06em;
+      line-height: 0.92;
+    }
+    .mode-input {
+      position: absolute;
+      opacity: 0;
+      pointer-events: none;
+    }
+    .mode-toggle {
+      display: inline-flex;
+      flex-shrink: 0;
+      gap: 4px;
+      border: 1px solid var(--rule);
+      border-radius: 999px;
+      background: rgba(255, 253, 248, 0.72);
+      padding: 4px;
+      box-shadow: 0 12px 30px rgba(61, 44, 26, 0.08);
+    }
+    .mode-toggle label {
+      position: relative;
+      cursor: pointer;
+      border-radius: 999px;
+      padding: 8px 14px;
+      color: var(--muted);
+      font: 600 0.74rem/1.2 ui-sans-serif, system-ui, sans-serif;
+      letter-spacing: 0.12em;
+      text-transform: uppercase;
+      transition:
+        background 160ms ease,
+        color 160ms ease;
+    }
+    .mode-toggle label:has(input:checked) {
+      background: var(--ink);
+      color: var(--paper);
+    }
+    .viewer {
+      display: block;
+    }
+    .viewer-panel {
+      display: none;
+    }
+    main:has(#designmd-visual-mode:checked) .visual-panel,
+    main:has(#designmd-raw-mode:checked) .raw-panel {
+      display: block;
+    }
+    .panel {
+      overflow: hidden;
+      border: 1px solid var(--rule);
+      border-radius: 18px;
+      background: color-mix(in srgb, var(--panel) 92%, white);
+      box-shadow: 0 20px 60px rgba(61, 44, 26, 0.12);
+    }
+    .panel-title {
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      border-bottom: 1px solid var(--rule);
+      padding: 12px 16px;
+      color: var(--muted);
+      font: 700 0.72rem/1 ui-sans-serif, system-ui, sans-serif;
+      letter-spacing: 0.12em;
+      text-transform: uppercase;
+    }
+    .visual {
+      padding: 24px;
+    }
+    .visual h1,
+    .visual h2,
+    .visual h3 {
+      margin: 1.3em 0 0.45em;
+      letter-spacing: -0.04em;
+      line-height: 1;
+    }
+    .visual h1:first-child,
+    .visual h2:first-child,
+    .visual h3:first-child {
+      margin-top: 0;
+    }
+    .visual h1 { font-size: 2.25rem; }
+    .visual h2 { font-size: 1.6rem; }
+    .visual h3 { font-size: 1.18rem; }
+    .visual p,
+    .visual li,
+    .visual blockquote {
+      color: #3d342c;
+      font-size: 1rem;
+      line-height: 1.62;
+    }
+    .visual ul {
+      display: grid;
+      gap: 8px;
+      padding-left: 1.1rem;
+    }
+    .visual blockquote {
+      margin: 18px 0;
+      border-left: 4px solid var(--accent);
+      padding-left: 14px;
+      color: var(--muted);
+    }
+    .visual code {
+      border-radius: 6px;
+      background: var(--accent-soft);
+      padding: 0.12rem 0.34rem;
+      font-family: ui-monospace, "SFMono-Regular", Menlo, Consolas, monospace;
+      font-size: 0.92em;
+    }
+    pre {
+      margin: 0;
+      max-height: calc(100vh - 190px);
+      overflow: auto;
+      background: #181512;
+      color: #f9ead7;
+      padding: 20px;
+      font: 0.78rem/1.55 ui-monospace, "SFMono-Regular", Menlo, Consolas, monospace;
+      white-space: pre-wrap;
+      word-break: break-word;
+    }
+    @media (max-width: 900px) {
+      main { width: min(100vw - 24px, 760px); padding: 24px 0; }
+      header { align-items: start; flex-direction: column; }
+      pre { max-height: 520px; }
+    }
+  </style>
+</head>
+<body>
+  <main>
+    <header>
+      <h1>${escapeHtml(title)}</h1>
+      <div class="mode-toggle" aria-label="DesignMD view mode">
+        <label>
+          <input class="mode-input" type="radio" name="designmd-view-mode" id="designmd-visual-mode" checked />
+          <span>Visual</span>
+        </label>
+        <label>
+          <input class="mode-input" type="radio" name="designmd-view-mode" id="designmd-raw-mode" />
+          <span>Raw</span>
+        </label>
+      </div>
+    </header>
+    <section class="viewer" aria-label="DesignMD artifact">
+      <article class="panel viewer-panel visual-panel" id="designmd-visual">
+        <div class="panel-title"><span>Visual</span><span>Rendered DESIGN.md</span></div>
+        <div class="visual">${visualHtml}</div>
+      </article>
+      <article class="panel viewer-panel raw-panel" id="designmd-raw">
+        <div class="panel-title"><span>Raw</span><span>Markdown source</span></div>
+        <pre>${rawMarkdown}</pre>
+      </article>
+    </section>
+  </main>
+</body>
+</html>`;
+};
+const renderDesignMarkdown = (markdown) => {
+    const lines = markdown.replace(/\r\n/g, '\n').split('\n');
+    const output = [];
+    const paragraph = [];
+    const listItems = [];
+    const codeLines = [];
+    let isCodeBlock = false;
+    const flushParagraph = () => {
+        if (paragraph.length === 0)
+            return;
+        output.push(`<p>${renderInlineMarkdown(paragraph.join(' '))}</p>`);
+        paragraph.length = 0;
+    };
+    const flushList = () => {
+        if (listItems.length === 0)
+            return;
+        output.push(`<ul>${listItems.map((item) => `<li>${renderInlineMarkdown(item)}</li>`).join('')}</ul>`);
+        listItems.length = 0;
+    };
+    const flushCode = () => {
+        if (codeLines.length === 0)
+            return;
+        output.push(`<pre>${escapeHtml(codeLines.join('\n'))}</pre>`);
+        codeLines.length = 0;
+    };
+    lines.forEach((line) => {
+        if (line.trim().startsWith('```')) {
+            if (isCodeBlock) {
+                flushCode();
+                isCodeBlock = false;
+                return;
+            }
+            flushParagraph();
+            flushList();
+            isCodeBlock = true;
+            return;
+        }
+        if (isCodeBlock) {
+            codeLines.push(line);
+            return;
+        }
+        const trimmed = line.trim();
+        if (!trimmed) {
+            flushParagraph();
+            flushList();
+            return;
+        }
+        if (/^---+$/.test(trimmed)) {
+            flushParagraph();
+            flushList();
+            output.push('<hr />');
+            return;
+        }
+        const headingMatch = trimmed.match(/^(#{1,6})\s+(.+)$/);
+        if (headingMatch) {
+            flushParagraph();
+            flushList();
+            const level = Math.min(headingMatch[1].length, 3);
+            output.push(`<h${level}>${renderInlineMarkdown(headingMatch[2])}</h${level}>`);
+            return;
+        }
+        const listMatch = trimmed.match(/^[-*]\s+(.+)$/);
+        if (listMatch) {
+            flushParagraph();
+            listItems.push(listMatch[1]);
+            return;
+        }
+        const quoteMatch = trimmed.match(/^>\s?(.+)$/);
+        if (quoteMatch) {
+            flushParagraph();
+            flushList();
+            output.push(`<blockquote>${renderInlineMarkdown(quoteMatch[1])}</blockquote>`);
+            return;
+        }
+        paragraph.push(trimmed);
+    });
+    flushCode();
+    flushParagraph();
+    flushList();
+    return output.join('\n');
+};
+const renderInlineMarkdown = (value) => {
+    return escapeHtml(value)
+        .replace(/\*\*([^*]+)\*\*/g, '<strong>$1</strong>')
+        .replace(/`([^`]+)`/g, '<code>$1</code>')
+        .replace(/\*([^*]+)\*/g, '<em>$1</em>');
+};
+const escapeHtml = (value) => {
+    return value
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+};
+/**
+ * Resolve a per-variant design context entry into the raw DESIGN.md markdown
+ * the worktree scaffolder writes, plus a small `designSource` descriptor for
+ * the variant manifest. Slug entries resolve through the bundled catalog;
+ * markdown entries (Agent Browser / inspiration extractor output) carry their
+ * stored markdown verbatim. Returns null when the entry is missing or the
+ * slug doesn't resolve to bundled markdown.
+ */
+const resolveDesignArtifact = (entry) => {
+    if (!entry)
+        return null;
+    if (entry.kind === 'markdown') {
+        return {
+            markdown: entry.content,
+            source: { kind: 'markdown', label: entry.label },
+        };
+    }
+    const markdown = (0, designCatalog_1.loadDesignSystemMarkdown)(entry.slug);
+    if (!markdown)
+        return null;
+    const catalogEntry = (0, designCatalog_1.getDesignSystemBySlug)(entry.slug);
+    return {
+        markdown,
+        source: {
+            kind: 'slug',
+            slug: entry.slug,
+            label: catalogEntry?.name ?? entry.slug,
+        },
+    };
+};
 const summarizeDesignContext = (designContext) => {
     if (!designContext)
         return null;