@openparachute/vault 0.5.0-rc.1 → 0.5.0-rc.2

package/package.json

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

package/src/export-watch.test.ts

@@ -35,6 +35,7 @@ import {
   runGitCommitCycle,
   shouldCommit,
 } from "./export-watch.ts";
+import { GitNotInstalledError } from "./git-preflight.ts";
 
 const CLI = path.resolve(import.meta.dir, "cli.ts");
 
@@ -504,6 +505,28 @@ describe("runGitCommitCycle", () => {
     });
     expect(result.message).toBe("note: Inbox/DonorMeeting");
   });
+
+  test("git missing → throws GitNotInstalledError (sync surfaces friendly error, not raw spawn crash)", async () => {
+    // vault#415 — the sync/commit path must surface the actionable
+    // git-not-installed message (which the manager threads into
+    // status.last_error) instead of crashing with a raw "Executable not
+    // found in $PATH". Force the preflight to see no git via the `which`
+    // seam; no real spawn should be reached.
+    fs.writeFileSync(path.join(dir, "Note.md"), "# n\n");
+    await expect(
+      runGitCommitCycle({
+        repoDir: dir,
+        template: DEFAULT_COMMIT_TEMPLATE,
+        notesChanged: 1,
+        vaultName: "default",
+        firstNoteTitle: "Note",
+        push: false,
+        which: () => null,
+      }),
+    ).rejects.toBeInstanceOf(GitNotInstalledError);
+    // The commit cycle bailed at the preflight — no commit landed.
+    expect(gitLogOneline(dir)).toHaveLength(1); // only the seed
+  });
 });
 
 // ---------------------------------------------------------------------------

package/src/export-watch.ts

@@ -13,6 +13,8 @@
  * detection. See `parachute-patterns/cookbook/vault-portable-export.md`.
  */
 
+import { ensureGitAvailable } from "./git-preflight.ts";
+
 // ---------------------------------------------------------------------------
 // Commit message templating
 // ---------------------------------------------------------------------------
@@ -269,11 +271,23 @@ export async function runGitCommitCycle(opts: {
   push: boolean;
   /** Override for tests — defaults to `new Date().toISOString()`. */
   now?: () => string;
+  /**
+   * 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;
 }): Promise<{
   committed: boolean;
   message?: string;
   push?: { attempted: true; ok: boolean; error?: string };
 }> {
+  // Preflight: every step below shells `git`. On a git-less server the first
+  // `Bun.spawn(["git", ...])` would throw a raw "Executable not found" error;
+  // surface the friendly, actionable GitNotInstalledError so callers can
+  // thread it into mirror status (`last_error`) instead of crashing the
+  // watch loop with an opaque message.
+  ensureGitAvailable(opts.which);
+
   const now = opts.now ?? (() => new Date().toISOString());
 
   const add = await gitAddAll(opts.repoDir);

package/src/git-preflight.test.ts

@@ -0,0 +1,70 @@
+/**
+ * Tests for the shared git-availability preflight (vault#415).
+ *
+ * Found live: importing a repo on a git-less Amazon Linux EC2 box failed
+ * with a raw `Executable not found in $PATH: "git"` 500. The preflight gives
+ * every git entry point a fast, friendly, actionable failure instead.
+ */
+
+import { describe, test, expect } from "bun:test";
+import {
+  GitNotInstalledError,
+  ensureGitAvailable,
+  isGitNotFoundSpawnError,
+} from "./git-preflight.ts";
+
+describe("ensureGitAvailable", () => {
+  test("throws GitNotInstalledError when which returns null", () => {
+    expect(() => ensureGitAvailable(() => null)).toThrow(GitNotInstalledError);
+  });
+
+  test("does not throw when which resolves git", () => {
+    expect(() => ensureGitAvailable(() => "/usr/bin/git")).not.toThrow();
+  });
+
+  test("defaults to Bun.which (git is present in this test env)", () => {
+    // The test host has git; the default-arg path resolves it cleanly.
+    expect(() => ensureGitAvailable()).not.toThrow();
+  });
+});
+
+describe("GitNotInstalledError message", () => {
+  test("is OS-agnostic-but-helpful — names dnf, apt-get, and brew", () => {
+    const msg = new GitNotInstalledError().message;
+    expect(msg).toContain("git is required for this operation");
+    expect(msg).toContain("sudo dnf install git");
+    expect(msg).toContain("sudo apt-get install -y git");
+    expect(msg).toContain("brew install git");
+  });
+
+  test("carries the GitNotInstalledError name (instanceof + name both work)", () => {
+    const err = new GitNotInstalledError();
+    expect(err).toBeInstanceOf(GitNotInstalledError);
+    expect(err.name).toBe("GitNotInstalledError");
+  });
+});
+
+describe("isGitNotFoundSpawnError", () => {
+  test("matches Bun's executable-not-found message for git", () => {
+    expect(
+      isGitNotFoundSpawnError(
+        new Error('Executable not found in $PATH: "git"'),
+      ),
+    ).toBe(true);
+  });
+
+  test("matches an ENOENT spawn error mentioning git", () => {
+    const err = new Error("spawn git ENOENT") as Error & { code?: string };
+    err.code = "ENOENT";
+    expect(isGitNotFoundSpawnError(err)).toBe(true);
+  });
+
+  test("does not match an unrelated error", () => {
+    expect(isGitNotFoundSpawnError(new Error("network unreachable"))).toBe(false);
+  });
+
+  test("does not match a non-Error value", () => {
+    expect(isGitNotFoundSpawnError("git missing")).toBe(false);
+    expect(isGitNotFoundSpawnError(null)).toBe(false);
+  });
+});

package/src/git-preflight.ts

@@ -0,0 +1,68 @@
+/**
+ * Shared git-availability preflight.
+ *
+ * Every git-using entry point in vault (mirror import, mirror sync/commit/
+ * push, internal-mirror bootstrap) shells out to the `git` binary via
+ * `Bun.spawn(["git", ...])`. On a server where `git` isn't installed (a
+ * fresh Amazon Linux / minimal Docker image, etc.) Bun throws a raw
+ * `Executable not found in $PATH: "git"` error, which the import route only
+ * caught in its generic `internal` 500 branch — surfacing an unhelpful,
+ * un-actionable error to the operator.
+ *
+ * This module centralizes the preflight so every git entry point fails
+ * fast with a clear, actionable message that tells the operator HOW to
+ * fix it (install git via their distro's package manager).
+ *
+ * Found live on the gitcoin-parachute EC2 deploy (Amazon Linux, no git).
+ * See vault#415-era fix.
+ */
+
+/**
+ * Thrown when `git` is required for an operation but isn't on PATH. Carries
+ * an OS-agnostic-but-helpful message with the common install commands so the
+ * operator can act without leaving the error surface.
+ */
+export class GitNotInstalledError extends Error {
+  constructor() {
+    super(
+      "git is required for this operation but was not found on the server. " +
+        "Install git and retry — e.g. `sudo dnf install git` (Amazon Linux / Fedora), " +
+        "`sudo apt-get install -y git` (Debian / Ubuntu), or `brew install git` (macOS).",
+    );
+    this.name = "GitNotInstalledError";
+  }
+}
+
+/**
+ * Throw `GitNotInstalledError` if `git` isn't resolvable on PATH.
+ *
+ * `which` is a TEST SEAM (default `Bun.which`) so tests can force the
+ * git-missing branch without uninstalling git from the test host. Production
+ * callers pass nothing and get the real `Bun.which`.
+ */
+export function ensureGitAvailable(
+  which: (cmd: string) => string | null = Bun.which,
+): void {
+  if (which("git") === null) {
+    throw new GitNotInstalledError();
+  }
+}
+
+/**
+ * Heuristic: does this error look like the "git executable not found" failure
+ * Bun throws when it can't resolve the binary? Used as a belt-and-suspenders
+ * catch around `Bun.spawn(["git", ...])` so a spawn that slips past the
+ * preflight (race where git is removed between check and spawn, or a code path
+ * that didn't preflight) still surfaces the friendly error instead of the raw
+ * `Executable not found in $PATH: "git"` string.
+ */
+export function isGitNotFoundSpawnError(err: unknown): boolean {
+  if (!(err instanceof Error)) return false;
+  const msg = err.message ?? "";
+  // Bun: `Executable not found in $PATH: "git"`.
+  // Node/posix: ENOENT spawn errors mention the missing file.
+  return (
+    (msg.includes("Executable not found") && msg.includes("git")) ||
+    ((err as { code?: string }).code === "ENOENT" && msg.includes("git"))
+  );
+}

package/src/mirror-config.test.ts

@@ -23,6 +23,7 @@ import {
   validateExternalPath,
   validateMirrorConfigShape,
 } from "./mirror-config.ts";
+import { GitNotInstalledError } from "./git-preflight.ts";
 
 function tmp(prefix: string): string {
   return fs.mkdtempSync(path.join(os.tmpdir(), prefix));
@@ -496,6 +497,19 @@ describe("validateExternalPath", () => {
     expect(r.ok).toBe(true);
     if (r.ok) expect(r.resolved_path).toBe(dir);
   });
+
+  test("git not installed → throws GitNotInstalledError (route maps to 503)", async () => {
+    // vault#415 nit — the isGitRepo() check shells `git`. On a git-less
+    // server, throw the friendly error (handleMirrorPut maps it to 503
+    // git_not_installed) instead of a raw "Executable not found" crash.
+    // Force the preflight via the `which` seam; a real, valid git repo is
+    // used so the ONLY failure source is the preflight.
+    dir = tmp("mirror-validate-nogit-installed-");
+    initRepo(dir);
+    await expect(validateExternalPath(dir, () => null)).rejects.toBeInstanceOf(
+      GitNotInstalledError,
+    );
+  });
 });
 
 // ---------------------------------------------------------------------------

package/src/mirror-config.ts

@@ -45,6 +45,7 @@ import { homedir } from "os";
 
 import { DEFAULT_COMMIT_TEMPLATE, isGitRepo } from "./export-watch.ts";
 import { readCredentials, type MirrorCredentials } from "./mirror-credentials.ts";
+import { ensureGitAvailable } from "./git-preflight.ts";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -888,7 +889,17 @@ export type PathValidation = PathValidationOk | PathValidationError;
  */
 export async function validateExternalPath(
   externalPath: string,
+  // Test seam for the git-presence preflight (default `Bun.which`). Inject a
+  // fn returning `null` to exercise the git-not-installed path.
+  which?: (cmd: string) => string | null,
 ): Promise<PathValidation> {
+  // Preflight: the git-repo check below shells `git`. On a git-less server,
+  // throw the friendly, actionable GitNotInstalledError (which handleMirrorPut
+  // maps to a 503 `git_not_installed`, consistent with the import route)
+  // instead of letting `isGitRepo`'s `Bun.spawn` throw a raw
+  // "Executable not found in $PATH: \"git\"".
+  ensureGitAvailable(which);
+
   if (!existsSync(externalPath)) {
     return {
       ok: false,

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,
@@ -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;
 }
 
 /**
@@ -315,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;
@@ -365,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);
   }

package/src/mirror-manager.test.ts

@@ -215,6 +215,21 @@ describe("bootstrapInternalMirror", () => {
       expect(isGitRepoSync(dir)).toBe(true);
     }
   });
+
+  test("git missing → ok:false with actionable error (status surfaces it, no raw crash)", async () => {
+    // vault#415 — a git-less server can't bootstrap a mirror. The error
+    // channel carries the friendly message that MirrorManager.start threads
+    // into status.last_error, instead of a raw "Executable not found" crash.
+    dir = path.join(tmp("mirror-boot-nogit-"), "mirror");
+    const r = await bootstrapInternalMirror(dir, () => null);
+    expect(r.ok).toBe(false);
+    if (!r.ok) {
+      expect(r.error).toContain("git is required");
+      expect(r.error).toContain("dnf install git");
+    }
+    // Failed fast at the preflight — the dir was never created.
+    expect(fs.existsSync(dir)).toBe(false);
+  });
 });
 
 // ---------------------------------------------------------------------------
@@ -378,6 +393,42 @@ describe("MirrorManager.start — lifecycle matrix", () => {
     fs.rmSync(external, { recursive: true, force: true });
   });
 
+  test("external + git not installed → enabled:false with friendly error, never spawns/exports", async () => {
+    // vault#415 nit — the external branch's isGitRepo() check shells `git`
+    // with no preflight; on a git-less server it would throw a raw
+    // "Executable not found in $PATH: \"git\"" and crash start(). The
+    // top-of-start() preflight (forced via the `which` seam) lands the
+    // friendly, actionable message in last_error for the external location.
+    home = tmp("mgr-ext-nogit-installed-");
+    fs.mkdirSync(path.join(home, "vault", "data", "default"), { recursive: true });
+    // Use a real, valid external git repo so the ONLY thing that can fail is
+    // the git-presence preflight — proving the preflight (not the path/repo
+    // checks) produced the disabled state.
+    const external = tmp("mgr-ext-nogit-target-");
+    initRepo(external);
+    seedCommit(external);
+    const deps = makeFakeDeps({
+      parachuteHome: home,
+      initialConfig: {
+        ...defaultMirrorConfig(),
+        enabled: true,
+        location: "external",
+        external_path: external,
+        sync_mode: "events",
+      },
+    });
+    const mgr = new MirrorManager(deps);
+    // Force the preflight to see no git on PATH.
+    const status = await mgr.start(() => null);
+    expect(status.enabled).toBe(false);
+    expect(status.last_error).toContain("git is required");
+    expect(status.last_error).toContain("dnf install git");
+    // Never reached export — the preflight bailed before any git work.
+    expect(deps.exportCalls).toHaveLength(0);
+    await mgr.stop();
+    fs.rmSync(external, { recursive: true, force: true });
+  });
+
   test("internal bootstrap refuses to clobber pre-existing non-git data", async () => {
     home = tmp("mgr-int-clobber-");
     const mirrorPath = path.join(home, "vault", "data", "default", "mirror");

package/src/mirror-manager.ts

@@ -75,6 +75,7 @@ import {
   applyToGitRemote,
   readCredentials,
 } from "./mirror-credentials.ts";
+import { GitNotInstalledError, ensureGitAvailable } from "./git-preflight.ts";
 import type { HookRegistry } from "../core/src/hooks.ts";
 
 /**
@@ -230,7 +231,20 @@ export type BootstrapResult = BootstrapResultOk | BootstrapResultError;
  */
 export async function bootstrapInternalMirror(
   path: string,
+  // Test seam for the git-presence preflight (default `Bun.which`). Inject a
+  // fn returning `null` to exercise the git-not-installed bootstrap path.
+  which?: (cmd: string) => string | null,
 ): Promise<BootstrapResult> {
+  // Preflight: a git-less server can't bootstrap a mirror. Surface the
+  // friendly, actionable message into the bootstrap-error channel so the
+  // caller threads it into mirror status (`last_error`) rather than letting
+  // a raw `Executable not found in $PATH: "git"` crash out of the spawn.
+  try {
+    ensureGitAvailable(which);
+  } catch (err) {
+    return { ok: false, error: (err as Error).message };
+  }
+
   if (existsSync(path)) {
     let stat;
     try {
@@ -466,7 +480,11 @@ export class MirrorManager {
    * Returns the final status snapshot — useful for tests + the PUT
    * endpoint response.
    */
-  async start(): Promise<MirrorStatus> {
+  async start(
+    // Test seam for the git-presence preflight (default `Bun.which`). Inject
+    // a fn returning `null` to exercise the git-not-installed start path.
+    which?: (cmd: string) => string | null,
+  ): Promise<MirrorStatus> {
     this.startCount++;
     await this.stop({ preserveStatus: true });
 
@@ -501,6 +519,24 @@ export class MirrorManager {
     }
     this.status.mirror_path = path;
 
+    // Preflight git BEFORE branching on location. Both branches shell `git`
+    // (internal → bootstrapInternalMirror; external → isGitRepo). On a
+    // git-less server the external branch's `isGitRepo` would otherwise throw
+    // a raw "Executable not found in $PATH: \"git\"" and crash start();
+    // catching it here lands the friendly, actionable message in
+    // status.last_error (disabled) for either location, uniformly.
+    try {
+      ensureGitAvailable(which);
+    } catch (err) {
+      if (err instanceof GitNotInstalledError) {
+        this.status.enabled = false;
+        this.status.last_error = err.message;
+        console.warn(`[mirror] ${err.message}`);
+        return this.getStatus();
+      }
+      throw err;
+    }
+
     // Internal bootstrap. External path is the operator's responsibility —
     // they should have validated via the PUT endpoint before we hit boot.
     // We re-check `isGitRepo` defensively here either way; a missing/non-
@@ -641,9 +677,13 @@ export class MirrorManager {
    * the operator-intended config on disk; on the next vault boot it
    * applies cleanly.
    */
-  async reload(newConfig: MirrorConfig): Promise<MirrorStatus> {
+  async reload(
+    newConfig: MirrorConfig,
+    // Test seam forwarded to `start()` — see `start(which)`.
+    which?: (cmd: string) => string | null,
+  ): Promise<MirrorStatus> {
     this.deps.writeMirrorConfig(newConfig);
-    return this.start();
+    return this.start(which);
   }
 
   /**
@@ -887,14 +927,25 @@ export class MirrorManager {
     }
 
     const firstNoteTitle = await this.deps.firstChangedNoteTitle(sinceCursor);
-    const commitResult = await runGitCommitCycle({
-      repoDir: path,
-      template: this.currentConfig.commit_template,
-      notesChanged: totalChanged,
-      vaultName: this.deps.vaultName,
-      firstNoteTitle,
-      push: this.currentConfig.auto_push,
-    });
+    let commitResult: Awaited<ReturnType<typeof runGitCommitCycle>>;
+    try {
+      commitResult = await runGitCommitCycle({
+        repoDir: path,
+        template: this.currentConfig.commit_template,
+        notesChanged: totalChanged,
+        vaultName: this.deps.vaultName,
+        firstNoteTitle,
+        push: this.currentConfig.auto_push,
+      });
+    } catch (err) {
+      // git-not-installed (or any commit-cycle throw) lands in status as a
+      // friendly last_error rather than crashing the cycle. Matches the
+      // "errors reflected in last_error, never rethrown" contract above.
+      const msg = (err as Error).message ?? String(err);
+      this.status.last_error = `commit cycle failed: ${msg}`;
+      console.warn(`[mirror] ${this.status.last_error}`);
+      return;
+    }
 
     if (commitResult.committed) {
       // Resolve the new HEAD sha so the status displays the commit that
@@ -950,6 +1001,17 @@ export class MirrorManager {
     if (!this.status.enabled) return { fired: false, reason: "not_enabled" };
     if (!this.status.mirror_path) return { fired: false, reason: "no_mirror_path" };
     const path = this.status.mirror_path;
+    // Preflight: git-less server can't push. Surface the friendly message
+    // into last_push_error (the SPA renders it) rather than throwing a raw
+    // "Executable not found" out of the gitPush spawn.
+    try {
+      ensureGitAvailable();
+    } catch (err) {
+      const msg = (err as Error).message ?? String(err);
+      this.status.last_push_error = msg;
+      console.warn(`[mirror] push-now failed: ${msg}`);
+      return { fired: true, pushed: false, error: msg };
+    }
     const pushResult = await gitPush(path);
     const now = new Date().toISOString();
     // Refresh commits_unpushed either way — a no-op push still reflects

package/src/mirror-routes.test.ts

@@ -245,6 +245,37 @@ describe("handleMirrorPut", () => {
     }
   });
 
+  test("external + git not installed → 503 git_not_installed + actionable message", async () => {
+    // vault#415 nit — handleMirrorPut validates the external path via
+    // validateExternalPath, which shells `git`. On a git-less server it must
+    // return the friendly 503 (consistent with the import route), not let a
+    // raw "Executable not found" crash out. Force the preflight via the
+    // whichOverride seam against a REAL git repo so the only failure is the
+    // preflight.
+    home = tmp("mirror-put-nogit-installed-");
+    const { manager } = makeManager(home);
+    const external = tmp("mirror-put-nogit-target-");
+    initRepo(external);
+    try {
+      const req = new Request("http://x/admin/mirror", {
+        method: "PUT",
+        body: JSON.stringify({
+          enabled: true,
+          location: "external",
+          external_path: external,
+        }),
+      });
+      const res = await handleMirrorPut(req, manager, () => null);
+      expect(res.status).toBe(503);
+      const body = (await res.json()) as { error_type: string; message: string };
+      expect(body.error_type).toBe("git_not_installed");
+      expect(body.message).toContain("git is required");
+      expect(body.message).toContain("dnf install git");
+    } finally {
+      fs.rmSync(external, { recursive: true, force: true });
+    }
+  });
+
   test("accepts a valid external config, persists, restarts watch", async () => {
     home = tmp("mirror-put-happy-");
     const external = tmp("mirror-put-ext-");
@@ -1258,6 +1289,35 @@ describe("handleMirrorImport", () => {
     expect(body.message).toContain("vault.yaml");
   });
 
+  test("git not installed returns 503 + git_not_installed + actionable message", async () => {
+    // vault#415 — live bug on a git-less Amazon Linux EC2 box. Force the
+    // preflight (via the whichOverride seam) to see no git; the spawn seam
+    // should never be reached.
+    home = tmp("import-route-nogit-");
+    await bootstrapVault(home);
+    let spawnCalled = false;
+    const spyingSpawn: GitSpawn = async () => {
+      spawnCalled = true;
+      return { exitCode: 0, stderr: "", timedOut: false };
+    };
+    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", spyingSpawn, () => null);
+    expect(res.status).toBe(503);
+    const body = (await res.json()) as { error_type: string; message: string };
+    expect(body.error_type).toBe("git_not_installed");
+    expect(body.message).toContain("git is required");
+    expect(body.message).toContain("dnf install git");
+    // Failed fast: the git spawn was never reached.
+    expect(spawnCalled).toBe(false);
+  });
+
   test("uses stored credentials when credentials: null (credentialsFile path)", async () => {
     home = tmp("import-route-stored-creds-");
     await bootstrapVault(home);

package/src/mirror-routes.ts

@@ -62,6 +62,7 @@ import {
   type ImportResult,
 } from "./mirror-import.ts";
 import { redactToken } from "./export-watch.ts";
+import { GitNotInstalledError, ensureGitAvailable } from "./git-preflight.ts";
 import { getVaultStore } from "./vault-store.ts";
 import { assetsDir } from "./routes.ts";
 
@@ -120,6 +121,10 @@ export function handleMirrorGet(manager: MirrorManager): Response {
 export async function handleMirrorPut(
   req: Request,
   manager: MirrorManager,
+  // Test seam for the external-path git-presence preflight (default
+  // `Bun.which` inside `validateExternalPath`). Inject a fn returning `null`
+  // to exercise the git_not_installed 503 path without uninstalling git.
+  whichOverride?: (cmd: string) => string | null,
 ): Promise<Response> {
   let body: unknown;
   try {
@@ -154,7 +159,25 @@ export async function handleMirrorPut(
   // to *do* something with an external path. Disabling the mirror by-
   // flipping enabled to false shouldn't fail because the path went away.
   if (config.enabled && config.location === "external" && config.external_path) {
-    const pathCheck = await validateExternalPath(config.external_path);
+    let pathCheck;
+    try {
+      pathCheck = await validateExternalPath(config.external_path, whichOverride);
+    } catch (err) {
+      if (err instanceof GitNotInstalledError) {
+        // 503 git_not_installed — consistent with the import route. The
+        // server can't validate (or later sync) an external git mirror
+        // without git installed; the message tells the operator how to fix.
+        return Response.json(
+          {
+            error: "git not installed",
+            error_type: "git_not_installed",
+            message: err.message,
+          },
+          { status: 503 },
+        );
+      }
+      throw err;
+    }
     if (!pathCheck.ok) {
       return Response.json(
         {
@@ -597,6 +620,26 @@ export async function handleAuthPat(
     );
   }
 
+  // Preflight: the validation probe (`git ls-remote`) and every later push
+  // shell `git`. On a git-less server, surface the friendly, actionable
+  // 503 instead of letting the probe's `Bun.spawn` throw a raw
+  // "Executable not found in $PATH: \"git\"".
+  try {
+    ensureGitAvailable();
+  } catch (err) {
+    if (err instanceof GitNotInstalledError) {
+      return Response.json(
+        {
+          error: "git not installed",
+          error_type: "git_not_installed",
+          message: err.message,
+        },
+        { status: 503 },
+      );
+    }
+    throw err;
+  }
+
   // Validate via `git ls-remote <embedded-auth-url>` — uses the same
   // x-access-token shape we'd embed at push time so the probe exercises
   // the actual auth path. If the operator pasted a URL that already has
@@ -1089,11 +1132,16 @@ export async function applyCredentialsToMirror(
  *
  * `spawnOverride` is a test seam: lets the test inject a fake git binary.
  * Production callers omit it; `cloneAndImport` falls back to `defaultGitSpawn`.
+ *
+ * `whichOverride` is a test seam for the git-presence preflight (default
+ * `Bun.which` inside `cloneAndImport`). Inject a fn returning `null` to
+ * exercise the git_not_installed 503 path without uninstalling git.
  */
 export async function handleMirrorImport(
   req: Request,
   vaultName: string,
   spawnOverride?: GitSpawn,
+  whichOverride?: (cmd: string) => string | null,
 ): Promise<Response> {
   let body: {
     remote_url?: unknown;
@@ -1208,8 +1256,21 @@ export async function handleMirrorImport(
       store,
       assetsDir: assets,
       spawn: spawnOverride,
+      which: whichOverride,
     });
   } catch (err) {
+    if (err instanceof GitNotInstalledError) {
+      // 503 Service Unavailable — the server isn't configured to do this
+      // yet (git missing). The message tells the operator how to fix it.
+      return Response.json(
+        {
+          error: "git not installed",
+          error_type: "git_not_installed",
+          message: err.message,
+        },
+        { status: 503 },
+      );
+    }
     if (err instanceof ImportConflictError) {
       return Response.json(
         {