rivet-design 0.11.11 → 0.11.13

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 = exports.defaultDesignCritiqueRunner = void 0;
+exports.AgentVariantsOrchestrator = void 0;
 exports.buildStaticPreviewDocument = buildStaticPreviewDocument;
 const crypto_1 = require("crypto");
 const events_1 = require("events");
@@ -17,12 +17,12 @@ const devServerError_1 = require("../../utils/devServerError");
 const errors_1 = require("./errors");
 const createProjectArtifacts_1 = require("./createProjectArtifacts");
 const contracts_1 = require("./contracts");
+const runLabel_1 = require("./runLabel");
 const runPlan_1 = require("./runPlan");
 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");
@@ -281,94 +281,19 @@ const defaultPreviewQaRunner = ({ html, assetBase }) => (0, previewQa_1.runPrevi
         ...(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);
+/** Disabled-reason copy for a variant whose preview cannot be opened. */
+const buildViewDisabledReason = (args) => {
+    if (args.status === 'failed') {
+        return args.qa?.summary ?? 'Generation failed';
+    }
+    if (args.status === 'cancelled') {
+        return 'Variant was cancelled';
+    }
+    if (args.isSucceeded) {
+        return 'Preview is unavailable for this variant';
+    }
+    return 'Variant is still running';
 };
-/**
- * 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;
@@ -416,7 +341,6 @@ class AgentVariantsOrchestrator {
     installDependencies;
     materializeProject;
     previewQaRunner;
-    designCritiqueRunner;
     switchPreviewPort;
     setCommittedDevServerHealth;
     variantHistory;
@@ -460,7 +384,6 @@ 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();
@@ -661,44 +584,242 @@ class AgentVariantsOrchestrator {
     }
     beginStaticPreviewRefinements(args) {
         const seenVariantIds = new Set();
+        // Targets whose in-place refinement could neither be created nor folded
+        // into a pending one (e.g. the variant was already sent). We finish the
+        // batch's other targets, then RETURN these so the caller can surface them
+        // in its response — rather than throwing (which would break the agent poll
+        // and lose the already-consumed batch) or silently dropping them.
+        const droppedRefinements = [];
+        // Work items THIS batch created, so the caller can tell the agent to lease
+        // exactly these — letting concurrent runs (several watchers) each pick up
+        // their own batch instead of one greedily leasing everything.
+        const createdWorkItemIds = [];
         for (const target of args.targets) {
             if (seenVariantIds.has(target.variantId))
                 continue;
             seenVariantIds.add(target.variantId);
             const currentHtml = this.getStaticPreviewHtml(args.sessionId, target.variantId);
+            if (target.count == null) {
+                // Plain Apply (no variantRequest) → refine the variant IN PLACE: one
+                // edit that overwrites the source, no new sibling cards. Only an
+                // explicit "Vary" (which carries a count) fans out new variants.
+                try {
+                    const refineItem = this.store.createRefineVariantWorkItem({
+                        sessionId: args.sessionId,
+                        variantId: target.variantId,
+                        instruction: target.instruction,
+                        currentHtml,
+                        targetElement: target.element,
+                        requestId: target.requestId,
+                    });
+                    createdWorkItemIds.push(refineItem.id);
+                }
+                catch (error) {
+                    // A refinement is already queued for this variant — fold the newer
+                    // instruction in rather than dropping it (mirrors the apply queue).
+                    if (error instanceof errors_1.AgentVariantsError &&
+                        error.code === 'PENDING_CHANGE_CONFLICT') {
+                        const folded = this.store.appendPendingRefineVariantInstruction({
+                            sessionId: args.sessionId,
+                            variantId: target.variantId,
+                            instruction: target.instruction,
+                        });
+                        if (!folded) {
+                            // Nothing to fold into — the conflict is terminal (the variant
+                            // was already sent / is no longer editable). Don't swallow it.
+                            droppedRefinements.push({
+                                variantId: target.variantId,
+                                reason: error.message,
+                            });
+                        }
+                    }
+                    else if (error instanceof errors_1.AgentVariantsError &&
+                        error.code === 'VARIANT_NOT_EDITABLE') {
+                        droppedRefinements.push({
+                            variantId: target.variantId,
+                            reason: error.message,
+                        });
+                    }
+                    else {
+                        throw error;
+                    }
+                }
+                continue;
+            }
+            // "Vary" fans out: create `count` NEW sibling variants seeded from the
+            // source HTML + instruction, rather than overwriting the source in place.
+            // The agent leases them through the standard request-work path.
             try {
-                this.store.createRefineVariantWorkItem({
+                const forks = this.store.createForkedStaticPreviewWorkItems({
                     sessionId: args.sessionId,
-                    variantId: target.variantId,
+                    sourceVariantId: target.variantId,
                     instruction: target.instruction,
+                    count: target.count,
                     currentHtml,
+                    targetElement: target.element,
+                    requestId: target.requestId,
                 });
+                createdWorkItemIds.push(...forks.map((item) => item.id));
             }
             catch (error) {
+                // Terminal conflict — the source is no longer editable, or a variant
+                // was already sent for this session (the fork path has nothing to fold
+                // into). Surface it structurally like the in-place branch instead of
+                // throwing, which would break the agent poll AND lose this batch (the
+                // server already consumed it from the FIFO before calling us).
                 if (error instanceof errors_1.AgentVariantsError &&
-                    error.code === 'PENDING_CHANGE_CONFLICT') {
-                    // A refinement is already queued for this variant and the newer
-                    // comment was already consumed from the bridge. Fold it into the
-                    // still-pending item so it isn't silently dropped.
-                    const folded = this.store.appendPendingRefineVariantInstruction({
-                        sessionId: args.sessionId,
+                    (error.code === 'PENDING_CHANGE_CONFLICT' ||
+                        error.code === 'VARIANT_NOT_EDITABLE')) {
+                    droppedRefinements.push({
                         variantId: target.variantId,
-                        instruction: target.instruction,
+                        reason: error.message,
                     });
-                    if (!folded) {
-                        this.store.createRefineVariantWorkItem({
-                            sessionId: args.sessionId,
-                            variantId: target.variantId,
-                            instruction: target.instruction,
-                            currentHtml,
-                        });
-                    }
                     continue;
                 }
                 throw error;
             }
         }
         this.emitChange();
+        return { droppedRefinements, createdWorkItemIds };
+    }
+    /**
+     * Adopt a PAST variant (from a prior session's persisted history) into the
+     * active session, rehydrating it from its on-disk static snapshot so the
+     * comment / refine / Vary machinery treats it as a live, first-class variant.
+     *
+     * Triggered when the user makes their first edit on a selected past direction.
+     * The store appends an already-`succeeded` `static_preview` work item keyed by
+     * the past identity (idempotent); this method registers the matching static-
+     * preview record so {@link getStaticPreviewHtml}, {@link getVariants}
+     * (preview.kind = 'static_artifact', view enabled), and the
+     * `/api/variants/:sid/static/:vid` routes all light up exactly as they do for a
+     * freshly-generated static_preview variant.
+     *
+     * `filesDir` is the absolute path to the persisted `files/` snapshot (resolved
+     * by the caller from history) and must hold a renderable `index.html`. Returns
+     * the stable active-session `workItemId` so the caller can route the
+     * triggering edit to it, plus whether it was already adopted.
+     */
+    async adoptPastVariant(args) {
+        const { assetBase, hasAssets } = await this.resolveAdoptedStaticPreviewFiles(args.filesDir);
+        const append = this.store.appendAdoptedStaticVariant({
+            sessionId: args.sessionId,
+            source: args.source,
+            label: args.label,
+            description: args.description,
+            runLabel: args.runLabel,
+        });
+        // Register (or re-register, harmlessly) the static-preview record so the
+        // snapshot surfaces the adopted variant as a static_artifact.
+        const resources = this.ensureResources(args.sessionId);
+        resources.staticPreviews.set(append.workItemId, {
+            workItemId: append.workItemId,
+            briefId: append.briefId,
+            assetBase,
+            hasAssets,
+        });
+        this.emitChange();
+        return {
+            workItemId: append.workItemId,
+            alreadyAdopted: !append.created,
+        };
+    }
+    /**
+     * Rehydrate a static history variant into the current active session when it
+     * can still accept edits; otherwise create a replacement active session whose
+     * only visible direction is the selected history artifact.
+     */
+    async bootstrapPastVariantSession(args) {
+        const usableSessionId = this.getUsableActiveSessionId();
+        if (usableSessionId) {
+            const adopted = await this.adoptPastVariant({
+                sessionId: usableSessionId,
+                source: args.source,
+                filesDir: args.filesDir,
+                label: args.label,
+                description: args.description,
+                runLabel: args.runLabel,
+            });
+            return {
+                sessionId: usableSessionId,
+                workItemId: adopted.workItemId,
+                alreadyAdopted: adopted.alreadyAdopted,
+                bootstrapped: false,
+            };
+        }
+        const { assetBase, hasAssets } = await this.resolveAdoptedStaticPreviewFiles(args.filesDir);
+        void this.stopLingeringCommittedDevServers().catch((err) => {
+            log.warn('Stopping lingering committed dev servers failed', err);
+        });
+        const created = this.store.createSessionFromStaticHistoryVariant({
+            source: args.source,
+            prompt: args.prompt ?? args.description ?? args.label,
+            label: args.label,
+            description: args.description,
+            runLabel: args.runLabel,
+            projectContext: args.projectContext,
+        });
+        this.activeSessionId = created.sessionId;
+        const resources = this.ensureResources(created.sessionId);
+        resources.staticPreviews.set(created.workItemId, {
+            workItemId: created.workItemId,
+            briefId: created.briefId,
+            assetBase,
+            hasAssets,
+        });
+        this.emitChange();
+        return {
+            sessionId: created.sessionId,
+            workItemId: created.workItemId,
+            alreadyAdopted: false,
+            bootstrapped: true,
+        };
+    }
+    getUsableActiveSessionId() {
+        const sessionId = this.activeSessionId;
+        if (!sessionId || !this.store.hasSession(sessionId)) {
+            return null;
+        }
+        const stage = this.store.getStage(sessionId);
+        return stage === 'failed' || stage === 'cancelled' ? null : sessionId;
+    }
+    async resolveAdoptedStaticPreviewFiles(filesDir) {
+        const entryFile = path_1.default.join(filesDir, 'index.html');
+        try {
+            await fs_1.default.promises.access(entryFile, fs_1.default.constants.R_OK);
+        }
+        catch {
+            throw new errors_1.AgentVariantsError('RUNTIME_VALIDATION_FAILED', `Cannot adopt past variant: no readable index.html under ${filesDir}`);
+        }
+        let assetBase;
+        try {
+            assetBase = fs_1.default.realpathSync(filesDir);
+        }
+        catch {
+            assetBase = filesDir;
+        }
+        let hasAssets = false;
+        try {
+            hasAssets = fs_1.default.readdirSync(assetBase).some((name) => name !== 'index.html');
+        }
+        catch {
+            hasAssets = false;
+        }
+        return { assetBase, hasAssets };
+    }
+    /**
+     * True when the variant is an HTML-only static_preview work item. Adopted past
+     * variants and fresh `static_preview` variants both qualify. Existing-project
+     * `code_gen` variants can still expose a static artifact for preview, but Vary
+     * must keep those on the worktree-backed code_gen append path.
+     */
+    isStaticPreviewVariant(sessionId, workItemId) {
+        try {
+            return this.store.getWorkItemKind(sessionId, workItemId) === 'static_preview';
+        }
+        catch {
+            return false;
+        }
     }
     getVariantPick(sessionId) {
         return this.store.getVariantPick(sessionId);
@@ -756,6 +877,13 @@ class AgentVariantsOrchestrator {
         const resources = this.resources.get(sessionId);
         return this.store.getVariants(sessionId).map((variant) => {
             const port = this.getDevServerPort(sessionId, variant.workItemId);
+            // Captured worktree diff (existing-project code_gen). Surfaced as a
+            // changed-files count so a diff-only variant (no dev server / static
+            // artifact) still reads as a real result in the panel.
+            const capturedDiff = resources?.worktrees.get(variant.workItemId)?.diff;
+            const changedFilesCount = typeof capturedDiff === 'string' && capturedDiff.length > 0
+                ? countDiffFiles(capturedDiff)
+                : undefined;
             // For fresh sessions, static_preview items ARE the variants — look up
             // directly by workItemId. Fall back to briefId search for existing-project
             // sessions where code_gen items were paired with companion static_preview items.
@@ -813,6 +941,7 @@ class AgentVariantsOrchestrator {
                 design: enrichDesignSource(variant.design),
                 ...(preview ? { preview } : {}),
                 port,
+                ...(changedFilesCount !== undefined ? { changedFilesCount } : {}),
                 ...(qa ? { qa } : {}),
                 ...(previewUnavailable ? { previewUnavailable } : {}),
                 actions: {
@@ -820,9 +949,11 @@ class AgentVariantsOrchestrator {
                         ? { enabled: true }
                         : {
                             enabled: false,
-                            reason: isSucceeded
-                                ? 'Preview is unavailable for this variant'
-                                : 'Variant is still running',
+                            reason: buildViewDisabledReason({
+                                status: variant.status,
+                                isSucceeded,
+                                qa,
+                            }),
                         },
                     commit: canCommit
                         ? { enabled: true }
@@ -1011,60 +1142,107 @@ class AgentVariantsOrchestrator {
         if (isSourceGrounded) {
             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({
+        // A second "Vary" on an existing project that still has a live session
+        // ACCUMULATES into that session instead of starting a fresh one that
+        // would orphan the prior variants (and overwrite `activeSessionId`, so
+        // the RHS would only ever show the latest batch). Gated to existing
+        // projects so fresh 0→1 generation is unaffected.
+        const appendSessionId = args.allowAccumulate &&
+            projectContext.kind === 'existing' &&
+            projectContext.projectPath
+            ? this.getAppendableExistingSessionId(projectContext.projectPath)
+            : null;
+        const briefs = this.buildUnifiedBriefs({
             prompt: args.prompt,
-            count,
-            target: args.target,
-            projectContext,
             runLabel: args.runLabel,
-            ...(args.sessionId ? { sessionId: args.sessionId } : {}),
-        });
-        if (proposeResult.stage !== 'awaiting_briefs' ||
-            !proposeResult.briefWorkItem) {
-            throw new errors_1.AgentVariantsError('INVALID_STAGE_ACTION', `start_variants expected awaiting_briefs from propose, got ${proposeResult.stage}`);
-        }
-        const briefs = args.briefs
-            ? args.briefs.map((b, i) => ({
-                briefId: `v${i + 1}`,
-                label: b.label,
-                body: b.body,
-                ...(b.visualReferenceUrl
-                    ? { visualReferenceUrl: b.visualReferenceUrl }
-                    : {}),
-            }))
-            : Array.from({ length: count }, (_, i) => ({
-                briefId: `v${i + 1}`,
-                label: `Variant ${i + 1}`,
-                body: synthesizeUnifiedBriefBody(args.prompt, i + 1, count),
-            }));
-        this.store.reportBriefs({
-            sessionId: proposeResult.sessionId,
-            workItemId: proposeResult.briefWorkItem.id,
-            attempt: proposeResult.briefWorkItem.attempt,
-            briefs,
-        });
-        const approveResult = await this.approve({
-            sessionId: proposeResult.sessionId,
-            selections: briefs.map((b) => ({ briefId: b.briefId })),
-        });
-        this.telemetry.track('agent_variants.unified_started', {
-            source: 'mcp',
-            sessionId: proposeResult.sessionId,
             count,
-            hasTarget: Boolean(args.target),
-            targetType: args.target?.type ?? null,
-            projectContextKind: projectContext.kind,
+            briefs: args.briefs,
+            uniqueBriefIds: Boolean(appendSessionId),
         });
-        // For existing-project sessions, approve() returns the new code_gen
-        // ids in codeGenWorkItemIds. For zero-to-one, approve() spawns
-        // static_preview items instead — those ids aren't in codeGenWorkItemIds,
-        // so read them out of the active-variants snapshot which covers both
-        // kinds. Snapshot order mirrors brief order (insertion order).
-        const variantIds = projectContext.kind === 'fresh'
-            ? this.store
-                .getVariants(proposeResult.sessionId)
-                .map((v) => v.workItemId)
-            : approveResult.codeGenWorkItemIds;
+        let sessionId;
+        let variantIds;
+        let scaffoldBaseWorkItemId = null;
+        if (appendSessionId) {
+            sessionId = appendSessionId;
+            const forkArgs = {
+                sessionId,
+                briefs,
+                runLabel: args.runLabel?.trim() || (0, runLabel_1.deriveRunLabel)(args.prompt),
+                ...(projectContext.kind === 'existing' && projectContext.variantContext
+                    ? { variantContext: projectContext.variantContext }
+                    : {}),
+            };
+            const { createdWorkItemIds } = args.sourceVariantId
+                ? this.store.createForkedCodeGenWorkItems({
+                    ...forkArgs,
+                    sourceVariantId: args.sourceVariantId,
+                })
+                : this.store.appendExistingCodeGenVariants(forkArgs);
+            variantIds = createdWorkItemIds;
+            if (args.sourceVariantId) {
+                await this.provisionForkedFromVariantWorktrees(sessionId, args.sourceVariantId, createdWorkItemIds);
+            }
+            else {
+                await this.provisionAppendedExistingWorktrees(sessionId, createdWorkItemIds);
+            }
+            this.telemetry.track('agent_variants.variants_appended', {
+                source: 'mcp',
+                sessionId,
+                count: createdWorkItemIds.length,
+                hasTarget: Boolean(args.target),
+                targetType: args.target?.type ?? null,
+                forkedFromVariantId: args.sourceVariantId ?? null,
+            });
+            this.emitChange();
+        }
+        else {
+            const proposeResult = this.propose({
+                prompt: args.prompt,
+                count,
+                target: args.target,
+                projectContext,
+                runLabel: args.runLabel,
+                ...(args.sessionId ? { sessionId: args.sessionId } : {}),
+            });
+            if (proposeResult.stage !== 'awaiting_briefs' ||
+                !proposeResult.briefWorkItem) {
+                throw new errors_1.AgentVariantsError('INVALID_STAGE_ACTION', `start_variants expected awaiting_briefs from propose, got ${proposeResult.stage}`);
+            }
+            this.store.reportBriefs({
+                sessionId: proposeResult.sessionId,
+                workItemId: proposeResult.briefWorkItem.id,
+                attempt: proposeResult.briefWorkItem.attempt,
+                briefs,
+            });
+            const approveResult = await this.approve({
+                sessionId: proposeResult.sessionId,
+                selections: briefs.map((b) => ({ briefId: b.briefId })),
+            });
+            this.telemetry.track('agent_variants.unified_started', {
+                source: 'mcp',
+                sessionId: proposeResult.sessionId,
+                count,
+                hasTarget: Boolean(args.target),
+                targetType: args.target?.type ?? null,
+                projectContextKind: projectContext.kind,
+            });
+            sessionId = proposeResult.sessionId;
+            scaffoldBaseWorkItemId = approveResult.scaffoldBaseWorkItemId ?? null;
+            // For existing-project sessions, approve() returns the new code_gen
+            // ids in codeGenWorkItemIds. For zero-to-one, approve() spawns
+            // static_preview items instead — those ids aren't in codeGenWorkItemIds,
+            // so read them out of the active-variants snapshot which covers both
+            // kinds. Snapshot order mirrors brief order (insertion order).
+            variantIds =
+                projectContext.kind === 'fresh'
+                    ? this.store.getVariants(sessionId).map((v) => v.workItemId)
+                    : approveResult.codeGenWorkItemIds;
+        }
+        // Stamp the UI correlation id so the panel maps its optimistic placeholders
+        // to these real cards (the same mechanism the static-preview fork uses).
+        if (args.requestId) {
+            this.store.assignVariantRequestId(sessionId, variantIds, args.requestId);
+        }
         const variants = variantIds.map((workItemId, i) => ({
             variantId: workItemId,
             briefId: briefs[i].briefId,
@@ -1076,22 +1254,111 @@ class AgentVariantsOrchestrator {
         let leasedWorkItems;
         if (args.leaseOwner) {
             const lease = this.requestWork({
-                sessionId: proposeResult.sessionId,
+                sessionId,
                 leaseOwner: args.leaseOwner,
+                // Append: lease ONLY the new batch so a still-leasable prior item
+                // (e.g. a re-leased one) isn't swept into this Vary's lease.
+                ...(appendSessionId ? { workItemIds: variantIds } : {}),
             });
             leaseId = lease.leaseId;
             leaseTtlMs = lease.leaseTtlMs;
             leasedWorkItems = lease.leasedWorkItems;
         }
         return {
-            sessionId: proposeResult.sessionId,
+            sessionId,
             variants,
-            scaffoldBaseWorkItemId: approveResult.scaffoldBaseWorkItemId ?? null,
+            scaffoldBaseWorkItemId,
             leaseId,
             leaseTtlMs,
             leasedWorkItems,
         };
     }
+    /**
+     * Build the per-variant briefs for a unified start. Agent-supplied briefs win
+     * verbatim. The fallback derives a short run-intent label from the prompt
+     * (e.g. "make it brighter" → "Brighter 1/2/…") rather than an indistinct
+     * "Variant N", so two sequential Vary batches stay distinguishable in the
+     * Directions list. `uniqueBriefIds` is set for the append path so the new
+     * batch's briefIds can't collide with the live session's existing ones.
+     */
+    buildUnifiedBriefs(args) {
+        const briefId = (i) => args.uniqueBriefIds ? `v-${(0, crypto_1.randomUUID)().slice(0, 8)}` : `v${i + 1}`;
+        if (args.briefs) {
+            return args.briefs.map((b, i) => ({
+                briefId: briefId(i),
+                label: b.label,
+                body: b.body,
+                ...(b.visualReferenceUrl
+                    ? { visualReferenceUrl: b.visualReferenceUrl }
+                    : {}),
+            }));
+        }
+        const runLabel = args.runLabel?.trim() || (0, runLabel_1.deriveRunLabel)(args.prompt);
+        return Array.from({ length: args.count }, (_, i) => ({
+            briefId: briefId(i),
+            label: args.count > 1 ? `${runLabel} ${i + 1}` : runLabel,
+            body: synthesizeUnifiedBriefBody(args.prompt, i + 1, args.count),
+        }));
+    }
+    /**
+     * The active sessionId IF it is an existing-project session for `projectPath`
+     * that can still accept appended variants — i.e. not committed, not
+     * cancelled/failed. Returns null otherwise, so start_variants falls back to
+     * creating a fresh session (first Vary, a different project, or after the
+     * prior session was committed/cancelled).
+     */
+    getAppendableExistingSessionId(projectPath) {
+        const sessionId = this.activeSessionId;
+        if (!sessionId || !this.store.hasSession(sessionId))
+            return null;
+        const ctx = this.store.getProjectContext(sessionId);
+        if (ctx.kind !== 'existing' || ctx.projectPath !== projectPath)
+            return null;
+        if (this.store.getVariantPick(sessionId))
+            return null;
+        const stage = this.store.getStage(sessionId);
+        if (stage === 'cancelled' || stage === 'failed')
+            return null;
+        return sessionId;
+    }
+    /**
+     * Provision a worktree for each appended existing-project variant. Mirrors
+     * {@link provisionExistingWorktrees} but only for the newly appended ids, and
+     * passes a per-batch `instanceKeyPrefix` so the new worktree dirs do not
+     * collide with the first batch's `${sessionId}-${i}` paths.
+     */
+    async provisionAppendedExistingWorktrees(sessionId, workItemIds) {
+        if (workItemIds.length === 0)
+            return;
+        const resources = this.ensureResources(sessionId);
+        const instanceKeyPrefix = `a${(0, crypto_1.randomUUID)().slice(0, 8)}-`;
+        const paths = await withProvisionTimeout(this.worktrees.createWorktrees(sessionId, workItemIds.length, instanceKeyPrefix), this.provisionTimeoutMs);
+        workItemIds.forEach((id, i) => {
+            resources.worktrees.set(id, { workItemId: id, worktreePath: paths[i] });
+        });
+    }
+    /**
+     * Provision worktrees for a code_gen Vary forked from a parent variant.
+     * Copies the parent's worktree tree so each sibling starts from the parent's
+     * diff rather than git HEAD / Original.
+     */
+    async provisionForkedFromVariantWorktrees(sessionId, sourceVariantId, workItemIds) {
+        if (workItemIds.length === 0)
+            return;
+        const sourcePath = this.getWorktreePath(sessionId, sourceVariantId);
+        if (!sourcePath) {
+            throw new errors_1.AgentVariantsError('VARIANT_NOT_EDITABLE', `Cannot fork from variant ${sourceVariantId}: no worktree path`);
+        }
+        if (!this.worktrees.forkWorktreesFrom) {
+            throw new errors_1.AgentVariantsError('RUNTIME_VALIDATION_FAILED', 'worktreeManager does not implement forkWorktreesFrom');
+        }
+        const resources = this.ensureResources(sessionId);
+        const instanceKeyPrefix = `f${(0, crypto_1.randomUUID)().slice(0, 8)}-`;
+        const paths = await withProvisionTimeout(this.worktrees.forkWorktreesFrom(sourcePath, sessionId, workItemIds.length, instanceKeyPrefix), this.provisionTimeoutMs);
+        workItemIds.forEach((id, i) => {
+            resources.worktrees.set(id, { workItemId: id, worktreePath: paths[i] });
+        });
+    }
     async reportComplete(args) {
         // Cooperative abort short-circuit: if the work item was removed/cancelled
         // while in flight (delete-while-loading, cancel_variant, session cancel),
@@ -1129,10 +1396,11 @@ class AgentVariantsOrchestrator {
         const qaEval = workItemKind === 'refine_variant'
             ? null
             : await this.evaluateQaForReport(args);
-        // A `retry` verdict re-leases the variant for one aesthetic regeneration
-        // instead of recording success — short-circuit the normal record path.
+        // A `retry` verdict re-leases the variant for one regeneration (the
+        // existing-project diff task-fit gate) instead of recording success —
+        // short-circuit the normal record path.
         if (qaEval?.decision === 'retry') {
-            return this.handleDesignCritiqueRetry(args, qaEval.qa);
+            return this.handleQaRegenRetry(args, qaEval.qa);
         }
         let effectiveArgs = qaEval?.decision === 'fail_terminal' ? qaEval.overrideArgs : args;
         // For a successful refine_variant, swap the refined static preview into
@@ -2227,11 +2495,9 @@ class AgentVariantsOrchestrator {
             }
             return null;
         }
-        // Resolve the objective base QA (static_preview only) and the design
-        // critique render target for this deliverable kind.
+        // Resolve the objective base QA for this deliverable kind.
         let baseQa = null;
-        let critiqueTarget = null;
-        let checkedSource;
+        const checkedSource = undefined;
         if (kind === 'static_preview') {
             const parsed = parseStaticPreviewOutput(normalizeOutput(args.output));
             if (!parsed)
@@ -2241,22 +2507,16 @@ class AgentVariantsOrchestrator {
                 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.
+            // Fresh vite_app variants run agent-authored dev-server code. No
+            // preview document to inspect — behave exactly as before.
             return null;
         }
         else {
             return null;
         }
-        // Objective base QA failure is terminal exactly as before — never run the
-        // aesthetic critique on a variant that's already broken.
+        // Objective base QA failure is terminal exactly as before.
         if (baseQa && baseQa.status === 'failed') {
             this.memoizeQa(args.sessionId, args.workItemId, baseQa);
             return {
@@ -2276,54 +2536,8 @@ class AgentVariantsOrchestrator {
             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 };
+        this.memoizeQa(args.sessionId, args.workItemId, passedBase);
+        return { decision: 'pass', qa: passedBase };
     }
     async evaluateExistingCodeGenQa(args) {
         const input = this.store.getWorkItemInput(args.sessionId, args.workItemId);
@@ -2425,6 +2639,10 @@ class AgentVariantsOrchestrator {
             ],
             summary: 'No generated content was added for this design variant; regenerate it with real homepage UI changes.',
         };
+        const sessionResources = this.ensureResources(args.sessionId);
+        if (!sessionResources.qaRegenRetried.has(args.workItemId)) {
+            return { decision: 'retry', qa };
+        }
         this.memoizeQa(args.sessionId, args.workItemId, qa);
         return {
             decision: 'fail_terminal',
@@ -2458,93 +2676,33 @@ class AgentVariantsOrchestrator {
             };
         }
     }
-    /** 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.
+     * variant work item so it can be re-leased and regenerated against the QA
+     * notes, and record that it has now used its single retry.
      */
-    async handleDesignCritiqueRetry(args, qa) {
+    async handleQaRegenRetry(args, qa) {
         const resources = this.ensureResources(args.sessionId);
-        const result = this.store.requeueForDesignCritique({
+        const result = this.store.requeueForRegeneration({
             sessionId: args.sessionId,
             workItemId: args.workItemId,
             leaseId: args.leaseId,
             attempt: args.attempt,
-            critique: {
-                summary: buildRetryCritiqueSummary(qa),
-                dimensionScores: qa.dimensionScores,
+            qaRetry: {
+                summary: qa.summary,
             },
         });
-        resources.designCritiqueRetried.add(args.workItemId);
+        resources.qaRegenRetried.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,
+            overall: null,
         });
         this.emitChange();
         // Carry the requeue signal + critique so the tool layer can tell the agent
@@ -3872,7 +4030,7 @@ class AgentVariantsOrchestrator {
                 startedAt: Date.now(),
                 leasedAt: new Map(),
                 qaResults: new Map(),
-                designCritiqueRetried: new Set(),
+                qaRegenRetried: new Set(),
                 previewFailures: new Map(),
                 vitePreservedSiblings: false,
             };
@@ -4855,13 +5013,21 @@ const buildExistingProjectDevCommand = (packageManager, devCommand, port) => {
     if (packageManager === 'npm') {
         return {
             cmd: 'npm',
-            args: ['run', devCommand, '--', '--port', String(port)],
+            args: [
+                'run',
+                devCommand,
+                '--',
+                '--port',
+                String(port),
+                '--host',
+                FRESH_DEV_SERVER_HOST,
+            ],
             env,
         };
     }
     return {
         cmd: packageManager,
-        args: [devCommand, '--port', String(port)],
+        args: [devCommand, '--port', String(port), '--host', FRESH_DEV_SERVER_HOST],
         env,
     };
 };