@openparachute/vault 0.4.7-rc.1 → 0.4.8-rc.4

package/src/cli.ts

@@ -103,7 +103,7 @@ import type { TokenPermission } from "./token-store.ts";
 import { resolveCreateTokenFlags, VAULT_SCOPES } from "./scopes.ts";
 import { validateVaultName, decideInitVaultName } from "./vault-name.ts";
 import { getVaultStore } from "./vault-store.ts";
-import { upsertService, ServicesManifestError } from "./services-manifest.ts";
+import { selfRegister } from "./self-register.ts";
 import {
   hasOwnerPassword,
   setOwnerPassword,
@@ -245,27 +245,6 @@ switch (command) {
 // Command implementations
 // ---------------------------------------------------------------------------
 
-/**
- * Compute the `paths` array for the parachute-vault entry in services.json.
- * One entry advertises every vault on this server; `paths[0]` is the
- * canonical mount the hub stamps into `.well-known/parachute.json`, so the
- * default vault sorts first when one is set. With no vaults yet, fall back
- * to "/" so an early-init registration is still well-formed.
- */
-function buildVaultServicePaths(
-  defaultVault: string | undefined,
-  vaults: string[],
-): string[] {
-  if (vaults.length === 0) return ["/"];
-  if (defaultVault && vaults.includes(defaultVault)) {
-    return [
-      `/vault/${defaultVault}`,
-      ...vaults.filter((v) => v !== defaultVault).map((v) => `/vault/${v}`),
-    ];
-  }
-  return vaults.map((v) => `/vault/${v}`);
-}
-
 async function cmdInit(args: string[] = []) {
   ensureConfigDirSync();
 
@@ -363,24 +342,24 @@ async function cmdInit(args: string[] = []) {
   // by name, preserving entries for other services. Non-fatal on failure —
   // init can complete without the manifest, just with a warning.
   //
+  // `selfRegister` stamps the full manifest-sourced row (displayName, tagline,
+  // stripPrefix, installDir) from `.parachute/module.json` — the same shape
+  // server boot writes via the self-registration pass (vault#266). Keeping
+  // the two write paths in lockstep means `parachute-vault init` and the
+  // first server boot agree on the row contents; without that, a re-init
+  // would silently lose the manifest fields the boot pass had added.
+  //
   // `paths[0]` is the canonical mount point — the hub uses it for the
   // `.well-known/parachute.json` URL and for `parachute expose`, so the
   // default vault always sorts first. Remaining vaults follow so the hub
   // well-known and paraclaw's attach picker see every vault on this server.
   // Re-running init re-registers the full set; that doubles as the
   // recovery path for installs whose services.json is stale (#208).
-  try {
-    upsertService({
-      name: "parachute-vault",
-      port: globalConfig.port || DEFAULT_PORT,
-      paths: buildVaultServicePaths(globalConfig.default_vault, allVaults),
-      health: "/health",
-      version: pkg.version,
-    });
-  } catch (err) {
-    const msg = err instanceof ServicesManifestError ? err.message : String(err);
-    console.error(`  Warning: could not update ~/.parachute/services.json: ${msg}`);
-  }
+  selfRegister({
+    version: pkg.version,
+    warn: (msg) => console.error(`  Warning: ${msg}`),
+    log: () => {}, // CLI init has its own status lines; suppress duplicate noise.
+  });
 
   // 2b. Migrate existing legacy keys into per-vault token tables
   for (const v of listVaults()) {
@@ -862,19 +841,16 @@ function cmdCreate(args: string[]) {
   // attach picker see this vault. cmdInit registers on first run; cmdCreate
   // adds the new path on every subsequent vault. Without this, vaults
   // created after init were invisible to the hub (#208).
-  // Warnings go to stderr to keep --json stdout clean for the orchestrator.
-  try {
-    upsertService({
-      name: "parachute-vault",
-      port: globalConfig.port || DEFAULT_PORT,
-      paths: buildVaultServicePaths(globalConfig.default_vault, listVaults()),
-      health: "/health",
-      version: pkg.version,
-    });
-  } catch (err) {
-    const msg = err instanceof ServicesManifestError ? err.message : String(err);
-    console.error(`Warning: could not update ~/.parachute/services.json: ${msg}`);
-  }
+  //
+  // Routed through `selfRegister` (vault#266) so the row carries the full
+  // manifest-sourced metadata (displayName, tagline, stripPrefix, installDir)
+  // — same shape server boot writes. Warnings go to stderr to keep --json
+  // stdout clean for the orchestrator.
+  selfRegister({
+    version: pkg.version,
+    warn: (msg) => console.error(`Warning: ${msg}`),
+    log: () => {}, // CLI create has its own status lines.
+  });
 
   if (jsonMode) {
     const payload = {
@@ -943,6 +919,11 @@ function takeArgValue(args: string[], name: string): { value?: string; missingVa
  * Targeting:
  *   --scope <verb>        vault:read | vault:write | vault:admin (default: vault:read).
  *                         For --mint, expands to vault:<vault-name>:<verb>.
+ *                         vault:admin requires --legacy-pat — hub policy makes
+ *                         per-vault admin non-requestable via mint-token (it's
+ *                         operator-only, minted only through the session-
+ *                         cookie-gated admin SPA endpoint), so --mint + admin
+ *                         is rejected pre-flight.
  *   --install-scope <s>   local (default) | user | project. local writes to
  *                         ~/.claude.json under projects[<cwd>].mcpServers
  *                         (private, this directory only — matches Claude
@@ -1331,6 +1312,28 @@ async function executeMcpInstall(opts: ExecuteMcpInstallOpts): Promise<void> {
     bearer = fullToken;
   } else {
     // mode === "mint"
+    // Pre-flight: hub policy rejects `vault:<name>:admin` via the public
+    // mint-token endpoint. Per-vault admin is operator-only, mintable
+    // only through the session-cookie-gated `/admin/vault-admin-token/:name`
+    // SPA path. Calling hub with admin would surface a 400:
+    //   "Hub mint-token rejected (HTTP 400, invalid_scope):
+    //    scope vault:default:admin is not requestable via mint-token;
+    //    use OAuth flow or operator rotation"
+    // Fail early with the actionable remediation rather than letting
+    // the operator chase the hub's wire-level error. See
+    // `parachute-hub/src/scope-explanations.ts` (VAULT_ADMIN_RE) and
+    // `parachute-hub/src/api-mint-token.ts` (non-requestable guard).
+    if (verb === "admin") {
+      console.error(
+        "Hub policy: vault:<name>:admin is not requestable via mint-token " +
+          "(per-vault admin is operator-only, minted only by the session-cookie-gated " +
+          "admin SPA at <hub>/admin/vaults/" + vaultName + ").\n" +
+          "  Fix: use `--legacy-pat --scope vault:admin` to mint a vault-DB pvt_* with admin scope " +
+          "(the right shape for an MCP entry needing schema management).\n" +
+          "  Or:  drop --scope to default to vault:read (least privilege), or use --scope vault:write.",
+      );
+      process.exit(1);
+    }
     const operatorToken = readOperatorToken();
     if (!operatorToken) {
       console.error(
@@ -2872,6 +2875,7 @@ async function cmdExport(args: string[]) {
   const { DEFAULT_COMMIT_TEMPLATE } = await import("./export-watch.ts");
   let gitMessageTemplate = DEFAULT_COMMIT_TEMPLATE;
   let gitPush = false;
+  let strictCaseCollision = false;
 
   const positional: string[] = [];
   for (let i = 0; i < args.length; i++) {
@@ -2923,6 +2927,8 @@ async function cmdExport(args: string[]) {
       gitMessageTemplate = v;
     } else if (arg === "--git-push") {
       gitPush = true;
+    } else if (arg === "--strict-case-collision") {
+      strictCaseCollision = true;
     } else {
       positional.push(arg);
     }
@@ -2952,6 +2958,12 @@ async function cmdExport(args: string[]) {
     console.error("                                {{first_note_title}}, {{vault_name}}");
     console.error("                              (default: \"export: {{date}} ({{notes_changed}} note{{plural}})\")");
     console.error("  --git-push                  After commit, run `git push` (non-fatal on failure).");
+    console.error("  --strict-case-collision     On case-insensitive filesystems (macOS APFS-default,");
+    console.error("                              Windows NTFS, FAT/exFAT), abort the export if two notes");
+    console.error("                              have paths differing only by case (vault#327).");
+    console.error("                              Without this flag, colliding notes are auto-disambiguated");
+    console.error("                              with an `__<id-short>` filename suffix (lossless; both");
+    console.error("                              files land, canonical path preserved in frontmatter).");
     process.exit(1);
   }
 
@@ -3010,6 +3022,7 @@ async function cmdExport(args: string[]) {
       assetsDir: assetsDirPath,
       ...(vaultDescription ? { vaultDescription } : {}),
       ...(opts.sinceCursor ? { since: opts.sinceCursor } : {}),
+      ...(strictCaseCollision ? { failOnCaseCollision: true } : {}),
     });
 
     if (opts.isInitial) {
@@ -3030,6 +3043,28 @@ async function cmdExport(args: string[]) {
           `Note: ${stats.skipped_attachments.length} attachment(s) skipped. See [export] warnings above.`,
         );
       }
+      // vault#327 Phase 2 — surface case-collision auto-disambiguation
+      // explicitly. The previous fix landed the logic silently; the
+      // operator had no signal that filenames had been munged. Now we
+      // print the count + every disambiguated path so the operator can
+      // (a) audit, (b) decide whether to rename a colliding note in
+      // the vault and re-export, or (c) re-run with
+      // --strict-case-collision to refuse the disambiguation entirely.
+      if (stats.disambiguated_paths.length > 0) {
+        const n = stats.disambiguated_paths.length;
+        console.warn(
+          `Warning: ${n} note${n === 1 ? "" : "s"} had path${n === 1 ? "" : "s"} that ` +
+          `differ only by case on this case-insensitive filesystem. ` +
+          `Auto-disambiguated on disk (canonical paths preserved in frontmatter):`,
+        );
+        for (const d of stats.disambiguated_paths) {
+          console.warn(`  - ${d.original_path} → ${d.disambiguated_filename} (id: ${d.note_id})`);
+        }
+        console.warn(
+          `Re-run with --strict-case-collision to abort instead, or rename one of each ` +
+          `colliding pair in the vault before re-exporting. See vault#327.`,
+        );
+      }
     } else {
       // Watch-mode status line: keep tight; the loop logs every interval.
       if (stats.notes > 0) {
@@ -3039,6 +3074,17 @@ async function cmdExport(args: string[]) {
       } else {
         console.log(`[watch] no changes`);
       }
+      // Watch-mode: log new disambiguations per cycle. Operators running
+      // a long-lived watch loop want to be notified the moment a
+      // collision shows up — they can fix it at the source without
+      // waiting for the next manual full export.
+      if (stats.disambiguated_paths.length > 0) {
+        const n = stats.disambiguated_paths.length;
+        console.warn(
+          `[watch] case-collision: ${n} disambiguated path${n === 1 ? "" : "s"} this cycle ` +
+          `(see vault#327; --strict-case-collision to abort instead).`,
+        );
+      }
     }
 
     let committed = false;
@@ -3058,15 +3104,44 @@ async function cmdExport(args: string[]) {
     return { stats, nextCursor, committed };
   }
 
+  // Import the typed CaseCollisionError once so both the single-shot and
+  // watch-initial paths can render it the same way. vault#327 Phase 2.
+  const { CaseCollisionError } = await import("../core/src/portable-md.ts");
+
   // ---- Single-shot mode ----
   if (!watch) {
-    await runCycle({ sinceCursor: since, isInitial: true });
+    try {
+      await runCycle({ sinceCursor: since, isInitial: true });
+    } catch (err) {
+      if (err instanceof CaseCollisionError) {
+        // The error's own message already includes the actionable
+        // instruction ("Rename one of them..."). Print verbatim + exit
+        // non-zero so scripts catch the failure deterministically.
+        console.error(err.message);
+        process.exit(1);
+      }
+      throw err;
+    }
     return;
   }
 
   // ---- Watch mode ----
   // Initial full (or since-filtered) export, then poll every interval.
-  const initial = await runCycle({ sinceCursor: since, isInitial: true });
+  let initial: Awaited<ReturnType<typeof runCycle>>;
+  try {
+    initial = await runCycle({ sinceCursor: since, isInitial: true });
+  } catch (err) {
+    if (err instanceof CaseCollisionError) {
+      console.error(err.message);
+      console.error(
+        "\n--strict-case-collision is enabled; refusing to start the watch loop until the " +
+        "collision is resolved in the vault. Re-export without --strict-case-collision to " +
+        "auto-disambiguate instead.",
+      );
+      process.exit(1);
+    }
+    throw err;
+  }
   let cursor = initial.nextCursor;
   console.log(`[watch] polling every ${intervalSeconds}s; press Ctrl-C to stop.`);
 
@@ -3095,6 +3170,26 @@ async function cmdExport(args: string[]) {
       const cycle = await runCycle({ sinceCursor: cursor, isInitial: false });
       cursor = cycle.nextCursor;
     } catch (err) {
+      // CaseCollisionError under --strict-case-collision means the
+      // operator opted into "abort on any collision". A new collision
+      // that appears mid-watch (e.g. an LLM client just wrote
+      // `Inbox/Foo` to a vault that already had `Inbox/foo`) must NOT
+      // be swallowed into the generic [watch] export-error log — the
+      // strict-mode guarantee would silently degrade after the initial
+      // export. Print the full collision message + actionable hint and
+      // stop the loop via the same SIGINT-style pathway used by Ctrl-C
+      // (clears timer, gives in-flight work a 250ms settle window).
+      // Exits non-zero so supervisors / git-watch sidecars catch it.
+      if (err instanceof CaseCollisionError) {
+        console.error(err.message);
+        console.error(
+          "Resolve the collision in the vault or re-run without --strict-case-collision to fall back to auto-disambiguate mode.",
+        );
+        stopping = true;
+        if (timer) clearInterval(timer);
+        setTimeout(() => process.exit(1), 0);
+        return;
+      }
       // Don't kill the loop on a transient export error — log and keep
       // polling. Operator can Ctrl-C if they want to bail.
       console.error(`[watch] export error: ${(err as Error).message ?? err}`);
@@ -3300,7 +3395,13 @@ Vaults:
                                             (any shape) instead of minting.
                                             --legacy-pat: mint a vault-DB pvt_*
                                             token (deprecated; for self-hosted-
-                                            without-hub setups).
+                                            without-hub setups). Also the only
+                                            path for --scope vault:admin — hub
+                                            policy reserves per-vault admin for
+                                            operator-only minting (the admin SPA
+                                            session-cookie path), so --mint
+                                            --scope vault:admin is rejected
+                                            pre-flight.
                                             --install-scope local (default) writes
                                             ~/.claude.json under
                                             projects[<cwd>].mcpServers (this

package/src/config.test.ts

@@ -1,9 +1,12 @@
 import { describe, test, expect } from "bun:test";
+import { statSync } from "fs";
+import { join } from "path";
 import {
   writeVaultConfig,
   readVaultConfig,
   writeGlobalConfig,
   readGlobalConfig,
+  writeEnvFile,
   generateApiKey,
   hashKey,
   verifyKey,
@@ -210,6 +213,29 @@ describe("config", () => {
     expect(reloaded.api_keys?.find((k) => k.id === "k_legacy")?.scope).toBe("write");
   });
 
+  test("writeEnvFile writes .env at 0600 (SCRIBE_AUTH_TOKEN secrecy)", () => {
+    // Regression for vault#354 reviewer finding: the .env holds
+    // SCRIBE_AUTH_TOKEN (the vault↔scribe loopback bearer). On a
+    // shared-user machine or a Docker image with a loose umask, a
+    // world-readable .env would leak the bearer to any local process.
+    //
+    // Resolve the path dynamically from PARACHUTE_HOME (not the
+    // module-load-time `ENV_PATH` constant) so this test is robust to
+    // earlier tests in the suite that mutate PARACHUTE_HOME — writeEnvFile
+    // itself resolves the path dynamically via `envFilePath()`.
+    const envPath = join(process.env.PARACHUTE_HOME!, "vault", ".env");
+    writeEnvFile({ SCRIBE_AUTH_TOKEN: "test-bearer-do-not-leak", PORT: "1940" });
+    const mode = statSync(envPath).mode & 0o777;
+    expect(mode).toBe(0o600);
+
+    // Existing-file branch: writeFileSync's `mode` only applies on
+    // create, so the defensive chmodSync must downgrade an existing
+    // (e.g. 0644-from-an-older-version) .env to 0600 on the next write.
+    writeEnvFile({ SCRIBE_AUTH_TOKEN: "rotated", PORT: "1940" });
+    const mode2 = statSync(envPath).mode & 0o777;
+    expect(mode2).toBe(0o600);
+  });
+
   test("round-trips autostart: true|false (#113)", () => {
     // Default: absent means autostart-on (init registers the daemon).
     writeGlobalConfig({ port: 1940 });

package/src/config.ts

@@ -277,6 +277,24 @@ export interface GlobalConfig {
    * resolved path. See `./mirror-config.ts`.
    */
   mirror?: MirrorConfigType;
+  /**
+   * Auto-transcribe configuration for the vault↔scribe handoff (vault#353,
+   * design 2026-05-21 Part 2). When `enabled: true` AND scribe is discoverable
+   * (`services.json` or `SCRIBE_URL` env), audio attachments uploaded to any
+   * vault are automatically sent to scribe and the resulting transcript lands
+   * as a sibling `<attachment-path>.transcript.md` note.
+   *
+   * URL + bearer are not stored here — URL is resolved per-process from
+   * `services.json` via `scribe-discovery.ts`, and bearer comes from the
+   * `SCRIBE_AUTH_TOKEN` env var (persisted in `~/.parachute/vault/.env`).
+   * The schema's `autoTranscribe.scribeUrl` / `autoTranscribe.scribeBearer`
+   * fields are projection of those resolved values (readOnly / writeOnly),
+   * not separate storage.
+   */
+  auto_transcribe?: {
+    /** Master toggle. Default false; the worker is a no-op when unset. */
+    enabled?: boolean;
+  };
 }
 
 // ---------------------------------------------------------------------------
@@ -1141,6 +1159,22 @@ export function readGlobalConfig(): GlobalConfig {
       const totpSecretMatch = yaml.match(/^totp_secret:\s*"([^"]+)"/m);
       const discoveryMatch = yaml.match(/^discovery:\s*(enabled|disabled)/m);
       const autostartMatch = yaml.match(/^autostart:\s*(true|false)/m);
+      // auto_transcribe block — currently single boolean `enabled` (vault#353).
+      // Parsed as a nested 2-space-indent block so future fields can grow under
+      // it without breaking the regex; only `enabled` is read for v0.6.
+      const autoTranscribeStart = yaml.match(/^auto_transcribe:\s*$/m);
+      let autoTranscribeEnabled: boolean | undefined;
+      if (autoTranscribeStart) {
+        const after = yaml.slice((autoTranscribeStart.index ?? 0) + autoTranscribeStart[0].length);
+        for (const line of after.split("\n")) {
+          if (line.match(/^\S/) && line.trim().length > 0) break; // next top-level key
+          const m = line.match(/^\s+enabled:\s*(true|false)/);
+          if (m) {
+            autoTranscribeEnabled = m[1]! === "true";
+            break;
+          }
+        }
+      }
       const config: GlobalConfig = {
         port: portMatch ? parseInt(portMatch[1]!, 10) : DEFAULT_PORT,
         default_vault: defaultVaultMatch?.[1],
@@ -1153,6 +1187,9 @@ export function readGlobalConfig(): GlobalConfig {
       if (autostartMatch) {
         config.autostart = autostartMatch[1]! === "true";
       }
+      if (autoTranscribeEnabled !== undefined) {
+        config.auto_transcribe = { enabled: autoTranscribeEnabled };
+      }
 
       // Parse backup_codes: a YAML list of quoted bcrypt hashes under
       //   backup_codes:
@@ -1297,6 +1334,13 @@ export function writeGlobalConfig(config: GlobalConfig): void {
     lines.push(...serializeMirrorSection(config.mirror));
   }
 
+  if (config.auto_transcribe) {
+    lines.push("auto_transcribe:");
+    if (config.auto_transcribe.enabled !== undefined) {
+      lines.push(`  enabled: ${config.auto_transcribe.enabled}`);
+    }
+  }
+
   // 0600 — owner read/write only. This file may contain the bcrypt password
   // hash and plaintext TOTP secret; it must not be world- or group-readable.
   writeFileSync(globalConfigPath(), lines.join("\n") + "\n", { mode: 0o600 });
@@ -1395,7 +1439,15 @@ export function writeEnvFile(env: Record<string, string>): void {
       lines.push(`${key}=${val}`);
     }
   }
-  writeFileSync(envFilePath(), lines.join("\n") + "\n");
+  // 0600 — owner read/write only. This file holds SCRIBE_AUTH_TOKEN (the
+  // vault↔scribe loopback bearer) and any other secrets the operator drops
+  // in via `parachute-vault config set`. It must not be world- or
+  // group-readable on shared-user machines or Docker images with a loose
+  // umask. Mirrors the writeGlobalConfig pattern above.
+  writeFileSync(envFilePath(), lines.join("\n") + "\n", { mode: 0o600 });
+  // writeFileSync's `mode` only applies on file creation, so chmod an existing
+  // file explicitly in case it was written by an older version at 0644.
+  try { chmodSync(envFilePath(), 0o600); } catch {}
 }
 
 /**

package/src/db.ts

@@ -4,11 +4,24 @@
 
 import { Database } from "bun:sqlite";
 import { vaultDbPath, vaultDir } from "./config.ts";
+import { applyConnectionPragmas } from "../core/src/schema.ts";
 import { mkdirSync } from "fs";
 
-/** Open (or create) a vault's SQLite database. */
+/**
+ * Open (or create) a vault's SQLite database with vault's standard
+ * connection pragmas (WAL + synchronous=NORMAL + foreign_keys=ON). Safe
+ * for both the in-process store and out-of-process consumers (CLI,
+ * parachute-runner, mirror tools) — pragmas are idempotent.
+ *
+ * The full schema migration runs separately when a `BunSqliteStore` is
+ * instantiated around the returned handle; callers that just want raw
+ * read access (auth probes, backup tooling) skip that and pay only the
+ * pragma cost.
+ */
 export function openVaultDb(name: string): Database {
   const dir = vaultDir(name);
   mkdirSync(dir, { recursive: true });
-  return new Database(vaultDbPath(name));
+  const db = new Database(vaultDbPath(name));
+  applyConnectionPragmas(db);
+  return db;
 }

package/src/export-watch.test.ts

@@ -763,6 +763,105 @@ describe("export CLI: --watch", () => {
     30_000,
   );
 
+  test(
+    "--strict-case-collision: mid-watch collision stops the loop with the full error + hint",
+    async () => {
+      // vault#350 reviewer fix. Before: the watch polling timer's
+      // generic catch swallowed a CaseCollisionError thrown by a
+      // post-initial-export poll, logging only `[watch] export error:
+      // ...` and continuing to spin. The strict-mode guarantee
+      // ("refuse to continue when a collision appears") evaporated
+      // after the initial export.
+      //
+      // Scenario: start --watch --strict-case-collision against a
+      // vault whose initial state has no collisions (so the watch
+      // loop boots). Write a colliding note out-of-band. On the next
+      // poll cycle, runCycle throws CaseCollisionError; the watch
+      // catch path should now (a) print the full err.message to
+      // stderr including every colliding path, (b) print the
+      // actionable hint, (c) exit non-zero.
+      //
+      // The CLI doesn't expose `caseSensitiveOverride`, so this test
+      // is meaningful only on a case-insensitive FS (macOS APFS
+      // default, Windows NTFS default). On a case-sensitive Linux
+      // ext4, the pre-scan is a no-op by design and the path under
+      // test never fires — skip rather than assert a behavior that
+      // can't manifest there.
+      const { probeCaseSensitive } = await import("../core/src/portable-md.ts");
+      if (probeCaseSensitive(exportDir)) {
+        console.log(
+          "skipping mid-watch strict-collision test on case-sensitive FS — the strict pre-scan is a no-op here",
+        );
+        return;
+      }
+      const watch = spawnWatchCli(
+        [
+          "export",
+          exportDir,
+          "--watch",
+          "--interval",
+          "1",
+          "--strict-case-collision",
+        ],
+        tmp,
+      );
+      try {
+        // Initial export must succeed (seed has no collision).
+        await watch.awaitLine((l) => l.includes("Exported 1 note"), 10_000);
+        await watch.awaitLine((l) => l.includes("[watch] polling every 1s"), 5_000);
+
+        // Inject a collision: existing seed is `Inbox/seed`; write
+        // `Inbox/SEED` so the lowercased (path, ext) key collides.
+        const { clearVaultStoreCache, getVaultStore } = await import("./vault-store.ts");
+        clearVaultStoreCache();
+        const store = getVaultStore("default");
+        await store.createNote("# upper\n", {
+          id: "01HZB222222222222222222222",
+          path: "Inbox/SEED",
+        });
+        clearVaultStoreCache();
+      } catch (err) {
+        watch.proc.kill("SIGKILL");
+        throw err;
+      }
+
+      // The strict-mode catch path exits the process. Wait for it.
+      // Use a guarded race so a hung process doesn't eat the full
+      // 30s suite budget — surface a useful failure message instead.
+      const exit = await Promise.race([
+        watch.proc.exited,
+        new Promise<number>((_, reject) =>
+          setTimeout(
+            () =>
+              reject(
+                new Error(
+                  `CLI did not exit within 15s of collision injection.\n` +
+                    `stdout:\n${watch.seenLines.join("\n")}\n` +
+                    `stderr:\n${watch.seenStderr.join("\n")}`,
+                ),
+              ),
+            15_000,
+          ),
+        ),
+      ]).catch((err) => {
+        watch.proc.kill("SIGKILL");
+        throw err;
+      });
+      // Non-zero exit: strict mode refused to continue.
+      expect(exit).not.toBe(0);
+
+      const stderr = watch.seenStderr.join("\n");
+      // Full collision message: header line + every colliding path.
+      expect(stderr).toContain("case-collision detected");
+      expect(stderr).toContain("Inbox/seed.md");
+      expect(stderr).toContain("Inbox/SEED.md");
+      // Actionable hint (the new line added by this fix).
+      expect(stderr).toContain("Resolve the collision in the vault");
+      expect(stderr).toContain("--strict-case-collision");
+    },
+    30_000,
+  );
+
   test(
     "--watch + --git-commit: vault write → re-export → auto-commit → continues",
     async () => {

package/src/mcp-install-interactive.test.ts

@@ -287,8 +287,23 @@ describe("runInteractiveInstall — decision tree", () => {
     expect(result.scope).toBe("vault:write");
   });
 
-  test("scope widening: typing 'admin' produces vault:admin mint", async () => {
-    const { io } = mockIO([
+  test("typing 'admin' auto-routes to legacy-pat with vault:admin scope (hub mint-token rejects admin)", async () => {
+    // Regression for the symptom Aaron hit on hub 0.5.12-rc.2 / vault
+    // 0.4.7-rc.1: picking "admin" in the mint prompt sent
+    // `vault:default:admin` to `POST /api/auth/mint-token`, which hub
+    // rejects by policy (per-vault admin is non-requestable; see
+    // `parachute-hub/src/scope-explanations.ts:VAULT_ADMIN_RE` and
+    // `api-mint-token.ts`'s non-requestable guard):
+    //
+    //   Hub mint-token rejected (HTTP 400, invalid_scope):
+    //   scope vault:default:admin is not requestable via mint-token;
+    //   use OAuth flow or operator rotation
+    //
+    // Fix: auto-route "admin" in the interactive prompt to legacy-pat
+    // mode (which mints a vault-DB pvt_* — the right shape for an MCP
+    // entry needing admin permissions), with a printed explanation so
+    // the switch isn't silent.
+    const { io, state } = mockIO([
       null,    // accept install-scope default
       "admin",
       true,
@@ -296,7 +311,13 @@ describe("runInteractiveInstall — decision tree", () => {
     const result = await runInteractiveInstall(baseCtx(), io);
     expect(result).not.toBe("abort");
     if (result === "abort") return;
+    expect(result.mode).toBe("legacy-pat");
     expect(result.scope).toBe("vault:admin");
+    // The auto-route must surface the reason — silent re-routing would
+    // mislead operators who specifically want a hub JWT.
+    const logged = state.logs.join("\n");
+    expect(logged).toMatch(/admin requires a vault-DB pvt_\*/);
+    expect(logged).toMatch(/hub policy/);
   });
 
   test("typing 'paste' at the auth prompt switches to token mode + asks for token", async () => {

package/src/mcp-install-interactive.ts

@@ -190,7 +190,9 @@ export async function runInteractiveInstall(
         "Choices:",
         "  Enter       → mint a hub JWT with vault:read scope (recommended).",
         "  write       → mint with vault:write (mutations).",
-        "  admin       → mint with vault:admin (schema management).",
+        "  admin       → mint a vault-DB pvt_* with vault:admin (schema management;",
+        "                hub policy reserves per-vault admin for operator-only paths,",
+        "                so this auto-routes to legacy-pat).",
         "  paste       → use an existing token instead of minting.",
         "  legacy      → mint a vault-DB pvt_* (self-hosted-without-hub).",
       ].join("\n"),
@@ -209,10 +211,27 @@ export async function runInteractiveInstall(
       // operator gets the same control they get when widening a hub
       // JWT's scope. (vault#292 review F2.)
       scope = await askScope(io);
+    } else if (answer === "admin") {
+      // `vault:<name>:admin` is non-requestable via hub mint-token by
+      // policy — only the session-cookie-gated `/admin/vault-admin-token/:name`
+      // endpoint can mint per-vault admin scopes (see
+      // `parachute-hub/src/scope-explanations.ts:VAULT_ADMIN_RE` and
+      // `api-mint-token.ts`'s non-requestable guard). Hub returns
+      // HTTP 400 invalid_scope: "scope vault:<name>:admin is not
+      // requestable via mint-token; use OAuth flow or operator rotation".
+      //
+      // Auto-route to legacy-pat which mints a vault-DB pvt_* with full
+      // permissions — that's the right shape for an operator who wants
+      // admin scope on a local MCP entry. Print a one-line explanation
+      // so the switch isn't silent.
+      io.log("  → admin requires a vault-DB pvt_* (hub policy: per-vault admin");
+      io.log("    is operator-only, not mintable via the public mint-token API).");
+      io.log("    Switching to legacy-pat mode with vault:admin scope.");
+      mode = "legacy-pat";
+      scope = "vault:admin";
     } else {
       mode = "mint";
       if (answer === "write") scope = "vault:write";
-      else if (answer === "admin") scope = "vault:admin";
     }
   } else {
     // No hub-mint path available — explain why and offer the alternatives.