rivet-design 0.26.2 → 0.27.0

package/dist/cli/commands/mcpServe.js

@@ -182,6 +182,7 @@ const buildMcpServer = async (options = {}) => {
                 durationMs: Date.now() - startedAt,
                 designContextKind: (0, telemetry_1.designContextKindForEnvelope)(result.envelope),
                 ...(0, telemetry_1.variantContextMetadataForArgs)(command, rest),
+                ...(0, telemetry_1.verificationMetadataForEnvelope)(result.envelope),
                 ...callerFields,
                 source: 'mcp',
             });

package/dist/cli/commands/serve.js

@@ -113,6 +113,7 @@ const handleServe = async (args, io) => {
             stage: 'resolve_dev_server',
             failureReason: 'operation_failed',
             durationMs: Date.now() - serverStartStartedAt,
+            error,
         });
         await telemetry.shutdown();
         await logForwarder.shutdown();
@@ -299,6 +300,7 @@ const handleServe = async (args, io) => {
             stage: 'start_editor_server',
             failureReason: 'operation_failed',
             durationMs: Date.now() - serverStartStartedAt,
+            error,
         });
         await telemetry.shutdown();
         await logForwarder.shutdown();

package/dist/cli/handoff.d.ts

@@ -35,6 +35,7 @@ export type CallerTelemetryFields = {
     callerAgent?: string;
     callerModel?: string;
     callerAgentSource?: 'handoff' | 'env';
+    callerRunId?: string;
 };
 export declare const callerTelemetryFieldsFromArgs: (args: string[], env?: NodeJS.ProcessEnv) => CallerTelemetryFields;
 export declare const initiatorFor: (handoff: CallerHandoff | null) => WorkItemInitiator;

package/dist/cli/handoff.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.initiatorFor = exports.callerTelemetryFieldsFromArgs = exports.detectCallerAgentFromEnv = exports.callerAgentEvidenceFromEnv = exports.detectCallerAgentsFromEnv = exports.parseHandoff = exports.HANDOFF_ENV_VARS = exports.CALLER_AGENT_ALLOWLIST = void 0;
+const node_crypto_1 = require("node:crypto");
 exports.CALLER_AGENT_ALLOWLIST = ['claude', 'codex', 'cursor'];
 exports.HANDOFF_ENV_VARS = {
     agent: 'RIVET_CALLER_AGENT',
@@ -84,6 +85,11 @@ const callerAgentEvidenceFromEnv = (env = process.env) => ENV_MARKERS_BY_AGENT.m
 exports.callerAgentEvidenceFromEnv = callerAgentEvidenceFromEnv;
 const detectCallerAgentFromEnv = (env = process.env) => (0, exports.detectCallerAgentsFromEnv)(env)[0];
 exports.detectCallerAgentFromEnv = detectCallerAgentFromEnv;
+const CALLER_RUN_ID_HEX_LENGTH = 16;
+const callerRunIdForSession = (session) => (0, node_crypto_1.createHash)('sha256')
+    .update(session)
+    .digest('hex')
+    .slice(0, CALLER_RUN_ID_HEX_LENGTH);
 const callerTelemetryFieldsFromArgs = (args, env = process.env) => {
     const valueOf = (flag) => {
         const index = args.indexOf(flag);
@@ -95,15 +101,25 @@ const callerTelemetryFieldsFromArgs = (args, env = process.env) => {
         callerSession: valueOf('--caller-session'),
         handoffJson: valueOf('--handoff'),
     }, env);
-    if (parsed.ok && parsed.handoff) {
+    const handoff = parsed.ok ? parsed.handoff : null;
+    const session = handoff?.session ??
+        nonEmpty(env.CODEX_THREAD_ID) ??
+        nonEmpty(env.CLAUDE_CODE_SESSION_ID);
+    const callerRunId = session ? callerRunIdForSession(session) : undefined;
+    const runId = callerRunId ? { callerRunId } : {};
+    if (handoff) {
         return {
-            callerAgent: parsed.handoff.agent,
-            callerModel: parsed.handoff.model,
+            callerAgent: handoff.agent,
+            callerModel: handoff.model,
             callerAgentSource: 'handoff',
+            ...runId,
         };
     }
     const detected = (0, exports.detectCallerAgentFromEnv)(env);
-    return detected ? { callerAgent: detected, callerAgentSource: 'env' } : {};
+    if (detected) {
+        return { callerAgent: detected, callerAgentSource: 'env', ...runId };
+    }
+    return runId;
 };
 exports.callerTelemetryFieldsFromArgs = callerTelemetryFieldsFromArgs;
 const initiatorFor = (handoff) => handoff

package/dist/cli/router.js

@@ -309,6 +309,7 @@ const runCliControlCommand = async (args, io = io_1.processCliIO) => {
                 designContextKind: (0, telemetry_1.designContextKindForEnvelope)(result.envelope),
                 ...(0, telemetry_1.variantContextMetadataForArgs)(command, rest),
                 ...(0, telemetry_1.browserMetadataForEnvelope)(result.envelope),
+                ...(0, telemetry_1.verificationMetadataForEnvelope)(result.envelope),
                 ...(0, handoff_1.callerTelemetryFieldsFromArgs)(rest),
             });
             telemetry.reportInstallRefActivations();

package/dist/cli/telemetry.d.ts

@@ -1,6 +1,7 @@
 import type { CliEnvelope } from './envelope';
 import type { BrowserOpenResult } from './browser';
 import { type ServerUnavailableReason } from './serverUnavailable';
+import { type GuidanceVerifierErrorReason } from '../types/guidance-verifier';
 export type { ServerUnavailableReason } from './serverUnavailable';
 export type DesignContextKind = 'arena' | 'pinterest' | 'reference' | 'unsupported' | 'website';
 export type VariantContextKind = 'image' | 'variant' | 'video' | 'website';
@@ -14,6 +15,15 @@ export type BrowserMetadata = {
     browserAction?: BrowserOpenResult['action'];
     browserReason?: BrowserOpenResult['reason'];
 };
+declare const COMPLETED_VERIFICATION_STATUSES: readonly ["pass", "fail", "blocked"];
+type CompletedVerificationStatus = (typeof COMPLETED_VERIFICATION_STATUSES)[number];
+export type VerificationOutcome = CompletedVerificationStatus | GuidanceVerifierErrorReason;
+export type VerificationMetadata = {
+    verificationOutcome?: VerificationOutcome;
+    verificationCheckCount?: number;
+    verificationDurationMs?: number;
+};
+export declare const verificationMetadataForEnvelope: (envelope: CliEnvelope) => VerificationMetadata;
 export declare const browserMetadataForEnvelope: (envelope: CliEnvelope) => BrowserMetadata;
 export declare const serverUnavailableReasonForEnvelope: (envelope: CliEnvelope) => ServerUnavailableReason | undefined;
 export declare const designContextKindForEnvelope: (envelope: CliEnvelope) => DesignContextKind | undefined;

package/dist/cli/telemetry.js

@@ -1,10 +1,46 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.variantContextMetadataForArgs = exports.designContextKindForEnvelope = exports.serverUnavailableReasonForEnvelope = exports.browserMetadataForEnvelope = void 0;
+exports.variantContextMetadataForArgs = exports.designContextKindForEnvelope = exports.serverUnavailableReasonForEnvelope = exports.browserMetadataForEnvelope = exports.verificationMetadataForEnvelope = void 0;
 const serverUnavailable_1 = require("./serverUnavailable");
+const guidance_verifier_1 = require("../types/guidance-verifier");
+const COMPLETED_VERIFICATION_STATUSES = ['pass', 'fail', 'blocked'];
+const isCompletedVerificationStatus = (value) => typeof value === 'string' &&
+    COMPLETED_VERIFICATION_STATUSES.includes(value);
+const isGuidanceVerifierErrorReason = (value) => typeof value === 'string' &&
+    guidance_verifier_1.GUIDANCE_VERIFIER_ERROR_REASONS.includes(value);
+const isNonNegativeDuration = (value) => typeof value === 'number' && Number.isFinite(value) && value >= 0;
+const verificationOutcomeForReport = (report) => {
+    if (report.execution === 'completed' &&
+        isCompletedVerificationStatus(report.status)) {
+        return report.status;
+    }
+    if (report.execution === 'error' &&
+        isGuidanceVerifierErrorReason(report.reason)) {
+        return report.reason;
+    }
+    return undefined;
+};
 const recordOf = (value) => value !== null && typeof value === 'object'
     ? value
     : {};
+const verificationMetadataForEnvelope = (envelope) => {
+    if (envelope.command !== 'context.verify')
+        return {};
+    const report = recordOf(envelope.ok ? envelope.data : envelope.error.details);
+    const verificationOutcome = verificationOutcomeForReport(report);
+    const verificationCheckCount = Array.isArray(report.checks)
+        ? report.checks.length
+        : undefined;
+    const verificationDurationMs = isNonNegativeDuration(report.durationMs)
+        ? report.durationMs
+        : undefined;
+    return {
+        ...(verificationOutcome !== undefined ? { verificationOutcome } : {}),
+        ...(verificationCheckCount !== undefined ? { verificationCheckCount } : {}),
+        ...(verificationDurationMs !== undefined ? { verificationDurationMs } : {}),
+    };
+};
+exports.verificationMetadataForEnvelope = verificationMetadataForEnvelope;
 const browserMetadataForEnvelope = (envelope) => {
     if (envelope.command !== 'open')
         return {};

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
@@ -112,8 +124,12 @@ const metricProperties = zod_1.z.object({
         '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',
@@ -169,6 +185,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/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

@@ -370,6 +370,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();

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/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;