ssh-mcp 2.3.2 → 2.3.4

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,8 +1,9 @@
 {
   "name": "ssh-mcp",
   "license": "MIT",
-  "version": "2.3.2",
+  "version": "2.3.4",
   "description": "MCP server exposing policy-gated, audited SSH access for Linux and Windows hosts via the Model Context Protocol.",
+  "mcpName": "io.github.tufantunc/ssh-mcp",
   "type": "module",
   "bin": {
     "ssh-mcp": "build/index.js"
@@ -13,7 +14,7 @@
     "typecheck": "tsc --noEmit -p tsconfig.test.json",
     "inspect": "npx @modelcontextprotocol/inspector node build/index.js",
     "changeset": "changeset",
-    "version": "changeset version",
+    "version": "changeset version && node scripts/sync-server-json.mjs",
     "test": "cross-env SSH_MCP_DISABLE_MAIN=1 vitest --run",
     "test:unit": "cross-env SSH_MCP_DISABLE_MAIN=1 vitest --run test/unit/ test/property/",
     "test:integration": "cross-env SSH_MCP_DISABLE_MAIN=1 vitest --run test/integration/",