@openparachute/vault 0.4.6 → 0.4.7-rc.2

package/core/src/portable-md.test.ts

@@ -25,6 +25,7 @@ import { tmpdir } from "os";
 
 import { SqliteStore } from "./store.js";
 import {
+  CaseCollisionError,
   emitYamlDoc,
   exportVaultToDir,
   importPortableVault,
@@ -1551,4 +1552,250 @@ describe("case-collision detection (vault#327)", async () => {
     expect(lower!.path).toBe("Tabular/budget-2026");
     expect(lower!.content).toBe("month,total\n2026-01,1");
   });
+
+  // ---------------------------------------------------------------------------
+  // failOnCaseCollision — strict mode (vault#327 Phase 2)
+  // ---------------------------------------------------------------------------
+  //
+  // The default behavior (auto-disambiguate) is lossless but silent on the
+  // wire — the CLI didn't surface it before #vault-rc.2. Strict mode is the
+  // opt-in fail-fast path: throws `CaseCollisionError` with every colliding
+  // path enumerated, so the operator can rename one of each pair in the
+  // vault before re-exporting.
+
+  it("failOnCaseCollision throws CaseCollisionError on case-insensitive FS", async () => {
+    await store.createNote("# in Balance", {
+      id: "2025-05-26-09-15-42-aaaaaa",
+      path: "Journal/2025-05-26 Technology in Balance",
+    });
+    await store.createNote("# in balance", {
+      id: "2025-05-26-09-15-42-bbbbbb",
+      path: "Journal/2025-05-26 Technology in balance",
+    });
+
+    const outDir = join(tmpBase, "strict-throw");
+    let thrown: unknown;
+    try {
+      await exportVaultToDir(store, {
+        outDir,
+        vaultName: "test",
+        exportedAt: "2026-05-15T00:00:00.000Z",
+        caseSensitiveOverride: false,
+        failOnCaseCollision: true,
+      });
+    } catch (err) {
+      thrown = err;
+    }
+    expect(thrown).toBeInstanceOf(CaseCollisionError);
+    const err = thrown as CaseCollisionError;
+    expect(err.collisions).toHaveLength(1);
+    expect(err.collisions[0]).toHaveLength(2);
+    const ids = err.collisions[0]!.map((c) => c.note_id).sort();
+    expect(ids).toEqual(["2025-05-26-09-15-42-aaaaaa", "2025-05-26-09-15-42-bbbbbb"]);
+    // Error message names BOTH paths + the actionable instruction.
+    expect(err.message).toContain("Journal/2025-05-26 Technology in Balance");
+    expect(err.message).toContain("Journal/2025-05-26 Technology in balance");
+    expect(err.message).toContain("Rename one of them");
+    // Pre-scan throws BEFORE any per-note file write. The .parachute/
+    // sidecar dir is still created (cheap, idempotent), but no per-note
+    // .md file landed.
+    expect(existsSync(join(outDir, "Journal/2025-05-26 Technology in Balance.md"))).toBe(false);
+  });
+
+  it("failOnCaseCollision is a no-op when FS is case-sensitive", async () => {
+    // Same fixture as above, but force the case-sensitive code path. The
+    // strict flag becomes a no-op — both files land at their canonical
+    // paths, no error.
+    await store.createNote("# in Balance", {
+      id: "2025-05-26-09-15-42-aaaaaa",
+      path: "Journal/2025-05-26 Technology in Balance",
+    });
+    await store.createNote("# in balance", {
+      id: "2025-05-26-09-15-42-bbbbbb",
+      path: "Journal/2025-05-26 Technology in balance",
+    });
+
+    const outDir = join(tmpBase, "strict-cs");
+    const stats = await exportVaultToDir(store, {
+      outDir,
+      vaultName: "test",
+      exportedAt: "2026-05-15T00:00:00.000Z",
+      caseSensitiveOverride: true,
+      failOnCaseCollision: true,
+    });
+    expect(stats.notes).toBe(2);
+    expect(stats.disambiguated_paths).toHaveLength(0);
+  });
+
+  it("failOnCaseCollision is a no-op on case-insensitive FS when nothing collides", async () => {
+    // One note. Strict mode + case-insensitive FS — should not throw,
+    // should ship clean. Pre-scan walks the (single-note) list and
+    // finds no collision groups.
+    await store.createNote("# solo", {
+      id: "2025-05-26-09-15-42-aaaaaa",
+      path: "Journal/Solo Note",
+    });
+
+    const outDir = join(tmpBase, "strict-solo");
+    const stats = await exportVaultToDir(store, {
+      outDir,
+      vaultName: "test",
+      exportedAt: "2026-05-15T00:00:00.000Z",
+      caseSensitiveOverride: false,
+      failOnCaseCollision: true,
+    });
+    expect(stats.notes).toBe(1);
+    expect(stats.disambiguated_paths).toHaveLength(0);
+    expect(existsSync(join(outDir, "Journal/Solo Note.md"))).toBe(true);
+  });
+
+  it("three-way collision lists all three paths in the error", async () => {
+    // Foo.md + foo.md + FOO.md — all share the same lowercased
+    // `(path, ext)` slot. CaseCollisionError.collisions[0] should
+    // include every one of them so the operator sees the full set in
+    // a single error report, not a paint-by-numbers re-export cycle.
+    await store.createNote("# upper-camel", {
+      id: "2025-05-26-09-15-42-aaaaaa",
+      path: "Journal/Foo",
+    });
+    await store.createNote("# lower", {
+      id: "2025-05-26-09-15-42-bbbbbb",
+      path: "Journal/foo",
+    });
+    await store.createNote("# all-caps", {
+      id: "2025-05-26-09-15-42-cccccc",
+      path: "Journal/FOO",
+    });
+
+    const outDir = join(tmpBase, "strict-3way");
+    let thrown: unknown;
+    try {
+      await exportVaultToDir(store, {
+        outDir,
+        vaultName: "test",
+        exportedAt: "2026-05-15T00:00:00.000Z",
+        caseSensitiveOverride: false,
+        failOnCaseCollision: true,
+      });
+    } catch (err) {
+      thrown = err;
+    }
+    expect(thrown).toBeInstanceOf(CaseCollisionError);
+    const err = thrown as CaseCollisionError;
+    expect(err.collisions).toHaveLength(1);
+    expect(err.collisions[0]).toHaveLength(3);
+    const paths = err.collisions[0]!.map((c) => c.path).sort();
+    expect(paths).toEqual(["Journal/FOO", "Journal/Foo", "Journal/foo"]);
+    expect(err.message).toContain("Journal/FOO");
+    expect(err.message).toContain("Journal/Foo");
+    expect(err.message).toContain("Journal/foo");
+  });
+
+  it("multiple independent collision groups all surface", async () => {
+    // Two distinct collision groups: (Bar.md, bar.md) and (Baz.md,
+    // baz.md). Both groups should appear in the error so the operator
+    // doesn't have to fix-rebuild-fix in a loop. Pairs are independent —
+    // resolving one doesn't reveal the other.
+    await store.createNote("# bar-upper", {
+      id: "2025-05-26-09-15-42-aaaaaa",
+      path: "Bar",
+    });
+    await store.createNote("# bar-lower", {
+      id: "2025-05-26-09-15-42-bbbbbb",
+      path: "bar",
+    });
+    await store.createNote("# baz-upper", {
+      id: "2025-05-26-09-15-42-cccccc",
+      path: "Baz",
+    });
+    await store.createNote("# baz-lower", {
+      id: "2025-05-26-09-15-42-dddddd",
+      path: "baz",
+    });
+
+    const outDir = join(tmpBase, "strict-multi-group");
+    let thrown: unknown;
+    try {
+      await exportVaultToDir(store, {
+        outDir,
+        vaultName: "test",
+        exportedAt: "2026-05-15T00:00:00.000Z",
+        caseSensitiveOverride: false,
+        failOnCaseCollision: true,
+      });
+    } catch (err) {
+      thrown = err;
+    }
+    expect(thrown).toBeInstanceOf(CaseCollisionError);
+    const err = thrown as CaseCollisionError;
+    expect(err.collisions).toHaveLength(2);
+    const allIds = err.collisions.flat().map((c) => c.note_id).sort();
+    expect(allIds).toEqual([
+      "2025-05-26-09-15-42-aaaaaa",
+      "2025-05-26-09-15-42-bbbbbb",
+      "2025-05-26-09-15-42-cccccc",
+      "2025-05-26-09-15-42-dddddd",
+    ]);
+  });
+
+  it("directory-level case difference triggers collision detection", async () => {
+    // Two notes at `Notes/foo` and `notes/foo` — the basename matches
+    // but the parent dir differs only by case. On a case-insensitive
+    // FS, both files would land in the same directory because
+    // `Notes/` and `notes/` resolve to the same inode. Verify the
+    // lowercased-path key catches this: `notes/foo.md`.
+    await store.createNote("# notes-upper", {
+      id: "2025-05-26-09-15-42-aaaaaa",
+      path: "Notes/foo",
+    });
+    await store.createNote("# notes-lower", {
+      id: "2025-05-26-09-15-42-bbbbbb",
+      path: "notes/foo",
+    });
+
+    const outDir = join(tmpBase, "strict-dir-case");
+    let thrown: unknown;
+    try {
+      await exportVaultToDir(store, {
+        outDir,
+        vaultName: "test",
+        exportedAt: "2026-05-15T00:00:00.000Z",
+        caseSensitiveOverride: false,
+        failOnCaseCollision: true,
+      });
+    } catch (err) {
+      thrown = err;
+    }
+    expect(thrown).toBeInstanceOf(CaseCollisionError);
+    const err = thrown as CaseCollisionError;
+    expect(err.collisions).toHaveLength(1);
+    expect(err.collisions[0]).toHaveLength(2);
+  });
+
+  it("default (no failOnCaseCollision) still auto-disambiguates — back-compat", async () => {
+    // The new strict mode is opt-in. Leaving failOnCaseCollision unset
+    // (or false) keeps the existing lossless auto-disambiguation path
+    // unchanged. This pins the back-compat contract — watch/mirror
+    // loops that don't opt in to strict mode never see a thrown
+    // CaseCollisionError on a colliding vault.
+    await store.createNote("# upper", {
+      id: "2025-05-26-09-15-42-aaaaaa",
+      path: "Journal/Note",
+    });
+    await store.createNote("# lower", {
+      id: "2025-05-26-09-15-42-bbbbbb",
+      path: "Journal/note",
+    });
+
+    const outDir = join(tmpBase, "default-disambig");
+    const stats = await exportVaultToDir(store, {
+      outDir,
+      vaultName: "test",
+      exportedAt: "2026-05-15T00:00:00.000Z",
+      caseSensitiveOverride: false,
+      // failOnCaseCollision deliberately omitted — default behavior.
+    });
+    expect(stats.notes).toBe(2);
+    expect(stats.disambiguated_paths).toHaveLength(1);
+  });
 });

package/core/src/portable-md.ts

@@ -631,6 +631,78 @@ export interface ExportOptions {
    * run on. When unset (the production default), the probe runs.
    */
   caseSensitiveOverride?: boolean;
+  /**
+   * Strict mode for case-collision handling on case-insensitive
+   * filesystems (vault#327 Phase 2). When `true`, the first detected
+   * collision aborts the export by throwing a `CaseCollisionError`
+   * naming every colliding path. When `false` (the default), the
+   * existing lossless behavior is preserved — the colliding note is
+   * written to a disambiguated filename (`<base>__<id-short>.<ext>`)
+   * and recorded in `ExportStats.disambiguated_paths`.
+   *
+   * Use `true` for one-shot CLI flows where the operator wants to be
+   * forced to fix the source-of-truth (rename one of the colliding
+   * notes in the vault before re-exporting). Leave `false` for
+   * long-running watch / mirror loops where a hard failure mid-loop
+   * would block the operator's actual work.
+   */
+  failOnCaseCollision?: boolean;
+}
+
+/**
+ * Thrown by `exportVaultToDir` when `failOnCaseCollision: true` is set
+ * and the export detects two-or-more notes whose paths differ only by
+ * case on a case-insensitive filesystem (vault#327).
+ *
+ * The error names every colliding path (full N-way group, not just
+ * the first pair) so the operator can audit the whole set in one
+ * pass. Caller catches by type and surfaces `.collisions` for a
+ * clean error report:
+ *
+ * ```ts
+ * try {
+ *   await exportVaultToDir(store, { ..., failOnCaseCollision: true });
+ * } catch (err) {
+ *   if (err instanceof CaseCollisionError) {
+ *     for (const group of err.collisions) {
+ *       console.error(`collision: ${group.map((g) => g.path).join(", ")}`);
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export class CaseCollisionError extends Error {
+  /**
+   * Each entry is one collision group — every note that shares the same
+   * lowercased `(path, extension)` slot. Two notes per group is the
+   * common case; three-or-more (`Foo.md` + `foo.md` + `FOO.md`) is rare
+   * but supported. Notes are listed in the order they were encountered
+   * during the export walk (deterministic — `queryNotes` sorts ASC).
+   */
+  readonly collisions: Array<Array<{ note_id: string; path: string; extension: string }>>;
+  constructor(collisions: CaseCollisionError["collisions"]) {
+    const lines: string[] = [
+      "Export failed: case-collision detected on case-insensitive filesystem.",
+      "The following notes have paths that differ only by case:",
+    ];
+    // Separate distinct collision groups with `  ---` so operators
+    // reading the error in a terminal can tell where one (Foo.md /
+    // foo.md) pair ends and the next (Bar.md / bar.md) begins. Without
+    // a separator, multi-group output runs together as an unbroken
+    // bullet list. vault#350.
+    collisions.forEach((group, idx) => {
+      if (idx > 0) lines.push("  ---");
+      for (const entry of group) {
+        lines.push(`  - ${entry.path}.${entry.extension} (note id: ${entry.note_id})`);
+      }
+    });
+    lines.push(
+      "Rename one of them in the vault before re-exporting, or run from a case-sensitive filesystem.",
+    );
+    super(lines.join("\n"));
+    this.name = "CaseCollisionError";
+    this.collisions = collisions;
+  }
 }
 
 /**
@@ -733,9 +805,54 @@ export async function exportVaultToDir(
   // case-insensitive filesystems.
   const seenLowerKeys = new Map<string, string>();
 
+  // Strict-mode pre-scan (vault#327 Phase 2). When the caller passes
+  // `failOnCaseCollision: true`, surface every collision group in one
+  // typed error BEFORE any write lands on disk — partial-export-then-
+  // throw would leave the operator with a half-mirrored output dir to
+  // clean up. The pre-scan walks every note in the vault (NOT
+  // since-filtered: a since-filter belongs in the write loop —
+  // collisions can involve one old + one new path, and a since-only
+  // pre-scan would miss those entirely, silently degrading the strict
+  // guarantee on every poll cycle after the initial export). When no
+  // collisions exist on a case-insensitive FS, the pre-scan is a
+  // no-op (cheap); on a case-sensitive FS it's skipped entirely.
+  //
+  // Perf: the pre-scan calls `noteToPortable` (3 DB queries per note:
+  // links, attachments, content). The main loop below also calls
+  // `noteToPortable` — without caching, every note that ALSO passes
+  // the since-filter would be serialized twice (~2x the DB round-
+  // trips on a large strict-mode export). Stash every pre-scan result
+  // in `prescanPortables` and reuse it below; cache-miss falls back
+  // to a fresh `noteToPortable` for safety. vault#350.
+  const prescanPortables = new Map<string, PortableNote>();
+  if (opts.failOnCaseCollision && !caseSensitive) {
+    const groups = new Map<string, Array<{ note_id: string; path: string; extension: string }>>();
+    for (const note of allNotes) {
+      const portable = await noteToPortable(note, store);
+      prescanPortables.set(portable.id, portable);
+      if (!portable.path) continue; // _unpathed/<id>.<ext> is case-stable
+      const ext = portable.extension ?? "md";
+      const key = `${portable.path.toLowerCase()}|${ext.toLowerCase()}`;
+      const entry = { note_id: portable.id, path: portable.path, extension: ext };
+      const existing = groups.get(key);
+      if (existing) {
+        existing.push(entry);
+      } else {
+        groups.set(key, [entry]);
+      }
+    }
+    const collisions = Array.from(groups.values()).filter((g) => g.length > 1);
+    if (collisions.length > 0) {
+      throw new CaseCollisionError(collisions);
+    }
+  }
+
   for (const note of allNotes) {
     if (since && !shouldIncludeForSince(note, since)) continue;
-    const portable = await noteToPortable(note, store);
+    // Reuse a pre-scan result when strict-mode populated the cache;
+    // otherwise serialize fresh. Same PortableNote shape either way,
+    // so the rest of the loop is untouched. vault#350.
+    const portable = prescanPortables.get(note.id) ?? (await noteToPortable(note, store));
     let relPath = portableExportFilePath(portable);
 
     // Decide whether this note's filename needs disambiguation

package/package.json

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

package/src/cli.ts

@@ -2872,6 +2872,7 @@ async function cmdExport(args: string[]) {
   const { DEFAULT_COMMIT_TEMPLATE } = await import("./export-watch.ts");
   let gitMessageTemplate = DEFAULT_COMMIT_TEMPLATE;
   let gitPush = false;
+  let strictCaseCollision = false;
 
   const positional: string[] = [];
   for (let i = 0; i < args.length; i++) {
@@ -2923,6 +2924,8 @@ async function cmdExport(args: string[]) {
       gitMessageTemplate = v;
     } else if (arg === "--git-push") {
       gitPush = true;
+    } else if (arg === "--strict-case-collision") {
+      strictCaseCollision = true;
     } else {
       positional.push(arg);
     }
@@ -2952,6 +2955,12 @@ async function cmdExport(args: string[]) {
     console.error("                                {{first_note_title}}, {{vault_name}}");
     console.error("                              (default: \"export: {{date}} ({{notes_changed}} note{{plural}})\")");
     console.error("  --git-push                  After commit, run `git push` (non-fatal on failure).");
+    console.error("  --strict-case-collision     On case-insensitive filesystems (macOS APFS-default,");
+    console.error("                              Windows NTFS, FAT/exFAT), abort the export if two notes");
+    console.error("                              have paths differing only by case (vault#327).");
+    console.error("                              Without this flag, colliding notes are auto-disambiguated");
+    console.error("                              with an `__<id-short>` filename suffix (lossless; both");
+    console.error("                              files land, canonical path preserved in frontmatter).");
     process.exit(1);
   }
 
@@ -3010,6 +3019,7 @@ async function cmdExport(args: string[]) {
       assetsDir: assetsDirPath,
       ...(vaultDescription ? { vaultDescription } : {}),
       ...(opts.sinceCursor ? { since: opts.sinceCursor } : {}),
+      ...(strictCaseCollision ? { failOnCaseCollision: true } : {}),
     });
 
     if (opts.isInitial) {
@@ -3030,6 +3040,28 @@ async function cmdExport(args: string[]) {
           `Note: ${stats.skipped_attachments.length} attachment(s) skipped. See [export] warnings above.`,
         );
       }
+      // vault#327 Phase 2 — surface case-collision auto-disambiguation
+      // explicitly. The previous fix landed the logic silently; the
+      // operator had no signal that filenames had been munged. Now we
+      // print the count + every disambiguated path so the operator can
+      // (a) audit, (b) decide whether to rename a colliding note in
+      // the vault and re-export, or (c) re-run with
+      // --strict-case-collision to refuse the disambiguation entirely.
+      if (stats.disambiguated_paths.length > 0) {
+        const n = stats.disambiguated_paths.length;
+        console.warn(
+          `Warning: ${n} note${n === 1 ? "" : "s"} had path${n === 1 ? "" : "s"} that ` +
+          `differ only by case on this case-insensitive filesystem. ` +
+          `Auto-disambiguated on disk (canonical paths preserved in frontmatter):`,
+        );
+        for (const d of stats.disambiguated_paths) {
+          console.warn(`  - ${d.original_path} → ${d.disambiguated_filename} (id: ${d.note_id})`);
+        }
+        console.warn(
+          `Re-run with --strict-case-collision to abort instead, or rename one of each ` +
+          `colliding pair in the vault before re-exporting. See vault#327.`,
+        );
+      }
     } else {
       // Watch-mode status line: keep tight; the loop logs every interval.
       if (stats.notes > 0) {
@@ -3039,6 +3071,17 @@ async function cmdExport(args: string[]) {
       } else {
         console.log(`[watch] no changes`);
       }
+      // Watch-mode: log new disambiguations per cycle. Operators running
+      // a long-lived watch loop want to be notified the moment a
+      // collision shows up — they can fix it at the source without
+      // waiting for the next manual full export.
+      if (stats.disambiguated_paths.length > 0) {
+        const n = stats.disambiguated_paths.length;
+        console.warn(
+          `[watch] case-collision: ${n} disambiguated path${n === 1 ? "" : "s"} this cycle ` +
+          `(see vault#327; --strict-case-collision to abort instead).`,
+        );
+      }
     }
 
     let committed = false;
@@ -3058,15 +3101,44 @@ async function cmdExport(args: string[]) {
     return { stats, nextCursor, committed };
   }
 
+  // Import the typed CaseCollisionError once so both the single-shot and
+  // watch-initial paths can render it the same way. vault#327 Phase 2.
+  const { CaseCollisionError } = await import("../core/src/portable-md.ts");
+
   // ---- Single-shot mode ----
   if (!watch) {
-    await runCycle({ sinceCursor: since, isInitial: true });
+    try {
+      await runCycle({ sinceCursor: since, isInitial: true });
+    } catch (err) {
+      if (err instanceof CaseCollisionError) {
+        // The error's own message already includes the actionable
+        // instruction ("Rename one of them..."). Print verbatim + exit
+        // non-zero so scripts catch the failure deterministically.
+        console.error(err.message);
+        process.exit(1);
+      }
+      throw err;
+    }
     return;
   }
 
   // ---- Watch mode ----
   // Initial full (or since-filtered) export, then poll every interval.
-  const initial = await runCycle({ sinceCursor: since, isInitial: true });
+  let initial: Awaited<ReturnType<typeof runCycle>>;
+  try {
+    initial = await runCycle({ sinceCursor: since, isInitial: true });
+  } catch (err) {
+    if (err instanceof CaseCollisionError) {
+      console.error(err.message);
+      console.error(
+        "\n--strict-case-collision is enabled; refusing to start the watch loop until the " +
+        "collision is resolved in the vault. Re-export without --strict-case-collision to " +
+        "auto-disambiguate instead.",
+      );
+      process.exit(1);
+    }
+    throw err;
+  }
   let cursor = initial.nextCursor;
   console.log(`[watch] polling every ${intervalSeconds}s; press Ctrl-C to stop.`);
 
@@ -3095,6 +3167,26 @@ async function cmdExport(args: string[]) {
       const cycle = await runCycle({ sinceCursor: cursor, isInitial: false });
       cursor = cycle.nextCursor;
     } catch (err) {
+      // CaseCollisionError under --strict-case-collision means the
+      // operator opted into "abort on any collision". A new collision
+      // that appears mid-watch (e.g. an LLM client just wrote
+      // `Inbox/Foo` to a vault that already had `Inbox/foo`) must NOT
+      // be swallowed into the generic [watch] export-error log — the
+      // strict-mode guarantee would silently degrade after the initial
+      // export. Print the full collision message + actionable hint and
+      // stop the loop via the same SIGINT-style pathway used by Ctrl-C
+      // (clears timer, gives in-flight work a 250ms settle window).
+      // Exits non-zero so supervisors / git-watch sidecars catch it.
+      if (err instanceof CaseCollisionError) {
+        console.error(err.message);
+        console.error(
+          "Resolve the collision in the vault or re-run without --strict-case-collision to fall back to auto-disambiguate mode.",
+        );
+        stopping = true;
+        if (timer) clearInterval(timer);
+        setTimeout(() => process.exit(1), 0);
+        return;
+      }
       // Don't kill the loop on a transient export error — log and keep
       // polling. Operator can Ctrl-C if they want to bail.
       console.error(`[watch] export error: ${(err as Error).message ?? err}`);

package/src/config.ts

@@ -33,6 +33,12 @@ import { join } from "path";
 import { existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync, renameSync } from "fs";
 import crypto from "node:crypto";
 
+import {
+  parseMirrorConfig as parseMirrorSectionFromYaml,
+  serializeMirrorConfig as serializeMirrorSection,
+  type MirrorConfig as MirrorConfigType,
+} from "./mirror-config.ts";
+
 // ---------------------------------------------------------------------------
 // Paths
 //
@@ -263,6 +269,14 @@ export interface GlobalConfig {
   autostart?: boolean;
   /** Backup configuration: schedule, retention, destinations. */
   backup?: BackupConfig;
+  /**
+   * Persistent vault-managed mirror configuration (vault-sync Phase A1).
+   * Unset when the operator has never touched the mirror block; defaults to
+   * `enabled: false` semantics in that case. When `enabled: true`, the
+   * vault server bootstraps and optionally watches a git mirror at the
+   * resolved path. See `./mirror-config.ts`.
+   */
+  mirror?: MirrorConfigType;
 }
 
 // ---------------------------------------------------------------------------
@@ -1187,6 +1201,12 @@ export function readGlobalConfig(): GlobalConfig {
       // Parse backup section
       config.backup = parseBackup(yaml);
 
+      // Parse mirror section (vault-sync Phase A1). Imported lazily via a
+      // narrow helper to keep config.ts free of a top-level cycle into the
+      // mirror module — `mirror-config.ts` imports `vaultDir` from here.
+      const mirror = parseMirrorSectionFromYaml(yaml);
+      if (mirror) config.mirror = mirror;
+
       return config;
     }
   } catch {}
@@ -1273,6 +1293,10 @@ export function writeGlobalConfig(config: GlobalConfig): void {
     lines.push(...serializeBackup(config.backup));
   }
 
+  if (config.mirror) {
+    lines.push(...serializeMirrorSection(config.mirror));
+  }
+
   // 0600 — owner read/write only. This file may contain the bcrypt password
   // hash and plaintext TOTP secret; it must not be world- or group-readable.
   writeFileSync(globalConfigPath(), lines.join("\n") + "\n", { mode: 0o600 });