rivet-design 0.17.4 → 0.18.0

package/dist/agent-variants/WorktreeOrchestrator.d.ts

@@ -1,81 +1,33 @@
+import type { VariantReference } from '../types/variant-reference';
 import type { ChildProcess } from 'child_process';
 import { AgentVariantsError } from './errors';
 import { SessionStore, type ApprovedBriefSelection, type ApproveResult, type ProposeArgs, type ProposeResult, type ReportCompleteResult, type RequestWorkResult } from './SessionStore';
-import type { ActiveProjectContext, ActiveVariantSnapshot, Brief, DesignContextEntry, ProjectContext, Stage, StartVariantsBriefContent, StaticPreviewTargetElement, Target, TerminalSummary, VariantContextBinding, HostVariantWorkItemSnapshot, VariantQaResult, VariantSessionArtifact, WorkItemStatus } from './contracts';
+import type { ActiveProjectContext, ActiveVariantSnapshot, Brief, DesignContextEntry, ProjectContext, Stage, StartVariantsBriefContent, StaticPreviewTargetElement, Target, TerminalSummary, VariantContextBinding, VariantWorkItemContext, HostVariantWorkItemSnapshot, VariantQaResult, VariantSessionArtifact, WorkItemStatus } from './contracts';
 import { VariantHistoryService } from '../services/VariantHistoryService';
 import type { MCPVariantsTelemetryMetadata } from '../services/MCPVariantsTelemetry';
 import type { Framework } from '../services/ProjectDetectionService';
-/**
- * Subset of WorktreeManager that the orchestrator depends on. Defined as an
- * interface so unit tests can mock it without spinning up real git/processes.
- *
- * Each succeeded variant gets its own dev server so the user can cycle
- * between live, running variants in the iframe via a proxy retarget.
- */
 export interface WorktreeManagerLike {
-    /** `instanceKeyPrefix` namespaces appended batches so a sequential "Vary"
-     *  on the same session doesn't collide with the first batch's worktree
-     *  dirs (still inside the per-session cleanup glob). */
     createWorktrees(sessionId: string, count: number, instanceKeyPrefix?: string): Promise<string[]>;
-    /** Copy an existing variant worktree into N new sibling worktrees. Used when
-     *  a code_gen "Vary" targets a parent variant so forks inherit its diff. */
     forkWorktreesFrom?(sourceWorktreePath: string, sessionId: string, count: number, instanceKeyPrefix?: string): Promise<string[]>;
     getDiff(worktreePath: string): Promise<string>;
-    /** Absolute git root of the host project's repo. Used as the base-snapshot
-     *  root for tree-store history persistence (see the tree-root contract in
-     *  the design doc). Optional so lightweight test doubles needn't implement
-     *  it — persistence degrades to no base ref. */
     getGitRoot?(): Promise<string>;
-    /** Apply a unified diff to a project working tree (no commit). Used by
-     *  commitVariant to land the chosen variant on the user's branch
-     *  immediately rather than waiting for an agent to pick up pending-changes. */
     applyDiffToProject?(diff: string, projectPath: string): Promise<void>;
-    /** `freshDestinationParent` is required when the session was fresh — it
-     *  tells WorktreeManager which `<destinationParent>/.rivet-variants/` root
-     *  the worktrees live under (since fresh worktrees are no longer in /tmp). */
     cleanupSession(sessionId: string, freshDestinationParent?: string): Promise<void>;
     getFreePort(): Promise<number>;
-    /** Find a free port scanning upward from `startPort` (the framework default),
-     *  so previews come up on a sensible port near the project's normal one and
-     *  step past a port the user's own dev server already holds. */
     findFreePortFrom(startPort: number): Promise<number>;
-    /** Release a port handed out by `findFreePortFrom` once its dev server has
-     *  bound it or failed to start, so concurrent variant starts stop avoiding
-     *  it. Optional so lightweight test doubles needn't implement it. */
     releasePort?(port: number): void;
     startDevServer(worktreePath: string, port: number, cmd: string, args: string[], env: Record<string, string>): Promise<ChildProcess>;
     stopDevServer(proc: ChildProcess, timeoutMs?: number): Promise<void>;
     getProjectCwdInWorktree(worktreePath: string): Promise<string>;
-    /** Optional fresh-project scaffold support — present in production but
-     *  optional so unit tests can mock with the minimum surface they need.
-     *  `destinationParent` is the user-supplied workspace parent directory;
-     *  fresh worktrees are scaffolded under `<destinationParent>/.rivet-variants/`
-     *  so commit time can be a same-volume rename. */
     createFreshWorktrees?(sessionId: string, count: number, template: import('../services/templates/viteReactTs').TemplateBundle, designContext: ReadonlyArray<DesignContextEntry | undefined> | undefined, destinationParent: string): Promise<string[]>;
-    /** Move a fresh-worktree directory to its history location, preserving
-     *  contents. Optional on the interface so unit tests can stub partially. */
     moveWorktreeToHistory?(srcWorktreePath: string, historyDir: string, folderName: string): string;
 }
-/**
- * Per-session resolved environment. Used to populate destinationPath on the
- * variant envelope and (in fresh-project flows) the workspace target. Also
- * identifies either the selected static entry or the dev-server command.
- * Static projects cannot carry package-manager fields, so a missing entry can
- * never fall through to an invalid package-manager invocation.
- */
 type DevServerProjectEnvironment = {
     projectPath: string;
     framework: Exclude<Framework, 'static'>;
     packageManager: string;
     devCommand: string;
-    /** The framework's conventional dev-server port (e.g. 3000 for Next, 5173
-     *  for Vite). Used as the starting point when allocating a variant's preview
-     *  port so it lands somewhere sensible near the project's normal port. */
     defaultPort?: number;
-    /** Builds (cmd, args, env) for spawning a dev server in a worktree on a
-     *  specific port. Defaults to a generic { packageManager, [devCommand,
-     *  '--port', port] } shape if not provided, but production wires this to
-     *  buildDevServerCommand from utils/devServerCommand.ts. */
     buildDevCommand?: (port: number) => {
         cmd: string;
         args: string[];
@@ -88,23 +40,11 @@ type StaticProjectEnvironment = {
     entryPath: string;
 };
 export type ProjectEnvironment = DevServerProjectEnvironment | StaticProjectEnvironment;
-/**
- * Checks a static-preview artifact before the orchestrator marks it as
- * succeeded. The default implementation validates non-empty HTML without
- * starting a browser. Tests may inject a runner to exercise pass and
- * terminal-failure paths deterministically.
- */
 export type PreviewQaRunner = (args: {
     sessionId: string;
     workItemId: string;
     html: string;
 }) => Promise<VariantQaResult>;
-/**
- * An in-place refine target that could not be applied (the variant was already
- * sent / is no longer editable and there was no pending refinement to fold the
- * instruction into). Returned by {@link AgentVariantsOrchestrator.beginStaticPreviewRefinements}
- * so the caller surfaces it to the agent instead of dropping it silently.
- */
 export type DroppedRefinement = {
     variantId: string;
     reason: string;
@@ -114,70 +54,25 @@ export interface OrchestratorDeps {
     worktreeManager: WorktreeManagerLike;
     resolveProjectEnvironment: (sessionId: string) => Promise<ProjectEnvironment>;
     telemetry?: VariantsTelemetry;
-    /** Background dependency installer for worktrees. Defaults to the shared
-     *  preparation service, which detects the project's package manager itself;
-     *  tests inject a fast no-op or rejecting stub. */
     installDependencies?: (worktreePath: string, options?: {
         workspaceRoot: string;
         force?: boolean;
         signal?: AbortSignal;
     }) => Promise<void>;
-    /** Server-side materialize step for fresh-project commits. Copies the
-     *  source worktree to `destinationPath` excluding install artifacts and
-     *  initializes a fresh git repo. Defaults to a real fs.cp + simpleGit
-     *  implementation; tests inject a stub. */
     materializeProject?: (sourceWorktreePath: string, destinationPath: string) => Promise<void>;
-    /** Override the preview QA runner. See `PreviewQaRunner` for the contract. */
     previewQaRunner?: PreviewQaRunner;
-    /** Retarget the iframe proxy to a different dev-server port (or back to the
-     *  default upstream when `null`). Used by `commitVariant` on the fresh
-     *  vite_app rename path: after the chosen variant is renamed into
-     *  destinationPath, the orchestrator spawns a fresh dev server there and
-     *  retargets so the iframe stays live instead of flashing "preview
-     *  disconnected." Optional — tests can omit, and production wires it to
-     *  `SessionBridgeService.switchPreviewPort`. */
     switchPreviewPort?: (port: number | null) => void;
-    /** Advertise a Rivet-spawned committed dev/static server on the bridge's
-     *  `devServerHealth` so `/api/mcp/status` and the iframe's upstream-probe
-     *  see `ownership: 'rivet_owned'`. Distinct from `switchPreviewPort`
-     *  (which is also called during variant cycling and on cancel — those
-     *  must NOT mutate the user's external dev-server health). Only the
-     *  commit-handoff path calls this. Production wires it to
-     *  `SessionBridgeService.setCommittedDevServerHealth`. */
     setCommittedDevServerHealth?: (port: number | null) => void;
-    /** Local persistence for the variant-history feature. Writes every
-     *  completed code_gen variant (and committed/rejected fresh-project
-     *  variants) into `<projectPath>/.rivet/variants/` so the UI and
-     *  MCP `list_past_variants` tool can surface prior runs. Optional in the
-     *  constructor for tests; production wires a real instance. */
     variantHistory?: VariantHistoryService;
-    /** Spawn a static file server bound to a committed `static_preview`
-     *  project. Defaults to the real `startStaticPreviewServer` (spawns a Node
-     *  child process). Tests inject a fake that returns a stub `ChildProcess`
-     *  so they don't bind real ports. */
     startStaticPreviewServer?: (args: {
         rootPath: string;
         port: number;
         host?: string;
     }) => Promise<ChildProcess>;
-    /** Hard ceiling (ms) on worktree provisioning before the kickoff fails fast.
-     *  Defaults to `RIVET_VARIANTS_PROVISION_TIMEOUT_MS` / 540s. Tests inject a
-     *  tiny value to exercise the timeout path without real slow I/O. */
     provisionTimeoutMs?: number;
-    /** Idle TTL (ms) for active variant dev servers. Defaults to
-     *  `RIVET_ACTIVE_VARIANT_SERVER_IDLE_TTL_MS` / 30m. Tests inject a short
-     *  value so server reclamation is deterministic. */
     activeVariantServerIdleTtlMs?: number;
-    /** Grace (ms) before auto-restarting a ready dev server that crashed, so
-     *  the dying process's port and file locks are released first. Defaults to
-     *  `DEV_SERVER_RESTART_DELAY_MS`; tests inject a tiny value. */
     devServerRestartDelayMs?: number;
 }
-/**
- * Minimal telemetry surface the orchestrator depends on. Decoupled from
- * TelemetryService so unit tests can pass a stub. Production wires this
- * to the singleton TelemetryService instance.
- */
 export interface VariantsTelemetry {
     track(event: string, properties?: Record<string, unknown>): void;
     trackAgentVariantsRequestStarted?: (data: MCPVariantsTelemetryMetadata) => void;
@@ -226,15 +121,10 @@ export interface VariantsTelemetry {
         sessionId: string;
         variantId: string;
         errorCode: string;
-        /** Coarse cause: 'spawn_error' | 'exited' | 'timeout' |
-         *  'missing_dev_script' | 'unknown'. */
         reason?: string;
-        /** True when the failure was a port collision (EADDRINUSE / already running). */
         portInUse?: boolean;
-        /** Child exit code / signal when reason is 'exited'. */
         exitCode?: number | null;
         signal?: string | null;
-        /** True when the output matched module-resolution failure markers. */
         missingDeps?: boolean;
     }) => void;
     trackAgentVariantsPreviewStarted?: (data: {
@@ -291,9 +181,6 @@ export interface VariantsTelemetry {
         durationMs: number | null;
     }) => void;
 }
-/** Snapshot shape consumed by the iframe chip, both via SSE and the legacy
- *  GET /api/variants/active endpoint. Single source of truth lives on the
- *  orchestrator (`buildActiveSnapshot`) so both transports are consistent. */
 export type ActiveSnapshot = {
     active: false;
 } | {
@@ -307,41 +194,13 @@ export type ActiveSnapshot = {
     };
     summary: TerminalSummary | null;
     variants: ActiveVariantSnapshot[];
-    /** Project context for the session — surfaced so the chip can render
-     *  a "Creating new project at {destinationPath}" header for fresh
-     *  sessions vs the default refinement header. */
     projectContext: ActiveProjectContext;
-    /** For fresh sessions, the user-facing destination path the materialize
-     *  step will land at. Undefined for existing-project sessions. */
     destinationPath?: string;
-    /** Supporting artifacts the agent used or generated for this session
-     *  (e.g. the DESIGN.md inspirations for a 0→1 run). Surfaced under the
-     *  variants list so the user can inspect the hidden MCP context. */
     artifacts?: VariantSessionArtifact[];
     hostWork?: import('./contracts').HostVariantWorkItemSnapshot[];
-    /** One-line summary of the run's worker-runtime lease decision —
-     *  `"codex (initiator)"` / `"host path (cursor: …)"` — so status
-     *  surfaces can answer "what is running these directions?" while
-     *  workers are still in flight (per-variant `runtime` lands only on
-     *  completion). Reflects the most recent batch in the session. */
     workerRuntime?: string;
-    /** Depth of the server's variant-request/refine FIFO at snapshot time.
-     *  Stamped onto the SSE payload from the live bridge (the FIFO does not
-     *  live on the orchestrator), so `buildActiveSnapshot()` itself leaves it
-     *  undefined and the SSE route fills it in. */
     pendingVariantRequests?: number;
 };
-/**
- * Wraps SessionStore for the operations that have side effects: approve
- * (provision worktrees), reportComplete (capture diff), commit (apply picked
- * output), cancel (teardown). Pure read paths bypass and call SessionStore
- * directly.
- *
- * This is the terminal-native variant of the orchestrator: the user picks
- * a single brief upfront, so there's only ever one code-gen item per
- * session and no live preview / proxy retarget. Once the agent reports
- * the variant succeeded, the CLI can commit the chosen output directly.
- */
 export declare class AgentVariantsOrchestrator {
     private readonly store;
     private readonly worktrees;
@@ -358,75 +217,23 @@ export declare class AgentVariantsOrchestrator {
     private readonly activeVariantServerIdleTtlMs;
     private readonly devServerRestartDelayMs;
     private readonly resources;
-    /**
-     * Committed dev servers from prior sessions that survived teardown. The
-     * orchestrator outlives any single session — once a new session starts, the
-     * prior committed dev server is no longer needed (the next session opens
-     * its own preview chip), so stop it before the new session's first preview
-     * goes live. Keyed by sessionId for diagnostics; values are kept alive
-     * intentionally between commit and next `propose` / `shutdown`.
-     */
     private readonly lingeringCommittedDevServers;
-    /**
-     * Per-session in-flight commit chain. Two overlapping commitVariant calls
-     * would otherwise both pass the `getVariantPick` idempotency check (the
-     * pick isn't recorded until after `applyDiffToProject`) and double-invoke
-     * `git apply` — which corrupts the working tree on the second run. The
-     * chain serializes commits per session so the second caller waits for the
-     * first to finish and then hits the idempotency check (returning
-     * `duplicate: true` for the same variantId, or `PENDING_CHANGE_CONFLICT`
-     * for a different one).
-     */
     private readonly inflightCommits;
-    /** Most recent agent-variants sessionId — read by the iframe chip via
-     *  GET /api/variants/active. Cleared on cancel or commit. */
     private activeSessionId;
-    /** Push channel for the iframe chip's SSE subscription. Emits an
-     *  ActiveSnapshot on every state change so the chip never has to poll. */
     private readonly events;
     constructor(deps: OrchestratorDeps);
     propose(args: ProposeArgs): ProposeResult;
-    /** Returns the most recent agent-variants sessionId (or null). */
     getActiveSessionId(): string | null;
-    /** Subscribe to active-snapshot pushes. Returns an unsubscribe fn. */
     subscribeToEvents(listener: (snapshot: ActiveSnapshot) => void): () => void;
-    /** Number of live Rivet UI clients subscribed to the variants SSE stream.
-     *  A subscribed client means a Rivet page is open in the browser. */
     private uiClientCount;
-    /** Wall-clock of the last UI-client connect/disconnect. `hasUiClients`
-     *  treats a very recent disconnect as still-connected to ride out the brief
-     *  gap when an EventSource drops and auto-reconnects (default retry ~3s) —
-     *  otherwise a `propose`/`start` landing in that window reads zero clients
-     *  and spawns a duplicate browser tab. */
     private lastUiClientActivityAt;
-    /** Grace window covering an EventSource reconnect (its default retry is ~3s;
-     *  the SSE heartbeat is 30s). Long enough to span a reconnect, short enough
-     *  that a genuine page close frees the "reopen on next propose" path quickly. */
     private static readonly UI_CLIENT_GRACE_MS;
-    /**
-     * Register a live Rivet UI client (called when the variants SSE stream opens).
-     * Returns a release fn to call on disconnect. Used as the "a Rivet page is
-     * already open" signal so the MCP server can avoid spawning a duplicate tab
-     * every time the variants flow re-enters an already-active editor session.
-     */
     registerUiClient(): () => void;
-    /** True when at least one Rivet UI page is currently connected — or one
-     *  disconnected within the grace window (an EventSource mid-reconnect). */
     hasUiClients(): boolean;
-    /** @effect Records activity for the current variants session, if one exists. */
     touchActiveSession(): void;
-    /** @effect Resets idle cleanup for active variant preview servers. */
     touchSession(sessionId: string): void;
-    /** Build the snapshot the chip cares about. Reads from SessionStore +
-     *  per-resource state; safe to call at any time. */
     buildActiveSnapshot(): ActiveSnapshot;
-    /** Record which worker runtime this session's current batch leases to —
-     *  called by the generation services right after the lease-owner decision
-     *  so `variants start`/status can answer "what is running these?". */
     setWorkerRuntime(sessionId: string, summary: string): void;
-    /** User reference files stored in the work item's context bundle (uploaded
-     *  or copied local images). Surfaced on the snapshot so briefings can point
-     *  workers at the files directly — one Read instead of a bundle walk. */
     private static contextFilesOf;
     getHostWork(sessionId: string): HostVariantWorkItemSnapshot[];
     private getAssignedWorkspace;
@@ -463,24 +270,10 @@ export declare class AgentVariantsOrchestrator {
         workItemId?: string;
         workItemIds?: string[];
     }): RequestWorkResult;
-    /** @effect Copies caller-supplied context assets into each leased workspace. */
     private materializeContextAssets;
-    /**
-     * @effect Records how an existing project's worktrees will be previewed so
-     * context assets receive references that resolve on that serving surface.
-     */
     private resolveContextAssetPreviewKind;
-    /**
-     * @effect Writes each leased implementation item's server-authored briefing
-     * BESIDE its workspace so the coordinating host dispatches workers with a
-     * short pointer prompt instead of composing prose per worker. Best-effort:
-     * a briefing write failure never blocks the lease (the host guidance's
-     * packet fields still carry the same data).
-     */
     private writeLeasedWorkItemBriefings;
-    /** @effect Assigns isolated, server-owned artifact workspaces to leased static work. */
     private ensureStaticWorkspaces;
-    /** Reads a completed static artifact while enforcing its assigned directory boundary. */
     private readAssignedStaticArtifact;
     beginStaticPreviewRefinements(args: {
         sessionId: string;
@@ -494,29 +287,12 @@ export declare class AgentVariantsOrchestrator {
             element?: StaticPreviewTargetElement;
             relevantFiles?: string[];
             requestId?: string;
+            additionalContext?: Pick<VariantWorkItemContext, 'contextBundlePath' | 'userContext' | 'rivetMetadata'>;
         }>;
     }): {
         droppedRefinements: DroppedRefinement[];
         createdWorkItemIds: string[];
     };
-    /**
-     * Adopt a PAST variant (from a prior session's persisted history) into the
-     * active session, rehydrating it from its on-disk static snapshot so the
-     * comment / refine / Vary machinery treats it as a live, first-class variant.
-     *
-     * Triggered when the user makes their first edit on a selected past direction.
-     * The store appends an already-`succeeded` `static_preview` work item keyed by
-     * the past identity (idempotent); this method registers the matching static-
-     * preview record so {@link getStaticPreviewHtml}, {@link getVariants}
-     * (preview.kind = 'static_artifact', view enabled), and the
-     * `/api/variants/:sid/static/:vid` routes all light up exactly as they do for a
-     * freshly-generated static_preview variant.
-     *
-     * `filesDir` is the absolute path to the persisted `files/` snapshot and
-     * `entryPath` is its selected HTML document. Returns the stable active-session
-     * `workItemId` so the caller can route the triggering edit to it, plus whether
-     * it was already adopted.
-     */
     adoptPastVariant(args: {
         sessionId: string;
         source: {
@@ -527,16 +303,12 @@ export declare class AgentVariantsOrchestrator {
         entryPath: string;
         label: string;
         description?: string;
+        references?: VariantReference[];
         runLabel?: string;
     }): Promise<{
         workItemId: string;
         alreadyAdopted: boolean;
     }>;
-    /**
-     * Rehydrate a static history variant into the current active session when it
-     * can still accept edits; otherwise create a replacement active session whose
-     * only visible direction is the selected history artifact.
-     */
     bootstrapPastVariantSession(args: {
         source: {
             sessionId: string;
@@ -546,6 +318,7 @@ export declare class AgentVariantsOrchestrator {
         entryPath: string;
         label: string;
         description?: string;
+        references?: VariantReference[];
         runLabel?: string;
         prompt?: string;
         projectContext: ProjectContext;
@@ -557,18 +330,7 @@ export declare class AgentVariantsOrchestrator {
     }>;
     private getUsableActiveSessionId;
     private resolveAdoptedStaticPreviewFiles;
-    /**
-     * True when the variant is an HTML-only static_preview work item. Adopted past
-     * variants and fresh `static_preview` variants both qualify. Existing-project
-     * `code_gen` variants can still expose a static artifact for preview, but Vary
-     * must keep those on the worktree-backed code_gen append path.
-     */
     isStaticPreviewVariant(sessionId: string, workItemId: string): boolean;
-    /**
-     * Resolve the history source for a forked Vary row. If the immediate parent
-     * is an adopted past direction, collapse against that original history row;
-     * otherwise collapse against the same-session parent variant.
-     */
     private resolveHistoryParentVariant;
     getVariantPick(sessionId: string): ReturnType<SessionStore['getVariantPick']>;
     refineVariant(args: {
@@ -579,7 +341,6 @@ export declare class AgentVariantsOrchestrator {
     }): RequestWorkResult;
     getStage(sessionId: string): Stage;
     getWorkItemInput(sessionId: string, workItemId: string): unknown;
-    /** Returns status after orchestration QA and refinement post-processing. */
     getWorkItemStatus(sessionId: string, workItemId: string): WorkItemStatus;
     getBriefs(sessionId: string): Brief[];
     getProgress(sessionId: string): {
@@ -589,66 +350,19 @@ export declare class AgentVariantsOrchestrator {
     getSummary(sessionId: string): TerminalSummary;
     getVariants(sessionId: string): ActiveVariantSnapshot[];
     hasSession(sessionId: string): boolean;
-    /** Read the projectContext for a session — used by Express routes that
-     *  build the chip snapshot via `stateForSession`. */
     getProjectContext(sessionId: string): ProjectContext;
-    /** Resolve a worktree path for a code-gen work item, if provisioned. */
     getWorktreePath(sessionId: string, workItemId: string): string | undefined;
-    /**
-     * Resolve the project cwd inside a worktree so subdirectory projects run
-     * from the same repo-relative location.
-     */
     getProjectCwdInWorktree(worktreePath: string): Promise<string>;
-    /** Resolve the dev server port for a code-gen work item, if running. */
     getDevServerPort(sessionId: string, workItemId: string): number | undefined;
-    /**
-     * Restores a Rivet-owned preview after idle reclamation or an explicit retry
-     * of a failed start. Reuses the saved worktree without leasing generation work.
-     *
-     * @effect Clears the idle marker and prior crash budget, starts the worktree
-     *   dev server, and emits preview-state snapshots.
-     * @deps Uses the live session resources, project context, and dev-server
-     *   manager owned by this orchestrator.
-     */
     restoreVariantPreview(sessionId: string, workItemId: string, options?: {
         retryFailed?: boolean;
     }): Promise<number | undefined>;
-    /**
-     * @effect Resolves the dev server port for a preview request and refreshes
-     *   active-preview retention for that session while the port is still live.
-     */
     resolveDevServerPortForPreview(sessionId: string, workItemId: string): number | undefined;
-    /**
-     * True work-item kind for a variant, or undefined when the session/item is
-     * unknown. This is the authoritative routing signal for Vary/refine intakes:
-     * an existing-project `code_gen` variant materialized as a static preview
-     * (registerExistingStaticPreview) DISPLAYS as `static_artifact` and serves
-     * HTML, but must fork via the code_gen/worktree path — HTML presence is not
-     * a valid discriminator.
-     */
     getVariantWorkItemKind(sessionId: string, workItemId: string): string | undefined;
     getStaticPreviewHtml(sessionId: string, workItemId: string): string | undefined;
-    /** Resolve the DESIGN.md markdown behind an artifact link. */
     getDesignContextMarkdown(sessionId: string, artifactId: string): string | undefined;
-    /** Build the rendered DesignMD document for an artifact link. */
     getDesignContextViewerHtml(sessionId: string, artifactId: string): string | undefined;
-    /**
-     * `true` when the variant has a non-empty `assetBase` — i.e. its inlined
-     * HTML references sibling files served by the asset route. The route
-     * uses this to decide whether to inject a `<base href>` (only needed
-     * when relative URLs in the HTML must resolve against the asset
-     * sub-path). Self-contained HTML keeps its natural URL resolution.
-     */
     hasStaticPreviewAssets(sessionId: string, workItemId: string): boolean;
-    /**
-     * Resolve an absolute, sandboxed path for a sibling asset that the
-     * variant's inlined HTML references (e.g. `./avatar.glb`, `./hero.png`).
-     * Returns `undefined` when the variant has no `assetBase`, the requested
-     * path escapes the base (path traversal), or the file does not exist.
-     *
-     * Used by the `/api/variants/:sessionId/static/:variantId/<asset>` route
-     * to serve assets from the agent's on-disk variant workspace pre-commit.
-     */
     resolveStaticPreviewAssetPath(sessionId: string, workItemId: string, requestedPath: string): string | undefined;
     private getStaticPreviewByBriefId;
     private buildStaticPreviewUrl;
@@ -656,66 +370,20 @@ export declare class AgentVariantsOrchestrator {
         sessionId: string;
         selections: ApprovedBriefSelection[];
     }): Promise<ApproveResult>;
-    /**
-     * Unified one-call kickoff that collapses propose → report_briefs →
-     * approve. Uses AI-authored briefs supplied by agent callers, with a
-     * deterministic prompt-derived fallback for human-direct calls, and
-     * immediately approves so the session lands in `work_items_ready`.
-     *
-     * Supports both existing-project sessions (spawns code_gen work items
-     * for the agent to lease) and zero-to-one sessions (spawns
-     * static_preview work items; the server runs scaffold_base in the
-     * background). This is the single-call path; source-grounded zero-to-one
-     * sessions (source URLs / inspiration extraction) run through `propose`
-     * instead so the source-research flow can gate generation — start_variants
-     * routes them there. This method does not run source research.
-     *
-     * Host-agnostic: no LLM calls happen here. The agent (Claude Code,
-     * Cursor, Codex) generates the label and code when it leases the
-     * work items via continue_variants(action="request_work").
-     */
     startUnified(args: {
+        assertContext?: () => void;
         prompt: string;
         count?: number;
         target?: Target;
         projectContext?: ProjectContext;
-        /** Pre-generated session id. Lets the caller build a variant context
-         *  bundle (whose on-disk path embeds the session id) before the session
-         *  exists, then hand both in together. Defaults to a fresh id. */
         sessionId?: string;
-        /** Agent-supplied short label for the run's intent (heuristic fallback
-         *  when absent). Shared by every variant in the run. */
         runLabel?: string;
-        /** When provided, the orchestrator leases all spawned variant work
-         *  items immediately so the caller can hand the lease + worktreePaths
-         *  back to the agent in the same response — saving a separate
-         *  continue_variants(request_work) round-trip. */
         leaseOwner?: string;
-        /** Per-variant briefs supplied by the agent (label + body, optional
-         *  visualReferenceUrl). When provided, briefs.length overrides any
-         *  explicit count. When absent, the server derives a run-intent label
-         *  per slot from the prompt and a copy of the prompt as each body. */
         briefs?: import('./contracts').StartVariantsBriefContent[];
-        /** UI correlation id (the originating change batch's agentRunId/traceId).
-         *  Stamped onto each spawned variant so the panel can map its optimistic
-         *  placeholders to the real cards. */
         requestId?: string;
-        /** Opt in to cross-Vary accumulation: when an existing-project session for
-         *  the same `projectPath` is already active, append these variants to it
-         *  instead of starting a fresh session. Only the MCP `start_variants`
-         *  existing path sets this — the inline-element-variant flow leaves it off
-         *  so it always gets its own session (it cancels that session on failure
-         *  and must never tear down an accumulated one). */
         allowAccumulate?: boolean;
-        /** When set with {@link allowAccumulate}, fork new code_gen variants from
-         *  this parent variant's worktree instead of git HEAD / Original. */
         sourceVariantId?: string;
-        /** Known project files from the initiating selection. Workers inspect
-         *  these first and expand only when dependencies require it. */
         relevantFiles?: string[];
-        /** User-selected design fidelity (worker tier selector). Each batch stamps
-         *  its own selection onto its implementation items; absent means the
-         *  server default. */
         fidelity?: import('./contracts').WorkerFidelity;
     }): Promise<{
         sessionId: string;
@@ -726,47 +394,15 @@ export declare class AgentVariantsOrchestrator {
             status: 'pending';
         }>;
         scaffoldBaseWorkItemId: string | null;
-        /** Populated when `leaseOwner` was provided. */
         leaseId?: string;
         leaseTtlMs?: number;
         leasedWorkItems?: import('./SessionStore').RequestWorkResult['leasedWorkItems'];
     }>;
-    /**
-     * Build the per-variant briefs for a unified start. Supplied briefs keep
-     * meaningful direction labels, while duplicate or empty labels are made
-     * unique against the visible session rows. The fallback derives a short
-     * run-intent label from the prompt (e.g. "make it brighter" →
-     * "Brighter 1/2/…") rather than an indistinct "Variant N". `uniqueBriefIds`
-     * is set for the append path so the new batch's briefIds can't collide with
-     * the live session's existing ones.
-     */
     private buildUnifiedBriefs;
-    /**
-     * The active sessionId IF it is an existing-project session for `projectPath`
-     * that can still accept appended variants — i.e. not committed, not
-     * cancelled/failed. Returns null otherwise, so start_variants falls back to
-     * creating a fresh session (first Vary, a different project, or after the
-     * prior session was committed/cancelled).
-     */
     private getAppendableExistingSessionId;
-    /** @effect Registers a provisioned git worktree with runtime and workspace state. */
     private registerWorktreeWorkspace;
-    /**
-     * Provision a worktree for each appended existing-project variant. Mirrors
-     * {@link provisionExistingWorktrees} but only for the newly appended ids, and
-     * passes a per-batch `instanceKeyPrefix` so the new worktree dirs do not
-     * collide with the first batch's `${sessionId}-${i}` paths.
-     */
-    /** Emits provisioning started/completed/failed telemetry around `run` for
-     *  the vary-fork/append lanes that bypass provisionWorktrees (and its
-     *  telemetry). Rethrows failures untouched. */
     private withProvisioningTelemetry;
     private provisionAppendedExistingWorktrees;
-    /**
-     * Provision worktrees for a code_gen Vary forked from a parent variant.
-     * Copies the parent's worktree tree so each sibling starts from the parent's
-     * diff rather than git HEAD / Original.
-     */
     private provisionForkedFromVariantWorktrees;
     reportComplete(args: {
         sessionId: string;
@@ -783,13 +419,9 @@ export declare class AgentVariantsOrchestrator {
         tokensIn?: number;
         tokensOut?: number;
         model?: string;
-        /** Worker cost in USD (executor-run workers bill outside any host
-         *  session; this keeps them cost-accountable in telemetry). */
         costUsd?: number;
         title?: string;
         description?: string;
-        /** The runtime that executed the worker — persisted on the work item so
-         *  status/history surfaces can attribute the variant to a vendor/model. */
         runtime?: import('./contracts').WorkerRuntimeInfo;
     }): Promise<ReportCompleteResult>;
     cancel(args: {
@@ -799,13 +431,6 @@ export declare class AgentVariantsOrchestrator {
         stage: 'cancelled';
         cleanupStatus: 'pending' | 'complete' | 'partial';
     }>;
-    /**
-     * Cancel a single variant within a session. Siblings continue. Idempotent
-     * on terminal states. Per-variant worktree teardown is deferred to a
-     * follow-up; the lease is released, so requestWork won't re-surface this
-     * variant and the agent's report_variant_complete for it (if it lands
-     * after cancellation) is rejected by the stale-lease check.
-     */
     cancelVariant(args: {
         sessionId: string;
         variantId: string;
@@ -817,12 +442,6 @@ export declare class AgentVariantsOrchestrator {
         sessionStage: Stage;
         alreadyTerminal: boolean;
     }>;
-    /**
-     * Remove a variant from the UI. Hides it from the active snapshot for good
-     * (it's filtered out of progress/summary/terminal accounting too) while
-     * retaining it in `.rivet/variants/` with status `removed` so the work is
-     * kept, never rendered again. Mirrors `cancelVariant`'s shape; idempotent.
-     */
     removeVariant(args: {
         sessionId: string;
         variantId: string;
@@ -833,13 +452,6 @@ export declare class AgentVariantsOrchestrator {
         sessionStage: Stage;
         alreadyRemoved: boolean;
     }>;
-    /**
-     * Rename a variant's user-visible title. Patches the in-memory work item so
-     * the next snapshot carries the new label, persists it to the variant's
-     * `.rivet/variants/` manifest (best-effort — a never-persisted variant simply
-     * skips the disk write), and pushes the updated snapshot over SSE. Mirrors
-     * `removeVariant`'s shape.
-     */
     renameVariant(args: {
         sessionId: string;
         variantId: string;
@@ -850,10 +462,6 @@ export declare class AgentVariantsOrchestrator {
         label: string;
         sessionStage: Stage;
     }>;
-    /**
-     * Rename a run folder: re-home one request batch in a single store pass,
-     * persist each affected manifest best-effort, and push one updated snapshot.
-     */
     renameRun(args: {
         sessionId: string;
         requestId?: string;
@@ -866,12 +474,6 @@ export declare class AgentVariantsOrchestrator {
         renamedCount: number;
         sessionStage: Stage;
     }>;
-    /**
-     * User has reviewed the rendered variants and picked one. Look up the
-     * captured diff or generated project, apply it to the destination, and record
-     * the pick. Idempotent on (sessionId, variantId): repeating the call returns
-     * duplicate=true without applying again.
-     */
     commitVariant(args: {
         sessionId: string;
         variantId: string;
@@ -886,241 +488,47 @@ export declare class AgentVariantsOrchestrator {
     }>;
     private commitVariantImpl;
     cleanupCommittedSession(sessionId: string): Promise<void>;
-    /**
-     * Ensure the user-facing destination path can receive the new project.
-     * Rejects when the path exists and is non-empty.
-     *
-     * `.rivet/` (pre-commit snapshots + history manifests) and `.gitignore`
-     * (written by VariantHistoryService.ensureGitignore when variants persist
-     * at success time) are both tolerated — neither is user-authored content
-     * that would be clobbered by the materialize step.
-     */
     private assertDestinationAvailable;
-    /** Read the captured diff for a code-gen variant, if available. */
     getVariantDiff(sessionId: string, variantId: string): string | undefined;
     private provisionWorktrees;
-    /**
-     * Existing-project flow: clone the user's repo N times via git worktree.
-     * Waits for source and dependency copies before making work available.
-     */
     private provisionExistingWorktrees;
-    /**
-     * Fresh-project flow: scaffold one template per variant + DESIGN.md per
-     * slot synchronously (fast — just file writes + git init), then dispatch a
-     * background `npm install` task per worktree. Returns immediately so the
-     * `approve_variant_briefs` MCP tool doesn't time out on cold installs.
-     *
-     * On install success: `sessionStore.completeInternal(scaffold_base)` runs,
-     * which unblocks the dependent code_gen items.
-     *
-     * On install failure: the scaffold_base work item is marked failed via
-     * `failInternal`, which cascades DEPENDENCY_FAILED to all dependent
-     * code_gen items so the session degrades cleanly.
-     */
     private provisionFreshWorktrees;
-    /**
-     * Run `npm install` in parallel across all fresh worktrees. On all-success,
-     * mark scaffold_base succeeded via `completeInternal`. On any failure,
-     * mark scaffold_base failed via `failInternal` and emit telemetry.
-     */
     private runBackgroundInstall;
-    /**
-     * Checks succeeded implementation reports before they reach the store.
-     * Static previews must contain a structurally complete local artifact;
-     * applicable existing-project variants must contain an added diff. Returns
-     * a pass, a single repair retry, or a terminal integrity failure.
-     */
     private evaluateQaForReport;
     private evaluateExistingCodeGenQa;
-    /** Run the injected preview QA runner, converting a thrown runner into a
-     *  failed `VariantQaResult` (mirrors the prior inline behavior). */
     private runPreviewQaSafely;
     private memoizeQa;
-    /**
-     * Handle a `retry` QA verdict: consume the agent's report, re-open the
-     * variant work item so it can be re-leased and regenerated against the QA
-     * notes, and record that it has now used its single retry.
-     */
     private handleQaRegenRetry;
     private startVariantDevServer;
     private handleSucceededReport;
     private handleStaticPreviewRefinement;
-    /** The worktree/dev-server manager this orchestrator boots previews with.
-     *  Exposed so HistoryReplayService shares the SAME instance: the
-     *  reserved-but-not-yet-bound port set is per-instance, and a second
-     *  manager scanning the same range can hand a live variant's pending port
-     *  to a replay (EADDRINUSE for the loser). */
     get devServerManager(): WorktreeManagerLike;
-    /** In-flight fire-and-forget history persists. Tree-store snapshots spawn
-     *  git subprocesses, so these can outlive the microtask flushes that used
-     *  to be enough to drain them — {@link teardownSession} (and the test
-     *  helpers' settleBackgroundWork) await {@link settleHistoryPersists}
-     *  instead of racing the writes. */
     private readonly pendingHistoryPersists;
     private trackHistoryPersist;
-    /** Await every in-flight history persist, including ones that start while
-     *  draining (a refine can persist mid-settle). */
     settleHistoryPersists(): Promise<void>;
-    /**
-     * Persist a completed existing-project code_gen variant into
-     * `<env.projectPath>/.rivet/variants/<sessionId>/<variantId>/`. Called from
-     * `handleSucceededReport` once the worktree diff has been captured but
-     * before the user picks. Status is `completed` until `commitVariant` or a
-     * cancellation transitions it.
-     */
     private persistCompletedExistingVariant;
-    /**
-     * Existing-mode `framework: 'static'` projects have no dev command, so there
-     * is no per-variant dev server for the iframe to proxy. Register the variant's
-     * materialized static site as a {@link StaticPreviewRecord} so the existing
-     * static-file plumbing — the `/api/variants/:sid/static/:vid[/asset]` routes,
-     * {@link getStaticPreviewHtml}, and {@link getVariants} (preview.kind=
-     * 'static_artifact', view enabled) — all light up exactly as they do for
-     * fresh `static_preview` variants. The entry HTML and its sibling assets are
-     * served straight from the variant's worktree project root (session-scoped,
-     * pre-commit; the persisted `.rivet/variants/.../files/` copy backs the
-     * post-session history route separately).
-     *
-     * Returns `registered` when the static preview is ready, `unavailable` when
-     * the project is static but its selected entry cannot be served, and
-     * `not_static` when the caller should start a dev server instead.
-     */
     private registerExistingStaticPreview;
-    /**
-     * Persist a completed fresh-project variant into
-     * `<projectContext.workspacePath>/.rivet/variants/<sessionId>/<variantId>/`.
-     * Called from `handleSucceededReport` right after the per-variant snapshot
-     * lands on disk — for static_preview that's the `.rivet/<slug>/` snapshot
-     * dir; for vite_app fresh variants it's the worktree itself. Status starts
-     * as 'completed' and transitions to 'committed' / 'rejected' / 'cancelled'
-     * via `markStatus` at commit or teardown time.
-     *
-     * Running at success time (rather than commit time) means the history panel
-     * populates live as variants generate — including when the user never picks
-     * one. Mirrors the existing-project persistCompletedExistingVariant flow.
-     */
     private persistCompletedFreshVariant;
-    /**
-     * @effect Drains fresh-project history writes before commit moves or rewrites
-     * the generated project folder.
-     */
     private persistCompletedFreshVariantsForCommit;
-    /**
-     * At commit time, flip persisted variant manifests to terminal statuses
-     * ('committed' for the chosen, 'rejected' for the rest). Both existing- and
-     * fresh-project variants have already been persisted at code_gen success
-     * time, so this is a pure status update — no source-dir copy required.
-     * Also records the destination path on the chosen variant so history can
-     * surface "this variant became <path>".
-     */
     private persistVariantHistoryAtCommit;
-    /**
-     * Flip persisted variant manifests to status='cancelled' for every variant
-     * in the session that was already snapshotted to disk. Fresh- and existing-
-     * project variants both persist at success time now, so both need their
-     * manifests flipped here. Best-effort — missing manifests are silently
-     * skipped by VariantHistoryService.markStatus.
-     */
     private markPersistedVariantsCancelled;
     private markPersistedVariantCancelled;
     private markPersistedVariantRemoved;
     private markPersistedVariantRenamed;
-    /**
-     * Resolve the project path that owns `.rivet/variants/` for a session.
-     * Existing sessions use the user's project. Fresh sessions use the generated
-     * project folder. Must match what `persistCompletedFreshVariant` writes to.
-     */
     private resolveHistoryProjectPath;
     private readManifest;
-    /**
-     * The port to start scanning from when allocating a variant's preview dev
-     * server. Fresh worktrees run the Vite template (5173); existing projects use
-     * their detected framework's default (3000 for Next, etc.), falling back to
-     * 3000 if detection fails. Scanning upward from here lands the preview on a
-     * sensible, predictable port near the project's normal one.
-     */
     private resolveDevServerStartPort;
-    /**
-     * Resolve dev server invocation for a worktree. Fresh-project worktrees
-     * always use the Vite template's npm command at the worktree root; existing
-     * projects defer to the user's framework/packageManager config.
-     */
     private resolveDevServer;
-    /**
-     * Pure invocation resolution — no dependency installs, no side effects.
-     * Split from {@link resolveDevServer} so history persistence can capture
-     * the SAME deterministic resolution the boot path uses without booting:
-     * persist fires at code-gen success, before the dev server starts, so the
-     * live record's stashed command usually isn't available yet.
-     */
     private resolveDevServerCommand;
-    /** Prepares the direction's declared dependencies before each server start. */
     private ensureProjectDependencies;
-    /**
-     * Resolve the dev-server working directory for an existing-project variant.
-     * WorktreeManager is constructed around the editor/root project, but
-     * `start_variants` can target a nested app (for example `examples/blog`).
-     * In that case the worktree root is still the git root clone, while the dev
-     * server must run from the nested project path.
-     */
     private resolveExistingProjectCwd;
-    /**
-     * After the chosen variant has been renamed into `destinationPath`, move
-     * each unchosen sibling worktree into a `<destinationParent>/<slug>-variants/NN-<label>/`
-     * folder with its own prepared dependency installation. Writes a manifest documenting all 5 variants (the chosen
-     * one with `folder: null` and `chosenPath: '../<slug>'`).
-     *
-     * Sets `vitePreservedSiblings = true` on session resources so the
-     * subsequent teardown skips `cleanupFreshWorktrees` (which would otherwise
-     * delete the just-preserved history). Dev servers still get stopped.
-     */
     private preserveUnchosenVariants;
-    /**
-     * Rename `sourceWorktreePath` into `destinationPath`, then replace the
-     * worktree's `.git` with a fresh-history init + initial commit. Matches
-     * the historical materializeProject behavior of "user sees a fresh repo
-     * at destinationPath" so we don't surprise them with a `rivet: variant
-     * baseline` commit they didn't intend.
-     *
-     * The rename is the load-bearing operation: it moves the entire variant
-     * tree (template files + materialized node_modules) in O(1) when the
-     * source and destination share a volume. The git reset that follows is
-     * best-effort housekeeping; a failure there leaves files in place.
-     */
     private renameWorktreeIntoDestination;
-    /**
-     * Stop every variant dev server currently running for `resources`. Clears
-     * the `devServerProcess` / `port` fields on each record so subsequent
-     * teardown logic doesn't try to stop them a second time. Called from
-     * `commitVariant` (vite_app rename path) BEFORE the worktree directory is
-     * renamed — leaving Vite alive across the rename leaks empty `.vite/`
-     * stub dirs at the old paths.
-     */
     private stopAllDevServersForSession;
     private scheduleActivePreviewIdleTimer;
     private clearActivePreviewIdleTimer;
-    /** @effect Stops idle variant child processes and clears dead preview ports. */
     private stopIdleVariantDevServers;
-    /**
-     * Spawn a fresh dev server at the user-facing destinationPath and retarget
-     * the proxy so the iframe stays live across commit. Stores the process on
-     * `resources.committedDevServer` so teardown can hand it off to the
-     * lingering registry instead of killing it. Best-effort: a failure here is
-     * non-fatal — the commit still succeeds; the user just has to run
-     * `npm run dev` themselves to bring the preview back.
-     *
-     * `mode` selects the server flavor: `vite_app` spawns Vite via `npm run
-     * dev`; `static_preview` spawns the in-tree static file server bound to
-     * the destination directory (no install, no build, ~ms startup).
-     */
     private startCommittedDevServer;
-    /**
-     * Stop any committed dev servers that were left alive past their session's
-     * teardown. Called at the start of a new `propose` (so the next session's
-     * preview doesn't compete with stale processes) and exposed for explicit
-     * shutdown hooks. Best-effort: per-server failures are logged but don't
-     * propagate.
-     */
     private stopLingeringCommittedDevServers;
     private teardownSession;
     private ensureResources;