rivet-design 0.10.8 → 0.11.0

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

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AgentVariantsOrchestrator = void 0;
+exports.AgentVariantsOrchestrator = exports.defaultDesignCritiqueRunner = void 0;
 exports.buildStaticPreviewDocument = buildStaticPreviewDocument;
 const crypto_1 = require("crypto");
 const events_1 = require("events");
@@ -22,7 +22,10 @@ const viteReactTs_1 = require("../../services/templates/viteReactTs");
 const StaticPreviewServer_1 = require("../../services/StaticPreviewServer");
 const designCatalog_1 = require("../../services/templates/designCatalog");
 const previewQa_1 = require("./previewQa");
+const designCritique_1 = require("./designCritique");
+const diffQa_1 = require("./diffQa");
 const VariantHistoryService_1 = require("../../services/VariantHistoryService");
+const variantContext_1 = require("./variantContext");
 const log = (0, logger_1.createLogger)('AgentVariantsOrchestrator');
 const FRESH_DEV_SERVER_HOST = '127.0.0.1';
 // Fresh worktrees run the Vite React template, whose dev server defaults to
@@ -257,8 +260,126 @@ function copyAssetIntoWorktree(worktreePath, entry, assetSourceRoot) {
     fs_1.default.mkdirSync(path_1.default.dirname(absDest), { recursive: true });
     fs_1.default.copyFileSync(resolvedSource, absDest);
 }
-const defaultPreviewQaRunner = ({ html }) => (0, previewQa_1.runPreviewQa)({ html });
+const defaultPreviewQaRunner = ({ html, assetBase }) => (0, previewQa_1.runPreviewQa)({
+    html,
+    options: {
+        ...(assetBase ? { localAssetBasePath: assetBase } : {}),
+    },
+});
+/**
+ * Production design-critique runner backed by the real GatewayClient + a
+ * Playwright screenshot. Failure-tolerant: `runDesignCritique` degrades to a
+ * non-blocking skip on any render/model error.
+ */
+const defaultDesignCritiqueRunner = ({ target, designContextMarkdown, designContract, }) => (0, designCritique_1.runDesignCritique)({ target, designContextMarkdown, designContract });
+exports.defaultDesignCritiqueRunner = defaultDesignCritiqueRunner;
+/** Merge the structured critique fields (findings/checks/caps) onto a QA
+ *  verdict. Only attaches each field when the critique produced it. */
+const attachCritiqueDetail = (qa, outcome) => ({
+    ...qa,
+    ...(outcome.scores
+        ? {
+            dimensionScores: {
+                ...outcome.scores,
+                overall: outcome.overallScore ?? outcome.scores.overall,
+            },
+        }
+        : {}),
+    ...(outcome.summary ? { designSummary: outcome.summary } : {}),
+    ...(outcome.findings.length > 0 ? { designFindings: outcome.findings } : {}),
+    ...(outcome.checks ? { designChecks: outcome.checks } : {}),
+    ...(outcome.scoreCaps.length > 0
+        ? { designScoreCaps: outcome.scoreCaps }
+        : {}),
+});
+/** Merge passing design scores onto a base QA verdict (status unchanged). */
+const attachDesignScores = (base, outcome) => attachCritiqueDetail(base, outcome);
+const designScoreFragment = (outcome) => {
+    const score = outcome.overallScore ?? outcome.scores?.overall;
+    return score !== undefined ? `overall ${score.toFixed(1)}/10` : 'below bar';
+};
+/**
+ * Compose the actionable critique summary handed to a re-leased variant: the
+ * model's prose plus an explicit, prioritized fix list drawn from the
+ * critical/major findings so the agent knows exactly what to change.
+ */
+const buildRetryCritiqueSummary = (qa) => {
+    const base = qa.designSummary ?? qa.summary;
+    const actionable = (qa.designFindings ?? []).filter((f) => f.severity === 'critical' || f.severity === 'major');
+    if (actionable.length === 0)
+        return base;
+    const fixes = actionable
+        .map((f) => `- [${f.severity} ${f.category}] ${f.evidence} → ${f.fix}`)
+        .join('\n');
+    return `${base}\n\nMust fix before re-reporting:\n${fixes}`;
+};
+/** One-line, actionable summary of the worst findings for chip/prompt copy. */
+const findingsFragment = (outcome) => {
+    const ranked = outcome.findings.filter((f) => f.severity === 'critical' || f.severity === 'major');
+    if (ranked.length === 0)
+        return '';
+    const first = ranked[0];
+    const more = ranked.length > 1 ? ` (+${ranked.length - 1} more)` : '';
+    return `${first.severity} ${first.category}: ${first.evidence}${more}`;
+};
+/** Build a failed QA verdict for a below-bar variant (drives the re-lease). */
+const buildDesignFailureQa = (base, outcome) => {
+    const findings = findingsFragment(outcome);
+    const detail = findings || designScoreFragment(outcome);
+    return attachCritiqueDetail({
+        status: 'failed',
+        issues: [
+            ...base.issues,
+            {
+                kind: 'design_quality',
+                detail,
+                ...(outcome.summary ? { message: outcome.summary } : {}),
+            },
+        ],
+        summary: outcome.blocked
+            ? `Design critical: ${detail}.`
+            : `Design quality below bar (${detail}).`,
+        ...(base.checkedSource ? { checkedSource: base.checkedSource } : {}),
+    }, outcome);
+};
+/**
+ * Build a degraded (but committable) QA verdict for a variant that stayed
+ * below the bar after its one retry. Status is `passed` so commit stays
+ * enabled — the low score is surfaced via `dimensionScores`/`designSummary`
+ * rather than hard-blocking the user forever. Only used for non-critical
+ * failures; an unresolved critical hard-fails instead of degrading.
+ */
+const buildDegradedDesignQa = (base, outcome) => attachCritiqueDetail({
+    ...base,
+    status: 'passed',
+    summary: `Accepted with low design score (${designScoreFragment(outcome)}) after retry.`,
+}, outcome);
 const NOOP_TELEMETRY = { track: () => undefined };
+const DESIGN_CREATION_ACTION_RE = /\b(create|build|design|make|redesign|refresh|update)\b/i;
+const DESIGN_CREATION_SURFACE_RE = /\b(home\s?page|landing page|dashboard|screen|site|website|app|page|ui|interface|component|hero)\b/i;
+const NON_VISUAL_CHANGE_RE = /\b(api|backend|database|event|lint|query|server|test|tracking|typecheck)\b/i;
+const DIFF_CAPTURE_FAILURE_SUMMARY = 'Unable to verify the generated design diff; regenerate this variant so Rivet can confirm source changes.';
+const buildDiffCaptureFailureQa = (detail, message) => ({
+    status: 'failed',
+    issues: [
+        {
+            kind: 'design_quality',
+            detail,
+            message,
+        },
+    ],
+    summary: DIFF_CAPTURE_FAILURE_SUMMARY,
+});
+const isDesignCreationCodeGenInput = (input, prompt) => {
+    const codeGenInput = input;
+    const text = [prompt, codeGenInput?.briefLabel, codeGenInput?.briefBody]
+        .filter((value) => typeof value === 'string')
+        .join('\n');
+    if (NON_VISUAL_CHANGE_RE.test(text))
+        return false;
+    return (DESIGN_CREATION_ACTION_RE.test(text) &&
+        DESIGN_CREATION_SURFACE_RE.test(text));
+};
 /**
  * Wraps SessionStore for the operations that have side effects: approve
  * (provision worktrees), reportComplete (capture diff + auto-enqueue to
@@ -280,6 +401,7 @@ class AgentVariantsOrchestrator {
     installDependencies;
     materializeProject;
     previewQaRunner;
+    designCritiqueRunner;
     switchPreviewPort;
     setCommittedDevServerHealth;
     variantHistory;
@@ -323,6 +445,7 @@ class AgentVariantsOrchestrator {
         this.materializeProject =
             deps.materializeProject ?? defaultMaterializeProject;
         this.previewQaRunner = deps.previewQaRunner ?? defaultPreviewQaRunner;
+        this.designCritiqueRunner = deps.designCritiqueRunner;
         this.switchPreviewPort = deps.switchPreviewPort;
         this.setCommittedDevServerHealth = deps.setCommittedDevServerHealth;
         this.variantHistory = deps.variantHistory ?? new VariantHistoryService_1.VariantHistoryService();
@@ -450,6 +573,10 @@ class AgentVariantsOrchestrator {
     }
     reportBriefs(args) {
         const result = this.store.reportBriefs(args);
+        const projectContext = this.store.getProjectContext(args.sessionId);
+        if (projectContext.variantContext) {
+            (0, variantContext_1.writeVariantContextBundle)(projectContext.variantContext);
+        }
         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?.({
@@ -463,13 +590,25 @@ class AgentVariantsOrchestrator {
     }
     reportSourcePlan(args) {
         const result = this.store.reportSourcePlan(args);
-        this.telemetry.trackAgentVariantsSourceContextQuality?.({
-            sessionId: args.sessionId,
-            sourceUrlCount: args.sourcePlan.sourceIntent.sources.length,
-            artifactCount: args.sourcePlan.sourceContext.sourceFindings.length,
-            hasScreenshotReferences: (args.sourcePlan.sourceContext.screenshotReferences?.length ?? 0) > 0,
-            preserveBrand: args.sourcePlan.sourceContext.sourceRoles.some((entry) => entry.role === 'primary'),
-        });
+        const projectContext = this.store.getProjectContext(args.sessionId);
+        if (projectContext.variantContext) {
+            (0, variantContext_1.writeVariantContextBundle)(projectContext.variantContext);
+        }
+        // Source-context quality is now measured off the raw context bundle plus
+        // the action metadata the agent reported, not the legacy summary fields.
+        const bundle = projectContext.kind === 'fresh'
+            ? projectContext.variantContext
+            : undefined;
+        if (args.sourcePlan.metadata.length > 0 || bundle) {
+            this.telemetry.trackAgentVariantsSourceContextQuality?.({
+                sessionId: args.sessionId,
+                sourceUrlCount: bundle?.userContext.filter((source) => source.transport === 'url')
+                    .length ?? 0,
+                artifactCount: args.sourcePlan.metadata.length,
+                hasScreenshotReferences: false,
+                preserveBrand: false,
+            });
+        }
         this.emitChange();
         return result;
     }
@@ -586,6 +725,9 @@ class AgentVariantsOrchestrator {
     getStage(sessionId) {
         return this.store.getStage(sessionId);
     }
+    getWorkItemInput(sessionId, workItemId) {
+        return this.store.getWorkItemInput(sessionId, workItemId);
+    }
     getBriefs(sessionId) {
         return this.store.getBriefs(sessionId);
     }
@@ -877,18 +1019,14 @@ class AgentVariantsOrchestrator {
         const projectContext = args.projectContext ?? {
             kind: 'existing',
         };
-        const sourceContext = projectContext.kind === 'fresh'
-            ? projectContext.sourceContext
-            : undefined;
-        const isSourceGrounded = Boolean(sourceContext?.sourceUrls?.length) ||
-            Boolean(sourceContext?.sourceArtifacts?.length) ||
-            Boolean(sourceContext?.sourceIntent) ||
-            Boolean(sourceContext?.artifact);
+        // Fresh source-grounded sessions (a captured context bundle on a fresh
+        // project) must run through `propose` so the source-research/source_plan
+        // flow gates generation; start_variants routes them there before reaching
+        // here, so this guard is an internal invariant. Existing-project sessions
+        // keep the single-call path even with a bundle — they have no source_plan
+        // stage, and the bundle's raw context is threaded straight into code_gen.
+        const isSourceGrounded = projectContext.kind === 'fresh' && Boolean(projectContext.variantContext);
         if (isSourceGrounded) {
-            // startUnified is the single-call path; source-grounded sessions must
-            // run through `propose` so the source-research flow gates generation.
-            // start_variants routes them there before reaching here — this guard is
-            // an internal invariant, not a user-facing dead end.
             throw new errors_1.AgentVariantsError('INVALID_STAGE_ACTION', 'Source-grounded sessions must run through the source-research flow (propose), not the single-call startUnified path.');
         }
         const proposeResult = this.propose({
@@ -897,6 +1035,7 @@ class AgentVariantsOrchestrator {
             target: args.target,
             projectContext,
             runLabel: args.runLabel,
+            ...(args.sessionId ? { sessionId: args.sessionId } : {}),
         });
         if (proposeResult.stage !== 'awaiting_briefs' ||
             !proposeResult.briefWorkItem) {
@@ -1005,10 +1144,15 @@ class AgentVariantsOrchestrator {
         // verdict converts the report to `failed` with code `VARIANT_QA_FAILED`
         // so the variant never reaches `ready` and `getVariants` can disable
         // its commit action.
-        const qaOverride = workItemKind === 'refine_variant'
+        const qaEval = workItemKind === 'refine_variant'
             ? null
             : await this.evaluateQaForReport(args);
-        let effectiveArgs = qaOverride?.overrideArgs ?? args;
+        // A `retry` verdict re-leases the variant for one aesthetic regeneration
+        // instead of recording success — short-circuit the normal record path.
+        if (qaEval?.decision === 'retry') {
+            return this.handleDesignCritiqueRetry(args, qaEval.qa);
+        }
+        let effectiveArgs = qaEval?.decision === 'fail_terminal' ? qaEval.overrideArgs : args;
         // For a successful refine_variant, swap the refined static preview into
         // place and persist history BEFORE recording success in the store. This
         // keeps the user-visible `refinement.status: succeeded` (and the snapshot
@@ -1928,7 +2072,6 @@ class AgentVariantsOrchestrator {
                 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');
@@ -1950,7 +2093,7 @@ class AgentVariantsOrchestrator {
         // 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);
+        const paths = await createFresh.call(this.worktrees, sessionId, codeGenIds.length, viteReactTs_1.VITE_REACT_TS_TEMPLATE, designContext, destinationParent);
         resources.scaffoldBaseWorkItemId = scaffoldId;
         resources.freshDestinationParent = destinationParent;
         // Each code_gen item maps 1:1 to a fresh worktree. The scaffold_base
@@ -2088,42 +2231,196 @@ class AgentVariantsOrchestrator {
             return null;
         if (!this.store.hasSession(args.sessionId))
             return null;
-        if (this.store.getWorkItemKind(args.sessionId, args.workItemId) !==
-            'static_preview') {
+        const projectContext = this.store.getProjectContext(args.sessionId);
+        const kind = this.store.getWorkItemKind(args.sessionId, args.workItemId);
+        // Existing-project code_gen has no preview document for browser QA. It
+        // still gets a cheap task-fit sanity check for design/creation requests so
+        // deletion-only "successes" cannot pass as generated UI.
+        if (projectContext.kind !== 'fresh') {
+            if (kind === 'code_gen') {
+                return this.evaluateExistingCodeGenQa(args);
+            }
             return null;
         }
-        const projectContext = this.store.getProjectContext(args.sessionId);
-        if (projectContext.kind !== 'fresh')
+        // Resolve the objective base QA (static_preview only) and the design
+        // critique render target for this deliverable kind.
+        let baseQa = null;
+        let critiqueTarget = null;
+        let checkedSource;
+        if (kind === 'static_preview') {
+            const parsed = parseStaticPreviewOutput(normalizeOutput(args.output));
+            if (!parsed)
+                return null;
+            const assetBase = resolveStaticPreviewAssetBase({
+                assetBase: parsed.assetBase,
+                projectContext,
+            });
+            baseQa = await this.runPreviewQaSafely(args, parsed.html, assetBase);
+            critiqueTarget = {
+                kind: 'html',
+                html: buildStaticPreviewDocument({ html: parsed.html }),
+                ...(assetBase ? { assetBase } : {}),
+            };
+        }
+        else if (kind === 'code_gen') {
+            // Fresh vite_app variants run agent-authored dev-server code. Do not
+            // navigate or request that server from the critique sandbox.
             return null;
-        const parsed = parseStaticPreviewOutput(normalizeOutput(args.output));
-        if (!parsed)
+        }
+        else {
             return null;
-        let qa;
+        }
+        // Objective base QA failure is terminal exactly as before — never run the
+        // aesthetic critique on a variant that's already broken.
+        if (baseQa && baseQa.status === 'failed') {
+            this.memoizeQa(args.sessionId, args.workItemId, baseQa);
+            return {
+                decision: 'fail_terminal',
+                qa: baseQa,
+                overrideArgs: {
+                    ...args,
+                    status: 'failed',
+                    error: { code: 'VARIANT_QA_FAILED', message: baseQa.summary },
+                },
+            };
+        }
+        // Synthesize a passing base verdict for vite_app (no objective layer).
+        const passedBase = baseQa ?? {
+            status: 'passed',
+            issues: [],
+            summary: 'Preview QA passed — dev server reachable.',
+            checkedSource,
+        };
+        // No design critique wired → behave exactly like objective-only QA.
+        if (!this.designCritiqueRunner) {
+            this.memoizeQa(args.sessionId, args.workItemId, passedBase);
+            return { decision: 'pass', qa: passedBase };
+        }
+        const outcome = await this.runDesignCritiqueSafely({
+            sessionId: args.sessionId,
+            workItemId: args.workItemId,
+            target: critiqueTarget,
+        });
+        // Critique skipped (render/model unavailable) → non-blocking, keep base.
+        if (!outcome.ran) {
+            this.memoizeQa(args.sessionId, args.workItemId, passedBase);
+            return { decision: 'pass', qa: passedBase };
+        }
+        if (outcome.passed) {
+            const qa = attachDesignScores(passedBase, outcome);
+            this.memoizeQa(args.sessionId, args.workItemId, qa);
+            return { decision: 'pass', qa };
+        }
+        // Below the bar. First failure → re-lease for one regeneration.
+        const resources = this.ensureResources(args.sessionId);
+        if (!resources.designCritiqueRetried.has(args.workItemId)) {
+            const qa = buildDesignFailureQa(passedBase, outcome);
+            return { decision: 'retry', qa };
+        }
+        // Retry already spent. A `critical` finding is a hard gate: an unusable
+        // variant must fail terminally (commit disabled) rather than degrade into
+        // a committable accept — a high vibe/brand score can never carry it past a
+        // usability-breaking defect. Non-critical (score- or major-driven) failures
+        // degrade to committable so a single fixable flaw doesn't reject a
+        // promising 0→1 direction forever.
+        if (outcome.blocked) {
+            const qa = buildDesignFailureQa(passedBase, outcome);
+            this.memoizeQa(args.sessionId, args.workItemId, qa);
+            return {
+                decision: 'fail_terminal',
+                qa,
+                overrideArgs: {
+                    ...args,
+                    status: 'failed',
+                    error: { code: 'VARIANT_QA_FAILED', message: qa.summary },
+                },
+            };
+        }
+        const qa = buildDegradedDesignQa(passedBase, outcome);
+        this.memoizeQa(args.sessionId, args.workItemId, qa);
+        return { decision: 'degrade', qa };
+    }
+    async evaluateExistingCodeGenQa(args) {
+        const input = this.store.getWorkItemInput(args.sessionId, args.workItemId);
+        if (!isDesignCreationCodeGenInput(input, this.store.getPrompt(args.sessionId))) {
+            return null;
+        }
+        const resources = this.resources.get(args.sessionId);
+        const record = resources?.worktrees.get(args.workItemId);
+        if (!record) {
+            const qa = buildDiffCaptureFailureQa('diff:worktree-record-missing', 'The succeeded report could not be checked because its worktree record is missing.');
+            this.memoizeQa(args.sessionId, args.workItemId, qa);
+            return {
+                decision: 'fail_terminal',
+                qa,
+                overrideArgs: {
+                    ...args,
+                    status: 'failed',
+                    error: { code: 'VARIANT_QA_FAILED', message: qa.summary },
+                },
+            };
+        }
+        let diff;
         try {
-            qa = await this.previewQaRunner({
-                sessionId: args.sessionId,
-                workItemId: args.workItemId,
-                html: parsed.html,
-            });
+            diff = await this.worktrees.getDiff(record.worktreePath);
+            record.diff = diff;
         }
         catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            qa = {
+            log.warn(`getDiff failed for ${record.worktreePath}`, err);
+            const qa = buildDiffCaptureFailureQa('diff:unavailable', 'The succeeded report could not be checked because diff capture failed.');
+            this.memoizeQa(args.sessionId, args.workItemId, qa);
+            return {
+                decision: 'fail_terminal',
+                qa,
+                overrideArgs: {
+                    ...args,
+                    status: 'failed',
+                    error: { code: 'VARIANT_QA_FAILED', message: qa.summary },
+                },
+            };
+        }
+        const addedContentLines = (0, diffQa_1.countAddedContentDiffLines)(diff);
+        const hasVisualImplementation = (0, diffQa_1.hasVisualImplementationDiff)(diff);
+        if ((0, diffQa_1.hasMarkdownInlineStyleDiff)(diff)) {
+            const qa = {
                 status: 'failed',
                 issues: [
                     {
-                        kind: 'preview_unavailable',
-                        detail: 'qa_runner_error',
-                        message,
+                        kind: 'design_quality',
+                        detail: 'diff:mdx-inline-style',
+                        message: 'The succeeded report added an inline <style> block inside Markdown/MDX, which can cause Next/Nextra hydration mismatches.',
                     },
                 ],
-                summary: `Preview QA runner threw: ${message}`,
+                summary: 'Inline <style> blocks in Markdown/MDX can break hydration; move styling into a stylesheet or component file.',
+            };
+            this.memoizeQa(args.sessionId, args.workItemId, qa);
+            return {
+                decision: 'fail_terminal',
+                qa,
+                overrideArgs: {
+                    ...args,
+                    status: 'failed',
+                    error: { code: 'VARIANT_QA_FAILED', message: qa.summary },
+                },
             };
         }
-        const resources = this.ensureResources(args.sessionId);
-        resources.qaResults.set(args.workItemId, qa);
-        if (qa.status === 'failed') {
+        if (hasVisualImplementation)
+            return null;
+        if (addedContentLines > 0) {
+            const qa = {
+                status: 'failed',
+                issues: [
+                    {
+                        kind: 'design_quality',
+                        detail: 'diff:no-visual-implementation',
+                        message: 'The succeeded report added content but did not add styling, components, or structured markup for the requested design.',
+                    },
+                ],
+                summary: 'No visual implementation was added for this design variant; regenerate it with real layout, styling, or component changes.',
+            };
+            this.memoizeQa(args.sessionId, args.workItemId, qa);
             return {
+                decision: 'fail_terminal',
                 qa,
                 overrideArgs: {
                     ...args,
@@ -2132,7 +2429,230 @@ class AgentVariantsOrchestrator {
                 },
             };
         }
-        return { qa };
+        const qa = {
+            status: 'failed',
+            issues: [
+                {
+                    kind: 'design_quality',
+                    detail: 'diff:no-added-content',
+                    message: 'The succeeded report did not add any source content for the requested design.',
+                },
+            ],
+            summary: 'No generated content was added for this design variant; regenerate it with real homepage UI changes.',
+        };
+        this.memoizeQa(args.sessionId, args.workItemId, qa);
+        return {
+            decision: 'fail_terminal',
+            qa,
+            overrideArgs: {
+                ...args,
+                status: 'failed',
+                error: { code: 'VARIANT_QA_FAILED', message: qa.summary },
+            },
+        };
+    }
+    /** Run the injected preview QA runner, converting a thrown runner into a
+     *  failed `VariantQaResult` (mirrors the prior inline behavior). */
+    async runPreviewQaSafely(args, html, assetBase) {
+        try {
+            return await this.previewQaRunner({
+                sessionId: args.sessionId,
+                workItemId: args.workItemId,
+                html,
+                ...(assetBase ? { assetBase } : {}),
+            });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                status: 'failed',
+                issues: [
+                    { kind: 'preview_unavailable', detail: 'qa_runner_error', message },
+                ],
+                summary: `Preview QA runner threw: ${message}`,
+            };
+        }
+    }
+    /** Run the injected design critique runner; a thrown runner degrades to a
+     *  non-blocking skip so the aesthetic layer can never break the gate. */
+    async runDesignCritiqueSafely(args) {
+        try {
+            const designContextMarkdown = this.resolveBoundDesignMarkdown(args.sessionId, args.workItemId);
+            const designContract = this.resolveDesignContract(args.sessionId, args.workItemId);
+            return await this.designCritiqueRunner({
+                sessionId: args.sessionId,
+                workItemId: args.workItemId,
+                target: args.target,
+                designContextMarkdown,
+                designContract,
+            });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            log.warn(`Design critique runner threw for ${args.sessionId}/${args.workItemId}: ${message}`);
+            return {
+                ran: false,
+                passed: true,
+                blocked: false,
+                findings: [],
+                scoreCaps: [],
+                skippedReason: `runner: ${message}`,
+            };
+        }
+    }
+    /** Resolve the DESIGN.md markdown bound to a variant work item, if any. */
+    resolveBoundDesignMarkdown(sessionId, workItemId) {
+        try {
+            const input = this.store.getWorkItemInput(sessionId, workItemId);
+            return resolveDesignArtifact(input.designContextEntry)?.markdown;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * Derive the task contract (artifact type + explicit requirements) for a
+     * variant from the session prompt and the variant's brief body, so the
+     * critique judges the variant against what was actually requested. Returns
+     * undefined when no request copy is available.
+     */
+    resolveDesignContract(sessionId, workItemId) {
+        try {
+            const prompt = this.store.getPrompt(sessionId);
+            const input = this.store.getWorkItemInput(sessionId, workItemId);
+            const contract = (0, designCritique_1.buildDesignContract)({
+                prompt,
+                brief: input.briefBody,
+            });
+            if (contract.requirements.length === 0)
+                return undefined;
+            return contract;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    memoizeQa(sessionId, workItemId, qa) {
+        this.ensureResources(sessionId).qaResults.set(workItemId, qa);
+    }
+    /**
+     * Handle a `retry` QA verdict: consume the agent's report, re-open the
+     * variant work item so it can be re-leased and regenerated against the
+     * critique, and record that it has now used its single retry.
+     */
+    async handleDesignCritiqueRetry(args, qa) {
+        const resources = this.ensureResources(args.sessionId);
+        const result = this.store.requeueForDesignCritique({
+            sessionId: args.sessionId,
+            workItemId: args.workItemId,
+            leaseId: args.leaseId,
+            attempt: args.attempt,
+            critique: {
+                summary: buildRetryCritiqueSummary(qa),
+                dimensionScores: qa.dimensionScores,
+            },
+        });
+        resources.designCritiqueRetried.add(args.workItemId);
+        resources.qaResults.delete(args.workItemId);
+        this.telemetry.track('agent_variants.variant_design_requeued', {
+            source: 'mcp',
+            sessionId: args.sessionId,
+            workItemId: args.workItemId,
+            attempt: args.attempt,
+            overall: qa.dimensionScores?.overall ?? null,
+        });
+        this.emitChange();
+        return result;
+    }
+    async startVariantDevServer(args) {
+        if (args.record.port !== undefined && args.record.devServerProcess) {
+            return args.record.port;
+        }
+        // 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.
+        //
+        // Pick a sensible port near the framework's default (3000 for Next, 5173
+        // for Vite) and inject it via PORT + the CLI flag (see buildDevServerCommand)
+        // so the server actually binds it — that's what moves a preview off a port
+        // the user's own dev server already holds instead of colliding on it. On a
+        // retry we scan past the port we just tried, so a transient race or a
+        // briefly-held port resolves onto the next free one.
+        const startPort = await this.resolveDevServerStartPort(args.sessionId, args.isFresh);
+        let scanFrom = startPort;
+        const maxAttempts = 2;
+        for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+            let port;
+            try {
+                port = await this.worktrees.findFreePortFrom(scanFrom);
+                const dev = await this.resolveDevServer(args.sessionId, args.workItemId, args.record.worktreePath, port, args.isFresh);
+                const proc = await this.worktrees.startDevServer(dev.cwd, port, dev.cmd, dev.args, dev.env);
+                args.record.port = port;
+                args.record.devServerProcess = proc;
+                // If the dev server dies on its own (crash, OOM, Vite hard-fail),
+                // clear the port so the iframe stops routing the chip onto a dead
+                // socket. Without this the proxy retargets onto an unreachable port
+                // and the chip shows "upstream_unreachable" instead of the accurate
+                // "Preview is unavailable for this variant".
+                proc.once('exit', (code, signal) => {
+                    if (args.record.devServerProcess !== proc)
+                        return;
+                    args.record.port = undefined;
+                    args.record.devServerProcess = undefined;
+                    log.warn(`Variant ${args.workItemId} dev server exited unexpectedly (code=${code ?? 'null'}, signal=${signal ?? 'null'}); preview disabled`);
+                    this.emitChange();
+                });
+                this.emitChange();
+                trackFreshDevServerStarted(this.telemetry, {
+                    sessionId: args.sessionId,
+                    variantId: args.workItemId,
+                    port,
+                });
+                log.info(`Variant ${args.workItemId} dev server up on port ${port} (worktree ${args.record.worktreePath}; cmd: ${dev.cmd} ${dev.args.join(' ')})`);
+                return port;
+            }
+            catch (err) {
+                const portInUse = (0, devServerError_1.isDevServerStartError)(err) && err.portInUse;
+                const reason = (0, devServerError_1.isDevServerStartError)(err) ? err.reason : 'unknown';
+                const willRetry = portInUse && attempt < maxAttempts;
+                // Next attempt scans past the port we just tried so we don't re-pick a
+                // port that's persistently held (vs. a transient race that freed it).
+                scanFrom = (port ?? scanFrom) + 1;
+                log.warn(`Failed to start dev server for variant ${args.workItemId} on port ${port ?? 'unallocated'} ` +
+                    `(attempt ${attempt}/${maxAttempts}, reason=${reason}, portInUse=${portInUse})` +
+                    (willRetry
+                        ? '; retrying on a fresh port'
+                        : '; live preview disabled for this variant'), err);
+                if (willRetry)
+                    continue;
+                // Record the failure so getVariants can tell the UI this direction's
+                // preview couldn't start (and why), then push a snapshot so the chip
+                // updates from "loading" to the accurate per-direction message.
+                this.resources
+                    .get(args.sessionId)
+                    ?.previewFailures.set(args.workItemId, {
+                    reason,
+                    portInUse,
+                });
+                trackFreshDevServerFailed(this.telemetry, {
+                    sessionId: args.sessionId,
+                    variantId: args.workItemId,
+                    errorCode: 'DEV_SERVER_START_FAILED',
+                    reason,
+                    portInUse,
+                });
+                this.emitChange();
+                return undefined;
+            }
+            finally {
+                // Hand the reservation back whether the dev server bound the port
+                // (now visible to the listener check, so the reservation is redundant),
+                // it failed (port free again), or we're about to retry on the next port.
+                if (port !== undefined)
+                    this.worktrees.releasePort?.(port);
+            }
+        }
+        return undefined;
     }
     async handleSucceededReport(args) {
         const { sessionId, workItemId } = args;
@@ -2228,7 +2748,8 @@ class AgentVariantsOrchestrator {
         const projectContext = this.store.getProjectContext(sessionId);
         const isFresh = projectContext.kind === 'fresh';
         try {
-            record.diff = await this.worktrees.getDiff(record.worktreePath);
+            record.diff =
+                record.diff ?? (await this.worktrees.getDiff(record.worktreePath));
             log.info(`Variant ${workItemId} diff captured (${countDiffFiles(record.diff)} files)`);
             this.emitChange();
         }
@@ -2278,88 +2799,12 @@ class AgentVariantsOrchestrator {
                 return;
             }
         }
-        // Bring up a dev server in the variant's worktree so the user can cycle
-        // through live variants in the iframe via the chip. Failures here are
-        // logged but non-fatal — the user can still pick by reading the diff.
-        //
-        // Pick a sensible port near the framework's default (3000 for Next, 5173
-        // for Vite) and inject it via PORT + the CLI flag (see buildDevServerCommand)
-        // so the server actually binds it — that's what moves a preview off a port
-        // the user's own dev server already holds instead of colliding on it. On a
-        // retry we scan past the port we just tried, so a transient race or a
-        // briefly-held port resolves onto the next free one.
-        const startPort = await this.resolveDevServerStartPort(sessionId, isFresh);
-        let scanFrom = startPort;
-        const maxAttempts = 2;
-        for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-            let port;
-            try {
-                port = await this.worktrees.findFreePortFrom(scanFrom);
-                const dev = await this.resolveDevServer(sessionId, record.worktreePath, port, isFresh);
-                const proc = await this.worktrees.startDevServer(dev.cwd, port, dev.cmd, dev.args, dev.env);
-                record.port = port;
-                record.devServerProcess = proc;
-                // If the dev server dies on its own (crash, OOM, Vite hard-fail),
-                // clear the port so the iframe stops routing the chip onto a dead
-                // socket. Without this the proxy retargets onto an unreachable port
-                // and the chip shows "upstream_unreachable" instead of the accurate
-                // "Preview is unavailable for this variant".
-                proc.once('exit', (code, signal) => {
-                    if (record.devServerProcess !== proc)
-                        return;
-                    record.port = undefined;
-                    record.devServerProcess = undefined;
-                    log.warn(`Variant ${workItemId} dev server exited unexpectedly (code=${code ?? 'null'}, signal=${signal ?? 'null'}); preview disabled`);
-                    this.emitChange();
-                });
-                this.emitChange();
-                trackFreshDevServerStarted(this.telemetry, {
-                    sessionId,
-                    variantId: workItemId,
-                    port,
-                });
-                log.info(`Variant ${workItemId} dev server up on port ${port} (worktree ${record.worktreePath}; cmd: ${dev.cmd} ${dev.args.join(' ')})`);
-                return;
-            }
-            catch (err) {
-                const portInUse = (0, devServerError_1.isDevServerStartError)(err) && err.portInUse;
-                const reason = (0, devServerError_1.isDevServerStartError)(err) ? err.reason : 'unknown';
-                const willRetry = portInUse && attempt < maxAttempts;
-                // Next attempt scans past the port we just tried so we don't re-pick a
-                // port that's persistently held (vs. a transient race that freed it).
-                scanFrom = (port ?? scanFrom) + 1;
-                log.warn(`Failed to start dev server for variant ${workItemId} on port ${port ?? 'unallocated'} ` +
-                    `(attempt ${attempt}/${maxAttempts}, reason=${reason}, portInUse=${portInUse})` +
-                    (willRetry
-                        ? '; retrying on a fresh port'
-                        : '; live preview disabled for this variant'), err);
-                if (willRetry)
-                    continue;
-                // Record the failure so getVariants can tell the UI this direction's
-                // preview couldn't start (and why), then push a snapshot so the chip
-                // updates from "loading" to the accurate per-direction message.
-                this.resources.get(sessionId)?.previewFailures.set(workItemId, {
-                    reason,
-                    portInUse,
-                });
-                trackFreshDevServerFailed(this.telemetry, {
-                    sessionId,
-                    variantId: workItemId,
-                    errorCode: 'DEV_SERVER_START_FAILED',
-                    reason,
-                    portInUse,
-                });
-                this.emitChange();
-                return;
-            }
-            finally {
-                // Hand the reservation back whether the dev server bound the port
-                // (now visible to the listener check, so the reservation is redundant),
-                // it failed (port free again), or we're about to retry on the next port.
-                if (port !== undefined)
-                    this.worktrees.releasePort?.(port);
-            }
-        }
+        await this.startVariantDevServer({
+            sessionId,
+            workItemId,
+            record,
+            isFresh,
+        });
     }
     async handleStaticPreviewRefinement(args) {
         const resources = this.resources.get(args.sessionId);
@@ -2599,6 +3044,7 @@ class AgentVariantsOrchestrator {
         }
         else if (staticPreview) {
             tmpStagingDir = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), `rivet-variant-${args.workItemId}-`));
+            copyStaticPreviewDirectory(staticPreview.assetBase, tmpStagingDir);
             // Read the materialized index.html from the variant's per-variant dir.
             let stagedHtml = '';
             try {
@@ -2811,7 +3257,7 @@ class AgentVariantsOrchestrator {
      * 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) {
+    async resolveDevServer(sessionId, workItemId, worktreePath, port, isFresh) {
         if (isFresh) {
             return {
                 cwd: worktreePath,
@@ -2829,7 +3275,20 @@ class AgentVariantsOrchestrator {
             };
         }
         const env = await this.resolveEnv(sessionId);
-        const cwd = await this.worktrees.getProjectCwdInWorktree(worktreePath);
+        const cwd = await this.resolveExistingProjectCwd(sessionId, worktreePath, env);
+        const packageManager = detectPackageManagerForCwd(cwd, env.packageManager);
+        await this.ensureExistingProjectDependencies({
+            sessionId,
+            workItemId,
+            cwd,
+            packageManager,
+        });
+        if (packageManager !== env.packageManager) {
+            return {
+                cwd,
+                ...buildExistingProjectDevCommand(packageManager, env.devCommand, port),
+            };
+        }
         if (env.buildDevCommand) {
             return { cwd, ...env.buildDevCommand(port) };
         }
@@ -2840,6 +3299,44 @@ class AgentVariantsOrchestrator {
             env: { PORT: String(port) },
         };
     }
+    /**
+     * Existing-project variants usually reuse the user's installed
+     * node_modules. Nested example projects may be standalone packages with no
+     * install in the cloned worktree; install only when the package has no
+     * node_modules so normal user projects are not penalized.
+     */
+    async ensureExistingProjectDependencies(args) {
+        const packageJsonPath = path_1.default.join(args.cwd, 'package.json');
+        const nodeModulesPath = path_1.default.join(args.cwd, 'node_modules');
+        if (!fs_1.default.existsSync(packageJsonPath) || fs_1.default.existsSync(nodeModulesPath)) {
+            return;
+        }
+        await this.installDependencies(args.cwd, args.packageManager);
+    }
+    /**
+     * Resolve the dev-server working directory for an existing-project variant.
+     * WorktreeManager is constructed around the editor/root project, but
+     * `start_variants` can target a nested app (for example `examples/blog`).
+     * In that case the worktree root is still the git root clone, while the dev
+     * server must run from the nested project path.
+     */
+    async resolveExistingProjectCwd(sessionId, worktreePath, env) {
+        const fallback = await this.worktrees.getProjectCwdInWorktree(worktreePath);
+        try {
+            const projectContext = this.store.getProjectContext(sessionId);
+            if (projectContext.kind !== 'existing' || !projectContext.projectPath) {
+                return fallback;
+            }
+            const rel = path_1.default.relative(path_1.default.resolve(env.projectPath), path_1.default.resolve(projectContext.projectPath));
+            if (!rel || rel.startsWith('..') || path_1.default.isAbsolute(rel)) {
+                return fallback;
+            }
+            return path_1.default.join(worktreePath, rel);
+        }
+        catch {
+            return fallback;
+        }
+    }
     /**
      * After the chosen variant has been renamed into `destinationPath`, move
      * each unchosen sibling worktree into a `<destinationParent>/<slug>-variants/NN-<label>/`
@@ -3266,6 +3763,7 @@ class AgentVariantsOrchestrator {
                 startedAt: Date.now(),
                 leasedAt: new Map(),
                 qaResults: new Map(),
+                designCritiqueRetried: new Set(),
                 previewFailures: new Map(),
                 vitePreservedSiblings: false,
             };
@@ -3490,8 +3988,27 @@ const enrichDesignSource = (design) => {
     };
 };
 const toActiveProjectContext = (projectContext) => {
+    // Source count + grounding are derived purely from the read-only context
+    // bundle now that `sourceContext` intake is gone.
+    const sourceCount = projectContext.variantContext?.userContext.filter((source) => source.transport !== 'prompt').length ?? 0;
+    const hasSourceContextSummary = Boolean(sourceCount > 0 ||
+        (projectContext.variantContext?.rivetMetadata.length ?? 0) > 0);
+    const activeSourceContext = hasSourceContextSummary
+        ? {
+            sourceCount,
+            isSourceGrounded: Boolean(sourceCount > 0 ||
+                projectContext.designContext?.length ||
+                projectContext.variantContext?.rivetMetadata.length),
+        }
+        : undefined;
     if (projectContext.kind === 'existing') {
-        return { kind: 'existing' };
+        return {
+            kind: 'existing',
+            designContext: projectContext.designContext?.map((entry) => entry.kind === 'slug'
+                ? { kind: 'slug', slug: entry.slug }
+                : { kind: 'markdown', label: entry.label }),
+            ...(activeSourceContext ? { sourceContext: activeSourceContext } : {}),
+        };
     }
     return {
         kind: 'fresh',
@@ -3501,14 +4018,7 @@ const toActiveProjectContext = (projectContext) => {
         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),
-                },
-            }
-            : {}),
+        ...(activeSourceContext ? { sourceContext: activeSourceContext } : {}),
         ...(projectContext.executionPlan
             ? {
                 executionPlan: {
@@ -3546,8 +4056,6 @@ const findDesignContextArtifact = (projectContext, artifactId) => {
     return buildResolvedDesignContextArtifacts(projectContext).find((artifact) => artifact.id === artifactId);
 };
 const buildResolvedDesignContextArtifacts = (projectContext) => {
-    if (projectContext.kind !== 'fresh')
-        return [];
     const designContext = projectContext.designContext;
     if (!designContext || designContext.length === 0)
         return [];
@@ -4046,9 +4554,70 @@ const MATERIALIZE_EXCLUDE = new Set([
     '.cache',
     '.vite',
 ]);
-const defaultInstallDependencies = (worktreePath) => {
+const STATIC_PREVIEW_HISTORY_EXCLUDE = new Set([
+    ...MATERIALIZE_EXCLUDE,
+    '.rivet',
+]);
+const STATIC_PREVIEW_HISTORY_FILE_EXTENSIONS = new Set([
+    ...ALLOWED_ASSET_EXTENSIONS,
+    '.css',
+    '.htm',
+    '.html',
+    '.js',
+]);
+function copyStaticPreviewDirectory(src, dest) {
+    fs_1.default.mkdirSync(dest, { recursive: true });
+    let entries;
+    try {
+        entries = fs_1.default.readdirSync(src, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        if (entry.name.startsWith('.') ||
+            STATIC_PREVIEW_HISTORY_EXCLUDE.has(entry.name)) {
+            continue;
+        }
+        const from = path_1.default.join(src, entry.name);
+        const to = path_1.default.join(dest, entry.name);
+        if (entry.isDirectory()) {
+            copyStaticPreviewDirectory(from, to);
+        }
+        else if (entry.isFile()) {
+            const extension = path_1.default.extname(entry.name).toLowerCase();
+            if (!STATIC_PREVIEW_HISTORY_FILE_EXTENSIONS.has(extension))
+                continue;
+            let stat;
+            try {
+                stat = fs_1.default.statSync(from);
+            }
+            catch {
+                continue;
+            }
+            if (!stat.isFile() || stat.nlink !== 1)
+                continue;
+            fs_1.default.mkdirSync(path_1.default.dirname(to), { recursive: true });
+            fs_1.default.copyFileSync(from, to);
+        }
+    }
+}
+const buildInstallCommand = (packageManager) => {
+    if (packageManager === 'npm') {
+        return {
+            cmd: 'npm',
+            args: ['install', '--no-audit', '--no-fund', '--ignore-scripts'],
+        };
+    }
+    return {
+        cmd: packageManager,
+        args: ['install', '--ignore-scripts'],
+    };
+};
+const defaultInstallDependencies = (worktreePath, packageManager = 'npm') => {
+    const install = buildInstallCommand(packageManager);
     return new Promise((resolve, reject) => {
-        const proc = (0, child_process_1.spawn)('npm', ['install', '--no-audit', '--no-fund', '--ignore-scripts'], {
+        const proc = (0, child_process_1.spawn)(install.cmd, install.args, {
             cwd: worktreePath,
             stdio: ['ignore', 'ignore', 'pipe'],
         });
@@ -4062,10 +4631,40 @@ const defaultInstallDependencies = (worktreePath) => {
                 resolve();
                 return;
             }
-            reject(new Error(`npm install in ${worktreePath} failed (code ${code}): ${stderr.slice(-512)}`));
+            reject(new Error(`${install.cmd} install in ${worktreePath} failed (code ${code}): ${stderr.slice(-512)}`));
         });
     });
 };
+const detectPackageManagerForCwd = (cwd, fallback) => {
+    if (fs_1.default.existsSync(path_1.default.join(cwd, 'yarn.lock')))
+        return 'yarn';
+    if (fs_1.default.existsSync(path_1.default.join(cwd, 'pnpm-lock.yaml')))
+        return 'pnpm';
+    if (fs_1.default.existsSync(path_1.default.join(cwd, 'package-lock.json')))
+        return 'npm';
+    if (fallback === 'pnpm' || fallback === 'yarn' || fallback === 'npm') {
+        // A nested package without a lockfile should not inherit a root Yarn Berry
+        // workspace when it is not declared as a workspace member; npm treats it as
+        // an independent package and is the safest default for old examples.
+        return fs_1.default.existsSync(path_1.default.join(cwd, 'package.json')) ? 'npm' : fallback;
+    }
+    return 'npm';
+};
+const buildExistingProjectDevCommand = (packageManager, devCommand, port) => {
+    const env = { PORT: String(port) };
+    if (packageManager === 'npm') {
+        return {
+            cmd: 'npm',
+            args: ['run', devCommand, '--', '--port', String(port)],
+            env,
+        };
+    }
+    return {
+        cmd: packageManager,
+        args: [devCommand, '--port', String(port)],
+        env,
+    };
+};
 /**
  * True when `a` and `b` (or the closest existing ancestor of each) live on
  * the same filesystem volume. Used by commitVariant to decide between an