@vellumai/cli 0.7.1 → 0.7.2

package/src/lib/guardian-token.ts

@@ -20,9 +20,11 @@ const DEVICE_ID_SALT = "vellum-assistant-host-id";
 export interface GuardianTokenData {
   guardianPrincipalId: string;
   accessToken: string;
-  accessTokenExpiresAt: string;
+  /** ISO date string or epoch-ms number as returned by the gateway. */
+  accessTokenExpiresAt: string | number;
   refreshToken: string;
-  refreshTokenExpiresAt: string;
+  /** ISO date string or epoch-ms number as returned by the gateway. */
+  refreshTokenExpiresAt: string | number;
   refreshAfter: string;
   isNew: boolean;
   deviceId: string;
@@ -104,7 +106,7 @@ export function getOrCreatePersistedDeviceId(): string {
 /**
  * Compute a stable device identifier matching the native client conventions.
  *
- * - macOS: SHA-256 of IOPlatformUUID + salt (matches PairingQRCodeSheet.computeHostId)
+ * - macOS: SHA-256 of IOPlatformUUID + salt
  * - Linux: SHA-256 of /etc/machine-id + salt
  * - Windows: SHA-256 of HKLM MachineGuid + salt
  * - Fallback: persisted random UUID in XDG config
@@ -158,6 +160,54 @@ export function saveGuardianToken(
   chmodSync(tokenPath, 0o600);
 }
 
+/**
+ * Call POST /v1/guardian/refresh on the remote gateway to obtain a new
+ * access token using an existing (possibly expired) access token for auth.
+ * Returns the refreshed token data (persisted locally), or null if the
+ * refresh fails (e.g. no stored token, or refresh token itself is expired).
+ */
+export async function refreshGuardianToken(
+  gatewayUrl: string,
+  assistantId: string,
+): Promise<GuardianTokenData | null> {
+  const tokenData = loadGuardianToken(assistantId);
+  if (!tokenData) return null;
+
+  // Gateway persists expiresAt as epoch-ms numbers; Date.parse("1234567890000")
+  // returns NaN. new Date() accepts both ISO strings and epoch-ms numbers.
+  const refreshExpiry = new Date(tokenData.refreshTokenExpiresAt).getTime();
+  if (!Number.isFinite(refreshExpiry) || refreshExpiry <= Date.now()) return null;
+
+  try {
+    const response = await fetch(`${gatewayUrl}/v1/guardian/refresh`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${tokenData.accessToken}`,
+      },
+      body: JSON.stringify({ refreshToken: tokenData.refreshToken }),
+    });
+    if (!response.ok) return null;
+
+    const json = (await response.json()) as Record<string, unknown>;
+    const refreshed: GuardianTokenData = {
+      guardianPrincipalId: (json.guardianPrincipalId as string) ?? tokenData.guardianPrincipalId,
+      accessToken: json.accessToken as string,
+      accessTokenExpiresAt: (json.accessTokenExpiresAt as string | number) ?? tokenData.accessTokenExpiresAt,
+      refreshToken: (json.refreshToken as string) ?? tokenData.refreshToken,
+      refreshTokenExpiresAt: (json.refreshTokenExpiresAt as string | number) ?? tokenData.refreshTokenExpiresAt,
+      refreshAfter: (json.refreshAfter as string) ?? tokenData.refreshAfter,
+      isNew: false,
+      deviceId: tokenData.deviceId,
+      leasedAt: new Date().toISOString(),
+    };
+    saveGuardianToken(assistantId, refreshed);
+    return refreshed;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Call POST /v1/guardian/init on the remote gateway to bootstrap a JWT
  * credential pair. The returned tokens are persisted locally under
@@ -190,9 +240,9 @@ export async function leaseGuardianToken(
   const tokenData: GuardianTokenData = {
     guardianPrincipalId: json.guardianPrincipalId as string,
     accessToken: json.accessToken as string,
-    accessTokenExpiresAt: json.accessTokenExpiresAt as string,
+    accessTokenExpiresAt: json.accessTokenExpiresAt as string | number,
     refreshToken: json.refreshToken as string,
-    refreshTokenExpiresAt: json.refreshTokenExpiresAt as string,
+    refreshTokenExpiresAt: json.refreshTokenExpiresAt as string | number,
     refreshAfter: json.refreshAfter as string,
     isNew: json.isNew as boolean,
     deviceId,
@@ -248,7 +298,7 @@ export function seedGuardianTokenFromSiblingEnv(assistantId: string): boolean {
     try {
       const raw = readFileSync(sibling);
       const parsed = JSON.parse(raw.toString("utf-8")) as GuardianTokenData;
-      const refreshExpiry = Date.parse(parsed.refreshTokenExpiresAt);
+      const refreshExpiry = new Date(parsed.refreshTokenExpiresAt).getTime();
       if (!Number.isFinite(refreshExpiry) || refreshExpiry <= now) continue;
       const dir = dirname(destPath);
       if (!existsSync(dir)) {

package/src/lib/hatch-local.ts

@@ -5,7 +5,6 @@ import {
   readlinkSync,
   symlinkSync,
   unlinkSync,
-  writeFileSync,
   appendFileSync,
   readFileSync,
 } from "fs";
@@ -20,7 +19,6 @@ import {
   findAssistantByName,
   saveAssistantEntry,
   setActiveAssistant,
-  syncConfigToLockfile,
 } from "./assistant-config.js";
 import type { AssistantEntry } from "./assistant-config.js";
 import type { Species } from "./constants.js";
@@ -31,7 +29,6 @@ import {
   startGateway,
   stopLocalProcesses,
 } from "./local.js";
-import { maybeStartNgrokTunnel } from "./ngrok.js";
 
 import { generateInstanceName } from "./random-name.js";
 import { leaseGuardianToken } from "./guardian-token.js";
@@ -223,9 +220,6 @@ export async function hatchLocal(
   }
 
   // Auto-start ngrok if webhook integrations (e.g. Telegram, Twilio) are configured.
-  // Set BASE_DATA_DIR so ngrok reads the correct instance config. Keep the
-  // lockfile save/sync inside the same scope so syncConfigToLockfile() reads
-  // this instance's workspace/config.json rather than a stale default path.
   const localEntry: AssistantEntry = {
     assistantId: instanceName,
     runtimeUrl,
@@ -236,26 +230,9 @@ export async function hatchLocal(
     resources: { ...resources, signingKey },
   };
 
-  const prevBaseDataDir = process.env.BASE_DATA_DIR;
-  process.env.BASE_DATA_DIR = resources.instanceDir;
-  try {
-    const ngrokChild = await maybeStartNgrokTunnel(resources.gatewayPort);
-    if (ngrokChild?.pid) {
-      const ngrokPidFile = join(resources.instanceDir, ".vellum", "ngrok.pid");
-      writeFileSync(ngrokPidFile, String(ngrokChild.pid));
-    }
-
-    emitProgress(6, 6, "Saving configuration...");
-    saveAssistantEntry(localEntry);
-    setActiveAssistant(instanceName);
-    syncConfigToLockfile();
-  } finally {
-    if (prevBaseDataDir !== undefined) {
-      process.env.BASE_DATA_DIR = prevBaseDataDir;
-    } else {
-      delete process.env.BASE_DATA_DIR;
-    }
-  }
+  emitProgress(6, 6, "Saving configuration...");
+  saveAssistantEntry(localEntry);
+  setActiveAssistant(instanceName);
 
   if (process.env.VELLUM_DESKTOP_APP) {
     installCLISymlink();

package/src/lib/local-runtime-client.ts

@@ -1,10 +1,14 @@
 import type { AssistantEntry } from "./assistant-config.js";
 import {
   authHeaders,
+  invalidateOrgIdCache,
   parseUnifiedJobStatus,
   type UnifiedJobStatus,
 } from "./platform-client.js";
-import { resolveRuntimeMigrationUrl } from "./runtime-url.js";
+import {
+  resolveRuntimeMigrationUrl,
+  resolveRuntimeUrl,
+} from "./runtime-url.js";
 
 /**
  * Thrown when the local runtime returns 409 for an export/import request
@@ -229,3 +233,80 @@ export async function localRuntimePollJobStatus(
   >[0];
   return parseUnifiedJobStatus(raw);
 }
+
+/**
+ * The subset of `/v1/health` we care about. The runtime's full response
+ * includes additional fields (status, disk, memory, cpu, migrations, etc.)
+ * — we only model `version` here because that's all the CLI consumes today.
+ */
+export interface RuntimeIdentity {
+  version: string;
+}
+
+/**
+ * Fetch the target runtime's APP_VERSION via `/v1/health`. Used by
+ * `vellum teleport` and `vellum backup` to stamp the exported bundle's
+ * `min_runtime_version` with the version of the runtime that actually
+ * produced it — which can diverge from the orchestrating CLI's version when
+ * the target was upgraded independently.
+ *
+ * GETs `/v1/health` (not `/v1/identity`) so the call works on freshly-
+ * hatched runtimes that haven't completed onboarding. The `/v1/identity`
+ * handler reads `IDENTITY.md` from the workspace and 404s if it's missing
+ * — and `IDENTITY.md` is only written during onboarding, not hatch. The
+ * `/v1/health` handler returns the same `version` field unconditionally
+ * (no filesystem reads), so it's safe to call against any running runtime.
+ *
+ * For local/docker assistants this GETs `{runtimeUrl}/v1/health` with
+ * guardian-token bearer auth. For platform-managed (cloud="vellum")
+ * assistants the URL is rewritten to the wildcard runtime proxy shape
+ * `{platformUrl}/v1/assistants/<assistantId>/health` and authenticated via
+ * the platform token.
+ *
+ * For the vellum target this is the FIRST network call in the
+ * teleport/backup export flow, so a stale `Vellum-Organization-Id` cache
+ * entry would surface as a hard abort before any retry-friendly call (like
+ * `platformRequestSignedUrl`) gets a chance to recover. Mirror that helper's
+ * one-shot 401-retry: invalidate the org-ID cache and retry once. Local /
+ * docker entries do not use the org-ID cache and are wrapped in
+ * `callRuntimeWithAuthRetry` by callers for guardian-token refresh, so the
+ * retry is intentionally vellum-only.
+ *
+ * The function name is intentionally retained ("identity-ish info about the
+ * runtime") even though the implementation now hits `/v1/health` — renaming
+ * would force changes in 4+ callsites for no behavioral benefit.
+ *
+ * Throws on non-2xx so callers can surface the failure (we never silently
+ * fall back — see teleport.ts call site).
+ */
+export async function localRuntimeIdentity(
+  entry: Pick<AssistantEntry, "cloud" | "runtimeUrl" | "assistantId">,
+  token: string,
+): Promise<RuntimeIdentity> {
+  const url = resolveRuntimeUrl(entry, "health");
+  const doRequest = async (): Promise<Response> =>
+    fetch(url, {
+      method: "GET",
+      headers: await migrationRequestHeaders(entry, token),
+    });
+
+  let response = await doRequest();
+  if (response.status === 401 && entry.cloud === "vellum") {
+    // `entry.runtimeUrl` is the platform host for vellum-cloud entries
+    // (the wildcard runtime proxy lives there). Pass it as the cache key
+    // platformUrl so we invalidate the same entry that authHeaders cached.
+    invalidateOrgIdCache(token, entry.runtimeUrl);
+    response = await doRequest();
+  }
+
+  if (!response.ok) {
+    throw new Error(
+      `Failed to fetch runtime identity: ${response.status} ${response.statusText}`,
+    );
+  }
+  const body = (await response.json()) as { version?: unknown };
+  if (typeof body.version !== "string" || !body.version) {
+    throw new Error("Runtime identity response missing version");
+  }
+  return { version: body.version };
+}

package/src/lib/local.ts

@@ -111,7 +111,9 @@ function computeIpcSocketDirOverride(workspaceDir: string): string | undefined {
  * a short override directory and set all IPC socket env vars on the target
  * env object. No-op on non-macOS or when paths are within limits.
  */
-function applyIpcSocketDirOverride(env: Record<string, string>): void {
+function applyIpcSocketDirOverride(
+  env: Record<string, string | undefined>,
+): void {
   const workspaceDir =
     env.VELLUM_WORKSPACE_DIR || join(homedir(), ".vellum", "workspace");
   const override = computeIpcSocketDirOverride(workspaceDir);
@@ -417,6 +419,8 @@ async function startDaemonFromSource(
       options.defaultWorkspaceConfigPath;
   }
 
+  applyIpcSocketDirOverride(env);
+
   // Write a sentinel PID file before spawning so concurrent hatch() calls
   // detect the in-progress spawn and wait instead of racing.
   writeFileSync(pidFile, "starting", "utf-8");
@@ -552,6 +556,8 @@ async function startDaemonWatchFromSource(
       options.defaultWorkspaceConfigPath;
   }
 
+  applyIpcSocketDirOverride(env);
+
   // Write a sentinel PID file before spawning so concurrent hatch() calls
   // detect the in-progress spawn and wait instead of racing.
   writeFileSync(pidFile, "starting", "utf-8");
@@ -1183,10 +1189,6 @@ export async function startGateway(
 
   applyIpcSocketDirOverride(gatewayEnv);
 
-  if (publicUrl) {
-    console.log(`   HTTP URL: ${publicUrl}`);
-  }
-
   let gateway;
 
   const gatewayBinary = join(dirname(process.execPath), "vellum-gateway");
@@ -1232,8 +1234,8 @@ export async function startGateway(
   const gatewayUrl = publicUrl || `http://localhost:${effectiveGatewayPort}`;
 
   // Wait for the gateway to be responsive before returning. Without this,
-  // callers (e.g. displayPairingQRCode) may try to connect before the HTTP
-  // server is listening and get connection-refused errors.
+  // callers may try to connect before the HTTP server is listening and get
+  // connection-refused errors.
   const start = Date.now();
   const timeoutMs = 30000;
   let ready = false;

package/src/lib/ngrok.ts

@@ -12,13 +12,19 @@ import { dirname, join } from "node:path";
 
 import { GATEWAY_PORT } from "./constants";
 
-function getConfigPath(): string {
-  const root = join(process.env.BASE_DATA_DIR?.trim() || homedir(), ".vellum");
-  return join(root, "workspace", "config.json");
+function getDefaultWorkspaceDir(): string {
+  return (
+    process.env.VELLUM_WORKSPACE_DIR?.trim() ||
+    join(homedir(), ".vellum", "workspace")
+  );
+}
+
+function getConfigPath(workspaceDir: string): string {
+  return join(workspaceDir, "config.json");
 }
 
-function loadRawConfig(): Record<string, unknown> {
-  const configPath = getConfigPath();
+function loadRawConfig(workspaceDir: string): Record<string, unknown> {
+  const configPath = getConfigPath(workspaceDir);
   if (!existsSync(configPath)) return {};
   return JSON.parse(readFileSync(configPath, "utf-8")) as Record<
     string,
@@ -26,8 +32,11 @@ function loadRawConfig(): Record<string, unknown> {
   >;
 }
 
-function saveRawConfig(config: Record<string, unknown>): void {
-  const configPath = getConfigPath();
+function saveRawConfig(
+  workspaceDir: string,
+  config: Record<string, unknown>,
+): void {
+  const configPath = getConfigPath(workspaceDir);
   const dir = dirname(configPath);
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
   writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
@@ -182,33 +191,33 @@ export async function waitForNgrokUrl(
 /**
  * Persist a public ingress URL to the workspace config and enable ingress.
  */
-function saveIngressUrl(publicUrl: string): void {
-  const config = loadRawConfig();
+function saveIngressUrl(workspaceDir: string, publicUrl: string): void {
+  const config = loadRawConfig(workspaceDir);
   const ingress = (config.ingress ?? {}) as Record<string, unknown>;
   ingress.publicBaseUrl = publicUrl;
   ingress.enabled = true;
   config.ingress = ingress;
-  saveRawConfig(config);
+  saveRawConfig(workspaceDir, config);
 }
 
 /**
  * Clear the ingress public base URL from the workspace config.
  */
-function clearIngressUrl(): void {
-  const config = loadRawConfig();
+function clearIngressUrl(workspaceDir: string): void {
+  const config = loadRawConfig(workspaceDir);
   const ingress = (config.ingress ?? {}) as Record<string, unknown>;
   delete ingress.publicBaseUrl;
   config.ingress = ingress;
-  saveRawConfig(config);
+  saveRawConfig(workspaceDir, config);
 }
 
 /**
  * Check whether any webhook-based integrations (e.g. Telegram, Twilio) are
  * configured that require a public ingress URL.
  */
-function hasWebhookIntegrationsConfigured(): boolean {
+function hasWebhookIntegrationsConfigured(workspaceDir: string): boolean {
   try {
-    const config = loadRawConfig();
+    const config = loadRawConfig(workspaceDir);
     const telegram = config.telegram as Record<string, unknown> | undefined;
     if (telegram?.botUsername) return true;
     const twilio = config.twilio as Record<string, unknown> | undefined;
@@ -223,9 +232,9 @@ function hasWebhookIntegrationsConfigured(): boolean {
  * Check whether a non-ngrok ingress URL is already configured (e.g. custom
  * domain or cloud deployment), meaning ngrok is not needed.
  */
-function hasNonNgrokIngressUrl(): boolean {
+function hasNonNgrokIngressUrl(workspaceDir: string): boolean {
   try {
-    const config = loadRawConfig();
+    const config = loadRawConfig(workspaceDir);
     const ingress = config.ingress as Record<string, unknown> | undefined;
     const publicBaseUrl = ingress?.publicBaseUrl;
     if (!publicBaseUrl || typeof publicBaseUrl !== "string") return false;
@@ -244,6 +253,7 @@ function hasNonNgrokIngressUrl(): boolean {
  */
 export async function maybeStartNgrokTunnel(
   targetPort: number,
+  workspaceDir: string,
 ): Promise<ChildProcess | null> {
   // Managed/containerized deployments route webhooks through the platform's
   // callback proxy. ngrok is not needed and would not be reachable from the
@@ -252,8 +262,8 @@ export async function maybeStartNgrokTunnel(
     process.env.IS_CONTAINERIZED === "true" ||
     process.env.IS_CONTAINERIZED === "1";
   if (isContainerized) return null;
-  if (!hasWebhookIntegrationsConfigured()) return null;
-  if (hasNonNgrokIngressUrl()) return null;
+  if (!hasWebhookIntegrationsConfigured(workspaceDir)) return null;
+  if (hasNonNgrokIngressUrl(workspaceDir)) return null;
 
   const version = getNgrokVersion();
   if (!version) return null;
@@ -262,7 +272,7 @@ export async function maybeStartNgrokTunnel(
   const existingUrl = await findExistingTunnel(targetPort);
   if (existingUrl) {
     console.log(`   Found existing ngrok tunnel: ${existingUrl}`);
-    saveIngressUrl(existingUrl);
+    saveIngressUrl(workspaceDir, existingUrl);
     return null;
   }
 
@@ -274,14 +284,13 @@ export async function maybeStartNgrokTunnel(
   //   2. If pipe handles are destroyed, SIGPIPE kills ngrok on its next write.
   // Writing to a log file sidesteps both issues — the file descriptor is
   // inherited by the detached ngrok process and remains valid after CLI exit.
-  const root = join(process.env.BASE_DATA_DIR?.trim() || homedir(), ".vellum");
-  const ngrokLogPath = join(root, "workspace", "data", "logs", "ngrok.log");
+  const ngrokLogPath = join(workspaceDir, "data", "logs", "ngrok.log");
   const ngrokProcess = startNgrokProcess(targetPort, ngrokLogPath);
   ngrokProcess.unref();
 
   try {
     const publicUrl = await waitForNgrokUrl();
-    saveIngressUrl(publicUrl);
+    saveIngressUrl(workspaceDir, publicUrl);
     console.log(`   Tunnel established: ${publicUrl}`);
 
     return ngrokProcess;
@@ -317,12 +326,13 @@ export async function runNgrokTunnel(): Promise<void> {
   console.log(`Using ${version}`);
 
   const port = GATEWAY_PORT;
+  const workspaceDir = getDefaultWorkspaceDir();
 
   // Check for an existing ngrok tunnel pointing at the gateway
   const existingUrl = await findExistingTunnel(port);
   if (existingUrl) {
     console.log(`Found existing ngrok tunnel: ${existingUrl}`);
-    saveIngressUrl(existingUrl);
+    saveIngressUrl(workspaceDir, existingUrl);
     console.log("Ingress URL saved to config.");
     console.log("");
     console.log(
@@ -349,7 +359,7 @@ export async function runNgrokTunnel(): Promise<void> {
     }
     if (publicUrl) {
       console.log("\nClearing ingress URL from config...");
-      clearIngressUrl();
+      clearIngressUrl(workspaceDir);
     }
   };
 
@@ -398,7 +408,7 @@ export async function runNgrokTunnel(): Promise<void> {
   console.log(`Tunnel established: ${publicUrl}`);
   console.log(`Forwarding to:     localhost:${port}`);
 
-  saveIngressUrl(publicUrl);
+  saveIngressUrl(workspaceDir, publicUrl);
   console.log("Ingress URL saved to config.");
   console.log("");
   console.log("Press Ctrl+C to stop the tunnel and clear the ingress URL.");

package/src/lib/platform-client.ts

@@ -99,6 +99,23 @@ function tokenAuthHeader(token: string): Record<string, string> {
 const orgIdCache = new Map<string, { orgId: string; expiresAt: number }>();
 const ORG_ID_CACHE_TTL_MS = 60_000; // 60 seconds
 
+/**
+ * Drop the cached org ID for a given (token, platformUrl) pair. Used by the
+ * one-shot 401-retry path: a 401 on a session-token request frequently means
+ * the cached `Vellum-Organization-Id` header is stale (e.g. user switched
+ * orgs in another tab). Clearing the entry forces the next `authHeaders`
+ * call to refetch the org ID from the platform.
+ *
+ * Exported so other modules (e.g. local-runtime-client) can implement the
+ * same retry pattern without needing direct access to the cache map.
+ */
+export function invalidateOrgIdCache(
+  token: string,
+  platformUrl?: string,
+): void {
+  orgIdCache.delete(`${token}::${platformUrl ?? ""}`);
+}
+
 /**
  * Returns the full set of headers needed for an authenticated platform
  * API request:
@@ -468,6 +485,7 @@ export async function hatchAssistant(
     method: "POST",
     headers: await authHeaders(token, platformUrl),
     body: JSON.stringify({}),
+    signal: AbortSignal.timeout(300_000),
   });
 
   if (response.ok) {
@@ -805,6 +823,45 @@ export function parseUnifiedJobStatus(
   };
 }
 
+export interface BundleCompatibility {
+  min_runtime_version: string;
+  max_runtime_version: string | null;
+}
+
+/**
+ * Thrown by platformRequestSignedUrl when the platform rejects a download
+ * signed-URL request because the target runtime version is outside the
+ * ExportJob's [min_runtime_version, max_runtime_version] band. Terminal
+ * — callers must NOT retry; surface to the user and abort the
+ * teleport/restore wizard.
+ */
+export class VersionMismatchError extends Error {
+  readonly bundleCompat: BundleCompatibility;
+  readonly targetRuntimeVersion: string;
+
+  constructor(bundleCompat: BundleCompatibility, targetRuntimeVersion: string) {
+    super(
+      VersionMismatchError.formatMessage(bundleCompat, targetRuntimeVersion),
+    );
+    this.name = "VersionMismatchError";
+    this.bundleCompat = bundleCompat;
+    this.targetRuntimeVersion = targetRuntimeVersion;
+  }
+
+  static formatMessage(
+    compat: BundleCompatibility,
+    targetRuntimeVersion: string,
+  ): string {
+    const range = compat.max_runtime_version
+      ? `${compat.min_runtime_version}–${compat.max_runtime_version}`
+      : `${compat.min_runtime_version}+`;
+    return (
+      `Cannot import: bundle requires runtime ${range}, but this runtime is ${targetRuntimeVersion}. ` +
+      `Update your runtime before importing.`
+    );
+  }
+}
+
 /**
  * Request a signed URL from the platform for either uploading a new bundle
  * or downloading an existing one. Calls `POST /v1/migrations/signed-url/`.
@@ -816,6 +873,9 @@ export function parseUnifiedJobStatus(
  *
  * Retries once with a fresh org-ID cache on 401 to match the retry pattern
  * used by other authenticated platform helpers.
+ *
+ * Throws {@link VersionMismatchError} on a 422 `version_mismatch` response,
+ * which is terminal — callers must NOT retry.
  */
 export async function platformRequestSignedUrl(
   params: {
@@ -823,6 +883,11 @@ export async function platformRequestSignedUrl(
     bundleKey?: string;
     contentType?: string;
     contentLength?: number;
+    // Source-side, upload only: runtime version that produced the bundle.
+    minRuntimeVersion?: string;
+    maxRuntimeVersion?: string | null;
+    // Target-side, download only: runtime version that will import.
+    targetRuntimeVersion?: string;
   },
   token: string,
   platformUrl?: string,
@@ -839,6 +904,17 @@ export async function platformRequestSignedUrl(
   if (params.contentLength !== undefined) {
     body.content_length = params.contentLength;
   }
+  if (params.minRuntimeVersion !== undefined) {
+    body.min_runtime_version = params.minRuntimeVersion;
+  }
+  if (params.maxRuntimeVersion !== undefined) {
+    // Explicit null is the documented "no upper bound" sentinel; keep it
+    // in the payload rather than stripping to undefined.
+    body.max_runtime_version = params.maxRuntimeVersion;
+  }
+  if (params.targetRuntimeVersion !== undefined) {
+    body.target_runtime_version = params.targetRuntimeVersion;
+  }
 
   const doRequest = async (): Promise<Response> =>
     fetch(`${resolvedUrl}/v1/migrations/signed-url/`, {
@@ -854,7 +930,7 @@ export async function platformRequestSignedUrl(
     // lookup. For session-token callers, a 401 frequently means the
     // cached org ID is stale — calling doRequest() again without clearing
     // the cache would just send the same stale header and fail again.
-    orgIdCache.delete(`${token}::${platformUrl ?? ""}`);
+    invalidateOrgIdCache(token, platformUrl);
     response = await doRequest();
   }
 
@@ -873,9 +949,28 @@ export async function platformRequestSignedUrl(
     };
   }
 
+  // Non-success body. Read once and reuse for both the 422 version-mismatch
+  // branch and the generic-error fallthrough — `response.json()` consumes
+  // the body, so a second read would always return undefined.
   const errorBody = (await response.json().catch(() => ({}))) as {
     detail?: string;
+    reason?: string;
+    bundle_compat?: BundleCompatibility;
+    target_runtime_version?: string;
   };
+
+  if (
+    response.status === 422 &&
+    errorBody.reason === "version_mismatch" &&
+    errorBody.bundle_compat &&
+    typeof errorBody.target_runtime_version === "string"
+  ) {
+    throw new VersionMismatchError(
+      errorBody.bundle_compat,
+      errorBody.target_runtime_version,
+    );
+  }
+
   throw new Error(
     errorBody.detail ??
       `Failed to request signed URL: ${response.status} ${response.statusText}`,

package/src/lib/retire-local.ts

@@ -1,9 +1,9 @@
 import { spawn } from "child_process";
+import { homedir } from "os";
 import { existsSync, mkdirSync, renameSync, writeFileSync } from "fs";
 import { basename, dirname, join } from "path";
 
 import {
-  getBaseDir,
   getDaemonPidPath,
   loadAllAssistants,
 } from "./assistant-config.js";
@@ -77,7 +77,7 @@ export async function retireLocal(
   // For named instances (instanceDir differs from the base directory),
   // archive and remove the entire instance directory. For the default
   // instance, archive only the .vellum subdirectory.
-  const isNamedInstance = resources.instanceDir !== getBaseDir();
+  const isNamedInstance = resources.instanceDir !== homedir();
   const dirToArchive = isNamedInstance ? resources.instanceDir : vellumDir;
 
   // Move the data directory out of the way so the path is immediately available

package/src/lib/runtime-url.ts

@@ -28,3 +28,25 @@ export function resolveRuntimeMigrationUrl(
   }
   return `${entry.runtimeUrl}/v1/migrations/${subpath}`;
 }
+
+/**
+ * Resolve the URL for a generic runtime endpoint under `/v1/<subpath>`,
+ * taking the assistant's topology into account.
+ *
+ * - For local/docker assistants, `runtimeUrl` is the loopback gateway and
+ *   the runtime serves `/v1/<subpath>` directly.
+ * - For platform-managed (cloud="vellum") assistants the path is rewritten
+ *   to the wildcard runtime proxy:
+ *   `{platformUrl}/v1/assistants/<assistantId>/<subpath>`.
+ *
+ * The `subpath` is appended verbatim (e.g. `"identity"`).
+ */
+export function resolveRuntimeUrl(
+  entry: Pick<AssistantEntry, "cloud" | "runtimeUrl" | "assistantId">,
+  subpath: string,
+): string {
+  if (entry.cloud === "vellum") {
+    return `${entry.runtimeUrl}/v1/assistants/${entry.assistantId}/${subpath}`;
+  }
+  return `${entry.runtimeUrl}/v1/${subpath}`;
+}