perplexity-user-mcp 0.8.37 → 0.8.39

package/dist/{chunk-TQLCLE4L.mjs → chunk-S677V2JU.mjs}

@@ -3,12 +3,12 @@ import {
 } from "./chunk-MTDFKNXX.mjs";
 import {
   getProfilePaths
-} from "./chunk-XKSWCEGI.mjs";
+} from "./chunk-HJIXH6CL.mjs";
 
 // src/vault.js
 import { createCipheriv, createDecipheriv, randomBytes, hkdfSync, scrypt as nodeScrypt } from "crypto";
 import { promisify } from "util";
-import { existsSync, readFileSync, mkdirSync, rmSync } from "fs";
+import { existsSync, readFileSync, mkdirSync, renameSync, rmSync } from "fs";
 import { dirname } from "path";
 var MAGIC = Buffer.from("PXVT");
 var VERSION_V1 = 1;
@@ -255,6 +255,14 @@ async function getUnsealMaterial() {
     "Vault locked: no keychain, no env var, no TTY. Three unseal paths on Linux/headless: (a) install an OS keychain (libsecret + gnome-keyring) so the MCP process can read it, (b) set PERPLEXITY_VAULT_PASSPHRASE in your IDE's MCP server env block, or (c) run the VS Code extension's daemon and connect over HTTP transport instead of stdio. Codex CLI setup: docs/codex-cli-setup.md. Generic vault-unseal docs: docs/vault-unseal.md."
   );
 }
+async function getAllUnsealMaterials() {
+  const materials = [];
+  const fromKc = await keyFromKeychain();
+  if (fromKc) materials.push({ kind: "key", key: fromKc });
+  const envPass = process.env.PERPLEXITY_VAULT_PASSPHRASE;
+  if (envPass) materials.push({ kind: "passphrase", passphrase: envPass });
+  return materials;
+}
 async function getMasterKey() {
   if (_keyCache) return _keyCache;
   const unseal = await getUnsealMaterial();
@@ -280,16 +288,31 @@ async function readVaultObject(profileName) {
   if (!existsSync(p)) return {};
   const blob = readFileSync(p);
   const header = parseVaultHeader(blob);
-  const unseal = await getUnsealMaterial();
-  const key = await deriveKeyForHeader(header, unseal);
-  const plain = aesGcmOpen(header, key);
-  try {
-    return JSON.parse(plain.toString("utf8"));
-  } catch (err) {
-    const { redact } = await import("./redact.mjs");
-    console.error(`[vault] Corrupt vault JSON for profile ${redact(profileName)}: ${redact(err.message)}`);
-    throw new Error(`Vault for profile '${profileName}' is corrupt or unreadable.`);
+  const materials = _unsealMaterialCache ? [_unsealMaterialCache, ...(await getAllUnsealMaterials()).filter((m) => m !== _unsealMaterialCache)] : await getAllUnsealMaterials();
+  if (materials.length === 0) {
+    await getUnsealMaterial();
+    return {};
   }
+  let lastErr;
+  for (const unseal of materials) {
+    try {
+      const key = await deriveKeyForHeader(header, unseal);
+      const plain = aesGcmOpen(header, key);
+      try {
+        const parsed = JSON.parse(plain.toString("utf8"));
+        _unsealMaterialCache = unseal;
+        return parsed;
+      } catch (err) {
+        const { redact } = await import("./redact.mjs");
+        console.error(`[vault] Corrupt vault JSON for profile ${redact(profileName)}: ${redact(err.message)}`);
+        throw new Error(`Vault for profile '${profileName}' is corrupt or unreadable.`);
+      }
+    } catch (err) {
+      lastErr = err;
+      if (!/wrong passphrase or corrupted ciphertext/.test(String(err?.message ?? ""))) throw err;
+    }
+  }
+  throw lastErr ?? new Error("Vault decrypt failed: no unseal material succeeded.");
 }
 async function writeVaultObject(profileName, obj) {
   const paths = getProfilePaths(profileName);
@@ -319,7 +342,28 @@ var Vault = class {
     return obj[key] ?? null;
   }
   async set(profile, key, value) {
-    const obj = await readVaultObject(profile);
+    let obj;
+    try {
+      obj = await readVaultObject(profile);
+    } catch (err) {
+      const msg = String(err?.message ?? "");
+      if (/wrong passphrase or corrupted ciphertext|Vault decrypt failed/.test(msg)) {
+        const paths = getProfilePaths(profile);
+        if (existsSync(paths.vault)) {
+          const quarantine = `${paths.vault}.unreadable.${Date.now()}.bak`;
+          try {
+            renameSync(paths.vault, quarantine);
+          } catch {
+          }
+          console.error(
+            `[vault] WARN existing vault.enc for profile '${profile}' could not be decrypted with any available unseal material; quarantined at ${quarantine} and starting fresh. Possible cause: keychain key rotation or PERPLEXITY_VAULT_PASSPHRASE change. Original error: ${msg}`
+          );
+        }
+        obj = {};
+      } else {
+        throw err;
+      }
+    }
     obj[key] = value;
     await writeVaultObject(profile, obj);
   }
@@ -340,6 +384,7 @@ export {
   decryptBlob,
   __resetKeyCache,
   getUnsealMaterial,
+  getAllUnsealMaterials,
   getMasterKey,
   Vault
 };

package/dist/{chunk-S5VD7WTU.mjs → chunk-T6ARJK2P.mjs}

@@ -2,22 +2,22 @@ import {
   appendAuditEntry,
   getAuditLogPath,
   readAuditTail
-} from "./chunk-PE23RMXY.mjs";
+} from "./chunk-V4U3JM4R.mjs";
 import {
   ensureToken,
   getTokenPath,
   rotateToken
-} from "./chunk-HTUAQRKH.mjs";
+} from "./chunk-TDXETAQT.mjs";
 import {
   hydrateCloudHistoryEntry,
   syncCloudHistory
-} from "./chunk-Q2VY4R5F.mjs";
+} from "./chunk-2FPGJKCA.mjs";
 import {
   PerplexityClient,
   exportThreadViaImpit,
   readCachedAccountInfoFromDisk,
   retrieveThreadViaImpit
-} from "./chunk-H4BUAPPO.mjs";
+} from "./chunk-C3HPFFTD.mjs";
 import {
   append,
   findPendingByThread,
@@ -26,13 +26,13 @@ import {
   getHistoryDir,
   list,
   update
-} from "./chunk-OF4DMAPJ.mjs";
+} from "./chunk-B65IJQZJ.mjs";
 import {
   safeAtomicWriteFileSync
 } from "./chunk-MTDFKNXX.mjs";
 import {
   getConfigDir
-} from "./chunk-XKSWCEGI.mjs";
+} from "./chunk-HJIXH6CL.mjs";
 
 // src/daemon/server.ts
 import { createServer } from "http";

package/dist/{chunk-HTUAQRKH.mjs → chunk-TDXETAQT.mjs}

@@ -3,7 +3,7 @@ import {
 } from "./chunk-MTDFKNXX.mjs";
 import {
   getConfigDir
-} from "./chunk-XKSWCEGI.mjs";
+} from "./chunk-HJIXH6CL.mjs";
 
 // src/daemon/token.ts
 import { randomBytes } from "crypto";

package/dist/{chunk-LKJMLGFP.mjs → chunk-U7QPUNRH.mjs}

@@ -1,10 +1,10 @@
 import {
   Vault
-} from "./chunk-TQLCLE4L.mjs";
+} from "./chunk-S677V2JU.mjs";
 import {
   getActiveName,
   getProfilePaths
-} from "./chunk-XKSWCEGI.mjs";
+} from "./chunk-HJIXH6CL.mjs";
 
 // src/config.ts
 import { existsSync } from "fs";

package/dist/{chunk-PE23RMXY.mjs → chunk-V4U3JM4R.mjs}

@@ -1,6 +1,6 @@
 import {
   getConfigDir
-} from "./chunk-XKSWCEGI.mjs";
+} from "./chunk-HJIXH6CL.mjs";
 
 // src/daemon/audit.ts
 import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync } from "fs";

package/dist/chunk-WDIW33DA.mjs

@@ -0,0 +1,77 @@
+import {
+  getConfigDir,
+  getProfilePaths
+} from "./chunk-HJIXH6CL.mjs";
+
+// src/reinit-watcher.js
+import { existsSync, mkdirSync, watch } from "fs";
+import { dirname, join } from "path";
+function watchReinit(profileName, callback, opts = {}) {
+  const { debounceMs = 200 } = opts;
+  const target = getProfilePaths(profileName).reinit;
+  const parent = dirname(target);
+  if (!existsSync(parent)) mkdirSync(parent, { recursive: true });
+  let timer = null;
+  const w = watch(parent, { persistent: false }, (event, filename) => {
+    if (!filename) return;
+    if (!String(filename).endsWith(".reinit")) return;
+    if (!existsSync(target)) return;
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(() => {
+      timer = null;
+      try {
+        callback();
+      } catch {
+      }
+    }, debounceMs);
+  });
+  return {
+    dispose() {
+      if (timer) {
+        clearTimeout(timer);
+        timer = null;
+      }
+      try {
+        w.close();
+      } catch {
+      }
+    }
+  };
+}
+function watchActiveProfile(configDirOverride, callback, opts = {}) {
+  const { debounceMs = 200 } = opts;
+  const configDir = configDirOverride ?? getConfigDir();
+  const target = join(configDir, "active");
+  if (!existsSync(configDir)) mkdirSync(configDir, { recursive: true });
+  let timer = null;
+  const w = watch(configDir, { persistent: false }, (event, filename) => {
+    if (!filename) return;
+    if (String(filename) !== "active") return;
+    if (!existsSync(target)) return;
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(() => {
+      timer = null;
+      try {
+        callback();
+      } catch {
+      }
+    }, debounceMs);
+  });
+  return {
+    dispose() {
+      if (timer) {
+        clearTimeout(timer);
+        timer = null;
+      }
+      try {
+        w.close();
+      } catch {
+      }
+    }
+  };
+}
+
+export {
+  watchReinit,
+  watchActiveProfile
+};

package/dist/{chunk-KCXM2M4B.mjs → chunk-XTRJSV72.mjs}

@@ -3,7 +3,7 @@ import {
 } from "./chunk-6YMQVLFX.mjs";
 import {
   getTunnelBinaryPath
-} from "./chunk-3B276PGG.mjs";
+} from "./chunk-FKQ3HP4Q.mjs";
 import {
   safeAtomicWriteFileSync
 } from "./chunk-MTDFKNXX.mjs";

package/dist/cli.d.ts

@@ -62,7 +62,7 @@ function parseArgs(argv) {
 
 const KNOWN_COMMANDS = new Set([
   "server", "version", "help",
-  "login", "logout", "status", "doctor", "install-browser",
+  "login", "logout", "status", "doctor", "install-browser", "setup-vault",
   "install-speed-boost", "uninstall-speed-boost", "speed-boost-status",
   "add-account", "switch-account", "list-accounts",
   "export", "open", "rebuild-history-index", "sync-cloud",
@@ -80,6 +80,288 @@ function normalizeExportFormat(value) {
   return null;
 }
 
+/**
+ * Probe the full vault-unseal state for the current process.
+ *
+ * Returns a structured snapshot covering every input the runtime path
+ * (vault.js getUnsealMaterial) considers: keychain availability and
+ * whether the master key was persisted there, env-var passphrase, TTY
+ * fallback, and (when a profile is given) whether the on-disk vault.enc
+ * actually decrypts with the resolved unseal material. The setup-vault
+ * command and the add-account/login preflight share this so user-facing
+ * advice stays consistent with what the runner will actually do.
+ */
+async function probeVaultState({ profile } = {}) {
+  let keychainAvailable = false;
+  let keychainHasKey = false;
+  try {
+    const mod = await import('keytar');
+    const keytar = mod.default ?? mod;
+    if (keytar && typeof keytar.getPassword === "function") {
+      keychainAvailable = true;
+      try {
+        const hex = await keytar.getPassword("perplexity-user-mcp", "vault-master-key");
+        keychainHasKey = !!hex;
+      } catch {
+        // getPassword can throw on broken credstore backends (e.g. headless
+        // Linux without libsecret). The binding loaded but isn't usable —
+        // treat that as "available but no key", same posture as a fresh
+        // box. vault.js falls back to env var when keychain returns null.
+        keychainHasKey = false;
+      }
+    }
+  } catch {
+    keychainAvailable = false;
+  }
+  const envPassphraseSet = !!process.env.PERPLEXITY_VAULT_PASSPHRASE;
+  const hasTty = process.stdin?.isTTY === true && process.env.PERPLEXITY_MCP_STDIO !== "1";
+
+  let vaultExists = false;
+  let vaultDecryptsOk = null;
+  let decryptError = null;
+  if (profile) {
+    try {
+      const { getProfilePaths } = await import('./profiles.d-DqS1oZWr.d.ts');
+      const { existsSync } = await import('node:fs');
+      vaultExists = existsSync(getProfilePaths(profile).vault);
+      if (vaultExists && (keychainAvailable || envPassphraseSet)) {
+        const { Vault, __resetKeyCache } = await import('./vault.d-BSJWDLhp.d.ts');
+        __resetKeyCache();
+        try {
+          await new Vault().get(profile, "cookies");
+          vaultDecryptsOk = true;
+        } catch (err) {
+          vaultDecryptsOk = false;
+          decryptError = err instanceof Error ? err.message : String(err);
+        }
+      }
+    } catch (err) {
+      // Probe is best-effort; don't crash the CLI just because the
+      // profile dir or modules failed to load.
+      decryptError = err instanceof Error ? err.message : String(err);
+    }
+  }
+
+  return {
+    platform: process.platform,
+    keychainAvailable,
+    keychainHasKey,
+    envPassphraseSet,
+    hasTty,
+    vaultExists,
+    vaultDecryptsOk,
+    decryptError,
+  };
+}
+
+/**
+ * Surface vault-unseal status BEFORE the user kicks off an interactive
+ * operation (add-account, login). Returns {ok: true} when at least one
+ * unseal path is configured. Returns {ok: false, ...} with structured
+ * guidance when none of those are available — caller decides whether to
+ * warn-then-continue or hard-stop.
+ */
+async function checkVaultUnseal() {
+  const state = await probeVaultState();
+  if (state.keychainAvailable || state.envPassphraseSet || state.hasTty) {
+    return {
+      ok: true,
+      hasKeychain: state.keychainAvailable,
+      envPass: state.envPassphraseSet,
+      hasTty: state.hasTty,
+    };
+  }
+  const isLinux = state.platform === "linux";
+  const isMac = state.platform === "darwin";
+  const isWin = state.platform === "win32";
+  const hint = isLinux
+    ? "Install libsecret + gnome-keyring (Debian/Ubuntu: `sudo apt install libsecret-1-0 gnome-keyring`; Fedora: `sudo dnf install libsecret gnome-keyring`), OR run `npx perplexity-user-mcp setup-vault` to generate a passphrase and get persistence snippets for your shell / MCP-client config."
+    : isMac
+      ? "Keychain Access should be available on macOS — keytar usually loads here. If you still see this, run `npx perplexity-user-mcp setup-vault` for a generated passphrase + persistence snippets."
+      : isWin
+        ? "Credential Manager is always available on Windows — keytar usually loads here. If you still see this, run `npx perplexity-user-mcp setup-vault` for a generated passphrase + persistence snippets."
+        : "Run `npx perplexity-user-mcp setup-vault` for a generated passphrase + persistence snippets.";
+  return {
+    ok: false,
+    hasKeychain: false,
+    envPass: false,
+    hasTty: false,
+    reason: "no_unseal_material",
+    hint,
+  };
+}
+
+/**
+ * Generate a strong random passphrase encoded as a shell-safe base64url
+ * string (no `+`, `/`, or `=` so it can be pasted into shell rcs and JSON
+ * env blocks without escaping). 32 bytes = 256 bits of entropy, matching
+ * the AES key strength so the passphrase is never the weak link.
+ */
+async function generatePassphrase() {
+  const { randomBytes } = await import('node:crypto');
+  // base64url encoding in Node ≥16.
+  return randomBytes(32).toString("base64url");
+}
+
+/**
+ * Build platform-specific persistence snippets the user can copy into
+ * their environment. Kept format-agnostic — does NOT write any file —
+ * because the safest place to put a passphrase varies by deployment
+ * (per-IDE mcp.json env block, ~/.zshrc, systemd unit, Docker secret).
+ */
+function buildPersistenceSnippets(passphrase) {
+  const platform = process.platform;
+  const snippets = [];
+
+  // 1. MCP client env block (preferred — scoped per client).
+  snippets.push({
+    title: "MCP client env block (preferred — scoped to one client only)",
+    detail: "Edit your MCP client's config (Cursor: ~/.cursor/mcp.json, Claude Desktop: claude_desktop_config.json, Codex CLI: ~/.codex/config.toml, etc.). Add an `env` field next to `command`/`args`:",
+    code: `{
+  "mcpServers": {
+    "Perplexity": {
+      "command": "npx",
+      "args": ["-y", "perplexity-user-mcp"],
+      "env": {
+        "PERPLEXITY_VAULT_PASSPHRASE": "${passphrase}"
+      }
+    }
+  }
+}`,
+  });
+
+  // 2. Shell rc — platform-specific.
+  if (platform === "win32") {
+    snippets.push({
+      title: "Windows — PowerShell user environment (persistent)",
+      detail: "Sets the variable for your user account; persists across reboots. Open PowerShell and run:",
+      code: `[Environment]::SetEnvironmentVariable("PERPLEXITY_VAULT_PASSPHRASE", "${passphrase}", "User")`,
+    });
+    snippets.push({
+      title: "Windows — cmd.exe (persistent)",
+      detail: "Equivalent for cmd.exe users:",
+      code: `setx PERPLEXITY_VAULT_PASSPHRASE "${passphrase}"`,
+    });
+  } else if (platform === "darwin") {
+    snippets.push({
+      title: "macOS — zsh (default since Catalina)",
+      detail: "Append to ~/.zshrc and restart your terminal:",
+      code: `echo 'export PERPLEXITY_VAULT_PASSPHRASE='\\''${passphrase}'\\''' >> ~/.zshrc`,
+    });
+    snippets.push({
+      title: "macOS — bash (legacy)",
+      detail: "If you use bash instead, append to ~/.bash_profile:",
+      code: `echo 'export PERPLEXITY_VAULT_PASSPHRASE='\\''${passphrase}'\\''' >> ~/.bash_profile`,
+    });
+  } else {
+    // Linux + everything else
+    snippets.push({
+      title: "Linux — bash",
+      detail: "Append to ~/.bashrc and restart your terminal (or `source ~/.bashrc`):",
+      code: `echo 'export PERPLEXITY_VAULT_PASSPHRASE='\\''${passphrase}'\\''' >> ~/.bashrc`,
+    });
+    snippets.push({
+      title: "Linux — zsh",
+      detail: "If you use zsh, append to ~/.zshrc:",
+      code: `echo 'export PERPLEXITY_VAULT_PASSPHRASE='\\''${passphrase}'\\''' >> ~/.zshrc`,
+    });
+    snippets.push({
+      title: "Linux — systemd unit (for daemon deployments)",
+      detail: "If you run perplexity-user-mcp as a systemd service, add to the [Service] block:",
+      code: `Environment=PERPLEXITY_VAULT_PASSPHRASE=${passphrase}`,
+    });
+  }
+
+  return snippets;
+}
+
+/**
+ * Render a plain-text setup-vault report. Used for the default human-
+ * readable output. JSON output uses `--json` and bypasses this entirely.
+ */
+function renderSetupVaultReport({ state, recommendation, passphrase, snippets }) {
+  const lines = [];
+  const tick = "✓";
+  const cross = "✗";
+  const warn = "!";
+  lines.push("Vault setup status:");
+  lines.push(`  ${state.keychainAvailable ? tick : cross} OS keychain ${state.keychainAvailable ? "available" : "unavailable"}${state.keychainHasKey ? " (master key persisted)" : state.keychainAvailable ? " (no master key yet — will be generated on first login)" : ""}`);
+  lines.push(`  ${state.envPassphraseSet ? tick : cross} PERPLEXITY_VAULT_PASSPHRASE ${state.envPassphraseSet ? "is set" : "is not set"}`);
+  if (state.vaultExists) {
+    if (state.vaultDecryptsOk === true) {
+      lines.push(`  ${tick} vault.enc decrypts cleanly with the active unseal material`);
+    } else if (state.vaultDecryptsOk === false) {
+      lines.push(`  ${cross} vault.enc cannot be decrypted — ${state.decryptError ?? "unknown error"}`);
+    }
+  }
+  if (state.keychainAvailable && state.envPassphraseSet) {
+    lines.push(`  ${warn} both keychain and env var are set — keychain wins at runtime; the env var is a fallback`);
+  }
+  lines.push("");
+  lines.push(`Recommendation: ${recommendation.message}`);
+
+  if (passphrase) {
+    lines.push("");
+    lines.push("Generated passphrase (256 bits, base64url):");
+    lines.push(`  ${passphrase}`);
+    lines.push("");
+    lines.push("⚠  Save this somewhere safe — losing it means losing access to vaults written under it.");
+    lines.push("");
+    lines.push("Pick ONE persistence method below:");
+    snippets.forEach((s, i) => {
+      lines.push("");
+      lines.push(`${i + 1}. ${s.title}`);
+      if (s.detail) lines.push(`   ${s.detail}`);
+      lines.push("");
+      const indent = "     ";
+      lines.push(s.code.split("\n").map((l) => indent + l).join("\n"));
+    });
+    lines.push("");
+    lines.push("After applying ONE of those, run `npx perplexity-user-mcp doctor` to verify the unseal-verify check passes.");
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Decide what the user should do given the probed vault state.
+ *
+ * - keychain works + vault decrypts (or no vault yet) → nothing to do.
+ * - keychain works + vault fails to decrypt → tell user to logout --purge.
+ * - no keychain + env var set → done; vault will use passphrase.
+ * - no keychain + no env var → setup needed; generate + show snippets.
+ */
+function recommendVaultSetup(state) {
+  if (state.vaultExists && state.vaultDecryptsOk === false) {
+    return {
+      status: "decrypt_broken",
+      message: "Existing vault.enc cannot be decrypted with any available unseal material. The blob was likely written under a since-rotated keychain key or PERPLEXITY_VAULT_PASSPHRASE. Run `npx perplexity-user-mcp logout --purge --profile <name>` and log in again to write a fresh vault. (v0.8.40+ self-heals this on the next login by quarantining the bad blob.)",
+      generatePassphrase: false,
+    };
+  }
+  if (state.keychainAvailable) {
+    return {
+      status: "ok_keychain",
+      message: state.keychainHasKey
+        ? "OS keychain holds the master key — nothing to do."
+        : "OS keychain is available; the master key will be generated and persisted there on your first login. Nothing to do.",
+      generatePassphrase: false,
+    };
+  }
+  if (state.envPassphraseSet) {
+    return {
+      status: "ok_envvar",
+      message: "PERPLEXITY_VAULT_PASSPHRASE is set; the vault will use it. (For better UX, install an OS keychain so the env var becomes optional — see https://github.com/Automations-Project/VSCode-Perplexity-MCP for platform docs.)",
+      generatePassphrase: false,
+    };
+  }
+  return {
+    status: "setup_needed",
+    message: "No keychain available and no PERPLEXITY_VAULT_PASSPHRASE set. Generating a strong passphrase and showing persistence snippets below.",
+    generatePassphrase: true,
+  };
+}
+
 async function openTarget(target) {
   if (process.platform === "win32") {
     const escaped = String(target).replace(/'/g, "''");
@@ -478,9 +760,50 @@ async function routeCommand(parsed) {
     return { code: 0, stdout: body + "\n", stderr: "" };
   }
 
+  if (command === "setup-vault") {
+    const profile = flags.profile ?? (await import('./profiles.d-DqS1oZWr.d.ts')).getActiveName() ?? null;
+    const state = await probeVaultState({ profile });
+    const recommendation = recommendVaultSetup(state);
+    let passphrase = null;
+    let snippets = [];
+    if (recommendation.generatePassphrase && !flags["probe-only"]) {
+      passphrase = await generatePassphrase();
+      snippets = buildPersistenceSnippets(passphrase);
+    }
+    if (flags.json) {
+      const body = JSON.stringify({
+        ok: true,
+        state,
+        recommendation: { status: recommendation.status, message: recommendation.message },
+        passphrase: passphrase ?? null,
+        snippets: snippets.map((s) => ({ title: s.title, detail: s.detail, code: s.code })),
+      });
+      return { code: 0, stdout: body + "\n", stderr: "" };
+    }
+    const report = renderSetupVaultReport({ state, recommendation, passphrase, snippets });
+    return { code: 0, stdout: report + "\n", stderr: "" };
+  }
+
   if (command === "add-account") {
     const name = flags.name ?? (await import('./profiles.d-DqS1oZWr.d.ts')).suggestNextDefaultName();
     const mode = flags.mode ?? "manual";
+
+    // Pre-flight the unseal chain BEFORE touching the profile dir, so users
+    // creating a new account on a fresh box get an actionable setup hint
+    // instead of a "Vault decrypt failed" / "Vault locked" surprise on the
+    // first login. Bypass with --skip-vault-check (e.g. when the daemon
+    // owns the vault and the CLI is just used for account management).
+    if (!flags["skip-vault-check"]) {
+      const unseal = await checkVaultUnseal();
+      if (!unseal.ok) {
+        const msg = `No vault unseal path configured. ${unseal.hint}`;
+        const body = flags.json
+          ? JSON.stringify({ ok: false, reason: unseal.reason, hint: unseal.hint })
+          : "";
+        return { code: 1, stdout: body + (body ? "\n" : ""), stderr: msg + "\n" };
+      }
+    }
+
     try {
       const { createProfile } = await import('./profiles.d-DqS1oZWr.d.ts');
       const profile = createProfile(name, { loginMode: mode });
@@ -515,7 +838,7 @@ async function routeCommand(parsed) {
 
   if (command === "status") {
     const name = flags.profile ?? (await import('./profiles.d-DqS1oZWr.d.ts')).getActiveName() ?? "default";
-    const { Vault } = await import('./vault.d-BtRSLZiM.d.ts');
+    const { Vault } = await import('./vault.d-BSJWDLhp.d.ts');
     /* v8 ignore next -- defensive catch for unreadable vault (malformed blob, wrong key) */
     const cookies = await new Vault().get(name, "cookies").catch(() => null);
     if (!cookies) {
@@ -535,6 +858,22 @@ async function routeCommand(parsed) {
     const { fork } = await import('node:child_process');
     const mode = flags.mode ?? "manual";
     const profile = flags.profile ?? (await import('./profiles.d-DqS1oZWr.d.ts')).getActiveName() ?? "default";
+
+    // Same preflight as add-account: surface unseal-path setup BEFORE the
+    // browser opens, so a user on a fresh headless box doesn't complete a
+    // 30s login flow only to crash at vault.set with a stack trace. Skip
+    // when --plain-cookies is set since plaintext mode bypasses the vault.
+    if (!flags["plain-cookies"] && !flags["skip-vault-check"]) {
+      const unseal = await checkVaultUnseal();
+      if (!unseal.ok) {
+        const msg = `No vault unseal path configured for profile '${profile}'. ${unseal.hint}`;
+        const body = flags.json
+          ? JSON.stringify({ ok: false, reason: unseal.reason, hint: unseal.hint, profile })
+          : "";
+        return { code: 1, stdout: body + (body ? "\n" : ""), stderr: msg + "\n" };
+      }
+    }
+
     const env = { ...process.env, PERPLEXITY_PROFILE: profile };
     if (mode === "auto") {
       if (!flags.email) return { code: 1, stdout: "", stderr: "`--email` required for --mode auto.\n" };
@@ -881,6 +1220,13 @@ Usage:
   npx perplexity-user-mcp status [--profile X] [--all]
   npx perplexity-user-mcp doctor [--profile X] [--probe] [--all] [--report]
   npx perplexity-user-mcp install-browser
+  npx perplexity-user-mcp setup-vault [--profile X] [--json] [--probe-only]
+      Probe the vault unseal chain (OS keychain / PERPLEXITY_VAULT_PASSPHRASE)
+      and, when neither is configured, generate a strong passphrase and print
+      cross-platform persistence snippets (PowerShell / setx / zsh / bash /
+      systemd / MCP-client env block). Read-only — never writes any file.
+      Cross-platform: Windows, macOS, Linux. Add --probe-only to skip
+      passphrase generation and just report state.
   npx perplexity-user-mcp install-speed-boost [--force] [--json]
   npx perplexity-user-mcp uninstall-speed-boost [--json]
   npx perplexity-user-mcp speed-boost-status [--json]