@vellumai/assistant 0.6.6 → 0.7.1

package/src/runtime/routes/migration-routes.ts

@@ -15,15 +15,17 @@
  */
 
 import { createReadStream } from "node:fs";
+import { hostname } from "node:os";
 import { PassThrough, Readable } from "node:stream";
 import { Database } from "bun:sqlite";
 
 import { z } from "zod";
 
+import { getPlatformAssistantId } from "../../config/env.js";
 import { invalidateConfigCache } from "../../config/loader.js";
+import { getAssistantName } from "../../daemon/identity-helpers.js";
 import { getDb, resetDb } from "../../memory/db-connection.js";
 import { validateMigrationState } from "../../memory/migrations/validate-migration-state.js";
-import { clearCache as clearTrustCache } from "../../permissions/trust-store.js";
 import { credentialKey } from "../../security/credential-key.js";
 import {
   bulkSetSecureKeysAsync,
@@ -41,12 +43,23 @@ import {
   getWorkspaceDir,
   getWorkspaceHooksDir,
 } from "../../util/platform.js";
-import { httpError } from "../http-errors.js";
-import type { RouteDefinition } from "../http-router.js";
+import { APP_VERSION } from "../../version.js";
+import { DAEMON_INTERNAL_ASSISTANT_ID } from "../assistant-scope.js";
 import {
   validateGcsSignedUrl,
   type ValidateGcsSignedUrlOptions,
 } from "../migrations/gcs-signed-url.js";
+import {
+  JobAlreadyInProgressError,
+  migrationJobs,
+} from "../migrations/job-registry.js";
+import { getOriginMode } from "../migrations/origin-mode.js";
+import type {
+  VBundleAssistantInfo,
+  VBundleCompatibility,
+  VBundleExportOptions,
+  VBundleOriginInfo,
+} from "../migrations/vbundle-builder.js";
 import { streamExportVBundle } from "../migrations/vbundle-builder.js";
 import {
   analyzeImport,
@@ -60,6 +73,15 @@ import {
 } from "../migrations/vbundle-importer.js";
 import { streamCommitImport } from "../migrations/vbundle-streaming-importer.js";
 import { validateVBundle } from "../migrations/vbundle-validator.js";
+import {
+  BadGatewayError,
+  BadRequestError,
+  InternalError,
+  NotFoundError,
+  RouteError,
+} from "./errors.js";
+import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
+import { RouteResponse } from "./types.js";
 
 /**
  * CES account prefix for platform-identity (`vellum:*`) credentials. Entries
@@ -126,6 +148,110 @@ export async function reconcileVellumMetadataFromCes(warningSink: {
 
 const log = getLogger("migration-routes");
 
+/**
+ * Fields the export pipeline must populate on the v1 manifest.
+ *
+ * Centralized so both the synchronous-bytes and async-to-gcs handlers
+ * compute the same values (and a future caller doesn't accidentally drift).
+ */
+interface ExportManifestInputs {
+  assistant: VBundleAssistantInfo;
+  origin: VBundleOriginInfo;
+  compatibility: VBundleCompatibility;
+  exportOptions: VBundleExportOptions;
+}
+
+/**
+ * Resolve the `assistant.id` for an export.
+ *
+ * Mirrors `platform/client.ts`'s precedence: in-memory override (set at
+ * daemon startup or by secret-routes) → credential store → daemon-internal
+ * fallback. The schema requires `id` to be non-empty, so we fall back to
+ * `DAEMON_INTERNAL_ASSISTANT_ID` rather than the empty string.
+ */
+async function resolveAssistantId(): Promise<string> {
+  const inMemory = getPlatformAssistantId();
+  if (inMemory) return inMemory;
+  try {
+    const stored = await getSecureKeyAsync(
+      credentialKey("vellum", "platform_assistant_id"),
+    );
+    if (stored) return stored;
+  } catch (err) {
+    log.warn(
+      { err },
+      "Failed to read platform_assistant_id from credential store; falling back to daemon-internal id",
+    );
+  }
+  return DAEMON_INTERNAL_ASSISTANT_ID;
+}
+
+/**
+ * Decide the truthful `secrets_redacted` flag for an export.
+ *
+ * The export entry points pass every collected credential through to the
+ * builder unfiltered, so the bundle is NOT redacted whenever any
+ * credentials made it in. Only flip to true when the credential list is
+ * empty AND every credential read succeeded — i.e. there genuinely are
+ * no secrets in the bundle.
+ *
+ * Two failure modes both force `false`:
+ *   - `storeUnreachable`: the top-level `listSecureKeysAsync()` call
+ *     failed, so we never even discovered which accounts exist.
+ *   - `perAccountUnreachable`: the LIST call succeeded but one or more
+ *     individual `getSecureKeyResultAsync(account)` reads returned
+ *     `unreachable: true`. Those accounts were silently skipped from the
+ *     `credentials` array, so a `credentialCount === 0` outcome could
+ *     reflect "we couldn't read them" rather than "no secrets exist".
+ *     Claiming a clean redaction in that case would be a lie.
+ *
+ * NOTE: a managed-mode bundle with `secrets_redacted: false` will fail
+ * the validator's cross-field refine. That surfaces an existing
+ * platform-side enforcement gap — the runtime emits the truthful value
+ * and lets the schema flag it.
+ */
+export function computeSecretsRedacted(
+  credentialCount: number,
+  storeUnreachable: boolean,
+  perAccountUnreachable: boolean,
+): boolean {
+  return credentialCount === 0 && !storeUnreachable && !perAccountUnreachable;
+}
+
+/**
+ * Compute the v1 manifest inputs that aren't tied to per-call options.
+ *
+ * `walkDirectoryForMetadata` skips `embedding-models`, `data/qdrant`,
+ * `signals`, and `deprecated` — `logs` is NOT in the skip list, so log
+ * files end up in `manifest.contents`. Browser state and memory vectors
+ * (qdrant) are skipped, so those flags are false.
+ */
+async function buildExportManifestInputs(): Promise<ExportManifestInputs> {
+  const assistantId = await resolveAssistantId();
+  const assistantName = getAssistantName() ?? "Assistant";
+  const originMode = await getOriginMode();
+  return {
+    assistant: {
+      id: assistantId,
+      name: assistantName,
+      runtime_version: APP_VERSION,
+    },
+    origin: {
+      mode: originMode,
+      hostname: hostname(),
+    },
+    compatibility: {
+      min_runtime_version: APP_VERSION,
+      max_runtime_version: null,
+    },
+    exportOptions: {
+      include_logs: true,
+      include_browser_state: false,
+      include_memory_vectors: false,
+    },
+  };
+}
+
 /**
  * POST /v1/migrations/validate
  *
@@ -139,60 +265,24 @@ const log = getLogger("migration-routes");
  *   400: Standard error envelope for missing/empty body
  *   422: Standard error envelope for completely unparseable input
  */
-export async function handleMigrationValidate(req: Request): Promise<Response> {
-  let fileData: Uint8Array | null = null;
-
-  const contentType = req.headers.get("content-type") ?? "";
-
-  if (contentType.includes("multipart/form-data")) {
-    try {
-      const formData = await req.formData();
-      const file = formData.get("file");
-      if (!file || !(file instanceof Blob)) {
-        return httpError(
-          "BAD_REQUEST",
-          'Multipart upload requires a "file" field',
-          400,
-        );
-      }
-      fileData = new Uint8Array(await file.arrayBuffer());
-    } catch (err) {
-      log.error({ err }, "Failed to parse multipart form data");
-      return httpError("BAD_REQUEST", "Invalid multipart form data", 400);
-    }
-  } else {
-    // Treat as raw binary body
-    try {
-      const arrayBuffer = await req.arrayBuffer();
-      fileData = new Uint8Array(arrayBuffer);
-    } catch (err) {
-      log.error({ err }, "Failed to read request body");
-      return httpError("BAD_REQUEST", "Failed to read request body", 400);
-    }
-  }
-
-  if (!fileData || fileData.length === 0) {
-    return httpError(
-      "BAD_REQUEST",
-      "Request body is empty — a .vbundle file is required",
-      400,
-    );
-  }
+export async function handleMigrationValidate({
+  rawBody,
+  headers,
+}: RouteHandlerArgs) {
+  const fileData = await extractFileData(rawBody, headers);
 
   try {
     const result = validateVBundle(fileData);
 
-    return Response.json({
+    return {
       is_valid: result.is_valid,
       errors: result.errors,
       ...(result.manifest ? { manifest: result.manifest } : {}),
-    });
+    };
   } catch (err) {
     log.error({ err }, "Unexpected error during vbundle validation");
-    return httpError(
-      "INTERNAL_ERROR",
+    throw new InternalError(
       err instanceof Error ? err.message : "Unexpected validation error",
-      500,
     );
   }
 }
@@ -214,28 +304,21 @@ export async function handleMigrationValidate(req: Request): Promise<Response> {
  *
  * Auth: Requires settings.write scope. Allowed for actor, svc_gateway, svc_daemon, local.
  */
-export async function handleMigrationExport(req: Request): Promise<Response> {
-  let description: string | undefined;
-
-  // Parse optional JSON body for export metadata
-  const contentType = req.headers.get("content-type") ?? "";
-  if (contentType.includes("application/json")) {
-    try {
-      const body = (await req.json()) as Record<string, unknown>;
-      if (typeof body.description === "string") {
-        description = body.description;
-      }
-    } catch (err) {
-      log.warn({ err }, "Failed to parse export request body — using defaults");
-    }
-  }
-
+export async function handleMigrationExport(
+  _args: RouteHandlerArgs,
+): Promise<RouteResponse> {
+  // The legacy `description` field is no longer carried on the v1
+  // manifest. Older clients still POST it; we silently ignore it.
   let cleanup: (() => Promise<void>) | undefined;
 
   try {
     // Read all stored credentials to include in the export bundle
     const credentialList = await listSecureKeysAsync();
     const credentials: Array<{ account: string; value: string }> = [];
+    // Track per-account read failures separately from the top-level LIST
+    // failure. A single skipped account means we cannot truthfully claim
+    // the bundle is fully redacted — we don't know what we missed.
+    let perAccountUnreachable = false;
     if (credentialList.unreachable) {
       log.warn(
         "Credential store is unreachable — export will not include credentials",
@@ -244,6 +327,7 @@ export async function handleMigrationExport(req: Request): Promise<Response> {
       for (const account of credentialList.accounts) {
         const result = await getSecureKeyResultAsync(account);
         if (result.unreachable) {
+          perAccountUnreachable = true;
           log.warn(
             { account },
             "Credential store unreachable when reading credential — skipping",
@@ -254,10 +338,17 @@ export async function handleMigrationExport(req: Request): Promise<Response> {
       }
     }
 
+    const manifestInputs = await buildExportManifestInputs();
+    const secretsRedacted = computeSecretsRedacted(
+      credentials.length,
+      credentialList.unreachable,
+      perAccountUnreachable,
+    );
+
     const result = await streamExportVBundle({
       workspaceDir: getWorkspaceDir(),
-      source: "runtime-export",
-      description,
+      ...manifestInputs,
+      secretsRedacted,
       credentials,
       checkpoint: () => {
         const dbPath = getDbPath();
@@ -292,30 +383,318 @@ export async function handleMigrationExport(req: Request): Promise<Response> {
       cleanup = undefined;
     });
 
-    const body = Readable.toWeb(fileStream) as unknown as ReadableStream;
-
-    return new Response(body, {
-      status: 200,
-      headers: {
-        "Content-Type": "application/octet-stream",
-        "Content-Disposition": `attachment; filename="${filename}"`,
-        "Content-Length": String(size),
-        "X-Vbundle-Schema-Version": manifest.schema_version,
-        "X-Vbundle-Manifest-Sha256": manifest.manifest_sha256,
-        "X-Vbundle-Credentials-Included": String(credentials.length),
-      },
+    const streamBody = Readable.toWeb(fileStream) as unknown as ReadableStream;
+
+    return new RouteResponse(streamBody, {
+      "Content-Type": "application/octet-stream",
+      "Content-Disposition": `attachment; filename="${filename}"`,
+      "Content-Length": String(size),
+      // `schema_version` is now an integer; clients that parse this header
+      // continue to work, but the value flips from "1.0" to "1".
+      "X-Vbundle-Schema-Version": String(manifest.schema_version),
+      // Header name preserved for cross-version client compat; populated
+      // from the renamed manifest `checksum` field.
+      "X-Vbundle-Manifest-Sha256": manifest.checksum,
+      "X-Vbundle-Credentials-Included": String(credentials.length),
     });
   } catch (err) {
     await cleanup?.();
     log.error({ err }, "Failed to build export bundle");
-    return httpError(
-      "INTERNAL_ERROR",
+    throw new InternalError(
       err instanceof Error ? err.message : "Unexpected export error",
-      500,
     );
   }
 }
 
+// ---------------------------------------------------------------------------
+// POST /v1/migrations/export-to-gcs — async export streamed to a signed URL
+// ---------------------------------------------------------------------------
+
+/** 60 minutes — matches the URL-body import fetch deadline. */
+const EXPORT_TO_GCS_PUT_TIMEOUT_MS = 60 * 60 * 1000;
+
+const MigrationExportToGcsBody = z.object({
+  upload_url: z.string().url(),
+  description: z.string().optional(),
+});
+
+/**
+ * Collected credentials plus warning markers if the credential store was
+ * unreachable. The caller surfaces the warning in logs; production callers
+ * fail closed on errors (a thrown exception → 500) to avoid shipping a
+ * bundle with partial credentials. An unreachable store is NOT an error —
+ * `handleMigrationExport` treats that case as "export without credentials".
+ *
+ * - `unreachable`: the top-level `listSecureKeysAsync()` call failed.
+ * - `perAccountUnreachable`: the LIST succeeded but one or more individual
+ *   `getSecureKeyResultAsync(account)` calls returned `unreachable: true`.
+ *   Those accounts were silently skipped from `credentials`, so the count
+ *   here understates reality. The flag is what tells `computeSecretsRedacted`
+ *   it cannot claim a clean redaction.
+ */
+interface CollectedCredentials {
+  credentials: Array<{ account: string; value: string }>;
+  unreachable: boolean;
+  perAccountUnreachable: boolean;
+}
+
+/**
+ * Mirror of the credential-collection block inside `handleMigrationExport`.
+ * Factored out so the new async export-to-gcs handler can share the exact
+ * same behavior. Throws if the credential store raises an unexpected error —
+ * the caller translates that into a 500 (fail closed on credential errors).
+ */
+async function collectExportCredentials(): Promise<CollectedCredentials> {
+  const credentialList = await listSecureKeysAsync();
+  if (credentialList.unreachable) {
+    log.warn(
+      "Credential store is unreachable — export will not include credentials",
+    );
+    return {
+      credentials: [],
+      unreachable: true,
+      perAccountUnreachable: false,
+    };
+  }
+  const credentials: Array<{ account: string; value: string }> = [];
+  let perAccountUnreachable = false;
+  for (const account of credentialList.accounts) {
+    const result = await getSecureKeyResultAsync(account);
+    if (result.unreachable) {
+      perAccountUnreachable = true;
+      log.warn(
+        { account },
+        "Credential store unreachable when reading credential — skipping",
+      );
+    } else if (result.value != null) {
+      credentials.push({ account, value: result.value });
+    }
+  }
+  return { credentials, unreachable: false, perAccountUnreachable };
+}
+
+/**
+ * POST /v1/migrations/export-to-gcs
+ *
+ * Starts an async export job that streams a freshly-built .vbundle archive
+ * to a GCS signed PUT URL. Returns `202 Accepted` with a `job_id` the caller
+ * can poll via the job-status endpoint; the bundle upload runs in the
+ * background via `migrationJobs`.
+ *
+ * Request body (JSON):
+ *   { upload_url: string, description?: string }
+ *
+ * Responses:
+ *   202: { job_id, status: "pending", type: "export" }
+ *   400: { error: { code: "invalid_upload_url", reason } } — URL failed
+ *        `validateGcsSignedUrl` (scheme/host/signature/traversal).
+ *   409: { error: { code: "export_in_progress", job_id } } — another export
+ *        job is already pending or running.
+ *   500: Standard error envelope for credential-collection failures or
+ *        other unexpected errors before the job is enqueued.
+ *
+ * Terminal job state (surfaced via the job-status endpoint once poll lands):
+ *   result: { size, sha256, schemaVersion, credentialsIncluded }
+ *   error.code = "upload_failed" with `upstreamStatus` on non-2xx PUT
+ *   error.code = "fetch_failed" on transport errors from the PUT itself.
+ *
+ * Auth: settings.write scope (matches `migrations/export`).
+ */
+export async function handleMigrationExportToGcs({ body }: RouteHandlerArgs) {
+  // ── 1. Parse JSON body ────────────────────────────────────────────────
+  const parsed = MigrationExportToGcsBody.safeParse(body);
+  if (!parsed.success) {
+    throw new BadRequestError(
+      "Request body must be { upload_url: string, description?: string } with a valid URL",
+    );
+  }
+
+  // ── 2. Validate the upload URL. Never log `parsed.data.upload_url`.
+  const validated = validateGcsSignedUrl(
+    parsed.data.upload_url,
+    urlValidatorOptions,
+  );
+  if (!validated.ok) {
+    log.warn(
+      { reason: validated.reason },
+      "Rejected migration export-to-gcs upload URL",
+    );
+    throw new RouteError(
+      `Invalid upload URL: ${validated.reason}`,
+      "invalid_upload_url",
+      400,
+    );
+  }
+
+  log.info(
+    { host: validated.host, path: validated.path },
+    "migration export to GCS starting",
+  );
+
+  // ── 3. Collect credentials up front. Fail closed → 500.
+  let collected: CollectedCredentials;
+  try {
+    collected = await collectExportCredentials();
+  } catch (err) {
+    log.error({ err }, "Failed to collect credentials for export-to-gcs");
+    throw new InternalError(
+      err instanceof Error ? err.message : "Failed to collect credentials",
+    );
+  }
+
+  const uploadUrl = parsed.data.upload_url;
+
+  // Compute the v1 manifest inputs once outside the async job runner so we
+  // surface failures (e.g. credential-store probe) as a synchronous 500
+  // before the caller starts polling.
+  let manifestInputs: ExportManifestInputs;
+  try {
+    manifestInputs = await buildExportManifestInputs();
+  } catch (err) {
+    log.error({ err }, "Failed to assemble export manifest inputs");
+    throw new InternalError(
+      err instanceof Error
+        ? err.message
+        : "Failed to assemble export manifest inputs",
+    );
+  }
+
+  const secretsRedacted = computeSecretsRedacted(
+    collected.credentials.length,
+    collected.unreachable,
+    collected.perAccountUnreachable,
+  );
+
+  // ── 4. Enqueue the job. The runner captures the collected credentials.
+  let job;
+  try {
+    job = migrationJobs.startJob("export", async () => {
+      let cleanup: (() => Promise<void>) | undefined;
+      try {
+        const result = await streamExportVBundle({
+          workspaceDir: getWorkspaceDir(),
+          ...manifestInputs,
+          secretsRedacted,
+          credentials: collected.credentials,
+          checkpoint: () => {
+            const dbPath = getDbPath();
+            try {
+              const db = new Database(dbPath);
+              try {
+                db.exec("PRAGMA wal_checkpoint(TRUNCATE)");
+              } finally {
+                db.close();
+              }
+            } catch (err) {
+              log.warn(
+                { err },
+                "WAL checkpoint failed — exporting without checkpoint",
+              );
+            }
+          },
+        });
+
+        cleanup = result.cleanup;
+        const { tempPath, size, manifest } = result;
+
+        // Stream the temp file to GCS via PUT. Using Node's ReadableStream
+        // bridge keeps peak memory bounded — we do NOT load the archive
+        // into memory.
+        const fileStream = createReadStream(tempPath);
+        const webBody = Readable.toWeb(
+          fileStream,
+        ) as unknown as ReadableStream<Uint8Array>;
+
+        let response: Response;
+        try {
+          response = await fetch(uploadUrl, {
+            method: "PUT",
+            body: webBody,
+            // `duplex: "half"` is required when sending a streaming body
+            // via fetch in Node/Bun — without it the platform rejects the
+            // request as "duplex option is required when body is a
+            // ReadableStream".
+            duplex: "half",
+            // `validateGcsSignedUrl` only vets the initial URL. If the
+            // upstream responds with a 3xx, default fetch would follow
+            // the redirect and PUT bytes to an attacker-controlled host.
+            // Refuse redirects so the signed URL's origin is the only
+            // destination for the export archive.
+            redirect: "error",
+            headers: {
+              "Content-Type": "application/octet-stream",
+              "Content-Length": String(size),
+            },
+            signal: AbortSignal.timeout(EXPORT_TO_GCS_PUT_TIMEOUT_MS),
+          } as RequestInit & { duplex: "half" });
+        } catch (err) {
+          // Transport-level fetch failures (DNS, reset, abort) — tag them
+          // with the fetch-body marker so the registry maps them to
+          // `error.code = "fetch_failed"` and logs stay consistent with
+          // the import URL path.
+          const wrapped = err instanceof Error ? err : new Error(String(err));
+          tagFetchBodyError(wrapped as NodeJS.ErrnoException);
+          (wrapped as { code?: string }).code = "fetch_failed";
+          throw wrapped;
+        }
+
+        if (!response.ok) {
+          // Drain so the socket is released promptly. Ignore drain errors.
+          try {
+            await response.body?.cancel();
+          } catch {
+            /* best-effort */
+          }
+          const uploadErr = new Error(
+            `Upload to GCS failed with status ${response.status}`,
+          );
+          (uploadErr as { code?: string }).code = "upload_failed";
+          (uploadErr as { upstreamStatus?: number }).upstreamStatus =
+            response.status;
+          throw uploadErr;
+        }
+
+        return {
+          size,
+          sha256: manifest.checksum,
+          schemaVersion: manifest.schema_version,
+          credentialsIncluded: collected.credentials.length,
+        };
+      } finally {
+        // Mirror the raw-bytes export cleanup pattern: the stream's
+        // `close` listener is the happy-path cleanup in that handler, but
+        // here we keep everything in the async block, so a finally is the
+        // right place to evict the temp file regardless of outcome.
+        if (cleanup) {
+          try {
+            await cleanup();
+          } catch (err) {
+            log.warn({ err }, "Failed to clean up export-to-gcs temp file");
+          }
+        }
+      }
+    });
+  } catch (err) {
+    if (err instanceof JobAlreadyInProgressError) {
+      throw new RouteError(
+        `Export already in progress: ${err.existingJobId}`,
+        "export_in_progress",
+        409,
+      );
+    }
+    log.error({ err }, "Unexpected error while enqueueing export-to-gcs job");
+    throw new InternalError(
+      err instanceof Error ? err.message : "Unexpected export-to-gcs error",
+    );
+  }
+
+  return {
+    job_id: job.id,
+    status: "pending" as const,
+    type: "export" as const,
+  };
+}
+
 /**
  * Extract file data from a request body, supporting both raw binary
  * and multipart form data uploads.
@@ -323,42 +702,41 @@ export async function handleMigrationExport(req: Request): Promise<Response> {
  * Shared between validate and import-preflight handlers.
  */
 async function extractFileData(
-  req: Request,
-): Promise<{ data: Uint8Array } | { error: Response }> {
-  const contentType = req.headers.get("content-type") ?? "";
+  rawBody: Uint8Array | undefined,
+  headers: Record<string, string> | undefined,
+): Promise<Uint8Array> {
+  const contentType = headers?.["content-type"] ?? "";
 
   if (contentType.includes("multipart/form-data")) {
+    if (!rawBody) {
+      throw new BadRequestError("Request body is empty");
+    }
     try {
-      const formData = await req.formData();
+      const syntheticReq = new Request("http://localhost", {
+        method: "POST",
+        headers: { "content-type": contentType },
+        body: rawBody.buffer as ArrayBuffer,
+      });
+      const formData = await syntheticReq.formData();
       const file = formData.get("file");
       if (!file || !(file instanceof Blob)) {
-        return {
-          error: httpError(
-            "BAD_REQUEST",
-            'Multipart upload requires a "file" field',
-            400,
-          ),
-        };
+        throw new BadRequestError('Multipart upload requires a "file" field');
       }
-      return { data: new Uint8Array(await file.arrayBuffer()) };
+      return new Uint8Array(await file.arrayBuffer());
     } catch (err) {
+      if (err instanceof BadRequestError) throw err;
       log.error({ err }, "Failed to parse multipart form data");
-      return {
-        error: httpError("BAD_REQUEST", "Invalid multipart form data", 400),
-      };
+      throw new BadRequestError("Invalid multipart form data");
     }
   }
 
-  // Treat as raw binary body
-  try {
-    const arrayBuffer = await req.arrayBuffer();
-    return { data: new Uint8Array(arrayBuffer) };
-  } catch (err) {
-    log.error({ err }, "Failed to read request body");
-    return {
-      error: httpError("BAD_REQUEST", "Failed to read request body", 400),
-    };
+  // Raw binary body — already provided as rawBody by the adapter
+  if (!rawBody || rawBody.length === 0) {
+    throw new BadRequestError(
+      "Request body is empty — a .vbundle file is required",
+    );
   }
+  return rawBody;
 }
 
 /**
@@ -387,35 +765,23 @@ async function extractFileData(
  *
  * Auth: Requires settings.write scope. Allowed for actor, svc_gateway, svc_daemon, local.
  */
-export async function handleMigrationImportPreflight(
-  req: Request,
-): Promise<Response> {
-  const extracted = await extractFileData(req);
-  if ("error" in extracted) {
-    return extracted.error;
-  }
-
-  const fileData = extracted.data;
-  if (fileData.length === 0) {
-    return httpError(
-      "BAD_REQUEST",
-      "Request body is empty — a .vbundle file is required",
-      400,
-    );
-  }
+export async function handleMigrationImportPreflight({
+  rawBody,
+  headers,
+}: RouteHandlerArgs) {
+  const fileData = await extractFileData(rawBody, headers);
 
   try {
-    // Step 1: Validate the bundle
     const validationResult = validateVBundle(fileData);
 
     if (!validationResult.is_valid || !validationResult.manifest) {
-      return Response.json({
+      return {
         can_import: false,
         validation: {
           is_valid: false,
           errors: validationResult.errors,
         },
-      });
+      };
     }
 
     const pathResolver = new DefaultPathResolver(
@@ -423,18 +789,14 @@ export async function handleMigrationImportPreflight(
       getWorkspaceHooksDir(),
     );
 
-    const report = analyzeImport({
+    return analyzeImport({
       manifest: validationResult.manifest,
       pathResolver,
     });
-
-    return Response.json(report);
   } catch (err) {
     log.error({ err }, "Unexpected error during import preflight analysis");
-    return httpError(
-      "INTERNAL_ERROR",
+    throw new InternalError(
       err instanceof Error ? err.message : "Unexpected import preflight error",
-      500,
     );
   }
 }
@@ -477,31 +839,18 @@ export async function handleMigrationImportPreflight(
  *
  * Auth: Requires settings.write scope. Allowed for actor, svc_gateway, svc_daemon, local.
  */
-export async function handleMigrationImport(req: Request): Promise<Response> {
+export async function handleMigrationImport(
+  args: RouteHandlerArgs,
+): Promise<unknown> {
+  const { body, rawBody, headers } = args;
   // JSON body means the caller is asking us to fetch the bundle from a
-  // signed URL and stream it through the importer. This keeps the daemon's
-  // peak memory bounded by one tar entry instead of bundle size, which is
-  // the whole point of supporting URL-based imports for large bundles.
-  //
-  // Raw-bytes path (octet-stream / multipart) is untouched below.
-  const contentType = req.headers.get("content-type") ?? "";
+  // signed URL and stream it through the importer.
+  const contentType = headers?.["content-type"] ?? "";
   if (contentType.includes("application/json")) {
-    return handleMigrationImportFromUrl(req);
+    return handleMigrationImportFromUrl(body);
   }
 
-  const extracted = await extractFileData(req);
-  if ("error" in extracted) {
-    return extracted.error;
-  }
-
-  const fileData = extracted.data;
-  if (fileData.length === 0) {
-    return httpError(
-      "BAD_REQUEST",
-      "Request body is empty — a .vbundle file is required",
-      400,
-    );
-  }
+  const fileData = await extractFileData(rawBody, headers);
 
   try {
     // Validate the bundle before closing the DB to avoid an unnecessary
@@ -510,11 +859,11 @@ export async function handleMigrationImport(req: Request): Promise<Response> {
     // (avoids holding two copies of decompressed data in memory).
     const validation = validateVBundle(fileData);
     if (!validation.is_valid) {
-      return Response.json({
+      return {
         success: false,
         reason: "validation_failed",
         errors: validation.errors,
-      });
+      };
     }
 
     const pathResolver = new DefaultPathResolver(
@@ -535,7 +884,7 @@ export async function handleMigrationImport(req: Request): Promise<Response> {
     });
 
     if (!result.ok) {
-      return importCommitFailureResponse(result);
+      throwImportCommitFailure(result);
     }
 
     // Import credentials from the bundle into CES (non-blocking — failures
@@ -558,9 +907,8 @@ export async function handleMigrationImport(req: Request): Promise<Response> {
     // if Django's post-hatch provisioning raced with the import.
     await reconcileVellumMetadataFromCes(result.report);
 
-    // Invalidate in-process caches so imported settings.json and trust.json take effect
+    // Invalidate in-process config cache so imported settings.json takes effect
     invalidateConfigCache();
-    clearTrustCache();
 
     // Check whether the imported database contains migration checkpoints from
     // a newer version. This is non-blocking — the import has already
@@ -568,19 +916,18 @@ export async function handleMigrationImport(req: Request): Promise<Response> {
     // not be fully compatible with this daemon's schema.
     appendNewerMigrationWarningsIfAny(result.report);
 
-    return importCommitSuccessResponse(result.report, credentialsImported);
+    return importCommitSuccessResult(result.report, credentialsImported);
   } catch (err) {
     log.error({ err }, "Unexpected error during import commit");
-    return httpError(
-      "INTERNAL_ERROR",
+    throw new InternalError(
       err instanceof Error ? err.message : "Unexpected import error",
-      500,
     );
   }
 }
 
 // ---------------------------------------------------------------------------
-// URL-body variant of POST /v1/migrations/import
+// GCS URL import pipeline — shared by the URL-body branch of
+// POST /v1/migrations/import and POST /v1/migrations/import-from-gcs.
 // ---------------------------------------------------------------------------
 
 /** 60 minutes — matches the gateway's upstream fetch deadline. */
@@ -588,6 +935,8 @@ const URL_FETCH_TIMEOUT_MS = 60 * 60 * 1000;
 
 const MigrationImportUrlBody = z.object({ url: z.string().min(1) });
 
+const MigrationImportFromGcsBody = z.object({ bundle_url: z.string().url() });
+
 /**
  * Marker attached to errors that originate from the upstream HTTP body
  * stream (peer reset, abort mid-stream, DNS/transport failure after
@@ -643,43 +992,98 @@ export function _setUrlImportValidatorOptionsForTests(
 }
 
 /**
- * Handle a JSON `{ "url": "..." }` body on POST /v1/migrations/import.
- *
- * Fetches the signed URL, pipes the response body through the streaming
- * importer, and returns the same response shapes as the raw-bytes path.
- * The signed URL is never logged or included in error responses — only the
- * extracted host and path make it into logs.
+ * Successful outcome of `runGcsImport`. Mirrors the wire shape produced by
+ * `importCommitSuccessResponse` (report fields spread at the top level, with
+ * an optional `credentialsImported` summary alongside) so the same value can
+ * be serialized directly as a Response body OR stashed as an async-job
+ * `result` — both the sync endpoint and the async job-status endpoint then
+ * hand the CLI a single, identical `ImportResponse`-compatible shape.
  */
-async function handleMigrationImportFromUrl(req: Request): Promise<Response> {
-  // ── 1. Parse JSON body ────────────────────────────────────────────────
-  let rawBody: unknown;
-  try {
-    rawBody = await req.json();
-  } catch (err) {
-    log.warn(
-      { err: err instanceof Error ? err.message : String(err) },
-      "Failed to parse JSON body on migration import URL request",
-    );
-    return httpError("BAD_REQUEST", "Invalid JSON body", 400);
-  }
+export interface ImportSummary extends ImportCommitReport {
+  credentialsImported?: CredentialImportSummary;
+}
 
-  const parsed = MigrationImportUrlBody.safeParse(rawBody);
-  if (!parsed.success) {
-    return httpError(
-      "BAD_REQUEST",
-      "Request body must be { url: string } with a non-empty url",
-      400,
-    );
+/**
+ * Structured error thrown by `runGcsImport`. Carries the information needed
+ * to reconstruct the URL-body handler's legacy Response shapes and for the
+ * async-job registry to map to `error.code`/`upstreamStatus`.
+ */
+interface GcsImportErrorInit {
+  code:
+    | "invalid_url"
+    | "fetch_failed"
+    | "validation_failed"
+    | "extraction_failed"
+    | "write_failed";
+  message: string;
+  upstreamStatus?: number;
+  reason?: string;
+  errors?: Array<{ code: string; message: string; path?: string }>;
+  partial_report?: ImportCommitReport;
+}
+
+class GcsImportError extends Error {
+  public readonly code: GcsImportErrorInit["code"];
+  public readonly upstreamStatus?: number;
+  public readonly reason?: string;
+  public readonly errors?: GcsImportErrorInit["errors"];
+  public readonly partial_report?: ImportCommitReport;
+
+  constructor(init: GcsImportErrorInit) {
+    super(init.message);
+    this.name = "GcsImportError";
+    this.code = init.code;
+    if (init.upstreamStatus !== undefined) {
+      this.upstreamStatus = init.upstreamStatus;
+    }
+    if (init.reason !== undefined) {
+      this.reason = init.reason;
+    }
+    if (init.errors !== undefined) {
+      this.errors = init.errors;
+    }
+    if (init.partial_report !== undefined) {
+      this.partial_report = init.partial_report;
+    }
   }
+}
 
-  // ── 2. Validate the URL (defense-in-depth; never log `parsed.data.url`).
-  const validated = validateGcsSignedUrl(parsed.data.url, urlValidatorOptions);
+/**
+ * Fetch a .vbundle from a signed GCS URL and commit it via the streaming
+ * importer. On success, returns an `ImportSummary` the caller can serialize
+ * into a Response or stash as an async-job `result`. On failure, throws a
+ * `GcsImportError`:
+ *
+ *   - `invalid_url`        → URL failed `validateGcsSignedUrl` (pre-fetch).
+ *   - `fetch_failed`       → upstream fetch error, non-2xx response, missing
+ *                            body, OR a mid-stream body teardown tagged via
+ *                            `kFetchBodyError`. `upstreamStatus` is populated
+ *                            for non-2xx responses.
+ *   - `validation_failed`  → the bundle failed schema/structural validation
+ *                            inside `streamCommitImport`; `errors` carries
+ *                            the per-issue list.
+ *   - `extraction_failed`  → bundle extraction threw (malformed archive, hash
+ *                            mismatch, etc.) that was NOT an upstream tear-
+ *                            down. `reason` carries the importer's string.
+ *   - `write_failed`       → post-extraction disk write error; `partial_report`
+ *                            is attached when the importer produced one.
+ *
+ * The signed URL is never echoed into errors or logs — only the extracted
+ * `host`/`path` are.
+ */
+async function runGcsImport(
+  url: string,
+  _correlationId?: string,
+): Promise<ImportSummary> {
+  // ── 1. Validate the URL (defense-in-depth; never log the raw URL).
+  const validated = validateGcsSignedUrl(url, urlValidatorOptions);
   if (!validated.ok) {
-    // `reason` is a stable enum string and safe to include. The raw URL is
-    // not — it may contain a live signature. Callers get the reason so they
-    // can correct the URL without leaking anything into observability.
     log.warn({ reason: validated.reason }, "Rejected migration import URL");
-    return httpError("BAD_REQUEST", `Invalid URL: ${validated.reason}`, 400);
+    throw new GcsImportError({
+      code: "invalid_url",
+      message: `Invalid URL: ${validated.reason}`,
+      reason: validated.reason,
+    });
   }
 
   log.info(
@@ -689,10 +1093,10 @@ async function handleMigrationImportFromUrl(req: Request): Promise<Response> {
 
   const startedAt = Date.now();
 
-  // ── 3. Fetch the URL ──────────────────────────────────────────────────
+  // ── 2. Fetch the URL ──────────────────────────────────────────────────
   let upstream: Response;
   try {
-    upstream = await fetch(parsed.data.url, {
+    upstream = await fetch(url, {
       signal: AbortSignal.timeout(URL_FETCH_TIMEOUT_MS),
       // SSRF guard: `validateGcsSignedUrl` only vetted the initial URL.
       // Default fetch behavior follows 3xx responses, which would let a
@@ -710,10 +1114,10 @@ async function handleMigrationImportFromUrl(req: Request): Promise<Response> {
       },
       "Failed to fetch migration import URL",
     );
-    return Response.json(
-      { success: false, reason: "fetch_failed" },
-      { status: 502 },
-    );
+    throw new GcsImportError({
+      code: "fetch_failed",
+      message: err instanceof Error ? err.message : String(err),
+    });
   }
 
   if (!upstream.ok) {
@@ -731,14 +1135,11 @@ async function handleMigrationImportFromUrl(req: Request): Promise<Response> {
     } catch {
       /* best effort */
     }
-    return Response.json(
-      {
-        success: false,
-        reason: "fetch_failed",
-        upstream_status: upstream.status,
-      },
-      { status: 502 },
-    );
+    throw new GcsImportError({
+      code: "fetch_failed",
+      message: `Upstream fetch returned ${upstream.status}`,
+      upstreamStatus: upstream.status,
+    });
   }
 
   if (!upstream.body) {
@@ -746,13 +1147,13 @@ async function handleMigrationImportFromUrl(req: Request): Promise<Response> {
       { host: validated.host, path: validated.path },
       "Migration import URL fetch returned no body",
     );
-    return Response.json(
-      { success: false, reason: "fetch_failed" },
-      { status: 502 },
-    );
+    throw new GcsImportError({
+      code: "fetch_failed",
+      message: "Upstream fetch returned no body",
+    });
   }
 
-  // ── 4. Stream the response through the importer ──────────────────────
+  // ── 3. Stream the response through the importer ──────────────────────
   // Convert the WHATWG ReadableStream from fetch() into a Node Readable so
   // the tar-stream / gunzip / hash-verifier pipeline inside
   // streamCommitImport can consume it via `.pipe()`.
@@ -764,8 +1165,8 @@ async function handleMigrationImportFromUrl(req: Request): Promise<Response> {
   // from the upstream HTTP body (peer reset, abort mid-stream, etc.) with a
   // known symbol. When that tagged error surfaces out of
   // streamCommitImport's gunzip/tar pipeline, we can distinguish it from a
-  // legitimate bundle-format failure and map it to 502 fetch_failed instead
-  // of 500 extraction_failed — matching the OpenAPI contract for the URL
+  // legitimate bundle-format failure and map it to `fetch_failed` instead
+  // of `extraction_failed` — matching the OpenAPI contract for the URL
   // body shape. We also propagate errors from the wrapper back to the
   // upstream stream so its underlying connection is torn down cleanly.
   //
@@ -781,7 +1182,7 @@ async function handleMigrationImportFromUrl(req: Request): Promise<Response> {
   // `taggedSource`. The subsequent `close` on `upstreamNodeStream` is then a
   // cascaded effect of our own teardown, NOT a real upstream failure — so
   // we must NOT tag it as a fetch-body error, or local validation /
-  // extraction errors would be masked as 502 fetch_failed.
+  // extraction errors would be masked as fetch_failed.
   let localTeardownInitiated = false;
   upstreamNodeStream.on("end", () => {
     upstreamEnded = true;
@@ -808,6 +1209,19 @@ async function handleMigrationImportFromUrl(req: Request): Promise<Response> {
     taggedSource.destroy(err);
   });
   upstreamNodeStream.pipe(taggedSource);
+  // Absorb stream errors on `taggedSource`. `streamCommitImport` does
+  // several `await`s (workspace recovery, temp-dir mkdir) before
+  // `parseVBundleStream(source)` attaches its own `source.on('error')`
+  // listener. If the upstream socket is destroyed during that window,
+  // the `upstreamNodeStream.on('close')` handler above calls
+  // `taggedSource.destroy(err)` with no listener attached yet and the
+  // error surfaces as unhandled. We don't need to act on it here — the
+  // `kFetchBodyTornDown` flag has already been latched on the stream,
+  // and the post-import branch below (`wasFetchBodyTornDown(taggedSource)`)
+  // maps the failure to `fetch_failed`. Register this absorber
+  // unconditionally so there is always at least one `'error'` listener
+  // on the wrapper for the lifetime of the stream.
+  taggedSource.on("error", () => {});
   // Propagate wrapper teardown back to the upstream fetch body. When the
   // streaming importer hits a validation/extraction error, it destroys
   // `source` (which is `taggedSource`). Without this listener the
@@ -817,8 +1231,8 @@ async function handleMigrationImportFromUrl(req: Request): Promise<Response> {
   // (malformed bundle, hash mismatch, size cap, etc.). We set
   // `localTeardownInitiated` BEFORE destroying upstream so the resulting
   // cascaded `close` on `upstreamNodeStream` isn't misclassified as a real
-  // upstream failure (which would return 502 fetch_failed and mask the
-  // actual validation error).
+  // upstream failure (which would return fetch_failed and mask the actual
+  // validation error).
   taggedSource.on("close", () => {
     if (!upstreamNodeStream.destroyed) {
       localTeardownInitiated = true;
@@ -867,10 +1281,10 @@ async function handleMigrationImportFromUrl(req: Request): Promise<Response> {
         },
         "Upstream body stream failed mid-import",
       );
-      return Response.json(
-        { success: false, reason: "fetch_failed" },
-        { status: 502 },
-      );
+      throw new GcsImportError({
+        code: "fetch_failed",
+        message: err instanceof Error ? err.message : String(err),
+      });
     }
     log.error(
       {
@@ -880,11 +1294,10 @@ async function handleMigrationImportFromUrl(req: Request): Promise<Response> {
       },
       "streamCommitImport threw during URL-body import",
     );
-    return httpError(
-      "INTERNAL_ERROR",
-      err instanceof Error ? err.message : "Unexpected import error",
-      500,
-    );
+    throw new GcsImportError({
+      code: "extraction_failed",
+      message: err instanceof Error ? err.message : "Unexpected import error",
+    });
   }
 
   if (!result.ok) {
@@ -902,10 +1315,10 @@ async function handleMigrationImportFromUrl(req: Request): Promise<Response> {
         },
         "Upstream body stream failed mid-import (detected via result)",
       );
-      return Response.json(
-        { success: false, reason: "fetch_failed" },
-        { status: 502 },
-      );
+      throw new GcsImportError({
+        code: "fetch_failed",
+        message: "Upstream body stream failed mid-import",
+      });
     }
     log.warn(
       {
@@ -915,7 +1328,28 @@ async function handleMigrationImportFromUrl(req: Request): Promise<Response> {
       },
       "streamCommitImport returned failure during URL-body import",
     );
-    return importCommitFailureResponse(result);
+    if (result.reason === "validation_failed") {
+      throw new GcsImportError({
+        code: "validation_failed",
+        message: "Bundle validation failed",
+        reason: result.reason,
+        errors: result.errors,
+      });
+    }
+    if (result.reason === "extraction_failed") {
+      throw new GcsImportError({
+        code: "extraction_failed",
+        message: result.message,
+        reason: result.reason,
+      });
+    }
+    // write_failed
+    throw new GcsImportError({
+      code: "write_failed",
+      message: result.message,
+      reason: result.reason,
+      partial_report: result.partial_report,
+    });
   }
 
   // Merge any warnings accumulated by the credential-import callback into
@@ -949,7 +1383,134 @@ async function handleMigrationImportFromUrl(req: Request): Promise<Response> {
     "Migration import from URL complete",
   );
 
-  return importCommitSuccessResponse(result.report, credentialsImported);
+  return credentialsImported
+    ? { ...result.report, credentialsImported }
+    : { ...result.report };
+}
+
+/**
+ * Handle a JSON `{ "url": "..." }` body on POST /v1/migrations/import.
+ *
+ * Thin wrapper around `runGcsImport` that preserves the legacy synchronous
+ * Response shapes. `handleMigrationImportFromGcs` below uses the same helper
+ * asynchronously via the migration-job registry.
+ */
+async function handleMigrationImportFromUrl(
+  body: Record<string, unknown> | undefined,
+): Promise<unknown> {
+  const parsed = MigrationImportUrlBody.safeParse(body);
+  if (!parsed.success) {
+    throw new BadRequestError(
+      "Request body must be { url: string } with a non-empty url",
+    );
+  }
+
+  try {
+    const summary = await runGcsImport(parsed.data.url);
+    const { credentialsImported, ...report } = summary;
+    return importCommitSuccessResult(report, credentialsImported);
+  } catch (err) {
+    throwGcsImportError(err);
+  }
+}
+
+/**
+ * Map a `runGcsImport` error (or any other thrown value) to a thrown
+ * RouteError subclass or a plain-object error body. Always throws —
+ * callers should invoke this in a catch block.
+ */
+function throwGcsImportError(err: unknown): never {
+  if (err instanceof GcsImportError) {
+    if (err.code === "invalid_url") {
+      throw new BadRequestError(err.message);
+    }
+    if (err.code === "fetch_failed") {
+      throw new BadGatewayError(
+        err.upstreamStatus
+          ? `Upstream fetch returned ${err.upstreamStatus}`
+          : err.message,
+      );
+    }
+    if (err.code === "validation_failed") {
+      // Validation failure is not an HTTP error — return structured body
+      // with 200 (same as raw-bytes validate path).
+      throw new BadRequestError(
+        JSON.stringify({
+          success: false,
+          reason: "validation_failed",
+          errors: err.errors ?? [],
+        }),
+      );
+    }
+    if (err.code === "extraction_failed") {
+      throw new InternalError(err.message);
+    }
+    // write_failed
+    throw new InternalError(err.message);
+  }
+
+  log.error({ err }, "Unexpected error from runGcsImport");
+  throw new InternalError(
+    err instanceof Error ? err.message : "Unexpected import error",
+  );
+}
+
+/**
+ * POST /v1/migrations/import-from-gcs
+ *
+ * Kick off an async bundle import from a signed GCS URL. Returns 202 with a
+ * `job_id` the caller can poll via `GET /v1/migrations/jobs/:job_id`
+ * (PR 4). 409 if another import is already pending or running.
+ *
+ * Auth: Requires settings.write scope. Allowed for actor, svc_gateway, svc_daemon, local.
+ */
+export async function handleMigrationImportFromGcs({ body }: RouteHandlerArgs) {
+  const parsed = MigrationImportFromGcsBody.safeParse(body);
+  if (!parsed.success) {
+    throw new BadRequestError(
+      "Request body must be { bundle_url: string } with a valid URL",
+    );
+  }
+
+  const { bundle_url } = parsed.data;
+
+  // Synchronously validate the GCS URL before consuming the single
+  // in-flight import slot.
+  const validated = validateGcsSignedUrl(bundle_url, urlValidatorOptions);
+  if (!validated.ok) {
+    log.warn(
+      { reason: validated.reason },
+      "Rejected migration import-from-gcs bundle URL",
+    );
+    throw new RouteError(
+      `Invalid bundle URL: ${validated.reason}`,
+      "invalid_bundle_url",
+      400,
+    );
+  }
+
+  try {
+    const job = migrationJobs.startJob("import", async (jobRecord) =>
+      runGcsImport(bundle_url, jobRecord.id),
+    );
+    return {
+      job_id: job.id,
+      status: "pending" as const,
+      type: "import" as const,
+    };
+  } catch (err) {
+    if (err instanceof JobAlreadyInProgressError) {
+      throw new RouteError(
+        `Import already in progress: ${err.existingJobId}`,
+        "import_in_progress",
+        409,
+      );
+    }
+    log.error({ err }, "Unexpected error scheduling import-from-gcs job");
+    throw new InternalError(
+      err instanceof Error ? err.message : "Unexpected import error",
+    );
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -1078,178 +1639,277 @@ function appendNewerMigrationWarningsIfAny(report: ImportCommitReport): void {
 }
 
 /**
- * Build a success Response from an ImportCommitReport. The report fields
- * are spread at the top level, with an optional `credentialsImported`
- * summary alongside.
+ * Build a success result from an ImportCommitReport.
  */
-function importCommitSuccessResponse(
+function importCommitSuccessResult(
   report: ImportCommitReport,
   credentialsImported: CredentialImportSummary | undefined,
-): Response {
-  return Response.json({
+): unknown {
+  return {
     ...report,
     ...(credentialsImported ? { credentialsImported } : {}),
-  });
+  };
 }
 
 /**
- * Map an `ImportCommitResult` failure to the Response shape callers of
- * `POST /v1/migrations/import` depend on. Status codes and body shapes
- * are part of the public contract and must remain stable.
+ * Map an `ImportCommitResult` failure to a thrown error or a plain-object
+ * error body. Status codes and body shapes are part of the public contract
+ * and must remain stable.
  */
-function importCommitFailureResponse(
+function throwImportCommitFailure(
   result: Extract<ImportCommitResult, { ok: false }>,
-): Response {
+): never {
   if (result.reason === "validation_failed") {
-    return Response.json({
-      success: false,
-      reason: "validation_failed",
-      errors: result.errors,
-    });
+    // Validation failure uses 400 — structured body with error details
+    throw new BadRequestError(
+      JSON.stringify({
+        success: false,
+        reason: "validation_failed",
+        errors: result.errors,
+      }),
+    );
   }
 
   if (result.reason === "extraction_failed") {
-    return Response.json(
-      {
-        success: false,
-        reason: "extraction_failed",
-        message: result.message,
-      },
-      { status: 500 },
-    );
+    throw new InternalError(result.message);
   }
 
   // write_failed
-  return Response.json(
-    {
-      success: false,
-      reason: "write_failed",
-      message: result.message,
-      ...(result.partial_report
-        ? { partial_report: result.partial_report }
-        : {}),
-    },
-    { status: 500 },
-  );
+  throw new InternalError(result.message);
+}
+
+// ---------------------------------------------------------------------------
+// GET /v1/migrations/jobs/:job_id
+// ---------------------------------------------------------------------------
+
+/**
+ * GET /v1/migrations/jobs/:job_id
+ *
+ * Returns the current status of a migration job tracked by
+ * `MigrationJobRegistry`. The response shape is a discriminated union on
+ * `status`:
+ *
+ *   - `{ job_id, type, status: "processing" }`
+ *     Covers both the internal `pending` and `running` states — collapsed
+ *     into a single wire value to match the platform's transport shape used
+ *     by `ExportStatusProcessingSerializer` / `ImportStatusProcessingSerializer`.
+ *   - `{ job_id, type, status: "complete", result }`
+ *   - `{ job_id, type, status: "failed", error, error_code, upstream_status? }`
+ *
+ * 404 `{ error: { code: "job_not_found" } }` when no job matches the id.
+ */
+export async function handleMigrationJobStatus({
+  pathParams,
+}: RouteHandlerArgs) {
+  const jobId = pathParams?.job_id;
+  if (!jobId) {
+    throw new BadRequestError("Missing job_id path parameter");
+  }
+
+  const job = migrationJobs.getJob(jobId);
+  if (job === null) {
+    throw new NotFoundError("Job not found");
+  }
+
+  if (job.status === "complete") {
+    return {
+      job_id: job.id,
+      type: job.type,
+      status: "complete",
+      result: job.result,
+    };
+  }
+
+  if (job.status === "failed") {
+    const error = job.error;
+    const result: Record<string, unknown> = {
+      job_id: job.id,
+      type: job.type,
+      status: "failed",
+      error: error?.message ?? "unknown",
+      error_code: error?.code ?? "unknown",
+    };
+    if (error?.upstreamStatus !== undefined) {
+      result.upstream_status = error.upstreamStatus;
+    }
+    return result;
+  }
+
+  // pending or running — collapse to the platform's "processing" wire value.
+  return {
+    job_id: job.id,
+    type: job.type,
+    status: "processing",
+  };
 }
 
 // ---------------------------------------------------------------------------
 // Route definitions
 // ---------------------------------------------------------------------------
 
-export function migrationRouteDefinitions(): RouteDefinition[] {
-  return [
-    {
-      endpoint: "migrations/validate",
-      method: "POST",
-      summary: "Validate a .vbundle archive",
-      description:
-        "Upload a .vbundle archive for validation. Accepts raw binary or multipart form data.",
-      tags: ["migrations"],
-      responseBody: z.object({
-        is_valid: z.boolean(),
-        errors: z.array(z.unknown()),
-        manifest: z.object({}).passthrough(),
-      }),
-      handler: async ({ req }) => handleMigrationValidate(req),
+export const ROUTES: RouteDefinition[] = [
+  {
+    operationId: "migrations_validate_post",
+    endpoint: "migrations/validate",
+    method: "POST",
+    summary: "Validate a .vbundle archive",
+    description:
+      "Upload a .vbundle archive for validation. Accepts raw binary or multipart form data.",
+    tags: ["migrations"],
+    responseBody: z.object({
+      is_valid: z.boolean(),
+      errors: z.array(z.unknown()),
+      manifest: z.object({}).passthrough(),
+    }),
+    handler: handleMigrationValidate,
+  },
+  {
+    operationId: "migrations_export_post",
+    endpoint: "migrations/export",
+    method: "POST",
+    summary: "Export a .vbundle archive",
+    description:
+      "Generate and download a .vbundle archive of the assistant's data. Optional JSON body for metadata.",
+    tags: ["migrations"],
+    requestBody: z.object({
+      description: z.string().describe("Human-readable export description"),
+    }),
+    handler: handleMigrationExport,
+  },
+  {
+    operationId: "migrations_importpreflight_post",
+    endpoint: "migrations/import-preflight",
+    method: "POST",
+    summary: "Dry-run import analysis",
+    description:
+      "Validate a .vbundle archive and return a report of what would change on import without modifying data.",
+    tags: ["migrations"],
+    responseBody: z.object({
+      can_import: z.boolean(),
+      summary: z.object({}).passthrough(),
+      files: z.array(z.unknown()),
+      conflicts: z.array(z.unknown()),
+      manifest: z.object({}).passthrough(),
+    }),
+    handler: handleMigrationImportPreflight,
+  },
+  {
+    operationId: "migrations_import_post",
+    endpoint: "migrations/import",
+    method: "POST",
+    summary: "Import a .vbundle archive",
+    description:
+      "Commit a .vbundle archive import to disk — destructive. Accepts the bundle as raw bytes (application/octet-stream), multipart/form-data, or a JSON body with `{ url }` carrying a signed URL the daemon fetches.",
+    tags: ["migrations"],
+    requestBody: z.object({
+      url: z
+        .string()
+        .url()
+        .describe(
+          "A signed GCS URL pointing to the .vbundle archive (JSON body path only).",
+        ),
+    }),
+    additionalResponses: {
+      "502": {
+        description: "Upstream fetch failed (URL body only).",
+      },
     },
-    {
-      endpoint: "migrations/export",
-      method: "POST",
-      summary: "Export a .vbundle archive",
-      description:
-        "Generate and download a .vbundle archive of the assistant's data. Optional JSON body for metadata.",
-      tags: ["migrations"],
-      requestBody: z.object({
-        description: z.string().describe("Human-readable export description"),
-      }),
-      handler: async ({ req }) => handleMigrationExport(req),
+    responseBody: z.object({
+      success: z.boolean(),
+      summary: z.object({}).passthrough(),
+      files: z.array(z.unknown()),
+      manifest: z.object({}).passthrough(),
+      warnings: z.array(z.unknown()),
+    }),
+    handler: handleMigrationImport,
+  },
+  {
+    operationId: "migrations_exporttogcs_post",
+    endpoint: "migrations/export-to-gcs",
+    method: "POST",
+    summary: "Start an async export streamed to a GCS signed URL",
+    description:
+      "Kick off a background export job that PUTs a freshly-built .vbundle archive to the supplied GCS signed URL. Returns 202 with a job_id the caller can poll via the job-status endpoint. Fails fast with 409 if another export job is already pending or running.",
+    tags: ["migrations"],
+    requestBody: z.object({
+      upload_url: z
+        .string()
+        .url()
+        .describe("Signed GCS PUT URL that receives the exported bundle."),
+      description: z
+        .string()
+        .optional()
+        .describe("Human-readable export description."),
+    }),
+    responseStatus: "202",
+    responseBody: z.object({
+      job_id: z.string(),
+      status: z.literal("pending"),
+      type: z.literal("export"),
+    }),
+    handler: handleMigrationExportToGcs,
+  },
+  {
+    operationId: "migrations_importfromgcs_post",
+    endpoint: "migrations/import-from-gcs",
+    method: "POST",
+    summary: "Start an async .vbundle import from a signed GCS URL",
+    description:
+      "Schedule a background import job that fetches the bundle at `bundle_url` and streams it through the importer. Returns 202 with a `job_id`; poll `GET /v1/migrations/jobs/{job_id}` for status. 409 if another import is already in flight.",
+    tags: ["migrations"],
+    requestBody: z.object({
+      bundle_url: z.string().url(),
+    }),
+    responseStatus: "202",
+    responseBody: z.object({
+      job_id: z.string(),
+      status: z.literal("pending"),
+      type: z.literal("import"),
+    }),
+    additionalResponses: {
+      "409": {
+        description: "Another import job is already pending or running.",
+      },
     },
-    {
-      endpoint: "migrations/import-preflight",
-      method: "POST",
-      summary: "Dry-run import analysis",
-      description:
-        "Validate a .vbundle archive and return a report of what would change on import without modifying data.",
-      tags: ["migrations"],
-      responseBody: z.object({
-        can_import: z.boolean(),
-        summary: z.object({}).passthrough(),
-        files: z.array(z.unknown()),
-        conflicts: z.array(z.unknown()),
-        manifest: z.object({}).passthrough(),
+    handler: handleMigrationImportFromGcs,
+  },
+  {
+    operationId: "migrations_jobs_by_job_id_get",
+    endpoint: "migrations/jobs/:job_id",
+    method: "GET",
+    summary: "Get migration job status",
+    description:
+      "Return the current status of an async migration job (export or import). The response discriminates on `status`: `processing` (pending or running), `complete` (with `result`), or `failed` (with `error`, `error_code`, optional `upstream_status`).",
+    tags: ["migrations"],
+    pathParams: [
+      { name: "job_id", description: "The migration job ID to query." },
+    ],
+    responseBody: z.discriminatedUnion("status", [
+      z.object({
+        job_id: z.string(),
+        type: z.enum(["export", "import"]),
+        status: z.literal("processing"),
       }),
-      handler: async ({ req }) => handleMigrationImportPreflight(req),
-    },
-    {
-      endpoint: "migrations/import",
-      method: "POST",
-      summary: "Import a .vbundle archive",
-      description:
-        "Commit a .vbundle archive import to disk — destructive. Accepts the bundle as raw bytes (application/octet-stream), multipart/form-data, or a JSON body carrying a signed URL the daemon fetches and streams through the importer.",
-      tags: ["migrations"],
-      requestBodies: [
-        {
-          contentType: "application/octet-stream",
-          schema: {
-            type: "string",
-            format: "binary",
-            description: "Raw .vbundle archive bytes.",
-          },
-        },
-        {
-          contentType: "multipart/form-data",
-          schema: {
-            type: "object",
-            properties: {
-              file: {
-                type: "string",
-                format: "binary",
-                description: "The .vbundle archive uploaded as a file field.",
-              },
-            },
-            required: ["file"],
-          },
-        },
-        {
-          contentType: "application/json",
-          schema: {
-            type: "object",
-            properties: {
-              url: {
-                type: "string",
-                format: "uri",
-                description:
-                  "A signed GCS URL pointing to the .vbundle archive. The daemon fetches the URL and streams the body through the importer.",
-              },
-            },
-            required: ["url"],
-          },
-        },
-      ],
-      additionalResponses: {
-        "502": {
-          description:
-            "Upstream fetch failed (URL body only). Body shape: { success: false, reason: 'fetch_failed', upstream_status?: number }.",
-          schema: {
-            type: "object",
-            properties: {
-              success: { type: "boolean" },
-              reason: { type: "string", enum: ["fetch_failed"] },
-              upstream_status: { type: "integer" },
-            },
-            required: ["success", "reason"],
-          },
-        },
-      },
-      responseBody: z.object({
-        success: z.boolean(),
-        summary: z.object({}).passthrough(),
-        files: z.array(z.unknown()),
-        manifest: z.object({}).passthrough(),
-        warnings: z.array(z.unknown()),
+      z.object({
+        job_id: z.string(),
+        type: z.enum(["export", "import"]),
+        status: z.literal("complete"),
+        result: z.unknown(),
+      }),
+      z.object({
+        job_id: z.string(),
+        type: z.enum(["export", "import"]),
+        status: z.literal("failed"),
+        error: z.string(),
+        error_code: z.string(),
+        upstream_status: z.number().int().optional(),
       }),
-      handler: async ({ req }) => handleMigrationImport(req),
+    ]),
+    additionalResponses: {
+      "404": {
+        description: "No job matches the given id.",
+      },
     },
-  ];
-}
+    handler: handleMigrationJobStatus,
+  },
+];