rivet-design 0.27.0 → 0.28.0

package/dist/routes/agentVariants.js

@@ -543,6 +543,7 @@ const createAgentVariantsRouter = (orchestrator, bridge, telemetry, variantHisto
             filesDir,
             entryPath: preview.entryPath,
             label: detail.manifest.label,
+            directionRef: detail.manifest.directionRef,
             description: detail.manifest.brief,
             references: detail.manifest.references,
             previewRoutes: detail.manifest.previewRoutes,
@@ -1058,6 +1059,7 @@ const createAgentVariantsRouter = (orchestrator, bridge, telemetry, variantHisto
                     sessionId: entry.manifest.sessionId,
                     variantId: entry.manifest.variantId,
                     requestId: entry.manifest.requestId,
+                    directionRef: entry.manifest.directionRef,
                     label: entry.manifest.label,
                     brief: entry.manifest.brief,
                     references: entry.manifest.references,
@@ -1507,6 +1509,7 @@ const createAgentVariantsRouter = (orchestrator, bridge, telemetry, variantHisto
                 filesDir,
                 entryPath: preview.entryPath,
                 label: detail.manifest.label,
+                directionRef: detail.manifest.directionRef,
                 description: detail.manifest.brief,
                 references: detail.manifest.references,
                 previewRoutes: detail.manifest.previewRoutes,
@@ -1580,6 +1583,7 @@ const createAgentVariantsRouter = (orchestrator, bridge, telemetry, variantHisto
                 filesDir,
                 entryPath: preview.entryPath,
                 label: detail.manifest.label,
+                directionRef: detail.manifest.directionRef,
                 description: detail.manifest.brief,
                 references: detail.manifest.references,
                 previewRoutes: detail.manifest.previewRoutes,

package/dist/routes/cli.js

@@ -102,8 +102,17 @@ const createCliRouter = (options) => {
             setImmediate(() => options.onShutdown?.());
             return;
         }
+        const isIdleRequired = req.body?.requireIdle === true;
         const activity = (0, runtimeActivity_1.classifyRuntimeActivity)(readStatus());
-        if (!admission.beginRetirement(activity, true)) {
+        if (!admission.beginRetirement(activity, !isIdleRequired)) {
+            if (isIdleRequired) {
+                res.status(409).json({
+                    reason: 'active_work',
+                    error: 'Rivet left the server running because it has active work or is already restarting.',
+                    upgrade: admission.status(),
+                });
+                return;
+            }
             res.status(409).json({
                 reason: 'server_retiring',
                 error: 'Rivet is already restarting. Retry after the runtime handoff completes.',

package/dist/server.js

@@ -212,6 +212,7 @@ const startServer = async (options) => {
         ? (0, crypto_1.randomBytes)(QUEUE_ACCESS_TOKEN_BYTES).toString('base64url')
         : null;
     const variantsOrchestrator = options.variantsRuntime?.orchestrator ?? options.agentVariantsOrchestrator;
+    await variantsOrchestrator?.loadDirectionRefs();
     const inlineStartTracker = (0, inlineStartTracker_1.createInlineStartTracker)();
     const runtimeAdmission = new RuntimeAdmission_1.RuntimeAdmission(telemetry_2.RIVET_VERSION);
     const variantsBridge = options.variantsRuntime?.bridge ?? sessionBridge;
@@ -251,11 +252,16 @@ const startServer = async (options) => {
     const editorHost = () => `${EMBEDDED_AGENT_LISTEN_HOST}:${listenPort}`;
     const isPreviewRequest = (req) => req.headers.host === new URL(previewOrigin).host &&
         (previewPort === undefined || req.socket.localPort === previewPort);
+    const rejectRequest = ({ req, res, reason, }) => {
+        log.warn(`Rejected ${req.method} ${req.path} with 403: ${reason}`);
+        telemetry?.trackRequestRejected(reason);
+        res.sendStatus(403);
+    };
     app.use((req, res, next) => {
         const requestHost = req.headers.host;
         const isEditorRequest = requestHost === editorHost() && req.socket.localPort === listenPort;
         if (!isEditorRequest && !isPreviewRequest(req)) {
-            res.sendStatus(403);
+            rejectRequest({ req, res, reason: 'host_not_allowed' });
             return;
         }
         next();
@@ -293,7 +299,7 @@ const startServer = async (options) => {
             return;
         }
         if (req.headers[editorAccess_2.EDITOR_ACCESS_TOKEN_HEADER]) {
-            res.sendStatus(403);
+            rejectRequest({ req, res, reason: 'editor_token_on_preview' });
             return;
         }
         const isAppApi = req.path.toLowerCase().startsWith('/api/') &&
@@ -438,7 +444,7 @@ const startServer = async (options) => {
             PREVIEW_PORT_ALLOWED_API_RE.test(req.path.toLowerCase());
         if (!isPreviewRequest(req) && isPreviewPath) {
             if (req.headers[editorAccess_2.EDITOR_ACCESS_TOKEN_HEADER]) {
-                res.sendStatus(403);
+                rejectRequest({ req, res, reason: 'editor_token_on_preview' });
                 return;
             }
             res.redirect(302, `${previewOrigin}${req.originalUrl}`);
@@ -511,7 +517,7 @@ const startServer = async (options) => {
     });
     app.post('/api/library/browser-launches', express_1.default.urlencoded({ extended: false }), async (req, res) => {
         if (!(0, middleware_1.isLocalBrowserRequest)(req))
-            return res.sendStatus(403);
+            return rejectRequest({ req, res, reason: 'origin_not_allowed' });
         const view = req.body?.view;
         if (view !== 'projects' && view !== 'references')
             return res.sendStatus(400);
@@ -591,14 +597,14 @@ const startServer = async (options) => {
                     return;
                 }
                 if (req.headers[editorAccess_2.EDITOR_ACCESS_TOKEN_HEADER]) {
-                    res.sendStatus(403);
+                    rejectRequest({ req, res, reason: 'editor_token_on_preview' });
                     return;
                 }
                 res.redirect(302, `${previewOrigin}${req.originalUrl}`);
                 return;
             }
             if (req.headers[editorAccess_2.EDITOR_ACCESS_TOKEN_HEADER]) {
-                res.sendStatus(403);
+                rejectRequest({ req, res, reason: 'editor_token_on_preview' });
                 return;
             }
             next();

package/dist/services/DependencyPreparationService.js

@@ -38,17 +38,40 @@ const INSTALL_ENVIRONMENT_PREFIXES = [
     'corepack_',
 ];
 const INSTALL_ENVIRONMENT_KEYS = new Set(['node_options', 'path']);
+const INSTALL_FAILURE_CAUSES = [
+    {
+        reasonCode: 'lockfile_outdated',
+        pattern: /^error Your lockfile needs to be updated, but yarn was run with `--frozen-lockfile`/m,
+        guidance: 'The lockfile does not match package.json. Update the lockfile in the project, commit it, then retry the preview.',
+    },
+    {
+        reasonCode: 'engine_incompatible',
+        pattern: /^error .+: The engine "node" is incompatible with this module/m,
+        guidance: 'The project or one of its dependencies does not support the active Node.js version. Switch to a Node.js version the project supports, then retry the preview.',
+    },
+    {
+        reasonCode: 'install_script_failed',
+        pattern: /^error .+: Command failed\.$/m,
+        guidance: 'A dependency install script failed. If it builds a native addon, switch to a Node.js version the project supports, then retry the preview.',
+    },
+];
+const UNRECOGNIZED_INSTALL_FAILURE = {
+    reasonCode: 'install_failed',
+    guidance: 'Fix the installation error, then retry the preview.',
+};
+const installFailureCause = (output) => INSTALL_FAILURE_CAUSES.find(({ pattern }) => pattern.test(output));
 const isInstallEnvironmentKey = (key) => {
     const lower = key.toLowerCase();
     return (INSTALL_ENVIRONMENT_PREFIXES.some((prefix) => lower.startsWith(prefix)) ||
         INSTALL_ENVIRONMENT_KEYS.has(lower));
 };
 const yarnAgentForVersion = (version) => Number.parseInt(version, 10) > 1 ? 'yarn@berry' : 'yarn';
-const preparationError = ({ reasonCode, message, detail = '', }) => new devServerError_1.DevServerStartError({
+const preparationError = ({ reasonCode, message, detail = '', exitCode, }) => new devServerError_1.DevServerStartError({
     message: detail ? `${message}\n${detail}` : message,
     reason: 'dependency_install_failed',
     portInUse: false,
     detail,
+    exitCode,
     reasonCode,
     summary: message,
 });
@@ -309,10 +332,13 @@ class DependencyPreparationService {
                 stdio: 'pipe',
             });
             let output = '';
+            let failureCause;
             let interruption;
             let settleTimer;
             const drain = (chunk) => {
-                output = (output + chunk.toString()).slice(-OUTPUT_TAIL_LIMIT);
+                const received = output + chunk.toString();
+                failureCause ??= installFailureCause(received);
+                output = received.slice(-OUTPUT_TAIL_LIMIT);
             };
             proc.stdout?.on('data', drain);
             proc.stderr?.on('data', drain);
@@ -351,14 +377,26 @@ class DependencyPreparationService {
             });
             proc.once('close', (code) => {
                 cleanup();
-                if (code === 0 && !interruption)
+                if (code === 0 && !interruption) {
                     resolve(output);
-                else
+                    return;
+                }
+                const command = `${project.name} ${args.join(' ')}`;
+                if (interruption) {
                     reject(preparationError({
-                        reasonCode: interruption ?? 'install_failed',
-                        message: `Dependency preparation failed: ${project.name} ${args.join(' ')} (${interruption ? 'cancelled or timed out' : `exit ${code}`}). Fix the installation error, then retry the preview.`,
+                        reasonCode: interruption,
+                        message: `Dependency preparation failed: ${command} (cancelled or timed out). ${UNRECOGNIZED_INSTALL_FAILURE.guidance}`,
                         detail: output.trim(),
                     }));
+                    return;
+                }
+                const { reasonCode, guidance } = failureCause ?? UNRECOGNIZED_INSTALL_FAILURE;
+                reject(preparationError({
+                    reasonCode,
+                    message: `Dependency preparation failed: ${command} (exit ${code}). ${guidance}`,
+                    detail: output.trim(),
+                    exitCode: code,
+                }));
             });
         });
     }

package/dist/services/FeatureFlagService.js

@@ -5,9 +5,9 @@ const telemetryPolicy_1 = require("../config/telemetryPolicy");
 const posthog_node_1 = require("posthog-node");
 const logger_1 = require("../utils/logger");
 const ConfigManager_1 = require("./ConfigManager");
+const posthog_1 = require("../config/posthog");
 const proxy_1 = require("../config/proxy");
 const log = (0, logger_1.createLogger)('FeatureFlagService');
-const POSTHOG_PUBLIC_API_KEY = 'phc_Ntj9tXHbS64XgYxlTfhglRmFivFsfm0AERph4ZlnNH';
 const remoteFlagsDisabled = () => {
     const v = process.env.RIVET_DISABLE_REMOTE_FLAGS;
     return v !== undefined && v !== 'false' && v !== '0';
@@ -20,7 +20,7 @@ class FeatureFlagService {
             return;
         }
         try {
-            this.posthog = new posthog_node_1.PostHog(POSTHOG_PUBLIC_API_KEY, {
+            this.posthog = new posthog_node_1.PostHog(posthog_1.POSTHOG_PUBLIC_API_KEY, {
                 host: proxy_1.POSTHOG_HOST,
                 flushAt: 1,
                 flushInterval: 0,

package/dist/services/ProjectLibrary.d.ts

@@ -12,6 +12,9 @@ interface VariantReference {
     sessionId: string;
     variantId: string;
 }
+interface LibraryListOptions {
+    isRemovedIncluded?: boolean;
+}
 export declare const currentLibraryRoot: (env?: NodeJS.ProcessEnv) => string;
 export declare class ProjectLibrary {
     readonly registry: ProjectRegistry;
@@ -45,7 +48,7 @@ export declare class ProjectLibrary {
         projectPath: string;
     }): Promise<void>;
     private listProject;
-    listVariants(projectId?: string): Promise<LibraryVariant[]>;
+    listVariants(projectId?: string, options?: LibraryListOptions): Promise<LibraryVariant[]>;
     private findVariant;
     variantSummary(reference: VariantReference): Promise<{
         summary: VariantHistorySummary;

package/dist/services/ProjectLibrary.js

@@ -23,6 +23,11 @@ const currentLibraryRoot = (env = process.env) => {
         : (0, ProjectRegistry_1.libraryRoot)({ channel });
 };
 exports.currentLibraryRoot = currentLibraryRoot;
+const isSameDirection = (left, right) => (!left.directionRef ||
+    !right.directionRef ||
+    left.directionRef === right.directionRef) &&
+    JSON.stringify({ ...left, directionRef: undefined }) ===
+        JSON.stringify({ ...right, directionRef: undefined });
 class ProjectLibrary {
     registry;
     isReadOnly;
@@ -158,7 +163,7 @@ class ProjectLibrary {
             });
         }
     }
-    async listProject(projectId) {
+    async listProject(projectId, options) {
         const project = this.registry.get(projectId);
         if (!project.isAvailable && project.storageKind === 'project')
             throw new Error('Working folder and project-local history are unavailable');
@@ -171,23 +176,23 @@ class ProjectLibrary {
             : history.listVariantsFromIndex({ projectPath }))).map((entry) => ({ ...entry, projectId, projectPath }))))).flat();
         const unique = new Map();
         for (const entry of entries) {
-            if (entry.manifest.status === 'removed' ||
-                entry.manifest.status === 'cancelled')
+            if (!options.isRemovedIncluded &&
+                (entry.manifest.status === 'removed' ||
+                    entry.manifest.status === 'cancelled'))
                 continue;
             const key = `${entry.manifest.sessionId}:${entry.manifest.variantId}`;
             const existing = unique.get(key);
-            if (existing &&
-                JSON.stringify(existing.manifest) !== JSON.stringify(entry.manifest))
+            if (existing && !isSameDirection(existing.manifest, entry.manifest))
                 throw new Error('Conflicting history identities across attached roots');
-            unique.set(key, entry);
+            unique.set(key, existing?.manifest.directionRef ? existing : entry);
         }
         return [...unique.values()];
     }
-    async listVariants(projectId) {
+    async listVariants(projectId, options = {}) {
         if (projectId)
-            return this.listProject(projectId);
+            return this.listProject(projectId, options);
         const projects = this.registry.list();
-        const results = await Promise.allSettled(projects.map((project) => this.listProject(project.id)));
+        const results = await Promise.allSettled(projects.map((project) => this.listProject(project.id, options)));
         return results
             .flatMap((result, index) => {
             if (result.status === 'fulfilled') {

package/dist/services/ProjectRuntimeService.d.ts

@@ -1,7 +1,15 @@
 import type { ProjectRegistry } from './ProjectRegistry';
+import { type ServerUnavailableReason } from '../cli/telemetry';
 interface ProjectRuntime {
     editorUrl: string;
 }
+export declare class ProjectRuntimeUnavailable extends Error {
+    readonly serverUnavailableReason?: ServerUnavailableReason;
+    constructor({ message, serverUnavailableReason, }: {
+        message: string;
+        serverUnavailableReason?: ServerUnavailableReason;
+    });
+}
 export declare class ProjectRuntimeService {
     private readonly registry;
     private readonly activations;

package/dist/services/ProjectRuntimeService.js

@@ -36,14 +36,24 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ProjectRuntimeService = void 0;
+exports.ProjectRuntimeService = exports.ProjectRuntimeUnavailable = void 0;
 const fs_1 = __importDefault(require("fs"));
 const zod_1 = require("zod");
 const installationChannel_1 = require("../install/installationChannel");
 const libraryErrors_1 = require("./libraryErrors");
 const serverHandshake_1 = require("../cli/serverHandshake");
 const shared_1 = require("../cli/commands/shared");
+const telemetry_1 = require("../cli/telemetry");
 const HEALTH_TIMEOUT_MS = 2_000;
+class ProjectRuntimeUnavailable extends Error {
+    serverUnavailableReason;
+    constructor({ message, serverUnavailableReason, }) {
+        super(message);
+        this.name = 'ProjectRuntimeUnavailable';
+        this.serverUnavailableReason = serverUnavailableReason;
+    }
+}
+exports.ProjectRuntimeUnavailable = ProjectRuntimeUnavailable;
 class ProjectRuntimeService {
     registry;
     activations = new Map();
@@ -118,7 +128,10 @@ class ProjectRuntimeService {
             writeEnvelope: () => { },
         });
         if (!result.envelope.ok)
-            throw new Error(result.envelope.error.message);
+            throw new ProjectRuntimeUnavailable({
+                message: result.envelope.error.message,
+                serverUnavailableReason: (0, telemetry_1.serverUnavailableReasonForEnvelope)(result.envelope),
+            });
         const data = zod_1.z
             .object({ editorUrl: zod_1.z.string().url() })
             .parse(result.envelope.data);

package/dist/services/TelemetryService.d.ts

@@ -3,6 +3,7 @@ import type { BrowserMetadata, DesignContextKind, ServerUnavailableReason, Varia
 import type { GuidanceErrorCode, GuidanceSelection } from '../types/guidance';
 import type { MCPAuthMethod, MCPAuthState, MCPOnboardingCorrelation, MCPOAuthCallbackResult } from './MCPOnboardingTelemetry';
 import { type MCPVariantsTelemetryMetadata } from './MCPVariantsTelemetry';
+export type RequestRejectionReason = 'host_not_allowed' | 'origin_not_allowed' | 'editor_token_on_preview';
 export type TelemetryOptions = {
     enabled?: boolean;
     source?: 'cli' | 'mcp' | 'core';
@@ -41,12 +42,14 @@ export declare class TelemetryService {
     trackGuidanceOperation(data: GuidanceOperation): void;
     trackProfileOperation(data: ProfileOperation): void;
     trackLibraryOperation(data: LibraryOperation): void;
+    trackRequestRejected(reason: RequestRejectionReason): void;
     private hashTelemetryValue;
     private posthog;
     private isEnabled;
     private readonly defaultSource;
     private readonly editor?;
     private readonly identifiedAccounts;
+    private readonly reportedRequestRejections;
     constructor(options?: boolean | TelemetryOptions);
     private get distinctId();
     identifyUser(identity?: AccountIdentity): void;
@@ -285,6 +288,7 @@ export declare class TelemetryService {
         hasPort: boolean;
         port?: number;
         durationMs?: number | null;
+        staticEntrySource?: string;
     }): void;
     trackAgentVariantsPreviewFailed(data: {
         sessionId: string;
@@ -298,6 +302,7 @@ export declare class TelemetryService {
         exitCode?: number | null;
         signal?: string | null;
         missingDeps?: boolean;
+        staticEntrySource?: string;
         error?: unknown;
     }): void;
     trackAgentVariantsPreviewSwitchStarted(data: {

package/dist/services/TelemetryService.js

@@ -11,10 +11,20 @@ const telemetryPolicy_1 = require("../config/telemetryPolicy");
 const pluginMetrics_1 = require("../config/pluginMetrics");
 const telemetryContract_1 = require("../config/telemetryContract");
 const failureReason_1 = require("../utils/failureReason");
+const posthog_1 = require("../config/posthog");
 const proxy_1 = require("../config/proxy");
 const MCPVariantsTelemetry_1 = require("./MCPVariantsTelemetry");
 const errorMessage_1 = require("../utils/errorMessage");
+const serverUnavailable_1 = require("../cli/serverUnavailable");
 const log = (0, logger_1.createLogger)('TelemetryService');
+const serverUnavailableReasonProperties = (error) => {
+    const reason = typeof error === 'object' && error !== null
+        ? Reflect.get(error, 'serverUnavailableReason')
+        : undefined;
+    return (0, serverUnavailable_1.isServerUnavailableReason)(reason)
+        ? { server_unavailable_reason: reason }
+        : {};
+};
 const KNOWN_MCP_EDITORS = new Set([
     'cursor',
     'codex',
@@ -32,7 +42,6 @@ const mcpEditorEventValue = (editor) => {
     }
     return 'other';
 };
-const POSTHOG_PUBLIC_API_KEY = 'phc_Ntj9tXHbS64XgYxlTfhglRmFivFsfm0AERph4ZlnNH';
 const HASH_PREFIX_LENGTH = 12;
 class TelemetryService {
     trackGuidanceOperation(data) {
@@ -61,8 +70,15 @@ class TelemetryService {
         this.track(`library_${data.operation}_${data.outcome}`, {
             duration_ms: data.durationMs,
             ...(0, failureReason_1.failureReasonCodeProperties)(data.error),
+            ...serverUnavailableReasonProperties(data.error),
         });
     }
+    trackRequestRejected(reason) {
+        if (this.reportedRequestRejections.has(reason))
+            return;
+        this.reportedRequestRejections.add(reason);
+        this.track('server_request_rejected', { reason });
+    }
     hashTelemetryValue(value) {
         return (0, crypto_1.createHash)('sha256')
             .update(value)
@@ -74,6 +90,7 @@ class TelemetryService {
     defaultSource;
     editor;
     identifiedAccounts = new Set();
+    reportedRequestRejections = new Set();
     constructor(options = true) {
         const opts = typeof options === 'boolean' ? { enabled: options } : options;
         this.isEnabled = (opts.enabled ?? true) && (0, telemetryPolicy_1.getTelemetryMode)() !== 'off';
@@ -81,7 +98,7 @@ class TelemetryService {
         this.editor = opts.editor;
         if (this.isEnabled) {
             try {
-                this.posthog = new posthog_node_1.PostHog(POSTHOG_PUBLIC_API_KEY, {
+                this.posthog = new posthog_node_1.PostHog(posthog_1.POSTHOG_PUBLIC_API_KEY, {
                     host: proxy_1.POSTHOG_HOST,
                     flushAt: 1,
                     flushInterval: 0,
@@ -682,6 +699,7 @@ class TelemetryService {
             has_port: data.hasPort,
             port: data.port,
             duration_ms: data.durationMs,
+            static_entry_source: data.staticEntrySource,
             source: 'mcp',
         });
     }
@@ -698,6 +716,7 @@ class TelemetryService {
             exit_code: data.exitCode,
             term_signal: data.signal,
             missing_deps: data.missingDeps,
+            static_entry_source: data.staticEntrySource,
             ...(0, failureReason_1.failureReasonProperties)(data.error),
             source: 'mcp',
         });

package/dist/services/VariantHistoryService.d.ts

@@ -3,6 +3,7 @@ import type { GuidanceDocument } from '../types/guidance';
 import { type ReferenceImage } from './referenceImages';
 import { type VariantReference } from '../types/variant-reference';
 import type { VariantHistoryStatus, VariantHistoryKind, PersistVariantPreview, VariantServeSpec, VariantDesignSource, VariantDeployment, VariantCanvasDeployment, VariantHistoryManifest } from '../types/variant-history';
+import type { DirectionRef } from '../types/direction-ref';
 export type { VariantHistoryStatus, VariantHistoryKind, VariantHistoryPreview, PersistVariantPreview, VariantTreePointer, VariantBasePointer, DevServerRecipe, VariantServeSpec, VariantHistoryArtifact, VariantDesignSource, VariantDeployment, VariantCanvasDeployment, VariantHistoryManifest, VariantHistorySessionFile, } from '../types/variant-history';
 import type { BundleMetadataStore } from '../storage/library/BundleMetadataStore';
 import { TreeStore } from './TreeStore';
@@ -13,6 +14,7 @@ export interface PersistVariantArgs {
     sessionId: string;
     variantId: string;
     requestId?: string;
+    directionRef?: DirectionRef;
     label: string;
     brief: string;
     references?: VariantReference[];
@@ -116,6 +118,12 @@ export declare class VariantHistoryService {
         label?: string;
         runLabel?: string;
     }): Promise<void>;
+    assignDirectionRef(args: {
+        projectPath: string;
+        sessionId: string;
+        variantId: string;
+        directionRef: DirectionRef;
+    }): Promise<void>;
     renameRun(args: {
         projectPath: string;
         sessionId: string;

package/dist/services/VariantHistoryService.js

@@ -203,6 +203,7 @@ class VariantHistoryService {
         let preservedDestinationPath;
         let preservedCreatedAt;
         let preservedRequestId;
+        let preservedDirectionRef;
         let preservedReferences;
         let preservedPreviewRoutes;
         let preservedTree;
@@ -219,6 +220,7 @@ class VariantHistoryService {
                 });
             preservedCreatedAt = prior.createdAt;
             preservedRequestId = prior.requestId;
+            preservedDirectionRef = prior.directionRef;
             preservedReferences = prior.references;
             preservedPreviewRoutes = prior.previewRoutes;
             preservedTree = prior.tree;
@@ -363,6 +365,9 @@ class VariantHistoryService {
             ...((args.requestId ?? preservedRequestId)
                 ? { requestId: args.requestId ?? preservedRequestId }
                 : {}),
+            ...((preservedDirectionRef ?? args.directionRef)
+                ? { directionRef: preservedDirectionRef ?? args.directionRef }
+                : {}),
             label: args.label,
             brief: args.brief,
             references: (0, variant_reference_1.mergeVariantReferences)(references),
@@ -527,6 +532,41 @@ class VariantHistoryService {
             manifest,
         });
     }
+    async assignDirectionRef(args) {
+        assertSafeId(args.sessionId, 'sessionId');
+        assertSafeId(args.variantId, 'variantId');
+        const bundle = this.bundleFor(args.projectPath);
+        if (bundle) {
+            bundle.updateVariant({
+                ...args,
+                update: (manifest) => {
+                    manifest.directionRef ??= args.directionRef;
+                },
+            });
+            return;
+        }
+        const manifestPath = path_1.default.join(this.variantDir(args.projectPath, args.sessionId, args.variantId), MANIFEST_FILENAME);
+        let manifest;
+        try {
+            const raw = await promises_1.default.readFile(manifestPath, 'utf8');
+            manifest = JSON.parse(raw);
+        }
+        catch (err) {
+            const code = (0, errnoCode_1.errnoCode)(err);
+            if (code !== 'ENOENT') {
+                log.warn(`assignDirectionRef: manifest read failed at ${manifestPath} (session ${args.sessionId} variant ${args.variantId})`, err);
+            }
+            return;
+        }
+        if (manifest.directionRef)
+            return;
+        manifest.directionRef = args.directionRef;
+        await writeManifestFile(manifestPath, manifest);
+        await this.projectManifestToIndex({
+            projectPath: args.projectPath,
+            manifest,
+        });
+    }
     async renameRun(args) {
         const entries = await this.listVariants({ projectPath: args.projectPath });
         const targets = entries.filter((entry) => {

package/dist/services/WorktreeManager.d.ts

@@ -23,6 +23,7 @@ export declare class WorktreeManager {
     createWorktrees(sessionId: string, count: number, instanceKeyPrefix?: string): Promise<string[]>;
     forkWorktreesFrom(sourceWorktreePath: string, sessionId: string, count: number, instanceKeyPrefix?: string): Promise<string[]>;
     getDiff(worktreePath: string): Promise<string>;
+    getChangedFiles(worktreePath: string): Promise<string[]>;
     getFreePort(): Promise<number>;
     findFreePortFrom(startPort: number, scanWindow?: number): Promise<number>;
     releasePort(port: number): void;

package/dist/services/WorktreeManager.js

@@ -276,6 +276,18 @@ class WorktreeManager {
         await git.raw(['add', '--intent-to-add', '.']).catch(() => { });
         return git.diff(['--binary', '--full-index', 'HEAD']);
     }
+    async getChangedFiles(worktreePath) {
+        const git = (0, simple_git_1.simpleGit)(worktreePath, GIT_OPTS);
+        await git.raw(['add', '--intent-to-add', '.']).catch(() => { });
+        const names = await git.raw([
+            'diff',
+            '--name-only',
+            '--diff-filter=d',
+            '-z',
+            'HEAD',
+        ]);
+        return names.split('\0').filter(Boolean);
+    }
     getFreePort() {
         return new Promise((resolve, reject) => {
             const server = net_1.default.createServer();

package/dist/services/createAgentVariantsOrchestrator.js

@@ -1,6 +1,11 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createAgentVariantsOrchestrator = exports.withVariantsSessionReplayLinking = void 0;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
 const index_core_1 = require("../index-core");
 const agent_variants_1 = require("../agent-variants");
 const devServerCommand_1 = require("../utils/devServerCommand");
@@ -69,11 +74,13 @@ const createAgentVariantsOrchestrator = (options) => {
                         targetPath: projectPath,
                         entryPath: options.staticEntry,
                     }).entryPath;
-                    log.info(`Resolved env for variants session ${sessionId}: static/${entryPath}`);
+                    const hasEntry = options.staticEntry !== undefined ||
+                        fs_1.default.existsSync(path_1.default.join(projectPath, entryPath));
+                    log.info(`Resolved env for variants session ${sessionId}: static/${hasEntry ? entryPath : '(no entry page)'}`);
                     return {
                         projectPath,
                         framework,
-                        entryPath,
+                        ...(hasEntry ? { entryPath } : {}),
                     };
                 }
                 const packageManager = await detection.detectPackageManager(projectPath);

package/dist/services/directionRefs.d.ts

@@ -0,0 +1,21 @@
+import type { DirectionAddress, DirectionCandidate, DirectionRef, DirectionResolution, DirectionSearchAddress } from '../types/direction-ref';
+import type { VariantHistoryManifest, VariantHistoryStatus } from '../types/variant-history';
+export declare const isDirectionActive: (status: VariantHistoryStatus) => boolean;
+type DirectionRefSource = {
+    manifest: Pick<VariantHistoryManifest, 'sessionId' | 'variantId' | 'label' | 'createdAt' | 'directionRef'>;
+};
+export declare const slugifyDirectionLabel: (label: string) => string;
+export declare const nextDirectionRef: (args: {
+    label: string;
+    taken: ReadonlySet<string>;
+}) => DirectionRef;
+export declare const withDirectionRefs: <Entry extends DirectionRefSource>(entries: readonly Entry[]) => Array<Entry & {
+    directionRef: DirectionRef;
+}>;
+export declare const parseDirectionAddress: (raw: string) => DirectionAddress | null;
+export declare const resolveDirectionAddress: (args: {
+    address: DirectionSearchAddress;
+    candidates: readonly DirectionCandidate[];
+}) => DirectionResolution;
+export {};
+//# sourceMappingURL=directionRefs.d.ts.map