rivet-design 0.14.11 → 0.14.13

package/dist/agent-variants/WorktreeOrchestrator.js

@@ -29,6 +29,7 @@ const VariantWorkspaceManager_1 = require("./VariantWorkspaceManager");
 const diffQa_1 = require("./diffQa");
 const VariantHistoryService_1 = require("../services/VariantHistoryService");
 const variantContext_1 = require("./variantContext");
+const contextAssets_1 = require("./contextAssets");
 const log = (0, logger_1.createLogger)('AgentVariantsOrchestrator');
 const FRESH_DEV_SERVER_HOST = '127.0.0.1';
 const BRIEF_LABEL_MAX_LENGTH = 48;
@@ -86,6 +87,19 @@ const RECIPE_PORT_SENTINEL = 65535;
 // 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;
+// Startup attempts for a variant's dev server. Attempt 2 covers a transient
+// early exit (with a dependency install first when the output shows
+// module-resolution errors); attempt 3 leaves room for one more port step
+// when a collision persists. Early exits fail fast, so extra attempts cost
+// little wall clock.
+const DEV_SERVER_START_MAX_ATTEMPTS = 3;
+// Auto-restarts allowed after a READY dev server crashes (see the exit
+// handler in startVariantDevServer). Two rescues cover transient crashes;
+// a third crash means the build is genuinely broken, so stop looping.
+const DEV_SERVER_MAX_AUTO_RESTARTS = 2;
+// Grace before an auto-restart so a crashing process's port and file locks
+// are actually released first.
+const DEV_SERVER_RESTART_DELAY_MS = 1_000;
 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
@@ -142,28 +156,16 @@ function withProvisionTimeout(work, timeoutMs) {
     return Promise.race([work, timeout]).finally(() => clearTimeout(timer));
 }
 /**
- * Allowlist of asset file extensions an agent-planned source may have.
- * `assetPlan` is sized for large local *assets* (3D models, images,
- * audio, video, fonts) — never code, dotfiles, secrets, or arbitrary
- * configs. The check is defense-in-depth alongside the path / symlink
- * filters in `copyAssetIntoWorktree`; without it, a prompt-injected
- * source plan could copy readable host files such as SSH keys or
- * project secrets into the generated app.
- *
- * Intentionally excludes `.json`, `.txt`, `.md`, `.csv`: these are
- * common carriers for credentials (`credentials.json`, `.aws/config`,
- * shell history `.txt`, README-shaped secrets) and have no legitimate
- * use as binary preview assets. If a future flow needs structured data
- * it should ship it through the manifest instead of file copy.
+ * File types an agent-authored asset plan may copy into a generated preview.
+ * This allowlist protects an agent-controlled path; caller-selected context
+ * assets use the separate, type-neutral delivery path.
  */
-const ALLOWED_ASSET_EXTENSIONS = new Set([
-    // 3D / models
+const ALLOWED_INERT_ASSET_EXTENSIONS = new Set([
     '.glb',
     '.gltf',
     '.obj',
     '.fbx',
     '.usdz',
-    // images
     '.png',
     '.jpg',
     '.jpeg',
@@ -173,22 +175,18 @@ const ALLOWED_ASSET_EXTENSIONS = new Set([
     '.avif',
     '.bmp',
     '.ico',
-    // video
     '.mp4',
     '.webm',
     '.mov',
-    // audio
     '.mp3',
     '.wav',
     '.ogg',
     '.m4a',
-    // fonts
     '.woff',
     '.woff2',
     '.ttf',
     '.otf',
     '.eot',
-    // PDFs
     '.pdf',
 ]);
 /**
@@ -267,7 +265,7 @@ function copyAssetIntoWorktree(worktreePath, entry, assetSourceRoot) {
         ? entry.source
         : path_1.default.resolve(assetSourceRoot, entry.source);
     const ext = path_1.default.extname(absoluteSource).toLowerCase();
-    if (!ALLOWED_ASSET_EXTENSIONS.has(ext)) {
+    if (!ALLOWED_INERT_ASSET_EXTENSIONS.has(ext)) {
         throw new errors_1.AgentVariantsError('RUNTIME_VALIDATION_FAILED', `assetPlan.source extension '${ext || '(none)'}' is not on the allowlist (got '${entry.source}'). Only inert media/font/document assets may be copied.`);
     }
     // lstat first: a symlink whose target lies outside the source path
@@ -331,7 +329,7 @@ function copyAssetIntoWorktree(worktreePath, entry, assetSourceRoot) {
         throw new errors_1.AgentVariantsError('RUNTIME_VALIDATION_FAILED', `assetPlan.source traverses a sensitive directory and is refused: ${entry.source}`);
     }
     const resolvedExt = path_1.default.extname(resolvedSource).toLowerCase();
-    if (!ALLOWED_ASSET_EXTENSIONS.has(resolvedExt)) {
+    if (!ALLOWED_INERT_ASSET_EXTENSIONS.has(resolvedExt)) {
         throw new errors_1.AgentVariantsError('RUNTIME_VALIDATION_FAILED', `assetPlan.source resolved extension '${resolvedExt || '(none)'}' is not on the allowlist (resolved from '${entry.source}').`);
     }
     const normalizedDest = path_1.default.normalize(entry.destination);
@@ -476,6 +474,7 @@ class AgentVariantsOrchestrator {
     startStaticPreviewServerImpl;
     provisionTimeoutMs;
     activeVariantServerIdleTtlMs;
+    devServerRestartDelayMs;
     resources = new Map();
     /**
      * Committed dev servers from prior sessions that survived teardown. The
@@ -521,6 +520,8 @@ class AgentVariantsOrchestrator {
         this.provisionTimeoutMs = deps.provisionTimeoutMs ?? PROVISION_TIMEOUT_MS;
         this.activeVariantServerIdleTtlMs =
             deps.activeVariantServerIdleTtlMs ?? ACTIVE_VARIANT_SERVER_IDLE_TTL_MS;
+        this.devServerRestartDelayMs =
+            deps.devServerRestartDelayMs ?? DEV_SERVER_RESTART_DELAY_MS;
     }
     // --- Pure delegations (no side effects) ---------------------------------
     propose(args) {
@@ -559,6 +560,7 @@ class AgentVariantsOrchestrator {
                 requestedCount: args.count ?? contracts_1.DEFAULT_VARIANT_COUNT,
             });
         }
+        const designContextCount = projectContext.designContext?.length ?? 0;
         this.telemetry.track('agent_variants.session_started', {
             source: 'mcp',
             sessionId: result.sessionId,
@@ -566,6 +568,8 @@ class AgentVariantsOrchestrator {
             hasTarget: Boolean(args.target),
             targetType: args.target?.type ?? null,
             projectContextKind: args.projectContext?.kind ?? 'existing',
+            design_context_count: designContextCount,
+            design_context_kinds: designContextCount > 0 ? ['design_system'] : [],
         });
         this.emitChange();
         return result;
@@ -697,7 +701,7 @@ class AgentVariantsOrchestrator {
             .filter((source) => source.transport === 'file')
             .map((source) => ({
             path: source.path,
-            ...(source.label ?? source.originalFilename
+            ...((source.label ?? source.originalFilename)
                 ? { label: source.label ?? source.originalFilename }
                 : {}),
         }));
@@ -719,6 +723,9 @@ class AgentVariantsOrchestrator {
                 workItemId: item.workId,
                 kind,
             });
+            const contextAssets = this.resources
+                .get(sessionId)
+                ?.contextAssets.get(item.workId);
             const mode = input.sourceVariantId
                 ? 'vary'
                 : DEFAULT_EXECUTION_MODE_BY_KIND[kind];
@@ -756,6 +763,7 @@ class AgentVariantsOrchestrator {
                     ? { contextBundlePath: input.context.contextBundlePath }
                     : {}),
                 ...(AgentVariantsOrchestrator.contextFilesOf(input.context) ?? {}),
+                ...(contextAssets?.length ? { contextAssets } : {}),
                 completion: kind === 'code_gen'
                     ? { kind: 'worktree_diff' }
                     : { kind: 'static_artifact' },
@@ -1074,12 +1082,12 @@ class AgentVariantsOrchestrator {
         const result = this.store.requestWork(args);
         try {
             this.ensureStaticWorkspaces(args.sessionId, result.leasedWorkItems);
+            this.materializeContextAssets(args.sessionId, result.leasedWorkItems);
         }
         catch (error) {
             for (const item of result.leasedWorkItems) {
-                if (item.kind !== 'static_preview' && item.kind !== 'refine_variant') {
+                if (!isImplementationWorkItemKind(item.kind))
                     continue;
-                }
                 try {
                     this.store.reportComplete({
                         sessionId: args.sessionId,
@@ -1091,7 +1099,7 @@ class AgentVariantsOrchestrator {
                             code: 'RUNTIME_VALIDATION_FAILED',
                             message: error instanceof Error
                                 ? error.message
-                                : 'Failed to assign static variant workspace',
+                                : 'Failed to prepare variant workspace',
                         },
                     });
                 }
@@ -1133,6 +1141,24 @@ class AgentVariantsOrchestrator {
         this.emitChange();
         return decorated;
     }
+    /** @effect Copies caller-supplied context assets into each leased workspace. */
+    materializeContextAssets(sessionId, items) {
+        const resources = this.ensureResources(sessionId);
+        for (const item of items) {
+            if (!isImplementationWorkItemKind(item.kind))
+                continue;
+            const input = (item.input ?? {});
+            const assets = input.context?.contextAssets ?? [];
+            if (assets.length === 0)
+                continue;
+            const workspace = this.getAssignedWorkspace({
+                sessionId,
+                workItemId: item.id,
+                kind: item.kind,
+            });
+            resources.contextAssets.set(item.id, (0, contextAssets_1.materializeContextAssets)({ assets, workspace }));
+        }
+    }
     /**
      * @effect Writes each leased implementation item's server-authored briefing
      * BESIDE its workspace so the coordinating host dispatches workers with a
@@ -1729,8 +1755,8 @@ class AgentVariantsOrchestrator {
      * reclaimed. Other missing-preview causes remain terminal so this path never
      * attempts to restart user-owned or repeatedly failing servers.
      *
-     * @effect Clears the idle marker, starts the worktree dev server, and emits
-     *   preview-state snapshots.
+     * @effect Clears the idle marker and prior crash budget, starts the worktree
+     *   dev server, and emits preview-state snapshots.
      * @deps Uses the live session resources, project context, and dev-server
      *   manager owned by this orchestrator.
      */
@@ -1747,6 +1773,7 @@ class AgentVariantsOrchestrator {
             return undefined;
         }
         resources.previewFailures.delete(workItemId);
+        record.devServerAutoRestarts = 0;
         this.emitChange();
         const projectContext = this.store.getProjectContext(sessionId);
         return this.startVariantDevServer({
@@ -1934,6 +1961,7 @@ class AgentVariantsOrchestrator {
         const projectContext = args.projectContext ?? {
             kind: 'existing',
         };
+        const designContextCount = projectContext.designContext?.length ?? 0;
         // Fresh source-grounded sessions (a captured context bundle on a fresh
         // project) must run through `propose` so the source-research/source_plan
         // flow gates generation; start_variants routes them there before reaching
@@ -2056,6 +2084,8 @@ class AgentVariantsOrchestrator {
                 hasTarget: Boolean(args.target),
                 targetType: args.target?.type ?? null,
                 projectContextKind: projectContext.kind,
+                design_context_count: designContextCount,
+                design_context_kinds: designContextCount > 0 ? ['design_system'] : [],
             });
             sessionId = proposeResult.sessionId;
             scaffoldBaseWorkItemId = approveResult.scaffoldBaseWorkItemId ?? null;
@@ -2245,7 +2275,11 @@ class AgentVariantsOrchestrator {
     async provisionAppendedExistingWorktrees(sessionId, workItemIds) {
         if (workItemIds.length === 0)
             return;
-        await this.withProvisioningTelemetry({ sessionId, kind: 'appended_existing', variantCount: workItemIds.length }, async () => {
+        await this.withProvisioningTelemetry({
+            sessionId,
+            kind: 'appended_existing',
+            variantCount: workItemIds.length,
+        }, async () => {
             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);
@@ -3275,14 +3309,10 @@ class AgentVariantsOrchestrator {
                         ? err.code
                         : 'PROVISION_FAILED',
             });
-            // Best-effort cleanup of any worktrees created before the failure so a
-            // timed-out clone doesn't leak half-provisioned dirs. Fire-and-forget so
-            // the provisioning error returns to the caller immediately — never block
-            // the error on teardown, which itself shells out to git (a wedged repo
-            // could otherwise re-hang the tool on cleanup). The cleanup git calls are
-            // bounded by GIT_OPTS in WorktreeManager, and the next-startup orphan
-            // sweep catches anything created after this point.
-            void this.teardownSession(sessionId, 'cancel').catch((teardownErr) => {
+            // Cancel synchronously before cleanup so a retry does not see this
+            // failed session as active. cancel() schedules teardown without blocking
+            // the provisioning error on git cleanup.
+            void this.cancel({ sessionId, reason: 'provisioning_failed' }).catch((teardownErr) => {
                 log.warn(`cleanup after provisioning failure for ${sessionId} failed`, teardownErr);
             });
             if (timedOut) {
@@ -3744,6 +3774,16 @@ class AgentVariantsOrchestrator {
         if (args.record.port !== undefined && args.record.devServerProcess) {
             return args.record.port;
         }
+        if (!args.autoRestartTimer && args.record.pendingAutoRestart) {
+            clearTimeout(args.record.pendingAutoRestart);
+            args.record.pendingAutoRestart = undefined;
+        }
+        const canContinueStart = () => {
+            const resources = this.resources.get(args.sessionId);
+            const isAutoRestartCancelled = args.autoRestartTimer !== undefined &&
+                args.record.pendingAutoRestart !== args.autoRestartTimer;
+            return Boolean(resources && !resources.cleanupStarted && !isAutoRestartCancelled);
+        };
         // 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.
@@ -3764,35 +3804,99 @@ class AgentVariantsOrchestrator {
         });
         const startPort = await this.resolveDevServerStartPort(args.sessionId, args.isFresh);
         let scanFrom = startPort;
-        const maxAttempts = 2;
+        const maxAttempts = DEV_SERVER_START_MAX_ATTEMPTS;
+        // At most one install-then-retry per start: a second missing-module exit
+        // after a fresh install means the install can't fix it.
+        let installRetried = false;
+        let lastDev;
         for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+            // Teardown can begin while a prior attempt waits for dependency
+            // installation. Do not start more work against a removed worktree.
+            if (!canContinueStart())
+                return undefined;
             let port;
             try {
                 port = await this.worktrees.findFreePortFrom(scanFrom);
                 const dev = await this.resolveDevServer(args.sessionId, args.workItemId, args.record.worktreePath, port, args.isFresh);
+                lastDev = dev;
                 const proc = await this.worktrees.startDevServer(dev.cwd, port, dev.cmd, dev.args, dev.env);
+                // The boot can outlive the session (a cancel during the readiness
+                // wait, or during an auto-restart's delay). At this point the child
+                // isn't on the record yet, so teardown's stop loop can't see it —
+                // kill it here instead of leaking an orphaned dev server.
+                if (!canContinueStart()) {
+                    log.info(`Variant ${args.workItemId} dev server booted after preview cleanup; stopping it`);
+                    void this.worktrees.stopDevServer(proc).catch(() => undefined);
+                    return undefined;
+                }
+                if (args.autoRestartTimer) {
+                    args.record.pendingAutoRestart = undefined;
+                }
                 args.record.port = port;
                 args.record.devServerProcess = proc;
                 args.record.devCommand = dev;
                 // 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".
+                // socket, then bring a replacement up automatically. A ready server
+                // that later crashes is almost always recoverable by a clean restart
+                // (transient OOM, watcher crash, HMR wedge) — without one, every such
+                // crash surfaced as a permanent "preview unavailable" plus a burst of
+                // upstream_lost noise until the user regenerated the variant. The
+                // restart budget keeps a genuinely broken build (crash loop) from
+                // restarting forever. Intentional stops clear `devServerProcess`
+                // before killing, so the guard below filters them out.
                 proc.once('exit', (code, signal) => {
                     if (args.record.devServerProcess !== proc)
                         return;
                     args.record.port = undefined;
                     args.record.devServerProcess = undefined;
-                    this.resources
-                        .get(args.sessionId)
-                        ?.previewFailures.set(args.workItemId, {
+                    const resources = this.resources.get(args.sessionId);
+                    const restartsUsed = args.record.devServerAutoRestarts ?? 0;
+                    const canRestart = restartsUsed < DEV_SERVER_MAX_AUTO_RESTARTS &&
+                        resources !== undefined &&
+                        !resources.cleanupStarted;
+                    log.warn(`Variant ${args.workItemId} dev server exited unexpectedly (code=${code ?? 'null'}, signal=${signal ?? 'null'}); ` +
+                        (canRestart
+                            ? `auto-restarting (${restartsUsed + 1}/${DEV_SERVER_MAX_AUTO_RESTARTS})`
+                            : 'preview disabled'));
+                    if (canRestart) {
+                        args.record.devServerAutoRestarts = restartsUsed + 1;
+                        this.emitChange();
+                        const timer = setTimeout(() => {
+                            // Re-check: the session may have been torn down while the
+                            // restart was pending — don't spawn into a cleaned-up worktree.
+                            const current = this.resources.get(args.sessionId);
+                            if (!current ||
+                                current.cleanupStarted ||
+                                args.record.pendingAutoRestart !== timer) {
+                                return;
+                            }
+                            this.startVariantDevServer({
+                                ...args,
+                                autoRestartTimer: timer,
+                            })
+                                .catch((err) => log.warn(`Auto-restart of variant ${args.workItemId} dev server failed`, err))
+                                .finally(() => {
+                                if (args.record.pendingAutoRestart === timer) {
+                                    args.record.pendingAutoRestart = undefined;
+                                }
+                            });
+                        }, this.devServerRestartDelayMs);
+                        args.record.pendingAutoRestart = timer;
+                        timer.unref?.();
+                        return;
+                    }
+                    resources?.previewFailures.set(args.workItemId, {
                         reason: 'exited',
                         portInUse: false,
                     });
-                    log.warn(`Variant ${args.workItemId} dev server exited unexpectedly (code=${code ?? 'null'}, signal=${signal ?? 'null'}); preview disabled`);
                     this.emitChange();
                 });
+                // A prior failure record (startup failure before a successful retry,
+                // idle reclaim, crash before this restart) is now stale.
+                this.resources
+                    .get(args.sessionId)
+                    ?.previewFailures.delete(args.workItemId);
                 this.emitChange();
                 trackFreshDevServerStarted(this.telemetry, {
                     sessionId: args.sessionId,
@@ -3813,19 +3917,54 @@ class AgentVariantsOrchestrator {
                 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;
+                if (!canContinueStart())
+                    return undefined;
+                const devErr = (0, devServerError_1.isDevServerStartError)(err) ? err : undefined;
+                const portInUse = devErr?.portInUse ?? false;
+                const reason = devErr?.reason ?? 'unknown';
+                // Classify what a retry can actually fix:
+                // - port_in_use: a fresh port fixes it (also step past unmatched
+                //   collision messages via the blanket exited retry below).
+                // - missing/stale dependencies (module-resolution errors in the
+                //   output): an install fixes it — install, then retry once.
+                // - any other early exit: retry once; exits fail fast, so one clean
+                //   attempt is cheap insurance against transient races (fs churn from
+                //   sibling provisioning, npm cache contention).
+                // - timeout / spawn_error / missing_dev_script: deterministic; a
+                //   retry just doubles the wait, so fail with the actionable cause.
+                const missingDepsOutput = (0, devServerError_1.isMissingDependencyOutput)(devErr?.detail ?? '');
+                const missingDeps = missingDepsOutput &&
+                    reason === 'exited' &&
+                    !installRetried &&
+                    lastDev !== undefined &&
+                    canInstallWithoutTouchingHost(lastDev.cwd);
+                const willRetry = attempt < maxAttempts &&
+                    (portInUse || missingDeps || (reason === 'exited' && attempt === 1));
                 // 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})` +
+                    `(attempt ${attempt}/${maxAttempts}, reason=${reason}, portInUse=${portInUse}, missingDeps=${missingDeps})` +
                     (willRetry
-                        ? '; retrying on a fresh port'
+                        ? missingDeps
+                            ? '; installing dependencies and retrying'
+                            : '; retrying on a fresh port'
                         : '; live preview disabled for this variant'), err);
-                if (willRetry)
+                if (willRetry) {
+                    if (missingDeps && lastDev) {
+                        installRetried = true;
+                        try {
+                            await this.installDependencies(lastDev.cwd, lastDev.packageManager);
+                        }
+                        catch (installErr) {
+                            // Still retry: the boot error may have been transient, and the
+                            // retry's own failure telemetry is more specific than aborting
+                            // here on the install's stderr.
+                            log.warn(`Dependency install before dev-server retry failed for variant ${args.workItemId}`, installErr);
+                        }
+                    }
                     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.
@@ -3835,22 +3974,35 @@ class AgentVariantsOrchestrator {
                     reason,
                     portInUse,
                 });
+                const errorCode = reason === 'missing_dev_script'
+                    ? 'DEV_SCRIPT_MISSING'
+                    : 'DEV_SERVER_START_FAILED';
+                // Telemetry gets structured classification only — never the raw
+                // output tail, which routinely carries absolute project paths and
+                // source frames (see AGENTS.md "What NEVER to capture"). The full
+                // tail still reaches the local logs via `err` above.
                 trackFreshDevServerFailed(this.telemetry, {
                     sessionId: args.sessionId,
                     variantId: args.workItemId,
-                    errorCode: 'DEV_SERVER_START_FAILED',
+                    errorCode,
                     reason,
                     portInUse,
+                    exitCode: devErr?.exitCode,
+                    signal: devErr?.signal,
+                    missingDeps: missingDepsOutput,
                 });
                 trackPreviewFailed(this.telemetry, {
                     sessionId: args.sessionId,
                     variantId: args.workItemId,
                     projectContextKind,
                     previewKind: 'dev_server',
-                    errorCode: 'DEV_SERVER_START_FAILED',
+                    errorCode,
                     reason,
                     portInUse,
                     durationMs: Date.now() - previewStartedAt,
+                    exitCode: devErr?.exitCode,
+                    signal: devErr?.signal,
+                    missingDeps: missingDepsOutput,
                 });
                 this.emitChange();
                 return undefined;
@@ -4238,7 +4390,7 @@ class AgentVariantsOrchestrator {
             label: input.briefLabel,
             brief: input.briefBody,
             sessionPrompt,
-            runLabel: this.store.getRunLabel(args.sessionId),
+            runLabel: input.runLabel ?? this.store.getRunLabel(args.sessionId),
             kind: 'diff',
             diff: args.diff,
             sourceDir,
@@ -4483,7 +4635,7 @@ class AgentVariantsOrchestrator {
                 label: input.briefLabel,
                 brief: input.briefBody,
                 sessionPrompt,
-                runLabel: this.store.getRunLabel(args.sessionId),
+                runLabel: input.runLabel ?? this.store.getRunLabel(args.sessionId),
                 kind: 'project-created',
                 sourceDir,
                 preview,
@@ -4725,6 +4877,12 @@ class AgentVariantsOrchestrator {
         const env = await this.resolveEnv(sessionId);
         const cwd = await this.resolveExistingProjectCwd(sessionId, worktreePath, env);
         const packageManager = detectPackageManagerForCwd(cwd, env.packageManager);
+        // Every branch below — including the production buildDevCommand recipes
+        // from utils/devServerCommand.ts — invokes the package.json script named
+        // by env.devCommand, so the preflight applies to all of them.
+        if (env.devCommand) {
+            assertDevScriptExists(cwd, env.devCommand);
+        }
         if (packageManager !== env.packageManager) {
             return {
                 cwd,
@@ -5026,6 +5184,10 @@ class AgentVariantsOrchestrator {
         this.clearActivePreviewIdleTimer(resources);
         const stops = [];
         for (const record of resources.worktrees.values()) {
+            if (record.pendingAutoRestart) {
+                clearTimeout(record.pendingAutoRestart);
+                record.pendingAutoRestart = undefined;
+            }
             if (!record.devServerProcess)
                 continue;
             const proc = record.devServerProcess;
@@ -5070,11 +5232,12 @@ class AgentVariantsOrchestrator {
             return;
         }
         const stop = (async () => {
-            const expiringWorkItemIds = Array.from(resources.worktrees.values())
-                .filter((record) => Boolean(record.devServerProcess))
-                .map((record) => record.workItemId);
+            const expiringRecords = Array.from(resources.worktrees.values()).filter((record) => Boolean(record.devServerProcess) ||
+                Boolean(record.pendingAutoRestart));
+            const expiringWorkItemIds = expiringRecords.map((record) => record.workItemId);
+            const pendingRestartCount = expiringRecords.filter((record) => Boolean(record.pendingAutoRestart)).length;
             const stoppedCount = await this.stopAllDevServersForSession(resources);
-            if (stoppedCount === 0)
+            if (expiringWorkItemIds.length === 0)
                 return;
             for (const workItemId of expiringWorkItemIds) {
                 resources.previewFailures.set(workItemId, {
@@ -5082,7 +5245,8 @@ class AgentVariantsOrchestrator {
                     portInUse: false,
                 });
             }
-            log.info(`Stopped ${stoppedCount} idle variant dev server(s) for session ${sessionId}`);
+            log.info(`Reclaimed ${expiringWorkItemIds.length} idle variant preview(s) for session ${sessionId} ` +
+                `(${stoppedCount} running, ${pendingRestartCount} restarting)`);
             // The next selection restores only the requested Rivet-owned preview;
             // siblings remain stopped until the user asks to view them.
             try {
@@ -5297,6 +5461,7 @@ class AgentVariantsOrchestrator {
                 worktrees: new Map(),
                 staticPreviews: new Map(),
                 workspaceManager: new VariantWorkspaceManager_1.VariantWorkspaceManager(),
+                contextAssets: new Map(),
                 cleanupStarted: false,
                 committedVariantIds: new Set(),
                 startedAt: Date.now(),
@@ -6117,6 +6282,9 @@ const trackFreshDevServerFailed = (telemetry, data) => {
         error_code: data.errorCode,
         failure_reason: data.reason,
         port_in_use: data.portInUse,
+        exit_code: data.exitCode,
+        term_signal: data.signal,
+        missing_deps: data.missingDeps,
     });
 };
 const trackPreviewStarted = (telemetry, data) => {
@@ -6163,6 +6331,9 @@ const trackPreviewFailed = (telemetry, data) => {
         failure_reason: data.reason,
         port_in_use: data.portInUse,
         duration_ms: data.durationMs,
+        exit_code: data.exitCode,
+        term_signal: data.signal,
+        missing_deps: data.missingDeps,
     });
 };
 const trackStaticPreviewCompleted = (telemetry, data) => {
@@ -6191,7 +6362,7 @@ const STATIC_PREVIEW_HISTORY_EXCLUDE = new Set([
     '.rivet',
 ]);
 const STATIC_PREVIEW_HISTORY_FILE_EXTENSIONS = new Set([
-    ...ALLOWED_ASSET_EXTENSIONS,
+    ...ALLOWED_INERT_ASSET_EXTENSIONS,
     '.css',
     '.htm',
     '.html',
@@ -6301,6 +6472,60 @@ const buildServeRecipeFromResolved = (snapshotRoot, dev, port) => {
         envTemplate: Object.fromEntries(Object.entries(dev.env).map(([key, value]) => [key, sub(value)])),
     };
 };
+/**
+ * Whether an install at `cwd` stays inside the Rivet-owned worktree.
+ * Existing-project worktrees SYMLINK `node_modules` to the user's real
+ * install (WorktreeManager.symlinkNodeModulesIfAvailable) — running a
+ * package manager through that link would mutate the user's project
+ * dependencies, which the variants flow must never do. Install is safe only
+ * when `node_modules` is absent (a nested standalone package — the install
+ * creates a worktree-local dir) or a real directory owned by the worktree.
+ */
+const canInstallWithoutTouchingHost = (cwd) => {
+    try {
+        return !fs_1.default.lstatSync(path_1.default.join(cwd, 'node_modules')).isSymbolicLink();
+    }
+    catch {
+        return true;
+    }
+};
+/**
+ * Fail fast — before spawning anything — when the package.json at `cwd`
+ * positively lacks the dev script we're about to invoke. Without this the
+ * spawn exits with the package manager's "missing script" error after a full
+ * boot round-trip and surfaces as an opaque `exited` failure; with it the
+ * user gets an actionable message naming the scripts that DO exist. Missing
+ * or unparseable package.json is NOT treated as a failure here — other paths
+ * own those cases, and the spawn's own error is more specific.
+ */
+const assertDevScriptExists = (cwd, scriptName) => {
+    let scripts;
+    try {
+        const raw = fs_1.default.readFileSync(path_1.default.join(cwd, 'package.json'), 'utf8');
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === 'object' && 'scripts' in parsed) {
+            const candidate = parsed.scripts;
+            if (candidate && typeof candidate === 'object') {
+                scripts = candidate;
+            }
+        }
+    }
+    catch {
+        return;
+    }
+    if (scripts && typeof scripts[scriptName] === 'string')
+        return;
+    const available = Object.keys(scripts ?? {});
+    throw new devServerError_1.DevServerStartError({
+        message: `package.json at ${cwd} has no "${scriptName}" script` +
+            (available.length ? ` (available: ${available.join(', ')})` : ''),
+        reason: 'missing_dev_script',
+        portInUse: false,
+        detail: available.length
+            ? `available scripts: ${available.join(', ')}`
+            : '',
+    });
+};
 const buildExistingProjectDevCommand = (packageManager, devCommand, port) => {
     const env = { PORT: String(port) };
     if (packageManager === 'npm') {