rivet-design 0.10.7 → 0.10.9

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");
@@ -13,6 +13,7 @@ const path_1 = __importDefault(require("path"));
 const child_process_1 = require("child_process");
 const simple_git_1 = require("simple-git");
 const logger_1 = require("../../utils/logger");
+const devServerError_1 = require("../../utils/devServerError");
 const errors_1 = require("./errors");
 const createProjectArtifacts_1 = require("./createProjectArtifacts");
 const contracts_1 = require("./contracts");
@@ -21,9 +22,14 @@ 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 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
+// 5173. Used as the scan start when allocating a fresh variant's preview port.
+const FRESH_DEV_SERVER_DEFAULT_PORT = 5173;
 const DESIGN_CONTEXT_ROUTE_SEGMENT = 'design-md';
 const DESIGN_CONTEXT_VIEW_SEGMENT = 'view';
 // Hard ceiling on worktree provisioning so a slow/large host project can never
@@ -254,7 +260,120 @@ function copyAssetIntoWorktree(worktreePath, entry, assetSourceRoot) {
     fs_1.default.copyFileSync(resolvedSource, absDest);
 }
 const defaultPreviewQaRunner = ({ html }) => (0, previewQa_1.runPreviewQa)({ html });
+/**
+ * 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
@@ -276,6 +395,7 @@ class AgentVariantsOrchestrator {
     installDependencies;
     materializeProject;
     previewQaRunner;
+    designCritiqueRunner;
     switchPreviewPort;
     setCommittedDevServerHealth;
     variantHistory;
@@ -319,13 +439,13 @@ 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();
         this.startStaticPreviewServerImpl =
             deps.startStaticPreviewServer ?? StaticPreviewServer_1.startStaticPreviewServer;
-        this.provisionTimeoutMs =
-            deps.provisionTimeoutMs ?? PROVISION_TIMEOUT_MS;
+        this.provisionTimeoutMs = deps.provisionTimeoutMs ?? PROVISION_TIMEOUT_MS;
     }
     // --- Pure delegations (no side effects) ---------------------------------
     propose(args) {
@@ -634,6 +754,16 @@ class AgentVariantsOrchestrator {
             const isSucceeded = variant.status === 'succeeded';
             const qaFailed = qa?.status === 'failed';
             const canView = Boolean(preview) || (isSucceeded && Boolean(port));
+            // A succeeded variant with no live preview whose dev server we tried and
+            // failed to start: surface the cause so the UI can show an accurate
+            // per-direction message instead of the generic disconnected overlay.
+            const previewFailure = resources?.previewFailures.get(variant.workItemId);
+            const previewUnavailable = !canView && isSucceeded && previewFailure
+                ? {
+                    reason: previewFailure.reason,
+                    ...(previewFailure.portInUse ? { portInUse: true } : {}),
+                }
+                : undefined;
             const canCommit = isSucceeded && !qaFailed;
             const commitDisabledReason = qaFailed
                 ? (qa?.summary ?? 'Variant failed QA')
@@ -644,6 +774,7 @@ class AgentVariantsOrchestrator {
                 ...(preview ? { preview } : {}),
                 port,
                 ...(qa ? { qa } : {}),
+                ...(previewUnavailable ? { previewUnavailable } : {}),
                 actions: {
                     view: canView
                         ? { enabled: true }
@@ -991,10 +1122,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
@@ -2074,42 +2210,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);
+            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;
+        }
+        // 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;
-        let qa;
+        }
+        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,
@@ -2118,7 +2408,229 @@ 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) {
+        try {
+            return await this.previewQaRunner({
+                sessionId: args.sessionId,
+                workItemId: args.workItemId,
+                html,
+            });
+        }
+        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;
@@ -2214,7 +2726,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();
         }
@@ -2264,44 +2777,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.
-        try {
-            const port = await this.worktrees.getFreePort();
-            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(' ')})`);
-        }
-        catch (err) {
-            trackFreshDevServerFailed(this.telemetry, {
-                sessionId,
-                variantId: workItemId,
-                errorCode: 'DEV_SERVER_START_FAILED',
-            });
-            log.warn(`Failed to start dev server for variant ${workItemId}; live preview disabled for this variant`, err);
-        }
+        await this.startVariantDevServer({
+            sessionId,
+            workItemId,
+            record,
+            isFresh,
+        });
     }
     async handleStaticPreviewRefinement(args) {
         const resources = this.resources.get(args.sessionId);
@@ -2541,6 +3022,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 {
@@ -2730,12 +3212,30 @@ class AgentVariantsOrchestrator {
             return undefined;
         }
     }
+    /**
+     * The port to start scanning from when allocating a variant's preview dev
+     * server. Fresh worktrees run the Vite template (5173); existing projects use
+     * their detected framework's default (3000 for Next, etc.), falling back to
+     * 3000 if detection fails. Scanning upward from here lands the preview on a
+     * sensible, predictable port near the project's normal one.
+     */
+    async resolveDevServerStartPort(sessionId, isFresh) {
+        if (isFresh)
+            return FRESH_DEV_SERVER_DEFAULT_PORT;
+        try {
+            const env = await this.resolveEnv(sessionId);
+            return env.defaultPort ?? 3000;
+        }
+        catch {
+            return 3000;
+        }
+    }
     /**
      * Resolve dev server invocation for a worktree. Fresh-project worktrees
      * always use the Vite template's npm command at the worktree root; existing
      * projects defer to the user's framework/packageManager config.
      */
-    async resolveDevServer(sessionId, worktreePath, port, isFresh) {
+    async resolveDevServer(sessionId, workItemId, worktreePath, port, isFresh) {
         if (isFresh) {
             return {
                 cwd: worktreePath,
@@ -2753,7 +3253,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) };
         }
@@ -2764,6 +3277,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>/`
@@ -3190,6 +3741,8 @@ class AgentVariantsOrchestrator {
                 startedAt: Date.now(),
                 leasedAt: new Map(),
                 qaResults: new Map(),
+                designCritiqueRetried: new Set(),
+                previewFailures: new Map(),
                 vitePreservedSiblings: false,
             };
             this.resources.set(sessionId, r);
@@ -3414,7 +3967,23 @@ const enrichDesignSource = (design) => {
 };
 const toActiveProjectContext = (projectContext) => {
     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 }),
+            ...(projectContext.sourceContext
+                ? {
+                    sourceContext: {
+                        sourceCount: (projectContext.sourceContext.sourceUrls?.length ?? 0) +
+                            (projectContext.sourceContext.sourceArtifacts?.length ?? 0),
+                        isSourceGrounded: Boolean(projectContext.sourceContext.artifact ||
+                            projectContext.sourceContext.sourceArtifacts?.length ||
+                            projectContext.sourceContext.sourceUrls?.length),
+                    },
+                }
+                : {}),
+        };
     }
     return {
         kind: 'fresh',
@@ -3469,8 +4038,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 [];
@@ -3945,6 +4512,8 @@ const trackFreshDevServerFailed = (telemetry, data) => {
         session_id: data.sessionId,
         variant_id: data.variantId,
         error_code: data.errorCode,
+        failure_reason: data.reason,
+        port_in_use: data.portInUse,
     });
 };
 const trackStaticPreviewCompleted = (telemetry, data) => {
@@ -3967,9 +4536,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'],
         });
@@ -3983,10 +4613,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