rivet-design 0.17.4 → 0.17.5

package/dist/routes/agentVariants.js

@@ -31,16 +31,6 @@ const htmlDocument_1 = require("../utils/htmlDocument");
 const log = (0, logger_1.createLogger)('AgentVariantsRouter');
 const DIRECTION_TITLE_MAX_WORDS = 5;
 const DIRECTION_SUBTITLE_MAX_WORDS = 10;
-/**
- * Public CDN hosts agent-generated previews are allowed to load code/assets
- * from. We don't control which CDN the agent emits: p5.js, three.js, and
- * friends get pulled from cdnjs / jsdelivr / esm.sh / skypack at least as often
- * as unpkg. An unpkg-only allowlist silently CSP-blocked those scripts, leaving
- * WebGL/canvas sketches blank — and because the violation fires inside the
- * cross-origin preview iframe, it never surfaced in our telemetry (parent saw
- * zero console errors). Keep this list as the de-facto set; add hosts as we
- * observe them rather than reaching for a wildcard.
- */
 const PREVIEW_CDN_HOSTS = [
     'https://unpkg.com',
     'https://cdn.jsdelivr.net',
@@ -48,40 +38,6 @@ const PREVIEW_CDN_HOSTS = [
     'https://esm.sh',
     'https://cdn.skypack.dev',
 ].join(' ');
-/**
- * CSP for agent-generated static previews. Shared by the live static-preview
- * route and the variant-history preview route so a variant renders identically
- * whether it's served fresh or replayed from a snapshot.
- *
- * Previews are served same-origin (the Rivet core server) and embedded in an
- * iframe that deliberately keeps `allow-same-origin` (the visual editor reaches
- * into the iframe DOM), so agent JS runs with the Rivet origin's privileges.
- * This policy is the main thing bounding that blast radius — note the absence
- * of `'unsafe-eval'` and of any wildcard host. `connect-src` is intentionally
- * NOT `*`: it stops agent JS from exfiltrating anything it can read to an
- * arbitrary server.
- *
- * THE RIGHT LONG-TERM FIX is to stop allowlisting CDNs entirely by serving
- * previews from an ISOLATED ORIGIN (separate port/origin, drop
- * `allow-same-origin`) and driving the visual editor over `postMessage`. The
- * embedded-mode preview bridge (`src/proxy-middleware/preview-bridge.ts`)
- * already implements exactly this handshake — migrating the default static
- * preview onto it is the work. Once the preview no longer shares Rivet's origin
- * or storage, this CSP can be loosened to `script-src https:` (or dropped)
- * without widening blast radius, and the per-CDN allowlist above goes away.
- * Until that migration lands, broadening PREVIEW_CDN_HOSTS is the stopgap.
- */
-/**
- * CSP for agent-generated static previews. Previews are served same-origin on
- * the isolated preview port, so `'self'` resolves to the preview document's own
- * origin and its sibling assets (CSS/JS/GLB/textures) load normally.
- *
- * `frame-ancestors` must also allow the editor origin: with the isolated
- * preview origin the editor lives on a different origin than the preview, so
- * `'self'` alone would block the editor from framing the variant preview
- * (`frame-ancestors 'self' → refused to connect`). See
- * docs/preview-target-addressing-design.md.
- */
 const buildStaticPreviewCsp = (parentFrameOrigin, libraryOrigin) => {
     const frameAncestors = ["'self'", parentFrameOrigin, libraryOrigin]
         .filter(Boolean)
@@ -253,9 +209,7 @@ const inlineVariantBody = v3_1.z.object({
         .passthrough())
         .min(1),
     sourceFiles: v3_1.z.array(v3_1.z.string()).optional(),
-    /** Vary on an existing variant: attaches to the active session. */
     target: inlineVariantTargetSchema.optional(),
-    /** Vary on an HTML-only static preview: forks it via the refine flow. */
     staticPreviewTarget: inlineStaticPreviewTargetSchema.optional(),
     telemetryContext: v3_1.z
         .object({
@@ -266,9 +220,6 @@ const inlineVariantBody = v3_1.z.object({
     traceId: v3_1.z.string().optional(),
     agentRunId: v3_1.z.string().optional(),
     initiator: inlineInitiatorSchema,
-    /** Explicit per-request worker runtime choice ("run my workers on opus
-     *  from this Codex session"). Flag-relayed by the host agent, never
-     *  inferred — see WorkerSelection in change-request-types. */
     workerSelection: v3_1.z
         .object({
         provider: v3_1.z.enum(['claude', 'codex', 'cursor']).optional(),
@@ -288,17 +239,12 @@ const hostVariantCompleteBody = v3_1.z.object({
     title: v3_1.z.string().min(1).max(120).optional(),
     description: v3_1.z.string().min(1).max(400).optional(),
 });
-// Shared by the active-session and history rename routes. Trim first so a
-// whitespace-only title is rejected, and cap the length so an over-long label
-// can't bloat the snapshot or the on-disk manifest.
 const renameLabelSchema = v3_1.z.preprocess((v) => (typeof v === 'string' ? v.trim() : v), v3_1.z.string().min(1).max(120));
 const renameBody = v3_1.z.object({
     label: renameLabelSchema,
     projectPath: v3_1.z.string().optional(),
 });
 const RENAME_VALIDATION_MESSAGE = 'Invalid rename — `label` must be a non-empty string of at most 120 characters.';
-// Run-folder rename — one call re-homes one session request batch, live and
-// history alike; the client never fans out per-variant.
 const renameRunBody = v3_1.z.object({
     sessionId: v3_1.z.string().min(1),
     requestId: v3_1.z.string().min(1).optional(),
@@ -306,10 +252,6 @@ const renameRunBody = v3_1.z.object({
     label: renameLabelSchema,
     projectPath: v3_1.z.string().optional(),
 });
-// The variants panel's UI arrangement (pinned items + user-arranged order),
-// persisted as one metadata_state row in the project's rivet.db. Keys are
-// panel-owned opaque strings (`row:…`/`group:…` pin keys, group keys, row
-// keys); the caps only bound a runaway payload, not the shape's semantics.
 const uiStateKeySchema = v3_1.z.string().min(1).max(500);
 const uiStateSchema = v3_1.z.object({
     pinned: v3_1.z.array(uiStateKeySchema).max(1000),
@@ -326,20 +268,6 @@ const uiStatePutBody = v3_1.z.object({
     uiState: uiStateSchema,
     projectPath: v3_1.z.string().optional(),
 });
-/**
- * Express routes that back the iframe variants chip.
- *
- * - GET  /api/variants/active             — current active session state for the chip
- * - GET  /api/variants/:sessionId         — explicit session lookup
- * - POST /api/variants/:sessionId/preview-port  — switch proxy to a variant's
- *   dev server (or null to restore the user's default dev server)
- * - GET  /api/variants/:sessionId/static/:variantId — serve static preview HTML
- * - GET  /api/variants/:sessionId/design-md/:artifactId — serve raw DESIGN.md
- * - GET  /api/variants/:sessionId/design-md/:artifactId/view — serve DesignMD page
- * - POST /api/variants/:sessionId/commit  — user picked this variant in the
- *   chip; orchestrator enqueues the diff onto pending changes
- * - POST /api/variants/:sessionId/cancel  — dismiss the variants session
- */
 const HISTORY_STATUSES = new Set([
     'completed',
     'committed',
@@ -364,16 +292,10 @@ const escapeHtml = (value) => value.replace(/[&<>"']/g, (char) => {
             return char;
     }
 });
-/**
- * Selects the best persisted human label to describe a public variant share.
- */
 const getVariantShareTitle = (manifest) => {
     const title = [manifest.label, manifest.brief, manifest.sessionPrompt].find((candidate) => candidate.trim().length > 0);
     return (0, PrototypeDeployService_1.normalizePrototypeShareTitle)(title) ?? VARIANT_SHARE_TITLE_FALLBACK;
 };
-/**
- * Selects the run prompt for a public canvas share, with a stable fallback.
- */
 const getCanvasShareTitle = (sessionPrompt) => {
     return ((0, PrototypeDeployService_1.normalizePrototypeShareTitle)(sessionPrompt) ?? CANVAS_SHARE_TITLE_FALLBACK);
 };
@@ -381,9 +303,6 @@ const CANVAS_IFRAME_SANDBOX = 'allow-scripts allow-forms allow-popups';
 const RIVET_SOCIAL_IMAGE_URL = 'https://rivet.design/images/rivet-social.png';
 const RIVET_DEFAULT_SHARE_DESCRIPTION = 'Built with Rivet — the visual editor for design';
 const UNSUPPORTED_PROTOTYPE_DEPLOY_MESSAGE = "This prototype can't be deployed — only buildable app directions or static previews are supported.";
-/**
- * Render a public canvas page that puts every deployed direction in one shareable view.
- */
 const buildCanvasShareHtml = (args) => {
     const prompt = args.sessionPrompt.trim();
     const variantCards = args.variants
@@ -539,7 +458,6 @@ ${variantCards}
 </body>
 </html>`;
 };
-/** Resolve a Rivet-generated subproject path to the workspace that owns variant history. */
 const generatedProjectWorkspaceRoot = (projectPath) => {
     const normalized = path_1.default.normalize(projectPath);
     const segments = normalized.split(path_1.default.sep);
@@ -550,14 +468,6 @@ const generatedProjectWorkspaceRoot = (projectPath) => {
     const rootPath = segments.slice(0, rivetIndex).join(path_1.default.sep);
     return path_1.default.resolve(rootPath || path_1.default.parse(normalized).root);
 };
-/**
- * Stamp the live {@link WatcherLiveness} onto a variants snapshot so the UI can
- * detect a stale host-agent watch loop off real queue/waiter state. Applied to
- * BOTH active and inactive snapshots — a change can strand with no variants
- * session active — while the variant FIFO depth (`pendingVariantRequests`) is
- * still only stamped on active snapshots, preserving prior behavior. Returns
- * the snapshot untouched when no liveness is available (no bridge).
- */
 const stampWatcherLiveness = (snapshot, liveness, pendingVariantRequestCount, activeLeases = []) => {
     if (!liveness || typeof snapshot !== 'object' || snapshot === null) {
         return snapshot;
@@ -579,19 +489,11 @@ const stampWatcherLiveness = (snapshot, liveness, pendingVariantRequestCount, ac
 exports.stampWatcherLiveness = stampWatcherLiveness;
 const createAgentVariantsRouter = (orchestrator, bridge, telemetry, variantHistoryOverride, deployServiceOverride, variantRunService, historyReplayOverride, previewBridge, inlineStartTrackerOverride) => {
     const router = (0, express_1.Router)();
-    // `agent_variants.*` events from this router (preview switches, active-project
-    // transitions) must carry the browser's PostHog $session_id to link to a
-    // session replay; the bridge holds it. Falls back to raw telemetry when no
-    // bridge is wired (e.g. demo mounts), where no browser session is available.
     const variantsTelemetry = telemetry && bridge
         ? (0, createAgentVariantsOrchestrator_1.withVariantsSessionReplayLinking)(telemetry, bridge)
         : telemetry;
     const variantHistory = variantHistoryOverride ?? new VariantHistoryService_1.VariantHistoryService();
     const deployService = deployServiceOverride ?? new PrototypeDeployService_1.PrototypeDeployService();
-    // Replay shares the orchestrator's WorktreeManager instance: the
-    // reserved-but-not-yet-bound port set is per-instance, so a separate
-    // manager could hand a live variant's pending port to a replay
-    // (EADDRINUSE for whichever binds second).
     const historyReplay = historyReplayOverride ??
         new HistoryReplayService_1.HistoryReplayService({
             history: variantHistory,
@@ -613,11 +515,6 @@ const createAgentVariantsRouter = (orchestrator, bridge, telemetry, variantHisto
         }
         next();
     });
-    /**
-     * Stamp the live watcher liveness onto a snapshot before it leaves the server.
-     * The `typeof` guards keep partial bridge mocks (and a missing bridge) from
-     * throwing — production always has the real bridge methods.
-     */
     const stampLiveness = (snapshot) => (0, exports.stampWatcherLiveness)(snapshot, bridge && typeof bridge.getWatcherLiveness === 'function'
         ? bridge.getWatcherLiveness()
         : null, bridge && typeof bridge.pendingVariantRequestCount === 'function'
@@ -631,7 +528,6 @@ const createAgentVariantsRouter = (orchestrator, bridge, telemetry, variantHisto
         }
         return bridge?.getProjectPath() ?? null;
     };
-    /** Resolve every project root that can own history for the requested route. */
     const resolveHistoryProjectPaths = (params) => {
         const seen = new Set();
         const candidates = [];
@@ -656,15 +552,10 @@ const createAgentVariantsRouter = (orchestrator, bridge, telemetry, variantHisto
                 }
             }
             catch {
-                // Persisted sessions may outlive in-memory orchestrator state.
             }
         }
         const upwardRoot = generatedProjectWorkspaceRoot(params.projectPath);
         addCandidate(upwardRoot);
-        // Rediscover fresh-session workdirs nested under a repo root. Without this,
-        // a stop/restart drops the in-memory session (and its `workspacePath`), so
-        // reopening the root — whose own `.rivet/variants` is empty — would surface
-        // none of the directions stored under `<root>/.rivet/<slug>/.rivet/variants`.
         for (const scanRoot of [params.projectPath, upwardRoot]) {
             if (!scanRoot)
                 continue;
@@ -701,15 +592,6 @@ const createAgentVariantsRouter = (orchestrator, bridge, telemetry, variantHisto
         }
         return { kind: 'existing', projectPath: args.projectPath };
     };
-    /**
-     * Resolve a variant reference whose session is no longer active from
-     * persisted history and adopt it — into the usable active session, or a
-     * fresh one — so targeted requests keep working after restarts and newer
-     * runs. This is the same adoption flow the editor uses when a past
-     * direction is edited; the CLI/agent path simply reuses it.
-     */
-    /** @effect Rejects a request that would displace or mutate an actively
-     *  generating session. Ready/terminal sessions rotate normally. */
     const rejectBlockedVariantSession = (res, snapshot) => {
         if (!(0, variantSessionStart_1.isVariantSessionStartBlocked)(snapshot))
             return false;
@@ -717,9 +599,6 @@ const createAgentVariantsRouter = (orchestrator, bridge, telemetry, variantHisto
         const sessionId = snapshot.active === true ? snapshot.sessionId : undefined;
         res.status(400).json({
             error: 'Variants session already active',
-            // Name the blocker so callers are not flying blind, and never
-            // recommend cancel as remediation: cancelling to unblock destroys
-            // the user's in-progress work. Only a human should decide that.
             details: `A variants session is active${sessionId
                 ? ` (session ${sessionId}${stage ? `, stage ${stage}` : ''})`
                 : ''}. Wait for it to settle (poll status), target it with --target to refine it, or ask the user before cancelling anything.`,
@@ -763,8 +642,6 @@ const createAgentVariantsRouter = (orchestrator, bridge, telemetry, variantHisto
                     'its artifact instead.',
             };
         }
-        // The history lookup is async — a run may have started meanwhile. Never
-        // adopt into (or displace) a session that is actively generating.
         const raceSnapshot = orchestrator.buildActiveSnapshot();
         if ((0, variantSessionStart_1.isVariantSessionStartBlocked)(raceSnapshot)) {
             return { ok: false, kind: 'blocked', snapshot: raceSnapshot };
@@ -800,9 +677,6 @@ const createAgentVariantsRouter = (orchestrator, bridge, telemetry, variantHisto
         });
         return true;
     };
-    /**
-     * Resolve the saved app directory a deploy build should run from.
-     */
     const resolveDeployableAppDir = async (args) => {
         const manifest = args.variant.manifest;
         if (manifest.projectKind === 'fresh' &&
@@ -825,9 +699,6 @@ const createAgentVariantsRouter = (orchestrator, bridge, telemetry, variantHisto
         }
         return appDir;
     };
-    /**
-     * Deploy one persisted variant and append the returned public URL to history.
-     */
     const deployPersistedVariant = async (args) => {
         const existingDeployments = args.variant.manifest.deployments ?? [];
         const latestDeployment = existingDeployments.length > 0
@@ -849,8 +720,6 @@ const createAgentVariantsRouter = (orchestrator, bridge, telemetry, variantHisto
         const title = getVariantShareTitle(args.variant.manifest);
         let result;
         if (preview.kind === 'static') {
-            // Already a built static bundle (e.g. a history static-preview variant)
-            // — upload files/ directly, no build needed.
             result = await deployService.deployStatic(filesDir, {
                 title,
                 entryPath: preview.entryPath,
@@ -910,13 +779,6 @@ const createAgentVariantsRouter = (orchestrator, bridge, telemetry, variantHisto
             });
             return;
         }
-        // Resolve a variant target that points at an HTML-only static preview:
-        // those requests fork through the refine flow rather than code-gen (a
-        // static preview has no worktree to edit). Gate on the TRUE work-item kind
-        // — never on HTML presence or the client's claim: an existing-project
-        // `code_gen` variant materialized as a static preview serves HTML and
-        // displays as `static_artifact`, but owns a worktree and MUST fork via the
-        // code_gen path (the static fork would reject it with VARIANT_NOT_EDITABLE).
         const batchTarget = parsed.data.target;
         const claimedStaticTarget = parsed.data.staticPreviewTarget ??
             (batchTarget
@@ -955,20 +817,10 @@ const createAgentVariantsRouter = (orchestrator, bridge, telemetry, variantHisto
             return;
         }
         const activeVariantsSession = orchestrator.buildActiveSnapshot();
-        // A targeted request against the CURRENTLY active session attaches to it
-        // directly. A reference to any other session — the originating session
-        // ended, the server restarted, or a newer run replaced it — resolves
-        // through persisted history: adopt the snapshot (into the usable active
-        // session, or a fresh one) and retarget the request at the adopted live
-        // variant. Copied variant references stay actionable for their whole
-        // lifetime, not just while their session is in memory.
         let effectiveTarget = batchTarget ?? staticPreviewTarget;
         const isPersistedTargetRequest = Boolean(effectiveTarget &&
             (activeVariantsSession.active !== true ||
                 effectiveTarget.sessionId !== activeVariantsSession.sessionId));
-        // Adoption creates or mutates a session, so persisted-target requests
-        // follow the same intake rules as untargeted starts: never displace an
-        // actively generating session, and never race an in-flight start.
         if ((isPersistedTargetRequest || !effectiveTarget) &&
             rejectBlockedVariantSession(res, activeVariantsSession)) {
             return;
@@ -1029,10 +881,6 @@ const createAgentVariantsRouter = (orchestrator, bridge, telemetry, variantHisto
                         variantId: adoption.workItemId,
                     }
                     : undefined;
-                // Rewrite EVERY pointer at the dead reference — the batch-level
-                // fields and the per-change `target`/`staticPreviewTarget` pair the
-                // editor sends (the refine flow prefers the per-change static target,
-                // so leaving it stale would aim the refine at the ended session).
                 const matchesStaleTarget = (candidate) => Boolean(candidate &&
                     candidate.sessionId === staleTarget.sessionId &&
                     candidate.variantId === staleTarget.variantId);
@@ -1062,16 +910,17 @@ const createAgentVariantsRouter = (orchestrator, bridge, telemetry, variantHisto
                 };
                 effectiveTarget = liveTarget;
             }
+            const refineStaticPreviewBatch = variantRunService.refineStaticPreviewBatch?.bind(variantRunService);
             const isStaticPreviewFork = Boolean(request.staticPreviewTarget);
-            if (isStaticPreviewFork && !variantRunService.refineStaticPreviewBatch) {
+            if (isStaticPreviewFork && !refineStaticPreviewBatch) {
                 res.status(503).json({
                     error: 'Static preview refinement unavailable',
                     reason: 'inline_variants_unavailable',
                 });
                 return;
             }
-            const result = isStaticPreviewFork
-                ? await variantRunService.refineStaticPreviewBatch(request)
+            const result = isStaticPreviewFork && refineStaticPreviewBatch
+                ? await refineStaticPreviewBatch(request)
                 : await variantRunService.startElementVariants(request);
             if (!result.success) {
                 res.status(500).json({
@@ -1147,16 +996,6 @@ const createAgentVariantsRouter = (orchestrator, bridge, telemetry, variantHisto
             starting: inlineStartTracker.isStarting(),
         }));
     });
-    /**
-     * Server-Sent Events stream for the iframe chip. Pushes a fresh
-     * ActiveSnapshot whenever the orchestrator's state changes (propose,
-     * approve, report-complete, dev-server-up, terminal, cancel, commit) so
-     * the chip never has to poll.
-     *
-     * Heartbeats every 30s as comments (`: heartbeat\n\n`) to keep
-     * intermediate proxies from killing the connection on idle. EventSource
-     * auto-reconnects on disconnect.
-     */
     router.get('/variants/events', (req, res) => {
         if (rejectNonLocalRequest(req, res))
             return;
@@ -1167,10 +1006,6 @@ const createAgentVariantsRouter = (orchestrator, bridge, telemetry, variantHisto
             'X-Accel-Buffering': 'no',
         });
         res.flushHeaders?.();
-        // Stamp each snapshot with the live variant-request FIFO depth + watcher
-        // liveness. Both live on the bridge (not the orchestrator), so
-        // buildActiveSnapshot() can't fill them in — we add them here at write time
-        // so the initial state and every subscribed update carry them.
         const writeSnapshot = (snapshot) => {
             try {
                 const activeSnapshot = snapshot && typeof snapshot === 'object'
@@ -1185,20 +1020,13 @@ const createAgentVariantsRouter = (orchestrator, bridge, telemetry, variantHisto
                 log.warn('SSE write failed (client likely disconnected)', err);
             }
         };
-        // Initial state so the chip can render immediately.
         writeSnapshot(orchestrator.buildActiveSnapshot());
         const unsubscribe = orchestrator.subscribeToEvents(writeSnapshot);
-        // Re-push on bridge queue/waiter changes too. A change the user sends with
-        // no host agent draining it never produces an orchestrator event, so
-        // without this the stale-watcher banner would never see the strand.
         const unsubscribeLiveness = bridge && typeof bridge.onWatcherLivenessChange === 'function'
             ? bridge.onWatcherLivenessChange(() => {
                 writeSnapshot(orchestrator.buildActiveSnapshot());
             })
             : undefined;
-        // A live SSE subscriber means a Rivet page is open; track it so the MCP
-        // server can skip re-opening a duplicate browser tab when the variants flow
-        // re-enters an already-active editor session.
         const releaseUiClient = orchestrator.registerUiClient();
         const heartbeat = setInterval(() => {
             try {
@@ -1206,7 +1034,6 @@ const createAgentVariantsRouter = (orchestrator, bridge, telemetry, variantHisto
                 res.write(': heartbeat\n\n');
             }
             catch {
-                // ignore — close handler will clean up
             }
         }, 30_000);
         req.on('close', () => {
@@ -1218,7 +1045,6 @@ const createAgentVariantsRouter = (orchestrator, bridge, telemetry, variantHisto
                 res.end();
             }
             catch {
-                // already ended
             }
         });
     });
@@ -1254,11 +1080,7 @@ const createAgentVariantsRouter = (orchestrator, bridge, telemetry, variantHisto
             return;
         }
         try {
-            const entries = (await Promise.all(resolveHistoryProjectPaths({ projectPath }).map((historyProjectPath) => 
-            // Reads the SQLite metadata index when it's usable and falls
-            // back to the manifest walk otherwise — same entries, faster
-            // list. Detail/preview routes stay manifest/file-backed.
-            variantHistory.listVariantsFromIndex({
+            const entries = (await Promise.all(resolveHistoryProjectPaths({ projectPath }).map((historyProjectPath) => variantHistory.listVariantsFromIndex({
                 projectPath: historyProjectPath,
                 status: statusParam,
             })))).flat();
@@ -1268,10 +1090,6 @@ const createAgentVariantsRouter = (orchestrator, bridge, telemetry, variantHisto
             }
             const uniqueEntries = Array.from(entriesById.values()).sort((a, b) => b.manifest.createdAt.localeCompare(a.manifest.createdAt));
             const limitedEntries = limit !== undefined ? uniqueEntries.slice(0, limit) : uniqueEntries;
-            // Removed and cancelled variants are retained on disk but never surfaced
-            // in the default history list. Keeps dismissed and cancelled directions
-            // hidden once the session is no longer active, matching the
-            // list_past_variants MCP tool.
             const visibleEntries = statusParam === 'removed'
                 ? limitedEntries
                 : limitedEntries.filter((entry) => entry.manifest.status !== 'removed' &&
@@ -1296,14 +1114,8 @@ const createAgentVariantsRouter = (orchestrator, bridge, telemetry, variantHisto
                     preview: entry.manifest.preview,
                     artifact: entry.manifest.artifact,
                     parentVariant: entry.manifest.parentVariant,
-                    // Tree-store fields (absent on legacy entries): `serve` tells the
-                    // panel how a tree-backed entry previews (static → history preview
-                    // route; dev-server → the replay run route), `hasTree` marks the
-                    // entry as snapshot-backed at all.
                     ...(entry.manifest.serve ? { serve: entry.manifest.serve } : {}),
                     hasTree: Boolean(entry.manifest.tree),
-                    // The runtime that built this direction (vendor/model/effort) —
-                    // absent on legacy entries and host-agent-executed variants.
                     ...(entry.manifest.runtime
                         ? { runtime: entry.manifest.runtime }
                         : {}),
@@ -1314,10 +1126,6 @@ const createAgentVariantsRouter = (orchestrator, bridge, telemetry, variantHisto
             sendError(res, err);
         }
     });
-    // The variants panel's UI arrangement (pins + custom order). Stored in the
-    // project's rivet.db metadata_state — per-project and shared across
-    // browsers, unlike the panel's other localStorage preferences. Not
-    // rebuildable: losing the database resets the arrangement.
     router.get('/variants/ui-state', async (req, res) => {
         if (rejectNonLocalRequest(req, res))
             return;
@@ -1337,7 +1145,6 @@ const createAgentVariantsRouter = (orchestrator, bridge, telemetry, variantHisto
                     stored = JSON.parse(raw);
                 }
                 catch {
-                    // A corrupt row reads as "nothing stored" — the next PUT heals it.
                 }
             }
             const parsed = uiStateSchema.safeParse(stored);
@@ -1377,13 +1184,8 @@ const createAgentVariantsRouter = (orchestrator, bridge, telemetry, variantHisto
             sendError(res, err);
         }
     });
-    // The entry route resolves the saved document's canonical URL. HTML files
-    // served below that URL receive the document policy and preview bridge.
     router.get('/variants/history/:sessionId/:variantId/preview', async (req, res) => serveHistoryPreview(req, res, variantHistory, resolveProjectPath, resolveHistoryProjectPaths, { isDocument: true }, previewBridge));
     router.get('/variants/history/:sessionId/:variantId/preview/{*assetPath}', async (req, res) => serveHistoryPreview(req, res, variantHistory, resolveProjectPath, resolveHistoryProjectPaths, { isDocument: false }, previewBridge));
-    // Stop history replay servers. Registered before the
-    // parameterized history routes purely for clarity — method+arity keep it
-    // unambiguous either way.
     router.post('/variants/history/replay/stop', async (req, res) => {
         if (rejectNonLocalRequest(req, res))
             return;
@@ -1397,12 +1199,6 @@ const createAgentVariantsRouter = (orchestrator, bridge, telemetry, variantHisto
         }
         res.json({ stopped: true });
     });
-    /**
-     * Boot a past dev-server variant from its tree-store ref: materialize the
-     * exact tree, overlay runtime (.env / node_modules), start the persisted
-     * serve recipe, and optionally retarget the main preview proxy at the new
-     * port. See docs/variant-history-tree-store-design.md.
-     */
     router.post('/variants/history/:sessionId/:variantId/run', async (req, res) => {
         if (rejectNonLocalRequest(req, res))
             return;
@@ -1603,13 +1399,6 @@ const createAgentVariantsRouter = (orchestrator, bridge, telemetry, variantHisto
             sendError(res, err);
         }
     });
-    /**
-     * Adopt a PAST (history) variant into the active session as a first-class
-     * succeeded variant, so the user's first edit on a selected past direction
-     * routes to a real session member. Resolves the persisted snapshot from
-     * history, then hands the rehydration `files/` dir to the orchestrator. The
-     * UI calls this on first comment/Vary against a selected past variant.
-     */
     router.post('/variants/adopt-past', async (req, res) => {
         if (rejectNonLocalRequest(req, res))
             return;
@@ -1755,43 +1544,21 @@ const createAgentVariantsRouter = (orchestrator, bridge, telemetry, variantHisto
                 });
                 return;
             }
-            // Only inject `<base href>` when the variant actually has sibling
-            // assets to serve. Otherwise the inlined HTML is self-contained and
-            // the base tag would only serve to mis-resolve any incidental
-            // relative URLs (e.g. `<a href="something">`) against the asset
-            // sub-path. The hasAssets check also avoids the trailing-slash
-            // fragment-link quirk for the common no-assets case.
             const hasAssets = orchestrator.hasStaticPreviewAssets(sessionId, variantId);
             if (hasAssets &&
                 !req.originalUrl.includes('?') &&
                 !req.originalUrl.endsWith('/')) {
-                // Document URL must end in `/` so the browser's `document.URL` and
-                // the `<base href>` agree. Otherwise fragment-only links
-                // (`<a href="#section">`) resolve to the base-href URL — different
-                // from the current URL — and the browser does a full navigation,
-                // hitting the asset route with an empty path → 404. Redirect to
-                // the canonical trailing-slash form before serving.
                 res.redirect(301, req.originalUrl + '/');
                 return;
             }
             const withBaseHref = hasAssets
-                ? injectBaseHref(html, 
-                // Trailing slash is required so `./avatar.glb` resolves to
-                // `.../static/<vid>/avatar.glb`, not `.../static/avatar.glb`.
-                `/api/variants/${encodeURIComponent(sessionId)}/static/${encodeURIComponent(variantId)}/`)
+                ? injectBaseHref(html, `/api/variants/${encodeURIComponent(sessionId)}/static/${encodeURIComponent(variantId)}/`)
                 : html;
-            // In embedded mode the visual editor drives this iframe over the preview
-            // bridge; without the injected listener, selecting/commenting on the
-            // variant times out (`Preview bridge timed out`) and the comment input
-            // never opens. Mirror the base static route (`routes/static.ts`).
             const finalHtml = previewBridge?.isEnabled
                 ? (0, preview_bridge_1.injectPreviewBridge)(withBaseHref, {
                     expectedParentOrigin: previewBridge.expectedParentOrigin,
                 })
                 : withBaseHref;
-            // Constrain the blast radius of agent-generated scripts. See
-            // buildStaticPreviewCsp for the policy and the isolated-origin migration
-            // that will eventually let us drop the per-CDN allowlist.
             res
                 .status(200)
                 .type('html')
@@ -1871,13 +1638,6 @@ const createAgentVariantsRouter = (orchestrator, bridge, telemetry, variantHisto
             sendError(res, err);
         }
     });
-    /**
-     * Serve sibling assets the variant's HTML references (e.g. `./avatar.glb`,
-     * `./hero.png`). The agent reports `output.assetBase` alongside the inline
-     * HTML; the orchestrator sandboxes it inside the fresh-session workspace
-     * and exposes a resolver. Path-traversal-rejected requests + missing files
-     * return 404. Loopback-only.
-     */
     router.get('/variants/:sessionId/static/:variantId/{*assetPath}', (req, res) => {
         if (rejectNonLocalRequest(req, res))
             return;
@@ -1895,10 +1655,6 @@ const createAgentVariantsRouter = (orchestrator, bridge, telemetry, variantHisto
                 });
                 return;
             }
-            // `dotfiles: 'allow'` because workspacePath is typically nested
-            // under a `.rivet/` directory (Rivet's per-project state dir) —
-            // sendFile's default 'ignore' setting 404s anything with a hidden
-            // segment, which would always trigger here.
             res.sendFile(abs, {
                 dotfiles: 'allow',
                 headers: { 'Cache-Control': 'no-store' },
@@ -1957,14 +1713,6 @@ const createAgentVariantsRouter = (orchestrator, bridge, telemetry, variantHisto
                 }
                 try {
                     bridge.rebindProjectPath(result.destinationPath);
-                    // Do NOT call switchPreviewPort(null) here on the fresh vite_app
-                    // path: commitVariant has already spawned a fresh dev server at
-                    // destinationPath and retargeted the proxy to its port via the
-                    // orchestrator's switchPreviewPort callback. Calling null here
-                    // would route the proxy to the default upstream (the user's repo,
-                    // which has no dev server) and the iframe would show "preview
-                    // disconnected" — exactly the regression we're fixing. The
-                    // committed dev server lives until the next propose / shutdown.
                     await orchestrator.cleanupCommittedSession(sessionId);
                     variantsTelemetry?.trackAgentVariantsActiveProjectTransition({
                         sessionId,
@@ -2002,18 +1750,10 @@ const createAgentVariantsRouter = (orchestrator, bridge, telemetry, variantHisto
             sendError(res, err);
         }
     });
-    /**
-     * Deploy a fresh-project (Vite) variant to the public Prototype Preview Host
-     * and return a shareable URL. Builds locally, uploads the static bundle with
-     * the user's Rivet JWT, and records the deployment in the variant manifest so
-     * the chip can re-show ("Copy link") without rebuilding.
-     */
     router.post('/variants/:sessionId/deploy', async (req, res) => {
         if (rejectNonLocalRequest(req, res))
             return;
         const sessionId = req.params.sessionId;
-        // Gated behind the `deployPrototype` flag (default off). Mirrors the UI
-        // gate so the endpoint can't be driven while the feature is dark.
         const flags = await (0, evaluateFlags_1.getFeatureFlags)({
             userKey: (0, featureFlagUserKey_1.getConfigFeatureFlagUserKey)({ headers: req.headers }),
         });
@@ -2082,11 +1822,6 @@ const createAgentVariantsRouter = (orchestrator, bridge, telemetry, variantHisto
             });
         }
     });
-    /**
-     * Deploy a fresh-project canvas to the public Prototype Preview Host. The
-     * canvas page embeds every requested direction so one public URL can be used
-     * for review instead of sharing one URL per variant.
-     */
     router.post('/variants/:sessionId/canvas/deploy', async (req, res) => {
         if (rejectNonLocalRequest(req, res))
             return;
@@ -2248,9 +1983,6 @@ const createAgentVariantsRouter = (orchestrator, bridge, telemetry, variantHisto
             sendError(res, err);
         }
     });
-    // Remove a single variant from the UI: hides it from the active snapshot for
-    // good while retaining it in `.rivet/variants/` as `removed`. Distinct from
-    // /cancel (which tears down the whole session).
     router.post('/variants/:sessionId/:variantId/remove', async (req, res) => {
         if (rejectNonLocalRequest(req, res))
             return;
@@ -2263,8 +1995,6 @@ const createAgentVariantsRouter = (orchestrator, bridge, telemetry, variantHisto
             sendError(res, err);
         }
     });
-    // Rename a live (active-session) variant. Patches the in-memory work item and
-    // its on-disk manifest, then re-pushes the snapshot over SSE.
     router.post('/variants/:sessionId/:variantId/rename', async (req, res) => {
         if (rejectNonLocalRequest(req, res))
             return;
@@ -2289,8 +2019,6 @@ const createAgentVariantsRouter = (orchestrator, bridge, telemetry, variantHisto
             sendError(res, err);
         }
     });
-    // Rename one run request batch across live state and every resolved history
-    // root in one call.
     router.post('/variants/runs/rename', async (req, res) => {
         if (rejectNonLocalRequest(req, res))
             return;
@@ -2314,8 +2042,6 @@ const createAgentVariantsRouter = (orchestrator, bridge, telemetry, variantHisto
                 });
                 liveRenamedCount = result.renamedCount;
             }
-            // History is best-effort even without a resolvable project path — a
-            // fresh-session run may have nothing persisted yet.
             const projectPath = resolveProjectPath(parsed.data.projectPath);
             let historyRenamedCount = 0;
             if (projectPath) {
@@ -2339,9 +2065,6 @@ const createAgentVariantsRouter = (orchestrator, bridge, telemetry, variantHisto
             sendError(res, err);
         }
     });
-    // Rename a past (history) variant — no active session involved, so this writes
-    // straight to the persisted manifest. Takes the workspace projectPath the same
-    // way the history list/preview routes do.
     router.post('/variants/history/:sessionId/:variantId/rename', async (req, res) => {
         if (rejectNonLocalRequest(req, res))
             return;
@@ -2387,10 +2110,6 @@ const createAgentVariantsRouter = (orchestrator, bridge, telemetry, variantHisto
             sendError(res, err);
         }
     });
-    // Remove a past (history) variant — flips its persisted manifest to `removed`
-    // so it drops out of the default history list. Non-destructive: the snapshot
-    // stays on disk, matching the active-session remove flow. Takes the workspace
-    // projectPath the same way the other history routes do.
     router.post('/variants/history/:sessionId/:variantId/remove', async (req, res) => {
         if (rejectNonLocalRequest(req, res))
             return;
@@ -2424,13 +2143,6 @@ const createAgentVariantsRouter = (orchestrator, bridge, telemetry, variantHisto
     return router;
 };
 exports.createAgentVariantsRouter = createAgentVariantsRouter;
-/**
- * Serve one saved static preview file from a variant history snapshot.
- *
- * The entry route redirects to the saved HTML filename so relative embeds,
- * assets and fragment links resolve naturally. HTML responses carry the
- * preview CSP and bridge; other sibling assets carry neither.
- */
 const serveHistoryPreview = async (req, res, variantHistory, resolveProjectPath, resolveHistoryProjectPaths, { isDocument }, previewBridge) => {
     if (rejectNonLocalRequest(req, res))
         return;
@@ -2488,17 +2200,11 @@ const serveHistoryPreview = async (req, res, variantHistory, resolveProjectPath,
             return;
         }
         if (isDocument) {
-            // Give the history entry its saved filename as the browser's document URL:
-            // /preview -> /preview/pages/index.html makes ./demo.html resolve under
-            // /preview/pages/. A <base> tag would also retarget fragment-only links
-            // such as #details, which must stay within the displayed document.
             const previewRoot = `/api/variants/history/${encodeURIComponent(sessionId)}/${encodeURIComponent(variantId)}/preview/`;
-            // Encode filenames (including spaces and #) without encoding directory separators.
             const entryPath = file.relativePath
                 .split('/')
                 .map(encodeURIComponent)
                 .join('/');
-            // Keep preview options and project lookup parameters through the redirect.
             const queryIndex = req.originalUrl.indexOf('?');
             const query = queryIndex === -1 ? '' : req.originalUrl.slice(queryIndex);
             res
@@ -2508,16 +2214,11 @@ const serveHistoryPreview = async (req, res, variantHistory, resolveProjectPath,
         }
         const contentType = path_1.default.extname(file.absolutePath) || 'html';
         res.status(200).type(contentType).set('Cache-Control', 'no-store');
-        // HTML siblings can be embedded documents too, so they need the same
-        // permissions as the entry. CSS, scripts and images retain their raw bytes.
         if (/\.html?$/i.test(file.relativePath)) {
             const html = file.body.toString('utf8');
             res
                 .set('Content-Security-Policy', buildStaticPreviewCsp(previewBridge?.expectedParentOrigin, previewBridge?.resolveLibraryOrigin?.()))
                 .set('X-Content-Type-Options', 'nosniff');
-            // Embedded mode drives this snapshot iframe over the preview bridge; the
-            // listener must be present or selecting/commenting on a past variant
-            // times out (`Preview bridge timed out`). Matches the live static route.
             if (previewBridge?.isEnabled) {
                 res.send((0, preview_bridge_1.injectPreviewBridge)(html, {
                     expectedParentOrigin: previewBridge.expectedParentOrigin,
@@ -2540,10 +2241,6 @@ const serveHistoryPreview = async (req, res, variantHistory, resolveProjectPath,
         sendError(res, err);
     }
 };
-/**
- * Validates the raw history-preview URL suffix before Express can normalize an
- * encoded traversal segment away from req.params.
- */
 const getInvalidRawHistoryPreviewAssetPath = (req) => {
     const rawPath = req.originalUrl.split('?')[0] ?? '';
     const marker = '/preview/';
@@ -2565,9 +2262,6 @@ const getInvalidRawHistoryPreviewAssetPath = (req) => {
     }
     return null;
 };
-/**
- * Resolve a child path while rejecting paths that escape the intended root.
- */
 const resolvePathWithinRoot = (rootPath, childPath) => {
     const absolutePath = path_1.default.resolve(rootPath, childPath);
     const relativePath = path_1.default.relative(rootPath, absolutePath);
@@ -2639,17 +2333,9 @@ const toActiveProjectContext = (projectContext) => {
             : {}),
     };
 };
-/** Map persisted artifact shape to the public history summary kind. */
 const manifestKind = (manifest) => {
     return manifest.artifact.kind === 'diff' ? 'diff' : 'project-created';
 };
-/**
- * Inject a `<base href>` tag into the variant HTML so relative URLs
- * resolve against the asset-serving sub-path. Idempotent: if the HTML
- * already declares a `<base>` tag we leave it alone (the agent opted in
- * to its own resolution rules). Documents without a head tag receive the base
- * after their html tag or doctype, outside any embedded markup.
- */
 const injectBaseHref = (html, baseHref) => (0, htmlDocument_1.insertHtmlHeadElements)(html, [
     {
         tagName: 'base',