@openparachute/vault 0.6.3 → 0.6.4-rc.10

package/src/routing.test.ts

@@ -1262,12 +1262,17 @@ describe("/.parachute/config/schema + /.parachute/config", () => {
     expect(body.type).toBe("object");
     expect(body.properties.audio_retention?.type).toBe("string");
     expect(body.properties.audio_retention?.enum).toEqual(["keep", "until_transcribed", "never"]);
-    expect(body.properties.scribe_url?.type).toBe("string");
-    expect(body.properties.scribe_token?.writeOnly).toBe(true);
-    expect(body.properties.port?.readOnly).toBe(true);
+    expect(body.properties.autoTranscribe?.type).toBe("object");
+    // vault#478 scope boundary: daemon-GLOBAL fields are NOT described by the
+    // per-vault admin config schema. The per-vault admin surface is "admin
+    // over *your* vault only" — port / scribe URL / scribe bearer are
+    // deployment-wide and live behind the operator-only surface.
+    expect(body.properties).not.toHaveProperty("scribe_url");
+    expect(body.properties).not.toHaveProperty("scribe_token");
+    expect(body.properties).not.toHaveProperty("port");
   });
 
-  test("config returns current values with writeOnly fields excluded", async () => {
+  test("config returns ONLY per-vault values, never daemon-global ones (scope boundary, vault#478)", async () => {
     createVault("journal");
     const token = await createAdminToken("journal");
     const path = "/vault/journal/.parachute/config";
@@ -1284,13 +1289,22 @@ describe("/.parachute/config/schema + /.parachute/config", () => {
       );
       expect(res.status).toBe(200);
       const body = (await res.json()) as Record<string, unknown>;
+      // Per-vault config is present.
       expect(body.audio_retention).toBe("keep"); // default when unset
-      expect(body.scribe_url).toBe("https://scribe.example/v1");
-      expect(body.port).toBe(1940);
+      expect(body).toHaveProperty("autoTranscribe");
+      // Daemon-GLOBAL values must NOT cross the per-vault admin boundary.
+      expect(body).not.toHaveProperty("port");
+      expect(body).not.toHaveProperty("scribe_url");
+      // The discovery-resolved scribe URL is daemon-global → must not leak,
+      // even nested under autoTranscribe.
+      const at = body.autoTranscribe as Record<string, unknown>;
+      expect(at).not.toHaveProperty("scribeUrl");
       // writeOnly field must not appear in GET.
       expect(body).not.toHaveProperty("scribe_token");
-      // Defense in depth: grep the raw body for the token value.
-      expect(JSON.stringify(body)).not.toContain("super-secret-should-never-appear");
+      // Defense in depth: no daemon-global value (URL or secret) anywhere.
+      const raw = JSON.stringify(body);
+      expect(raw).not.toContain("super-secret-should-never-appear");
+      expect(raw).not.toContain("https://scribe.example/v1");
     } finally {
       if (origScribeToken === undefined) delete process.env.SCRIBE_TOKEN;
       else process.env.SCRIBE_TOKEN = origScribeToken;
@@ -1318,24 +1332,27 @@ describe("/.parachute/config/schema + /.parachute/config", () => {
     expect(body.audio_retention).toBe("until_transcribed");
   });
 
-  test("config scribe_url falls back to empty string when SCRIBE_URL env is unset", async () => {
-    createVault("journal");
+  test("autoTranscribe.enabled reports the per-vault override (vault#478)", async () => {
+    // Server default ON; this vault explicitly opts OUT — the per-vault value
+    // must win, proving the field is reported per-vault (not the raw global).
+    writeGlobalConfig({ port: 1940, auto_transcribe: { enabled: true } });
+    writeVaultConfig({
+      name: "journal",
+      api_keys: [],
+      created_at: new Date().toISOString(),
+      auto_transcribe: { enabled: false },
+    });
     const token = await createAdminToken("journal");
-    const orig = process.env.SCRIBE_URL;
-    delete process.env.SCRIBE_URL;
-    try {
-      const path = "/vault/journal/.parachute/config";
-      const res = await route(
-        new Request(`http://localhost:1940${path}`, {
-          headers: { authorization: `Bearer ${token}` },
-        }),
-        path,
-      );
-      const body = (await res.json()) as { scribe_url: string };
-      expect(body.scribe_url).toBe("");
-    } finally {
-      if (orig !== undefined) process.env.SCRIBE_URL = orig;
-    }
+    const path = "/vault/journal/.parachute/config";
+    const res = await route(
+      new Request(`http://localhost:1940${path}`, {
+        headers: { authorization: `Bearer ${token}` },
+      }),
+      path,
+    );
+    const body = (await res.json()) as { autoTranscribe: { enabled: boolean } };
+    expect(body.autoTranscribe.enabled).toBe(false);
+    writeGlobalConfig({ port: 1940 });
   });
 
   test("unknown vault returns 404 before reaching the config handlers", async () => {
@@ -2249,6 +2266,79 @@ describe("/vault/<name>/.parachute/mirror/run-now — auth + dispatch", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// /vault/<name>/.parachute/mirror/history — surface the git write history
+// (vault#300). Admin-gated (ops/forensics surface). Tests pin the auth gate
+// matches the sibling mirror routes; helper + handler shape lives in
+// mirror-history.test.ts.
+// ---------------------------------------------------------------------------
+
+describe("/vault/<name>/.parachute/mirror/history — auth + dispatch", () => {
+  test("unauthenticated → 401", async () => {
+    createVault("journal");
+    const p = "/vault/journal/.parachute/mirror/history";
+    const res = await route(new Request(`http://localhost:1940${p}`), p);
+    expect(res.status).toBe(401);
+  });
+
+  test("vault:read token → 403 insufficient_scope (admin required)", async () => {
+    createVault("journal");
+    const fullToken = await mintJwt({ vaultName: "journal", scopes: ["vault:journal:read"] });
+    const p = "/vault/journal/.parachute/mirror/history";
+    const res = await route(
+      new Request(`http://localhost:1940${p}`, {
+        headers: { authorization: `Bearer ${fullToken}` },
+      }),
+      p,
+    );
+    expect(res.status).toBe(403);
+    const body = (await res.json()) as { error_type?: string; required_scope?: string };
+    expect(body.error_type).toBe("insufficient_scope");
+    expect(body.required_scope).toBe("vault:admin");
+  });
+
+  test("admin token reaches the handler (200 when wired, 503 when not)", async () => {
+    createVault("journal");
+    const token = await createAdminToken("journal");
+    const p = "/vault/journal/.parachute/mirror/history";
+    const res = await route(
+      new Request(`http://localhost:1940${p}`, {
+        headers: { authorization: `Bearer ${token}` },
+      }),
+      p,
+    );
+    // Either way the auth gate passed — that's what this routing-level test pins.
+    expect([200, 503]).toContain(res.status);
+  });
+
+  test("/history/show admin gate matches /history", async () => {
+    createVault("journal");
+    const fullToken = await mintJwt({ vaultName: "journal", scopes: ["vault:journal:read"] });
+    const p = "/vault/journal/.parachute/mirror/history/show";
+    const res = await route(
+      new Request(`http://localhost:1940${p}?sha=abc123&path=Notes/a`, {
+        headers: { authorization: `Bearer ${fullToken}` },
+      }),
+      p,
+    );
+    expect(res.status).toBe(403);
+  });
+
+  test("non-GET method → 405 (or 503 when manager not wired)", async () => {
+    createVault("journal");
+    const token = await createAdminToken("journal");
+    const p = "/vault/journal/.parachute/mirror/history";
+    const res = await route(
+      new Request(`http://localhost:1940${p}`, {
+        method: "POST",
+        headers: { authorization: `Bearer ${token}` },
+      }),
+      p,
+    );
+    expect([405, 503]).toContain(res.status);
+  });
+});
+
 // ---------------------------------------------------------------------------
 // /vault/<name>/.parachute/usage — per-vault data-footprint endpoint.
 //

package/src/routing.ts

@@ -52,7 +52,7 @@ import {
   authenticateGlobalRequest,
   extractApiKey,
 } from "./auth.ts";
-import { hasScopeForVault, SCOPE_ADMIN, SCOPE_READ, scopeForMethod, verbForMethod } from "./scopes.ts";
+import { hasScopeForVault, hasMigrateScopeForVault, SCOPE_ADMIN, SCOPE_READ, scopeForMethod, verbForMethod } from "./scopes.ts";
 import { getVaultStore } from "./vault-store.ts";
 import { handleScopedMcp } from "./mcp-http.ts";
 import {
@@ -71,6 +71,7 @@ import {
   handleStorage,
   handleViewNote,
   type TagScopeCtx,
+  type WriteCtx,
 } from "./routes.ts";
 import { handleSubscribe } from "./subscribe.ts";
 import { handleTriggers } from "./triggers-api.ts";
@@ -93,6 +94,8 @@ import {
   handleAuthGithubSelectRepo,
   handleAuthPat,
   handleMirrorGet,
+  handleMirrorHistory,
+  handleMirrorHistoryShow,
   handleMirrorImport,
   handleMirrorPushNow,
   handleMirrorPut,
@@ -670,6 +673,50 @@ export async function route(
     return Response.json({ error: "Method not allowed" }, { status: 405 });
   }
 
+  // /.parachute/mirror/history — surface the mirror's git commit history
+  // (vault#300). The vault is already git-backed (one file per note), so
+  // `git log` IS a tamper-evident write history; this read path exposes it.
+  // Admin-gated (it's an ops/forensics surface, not a content read) — same
+  // gate + manager check as the sibling mirror routes. GET-only.
+  //   /history       — full mirror history (?path=<note> scopes to one note,
+  //                    ?limit=<n> caps the count)
+  //   /history/show  — `git show <sha>:<path>.md` to read a past revision
+  if (
+    subpath === "/.parachute/mirror/history" ||
+    subpath === "/.parachute/mirror/history/show"
+  ) {
+    if (!hasScopeForVault(auth.scopes, vaultName, "admin")) {
+      return Response.json(
+        {
+          error: "Forbidden",
+          error_type: "insufficient_scope",
+          message: `This endpoint requires the '${SCOPE_ADMIN}' scope (or '${SCOPE_ADMIN.replace("vault:", `vault:${vaultName}:`)}').`,
+          required_scope: SCOPE_ADMIN,
+          granted_scopes: auth.scopes,
+        },
+        { status: 403 },
+      );
+    }
+    const manager = getMirrorManager(vaultName);
+    if (!manager) {
+      return Response.json(
+        {
+          error: "Mirror manager not initialized",
+          message:
+            "The vault server hasn't wired the mirror manager registry yet (boot hasn't finished, or it failed). Check logs for [mirror] entries.",
+        },
+        { status: 503 },
+      );
+    }
+    if (req.method !== "GET") {
+      return Response.json({ error: "Method not allowed" }, { status: 405 });
+    }
+    if (subpath === "/.parachute/mirror/history/show") {
+      return handleMirrorHistoryShow(req, manager);
+    }
+    return handleMirrorHistory(req, manager);
+  }
+
   // /.parachute/mirror/import — clone a vault export from git + import.
   // Admin-gated. POST-only. Synchronous (imports finish in <30s for
   // typical vaults). See mirror-routes.ts:handleMirrorImport for the
@@ -812,7 +859,22 @@ export async function route(
     raw: auth.scoped_tags,
   };
 
-  if (apiPath.startsWith("/notes")) return handleNotes(req, store, apiPath.slice(6), vaultName, tagScope);
+  // Write-attribution context (vault#298). `auth.actor` is the principal;
+  // `auth.via` is the credential class (`api` for hub JWTs + legacy keys,
+  // `operator` for the env-var bearer). The REST surface IS the `api` channel,
+  // so no refinement is needed here — the base via stands (the MCP handler is
+  // the one that refines to `mcp`). Threaded only into the write handler.
+  // Migration-bypass (vault#299): a `vault:migrate`-scoped caller may write
+  // notes that violate `strict:true` field constraints (for backfill /
+  // migration). Every bypassed write is logged. Orthogonal to read/write/admin
+  // — an admin token does NOT bypass unless it also holds `migrate`.
+  const writeCtx: WriteCtx = {
+    actor: auth.actor,
+    via: auth.via,
+    bypassStrict: hasMigrateScopeForVault(auth.scopes, vaultName),
+  };
+
+  if (apiPath.startsWith("/notes")) return handleNotes(req, store, apiPath.slice(6), vaultName, tagScope, writeCtx);
   // Live-query SSE subscription (design 2026-06-08). Snapshot + scoped live
   // upsert/remove events over text/event-stream. Auth + tag-scope already
   // resolved above and threaded through, mirroring the /notes branch.

package/src/scale.bench.test.ts

@@ -0,0 +1,82 @@
+/**
+ * Opt-in scale smoke (vault#325 Part 3).
+ *
+ * Guards the synthetic scale harness against bit-rot WITHOUT slowing the
+ * default `bun test` gate. The real benchmark lives in
+ * `scripts/scale-bench.ts` (10k / 50k / 100k); this is a fast, tiny-size
+ * functional smoke of the same hot-path code so a green CI run still
+ * proves the harness paths execute end-to-end.
+ *
+ * SKIPPED BY DEFAULT. To run it:
+ *
+ *   VAULT_SCALE_BENCH=1 bun test ./src/scale.bench.test.ts
+ *
+ * For real timings + the documented ceiling, run the standalone harness:
+ *
+ *   bun scripts/scale-bench.ts          # 10000 50000 100000
+ *
+ * See docs/SCALE.md.
+ */
+
+import { describe, test, expect } from "bun:test";
+import { Database } from "bun:sqlite";
+import { BunSqliteStore } from "../core/src/store.ts";
+import { generateMcpTools } from "../core/src/mcp.ts";
+import { exportVaultToDir } from "../core/src/portable-md.ts";
+import type { BulkNoteInput } from "../core/src/notes.ts";
+import { mkdtempSync, rmSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+
+const ENABLED = process.env.VAULT_SCALE_BENCH === "1";
+
+// `describe.skipIf` keeps the suite registered (so it shows in the test list)
+// but contributes zero runtime to the default gate. Size is intentionally
+// tiny — this is a functional smoke, not a timing run.
+describe.skipIf(!ENABLED)("scale harness smoke (opt-in: VAULT_SCALE_BENCH=1)", () => {
+  test("seed + hot-path queries + export run at small N", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "vault-scale-smoke-"));
+    const db = new Database(join(dir, "smoke.db"));
+    const store = new BunSqliteStore(db);
+    try {
+      const N = 500;
+
+      // Declare the indexed field via the update-tag tool (the owner of the
+      // indexed_fields lifecycle — mirrors scripts/scale-bench.ts).
+      const tools = generateMcpTools(store);
+      const updateTag = tools.find((t) => t.name === "update-tag");
+      expect(updateTag).toBeDefined();
+      await updateTag!.execute({
+        tag: "work",
+        fields: { status: { type: "string", indexed: true } },
+      });
+
+      const inputs: BulkNoteInput[] = Array.from({ length: N }, (_, i) => ({
+        id: `note-${i}`,
+        path: `notes/note-${i}`,
+        content: `# Note ${i}\n\nconsectetur body ${i}`,
+        tags: i % 3 === 0 ? ["work", "work/meeting"] : ["health"],
+        metadata: { status: i % 2 === 0 ? "active" : "done", seq: i },
+      }));
+      await store.createNotes(inputs);
+
+      // Hot paths — same shapes the standalone harness times.
+      expect((await store.queryNotes({ tags: ["health"], limit: 50 })).length).toBeGreaterThan(0);
+      expect(
+        (await store.queryNotes({ metadata: { status: { eq: "active" } }, limit: 50 })).length,
+      ).toBeGreaterThan(0);
+      expect((await store.queryNotes({ orderBy: "status", limit: 50 })).length).toBe(50);
+      expect((await store.searchNotes("consectetur", { limit: 50 })).length).toBeGreaterThan(0);
+
+      const stats = await exportVaultToDir(store, {
+        outDir: join(dir, "export"),
+        vaultName: "smoke",
+        exportedAt: "2026-01-01T00:00:00Z",
+      });
+      expect(stats.notes).toBe(N);
+    } finally {
+      db.close();
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});

package/src/scopes.test.ts

@@ -9,10 +9,12 @@ import {
   SCOPE_READ,
   SCOPE_WRITE,
   SCOPE_ADMIN,
+  SCOPE_MIGRATE,
   parseScopes,
   parseScopeFlags,
   hasScope,
   hasScopeForVault,
+  hasMigrateScopeForVault,
   findBroadVaultScopes,
   scopeForMethod,
   verbForMethod,
@@ -20,6 +22,28 @@ import {
   serializeScopes,
 } from "./scopes.ts";
 
+describe("hasMigrateScopeForVault — migration-bypass capability (vault#299)", () => {
+  test("broad vault:migrate satisfies any vault", () => {
+    expect(hasMigrateScopeForVault([SCOPE_MIGRATE], "default")).toBe(true);
+    expect(hasMigrateScopeForVault([SCOPE_MIGRATE], "anything")).toBe(true);
+  });
+
+  test("narrowed vault:<name>:migrate satisfies only that vault", () => {
+    expect(hasMigrateScopeForVault(["vault:gitcoin:migrate"], "gitcoin")).toBe(true);
+    expect(hasMigrateScopeForVault(["vault:gitcoin:migrate"], "default")).toBe(false);
+  });
+
+  test("admin does NOT imply migrate — orthogonal axis", () => {
+    expect(hasMigrateScopeForVault([SCOPE_ADMIN], "default")).toBe(false);
+    expect(hasMigrateScopeForVault(["vault:default:admin"], "default")).toBe(false);
+  });
+
+  test("no migrate scope → false", () => {
+    expect(hasMigrateScopeForVault([SCOPE_WRITE, SCOPE_READ], "default")).toBe(false);
+    expect(hasMigrateScopeForVault([], "default")).toBe(false);
+  });
+});
+
 describe("parseScopes", () => {
   test("returns [] for null or empty input", () => {
     expect(parseScopes(null)).toEqual([]);

package/src/scopes.ts

@@ -28,6 +28,19 @@ export const SCOPE_READ = "vault:read" as const;
 export const SCOPE_WRITE = "vault:write" as const;
 export const SCOPE_ADMIN = "vault:admin" as const;
 
+/**
+ * Migration-bypass scope (vault#299). A SEPARATE capability axis — NOT part
+ * of the read ⊇ write ⊇ admin inheritance chain. A token holding
+ * `vault:migrate` (broad) or `vault:<name>:migrate` (narrowed) may skip
+ * `strict:true` schema enforcement so existing non-conforming notes can be
+ * migrated/backfilled. It is deliberately orthogonal: an `admin` token does
+ * NOT auto-bypass strict validation — bypass must be an explicit, audited
+ * grant. A bypass write still needs `write` to actually mutate (migrate is an
+ * ADD-ON flag, not a write grant on its own). Every bypassed write is logged
+ * (see the write path) since #300 (the audit-log table) is deferred.
+ */
+export const SCOPE_MIGRATE = "vault:migrate" as const;
+
 /** All first-class vault scopes in inheritance order (lowest → highest). */
 export const VAULT_SCOPES = [SCOPE_READ, SCOPE_WRITE, SCOPE_ADMIN] as const;
 export type VaultScope = (typeof VAULT_SCOPES)[number];
@@ -137,6 +150,56 @@ export function hasScopeForVault(
   return false;
 }
 
+/**
+ * Migration-bypass check (vault#299): does `granted` hold the `migrate`
+ * capability for `vaultName`? Accepts broad `vault:migrate` (any vault) or
+ * narrowed `vault:<name>:migrate` (this vault only). Orthogonal to the
+ * read/write/admin verbs — a plain admin token returns `false` here, by
+ * design. The migrate scope does NOT live in `decomposeVaultScope` (it isn't a
+ * read/write/admin verb), so it's matched by exact shape here.
+ */
+export function hasMigrateScopeForVault(granted: string[], vaultName: string): boolean {
+  for (const s of granted) {
+    if (s === SCOPE_MIGRATE) return true; // broad — any vault
+    if (s === `vault:${vaultName}:migrate`) return true; // narrowed — this vault
+  }
+  return false;
+}
+
+/**
+ * Structured log line for a migration-bypassed write (vault#299 settled lead
+ * #2). Records WHO bypassed (actor/via from MW1 attribution), WHAT note, and
+ * WHICH strict violations were waived — enough to reconstruct the bypass for
+ * later audit without the #300 audit-log table (deferred). One JSON line so
+ * it's grep/jq-able in the daemon log. Lives here (next to the migrate-scope
+ * check) so both write transports — REST (routes.ts) and MCP (mcp-tools.ts) —
+ * emit the identical line without importing each other.
+ */
+export function logStrictBypass(info: {
+  actor: string | null;
+  via: string | null;
+  path?: string | null;
+  tags?: string[];
+  violations: { field: string; reason: string; schema: string }[];
+}): void {
+  console.warn(
+    "[schema-bypass] " +
+      JSON.stringify({
+        event: "strict_schema_bypass",
+        actor: info.actor,
+        via: info.via,
+        path: info.path ?? null,
+        tags: info.tags ?? [],
+        violations: info.violations.map((v) => ({
+          field: v.field,
+          reason: v.reason,
+          schema: v.schema,
+        })),
+        at: new Date().toISOString(),
+      }),
+  );
+}
+
 /**
  * Pick the required scope for a given API request.
  *   - GET/HEAD/OPTIONS → read

package/src/self-register.test.ts

@@ -61,10 +61,8 @@ function captureLogs(): {
 }
 
 describe("self-register", () => {
-  test("buildVaultServicePaths — no vaults yet → manifest fallback", () => {
-    expect(buildVaultServicePaths(undefined, [], ["/vault/default"])).toEqual([
-      "/vault/default",
-    ]);
+  test("buildVaultServicePaths — no vaults yet → empty paths (no phantom /vault/default, #478)", () => {
+    expect(buildVaultServicePaths(undefined, [], ["/vault/default"])).toEqual([]);
   });
 
   test("buildVaultServicePaths — default vault sorts first", () => {
@@ -108,7 +106,9 @@ describe("self-register", () => {
       const row = parsed.services[0] as Record<string, unknown>;
       expect(row.name).toBe("parachute-vault");
       expect(row.port).toBe(1940);
-      expect(row.paths).toEqual(["/vault/default"]);
+      // Zero vaults → paths: [] (no phantom /vault/default, #478).
+      // Health still well-formed: paths[0] ?? "/vault/default" fallback.
+      expect(row.paths).toEqual([]);
       expect(row.health).toBe("/vault/default/health");
       expect(row.version).toBe("0.4.8-rc.3");
       expect(row.installDir).toBe("/fake/install/dir");

package/src/self-register.ts

@@ -56,8 +56,13 @@ import { listVaults, readGlobalConfig, DEFAULT_PORT } from "./config.ts";
  *
  * Mirrors `buildVaultServicePaths` in `cli.ts` so the self-register pass
  * produces the same multi-vault path advertisement as `parachute-vault
- * init` / `vault create`. With no vaults yet, falls back to the manifest's
- * canonical `paths[0]` so early-boot registration is still well-formed.
+ * init` / `vault create`.
+ *
+ * At zero vaults, returns an empty array (`paths: []`). The row remains
+ * present in services.json (name, port, health, version, installDir intact
+ * — so the module is still detected as installed), but it advertises no
+ * `/vault/<name>` path and the hub must not resolve it to a phantom
+ * `/vault/default`. Closes #478.
  *
  * Exported for tests; not part of the public module surface.
  */
@@ -66,7 +71,7 @@ export function buildVaultServicePaths(
   vaults: readonly string[],
   fallbackFromManifest: readonly string[],
 ): string[] {
-  if (vaults.length === 0) return [...fallbackFromManifest];
+  if (vaults.length === 0) return [];
   if (defaultVault && vaults.includes(defaultVault)) {
     return [
       `/vault/${defaultVault}`,

package/src/server.ts

@@ -153,17 +153,23 @@ if (process.env.VAULT_AUTH_TOKEN?.trim()) {
 // logic lives in auth.ts (import-safe + unit-tested); see warnLegacyGlobalApiKeys.
 warnLegacyGlobalApiKeys(readGlobalConfig().api_keys);
 
-// Auto-init: create a default vault if none exist (first run in Docker).
-// The vault name comes from PARACHUTE_VAULT_NAME when set + valid; otherwise
-// falls back to "default". Hub's first-boot wizard (hub#267) passes through
-// an operator-chosen name via this env var.
+// First-boot vault creation — ONLY when PARACHUTE_VAULT_NAME is explicitly
+// set in the environment. (#478 Part 2)
+//
+// The hub setup wizard and `parachute init --vault-name <name>` both spawn
+// the vault server with PARACHUTE_VAULT_NAME=<operator-chosen-name>; that
+// env var is the load-bearing signal that an external orchestrator has
+// decided what the first vault should be called. With the env var unset the
+// server boots with zero vaults and stays that way — no silent "default"
+// — so a fresh install without a wizard can't accidentally squash an
+// explicit later `parachute-vault create <name>` call.
 //
 // Gated on the `auto_create: false` marker (2026-06-09 hub-module-boundary
 // migration): `parachute-vault remove` writes it when the operator deletes
 // their LAST vault, so an explicit empty-the-server action isn't silently
 // undone by a resurrection with fresh credentials on the next boot. Fresh
-// installs have no config.yaml — no marker — so Docker first-run still
-// auto-creates.
+// installs have no config.yaml — no marker — so the env-var-driven path
+// still works on a clean box.
 if (listVaults().length === 0) {
   const globalConfig = readGlobalConfig();
   if (!bootAutoCreateAllowed(globalConfig)) {
@@ -173,43 +179,57 @@ if (listVaults().length === 0) {
   } else if (!globalConfig.default_vault) {
     const firstBoot = resolveFirstBootVaultName(process.env.PARACHUTE_VAULT_NAME);
     if (firstBoot.source === "env") {
-      console.log(`[vault first-boot] using PARACHUTE_VAULT_NAME=${firstBoot.name}`);
+      // PARACHUTE_VAULT_NAME explicitly set + valid — create the named vault.
+      console.log(`[vault first-boot] PARACHUTE_VAULT_NAME=${firstBoot.name} — creating vault`);
+      const vaultName = firstBoot.name;
+      const { fullKey, keyId } = generateApiKey();
+      writeVaultConfig({
+        name: vaultName,
+        api_keys: [{
+          id: keyId,
+          label: "default",
+          scope: "write",
+          key_hash: hashKey(fullKey),
+          created_at: new Date().toISOString(),
+        }],
+        created_at: new Date().toISOString(),
+      });
+      globalConfig.default_vault = vaultName;
+      if (!globalConfig.api_keys?.length) {
+        globalConfig.api_keys = [{
+          id: keyId,
+          label: "default",
+          scope: "write",
+          key_hash: hashKey(fullKey),
+          created_at: new Date().toISOString(),
+        }];
+      }
+      writeGlobalConfig(globalConfig);
+      console.log(`Auto-created vault "${vaultName}" (API key: ${fullKey})`);
+      // Seed the in-vault onboarding guide so a connected AI can self-orient and
+      // help set the vault up — same as the `create`/`init` CLI path. Idempotent
+      // + best-effort (never fails first boot). Mirrors createVault() in cli.ts.
+      await seedOnboardingNotesBestEffort(getVaultStore(vaultName));
     } else if (firstBoot.source === "env-invalid") {
+      // PARACHUTE_VAULT_NAME was set but failed validation — do NOT silently
+      // fall back to "default". Log the problem and stay empty so the operator
+      // sees the misconfiguration instead of a phantom vault.
       console.warn(
-        `[vault first-boot] PARACHUTE_VAULT_NAME=${JSON.stringify(firstBoot.rawValue)} is invalid (${firstBoot.reason}); falling back to "default"`,
+        `[vault first-boot] PARACHUTE_VAULT_NAME=${JSON.stringify(firstBoot.rawValue)} is invalid (${firstBoot.reason}) — server starting with zero vaults. Fix the env var, or create one via the admin wizard, parachute init --vault-name <name>, or parachute-vault create <name>.`,
       );
     } else {
-      console.log("[vault first-boot] using default name (no PARACHUTE_VAULT_NAME set)");
-    }
-    const vaultName = firstBoot.name;
-    const { fullKey, keyId } = generateApiKey();
-    writeVaultConfig({
-      name: vaultName,
-      api_keys: [{
-        id: keyId,
-        label: "default",
-        scope: "write",
-        key_hash: hashKey(fullKey),
-        created_at: new Date().toISOString(),
-      }],
-      created_at: new Date().toISOString(),
-    });
-    globalConfig.default_vault = vaultName;
-    if (!globalConfig.api_keys?.length) {
-      globalConfig.api_keys = [{
-        id: keyId,
-        label: "default",
-        scope: "write",
-        key_hash: hashKey(fullKey),
-        created_at: new Date().toISOString(),
-      }];
+      // PARACHUTE_VAULT_NAME unset — stay empty. No silent "default".
+      console.log(
+        '[vault first-boot] no vaults and PARACHUTE_VAULT_NAME unset — staying empty. Create one via the admin wizard, parachute init --vault-name <name>, or parachute-vault create <name>.',
+      );
     }
-    writeGlobalConfig(globalConfig);
-    console.log(`Auto-created vault "${vaultName}" (API key: ${fullKey})`);
-    // Seed the in-vault onboarding guide so a connected AI can self-orient and
-    // help set the vault up — same as the `create`/`init` CLI path. Idempotent
-    // + best-effort (never fails first boot). Mirrors createVault() in cli.ts.
-    await seedOnboardingNotesBestEffort(getVaultStore(vaultName));
+  } else {
+    // Stale config: default_vault is set but no vault DB exists on disk, so
+    // first-boot create is skipped. Without a log line the server would boot
+    // empty and silent here, which is confusing. (#478 Part 2)
+    console.warn(
+      '[vault first-boot] config.yaml has default_vault set but no vaults exist on disk — skipping first-boot create. Create one with: parachute-vault create <name>',
+    );
   }
 }