@openparachute/vault 0.6.0-rc.1 → 0.6.1

package/src/vault-create.test.ts

@@ -10,7 +10,15 @@
 
 import { describe, test, expect, beforeEach, afterEach } from "bun:test";
 import { resolve } from "path";
-import { mkdtempSync, rmSync, existsSync, readFileSync } from "fs";
+import {
+  mkdtempSync,
+  rmSync,
+  existsSync,
+  readFileSync,
+  mkdirSync,
+  writeFileSync,
+  symlinkSync,
+} from "fs";
 import { tmpdir } from "os";
 import { join } from "path";
 
@@ -20,11 +28,18 @@ function runCli(
   args: string[],
   env: Record<string, string>,
 ): { exitCode: number; stdout: string; stderr: string } {
+  // Hermetic: don't inherit the dev/CI box's PARACHUTE_HUB_ORIGIN. A leaked
+  // origin makes `detectHubPresence`'s rule-1 (configured-origin) short-circuit
+  // to "hub present" with no probe, flipping the no-hub guidance copy to the
+  // "admin wizard" variant — a CI flake when the runner env has it set. Tests
+  // that genuinely want a hub origin pass it explicitly via `env`.
+  const baseEnv: Record<string, string | undefined> = { ...process.env };
+  delete baseEnv.PARACHUTE_HUB_ORIGIN;
   const proc = Bun.spawnSync({
     cmd: ["bun", CLI, ...args],
     stdout: "pipe",
     stderr: "pipe",
-    env: { ...process.env, ...env },
+    env: { ...baseEnv, ...env },
   });
   return {
     exitCode: proc.exitCode ?? -1,
@@ -33,6 +48,23 @@ function runCli(
   };
 }
 
+/** Path to a vault's per-vault mirror-config file inside a temp PARACHUTE_HOME. */
+function mirrorConfigPath(home: string, name: string): string {
+  return join(home, "vault", "data", name, "mirror-config.yaml");
+}
+
+/** Path to a vault's internal mirror git working tree. */
+function mirrorRepoPath(home: string, name: string): string {
+  return join(home, "vault", "data", name, "mirror");
+}
+
+/** Write a minimal config.yaml carrying a `default_mirror` knob value. */
+function writeDefaultMirrorKnob(home: string, value: "internal" | "off"): void {
+  const dir = join(home, "vault");
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, "config.yaml"), `port: 1940\ndefault_mirror: ${value}\n`);
+}
+
 let home: string;
 
 beforeEach(() => {
@@ -60,13 +92,15 @@ describe("vault create --json", () => {
     expect(lines).toHaveLength(1);
     const payload = JSON.parse(lines[0]!);
     expect(payload.name).toBe("myvault");
-    // vault#282 Stage 2: vault no longer mints pvt_* tokens. The contract
-    // hub's admin-vaults.ts requires still holds (`token` is a string). In
-    // this sandbox there's no hub/operator.token, so no token is issued: the
-    // token field is the empty string and `token_guidance` explains why.
+    // vault#442: default auth is per-user OAuth — `create` does NOT mint a
+    // token. The contract hub's admin-vaults.ts requires still holds (`token`
+    // is a string); it's the empty string and `token_guidance` carries the
+    // OAuth-first connect path (the hub SPA handles the empty-token case and
+    // mints admin via its own session-cookie path).
     expect(typeof payload.token).toBe("string");
     expect(payload.token).toBe("");
-    expect(payload.token_guidance).toContain("No token issued");
+    expect(payload.token_guidance).toContain("No token minted");
+    expect(payload.token_guidance).toContain("per-user OAuth");
     expect(payload.set_as_default).toBe(true);
     expect(payload.paths.vault_dir).toBe(join(home, "vault", "data", "myvault"));
     expect(payload.paths.vault_db).toBe(join(home, "vault", "data", "myvault", "vault.db"));
@@ -107,7 +141,47 @@ describe("vault create --json", () => {
     );
     expect(exitCode).not.toBe(0);
     expect(stdout).toBe("");
-    expect(stderr).toContain("letters, numbers");
+    expect(stderr).toContain("lowercase alphanumeric");
+  });
+
+  test("UPPERCASE vault name is rejected (security review — audience case-drift)", () => {
+    // An uppercase name would flip the JWT audience case (vault.<Name> vs
+    // vault.<name>) and drift from hub/init lowercasing. cmdCreate must
+    // reject it the same way `init` does.
+    const { exitCode, stdout, stderr } = runCli(
+      ["create", "MyVault", "--json"],
+      { PARACHUTE_HOME: home },
+    );
+    expect(exitCode).not.toBe(0);
+    expect(stdout).toBe("");
+    expect(stderr).toContain("lowercase");
+  });
+
+  test("reserved names (list/new/assets/admin) are rejected at create", () => {
+    // Consolidated reserved set (2026-06-09 hub-module-boundary B2). Before
+    // the consolidation cmdCreate hardcoded only "list" — `admin` could enter
+    // through `create` and capture the daemon-level /vault/admin mount.
+    for (const reserved of ["list", "new", "assets", "admin"]) {
+      const { exitCode, stdout, stderr } = runCli(
+        ["create", reserved, "--json"],
+        { PARACHUTE_HOME: home },
+      );
+      expect(exitCode).not.toBe(0);
+      expect(stdout).toBe("");
+      expect(stderr).toContain("reserved");
+      // The vault must not have been created.
+      expect(existsSync(join(home, "vault", "data", reserved))).toBe(false);
+    }
+  });
+
+  test("near-misses of reserved names (adminx, admin2) create fine", () => {
+    for (const name of ["adminx", "admin2"]) {
+      const { exitCode, stdout } = runCli(["create", name, "--json"], {
+        PARACHUTE_HOME: home,
+      });
+      expect(exitCode).toBe(0);
+      expect(JSON.parse(stdout.trim()).name).toBe(name);
+    }
   });
 
   test("duplicate name in --json mode errors on stderr and exits non-zero", () => {
@@ -122,6 +196,102 @@ describe("vault create --json", () => {
   });
 });
 
+/**
+ * vault#442: default to per-user OAuth — `create` must NOT auto-mint or bake in
+ * a shared `vault:<name>:admin` token. Token-minting is explicit opt-in
+ * (`--mint`) and scope-narrow (read/write, NEVER admin); `--token <bearer>` is
+ * the paste path. These tests pin the behavioral contract.
+ */
+describe("vault create — OAuth-first auth (vault#442)", () => {
+  test("default create does NOT mint a token — empty token + OAuth guidance (--json)", () => {
+    const { exitCode, stdout } = runCli(["create", "oauthy", "--json"], {
+      PARACHUTE_HOME: home,
+    });
+    expect(exitCode).toBe(0);
+    const payload = JSON.parse(stdout.trim());
+    // No token baked in — OAuth on first connect.
+    expect(payload.token).toBe("");
+    expect(payload.token_guidance).toContain("No token minted");
+    expect(payload.token_guidance).toContain("per-user OAuth");
+    // Never the admin-mint failure copy.
+    expect(payload.token_guidance).not.toContain("No token issued");
+    expect(payload.token_guidance).not.toContain("admin");
+  });
+
+  test("default create leads the human summary with the OAuth connect command", () => {
+    const { exitCode, stdout } = runCli(["create", "connectme"], {
+      PARACHUTE_HOME: home,
+    });
+    expect(exitCode).toBe(0);
+    expect(stdout).toContain(
+      "Connect your AI: claude mcp add --transport http parachute-connectme",
+    );
+    expect(stdout).toContain("no token needed");
+    // Scope-narrow opt-in pointer, never admin.
+    expect(stdout).toContain("parachute auth mint-token --scope vault:connectme:read");
+    expect(stdout).not.toContain("vault:connectme:admin");
+  });
+
+  test("--scope admin is rejected from the create flow (admin never mintable here)", () => {
+    const { exitCode, stdout, stderr } = runCli(
+      ["create", "noadmin", "--mint", "--scope", "admin", "--json"],
+      { PARACHUTE_HOME: home },
+    );
+    expect(exitCode).not.toBe(0);
+    expect(stdout).toBe("");
+    expect(stderr).toContain('--scope must be "read" or "write"');
+    // The vault must not have been created (rejected before createVault).
+    expect(existsSync(join(home, "vault", "data", "noadmin", "vault.db"))).toBe(false);
+  });
+
+  test("--mint and --token are mutually exclusive", () => {
+    const { exitCode, stderr } = runCli(
+      ["create", "conflict", "--mint", "--token", "abc.def.ghi", "--json"],
+      { PARACHUTE_HOME: home },
+    );
+    expect(exitCode).not.toBe(0);
+    expect(stderr).toContain("mutually exclusive");
+  });
+
+  test("--token <bearer> paste path surfaces the supplied bearer (no mint attempted)", () => {
+    const { exitCode, stdout } = runCli(
+      ["create", "pasted", "--token", "header.auth.bearer", "--json"],
+      { PARACHUTE_HOME: home },
+    );
+    expect(exitCode).toBe(0);
+    const payload = JSON.parse(stdout.trim());
+    // The pasted bearer is surfaced verbatim — vault never minted one.
+    expect(payload.token).toBe("header.auth.bearer");
+    expect(payload.token_guidance).toContain("--token");
+    // No admin scope, no mint-failure copy.
+    expect(payload.token_guidance).not.toContain("No token issued");
+  });
+
+  test("--mint (no hub reachable) opts in but mints scope-narrow read, never admin", () => {
+    // In this sandbox there's no hub/operator.token, so the mint can't complete
+    // — but the request is scope-narrow read by default and must NEVER ask for
+    // an admin grant. We assert the create still succeeds and the guidance is
+    // the standalone path (the scope requested is read, per
+    // mintBootstrapCredential).
+    //
+    // Point the hub-presence probe at a guaranteed-closed port so the test is
+    // deterministic regardless of whether a real hub happens to be running on
+    // the dev box's 1939 (#445 added a live `/health` probe to branch the
+    // no-operator-token copy).
+    const { exitCode, stdout } = runCli(
+      ["create", "wantmint", "--mint", "--json"],
+      { PARACHUTE_HOME: home, PARACHUTE_HUB_PORT: "59399" },
+    );
+    expect(exitCode).toBe(0);
+    const payload = JSON.parse(stdout.trim());
+    // No hub here → no token, and the standalone guidance asks for NO admin
+    // grant (the #445 hub-present "admin wizard" copy is gated out by the dead
+    // probe port above).
+    expect(payload.token).toBe("");
+    expect(payload.token_guidance).not.toContain("admin");
+  });
+});
+
 /**
  * Regression tests for #208: `vault create` was not updating
  * `~/.parachute/services.json`, so vaults created after init were invisible
@@ -191,11 +361,169 @@ describe("vault create (human mode)", () => {
     );
     expect(exitCode).toBe(0);
     expect(stdout).toContain('Vault "human" created.');
-    // vault#282 Stage 2: with no hub reachable in this sandbox, no token is
-    // issued — the human output prints the guidance instead of "API token:".
-    expect(stdout).toContain("No token issued");
-    expect(stdout).toContain("Install the hub");
+    // vault#442: default auth is per-user OAuth — NO token is minted, even when
+    // a hub would have been reachable. The human output leads with the OAuth
+    // connect command and never prints an "API token:" line.
+    expect(stdout).toContain("No token minted");
+    expect(stdout).toContain("Connect your AI: claude mcp add --transport http parachute-human");
+    expect(stdout).not.toContain("API token:");
+    // The old admin auto-mint failure copy must NOT fire on a default create.
+    expect(stdout).not.toContain("No token issued");
     // Human output should NOT be valid JSON.
     expect(() => JSON.parse(stdout.trim())).toThrow();
   });
 });
+
+/**
+ * Create-time default backup posture: new vaults default to an internal live
+ * mirror (local git backup of the markdown projection). The History preset
+ * `{enabled:true, location:internal, sync_mode:events, auto_commit:true,
+ * auto_push:false}` is written to `data/<vault>/mirror-config.yaml` and (when
+ * git is present) the internal mirror dir is git-bootstrapped. The behavior is
+ * controlled by the server-wide `default_mirror` knob (default `internal`) and
+ * overridable per-create by `--no-mirror`.
+ *
+ * Critically: create-time ONLY — already-created vaults are NOT retroactively
+ * migrated, and the git-less box stays a successful create (best-effort
+ * bootstrap, config still written, actionable log).
+ */
+describe("vault create — default internal live mirror", () => {
+  test("default (no knob) → History-preset mirror config written + git-bootstrapped", () => {
+    const { exitCode } = runCli(["create", "backed", "--json"], {
+      PARACHUTE_HOME: home,
+    });
+    expect(exitCode).toBe(0);
+
+    // Mirror config exists with the exact History preset.
+    const cfgPath = mirrorConfigPath(home, "backed");
+    expect(existsSync(cfgPath)).toBe(true);
+    const cfg = readFileSync(cfgPath, "utf-8");
+    expect(cfg).toContain("enabled: true");
+    expect(cfg).toContain("location: internal");
+    expect(cfg).toContain("sync_mode: events");
+    expect(cfg).toContain("auto_commit: true");
+    expect(cfg).toContain("auto_push: false");
+
+    // Git present on the test host → the internal mirror dir is a real repo
+    // with the seed commit (bootstrap ran). counts/usage reflect it: the
+    // mirror working tree exists under the vault data dir.
+    const repo = mirrorRepoPath(home, "backed");
+    expect(existsSync(join(repo, ".git"))).toBe(true);
+    const log = Bun.spawnSync({
+      cmd: ["git", "-C", repo, "log", "--oneline"],
+      stdout: "pipe",
+    });
+    expect(new TextDecoder().decode(log.stdout)).toContain("initial mirror bootstrap");
+  });
+
+  test("default_mirror: off knob → no mirror config written", () => {
+    writeDefaultMirrorKnob(home, "off");
+    const { exitCode } = runCli(["create", "bare", "--json"], {
+      PARACHUTE_HOME: home,
+    });
+    expect(exitCode).toBe(0);
+
+    // Vault is created…
+    expect(existsSync(join(home, "vault", "data", "bare", "vault.db"))).toBe(true);
+    // …but NO mirror config + NO mirror dir.
+    expect(existsSync(mirrorConfigPath(home, "bare"))).toBe(false);
+    expect(existsSync(mirrorRepoPath(home, "bare"))).toBe(false);
+  });
+
+  test("default_mirror: internal knob (explicit) → mirror config written", () => {
+    writeDefaultMirrorKnob(home, "internal");
+    const { exitCode } = runCli(["create", "explicit", "--json"], {
+      PARACHUTE_HOME: home,
+    });
+    expect(exitCode).toBe(0);
+    expect(existsSync(mirrorConfigPath(home, "explicit"))).toBe(true);
+  });
+
+  test("--no-mirror → no mirror config even when knob is internal", () => {
+    writeDefaultMirrorKnob(home, "internal");
+    const { exitCode } = runCli(["create", "optout", "--no-mirror", "--json"], {
+      PARACHUTE_HOME: home,
+    });
+    expect(exitCode).toBe(0);
+
+    expect(existsSync(join(home, "vault", "data", "optout", "vault.db"))).toBe(true);
+    expect(existsSync(mirrorConfigPath(home, "optout"))).toBe(false);
+    expect(existsSync(mirrorRepoPath(home, "optout"))).toBe(false);
+  });
+
+  test("--no-mirror in human mode keeps the rest of the create working", () => {
+    const { exitCode, stdout } = runCli(["create", "humanbare", "--no-mirror"], {
+      PARACHUTE_HOME: home,
+    });
+    expect(exitCode).toBe(0);
+    expect(stdout).toContain('Vault "humanbare" created.');
+    expect(existsSync(mirrorConfigPath(home, "humanbare"))).toBe(false);
+  });
+
+  test("git missing → vault still creates, config written, mirror NOT bootstrapped, actionable log, no crash", () => {
+    // Simulate a git-less server: spawn the CLI with a PATH that resolves
+    // `bun` (so the test can run) but NOT `git`. `bootstrapInternalMirror`'s
+    // `Bun.which("git")` preflight then returns null → friendly,
+    // best-effort failure. The vault create MUST still succeed.
+    const bunBin = Bun.which("bun");
+    expect(bunBin).toBeTruthy();
+    const fakeBin = mkdtempSync(join(tmpdir(), "vault-create-nogit-bin-"));
+    symlinkSync(bunBin!, join(fakeBin, "bun"));
+    try {
+      const proc = Bun.spawnSync({
+        cmd: [bunBin!, CLI, "create", "nogit", "--json"],
+        stdout: "pipe",
+        stderr: "pipe",
+        // Replace PATH entirely so `git` is unresolvable — only our fake bin
+        // (bun only) is on the path.
+        env: { ...process.env, PARACHUTE_HOME: home, PATH: fakeBin },
+      });
+      const exitCode = proc.exitCode ?? -1;
+      const stdout = new TextDecoder().decode(proc.stdout);
+      const stderr = new TextDecoder().decode(proc.stderr);
+
+      // No crash — the vault create succeeds on a git-less box.
+      expect(exitCode).toBe(0);
+      // The vault itself was created.
+      expect(existsSync(join(home, "vault", "data", "nogit", "vault.db"))).toBe(true);
+      // The mirror CONFIG was still written (intent persists for when git
+      // lands later).
+      expect(existsSync(mirrorConfigPath(home, "nogit"))).toBe(true);
+      // But the mirror was NOT git-bootstrapped (no .git — git was absent).
+      expect(existsSync(join(mirrorRepoPath(home, "nogit"), ".git"))).toBe(false);
+      // And the operator got an actionable, clear log on stderr.
+      expect(stderr).toContain("local git backup configured but not yet active");
+      expect(stderr).toContain("Install git");
+      // JSON stdout stays clean + parseable (the note went to stderr).
+      const payload = JSON.parse(stdout.trim());
+      expect(payload.name).toBe("nogit");
+    } finally {
+      rmSync(fakeBin, { recursive: true, force: true });
+    }
+  });
+
+  test("EXISTING vault (created before this change) is NOT auto-migrated on a later create", () => {
+    // Simulate a vault that predates the default-mirror behavior: create it
+    // with the knob OFF so it gets no mirror config (stand-in for "created by
+    // an older vault build").
+    writeDefaultMirrorKnob(home, "off");
+    const first = runCli(["create", "legacy", "--json"], { PARACHUTE_HOME: home });
+    expect(first.exitCode).toBe(0);
+    expect(existsSync(mirrorConfigPath(home, "legacy"))).toBe(false);
+
+    // Now flip the knob ON and create a SECOND, different vault. The act of
+    // creating "fresh" (which DOES get a mirror) must not retroactively write
+    // a mirror config onto the pre-existing "legacy" vault — create-time only,
+    // never a sweep over existing vaults.
+    writeDefaultMirrorKnob(home, "internal");
+    const second = runCli(["create", "fresh", "--json"], { PARACHUTE_HOME: home });
+    expect(second.exitCode).toBe(0);
+
+    // The new vault is backed…
+    expect(existsSync(mirrorConfigPath(home, "fresh"))).toBe(true);
+    // …but the pre-existing vault is left exactly as it was — no surprise
+    // mirror config, no surprise disk-doubling mirror repo.
+    expect(existsSync(mirrorConfigPath(home, "legacy"))).toBe(false);
+    expect(existsSync(mirrorRepoPath(home, "legacy"))).toBe(false);
+  });
+});

package/src/vault-name.test.ts

@@ -7,7 +7,13 @@
  */
 
 import { describe, test, expect } from "bun:test";
-import { validateVaultName, decideInitVaultName, resolveFirstBootVaultName } from "./vault-name.ts";
+import {
+  RESERVED_VAULT_NAMES,
+  decideInitVaultName,
+  reservedNameSquatWarnings,
+  resolveFirstBootVaultName,
+  validateVaultName,
+} from "./vault-name.ts";
 
 describe("validateVaultName", () => {
   describe("accepts", () => {
@@ -69,12 +75,29 @@ describe("validateVaultName", () => {
       }
     });
 
-    test("reserved name 'list'", () => {
-      const result = validateVaultName("list");
+    // The consolidated reserved set (2026-06-09 hub-module-boundary B2):
+    // `list` (legacy), `new` + `assets` (hub SPA route collisions), `admin`
+    // (the daemon-level /vault/admin multi-vault mount). Kept in lockstep
+    // with hub's RESERVED_VAULT_NAMES.
+    test.each(["list", "new", "assets", "admin"])("reserved name '%s'", (name) => {
+      const result = validateVaultName(name);
       expect(result.ok).toBe(false);
       if (!result.ok) expect(result.error).toContain("reserved");
     });
 
+    test("the exported set carries exactly the four consolidated names", () => {
+      expect([...RESERVED_VAULT_NAMES].sort()).toEqual(["admin", "assets", "list", "new"]);
+    });
+
+    test.each(["adminx", "admin2", "newer", "asset", "listing"])(
+      "near-miss '%s' is NOT reserved",
+      (name) => {
+        const result = validateVaultName(name);
+        expect(result.ok).toBe(true);
+        if (result.ok) expect(result.name).toBe(name);
+      },
+    );
+
     test("single character (below 2-char min)", () => {
       const result = validateVaultName("a");
       expect(result.ok).toBe(false);
@@ -95,6 +118,41 @@ describe("validateVaultName", () => {
   });
 });
 
+describe("reservedNameSquatWarnings", () => {
+  test("fires for a squatted 'admin' vault, naming the shadowing + recovery", () => {
+    const warnings = reservedNameSquatWarnings(["default", "admin"]);
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]).toContain('vault "admin"');
+    expect(warnings[0]).toContain("shadowed");
+    expect(warnings[0]).toContain("/vault/admin/*");
+    // Recovery procedure (no rename command exists): export → create →
+    // import → remove.
+    expect(warnings[0]).toContain("export");
+    expect(warnings[0]).toContain("create <newname>");
+    expect(warnings[0]).toContain("import");
+    expect(warnings[0]).toContain("remove admin --yes");
+  });
+
+  test("fires once per squatted name — admin + new + assets all warned", () => {
+    const warnings = reservedNameSquatWarnings(["admin", "new", "assets", "ok"]);
+    expect(warnings).toHaveLength(3);
+    expect(warnings.join("\n")).toContain('vault "admin"');
+    expect(warnings.join("\n")).toContain('vault "new"');
+    expect(warnings.join("\n")).toContain('vault "assets"');
+  });
+
+  test("silent for clean vault lists and near-misses", () => {
+    expect(reservedNameSquatWarnings([])).toEqual([]);
+    expect(reservedNameSquatWarnings(["default", "work", "adminx", "admin2"])).toEqual([]);
+  });
+
+  test("silent for 'list' (reserved for consistency, but not shadowed)", () => {
+    // `/vault/list/*` still routes per-vault — list is reserved at create
+    // time but a legacy squatter keeps working, so no scary boot warning.
+    expect(reservedNameSquatWarnings(["list"])).toEqual([]);
+  });
+});
+
 describe("decideInitVaultName", () => {
   test("--vault-name=aaron resolves to name 'aaron'", () => {
     const d = decideInitVaultName(["--vault-name", "aaron"], { isTTY: true });

package/src/vault-name.ts

@@ -7,34 +7,82 @@
  * rejected up front.
  *
  * Rule: lowercase alphanumeric + hyphens or underscores, 2–32 chars, with
- * `list` reserved. Used by the `init` prompt, the `--vault-name` flag, and
- * the `PARACHUTE_VAULT_NAME` env var at server first-boot. `cmdCreate`
- * keeps its own (slightly more permissive, legacy) regex for backward
- * compat — tightening it would reject names existing users may already
- * have minted.
+ * `list` / `new` / `assets` / `admin` reserved. Used by the `init` prompt,
+ * the `--vault-name` flag, the `PARACHUTE_VAULT_NAME` env var at server
+ * first-boot, and (since the 2026-06-09 hub-module-boundary migration B2)
+ * `cmdCreate` — every name-minting edge shares this one validator.
  */
 
 const VAULT_NAME_RE = /^[a-z0-9_-]+$/;
 const VAULT_NAME_MIN_LEN = 2;
 const VAULT_NAME_MAX_LEN = 32;
 
-const RESERVED_NAMES = new Set([
-  // Collides with the `/vaults/list` discovery endpoint historically; the
-  // routes have since moved under `/vault/<name>/`, but `cmdCreate` still
-  // rejects "list" and consistency is cheap.
+/**
+ * THE reserved vault-name set — kept in lockstep with hub's
+ * `RESERVED_VAULT_NAMES` (parachute-hub/src/vault-name.ts, B2h of the
+ * 2026-06-09 hub-module-boundary migration). A vault under any of these
+ * names would have its URL surface captured by a reserved route:
+ *
+ *   - `list`   — legacy `/vaults/list` discovery-endpoint collision; the
+ *     routes have since moved under `/vault/<name>/`, but consistency with
+ *     the historical reservation is cheap.
+ *   - `new`    — collides with `/vault/new`, the hub SPA's create route.
+ *   - `assets` — collides with `/vault/assets/*`, the hub SPA's bundle.
+ *   - `admin`  — collides with `/vault/admin`, the daemon-level mount for
+ *     vault's own multi-vault admin surface (B3). Both the hub's route and
+ *     this daemon's own routing dispatch `/vault/admin/*` before the
+ *     per-vault branch, so a vault named `admin` would be fully shadowed.
+ */
+export const RESERVED_VAULT_NAMES: ReadonlySet<string> = new Set([
   "list",
+  "new",
+  "assets",
+  "admin",
 ]);
 
+/**
+ * The subset of reserved names whose data plane is SHADOWED by reserved
+ * routes when a vault squats them (created before the reservation landed).
+ * `list` is reserved for historical consistency only — `/vault/list/*`
+ * still routes per-vault — so it's excluded here.
+ */
+const SHADOWED_RESERVED_NAMES = ["admin", "new", "assets"] as const;
+
+/**
+ * Build boot-time warnings for vaults squatting a shadowed reserved name.
+ * Pure (takes the vault list, returns warning strings) so server boot can
+ * `console.warn` each and tests can pin the copy without booting a server.
+ *
+ * Recovery procedure is spelled out because no rename command exists:
+ * export → create under a new name → import → remove the squatter.
+ */
+export function reservedNameSquatWarnings(vaults: readonly string[]): string[] {
+  const warnings: string[] = [];
+  for (const reserved of SHADOWED_RESERVED_NAMES) {
+    if (!vaults.includes(reserved)) continue;
+    warnings.push(
+      `[reserved-name] vault "${reserved}" exists but "${reserved}" is a reserved name — ` +
+        `its data plane (/vault/${reserved}/*) is shadowed by reserved hub/daemon routes, so its ` +
+        `MCP, REST, and admin surfaces are unreachable. Recover by renaming it (no rename ` +
+        `command exists): parachute-vault export <dir> --vault ${reserved} → ` +
+        `parachute-vault create <newname> → parachute-vault import <dir> --vault <newname> → ` +
+        `parachute-vault remove ${reserved} --yes`,
+    );
+  }
+  return warnings;
+}
+
 export type VaultNameValidation =
   | { ok: true; name: string }
   | { ok: false; error: string };
 
 /**
  * Validate a vault name. Accepts lowercase alphanumeric + hyphens or
- * underscores, 2–32 chars. Trims surrounding whitespace before checking.
- * `cmdCreate` keeps its own (legacy-permissive) regex; this validator is
- * the strict gate used by the env var, the `--vault-name` flag, and
- * hub's first-boot wizard.
+ * underscores, 2–32 chars, none of `RESERVED_VAULT_NAMES`. Trims
+ * surrounding whitespace before checking. The one gate used by the env
+ * var, the `--vault-name` flag, hub's first-boot wizard, AND `cmdCreate`
+ * (consolidated 2026-06-09 — cmdCreate previously carried its own inline
+ * charset + `"list"` check that had drifted from this set).
  */
 export function validateVaultName(raw: string): VaultNameValidation {
   const name = raw.trim();
@@ -54,7 +102,7 @@ export function validateVaultName(raw: string): VaultNameValidation {
         "vault names must be lowercase alphanumeric with hyphens or underscores. Try again.",
     };
   }
-  if (RESERVED_NAMES.has(name)) {
+  if (RESERVED_VAULT_NAMES.has(name)) {
     return { ok: false, error: `"${name}" is a reserved vault name.` };
   }
   return { ok: true, name };