@openparachute/vault 0.6.0-rc.1 → 0.6.1

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

package/src/auth-hub-jwt.test.ts

@@ -143,6 +143,7 @@ function bearer(token: string): Request {
 let tmpHome: string;
 let prevHome: string | undefined;
 let prevHubOrigin: string | undefined;
+let prevJwksOrigin: string | undefined;
 let fixture: HubFixture;
 let kp: Keypair;
 
@@ -159,7 +160,11 @@ beforeEach(async () => {
   kp = await makeKeypair("k1");
   fixture = startHubFixture([kp]);
   prevHubOrigin = process.env.PARACHUTE_HUB_ORIGIN;
+  prevJwksOrigin = process.env.PARACHUTE_HUB_JWKS_ORIGIN;
   process.env.PARACHUTE_HUB_ORIGIN = fixture.origin;
+  // Post-vault#464 the JWKS fetch origin resolves separately (loopback by
+  // default); point it at the fixture so keys are reachable in-test.
+  process.env.PARACHUTE_HUB_JWKS_ORIGIN = fixture.origin;
   resetJwksCache();
   resetRevocationCache();
 });
@@ -171,6 +176,8 @@ afterEach(() => {
   else process.env.PARACHUTE_HOME = prevHome;
   if (prevHubOrigin === undefined) delete process.env.PARACHUTE_HUB_ORIGIN;
   else process.env.PARACHUTE_HUB_ORIGIN = prevHubOrigin;
+  if (prevJwksOrigin === undefined) delete process.env.PARACHUTE_HUB_JWKS_ORIGIN;
+  else process.env.PARACHUTE_HUB_JWKS_ORIGIN = prevJwksOrigin;
   if (existsSync(tmpHome)) rmSync(tmpHome, { recursive: true, force: true });
 });
 
@@ -668,7 +675,7 @@ describe("authenticateVaultRequest — hub JWT tag-scoping (auth-unification C0)
 
 // ---------------------------------------------------------------------------
 // pvt_* DROP (vault#282 Stage 2 — BREAKING). pvt_* tokens were the only
-// non-JWT, non-YAML credential vault used to mint + validate. At 0.6.0 the
+// non-JWT, non-YAML credential vault used to mint + validate. At 0.5.0 the
 // mint + validation were removed entirely: a pvt_*-prefixed bearer is no
 // longer JWT-shaped (skips authenticateHubJwt) and matches no surviving
 // credential, so it 401s. The hub JWT — the migration target — keeps working.

package/src/auth-status.ts

@@ -8,7 +8,7 @@
  *
  * What gets exposed:
  *   - `initialized` — at least one vault exists
- *   - `auth_modes`  — accepted bearer formats. As of 0.6.0 (vault#282 Stage 2)
+ *   - `auth_modes`  — accepted bearer formats. As of 0.5.0 (vault#282 Stage 2)
  *     vault is a pure hub resource-server: the only first-class user
  *     credential is a hub-issued JWT, so this is `["hub_jwt"]`. (The
  *     server-wide VAULT_AUTH_TOKEN operator bearer + legacy YAML api_keys
@@ -17,7 +17,7 @@
  *   - `vaults`      — list of `{ name, url }` for client-side dispatch
  *   - `hasOwnerPassword`, `hasTotp` — OAuth consent prerequisites
  *   - `hasTokens`   — boolean | null. Probes the vestigial `tokens` table for
- *     any leftover pre-0.6.0 rows (the table is kept inert as the YAML-import
+ *     any leftover pre-0.5.0 rows (the table is kept inert as the YAML-import
  *     landing zone + a future-cosmetic-drop target). `null` ≈ "we couldn't
  *     read all DBs, don't trust this answer"; `true`/`false` are honest yes/no.
  *

package/src/auth.test.ts

@@ -1,7 +1,7 @@
 /**
  * Auth invariants — vault as a pure hub resource-server (vault#282 Stage 2).
  *
- * The `pvt_*` opaque vault-DB token was dropped at 0.6.0: vault no longer
+ * The `pvt_*` opaque vault-DB token was dropped at 0.5.0: vault no longer
  * mints or validates it. The surviving auth surfaces tested here are:
  *   - VAULT_AUTH_TOKEN — the server-wide operator bearer.
  *   - Legacy YAML api_keys (vault.yaml / config.yaml) — hashed keys.
@@ -26,7 +26,8 @@ import {
   hashKey,
 } from "./config.ts";
 import { getVaultStore, clearVaultStoreCache } from "./vault-store.ts";
-import { authenticateVaultRequest, authenticateGlobalRequest } from "./auth.ts";
+import { authenticateVaultRequest, authenticateGlobalRequest, warnLegacyGlobalApiKeys } from "./auth.ts";
+import type { StoredKey } from "./config.ts";
 
 let tmpHome: string;
 let prevHome: string | undefined;
@@ -91,7 +92,7 @@ describe("auth — pvt_* tokens are unvalidatable (fail closed)", () => {
   // API key" a non-pvt_ bad token gets) — the prefix is the user-meaningful
   // signal that the mechanism was dropped, not that the key was mistyped.
   const PVT_MESSAGE =
-    "pvt_* tokens are no longer supported (vault 0.6.0). Re-add this vault via your hub to get an access token.";
+    "pvt_* tokens are no longer supported (vault 0.5.0). Re-add this vault via your hub to get an access token.";
 
   test("a pvt_* bearer is 401-rejected with the dropped-token message on the per-vault surface", async () => {
     seedVault("journal");
@@ -442,3 +443,38 @@ describe("auth — VAULT_AUTH_TOKEN server-wide operator bearer", () => {
     expect("error" in result).toBe(true);
   });
 });
+
+// ---------------------------------------------------------------------------
+// Legacy GLOBAL api_keys boot warning (security review — multi-user
+// hardening). Cross-vault credentials in config.yaml must be surfaced loudly
+// at boot, but never altered. Pure-function unit tests (no server boot).
+// ---------------------------------------------------------------------------
+describe("warnLegacyGlobalApiKeys (legacy cross-vault key boot warning)", () => {
+  function key(id: string): StoredKey {
+    return {
+      id,
+      label: id,
+      key_hash: `sha256:${id}`,
+      scope: "full",
+      created_at: new Date().toISOString(),
+    };
+  }
+
+  test("warns when global api_keys are present", () => {
+    const msgs: string[] = [];
+    const count = warnLegacyGlobalApiKeys([key("a"), key("b")], (m) => msgs.push(m));
+    expect(count).toBe(2);
+    expect(msgs).toHaveLength(1);
+    expect(msgs[0]).toContain("legacy GLOBAL api_key");
+    expect(msgs[0]).toContain("CROSS-VAULT");
+    // Heads-up only — must signal it does NOT alter the keys.
+    expect(msgs[0]).toContain("remain active");
+  });
+
+  test("silent when there are no global api_keys", () => {
+    const msgs: string[] = [];
+    expect(warnLegacyGlobalApiKeys([], (m) => msgs.push(m))).toBe(0);
+    expect(warnLegacyGlobalApiKeys(undefined, (m) => msgs.push(m))).toBe(0);
+    expect(msgs).toHaveLength(0);
+  });
+});

package/src/auth.ts

@@ -1,7 +1,7 @@
 /**
  * Authentication and authorization for the vault server.
  *
- * As of 0.6.0 vault is a PURE HUB RESOURCE-SERVER (vault#282 Stage 2). The
+ * As of 0.5.0 vault is a PURE HUB RESOURCE-SERVER (vault#282 Stage 2). The
  * opaque `pvt_*` vault-DB token was dropped — vault no longer mints or
  * validates it. Three auth paths survive:
  *
@@ -171,6 +171,35 @@ export function warnLegacyOnce(cacheKey: string, context: string): void {
   );
 }
 
+/**
+ * Boot-time warning for legacy GLOBAL `api_keys` in `config.yaml` (security
+ * review — multi-user hardening). Those keys are CROSS-VAULT credentials: a
+ * single key authenticates against EVERY vault on this server (see the global
+ * `api_keys` branch in `authenticate` ~L283). That predates per-vault keys +
+ * tag-scoped hub JWTs and is a confidentiality hazard once a server hosts
+ * multiple users' vaults — one user's global key reads another's vault.
+ *
+ * WARNING ONLY — never touches the keys (the operator owns them). The
+ * verification flagged 6 such keys on the live box; this surfaces them at
+ * boot so they're rotated/removed before multi-user sharing. Returns the
+ * count it warned about (0 = silent) so callers / tests can assert.
+ */
+export function warnLegacyGlobalApiKeys(
+  globalApiKeys: StoredKey[] | undefined,
+  warn: (msg: string) => void = console.warn,
+): number {
+  const count = globalApiKeys?.length ?? 0;
+  if (count === 0) return 0;
+  warn(
+    `[auth] WARNING: ${count} legacy GLOBAL api_key(s) found in config.yaml. ` +
+      "These are CROSS-VAULT credentials (each grants access to every vault on this server) " +
+      "and predate per-vault keys + tag-scoped hub JWTs. Before multi-user sharing, ROTATE or " +
+      "REMOVE them — a global key leaks one user's vault to another. They remain active (the " +
+      "operator owns them); this is a heads-up, not an automatic change.",
+  );
+  return count;
+}
+
 /** Read-only tools (the only tools allowed for "read" permission). */
 const READ_TOOLS = new Set([
   "query-notes",
@@ -310,7 +339,7 @@ function droppedPvtTokenResponse(): Response {
     {
       error: "Unauthorized",
       message:
-        "pvt_* tokens are no longer supported (vault 0.6.0). Re-add this vault via your hub to get an access token.",
+        "pvt_* tokens are no longer supported (vault 0.5.0). Re-add this vault via your hub to get an access token.",
     },
     { status: 401 },
   );

package/src/auto-transcribe.test.ts

@@ -118,4 +118,55 @@ describe("shouldAutoTranscribe", () => {
       enabledOverride: false,
     })).toBe(false);
   });
+
+  describe("per-vault precedence (per-vault → global → true)", () => {
+    test("per-vault true wins even when global is false", () => {
+      expect(shouldAutoTranscribe("audio/wav", {
+        readGlobalConfigImpl: readGlobalConfig(false),
+        getCachedScribeUrlImpl: scribePresent,
+        perVaultEnabled: true,
+      })).toBe(true);
+    });
+
+    test("per-vault false wins even when global is true", () => {
+      // The whole point: linking scribe to vault X (perVault true) elsewhere
+      // must not force-on a vault that set its own false.
+      expect(shouldAutoTranscribe("audio/wav", {
+        readGlobalConfigImpl: readGlobalConfig(true),
+        getCachedScribeUrlImpl: scribePresent,
+        perVaultEnabled: false,
+      })).toBe(false);
+    });
+
+    test("per-vault unset falls back to global", () => {
+      expect(shouldAutoTranscribe("audio/wav", {
+        readGlobalConfigImpl: readGlobalConfig(true),
+        getCachedScribeUrlImpl: scribePresent,
+        perVaultEnabled: undefined,
+      })).toBe(true);
+      expect(shouldAutoTranscribe("audio/wav", {
+        readGlobalConfigImpl: readGlobalConfig(false),
+        getCachedScribeUrlImpl: scribePresent,
+        perVaultEnabled: undefined,
+      })).toBe(false);
+    });
+
+    test("both per-vault and global unset falls back to true (no regression)", () => {
+      expect(shouldAutoTranscribe("audio/wav", {
+        readGlobalConfigImpl: readGlobalConfig(undefined),
+        getCachedScribeUrlImpl: scribePresent,
+        perVaultEnabled: undefined,
+      })).toBe(true);
+    });
+
+    test("enabledOverride still hard-overrides the per-vault value", () => {
+      // The explicit caller-opt-in path beats everything.
+      expect(shouldAutoTranscribe("audio/wav", {
+        readGlobalConfigImpl: readGlobalConfig(true),
+        getCachedScribeUrlImpl: scribePresent,
+        perVaultEnabled: false,
+        enabledOverride: true,
+      })).toBe(true);
+    });
+  });
 });

package/src/auto-transcribe.ts

@@ -19,11 +19,18 @@ import { getCachedScribeUrl } from "./scribe-discovery.ts";
  *
  * Returns `true` only when ALL three conditions hold:
  *   1. mime-type starts with `audio/` (case-insensitive).
- *   2. `globalConfig.auto_transcribe?.enabled` is not explicitly false.
- *      Default behavior (when unset) is ON — once an operator has scribe
- *      reachable, audio attachments transcribe automatically without a
- *      separate config step. Operators who want it OFF set
- *      `auto_transcribe.enabled: false` explicitly.
+ *   2. The resolved auto-transcribe toggle is not `false`. Resolution is
+ *      **per-vault → global → true**:
+ *        - `perVaultEnabled` (the owning vault's own `auto_transcribe.enabled`)
+ *          wins when set — this is what makes scribe's "link to vault X" affect
+ *          only X, not the whole server.
+ *        - else the server-wide `globalConfig.auto_transcribe?.enabled`.
+ *        - else `true` (default ON — once scribe is reachable, audio
+ *          transcribes without a separate config step). Operators who want it
+ *          OFF set `auto_transcribe.enabled: false` explicitly (per-vault or
+ *          globally).
+ *      `enabledOverride`, when present, hard-overrides the whole chain (used
+ *      by the explicit caller-opt-in path).
  *   3. Scribe is discoverable (services.json entry OR SCRIBE_URL env).
  *
  * The three conditions are independent guards: a single `false` is sufficient
@@ -35,7 +42,17 @@ export function shouldAutoTranscribe(
     /** Injection seam for tests — defaults to live globals. */
     readGlobalConfigImpl?: typeof readGlobalConfig;
     getCachedScribeUrlImpl?: () => string | undefined;
-    /** Allow per-call enabled override — used by the explicit-opt-in path. */
+    /**
+     * The owning vault's per-vault `auto_transcribe.enabled` (vault.yaml).
+     * Takes precedence over the global toggle when set, so enabling/disabling
+     * one vault doesn't move the rest. `undefined` (the vault left it unset)
+     * falls through to the global toggle.
+     */
+    perVaultEnabled?: boolean;
+    /**
+     * Hard override of the entire per-vault→global→true chain. Used by the
+     * explicit caller-opt-in path; not part of the normal precedence ladder.
+     */
     enabledOverride?: boolean;
   } = {},
 ): boolean {
@@ -43,6 +60,7 @@ export function shouldAutoTranscribe(
     return false;
   }
   const enabled = opts.enabledOverride
+    ?? opts.perVaultEnabled
     ?? (opts.readGlobalConfigImpl ?? readGlobalConfig)().auto_transcribe?.enabled
     ?? true;
   if (!enabled) return false;

package/src/autostart.test.ts

@@ -0,0 +1,75 @@
+import { describe, test, expect } from "bun:test";
+import { decideAutostart } from "./autostart.ts";
+
+/**
+ * Pure matrix for the autostart decision (ParachuteComputer/parachute-hub#580
+ * item 2). No launchd/systemd is touched — `decideAutostart` is side-effect
+ * free; the CLI consumes its result to register or skip.
+ */
+describe("decideAutostart", () => {
+  test("hub present, no flag, no persisted → default OFF (#580)", () => {
+    const d = decideAutostart({ flagOn: false, flagOff: false, persisted: undefined, hubPresent: true });
+    expect(d.enabled).toBe(false);
+    expect(d.reason).toBe("hub-default-off");
+    // Per-run inference — not persisted, so a later standalone re-run registers.
+    expect(d.persist).toBe(false);
+    expect(d.overrodeHub).toBe(false);
+  });
+
+  test("hub absent, no flag, no persisted → default ON (standalone)", () => {
+    const d = decideAutostart({ flagOn: false, flagOff: false, persisted: undefined, hubPresent: false });
+    expect(d.enabled).toBe(true);
+    expect(d.reason).toBe("default-on");
+    expect(d.persist).toBe(false);
+  });
+
+  test("explicit --autostart forces ON even under a hub (operator override + warn flag)", () => {
+    const d = decideAutostart({ flagOn: true, flagOff: false, persisted: undefined, hubPresent: true });
+    expect(d.enabled).toBe(true);
+    expect(d.reason).toBe("flag-on");
+    expect(d.persist).toBe(true);
+    expect(d.overrodeHub).toBe(true);
+  });
+
+  test("explicit --autostart with no hub does not set overrodeHub", () => {
+    const d = decideAutostart({ flagOn: true, flagOff: false, persisted: undefined, hubPresent: false });
+    expect(d.enabled).toBe(true);
+    expect(d.overrodeHub).toBe(false);
+    expect(d.persist).toBe(true);
+  });
+
+  test("explicit --no-autostart forces OFF and persists (even under a hub)", () => {
+    const d = decideAutostart({ flagOn: false, flagOff: true, persisted: undefined, hubPresent: true });
+    expect(d.enabled).toBe(false);
+    expect(d.reason).toBe("flag-off");
+    expect(d.persist).toBe(true);
+    expect(d.overrodeHub).toBe(false);
+  });
+
+  test("--no-autostart wins over --autostart on the same line (safer default)", () => {
+    const d = decideAutostart({ flagOn: true, flagOff: true, persisted: undefined, hubPresent: false });
+    expect(d.enabled).toBe(false);
+    expect(d.reason).toBe("flag-off");
+  });
+
+  test("persisted=false honored over hub-present default", () => {
+    const d = decideAutostart({ flagOn: false, flagOff: false, persisted: false, hubPresent: true });
+    expect(d.enabled).toBe(false);
+    expect(d.reason).toBe("persisted");
+    expect(d.persist).toBe(false);
+  });
+
+  test("persisted=true honored even when a hub is present (prior explicit choice)", () => {
+    const d = decideAutostart({ flagOn: false, flagOff: false, persisted: true, hubPresent: true });
+    expect(d.enabled).toBe(true);
+    expect(d.reason).toBe("persisted");
+    expect(d.persist).toBe(false);
+  });
+
+  test("flag beats persisted: --no-autostart over persisted=true", () => {
+    const d = decideAutostart({ flagOn: false, flagOff: true, persisted: true, hubPresent: false });
+    expect(d.enabled).toBe(false);
+    expect(d.reason).toBe("flag-off");
+    expect(d.persist).toBe(true);
+  });
+});