@openparachute/vault 0.4.9-rc.9 → 0.5.0-rc.2

package/src/mirror-credentials.ts

@@ -23,16 +23,27 @@
  *     embeds them in the mirror's remote URL. Works against GitHub, GitLab,
  *     Codeberg, Gitea, anything that accepts an HTTPS token in the URL.
  *
- * **Storage:** `<configDir>/vault/.mirror-credentials.yaml`, perms `0o600`,
- * **not encrypted at rest**. Rationale: encryption-at-rest with the key on
- * the same disk doesn't add real security; OS perms ARE the protection. Same
- * trust model as `~/.git-credentials` (which most operators already use).
- * The file is documented as sensitive; redaction in logs is enforced by
- * `sanitizeCredentials` + a discipline of "never log the raw token."
+ * **Storage:** `<configDir>/vault/data/<vaultName>/.mirror-credentials.yaml`,
+ * perms `0o600`, **not encrypted at rest**. Rationale: encryption-at-rest
+ * with the key on the same disk doesn't add real security; OS perms ARE the
+ * protection. Same trust model as `~/.git-credentials` (which most operators
+ * already use). The file is documented as sensitive; redaction in logs is
+ * enforced by `sanitizeCredentials` + a discipline of "never log the raw
+ * token."
+ *
+ * **Per-vault (vault#399).** Credentials — both the PAT and the embedded
+ * `remote_url` — live under each vault's own data dir, alongside its SQLite
+ * DB + vault.yaml. This is the existing per-vault-state pattern. Before
+ * vault#399 they lived in a single SERVER-WIDE file
+ * (`<configDir>/vault/.mirror-credentials.yaml`); that leaked the first
+ * vault's remote + PAT onto every other vault that configured git sync —
+ * pointing vault B at vault A's GitHub repo. The legacy server-wide file is
+ * migrated to its owning vault on first per-vault read (see
+ * `migrateLegacyServerWideCredentials`).
  *
  * **One credential set per vault.** Multi-credential ("I want repo A pushed
- * with token X, repo B with token Y") isn't supported — vault#382 ships one
- * mirror per vault server today; one credential set per vault matches.
+ * with token X, repo B with token Y") within a single vault isn't supported —
+ * vault#382 ships one mirror per vault; one credential set per vault matches.
  */
 
 import {
@@ -98,8 +109,10 @@ export interface PATCredential {
 }
 
 /**
- * The on-disk + on-the-wire shape. One file per vault server (matches the
- * "one mirror per vault server today" invariant from mirror-config.ts).
+ * The on-disk + on-the-wire shape. One file per VAULT (vault#399) — keyed by
+ * the vault's data dir, not the server. Each vault has its own PAT + its own
+ * `remote_url`, so configuring git sync for vault B never reuses vault A's
+ * remote.
  */
 export interface MirrorCredentials {
   /**
@@ -137,23 +150,38 @@ export interface MirrorCredentialsPublic {
 // Path resolution
 // ---------------------------------------------------------------------------
 
+/** The vault home root — `<configDir>/vault`. Re-reads PARACHUTE_HOME per call. */
+function vaultHomeRoot(): string {
+  const root = process.env.PARACHUTE_HOME ?? join(homedir(), ".parachute");
+  return join(root, "vault");
+}
+
 /**
- * Path to the per-vault-server credentials file.
+ * Path to a vault's per-vault credentials file (vault#399).
  *
- * Note: this is a SERVER-wide credentials file (`<configDir>/vault/.mirror-credentials.yaml`),
- * not a per-vault file. The mirror manager itself is server-wide (one mirror
- * per vault server today) so the credentials follow that scope. When multi-
- * vault mirroring lands (open question 2 in the design doc), this becomes
- * per-vault and gets keyed by name. Today's shape: one file.
+ * `<configDir>/vault/data/<vaultName>/.mirror-credentials.yaml` — under the
+ * vault's own data dir, alongside its SQLite DB (`vault.db`) + config
+ * (`vault.yaml`). This is the canonical per-vault-state location; every
+ * vault carries its own PAT + remote_url so git sync for one vault never
+ * reuses another vault's remote.
  *
- * Path resolution mirrors `config.ts:vaultHomePath()` — re-reads
- * `PARACHUTE_HOME` on every call so test sandboxes (`PARACHUTE_VAULT_HOME`
- * is a vault-internal var that doesn't override here — we use the canonical
- * `PARACHUTE_HOME` that the rest of vault honors).
+ * Path resolution mirrors `config.ts:vaultDir()` rather than importing it —
+ * mirror-config.ts imports this module and config.ts imports mirror-config.ts,
+ * so importing config.ts here would close an import cycle. We re-derive the
+ * path from `PARACHUTE_HOME` (the canonical override the rest of vault honors)
+ * instead, which keeps this module dependency-light.
  */
-export function mirrorCredentialsPath(): string {
-  const root = process.env.PARACHUTE_HOME ?? join(homedir(), ".parachute");
-  return join(root, "vault", ".mirror-credentials.yaml");
+export function mirrorCredentialsPath(vaultName: string): string {
+  return join(vaultHomeRoot(), "data", vaultName, ".mirror-credentials.yaml");
+}
+
+/**
+ * Path to the LEGACY server-wide credentials file
+ * (`<configDir>/vault/.mirror-credentials.yaml`) used before vault#399.
+ * Retained only so the migration can find + attribute + rename it.
+ */
+export function legacyServerWideCredentialsPath(): string {
+  return join(vaultHomeRoot(), ".mirror-credentials.yaml");
 }
 
 // ---------------------------------------------------------------------------
@@ -344,12 +372,18 @@ export function parseCredentials(yaml: string): MirrorCredentials {
 // ---------------------------------------------------------------------------
 
 /**
- * Read credentials from disk. Returns `null` when the file doesn't exist
- * (operator hasn't connected anything yet); throws when the file is present
- * but unreadable (a permission error is a loud configuration problem).
+ * Read a vault's credentials from disk. Returns `null` when the file doesn't
+ * exist (operator hasn't connected anything yet); throws when the file is
+ * present but unreadable (a permission error is a loud configuration problem).
+ *
+ * vault#399 migration: if the per-vault file is absent but the legacy
+ * server-wide file exists, `migrateLegacyServerWideCredentials` may have
+ * promoted it to THIS vault (when it's the migration target). The migration
+ * runs at boot (server.ts) and is idempotent; this read just picks up
+ * whatever landed on disk.
  */
-export function readCredentials(): MirrorCredentials | null {
-  const path = mirrorCredentialsPath();
+export function readCredentials(vaultName: string): MirrorCredentials | null {
+  const path = mirrorCredentialsPath(vaultName);
   if (!existsSync(path)) return null;
   const raw = readFileSync(path, "utf8");
   return parseCredentials(raw);
@@ -366,8 +400,8 @@ export function readCredentials(): MirrorCredentials | null {
  * surface a 500 with the underlying message — quietly losing credentials
  * would be worse than crashing the request.
  */
-export function writeCredentials(creds: MirrorCredentials): void {
-  const path = mirrorCredentialsPath();
+export function writeCredentials(vaultName: string, creds: MirrorCredentials): void {
+  const path = mirrorCredentialsPath(vaultName);
   const dir = dirname(path);
   // Vault home may not exist yet (tests, fresh installs); create it.
   if (!existsSync(dir)) {
@@ -401,11 +435,100 @@ export function writeCredentials(creds: MirrorCredentials): void {
  * Delete the credentials file. Idempotent — missing file is a no-op (the
  * Disconnect UX should succeed even if the file was already removed).
  */
-export function deleteCredentials(): void {
-  const path = mirrorCredentialsPath();
+export function deleteCredentials(vaultName: string): void {
+  const path = mirrorCredentialsPath(vaultName);
   if (existsSync(path)) unlinkSync(path);
 }
 
+// ---------------------------------------------------------------------------
+// Migration — legacy server-wide → per-vault (vault#399)
+// ---------------------------------------------------------------------------
+
+/**
+ * One-time migration of the legacy server-wide credentials file to the
+ * per-vault layout (vault#399).
+ *
+ * The bug: pre-vault#399, credentials (PAT + embedded `remote_url`) lived in a
+ * single `<configDir>/vault/.mirror-credentials.yaml` shared across ALL
+ * vaults. Configuring git sync for a second vault reused the first vault's
+ * remote, pointing it at the wrong GitHub repo.
+ *
+ * Attribution policy (SAFEST per the design): attribute the legacy creds to
+ * the FIRST vault — the earliest-created one, which is what
+ * `resolveMirrorVaultName()` already bound the single server-wide mirror to.
+ * That's the vault whose remote/PAT the legacy file actually corresponds to.
+ * We do NOT copy the same remote/PAT onto every vault — that would recreate
+ * the leak.
+ *
+ * Safety:
+ *   - No-op when no legacy file exists (fresh installs, already-migrated).
+ *   - No-op when the target vault already has a per-vault file (don't clobber
+ *     creds the operator set post-migration).
+ *   - Leaves the legacy file in place renamed `.bak` (never silently deleted)
+ *     so nothing is lost if attribution was wrong — the operator can recover.
+ *   - Logs the attribution decision clearly.
+ *
+ * @param targetVaultName the vault to attribute the legacy creds to (caller
+ *   passes the result of `resolveMirrorVaultName()`, i.e. default-or-first).
+ * @returns a struct describing what happened, for logging + tests.
+ */
+export function migrateLegacyServerWideCredentials(
+  targetVaultName: string | null,
+):
+  | { migrated: false; reason: "no_legacy_file" | "no_target_vault" | "target_already_has_creds" }
+  | { migrated: true; targetVaultName: string; backupPath: string } {
+  const legacyPath = legacyServerWideCredentialsPath();
+  if (!existsSync(legacyPath)) {
+    return { migrated: false, reason: "no_legacy_file" };
+  }
+  if (!targetVaultName) {
+    // Legacy file present but no vault to attribute it to. Leave it in
+    // place — a future boot (once a vault exists) migrates it.
+    return { migrated: false, reason: "no_target_vault" };
+  }
+  const targetPath = mirrorCredentialsPath(targetVaultName);
+  if (existsSync(targetPath)) {
+    // The target vault already has per-vault creds (operator configured
+    // them post-migration, or a prior migration ran). Don't clobber.
+    // Still rename the legacy file so we don't re-evaluate it forever.
+    const backupPath = `${legacyPath}.bak`;
+    try {
+      if (!existsSync(backupPath)) renameSync(legacyPath, backupPath);
+    } catch {
+      // Non-fatal — worst case we re-check next boot and short-circuit here.
+    }
+    return { migrated: false, reason: "target_already_has_creds" };
+  }
+
+  // Read the legacy creds + write them to the target vault's per-vault file.
+  const raw = readFileSync(legacyPath, "utf8");
+  const creds = parseCredentials(raw);
+  writeCredentials(targetVaultName, creds);
+
+  // Rename the legacy file to .bak rather than deleting — never silently
+  // lose an operator's only copy of a token/remote.
+  const backupPath = `${legacyPath}.bak`;
+  try {
+    renameSync(legacyPath, backupPath);
+  } catch {
+    // If the rename fails (e.g. .bak already exists from a partial prior
+    // run), fall back to unlinking the original — the creds are now safely
+    // in the per-vault file.
+    try {
+      unlinkSync(legacyPath);
+    } catch {
+      // Leave it; the target_already_has_creds branch short-circuits next boot.
+    }
+  }
+
+  console.log(
+    `[mirror] migrated legacy server-wide mirror credentials → vault "${targetVaultName}" (per-vault, vault#399). ` +
+      `Other vaults start with no mirror credentials (configure each separately). ` +
+      `Legacy file preserved at ${backupPath}.`,
+  );
+  return { migrated: true, targetVaultName, backupPath };
+}
+
 // ---------------------------------------------------------------------------
 // Redaction
 // ---------------------------------------------------------------------------

package/src/mirror-deps.ts

@@ -10,8 +10,13 @@
 import { exportVaultToDir, hasSchemaContent, pruneOrphans } from "../core/src/portable-md.ts";
 
 import { defaultHookRegistry } from "../core/src/hooks.ts";
-import { readGlobalConfig, writeGlobalConfig, readVaultConfig } from "./config.ts";
-import { defaultMirrorConfig, type MirrorConfig } from "./mirror-config.ts";
+import { readGlobalConfig, readVaultConfig } from "./config.ts";
+import {
+  defaultMirrorConfig,
+  readMirrorConfigForVault,
+  writeMirrorConfigForVault,
+  type MirrorConfig,
+} from "./mirror-config.ts";
 import type { MirrorDeps } from "./mirror-manager.ts";
 import { assetsDir } from "./routes.ts";
 import { getVaultStore } from "./vault-store.ts";
@@ -24,9 +29,9 @@ import { getVaultStore } from "./vault-store.ts";
  *     CLI mode exactly.
  *   - `firstChangedNoteTitle` → DB query for the most recent note with
  *     `updated_at >= cursor`. Identical to the CLI helper.
- *   - `readMirrorConfig` / `writeMirrorConfig` → round-trip through
- *     `readGlobalConfig` + `writeGlobalConfig`, preserving the rest of
- *     the global config file atomically.
+ *   - `readMirrorConfig` / `writeMirrorConfig` → per-vault config file at
+ *     `data/<vault>/mirror-config.yaml` (vault#400). Each vault carries its
+ *     own mirror config, so configuring vault B never touches vault A's.
  */
 export function buildMirrorDeps(vaultName: string): MirrorDeps {
   return {
@@ -92,11 +97,12 @@ export function buildMirrorDeps(vaultName: string): MirrorDeps {
         return "";
       }
     },
-    readMirrorConfig: () => readGlobalConfig().mirror,
+    // Per-vault (vault#400): read/write THIS vault's own config file, never
+    // a shared server-wide block. Configuring vault B's mirror leaves vault
+    // A's config untouched.
+    readMirrorConfig: () => readMirrorConfigForVault(vaultName),
     writeMirrorConfig: (config: MirrorConfig) => {
-      const global = readGlobalConfig();
-      global.mirror = config;
-      writeGlobalConfig(global);
+      writeMirrorConfigForVault(vaultName, config);
     },
     // Share the process-wide hook registry so mirror's subscriptions land
     // on the same event bus that `BunSqliteStore` dispatches on. This is
@@ -107,14 +113,17 @@ export function buildMirrorDeps(vaultName: string): MirrorDeps {
 }
 
 /**
- * Resolve the mirror's owning vault. Today the mirror is per-server
- * (single config block in `config.yaml`), and the natural binding is
- * `default_vault` (the same vault the CLI + MCP wire up by default).
- * If no default is set, fall back to the first listed vault.
+ * Resolve the mirror's "owning" vault — the one the LEGACY server-wide
+ * config + credentials are attributed to during migration.
  *
- * Multi-vault mirror routing is future work (open question 2 in the
- * design doc); this helper localizes the binding decision so a future
- * refactor only touches one site.
+ * Post-vault#400 every vault has its own mirror config + manager (real
+ * multi-vault mirroring), so this is no longer "the one vault that can
+ * mirror." It survives as the migration-attribution target: the legacy
+ * server-wide `mirror:` block (vault#400) and the legacy server-wide
+ * credentials file (vault#399) belong to the vault the single old mirror
+ * was bound to — `default_vault`, or the first listed vault when no default
+ * is set. Localizing the binding here keeps the migration attribution in one
+ * place.
  */
 export function resolveMirrorVaultName(
   listVaults: () => string[],

package/src/mirror-import.test.ts

@@ -30,8 +30,10 @@ import {
   _resetImportInFlightForTest,
   authedCloneUrl,
   cloneAndImport,
+  defaultGitSpawn,
   type GitSpawn,
 } from "./mirror-import.ts";
+import { GitNotInstalledError } from "./git-preflight.ts";
 import {
   emptyCredentials,
   mirrorCredentialsPath,
@@ -112,13 +114,13 @@ afterEach(() => {
 
 describe("authedCloneUrl", () => {
   test("returns null for unparseable URL", () => {
-    expect(authedCloneUrl("not-a-url", { kind: "none" })).toBeNull();
+    expect(authedCloneUrl("not-a-url", { kind: "none" }, "v")).toBeNull();
   });
 
   test("passes git:// URLs verbatim (no userinfo to embed)", () => {
     // `git://github.com/owner/repo.git` parses as a URL with protocol
     // `git:`, not http/https — our helper returns it verbatim.
-    const r = authedCloneUrl("git://github.com/owner/repo.git", { kind: "pat", token: "ghp_x" });
+    const r = authedCloneUrl("git://github.com/owner/repo.git", { kind: "pat", token: "ghp_x" }, "v");
     expect(r).not.toBeNull();
     expect(r!.authedUrl).toBe("git://github.com/owner/repo.git");
     expect(r!.appliedAuth).toBe("none");
@@ -134,7 +136,7 @@ describe("authedCloneUrl", () => {
     const r = authedCloneUrl("git@github.com:owner/repo.git", {
       kind: "pat",
       token: "ghp_should_not_appear",
-    });
+    }, "v");
     expect(r).not.toBeNull();
     expect(r!.authedUrl).toBe("git@github.com:owner/repo.git");
     expect(r!.authedUrl).not.toContain("ghp_should_not_appear");
@@ -145,7 +147,7 @@ describe("authedCloneUrl", () => {
     const r = authedCloneUrl("ssh://git@github.com/owner/repo.git", {
       kind: "pat",
       token: "ghp_x",
-    });
+    }, "v");
     expect(r).not.toBeNull();
     expect(r!.authedUrl).toBe("ssh://git@github.com/owner/repo.git");
     expect(r!.appliedAuth).toBe("none");
@@ -155,7 +157,7 @@ describe("authedCloneUrl", () => {
     const r = authedCloneUrl("https://user:pass@github.com/owner/repo.git", {
       kind: "pat",
       token: "ghp_x",
-    });
+    }, "v");
     expect(r).not.toBeNull();
     expect(r!.authedUrl).toContain("user:pass@");
     expect(r!.appliedAuth).toBe("none");
@@ -165,14 +167,14 @@ describe("authedCloneUrl", () => {
     const r = authedCloneUrl("https://github.com/owner/repo.git", {
       kind: "pat",
       token: "ghp_abc123",
-    });
+    }, "v");
     expect(r).not.toBeNull();
     expect(r!.authedUrl).toContain("x-access-token:ghp_abc123@");
     expect(r!.appliedAuth).toBe("per_call_pat");
   });
 
   test("none auth returns verbatim URL", () => {
-    const r = authedCloneUrl("https://github.com/owner/repo.git", { kind: "none" });
+    const r = authedCloneUrl("https://github.com/owner/repo.git", { kind: "none" }, "v");
     expect(r).not.toBeNull();
     expect(r!.authedUrl).toBe("https://github.com/owner/repo.git");
     expect(r!.appliedAuth).toBe("none");
@@ -190,7 +192,7 @@ describe("authedCloneUrl", () => {
     });
 
     test("no credentials file → verbatim URL", () => {
-      const r = authedCloneUrl("https://github.com/owner/repo.git", { kind: "credentialsFile" });
+      const r = authedCloneUrl("https://github.com/owner/repo.git", { kind: "credentialsFile" }, "default");
       expect(r!.appliedAuth).toBe("none");
     });
 
@@ -206,8 +208,8 @@ describe("authedCloneUrl", () => {
           user_id: 1,
         },
       };
-      writeCredentials(creds);
-      const r = authedCloneUrl("https://github.com/owner/repo.git", { kind: "credentialsFile" });
+      writeCredentials("default", creds);
+      const r = authedCloneUrl("https://github.com/owner/repo.git", { kind: "credentialsFile" }, "default");
       expect(r!.authedUrl).toContain("x-access-token:gho_abc@");
       expect(r!.appliedAuth).toBe("stored_oauth");
     });
@@ -224,8 +226,8 @@ describe("authedCloneUrl", () => {
           user_id: 1,
         },
       };
-      writeCredentials(creds);
-      const r = authedCloneUrl("https://gitlab.com/owner/repo.git", { kind: "credentialsFile" });
+      writeCredentials("default", creds);
+      const r = authedCloneUrl("https://gitlab.com/owner/repo.git", { kind: "credentialsFile" }, "default");
       expect(r!.appliedAuth).toBe("none");
     });
 
@@ -239,8 +241,8 @@ describe("authedCloneUrl", () => {
           label: "GitLab PAT",
         },
       };
-      writeCredentials(creds);
-      const r = authedCloneUrl("https://gitlab.com/owner/repo.git", { kind: "credentialsFile" });
+      writeCredentials("default", creds);
+      const r = authedCloneUrl("https://gitlab.com/owner/repo.git", { kind: "credentialsFile" }, "default");
       expect(r!.authedUrl).toContain("x-access-token:glpat_xyz@");
       expect(r!.appliedAuth).toBe("stored_pat");
     });
@@ -255,8 +257,8 @@ describe("authedCloneUrl", () => {
           label: "GitLab PAT",
         },
       };
-      writeCredentials(creds);
-      const r = authedCloneUrl("https://github.com/owner/repo.git", { kind: "credentialsFile" });
+      writeCredentials("default", creds);
+      const r = authedCloneUrl("https://github.com/owner/repo.git", { kind: "credentialsFile" }, "default");
       expect(r!.appliedAuth).toBe("none");
     });
   });
@@ -548,3 +550,107 @@ describe("cloneAndImport — failures", () => {
     rmSync(notAnExport, { recursive: true, force: true });
   });
 });
+
+// ---------------------------------------------------------------------------
+// cloneAndImport — git not installed (vault#415 — live bug on a git-less EC2)
+// ---------------------------------------------------------------------------
+
+describe("cloneAndImport — git not installed", () => {
+  let assetsDir: string;
+  let store: SqliteStore;
+
+  beforeEach(() => {
+    assetsDir = tmp("import-assets-nogit-");
+    store = new SqliteStore(new Database(":memory:"));
+  });
+
+  afterEach(() => {
+    if (assetsDir) rmSync(assetsDir, { recursive: true, force: true });
+  });
+
+  test("git missing → GitNotInstalledError, fails fast (no spawn, no tempdir)", async () => {
+    const workDirRoot = tmp("import-workroot-nogit-");
+    let spawnCalled = false;
+    const spyingSpawn: GitSpawn = async () => {
+      spawnCalled = true;
+      return { exitCode: 0, stderr: "", timedOut: false };
+    };
+    await expect(
+      cloneAndImport({
+        vaultName: "default",
+        remoteUrl: "https://github.com/owner/repo.git",
+        auth: { kind: "none" },
+        mode: "merge",
+        store,
+        assetsDir,
+        spawn: spyingSpawn,
+        workDirRoot,
+        // Force the preflight to see no git on PATH.
+        which: () => null,
+      }),
+    ).rejects.toBeInstanceOf(GitNotInstalledError);
+
+    // Fails fast: the spawner is never reached and no tempdir is created.
+    expect(spawnCalled).toBe(false);
+    const { readdirSync } = await import("node:fs");
+    const entries = readdirSync(workDirRoot);
+    expect(entries.filter((e) => e.startsWith("parachute-import-"))).toEqual([]);
+    rmSync(workDirRoot, { recursive: true, force: true });
+  });
+
+  test("git missing → does not lay an in-flight marker (clean retry after install)", async () => {
+    await expect(
+      cloneAndImport({
+        vaultName: "default",
+        remoteUrl: "https://github.com/owner/repo.git",
+        auth: { kind: "none" },
+        mode: "merge",
+        store,
+        assetsDir,
+        spawn: async () => ({ exitCode: 0, stderr: "", timedOut: false }),
+        which: () => null,
+      }),
+    ).rejects.toBeInstanceOf(GitNotInstalledError);
+    // The preflight runs BEFORE the concurrency marker, so a failed call
+    // leaves no stale in-flight entry blocking the post-install retry.
+    expect(_isImportInFlight("default")).toBe(false);
+  });
+
+  test("git present (injected which) → normal import path still works", async () => {
+    const fixtureDir = await buildExportFixture();
+    try {
+      const result = await cloneAndImport({
+        vaultName: "default",
+        remoteUrl: "https://github.com/owner/repo.git",
+        auth: { kind: "none" },
+        mode: "merge",
+        store,
+        assetsDir,
+        spawn: spawnCloneSuccess(fixtureDir),
+        which: () => "/usr/bin/git",
+      });
+      expect(result.notes_imported).toBe(2);
+    } finally {
+      rmSync(fixtureDir, { recursive: true, force: true });
+    }
+  });
+
+  test("GitNotInstalledError message is actionable (names install commands)", () => {
+    const msg = new GitNotInstalledError().message;
+    expect(msg).toContain("git is required");
+    expect(msg).toContain("dnf install git");
+    expect(msg).toContain("apt-get install");
+    expect(msg).toContain("brew install git");
+  });
+
+  test("defaultGitSpawn rethrows a git-not-found spawn error as GitNotInstalledError", async () => {
+    // Belt-and-suspenders: spawn a non-existent binary to trigger Bun's
+    // "Executable not found" throw, and confirm the friendly rethrow.
+    // (We can't uninstall git, so spawn an impossible command name.)
+    await expect(
+      defaultGitSpawn(["definitely-not-a-real-binary-xyzzy-git"], {
+        timeoutMs: 5_000,
+      }),
+    ).rejects.toBeInstanceOf(GitNotInstalledError);
+  });
+});

package/src/mirror-import.ts

@@ -73,6 +73,11 @@ import {
 } from "../core/src/portable-md.ts";
 import type { SqliteStore } from "../core/src/store.ts";
 import { redactRemoteUrl, readCredentials } from "./mirror-credentials.ts";
+import {
+  GitNotInstalledError,
+  ensureGitAvailable,
+  isGitNotFoundSpawnError,
+} from "./git-preflight.ts";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -125,6 +130,11 @@ export interface ImportOpts {
   importer?: typeof importPortableVault;
   /** Override the clone timeout (default 60s; test seam to shorten). */
   cloneTimeoutMs?: number;
+  /**
+   * Override the git-presence probe (test seam — defaults to `Bun.which`).
+   * Inject a fn returning `null` to exercise the git-not-installed path.
+   */
+  which?: (cmd: string) => string | null;
 }
 
 /**
@@ -209,6 +219,8 @@ export class CloneFailedError extends Error {
  *   - `credentialsFile` → if stored creds are GitHub OAuth, embed the
  *     token. If stored creds are a PAT with a saved URL whose host
  *     matches, reuse the stored URL. Otherwise pass the URL verbatim.
+ *     The stored creds are read from the target vault's PER-VAULT file
+ *     (vault#399) — `vaultName` is required for this auth kind.
  *   - `none` → return the URL verbatim.
  *
  * Returns `null` when the URL is unparseable (caller surfaces a 400).
@@ -216,6 +228,7 @@ export class CloneFailedError extends Error {
 export function authedCloneUrl(
   remoteUrl: string,
   auth: ImportAuth,
+  vaultName: string,
 ): { authedUrl: string; appliedAuth: "stored_oauth" | "stored_pat" | "per_call_pat" | "none" } | null {
   // Local-path / SSH-shorthand pass-through. Git accepts three URL shapes:
   //   - HTTPS/HTTP — what we embed auth into below.
@@ -267,8 +280,8 @@ export function authedCloneUrl(
     return { authedUrl: u.toString(), appliedAuth: "per_call_pat" };
   }
 
-  // credentialsFile path — read from disk.
-  const creds = readCredentials();
+  // credentialsFile path — read the target vault's per-vault creds (vault#399).
+  const creds = readCredentials(vaultName);
   if (!creds || !creds.active_method) {
     return { authedUrl: remoteUrl, appliedAuth: "none" };
   }
@@ -312,19 +325,32 @@ export function authedCloneUrl(
  * exit code + stderr text + timeout flag.
  */
 export const defaultGitSpawn: GitSpawn = async (argv, options) => {
-  const proc = Bun.spawn(argv, {
-    cwd: options.cwd,
-    stdout: "pipe",
-    stderr: "pipe",
-    env: {
-      ...process.env,
-      GIT_TERMINAL_PROMPT: "0",
-      // Kill any system credential helper from intercepting — we want
-      // the clone to use ONLY the URL-embedded credential, not whatever's
-      // in keychain. Same shape as the ls-remote probe.
-      GIT_ASKPASS: "/bin/echo",
-    },
-  });
+  let proc;
+  try {
+    proc = Bun.spawn(argv, {
+      cwd: options.cwd,
+      stdout: "pipe",
+      stderr: "pipe",
+      env: {
+        ...process.env,
+        GIT_TERMINAL_PROMPT: "0",
+        // Kill any system credential helper from intercepting — we want
+        // the clone to use ONLY the URL-embedded credential, not whatever's
+        // in keychain. Same shape as the ls-remote probe.
+        GIT_ASKPASS: "/bin/echo",
+      },
+    });
+  } catch (err) {
+    // Belt-and-suspenders: `cloneAndImport` preflights via
+    // `ensureGitAvailable`, but if a git-missing spawn still slips through
+    // (race, or a future caller that skipped the preflight) rethrow it as
+    // the friendly error rather than leaking Bun's raw
+    // `Executable not found in $PATH: "git"`.
+    if (isGitNotFoundSpawnError(err)) {
+      throw new GitNotInstalledError();
+    }
+    throw err;
+  }
   let timedOut = false;
   const timer = setTimeout(() => {
     timedOut = true;
@@ -362,6 +388,14 @@ export const defaultGitSpawn: GitSpawn = async (argv, options) => {
  * Always cleans up the temp dir.
  */
 export async function cloneAndImport(opts: ImportOpts): Promise<ImportResult> {
+  // Fail fast + clean when git isn't installed — BEFORE the concurrency
+  // marker, tempdir creation, or any spawn. The route maps the resulting
+  // GitNotInstalledError to a friendly 503 (git_not_installed). Without
+  // this, the first `Bun.spawn(["git", ...])` threw a raw
+  // `Executable not found in $PATH: "git"` that only the generic 500 branch
+  // caught — the unhelpful failure mode found live on the gitcoin EC2 box.
+  ensureGitAvailable(opts.which);
+
   if (inFlight.has(opts.vaultName)) {
     throw new ImportConflictError(opts.vaultName);
   }
@@ -372,7 +406,7 @@ export async function cloneAndImport(opts: ImportOpts): Promise<ImportResult> {
   const workDirRoot = opts.workDirRoot ?? tmpdir();
   const cloneTimeoutMs = opts.cloneTimeoutMs ?? 60_000;
 
-  const authResult = authedCloneUrl(opts.remoteUrl, opts.auth);
+  const authResult = authedCloneUrl(opts.remoteUrl, opts.auth, opts.vaultName);
   if (!authResult) {
     inFlight.delete(opts.vaultName);
     throw new CloneFailedError(