rivet-design 0.12.4 → 0.13.1

package/README.md

@@ -1,60 +1,84 @@
 # Rivet
 
-Rivet helps you explore multiple design directions for your web app. It generates parallel variants you can compare side by side, refine with precision, and share or implement — all from your coding agent.
+Rivet helps you explore multiple design directions for your web app. It opens a local visual editor, generates parallel variants, lets you refine with comments, and can send the chosen direction back into your project.
 
-## How it works
+## Install
 
-Rivet runs as an MCP server alongside your coding agent (Claude Code, Cursor, etc.).
+Run the installer from the project where you want AI agents to use Rivet:
 
-1. **Start from your agent.** Use `/rivet` in Claude Code, or tell your agent "Use Rivet variants" or "Explore with Rivet" along with your design request.
-2. **Connect design references** (optional). Click **Connect design references** in the editor to link your Pinterest or Are.na account. Include relevant pins or boards and Rivet will extract design context from them to inform the variants it generates.
-3. **Refine with the comment tool.** Select any part of the UI and use the comment tool to make more precise variants of that section, or leave comments describing what you'd like to change within a variant.
-4. **Share or implement.** When you're happy, click the **Share** button to get a shareable link you can send to a collaborator — or share it back to your coding agent to implement the chosen direction.
+```bash
+npx -y rivet-design@latest install
+```
 
-## Install
+The installer writes CLI usage guidance and command allowlists for detected shell-capable agents such as Claude Code, Cursor, and Codex. After installing, start a new agent session and say "Open Rivet" or "/rivet".
 
-**Option 1 — CLI (recommended)**
+You can also run Rivet directly without a global install:
 
 ```bash
-claude mcp add --transport stdio --scope user rivet -- npx -y rivet-design@latest mcp --editor claude
+npx -y rivet-design@latest open --project /path/to/app
 ```
 
-**Option 2 — Run Rivet's installer** (adds Rivet globally via Claude Code CLI)
+If installed globally, the package exposes the `rivet` binary:
 
 ```bash
-npx rivet-design install
+rivet open --project /path/to/app
 ```
 
-No global install required. `npx` pulls the latest version each time.
+## CLI Agent Commands
 
-## Usage
+Rivet's agent-facing commands print one JSON envelope on stdout, write progress to stderr, and do not prompt for input.
 
-Once installed, tell your agent what you want to explore:
+For interactive user workflows, run `rivet open` without `--no-browser` so the Rivet UI opens in the browser. Use `--no-browser` only for headless/background automation, CI/e2e checks, or when the user explicitly asks not to open a browser; in those cases, report the returned `editorUrl`.
 
+```bash
+rivet open --project /path/to/app
+rivet status --project /path/to/app
+rivet variants start --project /path/to/app --instruction "try three hero layouts" --count 3
+rivet wait <workId> --project /path/to/app --timeout 120
+rivet variants list --project /path/to/app
+rivet variants commit <variantId> --project /path/to/app
+rivet changes request --project /path/to/app --instruction "make the header coral" --element "#header"
+rivet changes pull --project /path/to/app
+rivet stop --project /path/to/app
 ```
-"Use Rivet variants to explore hero section designs"
-"Explore with Rivet — show me options for the navigation"
-"/rivet redesign the pricing page"
+
+For a fresh project, create or use an empty directory, open Rivet there, then start variants with `--fresh`:
+
+```bash
+rivet open --project /path/to/new-app
+rivet variants start --project /path/to/new-app --fresh --instruction "build a SaaS landing page" --count 3
 ```
 
-Your agent will open Rivet, generate parallel design directions, and let you compare them side by side in the browser. Use the comment tool to refine, connect Pinterest or Are.na boards for design context, and share or implement when you're ready.
+For shell agents, pass caller metadata on each command when available:
 
-### Supported frameworks
+```bash
+rivet open --project /path/to/app --caller-agent cursor --caller-model <model> --caller-session <session-id>
+```
+
+## How It Works
+
+1. `rivet open` starts or attaches to the local Rivet editor server for a project. It can attach to an existing dev server or start the app's standard `dev`, `start`, or `serve` script when possible.
+2. The editor shows your app and variant previews in the browser. Agents use `rivet variants ...` and `rivet changes ...` to enqueue work.
+3. Use `rivet wait`, `rivet status`, or `rivet status --watch` to observe progress.
+4. Commit the chosen variant with `rivet variants commit <variantId>` or use the editor to keep refining.
+
+If Rivet reports pull mode, staged work can be drained with `rivet changes pull --project <path>`, applied by the agent, then acknowledged with `rivet changes pull --project <path> --ack <leaseId>`.
+
+## Supported Frameworks
 
 - Next.js
 - Vite
 - Create React App
 - Remix
 - SvelteKit
-
-Your dev server needs to be running before opening Rivet. Your agent will give you the start command if it isn't.
+- Static HTML
 
 ## Requirements
 
-- Node.js 18+
-- A running local dev server (Vite, Next.js, etc.)
-- Claude Code, Cursor, or another MCP-compatible agent
+- Node.js 24+
+- A shell-capable coding agent for agent-driven flows
+- Git for variant branch/history features
 
 ## License
 
-MIT
+GPL-3.0-or-later

package/README.npm.md

@@ -1,60 +1,84 @@
 # Rivet
 
-Rivet helps you explore multiple design directions for your web app. It generates parallel variants you can compare side by side, refine with precision, and share or implement — all from your coding agent.
+Rivet helps you explore multiple design directions for your web app. It opens a local visual editor, generates parallel variants, lets you refine with comments, and can send the chosen direction back into your project.
 
-## How it works
+## Install
 
-Rivet runs as an MCP server alongside your coding agent (Claude Code, Cursor, etc.).
+Run the installer from the project where you want AI agents to use Rivet:
 
-1. **Start from your agent.** Use `/rivet` in Claude Code, or tell your agent "Use Rivet variants" or "Explore with Rivet" along with your design request.
-2. **Connect design references** (optional). Click **Connect design references** in the editor to link your Pinterest or Are.na account. Include relevant pins or boards and Rivet will extract design context from them to inform the variants it generates.
-3. **Refine with the comment tool.** Select any part of the UI and use the comment tool to make more precise variants of that section, or leave comments describing what you'd like to change within a variant.
-4. **Share or implement.** When you're happy, click the **Share** button to get a shareable link you can send to a collaborator — or share it back to your coding agent to implement the chosen direction.
+```bash
+npx -y rivet-design@latest install
+```
 
-## Install
+The installer writes CLI usage guidance and command allowlists for detected shell-capable agents such as Claude Code, Cursor, and Codex. After installing, start a new agent session and say "Open Rivet" or "/rivet".
 
-**Option 1 — CLI (recommended)**
+You can also run Rivet directly without a global install:
 
 ```bash
-claude mcp add --transport stdio --scope user rivet -- npx -y rivet-design@latest mcp --editor claude
+npx -y rivet-design@latest open --project /path/to/app
 ```
 
-**Option 2 — Run Rivet's installer** (adds Rivet globally via Claude Code CLI)
+If installed globally, the package exposes the `rivet` binary:
 
 ```bash
-npx rivet-design install
+rivet open --project /path/to/app
 ```
 
-No global install required. `npx` pulls the latest version each time.
+## CLI Agent Commands
 
-## Usage
+Rivet's agent-facing commands print one JSON envelope on stdout, write progress to stderr, and do not prompt for input.
 
-Once installed, tell your agent what you want to explore:
+For interactive user workflows, run `rivet open` without `--no-browser` so the Rivet UI opens in the browser. Use `--no-browser` only for headless/background automation, CI/e2e checks, or when the user explicitly asks not to open a browser; in those cases, report the returned `editorUrl`.
 
+```bash
+rivet open --project /path/to/app
+rivet status --project /path/to/app
+rivet variants start --project /path/to/app --instruction "try three hero layouts" --count 3
+rivet wait <workId> --project /path/to/app --timeout 120
+rivet variants list --project /path/to/app
+rivet variants commit <variantId> --project /path/to/app
+rivet changes request --project /path/to/app --instruction "make the header coral" --element "#header"
+rivet changes pull --project /path/to/app
+rivet stop --project /path/to/app
 ```
-"Use Rivet variants to explore hero section designs"
-"Explore with Rivet — show me options for the navigation"
-"/rivet redesign the pricing page"
+
+For a fresh project, create or use an empty directory, open Rivet there, then start variants with `--fresh`:
+
+```bash
+rivet open --project /path/to/new-app
+rivet variants start --project /path/to/new-app --fresh --instruction "build a SaaS landing page" --count 3
 ```
 
-Your agent will open Rivet, generate parallel design directions, and let you compare them side by side in the browser. Use the comment tool to refine, connect Pinterest or Are.na boards for design context, and share or implement when you're ready.
+For shell agents, pass caller metadata on each command when available:
 
-### Supported frameworks
+```bash
+rivet open --project /path/to/app --caller-agent cursor --caller-model <model> --caller-session <session-id>
+```
+
+## How It Works
+
+1. `rivet open` starts or attaches to the local Rivet editor server for a project. It can attach to an existing dev server or start the app's standard `dev`, `start`, or `serve` script when possible.
+2. The editor shows your app and variant previews in the browser. Agents use `rivet variants ...` and `rivet changes ...` to enqueue work.
+3. Use `rivet wait`, `rivet status`, or `rivet status --watch` to observe progress.
+4. Commit the chosen variant with `rivet variants commit <variantId>` or use the editor to keep refining.
+
+If Rivet reports pull mode, staged work can be drained with `rivet changes pull --project <path>`, applied by the agent, then acknowledged with `rivet changes pull --project <path> --ack <leaseId>`.
+
+## Supported Frameworks
 
 - Next.js
 - Vite
 - Create React App
 - Remix
 - SvelteKit
-
-Your dev server needs to be running before opening Rivet. Your agent will give you the start command if it isn't.
+- Static HTML
 
 ## Requirements
 
-- Node.js 18+
-- A running local dev server (Vite, Next.js, etc.)
-- Claude Code, Cursor, or another MCP-compatible agent
+- Node.js 24+
+- A shell-capable coding agent for agent-driven flows
+- Git for variant branch/history features
 
 ## License
 
-MIT
+GPL-3.0-or-later

package/bin/rivet.js

@@ -22,20 +22,6 @@ if (!process.env.NODE_ENV) {
   }
 }
 
-// In MCP mode, stdout is reserved for the JSON-RPC protocol stream. The dist
-// logger's redirectLogsToStderr() runs inside startMCPServer, but module-level
-// log calls fire at import time — before that hook. Patch console output here
-// so those early lines (and any future ones) go to stderr instead of corrupting
-// the protocol stream.
-if (process.argv.includes('mcp')) {
-  console.log = console.error.bind(console);
-  console.info = console.error.bind(console);
-  console.warn = console.error.bind(console);
-}
-
-// Import the compiled main function
-const { main } = require('../dist/index.js');
-
 // Handle uncaught exceptions gracefully
 process.on('uncaughtException', (error) => {
   console.error('Uncaught exception:', error);
@@ -47,14 +33,43 @@ process.on('unhandledRejection', (reason, promise) => {
   process.exit(1);
 });
 
-// Handle Ctrl+C gracefully
-process.on('SIGINT', () => {
-  console.log('\n👋 Goodbye!');
-  process.exit(0);
-});
+// Control-plane subcommands route to the lean entry and skip dist/index.js
+// entirely: its static import graph is the dominant fixed cost of an
+// invocation and none of it is needed to emit an envelope. Any resolution
+// failure falls back to the full CLI.
+const args = process.argv.slice(2);
+let controlPlane = null;
+try {
+  const { isCliControlCommand } = require('../dist/cli/commandNames.js');
+  if (isCliControlCommand(args[0])) {
+    controlPlane = require('../dist/cli/entry.js');
+  }
+} catch {
+  controlPlane = null;
+}
 
-// Start the CLI
-main().catch((error) => {
-  console.error('CLI error:', error);
-  process.exit(1);
-});
+if (controlPlane) {
+  // stdout is reserved for JSON envelopes (and MCP frames under
+  // `rivet mcp serve`), so no Ctrl+C goodbye on this path.
+  process.on('SIGINT', () => {
+    process.exit(0);
+  });
+  controlPlane.runControlPlane(args).catch((error) => {
+    console.error('CLI error:', error);
+    process.exit(1);
+  });
+} else {
+  // Handle Ctrl+C gracefully
+  process.on('SIGINT', () => {
+    console.log('\n👋 Goodbye!');
+    process.exit(0);
+  });
+
+  const { main } = require('../dist/index.js');
+
+  // Start the CLI
+  main().catch((error) => {
+    console.error('CLI error:', error);
+    process.exit(1);
+  });
+}

package/dist/{mcp/agent-variants → agent-variants}/SessionStore.d.ts

@@ -1,4 +1,4 @@
-import { type Brief, type ActiveVariantSnapshot, type LeasedWorkItemDescriptor, type ProjectContext, type SourcePlanActionOption, type SourcePlanArtifact, type Stage, type StaticPreviewTargetElement, type Target, type TerminalSummary, type VariantContextBinding, type VariantContextBundle, type VariantQaResult, type VariantPickEnvelope, type WorkItem, type WorkItemStatus } from './contracts';
+import { type Brief, type ActiveVariantSnapshot, type LeasedWorkItemDescriptor, type ProjectContext, type SourcePlanActionOption, type SourcePlanArtifact, type Stage, type StartVariantsBriefContent, type StaticPreviewTargetElement, type Target, type TerminalSummary, type VariantContextBinding, type VariantContextBundle, type VariantQaResult, type VariantPickEnvelope, type WorkItem, type WorkItemStatus } from './contracts';
 /** TTL for a lease on a code_gen work item. Bumped to 20min after a timing
  *  audit found first-variant single-round code-gen routinely runs 540–950s
  *  (4+ Task sub-agents in parallel), so the previous 10min cap was the most
@@ -185,6 +185,7 @@ export declare class SessionStore {
         sourceVariantId: string;
         instruction: string;
         count: number;
+        briefs?: StartVariantsBriefContent[];
         currentHtml?: string;
         targetElement?: StaticPreviewTargetElement;
         requestId?: string;
@@ -199,12 +200,20 @@ export declare class SessionStore {
      * batch; the orchestrator provisions a worktree per item and runs each
      * through the normal completion/preview pipeline.
      *
+     * With `sourceVariantId`, forks a succeeded code_gen parent: each new item
+     * is stamped with the source id (+ sourceLabel/sourceBody) so the
+     * orchestrator seeds its worktree from the parent's tree rather than git
+     * HEAD / Original. Backs code_gen "Vary" targeting a parent variant.
+     *
      * Reopens the session to `work_items_ready` so the appended pending work is
      * visible and drives the stage back through generation to ready/degraded.
      */
-    appendExistingCodeGenVariants(args: {
+    appendCodeGenVariants(args: {
         sessionId: string;
         briefs: Brief[];
+        /** Fork parent: seed each new variant from this succeeded code_gen
+         *  variant's worktree instead of the base tree. */
+        sourceVariantId?: string;
         /** Run label (1–2 word intent) derived from THIS batch's instruction.
          *  Stamped onto each appended work item so the variant table tags the new
          *  rows with their OWN batch's label instead of inheriting the session's
@@ -220,23 +229,6 @@ export declare class SessionStore {
         createdWorkItemIds: string[];
         briefs: Brief[];
     };
-    /**
-     * Fork a succeeded code_gen variant into N NEW sibling variants. Each forked
-     * item is seeded from the source variant's worktree (not git HEAD / Original)
-     * and carries `sourceVariantId` so the orchestrator can copy the parent's
-     * tree when provisioning. Backs code_gen "Vary" when the UI targets a parent
-     * variant with `variantRequest.count > 0`.
-     */
-    createForkedCodeGenWorkItems(args: {
-        sessionId: string;
-        sourceVariantId: string;
-        briefs: Brief[];
-        runLabel?: string;
-        variantContext?: VariantContextBundle;
-    }): {
-        createdWorkItemIds: string[];
-        briefs: Brief[];
-    };
     /**
      * Adopt a PAST variant (from a prior session's persisted history) into THIS
      * active session as a first-class, already-`succeeded` `static_preview`
@@ -429,6 +421,7 @@ export declare class SessionStore {
     };
     getSummary(sessionId: string): TerminalSummary;
     getVariants(sessionId: string): ActiveVariantSnapshot[];
+    getHostWork(sessionId: string): import('./contracts').HostVariantWorkItemSnapshot[];
     getVariantPick(sessionId: string): VariantPickEnvelope | undefined;
     /** Validates a report lease without mutating the work item. */
     validateReportLease(args: {
@@ -439,7 +432,7 @@ export declare class SessionStore {
     }): void;
     hasSession(sessionId: string): boolean;
     /** Read a work item's input blob — used by the orchestrator to recover
-     *  briefLabel / target / projectContext when auto-enqueueing the diff. */
+     *  briefLabel / target / projectContext when committing the output. */
     getWorkItemInput(sessionId: string, workItemId: string): unknown;
     getWorkItemOutput(sessionId: string, workItemId: string): unknown;
     /** Replaces a completed work item's output after server-side post-processing. */

package/dist/agent-variants/SessionStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SessionStore.d.ts","sourceRoot":"","sources":["../../src/agent-variants/SessionStore.ts"],"names":[],"mappings":"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"}

package/dist/{mcp/agent-variants → agent-variants}/SessionStore.js

@@ -992,7 +992,8 @@ class SessionStore {
         const sourceInput = source.input;
         const seedHtml = args.currentHtml ??
             source.output?.html;
-        const total = Math.min(Math.max(Math.trunc(args.count) || 1, 1), contracts_1.VARIANT_COUNT_MAX);
+        const briefs = args.briefs?.map(briefContent_1.normalizeBriefContent);
+        const total = Math.min(briefs?.length ?? Math.max(Math.trunc(args.count) || 1, 1), contracts_1.VARIANT_COUNT_MAX);
         // Label/describe forked variants by the CHANGE requested (the Vary
         // instruction), not the source brief — otherwise every run on the same
         // variant reads identically ("<source> · variation N") and concurrent runs
@@ -1004,6 +1005,7 @@ class SessionStore {
         const LABEL_MAX = 48;
         const created = [];
         for (let i = 0; i < total; i++) {
+            const brief = briefs?.[i];
             const suffix = total > 1 ? ` · ${i + 1}` : '';
             const labelBase = prettyInstruction.length > LABEL_MAX - suffix.length
                 ? `${prettyInstruction.slice(0, LABEL_MAX - suffix.length - 1)}…`
@@ -1016,10 +1018,13 @@ class SessionStore {
                 dependsOn: [],
                 input: {
                     briefId: `${sourceInput.briefId ?? 'v'}-vary-${(0, crypto_1.randomUUID)().slice(0, 8)}`,
-                    // Provisional name/description (the change) shown while generating;
-                    // the agent reports a synthesized title/description on completion.
-                    briefLabel: `${labelBase}${suffix}`,
-                    briefBody: prettyInstruction,
+                    // Agent-authored metadata is visible from the start. Human-direct
+                    // fallback metadata can still be replaced on completion.
+                    briefLabel: brief?.label ?? `${labelBase}${suffix}`,
+                    briefBody: brief?.body ?? prettyInstruction,
+                    ...(brief?.visualReferenceUrl
+                        ? { visualReferenceUrl: brief.visualReferenceUrl }
+                        : {}),
                     instruction: args.instruction,
                     sourceVariantId: args.sourceVariantId,
                     // Parent identity, so the agent can synthesize a name/description that
@@ -1058,11 +1063,23 @@ class SessionStore {
      * batch; the orchestrator provisions a worktree per item and runs each
      * through the normal completion/preview pipeline.
      *
+     * With `sourceVariantId`, forks a succeeded code_gen parent: each new item
+     * is stamped with the source id (+ sourceLabel/sourceBody) so the
+     * orchestrator seeds its worktree from the parent's tree rather than git
+     * HEAD / Original. Backs code_gen "Vary" targeting a parent variant.
+     *
      * Reopens the session to `work_items_ready` so the appended pending work is
      * visible and drives the stage back through generation to ready/degraded.
      */
-    appendExistingCodeGenVariants(args) {
+    appendCodeGenVariants(args) {
         const session = this.requireSession(args.sessionId);
+        const source = args.sourceVariantId
+            ? this.requireWorkItem(session, args.sourceVariantId)
+            : null;
+        if (source &&
+            (source.kind !== 'code_gen' || source.status !== 'succeeded')) {
+            throw new errors_1.AgentVariantsError('VARIANT_NOT_EDITABLE', 'Only completed code_gen variants can be varied');
+        }
         if (session.projectContext.kind !== 'existing') {
             throw new errors_1.AgentVariantsError('INVALID_STAGE_ACTION', 'Only existing-project sessions can append code_gen variants');
         }
@@ -1075,81 +1092,19 @@ class SessionStore {
         if (args.briefs.length === 0) {
             throw new errors_1.AgentVariantsError('MISSING_REQUIRED_INPUT', 'At least one brief is required to append variants');
         }
-        const createdWorkItemIds = [];
-        for (const brief of args.briefs) {
-            const context = resolveVariantWorkItemContext({
-                bundle: args.variantContext ?? session.projectContext.variantContext,
-                projectContext: session.projectContext,
-                brief,
-                slotIndex: session.briefs.length,
+        if (source) {
+            const activeRefinement = [...session.workItems.values()].find((item) => {
+                if (item.kind !== 'refine_variant')
+                    return false;
+                const input = item.input;
+                return (input.variantId === args.sourceVariantId &&
+                    (item.status === 'pending' || item.status === 'running'));
             });
-            const visualRef = brief.visualReferenceUrl
-                ? { visualReferenceUrl: brief.visualReferenceUrl }
-                : {};
-            const item = {
-                id: (0, crypto_1.randomUUID)(),
-                kind: 'code_gen',
-                status: 'pending',
-                attempt: 0,
-                dependsOn: [],
-                input: {
-                    briefId: brief.briefId,
-                    briefLabel: brief.label,
-                    briefBody: brief.body,
-                    ...visualRef,
-                    ...(args.runLabel ? { runLabel: args.runLabel } : {}),
-                    target: session.target,
-                    projectContext: session.projectContext,
-                    ...(context ? { context } : {}),
-                },
-                acceptedReports: [],
-            };
-            session.workItems.set(item.id, item);
-            // Surface the newest Vary batch at the top of the Directions list, matching
-            // the static-preview fork ordering.
-            session.workItemOrder.unshift(item.id);
-            session.briefs.push(brief);
-            createdWorkItemIds.push(item.id);
-        }
-        session.stage = 'work_items_ready';
-        return { createdWorkItemIds, briefs: args.briefs };
-    }
-    /**
-     * Fork a succeeded code_gen variant into N NEW sibling variants. Each forked
-     * item is seeded from the source variant's worktree (not git HEAD / Original)
-     * and carries `sourceVariantId` so the orchestrator can copy the parent's
-     * tree when provisioning. Backs code_gen "Vary" when the UI targets a parent
-     * variant with `variantRequest.count > 0`.
-     */
-    createForkedCodeGenWorkItems(args) {
-        const session = this.requireSession(args.sessionId);
-        const source = this.requireWorkItem(session, args.sourceVariantId);
-        if (source.kind !== 'code_gen' || source.status !== 'succeeded') {
-            throw new errors_1.AgentVariantsError('VARIANT_NOT_EDITABLE', 'Only completed code_gen variants can be varied');
-        }
-        if (session.projectContext.kind !== 'existing') {
-            throw new errors_1.AgentVariantsError('INVALID_STAGE_ACTION', 'Only existing-project sessions can fork code_gen variants');
-        }
-        if (session.variantPick) {
-            throw new errors_1.AgentVariantsError('PENDING_CHANGE_CONFLICT', 'Cannot vary a variant after one has already been committed');
-        }
-        if (session.stage === 'cancelled' || session.stage === 'failed') {
-            throw new errors_1.AgentVariantsError('INVALID_STAGE_ACTION', `Cannot fork variants in a ${session.stage} session`);
-        }
-        if (args.briefs.length === 0) {
-            throw new errors_1.AgentVariantsError('MISSING_REQUIRED_INPUT', 'At least one brief is required to fork variants');
-        }
-        const activeRefinement = [...session.workItems.values()].find((item) => {
-            if (item.kind !== 'refine_variant')
-                return false;
-            const input = item.input;
-            return (input.variantId === args.sourceVariantId &&
-                (item.status === 'pending' || item.status === 'running'));
-        });
-        if (activeRefinement) {
-            throw new errors_1.AgentVariantsError('PENDING_CHANGE_CONFLICT', 'Cannot vary a variant while an in-place refinement is pending or running');
+            if (activeRefinement) {
+                throw new errors_1.AgentVariantsError('PENDING_CHANGE_CONFLICT', 'Cannot vary a variant while an in-place refinement is pending or running');
+            }
         }
-        const sourceInput = source.input;
+        const sourceInput = (source?.input ?? {});
         const createdWorkItemIds = [];
         for (const brief of args.briefs) {
             const context = resolveVariantWorkItemContext({
@@ -1173,11 +1128,15 @@ class SessionStore {
                     briefBody: brief.body,
                     ...visualRef,
                     ...(args.runLabel ? { runLabel: args.runLabel } : {}),
-                    sourceVariantId: args.sourceVariantId,
-                    ...(sourceInput.briefLabel
+                    ...(args.sourceVariantId
+                        ? { sourceVariantId: args.sourceVariantId }
+                        : {}),
+                    ...(source && sourceInput.briefLabel
                         ? { sourceLabel: sourceInput.briefLabel }
                         : {}),
-                    ...(sourceInput.briefBody ? { sourceBody: sourceInput.briefBody } : {}),
+                    ...(source && sourceInput.briefBody
+                        ? { sourceBody: sourceInput.briefBody }
+                        : {}),
                     target: session.target,
                     projectContext: session.projectContext,
                     ...(context ? { context } : {}),
@@ -1185,6 +1144,8 @@ class SessionStore {
                 acceptedReports: [],
             };
             session.workItems.set(item.id, item);
+            // Surface the newest Vary batch at the top of the Directions list, matching
+            // the static-preview fork ordering.
             session.workItemOrder.unshift(item.id);
             session.briefs.push(brief);
             createdWorkItemIds.push(item.id);
@@ -1539,7 +1500,7 @@ class SessionStore {
             sessionStage: session.stage,
         };
     }
-    // --- Variant pick handoff (queues to pending-changes adapter) -----------
+    // --- Variant pick handoff ----------------------------------------------
     recordVariantPick(args) {
         const session = this.requireSession(args.sessionId);
         if (!['ready', 'degraded'].includes(session.stage)) {
@@ -1582,6 +1543,30 @@ class SessionStore {
         const session = this.requireSession(sessionId);
         return this.variantsOf(session);
     }
+    getHostWork(sessionId) {
+        const session = this.requireSession(sessionId);
+        return [...session.workItems.values()]
+            .filter((item) => item.lease && item.status === 'running')
+            .map((item) => {
+            const input = item.input && typeof item.input === 'object'
+                ? item.input
+                : {};
+            const variantId = item.kind === 'refine_variant' && typeof input.variantId === 'string'
+                ? input.variantId
+                : item.id;
+            return {
+                workId: item.id,
+                variantId,
+                kind: item.kind,
+                status: item.status,
+                leaseId: item.lease.leaseId,
+                attempt: item.lease.attempt,
+                leaseExpiresAt: item.lease.leaseExpiresAt,
+                input: item.input,
+                outputSchema: outputSchemaFor(item.kind),
+            };
+        });
+    }
     getVariantPick(sessionId) {
         return this.requireSession(sessionId).variantPick;
     }
@@ -1595,7 +1580,7 @@ class SessionStore {
         return this.sessions.has(sessionId);
     }
     /** Read a work item's input blob — used by the orchestrator to recover
-     *  briefLabel / target / projectContext when auto-enqueueing the diff. */
+     *  briefLabel / target / projectContext when committing the output. */
     getWorkItemInput(sessionId, workItemId) {
         const session = this.requireSession(sessionId);
         const item = this.requireWorkItem(session, workItemId);
@@ -1894,6 +1879,11 @@ class SessionStore {
                 briefId: input.briefId ?? '',
                 label: input.briefLabel ?? 'Variant',
                 status: item.status,
+                // The filter above admits only code_gen / static_preview items
+                // (incl. adopted + forked static previews). Clients route Vary/apply
+                // on this — never on the display preview kind, which diverges for
+                // existing-project code_gen variants materialized as static HTML.
+                workItemKind: item.kind,
                 createdAt: new Date(session.createdAt).toISOString(),
                 // Prefer the per-item label stamped by an appended Vary batch; the
                 // session-level fallback is correct only for the first batch (its