@openparachute/vault 0.6.3 → 0.6.4-rc.10

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;
@@ -1665,11 +1674,11 @@ function cmdRemove(args: string[]) {
   // out of the parachute-vault row immediately — the same selfRegister
   // refresh cmdCreate does (#208). Without this, the hub's well-known
   // fan-out kept advertising the deleted vault until the next server boot.
-  // Note: with zero vaults remaining, selfRegister falls back to the
-  // manifest's canonical paths (`/vault/default`) — the same row a
-  // subsequent boot would write — so CLI-remove and boot agree on the
-  // zero-vault registration shape. Warnings go to stderr; status lines stay
-  // ours.
+  // Note: with zero vaults remaining, selfRegister emits paths: [] (#478) —
+  // the row stays present (so the hub still sees the module as installed)
+  // but advertises no /vault/<name> path. The hub must tolerate empty-paths
+  // rows and skip them rather than resolving a phantom "default". Warnings
+  // go to stderr; status lines stay ours.
   selfRegister({
     version: pkg.version,
     warn: (msg) => console.error(`Warning: ${msg}`),
@@ -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>`
 // ---------------------------------------------------------------------------
@@ -3345,11 +3511,17 @@ async function cmdExport(args: string[]) {
  */
 async function cmdSchema(args: string[] = []) {
   const sub = args[0];
+  if (sub === "migrate-field") {
+    await cmdSchemaMigrateField(args.slice(1));
+    return;
+  }
   if (sub !== "prune") {
-    console.error("Usage: parachute-vault schema prune [--vault <name>] [--dry-run|--apply|--yes]");
+    console.error("Usage: parachute-vault schema <prune|migrate-field> ...");
     console.error("\nSubcommands:");
-    console.error("  prune    Drop orphaned indexed-field columns whose declaring tags are gone.");
-    console.error("           Dry-run by default (--dry-run is an explicit alias); pass --apply (or --yes) to execute.");
+    console.error("  prune          Drop orphaned indexed-field columns whose declaring tags are gone.");
+    console.error("                 Dry-run by default (--dry-run is an explicit alias); pass --apply (or --yes) to execute.");
+    console.error("  migrate-field  Evolve a tag-schema field across existing notes (rename/remap/set-default/retype).");
+    console.error("                 Dry-run by default; pass --apply (or --yes) to write. See `schema migrate-field --help`.");
     process.exit(1);
   }
 
@@ -3416,6 +3588,154 @@ async function cmdSchema(args: string[] = []) {
   }
 }
 
+/**
+ * `parachute-vault schema migrate-field <tag> <field> --transform <spec>` —
+ * evolve a tag-schema field's type / values across the existing notes that
+ * carry the tag (vault#314). Dry-run by default — prints the count + a sample
+ * of what WOULD change and writes nothing; `--apply` (alias `--yes`) executes.
+ *
+ * Transform specs (the built-in set — issue #314):
+ *   rename:<newkey>          move the field's value to <newkey>, drop the old key
+ *   remap:<old>=<new>[,…]    rewrite enum-style values (repeatable / comma-sep)
+ *   set-default:<value>      fill the field where missing/null
+ *   set-default-invalid:<v>  set <v> where missing/null OR currently schema-invalid
+ *   to_string | to_int | to_number | to_boolean   retype the value
+ *
+ * The migration writes through `strict` enforcement (the migrate-bypass path,
+ * vault#299) so a freshly-declared strict field that the back-catalog violates
+ * doesn't block the rewrite, and every bypassed write is logged. Rewrites are
+ * attributed `migrate` (last_updated_*); created_* is preserved.
+ *
+ * Atomic by default: if any note's value can't be converted (e.g. `to_int` on
+ * "banana"), the apply aborts BEFORE writing anything and lists the offenders.
+ * Pass `--continue-on-error` for best-effort (write the convertible, skip the rest).
+ */
+async function cmdSchemaMigrateField(args: string[]) {
+  const usageLine =
+    "Usage: parachute-vault schema migrate-field <tag> <field> --transform <spec> [--vault <name>] [--apply|--yes] [--continue-on-error]";
+  if (args[0] === "--help" || args[0] === "-h") {
+    console.log(usageLine);
+    console.log("\nTransform specs:");
+    console.log("  rename:<newkey>          Move the field's value to <newkey>, drop the old key.");
+    console.log("  remap:<old>=<new>[,...]  Rewrite enum-style values (repeatable, comma-separated).");
+    console.log("  set-default:<value>      Set <value> on notes where the field is missing/null.");
+    console.log("  set-default-invalid:<v>  Set <v> where missing/null OR the current value is schema-invalid.");
+    console.log("  to_string | to_int | to_number | to_boolean   Retype the field's value.");
+    console.log("\nDry-run by default — prints the plan. Pass --apply (or --yes) to write.");
+    return;
+  }
+
+  let vaultName = "default";
+  let apply = false;
+  let continueOnError = false;
+  let transformSpec: string | undefined;
+  const positionals: string[] = [];
+  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 === "--transform") {
+      const v = args[++i];
+      if (!v) { console.error("--transform requires a value."); process.exit(1); }
+      transformSpec = v;
+    } else if (arg === "--apply" || arg === "--yes") {
+      apply = true;
+    } else if (arg === "--dry-run") {
+      // default; accept as an explicit affirmative
+    } else if (arg === "--continue-on-error") {
+      continueOnError = true;
+    } else if (arg.startsWith("--")) {
+      console.error(`Unknown flag for \`schema migrate-field\`: ${arg}`);
+      process.exit(1);
+    } else {
+      positionals.push(arg);
+    }
+  }
+
+  const [tag, field] = positionals;
+  if (!tag || !field || !transformSpec) {
+    console.error(usageLine);
+    console.error("\n  <tag> <field> and --transform <spec> are all required.");
+    console.error("  Run `schema migrate-field --help` for the transform spec list.");
+    process.exit(1);
+  }
+
+  const { parseTransformSpec } = await import("../core/src/migrate-tag-field.ts");
+  let transform;
+  try {
+    transform = parseTransformSpec(transformSpec);
+  } catch (err) {
+    console.error(`Invalid --transform "${transformSpec}": ${(err as Error).message}`);
+    process.exit(1);
+  }
+
+  const config = readVaultConfig(vaultName);
+  if (!config) {
+    console.error(`Vault "${vaultName}" not found.`);
+    process.exit(1);
+  }
+
+  const { getVaultStore } = await import("./vault-store.ts");
+  const { migrateTagField } = await import("../core/src/migrate-tag-field.ts");
+  const { logStrictBypass } = await import("./scopes.ts");
+  const store = getVaultStore(vaultName);
+
+  const result = await migrateTagField(store, {
+    tag,
+    field,
+    transform: transform!,
+    apply,
+    continueOnError,
+    // The CLI is the operator path — it bypasses strict enforcement by nature
+    // (writes go through the store, not the scope-gated transport). Log every
+    // waived violation so the bypass is auditable, exactly as MW2 intends.
+    onStrictBypass: (info) => logStrictBypass(info),
+  });
+
+  const verb = result.applied ? "Migrated" : "Would migrate";
+  console.log(
+    `${verb} field "${result.field}" on #${result.tag} in vault "${vaultName}"${result.applied ? "" : " (dry-run)"}:`,
+  );
+  console.log(
+    `  scanned ${result.scanned} · ${result.applied ? "changed" : "would change"} ${result.changed} · unchanged ${result.unchanged} · errored ${result.errored}`,
+  );
+
+  if (result.sample.length > 0) {
+    console.log(`\n  ${result.applied ? "Changes" : "Sample of changes"} (${result.sample.length}${result.changed > result.sample.length ? ` of ${result.changed}` : ""}):`);
+    for (const c of result.sample) {
+      const ref = c.path ?? c.id;
+      if (c.renamedTo) {
+        console.log(`    ${ref}: ${field} → ${c.renamedTo} = ${JSON.stringify(c.after)}`);
+      } else {
+        console.log(`    ${ref}: ${JSON.stringify(c.before)} → ${JSON.stringify(c.after)}`);
+      }
+    }
+  }
+
+  if (result.errors.length > 0) {
+    console.log(`\n  Unconvertible (${result.errors.length}):`);
+    for (const e of result.errors) {
+      console.log(`    ${e.path ?? e.id}: ${e.error}`);
+    }
+    if (apply && !result.applied) {
+      console.log(
+        "\n  Aborted without writing — some notes can't be converted (atomic by default).",
+      );
+      console.log("  Fix the data, or re-run with --continue-on-error to migrate the rest.");
+      process.exit(1);
+    }
+  }
+
+  if (!apply && result.changed > 0) {
+    console.log("\n  Re-run with --apply (or --yes) to write these changes.");
+  }
+  if (result.changed === 0 && result.errored === 0) {
+    console.log("\n  Nothing to migrate — the back-catalog already conforms.");
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Export-watch glue. The git-shell + commit-message logic lives in
 // `./export-watch.ts` for unit-testability; cli.ts just wires it in.
@@ -3952,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
@@ -3961,6 +4290,13 @@ Schema maintenance:
   parachute-vault schema prune --apply                Execute the prune (alias: --yes). Co-declared
                                                        fields keep their column; a drop loses only
                                                        the index (data lives in notes.metadata).
+  parachute-vault schema migrate-field <tag> <field>  Evolve a tag-schema field across existing
+    --transform <spec>                                 notes (rename:<key>, remap:<old>=<new>,
+                                                       set-default:<v>, to_string/to_int/to_number/
+                                                       to_boolean). Dry-run by default — prints the
+                                                       plan; pass --apply (or --yes) to write.
+                                                       Writes through strict enforcement (migrate
+                                                       bypass). See \`schema migrate-field --help\`.
 
 ── Advanced / standalone ──────────────────────────────────────────────
 

package/src/config.ts

@@ -215,6 +215,17 @@ export interface TriggerWhen {
   missing_metadata?: string[];
   /** Note.metadata must have ALL of these keys set (non-null). */
   has_metadata?: string[];
+  /**
+   * Value-matched metadata predicate (vault#299 Part B). A map of
+   * field → operator-object, evaluated against the note's live metadata with
+   * the SAME operators as `query-notes` (eq/ne/gt/gte/lt/lte/in/not_in/exists)
+   * via the shared `matchesOperator` engine. ALL entries must match (AND).
+   * Lets a trigger fire only on a specific transition — e.g.
+   * `metadata: { state: { eq: "published" } }` fires when a note reaches
+   * `published`, not on every edit. Combines with the presence/tag/content
+   * filters above (all must hold).
+   */
+  metadata?: Record<string, Record<string, unknown>>;
 }
 
 /**

package/src/first-boot-create.test.ts

@@ -0,0 +1,155 @@
+/**
+ * Integration tests for the first-boot vault creation gate introduced in
+ * vault#478 Part 2 — server creates a vault ONLY when PARACHUTE_VAULT_NAME
+ * is explicitly set.
+ *
+ * Each test spawns a real server subprocess against a fresh PARACHUTE_HOME
+ * tmpdir (the stop-signal.test.ts pattern) and probes over HTTP so the
+ * actual Bun.serve boot path is exercised, not a mocked code path.
+ *
+ * Port assignments (chosen to avoid collisions with the running daemon on
+ * 1940 and stop-signal.test.ts on 19404):
+ *   19410 — test 1: PARACHUTE_VAULT_NAME unset → zero vaults
+ *   19411 — test 2: PARACHUTE_VAULT_NAME=testvault → vault created
+ *
+ * NOTE: the unit-level assertions for resolveFirstBootVaultName (source:
+ * "default" / "env" / "env-invalid") already live in vault-name.test.ts.
+ * These tests cover the SERVER-LEVEL behaviour — whether a vault is actually
+ * created on disk — so they are intentionally non-duplicative.
+ */
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync, mkdirSync, existsSync } from "fs";
+import { tmpdir } from "os";
+import { join, resolve } from "path";
+import { waitForHealthy } from "./health.ts";
+import { listVaults } from "./config.ts";
+
+const SERVER_PATH = resolve(import.meta.dir, "server.ts");
+
+// ---------------------------------------------------------------------------
+// Test 1 — PARACHUTE_VAULT_NAME unset
+// ---------------------------------------------------------------------------
+
+const PORT_NO_ENV = 19_410;
+let tmpHomeNoEnv: string;
+
+beforeAll(() => {
+  tmpHomeNoEnv = mkdtempSync(join(tmpdir(), "vault-first-boot-no-env-"));
+  mkdirSync(join(tmpHomeNoEnv, "vault"), { recursive: true });
+});
+
+afterAll(() => {
+  rmSync(tmpHomeNoEnv, { recursive: true, force: true });
+});
+
+describe("first-boot: PARACHUTE_VAULT_NAME unset → zero vaults", () => {
+  test("server is healthy AND no vault was auto-created", async () => {
+    const proc = Bun.spawn({
+      cmd: ["bun", SERVER_PATH],
+      env: {
+        ...process.env,
+        PARACHUTE_HOME: tmpHomeNoEnv,
+        PORT: String(PORT_NO_ENV),
+        // Must be unset — do NOT inherit from the test runner's shell.
+        PARACHUTE_VAULT_NAME: undefined as unknown as string,
+        SCRIBE_URL: "",
+      },
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+
+    try {
+      const health = await waitForHealthy(PORT_NO_ENV, { totalMs: 15_000 });
+      expect(health.status).toBe("healthy");
+
+      // Verify zero vaults were created inside the tmp home.
+      const originalHome = process.env.PARACHUTE_HOME;
+      try {
+        process.env.PARACHUTE_HOME = tmpHomeNoEnv;
+        const vaults = listVaults();
+        expect(vaults).toHaveLength(0);
+        expect(vaults).not.toContain("default");
+      } finally {
+        if (originalHome === undefined) delete process.env.PARACHUTE_HOME;
+        else process.env.PARACHUTE_HOME = originalHome;
+      }
+
+      // Also assert no vault.yaml was written (belt-and-suspenders).
+      // Path structure: <PARACHUTE_HOME>/vault/data/<name>/vault.yaml
+      const defaultVaultConfig = join(tmpHomeNoEnv, "vault", "data", "default", "vault.yaml");
+      expect(existsSync(defaultVaultConfig)).toBe(false);
+    } finally {
+      if (!proc.killed) proc.kill();
+      await proc.exited;
+    }
+  }, 25_000);
+});
+
+// ---------------------------------------------------------------------------
+// Test 2 — PARACHUTE_VAULT_NAME=testvault → vault created
+// ---------------------------------------------------------------------------
+
+const PORT_WITH_ENV = 19_411;
+let tmpHomeWithEnv: string;
+
+// We need separate beforeAll/afterAll scopes for the two server lifetimes.
+// Bun:test describe blocks share the outer beforeAll/afterAll, so we use
+// module-level variables and a nested describe with its own lifecycle hooks.
+describe("first-boot: PARACHUTE_VAULT_NAME=testvault → vault created", () => {
+  let proc: ReturnType<typeof Bun.spawn>;
+
+  beforeAll(async () => {
+    tmpHomeWithEnv = mkdtempSync(join(tmpdir(), "vault-first-boot-with-env-"));
+    mkdirSync(join(tmpHomeWithEnv, "vault"), { recursive: true });
+
+    proc = Bun.spawn({
+      cmd: ["bun", SERVER_PATH],
+      env: {
+        ...process.env,
+        PARACHUTE_HOME: tmpHomeWithEnv,
+        PORT: String(PORT_WITH_ENV),
+        PARACHUTE_VAULT_NAME: "testvault",
+        SCRIBE_URL: "",
+      },
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+
+    const health = await waitForHealthy(PORT_WITH_ENV, { totalMs: 15_000 });
+    if (health.status !== "healthy") {
+      proc.kill();
+      throw new Error(`server failed to become healthy: ${health.status} (${health.error ?? ""})`);
+    }
+  });
+
+  afterAll(async () => {
+    if (proc && !proc.killed) proc.kill();
+    await proc?.exited;
+    rmSync(tmpHomeWithEnv, { recursive: true, force: true });
+  });
+
+  test('vault "testvault" was created (not "default")', () => {
+    const originalHome = process.env.PARACHUTE_HOME;
+    try {
+      process.env.PARACHUTE_HOME = tmpHomeWithEnv;
+      const vaults = listVaults();
+      expect(vaults).toContain("testvault");
+      expect(vaults).not.toContain("default");
+      expect(vaults).toHaveLength(1);
+    } finally {
+      if (originalHome === undefined) delete process.env.PARACHUTE_HOME;
+      else process.env.PARACHUTE_HOME = originalHome;
+    }
+  });
+
+  test("vault config dir exists at the correct path", () => {
+    // Path structure: <PARACHUTE_HOME>/vault/data/<name>/vault.yaml
+    const vaultConfigPath = join(tmpHomeWithEnv, "vault", "data", "testvault", "vault.yaml");
+    expect(existsSync(vaultConfigPath)).toBe(true);
+
+    // "default" must NOT have been created.
+    const defaultConfigPath = join(tmpHomeWithEnv, "vault", "data", "default", "vault.yaml");
+    expect(existsSync(defaultConfigPath)).toBe(false);
+  });
+});

package/src/import-daemon-busy.test.ts

@@ -15,30 +15,21 @@ import { resolve } from "path";
 import { mkdtempSync, rmSync, writeFileSync, mkdirSync } from "fs";
 import { tmpdir } from "os";
 import { join } from "path";
+import { runSubprocess } from "./test-support/spawn.ts";
 
 const CLI = resolve(import.meta.dir, "cli.ts");
 
+// Async spawn — the daemon-busy probe inside the CLI fetches the test
+// process's stub server, so the parent event loop must keep servicing
+// requests while the child runs. `Bun.spawnSync` blocks the event loop and
+// the in-test server can't answer, which makes every probe time out into
+// the "not listening" branch (vault#324). `runSubprocess` is the shared
+// safe primitive (vault#325 Part 1) — see src/test-support/spawn.ts.
 async function runCli(
   args: string[],
   env: Record<string, string>,
 ): Promise<{ exitCode: number; stdout: string; stderr: string }> {
-  // Async spawn — the daemon-busy probe inside the CLI fetches the test
-  // process's stub server, so the parent event loop must keep servicing
-  // requests while the child runs. Bun.spawnSync blocks the event loop
-  // and the in-test server can't answer, which makes every probe time
-  // out into the "not listening" branch.
-  const proc = Bun.spawn({
-    cmd: ["bun", CLI, ...args],
-    stdout: "pipe",
-    stderr: "pipe",
-    env: { ...process.env, ...env },
-  });
-  const [stdout, stderr, exitCode] = await Promise.all([
-    new Response(proc.stdout).text(),
-    new Response(proc.stderr).text(),
-    proc.exited,
-  ]);
-  return { exitCode: exitCode ?? -1, stdout, stderr };
+  return runSubprocess({ cmd: ["bun", CLI, ...args], env });
 }
 
 let home: string;

package/src/mcp-http.ts

@@ -151,6 +151,11 @@ async function handleMcp(
         note_path?: string | null;
         current_updated_at?: string | null;
         expected_updated_at?: string;
+        field?: string;
+        expected_from?: unknown;
+        to?: unknown;
+        current?: unknown;
+        violations?: unknown;
       };
       if (e?.code === "CONFLICT") {
         throw new McpError(ErrorCode.InvalidRequest, message, {
@@ -161,6 +166,28 @@ async function handleMcp(
           note_id: e.note_id,
         });
       }
+      // State-transition compare-and-set conflict (vault#299 Part B) — a
+      // DISTINCT vocabulary from `conflict` (settled lead #3): the value
+      // didn't match, not the updated_at token.
+      if (e?.code === "TRANSITION_CONFLICT") {
+        throw new McpError(ErrorCode.InvalidRequest, message, {
+          error_type: "transition_conflict",
+          note_id: e.note_id,
+          path: e.note_path ?? null,
+          field: e.field,
+          expected_from: e.expected_from,
+          to: e.to,
+          current: e.current ?? null,
+        });
+      }
+      // Strict-schema rejection (vault#299 Part A) — one error carrying ALL
+      // per-field violations (settled lead #1).
+      if (e?.code === "SCHEMA_VALIDATION") {
+        throw new McpError(ErrorCode.InvalidParams, message, {
+          error_type: "schema_validation",
+          violations: e.violations ?? [],
+        });
+      }
       if (e?.code === "PRECONDITION_REQUIRED") {
         throw new McpError(ErrorCode.InvalidParams, message, {
           error_type: "precondition_required",