rivet-design 0.17.4 → 0.18.0

package/dist/services/WorktreeManager.js

@@ -19,69 +19,23 @@ 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') {
@@ -99,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);
@@ -130,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);
@@ -167,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',
@@ -183,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);
@@ -204,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);
@@ -219,17 +120,11 @@ 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(['--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);
@@ -241,21 +136,15 @@ class WorktreeManager {
         ]);
         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) {
-                // The listing races live edits: a file with no readable source
-                // (deleted since `git ls-files`, or a dangling symlink) has nothing
-                // to copy. Any other failure aborts provisioning.
                 if (err.code === 'ENOENT') {
                     log.warn(`Skipped untracked file ${relPath} with no readable source`);
                     continue;
@@ -264,12 +153,6 @@ class WorktreeManager {
             }
         }
     }
-    /**
-     * @effect Commits the staged worktree state onto its detached HEAD with Git
-     * plumbing, so project commit hooks can neither block nor mutate the
-     * internal baseline. The commit lives only on this worktree's detached HEAD
-     * and disappears with it — the user's branches and config are untouched.
-     */
     async commitDetachedBaseline(worktreeGit, message) {
         const tree = (await worktreeGit.raw(['write-tree'])).trim();
         const baseline = (await worktreeGit.raw([
@@ -283,7 +166,6 @@ class WorktreeManager {
         ])).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', '-'], {
@@ -304,23 +186,11 @@ 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();
@@ -333,17 +203,9 @@ class WorktreeManager {
             try {
                 await git.raw(['worktree', 'add', '--detach', worktreePath, 'HEAD']);
                 isWorktreeCreated = true;
-                // 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.
                 if (patch.trim()) {
                     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);
                 }
@@ -353,8 +215,6 @@ class WorktreeManager {
                 paths.push(worktreePath);
             }
             catch (e) {
-                // Roll back only worktrees created by this batch; prior directions
-                // in the same session still belong to the user's exploration.
                 const incompletePaths = isWorktreeCreated
                     ? [...paths, worktreePath]
                     : paths;
@@ -383,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)) {
@@ -401,11 +256,9 @@ 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 });
-            // Each fork prepares its dependencies from its own manifests.
             await fs_1.default.promises.cp(resolvedSource, worktreePath, {
                 recursive: true,
                 verbatimSymlinks: true,
-                // Copy-on-write clone on Linux (btrfs/XFS); plain copy elsewhere.
                 mode: fs_1.default.constants.COPYFILE_FICLONE,
                 filter: (source) => !(0, ProjectPackageManager_1.isInstallOutputPath)(path_1.default.relative(resolvedSource, source)),
             });
@@ -413,31 +266,12 @@ class WorktreeManager {
         }
         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(['--binary', '--full-index', '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.
-     */
     async applyDiff(diff, reverse) {
         if (!diff.trim())
             return;
@@ -464,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;
@@ -474,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();
@@ -486,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
@@ -516,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();
@@ -569,26 +371,13 @@ class WorktreeManager {
             cp.stdin.end();
         });
     }
-    /**
-     * Spawn a dev server and poll until it responds without a server error.
-     * Compilation failures and process exits fail promptly; active startup output
-     * extends the readiness wait up to the hard deadline.
-     */
     async startDevServer(worktreePath, port, cmd, args, env) {
         const proc = this.operatingSystemServices.projectProcesses.start({ executable: cmd, args }, {
             cwd: worktreePath,
-            // Preview servers need development transforms even when the installed
-            // Rivet CLI runs in production. Explicit recipe settings take priority.
             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) => {
@@ -598,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 };
@@ -669,8 +454,6 @@ class WorktreeManager {
             }
             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)
@@ -681,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;
@@ -706,7 +485,6 @@ class WorktreeManager {
             });
         }
         catch {
-            /* ignore */
         }
         let timeout;
         const timedOut = await Promise.race([
@@ -726,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 {
@@ -768,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 });
                 }
             }
@@ -776,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)) {
@@ -835,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;
@@ -863,34 +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;
     }
-    /** 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)) {
@@ -910,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) {
@@ -918,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);
             }
@@ -936,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');
@@ -965,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))
@@ -978,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
@@ -998,7 +688,6 @@ const cleanupOrphanedWorktrees = () => {
         }
     }
     catch {
-        /* ignore */
     }
     const roots = loadFreshWorktreeRoots();
     const survivingRoots = [];
@@ -1025,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;