@yawlabs/ssh-mcp 0.16.0 → 0.17.0

package/dist/server.js

@@ -1317,137 +1317,31 @@ function testConnection(host, port = 22) {
   }
 }
 
-// src/ops.ts
-function shellQuote(s) {
-  return `'${s.replace(/'/g, "'\\''")}'`;
-}
-async function multiExec(pool, hosts, command, timeoutMs = 3e4) {
-  const results = await Promise.allSettled(
-    hosts.map(async (hostConfig) => {
-      return pool.withConnection(hostConfig, async (client) => {
-        const result = await exec(client, command, timeoutMs);
-        return { host: hostConfig.host, ...result };
-      });
-    })
-  );
-  return results.map((result, i) => {
-    if (result.status === "fulfilled") {
-      return result.value;
-    }
-    return {
-      host: hosts[i].host,
-      stdout: "",
-      stderr: "",
-      code: -1,
-      error: result.reason instanceof Error ? result.reason.message : String(result.reason)
-    };
-  });
-}
-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(
-      `Invalid minsize format: "${options.minsize}". Expected: digits followed by optional c/w/b/k/M/G (e.g. "1M", "100k")`
-    );
-  }
-  if (options.maxsize && !VALID_FIND_SIZE.test(options.maxsize)) {
-    throw new Error(
-      `Invalid maxsize format: "${options.maxsize}". Expected: digits followed by optional c/w/b/k/M/G (e.g. "10M", "500k")`
-    );
-  }
-  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));
-  if (options.minsize) args.push("-size", `+${options.minsize}`);
-  if (options.maxsize) args.push("-size", `-${options.maxsize}`);
-  if (options.newer) args.push("-newer", shellQuote(options.newer));
-  const command = `find ${args.join(" ")}`;
-  const result = await exec(client, command, timeoutMs);
-  if (!result.stdout.trim() && result.stderr.trim()) {
-    throw new Error(result.stderr.trim());
-  }
-  return result.stdout.split("\n").filter(Boolean);
-}
-async function tail(client, path, lines = 100, grep, timeoutMs = 3e4) {
-  let command = `tail -n ${lines} -- ${shellQuote(path)}`;
-  if (grep) {
-    command += ` | grep -i -e ${shellQuote(grep)}`;
-  }
-  const result = await exec(client, command, timeoutMs);
-  if (result.stderr.trim()) {
-    throw new Error(result.stderr.trim());
-  }
-  return result.stdout;
-}
-async function serviceStatus(client, serviceName, timeoutMs = 3e4) {
-  const result = await exec(client, `systemctl status -- ${shellQuote(serviceName)} 2>&1`, timeoutMs);
-  const raw = result.stdout;
-  const activeMatch = raw.match(/Active:\s+(\S+)\s+\(([^)]+)\)/);
-  const descMatch = raw.match(/^[^\w\n]*\S+\s+-\s+(.+)$/m);
-  const pidMatch = raw.match(/Main PID:\s+(\d+)/);
-  const sinceMatch = raw.match(/since\s+(.+?);/);
-  const unknown = !activeMatch && result.code !== 0;
-  const fallbackStatus = result.code === 0 ? "active" : "inactive";
-  return {
-    name: serviceName,
-    active: activeMatch?.[1] === "active",
-    status: activeMatch ? `${activeMatch[1]} (${activeMatch[2]})` : fallbackStatus,
-    description: descMatch?.[1]?.trim(),
-    since: sinceMatch?.[1]?.trim(),
-    pid: pidMatch ? Number.parseInt(pidMatch[1], 10) : void 0,
-    raw,
-    unknown
-  };
-}
-
-// src/policy.ts
-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.`
+// src/pool.ts
+import { createHash } from "crypto";
+var POOL_FULL_ERROR_CODE = "ERR_SSH_MCP_POOL_FULL";
+var PoolFullError = class extends Error {
+  code = POOL_FULL_ERROR_CODE;
+  maxPoolSize;
+  waitedMs;
+  constructor(maxPoolSize, waitedMs) {
+    const base = `Connection pool is full (${maxPoolSize} connections in use or dialing, the SSH_MCP_MAX_POOL_SIZE cap)`;
+    super(
+      waitedMs === void 0 ? base : (
+        // "became available to this call", not "freed up": every capacity signal wakes every
+        // parked caller, so a slot can free during the wait and still go to someone else.
+        `${base}; no slot became available to this call within ${Math.round(waitedMs)}ms. Retry once the calls holding the slots finish, or raise the cap (SSH_MCP_MAX_POOL_SIZE in the MCP server's environment).`
+      )
     );
+    this.name = "PoolFullError";
+    this.maxPoolSize = maxPoolSize;
+    if (waitedMs !== void 0) this.waitedMs = waitedMs;
   }
-  return patterns;
-}
-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))) {
-    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);
-  }
-  for (const pattern of blacklist) {
-    if (pattern.test(command)) {
-      throw new Error(`Command blocked by SSH_MCP_COMMAND_BLACKLIST: pattern "${pattern.source}"`);
-    }
-  }
-}
-function isPolicyConfigured() {
-  return Boolean(process.env.SSH_MCP_COMMAND_WHITELIST?.trim() || process.env.SSH_MCP_COMMAND_BLACKLIST?.trim());
+};
+function isPoolFullError(err) {
+  return typeof err === "object" && err !== null && err.code === POOL_FULL_ERROR_CODE;
 }
-
-// src/pool.ts
-import { createHash } from "crypto";
+var MAX_TIMER_MS = 2147483647;
 function defaultMaxPoolSize() {
   const raw = process.env.SSH_MCP_MAX_POOL_SIZE;
   if (!raw) return 100;
@@ -1500,11 +1394,42 @@ var ConnectionPool = class {
   // factory closes the freshly-connected client instead of registering it.
   // Consumers must construct a new pool to use again.
   drained = false;
+  // Callers parked in waitForCapacity(). Every site that can free a slot for a NEW key calls
+  // notifyCapacity(), which wakes all of them: an entry dropping to refCount 0 (it becomes
+  // evictable), an entry leaving the map (markDead, idle expiry), a dial failing without
+  // registering, and drain(). Waking all rather than one means a woken caller that does not
+  // take the slot (its retry fails for another reason, or joins a same-key dial) cannot
+  // strand the rest; the losers of a wake just find the pool full again and re-park.
+  capacityWaiters = /* @__PURE__ */ new Set();
   constructor(options) {
     this.idleTtlMs = options?.idleTtlMs ?? 6e4;
     this.maxPoolSize = options?.maxPoolSize ?? defaultMaxPoolSize();
   }
-  async acquire(config) {
+  /**
+   * Checks out a connection for `config`, dialing one if needed. Fails fast on a full pool
+   * unless `options.waitForCapacityMs` is set, in which case the caller parks and retries on
+   * every capacity signal until it wins a slot or the budget is spent. The wait is bounded,
+   * never a reservation: a woken caller can lose the slot to another and simply parks again
+   * for whatever budget is left. The final rejection carries the budget in its message.
+   */
+  async acquire(config, options) {
+    const budgetMs = options?.waitForCapacityMs ?? 0;
+    if (!(budgetMs > 0)) return this.acquireNow(config);
+    const deadline = performance.now() + budgetMs;
+    for (; ; ) {
+      try {
+        return await this.acquireNow(config);
+      } catch (err) {
+        if (!isPoolFullError(err)) throw err;
+        const remaining = deadline - performance.now();
+        if (remaining <= 0) throw new PoolFullError(this.maxPoolSize, budgetMs);
+        await this.waitForCapacity(remaining);
+      }
+    }
+  }
+  // The fail-fast acquire: one admission check, one dial (or a join on an in-flight one).
+  async acquireNow(config) {
+    if (this.drained) throw new Error("ConnectionPool was drained");
     const resolved = resolveOrDiagnose(config);
     const cc = resolved.connectConfig;
     const key = `${cc.username}@${cc.host}:${cc.port}#${authFingerprint(cc)}`;
@@ -1528,25 +1453,20 @@ var ConnectionPool = class {
       }
       let inflight = this.pending.get(key);
       if (!inflight) {
-        if (this.entries.size >= this.maxPoolSize) {
-          let evicted = false;
-          for (const [k, e] of this.entries) {
-            if (e.refCount === 0) {
-              if (e.idleTimer) clearTimeout(e.idleTimer);
-              try {
-                e.client.end();
-              } catch {
-              }
-              this.entries.delete(k);
-              evicted = true;
-              break;
-            }
+        if (this.entries.size + this.pending.size >= this.maxPoolSize) {
+          const victim = this.findEvictable();
+          if (!victim) {
+            throw new PoolFullError(this.maxPoolSize);
           }
-          if (!evicted) {
-            throw new Error(`Connection pool is full (${this.maxPoolSize} active connections)`);
+          if (victim.idleTimer) clearTimeout(victim.idleTimer);
+          try {
+            victim.client.end();
+          } catch {
           }
+          this.entries.delete(victim.key);
         }
         const promise = (async () => {
+          let registered = false;
           try {
             const client2 = await connectWithProxy(resolved);
             if (this.drained) {
@@ -1566,15 +1486,18 @@ var ConnectionPool = class {
               }
               if (this.entries.get(key) === entry2) {
                 this.entries.delete(key);
+                this.notifyCapacity();
               }
             };
             client2.on("close", markDead);
             client2.on("end", markDead);
             client2.on("error", markDead);
             this.entries.set(key, entry2);
+            registered = true;
             return client2;
           } finally {
             this.pending.delete(key);
+            if (!registered) this.notifyCapacity();
           }
         })();
         inflight = { promise, resolved };
@@ -1613,8 +1536,10 @@ var ConnectionPool = class {
             } catch {
             }
             this.entries.delete(entry.key);
+            this.notifyCapacity();
           }, this.idleTtlMs);
           entry.idleTimer.unref();
+          this.notifyCapacity();
         }
         return;
       }
@@ -1624,8 +1549,9 @@ var ConnectionPool = class {
     } catch {
     }
   }
-  async withConnection(config, fn) {
-    const client = await this.acquire(config);
+  /** `acquire()` + `fn` + `release()`, with the same optional bounded wait for a slot. */
+  async withConnection(config, fn, options) {
+    const client = await this.acquire(config, options);
     try {
       return await fn(client);
     } finally {
@@ -1645,10 +1571,81 @@ var ConnectionPool = class {
     }
     this.entries.clear();
     this.pending.clear();
+    this.notifyCapacity();
+  }
+  /**
+   * Parks until the pool's capacity may have changed, for a caller whose `acquire()` just
+   * rejected with a {@link PoolFullError} and that would rather wait than fail. This is the
+   * primitive behind `acquire()`'s `waitForCapacityMs` option; a bare `acquire()` never waits.
+   *
+   * Resolves `true` when a slot may be free (woken by a release, an entry closing or expiring,
+   * a failed dial, or `drain()`), or at once if a new host would fit right now or the pool is
+   * already drained. Resolves `false` after `timeoutMs` with nothing having changed. Never
+   * rejects. A `true` is a hint, not a reservation: another caller can take the slot first,
+   * so retry `acquire()` and wait again on another `PoolFullError`. The timer is cleared on
+   * wake and unref'd, so a parked caller never holds the process open.
+   *
+   * Aborting `signal` ends the park early with `false`, as if the timer had run out; an
+   * already-aborted signal resolves `false` without parking, unless the pool is drained or a
+   * new host would fit right now. A wake that lands first still resolves `true`. A caller that
+   * gives up on its own (`ssh_multi_exec` declaring the call starved) aborts rather than racing
+   * this promise against another: the race would add a promise hop to every wake.
+   */
+  waitForCapacity(timeoutMs, signal) {
+    return new Promise((resolve) => {
+      let timer;
+      const settle = (woken) => {
+        if (timer !== void 0) clearTimeout(timer);
+        this.capacityWaiters.delete(wake);
+        signal?.removeEventListener("abort", abort);
+        resolve(woken);
+      };
+      const wake = () => settle(true);
+      const abort = () => settle(false);
+      this.capacityWaiters.add(wake);
+      if (this.drained) {
+        wake();
+        return;
+      }
+      if (this.hasCapacity()) {
+        wake();
+        return;
+      }
+      if (!(timeoutMs > 0) || signal?.aborted) {
+        abort();
+        return;
+      }
+      timer = setTimeout(abort, Math.min(timeoutMs, MAX_TIMER_MS));
+      timer.unref();
+      signal?.addEventListener("abort", abort, { once: true });
+    });
+  }
+  // acquireNow()'s admission test for a new key: below the cap, or an entry to evict.
+  hasCapacity() {
+    return this.entries.size + this.pending.size < this.maxPoolSize || this.findEvictable() !== void 0;
+  }
+  // The eviction rule, in one place: the first entry (insertion order) no caller holds. Both
+  // acquireNow()'s eviction and hasCapacity() read it, so waitForCapacity's re-check can never
+  // disagree with what an acquire would actually evict.
+  findEvictable() {
+    for (const e of this.entries.values()) {
+      if (e.refCount === 0) return e;
+    }
+    return void 0;
+  }
+  notifyCapacity() {
+    if (this.capacityWaiters.size === 0) return;
+    const waiters = [...this.capacityWaiters];
+    this.capacityWaiters.clear();
+    for (const wake of waiters) wake();
   }
   get size() {
     return this.entries.size;
   }
+  /** The connection cap (`maxPoolSize`), counting pooled entries plus in-flight dials. */
+  get maxSize() {
+    return this.maxPoolSize;
+  }
   get stats() {
     let active = 0;
     let idle = 0;
@@ -1664,6 +1661,192 @@ var ConnectionPool = class {
   }
 };
 
+// src/ops.ts
+function shellQuote(s) {
+  return `'${s.replace(/'/g, "'\\''")}'`;
+}
+async function multiExec(pool, hosts, command, timeoutMs = 3e4) {
+  const cap = pool.maxSize;
+  const limit = typeof cap === "number" && cap >= 1 ? Math.min(hosts.length, Math.floor(cap)) : hosts.length;
+  let lastProgressAt = performance.now();
+  let starvedError;
+  const starvation = new AbortController();
+  let running = 0;
+  let parked = 0;
+  const canWait = typeof pool.waitForCapacity === "function";
+  const freshBudgetMs = timeoutMs >= 1 ? timeoutMs : 1;
+  const errorResult = (host, error) => ({
+    host,
+    stdout: "",
+    stderr: "",
+    code: -1,
+    error
+  });
+  const runHost = async (hostConfig) => {
+    for (; ; ) {
+      if (starvedError !== void 0) return errorResult(hostConfig.host, starvedError);
+      let rejection;
+      try {
+        return await pool.withConnection(hostConfig, async (client) => {
+          lastProgressAt = performance.now();
+          try {
+            const result = await exec(client, command, timeoutMs);
+            return { host: hostConfig.host, ...result };
+          } finally {
+            lastProgressAt = performance.now();
+          }
+        });
+      } catch (reason) {
+        if (!isPoolFullError(reason)) {
+          lastProgressAt = performance.now();
+          return errorResult(hostConfig.host, reason instanceof Error ? reason.message : String(reason));
+        }
+        if (!canWait) return errorResult(hostConfig.host, reason.message);
+        rejection = reason;
+      }
+      for (; ; ) {
+        if (starvedError !== void 0) return errorResult(hostConfig.host, starvedError);
+        const remaining = lastProgressAt + timeoutMs - performance.now();
+        let waitMs;
+        if (remaining > 0) {
+          waitMs = Math.ceil(remaining);
+        } else if (running - parked > 1) {
+          waitMs = freshBudgetMs;
+        } else {
+          starvedError ??= new PoolFullError(rejection.maxPoolSize, timeoutMs).message;
+          starvation.abort();
+          return errorResult(hostConfig.host, starvedError);
+        }
+        parked++;
+        let woken;
+        try {
+          woken = await pool.waitForCapacity(waitMs, starvation.signal);
+        } finally {
+          parked--;
+        }
+        if (woken) break;
+      }
+    }
+  };
+  const results = new Array(hosts.length);
+  let next = 0;
+  const worker = async () => {
+    running++;
+    try {
+      while (next < hosts.length) {
+        const i = next++;
+        results[i] = await runHost(hosts[i]);
+      }
+    } finally {
+      running--;
+    }
+  };
+  await Promise.all(Array.from({ length: limit }, worker));
+  return results;
+}
+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(
+      `Invalid minsize format: "${options.minsize}". Expected: digits followed by optional c/w/b/k/M/G (e.g. "1M", "100k")`
+    );
+  }
+  if (options.maxsize && !VALID_FIND_SIZE.test(options.maxsize)) {
+    throw new Error(
+      `Invalid maxsize format: "${options.maxsize}". Expected: digits followed by optional c/w/b/k/M/G (e.g. "10M", "500k")`
+    );
+  }
+  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));
+  if (options.minsize) args.push("-size", `+${options.minsize}`);
+  if (options.maxsize) args.push("-size", `-${options.maxsize}`);
+  if (options.newer) args.push("-newer", shellQuote(options.newer));
+  const command = `find ${args.join(" ")}`;
+  const result = await exec(client, command, timeoutMs);
+  if (!result.stdout.trim() && result.stderr.trim()) {
+    throw new Error(result.stderr.trim());
+  }
+  return result.stdout.split("\n").filter(Boolean);
+}
+async function tail(client, path, lines = 100, grep, timeoutMs = 3e4) {
+  let command = `tail -n ${lines} -- ${shellQuote(path)}`;
+  if (grep) {
+    command += ` | grep -i -e ${shellQuote(grep)}`;
+  }
+  const result = await exec(client, command, timeoutMs);
+  if (result.stderr.trim()) {
+    throw new Error(result.stderr.trim());
+  }
+  return result.stdout;
+}
+async function serviceStatus(client, serviceName, timeoutMs = 3e4) {
+  const result = await exec(client, `systemctl status -- ${shellQuote(serviceName)} 2>&1`, timeoutMs);
+  const raw = result.stdout;
+  const activeMatch = raw.match(/Active:\s+(\S+)\s+\(([^)]+)\)/);
+  const descMatch = raw.match(/^[^\w\n]*\S+\s+-\s+(.+)$/m);
+  const pidMatch = raw.match(/Main PID:\s+(\d+)/);
+  const sinceMatch = raw.match(/since\s+(.+?);/);
+  const unknown = !activeMatch && result.code !== 0;
+  const fallbackStatus = result.code === 0 ? "active" : "inactive";
+  return {
+    name: serviceName,
+    active: activeMatch?.[1] === "active",
+    status: activeMatch ? `${activeMatch[1]} (${activeMatch[2]})` : fallbackStatus,
+    description: descMatch?.[1]?.trim(),
+    since: sinceMatch?.[1]?.trim(),
+    pid: pidMatch ? Number.parseInt(pidMatch[1], 10) : void 0,
+    raw,
+    unknown
+  };
+}
+
+// src/policy.ts
+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, 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))) {
+    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);
+  }
+  for (const pattern of blacklist) {
+    if (pattern.test(command)) {
+      throw new Error(`Command blocked by SSH_MCP_COMMAND_BLACKLIST: pattern "${pattern.source}"`);
+    }
+  }
+}
+function isPolicyConfigured() {
+  return Boolean(process.env.SSH_MCP_COMMAND_WHITELIST?.trim() || process.env.SSH_MCP_COMMAND_BLACKLIST?.trim());
+}
+
 // src/tools.ts
 var HostSchema = z.string().describe("SSH hostname or IP address");
 var AbsoluteRemotePathSchema = z.string().refine((p) => p.startsWith("/"), {
@@ -1675,7 +1858,9 @@ var KeyPathSchema = z.string().optional().describe("Path to SSH private key");
 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 TimeoutSchema = z.number().int().positive().optional().describe(
+  "Command timeout in milliseconds (default: 30000). Also the longest the call waits for a free connection-pool slot (SSH_MCP_MAX_POOL_SIZE, default 100) before the command starts; the wait and the command are bounded separately."
+);
 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."
 );
@@ -1686,6 +1871,9 @@ var connectionParams = {
   privateKeyPath: KeyPathSchema,
   password: PasswordSchema
 };
+var DEFAULT_TIMEOUT_MS = 3e4;
+var poolWait = (timeoutMs = DEFAULT_TIMEOUT_MS) => ({ waitForCapacityMs: timeoutMs });
+var SFTP_POOL_WAIT_NOTE = ` If the connection pool is full (SSH_MCP_MAX_POOL_SIZE, default 100), waits up to ${DEFAULT_TIMEOUT_MS / 1e3}s for a free slot before starting.`;
 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) {
@@ -1716,21 +1904,26 @@ function registerTools(server, pool) {
     async ({ command, env, timeout, ...conn }) => {
       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 = [];
-        if (result.stdout) parts.push(result.stdout);
-        if (result.stderr) parts.push(`[stderr]
+      const timeoutMs = timeout || DEFAULT_TIMEOUT_MS;
+      return connectionPool.withConnection(
+        conn,
+        async (client) => {
+          const result = await exec(client, finalCommand, timeoutMs);
+          const parts = [];
+          if (result.stdout) parts.push(result.stdout);
+          if (result.stderr) parts.push(`[stderr]
 ${result.stderr}`);
-        if (result.signal) parts.push(`[signal: ${result.signal}]`);
-        parts.push(`[exit code: ${result.code}]`);
-        return { content: [{ type: "text", text: parts.join("\n") }] };
-      });
+          if (result.signal) parts.push(`[signal: ${result.signal}]`);
+          parts.push(`[exit code: ${result.code}]`);
+          return { content: [{ type: "text", text: parts.join("\n") }] };
+        },
+        poolWait(timeoutMs)
+      );
     }
   );
   server.tool(
     "ssh_read_file",
-    "Read a file from a remote host via SFTP.",
+    `Read a file from a remote host via SFTP.${SFTP_POOL_WAIT_NOTE}`,
     {
       ...connectionParams,
       path: z.string().refine((p) => p.startsWith("/"), {
@@ -1738,101 +1931,125 @@ ${result.stderr}`);
       }).describe("Absolute path to the remote file. Must start with /.")
     },
     async ({ path, ...conn }) => {
-      return connectionPool.withConnection(conn, async (client) => {
-        const content = await readFile(client, path);
-        return { content: [{ type: "text", text: content }] };
-      });
+      return connectionPool.withConnection(
+        conn,
+        async (client) => {
+          const content = await readFile(client, path);
+          return { content: [{ type: "text", text: content }] };
+        },
+        poolWait()
+      );
     }
   );
   server.tool(
     "ssh_write_file",
-    `Write content to a file on a remote host via SFTP. Creates or overwrites the file.${POLICY_EXEMPT_NOTE}`,
+    `Write content to a file on a remote host via SFTP. Creates or overwrites the file.${SFTP_POOL_WAIT_NOTE}${POLICY_EXEMPT_NOTE}`,
     {
       ...connectionParams,
       path: AbsoluteRemotePathSchema.describe("Absolute path to the remote file. Must start with /."),
       content: z.string().describe("File content to write")
     },
     async ({ path, content, ...conn }) => {
-      return connectionPool.withConnection(conn, async (client) => {
-        await writeFile(client, path, content);
-        const bytes = Buffer.byteLength(content, "utf8");
-        return { content: [{ type: "text", text: `Wrote ${bytes} bytes to ${path}` }] };
-      });
+      return connectionPool.withConnection(
+        conn,
+        async (client) => {
+          await writeFile(client, path, content);
+          const bytes = Buffer.byteLength(content, "utf8");
+          return { content: [{ type: "text", text: `Wrote ${bytes} bytes to ${path}` }] };
+        },
+        poolWait()
+      );
     }
   );
   server.tool(
     "ssh_upload",
-    `Upload a local file to a remote host via SFTP.${POLICY_EXEMPT_NOTE}`,
+    `Upload a local file to a remote host via SFTP.${SFTP_POOL_WAIT_NOTE}${POLICY_EXEMPT_NOTE}`,
     {
       ...connectionParams,
       localPath: z.string().describe("Path to the local file to upload"),
       remotePath: AbsoluteRemotePathSchema.describe("Absolute path on the remote host. Must start with /.")
     },
     async ({ localPath, remotePath, ...conn }) => {
-      return connectionPool.withConnection(conn, async (client) => {
-        await uploadFile(client, localPath, remotePath);
-        return { content: [{ type: "text", text: `Uploaded ${localPath} \u2192 ${remotePath}` }] };
-      });
+      return connectionPool.withConnection(
+        conn,
+        async (client) => {
+          await uploadFile(client, localPath, remotePath);
+          return { content: [{ type: "text", text: `Uploaded ${localPath} \u2192 ${remotePath}` }] };
+        },
+        poolWait()
+      );
     }
   );
   server.tool(
     "ssh_download",
-    "Download a file from a remote host to local filesystem via SFTP.",
+    `Download a file from a remote host to local filesystem via SFTP.${SFTP_POOL_WAIT_NOTE}`,
     {
       ...connectionParams,
       remotePath: AbsoluteRemotePathSchema.describe("Absolute path to the remote file. Must start with /."),
       localPath: z.string().describe("Local path to save the downloaded file")
     },
     async ({ remotePath, localPath, ...conn }) => {
-      return connectionPool.withConnection(conn, async (client) => {
-        await downloadFile(client, remotePath, localPath);
-        return { content: [{ type: "text", text: `Downloaded ${remotePath} \u2192 ${localPath}` }] };
-      });
+      return connectionPool.withConnection(
+        conn,
+        async (client) => {
+          await downloadFile(client, remotePath, localPath);
+          return { content: [{ type: "text", text: `Downloaded ${remotePath} \u2192 ${localPath}` }] };
+        },
+        poolWait()
+      );
     }
   );
   server.tool(
     "ssh_ls",
-    "List files in a directory on a remote host via SFTP.",
+    `List files in a directory on a remote host via SFTP.${SFTP_POOL_WAIT_NOTE}`,
     {
       ...connectionParams,
       path: AbsoluteRemotePathSchema.describe("Absolute path to the remote directory. Must start with /.")
     },
     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") }] };
-      });
+      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") }] };
+        },
+        poolWait()
+      );
     }
   );
   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 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.",
+    `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.${SFTP_POOL_WAIT_NOTE}`,
     {
       ...connectionParams,
       path: AbsoluteRemotePathSchema.describe("Absolute path to the remote file or directory. Must start with /.")
     },
     async ({ path, ...conn }) => {
-      return connectionPool.withConnection(conn, async (client) => {
-        const stats = await statFile(client, path);
-        const lines = [];
-        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}`);
-        lines.push(`  Owner: uid=${stats.uid} gid=${stats.gid}`);
-        lines.push(`  Modified: ${new Date(stats.mtime * 1e3).toISOString()}`);
-        lines.push(`  Accessed: ${new Date(stats.atime * 1e3).toISOString()}`);
-        return { content: [{ type: "text", text: lines.join("\n") }] };
-      });
+      return connectionPool.withConnection(
+        conn,
+        async (client) => {
+          const stats = await statFile(client, path);
+          const lines = [];
+          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}`);
+          lines.push(`  Owner: uid=${stats.uid} gid=${stats.gid}`);
+          lines.push(`  Modified: ${new Date(stats.mtime * 1e3).toISOString()}`);
+          lines.push(`  Accessed: ${new Date(stats.atime * 1e3).toISOString()}`);
+          return { content: [{ type: "text", text: lines.join("\n") }] };
+        },
+        poolWait()
+      );
     }
   );
   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. Unlike the other SFTP tools, the path may be relative.${POLICY_EXEMPT_NOTE}`,
+    `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.${SFTP_POOL_WAIT_NOTE}${POLICY_EXEMPT_NOTE}`,
     {
       ...connectionParams,
       path: z.string().describe(
@@ -1841,15 +2058,19 @@ ${result.stderr}`);
       recursive: z.boolean().optional().describe("Create parent directories as needed (default: false). Like `mkdir -p`.")
     },
     async ({ path, recursive, ...conn }) => {
-      return connectionPool.withConnection(conn, async (client) => {
-        await makeDir(client, path, recursive ?? false);
-        return { content: [{ type: "text", text: `Created directory ${path}` }] };
-      });
+      return connectionPool.withConnection(
+        conn,
+        async (client) => {
+          await makeDir(client, path, recursive ?? false);
+          return { content: [{ type: "text", text: `Created directory ${path}` }] };
+        },
+        poolWait()
+      );
     }
   );
   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.${POLICY_EXEMPT_NOTE}`,
+    `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.${SFTP_POOL_WAIT_NOTE}${POLICY_EXEMPT_NOTE}`,
     {
       ...connectionParams,
       path: AbsoluteRemotePathSchema.describe(
@@ -1857,10 +2078,14 @@ ${result.stderr}`);
       )
     },
     async ({ path, ...conn }) => {
-      return connectionPool.withConnection(conn, async (client) => {
-        await deleteFile(client, path);
-        return { content: [{ type: "text", text: `Deleted ${path}` }] };
-      });
+      return connectionPool.withConnection(
+        conn,
+        async (client) => {
+          await deleteFile(client, path);
+          return { content: [{ type: "text", text: `Deleted ${path}` }] };
+        },
+        poolWait()
+      );
     }
   );
   server.tool(
@@ -2050,7 +2275,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. 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).",
+    "Execute a command on multiple remote hosts in parallel. Runs at most SSH_MCP_MAX_POOL_SIZE hosts at once (default 100) and works through a longer list as slots free up. `timeout` is per host: it bounds each host's command, not the whole call. Each parallel slot works through its share of the list one host at a time, so with the pool to itself a call can take up to about ceil(hosts / SSH_MCP_MAX_POOL_SIZE) x (`timeout` + connect time). The connection pool is shared with every other tool; when it is full this call waits for slots instead of failing, and gives up only when none of its own hosts holds a slot and a full `timeout` has passed with none of them starting or finishing. The hosts waiting at that point (up to one per parallel slot) and every host still queued then report `Connection pool is full`; the queued ones are never attempted. Rerun those hosts once the other calls finish, or raise SSH_MCP_MAX_POOL_SIZE. 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"),
@@ -2059,13 +2284,17 @@ ${result.stderr}`);
       privateKeyPath: KeyPathSchema,
       password: PasswordSchema,
       env: EnvSchema,
-      timeout: TimeoutSchema
+      // Not the shared text: here the pool wait is the call-level no-progress budget, not a
+      // wait before one command starts.
+      timeout: TimeoutSchema.describe(
+        "Per-host command timeout in milliseconds (default: 30000): bounds each host's command, not the whole call. Also the call's no-progress budget on a full pool (see the tool description)."
+      )
     },
     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, finalCommand, timeout || 3e4);
+      const results = await multiExec(connectionPool, hostConfigs, finalCommand, timeout || DEFAULT_TIMEOUT_MS);
       const lines = [];
       for (const r of results) {
         lines.push(`--- ${r.host} ---`);
@@ -2098,14 +2327,19 @@ ${result.stderr}`);
       timeout: TimeoutSchema
     },
     async ({ path, name, type, maxdepth, minsize, maxsize, newer, timeout, ...conn }) => {
-      return connectionPool.withConnection(conn, async (client) => {
-        const files = await find(client, { path, name, type, maxdepth, minsize, maxsize, newer }, timeout || 3e4);
-        if (files.length === 0) {
-          return { content: [{ type: "text", text: "No files found." }] };
-        }
-        return { content: [{ type: "text", text: `Found ${files.length} result(s):
+      const timeoutMs = timeout || DEFAULT_TIMEOUT_MS;
+      return connectionPool.withConnection(
+        conn,
+        async (client) => {
+          const files = await find(client, { path, name, type, maxdepth, minsize, maxsize, newer }, timeoutMs);
+          if (files.length === 0) {
+            return { content: [{ type: "text", text: "No files found." }] };
+          }
+          return { content: [{ type: "text", text: `Found ${files.length} result(s):
 ${files.join("\n")}` }] };
-      });
+        },
+        poolWait(timeoutMs)
+      );
     }
   );
   server.tool(
@@ -2119,20 +2353,25 @@ ${files.join("\n")}` }] };
       timeout: TimeoutSchema
     },
     async ({ path, lines, grep, timeout, ...conn }) => {
-      return connectionPool.withConnection(conn, async (client) => {
-        const output = await tail(client, path, lines || 100, grep, timeout || 3e4);
-        if (!output.trim()) {
-          return {
-            content: [
-              {
-                type: "text",
-                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)."
-              }
-            ]
-          };
-        }
-        return { content: [{ type: "text", text: output }] };
-      });
+      const timeoutMs = timeout || DEFAULT_TIMEOUT_MS;
+      return connectionPool.withConnection(
+        conn,
+        async (client) => {
+          const output = await tail(client, path, lines || 100, grep, timeoutMs);
+          if (!output.trim()) {
+            return {
+              content: [
+                {
+                  type: "text",
+                  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)."
+                }
+              ]
+            };
+          }
+          return { content: [{ type: "text", text: output }] };
+        },
+        poolWait(timeoutMs)
+      );
     }
   );
   server.tool(
@@ -2144,18 +2383,23 @@ ${files.join("\n")}` }] };
       timeout: TimeoutSchema
     },
     async ({ service, timeout, ...conn }) => {
-      return connectionPool.withConnection(conn, async (client) => {
-        const status = await serviceStatus(client, service, timeout || 3e4);
-        const lines = [];
-        lines.push(`Service: ${status.name}`);
-        lines.push(`Status: ${status.status}`);
-        if (status.description) lines.push(`Description: ${status.description}`);
-        if (status.pid) lines.push(`PID: ${status.pid}`);
-        if (status.since) lines.push(`Since: ${status.since}`);
-        lines.push("");
-        lines.push(status.raw);
-        return { content: [{ type: "text", text: lines.join("\n") }], isError: status.unknown };
-      });
+      const timeoutMs = timeout || DEFAULT_TIMEOUT_MS;
+      return connectionPool.withConnection(
+        conn,
+        async (client) => {
+          const status = await serviceStatus(client, service, timeoutMs);
+          const lines = [];
+          lines.push(`Service: ${status.name}`);
+          lines.push(`Status: ${status.status}`);
+          if (status.description) lines.push(`Description: ${status.description}`);
+          if (status.pid) lines.push(`PID: ${status.pid}`);
+          if (status.since) lines.push(`Since: ${status.since}`);
+          lines.push("");
+          lines.push(status.raw);
+          return { content: [{ type: "text", text: lines.join("\n") }], isError: status.unknown };
+        },
+        poolWait(timeoutMs)
+      );
     }
   );
 }
@@ -2172,6 +2416,8 @@ function createServer(pool) {
 }
 export {
   ConnectionPool,
+  POOL_FULL_ERROR_CODE,
+  PoolFullError,
   checkConnectivity,
   checkGitSsh,
   checkKnownHosts,
@@ -2193,6 +2439,7 @@ export {
   fixKnownHosts,
   formatDiagnostics,
   isPolicyConfigured,
+  isPoolFullError,
   listDir,
   listSshKeys,
   loadKey,