@openparachute/vault 0.6.4-rc.9 → 0.6.4

package/core/src/notes.ts

@@ -19,6 +19,7 @@ import {
   type QueryHashInputs,
 } from "./cursor.js";
 import { getIndexedField, releaseField } from "./indexed-fields.js";
+import { stripTagHash } from "./tag-hierarchy.js";
 
 let idCounter = 0;
 
@@ -686,8 +687,14 @@ export function queryNotes(db: Database, opts: QueryOpts): Note[] {
   // rides idx_note_tags_tag, produces each note id at most once, and lets
   // the whole query drop DISTINCT. See the 2026-06-10 perf measurements.
   if (opts.tags && opts.tags.length > 0) {
+    // Canonical-bare-tag guard (vault#XXX) backstop for direct-core callers
+    // that bypass BunSqliteStore.normalizeQueryTags (the store normalizes +
+    // hierarchy-expands before reaching here; this protects the raw noteOps
+    // entry point and tests). `_tagsExpanded`, when present, was already built
+    // from bare names by the store, so prefer it; otherwise strip the literal
+    // tags. No-op on already-bare input.
     const tagSets: string[][] = (opts as QueryOpts & { _tagsExpanded?: string[][] })._tagsExpanded
-      ?? opts.tags.map((t) => [t]);
+      ?? opts.tags.map((t) => [stripTagHash(t)]);
     const match = opts.tagMatch ?? "all";
     if (match === "any") {
       // Flatten all expanded sets and dedupe — a note tagged with any one
@@ -710,9 +717,11 @@ export function queryNotes(db: Database, opts: QueryOpts): Note[] {
     }
   }
 
-  // Exclude tags
+  // Exclude tags — bare-tag guard backstop (see tags block above).
   if (opts.excludeTags && opts.excludeTags.length > 0) {
-    for (const tag of opts.excludeTags) {
+    for (const rawTag of opts.excludeTags) {
+      const tag = stripTagHash(rawTag);
+      if (tag === "") continue;
       conditions.push(`NOT EXISTS (SELECT 1 FROM note_tags ex WHERE ex.note_id = n.id AND ex.tag_name = ?)`);
       params.push(tag);
     }
@@ -1189,11 +1198,18 @@ export function searchNotes(
   const limit = typeof opts?.limit === "number" ? opts.limit : 50;
 
   if (opts?.tags && opts.tags.length > 0) {
+    // Canonical-bare-tag guard backstop (vault#XXX) for direct-core callers.
+    const searchTags = opts.tags.map(stripTagHash).filter((t) => t !== "");
+    if (searchTags.length === 0) {
+      // All tag filters collapsed to empty — fall through to the untagged
+      // search path below (no tag constraint).
+      opts = { ...opts, tags: undefined };
+    } else {
     try {
       // Tag membership as a semijoin — same rationale as queryNotes: a
       // `JOIN note_tags` multiplies rows for multi-tagged notes and forced
       // DISTINCT over full rows. The FTS join itself is 1:1 on rowid.
-      const tagPlaceholders = opts.tags.map(() => "?").join(", ");
+      const tagPlaceholders = searchTags.map(() => "?").join(", ");
       const rows = db.prepare(`
         SELECT n.* FROM notes n
         JOIN notes_fts fts ON fts.rowid = n.rowid
@@ -1201,11 +1217,12 @@ export function searchNotes(
           AND n.id IN (SELECT note_id FROM note_tags WHERE tag_name IN (${tagPlaceholders}))
         ORDER BY rank
         LIMIT ?
-      `).all(query, ...opts.tags, limit) as NoteRow[];
+      `).all(query, ...searchTags, limit) as NoteRow[];
       return notesWithTags(db, rows);
     } catch {
       return [];
     }
+    }
   }
 
   try {
@@ -1236,7 +1253,15 @@ export function tagNote(db: Database, noteId: string, tags: string[]): void {
   const insertTag = db.prepare("INSERT OR IGNORE INTO tags (name) VALUES (?)");
   const insertNoteTag = db.prepare("INSERT OR IGNORE INTO note_tags (note_id, tag_name) VALUES (?, ?)");
 
-  for (const tag of tags) {
+  // Canonical-bare-tag guard (vault#XXX): strip any leading `#` so the
+  // `#`-decorated form a client may pass (the agent module stored
+  // `#agent/message/inbound` verbatim) lands on the same bare row everyone
+  // else queries. This is the single write chokepoint — createNote /
+  // updateNote / batch / MCP add-tags / REST / import / transcript all funnel
+  // through store.tagNote → here.
+  for (const raw of tags) {
+    const tag = stripTagHash(raw);
+    if (tag === "") continue;
     insertTag.run(tag);
     insertNoteTag.run(noteId, tag);
   }
@@ -1244,7 +1269,10 @@ export function tagNote(db: Database, noteId: string, tags: string[]): void {
 
 export function untagNote(db: Database, noteId: string, tags: string[]): void {
   const stmt = db.prepare("DELETE FROM note_tags WHERE note_id = ? AND tag_name = ?");
-  for (const tag of tags) {
+  // Mirror tagNote's normalization so removing `#tag` deletes the bare row.
+  for (const raw of tags) {
+    const tag = stripTagHash(raw);
+    if (tag === "") continue;
     stmt.run(noteId, tag);
   }
 }
@@ -1359,6 +1387,11 @@ export type RenameTagResult =
  * after the cascade returns.
  */
 export function renameTag(db: Database, oldName: string, newName: string): RenameTagResult {
+  // Normalize the TARGET so a rename can never create a `#`-prefixed tag. The
+  // SOURCE (`oldName`) is left LITERAL on purpose — it's the transitional escape
+  // hatch that lets the `#legacy/*` → `legacy/*` data migration find the
+  // `#`-prefixed rows. (Renaming TO a `#`-name is the thing we're preventing.)
+  newName = stripTagHash(newName);
   if (oldName === newName) {
     const exists = db.prepare("SELECT 1 FROM tags WHERE name = ?").get(oldName);
     return exists
@@ -1727,6 +1760,9 @@ export function mergeTags(
   sources: string[],
   target: string,
 ): { merged: Record<string, number>; target: string } {
+  // Normalize the TARGET so a merge can never create a `#`-prefixed tag. SOURCES
+  // stay LITERAL so `#legacy/*` rows can be merged away (same carve-out as rename).
+  target = stripTagHash(target);
   // Dedup + drop target-in-sources (self-merge is a no-op).
   const uniqueSources = Array.from(new Set(sources)).filter((s) => s !== target);
 
@@ -1991,15 +2027,18 @@ export function createNotes(db: Database, inputs: BulkNoteInput[]): Note[] {
 export function batchTag(db: Database, noteIds: string[], tags: string[]): number {
   const insertTag = db.prepare("INSERT OR IGNORE INTO tags (name) VALUES (?)");
   const insertNoteTag = db.prepare("INSERT OR IGNORE INTO note_tags (note_id, tag_name) VALUES (?, ?)");
+  // Canonical-bare-tag guard (vault#XXX) — batchTag has its own SQL (does NOT
+  // funnel through tagNote), so it strips leading `#` independently.
+  const bareTags = tags.map(stripTagHash).filter((t) => t !== "");
   let count = 0;
 
   db.exec("BEGIN");
   try {
-    for (const tag of tags) {
+    for (const tag of bareTags) {
       insertTag.run(tag);
     }
     for (const noteId of noteIds) {
-      for (const tag of tags) {
+      for (const tag of bareTags) {
         insertNoteTag.run(noteId, tag);
         count++;
       }
@@ -2015,12 +2054,15 @@ export function batchTag(db: Database, noteIds: string[], tags: string[]): numbe
 
 export function batchUntag(db: Database, noteIds: string[], tags: string[]): number {
   const stmt = db.prepare("DELETE FROM note_tags WHERE note_id = ? AND tag_name = ?");
+  // Mirror batchTag's bare-tag normalization so removing `#tag` deletes the
+  // bare row.
+  const bareTags = tags.map(stripTagHash).filter((t) => t !== "");
   let count = 0;
 
   db.exec("BEGIN");
   try {
     for (const noteId of noteIds) {
-      for (const tag of tags) {
+      for (const tag of bareTags) {
         stmt.run(noteId, tag);
         count++;
       }

package/core/src/store.ts

@@ -16,6 +16,7 @@ import { HookRegistry } from "./hooks.js";
 import {
   loadTagHierarchy,
   getTagExpansion,
+  stripTagHash,
   TAG_CONFIG_PREFIX,
   DEFAULT_TAG_NAME,
   DEFAULT_TAG_EXPAND_MODE,
@@ -28,6 +29,10 @@ import {
   type ResolvedSchemas,
   type ValidationStatus,
 } from "./schema-defaults.js";
+import {
+  countConformanceViolations,
+  type ConformanceReport,
+} from "./conformance.js";
 
 /**
  * bun:sqlite-backed Store implementation. Internally everything is
@@ -247,8 +252,30 @@ export class BunSqliteStore implements Store {
     );
   }
 
+  /**
+   * Canonical-bare-tag guard (vault#XXX) for the QUERY path. Strip any leading
+   * `#` from `tags` / `excludeTags` BEFORE hierarchy expansion so a
+   * `#agent/message`-form query matches a bare-stored `agent/message` row (and
+   * vice-versa). This is what makes the data migration non-breaking — every
+   * old `#`-decorated query keeps working, mapping onto the same bare rows.
+   * Runs before `expandQueryTags` so hierarchy resolution / `_default` collapse
+   * see the bare names. Empty-after-strip entries are dropped.
+   */
+  private normalizeQueryTags(opts: QueryOpts): QueryOpts {
+    let next = opts;
+    if (opts.tags && opts.tags.length > 0) {
+      const tags = opts.tags.map(stripTagHash).filter((t) => t !== "");
+      next = { ...next, tags };
+    }
+    if (opts.excludeTags && opts.excludeTags.length > 0) {
+      const excludeTags = opts.excludeTags.map(stripTagHash).filter((t) => t !== "");
+      next = { ...next, excludeTags };
+    }
+    return next;
+  }
+
   async queryNotes(opts: QueryOpts): Promise<Note[]> {
-    return noteOps.queryNotes(this.db, this.expandQueryTags(opts));
+    return noteOps.queryNotes(this.db, this.expandQueryTags(this.normalizeQueryTags(opts)));
   }
 
   async queryNotesPaged(opts: QueryOpts): Promise<QueryNotesPage> {
@@ -258,7 +285,11 @@ export class BunSqliteStore implements Store {
     // descendant set → different rows match → caller should restart). The
     // alternative — hash the expanded set — would silently keep returning
     // stale results from a hierarchy snapshot the caller never saw.
-    return noteOps.queryNotesPaged(this.db, this.expandQueryTags(opts));
+    //
+    // Bare-tag normalization runs first (before the hash is taken inside
+    // queryNotesPaged) so a `#tag`-form page-1 and a bare `tag`-form follow-up
+    // resolve to the same cursor query_hash.
+    return noteOps.queryNotesPaged(this.db, this.expandQueryTags(this.normalizeQueryTags(opts)));
   }
 
   /**
@@ -328,6 +359,11 @@ export class BunSqliteStore implements Store {
   }
 
   async searchNotes(query: string, opts?: { tags?: string[]; limit?: number; expand?: TagExpandMode }): Promise<Note[]> {
+    // Canonical-bare-tag guard (vault#XXX): strip leading `#` from search tag
+    // filters before expansion, so `#manual` and `manual` resolve identically.
+    if (opts?.tags && opts.tags.length > 0) {
+      opts = { ...opts, tags: opts.tags.map(stripTagHash).filter((t) => t !== "") };
+    }
     // Same tag-expansion treatment as queryNotes, along the SAME `expand` axis
     // (vault tag `expand` axis) — searching `#manual` should match notes
     // tagged with any descendant under "subtypes", any `manual/*` under
@@ -626,6 +662,18 @@ export class BunSqliteStore implements Store {
       parent_names?: string[] | null;
     },
   ) {
+    // Canonical-bare-tag guard (vault#XXX) for the SCHEMA path. Strip leading
+    // `#` from the tag NAME being upserted and from every `parent_names` entry,
+    // so the `tags` rows and the inheritance graph stay bare — matching the
+    // bare-stored note_tags. A `#foo` schema with `parent_names: ["#bar"]`
+    // becomes `foo` / `["bar"]`, so `tag:bar` still expands to `foo`.
+    tag = stripTagHash(tag);
+    if (patch.parent_names != null) {
+      patch = {
+        ...patch,
+        parent_names: patch.parent_names.map(stripTagHash).filter((p) => p !== ""),
+      };
+    }
     // Snapshot the prior indexed-field set BEFORE the write so the diff below
     // sees what this tag declared going in. Only needed when `fields` changes.
     const priorRecord =
@@ -716,6 +764,21 @@ export class BunSqliteStore implements Store {
     return result;
   }
 
+  /**
+   * Conformance check (vault#283) — count how many EXISTING notes carrying
+   * `tag` (descendants included) would violate the PROPOSED field spec, so a
+   * tightening edit (strict / required / narrowed enum / changed type) can
+   * warn the operator BEFORE save. Pure read — no mutation. See
+   * core/src/conformance.ts.
+   */
+  async countTagConformance(
+    tag: string,
+    proposedFields: Record<string, tagSchemaOps.TagFieldSchema>,
+    opts?: { sampleLimit?: number },
+  ): Promise<ConformanceReport> {
+    return countConformanceViolations(this.db, tag, proposedFields, opts);
+  }
+
   // ---- Batch Wikilink Sync ----
 
   /**

package/core/src/tag-hierarchy.ts

@@ -27,6 +27,32 @@
 
 import { Database } from "bun:sqlite";
 
+/**
+ * Canonical-bare-tag guard (vault#XXX). Strip any leading `#` (one or more)
+ * from a tag value so a `#`-prefixed tag can never be stored or queried
+ * out-of-band. Tags are stored BARE by convention (`agent/message/inbound`,
+ * not `#agent/message/inbound`); a client that passes the `#`-decorated form —
+ * as the agent module did, persisting `#agent/message/inbound` literally — must
+ * land on the same canonical row everyone else queries.
+ *
+ * Deliberately MINIMAL: this is NOT `normalizeTagValue` (portable-md.ts). It
+ * does NOT lowercase, slug-validate, or otherwise transform the value — casing
+ * and structure are preserved. The ONLY job is to remove the stray leading `#`.
+ *
+ * Idempotent: `#tag` / `##tag` / `tag` all collapse to `tag`. Only LEADING `#`
+ * is stripped — a `#` mid-string (e.g. `c#`) is left intact. Whitespace is
+ * trimmed first so a `" #tag"` from a sloppy client also normalizes. Applied at
+ * the canonical chokepoints (note-tag write, query/exclude filters, tag-schema
+ * name + parent_names) so MCP, REST, and direct-core callers all converge.
+ */
+export function stripTagHash(tag: string): string {
+  // Strip any LEADING run of `#`/whitespace (handles `#tag`, `##tag`, `  #tag`,
+  // and `# tag` with a space after the hash), then trim the tail. A `#`
+  // mid-string (`c#`) is untouched; a degenerate `# #` collapses to "" (the
+  // write-path empty-tag gate drops it).
+  return tag.replace(/^[#\s]+/, "").trim();
+}
+
 export interface TagHierarchy {
   /** tag → set of immediate child tags (those that declared `tag` as a parent). */
   childrenOf: Map<string, Set<string>>;

package/core/src/types.ts

@@ -3,12 +3,14 @@ import type { TagFieldSchema, TagRelationship, TagRelationshipMap, TagRecord } f
 import type { PrunedField } from "./indexed-fields.js";
 import type { TagExpandMode } from "./tag-hierarchy.js";
 import type { ValidationStatus } from "./schema-defaults.js";
+import type { ConformanceReport } from "./conformance.js";
 
 // ---- Re-exports ----
 
 export type { TagFieldSchema, TagRelationship, TagRelationshipMap, TagRecord } from "./tag-schemas.js";
 export type { PrunedField } from "./indexed-fields.js";
 export type { TagExpandMode } from "./tag-hierarchy.js";
+export type { ConformanceReport } from "./conformance.js";
 
 // ---- Note ----
 
@@ -413,6 +415,19 @@ export interface Store {
     },
   ): Promise<TagRecord>;
 
+  /**
+   * Conformance check (vault#283) — count existing notes carrying `tag`
+   * (descendants included) that would violate the PROPOSED field spec, so a
+   * tightening edit (strict / required / narrowed enum / changed type) can
+   * warn before save. Pure read. `proposedFields` is the full merged field
+   * map the operator intends to save; only those fields are checked.
+   */
+  countTagConformance(
+    tag: string,
+    proposedFields: Record<string, TagFieldSchema>,
+    opts?: { sampleLimit?: number },
+  ): Promise<ConformanceReport>;
+
   // Schema validation (post-v17: backed by `tags.fields` only — the
   // standalone note_schemas + schema_mappings subsystem retired in v17, see
   // vault#267). Post vault#270 the resolver walks `parent_names` so a note's

package/package.json

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

package/src/bare-tag-guard-routes.test.ts

@@ -0,0 +1,72 @@
+/**
+ * Canonical-bare-tag guard (vault#XXX) — REST layer. Confirms the PUT
+ * /tags/:name route normalizes the upserted tag NAME (so the partial-merge read
+ * + write land on the bare row) and leaves the rename SOURCE-name lookup literal
+ * (the migration escape hatch — a #-prefixed legacy tag must still be
+ * rename-able away). The query + note-tag write paths normalize in the store and
+ * are covered by core/src/bare-tag-guard.test.ts.
+ */
+
+import { describe, it, expect, beforeEach } from "bun:test";
+import { Database } from "bun:sqlite";
+import { SqliteStore } from "../core/src/store.ts";
+import { initSchema } from "../core/src/schema.ts";
+import { handleTags } from "./routes.ts";
+
+let store: SqliteStore;
+let db: Database;
+
+beforeEach(() => {
+  db = new Database(":memory:");
+  initSchema(db);
+  store = new SqliteStore(db);
+});
+
+function put(name: string, body: unknown): Promise<Response> {
+  const req = new Request(`http://localhost/api/tags/${encodeURIComponent(name)}`, {
+    method: "PUT",
+    body: JSON.stringify(body),
+  });
+  return handleTags(req, store, `/${encodeURIComponent(name)}`);
+}
+
+describe("PUT /tags/:name — bare-tag guard", () => {
+  it("PUT /tags/%23foo with parent_names [#bar] stores the bare row + bare parents", async () => {
+    const res = await put("#foo", { parent_names: ["#bar"], description: "child" });
+    expect(res.status).toBe(200);
+
+    const record = await store.getTagRecord("foo");
+    expect(record).not.toBeNull();
+    expect(record!.parent_names).toEqual(["bar"]);
+    expect(await store.getTagRecord("#foo")).toBeNull();
+  });
+
+  it("a #-decorated PUT preserves the existing bare record's fields (merge correctness)", async () => {
+    await put("thing", { description: "first" });
+    await put("#thing", { parent_names: [] });
+    const record = await store.getTagRecord("thing");
+    expect(record!.description).toBe("first");
+  });
+});
+
+describe("POST /tags/:name/rename — source name stays literal", () => {
+  it("rename #agent/message → agent/message finds the literal #-prefixed row", async () => {
+    db.prepare("INSERT OR IGNORE INTO tags (name) VALUES ('#agent/message')").run();
+    const note = await store.createNote("legacy inbound");
+    db.prepare("INSERT INTO note_tags (note_id, tag_name) VALUES (?, '#agent/message')").run(note.id);
+
+    const sub = "/" + encodeURIComponent("#agent/message") + "/rename";
+    const req = new Request(`http://localhost/api/tags${sub}`, {
+      method: "POST",
+      body: JSON.stringify({ new_name: "agent/message" }),
+    });
+    const res = await handleTags(req, store, sub);
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { renamed?: number };
+    expect(body.renamed).toBeGreaterThan(0);
+
+    const tags = await store.listTags();
+    expect(tags.map((t) => t.name)).not.toContain("#agent/message");
+    expect(tags.map((t) => t.name)).toContain("agent/message");
+  });
+});

package/src/cli.ts

@@ -1664,7 +1664,7 @@ function cmdRemove(args: string[]) {
     configDirty = true;
     console.log(
       `  Last vault removed — wrote auto_create: false to ${GLOBAL_CONFIG_PATH} so the` +
-        ` server won't auto-recreate "default" on next boot. Create a vault with:` +
+        ` server won't auto-create a first vault on next boot. Create one with:` +
         ` parachute-vault create <name>`,
     );
   }

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);
+  });
+});