rivet-design 0.27.0 → 0.27.1

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

@@ -0,0 +1,11 @@
+import type { VariantHistoryService } from '../services/VariantHistoryService';
+import type { DirectionRef } from '../types/direction-ref';
+export declare class DirectionRefReservations {
+    private readonly taken;
+    reserve(label: string): DirectionRef;
+    load(args: {
+        projectPath: string;
+        history: VariantHistoryService;
+    }): Promise<void>;
+}
+//# sourceMappingURL=DirectionRefReservations.d.ts.map

package/dist/agent-variants/DirectionRefReservations.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DirectionRefReservations = void 0;
+const directionRefs_1 = require("../services/directionRefs");
+const projectDirections_1 = require("../services/projectDirections");
+const logger_1 = require("../utils/logger");
+const log = (0, logger_1.createLogger)('DirectionRefReservations');
+class DirectionRefReservations {
+    taken = new Set();
+    reserve(label) {
+        const directionRef = (0, directionRefs_1.nextDirectionRef)({ label, taken: this.taken });
+        this.taken.add(directionRef);
+        return directionRef;
+    }
+    async load(args) {
+        let directions;
+        try {
+            directions = await (0, projectDirections_1.listProjectDirections)({
+                kind: 'history',
+                history: args.history,
+                projectPath: args.projectPath,
+            });
+        }
+        catch (error) {
+            log.warn('Direction ref history could not be listed', error);
+            return;
+        }
+        for (const direction of directions) {
+            this.taken.add(direction.directionRef);
+            if (direction.manifest.directionRef)
+                continue;
+            try {
+                await args.history.assignDirectionRef({
+                    projectPath: direction.projectPath,
+                    sessionId: direction.manifest.sessionId,
+                    variantId: direction.manifest.variantId,
+                    directionRef: direction.directionRef,
+                });
+            }
+            catch (error) {
+                log.warn(`Direction ref backfill failed for ${direction.manifest.sessionId}:${direction.manifest.variantId}`, error);
+            }
+        }
+    }
+}
+exports.DirectionRefReservations = DirectionRefReservations;
+//# sourceMappingURL=DirectionRefReservations.js.map

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

@@ -2,6 +2,8 @@ import type { GuidanceDocument } from '../types/guidance';
 import type { WorkerSelection } from '../types/change-request-types';
 import { type VariantReference } from '../types/variant-reference';
 import { type Brief, type ActiveVariantSnapshot, type LeasedWorkItemDescriptor, type ProjectContext, type Stage, type StartVariantsBriefContent, type StaticPreviewTargetElement, type Target, type TerminalSummary, type VariantContextBinding, type VariantContextBundle, type VariantQaResult, type VariantWorkItemContext, type WorkItem, type WorkItemKind, type WorkItemStatus, type WorkerFidelity, type WorkerRuntimeInfo } from './contracts';
+import { DirectionRefReservations } from './DirectionRefReservations';
+import type { DirectionRef } from '../types/direction-ref';
 import { type VariantWorkItemInput, type VariantWorkItemInputByKind, type VariantWorkItemKind } from './workItemInput';
 export declare const DEFAULT_LEASE_TTL_MS: number;
 export declare const SCAFFOLD_LEASE_TTL_MS: number;
@@ -60,7 +62,8 @@ export declare const buildImageRefs: (artifacts: ReadonlyArray<{
 export declare class SessionStore {
     private readonly sessions;
     private readonly clock;
-    constructor(clock?: SessionStoreClock);
+    readonly directionRefs: DirectionRefReservations;
+    constructor(clock?: SessionStoreClock, directionRefs?: DirectionRefReservations);
     propose(args: ProposeArgs): ProposeResult;
     reportBriefs(args: {
         sessionId: string;
@@ -163,6 +166,7 @@ export declare class SessionStore {
         references?: VariantReference[];
         previewRoutes?: string[];
         runLabel?: string;
+        sourceDirectionRef?: DirectionRef;
     }): {
         workItemId: string;
         briefId: string;
@@ -180,12 +184,17 @@ export declare class SessionStore {
         references?: VariantReference[];
         previewRoutes?: string[];
         runLabel?: string;
+        sourceDirectionRef?: DirectionRef;
         projectContext: ProjectContext;
     }): {
         sessionId: string;
         workItemId: string;
         briefId: string;
     };
+    claimDirectionRef(args: {
+        sessionId: string;
+        workItemId: string;
+    }): DirectionRef;
     private findAdoptedVariant;
     assignVariantPreviewRoutes(args: {
         sessionId: string;

package/dist/agent-variants/SessionStore.js

@@ -7,6 +7,7 @@ const crypto_1 = require("crypto");
 const errors_1 = require("./errors");
 const contracts_1 = require("./contracts");
 const briefContent_1 = require("./briefContent");
+const DirectionRefReservations_1 = require("./DirectionRefReservations");
 const runLabel_1 = require("./runLabel");
 const runPlan_1 = require("./runPlan");
 const workItemInput_1 = require("./workItemInput");
@@ -185,8 +186,10 @@ const resolveVariantWorkItemContext = (args) => {
 class SessionStore {
     sessions = new Map();
     clock;
-    constructor(clock = SYSTEM_CLOCK) {
+    directionRefs;
+    constructor(clock = SYSTEM_CLOCK, directionRefs = new DirectionRefReservations_1.DirectionRefReservations()) {
         this.clock = clock;
+        this.directionRefs = directionRefs;
     }
     propose(args) {
         const sessionId = args.sessionId ?? (0, crypto_1.randomUUID)();
@@ -345,6 +348,7 @@ class SessionStore {
                     input: {
                         briefId: brief.briefId,
                         briefLabel: brief.label,
+                        directionRef: this.directionRefs.reserve(brief.label),
                         briefBody: sel.bodyOverride ?? brief.body,
                         instruction: session.prompt,
                         guidance: session.guidance,
@@ -376,6 +380,7 @@ class SessionStore {
                     input: {
                         briefId: brief.briefId,
                         briefLabel: brief.label,
+                        directionRef: this.directionRefs.reserve(brief.label),
                         briefBody: sel.bodyOverride ?? brief.body,
                         instruction: session.prompt,
                         guidance: session.guidance,
@@ -582,6 +587,7 @@ class SessionStore {
                 guidance: args.guidance ?? [],
                 briefId: targetInput.briefId,
                 briefLabel: targetInput.briefLabel,
+                ...(0, workItemInput_1.shownDirectionRef)(targetInput),
                 briefBody: targetInput.briefBody,
                 references: targetInput.references,
                 ...(targetInput.briefNotes
@@ -660,6 +666,7 @@ class SessionStore {
                     },
                 }
                 : sourceInput.context;
+            const briefLabel = brief?.label ?? `${labelBase}${suffix}`;
             const item = {
                 id: (0, crypto_1.randomUUID)(),
                 kind: 'static_preview',
@@ -668,7 +675,8 @@ class SessionStore {
                 dependsOn: [],
                 input: {
                     briefId: `${sourceInput.briefId ?? 'v'}-vary-${(0, crypto_1.randomUUID)().slice(0, 8)}`,
-                    briefLabel: brief?.label ?? `${labelBase}${suffix}`,
+                    briefLabel,
+                    directionRef: this.directionRefs.reserve(briefLabel),
                     briefBody: brief?.body ?? prettyInstruction,
                     ...(brief?.notes ? { briefNotes: brief.notes } : {}),
                     ...(previewRoutes.length ? { previewRoutes } : {}),
@@ -757,6 +765,7 @@ class SessionStore {
                 input: {
                     briefId: brief.briefId,
                     briefLabel: brief.label,
+                    directionRef: this.directionRefs.reserve(brief.label),
                     briefBody: brief.body,
                     references: (0, variant_reference_1.mergeVariantReferences)(sourceInput?.references, context?.references),
                     instruction: args.instruction,
@@ -815,6 +824,9 @@ class SessionStore {
             input: {
                 briefId,
                 briefLabel: args.label,
+                ...(args.sourceDirectionRef
+                    ? { sourceDirectionRef: args.sourceDirectionRef }
+                    : {}),
                 ...(args.description ? { briefBody: args.description } : {}),
                 ...(args.runLabel ? { runLabel: args.runLabel } : {}),
                 adoptedFrom: { ...args.source },
@@ -854,6 +866,7 @@ class SessionStore {
             references: args.references,
             previewRoutes: args.previewRoutes,
             runLabel: args.runLabel,
+            sourceDirectionRef: args.sourceDirectionRef,
         });
         return {
             sessionId,
@@ -861,6 +874,15 @@ class SessionStore {
             briefId: adopted.briefId,
         };
     }
+    claimDirectionRef(args) {
+        const item = this.requireWorkItem(this.requireSession(args.sessionId), args.workItemId);
+        if (!(0, workItemInput_1.isVariantWorkItem)(item))
+            throw new errors_1.AgentVariantsError('WORK_ITEM_NOT_FOUND', `Work item ${item.id} is a ${item.kind} work item, not a direction`);
+        const directionRef = item.input.directionRef ??
+            this.directionRefs.reserve(item.input.briefLabel ?? '');
+        item.input.directionRef = directionRef;
+        return directionRef;
+    }
     findAdoptedVariant(session, source) {
         for (const item of session.workItems.values()) {
             if (item.removed || !(0, workItemInput_1.isVariantWorkItem)(item))
@@ -1427,6 +1449,7 @@ class SessionStore {
                     ? { previewRoutes: [...input.previewRoutes] }
                     : {}),
                 briefId: input.briefId ?? '',
+                ...(0, workItemInput_1.shownDirectionRef)(input),
                 label: input.briefLabel ?? 'Variant',
                 references: input.references,
                 status: item.status,

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

@@ -0,0 +1,6 @@
+export declare class WorkItemRequestTimes {
+    private readonly requestedAt;
+    record(workItemIds: readonly string[], requestedAt: number): void;
+    elapsedSinceRequestMs(workItemId: string, at: number | undefined): number | null;
+}
+//# sourceMappingURL=WorkItemRequestTimes.d.ts.map

package/dist/agent-variants/WorkItemRequestTimes.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WorkItemRequestTimes = void 0;
+class WorkItemRequestTimes {
+    requestedAt = new Map();
+    record(workItemIds, requestedAt) {
+        for (const workItemId of workItemIds) {
+            if (!this.requestedAt.has(workItemId)) {
+                this.requestedAt.set(workItemId, requestedAt);
+            }
+        }
+    }
+    elapsedSinceRequestMs(workItemId, at) {
+        const requestedAt = this.requestedAt.get(workItemId);
+        if (requestedAt === undefined || at === undefined)
+            return null;
+        return at - requestedAt;
+    }
+}
+exports.WorkItemRequestTimes = WorkItemRequestTimes;
+//# sourceMappingURL=WorkItemRequestTimes.js.map

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

@@ -4,7 +4,7 @@ import type { VariantStartRequest, VariantStartResult } from './variant-start-ty
 import { AgentVariantsError } from './errors';
 import { SessionStore, type ApprovedBriefSelection, type ApproveResult, type ProposeArgs, type ProposeResult, type ReportCompleteResult, type RequestWorkResult } from './SessionStore';
 import type { ActiveProjectContext, AdoptPastVariantArgs, BootstrapPastVariantSessionArgs, BootstrapPastVariantSessionResult, ActiveVariantSnapshot, Brief, ProjectContext, Stage, TerminalSummary, VariantContextBinding, HostVariantWorkItemSnapshot, VariantQaResult, WorkItemStatus } from './contracts';
-import type { VariantWorkItemInput } from './workItemInput';
+import { type VariantWorkItemInput } from './workItemInput';
 import { VariantHistoryService } from '../services/VariantHistoryService';
 import type { MCPVariantsTelemetryMetadata } from '../services/MCPVariantsTelemetry';
 import type { ProjectEnvironment, WorktreeManagerLike } from './variant-project-runtime';
@@ -249,6 +249,7 @@ export declare class AgentVariantsOrchestrator {
     private readonly pendingHistoryPersists;
     private trackHistoryPersist;
     settleHistoryPersists(): Promise<void>;
+    loadDirectionRefs(): Promise<void>;
     private getSavedVariant;
     isHistoryDurableForRestart(isForced?: boolean): Promise<boolean>;
     private persistCompletedExistingVariant;

package/dist/agent-variants/WorktreeOrchestrator.js

@@ -8,6 +8,7 @@ const workItemContextFiles_1 = require("./workItemContextFiles");
 const staticPreviewFiles_1 = require("./staticPreviewFiles");
 const workItemPreviewRoutes_1 = require("./workItemPreviewRoutes");
 const staticPreviewRefinements_1 = require("./staticPreviewRefinements");
+const WorkItemRequestTimes_1 = require("./WorkItemRequestTimes");
 const crypto_1 = require("crypto");
 const events_1 = require("events");
 const fs_1 = __importDefault(require("fs"));
@@ -20,6 +21,7 @@ const workItemBriefing_1 = require("./workItemBriefing");
 const briefContent_1 = require("./briefContent");
 const runLabel_1 = require("./runLabel");
 const previewQa_1 = require("./previewQa");
+const workItemInput_1 = require("./workItemInput");
 const WorkspaceInventory_1 = require("./WorkspaceInventory");
 const WorkspaceProvisioning_1 = require("./WorkspaceProvisioning");
 const PreviewRuntime_1 = require("./PreviewRuntime");
@@ -31,6 +33,7 @@ const variantsTelemetry_1 = require("./variantsTelemetry");
 const variantWorkspaceFiles_1 = require("./variantWorkspaceFiles");
 const errorMessage_1 = require("../utils/errorMessage");
 const pathContainment_1 = require("../utils/pathContainment");
+const existingStaticEntry_1 = require("./existingStaticEntry");
 var variantWorkspaceFiles_2 = require("./variantWorkspaceFiles");
 Object.defineProperty(exports, "buildStaticPreviewDocument", { enumerable: true, get: function () { return variantWorkspaceFiles_2.buildStaticPreviewDocument; } });
 const log = (0, logger_1.createLogger)('AgentVariantsOrchestrator');
@@ -426,6 +429,7 @@ class AgentVariantsOrchestrator {
                 leaseExpiresAt: item.leaseExpiresAt,
                 workspace,
                 mode,
+                ...(0, workItemInput_1.shownDirectionRef)(input),
                 direction: {
                     label: input.briefLabel ?? 'Variant',
                     brief: input.briefBody ?? input.instruction ?? 'Create this variant',
@@ -487,6 +491,7 @@ class AgentVariantsOrchestrator {
         resources.currentRoundStartedAt = startedAt;
         resources.currentRoundMode = args.mode;
         resources.currentRoundWorkItemIds = workItemIds;
+        resources.requestTimes.record(workItemIds ?? [], startedAt);
         const projectContext = this.store.getProjectContext(args.sessionId);
         this.telemetry.trackAgentVariantsRoundStarted?.({
             sessionId: args.sessionId,
@@ -565,6 +570,7 @@ class AgentVariantsOrchestrator {
         const workItemIds = [...args.workItemIds];
         round.workItemIds = workItemIds;
         resources.currentRoundWorkItemIds = workItemIds;
+        resources.requestTimes.record(workItemIds, round.startedAt);
         this.completeTerminalVariantsRounds(args.sessionId);
     }
     completeTerminalVariantsRounds(sessionId) {
@@ -646,6 +652,8 @@ class AgentVariantsOrchestrator {
         };
     }
     trackRefinementLeased(args) {
+        const requestTimes = this.resources.get(args.sessionId)?.requestTimes;
+        const leasedAt = Date.now();
         for (const item of args.lease.leasedWorkItems) {
             const telemetry = this.refinementTelemetryForWorkItem({
                 sessionId: args.sessionId,
@@ -657,6 +665,7 @@ class AgentVariantsOrchestrator {
             this.telemetry.trackAgentVariantsRefinementLeased?.({
                 ...telemetry,
                 leaseDurationMs: args.lease.leaseTtlMs,
+                queueWaitMs: requestTimes?.elapsedSinceRequestMs(item.id, leasedAt) ?? undefined,
                 workItemCount: 1,
             });
         }
@@ -788,13 +797,16 @@ class AgentVariantsOrchestrator {
         }
     }
     beginStaticPreviewRefinements(args) {
-        return (0, staticPreviewRefinements_1.createStaticPreviewRefinements)({
+        const result = (0, staticPreviewRefinements_1.createStaticPreviewRefinements)({
             request: args,
             store: this.store,
             telemetry: this.telemetry,
             getStaticPreviewHtml: (sessionId, workItemId) => this.getStaticPreviewHtml(sessionId, workItemId),
             emitChange: () => this.emitChange(),
         });
+        const requestTimes = this.resources.get(args.sessionId)?.requestTimes;
+        requestTimes?.record(result.createdWorkItemIds, Date.now());
+        return result;
     }
     async adoptPastVariant(args) {
         const { assetBase, entryPath, hasAssets } = await (0, staticPreviewFiles_1.resolveStaticPreviewFiles)({
@@ -810,6 +822,7 @@ class AgentVariantsOrchestrator {
             references: args.references,
             previewRoutes: args.previewRoutes,
             runLabel: args.runLabel,
+            sourceDirectionRef: args.directionRef,
         });
         this.telemetry.trackAgentVariantsRequestStarted?.({
             sessionId: args.sessionId,
@@ -859,6 +872,7 @@ class AgentVariantsOrchestrator {
                 references: args.references,
                 previewRoutes: args.previewRoutes,
                 runLabel: args.runLabel,
+                directionRef: args.directionRef,
             });
             return {
                 sessionId: usableSessionId,
@@ -880,6 +894,7 @@ class AgentVariantsOrchestrator {
             references: args.references,
             previewRoutes: args.previewRoutes,
             runLabel: args.runLabel,
+            sourceDirectionRef: args.directionRef,
             projectContext: args.projectContext,
         });
         this.activeSessionId = created.sessionId;
@@ -1548,6 +1563,8 @@ class AgentVariantsOrchestrator {
             const durationMs = leasedAt !== undefined ? Date.now() - leasedAt : null;
             const approveStartedAt = resources?.approveStartedAt;
             const approveToCompleteMs = approveStartedAt !== undefined ? Date.now() - approveStartedAt : null;
+            const requestTimes = resources?.requestTimes;
+            const elapsedSinceRequestMs = (at) => requestTimes?.elapsedSinceRequestMs(args.workItemId, at) ?? null;
             const outputBytes = (0, variantWorkspaceFiles_1.estimateOutputBytes)(effectiveArgs.output);
             const projectContextKind = this.store.getProjectContext(args.sessionId).kind;
             const mode = workItemKind !== undefined && isImplementationWorkItemKind(workItemKind)
@@ -1563,6 +1580,8 @@ class AgentVariantsOrchestrator {
                 attempt: args.attempt,
                 durationMs,
                 approveToCompleteMs,
+                requestToCompleteMs: elapsedSinceRequestMs(Date.now()),
+                queueWaitMs: elapsedSinceRequestMs(leasedAt),
                 kind: workItemKind ?? null,
                 mode,
                 leaseToReportMs: leasedAt !== undefined ? reportReceivedAt - leasedAt : null,
@@ -2094,12 +2113,24 @@ class AgentVariantsOrchestrator {
         catch (err) {
             log.warn(`getDiff failed for ${record.worktreePath}`, err);
         }
+        const staticEntryResolution = isFresh
+            ? Promise.resolve(undefined)
+            : (0, existingStaticEntry_1.resolveExistingStaticPreviewEntry)({
+                sessionId,
+                record,
+                resolveEnv: this.resolveEnv,
+                worktrees: this.worktrees,
+                telemetry: this.telemetry,
+            });
         if (!isFresh) {
-            this.trackHistoryPersist(this.persistCompletedExistingVariant({
+            this.trackHistoryPersist(staticEntryResolution
+                .then((staticEntry) => this.persistCompletedExistingVariant({
                 sessionId,
                 workItemId,
                 diff: record.diff ?? '',
-            }).catch((err) => {
+                staticEntry,
+            }))
+                .catch((err) => {
                 log.warn(`persistCompletedExistingVariant failed for ${sessionId}/${workItemId}`, err);
             }));
         }
@@ -2111,12 +2142,11 @@ class AgentVariantsOrchestrator {
                 log.warn(`persistCompletedArtifactVariant failed for ${sessionId}/${workItemId}`, err);
             }));
         }
-        if (!isFresh) {
-            const staticPreview = await this.registerExistingStaticPreview(sessionId, workItemId, record);
-            if (staticPreview !== 'not_static') {
-                this.emitChange();
-                return;
-            }
+        const staticEntry = await staticEntryResolution;
+        if (staticEntry) {
+            await this.registerExistingStaticPreview(sessionId, workItemId, staticEntry);
+            this.emitChange();
+            return;
         }
         await this.previewRuntime.startVariant({
             sessionId,
@@ -2224,6 +2254,12 @@ class AgentVariantsOrchestrator {
             await Promise.allSettled([...this.pendingHistoryPersists]);
         }
     }
+    loadDirectionRefs() {
+        return this.store.directionRefs.load({
+            projectPath: this.getProjectPath(),
+            history: this.variantHistory,
+        });
+    }
     async getSavedVariant(args) {
         const saved = await this.variantHistory.getVariant(args);
         if (saved)
@@ -2297,16 +2333,9 @@ class AgentVariantsOrchestrator {
             return;
         }
         const record = this.workspaceInventory.getWorktree(args.sessionId, args.workItemId);
-        let sourceDir;
-        const staticEntryPath = env.framework === 'static' ? env.entryPath : undefined;
-        if (env.framework === 'static' && record) {
-            try {
-                sourceDir = await this.worktrees.getProjectCwdInWorktree(record.worktreePath);
-            }
-            catch (err) {
-                log.warn(`persistCompletedExistingVariant: static snapshot path failed for ${args.sessionId}/${args.workItemId}`, err);
-            }
-        }
+        const staticSource = args.staticEntry?.kind === 'found' ? args.staticEntry : undefined;
+        const sourceDir = staticSource?.projectDirectory;
+        const staticEntryPath = staticSource?.entryPath;
         const input = this.store.requireVariantWorkItemInput({
             sessionId: args.sessionId,
             workItemId: args.workItemId,
@@ -2333,7 +2362,7 @@ class AgentVariantsOrchestrator {
                 recipe: (0, variantWorkspaceFiles_1.buildServeRecipeFromResolved)(record.worktreePath, runningPreview.command, runningPreview.port),
             };
         }
-        else if (record) {
+        else if (record && env.framework !== 'static') {
             try {
                 const dev = await this.previewRuntime.resolveCommand(args.sessionId, record.worktreePath, RECIPE_PORT_SENTINEL, false);
                 serve = {
@@ -2350,6 +2379,7 @@ class AgentVariantsOrchestrator {
             sessionId: args.sessionId,
             variantId: args.workItemId,
             ...(input.requestId ? { requestId: input.requestId } : {}),
+            directionRef: this.store.claimDirectionRef(args),
             label: input.briefLabel,
             brief: input.briefBody,
             references: input.references,
@@ -2380,92 +2410,74 @@ class AgentVariantsOrchestrator {
                 : {}),
         });
     }
-    async registerExistingStaticPreview(sessionId, workItemId, record) {
-        let env;
-        try {
-            env = await this.resolveEnv(sessionId);
-        }
-        catch (err) {
-            log.warn(`registerExistingStaticPreview: resolveEnv failed for ${sessionId}`, err);
-            return 'not_static';
-        }
-        if (env.framework !== 'static')
-            return 'not_static';
-        const previewStartedAt = Date.now();
-        (0, variantsTelemetry_1.trackPreviewStarted)(this.telemetry, {
-            sessionId,
-            variantId: workItemId,
-            projectContextKind: 'existing',
-            previewKind: 'static_artifact',
-        });
+    async registerExistingStaticPreview(sessionId, workItemId, entry) {
         const resources = this.resources.get(sessionId);
         if (!resources)
-            return 'unavailable';
+            return;
         const input = this.store.getVariantWorkItemInput(sessionId, workItemId);
         if (!input?.briefId)
-            return 'unavailable';
-        let projectCwd;
-        try {
-            projectCwd = await this.worktrees.getProjectCwdInWorktree(record.worktreePath);
-        }
-        catch (err) {
-            log.warn(`registerExistingStaticPreview: project cwd failed for ${sessionId}/${workItemId}`, err);
-            return 'unavailable';
-        }
-        const entryFile = path_1.default.join(projectCwd, env.entryPath);
-        try {
-            await fs_1.default.promises.access(entryFile, fs_1.default.constants.R_OK);
-        }
-        catch (err) {
-            log.warn(`registerExistingStaticPreview: no entry HTML at ${entryFile} for ${sessionId}/${workItemId}; preview unavailable`, err);
-            (0, variantsTelemetry_1.trackPreviewFailed)(this.telemetry, {
-                sessionId,
-                variantId: workItemId,
-                projectContextKind: 'existing',
-                previewKind: 'static_artifact',
-                errorCode: 'STATIC_PREVIEW_ENTRY_MISSING',
-                reason: 'missing_static_entry',
-                durationMs: Date.now() - previewStartedAt,
-            });
-            this.previewRuntime.setFailure(sessionId, workItemId, {
-                reason: 'missing_static_entry',
-                portInUse: false,
-            });
-            return 'unavailable';
+            return;
+        switch (entry.kind) {
+            case 'unresolved':
+                return;
+            case 'missing':
+                log.warn(`registerExistingStaticPreview: no entry page (${entry.source}) for ${sessionId}/${workItemId}; preview unavailable`);
+                (0, variantsTelemetry_1.trackPreviewFailed)(this.telemetry, {
+                    sessionId,
+                    variantId: workItemId,
+                    projectContextKind: 'existing',
+                    previewKind: 'static_artifact',
+                    errorCode: 'STATIC_PREVIEW_ENTRY_MISSING',
+                    reason: 'missing_static_entry',
+                    durationMs: Date.now() - entry.startedAt,
+                    staticEntrySource: entry.source,
+                });
+                this.previewRuntime.setFailure(sessionId, workItemId, {
+                    reason: 'missing_static_entry',
+                    portInUse: false,
+                    detail: entry.detail,
+                });
+                return;
+            case 'found':
+                break;
+            default: {
+                const unhandled = entry;
+                throw new Error(`Unhandled static entry ${JSON.stringify(unhandled)}`);
+            }
         }
         let dir;
         try {
-            dir = fs_1.default.realpathSync(projectCwd);
+            dir = fs_1.default.realpathSync(entry.projectDirectory);
         }
         catch {
-            dir = projectCwd;
+            dir = entry.projectDirectory;
         }
         let siteFallbackBase;
         try {
-            const hostRealRoot = fs_1.default.realpathSync(env.projectPath);
+            const hostRealRoot = fs_1.default.realpathSync(entry.hostProjectPath);
             if (hostRealRoot !== dir)
-                siteFallbackBase = path_1.default.join(hostRealRoot, path_1.default.dirname(env.entryPath));
+                siteFallbackBase = path_1.default.join(hostRealRoot, path_1.default.dirname(entry.entryPath));
         }
         catch { }
         this.workspaceInventory.setStaticPreview(sessionId, {
             workItemId,
             briefId: input.briefId,
-            entryPath: path_1.default.basename(env.entryPath),
-            assetBase: path_1.default.dirname(path_1.default.join(dir, env.entryPath)),
+            entryPath: path_1.default.basename(entry.entryPath),
+            assetBase: path_1.default.dirname(path_1.default.join(dir, entry.entryPath)),
             hasAssets: true,
             ...(siteFallbackBase ? { assetFallbackBase: siteFallbackBase } : {}),
         });
         this.previewRuntime.clearFailure(sessionId, workItemId);
-        log.info(`Variant ${workItemId} served as a static preview (existing/static, no dev server; root ${projectCwd})`);
+        log.info(`Variant ${workItemId} served as a static preview (existing/static, no dev server; root ${entry.projectDirectory})`);
         (0, variantsTelemetry_1.trackPreviewReady)(this.telemetry, {
             sessionId,
             variantId: workItemId,
             projectContextKind: 'existing',
             previewKind: 'static_artifact',
             hasPort: false,
-            durationMs: Date.now() - previewStartedAt,
+            durationMs: Date.now() - entry.startedAt,
+            staticEntrySource: entry.source,
         });
-        return 'registered';
     }
     async prepareArtifactBase(sessionId) {
         const { projectPath } = await this.resolveEnv(sessionId);
@@ -2478,7 +2490,7 @@ class AgentVariantsOrchestrator {
     async createArtifactDiff(args) {
         const base = await this.prepareArtifactBase(args.sessionId);
         const env = await this.resolveEnv(args.sessionId);
-        const entryPath = env.framework === 'static' ? env.entryPath : 'index.html';
+        const entryPath = (env.framework === 'static' && env.entryPath) || 'index.html';
         const files = (0, staticPreviewFiles_1.prepareStaticPreviewProjectFiles)({
             sourceDir: args.sourceDir,
             entryPath,
@@ -2598,6 +2610,7 @@ class AgentVariantsOrchestrator {
                 sessionId: args.sessionId,
                 variantId: args.workItemId,
                 ...(input.requestId ? { requestId: input.requestId } : {}),
+                directionRef: this.store.claimDirectionRef(args),
                 label: input.briefLabel,
                 brief: input.briefBody ?? '',
                 references: input.references,
@@ -2746,6 +2759,7 @@ class AgentVariantsOrchestrator {
                 startedAt: Date.now(),
                 nextRoundIndex: 0,
                 rounds: new Map(),
+                requestTimes: new WorkItemRequestTimes_1.WorkItemRequestTimes(),
                 leasedAt: new Map(),
                 qaResults: new Map(),
                 qaRegenRetried: new Set(),

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

@@ -1,5 +1,6 @@
 import type { GuidanceDocument } from '../types/guidance';
 import type { WorkerSelection } from '../types/change-request-types';
+import type { DirectionRef } from '../types/direction-ref';
 import { type VariantReference } from '../types/variant-reference';
 import { z } from 'zod/v3';
 import { ERROR_CODES, type ErrorCode } from './errors';
@@ -6343,6 +6344,7 @@ export interface SavedVariantPreview {
     references?: VariantReference[];
     previewRoutes?: string[];
     runLabel?: string;
+    directionRef?: DirectionRef;
 }
 export interface AdoptPastVariantArgs extends SavedVariantPreview {
     sessionId: string;
@@ -6361,6 +6363,7 @@ export interface ActiveVariantSnapshot {
     previewRoutes?: string[];
     workItemId: string;
     briefId: string;
+    directionRef?: DirectionRef;
     label: string;
     status: WorkItemStatus;
     workItemKind?: 'code_gen' | 'static_preview';
@@ -6443,6 +6446,7 @@ export interface HostVariantImplementationWorkItemSnapshot extends HostVariantWo
     kind: 'static_preview' | 'refine_variant' | 'code_gen';
     workspace: VariantAssignedWorkspace;
     mode: VariantExecutionMode;
+    directionRef?: DirectionRef;
     direction: VariantWorkerDirection;
     fidelity?: WorkerFidelity;
     sourceDirection?: VariantWorkerDirection;