rivet-design 0.17.4 → 0.18.0

package/dist/agent-variants/SessionStore.js

@@ -1,15 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SessionStore = exports.buildImageRefs = exports.SOURCE_PLAN_ACTION_OPTIONS = exports.SOURCE_PLAN_OUTPUT_SCHEMA = exports.SCAFFOLD_LEASE_TTL_MS = exports.DEFAULT_LEASE_TTL_MS = void 0;
+const variant_reference_1 = require("../types/variant-reference");
 const crypto_1 = require("crypto");
 const errors_1 = require("./errors");
 const contracts_1 = require("./contracts");
 const briefContent_1 = require("./briefContent");
 const runLabel_1 = require("./runLabel");
 const runPlan_1 = require("./runPlan");
-/** The variant card subtitle must stay ≤ 10 words (matches the UI's
- *  summarizeVariantSubtitle). briefBody can be longer because it also feeds
- *  code_gen, so cap only the UI-facing description copy sent over the wire. */
 const MAX_SUBTITLE_WORDS = 10;
 const MAX_RELEVANT_FILES = 12;
 const capSubtitleWords = (text) => {
@@ -19,25 +17,12 @@ const capSubtitleWords = (text) => {
         : `${words.slice(0, MAX_SUBTITLE_WORDS).join(' ')}…`;
 };
 const mergeRelevantFiles = (...groups) => Array.from(new Set(groups.flatMap((group) => group ?? []).filter(Boolean))).slice(0, MAX_RELEVANT_FILES);
-/** 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
- *  frequently binding lease and caused recoverable LEASE_EXPIRED churn. The
- *  recovery path (re-lease + re-report) works, but the re-lease delay before
- *  the chip's pills lit up was noticeable. */
 exports.DEFAULT_LEASE_TTL_MS = 20 * 60 * 1000;
-/** TTL for a lease on a scaffold_base work item. Longer than code_gen because
- *  npm/yarn create can be slow on a cold cache. Raised to 30min alongside the
- *  code_gen bump; scaffold timing has never bound, but a longer lease is safe. */
 exports.SCAFFOLD_LEASE_TTL_MS = 30 * 60 * 1000;
 const SYSTEM_CLOCK = { now: () => Date.now() };
-/** True when a work item is a past variant adopted into the active session
- *  (see {@link SessionStore.appendAdoptedStaticVariant}). Adopted variants are
- *  surfaced as session members but excluded from generation accounting. */
 function isAdoptedVariant(item) {
     return Boolean(item.input.adoptedFrom);
 }
-/** True when a static preview is a Vary sibling forked from another variant. */
 function isForkedStaticPreviewVariant(item) {
     return (item.kind === 'static_preview' &&
         Boolean(item.input.sourceVariantId));
@@ -50,7 +35,6 @@ function leaseTtlForKind(kind) {
         ? exports.SCAFFOLD_LEASE_TTL_MS
         : exports.DEFAULT_LEASE_TTL_MS;
 }
-/** Describes the work item contract returned to an agent lease holder. */
 function descriptorFor(item) {
     return {
         id: item.id,
@@ -83,7 +67,6 @@ exports.SOURCE_PLAN_ACTION_OPTIONS = [
         instructions: 'Inspect interaction references natively and use the Rivet Describe Motion protocol to produce motion_guidance metadata.',
     },
 ];
-/** Returns the completion payload shape required for each leased work item. */
 function outputSchemaFor(kind) {
     switch (kind) {
         case 'source_plan':
@@ -147,19 +130,10 @@ const briefWorkItemContext = (projectContext) => {
         },
     };
 };
-// Source-artifact kinds that represent agent-described attached images.
-// These need their own DESIGN.md slot in the source_plan output, alongside
-// any URL-keyed entries. `siteBrief` / `urlText` are pasted text — they
-// feed SOURCE_CONTEXT only and do NOT get a DESIGN.md.
 const IMAGE_ARTIFACT_KINDS = new Set([
     'visualBrief',
     'screenshotNotes',
 ]);
-/**
- * Stable per-session ref for image-derived design sources. Indexed over the
- * filtered list of image-kind artifacts so the ref survives reordering of
- * text-only artifacts in the same `sourceArtifacts` array.
- */
 const buildImageRefs = (artifacts) => {
     if (!artifacts)
         return [];
@@ -172,12 +146,6 @@ const buildImageRefs = (artifacts) => {
     return refs;
 };
 exports.buildImageRefs = buildImageRefs;
-/**
- * Source-grounded fresh sessions require a single `source_plan` planning hop
- * before briefs. The hop fires when Rivet has captured a read-only user
- * context bundle (the sole source-intake surface). The source-plan agent
- * inspects raw context and reports actions plus metadata.
- */
 const requiresSourcePlan = (projectContext) => projectContext.kind === 'fresh' && Boolean(projectContext.variantContext);
 const listSection = (title, items) => {
     if (items.length === 0)
@@ -185,9 +153,6 @@ const listSection = (title, items) => {
     return [`## ${title}`, '', ...items.map((item) => `- ${item}`), ''];
 };
 const hasSharedSource = (sourceIds, candidateSourceIds) => candidateSourceIds.some((sourceId) => sourceIds.includes(sourceId));
-/**
- * Formats motion metadata that applies to the same raw sources as the design metadata.
- */
 const buildMotionGuidanceMarkdown = (sourceIds, metadata) => {
     const matchingMotion = metadata.filter((entry) => entry.kind === 'motion_guidance' &&
         hasSharedSource(sourceIds, entry.sourceIds));
@@ -208,9 +173,6 @@ const buildMotionGuidanceMarkdown = (sourceIds, metadata) => {
     }
     return lines;
 };
-/**
- * Converts design-system metadata into the markdown artifact variant agents consume.
- */
 const buildDesignMarkdownFromMetadata = (entry, metadata) => {
     if (entry.data.designMarkdown) {
         return entry.data.designMarkdown;
@@ -231,9 +193,6 @@ const buildDesignMarkdownFromMetadata = (entry, metadata) => {
     ];
     return `${lines.join('\n').trim()}\n`;
 };
-/**
- * Builds design-context entries from action metadata when the report does not provide them directly.
- */
 const designContextsFromActionMetadata = (metadata) => {
     if (!metadata)
         return [];
@@ -273,25 +232,13 @@ const METADATA_KIND_BY_ACTION_KIND = {
     extract_design_system: 'design_system',
     describe_motion: 'motion_guidance',
 };
-/**
- * Validates the reported source plan's action/metadata invariants:
- *  - metadata is produced BY actions, so metadata reported with zero actions
- *    is rejected (it would otherwise build DESIGN.md from an orphaned payload);
- *  - every metadata entry references real raw-context sources;
- *  - every reported action produces the metadata kind it claims to.
- */
 const validateActionMetadataOutputs = (args) => {
     const actions = args.sourcePlan.actions;
     const metadata = args.sourcePlan.metadata;
-    // Metadata is produced BY actions. A plan that reports metadata with no
-    // actions has nothing to produce it — reject rather than silently building
-    // design context from an orphaned, otherwise-unvalidated payload.
     if (actions.length === 0 && metadata.length > 0) {
         throw new errors_1.AgentVariantsError('SOURCE_CONTEXT_INVALID', 'source_plan reported metadata without any actions; metadata must be produced by a reported action');
     }
     const sourceIds = new Set(args.bundle?.userContext.map((source) => source.id) ?? []);
-    // Validate metadata sourceIds independently of `actions` so an empty action
-    // list can never skip the check wholesale.
     for (const entry of metadata) {
         const unknownSourceIds = entry.sourceIds.filter((sourceId) => sourceIds.size > 0 && !sourceIds.has(sourceId));
         if (unknownSourceIds.length > 0) {
@@ -366,6 +313,7 @@ const resolveVariantWorkItemContext = (args) => {
         contextBundlePath: args.bundle.contextBundlePath,
         userContext,
         rivetMetadata,
+        references: (0, variant_reference_1.mergeVariantReferences)(...userContext.map((source) => 'references' in source ? source.references : undefined)),
         ...(args.bundle.contextAssets?.length
             ? { contextAssets: args.bundle.contextAssets }
             : {}),
@@ -382,7 +330,6 @@ class SessionStore {
     constructor(clock = SYSTEM_CLOCK) {
         this.clock = clock;
     }
-    // --- Lifecycle ----------------------------------------------------------
     propose(args) {
         const sessionId = args.sessionId ?? (0, crypto_1.randomUUID)();
         if (this.sessions.has(sessionId)) {
@@ -457,8 +404,6 @@ class SessionStore {
     }
     reportBriefs(args) {
         const session = this.requireSession(args.sessionId);
-        // Idempotent replay: accept regardless of current stage so retries after a
-        // stage advance still return the same response without mutating state.
         const fp = fingerprint([
             'reportBriefs',
             args.sessionId,
@@ -522,8 +467,6 @@ class SessionStore {
         }
         this.validatePlanningReport(item, args.leaseId, args.attempt);
         const { executionPlan, actions, metadata, bindings } = args.sourcePlan;
-        // Canonical path: every reported action must produce its matching metadata
-        // kind, and action sourceIds must reference real raw-context sources.
         validateActionMetadataOutputs({
             bundle: session.projectContext.kind === 'fresh'
                 ? session.projectContext.variantContext
@@ -531,13 +474,6 @@ class SessionStore {
             sourcePlan: args.sourcePlan,
         });
         if (session.projectContext.kind === 'fresh') {
-            // Derive DESIGN.md context directly from `design_system` action
-            // metadata. Each entry uses explicit `designMarkdown` when present, or
-            // is synthesized from the structured observations. Brief fan-out
-            // (provisionFreshWorktrees) reads slot [min(briefIndex, length-1)] with
-            // a slot-0 fallback, so a single design system ships one shared markdown
-            // while multiple design systems land on deterministic slots in report
-            // order.
             const projectDesignContexts = designContextsFromActionMetadata(metadata);
             session.projectContext = {
                 ...session.projectContext,
@@ -603,25 +539,12 @@ class SessionStore {
         const executionPlan = session.projectContext.kind === 'fresh'
             ? session.projectContext.executionPlan
             : undefined;
-        // Surface an agent-flagged clarification as a hard blocker rather than
-        // silently downgrading to a static preview. The agent sets
-        // `userQuestion` when it cannot decide between static_preview and
-        // vite_app without more info from the user.
         if (executionPlan?.userQuestion) {
             throw new errors_1.AgentVariantsError('MISSING_REQUIRED_INPUT', executionPlan.userQuestion);
         }
-        // Resolve the canonical run plan once. The topology decision below (and
-        // the orchestrator's provision/commit decisions later) read off this
-        // single source of truth rather than re-deriving from `kind` /
-        // `executionPlan.mode`. Fresh sessions default to static_preview when no
-        // plan was reported (source-less zero-to-one); source-grounded sessions
-        // carry an executionPlan from `report_source_plan`.
         const policy = (0, runPlan_1.resolveRunPlanPolicy)(session.projectContext);
         const wantsStaticPreview = policy.topology === 'static_preview';
         const codeGenIds = [];
-        // For generated Vite apps, code_gen items depend on a single scaffold_base
-        // item so the orchestrator can do the Vite skeleton + npm install + asset
-        // copy before the agent leases the code_gen.
         let scaffoldBaseId;
         if (policy.needsScaffoldBase) {
             scaffoldBaseId = (0, crypto_1.randomUUID)();
@@ -643,15 +566,10 @@ class SessionStore {
             if (briefIndex === -1)
                 return;
             const brief = session.briefs[briefIndex];
-            // D-VR2: Plumb the optional per-brief visualReferenceUrl into the
-            // resulting work-item input. Omitted (not nulled) when absent so the
-            // shape stays backward-compatible for callers that destructure.
             const visualRef = brief.visualReferenceUrl
                 ? { visualReferenceUrl: brief.visualReferenceUrl }
                 : {};
             const context = resolveVariantWorkItemContext({
-                // Existing-project sessions also carry a server-owned context bundle
-                // (no source_plan stage), so thread it for both kinds.
                 bundle: session.projectContext.variantContext,
                 projectContext: session.projectContext,
                 brief,
@@ -664,8 +582,6 @@ class SessionStore {
                 ? freshDesignContext[Math.min(briefIndex, freshDesignContext.length - 1)]
                 : undefined;
             if (wantsStaticPreview) {
-                // Generated + static_preview: HTML is the deliverable. No scaffold or
-                // code_gen — the static_preview item is leased directly.
                 const staticPreviewItem = {
                     id: (0, crypto_1.randomUUID)(),
                     kind: 'static_preview',
@@ -685,7 +601,7 @@ class SessionStore {
                         ...(session.fidelity ? { fidelity: session.fidelity } : {}),
                         projectContext: session.projectContext,
                         ...(designContextEntry ? { designContextEntry } : {}),
-                        ...(context ? { context } : {}),
+                        ...(context ? { context, references: context.references } : {}),
                     },
                     acceptedReports: [],
                 };
@@ -693,15 +609,6 @@ class SessionStore {
                 session.workItemOrder.push(staticPreviewItem.id);
             }
             else {
-                // Existing project OR fresh+vite_app: code_gen against a worktree.
-                // Fresh+vite_app additionally depends on scaffold_base so the agent
-                // doesn't lease code_gen before the Vite skeleton lands.
-                //
-                // Per-slot designContextEntry is read by provisionFreshWorktrees to
-                // decide what DESIGN.md to write per variant. Falls back to slot 0
-                // when the session has fewer designContext entries than variants
-                // (the common case after report_source_plan ships one shared
-                // markdown).
                 const codeGenItem = {
                     id: (0, crypto_1.randomUUID)(),
                     kind: 'code_gen',
@@ -722,7 +629,7 @@ class SessionStore {
                         ...(session.fidelity ? { fidelity: session.fidelity } : {}),
                         projectContext: session.projectContext,
                         ...(designContextEntry ? { designContextEntry } : {}),
-                        ...(context ? { context } : {}),
+                        ...(context ? { context, references: context.references } : {}),
                     },
                     acceptedReports: [],
                 };
@@ -739,7 +646,6 @@ class SessionStore {
             scaffoldBaseWorkItemId: scaffoldBaseId,
         };
     }
-    // --- Lease management ---------------------------------------------------
     requestWork(args) {
         const session = this.requireSession(args.sessionId);
         this.assertStage(session, [
@@ -749,9 +655,6 @@ class SessionStore {
         ]);
         this.expireStaleLeases(session);
         let leasable = this.leasableItems(session);
-        // Targeted lease: restrict to a single named item so callers that just
-        // enqueued a specific work item (e.g. refineVariant) can't accidentally
-        // lease an unrelated leasable item that happens to sort earlier.
         if (args.workItemId !== undefined) {
             const target = leasable.find((item) => item.id === args.workItemId);
             if (!target) {
@@ -760,19 +663,12 @@ class SessionStore {
             leasable = [target];
         }
         else if (args.workItemIds !== undefined) {
-            // Scoped lease: restrict to a specific batch's work items so concurrent
-            // owners (e.g. several watchers each handling their own Vary run) don't
-            // greedily lease each other's items. Leases whatever subset of the
-            // requested ids is still leasable; only errors if NONE are.
             const wanted = new Set(args.workItemIds);
             leasable = leasable.filter((item) => wanted.has(item.id));
             if (leasable.length === 0) {
                 throw new errors_1.AgentVariantsError('INVALID_STAGE_ACTION', 'None of the requested work items are currently leasable (already leased, running, or done)');
             }
         }
-        // `workItemIds` takes precedence over `requestedLeaseCount`: a scoped batch
-        // leases ALL of its still-leasable items, not a count-capped subset (the
-        // scoping above already narrowed `leasable` to exactly that batch).
         const limit = args.workItemIds !== undefined
             ? leasable.length
             : (args.requestedLeaseCount ?? leasable.length);
@@ -806,15 +702,6 @@ class SessionStore {
     }
     reportComplete(args) {
         const session = this.requireSession(args.sessionId);
-        // Cooperative abort: if the work item was removed/cancelled while the agent
-        // was still working it (delete-while-loading, cancel_variant, or session
-        // cancel), its lease was deliberately cleared. Returning an opaque
-        // STALE_LEASE here forces the agent to guess; instead hand back an explicit
-        // `aborted` so it drops this work item right away — no retry, no recording
-        // soon-to-be-discarded output. Checked before the terminal-stage, lease,
-        // and fingerprint gates so it still fires once removal has driven the
-        // session terminal. Uses a non-throwing lookup so a report for an item that
-        // never existed still falls through to requireWorkItem's clear error.
         const abortTarget = session.workItems.get(args.workItemId);
         if (abortTarget &&
             (abortTarget.removed || abortTarget.status === 'cancelled')) {
@@ -825,8 +712,6 @@ class SessionStore {
             };
         }
         if (contracts_1.TERMINAL_STAGES.has(session.stage)) {
-            // idempotent: terminal sessions accept replays of accepted fingerprints,
-            // reject new mutating reports.
             const fp = fingerprint([
                 'reportComplete',
                 args.sessionId,
@@ -855,7 +740,6 @@ class SessionStore {
             return cached;
         this.validateLease(item, args.leaseId, args.attempt);
         if (args.status === 'running') {
-            // mid-status heartbeat: extend lease, return progress.
             const now = this.clock.now();
             if (item.lease) {
                 item.lease.leaseExpiresAt = now + leaseTtlForKind(item.kind);
@@ -870,9 +754,6 @@ class SessionStore {
         item.error = args.error;
         if (args.runtime)
             item.runtime = args.runtime;
-        // Apply an agent-synthesized title/description so the variant card shows a
-        // meaningful name (parent identity + the change) instead of the provisional
-        // instruction text. Only on success; capped so the label stays short.
         if (args.status === 'succeeded' && (args.title || args.description)) {
             const input = item.input;
             if (args.title)
@@ -885,24 +766,10 @@ class SessionStore {
         if (args.status === 'failed') {
             this.cascadeDependencyFailure(session, item.id);
         }
-        else if (args.status === 'succeeded') {
-            // succeeded items unblock dependents — handled in leasableItems()
-        }
         const result = this.evaluateTerminal(session);
         session.acceptedFingerprints.set(fp, result);
         return result;
     }
-    /**
-     * Re-open a succeeded variant work item for one QA-driven regeneration.
-     * Consumes the agent's report (validating the lease), then resets the item
-     * to `pending` so it becomes leasable again via `request_work`, stashing the
-     * QA notes onto its input so the re-leased descriptor carries the notes the
-     * agent must address before re-reporting.
-     *
-     * The work item never reaches a terminal status, so the session stays in
-     * `waiting_for_results` and never goes terminal off the back of a QA
-     * failure. Idempotent on replay via the accepted-fingerprint cache.
-     */
     requeueForRegeneration(args) {
         const session = this.requireSession(args.sessionId);
         const fp = fingerprint([
@@ -918,8 +785,6 @@ class SessionStore {
         this.assertStage(session, ['work_items_ready', 'waiting_for_results']);
         const item = this.requireWorkItem(session, args.workItemId);
         this.validateLease(item, args.leaseId, args.attempt);
-        // Reset to pending so request_work re-surfaces it. The re-lease increments
-        // `attempt`, so the regenerated report carries a fresh fingerprint.
         item.status = 'pending';
         item.lease = undefined;
         item.output = undefined;
@@ -933,11 +798,6 @@ class SessionStore {
         session.acceptedFingerprints.set(fp, result);
         return result;
     }
-    /**
-     * Creates a refinable HTML work item for a completed static preview variant.
-     * The target variant remains the user-facing snapshot; this work item only
-     * tracks the in-flight refinement and is surfaced through its `refinement`.
-     */
     createRefineVariantWorkItem(args) {
         const session = this.requireSession(args.sessionId);
         const target = this.requireWorkItem(session, args.variantId);
@@ -970,6 +830,7 @@ class SessionStore {
                 briefId: targetInput.briefId,
                 briefLabel: targetInput.briefLabel,
                 briefBody: targetInput.briefBody,
+                references: targetInput.references,
                 ...(targetInput.briefNotes
                     ? { briefNotes: targetInput.briefNotes }
                     : {}),
@@ -988,15 +849,6 @@ class SessionStore {
         session.stage = 'work_items_ready';
         return item;
     }
-    /**
-     * Fork a completed static_preview variant into N NEW sibling variants. Unlike
-     * {@link createRefineVariantWorkItem} (which overwrites the source variant in
-     * place), each forked item is a fresh `static_preview` work item with its own
-     * id, seeded from the source variant's HTML (`currentHtml`) plus the user's
-     * instruction. This backs the "Vary" action, where `variantRequest.count`
-     * asks for N new explorations rather than an in-place edit. Returns the
-     * created items so the caller can lease them via the normal request-work path.
-     */
     createForkedStaticPreviewWorkItems(args) {
         const session = this.requireSession(args.sessionId);
         const source = this.requireWorkItem(session, args.sourceVariantId);
@@ -1022,10 +874,6 @@ class SessionStore {
             source.output?.html;
         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
-        // are indistinguishable in the Directions list.
         const instruction = args.instruction.trim();
         const prettyInstruction = instruction
             ? instruction.charAt(0).toUpperCase() + instruction.slice(1)
@@ -1038,6 +886,27 @@ class SessionStore {
             const labelBase = prettyInstruction.length > LABEL_MAX - suffix.length
                 ? `${prettyInstruction.slice(0, LABEL_MAX - suffix.length - 1)}…`
                 : prettyInstruction;
+            const context = args.additionalContext
+                ? {
+                    ...sourceInput.context,
+                    contextBundlePath: args.additionalContext.contextBundlePath,
+                    references: (0, variant_reference_1.mergeVariantReferences)(sourceInput.context?.references, ...args.additionalContext.userContext.map((source) => 'references' in source ? source.references : undefined)),
+                    userContext: [
+                        ...(sourceInput.context?.userContext ?? []),
+                        ...args.additionalContext.userContext,
+                    ],
+                    rivetMetadata: [
+                        ...(sourceInput.context?.rivetMetadata ?? []),
+                        ...args.additionalContext.rivetMetadata,
+                    ],
+                    brief: {
+                        ...brief,
+                        briefId: sourceInput.briefId ?? 'vary',
+                        label: brief?.label ?? labelBase,
+                        body: brief?.body ?? prettyInstruction,
+                    },
+                }
+                : sourceInput.context;
             const item = {
                 id: (0, crypto_1.randomUUID)(),
                 kind: 'static_preview',
@@ -1046,18 +915,15 @@ class SessionStore {
                 dependsOn: [],
                 input: {
                     briefId: `${sourceInput.briefId ?? 'v'}-vary-${(0, crypto_1.randomUUID)().slice(0, 8)}`,
-                    // 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,
+                    references: (0, variant_reference_1.mergeVariantReferences)(sourceInput.references, context?.references),
                     ...(args.runLabel ? { runLabel: args.runLabel } : {}),
                     ...(brief?.visualReferenceUrl
                         ? { visualReferenceUrl: brief.visualReferenceUrl }
                         : {}),
                     instruction: args.instruction,
                     sourceVariantId: args.sourceVariantId,
-                    // Parent identity, so the agent can synthesize a name/description that
-                    // combines the source variant with the requested change.
                     ...(sourceInput.briefLabel
                         ? { sourceLabel: sourceInput.briefLabel }
                         : {}),
@@ -1069,39 +935,18 @@ class SessionStore {
                     ...(args.requestId ? { requestId: args.requestId } : {}),
                     ...(args.fidelity ? { fidelity: args.fidelity } : {}),
                     projectContext: sourceInput.projectContext ?? session.projectContext,
-                    ...(sourceInput.context ? { context: sourceInput.context } : {}),
+                    ...(context ? { context } : {}),
                     ...(relevantFiles.length > 0 ? { relevantFiles } : {}),
                 },
                 acceptedReports: [],
             };
             session.workItems.set(item.id, item);
-            // Surface newest siblings at the top of the Directions list: unshift each
-            // in creation order so the batch ends up [variation N … variation 1]
-            // ahead of the pre-existing variants.
             session.workItemOrder.unshift(item.id);
             created.push(item);
         }
         session.stage = 'work_items_ready';
         return created;
     }
-    /**
-     * Append new code_gen variants to an EXISTING-project session that already
-     * holds variants — the worktree-backed analog of
-     * {@link createForkedStaticPreviewWorkItems}. A second "Vary" on an existing
-     * project lands here so its variants ACCUMULATE in the live session instead
-     * of orphaning the prior ones in a fresh, superseding session. The new items
-     * are leasable via {@link requestWork} exactly like the initial code_gen
-     * 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.
-     */
     appendCodeGenVariants(args) {
         const session = this.requireSession(args.sessionId);
         const source = args.sourceVariantId
@@ -1158,6 +1003,7 @@ class SessionStore {
                     briefId: brief.briefId,
                     briefLabel: brief.label,
                     briefBody: brief.body,
+                    references: (0, variant_reference_1.mergeVariantReferences)(sourceInput.references, context?.references),
                     instruction: args.instruction,
                     ...(brief.notes ? { briefNotes: brief.notes } : {}),
                     ...visualRef,
@@ -1180,8 +1026,6 @@ 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);
@@ -1189,24 +1033,6 @@ class SessionStore {
         session.stage = 'work_items_ready';
         return { createdWorkItemIds, briefs: args.briefs };
     }
-    /**
-     * Adopt a PAST variant (from a prior session's persisted history) into THIS
-     * active session as a first-class, already-`succeeded` `static_preview`
-     * variant. Triggered when the user makes their first edit (a comment or a
-     * Vary) on a selected past direction: the past variant is rehydrated as a
-     * live session member so the comment/refine machinery scopes and routes to it
-     * exactly like a freshly-generated variant. The caller (orchestrator) registers
-     * the static-preview record that points at the rehydrated files so the snapshot
-     * surfaces it as a `static_artifact`.
-     *
-     * Kept as `static_preview` regardless of the host session's primary variant
-     * kind so {@link createRefineVariantWorkItem} / {@link createForkedStaticPreviewWorkItems}
-     * accept it. Adopted variants are pre-completed artifacts, so they are excluded
-     * from progress/summary/terminal accounting and never reopen the session.
-     *
-     * Idempotent: re-adopting the same `{sessionId, variantId}` returns the
-     * existing work item id (`created: false`) rather than duplicating it.
-     */
     appendAdoptedStaticVariant(args) {
         const session = this.requireSession(args.sessionId);
         if (session.stage === 'cancelled' || session.stage === 'failed') {
@@ -1237,32 +1063,15 @@ class SessionStore {
                 ...(args.description ? { briefBody: args.description } : {}),
                 ...(args.runLabel ? { runLabel: args.runLabel } : {}),
                 adoptedFrom: { ...args.source },
+                references: (0, variant_reference_1.mergeVariantReferences)(args.references),
                 projectContext: session.projectContext,
             },
             acceptedReports: [],
         };
         session.workItems.set(item.id, item);
-        // Adoption is triggered by the user's first in-place edit (a comment /
-        // refine) on an ALREADY-DISPLAYED past direction — not a request for a new
-        // exploration. Appending (rather than unshifting to the top) preserves the
-        // positions of the existing active variants so a refined card does NOT
-        // leapfrog a newer Vary/fork batch. Genuinely new variants (Vary / fork /
-        // append) still surface at the top via their own `unshift` paths. Stage is
-        // intentionally left untouched — the adopted variant is already complete,
-        // so the session must not reopen to `work_items_ready`.
         session.workItemOrder.push(item.id);
         return { workItemId: item.id, briefId, created: true };
     }
-    /**
-     * Create an active session whose initial visible direction is a static
-     * variant rehydrated from persisted history.
-     *
-     * This is the no-usable-session counterpart to
-     * {@link appendAdoptedStaticVariant}: the session starts terminal/ready
-     * because the adopted artifact is already generated, and the adopted work item
-     * remains excluded from generation progress because this run did not generate
-     * fresh variants.
-     */
     createSessionFromStaticHistoryVariant(args) {
         const sessionId = (0, crypto_1.randomUUID)();
         const record = {
@@ -1285,6 +1094,7 @@ class SessionStore {
             source: args.source,
             label: args.label,
             description: args.description,
+            references: args.references,
             runLabel: args.runLabel,
         });
         return {
@@ -1293,7 +1103,6 @@ class SessionStore {
             briefId: adopted.briefId,
         };
     }
-    /** Find an already-adopted variant by its source identity, or undefined. */
     findAdoptedVariant(session, source) {
         for (const item of session.workItems.values()) {
             if (item.removed)
@@ -1308,13 +1117,6 @@ class SessionStore {
         }
         return undefined;
     }
-    /**
-     * Stamp a UI correlation id onto already-created variant work items so the
-     * snapshot surfaces it and the panel can map its optimistic placeholders to
-     * the real cards (see {@link ActiveVariantSnapshot.requestId}). Skips ids
-     * that are unknown to the session. Used by `start_variants` for both the
-     * initial batch and the appended (accumulated) batch.
-     */
     assignVariantRequestId(sessionId, workItemIds, requestId) {
         const session = this.requireSession(sessionId);
         for (const id of workItemIds) {
@@ -1325,14 +1127,6 @@ class SessionStore {
             item.input = { ...input, requestId };
         }
     }
-    /**
-     * Fold a newer instruction into a variant's still-pending refinement. Used
-     * when a second refinement is requested for a variant that already has a
-     * queued (not yet leased) refinement: the new instruction is appended so the
-     * agent applies both rather than dropping the later request. The latest
-     * request's fidelity replaces the queued choice; omission restores the
-     * server default. Returns false when no pending refinement exists.
-     */
     appendPendingRefineVariantInstruction(args) {
         const session = this.requireSession(args.sessionId);
         const refineItem = [...session.workItems.values()].find((item) => {
@@ -1356,11 +1150,6 @@ class SessionStore {
         }
         return true;
     }
-    /**
-     * Lease the pending refinement already associated with a specific static
-     * preview variant. Keeps multi-target refinement batches independent of
-     * work-item order.
-     */
     leaseRefineItemForVariant(args) {
         const session = this.requireSession(args.sessionId);
         const runningRefinement = [...session.workItems.values()].find((item) => {
@@ -1387,15 +1176,6 @@ class SessionStore {
             workItemId: refineItem.id,
         });
     }
-    /**
-     * Mark a server-owned work item as succeeded without going through the
-     * lease + agent-report path. Used for `scaffold_base` items where the
-     * orchestrator runs the scaffold + npm install in the background and needs
-     * to unblock dependent code_gen items when it's done.
-     *
-     * Bypasses lease validation because no lease was ever issued for internal
-     * items. Idempotent: completing an already-succeeded item is a no-op.
-     */
     completeInternal(args) {
         const session = this.requireSession(args.sessionId);
         const item = this.requireWorkItem(session, args.workItemId);
@@ -1410,11 +1190,6 @@ class SessionStore {
         item.lease = undefined;
         return this.evaluateTerminal(session);
     }
-    /**
-     * Mark a server-owned work item as failed, cascading DEPENDENCY_FAILED to
-     * its dependents. Used when the orchestrator's background scaffold work
-     * (npm install, file writes) fails and we need the session to degrade.
-     */
     failInternal(args) {
         const session = this.requireSession(args.sessionId);
         const item = this.requireWorkItem(session, args.workItemId);
@@ -1430,7 +1205,6 @@ class SessionStore {
         this.cascadeDependencyFailure(session, item.id);
         return this.evaluateTerminal(session);
     }
-    // --- Cancel / cleanup ---------------------------------------------------
     cancel(args) {
         const session = this.requireSession(args.sessionId);
         if (session.stage === 'cancelled') {
@@ -1444,18 +1218,8 @@ class SessionStore {
                 item.lease = undefined;
             }
         }
-        // No cleanup_runtime items in Phase 1; status starts as pending until
-        // Phase 2 wires the worktree teardown.
         return { stage: 'cancelled', cleanupStatus: 'pending' };
     }
-    /**
-     * Cancel a single work item without tearing down its sibling variants or
-     * the session itself. Idempotent on terminal states — already-cancelled,
-     * succeeded, or failed items return their current status with
-     * `alreadyTerminal: true` and no state change. Triggers
-     * `evaluateTerminal` so the session can reach a terminal stage if this
-     * was the last in-flight item.
-     */
     cancelWorkItem(args) {
         const session = this.requireSession(args.sessionId);
         const item = this.requireWorkItem(session, args.workItemId);
@@ -1479,14 +1243,6 @@ class SessionStore {
             alreadyTerminal: false,
         };
     }
-    /**
-     * Remove a variant from the UI. The work item is retained in the session
-     * (and the caller persists it to `.rivet/variants/` as `removed`) but its
-     * `removed` flag excludes it from the active snapshot, progress/summary, and
-     * terminal evaluation — so it is never rendered again. Any in-flight work is
-     * cancelled first so the hidden variant doesn't keep a lease or resurface via
-     * `request_work`; terminal variants keep their final status. Idempotent.
-     */
     removeWorkItem(args) {
         const session = this.requireSession(args.sessionId);
         const item = this.requireWorkItem(session, args.workItemId);
@@ -1503,10 +1259,6 @@ class SessionStore {
             item.lease = undefined;
         }
         item.removed = true;
-        // Cancel any in-flight refinement for this variant too — otherwise a
-        // pending/running refine_variant keeps the session busy (evaluateTerminal
-        // waits on it) and request_work could keep leasing hidden refinement work
-        // after the parent variant was removed.
         for (const other of session.workItems.values()) {
             if (other.kind !== 'refine_variant')
                 continue;
@@ -1526,12 +1278,6 @@ class SessionStore {
             alreadyRemoved: false,
         };
     }
-    /**
-     * Rename a variant: patches the brief label held in the work item's `input`
-     * blob (the same field `variantsOf` reads for the snapshot `label`), so the
-     * next `emitChange` pushes the new title to the UI. Pure metadata edit — it
-     * never touches status, lease, or refinement state. Idempotent.
-     */
     renameWorkItem(args) {
         const session = this.requireSession(args.sessionId);
         const item = this.requireWorkItem(session, args.workItemId);
@@ -1543,12 +1289,6 @@ class SessionStore {
             sessionStage: session.stage,
         };
     }
-    /**
-     * Re-home every non-removed work item in one request batch whose effective
-     * run label matches. The explicit request id prevents same-label batches in
-     * one session from affecting each other; an absent id selects the session's
-     * initial batch. The new label is stamped per item as `input.runLabel`.
-     */
     renameRun(args) {
         const session = this.requireSession(args.sessionId);
         const sessionFallback = session.runLabel ?? (0, runLabel_1.deriveRunLabel)(session.prompt);
@@ -1568,7 +1308,6 @@ class SessionStore {
         }
         return { workItemIds, sessionStage: session.stage };
     }
-    // --- Variant pick handoff ----------------------------------------------
     recordVariantPick(args) {
         const session = this.requireSession(args.sessionId);
         if (!['ready', 'degraded'].includes(session.stage)) {
@@ -1584,15 +1323,12 @@ class SessionStore {
         session.variantPick = args.envelope;
         return { duplicate: false };
     }
-    // --- Read accessors -----------------------------------------------------
     getStage(sessionId) {
         return this.requireSession(sessionId).stage;
     }
     getPrompt(sessionId) {
         return this.requireSession(sessionId).prompt;
     }
-    /** The run's label — the agent-provided one if present, else a heuristic
-     *  derived from the prompt. */
     getRunLabel(sessionId) {
         const session = this.requireSession(sessionId);
         return session.runLabel ?? (0, runLabel_1.deriveRunLabel)(session.prompt);
@@ -1611,8 +1347,6 @@ class SessionStore {
         const session = this.requireSession(sessionId);
         return this.variantsOf(session);
     }
-    /** Record the run's worker-runtime lease summary (see
-     *  ActiveSnapshot.workerRuntime). Latest batch wins. */
     setWorkerRuntime(sessionId, summary) {
         const session = this.sessions.get(sessionId);
         if (session)
@@ -1621,16 +1355,15 @@ class SessionStore {
     getWorkerRuntime(sessionId) {
         return this.sessions.get(sessionId)?.workerRuntime;
     }
-    /** The runtime that executed a work item's worker, when the executor
-     *  reported one — read at history-persist time so manifests carry it. */
     getWorkItemRuntime(sessionId, workItemId) {
         return this.sessions.get(sessionId)?.workItems.get(workItemId)?.runtime;
     }
     getHostWork(sessionId) {
         const session = this.requireSession(sessionId);
-        return [...session.workItems.values()]
-            .filter((item) => item.lease && item.status === 'running')
-            .map((item) => {
+        return [...session.workItems.values()].flatMap((item) => {
+            const { lease } = item;
+            if (!lease || item.status !== 'running')
+                return [];
             const input = item.input && typeof item.input === 'object'
                 ? item.input
                 : {};
@@ -1642,10 +1375,10 @@ class SessionStore {
                 variantId,
                 kind: item.kind,
                 status: item.status,
-                leaseId: item.lease.leaseId,
-                leaseOwner: item.lease.leaseOwner,
-                attempt: item.lease.attempt,
-                leaseExpiresAt: item.lease.leaseExpiresAt,
+                leaseId: lease.leaseId,
+                leaseOwner: lease.leaseOwner,
+                attempt: lease.attempt,
+                leaseExpiresAt: lease.leaseExpiresAt,
                 input: item.input,
                 outputSchema: outputSchemaFor(item.kind),
             };
@@ -1654,7 +1387,6 @@ class SessionStore {
     getVariantPick(sessionId) {
         return this.requireSession(sessionId).variantPick;
     }
-    /** Validates a report lease without mutating the work item. */
     validateReportLease(args) {
         const session = this.requireSession(args.sessionId);
         const item = this.requireWorkItem(session, args.workItemId);
@@ -1663,8 +1395,6 @@ class SessionStore {
     hasSession(sessionId) {
         return this.sessions.has(sessionId);
     }
-    /** Read a work item's input blob — used by the orchestrator to recover
-     *  briefLabel / target / projectContext when committing the output. */
     getWorkItemInput(sessionId, workItemId) {
         const session = this.requireSession(sessionId);
         const item = this.requireWorkItem(session, workItemId);
@@ -1675,37 +1405,24 @@ class SessionStore {
         const item = this.requireWorkItem(session, workItemId);
         return item.output;
     }
-    /** Returns the authoritative status after report validation and post-processing. */
     getWorkItemStatus(sessionId, workItemId) {
         const session = this.requireSession(sessionId);
         return this.requireWorkItem(session, workItemId).status;
     }
-    /** Replaces a completed work item's output after server-side post-processing. */
     replaceWorkItemOutput(sessionId, workItemId, output) {
         const session = this.requireSession(sessionId);
         const item = this.requireWorkItem(session, workItemId);
         item.output = output;
     }
-    /** Read a work item's `kind` discriminator (brief | source_plan |
-     *  static_preview | code_gen | scaffold_base). Used by callers that need to
-     *  branch their validation on the work-item shape — e.g. enforcing the
-     *  inline-HTML contract on static_preview `succeeded` reports. */
     getWorkItemKind(sessionId, workItemId) {
         const session = this.requireSession(sessionId);
         const item = this.requireWorkItem(session, workItemId);
         return item.kind;
     }
-    /** True when the work item forks an existing variant (execution mode
-     *  "vary"). Non-throwing so telemetry callers can read it on any item:
-     *  unknown session or work item reads as not-a-fork. */
     isVaryForkWorkItem(sessionId, workItemId) {
         const item = this.sessions.get(sessionId)?.workItems.get(workItemId);
         return Boolean(item && item.input.sourceVariantId);
     }
-    /** True when the work item was removed or cancelled out from under the agent.
-     *  The orchestrator checks this to short-circuit the schema/QA gates before a
-     *  `report_variant_complete` it's about to abort. Non-throwing: unknown
-     *  session or work item reads as not-aborted. */
     isWorkItemAborted(sessionId, workItemId) {
         const session = this.sessions.get(sessionId);
         if (!session)
@@ -1713,11 +1430,9 @@ class SessionStore {
         const item = session.workItems.get(workItemId);
         return Boolean(item && (item.removed || item.status === 'cancelled'));
     }
-    /** Read the projectContext for a session (existing | fresh). */
     getProjectContext(sessionId) {
         return this.requireSession(sessionId).projectContext;
     }
-    // --- Internals ----------------------------------------------------------
     requireSession(sessionId) {
         const s = this.sessions.get(sessionId);
         if (!s) {
@@ -1737,19 +1452,6 @@ class SessionStore {
             throw new errors_1.AgentVariantsError('INVALID_STAGE_ACTION', `Action not allowed in stage ${session.stage}; allowed: ${allowed.join(', ')}`);
         }
     }
-    /**
-     * Validates a report against a planning work item (source_plan or brief).
-     *
-     * Planning items are single-planner and attempt-gated. `propose` /
-     * `start_variants` hand back the source_plan item, and `report_source_plan`
-     * hands back the brief item, WITHOUT issuing a lease — so the agent reports
-     * against them directly (no `request_work` round-trip) and may carry a stale
-     * or guessed `leaseId` from an earlier stage. When the item carries an active
-     * lease (the agent went through `request_work`, e.g. a recovery re-lease),
-     * validate it strictly. Otherwise gate on `attempt` alone and ignore any
-     * provided leaseId, so a direct report no longer fails with LEASE_MISMATCH
-     * and force a wasteful re-request → re-report round-trip.
-     */
     validatePlanningReport(item, leaseId, attempt) {
         if (item.lease) {
             this.validateLease(item, leaseId ?? '', attempt);
@@ -1788,9 +1490,10 @@ class SessionStore {
         const out = [];
         for (const id of session.workItemOrder) {
             const item = session.workItems.get(id);
+            if (!item)
+                throw new Error(`Missing ordered work item: ${id}`);
             if (item.kind === 'brief')
                 continue;
-            // Server-owned items never surface to external agents.
             if (item.internal)
                 continue;
             if (item.status !== 'pending')
@@ -1843,23 +1546,10 @@ class SessionStore {
     }
     terminalItems(session) {
         const kind = this.variantWorkItemKind(session);
-        // Removed variants are excluded everywhere progress/summary/terminal
-        // accounting reads from, so a removed variant neither blocks the session
-        // from going terminal nor inflates the ready/total counts. Adopted past
-        // variants are likewise excluded: they are pre-completed artifacts pulled in
-        // for editing, not part of this run's generation, so they must not inflate
-        // progress/total or flip a failed run to degraded.
         return [...session.workItems.values()].filter((i) => (i.kind === kind || isForkedStaticPreviewVariant(i)) &&
             !i.removed &&
             !isAdoptedVariant(i));
     }
-    /**
-     * The work-item kind that represents a user-facing variant for this
-     * session. Drives both progress accounting and the active variants
-     * snapshot. Fresh+vite_app sessions use `code_gen` like existing
-     * projects; fresh+static_preview (the default for source-less 0→1)
-     * keeps `static_preview` as the deliverable.
-     */
     variantWorkItemKind(session) {
         if (session.projectContext.kind !== 'fresh')
             return 'code_gen';
@@ -1876,9 +1566,6 @@ class SessionStore {
             };
         }
         const items = this.terminalItems(session);
-        // No live variants (e.g. the user removed them all) — don't flip an empty
-        // session to a terminal "ready" state with zero successes; leave the stage
-        // as-is.
         if (items.length === 0) {
             return {
                 stage: session.stage,
@@ -1974,23 +1661,13 @@ class SessionStore {
                 workItemId: item.id,
                 briefId: input.briefId ?? '',
                 label: input.briefLabel ?? 'Variant',
+                references: input.references,
                 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
-                // prompt is the session prompt). Without this, accumulated batches
-                // all show batch 1's tag.
                 runLabel: input.runLabel ??
                     session.runLabel ??
                     (0, runLabel_1.deriveRunLabel)(session.prompt),
-                // Correlation id of the UI request that produced this variant (a fork)
-                // or, for an in-place refine, the request driving its refinement —
-                // lets the UI map its optimistic placeholders to real cards.
                 ...(input.requestId
                     ? { requestId: input.requestId }
                     : refineRequestId
@@ -2020,9 +1697,6 @@ class SessionStore {
                     }
                     : {}),
                 ...(item.error?.code ? { errorCode: String(item.error.code) } : {}),
-                // The failure detail (exit code + stderr/result tail) must survive
-                // into the snapshot — dropping it here reduced every executor
-                // failure to a bare EXECUTOR_WORKER_FAILED in `variants status`.
                 ...(item.error?.message
                     ? { errorMessage: capErrorMessage(item.error.message) }
                     : {}),
@@ -2032,9 +1706,6 @@ class SessionStore {
     }
 }
 exports.SessionStore = SessionStore;
-/** Snapshot-side bound on failure detail. The executor already caps its
- *  stderr/result capture, but host-reported errors are unbounded — the
- *  status envelope should never balloon on a chatty failure. */
 function capErrorMessage(message) {
     const MAX = 1000;
     return message.length > MAX ? `${message.slice(0, MAX)}…` : message;