@akms/mcp-ssh 0.0.1

package/lib/cli.cjs

@@ -0,0 +1,3280 @@
+#!/usr/bin/env node
+'use strict';
+
+var stdio_js = require('@modelcontextprotocol/sdk/server/stdio.js');
+var os = require('os');
+var path2 = require('path');
+var crypto = require('crypto');
+var fs4 = require('fs');
+var string_decoder = require('string_decoder');
+var ssh2 = require('ssh2');
+var timers = require('timers');
+var mcp_js = require('@modelcontextprotocol/sdk/server/mcp.js');
+var zod = require('zod');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var os__default = /*#__PURE__*/_interopDefault(os);
+var path2__default = /*#__PURE__*/_interopDefault(path2);
+var fs4__default = /*#__PURE__*/_interopDefault(fs4);
+var ssh2__default = /*#__PURE__*/_interopDefault(ssh2);
+
+// src/_defs/defaults.ts
+var CONFIG_PATH_ENV = "SSH_MCP_CONFIG";
+var LOG_LEVEL_ENV = "SSH_MCP_LOG_LEVEL";
+var DEFAULT_CONFIG_FILENAMES = [
+  ".akms-ssh.json",
+  ".config/akms-ssh/config.json"
+];
+var DEFAULT_SSH_PORT = 22;
+var DEFAULT_EXEC_TIMEOUT_MS = 6e4;
+var DEFAULT_CONNECT_TIMEOUT_MS = 2e4;
+var DEFAULT_MAX_OUTPUT_CHARACTERS = 1e5;
+var DEFAULT_MAX_READ_FILE_BYTES = 2e5;
+var KEEPALIVE_INTERVAL_MS = 15e3;
+var SESSION_IDLE_TIMEOUT_MS = 15 * 60 * 1e3;
+var SESSION_SWEEP_INTERVAL_MS = 6e4;
+var CWD_MARKER = "__AKMS_SSH_CWD__";
+var MAX_DIRECTORY_ENTRIES = 1e3;
+var SERVER_NAME = "akms-ssh";
+var SERVER_VERSION = "0.0.1";
+
+// src/_defs/command-rules.ts
+var CRITICAL_PATH_PATTERN = new RegExp(
+  "^(?:/|//|/\\*|/\\.|/\\.\\.|/\\*/|//\\*|~|~/|~/\\*|\\$HOME|\\$HOME/|\\$HOME/\\*|\\$\\{HOME\\}/?\\*?|/(?:bin|boot|dev|etc|home|lib|lib32|lib64|libx32|media|mnt|opt|proc|root|run|sbin|srv|sys|usr|var|data)(?:/\\*)?/?)$",
+  "i"
+);
+var CRITICAL_FILE_PATTERN = new RegExp(
+  "^/(?:etc/(?:passwd|shadow|group|sudoers|fstab|hostname|hosts|resolv\\.conf)|boot/(?:vmlinuz|initrd|grub).*|etc/ssh/sshd_config)$",
+  "i"
+);
+var COMMAND_WRAPPER_BINARIES = [
+  "sudo",
+  "doas",
+  "env",
+  "eval",
+  "nohup",
+  "time",
+  "nice",
+  "ionice",
+  "timeout",
+  "stdbuf",
+  "command",
+  "exec",
+  "builtin",
+  "watch",
+  "xargs",
+  "setsid",
+  "unbuffer",
+  "busybox",
+  "toybox"
+];
+var NUMERIC_OPERAND_PATTERN = /^\d+(?:\.\d+)?[smhd]?$/i;
+var WRAPPER_VALUE_FLAGS = {
+  env: ["-u", "--unset", "-C", "--chdir", "-S", "--split-string"],
+  sudo: ["-u", "--user", "-g", "--group", "-p", "--prompt", "-C", "--close-from", "-h", "--host", "-D", "--chdir", "-R", "--chroot"],
+  doas: ["-u", "-C"],
+  timeout: ["-s", "--signal", "-k", "--kill-after"],
+  nice: ["-n", "--adjustment"],
+  ionice: ["-c", "--class", "-n", "--classdata", "-p", "--pid"],
+  stdbuf: ["-i", "--input", "-o", "--output", "-e", "--error"],
+  xargs: ["-a", "--arg-file", "-d", "--delimiter", "-E", "-I", "--replace", "-L", "-n", "--max-args", "-P", "--max-procs", "-s", "--max-chars"],
+  watch: ["-n", "--interval"],
+  setsid: [],
+  nohup: [],
+  "systemd-run": ["-u", "--unit", "-p", "--property", "--uid", "--gid", "--setenv"],
+  runuser: ["-u", "--user", "-g", "--group", "-s", "--shell"],
+  su: ["-s", "--shell", "-g", "--group"]
+};
+var PRIVILEGE_ESCALATION_BINARIES = [
+  "sudo",
+  "su",
+  "doas",
+  "pkexec",
+  "runuser",
+  "chroot",
+  "nsenter",
+  "systemd-run"
+];
+var SHELL_PAYLOAD_BINARIES = [
+  "sh",
+  "bash",
+  "zsh",
+  "ksh",
+  "dash",
+  "ash",
+  "mksh",
+  "csh",
+  "tcsh",
+  "fish",
+  "su",
+  "runuser",
+  "chroot",
+  "nsenter",
+  "systemd-run"
+];
+var DANGEROUS_COMMAND_RULES = [
+  {
+    pattern: /^mkfs(\.\w+)?\b/i,
+    reason: "formats a filesystem"
+  },
+  {
+    pattern: />\s*\/dev\/(sd|nvme|hd|vd|xvd|mapper)/i,
+    reason: "redirects output onto a block device"
+  },
+  {
+    pattern: /^(shutdown|reboot|halt|poweroff)\b/i,
+    reason: "powers off or reboots the host, ending this session"
+  },
+  {
+    pattern: /^init\s+[06]\b/i,
+    reason: "changes runlevel to halt or reboot"
+  },
+  {
+    pattern: /^systemctl\s+(poweroff|reboot|halt|emergency|rescue)\b/i,
+    reason: "powers off, reboots or degrades the host"
+  },
+  {
+    // Anchored on `/` as the whole search root: `find /tmp -delete` is ordinary
+    // cleanup, `find / -delete` empties the machine.
+    pattern: /^find\s+\/\s+.*(-delete|-exec(dir)?\s+(\/\S+\/)?rm)/i,
+    reason: "deletes files found from the filesystem root"
+  },
+  {
+    pattern: /^crontab\s+(-\S+\s+)*-r\b/i,
+    reason: "removes every cron job for the user"
+  },
+  {
+    pattern: /^(iptables|ip6tables|nft)\s+(-F|--flush|flush)\b/i,
+    reason: "flushes firewall rules and can lock this session out"
+  },
+  {
+    pattern: /--no-preserve-root/i,
+    reason: "explicitly disables the root-deletion safeguard"
+  }
+];
+var DANGEROUS_ARGUMENT_RULES = [
+  {
+    binaries: ["rm"],
+    requiredFlagPattern: /^--?(?:[a-z]*[rRf][a-z]*|recursive|force)$/,
+    argumentPattern: CRITICAL_PATH_PATTERN,
+    reason: "deletes the filesystem root, a system directory or an entire home directory"
+  },
+  {
+    binaries: ["rm", "unlink", "shred", "srm", "wipe"],
+    argumentPattern: CRITICAL_FILE_PATTERN,
+    reason: "deletes a file the host cannot boot or authenticate without"
+  },
+  {
+    binaries: ["shred", "srm", "wipe"],
+    argumentPattern: CRITICAL_PATH_PATTERN,
+    reason: "irreversibly destroys a system path"
+  },
+  {
+    binaries: ["chmod", "chown", "chgrp"],
+    requiredFlagPattern: /^--?(R|recursive)$/,
+    argumentPattern: CRITICAL_PATH_PATTERN,
+    reason: "recursively rewrites ownership or permissions on a system path"
+  },
+  {
+    binaries: ["dd"],
+    argumentPattern: /^of=(\/dev\/(?!null|zero|stdout|stderr|tty)|\/etc\/|\/boot\/|\/bin\/|\/sbin\/|\/usr\/|\/lib)/i,
+    reason: "writes raw bytes over a device or system file"
+  },
+  {
+    binaries: ["mkfs", "fdisk", "parted", "sgdisk", "wipefs"],
+    argumentPattern: /^\/dev\//i,
+    reason: "repartitions or formats a block device"
+  }
+];
+var DANGEROUS_PIPELINE_RULES = [
+  {
+    pattern: /\{\s*:\s*\|\s*:\s*&\s*\}/,
+    reason: "fork bomb"
+  }
+];
+var WRITE_COMMAND_BINARIES = [
+  // filesystem mutation
+  "rm",
+  "rmdir",
+  "mv",
+  "cp",
+  "dd",
+  "mkdir",
+  "touch",
+  "ln",
+  "chmod",
+  "chown",
+  "chgrp",
+  "truncate",
+  "shred",
+  "srm",
+  "wipe",
+  "install",
+  "tee",
+  "patch",
+  "rename",
+  "chattr",
+  "setfacl",
+  // storage / mounts
+  "mkfs",
+  "fdisk",
+  "parted",
+  "sgdisk",
+  "wipefs",
+  "mount",
+  "umount",
+  "swapon",
+  "swapoff",
+  // accounts and scheduling
+  "useradd",
+  "usermod",
+  "userdel",
+  "groupadd",
+  "groupmod",
+  "groupdel",
+  "passwd",
+  "chpasswd",
+  "visudo",
+  "crontab",
+  "at",
+  "batch",
+  // process and power control
+  "kill",
+  "killall",
+  "pkill",
+  "reboot",
+  "shutdown",
+  "halt",
+  "poweroff",
+  "init",
+  "service",
+  // package managers
+  "apt",
+  "apt-get",
+  "aptitude",
+  "dpkg",
+  "yum",
+  "dnf",
+  "rpm",
+  "zypper",
+  "pacman",
+  "apk",
+  "snap",
+  "brew",
+  "npm",
+  "pnpm",
+  "yarn",
+  "npx",
+  "pip",
+  "pip3",
+  "gem",
+  "cargo",
+  "composer",
+  "bundle",
+  "make",
+  "cmake",
+  // editors — interactive and write-oriented
+  "vi",
+  "vim",
+  "nvim",
+  "nano",
+  "emacs",
+  "ex",
+  "ed",
+  // transfer to/from other hosts, and archive extraction
+  "scp",
+  "rsync",
+  "sftp",
+  "ftp",
+  "ssh",
+  "ssh-keygen",
+  "ssh-copy-id",
+  "wget",
+  "unzip",
+  "gunzip",
+  "bunzip2",
+  "unxz",
+  "cpio",
+  // firewall
+  "iptables",
+  "ip6tables",
+  "ufw",
+  "firewall-cmd",
+  "nft"
+];
+var WRITE_USAGE_RULES = [
+  {
+    pattern: /^sed\b.*(?:(\s|^)-[a-zA-Z]*i([a-zA-Z]|\s|$|\.)|--in-place)/,
+    reason: "sed edits files in place"
+  },
+  {
+    pattern: /^sort\b.*(\s|^)(-o|--output)\b/i,
+    reason: "sort writes its result to a file"
+  },
+  {
+    pattern: /^find\b.*(-delete|-exec|-execdir|-ok|-okdir|-fls|-fprint)/i,
+    reason: "find action deletes files or runs an arbitrary command"
+  },
+  {
+    pattern: /^git\s+(push|reset|checkout|switch|restore|clean|rebase|merge|commit|add|rm|mv|stash|apply|revert|cherry-pick|pull|remote|tag|gc|prune|init|clone)\b/i,
+    reason: "git subcommand mutates the working tree or the remote"
+  },
+  {
+    pattern: /^systemctl\s+(start|stop|restart|reload|enable|disable|mask|unmask|kill|isolate|set-property|edit|daemon-reload|daemon-reexec)\b/i,
+    reason: "systemctl subcommand changes service state"
+  },
+  {
+    pattern: /^docker\s+(run|rm|rmi|stop|start|restart|kill|exec|create|build|push|pull|cp|commit|prune|load|import|tag|update|rename|volume|network|swarm)\b/i,
+    reason: "docker subcommand mutates containers, images or volumes"
+  },
+  {
+    pattern: /^(kubectl|oc)\s+(apply|delete|create|edit|scale|patch|replace|rollout|drain|cordon|uncordon|exec|cp|set|annotate|label|taint)\b/i,
+    reason: "kubectl subcommand mutates cluster state"
+  },
+  {
+    pattern: /^tar\b.*(--extract|--create|--delete|(\s|^)-{1,2}[a-zA-Z]*[xc][a-zA-Z]*(\s|$))/i,
+    reason: "tar extract/create writes files"
+  },
+  {
+    pattern: /^curl\b.*(\s|^)(-o|-O|--output|--remote-name|--upload-file|-T)\b/i,
+    reason: "curl writes a file or uploads one"
+  },
+  {
+    pattern: /^(zip|gzip|bzip2|xz)\b/i,
+    reason: "compression tool rewrites files on disk"
+  }
+];
+var BENIGN_REDIRECT_PATTERN = /(\d?>>?\s*&\s*\d|&>>?\s*\/dev\/null|\d?>>?\s*\/dev\/null)/g;
+var OUTPUT_REDIRECT_PATTERN = />/;
+var REDIRECTION_TOKEN_PATTERN = /^(?:\d*>>?|<|&>>?)/;
+var BARE_REDIRECTION_OPERATOR_PATTERN = /^(?:\d*>>?|<|&>>?)$/;
+var SHELL_TOKEN_PATTERN = /\d*>>?&?\d*|&>>?|<&?\d*|(?:[^\s'"\\<>&|]|\\.|'[^']*'|"[^"]*")+/g;
+var SHELL_KEYWORD_TOKENS = [
+  "if",
+  "then",
+  "else",
+  "elif",
+  "fi",
+  "for",
+  "while",
+  "until",
+  "do",
+  "done",
+  "case",
+  "esac",
+  "in",
+  "select",
+  "function",
+  "{",
+  "}",
+  "(",
+  ")",
+  "!",
+  "[[",
+  "]]",
+  "[",
+  "]"
+];
+var UNSAFE_PATH_CHARACTER_PATTERN = /[`$;|&<>(){}!*?\[\]\\"'\n\r\t]/;
+
+// src/_defs/protected-paths.ts
+var PROTECTED_LOCAL_PATH_RULES = [
+  {
+    pattern: /(^|\/)\.ssh(\/|$)/i,
+    reason: "SSH key directory"
+  },
+  {
+    pattern: /(^|\/)authorized_keys$/i,
+    reason: "SSH authorized_keys"
+  },
+  {
+    pattern: /(^|\/)id_(rsa|dsa|ecdsa|ed25519)/i,
+    reason: "private key file"
+  },
+  {
+    pattern: /\.(pem|ppk|p12|pfx|key)$/i,
+    reason: "private key or certificate file"
+  },
+  {
+    pattern: /(^|\/)\.gnupg(\/|$)/i,
+    reason: "GPG keyring"
+  },
+  {
+    pattern: /(^|\/)\.aws(\/|$)/i,
+    reason: "AWS credentials"
+  },
+  {
+    pattern: /(^|\/)\.kube(\/|$)/i,
+    reason: "kubeconfig"
+  },
+  {
+    pattern: /(^|\/)\.docker(\/|$)/i,
+    reason: "docker credentials"
+  },
+  {
+    pattern: /(^|\/)\.npmrc$/i,
+    reason: "npm credentials"
+  },
+  {
+    pattern: /(^|\/)\.netrc$/i,
+    reason: "netrc credentials"
+  },
+  {
+    pattern: /(^|\/)\.?akms-ssh(\.json)?(\/|$)/i,
+    reason: "this server's own host profile configuration"
+  },
+  {
+    pattern: /(^|\/)\.claude(\.json)?(\/|$)/i,
+    reason: "MCP client configuration"
+  },
+  {
+    pattern: /(^|\/)\.mcp\.json$/i,
+    reason: "MCP server configuration"
+  },
+  {
+    pattern: /(^|\/)claude_desktop_config\.json$/i,
+    reason: "MCP client configuration"
+  },
+  {
+    pattern: /(^|\/)start ?menu\/programs\/startup(\/|$)/i,
+    reason: "Windows startup folder"
+  },
+  {
+    pattern: /(^|\/)\.config\/autostart(\/|$)/i,
+    reason: "desktop autostart directory"
+  }
+];
+
+// src/_defs/env-vars.ts
+var SINGLE_HOST_ENV = {
+  /** Presence of this variable selects single-host mode. */
+  HOST: "SSH_HOST",
+  PORT: "SSH_PORT",
+  USER: "SSH_USER",
+  /** Path to a private key file. */
+  KEY: "SSH_KEY",
+  PASSPHRASE: "SSH_PASSPHRASE",
+  PASSWORD: "SSH_PASSWORD",
+  /** Pinned host key, `SHA256:…`. */
+  HOST_KEY: "SSH_HOST_KEY",
+  /** Alias shown to the model; defaults to the hostname. */
+  NAME: "SSH_NAME",
+  DESCRIPTION: "SSH_DESCRIPTION",
+  /** Directory new sessions start in. */
+  CWD: "SSH_CWD",
+  READONLY: "SSH_READONLY",
+  ALLOW_SUDO: "SSH_ALLOW_SUDO",
+  /** Comma-separated binary names. */
+  ALLOW_COMMANDS: "SSH_ALLOW_COMMANDS",
+  /** Comma-separated regex sources. */
+  DENY_PATTERNS: "SSH_DENY_PATTERNS",
+  /** Comma-separated absolute path prefixes. */
+  ALLOWED_PATHS: "SSH_ALLOWED_PATHS",
+  EXEC_TIMEOUT_MS: "SSH_EXEC_TIMEOUT_MS",
+  CONNECT_TIMEOUT_MS: "SSH_CONNECT_TIMEOUT_MS",
+  MAX_OUTPUT_CHARACTERS: "SSH_MAX_OUTPUT",
+  MAX_READ_FILE_BYTES: "SSH_MAX_READ_BYTES"
+};
+var TRUTHY_ENV_VALUES = ["true", "1", "yes", "on"];
+var FALSY_ENV_VALUES = ["false", "0", "no", "off"];
+
+// src/_libs/logger.ts
+var LEVEL_WEIGHTS = {
+  silent: 0,
+  debug: 1,
+  info: 2,
+  warn: 3,
+  error: 4
+};
+var SECRET_META_KEYS = ["password", "passphrase", "privatekey", "privatekeypath", "secret", "token"];
+function resolveThreshold() {
+  const configured = process.env[LOG_LEVEL_ENV];
+  if (configured == null) {
+    return "info";
+  }
+  const normalized = configured.toLowerCase();
+  if (Object.hasOwn(LEVEL_WEIGHTS, normalized) == false) {
+    return "info";
+  }
+  return normalized;
+}
+function maskMeta(meta) {
+  const masked = {};
+  for (const [key, value] of Object.entries(meta)) {
+    if (SECRET_META_KEYS.includes(key.toLowerCase()) == true) {
+      masked[key] = "***";
+      continue;
+    }
+    masked[key] = value;
+  }
+  return masked;
+}
+function write(level, message, meta) {
+  const threshold = resolveThreshold();
+  if (threshold === "silent") {
+    return;
+  }
+  if (LEVEL_WEIGHTS[level] < LEVEL_WEIGHTS[threshold]) {
+    return;
+  }
+  const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+  const masked = maskMeta(meta);
+  let line = `${timestamp} [${level}] ${message}`;
+  if (Object.keys(masked).length > 0) {
+    line += ` ${JSON.stringify(masked)}`;
+  }
+  process.stderr.write(`${line}
+`);
+}
+function createLogger(boundMeta) {
+  return {
+    child(meta) {
+      return createLogger({ ...boundMeta, ...meta });
+    },
+    debug(message, meta) {
+      write("debug", message, { ...boundMeta, ...meta });
+    },
+    info(message, meta) {
+      write("info", message, { ...boundMeta, ...meta });
+    },
+    warn(message, meta) {
+      write("warn", message, { ...boundMeta, ...meta });
+    },
+    error(error, message, meta) {
+      const errorMeta = { ...boundMeta, ...meta };
+      if (error instanceof Error) {
+        errorMeta.error_name = error.name;
+        errorMeta.error_message = error.message;
+        errorMeta.stack = error.stack;
+      } else if (error != null) {
+        errorMeta.error_message = String(error);
+      }
+      write("error", message, errorMeta);
+    }
+  };
+}
+var $logger = createLogger({});
+
+// src/_libs/text.ts
+function truncateOutput(text, maxCharacters) {
+  if (text.length <= maxCharacters) {
+    return { text, truncated: false };
+  }
+  let cutAt = maxCharacters;
+  const lastKeptCode = text.charCodeAt(cutAt - 1);
+  if (lastKeptCode >= 55296 && lastKeptCode <= 56319) {
+    cutAt -= 1;
+  }
+  const droppedCharacters = text.length - cutAt;
+  const kept = text.slice(0, cutAt);
+  return {
+    text: `${kept}
+... [truncated ${droppedCharacters} characters of ${text.length}]`,
+    truncated: true
+  };
+}
+function quoteShellArgument(value) {
+  const escaped = value.replace(/'/g, `'\\''`);
+  return `'${escaped}'`;
+}
+function formatBytes(bytes) {
+  if (bytes < 1024) {
+    return `${bytes} B`;
+  }
+  if (bytes < 1024 * 1024) {
+    const kilobytes = bytes / 1024;
+    return `${kilobytes.toFixed(1)} KB`;
+  }
+  const megabytes = bytes / (1024 * 1024);
+  return `${megabytes.toFixed(1)} MB`;
+}
+function expandHomePath(inputPath) {
+  let expanded = inputPath;
+  if (inputPath === "~") {
+    expanded = os__default.default.homedir();
+  } else if (inputPath.startsWith("~/") == true || inputPath.startsWith("~\\") == true) {
+    expanded = path2__default.default.join(os__default.default.homedir(), inputPath.slice(2));
+  }
+  return path2__default.default.resolve(expanded);
+}
+function isAbsoluteRemotePath(remotePath) {
+  return remotePath.startsWith("/");
+}
+function normalizeRemotePath(remotePath) {
+  return path2__default.default.posix.normalize(remotePath);
+}
+function isRemotePathWithin(candidate, allowedPrefix) {
+  const normalizedCandidate = normalizeRemotePath(candidate);
+  const normalizedPrefix = normalizeRemotePath(allowedPrefix).replace(/\/+$/, "");
+  if (normalizedPrefix === "" || normalizedPrefix === "/") {
+    return true;
+  }
+  if (normalizedCandidate === normalizedPrefix) {
+    return true;
+  }
+  return normalizedCandidate.startsWith(`${normalizedPrefix}/`);
+}
+
+// src/modules/guard/command-guard.ts
+var WRAPPER_BINARY_SET = new Set(COMMAND_WRAPPER_BINARIES);
+var PRIVILEGE_BINARY_SET = new Set(PRIVILEGE_ESCALATION_BINARIES);
+var SHELL_PAYLOAD_BINARY_SET = new Set(SHELL_PAYLOAD_BINARIES);
+var WRITE_BINARY_SET = new Set(WRITE_COMMAND_BINARIES);
+var SHELL_KEYWORD_SET = new Set(SHELL_KEYWORD_TOKENS);
+var MAX_INSPECTION_DEPTH = 3;
+var ASSIGNMENT_TOKEN_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*=/;
+var SHELL_COMMAND_FLAG_PATTERN = /^-[a-z]*c$/i;
+function normalizeCommandText(command) {
+  return command.replace(/\\\r?\n/g, "").replace(/\$\{IFS\}/g, " ").replace(/\$IFS/g, " ");
+}
+function canonicalizeCommand(command) {
+  return normalizeCommandText(command);
+}
+function splitCommandSegments(command) {
+  const segments = [];
+  let current = "";
+  let openQuote = null;
+  for (let index = 0; index < command.length; index++) {
+    const character = command[index];
+    const nextCharacter = command[index + 1];
+    if (openQuote != null) {
+      current += character;
+      if (character === "\\" && openQuote === `"` && nextCharacter != null) {
+        current += nextCharacter;
+        index++;
+        continue;
+      }
+      if (character === openQuote) {
+        openQuote = null;
+      }
+      continue;
+    }
+    if (character === "'" || character === `"`) {
+      openQuote = character;
+      current += character;
+      continue;
+    }
+    if (character === "\\") {
+      current += character;
+      if (nextCharacter != null) {
+        current += nextCharacter;
+        index++;
+      }
+      continue;
+    }
+    if (character === "&" && current.trimEnd().endsWith(">") == true) {
+      current += character;
+      continue;
+    }
+    const isDoubleOperator = character === "&" && nextCharacter === "&" || character === "|" && nextCharacter === "|";
+    if (isDoubleOperator == true) {
+      segments.push(current);
+      current = "";
+      index++;
+      continue;
+    }
+    if (character === ";" || character === "\n" || character === "|" || character === "&") {
+      segments.push(current);
+      current = "";
+      continue;
+    }
+    current += character;
+  }
+  segments.push(current);
+  return segments.map((segment) => segment.trim()).filter((segment) => segment !== "");
+}
+function stripQuotedText(segment) {
+  let result = "";
+  let openQuote = null;
+  for (let index = 0; index < segment.length; index++) {
+    const character = segment[index];
+    if (openQuote === "'") {
+      if (character === "'") {
+        openQuote = null;
+      }
+      continue;
+    }
+    if (openQuote === `"`) {
+      if (character === "\\") {
+        index++;
+        continue;
+      }
+      if (character === `"`) {
+        openQuote = null;
+      }
+      continue;
+    }
+    if (character === "\\") {
+      index++;
+      continue;
+    }
+    if (character === "'" || character === `"`) {
+      openQuote = character;
+      continue;
+    }
+    result += character;
+  }
+  return result;
+}
+function tokenizeSegment(segment) {
+  const tokens = segment.match(SHELL_TOKEN_PATTERN);
+  if (tokens == null) {
+    return [];
+  }
+  return tokens;
+}
+function unquoteToken(token) {
+  if (token.includes("'") == false && token.includes(`"`) == false && token.includes("\\") == false) {
+    return token;
+  }
+  return token.replace(/\$'([^']*)'/g, "$1").replace(/'([^']*)'/g, "$1").replace(/"([^"]*)"/g, "$1").replace(/\\(.)/g, "$1");
+}
+function normalizeOperand(operand) {
+  if (operand.startsWith("/") == false) {
+    return operand;
+  }
+  let globSuffix = "";
+  if (operand.endsWith("*") == true) {
+    globSuffix = "*";
+  }
+  const withoutGlob = operand.slice(0, operand.length - globSuffix.length);
+  const collapsed = withoutGlob.replace(/\/{2,}/g, "/").replace(/\/\.(?=\/|$)/g, "/").replace(/\/{2,}/g, "/");
+  if (collapsed === "") {
+    return `/${globSuffix}`;
+  }
+  return `${collapsed}${globSuffix}`;
+}
+function extractSubstitutions(command) {
+  const found = [];
+  const nestedPattern = /(?:\$|<|>)\(([^()]*(?:\([^()]*\)[^()]*)*)\)/g;
+  let nestedMatch = nestedPattern.exec(command);
+  while (nestedMatch != null) {
+    found.push(nestedMatch[1]);
+    nestedMatch = nestedPattern.exec(command);
+  }
+  const backtickPattern = /`([^`]*)`/g;
+  let backtickMatch = backtickPattern.exec(command);
+  while (backtickMatch != null) {
+    found.push(backtickMatch[1]);
+    backtickMatch = backtickPattern.exec(command);
+  }
+  return found.filter((substitution) => substitution.trim() !== "");
+}
+function analyzeSegment(segment) {
+  const tokens = tokenizeSegment(segment);
+  const wrappers = [];
+  const flags = [];
+  const operands = [];
+  let binary = "";
+  let binaryIndex = -1;
+  let expectRedirectionTarget = false;
+  let expectFlagValue = false;
+  for (let index = 0; index < tokens.length; index++) {
+    const token = tokens[index];
+    if (expectRedirectionTarget == true) {
+      expectRedirectionTarget = false;
+      continue;
+    }
+    if (expectFlagValue == true) {
+      expectFlagValue = false;
+      continue;
+    }
+    if (ASSIGNMENT_TOKEN_PATTERN.test(token) == true) {
+      continue;
+    }
+    if (REDIRECTION_TOKEN_PATTERN.test(token) == true) {
+      if (BARE_REDIRECTION_OPERATOR_PATTERN.test(token) == true) {
+        expectRedirectionTarget = true;
+      }
+      continue;
+    }
+    if (token.startsWith("-") == true) {
+      const currentWrapper = wrappers[wrappers.length - 1];
+      if (currentWrapper != null) {
+        const valueFlags = WRAPPER_VALUE_FLAGS[currentWrapper];
+        if (valueFlags != null && valueFlags.includes(token) == true) {
+          expectFlagValue = true;
+        }
+      }
+      continue;
+    }
+    if (NUMERIC_OPERAND_PATTERN.test(token) == true && wrappers.length > 0) {
+      continue;
+    }
+    const unquoted = unquoteToken(token);
+    const trimmed = unquoted.replace(/^[({!]+|[)}]+$/g, "");
+    if (SHELL_KEYWORD_SET.has(trimmed) == true || trimmed === "") {
+      continue;
+    }
+    const basename = trimmed.split("/").pop() ?? trimmed;
+    if (basename === "") {
+      continue;
+    }
+    if (WRAPPER_BINARY_SET.has(basename) == true) {
+      wrappers.push(basename);
+      continue;
+    }
+    binary = basename;
+    binaryIndex = index;
+    break;
+  }
+  if (binaryIndex >= 0) {
+    for (const token of tokens.slice(binaryIndex + 1)) {
+      const unquoted = unquoteToken(token);
+      if (unquoted.startsWith("-") == true) {
+        flags.push(unquoted);
+        continue;
+      }
+      operands.push(normalizeOperand(unquoted));
+    }
+  }
+  if (binary === "" && wrappers.length > 0) {
+    binary = wrappers[wrappers.length - 1];
+  }
+  let normalizedText = segment;
+  if (binaryIndex >= 0) {
+    normalizedText = [binary, ...tokens.slice(binaryIndex + 1).map(unquoteToken)].join(" ");
+  }
+  return {
+    wrappers,
+    binary,
+    flags,
+    operands,
+    normalizedText,
+    tokens
+  };
+}
+function extractShellPayloads(analysis) {
+  if (SHELL_PAYLOAD_BINARY_SET.has(analysis.binary) == false) {
+    return [];
+  }
+  const tokens = analysis.tokens;
+  const payloads = [];
+  for (let index = 0; index < tokens.length - 1; index++) {
+    if (SHELL_COMMAND_FLAG_PATTERN.test(tokens[index]) == true || tokens[index] === "--command") {
+      payloads.push(unquoteToken(tokens[index + 1]));
+    }
+  }
+  const separatorIndex = tokens.indexOf("--");
+  if (separatorIndex >= 0 && separatorIndex < tokens.length - 1) {
+    payloads.push(tokens.slice(separatorIndex + 1).map(unquoteToken).join(" "));
+  }
+  return payloads;
+}
+function inspectCommand(command, policy, depth = 0) {
+  const normalizedCommand = normalizeCommandText(command);
+  const trimmedCommand = normalizedCommand.trim();
+  if (trimmedCommand === "") {
+    return { allowed: false, reason: "command is empty" };
+  }
+  if (depth > MAX_INSPECTION_DEPTH) {
+    return {
+      allowed: false,
+      reason: "command nests shells or substitutions too deeply to screen reliably",
+      offendingText: trimmedCommand
+    };
+  }
+  for (const rule of DANGEROUS_PIPELINE_RULES) {
+    if (rule.pattern.test(trimmedCommand) == true) {
+      return {
+        allowed: false,
+        reason: `blocked as dangerous: ${rule.reason}`,
+        offendingText: trimmedCommand
+      };
+    }
+  }
+  for (const substitution of extractSubstitutions(trimmedCommand)) {
+    const verdict = inspectCommand(substitution, policy, depth + 1);
+    if (verdict.allowed == false) {
+      return {
+        allowed: false,
+        reason: `${verdict.reason} (inside a command substitution)`,
+        offendingText: substitution
+      };
+    }
+  }
+  for (const segment of splitCommandSegments(trimmedCommand)) {
+    const verdict = inspectSegment(segment, policy, depth);
+    if (verdict.allowed == false) {
+      return verdict;
+    }
+  }
+  return { allowed: true };
+}
+function inspectSegment(segment, policy, depth) {
+  const analysis = analyzeSegment(segment);
+  for (const pattern of policy.denyPatterns) {
+    if (pattern.test(segment) == true || pattern.test(analysis.normalizedText) == true) {
+      return {
+        allowed: false,
+        reason: `blocked by the profile's denyPatterns rule /${pattern.source}/`,
+        offendingText: segment
+      };
+    }
+  }
+  if (policy.allowSudo == false) {
+    const escalation = [...analysis.wrappers, analysis.binary].find((name) => PRIVILEGE_BINARY_SET.has(name) == true);
+    if (escalation != null) {
+      return {
+        allowed: false,
+        reason: `privilege escalation via '${escalation}' is disabled for this profile (set allowSudo: true to permit it)`,
+        offendingText: segment
+      };
+    }
+  }
+  const shouldTestRawSegment = analysis.normalizedText !== segment;
+  for (const rule of DANGEROUS_COMMAND_RULES) {
+    const matched = rule.pattern.test(analysis.normalizedText) == true || shouldTestRawSegment == true && rule.pattern.test(segment) == true;
+    if (matched == true) {
+      return {
+        allowed: false,
+        reason: `blocked as dangerous: ${rule.reason}`,
+        offendingText: segment
+      };
+    }
+  }
+  for (const rule of DANGEROUS_ARGUMENT_RULES) {
+    if (rule.binaries.includes(analysis.binary) == false) {
+      continue;
+    }
+    if (rule.requiredFlagPattern != null) {
+      const hasRequiredFlag = analysis.flags.some((flag) => rule.requiredFlagPattern?.test(flag) == true);
+      if (hasRequiredFlag == false) {
+        continue;
+      }
+    }
+    const offendingOperand = analysis.operands.find((operand) => rule.argumentPattern.test(operand) == true);
+    if (offendingOperand != null) {
+      return {
+        allowed: false,
+        reason: `blocked as dangerous: ${rule.reason}`,
+        offendingText: `${analysis.binary} \u2026 ${offendingOperand}`
+      };
+    }
+  }
+  if (policy.readonly == true) {
+    const readonlyVerdict = inspectReadOnly(segment, analysis, shouldTestRawSegment);
+    if (readonlyVerdict.allowed == false) {
+      return readonlyVerdict;
+    }
+  }
+  if (policy.allowCommands.length > 0) {
+    if (analysis.binary === "") {
+      return {
+        allowed: false,
+        reason: `this profile only permits ${policy.allowCommands.join(", ")}, and this segment runs no listed command`,
+        offendingText: segment
+      };
+    }
+    if (policy.allowCommands.includes(analysis.binary) == false) {
+      return {
+        allowed: false,
+        reason: `'${analysis.binary}' is not in this profile's allowCommands list (${policy.allowCommands.join(", ")})`,
+        offendingText: segment
+      };
+    }
+  }
+  for (const payload of extractShellPayloads(analysis)) {
+    const verdict = inspectCommand(payload, policy, depth + 1);
+    if (verdict.allowed == false) {
+      return {
+        allowed: false,
+        reason: `${verdict.reason} (inside a '${analysis.binary} -c' payload)`,
+        offendingText: payload
+      };
+    }
+  }
+  return { allowed: true };
+}
+function inspectReadOnly(segment, analysis, shouldTestRawSegment) {
+  if (WRITE_BINARY_SET.has(analysis.binary) == true) {
+    return {
+      allowed: false,
+      reason: `profile is read-only and '${analysis.binary}' can modify the host`,
+      offendingText: segment
+    };
+  }
+  for (const rule of WRITE_USAGE_RULES) {
+    const matched = rule.pattern.test(analysis.normalizedText) == true || shouldTestRawSegment == true && rule.pattern.test(segment) == true;
+    if (matched == true) {
+      return {
+        allowed: false,
+        reason: `profile is read-only: ${rule.reason}`,
+        offendingText: segment
+      };
+    }
+  }
+  const withoutQuotes = stripQuotedText(segment);
+  const withoutBenignRedirects = withoutQuotes.replace(BENIGN_REDIRECT_PATTERN, "");
+  if (OUTPUT_REDIRECT_PATTERN.test(withoutBenignRedirects) == true) {
+    return {
+      allowed: false,
+      reason: "profile is read-only and the command redirects output into a file",
+      offendingText: segment
+    };
+  }
+  return { allowed: true };
+}
+function inspectRemotePath(remotePath, policy, access) {
+  const trimmedPath = remotePath.trim();
+  if (trimmedPath === "") {
+    return { allowed: false, reason: "path is empty" };
+  }
+  if (access === "write" && policy.readonly == true) {
+    return {
+      allowed: false,
+      reason: "profile is read-only, remote writes are not permitted",
+      offendingText: trimmedPath
+    };
+  }
+  if (policy.allowedPaths.length === 0) {
+    return { allowed: true };
+  }
+  if (isAbsoluteRemotePath(trimmedPath) == false) {
+    return {
+      allowed: false,
+      reason: `this profile restricts file access to ${policy.allowedPaths.join(", ")}, so the path must be absolute`,
+      offendingText: trimmedPath
+    };
+  }
+  const normalizedPath = normalizeRemotePath(trimmedPath);
+  const matched = policy.allowedPaths.some((allowedPath) => isRemotePathWithin(normalizedPath, allowedPath) == true);
+  if (matched == false) {
+    return {
+      allowed: false,
+      reason: `path is outside this profile's allowedPaths (${policy.allowedPaths.join(", ")})`,
+      offendingText: normalizedPath
+    };
+  }
+  return { allowed: true };
+}
+function toRealPath(inputPath) {
+  const _logger = $logger.child({ context: "toRealPath" });
+  try {
+    return fs4__default.default.realpathSync.native(inputPath);
+  } catch (ex) {
+    _logger.debug("path does not resolve, falling back to its parent directory", {
+      reason: ex instanceof Error ? ex.name : "unknown"
+    });
+  }
+  try {
+    const parentRealPath = fs4__default.default.realpathSync.native(path2__default.default.dirname(inputPath));
+    return path2__default.default.join(parentRealPath, path2__default.default.basename(inputPath));
+  } catch (ex) {
+    _logger.debug("parent directory does not resolve either, comparing lexically", {
+      reason: ex instanceof Error ? ex.name : "unknown"
+    });
+    return path2__default.default.resolve(inputPath);
+  }
+}
+function toComparablePath(inputPath) {
+  return toRealPath(inputPath).replace(/\\/g, "/");
+}
+function inspectLocalPath(resolvedLocalPath, access, extraProtectedPaths = []) {
+  const trimmedPath = resolvedLocalPath.trim();
+  if (trimmedPath === "") {
+    return { allowed: false, reason: "local path is empty" };
+  }
+  const comparablePath = toComparablePath(trimmedPath);
+  for (const rule of PROTECTED_LOCAL_PATH_RULES) {
+    if (rule.pattern.test(comparablePath) == true) {
+      let verb = "read from";
+      if (access === "write") {
+        verb = "written to";
+      }
+      return {
+        allowed: false,
+        reason: `local path is protected and cannot be ${verb}: ${rule.reason}`,
+        offendingText: trimmedPath
+      };
+    }
+  }
+  for (const protectedPath of extraProtectedPaths) {
+    if (protectedPath === "") {
+      continue;
+    }
+    if (comparablePath.toLowerCase() === toComparablePath(protectedPath).toLowerCase()) {
+      return {
+        allowed: false,
+        reason: "local path is this server's own configuration file",
+        offendingText: trimmedPath
+      };
+    }
+  }
+  return { allowed: true };
+}
+function inspectWorkingDirectory(cwd) {
+  const trimmedCwd = cwd.trim();
+  if (trimmedCwd === "") {
+    return { allowed: true };
+  }
+  const unsafeMatch = UNSAFE_PATH_CHARACTER_PATTERN.exec(trimmedCwd);
+  if (unsafeMatch != null) {
+    const displayCharacter = unsafeMatch[0].replace(/\n/, "\\n").replace(/\r/, "\\r").replace(/\t/, "\\t");
+    return {
+      allowed: false,
+      reason: `cwd contains the shell metacharacter '${displayCharacter}', which is not allowed in a directory argument`,
+      offendingText: trimmedCwd
+    };
+  }
+  return { allowed: true };
+}
+
+// src/modules/guard/guard-error.ts
+var GuardRejectionError = class extends Error {
+  constructor(verdict) {
+    super(verdict.reason ?? "rejected by the host profile's guard policy");
+    this.verdict = verdict;
+    this.name = "GuardRejectionError";
+  }
+};
+
+// src/modules/ssh/ssh-connection.ts
+var { Client } = ssh2__default.default;
+var OUTPUT_HARD_CAP_MULTIPLIER = 4;
+var PRIVATE_KEY_CACHE = /* @__PURE__ */ new Map();
+var WINDOWS_AGENT_PIPE = "\\\\.\\pipe\\openssh-ssh-agent";
+function resolveAgentPath() {
+  const authSocket = process.env.SSH_AUTH_SOCK;
+  if (authSocket != null && authSocket !== "") {
+    return authSocket;
+  }
+  if (process.platform === "win32") {
+    return WINDOWS_AGENT_PIPE;
+  }
+  return void 0;
+}
+function readPrivateKey(profile, keyPath) {
+  const cached = PRIVATE_KEY_CACHE.get(keyPath);
+  if (cached != null) {
+    return cached;
+  }
+  try {
+    const contents = fs4__default.default.readFileSync(keyPath);
+    PRIVATE_KEY_CACHE.set(keyPath, contents);
+    return contents;
+  } catch (ex) {
+    const _logger = $logger.child({ context: "readPrivateKey", profile: profile.name });
+    _logger.error(ex, "cannot read the profile's private key file");
+    throw new Error(`cannot read the private key configured for profile '${profile.name}' (see the server log for the path)`);
+  }
+}
+function toHostKeyFingerprint(hostKey) {
+  const digest = crypto.createHash("sha256").update(hostKey).digest("base64").replace(/=+$/, "");
+  return `SHA256:${digest}`;
+}
+function buildHostVerifier(profile, onHostKeySeen) {
+  return (hostKey) => {
+    const fingerprint = toHostKeyFingerprint(hostKey);
+    onHostKeySeen(fingerprint);
+    const _logger = $logger.child({ context: "hostVerifier", profile: profile.name, host: profile.host });
+    if (profile.hostKeyFingerprint == null) {
+      _logger.info("host key accepted unpinned; add hostKeyFingerprint to the profile to pin it", {
+        host_key_fingerprint: fingerprint
+      });
+      return true;
+    }
+    if (profile.hostKeyFingerprint === fingerprint) {
+      _logger.debug("host key matches the pinned fingerprint");
+      return true;
+    }
+    _logger.error(null, "host key does not match the pinned fingerprint", {
+      expected: profile.hostKeyFingerprint,
+      actual: fingerprint
+    });
+    return false;
+  };
+}
+function buildConnectConfig(profile, onHostKeySeen) {
+  const connectConfig = {
+    host: profile.host,
+    port: profile.port,
+    username: profile.username,
+    readyTimeout: profile.policy.connectTimeoutMs,
+    keepaliveInterval: KEEPALIVE_INTERVAL_MS,
+    hostVerifier: buildHostVerifier(profile, onHostKeySeen)
+  };
+  if (profile.privateKeyPath != null) {
+    connectConfig.privateKey = readPrivateKey(profile, profile.privateKeyPath);
+  } else if (profile.privateKey != null) {
+    connectConfig.privateKey = profile.privateKey;
+  }
+  if (profile.passphrase != null) {
+    connectConfig.passphrase = profile.passphrase;
+  }
+  if (profile.password != null) {
+    connectConfig.password = profile.password;
+  }
+  if (connectConfig.privateKey == null && connectConfig.password == null) {
+    connectConfig.agent = resolveAgentPath();
+  }
+  return connectConfig;
+}
+function buildRemoteCommand(command, cwd, trackCwd) {
+  const lines = [];
+  if (cwd != null && cwd !== "") {
+    const quotedCwd = quoteShellArgument(cwd);
+    lines.push(`cd ${quotedCwd} 2>/dev/null || { echo 'akms-ssh: cannot enter the requested working directory' >&2; exit 1; }`);
+  }
+  lines.push(command);
+  if (trackCwd == true) {
+    lines.push("__akms_exit=$?");
+    lines.push(`printf '\\n${CWD_MARKER}%s' "$PWD"`);
+    lines.push("exit $__akms_exit");
+  }
+  return lines.join("\n");
+}
+function extractCwdMarker(stdout) {
+  const markerIndex = stdout.lastIndexOf(CWD_MARKER);
+  if (markerIndex < 0) {
+    return { output: stdout };
+  }
+  const markerPayload = stdout.slice(markerIndex + CWD_MARKER.length);
+  const cwd = (markerPayload.split("\n")[0] ?? "").trim();
+  let output = stdout.slice(0, markerIndex);
+  if (output.endsWith("\n") == true) {
+    output = output.slice(0, -1);
+  }
+  if (cwd === "") {
+    return { output };
+  }
+  return { output, cwd };
+}
+var SshConnection = class {
+  constructor(profile) {
+    this.profile = profile;
+    this.client = null;
+    this.pendingClient = null;
+    this.connecting = null;
+    this.disposed = false;
+    /** Set when the peer closed a previously established connection. */
+    this.droppedAfterReady = false;
+    this.observedFingerprint = null;
+  }
+  get isConnected() {
+    return this.client != null;
+  }
+  /** Host key the server presented, once a handshake has been attempted. */
+  get hostKeyFingerprint() {
+    return this.observedFingerprint;
+  }
+  /** True when a connection was established and then lost, so shell state is gone. */
+  get wasDropped() {
+    return this.droppedAfterReady;
+  }
+  /**
+   * Opens the connection, or joins the in-flight attempt when one is already running.
+   *
+   * @throws {Error} If the connection was closed, authentication fails, the host is
+   *                 unreachable, or the handshake times out.
+   */
+  async connect() {
+    if (this.disposed == true) {
+      throw new Error(`ssh connection for '${this.profile.name}' has been closed; open a new session`);
+    }
+    if (this.client != null) {
+      return;
+    }
+    if (this.connecting != null) {
+      await this.connecting;
+      return;
+    }
+    const _logger = $logger.child({
+      context: "SshConnection.connect",
+      profile: this.profile.name,
+      host: this.profile.host,
+      port: this.profile.port,
+      username: this.profile.username
+    });
+    const connectConfig = buildConnectConfig(this.profile, (fingerprint) => {
+      this.observedFingerprint = fingerprint;
+    });
+    this.connecting = new Promise((resolve, reject) => {
+      const client = new Client();
+      this.pendingClient = client;
+      let settled = false;
+      client.on("error", (error) => {
+        if (settled == false) {
+          settled = true;
+          this.pendingClient = null;
+          client.destroy();
+          reject(error);
+          return;
+        }
+        _logger.error(error, "ssh connection error after ready");
+      });
+      client.on("close", () => {
+        if (this.client === client) {
+          _logger.debug("ssh connection closed by the peer");
+          this.client = null;
+          this.droppedAfterReady = true;
+        }
+      });
+      client.once("ready", () => {
+        if (settled == true) {
+          return;
+        }
+        settled = true;
+        this.pendingClient = null;
+        if (this.disposed == true) {
+          client.destroy();
+          reject(new Error(`ssh connection for '${this.profile.name}' was closed during the handshake`));
+          return;
+        }
+        this.client = client;
+        resolve();
+      });
+      client.connect(connectConfig);
+    });
+    try {
+      await this.connecting;
+      _logger.info("ssh connection established");
+    } catch (ex) {
+      _logger.error(ex, "ssh connection failed");
+      let detail = String(ex);
+      if (ex instanceof Error) {
+        detail = ex.message;
+      }
+      throw new Error(`ssh connect failed for '${this.profile.name}' (${this.profile.username}@${this.profile.host}:${this.profile.port}): ${detail}`);
+    } finally {
+      this.connecting = null;
+    }
+  }
+  /**
+   * Screens a command against this profile's policy, then runs it on its own channel.
+   *
+   * The canonical form is what gets screened *and* what gets sent — validating one
+   * string while executing another is a bypass by construction.
+   *
+   * @throws {GuardRejectionError} If the policy refuses the command or the cwd.
+   * @throws {Error} If the connection is closed or the channel cannot be opened.
+   */
+  async exec(options) {
+    const canonicalCommand = canonicalizeCommand(options.command);
+    const verdict = inspectCommand(canonicalCommand, this.profile.policy);
+    if (verdict.allowed == false) {
+      throw new GuardRejectionError(verdict);
+    }
+    if (options.cwd != null) {
+      const cwdVerdict = inspectWorkingDirectory(options.cwd);
+      if (cwdVerdict.allowed == false) {
+        throw new GuardRejectionError(cwdVerdict);
+      }
+    }
+    await this.connect();
+    const client = this.client;
+    if (client == null) {
+      throw new Error(`ssh connection for '${this.profile.name}' is not open`);
+    }
+    const _logger = $logger.child({
+      context: "SshConnection.exec",
+      profile: this.profile.name,
+      cwd: options.cwd
+    });
+    const remoteCommand = buildRemoteCommand(canonicalCommand, options.cwd, options.trackCwd);
+    const hardCap = options.maxOutputCharacters * OUTPUT_HARD_CAP_MULTIPLIER;
+    const startedAt = Date.now();
+    const raw = await new Promise((resolve, reject) => {
+      client.exec(remoteCommand, (error, channel) => {
+        if (error != null) {
+          reject(error);
+          return;
+        }
+        let stdout = "";
+        let stderr = "";
+        let exitCode = null;
+        let signal = void 0;
+        let timedOut = false;
+        let settled = false;
+        let capExceeded = false;
+        const stdoutDecoder = new string_decoder.StringDecoder("utf8");
+        const stderrDecoder = new string_decoder.StringDecoder("utf8");
+        const timeoutTimer = setTimeout(() => {
+          timedOut = true;
+          _logger.warn("command timed out, closing the channel", { timeout_ms: options.timeoutMs });
+          channel.close();
+        }, options.timeoutMs);
+        timeoutTimer.unref();
+        const finish = () => {
+          if (settled == true) {
+            return;
+          }
+          settled = true;
+          clearTimeout(timeoutTimer);
+          stdout += stdoutDecoder.end();
+          stderr += stderrDecoder.end();
+          resolve({ stdout, stderr, exitCode, signal, timedOut });
+        };
+        channel.on("data", (chunk) => {
+          if (capExceeded == true) {
+            return;
+          }
+          stdout += stdoutDecoder.write(chunk);
+          if (stdout.length > hardCap) {
+            capExceeded = true;
+            _logger.warn("stdout exceeded the hard cap, closing the channel", { hard_cap: hardCap });
+            channel.close();
+          }
+        });
+        channel.stderr.on("data", (chunk) => {
+          if (capExceeded == true) {
+            return;
+          }
+          stderr += stderrDecoder.write(chunk);
+          if (stderr.length > hardCap) {
+            capExceeded = true;
+            channel.close();
+          }
+        });
+        channel.on("exit", (code, exitSignal) => {
+          exitCode = code;
+          signal = exitSignal;
+        });
+        channel.on("close", finish);
+        channel.on("error", (channelError) => {
+          clearTimeout(timeoutTimer);
+          if (settled == true) {
+            return;
+          }
+          settled = true;
+          reject(channelError);
+        });
+        channel.eof();
+      });
+    });
+    let output = raw.stdout;
+    let cwd = void 0;
+    if (options.trackCwd == true) {
+      const parsed = extractCwdMarker(raw.stdout);
+      output = parsed.output;
+      cwd = parsed.cwd;
+    }
+    const truncatedStdout = truncateOutput(output, options.maxOutputCharacters);
+    const truncatedStderr = truncateOutput(raw.stderr, options.maxOutputCharacters);
+    const result = {
+      stdout: truncatedStdout.text,
+      stderr: truncatedStderr.text,
+      exitCode: raw.exitCode,
+      timedOut: raw.timedOut,
+      truncated: truncatedStdout.truncated == true || truncatedStderr.truncated == true,
+      durationMs: Date.now() - startedAt
+    };
+    if (raw.signal != null) {
+      result.signal = raw.signal;
+    }
+    if (cwd != null) {
+      result.cwd = cwd;
+    }
+    _logger.debug("command finished", {
+      exit_code: result.exitCode,
+      duration_ms: result.durationMs,
+      timed_out: result.timedOut
+    });
+    return result;
+  }
+  /**
+   * Opens an SFTP channel, hands it to `handler`, and closes it afterwards.
+   *
+   * A channel per operation costs one round trip but keeps a broken transfer from
+   * poisoning later ones — SFTP channels do not recover from a mid-stream error.
+   *
+   * The channel's own `error` event is wired into the returned promise: ssh2 strips its
+   * setup listeners before handing the wrapper over, so an unhandled SFTP protocol error
+   * would otherwise crash the process rather than fail this one call.
+   *
+   * @throws {Error} If the SFTP subsystem cannot be started or the channel errors.
+   */
+  async withSftp(handler) {
+    await this.connect();
+    const client = this.client;
+    if (client == null) {
+      throw new Error(`ssh connection for '${this.profile.name}' is not open`);
+    }
+    const sftp = await new Promise((resolve, reject) => {
+      client.sftp((error, sftpWrapper) => {
+        if (error != null) {
+          reject(error);
+          return;
+        }
+        resolve(sftpWrapper);
+      });
+    });
+    return await new Promise((resolve, reject) => {
+      let settled = false;
+      const finish = (settle) => {
+        if (settled == true) {
+          return;
+        }
+        settled = true;
+        try {
+          sftp.end();
+        } catch (ex) {
+          const _logger = $logger.child({ context: "SshConnection.withSftp", profile: this.profile.name });
+          _logger.error(ex, "failed to close the sftp channel");
+        }
+        settle();
+      };
+      sftp.on("error", (error) => {
+        finish(() => {
+          reject(error);
+        });
+      });
+      handler(sftp).then(
+        (value) => {
+          finish(() => {
+            resolve(value);
+          });
+        },
+        (error) => {
+          finish(() => {
+            reject(error);
+          });
+        }
+      );
+    });
+  }
+  /** Closes the connection for good; a disposed connection will not re-dial. */
+  disconnect() {
+    this.disposed = true;
+    if (this.pendingClient != null) {
+      this.pendingClient.destroy();
+      this.pendingClient = null;
+    }
+    if (this.client == null) {
+      return;
+    }
+    this.client.end();
+    this.client = null;
+  }
+};
+var MAX_OPEN_SESSIONS = 32;
+var SshSession = class {
+  constructor(sessionId, connection) {
+    this.sessionId = sessionId;
+    this.connection = connection;
+    this.execCount = 0;
+    this.openedAt = /* @__PURE__ */ new Date();
+    /** Tail of the serialized operation chain; see `runExclusive`. */
+    this.operationChain = Promise.resolve();
+    this.activeOperationCount = 0;
+    this.cwd = connection.profile.defaultCwd ?? "";
+    this.lastUsedAt = /* @__PURE__ */ new Date();
+  }
+  get profile() {
+    return this.connection.profile;
+  }
+  /** True while an operation is running, so the idle sweeper leaves it alone. */
+  get isBusy() {
+    return this.activeOperationCount > 0;
+  }
+  /** Marks the session as in use. */
+  touch() {
+    this.lastUsedAt = /* @__PURE__ */ new Date();
+  }
+  /**
+   * Runs `operation` with exclusive use of this session.
+   *
+   * Serialized because `cwd` is read-modify-write across a network round trip: two
+   * concurrent calls both read the old directory, and the one that finishes second
+   * writes it back — silently undoing the other's `cd`. Bracketing with `touch()` also
+   * keeps the idle sweeper off a session that is mid-transfer.
+   */
+  async runExclusive(operation) {
+    const previous = this.operationChain;
+    let releaseChain = () => {
+    };
+    this.operationChain = new Promise((resolve) => {
+      releaseChain = resolve;
+    });
+    await previous.catch(() => {
+    });
+    this.activeOperationCount += 1;
+    this.touch();
+    try {
+      return await operation(this.connection);
+    } finally {
+      this.activeOperationCount -= 1;
+      this.touch();
+      releaseChain();
+    }
+  }
+  /**
+   * Runs a command in this session's working directory and adopts wherever it ended up,
+   * so a `cd` in one call is still in effect on the next.
+   *
+   * Passing `cwd` runs this command elsewhere *and* moves the session there — same
+   * result as prefixing `cd <cwd> &&`, which is what a shell user would expect.
+   *
+   * @throws {Error} If the connection was dropped since the session opened. A silent
+   *                 re-dial would hand back a fresh login shell while the model still
+   *                 believes it holds the old one — environment, sudo cache and
+   *                 background jobs all gone with no signal.
+   */
+  async exec(command, options) {
+    if (this.connection.wasDropped == true) {
+      throw new Error(`session ${this.sessionId} lost its connection to ${this.profile.host}; its shell state is gone \u2014 open a new session with ssh_connect`);
+    }
+    const policy = this.profile.policy;
+    const targetCwd = options?.cwd ?? this.cwd;
+    return await this.runExclusive(async (connection) => {
+      const result = await connection.exec({
+        command,
+        cwd: targetCwd,
+        timeoutMs: options?.timeoutMs ?? policy.execTimeoutMs,
+        maxOutputCharacters: policy.maxOutputCharacters,
+        trackCwd: true
+      });
+      if (result.cwd != null && result.cwd !== "") {
+        const verdict = inspectWorkingDirectory(result.cwd);
+        if (verdict.allowed == true) {
+          this.cwd = result.cwd;
+        } else {
+          const _logger = $logger.child({ context: "SshSession.exec", session_id: this.sessionId });
+          _logger.warn("remote working directory contains unsafe characters, keeping the previous cwd", {
+            reported_cwd: result.cwd
+          });
+        }
+      }
+      this.execCount += 1;
+      return result;
+    });
+  }
+  toInfo() {
+    let displayCwd = this.cwd;
+    if (displayCwd === "") {
+      displayCwd = "(login default)";
+    }
+    return {
+      sessionId: this.sessionId,
+      profileName: this.profile.name,
+      host: this.profile.host,
+      username: this.profile.username,
+      cwd: displayCwd,
+      openedAt: this.openedAt.toISOString(),
+      lastUsedAt: this.lastUsedAt.toISOString(),
+      execCount: this.execCount
+    };
+  }
+};
+var SshSessionManager = class {
+  constructor() {
+    this.sessions = /* @__PURE__ */ new Map();
+    this.sequence = 0;
+    this.pendingOpenCount = 0;
+    this.sweepTimer = null;
+  }
+  /**
+   * Opens a connection and registers it as a session.
+   *
+   * `pendingOpenCount` reserves the slot across the `await`: checking `sessions.size`
+   * alone let N concurrent calls all observe the same pre-connect count and blow past
+   * the ceiling together.
+   *
+   * @throws {Error} If the session ceiling is reached or the connection fails.
+   */
+  async open(profile) {
+    if (this.sessions.size + this.pendingOpenCount >= MAX_OPEN_SESSIONS) {
+      throw new Error(`too many open ssh sessions (${MAX_OPEN_SESSIONS}), close some with ssh_disconnect first`);
+    }
+    this.sequence += 1;
+    const sessionId = `${profile.name}#${this.sequence}`;
+    const connection = new SshConnection(profile);
+    this.pendingOpenCount += 1;
+    try {
+      await connection.connect();
+    } finally {
+      this.pendingOpenCount -= 1;
+    }
+    const session = new SshSession(sessionId, connection);
+    this.sessions.set(sessionId, session);
+    const _logger = $logger.child({ context: "SshSessionManager.open", session_id: sessionId, profile: profile.name });
+    _logger.info("ssh session opened", { open_sessions: this.sessions.size });
+    return session;
+  }
+  /**
+   * Looks up a session, failing with the list of live ids so the caller can self-correct.
+   *
+   * @throws {Error} If no session matches `sessionId`.
+   */
+  require(sessionId) {
+    const session = this.sessions.get(sessionId);
+    if (session == null) {
+      const openIds = Array.from(this.sessions.keys());
+      let openSummary = "none";
+      if (openIds.length > 0) {
+        openSummary = openIds.join(", ");
+      }
+      throw new Error(`unknown ssh session '${sessionId}' (open sessions: ${openSummary})`);
+    }
+    return session;
+  }
+  close(sessionId) {
+    const session = this.sessions.get(sessionId);
+    if (session == null) {
+      return false;
+    }
+    session.connection.disconnect();
+    this.sessions.delete(sessionId);
+    const _logger = $logger.child({ context: "SshSessionManager.close", session_id: sessionId });
+    _logger.info("ssh session closed", { open_sessions: this.sessions.size });
+    return true;
+  }
+  closeAll() {
+    for (const sessionId of Array.from(this.sessions.keys())) {
+      this.close(sessionId);
+    }
+  }
+  list() {
+    return Array.from(this.sessions.values()).map((session) => session.toInfo());
+  }
+  /** Starts the idle sweeper; the timer is unref'd so it never holds the process open. */
+  startIdleSweeper() {
+    if (this.sweepTimer != null) {
+      return;
+    }
+    this.sweepTimer = timers.setInterval(() => {
+      const expiredAt = Date.now() - SESSION_IDLE_TIMEOUT_MS;
+      for (const session of Array.from(this.sessions.values())) {
+        if (session.isBusy == true) {
+          continue;
+        }
+        if (session.lastUsedAt.getTime() > expiredAt) {
+          continue;
+        }
+        const _logger = $logger.child({
+          context: "SshSessionManager.sweep",
+          session_id: session.sessionId,
+          idle_ms: Date.now() - session.lastUsedAt.getTime()
+        });
+        _logger.info("closing idle ssh session");
+        this.close(session.sessionId);
+      }
+    }, SESSION_SWEEP_INTERVAL_MS);
+    this.sweepTimer.unref();
+  }
+  stopIdleSweeper() {
+    if (this.sweepTimer == null) {
+      return;
+    }
+    timers.clearInterval(this.sweepTimer);
+    this.sweepTimer = null;
+  }
+};
+function requirePermittedPath(connection, remotePath, access) {
+  const verdict = inspectRemotePath(remotePath, connection.profile.policy, access);
+  if (verdict.allowed == false) {
+    throw new GuardRejectionError(verdict);
+  }
+}
+function toEntryType(attrs) {
+  if (typeof attrs.mode !== "number") {
+    return "other";
+  }
+  if (attrs.isDirectory() == true) {
+    return "directory";
+  }
+  if (attrs.isSymbolicLink() == true) {
+    return "symlink";
+  }
+  if (attrs.isFile() == true) {
+    return "file";
+  }
+  return "other";
+}
+function toRemoteEntry(entry) {
+  const attrs = entry.attrs;
+  let mode = "?";
+  if (typeof attrs.mode === "number") {
+    mode = `0${(attrs.mode & 4095).toString(8)}`;
+  }
+  let sizeBytes = 0;
+  if (typeof attrs.size === "number" && Number.isFinite(attrs.size) == true) {
+    sizeBytes = attrs.size;
+  }
+  let modifiedAt = "unknown";
+  if (typeof attrs.mtime === "number" && Number.isFinite(attrs.mtime) == true) {
+    modifiedAt = new Date(attrs.mtime * 1e3).toISOString();
+  }
+  return {
+    name: entry.filename,
+    type: toEntryType(attrs),
+    sizeBytes,
+    mode,
+    modifiedAt
+  };
+}
+async function listRemoteDirectory(connection, remotePath) {
+  requirePermittedPath(connection, remotePath, "read");
+  return await connection.withSftp(async (sftp) => {
+    const entries = await new Promise((resolve, reject) => {
+      sftp.readdir(remotePath, (error, list) => {
+        if (error != null) {
+          reject(error);
+          return;
+        }
+        resolve(list);
+      });
+    });
+    const mapped = entries.map(toRemoteEntry);
+    mapped.sort((left, right) => {
+      if (left.type === "directory" && right.type !== "directory") {
+        return -1;
+      }
+      if (left.type !== "directory" && right.type === "directory") {
+        return 1;
+      }
+      return left.name.localeCompare(right.name);
+    });
+    return {
+      entries: mapped.slice(0, MAX_DIRECTORY_ENTRIES),
+      totalCount: mapped.length,
+      truncated: mapped.length > MAX_DIRECTORY_ENTRIES
+    };
+  });
+}
+async function readRemoteFile(connection, remotePath, maxBytes) {
+  requirePermittedPath(connection, remotePath, "read");
+  return await connection.withSftp(async (sftp) => {
+    const attrs = await new Promise((resolve, reject) => {
+      sftp.stat(remotePath, (error, stats) => {
+        if (error != null) {
+          reject(error);
+          return;
+        }
+        resolve(stats);
+      });
+    });
+    if (attrs.isDirectory() == true) {
+      throw new Error(`${remotePath} is a directory, use ssh_list_dir instead`);
+    }
+    let declaredSize = 0;
+    if (typeof attrs.size === "number" && Number.isFinite(attrs.size) == true) {
+      declaredSize = attrs.size;
+    }
+    const isSizeKnown = declaredSize > 0;
+    const streamOptions = {};
+    if (isSizeKnown == true) {
+      streamOptions.start = 0;
+      streamOptions.end = Math.min(declaredSize, maxBytes) - 1;
+    }
+    const chunks = [];
+    let collectedBytes = 0;
+    await new Promise((resolve, reject) => {
+      const stream = sftp.createReadStream(remotePath, streamOptions);
+      stream.on("data", (chunk) => {
+        chunks.push(chunk);
+        collectedBytes += chunk.length;
+        if (collectedBytes >= maxBytes) {
+          stream.destroy();
+          resolve();
+        }
+      });
+      stream.on("error", (error) => {
+        reject(error);
+      });
+      stream.on("end", () => {
+        resolve();
+      });
+      stream.on("close", () => {
+        resolve();
+      });
+    });
+    const buffer = Buffer.concat(chunks, Math.min(collectedBytes, maxBytes));
+    let truncated = false;
+    if (isSizeKnown == true) {
+      truncated = declaredSize > buffer.length;
+    } else {
+      truncated = buffer.length >= maxBytes;
+    }
+    const decoder = new string_decoder.StringDecoder("utf8");
+    const content = decoder.write(buffer) + decoder.end();
+    return {
+      content,
+      sizeBytes: declaredSize,
+      readBytes: buffer.length,
+      truncated
+    };
+  });
+}
+async function writeRemoteFile(connection, args) {
+  const { remotePath, content, append } = args;
+  requirePermittedPath(connection, remotePath, "write");
+  const payload = Buffer.from(content, "utf8");
+  await connection.withSftp(async (sftp) => {
+    await new Promise((resolve, reject) => {
+      const callback = (error) => {
+        if (error != null) {
+          reject(error);
+          return;
+        }
+        resolve();
+      };
+      if (append == true) {
+        sftp.appendFile(remotePath, payload, callback);
+        return;
+      }
+      sftp.writeFile(remotePath, payload, callback);
+    });
+  });
+  const _logger = $logger.child({
+    context: "writeRemoteFile",
+    profile: connection.profile.name,
+    remote_path: remotePath,
+    append
+  });
+  _logger.info("remote file written", { bytes: payload.length });
+  return payload.length;
+}
+async function uploadFile(connection, localPath, remotePath) {
+  requirePermittedPath(connection, remotePath, "write");
+  const localStats = fs4__default.default.statSync(localPath);
+  if (localStats.isFile() == false) {
+    throw new Error(`local path is not a file: ${localPath}`);
+  }
+  await connection.withSftp(async (sftp) => {
+    await new Promise((resolve, reject) => {
+      sftp.fastPut(localPath, remotePath, (error) => {
+        if (error != null) {
+          reject(error);
+          return;
+        }
+        resolve();
+      });
+    });
+  });
+  const _logger = $logger.child({
+    context: "uploadFile",
+    profile: connection.profile.name,
+    local_path: localPath,
+    remote_path: remotePath
+  });
+  _logger.info("file uploaded", { bytes: localStats.size });
+  return localStats.size;
+}
+async function downloadFile(connection, remotePath, localPath) {
+  requirePermittedPath(connection, remotePath, "read");
+  await connection.withSftp(async (sftp) => {
+    await new Promise((resolve, reject) => {
+      sftp.fastGet(remotePath, localPath, (error) => {
+        if (error != null) {
+          reject(error);
+          return;
+        }
+        resolve();
+      });
+    });
+  });
+  const localStats = fs4__default.default.statSync(localPath);
+  const _logger = $logger.child({
+    context: "downloadFile",
+    profile: connection.profile.name,
+    remote_path: remotePath,
+    local_path: localPath
+  });
+  _logger.info("file downloaded", { bytes: localStats.size });
+  return localStats.size;
+}
+var POLICY_INPUT_SCHEMA = zod.z.strictObject({
+  readonly: zod.z.boolean().optional(),
+  allowSudo: zod.z.boolean().optional(),
+  execTimeoutMs: zod.z.number().int().positive().optional(),
+  connectTimeoutMs: zod.z.number().int().positive().optional(),
+  maxOutputCharacters: zod.z.number().int().positive().optional(),
+  maxReadFileBytes: zod.z.number().int().positive().optional(),
+  allowCommands: zod.z.array(zod.z.string()).optional(),
+  denyPatterns: zod.z.array(zod.z.string()).optional(),
+  allowedPaths: zod.z.array(zod.z.string()).optional()
+});
+var HOST_INPUT_SCHEMA = POLICY_INPUT_SCHEMA.extend({
+  // Kept strict by `.extend()` on a strict base — verified by the config tests.
+  host: zod.z.string().min(1),
+  port: zod.z.number().int().min(1).max(65535).optional(),
+  username: zod.z.string().min(1),
+  description: zod.z.string().optional(),
+  privateKeyPath: zod.z.string().optional(),
+  privateKey: zod.z.string().optional(),
+  passphrase: zod.z.string().optional(),
+  /** Name of an env var holding the passphrase, preferred over inlining it. */
+  passphraseEnv: zod.z.string().optional(),
+  password: zod.z.string().optional(),
+  /** Name of an env var holding the password, preferred over inlining it. */
+  passwordEnv: zod.z.string().optional(),
+  /** Pinned server host key, e.g. "SHA256:abc123…". */
+  hostKeyFingerprint: zod.z.string().optional(),
+  defaultCwd: zod.z.string().optional()
+});
+var CONFIG_INPUT_SCHEMA = zod.z.strictObject({
+  /** Ignored at runtime; present so editors can attach a JSON schema. */
+  $schema: zod.z.string().optional(),
+  defaults: POLICY_INPUT_SCHEMA.optional(),
+  hosts: zod.z.record(zod.z.string(), HOST_INPUT_SCHEMA)
+});
+
+// src/modules/config/env-host.ts
+function readEnv(name) {
+  const value = process.env[name];
+  if (value == null) {
+    return void 0;
+  }
+  const trimmed = value.trim();
+  if (trimmed === "") {
+    return void 0;
+  }
+  return trimmed;
+}
+function readBooleanEnv(name) {
+  const value = readEnv(name);
+  if (value == null) {
+    return void 0;
+  }
+  const normalized = value.toLowerCase();
+  if (TRUTHY_ENV_VALUES.includes(normalized) == true) {
+    return true;
+  }
+  if (FALSY_ENV_VALUES.includes(normalized) == false) {
+    throw new Error(`${name} must be one of ${[...TRUTHY_ENV_VALUES, ...FALSY_ENV_VALUES].join(", ")} (got "${value}")`);
+  }
+  return false;
+}
+function readIntegerEnv(name) {
+  const value = readEnv(name);
+  if (value == null) {
+    return void 0;
+  }
+  const parsed = Number(value);
+  if (Number.isInteger(parsed) == false || parsed <= 0) {
+    throw new Error(`${name} must be a positive integer (got "${value}")`);
+  }
+  return parsed;
+}
+function readListEnv(name) {
+  const value = readEnv(name);
+  if (value == null) {
+    return void 0;
+  }
+  const items = value.split(",").map((item) => item.trim()).filter((item) => item !== "");
+  if (items.length === 0) {
+    return void 0;
+  }
+  return items;
+}
+function buildConfigFromEnv() {
+  const host = readEnv(SINGLE_HOST_ENV.HOST);
+  if (host == null) {
+    return null;
+  }
+  const username = readEnv(SINGLE_HOST_ENV.USER);
+  if (username == null) {
+    throw new Error(`${SINGLE_HOST_ENV.HOST} is set, so ${SINGLE_HOST_ENV.USER} is required`);
+  }
+  const hostInput = {
+    host,
+    username,
+    port: readIntegerEnv(SINGLE_HOST_ENV.PORT),
+    description: readEnv(SINGLE_HOST_ENV.DESCRIPTION),
+    privateKeyPath: readEnv(SINGLE_HOST_ENV.KEY),
+    passphrase: readEnv(SINGLE_HOST_ENV.PASSPHRASE),
+    password: readEnv(SINGLE_HOST_ENV.PASSWORD),
+    hostKeyFingerprint: readEnv(SINGLE_HOST_ENV.HOST_KEY),
+    defaultCwd: readEnv(SINGLE_HOST_ENV.CWD),
+    readonly: readBooleanEnv(SINGLE_HOST_ENV.READONLY),
+    allowSudo: readBooleanEnv(SINGLE_HOST_ENV.ALLOW_SUDO),
+    allowCommands: readListEnv(SINGLE_HOST_ENV.ALLOW_COMMANDS),
+    denyPatterns: readListEnv(SINGLE_HOST_ENV.DENY_PATTERNS),
+    allowedPaths: readListEnv(SINGLE_HOST_ENV.ALLOWED_PATHS),
+    execTimeoutMs: readIntegerEnv(SINGLE_HOST_ENV.EXEC_TIMEOUT_MS),
+    connectTimeoutMs: readIntegerEnv(SINGLE_HOST_ENV.CONNECT_TIMEOUT_MS),
+    maxOutputCharacters: readIntegerEnv(SINGLE_HOST_ENV.MAX_OUTPUT_CHARACTERS),
+    maxReadFileBytes: readIntegerEnv(SINGLE_HOST_ENV.MAX_READ_FILE_BYTES)
+  };
+  const name = readEnv(SINGLE_HOST_ENV.NAME) ?? host;
+  const _logger = $logger.child({ context: "buildConfigFromEnv", profile: name });
+  _logger.debug("single-host config assembled from environment variables");
+  return { hosts: { [name]: hostInput } };
+}
+
+// src/modules/config/load-config.ts
+function resolveConfigSource(explicitPath) {
+  if (explicitPath != null && explicitPath.trim() !== "") {
+    return { kind: "file", path: expandHomePath(explicitPath) };
+  }
+  const fromSingleHostEnv = buildConfigFromEnv();
+  if (fromSingleHostEnv != null) {
+    return { kind: "env", config: fromSingleHostEnv };
+  }
+  const fromEnv = process.env[CONFIG_PATH_ENV];
+  if (fromEnv != null && fromEnv.trim() !== "") {
+    const trimmedValue = fromEnv.trim();
+    if (trimmedValue.startsWith("{") == true) {
+      return { kind: "inline", json: trimmedValue };
+    }
+    return { kind: "file", path: expandHomePath(trimmedValue) };
+  }
+  for (const filename of DEFAULT_CONFIG_FILENAMES) {
+    const candidate = path2__default.default.join(os__default.default.homedir(), filename);
+    if (fs4__default.default.existsSync(candidate) == true) {
+      return { kind: "file", path: candidate };
+    }
+  }
+  return { kind: "none" };
+}
+function compileDenyPatterns(profileName, sources) {
+  return sources.map((source) => {
+    try {
+      return new RegExp(source, "i");
+    } catch (ex) {
+      const _logger = $logger.child({ context: "compileDenyPatterns", profile: profileName });
+      _logger.error(ex, "denyPatterns entry is not a valid regular expression");
+      let detail = String(ex);
+      if (ex instanceof Error) {
+        detail = ex.message;
+      }
+      throw new Error(`profile '${profileName}' has an invalid denyPatterns entry /${source}/: ${detail}`);
+    }
+  });
+}
+function resolvePolicy(profileName, defaults, override) {
+  const allowCommands = [...override.allowCommands ?? defaults?.allowCommands ?? []];
+  if (allowCommands.length > 0 && allowCommands.includes("pwd") == false) {
+    allowCommands.push("pwd");
+  }
+  const denyPatternSources = override.denyPatterns ?? defaults?.denyPatterns ?? [];
+  const allowedPaths = override.allowedPaths ?? defaults?.allowedPaths ?? [];
+  const _logger = $logger.child({ context: "resolvePolicy", profile: profileName });
+  if (override.allowCommands?.length === 0 && (defaults?.allowCommands?.length ?? 0) > 0) {
+    _logger.warn("host sets allowCommands to an empty list, which removes the restriction from defaults");
+  }
+  if (override.allowedPaths?.length === 0 && (defaults?.allowedPaths?.length ?? 0) > 0) {
+    _logger.warn("host sets allowedPaths to an empty list, which removes the restriction from defaults");
+  }
+  return {
+    readonly: override.readonly ?? defaults?.readonly ?? false,
+    allowSudo: override.allowSudo ?? defaults?.allowSudo ?? true,
+    execTimeoutMs: override.execTimeoutMs ?? defaults?.execTimeoutMs ?? DEFAULT_EXEC_TIMEOUT_MS,
+    connectTimeoutMs: override.connectTimeoutMs ?? defaults?.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS,
+    maxOutputCharacters: override.maxOutputCharacters ?? defaults?.maxOutputCharacters ?? DEFAULT_MAX_OUTPUT_CHARACTERS,
+    maxReadFileBytes: override.maxReadFileBytes ?? defaults?.maxReadFileBytes ?? DEFAULT_MAX_READ_FILE_BYTES,
+    allowCommands,
+    denyPatterns: compileDenyPatterns(profileName, denyPatternSources),
+    allowedPaths
+  };
+}
+function resolveSecret(profileName, inlineValue, envVarName) {
+  if (envVarName == null) {
+    return inlineValue;
+  }
+  const fromEnv = process.env[envVarName];
+  if (fromEnv == null || fromEnv === "") {
+    const _logger = $logger.child({ context: "resolveSecret", profile: profileName, env_var: envVarName });
+    _logger.warn("env var referenced by the profile is empty; falling back to the inline value");
+    return inlineValue;
+  }
+  return fromEnv;
+}
+function toHostProfile(name, raw, defaults) {
+  const profile = {
+    name,
+    host: raw.host,
+    port: raw.port ?? DEFAULT_SSH_PORT,
+    username: raw.username,
+    description: raw.description,
+    privateKey: raw.privateKey,
+    passphrase: resolveSecret(name, raw.passphrase, raw.passphraseEnv),
+    password: resolveSecret(name, raw.password, raw.passwordEnv),
+    hostKeyFingerprint: raw.hostKeyFingerprint,
+    defaultCwd: raw.defaultCwd,
+    policy: resolvePolicy(name, defaults, raw)
+  };
+  if (raw.privateKeyPath != null) {
+    const expandedKeyPath = expandHomePath(raw.privateKeyPath);
+    profile.privateKeyPath = expandedKeyPath;
+    if (fs4__default.default.existsSync(expandedKeyPath) == false) {
+      const _logger = $logger.child({ context: "toHostProfile", profile: name });
+      _logger.warn("privateKeyPath does not exist; connections for this profile will fail", {
+        private_key_path: expandedKeyPath
+      });
+    }
+  }
+  return profile;
+}
+function warnOnLoosePermissions(configPath) {
+  if (process.platform === "win32") {
+    return;
+  }
+  const stats = fs4__default.default.statSync(configPath);
+  const permissionBits = stats.mode & 511;
+  if ((permissionBits & 63) === 0) {
+    return;
+  }
+  const _logger = $logger.child({ context: "warnOnLoosePermissions", config_path: configPath });
+  _logger.warn(`config file is readable by other users, run: chmod 600 ${configPath}`, {
+    mode: permissionBits.toString(8)
+  });
+}
+function loadConfig(explicitPath) {
+  let _logger = $logger.child({ context: "loadConfig" });
+  const source = resolveConfigSource(explicitPath);
+  if (source.kind === "none") {
+    _logger.warn("no config found; no host profiles are registered", {
+      searched: DEFAULT_CONFIG_FILENAMES,
+      env_vars: [SINGLE_HOST_ENV.HOST, CONFIG_PATH_ENV]
+    });
+    return { profiles: /* @__PURE__ */ new Map(), sourcePath: null, sourceLabel: "none" };
+  }
+  let parsedJson = null;
+  let sourcePath = null;
+  let sourceLabel = `inline ${CONFIG_PATH_ENV}`;
+  if (source.kind === "env") {
+    _logger = _logger.child({ config_source: "env" });
+    sourceLabel = `${SINGLE_HOST_ENV.HOST} environment variables`;
+    parsedJson = source.config;
+  } else {
+    let rawText = "";
+    if (source.kind === "inline") {
+      _logger = _logger.child({ config_source: "inline" });
+      rawText = source.json;
+    } else {
+      _logger = _logger.child({ config_path: source.path });
+      sourcePath = source.path;
+      sourceLabel = source.path;
+      if (fs4__default.default.existsSync(source.path) == false) {
+        _logger.error(null, "config file does not exist");
+        throw new Error(`ssh mcp config not found: ${source.path}`);
+      }
+      rawText = fs4__default.default.readFileSync(source.path, "utf8");
+    }
+    try {
+      parsedJson = JSON.parse(rawText);
+    } catch (ex) {
+      _logger.error(ex, "config is not valid json");
+      throw new Error(`ssh mcp config is not valid JSON (${sourceLabel})`);
+    }
+  }
+  const validated = CONFIG_INPUT_SCHEMA.safeParse(parsedJson);
+  if (validated.success == false) {
+    const issueSummary = validated.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join("; ");
+    _logger.error(validated.error, "config failed schema validation");
+    throw new Error(`ssh mcp config is invalid (${sourceLabel}): ${issueSummary}`);
+  }
+  if (sourcePath != null) {
+    warnOnLoosePermissions(sourcePath);
+  }
+  const profiles = /* @__PURE__ */ new Map();
+  for (const [name, hostInput] of Object.entries(validated.data.hosts)) {
+    profiles.set(name, toHostProfile(name, hostInput, validated.data.defaults));
+  }
+  _logger.info("config loaded", {
+    profile_count: profiles.size,
+    profiles: Array.from(profiles.keys())
+  });
+  return { profiles, sourcePath, sourceLabel };
+}
+function toHostSummary(profile) {
+  let authMethod = "agent";
+  if (profile.privateKeyPath != null || profile.privateKey != null) {
+    authMethod = "privateKey";
+  } else if (profile.password != null) {
+    authMethod = "password";
+  }
+  return {
+    name: profile.name,
+    host: profile.host,
+    port: profile.port,
+    username: profile.username,
+    description: profile.description,
+    authMethod,
+    readonly: profile.policy.readonly,
+    allowSudo: profile.policy.allowSudo,
+    allowedPaths: profile.policy.allowedPaths,
+    allowCommands: profile.policy.allowCommands
+  };
+}
+
+// src/modules/tools/format.ts
+var ENTRY_TYPE_MARKERS = {
+  file: "-",
+  directory: "d",
+  symlink: "l",
+  other: "?"
+};
+function formatHostList(config) {
+  if (config.profiles.size === 0) {
+    return [
+      "No SSH host profiles are registered.",
+      "",
+      `Put them in this server's MCP entry \u2014 ${CONFIG_PATH_ENV} takes the JSON itself:`,
+      "",
+      `    "env": {`,
+      `        "${CONFIG_PATH_ENV}": "{\\"hosts\\":{\\"my-server\\":{\\"host\\":\\"10.0.0.5\\",\\"username\\":\\"deploy\\",\\"privateKeyPath\\":\\"~/.ssh/id_ed25519\\"}}}"`,
+      "    }",
+      "",
+      `It also accepts a path to a JSON file, and ~/${DEFAULT_CONFIG_FILENAMES[0]} is picked up automatically.`,
+      "Restart this server after changing it."
+    ].join("\n");
+  }
+  const lines = [];
+  lines.push(`${config.profiles.size} SSH host profile(s) from ${config.sourceLabel}:`);
+  for (const profile of config.profiles.values()) {
+    const summary = toHostSummary(profile);
+    let accessLabel = "writable";
+    if (summary.readonly == true) {
+      accessLabel = "READ-ONLY";
+    }
+    let sudoLabel = "sudo=disabled";
+    if (summary.allowSudo == true) {
+      sudoLabel = "sudo=enabled";
+    }
+    lines.push("");
+    lines.push(`${summary.name}  \u2192  ${summary.username}@${summary.host}:${summary.port}  auth=${summary.authMethod}  ${accessLabel}  ${sudoLabel}`);
+    if (summary.description != null) {
+      lines.push(`    ${summary.description}`);
+    }
+    if (summary.allowedPaths.length > 0) {
+      lines.push(`    file tools limited to: ${summary.allowedPaths.join(", ")} (does not restrict ssh_exec)`);
+    }
+    if (summary.allowCommands.length > 0) {
+      lines.push(`    commands limited to: ${summary.allowCommands.join(", ")}`);
+    }
+  }
+  return lines.join("\n");
+}
+function formatExecResult(result, timeoutMs) {
+  const headerParts = [];
+  if (result.exitCode != null) {
+    headerParts.push(`exit code: ${result.exitCode}`);
+  } else {
+    headerParts.push("exit code: none (killed)");
+  }
+  if (result.signal != null) {
+    headerParts.push(`signal: ${result.signal}`);
+  }
+  headerParts.push(`${result.durationMs}ms`);
+  if (result.cwd != null) {
+    headerParts.push(`cwd: ${result.cwd}`);
+  }
+  const lines = [headerParts.join("  \xB7  ")];
+  if (result.timedOut == true) {
+    lines.push(`TIMED OUT after ${timeoutMs}ms \u2014 the channel was closed, but the remote process may still be running.`);
+  }
+  if (result.truncated == true) {
+    lines.push("Output was truncated; narrow the command (grep / head / tail) or raise maxOutputCharacters for this profile.");
+  }
+  lines.push("");
+  lines.push("--- stdout ---");
+  if (result.stdout === "") {
+    lines.push("(empty)");
+  } else {
+    lines.push(result.stdout);
+  }
+  if (result.stderr !== "") {
+    lines.push("");
+    lines.push("--- stderr ---");
+    lines.push(result.stderr);
+  }
+  return lines.join("\n");
+}
+function formatGuardRejection(action, verdict) {
+  const lines = [`Blocked by the host profile's guard policy: ${verdict.reason}`];
+  if (verdict.offendingText != null && verdict.offendingText !== action) {
+    lines.push(`Offending part: ${verdict.offendingText}`);
+  }
+  lines.push(`Requested: ${action}`);
+  lines.push("Nothing was sent to the remote host. Adjust the request, or relax the profile's policy in the config file.");
+  return lines.join("\n");
+}
+function formatSessionList(sessions) {
+  if (sessions.length === 0) {
+    return "No open SSH sessions. Open one with ssh_connect, or pass 'target' to run a one-off command.";
+  }
+  const lines = [`${sessions.length} open SSH session(s):`];
+  const now = Date.now();
+  for (const session of sessions) {
+    const idleSeconds = Math.round((now - new Date(session.lastUsedAt).getTime()) / 1e3);
+    lines.push("");
+    lines.push(`${session.sessionId}  \u2192  ${session.username}@${session.host}  profile: ${session.profileName}`);
+    lines.push(`    cwd: ${session.cwd}  \xB7  ${session.execCount} command(s)  \xB7  idle ${idleSeconds}s  \xB7  opened ${session.openedAt}`);
+  }
+  return lines.join("\n");
+}
+function formatDirectoryListing(remotePath, listing) {
+  if (listing.totalCount === 0) {
+    return `${remotePath} is empty.`;
+  }
+  let header = `${remotePath} \u2014 ${listing.totalCount} entrie(s):`;
+  if (listing.truncated == true) {
+    header = `${remotePath} \u2014 ${listing.totalCount} entrie(s), showing the first ${listing.entries.length}:`;
+  }
+  const lines = [header, ""];
+  for (const entry of listing.entries) {
+    const marker = ENTRY_TYPE_MARKERS[entry.type];
+    const size = formatBytes(entry.sizeBytes).padStart(9);
+    let name = entry.name;
+    if (entry.type === "directory") {
+      name = `${entry.name}/`;
+    }
+    lines.push(`${marker}  ${entry.mode}  ${size}  ${entry.modifiedAt}  ${name}`);
+  }
+  if (listing.truncated == true) {
+    lines.push("");
+    lines.push("Listing was capped; narrow the path or filter with ssh_exec if you need the rest.");
+  }
+  return lines.join("\n");
+}
+
+// src/modules/tools/tool-context.ts
+var MAX_EPHEMERAL_CONNECTIONS = 32;
+var activeEphemeralCount = 0;
+function textResult(text) {
+  return { content: [{ type: "text", text }] };
+}
+function errorResult(message) {
+  return { content: [{ type: "text", text: message }], isError: true };
+}
+function describeError(error) {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  return String(error);
+}
+function toToolError(error, toolName, action) {
+  const _logger = $logger.child({ context: toolName });
+  if (error instanceof GuardRejectionError) {
+    _logger.warn("rejected by the guard", { reason: error.verdict.reason, action });
+    const rendered = formatGuardRejection(action, error.verdict);
+    return errorResult(rendered);
+  }
+  _logger.error(error, `${toolName} failed`);
+  return errorResult(`${toolName} failed: ${describeError(error)}`);
+}
+function requireProfile(context, target) {
+  const profile = context.config.profiles.get(target);
+  if (profile != null) {
+    return profile;
+  }
+  const available = Array.from(context.config.profiles.keys());
+  if (available.length === 0) {
+    throw new Error(`no host profiles are registered \u2014 set ${SINGLE_HOST_ENV.HOST} / ${SINGLE_HOST_ENV.USER} in this server's env block (or ${CONFIG_PATH_ENV} for several hosts), then restart it`);
+  }
+  throw new Error(`unknown host profile '${target}' (registered: ${available.join(", ")})`);
+}
+function resolveProfile(context, args) {
+  const hasTarget = args.target != null && args.target.trim() !== "";
+  const hasSession = args.session != null && args.session.trim() !== "";
+  if (hasTarget == true && hasSession == true) {
+    throw new Error("pass either 'target' or 'session', not both \u2014 they can name different hosts with different policies");
+  }
+  if (hasSession == true) {
+    const session = context.sessions.require(args.session.trim());
+    return { profile: session.profile, session };
+  }
+  if (hasTarget == true) {
+    const profile = requireProfile(context, args.target.trim());
+    return { profile, session: null };
+  }
+  const onlyProfile = context.config.profiles.values().next().value;
+  if (context.config.profiles.size === 1 && onlyProfile != null) {
+    return { profile: onlyProfile, session: null };
+  }
+  if (context.config.profiles.size === 0) {
+    throw new Error(`no host profiles are registered \u2014 set ${SINGLE_HOST_ENV.HOST} / ${SINGLE_HOST_ENV.USER} in this server's env block, then restart it`);
+  }
+  const available = Array.from(context.config.profiles.keys());
+  throw new Error(`this server fronts several hosts, so 'target' is required (registered: ${available.join(", ")})`);
+}
+async function withHostConnection(profile, session, operation) {
+  if (session != null) {
+    return await session.runExclusive(operation);
+  }
+  if (activeEphemeralCount >= MAX_EPHEMERAL_CONNECTIONS) {
+    throw new Error(`too many concurrent one-off connections (${MAX_EPHEMERAL_CONNECTIONS}); open a session with ssh_connect and reuse it`);
+  }
+  activeEphemeralCount += 1;
+  const connection = new SshConnection(profile);
+  try {
+    return await operation(connection);
+  } finally {
+    try {
+      connection.disconnect();
+    } finally {
+      activeEphemeralCount -= 1;
+    }
+  }
+}
+function protectedLocalPathsOf(context) {
+  if (context.config.sourcePath == null) {
+    return [];
+  }
+  return [context.config.sourcePath];
+}
+
+// src/modules/tools/exec-tools.ts
+function registerExecTools(server, context) {
+  server.registerTool(
+    "ssh_exec",
+    {
+      title: "Run a command over SSH",
+      description: [
+        "Run a shell command on a registered SSH host and return stdout, stderr and the exit code.",
+        "With a single configured host, no target is needed. Pass 'session' to reuse an open session (which remembers its working directory), or 'target' to pick a host when several are registered \u2014 one or the other, never both.",
+        "A non-zero exit code is reported as normal output, not as a tool error \u2014 read the exit code and stderr to judge the outcome.",
+        "Almost everything is permitted: package installs, service restarts, sudo, interpreters. Only catastrophic operations are refused outright (wiping the filesystem root, formatting a disk, rebooting, flushing the firewall), and individual profiles may add their own limits."
+      ].join(" "),
+      inputSchema: {
+        command: zod.z.string().min(1).describe("Shell command, exactly as it would be typed in a terminal. Chaining with ';', '&&', '||' and pipes is allowed; each part is screened separately."),
+        target: zod.z.string().optional().describe("Host profile alias. Omit it when this server fronts a single host, which is the usual setup. Opens a one-off connection that is closed afterwards."),
+        session: zod.z.string().optional().describe("Session id from ssh_connect. Reuses that connection and keeps the working directory across calls."),
+        cwd: zod.z.string().optional().describe("Absolute directory to run in, with no shell metacharacters. With a session, the session also moves there."),
+        timeoutMs: zod.z.number().int().positive().optional().describe("Lowers the command timeout for this call; it cannot exceed the profile's own limit. The channel is closed when it elapses; the remote process may survive.")
+      },
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: true
+      }
+    },
+    async ({ command, target, session, cwd, timeoutMs }) => {
+      let _logger = $logger.child({ context: "ssh_exec" });
+      try {
+        const { profile, session: openSession } = resolveProfile(context, { target, session });
+        _logger = _logger.child({ profile: profile.name, session_id: openSession?.sessionId });
+        const requestedTimeoutMs = timeoutMs ?? profile.policy.execTimeoutMs;
+        const effectiveTimeoutMs = Math.min(requestedTimeoutMs, profile.policy.execTimeoutMs);
+        let requestedCwd = void 0;
+        if (cwd != null && cwd.trim() !== "") {
+          requestedCwd = cwd.trim();
+        }
+        _logger.debug("running command", { command, timeout_ms: effectiveTimeoutMs });
+        let result;
+        if (openSession != null) {
+          result = await openSession.exec(command, { cwd: requestedCwd, timeoutMs: effectiveTimeoutMs });
+        } else {
+          result = await withHostConnection(profile, null, async (connection) => {
+            return await connection.exec({
+              command,
+              cwd: requestedCwd,
+              timeoutMs: effectiveTimeoutMs,
+              maxOutputCharacters: profile.policy.maxOutputCharacters,
+              trackCwd: false
+            });
+          });
+        }
+        _logger.info("command executed", {
+          exit_code: result.exitCode,
+          duration_ms: result.durationMs,
+          timed_out: result.timedOut
+        });
+        const rendered = formatExecResult(result, effectiveTimeoutMs);
+        return textResult(rendered);
+      } catch (ex) {
+        return toToolError(ex, "ssh_exec", command);
+      }
+    }
+  );
+}
+var TARGET_DESCRIPTION = "Host profile alias. Omit it when this server fronts a single host, which is the usual setup.";
+var SESSION_DESCRIPTION = "Session id from ssh_connect, whose connection is reused. Pass this or 'target', not both.";
+function requirePermittedLocalPath(context, localPath, access) {
+  const verdict = inspectLocalPath(localPath, access, protectedLocalPathsOf(context));
+  if (verdict.allowed == false) {
+    throw new GuardRejectionError(verdict);
+  }
+}
+function registerFileTools(server, context) {
+  server.registerTool(
+    "ssh_list_dir",
+    {
+      title: "List a remote directory",
+      description: [
+        "List a directory on a registered SSH host over SFTP, with type, permissions, size and mtime.",
+        "Cheaper and more structured than running 'ls -la' through ssh_exec, and it works on read-only profiles."
+      ].join(" "),
+      inputSchema: {
+        path: zod.z.string().min(1).describe("Absolute remote directory path. Profiles with allowedPaths set accept only paths inside them."),
+        target: zod.z.string().optional().describe(TARGET_DESCRIPTION),
+        session: zod.z.string().optional().describe(SESSION_DESCRIPTION)
+      },
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
+      }
+    },
+    async ({ path: remotePath, target, session }) => {
+      const _logger = $logger.child({ context: "ssh_list_dir", remote_path: remotePath });
+      try {
+        const { profile, session: openSession } = resolveProfile(context, { target, session });
+        const listing = await withHostConnection(profile, openSession, async (connection) => {
+          return await listRemoteDirectory(connection, remotePath);
+        });
+        _logger.info("remote directory listed", {
+          profile: profile.name,
+          entry_count: listing.totalCount,
+          truncated: listing.truncated
+        });
+        const rendered = formatDirectoryListing(remotePath, listing);
+        return textResult(rendered);
+      } catch (ex) {
+        return toToolError(ex, "ssh_list_dir", `list ${remotePath}`);
+      }
+    }
+  );
+  server.registerTool(
+    "ssh_read_file",
+    {
+      title: "Read a remote file",
+      description: [
+        "Read a remote text file over SFTP and return its contents.",
+        "Oversized files come back truncated to their leading bytes rather than failing, so pointing this at a large log is safe.",
+        "Files that report size 0 but hold content (/proc, /sys) are read in full up to the ceiling."
+      ].join(" "),
+      inputSchema: {
+        path: zod.z.string().min(1).describe("Absolute remote file path."),
+        target: zod.z.string().optional().describe(TARGET_DESCRIPTION),
+        session: zod.z.string().optional().describe(SESSION_DESCRIPTION),
+        maxBytes: zod.z.number().int().positive().optional().describe("Lowers the read ceiling for this call; it cannot exceed the profile's maxReadFileBytes.")
+      },
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
+      }
+    },
+    async ({ path: remotePath, target, session, maxBytes }) => {
+      const _logger = $logger.child({ context: "ssh_read_file", remote_path: remotePath });
+      try {
+        const { profile, session: openSession } = resolveProfile(context, { target, session });
+        const requestedLimit = maxBytes ?? profile.policy.maxReadFileBytes;
+        const readLimit = Math.min(requestedLimit, profile.policy.maxReadFileBytes);
+        const file = await withHostConnection(profile, openSession, async (connection) => {
+          return await readRemoteFile(connection, remotePath, readLimit);
+        });
+        let header = `${remotePath} \u2014 ${formatBytes(file.readBytes)} read`;
+        if (file.sizeBytes > 0) {
+          header = `${remotePath} \u2014 ${formatBytes(file.sizeBytes)}`;
+        }
+        if (file.truncated == true) {
+          header += `, truncated to the first ${formatBytes(file.readBytes)}`;
+        }
+        _logger.info("remote file read", {
+          profile: profile.name,
+          size_bytes: file.sizeBytes,
+          read_bytes: file.readBytes,
+          truncated: file.truncated
+        });
+        return textResult(`${header}
+
+${file.content}`);
+      } catch (ex) {
+        return toToolError(ex, "ssh_read_file", `read ${remotePath}`);
+      }
+    }
+  );
+  server.registerTool(
+    "ssh_write_file",
+    {
+      title: "Write a remote file",
+      description: [
+        "Write or append UTF-8 text to a file on a registered SSH host over SFTP.",
+        "Use this instead of 'echo ... > file' through ssh_exec: no shell quoting to get wrong, and it works with multi-line content.",
+        "Refused on read-only profiles. The parent directory must already exist."
+      ].join(" "),
+      inputSchema: {
+        path: zod.z.string().min(1).describe("Absolute remote file path. Existing content is replaced unless 'append' is true."),
+        content: zod.z.string().describe("UTF-8 text to write."),
+        target: zod.z.string().optional().describe(TARGET_DESCRIPTION),
+        session: zod.z.string().optional().describe(SESSION_DESCRIPTION),
+        append: zod.z.boolean().optional().describe("Append instead of replacing. Defaults to false.")
+      },
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: true
+      }
+    },
+    async ({ path: remotePath, content, target, session, append }) => {
+      const _logger = $logger.child({ context: "ssh_write_file", remote_path: remotePath });
+      try {
+        const { profile, session: openSession } = resolveProfile(context, { target, session });
+        const shouldAppend = append ?? false;
+        const writtenBytes = await withHostConnection(profile, openSession, async (connection) => {
+          return await writeRemoteFile(connection, {
+            remotePath,
+            content,
+            append: shouldAppend
+          });
+        });
+        let verb = "Wrote";
+        if (shouldAppend == true) {
+          verb = "Appended";
+        }
+        _logger.info("remote file written", { profile: profile.name, bytes: writtenBytes });
+        return textResult(`${verb} ${formatBytes(writtenBytes)} to ${remotePath} on ${profile.name}.`);
+      } catch (ex) {
+        return toToolError(ex, "ssh_write_file", `write ${remotePath}`);
+      }
+    }
+  );
+  server.registerTool(
+    "ssh_upload",
+    {
+      title: "Upload a file over SFTP",
+      description: [
+        "Upload a local file to a registered SSH host over SFTP.",
+        "Refused on read-only profiles, and for local paths holding credentials (SSH keys, cloud credentials, this server's own config).",
+        "The remote parent directory must already exist."
+      ].join(" "),
+      inputSchema: {
+        localPath: zod.z.string().min(1).describe("Local file path on the machine running this MCP server. '~' is expanded."),
+        remotePath: zod.z.string().min(1).describe("Absolute destination path on the remote host, including the filename."),
+        target: zod.z.string().optional().describe(TARGET_DESCRIPTION),
+        session: zod.z.string().optional().describe(SESSION_DESCRIPTION)
+      },
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: true
+      }
+    },
+    async ({ localPath, remotePath, target, session }) => {
+      const _logger = $logger.child({ context: "ssh_upload", remote_path: remotePath });
+      try {
+        const { profile, session: openSession } = resolveProfile(context, { target, session });
+        const resolvedLocalPath = expandHomePath(localPath);
+        requirePermittedLocalPath(context, resolvedLocalPath, "read");
+        if (fs4__default.default.existsSync(resolvedLocalPath) == false) {
+          return textResult(`local file not found: ${resolvedLocalPath}`);
+        }
+        const transferredBytes = await withHostConnection(profile, openSession, async (connection) => {
+          return await uploadFile(connection, resolvedLocalPath, remotePath);
+        });
+        _logger.info("file uploaded", { profile: profile.name, bytes: transferredBytes });
+        return textResult(`Uploaded ${resolvedLocalPath} \u2192 ${remotePath} (${formatBytes(transferredBytes)}) on ${profile.name}.`);
+      } catch (ex) {
+        return toToolError(ex, "ssh_upload", `upload to ${remotePath}`);
+      }
+    }
+  );
+  server.registerTool(
+    "ssh_download",
+    {
+      title: "Download a file over SFTP",
+      description: [
+        "Download a file from a registered SSH host to the machine running this MCP server.",
+        "Use this for binaries or files too large to read into the conversation; missing local directories are created.",
+        "The local destination is overwritten, and paths holding credentials or this server's own configuration are refused."
+      ].join(" "),
+      inputSchema: {
+        remotePath: zod.z.string().min(1).describe("Absolute source path on the remote host."),
+        localPath: zod.z.string().min(1).describe("Local destination path, including the filename. '~' is expanded. Overwritten if it exists."),
+        target: zod.z.string().optional().describe(TARGET_DESCRIPTION),
+        session: zod.z.string().optional().describe(SESSION_DESCRIPTION)
+      },
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: true
+      }
+    },
+    async ({ remotePath, localPath, target, session }) => {
+      const _logger = $logger.child({ context: "ssh_download", remote_path: remotePath });
+      try {
+        const { profile, session: openSession } = resolveProfile(context, { target, session });
+        const resolvedLocalPath = expandHomePath(localPath);
+        requirePermittedLocalPath(context, resolvedLocalPath, "write");
+        fs4__default.default.mkdirSync(path2__default.default.dirname(resolvedLocalPath), { recursive: true });
+        const transferredBytes = await withHostConnection(profile, openSession, async (connection) => {
+          return await downloadFile(connection, remotePath, resolvedLocalPath);
+        });
+        _logger.info("file downloaded", { profile: profile.name, bytes: transferredBytes });
+        return textResult(`Downloaded ${remotePath} \u2192 ${resolvedLocalPath} (${formatBytes(transferredBytes)}) from ${profile.name}.`);
+      } catch (ex) {
+        return toToolError(ex, "ssh_download", `download ${remotePath}`);
+      }
+    }
+  );
+}
+
+// src/modules/tools/host-tools.ts
+function registerHostTools(server, context) {
+  server.registerTool(
+    "ssh_list_hosts",
+    {
+      title: "List SSH host profiles",
+      description: [
+        "List the SSH hosts this server may connect to, with each host's guard policy.",
+        "Call this first: every other tool takes a profile alias as its 'target', and no host outside this list can be reached.",
+        "Credentials are never returned \u2014 only which auth method the profile uses."
+      ].join(" "),
+      inputSchema: {},
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+      }
+    },
+    async () => {
+      const _logger = $logger.child({ context: "ssh_list_hosts" });
+      try {
+        const listing = formatHostList(context.config);
+        _logger.debug("host list returned", { profile_count: context.config.profiles.size });
+        return textResult(listing);
+      } catch (ex) {
+        return toToolError(ex, "ssh_list_hosts", "list hosts");
+      }
+    }
+  );
+  server.registerTool(
+    "ssh_reload_config",
+    {
+      title: "Reload the host configuration",
+      description: [
+        "Re-read the host configuration and apply it, without restarting the MCP server.",
+        "Use after the operator edits the config file \u2014 adding a host, tightening a policy.",
+        "Every open session is closed first, so the new policy is in force everywhere rather than leaving old sessions on the old rules.",
+        "Configuration supplied through environment variables is fixed for the life of the process; changing that still needs a restart."
+      ].join(" "),
+      inputSchema: {},
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+      }
+    },
+    async () => {
+      const _logger = $logger.child({ context: "ssh_reload_config" });
+      try {
+        const previousLabel = context.config.sourceLabel;
+        const closedSessions = context.sessions.list().length;
+        context.sessions.closeAll();
+        const reloaded = context.reloadConfig();
+        const lines = [
+          `Reloaded ${reloaded.profiles.size} host profile(s) from ${reloaded.sourceLabel}.`
+        ];
+        if (reloaded.profiles.size > 0) {
+          lines.push(`Hosts: ${Array.from(reloaded.profiles.keys()).join(", ")}`);
+        }
+        if (closedSessions > 0) {
+          lines.push(`Closed ${closedSessions} open session(s); reopen with ssh_connect if needed.`);
+        }
+        if (reloaded.sourcePath == null) {
+          lines.push("This config comes from environment variables, which cannot change while the server runs \u2014 restart the MCP server to apply edits to them.");
+        }
+        _logger.info("config reloaded", {
+          profile_count: reloaded.profiles.size,
+          previous_source: previousLabel,
+          config_source: reloaded.sourceLabel
+        });
+        return textResult(lines.join("\n"));
+      } catch (ex) {
+        return toToolError(ex, "ssh_reload_config", "reload the configuration");
+      }
+    }
+  );
+}
+function registerSessionTools(server, context) {
+  server.registerTool(
+    "ssh_connect",
+    {
+      title: "Open an SSH session",
+      description: [
+        "Open a reusable SSH session to a registered host and return its session id.",
+        "Prefer this over one-off 'target' calls when running several commands: it pays the handshake once and remembers the working directory, so a 'cd' in one ssh_exec still applies to the next.",
+        "Close it with ssh_disconnect when done; idle sessions are reaped automatically, and a session whose connection drops reports that rather than silently reconnecting."
+      ].join(" "),
+      inputSchema: {
+        target: zod.z.string().optional().describe("Host profile alias. Omit it when this server fronts a single host, which is the usual setup."),
+        cwd: zod.z.string().optional().describe("Absolute directory to start in, with no shell metacharacters. Defaults to the profile's defaultCwd, else the login shell's directory.")
+      },
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: true
+      }
+    },
+    async ({ target, cwd }) => {
+      let _logger = $logger.child({ context: "ssh_connect", target });
+      let openedSessionId = null;
+      try {
+        const { profile } = resolveProfile(context, { target });
+        const session = await context.sessions.open(profile);
+        openedSessionId = session.sessionId;
+        _logger = _logger.child({ session_id: session.sessionId });
+        if (cwd != null && cwd.trim() !== "") {
+          session.cwd = cwd.trim();
+        }
+        const probe = await session.exec("pwd");
+        const probeSucceeded = probe.exitCode === 0 && probe.timedOut == false;
+        if (probeSucceeded == false) {
+          context.sessions.close(session.sessionId);
+          openedSessionId = null;
+          _logger.warn("session probe failed, closing the session", {
+            exit_code: probe.exitCode,
+            timed_out: probe.timedOut,
+            stderr: probe.stderr
+          });
+          return errorResult(`ssh_connect failed: could not confirm the starting directory.
+${probe.stderr.trim()}`);
+        }
+        const lines = [
+          `Opened session ${session.sessionId} \u2192 ${profile.username}@${profile.host}:${profile.port}`,
+          `cwd: ${session.cwd}`
+        ];
+        if (profile.policy.readonly == true) {
+          lines.push("This profile is READ-ONLY: writes, redirections and uploads will be rejected.");
+        }
+        lines.push(`Run commands with ssh_exec({ session: "${session.sessionId}", command: "..." }).`);
+        _logger.info("session opened via tool", { cwd: session.cwd });
+        return textResult(lines.join("\n"));
+      } catch (ex) {
+        if (openedSessionId != null) {
+          context.sessions.close(openedSessionId);
+        }
+        return toToolError(ex, "ssh_connect", `connect to ${target ?? "the configured host"}`);
+      }
+    }
+  );
+  server.registerTool(
+    "ssh_disconnect",
+    {
+      title: "Close an SSH session",
+      description: "Close an open SSH session and release its connection.",
+      inputSchema: {
+        session: zod.z.string().describe("Session id returned by ssh_connect.")
+      },
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
+      }
+    },
+    async ({ session }) => {
+      const _logger = $logger.child({ context: "ssh_disconnect", session_id: session });
+      try {
+        const closed = context.sessions.close(session);
+        if (closed == false) {
+          return errorResult(`no open session with id '${session}'. Call ssh_list_sessions to see what is open.`);
+        }
+        _logger.info("session closed via tool");
+        return textResult(`Closed session ${session}.`);
+      } catch (ex) {
+        return toToolError(ex, "ssh_disconnect", `close ${session}`);
+      }
+    }
+  );
+  server.registerTool(
+    "ssh_list_sessions",
+    {
+      title: "List open SSH sessions",
+      description: "List every open SSH session with its host, working directory and idle time.",
+      inputSchema: {},
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+      }
+    },
+    async () => {
+      try {
+        const sessions = context.sessions.list();
+        const rendered = formatSessionList(sessions);
+        return textResult(rendered);
+      } catch (ex) {
+        return toToolError(ex, "ssh_list_sessions", "list sessions");
+      }
+    }
+  );
+}
+
+// src/modules/tools/index.ts
+function registerAllTools(server, context) {
+  registerHostTools(server, context);
+  registerSessionTools(server, context);
+  registerExecTools(server, context);
+  registerFileTools(server, context);
+}
+
+// src/server.ts
+var SERVER_INSTRUCTIONS = [
+  "This server runs shell commands and transfers files on remote hosts over SSH.",
+  "Only hosts pre-registered in a local config file are reachable \u2014 arbitrary host/credential arguments are not accepted.",
+  "",
+  "Usually one server entry fronts one host, so no 'target' argument is needed \u2014 omit it and the configured host is used. ssh_list_hosts shows what is registered and what it permits.",
+  "",
+  "Workflow:",
+  "1. One command: ssh_exec with just 'command'.",
+  "2. Several commands in a row: ssh_connect once, then ssh_exec with 'session' (the working directory persists across calls), then ssh_disconnect.",
+  "3. Files: ssh_list_dir, ssh_read_file, ssh_write_file, ssh_upload, ssh_download \u2014 prefer these over shell equivalents; no quoting to get wrong.",
+  "Pass 'target' only when ssh_list_hosts shows several hosts, and never together with 'session'.",
+  "",
+  "What is permitted: ordinary administration, without asking \u2014 package installs, service restarts, sudo, interpreters, config edits, deployments.",
+  "Refused on every profile, and only these: operations that destroy the machine or cut this connection \u2014 wiping the filesystem root or a system directory, deleting a file the host cannot boot without, formatting a disk, writing raw bytes to a block device, rebooting or powering off, flushing the firewall, removing every cron job.",
+  "Individual profiles may add their own limits (read-only, an allow-list, deny patterns, path restrictions). ssh_list_hosts shows which apply where.",
+  "",
+  "Commands run with no terminal and with stdin closed, so anything that waits for input fails immediately instead of hanging: use non-interactive flags (apt-get -y, sudo -n), 'top -bn1' rather than 'top', and ssh_write_file rather than an editor.",
+  "A job that may outlive its timeout should be started detached (nohup \u2026 &, tmux new -d) and polled through its log.",
+  "",
+  "A guard rejection is a policy decision, not a transient failure \u2014 do not retry the same command; report it and ask before working around it.",
+  "A non-zero exit code is returned as normal output; read it and stderr to judge what happened.",
+  "You still carry the judgement the guards do not: these are real hosts, and an irreversible action deserves a check with the operator first."
+].join("\n");
+function createSshMcpServer(options) {
+  const _logger = $logger.child({ context: "createSshMcpServer" });
+  const config = loadConfig(options?.configPath);
+  const sessions = new SshSessionManager();
+  sessions.startIdleSweeper();
+  const server = new mcp_js.McpServer(
+    {
+      name: SERVER_NAME,
+      version: SERVER_VERSION
+    },
+    {
+      instructions: SERVER_INSTRUCTIONS
+    }
+  );
+  const context = {
+    config,
+    sessions,
+    reloadConfig() {
+      const reloaded = loadConfig(options?.configPath);
+      context.config = reloaded;
+      return reloaded;
+    }
+  };
+  registerAllTools(server, context);
+  _logger.info("mcp server built", {
+    profile_count: config.profiles.size,
+    config_source: config.sourceLabel
+  });
+  return {
+    server,
+    sessions,
+    get config() {
+      return context.config;
+    },
+    reloadConfig() {
+      return context.reloadConfig();
+    },
+    shutdown() {
+      sessions.stopIdleSweeper();
+      sessions.closeAll();
+    }
+  };
+}
+
+// src/cli.ts
+function parseArguments(argv) {
+  const parsed = { showHelp: false, showVersion: false, checkOnly: false };
+  for (let index = 0; index < argv.length; index++) {
+    const argument = argv[index];
+    if (argument === "--help" || argument === "-h") {
+      parsed.showHelp = true;
+      continue;
+    }
+    if (argument === "--version" || argument === "-v") {
+      parsed.showVersion = true;
+      continue;
+    }
+    if (argument === "--check") {
+      parsed.checkOnly = true;
+      continue;
+    }
+    if (argument === "--config" || argument === "-c") {
+      const value = argv[index + 1];
+      if (value == null || value.startsWith("-") == true) {
+        throw new Error(`${argument} requires a file path`);
+      }
+      parsed.configPath = value;
+      index++;
+      continue;
+    }
+    if (argument.startsWith("--config=") == true) {
+      const value = argument.slice("--config=".length);
+      if (value === "") {
+        throw new Error("--config= requires a file path");
+      }
+      parsed.configPath = value;
+      continue;
+    }
+  }
+  return parsed;
+}
+var HELP_TEXT = [
+  `${SERVER_NAME} ${SERVER_VERSION} \u2014 MCP server for SSH command execution and SFTP transfers`,
+  "",
+  "Usage:",
+  "  akms-ssh [--config <path>]",
+  "",
+  "Options:",
+  "  -c, --config <path>  Host profile config file",
+  `                       (default: ${CONFIG_PATH_ENV} env var, else ~/${DEFAULT_CONFIG_FILENAMES[0]})`,
+  "      --check          Connect to every profile, report the result, and exit.",
+  "                       Prints each host key fingerprint so it can be pinned.",
+  "  -v, --version        Print the version and exit",
+  "  -h, --help           Print this help and exit",
+  "",
+  "Environment:",
+  `  ${CONFIG_PATH_ENV}     Host profiles as JSON, or a path to a JSON file.`,
+  "                     A value starting with '{' is read as the config itself, so an",
+  "                     MCP client can carry the whole setup in its own env block.",
+  `  ${LOG_LEVEL_ENV}  silent | debug | info | warn | error  (default: info, written to stderr)`,
+  "",
+  "The server speaks MCP over stdio; run it from an MCP client, not interactively."
+].join("\n");
+function describeAuth(profile) {
+  if (profile.privateKeyPath != null) {
+    return `key ${profile.privateKeyPath}`;
+  }
+  if (profile.privateKey != null) {
+    return "inline key";
+  }
+  if (profile.password != null) {
+    return "password";
+  }
+  return "ssh agent";
+}
+async function runConnectionCheck(config) {
+  if (config.profiles.size === 0) {
+    process.stdout.write(`No host profiles are registered (config source: ${config.sourceLabel}).
+`);
+    return 1;
+  }
+  process.stdout.write(`Checking ${config.profiles.size} profile(s) from ${config.sourceLabel}
+
+`);
+  const profiles = Array.from(config.profiles.values());
+  const results = await Promise.all(profiles.map(async (profile) => {
+    const connection = new SshConnection(profile);
+    const startedAt = Date.now();
+    try {
+      await connection.connect();
+      return {
+        profile,
+        connected: true,
+        durationMs: Date.now() - startedAt,
+        fingerprint: connection.hostKeyFingerprint,
+        detail: ""
+      };
+    } catch (ex) {
+      let detail = String(ex);
+      if (ex instanceof Error) {
+        detail = ex.message;
+      }
+      return {
+        profile,
+        connected: false,
+        durationMs: Date.now() - startedAt,
+        fingerprint: connection.hostKeyFingerprint,
+        detail
+      };
+    } finally {
+      connection.disconnect();
+    }
+  }));
+  let connectedCount = 0;
+  for (const result of results) {
+    const endpoint = `${result.profile.username}@${result.profile.host}:${result.profile.port}`;
+    const auth = describeAuth(result.profile);
+    if (result.connected == true) {
+      connectedCount += 1;
+      process.stdout.write(`  OK      ${result.profile.name}  \u2192  ${endpoint}  (${auth}, ${result.durationMs}ms)
+`);
+    } else {
+      process.stdout.write(`  FAILED  ${result.profile.name}  \u2192  ${endpoint}  (${auth})
+`);
+      process.stdout.write(`          ${result.detail}
+`);
+    }
+    if (result.fingerprint != null) {
+      let pinNote = "not pinned \u2014 add it as hostKeyFingerprint to detect a changed key";
+      if (result.profile.hostKeyFingerprint != null) {
+        pinNote = "pinned";
+      }
+      process.stdout.write(`          host key ${result.fingerprint}  (${pinNote})
+`);
+    }
+  }
+  process.stdout.write(`
+${connectedCount} of ${results.length} reachable
+`);
+  if (connectedCount === results.length) {
+    return 0;
+  }
+  return 1;
+}
+async function main() {
+  const _logger = $logger.child({ context: "cli" });
+  const cliArguments = parseArguments(process.argv.slice(2));
+  if (cliArguments.showHelp == true) {
+    process.stderr.write(`${HELP_TEXT}
+`);
+    return;
+  }
+  if (cliArguments.showVersion == true) {
+    process.stderr.write(`${SERVER_VERSION}
+`);
+    return;
+  }
+  if (cliArguments.checkOnly == true && process.env[LOG_LEVEL_ENV] == null) {
+    process.env[LOG_LEVEL_ENV] = "silent";
+  }
+  const instance = createSshMcpServer({ configPath: cliArguments.configPath });
+  if (cliArguments.checkOnly == true) {
+    const exitCode = await runConnectionCheck(instance.config);
+    instance.shutdown();
+    process.exit(exitCode);
+  }
+  let shuttingDown = false;
+  const shutdown = (signal) => {
+    if (shuttingDown == true) {
+      return;
+    }
+    shuttingDown = true;
+    _logger.info("shutting down", { signal });
+    instance.shutdown();
+    void instance.server.close().finally(() => {
+      process.exit(0);
+    });
+  };
+  process.on("SIGINT", () => {
+    shutdown("SIGINT");
+  });
+  process.on("SIGTERM", () => {
+    shutdown("SIGTERM");
+  });
+  process.stdin.on("close", () => {
+    shutdown("stdin-close");
+  });
+  const transport = new stdio_js.StdioServerTransport();
+  await instance.server.connect(transport);
+  _logger.info("mcp server ready on stdio", {
+    server: SERVER_NAME,
+    version: SERVER_VERSION,
+    config_source: instance.config.sourceLabel,
+    profile_count: instance.config.profiles.size
+  });
+}
+main().catch((error) => {
+  const _logger = $logger.child({ context: "cli" });
+  _logger.error(error, "mcp server failed to start");
+  let detail = String(error);
+  if (error instanceof Error) {
+    detail = error.message;
+  }
+  process.stderr.write(`akms-ssh: ${detail}
+`);
+  process.exit(1);
+});
+//# sourceMappingURL=cli.cjs.map
+//# sourceMappingURL=cli.cjs.map