@openparachute/vault 0.4.9-rc.9 → 0.5.0-rc.2

package/src/config.ts

@@ -34,8 +34,11 @@ import { existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync, renameSy
 import crypto from "node:crypto";
 
 import {
+  // vault#400: only the PARSE side is used here now — to detect a legacy
+  // server-wide `mirror:` block so the boot migration can relocate it to the
+  // owning vault's per-vault file. `writeGlobalConfig` no longer serializes a
+  // mirror block (per-vault writes live in `mirror-config.ts`).
   parseMirrorConfig as parseMirrorSectionFromYaml,
-  serializeMirrorConfig as serializeMirrorSection,
   type MirrorConfig as MirrorConfigType,
 } from "./mirror-config.ts";
 
@@ -1330,9 +1333,14 @@ export function writeGlobalConfig(config: GlobalConfig): void {
     lines.push(...serializeBackup(config.backup));
   }
 
-  if (config.mirror) {
-    lines.push(...serializeMirrorSection(config.mirror));
-  }
+  // vault#400: mirror config is now PER-VAULT (`data/<vault>/mirror-config.yaml`),
+  // not a server-wide block here. `writeGlobalConfig` deliberately does NOT
+  // re-emit a `mirror:` block — doing so would resurrect the legacy
+  // server-wide config the boot migration just commented out, re-introducing
+  // the "same remote on every vault page" bug. `readGlobalConfig` still parses
+  // a legacy block (below) so the one-time migration can detect + relocate it.
+  // `serializeMirrorSection` remains used by the per-vault writer in
+  // `mirror-config.ts`.
 
   if (config.auto_transcribe) {
     lines.push("auto_transcribe:");

package/src/export-watch.test.ts

@@ -35,6 +35,7 @@ import {
   runGitCommitCycle,
   shouldCommit,
 } from "./export-watch.ts";
+import { GitNotInstalledError } from "./git-preflight.ts";
 
 const CLI = path.resolve(import.meta.dir, "cli.ts");
 
@@ -504,6 +505,28 @@ describe("runGitCommitCycle", () => {
     });
     expect(result.message).toBe("note: Inbox/DonorMeeting");
   });
+
+  test("git missing → throws GitNotInstalledError (sync surfaces friendly error, not raw spawn crash)", async () => {
+    // vault#415 — the sync/commit path must surface the actionable
+    // git-not-installed message (which the manager threads into
+    // status.last_error) instead of crashing with a raw "Executable not
+    // found in $PATH". Force the preflight to see no git via the `which`
+    // seam; no real spawn should be reached.
+    fs.writeFileSync(path.join(dir, "Note.md"), "# n\n");
+    await expect(
+      runGitCommitCycle({
+        repoDir: dir,
+        template: DEFAULT_COMMIT_TEMPLATE,
+        notesChanged: 1,
+        vaultName: "default",
+        firstNoteTitle: "Note",
+        push: false,
+        which: () => null,
+      }),
+    ).rejects.toBeInstanceOf(GitNotInstalledError);
+    // The commit cycle bailed at the preflight — no commit landed.
+    expect(gitLogOneline(dir)).toHaveLength(1); // only the seed
+  });
 });
 
 // ---------------------------------------------------------------------------

package/src/export-watch.ts

@@ -13,6 +13,8 @@
  * detection. See `parachute-patterns/cookbook/vault-portable-export.md`.
  */
 
+import { ensureGitAvailable } from "./git-preflight.ts";
+
 // ---------------------------------------------------------------------------
 // Commit message templating
 // ---------------------------------------------------------------------------
@@ -269,11 +271,23 @@ export async function runGitCommitCycle(opts: {
   push: boolean;
   /** Override for tests — defaults to `new Date().toISOString()`. */
   now?: () => string;
+  /**
+   * Override the git-presence probe (test seam — defaults to `Bun.which`).
+   * Inject a fn returning `null` to exercise the git-not-installed path.
+   */
+  which?: (cmd: string) => string | null;
 }): Promise<{
   committed: boolean;
   message?: string;
   push?: { attempted: true; ok: boolean; error?: string };
 }> {
+  // Preflight: every step below shells `git`. On a git-less server the first
+  // `Bun.spawn(["git", ...])` would throw a raw "Executable not found" error;
+  // surface the friendly, actionable GitNotInstalledError so callers can
+  // thread it into mirror status (`last_error`) instead of crashing the
+  // watch loop with an opaque message.
+  ensureGitAvailable(opts.which);
+
   const now = opts.now ?? (() => new Date().toISOString());
 
   const add = await gitAddAll(opts.repoDir);

package/src/git-preflight.test.ts

@@ -0,0 +1,70 @@
+/**
+ * Tests for the shared git-availability preflight (vault#415).
+ *
+ * Found live: importing a repo on a git-less Amazon Linux EC2 box failed
+ * with a raw `Executable not found in $PATH: "git"` 500. The preflight gives
+ * every git entry point a fast, friendly, actionable failure instead.
+ */
+
+import { describe, test, expect } from "bun:test";
+import {
+  GitNotInstalledError,
+  ensureGitAvailable,
+  isGitNotFoundSpawnError,
+} from "./git-preflight.ts";
+
+describe("ensureGitAvailable", () => {
+  test("throws GitNotInstalledError when which returns null", () => {
+    expect(() => ensureGitAvailable(() => null)).toThrow(GitNotInstalledError);
+  });
+
+  test("does not throw when which resolves git", () => {
+    expect(() => ensureGitAvailable(() => "/usr/bin/git")).not.toThrow();
+  });
+
+  test("defaults to Bun.which (git is present in this test env)", () => {
+    // The test host has git; the default-arg path resolves it cleanly.
+    expect(() => ensureGitAvailable()).not.toThrow();
+  });
+});
+
+describe("GitNotInstalledError message", () => {
+  test("is OS-agnostic-but-helpful — names dnf, apt-get, and brew", () => {
+    const msg = new GitNotInstalledError().message;
+    expect(msg).toContain("git is required for this operation");
+    expect(msg).toContain("sudo dnf install git");
+    expect(msg).toContain("sudo apt-get install -y git");
+    expect(msg).toContain("brew install git");
+  });
+
+  test("carries the GitNotInstalledError name (instanceof + name both work)", () => {
+    const err = new GitNotInstalledError();
+    expect(err).toBeInstanceOf(GitNotInstalledError);
+    expect(err.name).toBe("GitNotInstalledError");
+  });
+});
+
+describe("isGitNotFoundSpawnError", () => {
+  test("matches Bun's executable-not-found message for git", () => {
+    expect(
+      isGitNotFoundSpawnError(
+        new Error('Executable not found in $PATH: "git"'),
+      ),
+    ).toBe(true);
+  });
+
+  test("matches an ENOENT spawn error mentioning git", () => {
+    const err = new Error("spawn git ENOENT") as Error & { code?: string };
+    err.code = "ENOENT";
+    expect(isGitNotFoundSpawnError(err)).toBe(true);
+  });
+
+  test("does not match an unrelated error", () => {
+    expect(isGitNotFoundSpawnError(new Error("network unreachable"))).toBe(false);
+  });
+
+  test("does not match a non-Error value", () => {
+    expect(isGitNotFoundSpawnError("git missing")).toBe(false);
+    expect(isGitNotFoundSpawnError(null)).toBe(false);
+  });
+});

package/src/git-preflight.ts

@@ -0,0 +1,68 @@
+/**
+ * Shared git-availability preflight.
+ *
+ * Every git-using entry point in vault (mirror import, mirror sync/commit/
+ * push, internal-mirror bootstrap) shells out to the `git` binary via
+ * `Bun.spawn(["git", ...])`. On a server where `git` isn't installed (a
+ * fresh Amazon Linux / minimal Docker image, etc.) Bun throws a raw
+ * `Executable not found in $PATH: "git"` error, which the import route only
+ * caught in its generic `internal` 500 branch — surfacing an unhelpful,
+ * un-actionable error to the operator.
+ *
+ * This module centralizes the preflight so every git entry point fails
+ * fast with a clear, actionable message that tells the operator HOW to
+ * fix it (install git via their distro's package manager).
+ *
+ * Found live on the gitcoin-parachute EC2 deploy (Amazon Linux, no git).
+ * See vault#415-era fix.
+ */
+
+/**
+ * Thrown when `git` is required for an operation but isn't on PATH. Carries
+ * an OS-agnostic-but-helpful message with the common install commands so the
+ * operator can act without leaving the error surface.
+ */
+export class GitNotInstalledError extends Error {
+  constructor() {
+    super(
+      "git is required for this operation but was not found on the server. " +
+        "Install git and retry — e.g. `sudo dnf install git` (Amazon Linux / Fedora), " +
+        "`sudo apt-get install -y git` (Debian / Ubuntu), or `brew install git` (macOS).",
+    );
+    this.name = "GitNotInstalledError";
+  }
+}
+
+/**
+ * Throw `GitNotInstalledError` if `git` isn't resolvable on PATH.
+ *
+ * `which` is a TEST SEAM (default `Bun.which`) so tests can force the
+ * git-missing branch without uninstalling git from the test host. Production
+ * callers pass nothing and get the real `Bun.which`.
+ */
+export function ensureGitAvailable(
+  which: (cmd: string) => string | null = Bun.which,
+): void {
+  if (which("git") === null) {
+    throw new GitNotInstalledError();
+  }
+}
+
+/**
+ * Heuristic: does this error look like the "git executable not found" failure
+ * Bun throws when it can't resolve the binary? Used as a belt-and-suspenders
+ * catch around `Bun.spawn(["git", ...])` so a spawn that slips past the
+ * preflight (race where git is removed between check and spawn, or a code path
+ * that didn't preflight) still surfaces the friendly error instead of the raw
+ * `Executable not found in $PATH: "git"` string.
+ */
+export function isGitNotFoundSpawnError(err: unknown): boolean {
+  if (!(err instanceof Error)) return false;
+  const msg = err.message ?? "";
+  // Bun: `Executable not found in $PATH: "git"`.
+  // Node/posix: ENOENT spawn errors mention the missing file.
+  return (
+    (msg.includes("Executable not found") && msg.includes("git")) ||
+    ((err as { code?: string }).code === "ENOENT" && msg.includes("git"))
+  );
+}

package/src/hub-jwt.test.ts

@@ -87,15 +87,19 @@ interface SignOpts {
   expiresAtSeconds?: number;
   omitKid?: boolean;
   kid?: string;
+  /** `permissions` claim (auth-unification C0). Undefined → omit. */
+  permissions?: unknown;
 }
 
 async function signJwt(kp: Keypair, opts: SignOpts): Promise<string> {
   const iat = Math.floor(Date.now() / 1000);
   const exp = opts.expiresAtSeconds ?? iat + (opts.ttlSeconds ?? 60);
-  const builder = new SignJWT({
+  const claims: Record<string, unknown> = {
     scope: opts.scope ?? "vault:read vault:write",
     client_id: opts.clientId ?? "test-client",
-  })
+  };
+  if (opts.permissions !== undefined) claims.permissions = opts.permissions;
+  const builder = new SignJWT(claims)
     .setProtectedHeader(opts.omitKid ? { alg: "RS256" } : { alg: "RS256", kid: opts.kid ?? kp.kid })
     .setIssuer(opts.iss ?? "http://issuer.invalid")
     .setSubject(opts.sub ?? "user-1")
@@ -187,6 +191,27 @@ describe("validateHubJwt — happy path", () => {
     const claims = await validateHubJwt(token, { expectedAudience: "vault.work" });
     expect(claims.aud).toBe("vault.work");
   });
+
+  test("permissions claim surfaces on the validated result (C0)", async () => {
+    const token = await signJwt(kp, {
+      iss: fixture.origin,
+      permissions: { scoped_tags: ["health", "finance"] },
+    });
+    const claims = await validateHubJwt(token);
+    expect(claims.permissions).toEqual({ scoped_tags: ["health", "finance"] });
+  });
+
+  test("no permissions claim → permissions is undefined", async () => {
+    const token = await signJwt(kp, { iss: fixture.origin });
+    const claims = await validateHubJwt(token);
+    expect(claims.permissions).toBeUndefined();
+  });
+
+  test("non-object permissions claim → permissions is undefined (not surfaced)", async () => {
+    const token = await signJwt(kp, { iss: fixture.origin, permissions: "not-an-object" });
+    const claims = await validateHubJwt(token);
+    expect(claims.permissions).toBeUndefined();
+  });
 });
 
 describe("validateHubJwt — audience strict-check", () => {

package/src/hub-jwt.ts

@@ -59,6 +59,16 @@ const guard = createScopeGuard({ hubOrigin: () => getHubOrigin() });
  * Scope-shape policy (e.g. "hub-issued tokens may not carry broad
  * `vault:<verb>` scopes") is enforced one layer up in `authenticateHubJwt`,
  * not here — this function stays focused on JWT-level concerns.
+ *
+ * The returned `HubJwtClaims` carries the native `permissions` claim
+ * (scope-guard ≥0.4.0-rc.2 parses + surfaces it; `undefined` when absent or
+ * not a JSON object). Tag-scope enforcement reads `permissions.scoped_tags`
+ * in `authenticateHubJwt` — see auth-unification arc C0.
+ *
+ * jti policy: scope-guard's `createScopeGuard` defaults `allowMissingJti:
+ * false` (per hub#218 / scope-guard #322), so a hub JWT lacking a `jti`
+ * claim is rejected here. Vault doesn't opt out — every hub mint stamps a
+ * jti, and revocation can't be enforced on tokens we can't index.
  */
 export async function validateHubJwt(
   token: string,

package/src/init-summary.test.ts

@@ -57,9 +57,9 @@ describe("buildInitSummaryLines", () => {
       expect(out).not.toContain("Baked into ~/.claude.json");
     });
 
-    test("includes the tokens-create-later hint", () => {
+    test("includes the mcp-install-later hint", () => {
       expect(out).toContain("Token in ~/.claude.json");
-      expect(out).toContain("parachute vault tokens create");
+      expect(out).toContain("parachute-vault mcp-install");
     });
 
     test("omits the Bearer curl example", () => {
@@ -103,9 +103,9 @@ describe("buildInitSummaryLines", () => {
       expect(out).toContain("your vault isn't reachable by any client");
     });
 
-    test("points to both recovery paths", () => {
+    test("points to the mcp-install recovery path (hub JWT)", () => {
       expect(out).toContain("parachute-vault mcp-install");
-      expect(out).toContain("parachute vault tokens create");
+      expect(out).toContain("mints a hub JWT");
     });
 
     test("does not print any token", () => {

package/src/init-summary.ts

@@ -12,46 +12,73 @@ export type InitSummaryInput = {
   bindHost: string;
   port: number;
   mcpUrl: string;
+  /**
+   * Guidance from the bootstrap-credential step when no token could be issued
+   * (standalone install, no hub reachable — vault#282 Stage 2). Surfaced when
+   * the operator wanted a token (`addMcp || addToken`) but `apiKey` is
+   * undefined, so they know why and how to make the vault reachable.
+   */
+  noTokenGuidance?: string | undefined;
 };
 
 /**
  * Build the post-install summary lines for `vault init`, branched on the
- * (addMcp, addToken) decision matrix:
+ * (addMcp, addToken, apiKey) decision matrix. Post-0.5.0 the token is a
+ * hub-issued JWT minted via operator.token; when no hub is reachable `apiKey`
+ * is undefined even though the operator opted in (`addToken`/`addMcp`):
  *
- *   Y, Y → token baked into claude.json + printed prominently
- *   Y, N → token baked into claude.json, hint about `tokens create`
- *   N, Y → token printed prominently, no claude.json entry
- *   N, N → warning: vault unreachable; both recovery paths listed
+ *   addMcp,  addToken,  apiKey → token baked into claude.json + printed
+ *   addMcp,  !addToken, apiKey → token baked into claude.json, hint
+ *   !addMcp, addToken,  apiKey → token printed prominently
+ *   wanted-token-but-no-hub    → guidance: no token issued, recovery paths
+ *   !addMcp, !addToken         → warning: vault unreachable; recovery paths
  */
 export function buildInitSummaryLines(input: InitSummaryInput): string[] {
-  const { addMcp, addToken, apiKey, configDir, bindHost, port, mcpUrl } = input;
+  const { addMcp, addToken, apiKey, configDir, bindHost, port, mcpUrl, noTokenGuidance } = input;
   const lines: string[] = [];
   lines.push("");
   lines.push("---");
 
+  const wantedToken = addMcp || addToken;
+
   if (addMcp && addToken && apiKey) {
     lines.push("");
     lines.push(`Your API token: ${apiKey}`);
     lines.push(`  - Baked into ~/.claude.json for Claude Code ✓`);
     lines.push(`  - Paste into your other MCP client's config, or use as Authorization: Bearer <token>`);
     lines.push(`  - Won't be shown again — save it now.`);
-  } else if (addMcp && !addToken) {
+  } else if (addMcp && !addToken && apiKey) {
     lines.push("");
     lines.push(
-      "Token in ~/.claude.json; run `parachute vault tokens create` later if you need one for other clients.",
+      "Token in ~/.claude.json; run `parachute-vault mcp-install` later if you need one for other clients.",
     );
   } else if (!addMcp && addToken && apiKey) {
     lines.push("");
     lines.push(`Your API token: ${apiKey}`);
     lines.push(`  - Paste into your other MCP client's config, or use as Authorization: Bearer <token>`);
     lines.push(`  - Won't be shown again — save it now.`);
+  } else if (wantedToken && !apiKey) {
+    // Opted into a token but no hub was reachable to mint one (vault#282
+    // Stage 2 — vault no longer mints local pvt_* tokens). Surface why and
+    // the recovery paths.
+    lines.push("");
+    lines.push(
+      noTokenGuidance ??
+        "No token issued — no hub was reachable to mint a hub JWT.",
+    );
+    lines.push(
+      "  Once a hub is running, run `parachute-vault mcp-install` to mint + wire a token,",
+    );
+    lines.push(
+      "  or set VAULT_AUTH_TOKEN for an operator-channel bearer.",
+    );
   } else if (!addMcp && !addToken) {
     lines.push("");
     lines.push(
       "You've skipped both MCP install and token generation — your vault isn't reachable by any client.",
     );
     lines.push(
-      "  Add Claude Code later with `parachute-vault mcp-install`, or mint a token with `parachute vault tokens create`.",
+      "  Add Claude Code later with `parachute-vault mcp-install`, which mints a hub JWT (needs a hub running).",
     );
   }
 
@@ -81,7 +108,6 @@ export function buildInitSummaryLines(input: InitSummaryInput): string[] {
     lines.push(`  - Or add Claude Code back anytime:  parachute-vault mcp-install`);
   } else {
     lines.push(`  - Add Claude Code:  parachute-vault mcp-install`);
-    lines.push(`  - Mint a token:     parachute vault tokens create`);
   }
   lines.push(`  - Check status:     parachute-vault status`);
   lines.push(`  - Edit config:      parachute-vault config`);

package/src/mcp-config.test.ts

@@ -189,8 +189,10 @@ describe("mcp-config CLI", () => {
     expect(res.stderr).toMatch(/--token/);
     expect(res.stderr).toMatch(/PARACHUTE_VAULT_TOKEN/);
     // The error message points operators at the workaround paths so they
-    // can recover without re-reading the docs.
-    expect(res.stderr).toMatch(/parachute-vault tokens create/);
+    // can recover without re-reading the docs. (vault#282 Stage 2: tokens are
+    // hub-issued JWTs now, so the hint names mcp-install, not the removed
+    // `tokens create`.)
+    expect(res.stderr).toMatch(/parachute-vault mcp-install/);
     expect(res.stderr).toMatch(/--env-vars/);
   });
 

package/src/mcp-http.ts

@@ -45,13 +45,34 @@ function requiredVerbForTool(tool: { requiredVerb?: VaultVerb }): VaultVerb {
   return tool.requiredVerb ?? "write";
 }
 
-/** Handle scoped MCP at /vault/{name}/mcp (single vault). */
-export async function handleScopedMcp(req: Request, vaultName: string, auth: AuthResult): Promise<Response> {
+/**
+ * Handle scoped MCP at /vault/{name}/mcp (single vault).
+ *
+ * `callerBearer` is the RAW credential the session presented (from
+ * `extractApiKey`). It's threaded into `generateScopedMcpTools` so the
+ * manage-token tool can forward it to hub's mint-token attenuation proxy
+ * (vault#403, MGT). NULL when the request carried no bearer (auth would have
+ * already rejected) — the tool treats a missing/non-JWT bearer as
+ * non-forwardable and returns a clear error on mint.
+ */
+export async function handleScopedMcp(
+  req: Request,
+  vaultName: string,
+  auth: AuthResult,
+  callerBearer?: string | null,
+): Promise<Response> {
   // Auth flows through to getServerInstruction so the connect-time
   // markdown brief is filtered by `scoped_tags` — symmetric with the
   // JSON `vault-info` wrapper.
   const instruction = await getServerInstruction(vaultName, auth);
-  return handleMcp(req, () => generateScopedMcpTools(vaultName, auth), `parachute-vault/${vaultName}`, vaultName, auth, instruction);
+  return handleMcp(
+    req,
+    () => generateScopedMcpTools(vaultName, auth, callerBearer ?? null),
+    `parachute-vault/${vaultName}`,
+    vaultName,
+    auth,
+    instruction,
+  );
 }
 
 async function handleMcp(

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

@@ -237,12 +237,11 @@ describe("runInteractiveInstall — decision tree", () => {
     expect(state.logs.some((l) => /expected one of/.test(l))).toBe(true);
   });
 
-  test("hub not reachable: walkthrough offers paste vs legacy (no mint option)", async () => {
+  test("hub not reachable: walkthrough falls back to paste-only (vault#282 Stage 2 — no legacy mint)", async () => {
     const { io, state } = mockIO([
-      null,     // accept install-scope default
-      "legacy", // pick legacy-pat
-      null,     // accept default scope (read) on the F2 scope prompt
-      true,     // proceed
+      null,         // accept install-scope default
+      "pasted-jwt", // the bearer (no auth-mode prompt — paste is the only path)
+      true,         // proceed
     ]);
     const result = await runInteractiveInstall(
       baseCtx({ hubReachable: false }),
@@ -250,16 +249,15 @@ describe("runInteractiveInstall — decision tree", () => {
     );
     expect(result).not.toBe("abort");
     if (result === "abort") return;
-    expect(result.mode).toBe("legacy-pat");
-    expect(result.scope).toBe("vault:read");
+    expect(result.mode).toBe("token");
+    expect(result.pastedToken).toBe("pasted-jwt");
     // Auth prompt should explain the no-hub state.
     expect(state.logs.some((l) => /Hub-mint isn't available/.test(l))).toBe(true);
   });
 
-  test("hub reachable but no operator.token: also offers paste vs legacy", async () => {
+  test("hub reachable but no operator.token: also falls back to paste-only", async () => {
     const { io, state } = mockIO([
       null,         // accept install-scope default
-      "paste",      // pick paste
       "pasted-jwt", // the bearer
       true,         // proceed
     ]);
@@ -287,22 +285,13 @@ describe("runInteractiveInstall — decision tree", () => {
     expect(result.scope).toBe("vault:write");
   });
 
-  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.
+  test("typing 'admin' mints a hub JWT with vault:admin scope (hub PR-A / hub#449)", async () => {
+    // As of hub PR-A (hub#449), `POST /api/auth/mint-token` mints
+    // `vault:<name>:admin` when the calling operator bearer carries
+    // `parachute:host:admin` (which the default operator.token does).
+    // So picking "admin" in the mint prompt now resolves to mint mode
+    // with vault:admin scope — the verb extraction downstream narrows
+    // it to `vault:<name>:admin`. No more legacy-pat auto-route.
     const { io, state } = mockIO([
       null,    // accept install-scope default
       "admin",
@@ -311,13 +300,11 @@ 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.mode).toBe("mint");
     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.
+    // The branch surfaces that admin mints a scope-narrowed hub JWT.
     const logged = state.logs.join("\n");
-    expect(logged).toMatch(/admin requires a vault-DB pvt_\*/);
-    expect(logged).toMatch(/hub policy/);
+    expect(logged).toMatch(/scope-narrowed hub JWT/);
   });
 
   test("typing 'paste' at the auth prompt switches to token mode + asks for token", async () => {
@@ -334,48 +321,23 @@ describe("runInteractiveInstall — decision tree", () => {
     expect(result.pastedToken).toBe("my-existing-jwt");
   });
 
-  test("typing 'legacy' at the auth prompt switches to legacy-pat with default scope", async () => {
-    const { io } = mockIO([
-      null,    // accept install-scope default
-      "legacy",
-      null,    // accept default scope (read) on the F2 scope prompt
-      true,
-    ]);
-    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:read");
-  });
-
-  test("legacy-pat path: typing 'write' on the scope prompt widens to vault:write (F2)", async () => {
+  test("typing 'legacy' at the auth prompt is no longer accepted (vault#282 Stage 2)", async () => {
+    // The 'legacy' choice was removed — the only options are mint / write /
+    // admin / paste. An unrecognized input re-prompts; we then pick paste.
     const { io, state } = mockIO([
-      null,       // accept install-scope default
-      "legacy",   // pick legacy-pat
-      "write",    // widen scope
-      true,       // proceed
+      null,              // accept install-scope default
+      "legacy",          // no longer a valid choice → validation re-prompt
+      "paste",           // pick paste
+      "my-existing-jwt", // the bearer
+      true,
     ]);
     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:write");
-    // Scope-prompt wording must match the mint path's "least privilege" framing.
-    expect(state.prompts.some((p) => /least privilege/.test(p.question))).toBe(true);
-  });
-
-  test("legacy-pat path (no-hub branch): scope prompt also fires (F2)", async () => {
-    const { io } = mockIO([
-      null,      // accept install-scope default
-      "legacy",  // pick legacy (no-hub branch)
-      "admin",   // widen scope
-      true,      // proceed
-    ]);
-    const result = await runInteractiveInstall(baseCtx({ hubReachable: false }), io);
-    expect(result).not.toBe("abort");
-    if (result === "abort") return;
-    expect(result.mode).toBe("legacy-pat");
-    expect(result.scope).toBe("vault:admin");
+    expect(result.mode).toBe("token");
+    expect(result.pastedToken).toBe("my-existing-jwt");
+    // The validator rejected 'legacy' with the expected-one-of message.
+    expect(state.logs.some((l) => /expected one of/.test(l))).toBe(true);
   });
 
   test("paste path: preview clarifies scope is determined by the pasted token (F2)", async () => {
@@ -477,10 +439,10 @@ describe("runInteractiveInstall — decision tree", () => {
     const result = await runInteractiveInstall(baseCtx(), io);
     expect(result).not.toBe("abort");
     // The help text should have been logged between the two ask calls.
-    // It enumerates the choices (mint / write / admin / paste / legacy);
-    // matching on the "Choices:" header keeps the assertion stable
-    // against future re-wording of individual lines.
-    const helpLogged = state.logs.some((l) => /Choices:/.test(l) && /paste/.test(l) && /legacy/.test(l));
+    // It enumerates the choices (mint / write / admin / paste — vault#282
+    // Stage 2 dropped the legacy pvt_* option); matching on the "Choices:"
+    // header keeps the assertion stable against future re-wording.
+    const helpLogged = state.logs.some((l) => /Choices:/.test(l) && /paste/.test(l));
     expect(helpLogged).toBe(true);
   });