rivet-design 0.26.2 → 0.27.1

package/dist/agent-variants/workItemInput.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.parseVariantWorkItemInput = exports.isVariantWorkItem = exports.isVariantWorkItemKind = exports.VARIANT_WORK_ITEM_KINDS = void 0;
+exports.parseVariantWorkItemInput = exports.shownDirectionRef = exports.isVariantWorkItem = exports.isVariantWorkItemKind = exports.VARIANT_WORK_ITEM_KINDS = void 0;
 const v3_1 = require("zod/v3");
 const errors_1 = require("./errors");
 exports.VARIANT_WORK_ITEM_KINDS = [
@@ -21,6 +21,12 @@ const variantWorkItemInputFields = v3_1.z.object({
     briefLabel: v3_1.z.string().optional(),
     briefBody: v3_1.z.string().optional(),
     briefNotes: v3_1.z.string().optional(),
+    directionRef: v3_1.z
+        .custom((value) => typeof value === 'string')
+        .optional(),
+    sourceDirectionRef: v3_1.z
+        .custom((value) => typeof value === 'string')
+        .optional(),
     visualReferenceUrl: v3_1.z.string().optional(),
     instruction: v3_1.z.string().optional(),
     guidance: v3_1.z.array(recordOf()).optional(),
@@ -59,6 +65,11 @@ const variantWorkItemInputSchemas = {
         briefBody: v3_1.z.string(),
     }),
 };
+const shownDirectionRef = (input) => {
+    const directionRef = input.directionRef ?? input.sourceDirectionRef;
+    return directionRef ? { directionRef } : {};
+};
+exports.shownDirectionRef = shownDirectionRef;
 const variantWorkItemInputParsers = {
     static_preview: (input) => variantWorkItemInputSchemas.static_preview.safeParse(input),
     refine_variant: (input) => variantWorkItemInputSchemas.refine_variant.safeParse(input),

package/dist/cli/commands/directionTarget.d.ts

@@ -0,0 +1,23 @@
+import { type CliCommandResult } from '../envelope';
+import type { DirectionRef } from '../../types/direction-ref';
+export type DirectionTarget = {
+    projectId?: string;
+    sessionId: string;
+    variantId: string;
+    directionRef?: DirectionRef;
+};
+type DirectionTargetResult = {
+    ok: true;
+    target: DirectionTarget;
+} | {
+    ok: false;
+    result: CliCommandResult;
+};
+export declare const resolveDirectionTarget: (args: {
+    command: string;
+    projectPath: string;
+    input: string;
+    usage: string;
+}) => Promise<DirectionTargetResult>;
+export {};
+//# sourceMappingURL=directionTarget.d.ts.map

package/dist/cli/commands/directionTarget.js

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveDirectionTarget = void 0;
+const envelope_1 = require("../envelope");
+const libraryErrors_1 = require("../../services/libraryErrors");
+const ProjectLibrary_1 = require("../../services/ProjectLibrary");
+const VariantHistoryService_1 = require("../../services/VariantHistoryService");
+const directionRefs_1 = require("../../services/directionRefs");
+const projectDirections_1 = require("../../services/projectDirections");
+const errorMessage_1 = require("../../utils/errorMessage");
+const resolveInProject = async (args) => {
+    const library = ProjectLibrary_1.ProjectLibrary.openReadOnly();
+    try {
+        const owner = library?.registry.findByPath(args.projectPath);
+        if (library && owner)
+            return {
+                projectId: owner.id,
+                resolution: await (0, projectDirections_1.resolveProjectDirection)({
+                    source: { kind: 'library', library, projectId: owner.id },
+                    address: args.address,
+                }),
+            };
+        const history = new VariantHistoryService_1.VariantHistoryService();
+        try {
+            return {
+                resolution: await (0, projectDirections_1.resolveProjectDirection)({
+                    source: { kind: 'history', history, projectPath: args.projectPath },
+                    address: args.address,
+                }),
+            };
+        }
+        finally {
+            history.metadata.closeAll();
+        }
+    }
+    finally {
+        library?.close();
+    }
+};
+const resolveDirectionTarget = async (args) => {
+    const address = (0, directionRefs_1.parseDirectionAddress)(args.input);
+    if (!address)
+        return {
+            ok: false,
+            result: (0, envelope_1.errorResult)(args.command, 'USAGE_ERROR', args.usage),
+        };
+    if (address.kind === 'ids') {
+        const { projectId, sessionId, variantId } = address;
+        return {
+            ok: true,
+            target: { ...(projectId ? { projectId } : {}), sessionId, variantId },
+        };
+    }
+    try {
+        const { projectId, resolution } = await resolveInProject({
+            projectPath: args.projectPath,
+            address,
+        });
+        if (!resolution.isResolved)
+            return {
+                ok: false,
+                result: (0, envelope_1.errorResult)(args.command, resolution.code, resolution.message, {
+                    input: args.input.trim(),
+                    candidates: resolution.candidates,
+                }),
+            };
+        const { directionRef, sessionId, variantId } = resolution.direction;
+        return {
+            ok: true,
+            target: {
+                ...(projectId ? { projectId } : {}),
+                sessionId,
+                variantId,
+                directionRef,
+            },
+        };
+    }
+    catch (error) {
+        const isMissingProject = error instanceof libraryErrors_1.LibraryError && error.code === 'project_not_found';
+        return {
+            ok: false,
+            result: (0, envelope_1.errorResult)(args.command, isMissingProject ? 'WORK_ITEM_NOT_FOUND' : 'OPERATION_FAILED', (0, errorMessage_1.errorMessage)(error)),
+        };
+    }
+};
+exports.resolveDirectionTarget = resolveDirectionTarget;
+//# sourceMappingURL=directionTarget.js.map

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/open.js

@@ -47,6 +47,7 @@ const flags_1 = require("../flags");
 const client_1 = require("../client");
 const serverHandshake_1 = require("../serverHandshake");
 const serverVersion_1 = require("../serverVersion");
+const telemetry_1 = require("../telemetry");
 const handoff_1 = require("../handoff");
 const callerRunnerPaths_1 = require("../callerRunnerPaths");
 const runnerSelection_1 = require("../runnerSelection");
@@ -149,6 +150,15 @@ const passthroughServeArgs = (context) => {
     }
     return args;
 };
+const USER_PORT_FLAG = '--user-port';
+const withoutUserPort = (args) => args.filter((arg, index) => arg !== USER_PORT_FLAG && args[index - 1] !== USER_PORT_FLAG);
+const previewRecoveryServeArgs = (context, retiredArgs) => {
+    const userPort = (0, flags_1.stringFlag)(context.flags, 'user-port');
+    return [
+        ...withoutUserPort(retiredArgs ?? passthroughServeArgs(context)),
+        ...(userPort === undefined ? [] : [USER_PORT_FLAG, userPort]),
+    ];
+};
 const serveEnvFor = (handoff, baseEnv) => ({
     ...(0, subprocessEnvironment_1.subprocessEnvironment)('rivetRuntime', baseEnv),
     ...(0, callerRunnerPaths_1.callerRunnerPathsEnvEntry)(baseEnv),
@@ -283,12 +293,26 @@ const ensureProjectRuntime = async (context, io, dependencies = {}) => {
             }
             if (replacement.outcome === 'attach') {
                 const readinessError = await verifyRuntimeReadiness(existing, Math.min(serverStartTimeoutMs, APP_HEALTH_TIMEOUT_MS));
-                if (readinessError)
+                if (!readinessError) {
+                    return finishProjectOpen(await openedData(existing, true), io);
+                }
+                if ((0, telemetry_1.serverUnavailableReasonForEnvelope)(readinessError.envelope) !==
+                    'app_health_failed')
+                    return readinessError;
+                const retirement = await (0, projectRuntimeUpgrade_1.retireUnavailablePreview)({
+                    attached: existing,
+                    clientVersion: (0, serverVersion_1.serverVersionInfo)(existing.handshake).cliVersion,
+                    shutdownTimeoutMs: timeoutFromEnv(env, UPGRADE_SHUTDOWN_TIMEOUT_ENV, DEFAULT_UPGRADE_SHUTDOWN_TIMEOUT_MS),
+                });
+                if (retirement.outcome === 'kept')
                     return readinessError;
-                return finishProjectOpen(await openedData(existing, true), io);
+                restartArgs = previewRecoveryServeArgs(context, retirement.restartArgs);
+                io.writeProgress('The project server is restarting because the app preview is unavailable…');
+            }
+            else {
+                interruptedWork = replacement.interruptedWork;
+                restartArgs = replacement.restartArgs;
             }
-            interruptedWork = replacement.interruptedWork;
-            restartArgs = replacement.restartArgs;
         }
         io.writeProgress(`Starting Rivet server for ${projectPath}…`);
         const handle = spawnServer({

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