@vellumai/cli 0.5.15 → 0.6.0

package/src/__tests__/teleport.test.ts

@@ -1,5 +1,6 @@
 import {
   afterAll,
+  afterEach,
   beforeEach,
   describe,
   expect,
@@ -33,6 +34,21 @@ const findAssistantByNameMock = spyOn(
   "findAssistantByName",
 ).mockReturnValue(null);
 
+const saveAssistantEntryMock = spyOn(
+  assistantConfig,
+  "saveAssistantEntry",
+).mockImplementation(() => {});
+
+const loadAllAssistantsMock = spyOn(
+  assistantConfig,
+  "loadAllAssistants",
+).mockReturnValue([]);
+
+const removeAssistantEntryMock = spyOn(
+  assistantConfig,
+  "removeAssistantEntry",
+).mockImplementation(() => {});
+
 const loadGuardianTokenMock = mock((_id: string) => ({
   accessToken: "local-token",
   accessTokenExpiresAt: new Date(Date.now() + 60_000).toISOString(),
@@ -49,6 +65,12 @@ mock.module("../lib/guardian-token.js", () => ({
 
 const readPlatformTokenMock = mock((): string | null => "platform-token");
 const fetchOrganizationIdMock = mock(async () => "org-123");
+const getPlatformUrlMock = mock(() => "https://platform.vellum.ai");
+const hatchAssistantMock = mock(async () => ({
+  id: "platform-new-id",
+  name: "platform-new",
+  status: "active",
+}));
 const platformInitiateExportMock = mock(async () => ({
   jobId: "job-1",
   status: "pending",
@@ -86,18 +108,95 @@ const platformImportBundleMock = mock(async () => ({
     },
   } as Record<string, unknown>,
 }));
+const platformRequestUploadUrlMock = mock(async () => ({
+  uploadUrl: "https://storage.googleapis.com/bucket/signed-upload-url",
+  bundleKey: "bundle-key-123",
+  expiresAt: new Date(Date.now() + 3600_000).toISOString(),
+}));
+const platformUploadToSignedUrlMock = mock(async () => {});
+const platformImportPreflightFromGcsMock = mock(async () => ({
+  statusCode: 200,
+  body: {
+    can_import: true,
+    summary: {
+      files_to_create: 2,
+      files_to_overwrite: 1,
+      files_unchanged: 0,
+      total_files: 3,
+    },
+  } as Record<string, unknown>,
+}));
+const platformImportBundleFromGcsMock = mock(async () => ({
+  statusCode: 200,
+  body: {
+    success: true,
+    summary: {
+      total_files: 3,
+      files_created: 2,
+      files_overwritten: 1,
+      files_skipped: 0,
+      backups_created: 1,
+    },
+  } as Record<string, unknown>,
+}));
 
 mock.module("../lib/platform-client.js", () => ({
   readPlatformToken: readPlatformTokenMock,
   fetchOrganizationId: fetchOrganizationIdMock,
+  getPlatformUrl: getPlatformUrlMock,
+  hatchAssistant: hatchAssistantMock,
   platformInitiateExport: platformInitiateExportMock,
   platformPollExportStatus: platformPollExportStatusMock,
   platformDownloadExport: platformDownloadExportMock,
   platformImportPreflight: platformImportPreflightMock,
   platformImportBundle: platformImportBundleMock,
+  platformRequestUploadUrl: platformRequestUploadUrlMock,
+  platformUploadToSignedUrl: platformUploadToSignedUrlMock,
+  platformImportPreflightFromGcs: platformImportPreflightFromGcsMock,
+  platformImportBundleFromGcs: platformImportBundleFromGcsMock,
+}));
+
+const hatchLocalMock = mock(async () => {});
+
+mock.module("../lib/hatch-local.js", () => ({
+  hatchLocal: hatchLocalMock,
+}));
+
+const hatchDockerMock = mock(async () => {});
+const retireDockerMock = mock(async () => {});
+
+const sleepContainersMock = mock(async () => {});
+const dockerResourceNamesMock = mock((name: string) => ({
+  assistantContainer: `${name}-assistant`,
+  gatewayContainer: `${name}-gateway`,
+  cesContainer: `${name}-ces`,
+  network: `${name}-net`,
+}));
+
+mock.module("../lib/docker.js", () => ({
+  hatchDocker: hatchDockerMock,
+  retireDocker: retireDockerMock,
+  sleepContainers: sleepContainersMock,
+  dockerResourceNames: dockerResourceNamesMock,
+}));
+
+const stopProcessByPidFileMock = mock(async () => true);
+
+mock.module("../lib/process.js", () => ({
+  stopProcessByPidFile: stopProcessByPidFileMock,
+}));
+
+const retireLocalMock = mock(async () => {});
+
+mock.module("../lib/retire-local.js", () => ({
+  retireLocal: retireLocalMock,
 }));
 
-import { teleport } from "../commands/teleport.js";
+import {
+  teleport,
+  parseArgs,
+  resolveOrHatchTarget,
+} from "../commands/teleport.js";
 import type { AssistantEntry } from "../lib/assistant-config.js";
 
 // ---------------------------------------------------------------------------
@@ -106,6 +205,9 @@ import type { AssistantEntry } from "../lib/assistant-config.js";
 
 afterAll(() => {
   findAssistantByNameMock.mockRestore();
+  saveAssistantEntryMock.mockRestore();
+  loadAllAssistantsMock.mockRestore();
+  removeAssistantEntryMock.mockRestore();
   rmSync(testDir, { recursive: true, force: true });
   delete process.env.VELLUM_LOCKFILE_DIR;
 });
@@ -122,6 +224,12 @@ beforeEach(() => {
   // Reset all mocks
   findAssistantByNameMock.mockReset();
   findAssistantByNameMock.mockReturnValue(null);
+  saveAssistantEntryMock.mockReset();
+  saveAssistantEntryMock.mockImplementation(() => {});
+  loadAllAssistantsMock.mockReset();
+  loadAllAssistantsMock.mockReturnValue([]);
+  removeAssistantEntryMock.mockReset();
+  removeAssistantEntryMock.mockImplementation(() => {});
 
   loadGuardianTokenMock.mockReset();
   loadGuardianTokenMock.mockReturnValue({
@@ -134,6 +242,14 @@ beforeEach(() => {
   readPlatformTokenMock.mockReturnValue("platform-token");
   fetchOrganizationIdMock.mockReset();
   fetchOrganizationIdMock.mockResolvedValue("org-123");
+  getPlatformUrlMock.mockReset();
+  getPlatformUrlMock.mockReturnValue("https://platform.vellum.ai");
+  hatchAssistantMock.mockReset();
+  hatchAssistantMock.mockResolvedValue({
+    id: "platform-new-id",
+    name: "platform-new",
+    status: "active",
+  });
   platformInitiateExportMock.mockReset();
   platformInitiateExportMock.mockResolvedValue({
     jobId: "job-1",
@@ -175,6 +291,54 @@ beforeEach(() => {
       },
     },
   });
+  platformRequestUploadUrlMock.mockReset();
+  platformRequestUploadUrlMock.mockResolvedValue({
+    uploadUrl: "https://storage.googleapis.com/bucket/signed-upload-url",
+    bundleKey: "bundle-key-123",
+    expiresAt: new Date(Date.now() + 3600_000).toISOString(),
+  });
+  platformUploadToSignedUrlMock.mockReset();
+  platformUploadToSignedUrlMock.mockResolvedValue(undefined);
+  platformImportPreflightFromGcsMock.mockReset();
+  platformImportPreflightFromGcsMock.mockResolvedValue({
+    statusCode: 200,
+    body: {
+      can_import: true,
+      summary: {
+        files_to_create: 2,
+        files_to_overwrite: 1,
+        files_unchanged: 0,
+        total_files: 3,
+      },
+    },
+  });
+  platformImportBundleFromGcsMock.mockReset();
+  platformImportBundleFromGcsMock.mockResolvedValue({
+    statusCode: 200,
+    body: {
+      success: true,
+      summary: {
+        total_files: 3,
+        files_created: 2,
+        files_overwritten: 1,
+        files_skipped: 0,
+        backups_created: 1,
+      },
+    },
+  });
+
+  hatchLocalMock.mockReset();
+  hatchLocalMock.mockResolvedValue(undefined);
+  hatchDockerMock.mockReset();
+  hatchDockerMock.mockResolvedValue(undefined);
+  retireDockerMock.mockReset();
+  retireDockerMock.mockResolvedValue(undefined);
+  retireLocalMock.mockReset();
+  retireLocalMock.mockResolvedValue(undefined);
+  sleepContainersMock.mockReset();
+  sleepContainersMock.mockResolvedValue(undefined);
+  stopProcessByPidFileMock.mockReset();
+  stopProcessByPidFileMock.mockResolvedValue(true);
 
   // Mock process.exit to throw so we can catch it
   exitMock = mock((code?: number) => {
@@ -187,8 +351,6 @@ beforeEach(() => {
   consoleErrorSpy = spyOn(console, "error").mockImplementation(() => {});
 });
 
-import { afterEach } from "bun:test";
-
 afterEach(() => {
   process.argv = originalArgv;
   process.exit = originalExit;
@@ -213,24 +375,44 @@ function makeEntry(
   };
 }
 
-/** Extract the URL string from a fetch mock call argument. */
-function extractUrl(arg: unknown): string {
-  if (typeof arg === "string") return arg;
-  if (arg && typeof arg === "object" && "url" in arg) {
-    return (arg as { url: string }).url;
-  }
-  return String(arg);
-}
-
-/** Filter fetch mock calls by URL substring. */
-function filterFetchCalls(
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  fetchMock: { mock: { calls: any[][] } },
-  substring: string,
-): unknown[][] {
-  return fetchMock.mock.calls.filter((call: unknown[]) =>
-    extractUrl(call[0]).includes(substring),
-  );
+/** Create a mock fetch that handles export and import endpoints. */
+function createFetchMock() {
+  return mock(async (url: string | URL | Request) => {
+    const urlStr = typeof url === "string" ? url : url.toString();
+    if (urlStr.includes("/export")) {
+      return new Response(new Uint8Array([1, 2, 3]), { status: 200 });
+    }
+    if (urlStr.includes("/import-preflight")) {
+      return new Response(
+        JSON.stringify({
+          can_import: true,
+          summary: {
+            files_to_create: 1,
+            files_to_overwrite: 0,
+            files_unchanged: 0,
+            total_files: 1,
+          },
+        }),
+        { status: 200, headers: { "Content-Type": "application/json" } },
+      );
+    }
+    if (urlStr.includes("/import")) {
+      return new Response(
+        JSON.stringify({
+          success: true,
+          summary: {
+            total_files: 1,
+            files_created: 1,
+            files_overwritten: 0,
+            files_skipped: 0,
+            backups_created: 0,
+          },
+        }),
+        { status: 200, headers: { "Content-Type": "application/json" } },
+      );
+    }
+    return new Response("not found", { status: 404 });
+  });
 }
 
 // ---------------------------------------------------------------------------
@@ -254,7 +436,7 @@ describe("teleport arg parsing", () => {
     );
   });
 
-  test("missing --from and --to prints help and exits 1", async () => {
+  test("missing --from and env flag prints help and exits 1", async () => {
     setArgv();
     await expect(teleport()).rejects.toThrow("process.exit:1");
     expect(consoleLogSpy).toHaveBeenCalledWith(
@@ -262,7 +444,7 @@ describe("teleport arg parsing", () => {
     );
   });
 
-  test("missing --to prints help and exits 1", async () => {
+  test("missing env flag prints help and exits 1", async () => {
     setArgv("--from", "source");
     await expect(teleport()).rejects.toThrow("process.exit:1");
     expect(consoleLogSpy).toHaveBeenCalledWith(
@@ -270,126 +452,122 @@ describe("teleport arg parsing", () => {
     );
   });
 
-  test("missing --from prints help and exits 1", async () => {
-    setArgv("--to", "target");
-    await expect(teleport()).rejects.toThrow("process.exit:1");
-    expect(consoleLogSpy).toHaveBeenCalledWith(
-      expect.stringContaining("Usage:"),
+  test("--local sets targetEnv to 'local' with no name", () => {
+    const result = parseArgs(["--from", "source", "--local"]);
+    expect(result.from).toBe("source");
+    expect(result.targetEnv).toBe("local");
+    expect(result.targetName).toBeUndefined();
+  });
+
+  test("--docker my-name sets targetEnv to 'docker' and targetName to 'my-name'", () => {
+    const result = parseArgs(["--from", "source", "--docker", "my-name"]);
+    expect(result.from).toBe("source");
+    expect(result.targetEnv).toBe("docker");
+    expect(result.targetName).toBe("my-name");
+  });
+
+  test("--platform sets targetEnv to 'platform'", () => {
+    const result = parseArgs(["--from", "source", "--platform"]);
+    expect(result.from).toBe("source");
+    expect(result.targetEnv).toBe("platform");
+    expect(result.targetName).toBeUndefined();
+  });
+
+  test("multiple env flags error", () => {
+    expect(() => parseArgs(["--from", "src", "--local", "--docker"])).toThrow(
+      "process.exit:1",
+    );
+    expect(consoleErrorSpy).toHaveBeenCalledWith(
+      expect.stringContaining("Only one environment flag"),
     );
   });
 
-  test("--from and --to are correctly parsed", async () => {
-    setArgv("--from", "source", "--to", "target");
+  test("--keep-source is parsed", () => {
+    const result = parseArgs(["--from", "source", "--docker", "--keep-source"]);
+    expect(result.keepSource).toBe(true);
+  });
+
+  test("--dry-run is parsed", () => {
+    const result = parseArgs(["--from", "source", "--local", "--dry-run"]);
+    expect(result.dryRun).toBe(true);
+  });
+
+  test("target name after env flag is consumed but --flags are not", () => {
+    const result = parseArgs(["--from", "source", "--docker", "--keep-source"]);
+    expect(result.targetEnv).toBe("docker");
+    expect(result.targetName).toBeUndefined();
+    expect(result.keepSource).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Same-environment rejection tests
+// ---------------------------------------------------------------------------
+
+describe("same-environment rejection", () => {
+  test("source local, target local -> error (after resolving target)", async () => {
+    setArgv("--from", "src", "--local", "dst");
+
+    const srcEntry = makeEntry("src", { cloud: "local" });
+    const dstEntry = makeEntry("dst", { cloud: "local" });
 
     findAssistantByNameMock.mockImplementation((name: string) => {
-      if (name === "source") return makeEntry("source");
-      if (name === "target") return makeEntry("target");
+      if (name === "src") return srcEntry;
+      if (name === "dst") return dstEntry;
       return null;
     });
 
-    // This will attempt a fetch to the local export endpoint, which will fail.
-    // We just want to confirm parsing worked (i.e. it gets past the arg check).
-    // Mock global fetch to avoid network calls.
     const originalFetch = globalThis.fetch;
-    const fetchMock = mock(async (url: string | URL | Request) => {
-      const urlStr = typeof url === "string" ? url : url.toString();
-      if (urlStr.includes("/export")) {
-        return new Response(new Uint8Array([1, 2, 3]), { status: 200 });
-      }
-      // import endpoint — return valid JSON
-      return new Response(
-        JSON.stringify({
-          success: true,
-          summary: {
-            total_files: 1,
-            files_created: 1,
-            files_overwritten: 0,
-            files_skipped: 0,
-            backups_created: 0,
-          },
-        }),
-        { status: 200, headers: { "Content-Type": "application/json" } },
-      );
-    });
-    globalThis.fetch = fetchMock as unknown as typeof globalThis.fetch;
+    globalThis.fetch = createFetchMock() as unknown as typeof globalThis.fetch;
 
     try {
-      await teleport();
-      // Should call findAssistantByName for both source and target
-      expect(findAssistantByNameMock).toHaveBeenCalledWith("source");
-      expect(findAssistantByNameMock).toHaveBeenCalledWith("target");
+      await expect(teleport()).rejects.toThrow("process.exit:1");
+      expect(consoleErrorSpy).toHaveBeenCalledWith(
+        expect.stringContaining("Cannot teleport between two local assistants"),
+      );
     } finally {
       globalThis.fetch = originalFetch;
     }
   });
 
-  test("--dry-run flag is detected", async () => {
-    setArgv("--from", "source", "--to", "target", "--dry-run");
+  test("source docker, target docker -> error (after resolving target)", async () => {
+    setArgv("--from", "src", "--docker", "dst");
+
+    const srcEntry = makeEntry("src", { cloud: "docker" });
+    const dstEntry = makeEntry("dst", { cloud: "docker" });
 
     findAssistantByNameMock.mockImplementation((name: string) => {
-      if (name === "source") return makeEntry("source");
-      if (name === "target") return makeEntry("target");
+      if (name === "src") return srcEntry;
+      if (name === "dst") return dstEntry;
       return null;
     });
 
     const originalFetch = globalThis.fetch;
-    const fetchMock = mock(async (url: string | URL | Request) => {
-      const urlStr = typeof url === "string" ? url : url.toString();
-      if (urlStr.includes("/export")) {
-        return new Response(new Uint8Array([1, 2, 3]), { status: 200 });
-      }
-      if (urlStr.includes("/import-preflight")) {
-        return new Response(
-          JSON.stringify({
-            can_import: true,
-            summary: {
-              files_to_create: 1,
-              files_to_overwrite: 0,
-              files_unchanged: 0,
-              total_files: 1,
-            },
-          }),
-          { status: 200, headers: { "Content-Type": "application/json" } },
-        );
-      }
-      return new Response("not found", { status: 404 });
-    });
-    globalThis.fetch = fetchMock as unknown as typeof globalThis.fetch;
+    globalThis.fetch = createFetchMock() as unknown as typeof globalThis.fetch;
 
     try {
-      await teleport();
-      // In dry-run mode for local target, it should call the preflight endpoint
-      const preflightCalls = filterFetchCalls(fetchMock, "import-preflight");
-      expect(preflightCalls.length).toBe(1);
+      await expect(teleport()).rejects.toThrow("process.exit:1");
+      expect(consoleErrorSpy).toHaveBeenCalledWith(
+        expect.stringContaining(
+          "Cannot teleport between two docker assistants",
+        ),
+      );
     } finally {
       globalThis.fetch = originalFetch;
     }
   });
 
-  test("unknown assistant name causes exit with error", async () => {
-    setArgv("--from", "nonexistent", "--to", "target");
-    findAssistantByNameMock.mockReturnValue(null);
-
-    await expect(teleport()).rejects.toThrow("process.exit:1");
-    expect(consoleErrorSpy).toHaveBeenCalledWith(
-      expect.stringContaining("not found in lockfile"),
-    );
-  });
-});
-
-// ---------------------------------------------------------------------------
-// Cloud resolution tests
-// ---------------------------------------------------------------------------
-
-describe("teleport cloud resolution", () => {
-  test("entry with cloud: 'vellum' resolves to vellum", async () => {
-    setArgv("--from", "src", "--to", "dst");
+  test("source vellum, target platform -> error (after resolving target)", async () => {
+    setArgv("--from", "src", "--platform", "dst");
 
     const srcEntry = makeEntry("src", {
       cloud: "vellum",
       runtimeUrl: "https://platform.vellum.ai",
     });
-    const dstEntry = makeEntry("dst", { cloud: "local" });
+    const dstEntry = makeEntry("dst", {
+      cloud: "vellum",
+      runtimeUrl: "https://platform.vellum.ai",
+    });
 
     findAssistantByNameMock.mockImplementation((name: string) => {
       if (name === "src") return srcEntry;
@@ -397,397 +575,704 @@ describe("teleport cloud resolution", () => {
       return null;
     });
 
-    // Platform export path: readPlatformToken → fetchOrganizationId → initiateExport → poll → download
-    // then local import
     const originalFetch = globalThis.fetch;
-    const fetchMock = mock(async () => {
-      return new Response(
-        JSON.stringify({
-          success: true,
-          summary: {
-            total_files: 1,
-            files_created: 1,
-            files_overwritten: 0,
-            files_skipped: 0,
-            backups_created: 0,
-          },
-        }),
-        { status: 200, headers: { "Content-Type": "application/json" } },
-      );
-    });
-    globalThis.fetch = fetchMock as unknown as typeof globalThis.fetch;
+    globalThis.fetch = createFetchMock() as unknown as typeof globalThis.fetch;
 
     try {
-      await teleport();
-      // Should have used platform export functions
-      expect(platformInitiateExportMock).toHaveBeenCalled();
-      expect(platformPollExportStatusMock).toHaveBeenCalled();
-      expect(platformDownloadExportMock).toHaveBeenCalled();
+      await expect(teleport()).rejects.toThrow("process.exit:1");
+      expect(consoleErrorSpy).toHaveBeenCalledWith(
+        expect.stringContaining(
+          "Cannot teleport between two platform assistants",
+        ),
+      );
     } finally {
       globalThis.fetch = originalFetch;
     }
   });
 
-  test("entry with cloud: 'local' resolves to local", async () => {
-    setArgv("--from", "src", "--to", "dst");
-
-    const srcEntry = makeEntry("src", { cloud: "local" });
-    const dstEntry = makeEntry("dst", {
-      cloud: "vellum",
-      runtimeUrl: "https://platform.vellum.ai",
-    });
+  test("same-env rejection happens before hatching (no orphaned assistants)", async () => {
+    setArgv("--from", "my-local", "--local");
 
+    const localEntry = makeEntry("my-local", { cloud: "local" });
     findAssistantByNameMock.mockImplementation((name: string) => {
-      if (name === "src") return srcEntry;
-      if (name === "dst") return dstEntry;
+      if (name === "my-local") return localEntry;
       return null;
     });
 
-    const originalFetch = globalThis.fetch;
-    const fetchMock = mock(async () => {
-      return new Response(new Uint8Array([1, 2, 3]), { status: 200 });
+    await expect(teleport()).rejects.toThrow("process.exit:1");
+    expect(consoleErrorSpy).toHaveBeenCalledWith(
+      expect.stringContaining("Cannot teleport between two local assistants"),
+    );
+    // Crucially: no hatch should have been called — the early guard fires first
+    expect(hatchLocalMock).not.toHaveBeenCalled();
+    expect(hatchDockerMock).not.toHaveBeenCalled();
+    expect(hatchAssistantMock).not.toHaveBeenCalled();
+  });
+
+  test("same-env rejection before hatching for docker", async () => {
+    setArgv("--from", "my-docker", "--docker");
+
+    const dockerEntry = makeEntry("my-docker", { cloud: "docker" });
+    findAssistantByNameMock.mockImplementation((name: string) => {
+      if (name === "my-docker") return dockerEntry;
+      return null;
     });
-    globalThis.fetch = fetchMock as unknown as typeof globalThis.fetch;
 
-    try {
-      await teleport();
-      // Local export uses fetch to /v1/migrations/export
-      const exportCalls = filterFetchCalls(fetchMock, "/v1/migrations/export");
-      expect(exportCalls.length).toBe(1);
-      // Platform import should be called
-      expect(platformImportBundleMock).toHaveBeenCalled();
-    } finally {
-      globalThis.fetch = originalFetch;
-    }
+    await expect(teleport()).rejects.toThrow("process.exit:1");
+    expect(consoleErrorSpy).toHaveBeenCalledWith(
+      expect.stringContaining("Cannot teleport between two docker assistants"),
+    );
+    expect(hatchLocalMock).not.toHaveBeenCalled();
+    expect(hatchDockerMock).not.toHaveBeenCalled();
+    expect(hatchAssistantMock).not.toHaveBeenCalled();
   });
 
-  test("entry with no cloud but project set resolves to gcp (unsupported)", async () => {
-    setArgv("--from", "src", "--to", "dst");
+  test("same-env rejection before hatching for platform (vellum cloud)", async () => {
+    setArgv("--from", "my-cloud", "--platform");
 
-    // cloud is empty string or undefined — resolveCloud checks entry.project
-    const srcEntry = makeEntry("src", {
-      cloud: "" as string,
-      project: "my-gcp-project",
+    const platformEntry = makeEntry("my-cloud", {
+      cloud: "vellum",
+      runtimeUrl: "https://platform.vellum.ai",
     });
-    const dstEntry = makeEntry("dst", { cloud: "local" });
-
     findAssistantByNameMock.mockImplementation((name: string) => {
-      if (name === "src") return srcEntry;
-      if (name === "dst") return dstEntry;
+      if (name === "my-cloud") return platformEntry;
       return null;
     });
 
-    // GCP is unsupported, should print error and exit
     await expect(teleport()).rejects.toThrow("process.exit:1");
     expect(consoleErrorSpy).toHaveBeenCalledWith(
-      expect.stringContaining("only supports local and platform"),
+      expect.stringContaining(
+        "Cannot teleport between two platform assistants",
+      ),
     );
+    expect(hatchLocalMock).not.toHaveBeenCalled();
+    expect(hatchDockerMock).not.toHaveBeenCalled();
+    expect(hatchAssistantMock).not.toHaveBeenCalled();
   });
 
-  test("entry with no cloud and no project resolves to local", async () => {
-    setArgv("--from", "src", "--to", "dst");
+  test("flag says docker but resolved target is local -> rejects cloud mismatch", async () => {
+    // User passes --docker but the named target is actually a local assistant
+    setArgv("--from", "src", "--docker", "misidentified");
 
-    // cloud is falsy, no project — resolveCloud returns "local"
-    const srcEntry = makeEntry("src", { cloud: "" as string });
-    const dstEntry = makeEntry("dst", { cloud: "local" });
+    const srcEntry = makeEntry("src", { cloud: "vellum" });
+    // Target is actually local despite the --docker flag
+    const dstEntry = makeEntry("misidentified", { cloud: "local" });
 
     findAssistantByNameMock.mockImplementation((name: string) => {
       if (name === "src") return srcEntry;
-      if (name === "dst") return dstEntry;
+      if (name === "misidentified") return dstEntry;
       return null;
     });
 
-    const originalFetch = globalThis.fetch;
-    const fetchMock = mock(async (url: string | URL | Request) => {
-      const urlStr = typeof url === "string" ? url : url.toString();
-      if (urlStr.includes("/export")) {
-        return new Response(new Uint8Array([1, 2, 3]), { status: 200 });
-      }
-      // import endpoint
-      return new Response(
-        JSON.stringify({
-          success: true,
-          summary: {
-            total_files: 1,
-            files_created: 1,
-            files_overwritten: 0,
-            files_skipped: 0,
-            backups_created: 0,
-          },
-        }),
-        { status: 200, headers: { "Content-Type": "application/json" } },
-      );
-    });
-    globalThis.fetch = fetchMock as unknown as typeof globalThis.fetch;
-
-    try {
-      await teleport();
-      // Should use local export (fetch to /v1/migrations/export)
-      const exportCalls = filterFetchCalls(fetchMock, "/v1/migrations/export");
-      expect(exportCalls.length).toBe(1);
-    } finally {
-      globalThis.fetch = originalFetch;
-    }
+    await expect(teleport()).rejects.toThrow("process.exit:1");
+    expect(consoleErrorSpy).toHaveBeenCalledWith(
+      expect.stringContaining("is a local assistant, not docker"),
+    );
   });
 });
 
 // ---------------------------------------------------------------------------
-// Transfer routing tests
+// resolveOrHatchTarget tests
 // ---------------------------------------------------------------------------
 
-describe("teleport transfer routing", () => {
-  test("local → platform calls local export endpoint and platform import", async () => {
-    setArgv("--from", "local-src", "--to", "platform-dst");
-
+describe("resolveOrHatchTarget", () => {
+  test("existing assistant is returned without hatching", async () => {
+    const dockerEntry = makeEntry("my-docker", { cloud: "docker" });
     findAssistantByNameMock.mockImplementation((name: string) => {
-      if (name === "local-src")
-        return makeEntry("local-src", { cloud: "local" });
-      if (name === "platform-dst")
-        return makeEntry("platform-dst", {
-          cloud: "vellum",
-          runtimeUrl: "https://platform.vellum.ai",
-        });
+      if (name === "my-docker") return dockerEntry;
       return null;
     });
 
-    const originalFetch = globalThis.fetch;
-    const fetchMock = mock(async () => {
-      return new Response(new Uint8Array([1, 2, 3]), { status: 200 });
-    });
-    globalThis.fetch = fetchMock as unknown as typeof globalThis.fetch;
+    const result = await resolveOrHatchTarget("docker", "my-docker");
+    expect(result).toBe(dockerEntry);
+    expect(hatchDockerMock).not.toHaveBeenCalled();
+    expect(consoleLogSpy).toHaveBeenCalledWith(
+      expect.stringContaining("Target: my-docker (docker)"),
+    );
+  });
+
+  test("name not found -> hatch docker", async () => {
+    const newEntry = makeEntry("new-one", { cloud: "docker" });
+    findAssistantByNameMock.mockImplementation((name: string) => {
+      // First call: lookup by name -> not found
+      // Second call: after hatch -> found
+      if (name === "new-one" && hatchDockerMock.mock.calls.length > 0) {
+        return newEntry;
+      }
+      return null;
+    });
+
+    const result = await resolveOrHatchTarget("docker", "new-one");
+    expect(hatchDockerMock).toHaveBeenCalledWith(
+      "vellum",
+      false,
+      "new-one",
+      false,
+      {},
+    );
+    expect(result).toBe(newEntry);
+  });
+
+  test("no name -> hatch local with null name, discovers via diff", async () => {
+    const existingEntry = makeEntry("existing-local", { cloud: "local" });
+    const newEntry = makeEntry("auto-generated", { cloud: "local" });
+
+    // Before hatch: only the existing entry
+    // After hatch: existing + new entry
+    loadAllAssistantsMock.mockImplementation(() => {
+      if (hatchLocalMock.mock.calls.length > 0) {
+        return [existingEntry, newEntry];
+      }
+      return [existingEntry];
+    });
+
+    const result = await resolveOrHatchTarget("local");
+    expect(hatchLocalMock).toHaveBeenCalledWith(
+      "vellum",
+      null,
+      false,
+      false,
+      false,
+      {},
+    );
+    expect(result).toBe(newEntry);
+  });
+
+  test("platform with existing ID -> returns existing without hatching", async () => {
+    const platformEntry = makeEntry("uuid-123", {
+      cloud: "vellum",
+      runtimeUrl: "https://platform.vellum.ai",
+    });
+    findAssistantByNameMock.mockImplementation((name: string) => {
+      if (name === "uuid-123") return platformEntry;
+      return null;
+    });
+
+    const result = await resolveOrHatchTarget("platform", "uuid-123");
+    expect(result).toBe(platformEntry);
+    expect(hatchAssistantMock).not.toHaveBeenCalled();
+  });
+
+  test("platform with unknown name -> hatches via hatchAssistant", async () => {
+    findAssistantByNameMock.mockReturnValue(null);
+
+    const result = await resolveOrHatchTarget("platform", "nonexistent");
+    expect(hatchAssistantMock).toHaveBeenCalledWith(
+      "platform-token",
+      "org-123",
+    );
+    expect(saveAssistantEntryMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        assistantId: "platform-new-id",
+        cloud: "vellum",
+      }),
+    );
+    expect(result.assistantId).toBe("platform-new-id");
+  });
+
+  test("existing assistant with wrong cloud -> rejects", async () => {
+    const localEntry = makeEntry("my-local", { cloud: "local" });
+    findAssistantByNameMock.mockImplementation((name: string) => {
+      if (name === "my-local") return localEntry;
+      return null;
+    });
+
+    await expect(resolveOrHatchTarget("docker", "my-local")).rejects.toThrow(
+      "process.exit:1",
+    );
+    expect(consoleErrorSpy).toHaveBeenCalledWith(
+      expect.stringContaining("is a local assistant, not docker"),
+    );
+  });
+
+  test("name with path traversal -> rejects before hatching", async () => {
+    findAssistantByNameMock.mockReturnValue(null);
+
+    await expect(
+      resolveOrHatchTarget("docker", "../../../etc/passwd"),
+    ).rejects.toThrow("process.exit:1");
+    expect(consoleErrorSpy).toHaveBeenCalledWith(
+      expect.stringContaining("invalid characters"),
+    );
+    expect(hatchDockerMock).not.toHaveBeenCalled();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Auto-retire tests
+// ---------------------------------------------------------------------------
+
+describe("auto-retire", () => {
+  test("local -> docker: stops source before hatch, retires after import", async () => {
+    setArgv("--from", "my-local", "--docker");
+
+    const localEntry = makeEntry("my-local", {
+      cloud: "local",
+      resources: {
+        instanceDir: "/home/test",
+        pidFile: "/home/test/.vellum/assistant.pid",
+        signingKey: "key",
+        daemonPort: 7821,
+        gatewayPort: 7830,
+        qdrantPort: 6333,
+        cesPort: 8090,
+      },
+    });
+    const dockerEntry = makeEntry("new-docker", { cloud: "docker" });
+
+    findAssistantByNameMock.mockImplementation((name: string) => {
+      if (name === "my-local") return localEntry;
+      return null;
+    });
+
+    // Simulate hatch creating a new docker entry
+    loadAllAssistantsMock.mockImplementation(() => {
+      if (hatchDockerMock.mock.calls.length > 0) {
+        return [localEntry, dockerEntry];
+      }
+      return [localEntry];
+    });
+
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = createFetchMock() as unknown as typeof globalThis.fetch;
 
     try {
       await teleport();
+      // Source should be stopped (slept) before hatch
+      expect(stopProcessByPidFileMock).toHaveBeenCalled();
+      // Retire happens after successful import
+      expect(retireLocalMock).toHaveBeenCalledWith("my-local", localEntry);
+      expect(removeAssistantEntryMock).toHaveBeenCalledWith("my-local");
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
 
-      // Local export: should call fetch to /v1/migrations/export
-      const exportCalls = filterFetchCalls(fetchMock, "/v1/migrations/export");
-      expect(exportCalls.length).toBe(1);
+  test("docker -> local: sleeps containers before hatch, retires after import", async () => {
+    setArgv("--from", "my-docker", "--local");
 
-      // Platform import: should call platformImportBundle
-      expect(platformImportBundleMock).toHaveBeenCalled();
+    const dockerEntry = makeEntry("my-docker", { cloud: "docker" });
+    const localEntry = makeEntry("new-local", { cloud: "local" });
+
+    findAssistantByNameMock.mockImplementation((name: string) => {
+      if (name === "my-docker") return dockerEntry;
+      return null;
+    });
+
+    loadAllAssistantsMock.mockImplementation(() => {
+      if (hatchLocalMock.mock.calls.length > 0) {
+        return [dockerEntry, localEntry];
+      }
+      return [dockerEntry];
+    });
 
-      // Should NOT call platform export functions
-      expect(platformInitiateExportMock).not.toHaveBeenCalled();
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = createFetchMock() as unknown as typeof globalThis.fetch;
+
+    try {
+      await teleport();
+      // Docker source should be slept (containers stopped) before hatch
+      expect(sleepContainersMock).toHaveBeenCalled();
+      // Retire happens after successful import
+      expect(retireDockerMock).toHaveBeenCalledWith("my-docker");
+      expect(removeAssistantEntryMock).toHaveBeenCalledWith("my-docker");
     } finally {
       globalThis.fetch = originalFetch;
     }
   });
 
-  test("platform → local calls platform export functions and local import endpoint", async () => {
-    setArgv("--from", "platform-src", "--to", "local-dst");
+  test("--keep-source skips retire and removeAssistantEntry", async () => {
+    setArgv("--from", "my-local", "--docker", "--keep-source");
+
+    const localEntry = makeEntry("my-local", { cloud: "local" });
+    const dockerEntry = makeEntry("new-docker", { cloud: "docker" });
 
     findAssistantByNameMock.mockImplementation((name: string) => {
-      if (name === "platform-src")
-        return makeEntry("platform-src", {
-          cloud: "vellum",
-          runtimeUrl: "https://platform.vellum.ai",
-        });
-      if (name === "local-dst")
-        return makeEntry("local-dst", { cloud: "local" });
+      if (name === "my-local") return localEntry;
       return null;
     });
 
+    loadAllAssistantsMock.mockImplementation(() => {
+      if (hatchDockerMock.mock.calls.length > 0) {
+        return [localEntry, dockerEntry];
+      }
+      return [localEntry];
+    });
+
     const originalFetch = globalThis.fetch;
-    const fetchMock = mock(async () => {
-      return new Response(
-        JSON.stringify({
-          success: true,
-          summary: {
-            total_files: 3,
-            files_created: 2,
-            files_overwritten: 1,
-            files_skipped: 0,
-            backups_created: 1,
-          },
-        }),
-        { status: 200, headers: { "Content-Type": "application/json" } },
+    globalThis.fetch = createFetchMock() as unknown as typeof globalThis.fetch;
+
+    try {
+      await teleport();
+      expect(retireLocalMock).not.toHaveBeenCalled();
+      expect(retireDockerMock).not.toHaveBeenCalled();
+      expect(removeAssistantEntryMock).not.toHaveBeenCalled();
+      expect(consoleLogSpy).toHaveBeenCalledWith(
+        expect.stringContaining("kept (--keep-source)"),
       );
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+
+  test("platform transfers skip retire", async () => {
+    setArgv("--from", "my-local", "--platform");
+
+    const localEntry = makeEntry("my-local", { cloud: "local" });
+
+    findAssistantByNameMock.mockImplementation((name: string) => {
+      if (name === "my-local") return localEntry;
+      return null;
     });
-    globalThis.fetch = fetchMock as unknown as typeof globalThis.fetch;
+
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = createFetchMock() as unknown as typeof globalThis.fetch;
 
     try {
       await teleport();
+      expect(retireLocalMock).not.toHaveBeenCalled();
+      expect(retireDockerMock).not.toHaveBeenCalled();
+      expect(removeAssistantEntryMock).not.toHaveBeenCalled();
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
 
-      // Platform export: should call all three platform export functions
-      expect(platformInitiateExportMock).toHaveBeenCalled();
-      expect(platformPollExportStatusMock).toHaveBeenCalled();
-      expect(platformDownloadExportMock).toHaveBeenCalled();
+  test("dry-run without existing target does not hatch or export", async () => {
+    setArgv("--from", "my-local", "--docker", "--dry-run");
 
-      // Local import: should call fetch to /v1/migrations/import (but not /import-preflight)
-      const importCalls = filterFetchCalls(
-        fetchMock,
-        "/v1/migrations/import",
-      ).filter((call) => !extractUrl(call[0]).includes("/import-preflight"));
-      expect(importCalls.length).toBe(1);
+    const localEntry = makeEntry("my-local", { cloud: "local" });
 
-      // Should NOT call platformImportBundle
-      expect(platformImportBundleMock).not.toHaveBeenCalled();
+    findAssistantByNameMock.mockImplementation((name: string) => {
+      if (name === "my-local") return localEntry;
+      return null;
+    });
+
+    await teleport();
+
+    // Should NOT hatch, export, import, or retire
+    expect(hatchDockerMock).not.toHaveBeenCalled();
+    expect(hatchLocalMock).not.toHaveBeenCalled();
+    expect(hatchAssistantMock).not.toHaveBeenCalled();
+    expect(retireLocalMock).not.toHaveBeenCalled();
+    expect(retireDockerMock).not.toHaveBeenCalled();
+    expect(removeAssistantEntryMock).not.toHaveBeenCalled();
+  });
+
+  test("dry-run with existing target runs preflight without hatching", async () => {
+    setArgv("--from", "my-local", "--docker", "my-docker", "--dry-run");
+
+    const localEntry = makeEntry("my-local", { cloud: "local" });
+    const dockerEntry = makeEntry("my-docker", { cloud: "docker" });
+
+    findAssistantByNameMock.mockImplementation((name: string) => {
+      if (name === "my-local") return localEntry;
+      if (name === "my-docker") return dockerEntry;
+      return null;
+    });
+
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = createFetchMock() as unknown as typeof globalThis.fetch;
+
+    try {
+      await teleport();
+
+      // Should NOT hatch or retire
+      expect(hatchDockerMock).not.toHaveBeenCalled();
+      expect(hatchLocalMock).not.toHaveBeenCalled();
+      expect(retireLocalMock).not.toHaveBeenCalled();
+      expect(retireDockerMock).not.toHaveBeenCalled();
+      expect(removeAssistantEntryMock).not.toHaveBeenCalled();
     } finally {
       globalThis.fetch = originalFetch;
     }
   });
+});
+
+// ---------------------------------------------------------------------------
+// Full flow tests
+// ---------------------------------------------------------------------------
+
+describe("teleport full flow", () => {
+  test("hatch and import: --from my-local --docker", async () => {
+    setArgv("--from", "my-local", "--docker");
 
-  test("--dry-run calls preflight instead of import (local target)", async () => {
-    setArgv("--from", "src", "--to", "dst", "--dry-run");
+    const localEntry = makeEntry("my-local", { cloud: "local" });
+    const dockerEntry = makeEntry("new-docker", { cloud: "docker" });
 
     findAssistantByNameMock.mockImplementation((name: string) => {
-      if (name === "src") return makeEntry("src", { cloud: "local" });
-      if (name === "dst") return makeEntry("dst", { cloud: "local" });
+      if (name === "my-local") return localEntry;
       return null;
     });
 
-    const originalFetch = globalThis.fetch;
-    const fetchMock = mock(async (url: string | URL | Request) => {
-      const urlStr = typeof url === "string" ? url : url.toString();
-      if (urlStr.includes("/export")) {
-        return new Response(new Uint8Array([1, 2, 3]), { status: 200 });
+    loadAllAssistantsMock.mockImplementation(() => {
+      if (hatchDockerMock.mock.calls.length > 0) {
+        return [localEntry, dockerEntry];
       }
-      if (urlStr.includes("/import-preflight")) {
-        return new Response(
-          JSON.stringify({
-            can_import: true,
-            summary: {
-              files_to_create: 1,
-              files_to_overwrite: 0,
-              files_unchanged: 0,
-              total_files: 1,
-            },
-          }),
-          { status: 200, headers: { "Content-Type": "application/json" } },
-        );
-      }
-      return new Response("not found", { status: 404 });
+      return [localEntry];
     });
+
+    const originalFetch = globalThis.fetch;
+    const fetchMock = createFetchMock();
     globalThis.fetch = fetchMock as unknown as typeof globalThis.fetch;
 
     try {
       await teleport();
 
-      // Should call preflight endpoint
-      const preflightCalls = filterFetchCalls(fetchMock, "import-preflight");
-      expect(preflightCalls.length).toBe(1);
-
-      // Should NOT call the actual import endpoint
-      const importCalls = filterFetchCalls(fetchMock, "/import").filter(
-        (call) => !extractUrl(call[0]).includes("preflight"),
+      // Verify sequence: export, hatch, import, retire
+      expect(hatchDockerMock).toHaveBeenCalled();
+      expect(retireLocalMock).toHaveBeenCalledWith("my-local", localEntry);
+      expect(removeAssistantEntryMock).toHaveBeenCalledWith("my-local");
+      expect(consoleLogSpy).toHaveBeenCalledWith(
+        expect.stringContaining("Teleport complete"),
       );
-      expect(importCalls.length).toBe(0);
     } finally {
       globalThis.fetch = originalFetch;
     }
   });
 
-  test("--dry-run calls platformImportPreflight instead of platformImportBundle (platform target)", async () => {
-    setArgv("--from", "src", "--to", "dst", "--dry-run");
+  test("existing target overwrite: --from my-local --docker my-existing", async () => {
+    setArgv("--from", "my-local", "--docker", "my-existing");
+
+    const localEntry = makeEntry("my-local", { cloud: "local" });
+    const dockerEntry = makeEntry("my-existing", { cloud: "docker" });
 
     findAssistantByNameMock.mockImplementation((name: string) => {
-      if (name === "src") return makeEntry("src", { cloud: "local" });
-      if (name === "dst")
-        return makeEntry("dst", {
-          cloud: "vellum",
-          runtimeUrl: "https://platform.vellum.ai",
-        });
+      if (name === "my-local") return localEntry;
+      if (name === "my-existing") return dockerEntry;
       return null;
     });
 
     const originalFetch = globalThis.fetch;
-    const fetchMock = mock(async () => {
-      return new Response(new Uint8Array([1, 2, 3]), { status: 200 });
-    });
+    const fetchMock = createFetchMock();
     globalThis.fetch = fetchMock as unknown as typeof globalThis.fetch;
 
     try {
       await teleport();
 
-      // Should call platformImportPreflight
-      expect(platformImportPreflightMock).toHaveBeenCalled();
-
-      // Should NOT call platformImportBundle
-      expect(platformImportBundleMock).not.toHaveBeenCalled();
+      // No hatch should happen — existing target is used
+      expect(hatchDockerMock).not.toHaveBeenCalled();
+      // Source should still be retired
+      expect(retireLocalMock).toHaveBeenCalledWith("my-local", localEntry);
+      expect(consoleLogSpy).toHaveBeenCalledWith(
+        expect.stringContaining("Teleport complete"),
+      );
     } finally {
       globalThis.fetch = originalFetch;
     }
   });
 
-  test("platform → platform calls platform export and platform import", async () => {
-    setArgv("--from", "platform-src", "--to", "platform-dst");
+  test("legacy --to flag shows deprecation message", async () => {
+    setArgv("--from", "source", "--to", "target");
+
+    await expect(teleport()).rejects.toThrow("process.exit:1");
+    expect(consoleErrorSpy).toHaveBeenCalledWith(
+      expect.stringContaining("--to is deprecated"),
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Signed-URL upload tests
+// ---------------------------------------------------------------------------
+
+describe("signed-URL upload flow", () => {
+  test("happy path: signed URL upload succeeds → GCS-based import used", async () => {
+    setArgv("--from", "my-local", "--platform");
+
+    const localEntry = makeEntry("my-local", { cloud: "local" });
 
     findAssistantByNameMock.mockImplementation((name: string) => {
-      if (name === "platform-src")
-        return makeEntry("platform-src", {
-          cloud: "vellum",
-          runtimeUrl: "https://platform.vellum.ai",
-        });
-      if (name === "platform-dst")
-        return makeEntry("platform-dst", {
-          cloud: "vellum",
-          runtimeUrl: "https://platform2.vellum.ai",
-        });
+      if (name === "my-local") return localEntry;
       return null;
     });
 
-    await teleport();
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = createFetchMock() as unknown as typeof globalThis.fetch;
 
-    // Platform export: should call all three platform export functions
-    expect(platformInitiateExportMock).toHaveBeenCalled();
-    expect(platformPollExportStatusMock).toHaveBeenCalled();
-    expect(platformDownloadExportMock).toHaveBeenCalled();
+    try {
+      await teleport();
 
-    // Platform import: should call platformImportBundle
-    expect(platformImportBundleMock).toHaveBeenCalled();
+      // Signed-URL flow should be used
+      expect(platformRequestUploadUrlMock).toHaveBeenCalled();
+      expect(platformUploadToSignedUrlMock).toHaveBeenCalled();
+      expect(platformImportBundleFromGcsMock).toHaveBeenCalledWith(
+        "bundle-key-123",
+        "platform-token",
+        "org-123",
+        "https://platform.vellum.ai",
+      );
+      // Inline import should NOT be called
+      expect(platformImportBundleMock).not.toHaveBeenCalled();
+      expect(consoleLogSpy).toHaveBeenCalledWith(
+        expect.stringContaining("Teleport complete"),
+      );
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
   });
-});
 
-// ---------------------------------------------------------------------------
-// Edge case: extra/unrecognized arguments
-// ---------------------------------------------------------------------------
-
-describe("teleport extra arguments", () => {
-  test("extra unrecognized flags are ignored and command works normally", async () => {
+  test("happy path dry-run: signed URL upload succeeds → GCS-based preflight used", async () => {
     setArgv(
       "--from",
-      "src",
-      "--to",
-      "dst",
-      "--bogus-flag",
-      "--another-unknown",
+      "my-local",
+      "--platform",
+      "existing-platform",
+      "--dry-run",
     );
 
+    const localEntry = makeEntry("my-local", { cloud: "local" });
+    const platformEntry = makeEntry("existing-platform", {
+      cloud: "vellum",
+      runtimeUrl: "https://platform.vellum.ai",
+    });
+
     findAssistantByNameMock.mockImplementation((name: string) => {
-      if (name === "src") return makeEntry("src", { cloud: "local" });
-      if (name === "dst") return makeEntry("dst", { cloud: "local" });
+      if (name === "my-local") return localEntry;
+      if (name === "existing-platform") return platformEntry;
       return null;
     });
 
     const originalFetch = globalThis.fetch;
-    const fetchMock = mock(async (url: string | URL | Request) => {
-      const urlStr = typeof url === "string" ? url : url.toString();
-      if (urlStr.includes("/export")) {
-        return new Response(new Uint8Array([1, 2, 3]), { status: 200 });
-      }
-      return new Response(
-        JSON.stringify({
-          success: true,
-          summary: {
-            total_files: 1,
-            files_created: 1,
-            files_overwritten: 0,
-            files_skipped: 0,
-            backups_created: 0,
-          },
-        }),
-        { status: 200, headers: { "Content-Type": "application/json" } },
+    globalThis.fetch = createFetchMock() as unknown as typeof globalThis.fetch;
+
+    try {
+      await teleport();
+
+      // Signed-URL flow should be used for preflight
+      expect(platformRequestUploadUrlMock).toHaveBeenCalled();
+      expect(platformUploadToSignedUrlMock).toHaveBeenCalled();
+      expect(platformImportPreflightFromGcsMock).toHaveBeenCalledWith(
+        "bundle-key-123",
+        "platform-token",
+        "org-123",
+        "https://platform.vellum.ai",
       );
+      // Inline preflight should NOT be called
+      expect(platformImportPreflightMock).not.toHaveBeenCalled();
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+
+  test("fallback: platformRequestUploadUrl throws 503 → falls back to inline import", async () => {
+    setArgv("--from", "my-local", "--platform");
+
+    const localEntry = makeEntry("my-local", { cloud: "local" });
+
+    findAssistantByNameMock.mockImplementation((name: string) => {
+      if (name === "my-local") return localEntry;
+      return null;
     });
-    globalThis.fetch = fetchMock as unknown as typeof globalThis.fetch;
+
+    // Simulate 503 — "not available" in the error message
+    platformRequestUploadUrlMock.mockRejectedValue(
+      new Error("Signed uploads are not available on this platform instance"),
+    );
+
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = createFetchMock() as unknown as typeof globalThis.fetch;
+
+    try {
+      await teleport();
+
+      // Should fall back to inline import
+      expect(platformRequestUploadUrlMock).toHaveBeenCalled();
+      expect(platformUploadToSignedUrlMock).not.toHaveBeenCalled();
+      expect(platformImportBundleFromGcsMock).not.toHaveBeenCalled();
+      expect(platformImportBundleMock).toHaveBeenCalled();
+      expect(consoleLogSpy).toHaveBeenCalledWith(
+        expect.stringContaining("Teleport complete"),
+      );
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+
+  test("fallback: platformRequestUploadUrl throws 404 → falls back to inline import", async () => {
+    setArgv("--from", "my-local", "--platform");
+
+    const localEntry = makeEntry("my-local", { cloud: "local" });
+
+    findAssistantByNameMock.mockImplementation((name: string) => {
+      if (name === "my-local") return localEntry;
+      return null;
+    });
+
+    // Simulate 404 — endpoint doesn't exist on older platform versions
+    platformRequestUploadUrlMock.mockRejectedValue(
+      new Error("Signed uploads are not available on this platform instance"),
+    );
+
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = createFetchMock() as unknown as typeof globalThis.fetch;
 
     try {
       await teleport();
-      // Should have proceeded normally despite extra flags
-      expect(findAssistantByNameMock).toHaveBeenCalledWith("src");
-      expect(findAssistantByNameMock).toHaveBeenCalledWith("dst");
-      const exportCalls = filterFetchCalls(fetchMock, "/v1/migrations/export");
-      expect(exportCalls.length).toBe(1);
+
+      // Should fall back to inline import
+      expect(platformRequestUploadUrlMock).toHaveBeenCalled();
+      expect(platformUploadToSignedUrlMock).not.toHaveBeenCalled();
+      expect(platformImportBundleFromGcsMock).not.toHaveBeenCalled();
+      expect(platformImportBundleMock).toHaveBeenCalled();
+      expect(consoleLogSpy).toHaveBeenCalledWith(
+        expect.stringContaining("Teleport complete"),
+      );
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+
+  test("upload error: platformUploadToSignedUrl throws → error propagates", async () => {
+    setArgv("--from", "my-local", "--platform");
+
+    const localEntry = makeEntry("my-local", { cloud: "local" });
+
+    findAssistantByNameMock.mockImplementation((name: string) => {
+      if (name === "my-local") return localEntry;
+      return null;
+    });
+
+    // Upload succeeds at getting URL but fails during PUT
+    platformUploadToSignedUrlMock.mockRejectedValue(
+      new Error("Upload to signed URL failed: 500 Internal Server Error"),
+    );
+
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = createFetchMock() as unknown as typeof globalThis.fetch;
+
+    try {
+      await expect(teleport()).rejects.toThrow(
+        "Upload to signed URL failed: 500 Internal Server Error",
+      );
+      // Should NOT fall back to inline import
+      expect(platformImportBundleMock).not.toHaveBeenCalled();
+      expect(platformImportBundleFromGcsMock).not.toHaveBeenCalled();
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+
+  test("413 from GCS import: error message includes 'too large'", async () => {
+    setArgv("--from", "my-local", "--platform");
+
+    const localEntry = makeEntry("my-local", { cloud: "local" });
+
+    findAssistantByNameMock.mockImplementation((name: string) => {
+      if (name === "my-local") return localEntry;
+      return null;
+    });
+
+    // GCS import returns 413
+    platformImportBundleFromGcsMock.mockRejectedValue(
+      new Error("Bundle too large to import"),
+    );
+
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = createFetchMock() as unknown as typeof globalThis.fetch;
+
+    try {
+      await expect(teleport()).rejects.toThrow("too large");
     } finally {
       globalThis.fetch = originalFetch;
     }
@@ -795,35 +1280,164 @@ describe("teleport extra arguments", () => {
 });
 
 // ---------------------------------------------------------------------------
-// Edge case: --from or --to without a following value
+// Platform teleport org ID and reordered flow tests
 // ---------------------------------------------------------------------------
 
-describe("teleport malformed flag usage", () => {
-  test("--from as the last argument (no value) prints help and exits 1", async () => {
-    setArgv("--to", "target", "--from");
-    // --from is the last arg so parseArgs won't assign a value to `from`
-    // This should result in missing --from and trigger help + exit 1
-    await expect(teleport()).rejects.toThrow("process.exit:1");
-    expect(consoleLogSpy).toHaveBeenCalledWith(
-      expect.stringContaining("Usage:"),
-    );
+describe("platform teleport org ID and reordered flow", () => {
+  test("hatchAssistant is called with the org ID from fetchOrganizationId", async () => {
+    setArgv("--from", "my-local", "--platform");
+
+    const localEntry = makeEntry("my-local", { cloud: "local" });
+
+    findAssistantByNameMock.mockImplementation((name: string) => {
+      if (name === "my-local") return localEntry;
+      return null;
+    });
+
+    fetchOrganizationIdMock.mockResolvedValue("test-org-456");
+
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = createFetchMock() as unknown as typeof globalThis.fetch;
+
+    try {
+      await teleport();
+
+      // fetchOrganizationId should have been called
+      expect(fetchOrganizationIdMock).toHaveBeenCalled();
+      // hatchAssistant must be called with (token, orgId)
+      expect(hatchAssistantMock).toHaveBeenCalledWith(
+        "platform-token",
+        "test-org-456",
+      );
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
   });
 
-  test("--to as the last argument (no value) prints help and exits 1", async () => {
-    setArgv("--from", "source", "--to");
-    await expect(teleport()).rejects.toThrow("process.exit:1");
-    expect(consoleLogSpy).toHaveBeenCalledWith(
-      expect.stringContaining("Usage:"),
-    );
+  test("upload to GCS happens before hatchAssistant for platform targets", async () => {
+    setArgv("--from", "my-local", "--platform");
+
+    const localEntry = makeEntry("my-local", { cloud: "local" });
+
+    findAssistantByNameMock.mockImplementation((name: string) => {
+      if (name === "my-local") return localEntry;
+      return null;
+    });
+
+    const callOrder: string[] = [];
+
+    platformRequestUploadUrlMock.mockImplementation(async () => {
+      callOrder.push("platformRequestUploadUrl");
+      return {
+        uploadUrl: "https://storage.googleapis.com/bucket/signed-upload-url",
+        bundleKey: "bundle-key-123",
+        expiresAt: new Date(Date.now() + 3600_000).toISOString(),
+      };
+    });
+
+    platformUploadToSignedUrlMock.mockImplementation(async () => {
+      callOrder.push("platformUploadToSignedUrl");
+    });
+
+    hatchAssistantMock.mockImplementation(async () => {
+      callOrder.push("hatchAssistant");
+      return { id: "platform-new-id", name: "platform-new", status: "active" };
+    });
+
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = createFetchMock() as unknown as typeof globalThis.fetch;
+
+    try {
+      await teleport();
+
+      // Verify ordering: upload steps come before hatch
+      const uploadUrlIdx = callOrder.indexOf("platformRequestUploadUrl");
+      const uploadIdx = callOrder.indexOf("platformUploadToSignedUrl");
+      const hatchIdx = callOrder.indexOf("hatchAssistant");
+
+      expect(uploadUrlIdx).toBeGreaterThanOrEqual(0);
+      expect(uploadIdx).toBeGreaterThanOrEqual(0);
+      expect(hatchIdx).toBeGreaterThanOrEqual(0);
+      expect(uploadUrlIdx).toBeLessThan(hatchIdx);
+      expect(uploadIdx).toBeLessThan(hatchIdx);
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
   });
 
-  test("--from --to target rejects flag-like value for --from, leaving from undefined", async () => {
-    setArgv("--from", "--to", "target");
-    // parseArgs sees --from then skips "--to" (starts with --) so from stays undefined.
-    // --to then correctly consumes "target". from is undefined → prints help and exits 1.
-    await expect(teleport()).rejects.toThrow("process.exit:1");
-    expect(consoleLogSpy).toHaveBeenCalledWith(
-      expect.stringContaining("Usage:"),
+  test("signed-URL fallback: when platformRequestUploadUrl throws 'not available', falls back to inline upload via importToAssistant", async () => {
+    setArgv("--from", "my-local", "--platform");
+
+    const localEntry = makeEntry("my-local", { cloud: "local" });
+
+    findAssistantByNameMock.mockImplementation((name: string) => {
+      if (name === "my-local") return localEntry;
+      return null;
+    });
+
+    // Simulate 503 — signed uploads not available
+    platformRequestUploadUrlMock.mockRejectedValue(
+      new Error("Signed uploads are not available on this platform instance"),
     );
+
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = createFetchMock() as unknown as typeof globalThis.fetch;
+
+    try {
+      await teleport();
+
+      // Upload URL was attempted but failed
+      expect(platformRequestUploadUrlMock).toHaveBeenCalled();
+      // No signed URL upload should have happened
+      expect(platformUploadToSignedUrlMock).not.toHaveBeenCalled();
+      // Should NOT use GCS-based import
+      expect(platformImportBundleFromGcsMock).not.toHaveBeenCalled();
+      // Should fall back to inline import
+      expect(platformImportBundleMock).toHaveBeenCalled();
+      // Hatch should still succeed
+      expect(hatchAssistantMock).toHaveBeenCalled();
+      expect(consoleLogSpy).toHaveBeenCalledWith(
+        expect.stringContaining("Teleport complete"),
+      );
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+
+  test("bundleKey from pre-upload is forwarded to platformImportBundleFromGcs", async () => {
+    setArgv("--from", "my-local", "--platform");
+
+    const localEntry = makeEntry("my-local", { cloud: "local" });
+
+    findAssistantByNameMock.mockImplementation((name: string) => {
+      if (name === "my-local") return localEntry;
+      return null;
+    });
+
+    // Return a specific bundle key from the pre-upload step
+    platformRequestUploadUrlMock.mockResolvedValue({
+      uploadUrl: "https://storage.googleapis.com/bucket/signed-upload-url",
+      bundleKey: "pre-uploaded-key-789",
+      expiresAt: new Date(Date.now() + 3600_000).toISOString(),
+    });
+
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = createFetchMock() as unknown as typeof globalThis.fetch;
+
+    try {
+      await teleport();
+
+      // The bundle key from the pre-upload step should be forwarded to GCS import
+      expect(platformImportBundleFromGcsMock).toHaveBeenCalledWith(
+        "pre-uploaded-key-789",
+        "platform-token",
+        expect.any(String),
+        expect.any(String),
+      );
+      // Inline import should NOT be used since signed upload succeeded
+      expect(platformImportBundleMock).not.toHaveBeenCalled();
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
   });
 });