@openparachute/vault 0.4.8 → 0.4.9-rc.11

package/src/mirror-config.ts

@@ -4,12 +4,25 @@
  * Builds on the manual export primitives from vault#346 (`parachute-vault
  * export --watch --git-commit`). This module owns the *persistent* form:
  *
- *   - Schema for the `mirror:` block in `~/.parachute/vault/config.yaml`.
- *   - Parse + serialize that block alongside the existing global config.
+ *   - Schema for the per-vault mirror config block.
+ *   - Parse + serialize that block.
+ *   - Per-vault read/write of the config to `data/<vault>/mirror-config.yaml`
+ *     (vault#400 — see below).
  *   - Resolve the on-disk mirror path (internal vs external).
  *   - Validate the operator-supplied shape (location enum, external_path
  *     existence + git-repo-ness).
  *
+ * **Per-vault config (vault#400).** Before vault#400, mirror config lived in a
+ * SINGLE server-wide `mirror:` block in `~/.parachute/vault/config.yaml`.
+ * That made every vault's mirror page show the same config + the same git
+ * remote, and configuring vault B clobbered vault A. vault#399 had already
+ * moved credential STORAGE per-vault; vault#400 completes the job by moving
+ * the CONFIG block to `data/<vault>/mirror-config.yaml` — alongside the
+ * per-vault credentials file + the SQLite DB. The legacy server-wide
+ * `mirror:` block is migrated to its owning vault on boot (default/first
+ * vault, matching how the single server-wide mirror was bound); other
+ * vaults start with no mirror config. See `migrateLegacyServerWideConfig`.
+ *
  * The lifecycle wiring (boot-time bootstrap, watch loop start/stop/reload)
  * lives in `./mirror-manager.ts`; the HTTP surface lives in
  * `./mirror-routes.ts`. This file is intentionally I/O-light: pure parsing,
@@ -19,10 +32,19 @@
  * `parachute.computer/design/2026-05-20-vault-as-git-projection.md`.
  */
 
-import { existsSync, statSync } from "fs";
-import { join } from "path";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  statSync,
+  writeFileSync,
+} from "fs";
+import { dirname, join } from "path";
+import { homedir } from "os";
 
 import { DEFAULT_COMMIT_TEMPLATE, isGitRepo } from "./export-watch.ts";
+import { readCredentials, type MirrorCredentials } from "./mirror-credentials.ts";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -38,40 +60,78 @@ import { DEFAULT_COMMIT_TEMPLATE, isGitRepo } from "./export-watch.ts";
 export type MirrorLocation = "internal" | "external";
 
 /**
- * The persistent mirror configuration block. Lives under the `mirror:` key
- * in the global config.yaml (one mirror per vault server today — multi-vault
- * mirroring is a future ripple, see open question 2 in the design doc).
+ * How the mirror stays current with vault state.
+ *
+ *   - `events` → in-process hooks fire on every note/tag/attachment
+ *     mutation; the manager debounces them (~500ms) into a single export
+ *     pass. A background safety-net poll (default 1h) catches anything
+ *     missed (direct SQL writes, dropped hook dispatches, restart gaps).
+ *     This is the default for new configs and the post-vault#382 shape.
+ *   - `manual` → no event subscriptions, no polling. The operator runs
+ *     "Run export now" (admin SPA button or POST `/.parachute/mirror/run-now`)
+ *     or `parachute-vault export` from the CLI on their own cadence.
+ *
+ * The pre-vault#382 `interval_seconds`-driven watch loop has retired —
+ * existing configs migrate to `events` (when `watch: true`) or `manual`
+ * (when `watch: false`). The legacy field still parses, repurposed as
+ * `safety_net_seconds` when explicit.
+ */
+export type MirrorSyncMode = "events" | "manual";
+
+/** Default safety-net poll interval in seconds (1 hour). */
+export const DEFAULT_SAFETY_NET_SECONDS = 3600;
+/** Minimum safety-net poll interval. Anything tighter would defeat the point of "safety net" — that's what the event path is for. */
+export const MIN_SAFETY_NET_SECONDS = 60;
+/** Maximum safety-net poll interval (24 hours). */
+export const MAX_SAFETY_NET_SECONDS = 86400;
+
+/**
+ * The persistent mirror configuration block. Per-vault since vault#400: each
+ * vault stores its own block in `data/<vault>/mirror-config.yaml` (real
+ * multi-vault mirroring — every vault can mirror to its own git remote).
  *
  * Field semantics:
  *   - `enabled` — master switch. When false (the default for upgrading
  *     vaults), no mirror behavior runs at all. The other fields are
  *     preserved so the operator can flip enabled back on without losing
- *     their location/path/watch settings.
+ *     their location/path/sync_mode settings.
  *   - `location` — "internal" or "external". Drives `resolveMirrorPath`.
  *   - `external_path` — required when location=external. Operator-picked
  *     absolute path. Must exist + be a git repo when first validated.
- *   - `watch` — when true, the manager runs the export-watch loop in the
- *     vault server process. When false, the mirror gets a one-shot export
- *     on boot/config-change only; subsequent updates need an explicit
- *     manual export.
+ *   - `sync_mode` — "events" (subscribe to in-process hooks; debounce ~500ms;
+ *     safety-net poll on top) or "manual" (no auto-fire; operator triggers
+ *     manually). Default "events".
  *   - `auto_commit` — after each export pass, `git add -A && git commit`.
  *     Reuses the existing `runGitCommitCycle` from vault#346.
  *   - `auto_push` — after commit, `git push`. Failures non-fatal.
  *   - `commit_template` — passed verbatim to `renderCommitMessage`. Same
  *     variable set as the CLI: `{{date}}`, `{{notes_changed}}`,
  *     `{{plural}}`, `{{first_note_title}}`, `{{vault_name}}`.
- *   - `interval_seconds` — watch-loop poll interval. Default 5, matching
- *     the CLI flag's default.
+ *   - `safety_net_seconds` — `sync_mode: events` runs an hourly background
+ *     sweep on top of the event-driven path. This field controls the
+ *     interval (default 3600). Clamped to `[MIN_SAFETY_NET_SECONDS,
+ *     MAX_SAFETY_NET_SECONDS]` at validation time.
+ *
+ * Legacy / migration:
+ *   - `watch` (boolean) — pre-vault#382 field. `true` → `sync_mode: events`,
+ *     `false` → `sync_mode: manual`. Parsed for back-compat; the canonical
+ *     form on the wire is `sync_mode`.
+ *   - `interval_seconds` (positive integer) — pre-vault#382 watch-loop
+ *     poll interval. Reinterpreted as `safety_net_seconds` when no
+ *     explicit `safety_net_seconds` is present AND the value lies in the
+ *     valid range. Out-of-range / missing → default 3600. The field is
+ *     no longer surfaced in the UI; the SPA stops emitting it but the
+ *     parser keeps accepting it for hand-edited configs.
  */
 export interface MirrorConfig {
   enabled: boolean;
   location: MirrorLocation;
   external_path: string | null;
-  watch: boolean;
+  sync_mode: MirrorSyncMode;
   auto_commit: boolean;
   auto_push: boolean;
   commit_template: string;
-  interval_seconds: number;
+  safety_net_seconds: number;
 }
 
 /**
@@ -85,11 +145,11 @@ export function defaultMirrorConfig(): MirrorConfig {
     enabled: false,
     location: "internal",
     external_path: null,
-    watch: false,
+    sync_mode: "events",
     auto_commit: true,
     auto_push: false,
     commit_template: DEFAULT_COMMIT_TEMPLATE,
-    interval_seconds: 5,
+    safety_net_seconds: DEFAULT_SAFETY_NET_SECONDS,
   };
 }
 
@@ -129,6 +189,13 @@ export function parseMirrorConfig(yaml: string): MirrorConfig | undefined {
   const lines = yaml.slice(startIdx).split("\n");
 
   const config = defaultMirrorConfig();
+  // Track legacy field state for migration: if `sync_mode` is absent and
+  // `watch` is set, derive sync_mode from watch. If `safety_net_seconds`
+  // is absent and `interval_seconds` is set (legacy field), repurpose it.
+  let sawSyncMode = false;
+  let sawSafetyNet = false;
+  let legacyWatch: boolean | null = null;
+  let legacyInterval: number | null = null;
 
   for (const line of lines) {
     // Stop at the next top-level key.
@@ -140,7 +207,7 @@ export function parseMirrorConfig(yaml: string): MirrorConfig | undefined {
     const boolField = (
       name: keyof Pick<
         MirrorConfig,
-        "enabled" | "watch" | "auto_commit" | "auto_push"
+        "enabled" | "auto_commit" | "auto_push"
       >,
     ): boolean => {
       const m = trimmed.match(new RegExp(`^${name}:\\s*(true|false)\\s*$`));
@@ -151,10 +218,22 @@ export function parseMirrorConfig(yaml: string): MirrorConfig | undefined {
       return false;
     };
     if (boolField("enabled")) continue;
-    if (boolField("watch")) continue;
     if (boolField("auto_commit")) continue;
     if (boolField("auto_push")) continue;
 
+    const watchMatch = trimmed.match(/^watch:\s*(true|false)\s*$/);
+    if (watchMatch) {
+      legacyWatch = watchMatch[1] === "true";
+      continue;
+    }
+
+    const syncModeMatch = trimmed.match(/^sync_mode:\s*(events|manual)\s*$/);
+    if (syncModeMatch) {
+      config.sync_mode = syncModeMatch[1] as MirrorSyncMode;
+      sawSyncMode = true;
+      continue;
+    }
+
     const locationMatch = trimmed.match(/^location:\s*(internal|external)\s*$/);
     if (locationMatch) {
       config.location = locationMatch[1] as MirrorLocation;
@@ -181,17 +260,47 @@ export function parseMirrorConfig(yaml: string): MirrorConfig | undefined {
       continue;
     }
 
+    const safetyNetMatch = trimmed.match(/^safety_net_seconds:\s*(\d+)\s*$/);
+    if (safetyNetMatch) {
+      const n = parseInt(safetyNetMatch[1]!, 10);
+      if (Number.isFinite(n) && n > 0) {
+        config.safety_net_seconds = clampSafetyNet(n);
+        sawSafetyNet = true;
+      }
+      continue;
+    }
+
     const intervalMatch = trimmed.match(/^interval_seconds:\s*(\d+)\s*$/);
     if (intervalMatch) {
       const n = parseInt(intervalMatch[1]!, 10);
-      if (Number.isFinite(n) && n > 0) config.interval_seconds = n;
+      if (Number.isFinite(n) && n > 0) legacyInterval = n;
       continue;
     }
   }
 
+  // Migration: explicit `sync_mode` wins; otherwise derive from `watch`.
+  // A config that carries neither falls through to defaults (events).
+  if (!sawSyncMode && legacyWatch !== null) {
+    config.sync_mode = legacyWatch ? "events" : "manual";
+  }
+  // Migration: explicit `safety_net_seconds` wins; otherwise upgrade
+  // `interval_seconds` (legacy short-cadence values like 5 get clamped
+  // up to MIN_SAFETY_NET_SECONDS — the safety-net path doesn't want
+  // 5-second polls). Out-of-range values fall through to the default.
+  if (!sawSafetyNet && legacyInterval !== null) {
+    config.safety_net_seconds = clampSafetyNet(legacyInterval);
+  }
+
   return config;
 }
 
+/** Clamp safety_net_seconds to the valid range. */
+function clampSafetyNet(n: number): number {
+  if (n < MIN_SAFETY_NET_SECONDS) return MIN_SAFETY_NET_SECONDS;
+  if (n > MAX_SAFETY_NET_SECONDS) return MAX_SAFETY_NET_SECONDS;
+  return n;
+}
+
 /**
  * Serialize a MirrorConfig as YAML lines suitable for appending under the
  * top-level keys of `config.yaml`. Returns the lines without a trailing
@@ -215,15 +324,234 @@ export function serializeMirrorConfig(config: MirrorConfig): string[] {
       `  external_path: ${needsQuote ? `"${config.external_path}"` : config.external_path}`,
     );
   }
-  lines.push(`  watch: ${config.watch}`);
+  lines.push(`  sync_mode: ${config.sync_mode}`);
   lines.push(`  auto_commit: ${config.auto_commit}`);
   lines.push(`  auto_push: ${config.auto_push}`);
   // Templates contain `{{ }}` and frequently `:` — always quote.
   lines.push(`  commit_template: "${config.commit_template.replace(/"/g, '\\"')}"`);
-  lines.push(`  interval_seconds: ${config.interval_seconds}`);
+  lines.push(`  safety_net_seconds: ${config.safety_net_seconds}`);
   return lines;
 }
 
+// ---------------------------------------------------------------------------
+// Per-vault config storage (vault#400)
+//
+// Each vault's mirror config lives in `data/<vault>/mirror-config.yaml`,
+// alongside its SQLite DB (`vault.db`), config (`vault.yaml`), and per-vault
+// credentials file (`.mirror-credentials.yaml`, vault#399). The file holds
+// the same `mirror:`-prefixed block `serializeMirrorConfig` already emits, so
+// `parseMirrorConfig`/`serializeMirrorConfig` are reused verbatim.
+//
+// Why a separate file from credentials (not folded in): config is
+// non-secret + hand-editable; credentials are 0o600 + token-bearing. Keeping
+// them separate avoids accidentally widening the credentials file's perms,
+// and keeps the credentials migration (vault#399) and config migration
+// (vault#400) cleanly independent.
+//
+// Path resolution mirrors `mirror-credentials.ts` rather than importing
+// `config.ts:vaultDir()` — config.ts imports this module, so importing it
+// back would close a cycle. We re-derive from `PARACHUTE_HOME` (the canonical
+// override the rest of vault honors) instead.
+// ---------------------------------------------------------------------------
+
+/** The vault home root — `<configDir>/vault`. Re-reads PARACHUTE_HOME per call. */
+function vaultHomeRoot(): string {
+  const root = process.env.PARACHUTE_HOME ?? join(homedir(), ".parachute");
+  return join(root, "vault");
+}
+
+/**
+ * Path to a vault's per-vault mirror-config file (vault#400):
+ * `<configDir>/vault/data/<vaultName>/mirror-config.yaml`.
+ */
+export function mirrorConfigPath(vaultName: string): string {
+  return join(vaultHomeRoot(), "data", vaultName, "mirror-config.yaml");
+}
+
+/**
+ * Read a vault's mirror config from its per-vault file. Returns `undefined`
+ * when the file is absent (operator has never configured this vault's
+ * mirror) — distinct from "configured with enabled:false" so callers can
+ * tell "never touched" apart from "explicitly disabled" (same distinction
+ * `parseMirrorConfig` preserves). Callers that just want a usable config
+ * coalesce with `defaultMirrorConfig()`.
+ */
+export function readMirrorConfigForVault(vaultName: string): MirrorConfig | undefined {
+  const path = mirrorConfigPath(vaultName);
+  if (!existsSync(path)) return undefined;
+  try {
+    const raw = readFileSync(path, "utf8");
+    return parseMirrorConfig(raw);
+  } catch {
+    // Unreadable / malformed → treat as "no config" rather than crashing
+    // the boot path or a route. The operator can re-PUT to repair it.
+    return undefined;
+  }
+}
+
+/**
+ * Persist a vault's mirror config to its per-vault file, atomically
+ * (write-temp → rename). Creates the vault data dir if missing (fresh
+ * installs / tests). The file is NOT secret (no tokens — those live in
+ * `.mirror-credentials.yaml`), so default perms are fine.
+ */
+export function writeMirrorConfigForVault(
+  vaultName: string,
+  config: MirrorConfig,
+): void {
+  const path = mirrorConfigPath(vaultName);
+  const dir = dirname(path);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  const body = serializeMirrorConfig(config).join("\n") + "\n";
+  const tmp = `${path}.tmp`;
+  writeFileSync(tmp, body);
+  renameSync(tmp, path);
+}
+
+// ---------------------------------------------------------------------------
+// Migration — legacy server-wide `mirror:` config → per-vault (vault#400)
+// ---------------------------------------------------------------------------
+
+/**
+ * One-time migration of the legacy server-wide `mirror:` config block to the
+ * per-vault layout (vault#400). Symmetric counterpart to vault#399's
+ * `migrateLegacyServerWideCredentials`.
+ *
+ * The bug: pre-vault#400, mirror config lived in a single `mirror:` block in
+ * `<configDir>/vault/config.yaml`, shared across ALL vaults. Every vault's
+ * mirror page rendered that one config (+ the owning vault's git remote);
+ * configuring vault B clobbered vault A.
+ *
+ * Attribution: attribute the legacy block to the mirror-owning vault
+ * (`resolveMirrorVaultName` = default_vault → first listed) — the same vault
+ * the single server-wide mirror was actually bound to. Other vaults start
+ * with no mirror config (they read `undefined` → default disabled).
+ *
+ * Safety:
+ *   - No-op when no legacy block exists (fresh installs, already-migrated).
+ *   - No-op when the target vault already has a per-vault config file (don't
+ *     clobber config the operator set post-migration).
+ *   - The legacy block is preserved (commented out in place) rather than
+ *     silently dropped, so nothing is lost if attribution was wrong.
+ *   - Logs the attribution decision clearly.
+ *
+ * This function is intentionally I/O-light on the config.yaml side: it takes
+ * the raw config.yaml text + a rewriter callback so it doesn't import
+ * `config.ts` (which imports this module). server.ts supplies the read/write.
+ *
+ * @param legacyConfig the `mirror:` block parsed from config.yaml, or
+ *   undefined when there is none. server.ts passes `readGlobalConfig().mirror`.
+ * @param targetVaultName the vault to attribute the legacy config to
+ *   (caller passes `resolveMirrorVaultName()`).
+ * @param commentOutLegacyBlock callback that rewrites config.yaml to comment
+ *   out the `mirror:` block (so it isn't re-migrated + the operator can see
+ *   the old values). Best-effort; failure is non-fatal.
+ * @returns a struct describing what happened, for logging + tests.
+ */
+export function migrateLegacyServerWideConfig(
+  legacyConfig: MirrorConfig | undefined,
+  targetVaultName: string | null,
+  commentOutLegacyBlock: () => void,
+):
+  | { migrated: false; reason: "no_legacy_block" | "no_target_vault" | "target_already_configured" }
+  | { migrated: true; targetVaultName: string } {
+  if (!legacyConfig) {
+    return { migrated: false, reason: "no_legacy_block" };
+  }
+  if (!targetVaultName) {
+    // Legacy block present but no vault to attribute it to. Leave it in
+    // place — a future boot (once a vault exists) migrates it.
+    return { migrated: false, reason: "no_target_vault" };
+  }
+  const targetPath = mirrorConfigPath(targetVaultName);
+  if (existsSync(targetPath)) {
+    // Target vault already has per-vault config. Don't clobber. Still
+    // comment out the legacy block so we don't re-evaluate it every boot.
+    try {
+      commentOutLegacyBlock();
+    } catch {
+      // Non-fatal — worst case we re-check next boot and short-circuit here.
+    }
+    return { migrated: false, reason: "target_already_configured" };
+  }
+
+  writeMirrorConfigForVault(targetVaultName, legacyConfig);
+  try {
+    commentOutLegacyBlock();
+  } catch {
+    // Non-fatal — the config is now in the per-vault file; the legacy block
+    // staying live would just re-migrate to the same place idempotently
+    // (the target_already_configured branch short-circuits next boot).
+  }
+
+  console.log(
+    `[mirror] migrated legacy server-wide mirror config → vault "${targetVaultName}" ` +
+      `(per-vault, vault#400). Other vaults start with no mirror config (configure each ` +
+      `separately). Legacy config.yaml \`mirror:\` block commented out (preserved for reference).`,
+  );
+  return { migrated: true, targetVaultName };
+}
+
+/**
+ * Pure string transform: comment out the server-wide `mirror:` block in a
+ * config.yaml string (vault#400 migration). Prefixes each line of the block
+ * with `# ` so the operator can still see the migrated values + nothing is
+ * silently dropped, and a subsequent boot's `parseMirrorConfig` no longer
+ * sees a LIVE block (so no re-migration — `parseMirrorConfig`'s anchor regex
+ * `^mirror:\s*$` doesn't match `# mirror:`).
+ *
+ * Block boundaries match the parser's stop rule exactly: the block starts at
+ * a 0-indent `mirror:` line and runs until the next 0-indent non-blank line
+ * (the next top-level key). Other top-level keys (port, default_vault, …) are
+ * left byte-for-byte intact; blank lines are preserved verbatim (not
+ * commented). Idempotent: an already-commented config has no live `mirror:`
+ * line, so it passes through unchanged.
+ *
+ * Extracted from server.ts (vault#408 review N3) so the YAML rewriting — which
+ * runs against the operator's real config.yaml — is directly unit-tested.
+ */
+export function commentOutMirrorBlock(yaml: string): string {
+  const lines = yaml.split("\n");
+  const out: string[] = [];
+  let inBlock = false;
+  for (const line of lines) {
+    if (!inBlock && /^mirror:\s*$/.test(line)) {
+      inBlock = true;
+      out.push(`# [vault#400] migrated to per-vault data/<vault>/mirror-config.yaml`);
+      out.push(`# ${line}`);
+      continue;
+    }
+    if (inBlock) {
+      // The block runs until the next top-level (0-indent, non-blank) key.
+      if (/^\S/.test(line) && line.trim().length > 0) {
+        inBlock = false;
+        out.push(line);
+      } else if (line.trim().length === 0) {
+        // Preserve blank lines verbatim (don't comment them).
+        out.push(line);
+      } else {
+        out.push(`# ${line}`);
+      }
+      continue;
+    }
+    out.push(line);
+  }
+  return out.join("\n");
+}
+
+/**
+ * File-I/O wrapper around `commentOutMirrorBlock`: read config.yaml at
+ * `configPath`, comment out its `mirror:` block, write it back. No-op when
+ * the file is absent. server.ts passes this (bound to GLOBAL_CONFIG_PATH) as
+ * the migration's `commentOutLegacyBlock` callback. Best-effort — callers
+ * treat a throw as non-fatal.
+ */
+export function commentOutLegacyMirrorBlockFile(configPath: string): void {
+  if (!existsSync(configPath)) return;
+  const yaml = readFileSync(configPath, "utf8");
+  writeFileSync(configPath, commentOutMirrorBlock(yaml));
+}
+
 // ---------------------------------------------------------------------------
 // Path resolution
 // ---------------------------------------------------------------------------
@@ -285,12 +613,31 @@ export type ShapeValidation = ShapeValidationOk | ShapeValidationError;
  * `defaultMirrorConfig()`; rejects values that don't conform to the
  * declared types.
  *
- * Does NOT touch the filesystem — operators get a fast 400 on shape
- * errors before vault attempts any filesystem work. Filesystem-level
- * validation (path exists, is a git repo) lives in `validateExternalPath`.
+ * Mostly pure: the one filesystem touch is reading
+ * `.mirror-credentials.yaml` to decide whether `auto_push: true +
+ * location: internal` is acceptable (credentials carry a remote URL, so
+ * "internal mirrors have no remote" no longer holds). The credentials
+ * read is injectable via `opts.readCredentials` so tests stay hermetic;
+ * production callers omit it and pick up the canonical `readCredentials`
+ * from `./mirror-credentials.ts`.
+ *
+ * Filesystem-level validation of `external_path` (exists, is a git repo)
+ * still lives in `validateExternalPath` — that's I/O and stays out of
+ * this function.
  */
 export function validateMirrorConfigShape(
   input: unknown,
+  opts: {
+    /**
+     * Vault whose credentials gate `auto_push + internal`. Required for the
+     * production credential read (per-vault since vault#399). Omitting it
+     * AND `readCredentials` means the auto_push/internal credential check
+     * treats credentials as absent (fail-closed) — fine for callers that
+     * never set that combination.
+     */
+    vaultName?: string;
+    readCredentials?: () => MirrorCredentials | null;
+  } = {},
 ): ShapeValidation {
   if (input === null || typeof input !== "object") {
     return {
@@ -334,11 +681,24 @@ export function validateMirrorConfigShape(
     }
   }
 
+  // Legacy back-compat: `watch: boolean` translates to sync_mode.
+  // `sync_mode` takes priority if both are present.
   if ("watch" in blob) {
     if (typeof blob.watch !== "boolean") {
-      return { ok: false, field: "watch", error: "`watch` must be boolean." };
+      return { ok: false, error: "`watch` must be boolean." };
+    }
+    out.sync_mode = blob.watch ? "events" : "manual";
+  }
+
+  if ("sync_mode" in blob) {
+    if (blob.sync_mode !== "events" && blob.sync_mode !== "manual") {
+      return {
+        ok: false,
+        field: "sync_mode",
+        error: '`sync_mode` must be "events" or "manual".',
+      };
     }
-    out.watch = blob.watch;
+    out.sync_mode = blob.sync_mode;
   }
 
   if ("auto_commit" in blob) {
@@ -382,7 +742,33 @@ export function validateMirrorConfigShape(
     out.commit_template = blob.commit_template;
   }
 
-  if ("interval_seconds" in blob) {
+  if ("safety_net_seconds" in blob) {
+    if (
+      typeof blob.safety_net_seconds !== "number" ||
+      !Number.isFinite(blob.safety_net_seconds) ||
+      blob.safety_net_seconds <= 0 ||
+      !Number.isInteger(blob.safety_net_seconds)
+    ) {
+      return {
+        ok: false,
+        field: "safety_net_seconds",
+        error: "`safety_net_seconds` must be a positive integer.",
+      };
+    }
+    if (
+      blob.safety_net_seconds < MIN_SAFETY_NET_SECONDS ||
+      blob.safety_net_seconds > MAX_SAFETY_NET_SECONDS
+    ) {
+      return {
+        ok: false,
+        field: "safety_net_seconds",
+        error: `\`safety_net_seconds\` must be between ${MIN_SAFETY_NET_SECONDS} and ${MAX_SAFETY_NET_SECONDS}.`,
+      };
+    }
+    out.safety_net_seconds = blob.safety_net_seconds;
+  } else if ("interval_seconds" in blob) {
+    // Legacy field still accepted for hand-edited configs. Migrate by
+    // clamping into the safety-net range.
     if (
       typeof blob.interval_seconds !== "number" ||
       !Number.isFinite(blob.interval_seconds) ||
@@ -391,11 +777,15 @@ export function validateMirrorConfigShape(
     ) {
       return {
         ok: false,
-        field: "interval_seconds",
         error: "`interval_seconds` must be a positive integer.",
       };
     }
-    out.interval_seconds = blob.interval_seconds;
+    const clamped = blob.interval_seconds < MIN_SAFETY_NET_SECONDS
+      ? MIN_SAFETY_NET_SECONDS
+      : blob.interval_seconds > MAX_SAFETY_NET_SECONDS
+        ? MAX_SAFETY_NET_SECONDS
+        : blob.interval_seconds;
+    out.safety_net_seconds = clamped;
   }
 
   // Cross-field rule: external requires external_path — but ONLY when
@@ -414,6 +804,67 @@ export function validateMirrorConfigShape(
     };
   }
 
+  // Cross-field rule: auto_push + internal location was historically
+  // rejected outright — the assumption being "internal mirrors live under
+  // vault's data dir with no configured remote, so push would always
+  // fail." That assumption no longer holds once credentials are wired:
+  // the credential save path (handleAuthPat / handleAuthGithubSelectRepo)
+  // sets `origin` on the internal repo to the embedded-credential URL,
+  // so `git push` to GitHub/GitLab/etc. is meaningful even when the
+  // working tree lives under `~/.parachute/vault/data/<name>/mirror/`.
+  //
+  // New rule: auto_push + internal is rejected ONLY when no credentials
+  // are configured. If credentials ARE wired (PAT or GitHub OAuth),
+  // accept the combination — vault has a remote to push to. Operators
+  // hitting Aaron's three-stacking-gaps bug (History preset + PAT saved,
+  // pushes never fire) get unblocked.
+  //
+  // Asymmetry note (reviewer-flagged on vault#392): external + auto_push +
+  // no vault-stored credentials is INTENTIONALLY not rejected here.
+  // External mirrors are operator-managed paths — operators may have
+  // configured push credentials via system-level git config (SSH agent,
+  // ~/.git-credentials, GH_TOKEN env, `gh auth login`), none of which
+  // vault can detect by reading `.mirror-credentials.yaml`. Rejecting on
+  // "vault doesn't see credentials" would refuse legitimate
+  // operator-managed setups. Push failures on missing credentials surface
+  // via the non-fatal warning path in gitPush — operators see them in
+  // `last_push_error` rather than being blocked at save time. Internal
+  // location is different: internal mirrors live under vault's data
+  // dir, so vault IS the only thing that can wire a remote, which is
+  // why the gate below requires vault-stored credentials specifically.
+  if (out.enabled && out.auto_push && out.location === "internal") {
+    // Per-vault credentials (vault#399): bind the read to opts.vaultName.
+    // When neither an injected reader nor a vaultName is supplied, treat
+    // credentials as absent (fail-closed) rather than reading a wrong file.
+    const readCreds =
+      opts.readCredentials ??
+      (opts.vaultName ? () => readCredentials(opts.vaultName!) : () => null);
+    let creds: MirrorCredentials | null = null;
+    try {
+      creds = readCreds();
+    } catch {
+      // If the credentials file is unreadable we conservatively fail
+      // closed — same outcome as "no credentials." Better to surface the
+      // actionable "configure credentials first" error than to accept a
+      // config that won't actually push.
+      creds = null;
+    }
+    const hasCredentials = !!(
+      creds &&
+      creds.active_method &&
+      ((creds.active_method === "pat" && creds.pat) ||
+        (creds.active_method === "github_oauth" && creds.github_oauth))
+    );
+    if (!hasCredentials) {
+      return {
+        ok: false,
+        field: "auto_push",
+        error:
+          "Configure git credentials before enabling auto-push on an internal mirror — vault has no remote to push to without them. Connect GitHub or paste a Personal Access Token in the Git remote section, or set auto_push to false.",
+      };
+    }
+  }
+
   return { ok: true, config: out };
 }