rivet-design 0.13.3 → 0.13.5

package/dist/agent-variants/WorktreeOrchestrator.js

@@ -17,6 +17,7 @@ const devServerError_1 = require("../utils/devServerError");
 const errors_1 = require("./errors");
 const createProjectArtifacts_1 = require("./createProjectArtifacts");
 const contracts_1 = require("./contracts");
+const workItemBriefing_1 = require("./workItemBriefing");
 const briefContent_1 = require("./briefContent");
 const runLabel_1 = require("./runLabel");
 const runPlan_1 = require("./runPlan");
@@ -24,6 +25,7 @@ const viteReactTs_1 = require("../services/templates/viteReactTs");
 const StaticPreviewServer_1 = require("../services/StaticPreviewServer");
 const designCatalog_1 = require("../services/templates/designCatalog");
 const previewQa_1 = require("./previewQa");
+const VariantWorkspaceManager_1 = require("./VariantWorkspaceManager");
 const diffQa_1 = require("./diffQa");
 const VariantHistoryService_1 = require("../services/VariantHistoryService");
 const variantContext_1 = require("./variantContext");
@@ -60,6 +62,16 @@ const BRIEF_LABEL_ALTERNATIVES = [
     'Density',
     'Color',
 ];
+const FALLBACK_DIRECTION_FOCI = [
+    'Emphasize hierarchy and one unmistakable primary action.',
+    'Use stronger contrast, scale shifts, and a more expressive visual system.',
+    'Favor a quieter, spacious composition with restrained supporting detail.',
+    'Make information density and fast scanning the organizing principle.',
+    'Lead with imagery and let content frame the visual story.',
+    'Use modular cards and clear grouping to expose the product structure.',
+    'Explore tactile depth, layering, and purposeful interaction cues.',
+    'Reduce the concept to its most essential typography and geometry.',
+];
 // Upper bound on waiting for in-flight history persists during session
 // teardown. Generous enough for a full-repo snapshot on a large project;
 // small enough that a wedged git subprocess (which has its own 120s block
@@ -350,6 +362,12 @@ const buildViewDisabledReason = (args) => {
     return 'Variant is still running';
 };
 const NOOP_TELEMETRY = { track: () => undefined };
+const isImplementationWorkItemKind = (kind) => kind === 'static_preview' || kind === 'refine_variant' || kind === 'code_gen';
+const DEFAULT_EXECUTION_MODE_BY_KIND = {
+    static_preview: 'create',
+    refine_variant: 'refine',
+    code_gen: 'create',
+};
 const DESIGN_CREATION_ACTION_RE = /\b(create|build|design|make|redesign|refresh|update)\b/i;
 const DESIGN_CREATION_SURFACE_RE = /\b(home\s?page|landing page|dashboard|screen|site|website|app|page|ui|interface|component|hero)\b/i;
 const NON_VISUAL_CHANGE_RE = /\b(api|backend|database|event|lint|query|server|test|tracking|typecheck)\b/i;
@@ -658,16 +676,71 @@ class AgentVariantsOrchestrator {
     }
     getHostWork(sessionId) {
         return this.store.getHostWork(sessionId).map((item) => {
-            const worktreePath = this.getWorktreePath(sessionId, item.workId);
-            const baseInput = item.input && typeof item.input === 'object'
-                ? item.input
-                : {};
-            return {
-                ...item,
-                input: { ...baseInput, worktreePath },
+            const kind = item.kind;
+            if (!isImplementationWorkItemKind(kind)) {
+                const planningItem = {
+                    ...item,
+                    kind,
+                };
+                return planningItem;
+            }
+            const input = (item.input ?? {});
+            const workspace = this.getAssignedWorkspace({
+                sessionId,
+                workItemId: item.workId,
+                kind,
+            });
+            const mode = input.sourceVariantId
+                ? 'vary'
+                : DEFAULT_EXECUTION_MODE_BY_KIND[kind];
+            const sourceLabel = input.sourceLabel ?? (mode === 'refine' ? input.briefLabel : undefined);
+            const sourceBody = input.sourceBody ??
+                (mode === 'refine' ? input.briefBody : undefined) ??
+                sourceLabel;
+            const implementationItem = {
+                workId: item.workId,
+                variantId: item.variantId,
+                kind,
+                status: item.status,
+                leaseId: item.leaseId,
+                attempt: item.attempt,
+                leaseExpiresAt: item.leaseExpiresAt,
+                workspace,
+                mode,
+                direction: {
+                    label: input.briefLabel ?? 'Variant',
+                    brief: input.briefBody ?? input.instruction ?? 'Create this variant',
+                    ...(input.briefNotes ? { notes: input.briefNotes } : {}),
+                },
+                ...(sourceLabel && sourceBody
+                    ? { sourceDirection: { label: sourceLabel, brief: sourceBody } }
+                    : {}),
+                ...(input.relevantFiles?.length
+                    ? { relevantFiles: input.relevantFiles }
+                    : {}),
+                ...(input.instruction ? { instruction: input.instruction } : {}),
+                ...(input.target ? { target: input.target } : {}),
+                ...(input.targetElement ? { targetElement: input.targetElement } : {}),
+                ...(input.context?.contextBundlePath
+                    ? { contextBundlePath: input.context.contextBundlePath }
+                    : {}),
+                completion: kind === 'code_gen'
+                    ? { kind: 'worktree_diff' }
+                    : { kind: 'static_artifact' },
             };
+            return implementationItem;
         });
     }
+    getAssignedWorkspace(args) {
+        const workspace = this.resources
+            .get(args.sessionId)
+            ?.workspaceManager.getAssignedWorkspace(args.workItemId);
+        const expectedKind = args.kind === 'code_gen' ? 'git_worktree' : 'artifact_directory';
+        if (!workspace || workspace.kind !== expectedKind) {
+            throw new errors_1.AgentVariantsError('RUNTIME_VALIDATION_FAILED', `Variant ${args.workItemId} has no assigned ${expectedKind} workspace`);
+        }
+        return workspace;
+    }
     getVariantsTelemetryMode(projectContext, _target) {
         if (projectContext.kind === 'fresh' && projectContext.variantContext) {
             return 'source_grounded';
@@ -967,6 +1040,35 @@ class AgentVariantsOrchestrator {
     }
     requestWork(args) {
         const result = this.store.requestWork(args);
+        try {
+            this.ensureStaticWorkspaces(args.sessionId, result.leasedWorkItems);
+        }
+        catch (error) {
+            for (const item of result.leasedWorkItems) {
+                if (item.kind !== 'static_preview' && item.kind !== 'refine_variant') {
+                    continue;
+                }
+                try {
+                    this.store.reportComplete({
+                        sessionId: args.sessionId,
+                        workItemId: item.id,
+                        leaseId: result.leaseId,
+                        attempt: item.attempt,
+                        status: 'failed',
+                        error: {
+                            code: 'RUNTIME_VALIDATION_FAILED',
+                            message: error instanceof Error
+                                ? error.message
+                                : 'Failed to assign static variant workspace',
+                        },
+                    });
+                }
+                catch (reportError) {
+                    log.warn(`Failed to record static workspace provisioning failure for ${item.id}`, reportError);
+                }
+            }
+            throw error;
+        }
         // Record lease times so variant_completed can report lease→report
         // duration. (We don't fire a separate code_gen_leased event — the
         // funnel signal we care about is per-variant completion duration.)
@@ -977,6 +1079,7 @@ class AgentVariantsOrchestrator {
                 resources.leasedAt.set(item.id, now);
             }
         }
+        this.writeLeasedWorkItemBriefings(args.sessionId, result.leasedWorkItems.map((item) => item.id));
         this.trackRefinementLeased({ sessionId: args.sessionId, lease: result });
         // Decorate each leased item's input with the worktreePath provisioned
         // by approve(). The skill instructs agents to write files to
@@ -998,6 +1101,94 @@ class AgentVariantsOrchestrator {
         this.emitChange();
         return decorated;
     }
+    /**
+     * @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).
+     */
+    writeLeasedWorkItemBriefings(sessionId, leasedWorkItemIds) {
+        if (leasedWorkItemIds.length === 0)
+            return;
+        const leased = new Set(leasedWorkItemIds);
+        for (const item of this.getHostWork(sessionId)) {
+            if (!leased.has(item.workId))
+                continue;
+            if (!isImplementationWorkItemKind(item.kind))
+                continue;
+            const implementation = item;
+            try {
+                const briefingPath = (0, workItemBriefing_1.workItemBriefingPath)(sessionId, item.workId);
+                fs_1.default.mkdirSync(path_1.default.dirname(briefingPath), { recursive: true });
+                fs_1.default.writeFileSync(briefingPath, (0, workItemBriefing_1.renderWorkItemBriefing)(implementation), 'utf8');
+            }
+            catch (error) {
+                log.warn(`Failed to write work-item briefing for ${item.workId}`, error);
+            }
+        }
+    }
+    /** @effect Assigns isolated, server-owned artifact workspaces to leased static work. */
+    ensureStaticWorkspaces(sessionId, items) {
+        const resources = this.ensureResources(sessionId);
+        const projectContext = this.store.getProjectContext(sessionId);
+        // This lane provisions by copying the source artifact tree (vary forks) or
+        // seeding an entry file — it bypasses provisionWorktrees, so it gets its
+        // own provisioning telemetry here.
+        const provisionStartedAt = Date.now();
+        let assignedCount = 0;
+        for (const item of items) {
+            if (item.kind !== 'static_preview' && item.kind !== 'refine_variant') {
+                continue;
+            }
+            if (resources.workspaceManager.getAssignedWorkspace(item.id))
+                continue;
+            assignedCount += 1;
+            const input = (item.input ?? {});
+            const existingProjectPath = projectContext.kind === 'existing'
+                ? projectContext.projectPath
+                : undefined;
+            const existingParent = existingProjectPath && fs_1.default.existsSync(existingProjectPath)
+                ? path_1.default.join(existingProjectPath, '.rivet', 'variant-work', sessionId)
+                : path_1.default.join(os_1.default.tmpdir(), 'rivet-variant-work', sessionId);
+            const parent = projectContext.kind === 'fresh'
+                ? projectContext.workspacePath
+                : existingParent;
+            fs_1.default.mkdirSync(parent, { recursive: true });
+            const rootPath = projectContext.kind === 'fresh'
+                ? path_1.default.join(parent, `.rivet-preview-${item.id}`)
+                : path_1.default.join(parent, item.id);
+            const sourceVariantId = input.sourceVariantId ?? input.variantId;
+            const sourceDirectory = sourceVariantId
+                ? resources.staticPreviews.get(sourceVariantId)?.assetBase
+                : undefined;
+            resources.workspaceManager.assignArtifactWorkspace({
+                workItemId: item.id,
+                rootPath,
+                allowedRoot: parent,
+                entryPath: 'index.html',
+                sourceDirectory,
+                seedHtml: input.currentHtml,
+            });
+        }
+        if (assignedCount > 0) {
+            this.telemetry.track('agent_variants.provisioning_completed', {
+                source: 'mcp',
+                sessionId,
+                kind: 'artifact_directory',
+                variantCount: assignedCount,
+                durationMs: Date.now() - provisionStartedAt,
+            });
+        }
+    }
+    /** Reads a completed static artifact while enforcing its assigned directory boundary. */
+    readAssignedStaticArtifact(sessionId, workItemId) {
+        const workspaceManager = this.resources.get(sessionId)?.workspaceManager;
+        if (!workspaceManager) {
+            throw new errors_1.AgentVariantsError('SESSION_NOT_FOUND', `No live resources for session ${sessionId}`);
+        }
+        return workspaceManager.readArtifact(workItemId);
+    }
     beginStaticPreviewRefinements(args) {
         const seenVariantIds = new Set();
         // Targets whose in-place refinement could neither be created nor folded
@@ -1039,6 +1230,7 @@ class AgentVariantsOrchestrator {
                         instruction: target.instruction,
                         currentHtml,
                         targetElement: target.element,
+                        relevantFiles: target.relevantFiles,
                         requestId: target.requestId,
                     });
                     createdWorkItemIds.push(refineItem.id);
@@ -1085,8 +1277,10 @@ class AgentVariantsOrchestrator {
                     instruction: target.instruction,
                     count: target.count,
                     ...(target.briefs ? { briefs: target.briefs } : {}),
+                    ...(target.runLabel ? { runLabel: target.runLabel } : {}),
                     currentHtml,
                     targetElement: target.element,
+                    relevantFiles: target.relevantFiles,
                     requestId: target.requestId,
                 });
                 createdWorkItemIds.push(...forks.map((item) => item.id));
@@ -1369,6 +1563,10 @@ class AgentVariantsOrchestrator {
     getWorkItemInput(sessionId, workItemId) {
         return this.store.getWorkItemInput(sessionId, workItemId);
     }
+    /** Returns status after orchestration QA and refinement post-processing. */
+    getWorkItemStatus(sessionId, workItemId) {
+        return this.store.getWorkItemStatus(sessionId, workItemId);
+    }
     getBriefs(sessionId) {
         return this.store.getBriefs(sessionId);
     }
@@ -1494,6 +1692,38 @@ class AgentVariantsOrchestrator {
     getDevServerPort(sessionId, workItemId) {
         return this.resources.get(sessionId)?.worktrees.get(workItemId)?.port;
     }
+    /**
+     * Restores a Rivet-owned variant preview that the active-session idle timer
+     * reclaimed. Other missing-preview causes remain terminal so this path never
+     * attempts to restart user-owned or repeatedly failing servers.
+     *
+     * @effect Clears the idle marker, 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.
+     */
+    async restoreVariantPreview(sessionId, workItemId) {
+        const resources = this.resources.get(sessionId);
+        const record = resources?.worktrees.get(workItemId);
+        if (!resources || !record)
+            return undefined;
+        if (record.port !== undefined && record.devServerProcess) {
+            this.touchSession(sessionId);
+            return record.port;
+        }
+        if (resources.previewFailures.get(workItemId)?.reason !== 'idle_timeout') {
+            return undefined;
+        }
+        resources.previewFailures.delete(workItemId);
+        this.emitChange();
+        const projectContext = this.store.getProjectContext(sessionId);
+        return this.startVariantDevServer({
+            sessionId,
+            workItemId,
+            record,
+            isFresh: projectContext.kind === 'fresh',
+        });
+    }
     /**
      * @effect Resolves the dev server port for a preview request and refreshes
      *   active-preview retention for that session while the port is still live.
@@ -1713,6 +1943,9 @@ class AgentVariantsOrchestrator {
                 sessionId,
                 briefs,
                 runLabel: args.runLabel?.trim() || (0, runLabel_1.deriveRunLabel)(args.prompt),
+                ...(args.relevantFiles?.length
+                    ? { relevantFiles: args.relevantFiles }
+                    : {}),
                 ...(projectContext.kind === 'existing' && projectContext.variantContext
                     ? { variantContext: projectContext.variantContext }
                     : {}),
@@ -1755,6 +1988,7 @@ class AgentVariantsOrchestrator {
                 prompt: args.prompt,
                 count,
                 target: args.target,
+                relevantFiles: args.relevantFiles,
                 projectContext,
                 runLabel: args.runLabel,
                 ...(args.sessionId ? { sessionId: args.sessionId } : {}),
@@ -1905,20 +2139,79 @@ class AgentVariantsOrchestrator {
             return null;
         return sessionId;
     }
+    /** @effect Registers a provisioned git worktree with runtime and workspace state. */
+    async registerWorktreeWorkspace(resources, record) {
+        let projectPath = record.worktreePath;
+        try {
+            projectPath = await this.worktrees.getProjectCwdInWorktree(record.worktreePath);
+        }
+        catch (err) {
+            log.warn(`Failed to resolve project path in worktree ${record.worktreePath}; using its root`, err);
+        }
+        resources.worktrees.set(record.workItemId, record);
+        resources.workspaceManager.registerGitWorkspace({
+            workItemId: record.workItemId,
+            rootPath: record.worktreePath,
+            projectPath,
+        });
+    }
     /**
      * 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. */
+    async withProvisioningTelemetry(args, run) {
+        const startedAt = Date.now();
+        this.telemetry.track('agent_variants.provisioning_started', {
+            source: 'mcp',
+            sessionId: args.sessionId,
+            kind: args.kind,
+            variantCount: args.variantCount,
+        });
+        try {
+            const result = await run();
+            this.telemetry.track('agent_variants.provisioning_completed', {
+                source: 'mcp',
+                sessionId: args.sessionId,
+                kind: args.kind,
+                variantCount: args.variantCount,
+                durationMs: Date.now() - startedAt,
+            });
+            return result;
+        }
+        catch (err) {
+            const timedOut = err instanceof ProvisionTimeoutError;
+            this.telemetry.track('agent_variants.provisioning_failed', {
+                source: 'mcp',
+                sessionId: args.sessionId,
+                kind: args.kind,
+                variantCount: args.variantCount,
+                durationMs: Date.now() - startedAt,
+                timedOut,
+                errorCode: timedOut
+                    ? 'PROVISION_TIMEOUT'
+                    : err instanceof errors_1.AgentVariantsError
+                        ? err.code
+                        : 'PROVISION_FAILED',
+            });
+            throw err;
+        }
+    }
     async provisionAppendedExistingWorktrees(sessionId, workItemIds) {
         if (workItemIds.length === 0)
             return;
-        const resources = this.ensureResources(sessionId);
-        const instanceKeyPrefix = `a${(0, crypto_1.randomUUID)().slice(0, 8)}-`;
-        const paths = await withProvisionTimeout(this.worktrees.createWorktrees(sessionId, workItemIds.length, instanceKeyPrefix), this.provisionTimeoutMs);
-        workItemIds.forEach((id, i) => {
-            resources.worktrees.set(id, { workItemId: id, worktreePath: paths[i] });
+        await this.withProvisioningTelemetry({ sessionId, kind: 'appended_existing', variantCount: workItemIds.length }, async () => {
+            const resources = this.ensureResources(sessionId);
+            const instanceKeyPrefix = `a${(0, crypto_1.randomUUID)().slice(0, 8)}-`;
+            const paths = await withProvisionTimeout(this.worktrees.createWorktrees(sessionId, workItemIds.length, instanceKeyPrefix), this.provisionTimeoutMs);
+            await Promise.all(workItemIds.map((id, index) => this.registerWorktreeWorkspace(resources, {
+                workItemId: id,
+                worktreePath: paths[index],
+            })));
         });
     }
     /**
@@ -1936,14 +2229,21 @@ class AgentVariantsOrchestrator {
         if (!this.worktrees.forkWorktreesFrom) {
             throw new errors_1.AgentVariantsError('RUNTIME_VALIDATION_FAILED', 'worktreeManager does not implement forkWorktreesFrom');
         }
-        const resources = this.ensureResources(sessionId);
-        const instanceKeyPrefix = `f${(0, crypto_1.randomUUID)().slice(0, 8)}-`;
-        const paths = await withProvisionTimeout(this.worktrees.forkWorktreesFrom(sourcePath, sessionId, workItemIds.length, instanceKeyPrefix), this.provisionTimeoutMs);
-        workItemIds.forEach((id, i) => {
-            resources.worktrees.set(id, { workItemId: id, worktreePath: paths[i] });
+        await this.withProvisioningTelemetry({ sessionId, kind: 'forked_variant', variantCount: workItemIds.length }, async () => {
+            const resources = this.ensureResources(sessionId);
+            const instanceKeyPrefix = `f${(0, crypto_1.randomUUID)().slice(0, 8)}-`;
+            const paths = await withProvisionTimeout(this.worktrees.forkWorktreesFrom(sourcePath, sessionId, workItemIds.length, instanceKeyPrefix), this.provisionTimeoutMs);
+            await Promise.all(workItemIds.map((id, index) => this.registerWorktreeWorkspace(resources, {
+                workItemId: id,
+                worktreePath: paths[index],
+            })));
         });
     }
     async reportComplete(args) {
+        // Phase-timing anchor: lease→report (agent work) vs report→recorded
+        // (QA gate + post-processing) are attributed separately on
+        // `variant_completed` so latency work can tell them apart.
+        const reportReceivedAt = Date.now();
         // Cooperative abort short-circuit: if the work item was removed/cancelled
         // while in flight (delete-while-loading, cancel_variant, session cancel),
         // skip the schema and QA gates entirely — there is no point validating or
@@ -1956,18 +2256,23 @@ class AgentVariantsOrchestrator {
         const workItemKind = this.store.hasSession(args.sessionId)
             ? this.store.getWorkItemKind(args.sessionId, args.workItemId)
             : undefined;
-        // Contract validation: a `succeeded` static_preview report MUST carry the
-        // deliverable inline as `output.html` (with optional `css` / `js`). Agents
-        // sometimes default to writing files to disk and reporting back a file
-        // list — that leaves the orchestrator with no HTML to serve, the variant
-        // shows "Preview unavailable" in the panel, and `/api/variants/.../static`
-        // returns 404. Reject loudly so the agent self-corrects on retry instead
-        // of silently producing an empty-preview run.
-        if (args.status === 'succeeded' &&
+        const resolvedArgs = args.status === 'succeeded' &&
+            (workItemKind === 'static_preview' ||
+                workItemKind === 'refine_variant') &&
+            args.output === undefined
+            ? {
+                ...args,
+                output: this.readAssignedStaticArtifact(args.sessionId, args.workItemId),
+            }
+            : args;
+        // Contract validation keeps internal callers that provide an explicit
+        // static output honest. Host workers complete assigned artifacts without
+        // transporting the HTML through this report.
+        if (resolvedArgs.status === 'succeeded' &&
             this.store.hasSession(args.sessionId) &&
             (workItemKind === 'static_preview' ||
                 workItemKind === 'refine_variant') &&
-            !parseStaticPreviewOutput(normalizeOutput(args.output))) {
+            !parseStaticPreviewOutput(normalizeOutput(resolvedArgs.output))) {
             const telemetry = this.refinementTelemetryForWorkItem({
                 sessionId: args.sessionId,
                 workItemId: args.workItemId,
@@ -1978,25 +2283,25 @@ class AgentVariantsOrchestrator {
             if (telemetry) {
                 this.telemetry.trackAgentVariantsRefinementFailed?.(telemetry);
             }
-            throw new errors_1.AgentVariantsError('SCHEMA_VALIDATION_FAILED', `${workItemKind} report_variant_complete requires output.html (string, non-empty). ` +
-                'Pass the full HTML inline as output: { html: "<!doctype html>...", css?: "...", js?: "..." }. ' +
-                'Do NOT write the HTML to a file and report a file list — Rivet renders the HTML inline; on-disk files are not read.');
+            throw new errors_1.AgentVariantsError('SCHEMA_VALIDATION_FAILED', `${workItemKind} output.html must be a string and non-empty when explicit output is provided. Host workers should write the assigned index.html instead.`);
         }
         // QA gate: for `succeeded` static_preview reports, run preview QA
         // synchronously before recording success in the store. A failed QA
         // verdict converts the report to `failed` with code `VARIANT_QA_FAILED`
         // so the variant never reaches `ready` and `getVariants` can disable
         // its commit action.
+        const qaStartedAt = Date.now();
         const qaEval = workItemKind === 'refine_variant'
             ? null
-            : await this.evaluateQaForReport(args);
+            : await this.evaluateQaForReport(resolvedArgs);
+        const qaMs = qaEval === null ? null : Date.now() - qaStartedAt;
         // A `retry` verdict re-leases the variant for one regeneration (the
         // existing-project diff task-fit gate) instead of recording success —
         // short-circuit the normal record path.
         if (qaEval?.decision === 'retry') {
-            return this.handleQaRegenRetry(args, qaEval.qa);
+            return this.handleQaRegenRetry(resolvedArgs, qaEval.qa);
         }
-        let effectiveArgs = qaEval?.decision === 'fail_terminal' ? qaEval.overrideArgs : args;
+        let effectiveArgs = qaEval?.decision === 'fail_terminal' ? qaEval.overrideArgs : resolvedArgs;
         // For a successful refine_variant, swap the refined static preview into
         // place and persist history BEFORE recording success in the store. This
         // keeps the user-visible `refinement.status: succeeded` (and the snapshot
@@ -2016,7 +2321,7 @@ class AgentVariantsOrchestrator {
                 await this.handleStaticPreviewRefinement({
                     sessionId: args.sessionId,
                     workItemId: args.workItemId,
-                    output: args.output,
+                    output: effectiveArgs.output,
                 });
             }
             catch (err) {
@@ -2062,8 +2367,15 @@ class AgentVariantsOrchestrator {
             const approveStartedAt = resources?.approveStartedAt;
             const approveToCompleteMs = approveStartedAt !== undefined ? Date.now() - approveStartedAt : null;
             // Byte size of generated output for HTML vs full-stack comparison.
-            const outputBytes = estimateOutputBytes(args.output);
+            const outputBytes = estimateOutputBytes(effectiveArgs.output);
             const projectContextKind = this.store.getProjectContext(args.sessionId).kind;
+            // Execution mode mirrors the host work-item snapshot derivation so
+            // prod latency can finally segment vary vs create vs refine.
+            const mode = workItemKind !== undefined && isImplementationWorkItemKind(workItemKind)
+                ? this.store.isVaryForkWorkItem(args.sessionId, args.workItemId)
+                    ? 'vary'
+                    : DEFAULT_EXECUTION_MODE_BY_KIND[workItemKind]
+                : null;
             this.telemetry.track('agent_variants.variant_completed', {
                 source: 'mcp',
                 sessionId: args.sessionId,
@@ -2072,6 +2384,12 @@ class AgentVariantsOrchestrator {
                 attempt: args.attempt,
                 durationMs,
                 approveToCompleteMs,
+                kind: workItemKind ?? null,
+                mode,
+                // Phase split of `durationMs`: agent work vs server-side gating.
+                leaseToReportMs: leasedAt !== undefined ? reportReceivedAt - leasedAt : null,
+                reportProcessingMs: Date.now() - reportReceivedAt,
+                qaMs,
                 hasError: Boolean(effectiveArgs.error),
                 errorCode: effectiveArgs.error?.code ?? null,
                 isScaffold: resources?.scaffoldBaseWorkItemId === args.workItemId,
@@ -2151,7 +2469,7 @@ class AgentVariantsOrchestrator {
             void this.handleSucceededReport({
                 sessionId: args.sessionId,
                 workItemId: args.workItemId,
-                output: args.output,
+                output: effectiveArgs.output,
             }).catch((err) => {
                 log.error(`handleSucceededReport failed for ${args.sessionId}/${args.workItemId}`, err);
             });
@@ -2947,7 +3265,7 @@ class AgentVariantsOrchestrator {
         let cursor = 0;
         if (approveResult.scaffoldBaseWorkItemId) {
             resources.scaffoldBaseWorkItemId = approveResult.scaffoldBaseWorkItemId;
-            resources.worktrees.set(approveResult.scaffoldBaseWorkItemId, {
+            await this.registerWorktreeWorkspace(resources, {
                 workItemId: approveResult.scaffoldBaseWorkItemId,
                 worktreePath: paths[cursor],
             });
@@ -2956,7 +3274,10 @@ class AgentVariantsOrchestrator {
         for (const id of approveResult.codeGenWorkItemIds) {
             const p = paths[cursor];
             cursor += 1;
-            resources.worktrees.set(id, { workItemId: id, worktreePath: p });
+            await this.registerWorktreeWorkspace(resources, {
+                workItemId: id,
+                worktreePath: p,
+            });
         }
     }
     /**
@@ -3013,12 +3334,10 @@ class AgentVariantsOrchestrator {
         resources.freshDestinationParent = destinationParent;
         // Each code_gen item maps 1:1 to a fresh worktree. The scaffold_base
         // work item is internal — no dedicated worktree.
-        for (let i = 0; i < codeGenIds.length; i++) {
-            resources.worktrees.set(codeGenIds[i], {
-                workItemId: codeGenIds[i],
-                worktreePath: paths[i],
-            });
-        }
+        await Promise.all(codeGenIds.map((workItemId, index) => this.registerWorktreeWorkspace(resources, {
+            workItemId,
+            worktreePath: paths[index],
+        })));
         // Copy agent-planned assets (e.g. avatar.glb) into each worktree so
         // generated code can reference them via plan.referenceAs. Done before
         // the background install so the assets are on disk by the time the
@@ -3418,6 +3737,12 @@ class AgentVariantsOrchestrator {
                         return;
                     args.record.port = undefined;
                     args.record.devServerProcess = undefined;
+                    this.resources
+                        .get(args.sessionId)
+                        ?.previewFailures.set(args.workItemId, {
+                        reason: 'exited',
+                        portInUse: false,
+                    });
                     log.warn(`Variant ${args.workItemId} dev server exited unexpectedly (code=${code ?? 'null'}, signal=${signal ?? 'null'}); preview disabled`);
                     this.emitChange();
                 });
@@ -3565,6 +3890,11 @@ class AgentVariantsOrchestrator {
                         hasAssets: Boolean(resolvedAssetBase),
                     };
                     resources.staticPreviews.set(workItemId, record);
+                    const assignedWorkspace = resources.workspaceManager.getAssignedWorkspace(workItemId);
+                    if (assignedWorkspace?.kind === 'artifact_directory' &&
+                        assignedWorkspace.rootPath !== record.assetBase) {
+                        resources.workspaceManager.removeArtifactWorkspace(workItemId);
+                    }
                     if (this.store.getProjectContext(sessionId).kind === 'fresh') {
                         // History at `<workspacePath>/.rivet/variants/<sessionId>/<variantId>/`
                         // is the on-disk record for this generated project.
@@ -3721,6 +4051,14 @@ class AgentVariantsOrchestrator {
                 hasAssets: Boolean(resolvedAssetBase) || Boolean(previousRecord?.hasAssets),
             });
         }
+        const refinementWorkspace = resources.workspaceManager.getAssignedWorkspace(args.workItemId);
+        if (refinementWorkspace?.kind === 'artifact_directory' &&
+            dir === refinementWorkspace.rootPath) {
+            resources.workspaceManager.promoteArtifactWorkspace({
+                sourceWorkItemId: args.workItemId,
+                targetWorkItemId: input.variantId,
+            });
+        }
         // History persistence is best-effort, mirroring handleSucceededReport's
         // fire-and-forget persistence for freshly completed variants. A failure
         // here (e.g. a transient filesystem race) must not fail the refinement or
@@ -4666,17 +5004,30 @@ class AgentVariantsOrchestrator {
         const resources = this.resources.get(sessionId);
         if (!resources || resources.cleanupStarted)
             return;
+        if (this.uiClientCount > 0) {
+            this.scheduleActivePreviewIdleTimer(resources);
+            return;
+        }
         if (resources.activePreviewIdleStop) {
             await resources.activePreviewIdleStop;
             return;
         }
         const stop = (async () => {
+            const expiringWorkItemIds = Array.from(resources.worktrees.values())
+                .filter((record) => Boolean(record.devServerProcess))
+                .map((record) => record.workItemId);
             const stoppedCount = await this.stopAllDevServersForSession(resources);
             if (stoppedCount === 0)
                 return;
+            for (const workItemId of expiringWorkItemIds) {
+                resources.previewFailures.set(workItemId, {
+                    reason: 'idle_timeout',
+                    portInUse: false,
+                });
+            }
             log.info(`Stopped ${stoppedCount} idle variant dev server(s) for session ${sessionId}`);
-            // Keep the current behavior bounded: expired previews become unavailable
-            // until fresh generation or another path explicitly starts servers again.
+            // The next selection restores only the requested Rivet-owned preview;
+            // siblings remain stopped until the user asks to view them.
             try {
                 this.switchPreviewPort?.(null);
             }
@@ -4848,12 +5199,13 @@ class AgentVariantsOrchestrator {
                 log.warn(`cleanupSession (worktree removal) failed for ${sessionId}`, err);
             }
         }
-        // Remove fresh static_preview staging dirs (the per-variant directories
-        // materialized under workspacePath at report time). On 'committed' the
-        // commit flatten already moved/removed them; on cancel/shutdown they'd
-        // otherwise orphan under `.rivet/<slug>/`. Existing-mode static previews
-        // point at worktree dirs (cleaned by cleanupSession above), so scope this
-        // to fresh sessions — where every staticPreviews dir is Rivet staging.
+        // Assigned static workspaces are always Rivet-owned, including existing-
+        // project refinement work staged under `.rivet/variant-work` or /tmp.
+        // Fresh staticPreviews are also Rivet staging unless commit already moved
+        // the selected directory into the destination.
+        const ownedArtifactRoots = new Set(resources.workspaceManager.getOwnedArtifactRoots());
+        resources.workspaceManager.removeOwnedArtifactWorkspaces();
+        const staticDirectories = new Set();
         if (reason !== 'committed') {
             let isFresh = false;
             try {
@@ -4863,16 +5215,21 @@ class AgentVariantsOrchestrator {
                 isFresh = false;
             }
             if (isFresh) {
-                for (const sp of resources.staticPreviews.values()) {
-                    try {
-                        fs_1.default.rmSync(sp.assetBase, { recursive: true, force: true });
-                    }
-                    catch (err) {
-                        log.warn(`failed to remove static preview dir ${sp.assetBase} for ${sessionId}`, err);
+                for (const preview of resources.staticPreviews.values()) {
+                    if (!ownedArtifactRoots.has(preview.assetBase)) {
+                        staticDirectories.add(preview.assetBase);
                     }
                 }
             }
         }
+        for (const staticDirectory of staticDirectories) {
+            try {
+                fs_1.default.rmSync(staticDirectory, { recursive: true, force: true });
+            }
+            catch (err) {
+                log.warn(`failed to remove static preview dir ${staticDirectory} for ${sessionId}`, err);
+            }
+        }
         this.resources.delete(sessionId);
     }
     ensureResources(sessionId) {
@@ -4882,6 +5239,7 @@ class AgentVariantsOrchestrator {
                 sessionId,
                 worktrees: new Map(),
                 staticPreviews: new Map(),
+                workspaceManager: new VariantWorkspaceManager_1.VariantWorkspaceManager(),
                 cleanupStarted: false,
                 committedVariantIds: new Set(),
                 startedAt: Date.now(),
@@ -6023,12 +6381,16 @@ const defaultMaterializeProject = async (sourceWorktreePath, destinationPath) =>
 };
 /**
  * Synthesize a fallback brief body for a human-direct unified start slot.
- * Agent callers provide structured briefs before starting. Index/total are
- * unused for now but kept in the signature so future human-direct diversity
- * hints can be added without a call-site change.
+ * Agent callers provide structured briefs before starting. Human-direct
+ * batches get stable, slot-specific focus statements without another model
+ * call so workers do not independently invent overlapping directions.
  */
-function synthesizeUnifiedBriefBody(prompt, _index, _total) {
+function synthesizeUnifiedBriefBody(prompt, index, total) {
     const trimmed = prompt.trim().replace(/\s+/g, ' ').slice(0, 200);
-    return trimmed.length > 0 ? trimmed : 'variant';
+    const intent = trimmed.length > 0 ? trimmed : 'Create this variant';
+    if (total <= 1)
+        return intent;
+    const focus = FALLBACK_DIRECTION_FOCI[(Math.max(index, 1) - 1) % FALLBACK_DIRECTION_FOCI.length];
+    return `${intent} Direction ${index} of ${total}: ${focus}`;
 }
 //# sourceMappingURL=WorktreeOrchestrator.js.map