ssh-mcp 2.3.2 → 2.3.3

package/README.md

@@ -138,7 +138,7 @@ claude mcp add --transport stdio ssh-mcp -- ssh-mcp
 | `list-connections` | Discover available hosts and connection status | ✅ | — |
 | `list-sessions` | List active sessions per host | ✅ | — |
 | `open-session` | Create a named interactive (stateful) or background session | — | — |
-| `close-session` | Close a session, releasing resources | — | ✅ |
+| `close-session` | Close a session. A background session's command is signalled (INT/TERM/KILL) before its channel is dropped | — | ✅ |
 | `read-session-output` | Read output from background sessions (e.g., `tail -f`) | ✅ | — |
 | `read-command` | Execute allowlisted read-only commands (`ls`, `cat`, `grep`, ...) | ✅ | — |
 | `run-command` | Execute arbitrary commands (destructive ones need approval) | — | — |

package/build/index.js

@@ -268,14 +268,29 @@ async function main() {
         console.error('SSH MCP Server v2 running on stdio');
     }
     const reaperInterval = setInterval(() => {
-        for (const info of registry.listConnections()) {
-            const conn = registry.get(info.profile);
-            if (conn) {
-                conn.reapExpiredSessions();
-            }
-        }
-        registry.reapIdleConnections();
+        // Session reaping is awaited before connection reaping, and that order is load-bearing:
+        // closing a background session now signals its command, and `reapIdleConnections` gates
+        // on `sessionCount`, which drops to zero as soon as a session is closed. Fired without
+        // awaiting, the connection was torn down microseconds after the first signal and the
+        // TERM and KILL rungs were discarded — so a command that ignores INT survived its own
+        // reaping.
+        void (async () => {
+            const conns = registry.listConnections()
+                .map((info) => registry.get(info.profile))
+                .filter((c) => Boolean(c));
+            await Promise.all(conns.map((conn) => conn.reapExpiredSessions().catch(() => { })));
+            registry.reapIdleConnections();
+        })();
     }, 60_000);
+    /**
+     * How long teardown gets before the process exits regardless.
+     *
+     * One kill ladder (3s) plus slack. Sessions and connections close concurrently, so this
+     * is the whole budget rather than a per-session one. Docker's default stop grace is 10s
+     * and Kubernetes' is 30s, so this stays comfortably inside both — the point is that we
+     * choose the moment we give up rather than being SIGKILLed in the middle of it.
+     */
+    const SHUTDOWN_BUDGET_MS = 5000;
     let isShuttingDown = false;
     const cleanup = async () => {
         if (isShuttingDown)
@@ -283,14 +298,26 @@ async function main() {
         isShuttingDown = true;
         console.error('Shutting down SSH MCP Server...');
         clearInterval(reaperInterval);
+        // Audit first. An earlier version of this comment claimed session teardown wrote audit
+        // records that the old order dropped — it does not: nothing under src/ssh/ touches the
+        // audit store, only the `close-session` tool does, and that record is written and
+        // awaited during the tool call. So the reorder rescued nothing and put the final flush
+        // behind a teardown that now waits for kill ladders. Flushing first cannot lose a record
+        // that teardown does not write, and it survives a SIGKILL at the end of the grace period.
         try {
             await audit.close();
         }
         catch (e) {
             console.error('audit.close failed:', e);
         }
+        // Bounded, so `process.exit(0)` is reached deliberately rather than by the container
+        // runtime's SIGKILL. Teardown is concurrent now, so the honest ceiling is one kill
+        // ladder plus slack rather than one per session.
         try {
-            await registry.closeAll();
+            await Promise.race([
+                registry.closeAll(),
+                new Promise((resolve) => setTimeout(resolve, SHUTDOWN_BUDGET_MS).unref()),
+            ]);
         }
         catch (e) {
             console.error('closeAll failed:', e);

package/build/ssh/channel-signal.js

@@ -0,0 +1,193 @@
+/** Outgoing states in which the far end still has a channel to receive a request. */
+const OPEN_STATES = new Set(['open', 'eof']);
+/**
+ * Whether ssh2's own `Channel.signal()` would put this request on the wire.
+ *
+ * A deliberate copy of lib/Channel.js:241-243 in ssh2 1.17, and the single place to
+ * update when that changes. Copying it is what lets us tell "ssh2 will handle this"
+ * from "ssh2 will silently discard it" — the distinction the whole module exists for.
+ */
+function ssh2WillSend(ch) {
+    return ch.type === 'session' && ch.writable === true && ch.outgoing?.state === 'open';
+}
+/**
+ * Whether the transport can still carry a packet.
+ *
+ * ssh2 hands every packet to `onWrite`, which is `if (isWritable(sock)) sock.write(data)`
+ * (lib/client.js:303) — an unwritable socket means the packet is dropped with no error
+ * and no return value. Measured against 1.17.0: immediately after `client.end()`,
+ * `sock.writable` is false while `outgoing.state` is still `'eof'`, so the state guard
+ * below passes and the signal call returns without throwing. Reporting that as delivery
+ * is #146 one layer down, and it is reachable whenever a connection is closed under a
+ * running command — `SSHConnection.close()`, or the idle reaper, which does not consult
+ * `activeChannels`.
+ *
+ * All three of `isWritable`'s conjuncts, not just the first. The first version of this
+ * checked `sock.writable` alone, and ssh2 added the other two for a reason
+ * (nodejs/node#36029: `writable` stays true after the stream has ended). Measured:
+ *
+ *   allowHalfOpen=false, peer FIN -> writable=false, isWritable()=false   (agree)
+ *   allowHalfOpen=true,  peer FIN -> writable=true,  isWritable()=false   (disagree)
+ *
+ * and a ProxyJump connection's transport is exactly the second case — `connectConfig.sock`
+ * is a `forwardOut` channel, and ssh2's channels default to `allowHalfOpen: true`
+ * (lib/Channel.js:90). So the one-conjunct version was blind on the path that has its own
+ * integration test. Mirroring the whole predicate is also what `ssh2WillSend` does, and
+ * the asymmetry between the two was the actual defect.
+ */
+function onTheWire(ch) {
+    const sock = ch._client?._sock;
+    // Fail closed on a shape we cannot read: every other unknown in this module is reported
+    // as "not dispatched", and a guard whose job is to refuse when unsure must not be the
+    // one place that assumes the best.
+    if (sock === undefined || typeof sock.writable !== 'boolean')
+        return false;
+    return sock.writable && sock._readableState?.ended === false;
+}
+/**
+ * Send `name` to the process behind `channel`.
+ *
+ * Returns whether the request was **dispatched to the wire** — not whether the command
+ * stopped. Nothing in SSH acknowledges a signal request, the delivery semantics are the
+ * server's choice rather than the protocol's, and a target may refuse it outright, so
+ * "the process is gone" is not a fact this function can produce. What it can produce
+ * honestly is "I could not even ask", which is what the caller warns about, because a
+ * signal that goes nowhere while reporting success is the defect this module exists to
+ * remove.
+ */
+export function signalChannel(channel, name) {
+    const ch = channel;
+    const state = ch.outgoing?.state;
+    // Only session channels carry a process. ssh2 gates on this too, and a
+    // forwarded-tcpip channel has nothing to signal.
+    if (ch.type !== undefined && ch.type !== 'session')
+        return false;
+    // Already closing or closed: the request would have no channel to arrive on, and
+    // ssh2 may have handed the id to a new channel.
+    if (state !== undefined && !OPEN_STATES.has(state))
+        return false;
+    // Nothing can be dispatched through a socket ssh2 will not write to, and it will not
+    // tell us — so this has to be asked before either path claims success.
+    if (!onTheWire(ch))
+        return false;
+    // The supported path, taken whenever ssh2 will actually write the request.
+    if (ssh2WillSend(ch)) {
+        try {
+            channel.signal(name);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    const id = ch.outgoing?.id;
+    const protocol = ch._client?._protocol;
+    if (typeof id === 'number' && typeof protocol?.signal === 'function') {
+        try {
+            protocol.signal(id, name);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    // A shape we do not recognise. Ask ssh2 and report failure anyway: we cannot tell
+    // whether it sent anything, and claiming delivery we cannot verify is what made
+    // this bug invisible for so long. An unnecessary "may still be running" warning is
+    // the better way to be wrong.
+    try {
+        channel.signal(name);
+    }
+    catch { /* nothing left to try */ }
+    return false;
+}
+/**
+ * Appended when a stop request could not even be dispatched, so nothing was asked of the
+ * host at all.
+ *
+ * Deliberately narrower than "the command is still running", which is not knowable from
+ * here: nothing acknowledges a signal request. Its *absence* therefore means "we asked",
+ * not "it died".
+ *
+ * It lives beside the function that decides it because two callers now need the same
+ * sentence — a timed-out or cancelled `exec`, and `close-session` on a background
+ * session. One contract, one place.
+ */
+export const COULD_NOT_SIGNAL = ' The remote command could not be signalled, so it may still be running on the host.';
+/** How long each signal is given to work before the next one is tried. */
+const ESCALATION_MS = 1000;
+/**
+ * Escalate until the command is gone: INT, then TERM, then KILL, then drop the
+ * channel.
+ *
+ * KILL is last because it denies the command any chance to clean up; it exists
+ * because the rung below it used to be `close()`, and closing a channel was measured
+ * not to stop anything. A command that ignores INT and TERM used to run forever.
+ *
+ * Returns whether the *first* signal was dispatched — known synchronously, so the
+ * caller can say "I could not even ask" in the same breath as the timeout it is already
+ * reporting. It is not a claim that the command stopped, and callers must not read it
+ * as one: the later rungs have not run yet, and no rung is acknowledged by anything.
+ */
+export function terminateChannel(channel) {
+    const dispatched = signalChannel(channel, 'INT');
+    const pending = [];
+    const later = (fn, ms) => {
+        // Unreferenced: this ladder outlives the promise it settled by up to three
+        // seconds, and a referenced timer would add that to the exit of any process
+        // whose last act was a timed-out command.
+        pending.push(setTimeout(fn, ms).unref());
+    };
+    const stop = () => { for (const t of pending)
+        clearTimeout(t); pending.length = 0; };
+    // Nothing more to send once the channel is gone, and the id may be reused.
+    channel.once('close', stop);
+    later(() => { signalChannel(channel, 'TERM'); }, ESCALATION_MS);
+    later(() => { signalChannel(channel, 'KILL'); }, ESCALATION_MS * 2);
+    later(() => { try {
+        channel.close();
+    }
+    catch { /* already gone */ } }, ESCALATION_MS * 3);
+    return dispatched;
+}
+/**
+ * Wait for a channel to actually close, bounded.
+ *
+ * The ladder's rungs are timers, so `terminateChannel` returns long before the escalation
+ * has finished. Anything that tears the transport down afterwards — `SSHConnection.close()`
+ * calling `client.end()`, or the process exiting — cancels the rest of it, and a command
+ * that ignored INT then survives with no further escalation possible. Callers that are
+ * about to do that must wait here first.
+ *
+ * Resolves true if the channel closed, false on timeout. The default budget is the ladder
+ * plus a little, so a command that only dies to KILL still gets there.
+ */
+export function waitForChannelClose(channel, ms = ESCALATION_MS * 3 + 500) {
+    // ssh2 emits `'close'` exactly once, and `onCHANNEL_CLOSE` early-returns for a channel
+    // whose incoming state is already `'closed'` — so a listener attached after the fact
+    // never fires and the caller would burn the whole budget waiting for an event that has
+    // already happened. Not reachable through SessionManager today, because the session is
+    // removed from the map by that same emit; it is a trap for the next caller.
+    const incoming = channel.incoming;
+    if (incoming?.state === 'closed' || channel.destroyed)
+        return Promise.resolve(true);
+    return new Promise((resolve) => {
+        let settled = false;
+        const onClose = () => done(true);
+        const done = (closed) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            // Detached on the timeout path too: a timed-out wait would otherwise leave its
+            // closure attached to a channel that may outlive it.
+            channel.removeListener('close', onClose);
+            resolve(closed);
+        };
+        const timer = setTimeout(() => done(false), ms);
+        // Unreferenced so a hung channel cannot hold the process open; the caller is awaiting
+        // this, so the loop stays alive for as long as the caller itself does.
+        timer.unref();
+        channel.once('close', onClose);
+    });
+}

package/build/ssh/connection-registry.js

@@ -94,9 +94,10 @@ export class ConnectionRegistry {
         }
     }
     async closeAll() {
-        for (const conn of this.connections.values()) {
-            await conn.close().catch(() => { });
-        }
+        // Concurrently, for the reason SessionManager.closeAll gives: each connection now waits
+        // for its sessions' kill ladders, and serialising multiplied that wait by the number of
+        // profiles.
+        await Promise.all([...this.connections.values()].map((conn) => conn.close().catch(() => { })));
         this.connections.clear();
     }
 }

package/build/ssh/connection.js

@@ -6,6 +6,40 @@ import { tracer } from '../observability/tracer.js';
 import { redactText } from '../guard/redactor.js';
 import { shellSingleQuote } from '../guard/sanitizer.js';
 import { openWithRetry } from './channel-retry.js';
+import { terminateChannel, COULD_NOT_SIGNAL } from './channel-signal.js';
+/**
+ * Stop the command behind `channel`, record why on the span, and return the sentence the
+ * rejection should carry.
+ *
+ * Module scope rather than a closure inside `exec`: it captures nothing but the span, and
+ * at module scope it is directly testable with a stub span and a fake channel. It exists
+ * at all because the three settle paths used to inline this, and two of them computed the
+ * "unstopped" value for the message and then dropped it before the span — so
+ * `ssh.unstopped` was structurally incapable of being true for a cancelled command, which
+ * is the most common way an MCP client stops one.
+ */
+export function stopAndDescribe(span, reason, channel) {
+    span.setAttribute(reason, true);
+    // A null channel means the exec callback has not arrived yet. It does NOT mean nothing is
+    // running — ssh2 invokes that callback on CHANNEL_SUCCESS, which OpenSSH sends after
+    // forking the command — but there is nothing to warn about either: `onExecChannel` stops
+    // such a late channel the moment it arrives. Warning here would put "may still be
+    // running" on every timeout that races a slow channel open, and a warning that fires when
+    // nothing is wrong stops being read.
+    //
+    // Recorded as its own attribute rather than as `ssh.unstopped: false`, which would assert
+    // a clean stop this path cannot yet know about. The late-arrival handler emits the real
+    // answer on its own span.
+    if (channel === null) {
+        span.setAttribute('ssh.stopDeferred', true);
+        return '';
+    }
+    const dispatched = terminateChannel(channel);
+    // Set on every settle path, always, so "stopped cleanly" and "ran an older build" are not
+    // the same absent-attribute query.
+    span.setAttribute('ssh.unstopped', !dispatched);
+    return dispatched ? '' : COULD_NOT_SIGNAL;
+}
 export class SSHConnection {
     profile;
     client = null;
@@ -193,25 +227,9 @@ export class SSHConnection {
             const timeoutId = setTimeout(() => {
                 if (!resolved) {
                     resolved = true;
-                    if (activeStream) {
-                        try {
-                            activeStream.signal('INT');
-                        }
-                        catch { /* */ }
-                        setTimeout(() => {
-                            try {
-                                activeStream?.signal('TERM');
-                            }
-                            catch { /* */ }
-                            setTimeout(() => { try {
-                                activeStream?.close();
-                            }
-                            catch { /* */ } }, 1000);
-                        }, 1000);
-                    }
-                    span.setAttribute('ssh.timedOut', true);
+                    const note = stopAndDescribe(span, 'ssh.timedOut', activeStream);
                     span.end();
-                    reject(new Error(`Command timed out after ${timeoutMs}ms`));
+                    reject(new Error(`Command timed out after ${timeoutMs}ms${note}`));
                 }
             }, timeoutMs);
             const execOpts = {};
@@ -240,6 +258,23 @@ export class SSHConnection {
                     }
                     return;
                 }
+                // The promise may already have settled — the timeout can fire while
+                // `openWithRetry` is still in flight, and ssh2 only invokes this callback once
+                // the server has replied CHANNEL_SUCCESS, which OpenSSH sends *after* forking
+                // the command. Without this the command ran to completion on the host after the
+                // caller had been told it timed out, holding a channel and discarding its
+                // output: #146 exactly, in the one path the first fix did not cover.
+                if (resolved) {
+                    // On its own span: the exec span was ended when the promise settled, and an
+                    // attribute set on an ended span is silently dropped. Without this the one
+                    // outcome `stopAndDescribe` deferred would be unobservable — the shape this
+                    // whole change exists to remove.
+                    const late = tracer.startSpan('ssh.exec.lateStop');
+                    late.setAttribute('ssh.host', this.profile.host);
+                    late.setAttribute('ssh.unstopped', !terminateChannel(stream));
+                    late.end();
+                    return;
+                }
                 activeStream = stream;
                 this.activeChannels++;
                 let stdout = '';
@@ -261,42 +296,26 @@ export class SSHConnection {
                     if (opts.abortSignal.aborted) {
                         resolved = true;
                         clearTimeout(timeoutId);
+                        // Decremented here rather than on 'close', because the close listener
+                        // below is never attached on this path. The channel now outlives the
+                        // count by as long as the kill ladder takes.
                         this.activeChannels--;
                         // client.exec() has already dispatched the command, so rejecting
                         // without signalling left it running to completion on the host and
-                        // held a channel until it finished.
-                        try {
-                            stream.signal('INT');
-                        }
-                        catch { /* */ }
-                        try {
-                            stream.close();
-                        }
-                        catch { /* */ }
+                        // held a channel until it finished. Closing the channel does not stop
+                        // it either — only a delivered signal does (#146).
+                        const note = stopAndDescribe(span, 'ssh.aborted', stream);
                         span.end();
-                        reject(new Error('Command aborted before execution'));
+                        reject(new Error(`Command aborted before execution${note}`));
                         return;
                     }
                     const onAbort = () => {
                         if (!resolved) {
                             resolved = true;
                             clearTimeout(timeoutId);
-                            try {
-                                stream.signal('INT');
-                            }
-                            catch { /* */ }
-                            setTimeout(() => {
-                                try {
-                                    stream.signal('TERM');
-                                }
-                                catch { /* */ }
-                                setTimeout(() => { try {
-                                    stream.close();
-                                }
-                                catch { /* */ } }, 1000);
-                            }, 1000);
+                            const note = stopAndDescribe(span, 'ssh.aborted', stream);
                             span.end();
-                            reject(new Error('Command aborted'));
+                            reject(new Error(`Command aborted${note}`));
                         }
                     };
                     opts.abortSignal.addEventListener('abort', onAbort, { once: true });
@@ -359,8 +378,8 @@ export class SSHConnection {
     async closeSession(name) {
         return this.sessions.close(name);
     }
-    reapExpiredSessions() {
-        this.sessions.reapExpired();
+    async reapExpiredSessions() {
+        return this.sessions.reapExpired();
     }
     async close() {
         await this.sessions.closeAll();

package/build/ssh/session-manager.js

@@ -140,22 +140,43 @@ export class SessionManager {
         const session = this.sessions.get(name);
         if (!session)
             throw new Error(`Session "${name}" not found on ${this.deps.profile().name}`);
-        await session.close();
-        this.sessions.delete(name);
-    }
-    async closeAll() {
-        for (const name of [...this.sessions.keys()]) {
-            await this.close(name).catch(() => { });
+        try {
+            return await session.close();
         }
-    }
-    reapExpired() {
-        for (const [name, session] of this.sessions) {
-            if (session.isExpired()) {
-                session.close().catch(() => { });
+        finally {
+            // Guarded and in a `finally`, both because closing now awaits a kill ladder rather
+            // than returning on the next microtask. Unguarded, a reaper closing this session
+            // while the caller re-opened the same name would evict the *new* session — the
+            // hazard `register` already documents. Without the `finally`, a rejection left the
+            // entry behind forever, holding a `sessionMaxPerConnection` slot and blocking the
+            // name.
+            if (this.sessions.get(name) === session)
                 this.sessions.delete(name);
-            }
         }
     }
+    async closeAll() {
+        // Concurrently. The ladders are independent timers on independent channels, and
+        // sequentially this was measured at 10.0s for five commands that ignore INT and TERM —
+        // past Docker's 10s default stop grace, so the container was SIGKILLed mid-teardown and
+        // the later sessions got no escalation at all. Before the ladder was awaited each
+        // session at least received its INT immediately, so serialising made the tail worse
+        // than the bug it fixed.
+        await Promise.all([...this.sessions.keys()].map((name) => this.close(name).catch(() => { })));
+    }
+    /**
+     * Close every expired session, awaiting the escalation.
+     *
+     * Awaited, and async for that reason. Fire-and-forget left exactly one hole in the
+     * guarantee `waitForChannelClose` exists for: `close()` dispatched INT and returned, the
+     * entry was deleted so `sessionCount` hit zero in the same tick, and the reaper's very
+     * next call — `reapIdleConnections`, which gates on `sessionCount` — closed the
+     * connection and ended the client microseconds later. TERM and KILL were then discarded,
+     * so a background command that ignores INT survived its own reaping.
+     */
+    async reapExpired() {
+        const expired = [...this.sessions.entries()].filter(([, s]) => s.isExpired());
+        await Promise.all(expired.map(([name]) => this.close(name).catch(() => { })));
+    }
     markAllDisconnected() {
         for (const session of this.sessions.values()) {
             session.markDisconnected();

package/build/ssh/session.js

@@ -1,5 +1,6 @@
 import { randomBytes } from 'crypto';
 import { tracer } from '../observability/tracer.js';
+import { terminateChannel, waitForChannelClose } from './channel-signal.js';
 const ANSI_REGEX = /\x1b\[[0-9;?]*[a-zA-Z]|\x1b\][^\x07]*\x07|\r/g;
 export function stripAnsi(text) {
     return text.replace(ANSI_REGEX, '');
@@ -250,6 +251,9 @@ export class InteractiveSession extends Session {
         }
         catch { /* ignore */ }
         this._status = 'closed';
+        // Nothing remote is signalled here: an interactive session's stop is `^C` written into
+        // its live pty during a command, and closing the session just ends the shell.
+        return 'closed';
     }
     get currentCwd() {
         return this.cwd;
@@ -341,10 +345,30 @@ export class BackgroundSession extends Session {
         throw new Error('Background sessions do not support run(). The command was started when the session was opened.');
     }
     async close() {
-        try {
-            this.stream.close();
-        }
-        catch { /* ignore */ }
+        // Signalled, not just closed. A background session runs on an exec channel, and
+        // closing such a channel was measured not to stop the command (#146) — so
+        // `close-session` reported `status: 'closed'` while `tail -f` kept running on the
+        // host, which is the same false claim the exec path stopped making.
+        const dispatched = terminateChannel(this.stream);
+        // Our side is closed either way — the session is being torn down and the caller is not
+        // getting it back. What varies is whether the *host* stopped, which the outcome carries.
         this._status = 'closed';
+        if (!dispatched)
+            return 'unsignalled';
+        // Awaited, because the ladder's later rungs are timers and whatever happens next may
+        // tear the transport down: `SSHConnection.close()` ends the client immediately after
+        // `closeAll()` returns, and shutdown calls `process.exit`. Returning early meant a
+        // command that ignored INT received nothing further and survived — the KILL rung
+        // exists precisely for that command. Bounded by the ladder's own length, so a command
+        // that dies to INT costs one round trip rather than three seconds.
+        //
+        // Skipped entirely when nothing was dispatched: no rung can be delivered through a
+        // transport that refused the first one, including the `channel.close()` rung, so
+        // `'close'` would never arrive and the wait was measured burning its full 3.5s for
+        // nothing.
+        //
+        // The old `stream.close()` released the channel synchronously; this releases it when
+        // the ladder finishes, which is why the wait is here rather than left to the caller.
+        return (await waitForChannelClose(this.stream)) ? 'closed' : 'stop-unconfirmed';
     }
 }

package/build/tools/descriptions.js

@@ -3,7 +3,7 @@ export const TOOL_DESCRIPTIONS = {
     'list-connections': 'List all configured SSH profiles and their connection status. Use this to discover available hosts before running commands.',
     'list-sessions': 'List active sessions for a given SSH profile.',
     'open-session': 'Open a named session on a remote host. Use type="interactive" for stateful shell (CWD/env persists between commands) or type="background" for long-running processes.',
-    'close-session': 'Close a named session, releasing its resources.',
+    'close-session': 'Close a named session. A background session\'s command is signalled on the host (INT, then TERM, then KILL) before its channel is dropped; an interactive session\'s shell is ended. The response says so if the command could not be signalled or had not stopped in time.',
     'read-session-output': 'Read recent output from a background session (e.g., tail -f logs).',
     'read-command': 'Execute a READ-ONLY command from an allowlist (ls, cat, grep, find, stat, df, etc.). This tool does NOT modify the system. Prefer this tool for all read operations.',
     'run-command': 'Execute an arbitrary shell command on the remote server. May modify the system. Destructive commands require user approval.',

package/build/tools/session-tools.js

@@ -2,11 +2,40 @@ import { z } from 'zod';
 import { sanitizeSessionName } from '../guard/sanitizer.js';
 import { redactText } from '../guard/redactor.js';
 import { BackgroundSession } from '../ssh/session.js';
+import { COULD_NOT_SIGNAL } from '../ssh/channel-signal.js';
 import { TOOL_DESCRIPTIONS as D } from './descriptions.js';
 import { syntheticSuccess, textResult } from './results.js';
 /** Connection and session discovery/lifecycle tools. */
+/**
+ * The evaluation recorded for a session release.
+ *
+ * Releasing a session is audited but never refused, which is why this is a constant rather
+ * than an engine call. The first version of this routed the close through `runAudited`, and
+ * that made the stop *refusable*: `session:close <name>` classifies as `safe`, so a
+ * `readOnly` profile — which can open a background session, because a `tail -f` classifies
+ * `read-only` — was denied permission to close it, and had no other way to stop the
+ * command for an hour. `ask-all` prompted on every close, and an exhausted
+ * `commandQuotaPerDay` wedged the profile entirely.
+ *
+ * A control whose refusal mode is "the thing you asked me to stop keeps running" is worse
+ * than the unaudited stop it replaced. The record was the part worth having; the veto was
+ * not. `ruleId` says so, so the log distinguishes this from an engine `allow`.
+ */
+const RELEASE = {
+    decision: 'allow',
+    commandClass: 'safe',
+    binary: 'session:close',
+    ruleId: 'session-release',
+    reason: 'A session release is audited but not policy-gated; see SECURITY.md.',
+};
+/** What to append to the caller's confirmation for each outcome. */
+const CLOSE_NOTES = {
+    closed: '',
+    unsignalled: COULD_NOT_SIGNAL,
+    'stop-unconfirmed': ' The command was signalled but the channel had not closed in time, so it may still be running on the host.',
+};
 export function registerSessionTools({ server, registry }, pipeline) {
-    const { runAudited, resolveConn } = pipeline;
+    const { runAudited, resolveConn, auditResult, auditFailure, makeCtx, defaultProfileName } = pipeline;
     // ─── list-connections ──────────────────────────────────────────────────
     server.tool('list-connections', D["list-connections"], {}, { readOnlyHint: true }, async () => {
         const connections = registry.listConnections();
@@ -73,10 +102,35 @@ export function registerSessionTools({ server, registry }, pipeline) {
     server.tool('close-session', D["close-session"], {
         name: z.string().describe('Session name to close'),
         profile: z.string().optional().describe('Profile name'),
-    }, { destructiveHint: true }, async ({ name, profile }) => {
+    }, { destructiveHint: true }, async ({ name, profile }, extra) => {
+        const cleanName = sanitizeSessionName(name);
+        const profileName = defaultProfileName(profile);
+        const ctx = makeCtx(extra, profileName, cleanName);
         const conn = await resolveConn(profile);
-        await conn.closeSession(name);
-        return textResult(`Session "${name}" closed.`);
+        // Recorded with the session's kind, so a remote SIGKILL is greppable in the log and
+        // distinguishable from ending a local shell — `open-session` encodes its type the
+        // same way.
+        // Through `toInfo()` rather than an `instanceof` check: the type is public API, and a
+        // tool handler reaching for a constructor identity is the layer leak this repo's own
+        // rules call out.
+        const kind = conn.getSession(cleanName)?.toInfo().type ?? 'unknown';
+        const command = `session:close ${kind} ${cleanName}`;
+        const startedAt = Date.now();
+        try {
+            const outcome = await conn.closeSession(cleanName);
+            await auditResult(ctx, profileName, command, RELEASE, {
+                stdout: '',
+                stderr: '',
+                exitCode: outcome === 'closed' ? 0 : 1,
+                durationMs: Date.now() - startedAt,
+                profile: profileName,
+            });
+            return textResult(`Session "${cleanName}" closed.${CLOSE_NOTES[outcome]}`);
+        }
+        catch (err) {
+            await auditFailure(ctx, profileName, { command }, 'safe', err);
+            throw err;
+        }
     });
     // ─── read-session-output ───────────────────────────────────────────────
     server.tool('read-session-output', D["read-session-output"], {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ssh-mcp",
   "license": "MIT",
-  "version": "2.3.2",
+  "version": "2.3.3",
   "description": "MCP server exposing policy-gated, audited SSH access for Linux and Windows hosts via the Model Context Protocol.",
   "type": "module",
   "bin": {