@openparachute/vault 0.5.3-rc.3 → 0.6.0

package/core/src/tag-hierarchy.ts

@@ -143,6 +143,86 @@ export function getTagDescendants(h: TagHierarchy, tag: string): Set<string> {
   return result;
 }
 
+/**
+ * Tag-expansion axis (vault tag `expand` axis — design
+ * `design/2026-06-09-tag-expand-axis.md`). A tag relates to others along two
+ * orthogonal axes; this selects which one (or both, or neither) a query expands
+ * along:
+ *
+ * - `"subtypes"` (DEFAULT): tag ∪ `parent_names` descendants. The semantic
+ *   is-a axis — today's always-on behavior, unchanged. `_default` universal
+ *   parent magic fires here.
+ * - `"namespace"`: tag ∪ {names lexically prefixed `tag/`}. The organizational
+ *   filing axis — purely lexical over the known tag set, no `parent_names`, no
+ *   `_default` magic.
+ * - `"both"`: union of subtypes and namespace.
+ * - `"exact"`: the literal tag only, no expansion.
+ */
+export type TagExpandMode = "subtypes" | "namespace" | "both" | "exact";
+
+export const TAG_EXPAND_MODES: readonly TagExpandMode[] = [
+  "subtypes",
+  "namespace",
+  "both",
+  "exact",
+] as const;
+
+export const DEFAULT_TAG_EXPAND_MODE: TagExpandMode = "subtypes";
+
+/**
+ * Lexical namespace expansion for a single tag: the tag itself plus every
+ * known tag name filed under it (`name === tag` OR `name` starts with
+ * `tag + "/"`). Purely a string-prefix match over `h.allTags` — namespacing is
+ * free-form (the slash in the tag *name*), declared nowhere, which is the whole
+ * point: subtyping is declared via `parent_names`, filing is not. No `_default`
+ * magic here — that's a subtypes-axis concept.
+ */
+export function getTagNamespace(h: TagHierarchy, tag: string): Set<string> {
+  // Pre-seeded with `tag` itself, so the loop only needs the strict `tag/*`
+  // prefix test (the `name === tag` case is already covered by the seed).
+  const result = new Set<string>([tag]);
+  const prefix = tag + "/";
+  for (const name of h.allTags) {
+    if (name.startsWith(prefix)) result.add(name);
+  }
+  return result;
+}
+
+/**
+ * Mode-aware single-tag expansion (vault tag `expand` axis). Returns the set of
+ * tag names a query for `tag` should match under `mode`. Always includes `tag`
+ * itself. Set semantics: a tag that is BOTH a declared subtype-child AND
+ * name-prefixed appears once.
+ *
+ * - `"subtypes"` → `getTagDescendants` (parent_names + `_default` magic).
+ * - `"namespace"` → `getTagNamespace` (lexical `tag/*`).
+ * - `"both"` → union of the two.
+ * - `"exact"` → `{tag}`.
+ */
+export function getTagExpansion(
+  h: TagHierarchy,
+  tag: string,
+  mode: TagExpandMode,
+): Set<string> {
+  switch (mode) {
+    case "exact":
+      return new Set<string>([tag]);
+    case "namespace":
+      return getTagNamespace(h, tag);
+    case "both": {
+      const union = new Set<string>(getTagDescendants(h, tag));
+      for (const name of getTagNamespace(h, tag)) union.add(name);
+      return union;
+    }
+    case "subtypes":
+    default:
+      // `default` is a defensive fallback — `TagExpandMode` already constrains
+      // the value to the four cases above; it can only be reached if an
+      // untyped caller passes a bad string.
+      return getTagDescendants(h, tag);
+  }
+}
+
 /**
  * Detect cycles in the declared hierarchy. Returns the list of tags
  * reachable from themselves via parent declarations. Used by

package/core/src/triggers-store.test.ts

@@ -0,0 +1,100 @@
+/**
+ * Unit tests for the persisted-triggers store (core/src/triggers-store.ts) —
+ * JSON encode/decode round-trip + upsert/list/get/delete semantics over an
+ * in-memory SQLite DB (schema v21).
+ */
+
+import { describe, test, expect, beforeEach } from "bun:test";
+import { Database } from "bun:sqlite";
+import { initSchema } from "./schema.js";
+import {
+  upsertTrigger,
+  listTriggers,
+  getTrigger,
+  deleteTrigger,
+  loadAllTriggers,
+} from "./triggers-store.js";
+
+let db: Database;
+
+beforeEach(() => {
+  db = new Database(":memory:");
+  initSchema(db);
+});
+
+function sample(name: string) {
+  return {
+    name,
+    events: ["created", "updated"] as Array<"created" | "updated">,
+    when: { tags: ["channel-message"], has_content: true },
+    action: {
+      webhook: "https://example.test/hook",
+      send: "json" as const,
+      timeout: 30000,
+      auth: { bearer: "jwt-token" },
+    },
+  };
+}
+
+describe("triggers-store", () => {
+  test("the triggers table exists after initSchema (v21)", () => {
+    const row = db
+      .prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='triggers'")
+      .get();
+    expect(row).toBeTruthy();
+  });
+
+  test("upsert → get round-trips the structured JSON columns", () => {
+    upsertTrigger(db, sample("inbound"));
+    const got = getTrigger(db, "inbound");
+    expect(got).not.toBeNull();
+    expect(got!.when).toEqual({ tags: ["channel-message"], has_content: true });
+    expect(got!.action.webhook).toBe("https://example.test/hook");
+    expect(got!.action.auth).toEqual({ bearer: "jwt-token" });
+    expect(got!.events).toEqual(["created", "updated"]);
+    expect(got!.created_at).toBeTruthy();
+    expect(got!.updated_at).toBeTruthy();
+  });
+
+  test("upsert by name replaces + preserves created_at, bumps updated_at", async () => {
+    const first = upsertTrigger(db, sample("inbound"));
+    // Ensure clock advances so updated_at differs.
+    await new Promise((r) => setTimeout(r, 5));
+    const second = upsertTrigger(db, {
+      ...sample("inbound"),
+      action: { webhook: "https://example.test/v2" },
+    });
+
+    expect(listTriggers(db)).toHaveLength(1);
+    expect(second.created_at).toBe(first.created_at);
+    expect(second.updated_at >= first.updated_at).toBe(true);
+    expect(getTrigger(db, "inbound")!.action.webhook).toBe("https://example.test/v2");
+  });
+
+  test("events defaults to [created, updated] when omitted", () => {
+    upsertTrigger(db, {
+      name: "no-events",
+      when: { tags: ["x"] },
+      action: { webhook: "https://example.test/hook" },
+    });
+    expect(getTrigger(db, "no-events")!.events).toEqual(["created", "updated"]);
+  });
+
+  test("list / loadAllTriggers return all rows ordered by name", () => {
+    upsertTrigger(db, sample("zebra"));
+    upsertTrigger(db, sample("alpha"));
+    expect(listTriggers(db).map((t) => t.name)).toEqual(["alpha", "zebra"]);
+    expect(loadAllTriggers(db).map((t) => t.name)).toEqual(["alpha", "zebra"]);
+  });
+
+  test("delete removes the row; returns false on a missing name", () => {
+    upsertTrigger(db, sample("inbound"));
+    expect(deleteTrigger(db, "inbound")).toBe(true);
+    expect(getTrigger(db, "inbound")).toBeNull();
+    expect(deleteTrigger(db, "inbound")).toBe(false);
+  });
+
+  test("getTrigger returns null for an unknown name", () => {
+    expect(getTrigger(db, "nope")).toBeNull();
+  });
+});

package/core/src/triggers-store.ts

@@ -0,0 +1,165 @@
+/**
+ * Persisted runtime triggers — per-vault CRUD over the `triggers` table
+ * (schema v21).
+ *
+ * Complements the static `config.yaml` trigger system: config.yaml triggers
+ * are loaded at boot and fire globally (all vaults); rows in this table live
+ * in a single vault's SQLite DB and are re-registered at boot scoped to that
+ * vault (they fire ONLY for events on the vault they were stored under).
+ *
+ * The structured columns (`events`, `when`, `action`) are JSON-encoded on
+ * write and parsed on read. `name` is the primary key, so `upsertTrigger`
+ * is a true upsert (insert-or-replace by name). The shape here is kept
+ * structurally compatible with `src/config.ts`'s `TriggerConfig` /
+ * `TriggerWhen` / `TriggerAction` without importing from `src/` — core stays
+ * dependency-free of the server layer.
+ *
+ * `action.auth.bearer`, when present, becomes an `Authorization: Bearer`
+ * header on the webhook POST (the JWT webhook-auth path that retires the
+ * old `?secret=` query param). It is stored verbatim in the JSON column.
+ */
+
+import type { Database } from "bun:sqlite";
+
+/** Predicate shape — mirrors src/config.ts:TriggerWhen. */
+export interface StoredTriggerWhen {
+  tags?: string[];
+  has_content?: boolean;
+  missing_metadata?: string[];
+  has_metadata?: string[];
+}
+
+/** Webhook auth — only the bearer-JWT path for now. */
+export interface StoredTriggerAuth {
+  bearer?: string;
+}
+
+/** Action shape — mirrors src/config.ts:TriggerAction plus `auth`. */
+export interface StoredTriggerAction {
+  webhook: string;
+  timeout?: number;
+  send?: "json" | "attachment" | "content";
+  auth?: StoredTriggerAuth;
+  // Forward-compat: include_context and any other action fields round-trip
+  // through the JSON column verbatim even though core doesn't interpret them.
+  [key: string]: unknown;
+}
+
+/** A persisted trigger row, decoded. */
+export interface StoredTrigger {
+  name: string;
+  events: Array<"created" | "updated">;
+  when: StoredTriggerWhen;
+  action: StoredTriggerAction;
+  created_at: string;
+  updated_at: string;
+}
+
+/** The writable subset callers pass to upsert. */
+export interface TriggerInput {
+  name: string;
+  events?: Array<"created" | "updated">;
+  when: StoredTriggerWhen;
+  action: StoredTriggerAction;
+}
+
+interface TriggerRow {
+  name: string;
+  events: string;
+  when: string;
+  action: string;
+  created_at: string;
+  updated_at: string;
+}
+
+function decodeRow(row: TriggerRow): StoredTrigger {
+  return {
+    name: row.name,
+    events: safeParse(row.events, ["created", "updated"]) as Array<"created" | "updated">,
+    when: safeParse(row.when, {}) as StoredTriggerWhen,
+    action: safeParse(row.action, { webhook: "" }) as StoredTriggerAction,
+    created_at: row.created_at,
+    updated_at: row.updated_at,
+  };
+}
+
+function safeParse(json: string, fallback: unknown): unknown {
+  try {
+    return JSON.parse(json);
+  } catch {
+    return fallback;
+  }
+}
+
+/**
+ * Insert or replace a trigger by name. Preserves `created_at` on update
+ * (re-fetches the existing row's timestamp) and stamps a fresh `updated_at`.
+ * Returns the stored shape.
+ */
+export function upsertTrigger(db: Database, input: TriggerInput): StoredTrigger {
+  const now = new Date().toISOString();
+  const existing = db
+    .prepare("SELECT created_at FROM triggers WHERE name = ?")
+    .get(input.name) as { created_at: string } | null;
+  const createdAt = existing?.created_at ?? now;
+  const events = input.events ?? ["created", "updated"];
+
+  db.prepare(
+    `INSERT INTO triggers (name, events, "when", action, created_at, updated_at)
+     VALUES (?, ?, ?, ?, ?, ?)
+     ON CONFLICT(name) DO UPDATE SET
+       events = excluded.events,
+       "when" = excluded."when",
+       action = excluded.action,
+       updated_at = excluded.updated_at`,
+  ).run(
+    input.name,
+    JSON.stringify(events),
+    JSON.stringify(input.when),
+    JSON.stringify(input.action),
+    createdAt,
+    now,
+  );
+
+  return {
+    name: input.name,
+    events,
+    when: input.when,
+    action: input.action,
+    created_at: createdAt,
+    updated_at: now,
+  };
+}
+
+/** List all persisted triggers for this vault, ordered by name. */
+export function listTriggers(db: Database): StoredTrigger[] {
+  const rows = db
+    .prepare(
+      `SELECT name, events, "when", action, created_at, updated_at
+       FROM triggers ORDER BY name`,
+    )
+    .all() as TriggerRow[];
+  return rows.map(decodeRow);
+}
+
+/** Fetch a single trigger by name, or null. */
+export function getTrigger(db: Database, name: string): StoredTrigger | null {
+  const row = db
+    .prepare(
+      `SELECT name, events, "when", action, created_at, updated_at
+       FROM triggers WHERE name = ?`,
+    )
+    .get(name) as TriggerRow | null;
+  return row ? decodeRow(row) : null;
+}
+
+/** Delete a trigger by name. Returns true if a row was removed. */
+export function deleteTrigger(db: Database, name: string): boolean {
+  const res = db.prepare("DELETE FROM triggers WHERE name = ?").run(name);
+  return res.changes > 0;
+}
+
+/** Load all persisted triggers (boot path). Alias of listTriggers for clarity. */
+export function loadAllTriggers(db: Database): StoredTrigger[] {
+  return listTriggers(db);
+}

package/core/src/types.ts

@@ -1,11 +1,13 @@
 import type { Database } from "bun:sqlite";
 import type { TagFieldSchema, TagRelationship, TagRelationshipMap, TagRecord } from "./tag-schemas.js";
 import type { PrunedField } from "./indexed-fields.js";
+import type { TagExpandMode } from "./tag-hierarchy.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";
 
 // ---- Note ----
 
@@ -85,6 +87,18 @@ export interface VaultStats {
 export interface QueryOpts {
   tags?: string[];
   tagMatch?: "all" | "any"; // "all" = must have ALL tags (default), "any" = must have ANY tag
+  /**
+   * Tag-expansion axis (vault tag `expand` axis — design
+   * `design/2026-06-09-tag-expand-axis.md`). Selects how each `tags` entry
+   * expands:
+   * - `"subtypes"` (DEFAULT): tag ∪ `parent_names` descendants. Today's
+   *   semantic is-a behavior, unchanged. `_default` universal magic fires here.
+   * - `"namespace"`: tag ∪ lexically name-prefixed `tag/*` (the filing axis).
+   * - `"both"`: union of subtypes + namespace.
+   * - `"exact"`: the literal tag only, no expansion.
+   * Absent → `"subtypes"` → byte-identical to pre-axis behavior.
+   */
+  expand?: TagExpandMode;
   excludeTags?: string[];
   // Presence filters. `true` → has at least one; `false` → has none.
   // When `tags` is also set, `hasTags` is ignored (the tag filter already constrains the set).
@@ -256,7 +270,7 @@ export interface Store {
    * agent loop can persist a single watermark and keep polling.
    */
   queryNotesPaged(opts: QueryOpts): Promise<QueryNotesPage>;
-  searchNotes(query: string, opts?: { tags?: string[]; limit?: number }): Promise<Note[]>;
+  searchNotes(query: string, opts?: { tags?: string[]; limit?: number; expand?: TagExpandMode }): Promise<Note[]>;
 
   // Tags
   tagNote(noteId: string, tags: string[]): Promise<void>;
@@ -268,6 +282,18 @@ export interface Store {
    * compute the effective allowlisted tag-set at auth time.
    */
   expandTagsWithDescendants(tags: string[]): Promise<Set<string>>;
+  /**
+   * Mode-aware tag expansion (vault tag `expand` axis). Expands each input tag
+   * along the selected axis and returns the union:
+   * - `"subtypes"` (default): `{tag} ∪ parent_names-descendants` — identical to
+   *   `expandTagsWithDescendants` (which is a thin shim over this).
+   * - `"namespace"`: `{tag} ∪ lexically name-prefixed tag/*`.
+   * - `"both"`: union of the two.
+   * - `"exact"`: `{tag}` only.
+   * Always includes each input tag. Used by the live-query matcher to lower the
+   * IDENTICAL expansion the snapshot query engine uses for the same `expand`.
+   */
+  expandTags(tags: string[], mode?: TagExpandMode): Promise<Set<string>>;
   listTags(): Promise<{ name: string; count: number }[]>;
   deleteTag(name: string): Promise<{ deleted: boolean; notes_untagged: number }>;
   renameTag(

package/package.json

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

package/src/admin-spa.test.ts

@@ -12,7 +12,12 @@ import { describe, test, expect, beforeAll, afterAll } from "bun:test";
 import { mkdirSync, readFileSync, rmSync, writeFileSync } from "fs";
 import { join } from "path";
 import { tmpdir } from "os";
-import { isAdminSpaPath, serveAdminSpa } from "./admin-spa.ts";
+import {
+  isAdminSpaPath,
+  isDaemonAdminSpaPath,
+  serveAdminSpa,
+  serveDaemonAdminSpa,
+} from "./admin-spa.ts";
 
 const fixtureDir = join(tmpdir(), `vault-admin-spa-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
 
@@ -130,15 +135,76 @@ describe("serveAdminSpa", () => {
   });
 });
 
+describe("isDaemonAdminSpaPath", () => {
+  test("matches /vault/admin and true subpaths", () => {
+    expect(isDaemonAdminSpaPath("/vault/admin")).toBe(true);
+    expect(isDaemonAdminSpaPath("/vault/admin/")).toBe(true);
+    expect(isDaemonAdminSpaPath("/vault/admin/assets/index.js")).toBe(true);
+    // The doubled path the per-vault regex would mis-read as vault "admin".
+    expect(isDaemonAdminSpaPath("/vault/admin/admin")).toBe(true);
+  });
+
+  test("does not match vaults whose name merely starts with 'admin'", () => {
+    expect(isDaemonAdminSpaPath("/vault/adminx")).toBe(false);
+    expect(isDaemonAdminSpaPath("/vault/admin2/admin")).toBe(false);
+    expect(isDaemonAdminSpaPath("/vault/admin-foo")).toBe(false);
+  });
+
+  test("does not match per-vault mounts or unrelated paths", () => {
+    expect(isDaemonAdminSpaPath("/vault/work/admin")).toBe(false);
+    expect(isDaemonAdminSpaPath("/admin")).toBe(false);
+    expect(isDaemonAdminSpaPath("/vaults")).toBe(false);
+  });
+});
+
+describe("serveDaemonAdminSpa (the /vault/admin multi-vault mount)", () => {
+  test("bare /vault/admin redirects to trailing-slash form (301)", async () => {
+    // Same load-bearing canonicalization as the per-vault mount: Vite's
+    // relative asset URLs (./assets/...) resolve against the document's
+    // DIRECTORY, so /vault/admin (bare) would resolve assets to
+    // /vault/assets/... and 404 them.
+    const res = await serveDaemonAdminSpa(fixtureDir, "/vault/admin");
+    expect(res.status).toBe(301);
+    expect(res.headers.get("Location")).toBe("/vault/admin/");
+  });
+
+  test("/vault/admin/ returns the SPA index", async () => {
+    const res = await serveDaemonAdminSpa(fixtureDir, "/vault/admin/");
+    expect(res.status).toBe(200);
+    expect(res.headers.get("content-type")).toContain("text/html");
+    expect(await res.text()).toContain("shell");
+  });
+
+  test("daemon-mount asset path strips cleanly", async () => {
+    const res = await serveDaemonAdminSpa(fixtureDir, "/vault/admin/assets/index-abc.js");
+    expect(res.status).toBe(200);
+    expect(res.headers.get("content-type")).toContain("application/javascript");
+  });
+
+  test("/vault/admin/admin serves the shell (client route, not a per-vault boot)", async () => {
+    const res = await serveDaemonAdminSpa(fixtureDir, "/vault/admin/admin");
+    expect(res.status).toBe(200);
+    expect(res.headers.get("content-type")).toContain("text/html");
+    expect(await res.text()).toContain("shell");
+  });
+
+  test("path traversal (..) cannot escape dist dir on the daemon mount", async () => {
+    const res = await serveDaemonAdminSpa(fixtureDir, "/vault/admin/../../etc/passwd");
+    expect(res.status).toBe(200);
+    expect(await res.text()).toContain("shell");
+  });
+});
+
 describe("hub <-> vault managementUrl contract", () => {
   // Browsers drop the URL fragment when following a 301 (RFC 7231 SHOULD
   // preserve, but Chrome/Firefox/Safari are inconsistent in practice). The
   // hub-issued JWT travels in `#token=...`, so a redirected click loses the
-  // token and the SPA boots unauthenticated. Hub's resolveManagementUrl joins
-  // the per-vault module URL with module.json's `managementUrl` verbatim — if
-  // it ends with "/" the canonical click target is `/vault/<name>/admin/`
-  // (no redirect, fragment preserved). Without the trailing slash hub emits
-  // `/vault/<name>/admin`, the server 301s, and the fragment is gone.
+  // token and the SPA boots unauthenticated. Under the B4 URL-resolution
+  // semantics (hub#637) a RELATIVE managementUrl is mount-joined per
+  // instance (`/vault/<name>` + "/" + "admin/") — if it ends with "/" the
+  // canonical click target is `/vault/<name>/admin/` (no redirect, fragment
+  // preserved). Without the trailing slash hub emits `/vault/<name>/admin`,
+  // the server 301s, and the fragment is gone.
   test("module.json managementUrl ends with '/' so hub emits the no-redirect form", () => {
     const moduleJson = JSON.parse(
       readFileSync(join(import.meta.dir, "..", ".parachute", "module.json"), "utf8"),
@@ -146,16 +212,40 @@ describe("hub <-> vault managementUrl contract", () => {
     expect(moduleJson.managementUrl).toMatch(/\/$/);
   });
 
-  test("the canonical hub-emitted URL serves the SPA shell directly (no 301)", async () => {
-    // Mirror hub's resolveManagementUrl shape: per-vault module URL +
-    // managementUrl. With managementUrl="/admin/" the result is
+  test("managementUrl + uiUrl are RELATIVE (per-instance); configUiUrl is origin-absolute (daemon-level)", () => {
+    // B4 semantics (2026-06-09 hub-module-boundary): relative = mount-joined
+    // per instance; leading "/" = origin-absolute verbatim. The per-instance
+    // surfaces (manage tile, instance UI) stay per-vault; the module-level
+    // config UI points at the daemon-level multi-vault home. A leading "/"
+    // on managementUrl/uiUrl here would flip every instance tile to the
+    // module home; a relative configUiUrl would wrongly mount-join.
+    const moduleJson = JSON.parse(
+      readFileSync(join(import.meta.dir, "..", ".parachute", "module.json"), "utf8"),
+    );
+    expect(moduleJson.managementUrl).toBe("admin/");
+    expect(moduleJson.uiUrl).toBe("admin/");
+    expect(moduleJson.configUiUrl).toBe("/vault/admin/");
+  });
+
+  test("the canonical hub-emitted per-instance URL serves the SPA shell directly (no 301)", async () => {
+    // Mirror hub's per-instance join under B4: mount + "/" + relative
+    // managementUrl. With managementUrl="admin/" the result is
     // /vault/<name>/admin/ — which serveAdminSpa returns as 200, not 301.
     const moduleJson = JSON.parse(
       readFileSync(join(import.meta.dir, "..", ".parachute", "module.json"), "utf8"),
     );
-    const canonical = `/vault/work${moduleJson.managementUrl}`;
+    const canonical = `/vault/work/${moduleJson.managementUrl}`;
     const res = await serveAdminSpa(fixtureDir, canonical);
     expect(res.status).toBe(200);
     expect(res.headers.get("Location")).toBeNull();
   });
+
+  test("the canonical configUiUrl serves the daemon-level shell directly (no 301)", async () => {
+    const moduleJson = JSON.parse(
+      readFileSync(join(import.meta.dir, "..", ".parachute", "module.json"), "utf8"),
+    );
+    const res = await serveDaemonAdminSpa(fixtureDir, moduleJson.configUiUrl);
+    expect(res.status).toBe(200);
+    expect(res.headers.get("Location")).toBeNull();
+  });
 });

package/src/admin-spa.ts

@@ -28,6 +28,18 @@ import { fileURLToPath } from "node:url";
  */
 const ADMIN_SPA_MOUNT_RE = /^\/vault\/([^/]+)\/admin(?=\/|$)/;
 
+/**
+ * Regex anchoring the DAEMON-LEVEL multi-vault SPA mount at `/vault/admin`
+ * (B3 of the 2026-06-09 hub-module-boundary migration). Deliberately a
+ * SEPARATE regex from the per-vault one — merging them would let
+ * `/vault/admin/admin` boot per-vault mode with name="admin". `admin` is a
+ * reserved vault name (see `vault-name.ts:RESERVED_VAULT_NAMES`), so this
+ * mount can never collide with a real instance; routing dispatches it
+ * BEFORE the per-vault branch so a pre-reservation squatter is shadowed
+ * (and warned about at boot) rather than capturing the mount.
+ */
+const DAEMON_ADMIN_SPA_MOUNT_RE = /^\/vault\/admin(?=\/|$)/;
+
 /**
  * Resolve the default SPA bundle dir. Anchored to this file's location so
  * a `bun src/server.ts` from any cwd still finds `<repo>/web/ui/dist/`.
@@ -92,18 +104,24 @@ function spaContentType(pathname: string): string {
  * even before a token has been minted (so the operator can actually see
  * the empty / auth-required state we render in `VaultDetail.tsx`).
  */
-export async function serveAdminSpa(spaDistDir: string, pathname: string): Promise<Response> {
+export async function serveAdminSpa(
+  spaDistDir: string,
+  pathname: string,
+  mountRe: RegExp = ADMIN_SPA_MOUNT_RE,
+): Promise<Response> {
   if (!existsSync(spaDistDir)) {
     return new Response(
       "vault admin SPA bundle not found — run `bun run build` in web/ui/ to produce dist/",
       { status: 503, headers: { "content-type": "text/plain; charset=utf-8" } },
     );
   }
-  // Strip the mount prefix:
+  // Strip the mount prefix (per-vault by default; the daemon-level mount
+  // passes its own regex via `serveDaemonAdminSpa`):
   //   /vault/foo/admin       → ""
   //   /vault/foo/admin/      → "/"
   //   /vault/foo/admin/x.js  → "/x.js"
-  const sub = pathname.replace(ADMIN_SPA_MOUNT_RE, "");
+  //   /vault/admin/x.js      → "/x.js"   (daemon mount)
+  const sub = pathname.replace(mountRe, "");
 
   // Canonicalize the bare mount → trailing-slash form. Vite emits
   // *relative* asset URLs (`./assets/index-abc.js`) since `<name>` isn't
@@ -155,7 +173,34 @@ export async function serveAdminSpa(spaDistDir: string, pathname: string): Promi
  * Match `/vault/<name>/admin` or `/vault/<name>/admin/...`. Bare
  * `/vault/<name>/admin-foo` and `/vault/<name>` (the metadata endpoint)
  * must NOT trigger this — only the SPA mount root and its true subpaths.
+ *
+ * NOTE: `/vault/admin/admin` also matches this regex (name="admin") — the
+ * router dispatches `isDaemonAdminSpaPath` FIRST so that path never
+ * reaches per-vault mode. Keep that dispatch order; it's pinned in
+ * routing.test.ts.
  */
 export function isAdminSpaPath(pathname: string): boolean {
   return ADMIN_SPA_MOUNT_RE.test(pathname);
 }
+
+/**
+ * Match the daemon-level multi-vault mount: `/vault/admin` or
+ * `/vault/admin/...`. `/vault/adminx` (a real vault that begins with
+ * "admin") must NOT trigger this — only the exact segment.
+ */
+export function isDaemonAdminSpaPath(pathname: string): boolean {
+  return DAEMON_ADMIN_SPA_MOUNT_RE.test(pathname);
+}
+
+/**
+ * Serve the SPA bundle under the daemon-level `/vault/admin` mount. Same
+ * bundle as the per-vault mount — `web/ui/src/lib/mount.ts` detects which
+ * basename it booted under at runtime — with the daemon mount's own
+ * prefix-strip. The bare-mount 301 inside `serveAdminSpa` fires for
+ * `/vault/admin` too: Vite's relative asset URLs resolve against the
+ * document's DIRECTORY, so without the trailing-slash canonicalization
+ * assets would resolve to `/vault/assets/...` and 404.
+ */
+export function serveDaemonAdminSpa(spaDistDir: string, pathname: string): Promise<Response> {
+  return serveAdminSpa(spaDistDir, pathname, DAEMON_ADMIN_SPA_MOUNT_RE);
+}