@aaarc/handfree-ssh-mcp 1.0.6 → 1.0.9

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

@@ -125,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");
@@ -197,6 +194,12 @@ 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);
@@ -209,10 +212,7 @@ export class SSHConnectionManager {
                 affected.add(target);
             }
         }
-        for (const target of affected) {
-            this.closeClient(target, true);
-            this.statusCache.delete(target);
-        }
+        this.closeClientSet(affected, true);
         return {
             requested: key,
             closed: Array.from(affected),
@@ -496,15 +496,34 @@ 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);
+    }
     /**
-     * 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.
+     * 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 = `__command__:${key}:${Date.now()}:${crypto.randomBytes(4).toString("hex")}`;
+        const jumpChainKey = `__${purpose}__:${key}:${Date.now()}:${crypto.randomBytes(4).toString("hex")}`;
         const connectTimeout = this.normalizeConnectTimeout(timeout) ?? 30000;
         let settled = false;
         let closed = false;
@@ -513,7 +532,7 @@ export class SSHConnectionManager {
                 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");
+            Logger.log(`One-shot SSH ${purpose} client [${key}] emitted error after settle: ${err.message}`, "error");
         };
         client.on("error", onLateError);
         const close = () => {
@@ -560,11 +579,11 @@ export class SSHConnectionManager {
                         }
                         this.teardownJumpChain(jumpChainKey);
                     });
-                    Logger.log(`Using one-shot jump host '${config.jumpHost}' for command on [${key}]`, "info");
+                    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 [${key}] via '${config.jumpHost}': ${err.message}`, true);
+                    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) {
@@ -611,7 +630,7 @@ export class SSHConnectionManager {
                 sshConfig.password = config.password;
             }
             else if (agent || config.authOptional) {
-                Logger.log(`Using SSH agent/default authentication for one-shot command [${key}]`, "info");
+                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);
@@ -631,19 +650,19 @@ export class SSHConnectionManager {
                         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 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 command connection [${key}] timed out after ${connectTimeout}ms`, true));
+                    done(new ToolError("SSH_CONNECTION_FAILED", `SSH ${purpose} connection [${key}] timed out after ${connectTimeout}ms`, true));
                     close();
                 }, connectTimeout);
-                debug?.(`[mcp] opening one-shot SSH connection for [${key}]`);
+                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 command connection for [${key}]`, "info");
+            Logger.log(`Opened one-shot SSH ${purpose} connection for [${key}]`, "info");
             return { client, close };
         }
         catch (err) {
@@ -700,7 +719,63 @@ export class SSHConnectionManager {
         if (typeof timeout !== "number" || !Number.isFinite(timeout) || timeout <= 0) {
             return undefined;
         }
-        return Math.max(1, Math.min(timeout, 30000));
+        return Math.max(1, timeout);
+    }
+    /**
+     * Run a transfer that reports progress through a callback, aborting it if no
+     * progress arrives within `timeoutMs` (an INACTIVITY watchdog, not a total
+     * duration cap -- a long but actively-streaming transfer is never killed).
+     * When `timeoutMs` is falsy the operation runs unbounded, preserving the
+     * previous behavior. `onTimeout` is invoked to tear down the stalled session.
+     */
+    runWithInactivityTimeout(start, timeoutMs, description, debug, onTimeout) {
+        if (!timeoutMs || timeoutMs <= 0) {
+            return start(() => { });
+        }
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            let timer = null;
+            const clear = () => {
+                if (timer) {
+                    clearTimeout(timer);
+                    timer = null;
+                }
+            };
+            const arm = () => {
+                clear();
+                timer = setTimeout(() => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    debug?.(`[mcp] ${description} stalled: no progress for ${timeoutMs}ms`);
+                    try {
+                        onTimeout?.();
+                    }
+                    catch {
+                        // Ignore cleanup failures after a stall.
+                    }
+                    reject(new ToolError("SSH_CONNECTION_FAILED", `${description} stalled: no progress for ${timeoutMs}ms`, true));
+                }, timeoutMs);
+            };
+            const onProgress = () => {
+                if (!settled)
+                    arm();
+            };
+            arm();
+            start(onProgress).then((value) => {
+                if (settled)
+                    return;
+                settled = true;
+                clear();
+                resolve(value);
+            }, (err) => {
+                if (settled)
+                    return;
+                settled = true;
+                clear();
+                reject(err);
+            });
+        });
     }
     /**
      * Open a TCP tunnel from the target's jump chain to `config.host:config.port`
@@ -994,6 +1069,31 @@ export class SSHConnectionManager {
             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
      * @private
@@ -1262,12 +1362,29 @@ export class SSHConnectionManager {
         return new Promise((resolve, reject) => {
             let timeoutId = null;
             let settled = false;
-            const cleanup = () => {
+            let channelOpened = false;
+            let activeStream = null;
+            const eventedClient = client;
+            const canObserveClientLifecycle = typeof eventedClient.once === "function" &&
+                typeof eventedClient.removeListener === "function";
+            const clearCommandTimer = () => {
                 if (timeoutId) {
                     clearTimeout(timeoutId);
                     timeoutId = null;
                 }
             };
+            const removeClientLifecycleListeners = () => {
+                if (!canObserveClientLifecycle) {
+                    return;
+                }
+                eventedClient.removeListener?.("error", onClientError);
+                eventedClient.removeListener?.("end", onClientEnd);
+                eventedClient.removeListener?.("close", onClientClose);
+            };
+            const cleanup = () => {
+                clearCommandTimer();
+                removeClientLifecycleListeners();
+            };
             const settle = (err, code) => {
                 if (settled)
                     return;
@@ -1286,8 +1403,26 @@ export class SSHConnectionManager {
                     // Ignore late-stream close errors after the promise has settled.
                 }
             };
+            const failOnClientEvent = (event, message) => {
+                const phase = channelOpened ? "running command" : "opening command channel";
+                const detail = message ? `: ${message}` : "";
+                sinks.debug?.(`[mcp] SSH client ${event} while ${phase}${detail}`);
+                if (activeStream) {
+                    closeLateStream(activeStream);
+                }
+                settle(new ToolError("SSH_CONNECTION_FAILED", `SSH connection ${event} while ${phase}${detail}`, true));
+            };
+            const onClientError = (err) => {
+                failOnClientEvent("failed", err.message);
+            };
+            const onClientEnd = () => {
+                failOnClientEvent("ended");
+            };
+            const onClientClose = () => {
+                failOnClientEvent("closed");
+            };
             const armExecOpenTimeout = () => {
-                const execOpenTimeout = Math.max(1, Math.min(timeout, 30000));
+                const execOpenTimeout = Math.max(1, timeout);
                 timeoutId = setTimeout(() => {
                     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));
@@ -1312,6 +1447,11 @@ export class SSHConnectionManager {
                 }, timeout);
             };
             armExecOpenTimeout();
+            if (canObserveClientLifecycle) {
+                eventedClient.once?.("error", onClientError);
+                eventedClient.once?.("end", onClientEnd);
+                eventedClient.once?.("close", onClientClose);
+            }
             sinks.debug?.(`[mcp] opening exec channel for command: ${cmdString}`);
             try {
                 client.exec(cmdString, (err, stream) => {
@@ -1327,7 +1467,9 @@ export class SSHConnectionManager {
                         settle(new ToolError(code, `Command execution error: ${err.message}`, isConnectionFailure));
                         return;
                     }
-                    cleanup();
+                    clearCommandTimer();
+                    channelOpened = true;
+                    activeStream = stream;
                     sinks.debug?.("[mcp] exec channel opened");
                     stream.on("data", (chunk) => {
                         sinks.stdoutCollector?.push(chunk);
@@ -1383,24 +1525,18 @@ export class SSHConnectionManager {
         };
     }
     appendDebugOutput(result, collector) {
-        if (!collector || collector.getTotalBytes() === 0) {
+        const debugBlock = this.formatDebugBlock(collector);
+        if (!debugBlock) {
             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()}`;
+        return `${result}\n\n${debugBlock}`;
     }
     appendDebugToError(error, collector) {
-        if (!collector || collector.getTotalBytes() === 0) {
+        const debugBlock = this.formatDebugBlock(collector);
+        if (!debugBlock) {
             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()}`;
+        const message = `${error.message}\n\n${debugBlock}`;
         if (error instanceof ToolError) {
             return new ToolError(error.code, message, error.retriable);
         }
@@ -1408,6 +1544,40 @@ export class SSHConnectionManager {
         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
@@ -1480,13 +1650,13 @@ export class SSHConnectionManager {
         for (let attempt = 0; attempt <= maxRetries; attempt++) {
             try {
                 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 commandConnection = await this.acquireSshClient(key, {
+                    reuseConnection,
+                    timeout,
+                    debug,
+                    purpose: "command",
+                });
                 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);
@@ -1573,13 +1743,13 @@ export class SSHConnectionManager {
         for (let attempt = 0; attempt <= maxRetries; attempt++) {
             try {
                 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 commandConnection = await this.acquireSshClient(key, {
+                    reuseConnection,
+                    timeout,
+                    debug,
+                    purpose: "command",
+                });
                 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);
@@ -1725,6 +1895,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
@@ -1740,32 +1912,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
@@ -1822,10 +2029,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;
@@ -1846,7 +2053,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" };
@@ -1869,7 +2076,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" };
@@ -1905,88 +2112,166 @@ 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) => {
-                if (err) {
-                    return reject(new ToolError("SFTP_ERROR", `SFTP open failed: ${err.message}`, true));
-                }
-                const writeStream = sftp.createWriteStream(remotePath);
-                writeStream.on("close", () => {
-                    sftp.end();
+            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) {
+        // Validate transfer options BEFORE opening the channel so invalid options
+        // can never leak an SFTP channel.
+        const transferOptions = this.createSftpTransferOptions(options);
+        const sftp = await this.openSftp(client, "fastPut", timeout, debug);
+        debug?.(`[mcp] fastPut ${localPath} -> ${remotePath}, concurrency=${transferOptions.concurrency ?? "ssh2-default"}, chunkSize=${transferOptions.chunkSize ?? "ssh2-default"}`);
+        const endSftp = () => {
+            try {
+                sftp.end();
+            }
+            catch {
+                // Ignore late SFTP cleanup errors.
+            }
+        };
+        try {
+            await this.runWithInactivityTimeout((onProgress) => new Promise((resolve, reject) => {
+                sftp.fastPut(localPath, remotePath, { ...transferOptions, step: () => onProgress() }, (err) => {
+                    if (err) {
+                        reject(this.makeSftpError("Fast upload failed", err));
+                        return;
+                    }
                     resolve();
                 });
-                writeStream.on("error", (e) => {
-                    sftp.end();
-                    reject(new ToolError("SFTP_ERROR", `File upload failed: ${e.message}`, false));
+            }), this.normalizeConnectTimeout(timeout), `fast upload ${localPath} -> ${remotePath}`, debug, endSftp);
+        }
+        finally {
+            endSftp();
+        }
+    }
+    /**
+     * Download a remote file using ssh2's parallel SFTP fastGet implementation.
+     */
+    async sftpFastGet(client, remotePath, localPath, options, timeout, debug) {
+        // Validate transfer options BEFORE opening the channel so invalid options
+        // can never leak an SFTP channel.
+        const transferOptions = this.createSftpTransferOptions(options);
+        const sftp = await this.openSftp(client, "fastGet", timeout, debug);
+        debug?.(`[mcp] fastGet ${remotePath} -> ${localPath}, concurrency=${transferOptions.concurrency ?? "ssh2-default"}, chunkSize=${transferOptions.chunkSize ?? "ssh2-default"}`);
+        const endSftp = () => {
+            try {
+                sftp.end();
+            }
+            catch {
+                // Ignore late SFTP cleanup errors.
+            }
+        };
+        try {
+            await this.runWithInactivityTimeout((onProgress) => new Promise((resolve, reject) => {
+                sftp.fastGet(remotePath, localPath, { ...transferOptions, step: () => onProgress() }, (err) => {
+                    if (err) {
+                        reject(this.makeSftpError("Fast download failed", err));
+                        return;
+                    }
+                    resolve();
                 });
-                writeStream.end(payload);
-            });
-        });
+            }), this.normalizeConnectTimeout(timeout), `fast download ${remotePath} -> ${localPath}`, debug, endSftp);
+        }
+        finally {
+            endSftp();
+        }
     }
     /**
      * 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
@@ -2080,11 +2365,35 @@ 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 selfRelay = sourceName === destName;
+        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",
+            });
+            // Same host on both ends: reuse the one SSH client (two SFTP channels are
+            // still opened below) so we never open or close a second connection.
+            dstConnection = selfRelay
+                ? srcConnection
+                : 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
@@ -2101,10 +2410,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);
                     }
                 }
             }
@@ -2120,11 +2429,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 ---
@@ -2148,13 +2462,24 @@ 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);
+                if (!selfRelay)
+                    this.closeClient(destName, true);
+            }
+            throw this.appendDebugToError(error, debugCollector);
         }
         finally {
-            srcSftp.end();
-            dstSftp.end();
+            srcSftp?.end();
+            dstSftp?.end();
+            srcConnection?.close();
+            if (!selfRelay)
+                dstConnection?.close();
         }
     }
     /**
@@ -2164,7 +2489,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 });
             });
@@ -2201,40 +2526,71 @@ 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));
+                    // A client that cannot open an SFTP channel is unusable, so treat the
+                    // failure as connection-shaped regardless of wording. This lets the
+                    // caller force-drop the stale cached client and self-heal on retry.
+                    return reject(new ToolError("SSH_CONNECTION_FAILED", `SFTP connection failed (${label}): ${err.message}`, true));
                 }
+                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
@@ -2247,8 +2603,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);
@@ -2267,7 +2643,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);
@@ -2275,18 +2651,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);
             }
         }
@@ -2295,27 +2671,39 @@ 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);
+        const walk = new Promise((resolve, reject) => {
+            const parts = remotePath.split("/").filter(Boolean);
+            let current = "";
+            const mkdirNext = (index) => {
+                if (index >= parts.length) {
+                    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) => {
+                    // An existing directory (or other non-connection failure) is fine and
+                    // just means the path component already exists. A connection-shaped
+                    // error means the channel died mid-walk -- surface it instead of
+                    // silently marching on (and eventually hanging the per-file uploads).
+                    if (err && this.isConnectionShapedMessage(err.message)) {
+                        return reject(this.makeSftpError("Remote mkdir failed", err));
                     }
-                    current += "/" + parts[index];
-                    sftp.mkdir(current, (err) => {
-                        // EEXIST is fine
-                        mkdirNext(index + 1);
-                    });
-                };
-                mkdirNext(0);
-            });
+                    mkdirNext(index + 1);
+                });
+            };
+            mkdirNext(0);
         });
+        try {
+            await this.withConnectionTimeout(walk, this.normalizeConnectTimeout(timeout), `SFTP mkdir ${remotePath}`, debug);
+        }
+        finally {
+            try {
+                sftp.end();
+            }
+            catch {
+                // Ignore late SFTP cleanup errors.
+            }
+        }
     }
 }