@vellumai/cli 0.12.1 → 0.12.2-dev.202609162214.308bda0

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/__tests__/docker.test.ts

@@ -83,6 +83,7 @@ describe("buildServiceRunArgs — assistant", () => {
     const args = buildAssistantArgs();
     expect(args).toContain("IS_CONTAINERIZED=true");
     expect(args).toContain("VELLUM_WORKSPACE_DIR=/workspace");
+    expect(args).toContain("CES_BOOTSTRAP_SOCKET_DIR=/run/ces-bootstrap");
     expect(args).toContain(`VELLUM_ASSISTANT_NAME=${instanceName}`);
   });
 

package/src/lib/__tests__/local-ces.test.ts

@@ -9,6 +9,8 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterAll, beforeAll, describe, expect, mock, test } from "bun:test";
 
+import { resolveIpcEndpoint } from "@vellumai/ipc-server-utils";
+
 import { resolveCesSocketPath, startCes } from "../local.js";
 
 // ---------------------------------------------------------------------------
@@ -106,7 +108,7 @@ describe("startCes", () => {
     // startCes unlinks the stale socket, then polls for it. We create it with
     // a slight delay so the poll catches it.
     setTimeout(() => {
-      const socketDir = join(vellumDir, "workspace");
+      const socketDir = join(vellumDir, "protected", "credential-executor");
       mkdirSync(socketDir, { recursive: true });
       writeFileSync(join(socketDir, "ces.sock"), "");
     }, 50);
@@ -126,7 +128,9 @@ describe("startCes", () => {
 
     // Verify env vars
     const env = lastSpawnCall!.options.env!;
-    expect(env["CES_LOCAL_SOCKET"]).toBeDefined();
+    expect(env["CES_BOOTSTRAP_SOCKET_DIR"]).toBe(
+      join(tempDir, ".vellum", "protected", "credential-executor"),
+    );
     expect(env["CREDENTIAL_SECURITY_DIR"]).toBeDefined();
     expect(env["VELLUM_WORKSPACE_DIR"]).toBeDefined();
 
@@ -143,4 +147,23 @@ describe("startCes", () => {
     expect(socketPath.startsWith("\\\\.\\pipe\\vellum-ces-")).toBe(true);
     expect(socketPath).not.toContain("Example");
   });
+
+  test("POSIX local CES seam matches resolveIpcEndpoint", () => {
+    const resources = {
+      instanceDir: "/tmp/assistant-123",
+    } as Parameters<typeof resolveCesSocketPath>[0];
+
+    const socketPath = resolveCesSocketPath(resources, "linux");
+    expect(socketPath).toBe(
+      resolveIpcEndpoint("ces", {
+        workspaceDir: join(
+          "/tmp/assistant-123",
+          ".vellum",
+          "protected",
+          "credential-executor",
+        ),
+        platform: "linux",
+      }).path,
+    );
+  });
 });

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;