rivet-design 0.17.3 → 0.17.5

package/dist/agent-variants/WorktreeOrchestrator.js

@@ -10,7 +10,9 @@ const events_1 = require("events");
 const fs_1 = __importDefault(require("fs"));
 const os_1 = __importDefault(require("os"));
 const path_1 = __importDefault(require("path"));
-const child_process_1 = require("child_process");
+const DependencyPreparationService_1 = require("../services/DependencyPreparationService");
+const ProjectPackageManager_1 = require("../services/ProjectPackageManager");
+const devServerCommand_1 = require("../utils/devServerCommand");
 const simple_git_1 = require("simple-git");
 const logger_1 = require("../utils/logger");
 const devServerError_1 = require("../utils/devServerError");
@@ -73,44 +75,14 @@ const FALLBACK_DIRECTION_FOCI = [
     'Explore tactile depth, layering, and purposeful interaction cues.',
     'Reduce the concept to its most essential typography and geometry.',
 ];
-// 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
-// timeout) can't make commit/cancel appear hung.
 const SETTLE_PERSISTS_TEARDOWN_TIMEOUT_MS = 20_000;
-// Sentinel port for deriving a persist-time serve recipe when the dev server
-// hasn't booted yet: resolved into the command, then reverse-substituted to
-// the ${PORT} placeholder. Digit-boundary-guarded substitution means only an
-// exact standalone occurrence is replaced, and 65535 never appears in any
-// framework's default invocation.
 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
-// stall the `start_variants` / `approve_variant_briefs` tool call indefinitely.
-// Existing-project provisioning clones the host working tree once per variant
-// (`git worktree add` + untracked-file copy), so its cost scales with repo
-// size — a big monorepo (or a React Native tree with native build dirs) used to
-// hang the call for 15+ minutes with no signal. With this bound the call fails
-// fast and legibly instead. Per-git-op hangs are already caught by simple-git's
-// block timeout in WorktreeManager; this is the cross-op backstop. Override via
-// env for unusually large repos.
 const DEFAULT_PROVISION_TIMEOUT_MS = 540_000;
 const PROVISION_TIMEOUT_MS = (() => {
     const raw = process.env.RIVET_VARIANTS_PROVISION_TIMEOUT_MS;
@@ -119,10 +91,6 @@ 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;
@@ -131,7 +99,6 @@ const ACTIVE_VARIANT_SERVER_IDLE_TTL_MS = (() => {
         ? parsed
         : DEFAULT_ACTIVE_VARIANT_SERVER_IDLE_TTL_MS;
 })();
-/** Sentinel so callers can distinguish a provisioning timeout from other errors. */
 class ProvisionTimeoutError extends Error {
     timeoutMs;
     constructor(timeoutMs) {
@@ -140,12 +107,6 @@ class ProvisionTimeoutError extends Error {
         this.name = 'ProvisionTimeoutError';
     }
 }
-/**
- * Reject with `ProvisionTimeoutError` if `work` hasn't settled within
- * `timeoutMs`. The underlying work is NOT cancellable (git/fs I/O), so it may
- * keep running after we reject — callers should best-effort clean up partial
- * state. The timer is unref'd so it never keeps the process alive on its own.
- */
 function withProvisionTimeout(work, timeoutMs) {
     let timer;
     const timeout = new Promise((_, reject) => {
@@ -155,11 +116,6 @@ function withProvisionTimeout(work, timeoutMs) {
     });
     return Promise.race([work, timeout]).finally(() => clearTimeout(timer));
 }
-/**
- * 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_INERT_ASSET_EXTENSIONS = new Set([
     '.glb',
     '.gltf',
@@ -189,13 +145,6 @@ const ALLOWED_INERT_ASSET_EXTENSIONS = new Set([
     '.eot',
     '.pdf',
 ]);
-/**
- * Reject paths that traverse through a "sensitive" directory anywhere
- * in their ancestry — `.ssh`, `.aws`, `.config`, `.gnupg`, etc. Even if
- * a copy passes the extension allowlist, an agent-controlled source
- * resolving inside `~/.ssh/` is almost certainly an exfiltration
- * attempt rather than a legitimate asset reference.
- */
 const SENSITIVE_PATH_SEGMENTS = new Set([
     '.ssh',
     '.aws',
@@ -212,14 +161,9 @@ const SENSITIVE_PATH_SEGMENTS = new Set([
     'credentials',
 ]);
 function hasSensitivePathSegment(absolutePath) {
-    // Split on any path separator; check each segment case-insensitively.
     const segments = absolutePath.split(/[/\\]/).filter(Boolean);
     return segments.some((segment) => SENSITIVE_PATH_SEGMENTS.has(segment.toLowerCase()));
 }
-/**
- * Returns true when `absolutePath` is the root itself or one of its
- * descendants after both paths have been resolved.
- */
 function isPathWithinRoot(absolutePath, root) {
     const relative = path_1.default.relative(root, absolutePath);
     return (relative === '' ||
@@ -227,25 +171,6 @@ function isPathWithinRoot(absolutePath, root) {
             !relative.startsWith('..') &&
             !path_1.default.isAbsolute(relative)));
 }
-/**
- * Copy one agent-planned asset file into a variant worktree at the
- * project-relative `destination`. The agent decides routing
- * (`destination` like `public/assets/avatar.glb`) so all variants share
- * a consistent layout. Fails loudly when the source is missing or the
- * destination tries to escape the worktree — silent fallbacks here
- * would re-introduce the broken-asset failure mode this routing is
- * supposed to prevent.
- *
- * Security: `entry.source` comes from `report_source_plan` and is
- * agent-controlled. To prevent a prompt-injected source plan from
- * exfiltrating arbitrary readable host files (SSH keys, dotfiles,
- * cloud credentials, project secrets) into the generated app, the
- * source must (1) be an absolute path that resolves via realpath
- * (no traversal, no symlinks pointing outside the resolved location),
- * (2) be a regular file (not a device, socket, fifo, or directory),
- * (3) live under the approved asset root, (4) have an extension on the
- * asset allowlist.
- */
 function copyAssetIntoWorktree(worktreePath, entry, assetSourceRoot) {
     if (!assetSourceRoot) {
         throw new errors_1.AgentVariantsError('RUNTIME_VALIDATION_FAILED', `assetPlan.source requires an approved asset root before copying '${entry.source}'`);
@@ -253,14 +178,6 @@ function copyAssetIntoWorktree(worktreePath, entry, assetSourceRoot) {
     if (!path_1.default.isAbsolute(assetSourceRoot)) {
         throw new errors_1.AgentVariantsError('RUNTIME_VALIDATION_FAILED', `assetSourceRoot must be an absolute path, got '${assetSourceRoot}'`);
     }
-    // A relative source is resolved against the approved asset root. The
-    // agent-facing protocol requires the source to live under that root but not
-    // to be absolute, and the root path is internal to Rivet (a staged context
-    // bundle) — so a relative name such as 'avatar.glb' is the natural, safe
-    // form. Every downstream guard (symlink, extension, within-root, sensitive
-    // segments) runs against this resolved absolute path, so the resolution
-    // cannot widen what is copyable: a relative `..` escape still fails the
-    // within-root check below.
     const absoluteSource = path_1.default.isAbsolute(entry.source)
         ? entry.source
         : path_1.default.resolve(assetSourceRoot, entry.source);
@@ -268,10 +185,6 @@ function copyAssetIntoWorktree(worktreePath, entry, assetSourceRoot) {
     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
-    // could otherwise smuggle in arbitrary files. Reject symlinks outright;
-    // realpath would resolve them but the user-visible intent of an
-    // assetPlan entry is to name a concrete file.
     let lstat;
     try {
         lstat = fs_1.default.lstatSync(absoluteSource);
@@ -285,9 +198,6 @@ function copyAssetIntoWorktree(worktreePath, entry, assetSourceRoot) {
     if (!lstat.isFile()) {
         throw new errors_1.AgentVariantsError('RUNTIME_VALIDATION_FAILED', `assetPlan.source must be a regular file: ${entry.source}`);
     }
-    // Resolve realpath as additional defense: even with no symlinks at the
-    // leaf, an intermediate directory could be a symlink. Cross-check the
-    // file kind on the resolved path.
     let resolvedSource;
     try {
         resolvedSource = fs_1.default.realpathSync(absoluteSource);
@@ -306,24 +216,9 @@ function copyAssetIntoWorktree(worktreePath, entry, assetSourceRoot) {
     if (!resolvedStat.isFile()) {
         throw new errors_1.AgentVariantsError('RUNTIME_VALIDATION_FAILED', `assetPlan.source resolved target must be a regular file: ${entry.source}`);
     }
-    // Containment is the security boundary and must be checked before any
-    // sensitive-segment scan. The approved asset root is system-chosen and
-    // trusted (a staged context bundle), and its realpath can legitimately
-    // pass through a "sensitive" segment that is NOT agent-controlled — on
-    // macOS `fs.realpathSync(os.tmpdir())` resolves to `/private/var/folders/...`,
-    // so the temp-staged root contains `private`. A symlinked intermediate dir
-    // that forwards into a sensitive ancestor (e.g. `<asset-root>/avatar -> ~/.ssh`)
-    // pushes the realpath OUTSIDE the root and is rejected here.
     if (!isPathWithinRoot(resolvedSource, resolvedAssetSourceRoot)) {
         throw new errors_1.AgentVariantsError('RUNTIME_VALIDATION_FAILED', `assetPlan.source must stay inside the approved asset root: ${entry.source}`);
     }
-    // Sensitive-segment defense, scoped to the agent-controlled portion BELOW
-    // the trusted root. Only this relative remainder is chosen by the agent's
-    // source plan, so a sensitive segment it introduces under the root (a real
-    // `<asset-root>/.ssh/key.glb`, or a within-root symlink that realpaths into
-    // one) is still refused, while the trusted root prefix is never scanned.
-    // `resolvedSource` is the fully symlink-resolved real path, so the scan
-    // covers what the file actually resolves to, not just its literal name.
     const relativeResolvedSource = path_1.default.relative(resolvedAssetSourceRoot, resolvedSource);
     if (hasSensitivePathSegment(relativeResolvedSource)) {
         throw new errors_1.AgentVariantsError('RUNTIME_VALIDATION_FAILED', `assetPlan.source traverses a sensitive directory and is refused: ${entry.source}`);
@@ -341,7 +236,6 @@ function copyAssetIntoWorktree(worktreePath, entry, assetSourceRoot) {
     fs_1.default.copyFileSync(resolvedSource, absDest);
 }
 const defaultPreviewQaRunner = ({ html }) => (0, previewQa_1.runPreviewQa)({ html });
-/** Disabled-reason copy for a variant whose preview cannot be opened. */
 const buildViewDisabledReason = (args) => {
     if (args.status === 'failed') {
         return args.qa?.summary ?? 'Generation failed';
@@ -365,11 +259,9 @@ 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.';
-/** Separates invalid worker output from a Rivet check that could not run. */
 const qaFailureErrorCode = (qa) => qa.issues.some((issue) => issue.kind === 'verification_unavailable')
     ? 'VARIANT_VERIFICATION_UNAVAILABLE'
     : 'VARIANT_QA_FAILED';
-/** Identifies a repair-triggering completion across transport retries. */
 const repairCompletionKey = (args) => JSON.stringify([args.workItemId, args.leaseId, args.attempt, 'succeeded']);
 const briefLabelKey = (value) => value.trim().toLowerCase().replace(/\s+/g, ' ');
 const truncateBriefLabel = (value) => {
@@ -450,17 +342,6 @@ const isDesignCreationCodeGenInput = (input, prompt) => {
     return (DESIGN_CREATION_ACTION_RE.test(text) &&
         DESIGN_CREATION_SURFACE_RE.test(text));
 };
-/**
- * Wraps SessionStore for the operations that have side effects: approve
- * (provision worktrees), reportComplete (capture diff), 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 CLI can commit the chosen output directly.
- */
 class AgentVariantsOrchestrator {
     store;
     worktrees;
@@ -477,31 +358,9 @@ class AgentVariantsOrchestrator {
     activeVariantServerIdleTtlMs;
     devServerRestartDelayMs;
     resources = new Map();
-    /**
-     * Committed dev servers from prior sessions that survived teardown. The
-     * orchestrator outlives any single session — once a new session starts, the
-     * prior committed dev server is no longer needed (the next session opens
-     * its own preview chip), so stop it before the new session's first preview
-     * goes live. Keyed by sessionId for diagnostics; values are kept alive
-     * intentionally between commit and next `propose` / `shutdown`.
-     */
     lingeringCommittedDevServers = new Map();
-    /**
-     * Per-session in-flight commit chain. Two overlapping commitVariant calls
-     * would otherwise both pass the `getVariantPick` idempotency check (the
-     * pick isn't recorded until after `applyDiffToProject`) and double-invoke
-     * `git apply` — which corrupts the working tree on the second run. The
-     * chain serializes commits per session so the second caller waits for the
-     * first to finish and then hits the idempotency check (returning
-     * `duplicate: true` for the same variantId, or `PENDING_CHANGE_CONFLICT`
-     * for a different one).
-     */
     inflightCommits = new Map();
-    /** Most recent agent-variants sessionId — read by the iframe chip via
-     *  GET /api/variants/active. Cleared on cancel or commit. */
     activeSessionId = null;
-    /** Push channel for the iframe chip's SSE subscription. Emits an
-     *  ActiveSnapshot on every state change so the chip never has to poll. */
     events = new events_1.EventEmitter();
     constructor(deps) {
         this.store = deps.store;
@@ -524,11 +383,7 @@ class AgentVariantsOrchestrator {
         this.devServerRestartDelayMs =
             deps.devServerRestartDelayMs ?? DEV_SERVER_RESTART_DELAY_MS;
     }
-    // --- Pure delegations (no side effects) ---------------------------------
     propose(args) {
-        // A new session means any lingering committed dev server from a prior
-        // session is no longer needed — the next session opens its own preview.
-        // Best-effort stop; failures here don't block propose.
         void this.stopLingeringCommittedDevServers().catch((err) => {
             log.warn('Stopping lingering committed dev servers failed', err);
         });
@@ -575,36 +430,18 @@ class AgentVariantsOrchestrator {
         this.emitChange();
         return result;
     }
-    /** Returns the most recent agent-variants sessionId (or null). */
     getActiveSessionId() {
         return this.activeSessionId;
     }
-    /** Subscribe to active-snapshot pushes. Returns an unsubscribe fn. */
     subscribeToEvents(listener) {
         this.events.on('change', listener);
         return () => {
             this.events.off('change', listener);
         };
     }
-    /** Number of live Rivet UI clients subscribed to the variants SSE stream.
-     *  A subscribed client means a Rivet page is open in the browser. */
     uiClientCount = 0;
-    /** Wall-clock of the last UI-client connect/disconnect. `hasUiClients`
-     *  treats a very recent disconnect as still-connected to ride out the brief
-     *  gap when an EventSource drops and auto-reconnects (default retry ~3s) —
-     *  otherwise a `propose`/`start` landing in that window reads zero clients
-     *  and spawns a duplicate browser tab. */
     lastUiClientActivityAt = 0;
-    /** Grace window covering an EventSource reconnect (its default retry is ~3s;
-     *  the SSE heartbeat is 30s). Long enough to span a reconnect, short enough
-     *  that a genuine page close frees the "reopen on next propose" path quickly. */
     static UI_CLIENT_GRACE_MS = 6000;
-    /**
-     * Register a live Rivet UI client (called when the variants SSE stream opens).
-     * Returns a release fn to call on disconnect. Used as the "a Rivet page is
-     * already open" signal so the MCP server can avoid spawning a duplicate tab
-     * every time the variants flow re-enters an already-active editor session.
-     */
     registerUiClient() {
         this.uiClientCount += 1;
         this.lastUiClientActivityAt = Date.now();
@@ -618,8 +455,6 @@ class AgentVariantsOrchestrator {
             this.lastUiClientActivityAt = Date.now();
         };
     }
-    /** True when at least one Rivet UI page is currently connected — or one
-     *  disconnected within the grace window (an EventSource mid-reconnect). */
     hasUiClients() {
         if (this.uiClientCount > 0)
             return true;
@@ -628,21 +463,17 @@ 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() {
         const sessionId = this.activeSessionId;
         if (!sessionId || !this.store.hasSession(sessionId)) {
@@ -681,22 +512,12 @@ class AgentVariantsOrchestrator {
             ...(workerRuntime ? { workerRuntime } : {}),
         };
     }
-    /** Record which worker runtime this session's current batch leases to —
-     *  called by the generation services right after the lease-owner decision
-     *  so `variants start`/status can answer "what is running these?". */
     setWorkerRuntime(sessionId, summary) {
         if (!this.store.hasSession(sessionId))
             return;
         this.store.setWorkerRuntime(sessionId, summary);
-        // Push a fresh snapshot to SSE subscribers: startUnified/requestWork
-        // already emitted before this setter ran, and without an emit here a
-        // subscribed client would not see workerRuntime until the next state
-        // transition (possibly the first worker completion).
         this.emitChange();
     }
-    /** User reference files stored in the work item's context bundle (uploaded
-     *  or copied local images). Surfaced on the snapshot so briefings can point
-     *  workers at the files directly — one Read instead of a bundle walk. */
     static contextFilesOf(context) {
         const files = (context?.userContext ?? [])
             .filter((source) => source.transport === 'file')
@@ -1048,8 +869,6 @@ class AgentVariantsOrchestrator {
         if (projectContext.variantContext) {
             (0, variantContext_1.writeVariantContextBundle)(projectContext.variantContext);
         }
-        // Source-context quality is now measured off the raw context bundle plus
-        // the action metadata the agent reported, not the legacy summary fields.
         const bundle = projectContext.kind === 'fresh'
             ? projectContext.variantContext
             : undefined;
@@ -1111,9 +930,6 @@ class AgentVariantsOrchestrator {
             }
             throw error;
         }
-        // Record lease times so variant_completed can report lease→report
-        // duration. (We don't fire a separate code_gen_leased event — the
-        // funnel signal we care about is per-variant completion duration.)
         const resources = this.resources.get(args.sessionId);
         if (resources) {
             const now = Date.now();
@@ -1123,10 +939,6 @@ class AgentVariantsOrchestrator {
         }
         this.writeLeasedWorkItemBriefings(args.sessionId, result.leasedWorkItems.map((item) => item.id));
         this.trackRefinementLeased({ sessionId: args.sessionId, lease: result });
-        // Decorate each leased item's input with the worktreePath provisioned
-        // by approve(). The skill instructs agents to write files to
-        // `input.worktreePath` — without this decoration that field would be
-        // missing and the agent would have no idea where to edit.
         const decorated = {
             ...result,
             leasedWorkItems: result.leasedWorkItems.map((item) => {
@@ -1143,7 +955,6 @@ 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) {
@@ -1164,10 +975,6 @@ class AgentVariantsOrchestrator {
             resources.contextAssets.set(item.id, (0, contextAssets_1.materializeContextAssets)({ assets, workspace, previewKind }));
         }
     }
-    /**
-     * @effect Records how an existing project's worktrees will be previewed so
-     * context assets receive references that resolve on that serving surface.
-     */
     async resolveContextAssetPreviewKind(sessionId) {
         const resources = this.ensureResources(sessionId);
         try {
@@ -1180,13 +987,6 @@ class AgentVariantsOrchestrator {
             log.warn(`Failed to resolve context asset preview kind for ${sessionId}; using dev-server references`, error);
         }
     }
-    /**
-     * @effect Writes each leased implementation item's server-authored briefing
-     * BESIDE its workspace so the coordinating host dispatches workers with a
-     * short pointer prompt instead of composing prose per worker. Best-effort:
-     * a briefing write failure never blocks the lease (the host guidance's
-     * packet fields still carry the same data).
-     */
     writeLeasedWorkItemBriefings(sessionId, leasedWorkItemIds) {
         if (leasedWorkItemIds.length === 0)
             return;
@@ -1216,13 +1016,9 @@ class AgentVariantsOrchestrator {
             }
         }
     }
-    /** @effect Assigns isolated, server-owned artifact workspaces to leased static work. */
     ensureStaticWorkspaces(sessionId, items) {
         const resources = this.ensureResources(sessionId);
         const projectContext = this.store.getProjectContext(sessionId);
-        // This lane provisions by copying the source artifact tree (vary forks) or
-        // seeding an entry file — it bypasses provisionWorktrees, so it gets its
-        // own provisioning telemetry here.
         const provisionStartedAt = Date.now();
         let assignedCount = 0;
         for (const item of items) {
@@ -1269,7 +1065,6 @@ class AgentVariantsOrchestrator {
             });
         }
     }
-    /** Reads a completed static artifact while enforcing its assigned directory boundary. */
     readAssignedStaticArtifact(sessionId, workItemId) {
         const workspaceManager = this.resources.get(sessionId)?.workspaceManager;
         if (!workspaceManager) {
@@ -1279,15 +1074,7 @@ 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))
@@ -1308,9 +1095,6 @@ class AgentVariantsOrchestrator {
             });
             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,
@@ -1325,8 +1109,6 @@ class AgentVariantsOrchestrator {
                     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({
@@ -1336,8 +1118,6 @@ class AgentVariantsOrchestrator {
                             fidelity: target.fidelity,
                         });
                         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,
@@ -1357,9 +1137,6 @@ class AgentVariantsOrchestrator {
                 }
                 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 {
                 const forks = this.store.createForkedStaticPreviewWorkItems({
                     sessionId: args.sessionId,
@@ -1377,11 +1154,6 @@ class AgentVariantsOrchestrator {
                 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' ||
                         error.code === 'VARIANT_NOT_EDITABLE')) {
@@ -1408,24 +1180,6 @@ class AgentVariantsOrchestrator {
         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 and
-     * `entryPath` is its selected HTML document. 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, args.entryPath);
         const append = this.store.appendAdoptedStaticVariant({
@@ -1443,8 +1197,6 @@ class AgentVariantsOrchestrator {
             requestedCount: 1,
             sourceVariantId: args.source.variantId,
         });
-        // 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,
@@ -1469,11 +1221,6 @@ class AgentVariantsOrchestrator {
             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) {
@@ -1554,12 +1301,6 @@ class AgentVariantsOrchestrator {
         }
         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');
@@ -1568,11 +1309,6 @@ 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;
@@ -1639,10 +1375,6 @@ class AgentVariantsOrchestrator {
             workItemCount: 1,
             instructionLength: args.instruction.length,
         });
-        // Lease the just-created refine item by id. A generic
-        // requestWork({ requestedLeaseCount: 1 }) takes the first leasable item in
-        // work-item order, which could be an unrelated still-pending static_preview
-        // rather than this refinement.
         return this.requestWork({
             sessionId: args.sessionId,
             leaseOwner: args.leaseOwner,
@@ -1655,7 +1387,6 @@ class AgentVariantsOrchestrator {
     getWorkItemInput(sessionId, workItemId) {
         return this.store.getWorkItemInput(sessionId, workItemId);
     }
-    /** Returns status after orchestration QA and refinement post-processing. */
     getWorkItemStatus(sessionId, workItemId) {
         return this.store.getWorkItemStatus(sessionId, workItemId);
     }
@@ -1672,16 +1403,10 @@ 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.
             const staticPreview = resources?.staticPreviews.get(variant.workItemId) ??
                 this.getStaticPreviewByBriefId(sessionId, variant.briefId);
             let preview;
@@ -1692,11 +1417,6 @@ class AgentVariantsOrchestrator {
                 };
             }
             else if (!port) {
-                // handleSucceededReport is fire-and-forget so staticPreviews may not be
-                // populated yet when getVariants is called (e.g. in the terminal response).
-                // item.output is set synchronously by store.reportComplete, so it's always
-                // available. Read it directly as a fallback so previewUrls in terminal
-                // responses include the variant that just triggered terminal state.
                 try {
                     const output = this.store.getWorkItemOutput(sessionId, variant.workItemId);
                     if (typeof output?.html === 'string' && output.html.length > 0) {
@@ -1707,7 +1427,6 @@ class AgentVariantsOrchestrator {
                     }
                 }
                 catch {
-                    /* work item may not exist in edge cases */
                 }
             }
             if (!preview && port) {
@@ -1717,9 +1436,6 @@ class AgentVariantsOrchestrator {
             const isSucceeded = variant.status === 'succeeded';
             const qaFailed = qa?.status === 'failed';
             const canView = Boolean(preview) || (isSucceeded && Boolean(port));
-            // A succeeded variant with no live preview whose dev server we tried and
-            // failed to start: surface the cause so the UI can show an accurate
-            // per-direction message instead of the generic disconnected overlay.
             const previewFailure = resources?.previewFailures.get(variant.workItemId);
             const previewUnavailable = !canView && isSucceeded && previewFailure
                 ? {
@@ -1763,64 +1479,60 @@ class AgentVariantsOrchestrator {
     hasSession(sessionId) {
         return this.store.hasSession(sessionId);
     }
-    /** Read the projectContext for a session — used by Express routes that
-     *  build the chip snapshot via `stateForSession`. */
     getProjectContext(sessionId) {
         return this.store.getProjectContext(sessionId);
     }
-    /** Resolve a worktree path for a code-gen work item, if provisioned. */
     getWorktreePath(sessionId, workItemId) {
         return this.resources.get(sessionId)?.worktrees.get(workItemId)
             ?.worktreePath;
     }
-    /**
-     * Resolve the project cwd inside a worktree so subdirectory projects run
-     * from the same repo-relative location.
-     */
     getProjectCwdInWorktree(worktreePath) {
         return this.worktrees.getProjectCwdInWorktree(worktreePath);
     }
-    /** Resolve the dev server port for a code-gen work item, if running. */
     getDevServerPort(sessionId, workItemId) {
         return this.resources.get(sessionId)?.worktrees.get(workItemId)?.port;
     }
-    /**
-     * Restores a Rivet-owned variant preview that the active-session idle timer
-     * 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 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.
-     */
-    async restoreVariantPreview(sessionId, workItemId) {
+    async restoreVariantPreview(sessionId, workItemId, options = {}) {
         const resources = this.resources.get(sessionId);
         const record = resources?.worktrees.get(workItemId);
-        if (!resources || !record)
+        if (!resources || !record || resources.cleanupStarted)
             return undefined;
+        if (record.previewRestoration)
+            return record.previewRestoration;
         if (record.port !== undefined && record.devServerProcess) {
             this.touchSession(sessionId);
             return record.port;
         }
-        if (resources.previewFailures.get(workItemId)?.reason !== 'idle_timeout') {
+        const failure = resources.previewFailures.get(workItemId);
+        const isSucceeded = this.store
+            .getVariants(sessionId)
+            .some((variant) => variant.workItemId === workItemId && variant.status === 'succeeded');
+        const isExplicitRetry = options.retryFailed === true &&
+            failure?.reason !== 'missing_static_entry';
+        if (!failure ||
+            !isSucceeded ||
+            (failure.reason !== 'idle_timeout' && !isExplicitRetry)) {
             return undefined;
         }
         resources.previewFailures.delete(workItemId);
         record.devServerAutoRestarts = 0;
         this.emitChange();
         const projectContext = this.store.getProjectContext(sessionId);
-        return this.startVariantDevServer({
+        const restoration = this.startVariantDevServer({
             sessionId,
             workItemId,
             record,
             isFresh: projectContext.kind === 'fresh',
         });
+        record.previewRestoration = restoration;
+        try {
+            return await restoration;
+        }
+        finally {
+            if (record.previewRestoration === restoration)
+                record.previewRestoration = undefined;
+        }
     }
-    /**
-     * @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') {
@@ -1828,14 +1540,6 @@ class AgentVariantsOrchestrator {
         }
         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);
@@ -1845,9 +1549,6 @@ class AgentVariantsOrchestrator {
         }
     }
     getStaticPreviewHtml(sessionId, workItemId) {
-        // Primary: read the materialized entry from the variant's per-variant
-        // directory (written by handleSucceededReport). The directory is the source
-        // of truth for the static deliverable.
         const preview = this.resources
             .get(sessionId)
             ?.staticPreviews.get(workItemId);
@@ -1858,12 +1559,8 @@ class AgentVariantsOrchestrator {
                     return fromDisk;
             }
             catch {
-                // fall through to the work-item output fallback below
             }
         }
-        // Fallback: read directly from the work item's stored output — available
-        // as soon as reportComplete runs, before handleSucceededReport fires (so
-        // the per-variant directory may not exist yet).
         try {
             const output = this.store.getWorkItemOutput(sessionId, workItemId);
             return typeof output?.html === 'string' && output.html.length > 0
@@ -1874,38 +1571,20 @@ class AgentVariantsOrchestrator {
             return undefined;
         }
     }
-    /** Resolve the DESIGN.md markdown behind an artifact link. */
     getDesignContextMarkdown(sessionId, artifactId) {
         const artifact = findDesignContextArtifact(this.store.getProjectContext(sessionId), artifactId);
         return artifact?.content;
     }
-    /** Build the rendered DesignMD document for an artifact link. */
     getDesignContextViewerHtml(sessionId, artifactId) {
         const artifact = findDesignContextArtifact(this.store.getProjectContext(sessionId), artifactId);
         return artifact ? buildDesignContextViewerDocument(artifact) : undefined;
     }
-    /**
-     * `true` when the variant has a non-empty `assetBase` — i.e. its inlined
-     * HTML references sibling files served by the asset route. The route
-     * uses this to decide whether to inject a `<base href>` (only needed
-     * when relative URLs in the HTML must resolve against the asset
-     * sub-path). Self-contained HTML keeps its natural URL resolution.
-     */
     hasStaticPreviewAssets(sessionId, workItemId) {
         const record = this.resources
             .get(sessionId)
             ?.staticPreviews.get(workItemId);
         return Boolean(record?.hasAssets);
     }
-    /**
-     * Resolve an absolute, sandboxed path for a sibling asset that the
-     * variant's inlined HTML references (e.g. `./avatar.glb`, `./hero.png`).
-     * Returns `undefined` when the variant has no `assetBase`, the requested
-     * path escapes the base (path traversal), or the file does not exist.
-     *
-     * Used by the `/api/variants/:sessionId/static/:variantId/<asset>` route
-     * to serve assets from the agent's on-disk variant workspace pre-commit.
-     */
     resolveStaticPreviewAssetPath(sessionId, workItemId, requestedPath) {
         const record = this.resources
             .get(sessionId)
@@ -1914,12 +1593,6 @@ class AgentVariantsOrchestrator {
             return undefined;
         if (!requestedPath || requestedPath.length === 0)
             return undefined;
-        // Resolve against the variant's own directory first so any asset the agent
-        // actually wrote/modified wins. Only when the worktree clone lacks the file
-        // do we fall back to the host project root — that recovers git-ignored or
-        // binary assets the worktree provisioning couldn't carry over, which the
-        // original preview already serves (see `assetFallbackBase`). Both roots are
-        // held to the identical traversal/realpath/hardlink sandbox.
         return (resolveAssetWithinBase(record.assetBase, requestedPath) ??
             (record.assetFallbackBase
                 ? resolveAssetWithinBase(record.assetFallbackBase, requestedPath)
@@ -1936,7 +1609,6 @@ class AgentVariantsOrchestrator {
         const safeWorkItemId = encodeURIComponent(workItemId);
         return `/api/variants/${safeSessionId}/static/${safeWorkItemId}`;
     }
-    // --- Mutation wrappers (state + side effects) ---------------------------
     async approve(args) {
         const result = this.store.approve(args);
         const resources = this.ensureResources(args.sessionId);
@@ -1957,11 +1629,6 @@ class AgentVariantsOrchestrator {
             workItemIds,
         });
         this.emitChange();
-        // Await provisioning before returning so request_work always sees a
-        // populated worktreePath on each leased item. Provisioning is fast
-        // (`git worktree add` per variant + node_modules symlink), and the
-        // agent has nothing useful to do between approve and request_work
-        // anyway — running them serially is the contract the skill assumes.
         try {
             if (projectContext.kind === 'existing') {
                 await this.resolveContextAssetPreviewKind(args.sessionId);
@@ -1975,50 +1642,18 @@ class AgentVariantsOrchestrator {
         }
         return result;
     }
-    /**
-     * Unified one-call kickoff that collapses propose → report_briefs →
-     * 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
-     * static_preview work items; the server runs scaffold_base in the
-     * background). This is the single-call path; source-grounded zero-to-one
-     * sessions (source URLs / inspiration extraction) run through `propose`
-     * instead so the source-research flow can gate generation — start_variants
-     * routes them there. This method does not run source research.
-     *
-     * Host-agnostic: no LLM calls happen here. The agent (Claude Code,
-     * Cursor, Codex) generates the label and code when it leases the
-     * work items via continue_variants(action="request_work").
-     */
     async startUnified(args) {
         const count = args.briefs?.length ?? args.count ?? contracts_1.DEFAULT_VARIANT_COUNT;
         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
-        // here, so this guard is an internal invariant. Existing-project sessions
-        // keep the single-call path even with a bundle — they have no source_plan
-        // stage, and the bundle's raw context is threaded straight into code_gen.
-        // Brief-driven fresh starts are exempt for the same reason: the caller
-        // already did its source research when it authored the briefs, so the
-        // bundle is raw worker context (reference images), not research input.
         const isSourceGrounded = projectContext.kind === 'fresh' &&
             Boolean(projectContext.variantContext) &&
             !args.briefs?.length;
         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.');
         }
-        // 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
@@ -2056,8 +1691,6 @@ class AgentVariantsOrchestrator {
             };
             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 }
                     : {}),
@@ -2096,8 +1729,6 @@ class AgentVariantsOrchestrator {
                 projectContext,
                 runLabel: args.runLabel,
                 ...(args.fidelity ? { fidelity: args.fidelity } : {}),
-                // Briefs land via reportBriefs immediately below — never enter the
-                // source-plan stage, even for a fresh session carrying a bundle.
                 hasPreparedBriefs: true,
                 ...(args.sessionId ? { sessionId: args.sessionId } : {}),
             });
@@ -2128,18 +1759,11 @@ class AgentVariantsOrchestrator {
             });
             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);
         }
@@ -2173,8 +1797,6 @@ class AgentVariantsOrchestrator {
             const lease = this.requestWork({
                 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;
@@ -2190,15 +1812,6 @@ class AgentVariantsOrchestrator {
             leasedWorkItems,
         };
     }
-    /**
-     * 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);
@@ -2228,13 +1841,6 @@ class AgentVariantsOrchestrator {
             body: synthesizeUnifiedBriefBody(args.prompt, i + 1, args.count),
         }, i));
     }
-    /**
-     * 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))
@@ -2249,7 +1855,6 @@ class AgentVariantsOrchestrator {
             return null;
         return sessionId;
     }
-    /** @effect Registers a provisioned git worktree with runtime and workspace state. */
     async registerWorktreeWorkspace(resources, record) {
         let projectPath = record.worktreePath;
         try {
@@ -2265,15 +1870,6 @@ class AgentVariantsOrchestrator {
             projectPath,
         });
     }
-    /**
-     * 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.
-     */
-    /** Emits provisioning started/completed/failed telemetry around `run` for
-     *  the vary-fork/append lanes that bypass provisionWorktrees (and its
-     *  telemetry). Rethrows failures untouched. */
     async withProvisioningTelemetry(args, run) {
         const startedAt = Date.now();
         this.telemetry.track('agent_variants.provisioning_started', {
@@ -2328,11 +1924,6 @@ class AgentVariantsOrchestrator {
             })));
         });
     }
-    /**
-     * 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;
@@ -2340,13 +1931,14 @@ class AgentVariantsOrchestrator {
         if (!sourcePath) {
             throw new errors_1.AgentVariantsError('VARIANT_NOT_EDITABLE', `Cannot fork from variant ${sourceVariantId}: no worktree path`);
         }
-        if (!this.worktrees.forkWorktreesFrom) {
+        const forkWorktreesFrom = this.worktrees.forkWorktreesFrom?.bind(this.worktrees);
+        if (!forkWorktreesFrom) {
             throw new errors_1.AgentVariantsError('RUNTIME_VALIDATION_FAILED', 'worktreeManager does not implement forkWorktreesFrom');
         }
         await this.withProvisioningTelemetry({ sessionId, kind: 'forked_variant', variantCount: workItemIds.length }, async () => {
             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);
+            const paths = await withProvisionTimeout(forkWorktreesFrom(sourcePath, sessionId, workItemIds.length, instanceKeyPrefix), this.provisionTimeoutMs);
             await Promise.all(workItemIds.map((id, index) => this.registerWorktreeWorkspace(resources, {
                 workItemId: id,
                 worktreePath: paths[index],
@@ -2354,15 +1946,7 @@ class AgentVariantsOrchestrator {
         });
     }
     async reportComplete(args) {
-        // Phase-timing anchor: lease→report (agent work) vs report→recorded
-        // (QA gate + post-processing) are attributed separately on
-        // `variant_completed` so latency work can tell them apart.
         const reportReceivedAt = Date.now();
-        // Cooperative abort short-circuit: if the work item was removed/cancelled
-        // while in flight (delete-while-loading, cancel_variant, session cancel),
-        // skip the schema and QA gates entirely — there is no point validating or
-        // QA-ing output we are about to discard — and hand back the store's
-        // `aborted` signal so the agent stops this work item now.
         if (this.store.hasSession(args.sessionId) &&
             this.store.isWorkItemAborted(args.sessionId, args.workItemId)) {
             return this.store.reportComplete(args);
@@ -2386,9 +1970,6 @@ class AgentVariantsOrchestrator {
                 output: this.readAssignedStaticArtifact(args.sessionId, args.workItemId),
             }
             : args;
-        // Contract validation keeps internal callers that provide an explicit
-        // static output honest. Host workers complete assigned artifacts without
-        // transporting the HTML through this report.
         if (resolvedArgs.status === 'succeeded' &&
             this.store.hasSession(args.sessionId) &&
             (workItemKind === 'static_preview' ||
@@ -2406,27 +1987,15 @@ class AgentVariantsOrchestrator {
             }
             throw new errors_1.AgentVariantsError('SCHEMA_VALIDATION_FAILED', `${workItemKind} output.html must be a string and non-empty when explicit output is provided. Host workers should write the assigned index.html instead.`);
         }
-        // Check Rivet-owned output integrity synchronously before recording
-        // success. A terminal failure uses `VARIANT_QA_FAILED` so the variant never
-        // reaches `ready` and `getVariants` can disable its commit action.
         const qaStartedAt = Date.now();
         const qaEval = workItemKind === 'refine_variant'
             ? null
             : await this.evaluateQaForReport(resolvedArgs);
         const qaMs = qaEval === null ? null : Date.now() - qaStartedAt;
-        // A `retry` verdict re-leases the variant for one structural repair instead
-        // of recording success, so short-circuit the normal record path.
         if (qaEval?.decision === 'retry') {
             return this.handleQaRegenRetry(resolvedArgs, qaEval.qa);
         }
         let effectiveArgs = qaEval?.decision === 'fail_terminal' ? qaEval.overrideArgs : resolvedArgs;
-        // For a successful refine_variant, swap the refined static preview into
-        // place and persist history BEFORE recording success in the store. This
-        // keeps the user-visible `refinement.status: succeeded` (and the snapshot
-        // emitted below) from ever being observable while the variant still serves
-        // stale HTML. If post-processing throws, convert the report to `failed` so
-        // the agent/UI surface the failure instead of a success pointing at
-        // unrefreshed output.
         if (workItemKind === 'refine_variant' &&
             effectiveArgs.status === 'succeeded') {
             try {
@@ -2473,9 +2042,6 @@ class AgentVariantsOrchestrator {
             throw error;
         }
         this.emitChange();
-        // Per-variant telemetry on terminal item statuses (skip 'running'
-        // heartbeats and the brief work item — only code_gen / scaffold_base
-        // matter for the funnel).
         if (effectiveArgs.status === 'succeeded' ||
             effectiveArgs.status === 'failed' ||
             effectiveArgs.status === 'cancelled') {
@@ -2484,11 +2050,8 @@ class AgentVariantsOrchestrator {
             const durationMs = leasedAt !== undefined ? Date.now() - leasedAt : null;
             const approveStartedAt = resources?.approveStartedAt;
             const approveToCompleteMs = approveStartedAt !== undefined ? Date.now() - approveStartedAt : null;
-            // Byte size of generated output for HTML vs full-stack comparison.
             const outputBytes = estimateOutputBytes(effectiveArgs.output);
             const projectContextKind = this.store.getProjectContext(args.sessionId).kind;
-            // Execution mode mirrors the host work-item snapshot derivation so
-            // prod latency can finally segment vary vs create vs refine.
             const mode = workItemKind !== undefined && isImplementationWorkItemKind(workItemKind)
                 ? this.store.isVaryForkWorkItem(args.sessionId, args.workItemId)
                     ? 'vary'
@@ -2504,15 +2067,11 @@ class AgentVariantsOrchestrator {
                 approveToCompleteMs,
                 kind: workItemKind ?? null,
                 mode,
-                // Phase split of `durationMs`: agent work vs server-side gating.
                 leaseToReportMs: leasedAt !== undefined ? reportReceivedAt - leasedAt : null,
                 reportProcessingMs: Date.now() - reportReceivedAt,
                 qaMs,
                 hasError: Boolean(effectiveArgs.error),
                 errorCode: effectiveArgs.error?.code ?? null,
-                // Failure detail + API status ride the event so field failures are
-                // diagnosable from telemetry alone (the July 2026 EXECUTOR_WORKER_FAILED
-                // incident took an hour of forensics for want of these).
                 errorMessage: effectiveArgs.error?.message ?? null,
                 errorApiStatus: effectiveArgs.error?.apiErrorStatus ?? null,
                 isScaffold: resources?.scaffoldBaseWorkItemId === args.workItemId,
@@ -2598,10 +2157,6 @@ class AgentVariantsOrchestrator {
                 log.error(`handleSucceededReport failed for ${args.sessionId}/${args.workItemId}`, err);
             });
         }
-        // Teardown is deferred to commitVariant / cancel. Terminal stage just
-        // means all variants are done; the user still needs to review and pick
-        // one. Resources (worktrees + captured diffs) live until that pick lands
-        // on the bridge.
         return result;
     }
     async cancel(args) {
@@ -2632,13 +2187,6 @@ class AgentVariantsOrchestrator {
         });
         return result;
     }
-    /**
-     * Cancel a single variant within a session. Siblings continue. Idempotent
-     * on terminal states. Per-variant worktree teardown is deferred to a
-     * follow-up; the lease is released, so requestWork won't re-surface this
-     * variant and the agent's report_variant_complete for it (if it lands
-     * after cancellation) is rejected by the stale-lease check.
-     */
     async cancelVariant(args) {
         const result = this.store.cancelWorkItem({
             sessionId: args.sessionId,
@@ -2668,12 +2216,6 @@ class AgentVariantsOrchestrator {
             alreadyTerminal: result.alreadyTerminal,
         };
     }
-    /**
-     * Remove a variant from the UI. Hides it from the active snapshot for good
-     * (it's filtered out of progress/summary/terminal accounting too) while
-     * retaining it in `.rivet/variants/` with status `removed` so the work is
-     * kept, never rendered again. Mirrors `cancelVariant`'s shape; idempotent.
-     */
     async removeVariant(args) {
         const result = this.store.removeWorkItem({
             sessionId: args.sessionId,
@@ -2701,13 +2243,6 @@ class AgentVariantsOrchestrator {
             alreadyRemoved: result.alreadyRemoved,
         };
     }
-    /**
-     * Rename a variant's user-visible title. Patches the in-memory work item so
-     * the next snapshot carries the new label, persists it to the variant's
-     * `.rivet/variants/` manifest (best-effort — a never-persisted variant simply
-     * skips the disk write), and pushes the updated snapshot over SSE. Mirrors
-     * `removeVariant`'s shape.
-     */
     async renameVariant(args) {
         const result = this.store.renameWorkItem({
             sessionId: args.sessionId,
@@ -2718,7 +2253,6 @@ class AgentVariantsOrchestrator {
             source: 'mcp',
             sessionId: args.sessionId,
             variantId: args.variantId,
-            // Telemetry policy: never the raw agent/user label text, only its length.
             labelLength: args.label.length,
             sessionStage: result.sessionStage,
         });
@@ -2733,10 +2267,6 @@ class AgentVariantsOrchestrator {
             sessionStage: result.sessionStage,
         };
     }
-    /**
-     * Rename a run folder: re-home one request batch in a single store pass,
-     * persist each affected manifest best-effort, and push one updated snapshot.
-     */
     async renameRun(args) {
         const result = this.store.renameRun({
             sessionId: args.sessionId,
@@ -2747,7 +2277,6 @@ class AgentVariantsOrchestrator {
         this.telemetry.track('agent_variants.run_renamed', {
             source: 'mcp',
             sessionId: args.sessionId,
-            // Telemetry policy: never the raw label text, only its length.
             runLabelLength: args.label.length,
             renamedCount: result.workItemIds.length,
             sessionStage: result.sessionStage,
@@ -2766,18 +2295,7 @@ class AgentVariantsOrchestrator {
             sessionStage: result.sessionStage,
         };
     }
-    /**
-     * 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
-        // `applyDiffToProject` (or the fresh rename) before the first records
-        // its pick. The second caller waits for the first to settle, then runs
-        // commitVariantImpl which hits the idempotency check in
-        // `getVariantPick` / `recordVariantPick`.
         const prior = this.inflightCommits.get(args.sessionId);
         const run = (async () => {
             if (prior) {
@@ -2806,17 +2324,8 @@ class AgentVariantsOrchestrator {
         }
     }
     async commitVariantImpl(args) {
-        // Idempotent path — SessionStore.recordVariantPick is the source of truth
-        // for which variant the user picked. If the same variant is being
-        // committed again, replay the previously stored envelope's metadata
-        // 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 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') {
@@ -2842,9 +2351,6 @@ class AgentVariantsOrchestrator {
                     log.warn(`persistVariantHistoryAtCommit (duplicate retry) failed for session ${args.sessionId}`, err);
                 });
             }
-            // If the committed dev/static server is still running (either tracked
-            // on resources, or handed off to the lingering registry), surface its
-            // URL so a retry restores the iframe to the live project.
             const lingering = this.lingeringCommittedDevServers.get(args.sessionId);
             const live = this.resources.get(args.sessionId)?.committedDevServer;
             const replayPort = lingering?.port ?? live?.port;
@@ -2879,19 +2385,9 @@ class AgentVariantsOrchestrator {
         let envelopeDestination;
         let changedFilesCount;
         let runnablePaths;
-        // Port of the committed dev/static server, when one was spawned during
-        // this commit. Surfaced on the response as `previewUrl` so the UI can
-        // restore the iframe to the committed project without falling through to
-        // the auto-static fallback.
         let committedPreviewPort;
         if (projectContext.kind === 'fresh') {
             const destinationPath = projectContext.workspacePath;
-            // Realpath the destination ONCE for both the empty-check (below) and
-            // the static_preview flatten step (further down). Computing it twice
-            // could diverge if the path's realpath status changes between calls
-            // (e.g. the directory was a symlink during the empty check but got
-            // resolved between then and `mkdirSync`). `undefined` means realpath
-            // failed — caller branches treat that as "no canonical form known".
             let realDestination;
             try {
                 realDestination = fs_1.default.realpathSync(destinationPath);
@@ -2899,34 +2395,13 @@ class AgentVariantsOrchestrator {
             catch {
                 realDestination = undefined;
             }
-            // Read the commit policy off the canonical run plan rather than
-            // re-deriving from executionPlan.mode. `materialize_project` is the
-            // vite_app lane (rename/copy the whole worktree); `write_static_site`
-            // is the static_preview lane (inline HTML + sibling assets).
             const commitPolicy = (0, runPlan_1.resolveRunPlanPolicy)(projectContext).commit;
             const isViteApp = commitPolicy === 'materialize_project';
-            // vite_app: strict emptiness check — that lane renames a worktree into
-            // destinationPath and would clobber user files.
-            // static_preview: the agent intentionally wrote sibling assets under
-            // workspacePath (via `output.assetBase`) before reporting succeeded —
-            // those per-variant subdirs ARE the deliverable. Allow exactly the
-            // assetBase entries known to this session; anything else still
-            // triggers DESTINATION_NOT_EMPTY.
             if (isViteApp) {
                 this.assertDestinationAvailable(destinationPath);
             }
             else {
-                // Compare assetBase entries (which are realpath'd by
-                // resolveStaticPreviewAssetBase) against the realpath'd destination
-                // — on macOS `/tmp` is a symlink to `/private/tmp`, and a raw
-                // string comparison would falsely reject every entry.
                 const compareBase = realDestination ?? destinationPath;
-                // When ANY variant's assetBase is the destination itself (the agent
-                // wrote files directly at the workspace root rather than under a
-                // per-variant subdir), the empty-check would treat the agent's own
-                // deliverable as foreign content. Skip the check in that case — the
-                // workspace IS the deliverable; commit will overwrite index.html
-                // below.
                 const anyAssetBaseIsDestination = [
                     ...resources.staticPreviews.values(),
                 ].some((sp) => sp.assetBase === compareBase);
@@ -2941,16 +2416,6 @@ class AgentVariantsOrchestrator {
                 }
             }
             if (isViteApp) {
-                // Vite_app: the deliverable is the entire variant worktree, not a
-                // single HTML file. When the worktree lives on the same volume as
-                // the destination (the common case — provisionFreshWorktrees scaffolds
-                // under destinationParent/.rivet-variants/) we can rename it into
-                // place. That moves the entire tree — including the materialized
-                // node_modules — in O(1) with no copy, and the rename is atomic.
-                // For cross-volume cases (user passed a destinationParent on a
-                // different mount than the .rivet-variants dir, e.g. tests stubbing
-                // workspacePath to a tmp dir), fall back to the recursive-copy +
-                // background-install path so the feature still works.
                 const record = resources.worktrees.get(args.variantId);
                 if (!record) {
                     throw new errors_1.AgentVariantsError('WORK_ITEM_NOT_FOUND', `Unknown variantId ${args.variantId} for session ${args.sessionId}`);
@@ -2959,25 +2424,7 @@ class AgentVariantsOrchestrator {
                 let isDependencyInstallRequired = false;
                 try {
                     if (areSameVolume(record.worktreePath, destinationPath)) {
-                        // Vite's dev server writes its module cache to `<worktreePath>/.vite/`
-                        // and recreates that directory on the fly whenever it's missing. If
-                        // we rename a worktree out from under a running dev server, Vite
-                        // will materialize an empty `.vite/` shell back at the OLD path —
-                        // leaving behind orphan stub dirs in `.rivet-variants/` and
-                        // confusing later cleanup. Stop every variant's dev server first
-                        // (including the chosen variant, which is about to move) so no
-                        // process is holding the old paths open during the rename.
-                        //
-                        // We stop them eagerly here rather than relying on teardownSession
-                        // because teardown runs AFTER the rename — too late to prevent the
-                        // stub-dir race.
                         await this.stopAllDevServersForSession(resources);
-                        // node_modules in fresh variants 1..N is a symlink into variant 0
-                        // (see runBackgroundInstall). After rename, variant 0's
-                        // node_modules vanishes during cleanup of the sibling worktrees,
-                        // leaving the chosen variant with a dangling link. Resolve the
-                        // symlink to a real directory first so the destination has real
-                        // deps and the rename is self-contained.
                         isDependencyInstallRequired = await resolveNodeModulesSymlink(record.worktreePath);
                         await this.renameWorktreeIntoDestination(record.worktreePath, destinationPath);
                         usedRename = true;
@@ -2992,21 +2439,6 @@ class AgentVariantsOrchestrator {
                 }
                 changedFilesCount = countWorktreeFiles(destinationPath);
                 if (!usedRename) {
-                    // Cross-volume fallback: materializeProject excludes node_modules
-                    // so we have to re-install at the destination. Don't await the
-                    // install — the agent's commit_variant call should return
-                    // immediately — but chain the dev-server start to it so the iframe
-                    // recovers without manual intervention once deps are ready.
-                    //
-                    // NOTE: `committedPreviewPort` stays undefined on this branch by
-                    // design — the install + start sequence takes minutes, far longer
-                    // than the response can wait. The iframe's `switchPreviewPort`
-                    // callback (invoked from `startCommittedDevServer` when the
-                    // server finally comes up) retargets the proxy then, so the
-                    // iframe reaches the new server without the URL being on the
-                    // commit response. The response surface stays `previewUrl?:` (the
-                    // field is optional) and consumers fall back to the proxy
-                    // upstream when it's absent.
                     void this.installDependencies(destinationPath)
                         .then(() => this.startCommittedDevServer({
                         resources,
@@ -3020,9 +2452,6 @@ class AgentVariantsOrchestrator {
                     await this.installDependencies(destinationPath);
                 }
                 if (usedRename) {
-                    // Preserve the unchosen variants as runnable siblings of the
-                    // chosen project. Best-effort: failures here log and continue so
-                    // a partial history never blocks the commit handoff.
                     try {
                         runnablePaths = this.preserveUnchosenVariants({
                             sessionId: args.sessionId,
@@ -3033,12 +2462,6 @@ class AgentVariantsOrchestrator {
                     catch (err) {
                         log.warn(`preserveUnchosenVariants failed for session ${args.sessionId}; continuing without history`, err);
                     }
-                    // Stopped every dev server pre-rename to dodge the .vite/ stub-dir
-                    // race. The iframe is still pointed at the (now-dead) chosen
-                    // variant's port via the proxy, so without a fresh server at the
-                    // destination the user would see "preview disconnected" the moment
-                    // they commit. Spawn one and retarget the proxy. Best-effort: if
-                    // it fails, the user can `npm run dev` themselves at destination.
                     committedPreviewPort = await this.startCommittedDevServer({
                         resources,
                         destinationPath,
@@ -3056,18 +2479,7 @@ class AgentVariantsOrchestrator {
                 envelopeDestination = destinationPath;
             }
             else {
-                // Static_preview: HTML is the entire deliverable. Write index.html.
-                // Prefer the in-memory record; fall back to the persisted history at
-                // `<workspacePath>/.rivet/variants/<sessionId>/<variantId>/files/index.html`
-                // so a process restart between report_variant_complete and commit
-                // doesn't strand the variant.
                 const staticPreview = resources.staticPreviews.get(args.variantId);
-                // Resolve the committed index.html before the flatten step below
-                // moves/removes the per-variant dir. `getStaticPreviewHtml` reads the
-                // materialized `<dir>/index.html` and falls back to the work-item's
-                // stored output (the reported HTML) when the on-disk file is missing
-                // or empty — so a failed materialization still commits real content
-                // rather than an empty file.
                 const htmlFromDir = staticPreview
                     ? this.getStaticPreviewHtml(args.sessionId, args.variantId)
                     : undefined;
@@ -3081,21 +2493,6 @@ class AgentVariantsOrchestrator {
                 }
                 try {
                     fs_1.default.mkdirSync(destinationPath, { recursive: true });
-                    // If the chosen variant has an `assetBase` subdir under
-                    // destinationPath (e.g. `<workspace>/var-1` containing
-                    // `avatar.glb`), move its contents up to the destination root so
-                    // the committed HTML can reference them as `./avatar.glb`. Then
-                    // delete every OTHER static_preview record's assetBase — the
-                    // unchosen variants' sibling assets are no longer relevant once
-                    // the user picked. Both steps run before the canonical index.html
-                    // is written so the chosen variant's on-disk index.html (if any)
-                    // gets overwritten by the inlined version below.
-                    // assetBase entries are realpath'd; compare against the realpath
-                    // of destinationPath so symlink-stripped paths line up (macOS:
-                    // `/tmp` → `/private/tmp`). `realDestination` was computed once
-                    // at the top of the fresh branch — re-realpath in case `mkdirSync`
-                    // above just created the directory (the initial computation may
-                    // have returned undefined when the dir didn't yet exist).
                     let flattenBase = realDestination;
                     if (!flattenBase) {
                         try {
@@ -3106,32 +2503,17 @@ class AgentVariantsOrchestrator {
                         }
                     }
                     const chosenAssetBase = staticPreview?.assetBase;
-                    // Skip flattening when assetBase IS the destination — the agent
-                    // wrote files directly at the workspace root, so there's no subdir
-                    // to flatten. Only move when assetBase is a strict descendant.
                     if (chosenAssetBase &&
                         isStrictlyInside(chosenAssetBase, flattenBase)) {
                         for (const entry of fs_1.default.readdirSync(chosenAssetBase)) {
                             const src = path_1.default.join(chosenAssetBase, entry);
                             const dst = path_1.default.join(flattenBase, entry);
-                            // Self-collision guard: when an agent names a child the same
-                            // as the parent dir (e.g. `var-1/var-1/`), `dst` resolves to
-                            // `chosenAssetBase` itself. The rmSync below would then delete
-                            // the parent — including every remaining entry we're about to
-                            // move — and the next iteration's `renameSync` would fail
-                            // with ENOENT. The agent's last attempted variant would also
-                            // be silently dropped. Skip this entry; we still rm the
-                            // parent at the end of the loop.
                             if (path_1.default.resolve(dst) === path_1.default.resolve(chosenAssetBase)) {
                                 continue;
                             }
                             if (fs_1.default.existsSync(dst)) {
                                 fs_1.default.rmSync(dst, { recursive: true, force: true });
                             }
-                            // Cross-volume safety: rename fails with EXDEV when src and
-                            // dst are on different mounts (possible when the user's
-                            // workspacePath crosses a symlink to another volume). Fall
-                            // back to recursive copy + remove so the commit doesn't die.
                             try {
                                 fs_1.default.renameSync(src, dst);
                             }
@@ -3160,10 +2542,6 @@ class AgentVariantsOrchestrator {
                     throw new errors_1.AgentVariantsError('RUNTIME_VALIDATION_FAILED', `Failed to write static preview to ${destinationPath}: ${message}`);
                 }
                 changedFilesCount = countWorktreeFiles(destinationPath);
-                // Spawn a static file server at destinationPath and retarget the
-                // proxy so the iframe stays live across commit (parity with the
-                // vite_app rename path). Best-effort: a failure leaves the iframe
-                // showing "preview disconnected" but doesn't fail the commit.
                 committedPreviewPort = await this.startCommittedDevServer({
                     resources,
                     destinationPath,
@@ -3179,10 +2557,6 @@ class AgentVariantsOrchestrator {
             }
         }
         else {
-            // Existing project: diff against the user's repo. resolveEnv lives in
-            // this branch only — fresh sessions don't have a user-supplied project
-            // and the bridge.getProjectPath() it reads from would either be stale
-            // or empty for them.
             const env = await this.resolveEnv(args.sessionId);
             const record = resources.worktrees.get(args.variantId);
             if (!record) {
@@ -3192,8 +2566,6 @@ 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 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');
             }
@@ -3221,17 +2593,10 @@ class AgentVariantsOrchestrator {
             changedFilesCount,
             payload,
         };
-        // Record the pick in the SessionStore so future commitVariant calls with
-        // the same variantId are idempotent and a different variantId returns
-        // PENDING_CHANGE_CONFLICT (already picked).
         this.store.recordVariantPick({
             sessionId: args.sessionId,
             envelope,
         });
-        // History: flip every persisted variant in this session to its terminal
-        // status. Variants are persisted at code_gen success time; this patches
-        // the status and destinationPath for the chosen one. Best-effort, never
-        // blocks the commit.
         const historyProjectPath = projectContext.kind === 'fresh'
             ? projectContext.workspacePath
             : envelopeDestination;
@@ -3249,13 +2614,6 @@ class AgentVariantsOrchestrator {
             log.warn(`persistVariantHistoryAtCommit failed for session ${args.sessionId}`, err);
         }
         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
-        // active so SSE keeps pushing snapshots with the chosen variant; the UI's
-        // iframe stays on it instead of unmounting to about:blank (which would
-        // surface a misleading "Preview isn't connected" overlay). For diff /
-        // diff-applied commits the user moves on to their own dev server, so
-        // clearing is correct — that's the original behavior preserved below.
         if (this.activeSessionId === args.sessionId &&
             payload.kind !== 'project-created') {
             this.activeSessionId = null;
@@ -3275,9 +2633,6 @@ class AgentVariantsOrchestrator {
         this.emitChange();
         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
-            // commit_variant call returns immediately.
             void this.teardownSession(args.sessionId, 'committed').catch((err) => {
                 log.warn(`teardownSession after commit failed for ${args.sessionId}`, err);
             });
@@ -3298,25 +2653,7 @@ class AgentVariantsOrchestrator {
     async cleanupCommittedSession(sessionId) {
         await this.teardownSession(sessionId, 'committed');
     }
-    /**
-     * Ensure the user-facing destination path can receive the new project.
-     * Rejects when the path exists and is non-empty.
-     *
-     * `.rivet/` (pre-commit snapshots + history manifests) and `.gitignore`
-     * (written by VariantHistoryService.ensureGitignore when variants persist
-     * at success time) are both tolerated — neither is user-authored content
-     * that would be clobbered by the materialize step.
-     */
-    assertDestinationAvailable(destinationPath, 
-    /**
-     * Top-level entries the caller knows it owns and can safely overwrite.
-     * Used by the fresh static_preview commit path so a directory holding
-     * only this session's per-variant `assetBase` subdirs still counts as
-     * "available" — those came from the agent during generation. Any entry
-     * NOT in this set (and not the standard `.rivet`/`.gitignore` exemptions)
-     * still triggers DESTINATION_NOT_EMPTY.
-     */
-    additionalAllowedEntries = new Set()) {
+    assertDestinationAvailable(destinationPath, additionalAllowedEntries = new Set()) {
         if (!fs_1.default.existsSync(destinationPath))
             return;
         const entries = fs_1.default.readdirSync(destinationPath);
@@ -3327,18 +2664,13 @@ class AgentVariantsOrchestrator {
             return;
         throw new errors_1.AgentVariantsError('DESTINATION_NOT_EMPTY', `Destination ${destinationPath} is not empty (${userVisibleEntries.length} entries) — refuse to materialize.`);
     }
-    /** Read the captured diff for a code-gen variant, if available. */
     getVariantDiff(sessionId, variantId) {
         return this.resources.get(sessionId)?.worktrees.get(variantId)?.diff;
     }
-    // --- Side-effect implementations ----------------------------------------
     async provisionWorktrees(sessionId, approveResult) {
         const projectContext = this.store.getProjectContext(sessionId);
         const variantCount = approveResult.codeGenWorkItemIds.length +
             (approveResult.scaffoldBaseWorkItemId ? 1 : 0);
-        // Generated + static_preview provisions nothing (HTML is the deliverable)
-        // — skip the timing/telemetry wrapper so the fast path stays untouched.
-        // `provision: 'none'` is exactly the no-scaffold generated-static lane.
         if ((0, runPlan_1.resolveRunPlanPolicy)(projectContext).provision === 'none') {
             return;
         }
@@ -3351,10 +2683,6 @@ class AgentVariantsOrchestrator {
         });
         const run = async () => {
             if (projectContext.kind === 'fresh') {
-                // Fresh + vite_app: provision a Vite skeleton per variant and copy the
-                // agent-planned assetPlan files before the agent leases its code_gen
-                // items. (Background `npm install` is dispatched inside and is NOT
-                // awaited here — the timeout bounds worktree creation, not install.)
                 await this.provisionFreshWorktrees(sessionId, approveResult, projectContext);
                 return;
             }
@@ -3385,9 +2713,6 @@ class AgentVariantsOrchestrator {
                         ? err.code
                         : 'PROVISION_FAILED',
             });
-            // 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);
             });
@@ -3402,11 +2727,6 @@ class AgentVariantsOrchestrator {
             throw err;
         }
     }
-    /**
-     * Existing-project flow: clone the user's repo N times via git worktree.
-     * Runs synchronously because the operation is fast (no install needed —
-     * node_modules is symlinked from the source project).
-     */
     async provisionExistingWorktrees(sessionId, approveResult) {
         const resources = this.ensureResources(sessionId);
         const totalCount = approveResult.codeGenWorkItemIds.length +
@@ -3433,19 +2753,6 @@ class AgentVariantsOrchestrator {
             });
         }
     }
-    /**
-     * Fresh-project flow: scaffold one template per variant + DESIGN.md per
-     * slot synchronously (fast — just file writes + git init), then dispatch a
-     * background `npm install` task per worktree. Returns immediately so the
-     * `approve_variant_briefs` MCP tool doesn't time out on cold installs.
-     *
-     * On install success: `sessionStore.completeInternal(scaffold_base)` runs,
-     * which unblocks the dependent code_gen items.
-     *
-     * On install failure: the scaffold_base work item is marked failed via
-     * `failInternal`, which cascades DEPENDENCY_FAILED to all dependent
-     * code_gen items so the session degrades cleanly.
-     */
     async provisionFreshWorktrees(sessionId, approveResult, projectContext) {
         const resources = this.ensureResources(sessionId);
         const scaffoldId = approveResult.scaffoldBaseWorkItemId;
@@ -3472,33 +2779,14 @@ class AgentVariantsOrchestrator {
             designContext: summarizeDesignContext(designContext),
         });
         log.info(`Provisioning ${codeGenIds.length} fresh worktree(s) for session ${sessionId}`);
-        // destinationParent for fresh worktrees: the user's workspace root
-        // (sibling to `.rivet/`). Keeping the worktree on the same volume as
-        // the materialize destination turns commit into a directory rename
-        // instead of a recursive copy. `path.dirname(workspacePath)` *used*
-        // to equal `workspaceRoot`, but after nesting subprojects under
-        // `<workspaceRoot>/.rivet/<slug>/` the dirname is now `.rivet/`,
-        // which would stage worktrees inside `.rivet/.rivet-variants/`.
-        // Use workspaceRoot directly so staging lives at
-        // `<workspaceRoot>/.rivet-variants/` as originally intended.
         const destinationParent = projectContext.workspaceRoot;
         const paths = await createFresh.call(this.worktrees, sessionId, codeGenIds.length, viteReactTs_1.VITE_REACT_TS_TEMPLATE, designContext, destinationParent);
         resources.scaffoldBaseWorkItemId = scaffoldId;
         resources.freshDestinationParent = destinationParent;
-        // Each code_gen item maps 1:1 to a fresh worktree. The scaffold_base
-        // work item is internal — no dedicated worktree.
         await Promise.all(codeGenIds.map((workItemId, index) => this.registerWorktreeWorkspace(resources, {
             workItemId,
             worktreePath: paths[index],
         })));
-        // Copy agent-planned assets (e.g. avatar.glb) into each worktree so
-        // generated code can reference them via plan.referenceAs. Done before
-        // the background install so the assets are on disk by the time the
-        // agent leases its code_gen item.
-        // If copy throws (e.g. source asset deleted between planning and
-        // provisioning), fail scaffold_base immediately so dependent code_gen
-        // items cascade DEPENDENCY_FAILED instead of leaving the session
-        // permanently stuck in `work_items_ready`.
         const assetPlan = projectContext.executionPlan?.assetPlan ?? [];
         if (assetPlan.length > 0) {
             try {
@@ -3530,39 +2818,22 @@ class AgentVariantsOrchestrator {
                 return;
             }
         }
-        // Background install: don't await. The orchestrator finishes the
-        // approve→provision call immediately; the agent polls for scaffold
-        // completion via continue_variants(action='check').
         void this.runBackgroundInstall(sessionId, scaffoldId, paths, scaffoldStartedAt).catch((err) => {
             log.error(`runBackgroundInstall failed for session ${sessionId}`, err);
         });
     }
-    /**
-     * Run `npm install` in parallel across all fresh worktrees. On all-success,
-     * mark scaffold_base succeeded via `completeInternal`. On any failure,
-     * mark scaffold_base failed via `failInternal` and emit telemetry.
-     */
     async runBackgroundInstall(sessionId, scaffoldWorkItemId, worktreePaths, scaffoldStartedAt) {
         const installStartedAt = Date.now();
         try {
-            const [firstWorktree, ...rest] = worktreePaths;
-            await this.installDependencies(firstWorktree);
-            await Promise.all(rest.map(async (p) => {
-                const target = path_1.default.join(firstWorktree, 'node_modules');
-                const link = path_1.default.join(p, 'node_modules');
-                // The fresh template has no node_modules until install runs, so
-                // the link target is guaranteed absent in `p` — no need to remove
-                // first.
-                try {
-                    fs_1.default.symlinkSync(target, link, 'dir');
-                }
-                catch (symlinkErr) {
-                    log.warn(`Symlink node_modules failed for ${p}, falling back to install`, symlinkErr);
-                    await this.installDependencies(p);
-                }
-            }));
+            await Promise.all(worktreePaths.map((worktreePath) => this.installDependencies(worktreePath, {
+                workspaceRoot: worktreePath,
+                signal: this.resources.get(sessionId)?.dependencyAbortController.signal,
+            })));
         }
         catch (err) {
+            const resources = this.resources.get(sessionId);
+            if (!resources || resources.cleanupStarted)
+                return;
             const message = err instanceof Error ? err.message : String(err);
             log.warn(`npm install failed for session ${sessionId}; marking scaffold_base failed`, err);
             trackScaffoldFailed(this.telemetry, {
@@ -3601,12 +2872,6 @@ class AgentVariantsOrchestrator {
             variantCount: worktreePaths.length,
         });
     }
-    /**
-     * Checks succeeded implementation reports before they reach the store.
-     * Static previews must contain a structurally complete local artifact;
-     * applicable existing-project variants must contain an added diff. Returns
-     * a pass, a single repair retry, or a terminal integrity failure.
-     */
     async evaluateQaForReport(args) {
         if (args.status !== 'succeeded')
             return null;
@@ -3614,15 +2879,12 @@ class AgentVariantsOrchestrator {
             return null;
         const projectContext = this.store.getProjectContext(args.sessionId);
         const kind = this.store.getWorkItemKind(args.sessionId, args.workItemId);
-        // Existing-project code_gen has no owned preview document to inspect. Its
-        // structural contract is a captured diff containing added source content.
         if (projectContext.kind !== 'fresh') {
             if (kind === 'code_gen') {
                 return this.evaluateExistingCodeGenQa(args);
             }
             return null;
         }
-        // Resolve the objective base QA for this deliverable kind.
         let baseQa = null;
         const checkedSource = undefined;
         if (kind === 'static_preview') {
@@ -3632,8 +2894,6 @@ class AgentVariantsOrchestrator {
             baseQa = await this.runPreviewQaSafely(args, parsed.html);
         }
         else if (kind === 'code_gen') {
-            // Fresh vite_app variants run agent-authored dev-server code. No
-            // preview document to inspect — behave exactly as before.
             return null;
         }
         else {
@@ -3651,7 +2911,6 @@ class AgentVariantsOrchestrator {
                 },
             };
         }
-        // Synthesize a passing base verdict for vite_app (no objective layer).
         const passedBase = baseQa ?? {
             status: 'passed',
             issues: [],
@@ -3735,8 +2994,6 @@ class AgentVariantsOrchestrator {
             },
         };
     }
-    /** Run the injected preview QA runner, converting a thrown runner into a
-     *  failed `VariantQaResult` (mirrors the prior inline behavior). */
     async runPreviewQaSafely(args, html) {
         try {
             return await this.previewQaRunner({
@@ -3763,11 +3020,6 @@ class AgentVariantsOrchestrator {
     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 QA
-     * notes, and record that it has now used its single retry.
-     */
     async handleQaRegenRetry(args, qa) {
         const resources = this.ensureResources(args.sessionId);
         const result = this.store.requeueForRegeneration({
@@ -3789,11 +3041,6 @@ class AgentVariantsOrchestrator {
             overall: null,
         });
         this.emitChange();
-        // Carry the requeue signal + critique so the tool layer can tell the agent
-        // to re-lease and regenerate. The store result is an opaque
-        // `waiting_for_results` (the variant is pending again); on its own that is
-        // indistinguishable from a sibling still in flight, so the agent would
-        // otherwise abandon the variant and the session would stall at ready:0.
         const completionResult = { ...result, requeuedForRegeneration: true, qa };
         resources.repairCompletionResults.set(repairCompletionKey(args), completionResult);
         return completionResult;
@@ -3812,16 +3059,6 @@ class AgentVariantsOrchestrator {
                 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.
-        //
-        // Pick a sensible port near the framework's default (3000 for Next, 5173
-        // for Vite) and inject it via PORT + the CLI flag (see buildDevServerCommand)
-        // so the server actually binds it — that's what moves a preview off a port
-        // the user's own dev server already holds instead of colliding on it. On a
-        // retry we scan past the port we just tried, so a transient race or a
-        // briefly-held port resolves onto the next free one.
         const previewStartedAt = Date.now();
         const projectContextKind = args.isFresh ? 'fresh' : 'existing';
         trackPreviewStarted(this.telemetry, {
@@ -3833,25 +3070,19 @@ class AgentVariantsOrchestrator {
         const startPort = await this.resolveDevServerStartPort(args.sessionId, args.isFresh);
         let scanFrom = startPort;
         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);
+                const dev = await this.resolveDevServer(args.sessionId, args.record.worktreePath, port, args.isFresh);
                 lastDev = dev;
+                if (!canContinueStart())
+                    return undefined;
                 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);
@@ -3863,16 +3094,6 @@ class AgentVariantsOrchestrator {
                 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, 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;
@@ -3891,8 +3112,6 @@ class AgentVariantsOrchestrator {
                         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 ||
@@ -3920,8 +3139,6 @@ class AgentVariantsOrchestrator {
                     });
                     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);
@@ -3950,16 +3167,6 @@ class AgentVariantsOrchestrator {
                 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' &&
@@ -3968,8 +3175,6 @@ class AgentVariantsOrchestrator {
                     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}, missingDeps=${missingDeps})` +
@@ -3982,33 +3187,48 @@ class AgentVariantsOrchestrator {
                     if (missingDeps && lastDev) {
                         installRetried = true;
                         try {
-                            await this.installDependencies(lastDev.cwd, lastDev.packageManager);
+                            await this.installDependencies(lastDev.cwd, {
+                                workspaceRoot: args.record.worktreePath,
+                                force: true,
+                                signal: this.resources.get(args.sessionId)
+                                    ?.dependencyAbortController.signal,
+                            });
                         }
                         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);
+                            log.warn(`Dependency preparation failed for variant ${args.workItemId}`, installErr);
+                            this.resources
+                                .get(args.sessionId)
+                                ?.previewFailures.set(args.workItemId, {
+                                reason: 'dependency_install_failed',
+                                portInUse: false,
+                            });
+                            trackPreviewFailed(this.telemetry, {
+                                sessionId: args.sessionId,
+                                variantId: args.workItemId,
+                                projectContextKind,
+                                previewKind: 'dev_server',
+                                errorCode: 'DEPENDENCY_INSTALL_FAILED',
+                                reason: 'dependency_install_failed',
+                                portInUse: false,
+                                durationMs: Date.now() - previewStartedAt,
+                            });
+                            this.emitChange();
+                            return undefined;
                         }
                     }
                     continue;
                 }
-                // Record the failure so getVariants can tell the UI this direction's
-                // preview couldn't start (and why), then push a snapshot so the chip
-                // updates from "loading" to the accurate per-direction message.
                 this.resources
                     .get(args.sessionId)
                     ?.previewFailures.set(args.workItemId, {
                     reason,
                     portInUse,
                 });
-                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.
+                let errorCode = 'DEV_SERVER_START_FAILED';
+                if (reason === 'dependency_install_failed')
+                    errorCode = 'DEPENDENCY_INSTALL_FAILED';
+                if (reason === 'missing_dev_script')
+                    errorCode = 'DEV_SCRIPT_MISSING';
                 trackFreshDevServerFailed(this.telemetry, {
                     sessionId: args.sessionId,
                     variantId: args.workItemId,
@@ -4036,9 +3256,6 @@ class AgentVariantsOrchestrator {
                 return undefined;
             }
             finally {
-                // Hand the reservation back whether the dev server bound the port
-                // (now visible to the listener check, so the reservation is redundant),
-                // it failed (port free again), or we're about to retry on the next port.
                 if (port !== undefined)
                     this.worktrees.releasePort?.(port);
             }
@@ -4066,12 +3283,6 @@ class AgentVariantsOrchestrator {
                         assetBase: staticPreview.assetBase,
                         projectContext,
                     });
-                    // Materialize the variant into a per-variant directory so every
-                    // static variant is directory-backed (the same shape as the
-                    // worktree-based variants). Reuse the agent's assetBase dir when it
-                    // wrote sibling assets; otherwise create a Rivet-managed per-variant
-                    // dir under workspacePath. `staticPreview.html` is the complete built
-                    // document (html + css + js), written as index.html.
                     const workspacePath = projectContext.kind === 'fresh'
                         ? projectContext.workspacePath
                         : undefined;
@@ -4094,16 +3305,10 @@ class AgentVariantsOrchestrator {
                     }
                     try {
                         fs_1.default.mkdirSync(dir, { recursive: true });
-                        // Realpath the dir so it lines up with the realpath'd destination
-                        // the commit emptiness-check compares against (macOS symlinks
-                        // `/var` → `/private/var`). `resolveStaticPreviewAssetBase`
-                        // already realpaths the agent-provided case; do the same for the
-                        // Rivet-created dir.
                         try {
                             dir = fs_1.default.realpathSync(dir);
                         }
                         catch {
-                            // keep the un-realpath'd path if realpath fails
                         }
                         fs_1.default.writeFileSync(path_1.default.join(dir, 'index.html'), staticPreview.html, 'utf8');
                     }
@@ -4124,8 +3329,6 @@ class AgentVariantsOrchestrator {
                         resources.workspaceManager.removeArtifactWorkspace(workItemId);
                     }
                     if (this.store.getProjectContext(sessionId).kind === 'fresh') {
-                        // History at `<workspacePath>/.rivet/variants/<sessionId>/<variantId>/`
-                        // is the on-disk record for this generated project.
                         this.trackHistoryPersist(this.persistCompletedFreshVariant({
                             sessionId,
                             workItemId,
@@ -4156,8 +3359,6 @@ class AgentVariantsOrchestrator {
             log.warn(`No worktree record for ${sessionId}/${workItemId}; skipping diff capture`);
             return;
         }
-        // scaffold_base sets up the base for dependent code_gen items. No diff
-        // to capture from it — its result is the disk state of the worktree.
         if (resources.scaffoldBaseWorkItemId === workItemId) {
             log.info(`scaffold_base ${workItemId} succeeded; awaiting dependent code-gen`);
             return;
@@ -4173,14 +3374,6 @@ class AgentVariantsOrchestrator {
         catch (err) {
             log.warn(`getDiff failed for ${record.worktreePath}`, err);
         }
-        // History: persist every completed variant immediately to
-        // `<projectPath>/.rivet/variants/`. Existing projects pass the captured
-        // diff (or an empty string when capture itself failed — the variant
-        // still succeeded code-gen-wise, and the history row is the only
-        // record the UI has). Fresh-project variants copy their worktree
-        // (vite_app) or the staged HTML (static_preview). Best-effort — a
-        // failure here must never block dev-server startup or the user's pick
-        // flow.
         if (!isFresh) {
             this.trackHistoryPersist(this.persistCompletedExistingVariant({
                 sessionId,
@@ -4198,19 +3391,8 @@ class AgentVariantsOrchestrator {
                 log.warn(`persistCompletedFreshVariant failed for ${sessionId}/${workItemId}`, err);
             }));
         }
-        // Static existing-mode projects (framework='static', no dev command) have
-        // no per-variant dev server to proxy the iframe at. Serve the variant's
-        // materialized static files directly — the same renderer the chip/iframe
-        // already uses for fresh static_preview variants — so the variant is
-        // viewable/cyclable instead of being silently stuck on "Preview is
-        // unavailable for this variant". When this succeeds there is no dev server
-        // to bring up, so skip the proxy path below.
         if (!isFresh) {
             const staticPreview = await this.registerExistingStaticPreview(sessionId, workItemId, record);
-            // Existing projects resolve their preview surface at success time (the
-            // one genuinely-late axis of the run plan): a framework='static' project
-            // materializes static files → static_artifact and needs no dev server;
-            // anything else falls through to the dev-server proxy below.
             if (staticPreview !== 'not_static') {
                 this.emitChange();
                 return;
@@ -4244,17 +3426,8 @@ class AgentVariantsOrchestrator {
             assetBase: parsed.assetBase,
             projectContext: this.store.getProjectContext(args.sessionId),
         });
-        // A refinement that only rewrites HTML won't re-declare an assetBase, but
-        // the refined markup can still reference the original sibling assets
-        // (images, GLB, fonts). Fall back to the variant's existing asset base so
-        // those relative URLs keep resolving instead of 404ing after the swap.
         const previousRecord = resources.staticPreviews.get(input.variantId);
         const dir = resolvedAssetBase ?? previousRecord?.assetBase;
-        // Re-materialize index.html in the per-variant dir FIRST. The directory is
-        // the source of truth (`getStaticPreviewHtml` reads it disk-first), so the
-        // write must succeed before we swap any in-memory / stored-output state to
-        // the refined HTML. If it fails we throw — converting to a `failed` report
-        // rather than a success that still serves the pre-refine document on disk.
         if (dir) {
             try {
                 fs_1.default.mkdirSync(dir, { recursive: true });
@@ -4264,9 +3437,6 @@ class AgentVariantsOrchestrator {
                 throw new errors_1.AgentVariantsError('RUNTIME_VALIDATION_FAILED', `Failed to materialize refined static preview for ${input.variantId}: ${err instanceof Error ? err.message : String(err)}`);
             }
         }
-        // Swap the served preview to the refined HTML. Runs before
-        // store.reportComplete so any failure above converts to a `failed` report
-        // rather than a success pointing at unrefreshed output.
         this.store.replaceWorkItemOutput(args.sessionId, input.variantId, {
             ...parsed,
             ...(dir ? { assetBase: dir } : {}),
@@ -4288,10 +3458,6 @@ class AgentVariantsOrchestrator {
                 targetWorkItemId: input.variantId,
             });
         }
-        // History persistence is best-effort, mirroring handleSucceededReport's
-        // fire-and-forget persistence for freshly completed variants. A failure
-        // here (e.g. a transient filesystem race) must not fail the refinement or
-        // discard the already-serving refined HTML.
         try {
             await this.persistCompletedFreshVariant({
                 sessionId: args.sessionId,
@@ -4301,22 +3467,10 @@ class AgentVariantsOrchestrator {
         catch (err) {
             log.warn(`persistCompletedFreshVariant failed for refined variant ${input.variantId} (session ${args.sessionId}); preview already swapped`, err);
         }
-        // The caller (reportComplete) emits the change after recording success so
-        // the snapshot reflects both the swapped HTML and refinement.status.
     }
-    /** The worktree/dev-server manager this orchestrator boots previews with.
-     *  Exposed so HistoryReplayService shares the SAME instance: the
-     *  reserved-but-not-yet-bound port set is per-instance, and a second
-     *  manager scanning the same range can hand a live variant's pending port
-     *  to a replay (EADDRINUSE for the loser). */
     get devServerManager() {
         return this.worktrees;
     }
-    /** In-flight fire-and-forget history persists. Tree-store snapshots spawn
-     *  git subprocesses, so these can outlive the microtask flushes that used
-     *  to be enough to drain them — {@link teardownSession} (and the test
-     *  helpers' settleBackgroundWork) await {@link settleHistoryPersists}
-     *  instead of racing the writes. */
     pendingHistoryPersists = new Set();
     trackHistoryPersist(persist) {
         this.pendingHistoryPersists.add(persist);
@@ -4326,20 +3480,11 @@ class AgentVariantsOrchestrator {
             this.pendingHistoryPersists.delete(persist);
         });
     }
-    /** Await every in-flight history persist, including ones that start while
-     *  draining (a refine can persist mid-settle). */
     async settleHistoryPersists() {
         while (this.pendingHistoryPersists.size > 0) {
             await Promise.allSettled([...this.pendingHistoryPersists]);
         }
     }
-    /**
-     * Persist a completed existing-project code_gen variant into
-     * `<env.projectPath>/.rivet/variants/<sessionId>/<variantId>/`. Called from
-     * `handleSucceededReport` once the worktree diff has been captured but
-     * before the user picks. Status is `completed` until `commitVariant` or a
-     * cancellation transitions it.
-     */
     async persistCompletedExistingVariant(args) {
         const projectContext = this.store.getProjectContext(args.sessionId);
         if (projectContext.kind !== 'existing')
@@ -4367,13 +3512,7 @@ class AgentVariantsOrchestrator {
         }
         const input = this.store.getWorkItemInput(args.sessionId, args.workItemId);
         const sessionPrompt = this.store.getPrompt(args.sessionId);
-        // Tree-store snapshot inputs (dual-write). The snapshot root is the
-        // worktree root — the git root, per the tree-root contract — for EVERY
-        // framework, not just static: this is what makes dev-server (Vite /
-        // fullstack) variants replayable from history instead of diff-only.
         const snapshotDir = record?.worktreePath;
-        // Lazy per-session base snapshot from the host repo root. Best-effort:
-        // resolution failure just means no base ref (variant commits still land).
         let baseDir;
         try {
             baseDir = await this.worktrees.getGitRoot?.();
@@ -4383,9 +3522,6 @@ class AgentVariantsOrchestrator {
         }
         let serve;
         if (sourceDir && record && staticEntryPath) {
-            // Static framework: entryPath is relative to the snapshot root (the
-            // worktree root), pointing into the nested project dir when the
-            // project lives below the git root.
             const entryPath = path_1.default.relative(record.worktreePath, path_1.default.join(sourceDir, staticEntryPath));
             serve = { kind: 'static', entryPath };
         }
@@ -4396,12 +3532,6 @@ class AgentVariantsOrchestrator {
             };
         }
         else if (record) {
-            // Persist fires at code-gen success, BEFORE the dev server boots (the
-            // boot is what stashes record.devCommand/port) — so for the common
-            // path the live invocation isn't available yet. Run the same
-            // deterministic resolution the boot will use, against a sentinel port
-            // that becomes the ${PORT} placeholder. No dependency install here —
-            // resolveDevServerCommand is the side-effect-free half of the split.
             try {
                 const dev = await this.resolveDevServerCommand(args.sessionId, record.worktreePath, RECIPE_PORT_SENTINEL, false);
                 serve = {
@@ -4441,22 +3571,6 @@ class AgentVariantsOrchestrator {
                 : {}),
         });
     }
-    /**
-     * Existing-mode `framework: 'static'` projects have no dev command, so there
-     * is no per-variant dev server for the iframe to proxy. Register the variant's
-     * materialized static site as a {@link StaticPreviewRecord} so the existing
-     * static-file plumbing — the `/api/variants/:sid/static/:vid[/asset]` routes,
-     * {@link getStaticPreviewHtml}, and {@link getVariants} (preview.kind=
-     * 'static_artifact', view enabled) — all light up exactly as they do for
-     * fresh `static_preview` variants. The entry HTML and its sibling assets are
-     * served straight from the variant's worktree project root (session-scoped,
-     * pre-commit; the persisted `.rivet/variants/.../files/` copy backs the
-     * post-session history route separately).
-     *
-     * Returns `registered` when the static preview is ready, `unavailable` when
-     * the project is static but its selected entry cannot be served, and
-     * `not_static` when the caller should start a dev server instead.
-     */
     async registerExistingStaticPreview(sessionId, workItemId, record) {
         let env;
         try {
@@ -4489,9 +3603,6 @@ class AgentVariantsOrchestrator {
             log.warn(`registerExistingStaticPreview: project cwd failed for ${sessionId}/${workItemId}`, err);
             return 'unavailable';
         }
-        // The materialized worktree IS the per-variant directory. Require its
-        // selected entry to exist; the directory is then served directly (no
-        // in-memory HTML copy — getStaticPreviewHtml reads it from here).
         const entryFile = path_1.default.join(projectCwd, env.entryPath);
         try {
             await fs_1.default.promises.access(entryFile, fs_1.default.constants.R_OK);
@@ -4513,41 +3624,26 @@ class AgentVariantsOrchestrator {
             });
             return 'unavailable';
         }
-        // The dir must be realpath'd so resolveStaticPreviewAssetPath's sandbox
-        // comparison lines up; sibling assets (css/js/images) then resolve from the
-        // same static root the entry HTML lives in.
         let dir;
         try {
             dir = fs_1.default.realpathSync(projectCwd);
         }
         catch {
-            // Fall back to the un-realpath'd cwd; serving still works, only the
-            // sandbox symlink-normalization is skipped.
             dir = projectCwd;
         }
-        // Host project root, used as a read-only fallback for assets the worktree
-        // clone is missing (git-ignored or binary files that `git worktree add` +
-        // text-patch + untracked-copy can't carry). Without this the original
-        // preview shows such an asset while the variant 404s. Realpath'd so the
-        // sandbox containment check in `resolveAssetWithinBase` lines up.
         let assetFallbackBase;
         try {
             const hostRealRoot = fs_1.default.realpathSync(env.projectPath);
-            // Skip the fallback if it would collapse onto the worktree root (can't
-            // happen in practice, but keeps the two roots genuinely distinct).
             if (hostRealRoot !== dir)
                 assetFallbackBase = hostRealRoot;
         }
         catch {
-            // No host root resolvable — serve worktree assets only.
         }
         resources.staticPreviews.set(workItemId, {
             workItemId,
             briefId: input.briefId,
             entryPath: env.entryPath,
             assetBase: dir,
-            // Existing-mode static projects are real multi-file sites — assume
-            // sibling assets so the preview route resolves relative URLs.
             hasAssets: true,
             ...(assetFallbackBase ? { assetFallbackBase } : {}),
         });
@@ -4563,25 +3659,10 @@ class AgentVariantsOrchestrator {
         });
         return 'registered';
     }
-    /**
-     * Persist a completed fresh-project variant into
-     * `<projectContext.workspacePath>/.rivet/variants/<sessionId>/<variantId>/`.
-     * Called from `handleSucceededReport` right after the per-variant snapshot
-     * lands on disk — for static_preview that's the `.rivet/<slug>/` snapshot
-     * dir; for vite_app fresh variants it's the worktree itself. Status starts
-     * as 'completed' and transitions to 'committed' / 'rejected' / 'cancelled'
-     * via `markStatus` at commit or teardown time.
-     *
-     * Running at success time (rather than commit time) means the history panel
-     * populates live as variants generate — including when the user never picks
-     * one. Mirrors the existing-project persistCompletedExistingVariant flow.
-     */
     async persistCompletedFreshVariant(args) {
         const projectContext = this.store.getProjectContext(args.sessionId);
         if (projectContext.kind !== 'fresh')
             return;
-        // Variant history lives in the generated project folder so reopening that
-        // folder gives the history panel the same owner path that wrote it.
         const historyProjectPath = projectContext.workspacePath;
         const input = this.store.getWorkItemInput(args.sessionId, args.workItemId);
         const sessionPrompt = this.store.getPrompt(args.sessionId);
@@ -4589,11 +3670,6 @@ class AgentVariantsOrchestrator {
         const resources = this.resources.get(args.sessionId);
         const worktreeRecord = resources?.worktrees.get(args.workItemId);
         const staticPreview = resources?.staticPreviews.get(args.workItemId);
-        // Vite_app deliverables are full scaffolded worktrees — pass the worktree
-        // directory as sourceDir and let copyDirFiltered handle it (excludes
-        // node_modules, .rivet, etc). Static_preview deliverables are inline HTML
-        // captured in `resources.staticPreviews`; stage them in a tmp dir so the
-        // existing copy path works without poking the user's workspace.
         let sourceDir = null;
         let tmpStagingDir = null;
         if (worktreeRecord && fs_1.default.existsSync(worktreeRecord.worktreePath)) {
@@ -4602,7 +3678,6 @@ class AgentVariantsOrchestrator {
         else if (staticPreview) {
             tmpStagingDir = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), `rivet-variant-${args.workItemId}-`));
             copyStaticPreviewDirectory(staticPreview.assetBase, tmpStagingDir);
-            // Read the materialized index.html from the variant's per-variant dir.
             let stagedHtml = '';
             try {
                 stagedHtml = fs_1.default.readFileSync(path_1.default.join(staticPreview.assetBase, 'index.html'), 'utf8');
@@ -4618,10 +3693,6 @@ class AgentVariantsOrchestrator {
             log.warn(`persistCompletedFreshVariant: no source for ${args.workItemId} (session ${args.sessionId}); skipping`);
             return;
         }
-        // For static_preview, only `index.html` is a real deliverable — `brief.md`
-        // is implementation-detail staging that we copy alongside it. Hardcode
-        // the count so the history row matches what `commit_variant` reports
-        // (always 1) instead of double-counting the brief.
         const changedFilesCount = staticPreview ? 1 : countWorktreeFiles(sourceDir);
         const preview = staticPreview
             ? { kind: 'static', entryPath: 'index.html' }
@@ -4633,12 +3704,6 @@ class AgentVariantsOrchestrator {
                     script: 'dev',
                 },
             };
-        // Tree-store serve contract. Fresh worktrees prefer the live record's
-        // resolved invocation (stashed at dev-server start); the fallback recipe
-        // mirrors resolveDevServer's fresh branch, which is fully deterministic
-        // for the Vite template. Static previews serve their staged index.html.
-        // Fresh sessions have no host project, so there is no base snapshot —
-        // variant commits are root commits.
         const serve = staticPreview
             ? { kind: 'static', entryPath: 'index.html' }
             : worktreeRecord?.devCommand && worktreeRecord.port !== undefined
@@ -4701,10 +3766,6 @@ class AgentVariantsOrchestrator {
             }
         }
     }
-    /**
-     * @effect Drains fresh-project history writes before commit moves or rewrites
-     * the generated project folder.
-     */
     async persistCompletedFreshVariantsForCommit(sessionId) {
         const projectContext = this.store.getProjectContext(sessionId);
         if (projectContext.kind !== 'fresh')
@@ -4724,14 +3785,6 @@ class AgentVariantsOrchestrator {
             }
         }
     }
-    /**
-     * At commit time, flip persisted variant manifests to terminal statuses
-     * ('committed' for the chosen, 'rejected' for the rest). Both existing- and
-     * fresh-project variants have already been persisted at code_gen success
-     * time, so this is a pure status update — no source-dir copy required.
-     * Also records the destination path on the chosen variant so history can
-     * surface "this variant became <path>".
-     */
     async persistVariantHistoryAtCommit(args) {
         const variants = this.store.getVariants(args.sessionId);
         for (const variant of variants) {
@@ -4752,13 +3805,6 @@ class AgentVariantsOrchestrator {
             });
         }
     }
-    /**
-     * Flip persisted variant manifests to status='cancelled' for every variant
-     * in the session that was already snapshotted to disk. Fresh- and existing-
-     * project variants both persist at success time now, so both need their
-     * manifests flipped here. Best-effort — missing manifests are silently
-     * skipped by VariantHistoryService.markStatus.
-     */
     async markPersistedVariantsCancelled(sessionId) {
         if (!this.store.hasSession(sessionId))
             return;
@@ -4794,9 +3840,6 @@ class AgentVariantsOrchestrator {
         const projectPath = await this.resolveHistoryProjectPath(sessionId);
         if (!projectPath)
             return;
-        // No-ops (ENOENT) when the variant was never persisted — e.g. removing a
-        // still-pending variant that produced no artifact. Completed variants have
-        // a manifest, which flips to `removed` and is retained on disk.
         await this.variantHistory.markStatus({
             projectPath,
             sessionId,
@@ -4810,9 +3853,6 @@ class AgentVariantsOrchestrator {
         const projectPath = await this.resolveHistoryProjectPath(sessionId);
         if (!projectPath)
             return;
-        // No-ops (ENOENT) when the variant has no manifest yet — e.g. renaming a
-        // still-generating direction before its artifact lands. The in-memory
-        // label still updates; the disk copy catches up when the variant persists.
         await this.variantHistory.renameVariant({
             projectPath,
             sessionId,
@@ -4821,11 +3861,6 @@ class AgentVariantsOrchestrator {
             runLabel,
         });
     }
-    /**
-     * Resolve the project path that owns `.rivet/variants/` for a session.
-     * Existing sessions use the user's project. Fresh sessions use the generated
-     * project folder. Must match what `persistCompletedFreshVariant` writes to.
-     */
     async resolveHistoryProjectPath(sessionId) {
         const projectContext = this.store.getProjectContext(sessionId);
         if (projectContext.kind === 'fresh') {
@@ -4852,13 +3887,6 @@ class AgentVariantsOrchestrator {
             return undefined;
         }
     }
-    /**
-     * The port to start scanning from when allocating a variant's preview dev
-     * server. Fresh worktrees run the Vite template (5173); existing projects use
-     * their detected framework's default (3000 for Next, etc.), falling back to
-     * 3000 if detection fails. Scanning upward from here lands the preview on a
-     * sensible, predictable port near the project's normal one.
-     */
     async resolveDevServerStartPort(sessionId, isFresh) {
         if (isFresh)
             return FRESH_DEV_SERVER_DEFAULT_PORT;
@@ -4870,30 +3898,15 @@ class AgentVariantsOrchestrator {
             return 3000;
         }
     }
-    /**
-     * Resolve dev server invocation for a worktree. Fresh-project worktrees
-     * always use the Vite template's npm command at the worktree root; existing
-     * projects defer to the user's framework/packageManager config.
-     */
-    async resolveDevServer(sessionId, workItemId, worktreePath, port, isFresh) {
+    async resolveDevServer(sessionId, worktreePath, port, isFresh) {
         const resolved = await this.resolveDevServerCommand(sessionId, worktreePath, port, isFresh);
-        if (!isFresh) {
-            await this.ensureExistingProjectDependencies({
-                sessionId,
-                workItemId,
-                cwd: resolved.cwd,
-                packageManager: resolved.packageManager,
-            });
-        }
+        await this.ensureProjectDependencies({
+            signal: this.resources.get(sessionId)?.dependencyAbortController.signal,
+            cwd: resolved.cwd,
+            workspaceRoot: worktreePath,
+        });
         return resolved;
     }
-    /**
-     * Pure invocation resolution — no dependency installs, no side effects.
-     * Split from {@link resolveDevServer} so history persistence can capture
-     * the SAME deterministic resolution the boot path uses without booting:
-     * persist fires at code-gen success, before the dev server starts, so the
-     * live record's stashed command usually isn't available yet.
-     */
     async resolveDevServerCommand(sessionId, worktreePath, port, isFresh) {
         if (isFresh) {
             return {
@@ -4917,18 +3930,28 @@ class AgentVariantsOrchestrator {
             throw new Error('Static projects do not have a dev server command');
         }
         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);
         }
+        const detected = fs_1.default.existsSync(path_1.default.join(cwd, 'package.json'))
+            ? await (0, ProjectPackageManager_1.resolveProjectPackageManager)({
+                cwd,
+                workspaceRoot: worktreePath,
+            }).catch((error) => {
+                throw new devServerError_1.DevServerStartError({
+                    message: error instanceof Error ? error.message : String(error),
+                    detail: '',
+                    reason: 'dependency_install_failed',
+                    portInUse: false,
+                });
+            })
+            : null;
+        const packageManager = detected?.name ?? env.packageManager;
         if (packageManager !== env.packageManager) {
             return {
                 cwd,
                 packageManager,
-                ...buildExistingProjectDevCommand(packageManager, env.devCommand, port),
+                ...(0, devServerCommand_1.buildDevServerCommand)(env.framework, packageManager, env.devCommand, port),
             };
         }
         if (env.buildDevCommand) {
@@ -4942,27 +3965,14 @@ class AgentVariantsOrchestrator {
             packageManager,
         };
     }
-    /**
-     * Existing-project variants usually reuse the user's installed
-     * node_modules. Nested example projects may be standalone packages with no
-     * install in the cloned worktree; install only when the package has no
-     * node_modules so normal user projects are not penalized.
-     */
-    async ensureExistingProjectDependencies(args) {
-        const packageJsonPath = path_1.default.join(args.cwd, 'package.json');
-        const nodeModulesPath = path_1.default.join(args.cwd, 'node_modules');
-        if (!fs_1.default.existsSync(packageJsonPath) || fs_1.default.existsSync(nodeModulesPath)) {
+    async ensureProjectDependencies(args) {
+        if (!fs_1.default.existsSync(path_1.default.join(args.cwd, 'package.json')))
             return;
-        }
-        await this.installDependencies(args.cwd, args.packageManager);
+        await this.installDependencies(args.cwd, {
+            workspaceRoot: args.workspaceRoot,
+            signal: args.signal,
+        });
     }
-    /**
-     * Resolve the dev-server working directory for an existing-project variant.
-     * WorktreeManager is constructed around the editor/root project, but
-     * `start_variants` can target a nested app (for example `examples/blog`).
-     * In that case the worktree root is still the git root clone, while the dev
-     * server must run from the nested project path.
-     */
     async resolveExistingProjectCwd(sessionId, worktreePath, env) {
         const fallback = await this.worktrees.getProjectCwdInWorktree(worktreePath);
         try {
@@ -4980,17 +3990,6 @@ class AgentVariantsOrchestrator {
             return fallback;
         }
     }
-    /**
-     * After the chosen variant has been renamed into `destinationPath`, move
-     * each unchosen sibling worktree into a `<destinationParent>/<slug>-variants/NN-<label>/`
-     * folder and repoint its `node_modules` symlink at the chosen project's
-     * real install. Writes a manifest documenting all 5 variants (the chosen
-     * one with `folder: null` and `chosenPath: '../<slug>'`).
-     *
-     * Sets `vitePreservedSiblings = true` on session resources so the
-     * subsequent teardown skips `cleanupFreshWorktrees` (which would otherwise
-     * delete the just-preserved history). Dev servers still get stopped.
-     */
     preserveUnchosenVariants(args) {
         const resources = this.resources.get(args.sessionId);
         const runnablePaths = new Map();
@@ -4999,7 +3998,6 @@ class AgentVariantsOrchestrator {
         const destinationParent = path_1.default.dirname(args.destinationPath);
         const projectSlug = path_1.default.basename(args.destinationPath);
         const historyDir = (0, createProjectArtifacts_1.createVariantsHistoryPath)(destinationParent, projectSlug);
-        const sharedNodeModulesAbs = path_1.default.join(args.destinationPath, 'node_modules');
         const briefs = this.store.getBriefs(args.sessionId);
         const variants = this.store.getVariants(args.sessionId);
         const briefIndexById = new Map(briefs.map((b, i) => [b.briefId, i]));
@@ -5027,8 +4025,6 @@ class AgentVariantsOrchestrator {
             }
             const record = resources.worktrees.get(variant.workItemId);
             if (!record) {
-                // No worktree (e.g. failed variant) — still list it in manifest with
-                // null folder so the user can see why it's absent.
                 manifestEntries.push({
                     variantId: variant.workItemId,
                     label,
@@ -5057,28 +4053,6 @@ class AgentVariantsOrchestrator {
                         fs_1.default.renameSync(record.worktreePath, dest);
                         return dest;
                     })();
-                // Repoint node_modules at the chosen project's real install.
-                try {
-                    if (this.worktrees.repointNodeModulesSymlink) {
-                        this.worktrees.repointNodeModulesSymlink(newPath, sharedNodeModulesAbs);
-                    }
-                    else {
-                        const link = path_1.default.join(newPath, 'node_modules');
-                        try {
-                            fs_1.default.rmSync(link, { force: true, recursive: true });
-                        }
-                        catch {
-                            /* may not exist */
-                        }
-                        const target = path_1.default.relative(path_1.default.dirname(link), sharedNodeModulesAbs);
-                        fs_1.default.symlinkSync(target, link, 'dir');
-                    }
-                }
-                catch (err) {
-                    log.warn(`repointNodeModulesSymlink failed for ${newPath}; variant still runnable after npm install`, err);
-                }
-                // Update the in-memory record so teardown doesn't try to operate on
-                // the stale path.
                 record.worktreePath = newPath;
                 runnablePaths.set(variant.workItemId, `${path_1.default.basename(historyDir)}/${folderName}`);
                 manifestEntries.push({
@@ -5117,22 +4091,7 @@ class AgentVariantsOrchestrator {
         resources.vitePreservedSiblings = true;
         return runnablePaths;
     }
-    /**
-     * Rename `sourceWorktreePath` into `destinationPath`, then replace the
-     * worktree's `.git` with a fresh-history init + initial commit. Matches
-     * the historical materializeProject behavior of "user sees a fresh repo
-     * at destinationPath" so we don't surprise them with a `rivet: variant
-     * baseline` commit they didn't intend.
-     *
-     * The rename is the load-bearing operation: it moves the entire variant
-     * tree (template files + materialized node_modules) in O(1) when the
-     * source and destination share a volume. The git reset that follows is
-     * best-effort housekeeping; a failure there leaves files in place.
-     */
     async renameWorktreeIntoDestination(sourceWorktreePath, destinationPath) {
-        // destinationPath must not exist for fs.rename to behave as a move.
-        // assertDestinationAvailable already enforced that any existing directory
-        // contains only `.rivet`, which we preserve across the move.
         const destinationParent = path_1.default.dirname(destinationPath);
         await fs_1.default.promises.mkdir(destinationParent, { recursive: true });
         let preservedRivetParent;
@@ -5179,15 +4138,11 @@ class AgentVariantsOrchestrator {
                 force: true,
             });
         }
-        // Replace the variant-baseline git history with a fresh init so the
-        // user doesn't inherit a `rivet: variant baseline` commit.
         const dotGit = path_1.default.join(destinationPath, '.git');
         try {
             fs_1.default.rmSync(dotGit, { recursive: true, force: true });
         }
         catch {
-            // Best-effort — leaving the baseline .git is preferable to failing
-            // the commit after we've moved the tree.
         }
         try {
             const git = (0, simple_git_1.simpleGit)(destinationPath);
@@ -5205,22 +4160,12 @@ class AgentVariantsOrchestrator {
                 'Initial commit (created with Rivet)',
             ])
                 .catch(() => {
-                // Best-effort: missing user identity or empty tree leaves the
-                // commit step un-applied. Files are still in place.
             });
         }
         catch (err) {
             log.warn(`Initial git history setup at ${destinationPath} failed`, err);
         }
     }
-    /**
-     * Stop every variant dev server currently running for `resources`. Clears
-     * the `devServerProcess` / `port` fields on each record so subsequent
-     * teardown logic doesn't try to stop them a second time. Called from
-     * `commitVariant` (vite_app rename path) BEFORE the worktree directory is
-     * renamed — leaving Vite alive across the rename leaks empty `.vite/`
-     * stub dirs at the old paths.
-     */
     async stopAllDevServersForSession(resources) {
         this.clearActivePreviewIdleTimer(resources);
         const stops = [];
@@ -5259,7 +4204,6 @@ class AgentVariantsOrchestrator {
         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)
@@ -5288,8 +4232,6 @@ class AgentVariantsOrchestrator {
             }
             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 {
                 this.switchPreviewPort?.(null);
             }
@@ -5305,18 +4247,6 @@ class AgentVariantsOrchestrator {
         resources.activePreviewIdleStop = stop;
         await stop;
     }
-    /**
-     * Spawn a fresh dev server at the user-facing destinationPath and retarget
-     * the proxy so the iframe stays live across commit. Stores the process on
-     * `resources.committedDevServer` so teardown can hand it off to the
-     * lingering registry instead of killing it. Best-effort: a failure here is
-     * non-fatal — the commit still succeeds; the user just has to run
-     * `npm run dev` themselves to bring the preview back.
-     *
-     * `mode` selects the server flavor: `vite_app` spawns Vite via `npm run
-     * dev`; `static_preview` spawns the in-tree static file server bound to
-     * the destination directory (no install, no build, ~ms startup).
-     */
     async startCommittedDevServer(args) {
         const mode = args.mode ?? 'vite_app';
         try {
@@ -5341,14 +4271,6 @@ class AgentVariantsOrchestrator {
                 port,
                 path: args.destinationPath,
             };
-            // Advertise the Rivet-owned server on devServerHealth so the iframe's
-            // upstream probe stops reporting `ownership: 'none'`. Distinct from
-            // switchPreviewPort: this updates health metadata, switchPreviewPort
-            // retargets the proxy. Both fire here because the commit-handoff is
-            // the only place Rivet legitimately takes ownership of the dev
-            // server — variant cycling and cancel only retarget, they don't
-            // touch health (which the user's external dev server owns during a
-            // regular session).
             try {
                 this.setCommittedDevServerHealth?.(port);
             }
@@ -5369,19 +4291,9 @@ class AgentVariantsOrchestrator {
             return undefined;
         }
     }
-    /**
-     * Stop any committed dev servers that were left alive past their session's
-     * teardown. Called at the start of a new `propose` (so the next session's
-     * preview doesn't compete with stale processes) and exposed for explicit
-     * shutdown hooks. Best-effort: per-server failures are logged but don't
-     * propagate.
-     */
     async stopLingeringCommittedDevServers() {
         const entries = [...this.lingeringCommittedDevServers.entries()];
         this.lingeringCommittedDevServers.clear();
-        // Clear the Rivet-owned-server advertisement on `devServerHealth` so the
-        // probe doesn't keep reporting a port that's about to stop listening.
-        // Safe to call even when no committed server existed for this process.
         if (entries.length > 0) {
             try {
                 this.setCommittedDevServerHealth?.(null);
@@ -5408,40 +4320,22 @@ class AgentVariantsOrchestrator {
         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
-        // below doesn't fail — it stages whatever files remain, publishing a
-        // silently truncated snapshot. The design doc's ordering constraint
-        // ("tree committed before worktree teardown") is enforced here, not
-        // just in tests. Best-effort with a bound: never let a wedged git call
-        // stall teardown forever.
+        resources.dependencyAbortController.abort();
+        await Promise.all([...resources.worktrees.values()].map((record) => DependencyPreparationService_1.previewDependencies.settle(record.worktreePath)));
         await Promise.race([
             this.settleHistoryPersists(),
             new Promise((resolve) => setTimeout(resolve, SETTLE_PERSISTS_TEARDOWN_TIMEOUT_MS)),
         ]);
-        // Stop dev servers in parallel; ignore individual failures.
-        // NOTE: For the fresh vite_app rename path, commitVariant already stopped
-        // these dev servers BEFORE the rename (so Vite couldn't recreate `.vite/`
-        // stub dirs at the old worktree paths). In that case devServerProcess is
-        // already cleared and this loop is a no-op — exactly the desired behavior.
         const stops = [...resources.worktrees.values()]
             .filter((r) => r.devServerProcess)
             .map((r) => this.worktrees
             .stopDevServer(r.devServerProcess)
             .catch((err) => log.warn(`stopDevServer failed for ${sessionId}/${r.workItemId}`, err)));
         await Promise.all(stops);
-        // The committed dev server (spawned at destinationPath after a fresh
-        // vite_app commit) intentionally outlives this teardown — the iframe is
-        // pointed at it via the proxy and the user just chose this project. Hand
-        // it off to the lingering registry; it'll be stopped on the next
-        // `propose` or explicit shutdown.
         if (resources.committedDevServer && reason === 'committed') {
             this.lingeringCommittedDevServers.set(sessionId, resources.committedDevServer);
         }
         else if (resources.committedDevServer) {
-            // Non-committed teardown (cancel/shutdown) with a committed dev server
-            // shouldn't happen in current code paths, but stop it defensively so we
-            // don't leak procs.
             try {
                 await this.worktrees.stopDevServer(resources.committedDevServer.proc);
             }
@@ -5449,10 +4343,6 @@ class AgentVariantsOrchestrator {
                 log.warn(`stopDevServer for committed dev server (session ${sessionId}) failed`, err);
             }
         }
-        // When a vite_app commit already moved the unchosen worktrees into a
-        // sibling history dir, calling cleanupSession would re-delete them. Skip
-        // the worktree removal step in that case — the move already cleared the
-        // .rivet-variants/ entries for the chosen + preserved variants.
         if (!resources.vitePreservedSiblings) {
             try {
                 await this.worktrees.cleanupSession(sessionId, resources.freshDestinationParent);
@@ -5461,10 +4351,6 @@ class AgentVariantsOrchestrator {
                 log.warn(`cleanupSession (worktree removal) failed for ${sessionId}`, err);
             }
         }
-        // Assigned static workspaces are always Rivet-owned, including existing-
-        // project refinement work staged under `.rivet/variant-work` or /tmp.
-        // Fresh staticPreviews are also Rivet staging unless commit already moved
-        // the selected directory into the destination.
         const ownedArtifactRoots = new Set(resources.workspaceManager.getOwnedArtifactRoots());
         resources.workspaceManager.removeOwnedArtifactWorkspaces();
         const staticDirectories = new Set();
@@ -5504,6 +4390,7 @@ class AgentVariantsOrchestrator {
                 workspaceManager: new VariantWorkspaceManager_1.VariantWorkspaceManager(),
                 contextAssets: new Map(),
                 cleanupStarted: false,
+                dependencyAbortController: new AbortController(),
                 committedVariantIds: new Set(),
                 startedAt: Date.now(),
                 nextRoundIndex: 0,
@@ -5521,10 +4408,6 @@ class AgentVariantsOrchestrator {
     }
 }
 exports.AgentVariantsOrchestrator = AgentVariantsOrchestrator;
-/** MCP bridges sometimes serialize the output field as a JSON string instead
- *  of a parsed object. Normalize it before field-level inspection. */
-/** Rough byte-size of the agent's output. Used as a proxy for "how much
- *  code did the agent write" when comparing HTML vs full-stack flows. */
 function estimateOutputBytes(output) {
     if (output === undefined || output === null)
         return 0;
@@ -5548,28 +4431,11 @@ function normalizeOutput(output) {
     }
     return output;
 }
-/**
- * `true` when `child` is a strict descendant of `parent` (resolved). Used by
- * the static_preview commit branch before rm/rename to make sure we never
- * touch anything outside the variant's workspace.
- */
 function isStrictlyInside(child, parent) {
     const c = path_1.default.resolve(child);
     const p = path_1.default.resolve(parent);
     return c !== p && c.startsWith(p + path_1.default.sep);
 }
-/**
- * Resolve `requestedPath` to an absolute, sandboxed file under `base`, or
- * `undefined` if it escapes the base, doesn't exist, isn't a regular file, or
- * is a hardlink. Shared by `resolveStaticPreviewAssetPath` across the variant's
- * own directory and the host-root fallback so both get identical containment.
- *
- * `base` is expected to be realpath'd by the caller. The requested target is
- * realpath'd here too — without it, a symlink planted under the base (e.g. via
- * a follow-up Write tool call) could pivot outside the sandbox. `requestedPath`
- * is used as Express delivered it (already URL-decoded); decoding again would
- * mangle filenames that legitimately contain `%` (e.g. `100%25.png` on disk).
- */
 function resolveAssetWithinBase(base, requestedPath) {
     const target = path_1.default.resolve(base, '.' + path_1.default.sep + requestedPath);
     if (target !== base && !target.startsWith(base + path_1.default.sep)) {
@@ -5589,11 +4455,6 @@ function resolveAssetWithinBase(base, requestedPath) {
         const stat = fs_1.default.statSync(realTarget);
         if (!stat.isFile())
             return undefined;
-        // Hardlinks aren't dereferenced by `realpath` — they ARE the file from a
-        // path-resolution perspective, so the realpath check above can't detect
-        // them. An agent could `ln /path/to/.env base/x.glb` (hardlink, not
-        // symlink) and the resolver would happily serve the secret. Reject
-        // anything with multiple links — legitimate assets always have nlink === 1.
         if (stat.nlink !== 1)
             return undefined;
         return realTarget;
@@ -5602,19 +4463,6 @@ function resolveAssetWithinBase(base, requestedPath) {
         return undefined;
     }
 }
-/**
- * Sandbox the agent's `output.assetBase` to a path inside the session
- * workspace. Accepts either an absolute path (used as-is after the
- * within-workspace check) or a path relative to the fresh-session
- * `workspacePath`. Returns `undefined` for non-fresh sessions, missing
- * directories, or paths that escape the workspace via `..` or symlinks.
- *
- * `assetBase` is agent-controlled, so a prompt-injected variant could point
- * it at a symlink whose real target is outside `workspacePath` — and the
- * asset endpoint would then happily serve files like `~/.ssh/id_rsa` or
- * `.env`. Resolving with `fs.realpathSync` collapses symlinks before the
- * containment check, so the check applies to the real target, not the link.
- */
 function resolveStaticPreviewAssetBase(args) {
     if (!args.assetBase)
         return undefined;
@@ -5623,23 +4471,6 @@ function resolveStaticPreviewAssetBase(args) {
     let workspace;
     let resolved;
     try {
-        // Defense against an agent that subverts the sandbox by replacing the
-        // Rivet-created `workspacePath` directory with a symlink. Plain
-        // `realpath` would silently follow that symlink and the containment
-        // check below would then trust the wrong root.
-        //
-        // Two layers:
-        //   1. `lstat` the workspacePath itself — if it's a symlink (rather
-        //      than a real directory Rivet created), reject outright. This
-        //      catches the obvious swap `ln -sf $HOME <workspacePath>` and the
-        //      subtler swap to a sibling like `<workspaceRoot>` itself
-        //      (which would pass any subsequent containment check based on
-        //      ancestor matching).
-        //   2. realpath both and require the resolved workspacePath to be a
-        //      STRICT descendant of the resolved workspaceRoot — equal is not
-        //      enough (a symlink to workspaceRoot would otherwise be accepted
-        //      and the asset route would then serve files at the project
-        //      root, e.g. `.env`).
         const wsStat = fs_1.default.lstatSync(args.projectContext.workspacePath);
         if (wsStat.isSymbolicLink()) {
             log.warn(`Static preview workspacePath ${args.projectContext.workspacePath} is a symlink — refusing assetBase`);
@@ -5701,11 +4532,6 @@ function buildStaticPreviewDocument(input) {
     const style = input.css ? `<style>\n${input.css}\n</style>` : '';
     const script = input.js ? `<script>\n${input.js}\n</script>` : '';
     if (/<!doctype html>|<html[\s>]/i.test(input.html)) {
-        // Full document: inject css before </head> and js before </body>. The
-        // agent often passes a complete `<!doctype html>...` blob with css/js
-        // alongside; without this they're silently dropped and the variant ships
-        // unstyled and non-interactive. Falls back to appending to the end if
-        // the closing tag isn't found.
         let doc = input.html;
         if (style) {
             if (/<\/head>/i.test(doc)) {
@@ -5739,15 +4565,8 @@ ${input.html}
 </html>`;
 }
 function countDiffFiles(diff) {
-    // Each file in a unified diff starts with "diff --git ".
     return (diff.match(/^diff --git /gm) ?? []).length;
 }
-/**
- * Count source files under a materialized fresh-project destination,
- * skipping install artifacts (`node_modules`, `.git`, build outputs) so the
- * commit telemetry / chip count reflects the agent-visible surface area
- * rather than the install footprint.
- */
 function countWorktreeFiles(destinationPath) {
     let count = 0;
     const walk = (dir) => {
@@ -5780,8 +4599,6 @@ const enrichDesignSource = (design) => {
     };
 };
 const toActiveProjectContext = (projectContext) => {
-    // Source count + grounding are derived purely from the read-only context
-    // bundle now that `sourceContext` intake is gone.
     const sourceCount = projectContext.variantContext?.userContext.filter((source) => source.transport !== 'prompt').length ?? 0;
     const hasSourceContextSummary = Boolean(sourceCount > 0 ||
         (projectContext.variantContext?.rivetMetadata.length ?? 0) > 0);
@@ -5824,18 +4641,6 @@ const toActiveProjectContext = (projectContext) => {
             : {}),
     };
 };
-/**
- * Resolve the user-facing supporting artifacts for a session.
- *
- * For 0→1 (`fresh`) sessions with a populated `designContext`, each slot is
- * turned into a `design_context` artifact that links to Rivet-hosted
- * DESIGN.md views:
- *   - `slug` entries resolve bundled catalog markdown via the design catalog.
- *   - `markdown` entries (Agent Browser / inspiration extractor output) carry
- *     their stored markdown when the linked route is requested.
- * Slots whose markdown can't be resolved are skipped so the UI never renders
- * a metadata-only DESIGN.md row.
- */
 const buildSessionArtifacts = (sessionId, projectContext) => {
     const artifacts = buildResolvedDesignContextArtifacts(projectContext);
     return artifacts.map(({ content: _content, ...artifact }) => ({
@@ -6173,7 +4978,6 @@ const renderDesignMarkdown = (markdown, artifactLabel) => {
             const headingText = headingMatch[2].trim();
             const isDuplicateTitle = headingText === artifactLabel ||
                 headingText === `${artifactLabel} DESIGN.md`;
-            // The viewer header already renders the artifact title.
             if (level === 1 && !skippedFirstH1 && isDuplicateTitle) {
                 skippedFirstH1 = true;
                 return;
@@ -6215,14 +5019,6 @@ const escapeHtml = (value) => {
         .replace(/"/g, '&quot;')
         .replace(/'/g, '&#39;');
 };
-/**
- * Resolve a per-variant design context entry into the raw DESIGN.md markdown
- * the worktree scaffolder writes, plus a small `designSource` descriptor for
- * the variant manifest. Slug entries resolve through the bundled catalog;
- * markdown entries (Agent Browser / inspiration extractor output) carry their
- * stored markdown verbatim. Returns null when the entry is missing or the
- * slug doesn't resolve to bundled markdown.
- */
 const resolveDesignArtifact = (entry) => {
     if (!entry)
         return null;
@@ -6447,62 +5243,14 @@ function copyStaticPreviewDirectory(src, dest) {
         }
     }
 }
-const buildInstallCommand = (packageManager) => {
-    if (packageManager === 'npm') {
-        return {
-            cmd: 'npm',
-            args: ['install', '--no-audit', '--no-fund', '--ignore-scripts'],
-        };
-    }
-    return {
-        cmd: packageManager,
-        args: ['install', '--ignore-scripts'],
-    };
-};
-const defaultInstallDependencies = (worktreePath, packageManager = 'npm') => {
-    const install = buildInstallCommand(packageManager);
-    return new Promise((resolve, reject) => {
-        const proc = (0, child_process_1.spawn)(install.cmd, install.args, {
-            cwd: worktreePath,
-            stdio: ['ignore', 'ignore', 'pipe'],
-        });
-        let stderr = '';
-        proc.stderr.on('data', (chunk) => {
-            stderr += chunk.toString();
-        });
-        proc.on('error', reject);
-        proc.on('exit', (code) => {
-            if (code === 0) {
-                resolve();
-                return;
-            }
-            reject(new Error(`${install.cmd} install in ${worktreePath} failed (code ${code}): ${stderr.slice(-512)}`));
-        });
+const defaultInstallDependencies = async (worktreePath, options) => {
+    await DependencyPreparationService_1.previewDependencies.prepare({
+        cwd: worktreePath,
+        workspaceRoot: options?.workspaceRoot ?? worktreePath,
+        force: options?.force,
+        signal: options?.signal,
     });
 };
-const detectPackageManagerForCwd = (cwd, fallback) => {
-    if (fs_1.default.existsSync(path_1.default.join(cwd, 'yarn.lock')))
-        return 'yarn';
-    if (fs_1.default.existsSync(path_1.default.join(cwd, 'pnpm-lock.yaml')))
-        return 'pnpm';
-    if (fs_1.default.existsSync(path_1.default.join(cwd, 'package-lock.json')))
-        return 'npm';
-    if (fallback === 'pnpm' || fallback === 'yarn' || fallback === 'npm') {
-        // A nested package without a lockfile should not inherit a root Yarn Berry
-        // workspace when it is not declared as a workspace member; npm treats it as
-        // an independent package and is the safest default for old examples.
-        return fs_1.default.existsSync(path_1.default.join(cwd, 'package.json')) ? 'npm' : fallback;
-    }
-    return 'npm';
-};
-/**
- * Turn the invocation a live dev server actually booted with into a
- * port-parameterized replay recipe. The resolution bakes the allocated port
- * into args/env (`--port <n>`, `PORT=<n>`) — storing that verbatim would
- * bake in a dead port, so occurrences of the port (digit-boundary-guarded so
- * incidental digit runs survive) become `${PORT}` for replay to substitute.
- * `cwd` is stored relative to the snapshot root per the tree-root contract.
- */
 const buildServeRecipeFromResolved = (snapshotRoot, dev, port) => {
     const portPattern = new RegExp(`(?<![0-9])${port}(?![0-9])`, 'g');
     const sub = (value) => value.replace(portPattern, '${PORT}');
@@ -6514,15 +5262,6 @@ 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();
@@ -6531,15 +5270,6 @@ const canInstallWithoutTouchingHost = (cwd) => {
         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 {
@@ -6568,39 +5298,6 @@ const assertDevScriptExists = (cwd, scriptName) => {
             : '',
     });
 };
-const buildExistingProjectDevCommand = (packageManager, devCommand, port) => {
-    const env = { PORT: String(port) };
-    if (packageManager === 'npm') {
-        return {
-            cmd: 'npm',
-            args: [
-                'run',
-                devCommand,
-                '--',
-                '--port',
-                String(port),
-                '--host',
-                FRESH_DEV_SERVER_HOST,
-            ],
-            env,
-        };
-    }
-    return {
-        cmd: packageManager,
-        args: [devCommand, '--port', String(port), '--host', FRESH_DEV_SERVER_HOST],
-        env,
-    };
-};
-/**
- * True when `a` and `b` (or the closest existing ancestor of each) live on
- * the same filesystem volume. Used by commitVariant to decide between an
- * O(1) rename and a recursive copy-with-reinstall fallback.
- *
- * `destinationPath` for fresh sessions does not exist yet (we'd fail the
- * "destination must be empty" guard otherwise), so we compare against its
- * parent directory which is guaranteed to exist (createZeroToOneTool either
- * created it or validated it).
- */
 function areSameVolume(a, b) {
     try {
         const statA = fs_1.default.statSync(a);
@@ -6612,65 +5309,19 @@ function areSameVolume(a, b) {
         return false;
     }
 }
-/**
- * Materialize node_modules from symlink → real directory at the given path,
- * so a subsequent rename of that path leaves a self-contained tree.
- *
- * Fresh worktrees 1..N share variant 0's node_modules via a symlink (see
- * runBackgroundInstall). When the user picks variant K and we rename it
- * into the destination, the sibling worktrees get torn down — which would
- * otherwise leave a dangling symlink in the destination if variant K was
- * the one with the symlink (K > 0).
- *
- * Returns true when the destination must run a dependency install after the
- * rename because node_modules is missing or points nowhere.
- */
 async function resolveNodeModulesSymlink(worktreePath) {
     const nodeModulesPath = path_1.default.join(worktreePath, 'node_modules');
-    let lstat;
-    try {
-        lstat = await fs_1.default.promises.lstat(nodeModulesPath);
-    }
-    catch {
-        return true;
-    }
-    if (!lstat.isSymbolicLink())
-        return false;
-    let target;
     try {
-        target = await fs_1.default.promises.realpath(nodeModulesPath);
-    }
-    catch {
+        if (!(await fs_1.default.promises.lstat(nodeModulesPath)).isSymbolicLink())
+            return false;
         await fs_1.default.promises.rm(nodeModulesPath, { force: true });
         return true;
     }
-    // Stage the copy under a sibling temp name so a mid-copy failure (disk
-    // full, EACCES, etc.) leaves the original symlink intact rather than
-    // wiping it and leaving the worktree with no node_modules at all.
-    // The final swap is then atomic on the same filesystem (rename + unlink).
-    const stagingPath = `${nodeModulesPath}.materializing-${(0, crypto_1.randomBytes)(4).toString('hex')}`;
-    try {
-        await fs_1.default.promises.cp(target, stagingPath, {
-            recursive: true,
-            dereference: false,
-        });
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return true;
+        throw error;
     }
-    catch (err) {
-        // Best-effort cleanup of the partial staging dir; leave the symlink
-        // intact so the caller can re-run materialization.
-        await fs_1.default.promises
-            .rm(stagingPath, { recursive: true, force: true })
-            .catch(() => { });
-        throw err;
-    }
-    // Swap: remove the symlink, then rename the staging dir into place.
-    // Both operations are local fs ops on the same parent — fast and
-    // unlikely to fail independently, but if the rename fails the symlink
-    // is already gone, so prefer to leave the staging dir on disk over a
-    // half-broken worktree (the caller will surface the throw).
-    await fs_1.default.promises.rm(nodeModulesPath, { force: true });
-    await fs_1.default.promises.rename(stagingPath, nodeModulesPath);
-    return false;
 }
 const defaultMaterializeProject = async (sourceWorktreePath, destinationPath) => {
     await fs_1.default.promises.mkdir(destinationPath, { recursive: true });
@@ -6699,16 +5350,8 @@ const defaultMaterializeProject = async (sourceWorktreePath, destinationPath) =>
         'Initial commit (created with Rivet)',
     ])
         .catch(() => {
-        // Best-effort: a missing user identity or empty tree leaves the
-        // commit step un-applied. The destination still has the files.
     });
 };
-/**
- * Synthesize a fallback brief body for a human-direct unified start slot.
- * Agent callers provide structured briefs before starting. Human-direct
- * batches get stable, slot-specific focus statements without another model
- * call so workers do not independently invent overlapping directions.
- */
 function synthesizeUnifiedBriefBody(prompt, index, total) {
     const trimmed = prompt.trim().replace(/\s+/g, ' ').slice(0, 200);
     const intent = trimmed.length > 0 ? trimmed : 'Create this variant';