@aaarc/handfree-ssh-mcp 1.0.5 → 1.0.7

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();
@@ -124,10 +125,7 @@ export class SSHConnectionManager {
                 toReset.add(name);
             }
         }
-        for (const name of toReset) {
-            this.closeClient(name, true);
-            this.statusCache.delete(name);
-        }
+        this.closeClientSet(toReset, true);
         this.setConfig(configs, enabledServers);
         Logger.log(`Hot-reloaded SSH config: ${Object.keys(configs).length} server(s), ` +
             `${toReset.size} connection(s) reset`, "info");
@@ -196,6 +194,30 @@ export class SSHConnectionManager {
         this.connected.set(name, false);
         this.connecting.delete(name);
     }
+    closeClientSet(names, bumpGeneration = true) {
+        for (const name of names) {
+            this.closeClient(name, bumpGeneration);
+            this.statusCache.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);
+            }
+        }
+        this.closeClientSet(affected, true);
+        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,231 @@ export class SSHConnectionManager {
         }
         this.clients.set(key, client);
     }
+    async acquireSshClient(key, options = {}) {
+        const reuseConnection = options.reuseConnection !== false;
+        const purpose = options.purpose ?? "command";
+        if (reuseConnection) {
+            const client = await this.ensureConnected(key, options.timeout);
+            options.debug?.(`[mcp] using cached SSH connection for [${key}]; set reuseConnection=false to capture SSH handshake debug`);
+            return { client, close: () => { } };
+        }
+        if (purpose === "command") {
+            return this.connectCommandClient(key, options.timeout ?? 30000, options.debug);
+        }
+        return this.connectOneShotClient(key, options.timeout ?? 30000, options.debug, purpose);
+    }
+    /**
+     * Compatibility wrapper for tests and existing command call sites.
+     */
+    async connectCommandClient(key, timeout, debug) {
+        return this.connectOneShotClient(key, timeout, debug, "command");
+    }
+    /**
+     * Open a one-shot SSH client for a single operation. Used when the caller
+     * disables connection reuse after a timeout or when a fresh TCP/SSH
+     * handshake is more important than latency.
+     */
+    async connectOneShotClient(key, timeout, debug, purpose = "command") {
+        const config = this.getConfig(key);
+        const client = new Client();
+        const jumpChainKey = `__${purpose}__:${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 ${purpose} 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 ${purpose} on [${key}]`, "info");
+                }
+                catch (err) {
+                    this.teardownJumpChain(jumpChainKey);
+                    throw new ToolError("SSH_CONNECTION_FAILED", `Failed to open one-shot jump tunnel for ${purpose} [${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 ${purpose} [${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 ${purpose} connection [${key}] failed: ${err.message}`, true));
+                const onClose = () => done(new ToolError("SSH_CONNECTION_FAILED", `SSH ${purpose} connection [${key}] closed before ready`, true));
+                const timeoutId = setTimeout(() => {
+                    done(new ToolError("SSH_CONNECTION_FAILED", `SSH ${purpose} connection [${key}] timed out after ${connectTimeout}ms`, true));
+                    close();
+                }, connectTimeout);
+                debug?.(`[mcp] opening one-shot SSH ${purpose} connection for [${key}]`);
+                client.once("ready", onReady);
+                client.once("error", onError);
+                client.once("close", onClose);
+                client.connect(sshConfig);
+            });
+            Logger.log(`Opened one-shot SSH ${purpose} 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, timeout);
+    }
     /**
      * 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 +736,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 +749,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 +759,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 +778,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 +841,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 +888,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 +977,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 +997,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 +1009,34 @@ 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"));
+    }
+    makeSftpError(context, error) {
+        const connectionFailure = this.isConnectionShapedMessage(error.message);
+        return new ToolError(connectionFailure ? "SSH_CONNECTION_FAILED" : "SFTP_ERROR", `${context}: ${error.message}`, connectionFailure);
+    }
+    createSftpTransferOptions(options) {
+        const transferOptions = {};
+        const concurrency = this.optionalPositiveInteger(options?.sftpConcurrency, "sftpConcurrency");
+        const chunkSize = this.optionalPositiveInteger(options?.chunkSize, "chunkSize");
+        if (concurrency !== undefined) {
+            transferOptions.concurrency = concurrency;
+        }
+        if (chunkSize !== undefined) {
+            transferOptions.chunkSize = chunkSize;
+        }
+        return transferOptions;
+    }
+    optionalPositiveInteger(value, name) {
+        if (value === undefined) {
+            return undefined;
+        }
+        if (!Number.isInteger(value) || value <= 0) {
+            throw new ToolError("INVALID_CONFIGURATION", `${name} must be a positive integer`, false);
+        }
+        return value;
     }
     /**
      * Force reconnect to SSH server
@@ -918,54 +1304,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, timeout);
                 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 +1413,73 @@ 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) {
+        const debugBlock = this.formatDebugBlock(collector);
+        if (!debugBlock) {
+            return result;
+        }
+        return `${result}\n\n${debugBlock}`;
+    }
+    appendDebugToError(error, collector) {
+        const debugBlock = this.formatDebugBlock(collector);
+        if (!debugBlock) {
+            return error;
+        }
+        const message = `${error.message}\n\n${debugBlock}`;
+        if (error instanceof ToolError) {
+            return new ToolError(error.code, message, error.retriable);
+        }
+        const wrapped = new Error(message);
+        wrapped.name = error.name;
+        return wrapped;
+    }
+    formatDebugBlock(collector) {
+        if (!collector || collector.getTotalBytes() === 0) {
+            return null;
+        }
+        const snapshot = collector.getSnapshot();
+        const header = snapshot.truncated
+            ? `[SSH DEBUG TRUNCATED: dropped ${snapshot.droppedBytes} bytes]\n`
+            : "[SSH DEBUG]\n";
+        return `${header}${snapshot.tail.toString("utf8").trimEnd()}`;
+    }
+    unpipeStream(readStream, writeStream) {
+        const candidate = readStream;
+        if (typeof candidate.unpipe !== "function") {
+            return;
+        }
+        try {
+            candidate.unpipe(writeStream);
+        }
+        catch {
+            // Ignore cleanup errors after the original stream failure.
+        }
+    }
+    destroyStream(stream) {
+        const candidate = stream;
+        if (typeof candidate.destroy !== "function") {
+            return;
+        }
+        try {
+            candidate.destroy();
+        }
+        catch {
+            // Ignore cleanup errors after the original stream failure.
+        }
+    }
     /**
      * 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 +1545,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 = await this.acquireSshClient(key, {
+                    reuseConnection,
+                    timeout,
+                    debug,
+                    purpose: "command",
+                });
+                const client = commandConnection.client;
                 // 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 +1571,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 +1589,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 +1599,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 +1614,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 +1638,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 = await this.acquireSshClient(key, {
+                    reuseConnection,
+                    timeout,
+                    debug,
+                    purpose: "command",
+                });
+                const client = commandConnection.client;
                 // 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 +1665,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 +1683,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 +1692,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
@@ -1269,6 +1797,8 @@ export class SSHConnectionManager {
      */
     async upload(localPath, remotePath, name, options) {
         const resolvedName = name || this.defaultName;
+        const reuseConnection = options?.reuseConnection !== false;
+        const { collector: debugCollector, debug } = this.createDebugCollector(options?.vvv === true);
         const validatedLocalPath = this.validateLocalPath(localPath, resolvedName);
         const validatedRemotePath = this.validateRemotePath(remotePath, resolvedName);
         const skipIfIdentical = options?.skipIfIdentical !== false; // default true
@@ -1284,32 +1814,67 @@ export class SSHConnectionManager {
             throw new ToolError("LOCAL_FILE_READ_FAILED", `Local path '${validatedLocalPath}' is not a regular file (size=${stat.size}). ` +
                 `Use uploadDirectory / recursive=true for directories.`, false);
         }
-        let payload;
-        try {
-            payload = fs.readFileSync(validatedLocalPath);
-        }
-        catch (e) {
-            throw new ToolError("LOCAL_FILE_READ_FAILED", `Failed to read local file '${validatedLocalPath}': ${e.message}`, false);
+        const isShellScript = SSHConnectionManager.SHELL_SCRIPT_EXTENSIONS.has(path.extname(validatedLocalPath).toLowerCase());
+        const fastUpload = options?.fast === true;
+        const mustReadPayload = skipIfIdentical || !fastUpload || isShellScript;
+        let payload = null;
+        let crlfFixed = {
+            buffer: Buffer.alloc(0),
+            fixed: false,
+            replacedCount: 0,
+        };
+        if (mustReadPayload) {
+            try {
+                payload = fs.readFileSync(validatedLocalPath);
+            }
+            catch (e) {
+                throw new ToolError("LOCAL_FILE_READ_FAILED", `Failed to read local file '${validatedLocalPath}': ${e.message}`, false);
+            }
+            // ---- CRLF auto-fix for shell scripts ----
+            crlfFixed = SSHConnectionManager.maybeFixShellScriptLineEndings(validatedLocalPath, payload);
+            payload = crlfFixed.buffer;
         }
-        // ---- CRLF auto-fix for shell scripts ----
-        const crlfFixed = SSHConnectionManager.maybeFixShellScriptLineEndings(validatedLocalPath, payload);
-        payload = crlfFixed.buffer;
         const crlfNote = crlfFixed.fixed
             ? ` (CRLF→LF auto-fix: converted ${crlfFixed.replacedCount} line endings to LF before upload because target is a shell script).`
             : "";
-        const client = await this.ensureConnected(resolvedName);
-        // ---- Skip-if-identical check ----
-        const isShellScript = SSHConnectionManager.SHELL_SCRIPT_EXTENSIONS.has(path.extname(validatedLocalPath).toLowerCase());
-        if (skipIfIdentical) {
-            const decision = await this.shouldSkipUpload(client, payload, validatedRemotePath, isShellScript);
-            if (decision.skip) {
-                return (`Upload skipped: remote file '${validatedRemotePath}' is already identical to local ` +
-                    `'${validatedLocalPath}' (${decision.reason}).${crlfNote}`);
+        debug?.(`[mcp] sftp upload on [${resolvedName}], reuseConnection=${reuseConnection}`);
+        let connection = null;
+        try {
+            connection = await this.acquireSshClient(resolvedName, {
+                reuseConnection,
+                timeout: options?.timeout,
+                debug,
+                purpose: "sftp",
+            });
+            const client = connection.client;
+            // ---- Skip-if-identical check ----
+            if (skipIfIdentical) {
+                const decision = await this.shouldSkipUpload(client, payload, validatedRemotePath, isShellScript, options?.timeout, debug);
+                if (decision.skip) {
+                    return this.appendDebugOutput(`Upload skipped: remote file '${validatedRemotePath}' is already identical to local ` +
+                        `'${validatedLocalPath}' (${decision.reason}).${crlfNote}`, debugCollector);
+                }
+            }
+            // ---- Actually upload ----
+            if (fastUpload && !crlfFixed.fixed) {
+                await this.sftpFastPut(client, validatedLocalPath, validatedRemotePath, options, options?.timeout, debug);
             }
+            else {
+                await this.sftpWriteBuffer(client, validatedRemotePath, payload, options?.timeout, debug);
+            }
+            const uploadedBytes = payload?.length ?? stat.size;
+            const modeNote = fastUpload && !crlfFixed.fixed ? " via fast SFTP" : "";
+            return this.appendDebugOutput(`File uploaded successfully (${uploadedBytes} bytes${modeNote})${crlfNote}`, debugCollector);
+        }
+        catch (error) {
+            if (reuseConnection && this.isConnectionError(error)) {
+                this.closeClient(resolvedName, true);
+            }
+            throw this.appendDebugToError(error, debugCollector);
+        }
+        finally {
+            connection?.close();
         }
-        // ---- Actually upload ----
-        await this.sftpWriteBuffer(client, validatedRemotePath, payload);
-        return `File uploaded successfully (${payload.length} bytes)${crlfNote}`;
     }
     /**
      * Threshold above which we use MD5 hash comparison instead of byte-content
@@ -1366,10 +1931,10 @@ export class SSHConnectionManager {
      * Any error during the check is treated as 'don't skip' (i.e. fall through
      * to a normal upload), since correctness wins over an optimization.
      */
-    async shouldSkipUpload(client, localPayload, remotePath, lineEndingAgnostic) {
+    async shouldSkipUpload(client, localPayload, remotePath, lineEndingAgnostic, timeout, debug) {
         let remoteSize;
         try {
-            const sftp = await this.openSftp(client, "dest");
+            const sftp = await this.openSftp(client, "dest", timeout, debug);
             try {
                 const stat = await this.sftpStat(sftp, remotePath, "dest");
                 remoteSize = stat.size;
@@ -1390,7 +1955,7 @@ export class SSHConnectionManager {
             }
             let remoteBuf;
             try {
-                remoteBuf = await this.sftpReadBuffer(client, remotePath, remoteSize);
+                remoteBuf = await this.sftpReadBuffer(client, remotePath, remoteSize, timeout, debug);
             }
             catch {
                 return { skip: false, reason: "remote-read-failed-during-content-compare" };
@@ -1413,7 +1978,7 @@ export class SSHConnectionManager {
             // Byte-content compare
             let remoteBuf;
             try {
-                remoteBuf = await this.sftpReadBuffer(client, remotePath, remoteSize);
+                remoteBuf = await this.sftpReadBuffer(client, remotePath, remoteSize, timeout, debug);
             }
             catch {
                 return { skip: false, reason: "remote-read-failed-during-content-compare" };
@@ -1449,88 +2014,138 @@ export class SSHConnectionManager {
     /**
      * Read an SFTP file fully into a Buffer.
      */
-    async sftpReadBuffer(client, remotePath, expectedSize) {
+    async sftpReadBuffer(client, remotePath, expectedSize, timeout, debug) {
+        const sftp = await this.openSftp(client, "read", timeout, debug);
         return new Promise((resolve, reject) => {
-            client.sftp((err, sftp) => {
-                if (err) {
-                    return reject(new ToolError("SFTP_ERROR", `SFTP open failed: ${err.message}`, true));
+            const chunks = [];
+            let received = 0;
+            const stream = sftp.createReadStream(remotePath);
+            stream.on("data", (chunk) => {
+                chunks.push(chunk);
+                received += chunk.length;
+            });
+            stream.on("error", (e) => {
+                sftp.end();
+                reject(this.makeSftpError("Remote read failed", e));
+            });
+            stream.on("end", () => {
+                sftp.end();
+                if (received !== expectedSize) {
+                    return reject(new ToolError("SFTP_ERROR", `Remote read short: expected ${expectedSize} bytes, got ${received}`, false));
                 }
-                const chunks = [];
-                let received = 0;
-                const stream = sftp.createReadStream(remotePath);
-                stream.on("data", (chunk) => {
-                    chunks.push(chunk);
-                    received += chunk.length;
-                });
-                stream.on("error", (e) => {
-                    sftp.end();
-                    reject(new ToolError("SFTP_ERROR", `Remote read failed: ${e.message}`, false));
-                });
-                stream.on("end", () => {
-                    sftp.end();
-                    if (received !== expectedSize) {
-                        return reject(new ToolError("SFTP_ERROR", `Remote read short: expected ${expectedSize} bytes, got ${received}`, false));
-                    }
-                    resolve(Buffer.concat(chunks, received));
-                });
+                resolve(Buffer.concat(chunks, received));
             });
         });
     }
     /**
      * Write a Buffer to an SFTP path (overwrites if exists).
      */
-    async sftpWriteBuffer(client, remotePath, payload) {
+    async sftpWriteBuffer(client, remotePath, payload, timeout, debug) {
+        const sftp = await this.openSftp(client, "write", timeout, debug);
         return new Promise((resolve, reject) => {
-            client.sftp((err, sftp) => {
+            const writeStream = sftp.createWriteStream(remotePath);
+            writeStream.on("close", () => {
+                sftp.end();
+                resolve();
+            });
+            writeStream.on("error", (e) => {
+                sftp.end();
+                reject(this.makeSftpError("File upload failed", e));
+            });
+            writeStream.end(payload);
+        });
+    }
+    /**
+     * Upload a local file using ssh2's parallel SFTP fastPut implementation.
+     */
+    async sftpFastPut(client, localPath, remotePath, options, timeout, debug) {
+        const sftp = await this.openSftp(client, "fastPut", timeout, debug);
+        const transferOptions = this.createSftpTransferOptions(options);
+        debug?.(`[mcp] fastPut ${localPath} -> ${remotePath}, concurrency=${transferOptions.concurrency ?? "ssh2-default"}, chunkSize=${transferOptions.chunkSize ?? "ssh2-default"}`);
+        return new Promise((resolve, reject) => {
+            sftp.fastPut(localPath, remotePath, transferOptions, (err) => {
+                sftp.end();
                 if (err) {
-                    return reject(new ToolError("SFTP_ERROR", `SFTP open failed: ${err.message}`, true));
+                    reject(this.makeSftpError("Fast upload failed", err));
+                    return;
                 }
-                const writeStream = sftp.createWriteStream(remotePath);
-                writeStream.on("close", () => {
-                    sftp.end();
-                    resolve();
-                });
-                writeStream.on("error", (e) => {
-                    sftp.end();
-                    reject(new ToolError("SFTP_ERROR", `File upload failed: ${e.message}`, false));
-                });
-                writeStream.end(payload);
+                resolve();
+            });
+        });
+    }
+    /**
+     * Download a remote file using ssh2's parallel SFTP fastGet implementation.
+     */
+    async sftpFastGet(client, remotePath, localPath, options, timeout, debug) {
+        const sftp = await this.openSftp(client, "fastGet", timeout, debug);
+        const transferOptions = this.createSftpTransferOptions(options);
+        debug?.(`[mcp] fastGet ${remotePath} -> ${localPath}, concurrency=${transferOptions.concurrency ?? "ssh2-default"}, chunkSize=${transferOptions.chunkSize ?? "ssh2-default"}`);
+        return new Promise((resolve, reject) => {
+            sftp.fastGet(remotePath, localPath, transferOptions, (err) => {
+                sftp.end();
+                if (err) {
+                    reject(this.makeSftpError("Fast download failed", err));
+                    return;
+                }
+                resolve();
             });
         });
     }
     /**
      * Download file
      */
-    async download(remotePath, localPath, name) {
+    async download(remotePath, localPath, name, options) {
         const resolvedName = name || this.defaultName;
+        const reuseConnection = options?.reuseConnection !== false;
+        const { collector: debugCollector, debug } = this.createDebugCollector(options?.vvv === true);
         const validatedLocalPath = this.validateLocalPath(localPath, resolvedName);
         const validatedRemotePath = this.validateRemotePath(remotePath, resolvedName);
-        const client = await this.ensureConnected(resolvedName);
-        return new Promise((resolve, reject) => {
-            client.sftp((err, sftp) => {
-                if (err) {
-                    return reject(new ToolError("SFTP_ERROR", `SFTP connection failed: ${err.message}`, true));
-                }
+        debug?.(`[mcp] sftp download on [${resolvedName}], reuseConnection=${reuseConnection}`);
+        let connection = null;
+        try {
+            connection = await this.acquireSshClient(resolvedName, {
+                reuseConnection,
+                timeout: options?.timeout,
+                debug,
+                purpose: "sftp",
+            });
+            if (options?.fast === true) {
+                await this.sftpFastGet(connection.client, validatedRemotePath, validatedLocalPath, options, options?.timeout, debug);
+                return this.appendDebugOutput("File downloaded successfully via fast SFTP", debugCollector);
+            }
+            const sftp = await this.openSftp(connection.client, "download", options?.timeout, debug);
+            await new Promise((resolve, reject) => {
+                let settled = false;
                 const readStream = sftp.createReadStream(validatedRemotePath);
                 const writeStream = fs.createWriteStream(validatedLocalPath);
-                const cleanup = () => {
+                const settle = (err) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    if (err) {
+                        this.unpipeStream(readStream, writeStream);
+                        this.destroyStream(readStream);
+                        this.destroyStream(writeStream);
+                    }
                     sftp.end();
+                    err ? reject(err) : resolve();
                 };
-                writeStream.on("finish", () => {
-                    cleanup();
-                    resolve("File downloaded successfully");
-                });
-                writeStream.on("error", (err) => {
-                    cleanup();
-                    reject(new ToolError("LOCAL_FILE_WRITE_FAILED", `Failed to save file: ${err.message}`, false));
-                });
-                readStream.on("error", (err) => {
-                    cleanup();
-                    reject(new ToolError("SFTP_ERROR", `File download failed: ${err.message}`, false));
-                });
+                writeStream.on("finish", () => settle());
+                writeStream.on("error", (err) => settle(new ToolError("LOCAL_FILE_WRITE_FAILED", `Failed to save file: ${err.message}`, false)));
+                readStream.on("error", (err) => settle(this.makeSftpError("File download failed", err)));
                 readStream.pipe(writeStream);
             });
-        });
+            return this.appendDebugOutput("File downloaded successfully", debugCollector);
+        }
+        catch (error) {
+            if (reuseConnection && this.isConnectionError(error)) {
+                this.closeClient(resolvedName, true);
+            }
+            throw this.appendDebugToError(error, debugCollector);
+        }
+        finally {
+            connection?.close();
+        }
     }
     /**
      * Disconnect SSH connection
@@ -1624,11 +2239,30 @@ export class SSHConnectionManager {
         const validatedSourcePath = this.validateRemotePath(sourceRemotePath, sourceName);
         const validatedDestPath = this.validateRemotePath(destRemotePath, destName);
         const skipIfIdentical = options?.skipIfIdentical !== false; // default true
-        const srcClient = await this.ensureConnected(sourceName);
-        const dstClient = await this.ensureConnected(destName);
-        const srcSftp = await this.openSftp(srcClient, "source");
-        const dstSftp = await this.openSftp(dstClient, "dest");
+        const reuseConnection = options?.reuseConnection !== false;
+        const { collector: debugCollector, debug } = this.createDebugCollector(options?.vvv === true);
+        debug?.(`[mcp] sftp relay ${sourceName} -> ${destName}, reuseConnection=${reuseConnection}`);
+        let srcConnection = null;
+        let dstConnection = null;
+        let srcSftp = null;
+        let dstSftp = null;
         try {
+            srcConnection = await this.acquireSshClient(sourceName, {
+                reuseConnection,
+                timeout: options?.timeout,
+                debug,
+                purpose: "sftp",
+            });
+            dstConnection = await this.acquireSshClient(destName, {
+                reuseConnection,
+                timeout: options?.timeout,
+                debug,
+                purpose: "sftp",
+            });
+            const srcClient = srcConnection.client;
+            const dstClient = dstConnection.client;
+            srcSftp = await this.openSftp(srcClient, "source", options?.timeout, debug);
+            dstSftp = await this.openSftp(dstClient, "dest", options?.timeout, debug);
             // Get source file size before transfer
             const srcStat = await this.sftpStat(srcSftp, validatedSourcePath, "source");
             // Skip-if-identical: same size on both sides AND matching md5sum (when
@@ -1645,10 +2279,10 @@ export class SSHConnectionManager {
                     if (srcMd5 && dstMd5 && srcMd5 === dstMd5) {
                         const srcConfig = this.getConfig(sourceName);
                         const dstConfig = this.getConfig(destName);
-                        return (`Transfer skipped: destination already identical ` +
+                        return this.appendDebugOutput(`Transfer skipped: destination already identical ` +
                             `(size=${srcStat.size} bytes, md5=${srcMd5}). ` +
                             `${srcConfig.username}@${srcConfig.host}:${validatedSourcePath}` +
-                            ` == ${dstConfig.username}@${dstConfig.host}:${validatedDestPath}`);
+                            ` == ${dstConfig.username}@${dstConfig.host}:${validatedDestPath}`, debugCollector);
                     }
                 }
             }
@@ -1664,11 +2298,16 @@ export class SSHConnectionManager {
                     if (settled)
                         return;
                     settled = true;
+                    if (err) {
+                        this.unpipeStream(readStream, writeStream);
+                        this.destroyStream(readStream);
+                        this.destroyStream(writeStream);
+                    }
                     err ? reject(err) : resolve();
                 };
                 writeStream.on("close", () => settle());
-                writeStream.on("error", (err) => settle(new ToolError("SFTP_ERROR", `Dest write error: ${err.message}`, false)));
-                readStream.on("error", (err) => settle(new ToolError("SFTP_ERROR", `Source read error: ${err.message}`, false)));
+                writeStream.on("error", (err) => settle(this.makeSftpError("Dest write error", err)));
+                readStream.on("error", (err) => settle(this.makeSftpError("Source read error", err)));
                 readStream.pipe(writeStream);
             });
             // --- Verification ---
@@ -1692,13 +2331,22 @@ export class SSHConnectionManager {
             }
             const srcConfig = this.getConfig(sourceName);
             const dstConfig = this.getConfig(destName);
-            return (`Transfer complete (streamed via SFTP, verified: ${verification.join(", ")}): ` +
+            return this.appendDebugOutput(`Transfer complete (streamed via SFTP, verified: ${verification.join(", ")}): ` +
                 `${srcConfig.username}@${srcConfig.host}:${sourceRemotePath}` +
-                ` → ${dstConfig.username}@${dstConfig.host}:${destRemotePath}`);
+                ` → ${dstConfig.username}@${dstConfig.host}:${destRemotePath}`, debugCollector);
+        }
+        catch (error) {
+            if (reuseConnection && this.isConnectionError(error)) {
+                this.closeClient(sourceName, true);
+                this.closeClient(destName, true);
+            }
+            throw this.appendDebugToError(error, debugCollector);
         }
         finally {
-            srcSftp.end();
-            dstSftp.end();
+            srcSftp?.end();
+            dstSftp?.end();
+            srcConnection?.close();
+            dstConnection?.close();
         }
     }
     /**
@@ -1708,7 +2356,7 @@ export class SSHConnectionManager {
         return new Promise((resolve, reject) => {
             sftp.stat(remotePath, (err, stats) => {
                 if (err) {
-                    return reject(new ToolError("SFTP_ERROR", `Failed to stat ${label} file: ${err.message}`, false));
+                    return reject(this.makeSftpError(`Failed to stat ${label} file`, err));
                 }
                 resolve({ size: stats.size });
             });
@@ -1745,40 +2393,68 @@ export class SSHConnectionManager {
     /**
      * Open an SFTP session from an existing SSH client.
      */
-    openSftp(client, label) {
-        return new Promise((resolve, reject) => {
+    openSftp(client, label, timeout, debug) {
+        const open = new Promise((resolve, reject) => {
             client.sftp((err, sftp) => {
                 if (err) {
-                    return reject(new ToolError("SFTP_ERROR", `SFTP connection failed (${label}): ${err.message}`, true));
+                    return reject(this.makeSftpError(`SFTP connection failed (${label})`, err));
                 }
+                debug?.(`[mcp] sftp channel opened (${label})`);
                 resolve(sftp);
             });
         });
+        return this.withConnectionTimeout(open, this.normalizeConnectTimeout(timeout), `SFTP channel open (${label})`, debug, undefined, (sftp) => {
+            try {
+                sftp.end();
+            }
+            catch {
+                // Ignore late SFTP cleanup errors.
+            }
+        });
     }
     /**
      * List remote files/directories via SFTP readdir
      */
-    async listRemoteDir(remotePath, name) {
-        const client = await this.ensureConnected(name);
-        return new Promise((resolve, reject) => {
-            client.sftp((err, sftp) => {
-                if (err) {
-                    return reject(new ToolError("SFTP_ERROR", `SFTP connection failed: ${err.message}`, true));
-                }
-                sftp.readdir(remotePath, (err, list) => {
-                    sftp.end();
-                    if (err) {
-                        return reject(new ToolError("SFTP_ERROR", `Failed to list remote directory: ${err.message}`, false));
-                    }
-                    const entries = list.map((entry) => ({
-                        filename: entry.filename,
-                        isDirectory: (entry.attrs.mode & 0o40000) !== 0,
-                        size: entry.attrs.size,
-                    }));
-                    resolve(entries);
-                });
+    async listRemoteDir(remotePath, name, options) {
+        const resolvedName = name || this.defaultName;
+        const reuseConnection = options?.reuseConnection !== false;
+        const { collector: debugCollector, debug } = this.createDebugCollector(options?.vvv === true);
+        debug?.(`[mcp] sftp list on [${resolvedName}], reuseConnection=${reuseConnection}`);
+        let connection = null;
+        try {
+            connection = await this.acquireSshClient(resolvedName, {
+                reuseConnection,
+                timeout: options?.timeout,
+                debug,
+                purpose: "sftp",
             });
-        });
+            const entries = await new Promise((resolve, reject) => {
+                this.openSftp(connection.client, "list", options?.timeout, debug).then((sftp) => {
+                    sftp.readdir(remotePath, (err, list) => {
+                        sftp.end();
+                        if (err) {
+                            return reject(this.makeSftpError("Failed to list remote directory", err));
+                        }
+                        const entries = list.map((entry) => ({
+                            filename: entry.filename,
+                            isDirectory: (entry.attrs.mode & 0o40000) !== 0,
+                            size: entry.attrs.size,
+                        }));
+                        resolve(entries);
+                    });
+                }, reject);
+            });
+            return entries;
+        }
+        catch (error) {
+            if (reuseConnection && this.isConnectionError(error)) {
+                this.closeClient(resolvedName, true);
+            }
+            throw this.appendDebugToError(error, debugCollector);
+        }
+        finally {
+            connection?.close();
+        }
     }
     /**
      * Upload a local directory recursively to a remote server
@@ -1791,8 +2467,28 @@ export class SSHConnectionManager {
             throw new ToolError("LOCAL_FILE_READ_FAILED", `Not a directory: ${localDir}`, false);
         }
         const results = [];
-        const client = await this.ensureConnected(resolvedName);
-        await this.sftpMkdirRecursive(client, validatedRemoteDir);
+        const reuseConnection = options?.reuseConnection !== false;
+        const { collector: debugCollector, debug } = this.createDebugCollector(options?.vvv === true);
+        debug?.(`[mcp] sftp recursive upload mkdir on [${resolvedName}], reuseConnection=${reuseConnection}`);
+        let connection = null;
+        try {
+            connection = await this.acquireSshClient(resolvedName, {
+                reuseConnection,
+                timeout: options?.timeout,
+                debug,
+                purpose: "sftp",
+            });
+            await this.sftpMkdirRecursive(connection.client, validatedRemoteDir, options?.timeout, debug);
+        }
+        catch (error) {
+            if (reuseConnection && this.isConnectionError(error)) {
+                this.closeClient(resolvedName, true);
+            }
+            throw this.appendDebugToError(error, debugCollector);
+        }
+        finally {
+            connection?.close();
+        }
         const entries = fs.readdirSync(resolvedLocal, { withFileTypes: true });
         for (const entry of entries) {
             const localPath = path.join(localDir, entry.name);
@@ -1811,7 +2507,7 @@ export class SSHConnectionManager {
     /**
      * Download a remote directory recursively to a local path
      */
-    async downloadDirectory(remoteDir, localDir, name) {
+    async downloadDirectory(remoteDir, localDir, name, options) {
         const resolvedName = name || this.defaultName;
         const resolvedLocal = this.validateLocalPath(localDir, resolvedName);
         const validatedRemoteDir = this.validateRemotePath(remoteDir, resolvedName);
@@ -1819,18 +2515,18 @@ export class SSHConnectionManager {
             fs.mkdirSync(resolvedLocal, { recursive: true });
         }
         const results = [];
-        const entries = await this.listRemoteDir(validatedRemoteDir, resolvedName);
+        const entries = await this.listRemoteDir(validatedRemoteDir, resolvedName, options);
         for (const entry of entries) {
             if (entry.filename === "." || entry.filename === "..")
                 continue;
             const remotePath = `${validatedRemoteDir}/${entry.filename}`;
             const localPath = path.join(localDir, entry.filename);
             if (entry.isDirectory) {
-                const subResults = await this.downloadDirectory(remotePath, localPath, resolvedName);
+                const subResults = await this.downloadDirectory(remotePath, localPath, resolvedName, options);
                 results.push(...subResults);
             }
             else {
-                await this.download(remotePath, localPath, resolvedName);
+                await this.download(remotePath, localPath, resolvedName, options);
                 results.push(localPath);
             }
         }
@@ -1839,27 +2535,23 @@ export class SSHConnectionManager {
     /**
      * Create remote directory recursively via SFTP
      */
-    async sftpMkdirRecursive(client, remotePath) {
-        return new Promise((resolve, reject) => {
-            client.sftp((err, sftp) => {
-                if (err) {
-                    return reject(new ToolError("SFTP_ERROR", `SFTP connection failed: ${err.message}`, true));
+    async sftpMkdirRecursive(client, remotePath, timeout, debug) {
+        const sftp = await this.openSftp(client, "mkdir", timeout, debug);
+        return new Promise((resolve) => {
+            const parts = remotePath.split("/").filter(Boolean);
+            let current = "";
+            const mkdirNext = (index) => {
+                if (index >= parts.length) {
+                    sftp.end();
+                    return resolve();
                 }
-                const parts = remotePath.split("/").filter(Boolean);
-                let current = "";
-                const mkdirNext = (index) => {
-                    if (index >= parts.length) {
-                        sftp.end();
-                        return resolve();
-                    }
-                    current += "/" + parts[index];
-                    sftp.mkdir(current, (err) => {
-                        // EEXIST is fine
-                        mkdirNext(index + 1);
-                    });
-                };
-                mkdirNext(0);
-            });
+                current += "/" + parts[index];
+                sftp.mkdir(current, () => {
+                    // EEXIST is fine
+                    mkdirNext(index + 1);
+                });
+            };
+            mkdirNext(0);
         });
     }
 }