@openparachute/vault 0.4.8 → 0.4.9-rc.11

package/src/module-config.ts

@@ -19,8 +19,11 @@
  *   - port:                 GlobalConfig.port, exposed read-only.
  *   - autoTranscribe.*:     vault↔scribe handoff (vault#353, design 2026-05-21
  *                           Part 2). Three nested fields per design Q4:
- *       - enabled:          boolean toggle, default false (persisted in
- *                           GlobalConfig.auto_transcribe.enabled).
+ *       - enabled:          boolean toggle, default true when scribe is
+ *                           reachable (persisted in
+ *                           GlobalConfig.auto_transcribe.enabled). Default
+ *                           flipped from off → on so installing scribe is
+ *                           the only opt-in signal needed.
  *       - scribeUrl:        readOnly — resolved per-process from
  *                           `~/.parachute/services.json` via
  *                           `scribe-discovery.ts`. Operators can't point at an
@@ -69,10 +72,10 @@ export function buildConfigSchema(): ModuleConfigSchema {
         properties: {
           enabled: {
             type: "boolean",
-            default: false,
+            default: true,
             title: "Enable auto-transcription",
             description:
-              "Master toggle. When false, audio uploads land normally without any scribe interaction. Global — persisted in `GlobalConfig.auto_transcribe.enabled` and applies to every vault on this server. Per-vault control is a future enhancement when multi-vault deployments need it.",
+              "Master toggle. Default on — audio uploads transcribe automatically when scribe is reachable. Set to false to disable. Global — persisted in `GlobalConfig.auto_transcribe.enabled` and applies to every vault on this server. Per-vault control is a future enhancement when multi-vault deployments need it.",
           },
           scribeUrl: {
             type: "string",
@@ -139,7 +142,10 @@ export function buildConfigValues(
   return {
     audio_retention: vaultConfig.audio_retention ?? "keep",
     autoTranscribe: {
-      enabled: globalConfig.auto_transcribe?.enabled ?? false,
+      // Match shouldAutoTranscribe's `?? true` so the admin SPA displays
+      // the same value runtime uses. An unset config row shows `true`
+      // because that's what vault will actually do on the next audio upload.
+      enabled: globalConfig.auto_transcribe?.enabled ?? true,
       scribeUrl,
     },
     // Legacy alias mirrors `autoTranscribe.scribeUrl` so hubs reading the

package/src/routes.ts

@@ -2077,7 +2077,13 @@ const MIME_TYPES: Record<string, string> = {
   ".mp4": "video/mp4",
 };
 
-export async function handleStorage(req: Request, path: string, vault: string): Promise<Response> {
+export async function handleStorage(
+  req: Request,
+  path: string,
+  vault: string,
+  store: Store,
+  tagScope: TagScopeCtx = NO_TAG_SCOPE,
+): Promise<Response> {
   const assets = assetsDir(vault);
 
   if (req.method === "POST" && path === "/upload") {
@@ -2121,6 +2127,37 @@ export async function handleStorage(req: Request, path: string, vault: string):
       return json({ error: "Not found" }, 404);
     }
 
+    // Tag-scope gate (C0 adversarial-audit finding). The note-keyed
+    // attachment surfaces (GET /notes/:id?include_attachments, GET
+    // /notes/:id/attachments, query results) are all gated behind
+    // `noteWithinTagScope`, but this raw byte-serve endpoint historically
+    // shipped bytes purely by filesystem path with only a path-traversal
+    // guard — so a tag-scoped token (scoped to e.g. ["work"]) could fetch
+    // an out-of-scope note's attachment bytes directly if it learned the
+    // storage path. Path secrecy (the 122-bit UUID in the filename) is NOT
+    // an access control. When the token is tag-scoped, reverse-lookup the
+    // requested path → owning attachment row(s) → note_id, and serve only
+    // if at least one owning note is within scope. Unscoped tokens
+    // (tagScope.raw === null) keep the prior behavior verbatim.
+    //
+    // 404 (not 403) on out-of-scope / no-owning-row, matching the
+    // note-level surfaces — don't create an existence oracle that confirms
+    // "this path exists but you can't see it."
+    if (tagScope.raw !== null) {
+      const rows = await store.getAttachmentsByPath(reqPath);
+      let allowed = false;
+      for (const att of rows) {
+        const note = await store.getNote(att.noteId);
+        if (note && noteWithinTagScope(note, tagScope.allowed, tagScope.raw)) {
+          allowed = true;
+          break;
+        }
+      }
+      if (!allowed) {
+        return json({ error: "Not found" }, 404);
+      }
+    }
+
     const stat = statSync(filePath);
     const ext = extname(filePath).toLowerCase();
     const contentType = MIME_TYPES[ext] ?? "application/octet-stream";

package/src/routing.test.ts

@@ -17,7 +17,7 @@
  * never touch ~/.parachute.
  */
 
-import { describe, test, expect, beforeEach, afterEach, afterAll } from "bun:test";
+import { describe, test, expect, beforeAll, beforeEach, afterEach, afterAll } from "bun:test";
 import { rmSync, existsSync, mkdirSync, writeFileSync } from "fs";
 import { join } from "path";
 import { tmpdir } from "os";
@@ -606,6 +606,24 @@ describe("MCP 401 WWW-Authenticate challenge (RFC 9728)", () => {
 
 const HUB_ORIGIN = "http://127.0.0.1:1939";
 
+// Process-env isolation: sibling test files (tokens-routes.test.ts,
+// auth-hub-jwt.test.ts) set PARACHUTE_HUB_ORIGIN in their own beforeAll
+// hooks. Bun's test runner shares a single process across test files,
+// and when file-ordering puts those before this one, their hook-set
+// value can still be live when our tests run. Restore the default
+// (unset) here so we test against `DEFAULT_HUB_LOOPBACK`. Caught when
+// vault rc.1 release CI failed with "Received: http://127.0.0.1:34295"
+// — a leaked ephemeral port from another test's fixture.
+let _prevHubOriginRouting: string | undefined;
+beforeAll(() => {
+  _prevHubOriginRouting = process.env.PARACHUTE_HUB_ORIGIN;
+  delete process.env.PARACHUTE_HUB_ORIGIN;
+});
+afterAll(() => {
+  if (_prevHubOriginRouting === undefined) delete process.env.PARACHUTE_HUB_ORIGIN;
+  else process.env.PARACHUTE_HUB_ORIGIN = _prevHubOriginRouting;
+});
+
 describe("per-vault OAuth discovery (hub-rooted after workstream E)", () => {
   test("AS metadata names the hub as issuer + endpoints", async () => {
     createVault("journal");
@@ -1804,3 +1822,76 @@ describe("/vault/<name>/.parachute/mirror — auth + dispatch", () => {
     expect([405, 503]).toContain(res.status);
   });
 });
+
+// ---------------------------------------------------------------------------
+// /vault/<name>/.parachute/mirror/run-now — manual-trigger endpoint added
+// alongside the SPA UI. Tests pin the auth gate matches the parent
+// endpoint; handler-shape coverage lives in mirror-routes.test.ts.
+// ---------------------------------------------------------------------------
+
+describe("/vault/<name>/.parachute/mirror/run-now — auth + dispatch", () => {
+  test("unauthenticated → 401", async () => {
+    createVault("journal");
+    const p = "/vault/journal/.parachute/mirror/run-now";
+    const res = await route(
+      new Request(`http://localhost:1940${p}`, { method: "POST" }),
+      p,
+    );
+    expect(res.status).toBe(401);
+  });
+
+  test("vault:read token → 403 insufficient_scope", async () => {
+    createVault("journal");
+    const store = getVaultStore("journal");
+    const { fullToken } = generateToken();
+    createToken(store.db, fullToken, {
+      label: "reader",
+      permission: "read",
+      scopes: ["vault:read"],
+    });
+    const p = "/vault/journal/.parachute/mirror/run-now";
+    const res = await route(
+      new Request(`http://localhost:1940${p}`, {
+        method: "POST",
+        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 — 503 when manager not wired, 400 when wired+disabled", async () => {
+    // Mirrors the parent endpoint's harness behavior: test ordering
+    // determines whether a previous test wired a manager. Either way
+    // the auth gate passed, which is what this routing-level test pins.
+    createVault("journal");
+    const token = createAdminToken("journal");
+    const p = "/vault/journal/.parachute/mirror/run-now";
+    const res = await route(
+      new Request(`http://localhost:1940${p}`, {
+        method: "POST",
+        headers: { authorization: `Bearer ${token}` },
+      }),
+      p,
+    );
+    expect([400, 503]).toContain(res.status);
+  });
+
+  test("non-POST methods return 405 when manager is wired", async () => {
+    createVault("journal");
+    const token = createAdminToken("journal");
+    const p = "/vault/journal/.parachute/mirror/run-now";
+    const res = await route(
+      new Request(`http://localhost:1940${p}`, {
+        method: "GET",
+        headers: { authorization: `Bearer ${token}` },
+      }),
+      p,
+    );
+    // 503 short-circuits the method check when no manager is wired.
+    expect([405, 503]).toContain(res.status);
+  });
+});

package/src/routing.ts

@@ -72,7 +72,21 @@ import {
 } from "./oauth-discovery.ts";
 import { handleConfigSchema, handleConfig } from "./module-config.ts";
 import { buildAuthStatus } from "./auth-status.ts";
-import { handleMirrorGet, handleMirrorPut } from "./mirror-routes.ts";
+import {
+  handleAuthDelete,
+  handleAuthGet,
+  handleAuthGithubCreateRepo,
+  handleAuthGithubDeviceCode,
+  handleAuthGithubPoll,
+  handleAuthGithubRepos,
+  handleAuthGithubSelectRepo,
+  handleAuthPat,
+  handleMirrorGet,
+  handleMirrorImport,
+  handleMirrorPushNow,
+  handleMirrorPut,
+  handleMirrorRunNow,
+} from "./mirror-routes.ts";
 import { getMirrorManager } from "./mirror-registry.ts";
 
 /**
@@ -424,7 +438,15 @@ export async function route(
 
   // MCP (per-vault, single-vault session).
   if (isScopedMcp) {
-    return handleScopedMcp(req, vaultName, auth);
+    // Thread the RAW caller bearer (the exact credential the session
+    // presented) into the MCP layer so the manage-token tool can forward it
+    // to hub's mint-token attenuation proxy (vault#403, MGT). Only the raw
+    // validated bearer — never a fabricated one. extractApiKey returns the
+    // same value `authenticateVaultRequest` validated above; non-forwardable
+    // credentials (env-var secret, legacy pvt_*) are handled by manage-token
+    // itself (it only forwards JWT-shaped bearers).
+    const callerBearer = extractApiKey(req);
+    return handleScopedMcp(req, vaultName, auth, callerBearer);
   }
 
   // Bare `/vault/<name>` — single-vault root. Returns name, description,
@@ -467,15 +489,13 @@ export async function route(
     return handleTokens(req, store, vaultName, auth.scopes, auth.scoped_tags, tokensMatch[1] ?? "");
   }
 
-  // /.parachute/mirror — vault-sync Phase A1. Admin-gated read+write of
-  // the persistent mirror config + runtime status. Lives under
-  // `.parachute/` (alongside info/icon/config) rather than `admin/`
-  // because `/vault/<name>/admin/*` is reserved for the admin SPA's
-  // static-file mount; the API surface goes under `.parachute/` by the
-  // module-protocol convention. Per the design doc, the hub admin SPA
-  // (Phase A2 — future PR) is the eventual primary consumer; for Phase
-  // A1 these endpoints unblock direct API callers and the by-hand
-  // config workflow.
+  // /.parachute/mirror — Admin-gated read+write of THIS vault's persistent
+  // mirror config + runtime status. Per-vault (vault#400): the manager is
+  // resolved by the URL's vault name, so each vault's mirror page reflects
+  // its own config + git remote. Lives under `.parachute/` (alongside
+  // info/icon/config) rather than `admin/` because `/vault/<name>/admin/*`
+  // is reserved for the admin SPA's static-file mount; the API surface goes
+  // under `.parachute/` by the module-protocol convention.
   if (subpath === "/.parachute/mirror") {
     if (!hasScopeForVault(auth.scopes, vaultName, "admin")) {
       return Response.json(
@@ -489,19 +509,22 @@ export async function route(
         { status: 403 },
       );
     }
-    const manager = getMirrorManager();
+    // vault#400: resolve the manager for THIS vault (from the URL). The
+    // registry lazily builds one (via the boot-installed factory) for any
+    // existing vault — including a non-default vault or one configured at
+    // runtime — so the handler operates on the right vault's config + status
+    // + git remote, never the default vault's.
+    const manager = getMirrorManager(vaultName);
     if (!manager) {
-      // The boot path constructs a manager when at least one vault
-      // exists; a missing manager here means either a startup error or
-      // a brand-new deploy that hasn't finished first-boot. Surface a
-      // clear 503 rather than a JSON null so the operator + the hub
-      // SPA know it's a service-state issue, not a misconfig on their
-      // end.
+      // Null only when boot hasn't installed the factory yet (startup race
+      // or boot failure). Surface a clear 503 rather than a JSON null so the
+      // operator + the hub SPA know it's a service-state issue, not a
+      // misconfig on their end.
       return Response.json(
         {
           error: "Mirror manager not initialized",
           message:
-            "The vault server hasn't wired a mirror manager yet (no vaults exist, or boot failed). Check logs for [mirror] entries.",
+            "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 },
       );
@@ -511,6 +534,156 @@ export async function route(
     return Response.json({ error: "Method not allowed" }, { status: 405 });
   }
 
+  // /.parachute/mirror/run-now — fire a one-shot export+commit+push pass.
+  // Same admin gate as the GET/PUT above; same manager presence check.
+  // POST-only — a GET would imply "read the result of running" which
+  // isn't the verb (the rolling status is already available on the
+  // parent GET endpoint).
+  if (subpath === "/.parachute/mirror/run-now") {
+    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 === "POST") return handleMirrorRunNow(manager);
+    return Response.json({ error: "Method not allowed" }, { status: 405 });
+  }
+
+  // /.parachute/mirror/push-now — fire `git push` against committed state.
+  // Cut 6 of vault#392. Same admin gate + manager check as run-now;
+  // POST-only. Distinguished from /run-now in that this skips export +
+  // commit, only pushes — for "did my credentials actually work?" flow.
+  if (subpath === "/.parachute/mirror/push-now") {
+    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 === "POST") return handleMirrorPushNow(manager);
+    return Response.json({ error: "Method not allowed" }, { status: 405 });
+  }
+
+  // /.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
+  // request/response shape + error map. Symmetric counterpart to the
+  // export-to-git flow vault#382 + vault#384 shipped.
+  if (subpath === "/.parachute/mirror/import") {
+    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 },
+      );
+    }
+    if (req.method !== "POST") {
+      return Response.json({ error: "Method not allowed" }, { status: 405 });
+    }
+    return handleMirrorImport(req, vaultName);
+  }
+
+  // /.parachute/mirror/auth/* — UI-configurable git push credentials.
+  // GitHub OAuth Device Flow + PAT fallback. All admin-gated; the
+  // routes themselves don't carry secrets in their responses
+  // (mirror-routes.ts redacts via sanitizeCredentials).
+  if (subpath.startsWith("/.parachute/mirror/auth")) {
+    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 (subpath === "/.parachute/mirror/auth") {
+      if (req.method === "GET") return handleAuthGet(manager);
+      if (req.method === "DELETE") return handleAuthDelete(manager);
+      return Response.json({ error: "Method not allowed" }, { status: 405 });
+    }
+    if (subpath === "/.parachute/mirror/auth/github/device-code") {
+      if (req.method === "POST") return handleAuthGithubDeviceCode();
+      return Response.json({ error: "Method not allowed" }, { status: 405 });
+    }
+    if (subpath === "/.parachute/mirror/auth/github/poll") {
+      if (req.method === "POST") return handleAuthGithubPoll(req, manager);
+      return Response.json({ error: "Method not allowed" }, { status: 405 });
+    }
+    if (subpath === "/.parachute/mirror/auth/github/repos") {
+      if (req.method === "GET") return handleAuthGithubRepos(manager);
+      return Response.json({ error: "Method not allowed" }, { status: 405 });
+    }
+    if (subpath === "/.parachute/mirror/auth/github/create-repo") {
+      if (req.method === "POST") return handleAuthGithubCreateRepo(req, manager);
+      return Response.json({ error: "Method not allowed" }, { status: 405 });
+    }
+    if (subpath === "/.parachute/mirror/auth/github/select-repo") {
+      if (req.method === "POST") return handleAuthGithubSelectRepo(req, manager);
+      return Response.json({ error: "Method not allowed" }, { status: 405 });
+    }
+    if (subpath === "/.parachute/mirror/auth/pat") {
+      if (req.method === "POST") return handleAuthPat(req, manager);
+      return Response.json({ error: "Method not allowed" }, { status: 405 });
+    }
+    return Response.json({ error: "Not found" }, { status: 404 });
+  }
+
   const apiMatch = subpath.match(/^\/api(\/.*)?$/);
   if (!apiMatch) {
     return Response.json({ error: "Not found" }, { status: 404 });
@@ -558,7 +731,7 @@ export async function route(
     });
   }
   if (apiPath === "/unresolved-wikilinks") return handleUnresolvedWikilinks(req, store);
-  if (apiPath.startsWith("/storage")) return handleStorage(req, apiPath.slice(8), vaultName);
+  if (apiPath.startsWith("/storage")) return handleStorage(req, apiPath.slice(8), vaultName, store, tagScope);
   if (apiPath === "/health") return Response.json({ status: "ok", vault: vaultName });
 
   return Response.json({ error: "Not found" }, { status: 404 });

package/src/server.ts

@@ -31,8 +31,19 @@ import { getCachedScribeUrl } from "./scribe-discovery.ts";
 import { readEnvFile, setEnvVar } from "./config.ts";
 import { resolveBindHostname } from "./bind.ts";
 import { MirrorManager } from "./mirror-manager.ts";
-import { setMirrorManager } from "./mirror-registry.ts";
+import {
+  setMirrorManager,
+  setMirrorManagerFactory,
+  listMirrorManagers,
+} from "./mirror-registry.ts";
 import { buildMirrorDeps, resolveMirrorVaultName } from "./mirror-deps.ts";
+import { migrateLegacyServerWideCredentials } from "./mirror-credentials.ts";
+import {
+  commentOutLegacyMirrorBlockFile,
+  migrateLegacyServerWideConfig,
+  readMirrorConfigForVault,
+} from "./mirror-config.ts";
+import { GLOBAL_CONFIG_PATH } from "./config.ts";
 import { selfRegister } from "./self-register.ts";
 import pkg from "../package.json" with { type: "json" };
 
@@ -231,47 +242,96 @@ const port = parseInt(process.env.PORT ?? "") || globalConfig.port || DEFAULT_PO
 const hostname = resolveBindHostname();
 
 // ---------------------------------------------------------------------------
-// Mirror lifecycle (vault-sync Phase A1).
+// Mirror lifecycle — per-vault (vault#400).
 //
-// Boot-time bootstrap of the persistent mirror manager. Only stands up an
-// active mirror when global config carries `mirror.enabled: true`; otherwise
-// the manager construct + status reflects "disabled" but no filesystem work
-// happens. The HTTP `/admin/mirror` routes can still flip it on at runtime
-// without a vault restart — see routing.ts + mirror-routes.ts.
+// Before vault#400 the server stood up a SINGLE mirror manager bound to the
+// mirror-owning vault (default/first), and every mirror route resolved to it
+// — so every vault's mirror page showed the default vault's config + git
+// remote. Now each vault gets its OWN config (`data/<vault>/mirror-config.yaml`)
+// + its OWN manager. Boot:
 //
-// Failure here is logged and ignored; vault keeps serving. The operator
-// sees the error via `GET /admin/mirror` + the log line.
+//   1. Migrate the legacy SERVER-WIDE credentials file (vault#399) + the
+//      legacy server-wide `mirror:` config block (vault#400) to the
+//      mirror-owning vault (default/first). Other vaults start unconfigured.
+//   2. Install the lazy-build factory so routes can stand up a manager for
+//      any vault on first request (handles a vault configured at runtime
+//      without a restart).
+//   3. Iterate ALL vaults; for each whose per-vault config has
+//      `enabled: true`, build + register + start its manager. Per-vault
+//      failure is logged + isolated — one vault's mirror error never breaks
+//      another vault's mirror or the vault server's serving path.
 // ---------------------------------------------------------------------------
-let mirrorManager: MirrorManager | null = null;
 {
-  // Canonicalized in `mirror-deps.ts:resolveMirrorVaultName` so the
-  // binding rule (default_vault → first listed vault → null) lives in
-  // exactly one place; multi-vault-mirror work (design-doc open
-  // question 2) only has to touch one site.
+  // Canonicalized in `mirror-deps.ts:resolveMirrorVaultName` — the binding
+  // rule (default_vault → first listed vault → null) lives in exactly one
+  // place. Post-vault#400 it's only used for migration attribution.
   const mirrorVaultName = resolveMirrorVaultName(listVaults);
-  if (mirrorVaultName) {
+
+  // vault#399: migrate the legacy SERVER-WIDE credentials file to the
+  // per-vault layout, attributed to the mirror-owning vault. Idempotent +
+  // safe (no-op when no legacy file / already migrated; legacy file renamed
+  // `.bak`, never deleted). Runs even with no vaults (no-op).
+  try {
+    migrateLegacyServerWideCredentials(mirrorVaultName);
+  } catch (err) {
+    console.warn(
+      `[mirror] legacy credential migration failed (non-fatal): ${(err as Error).message ?? err}`,
+    );
+  }
+
+  // vault#400: migrate the legacy server-wide `mirror:` CONFIG block from
+  // config.yaml to the mirror-owning vault's per-vault config file. The
+  // legacy block is commented out in place (preserved for reference), never
+  // silently dropped. Idempotent: no-op when no block / target already
+  // configured. (#399 already moved credentials — we do NOT re-migrate them.)
+  try {
+    migrateLegacyServerWideConfig(
+      readGlobalConfig().mirror,
+      mirrorVaultName,
+      () => commentOutLegacyMirrorBlockFile(GLOBAL_CONFIG_PATH),
+    );
+  } catch (err) {
+    console.warn(
+      `[mirror] legacy config migration failed (non-fatal): ${(err as Error).message ?? err}`,
+    );
+  }
+
+  // Install the lazy-build factory so routes can stand up a per-vault manager
+  // on demand (a vault configured at runtime works without a restart).
+  setMirrorManagerFactory((name) => new MirrorManager(buildMirrorDeps(name)));
+
+  // Stand up every vault whose per-vault config is enabled. Don't block
+  // server startup on slow initial exports — kick each off in the background.
+  const vaults = listVaults();
+  if (vaults.length === 0) {
+    console.log("[mirror] no vaults yet — managers stand up on next restart after a vault exists");
+  }
+  for (const name of vaults) {
+    let cfg;
+    try {
+      cfg = readMirrorConfigForVault(name);
+    } catch (err) {
+      console.warn(`[mirror] could not read config for vault "${name}" (skipping): ${(err as Error).message ?? err}`);
+      continue;
+    }
+    if (!cfg?.enabled) continue; // unconfigured / disabled → no manager work
     try {
-      mirrorManager = new MirrorManager(buildMirrorDeps(mirrorVaultName));
-      setMirrorManager(mirrorManager);
-      // Don't block server startup on a slow initial export — kick it off
-      // in the background, log the outcome. The HTTP server comes up
-      // immediately so OAuth + REST aren't blocked behind a multi-second
-      // export pass.
-      void mirrorManager
+      const mgr = new MirrorManager(buildMirrorDeps(name));
+      setMirrorManager(name, mgr);
+      void mgr
         .start()
         .then((status) => {
           if (!status.enabled && status.last_error) {
-            console.warn(`[mirror] startup error: ${status.last_error}`);
+            console.warn(`[mirror] vault "${name}" startup error: ${status.last_error}`);
           }
         })
         .catch((err) => {
-          console.warn(`[mirror] startup threw: ${(err as Error).message ?? err}`);
+          console.warn(`[mirror] vault "${name}" startup threw: ${(err as Error).message ?? err}`);
         });
     } catch (err) {
-      console.warn(`[mirror] manager construction failed: ${(err as Error).message ?? err}`);
+      // Isolated per-vault: one vault's failure never touches others.
+      console.warn(`[mirror] vault "${name}" manager construction failed: ${(err as Error).message ?? err}`);
     }
-  } else {
-    console.log("[mirror] no vaults yet — manager will be initialized on next restart after a vault exists");
   }
 }
 
@@ -315,18 +375,39 @@ const server = Bun.serve({
 console.log(`Parachute Vault server listening on http://${hostname}:${server.port}`);
 
 // Graceful shutdown — best-effort drain of in-flight note-mutation hooks.
+//
+// Order matters under the event-driven mirror shape (vault#382):
+//   1. Every MirrorManager.stop() runs FIRST (vault#400: drain ALL per-vault
+//      managers, not just one) so they unsubscribe from hooks cleanly +
+//      cancel their debounce timers. Otherwise the registry drain below
+//      would wait on a manager's hook handler that just queued itself after
+//      a final mutation.
+//   2. Then drain hooks + stop the transcription worker in parallel —
+//      neither depends on the other.
+//
+// The whole thing races a 5s timeout so a stuck handler doesn't hang
+// shutdown indefinitely.
 async function shutdown(signal: string): Promise<void> {
   console.log(`\n[${signal}] shutting down; in-flight hooks: ${defaultHookRegistry.inFlightCount}`);
   try {
     await Promise.race([
-      Promise.all([
-        defaultHookRegistry.drain(),
-        transcriptionWorker?.stop() ?? Promise.resolve(),
-        // Mirror manager: cancel the watch interval + let any in-flight
-        // export cycle settle. `stop` already has its own brief timeout
-        // (250ms) so this doesn't block the larger shutdown race.
-        mirrorManager?.stop() ?? Promise.resolve(),
-      ]),
+      (async () => {
+        // Mirror stop first — unsubscribes + cancels each debounce. Each
+        // manager's internal soft-settle timeout (250ms) bounds the wait;
+        // drain them in parallel so total shutdown stays bounded.
+        await Promise.all(
+          listMirrorManagers().map((m) =>
+            m.stop().catch((err) =>
+              console.warn(`[mirror] stop threw during shutdown (non-fatal): ${(err as Error).message ?? err}`),
+            ),
+          ),
+        );
+        // Then drain hooks + stop the transcription worker in parallel.
+        await Promise.all([
+          defaultHookRegistry.drain(),
+          transcriptionWorker?.stop() ?? Promise.resolve(),
+        ]);
+      })(),
       new Promise<void>((resolve) => setTimeout(resolve, 5000)),
     ]);
   } catch (err) {