@openparachute/vault 0.6.4-rc.7 → 0.6.4-rc.8

package/package.json

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

package/src/cli.ts

@@ -110,11 +110,17 @@ import { getVaultStore } from "./vault-store.ts";
 import { seedOnboardingNotesBestEffort } from "./onboarding-seed.ts";
 import {
   defaultMirrorConfig,
+  readMirrorConfigForVault,
   resolveMirrorPath,
   writeMirrorConfigForVault,
   type MirrorConfig,
 } from "./mirror-config.ts";
-import { bootstrapInternalMirror } from "./mirror-manager.ts";
+import {
+  bootstrapInternalMirror,
+  readMirrorHistory,
+  showMirrorRevision,
+} from "./mirror-manager.ts";
+import { GitNotInstalledError, ensureGitAvailable } from "./git-preflight.ts";
 import { selfRegister } from "./self-register.ts";
 import {
   hasOwnerPassword,
@@ -234,6 +240,9 @@ switch (command) {
   case "export":
     await cmdExport(cmdArgs);
     break;
+  case "history":
+    await cmdHistory(cmdArgs);
+    break;
   case "schema":
     await cmdSchema(cmdArgs);
     break;
@@ -3330,6 +3339,163 @@ async function cmdExport(args: string[]) {
   await new Promise(() => {});
 }
 
+// ---------------------------------------------------------------------------
+// `parachute-vault history` — surface the vault's git write history (vault#300)
+// ---------------------------------------------------------------------------
+
+/**
+ * `parachute-vault history [--note <path>] [--limit N] [--vault <name>] [--json]`
+ *
+ * Surfaces the mirror's git commit log — the vault is already git-backed
+ * (one file per note), so `git log` IS a tamper-evident, diffable write
+ * history. This CLI front-door wraps the SAME `readMirrorHistory` helper the
+ * REST `/history` endpoint uses (no drift between the two surfaces).
+ *
+ * `--note <path>` scopes to a single note's history (`git log --follow --
+ * <path>.md`). `--show <sha>` (with `--note`) prints that note's content at
+ * a past revision (`git show <sha>:<path>.md`).
+ */
+async function cmdHistory(args: string[]) {
+  let vaultName = "default";
+  let notePath: string | undefined;
+  let limit: number | undefined;
+  let showSha: string | undefined;
+  let asJson = false;
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]!;
+    if (arg === "--vault") {
+      const v = args[++i];
+      if (!v) {
+        console.error("--vault requires a value.");
+        process.exit(1);
+      }
+      vaultName = v;
+    } else if (arg === "--note") {
+      const v = args[++i];
+      if (!v) {
+        console.error("--note requires a note path.");
+        process.exit(1);
+      }
+      notePath = v;
+    } else if (arg === "--limit") {
+      const v = args[++i];
+      if (!v) {
+        console.error("--limit requires a number.");
+        process.exit(1);
+      }
+      const n = Number(v);
+      if (!Number.isInteger(n) || n <= 0) {
+        console.error(`--limit: must be a positive integer (got '${v}')`);
+        process.exit(1);
+      }
+      limit = n;
+    } else if (arg === "--show") {
+      const v = args[++i];
+      if (!v) {
+        console.error("--show requires a commit sha.");
+        process.exit(1);
+      }
+      showSha = v;
+    } else if (arg === "--json") {
+      asJson = true;
+    } else if (arg === "--help" || arg === "-h") {
+      printHistoryUsage();
+      return;
+    } else {
+      console.error(`Unknown argument: ${arg}`);
+      printHistoryUsage();
+      process.exit(1);
+    }
+  }
+
+  if (showSha && !notePath) {
+    console.error("--show <sha> requires --note <path> (which file to read at that revision).");
+    process.exit(1);
+  }
+
+  const config = readVaultConfig(vaultName);
+  if (!config) {
+    console.error(`Vault "${vaultName}" not found. Available: ${listVaults().join(", ") || "(none)"}.`);
+    process.exit(1);
+  }
+
+  // Resolve the mirror dir the same way the server does: per-vault mirror
+  // config (or defaults) → resolveMirrorPath against the vault's data dir.
+  const mirrorConfig = readMirrorConfigForVault(vaultName) ?? defaultMirrorConfig();
+  const mirrorPath = resolveMirrorPath(vaultDir(vaultName), mirrorConfig);
+  if (!mirrorPath || !existsSync(mirrorPath)) {
+    console.error(
+      `No git history for vault "${vaultName}" — the mirror isn't initialized yet.\n` +
+        `Enable history (backup) so writes are recorded, then re-run.`,
+    );
+    process.exit(1);
+  }
+
+  // Preflight git — friendly, actionable message instead of a raw spawn throw.
+  try {
+    ensureGitAvailable();
+  } catch (err) {
+    if (err instanceof GitNotInstalledError) {
+      console.error(err.message);
+      process.exit(1);
+    }
+    throw err;
+  }
+
+  // `--show` path: print one note's content at a past revision.
+  if (showSha && notePath) {
+    const content = await showMirrorRevision(mirrorPath, showSha, notePath);
+    if (content === null) {
+      console.error(
+        `No content for "${notePath}" at ${showSha} — the sha may be unknown, the note may not have existed at that commit, or the path is invalid.`,
+      );
+      process.exit(1);
+    }
+    process.stdout.write(content);
+    return;
+  }
+
+  const history = await readMirrorHistory(mirrorPath, { notePath, limit });
+
+  if (asJson) {
+    console.log(JSON.stringify(history, null, 2));
+    return;
+  }
+
+  if (history.length === 0) {
+    if (notePath) {
+      console.log(`No history for note "${notePath}" in vault "${vaultName}".`);
+    } else {
+      console.log(`No history yet for vault "${vaultName}".`);
+    }
+    return;
+  }
+
+  const scope = notePath ? ` for "${notePath}"` : "";
+  console.log(`Git history for vault "${vaultName}"${scope} (${history.length} commit${history.length === 1 ? "" : "s"}):\n`);
+  for (const entry of history) {
+    // Short sha + date + subject — one line per commit, the `git log --oneline`
+    // shape an operator expects.
+    console.log(`  ${entry.sha.slice(0, 8)}  ${entry.date}  ${entry.message}`);
+  }
+}
+
+function printHistoryUsage(): void {
+  console.error(
+    "Usage: parachute-vault history [--note <path>] [--limit N] [--vault <name>] [--json]\n" +
+      "                              [--note <path> --show <sha>]",
+  );
+  console.error("\nSurface the vault's git write history. The vault is already git-backed via the");
+  console.error("mirror (one file per note), so `git log` IS a tamper-evident, diffable history.");
+  console.error("\nOptions:");
+  console.error("  --vault <name>   Vault to read (default: 'default')");
+  console.error("  --note <path>    Scope to a single note's history (git log --follow)");
+  console.error("  --limit N        Cap the number of commits returned (default 100)");
+  console.error("  --show <sha>     With --note: print that note's content at the given revision");
+  console.error("  --json           Emit the history as JSON instead of the human-readable list");
+}
+
 // ---------------------------------------------------------------------------
 // Schema maintenance — `parachute-vault schema <subcommand>`
 // ---------------------------------------------------------------------------
@@ -4106,6 +4272,15 @@ Import/Export:
                                                        template via --git-message-template;
                                                        --git-push to push after commit)
 
+History:
+  parachute-vault history [--vault <name>]             Show the vault's git write history (the
+                                                       mirror is git-backed — one file per note,
+                                                       so git log IS a tamper-evident history)
+  parachute-vault history --note <path>                Scope to one note's history (git log --follow)
+  parachute-vault history --limit N                    Cap the number of commits (default 100)
+  parachute-vault history --note <path> --show <sha>   Print that note's content at a past revision
+  parachute-vault history --json                       Emit history as JSON
+
 Schema maintenance:
   parachute-vault schema prune [--vault <name>]       Drop orphaned indexed-field columns +
                                                        indexes whose declaring tags no longer

package/src/mirror-history.test.ts

@@ -0,0 +1,426 @@
+/**
+ * Tests for the git-history read surface (vault#300).
+ *
+ * The vault is already git-backed via the mirror — one file per note — so
+ * `git log` IS the write history. These tests exercise:
+ *   - the `readMirrorHistory` / `showMirrorRevision` / `noteHistoryPathspec`
+ *     helpers (mirror-manager.ts) against a real seeded git repo in a tmpdir
+ *   - the `handleMirrorHistory` / `handleMirrorHistoryShow` REST handlers
+ *     (mirror-routes.ts), including the not-initialized + path-scoped cases
+ *
+ * Routing-level admin-gate enforcement lives in routing.test.ts (alongside
+ * the sibling mirror routes); these are the after-auth handler + helper
+ * tests, matching the mirror-manager / mirror-routes test split.
+ *
+ * Like the other mirror tests: real tempdirs + real `git` so we exercise
+ * the actual log/show behavior, not a mock.
+ */
+
+import { describe, test, expect, afterEach, afterAll } from "bun:test";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import {
+  HISTORY_MAX_LIMIT,
+  noteHistoryPathspec,
+  readMirrorHistory,
+  showMirrorRevision,
+  MirrorManager,
+  type MirrorDeps,
+} from "./mirror-manager.ts";
+import {
+  handleMirrorHistory,
+  handleMirrorHistoryShow,
+} from "./mirror-routes.ts";
+import { defaultMirrorConfig, type MirrorConfig } from "./mirror-config.ts";
+
+// Keep HOME / PARACHUTE_HOME from leaking between test files — same pattern
+// as mirror-manager.test.ts.
+const ORIG_HOME = process.env.HOME;
+const ORIG_PARACHUTE_HOME = process.env.PARACHUTE_HOME;
+afterEach(() => {
+  if (ORIG_HOME === undefined) delete process.env.HOME;
+  else process.env.HOME = ORIG_HOME;
+  if (ORIG_PARACHUTE_HOME === undefined) delete process.env.PARACHUTE_HOME;
+  else process.env.PARACHUTE_HOME = ORIG_PARACHUTE_HOME;
+});
+afterAll(() => {
+  if (ORIG_HOME === undefined) delete process.env.HOME;
+  else process.env.HOME = ORIG_HOME;
+});
+
+function tmp(prefix: string): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+}
+
+function initRepo(dir: string): void {
+  Bun.spawnSync(["git", "init", "-q", "-b", "main"], { cwd: dir });
+  Bun.spawnSync(["git", "config", "user.email", "t@p.computer"], { cwd: dir });
+  Bun.spawnSync(["git", "config", "user.name", "T P"], { cwd: dir });
+  Bun.spawnSync(["git", "config", "commit.gpgsign", "false"], { cwd: dir });
+}
+
+/** Write a file (creating parent dirs), `git add -A`, commit with `message`. */
+function commitFile(dir: string, relPath: string, content: string, message: string): void {
+  const full = path.join(dir, relPath);
+  fs.mkdirSync(path.dirname(full), { recursive: true });
+  fs.writeFileSync(full, content);
+  Bun.spawnSync(["git", "add", "-A"], { cwd: dir });
+  Bun.spawnSync(["git", "commit", "-q", "-m", message], { cwd: dir });
+}
+
+// ---------------------------------------------------------------------------
+// noteHistoryPathspec — normalize + traversal guard
+// ---------------------------------------------------------------------------
+
+describe("noteHistoryPathspec", () => {
+  test("appends .md to a bare note path", () => {
+    expect(noteHistoryPathspec("Inbox/today")).toBe("Inbox/today.md");
+  });
+
+  test("is idempotent on an already-suffixed path", () => {
+    expect(noteHistoryPathspec("Inbox/today.md")).toBe("Inbox/today.md");
+  });
+
+  test("rejects traversal", () => {
+    expect(noteHistoryPathspec("../etc/passwd")).toBeNull();
+    expect(noteHistoryPathspec("Inbox/../../secret")).toBeNull();
+  });
+
+  test("rejects absolute paths", () => {
+    expect(noteHistoryPathspec("/etc/passwd")).toBeNull();
+  });
+
+  test("rejects empty / whitespace", () => {
+    expect(noteHistoryPathspec("")).toBeNull();
+    expect(noteHistoryPathspec("   ")).toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// readMirrorHistory — the core git-log read
+// ---------------------------------------------------------------------------
+
+describe("readMirrorHistory", () => {
+  test("returns commits newest-first with sha/date/message", async () => {
+    const dir = tmp("vault-history-");
+    initRepo(dir);
+    commitFile(dir, "Inbox/one.md", "one", "export: first (1 note)");
+    commitFile(dir, "Inbox/two.md", "two", "export: second (1 note)");
+
+    const history = await readMirrorHistory(dir);
+    expect(history.length).toBe(2);
+    // Newest first.
+    expect(history[0]!.message).toBe("export: second (1 note)");
+    expect(history[1]!.message).toBe("export: first (1 note)");
+    // Each entry has a full sha + an ISO date.
+    for (const entry of history) {
+      expect(entry.sha).toMatch(/^[0-9a-f]{40}$/);
+      expect(Number.isNaN(Date.parse(entry.date))).toBe(false);
+    }
+  });
+
+  test("?path filters to a single note's commits, --follow across renames", async () => {
+    const dir = tmp("vault-history-path-");
+    initRepo(dir);
+    commitFile(dir, "Notes/alpha.md", "a1", "export: alpha created");
+    commitFile(dir, "Notes/beta.md", "b1", "export: beta created");
+    commitFile(dir, "Notes/alpha.md", "a2", "export: alpha edited");
+
+    const alpha = await readMirrorHistory(dir, { notePath: "Notes/alpha" });
+    // Two commits touched alpha; beta's commit is excluded.
+    expect(alpha.length).toBe(2);
+    expect(alpha.map((e) => e.message)).toEqual([
+      "export: alpha edited",
+      "export: alpha created",
+    ]);
+
+    const beta = await readMirrorHistory(dir, { notePath: "Notes/beta" });
+    expect(beta.length).toBe(1);
+    expect(beta[0]!.message).toBe("export: beta created");
+  });
+
+  test("limit caps the number of commits returned", async () => {
+    const dir = tmp("vault-history-limit-");
+    initRepo(dir);
+    for (let i = 0; i < 5; i++) {
+      commitFile(dir, `Notes/n${i}.md`, `v${i}`, `export: commit ${i}`);
+    }
+    const limited = await readMirrorHistory(dir, { limit: 2 });
+    expect(limited.length).toBe(2);
+    // Newest two.
+    expect(limited[0]!.message).toBe("export: commit 4");
+    expect(limited[1]!.message).toBe("export: commit 3");
+  });
+
+  test("an out-of-range limit is clamped to HISTORY_MAX_LIMIT (never exceeds the ceiling)", async () => {
+    const dir = tmp("vault-history-ceiling-");
+    initRepo(dir);
+    // Seed just a few commits — the assertion is on the ARG cap, not commit
+    // count: an absurd limit must never spawn `git log` with --max-count
+    // above the hard ceiling. With <ceiling commits the result is bounded by
+    // commit count, so we assert it's never MORE than the ceiling.
+    commitFile(dir, "Notes/a.md", "a", "export: a");
+    commitFile(dir, "Notes/b.md", "b", "export: b");
+    const history = await readMirrorHistory(dir, { limit: 99_999_999 });
+    expect(history.length).toBeLessThanOrEqual(HISTORY_MAX_LIMIT);
+    // Sanity: a huge limit still returns the (few) real commits.
+    expect(history.length).toBe(2);
+  });
+
+  test("no commits yet → empty list, not an error", async () => {
+    const dir = tmp("vault-history-empty-");
+    initRepo(dir); // repo but no commits
+    const history = await readMirrorHistory(dir);
+    expect(history).toEqual([]);
+  });
+
+  test("not a git repo → empty list, not an error", async () => {
+    const dir = tmp("vault-history-nonrepo-");
+    // No `git init`.
+    const history = await readMirrorHistory(dir);
+    expect(history).toEqual([]);
+  });
+
+  test("a path with no history → empty list", async () => {
+    const dir = tmp("vault-history-nopath-");
+    initRepo(dir);
+    commitFile(dir, "Notes/exists.md", "x", "export: exists");
+    const history = await readMirrorHistory(dir, { notePath: "Notes/ghost" });
+    expect(history).toEqual([]);
+  });
+
+  test("an unsafe path → empty list (never an unscoped log)", async () => {
+    const dir = tmp("vault-history-unsafe-");
+    initRepo(dir);
+    commitFile(dir, "Notes/a.md", "a", "export: a");
+    commitFile(dir, "Notes/b.md", "b", "export: b");
+    // A traversal path must NOT fall back to the full (unscoped) log.
+    const history = await readMirrorHistory(dir, { notePath: "../../../etc/passwd" });
+    expect(history).toEqual([]);
+  });
+
+  test("redacts tokens that appear in a commit subject", async () => {
+    const dir = tmp("vault-history-redact-");
+    initRepo(dir);
+    commitFile(dir, "Notes/a.md", "a", "synced from https://x-access-token:ghp_supersecrettoken123@github.com/a/b");
+    const history = await readMirrorHistory(dir);
+    expect(history.length).toBe(1);
+    expect(history[0]!.message).not.toContain("ghp_supersecrettoken123");
+    expect(history[0]!.message).toContain("***");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// showMirrorRevision — read a past revision of a note
+// ---------------------------------------------------------------------------
+
+describe("showMirrorRevision", () => {
+  test("returns the file content at a past revision", async () => {
+    const dir = tmp("vault-show-");
+    initRepo(dir);
+    commitFile(dir, "Notes/a.md", "version one", "export: a v1");
+    // Capture the sha at v1.
+    const v1 = (await readMirrorHistory(dir))[0]!.sha;
+    commitFile(dir, "Notes/a.md", "version two", "export: a v2");
+
+    const past = await showMirrorRevision(dir, v1, "Notes/a");
+    expect(past).toBe("version one");
+
+    const current = await showMirrorRevision(dir, (await readMirrorHistory(dir))[0]!.sha, "Notes/a");
+    expect(current).toBe("version two");
+  });
+
+  test("unknown sha → null", async () => {
+    const dir = tmp("vault-show-badsha-");
+    initRepo(dir);
+    commitFile(dir, "Notes/a.md", "x", "export: a");
+    const result = await showMirrorRevision(dir, "deadbeef", "Notes/a");
+    expect(result).toBeNull();
+  });
+
+  test("non-hex / option-looking sha → null (no smuggled ref)", async () => {
+    const dir = tmp("vault-show-refsmuggle-");
+    initRepo(dir);
+    commitFile(dir, "Notes/a.md", "x", "export: a");
+    expect(await showMirrorRevision(dir, "HEAD", "Notes/a")).toBeNull();
+    expect(await showMirrorRevision(dir, "--output=/tmp/x", "Notes/a")).toBeNull();
+  });
+
+  test("unsafe path → null", async () => {
+    const dir = tmp("vault-show-unsafe-");
+    initRepo(dir);
+    commitFile(dir, "Notes/a.md", "x", "export: a");
+    const sha = (await readMirrorHistory(dir))[0]!.sha;
+    expect(await showMirrorRevision(dir, sha, "../../../etc/passwd")).toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Route handlers — handleMirrorHistory / handleMirrorHistoryShow
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a MirrorManager whose status reports `mirror_path = mirrorPath`
+ * without standing up the full lifecycle — the history handlers only read
+ * `getStatus().mirror_path`, so we start a minimal enabled internal mirror
+ * pointed at a tmp repo we control.
+ *
+ * Simpler: construct the manager with fake deps and force the status by
+ * starting it against an internal mirror dir we then seed. But the history
+ * read is path-only, so we instead use a tiny manager whose deps resolve the
+ * internal mirror under a tmp PARACHUTE_HOME and start it (which bootstraps a
+ * real git repo), then commit into that repo.
+ */
+function makeStartedManager(home: string): { manager: MirrorManager; deps: MirrorDeps } {
+  process.env.PARACHUTE_HOME = home;
+  process.env.HOME = home;
+  fs.mkdirSync(path.join(home, "vault", "data", "default"), { recursive: true });
+  let stored: MirrorConfig | undefined = { ...defaultMirrorConfig(), enabled: true };
+  const deps: MirrorDeps = {
+    vaultName: "default",
+    runExport: async () => ({ notes: 0 }),
+    firstChangedNoteTitle: async () => "",
+    readMirrorConfig: () => stored,
+    writeMirrorConfig: (c) => {
+      stored = c;
+    },
+  };
+  return { manager: new MirrorManager(deps), deps };
+}
+
+describe("handleMirrorHistory route", () => {
+  test("not-initialized mirror → 200 empty history + note (not 500)", async () => {
+    const home = tmp("vault-route-noinit-");
+    const { manager } = makeStartedManager(home);
+    // Never started → no mirror_path resolved.
+    const res = await handleMirrorHistory(
+      new Request("http://localhost/vault/default/.parachute/mirror/history"),
+      manager,
+    );
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { history: unknown[]; mirror_path: null; note?: string };
+    expect(body.history).toEqual([]);
+    expect(body.mirror_path).toBeNull();
+    expect(body.note).toBeDefined();
+  });
+
+  test("started mirror with commits → 200 history list", async () => {
+    const home = tmp("vault-route-hist-");
+    const { manager } = makeStartedManager(home);
+    await manager.start();
+    const mirrorPath = manager.getStatus().mirror_path!;
+    expect(mirrorPath).toBeTruthy();
+    commitFile(mirrorPath, "Notes/a.md", "a", "export: a created");
+    commitFile(mirrorPath, "Notes/b.md", "b", "export: b created");
+
+    const res = await handleMirrorHistory(
+      new Request("http://localhost/vault/default/.parachute/mirror/history"),
+      manager,
+    );
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as {
+      history: Array<{ sha: string; date: string; message: string }>;
+      mirror_path: string;
+    };
+    // Includes the bootstrap commit + our two; newest first.
+    expect(body.history.length).toBeGreaterThanOrEqual(3);
+    expect(body.history[0]!.message).toBe("export: b created");
+    expect(body.mirror_path).toBe(mirrorPath);
+  });
+
+  test("?path scopes to one note", async () => {
+    const home = tmp("vault-route-histpath-");
+    const { manager } = makeStartedManager(home);
+    await manager.start();
+    const mirrorPath = manager.getStatus().mirror_path!;
+    commitFile(mirrorPath, "Notes/alpha.md", "a1", "export: alpha");
+    commitFile(mirrorPath, "Notes/beta.md", "b1", "export: beta");
+
+    const res = await handleMirrorHistory(
+      new Request("http://localhost/vault/default/.parachute/mirror/history?path=Notes/alpha"),
+      manager,
+    );
+    const body = (await res.json()) as {
+      history: Array<{ message: string }>;
+      path?: string;
+    };
+    expect(body.path).toBe("Notes/alpha");
+    expect(body.history.length).toBe(1);
+    expect(body.history[0]!.message).toBe("export: alpha");
+  });
+
+  test("?limit caps the count", async () => {
+    const home = tmp("vault-route-histlimit-");
+    const { manager } = makeStartedManager(home);
+    await manager.start();
+    const mirrorPath = manager.getStatus().mirror_path!;
+    for (let i = 0; i < 4; i++) commitFile(mirrorPath, `Notes/n${i}.md`, `v${i}`, `export: c${i}`);
+
+    const res = await handleMirrorHistory(
+      new Request("http://localhost/vault/default/.parachute/mirror/history?limit=2"),
+      manager,
+    );
+    const body = (await res.json()) as { history: unknown[] };
+    expect(body.history.length).toBe(2);
+  });
+
+  test("invalid limit → 400", async () => {
+    const home = tmp("vault-route-histbadlimit-");
+    const { manager } = makeStartedManager(home);
+    await manager.start();
+    const res = await handleMirrorHistory(
+      new Request("http://localhost/vault/default/.parachute/mirror/history?limit=-3"),
+      manager,
+    );
+    expect(res.status).toBe(400);
+  });
+});
+
+describe("handleMirrorHistoryShow route", () => {
+  test("returns a past revision's content", async () => {
+    const home = tmp("vault-route-show-");
+    const { manager } = makeStartedManager(home);
+    await manager.start();
+    const mirrorPath = manager.getStatus().mirror_path!;
+    commitFile(mirrorPath, "Notes/a.md", "v1 content", "export: a v1");
+    const sha = (await readMirrorHistory(mirrorPath, { notePath: "Notes/a" }))[0]!.sha;
+    commitFile(mirrorPath, "Notes/a.md", "v2 content", "export: a v2");
+
+    const res = await handleMirrorHistoryShow(
+      new Request(
+        `http://localhost/vault/default/.parachute/mirror/history/show?sha=${sha}&path=Notes/a`,
+      ),
+      manager,
+    );
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { content: string; sha: string; path: string };
+    expect(body.content).toBe("v1 content");
+    expect(body.path).toBe("Notes/a");
+  });
+
+  test("missing sha/path → 400", async () => {
+    const home = tmp("vault-route-show-missing-");
+    const { manager } = makeStartedManager(home);
+    await manager.start();
+    const res = await handleMirrorHistoryShow(
+      new Request("http://localhost/vault/default/.parachute/mirror/history/show?sha=abc123"),
+      manager,
+    );
+    expect(res.status).toBe(400);
+  });
+
+  test("unknown sha/path → 404", async () => {
+    const home = tmp("vault-route-show-404-");
+    const { manager } = makeStartedManager(home);
+    await manager.start();
+    const res = await handleMirrorHistoryShow(
+      new Request(
+        "http://localhost/vault/default/.parachute/mirror/history/show?sha=deadbeef&path=Notes/ghost",
+      ),
+      manager,
+    );
+    expect(res.status).toBe(404);
+  });
+});

package/src/mirror-manager.ts

@@ -369,6 +369,170 @@ async function readCurrentOrigin(repoDir: string): Promise<string | null> {
   return url.length > 0 ? url : null;
 }
 
+// ---------------------------------------------------------------------------
+// Git history read surface (vault#300)
+//
+// The vault is already git-backed via the mirror — one file per note, so
+// `git log` IS a tamper-evident, time-travelable, diffable write history.
+// These helpers SURFACE that history through the admin-gated REST + CLI
+// read paths. No write-path change, no schema change, no new table — the
+// history already exists on disk; we just read it.
+//
+// Same Bun.spawn-git shape as `readCommitsUnpushed` / `readCurrentOrigin`
+// above (spawn array argv, capture stdout, parse) so REST + CLI share ONE
+// implementation and there's no drift between them.
+// ---------------------------------------------------------------------------
+
+/** A single commit in the mirror's history. */
+export interface HistoryEntry {
+  /** Full commit sha. */
+  sha: string;
+  /** ISO-8601 author date (`%aI`). */
+  date: string;
+  /** Commit subject line (`%s`). */
+  message: string;
+}
+
+/** Default cap on how many commits a history read returns. */
+export const HISTORY_DEFAULT_LIMIT = 100;
+/** Hard ceiling — even an explicit `?limit=` can't exceed this. */
+export const HISTORY_MAX_LIMIT = 1000;
+
+/**
+ * Normalize + validate a note path for use as a `git log -- <path>.md`
+ * pathspec. Returns the `<path>.md` argv token, or null when the path is
+ * unsafe / empty.
+ *
+ * The path goes into an ARRAY-spawn argv (no shell), so this isn't guarding
+ * against shell injection — it's guarding against directory traversal
+ * (`..`) and absolute paths escaping the mirror dir, plus normalizing the
+ * leading-slash + trailing-`.md` shape so the pathspec matches the file the
+ * exporter actually wrote (`<note.path>.md`, see portable-md.ts).
+ */
+export function noteHistoryPathspec(notePath: string): string | null {
+  const trimmed = notePath.trim();
+  if (trimmed.length === 0) return null;
+  // Reject absolute paths and traversal — the pathspec must stay inside the
+  // mirror working tree. A `..` segment (or a leading `/`) could otherwise
+  // point `git log` at files outside the vault's note tree.
+  if (trimmed.startsWith("/")) return null;
+  const segments = trimmed.split("/");
+  if (segments.some((s) => s === "..")) return null;
+  // The exporter writes `<note.path>.md`. Accept a path the caller already
+  // suffixed with `.md` (idempotent) or bare; emit the `.md` form either way.
+  const base = trimmed.endsWith(".md") ? trimmed.slice(0, -3) : trimmed;
+  if (base.length === 0) return null;
+  return `${base}.md`;
+}
+
+/**
+ * Read the mirror's commit history via `git log`. Optionally scoped to a
+ * single note's file (`opts.notePath` → `git log --follow -- <path>.md`).
+ *
+ * Returns an ordered (newest-first) array of `{ sha, date, message }`.
+ * Tolerant of the not-yet-a-repo / no-commits-yet cases — those return an
+ * empty array rather than throwing, so a freshly-bootstrapped (or never-
+ * bootstrapped) mirror reads as "no history yet", not a 500.
+ *
+ * `git log` field separators: we use `%H` (full sha), `%aI` (ISO author
+ * date), `%s` (subject). A literal record separator (`\x1f`) joins the
+ * three fields and a literal unit separator (`\x1e`) terminates each record
+ * so a multi-line-unfriendly subject (it isn't — `%s` is the subject line
+ * only) or a commit message containing our delimiters can't desync parsing.
+ *
+ * The git binary preflight is the CALLER's responsibility (REST + CLI both
+ * call `ensureGitAvailable` before this) — but a missing-repo `git log`
+ * exits non-zero, which we map to `[]`, so even an un-preflighted call
+ * degrades to "empty" rather than a crash.
+ */
+export async function readMirrorHistory(
+  repoDir: string,
+  opts: { notePath?: string; limit?: number } = {},
+): Promise<HistoryEntry[]> {
+  const limit = Math.min(
+    Math.max(1, Math.floor(opts.limit ?? HISTORY_DEFAULT_LIMIT)),
+    HISTORY_MAX_LIMIT,
+  );
+  const FIELD_SEP = "\x1f";
+  const RECORD_SEP = "\x1e";
+  const format = `%H${FIELD_SEP}%aI${FIELD_SEP}%s${RECORD_SEP}`;
+  const args = [
+    "log",
+    `--max-count=${limit}`,
+    `--pretty=format:${format}`,
+  ];
+  if (opts.notePath) {
+    const spec = noteHistoryPathspec(opts.notePath);
+    // An unsafe / empty path yields no history rather than an unscoped log.
+    if (spec === null) return [];
+    // `--follow` traces the file across renames (the vault renames note
+    // files when a note's path changes). `--` ends the option list so the
+    // pathspec is never mistaken for a flag.
+    args.push("--follow", "--", spec);
+  }
+  const proc = Bun.spawn(["git", ...args], {
+    cwd: repoDir,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const exitCode = await proc.exited;
+  // Non-zero: not a git repo, no commits yet, or a path with no history.
+  // All map to "empty history" — never a thrown error.
+  if (exitCode !== 0) return [];
+  const out = new TextDecoder().decode(
+    await new Response(proc.stdout).arrayBuffer(),
+  );
+  const entries: HistoryEntry[] = [];
+  for (const record of out.split(RECORD_SEP)) {
+    const trimmed = record.trim();
+    if (trimmed.length === 0) continue;
+    const [sha, date, ...rest] = trimmed.split(FIELD_SEP);
+    if (!sha || !date) continue;
+    entries.push({
+      sha,
+      date,
+      // `%s` never contains FIELD_SEP, but rejoin defensively so a delimiter
+      // that somehow slipped into a subject doesn't truncate the message.
+      message: redactToken(rest.join(FIELD_SEP)),
+    });
+  }
+  return entries;
+}
+
+/**
+ * Read a single past revision of a note file: `git show <sha>:<path>.md`.
+ * Returns the file content at that commit, or null when the path is unsafe,
+ * the sha/path pair doesn't resolve, or git exits non-zero.
+ *
+ * The sha + path both go into an array-spawn argv (no shell). The sha is
+ * validated to a hex-only shape (git accepts abbreviated shas + symbolic
+ * refs, but for this read surface we only allow `[0-9a-f]` so a caller can't
+ * smuggle a `..`-style ref or option-looking token). The path runs through
+ * the same `noteHistoryPathspec` normalization as the log read.
+ */
+export async function showMirrorRevision(
+  repoDir: string,
+  sha: string,
+  notePath: string,
+): Promise<string | null> {
+  const cleanSha = sha.trim();
+  // Hex-only, bounded. Covers full + abbreviated shas; rejects refs,
+  // ranges, and anything option-looking.
+  if (!/^[0-9a-f]{4,64}$/.test(cleanSha)) return null;
+  const spec = noteHistoryPathspec(notePath);
+  if (spec === null) return null;
+  const proc = Bun.spawn(["git", "show", `${cleanSha}:${spec}`], {
+    cwd: repoDir,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const exitCode = await proc.exited;
+  if (exitCode !== 0) return null;
+  return new TextDecoder().decode(
+    await new Response(proc.stdout).arrayBuffer(),
+  );
+}
+
 /**
  * Singleton lifecycle controller. Holds the active mirror config, the
  * resolved path, hook subscriptions (when sync_mode=events), the

package/src/mirror-routes.ts

@@ -34,7 +34,11 @@ import {
   validateMirrorConfigShape,
   type MirrorConfig,
 } from "./mirror-config.ts";
-import type { MirrorManager } from "./mirror-manager.ts";
+import {
+  readMirrorHistory,
+  showMirrorRevision,
+  type MirrorManager,
+} from "./mirror-manager.ts";
 import { getMirrorManager } from "./mirror-registry.ts";
 import {
   applyToGitRemote,
@@ -296,6 +300,183 @@ export async function handleMirrorPushNow(
   );
 }
 
+/**
+ * `GET /vault/<name>/.parachute/mirror/history` — surface the mirror's git
+ * commit history (vault#300).
+ *
+ * The vault is already git-backed via the mirror (one file per note), so
+ * `git log` IS a tamper-evident, diffable write history. This endpoint
+ * SURFACES it through the admin gate — it's a read-only ops/forensics
+ * surface, not a content read path (hence admin, not read, scoped upstream).
+ *
+ * Query params:
+ *   - `?path=<note.path>` — scope the log to a single note's file
+ *     (`git log --follow -- <path>.md`). An unsafe path (traversal /
+ *     absolute) yields an empty list, never an unscoped log.
+ *   - `?limit=<n>` — cap the number of commits (default
+ *     HISTORY_DEFAULT_LIMIT, clamped to HISTORY_MAX_LIMIT).
+ *
+ * Response: 200 `{ history: [{ sha, date, message }], mirror_path,
+ * path?, limit }`. Degrades gracefully:
+ *   - mirror disabled / no path resolved → 200 with empty history + a
+ *     `note` explaining the mirror isn't initialized (not a 500).
+ *   - git not installed → 503 git_not_installed (consistent with the other
+ *     mirror routes).
+ *   - no commits yet / path with no history → 200 empty history.
+ */
+export async function handleMirrorHistory(
+  req: Request,
+  manager: MirrorManager,
+): Promise<Response> {
+  const url = new URL(req.url);
+  const pathParam = url.searchParams.get("path") ?? undefined;
+  const limitParam = url.searchParams.get("limit");
+  let limit: number | undefined;
+  if (limitParam !== null) {
+    const n = Number(limitParam);
+    if (!Number.isInteger(n) || n <= 0) {
+      return Response.json(
+        {
+          error: "Invalid limit",
+          field: "limit",
+          message: "limit must be a positive integer.",
+        },
+        { status: 400 },
+      );
+    }
+    limit = n;
+  }
+
+  const status = manager.getStatus();
+  // No resolved mirror path means the mirror was never enabled /
+  // bootstrapped for this vault — there's no git repo to read. Return an
+  // empty history with an explanatory note rather than a 500/404; the
+  // caller (SPA / CLI) renders "no history yet, enable backup to start".
+  if (!status.mirror_path) {
+    return Response.json(
+      {
+        history: [],
+        mirror_path: null,
+        ...(pathParam ? { path: pathParam } : {}),
+        note: "Mirror is not initialized for this vault — no git history exists yet. Enable history (backup) to start recording write history.",
+      },
+      { headers: { "Access-Control-Allow-Origin": "*" } },
+    );
+  }
+
+  // Preflight git — the helper degrades a missing repo to [], but a
+  // git-less server should get the friendly, actionable 503 (same shape as
+  // the import / PUT routes) rather than a silently-empty list.
+  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;
+  }
+
+  const history = await readMirrorHistory(status.mirror_path, {
+    notePath: pathParam,
+    limit,
+  });
+  return Response.json(
+    {
+      history,
+      mirror_path: status.mirror_path,
+      ...(pathParam ? { path: pathParam } : {}),
+      ...(limit !== undefined ? { limit } : {}),
+    },
+    { headers: { "Access-Control-Allow-Origin": "*" } },
+  );
+}
+
+/**
+ * `GET /vault/<name>/.parachute/mirror/history/show?sha=<sha>&path=<note.path>`
+ * — read a single note file at a past revision (`git show <sha>:<path>.md`).
+ * The companion to `/history`: history lists the commits, this reads what a
+ * note looked like at one of them. Admin-gated (vault#300).
+ *
+ * Query params (both required):
+ *   - `sha` — a commit sha (hex, validated in `showMirrorRevision`).
+ *   - `path` — the note path (normalized to `<path>.md`).
+ *
+ * Response:
+ *   200 `{ sha, path, content }` — the file content at that revision.
+ *   400 — missing sha/path.
+ *   404 — the sha/path pair doesn't resolve (unknown sha, note didn't
+ *         exist at that commit, or an unsafe path).
+ *   503 — git not installed.
+ */
+export async function handleMirrorHistoryShow(
+  req: Request,
+  manager: MirrorManager,
+): Promise<Response> {
+  const url = new URL(req.url);
+  const sha = url.searchParams.get("sha")?.trim() ?? "";
+  const notePath = url.searchParams.get("path")?.trim() ?? "";
+  if (sha.length === 0 || notePath.length === 0) {
+    return Response.json(
+      {
+        error: "sha and path required",
+        message:
+          "Provide both `sha` (a commit from /history) and `path` (the note path) query params.",
+      },
+      { status: 400 },
+    );
+  }
+
+  const status = manager.getStatus();
+  if (!status.mirror_path) {
+    return Response.json(
+      {
+        error: "Mirror not initialized",
+        message:
+          "No git history exists for this vault yet — enable history (backup) first.",
+      },
+      { status: 404 },
+    );
+  }
+
+  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;
+  }
+
+  const content = await showMirrorRevision(status.mirror_path, sha, notePath);
+  if (content === null) {
+    return Response.json(
+      {
+        error: "Revision not found",
+        message: `No content for ${notePath} at ${sha} — the sha may be unknown, the note may not have existed at that commit, or the path is invalid.`,
+      },
+      { status: 404 },
+    );
+  }
+  return Response.json(
+    { sha, path: notePath, content },
+    { headers: { "Access-Control-Allow-Origin": "*" } },
+  );
+}
+
 /**
  * Convenience for tests + future callers: build the GET response from a
  * known-good config without needing a real MirrorManager.

package/src/routing.test.ts

@@ -2266,6 +2266,79 @@ describe("/vault/<name>/.parachute/mirror/run-now — auth + dispatch", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// /vault/<name>/.parachute/mirror/history — surface the git write history
+// (vault#300). Admin-gated (ops/forensics surface). Tests pin the auth gate
+// matches the sibling mirror routes; helper + handler shape lives in
+// mirror-history.test.ts.
+// ---------------------------------------------------------------------------
+
+describe("/vault/<name>/.parachute/mirror/history — auth + dispatch", () => {
+  test("unauthenticated → 401", async () => {
+    createVault("journal");
+    const p = "/vault/journal/.parachute/mirror/history";
+    const res = await route(new Request(`http://localhost:1940${p}`), p);
+    expect(res.status).toBe(401);
+  });
+
+  test("vault:read token → 403 insufficient_scope (admin required)", async () => {
+    createVault("journal");
+    const fullToken = await mintJwt({ vaultName: "journal", scopes: ["vault:journal:read"] });
+    const p = "/vault/journal/.parachute/mirror/history";
+    const res = await route(
+      new Request(`http://localhost:1940${p}`, {
+        headers: { authorization: `Bearer ${fullToken}` },
+      }),
+      p,
+    );
+    expect(res.status).toBe(403);
+    const body = (await res.json()) as { error_type?: string; required_scope?: string };
+    expect(body.error_type).toBe("insufficient_scope");
+    expect(body.required_scope).toBe("vault:admin");
+  });
+
+  test("admin token reaches the handler (200 when wired, 503 when not)", async () => {
+    createVault("journal");
+    const token = await createAdminToken("journal");
+    const p = "/vault/journal/.parachute/mirror/history";
+    const res = await route(
+      new Request(`http://localhost:1940${p}`, {
+        headers: { authorization: `Bearer ${token}` },
+      }),
+      p,
+    );
+    // Either way the auth gate passed — that's what this routing-level test pins.
+    expect([200, 503]).toContain(res.status);
+  });
+
+  test("/history/show admin gate matches /history", async () => {
+    createVault("journal");
+    const fullToken = await mintJwt({ vaultName: "journal", scopes: ["vault:journal:read"] });
+    const p = "/vault/journal/.parachute/mirror/history/show";
+    const res = await route(
+      new Request(`http://localhost:1940${p}?sha=abc123&path=Notes/a`, {
+        headers: { authorization: `Bearer ${fullToken}` },
+      }),
+      p,
+    );
+    expect(res.status).toBe(403);
+  });
+
+  test("non-GET method → 405 (or 503 when manager not wired)", async () => {
+    createVault("journal");
+    const token = await createAdminToken("journal");
+    const p = "/vault/journal/.parachute/mirror/history";
+    const res = await route(
+      new Request(`http://localhost:1940${p}`, {
+        method: "POST",
+        headers: { authorization: `Bearer ${token}` },
+      }),
+      p,
+    );
+    expect([405, 503]).toContain(res.status);
+  });
+});
+
 // ---------------------------------------------------------------------------
 // /vault/<name>/.parachute/usage — per-vault data-footprint endpoint.
 //

package/src/routing.ts

@@ -94,6 +94,8 @@ import {
   handleAuthGithubSelectRepo,
   handleAuthPat,
   handleMirrorGet,
+  handleMirrorHistory,
+  handleMirrorHistoryShow,
   handleMirrorImport,
   handleMirrorPushNow,
   handleMirrorPut,
@@ -671,6 +673,50 @@ export async function route(
     return Response.json({ error: "Method not allowed" }, { status: 405 });
   }
 
+  // /.parachute/mirror/history — surface the mirror's git commit history
+  // (vault#300). The vault is already git-backed (one file per note), so
+  // `git log` IS a tamper-evident write history; this read path exposes it.
+  // Admin-gated (it's an ops/forensics surface, not a content read) — same
+  // gate + manager check as the sibling mirror routes. GET-only.
+  //   /history       — full mirror history (?path=<note> scopes to one note,
+  //                    ?limit=<n> caps the count)
+  //   /history/show  — `git show <sha>:<path>.md` to read a past revision
+  if (
+    subpath === "/.parachute/mirror/history" ||
+    subpath === "/.parachute/mirror/history/show"
+  ) {
+    if (!hasScopeForVault(auth.scopes, vaultName, "admin")) {
+      return Response.json(
+        {
+          error: "Forbidden",
+          error_type: "insufficient_scope",
+          message: `This endpoint requires the '${SCOPE_ADMIN}' scope (or '${SCOPE_ADMIN.replace("vault:", `vault:${vaultName}:`)}').`,
+          required_scope: SCOPE_ADMIN,
+          granted_scopes: auth.scopes,
+        },
+        { status: 403 },
+      );
+    }
+    const manager = getMirrorManager(vaultName);
+    if (!manager) {
+      return Response.json(
+        {
+          error: "Mirror manager not initialized",
+          message:
+            "The vault server hasn't wired the mirror manager registry yet (boot hasn't finished, or it failed). Check logs for [mirror] entries.",
+        },
+        { status: 503 },
+      );
+    }
+    if (req.method !== "GET") {
+      return Response.json({ error: "Method not allowed" }, { status: 405 });
+    }
+    if (subpath === "/.parachute/mirror/history/show") {
+      return handleMirrorHistoryShow(req, manager);
+    }
+    return handleMirrorHistory(req, manager);
+  }
+
   // /.parachute/mirror/import — clone a vault export from git + import.
   // Admin-gated. POST-only. Synchronous (imports finish in <30s for
   // typical vaults). See mirror-routes.ts:handleMirrorImport for the