@neoline/hostbridge 2.0.3 → 2.0.5

package/README.md

@@ -6,26 +6,25 @@ 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.
 - `session_read(session_id, timeout=1.0, max_chars=20000)` — read available raw output after interactive writes.
 - `file_write_text(session_id, remote_path, content)` — write a UTF-8 text file through the active shell, up to 100MiB.
 - `file_read_text(session_id, remote_path)` — read a UTF-8 text file through the active shell, up to 100MiB.
-- `file_upload(session_id, local_path, remote_path)` — upload a local file with chunked shell/base64 transfer, up to 100MiB.
-- `file_download(session_id, remote_path, local_path)` — download a remote file with chunked shell/base64 transfer, up to 100MiB.
+- `file_upload(session_id, local_path, remote_path)` — stream a local file as binary data, up to 100MiB.
+- `file_download(session_id, remote_path, local_path)` — stream a remote file as binary data, 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
+## Install and configure
 
 Install from npm or Python, then create a schema-v1 configuration and start the daemon:
 
@@ -48,14 +47,14 @@ hostbridge hosts check gpu
 
 ## File transfer model
 
-HostBridge file transfer is shell-based because recorded login paths may be JumpServer menus, OTP flows, wrapper scripts, or `docker exec` sessions rather than standard SSH/SFTP connections. The first-class transfer tools stream chunked base64 through the already-open shell session, verify hashes, and work for text or binary artifacts up to 100MiB:
+HostBridge streams file data as raw bytes over its bounded multiplexed tunnel. Direct SSH targets use SFTP on the host's shared AsyncSSH connection. JumpServer, menu, wrapper, and `docker exec` paths use the persistent PTY remote agent, which implements the same binary upload/download protocol without Base64 expansion. Both providers verify SHA-256 and size before atomically replacing the destination. Transfers are limited to 100MiB by default:
 
 ```bash
 file_upload(session_id, "/absolute/local/script.py", "/remote/work/script.py")
 file_download(session_id, "/remote/work/result.log", "/absolute/local/result.log")
 ```
 
-Give file tools local and remote paths; do not paste base64 into tool arguments. Files larger than 100MiB are deliberately rejected with guidance to use remote pull instead, for example `curl`, `wget`, `git clone`, `modelscope download`, or another remote-native downloader. The MCP file tools intentionally keep this shell/base64 backend for non-standard login flows. The optional `mock-ssh` bridge below exposes SFTP/SCP protocol compatibility on top of the same backend for clients which require SSH file-transfer channels.
+Give file tools local and remote paths. Files larger than 100MiB are deliberately rejected with guidance to use remote pull instead, for example `curl`, `wget`, `git clone`, `modelscope download`, or another remote-native downloader. The optional `mock-ssh` bridge below exposes SFTP/SCP protocol compatibility on top of the same binary transfer service for clients which require SSH file-transfer channels.
 
 ## Mock SSH bridge
 
@@ -91,7 +90,9 @@ The bridge supports:
 - OpenSSH `scp` in its default SFTP-backed mode.
 - Legacy OpenSSH `scp -O` mode through AsyncSSH's SCP server.
 
-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.
+Each SSH channel owns a HostBridge runtime lease and closes it when the channel ends, while all leases for a host reuse the daemon's single provider connection. An interactive shell `exit` therefore does not kill later exec or file-transfer requests. SFTP/SCP uses the same binary transfer service and works 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 streamed 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. Output remains bytes end to end and is bounded before returning to the client.
 
 ## Daemon lifecycle
 
@@ -103,12 +104,14 @@ hostbridge daemon status
 hostbridge daemon stop
 ```
 
-The daemon uses a Unix domain socket with a small JSON-line RPC protocol by default, not HTTP and not a TCP port:
+The daemon uses a Unix domain socket with a versioned binary multiplexing protocol, not HTTP and not a TCP port:
 
 ```text
 ~/.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. Each control connection has bounded pending requests, concurrent handlers, receive windows, and per-stream flow-control credit. Business handlers execute on the daemon event loop; there is no synchronous service worker pool.
+
 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,9 @@ 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`).
+
+See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for runtime ownership, cancellation, and provider invariants.
 
 ## Configuration lifecycle
 
@@ -259,7 +264,7 @@ Claude Desktop style config:
   "mcpServers": {
     "hostbridge": {
       "command": "npx",
-      "args": ["-y", "hostbridge"],
+      "args": ["-y", "@neoline/hostbridge"],
       "env": {"HOSTBRIDGE_AGENT_ID": "claude-code"}
     }
   }
@@ -288,6 +293,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 +305,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/docs/ARCHITECTURE.md

@@ -0,0 +1,62 @@
+# HostBridge Runtime Architecture
+
+HostBridge has one asynchronous runtime owned by the local daemon. CLI, MCP, and Mock SSH clients use the same versioned binary Mux protocol over a private Unix socket.
+
+## Ownership
+
+```text
+CLI / MCP / Mock SSH
+        |
+        v
+MuxDaemonServer
+        |
+        +-- AsyncHostBridgeServices -- RuntimeServiceSession -- HostRuntimeLease
+        |
+        +-- forwarding stream registry ------------------------+
+                                                               |
+                                                               v
+                                                     HostTunnelManager
+                                                               |
+                                                    one HostRuntime per host
+                                                       /              \
+                                             Native AsyncSSH       PTY agent
+```
+
+`HostTunnelManager` owns exactly one active provider generation per host. Session leases and forwarding stream handles share that provider. A Native SSH provider owns one AsyncSSH connection; a PTY provider owns one local login process and one persistent remote Mux agent.
+
+## Data Plane
+
+- Exec stdin, stdout, and stderr are bytes.
+- Upload, download, forwarding, and shell traffic use binary Mux streams.
+- Connection and stream credit provide bounded memory and backpressure.
+- Uploads write a private temporary file, validate expected size and SHA-256, fsync, chmod, and atomically replace the destination.
+- No host data path uses JSONL, Base64, shell line framing, or periodic polling.
+
+## Session Lifecycle
+
+```text
+OPENING -> ACTIVE -> DRAINING -> CLOSED
+```
+
+Opening reserves host session capacity before acquiring a runtime lease. Cancellation or rejection after acquisition closes the lease before releasing the reservation.
+
+Closing marks the session as draining before releasing the registry lock. Normal close rejects active operations. Force close cancels and bounds active operation shutdown, terminates registered remote jobs, deletes their job directories, closes the lease-owned shell, releases the lease, and removes all session metadata. Finalization runs in its own shielded task, so caller cancellation cannot interrupt resource cleanup.
+
+Idle expiry uses one asyncio task on the daemon event loop. Service audit events cover session, command, transfer, and remote-task lifecycle transitions.
+
+## Provider Isolation
+
+- Shell identity is the internal lease token, never a client-provided shell ID.
+- Shell creation and removal are atomic per provider, preventing duplicate processes during concurrent first access.
+- Cancelling a Native SSH exec channel does not abort the shared host connection.
+- PTY exec and shell processes run in dedicated process groups and use TERM/KILL cleanup deadlines.
+- Provider generation changes invalidate old leases and stream handles without attaching them to a replacement connection.
+
+## Shutdown Order
+
+1. Stop accepting Mux work and drain or cancel request handlers.
+2. Force-close service sessions and their operations, jobs, and shells.
+3. Close forwarding streams and host providers.
+4. Remove daemon socket and PID files.
+
+There is no synchronous service implementation or daemon worker executor. `HostBridgeClient` remains a thread-safe synchronous facade for current CLI, MCP, and Mock SSH callers, but it communicates with the same asynchronous daemon runtime and does not create per-host connections.

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.3",
+  "version": "2.0.5",
   "description": "HostBridge MCP server for persistent allowlisted SSH and shell sessions.",
   "type": "module",
   "license": "MIT",
@@ -25,6 +25,7 @@
     "src/server_control_mcp/**/*.py",
     "pyproject.toml",
     "README.md",
+    "docs/ARCHITECTURE.md",
     "LICENSE",
     "examples/"
   ],

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "hostbridge"
-version = "2.0.3"
+version = "2.0.5"
 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

@@ -3,32 +3,53 @@
 from __future__ import annotations
 
 import os
-import subprocess
+import subprocess  # nosec B404
 import sys
+from importlib import metadata
 from typing import NoReturn
 
 __all__ = ["__version__", "ensure_runtime"]
-__version__ = "2.0.3"
+__version__ = "2.0.5"
 
-# (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,19 @@ 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)
+    # The executable and pip arguments are package-owned constants.
+    result = subprocess.run(  # nosec B603
+        [sys.executable, "-m", "pip", "install", *requirements], stdout=sys.stderr, stderr=sys.stderr, check=False
+    )
     return result.returncode == 0

package/src/server_control_mcp/async_lifecycle.py

@@ -0,0 +1,41 @@
+"""Shared lifecycle helpers for paired asynchronous pumps."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import TypeVar
+
+T = TypeVar("T")
+
+
+async def finish_task_despite_cancellation(task: asyncio.Future[T]) -> T:
+    """Wait for cleanup without allowing repeated caller cancellation to detach it."""
+    while True:
+        try:
+            return await asyncio.shield(task)
+        except asyncio.CancelledError:
+            if task.done():
+                return task.result()
+
+
+async def finish_task_before_cancellation(task: asyncio.Future[T]) -> T:
+    """Finish an owned task before propagating cancellation from its waiter."""
+    try:
+        return await asyncio.shield(task)
+    except asyncio.CancelledError:
+        await finish_task_despite_cancellation(task)
+        raise
+
+
+async def stop_input_after_peer_eof(task: asyncio.Task[None]) -> None:
+    """Stop pending input after peer EOF while preserving completed failures."""
+    if task.done():
+        await task
+        return
+    task.cancel()
+    results = await asyncio.shield(asyncio.gather(task, return_exceptions=True))
+    result = results[0]
+    if isinstance(result, asyncio.CancelledError):
+        return
+    if isinstance(result, BaseException):
+        raise result

package/src/server_control_mcp/cli.py

@@ -78,7 +78,7 @@ def build_parser() -> argparse.ArgumentParser:
     check.add_argument("host_id")
     check.add_argument("--timeout", type=int, default=30)
 
-    daemon = commands.add_parser("daemon", help="manage the protocol-v1 daemon")
+    daemon = commands.add_parser("daemon", help="manage the binary Mux daemon")
     _add_config_argument(daemon)
     daemon_commands = daemon.add_subparsers(dest="daemon_command", required=True)
     start = daemon_commands.add_parser("start")
@@ -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")