@yawlabs/ssh-mcp 0.14.0 → 0.15.0

package/dist/index.js

@@ -1,19 +1,32 @@
 #!/usr/bin/env node
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
 
 // src/index.ts
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
 // src/env.ts
 import { execFileSync as execFileSync2 } from "child_process";
-import { appendFileSync, existsSync as existsSync2, readdirSync as readdirSync2, readFileSync as readFileSync2, statSync } from "fs";
-import { homedir as homedir2 } from "os";
-import { join as join2 } from "path";
+import { appendFileSync, existsSync as existsSync2, readdirSync as readdirSync2, readFileSync as readFileSync3, statSync } from "fs";
+import { homedir as homedir3 } from "os";
+import { join as join3 } from "path";
 
 // src/diagnose.ts
 import { execFileSync } from "child_process";
 import { existsSync, readdirSync, readFileSync } from "fs";
 import { homedir } from "os";
 import { join } from "path";
+var SSH_NON_KEY_FILES = /* @__PURE__ */ new Set([
+  "known_hosts",
+  "known_hosts.old",
+  "config",
+  "authorized_keys",
+  "environment"
+]);
 function isValidHostname(host) {
   if (host.length === 0 || host.length > 253) return false;
   if (host.startsWith("[")) {
@@ -60,16 +73,16 @@ ${stdout2}` };
     };
   }
   const { stdout, ok } = runArgs("ssh-add", ["-l"]);
-  if (!ok && stdout.includes("Could not open a connection")) {
+  if (stdout.includes("The agent has no identities") || stdout.includes("no identities")) {
     return {
-      status: "error",
-      message: `SSH_AUTH_SOCK is set to "${sock}" but the agent is not reachable. The agent process may have died. Run: eval "$(ssh-agent -s)"`
+      status: "warning",
+      message: "ssh-agent is running but has no keys loaded. Run: ssh-add <key-path>"
     };
   }
-  if (stdout.includes("The agent has no identities")) {
+  if (!ok) {
     return {
-      status: "warning",
-      message: "ssh-agent is running but has no keys loaded. Run: ssh-add <key-path>"
+      status: "error",
+      message: stdout.includes("Could not open a connection") ? `SSH_AUTH_SOCK is set to "${sock}" but the agent is not reachable. The agent process may have died. Run: eval "$(ssh-agent -s)"` : `SSH_AUTH_SOCK is set to "${sock}" but ssh-add could not query the agent: ${stdout || "no output"}. Run: eval "$(ssh-agent -s)"`
     };
   }
   return { status: "ok", message: `ssh-agent running with keys:
@@ -90,9 +103,7 @@ function checkSshKeys() {
     }
   }
   try {
-    const allFiles = readdirSync(sshDir).filter(
-      (f) => !f.endsWith(".pub") && !["known_hosts", "known_hosts.old", "config", "authorized_keys"].includes(f)
-    );
+    const allFiles = readdirSync(sshDir).filter((f) => !f.endsWith(".pub") && !SSH_NON_KEY_FILES.has(f));
     for (const f of allFiles) {
       if (!keyTypes.includes(f) && existsSync(join(sshDir, f))) {
         try {
@@ -134,10 +145,17 @@ function checkKnownHosts(host) {
   }
   return { status: "ok", message: `Host "${host}" found in known_hosts` };
 }
-function checkConnectivity(host, port = 22) {
-  if (!isValidHostname(host)) {
-    return { status: "error", message: `Invalid hostname: "${host}"` };
-  }
+function classifySshProbe(ok, output) {
+  if (ok && output.includes("SSH_OK")) return "ok";
+  if (output.includes("Permission denied")) return "permission-denied";
+  if (output.includes("Connection refused")) return "connection-refused";
+  if (output.includes("timed out")) return "timed-out";
+  if (output.includes("Host key verification failed")) return "host-key-mismatch";
+  if (output.includes("Could not resolve")) return "dns-failure";
+  return "unknown";
+}
+function probeSshConnection(host, port) {
+  const start = Date.now();
   const { ok, stdout } = runArgs("ssh", [
     "-o",
     "ConnectTimeout=5",
@@ -152,40 +170,66 @@ function checkConnectivity(host, port = 22) {
     "echo",
     "SSH_OK"
   ]);
-  if (ok && stdout.includes("SSH_OK")) {
-    return { status: "ok", message: `SSH connection to ${host}:${port} succeeded` };
-  }
-  if (stdout.includes("Permission denied")) {
-    return {
-      status: "error",
-      message: `Permission denied connecting to ${host}:${port}. Your key is not authorized on this host. Check: 1) correct key is loaded (ssh-add -l), 2) key is in remote authorized_keys, 3) correct username.`
-    };
-  }
-  if (stdout.includes("Connection refused")) {
-    return {
-      status: "error",
-      message: `Connection refused at ${host}:${port}. SSH server is not running on this port or host is blocking connections.`
-    };
-  }
-  if (stdout.includes("Connection timed out") || stdout.includes("timed out")) {
-    return {
-      status: "error",
-      message: `Connection timed out to ${host}:${port}. Host may be down, port may be blocked by firewall, or DNS resolution failed.`
-    };
+  return { outcome: classifySshProbe(ok, stdout), output: stdout, elapsedMs: Date.now() - start };
+}
+function checkConnectivity(host, port = 22) {
+  if (!isValidHostname(host)) {
+    return { status: "error", message: `Invalid hostname: "${host}"` };
   }
-  if (stdout.includes("Host key verification failed")) {
-    return {
-      status: "error",
-      message: `Host key verification failed for ${host}. The host key changed (instance recreated?). Fix: ssh-keygen -R "${host}" && ssh-keyscan -H "${host}" >> ~/.ssh/known_hosts`
-    };
+  const { outcome, output } = probeSshConnection(host, port);
+  switch (outcome) {
+    case "ok":
+      return { status: "ok", message: `SSH connection to ${host}:${port} succeeded` };
+    case "permission-denied":
+      return {
+        status: "error",
+        message: `Permission denied connecting to ${host}:${port}. Your key is not authorized on this host. Check: 1) correct key is loaded (ssh-add -l), 2) key is in remote authorized_keys, 3) correct username.`
+      };
+    case "connection-refused":
+      return {
+        status: "error",
+        message: `Connection refused at ${host}:${port}. SSH server is not running on this port or host is blocking connections.`
+      };
+    case "timed-out":
+      return {
+        status: "error",
+        message: `Connection timed out to ${host}:${port}. Host may be down, port may be blocked by firewall, or DNS resolution failed.`
+      };
+    case "host-key-mismatch":
+      return {
+        status: "error",
+        message: `Host key verification failed for ${host}. The host key changed (instance recreated?). Fix: ssh-keygen -R "${host}" && ssh-keyscan -H "${host}" >> ~/.ssh/known_hosts`
+      };
+    case "dns-failure":
+      return {
+        status: "error",
+        message: `Could not resolve hostname "${host}". Check DNS, /etc/hosts, or SSH config aliases.`
+      };
+    default:
+      return { status: "error", message: `SSH connection failed: ${output}` };
   }
-  if (stdout.includes("Could not resolve hostname")) {
-    return {
-      status: "error",
-      message: `Could not resolve hostname "${host}". Check DNS, /etc/hosts, or SSH config aliases.`
-    };
+}
+function matchesHostPattern(pattern, host) {
+  if (pattern === "*") return true;
+  if (pattern === host) return true;
+  if (pattern.includes("*") || pattern.includes("?")) {
+    const escaped = pattern.replace(/[\\^$.|+()[\]{}]/g, "\\$&");
+    return new RegExp("^" + escaped.replace(/\*/g, ".*").replace(/\?/g, ".") + "$").test(host);
   }
-  return { status: "error", message: `SSH connection failed: ${stdout}` };
+  return false;
+}
+function hostLineSelects(patternList, host) {
+  let positive = false;
+  for (const raw of patternList.split(/\s+/)) {
+    if (!raw) continue;
+    const negated = raw.startsWith("!");
+    const pattern = negated ? raw.slice(1) : raw;
+    if (!pattern) continue;
+    if (!matchesHostPattern(pattern, host)) continue;
+    if (negated) return false;
+    positive = true;
+  }
+  return positive;
 }
 function checkSshConfig(host) {
   const configPath = join(homedir(), ".ssh", "config");
@@ -194,24 +238,17 @@ function checkSshConfig(host) {
   }
   try {
     const content = readFileSync(configPath, "utf8");
-    const lines = content.split("\n");
+    const lines = content.split(/\r?\n/);
     let inHostBlock = false;
     const hostConfig = [];
-    for (const line of lines) {
-      const trimmed = line.trim();
-      if (/^Host\s+/i.test(trimmed)) {
-        const patterns = trimmed.replace(/^Host\s+/i, "").trim().split(/\s+/);
-        inHostBlock = patterns.some((p) => {
-          if (p === "*") return true;
-          if (p === host) return true;
-          if (p.includes("*") || p.includes("?")) {
-            const escaped = p.replace(/[\\^$.|+()[\]{}]/g, "\\$&");
-            const regex = new RegExp("^" + escaped.replace(/\*/g, ".*").replace(/\?/g, ".") + "$");
-            return regex.test(host);
-          }
-          return false;
-        });
+    for (const rawLine of lines) {
+      const trimmed = rawLine.replace(/(^|\s)#.*/, "$1").trim();
+      if (/^Host[\s=]/i.test(trimmed)) {
+        const patternList = trimmed.replace(/^Host[\s=]+/i, "").trim();
+        inHostBlock = hostLineSelects(patternList, host);
         if (inHostBlock) hostConfig.push(trimmed);
+      } else if (/^Match[\s=]/i.test(trimmed)) {
+        inHostBlock = false;
       } else if (inHostBlock && trimmed) {
         hostConfig.push(trimmed);
       }
@@ -261,6 +298,15 @@ function diagnose(host, port = 22) {
   return { overall, checks, suggestions };
 }
 
+// src/ssh.ts
+import { readFileSync as readFileSync2 } from "fs";
+import { createRequire } from "module";
+import { homedir as homedir2 } from "os";
+import { join as join2 } from "path";
+import {
+  Client
+} from "ssh2";
+
 // src/ssh-config.ts
 function parseSshConfigOutput(stdout) {
   const all = {};
@@ -280,450 +326,220 @@ function parseSshConfigOutput(stdout) {
   return { all, identityFiles };
 }
 
-// src/env.ts
-function runArgsWithEnv(cmd, args, extraEnv) {
-  const env = {};
-  for (const [k, v] of Object.entries(process.env)) {
-    if (typeof v === "string") env[k] = v;
+// src/ssh.ts
+var sshConfigCache = /* @__PURE__ */ new Map();
+function resolveFromSshConfig(host) {
+  const cached = sshConfigCache.get(host);
+  if (cached !== void 0) return cached;
+  const result = resolveFromSshConfigUncached(host);
+  sshConfigCache.set(host, result);
+  return result;
+}
+function resolveFromSshConfigUncached(host) {
+  try {
+    const { stdout, ok } = runArgs("ssh", ["-G", host]);
+    if (!ok) return null;
+    const { all, identityFiles } = parseSshConfigOutput(stdout);
+    return {
+      hostname: all.hostname || host,
+      user: all.user || "",
+      port: all.port || "22",
+      identityFiles,
+      proxyJump: all.proxyjump && all.proxyjump !== "none" ? all.proxyjump : void 0
+    };
+  } catch {
+    return null;
   }
-  for (const [k, v] of Object.entries(extraEnv)) {
-    if (v === void 0) {
-      delete env[k];
-    } else {
-      env[k] = v;
+}
+function unbracketHost(host) {
+  return host.length > 2 && host.startsWith("[") && host.endsWith("]") ? host.slice(1, -1) : host;
+}
+function knownHostsTargets(host, port) {
+  const bare = unbracketHost(host);
+  const isIpv6 = bare.includes(":");
+  if (!isValidHostname(isIpv6 ? `[${bare}]` : bare)) return [];
+  return port && port !== 22 ? [`[${bare}]:${port}`, bare] : [bare];
+}
+function readKnownHostsEntries(host, port) {
+  const entries = [];
+  for (const target of knownHostsTargets(host, port)) {
+    const { stdout, ok } = runArgs("ssh-keygen", ["-F", target]);
+    if (!ok || !stdout.trim()) continue;
+    for (const line of stdout.split("\n")) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith("#")) continue;
+      const parts = trimmed.split(/\s+/);
+      if (parts[0].startsWith("@")) continue;
+      if (parts.length < 3) continue;
+      try {
+        entries.push({ type: parts[1], key: Buffer.from(parts[2], "base64") });
+      } catch {
+      }
     }
   }
-  try {
-    const stdout = execFileSync2(cmd, args, {
-      env,
-      encoding: "utf8",
-      timeout: 1e4,
-      stdio: ["pipe", "pipe", "pipe"]
-    });
-    return { stdout: stdout.trim(), ok: true };
-  } catch (e) {
-    const err = e;
-    const so = err.stdout?.toString().trim() || "";
-    const se = err.stderr?.toString().trim() || "";
-    const output = [so, se].filter(Boolean).join("\n") || err.message || "";
-    return { stdout: output, ok: false };
-  }
+  return entries;
 }
-function probeAgent(socket, agentLabel) {
-  const isWindowsNamedPipe = socket.startsWith("\\\\.\\pipe\\");
-  const extraEnv = isWindowsNamedPipe ? { SSH_AUTH_SOCK: void 0 } : { SSH_AUTH_SOCK: socket };
-  const { stdout, ok } = runArgsWithEnv("ssh-add", ["-l"], extraEnv);
-  const noIdentities = stdout.includes("no identities") || stdout.includes("The agent has no identities");
-  if (!ok && !noIdentities) return null;
-  const keys = ok && !noIdentities ? stdout.split("\n").filter(Boolean) : [];
-  return {
-    running: true,
-    reachable: true,
-    socket,
-    keys,
-    started: false,
-    message: keys.length > 0 ? `${agentLabel} running with ${keys.length} key(s) loaded` : `${agentLabel} running but no keys loaded. Use ssh_key_load to add one.`
-  };
+function hostKeyBlobType(key) {
+  if (key.length < 4) return null;
+  const len = key.readUInt32BE(0);
+  if (len === 0 || len > 64 || key.length < 4 + len) return null;
+  const type = key.toString("utf8", 4, 4 + len);
+  return /^[a-zA-Z0-9@._-]+$/.test(type) ? type : null;
 }
-var startedAgentPid = null;
-function killStartedAgent() {
-  if (startedAgentPid === null) return;
+var HOST_KEY_TYPE_TO_ALGORITHMS = {
+  "ssh-rsa": ["rsa-sha2-512", "rsa-sha2-256", "ssh-rsa"]
+};
+var SSH2_CONSTANTS_MODULE = "ssh2/lib/protocol/constants.js";
+function loadSsh2Constants() {
   try {
-    process.kill(startedAgentPid);
+    return __require("ssh2/lib/protocol/constants.js");
   } catch {
   }
-  startedAgentPid = null;
-}
-function ensureAgent() {
-  const sock = process.env.SSH_AUTH_SOCK;
-  if (sock) {
-    const result = probeAgent(sock, "ssh-agent");
-    if (result) return result;
-  }
-  if (process.platform === "win32") {
-    const result = probeAgent("\\\\.\\pipe\\openssh-ssh-agent", "Windows OpenSSH agent");
-    if (result) return result;
-    return {
-      running: false,
-      reachable: false,
-      keys: [],
-      started: false,
-      message: "Windows OpenSSH agent not running. Start it: Get-Service ssh-agent | Set-Service -StartupType Automatic; Start-Service ssh-agent"
-    };
+  try {
+    return createRequire(import.meta.url)(SSH2_CONSTANTS_MODULE);
+  } catch {
+    return null;
   }
-  const { stdout, ok } = runArgs("ssh-agent", ["-s"]);
-  if (ok) {
-    const sockMatch = stdout.match(/SSH_AUTH_SOCK=([^;]+)/);
-    const pidMatch = stdout.match(/SSH_AGENT_PID=([^;]+)/);
-    if (sockMatch) {
-      process.env.SSH_AUTH_SOCK = sockMatch[1];
-      if (pidMatch) {
-        process.env.SSH_AGENT_PID = pidMatch[1];
-        startedAgentPid = Number.parseInt(pidMatch[1], 10);
+}
+var ssh2DefaultHostKeyAlgos;
+function defaultServerHostKeyAlgorithms() {
+  if (ssh2DefaultHostKeyAlgos !== void 0) return ssh2DefaultHostKeyAlgos;
+  const DEFAULT_SERVER_HOST_KEY = loadSsh2Constants()?.DEFAULT_SERVER_HOST_KEY;
+  ssh2DefaultHostKeyAlgos = Array.isArray(DEFAULT_SERVER_HOST_KEY) && DEFAULT_SERVER_HOST_KEY.length > 0 && DEFAULT_SERVER_HOST_KEY.every((a) => typeof a === "string") ? DEFAULT_SERVER_HOST_KEY.slice() : null;
+  return ssh2DefaultHostKeyAlgos;
+}
+function hostKeyAlgorithmOrder(knownHostTypes) {
+  if (knownHostTypes.length === 0) return null;
+  const defaults = defaultServerHostKeyAlgorithms();
+  if (!defaults) return null;
+  const preferred = /* @__PURE__ */ new Set();
+  for (const type of knownHostTypes) {
+    for (const algo of HOST_KEY_TYPE_TO_ALGORITHMS[type] ?? [type]) preferred.add(algo);
+  }
+  const front = defaults.filter((a) => preferred.has(a));
+  const back = defaults.filter((a) => !preferred.has(a));
+  if (front.length === 0 || back.length === 0) return null;
+  return [...front, ...back];
+}
+var KNOWN_HOST_TYPE_TTL_MS = 5e3;
+var knownHostTypeCache = /* @__PURE__ */ new Map();
+function cachedKnownHostTypes(hosts, port) {
+  const cacheKey = `${hosts.join(" ")}:${port ?? ""}`;
+  const now = Date.now();
+  const hit = knownHostTypeCache.get(cacheKey);
+  if (hit && now - hit.at < KNOWN_HOST_TYPE_TTL_MS) return hit.types;
+  const types = [...new Set(hosts.flatMap((h) => readKnownHostsEntries(h, port).map((e) => e.type)))];
+  knownHostTypeCache.set(cacheKey, { at: now, types });
+  return types;
+}
+function buildHostVerifier(hosts, port, rejection) {
+  const strict = process.env.SSH_MCP_STRICT_HOST_KEY === "1";
+  const label = hosts.join(" / ");
+  const remediationHost = unbracketHost(hosts[0]);
+  return (key) => {
+    rejection.current = null;
+    const known = hosts.flatMap((h) => readKnownHostsEntries(h, port));
+    if (known.length === 0) {
+      if (strict) {
+        rejection.current = {
+          reason: "unknown-host-strict",
+          message: `no known_hosts entry for ${label}, and SSH_MCP_STRICT_HOST_KEY=1 requires one. Add it: ssh-keyscan -H "${remediationHost}" >> ~/.ssh/known_hosts`
+        };
       }
-      return {
-        running: true,
-        reachable: true,
-        socket: sockMatch[1],
-        keys: [],
-        started: true,
-        env: { SSH_AUTH_SOCK: sockMatch[1], SSH_AGENT_PID: pidMatch?.[1] },
-        message: "Started new ssh-agent scoped to the ssh-mcp server process. Your shell's environment is NOT modified \u2014 this agent is only visible to this MCP server and will terminate when the server exits. No keys loaded yet \u2014 use ssh_key_load to add one."
-      };
+      return !strict;
     }
-  }
-  return {
-    running: false,
-    reachable: false,
-    keys: [],
-    started: false,
-    message: 'Could not start ssh-agent. Run manually: eval "$(ssh-agent -s)"'
+    if (known.some((e) => e.key.equals(key))) return true;
+    const offered = hostKeyBlobType(key);
+    const knownTypes = [...new Set(known.map((e) => e.type))];
+    rejection.current = offered && !knownTypes.includes(offered) ? {
+      reason: "algorithm-not-in-known-hosts",
+      message: `the server offered a ${offered} host key, but known_hosts has only ${knownTypes.join(", ")} for ${label}. This is NOT a key mismatch -- there is no ${offered} entry to compare it against. Refresh the entry: ssh-keyscan -H "${remediationHost}" >> ~/.ssh/known_hosts`
+    } : {
+      reason: "key-mismatch",
+      message: `the server's ${offered ?? "offered"} host key does NOT match the known_hosts entry of the same type for ${label}. This can mean a man-in-the-middle attack, or that the host was legitimately rekeyed. Verify the fingerprint out of band before removing the old entry with: ssh-keygen -R "${remediationHost}"`
+    };
+    return false;
   };
 }
-function detectKeyType(filePath, fileName) {
-  const pubPath = `${filePath}.pub`;
-  if (existsSync2(pubPath)) {
+var PRIVATE_KEY_MARKER = /-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----/;
+function looksLikePrivateKey(content) {
+  const text = content.toString("utf8");
+  return PRIVATE_KEY_MARKER.test(text) || text.trimStart().startsWith("PuTTY-User-Key-File-");
+}
+function isEncryptedKey(content) {
+  const text = content.toString("utf8");
+  if (text.includes("ENCRYPTED")) return true;
+  const m = text.match(/-----BEGIN OPENSSH PRIVATE KEY-----([\s\S]+?)-----END/);
+  if (m) {
     try {
-      const pub = readFileSync2(pubPath, "utf8");
-      if (pub.includes("ssh-ed25519")) return "ed25519";
-      if (pub.includes("ssh-rsa")) return "rsa";
-      if (pub.includes("ecdsa")) return "ecdsa";
-      if (pub.includes("ssh-dss")) return "dsa";
+      const raw = Buffer.from(m[1].replace(/\s+/g, ""), "base64");
+      const magic = "openssh-key-v1\0";
+      if (raw.toString("latin1", 0, magic.length) !== magic) return true;
+      const cipherLen = raw.readUInt32BE(magic.length);
+      const cipher = raw.toString("latin1", magic.length + 4, magic.length + 4 + cipherLen);
+      return cipher !== "none";
     } catch {
+      return true;
     }
   }
-  if (fileName.includes("ed25519")) return "ed25519";
-  if (fileName.includes("rsa")) return "rsa";
-  if (fileName.includes("ecdsa")) return "ecdsa";
-  if (fileName.includes("dsa")) return "dsa";
-  try {
-    const content = readFileSync2(filePath, "utf8");
-    if (content.includes("RSA PRIVATE KEY")) return "rsa";
-    if (content.includes("EC PRIVATE KEY")) return "ecdsa";
-    if (content.includes("DSA PRIVATE KEY")) return "dsa";
-    if (content.includes("OPENSSH PRIVATE KEY")) {
-      const { stdout, ok } = runArgs("ssh-keygen", ["-l", "-f", filePath]);
-      if (ok) {
-        const match = stdout.match(/\(([^)]+)\)\s*$/);
-        if (match) return match[1].toLowerCase();
+  return false;
+}
+function resolveConfig(config) {
+  const sshConfig = resolveFromSshConfig(config.host);
+  const port = config.port || (sshConfig ? Number.parseInt(sshConfig.port, 10) : 22);
+  const verifierHosts = [];
+  const seenHosts = /* @__PURE__ */ new Set();
+  for (const candidate of [config.host, sshConfig?.hostname]) {
+    if (!candidate) continue;
+    const canonical = unbracketHost(candidate);
+    if (seenHosts.has(canonical)) continue;
+    seenHosts.add(canonical);
+    verifierHosts.push(candidate);
+  }
+  const hostKeyRejection = { current: null };
+  const connectConfig = {
+    host: sshConfig?.hostname || config.host,
+    port,
+    username: config.username || sshConfig?.user || process.env.USER || process.env.USERNAME || "root",
+    keepaliveInterval: 15e3,
+    keepaliveCountMax: 3,
+    hostVerifier: buildHostVerifier(verifierHosts, port, hostKeyRejection)
+  };
+  let algorithmsApplied = false;
+  const applyHostKeyAlgorithms = () => {
+    if (algorithmsApplied) return;
+    algorithmsApplied = true;
+    const algorithmOrder = hostKeyAlgorithmOrder(cachedKnownHostTypes(verifierHosts, port));
+    if (algorithmOrder) {
+      connectConfig.algorithms = { serverHostKey: algorithmOrder };
+    }
+  };
+  const home = homedir2();
+  if (config.privateKeyPath) {
+    const keyPath = config.privateKeyPath.startsWith("~") ? join2(home, config.privateKeyPath.slice(1)) : config.privateKeyPath;
+    connectConfig.privateKey = readFileSync2(keyPath);
+  } else if (config.password) {
+    connectConfig.password = config.password;
+  } else {
+    const agentSock = config.agent || process.env.SSH_AUTH_SOCK || (process.platform === "win32" ? "\\\\.\\pipe\\openssh-ssh-agent" : void 0);
+    if (agentSock) {
+      connectConfig.agent = agentSock;
+    }
+    const keyPaths = sshConfig && sshConfig.identityFiles.length > 0 ? sshConfig.identityFiles.map((p) => p.startsWith("~") ? join2(home, p.slice(1)) : p) : [join2(home, ".ssh", "id_ed25519"), join2(home, ".ssh", "id_rsa"), join2(home, ".ssh", "id_ecdsa")];
+    for (const keyPath of keyPaths) {
+      let keyData;
+      try {
+        keyData = readFileSync2(keyPath);
+      } catch {
+        continue;
       }
+      if (!looksLikePrivateKey(keyData)) continue;
+      if (agentSock && isEncryptedKey(keyData)) continue;
+      connectConfig.privateKey = keyData;
+      break;
     }
-  } catch {
-  }
-  return "unknown";
-}
-function listSshKeys() {
-  const sshDir = join2(homedir2(), ".ssh");
-  if (!existsSync2(sshDir)) return [];
-  const loadedFingerprints = /* @__PURE__ */ new Set();
-  const { stdout: agentOut, ok: agentOk } = runArgs("ssh-add", ["-l"]);
-  if (agentOk && !agentOut.includes("no identities")) {
-    for (const line of agentOut.split("\n").filter(Boolean)) {
-      const match = line.match(/(\S+:\S+)/);
-      if (match) loadedFingerprints.add(match[1]);
-    }
-  }
-  const skipFiles = /* @__PURE__ */ new Set(["known_hosts", "known_hosts.old", "config", "authorized_keys", "environment"]);
-  const keys = [];
-  let files;
-  try {
-    files = readdirSync2(sshDir);
-  } catch {
-    return [];
-  }
-  for (const file of files) {
-    if (file.endsWith(".pub") || file.startsWith(".") || skipFiles.has(file)) continue;
-    const filePath = join2(sshDir, file);
-    try {
-      const stat = statSync(filePath);
-      if (!stat.isFile()) continue;
-      const content = readFileSync2(filePath, "utf8");
-      if (!content.includes("PRIVATE KEY")) continue;
-      const type = detectKeyType(filePath, file);
-      let fingerprint;
-      const { stdout: fpOut, ok: fpOk } = runArgs("ssh-keygen", ["-lf", filePath]);
-      if (fpOk) {
-        const match = fpOut.match(/(\S+:\S+)/);
-        fingerprint = match?.[1];
-      }
-      const loadedInAgent = fingerprint ? loadedFingerprints.has(fingerprint) : false;
-      keys.push({ name: file, path: filePath, type, fingerprint, loadedInAgent });
-    } catch {
-    }
-  }
-  return keys;
-}
-function loadKey(keyPath) {
-  const agent = ensureAgent();
-  if (!agent.reachable) {
-    return { status: "error", message: agent.message };
-  }
-  const resolved = keyPath.startsWith("~") ? join2(homedir2(), keyPath.slice(1)) : keyPath;
-  if (!existsSync2(resolved)) {
-    return { status: "error", message: `Key not found: ${resolved}` };
-  }
-  const { stdout, ok } = runArgs("ssh-add", [resolved]);
-  if (ok) {
-    return { status: "ok", message: `Key loaded: ${resolved}` };
-  }
-  if (stdout.includes("UNPROTECTED PRIVATE KEY") || stdout.includes("too open") || stdout.includes("bad permissions")) {
-    return { status: "error", message: `Key ${resolved} has too-open permissions. Fix: chmod 600 ${resolved}` };
-  }
-  if (stdout.includes("passphrase") || stdout.includes("incorrect")) {
-    return { status: "error", message: `Key ${resolved} requires a passphrase. Add it manually: ssh-add ${resolved}` };
-  }
-  return { status: "error", message: `Failed to load key: ${stdout}` };
-}
-function configLookup(host) {
-  if (!isValidHostname(host)) {
-    return { error: `Invalid hostname: "${host}"` };
-  }
-  const { stdout, ok } = runArgs("ssh", ["-G", host]);
-  if (!ok) {
-    return { error: `Failed to resolve SSH config for ${host}: ${stdout}` };
-  }
-  const { all, identityFiles } = parseSshConfigOutput(stdout);
-  return {
-    hostname: all.hostname || host,
-    user: all.user || "",
-    port: all.port || "22",
-    identityFile: identityFiles,
-    proxyJump: all.proxyjump && all.proxyjump !== "none" ? all.proxyjump : void 0,
-    proxyCommand: all.proxycommand && all.proxycommand !== "none" ? all.proxycommand : void 0,
-    all,
-    raw: stdout
-  };
-}
-function fixKnownHosts(host, port = 22) {
-  if (!isValidHostname(host)) {
-    return { status: "error", message: `Invalid hostname: "${host}"`, actions: [] };
-  }
-  const actions = [];
-  const { ok: removeOk } = runArgs("ssh-keygen", ["-R", host]);
-  if (removeOk) {
-    actions.push(`Removed old host key for ${host}`);
-  }
-  if (port !== 22) {
-    const { ok } = runArgs("ssh-keygen", ["-R", `[${host}]:${port}`]);
-    if (ok) actions.push(`Removed old host key for [${host}]:${port}`);
-  }
-  const scanArgs = port !== 22 ? ["-H", "-p", String(port), host] : ["-H", host];
-  const { stdout: scanOut, ok: scanOk } = runArgs("ssh-keyscan", scanArgs);
-  if (scanOk && scanOut.trim()) {
-    try {
-      const knownHostsPath = join2(homedir2(), ".ssh", "known_hosts");
-      appendFileSync(knownHostsPath, `
-${scanOut.trim()}
-`);
-      actions.push(`Added new host key for ${host}`);
-      return { status: "ok", message: `Host key refreshed for ${host}`, actions };
-    } catch (e) {
-      const msg = e instanceof Error ? e.message : String(e);
-      return { status: "error", message: `Scanned key but failed to write known_hosts: ${msg}`, actions };
-    }
-  }
-  return { status: "error", message: `Could not scan host key for ${host}. Host may be unreachable.`, actions };
-}
-function checkGitSsh(host = "github.com", user = "git") {
-  if (!isValidHostname(host)) {
-    return { status: "error", message: `Invalid hostname: "${host}"` };
-  }
-  const { stdout } = runArgs("ssh", ["-T", "-o", "ConnectTimeout=5", "-o", "BatchMode=yes", `${user}@${host}`]);
-  const text = stdout;
-  if (text.includes("successfully authenticated") || text.includes("Welcome to GitLab") || text.includes("logged in as")) {
-    const userMatch = text.match(/Hi (\S+)!/) || text.match(/@(\S+)!/) || text.match(/logged in as (\S+)/);
-    return {
-      status: "ok",
-      message: `Git SSH authentication to ${host} succeeded${userMatch ? ` as ${userMatch[1]}` : ""}`,
-      authenticatedAs: userMatch?.[1]
-    };
-  }
-  if (text.includes("Permission denied")) {
-    return {
-      status: "error",
-      message: `Permission denied for ${host}. Either no key is loaded in the agent or your key isn't registered with ${host}. Run ssh_key_list to check, then ssh_key_load if needed.`
-    };
-  }
-  if (text.includes("Connection refused")) {
-    return { status: "error", message: `Connection refused by ${host}. SSH may not be available on this host.` };
-  }
-  if (text.includes("timed out") || text.includes("Connection timed out")) {
-    return { status: "error", message: `Connection to ${host} timed out. Check your network or firewall.` };
-  }
-  if (text.includes("Could not resolve")) {
-    return { status: "error", message: `Could not resolve hostname "${host}". Check DNS or spelling.` };
-  }
-  return { status: "error", message: `Git SSH check for ${host}: ${text || "no response (agent may not be running)"}` };
-}
-function testConnection(host, port = 22) {
-  if (!isValidHostname(host)) {
-    return { status: "error", message: `Invalid hostname: "${host}"` };
-  }
-  const start = Date.now();
-  const { ok, stdout } = runArgs("ssh", [
-    "-o",
-    "ConnectTimeout=5",
-    "-o",
-    "BatchMode=yes",
-    "-o",
-    "StrictHostKeyChecking=no",
-    "-p",
-    String(port),
-    "--",
-    host,
-    "echo",
-    "SSH_OK"
-  ]);
-  const elapsed = Date.now() - start;
-  if (ok && stdout.includes("SSH_OK")) {
-    return { status: "ok", message: `Connected to ${host}:${port} in ${elapsed}ms` };
-  }
-  if (stdout.includes("Permission denied")) {
-    return {
-      status: "error",
-      message: `Authentication failed to ${host}:${port} (${elapsed}ms). Key not authorized. Check: ssh-add -l, verify correct username, verify key is in remote authorized_keys.`
-    };
-  }
-  if (stdout.includes("Connection refused")) {
-    return {
-      status: "error",
-      message: `Connection refused at ${host}:${port}. SSH server not running or port blocked.`
-    };
-  }
-  if (stdout.includes("timed out")) {
-    return { status: "error", message: `Connection timed out to ${host}:${port}. Host down or firewall blocking.` };
-  }
-  if (stdout.includes("Host key verification failed")) {
-    return {
-      status: "error",
-      message: `Host key mismatch for ${host}. Instance was likely recreated. Fix with ssh_known_hosts_fix.`
-    };
-  }
-  if (stdout.includes("Could not resolve")) {
-    return { status: "error", message: `Could not resolve "${host}". Check DNS, /etc/hosts, or SSH config.` };
-  }
-  return { status: "error", message: `Connection failed to ${host}:${port}: ${stdout}` };
-}
-
-// src/pool.ts
-import { createHash } from "crypto";
-
-// src/ssh.ts
-import { readFileSync as readFileSync3 } from "fs";
-import { homedir as homedir3 } from "os";
-import { join as join3 } from "path";
-import { Client } from "ssh2";
-var sshConfigCache = /* @__PURE__ */ new Map();
-function resolveFromSshConfig(host) {
-  const cached = sshConfigCache.get(host);
-  if (cached !== void 0) return cached;
-  const result = resolveFromSshConfigUncached(host);
-  sshConfigCache.set(host, result);
-  return result;
-}
-function resolveFromSshConfigUncached(host) {
-  try {
-    const { stdout, ok } = runArgs("ssh", ["-G", host]);
-    if (!ok) return null;
-    const { all, identityFiles } = parseSshConfigOutput(stdout);
-    return {
-      hostname: all.hostname || host,
-      user: all.user || "",
-      port: all.port || "22",
-      identityFiles,
-      proxyJump: all.proxyjump && all.proxyjump !== "none" ? all.proxyjump : void 0
-    };
-  } catch {
-    return null;
   }
-}
-function readKnownHostsKeys(host, port) {
-  if (!isValidHostname(host)) return [];
-  const targets = port && port !== 22 ? [`[${host}]:${port}`, host] : [host];
-  const keys = [];
-  for (const target of targets) {
-    const { stdout, ok } = runArgs("ssh-keygen", ["-F", target]);
-    if (!ok || !stdout.trim()) continue;
-    for (const line of stdout.split("\n")) {
-      const trimmed = line.trim();
-      if (!trimmed || trimmed.startsWith("#")) continue;
-      const parts = trimmed.split(/\s+/);
-      if (parts.length < 3) continue;
-      try {
-        keys.push(Buffer.from(parts[2], "base64"));
-      } catch {
-      }
-    }
-  }
-  return keys;
-}
-function buildHostVerifier(hosts, port) {
-  const strict = process.env.SSH_MCP_STRICT_HOST_KEY === "1";
-  return (key) => {
-    const known = hosts.flatMap((h) => readKnownHostsKeys(h, port));
-    if (known.length === 0) {
-      return !strict;
-    }
-    return known.some((k) => k.equals(key));
-  };
-}
-function isEncryptedKey(content) {
-  const text = content.toString("utf8");
-  if (text.includes("ENCRYPTED")) return true;
-  const m = text.match(/-----BEGIN OPENSSH PRIVATE KEY-----([\s\S]+?)-----END/);
-  if (m) {
-    try {
-      const raw = Buffer.from(m[1].replace(/\s+/g, ""), "base64");
-      const magic = "openssh-key-v1\0";
-      if (raw.toString("latin1", 0, magic.length) === magic) {
-        const cipherLen = raw.readUInt32BE(magic.length);
-        const cipher = raw.toString("latin1", magic.length + 4, magic.length + 4 + cipherLen);
-        return cipher !== "none";
-      }
-    } catch {
-      return true;
-    }
-  }
-  return false;
-}
-function resolveConfig(config) {
-  const sshConfig = resolveFromSshConfig(config.host);
-  const port = config.port || (sshConfig ? Number.parseInt(sshConfig.port, 10) : 22);
-  const verifierHosts = [config.host];
-  if (sshConfig?.hostname && sshConfig.hostname !== config.host) {
-    verifierHosts.push(sshConfig.hostname);
-  }
-  const connectConfig = {
-    host: sshConfig?.hostname || config.host,
-    port,
-    username: config.username || sshConfig?.user || process.env.USER || process.env.USERNAME || "root",
-    keepaliveInterval: 15e3,
-    keepaliveCountMax: 3,
-    hostVerifier: buildHostVerifier(verifierHosts, port)
-  };
-  const home = homedir3();
-  if (config.privateKeyPath) {
-    const keyPath = config.privateKeyPath.startsWith("~") ? join3(home, config.privateKeyPath.slice(1)) : config.privateKeyPath;
-    connectConfig.privateKey = readFileSync3(keyPath);
-  } else if (config.password) {
-    connectConfig.password = config.password;
-  } else {
-    const agentSock = config.agent || process.env.SSH_AUTH_SOCK || (process.platform === "win32" ? "\\\\.\\pipe\\openssh-ssh-agent" : void 0);
-    if (agentSock) {
-      connectConfig.agent = agentSock;
-    }
-    const keyPaths = sshConfig && sshConfig.identityFiles.length > 0 ? sshConfig.identityFiles.map((p) => p.startsWith("~") ? join3(home, p.slice(1)) : p) : [join3(home, ".ssh", "id_ed25519"), join3(home, ".ssh", "id_rsa"), join3(home, ".ssh", "id_ecdsa")];
-    for (const keyPath of keyPaths) {
-      try {
-        const keyData = readFileSync3(keyPath);
-        if (agentSock && isEncryptedKey(keyData)) continue;
-        connectConfig.privateKey = keyData;
-        break;
-      } catch {
-      }
-    }
-  }
-  return { connectConfig, proxyJump: sshConfig?.proxyJump };
+  return { connectConfig, proxyJump: sshConfig?.proxyJump, hostKeyRejection, applyHostKeyAlgorithms };
 }
 var DIAG_CACHE_TTL_MS = 2e3;
 var diagAgentCache = null;
@@ -782,12 +598,82 @@ function connectRaw(connectConfig) {
     client.on("ready", () => resolve(client)).on("error", (err) => reject(err)).connect(connectConfig);
   });
 }
-async function connectWithProxy(resolved) {
-  if (!resolved.proxyJump) {
-    return connectRaw(resolved.connectConfig);
+function parsePort(text) {
+  if (!/^\d{1,5}$/.test(text)) return void 0;
+  const port = Number.parseInt(text, 10);
+  return port >= 1 && port <= 65535 ? port : void 0;
+}
+function parseJumpSpec(spec) {
+  const hops = [];
+  for (const piece of spec.split(",")) {
+    const hop = parseJumpHop(piece.trim());
+    if (hop) hops.push(hop);
+  }
+  return hops;
+}
+function parseJumpHop(piece) {
+  if (!piece) return null;
+  let rest = piece.startsWith("ssh://") ? piece.slice("ssh://".length) : piece;
+  if (!rest) return null;
+  let username;
+  const at = rest.lastIndexOf("@");
+  if (at !== -1) {
+    username = rest.slice(0, at) || void 0;
+    rest = rest.slice(at + 1);
+  }
+  let host = rest;
+  let port;
+  if (host.startsWith("[")) {
+    const close = host.indexOf("]");
+    if (close !== -1) {
+      const after = host.slice(close + 1);
+      host = host.slice(1, close);
+      if (after.startsWith(":")) port = parsePort(after.slice(1));
+    }
+  } else if (host.indexOf(":") !== -1 && host.indexOf(":") === host.lastIndexOf(":")) {
+    const colon = host.lastIndexOf(":");
+    const parsed = parsePort(host.slice(colon + 1));
+    if (parsed !== void 0) {
+      port = parsed;
+      host = host.slice(0, colon);
+    }
+  }
+  if (!host) return null;
+  const hop = { host };
+  if (port !== void 0) hop.port = port;
+  if (username !== void 0) hop.username = username;
+  return hop;
+}
+function formatJumpHop(hop) {
+  const host = hop.host.includes(":") ? `[${hop.host}]` : hop.host;
+  const withPort = hop.port ? `${host}:${hop.port}` : host;
+  return hop.username ? `${hop.username}@${withPort}` : withPort;
+}
+async function connectWithProxy(resolved) {
+  resolved.applyHostKeyAlgorithms?.();
+  const hops = resolved.proxyJump ? parseJumpSpec(resolved.proxyJump) : [];
+  if (hops.length === 0) {
+    return connectRaw(resolved.connectConfig);
+  }
+  const jumpHop = hops[hops.length - 1];
+  const jumpLabel = formatJumpHop(jumpHop);
+  const jumpResolved = resolveConfig({ host: jumpHop.host, port: jumpHop.port, username: jumpHop.username });
+  if (hops.length > 1) {
+    jumpResolved.proxyJump = hops.slice(0, -1).map(formatJumpHop).join(",");
+  }
+  let jumpClient;
+  try {
+    jumpClient = await connectWithProxy(jumpResolved);
+  } catch (err) {
+    const jumpRejection = jumpResolved.hostKeyRejection?.current;
+    if (jumpRejection && resolved.hostKeyRejection) {
+      resolved.hostKeyRejection.current = {
+        reason: jumpRejection.reason,
+        message: `on jump host ${jumpLabel} -- ${jumpRejection.message}`
+      };
+    }
+    throw err;
   }
-  const jumpResolved = resolveConfig({ host: resolved.proxyJump });
-  const jumpClient = await connectWithProxy(jumpResolved);
   const targetHost = resolved.connectConfig.host;
   const targetPort = resolved.connectConfig.port;
   const endJump = () => {
@@ -815,28 +701,44 @@ async function connectWithProxy(resolved) {
     }).connect({ ...resolved.connectConfig, sock: stream });
   });
 }
+function enhanceSshError(err, host, resolved) {
+  const extra = [];
+  const rejection = resolved?.hostKeyRejection?.current;
+  if (rejection) extra.push(`Host key check failed -- ${rejection.message}`);
+  const diag = formatDiagnostics(host);
+  if (diag) extra.push(`SSH Diagnostics:
+${diag}`);
+  if (extra.length === 0) return err;
+  const message = err instanceof Error ? err.message : String(err);
+  const enhanced = new Error([message, ...extra].join("\n\n"));
+  enhanced.cause = err;
+  return enhanced;
+}
 var DEFAULT_MAX_EXEC_BYTES = 10 * 1024 * 1024;
 function exec(client, command, timeoutMs = 3e4, maxBytes = DEFAULT_MAX_EXEC_BYTES) {
   return new Promise((resolve, reject) => {
     let settled = false;
     let activeStream = null;
+    let releaseCapture = null;
     const settle = (fn) => {
       if (settled) return;
       settled = true;
       clearTimeout(timer);
       fn();
     };
-    const timer = setTimeout(() => {
-      if (activeStream) {
-        try {
-          activeStream.signal("TERM");
-        } catch {
-        }
-        try {
-          activeStream.close();
-        } catch {
-        }
+    const teardownStream = (stream) => {
+      try {
+        stream.signal("TERM");
+      } catch {
+      }
+      try {
+        stream.close();
+      } catch {
       }
+    };
+    const timer = setTimeout(() => {
+      releaseCapture?.();
+      if (activeStream) teardownStream(activeStream);
       settle(() => reject(new Error(`Command timed out after ${timeoutMs}ms`)));
     }, timeoutMs);
     client.exec(command, (err, stream) => {
@@ -898,6 +800,18 @@ function exec(client, command, timeoutMs = 3e4, maxBytes = DEFAULT_MAX_EXEC_BYTE
       stream.stderr.on("data", appendStderr).on("error", (err2) => {
         settle(() => reject(err2));
       });
+      releaseCapture = () => {
+        stream.removeListener("data", appendStdout);
+        stream.stderr.removeListener("data", appendStderr);
+        stdoutChunks.length = 0;
+        stderrChunks.length = 0;
+        stdoutBytes = 0;
+        stderrBytes = 0;
+      };
+      if (settled) {
+        releaseCapture();
+        teardownStream(stream);
+      }
     });
   });
 }
@@ -924,143 +838,475 @@ async function readFile(client, remotePath, maxBytes = DEFAULT_MAX_READ_BYTES) {
         `File is ${(stats.size / 1024 / 1024).toFixed(1)} MB, exceeds ${(maxBytes / 1024 / 1024).toFixed(0)} MB limit. Use ssh_exec with head/tail to read a portion.`
       );
     }
-    return await new Promise((resolve, reject) => {
-      sftp.readFile(remotePath, (err, data) => {
-        if (err) return reject(err);
-        resolve(data.toString("utf8"));
-      });
-    });
-  } finally {
-    sftp.end();
+    return await new Promise((resolve, reject) => {
+      sftp.readFile(remotePath, (err, data) => {
+        if (err) return reject(err);
+        resolve(data.toString("utf8"));
+      });
+    });
+  } finally {
+    sftp.end();
+  }
+}
+async function writeFile(client, remotePath, content) {
+  const sftp = await getSftp(client);
+  try {
+    await new Promise((resolve, reject) => {
+      sftp.writeFile(remotePath, content, (err) => {
+        if (err) return reject(err);
+        resolve();
+      });
+    });
+  } finally {
+    sftp.end();
+  }
+}
+async function uploadFile(client, localPath, remotePath) {
+  const resolvedLocal = localPath.startsWith("~") ? join2(homedir2(), localPath.slice(1)) : localPath;
+  const sftp = await getSftp(client);
+  try {
+    await new Promise((resolve, reject) => {
+      sftp.fastPut(resolvedLocal, remotePath, (err) => {
+        if (err) return reject(err);
+        resolve();
+      });
+    });
+  } finally {
+    sftp.end();
+  }
+}
+async function downloadFile(client, remotePath, localPath) {
+  const resolvedLocal = localPath.startsWith("~") ? join2(homedir2(), localPath.slice(1)) : localPath;
+  const sftp = await getSftp(client);
+  try {
+    await new Promise((resolve, reject) => {
+      sftp.fastGet(remotePath, resolvedLocal, (err) => {
+        if (err) return reject(err);
+        resolve();
+      });
+    });
+  } finally {
+    sftp.end();
+  }
+}
+async function listDir(client, remotePath) {
+  const sftp = await getSftp(client);
+  try {
+    return await new Promise((resolve, reject) => {
+      sftp.readdir(remotePath, (err, list) => {
+        if (err) return reject(err);
+        resolve(list.map((item) => item.filename));
+      });
+    });
+  } finally {
+    sftp.end();
+  }
+}
+async function statFile(client, remotePath) {
+  const sftp = await getSftp(client);
+  const call = (fn) => new Promise((resolve, reject) => {
+    sftp[fn](remotePath, (err, stats) => err ? reject(err) : resolve(stats));
+  });
+  try {
+    const link = await call("lstat");
+    const isSymbolicLink = link.isSymbolicLink();
+    let meta = link;
+    if (isSymbolicLink) {
+      try {
+        meta = await call("stat");
+      } catch {
+      }
+    }
+    return {
+      size: meta.size,
+      mode: meta.mode,
+      modeOctal: (meta.mode & 4095).toString(8).padStart(4, "0"),
+      uid: meta.uid,
+      gid: meta.gid,
+      mtime: meta.mtime,
+      atime: meta.atime,
+      // isFile / isDirectory describe the TARGET (they pair with the metadata above);
+      // isSymbolicLink describes the PATH. A symlink to a directory is therefore both
+      // a directory and a symlink, and the caller decides which matters.
+      isFile: meta.isFile(),
+      isDirectory: meta.isDirectory(),
+      isSymbolicLink
+    };
+  } finally {
+    sftp.end();
+  }
+}
+async function deleteFile(client, remotePath) {
+  const sftp = await getSftp(client);
+  try {
+    const stats = await new Promise((resolve, reject) => {
+      sftp.lstat(remotePath, (err, stats2) => {
+        if (err) return reject(err);
+        resolve(stats2);
+      });
+    });
+    await new Promise((resolve, reject) => {
+      const done = (err) => err ? reject(err) : resolve();
+      if (stats.isDirectory()) {
+        sftp.rmdir(remotePath, done);
+      } else {
+        sftp.unlink(remotePath, done);
+      }
+    });
+  } finally {
+    sftp.end();
+  }
+}
+async function makeDir(client, remotePath, recursive = false) {
+  const sftp = await getSftp(client);
+  try {
+    const mkOne = (path) => new Promise((resolve, reject) => {
+      sftp.mkdir(path, (err) => err ? reject(err) : resolve());
+    });
+    if (!recursive) {
+      await mkOne(remotePath);
+      return;
+    }
+    const parts = remotePath.split("/").filter(Boolean);
+    let cur = remotePath.startsWith("/") ? "" : ".";
+    for (let i = 0; i < parts.length; i++) {
+      cur = `${cur}/${parts[i]}`;
+      const isLeaf = i === parts.length - 1;
+      try {
+        await mkOne(cur);
+      } catch (e) {
+        if (isLeaf) throw e;
+      }
+    }
+  } finally {
+    sftp.end();
+  }
+}
+
+// src/env.ts
+function runArgsWithEnv(cmd, args, extraEnv) {
+  const env = {};
+  for (const [k, v] of Object.entries(process.env)) {
+    if (typeof v === "string") env[k] = v;
+  }
+  for (const [k, v] of Object.entries(extraEnv)) {
+    if (v === void 0) {
+      delete env[k];
+    } else {
+      env[k] = v;
+    }
+  }
+  try {
+    const stdout = execFileSync2(cmd, args, {
+      env,
+      encoding: "utf8",
+      timeout: 1e4,
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+    return { stdout: stdout.trim(), ok: true };
+  } catch (e) {
+    const err = e;
+    const so = err.stdout?.toString().trim() || "";
+    const se = err.stderr?.toString().trim() || "";
+    const output = [so, se].filter(Boolean).join("\n") || err.message || "";
+    return { stdout: output, ok: false };
+  }
+}
+function probeAgent(socket, agentLabel) {
+  const isWindowsNamedPipe = socket.startsWith("\\\\.\\pipe\\");
+  const extraEnv = isWindowsNamedPipe ? { SSH_AUTH_SOCK: void 0 } : { SSH_AUTH_SOCK: socket };
+  const { stdout, ok } = runArgsWithEnv("ssh-add", ["-l"], extraEnv);
+  const noIdentities = stdout.includes("no identities") || stdout.includes("The agent has no identities");
+  if (!ok && !noIdentities) return null;
+  const keys = ok && !noIdentities ? stdout.split("\n").filter(Boolean) : [];
+  return {
+    running: true,
+    reachable: true,
+    socket,
+    keys,
+    started: false,
+    message: keys.length > 0 ? `${agentLabel} running with ${keys.length} key(s) loaded` : `${agentLabel} running but no keys loaded. Use ssh_key_load to add one.`
+  };
+}
+var startedAgentPid = null;
+function killStartedAgent() {
+  if (startedAgentPid === null) return;
+  try {
+    process.kill(startedAgentPid);
+  } catch {
+  }
+  startedAgentPid = null;
+}
+function ensureAgent() {
+  const sock = process.env.SSH_AUTH_SOCK;
+  if (sock) {
+    const result = probeAgent(sock, "ssh-agent");
+    if (result) return result;
+  }
+  if (process.platform === "win32") {
+    const result = probeAgent("\\\\.\\pipe\\openssh-ssh-agent", "Windows OpenSSH agent");
+    if (result) return result;
+    return {
+      running: false,
+      reachable: false,
+      keys: [],
+      started: false,
+      message: "Windows OpenSSH agent not running. Start it: Get-Service ssh-agent | Set-Service -StartupType Automatic; Start-Service ssh-agent"
+    };
+  }
+  const { stdout, ok } = runArgs("ssh-agent", ["-s"]);
+  if (ok) {
+    const sockMatch = stdout.match(/SSH_AUTH_SOCK=([^;]+)/);
+    const pidMatch = stdout.match(/SSH_AGENT_PID=([^;]+)/);
+    if (sockMatch) {
+      process.env.SSH_AUTH_SOCK = sockMatch[1];
+      if (pidMatch) {
+        process.env.SSH_AGENT_PID = pidMatch[1];
+        startedAgentPid = Number.parseInt(pidMatch[1], 10);
+      }
+      return {
+        running: true,
+        reachable: true,
+        socket: sockMatch[1],
+        keys: [],
+        started: true,
+        env: { SSH_AUTH_SOCK: sockMatch[1], SSH_AGENT_PID: pidMatch?.[1] },
+        message: "Started new ssh-agent scoped to the ssh-mcp server process. Your shell's environment is NOT modified \u2014 this agent is only visible to this MCP server and will terminate when the server exits. No keys loaded yet \u2014 use ssh_key_load to add one."
+      };
+    }
+  }
+  return {
+    running: false,
+    reachable: false,
+    keys: [],
+    started: false,
+    message: 'Could not start ssh-agent. Run manually: eval "$(ssh-agent -s)"'
+  };
+}
+function detectKeyType(filePath, fileName) {
+  const pubPath = `${filePath}.pub`;
+  if (existsSync2(pubPath)) {
+    try {
+      const pub = readFileSync3(pubPath, "utf8");
+      if (pub.includes("ssh-ed25519")) return "ed25519";
+      if (pub.includes("ssh-rsa")) return "rsa";
+      if (pub.includes("ecdsa")) return "ecdsa";
+      if (pub.includes("ssh-dss")) return "dsa";
+    } catch {
+    }
+  }
+  if (fileName.includes("ed25519")) return "ed25519";
+  if (fileName.includes("rsa")) return "rsa";
+  if (fileName.includes("ecdsa")) return "ecdsa";
+  if (fileName.includes("dsa")) return "dsa";
+  try {
+    const content = readFileSync3(filePath, "utf8");
+    if (content.includes("RSA PRIVATE KEY")) return "rsa";
+    if (content.includes("EC PRIVATE KEY")) return "ecdsa";
+    if (content.includes("DSA PRIVATE KEY")) return "dsa";
+    if (content.includes("OPENSSH PRIVATE KEY")) {
+      const { stdout, ok } = runArgs("ssh-keygen", ["-l", "-f", filePath]);
+      if (ok) {
+        const match = stdout.match(/\(([^)]+)\)\s*$/);
+        if (match) return match[1].toLowerCase();
+      }
+    }
+  } catch {
+  }
+  return "unknown";
+}
+function listSshKeysDetailed() {
+  const sshDir = join3(homedir3(), ".ssh");
+  if (!existsSync2(sshDir)) return { status: "no-dir", dir: sshDir, keys: [] };
+  const loadedFingerprints = /* @__PURE__ */ new Set();
+  const { stdout: agentOut, ok: agentOk } = runArgs("ssh-add", ["-l"]);
+  if (agentOk && !agentOut.includes("no identities")) {
+    for (const line of agentOut.split("\n").filter(Boolean)) {
+      const match = line.match(/(\S+:\S+)/);
+      if (match) loadedFingerprints.add(match[1]);
+    }
+  }
+  const keys = [];
+  let files;
+  try {
+    files = readdirSync2(sshDir);
+  } catch (e) {
+    return { status: "unreadable", dir: sshDir, keys: [], reason: e instanceof Error ? e.message : String(e) };
+  }
+  for (const file of files) {
+    if (file.endsWith(".pub") || file.startsWith(".") || SSH_NON_KEY_FILES.has(file)) continue;
+    const filePath = join3(sshDir, file);
+    try {
+      const stat = statSync(filePath);
+      if (!stat.isFile()) continue;
+      const content = readFileSync3(filePath, "utf8");
+      if (!content.includes("PRIVATE KEY")) continue;
+      const type = detectKeyType(filePath, file);
+      let fingerprint;
+      const { stdout: fpOut, ok: fpOk } = runArgs("ssh-keygen", ["-lf", filePath]);
+      if (fpOk) {
+        const match = fpOut.match(/(\S+:\S+)/);
+        fingerprint = match?.[1];
+      }
+      const loadedInAgent = fingerprint ? loadedFingerprints.has(fingerprint) : false;
+      keys.push({ name: file, path: filePath, type, fingerprint, loadedInAgent });
+    } catch {
+    }
   }
+  return { status: "ok", dir: sshDir, keys };
 }
-async function writeFile(client, remotePath, content) {
-  const sftp = await getSftp(client);
-  try {
-    await new Promise((resolve, reject) => {
-      sftp.writeFile(remotePath, content, (err) => {
-        if (err) return reject(err);
-        resolve();
-      });
-    });
-  } finally {
-    sftp.end();
+function loadKey(keyPath) {
+  const agent = ensureAgent();
+  if (!agent.reachable) {
+    return { status: "error", message: agent.message };
+  }
+  const resolved = keyPath.startsWith("~") ? join3(homedir3(), keyPath.slice(1)) : keyPath;
+  if (!existsSync2(resolved)) {
+    return { status: "error", message: `Key not found: ${resolved}` };
   }
+  const { stdout, ok } = runArgs("ssh-add", [resolved]);
+  if (ok) {
+    return { status: "ok", message: `Key loaded: ${resolved}` };
+  }
+  if (stdout.includes("UNPROTECTED PRIVATE KEY") || stdout.includes("too open") || stdout.includes("bad permissions")) {
+    return { status: "error", message: `Key ${resolved} has too-open permissions. Fix: chmod 600 ${resolved}` };
+  }
+  if (stdout.includes("passphrase") || stdout.includes("incorrect")) {
+    return { status: "error", message: `Key ${resolved} requires a passphrase. Add it manually: ssh-add ${resolved}` };
+  }
+  return { status: "error", message: `Failed to load key: ${stdout}` };
 }
-async function uploadFile(client, localPath, remotePath) {
-  const resolvedLocal = localPath.startsWith("~") ? join3(homedir3(), localPath.slice(1)) : localPath;
-  const sftp = await getSftp(client);
-  try {
-    await new Promise((resolve, reject) => {
-      sftp.fastPut(resolvedLocal, remotePath, (err) => {
-        if (err) return reject(err);
-        resolve();
-      });
-    });
-  } finally {
-    sftp.end();
+function configLookup(host) {
+  if (!isValidHostname(host)) {
+    return { error: `Invalid hostname: "${host}"` };
+  }
+  const { stdout, ok } = runArgs("ssh", ["-G", host]);
+  if (!ok) {
+    return { error: `Failed to resolve SSH config for ${host}: ${stdout}` };
   }
+  const { all, identityFiles } = parseSshConfigOutput(stdout);
+  return {
+    hostname: all.hostname || host,
+    user: all.user || "",
+    port: all.port || "22",
+    identityFile: identityFiles,
+    proxyJump: all.proxyjump && all.proxyjump !== "none" ? all.proxyjump : void 0,
+    proxyCommand: all.proxycommand && all.proxycommand !== "none" ? all.proxycommand : void 0,
+    all,
+    raw: stdout
+  };
 }
-async function downloadFile(client, remotePath, localPath) {
-  const resolvedLocal = localPath.startsWith("~") ? join3(homedir3(), localPath.slice(1)) : localPath;
-  const sftp = await getSftp(client);
-  try {
-    await new Promise((resolve, reject) => {
-      sftp.fastGet(remotePath, resolvedLocal, (err) => {
-        if (err) return reject(err);
-        resolve();
-      });
-    });
-  } finally {
-    sftp.end();
+var KEYGEN_REMOVED = [/(?:^|\s)found: line \d+/m, / updated\.$/m];
+var KEYGEN_NO_FILE = /Cannot stat .*No such file or directory/s;
+function removeKnownHostEntry(target) {
+  const { stdout, ok } = runArgs("ssh-keygen", ["-R", target]);
+  if (!ok) {
+    return KEYGEN_NO_FILE.test(stdout) ? { result: "absent", output: stdout } : { result: "failed", output: stdout };
   }
+  if (KEYGEN_REMOVED.some((re) => re.test(stdout))) return { result: "removed", output: stdout };
+  return { result: "absent", output: stdout };
 }
-async function listDir(client, remotePath) {
-  const sftp = await getSftp(client);
-  try {
-    return await new Promise((resolve, reject) => {
-      sftp.readdir(remotePath, (err, list) => {
-        if (err) return reject(err);
-        resolve(list.map((item) => item.filename));
-      });
-    });
-  } finally {
-    sftp.end();
+function describeRemoval(target, removal) {
+  switch (removal.result) {
+    case "removed":
+      return `Removed old host key for ${target}`;
+    case "absent":
+      return `No existing host key for ${target} (nothing to remove)`;
+    default:
+      return `Could not remove existing host key for ${target}: ${removal.output || "ssh-keygen failed"}`;
   }
 }
-async function statFile(client, remotePath) {
-  const sftp = await getSftp(client);
-  try {
-    return await new Promise((resolve, reject) => {
-      sftp.stat(remotePath, (err, stats) => {
-        if (err) return reject(err);
-        resolve({
-          size: stats.size,
-          mode: stats.mode,
-          modeOctal: (stats.mode & 4095).toString(8).padStart(4, "0"),
-          uid: stats.uid,
-          gid: stats.gid,
-          mtime: stats.mtime,
-          atime: stats.atime,
-          isFile: stats.isFile(),
-          isDirectory: stats.isDirectory(),
-          isSymbolicLink: stats.isSymbolicLink()
-        });
-      });
-    });
-  } finally {
-    sftp.end();
+function fixKnownHosts(host, port = 22) {
+  if (!isValidHostname(host)) {
+    return { status: "error", message: `Invalid hostname: "${host}"`, actions: [] };
+  }
+  const actions = [];
+  for (const target of knownHostsTargets(host, port)) {
+    actions.push(describeRemoval(target, removeKnownHostEntry(target)));
+  }
+  const scanHost = unbracketHost(host);
+  const scanArgs = port !== 22 ? ["-H", "-p", String(port), scanHost] : ["-H", scanHost];
+  const { stdout: scanOut, ok: scanOk } = runArgs("ssh-keyscan", scanArgs);
+  if (scanOk && scanOut.trim()) {
+    try {
+      const knownHostsPath = join3(homedir3(), ".ssh", "known_hosts");
+      appendFileSync(knownHostsPath, `
+${scanOut.trim()}
+`);
+      actions.push(`Added new host key for ${host}`);
+      return { status: "ok", message: `Host key refreshed for ${host}`, actions };
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      return { status: "error", message: `Scanned key but failed to write known_hosts: ${msg}`, actions };
+    }
   }
+  return { status: "error", message: `Could not scan host key for ${host}. Host may be unreachable.`, actions };
 }
-async function deleteFile(client, remotePath) {
-  const sftp = await getSftp(client);
-  try {
-    const stats = await new Promise((resolve, reject) => {
-      sftp.stat(remotePath, (err, stats2) => {
-        if (err) return reject(err);
-        resolve(stats2);
-      });
-    });
-    await new Promise((resolve, reject) => {
-      const done = (err) => err ? reject(err) : resolve();
-      if (stats.isDirectory()) {
-        sftp.rmdir(remotePath, done);
-      } else {
-        sftp.unlink(remotePath, done);
-      }
-    });
-  } finally {
-    sftp.end();
+function checkGitSsh(host = "github.com", user = "git") {
+  if (!isValidHostname(host)) {
+    return { status: "error", message: `Invalid hostname: "${host}"` };
+  }
+  const { stdout } = runArgs("ssh", ["-T", "-o", "ConnectTimeout=5", "-o", "BatchMode=yes", `${user}@${host}`]);
+  const text = stdout;
+  if (text.includes("successfully authenticated") || text.includes("Welcome to GitLab") || text.includes("logged in as")) {
+    const userMatch = text.match(/Hi (\S+)!/) || text.match(/@(\S+)!/) || text.match(/logged in as (\S+)/);
+    return {
+      status: "ok",
+      message: `Git SSH authentication to ${host} succeeded${userMatch ? ` as ${userMatch[1]}` : ""}`,
+      authenticatedAs: userMatch?.[1]
+    };
+  }
+  if (text.includes("Permission denied")) {
+    return {
+      status: "error",
+      message: `Permission denied for ${host}. Either no key is loaded in the agent or your key isn't registered with ${host}. Run ssh_key_list to check, then ssh_key_load if needed.`
+    };
+  }
+  if (text.includes("Connection refused")) {
+    return { status: "error", message: `Connection refused by ${host}. SSH may not be available on this host.` };
+  }
+  if (text.includes("timed out") || text.includes("Connection timed out")) {
+    return { status: "error", message: `Connection to ${host} timed out. Check your network or firewall.` };
+  }
+  if (text.includes("Could not resolve")) {
+    return { status: "error", message: `Could not resolve hostname "${host}". Check DNS or spelling.` };
   }
+  return { status: "error", message: `Git SSH check for ${host}: ${text || "no response (agent may not be running)"}` };
 }
-async function makeDir(client, remotePath, recursive = false) {
-  const sftp = await getSftp(client);
-  try {
-    const mkOne = (path) => new Promise((resolve, reject) => {
-      sftp.mkdir(path, (err) => err ? reject(err) : resolve());
-    });
-    if (!recursive) {
-      await mkOne(remotePath);
-      return;
-    }
-    const isAbsolute = remotePath.startsWith("/");
-    const parts = remotePath.split("/").filter(Boolean);
-    let cur = isAbsolute ? "" : ".";
-    for (let i = 0; i < parts.length; i++) {
-      cur = isAbsolute ? `${cur}/${parts[i]}` : `${cur}/${parts[i]}`;
-      const isLeaf = i === parts.length - 1;
-      try {
-        await mkOne(cur);
-      } catch (e) {
-        if (isLeaf) throw e;
-      }
-    }
-  } finally {
-    sftp.end();
+function testConnection(host, port = 22) {
+  if (!isValidHostname(host)) {
+    return { status: "error", message: `Invalid hostname: "${host}"` };
+  }
+  const { outcome, output, elapsedMs } = probeSshConnection(host, port);
+  switch (outcome) {
+    case "ok":
+      return { status: "ok", message: `Connected to ${host}:${port} in ${elapsedMs}ms` };
+    case "permission-denied":
+      return {
+        status: "error",
+        message: `Authentication failed to ${host}:${port} (${elapsedMs}ms). Key not authorized. Check: ssh-add -l, verify correct username, verify key is in remote authorized_keys.`
+      };
+    case "connection-refused":
+      return {
+        status: "error",
+        message: `Connection refused at ${host}:${port}. SSH server not running or port blocked.`
+      };
+    case "timed-out":
+      return { status: "error", message: `Connection timed out to ${host}:${port}. Host down or firewall blocking.` };
+    case "host-key-mismatch":
+      return {
+        status: "error",
+        message: `Host key mismatch for ${host}. Instance was likely recreated. Fix with ssh_known_hosts_fix.`
+      };
+    case "dns-failure":
+      return { status: "error", message: `Could not resolve "${host}". Check DNS, /etc/hosts, or SSH config.` };
+    default:
+      return { status: "error", message: `Connection failed to ${host}:${port}: ${output}` };
   }
 }
 
 // src/pool.ts
+import { createHash } from "crypto";
 function defaultMaxPoolSize() {
   const raw = process.env.SSH_MCP_MAX_POOL_SIZE;
   if (!raw) return 100;
@@ -1083,10 +1329,26 @@ function authFingerprint(cc) {
   }
   return h.digest("hex").slice(0, 16);
 }
+function resolveOrDiagnose(config) {
+  try {
+    return resolveConfig(config);
+  } catch (err) {
+    throw enhanceSshError(err, config.host);
+  }
+}
 var ConnectionPool = class {
   entries = /* @__PURE__ */ new Map();
   // Coalesces concurrent connect attempts for the same key so we don't open N
   // duplicate TCP connections when N tool calls fire simultaneously.
+  //
+  // The ResolvedConfig is stored alongside the promise because the coalesced dial
+  // runs with the FIRST caller's resolved: only that one's `hostVerifier` is ever
+  // invoked, so only that one's `hostKeyRejection` side channel records why the
+  // server's key was turned down. Waiters must report the failure from THAT resolved
+  // rather than their own (whose verifier never ran and whose rejection is still
+  // null), or one caller gets "the server offered an ed25519 key but known_hosts
+  // has only ecdsa" while the other N-1 get generic environment diagnostics for the
+  // very same failure.
   pending = /* @__PURE__ */ new Map();
   idleTtlMs;
   maxPoolSize;
@@ -1102,7 +1364,7 @@ var ConnectionPool = class {
     this.maxPoolSize = options?.maxPoolSize ?? defaultMaxPoolSize();
   }
   async acquire(config) {
-    const resolved = resolveConfig(config);
+    const resolved = resolveOrDiagnose(config);
     const cc = resolved.connectConfig;
     const key = `${cc.username}@${cc.host}:${cc.port}#${authFingerprint(cc)}`;
     const MAX_ACQUIRE_ATTEMPTS = 3;
@@ -1123,8 +1385,8 @@ var ConnectionPool = class {
       if (existing?.dead) {
         this.entries.delete(key);
       }
-      let pending = this.pending.get(key);
-      if (!pending) {
+      let inflight = this.pending.get(key);
+      if (!inflight) {
         if (this.entries.size >= this.maxPoolSize) {
           let evicted = false;
           for (const [k, e] of this.entries) {
@@ -1143,7 +1405,7 @@ var ConnectionPool = class {
             throw new Error(`Connection pool is full (${this.maxPoolSize} active connections)`);
           }
         }
-        pending = (async () => {
+        const promise = (async () => {
           try {
             const client2 = await connectWithProxy(resolved);
             if (this.drained) {
@@ -1174,23 +1436,14 @@ var ConnectionPool = class {
             this.pending.delete(key);
           }
         })();
-        this.pending.set(key, pending);
+        inflight = { promise, resolved };
+        this.pending.set(key, inflight);
       }
       let client;
       try {
-        client = await pending;
+        client = await inflight.promise;
       } catch (err) {
-        const diag = formatDiagnostics(config.host);
-        if (diag) {
-          const message = err instanceof Error ? err.message : String(err);
-          const enhanced = new Error(`${message}
-
-SSH Diagnostics:
-${diag}`);
-          enhanced.cause = err;
-          throw enhanced;
-        }
-        throw err;
+        throw enhanceSshError(err, config.host, inflight.resolved);
       }
       const entry = this.entries.get(key);
       if (!entry || entry.dead || entry.client !== client) {
@@ -1306,6 +1559,7 @@ async function multiExec(pool, hosts, command, timeoutMs = 3e4) {
   });
 }
 var VALID_FIND_SIZE = /^\d+[cwbkMG]?$/;
+var FIND_EXPRESSION_TOKENS = /* @__PURE__ */ new Set(["(", ")", "!", ","]);
 async function find(client, options, timeoutMs = 3e4) {
   if (options.minsize && !VALID_FIND_SIZE.test(options.minsize)) {
     throw new Error(
@@ -1317,7 +1571,8 @@ async function find(client, options, timeoutMs = 3e4) {
       `Invalid maxsize format: "${options.maxsize}". Expected: digits followed by optional c/w/b/k/M/G (e.g. "10M", "500k")`
     );
   }
-  const args = ["--", shellQuote(options.path)];
+  const pathOperand = options.path.startsWith("-") || FIND_EXPRESSION_TOKENS.has(options.path) ? `./${options.path}` : options.path;
+  const args = [shellQuote(pathOperand)];
   if (options.maxdepth !== void 0) args.push("-maxdepth", String(options.maxdepth));
   if (options.type) args.push("-type", options.type);
   if (options.name) args.push("-name", shellQuote(options.name));
@@ -1364,28 +1619,38 @@ async function serviceStatus(client, serviceName, timeoutMs = 3e4) {
 }
 
 // src/policy.ts
-function parsePatterns(raw) {
+function parsePatterns(raw, envVarName) {
   if (!raw) return [];
   const patterns = [];
+  const malformed = [];
   for (const p of raw.split(",")) {
     const cleaned = p.replace(/^\s+/, "");
     if (!cleaned) continue;
     try {
       patterns.push(new RegExp(cleaned));
     } catch {
+      malformed.push(cleaned);
       console.error(`ssh-mcp: ignoring malformed regex in command policy: "${cleaned}"`);
     }
   }
+  if (patterns.length === 0 && raw.trim() !== "") {
+    const detail = malformed.length > 0 ? `Malformed pattern(s): ${malformed.map((m) => `"${m}"`).join(", ")}.` : `The value ${JSON.stringify(raw)} contains only separators, so it declares no patterns.`;
+    throw new Error(
+      `Command blocked -- ssh-mcp command policy is MISCONFIGURED: ${envVarName} is set, but not one usable regex could be compiled from it, so ${envVarName} is NOT IN EFFECT. Every ssh_exec / ssh_multi_exec call is refused until it is fixed (failing closed: a policy that cannot be compiled must not be read as "no policy"). ${detail} Each comma-separated entry must be a valid JavaScript regex -- note that comma is the delimiter, so a pattern needing a literal comma must write it as \\x2c or [,]. Fix or unset the variable to restore service.`
+    );
+  }
   return patterns;
 }
-function enforcePolicy(command) {
-  const whitelist = parsePatterns(process.env.SSH_MCP_COMMAND_WHITELIST);
+function enforcePolicy(command, context = {}) {
+  const whitelist = parsePatterns(process.env.SSH_MCP_COMMAND_WHITELIST, "SSH_MCP_COMMAND_WHITELIST");
+  const blacklist = parsePatterns(process.env.SSH_MCP_COMMAND_BLACKLIST, "SSH_MCP_COMMAND_BLACKLIST");
   if (whitelist.length > 0 && !whitelist.some((r) => r.test(command))) {
-    throw new Error(
-      `Command blocked: does not match any pattern in SSH_MCP_COMMAND_WHITELIST. Configured patterns: ${whitelist.map((r) => r.source).join(", ")}`
-    );
+    let message = `Command blocked: does not match any pattern in SSH_MCP_COMMAND_WHITELIST. Configured patterns: ${whitelist.map((r) => r.source).join(", ")}`;
+    if (context.envPrefixApplied) {
+      message += ". NOTE: an `env` prefix was applied, and policy is checked against the PREFIXED command -- the string starts with the first `KEY='value'` assignment, not the command verb, so a `^`-anchored pattern that matches without `env` stops matching with it. Either set the variables inside the command string instead of passing `env`, or add a pattern that tolerates the prefix (e.g. `^([A-Za-z_][A-Za-z0-9_]*=(?:'[^']*'|\\\\')+ )*ls( |$)`). Keep the trailing `( |$)`: without a tail anchor the suggestion is a PREFIX match, so `^(...)*ls` would also admit `lsof -i` and `ls; <anything>`. The value group is `(?:'[^']*'|\\\\')+`, not `'[^']*'`: an env VALUE containing an apostrophe is emitted by shellQuote in the close-escape-reopen form (`O'Brien` -> `'O'\\''Brien'`), which a single `'[^']*'` cannot match -- a suggestion built on it would block exactly the calls it claims to allow.";
+    }
+    throw new Error(message);
   }
-  const blacklist = parsePatterns(process.env.SSH_MCP_COMMAND_BLACKLIST);
   for (const pattern of blacklist) {
     if (pattern.test(command)) {
       throw new Error(`Command blocked by SSH_MCP_COMMAND_BLACKLIST: pattern "${pattern.source}"`);
@@ -1405,6 +1670,9 @@ var PasswordSchema = z.string().optional().describe(
   "SSH password. STRONGLY prefer key-based auth (privateKeyPath or ssh-agent). Passwords pass through MCP protocol frames as plaintext and may be logged by the transport or host process."
 );
 var TimeoutSchema = z.number().int().positive().optional().describe("Command timeout in milliseconds (default: 30000)");
+var EnvSchema = z.record(z.string(), z.string()).optional().describe(
+  "Environment variables to set for this command. Injected as a `KEY='value' ...` prefix; works on any sshd regardless of AcceptEnv config. VALUES are POSIX-single-quoted, so any byte is safe in a value. KEYS cannot be quoted (a shell assignment prefix requires a bare name), so each key must match /^[A-Za-z_][A-Za-z0-9_]*$/ (the POSIX name grammar) \u2014 a key outside that grammar is rejected and the call fails before anything is sent to a host. Command policy is checked against the PREFIXED command, so a `^`-anchored whitelist pattern stops matching once this is set."
+);
 var connectionParams = {
   host: HostSchema,
   port: PortSchema,
@@ -1412,6 +1680,22 @@ var connectionParams = {
   privateKeyPath: KeyPathSchema,
   password: PasswordSchema
 };
+var POLICY_EXEMPT_NOTE = " NOT gated by SSH_MCP_COMMAND_WHITELIST / SSH_MCP_COMMAND_BLACKLIST: command policy applies only to ssh_exec and ssh_multi_exec, so a blacklist such as `^rm` does NOT block this tool.";
+var ENV_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function applyEnvPrefix(command, env) {
+  if (!env || Object.keys(env).length === 0) {
+    return { finalCommand: command, envPrefixApplied: false };
+  }
+  const prefix = Object.entries(env).map(([k, v]) => {
+    if (!ENV_NAME_PATTERN.test(k)) {
+      throw new Error(
+        `Invalid environment variable name ${JSON.stringify(k)}: env keys must match ${ENV_NAME_PATTERN.source} (the POSIX name grammar). Values are single-quoted before they reach the remote shell, but a key is emitted as a bare \`KEY=\` assignment and cannot be quoted, so anything outside that grammar is rejected instead of escaped.`
+      );
+    }
+    return `${k}=${shellQuote(v)}`;
+  }).join(" ");
+  return { finalCommand: `${prefix} ${command}`, envPrefixApplied: true };
+}
 function registerTools(server, pool) {
   const connectionPool = pool ?? new ConnectionPool();
   server.tool(
@@ -1420,18 +1704,12 @@ function registerTools(server, pool) {
     {
       ...connectionParams,
       command: z.string().describe("Shell command to execute on the remote host (interpreted by the remote login shell)"),
-      env: z.record(z.string(), z.string()).optional().describe(
-        "Environment variables to set for this command. Injected as a `KEY='value' ...` prefix; works on any sshd regardless of AcceptEnv config. Values are POSIX-single-quoted, so any byte is safe."
-      ),
+      env: EnvSchema,
       timeout: TimeoutSchema
     },
     async ({ command, env, timeout, ...conn }) => {
-      let finalCommand = command;
-      if (env && Object.keys(env).length > 0) {
-        const prefix = Object.entries(env).map(([k, v]) => `${k}=${shellQuote(v)}`).join(" ");
-        finalCommand = `${prefix} ${command}`;
-      }
-      enforcePolicy(finalCommand);
+      const { finalCommand, envPrefixApplied } = applyEnvPrefix(command, env);
+      enforcePolicy(finalCommand, { envPrefixApplied });
       return connectionPool.withConnection(conn, async (client) => {
         const result = await exec(client, finalCommand, timeout || 3e4);
         const parts = [];
@@ -1462,7 +1740,7 @@ ${result.stderr}`);
   );
   server.tool(
     "ssh_write_file",
-    "Write content to a file on a remote host via SFTP. Creates or overwrites the file.",
+    `Write content to a file on a remote host via SFTP. Creates or overwrites the file.${POLICY_EXEMPT_NOTE}`,
     {
       ...connectionParams,
       path: AbsoluteRemotePathSchema.describe("Absolute path to the remote file. Must start with /."),
@@ -1471,13 +1749,14 @@ ${result.stderr}`);
     async ({ path, content, ...conn }) => {
       return connectionPool.withConnection(conn, async (client) => {
         await writeFile(client, path, content);
-        return { content: [{ type: "text", text: `Wrote ${content.length} bytes to ${path}` }] };
+        const bytes = Buffer.byteLength(content, "utf8");
+        return { content: [{ type: "text", text: `Wrote ${bytes} bytes to ${path}` }] };
       });
     }
   );
   server.tool(
     "ssh_upload",
-    "Upload a local file to a remote host via SFTP.",
+    `Upload a local file to a remote host via SFTP.${POLICY_EXEMPT_NOTE}`,
     {
       ...connectionParams,
       localPath: z.string().describe("Path to the local file to upload"),
@@ -1515,13 +1794,16 @@ ${result.stderr}`);
     async ({ path, ...conn }) => {
       return connectionPool.withConnection(conn, async (client) => {
         const files = await listDir(client, path);
+        if (files.length === 0) {
+          return { content: [{ type: "text", text: `Directory is empty: ${path}` }] };
+        }
         return { content: [{ type: "text", text: files.join("\n") }] };
       });
     }
   );
   server.tool(
     "ssh_stat",
-    "Get metadata for a file or directory on a remote host via SFTP. Returns size, permissions (octal), uid/gid, mtime/atime, and type flags (isFile, isDirectory, isSymbolicLink). Use this instead of parsing `ls -la` output.",
+    "Get metadata for a file or directory on a remote host via SFTP. Returns size, permissions (octal), uid/gid, mtime/atime, and the path type. Symlinks are reported as `symlink -> <target kind>`: the type describes the link itself while size/mode/mtime describe its TARGET, and a dangling symlink is reported rather than erroring. Use this instead of parsing `ls -la` output.",
     {
       ...connectionParams,
       path: AbsoluteRemotePathSchema.describe("Absolute path to the remote file or directory. Must start with /.")
@@ -1530,7 +1812,8 @@ ${result.stderr}`);
       return connectionPool.withConnection(conn, async (client) => {
         const stats = await statFile(client, path);
         const lines = [];
-        const kind = stats.isDirectory ? "directory" : stats.isSymbolicLink ? "symlink" : stats.isFile ? "file" : "other";
+        const targetKind = stats.isDirectory ? "directory" : stats.isFile ? "file" : "other";
+        const kind = stats.isSymbolicLink ? `symlink -> ${targetKind}` : targetKind;
         lines.push(`${path}: ${kind}`);
         lines.push(`  Size: ${stats.size} bytes`);
         lines.push(`  Mode: ${stats.modeOctal}`);
@@ -1543,10 +1826,12 @@ ${result.stderr}`);
   );
   server.tool(
     "ssh_mkdir",
-    "Create a directory on a remote host via SFTP. Set `recursive: true` to create parent directories as needed (like `mkdir -p`). Existing intermediate dirs are tolerated; an existing leaf path is still an error.",
+    `Create a directory on a remote host via SFTP. Set \`recursive: true\` to create parent directories as needed (like \`mkdir -p\`). Existing intermediate dirs are tolerated; an existing leaf path is still an error. Unlike the other SFTP tools, the path may be relative.${POLICY_EXEMPT_NOTE}`,
     {
       ...connectionParams,
-      path: z.string().describe("Absolute path of the directory to create"),
+      path: z.string().describe(
+        "Path of the directory to create. Absolute (starting with /) is recommended and unambiguous. A relative path is also accepted and resolves against the SFTP working directory, which is normally the remote user's home. ~ is NOT expanded \u2014 SFTP has no shell to expand it."
+      ),
       recursive: z.boolean().optional().describe("Create parent directories as needed (default: false). Like `mkdir -p`.")
     },
     async ({ path, recursive, ...conn }) => {
@@ -1558,7 +1843,7 @@ ${result.stderr}`);
   );
   server.tool(
     "ssh_delete",
-    "Delete a file or empty directory on a remote host via SFTP. Auto-detects the path type and calls the right SFTP op (unlink for files/symlinks, rmdir for empty dirs). Recursive directory delete is intentionally NOT supported -- for that, use ssh_exec with `rm -rf` explicitly so the destructive intent is visible in the tool trace.",
+    `Delete a file or empty directory on a remote host via SFTP. Auto-detects the path type and calls the right SFTP op (unlink for files/symlinks, rmdir for empty dirs). Recursive directory delete is intentionally NOT supported -- for that, use ssh_exec with \`rm -rf\` explicitly so the destructive intent is visible in the tool trace.${POLICY_EXEMPT_NOTE}`,
     {
       ...connectionParams,
       path: AbsoluteRemotePathSchema.describe(
@@ -1623,10 +1908,33 @@ ${result.stderr}`);
   );
   server.tool(
     "ssh_key_list",
-    "List all SSH private keys in ~/.ssh/ with their type, fingerprint, and whether they are loaded in the agent. Use this to find which keys are available and which ones need to be loaded.",
+    "List all SSH private keys in ~/.ssh/ with their type, fingerprint, and whether they are loaded in the agent. Use this to find which keys are available and which ones need to be loaded. Reports isError only when ~/.ssh exists but could not be read -- an absent or empty ~/.ssh is a successful answer with a ssh-keygen hint.",
     {},
     async () => {
-      const keys = listSshKeys();
+      const listing = listSshKeysDetailed();
+      if (listing.status === "unreadable") {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Could not read ${listing.dir}: ${listing.reason}. This is NOT "no keys" -- the directory exists but could not be listed. Check that it is a directory and that you own it: ls -ld ${listing.dir}, then chmod 700 ${listing.dir}.`
+            }
+          ],
+          isError: true
+        };
+      }
+      if (listing.status === "no-dir") {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `No ~/.ssh directory yet (${listing.dir} does not exist). Generate a key to create it: ssh-keygen -t ed25519 -C "your@email.com"`
+            }
+          ],
+          isError: false
+        };
+      }
+      const keys = listing.keys;
       if (keys.length === 0) {
         return {
           content: [
@@ -1634,7 +1942,8 @@ ${result.stderr}`);
               type: "text",
               text: 'No SSH private keys found in ~/.ssh/. Generate one: ssh-keygen -t ed25519 -C "your@email.com"'
             }
-          ]
+          ],
+          isError: false
         };
       }
       const lines = [`Found ${keys.length} SSH key(s):`, ""];
@@ -1645,7 +1954,7 @@ ${result.stderr}`);
         if (key.fingerprint) lines.push(`  Fingerprint: ${key.fingerprint}`);
         lines.push("");
       }
-      return { content: [{ type: "text", text: lines.join("\n") }] };
+      return { content: [{ type: "text", text: lines.join("\n") }], isError: false };
     }
   );
   server.tool(
@@ -1716,8 +2025,13 @@ ${result.stderr}`);
     "ssh_git_check",
     "Test Git-over-SSH authentication to a hosting provider (GitHub, GitLab, Bitbucket, etc). Verifies your SSH key is registered and working. Use this when git clone/pull/push fails with SSH errors.",
     {
-      host: z.string().optional().describe('Git hosting hostname (default: "github.com")'),
-      user: z.string().optional().describe('SSH user for the git host (default: "git")')
+      // .min(1), not a bare optional string: the handler defaults with `host || "github.com"`,
+      // so an explicitly-empty host would silently probe github.com and report on a host the
+      // caller never named -- and, because "" never reaches checkGitSsh, it would skip the
+      // isValidHostname check every other host-taking tool routes its input through. Omitting
+      // the field is the way to ask for the default; "" is rejected at the schema boundary.
+      host: z.string().min(1, "host must not be empty. Omit it to use the default (github.com).").optional().describe('Git hosting hostname (default: "github.com"). Omit for the default; an empty string is rejected.'),
+      user: z.string().min(1, "user must not be empty. Omit it to use the default (git).").optional().describe('SSH user for the git host (default: "git"). Omit for the default; an empty string is rejected.')
     },
     async ({ host, user }) => {
       const result = checkGitSsh(host || "github.com", user || "git");
@@ -1730,7 +2044,7 @@ ${result.stderr}`);
   );
   server.tool(
     "ssh_multi_exec",
-    "Execute a command on multiple remote hosts in parallel. Returns results per host. Use this instead of calling ssh_exec multiple times \u2014 it's faster and shows results side by side. Subject to SSH_MCP_COMMAND_WHITELIST / SSH_MCP_COMMAND_BLACKLIST if configured (policy is checked once before fan-out).",
+    "Execute a command on multiple remote hosts in parallel. Returns results per host. Use this instead of calling ssh_exec multiple times \u2014 it's faster and shows results side by side. Use `env` to set environment variables for this call without modifying the command string. Subject to SSH_MCP_COMMAND_WHITELIST / SSH_MCP_COMMAND_BLACKLIST if configured (policy is checked once, against the env-prefixed command, before fan-out).",
     {
       hosts: z.array(z.string()).describe("List of SSH hostnames or IPs"),
       command: z.string().describe("Shell command to execute on all hosts"),
@@ -1738,12 +2052,14 @@ ${result.stderr}`);
       username: UsernameSchema,
       privateKeyPath: KeyPathSchema,
       password: PasswordSchema,
+      env: EnvSchema,
       timeout: TimeoutSchema
     },
-    async ({ hosts, command, port, username, privateKeyPath, password, timeout }) => {
-      enforcePolicy(command);
+    async ({ hosts, command, port, username, privateKeyPath, password, env, timeout }) => {
+      const { finalCommand, envPrefixApplied } = applyEnvPrefix(command, env);
+      enforcePolicy(finalCommand, { envPrefixApplied });
       const hostConfigs = hosts.map((host) => ({ host, port, username, privateKeyPath, password }));
-      const results = await multiExec(connectionPool, hostConfigs, command, timeout || 3e4);
+      const results = await multiExec(connectionPool, hostConfigs, finalCommand, timeout || 3e4);
       const lines = [];
       for (const r of results) {
         lines.push(`--- ${r.host} ---`);
@@ -1752,6 +2068,7 @@ ${result.stderr}`);
         } else {
           if (r.stdout) lines.push(r.stdout);
           if (r.stderr) lines.push(`[stderr] ${r.stderr}`);
+          if (r.signal) lines.push(`[signal: ${r.signal}]`);
           lines.push(`[exit code: ${r.code}]`);
         }
         lines.push("");
@@ -1803,7 +2120,7 @@ ${files.join("\n")}` }] };
             content: [
               {
                 type: "text",
-                text: grep ? `No lines matching "${grep}" in last ${lines || 100} lines.` : "File is empty or does not exist."
+                text: grep ? `No lines matching "${grep}" in last ${lines || 100} lines.` : "File is empty (no content in the last lines read; whitespace-only counts as empty here)."
               }
             ]
           };