rivet-design 0.26.2 → 0.27.1

package/dist/config/pluginMetrics.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.pluginMetricProperties = void 0;
 const zod_1 = require("zod");
+const failureReason_1 = require("../utils/failureReason");
 const count = zod_1.z.number().finite().nonnegative().max(Number.MAX_SAFE_INTEGER);
 const metricProperties = zod_1.z.object({
     command: zod_1.z
@@ -19,6 +20,17 @@ const metricProperties = zod_1.z.object({
         'variants.cancel',
         'reference.fetch',
         'evidence.capture',
+        'context.add',
+        'context.update',
+        'context.list',
+        'context.show',
+        'context.enable',
+        'context.disable',
+        'context.remove',
+        'context.resolve',
+        'context.inspect',
+        'context.verifier',
+        'context.verify',
     ])
         .optional(),
     tool_name: zod_1.z
@@ -108,12 +120,17 @@ 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',
         'PREVIEW_UNAVAILABLE',
+        'DEPENDENCY_INSTALL_FAILED',
+        'DEV_SERVER_START_FAILED',
+        'DEV_SCRIPT_MISSING',
     ])
         .optional(),
+    reason_code: zod_1.z.enum(failureReason_1.FAILURE_REASON_CODES).optional(),
     failure_reason: zod_1.z
         .enum([
         'ack_failed',
@@ -148,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',
@@ -169,6 +187,26 @@ const metricProperties = zod_1.z.object({
         'editor_server_start_failed',
     ])
         .optional(),
+    verification_outcome: zod_1.z
+        .enum([
+        'pass',
+        'fail',
+        'blocked',
+        'package_required',
+        'verifier_missing',
+        'verifier_stale',
+        'cancelled',
+        'timeout',
+        'output_limit',
+        'process_failed',
+        'invalid_result',
+        'invalid_evidence',
+        'cleanup_failed',
+        'setup_failed',
+    ])
+        .optional(),
+    verification_check_count: count.int().optional(),
+    verification_duration_ms: count.optional(),
     ok: zod_1.z.boolean().optional(),
     is_recoverable: zod_1.z.boolean().optional(),
     is_fresh: zod_1.z.boolean().optional(),

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { ProjectDetectionService } from './index-core';
+import { AuthService } from './services/AuthService';
 import { SessionBridgeService } from './services/SessionBridgeService';
 import type { Framework } from './services/ProjectDetectionService';
 import { DevServerRuntimeService, type StartDevServerResult } from './services/DevServerRuntimeService';
@@ -75,6 +76,24 @@ export declare const authCommandOptionsForArgs: (args: string[]) => {
 };
 export declare const rememberInstallRef: (args: string[], downloadType?: string) => string[];
 export declare const authFailureReasonForError: (error: string | undefined) => "oauth_failed" | "timeout";
+export declare const signInWithoutBrowser: (authService?: AuthService) => Promise<{
+    success: boolean;
+    token?: string | undefined;
+    refreshToken?: string | undefined;
+    user?: {
+        id: string;
+        email: string;
+        displayName?: string | undefined;
+    } | undefined;
+    profile?: {
+        remaining_spend_usd?: number | null | undefined;
+        monthly_limit_usd?: number | null | undefined;
+        current_month_spend_usd?: number | null | undefined;
+        total_spend_usd?: number | null | undefined;
+    } | null | undefined;
+    error?: string | undefined;
+    message?: string | undefined;
+}>;
 export declare const main: (args?: string[]) => Promise<void>;
 export declare const parseArgs: (args: string[]) => CLIOptions;
 export declare const handleLogin: (options?: {

package/dist/index.js

@@ -36,7 +36,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.handleLogin = exports.parseArgs = exports.main = exports.authFailureReasonForError = exports.rememberInstallRef = exports.authCommandOptionsForArgs = exports.registerOwnedDevServerSignalHandlers = exports.isAgentVariantsEnabled = exports.updateOwnedDevServerHealthOnExit = exports.buildAgentDevServerHealth = exports.resolveAgentDevServer = exports.buildAgentDevServerContext = exports.DEFAULT_USER_PORT = exports.DEFAULT_PORT = void 0;
+exports.handleLogin = exports.parseArgs = exports.main = exports.signInWithoutBrowser = exports.authFailureReasonForError = exports.rememberInstallRef = exports.authCommandOptionsForArgs = exports.registerOwnedDevServerSignalHandlers = exports.isAgentVariantsEnabled = exports.updateOwnedDevServerHealthOnExit = exports.buildAgentDevServerHealth = exports.resolveAgentDevServer = exports.buildAgentDevServerContext = exports.DEFAULT_USER_PORT = exports.DEFAULT_PORT = void 0;
 /* eslint-disable no-console */
 const dotenv = __importStar(require("dotenv"));
 const crypto_1 = require("crypto");
@@ -260,6 +260,18 @@ const discardInstallRefForValidatedSession = () => {
 };
 const authFailureReasonForError = (error) => error?.trim().toLowerCase() === 'timeout' ? 'timeout' : 'oauth_failed';
 exports.authFailureReasonForError = authFailureReasonForError;
+const signInWithoutBrowser = async (authService = new AuthService_1.AuthService()) => {
+    console.log('\n🔐 Authentication required');
+    console.log('Open this link to sign in:');
+    return authService.loginWithGoogle({
+        source: 'cli',
+        noBrowser: true,
+        onAuthUrl: (url) => {
+            console.log(`\n  ${url}\n`);
+        },
+    });
+};
+exports.signInWithoutBrowser = signInWithoutBrowser;
 const main = async (args = process.argv.slice(2)) => {
     if (args.includes('--no-telemetry'))
         process.env.RIVET_TELEMETRY_DISABLED = '1';
@@ -452,10 +464,7 @@ const main = async (args = process.argv.slice(2)) => {
                     process.exit(1);
                 }
                 if (options.noBrowser) {
-                    console.log('\n🔐 Authentication required');
-                    console.log('Opening browser for Google login...\n');
-                    const authService = new AuthService_1.AuthService();
-                    const loginResult = await authService.loginWithGoogle();
+                    const loginResult = await (0, exports.signInWithoutBrowser)();
                     if (!loginResult.success) {
                         console.log(`\n❌ Authentication failed: ${loginResult.error || loginResult.message}`);
                         process.exit(1);

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/routes/library/middleware.js

@@ -45,13 +45,18 @@ const authenticateLibrary = (token, sessions) => (req, res, next) => {
     next();
 };
 exports.authenticateLibrary = authenticateLibrary;
+const HANDLED_ERROR_KEY = 'libraryError';
 const trackLibraryOperation = (telemetry) => (operation) => (_req, res, next) => {
     const startedAt = Date.now();
-    res.once('finish', () => telemetry?.trackLibraryOperation({
-        operation,
-        outcome: res.statusCode < 400 ? 'completed' : 'failed',
-        durationMs: Date.now() - startedAt,
-    }));
+    res.once('finish', () => {
+        const isCompleted = res.statusCode < 400;
+        telemetry?.trackLibraryOperation({
+            operation,
+            outcome: isCompleted ? 'completed' : 'failed',
+            durationMs: Date.now() - startedAt,
+            error: isCompleted ? undefined : res.locals[HANDLED_ERROR_KEY],
+        });
+    });
     next();
 };
 exports.trackLibraryOperation = trackLibraryOperation;
@@ -73,6 +78,7 @@ const libraryErrorStatus = (code) => {
     }
 };
 const handleLibraryError = (error, _req, res, _next) => {
+    res.locals[HANDLED_ERROR_KEY] = error;
     const message = (0, errorMessage_1.errorMessage)(error);
     if (error instanceof libraryErrors_1.LibraryError) {
         res

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/') &&
@@ -370,6 +376,14 @@ const startServer = async (options) => {
     app.get('/rivet/favicon.ico', (_req, res) => {
         res.sendFile('favicon.ico', { root: exports.DIST_UI_PATH });
     });
+    app.get(/^\/rivet\/library(?:\/.*)?$/, (req, res) => {
+        const resolvedLibraryOrigin = options.resolveLibraryOrigin?.();
+        if (!resolvedLibraryOrigin) {
+            res.sendStatus(404);
+            return;
+        }
+        res.redirect(302, `${new URL(resolvedLibraryOrigin).origin}${req.path}`);
+    });
     app.get(/^\/rivet(?:\/.*)?$/, (req, res, next) => {
         if ((0, exports.isRivetUiStaticAssetPath)(req.path)) {
             next();
@@ -430,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}`);
@@ -503,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);
@@ -583,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

@@ -16,6 +16,7 @@ const ProjectPackageManager_1 = require("./ProjectPackageManager");
 const errnoCode_1 = require("../utils/errnoCode");
 const pathContainment_1 = require("../utils/pathContainment");
 const errorMessage_1 = require("../utils/errorMessage");
+const failureReason_1 = require("../utils/failureReason");
 const subprocessEnvironment_1 = require("../utils/subprocessEnvironment");
 const MAX_CONCURRENT_INSTALLS = 2;
 const INSTALL_TIMEOUT_MS = 5 * 60 * 1000;
@@ -43,11 +44,13 @@ const isInstallEnvironmentKey = (key) => {
         INSTALL_ENVIRONMENT_KEYS.has(lower));
 };
 const yarnAgentForVersion = (version) => Number.parseInt(version, 10) > 1 ? 'yarn@berry' : 'yarn';
-const preparationError = (message, detail = '') => new devServerError_1.DevServerStartError({
+const preparationError = ({ reasonCode, message, detail = '', }) => new devServerError_1.DevServerStartError({
     message: detail ? `${message}\n${detail}` : message,
     reason: 'dependency_install_failed',
     portInUse: false,
     detail,
+    reasonCode,
+    summary: message,
 });
 class DependencyPreparationService {
     pending = new Map();
@@ -78,7 +81,10 @@ class DependencyPreparationService {
         catch (error) {
             if (error instanceof devServerError_1.DevServerStartError)
                 throw error;
-            throw preparationError(`Could not prepare preview dependencies: ${(0, errorMessage_1.errorMessage)(error)}`);
+            throw preparationError({
+                reasonCode: (0, failureReason_1.failureReasonCode)(error),
+                message: `Could not prepare preview dependencies: ${(0, errorMessage_1.errorMessage)(error)}`,
+            });
         }
     }
     forget(workspaceRoot) {
@@ -116,9 +122,16 @@ class DependencyPreparationService {
             .reverse()
             .find((line) => /^\d+\.\d+\.\d+(?:-.+)?$/.test(line));
         if (!version)
-            throw preparationError(`Could not identify the ${project.name} version`, versionOutput);
+            throw preparationError({
+                reasonCode: 'version_unreadable',
+                message: `Could not identify the ${project.name} version`,
+                detail: versionOutput,
+            });
         if (project.version && version !== project.version) {
-            throw preparationError(`This project requires ${project.name}@${project.version}, but the available command reports ${version}. Activate the project's package manager version, then retry the preview.`);
+            throw preparationError({
+                reasonCode: 'version_mismatch',
+                message: `This project requires ${project.name}@${project.version}, but the available command reports ${version}. Activate the project's package manager version, then retry the preview.`,
+            });
         }
         const agent = project.name === 'yarn' ? yarnAgentForVersion(version) : project.agent;
         const fingerprint = await this.fingerprint(project, version);
@@ -134,7 +147,10 @@ class DependencyPreparationService {
             : await this.fingerprint(project, version, true);
         const command = (0, package_manager_detector_1.resolveCommand)(agent, project.hasLockfile ? 'frozen' : 'install', []);
         if (!command)
-            throw preparationError(`No dependency install command is available for ${project.name}`);
+            throw preparationError({
+                reasonCode: 'no_install_command',
+                message: `No dependency install command is available for ${project.name}`,
+            });
         if (project.name === 'npm')
             command.args.push('--no-audit', '--no-fund');
         if (this.activeInstalls >= MAX_CONCURRENT_INSTALLS) {
@@ -166,7 +182,10 @@ class DependencyPreparationService {
                 ? completedFingerprint
                 : await this.fingerprint(project, version, true);
             if (inputsAfterInstall !== inputsBeforeInstall) {
-                throw preparationError('Dependency inputs changed during installation. Retry the preview to prepare the updated project.');
+                throw preparationError({
+                    reasonCode: 'inputs_changed',
+                    message: 'Dependency inputs changed during installation. Retry the preview to prepare the updated project.',
+                });
             }
             this.prepared.set(project.rootPath, {
                 fingerprint: completedFingerprint,
@@ -194,14 +213,20 @@ class DependencyPreparationService {
                 try {
                     const resolved = await promises_1.default.realpath(candidate);
                     if (!(0, pathContainment_1.isPathWithinRoot)(boundary, resolved))
-                        throw preparationError(`Dependency path resolves outside the preview workspace: ${candidate}`);
+                        throw preparationError({
+                            reasonCode: 'path_outside_workspace',
+                            message: `Dependency path resolves outside the preview workspace: ${candidate}`,
+                        });
                 }
                 catch (error) {
                     if ((0, errnoCode_1.errnoCode)(error) !== 'ENOENT')
                         throw error;
                     const entry = await promises_1.default.lstat(candidate).catch(() => null);
                     if (entry?.isSymbolicLink())
-                        throw preparationError(`Dependency path is a dangling symlink: ${candidate}`);
+                        throw preparationError({
+                            reasonCode: 'dangling_symlink',
+                            message: `Dependency path is a dangling symlink: ${candidate}`,
+                        });
                 }
             }
         }
@@ -284,7 +309,7 @@ class DependencyPreparationService {
                 stdio: 'pipe',
             });
             let output = '';
-            let interrupted = false;
+            let interruption;
             let settleTimer;
             const drain = (chunk) => {
                 output = (output + chunk.toString()).slice(-OUTPUT_TAIL_LIMIT);
@@ -292,35 +317,48 @@ class DependencyPreparationService {
             proc.stdout?.on('data', drain);
             proc.stderr?.on('data', drain);
             proc.stdin?.end();
-            const stop = () => {
-                interrupted = true;
+            const stop = (cause) => {
+                interruption ??= cause;
                 void OperatingSystemServices_1.selectedOperatingSystemServices.projectProcesses
                     .terminate(proc, { isForceful: true })
                     .catch(() => undefined);
                 settleTimer ??= setTimeout(() => {
                     cleanup();
-                    reject(preparationError(`Dependency preparation could not be stopped: ${project.name} ${args.join(' ')} is still running. Stop the process, then retry the preview.`, output.trim()));
+                    reject(preparationError({
+                        reasonCode: 'installer_unstoppable',
+                        message: `Dependency preparation could not be stopped: ${project.name} ${args.join(' ')} is still running. Stop the process, then retry the preview.`,
+                        detail: output.trim(),
+                    }));
                 }, this.terminationSettleTimeoutMs);
             };
-            const timer = setTimeout(stop, timeoutMs);
-            signal?.addEventListener('abort', stop, { once: true });
+            const abort = () => stop('aborted');
+            const timer = setTimeout(() => stop('timeout'), timeoutMs);
+            signal?.addEventListener('abort', abort, { once: true });
             if (signal?.aborted)
-                stop();
+                abort();
             const cleanup = () => {
                 clearTimeout(timer);
                 clearTimeout(settleTimer);
-                signal?.removeEventListener('abort', stop);
+                signal?.removeEventListener('abort', abort);
             };
             proc.once('error', (error) => {
                 cleanup();
-                reject(preparationError(`Could not run ${project.name} ${args.join(' ')}: ${error.message}`, output));
+                reject(preparationError({
+                    reasonCode: (0, failureReason_1.failureReasonCode)(error),
+                    message: `Could not run ${project.name} ${args.join(' ')}: ${error.message}`,
+                    detail: output,
+                }));
             });
             proc.once('close', (code) => {
                 cleanup();
-                if (code === 0 && !interrupted)
+                if (code === 0 && !interruption)
                     resolve(output);
                 else
-                    reject(preparationError(`Dependency preparation failed: ${project.name} ${args.join(' ')} (${interrupted ? 'cancelled or timed out' : `exit ${code}`}). Fix the installation error, then retry the preview.`, output.trim()));
+                    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.`,
+                        detail: output.trim(),
+                    }));
             });
         });
     }

package/dist/services/GuidanceVerifierRunner.js

@@ -254,16 +254,16 @@ const executeGuidanceVerifier = async (args) => {
         durationMs: Date.now() - started,
     });
     try {
-        await promises_1.default.mkdir(args.runsDirectory, { recursive: true, mode: 0o700 });
-        runDirectory = await promises_1.default.mkdtemp(path_1.default.join(await promises_1.default.realpath(args.runsDirectory), 'run-'));
-        if (args.signal?.aborted)
-            return failed('cancelled');
         if (args.packet.verifierState === 'missing')
             return failed('verifier_missing');
         if (args.packet.verifierState === 'stale')
             return failed('verifier_stale');
         if (!args.packet.verifier.package)
             return failed('package_required');
+        await promises_1.default.mkdir(args.runsDirectory, { recursive: true, mode: 0o700 });
+        runDirectory = await promises_1.default.mkdtemp(path_1.default.join(await promises_1.default.realpath(args.runsDirectory), 'run-'));
+        if (args.signal?.aborted)
+            return failed('cancelled');
         const executable = guidance_verifier_1.GuidanceVerifierPackageSchema.parse(args.packet.verifier.package);
         const packageDirectory = await (0, retainedTextFiles_1.materializeTextFiles)({
             files: executable.files,

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/ProjectPackageManager.d.ts

@@ -1,5 +1,10 @@
 import { type Agent } from 'package-manager-detector';
+import type { FailureReasonCode } from '../utils/failureReason';
 export type PreviewPackageManager = 'npm' | 'yarn' | 'pnpm';
+export declare class PackageManagerError extends Error {
+    readonly reasonCode: FailureReasonCode;
+    constructor(reasonCode: FailureReasonCode, message: string);
+}
 export interface ProjectPackageManager {
     name: PreviewPackageManager;
     agent: Agent;