@yawlabs/mcp 0.60.6 → 0.62.0

package/dist/index.js

@@ -17,7 +17,7 @@ import {
   signIn,
   signOut,
   userConfigDir
-} from "./chunk-I5625HJE.js";
+} from "./chunk-WORQOSXT.js";
 
 // src/audit-cmd.ts
 import { homedir as homedir3 } from "os";
@@ -73,9 +73,49 @@ function stripJsoncComments(src) {
   }
   return out;
 }
+function stripTrailingCommas(src) {
+  let out = "";
+  let i = 0;
+  const len = src.length;
+  let inString = false;
+  let stringChar = "";
+  while (i < len) {
+    const c = src[i];
+    if (inString) {
+      out += c;
+      if (c === "\\" && i + 1 < len) {
+        out += src[i + 1];
+        i += 2;
+        continue;
+      }
+      if (c === stringChar) inString = false;
+      i++;
+      continue;
+    }
+    if (c === '"' || c === "'") {
+      inString = true;
+      stringChar = c;
+      out += c;
+      i++;
+      continue;
+    }
+    if (c === ",") {
+      let j = i + 1;
+      while (j < len && (src[j] === " " || src[j] === "	" || src[j] === "\r" || src[j] === "\n")) j++;
+      if (j < len && (src[j] === "]" || src[j] === "}")) {
+        out += " ";
+        i++;
+        continue;
+      }
+    }
+    out += c;
+    i++;
+  }
+  return out;
+}
 function parseJsonc(src) {
   const debommed = src.charCodeAt(0) === 65279 ? src.slice(1) : src;
-  const stripped = stripJsoncComments(debommed);
+  const stripped = stripTrailingCommas(stripJsoncComments(debommed));
   return JSON.parse(stripped);
 }
 
@@ -97,10 +137,10 @@ function validateEntry(entry) {
   return { grade, score, gradedAt };
 }
 async function readGradesCache(home = homedir()) {
-  const path3 = gradesCachePath(home);
+  const path5 = gradesCachePath(home);
   let raw;
   try {
-    raw = await readFile(path3, "utf8");
+    raw = await readFile(path5, "utf8");
   } catch {
     return {};
   }
@@ -109,7 +149,7 @@ async function readGradesCache(home = homedir()) {
     parsed = parseJsonc(raw);
   } catch (err) {
     log("warn", "grades.json is not valid JSON; ignoring", {
-      path: path3,
+      path: path5,
       error: err instanceof Error ? err.message : String(err)
     });
     return {};
@@ -123,12 +163,12 @@ async function readGradesCache(home = homedir()) {
   return out;
 }
 async function writeGrade(namespace, grade, home = homedir()) {
-  const path3 = gradesCachePath(home);
+  const path5 = gradesCachePath(home);
   const cache = await readGradesCache(home);
   cache[namespace] = grade;
-  await atomicWriteFile(path3, `${JSON.stringify(cache, null, 2)}
+  await atomicWriteFile(path5, `${JSON.stringify(cache, null, 2)}
 `);
-  return path3;
+  return path5;
 }
 
 // src/local-bundles.ts
@@ -180,36 +220,43 @@ function validateEntry2(entry, warnings) {
     description
   };
 }
-async function readBundlesAt(path3, warnings) {
+async function readBundlesAt(path5, warnings) {
   let raw;
   try {
-    raw = await readFile2(path3, "utf8");
-  } catch {
-    return { exists: false, file: null };
+    raw = await readFile2(path5, "utf8");
+  } catch (err) {
+    const code = err.code;
+    if (code === "ENOENT" || code === "EISDIR") {
+      return { exists: false, file: null };
+    }
+    const msg = err instanceof Error ? err.message : String(err);
+    warnings.push(`${path5}: could not read file (${msg}) -- skipping`);
+    log("warn", "Could not read bundles.json", { path: path5, error: msg, code });
+    return { exists: true, file: null };
   }
   let parsed;
   try {
     parsed = parseJsonc(raw);
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
-    warnings.push(`${path3}: invalid JSON (${msg}) -- file ignored`);
-    log("warn", "bundles.json is not valid JSON; ignoring", { path: path3, error: msg });
+    warnings.push(`${path5}: invalid JSON (${msg}) -- file ignored`);
+    log("warn", "bundles.json is not valid JSON; ignoring", { path: path5, error: msg });
     return { exists: true, file: null };
   }
   if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-    warnings.push(`${path3}: root must be a JSON object -- file ignored`);
+    warnings.push(`${path5}: root must be a JSON object -- file ignored`);
     return { exists: true, file: null };
   }
   const obj = parsed;
   const version = typeof obj.version === "number" ? obj.version : void 0;
   if (version !== void 0 && version > CURRENT_BUNDLES_SCHEMA_VERSION) {
     warnings.push(
-      `${path3}: schema version ${version} is newer than this yaw-mcp (${CURRENT_BUNDLES_SCHEMA_VERSION}); upgrade with \`npm i -g @yawlabs/mcp@latest\`. Loading best-effort.`
+      `${path5}: schema version ${version} is newer than this yaw-mcp (${CURRENT_BUNDLES_SCHEMA_VERSION}); upgrade with \`npm i -g @yawlabs/mcp@latest\`. Loading best-effort.`
     );
   }
   const rawServers = obj.servers;
   if (!Array.isArray(rawServers)) {
-    warnings.push(`${path3}: 'servers' must be an array -- file ignored`);
+    warnings.push(`${path5}: 'servers' must be an array -- file ignored`);
     return { exists: true, file: null };
   }
   return {
@@ -257,6 +304,7 @@ async function loadLocalBundles(opts = {}) {
     warnings
   };
 }
+var bundleWriteChain = Promise.resolve();
 function deriveNamespace(name) {
   let ns = name.toLowerCase().replace(/[^a-z0-9]+/g, "");
   if (ns.length === 0) return "server";
@@ -265,21 +313,34 @@ function deriveNamespace(name) {
   return ns;
 }
 async function readRawUserBundles(home) {
-  const path3 = localBundlesPath(userConfigDir(home));
-  if (!existsSync(path3)) {
+  const path5 = localBundlesPath(userConfigDir(home));
+  if (!existsSync(path5)) {
     return { version: CURRENT_BUNDLES_SCHEMA_VERSION, servers: [] };
   }
   const warnings = [];
-  const r = await readBundlesAt(path3, warnings);
+  const r = await readBundlesAt(path5, warnings);
   if (!r.file) {
-    const detail = warnings.length > 0 ? ` (${warnings.join("; ")})` : "";
-    throw new Error(`${path3} is malformed${detail}; fix it by hand before adding servers.`);
+    const warningText = warnings.join("; ");
+    const isReadError = /EPERM|EACCES|could not read/i.test(warningText);
+    if (isReadError) {
+      throw new Error(`${path5} could not be read (${warningText}) -- check file permissions before adding servers.`);
+    }
+    const detail = warnings.length > 0 ? ` (${warningText})` : "";
+    throw new Error(`${path5} could not be parsed -- fix the JSON${detail} before adding servers.`);
   }
   return { version: r.file.version ?? CURRENT_BUNDLES_SCHEMA_VERSION, servers: r.file.servers };
 }
-async function upsertUserBundle(entry, opts = {}) {
+function upsertUserBundle(entry, opts = {}) {
+  const result = bundleWriteChain.then(() => doUpsertUserBundle(entry, opts));
+  bundleWriteChain = result.then(
+    () => void 0,
+    () => void 0
+  );
+  return result;
+}
+async function doUpsertUserBundle(entry, opts) {
   const home = opts.home ?? homedir2();
-  const path3 = localBundlesPath(userConfigDir(home));
+  const path5 = localBundlesPath(userConfigDir(home));
   const file = await readRawUserBundles(home);
   const idx = file.servers.findIndex(
     (s) => s?.namespace === entry.namespace || entry.name != null && s?.name === entry.name
@@ -288,22 +349,30 @@ async function upsertUserBundle(entry, opts = {}) {
   if (replaced) file.servers[idx] = entry;
   else file.servers.push(entry);
   file.version = file.version ?? CURRENT_BUNDLES_SCHEMA_VERSION;
-  await atomicWriteFile(path3, `${JSON.stringify(file, null, 2)}
+  await atomicWriteFile(path5, `${JSON.stringify(file, null, 2)}
 `);
-  return { path: path3, replaced };
+  return { path: path5, replaced };
+}
+function removeUserBundle(namespace, opts = {}) {
+  const result = bundleWriteChain.then(() => doRemoveUserBundle(namespace, opts));
+  bundleWriteChain = result.then(
+    () => void 0,
+    () => void 0
+  );
+  return result;
 }
-async function removeUserBundle(namespace, opts = {}) {
+async function doRemoveUserBundle(namespace, opts) {
   const home = opts.home ?? homedir2();
-  const path3 = localBundlesPath(userConfigDir(home));
-  if (!existsSync(path3)) return { path: path3, removed: false };
+  const path5 = localBundlesPath(userConfigDir(home));
+  if (!existsSync(path5)) return { path: path5, removed: false };
   const file = await readRawUserBundles(home);
   const before = file.servers.length;
   file.servers = file.servers.filter((s) => s?.namespace !== namespace);
-  if (file.servers.length === before) return { path: path3, removed: false };
+  if (file.servers.length === before) return { path: path5, removed: false };
   file.version = file.version ?? CURRENT_BUNDLES_SCHEMA_VERSION;
-  await atomicWriteFile(path3, `${JSON.stringify(file, null, 2)}
+  await atomicWriteFile(path5, `${JSON.stringify(file, null, 2)}
 `);
-  return { path: path3, removed: true };
+  return { path: path5, removed: true };
 }
 async function findShadowingProjectBundles(cwd, home = homedir2()) {
   const projectDir = await findProjectConfigDir(cwd, home).catch(() => null);
@@ -385,11 +454,11 @@ async function runAudit(opts = {}) {
     return { exitCode: 1, lines };
   }
   const home = opts.home ?? homedir3();
-  const { config, path: path3 } = await loadLocalBundles({ cwd: opts.cwd, home });
+  const { config, path: path5 } = await loadLocalBundles({ cwd: opts.cwd, home });
   const servers = config?.servers ?? [];
   const server = findServer(servers, namespace);
   if (!server) {
-    const where = path3 ? ` (${path3})` : "";
+    const where = path5 ? ` (${path5})` : "";
     printErr(
       `yaw-mcp audit: no server named "${namespace}" in bundles.json${where}. Run \`yaw-mcp list\` to see configured servers.`
     );
@@ -495,7 +564,7 @@ function matchBundles(installedNamespaces) {
   return { ready, partial };
 }
 function bundleActivateHint(bundle) {
-  return `mcp_connect_activate({ namespaces: ${JSON.stringify(bundle.namespaces)} })`;
+  return `mcp_connect_activate({ servers: ${JSON.stringify(bundle.namespaces)} })`;
 }
 function topPartialBundles(installedNamespaces, limit) {
   if (limit <= 0) return [];
@@ -510,19 +579,19 @@ function topPartialBundles(installedNamespaces, limit) {
 // src/config-loader.ts
 import { readFile as readFile3, stat as stat2 } from "fs/promises";
 import { homedir as homedir4 } from "os";
-import { join as join4, resolve } from "path";
+import { join as join4, resolve as resolve2 } from "path";
 
 // src/migrate.ts
 import { mkdir, rename, stat } from "fs/promises";
-import { dirname, join as join3 } from "path";
+import { dirname, join as join3, resolve } from "path";
 var LEGACY_GLOBAL_FILENAME = ".yaw-mcp.json";
 var LEGACY_PROJECT_FILENAME = ".yaw-mcp.json";
 var LEGACY_LOCAL_FILENAME = ".yaw-mcp.local.json";
 var NEW_CONFIG_FILENAME = "config.json";
 var NEW_LOCAL_FILENAME = "config.local.json";
-async function exists(path3) {
+async function exists(path5) {
   try {
-    await stat(path3);
+    await stat(path5);
     return true;
   } catch {
     return false;
@@ -573,9 +642,8 @@ async function migrateLegacyConfigPaths(opts) {
   }
 }
 async function findLegacyProjectRoot(cwd, home) {
-  const { resolve: resolve5, dirname: dirname5 } = await import("path");
-  const homeResolved = resolve5(home);
-  let dir = resolve5(cwd);
+  const homeResolved = resolve(home);
+  let dir = resolve(cwd);
   let prev = "";
   while (dir !== prev) {
     if (dir === homeResolved) return null;
@@ -583,7 +651,7 @@ async function findLegacyProjectRoot(cwd, home) {
     const legacyLocal = join3(dir, LEGACY_LOCAL_FILENAME);
     if (await exists(legacyProject) || await exists(legacyLocal)) return dir;
     prev = dir;
-    dir = dirname5(dir);
+    dir = dirname(dir);
   }
   return null;
 }
@@ -593,10 +661,10 @@ var CONFIG_FILENAME = "config.json";
 var LOCAL_CONFIG_FILENAME = "config.local.json";
 var CURRENT_SCHEMA_VERSION = 1;
 var DEFAULT_API_BASE = "https://yaw.sh/mcp";
-async function readConfigAt(path3, scope, warnings) {
+async function readConfigAt(path5, scope, warnings) {
   let raw;
   try {
-    raw = await readFile3(path3, "utf8");
+    raw = await readFile3(path5, "utf8");
   } catch {
     return null;
   }
@@ -605,19 +673,19 @@ async function readConfigAt(path3, scope, warnings) {
     parsed = parseJsonc(raw);
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
-    warnings.push(`${path3}: invalid JSON (${msg}) \u2014 file ignored`);
-    log("warn", "Config file is not valid JSON; ignoring", { path: path3, error: msg });
+    warnings.push(`${path5}: invalid JSON (${msg}) \u2014 file ignored`);
+    log("warn", "Config file is not valid JSON; ignoring", { path: path5, error: msg });
     return null;
   }
   if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-    warnings.push(`${path3}: root must be a JSON object \u2014 file ignored`);
+    warnings.push(`${path5}: root must be a JSON object \u2014 file ignored`);
     return null;
   }
   const obj = parsed;
   const version = typeof obj.version === "number" ? obj.version : void 0;
   if (version !== void 0 && version > CURRENT_SCHEMA_VERSION) {
     warnings.push(
-      `${path3}: schema version ${version} is newer than this yaw-mcp (${CURRENT_SCHEMA_VERSION}); upgrade with \`npm i -g @yawlabs/mcp@latest\`. Loading best-effort.`
+      `${path5}: schema version ${version} is newer than this yaw-mcp (${CURRENT_SCHEMA_VERSION}); upgrade with \`npm i -g @yawlabs/mcp@latest\`. Loading best-effort.`
     );
   }
   const token5 = typeof obj.token === "string" && obj.token.length > 0 ? obj.token : void 0;
@@ -627,21 +695,21 @@ async function readConfigAt(path3, scope, warnings) {
   if (token5) {
     if (scope === "project") {
       warnings.push(
-        `${path3}: 'token' should not appear in a project-shared file. Move it to ${CONFIG_DIRNAME}/${LOCAL_CONFIG_FILENAME} (gitignored) or ~/${CONFIG_DIRNAME}/${CONFIG_FILENAME}.`
+        `${path5}: 'token' found in a project-shared config file is IGNORED -- yaw-mcp never reads a token from this scope to avoid committing credentials. Move it to ${CONFIG_DIRNAME}/${LOCAL_CONFIG_FILENAME} (machine-local, gitignore by convention) or ~/${CONFIG_DIRNAME}/${CONFIG_FILENAME} (user-global).`
       );
     }
-    await checkPermissions(path3, warnings);
+    await checkPermissions(path5, warnings);
   }
-  return { path: path3, scope, version, token: token5, apiBase, servers, blocked };
+  return { path: path5, scope, version, token: token5, apiBase, servers, blocked };
 }
-async function checkPermissions(path3, warnings) {
+async function checkPermissions(path5, warnings) {
   if (process.platform === "win32") return;
   try {
-    const st = await stat2(path3);
+    const st = await stat2(path5);
     const mode = st.mode & 511;
     if ((mode & 63) !== 0) {
       warnings.push(
-        `${path3}: contains a token but is readable by group/other (mode ${mode.toString(8)}). Run \`chmod 600 ${path3}\` to restrict.`
+        `${path5}: contains a token but is readable by group/other (mode ${mode.toString(8)}). Run \`chmod 600 ${path5}\` to restrict.`
       );
     }
   } catch {
@@ -666,8 +734,8 @@ function unionBlocked(files) {
   return touched ? [...set] : void 0;
 }
 async function loadYawMcpConfig(opts = {}) {
-  const cwd = resolve(opts.cwd ?? process.cwd());
-  const home = resolve(opts.home ?? homedir4());
+  const cwd = resolve2(opts.cwd ?? process.cwd());
+  const home = resolve2(opts.home ?? homedir4());
   const env = opts.env ?? process.env;
   const warnings = [];
   const loadedFiles = [];
@@ -684,7 +752,11 @@ async function loadYawMcpConfig(opts = {}) {
   const globalPath = join4(globalDir, CONFIG_FILENAME);
   const local = localPath ? await readConfigAt(localPath, "local", warnings) : null;
   if (local) loadedFiles.push(local);
-  const projectIsGlobal = projectConfigDir !== null && projectConfigDir === globalDir;
+  const normalizeDir = (d) => {
+    const r = resolve2(d);
+    return process.platform === "win32" ? r.toLowerCase() : r;
+  };
+  const projectIsGlobal = projectConfigDir !== null && normalizeDir(projectConfigDir) === normalizeDir(globalDir);
   const project = projectIsGlobal || !projectPath ? null : await readConfigAt(projectPath, "project", warnings);
   if (project) loadedFiles.push(project);
   const global = await readConfigAt(globalPath, "global", warnings);
@@ -804,9 +876,9 @@ async function fetchConfig(apiUrl5, token5, currentVersion) {
     await res.body.text().catch(() => {
     });
     throw new ConfigError(
-      `Access denied (HTTP 403) \u2014 the token ${tokenFingerprint(token5)} was accepted but lacks permission to read this account's servers.
-  The account may be suspended or the token scope reduced \u2014 check
-  https://yaw.sh/mcp/dashboard/settings/tokens, or reach support@mcp.hosting.`,
+      `Access denied (HTTP 403) -- the token ${tokenFingerprint(token5)} was accepted but lacks permission to read this account's servers.
+  The account may be suspended or the token scope reduced -- check
+  https://yaw.sh/mcp/dashboard/settings/tokens, or reach support@yaw.sh.`,
       true
     );
   }
@@ -825,9 +897,8 @@ async function fetchConfig(apiUrl5, token5, currentVersion) {
     }
     return true;
   });
-  const NAMESPACE_RE3 = /^[a-z][a-z0-9_]{0,29}$/;
   data.servers = data.servers.filter((s) => {
-    if (!s.namespace || !NAMESPACE_RE3.test(s.namespace)) {
+    if (!s.namespace || !NAMESPACE_RE.test(s.namespace)) {
       log("warn", "Skipping server with invalid namespace", { namespace: s.namespace, name: s.name });
       return false;
     }
@@ -862,7 +933,7 @@ function parseBundlesArgs(argv) {
     if (a === "--json") {
       json = true;
     } else if (a === "--help" || a === "-h") {
-      return { ok: false, error: BUNDLES_USAGE };
+      return { ok: false, error: BUNDLES_USAGE, help: true };
     } else if (a === "list" || a === "match") {
       if (actionSet) {
         return {
@@ -926,7 +997,7 @@ async function runBundlesCommand(opts = {}) {
     return { exitCode: 2, lines };
   }
   if (!backend) {
-    printErr("yaw-mcp bundles match: backend returned no data (unexpected 304).");
+    printErr("yaw-mcp bundles match: backend returned 304 without a conditional request.");
     return { exitCode: 2, lines };
   }
   const installed = backend.servers.filter((s) => s.isActive).map((s) => s.namespace);
@@ -1065,20 +1136,27 @@ var SUBCOMMAND_SPEC = [
     positional: ["push", "pull", "status"],
     flags: ["--key", "--json", "--help"]
   },
-  { name: "stats", description: "Show usage statistics", flags: ["--key", "--limit", "--days", "--json", "--help"] },
+  { name: "stats", description: "Show usage statistics", flags: ["--limit", "--days", "--json", "--help"] },
   {
     name: "secrets",
     description: "Manage stored secrets",
     positional: ["set", "get", "list", "remove", "lock", "push", "pull"],
     flags: ["--key", "--value", "--stdin", "--json", "--help"]
   },
+  {
+    name: "set-active",
+    description: "Enable/disable a team server (authoritative)",
+    positional: ["<namespace>", "on", "off"],
+    flags: ["--json", "--help"]
+  },
   // Other.
+  { name: "audit", description: "Run a full-pass audit of loaded servers", flags: ["--json", "--help"] },
   { name: "compliance", description: "Run the compliance suite against a server", flags: ["--publish", "--help"] },
   { name: "help", description: "Show usage", flags: [] }
 ];
 function parseCompletionArgs(argv) {
   if (argv.includes("--help") || argv.includes("-h")) {
-    return { ok: false, error: COMPLETION_USAGE };
+    return { ok: false, error: COMPLETION_USAGE, help: true };
   }
   const positional = argv.filter((a) => !a.startsWith("-"));
   if (positional.length === 0) {
@@ -1275,10 +1353,16 @@ async function runComplianceCommand(argv) {
   if (publish) {
     const result = await publishReport(apiUrl5, report);
     if (!result) return 1;
+    const reportUrl = typeof result.reportUrl === "string" ? result.reportUrl.trim() : "";
+    const badgeUrl = typeof result.badgeUrl === "string" ? result.badgeUrl.trim() : "";
+    if (!reportUrl || !badgeUrl) {
+      process.stderr.write("\nPublish failed: server returned 200 but no report/badge URL.\n");
+      return 1;
+    }
     process.stdout.write(`
-Published: ${result.reportUrl}
+Published: ${reportUrl}
 `);
-    process.stdout.write(`Badge:     ${result.badgeUrl}
+    process.stdout.write(`Badge:     ${badgeUrl}
 `);
     if (result.deleteToken) {
       process.stdout.write(`
@@ -1289,7 +1373,7 @@ Delete token (save this): ${result.deleteToken}
   return 0;
 }
 function runTest(args) {
-  return new Promise((resolve5) => {
+  return new Promise((resolve7) => {
     const child = spawn("npx", ["-y", "@yawlabs/mcp-compliance", "test", "--format", "json", ...args], {
       stdio: ["ignore", "pipe", "inherit"],
       shell: process.platform === "win32"
@@ -1302,7 +1386,7 @@ function runTest(args) {
       process.stderr.write(`
 Failed to launch mcp-compliance: ${err.message}
 `);
-      resolve5(null);
+      resolve7(null);
     });
     child.on("close", (code) => {
       try {
@@ -1311,15 +1395,15 @@ Failed to launch mcp-compliance: ${err.message}
           process.stderr.write(`
 mcp-compliance returned unexpected JSON (exit ${code}).
 `);
-          resolve5(null);
+          resolve7(null);
           return;
         }
-        resolve5(parsed);
+        resolve7(parsed);
       } catch {
         process.stderr.write(`
 mcp-compliance exited ${code} without valid JSON output.
 `);
-        resolve5(null);
+        resolve7(null);
       }
     });
   });
@@ -1328,7 +1412,7 @@ function printSummary(report) {
   const { grade, score, summary, url } = report;
   process.stdout.write(
     `
-Compliance: ${grade} (${score.toFixed(1)}%) \u2014 ${summary.passed}/${summary.total} passed, ${summary.requiredPassed}/${summary.required} required
+Compliance: ${grade} (${score.toFixed(1)}%) -- ${summary.passed}/${summary.total} passed, ${summary.requiredPassed}/${summary.required} required
 Target: ${url}
 `
   );
@@ -1343,15 +1427,16 @@ async function publishReport(apiUrl5, report) {
     if (res.statusCode !== 200) {
       const body = await res.body.text().catch(() => "");
       process.stderr.write(`
-Publish failed: HTTP ${res.statusCode}${body ? ` \u2014 ${body}` : ""}
+Publish failed: HTTP ${res.statusCode}${body ? ` -- ${body}` : ""}
 `);
       return null;
     }
     const parsed = await res.body.json();
     return parsed;
   } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
     process.stderr.write(`
-Publish failed: ${err?.message ?? String(err)}
+Publish failed: ${message}
 `);
     return null;
   }
@@ -1359,7 +1444,7 @@ Publish failed: ${err?.message ?? String(err)}
 
 // src/doctor-cmd.ts
 import { existsSync as existsSync4, readFileSync, statSync } from "fs";
-import { readFile as readFile7 } from "fs/promises";
+import { readFile as readFile7, stat as stat3 } from "fs/promises";
 import { homedir as homedir8 } from "os";
 import { join as join8 } from "path";
 
@@ -1494,6 +1579,7 @@ function initAnalytics(url, tok) {
   token = tok;
   lastLoggedConnectStatus = null;
   lastLoggedDispatchStatus = null;
+  teamAnalyticsDisabled = false;
   flushTimer = setInterval(() => {
     flush().catch(() => {
     });
@@ -1669,7 +1755,7 @@ function formatShadowLine(server) {
 
 // src/install-targets.ts
 import { homedir as homedir5 } from "os";
-import { join as join5 } from "path";
+import { isAbsolute, join as join5, resolve as resolve3 } from "path";
 var CURRENT_OS = process.platform === "darwin" ? "macos" : process.platform === "win32" ? "windows" : "linux";
 var INSTALL_TARGETS = [
   {
@@ -1763,10 +1849,11 @@ function resolveInstallPath(opts) {
   if (scopeSpec.requiresProjectDir && !projectDir) {
     throw new Error(`Scope ${scope} for ${clientId} requires a project directory`);
   }
+  const absoluteProjectDir = projectDir && !isAbsolute(projectDir) ? resolve3(projectDir) : projectDir;
   const p = pathFor(clientId, scope, os, {
     home,
     appData,
-    projectDir: projectDir ?? "",
+    projectDir: absoluteProjectDir ?? "",
     claudeConfigDir: claudeConfigDir && claudeConfigDir.length > 0 ? claudeConfigDir : void 0
   });
   return p;
@@ -1929,7 +2016,8 @@ function sanitizeLearning(input) {
     if (typeof u.dispatched !== "number" || !Number.isFinite(u.dispatched) || u.dispatched < 0) continue;
     if (typeof u.succeeded !== "number" || !Number.isFinite(u.succeeded) || u.succeeded < 0) continue;
     if (typeof u.lastUsedAt !== "number" || !Number.isFinite(u.lastUsedAt) || u.lastUsedAt < 0) continue;
-    out[k] = { dispatched: u.dispatched, succeeded: u.succeeded, lastUsedAt: u.lastUsedAt };
+    const succeeded = Math.min(u.succeeded, u.dispatched);
+    out[k] = { dispatched: u.dispatched, succeeded, lastUsedAt: u.lastUsedAt };
   }
   return out;
 }
@@ -1997,7 +2085,7 @@ import { createHash as createHash2 } from "crypto";
 import { existsSync as existsSync3 } from "fs";
 import { chmod as chmod2, mkdir as mkdir2, readFile as readFile6, readdir, unlink } from "fs/promises";
 import { homedir as homedir7, hostname, userInfo } from "os";
-import { join as join7, resolve as resolve3 } from "path";
+import { join as join7, resolve as resolve5 } from "path";
 import { request as request5 } from "undici";
 
 // src/catalog.ts
@@ -2099,7 +2187,7 @@ async function resolveCatalogSlug(slug, opts = {}) {
 import { existsSync as existsSync2 } from "fs";
 import { chmod, readFile as readFile5 } from "fs/promises";
 import { homedir as homedir6 } from "os";
-import { join as join6, resolve as resolve2 } from "path";
+import { join as join6, resolve as resolve4 } from "path";
 import { createInterface } from "readline/promises";
 var USAGE = "Usage: yaw-mcp install <claude-code|claude-desktop|cursor|vscode> [--scope user|project|local]\n                       [--token <mcp_pat_\u2026>] [--project-dir <path>] [--os macos|linux|windows]\n                       [--force | --skip] [--dry-run] [--no-yaw-mcp-config]\n       yaw-mcp install --list                       (detect clients; no writes)\n       yaw-mcp install --all  [--token <mcp_pat_\u2026>] (install into every detected client)";
 async function runInstall(opts) {
@@ -2152,7 +2240,7 @@ ${USAGE}`);
     );
     return { written: [], wouldWrite: [], messages, exitCode: 2 };
   }
-  const projectDir = scopeSpec.requiresProjectDir ? resolve2(opts.projectDir ?? process.cwd()) : void 0;
+  const projectDir = scopeSpec.requiresProjectDir ? resolve4(opts.projectDir ?? process.cwd()) : void 0;
   let resolved;
   try {
     resolved = resolveInstallPath({
@@ -2221,7 +2309,7 @@ ${USAGE}`);
     if (opts.force) decision = "overwrite";
     else if (opts.skip) decision = "skip";
     else if (opts.promptAnswer) decision = opts.promptAnswer;
-    else if (opts.io?.isTTY ?? process.stdout.isTTY) {
+    else if (opts.io?.isTTY ?? (Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY))) {
       decision = await promptCollision(resolved.absolute, opts.io);
     } else {
       err(
@@ -2323,38 +2411,38 @@ ${settingsPatch.nextJson}`);
     );
   }
   log2(`
-\u2713 ${target.label} is configured. Restart it to pick up the new MCP server.`);
+Done: ${target.label} is configured. Restart it to pick up the new MCP server.`);
   return { written, wouldWrite: [], messages, exitCode: 0 };
 }
 async function prepareClaudeCodeSettingsPatch(opts) {
-  const path3 = resolveClaudeCodeSettingsPath(opts.scope, {
+  const path5 = resolveClaudeCodeSettingsPath(opts.scope, {
     home: opts.home,
     projectDir: opts.projectDir,
     os: opts.os,
     claudeConfigDir: opts.claudeConfigDir
   });
-  if (!path3) return null;
+  if (!path5) return null;
   let existing = {};
-  if (existsSync2(path3)) {
+  if (existsSync2(path5)) {
     try {
-      const raw = await readFile5(path3, "utf8");
+      const raw = await readFile5(path5, "utf8");
       if (raw.trim().length > 0) {
         const parsed = parseJsonc(raw);
         if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
           existing = parsed;
         } else {
-          return { path: path3, nextJson: "", changed: false };
+          return { path: path5, nextJson: "", changed: false };
         }
       }
     } catch {
-      return { path: path3, nextJson: "", changed: false };
+      return { path: path5, nextJson: "", changed: false };
     }
   }
   const merged = mergePermissionsAllow(existing, [CLAUDE_CODE_ALLOW_PATTERN]);
   const before = JSON.stringify(existing);
   const after = JSON.stringify(merged);
-  if (before === after) return { path: path3, nextJson: "", changed: false };
-  return { path: path3, nextJson: `${JSON.stringify(merged, null, 2)}
+  if (before === after) return { path: path5, nextJson: "", changed: false };
+  return { path: path5, nextJson: `${JSON.stringify(merged, null, 2)}
 `, changed: true };
 }
 var LEGACY_CLAUDE_CODE_ALLOW_PATTERNS = ["mcp__mcp_hosting__*", "mcp__yaw_mcp__*"];
@@ -2373,13 +2461,13 @@ function mergePermissionsAllow(existing, patterns) {
   out.permissions = perms;
   return out;
 }
-async function promptCollision(path3, io) {
+async function promptCollision(path5, io) {
   const stdin = io?.stdin ?? process.stdin;
   const stdout = io?.stdout ?? process.stdout;
   const rl = createInterface({ input: stdin, output: stdout });
   try {
     const answer = (await rl.question(
-      `${path3} already has an "${ENTRY_NAME}" entry.
+      `${path5} already has an "${ENTRY_NAME}" entry.
   [o]verwrite, [s]kip, or [a]bort? (default: skip) `
     )).trim().toLowerCase();
     if (answer.startsWith("o")) return "overwrite";
@@ -2439,13 +2527,13 @@ function removeFromClientConfig(existing, containerPath, entryName) {
   parent[leafKey] = container;
   return out;
 }
-async function composeYawMcpConfig(path3, token5) {
+async function composeYawMcpConfig(path5, token5) {
   let existing = {};
   let backupPath;
-  if (existsSync2(path3)) {
+  if (existsSync2(path5)) {
     let raw = "";
     try {
-      raw = await readFile5(path3, "utf8");
+      raw = await readFile5(path5, "utf8");
     } catch {
       raw = "";
     }
@@ -2454,9 +2542,16 @@ async function composeYawMcpConfig(path3, token5) {
         const parsed = parseJsonc(raw);
         if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
           existing = parsed;
+        } else {
+          const candidate = `${path5}.bak-${Date.now()}`;
+          try {
+            await atomicWriteFile(candidate, raw);
+            backupPath = candidate;
+          } catch {
+          }
         }
       } catch {
-        const candidate = `${path3}.bak-${Date.now()}`;
+        const candidate = `${path5}.bak-${Date.now()}`;
         try {
           await atomicWriteFile(candidate, raw);
           backupPath = candidate;
@@ -2525,7 +2620,7 @@ function parseInstallArgs(argv) {
         break;
       case "-h":
       case "--help":
-        return { ok: false, error: USAGE };
+        return { ok: false, error: USAGE, help: true };
       default:
         if (a.startsWith("--")) return { ok: false, error: `Unknown flag: ${a}
 ${USAGE}` };
@@ -2660,7 +2755,7 @@ async function runInstallAll(opts, log2, err) {
   }
   const totalPlanned = plans.length;
   if (failed === 0) {
-    log2(`\u2713 ${succeeded}/${totalPlanned} clients installed successfully.`);
+    log2(`Done: ${succeeded}/${totalPlanned} clients installed successfully.`);
     return {
       written: aggregateWritten,
       wouldWrite: aggregateWouldWrite,
@@ -2755,7 +2850,7 @@ function parseTryArgs(argv) {
       }
       case "-h":
       case "--help":
-        return { ok: false, error: TRY_USAGE };
+        return { ok: false, error: TRY_USAGE, help: true };
       default:
         if (a.startsWith("--")) return { ok: false, error: `Unknown flag: ${a}
 ${TRY_USAGE}` };
@@ -2776,7 +2871,7 @@ function parseTryCleanupArgs(argv) {
   const positional = [];
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
-    if (a === "-h" || a === "--help") return { ok: false, error: TRY_CLEANUP_USAGE };
+    if (a === "-h" || a === "--help") return { ok: false, error: TRY_CLEANUP_USAGE, help: true };
     if (a === "--base") {
       const v = argv[++i];
       if (!v) return { ok: false, error: "--base requires a URL" };
@@ -2822,10 +2917,10 @@ function computeAnonId() {
   return h.digest("hex").slice(0, 16);
 }
 async function loadOrCreateAnonId(home = homedir7()) {
-  const path3 = anonIdPath(home);
-  if (existsSync3(path3)) {
+  const path5 = anonIdPath(home);
+  if (existsSync3(path5)) {
     try {
-      const raw = (await readFile6(path3, "utf8")).trim();
+      const raw = (await readFile6(path5, "utf8")).trim();
       if (/^[0-9a-f]{16}$/.test(raw)) return raw;
     } catch {
     }
@@ -2833,11 +2928,11 @@ async function loadOrCreateAnonId(home = homedir7()) {
   const id = computeAnonId();
   try {
     await mkdir2(trialsDir(home), { recursive: true });
-    await atomicWriteFile(path3, `${id}
+    await atomicWriteFile(path5, `${id}
 `);
     if (process.platform !== "win32") {
       try {
-        await chmod2(path3, 384);
+        await chmod2(path5, 384);
       } catch {
       }
     }
@@ -2922,7 +3017,7 @@ async function runTry(opts) {
   }
   const clientId = opts.clientId ?? await autoDetectClient({ home, os, cwd, claudeConfigDir });
   const scope = clientId === "vscode" ? "project" : "user";
-  const projectDir = scope === "project" ? resolve3(cwd) : void 0;
+  const projectDir = scope === "project" ? resolve5(cwd) : void 0;
   let resolved;
   try {
     resolved = resolveInstallPath({ clientId, scope, os, home, projectDir, claudeConfigDir });
@@ -2931,7 +3026,7 @@ async function runTry(opts) {
     return { exitCode: 1, written: [] };
   }
   const supplied = { ...env, ...opts.envOverrides ?? {} };
-  const missing = (server.requiredEnvVars ?? []).filter((k) => !supplied[k] || supplied[k] === "");
+  const missing = (server.requiredEnvVars ?? []).filter((k) => (supplied[k] ?? "").trim() === "");
   if (missing.length > 0) {
     printErr(`yaw-mcp try: ${server.name} needs the following env var(s) before it can run:`);
     for (const k of missing) printErr(`  - ${k}`);
@@ -2944,7 +3039,7 @@ async function runTry(opts) {
   }
   const trialEnv = {};
   for (const k of server.requiredEnvVars ?? []) {
-    const v = supplied[k];
+    const v = (supplied[k] ?? "").trim();
     if (v) trialEnv[k] = v;
   }
   for (const [k, v] of Object.entries(opts.envOverrides ?? {})) {
@@ -3065,6 +3160,7 @@ async function runTryCleanup(opts) {
     printErr(`yaw-mcp try-cleanup: marker at ${markerPath} is unreadable (${e.message}).`);
     return { exitCode: 1, written: [] };
   }
+  const written = [];
   if (existsSync3(marker.clientPath)) {
     try {
       const raw = await readFile6(marker.clientPath, "utf8");
@@ -3079,13 +3175,14 @@ async function runTryCleanup(opts) {
           if (stripped !== parsed) {
             await atomicWriteFile(marker.clientPath, `${JSON.stringify(stripped, null, 2)}
 `);
+            written.push(marker.clientPath);
             print(`Removed ${marker.entryName} from ${marker.clientPath}`);
           }
         }
       }
     } catch (e) {
       printErr(
-        `yaw-mcp try-cleanup: warning \u2014 couldn't strip ${marker.entryName} from ${marker.clientPath} (${e.message}).`
+        `yaw-mcp try-cleanup: warning -- couldn't strip ${marker.entryName} from ${marker.clientPath} (${e.message}).`
       );
     }
   }
@@ -3099,7 +3196,7 @@ async function runTryCleanup(opts) {
   const postEvent = opts.postEvent ?? defaultPostEvent;
   postEvent(baseUrl, { slug, action: "cleanup", anonId }).catch(() => void 0);
   print(`Trial for "${slug}" cleaned up.`);
-  return { exitCode: 0, written: [marker.clientPath] };
+  return { exitCode: 0, written };
 }
 function formatTtl(ms) {
   const clamped = Math.max(0, ms);
@@ -3122,12 +3219,12 @@ async function scanTrials(opts = {}) {
   }
   for (const filename of entries) {
     if (!filename.endsWith(".json")) continue;
-    const path3 = join7(dir, filename);
+    const path5 = join7(dir, filename);
     try {
-      const raw = await readFile6(path3, "utf8");
+      const raw = await readFile6(path5, "utf8");
       const parsed = JSON.parse(raw);
       if (!parsed || typeof parsed !== "object" || typeof parsed.slug !== "string" || typeof parsed.expiresAt !== "number" || typeof parsed.clientPath !== "string" || !Array.isArray(parsed.containerPath) || typeof parsed.entryName !== "string") {
-        result.malformed.push(path3);
+        result.malformed.push(path5);
         continue;
       }
       const msUntilExpiry = parsed.expiresAt - now;
@@ -3136,7 +3233,7 @@ async function scanTrials(opts = {}) {
       if (expired) result.expired.push(entry);
       else result.live.push(entry);
     } catch {
-      result.malformed.push(path3);
+      result.malformed.push(path5);
     }
   }
   return result;
@@ -3189,16 +3286,19 @@ var UPGRADE_USAGE = `Usage: yaw-mcp upgrade [--run] [--json]
 
   Show (or execute) the command to upgrade @yawlabs/mcp to the latest version.
 
-  --run     Run the upgrade in place (global and local npm installs).
-            No-op for npx installs \u2014 they always fetch the latest.
+  --run     Run the upgrade in place (global npm, pnpm, bun, and local npm
+            installs). No-op for npx installs -- they always fetch the latest.
   --json    Emit a machine-readable snapshot ({ current, latest, stale,
-            method, command }) instead of prose.`;
+            method, command }) instead of prose.
+            NOTE: --json is a report-only snapshot; it never spawns an upgrade
+            even when combined with --run. Use --run without --json to
+            actually perform the upgrade.`;
 function parseUpgradeArgs(argv) {
   const opts = {};
   for (const a of argv) {
     if (a === "--run") opts.run = true;
     else if (a === "--json") opts.json = true;
-    else if (a === "--help" || a === "-h") return { ok: false, error: UPGRADE_USAGE };
+    else if (a === "--help" || a === "-h") return { ok: false, error: UPGRADE_USAGE, help: true };
     else return { ok: false, error: `yaw-mcp upgrade: unknown argument "${a}"
 
 ${UPGRADE_USAGE}` };
@@ -3227,7 +3327,7 @@ function localInstallRoot(argvPath) {
 }
 async function defaultNpmPrefix() {
   if (process.env.VITEST) return null;
-  return new Promise((resolve5) => {
+  return new Promise((resolve7) => {
     const child = spawn2("npm", ["prefix", "-g"], {
       shell: process.platform === "win32",
       stdio: ["ignore", "pipe", "ignore"]
@@ -3235,18 +3335,18 @@ async function defaultNpmPrefix() {
     let out = "";
     const timer = setTimeout(() => {
       child.kill();
-      resolve5(null);
+      resolve7(null);
     }, 3e3);
     child.stdout?.on("data", (d) => {
       out += String(d);
     });
     child.on("close", (code) => {
       clearTimeout(timer);
-      resolve5(code === 0 && out.trim() ? out.trim() : null);
+      resolve7(code === 0 && out.trim() ? out.trim() : null);
     });
     child.on("error", () => {
       clearTimeout(timer);
-      resolve5(null);
+      resolve7(null);
     });
   });
 }
@@ -3339,10 +3439,10 @@ async function defaultFetchLatest() {
   }
 }
 async function defaultSpawn(cmd, args, cwd) {
-  return new Promise((resolve5) => {
+  return new Promise((resolve7) => {
     const child = spawn2(cmd, args, { stdio: "inherit", shell: process.platform === "win32", cwd });
-    child.on("close", (code) => resolve5(typeof code === "number" ? code : 1));
-    child.on("error", () => resolve5(1));
+    child.on("close", (code) => resolve7(typeof code === "number" ? code : 1));
+    child.on("error", () => resolve7(1));
   });
 }
 async function detectSea() {
@@ -3407,7 +3507,7 @@ async function runUpgrade(opts = {}) {
   print(`Install: ${method}`);
   if (!plan.stale) {
     print("");
-    print("\u2713 You're on the latest version \u2014 nothing to do.");
+    print("OK: You're on the latest version -- nothing to do.");
     return { exitCode: 0, lines };
   }
   print("");
@@ -3440,6 +3540,9 @@ async function runUpgrade(opts = {}) {
       print("Run it yourself (--run can't safely automate this install method):");
     }
     print("");
+    if (installRoot) {
+      print(`in ${installRoot}:`);
+    }
     print(`  ${plan.command}`);
     return { exitCode: 1, lines };
   }
@@ -3460,7 +3563,7 @@ async function runUpgrade(opts = {}) {
   const code = await runner(runSpec.cmd, runSpec.args, runSpec.cwd);
   if (code === 0) {
     print("");
-    print(`\u2713 Upgraded @yawlabs/mcp to ${latest}`);
+    print(`OK: Upgraded @yawlabs/mcp to ${latest}`);
     return { exitCode: 0, lines };
   }
   printErr(`yaw-mcp upgrade: ${runSpec.cmd} exited ${code}. Try running the command yourself:`);
@@ -3469,7 +3572,7 @@ async function runUpgrade(opts = {}) {
   return { exitCode: 3, lines };
 }
 function readCurrentVersion() {
-  return true ? "0.60.6" : "dev";
+  return true ? "0.62.0" : "dev";
 }
 
 // src/usage-hints.ts
@@ -3497,7 +3600,7 @@ function buildCoUsageMap(packs) {
 function formatUsageHint(usage, coUsedWith) {
   const parts = [];
   if (usage && usage.succeeded >= MIN_SUCCESS_TO_SHOW) {
-    parts.push(`used ${usage.succeeded}x`);
+    parts.push(`used ${Math.round(usage.succeeded)}x`);
   }
   if (coUsedWith.length > 0) {
     const shown = coUsedWith.slice(0, MAX_PEERS);
@@ -3531,7 +3634,11 @@ function selectFlakyNamespaces(entries, limit) {
 }
 
 // src/doctor-cmd.ts
-var VERSION = true ? "0.60.6" : "dev";
+var VERSION = true ? "0.62.0" : "dev";
+function isPersistenceDisabled(env) {
+  const raw = env.YAW_MCP_DISABLE_PERSISTENCE;
+  return raw !== void 0 && raw !== "" && (raw === "1" || raw.toLowerCase() === "true");
+}
 async function runDoctor(opts = {}) {
   if (opts.json) return runDoctorJson(opts);
   const lines = [];
@@ -3568,8 +3675,16 @@ async function runDoctor(opts = {}) {
   print(`  source: ${config.apiBaseSource}`);
   print("");
   renderEnvSection({ env, print });
-  await renderStateSection({ home, env, print });
-  await renderReliabilitySection({ home, env, print });
+  const persistenceDisabled = isPersistenceDisabled(env);
+  const stateFilePath = join8(userConfigDir(home), STATE_FILENAME);
+  const persistedState = persistenceDisabled ? null : await loadState(stateFilePath);
+  await renderStateSection({
+    filePath: stateFilePath,
+    disabled: persistenceDisabled,
+    persisted: persistedState,
+    print
+  });
+  renderReliabilitySection({ disabled: persistenceDisabled, persisted: persistedState, print });
   await renderTrialsSection({ home, env, print, postEvent: opts.postTryEvent, now: opts.now });
   renderBackgroundPostersSection({ print });
   const claudeConfigDir = env.CLAUDE_CONFIG_DIR && env.CLAUDE_CONFIG_DIR.length > 0 ? env.CLAUDE_CONFIG_DIR : void 0;
@@ -3599,29 +3714,31 @@ async function runDoctor(opts = {}) {
     }
     print("");
   }
-  const skipCheck = opts.skipRegistryCheck === true || Boolean(process.env.VITEST);
+  const skipCheck = (opts.skipRegistryCheck === true || Boolean(process.env.VITEST)) && !opts.registryFetch;
   const latest = skipCheck ? null : await fetchLatestVersion(opts.registryFetch);
-  const staleHint = latest && VERSION !== "dev" && compareSemver(VERSION, latest) < 0 ? latest : null;
+  const effectiveVersion = opts.currentVersion ?? VERSION;
+  const staleHint = latest && effectiveVersion !== "dev" && compareSemver(effectiveVersion, latest) < 0 ? latest : null;
   if (staleHint) {
-    const method = await detectSea() ? "binary" : await refineInstallMethod(detectInstallMethod(process.argv[1]), process.argv[1]);
+    const effectiveArgvPath = opts.argvPath ?? process.argv[1];
+    const method = await detectSea() ? "binary" : await refineInstallMethod(detectInstallMethod(effectiveArgvPath), effectiveArgvPath);
     print("UPGRADE AVAILABLE");
     if (method === "bundled-app") {
-      print(`  Running ${VERSION}; npm latest is ${staleHint}. This copy ships inside`);
+      print(`  Running ${effectiveVersion}; npm latest is ${staleHint}. This copy ships inside`);
       print("  Yaw Terminal and updates with the app \u2014 update Yaw Terminal to get it.");
     } else if (method === "npx") {
-      print(`  Running ${VERSION}; npm latest is ${staleHint}. npx fetches the latest`);
+      print(`  Running ${effectiveVersion}; npm latest is ${staleHint}. npx fetches the latest`);
       print("  on each spawn \u2014 restart your MCP client to pick it up.");
     } else if (method === "binary") {
-      print(`  Running ${VERSION}; npm latest is ${staleHint}. This is a standalone`);
+      print(`  Running ${effectiveVersion}; npm latest is ${staleHint}. This is a standalone`);
       print("  binary \u2014 download the latest build and replace the executable:");
       print(`    ${BINARY_DOWNLOAD_URL}`);
     } else if (method === "global-npm" || method === "pnpm-global" || method === "bun-global" || method === "local-node-modules") {
-      print(`  Running ${VERSION}; npm latest is ${staleHint}. To upgrade in place:`);
+      print(`  Running ${effectiveVersion}; npm latest is ${staleHint}. To upgrade in place:`);
       print("");
       print("    yaw-mcp upgrade --run");
     } else {
-      const plan = buildUpgradePlan({ current: VERSION, latest: staleHint, method });
-      print(`  Running ${VERSION}; npm latest is ${staleHint}. To upgrade:`);
+      const plan = buildUpgradePlan({ current: effectiveVersion, latest: staleHint, method });
+      print(`  Running ${effectiveVersion}; npm latest is ${staleHint}. To upgrade:`);
       print("");
       print(`    ${plan.command ?? "npm install -g @yawlabs/mcp@latest"}`);
     }
@@ -3668,24 +3785,21 @@ async function runDoctorJson(opts) {
     const raw = env[name];
     envOverrides[name] = raw === void 0 || raw === "" ? null : raw;
   }
-  const persistRaw = env.YAW_MCP_DISABLE_PERSISTENCE;
-  const persistDisabled = persistRaw !== void 0 && persistRaw !== "" && (persistRaw === "1" || persistRaw.toLowerCase() === "true");
-  const state = persistDisabled ? { disabled: true, path: null, savedAt: null, learningEntries: null, packHistoryEntries: null } : await (async () => {
-    const filePath = join8(userConfigDir(home), STATE_FILENAME);
-    const persisted = await loadState(filePath);
+  const persistDisabled = isPersistenceDisabled(env);
+  const stateFilePath = join8(userConfigDir(home), STATE_FILENAME);
+  const persisted = persistDisabled ? null : await loadState(stateFilePath);
+  const state = persistDisabled || !persisted ? { disabled: true, path: null, savedAt: null, learningEntries: null, packHistoryEntries: null } : (() => {
     const fresh = persisted.savedAt === 0;
     return {
       disabled: false,
-      path: filePath,
+      path: stateFilePath,
       savedAt: fresh ? null : new Date(persisted.savedAt).toISOString(),
       learningEntries: fresh ? 0 : Object.keys(persisted.learning).length,
       packHistoryEntries: fresh ? 0 : persisted.packHistory.length
     };
   })();
   const reliability = [];
-  if (!persistDisabled) {
-    const filePath = join8(userConfigDir(home), STATE_FILENAME);
-    const persisted = await loadState(filePath);
+  if (!persistDisabled && persisted) {
     if (persisted.savedAt !== 0) {
       const entries = Object.entries(persisted.learning).map(([namespace, usage]) => ({ namespace, usage }));
       for (const { namespace, usage } of selectFlakyNamespaces(entries, 5)) {
@@ -3700,9 +3814,10 @@ async function runDoctorJson(opts) {
     }
   }
   const shellShadows = scanShellHistoryForShadows({ home, env });
-  const skipCheck = opts.skipRegistryCheck === true || Boolean(process.env.VITEST);
+  const skipCheck = (opts.skipRegistryCheck === true || Boolean(process.env.VITEST)) && !opts.registryFetch;
   const latest = skipCheck ? null : await fetchLatestVersion(opts.registryFetch);
-  const stale = latest !== null && VERSION !== "dev" && compareSemver(VERSION, latest) < 0;
+  const effectiveVersion = opts.currentVersion ?? VERSION;
+  const stale = latest !== null && effectiveVersion !== "dev" && compareSemver(effectiveVersion, latest) < 0;
   let exitCode = 0;
   let summary;
   if (config.token === null) {
@@ -3731,7 +3846,7 @@ async function runDoctorJson(opts) {
     reliability,
     clients,
     shellShadows,
-    upgrade: { current: VERSION, latest, stale },
+    upgrade: { current: effectiveVersion, latest, stale },
     diagnosis: { exitCode, summary }
   };
   const blob = JSON.stringify(snapshotJson, null, 2);
@@ -3760,16 +3875,13 @@ function renderEnvSection(opts) {
   print("");
 }
 async function renderStateSection(opts) {
-  const { home, env, print } = opts;
-  const raw = env.YAW_MCP_DISABLE_PERSISTENCE;
-  const disabled = raw !== void 0 && raw !== "" && (raw === "1" || raw.toLowerCase() === "true");
+  const { filePath, disabled, persisted, print } = opts;
   print("STATE");
   if (disabled) {
     print("  status: disabled via YAW_MCP_DISABLE_PERSISTENCE");
     print("");
     return;
   }
-  const filePath = join8(userConfigDir(home), STATE_FILENAME);
   print(`  path:   ${filePath}`);
   const peek = await peekStateFile(filePath);
   if (peek.kind === "malformed") {
@@ -3790,8 +3902,7 @@ async function renderStateSection(opts) {
     print("");
     return;
   }
-  const persisted = await loadState(filePath);
-  if (persisted.savedAt === 0) {
+  if (!persisted || persisted.savedAt === 0) {
     print("  (no persisted state yet \u2014 will be created on the first tool call)");
   } else {
     print(`  last saved:           ${formatRelativeAge(Date.now() - persisted.savedAt)} ago`);
@@ -3823,13 +3934,9 @@ async function peekStateFile(filePath) {
   }
   return { kind: "ok" };
 }
-async function renderReliabilitySection(opts) {
-  const { home, env, print } = opts;
-  const raw = env.YAW_MCP_DISABLE_PERSISTENCE;
-  const disabled = raw !== void 0 && raw !== "" && (raw === "1" || raw.toLowerCase() === "true");
-  if (disabled) return;
-  const filePath = join8(userConfigDir(home), STATE_FILENAME);
-  const persisted = await loadState(filePath);
+function renderReliabilitySection(opts) {
+  const { disabled, persisted, print } = opts;
+  if (disabled || !persisted) return;
   if (persisted.savedAt === 0) return;
   const entries = Object.entries(persisted.learning).map(([namespace, usage]) => ({ namespace, usage }));
   const flaky = selectFlakyNamespaces(entries, 5);
@@ -3855,8 +3962,8 @@ async function renderTrialsSection(opts) {
   for (const { marker, msUntilExpiry } of scan.live) {
     print(`  ${marker.slug} -> ${marker.clientName} (${marker.clientPath}) \u2014 expires in ${formatTtl(msUntilExpiry)}`);
   }
-  for (const path3 of scan.malformed) {
-    print(`  ! malformed marker at ${path3} (delete by hand)`);
+  for (const path5 of scan.malformed) {
+    print(`  ! malformed marker at ${path5} (delete by hand)`);
   }
   print("");
 }
@@ -3975,9 +4082,9 @@ function probeClients(opts) {
   }
   return out;
 }
-function walkContainer(root, path3) {
+function walkContainer(root, path5) {
   let cur = root;
-  for (const key of path3) {
+  for (const key of path5) {
     if (typeof cur !== "object" || cur === null || Array.isArray(cur)) return null;
     cur = cur[key];
   }
@@ -4018,6 +4125,7 @@ async function probeClientsAsync(opts) {
       let malformed = false;
       if (exists3) {
         try {
+          await stat3(resolved.absolute);
           const raw = await readFile7(resolved.absolute, "utf8");
           if (raw.trim().length > 0) {
             const parsed = parseJsonc(raw);
@@ -4124,9 +4232,9 @@ function shellHistorySources(opts) {
   }
   return sources;
 }
-function readTailLines(path3, n) {
+function readTailLines(path5, n) {
   try {
-    const raw = readFileSync(path3, "utf8");
+    const raw = readFileSync(path5, "utf8");
     const all = raw.split(/\r?\n/);
     return all.length <= n ? all : all.slice(all.length - n);
   } catch {
@@ -4171,97 +4279,494 @@ function compareSemver(a, b) {
   return 0;
 }
 
-// src/fuzzy.ts
-function levenshtein(a, b) {
-  if (a === b) return 0;
-  const aLen = a.length;
-  const bLen = b.length;
-  if (aLen === 0) return bLen;
-  if (bLen === 0) return aLen;
-  let prev = new Array(bLen + 1);
-  let curr = new Array(bLen + 1);
-  for (let j = 0; j <= bLen; j++) prev[j] = j;
-  for (let i = 1; i <= aLen; i++) {
-    curr[0] = i;
-    for (let j = 1; j <= bLen; j++) {
-      const cost = a.charCodeAt(i - 1) === b.charCodeAt(j - 1) ? 0 : 1;
-      curr[j] = Math.min(
-        curr[j - 1] + 1,
-        // insertion
-        prev[j] + 1,
-        // deletion
-        prev[j - 1] + cost
-        // substitution
-      );
+// src/foundry-cmd.ts
+import { mkdirSync, readFileSync as readFileSync3, writeFileSync } from "fs";
+import { homedir as homedir10 } from "os";
+import path3 from "path";
+
+// src/foundry-corpus.ts
+import { readFileSync as readFileSync2 } from "fs";
+
+// src/relevance.ts
+var K1 = 1.2;
+var B = 0.75;
+var FIELD_WEIGHTS = {
+  name: 3,
+  namespace: 2,
+  description: 1.5,
+  toolName: 2,
+  toolDescription: 1
+};
+var MIN_TOKEN_LEN = 3;
+function tokenize(text) {
+  if (!text) return [];
+  return text.toLowerCase().split(/[^a-z0-9]+/).filter((w) => w.length >= MIN_TOKEN_LEN);
+}
+function buildDocFields(server) {
+  const toolNameTokens = [];
+  const toolDescriptionTokens = [];
+  for (const tool of server.tools) {
+    toolNameTokens.push(...tokenize(tool.name));
+    toolDescriptionTokens.push(...tokenize(tool.description));
+  }
+  return {
+    namespace: tokenize(server.namespace),
+    name: tokenize(server.name),
+    description: tokenize(server.description),
+    toolName: toolNameTokens,
+    toolDescription: toolDescriptionTokens
+  };
+}
+function termFreq(tokens, term) {
+  let count = 0;
+  for (const t of tokens) {
+    if (t === term) count++;
+  }
+  return count;
+}
+function bm25Score(queryTerms, fields, avgFieldLen, idfValues) {
+  let score = 0;
+  const seen = /* @__PURE__ */ new Set();
+  for (const term of queryTerms) {
+    if (seen.has(term)) continue;
+    seen.add(term);
+    const termIdf = idfValues.get(term);
+    if (termIdf === void 0 || termIdf <= 0) continue;
+    for (const [fieldName, weight] of Object.entries(FIELD_WEIGHTS)) {
+      const fieldTokens = fields[fieldName];
+      if (fieldTokens.length === 0) continue;
+      const tf = termFreq(fieldTokens, term);
+      if (tf === 0) continue;
+      const avg = avgFieldLen[fieldName] || 1;
+      const normLen = 1 - B + B * (fieldTokens.length / avg);
+      const numerator = tf * (K1 + 1);
+      const denominator = tf + K1 * normLen;
+      score += weight * termIdf * (numerator / denominator);
     }
-    [prev, curr] = [curr, prev];
   }
-  return prev[bLen];
+  return score;
 }
-function closestNames(query, candidates, limit) {
-  if (limit <= 0) return [];
-  const q = query.toLowerCase();
-  const scored = [];
-  for (const c of candidates) {
-    if (c === query) continue;
-    const lc = c.toLowerCase();
-    let score = null;
-    if (lc === q) {
-      score = 0;
-    } else if (lc.startsWith(q) || q.startsWith(lc)) {
-      score = 1;
-    } else if (lc.includes(q) || q.includes(lc)) {
-      score = 2;
-    } else {
-      const d = levenshtein(q, lc);
-      if (d <= 2) score = 2 + d;
+function rankServers(context, servers) {
+  const queryTerms = tokenize(context);
+  if (queryTerms.length === 0 || servers.length === 0) return [];
+  const docsWithFields = servers.map((s) => ({ server: s, fields: buildDocFields(s) }));
+  const N = docsWithFields.length;
+  const df = /* @__PURE__ */ new Map();
+  for (const { fields } of docsWithFields) {
+    const bag = /* @__PURE__ */ new Set([
+      ...fields.namespace,
+      ...fields.name,
+      ...fields.description,
+      ...fields.toolName,
+      ...fields.toolDescription
+    ]);
+    for (const term of bag) {
+      df.set(term, (df.get(term) ?? 0) + 1);
     }
-    if (score !== null) scored.push({ name: c, score });
   }
-  scored.sort((a, b) => {
-    if (a.score !== b.score) return a.score - b.score;
-    return a.name.localeCompare(b.name);
+  const idfValues = /* @__PURE__ */ new Map();
+  for (const [term, d] of df) {
+    idfValues.set(term, Math.log((N - d + 0.5) / (d + 0.5) + 1));
+  }
+  const totalLen = {
+    namespace: 0,
+    name: 0,
+    description: 0,
+    toolName: 0,
+    toolDescription: 0
+  };
+  for (const { fields } of docsWithFields) {
+    totalLen.namespace += fields.namespace.length;
+    totalLen.name += fields.name.length;
+    totalLen.description += fields.description.length;
+    totalLen.toolName += fields.toolName.length;
+    totalLen.toolDescription += fields.toolDescription.length;
+  }
+  const denom = Math.max(N, 1);
+  const avgFieldLen = {
+    namespace: totalLen.namespace / denom,
+    name: totalLen.name / denom,
+    description: totalLen.description / denom,
+    toolName: totalLen.toolName / denom,
+    toolDescription: totalLen.toolDescription / denom
+  };
+  const results = [];
+  for (const { server, fields } of docsWithFields) {
+    const score = bm25Score(queryTerms, fields, avgFieldLen, idfValues);
+    if (score > 0) {
+      results.push({ namespace: server.namespace, score });
+    }
+  }
+  results.sort((a, b) => {
+    if (b.score !== a.score) return b.score - a.score;
+    return a.namespace < b.namespace ? -1 : 1;
   });
-  return scored.slice(0, limit).map((s) => s.name);
+  return results;
 }
 
-// src/local-add-cmd.ts
-import { homedir as homedir9 } from "os";
-var SLUG_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
-var ADD_USAGE = `Usage: yaw-mcp add <slug> [flags]
-
-  Resolve <slug> from the yaw.sh/mcp catalog and add it to your local
-  ~/.yaw-mcp/bundles.json so yaw-mcp loads it (no account needed).
-
-  This is NOT the same as \`yaw-mcp install\` -- install wires the yaw-mcp
-  aggregator into an AI client; add adds an MCP server to yaw-mcp itself.
-
-  --env KEY=value   Provide a required env var's value. Repeatable. Required
-                    vars not given here AND not in your shell block the add.
-  --dry-run         Print what would be written without writing.
-  --json            Emit the written entry as JSON (implies success on stdout).
-  --catalog <url>   Override the catalog URL (default the public catalog).`;
-function parseEnvFlag(v, bag) {
-  if (!v || !v.includes("=")) return "--env requires KEY=value";
-  const eq = v.indexOf("=");
-  const key = v.slice(0, eq);
-  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) return `--env: invalid KEY "${key}"`;
-  bag[key] = v.slice(eq + 1);
-  return null;
-}
-function parseAddArgs(argv) {
-  if (argv.length === 0) return { ok: false, error: ADD_USAGE };
-  const positional = [];
-  const opts = {};
-  const env = {};
-  for (let i = 0; i < argv.length; i++) {
-    const a = argv[i];
-    const next = () => argv[++i];
-    switch (a) {
-      case "--env": {
-        const e = parseEnvFlag(next(), env);
-        if (e) return { ok: false, error: e };
-        break;
+// src/foundry-corpus.ts
+var FOUNDRY_CORPUS_VERSION = 1;
+var DEFAULT_CORPUS_CAP = 500;
+function parseTraceLines(text) {
+  const out = [];
+  for (const line of text.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      const obj = JSON.parse(trimmed);
+      if (obj && Array.isArray(obj.tokens) && typeof obj.chosen === "string") {
+        out.push(obj);
+      }
+    } catch {
+    }
+  }
+  return out;
+}
+function entryKey(tokens, chosen) {
+  return `${tokens.join(" ")}::${chosen}`;
+}
+function capStratified(entries, cap) {
+  if (entries.length <= cap) return entries;
+  const byChosen = /* @__PURE__ */ new Map();
+  for (const e of entries) {
+    const g = byChosen.get(e.chosen);
+    if (g) g.push(e);
+    else byChosen.set(e.chosen, [e]);
+  }
+  const groups = [...byChosen.entries()].sort((a, b) => a[0] < b[0] ? -1 : 1).map(([, g]) => g.sort((x, y) => y.weight - x.weight));
+  const out = [];
+  let i = 0;
+  while (out.length < cap) {
+    let took = false;
+    for (const g of groups) {
+      if (i < g.length) {
+        out.push(g[i]);
+        took = true;
+        if (out.length >= cap) break;
+      }
+    }
+    if (!took) break;
+    i++;
+  }
+  return out;
+}
+function buildCorpusFromTraces(traces, servers, opts = {}) {
+  const known = new Set(servers.map((s) => s.namespace));
+  const byKey = /* @__PURE__ */ new Map();
+  for (const t of traces) {
+    if (!t || typeof t.chosen !== "string" || !known.has(t.chosen)) continue;
+    if (!Array.isArray(t.tokens) || t.tokens.length === 0) continue;
+    const tokens = [...t.tokens].filter((x) => typeof x === "string").sort();
+    if (tokens.length === 0) continue;
+    const key = entryKey(tokens, t.chosen);
+    const prev = byKey.get(key);
+    if (prev) prev.weight += 1;
+    else byKey.set(key, { tokens, chosen: t.chosen, weight: 1 });
+  }
+  const entries = capStratified([...byKey.values()], opts.cap ?? DEFAULT_CORPUS_CAP);
+  return { version: FOUNDRY_CORPUS_VERSION, servers, entries };
+}
+function scoreCorpus(corpus) {
+  let totalWeight = 0;
+  let top1Weight = 0;
+  let top3Weight = 0;
+  for (const e of corpus.entries) {
+    totalWeight += e.weight;
+    const top3 = rankServers(e.tokens.join(" "), corpus.servers).slice(0, 3).map((r) => r.namespace);
+    if (top3[0] === e.chosen) top1Weight += e.weight;
+    if (top3.includes(e.chosen)) top3Weight += e.weight;
+  }
+  return {
+    totalWeight,
+    top1Weight,
+    top3Weight,
+    top1: totalWeight > 0 ? top1Weight / totalWeight : 0,
+    top3: totalWeight > 0 ? top3Weight / totalWeight : 0
+  };
+}
+
+// src/foundry.ts
+import { appendFile, mkdir as mkdir3, stat as stat4 } from "fs/promises";
+import { homedir as homedir9 } from "os";
+import path2 from "path";
+var SECRET_PREFIXES = ["sk_", "sk-", "tok_", "ghp_", "gho_", "xox", "pk_", "akia"];
+function looksSensitive(token5) {
+  for (const prefix of SECRET_PREFIXES) {
+    if (token5.startsWith(prefix)) return true;
+  }
+  if (token5.length >= 16 && /^[0-9a-f]+$/.test(token5)) return true;
+  if (token5.length >= 12 && /[a-z]/.test(token5) && /[0-9]/.test(token5)) return true;
+  if (token5.length >= 16 && /^[a-z]+$/.test(token5)) return true;
+  return false;
+}
+function redactIntent(intent) {
+  const all = tokenize(intent);
+  const tokens = [];
+  let redactedCount = 0;
+  for (const token5 of all) {
+    if (looksSensitive(token5)) {
+      redactedCount++;
+    } else {
+      tokens.push(token5);
+    }
+  }
+  tokens.sort();
+  return { tokens, redactedCount };
+}
+function isFoundryEnabled() {
+  const raw = process.env.YAW_MCP_FOUNDRY;
+  if (!raw) return false;
+  const v = raw.trim().toLowerCase();
+  return v === "1" || v === "true";
+}
+var MAX_FOUNDRY_BYTES = 5 * 1024 * 1024;
+var FOUNDRY_FILENAME = "foundry.jsonl";
+async function appendFoundryTrace(trace, home = homedir9()) {
+  try {
+    if (!isFoundryEnabled()) return;
+    const dir = userConfigDir(home);
+    const file = path2.join(dir, FOUNDRY_FILENAME);
+    try {
+      const info = await stat4(file);
+      if (info.size >= MAX_FOUNDRY_BYTES) return;
+    } catch {
+    }
+    const line = `${JSON.stringify({
+      tokens: trace.tokens,
+      candidates: trace.candidates,
+      chosen: trace.chosen,
+      redactedCount: trace.redactedCount
+    })}
+`;
+    await mkdir3(dir, { recursive: true });
+    await appendFile(file, line, "utf8");
+  } catch {
+  }
+}
+
+// src/foundry-cmd.ts
+var DEFAULT_OUT = path3.join("src", "tests", "fixtures", "foundry-corpus.json");
+var FOUNDRY_USAGE = `Usage: yaw-mcp foundry export [--out <path>] [--cap <n>] [--json]
+
+  Fold the opt-in dispatch harvest (~/.yaw-mcp/foundry.jsonl) into a routing
+  regression corpus consumed by the foundry-routing test gate. Maintainer
+  command: requires a local bundles.json for the server-catalog snapshot.
+
+  --out <path>   Where to write the corpus (default: ${DEFAULT_OUT}).
+  --cap <n>      Max entries, stratified by chosen server (default: ${DEFAULT_CORPUS_CAP}).
+  --json         Emit a machine-readable summary instead of text.`;
+function parseFoundryArgs(argv) {
+  let action;
+  let out = DEFAULT_OUT;
+  let cap = DEFAULT_CORPUS_CAP;
+  let json = false;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--help" || a === "-h") return { ok: false, error: FOUNDRY_USAGE };
+    if (a === "--json") {
+      json = true;
+    } else if (a === "--out") {
+      const v = argv[++i];
+      if (!v) return { ok: false, error: `yaw-mcp foundry: --out needs a path
+
+${FOUNDRY_USAGE}` };
+      out = v;
+    } else if (a === "--cap") {
+      const v = Number(argv[++i]);
+      if (!Number.isFinite(v) || v <= 0)
+        return { ok: false, error: `yaw-mcp foundry: --cap needs a positive number
+
+${FOUNDRY_USAGE}` };
+      cap = Math.floor(v);
+    } else if (a.startsWith("-")) {
+      return { ok: false, error: `yaw-mcp foundry: unknown argument "${a}"
+
+${FOUNDRY_USAGE}` };
+    } else if (action === void 0) {
+      if (a !== "export")
+        return { ok: false, error: `yaw-mcp foundry: unknown action "${a}" (only "export")
+
+${FOUNDRY_USAGE}` };
+      action = a;
+    } else {
+      return { ok: false, error: `yaw-mcp foundry: unexpected extra argument "${a}"
+
+${FOUNDRY_USAGE}` };
+    }
+  }
+  if (action === void 0) return { ok: false, error: `yaw-mcp foundry: missing action.
+
+${FOUNDRY_USAGE}` };
+  return { ok: true, options: { action, out, cap, json } };
+}
+async function defaultLoadServers(cwd, home) {
+  const { config } = await loadLocalBundles({ cwd, home });
+  return (config?.servers ?? []).map((s) => ({
+    namespace: s.namespace,
+    name: s.name,
+    description: s.description,
+    tools: s.toolCache ?? []
+  }));
+}
+async function runFoundryExport(opts) {
+  const write = opts.write ?? ((s) => process.stdout.write(s));
+  const writeErr = opts.writeErr ?? ((s) => process.stderr.write(s));
+  const lines = [];
+  const print = (s = "") => {
+    lines.push(s);
+    write(`${s}
+`);
+  };
+  const printErr = (s) => {
+    lines.push(s);
+    writeErr(`${s}
+`);
+  };
+  const home = opts.home ?? homedir10();
+  const harvestPath = path3.join(userConfigDir(home), FOUNDRY_FILENAME);
+  const blob = opts.readTraces ? opts.readTraces() : (() => {
+    try {
+      return readFileSync3(harvestPath, "utf8");
+    } catch {
+      return null;
+    }
+  })();
+  if (blob === null) {
+    printErr(`yaw-mcp foundry: no harvest at ${harvestPath}. Set YAW_MCP_FOUNDRY=1 and dispatch first.`);
+    return { exitCode: 1, lines };
+  }
+  const traces = parseTraceLines(blob);
+  if (traces.length === 0) {
+    printErr(`yaw-mcp foundry: ${harvestPath} has no parseable traces.`);
+    return { exitCode: 1, lines };
+  }
+  const servers = opts.loadServers ? await opts.loadServers() : await defaultLoadServers(opts.cwd, home);
+  const corpus = buildCorpusFromTraces(traces, servers, { cap: opts.cap });
+  if (corpus.entries.length === 0) {
+    printErr(
+      `yaw-mcp foundry: ${traces.length} traces but 0 usable entries -- none of the chosen servers are in the local catalog (${servers.length} servers).`
+    );
+    return { exitCode: 2, lines };
+  }
+  mkdirSync(path3.dirname(path3.resolve(opts.out)), { recursive: true });
+  writeFileSync(opts.out, `${JSON.stringify(corpus, null, 2)}
+`, "utf8");
+  const score = scoreCorpus(corpus);
+  if (opts.json) {
+    print(
+      JSON.stringify(
+        {
+          out: opts.out,
+          entries: corpus.entries.length,
+          servers: corpus.servers.length,
+          fromTraces: traces.length,
+          top1: score.top1,
+          top3: score.top3
+        },
+        null,
+        2
+      )
+    );
+    return { exitCode: 0, lines };
+  }
+  print(`Wrote ${corpus.entries.length} entries (from ${traces.length} traces) to ${opts.out}`);
+  print(
+    `BM25-floor accuracy on this corpus: top-1 ${(score.top1 * 100).toFixed(1)}%, top-3 ${(score.top3 * 100).toFixed(1)}%`
+  );
+  return { exitCode: 0, lines };
+}
+
+// src/fuzzy.ts
+function levenshtein(a, b) {
+  if (a === b) return 0;
+  const aLen = a.length;
+  const bLen = b.length;
+  if (aLen === 0) return bLen;
+  if (bLen === 0) return aLen;
+  let prev = new Array(bLen + 1);
+  let curr = new Array(bLen + 1);
+  for (let j = 0; j <= bLen; j++) prev[j] = j;
+  for (let i = 1; i <= aLen; i++) {
+    curr[0] = i;
+    for (let j = 1; j <= bLen; j++) {
+      const cost = a.charCodeAt(i - 1) === b.charCodeAt(j - 1) ? 0 : 1;
+      curr[j] = Math.min(
+        curr[j - 1] + 1,
+        // insertion
+        prev[j] + 1,
+        // deletion
+        prev[j - 1] + cost
+        // substitution
+      );
+    }
+    [prev, curr] = [curr, prev];
+  }
+  return prev[bLen];
+}
+function closestNames(query, candidates, limit) {
+  if (limit <= 0) return [];
+  const q = query.toLowerCase();
+  const scored = [];
+  for (const c of candidates) {
+    if (c === query) continue;
+    const lc = c.toLowerCase();
+    let score = null;
+    if (lc === q) {
+      score = 0;
+    } else if (lc.startsWith(q) || q.startsWith(lc)) {
+      score = 1;
+    } else if (lc.includes(q) || q.includes(lc)) {
+      score = 2;
+    } else {
+      const d = levenshtein(q, lc);
+      if (d <= 2) score = 2 + d;
+    }
+    if (score !== null) scored.push({ name: c, score });
+  }
+  scored.sort((a, b) => {
+    if (a.score !== b.score) return a.score - b.score;
+    return a.name.localeCompare(b.name);
+  });
+  return scored.slice(0, limit).map((s) => s.name);
+}
+
+// src/local-add-cmd.ts
+import { homedir as homedir11 } from "os";
+var SLUG_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
+var ADD_USAGE = `Usage: yaw-mcp add <slug> [flags]
+
+  Resolve <slug> from the yaw.sh/mcp catalog and add it to your local
+  ~/.yaw-mcp/bundles.json so yaw-mcp loads it (no account needed).
+
+  This is NOT the same as \`yaw-mcp install\` -- install wires the yaw-mcp
+  aggregator into an AI client; add adds an MCP server to yaw-mcp itself.
+
+  --env KEY=value   Provide a required env var's value. Repeatable. Required
+                    vars not given here AND not in your shell block the add.
+  --dry-run         Print what would be written without writing.
+  --json            Emit the written entry as JSON (implies success on stdout).
+  --catalog <url>   Override the catalog URL (default the public catalog).`;
+function parseEnvFlag(v, bag) {
+  if (!v || !v.includes("=")) return "--env requires KEY=value";
+  const eq = v.indexOf("=");
+  const key = v.slice(0, eq);
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) return `--env: invalid KEY "${key}"`;
+  bag[key] = v.slice(eq + 1);
+  return null;
+}
+function parseAddArgs(argv) {
+  if (argv.length === 0) return { ok: false, error: ADD_USAGE };
+  const positional = [];
+  const opts = {};
+  const env = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const next = () => argv[++i];
+    switch (a) {
+      case "--env": {
+        const e = parseEnvFlag(next(), env);
+        if (e) return { ok: false, error: e };
+        break;
       }
       case "--dry-run":
         opts.dryRun = true;
@@ -4277,7 +4782,7 @@ function parseAddArgs(argv) {
       }
       case "-h":
       case "--help":
-        return { ok: false, error: ADD_USAGE };
+        return { ok: false, error: ADD_USAGE, help: true };
       default:
         if (a.startsWith("--")) return { ok: false, error: `Unknown flag: ${a}
 ${ADD_USAGE}` };
@@ -4309,7 +4814,7 @@ async function runAdd(opts) {
     return { exitCode: 2, written: [] };
   }
   const env = opts.env ?? process.env;
-  const home = opts.home ?? homedir9();
+  const home = opts.home ?? homedir11();
   const cwd = opts.cwd ?? process.cwd();
   let server;
   try {
@@ -4336,6 +4841,10 @@ async function runAdd(opts) {
   const entryEnv = {};
   for (const k of server.requiredEnvKeys) entryEnv[k] = "";
   for (const [k, v] of Object.entries(opts.envOverrides ?? {})) entryEnv[k] = v;
+  const overrides = opts.envOverrides ?? {};
+  const ambientOnlyRequired = server.requiredEnvKeys.filter(
+    (k) => (!overrides[k] || overrides[k] === "") && env[k] != null && env[k] !== ""
+  );
   const entry = {
     id: `local-${namespace}`,
     name: server.name,
@@ -4371,6 +4880,11 @@ async function runAdd(opts) {
     print(`${res.replaced ? "Updated" : "Added"} ${server.name} (namespace "${namespace}") in ${res.path}`);
     print("Restart your MCP client (or yaw-mcp) to pick it up.");
   }
+  if (ambientOnlyRequired.length > 0) {
+    printErr(
+      `Note: ${ambientOnlyRequired.join(", ")} ${ambientOnlyRequired.length === 1 ? "was" : "were"} read from your shell env and NOT persisted; the server depends on ${ambientOnlyRequired.length === 1 ? "that var" : "those vars"} being present wherever yaw-mcp launches. Pass --env ${ambientOnlyRequired[0]}=... to persist a value.`
+    );
+  }
   const shadow = await findShadowingProjectBundles(cwd, home).catch(() => null);
   if (shadow) {
     printErr(
@@ -4389,7 +4903,7 @@ function parseRemoveArgs(argv) {
   if (argv.length === 0) return { ok: false, error: REMOVE_USAGE };
   const positional = [];
   for (const a of argv) {
-    if (a === "-h" || a === "--help") return { ok: false, error: REMOVE_USAGE };
+    if (a === "-h" || a === "--help") return { ok: false, error: REMOVE_USAGE, help: true };
     if (a.startsWith("--")) return { ok: false, error: `Unknown flag: ${a}
 ${REMOVE_USAGE}` };
     positional.push(a);
@@ -4415,7 +4929,7 @@ async function runRemove(opts) {
     printErr(`yaw-mcp remove: "${opts.target}" isn't a valid slug or namespace.`);
     return { exitCode: 2, written: [] };
   }
-  const home = opts.home ?? homedir9();
+  const home = opts.home ?? homedir11();
   const cwd = opts.cwd ?? process.cwd();
   const derived = deriveNamespace(opts.target);
   const candidates = derived === opts.target ? [opts.target] : [opts.target, derived];
@@ -4459,7 +4973,7 @@ var LIST_USAGE = `Usage: yaw-mcp list [--json]
 function parseListArgs(argv) {
   const opts = {};
   for (const a of argv) {
-    if (a === "-h" || a === "--help") return { ok: false, error: LIST_USAGE };
+    if (a === "-h" || a === "--help") return { ok: false, error: LIST_USAGE, help: true };
     if (a === "--json") {
       opts.json = true;
       continue;
@@ -4471,14 +4985,18 @@ ${LIST_USAGE}` };
 }
 async function runList(opts) {
   const out = opts.out ?? ((s) => process.stdout.write(s));
+  const err = opts.err ?? ((s) => process.stderr.write(s));
   const print = (s = "") => out(`${s}
 `);
-  const home = opts.home ?? homedir9();
+  const printErr = (s) => err(`${s}
+`);
+  const home = opts.home ?? homedir11();
   const cwd = opts.cwd ?? process.cwd();
   const loaded = await loadLocalBundles({ home, cwd });
   const servers = loaded.config?.servers ?? [];
+  for (const w of loaded.warnings) printErr(`warning: ${w}`);
   if (opts.json) {
-    print(JSON.stringify({ path: loaded.path, servers }, null, 2));
+    print(JSON.stringify({ path: loaded.path, servers, warnings: loaded.warnings }, null, 2));
     return { exitCode: 0, written: [] };
   }
   if (servers.length === 0) {
@@ -4519,12 +5037,14 @@ function parseLoginArgs(argv) {
     const a = argv[i];
     if (a === "--key") {
       const v = argv[++i];
-      if (!v) return { ok: false, error: "yaw-mcp login: --key requires a value\n\n" + LOGIN_USAGE };
+      if (!v) return { ok: false, error: `yaw-mcp login: --key requires a value
+
+${LOGIN_USAGE}` };
       opts.key = v;
     } else if (a === "--json") {
       opts.json = true;
     } else if (a === "--help" || a === "-h") {
-      return { ok: false, error: LOGIN_USAGE };
+      return { ok: false, error: LOGIN_USAGE, help: true };
     } else {
       return { ok: false, error: `yaw-mcp login: unknown argument "${a}"
 
@@ -4532,7 +5052,9 @@ ${LOGIN_USAGE}` };
     }
   }
   if (!opts.key) {
-    return { ok: false, error: "yaw-mcp login: --key is required\n\n" + LOGIN_USAGE };
+    return { ok: false, error: `yaw-mcp login: --key is required
+
+${LOGIN_USAGE}` };
   }
   return { ok: true, options: opts };
 }
@@ -4574,7 +5096,7 @@ async function runLogin(opts, io = {
       io.err(`yaw-mcp login: ${message}
 `);
     }
-    return { exitCode: err instanceof TeamSyncAuthError ? 1 : 1 };
+    return { exitCode: err instanceof TeamSyncAuthError ? 1 : 2 };
   }
 }
 
@@ -4590,7 +5112,7 @@ function parseLogoutArgs(argv) {
   const opts = {};
   for (const a of argv) {
     if (a === "--json") opts.json = true;
-    else if (a === "--help" || a === "-h") return { ok: false, error: LOGOUT_USAGE };
+    else if (a === "--help" || a === "-h") return { ok: false, error: LOGOUT_USAGE, help: true };
     else return { ok: false, error: `yaw-mcp logout: unknown argument "${a}"
 
 ${LOGOUT_USAGE}` };
@@ -4621,7 +5143,7 @@ async function runLogout(opts = {}, io = {
 
 // src/reset-learning-cmd.ts
 import { unlink as unlink2 } from "fs/promises";
-import { homedir as homedir10 } from "os";
+import { homedir as homedir12 } from "os";
 import { join as join9 } from "path";
 var RESET_LEARNING_USAGE = `Usage: yaw-mcp reset-learning
 
@@ -4644,7 +5166,7 @@ ${RESET_LEARNING_USAGE}`
   return { kind: "ok", options: {} };
 }
 async function runResetLearning(opts = {}) {
-  const home = opts.home ?? homedir10();
+  const home = opts.home ?? homedir12();
   const env = opts.env ?? process.env;
   const write = opts.out ?? ((s) => process.stdout.write(s));
   const writeErr = opts.err ?? ((s) => process.stderr.write(s));
@@ -4693,15 +5215,13 @@ function isFileNotFound2(err) {
 
 // src/secrets-cmd.ts
 import { existsSync as existsSync6 } from "fs";
-import { mkdir as mkdir3 } from "fs/promises";
-import { homedir as homedir12 } from "os";
-import { dirname as dirname3 } from "path";
+import { homedir as homedir14 } from "os";
 
 // src/secrets-vault.ts
 import { existsSync as existsSync5 } from "fs";
 import { chmod as chmod3, readFile as readFile8 } from "fs/promises";
-import { homedir as homedir11 } from "os";
-import { dirname as dirname2, join as join10 } from "path";
+import { homedir as homedir13 } from "os";
+import { join as join10 } from "path";
 
 // src/secrets-crypto.ts
 import { createCipheriv, createDecipheriv, randomBytes, scrypt as scryptCb } from "crypto";
@@ -4721,13 +5241,13 @@ async function deriveKey(passphrase, salt) {
   return scryptCallWithMaxmem(passphrase, salt, KEY_LEN);
 }
 async function scryptCallWithMaxmem(password, salt, keylen) {
-  return new Promise((resolve5, reject) => {
+  return new Promise((resolve7, reject) => {
     scryptCb(
       password,
       salt,
       keylen,
       { N: SCRYPT_N, r: SCRYPT_R, p: SCRYPT_P, maxmem: SCRYPT_MAXMEM },
-      (err, key) => err ? reject(err) : resolve5(key)
+      (err, key) => err ? reject(err) : resolve7(key)
     );
   });
 }
@@ -4759,7 +5279,8 @@ function decryptEntry(entry, key) {
 // src/secrets-vault.ts
 var SECRETS_FILENAME = "secrets.json";
 var SECRETS_SCHEMA_VERSION = 1;
-function vaultPath(home = homedir11()) {
+var VAULT_CHECK_PLAINTEXT = "yaw-mcp-vault-v1";
+function vaultPath(home = homedir13()) {
   return join10(home, CONFIG_DIRNAME, SECRETS_FILENAME);
 }
 function emptyVault() {
@@ -4769,39 +5290,50 @@ function emptyVault() {
     entries: {}
   };
 }
-async function loadVault(path3) {
-  if (!existsSync5(path3)) return null;
+async function loadVault(path5) {
+  if (!existsSync5(path5)) return null;
   let raw;
   try {
-    raw = await readFile8(path3, "utf8");
+    raw = await readFile8(path5, "utf8");
   } catch (err) {
-    log("warn", "Failed to read vault", { path: path3, error: err instanceof Error ? err.message : String(err) });
+    log("warn", "Failed to read vault", { path: path5, error: err instanceof Error ? err.message : String(err) });
     return null;
   }
   let parsed;
   try {
     parsed = JSON.parse(raw);
   } catch (err) {
-    log("warn", "Vault file is not valid JSON", { path: path3, error: err instanceof Error ? err.message : String(err) });
+    log("warn", "Vault file is not valid JSON", { path: path5, error: err instanceof Error ? err.message : String(err) });
     return null;
   }
   if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
   const obj = parsed;
   if (typeof obj.salt !== "string" || !obj.entries || typeof obj.entries !== "object") return null;
+  const entries = obj.entries;
+  for (const [name, entry] of Object.entries(entries)) {
+    if (!isEncryptedEntry(entry)) {
+      throw new Error(`vault corrupt at entry ${name}`);
+    }
+  }
+  const check = isEncryptedEntry(obj.check) ? obj.check : void 0;
   return {
     version: typeof obj.version === "number" ? obj.version : SECRETS_SCHEMA_VERSION,
     salt: obj.salt,
-    entries: obj.entries
+    entries: obj.entries,
+    ...check ? { check } : {}
   };
 }
-async function saveVault(path3, vault) {
-  const tmpDir = dirname2(path3);
-  void tmpDir;
-  await atomicWriteFile(path3, `${JSON.stringify(vault, null, 2)}
+function isEncryptedEntry(v) {
+  if (!v || typeof v !== "object") return false;
+  const e = v;
+  return typeof e.iv === "string" && typeof e.ciphertext === "string" && typeof e.authTag === "string";
+}
+async function saveVault(path5, vault) {
+  await atomicWriteFile(path5, `${JSON.stringify(vault, null, 2)}
 `);
   if (process.platform !== "win32") {
     try {
-      await chmod3(path3, 384);
+      await chmod3(path5, 384);
     } catch {
     }
   }
@@ -4817,22 +5349,39 @@ async function unlock(vault, passphrase) {
   if (cachedKey && cachedSalt === vault.salt) return cachedKey;
   const salt = Buffer.from(vault.salt, "base64");
   const key = await deriveKey(passphrase, salt);
+  verifyKey(vault, key);
   cachedKey = key;
   cachedSalt = vault.salt;
   return key;
 }
+function verifyKey(vault, key) {
+  const canary = vault.check ?? Object.values(vault.entries)[0];
+  if (!canary) return;
+  try {
+    decryptEntry(canary, key);
+  } catch {
+    throw new Error("wrong passphrase for this vault (decryption failed)");
+  }
+}
+function ensureCheck(vault, key) {
+  if (vault.check) return vault;
+  return { ...vault, check: encryptEntry(VAULT_CHECK_PLAINTEXT, key) };
+}
 function listKeys(vault) {
   return Object.keys(vault.entries).sort();
 }
 function setSecret(vault, key, name, value) {
   if (!name) throw new Error("secret name is required");
-  return {
-    ...vault,
-    entries: {
-      ...vault.entries,
-      [name]: encryptEntry(value, key)
-    }
-  };
+  return ensureCheck(
+    {
+      ...vault,
+      entries: {
+        ...vault.entries,
+        [name]: encryptEntry(value, key)
+      }
+    },
+    key
+  );
 }
 function removeSecret(vault, name) {
   if (!(name in vault.entries)) return vault;
@@ -4902,13 +5451,17 @@ Actions:
                           Requires \`yaw-mcp login\` first.
   pull                    Download the vault from mcp_secrets and write
                           it locally. Overwrites local vault. Requires
-                          \`yaw-mcp login\` first.
+                          \`yaw-mcp login\` first. Refuses when the local
+                          vault has a different salt (different passphrase
+                          lineage) unless --force is passed.
 
 Flags:
   --json                  Machine-readable output (where applicable).
   --value <v>             Inline secret value (set only). Beware shell
                           history -- prefer the default stdin prompt.
   --stdin                 Read the secret from raw stdin (set only).
+  --force                 (pull only) Overwrite even when the local vault
+                          salt differs from the remote. Back up first.
 
 Passphrase:
   Set YAW_MCP_VAULT_PASSPHRASE in the env, or you will be prompted on
@@ -4919,7 +5472,7 @@ function parseSecretsArgs(argv) {
   const opts = {};
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
-    if (a === "--help" || a === "-h") return { ok: false, error: SECRETS_USAGE };
+    if (a === "--help" || a === "-h") return { ok: false, error: SECRETS_USAGE, help: true };
     if (a === "--json") {
       opts.json = true;
       continue;
@@ -4928,9 +5481,15 @@ function parseSecretsArgs(argv) {
       opts.fromStdin = true;
       continue;
     }
+    if (a === "--force") {
+      opts.force = true;
+      continue;
+    }
     if (a === "--value") {
       const v = argv[++i];
-      if (v === void 0) return { ok: false, error: "yaw-mcp secrets: --value requires a value\n\n" + SECRETS_USAGE };
+      if (v === void 0) return { ok: false, error: `yaw-mcp secrets: --value requires a value
+
+${SECRETS_USAGE}` };
       opts.value = v;
       continue;
     }
@@ -4956,7 +5515,9 @@ ${SECRETS_USAGE}` };
 
 ${SECRETS_USAGE}` };
   }
-  if (!opts.action) return { ok: false, error: "yaw-mcp secrets: missing action\n\n" + SECRETS_USAGE };
+  if (!opts.action) return { ok: false, error: `yaw-mcp secrets: missing action
+
+${SECRETS_USAGE}` };
   if ((opts.action === "set" || opts.action === "get" || opts.action === "remove") && !opts.name) {
     return { ok: false, error: `yaw-mcp secrets ${opts.action}: <name> is required
 
@@ -4965,18 +5526,34 @@ ${SECRETS_USAGE}` };
   return { ok: true, options: opts };
 }
 async function resolvePassphrase(opts) {
-  if (opts.passphrase !== void 0) return opts.passphrase;
+  if (opts.passphrase !== void 0) return opts.passphrase.length > 0 ? opts.passphrase : null;
   const fromEnv = process.env.YAW_MCP_VAULT_PASSPHRASE;
-  if (typeof fromEnv === "string" && fromEnv.length > 0) return fromEnv;
+  if (typeof fromEnv === "string" && fromEnv.length > 0) {
+    if (fromEnv.length < MIN_PASSPHRASE_WARN_LEN) {
+      const stderr = opts.io?.stderr ?? process.stderr;
+      stderr.write(
+        `yaw-mcp secrets: warning -- YAW_MCP_VAULT_PASSPHRASE is shorter than ${MIN_PASSPHRASE_WARN_LEN} characters; consider a longer passphrase.
+`
+      );
+    }
+    return fromEnv;
+  }
   const stdin = opts.io?.stdin ?? process.stdin;
   const stdout = opts.io?.stdout ?? process.stdout;
   const isTTY = stdin.isTTY === true && stdout.isTTY === true;
   if (!isTTY) return null;
-  return readPassphraseFromTTY(stdin, stdout);
+  for (let attempt = 0; attempt < MAX_PASSPHRASE_PROMPTS; attempt++) {
+    const entered = await readPassphraseFromTTY(stdin, stdout);
+    if (entered.length > 0) return entered;
+    stdout.write("Passphrase cannot be empty.\n");
+  }
+  return null;
 }
-function readPassphraseFromTTY(stdin, stdout) {
-  stdout.write("Vault passphrase: ");
-  return new Promise((resolve5) => {
+var MAX_PASSPHRASE_PROMPTS = 3;
+var MIN_PASSPHRASE_WARN_LEN = 12;
+function readPassphraseFromTTY(stdin, stdout, prompt = "Vault passphrase: ") {
+  stdout.write(prompt);
+  return new Promise((resolve7) => {
     const chunks = [];
     const wasRaw = stdin.isRaw === true;
     try {
@@ -4995,7 +5572,7 @@ function readPassphraseFromTTY(stdin, stdout) {
           } catch {
           }
           stdin.pause();
-          resolve5(chunks.join(""));
+          resolve7(chunks.join(""));
           return;
         }
         if (ch === "") {
@@ -5025,16 +5602,12 @@ async function readStdinValue(io) {
   for await (const chunk of stdin) chunks.push(chunk);
   return chunks.join("").replace(/\r?\n$/, "");
 }
-async function ensureVaultDir(path3) {
-  const dir = dirname3(path3);
-  if (!existsSync6(dir)) await mkdir3(dir, { recursive: true });
-}
 async function runSecrets(opts, io = {
   out: (s) => process.stdout.write(s),
   err: (s) => process.stderr.write(s)
 }) {
-  const home = opts.home ?? homedir12();
-  const path3 = vaultPath(home);
+  const home = opts.home ?? homedir14();
+  const path5 = vaultPath(home);
   if (opts.action === "lock") {
     lock();
     if (opts.json) io.out(`${JSON.stringify({ ok: true, locked: true })}
@@ -5049,24 +5622,24 @@ async function runSecrets(opts, io = {
     return await runSecretsPull(opts, io);
   }
   if (opts.action === "list") {
-    const vault2 = await loadVault(path3);
+    const vault2 = await loadVault(path5);
     const keys = vault2 ? listKeys(vault2) : [];
-    if (opts.json) io.out(`${JSON.stringify({ ok: true, vault: existsSync6(path3), keys }, null, 2)}
+    if (opts.json) io.out(`${JSON.stringify({ ok: true, vault: existsSync6(path5), keys }, null, 2)}
 `);
-    else if (!vault2) io.out(`No vault at ${path3}. Run \`yaw-mcp secrets set <name>\` to create one.
+    else if (!vault2) io.out(`No vault at ${path5}. Run \`yaw-mcp secrets set <name>\` to create one.
 `);
-    else if (keys.length === 0) io.out(`Vault at ${path3} is empty.
+    else if (keys.length === 0) io.out(`Vault at ${path5} is empty.
 `);
     else {
-      io.out(`Vault at ${path3}
+      io.out(`Vault at ${path5}
 `);
       for (const k of keys) io.out(`  ${k}
 `);
     }
     return { exitCode: 0 };
   }
-  let vault = await loadVault(path3) ?? newVault();
-  const isFresh = !existsSync6(path3);
+  let vault = await loadVault(path5) ?? newVault();
+  const isFresh = !existsSync6(path5);
   const passphrase = await resolvePassphrase(opts);
   if (passphrase === null) {
     const msg = "Passphrase required. Set YAW_MCP_VAULT_PASSPHRASE or run from a TTY so we can prompt.";
@@ -5101,8 +5674,7 @@ async function runSecrets(opts, io = {
       return { exitCode: 1 };
     }
     vault = setSecret(vault, key, name, value);
-    await ensureVaultDir(path3);
-    await saveVault(path3, vault);
+    await saveVault(path5, vault);
     if (opts.json) io.out(`${JSON.stringify({ ok: true, name, fresh_vault: isFresh })}
 `);
     else io.out(`${isFresh ? "Created vault and " : ""}Stored secret "${name}".
@@ -5148,7 +5720,7 @@ async function runSecrets(opts, io = {
       return { exitCode: 1 };
     }
     vault = removeSecret(vault, name);
-    await saveVault(path3, vault);
+    await saveVault(path5, vault);
     if (opts.json) io.out(`${JSON.stringify({ ok: true, removed: name })}
 `);
     else io.out(`Removed "${name}".
@@ -5161,8 +5733,8 @@ async function runSecrets(opts, io = {
 }
 var MCP_SECRETS_RESOURCE = "mcp_secrets";
 async function runSecretsPush(opts, io) {
-  const home = opts.home ?? homedir12();
-  const path3 = vaultPath(home);
+  const home = opts.home ?? homedir14();
+  const path5 = vaultPath(home);
   const session = await getSession({ home, baseUrl: opts.baseUrl });
   if (!session) {
     const msg = "Not signed in. Run `yaw-mcp login --key <license-key>` first.";
@@ -5172,9 +5744,9 @@ async function runSecretsPush(opts, io) {
 `);
     return { exitCode: 1 };
   }
-  const vault = await loadVault(path3);
+  const vault = await loadVault(path5);
   if (!vault) {
-    const msg = `No local vault at ${path3} to push. Run \`yaw-mcp secrets set <name>\` first.`;
+    const msg = `No local vault at ${path5} to push. Run \`yaw-mcp secrets set <name>\` first.`;
     if (opts.json) io.err(`${JSON.stringify({ ok: false, error: msg })}
 `);
     else io.err(`yaw-mcp secrets push: ${msg}
@@ -5224,8 +5796,8 @@ async function runSecretsPush(opts, io) {
   }
 }
 async function runSecretsPull(opts, io) {
-  const home = opts.home ?? homedir12();
-  const path3 = vaultPath(home);
+  const home = opts.home ?? homedir14();
+  const path5 = vaultPath(home);
   const session = await getSession({ home, baseUrl: opts.baseUrl });
   if (!session) {
     const msg = "Not signed in. Run `yaw-mcp login --key <license-key>` first.";
@@ -5237,7 +5809,9 @@ async function runSecretsPull(opts, io) {
   }
   try {
     const remote = await getResource(MCP_SECRETS_RESOURCE, { home, baseUrl: opts.baseUrl });
-    if (!remote.data || !remote.data.salt || !remote.data.entries) {
+    const remoteEntries = remote.data?.entries;
+    const remoteHasEntries = remoteEntries !== void 0 && remoteEntries !== null && typeof remoteEntries === "object" && Object.keys(remoteEntries).length > 0;
+    if (!remote.data || !remote.data.salt || !remoteHasEntries) {
       const msg = "Remote mcp_secrets is empty. Push from this machine to seed it.";
       if (opts.json) io.out(`${JSON.stringify({ ok: true, empty: true })}
 `);
@@ -5245,18 +5819,29 @@ async function runSecretsPull(opts, io) {
 `);
       return { exitCode: 0 };
     }
-    await ensureVaultDir(path3);
-    await saveVault(path3, remote.data);
+    const localVault = await loadVault(path5);
+    const localHasEntries = localVault !== null && Object.keys(localVault.entries).length > 0;
+    if (localHasEntries && localVault.salt !== remote.data.salt && !opts.force) {
+      const msg = `Local vault at ${path5} has a different salt than the remote (different passphrase lineage). Back up ${path5} first, then re-run with --force to overwrite.`;
+      if (opts.json) io.err(`${JSON.stringify({ ok: false, error: msg })}
+`);
+      else io.err(`yaw-mcp secrets pull: ${msg}
+`);
+      return { exitCode: 1 };
+    }
+    await saveVault(path5, remote.data);
     lock();
     const count = Object.keys(remote.data.entries).length;
     if (opts.json) {
       io.out(
-        `${JSON.stringify({ ok: true, secret_count: count, remote_version: remote.version, written: path3 }, null, 2)}
+        `${JSON.stringify({ ok: true, secret_count: count, remote_version: remote.version, written: path5 }, null, 2)}
 `
       );
     } else {
-      io.out(`Pulled ${count} secret${count === 1 ? "" : "s"} (encrypted) -> ${path3}
-`);
+      io.out(
+        `Local vault replaced with remote copy: ${count} secret${count === 1 ? "" : "s"} (encrypted) -> ${path5}
+`
+      );
       io.out("Vault locked -- next secrets command will prompt for the passphrase.\n");
     }
     return { exitCode: 0 };
@@ -5280,8 +5865,8 @@ async function runSecretsPull(opts, io) {
 
 // src/server.ts
 import { readFile as readFile10 } from "fs/promises";
-import { homedir as homedir13 } from "os";
-import { isAbsolute, relative, resolve as resolve4 } from "path";
+import { homedir as homedir15 } from "os";
+import { isAbsolute as isAbsolute2, relative, resolve as resolve6 } from "path";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import {
@@ -5314,33 +5899,38 @@ async function fetchLatestVersion2() {
   }
 }
 function defaultSpawn2(cmd, args) {
+  let errorFired = false;
+  const correctiveCmd = cmd === "npm" ? "npm install -g @yawlabs/mcp@latest" : cmd === "pnpm" ? "pnpm add -g @yawlabs/mcp@latest" : "bun add -g @yawlabs/mcp@latest";
   const child = spawn3(cmd, args, {
     stdio: "ignore",
     // Stay a child of this process (not detached) so it dies with yaw-mcp
-    // if yaw-mcp exits mid-install -- a half-finished `npm i -g` is fine
-    // (npm is atomic per package) and a re-run next startup completes it.
+    // if yaw-mcp exits mid-install -- a half-finished install is fine
+    // (npm/pnpm/bun are atomic per package) and a re-run next startup completes it.
     detached: false,
     shell: process.platform === "win32"
   });
   child.on("close", (code) => {
+    if (errorFired) return;
     if (code === 0) {
       log("info", "yaw-mcp self-upgrade complete; the next client restart will run the new version");
     } else {
+      const hint = cmd === "npm" ? " (often EACCES on a sudo-installed global -- run with the right permissions)" : "";
       log(
         "warn",
-        "yaw-mcp self-upgrade: npm exited non-zero (often EACCES on a sudo-installed global). Run `npm install -g @yawlabs/mcp@latest` with the right permissions, or set YAW_MCP_AUTO_UPGRADE=0 to silence this.",
+        `yaw-mcp self-upgrade: ${cmd} exited non-zero${hint}. Run \`${correctiveCmd}\` manually, or set YAW_MCP_AUTO_UPGRADE=0 to silence this.`,
         { code }
       );
     }
   });
   child.on("error", (err) => {
-    log("warn", "yaw-mcp self-upgrade: npm spawn failed", { error: err?.message });
+    errorFired = true;
+    log("warn", `yaw-mcp self-upgrade: ${cmd} spawn failed`, { error: err?.message });
   });
 }
 async function maybeAutoUpgrade(deps = {}) {
   const optOut = process.env.YAW_MCP_AUTO_UPGRADE;
   if (optOut === "0" || optOut?.toLowerCase() === "false") return;
-  const current = deps.currentVersion ?? (true ? "0.60.6" : "dev");
+  const current = deps.currentVersion ?? (true ? "0.62.0" : "dev");
   if (current === "dev") return;
   const method = (deps.isSeaImpl ? await deps.isSeaImpl() : await detectSea()) ? "binary" : detectInstallMethod(deps.argvPath ?? process.argv[1]);
   const latest = await (deps.fetchLatestImpl ?? fetchLatestVersion2)();
@@ -5365,11 +5955,23 @@ async function maybeAutoUpgrade(deps = {}) {
     log("info", "yaw-mcp (standalone binary) is behind npm; download the latest build to update", { current, latest });
     return;
   }
-  log("info", "yaw-mcp is out of date; restart your MCP client to pick up the latest version", {
-    current,
-    latest,
-    method
-  });
+  if (method === "npx") {
+    log("info", "yaw-mcp is out of date; restart your MCP client to pick up the latest version", {
+      current,
+      latest,
+      method
+    });
+  } else {
+    log(
+      "info",
+      "yaw-mcp is out of date; run `yaw-mcp upgrade --run` to update this install (a restart won't refresh a stale global)",
+      {
+        current,
+        latest,
+        method
+      }
+    );
+  }
 }
 
 // src/compliance.ts
@@ -5671,6 +6273,28 @@ function resolveArgs(args, bindings) {
   }
   return args;
 }
+function collectRefDeps(args) {
+  const deps = /* @__PURE__ */ new Set();
+  const walk = (node) => {
+    if (isRefNode(node)) {
+      const tokens = parseRefPath(node.$ref);
+      if (tokens && tokens.length > 0 && typeof tokens[0] === "string") {
+        deps.add(tokens[0]);
+      }
+      return;
+    }
+    if (Array.isArray(node)) {
+      for (const v of node) walk(v);
+      return;
+    }
+    if (node !== null && typeof node === "object") {
+      for (const v of Object.values(node)) walk(v);
+      return;
+    }
+  };
+  walk(args);
+  return Array.from(deps);
+}
 var MAX_EXEC_STEPS = 16;
 function validateExecRequest(req) {
   if (req === null || typeof req !== "object" || Array.isArray(req)) {
@@ -5687,6 +6311,7 @@ function validateExecRequest(req) {
     return { ok: false, message: `too many steps (${steps.length}); max is ${MAX_EXEC_STEPS}` };
   }
   const seenIds = /* @__PURE__ */ new Set();
+  const positionalSlots = /* @__PURE__ */ new Set();
   for (let i = 0; i < steps.length; i++) {
     const step = steps[i];
     if (step === null || typeof step !== "object" || Array.isArray(step)) {
@@ -5704,16 +6329,33 @@ function validateExecRequest(req) {
         return { ok: false, message: `step ${i}: duplicate id "${s.id}"` };
       }
       seenIds.add(s.id);
+    } else {
+      positionalSlots.add(String(i));
     }
     if (s.args !== void 0 && (s.args === null || typeof s.args !== "object" || Array.isArray(s.args))) {
       return { ok: false, message: `step ${i}: \`args\` must be an object if provided` };
     }
   }
+  for (const id of seenIds) {
+    if (positionalSlots.has(id)) {
+      return {
+        ok: false,
+        message: `step id "${id}" collides with the positional binding key of an unnamed step; rename it`
+      };
+    }
+  }
   if (ret !== void 0) {
     if (typeof ret !== "string" || ret.length === 0) {
       return { ok: false, message: "`return` must be a non-empty step id string" };
     }
-    if (!seenIds.has(ret)) {
+    const allBindingKeys = new Set(seenIds);
+    for (let i = 0; i < steps.length; i++) {
+      const s = steps[i];
+      if (typeof s.id !== "string" || s.id.length === 0) {
+        allBindingKeys.add(String(i));
+      }
+    }
+    if (!allBindingKeys.has(ret)) {
       return { ok: false, message: `\`return\` references unknown step id "${ret}"` };
     }
   }
@@ -5726,18 +6368,18 @@ function stepBindingKey(step, index) {
 // src/guide.ts
 import { readFile as readFile9 } from "fs/promises";
 var GUIDE_READ_TIMEOUT_MS = 1e3;
-async function readGuide(path3, scope) {
+async function readGuide(path5, scope) {
   let raw;
   try {
     raw = await Promise.race([
-      readFile9(path3, "utf8"),
+      readFile9(path5, "utf8"),
       new Promise(
         (_, reject) => setTimeout(() => reject(new Error("guide read timeout")), GUIDE_READ_TIMEOUT_MS)
       )
     ]);
   } catch (err) {
     if (err instanceof Error && err.message === "guide read timeout") {
-      log("warn", "Guide read timed out", { path: path3 });
+      log("warn", "Guide read timed out", { path: path5 });
     }
     return null;
   }
@@ -5745,7 +6387,7 @@ async function readGuide(path3, scope) {
   if (content.length === 0) {
     return null;
   }
-  return { scope, path: path3, content };
+  return { scope, path: path5, content };
 }
 async function loadUserGuide(home) {
   const p = guidePath(userConfigDir(home));
@@ -5933,6 +6575,11 @@ var LEARNING_MIN_BOOST = 0.9;
 var PENALTY_RATE_THRESHOLD = 0.8;
 var SATURATION_AT = 10;
 var LearningStore = class {
+  // Growth bound: the map keys on namespace, and recordDispatch is only
+  // reached with validated/bounded namespaces from the dispatch path, so
+  // cardinality is capped by the number of distinct configured namespaces.
+  // No explicit cap is needed unless untrusted strings can reach
+  // recordDispatch (they cannot today).
   usage = /* @__PURE__ */ new Map();
   recordDispatch(namespace) {
     const prev = this.usage.get(namespace);
@@ -5950,6 +6597,50 @@ var LearningStore = class {
       lastUsedAt: Date.now()
     });
   }
+  // Graded outcome in [0,1] for a single dispatched proxy call. This is
+  // the SOUND replacement for the binary recordDispatch + recordSuccess
+  // pair on the proxy path: a 200/empty/error-shaped reply no longer banks
+  // full credit (the reward is computed by reward.ts/computeOutcomeReward).
+  // One call records BOTH the dispatch (denominator) and the graded credit
+  // (numerator), so callers no longer pair recordDispatch with a
+  // conditional recordSuccess. reward is clamped to [0,1].
+  recordOutcome(namespace, reward) {
+    const r = Number.isFinite(reward) ? Math.min(1, Math.max(0, reward)) : 0;
+    const prev = this.usage.get(namespace);
+    this.usage.set(namespace, {
+      dispatched: (prev?.dispatched ?? 0) + 1,
+      succeeded: (prev?.succeeded ?? 0) + r,
+      lastUsedAt: Date.now()
+    });
+  }
+  // Synthetic failed observation with NO success credit. Used by the
+  // re-dispatch routing-miss signal (redispatch.ts): when the model
+  // abandons server A and re-routes a similar intent to B, A's earlier
+  // "clean" reply was useless in hindsight, so we depress A's success rate
+  // by one failed observation. Denominator-only — same shape as a
+  // recordDispatch that never sees a matching success.
+  recordMiss(namespace) {
+    const prev = this.usage.get(namespace);
+    this.usage.set(namespace, {
+      dispatched: (prev?.dispatched ?? 0) + 1,
+      succeeded: prev?.succeeded ?? 0,
+      lastUsedAt: Date.now()
+    });
+  }
+  // Apply a DELTA to a namespace's success credit WITHOUT touching the
+  // dispatched count. Used by the optional LLM reward grader (reward-grader.ts)
+  // to revise a previously-recorded heuristic reward in the background: the
+  // caller records the heuristic via recordOutcome immediately, then later
+  // adjusts by (graded - heuristic) once the LLM verdict lands. Adding a delta
+  // (rather than setting an absolute) stays correct under concurrent
+  // recordOutcome calls on the same namespace. No-op for an unknown namespace
+  // (nothing to revise); succeeded is clamped to [0, dispatched].
+  adjustSucceeded(namespace, delta) {
+    const u = this.usage.get(namespace);
+    if (!u || !Number.isFinite(delta)) return;
+    u.succeeded = Math.min(u.dispatched, Math.max(0, u.succeeded + delta));
+    u.lastUsedAt = Date.now();
+  }
   get(namespace) {
     return this.usage.get(namespace);
   }
@@ -5962,8 +6653,9 @@ var LearningStore = class {
   boostFactor(namespace) {
     const u = this.usage.get(namespace);
     if (!u) return 1;
-    if (u.dispatched >= LEARNING_MIN_OBSERVATIONS) {
-      const rate = u.succeeded / u.dispatched;
+    const dispatched = Math.max(u.dispatched, u.succeeded);
+    if (dispatched >= LEARNING_MIN_OBSERVATIONS) {
+      const rate = u.succeeded / dispatched;
       if (rate < PENALTY_RATE_THRESHOLD) {
         const distance = Math.min(1, (PENALTY_RATE_THRESHOLD - rate) / PENALTY_RATE_THRESHOLD);
         return 1 - distance * (1 - LEARNING_MIN_BOOST);
@@ -6007,7 +6699,11 @@ var LearningStore = class {
   loadSnapshot(snapshot) {
     this.usage.clear();
     for (const [ns, usage] of Object.entries(snapshot)) {
-      this.usage.set(ns, { dispatched: usage.dispatched, succeeded: usage.succeeded, lastUsedAt: usage.lastUsedAt });
+      const dispatched = Number.isFinite(usage.dispatched) ? Math.max(0, usage.dispatched) : 0;
+      const succeededRaw = Number.isFinite(usage.succeeded) ? Math.max(0, usage.succeeded) : 0;
+      const succeeded = Math.min(succeededRaw, dispatched);
+      const lastUsedAt = Number.isFinite(usage.lastUsedAt) ? usage.lastUsedAt : 0;
+      this.usage.set(ns, { dispatched, succeeded, lastUsedAt });
     }
   }
 };
@@ -6137,6 +6833,7 @@ var META_TOOLS = {
         },
         budget: {
           type: "number",
+          default: 1,
           description: "How many top-ranked servers to load into the session. Defaults to 1. Cap is 10. Raise only when one task genuinely spans multiple servers."
         }
       },
@@ -6684,8 +7381,9 @@ async function routeResourceRead(uri, resourceRoutes, activeConnections, builtin
     const result = await connection.client.readResource({ uri: route.originalUri });
     return result;
   } catch (err) {
-    log("error", "Resource read failed", { uri, namespace: route.namespace, error: err.message });
-    return { contents: [{ uri, text: `Error: ${err.message}` }] };
+    const message = err instanceof Error ? err.message : String(err);
+    log("error", "Resource read failed", { uri, namespace: route.namespace, error: message });
+    return { contents: [{ uri, text: `Error: ${message}` }] };
   }
 }
 async function routePromptGet(name, args, promptRoutes, activeConnections) {
@@ -6703,8 +7401,9 @@ async function routePromptGet(name, args, promptRoutes, activeConnections) {
     const result = await connection.client.getPrompt({ name: route.originalName, arguments: args });
     return result;
   } catch (err) {
-    log("error", "Prompt get failed", { name, namespace: route.namespace, error: err.message });
-    return { messages: [{ role: "user", content: { type: "text", text: `Error: ${err.message}` } }] };
+    const message = err instanceof Error ? err.message : String(err);
+    log("error", "Prompt get failed", { name, namespace: route.namespace, error: message });
+    return { messages: [{ role: "user", content: { type: "text", text: `Error: ${message}` } }] };
   }
 }
 async function routeToolCall(toolName, args, toolRoutes, activeConnections) {
@@ -6791,12 +7490,14 @@ function pruneWhitespace(text) {
 function pruneJson(value) {
   if (value === null || value === void 0) return void 0;
   if (Array.isArray(value)) {
-    const cleaned = [];
-    for (const el of value) {
+    if (value.length === 0) return void 0;
+    const cleaned = value.map((el) => {
       const pv = pruneJson(el);
-      if (pv !== void 0) cleaned.push(pv);
-    }
-    return cleaned.length === 0 ? void 0 : cleaned;
+      if (pv !== void 0) return pv;
+      if (el !== null && typeof el === "object" && !Array.isArray(el)) return {};
+      return null;
+    });
+    return cleaned;
   }
   if (typeof value === "object") {
     const out = {};
@@ -6849,122 +7550,87 @@ function formatToolNotFound(server, toolName, availableTools) {
   return `"${toolName}" not found on "${server.namespace}". Available tools: ${names}`;
 }
 
-// src/relevance.ts
-var K1 = 1.2;
-var B = 0.75;
-var FIELD_WEIGHTS = {
-  name: 3,
-  namespace: 2,
-  description: 1.5,
-  toolName: 2,
-  toolDescription: 1
-};
-var MIN_TOKEN_LEN = 3;
-function tokenize(text) {
-  if (!text) return [];
-  return text.toLowerCase().split(/[^a-z0-9]+/).filter((w) => w.length >= MIN_TOKEN_LEN);
-}
-function buildDocFields(server) {
-  const toolNameTokens = [];
-  const toolDescriptionTokens = [];
-  for (const tool of server.tools) {
-    toolNameTokens.push(...tokenize(tool.name));
-    toolDescriptionTokens.push(...tokenize(tool.description));
-  }
-  return {
-    namespace: tokenize(server.namespace),
-    name: tokenize(server.name),
-    description: tokenize(server.description),
-    toolName: toolNameTokens,
-    toolDescription: toolDescriptionTokens
-  };
-}
-function termFreq(tokens, term) {
-  let count = 0;
-  for (const t of tokens) {
-    if (t === term) count++;
-  }
-  return count;
-}
-function bm25Score(queryTerms, fields, idf, avgFieldLen, idfValues) {
-  let score = 0;
-  const seen = /* @__PURE__ */ new Set();
-  for (const term of queryTerms) {
-    if (seen.has(term)) continue;
-    seen.add(term);
-    const termIdf = idfValues.get(term);
-    if (termIdf === void 0 || termIdf <= 0) continue;
-    for (const [fieldName, weight] of Object.entries(FIELD_WEIGHTS)) {
-      const fieldTokens = fields[fieldName];
-      if (fieldTokens.length === 0) continue;
-      const tf = termFreq(fieldTokens, term);
-      if (tf === 0) continue;
-      const avg = avgFieldLen[fieldName] || 1;
-      const normLen = 1 - B + B * (fieldTokens.length / avg);
-      const numerator = tf * (K1 + 1);
-      const denominator = tf + K1 * normLen;
-      score += weight * termIdf * (numerator / denominator);
+// src/redispatch.ts
+var RING_CAP = 8;
+var WINDOW_MS = 12e4;
+var JACCARD_THRESHOLD = 0.4;
+var MIN_SHARED_TOKENS = 3;
+function jaccard(a, b) {
+  if (a.size === 0 || b.size === 0) return { score: 0, shared: 0 };
+  let shared = 0;
+  for (const t of a) {
+    if (b.has(t)) shared++;
+  }
+  const union = a.size + b.size - shared;
+  return { score: union === 0 ? 0 : shared / union, shared };
+}
+var RedispatchTracker = class {
+  // Newest record is at the END of the array. Capped at RING_CAP by shifting
+  // the oldest off the front.
+  ring = [];
+  // Record a new dispatch decision. intentTokens = tokenize(intent).
+  push(namespace, intentTokens, now) {
+    for (const rec of this.ring) {
+      if (rec.namespace === namespace && !rec.consumed) rec.furtherUse = true;
+    }
+    this.ring.push({
+      namespace,
+      tokens: new Set(intentTokens),
+      time: now,
+      replied: false,
+      cleanReply: false,
+      furtherUse: false,
+      consumed: false
+    });
+    while (this.ring.length > RING_CAP) {
+      this.ring.shift();
     }
   }
-  void idf;
-  return score;
-}
-function rankServers(context, servers) {
-  const queryTerms = tokenize(context);
-  if (queryTerms.length === 0 || servers.length === 0) return [];
-  const docsWithFields = servers.map((s) => ({ server: s, fields: buildDocFields(s) }));
-  const N = docsWithFields.length;
-  const df = /* @__PURE__ */ new Map();
-  for (const { fields } of docsWithFields) {
-    const bag = /* @__PURE__ */ new Set([
-      ...fields.namespace,
-      ...fields.name,
-      ...fields.description,
-      ...fields.toolName,
-      ...fields.toolDescription
-    ]);
-    for (const term of bag) {
-      df.set(term, (df.get(term) ?? 0) + 1);
+  // Called from the proxy path when the dispatched server replied. We only
+  // care about the MOST-RECENT record for `namespace` (that's the dispatch
+  // the reply belongs to).
+  //
+  // First clean reply for that record sets cleanReply=true. Any SUBSEQUENT
+  // call for that same record sets furtherUse=true (the server kept getting
+  // used -> NOT abandoned, so it can never be a loser).
+  markReply(namespace, clean) {
+    for (let i = this.ring.length - 1; i >= 0; i--) {
+      const rec = this.ring[i];
+      if (rec.namespace !== namespace) continue;
+      if (!rec.replied) {
+        rec.replied = true;
+        if (clean) rec.cleanReply = true;
+      } else {
+        rec.furtherUse = true;
+      }
+      return;
     }
   }
-  const idfValues = /* @__PURE__ */ new Map();
-  for (const [term, d] of df) {
-    idfValues.set(term, Math.log((N - d + 0.5) / (d + 0.5) + 1));
-  }
-  const totalLen = {
-    namespace: 0,
-    name: 0,
-    description: 0,
-    toolName: 0,
-    toolDescription: 0
-  };
-  for (const { fields } of docsWithFields) {
-    totalLen.namespace += fields.namespace.length;
-    totalLen.name += fields.name.length;
-    totalLen.description += fields.description.length;
-    totalLen.toolName += fields.toolName.length;
-    totalLen.toolDescription += fields.toolDescription.length;
-  }
-  const avgFieldLen = {
-    namespace: totalLen.namespace / N,
-    name: totalLen.name / N,
-    description: totalLen.description / N,
-    toolName: totalLen.toolName / N,
-    toolDescription: totalLen.toolDescription / N
-  };
-  const results = [];
-  for (const { server, fields } of docsWithFields) {
-    const score = bm25Score(queryTerms, fields, /* @__PURE__ */ new Map(), avgFieldLen, idfValues);
-    if (score > 0) {
-      results.push({ namespace: server.namespace, score });
+  // When a new dispatch (newNamespace) lands, look back over the recent ring
+  // for an ABANDONED record (cleanReply && !furtherUse) on a DIFFERENT
+  // namespace whose intent is SIMILAR to newTokens and within the time
+  // window. If found, that earlier server was the wrong route -> return
+  // { loser }. isExcluded(a, b) returns true when a->b is a known legitimate
+  // multi-server chain (curated bundle / detected pack) and must NOT be
+  // treated as a miss. Returns null when no miss.
+  detectMiss(newNamespace, newTokens, now, isExcluded) {
+    const newSet = new Set(newTokens);
+    for (let i = this.ring.length - 1; i >= 0; i--) {
+      const rec = this.ring[i];
+      if (rec.consumed) continue;
+      if (rec.namespace === newNamespace) continue;
+      if (!rec.cleanReply || rec.furtherUse) continue;
+      if (now - rec.time > WINDOW_MS) continue;
+      if (isExcluded(rec.namespace, newNamespace)) continue;
+      const { score, shared } = jaccard(rec.tokens, newSet);
+      if (shared < MIN_SHARED_TOKENS) continue;
+      if (score < JACCARD_THRESHOLD) continue;
+      rec.consumed = true;
+      return { loser: rec.namespace };
     }
+    return null;
   }
-  results.sort((a, b) => {
-    if (b.score !== a.score) return b.score - a.score;
-    return a.namespace < b.namespace ? -1 : 1;
-  });
-  return results;
-}
+};
 
 // src/rerank.ts
 import { request as request7 } from "undici";
@@ -7064,18 +7730,150 @@ async function callLegacyRerank(payload) {
     return null;
   }
 }
-async function readTeamCookie() {
-  const teamSync = await import("./team-sync-5356FJP6.js");
-  const session = await teamSync.getSession();
-  if (!session) return null;
-  const { readFile: readFile12 } = await import("fs/promises");
-  try {
-    const raw = await readFile12(teamSync.sessionStatePath(), "utf8");
-    const parsed = JSON.parse(raw);
-    return typeof parsed.cookie === "string" && parsed.cookie ? parsed.cookie : null;
-  } catch {
-    return null;
+async function readTeamCookie() {
+  const teamSync = await import("./team-sync-B4R6FLKR.js");
+  return teamSync.getCachedCookie();
+}
+
+// src/reward-grader.ts
+function isRewardGraderEnabled() {
+  const raw = process.env.YAW_MCP_REWARD_GRADER;
+  if (!raw) return false;
+  const v = raw.trim().toLowerCase();
+  return v === "1" || v === "true";
+}
+function isUncertainReward(heuristic) {
+  return heuristic >= 0.2 && heuristic <= 0.3;
+}
+var GRADER_MAX_TOKENS = 8;
+var GRADER_TIMEOUT_MS = 4e3;
+var RESULT_SNIPPET_LEN = 600;
+function firstResultText(result) {
+  const content = result.content;
+  if (Array.isArray(content)) {
+    for (const block of content) {
+      if (typeof block.text === "string" && block.text.trim().length > 0) {
+        const t = block.text.trim();
+        return t.length > RESULT_SNIPPET_LEN ? `${t.slice(0, RESULT_SNIPPET_LEN)}...` : t;
+      }
+    }
+  }
+  return "(empty result)";
+}
+function buildGraderPrompt(ctx) {
+  const lines = ["You are grading whether an MCP tool call accomplished its goal."];
+  if (ctx.intent && ctx.intent.trim().length > 0) {
+    lines.push("", `Goal: ${ctx.intent.trim()}`);
+  }
+  lines.push(
+    "",
+    `Tool called: ${ctx.toolName}`,
+    `Result (truncated): ${ctx.resultText}`,
+    "",
+    "Did the tool call accomplish the goal / return a useful, on-task result?",
+    "Reply with ONLY one word: YES, PARTIAL, or NO."
+  );
+  return lines.join("\n");
+}
+function parseGrade(text) {
+  const m = /\b(yes|partial|no)\b/i.exec(text);
+  if (!m) return null;
+  switch (m[1].toLowerCase()) {
+    case "yes":
+      return 1;
+    case "partial":
+      return 0.5;
+    default:
+      return 0;
+  }
+}
+async function gradeOutcomeViaSampling(server, ctx) {
+  const caps = server.getClientCapabilities();
+  if (!caps?.sampling) return null;
+  const prompt = buildGraderPrompt(ctx);
+  try {
+    const result = await withTimeout(
+      server.createMessage({
+        messages: [{ role: "user", content: { type: "text", text: prompt } }],
+        maxTokens: GRADER_MAX_TOKENS,
+        includeContext: "none"
+      }),
+      GRADER_TIMEOUT_MS
+    );
+    if (!result || typeof result !== "object" || !("content" in result) || !result.content) return null;
+    const text = extractText(result.content);
+    if (!text) return null;
+    return parseGrade(text);
+  } catch (err) {
+    log("warn", "Reward grader sampling failed", { error: err instanceof Error ? err.message : String(err) });
+    return null;
+  }
+}
+function withTimeout(p, ms) {
+  return new Promise((resolve7) => {
+    const timer = setTimeout(() => resolve7(null), ms);
+    if (typeof timer === "object" && timer && "unref" in timer) timer.unref();
+    p.then(
+      (v) => {
+        clearTimeout(timer);
+        resolve7(v);
+      },
+      () => {
+        clearTimeout(timer);
+        resolve7(null);
+      }
+    );
+  });
+}
+function extractText(content) {
+  if (Array.isArray(content)) {
+    return content.map((c) => c && typeof c === "object" && "type" in c && c.type === "text" && "text" in c ? String(c.text) : "").filter(Boolean).join("\n");
+  }
+  if (content && typeof content === "object" && "type" in content) {
+    const block = content;
+    if (block.type === "text" && typeof block.text === "string") return block.text;
+  }
+  return "";
+}
+
+// src/reward.ts
+var ERROR_SHAPED_CATEGORIES = /* @__PURE__ */ new Set([
+  "validation_error",
+  "timeout",
+  "unauthorized",
+  "unknown_tool",
+  "connection_lost",
+  "rate_limited",
+  "not_found"
+]);
+function firstTextBlock(result) {
+  const content = result.content;
+  if (!content || content.length === 0) return void 0;
+  for (const block of content) {
+    if (typeof block.text === "string" && block.text.trim().length > 0) return block.text;
+  }
+  return void 0;
+}
+function isEmptyBody(result) {
+  const content = result.content;
+  if (!content || content.length === 0) return true;
+  for (const block of content) {
+    if (typeof block.text === "string" && block.text.trim().length > 0) {
+      return false;
+    }
+  }
+  return true;
+}
+function computeOutcomeReward(result) {
+  if (result.isError === true) return 0;
+  const text = firstTextBlock(result);
+  if (text !== void 0) {
+    if (ERROR_SHAPED_CATEGORIES.has(classifyError(text))) {
+      return 0.2;
+    }
   }
+  if (isEmptyBody(result)) return 0.3;
+  return 1;
 }
 
 // src/runtime-detect.ts
@@ -7089,55 +7887,58 @@ function initRuntimeDetect(url, tok) {
   apiUrl4 = url;
   token4 = tok;
 }
+var PYTHON_CANDIDATES = process.platform === "win32" ? [
+  { bin: "py", args: ["-3", "--version"] },
+  { bin: "python", args: ["--version"] },
+  { bin: "python3", args: ["--version"] }
+] : [
+  { bin: "python3", args: ["--version"] },
+  { bin: "python", args: ["--version"] }
+];
 var PROBES = {
   node: {
-    bin: "node",
-    args: ["--version"],
+    candidates: [{ bin: "node", args: ["--version"] }],
     parse: (out) => out.trim().replace(/^v/, "") || true
   },
   npx: {
-    bin: "npx",
-    args: ["--version"],
+    candidates: [{ bin: "npx", args: ["--version"] }],
     parse: (out) => out.trim() || true
   },
   python: {
-    bin: process.platform === "win32" ? "python" : "python3",
-    args: ["--version"],
+    candidates: PYTHON_CANDIDATES,
     parse: (out) => {
       const m = out.match(/Python\s+(\d+\.\d+\.\d+)/);
       return m ? m[1] : true;
     }
   },
   uvx: {
-    bin: "uvx",
-    args: ["--version"],
+    candidates: [{ bin: "uvx", args: ["--version"] }],
     parse: (out) => {
       const m = out.match(/(\d+\.\d+\.\d+)/);
       return m ? m[1] : true;
     }
   },
   docker: {
-    bin: "docker",
-    args: ["--version"],
+    candidates: [{ bin: "docker", args: ["--version"] }],
     parse: (out) => {
       const m = out.match(/Docker version (\d+\.\d+\.\d+)/);
       return m ? m[1] : true;
     }
   }
 };
-async function probe(name, p) {
-  return new Promise((resolve5) => {
+async function probeCandidate(c, parse) {
+  return new Promise((resolve7) => {
     let settled = false;
     const settle = (v) => {
       if (settled) return;
       settled = true;
-      resolve5(v);
+      resolve7(v);
     };
     let stdout = "";
     let stderr = "";
     let child;
     try {
-      child = spawn4(p.bin, p.args, {
+      child = spawn4(c.bin, c.args, {
         stdio: ["ignore", "pipe", "pipe"],
         // Windows needs a shell for PATH lookup of .cmd/.bat shims —
         // node/npx/uvx arrive as `npx.cmd` in PATH, and native spawn
@@ -7180,16 +7981,22 @@ async function probe(name, p) {
         return;
       }
       const text = stdout || stderr;
-      if (p.parse) {
-        const parsed = p.parse(text);
+      if (parse) {
+        const parsed = parse(text);
         settle(parsed);
       } else {
         settle(true);
       }
     });
-    void name;
   });
 }
+async function probe(_name, p) {
+  for (const c of p.candidates) {
+    const result = await probeCandidate(c, p.parse);
+    if (result !== false) return result;
+  }
+  return false;
+}
 async function detectRuntimes() {
   const entries = await Promise.all(
     Object.entries(PROBES).map(async ([name, p]) => [name, await probe(name, p)])
@@ -7233,6 +8040,9 @@ async function reportRuntimes() {
 // src/sampling-rank.ts
 var SAMPLING_TIEBREAK_RATIO = 0.9;
 var SAMPLING_MAX_TOKENS = 120;
+var MAX_SAMPLES = 5;
+var SAMPLING_TIMEOUT_MS = 2e3;
+var AGGRESSIVE_AMBIGUITY_THRESHOLD = 0.6;
 function shouldTiebreak(ranked, ratio = SAMPLING_TIEBREAK_RATIO) {
   if (ranked.length < 2) return false;
   const [top, second] = ranked;
@@ -7242,7 +8052,7 @@ function shouldTiebreak(ranked, ratio = SAMPLING_TIEBREAK_RATIO) {
 function buildTiebreakPrompt(intent, candidates) {
   const blocks = candidates.map((c, i) => {
     const toolLine = c.tools.length > 0 ? c.tools.slice(0, 8).map((t) => t.name).join(", ") : "(no tool metadata yet)";
-    return `${i + 1}. ${c.namespace}${c.description ? ` \u2014 ${c.description}` : ""}
+    return `${i + 1}. ${c.namespace}${c.description ? ` -- ${c.description}` : ""}
    tools: ${toolLine}`;
   });
   return [
@@ -7279,27 +8089,7 @@ function parseTiebreakResponse(response, candidates) {
 function escapeRegex(s) {
   return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
-async function tiebreakViaSampling(server, intent, candidates) {
-  const caps = server.getClientCapabilities();
-  if (!caps?.sampling) return null;
-  if (candidates.length < 2) return null;
-  const prompt = buildTiebreakPrompt(intent, candidates);
-  try {
-    const result = await server.createMessage({
-      messages: [{ role: "user", content: { type: "text", text: prompt } }],
-      maxTokens: SAMPLING_MAX_TOKENS,
-      // Hint that we want a cheap, fast response.
-      includeContext: "none"
-    });
-    const text = result && typeof result === "object" && "content" in result && result.content ? extractText(result.content) : "";
-    if (!text) return null;
-    return parseTiebreakResponse(text, candidates);
-  } catch (err) {
-    log("warn", "Sampling tiebreak failed", { error: err instanceof Error ? err.message : String(err) });
-    return null;
-  }
-}
-function extractText(content) {
+function extractText2(content) {
   if (!content) return "";
   if (Array.isArray(content)) {
     return content.map((c) => c && typeof c === "object" && "type" in c && c.type === "text" && "text" in c ? String(c.text) : "").filter(Boolean).join("\n");
@@ -7325,6 +8115,109 @@ function buildCandidates(topRanked, serversByNamespace, toolsByNamespace) {
   }
   return out;
 }
+function parseRouteEffort(raw) {
+  if (raw === void 0) return "auto";
+  switch (raw.trim().toLowerCase()) {
+    case "off":
+      return "off";
+    case "aggressive":
+      return "aggressive";
+    default:
+      return "auto";
+  }
+}
+function computeAmbiguity(ranked, k = 3) {
+  if (ranked.length < 2) return 0;
+  const top = ranked[0];
+  if (!top || top.score <= 0) return 0;
+  const topK = ranked.slice(0, Math.max(2, k));
+  const second = topK[1];
+  const secondScore = second ? second.score : 0;
+  const inverseMargin = Math.min(1, Math.max(0, secondScore / top.score));
+  const weights = topK.map((c) => Math.max(0, c.score));
+  const total = weights.reduce((a, b) => a + b, 0);
+  let entropy = 0;
+  if (total > 0 && topK.length >= 2) {
+    let h = 0;
+    for (const w of weights) {
+      if (w <= 0) continue;
+      const p = w / total;
+      h -= p * Math.log(p);
+    }
+    const maxH = Math.log(topK.length);
+    entropy = maxH > 0 ? h / maxH : 0;
+  }
+  return Math.max(inverseMargin, entropy);
+}
+function shouldSample(ranked, effort) {
+  if (effort === "off") return false;
+  if (effort === "auto") return shouldTiebreak(ranked);
+  return computeAmbiguity(ranked) >= AGGRESSIVE_AMBIGUITY_THRESHOLD;
+}
+function sampleCountForEffort(effort) {
+  switch (effort) {
+    case "off":
+      return 0;
+    case "aggressive":
+      return 3;
+    default:
+      return 1;
+  }
+}
+async function bestOfNViaSampling(server, intent, candidates, n) {
+  const caps = server.getClientCapabilities();
+  if (!caps?.sampling) return null;
+  if (candidates.length < 2) return null;
+  const samples = Math.min(MAX_SAMPLES, Math.max(1, Math.floor(n)));
+  const prompt = buildTiebreakPrompt(intent, candidates);
+  const sampleOnce = async () => {
+    try {
+      const result = await server.createMessage({
+        messages: [{ role: "user", content: { type: "text", text: prompt } }],
+        maxTokens: SAMPLING_MAX_TOKENS,
+        includeContext: "none"
+      });
+      const text = result && typeof result === "object" && "content" in result && result.content ? extractText2(result.content) : "";
+      if (!text) return null;
+      return parseTiebreakResponse(text, candidates);
+    } catch (err) {
+      log("warn", "Best-of-N sample failed", { error: err instanceof Error ? err.message : String(err) });
+      return null;
+    }
+  };
+  const aggregate2 = (async () => {
+    const results = await Promise.all(Array.from({ length: samples }, () => sampleOnce()));
+    const votes = /* @__PURE__ */ new Map();
+    for (const ns of results) {
+      if (!ns) continue;
+      votes.set(ns, (votes.get(ns) ?? 0) + 1);
+    }
+    if (votes.size === 0) return null;
+    const order = /* @__PURE__ */ new Map();
+    candidates.forEach((c, i) => order.set(c.namespace, i));
+    let winner = null;
+    let bestVotes = -1;
+    let bestRank = Number.POSITIVE_INFINITY;
+    for (const [ns, count] of votes) {
+      const rank = order.get(ns) ?? Number.POSITIVE_INFINITY;
+      if (count > bestVotes || count === bestVotes && rank < bestRank) {
+        winner = ns;
+        bestVotes = count;
+        bestRank = rank;
+      }
+    }
+    return winner;
+  })();
+  let timer;
+  const timeout = new Promise((resolve7) => {
+    timer = setTimeout(() => resolve7(null), SAMPLING_TIMEOUT_MS);
+  });
+  try {
+    return await Promise.race([aggregate2, timeout]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
 
 // src/server-cap.ts
 var DEFAULT_SERVER_CAP = 6;
@@ -7366,7 +8259,7 @@ import { spawn as spawn5 } from "child_process";
 import { createHash as createHash3 } from "crypto";
 import { createWriteStream } from "fs";
 import fs from "fs/promises";
-import path2 from "path";
+import path4 from "path";
 import { pipeline } from "stream/promises";
 import { request as request9 } from "undici";
 var UV_VERSION = "0.11.7";
@@ -7406,18 +8299,21 @@ async function exists2(p) {
   }
 }
 async function onPath(cmd) {
-  return new Promise((resolve5) => {
+  return new Promise((resolve7) => {
     let settled = false;
     const settle = (v) => {
       if (settled) return;
       settled = true;
-      resolve5(v);
+      resolve7(v);
     };
     let child;
     try {
       child = spawn5(cmd, ["--version"], {
         stdio: "ignore",
-        shell: false,
+        // Windows needs a shell for PATHEXT shim resolution (.cmd/.exe)
+        // so `uv --version` finds uv.cmd without an ENOENT false-negative.
+        // Mirrors the PROBES spawn options in runtime-detect.ts.
+        shell: process.platform === "win32",
         windowsHide: process.platform === "win32"
       });
     } catch {
@@ -7442,10 +8338,24 @@ async function onPath(cmd) {
     });
   });
 }
+var UV_FETCH_TIMEOUT_MS = 3e4;
 async function fetchWithRedirects(url, maxHops = 5) {
   let current = url;
   for (let i = 0; i < maxHops; i++) {
-    const res = await request9(current, { method: "GET" });
+    let res;
+    try {
+      res = await request9(current, {
+        method: "GET",
+        headersTimeout: UV_FETCH_TIMEOUT_MS,
+        bodyTimeout: UV_FETCH_TIMEOUT_MS
+      });
+    } catch (e) {
+      const code = e.code;
+      if (code === "UND_ERR_HEADERS_TIMEOUT" || code === "UND_ERR_BODY_TIMEOUT") {
+        throw new Error(`uv download timed out after ${UV_FETCH_TIMEOUT_MS}ms (${current})`);
+      }
+      throw e;
+    }
     if (res.statusCode >= 300 && res.statusCode < 400) {
       const loc = res.headers.location;
       if (!loc) throw new Error(`Redirect without Location header from ${current}`);
@@ -7457,13 +8367,29 @@ async function fetchWithRedirects(url, maxHops = 5) {
       await res.body.dump();
       throw new Error(`GET ${current} failed: HTTP ${res.statusCode}`);
     }
-    return Buffer.from(await res.body.arrayBuffer());
+    try {
+      return Buffer.from(await res.body.arrayBuffer());
+    } catch (e) {
+      const code = e.code;
+      if (code === "UND_ERR_HEADERS_TIMEOUT" || code === "UND_ERR_BODY_TIMEOUT") {
+        throw new Error(`uv download timed out after ${UV_FETCH_TIMEOUT_MS}ms (${current})`);
+      }
+      throw e;
+    }
   }
   throw new Error(`Too many redirects starting at ${url}`);
 }
 async function extractArchive(archivePath, destDir) {
   await fs.mkdir(destDir, { recursive: true });
   if (process.platform === "win32") {
+    for (const [label, p] of [
+      ["archivePath", archivePath],
+      ["destDir", destDir]
+    ]) {
+      if (/['\r\n]/.test(p)) {
+        throw new Error(`Refusing to extract uv archive: ${label} contains a quote or newline (${JSON.stringify(p)})`);
+      }
+    }
     await runCommand("powershell.exe", [
       "-NoProfile",
       "-NonInteractive",
@@ -7475,7 +8401,7 @@ async function extractArchive(archivePath, destDir) {
   }
 }
 function runCommand(cmd, args) {
-  return new Promise((resolve5, reject) => {
+  return new Promise((resolve7, reject) => {
     const child = spawn5(cmd, args, {
       stdio: ["ignore", "pipe", "pipe"],
       shell: false,
@@ -7487,7 +8413,7 @@ function runCommand(cmd, args) {
     });
     child.on("error", reject);
     child.on("close", (code) => {
-      if (code === 0) resolve5();
+      if (code === 0) resolve7();
       else reject(new Error(`${cmd} exited ${code}: ${stderr.trim()}`));
     });
   });
@@ -7495,7 +8421,7 @@ function runCommand(cmd, args) {
 async function findBinary(root, name) {
   const entries = await fs.readdir(root, { withFileTypes: true });
   for (const e of entries) {
-    const full = path2.join(root, e.name);
+    const full = path4.join(root, e.name);
     if (e.isFile() && e.name === name) return full;
     if (e.isDirectory()) {
       const found = await findBinary(full, name);
@@ -7506,7 +8432,12 @@ async function findBinary(root, name) {
 }
 var pending = null;
 function ensureUv() {
-  pending ??= resolveUv();
+  if (!pending) {
+    pending = resolveUv().catch((err) => {
+      pending = null;
+      return Promise.reject(err);
+    });
+  }
   return pending;
 }
 async function resolveUv() {
@@ -7517,8 +8448,8 @@ async function resolveUv() {
       `No prebuilt uv binary for ${process.platform}/${process.arch}. Install uv manually: https://docs.astral.sh/uv/`
     );
   }
-  const installDir = path2.join(cacheDir(), "uv", UV_VERSION);
-  const finalBin = path2.join(installDir, binName());
+  const installDir = path4.join(cacheDir(), "uv", UV_VERSION);
+  const finalBin = path4.join(installDir, binName());
   if (await exists2(finalBin)) return finalBin;
   await fs.mkdir(installDir, { recursive: true });
   log("info", "Bootstrapping uv", { version: UV_VERSION, target, cache: installDir });
@@ -7531,20 +8462,24 @@ async function resolveUv() {
   if (!expected || expected.toLowerCase() !== actual.toLowerCase()) {
     throw new Error(`uv archive checksum mismatch (expected ${expected}, got ${actual})`);
   }
-  const archivePath = path2.join(installDir, archiveName);
+  const archivePath = path4.join(installDir, archiveName);
   await pipeline(async function* () {
     yield archiveBuf;
   }, createWriteStream(archivePath));
-  const extractDir = path2.join(installDir, "extract");
-  await fs.rm(extractDir, { recursive: true, force: true });
-  await extractArchive(archivePath, extractDir);
-  const extracted = await findBinary(extractDir, binName());
-  if (!extracted) throw new Error(`uv binary not found inside ${archiveName}`);
-  await fs.rename(extracted, finalBin);
-  await fs.chmod(finalBin, 493).catch(() => {
-  });
-  await fs.rm(extractDir, { recursive: true, force: true });
-  await fs.rm(archivePath, { force: true });
+  const extractDir = path4.join(installDir, `extract-${process.pid}-${Date.now()}`);
+  try {
+    await extractArchive(archivePath, extractDir);
+    const extracted = await findBinary(extractDir, binName());
+    if (!extracted) throw new Error(`uv binary not found inside ${archiveName}`);
+    await fs.rename(extracted, finalBin);
+    await fs.chmod(finalBin, 493).catch(() => {
+    });
+  } finally {
+    await fs.rm(extractDir, { recursive: true, force: true }).catch(() => {
+    });
+    await fs.rm(archivePath, { force: true }).catch(() => {
+    });
+  }
   log("info", "uv bootstrap complete", { bin: finalBin });
   return finalBin;
 }
@@ -7622,7 +8557,7 @@ function categorizeSpawnError(err) {
 }
 async function connectToUpstream(config, onDisconnect, onListChanged) {
   const client = new Client(
-    { name: "yaw-mcp", version: true ? "0.60.6" : "dev" },
+    { name: "yaw-mcp", version: true ? "0.62.0" : "dev" },
     { capabilities: {} }
   );
   let transport;
@@ -7631,7 +8566,11 @@ async function connectToUpstream(config, onDisconnect, onListChanged) {
     if (!config.command) {
       throw new Error("command is required for local servers");
     }
-    const { YAW_MCP_TOKEN: _excluded, ...parentEnv } = process.env;
+    const {
+      YAW_MCP_TOKEN: _excludedToken,
+      YAW_MCP_VAULT_PASSPHRASE: _excludedVaultPassphrase,
+      ...parentEnv
+    } = process.env;
     const resolved = await resolveUvSpawn(config.command, config.args ?? []);
     const serverEnv = await resolveServerEnv(config.env ?? {});
     const stdioTransport = new StdioClientTransport({
@@ -7664,7 +8603,10 @@ async function connectToUpstream(config, onDisconnect, onListChanged) {
     }, CONNECT_TIMEOUT);
   });
   try {
-    await Promise.race([client.connect(transport), timeoutPromise]);
+    const connectP = client.connect(transport);
+    connectP.catch(() => {
+    });
+    await Promise.race([connectP, timeoutPromise]);
     clearTimeout(timer);
   } catch (err) {
     clearTimeout(timer);
@@ -7830,7 +8772,18 @@ async function fetchPromptsFromUpstream(client, namespace) {
   }
 }
 async function fetchToolsFromUpstream(client, namespace) {
-  const result = await client.listTools({}, { timeout: LIST_TIMEOUT });
+  let result;
+  try {
+    result = await client.listTools({}, { timeout: LIST_TIMEOUT });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new ActivationError(
+      `"${namespace}" returned an error on tools/list: ${message}`,
+      "protocol_error",
+      void 0,
+      err
+    );
+  }
   const raw = result.tools ?? [];
   if (raw.length > MAX_TOOLS_PER_SERVER) {
     log("warn", "Upstream returned more tools than cap; truncating", {
@@ -7860,7 +8813,7 @@ function resolvePollIntervalMs() {
   }
   return seconds * 1e3;
 }
-function isPersistenceDisabled() {
+function isPersistenceDisabled2() {
   const raw = process.env.YAW_MCP_DISABLE_PERSISTENCE;
   if (raw === void 0 || raw === "") return false;
   return raw === "1" || raw.toLowerCase() === "true";
@@ -7931,7 +8884,7 @@ var ConnectServer = class _ConnectServer {
     this.apiUrl = apiUrl5;
     this.token = token5;
     this.server = new Server(
-      { name: "yaw-mcp", version: true ? "0.60.6" : "dev" },
+      { name: "yaw-mcp", version: true ? "0.62.0" : "dev" },
       {
         capabilities: {
           tools: { listChanged: true },
@@ -8006,6 +8959,17 @@ var ConnectServer = class _ConnectServer {
   // same promise as the first; the entry is cleared when the promise
   // settles (success or failure).
   activationInflight = /* @__PURE__ */ new Map();
+  // Tracks namespaces whose current activationInflight was initiated by
+  // prewarmDormantServers. An explicit mcp_connect_activate clears the
+  // namespace from this set, which prevents prewarm from disconnecting a
+  // connection the user just claimed. Without this, the prewarm race is:
+  //   1. prewarm activateOne("foo") -> inflight P1
+  //   2. user activateOne("foo") -> joins P1 (same promise)
+  //   3. P1 resolves ok=true for both callers
+  //   4. prewarm disconnects "foo" — user's next tool call fails
+  // With this set: prewarm only disconnects when the namespace was NOT
+  // claimed by an explicit activate while P1 was in flight.
+  prewarmNamespaces = /* @__PURE__ */ new Set();
   // Usage learning — nudges dispatch toward namespaces that have been
   // genuinely useful. Counts persist across yaw-mcp restarts via state.json
   // (see persistence.ts). YAW_MCP_DISABLE_PERSISTENCE=1 makes it session
@@ -8016,6 +8980,16 @@ var ConnectServer = class _ConnectServer {
   // "packs". Observation-only; never activates anything. Meta-tool calls
   // are deliberately excluded because they aren't user workflow.
   packDetector = new PackDetector();
+  // Session-scoped re-dispatch tracking — watches for the model abandoning
+  // one server and re-routing a similar intent to another, which is
+  // evidence the first route was wrong. Feeds a negative learning signal
+  // (LearningStore.recordMiss). Not persisted: a re-dispatch window that
+  // spans a restart is meaningless. See redispatch.ts.
+  redispatch = new RedispatchTracker();
+  // Last dispatch intent per namespace (session-scoped, not persisted). Lets
+  // the optional reward grader (reward-grader.ts) judge a tool call against the
+  // goal the server was routed for. Bounded by the number of namespaces.
+  lastIntentByNamespace = /* @__PURE__ */ new Map();
   // Short-TTL dedup cache for discover output. Agents often call
   // discover twice in quick succession (e.g. once to list, again after
   // a failed activate) — the second call returns the same text if
@@ -8166,7 +9140,7 @@ var ConnectServer = class _ConnectServer {
     });
   }
   async start() {
-    if (isPersistenceDisabled()) {
+    if (isPersistenceDisabled2()) {
       log("info", "Cross-session persistence disabled via YAW_MCP_DISABLE_PERSISTENCE");
     } else {
       const persisted = await loadState();
@@ -8203,6 +9177,15 @@ var ConnectServer = class _ConnectServer {
       });
       for (const w of result.warnings) log("warn", "bundles.json warning", { warning: w });
       this.config = result.config ?? { servers: [], configVersion: "" };
+      const seenNs = /* @__PURE__ */ new Set();
+      this.config.servers = this.config.servers.filter((s) => {
+        if (seenNs.has(s.namespace)) {
+          log("warn", "Duplicate namespace in bundles.json, skipping", { namespace: s.namespace });
+          return false;
+        }
+        seenNs.add(s.namespace);
+        return true;
+      });
       this.configVersion = this.config.configVersion;
       log("info", "Local mode: loaded bundles", {
         path: result.path,
@@ -8314,8 +9297,21 @@ var ConnectServer = class _ConnectServer {
       await Promise.all(
         batch.map(async (server) => {
           try {
-            const result = await this.activateOne(server.namespace);
+            const result = await this.activateOne(
+              server.namespace,
+              void 0,
+              /* fromPrewarm */
+              true
+            );
             if (!result.ok) return;
+            if (!this.prewarmNamespaces.has(server.namespace)) {
+              log("info", "Pre-warm skipping disconnect \u2014 namespace claimed by explicit activate", {
+                namespace: server.namespace
+              });
+              anyPopulated = true;
+              return;
+            }
+            this.prewarmNamespaces.delete(server.namespace);
             const conn = this.connections.get(server.namespace);
             if (conn) {
               await disconnectFromUpstream(conn).catch(() => {
@@ -8361,7 +9357,7 @@ var ConnectServer = class _ConnectServer {
     }
     return result;
   }
-  async handleToolCall(name, args, extra) {
+  async handleToolCall(name, args, extra, opts) {
     const progress = createProgressReporter(extra);
     if (name === META_TOOLS.discover.name) {
       recordConnectEvent({ namespace: null, toolName: null, action: "discover", latencyMs: null, success: true });
@@ -8370,8 +9366,9 @@ var ConnectServer = class _ConnectServer {
     if (name === META_TOOLS.dispatch.name) {
       const intent = typeof args.intent === "string" ? args.intent : "";
       const budget = typeof args.budget === "number" && Number.isFinite(args.budget) ? args.budget : 1;
+      const routeEffort = typeof args.routeEffort === "string" ? args.routeEffort : void 0;
       recordConnectEvent({ namespace: null, toolName: null, action: "activate", latencyMs: null, success: true });
-      return this.attachGuideNudge(await this.handleDispatch(intent, budget, progress));
+      return this.attachGuideNudge(await this.handleDispatch(intent, budget, progress, routeEffort));
     }
     if (name === META_TOOLS.activate.name) {
       const namespaces = resolveNamespaces(args);
@@ -8496,7 +9493,7 @@ var ConnectServer = class _ConnectServer {
           content: [
             {
               type: "text",
-              text: `Tool "${name}" is no longer available after loading "${activation.serverId ? activation.serverId : name}" \u2014 the upstream's tool set changed. Call mcp_connect_discover to see current tools.`
+              text: `Tool "${name}" is no longer available after loading "${activation.serverId ? activation.serverId : name}" \u2014 the upstream's tool set changed. Call mcp_connect_discover to list the current tools for that namespace.`
             }
           ],
           isError: true
@@ -8504,9 +9501,10 @@ var ConnectServer = class _ConnectServer {
       }
     }
     if (route) {
-      const conn = this.connections.get(route.namespace);
+      const ns = route.namespace;
+      const conn = this.connections.get(ns);
       if (conn && conn.status === "error") {
-        const serverConfig = this.config?.servers.find((s) => s.namespace === route.namespace);
+        const serverConfig = this.config?.servers.find((s) => s.namespace === ns);
         if (serverConfig) {
           let reconnected = false;
           let lastErr;
@@ -8521,17 +9519,30 @@ var ConnectServer = class _ConnectServer {
                 this.onUpstreamDisconnect,
                 this.onUpstreamListChanged
               );
-              this.connections.set(route.namespace, newConn);
+              this.connections.set(ns, newConn);
               this.rebuildRoutes();
               await this.notifyAllListsChanged();
-              log("info", "Auto-reconnected to upstream", { namespace: route.namespace });
+              log("info", "Auto-reconnected to upstream", { namespace: ns });
               reconnected = true;
+              routes = this.toolRoutes;
+              route = routes.get(name);
+              if (!route || route.deferred) {
+                return {
+                  content: [
+                    {
+                      type: "text",
+                      text: `Tool "${name}" is no longer available after reconnecting "${serverConfig.namespace}" \u2014 the upstream's tool set changed. Call mcp_connect_discover to list the current tools for that namespace.`
+                    }
+                  ],
+                  isError: true
+                };
+              }
               break;
             } catch (err) {
               lastErr = err;
               if (attempt < RECONNECT_ATTEMPTS - 1) {
                 log("warn", "Auto-reconnect attempt failed, retrying", {
-                  namespace: route.namespace,
+                  namespace: ns,
                   error: err instanceof Error ? err.message : String(err)
                 });
               }
@@ -8540,12 +9551,12 @@ var ConnectServer = class _ConnectServer {
           if (!reconnected) {
             conn.status = "error";
             const lastErrMsg = lastErr instanceof Error ? lastErr.message : String(lastErr);
-            log("error", "Auto-reconnect failed", { namespace: route.namespace, error: lastErrMsg });
+            log("error", "Auto-reconnect failed", { namespace: ns, error: lastErrMsg });
             return {
               content: [
                 {
                   type: "text",
-                  text: `Server "${route.namespace}" disconnected and auto-reconnect failed: ${lastErrMsg}. Use mcp_connect_activate with server "${route.namespace}" to reload it manually.`
+                  text: `Server "${ns}" disconnected and auto-reconnect failed: ${lastErrMsg}. Use mcp_connect_activate with server "${ns}" to reload it manually.`
                 }
               ],
               isError: true
@@ -8621,9 +9632,19 @@ var ConnectServer = class _ConnectServer {
         } catch {
         }
       }
-      this.learning.recordDispatch(route.namespace);
-      if (!result.isError) this.learning.recordSuccess(route.namespace);
-      this.scheduleStateSave();
+      if (!opts?.deferLearning) {
+        const reward = computeOutcomeReward(result);
+        this.learning.recordOutcome(route.namespace, reward);
+        this.scheduleStateSave();
+        if (isRewardGraderEnabled() && isUncertainReward(reward)) {
+          void this.refineRewardInBackground(route.namespace, reward, {
+            intent: this.lastIntentByNamespace.get(route.namespace),
+            toolName: route.originalName,
+            resultText: firstResultText(result)
+          });
+        }
+        this.redispatch.markReply(route.namespace, !result.isError);
+      }
       if (!result.isError) {
         this.packDetector.recordCall(route.namespace, route.originalName, Date.now());
       }
@@ -8952,15 +9973,28 @@ ${activeCount} loaded in this session, ${totalTools} tools in context${tokenSumm
   // child process; the second set() would win and the first would leak
   // until its transport noticed. See activationInflight.
   //
+  // `fromPrewarm` marks the inflight as prewarm-initiated so that
+  // prewarmDormantServers can safely disconnect when it is the sole
+  // caller, but skip the disconnect when an explicit activate has also
+  // joined the inflight promise. An explicit call (fromPrewarm=false)
+  // removes the namespace from prewarmNamespaces so prewarm's teardown
+  // code sees it as "claimed" and leaves the connection alive.
+  //
   // Returns:
   //   { ok: true, message } — already connected or newly connected
   //   { ok: false, message, isChanged: false } — failed or not in config
-  activateOne(namespace, progress) {
+  activateOne(namespace, progress, fromPrewarm = false) {
+    if (!fromPrewarm) {
+      this.prewarmNamespaces.delete(namespace);
+    }
     const inflight = this.activationInflight.get(namespace);
     if (inflight) {
       progress?.(`"${namespace}" load already in flight \u2014 awaiting existing attempt`);
       return inflight;
     }
+    if (fromPrewarm) {
+      this.prewarmNamespaces.add(namespace);
+    }
     const promise = this.runActivateOne(namespace, progress).finally(() => {
       if (this.activationInflight.get(namespace) === promise) {
         this.activationInflight.delete(namespace);
@@ -9010,7 +10044,12 @@ ${activeCount} loaded in this session, ${totalTools} tools in context${tokenSumm
     }
     const capDecision = evaluateServerCap(namespace, loadedSlots, this.serverCap);
     if (!capDecision.allow) {
-      return { ok: false, isChanged: false, message: capDecision.message ?? "Concurrent server cap reached." };
+      return {
+        ok: false,
+        isChanged: false,
+        capped: true,
+        message: capDecision.message ?? "Concurrent server cap reached."
+      };
     }
     const elicited = this.elicitedEnv.get(namespace);
     const effectiveConfig = elicited ? { ...serverConfig, env: { ...serverConfig.env, ...elicited } } : serverConfig;
@@ -9160,6 +10199,7 @@ ${activeCount} loaded in this session, ${totalTools} tools in context${tokenSumm
     const results = [];
     let anyChanged = false;
     let anyError = false;
+    let anyCapped = false;
     const minCompliance = resolveMinCompliance();
     const total = namespaces.length;
     let i = 0;
@@ -9179,7 +10219,10 @@ ${activeCount} loaded in this session, ${totalTools} tools in context${tokenSumm
       const r = await this.activateOne(namespace, progress);
       results.push(r.message);
       if (r.isChanged) anyChanged = true;
-      if (!r.ok) anyError = true;
+      if (!r.ok) {
+        if (r.capped) anyCapped = true;
+        else anyError = true;
+      }
     }
     if (anyChanged) {
       this.rebuildRoutes();
@@ -9189,7 +10232,7 @@ ${activeCount} loaded in this session, ${totalTools} tools in context${tokenSumm
     }
     return {
       content: [{ type: "text", text: results.join("\n") }],
-      isError: anyError && !anyChanged ? true : void 0
+      isError: anyError || anyCapped && !anyChanged ? true : void 0
     };
   }
   // Smart-routing meta-tool. The LLM describes the task in plain English
@@ -9197,7 +10240,33 @@ ${activeCount} loaded in this session, ${totalTools} tools in context${tokenSumm
   // with BM25 and activates the top N, then lets the LLM call the now-
   // exposed tools normally. Default budget is 1 because over-activating
   // pollutes the tool list in the LLM's context with noise.
-  async handleDispatch(intent, budget, progress) {
+  // Is A -> B a designed multi-server flow rather than a routing miss? True
+  // when both namespaces co-occur in a curated bundle or a detected usage
+  // pack — those A-then-B sequences are intentional, so re-dispatch from A
+  // to B must NOT penalize A. Used as detectMiss's exclusion predicate.
+  // Background refinement of a just-recorded heuristic reward via the optional
+  // LLM grader. Fire-and-forget: the tool result has already returned. If the
+  // grader returns a verdict different from the heuristic, revise the credit by
+  // the delta (recordOutcome already counted the dispatch). Never throws.
+  async refineRewardInBackground(namespace, heuristic, ctx) {
+    try {
+      const graded = await gradeOutcomeViaSampling(this.server, ctx);
+      if (graded === null || graded === heuristic) return;
+      this.learning.adjustSucceeded(namespace, graded - heuristic);
+      this.scheduleStateSave();
+    } catch {
+    }
+  }
+  isLegitChain(a, b) {
+    for (const bundle of CURATED_BUNDLES) {
+      if (bundle.namespaces.includes(a) && bundle.namespaces.includes(b)) return true;
+    }
+    for (const pack of this.packDetector.detectChains()) {
+      if (pack.namespaces.includes(a) && pack.namespaces.includes(b)) return true;
+    }
+    return false;
+  }
+  async handleDispatch(intent, budget, progress, routeEffortOverride) {
     const trimmed = intent?.trim?.() ?? "";
     if (trimmed.length === 0) {
       return {
@@ -9241,11 +10310,13 @@ ${activeCount} loaded in this session, ${totalTools} tools in context${tokenSumm
         isError: true
       };
     }
-    if (budget === 1 && shouldTiebreak(ranked)) {
+    const effort = parseRouteEffort(routeEffortOverride ?? process.env.YAW_MCP_ROUTE_EFFORT);
+    if (budget === 1 && shouldSample(ranked, effort)) {
       progress?.("Top candidates close \u2014 asking LLM to pick\u2026");
       const serversByNamespace = new Map(activeServers.map((s) => [s.namespace, s]));
       const candidates = buildCandidates(ranked.slice(0, 3), serversByNamespace, this.toolCache);
-      const picked = await tiebreakViaSampling(this.server, trimmed, candidates);
+      const samples = sampleCountForEffort(effort);
+      const picked = await bestOfNViaSampling(this.server, trimmed, candidates, samples);
       if (picked) {
         const winner = ranked.find((r) => r.namespace === picked);
         if (winner) {
@@ -9258,9 +10329,31 @@ ${activeCount} loaded in this session, ${totalTools} tools in context${tokenSumm
     }
     const safeBudget = Math.max(1, Math.min(10, Math.floor(budget)));
     const winners = ranked.slice(0, safeBudget);
+    const primary = winners[0]?.namespace;
+    if (primary) {
+      for (const w of winners) this.lastIntentByNamespace.set(w.namespace, trimmed);
+      const intentTokens = tokenize(trimmed);
+      const now = Date.now();
+      const miss = this.redispatch.detectMiss(primary, intentTokens, now, (a, b) => this.isLegitChain(a, b));
+      if (miss) {
+        this.learning.recordMiss(miss.loser);
+        this.scheduleStateSave();
+      }
+      this.redispatch.push(primary, intentTokens, now);
+      if (isFoundryEnabled()) {
+        const redacted = redactIntent(trimmed);
+        void appendFoundryTrace({
+          tokens: redacted.tokens,
+          redactedCount: redacted.redactedCount,
+          candidates: ranked.slice(0, 5).map((r) => ({ ns: r.namespace, score: r.score })),
+          chosen: primary
+        });
+      }
+    }
     const results = [];
     let anyChanged = false;
     let anyError = false;
+    let anyCapped = false;
     let i = 0;
     for (const winner of winners) {
       i += 1;
@@ -9268,7 +10361,10 @@ ${activeCount} loaded in this session, ${totalTools} tools in context${tokenSumm
       const r = await this.activateOne(winner.namespace, progress);
       results.push(`${winner.namespace} (score ${winner.score.toFixed(2)}): ${r.message}`);
       if (r.isChanged) anyChanged = true;
-      if (!r.ok) anyError = true;
+      if (!r.ok) {
+        if (r.capped) anyCapped = true;
+        else anyError = true;
+      }
     }
     if (anyChanged) {
       this.rebuildRoutes();
@@ -9278,7 +10374,7 @@ ${activeCount} loaded in this session, ${totalTools} tools in context${tokenSumm
 `;
     return {
       content: [{ type: "text", text: header + results.join("\n") }],
-      isError: anyError && !anyChanged ? true : void 0
+      isError: anyError || anyCapped && !anyChanged ? true : void 0
     };
   }
   async handleDeactivate(namespaces) {
@@ -9309,8 +10405,7 @@ ${activeCount} loaded in this session, ${totalTools} tools in context${tokenSumm
       await this.notifyAllListsChanged();
     }
     return {
-      content: [{ type: "text", text: results.join("\n") }],
-      isError: !anyChanged ? true : void 0
+      content: [{ type: "text", text: results.join("\n") }]
     };
   }
   async trackUsageAndAutoDeactivate(calledNamespace) {
@@ -9400,7 +10495,7 @@ ${activeCount} loaded in this session, ${totalTools} tools in context${tokenSumm
         continue;
       }
       const oldConfig = connection.config;
-      if (oldConfig.command !== newServerConfig.command || !argsEqual(oldConfig.args, newServerConfig.args) || oldConfig.url !== newServerConfig.url || !envEqual(oldConfig.env, newServerConfig.env)) {
+      if (oldConfig.command !== newServerConfig.command || !argsEqual(oldConfig.args, newServerConfig.args) || oldConfig.url !== newServerConfig.url || !envEqual(oldConfig.env, newServerConfig.env) || oldConfig.type !== newServerConfig.type || oldConfig.connectTimeoutMs !== newServerConfig.connectTimeoutMs) {
         log("info", "Server config changed, deactivating stale connection", { namespace });
         await disconnectFromUpstream(connection);
         this.connections.delete(namespace);
@@ -9462,7 +10557,7 @@ ${activeCount} loaded in this session, ${totalTools} tools in context${tokenSumm
     }
     const ALLOWED_FILENAMES = ["claude_desktop_config.json", "mcp.json", "settings.json", "mcp_config.json"];
     try {
-      const resolved = filepath.startsWith("~/") || filepath.startsWith("~\\") ? resolve4(homedir13(), filepath.slice(2)) : resolve4(filepath);
+      const resolved = filepath.startsWith("~/") || filepath.startsWith("~\\") ? resolve6(homedir15(), filepath.slice(2)) : resolve6(filepath);
       const resolvedBasename = resolved.split(/[/\\]/).pop() || "";
       if (!ALLOWED_FILENAMES.includes(resolvedBasename)) {
         return {
@@ -9477,9 +10572,9 @@ ${activeCount} loaded in this session, ${totalTools} tools in context${tokenSumm
       }
       const isUnder = (base, p) => {
         const rel = relative(base, p);
-        return rel === "" || !rel.startsWith("..") && !isAbsolute(rel);
+        return rel === "" || !rel.startsWith("..") && !isAbsolute2(rel);
       };
-      if (!isUnder(homedir13(), resolved) && !isUnder(process.cwd(), resolved)) {
+      if (!isUnder(homedir15(), resolved) && !isUnder(process.cwd(), resolved)) {
         return {
           content: [
             { type: "text", text: "Import path must be under your home directory or the current working directory." }
@@ -9566,7 +10661,12 @@ Use mcp_connect_discover to see imported servers.`
         ]
       };
     } catch (err) {
-      return { content: [{ type: "text", text: `Import error: ${err.message}` }], isError: true };
+      const { code, text } = this.mapNetworkError(err, "Import");
+      log("warn", "handleImport error", {
+        error: err instanceof Error ? err.message : String(err),
+        code
+      });
+      return { content: [{ type: "text", text }], isError: true };
     }
   }
   // Install a new MCP server on the user's Yaw MCP account. Validates
@@ -9657,15 +10757,7 @@ Use mcp_connect_discover to see imported servers.`
         ]
       };
     } catch (err) {
-      const code = typeof err === "object" && err !== null ? err.code || err.cause?.code : void 0;
-      let text;
-      if (code === "UND_ERR_HEADERS_TIMEOUT" || code === "UND_ERR_BODY_TIMEOUT" || code === "UND_ERR_CONNECT_TIMEOUT") {
-        text = "Install timed out talking to yaw.sh/mcp. Retry in a moment.";
-      } else if (code === "ECONNREFUSED" || code === "ENOTFOUND" || code === "EAI_AGAIN" || code === "UND_ERR_SOCKET") {
-        text = "Couldn't reach yaw.sh/mcp (network unreachable or DNS failure). Check your connection and retry.";
-      } else {
-        text = "Install failed unexpectedly. Check yaw-mcp logs on this machine for the underlying error.";
-      }
+      const { code, text } = this.mapNetworkError(err, "Install");
       log("warn", "handleInstall error", {
         error: err instanceof Error ? err.message : String(err),
         code
@@ -9673,6 +10765,23 @@ Use mcp_connect_discover to see imported servers.`
       return { content: [{ type: "text", text }], isError: true };
     }
   }
+  // Map a raw undici/network error to a user-facing string instead of
+  // leaking `err.message` (e.g. "getaddrinfo ENOTFOUND yaw.sh") verbatim to
+  // the model. Returns the extracted node error code (for ops logging) and a
+  // clean message keyed by the failing operation verb ("Install"/"Import").
+  // Callers keep the raw error in the log; the LLM/user only sees `text`.
+  mapNetworkError(err, op) {
+    const code = typeof err === "object" && err !== null ? err.code || err.cause?.code : void 0;
+    let text;
+    if (code === "UND_ERR_HEADERS_TIMEOUT" || code === "UND_ERR_BODY_TIMEOUT" || code === "UND_ERR_CONNECT_TIMEOUT") {
+      text = `${op} timed out talking to yaw.sh/mcp. Retry in a moment.`;
+    } else if (code === "ECONNREFUSED" || code === "ENOTFOUND" || code === "EAI_AGAIN" || code === "UND_ERR_SOCKET") {
+      text = `Couldn't reach yaw.sh/mcp (network unreachable or DNS failure). Check your connection and retry.`;
+    } else {
+      text = `${op} failed unexpectedly. Check yaw-mcp logs on this machine for the underlying error.`;
+    }
+    return { code, text };
+  }
   // Signature-on-demand: return one tool's full input schema without
   // persistently activating its server. When the server is already
   // loaded we read from the in-memory connection. When it isn't, we
@@ -9861,7 +10970,7 @@ To load the top pack in one step, call \`mcp_connect_activate\` with namespaces=
 `];
       for (const bundle of CURATED_BUNDLES) {
         lines2.push(`  ${bundle.id} \u2014 ${bundle.description}`);
-        lines2.push(`    namespaces: ${JSON.stringify(bundle.namespaces)}`);
+        lines2.push(`    servers: ${JSON.stringify(bundle.namespaces)}`);
         lines2.push(`    activate: ${bundleActivateHint(bundle)}`);
       }
       lines2.push("");
@@ -9887,7 +10996,7 @@ To load the top pack in one step, call \`mcp_connect_activate\` with namespaces=
       lines.push("Bundles ready to activate now:");
       for (const bundle of ready) {
         lines.push(`  ${bundle.id} \u2014 ${bundle.description}`);
-        lines.push(`    namespaces: ${JSON.stringify(bundle.namespaces)}`);
+        lines.push(`    servers: ${JSON.stringify(bundle.namespaces)}`);
         lines.push(`    activate: ${bundleActivateHint(bundle)}`);
       }
     }
@@ -9903,6 +11012,30 @@ To load the top pack in one step, call \`mcp_connect_activate\` with namespaces=
     }
     return { content: [{ type: "text", text: lines.join("\n") }] };
   }
+  // Extract the semantic payload from a successful MCP tool result for use
+  // as a step binding in exec pipelines. The MCP wire format wraps every
+  // result in `{ content: [{type, text}, ...], isError? }`, but the exec
+  // tool description promises `$ref` targets that behave like the tool's
+  // actual output -- e.g. `a = gh_list_prs(); b = gh_get_pr(a[0].number)`.
+  //
+  // Rules, in order:
+  //   1. Single text item whose text is valid JSON -> the parsed JSON value.
+  //   2. Single text item (non-JSON) -> the raw text string.
+  //   3. Everything else (multi-item, non-text, empty) -> the content array.
+  //
+  // This is intentionally simple and loss-free: callers can still reach
+  // the full wire payload via the `partial` / `steps` objects if needed.
+  static parseStepPayload(result) {
+    const content = result.content;
+    if (!Array.isArray(content) || content.length !== 1) return content ?? [];
+    const item = content[0];
+    if (item.type !== "text" || typeof item.text !== "string") return content;
+    try {
+      return JSON.parse(item.text);
+    } catch {
+      return item.text;
+    }
+  }
   // Declarative pipeline executor. Runs N tool calls in order, binding
   // each output under the step's id (or positional index), and lets
   // later steps splice those outputs into their args via
@@ -9934,6 +11067,7 @@ To load the top pack in one step, call \`mcp_connect_activate\` with namespaces=
     const explicitReturn = typeof args.return === "string" ? args.return : void 0;
     const bindings = {};
     const stepKeys = [];
+    const stepNamespaces = /* @__PURE__ */ new Map();
     for (let i = 0; i < steps.length; i++) {
       const step = steps[i];
       const key = stepBindingKey(step, i);
@@ -10003,9 +11137,26 @@ To load the top pack in one step, call \`mcp_connect_activate\` with namespaces=
           isError: true
         };
       }
-      const stepResult = await this.handleToolCall(step.tool, resolvedArgs);
+      const stepNs = this.toolRoutes.get(step.tool)?.namespace;
+      if (stepNs) stepNamespaces.set(key, stepNs);
+      const stepResult = await this.handleToolCall(step.tool, resolvedArgs, void 0, { deferLearning: true });
       if (stepResult.isError) {
         const errText = stepResult.content?.[0]?.text ?? "unknown error";
+        const routingFault = errText.includes("no longer available") || errText.includes("no longer connected") || errText.includes("auto-reconnect failed") || errText.includes("Unknown tool:");
+        if (stepNs && !routingFault) {
+          const inputShaped = errText.includes("[code=-32602]") || classifyError(errText) === "validation_error";
+          const deps = collectRefDeps(step.args);
+          if (inputShaped && deps.length > 0) {
+            this.learning.recordOutcome(stepNs, 0.5);
+            for (const dep of deps) {
+              const depNs = stepNamespaces.get(dep);
+              if (depNs) this.learning.recordOutcome(depNs, 0.5);
+            }
+          } else {
+            this.learning.recordOutcome(stepNs, 0);
+          }
+          this.scheduleStateSave();
+        }
         return {
           content: [
             {
@@ -10025,7 +11176,11 @@ To load the top pack in one step, call \`mcp_connect_activate\` with namespaces=
           isError: true
         };
       }
-      bindings[key] = stepResult;
+      if (stepNs) {
+        this.learning.recordOutcome(stepNs, computeOutcomeReward(stepResult));
+        this.scheduleStateSave();
+      }
+      bindings[key] = _ConnectServer.parseStepPayload(stepResult);
     }
     const returnKey = explicitReturn ?? stepKeys[stepKeys.length - 1];
     const finalResult = bindings[returnKey];
@@ -10097,7 +11252,7 @@ function parseServersArgs(argv) {
     if (a === "--json") {
       json = true;
     } else if (a === "--help" || a === "-h") {
-      return { ok: false, error: SERVERS_USAGE };
+      return { ok: false, error: SERVERS_USAGE, help: true };
     } else if (a.startsWith("-")) {
       return { ok: false, error: `yaw-mcp servers: unknown argument "${a}"
 
@@ -10171,7 +11326,12 @@ async function runServersCommand(opts = {}) {
     })
   };
   if (opts.json) {
-    print(JSON.stringify(merged, null, 2));
+    const payload = {
+      ...merged,
+      filter: opts.filter ?? null,
+      filterMatched: opts.filter ? merged.servers.length > 0 : null
+    };
+    print(JSON.stringify(payload, null, 2));
     return { exitCode: 0, lines };
   }
   if (opts.filter && filtered.servers.length === 0) {
@@ -10221,8 +11381,165 @@ function truncateVersion(v) {
   return v.length > 8 ? v.slice(0, 8) : v;
 }
 
+// src/set-active-cmd.ts
+import { homedir as homedir16 } from "os";
+
+// src/sync-state.ts
+import { existsSync as existsSync7 } from "fs";
+import { mkdir as mkdir4, readFile as readFile11 } from "fs/promises";
+import { dirname as dirname2, join as join11 } from "path";
+var SYNC_STATE_FILENAME = "sync-state.json";
+function syncStatePath(home) {
+  return join11(home, CONFIG_DIRNAME, SYNC_STATE_FILENAME);
+}
+async function readSyncState(home) {
+  const path5 = syncStatePath(home);
+  if (!existsSync7(path5)) return {};
+  try {
+    const raw = await readFile11(path5, "utf8");
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object") return {};
+    return parsed;
+  } catch {
+    return {};
+  }
+}
+async function writeSyncState(home, state) {
+  const path5 = syncStatePath(home);
+  await mkdir4(dirname2(path5), { recursive: true });
+  await atomicWriteFile(path5, `${JSON.stringify(state, null, 2)}
+`);
+}
+
+// src/set-active-cmd.ts
+var SET_ACTIVE_RESOURCE = "mcp_bundles";
+var SET_ACTIVE_USAGE = `Usage: yaw-mcp set-active <namespace> <on|off>
+
+  Enable or disable a server in your shared Yaw Team config. The change is
+  authoritative -- it applies to every member's config on their next
+  sync/connect.
+
+  <namespace>   The server's namespace (see \`yaw-mcp sync status\` or the dashboard).
+  on|off        Whether the server should be active.
+  --json        Emit machine-readable JSON instead of prose.
+
+  Sign in first with \`yaw-mcp login --key <license-key>\`. To hide a server only
+  on THIS machine, edit the \`blocked\` list in ~/.yaw-mcp/config.json instead.`;
+function parseState(s) {
+  const v = s.toLowerCase();
+  if (v === "on" || v === "true" || v === "enable" || v === "enabled") return true;
+  if (v === "off" || v === "false" || v === "disable" || v === "disabled") return false;
+  return null;
+}
+function parseSetActiveArgs(argv) {
+  const opts = {};
+  const positionals = [];
+  for (const a of argv) {
+    if (a === "--json") opts.json = true;
+    else if (a === "--help" || a === "-h") return { ok: false, error: SET_ACTIVE_USAGE, help: true };
+    else if (a.startsWith("-"))
+      return { ok: false, error: `yaw-mcp set-active: unknown flag "${a}"
+
+${SET_ACTIVE_USAGE}` };
+    else positionals.push(a);
+  }
+  if (positionals.length > 2)
+    return { ok: false, error: `yaw-mcp set-active: too many arguments
+
+${SET_ACTIVE_USAGE}` };
+  const [ns, state] = positionals;
+  if (!ns || !state)
+    return { ok: false, error: `yaw-mcp set-active: <namespace> and <on|off> are required
+
+${SET_ACTIVE_USAGE}` };
+  if (!NAMESPACE_RE.test(ns))
+    return { ok: false, error: `yaw-mcp set-active: invalid namespace "${ns}"
+
+${SET_ACTIVE_USAGE}` };
+  const active = parseState(state);
+  if (active === null)
+    return { ok: false, error: `yaw-mcp set-active: state must be on|off (got "${state}")
+
+${SET_ACTIVE_USAGE}` };
+  opts.namespace = ns;
+  opts.active = active;
+  return { ok: true, options: opts };
+}
+async function runSetActive(opts, io = { out: (s) => process.stdout.write(s), err: (s) => process.stderr.write(s) }, deps = { getResource, putResource, writeSyncState }) {
+  const { namespace, active } = opts;
+  if (!namespace || active === void 0) {
+    io.err("yaw-mcp set-active: <namespace> and <on|off> are required\n");
+    return { exitCode: 2 };
+  }
+  const base = { home: opts.home, baseUrl: opts.baseUrl };
+  try {
+    for (let attempt = 0; ; attempt++) {
+      const res = await deps.getResource(SET_ACTIVE_RESOURCE, base);
+      const data = res.data ?? { servers: [] };
+      const servers = Array.isArray(data.servers) ? data.servers : [];
+      const idx = servers.findIndex((s) => s?.namespace === namespace);
+      if (idx < 0) {
+        return fail(
+          io,
+          opts.json,
+          `No team server with namespace "${namespace}". Run \`yaw-mcp sync status\` to list them.`,
+          1
+        );
+      }
+      if (servers[idx].isActive !== false === active) {
+        return done(io, opts.json, namespace, active, false);
+      }
+      const nextServers = servers.map((s, i) => i === idx ? { ...s, isActive: active } : s);
+      try {
+        const putRes = await deps.putResource(
+          SET_ACTIVE_RESOURCE,
+          res.version,
+          { ...data, version: 1, servers: nextServers },
+          base
+        );
+        if (typeof putRes.version === "number") {
+          await deps.writeSyncState(opts.home ?? homedir16(), {
+            mcp_bundles: { lastPulledVersion: putRes.version }
+          }).catch(() => {
+          });
+        }
+        return done(io, opts.json, namespace, active, true);
+      } catch (e) {
+        if (e instanceof TeamSyncStaleVersionError && attempt < 1) continue;
+        throw e;
+      }
+    }
+  } catch (e) {
+    if (e instanceof TeamSyncAuthError)
+      return fail(io, opts.json, "Not signed in. Run `yaw-mcp login --key <license-key>` first.", 1);
+    if (e instanceof TeamSyncForbiddenError)
+      return fail(io, opts.json, "You do not have permission to edit the team's servers.", 1);
+    return fail(io, opts.json, e instanceof Error ? e.message : String(e), 1);
+  }
+}
+function done(io, json, namespace, active, changed) {
+  if (json) {
+    io.out(`${JSON.stringify({ ok: true, namespace, isActive: active, changed })}
+`);
+  } else if (changed) {
+    io.out(`${namespace} is now ${active ? "active" : "inactive"} for the team.
+`);
+  } else {
+    io.out(`${namespace} is already ${active ? "active" : "inactive"}.
+`);
+  }
+  return { exitCode: 0 };
+}
+function fail(io, json, message, code) {
+  if (json) io.err(`${JSON.stringify({ ok: false, error: message })}
+`);
+  else io.err(`yaw-mcp set-active: ${message}
+`);
+  return { exitCode: code };
+}
+
 // src/stats-cmd.ts
-import { homedir as homedir14 } from "os";
+import { homedir as homedir17 } from "os";
 var STATS_USAGE = `Usage: yaw-mcp stats [--json] [--limit N] [--days N]
 
   Print a digest of recent AI tool calls recorded against your Yaw
@@ -10242,18 +11559,22 @@ function parseStatsArgs(argv) {
       const v = argv[++i];
       const n = Number.parseInt(v ?? "", 10);
       if (!Number.isFinite(n) || n <= 0 || n > 1e3)
-        return { ok: false, error: "yaw-mcp stats: --limit must be a positive integer up to 1000\n\n" + STATS_USAGE };
+        return { ok: false, error: `yaw-mcp stats: --limit must be a positive integer up to 1000
+
+${STATS_USAGE}` };
       opts.limit = n;
     } else if (a === "--days") {
       const v = argv[++i];
       const n = Number.parseInt(v ?? "", 10);
       if (!Number.isFinite(n) || n <= 0 || n > 365)
-        return { ok: false, error: "yaw-mcp stats: --days must be a positive integer up to 365\n\n" + STATS_USAGE };
+        return { ok: false, error: `yaw-mcp stats: --days must be a positive integer up to 365
+
+${STATS_USAGE}` };
       opts.days = n;
     } else if (a === "--json") {
       opts.json = true;
     } else if (a === "--help" || a === "-h") {
-      return { ok: false, error: STATS_USAGE };
+      return { ok: false, error: STATS_USAGE, help: true };
     } else {
       return { ok: false, error: `yaw-mcp stats: unknown argument "${a}"
 
@@ -10294,8 +11615,9 @@ function aggregate(events) {
 function formatPlain(events, opts, orderId, total) {
   const lines = [];
   lines.push(`Signed in to order ${orderId}.`);
+  const renderedCount = Math.min(events.length, opts.limit ?? 50);
   lines.push(
-    `Showing ${events.length} of ${total} event${total === 1 ? "" : "s"} from the last ${opts.days ?? 7} day${opts.days === 1 ? "" : "s"}.`
+    `Showing ${renderedCount} of ${total} event${total === 1 ? "" : "s"} from the last ${opts.days ?? 7} day${opts.days === 1 ? "" : "s"}.`
   );
   if (events.length === 0) {
     lines.push("");
@@ -10306,7 +11628,7 @@ function formatPlain(events, opts, orderId, total) {
   }
   const agg = aggregate(events);
   lines.push("");
-  lines.push("By server:");
+  lines.push("By server (full window):");
   const nsCol = Math.max(...agg.byNamespace.map((n) => n.namespace.length), 6);
   for (const n of agg.byNamespace) {
     const success = n.success.toString().padStart(5);
@@ -10337,7 +11659,7 @@ async function runStats(opts, io = {
   out: (s) => process.stdout.write(s),
   err: (s) => process.stderr.write(s)
 }) {
-  const home = opts.home ?? homedir14();
+  const home = opts.home ?? homedir17();
   const session = await getSession({ home, baseUrl: opts.baseUrl });
   if (!session) {
     const msg = "Not signed in. Yaw MCP analytics requires a Yaw Team account.\n  - Yaw Team: $15/seat/mo or $150/seat/yr -- https://yaw.sh/mcp\nSign in with: yaw-mcp login --key <license-key>";
@@ -10351,7 +11673,7 @@ async function runStats(opts, io = {
     const result = await listAnalyticsEvents({ home, baseUrl: opts.baseUrl });
     const days = opts.days ?? 7;
     const cutoff = Date.now() - days * 24 * 60 * 60 * 1e3;
-    const filtered = result.events.filter((e) => e.ts >= cutoff);
+    const filtered = result.events.filter((e) => e.ts >= cutoff).sort((a, b) => a.ts - b.ts);
     if (opts.json) {
       io.out(
         `${JSON.stringify(
@@ -10394,10 +11716,10 @@ async function runStats(opts, io = {
 }
 
 // src/sync-cmd.ts
-import { existsSync as existsSync7 } from "fs";
-import { mkdir as mkdir4, readFile as readFile11 } from "fs/promises";
-import { homedir as homedir15 } from "os";
-import { dirname as dirname4, join as join11 } from "path";
+import { existsSync as existsSync8 } from "fs";
+import { mkdir as mkdir5, readFile as readFile12 } from "fs/promises";
+import { homedir as homedir18 } from "os";
+import { dirname as dirname3, join as join12 } from "path";
 var SYNC_USAGE = `Usage: yaw-mcp sync <push|pull|status> [--json]
 
   Replicate ~/.yaw-mcp/bundles.json across machines via your Yaw
@@ -10410,7 +11732,9 @@ var SYNC_USAGE = `Usage: yaw-mcp sync <push|pull|status> [--json]
   status  Show sign-in state, last-pulled version, and a coarse
           local-vs-remote diff.
 
-  --json  Emit machine-readable JSON.
+  --json     Emit machine-readable JSON.
+  --dry-run  (pull only) Preview the merge without writing the local file
+             or advancing the sync version.
 
   Sign in first with \`yaw-mcp login --key <license-key>\`.`;
 var BUNDLES_FILENAME2 = "bundles.json";
@@ -10426,8 +11750,10 @@ ${SYNC_USAGE}` };
       opts.action = a;
     } else if (a === "--json") {
       opts.json = true;
+    } else if (a === "--dry-run") {
+      opts.dryRun = true;
     } else if (a === "--help" || a === "-h") {
-      return { ok: false, error: SYNC_USAGE };
+      return { ok: false, error: SYNC_USAGE, help: true };
     } else {
       return { ok: false, error: `yaw-mcp sync: unknown argument "${a}"
 
@@ -10440,24 +11766,30 @@ ${SYNC_USAGE}` };
   return { ok: true, options: opts };
 }
 function bundlesPath(home) {
-  return join11(home, CONFIG_DIRNAME, BUNDLES_FILENAME2);
+  return join12(home, CONFIG_DIRNAME, BUNDLES_FILENAME2);
 }
 async function readLocalBundles(home) {
-  const path3 = bundlesPath(home);
-  if (!existsSync7(path3)) return { version: 1, servers: [] };
-  const raw = await readFile11(path3, "utf8");
-  const parsed = JSON.parse(raw);
+  const path5 = bundlesPath(home);
+  if (!existsSync8(path5)) return { version: 1, servers: [] };
+  const raw = await readFile12(path5, "utf8");
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new Error(`${path5}: invalid JSON -- ${msg}. Fix the file before running sync.`);
+  }
   if (!parsed || typeof parsed !== "object" || !Array.isArray(parsed.servers)) {
-    throw new Error(`${path3}: malformed -- expected { servers: [...] }`);
+    throw new Error(`${path5}: malformed -- expected { servers: [...] }`);
   }
   return parsed;
 }
 async function writeLocalBundles(home, file) {
-  const path3 = bundlesPath(home);
-  await mkdir4(dirname4(path3), { recursive: true });
-  await atomicWriteFile(path3, `${JSON.stringify(file, null, 2)}
+  const path5 = bundlesPath(home);
+  await mkdir5(dirname3(path5), { recursive: true });
+  await atomicWriteFile(path5, `${JSON.stringify(file, null, 2)}
 `);
-  return path3;
+  return path5;
 }
 function stripEnvValues(server) {
   if (!server.env || typeof server.env !== "object") return server;
@@ -10478,11 +11810,19 @@ function mergeLocalEnv(incoming, local) {
     return { ...srv, env: merged };
   });
 }
+function mergeRemoteActive(localStripped, remoteServers) {
+  const remoteByNs = new Map(remoteServers.filter((s) => s.namespace).map((s) => [s.namespace, s]));
+  return localStripped.map((srv) => {
+    const matched = srv.namespace ? remoteByNs.get(srv.namespace) : void 0;
+    if (!matched || matched.isActive === void 0) return srv;
+    return { ...srv, isActive: matched.isActive };
+  });
+}
 async function runSync(opts, io = {
   out: (s) => process.stdout.write(s),
   err: (s) => process.stderr.write(s)
 }) {
-  const home = opts.home ?? homedir15();
+  const home = opts.home ?? homedir18();
   const session = await getSession({ home, baseUrl: opts.baseUrl });
   if (!session) {
     const msg = "Not signed in. Run `yaw-mcp login --key <license-key>` first.";
@@ -10508,7 +11848,9 @@ async function syncStatus(session, opts, io, home) {
     home: opts.home,
     baseUrl: opts.baseUrl
   });
-  const local = await readLocalBundles(home).catch(() => ({ servers: [] }));
+  const local = await readLocalBundles(home);
+  const syncState = await readSyncState(home);
+  const lastPulledVersion = syncState.mcp_bundles?.lastPulledVersion ?? null;
   const localNs = new Set(local.servers.map((s) => s.namespace).filter((n) => typeof n === "string"));
   const remoteNs = new Set(
     (remote.data?.servers ?? []).map((s) => s.namespace).filter((n) => typeof n === "string")
@@ -10523,6 +11865,7 @@ async function syncStatus(session, opts, io, home) {
           signedInAs: session.email,
           role: session.role,
           remoteVersion: remote.version,
+          lastPulledVersion,
           localOnly,
           remoteOnly,
           updatedAt: remote.updated_at,
@@ -10539,6 +11882,8 @@ async function syncStatus(session, opts, io, home) {
     io.out(`Remote mcp_bundles: version ${remote.version}`);
     if (remote.updated_at) io.out(`, updated ${remote.updated_at} by ${remote.updated_by ?? "unknown"}`);
     io.out("\n");
+    io.out(lastPulledVersion === null ? "Last pulled: never pulled.\n" : `Last pulled: v${lastPulledVersion}.
+`);
     if (localOnly.length > 0) io.out(`Local-only servers: ${localOnly.join(", ")}
 `);
     if (remoteOnly.length > 0) io.out(`Remote-only servers: ${remoteOnly.join(", ")}
@@ -10553,9 +11898,26 @@ async function syncPull(opts, io, home) {
     baseUrl: opts.baseUrl
   });
   const remoteServers = remote.data?.servers ?? [];
-  const local = await readLocalBundles(home).catch(() => ({ servers: [] }));
+  const local = await readLocalBundles(home);
   const merged = mergeLocalEnv(remoteServers, local.servers);
+  if (opts.dryRun) {
+    const target = bundlesPath(home);
+    if (opts.json) {
+      io.out(
+        `${JSON.stringify({ ok: true, dryRun: true, wouldWrite: target, serverCount: merged.length, remoteVersion: remote.version }, null, 2)}
+`
+      );
+    } else {
+      io.out(
+        `[dry-run] would pull ${merged.length} server${merged.length === 1 ? "" : "s"} -> ${target} (remote v${remote.version}); nothing written.
+`
+      );
+      if (remote.version === 0) io.out("Remote mcp_bundles is empty (version 0). Push from this machine to seed it.\n");
+    }
+    return { exitCode: 0 };
+  }
   const written = await writeLocalBundles(home, { version: 1, servers: merged });
+  await writeSyncState(home, { mcp_bundles: { lastPulledVersion: remote.version } });
   if (opts.json) {
     io.out(
       `${JSON.stringify({ ok: true, written, serverCount: merged.length, remoteVersion: remote.version }, null, 2)}
@@ -10574,19 +11936,24 @@ async function syncPush(opts, io, home) {
     home: opts.home,
     baseUrl: opts.baseUrl
   });
-  const stripped = local.servers.map(stripEnvValues);
+  const remoteServers = remote.data?.servers ?? [];
+  const stripped = mergeRemoteActive(local.servers.map(stripEnvValues), remoteServers);
   const payload = { version: 1, servers: stripped };
-  const res = await putResource(MCP_BUNDLES_RESOURCE, remote.version, payload, {
+  const syncState = await readSyncState(home);
+  const lastPulled = syncState.mcp_bundles?.lastPulledVersion;
+  const pushVersion = lastPulled ?? remote.version;
+  const res = await putResource(MCP_BUNDLES_RESOURCE, pushVersion, payload, {
     home: opts.home,
     baseUrl: opts.baseUrl
   });
+  await writeSyncState(home, { mcp_bundles: { lastPulledVersion: res.version } });
   if (opts.json) {
     io.out(`${JSON.stringify({ ok: true, serverCount: stripped.length, newVersion: res.version }, null, 2)}
 `);
   } else {
     io.out(`Pushed ${stripped.length} server${stripped.length === 1 ? "" : "s"} -> mcp_bundles v${res.version}.
 `);
-    io.out("Env values stripped before upload; secrets stay machine-local until Phase 6b ships the encrypted vault.\n");
+    io.out("Env values stripped before upload; use `yaw-mcp secrets push` to sync secrets across machines.\n");
   }
   return { exitCode: 0 };
 }
@@ -10625,6 +11992,7 @@ function handleSyncError(err, opts, io) {
 var KNOWN_SUBCOMMANDS = [
   "compliance",
   "audit",
+  "foundry",
   "install",
   "add",
   "remove",
@@ -10642,6 +12010,7 @@ var KNOWN_SUBCOMMANDS = [
   "sync",
   "stats",
   "secrets",
+  "set-active",
   "help",
   "--help",
   "-h",
@@ -10659,9 +12028,23 @@ if (subcommand === "compliance") {
     process.exit(2);
   }
   runAudit(parsed.options).then((r) => process.exit(r.exitCode));
+} else if (subcommand === "foundry") {
+  const parsed = parseFoundryArgs(process.argv.slice(3));
+  if (!parsed.ok) {
+    const isHelp = parsed.error === FOUNDRY_USAGE;
+    (isHelp ? process.stdout : process.stderr).write(`${parsed.error}
+`);
+    process.exit(isHelp ? 0 : 2);
+  }
+  runFoundryExport(parsed.options).then((r) => process.exit(r.exitCode));
 } else if (subcommand === "install") {
   const parsed = parseInstallArgs(process.argv.slice(3));
   if (!parsed.ok) {
+    if (parsed.help) {
+      process.stdout.write(`${parsed.error}
+`);
+      process.exit(0);
+    }
     process.stderr.write(`${parsed.error}
 `);
     process.exit(2);
@@ -10700,6 +12083,11 @@ if (subcommand === "compliance") {
 } else if (subcommand === "servers") {
   const parsed = parseServersArgs(process.argv.slice(3));
   if (!parsed.ok) {
+    if (parsed.help) {
+      process.stdout.write(`${parsed.error}
+`);
+      process.exit(0);
+    }
     process.stderr.write(`${parsed.error}
 `);
     process.exit(2);
@@ -10708,6 +12096,11 @@ if (subcommand === "compliance") {
 } else if (subcommand === "bundles") {
   const parsed = parseBundlesArgs(process.argv.slice(3));
   if (!parsed.ok) {
+    if (parsed.help) {
+      process.stdout.write(`${parsed.error}
+`);
+      process.exit(0);
+    }
     process.stderr.write(`${parsed.error}
 `);
     process.exit(2);
@@ -10716,6 +12109,11 @@ if (subcommand === "compliance") {
 } else if (subcommand === "completion") {
   const parsed = parseCompletionArgs(process.argv.slice(3));
   if (!parsed.ok) {
+    if (parsed.help) {
+      process.stdout.write(`${parsed.error}
+`);
+      process.exit(0);
+    }
     process.stderr.write(`${parsed.error}
 `);
     process.exit(2);
@@ -10724,6 +12122,11 @@ if (subcommand === "compliance") {
 } else if (subcommand === "upgrade") {
   const parsed = parseUpgradeArgs(process.argv.slice(3));
   if (!parsed.ok) {
+    if (parsed.help) {
+      process.stdout.write(`${parsed.error}
+`);
+      process.exit(0);
+    }
     process.stderr.write(`${parsed.error}
 `);
     process.exit(2);
@@ -10732,6 +12135,11 @@ if (subcommand === "compliance") {
 } else if (subcommand === "try") {
   const parsed = parseTryArgs(process.argv.slice(3));
   if (!parsed.ok) {
+    if (parsed.help) {
+      process.stdout.write(`${parsed.error}
+`);
+      process.exit(0);
+    }
     process.stderr.write(`${parsed.error}
 `);
     process.exit(2);
@@ -10740,6 +12148,11 @@ if (subcommand === "compliance") {
 } else if (subcommand === "try-cleanup") {
   const parsed = parseTryCleanupArgs(process.argv.slice(3));
   if (!parsed.ok) {
+    if (parsed.help) {
+      process.stdout.write(`${parsed.error}
+`);
+      process.exit(0);
+    }
     process.stderr.write(`${parsed.error}
 `);
     process.exit(2);
@@ -10748,6 +12161,11 @@ if (subcommand === "compliance") {
 } else if (subcommand === "add") {
   const parsed = parseAddArgs(process.argv.slice(3));
   if (!parsed.ok) {
+    if (parsed.help) {
+      process.stdout.write(`${parsed.error}
+`);
+      process.exit(0);
+    }
     process.stderr.write(`${parsed.error}
 `);
     process.exit(2);
@@ -10756,6 +12174,11 @@ if (subcommand === "compliance") {
 } else if (subcommand === "remove") {
   const parsed = parseRemoveArgs(process.argv.slice(3));
   if (!parsed.ok) {
+    if (parsed.help) {
+      process.stdout.write(`${parsed.error}
+`);
+      process.exit(0);
+    }
     process.stderr.write(`${parsed.error}
 `);
     process.exit(2);
@@ -10764,6 +12187,11 @@ if (subcommand === "compliance") {
 } else if (subcommand === "list") {
   const parsed = parseListArgs(process.argv.slice(3));
   if (!parsed.ok) {
+    if (parsed.help) {
+      process.stdout.write(`${parsed.error}
+`);
+      process.exit(0);
+    }
     process.stderr.write(`${parsed.error}
 `);
     process.exit(2);
@@ -10772,6 +12200,11 @@ if (subcommand === "compliance") {
 } else if (subcommand === "login") {
   const parsed = parseLoginArgs(process.argv.slice(3));
   if (!parsed.ok) {
+    if (parsed.help) {
+      process.stdout.write(`${parsed.error}
+`);
+      process.exit(0);
+    }
     process.stderr.write(`${parsed.error}
 `);
     process.exit(2);
@@ -10780,6 +12213,11 @@ if (subcommand === "compliance") {
 } else if (subcommand === "logout") {
   const parsed = parseLogoutArgs(process.argv.slice(3));
   if (!parsed.ok) {
+    if (parsed.help) {
+      process.stdout.write(`${parsed.error}
+`);
+      process.exit(0);
+    }
     process.stderr.write(`${parsed.error}
 `);
     process.exit(2);
@@ -10788,6 +12226,11 @@ if (subcommand === "compliance") {
 } else if (subcommand === "sync") {
   const parsed = parseSyncArgs(process.argv.slice(3));
   if (!parsed.ok) {
+    if (parsed.help) {
+      process.stdout.write(`${parsed.error}
+`);
+      process.exit(0);
+    }
     process.stderr.write(`${parsed.error}
 `);
     process.exit(2);
@@ -10796,6 +12239,11 @@ if (subcommand === "compliance") {
 } else if (subcommand === "stats") {
   const parsed = parseStatsArgs(process.argv.slice(3));
   if (!parsed.ok) {
+    if (parsed.help) {
+      process.stdout.write(`${parsed.error}
+`);
+      process.exit(0);
+    }
     process.stderr.write(`${parsed.error}
 `);
     process.exit(2);
@@ -10804,19 +12252,38 @@ if (subcommand === "compliance") {
 } else if (subcommand === "secrets") {
   const parsed = parseSecretsArgs(process.argv.slice(3));
   if (!parsed.ok) {
+    if (parsed.help) {
+      process.stdout.write(`${parsed.error}
+`);
+      process.exit(0);
+    }
     process.stderr.write(`${parsed.error}
 `);
     process.exit(2);
   }
   runSecrets(parsed.options).then((r) => process.exit(r.exitCode));
+} else if (subcommand === "set-active") {
+  const parsed = parseSetActiveArgs(process.argv.slice(3));
+  if (!parsed.ok) {
+    if (parsed.help) {
+      process.stdout.write(`${parsed.error}
+`);
+      process.exit(0);
+    }
+    process.stderr.write(`${parsed.error}
+`);
+    process.exit(2);
+  }
+  runSetActive(parsed.options).then((r) => process.exit(r.exitCode));
 } else if (subcommand === "--help" || subcommand === "-h" || subcommand === "help") {
   process.stdout.write(`
   yaw-mcp \u2014 one install, every MCP server, managed from the cloud.
 
   Quickstart:
-    1. Get a token      https://yaw.sh/mcp/dashboard/settings/tokens
-    2. Install yaw-mcp     yaw-mcp install claude-code --token mcp_pat_...
-    3. Verify setup     yaw-mcp doctor
+    1. Install yaw-mcp     yaw-mcp install claude-code
+    2. Verify setup     yaw-mcp doctor
+    3. Yaw Team (optional)  yaw-mcp login --key <license-key>
+                            https://yaw.sh/mcp/dashboard/settings/tokens
 
   Setup (connect a client to yaw-mcp):
     install <client>         Connect one MCP client to yaw-mcp. This wires the
@@ -10919,12 +12386,12 @@ if (subcommand === "compliance") {
   (or kill yaw-mcp; the client will respawn it) after editing any config.
 
   Docs:   https://yaw.sh/mcp
-  Source: https://github.com/YawLabs/yaw-mcp
+  Source: https://github.com/YawLabs/mcp
 
 `);
   process.exit(0);
 } else if (subcommand === "--version" || subcommand === "-V") {
-  process.stdout.write(`yaw-mcp ${true ? "0.60.6" : "dev"}
+  process.stdout.write(`yaw-mcp ${true ? "0.62.0" : "dev"}
 `);
   process.exit(0);
 } else if (subcommand && !subcommand.startsWith("-")) {
@@ -10966,6 +12433,8 @@ async function runServer() {
   };
   process.on("SIGTERM", shutdown);
   process.on("SIGINT", shutdown);
+  process.on("unhandledRejection", (e) => log("error", "unhandledRejection", { error: String(e) }));
+  process.on("uncaughtException", (e) => log("error", "uncaughtException", { error: String(e) }));
   server.start().catch((err) => {
     if (err instanceof ConfigError && err.fatal) {
       const msg2 = err instanceof Error ? err.message : String(err);