rivet-design 0.27.0 → 0.27.1

package/dist/cli/commands/variants.js

@@ -50,6 +50,7 @@ const handoff_1 = require("../handoff");
 const callerModel_1 = require("../callerModel");
 const shared_1 = require("./shared");
 const elementSelector_1 = require("./elementSelector");
+const directionTarget_1 = require("./directionTarget");
 const hostWorkNextAction_1 = require("../hostWorkNextAction");
 const runLabel_1 = require("../../agent-variants/runLabel");
 const contracts_1 = require("../../agent-variants/contracts");
@@ -116,44 +117,22 @@ const LIST_FLAG_SPEC = {
 const GET_FLAG_SPEC = {
     detail: { takesValue: false },
 };
-const parseVariantTarget = (raw) => {
-    if (raw === undefined) {
+const START_TARGET_USAGE = 'Usage: --target <directionRef>|<sessionId>:<variantId> (example: --target warm-editorial-green)';
+const GET_USAGE = 'Usage: rivet variants get <directionRef>|last|[<projectId>/]<sessionId>:<variantId> [--detail] [--project <path>]';
+const resolveStartTarget = async (args) => {
+    if (args.raw === undefined)
         return { ok: true };
-    }
-    const separatorIndex = raw.indexOf(':');
-    if (separatorIndex <= 0 || separatorIndex === raw.length - 1) {
-        return {
-            ok: false,
-            message: 'Usage: --target <sessionId>:<variantId> (example: --target abc:def)',
-        };
-    }
-    const sessionId = raw.slice(0, separatorIndex).trim();
-    const variantId = raw.slice(separatorIndex + 1).trim();
-    if (!sessionId || !variantId) {
-        return {
-            ok: false,
-            message: 'Usage: --target <sessionId>:<variantId> (example: --target abc:def)',
-        };
-    }
+    const resolved = await (0, directionTarget_1.resolveDirectionTarget)({
+        command: START_COMMAND,
+        projectPath: args.projectPath,
+        input: args.raw,
+        usage: START_TARGET_USAGE,
+    });
+    if (!resolved.ok)
+        return resolved;
+    const { sessionId, variantId } = resolved.target;
     return { ok: true, target: { kind: 'variant', sessionId, variantId } };
 };
-const variantReferenceFromString = (raw) => {
-    if (!raw)
-        return null;
-    const projectSeparator = raw.indexOf('/');
-    const projectId = projectSeparator === -1 ? undefined : raw.slice(0, projectSeparator);
-    const direction = projectSeparator === -1 ? raw : raw.slice(projectSeparator + 1);
-    if (projectSeparator !== -1 && (!projectId || direction.includes('/')))
-        return null;
-    const variantSeparator = direction.indexOf(':');
-    if (variantSeparator <= 0 || variantSeparator === direction.length - 1)
-        return null;
-    if (direction.indexOf(':', variantSeparator + 1) !== -1)
-        return null;
-    const sessionId = direction.slice(0, variantSeparator).trim();
-    const variantId = direction.slice(variantSeparator + 1).trim();
-    return sessionId && variantId ? { projectId, sessionId, variantId } : null;
-};
 const parseJsonFlag = (command, name, raw) => {
     if (raw === undefined) {
         return { ok: true };
@@ -437,7 +416,7 @@ const handleVariantsStart = async (args, options) => {
     }
     const instruction = (0, flags_1.stringFlag)(context.flags, 'instruction');
     if (!instruction?.trim()) {
-        return (0, envelope_1.errorResult)(START_COMMAND, 'USAGE_ERROR', 'Usage: rivet variants start --instruction <text> [--run-label <text>] [--briefs <json>] [--count N] [--fidelity low|medium|high] [--element <selector>] [--files <json>] [--fresh] [--context-images <json>] [--context-assets <json>] [--reference-pages <json>] [--reference-videos <json>] [--target <sessionId>:<variantId>]');
+        return (0, envelope_1.errorResult)(START_COMMAND, 'USAGE_ERROR', 'Usage: rivet variants start --instruction <text> [--run-label <text>] [--briefs <json>] [--count N] [--fidelity low|medium|high] [--element <selector>] [--files <json>] [--fresh] [--context-images <json>] [--context-assets <json>] [--reference-pages <json>] [--reference-videos <json>] [--target <directionRef>|<sessionId>:<variantId>]');
     }
     if (context.flags.errors.length > 0) {
         return (0, envelope_1.errorResult)(START_COMMAND, 'USAGE_ERROR', context.flags.errors.join('; '));
@@ -508,10 +487,12 @@ const handleVariantsStart = async (args, options) => {
         return (0, envelope_1.errorResult)(START_COMMAND, 'USAGE_ERROR', '--count must match --briefs length when both are provided.');
     }
     const isFresh = isFreshStart;
-    const parsedTarget = parseVariantTarget((0, flags_1.stringFlag)(context.flags, 'target'));
-    if (!parsedTarget.ok) {
-        return (0, envelope_1.errorResult)(START_COMMAND, 'USAGE_ERROR', parsedTarget.message);
-    }
+    const parsedTarget = await resolveStartTarget({
+        projectPath: context.projectPath,
+        raw: (0, flags_1.stringFlag)(context.flags, 'target'),
+    });
+    if (!parsedTarget.ok)
+        return parsedTarget.result;
     if (isFresh && parsedTarget.target) {
         return (0, envelope_1.errorResult)(START_COMMAND, 'USAGE_ERROR', '--fresh cannot be combined with --target; start fresh generation from the base project.');
     }
@@ -782,6 +763,7 @@ const handleSavedVariantGet = async (args) => {
                 return (0, envelope_1.errorResult)(GET_COMMAND, 'WORK_ITEM_NOT_FOUND', 'No saved variant exists for this project and reference.');
             const saved = 'detail' in found ? found.detail : found.summary;
             const { manifest, variantDir } = saved;
+            const directionRef = args.directionRef ?? manifest.directionRef;
             const kind = manifest.artifact.kind === 'diff' ? 'diff' : 'project-created';
             const artifactPath = path.join(variantDir, manifest.artifact.kind === 'diff'
                 ? manifest.artifact.diffPath
@@ -789,6 +771,7 @@ const handleSavedVariantGet = async (args) => {
             const variant = args.isDetailed && 'detail' in found
                 ? {
                     ...manifest,
+                    directionRef,
                     kind,
                     artifactPath,
                     diff: found.detail.diff,
@@ -796,6 +779,7 @@ const handleSavedVariantGet = async (args) => {
                     designMarkdown: found.detail.designMarkdown,
                 }
                 : {
+                    directionRef,
                     sessionId: manifest.sessionId,
                     variantId: manifest.variantId,
                     status: manifest.status,
@@ -825,12 +809,21 @@ const handleVariantsGet = async (args) => {
     if ((0, shared_1.isCommandResult)(context)) {
         return context;
     }
-    const reference = variantReferenceFromString(context.flags.positionals[0]);
-    if (!reference ||
+    const input = context.flags.positionals[0];
+    if (input === undefined ||
         context.flags.positionals.length !== 1 ||
         context.flags.errors.length > 0) {
-        return (0, envelope_1.errorResult)(GET_COMMAND, 'USAGE_ERROR', 'Usage: rivet variants get [<projectId>/]<sessionId>:<variantId> [--detail] [--project <path>]');
+        return (0, envelope_1.errorResult)(GET_COMMAND, 'USAGE_ERROR', GET_USAGE);
     }
+    const resolved = await (0, directionTarget_1.resolveDirectionTarget)({
+        command: GET_COMMAND,
+        projectPath: context.projectPath,
+        input,
+        usage: GET_USAGE,
+    });
+    if (!resolved.ok)
+        return resolved.result;
+    const reference = resolved.target;
     if (reference.projectId)
         return handleSavedVariantGet({
             ...reference,

package/dist/cli/envelope.d.ts

@@ -8,7 +8,7 @@ export declare const CLI_EXIT_CODES: {
     readonly waitTimeout: 5;
 };
 export type CliExitCode = (typeof CLI_EXIT_CODES)[keyof typeof CLI_EXIT_CODES];
-export type CliErrorCode = 'OPERATION_FAILED' | 'USAGE_ERROR' | 'AUTH_REQUIRED' | 'SERVER_UNAVAILABLE' | 'WAIT_TIMEOUT' | 'SESSION_NOT_FOUND' | 'WORK_ITEM_NOT_FOUND' | 'MCP_REMOVED';
+export type CliErrorCode = 'OPERATION_FAILED' | 'USAGE_ERROR' | 'AUTH_REQUIRED' | 'SERVER_UNAVAILABLE' | 'WAIT_TIMEOUT' | 'SESSION_NOT_FOUND' | 'WORK_ITEM_NOT_FOUND' | 'DIRECTION_AMBIGUOUS' | 'MCP_REMOVED';
 export type CliLoginAction = {
     action: 'login';
     command: 'rivet login';

package/dist/cli/envelope.js

@@ -24,6 +24,7 @@ const ERROR_EXIT_CODES = {
     WAIT_TIMEOUT: exports.CLI_EXIT_CODES.waitTimeout,
     SESSION_NOT_FOUND: exports.CLI_EXIT_CODES.operationFailed,
     WORK_ITEM_NOT_FOUND: exports.CLI_EXIT_CODES.operationFailed,
+    DIRECTION_AMBIGUOUS: exports.CLI_EXIT_CODES.usageError,
     MCP_REMOVED: exports.CLI_EXIT_CODES.usageError,
 };
 const loginRecovery = (authUrl) => ({

package/dist/cli/projectRuntimeUpgrade.d.ts

@@ -12,6 +12,17 @@ type RuntimeUpgradeOutcome = {
     restartArgs?: string[];
     interruptedWork?: RuntimeInterruption;
 };
+type RuntimeRetirement = {
+    outcome: 'retired';
+    restartArgs?: string[];
+} | {
+    outcome: 'kept';
+};
+export declare const retireUnavailablePreview: ({ attached, clientVersion, shutdownTimeoutMs, }: {
+    attached: AttachedServer;
+    clientVersion: string;
+    shutdownTimeoutMs: number;
+}) => Promise<RuntimeRetirement>;
 export declare const prepareRuntimeUpgrade: ({ attached, io, shutdownTimeoutMs, }: {
     attached: AttachedServer;
     io: CliIO;

package/dist/cli/projectRuntimeUpgrade.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.prepareRuntimeUpgrade = void 0;
+exports.prepareRuntimeUpgrade = exports.retireUnavailablePreview = void 0;
 const zod_1 = require("zod");
 const fs_1 = __importDefault(require("fs"));
 const client_1 = require("./client");
@@ -34,6 +34,43 @@ const INTERRUPTIBLE_REASONS = new Set([
     'active_work',
     'unknown_execution_state',
 ]);
+const awaitOwnedRuntimeShutdown = async ({ attached, processIdentity, shutdownTimeoutMs, }) => {
+    if (await (0, serverShutdown_1.waitForServerShutdown)(attached, shutdownTimeoutMs))
+        return;
+    await (0, stopRuntimeProcess_1.stopRuntimeProcess)({
+        pid: attached.handshake.pid,
+        timeoutMs: shutdownTimeoutMs,
+        isOwned: async () => {
+            return (processIdentity !== null &&
+                (0, stopRuntimeProcess_1.runtimeProcessIdentity)(attached.handshake.pid) === processIdentity);
+        },
+    });
+};
+const retireUnavailablePreview = async ({ attached, clientVersion, shutdownTimeoutMs, }) => {
+    const serverVersion = attached.handshake.rivetVersion;
+    if (!serverVersion || (0, serverVersion_1.isNewerVersion)(serverVersion, clientVersion))
+        return { outcome: 'kept' };
+    try {
+        const processIdentity = (0, stopRuntimeProcess_1.runtimeProcessIdentity)(attached.handshake.pid);
+        const upgrade = await (0, client_1.requestServer)(attached, '/api/cli/upgrade', {
+            method: 'POST',
+            body: { clientVersion, requireIdle: true },
+        });
+        const parsed = upgradeSchema.parse(upgrade.body);
+        if (upgrade.status !== 200 || parsed.stopping !== true)
+            return { outcome: 'kept' };
+        await awaitOwnedRuntimeShutdown({
+            attached,
+            processIdentity,
+            shutdownTimeoutMs,
+        });
+        return { outcome: 'retired', restartArgs: parsed.restartArgs };
+    }
+    catch {
+        return { outcome: 'kept' };
+    }
+};
+exports.retireUnavailablePreview = retireUnavailablePreview;
 const prepareRuntimeUpgrade = async ({ attached, io, shutdownTimeoutMs, }) => {
     const info = (0, serverVersion_1.serverVersionInfo)(attached.handshake);
     if (!info.staleServer)
@@ -92,16 +129,11 @@ const prepareRuntimeUpgrade = async ({ attached, io, shutdownTimeoutMs, }) => {
             : undefined;
         if (interruptedWork)
             io.writeProgress(`${interruptedWork.message} Recovery details: ${interruptedWork.receiptPath}`);
-        if (!(await (0, serverShutdown_1.waitForServerShutdown)(attached, shutdownTimeoutMs))) {
-            await (0, stopRuntimeProcess_1.stopRuntimeProcess)({
-                pid: attached.handshake.pid,
-                timeoutMs: shutdownTimeoutMs,
-                isOwned: async () => {
-                    return (processIdentity !== null &&
-                        (0, stopRuntimeProcess_1.runtimeProcessIdentity)(attached.handshake.pid) === processIdentity);
-                },
-            });
-        }
+        await awaitOwnedRuntimeShutdown({
+            attached,
+            processIdentity,
+            shutdownTimeoutMs,
+        });
         io.writeProgress(`Upgrading project server to rivet v${info.cliVersion}…`);
         return {
             outcome: 'spawn',

package/dist/config/pluginMetrics.js

@@ -120,6 +120,7 @@ const metricProperties = zod_1.z.object({
         'WAIT_TIMEOUT',
         'SESSION_NOT_FOUND',
         'WORK_ITEM_NOT_FOUND',
+        'DIRECTION_AMBIGUOUS',
         'MCP_REMOVED',
         'STATIC_PREVIEW_FAILED',
         'DEV_SERVER_FAILED',
@@ -164,6 +165,7 @@ const metricProperties = zod_1.z.object({
         'usage_error',
         'wait_timeout',
         'session_not_found',
+        'direction_ambiguous',
         'mcp_removed',
         'server_start_timeout',
         'handshake_missing',

package/dist/mcp/explorationSchema.js

@@ -117,7 +117,7 @@ exports.explorationShape = {
     baseDirectionId: v3_1.z
         .string()
         .optional()
-        .describe('start: sessionId:variantId — refine an existing variant in place'),
+        .describe('start: direction ref (e.g. warm-editorial-green), sessionId:variantId, or projectId/sessionId:variantId — refine an existing variant in place'),
     project: v3_1.z.string().trim().min(1).describe('Absolute project root path'),
 };
 //# sourceMappingURL=explorationSchema.js.map

package/dist/mcp/getExploration.js

@@ -17,6 +17,8 @@ const ConfigManager_1 = require("../services/ConfigManager");
 const ProjectLibrary_1 = require("../services/ProjectLibrary");
 const VariantHistoryService_1 = require("../services/VariantHistoryService");
 const historyRoots_1 = require("../services/historyRoots");
+const directionRefs_1 = require("../services/directionRefs");
+const projectDirections_1 = require("../services/projectDirections");
 const profileAccess_1 = require("./profileAccess");
 const getExploration = async (input) => {
     const command = 'rivet_get_exploration';
@@ -68,12 +70,16 @@ const getExploration = async (input) => {
             ? registered.library.registry.historyRoots(registered.owner.id)
             : [project, ...(0, historyRoots_1.nestedFreshSessionWorkdirs)(project)];
         if (!hasLiveServer || input.includeHistory || input.sessionId) {
+            const directions = await (0, projectDirections_1.listProjectDirections)(registered
+                ? {
+                    kind: 'library',
+                    library: registered.library,
+                    projectId: registered.owner.id,
+                }
+                : { kind: 'history', history, projectPath: project });
             const entries = registered
-                ? await registered.library.listVariants(registered.owner.id)
-                : (await Promise.all(roots.map(async (projectPath) => (await history.listVariants({ projectPath })).map((entry) => ({
-                    ...entry,
-                    projectPath,
-                }))))).flat();
+                ? directions.filter((entry) => (0, directionRefs_1.isDirectionActive)(entry.manifest.status))
+                : directions;
             data.history = entries.filter((entry) => (!input.sessionId || entry.manifest.sessionId === input.sessionId) &&
                 (!input.variantId || entry.manifest.variantId === input.variantId));
             if (input.variantId && input.sessionId) {

package/dist/proxy-middleware/proxy-config.js

@@ -13,6 +13,10 @@ const TARGET_ADDRESSED_PREVIEW_PREFIX = '/__rivet/preview';
 const TARGET_ADDRESSED_PREVIEW_KIND_BASE = 'base';
 const TARGET_ADDRESSED_PREVIEW_KIND_HISTORY = 'history';
 const TARGET_ADDRESSED_PREVIEW_KIND_VARIANT = 'variant';
+const CACHE_VALIDATOR_REQUEST_HEADERS = [
+    'if-none-match',
+    'if-modified-since',
+];
 const hasValidUserDevPort = (userPort) => Number.isInteger(userPort) && userPort > 0;
 const resolveTargetAddressedPreview = (args) => {
     const parsed = new URL(args.rawUrl ?? '/', 'http://rivet.local');
@@ -152,6 +156,9 @@ const createUserDevServerProxy = (userPort, userHost = 'localhost', options = {}
         requestTargets.set(req, target);
         if (target.isTargetAddressed) {
             req.url = target.path;
+            for (const header of CACHE_VALIDATOR_REQUEST_HEADERS) {
+                delete req.headers[header];
+            }
         }
     };
     const getRouterTargetForLibrary = (req) => {

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/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: {