@openparachute/vault 0.7.4 → 0.7.5-rc.5

package/src/mirror-import.ts

@@ -18,9 +18,10 @@
  *   - Creates a temp dir (`os.tmpdir() + /parachute-import-<rand>`).
  *   - Resolves the authed clone URL (stored credentials, supplied per-call
  *     PAT, or none).
- *   - Shells `git clone --depth 1 <authedUrl> <tempDir>` with a 60s
- *     timeout and `GIT_TERMINAL_PROMPT=0` so bad credentials fail fast
- *     rather than blocking on a stdin prompt.
+ *   - Shells `git clone --depth 1 --progress <authedUrl> <tempDir>` with
+ *     `GIT_TERMINAL_PROMPT=0` so bad credentials fail fast rather than
+ *     blocking on a stdin prompt. Bounded by a STALL timeout (no progress
+ *     output for 10 min), not a wall-clock one — see `cloneTimeoutMs`.
  *   - Validates the clone looks like a vault export — `.parachute/vault.yaml`
  *     must be present. Refuses with a clear error otherwise.
  *   - On `mode: "replace"`: wipes notes + tags via `store.deleteNote()` /
@@ -128,8 +129,28 @@ export interface ImportOpts {
   spawn?: GitSpawn;
   /** Override the post-clone import path (test seam — assume cloned dir is a vault export). */
   importer?: typeof importPortableVault;
-  /** Override the clone timeout (default 60s; test seam to shorten). */
+  /**
+   * Absolute wall-clock cap on the clone. **Defaults to 0 — disabled.**
+   *
+   * This used to default to 60s, which is why importing any vault bigger than
+   * a demo failed with "git clone timed out after 60s" (vault#640). A clone's
+   * duration is a function of vault size and link speed; there is no honest
+   * wall-clock number that fits both a 200-note vault and a 40k-note one. The
+   * bound that actually distinguishes "big" from "broken" is
+   * `cloneStallTimeoutMs` below. Tests set this to force the timeout branch.
+   */
   cloneTimeoutMs?: number;
+  /**
+   * How long the clone may emit NO progress output before we call it wedged.
+   * Defaults to `DEFAULT_CLONE_STALL_TIMEOUT_MS` (10 min); `0` disables.
+   */
+  cloneStallTimeoutMs?: number;
+  /**
+   * Progress sink. Called as the import moves between stages and as git
+   * reports clone progress. The job registry wires this to the record the
+   * status endpoint serves; direct callers can omit it.
+   */
+  onProgress?: (update: ImportProgress) => void;
   /**
    * Override the git-presence probe (test seam — defaults to `Bun.which`).
    * Inject a fn returning `null` to exercise the git-not-installed path.
@@ -137,6 +158,31 @@ export interface ImportOpts {
   which?: (cmd: string) => string | null;
 }
 
+/**
+ * Default stall bound: ten minutes of total silence from `git clone`.
+ *
+ * Sized off what git actually does — with `--progress` it repaints the
+ * counter every few hundred milliseconds while it's moving, so ten minutes of
+ * nothing means the transfer is dead, not slow. Generous enough to cover a
+ * remote that's slow to enumerate objects on a very large repo before the
+ * first byte lands.
+ */
+export const DEFAULT_CLONE_STALL_TIMEOUT_MS = 10 * 60_000;
+
+/** Coarse stage the import is in. Drives the SPA's progress copy. */
+export type ImportStage = "cloning" | "importing" | "syncing";
+
+/** A progress tick handed to `ImportOpts.onProgress`. */
+export interface ImportProgress {
+  stage: ImportStage;
+  /**
+   * Human-readable detail for the current stage — for `cloning` this is the
+   * most recent `git --progress` line ("Receiving objects:  47% …").
+   * Absent when the stage has no finer detail to report.
+   */
+  detail?: string;
+}
+
 /**
  * Counts + warnings returned to the HTTP caller. `notes_imported` totals
  * created+updated so the operator sees a single "imported N notes" number
@@ -185,13 +231,38 @@ export interface ImportResult {
  */
 export type GitSpawn = (
   argv: string[],
-  options: { cwd?: string; timeoutMs: number },
+  options: GitSpawnOptions,
 ) => Promise<GitSpawnResult>;
 
+export interface GitSpawnOptions {
+  cwd?: string;
+  /**
+   * Wall-clock cap on the whole command. `0` disables it — the default for
+   * clones (see `ImportOpts.cloneTimeoutMs`). Tests pass a small number to
+   * exercise the timeout branch.
+   */
+  timeoutMs: number;
+  /**
+   * Cap on the gap BETWEEN progress lines. This — not `timeoutMs` — is what
+   * bounds a real clone: a 4 GB vault legitimately takes an hour, but a clone
+   * that has emitted nothing for 10 minutes is wedged (dead TCP connection,
+   * auth prompt we failed to suppress, remote hang). `0` disables it.
+   */
+  stallTimeoutMs?: number;
+  /**
+   * Called for each line git writes to stderr, which with `--progress` is
+   * where "Receiving objects:  47% (…)" lands. Drives the job's live progress
+   * detail and resets the stall timer.
+   */
+  onProgress?: (line: string) => void;
+}
+
 export interface GitSpawnResult {
   exitCode: number;
   stderr: string;
   timedOut: boolean;
+  /** True when the kill came from the stall timer rather than `timeoutMs`. */
+  stalled?: boolean;
 }
 
 // ---------------------------------------------------------------------------
@@ -344,8 +415,27 @@ export function authedCloneUrl(
 // ---------------------------------------------------------------------------
 
 /**
- * Run a git command with a hard timeout + non-interactive env. Returns
- * exit code + stderr text + timeout flag.
+ * Run a git command with a non-interactive env, streaming stderr so the
+ * caller sees progress while it runs. Returns exit code + stderr text +
+ * timeout flags.
+ *
+ * **Why stderr is STREAMED, not buffered (vault#640).** The previous
+ * implementation awaited `proc.exited` and only then drained `proc.stderr`.
+ * That made progress structurally unobservable — the import was a black box
+ * until it finished — and it forced the caller to bound the clone with a
+ * wall-clock timeout, because a wedged clone and a slow one look identical
+ * when you can't see output. A 60s cap was the result, and it made vaults
+ * above a few thousand notes simply un-importable.
+ *
+ * Streaming lets us bound the RIGHT thing: the gap between progress lines
+ * (`stallTimeoutMs`). A big clone runs as long as it needs to as long as it's
+ * still moving; a wedged one dies in minutes. `timeoutMs` remains as an
+ * optional absolute ceiling (0 = disabled) mainly so tests can force the
+ * timeout branch deterministically.
+ *
+ * Draining stderr concurrently also fixes a latent deadlock: git blocks
+ * writing to a full stderr pipe, so a clone chatty enough to fill the pipe
+ * buffer would hang forever against the old await-then-read order.
  */
 export const defaultGitSpawn: GitSpawn = async (argv, options) => {
   let proc;
@@ -375,20 +465,74 @@ export const defaultGitSpawn: GitSpawn = async (argv, options) => {
     throw err;
   }
   let timedOut = false;
-  const timer = setTimeout(() => {
-    timedOut = true;
+  let stalled = false;
+  const kill = () => {
     try {
       proc.kill();
     } catch {
       // already exited
     }
-  }, options.timeoutMs);
+  };
+
+  const absoluteTimer =
+    options.timeoutMs > 0
+      ? setTimeout(() => {
+          timedOut = true;
+          kill();
+        }, options.timeoutMs)
+      : null;
+
+  // Stall timer — rearmed on every line git emits. This is the real guard.
+  let stallTimer: ReturnType<typeof setTimeout> | null = null;
+  const stallMs = options.stallTimeoutMs ?? 0;
+  const armStall = () => {
+    if (stallMs <= 0) return;
+    if (stallTimer) clearTimeout(stallTimer);
+    stallTimer = setTimeout(() => {
+      stalled = true;
+      timedOut = true;
+      kill();
+    }, stallMs);
+  };
+  armStall();
+
+  // Drain stderr line-by-line. git writes progress with `\r` (carriage
+  // return, no newline) so it can repaint one line in a terminal — split on
+  // BOTH so "Receiving objects: 47%" surfaces as it happens rather than
+  // arriving as one giant line at the end.
+  const collected: string[] = [];
+  let pending = "";
+  const emit = (line: string) => {
+    const trimmed = line.trim();
+    if (trimmed.length === 0) return;
+    collected.push(trimmed);
+    armStall();
+    try {
+      options.onProgress?.(trimmed);
+    } catch {
+      // A throwing progress callback must never take down the clone.
+    }
+  };
+  const drain = (async () => {
+    const decoder = new TextDecoder();
+    for await (const chunk of proc.stderr) {
+      pending += decoder.decode(chunk, { stream: true });
+      const parts = pending.split(/[\r\n]+/);
+      pending = parts.pop() ?? "";
+      for (const part of parts) emit(part);
+    }
+    if (pending.length > 0) emit(pending);
+  })().catch(() => {
+    // Stream errors (killed process mid-read) aren't interesting — the exit
+    // code and the timeout flags already describe what happened.
+  });
+
   const exitCode = await proc.exited;
-  clearTimeout(timer);
-  const stderr = new TextDecoder()
-    .decode(await new Response(proc.stderr).arrayBuffer())
-    .trim();
-  return { exitCode, stderr, timedOut };
+  await drain;
+  if (absoluteTimer) clearTimeout(absoluteTimer);
+  if (stallTimer) clearTimeout(stallTimer);
+
+  return { exitCode, stderr: collected.join("\n").trim(), timedOut, stalled };
 };
 
 // ---------------------------------------------------------------------------
@@ -427,7 +571,12 @@ export async function cloneAndImport(opts: ImportOpts): Promise<ImportResult> {
   const spawn = opts.spawn ?? defaultGitSpawn;
   const importer = opts.importer ?? importPortableVault;
   const workDirRoot = opts.workDirRoot ?? tmpdir();
-  const cloneTimeoutMs = opts.cloneTimeoutMs ?? 60_000;
+  // 0 = no absolute ceiling; the stall bound is the real guard. See the
+  // `cloneTimeoutMs` docstring on ImportOpts for why the old 60s default was
+  // wrong rather than merely too small.
+  const cloneTimeoutMs = opts.cloneTimeoutMs ?? 0;
+  const cloneStallTimeoutMs =
+    opts.cloneStallTimeoutMs ?? DEFAULT_CLONE_STALL_TIMEOUT_MS;
 
   const authResult = authedCloneUrl(opts.remoteUrl, opts.auth, opts.vaultName);
   if (!authResult) {
@@ -440,15 +589,25 @@ export async function cloneAndImport(opts: ImportOpts): Promise<ImportResult> {
 
   const tempDir = mkdtempSync(join(workDirRoot, "parachute-import-"));
   try {
+    opts.onProgress?.({ stage: "cloning" });
     const cloneResult = await spawn(
-      ["git", "clone", "--depth", "1", authedUrl, tempDir],
-      { timeoutMs: cloneTimeoutMs },
+      // `--progress` forces the progress meter even though our stderr is a
+      // pipe, not a tty. Without it git stays silent, the stall timer has
+      // nothing to observe, and the operator watches a spinner with no
+      // information for the length of a multi-GB transfer.
+      ["git", "clone", "--depth", "1", "--progress", authedUrl, tempDir],
+      {
+        timeoutMs: cloneTimeoutMs,
+        stallTimeoutMs: cloneStallTimeoutMs,
+        onProgress: (line) => opts.onProgress?.({ stage: "cloning", detail: line }),
+      },
     );
     if (cloneResult.timedOut) {
-      throw new CloneFailedError(
-        `git clone timed out after ${Math.floor(cloneTimeoutMs / 1000)}s. ` +
-          `Check the network connection or try a shallower remote. URL: ${redactRemoteUrl(opts.remoteUrl)}`,
-      );
+      const why = cloneResult.stalled
+        ? `git clone stalled — no progress for ${Math.floor(cloneStallTimeoutMs / 60_000)} minutes. ` +
+          `The remote stopped responding, or the credential was rejected without an error.`
+        : `git clone exceeded its ${Math.floor(cloneTimeoutMs / 1000)}s limit.`;
+      throw new CloneFailedError(`${why} URL: ${redactRemoteUrl(opts.remoteUrl)}`);
     }
     if (cloneResult.exitCode !== 0) {
       // Redact any leaked URLs in stderr — git error messages echo them.
@@ -469,6 +628,7 @@ export async function cloneAndImport(opts: ImportOpts): Promise<ImportResult> {
     // Delegate to the importer. `blowAway: true` for replace mode triggers
     // the wipe-then-import path (deletes notes via the public store API
     // so hooks fire); `false` for merge does upsert-by-id.
+    opts.onProgress?.({ stage: "importing" });
     const stats: ImportStats = await importer(opts.store, {
       inDir: tempDir,
       blowAway: opts.mode === "replace",

package/src/mirror-routes.test.ts

@@ -34,6 +34,7 @@ import {
   handleAuthPat,
   handleMirrorGet,
   handleMirrorImport,
+  handleMirrorImportStatus,
   handleMirrorPushNow,
   handleMirrorPut,
   handleMirrorRunNow,
@@ -42,6 +43,7 @@ import {
   _resetImportInFlightForTest,
   type GitSpawn,
 } from "./mirror-import.ts";
+import { _resetImportJobsForTest, type ImportJob } from "./mirror-import-jobs.ts";
 import { writeVaultConfig } from "./config.ts";
 import { clearVaultStoreCache } from "./vault-store.ts";
 import { exportVaultToDir } from "../core/src/portable-md.ts";
@@ -1984,6 +1986,7 @@ describe("handleMirrorImport", () => {
     if (home) fs.rmSync(home, { recursive: true, force: true });
     if (fixture) fs.rmSync(fixture, { recursive: true, force: true });
     _resetImportInFlightForTest();
+    _resetImportJobsForTest();
     clearVaultStoreCache();
   });
 
@@ -2034,6 +2037,7 @@ describe("handleMirrorImport", () => {
       body: JSON.stringify({
         remote_url: "https://github.com/a/b.git",
         mode: "merge",
+        wait: true,
         credentials: { kind: "pat", token: "" },
       }),
     });
@@ -2051,6 +2055,7 @@ describe("handleMirrorImport", () => {
       body: JSON.stringify({
         remote_url: "https://github.com/a/b.git",
         mode: "merge",
+        wait: true,
         credentials: { kind: "magic" },
       }),
     });
@@ -2069,6 +2074,7 @@ describe("handleMirrorImport", () => {
       body: JSON.stringify({
         remote_url: "https://github.com/a/b.git",
         mode: "merge",
+        wait: true,
         credentials: { kind: "none" },
       }),
     });
@@ -2100,6 +2106,7 @@ describe("handleMirrorImport", () => {
       body: JSON.stringify({
         remote_url: "https://github.com/a/b.git",
         mode: "replace",
+        wait: true,
         credentials: { kind: "none" },
       }),
     });
@@ -2121,6 +2128,7 @@ describe("handleMirrorImport", () => {
       body: JSON.stringify({
         remote_url: "https://github.com/a/b.git",
         mode: "merge",
+        wait: true,
         credentials: { kind: "pat", token: "ghp_secret_xyz" },
       }),
     });
@@ -2143,6 +2151,7 @@ describe("handleMirrorImport", () => {
       body: JSON.stringify({
         remote_url: "https://github.com/a/b.git",
         mode: "merge",
+        wait: true,
         credentials: { kind: "none" },
       }),
     });
@@ -2169,6 +2178,7 @@ describe("handleMirrorImport", () => {
       body: JSON.stringify({
         remote_url: "https://github.com/a/b.git",
         mode: "merge",
+        wait: true,
         credentials: { kind: "none" },
       }),
     });
@@ -2210,6 +2220,7 @@ describe("handleMirrorImport", () => {
       body: JSON.stringify({
         remote_url: "https://github.com/a/b.git",
         mode: "merge",
+        wait: true,
         credentials: null,
       }),
     });
@@ -2246,6 +2257,7 @@ describe("handleMirrorImport", () => {
       body: JSON.stringify({
         remote_url: "https://github.com/a/b.git",
         mode: "merge",
+        wait: true,
         credentials: { kind: "pat", token: "ghp_per_call_only" },
       }),
     });
@@ -2272,6 +2284,7 @@ describe("handleMirrorImport — auto-enable sync (vault#416)", () => {
     if (home) fs.rmSync(home, { recursive: true, force: true });
     if (fixture) fs.rmSync(fixture, { recursive: true, force: true });
     _resetImportInFlightForTest();
+    _resetImportJobsForTest();
     clearVaultStoreCache();
   });
 
@@ -2286,6 +2299,7 @@ describe("handleMirrorImport — auto-enable sync (vault#416)", () => {
       body: JSON.stringify({
         remote_url: "https://github.com/aaron/my-vault.git",
         mode: "merge",
+        wait: true,
         credentials: { kind: "pat", token: "ghp_import_token_abc" },
         enable_sync: true,
       }),
@@ -2330,6 +2344,7 @@ describe("handleMirrorImport — auto-enable sync (vault#416)", () => {
       body: JSON.stringify({
         remote_url: "https://github.com/aaron/my-vault.git",
         mode: "merge",
+        wait: true,
         credentials: { kind: "pat", token: "ghp_import_token_abc" },
         enable_sync: false,
       }),
@@ -2365,6 +2380,7 @@ describe("handleMirrorImport — auto-enable sync (vault#416)", () => {
       body: JSON.stringify({
         remote_url: "https://github.com/aaron/my-vault.git",
         mode: "merge",
+        wait: true,
         credentials: { kind: "none" },
         enable_sync: true,
       }),
@@ -2392,7 +2408,12 @@ describe("handleMirrorImport — auto-enable sync (vault#416)", () => {
     expect(readCredentials("default")).toBeNull();
   });
 
-  test("enable_sync defaults to true when omitted", async () => {
+  // vault#641 — the default INVERTED. Import is a read; it must not arm a
+  // write to the source repo unless the operator says so. Pinned as its own
+  // test because the old default (ON, vault#416) was the single most dangerous
+  // thing about this flow: pulling a vault onto a new box silently repointed
+  // backup at the repo you pulled from.
+  test("enable_sync defaults to FALSE when omitted — import never arms push-back on its own", async () => {
     home = tmp("import-sync-default-");
     await bootstrapVault(home);
     fixture = await buildExportFixture();
@@ -2403,8 +2424,44 @@ describe("handleMirrorImport — auto-enable sync (vault#416)", () => {
       body: JSON.stringify({
         remote_url: "https://github.com/aaron/my-vault.git",
         mode: "merge",
-        credentials: { kind: "pat", token: "ghp_default_on_token" },
-        // enable_sync omitted — should default ON.
+        wait: true,
+        credentials: { kind: "pat", token: "ghp_default_off_token" },
+        // enable_sync omitted — must default OFF.
+      }),
+    });
+    const res = await handleMirrorImport(
+      req,
+      "default",
+      spawnCloneSuccess(fixture),
+      undefined,
+      manager,
+    );
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as {
+      sync_enabled: boolean;
+      sync_warning?: string;
+    };
+    expect(body.sync_enabled).toBe(false);
+    // Not a failure — the operator didn't ask. No scary warning either.
+    expect(body.sync_warning).toBeUndefined();
+    // The decisive assertion: nothing was wired up.
+    expect(readMirrorConfigForVault("default")?.auto_push ?? false).toBe(false);
+  });
+
+  test("enable_sync: true still opts in explicitly", async () => {
+    home = tmp("import-sync-optin-");
+    await bootstrapVault(home);
+    fixture = await buildExportFixture();
+    manager = makeSyncManager(home);
+
+    const req = new Request("http://x/import", {
+      method: "POST",
+      body: JSON.stringify({
+        remote_url: "https://github.com/aaron/my-vault.git",
+        mode: "merge",
+        wait: true,
+        enable_sync: true,
+        credentials: { kind: "pat", token: "ghp_opt_in_token" },
       }),
     });
     const res = await handleMirrorImport(
@@ -2448,6 +2505,7 @@ describe("handleMirrorImport — auto-enable sync (vault#416)", () => {
       body: JSON.stringify({
         remote_url: "https://github.com/aaron/my-vault.git",
         mode: "merge",
+        wait: true,
         credentials: { kind: "pat", token: "ghp_import_token_abc" },
         enable_sync: true,
       }),
@@ -2500,6 +2558,7 @@ describe("handleMirrorImport — auto-enable sync (vault#416)", () => {
       body: JSON.stringify({
         remote_url: "https://github.com/aaron/my-vault.git",
         mode: "merge",
+        wait: true,
         credentials: { kind: "pat", token: "ghp_import_token_abc" },
         enable_sync: true,
       }),
@@ -2555,6 +2614,7 @@ describe("handleMirrorImport — auto-enable sync (vault#416)", () => {
       body: JSON.stringify({
         remote_url: "https://github.com/aaron/my-vault.git",
         mode: "merge",
+        wait: true,
         credentials: { kind: "pat", token: "ghp_import_token_abc" },
         enable_sync: true,
         override: true,
@@ -2602,6 +2662,7 @@ describe("handleMirrorImport — auto-enable sync (vault#416)", () => {
       body: JSON.stringify({
         remote_url: "https://github.com/aaron/my-vault.git",
         mode: "merge",
+        wait: true,
         credentials: { kind: "pat", token: "ghp_same_token" },
         enable_sync: true,
       }),
@@ -2650,6 +2711,7 @@ describe("handleMirrorImport — auto-enable sync (vault#416)", () => {
       body: JSON.stringify({
         remote_url: "https://github.com/aaron/my-vault.git",
         mode: "merge",
+        wait: true,
         credentials: { kind: "pat", token: "ghp_import_token_abc" },
         enable_sync: true,
       }),
@@ -2693,6 +2755,7 @@ describe("handleMirrorImport — auto-enable sync (vault#416)", () => {
       body: JSON.stringify({
         remote_url: "https://github.com/aaron/my-vault.git",
         mode: "merge",
+        wait: true,
         credentials: { kind: "pat", token: "ghp_import_token_abc" },
         enable_sync: true,
       }),
@@ -2724,6 +2787,7 @@ describe("handleMirrorImport — auto-enable sync (vault#416)", () => {
       body: JSON.stringify({
         remote_url: "https://github.com/aaron/my-vault.git",
         mode: "merge",
+        wait: true,
         credentials: { kind: "none" },
         enable_sync: "yes",
       }),
@@ -2769,6 +2833,161 @@ function seedSiblingVault(name: string, originUrl: string): void {
   );
 }
 
+// ---------------------------------------------------------------------------
+// vault#640 — the ASYNC import transport.
+//
+// The semantic tests above (what gets imported, how sync gets wired, which
+// credential is picked) run through `wait: true`, the back-compat synchronous
+// path. That's deliberate, not laziness: both paths call the SAME `runImport`
+// closure, so transport and semantics are genuinely orthogonal and testing
+// each import behaviour twice would buy nothing. This block covers the part
+// that IS different — the job lifecycle the SPA actually drives.
+// ---------------------------------------------------------------------------
+describe("handleMirrorImport — async job transport (vault#640)", () => {
+  let home: string;
+  let fixture: string;
+
+  afterEach(() => {
+    if (home) fs.rmSync(home, { recursive: true, force: true });
+    if (fixture) fs.rmSync(fixture, { recursive: true, force: true });
+    _resetImportInFlightForTest();
+    _resetImportJobsForTest();
+    clearVaultStoreCache();
+  });
+
+  /** POST an import, asserting the 202, and hand back the job record. */
+  async function startImport(
+    spawn: GitSpawn,
+    body: Record<string, unknown> = {},
+  ): Promise<ImportJob> {
+    const req = new Request("http://x/import", {
+      method: "POST",
+      body: JSON.stringify({
+        remote_url: "https://github.com/a/b.git",
+        mode: "merge",
+        credentials: { kind: "none" },
+        ...body,
+      }),
+    });
+    const res = await handleMirrorImport(req, "default", spawn);
+    expect(res.status).toBe(202);
+    return (await res.json()) as ImportJob;
+  }
+
+  /** Poll the status route until the job leaves `running`. */
+  async function pollUntilDone(jobId: string, vault = "default"): Promise<ImportJob> {
+    for (let i = 0; i < 200; i++) {
+      const res = handleMirrorImportStatus(vault, jobId);
+      const job = (await res.json()) as ImportJob;
+      if (job.status !== "running") return job;
+      await new Promise((r) => setTimeout(r, 10));
+    }
+    throw new Error("import job never reached a terminal state");
+  }
+
+  test("POST returns 202 with a running job, not the result", async () => {
+    home = tmp("import-async-202-");
+    await bootstrapVault(home);
+    fixture = await buildExportFixture();
+
+    const job = await startImport(spawnCloneSuccess(fixture));
+    expect(job.job_id).toBeTruthy();
+    expect(job.status).toBe("running");
+    expect(job.stage).toBe("cloning");
+    expect(job.vault_name).toBe("default");
+
+    await pollUntilDone(job.job_id);
+  });
+
+  test("polling reaches succeeded and carries the import result", async () => {
+    home = tmp("import-async-ok-");
+    await bootstrapVault(home);
+    fixture = await buildExportFixture();
+
+    const started = await startImport(spawnCloneSuccess(fixture));
+    const done = await pollUntilDone(started.job_id);
+
+    expect(done.status).toBe("succeeded");
+    expect(done.finished_at).toBeTruthy();
+    expect(done.result?.notes_imported).toBe(2);
+    expect(done.error).toBeUndefined();
+  });
+
+  test("a clone failure lands on the job as clone_failed, with the token redacted", async () => {
+    home = tmp("import-async-fail-");
+    await bootstrapVault(home);
+
+    const started = await startImport(spawnCloneFail, {
+      credentials: { kind: "pat", token: "ghp_secret_xyz" },
+    });
+    const done = await pollUntilDone(started.job_id);
+
+    expect(done.status).toBe("failed");
+    expect(done.error?.error_type).toBe("clone_failed");
+    expect(JSON.stringify(done)).not.toContain("ghp_secret_xyz");
+  });
+
+  test("a second import while one is running → 409 carrying the in-flight job_id", async () => {
+    home = tmp("import-async-conflict-");
+    await bootstrapVault(home);
+    fixture = await buildExportFixture();
+
+    const first = await startImport(spawnCloneSuccess(fixture));
+    const req = new Request("http://x/import", {
+      method: "POST",
+      body: JSON.stringify({
+        remote_url: "https://github.com/a/b.git",
+        mode: "merge",
+        credentials: { kind: "none" },
+      }),
+    });
+    const res = await handleMirrorImport(req, "default", spawnCloneSuccess(fixture));
+    expect(res.status).toBe(409);
+    const body = (await res.json()) as { error_type: string; job_id?: string };
+    expect(body.error_type).toBe("concurrent_import");
+    // The second tab can attach to the running import instead of being stuck.
+    expect(body.job_id).toBe(first.job_id);
+
+    await pollUntilDone(first.job_id);
+  });
+
+  test("a finished job frees the vault for the next import", async () => {
+    home = tmp("import-async-serial-");
+    await bootstrapVault(home);
+    fixture = await buildExportFixture();
+
+    const first = await startImport(spawnCloneSuccess(fixture));
+    await pollUntilDone(first.job_id);
+
+    const second = await startImport(spawnCloneSuccess(fixture));
+    expect(second.job_id).not.toBe(first.job_id);
+    await pollUntilDone(second.job_id);
+  });
+
+  test("status is scoped to the vault — another vault's admin can't read the job", async () => {
+    home = tmp("import-async-scope-");
+    await bootstrapVault(home);
+    fixture = await buildExportFixture();
+
+    const started = await startImport(spawnCloneSuccess(fixture));
+    const res = handleMirrorImportStatus("some-other-vault", started.job_id);
+    expect(res.status).toBe(404);
+    const body = (await res.json()) as { error_type: string };
+    expect(body.error_type).toBe("job_not_found");
+
+    await pollUntilDone(started.job_id);
+  });
+
+  test("unknown job id → 404 job_not_found", async () => {
+    home = tmp("import-async-404-");
+    await bootstrapVault(home);
+    const res = handleMirrorImportStatus("default", "no-such-job");
+    expect(res.status).toBe(404);
+    const body = (await res.json()) as { error_type: string };
+    expect(body.error_type).toBe("job_not_found");
+  });
+});
+
 describe("cross-vault remote-clobber guard (vault#482)", () => {
   let home: string;
   afterEach(() => {