@aaarc/handfree-ssh-mcp 1.0.4 → 1.0.6

package/build/services/ssh-connection-manager.js

@@ -41,6 +41,7 @@ export const BUILT_IN_DESTRUCTIVE_GUARDS = [
  */
 export class SSHConnectionManager {
     static instance;
+    static CLOSED_CLIENT_ERROR_SINK = () => { };
     clients = new Map();
     configs = {};
     connected = new Map();
@@ -196,6 +197,27 @@ export class SSHConnectionManager {
         this.connected.set(name, false);
         this.connecting.delete(name);
     }
+    closeConnection(name) {
+        const key = this.resolveServer(name);
+        this.getConfig(key);
+        const affected = new Set([key]);
+        const changed = new Set([key]);
+        for (const target of Object.keys(this.configs)) {
+            if (target === key)
+                continue;
+            if (this.jumpChainTouchesChanged(target, this.configs, changed)) {
+                affected.add(target);
+            }
+        }
+        for (const target of affected) {
+            this.closeClient(target, true);
+            this.statusCache.delete(target);
+        }
+        return {
+            requested: key,
+            closed: Array.from(affected),
+        };
+    }
     bumpConnectionGeneration(name) {
         this.connectionGenerations.set(name, (this.connectionGenerations.get(name) ?? 0) + 1);
     }
@@ -278,7 +300,7 @@ export class SSHConnectionManager {
      * Concurrent callers for the same server share a single in-flight promise,
      * so we never create two SSH clients and leak the loser.
      */
-    async connect(name) {
+    async connect(name, timeout) {
         const key = name || this.defaultName;
         if (this.connected.get(key) && this.clients.get(key)) {
             return;
@@ -287,21 +309,25 @@ export class SSHConnectionManager {
         if (inFlight) {
             return inFlight;
         }
-        const promise = this.doConnect(key).finally(() => {
-            this.connecting.delete(key);
+        let trackedPromise;
+        trackedPromise = this.doConnect(key, timeout).finally(() => {
+            if (this.connecting.get(key) === trackedPromise) {
+                this.connecting.delete(key);
+            }
         });
-        this.connecting.set(key, promise);
-        return promise;
+        this.connecting.set(key, trackedPromise);
+        return trackedPromise;
     }
     /**
      * Actual SSH connect implementation. Callers must go through `connect()`
      * so concurrent requests are deduped.
      * @private
      */
-    async doConnect(key) {
+    async doConnect(key, timeout) {
         const config = this.getConfig(key);
         const client = new Client();
         const generation = this.connectionGenerations.get(key) ?? 0;
+        const connectTimeout = this.normalizeConnectTimeout(timeout);
         this.pendingClients.set(key, client);
         try {
             await new Promise(async (resolve, reject) => {
@@ -357,6 +383,9 @@ export class SSHConnectionManager {
                     port: config.port,
                     username: config.username,
                 };
+                if (connectTimeout) {
+                    sshConfig.readyTimeout = connectTimeout;
+                }
                 const agent = config.agent === false
                     ? undefined
                     : config.agent || (config.identitiesOnly ? undefined : process.env.SSH_AUTH_SOCK);
@@ -367,7 +396,15 @@ export class SSHConnectionManager {
                 // (enforced at config load time).
                 if (config.jumpHost) {
                     try {
-                        const sock = await this.openJumpTunnel(key, config);
+                        const sock = await this.withConnectionTimeout(this.openJumpTunnel(key, config, undefined, connectTimeout), connectTimeout, `jump tunnel for [${key}] via '${config.jumpHost}'`, undefined, () => this.teardownJumpChain(key), (stream) => {
+                            try {
+                                stream.destroy?.();
+                            }
+                            catch {
+                                // Ignore late stream cleanup errors.
+                            }
+                            this.teardownJumpChain(key);
+                        });
                         sshConfig.sock = sock;
                         Logger.log(`Using jump host '${config.jumpHost}' for [${key}]`, "info");
                     }
@@ -390,7 +427,7 @@ export class SSHConnectionManager {
                         const proxyPort = parseInt(proxyUrl.port, 10);
                         Logger.log(`Using SOCKS proxy for [${key}]: ${config.socksProxy}`, "info");
                         // Create SOCKS connection
-                        const { socket } = await SocksClient.createConnection({
+                        const { socket } = await this.withConnectionTimeout(SocksClient.createConnection({
                             proxy: {
                                 host: proxyHost,
                                 port: proxyPort,
@@ -401,6 +438,14 @@ export class SSHConnectionManager {
                                 host: config.host,
                                 port: config.port,
                             },
+                            timeout: connectTimeout,
+                        }), connectTimeout, `SOCKS proxy connection for [${key}]`, undefined, undefined, (event) => {
+                            try {
+                                event.socket.destroy();
+                            }
+                            catch {
+                                // Ignore late socket cleanup errors.
+                            }
                         });
                         // Set the socket as the sock for SSH connection
                         sshConfig.sock = socket;
@@ -451,6 +496,212 @@ export class SSHConnectionManager {
         }
         this.clients.set(key, client);
     }
+    /**
+     * Open a one-shot SSH client for a single execute-command call.
+     * Used when the caller disables connection reuse after a timeout or when a
+     * fresh TCP/SSH handshake is more important than latency.
+     */
+    async connectCommandClient(key, timeout, debug) {
+        const config = this.getConfig(key);
+        const client = new Client();
+        const jumpChainKey = `__command__:${key}:${Date.now()}:${crypto.randomBytes(4).toString("hex")}`;
+        const connectTimeout = this.normalizeConnectTimeout(timeout) ?? 30000;
+        let settled = false;
+        let closed = false;
+        const onLateError = (err) => {
+            if (!settled) {
+                return;
+            }
+            debug?.(`[mcp] one-shot SSH client emitted error after ready/settle: ${err.message}`);
+            Logger.log(`One-shot SSH command client [${key}] emitted error after settle: ${err.message}`, "error");
+        };
+        client.on("error", onLateError);
+        const close = () => {
+            if (closed) {
+                return;
+            }
+            closed = true;
+            client.on("error", SSHConnectionManager.CLOSED_CLIENT_ERROR_SINK);
+            client.removeListener("error", onLateError);
+            try {
+                client.end();
+            }
+            catch {
+                // Ignore close errors for per-command clients.
+            }
+            this.connected.delete(jumpChainKey);
+            this.connecting.delete(jumpChainKey);
+            this.teardownJumpChain(jumpChainKey);
+        };
+        try {
+            const sshConfig = {
+                host: config.host,
+                port: config.port,
+                username: config.username,
+                readyTimeout: connectTimeout,
+            };
+            if (debug) {
+                sshConfig.debug = (line) => debug(`[ssh2] ${line}`);
+            }
+            const agent = config.agent === false
+                ? undefined
+                : config.agent || (config.identitiesOnly ? undefined : process.env.SSH_AUTH_SOCK);
+            if (agent) {
+                sshConfig.agent = agent;
+            }
+            if (config.jumpHost) {
+                try {
+                    sshConfig.sock = await this.withConnectionTimeout(this.openJumpTunnel(jumpChainKey, config, debug, connectTimeout), connectTimeout, `one-shot jump tunnel for [${key}] via '${config.jumpHost}'`, debug, () => this.teardownJumpChain(jumpChainKey), (stream) => {
+                        try {
+                            stream.destroy?.();
+                        }
+                        catch {
+                            // Ignore late stream cleanup errors.
+                        }
+                        this.teardownJumpChain(jumpChainKey);
+                    });
+                    Logger.log(`Using one-shot jump host '${config.jumpHost}' for command on [${key}]`, "info");
+                }
+                catch (err) {
+                    this.teardownJumpChain(jumpChainKey);
+                    throw new ToolError("SSH_CONNECTION_FAILED", `Failed to open one-shot jump tunnel for [${key}] via '${config.jumpHost}': ${err.message}`, true);
+                }
+            }
+            if (config.socksProxy) {
+                try {
+                    const proxyUrl = new URL(config.socksProxy);
+                    const { socket } = await this.withConnectionTimeout(SocksClient.createConnection({
+                        proxy: {
+                            host: proxyUrl.hostname,
+                            port: parseInt(proxyUrl.port, 10),
+                            type: 5,
+                        },
+                        command: "connect",
+                        destination: {
+                            host: config.host,
+                            port: config.port,
+                        },
+                        timeout: connectTimeout,
+                    }), connectTimeout, `SOCKS proxy connection for one-shot command [${key}]`, debug, undefined, (event) => {
+                        try {
+                            event.socket.destroy();
+                        }
+                        catch {
+                            // Ignore late socket cleanup errors.
+                        }
+                    });
+                    sshConfig.sock = socket;
+                }
+                catch (err) {
+                    throw new ToolError("SSH_CONNECTION_FAILED", `Failed to create SOCKS proxy connection for one-shot command [${key}]: ${err.message}`, true);
+                }
+            }
+            if (config.privateKey) {
+                try {
+                    sshConfig.privateKey = fs.readFileSync(config.privateKey, "utf8");
+                    if (config.passphrase) {
+                        sshConfig.passphrase = config.passphrase;
+                    }
+                }
+                catch (err) {
+                    throw new ToolError("LOCAL_FILE_READ_FAILED", `Failed to read private key file for [${key}]: ${err.message}`, false);
+                }
+            }
+            else if (config.password) {
+                sshConfig.password = config.password;
+            }
+            else if (agent || config.authOptional) {
+                Logger.log(`Using SSH agent/default authentication for one-shot command [${key}]`, "info");
+            }
+            else {
+                throw new ToolError("SSH_AUTHENTICATION_MISSING", `No valid authentication method provided for [${key}] (password or private key)`, false);
+            }
+            await new Promise((resolve, reject) => {
+                const done = (err) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    clearTimeout(timeoutId);
+                    client.removeListener("ready", onReady);
+                    client.removeListener("error", onError);
+                    client.removeListener("close", onClose);
+                    if (err)
+                        reject(err);
+                    else
+                        resolve();
+                };
+                const onReady = () => done();
+                const onError = (err) => done(new ToolError("SSH_CONNECTION_FAILED", `SSH command connection [${key}] failed: ${err.message}`, true));
+                const onClose = () => done(new ToolError("SSH_CONNECTION_FAILED", `SSH command connection [${key}] closed before ready`, true));
+                const timeoutId = setTimeout(() => {
+                    done(new ToolError("SSH_CONNECTION_FAILED", `SSH command connection [${key}] timed out after ${connectTimeout}ms`, true));
+                    close();
+                }, connectTimeout);
+                debug?.(`[mcp] opening one-shot SSH connection for [${key}]`);
+                client.once("ready", onReady);
+                client.once("error", onError);
+                client.once("close", onClose);
+                client.connect(sshConfig);
+            });
+            Logger.log(`Opened one-shot SSH command connection for [${key}]`, "info");
+            return { client, close };
+        }
+        catch (err) {
+            close();
+            throw err;
+        }
+    }
+    withConnectionTimeout(operation, timeoutMs, description, debug, onTimeout, onLateResolve) {
+        if (!timeoutMs || timeoutMs <= 0) {
+            return operation;
+        }
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            let timedOut = false;
+            const timeoutId = setTimeout(() => {
+                if (settled)
+                    return;
+                settled = true;
+                timedOut = true;
+                debug?.(`[mcp] ${description} timed out after ${timeoutMs}ms`);
+                try {
+                    onTimeout?.();
+                }
+                catch {
+                    // Ignore cleanup failures after timeout.
+                }
+                reject(new ToolError("SSH_CONNECTION_FAILED", `${description} timed out after ${timeoutMs}ms`, true));
+            }, timeoutMs);
+            operation.then((value) => {
+                if (timedOut) {
+                    try {
+                        onLateResolve?.(value);
+                    }
+                    catch {
+                        // Ignore cleanup failures for a late result.
+                    }
+                    return;
+                }
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timeoutId);
+                resolve(value);
+            }, (err) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timeoutId);
+                reject(err);
+            });
+        });
+    }
+    normalizeConnectTimeout(timeout) {
+        if (typeof timeout !== "number" || !Number.isFinite(timeout) || timeout <= 0) {
+            return undefined;
+        }
+        return Math.max(1, Math.min(timeout, 30000));
+    }
     /**
      * Open a TCP tunnel from the target's jump chain to `config.host:config.port`
      * and return the duplex stream to be used as `sock` for the target SSH client.
@@ -466,12 +717,12 @@ export class SSHConnectionManager {
      * calls against a bastion stay isolated.
      * @private
      */
-    async openJumpTunnel(targetKey, config) {
+    async openJumpTunnel(targetKey, config, debug, timeout) {
         // Tear down any stale jump chain for this target before opening a new one.
         this.teardownJumpChain(targetKey);
         this.jumpClients.set(targetKey, []);
-        const jumpClient = await this.connectJumpChain(targetKey, config.jumpHost);
-        return this.forwardOutStream(jumpClient, config.host, config.port);
+        const jumpClient = await this.connectJumpChain(targetKey, config.jumpHost, debug, timeout);
+        return this.forwardOutStream(jumpClient, config.host, config.port, timeout);
     }
     /**
      * Recursively connect the SSH client for `jumpName`, tunneling through its own
@@ -479,7 +730,7 @@ export class SSHConnectionManager {
      * to the target's jump-client chain. Returns the connected client for this hop.
      * @private
      */
-    async connectJumpChain(targetKey, jumpName) {
+    async connectJumpChain(targetKey, jumpName, debug, timeout) {
         const jumpConfig = this.configs[jumpName];
         if (!jumpConfig) {
             // Should be caught at config load, but guard at runtime too.
@@ -489,10 +740,10 @@ export class SSHConnectionManager {
         // tunnel first and hand its stream to this hop as `sock`.
         let sock;
         if (jumpConfig.jumpHost) {
-            const innerClient = await this.connectJumpChain(targetKey, jumpConfig.jumpHost);
-            sock = await this.forwardOutStream(innerClient, jumpConfig.host, jumpConfig.port);
+            const innerClient = await this.connectJumpChain(targetKey, jumpConfig.jumpHost, debug, timeout);
+            sock = await this.forwardOutStream(innerClient, jumpConfig.host, jumpConfig.port, timeout);
         }
-        const jumpClient = await this.connectJumpClient(targetKey, jumpName, jumpConfig, sock);
+        const jumpClient = await this.connectJumpClient(targetKey, jumpName, jumpConfig, sock, debug, timeout);
         const chain = this.jumpClients.get(targetKey);
         if (chain) {
             chain.push(jumpClient);
@@ -508,14 +759,57 @@ export class SSHConnectionManager {
      * chain down so a dead hop surfaces as a clear failure on the next op.
      * @private
      */
-    connectJumpClient(targetKey, jumpName, jumpConfig, sock) {
+    connectJumpClient(targetKey, jumpName, jumpConfig, sock, debug, timeout) {
         return new Promise((resolve, reject) => {
             const jumpClient = new Client();
-            jumpClient.on("ready", () => resolve(jumpClient));
-            jumpClient.on("error", (err) => {
-                reject(new Error(`jump SSH connect failed for '${jumpName}': ${err.message}`));
-            });
+            let settled = false;
+            let timeoutId = null;
+            let closedErrorSinkInstalled = false;
+            const installClosedErrorSink = () => {
+                if (!closedErrorSinkInstalled) {
+                    closedErrorSinkInstalled = true;
+                    jumpClient.on("error", SSHConnectionManager.CLOSED_CLIENT_ERROR_SINK);
+                }
+            };
+            const onLateError = (err) => {
+                Logger.log(`Jump SSH client '${jumpName}' for [${targetKey}] emitted error after ready: ${err.message}`, "error");
+                this.teardownTargetViaJump(targetKey);
+            };
+            const cleanup = () => {
+                if (timeoutId) {
+                    clearTimeout(timeoutId);
+                    timeoutId = null;
+                }
+                jumpClient.removeListener("ready", onReady);
+                jumpClient.removeListener("error", onError);
+            };
+            const done = (err) => {
+                if (settled)
+                    return;
+                settled = true;
+                cleanup();
+                if (err) {
+                    installClosedErrorSink();
+                    reject(err);
+                    return;
+                }
+                jumpClient.on("error", onLateError);
+                resolve(jumpClient);
+            };
+            const onReady = () => done();
+            const onError = (err) => {
+                done(new Error(`jump SSH connect failed for '${jumpName}': ${err.message}`));
+            };
+            jumpClient.on("ready", onReady);
+            jumpClient.on("error", onError);
             jumpClient.on("close", () => {
+                if (!settled) {
+                    done(new Error(`jump SSH connect closed for '${jumpName}' before ready`));
+                    return;
+                }
+                jumpClient.removeListener("error", onError);
+                jumpClient.removeListener("error", onLateError);
+                installClosedErrorSink();
                 // If any hop dies, kill the target too so callers get a clear failure on
                 // the next op and reconnect through a fresh chain.
                 this.teardownTargetViaJump(targetKey);
@@ -528,6 +822,21 @@ export class SSHConnectionManager {
             if (sock) {
                 jumpSsh.sock = sock;
             }
+            if (timeout) {
+                jumpSsh.readyTimeout = timeout;
+                timeoutId = setTimeout(() => {
+                    done(new Error(`jump SSH connect timed out for '${jumpName}' after ${timeout}ms`));
+                    try {
+                        jumpClient.end();
+                    }
+                    catch {
+                        // Ignore close errors after timeout.
+                    }
+                }, timeout);
+            }
+            if (debug) {
+                jumpSsh.debug = (line) => debug(`[ssh2:${jumpName}] ${line}`);
+            }
             const jumpAgent = jumpConfig.agent === false
                 ? undefined
                 : jumpConfig.agent || (jumpConfig.identitiesOnly ? undefined : process.env.SSH_AUTH_SOCK);
@@ -560,12 +869,39 @@ export class SSHConnectionManager {
      * Open a forwarded TCP stream from `client` to `host:port`.
      * @private
      */
-    forwardOutStream(client, host, port) {
+    forwardOutStream(client, host, port, timeout) {
         return new Promise((resolve, reject) => {
+            let settled = false;
+            let timeoutId = null;
+            const done = (err, stream) => {
+                if (settled)
+                    return;
+                settled = true;
+                if (timeoutId) {
+                    clearTimeout(timeoutId);
+                }
+                if (err) {
+                    reject(err);
+                    return;
+                }
+                resolve(stream);
+            };
+            if (timeout) {
+                timeoutId = setTimeout(() => {
+                    done(new Error(`forwardOut to ${host}:${port} timed out after ${timeout}ms`));
+                }, timeout);
+            }
             client.forwardOut("127.0.0.1", 0, host, port, (err, ch) => {
-                if (err)
-                    return reject(err);
-                resolve(ch);
+                if (settled) {
+                    try {
+                        ch?.close();
+                    }
+                    catch {
+                        // Ignore cleanup failures for a late forwarded channel.
+                    }
+                    return;
+                }
+                done(err, ch);
             });
         });
     }
@@ -622,10 +958,11 @@ export class SSHConnectionManager {
      * Ensure SSH client is connected
      * @private
      */
-    async ensureConnected(name) {
+    async ensureConnected(name, timeout) {
         const key = name || this.defaultName;
         if (!this.connected.get(key) || !this.clients.get(key)) {
-            await this.connect(key);
+            const connectTimeout = this.normalizeConnectTimeout(timeout);
+            await this.withConnectionTimeout(this.connect(key, timeout), connectTimeout, `cached SSH connection [${key}]`, undefined, () => this.closeClient(key, true));
         }
         const client = this.clients.get(key);
         if (!client) {
@@ -641,7 +978,10 @@ export class SSHConnectionManager {
         if (error instanceof ToolError) {
             return error.code === "SSH_CONNECTION_FAILED";
         }
-        const msg = error.message.toLowerCase();
+        return this.isConnectionShapedMessage(error.message);
+    }
+    isConnectionShapedMessage(message) {
+        const msg = message.toLowerCase();
         return (msg.includes("not connected") ||
             msg.includes("connection") ||
             msg.includes("socket") ||
@@ -650,7 +990,9 @@ export class SSHConnectionManager {
             msg.includes("epipe") ||
             msg.includes("closed") ||
             msg.includes("end of stream") ||
-            msg.includes("channel"));
+            msg.includes("channel") ||
+            msg.includes("no response from server") ||
+            msg.includes("timed out"));
     }
     /**
      * Force reconnect to SSH server
@@ -918,54 +1260,107 @@ export class SSHConnectionManager {
      */
     async runCommandStream(cmdString, client, timeout, sinks) {
         return new Promise((resolve, reject) => {
-            let timeoutId;
+            let timeoutId = null;
+            let settled = false;
             const cleanup = () => {
-                if (timeoutId)
+                if (timeoutId) {
                     clearTimeout(timeoutId);
+                    timeoutId = null;
+                }
             };
-            client.exec(cmdString, (err, stream) => {
-                if (err) {
-                    cleanup();
-                    reject(new ToolError("COMMAND_EXECUTION_ERROR", `Command execution error: ${err.message}`, false));
+            const settle = (err, code) => {
+                if (settled)
                     return;
-                }
-                stream.on("data", (chunk) => {
-                    sinks.stdoutCollector?.push(chunk);
-                    sinks.logWriter?.appendStdout(chunk);
-                    if (sinks.onProgress)
-                        sinks.onProgress(chunk.toString());
-                });
-                stream.stderr.on("data", (chunk) => {
-                    sinks.stderrCollector?.push(chunk);
-                    sinks.logWriter?.appendStderr(chunk);
-                    if (sinks.onProgress)
-                        sinks.onProgress(`[STDERR] ${chunk.toString()}`);
-                });
-                stream.on("close", (code) => {
-                    cleanup();
+                settled = true;
+                cleanup();
+                if (err)
+                    reject(err);
+                else
                     resolve(code ?? null);
-                });
-                stream.on("error", (err) => {
-                    cleanup();
-                    reject(new ToolError("COMMAND_EXECUTION_ERROR", `Stream error: ${err.message}`, false));
-                });
+            };
+            const closeLateStream = (stream) => {
+                try {
+                    stream.close();
+                }
+                catch {
+                    // Ignore late-stream close errors after the promise has settled.
+                }
+            };
+            const armExecOpenTimeout = () => {
+                const execOpenTimeout = Math.max(1, Math.min(timeout, 30000));
                 timeoutId = setTimeout(() => {
-                    cleanup();
+                    sinks.debug?.(`[mcp] exec channel open timed out after ${execOpenTimeout}ms`);
+                    settle(new ToolError("SSH_CONNECTION_FAILED", `SSH exec channel timeout: no response from server within ${execOpenTimeout}ms while opening command channel`, true));
+                }, execOpenTimeout);
+            };
+            const armCommandTimeout = (stream) => {
+                timeoutId = setTimeout(() => {
+                    sinks.debug?.(`[mcp] remote command timed out after ${timeout}ms; closing command channel`);
+                    settle(new ToolError("COMMAND_TIMEOUT", `Command timeout: execution exceeded ${timeout}ms limit. Remote process killed.`, false));
                     try {
                         stream.signal("KILL");
                     }
-                    catch (e) {
-                        // Ignore errors when sending signal
+                    catch {
+                        // Ignore errors when sending signal.
                     }
                     try {
                         stream.close();
                     }
-                    catch (e) {
-                        // Ignore errors when closing streams during timeout
+                    catch {
+                        // Ignore errors when closing streams during timeout.
                     }
-                    reject(new ToolError("COMMAND_TIMEOUT", `Command timeout: execution exceeded ${timeout}ms limit. Remote process killed.`, false));
                 }, timeout);
-            });
+            };
+            armExecOpenTimeout();
+            sinks.debug?.(`[mcp] opening exec channel for command: ${cmdString}`);
+            try {
+                client.exec(cmdString, (err, stream) => {
+                    if (settled) {
+                        if (stream)
+                            closeLateStream(stream);
+                        return;
+                    }
+                    if (err) {
+                        const isConnectionFailure = this.isConnectionShapedMessage(err.message);
+                        const code = isConnectionFailure ? "SSH_CONNECTION_FAILED" : "COMMAND_EXECUTION_ERROR";
+                        sinks.debug?.(`[mcp] exec callback failed: ${err.message}`);
+                        settle(new ToolError(code, `Command execution error: ${err.message}`, isConnectionFailure));
+                        return;
+                    }
+                    cleanup();
+                    sinks.debug?.("[mcp] exec channel opened");
+                    stream.on("data", (chunk) => {
+                        sinks.stdoutCollector?.push(chunk);
+                        sinks.logWriter?.appendStdout(chunk);
+                        if (sinks.onProgress)
+                            sinks.onProgress(chunk.toString());
+                    });
+                    stream.stderr.on("data", (chunk) => {
+                        sinks.stderrCollector?.push(chunk);
+                        sinks.logWriter?.appendStderr(chunk);
+                        if (sinks.onProgress)
+                            sinks.onProgress(`[STDERR] ${chunk.toString()}`);
+                    });
+                    stream.on("close", (code) => {
+                        sinks.debug?.(`[mcp] exec channel closed with code ${code ?? "null"}`);
+                        settle(null, code ?? null);
+                    });
+                    stream.on("error", (err) => {
+                        const isConnectionFailure = this.isConnectionShapedMessage(err.message);
+                        const code = isConnectionFailure ? "SSH_CONNECTION_FAILED" : "COMMAND_EXECUTION_ERROR";
+                        sinks.debug?.(`[mcp] exec stream error: ${err.message}`);
+                        settle(new ToolError(code, `Stream error: ${err.message}`, isConnectionFailure));
+                    });
+                    armCommandTimeout(stream);
+                });
+            }
+            catch (err) {
+                const error = err;
+                const isConnectionFailure = this.isConnectionShapedMessage(error.message);
+                const code = isConnectionFailure ? "SSH_CONNECTION_FAILED" : "COMMAND_EXECUTION_ERROR";
+                sinks.debug?.(`[mcp] client.exec threw before callback: ${error.message}`);
+                settle(new ToolError(code, `Command execution error: ${error.message}`, isConnectionFailure));
+            }
         });
     }
     /**
@@ -974,6 +1369,45 @@ export class SSHConnectionManager {
      * full output is always persisted to disk regardless of this cap.
      */
     static DEFAULT_MAX_OUTPUT_BYTES = 64 * 1024;
+    static DEFAULT_DEBUG_BYTES = 64 * 1024;
+    createDebugCollector(enabled) {
+        if (!enabled) {
+            return { collector: null };
+        }
+        const collector = new OutputCollector(SSHConnectionManager.DEFAULT_DEBUG_BYTES);
+        return {
+            collector,
+            debug: (line) => {
+                collector.push(`${line}\n`);
+            },
+        };
+    }
+    appendDebugOutput(result, collector) {
+        if (!collector || collector.getTotalBytes() === 0) {
+            return result;
+        }
+        const snapshot = collector.getSnapshot();
+        const header = snapshot.truncated
+            ? `[SSH DEBUG TRUNCATED: dropped ${snapshot.droppedBytes} bytes]\n`
+            : "[SSH DEBUG]\n";
+        return `${result}\n\n${header}${snapshot.tail.toString("utf8").trimEnd()}`;
+    }
+    appendDebugToError(error, collector) {
+        if (!collector || collector.getTotalBytes() === 0) {
+            return error;
+        }
+        const snapshot = collector.getSnapshot();
+        const header = snapshot.truncated
+            ? `[SSH DEBUG TRUNCATED: dropped ${snapshot.droppedBytes} bytes]\n`
+            : "[SSH DEBUG]\n";
+        const message = `${error.message}\n\n${header}${snapshot.tail.toString("utf8").trimEnd()}`;
+        if (error instanceof ToolError) {
+            return new ToolError(error.code, message, error.retriable);
+        }
+        const wrapped = new Error(message);
+        wrapped.name = error.name;
+        return wrapped;
+    }
     /**
      * Assemble the final user-visible result string from collected tails.
      * Adds a truncation header (with the on-disk log path) and the legacy
@@ -1039,12 +1473,20 @@ export class SSHConnectionManager {
         const timeout = options.timeout || 30000; // Default 30 seconds timeout
         const maxRetries = options.maxRetries ?? 2; // Default 2 retries
         const maxOutputBytes = options.maxOutputBytes ?? SSHConnectionManager.DEFAULT_MAX_OUTPUT_BYTES;
+        const reuseConnection = options.reuseConnection !== false;
         const key = name || this.defaultName;
+        const { collector: debugCollector, debug } = this.createDebugCollector(options.vvv === true);
         let lastError = null;
         for (let attempt = 0; attempt <= maxRetries; attempt++) {
             try {
-                // Ensure SSH connection is established
-                const client = await this.ensureConnected(name);
+                debug?.(`[mcp] command attempt ${attempt + 1}/${maxRetries + 1} on [${key}], reuseConnection=${reuseConnection}`);
+                const commandConnection = reuseConnection
+                    ? { client: await this.ensureConnected(name, timeout), close: () => { } }
+                    : await this.connectCommandClient(key, timeout, debug);
+                const client = commandConnection.client;
+                if (reuseConnection) {
+                    debug?.(`[mcp] using cached SSH connection for [${key}]; set reuseConnection=false to capture SSH handshake debug`);
+                }
                 // Per-attempt collectors + log writer. We rebuild them on each retry
                 // so partial output from a failed attempt is not mixed into the next.
                 const stdoutCollector = new OutputCollector(maxOutputBytes);
@@ -1057,10 +1499,12 @@ export class SSHConnectionManager {
                         stdoutCollector,
                         stderrCollector,
                         logWriter: logWriter ?? undefined,
+                        debug,
                     });
                 }
                 finally {
                     logWriter?.close({ exitCode, durationMs: Date.now() - startedMs });
+                    commandConnection.close();
                 }
                 const result = this.buildExecuteResult({
                     stdoutCollector,
@@ -1073,7 +1517,7 @@ export class SSHConnectionManager {
                 if (attempt > 0) {
                     Logger.log(`Command succeeded on retry attempt ${attempt} for [${key}]`, "info");
                 }
-                return result;
+                return this.appendDebugOutput(result, debugCollector);
             }
             catch (error) {
                 lastError = error;
@@ -1083,13 +1527,13 @@ export class SSHConnectionManager {
                     Logger.log(`Connection error on attempt ${attempt + 1}/${maxRetries + 1} for [${key}]: ${lastError.message}. Retrying in ${backoffMs}ms...`, "info");
                     // Wait with exponential backoff
                     await this.sleep(backoffMs);
-                    // Force reconnect before retry
-                    try {
-                        await this.reconnect(name);
-                    }
-                    catch (reconnectError) {
-                        Logger.log(`Reconnect failed for [${key}]: ${reconnectError.message}`, "error");
-                        // Continue to next retry attempt anyway
+                    if (reuseConnection) {
+                        try {
+                            await this.reconnect(name);
+                        }
+                        catch (reconnectError) {
+                            Logger.log(`Reconnect failed for [${key}]: ${reconnectError.message}`, "error");
+                        }
                     }
                     continue;
                 }
@@ -1098,7 +1542,7 @@ export class SSHConnectionManager {
             }
         }
         // All retries exhausted
-        throw lastError || new Error("Command execution failed after all retries");
+        throw this.appendDebugToError(lastError || new Error("Command execution failed after all retries"), debugCollector);
     }
     /**
      * Execute SSH command with real-time streaming output via progress callback
@@ -1122,12 +1566,20 @@ export class SSHConnectionManager {
         const timeout = options.timeout || 300000; // Default 5 minutes for streaming
         const maxRetries = options.maxRetries ?? 2; // Default 2 retries
         const maxOutputBytes = options.maxOutputBytes ?? SSHConnectionManager.DEFAULT_MAX_OUTPUT_BYTES;
+        const reuseConnection = options.reuseConnection !== false;
         const key = name || this.defaultName;
+        const { collector: debugCollector, debug } = this.createDebugCollector(options.vvv === true);
         let lastError = null;
         for (let attempt = 0; attempt <= maxRetries; attempt++) {
             try {
-                // Ensure SSH connection is established
-                const client = await this.ensureConnected(name);
+                debug?.(`[mcp] streaming command attempt ${attempt + 1}/${maxRetries + 1} on [${key}], reuseConnection=${reuseConnection}`);
+                const commandConnection = reuseConnection
+                    ? { client: await this.ensureConnected(name, timeout), close: () => { } }
+                    : await this.connectCommandClient(key, timeout, debug);
+                const client = commandConnection.client;
+                if (reuseConnection) {
+                    debug?.(`[mcp] using cached SSH connection for [${key}]; set reuseConnection=false to capture SSH handshake debug`);
+                }
                 // Per-attempt collectors + log writer. onProgress keeps streaming
                 // every byte live; only the final returned string is capped.
                 const stdoutCollector = new OutputCollector(maxOutputBytes);
@@ -1141,10 +1593,12 @@ export class SSHConnectionManager {
                         stderrCollector,
                         logWriter: logWriter ?? undefined,
                         onProgress: options.onProgress,
+                        debug,
                     });
                 }
                 finally {
                     logWriter?.close({ exitCode, durationMs: Date.now() - startedMs });
+                    commandConnection.close();
                 }
                 const result = this.buildExecuteResult({
                     stdoutCollector,
@@ -1157,7 +1611,7 @@ export class SSHConnectionManager {
                 if (attempt > 0) {
                     Logger.log(`Streaming command succeeded on retry attempt ${attempt} for [${key}]`, "info");
                 }
-                return result;
+                return this.appendDebugOutput(result, debugCollector);
             }
             catch (error) {
                 lastError = error;
@@ -1166,18 +1620,20 @@ export class SSHConnectionManager {
                     const backoffMs = 500 * Math.pow(2, attempt);
                     Logger.log(`Connection error on streaming attempt ${attempt + 1}/${maxRetries + 1} for [${key}]: ${lastError.message}. Retrying in ${backoffMs}ms...`, "info");
                     await this.sleep(backoffMs);
-                    try {
-                        await this.reconnect(name);
-                    }
-                    catch (reconnectError) {
-                        Logger.log(`Reconnect failed for [${key}]: ${reconnectError.message}`, "error");
+                    if (reuseConnection) {
+                        try {
+                            await this.reconnect(name);
+                        }
+                        catch (reconnectError) {
+                            Logger.log(`Reconnect failed for [${key}]: ${reconnectError.message}`, "error");
+                        }
                     }
                     continue;
                 }
                 break;
             }
         }
-        throw lastError || new Error("Streaming command execution failed after all retries");
+        throw this.appendDebugToError(lastError || new Error("Streaming command execution failed after all retries"), debugCollector);
     }
     /**
      * Build an OutputLogWriter for a given server. Returns null if we cannot
@@ -1204,14 +1660,16 @@ export class SSHConnectionManager {
      */
     validateLocalPath(localPath, name) {
         const resolvedPath = path.resolve(localPath);
+        const config = name ? this.getServerConfig(name) : undefined;
+        // disableSftpPathPolicy fully opens the local side too (any path allowed).
+        if (config?.disableSftpPathPolicy) {
+            return resolvedPath;
+        }
         const allowedRoots = new Set([process.cwd()]);
         // Add per-server allowedLocalDirectories if a server is targeted
-        if (name) {
-            const config = this.getServerConfig(name);
-            if (config?.allowedLocalDirectories) {
-                for (const dir of config.allowedLocalDirectories) {
-                    allowedRoots.add(dir);
-                }
+        if (config?.allowedLocalDirectories) {
+            for (const dir of config.allowedLocalDirectories) {
+                allowedRoots.add(dir);
             }
         }
         const isAllowed = Array.from(allowedRoots).some((root) => resolvedPath === root || resolvedPath.startsWith(root + path.sep));
@@ -1249,9 +1707,11 @@ export class SSHConnectionManager {
         const normalized = path.posix.normalize(remotePath);
         const config = this.getConfig(name);
         const allowedRoots = config.allowedRemoteDirectories ?? [];
-        if (allowedRoots.length === 0) {
-            throw new ToolError("REMOTE_PATH_NOT_ALLOWED", `SFTP is disabled for server '${name}': no 'allowedRemoteDirectories' configured. ` +
-                `Add at least one absolute POSIX directory to 'allowedRemoteDirectories' in the YAML config to permit upload/download.`, false);
+        // Default is OPEN: with no 'allowedRemoteDirectories' configured (or
+        // disableSftpPathPolicy set), any absolute POSIX path is allowed. Configure
+        // 'allowedRemoteDirectories' to opt into an allowlist for this server.
+        if (config.disableSftpPathPolicy || allowedRoots.length === 0) {
+            return normalized;
         }
         const isAllowed = allowedRoots.some((root) => normalized === root || normalized.startsWith(root === "/" ? "/" : root + "/"));
         if (!isAllowed) {