rivet-design 0.12.4 → 0.13.1

package/dist/{mcp/agent-variants → agent-variants}/WorktreeOrchestrator.js

@@ -12,23 +12,54 @@ const os_1 = __importDefault(require("os"));
 const path_1 = __importDefault(require("path"));
 const child_process_1 = require("child_process");
 const simple_git_1 = require("simple-git");
-const logger_1 = require("../../utils/logger");
-const devServerError_1 = require("../../utils/devServerError");
+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");
 const briefContent_1 = require("./briefContent");
 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 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 diffQa_1 = require("./diffQa");
-const VariantHistoryService_1 = require("../../services/VariantHistoryService");
+const VariantHistoryService_1 = require("../services/VariantHistoryService");
 const variantContext_1 = require("./variantContext");
 const log = (0, logger_1.createLogger)('AgentVariantsOrchestrator');
 const FRESH_DEV_SERVER_HOST = '127.0.0.1';
+const BRIEF_LABEL_MAX_LENGTH = 48;
+const GENERIC_BRIEF_LABELS = new Set([
+    'variant',
+    'direction',
+    'option',
+    'untitled',
+]);
+const DIRECTIONAL_BRIEF_LABELS = [
+    'Refined Focus',
+    'Bold Contrast',
+    'Airy Layout',
+    'Editorial Polish',
+    'Playful Accent',
+    'Calm Minimal',
+    'Dense Utility',
+    'Sharp Detail',
+];
+const BRIEF_LABEL_ALTERNATIVES = [
+    'Focus',
+    'Contrast',
+    'Layout',
+    'Editorial',
+    'Accent',
+    'Minimal',
+    'Utility',
+    'Detail',
+    'Motion',
+    'Depth',
+    'Density',
+    'Color',
+];
 // Upper bound on waiting for in-flight history persists during session
 // teardown. Generous enough for a full-repo snapshot on a large project;
 // small enough that a wedged git subprocess (which has its own 120s block
@@ -62,6 +93,18 @@ const PROVISION_TIMEOUT_MS = (() => {
         ? parsed
         : DEFAULT_PROVISION_TIMEOUT_MS;
 })();
+// Active variant dev servers are useful only while the Rivet app is being used.
+// Reclaim them after app/API silence so abandoned sessions do not pin one child
+// process per succeeded variant forever. The session state and worktrees stay
+// intact; only live preview ports are cleared.
+const DEFAULT_ACTIVE_VARIANT_SERVER_IDLE_TTL_MS = 30 * 60 * 1000;
+const ACTIVE_VARIANT_SERVER_IDLE_TTL_MS = (() => {
+    const raw = process.env.RIVET_ACTIVE_VARIANT_SERVER_IDLE_TTL_MS;
+    const parsed = raw ? Number.parseInt(raw, 10) : NaN;
+    return Number.isFinite(parsed) && parsed > 0
+        ? parsed
+        : DEFAULT_ACTIVE_VARIANT_SERVER_IDLE_TTL_MS;
+})();
 /** Sentinel so callers can distinguish a provisioning timeout from other errors. */
 class ProvisionTimeoutError extends Error {
     timeoutMs;
@@ -311,6 +354,64 @@ const DESIGN_CREATION_ACTION_RE = /\b(create|build|design|make|redesign|refresh|
 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 briefLabelKey = (value) => value.trim().toLowerCase().replace(/\s+/g, ' ');
+const truncateBriefLabel = (value) => {
+    const normalized = value.trim().replace(/\s+/g, ' ');
+    if (normalized.length <= BRIEF_LABEL_MAX_LENGTH) {
+        return normalized;
+    }
+    return `${normalized.slice(0, BRIEF_LABEL_MAX_LENGTH - 1).trimEnd()}…`;
+};
+const suffixFromGenericLabel = (label, slotIndex) => {
+    const words = label.trim().split(/\s+/).filter(Boolean);
+    return (words[words.length - 1] ??
+        BRIEF_LABEL_ALTERNATIVES[slotIndex % BRIEF_LABEL_ALTERNATIVES.length]);
+};
+const makeSpecificBriefLabel = (args) => {
+    const label = truncateBriefLabel(args.label);
+    if (!GENERIC_BRIEF_LABELS.has(briefLabelKey(label))) {
+        return label;
+    }
+    return truncateBriefLabel(`${args.runLabel} ${suffixFromGenericLabel(label, args.slotIndex)}`);
+};
+const firstUnusedDirectionalBriefLabel = (slotIndex, usedLabels) => {
+    for (let offset = 0; offset < DIRECTIONAL_BRIEF_LABELS.length; offset++) {
+        const candidate = truncateBriefLabel(DIRECTIONAL_BRIEF_LABELS[(slotIndex + offset) % DIRECTIONAL_BRIEF_LABELS.length]);
+        if (!usedLabels.has(briefLabelKey(candidate))) {
+            return candidate;
+        }
+    }
+    return null;
+};
+const uniquifyBriefLabel = (args) => {
+    const preferred = makeSpecificBriefLabel(args);
+    if (!args.usedLabels.has(briefLabelKey(preferred))) {
+        args.usedLabels.add(briefLabelKey(preferred));
+        return preferred;
+    }
+    const directional = firstUnusedDirectionalBriefLabel(args.slotIndex, args.usedLabels);
+    if (directional) {
+        args.usedLabels.add(briefLabelKey(directional));
+        return directional;
+    }
+    for (let offset = 0; offset < BRIEF_LABEL_ALTERNATIVES.length; offset++) {
+        const alternative = BRIEF_LABEL_ALTERNATIVES[(args.slotIndex + offset) % BRIEF_LABEL_ALTERNATIVES.length];
+        const candidate = truncateBriefLabel(`${args.runLabel} ${alternative}`);
+        if (!args.usedLabels.has(briefLabelKey(candidate))) {
+            args.usedLabels.add(briefLabelKey(candidate));
+            return candidate;
+        }
+    }
+    let suffix = 2;
+    while (true) {
+        const candidate = truncateBriefLabel(`${args.runLabel} ${suffix}`);
+        if (!args.usedLabels.has(briefLabelKey(candidate))) {
+            args.usedLabels.add(briefLabelKey(candidate));
+            return candidate;
+        }
+        suffix += 1;
+    }
+};
 const buildDiffCaptureFailureQa = (detail, message) => ({
     status: 'failed',
     issues: [
@@ -334,20 +435,18 @@ const isDesignCreationCodeGenInput = (input, prompt) => {
 };
 /**
  * Wraps SessionStore for the operations that have side effects: approve
- * (provision worktrees), reportComplete (capture diff + auto-enqueue to
- * pending changes), cancel (teardown). Pure read paths bypass and call
- * SessionStore directly.
+ * (provision worktrees), reportComplete (capture diff), commit (apply picked
+ * output), cancel (teardown). Pure read paths bypass and call SessionStore
+ * directly.
  *
  * This is the terminal-native variant of the orchestrator: the user picks
  * a single brief upfront, so there's only ever one code-gen item per
  * session and no live preview / proxy retarget. Once the agent reports
- * the variant succeeded, the diff auto-enqueues to bridge — no separate
- * pick step.
+ * the variant succeeded, the CLI can commit the chosen output directly.
  */
 class AgentVariantsOrchestrator {
     store;
     worktrees;
-    adapter;
     resolveEnv;
     telemetry;
     installDependencies;
@@ -358,6 +457,7 @@ class AgentVariantsOrchestrator {
     variantHistory;
     startStaticPreviewServerImpl;
     provisionTimeoutMs;
+    activeVariantServerIdleTtlMs;
     resources = new Map();
     /**
      * Committed dev servers from prior sessions that survived teardown. The
@@ -388,7 +488,6 @@ class AgentVariantsOrchestrator {
     constructor(deps) {
         this.store = deps.store;
         this.worktrees = deps.worktreeManager;
-        this.adapter = deps.pendingChangesAdapter;
         this.resolveEnv = deps.resolveProjectEnvironment;
         this.telemetry = deps.telemetry ?? NOOP_TELEMETRY;
         this.installDependencies =
@@ -402,6 +501,8 @@ class AgentVariantsOrchestrator {
         this.startStaticPreviewServerImpl =
             deps.startStaticPreviewServer ?? StaticPreviewServer_1.startStaticPreviewServer;
         this.provisionTimeoutMs = deps.provisionTimeoutMs ?? PROVISION_TIMEOUT_MS;
+        this.activeVariantServerIdleTtlMs =
+            deps.activeVariantServerIdleTtlMs ?? ACTIVE_VARIANT_SERVER_IDLE_TTL_MS;
     }
     // --- Pure delegations (no side effects) ---------------------------------
     propose(args) {
@@ -414,6 +515,7 @@ class AgentVariantsOrchestrator {
         const result = this.store.propose(args);
         this.activeSessionId = result.sessionId;
         this.ensureResources(result.sessionId);
+        this.touchSession(result.sessionId);
         const projectContext = args.projectContext ?? { kind: 'existing' };
         const mode = this.getVariantsTelemetryMode(projectContext, args.target);
         this.startVariantsRound({
@@ -483,6 +585,7 @@ class AgentVariantsOrchestrator {
     registerUiClient() {
         this.uiClientCount += 1;
         this.lastUiClientActivityAt = Date.now();
+        this.touchActiveSession();
         let released = false;
         return () => {
             if (released)
@@ -502,6 +605,19 @@ class AgentVariantsOrchestrator {
         return (Date.now() - this.lastUiClientActivityAt <
             AgentVariantsOrchestrator.UI_CLIENT_GRACE_MS);
     }
+    /** @effect Records activity for the current variants session, if one exists. */
+    touchActiveSession() {
+        if (!this.activeSessionId)
+            return;
+        this.touchSession(this.activeSessionId);
+    }
+    /** @effect Resets idle cleanup for active variant preview servers. */
+    touchSession(sessionId) {
+        const resources = this.resources.get(sessionId);
+        if (!resources || resources.cleanupStarted)
+            return;
+        this.scheduleActivePreviewIdleTimer(resources);
+    }
     /** Build the snapshot the chip cares about. Reads from SessionStore +
      *  per-resource state; safe to call at any time. */
     buildActiveSnapshot() {
@@ -525,6 +641,7 @@ class AgentVariantsOrchestrator {
             ? projectContext.workspacePath
             : undefined;
         const artifacts = buildSessionArtifacts(sessionId, sessionProjectContext);
+        const hostWork = this.getHostWork(sessionId);
         return {
             active: true,
             sessionId,
@@ -536,8 +653,21 @@ class AgentVariantsOrchestrator {
             projectContext,
             ...(destinationPath ? { destinationPath } : {}),
             ...(artifacts.length > 0 ? { artifacts } : {}),
+            ...(hostWork.length > 0 ? { hostWork } : {}),
         };
     }
+    getHostWork(sessionId) {
+        return this.store.getHostWork(sessionId).map((item) => {
+            const worktreePath = this.getWorktreePath(sessionId, item.workId);
+            const baseInput = item.input && typeof item.input === 'object'
+                ? item.input
+                : {};
+            return {
+                ...item,
+                input: { ...baseInput, worktreePath },
+            };
+        });
+    }
     getVariantsTelemetryMode(projectContext, _target) {
         if (projectContext.kind === 'fresh' && projectContext.variantContext) {
             return 'source_grounded';
@@ -739,6 +869,7 @@ class AgentVariantsOrchestrator {
     }
     emitChange() {
         try {
+            this.touchActiveSession();
             this.events.emit('change', this.buildActiveSnapshot());
         }
         catch (err) {
@@ -953,6 +1084,7 @@ class AgentVariantsOrchestrator {
                     sourceVariantId: target.variantId,
                     instruction: target.instruction,
                     count: target.count,
+                    ...(target.briefs ? { briefs: target.briefs } : {}),
                     currentHtml,
                     targetElement: target.element,
                     requestId: target.requestId,
@@ -1150,6 +1282,22 @@ class AgentVariantsOrchestrator {
             return false;
         }
     }
+    /**
+     * Resolve the history source for a forked Vary row. If the immediate parent
+     * is an adopted past direction, collapse against that original history row;
+     * otherwise collapse against the same-session parent variant.
+     */
+    resolveHistoryParentVariant(sessionId, sourceVariantId) {
+        if (!sourceVariantId)
+            return undefined;
+        try {
+            const sourceInput = this.store.getWorkItemInput(sessionId, sourceVariantId);
+            return (sourceInput?.adoptedFrom ?? { sessionId, variantId: sourceVariantId });
+        }
+        catch {
+            return { sessionId, variantId: sourceVariantId };
+        }
+    }
     getVariantPick(sessionId) {
         return this.store.getVariantPick(sessionId);
     }
@@ -1346,6 +1494,33 @@ class AgentVariantsOrchestrator {
     getDevServerPort(sessionId, workItemId) {
         return this.resources.get(sessionId)?.worktrees.get(workItemId)?.port;
     }
+    /**
+     * @effect Resolves the dev server port for a preview request and refreshes
+     *   active-preview retention for that session while the port is still live.
+     */
+    resolveDevServerPortForPreview(sessionId, workItemId) {
+        const port = this.getDevServerPort(sessionId, workItemId);
+        if (typeof port === 'number') {
+            this.touchSession(sessionId);
+        }
+        return port;
+    }
+    /**
+     * True work-item kind for a variant, or undefined when the session/item is
+     * unknown. This is the authoritative routing signal for Vary/refine intakes:
+     * an existing-project `code_gen` variant materialized as a static preview
+     * (registerExistingStaticPreview) DISPLAYS as `static_artifact` and serves
+     * HTML, but must fork via the code_gen/worktree path — HTML presence is not
+     * a valid discriminator.
+     */
+    getVariantWorkItemKind(sessionId, workItemId) {
+        try {
+            return this.store.getWorkItemKind(sessionId, workItemId);
+        }
+        catch {
+            return undefined;
+        }
+    }
     getStaticPreviewHtml(sessionId, workItemId) {
         // Primary: read the materialized index.html from the variant's per-variant
         // directory (written by handleSucceededReport). The directory is the source
@@ -1476,9 +1651,9 @@ class AgentVariantsOrchestrator {
     }
     /**
      * Unified one-call kickoff that collapses propose → report_briefs →
-     * approve. Synthesizes placeholder briefs server-side (the agent's
-     * streamed first-line label replaces them in the UI) and immediately
-     * approves so the session lands in `work_items_ready`.
+     * approve. Uses AI-authored briefs supplied by agent callers, with a
+     * deterministic prompt-derived fallback for human-direct calls, and
+     * immediately approves so the session lands in `work_items_ready`.
      *
      * Supports both existing-project sessions (spawns code_gen work items
      * for the agent to lease) and zero-to-one sessions (spawns
@@ -1523,6 +1698,11 @@ class AgentVariantsOrchestrator {
             count,
             briefs: args.briefs,
             uniqueBriefIds: Boolean(appendSessionId),
+            existingLabels: appendSessionId
+                ? this.store
+                    .getVariants(appendSessionId)
+                    .map((variant) => variant.label)
+                : [],
         });
         let sessionId;
         let variantIds;
@@ -1537,12 +1717,14 @@ class AgentVariantsOrchestrator {
                     ? { variantContext: projectContext.variantContext }
                     : {}),
             };
-            const { createdWorkItemIds } = args.sourceVariantId
-                ? this.store.createForkedCodeGenWorkItems({
-                    ...forkArgs,
-                    sourceVariantId: args.sourceVariantId,
-                })
-                : this.store.appendExistingCodeGenVariants(forkArgs);
+            const { createdWorkItemIds } = this.store.appendCodeGenVariants({
+                ...forkArgs,
+                // Fork parent (Vary on a variant): seeds each new worktree from the
+                // parent's tree instead of the base tree. Absent for a plain append.
+                ...(args.sourceVariantId
+                    ? { sourceVariantId: args.sourceVariantId }
+                    : {}),
+            });
             variantIds = createdWorkItemIds;
             this.startVariantsRound({
                 sessionId,
@@ -1665,31 +1847,42 @@ class AgentVariantsOrchestrator {
         };
     }
     /**
-     * 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.
+     * Build the per-variant briefs for a unified start. Supplied briefs keep
+     * meaningful direction labels, while duplicate or empty labels are made
+     * unique against the visible session rows. 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". `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}`;
+        const runLabel = args.runLabel?.trim() || (0, runLabel_1.deriveRunLabel)(args.prompt);
+        const usedLabels = new Set((args.existingLabels ?? []).map(briefLabelKey));
+        const withUniqueLabel = (brief, slotIndex) => ({
+            ...brief,
+            label: uniquifyBriefLabel({
+                label: brief.label,
+                runLabel,
+                slotIndex,
+                usedLabels,
+            }),
+        });
         if (args.briefs) {
-            return args.briefs.map((b, i) => (0, briefContent_1.normalizeBriefContent)({
+            return args.briefs.map((b, i) => withUniqueLabel((0, briefContent_1.normalizeBriefContent)({
                 briefId: briefId(i),
                 label: b.label,
                 body: b.body,
                 ...(b.visualReferenceUrl
                     ? { visualReferenceUrl: b.visualReferenceUrl }
                     : {}),
-            }));
+            }), i));
         }
-        const runLabel = args.runLabel?.trim() || (0, runLabel_1.deriveRunLabel)(args.prompt);
-        return Array.from({ length: args.count }, (_, i) => ({
+        return Array.from({ length: args.count }, (_, i) => withUniqueLabel({
             briefId: briefId(i),
             label: args.count > 1 ? `${runLabel} ${i + 1}` : runLabel,
             body: synthesizeUnifiedBriefBody(args.prompt, i + 1, args.count),
-        }));
+        }, i));
     }
     /**
      * The active sessionId IF it is an existing-project session for `projectPath`
@@ -2099,10 +2292,10 @@ class AgentVariantsOrchestrator {
         };
     }
     /**
-     * User has reviewed the rendered variants in chat and picked one. Look up
-     * the captured diff, build a VariantPickEnvelope, and enqueue to the
-     * pending-changes channel. Idempotent on (sessionId, variantId): repeating
-     * the call returns duplicate=true without re-enqueueing.
+     * User has reviewed the rendered variants and picked one. Look up the
+     * captured diff or generated project, apply it to the destination, and record
+     * the pick. Idempotent on (sessionId, variantId): repeating the call returns
+     * duplicate=true without applying again.
      */
     async commitVariant(args) {
         // Serialize per-session so two overlapping commits can't both run
@@ -2144,13 +2337,11 @@ class AgentVariantsOrchestrator {
         // without going back through resources (which may have been torn down).
         const existingPick = this.store.getVariantPick(args.sessionId);
         if (existingPick && existingPick.variantId === args.variantId) {
-            // Retry-safe history flip. If the first commit attempt enqueued
-            // successfully but the history-persist task crashed (it's
-            // fire-and-forget — see persistVariantHistoryAtCommit call site),
-            // the chosen variant stays at `completed` instead of `committed`
-            // on disk. Re-run the flip on every duplicate attempt; the
-            // terminal-status guard in `markStatus` makes this safely
-            // idempotent.
+            // Retry-safe history flip. If the first commit attempt applied
+            // successfully but the history-persist task crashed, the chosen variant
+            // stays at `completed` instead of `committed` on disk. Re-run the flip on
+            // every duplicate attempt; the terminal-status guard in `markStatus`
+            // makes this safely idempotent.
             const projectContext = this.store.getProjectContext(args.sessionId);
             let historyProjectPath;
             if (projectContext.kind === 'fresh') {
@@ -2526,10 +2717,8 @@ class AgentVariantsOrchestrator {
                 throw new errors_1.AgentVariantsError('INVALID_STAGE_ACTION', `Variant ${args.variantId} has no captured diff yet — wait for report_variant_complete(succeeded) first`);
             }
             changedFilesCount = countDiffFiles(record.diff);
-            // Apply the diff to the user's working tree right now so the variant
-            // lands on the current branch (uncommitted). Previously this just
-            // enqueued the diff for an agent to apply; non-MCP sessions had no
-            // agent and the variant was effectively lost.
+            // Apply the diff to the user's working tree so the variant lands on the
+            // current branch uncommitted.
             if (!this.worktrees.applyDiffToProject) {
                 throw new errors_1.AgentVariantsError('RUNTIME_VALIDATION_FAILED', 'WorktreeManager does not support applying diffs to the project tree');
             }
@@ -2584,7 +2773,6 @@ class AgentVariantsOrchestrator {
         catch (err) {
             log.warn(`persistVariantHistoryAtCommit failed for session ${args.sessionId}`, err);
         }
-        const enqueueResult = this.adapter.enqueue(envelope);
         resources.committedVariantIds.add(args.variantId);
         // For fresh `new-project` commits the committed variant IS the user's
         // final result — there's no dev server to fall back to. Keep the session
@@ -2610,7 +2798,7 @@ class AgentVariantsOrchestrator {
             isFresh: projectContext.kind === 'fresh',
         });
         this.emitChange();
-        log.info(`Variant ${args.variantId} (${input.briefLabel}) committed by user → enqueued=${enqueueResult.enqueued}`);
+        log.info(`Variant ${args.variantId} (${input.briefLabel}) committed by user`);
         if (!args.skipTeardown) {
             // Once a variant is committed, the unpicked worktrees are no longer
             // useful. Schedule teardown in the background so the agent's
@@ -2620,8 +2808,8 @@ class AgentVariantsOrchestrator {
             });
         }
         return {
-            enqueued: enqueueResult.enqueued,
-            duplicate: enqueueResult.duplicate,
+            enqueued: true,
+            duplicate: false,
             changedFilesCount,
             payloadKind: payload.kind,
             destinationPath: envelopeDestination,
@@ -3249,6 +3437,7 @@ class AgentVariantsOrchestrator {
                     durationMs: Date.now() - previewStartedAt,
                 });
                 log.info(`Variant ${args.workItemId} dev server up on port ${port} (worktree ${args.record.worktreePath}; cmd: ${dev.cmd} ${dev.args.join(' ')})`);
+                this.touchSession(args.sessionId);
                 return port;
             }
             catch (err) {
@@ -3676,6 +3865,7 @@ class AgentVariantsOrchestrator {
             snapshotDir,
             baseDir,
             serve,
+            parentVariant: this.resolveHistoryParentVariant(args.sessionId, input.sourceVariantId),
         });
     }
     /**
@@ -3913,6 +4103,7 @@ class AgentVariantsOrchestrator {
                 designSource: designArtifact?.source,
                 snapshotDir: sourceDir,
                 serve,
+                parentVariant: this.resolveHistoryParentVariant(args.sessionId, input.sourceVariantId),
             });
         }
         finally {
@@ -4437,6 +4628,7 @@ class AgentVariantsOrchestrator {
      * stub dirs at the old paths.
      */
     async stopAllDevServersForSession(resources) {
+        this.clearActivePreviewIdleTimer(resources);
         const stops = [];
         for (const record of resources.worktrees.values()) {
             if (!record.devServerProcess)
@@ -4449,6 +4641,56 @@ class AgentVariantsOrchestrator {
             record.port = undefined;
         }
         await Promise.all(stops);
+        return stops.length;
+    }
+    scheduleActivePreviewIdleTimer(resources) {
+        if (!Number.isFinite(this.activeVariantServerIdleTtlMs) ||
+            this.activeVariantServerIdleTtlMs <= 0) {
+            return;
+        }
+        this.clearActivePreviewIdleTimer(resources);
+        resources.activePreviewIdleTimer = setTimeout(() => {
+            resources.activePreviewIdleTimer = undefined;
+            void this.stopIdleVariantDevServers(resources.sessionId);
+        }, this.activeVariantServerIdleTtlMs);
+        resources.activePreviewIdleTimer.unref?.();
+    }
+    clearActivePreviewIdleTimer(resources) {
+        if (!resources.activePreviewIdleTimer)
+            return;
+        clearTimeout(resources.activePreviewIdleTimer);
+        resources.activePreviewIdleTimer = undefined;
+    }
+    /** @effect Stops idle variant child processes and clears dead preview ports. */
+    async stopIdleVariantDevServers(sessionId) {
+        const resources = this.resources.get(sessionId);
+        if (!resources || resources.cleanupStarted)
+            return;
+        if (resources.activePreviewIdleStop) {
+            await resources.activePreviewIdleStop;
+            return;
+        }
+        const stop = (async () => {
+            const stoppedCount = await this.stopAllDevServersForSession(resources);
+            if (stoppedCount === 0)
+                return;
+            log.info(`Stopped ${stoppedCount} idle variant dev server(s) for session ${sessionId}`);
+            // Keep the current behavior bounded: expired previews become unavailable
+            // until fresh generation or another path explicitly starts servers again.
+            try {
+                this.switchPreviewPort?.(null);
+            }
+            catch (err) {
+                log.warn(`switchPreviewPort(null) after idle variant server cleanup failed for ${sessionId}`, err);
+            }
+            this.emitChange();
+        })().finally(() => {
+            if (resources.activePreviewIdleStop === stop) {
+                resources.activePreviewIdleStop = undefined;
+            }
+        });
+        resources.activePreviewIdleStop = stop;
+        await stop;
     }
     /**
      * Spawn a fresh dev server at the user-facing destinationPath and retarget
@@ -4551,6 +4793,7 @@ class AgentVariantsOrchestrator {
         if (resources.cleanupStarted)
             return;
         resources.cleanupStarted = true;
+        this.clearActivePreviewIdleTimer(resources);
         log.info(`Tearing down session ${sessionId} (reason: ${reason})`);
         // Drain in-flight history persists BEFORE deleting worktrees: a tree
         // snapshot's `git add -A --work-tree <worktree>` racing the deletion
@@ -5779,11 +6022,10 @@ const defaultMaterializeProject = async (sourceWorktreePath, destinationPath) =>
     });
 };
 /**
- * Synthesize a placeholder brief body for a unified start_variants slot.
- * The body must fit `briefSchema.body` (≤ 200 chars, ≥ 1 char). The agent's
- * streamed first-line label replaces this in the UI once code_gen output
- * arrives. Index/total are unused for now but kept in the signature so
- * future diversity hints can be added without a call-site change.
+ * Synthesize a fallback brief body for a human-direct unified start slot.
+ * Agent callers provide structured briefs before starting. Index/total are
+ * unused for now but kept in the signature so future human-direct diversity
+ * hints can be added without a call-site change.
  */
 function synthesizeUnifiedBriefBody(prompt, _index, _total) {
     const trimmed = prompt.trim().replace(/\s+/g, ' ').slice(0, 200);