@neoline/hostbridge 2.0.2 → 2.0.4

package/README.md

@@ -6,13 +6,12 @@ This repo is portable: it ships with no personal server paths or built-in hosts.
 
 ## Tools
 
-- `hosts_list` — reload and show configured connection targets and local script availability when applicable.
-- `hosts_reload` — explicitly reload configured connection targets without restarting the MCP server.
+- `hosts_list` — show the connection targets loaded by the daemon.
 - `session_open(host_id, connect_timeout=30)` — open a persistent interactive shell for one configured host.
-- `sessions_list()` — list live sessions in this MCP process.
+- `sessions_list()` — list live sessions in the daemon.
 - `sessions_close_all()` — close every live session in one call; useful for shutdown and cleanup.
 - `command_run(session_id, command, timeout=60)` — run a foreground command and wait for completion.
-- `task_start(session_id, command)` — start a remote background job under `$HOME/.hostbridge/jobs/<task_id>`.
+- `task_start(session_id, command)` — start a remote background job under `$HOME/.hostbridge/jobs/<task_id>` with private permissions.
 - `task_status(session_id, task_id, tail_lines=80)` — poll job state, exit code, and log tail.
 - `task_stop(session_id, task_id)` — terminate a running background job and reap its process.
 - `session_write(session_id, text)` — send a raw line for interactive edge cases.
@@ -23,7 +22,7 @@ This repo is portable: it ships with no personal server paths or built-in hosts.
 - `file_download(session_id, remote_path, local_path)` — download a remote file with chunked shell/base64 transfer, up to 100MiB.
 - `session_close(session_id)` — close a persistent session.
 
-Every tool returns a structured payload with a stable `error_code` on failure (`HOST_NOT_FOUND`, `SESSION_NOT_FOUND`, `POLICY_DENIED`, `TASK_NOT_FOUND`, `TIMEOUT`, `INTERNAL`).
+Every tool returns a structured payload with a stable lowercase `error_code`, such as `not_found`, `denied`, `remote_error`, `timeout`, or `internal`.
 
 ## Install and configure v1
 
@@ -93,6 +92,8 @@ The bridge supports:
 
 Each SSH channel opens its own HostBridge backend session and closes it when the channel ends, so an interactive shell `exit` does not kill later exec or file-transfer requests. The SFTP/SCP implementation is a compatibility layer backed by HostBridge's shell/base64 transfer primitives, so it keeps working across JumpServer/menu/wrapper login flows where direct remote SFTP is unavailable. It inherits the same transfer size limit (100MiB by default); for larger files, start a remote-native pull from the target host.
 
+Mock SSH exec channels are byte-oriented. Binary stdin is staged with one total deadline, client EOF is propagated to the remote command, and disconnect, timeout, cancellation, or a missing backend exit status closes the HostBridge session. PTY command output is tail-bounded before base64 encoding, so arbitrary bytes are preserved without accumulating unbounded local output.
+
 ## Daemon lifecycle
 
 HostBridge always keeps remote sessions in the local daemon. The MCP server process is only a lightweight stdio adapter for agent clients and talks to the daemon over a Unix domain socket. If the daemon is not already running, the MCP adapter starts it lazily on the first tool call.
@@ -109,6 +110,8 @@ The daemon uses a Unix domain socket with a small JSON-line RPC protocol by defa
 ~/.hostbridge/daemon.sock
 ```
 
+Every client validates both protocol version and the exact HostBridge runtime version. When an older or incompatible daemon owns the configured socket, the launcher shuts it down and starts the current runtime before use. The daemon accepts at most 64 concurrent control connections; an idle control connection is closed after 30 seconds so abandoned clients cannot consume unbounded worker threads.
+
 When launched through the npm wrapper on macOS, HostBridge sets `HOSTBRIDGE_DAEMON_SOCKET` to `/private/tmp/hostbridge-$USER/daemon.sock` so sandboxed MCP launchers do not accidentally isolate the daemon under a rewritten `HOME`. Python-only launches keep the `~/.hostbridge/daemon.sock` default unless you set `HOSTBRIDGE_DAEMON_SOCKET` or `HOSTBRIDGE_DAEMON_DIR`.
 
 This avoids fixed port conflicts, removes the local HTTP surface, and keeps the control API local to the current machine. The daemon directory should be private to the local user. To point daemon management commands at a custom socket path:
@@ -127,7 +130,7 @@ For MCP clients, prefer setting the environment variable instead of relying on s
 }
 ```
 
-Sessions can outlive a single agent client process. HostBridge records an optional `HOSTBRIDGE_AGENT_ID` owner on sessions and refuses cross-owner operations unless a force-close path is used. Set `HOSTBRIDGE_MAX_SESSIONS_PER_HOST` to cap concurrent live sessions per configured host (default `0`, unlimited).
+Sessions can outlive a single agent client process. HostBridge records an optional `HOSTBRIDGE_AGENT_ID` owner on sessions and refuses cross-owner operations unless an internal cleanup path force-closes them. Configure `limits.max_sessions` per host to cap concurrent live sessions (default `16`).
 
 ## Configuration lifecycle
 
@@ -259,7 +262,7 @@ Claude Desktop style config:
   "mcpServers": {
     "hostbridge": {
       "command": "npx",
-      "args": ["-y", "hostbridge"],
+      "args": ["-y", "@neoline/hostbridge"],
       "env": {"HOSTBRIDGE_AGENT_ID": "claude-code"}
     }
   }
@@ -288,6 +291,8 @@ Environment variables:
 | `HOSTBRIDGE_DENYLIST=pat1:pat2` | Append extra deny regex patterns (colon-separated). |
 | `HOSTBRIDGE_IDLE_TIMEOUT=900` | Idle timeout in seconds before an inactive session is reaped (default 1800). |
 | `HOSTBRIDGE_AUDIT_LOG=/path/to/audit.jsonl` | Override audit log path (default `~/.hostbridge/audit.jsonl`). |
+| `HOSTBRIDGE_AUDIT_MAX_BYTES=10485760` | Rotate the current audit log before it exceeds this size (default 10MiB). |
+| `HOSTBRIDGE_AUDIT_BACKUP_COUNT=3` | Number of rotated audit logs to retain (default 3; `0` retains none). |
 
 Default denylist blocks obviously destructive commands (`rm -rf /`, `mkfs`, `dd of=/dev/sd*`, fork bombs, `shutdown`, `reboot`). A denied command returns `error_code=POLICY_DENIED` with the matched pattern, and is recorded in the audit log alongside session/task lifecycle events.
 
@@ -298,7 +303,9 @@ Policy config file (optional):
   "idle_timeout_seconds": 1800,
   "use_default_denylist": true,
   "command_denylist": ["\\bmytool\\b"],
-  "audit_log_path": "~/.hostbridge/audit.jsonl"
+  "audit_log_path": "~/.hostbridge/audit.jsonl",
+  "audit_max_bytes": 10485760,
+  "audit_backup_count": 3
 }
 ```
 

package/bin/hostbridge.js

@@ -1,22 +1,65 @@
 #!/usr/bin/env node
-import { spawn } from 'node:child_process';
-import { existsSync } from 'node:fs';
+import { spawn, spawnSync } from 'node:child_process';
+import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, rmSync } from 'node:fs';
 import { tmpdir, userInfo } from 'node:os';
 import { dirname, join, delimiter } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const packageRoot = dirname(__dirname);
-const pythonPath = process.env.HOSTBRIDGE_PYTHON || process.env.SERVER_CONTROL_MCP_PYTHON || 'python3';
 const bundledSrc = join(packageRoot, 'src');
 const moduleDir = join(bundledSrc, 'server_control_mcp');
 const docsUrl = 'https://www.npmjs.com/package/@neoline/hostbridge';
+const packageVersion = JSON.parse(readFileSync(join(packageRoot, 'package.json'), 'utf8')).version;
 
 function hostbridgeRuntimeDir(username) {
   const baseTmp = process.platform === 'darwin' ? '/private/tmp' : tmpdir();
   return join(baseTmp, `hostbridge-${username}`);
 }
 
+function ensurePrivateDirectory(path) {
+  mkdirSync(path, { recursive: true, mode: 0o700 });
+  const metadata = lstatSync(path);
+  if (!metadata.isDirectory() || metadata.isSymbolicLink()) {
+    throw new Error(`refusing unsafe npm runtime path: ${path}`);
+  }
+  if (typeof process.getuid === 'function' && metadata.uid !== process.getuid()) {
+    throw new Error(`npm runtime path is not owned by the current user: ${path}`);
+  }
+  chmodSync(path, 0o700);
+}
+
+function acquireBootstrapLock(path) {
+  const deadline = Date.now() + 120_000;
+  const sleeper = new Int32Array(new SharedArrayBuffer(4));
+  while (Date.now() < deadline) {
+    try {
+      mkdirSync(path, { mode: 0o700 });
+      return;
+    } catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+      const metadata = lstatSync(path);
+      if (!metadata.isDirectory() || metadata.isSymbolicLink()) {
+        throw new Error(`refusing unsafe npm bootstrap lock: ${path}`);
+      }
+      if (Date.now() - metadata.mtimeMs > 300_000) {
+        rmSync(path, { recursive: true });
+        continue;
+      }
+      Atomics.wait(sleeper, 0, 0, 50);
+    }
+  }
+  throw new Error(`timed out waiting for npm runtime bootstrap: ${path}`);
+}
+
+function runBootstrap(python, args, env) {
+  const result = spawnSync(python, args, { stdio: 'inherit', env });
+  if (result.error) throw result.error;
+  if (result.signal || result.status !== 0) {
+    throw new Error(`Python runtime bootstrap failed (${result.signal || `exit ${result.status}`})`);
+  }
+}
+
 if (!existsSync(moduleDir)) {
   console.error(`hostbridge: bundled Python sources not found at ${moduleDir}`);
   console.error(`  This npm package wraps a Python MCP core. See: ${docsUrl}`);
@@ -27,7 +70,40 @@ const env = { ...process.env };
 env.PYTHONPATH = env.PYTHONPATH ? `${bundledSrc}${delimiter}${env.PYTHONPATH}` : bundledSrc;
 env.HOSTBRIDGE_DEFAULT_MCP_COMMAND = env.HOSTBRIDGE_DEFAULT_MCP_COMMAND || 'npx';
 env.HOSTBRIDGE_DEFAULT_MCP_ARGS = env.HOSTBRIDGE_DEFAULT_MCP_ARGS || JSON.stringify(['-y', '@neoline/hostbridge']);
-env.HOSTBRIDGE_NPM_LAUNCHER = env.HOSTBRIDGE_NPM_LAUNCHER || '1';
+const configuredPython = env.HOSTBRIDGE_PYTHON || env.SERVER_CONTROL_MCP_PYTHON;
+let pythonPath = configuredPython;
+if (!pythonPath) {
+  const username = env.USER || env.LOGNAME || userInfo().username || 'user';
+  const npmRuntimeRoot = env.HOSTBRIDGE_NPM_RUNTIME_DIR || join(hostbridgeRuntimeDir(username), 'npm-runtime');
+  const environmentDir = join(npmRuntimeRoot, packageVersion);
+  const scriptsDir = process.platform === 'win32' ? 'Scripts' : 'bin';
+  const environmentPython = join(environmentDir, scriptsDir, process.platform === 'win32' ? 'python.exe' : 'python');
+  const lock = join(npmRuntimeRoot, `${packageVersion}.bootstrap.lock`);
+  try {
+    ensurePrivateDirectory(npmRuntimeRoot);
+    acquireBootstrapLock(lock);
+    try {
+      if (!existsSync(environmentPython)) {
+        runBootstrap('python3', ['-m', 'venv', environmentDir], env);
+      }
+      runBootstrap(
+        environmentPython,
+        ['-c', 'import server_control_mcp; server_control_mcp.ensure_runtime()'],
+        { ...env, HOSTBRIDGE_NPM_LAUNCHER: '1' },
+      );
+    } finally {
+      rmSync(lock, { recursive: true, force: true });
+    }
+  } catch (error) {
+    console.error(`hostbridge: failed to prepare isolated Python runtime: ${error.message}`);
+    console.error(`  See: ${docsUrl}`);
+    process.exit(1);
+  }
+  pythonPath = environmentPython;
+  env.HOSTBRIDGE_NPM_LAUNCHER = '0';
+} else {
+  env.HOSTBRIDGE_NPM_LAUNCHER = env.HOSTBRIDGE_NPM_LAUNCHER || '1';
+}
 if (!env.HOSTBRIDGE_DAEMON_SOCKET && !env.HOSTBRIDGE_DAEMON_DIR) {
   const username = env.USER || env.LOGNAME || userInfo().username || 'user';
   env.HOSTBRIDGE_DAEMON_SOCKET = join(hostbridgeRuntimeDir(username), 'daemon.sock');
@@ -55,10 +131,5 @@ child.on('exit', (code, signal) => {
     process.kill(process.pid, signal);
     return;
   }
-  if (code === 2) {
-    // exit code 2 is reserved by the Python runtime guard for missing dependencies.
-    // The actionable install command was already printed to stderr by Python.
-    console.error(`\nhostbridge: runtime dependency check failed. See: ${docsUrl}`);
-  }
   process.exit(code ?? 0);
 });

package/examples/claude_desktop_config.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "hostbridge": {
       "command": "npx",
-      "args": ["-y", "hostbridge"],
+      "args": ["-y", "@neoline/hostbridge"],
       "env": {
         "HOSTBRIDGE_AGENT_ID": "claude-code"
       }

package/examples/codex.config.toml

@@ -1,6 +1,6 @@
 [mcp_servers.hostbridge]
 command = "npx"
-args = ["-y", "hostbridge"]
+args = ["-y", "@neoline/hostbridge"]
 [mcp_servers.hostbridge.env]
 HOSTBRIDGE_AGENT_ID = "codex"
 # Optional: use a project-specific host file instead of ~/.hostbridge/hosts.json

package/examples/hosts.example.json

@@ -1,4 +1,5 @@
 {
+  "schema_version": 1,
   "hosts": [
     {
       "id": "gpu",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neoline/hostbridge",
-  "version": "2.0.2",
+  "version": "2.0.4",
   "description": "HostBridge MCP server for persistent allowlisted SSH and shell sessions.",
   "type": "module",
   "license": "MIT",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "hostbridge"
-version = "2.0.2"
+version = "2.0.4"
 description = "HostBridge MCP server for persistent allowlisted SSH and shell sessions."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -36,10 +36,11 @@ classifiers = [
   "Topic :: Software Development :: Libraries",
 ]
 dependencies = [
-  "mcp>=1.0.0",
+  "packaging>=24.0",
+  "mcp>=1.28.1",
   "pexpect>=4.9.0",
-  "cryptography>=42.0.0",
-  "asyncssh>=2.14.0",
+  "cryptography>=48.0.1",
+  "asyncssh>=2.14.2",
 ]
 
 [project.optional-dependencies]

package/src/server_control_mcp/__init__.py

@@ -5,30 +5,51 @@ from __future__ import annotations
 import os
 import subprocess
 import sys
+from importlib import metadata
 from typing import NoReturn
 
 __all__ = ["__version__", "ensure_runtime"]
-__version__ = "2.0.2"
+__version__ = "2.0.4"
 
-# (import_name, pip_name) pairs for runtime dependency probing.
+# (import_name, requirement) pairs for runtime dependency probing.
 _REQUIRED_DEPENDENCIES = (
-    ("mcp", "mcp"),
-    ("pexpect", "pexpect"),
-    ("cryptography", "cryptography"),
-    ("asyncssh", "asyncssh"),
+    ("packaging", "packaging>=24.0"),
+    ("mcp", "mcp>=1.28.1"),
+    ("pexpect", "pexpect>=4.9.0"),
+    ("cryptography", "cryptography>=48.0.1"),
+    ("asyncssh", "asyncssh>=2.14.2"),
 )
 
 
-def _missing_dependencies() -> list[str]:
-    """Return pip names of runtime dependencies that cannot be imported."""
+def _unsatisfied_dependencies() -> list[str]:
+    """Return requirements which are missing or below their supported version."""
 
-    missing: list[str] = []
-    for import_name, pip_name in _REQUIRED_DEPENDENCIES:
+    try:
+        from packaging.requirements import Requirement
+        from packaging.version import InvalidVersion
+    except ImportError:
+        return ["packaging>=24.0"]
+
+    unsatisfied: list[str] = []
+    for import_name, requirement_text in _REQUIRED_DEPENDENCIES:
         try:
             __import__(import_name)
         except ImportError:
-            missing.append(pip_name)
-    return missing
+            unsatisfied.append(requirement_text)
+            continue
+        requirement = Requirement(requirement_text)
+        try:
+            installed_version = metadata.version(requirement.name)
+        except metadata.PackageNotFoundError:
+            unsatisfied.append(requirement_text)
+            continue
+        try:
+            supported = requirement.specifier.contains(installed_version, prereleases=True)
+        except InvalidVersion:
+            supported = False
+        if not supported:
+            unsatisfied.append(requirement_text)
+    return unsatisfied
 
 
 def ensure_runtime() -> None:
@@ -38,15 +59,25 @@ def ensure_runtime() -> None:
     single, copy-pasteable fix instead of a deep ImportError traceback.
     """
 
-    missing = _missing_dependencies()
-    if not missing:
+    unsatisfied = _unsatisfied_dependencies()
+    if not unsatisfied:
         return
-    if _auto_install_enabled() and _install_missing_dependencies(missing) and not _missing_dependencies():
-        return
-
-    install_command = "pip install " + " ".join(missing)
+    if _auto_install_enabled():
+        attempted_states: set[tuple[str, ...]] = set()
+        for _ in range(len(_REQUIRED_DEPENDENCIES) + 1):
+            state = tuple(unsatisfied)
+            if state in attempted_states:
+                break
+            attempted_states.add(state)
+            if not _install_dependencies(unsatisfied):
+                break
+            unsatisfied = _unsatisfied_dependencies()
+            if not unsatisfied:
+                return
+
+    install_command = "pip install " + " ".join(unsatisfied)
     message = (
-        f"hostbridge: missing Python dependencies: {', '.join(missing)}\n"
+        f"hostbridge: missing or unsupported Python dependencies: {', '.join(unsatisfied)}\n"
         f"  Install them with:  {install_command}\n"
         "  Or reinstall the package:  pip install --force-reinstall hostbridge"
     )
@@ -60,14 +91,18 @@ def _abort_with_error(message: str) -> NoReturn:
 
 
 def _auto_install_enabled() -> bool:
-    return (os.environ.get("HOSTBRIDGE_AUTO_INSTALL_DEPS") or os.environ.get("HOSTBRIDGE_NPM_LAUNCHER") or "").lower() in {
+    return (
+        os.environ.get("HOSTBRIDGE_AUTO_INSTALL_DEPS") or os.environ.get("HOSTBRIDGE_NPM_LAUNCHER") or ""
+    ).lower() in {
         "1",
         "true",
         "yes",
     }
 
 
-def _install_missing_dependencies(missing: list[str]) -> bool:
-    print(f"hostbridge: installing missing Python dependencies: {', '.join(missing)}", file=sys.stderr)
-    result = subprocess.run([sys.executable, "-m", "pip", "install", *missing], stdout=sys.stderr, stderr=sys.stderr, check=False)
+def _install_dependencies(requirements: list[str]) -> bool:
+    print(f"hostbridge: installing Python dependencies: {', '.join(requirements)}", file=sys.stderr)
+    result = subprocess.run(
+        [sys.executable, "-m", "pip", "install", *requirements], stdout=sys.stderr, stderr=sys.stderr, check=False
+    )
     return result.returncode == 0

package/src/server_control_mcp/cli.py

@@ -153,7 +153,7 @@ def _run_hosts(args: argparse.Namespace) -> int:
     try:
         result = client.exec(session.session_id, "printf hostbridge-ok", timeout=args.timeout, owner="cli-check")
     finally:
-        client.close_session(session.session_id, owner="cli-check", force=True)
+        client.close_session(session.session_id, owner="cli-check")
     if result.exit_code != 0 or result.stdout != b"hostbridge-ok":
         raise HostBridgeError("remote_error", "host check command failed")
     print(f"{args.host_id}: ok")

package/src/server_control_mcp/client.py

@@ -9,12 +9,15 @@ import json
 import socket
 import threading
 import uuid
-from collections.abc import Mapping
+from collections.abc import Iterable, Mapping
+from contextlib import suppress
 from dataclasses import dataclass
 from pathlib import Path
 
+from . import __version__
 from .protocol import (
     MAX_FRAME_BYTES,
+    PROTOCOL_VERSION,
     BinaryFrame,
     ErrorInfo,
     FrameFlags,
@@ -144,19 +147,31 @@ class HostBridgeClient:
         return response.result
 
     def hello(self) -> dict[str, object]:
-        return self.request("system.hello", {})
+        result = self.request("system.hello", {})
+        if (
+            result.get("service") != "hostbridge"
+            or result.get("protocol") != PROTOCOL_VERSION
+            or result.get("version") != __version__
+        ):
+            raise HostBridgeError(
+                "protocol_mismatch",
+                f"HostBridge daemon is not compatible with runtime {__version__}",
+            )
+        return result
 
     def open_session(
         self,
         host_id: str,
         *,
         owner: str | None = None,
-        timeout: float | None = None,
+        connect_timeout: float = 30,
     ) -> SessionInfo:
+        if connect_timeout <= 0:
+            raise ValueError("connect_timeout must be positive")
         result = self.request(
             "session.open",
-            {"host_id": host_id, "owner": owner},
-            timeout=timeout,
+            {"host_id": host_id, "owner": owner, "connect_timeout": connect_timeout},
+            timeout=connect_timeout + 5,
         )
         return SessionInfo.from_dict(result)
 
@@ -184,8 +199,72 @@ class HostBridgeClient:
         result = self.request("exec.start", params, timeout=timeout)
         return ExecResult.from_dict(result)
 
-    def close_session(self, session_id: str, *, owner: str | None = None, force: bool = False) -> None:
-        params: dict[str, object] = {"session_id": session_id, "force": force}
+    def exec_stream(
+        self,
+        session_id: str,
+        command: str,
+        stdin: Iterable[bytes],
+        *,
+        timeout: float | None = None,
+        output_limit: int | None = None,
+        owner: str | None = None,
+        cancel_event: threading.Event | None = None,
+    ) -> ExecResult:
+        stream_id = uuid.uuid4().hex
+        params: dict[str, object] = {
+            "session_id": session_id,
+            "command": command,
+            "stream_id": stream_id,
+        }
+        if timeout is not None:
+            params["timeout"] = timeout
+        if output_limit is not None:
+            params["output_limit"] = output_limit
+        if owner is not None:
+            params["owner"] = owner
+        request = Request.new("exec.stream", params)
+        request_timeout = self.default_timeout if timeout is None else timeout
+        sequence = 0
+        try:
+            with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as connection:
+                connection.settimeout(request_timeout)
+                connection.connect(str(self.socket_path))
+                connection.sendall(request.to_json().encode("utf-8") + b"\n")
+                try:
+                    for chunk in stdin:
+                        if cancel_event is not None and cancel_event.is_set():
+                            raise HostBridgeError("cancelled", "exec stdin cancelled")
+                        if not isinstance(chunk, bytes):
+                            raise TypeError("exec stdin chunks must be bytes")
+                        for offset in range(0, len(chunk), MAX_FRAME_BYTES):
+                            payload = chunk[offset : offset + MAX_FRAME_BYTES]
+                            connection.sendall(encode_frame(BinaryFrame(stream_id, sequence, FrameFlags.DATA, payload)))
+                            sequence += 1
+                    if cancel_event is not None and cancel_event.is_set():
+                        raise HostBridgeError("cancelled", "exec stdin cancelled")
+                    connection.sendall(encode_frame(BinaryFrame(stream_id, sequence, FrameFlags.EOF)))
+                except BaseException as exc:
+                    metadata = json.dumps(
+                        {"code": "cancelled", "message": str(exc) or "exec stdin failed"},
+                        separators=(",", ":"),
+                    ).encode("utf-8")
+                    with suppress(OSError):
+                        connection.sendall(encode_frame(BinaryFrame(stream_id, sequence, FrameFlags.CANCEL, metadata)))
+                    raise
+                with connection.makefile("rb") as reader:
+                    response = self._read_response(reader, request)
+        except HostBridgeError:
+            raise
+        except TimeoutError as exc:
+            raise HostBridgeError("timeout", "HostBridge exec stream timed out", retryable=True) from exc
+        except OSError as exc:
+            raise HostBridgeError(
+                "connection_lost", "HostBridge exec stream connection failed", retryable=True
+            ) from exc
+        return ExecResult.from_dict(response.result)
+
+    def close_session(self, session_id: str, *, owner: str | None = None) -> None:
+        params: dict[str, object] = {"session_id": session_id}
         if owner is not None:
             params["owner"] = owner
         self.request("session.close", params)
@@ -274,10 +353,14 @@ class HostBridgeClient:
         timeout: float | None = None,
         cancel_event: threading.Event | None = None,
         owner: str | None = None,
+        max_bytes: int | None = None,
     ) -> TransferResult:
         self._validate_chunk_size(chunk_size)
         source = Path(local_path)
         expected_size = source.stat().st_size
+        self._validate_optional_byte_limit(max_bytes)
+        if max_bytes is not None and expected_size > max_bytes:
+            raise HostBridgeError("resource_limit", f"upload exceeds {max_bytes} bytes")
         stream_id = uuid.uuid4().hex
         params: dict[str, object] = {
             "session_id": session_id,
@@ -335,8 +418,10 @@ class HostBridgeClient:
         chunk_size: int = 256 * 1024,
         timeout: float | None = None,
         owner: str | None = None,
+        max_bytes: int | None = None,
     ) -> TransferResult:
         self._validate_chunk_size(chunk_size)
+        self._validate_optional_byte_limit(max_bytes)
         destination = Path(local_path)
         destination.parent.mkdir(parents=True, exist_ok=True)
         temporary = destination.with_name(f".{destination.name}.hostbridge-{uuid.uuid4().hex}.tmp")
@@ -375,6 +460,8 @@ class HostBridgeClient:
                                 local_file.write(frame.payload)
                                 digest.update(frame.payload)
                                 transferred += len(frame.payload)
+                                if max_bytes is not None and transferred > max_bytes:
+                                    raise HostBridgeError("resource_limit", f"download exceeds {max_bytes} bytes")
                             if frame.flags & FrameFlags.EOF:
                                 metadata = self._frame_metadata(frame.payload)
                                 break
@@ -399,6 +486,11 @@ class HostBridgeClient:
         if not isinstance(chunk_size, int) or isinstance(chunk_size, bool) or not 4096 <= chunk_size <= MAX_FRAME_BYTES:
             raise ValueError(f"chunk_size must be between 4096 and {MAX_FRAME_BYTES} bytes")
 
+    @staticmethod
+    def _validate_optional_byte_limit(max_bytes: int | None) -> None:
+        if max_bytes is not None and (not isinstance(max_bytes, int) or isinstance(max_bytes, bool) or max_bytes <= 0):
+            raise ValueError("max_bytes must be a positive integer or None")
+
     @staticmethod
     def _transfer_result(value: Mapping[str, object]) -> TransferResult:
         byte_count = value.get("bytes_transferred")

package/src/server_control_mcp/config.py

@@ -10,11 +10,21 @@ from dataclasses import dataclass
 from pathlib import Path
 
 from .secrets import SCHEME, encrypt_secret
+from .secure_files import read_private_text
 
 SCHEMA_VERSION = 1
 _HOST_ID = re.compile(r"^[A-Za-z0-9_.-]+$")
 _CONNECTION_STYLES = {"script", "ssh", "command"}
 _TRANSPORTS = {"auto", "pty", "ssh"}
+_LIMITS = {
+    "max_sessions",
+    "command_timeout_seconds",
+    "max_output_bytes",
+    "max_stdin_bytes",
+    "max_transfer_bytes",
+    "max_text_bytes",
+    "max_shell_bytes",
+}
 
 
 @dataclass(frozen=True, slots=True)
@@ -32,7 +42,7 @@ class ConfigDocument:
 def load_v1_config(path: Path | str) -> ConfigDocument:
     config_path = Path(path).expanduser()
     try:
-        payload = json.loads(config_path.read_text(encoding="utf-8"))
+        payload = json.loads(read_private_text(config_path))
     except json.JSONDecodeError as exc:
         raise ValueError(f"{config_path} is not valid JSON") from exc
     validated = validate_v1_config(payload, source=config_path)
@@ -108,8 +118,10 @@ def _validate_limits(value: object, source: Path | str, index: int) -> None:
     if not isinstance(value, dict):
         raise ValueError(f"{source}.hosts[{index}].limits must be an object")
     for name, limit in value.items():
-        if not isinstance(name, str) or not isinstance(limit, int) or isinstance(limit, bool) or limit <= 0:
-            raise ValueError(f"{source}.hosts[{index}].limits values must be positive integers")
+        if name not in _LIMITS:
+            raise ValueError(f"{source}.hosts[{index}].limits contains unknown limit {name!r}")
+        if not isinstance(limit, int) or isinstance(limit, bool) or limit <= 0:
+            raise ValueError(f"{source}.hosts[{index}].limits.{name} must be a positive integer")
 
 
 def migrate_config(source: Path | str, destination: Path | str) -> ConfigDocument:
@@ -132,8 +144,7 @@ def migrate_config(source: Path | str, destination: Path | str) -> ConfigDocumen
         secrets = host.get("secrets")
         if isinstance(secrets, dict):
             host["secrets"] = {
-                name: encrypt_secret(secret) if isinstance(secret, str) else secret
-                for name, secret in secrets.items()
+                name: encrypt_secret(secret) if isinstance(secret, str) else secret for name, secret in secrets.items()
             }
         migrated_hosts.append(host)
     payload = validate_v1_config(