rivet-design 0.17.3 → 0.17.5

package/dist/services/WorktreeManager.js

@@ -15,72 +15,27 @@ const designCatalog_1 = require("./templates/designCatalog");
 const viteReactTs_1 = require("./templates/viteReactTs");
 const devServerError_1 = require("../utils/devServerError");
 const portUtils_1 = require("../utils/portUtils");
-const cloneOrCopyDirSync_1 = require("../utils/cloneOrCopyDirSync");
+const internalGitIdentity_1 = require("../utils/internalGitIdentity");
+const ProjectPackageManager_1 = require("./ProjectPackageManager");
 const OperatingSystemServices_1 = require("./OperatingSystemServices");
 const log = (0, logger_1.createLogger)('WorktreeManager');
-// How long a freshly-spawned dev server may go SILENT (no stdout/stderr)
-// before we give up on it answering on its port. Inactivity-based rather than
-// a flat wall clock: a large Next/Vite project's cold first compile can chew
-// through 30s+ while chattering progress output, and killing it mid-compile
-// manufactured `timeout` failures. A server that is still printing is still
-// making progress; only a genuinely silent one is presumed wedged. The probe
-// fails fast on early process exit regardless.
 const DEV_SERVER_READY_INACTIVITY_MS = 30_000;
-// Absolute ceiling on the readiness wait, however chatty the process is —
-// bounds worst-case UX for a dev server that logs forever without serving.
 const DEV_SERVER_READY_MAX_MS = 120_000;
 const DEV_SERVER_PROBE_TIMEOUT_MS = 1_000;
-// Keep a rolling tail of the dev server's output so a failed start is
-// diagnosable (which port it tried, EADDRINUSE, missing script) without
-// retaining unbounded logs.
 const DEV_SERVER_OUTPUT_TAIL_LIMIT = 4_000;
-// Abort any git child process that goes silent (no stdout/stderr) for this
-// long. Provisioning worktrees for a large project (e.g. React Native, whose
-// working tree carries native build dirs) used to hang indefinitely because
-// none of these git calls had a timeout — a stuck `worktree add`/`commit`
-// would stall the whole `start_variants` tool call. `block` resets on every
-// data chunk, so a slow-but-progressing checkout keeps running; only a
-// genuinely wedged process (lock contention, credential/hook prompt) trips it.
 const GIT_BLOCK_TIMEOUT_MS = 120_000;
 const GIT_OPTS = { timeout: { block: GIT_BLOCK_TIMEOUT_MS } };
-// Existing-project worktrees still go under /tmp — `git worktree add` refuses
-// to nest inside the main worktree, so the user's project tree is off-limits
-// and /tmp is the right neutral location.
 const EXISTING_WORKTREE_BASE = '/tmp';
-// Fresh-project worktrees live under destinationParent so commit time is a
-// same-volume rename instead of a cross-volume cp. Tucked under a
-// dot-prefixed dir so the editor file tree collapses them cleanly.
 exports.FRESH_WORKTREES_DIRNAME = '.rivet-variants';
 const WORKTREE_PREFIX = 'rivet-variants';
 const SESSION_ID_PATTERN = /^[A-Za-z0-9_-]+$/;
-// Include the PID so each server instance only cleans up its own worktrees.
 exports.INSTANCE_PREFIX = `${WORKTREE_PREFIX}-pid${process.pid}`;
-// Registry of every destinationParent that has ever housed a fresh-worktree
-// root in this user account. Read at startup so orphan cleanup can sweep
-// roots created by prior MCP processes that crashed before teardown ran.
 const FRESH_ROOTS_REGISTRY_PATH = path_1.default.join(os_1.default.homedir(), '.rivet', 'fresh-worktree-roots.json');
 const FRESH_SESSION_ERROR = 'Fresh-project sessions have no source project — this operation requires an existing project path.';
 class WorktreeManager {
     operatingSystemServices;
     resolveProjectPath;
-    /**
-     * Ports handed out by `findFreePortFrom` to a dev server that hasn't bound
-     * them yet. Until a port is actually listening, a bind/connect probe still
-     * sees it as free, so without this set two concurrent variant starts would
-     * both walk away with the same "free" port and collide. Released (see
-     * `releasePort`) once the dev server has bound the port — at which point the
-     * listener check sees it taken — or has failed to start.
-     */
     reservedPorts = new Set();
-    /**
-     * Accepts either a static path, null, or a lazy getter. The getter form
-     * lets long-lived callers (e.g. the agent-variants orchestrator) defer the
-     * project path until each operation, since `bridge.getProjectPath()`
-     * isn't known until `open_visual_editor` runs. A null projectPath is
-     * allowed for fresh-project sessions that scaffold from scratch and
-     * therefore have no source repo; methods that need a real project path
-     * throw a clear error in that case.
-     */
     constructor(projectPath, operatingSystemServices = OperatingSystemServices_1.selectedOperatingSystemServices) {
         this.operatingSystemServices = operatingSystemServices;
         if (typeof projectPath === 'function') {
@@ -98,29 +53,12 @@ class WorktreeManager {
         }
         return resolved;
     }
-    /**
-     * Return the absolute git root for the repo containing this.projectPath.
-     * When projectPath is a subdirectory (e.g. examples/microsoft-paint inside
-     * rivet-core), this returns the repo root — not the subdirectory.
-     */
     async getGitRoot() {
         const root = await (0, simple_git_1.simpleGit)(this.projectPath, GIT_OPTS).revparse([
             '--show-toplevel',
         ]);
         return root.trim();
     }
-    /**
-     * Resolve a path to its canonical (symlinks-followed) form.
-     *
-     * `getGitRoot` returns a git-canonicalized path (`rev-parse
-     * --show-toplevel` resolves symlinks), but `this.projectPath` may be a
-     * symlinked path — on macOS `/tmp` → `/private/tmp`. Computing
-     * `path.relative` between a canonical git root and a symlinked project path
-     * yields an ESCAPING relative path (e.g. `../../../tmp/...`), which then
-     * resolves OUTSIDE the worktree. Canonicalizing both sides first keeps the
-     * relative path inside the tree. Falls back to a plain `path.resolve` when
-     * the path doesn't exist yet (realpath throws ENOENT).
-     */
     async realPath(p) {
         try {
             return await fs_1.default.promises.realpath(p);
@@ -129,21 +67,6 @@ class WorktreeManager {
             return path_1.default.resolve(p);
         }
     }
-    /**
-     * Ensure `this.projectPath` is inside a git repo, bootstrapping one if not.
-     *
-     * Fresh / blank projects (an empty folder, or a plain HTML preview) that the
-     * user opens outside any repo would otherwise fail at `git worktree add`
-     * (and `getGitRoot`'s `rev-parse --show-toplevel`) with "expected a git
-     * workspace". We `git init` the folder and create an EMPTY initial commit so
-     * `HEAD` exists — `git worktree add HEAD` requires a commit to point at, so a
-     * bare `git init` on a blank folder isn't enough. `add -A` first captures
-     * whatever is already there (e.g. an `index.html`) as the starting point.
-     *
-     * No-op when an enclosing repo already has a HEAD commit — we never nest a
-     * repo inside another. Best-effort: a failure here surfaces at the
-     * subsequent worktree step rather than masking the original operation.
-     */
     async ensureGitRepo() {
         const projectPath = this.projectPath;
         const git = (0, simple_git_1.simpleGit)(projectPath, GIT_OPTS);
@@ -166,9 +89,6 @@ class WorktreeManager {
         else {
             log.info(`Git repo at ${projectPath} has no HEAD — creating one for Rivet`);
         }
-        // Stage anything already present so a non-empty start point (e.g. an
-        // HTML preview) lands in the initial commit. Empty dir → nothing staged,
-        // and `--allow-empty` still produces the HEAD commit we need.
         await git.add(['-A']).catch(() => { });
         await git.raw([
             '-c',
@@ -182,18 +102,7 @@ class WorktreeManager {
             'rivet: initial',
         ]);
     }
-    /**
-     * Return the path to the project within a worktree.
-     * When projectPath == gitRoot this is just worktreePath.
-     * When projectPath is a subdirectory (e.g. rivet-core/examples/microsoft-paint),
-     * this returns worktreePath/examples/microsoft-paint so the dev server starts
-     * from the right directory.
-     */
     async getProjectCwdInWorktree(worktreePath) {
-        // Canonicalize both sides so a symlinked projectPath (e.g. /tmp on macOS,
-        // which is a symlink to /private/tmp) matches the git-resolved gitRoot.
-        // Without this, path.relative produces an escaping `../../..` path that
-        // resolves back to the ORIGINAL project dir instead of inside the worktree.
         const gitRoot = await this.realPath(await this.getGitRoot());
         const projectPath = await this.realPath(this.projectPath);
         const relPath = path_1.default.relative(gitRoot, projectPath);
@@ -203,14 +112,7 @@ class WorktreeManager {
         }
         return relPath ? path_1.default.join(worktreePath, relPath) : worktreePath;
     }
-    /**
-     * Translate an absolute path that lives inside the main project tree to its
-     * equivalent path inside a worktree.  Paths outside the git root are returned
-     * unchanged so the method is safe to call on arbitrary strings.
-     */
     async translateToWorktreePath(absPath, worktreePath) {
-        // Canonicalize both sides (see getProjectCwdInWorktree) so a symlinked
-        // absPath doesn't compute an escaping rel against the git-resolved root.
         const gitRoot = await this.realPath(await this.getGitRoot());
         const realAbsPath = await this.realPath(absPath);
         const rel = path_1.default.relative(gitRoot, realAbsPath);
@@ -218,55 +120,52 @@ class WorktreeManager {
             return absPath;
         return path_1.default.join(worktreePath, rel);
     }
-    /** Get diff of all uncommitted changes (staged + unstaged) vs HEAD */
     async getUncommittedPatch() {
         const git = (0, simple_git_1.simpleGit)(this.projectPath, GIT_OPTS);
-        const diff = await git.diff(['HEAD']);
+        const diff = await git.diff(['--binary', '--full-index', 'HEAD']);
         return diff;
     }
-    /**
-     * Return untracked, non-ignored file paths relative to the git root.
-     * These are files present in the working tree but not yet in any commit,
-     * so `git diff HEAD` won't include them.
-     */
     async getUntrackedFiles() {
         const gitRoot = await this.getGitRoot();
         const git = (0, simple_git_1.simpleGit)(gitRoot, GIT_OPTS);
-        const result = await git
-            .raw(['ls-files', '--others', '--exclude-standard'])
-            .catch(() => '');
-        return result.split('\n').filter(Boolean);
+        const result = await git.raw([
+            'ls-files',
+            '--others',
+            '--exclude-standard',
+            '-z',
+        ]);
+        return result.split('\0').filter(Boolean);
     }
-    /** Copy untracked files from the source repo into a worktree */
     copyUntrackedFiles(untrackedFiles, gitRoot, worktreePath) {
         for (const relPath of untrackedFiles) {
             try {
                 const src = path_1.default.join(gitRoot, relPath);
                 const dest = path_1.default.join(worktreePath, relPath);
                 fs_1.default.mkdirSync(path_1.default.dirname(dest), { recursive: true });
-                // Clone-on-write where the filesystem supports it (free), plain copy
-                // elsewhere — untracked trees can hold large binary assets.
                 fs_1.default.copyFileSync(src, dest, fs_1.default.constants.COPYFILE_FICLONE);
             }
             catch (err) {
-                log.warn(`Could not copy untracked file ${relPath} to worktree:`, err);
+                if (err.code === 'ENOENT') {
+                    log.warn(`Skipped untracked file ${relPath} with no readable source`);
+                    continue;
+                }
+                throw new Error(`Could not copy untracked file ${relPath} to worktree: ${err instanceof Error ? err.message : String(err)}`);
             }
         }
     }
-    /**
-     * @effect Makes an existing dependency install available in a worktree when the destination is absent.
-     */
-    async provisionWorkspaceDependenciesIfAvailable(sourceRoot, destRoot) {
-        const nodeModulesSource = path_1.default.join(sourceRoot, 'node_modules');
-        const nodeModulesDest = path_1.default.join(destRoot, 'node_modules');
-        if (fs_1.default.existsSync(nodeModulesSource) && !fs_1.default.existsSync(nodeModulesDest)) {
-            await this.operatingSystemServices.workspaceDependencies.provision({
-                sourceDirectory: nodeModulesSource,
-                destinationDirectory: nodeModulesDest,
-            });
-        }
+    async commitDetachedBaseline(worktreeGit, message) {
+        const tree = (await worktreeGit.raw(['write-tree'])).trim();
+        const baseline = (await worktreeGit.raw([
+            ...internalGitIdentity_1.INTERNAL_GIT_IDENTITY_ARGS,
+            'commit-tree',
+            tree,
+            '-p',
+            'HEAD',
+            '-m',
+            message,
+        ])).trim();
+        await worktreeGit.raw(['update-ref', '--no-deref', 'HEAD', baseline]);
     }
-    /** Apply a patch string via stdin to the given cwd using git apply */
     applyPatchViaStdin(patch, cwd) {
         return new Promise((resolve, reject) => {
             const cp = (0, child_process_1.spawn)('git', ['apply', '--whitespace=nowarn', '-'], {
@@ -287,74 +186,50 @@ class WorktreeManager {
             cp.stdin.end();
         });
     }
-    /**
-     * Create N worktrees for a session, apply uncommitted patch to each, return paths.
-     *
-     * `instanceKeyPrefix` namespaces the worktree directory names so a second
-     * batch appended to the same session (sequential "Vary") does not collide
-     * with the first batch's `${INSTANCE_PREFIX}-${sessionId}-${i}` paths. It
-     * stays within the `${INSTANCE_PREFIX}-${sessionId}-` cleanup glob, so
-     * `cleanupSession` still removes appended worktrees.
-     */
     async createWorktrees(sessionId, count, instanceKeyPrefix = '') {
         this.assertSafeSessionId(sessionId);
         if (instanceKeyPrefix && !SESSION_ID_PATTERN.test(instanceKeyPrefix)) {
             throw new Error('Invalid instanceKeyPrefix: expected a safe path segment');
         }
-        // Blank / non-repo workspaces (empty folder or a bare HTML preview) have
-        // no git history for `git worktree add` to branch from — bootstrap one
-        // first so variants work outside an existing repo.
         await this.ensureGitRepo();
         const git = (0, simple_git_1.simpleGit)(this.projectPath, GIT_OPTS);
         const patch = await this.getUncommittedPatch();
         const gitRoot = await this.getGitRoot();
         const untrackedFiles = await this.getUntrackedFiles();
         const paths = [];
-        const projectCwdRelative = path_1.default.relative(gitRoot, path_1.default.resolve(this.projectPath));
         for (let i = 0; i < count; i++) {
             const worktreePath = path_1.default.join(EXISTING_WORKTREE_BASE, `${exports.INSTANCE_PREFIX}-${sessionId}-${instanceKeyPrefix}${i}`);
+            let isWorktreeCreated = false;
             try {
                 await git.raw(['worktree', 'add', '--detach', worktreePath, 'HEAD']);
-                // Provision dependency installs in both roots the dev tooling may
-                // resolve from: the repo root for shared config files and the project
-                // subdirectory for app-local imports.
-                const projectCwdInWorktree = projectCwdRelative
-                    ? path_1.default.join(worktreePath, projectCwdRelative)
-                    : worktreePath;
-                await this.provisionWorkspaceDependenciesIfAvailable(gitRoot, worktreePath);
-                if (projectCwdInWorktree !== worktreePath) {
-                    await this.provisionWorkspaceDependenciesIfAvailable(this.projectPath, projectCwdInWorktree);
-                }
-                // Apply uncommitted changes so agent sees current state, then commit
-                // them as a "baseline" so getDiff returns only the agent's delta.
-                // Without this, getDiff (git diff HEAD) would include the user's
-                // pre-existing changes, and reverting the combined diff would wipe them.
+                isWorktreeCreated = true;
                 if (patch.trim()) {
-                    await this.applyPatchViaStdin(patch, worktreePath).catch(() => {
-                        log.warn(`Could not apply uncommitted patch to worktree ${i} — working from HEAD`);
-                    });
+                    await this.applyPatchViaStdin(patch, worktreePath);
                 }
-                // Copy untracked files — git diff HEAD only covers tracked files, so
-                // untracked-but-not-ignored files (e.g. new components not yet committed)
-                // must be copied manually or the worktree's dev server will fail to
-                // resolve their imports.
                 if (untrackedFiles.length > 0) {
                     this.copyUntrackedFiles(untrackedFiles, gitRoot, worktreePath);
                 }
                 const wtGit = (0, simple_git_1.simpleGit)(worktreePath, GIT_OPTS);
-                await wtGit.raw(['add', '-A']).catch(() => { });
-                await wtGit
-                    .raw([
-                    'commit',
-                    '--allow-empty',
-                    '--no-gpg-sign',
-                    '-m',
-                    'rivet: variant baseline',
-                ])
-                    .catch(() => { });
+                await wtGit.raw(['add', '-A']);
+                await this.commitDetachedBaseline(wtGit, 'rivet: variant baseline');
                 paths.push(worktreePath);
             }
             catch (e) {
+                const incompletePaths = isWorktreeCreated
+                    ? [...paths, worktreePath]
+                    : paths;
+                for (const incompletePath of incompletePaths) {
+                    try {
+                        await git.raw(['worktree', 'remove', '--force', incompletePath]);
+                    }
+                    catch (cleanupError) {
+                        log.warn('Could not unregister an incomplete variant worktree', cleanupError);
+                        await fs_1.default.promises.rm(incompletePath, {
+                            recursive: true,
+                            force: true,
+                        });
+                    }
+                }
                 log.error(`Failed to create worktree ${i}:`, e);
                 const msg = e instanceof Error ? e.message : String(e);
                 if (/block timeout reached/i.test(msg)) {
@@ -368,11 +243,6 @@ class WorktreeManager {
         }
         return paths;
     }
-    /**
-     * Copy a variant worktree into N new sibling worktrees. Each destination
-     * inherits the source tree (including the baseline commit and agent delta)
-     * so a code_gen "Vary" starts from the parent variant rather than git HEAD.
-     */
     async forkWorktreesFrom(sourceWorktreePath, sessionId, count, instanceKeyPrefix = '') {
         this.assertSafeSessionId(sessionId);
         if (instanceKeyPrefix && !SESSION_ID_PATTERN.test(instanceKeyPrefix)) {
@@ -386,38 +256,22 @@ class WorktreeManager {
         for (let i = 0; i < count; i++) {
             const worktreePath = path_1.default.join(EXISTING_WORKTREE_BASE, `${exports.INSTANCE_PREFIX}-${sessionId}-${instanceKeyPrefix}${i}`);
             fs_1.default.mkdirSync(path_1.default.dirname(worktreePath), { recursive: true });
-            // Copy-on-write clone where supported: forking a large parent tree
-            // completes in milliseconds instead of scaling with repo size.
-            (0, cloneOrCopyDirSync_1.cloneOrCopyDirSync)(resolvedSource, worktreePath);
+            await fs_1.default.promises.cp(resolvedSource, worktreePath, {
+                recursive: true,
+                verbatimSymlinks: true,
+                mode: fs_1.default.constants.COPYFILE_FICLONE,
+                filter: (source) => !(0, ProjectPackageManager_1.isInstallOutputPath)(path_1.default.relative(resolvedSource, source)),
+            });
             paths.push(worktreePath);
         }
         return paths;
     }
-    /** Get git diff of all changes made in a worktree vs HEAD.
-     *
-     * `git diff HEAD` only covers tracked files. New files created by the agent
-     * are untracked and would be silently omitted, breaking imports/styles when
-     * the diff is applied to the main tree. `git add --intent-to-add .` marks
-     * every untracked file in the index as a zero-length blob so `git diff HEAD`
-     * includes them as pure additions without actually staging their content.
-     */
     async getDiff(worktreePath) {
         const git = (0, simple_git_1.simpleGit)(worktreePath);
-        // Stage new files with intent-to-add so they appear in the diff
         await git.raw(['add', '--intent-to-add', '.']).catch(() => {
-            // Non-fatal — if this fails, fall back to tracked-only diff
         });
-        return git.diff(['HEAD']);
-    }
-    /**
-     * Apply or revert a diff to the main project working tree.
-     *
-     * Because getDiff now diffs against the worktree baseline commit (HEAD +
-     * user's uncommitted changes), the codeDiff contains only the agent's delta.
-     * This means git apply --reverse reliably restores to the baseline state
-     * (user's uncommitted changes intact) without touching git checkout HEAD,
-     * which would wipe the user's pre-existing work.
-     */
+        return git.diff(['--binary', '--full-index', 'HEAD']);
+    }
     async applyDiff(diff, reverse) {
         if (!diff.trim())
             return;
@@ -444,9 +298,6 @@ class WorktreeManager {
             cp.stdin.end();
         });
     }
-    /**
-     * Apply a unified diff to the repository that contains the target project path.
-     */
     async applyDiffToProject(diff, projectPath) {
         if (!diff.trim())
             return;
@@ -454,7 +305,6 @@ class WorktreeManager {
         const gitRoot = (await git.revparse(['--show-toplevel'])).trim();
         return this.applyPatchViaStdin(diff, gitRoot);
     }
-    /** Bind port 0 to get an OS-assigned free port */
     getFreePort() {
         return new Promise((resolve, reject) => {
             const server = net_1.default.createServer();
@@ -466,24 +316,6 @@ class WorktreeManager {
             server.on('error', reject);
         });
     }
-    /**
-     * Find a free port by scanning upward from `startPort` (the framework's
-     * default, e.g. 3000 for Next, 5173 for Vite). Returns the first port that is
-     * both bindable and not already reserved by a concurrent variant start, so a
-     * preview comes up on a sensible, predictable port near the project's normal
-     * one — and naturally steps past a port the user's own dev server already
-     * holds — instead of a random high port. Falls back to an OS-assigned port if
-     * the scan window is exhausted.
-     *
-     * Port availability is delegated to {@link findAvailablePort}, which (unlike a
-     * plain bind check) also rejects a port with an active listener on 127.0.0.1
-     * or ::1 — the ports that actually carry `localhost` preview traffic.
-     *
-     * The returned port is reserved synchronously; the caller MUST `releasePort`
-     * it once the dev server has bound it or failed to start (the orchestrator
-     * does this in a `finally`). Reserving here is what stops two concurrent
-     * starts — neither of which has bound its port yet — from both picking it.
-     */
     async findFreePortFrom(startPort, scanWindow = 64) {
         const base = Number.isInteger(startPort) && startPort > 0 && startPort <= 65535
             ? startPort
@@ -496,33 +328,23 @@ class WorktreeManager {
                 candidate = await (0, portUtils_1.findAvailablePort)(from);
             }
             catch {
-                break; // no bindable port between `from` and 65535
+                break;
             }
             if (candidate > limit)
-                break; // first free port is outside the scan window
-            // Check-and-claim with no `await` in between, so two concurrent callers
-            // can't both observe the same port as unreserved before claiming it.
+                break;
             if (!this.reservedPorts.has(candidate)) {
                 this.reservedPorts.add(candidate);
                 return candidate;
             }
-            from = candidate + 1; // reserved by a sibling start — step past it
+            from = candidate + 1;
         }
-        // Scan window exhausted (or every free port in it is reserved by a sibling
-        // that hasn't bound yet) — fall back to an OS-assigned ephemeral port.
         const fallback = await this.getFreePort();
         this.reservedPorts.add(fallback);
         return fallback;
     }
-    /**
-     * Release a port previously handed out by {@link findFreePortFrom}. Call once
-     * the dev server has bound it (the listener check now sees it taken, so the
-     * reservation is redundant) or has failed to start (the port is free again).
-     */
     releasePort(port) {
         this.reservedPorts.delete(port);
     }
-    /** Validate a diff via `git apply --check` without modifying files */
     validateDiff(diff, reverse) {
         if (!diff.trim())
             return Promise.resolve();
@@ -549,23 +371,13 @@ class WorktreeManager {
             cp.stdin.end();
         });
     }
-    /**
-     * Spawn a dev server and poll until it responds with a non-502 HTTP status
-     * (max 30s). Throws on timeout.
-     */
     async startDevServer(worktreePath, port, cmd, args, env) {
         const proc = this.operatingSystemServices.projectProcesses.start({ executable: cmd, args }, {
             cwd: worktreePath,
-            env: { ...process.env, ...env },
+            env: { ...process.env, NODE_ENV: 'development', ...env },
             stdio: 'pipe',
             detached: false,
         });
-        // Capture a rolling tail of the child's output so a failed start is
-        // diagnosable (EADDRINUSE, missing dev script, build crash) instead of a
-        // blind timeout. Draining the pipes is also required: with `stdio: 'pipe'`
-        // and no consumer, the OS pipe buffer (~64KB) fills within seconds of
-        // Vite's HMR/request logging and the child blocks on write, freezing the
-        // dev server even though it passed the readiness probe.
         let outputTail = '';
         let lastOutputAt = Date.now();
         const drain = (data) => {
@@ -575,10 +387,6 @@ class WorktreeManager {
         };
         proc.stdout?.on('data', drain);
         proc.stderr?.on('data', drain);
-        // Track early termination so the probe can fail fast: a dev server that
-        // exits (or never spawns) before answering on `port` is never coming up —
-        // commonly because the project's dev script ignored the injected port and
-        // tried to bind its own default, which was already taken (EADDRINUSE).
         const term = {};
         const onExit = (code, signal) => {
             term.exited = { code, signal };
@@ -597,8 +405,14 @@ class WorktreeManager {
             detach();
             const portInUse = (0, devServerError_1.isPortInUseOutput)(outputTail);
             const detail = outputTail.trim();
+            const failureReason = reason !== 'spawn_error' && (0, devServerError_1.isCompilationFailureOutput)(detail)
+                ? 'compile_error'
+                : reason;
             let message;
-            if (reason === 'spawn_error') {
+            if (failureReason === 'compile_error') {
+                message = `Dev server could not compile the preview on port ${port}`;
+            }
+            else if (reason === 'spawn_error') {
                 message = `Dev server failed to spawn on port ${port}: ${term.spawnError?.message ?? 'unknown error'}`;
             }
             else if (reason === 'exited') {
@@ -609,7 +423,7 @@ class WorktreeManager {
             }
             throw new devServerError_1.DevServerStartError({
                 message: detail ? `${message}\n${detail}` : message,
-                reason,
+                reason: failureReason,
                 portInUse,
                 detail,
                 exitCode: term.exited?.code ?? null,
@@ -626,14 +440,20 @@ class WorktreeManager {
             const isReady = await (0, portUtils_1.probeLoopbackHttp)(port, {
                 timeoutMs: DEV_SERVER_PROBE_TIMEOUT_MS,
             });
+            if (term.spawnError)
+                fail('spawn_error');
+            if (term.exited)
+                fail('exited');
             if (isReady) {
                 detach();
                 return proc;
             }
+            if ((0, devServerError_1.isCompilationFailureOutput)(outputTail)) {
+                await this.stopDevServer(proc);
+                fail('compile_error');
+            }
             await new Promise((r) => setTimeout(r, 500));
         }
-        // Deadline hit. If the child died during the final wait, report that
-        // (actionable) rather than a generic timeout.
         if (term.spawnError)
             fail('spawn_error');
         if (term.exited)
@@ -644,13 +464,9 @@ class WorktreeManager {
             });
         }
         catch {
-            /* ignore */
         }
         return fail('timeout');
     }
-    /**
-     * @effect Stops a project dev server through the selected operating-system service.
-     */
     async stopDevServer(proc, timeoutMs = 5_000) {
         if (proc.killed || proc.exitCode !== null || proc.pid == null)
             return;
@@ -669,7 +485,6 @@ class WorktreeManager {
             });
         }
         catch {
-            /* ignore */
         }
         let timeout;
         const timedOut = await Promise.race([
@@ -689,34 +504,17 @@ class WorktreeManager {
             });
         }
         catch {
-            /* ignore */
         }
         await exited;
     }
-    /** Remove all worktrees for a session.
-     *
-     *  For existing-project sessions, asks git to unregister the worktree
-     *  (handles `.git/worktrees/*` cleanup) and falls back to plain rm. For
-     *  fresh-project sessions (no projectPath) the worktrees are detached
-     *  directories with their own `.git` under `<destinationParent>/.rivet-variants/`
-     *  — git registry cleanup is a no-op and we just rm the matching dirs.
-     *
-     *  `freshDestinationParent` is required when the session was fresh; pass
-     *  `path.dirname(projectContext.workspacePath)` so we know which
-     *  `.rivet-variants/` root to sweep.
-     */
     async cleanupSession(sessionId, freshDestinationParent) {
         this.assertSafeSessionId(sessionId);
         if (!this.resolveProjectPath()) {
-            // Fresh sessions: no source repo, no git registry to clean. Just rm.
             if (freshDestinationParent) {
                 this.cleanupFreshWorktrees(sessionId, freshDestinationParent);
             }
             return;
         }
-        // GIT_OPTS so cleanup can't re-hang: this path runs from teardown after a
-        // provision timeout/stall, and an unbounded `git worktree list`/`remove`
-        // would leave the tool hanging on cleanup instead of returning the error.
         const git = (0, simple_git_1.simpleGit)(this.projectPath, GIT_OPTS);
         const pattern = path_1.default.join(EXISTING_WORKTREE_BASE, `${exports.INSTANCE_PREFIX}-${sessionId}-`);
         try {
@@ -731,7 +529,6 @@ class WorktreeManager {
                     await git.raw(['worktree', 'remove', '--force', wPath]);
                 }
                 catch {
-                    // Force remove directory if git command fails
                     fs_1.default.rmSync(wPath, { recursive: true, force: true });
                 }
             }
@@ -739,31 +536,10 @@ class WorktreeManager {
         catch (e) {
             log.warn('Worktree cleanup error:', e);
         }
-        // Always also remove any leftover fresh-style directories for this
-        // session (e.g. mixed-mode sessions, or git registry mismatch).
         if (freshDestinationParent) {
             this.cleanupFreshWorktrees(sessionId, freshDestinationParent);
         }
     }
-    /**
-     * Create N worktrees for a fresh-project session by writing a template
-     * bundle into each `<destinationParent>/.rivet-variants/rivet-variants-pid<PID>-<sessionId>-<i>`
-     * directory, optionally writing a DESIGN.md per slot, and committing a
-     * baseline.
-     *
-     * Worktrees live under the user's destinationParent (not /tmp) so commit
-     * time can be a same-volume rename instead of a cross-volume copy. The
-     * destinationParent is registered to a small JSON file so a future MCP
-     * startup can sweep orphans even when the original process crashed.
-     *
-     * Does NOT run `npm install` — the orchestrator dispatches that as a
-     * background task so failures surface via work-item state without blocking
-     * the MCP tool response.
-     *
-     * @effect Creates directories under destinationParent, writes template
-     *         files, runs git init/add/commit, appends destinationParent to
-     *         the fresh-worktree-roots registry.
-     */
     async createFreshWorktrees(sessionId, count, template, designContext, destinationParent) {
         this.assertSafeSessionId(sessionId);
         if (!destinationParent || !path_1.default.isAbsolute(destinationParent)) {
@@ -798,19 +574,12 @@ class WorktreeManager {
                 });
             }
             catch (err) {
-                // Best-effort: even without a baseline commit the worktree is usable
-                // for the agent — log and continue.
                 log.warn(`Fresh worktree ${i}: git init failed`, err);
             }
             paths.push(worktreePath);
         }
         return paths;
     }
-    /**
-     * Write the per-slot DESIGN.md for a fresh worktree.
-     *
-     * @effect Writes DESIGN.md when a design context is available.
-     */
     writeDesignContext(worktreePath, slot, entry) {
         if (!entry)
             return;
@@ -826,50 +595,12 @@ class WorktreeManager {
         }
         log.warn(`Fresh worktree ${slot}: unknown design system slug '${entry.slug}' — DESIGN.md skipped`);
     }
-    /**
-     * Move a worktree to its history location preserving contents. Used by the
-     * orchestrator at commit time so unchosen variants survive on disk as
-     * runnable references (siblings of the chosen project).
-     *
-     * Returns the destination path (`<historyDir>/<folderName>`).
-     *
-     * @effect renames `srcWorktreePath` → `<historyDir>/<folderName>`, creating
-     *         the historyDir if needed.
-     */
     moveWorktreeToHistory(srcWorktreePath, historyDir, folderName) {
         fs_1.default.mkdirSync(historyDir, { recursive: true });
         const dest = path_1.default.join(historyDir, folderName);
         fs_1.default.renameSync(srcWorktreePath, dest);
         return dest;
     }
-    /**
-     * Repoint a worktree's `node_modules` at a relative symlink so it tracks
-     * the chosen variant's real install after both have moved into their new
-     * permanent homes. Idempotent — removes any existing entry first.
-     */
-    repointNodeModulesSymlink(worktreePath, sharedNodeModulesAbsPath) {
-        const link = path_1.default.join(worktreePath, '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), sharedNodeModulesAbsPath);
-        fs_1.default.symlinkSync(target, link, 'dir');
-    }
-    /** Remove all fresh worktrees for a session.
-     *
-     *  @effect Removes directories under <destinationParent>/.rivet-variants/
-     *          matching ${INSTANCE_PREFIX}-<sessionId>-*. Also removes the
-     *          .rivet-variants/ parent if it becomes empty so the editor file
-     *          tree doesn't accumulate noise.
-     *
-     *  When `preserve` is provided, entries whose basenames are in the set are
-     *  skipped — used by the orchestrator after a vite_app commit, where the
-     *  unchosen variant worktrees have already been moved to a sibling history
-     *  dir and must not be re-deleted.
-     */
     cleanupFreshWorktrees(sessionId, destinationParent, preserve) {
         this.assertSafeSessionId(sessionId);
         if (!destinationParent || !path_1.default.isAbsolute(destinationParent)) {
@@ -889,7 +620,6 @@ class WorktreeManager {
                     force: true,
                 });
             }
-            // If the freshRoot is now empty, remove it too.
             try {
                 const remaining = fs_1.default.readdirSync(freshRoot);
                 if (remaining.length === 0) {
@@ -897,12 +627,9 @@ class WorktreeManager {
                 }
             }
             catch {
-                // Non-fatal — leaving the dir is harmless.
             }
         }
         catch (e) {
-            // ENOENT is expected when the dir was already cleaned up — only log
-            // when it's a different failure mode.
             if (e.code !== 'ENOENT') {
                 log.warn('Fresh worktree cleanup error:', e);
             }
@@ -915,10 +642,6 @@ class WorktreeManager {
     }
 }
 exports.WorktreeManager = WorktreeManager;
-/**
- * Read the fresh-worktree-root registry, dropping entries whose dir no
- * longer exists so the file stays small.
- */
 const loadFreshWorktreeRoots = () => {
     try {
         const raw = fs_1.default.readFileSync(FRESH_ROOTS_REGISTRY_PATH, 'utf8');
@@ -944,11 +667,6 @@ const saveFreshWorktreeRoots = (roots) => {
         log.warn('Could not persist fresh-worktree-roots registry:', err);
     }
 };
-/**
- * Append a freshRoot path to the registry (de-duped). Called by
- * createFreshWorktrees so future MCP startups can sweep orphans even if
- * the original process crashed before teardown ran.
- */
 const registerFreshWorktreeRoot = (freshRoot) => {
     const existing = loadFreshWorktreeRoots();
     if (existing.includes(freshRoot))
@@ -957,13 +675,6 @@ const registerFreshWorktreeRoot = (freshRoot) => {
     saveFreshWorktreeRoots(existing);
 };
 exports.registerFreshWorktreeRoot = registerFreshWorktreeRoot;
-/**
- * Sweep orphan worktrees from /tmp (existing-project flow) and from every
- * registered fresh-worktree root (fresh-project flow). Filters by
- * INSTANCE_PREFIX (includes PID) so each server instance only removes its
- * own worktrees and never touches those of sibling instances. Prunes
- * registry entries whose directory no longer exists so the file stays small.
- */
 const cleanupOrphanedWorktrees = () => {
     try {
         const entries = fs_1.default
@@ -977,7 +688,6 @@ const cleanupOrphanedWorktrees = () => {
         }
     }
     catch {
-        /* ignore */
     }
     const roots = loadFreshWorktreeRoots();
     const survivingRoots = [];
@@ -1004,19 +714,12 @@ const cleanupOrphanedWorktrees = () => {
     }
 };
 exports.cleanupOrphanedWorktrees = cleanupOrphanedWorktrees;
-// Clean up on natural exit (covers process.exit() calls from server shutdown)
 process.on('exit', exports.cleanupOrphanedWorktrees);
-/**
- * Prune stale worktree registry entries for a project (`.git/worktrees/<name>`
- * entries where the referenced directory no longer exists). Safe to call at
- * startup — only removes entries for directories that are already gone.
- */
 const pruneWorktrees = async (projectPath) => {
     try {
         await (0, simple_git_1.simpleGit)(projectPath, GIT_OPTS).raw(['worktree', 'prune']);
     }
     catch {
-        // Non-fatal — prune is best-effort housekeeping
     }
 };
 exports.pruneWorktrees = pruneWorktrees;