@vellumai/cli 0.12.1 → 0.12.2-staging.2

package/node_modules/@vellumai/local-mode/package.json

@@ -6,7 +6,8 @@
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
-    "./contract": "./src/lockfile-contract.ts"
+    "./contract": "./src/lockfile-contract.ts",
+    "./teleport-backup-policy": "./src/teleport-backup-policy.ts"
   },
   "scripts": {
     "typecheck": "bunx tsc --noEmit",

package/node_modules/@vellumai/local-mode/src/teleport-backup-policy.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  hasRecentBackup,
+  managedBackupIsReady,
+  readyManagedBackupCreatedAts,
+  RECENT_BACKUP_MAX_AGE_MS,
+} from "./teleport-backup-policy";
+
+const NOW = Date.parse("2026-09-15T12:00:00Z");
+
+function ago(ms: number): string {
+  return new Date(NOW - ms).toISOString();
+}
+
+describe("hasRecentBackup", () => {
+  test("true when a backup is within the max age", () => {
+    expect(hasRecentBackup([ago(5 * 60_000)], NOW)).toBe(true);
+    expect(hasRecentBackup([ago(RECENT_BACKUP_MAX_AGE_MS)], NOW)).toBe(true);
+  });
+
+  test("false when every backup is older than the max age", () => {
+    expect(hasRecentBackup([ago(RECENT_BACKUP_MAX_AGE_MS + 1)], NOW)).toBe(
+      false,
+    );
+    expect(hasRecentBackup([ago(2 * 24 * 60 * 60_000)], NOW)).toBe(false);
+  });
+
+  test("false with no backups", () => {
+    expect(hasRecentBackup([], NOW)).toBe(false);
+  });
+
+  test("ignores empty, missing, unparseable and future timestamps", () => {
+    expect(
+      hasRecentBackup(["", undefined, null, "garbage", ago(-60_000)], NOW),
+    ).toBe(false);
+    expect(hasRecentBackup(["", "garbage", ago(60_000)], NOW)).toBe(true);
+  });
+
+  test("finds a recent backup anywhere in the list", () => {
+    expect(
+      hasRecentBackup(
+        [ago(3 * RECENT_BACKUP_MAX_AGE_MS), ago(30 * 60_000)],
+        NOW,
+      ),
+    ).toBe(true);
+  });
+
+  test("honors a custom max age", () => {
+    expect(hasRecentBackup([ago(10 * 60_000)], NOW, 5 * 60_000)).toBe(false);
+    expect(hasRecentBackup([ago(10 * 60_000)], NOW, 15 * 60_000)).toBe(true);
+  });
+});
+
+describe("readyManagedBackupCreatedAts", () => {
+  test("keeps ready snapshots and drops pending ones", () => {
+    expect(
+      readyManagedBackupCreatedAts([
+        {
+          snapshot_name: "a",
+          created_at: "2026-09-15T11:00:00Z",
+          ready_to_use: true,
+        },
+        {
+          snapshot_name: "b",
+          created_at: "2026-09-15T11:30:00Z",
+          ready_to_use: false,
+        },
+        { snapshot_name: "c", created_at: "2026-09-15T10:00:00Z" },
+      ]),
+    ).toEqual(["2026-09-15T11:00:00Z", "2026-09-15T10:00:00Z"]);
+  });
+});
+
+describe("managedBackupIsReady", () => {
+  const backups = [
+    { snapshot_name: "ready", ready_to_use: true },
+    { snapshot_name: "pending", ready_to_use: false },
+    { snapshot_name: "unknown" },
+  ];
+
+  test("true only for a snapshot explicitly marked ready", () => {
+    expect(managedBackupIsReady(backups, "ready")).toBe(true);
+    expect(managedBackupIsReady(backups, "pending")).toBe(false);
+    expect(managedBackupIsReady(backups, "unknown")).toBe(false);
+    expect(managedBackupIsReady(backups, "missing")).toBe(false);
+  });
+});

package/node_modules/@vellumai/local-mode/src/teleport-backup-policy.ts

@@ -0,0 +1,74 @@
+/**
+ * Pre-teleport backup policy shared by every teleport surface (CLI and web).
+ *
+ * A teleport ends with the source assistant being retired, so each surface
+ * snapshots the source before any data leaves it. This module holds the
+ * decisions those surfaces must agree on: how fresh an existing backup has to
+ * be to stand in for a new one, and how a platform (PVC) snapshot is judged
+ * restorable. Transport lives with each client; nothing here touches the
+ * network or the filesystem.
+ */
+
+/** A backup at most this old satisfies the pre-teleport backup requirement. */
+export const RECENT_BACKUP_MAX_AGE_MS = 60 * 60 * 1000;
+
+/** How long to wait for a freshly cut platform snapshot to become restorable. */
+export const MANAGED_BACKUP_READY_TIMEOUT_MS = 10 * 60 * 1000;
+
+/** How often to re-list platform snapshots while waiting for readiness. */
+export const MANAGED_BACKUP_READY_POLL_INTERVAL_MS = 5_000;
+
+/**
+ * Whether any of `createdAts` (ISO-8601 timestamps; empty, missing and
+ * unparseable values are ignored) falls within `maxAgeMs` of `now`.
+ */
+export function hasRecentBackup(
+  createdAts: Iterable<string | null | undefined>,
+  now: number = Date.now(),
+  maxAgeMs: number = RECENT_BACKUP_MAX_AGE_MS,
+): boolean {
+  for (const createdAt of createdAts) {
+    if (!createdAt) {
+      continue;
+    }
+    const createdMs = Date.parse(createdAt);
+    if (Number.isNaN(createdMs)) {
+      continue;
+    }
+    const age = now - createdMs;
+    if (age >= 0 && age <= maxAgeMs) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/** The fields of a platform backup listing entry the policy reads. */
+export interface ManagedBackupEntry {
+  snapshot_name?: string;
+  created_at?: string;
+  ready_to_use?: boolean;
+}
+
+/**
+ * `created_at` of every restorable platform snapshot. A snapshot still being
+ * cut (`ready_to_use: false`) never counts as a usable restore point.
+ */
+export function readyManagedBackupCreatedAts(
+  backups: readonly ManagedBackupEntry[],
+): Array<string | undefined> {
+  return backups
+    .filter((backup) => backup.ready_to_use !== false)
+    .map((backup) => backup.created_at);
+}
+
+/** Whether the listing shows `snapshotName` as restorable. */
+export function managedBackupIsReady(
+  backups: readonly ManagedBackupEntry[],
+  snapshotName: string,
+): boolean {
+  return backups.some(
+    (backup) =>
+      backup.snapshot_name === snapshotName && backup.ready_to_use === true,
+  );
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/cli",
-  "version": "0.12.1",
+  "version": "0.12.2-staging.2",
   "description": "CLI tools for vellum-assistant",
   "type": "module",
   "exports": {

package/src/__tests__/backup-ops-matching.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, test } from "bun:test";
+
+import { assistantBackupFilenamePattern } from "../lib/backup-ops.js";
+
+const STAMP = "2026-09-15T14-27-28-123Z";
+
+describe("assistantBackupFilenamePattern", () => {
+  test("matches this CLI's backups for exactly the given assistant", () => {
+    const pattern = assistantBackupFilenamePattern("alpha");
+    expect(pattern.test(`alpha-pre-upgrade-${STAMP}.vbundle`)).toBe(true);
+    expect(pattern.test(`alpha-pre-teleport-${STAMP}.vbundle`)).toBe(true);
+  });
+
+  test("does not match an assistant whose id extends this one", () => {
+    const pattern = assistantBackupFilenamePattern("alpha");
+    expect(pattern.test(`alpha-prod-pre-upgrade-${STAMP}.vbundle`)).toBe(false);
+    expect(pattern.test(`alpha-prod-pre-teleport-${STAMP}.vbundle`)).toBe(
+      false,
+    );
+  });
+
+  test("does not match a shorter id's backups from a longer id", () => {
+    const pattern = assistantBackupFilenamePattern("alpha-prod");
+    expect(pattern.test(`alpha-pre-upgrade-${STAMP}.vbundle`)).toBe(false);
+  });
+
+  test("ignores user-named vellum backup files and other kinds", () => {
+    const pattern = assistantBackupFilenamePattern("alpha");
+    expect(pattern.test(`alpha-${STAMP}.vbundle`)).toBe(false);
+    expect(pattern.test(`alpha-manual-${STAMP}.vbundle`)).toBe(false);
+    expect(pattern.test(`alpha-pre-upgrade-${STAMP}.vbundle.enc`)).toBe(false);
+  });
+
+  test("restricts to the requested kinds", () => {
+    const pattern = assistantBackupFilenamePattern("alpha", ["pre-teleport"]);
+    expect(pattern.test(`alpha-pre-teleport-${STAMP}.vbundle`)).toBe(true);
+    expect(pattern.test(`alpha-pre-upgrade-${STAMP}.vbundle`)).toBe(false);
+    expect(
+      pattern.test(`alpha-pre-teleport-prod-pre-teleport-${STAMP}.vbundle`),
+    ).toBe(false);
+  });
+
+  test("escapes regex metacharacters in ids", () => {
+    const pattern = assistantBackupFilenamePattern("a.b");
+    expect(pattern.test(`a.b-pre-upgrade-${STAMP}.vbundle`)).toBe(true);
+    expect(pattern.test(`axb-pre-upgrade-${STAMP}.vbundle`)).toBe(false);
+  });
+});

package/src/__tests__/teleport-backup.test.ts

@@ -0,0 +1,208 @@
+import {
+  afterAll,
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  mock,
+  spyOn,
+  test,
+} from "bun:test";
+
+import * as platformClient from "../lib/platform-client.js";
+import {
+  createPlatformBackup,
+  listPlatformBackups,
+} from "../lib/teleport-backup.js";
+
+const authHeadersSpy = spyOn(platformClient, "authHeaders").mockResolvedValue({
+  "Content-Type": "application/json",
+  "X-Session-Token": "platform-token",
+  "Vellum-Organization-Id": "org-1",
+});
+const invalidateOrgIdCacheSpy = spyOn(
+  platformClient,
+  "invalidateOrgIdCache",
+).mockImplementation(() => {});
+
+afterAll(() => {
+  authHeadersSpy.mockRestore();
+  invalidateOrgIdCacheSpy.mockRestore();
+});
+
+let originalFetch: typeof globalThis.fetch;
+let fetchCalls: Array<{ url: string; method: string }>;
+let responses: Array<() => Response>;
+
+beforeEach(() => {
+  originalFetch = globalThis.fetch;
+  fetchCalls = [];
+  responses = [];
+  globalThis.fetch = mock(
+    async (url: string | URL | Request, init?: RequestInit) => {
+      fetchCalls.push({
+        url: typeof url === "string" ? url : url.toString(),
+        method: init?.method ?? "GET",
+      });
+      const next = responses.shift();
+      if (!next) {
+        throw new Error("unexpected fetch");
+      }
+      return next();
+    },
+  ) as unknown as typeof globalThis.fetch;
+  authHeadersSpy.mockClear();
+  invalidateOrgIdCacheSpy.mockClear();
+});
+
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+});
+
+const ENTRY = {
+  runtimeUrl: "https://platform.vellum.ai",
+  assistantId: "11111111-2222-3333-4444-555555555555",
+};
+const BACKUPS_URL = `https://platform.vellum.ai/v1/assistants/${ENTRY.assistantId}/backups/`;
+const FAST_POLL = { pollIntervalMs: 1, timeoutMs: 200 };
+
+function json(body: unknown, status = 200): () => Response {
+  return () => Response.json(body, { status });
+}
+
+describe("listPlatformBackups", () => {
+  test("returns created_at of ready snapshots only", async () => {
+    responses.push(
+      json({
+        backups: [
+          { created_at: "2026-09-15T11:00:00Z", ready_to_use: true },
+          { created_at: "2026-09-15T11:30:00Z", ready_to_use: false },
+          { created_at: "2026-09-15T10:00:00Z" },
+        ],
+      }),
+    );
+
+    const result = await listPlatformBackups(ENTRY, "platform-token");
+
+    expect(result).toEqual(["2026-09-15T11:00:00Z", "2026-09-15T10:00:00Z"]);
+    expect(fetchCalls[0]).toEqual({ url: BACKUPS_URL, method: "GET" });
+    expect(authHeadersSpy).toHaveBeenCalledWith(
+      "platform-token",
+      "https://platform.vellum.ai",
+    );
+  });
+
+  test("refreshes the org id cache and retries once on 401", async () => {
+    responses.push(() => new Response("unauthorized", { status: 401 }));
+    responses.push(json({ backups: [] }));
+
+    const result = await listPlatformBackups(ENTRY, "platform-token");
+
+    expect(result).toEqual([]);
+    expect(fetchCalls).toHaveLength(2);
+    expect(invalidateOrgIdCacheSpy).toHaveBeenCalledWith(
+      "platform-token",
+      "https://platform.vellum.ai",
+    );
+  });
+
+  test("throws on a persistent error", async () => {
+    responses.push(() => new Response("Bad gateway", { status: 502 }));
+
+    await expect(listPlatformBackups(ENTRY, "platform-token")).rejects.toThrow(
+      "Platform backup list failed (502): Bad gateway",
+    );
+  });
+});
+
+describe("createPlatformBackup", () => {
+  test("returns immediately when the POST reports the snapshot ready", async () => {
+    responses.push(json({ snapshot_name: "snap-1", ready_to_use: true }, 201));
+
+    await createPlatformBackup(ENTRY, "platform-token", FAST_POLL);
+
+    expect(fetchCalls).toEqual([{ url: BACKUPS_URL, method: "POST" }]);
+  });
+
+  test("polls the listing until the new snapshot is ready", async () => {
+    responses.push(json({ snapshot_name: "snap-1", ready_to_use: false }, 201));
+    responses.push(
+      json({ backups: [{ snapshot_name: "snap-1", ready_to_use: false }] }),
+    );
+    responses.push(
+      json({
+        backups: [
+          { snapshot_name: "older", ready_to_use: true },
+          { snapshot_name: "snap-1", ready_to_use: true },
+        ],
+      }),
+    );
+
+    await createPlatformBackup(ENTRY, "platform-token", FAST_POLL);
+
+    expect(fetchCalls.map((call) => call.method)).toEqual([
+      "POST",
+      "GET",
+      "GET",
+    ]);
+  });
+
+  test("another ready snapshot does not satisfy the wait", async () => {
+    responses.push(json({ snapshot_name: "snap-1" }, 201));
+    responses.push(
+      json({ backups: [{ snapshot_name: "older", ready_to_use: true }] }),
+    );
+    responses.push(
+      json({ backups: [{ snapshot_name: "snap-1", ready_to_use: true }] }),
+    );
+
+    await createPlatformBackup(ENTRY, "platform-token", FAST_POLL);
+
+    expect(fetchCalls).toHaveLength(3);
+  });
+
+  test("throws when the snapshot is not ready before the timeout", async () => {
+    responses.push(json({ snapshot_name: "snap-1", ready_to_use: false }, 201));
+    const pending = json({
+      backups: [{ snapshot_name: "snap-1", ready_to_use: false }],
+    });
+    for (let i = 0; i < 1000; i++) {
+      responses.push(pending);
+    }
+
+    await expect(
+      createPlatformBackup(ENTRY, "platform-token", {
+        pollIntervalMs: 1,
+        timeoutMs: 30,
+      }),
+    ).rejects.toThrow("Platform backup snap-1 was not ready after 0s");
+  });
+
+  test("throws when the POST fails", async () => {
+    responses.push(
+      () => new Response('{"detail":"Bad gateway"}', { status: 502 }),
+    );
+
+    await expect(
+      createPlatformBackup(ENTRY, "platform-token", FAST_POLL),
+    ).rejects.toThrow("Platform backup create failed (502)");
+    expect(fetchCalls).toHaveLength(1);
+  });
+
+  test("throws when the POST returns no snapshot name", async () => {
+    responses.push(json({}, 201));
+
+    await expect(
+      createPlatformBackup(ENTRY, "platform-token", FAST_POLL),
+    ).rejects.toThrow("no snapshot name");
+  });
+
+  test("a listing failure while waiting is fatal", async () => {
+    responses.push(json({ snapshot_name: "snap-1" }, 201));
+    responses.push(() => new Response("Bad gateway", { status: 502 }));
+
+    await expect(
+      createPlatformBackup(ENTRY, "platform-token", FAST_POLL),
+    ).rejects.toThrow("Platform backup list failed (502)");
+  });
+});

package/src/__tests__/teleport.test.ts

@@ -39,6 +39,8 @@ import * as assistantConfig from "../lib/assistant-config.js";
 import * as guardianToken from "../lib/guardian-token.js";
 import * as platformClient from "../lib/platform-client.js";
 import * as localRuntimeClient from "../lib/local-runtime-client.js";
+import * as backupOps from "../lib/backup-ops.js";
+import * as teleportBackup from "../lib/teleport-backup.js";
 
 // Snapshot the real exports before any `mock.module()` call so we can
 // reliably restore them after this file's tests complete, regardless of
@@ -47,6 +49,8 @@ const realAssistantConfig = { ...assistantConfig };
 const realGuardianToken = { ...guardianToken };
 const realPlatformClient = { ...platformClient };
 const realLocalRuntimeClient = { ...localRuntimeClient };
+const realBackupOps = { ...backupOps };
+const realTeleportBackup = { ...teleportBackup };
 
 const findAssistantByNameMock = mock<
   typeof assistantConfig.findAssistantByName
@@ -282,6 +286,36 @@ mock.module("../lib/local-runtime-client.js", () => ({
   localRuntimePreflightFromGcs: localRuntimePreflightFromGcsMock,
 }));
 
+// Pre-export source backup. Default to "no backups yet" so the create path
+// runs; individual tests override to exercise reuse and failure.
+const listAssistantBackupTimesMock = mock<
+  typeof backupOps.listAssistantBackupTimes
+>(() => []);
+const createBackupMock = mock<typeof backupOps.createBackup>(
+  async () => "/tmp/backups/my-local-pre-teleport-2026.vbundle",
+);
+const pruneOldBackupsMock = mock<typeof backupOps.pruneOldBackups>(() => {});
+
+mock.module("../lib/backup-ops.js", () => ({
+  ...realBackupOps,
+  listAssistantBackupTimes: listAssistantBackupTimesMock,
+  createBackup: createBackupMock,
+  pruneOldBackups: pruneOldBackupsMock,
+}));
+
+const listPlatformBackupsMock = mock<typeof teleportBackup.listPlatformBackups>(
+  async () => [],
+);
+const createPlatformBackupMock = mock<
+  typeof teleportBackup.createPlatformBackup
+>(async () => {});
+
+mock.module("../lib/teleport-backup.js", () => ({
+  ...realTeleportBackup,
+  listPlatformBackups: listPlatformBackupsMock,
+  createPlatformBackup: createPlatformBackupMock,
+}));
+
 // Snapshot the remaining real modules before mocking so `afterAll` can
 // restore them too — otherwise these mocks leak into sibling test files that
 // import the same modules in the same `bun test` run.
@@ -362,6 +396,8 @@ afterAll(() => {
   mock.module("../lib/guardian-token.js", () => realGuardianToken);
   mock.module("../lib/platform-client.js", () => realPlatformClient);
   mock.module("../lib/local-runtime-client.js", () => realLocalRuntimeClient);
+  mock.module("../lib/backup-ops.js", () => realBackupOps);
+  mock.module("../lib/teleport-backup.js", () => realTeleportBackup);
   mock.module("../lib/hatch-local.js", () => realHatchLocal);
   mock.module("../lib/docker.js", () => realDocker);
   mock.module("../lib/process.js", () => realProcess);
@@ -532,6 +568,19 @@ beforeEach(() => {
   localRuntimePollJobStatusMock.mockReset();
   localRuntimePollJobStatusMock.mockImplementation(defaultLocalRuntimePollImpl);
 
+  listAssistantBackupTimesMock.mockReset();
+  listAssistantBackupTimesMock.mockReturnValue([]);
+  createBackupMock.mockReset();
+  createBackupMock.mockResolvedValue(
+    "/tmp/backups/my-local-pre-teleport-2026.vbundle",
+  );
+  pruneOldBackupsMock.mockReset();
+  pruneOldBackupsMock.mockImplementation(() => {});
+  listPlatformBackupsMock.mockReset();
+  listPlatformBackupsMock.mockResolvedValue([]);
+  createPlatformBackupMock.mockReset();
+  createPlatformBackupMock.mockResolvedValue(undefined);
+
   hatchLocalMock.mockReset();
   hatchLocalMock.mockResolvedValue(undefined);
   hatchDockerMock.mockReset();
@@ -2019,6 +2068,254 @@ describe("dry-run", () => {
 // Pre-check: block teleport to platform when existing assistant detected
 // ---------------------------------------------------------------------------
 
+describe("pre-export source backup", () => {
+  test("local source with no recent backup: exports a host-side backup before exporting", async () => {
+    setArgv("--from", "my-local", "--platform");
+    const localEntry = makeEntry("my-local", { cloud: "local" });
+    findAssistantByNameMock.mockImplementation((name: string) =>
+      name === "my-local" ? localEntry : null,
+    );
+
+    const order: string[] = [];
+    createBackupMock.mockImplementation(async () => {
+      order.push("backup");
+      return "/tmp/backups/my-local-pre-teleport-2026.vbundle";
+    });
+    localRuntimeExportToGcsMock.mockImplementation(async () => {
+      order.push("export");
+      return { jobId: "local-export-job-1" };
+    });
+
+    const restoreFetch = installTrackingFetch();
+    try {
+      await teleport();
+    } finally {
+      restoreFetch();
+    }
+
+    expect(listAssistantBackupTimesMock).toHaveBeenCalledWith("my-local");
+    expect(createBackupMock).toHaveBeenCalledWith(
+      "http://localhost:7821",
+      "my-local",
+      expect.objectContaining({ prefix: "my-local-pre-teleport" }),
+    );
+    expect(pruneOldBackupsMock).toHaveBeenCalledWith(
+      "my-local",
+      3,
+      "pre-teleport",
+    );
+    expect(createPlatformBackupMock).not.toHaveBeenCalled();
+    expect(order).toEqual(["backup", "export"]);
+  });
+
+  test("local source with a recent backup: reuses it and skips the export", async () => {
+    setArgv("--from", "my-local", "--platform");
+    const localEntry = makeEntry("my-local", { cloud: "local" });
+    findAssistantByNameMock.mockImplementation((name: string) =>
+      name === "my-local" ? localEntry : null,
+    );
+    listAssistantBackupTimesMock.mockReturnValue([
+      new Date(Date.now() - 5 * 60_000).toISOString(),
+    ]);
+
+    const restoreFetch = installTrackingFetch();
+    try {
+      await teleport();
+    } finally {
+      restoreFetch();
+    }
+
+    expect(createBackupMock).not.toHaveBeenCalled();
+    expect(localRuntimeExportToGcsMock).toHaveBeenCalled();
+  });
+
+  test("local source with only stale backups: takes a fresh one", async () => {
+    setArgv("--from", "my-local", "--platform");
+    const localEntry = makeEntry("my-local", { cloud: "local" });
+    findAssistantByNameMock.mockImplementation((name: string) =>
+      name === "my-local" ? localEntry : null,
+    );
+    listAssistantBackupTimesMock.mockReturnValue([
+      new Date(Date.now() - 3 * 60 * 60_000).toISOString(),
+    ]);
+
+    const restoreFetch = installTrackingFetch();
+    try {
+      await teleport();
+    } finally {
+      restoreFetch();
+    }
+
+    expect(createBackupMock).toHaveBeenCalledTimes(1);
+  });
+
+  test("docker source: backs up host-side through its runtime URL", async () => {
+    setArgv("--from", "my-docker", "--local");
+    const dockerEntry = makeEntry("my-docker", {
+      cloud: "docker",
+      runtimeUrl: "http://localhost:9821",
+    });
+    findAssistantByNameMock.mockImplementation((name: string) =>
+      name === "my-docker" ? dockerEntry : null,
+    );
+    const freshLocal = makeEntry("fresh-local", { cloud: "local" });
+    loadAllAssistantsMock.mockImplementation(() =>
+      hatchLocalMock.mock.calls.length > 0
+        ? [dockerEntry, freshLocal]
+        : [dockerEntry],
+    );
+
+    const restoreFetch = installTrackingFetch();
+    try {
+      await teleport();
+    } finally {
+      restoreFetch();
+    }
+
+    expect(createBackupMock).toHaveBeenCalledWith(
+      "http://localhost:9821",
+      "my-docker",
+      expect.objectContaining({ prefix: "my-docker-pre-teleport" }),
+    );
+  });
+
+  test("platform source: takes a PVC snapshot through the source platform before exporting", async () => {
+    setArgv("--from", "my-platform", "--local", "my-local");
+    const platformEntry = makeEntry("my-platform", {
+      cloud: "vellum",
+      runtimeUrl: "https://platform.vellum.ai",
+    });
+    const localEntry = makeEntry("my-local", { cloud: "local" });
+    findAssistantByNameMock.mockImplementation((name: string) => {
+      if (name === "my-platform") return platformEntry;
+      if (name === "my-local") return localEntry;
+      return null;
+    });
+
+    const order: string[] = [];
+    createPlatformBackupMock.mockImplementation(async () => {
+      order.push("backup");
+    });
+    localRuntimeExportToGcsMock.mockImplementation(async () => {
+      order.push("export");
+      return { jobId: "local-export-job-1" };
+    });
+
+    const restoreFetch = installTrackingFetch();
+    try {
+      await teleport();
+    } finally {
+      restoreFetch();
+    }
+
+    expect(listPlatformBackupsMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        assistantId: "my-platform",
+        runtimeUrl: "https://platform.vellum.ai",
+      }),
+      "platform-token",
+    );
+    expect(createPlatformBackupMock).toHaveBeenCalledWith(
+      expect.objectContaining({ assistantId: "my-platform" }),
+      "platform-token",
+    );
+    expect(createBackupMock).not.toHaveBeenCalled();
+    expect(order).toEqual(["backup", "export"]);
+  });
+
+  test("platform source with a recent ready snapshot: reuses it", async () => {
+    setArgv("--from", "my-platform", "--local", "my-local");
+    const platformEntry = makeEntry("my-platform", {
+      cloud: "vellum",
+      runtimeUrl: "https://platform.vellum.ai",
+    });
+    const localEntry = makeEntry("my-local", { cloud: "local" });
+    findAssistantByNameMock.mockImplementation((name: string) => {
+      if (name === "my-platform") return platformEntry;
+      if (name === "my-local") return localEntry;
+      return null;
+    });
+    listPlatformBackupsMock.mockResolvedValue([
+      new Date(Date.now() - 20 * 60_000).toISOString(),
+    ]);
+
+    const restoreFetch = installTrackingFetch();
+    try {
+      await teleport();
+    } finally {
+      restoreFetch();
+    }
+
+    expect(createPlatformBackupMock).not.toHaveBeenCalled();
+    expect(localRuntimeExportToGcsMock).toHaveBeenCalled();
+  });
+
+  test("host-side backup failure aborts before export and before hatching", async () => {
+    setArgv("--from", "my-local", "--platform");
+    const localEntry = makeEntry("my-local", { cloud: "local" });
+    findAssistantByNameMock.mockImplementation((name: string) =>
+      name === "my-local" ? localEntry : null,
+    );
+    createBackupMock.mockResolvedValue(null);
+
+    const restoreFetch = installTrackingFetch();
+    try {
+      await expect(teleport()).rejects.toThrow("process.exit:1");
+    } finally {
+      restoreFetch();
+    }
+
+    expect(localRuntimeExportToGcsMock).not.toHaveBeenCalled();
+    expect(hatchAssistantMock).not.toHaveBeenCalled();
+    expect(platformImportBundleFromGcsMock).not.toHaveBeenCalled();
+    expect(consoleErrorSpy).toHaveBeenCalledWith(
+      expect.stringContaining("Could not back up 'my-local'"),
+    );
+  });
+
+  test("platform snapshot failure (never ready) aborts too", async () => {
+    setArgv("--from", "my-platform", "--local", "my-local");
+    const platformEntry = makeEntry("my-platform", {
+      cloud: "vellum",
+      runtimeUrl: "https://platform.vellum.ai",
+    });
+    const localEntry = makeEntry("my-local", { cloud: "local" });
+    findAssistantByNameMock.mockImplementation((name: string) => {
+      if (name === "my-platform") return platformEntry;
+      if (name === "my-local") return localEntry;
+      return null;
+    });
+    createPlatformBackupMock.mockRejectedValue(
+      new Error("Platform backup snap-1 was not ready after 600s"),
+    );
+
+    const restoreFetch = installTrackingFetch();
+    try {
+      await expect(teleport()).rejects.toThrow("process.exit:1");
+    } finally {
+      restoreFetch();
+    }
+
+    expect(localRuntimeExportToGcsMock).not.toHaveBeenCalled();
+    expect(consoleErrorSpy).toHaveBeenCalledWith(
+      expect.stringContaining("was not ready"),
+    );
+  });
+
+  test("dry-run never backs up the source", async () => {
+    setArgv("--from", "my-local", "--platform", "--dry-run");
+    const localEntry = makeEntry("my-local", { cloud: "local" });
+    findAssistantByNameMock.mockImplementation((name: string) =>
+      name === "my-local" ? localEntry : null,
+    );
+
+    await teleport();
+
+    expect(listAssistantBackupTimesMock).not.toHaveBeenCalled();
+    expect(createBackupMock).not.toHaveBeenCalled();
+  });
+});
+
 describe("pre-check: existing platform assistant", () => {
   test("blocks before any work when pre-check finds existing assistant", async () => {
     setArgv("--from", "my-local", "--platform");

package/src/commands/teleport.ts

@@ -37,6 +37,15 @@ import {
   MigrationInProgressError,
 } from "../lib/local-runtime-client.js";
 import { pollJobUntilDone } from "../lib/job-polling.js";
+import {
+  createBackup,
+  listAssistantBackupTimes,
+  pruneOldBackups,
+} from "../lib/backup-ops.js";
+import {
+  createPlatformBackup,
+  listPlatformBackups,
+} from "../lib/teleport-backup.js";
 import {
   hatchDocker,
   retireDocker,
@@ -56,6 +65,10 @@ import {
 } from "../lib/upgrade-lifecycle.js";
 import { compareVersions } from "../lib/version-compat.js";
 import { join } from "node:path";
+import {
+  hasRecentBackup,
+  RECENT_BACKUP_MAX_AGE_MS,
+} from "@vellumai/local-mode/teleport-backup-policy";
 
 function printHelp(): void {
   console.log(
@@ -88,6 +101,20 @@ function printHelp(): void {
   );
   console.log("transfers (e.g. local to local) are not supported.");
   console.log("");
+  console.log(
+    "Before exporting, the source assistant is backed up. Platform sources",
+  );
+  console.log(
+    "get a PVC snapshot (waited on until restorable); local and docker",
+  );
+  console.log(
+    "sources get a .vbundle written to ~/.local/share/vellum/backups/ on this",
+  );
+  console.log(
+    `machine. A backup of the source taken within the last ${RECENT_BACKUP_MAX_AGE_MS / 60_000} minutes is`,
+  );
+  console.log("reused. If the backup fails, the teleport is aborted.");
+  console.log("");
   console.log(
     "For local-to-docker and docker-to-local transfers, the source assistant",
   );
@@ -363,6 +390,70 @@ interface ImportResponse {
   };
 }
 
+// ---------------------------------------------------------------------------
+// Pre-export safety backup of the source
+//
+// Runs before any data leaves the source. Reuses a backup of this assistant
+// younger than RECENT_BACKUP_MAX_AGE_MS; otherwise takes one and blocks until
+// it is usable. Any failure aborts the teleport: the source is retired at the
+// end of a successful teleport, and that is only safe with a restore point
+// behind it.
+//
+// Local and docker sources are exported to the host's CLI backup directory
+// rather than snapshotted by their own gateway: docker retirement removes
+// every source volume (including the gateway's backup pool), and bare-metal
+// gateways share one unlabelled pool across assistants, so neither would
+// give this assistant a restore point that outlives the teleport.
+// ---------------------------------------------------------------------------
+
+/** Export timeout for the host-side pre-teleport backup of a local/docker source. */
+const LOCAL_SOURCE_BACKUP_TIMEOUT_MS = 30 * 60 * 1000;
+
+async function backupSourceBeforeTeleport(
+  entry: AssistantEntry,
+  cloud: string,
+  displayName: string,
+): Promise<void> {
+  console.log(`Backing up ${displayName} (${cloud})...`);
+  try {
+    if (cloud === "vellum") {
+      const platformToken = readPlatformToken();
+      if (!platformToken) {
+        console.error("Not logged in. Run 'vellum login' first.");
+        process.exit(1);
+      }
+      const createdAts = await listPlatformBackups(entry, platformToken);
+      if (hasRecentBackup(createdAts)) {
+        console.log("Recent backup found, reusing it.");
+        return;
+      }
+      await createPlatformBackup(entry, platformToken);
+      console.log("Backup complete.");
+      return;
+    }
+
+    if (hasRecentBackup(listAssistantBackupTimes(entry.assistantId))) {
+      console.log("Recent backup found, reusing it.");
+      return;
+    }
+    const backupPath = await createBackup(entry.runtimeUrl, entry.assistantId, {
+      prefix: `${entry.assistantId}-pre-teleport`,
+      description: `Pre-teleport snapshot of ${displayName} (${cloud})`,
+      timeoutMs: LOCAL_SOURCE_BACKUP_TIMEOUT_MS,
+    });
+    if (!backupPath) {
+      throw new Error("backup export failed (see warning above)");
+    }
+    pruneOldBackups(entry.assistantId, 3, "pre-teleport");
+    console.log(`Backup saved: ${backupPath}`);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(`Error: Could not back up '${displayName}': ${msg}`);
+    console.error("Teleport aborted; the source assistant was not modified.");
+    process.exit(1);
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Export from source — unified GCS flow
 //
@@ -1399,6 +1490,8 @@ export async function teleport(): Promise<void> {
     // where the import will run. For existing targets that's the lockfile's
     // runtimeUrl; for fresh hatches it's getPlatformUrl() (which is what
     // resolveOrHatchTarget writes to the new entry).
+    await backupSourceBeforeTeleport(fromEntry, fromCloud, from);
+
     console.log(`Exporting from ${from} (${fromCloud})...`);
     const bundlePlatformUrl = targetPlatformUrl ?? getPlatformUrl();
     const { bundleKey } = await exportFromAssistant(
@@ -1469,6 +1562,8 @@ export async function teleport(): Promise<void> {
   const bundlePlatformUrl =
     fromCloud === "vellum" ? fromEntry.runtimeUrl : getPlatformUrl();
 
+  await backupSourceBeforeTeleport(fromEntry, fromCloud, from);
+
   // Export from source (bundle lives in GCS after this returns).
   console.log(`Exporting from ${from} (${fromCloud})...`);
   const { bundleKey } = await exportFromAssistant(

package/src/lib/backup-ops.ts

@@ -3,6 +3,7 @@ import {
   mkdirSync,
   readdirSync,
   readFileSync,
+  statSync,
   unlinkSync,
   writeFileSync,
 } from "fs";
@@ -60,8 +61,9 @@ async function getGuardianAccessToken(
 export async function createBackup(
   runtimeUrl: string,
   assistantId: string,
-  options?: { prefix?: string; description?: string },
+  options?: { prefix?: string; description?: string; timeoutMs?: number },
 ): Promise<string | null> {
+  const timeoutMs = options?.timeoutMs ?? 120_000;
   try {
     let accessToken = await getGuardianAccessToken(runtimeUrl, assistantId);
     if (!accessToken) {
@@ -82,7 +84,7 @@ export async function createBackup(
         body: JSON.stringify({
           description: options?.description ?? "CLI backup",
         }),
-        signal: AbortSignal.timeout(120_000),
+        signal: AbortSignal.timeout(timeoutMs),
       },
     );
 
@@ -106,7 +108,7 @@ export async function createBackup(
         body: JSON.stringify({
           description: options?.description ?? "CLI backup",
         }),
-        signal: AbortSignal.timeout(120_000),
+        signal: AbortSignal.timeout(timeoutMs),
       });
     }
 
@@ -283,19 +285,84 @@ export async function restoreBackup(
   }
 }
 
+/** Filename kinds this CLI writes: `<assistantId>-<kind>-<timestamp>.vbundle`. */
+export const CLI_BACKUP_KINDS = ["pre-upgrade", "pre-teleport"] as const;
+export type CliBackupKind = (typeof CLI_BACKUP_KINDS)[number];
+
+/** `new Date().toISOString().replace(/[:.]/g, "-")`, as used in every CLI backup filename. */
+const BACKUP_TIMESTAMP_PATTERN =
+  "\\d{4}-\\d{2}-\\d{2}T\\d{2}-\\d{2}-\\d{2}-\\d{3}Z";
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * Matches the backup filenames this CLI wrote for exactly `assistantId` and
+ * one of `kinds`. The kind and timestamp segments are matched in full, so an
+ * assistant whose id is a prefix of another's (`alpha` vs `alpha-prod`, or
+ * `alpha` vs `alpha-pre-teleport-prod`) never matches the other's files.
+ */
+export function assistantBackupFilenamePattern(
+  assistantId: string,
+  kinds: readonly CliBackupKind[] = CLI_BACKUP_KINDS,
+): RegExp {
+  return new RegExp(
+    `^${escapeRegExp(assistantId)}-(?:${kinds.join("|")})-${BACKUP_TIMESTAMP_PATTERN}\\.vbundle$`,
+  );
+}
+
+/**
+ * Modification times of the `.vbundle` backups this CLI has written for
+ * `assistantId` (every kind in `CLI_BACKUP_KINDS`), as ISO timestamps.
+ * Missing directory yields `[]`.
+ */
+export function listAssistantBackupTimes(assistantId: string): string[] {
+  const backupsDir = getBackupsDir();
+  let names: string[];
+  try {
+    names = readdirSync(backupsDir);
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+      return [];
+    }
+    throw err;
+  }
+  const pattern = assistantBackupFilenamePattern(assistantId);
+  const times: string[] = [];
+  for (const name of names) {
+    if (!pattern.test(name)) {
+      continue;
+    }
+    try {
+      times.push(statSync(join(backupsDir, name)).mtime.toISOString());
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== "ENOENT") {
+        throw err;
+      }
+    }
+  }
+  return times;
+}
+
 /**
- * Keep only the N most recent pre-upgrade backups for an assistant,
- * deleting older ones. Default: keep 3.
+ * Keep only the N most recent backups of one `kind` for an assistant,
+ * deleting older ones. Filenames are matched exactly (id, kind and
+ * timestamp), never by prefix. Default: keep 3 pre-upgrade backups.
  * Never throws — failures are silently ignored.
  */
-export function pruneOldBackups(assistantId: string, keep: number = 3): void {
+export function pruneOldBackups(
+  assistantId: string,
+  keep: number = 3,
+  kind: CliBackupKind = "pre-upgrade",
+): void {
   try {
     const backupsDir = getBackupsDir();
     if (!existsSync(backupsDir)) return;
 
-    const prefix = `${assistantId}-pre-upgrade-`;
+    const pattern = assistantBackupFilenamePattern(assistantId, [kind]);
     const entries = readdirSync(backupsDir)
-      .filter((f) => f.startsWith(prefix) && f.endsWith(".vbundle"))
+      .filter((f) => pattern.test(f))
       .sort();
 
     if (entries.length <= keep) return;

package/src/lib/teleport-backup.ts

@@ -0,0 +1,139 @@
+/**
+ * Platform (cloud="vellum") half of the pre-teleport safety backup.
+ *
+ * A platform source is snapshotted through Django's user-facing backup
+ * endpoint, which cuts a PVC VolumeSnapshot via vembda. The POST returns as
+ * soon as the snapshot object exists; it becomes restorable asynchronously,
+ * so {@link createPlatformBackup} polls the listing until the new snapshot
+ * reports `ready_to_use` before returning. A snapshot that never becomes
+ * ready within the timeout is a backup failure, not a success.
+ *
+ * Local and docker sources are backed up host-side by `backup-ops` instead,
+ * so the restore point survives the source's retirement. Policy shared with
+ * the web teleport lives in `@vellumai/local-mode/teleport-backup-policy`.
+ */
+
+import {
+  MANAGED_BACKUP_READY_POLL_INTERVAL_MS,
+  MANAGED_BACKUP_READY_TIMEOUT_MS,
+  managedBackupIsReady,
+  readyManagedBackupCreatedAts,
+  type ManagedBackupEntry,
+} from "@vellumai/local-mode/teleport-backup-policy";
+
+import type { AssistantEntry } from "./assistant-config.js";
+import { loopbackSafeFetch } from "./loopback-fetch.js";
+import { authHeaders, invalidateOrgIdCache } from "./platform-client.js";
+
+type PlatformEntry = Pick<AssistantEntry, "runtimeUrl" | "assistantId">;
+
+function platformBackupsUrl(entry: PlatformEntry): string {
+  return `${entry.runtimeUrl}/v1/assistants/${entry.assistantId}/backups/`;
+}
+
+async function errorSuffix(response: Response): Promise<string> {
+  const body = await response.text().catch(() => "");
+  return `(${response.status})${body ? `: ${body}` : ""}`;
+}
+
+/**
+ * Send a platform backup request with user-session auth, refreshing the
+ * cached organization id once on 401 (the same recovery the runtime identity
+ * probe applies).
+ */
+async function platformBackupRequest(
+  entry: PlatformEntry,
+  token: string,
+  method: "GET" | "POST",
+): Promise<Response> {
+  const doRequest = async (): Promise<Response> =>
+    loopbackSafeFetch(platformBackupsUrl(entry), {
+      method,
+      headers: {
+        ...(await authHeaders(token, entry.runtimeUrl)),
+        Accept: "application/json",
+      },
+    });
+  let response = await doRequest();
+  if (response.status === 401) {
+    invalidateOrgIdCache(token, entry.runtimeUrl);
+    response = await doRequest();
+  }
+  return response;
+}
+
+async function fetchPlatformBackups(
+  entry: PlatformEntry,
+  token: string,
+): Promise<ManagedBackupEntry[]> {
+  const response = await platformBackupRequest(entry, token, "GET");
+  if (!response.ok) {
+    throw new Error(
+      `Platform backup list failed ${await errorSuffix(response)}`,
+    );
+  }
+  const body = (await response.json()) as { backups?: ManagedBackupEntry[] };
+  return body.backups ?? [];
+}
+
+/**
+ * `created_at` of every restorable PVC snapshot of a platform assistant:
+ * `GET /v1/assistants/<id>/backups/`.
+ */
+export async function listPlatformBackups(
+  entry: PlatformEntry,
+  token: string,
+): Promise<Array<string | undefined>> {
+  return readyManagedBackupCreatedAts(await fetchPlatformBackups(entry, token));
+}
+
+export interface CreatePlatformBackupOptions {
+  timeoutMs?: number;
+  pollIntervalMs?: number;
+}
+
+/**
+ * Take a PVC snapshot of a platform assistant and wait until it is
+ * restorable: `POST /v1/assistants/<id>/backups/`, then re-list until the
+ * returned `snapshot_name` reports `ready_to_use`. Throws if the POST fails
+ * or the snapshot is not ready within `timeoutMs`.
+ */
+export async function createPlatformBackup(
+  entry: PlatformEntry,
+  token: string,
+  options: CreatePlatformBackupOptions = {},
+): Promise<void> {
+  const timeoutMs = options.timeoutMs ?? MANAGED_BACKUP_READY_TIMEOUT_MS;
+  const pollIntervalMs =
+    options.pollIntervalMs ?? MANAGED_BACKUP_READY_POLL_INTERVAL_MS;
+
+  const response = await platformBackupRequest(entry, token, "POST");
+  if (!response.ok) {
+    throw new Error(
+      `Platform backup create failed ${await errorSuffix(response)}`,
+    );
+  }
+  const created = (await response.json().catch(() => null)) as {
+    snapshot_name?: string;
+    ready_to_use?: boolean;
+  } | null;
+  const snapshotName = created?.snapshot_name;
+  if (!snapshotName) {
+    throw new Error("Platform backup create returned no snapshot name");
+  }
+  if (created?.ready_to_use === true) {
+    return;
+  }
+
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+    const backups = await fetchPlatformBackups(entry, token);
+    if (managedBackupIsReady(backups, snapshotName)) {
+      return;
+    }
+  }
+  throw new Error(
+    `Platform backup ${snapshotName} was not ready after ${Math.round(timeoutMs / 1000)}s`,
+  );
+}