@openparachute/vault 0.7.4 → 0.7.5-rc.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/vault",
-  "version": "0.7.4",
+  "version": "0.7.5-rc.4",
   "description": "Agent-native knowledge graph. Notes, tags, links over MCP.",
   "module": "src/cli.ts",
   "type": "module",

package/src/mirror-import-jobs.ts

@@ -0,0 +1,197 @@
+/**
+ * In-process job registry for git imports (vault#640).
+ *
+ * **Why this exists.** `POST /vault/<name>/.parachute/mirror/import` used to
+ * run the whole clone-and-import inside the request and return the result.
+ * That shape has a hard ceiling that has nothing to do with how long the work
+ * legitimately takes:
+ *
+ *   - hub proxies the vault behind `Bun.serve({ idleTimeout: 255 })`, so any
+ *     import past ~4 minutes dies in the proxy no matter what vault does;
+ *   - browsers and intermediate proxies impose their own limits;
+ *   - a dropped connection lost the import's outcome entirely, even when the
+ *     import itself had succeeded.
+ *
+ * So the old handler papered over it with a 60s clone timeout and a docstring
+ * promising "if/when bigger vaults arrive we promote to async polling." They
+ * arrived. This is that promotion.
+ *
+ * **Shape.** POST starts a job and returns `202 { job_id }` immediately. The
+ * work continues on the server independent of the request that started it.
+ * `GET .../mirror/import/<job_id>` returns the current record; the SPA polls
+ * it for stage + progress and renders the terminal state.
+ *
+ * **Deliberately in-memory.** Jobs do not survive a vault restart, and that's
+ * the honest design rather than a shortcut: the work itself can't survive a
+ * restart either (the clone lives in a tempdir, the importer holds an open
+ * store handle), so a persisted "running" row would only ever resurrect as a
+ * lie. A restart mid-import surfaces as `job_not_found`, which the SPA reads
+ * as "the server restarted — check your vault and retry." Whatever the
+ * importer had already committed is committed; merge mode makes a retry safe.
+ *
+ * **Concurrency.** One running import per vault, enforced here so the 409
+ * lands before a tempdir is created. `cloneAndImport` keeps its own inFlight
+ * guard as the inner belt for direct (CLI / test) callers.
+ */
+
+import type {
+  ImportProgress,
+  ImportResult,
+  ImportStage,
+} from "./mirror-import.ts";
+
+/** How long a finished job stays queryable before GC. */
+export const FINISHED_JOB_TTL_MS = 60 * 60_000;
+
+/** Terminal + non-terminal job states. */
+export type ImportJobStatus = "running" | "succeeded" | "failed";
+
+/**
+ * Error detail for a failed job. Mirrors the `error_type` vocabulary the
+ * synchronous handler used to return, so the SPA's error branching is
+ * unchanged — it just reads them off the job record instead of the POST
+ * response.
+ */
+export interface ImportJobError {
+  error_type:
+    | "git_not_installed"
+    | "concurrent_import"
+    | "not_a_vault_export"
+    | "clone_failed"
+    | "internal";
+  message: string;
+}
+
+/** The record the status endpoint serves. */
+export interface ImportJob {
+  job_id: string;
+  vault_name: string;
+  status: ImportJobStatus;
+  stage: ImportStage;
+  /** Latest progress line for the current stage, when there is one. */
+  detail?: string;
+  started_at: string;
+  updated_at: string;
+  finished_at?: string;
+  /** Present iff `status === "succeeded"`. */
+  result?: ImportResult;
+  /** Present iff `status === "failed"`. */
+  error?: ImportJobError;
+}
+
+/** Thrown by `startImportJob` when this vault already has one running. */
+export class ImportJobConflictError extends Error {
+  constructor(public readonly vaultName: string) {
+    super(
+      `An import is already running for vault "${vaultName}". Wait for it to finish, or reload to watch its progress.`,
+    );
+    this.name = "ImportJobConflictError";
+  }
+}
+
+/** job_id → record. */
+const jobs = new Map<string, ImportJob>();
+/** vault name → job_id of the RUNNING job, if any. */
+const running = new Map<string, string>();
+
+/**
+ * Drop finished jobs past their TTL. Called opportunistically on every
+ * create/read rather than on a timer — a timer would keep the event loop
+ * alive and there is no correctness need for prompt collection.
+ */
+function gc(now: number): void {
+  for (const [id, job] of jobs) {
+    if (job.status === "running") continue;
+    const finished = job.finished_at ? Date.parse(job.finished_at) : 0;
+    if (Number.isFinite(finished) && now - finished > FINISHED_JOB_TTL_MS) {
+      jobs.delete(id);
+    }
+  }
+}
+
+/** The running job for a vault, or undefined. */
+export function getRunningImportJob(vaultName: string): ImportJob | undefined {
+  const id = running.get(vaultName);
+  return id ? jobs.get(id) : undefined;
+}
+
+/**
+ * Look up a job by id, scoped to a vault. The vault scope matters: the route
+ * is authorized against `vault:<name>:admin`, so an admin of vault A must not
+ * be able to read vault B's import record by guessing an id.
+ */
+export function getImportJob(
+  vaultName: string,
+  jobId: string,
+): ImportJob | undefined {
+  gc(Date.now());
+  const job = jobs.get(jobId);
+  if (!job || job.vault_name !== vaultName) return undefined;
+  return job;
+}
+
+/**
+ * Register a job and start `work` on it. Returns the initial record
+ * synchronously so the route can 202 immediately; `work` runs detached.
+ *
+ * `work` receives a progress sink to call as it moves through stages. Its
+ * resolved value becomes `result`; a throw becomes `error` via `classify`.
+ */
+export function startImportJob(
+  vaultName: string,
+  work: (onProgress: (update: ImportProgress) => void) => Promise<ImportResult>,
+  classify: (err: unknown) => ImportJobError,
+): ImportJob {
+  const now = Date.now();
+  gc(now);
+  if (running.has(vaultName)) {
+    throw new ImportJobConflictError(vaultName);
+  }
+
+  const nowIso = new Date(now).toISOString();
+  const job: ImportJob = {
+    job_id: crypto.randomUUID(),
+    vault_name: vaultName,
+    status: "running",
+    stage: "cloning",
+    started_at: nowIso,
+    updated_at: nowIso,
+  };
+  jobs.set(job.job_id, job);
+  running.set(vaultName, job.job_id);
+
+  const onProgress = (update: ImportProgress) => {
+    // A tick that arrives after the job finished (a late stderr line racing
+    // the exit) must not resurrect a terminal record.
+    if (job.status !== "running") return;
+    job.stage = update.stage;
+    if (update.detail !== undefined) job.detail = update.detail;
+    else delete job.detail;
+    job.updated_at = new Date().toISOString();
+  };
+
+  const finish = (patch: Partial<ImportJob>) => {
+    Object.assign(job, patch);
+    job.finished_at = new Date().toISOString();
+    job.updated_at = job.finished_at;
+    delete job.detail;
+    running.delete(vaultName);
+  };
+
+  // Detached on purpose — the response has already been sent by the time this
+  // settles. Every rejection path is funnelled through `classify` so an
+  // unexpected throw becomes a readable job error rather than an unhandled
+  // rejection that leaves the job "running" forever.
+  void work(onProgress).then(
+    (result) => finish({ status: "succeeded", result }),
+    (err) => finish({ status: "failed", error: classify(err) }),
+  );
+
+  return job;
+}
+
+/** Test seam: forget every job. */
+export function _resetImportJobsForTest(): void {
+  jobs.clear();
+  running.clear();
+}

package/src/mirror-import.test.ts

@@ -24,6 +24,7 @@ import { SqliteStore } from "../core/src/store.ts";
 import { exportVaultToDir } from "../core/src/portable-md.ts";
 import {
   CloneFailedError,
+  DEFAULT_CLONE_STALL_TIMEOUT_MS,
   ImportConflictError,
   NotAVaultExportError,
   _isImportInFlight,
@@ -437,7 +438,7 @@ describe("cloneAndImport — failures", () => {
     }
   });
 
-  test("clone timeout → CloneFailedError mentioning timeout", async () => {
+  test("absolute clone timeout → CloneFailedError naming the limit", async () => {
     await expect(
       cloneAndImport({
         vaultName: "default",
@@ -449,7 +450,106 @@ describe("cloneAndImport — failures", () => {
         spawn: spawnCloneTimeout,
         cloneTimeoutMs: 100,
       }),
-    ).rejects.toThrow(/timed out/);
+    ).rejects.toThrow(/exceeded its .*limit/);
+  });
+
+  // vault#640 — a stalled clone and a slow one are different failures and get
+  // different copy. The old code could only say "timed out after 60s", which
+  // was actively misleading on a big vault: nothing was wrong except that the
+  // vault was large.
+  test("stalled clone → CloneFailedError says STALLED, not 'too slow'", async () => {
+    const spawnStalled: GitSpawn = async () => ({
+      exitCode: 143,
+      stderr: "",
+      timedOut: true,
+      stalled: true,
+    });
+    await expect(
+      cloneAndImport({
+        vaultName: "default",
+        remoteUrl: "https://github.com/owner/repo.git",
+        auth: { kind: "none" },
+        mode: "merge",
+        store,
+        assetsDir,
+        spawn: spawnStalled,
+        cloneStallTimeoutMs: 600_000,
+      }),
+    ).rejects.toThrow(/stalled — no progress for 10 minutes/);
+  });
+
+  // The regression that made this whole change necessary: a clone that takes
+  // longer than a minute must NOT be killed. Previously `cloneTimeoutMs`
+  // defaulted to 60s, so any vault big enough to matter failed here.
+  test("no absolute timeout by default — a long clone is allowed to finish", async () => {
+    const localFixture = await buildExportFixture();
+    let observedTimeout: number | undefined;
+    let observedStall: number | undefined;
+    const spawnSlowButFine: GitSpawn = async (argv, options) => {
+      observedTimeout = options.timeoutMs;
+      observedStall = options.stallTimeoutMs;
+      const dest = argv[argv.length - 1]!;
+      cpSync(localFixture, dest, { recursive: true });
+      return { exitCode: 0, stderr: "", timedOut: false };
+    };
+    const result = await cloneAndImport({
+      vaultName: "default",
+      remoteUrl: "https://github.com/owner/repo.git",
+      auth: { kind: "none" },
+      mode: "merge",
+      store,
+      assetsDir,
+      spawn: spawnSlowButFine,
+    });
+    expect(result.notes_imported).toBeGreaterThan(0);
+    // 0 == disabled. The stall bound is what guards a wedged clone.
+    expect(observedTimeout).toBe(0);
+    expect(observedStall).toBe(DEFAULT_CLONE_STALL_TIMEOUT_MS);
+  });
+
+  test("clone runs with --progress so the stall timer has something to watch", async () => {
+    const localFixture = await buildExportFixture();
+    let argvSeen: string[] = [];
+    const spawnCapture: GitSpawn = async (argv) => {
+      argvSeen = argv;
+      const dest = argv[argv.length - 1]!;
+      cpSync(localFixture, dest, { recursive: true });
+      return { exitCode: 0, stderr: "", timedOut: false };
+    };
+    await cloneAndImport({
+      vaultName: "default",
+      remoteUrl: "https://github.com/owner/repo.git",
+      auth: { kind: "none" },
+      mode: "merge",
+      store,
+      assetsDir,
+      spawn: spawnCapture,
+    });
+    expect(argvSeen).toContain("--progress");
+  });
+
+  test("onProgress reports stage transitions and clone detail", async () => {
+    const localFixture = await buildExportFixture();
+    const seen: string[] = [];
+    const spawnWithProgress: GitSpawn = async (argv, options) => {
+      options.onProgress?.("Receiving objects:  47% (470/1000)");
+      const dest = argv[argv.length - 1]!;
+      cpSync(localFixture, dest, { recursive: true });
+      return { exitCode: 0, stderr: "", timedOut: false };
+    };
+    await cloneAndImport({
+      vaultName: "default",
+      remoteUrl: "https://github.com/owner/repo.git",
+      auth: { kind: "none" },
+      mode: "merge",
+      store,
+      assetsDir,
+      spawn: spawnWithProgress,
+      onProgress: (u) => seen.push(`${u.stage}:${u.detail ?? ""}`),
+    });
+    expect(seen).toContain("cloning:");
+    expect(seen).toContain("cloning:Receiving objects:  47% (470/1000)");
+    expect(seen).toContain("importing:");
   });
 
   test("clone target lacks .parachute/vault.yaml → NotAVaultExportError", async () => {

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",