@neoline/hostbridge 1.4.4 → 2.0.1

package/src/server_control_mcp/cli.py

@@ -1,1268 +1,266 @@
 from __future__ import annotations
 
 import argparse
-import copy
-import getpass
 import json
 import os
-import re
-import select
-import shlex
+import shutil
 import sys
-import termios
-import tty
-from collections.abc import Callable, Iterable
-from contextlib import suppress
-from dataclasses import dataclass
+import tempfile
+from dataclasses import asdict
 from pathlib import Path
 
-import pexpect
+from . import __version__
+from .client import HostBridgeClient, HostBridgeError
+from .config import SCHEMA_VERSION, load_v1_config, migrate_config, validate_v1_config
+from .doctor import collect_diagnostics
+from .hosts import DEFAULT_HOSTS_FILE
 
-from .hosts import DEFAULT_HOSTS_FILE, HOST_ID_PATTERN, LEGACY_HOSTS_FILE, load_hosts
-from .manager import DEFAULT_MAX_TRANSFER_BYTES
-from .secrets import decrypt_secret, encrypt_secret
+SETUP_COMMANDS = {"setup", "migrate", "doctor", "hosts", "daemon", "mock-ssh", "version"}
+EXIT_OK = 0
+EXIT_USAGE = 2
+EXIT_UNAVAILABLE = 3
+EXIT_DENIED = 4
+EXIT_REMOTE = 5
 
-DEFAULT_VERIFY_TIMEOUT = 30
-DEFAULT_CODEX_CONFIG = Path("~/.codex/config.toml").expanduser()
-PUBLIC_NAME = "hostbridge"
-LEGACY_PUBLIC_NAME = "server-control"
-LEGACY_PACKAGE_NAME = "server-control-mcp"
-HOSTBRIDGE_GUIDANCE_START = "<!-- HOSTBRIDGE_START -->"
-HOSTBRIDGE_GUIDANCE_END = "<!-- HOSTBRIDGE_END -->"
-HOSTBRIDGE_AGENT_GUIDANCE = f"""{HOSTBRIDGE_GUIDANCE_START}
-## HostBridge
 
-Use HostBridge when the user asks to connect to, inspect, or operate an allowlisted remote host/server.
+def _config_path(value: str | None) -> Path:
+    return Path(value).expanduser() if value else DEFAULT_HOSTS_FILE
 
-- First call `hosts_list` to see configured hosts; then use `session_open("<host_id>")`.
-- If the host is missing, ask only for the missing connection details and run `hostbridge setup <host_id>` instead of editing JSON by hand.
-- Do not run `hostbridge check` before every connection; only use `hostbridge check <host_id>` when `session_open` times out or fails.
-- Do not search shell history, SSH config, or old scripts unless the setup flow lacks required information or the user explicitly asks.
-- Keep long-running work in `task_start`/`task_status`; use `session_close` or `sessions_close_all` when done.
-- Use `file_write_text`/`file_read_text` for UTF-8 files and `file_upload`/`file_download` for binary artifacts up to 100MiB; these tools stream through the already-open shell and work across JumpServer/menu/sudo flows where SFTP may not exist.
-- For files larger than 100MiB, do not use HostBridge file tools; start a remote pull instead (`curl`, `wget`, `git clone`, `modelscope download`, etc.) and poll it with `task_status`.
-- Do not ask the user to provide base64 content. Give file tools local/remote paths; HostBridge handles chunking, encoding, hashing, and cleanup internally.
-{HOSTBRIDGE_GUIDANCE_END}
-"""
-SUPPORTED_INSTALL_TARGETS = (
-    "all",
-    "codex",
-    "claude-code",
-    "cursor",
-    "gemini",
-    "opencode",
-    "hermes",
-    "antigravity",
-    "kiro",
-)
-SETUP_COMMANDS = {"install", "setup", "check", "list", "remove", "reload", "secret", "step", "daemon", "mock-ssh"}
-AskFunc = Callable[[str], str]
-SecretAskFunc = Callable[[str], str]
-VerifyFunc = Callable[[dict[str, object], int], "VerificationResult"]
-SpawnFunc = Callable[[dict[str, object], int], object]
-SetupProbeFunc = Callable[[dict[str, object], int, AskFunc, SecretAskFunc], "VerificationResult"]
 
-
-@dataclass(frozen=True, slots=True)
-class VerificationResult:
-    ok: bool
-    message: str
-
-
-@dataclass(frozen=True, slots=True)
-class RecorderAction:
-    kind: str
-    text: str = ""
-
-
-class InteractiveLoginRecorder:
-    """Record prompt-timed user inputs into replayable login_steps."""
-
-    def __init__(self, entry: dict[str, object]) -> None:
-        self._entry = entry
-        self._output = ""
-        self._steps: list[dict[str, str]] = []
-        self._secrets: dict[str, object] = {}
-        self._secret_index = 1
-
-    def observe(self, text: str) -> None:
-        self._output = (self._output + text)[-20000:]
-
-    def current_prompt_is_secret(self) -> bool:
-        return _looks_secret_prompt(self._current_prompt_text())
-
-    def finish_line(self, line: str) -> RecorderAction:
-        line = line.rstrip("\r\n")
-        if line == "/abort":
-            return RecorderAction("abort")
-        if line == "/ready":
-            self._entry["ready_expect"] = _prompt_regex_from_output(self._current_prompt_text())
-            return RecorderAction("ready")
-
-        expect = _prompt_regex_from_output(self._current_prompt_text())
-        if self.current_prompt_is_secret():
-            secret_name = f"password_{self._secret_index}"
-            self._secret_index += 1
-            self._secrets[secret_name] = encrypt_secret(line)
-            self._steps.append({"expect": expect, "send_secret": secret_name})
-        else:
-            self._steps.append({"expect": expect, "send": line})
-        self._output = ""
-        return RecorderAction("send", line)
-
-    def apply_to_entry(self) -> None:
-        if self._steps:
-            self._entry["login_steps"] = self._steps
-        if self._secrets:
-            self._entry["secrets"] = self._secrets
-
-    def _current_prompt_text(self) -> str:
-        return self._output
-
-
-class RealTerminalIO:
-    def __init__(self, stdin: object = sys.stdin, stdout: object = sys.stdout, child_fd: int | None = None) -> None:
-        self._stdin = stdin
-        self._stdout = stdout
-        self._stdin_fd = stdin.fileno()  # type: ignore[attr-defined]
-        if child_fd is None:
-            raise ValueError("child_fd is required")
-        self._child_fd = child_fd
-        self._stdout_buffer = getattr(stdout, "buffer", stdout)
-        self._old_attrs = None
-
-    def start(self) -> None:
-        if hasattr(self._stdin, "isatty") and self._stdin.isatty():  # type: ignore[attr-defined]
-            self._old_attrs = termios.tcgetattr(self._stdin_fd)
-            tty.setraw(self._stdin_fd)
-
-    def read_event(self) -> tuple[str, bytes]:
-        while True:
-            readable, _, _ = select.select([self._stdin_fd, self._child_fd], [], [], 0.1)
-            if self._child_fd in readable:
-                return "child", os.read(self._child_fd, 4096)
-            if self._stdin_fd in readable:
-                return "stdin", os.read(self._stdin_fd, 4096)
-
-    def write_stdout(self, data: bytes) -> None:
-        self._stdout_buffer.write(data)
-        self._stdout_buffer.flush()
-
-    def close(self) -> None:
-        if self._old_attrs is not None:
-            termios.tcsetattr(self._stdin_fd, termios.TCSADRAIN, self._old_attrs)
-
-
-def build_host_entry(host_id: str, label: str, command_text: str) -> dict[str, object]:
-    """Convert a user-entered connection command into a hosts.json entry."""
-
-    host_id = host_id.strip()
-    label = label.strip() or host_id
-    if not HOST_ID_PATTERN.fullmatch(host_id):
-        raise ValueError("host id may contain only letters, numbers, '_', '-', and '.'")
-    parts = shlex.split(command_text.strip())
-    if not parts:
-        raise ValueError("command must not be empty")
-
-    entry: dict[str, object] = {"id": host_id, "label": label}
-    command = parts[0]
-    args = parts[1:]
-    if command == "ssh":
-        entry["ssh"] = _parse_ssh_command(args)
-    elif _looks_like_shell_script(command, args):
-        entry["script"] = args[0]
-    else:
-        entry["command"] = command
-        entry["args"] = args
-    return entry
-
-
-def _parse_ssh_command(args: list[str]) -> dict[str, object]:
-    ssh: dict[str, object] = {}
-    extra_args: list[str] = []
-    targets: list[str] = []
-    index = 0
-    while index < len(args):
-        arg = args[index]
-        if arg in ("-J", "-p", "-i", "-o"):
-            if index + 1 >= len(args):
-                raise ValueError(f"ssh option {arg} requires a value")
-            value = args[index + 1]
-            if arg == "-J":
-                ssh["proxy_jump"] = value
-            elif arg == "-p":
-                ssh["port"] = int(value)
-            elif arg == "-i":
-                ssh["identity_file"] = value
-            else:
-                extra_args.extend([arg, value])
-            index += 2
-            continue
-        if arg.startswith("-J") and len(arg) > 2:
-            ssh["proxy_jump"] = arg[2:]
-        elif arg.startswith("-p") and len(arg) > 2:
-            ssh["port"] = int(arg[2:])
-        elif arg.startswith("-i") and len(arg) > 2:
-            ssh["identity_file"] = arg[2:]
-        elif arg.startswith("-"):
-            extra_args.append(arg)
-        else:
-            targets.append(arg)
-        index += 1
-
-    if not targets:
-        raise ValueError("ssh command must include a target host")
-    ssh["host"] = targets[-1]
-    if extra_args:
-        ssh["extra_args"] = extra_args
-    return _ordered_ssh_config(ssh)
-
-
-def _ordered_ssh_config(ssh: dict[str, object]) -> dict[str, object]:
-    ordered: dict[str, object] = {"host": ssh["host"]}
-    for key in ("proxy_jump", "port", "identity_file", "extra_args"):
-        if key in ssh:
-            ordered[key] = ssh[key]
-    return ordered
-
-
-def _looks_like_shell_script(command: str, args: list[str]) -> bool:
-    shell_names = {"sh", "bash", "zsh", "/bin/sh", "/bin/bash", "/bin/zsh"}
-    return command in shell_names and len(args) == 1 and args[0].endswith((".sh", ".bash", ".zsh"))
-
-
-def _default_mcp_command_args() -> tuple[str, list[str]]:
-    env_command = os.environ.get("HOSTBRIDGE_DEFAULT_MCP_COMMAND")
-    if env_command:
-        raw_args = os.environ.get("HOSTBRIDGE_DEFAULT_MCP_ARGS", "[]")
-        try:
-            parsed_args = json.loads(raw_args)
-        except json.JSONDecodeError:
-            parsed_args = []
-        if not isinstance(parsed_args, list) or not all(isinstance(arg, str) for arg in parsed_args):
-            parsed_args = []
-        return env_command, parsed_args
-
-    repo_root = Path(__file__).resolve().parents[2]
-    run_server = repo_root / "run_server.py"
-    if run_server.exists():
-        return "python3", [str(run_server)]
-    command = Path(sys.argv[0]).name or PUBLIC_NAME
-    if command in (LEGACY_PUBLIC_NAME, LEGACY_PACKAGE_NAME, "__main__.py"):
-        command = PUBLIC_NAME
-    return command, []
-
-
-def _resolve_hosts_config_path(config_path: Path | str | None) -> Path:
-    if config_path is None:
-        configured = os.environ.get("HOSTBRIDGE_HOSTS_FILE") or os.environ.get("SERVER_CONTROL_MCP_HOSTS_FILE")
-        if configured:
-            return Path(configured).expanduser()
-        if DEFAULT_HOSTS_FILE.exists() or not LEGACY_HOSTS_FILE.exists():
-            return DEFAULT_HOSTS_FILE
-        return LEGACY_HOSTS_FILE
-    return Path(config_path).expanduser()
-
-
-def _toml_quote(value: str) -> str:
-    return json.dumps(value, ensure_ascii=False)
-
-
-def _toml_array(values: list[str]) -> str:
-    return "[" + ", ".join(_toml_quote(value) for value in values) + "]"
-
-
-def _server_control_block(command: str, args: list[str], *, agent_id: str) -> str:
-    return "\n".join([
-        f"[mcp_servers.{PUBLIC_NAME}]",
-        f"command = {_toml_quote(command)}",
-        f"args = {_toml_array(args)}",
-        f"[mcp_servers.{PUBLIC_NAME}.env]",
-        f"HOSTBRIDGE_AGENT_ID = {_toml_quote(agent_id)}",
-        "",
-    ])
-
-
-def _replace_toml_table(text: str, table_header: str, block: str) -> str:
-    lines = text.splitlines()
-    start = None
-    for index, line in enumerate(lines):
-        if line.strip() == table_header:
-            start = index
-            break
-    if start is None:
-        prefix = text.rstrip()
-        return f"{prefix}\n\n{block}" if prefix else block
-
-    end = len(lines)
-    for index in range(start + 1, len(lines)):
-        stripped = lines[index].strip()
-        if stripped.startswith("[") and stripped.endswith("]"):
-            end = index
-            break
-    new_lines = lines[:start] + block.rstrip().splitlines() + lines[end:]
-    return "\n".join(new_lines).rstrip() + "\n"
-
-
-def _remove_toml_table(text: str, table_header: str) -> str:
-    lines = text.splitlines()
-    start = None
-    for index, line in enumerate(lines):
-        if line.strip() == table_header:
-            start = index
-            break
-    if start is None:
-        return text
-    end = len(lines)
-    for index in range(start + 1, len(lines)):
-        stripped = lines[index].strip()
-        if stripped.startswith("[") and stripped.endswith("]"):
-            end = index
-            break
-    return "\n".join(lines[:start] + lines[end:]).rstrip() + ("\n" if lines[:start] + lines[end:] else "")
-
-
-def _read_json_object(path: Path) -> dict[str, object]:
-    if not path.exists():
-        return {}
-    data = json.loads(path.read_text(encoding="utf-8"))
-    if not isinstance(data, dict):
-        raise ValueError(f"{path} must contain a JSON object")
-    return data
-
-
-def _write_json_object(path: Path, data: dict[str, object]) -> None:
+def _write_config(path: Path, payload: dict[str, object]) -> None:
+    validated = validate_v1_config(payload, source=path)
     path.parent.mkdir(parents=True, exist_ok=True)
-    path.write_text(json.dumps(data, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
-
-
-def _replace_managed_block(text: str, start: str, end: str, block: str) -> str:
-    start_index = text.find(start)
-    end_index = text.find(end)
-    if start_index != -1 and end_index != -1 and end_index > start_index:
-        end_index += len(end)
-        return (text[:start_index].rstrip() + "\n\n" + block.strip() + "\n" + text[end_index:].lstrip()).rstrip() + "\n"
-    prefix = text.rstrip()
-    return (prefix + "\n\n" + block.strip() + "\n") if prefix else (block.strip() + "\n")
-
-
-def _install_guidance_file(path: Path) -> None:
-    existing = path.read_text(encoding="utf-8") if path.exists() else ""
-    updated = _replace_managed_block(existing, HOSTBRIDGE_GUIDANCE_START, HOSTBRIDGE_GUIDANCE_END, HOSTBRIDGE_AGENT_GUIDANCE)
-    path.parent.mkdir(parents=True, exist_ok=True)
-    path.write_text(updated, encoding="utf-8")
-
-
-def _remove_legacy_mcp_server_keys(value: object) -> None:
-    if isinstance(value, dict):
-        servers = value.get("mcpServers")
-        if isinstance(servers, dict):
-            servers.pop(LEGACY_PUBLIC_NAME, None)
-            servers.pop(LEGACY_PACKAGE_NAME, None)
-        for child in value.values():
-            _remove_legacy_mcp_server_keys(child)
-    elif isinstance(value, list):
-        for child in value:
-            _remove_legacy_mcp_server_keys(child)
-
-
-def _install_codex_config(config_path: Path, command: str, args: list[str], *, agent_id: str) -> None:
-    block = _server_control_block(command, args, agent_id=agent_id)
-    existing = config_path.read_text(encoding="utf-8") if config_path.exists() else ""
-    updated = _remove_toml_table(existing, f"[mcp_servers.{LEGACY_PUBLIC_NAME}]")
-    updated = _remove_toml_table(updated, f"[mcp_servers.{LEGACY_PACKAGE_NAME}]")
-    updated = _remove_toml_table(updated, f"[mcp_servers.{PUBLIC_NAME}.env]")
-    updated = _replace_toml_table(updated, f"[mcp_servers.{PUBLIC_NAME}]", block)
-    config_path.parent.mkdir(parents=True, exist_ok=True)
-    config_path.write_text(updated, encoding="utf-8")
-
-
-def _install_mcp_servers_json(config_path: Path, command: str, args: list[str], *, agent_id: str) -> None:
-    data = _read_json_object(config_path)
-    _remove_legacy_mcp_server_keys(data)
-    servers = data.setdefault("mcpServers", {})
-    if not isinstance(servers, dict):
-        raise ValueError(f"{config_path} mcpServers must be an object")
-    servers[PUBLIC_NAME] = {"command": command, "args": args, "env": {"HOSTBRIDGE_AGENT_ID": agent_id}}
-    _write_json_object(config_path, data)
-
-
-def _install_opencode_config(config_path: Path, command: str, args: list[str], *, agent_id: str) -> None:
-    data = _read_json_object(config_path)
-    servers = data.setdefault("mcp", {})
-    if not isinstance(servers, dict):
-        raise ValueError(f"{config_path} mcp must be an object")
-    servers.pop(LEGACY_PUBLIC_NAME, None)
-    servers.pop(LEGACY_PACKAGE_NAME, None)
-    servers[PUBLIC_NAME] = {
-        "type": "local",
-        "command": [command, *args],
-        "enabled": True,
-        "env": {"HOSTBRIDGE_AGENT_ID": agent_id},
-    }
-    _write_json_object(config_path, data)
-
-
-@dataclass(frozen=True, slots=True)
-class AgentInstallSpec:
-    target: str
-    label: str
-    path: Path
-    kind: str
-    detect_path: Path
-    guidance_path: Path | None = None
-
-
-def _agent_install_specs(home: Path) -> list[AgentInstallSpec]:
-    return [
-        AgentInstallSpec("codex", "Codex CLI", home / ".codex" / "config.toml", "codex_toml", home / ".codex", home / ".codex" / "AGENTS.md"),
-        AgentInstallSpec("claude-code", "Claude Code", home / ".claude.json", "mcp_json", home / ".claude", home / ".claude" / "CLAUDE.md"),
-        AgentInstallSpec("cursor", "Cursor", home / ".cursor" / "mcp.json", "mcp_json", home / ".cursor", home / ".cursor" / "rules" / "hostbridge.mdc"),
-        AgentInstallSpec("gemini", "Gemini CLI", home / ".gemini" / "settings.json", "mcp_json", home / ".gemini", home / ".gemini" / "GEMINI.md"),
-        AgentInstallSpec("opencode", "opencode", home / ".config" / "opencode" / "opencode.json", "opencode_json", home / ".config" / "opencode", home / ".config" / "opencode" / "AGENTS.md"),
-        AgentInstallSpec("hermes", "Hermes Agent", home / ".hermes" / "mcp.json", "mcp_json", home / ".hermes", home / ".hermes" / "AGENTS.md"),
-        AgentInstallSpec("antigravity", "Antigravity IDE", home / ".antigravity" / "mcp.json", "mcp_json", home / ".antigravity", home / ".antigravity" / "AGENTS.md"),
-        AgentInstallSpec("kiro", "Kiro", home / ".kiro" / "settings" / "mcp.json", "mcp_json", home / ".kiro", home / ".kiro" / "steering" / "hostbridge.md"),
-    ]
-
-
-def _install_spec(spec: AgentInstallSpec, command: str, args: list[str]) -> None:
-    if spec.kind == "codex_toml":
-        _install_codex_config(spec.path, command, args, agent_id=spec.target)
-    elif spec.kind == "opencode_json":
-        _install_opencode_config(spec.path, command, args, agent_id=spec.target)
-    else:
-        _install_mcp_servers_json(spec.path, command, args, agent_id=spec.target)
-    if spec.guidance_path is not None:
-        _install_guidance_file(spec.guidance_path)
-
-
-def run_install(
-    *,
-    target: str = "all",
-    config_path: Path | str | None = None,
-    command: str | None = None,
-    args: list[str] | None = None,
-    home_path: Path | str | None = None,
-) -> int:
-    if target not in SUPPORTED_INSTALL_TARGETS:
-        print(f"Install target '{target}' is not supported; supported targets: {', '.join(SUPPORTED_INSTALL_TARGETS)}")
-        return 1
-    resolved_command, resolved_args = (command, args or []) if command else _default_mcp_command_args()
-
-    if target == "all":
-        home = Path(home_path or Path.home()).expanduser()
-        specs = [spec for spec in _agent_install_specs(home) if spec.detect_path.exists() or spec.path.exists()]
-        if not specs:
-            print(f"No supported agent configs detected under {home}")
-            return 1
-        for spec in specs:
-            _install_spec(spec, resolved_command, resolved_args)
-            print(f"Registered {PUBLIC_NAME} MCP for {spec.label} in {spec.path}")
-        print(f"Installed {PUBLIC_NAME} MCP into {len(specs)} agent config(s)")
-        print(f"Command: {resolved_command} {' '.join(resolved_args)}".rstrip())
-        print("Restart open agent clients or start new sessions if this MCP was not already loaded.")
-        return 0
-
-    if target == "codex":
-        resolved_config = Path(config_path or DEFAULT_CODEX_CONFIG).expanduser()
-        _install_codex_config(resolved_config, resolved_command, resolved_args, agent_id="codex")
-        label = "Codex"
-    else:
-        home = Path(home_path or Path.home()).expanduser()
-        spec_by_target = {spec.target: spec for spec in _agent_install_specs(home)}
-        spec = spec_by_target[target]
-        resolved_config = Path(config_path).expanduser() if config_path else spec.path
-        spec = AgentInstallSpec(spec.target, spec.label, resolved_config, spec.kind, spec.detect_path, spec.guidance_path)
-        _install_spec(spec, resolved_command, resolved_args)
-        label = spec.label
-
-    print(f"Registered {PUBLIC_NAME} MCP for {label} in {resolved_config}")
-    print(f"Command: {resolved_command} {' '.join(resolved_args)}".rstrip())
-    print("Restart the agent client or start a new session if this MCP was not already loaded.")
-    return 0
-
-
-def upsert_host_entry(config_path: Path | str, entry: dict[str, object], *, replace: bool) -> str:
-    path = _resolve_hosts_config_path(config_path)
-    config = _read_config(path)
-    hosts = config.setdefault("hosts", [])
-    if not isinstance(hosts, list):
-        raise ValueError(f"{path} must contain a top-level 'hosts' list")
-
-    host_id = str(entry["id"])
-    for index, existing in enumerate(hosts):
-        if isinstance(existing, dict) and existing.get("id") == host_id:
-            if not replace:
-                raise ValueError(f"host '{host_id}' already exists")
-            hosts[index] = entry
-            _write_config(path, config)
-            return "replaced"
-
-    hosts.append(entry)
-    _write_config(path, config)
-    return "added"
-
-
-def remove_host_entry(config_path: Path | str, host_id: str) -> bool:
-    path = _resolve_hosts_config_path(config_path)
-    config = _read_config(path)
-    hosts = config.setdefault("hosts", [])
-    if not isinstance(hosts, list):
-        raise ValueError(f"{path} must contain a top-level 'hosts' list")
-    new_hosts = [host for host in hosts if not (isinstance(host, dict) and host.get("id") == host_id)]
-    if len(new_hosts) == len(hosts):
-        return False
-    config["hosts"] = new_hosts
-    _write_config(path, config)
-    return True
-
-
-
-
-def _yes(answer: str) -> bool:
-    return answer.strip().lower() in ("y", "yes")
-
-
-def configure_login_automation(
-    entry: dict[str, object],
-    *,
-    ask: AskFunc = input,
-    secret_ask: SecretAskFunc = getpass.getpass,
-) -> None:
-    """Add optional encrypted pre-login automation to a host entry."""
-
-    print("\nRuntime login automation")
-    print("Use this when the MCP process must answer SSH or jump-host prompts before a shell is ready.")
-    if not _yes(ask("Add encrypted login automation? [y/N]: ")):
-        return
-
-    secrets: dict[str, object] = {}
-    steps: list[dict[str, str]] = []
-
-    if _yes(ask("Store an encrypted password/passphrase for a prompt? [y/N]: ")):
-        value = secret_ask("Password/passphrase to encrypt locally: ")
-        secrets["password"] = encrypt_secret(value)
-        password_prompt_raw = ask("Password prompt regex [(?i)password:]: ")
-        password_prompt = password_prompt_raw if password_prompt_raw.strip() else "(?i)password:"
-        steps.append({"expect": password_prompt, "send_secret": "password"})
-
-    if _yes(ask("Add a jump-host/menu selection step? [y/N]: ")):
-        menu_prompt_raw = ask("Menu prompt regex [Opt>]: ")
-        menu_prompt = menu_prompt_raw if menu_prompt_raw.strip() else "Opt>"
-        selector = ask("Menu selection to send (host/IP/name): ").strip()
-        if not selector:
-            raise ValueError("menu selection must not be empty")
-        steps.append({"expect": menu_prompt, "send": selector})
-
-    final_prompt_raw = ask("Remote shell prompt regex before readiness probe [skip]: ")
-    final_prompt = final_prompt_raw if final_prompt_raw.strip() else ""
-    if final_prompt:
-        steps.append({"expect": final_prompt, "send": ""})
-
-    if not steps:
-        raise ValueError("login automation enabled but no steps were configured")
-    if secrets:
-        entry["secrets"] = secrets
-    entry["login_steps"] = steps
-
-def set_host_secret(config_path: Path | str, host_id: str, name: str, value: str) -> None:
-    if not name.strip():
-        raise ValueError("secret name must not be empty")
-    path = _resolve_hosts_config_path(config_path)
-    config = _read_config(path)
-    host = _require_raw_host_entry(config, path, host_id)
-    secrets = host.setdefault("secrets", {})
-    if not isinstance(secrets, dict):
-        raise ValueError(f"{path} host '{host_id}' secrets must be an object")
-    secrets[name] = encrypt_secret(value)
-    _write_config(path, config)
-
-
-def add_login_step(
-    config_path: Path | str,
-    host_id: str,
-    *,
-    expect: str,
-    send: str | None = None,
-    send_secret: str | None = None,
-) -> None:
-    expect = expect.strip()
-    if not expect:
-        raise ValueError("expect pattern must not be empty")
-    if (send is None) == (send_secret is None):
-        raise ValueError("login step must define exactly one of send or send_secret")
-    path = _resolve_hosts_config_path(config_path)
-    config = _read_config(path)
-    host = _require_raw_host_entry(config, path, host_id)
-    steps = host.setdefault("login_steps", [])
-    if not isinstance(steps, list):
-        raise ValueError(f"{path} host '{host_id}' login_steps must be a list")
-    step: dict[str, str] = {"expect": expect}
-    if send is not None:
-        step["send"] = send
-    else:
-        step["send_secret"] = str(send_secret)
-    steps.append(step)
-    _write_config(path, config)
-
-
-def _require_raw_host_entry(config: dict[str, object], path: Path, host_id: str) -> dict[str, object]:
-    hosts = config.get("hosts", [])
-    if not isinstance(hosts, list):
-        raise ValueError(f"{path} must contain a top-level 'hosts' list")
-    for host in hosts:
-        if isinstance(host, dict) and host.get("id") == host_id:
-            return host
-    raise ValueError(f"host '{host_id}' not found in {path}")
-
-
-def clone_jump_host_entry(
-    config_path: Path | str,
-    *,
-    source_host_id: str,
-    host_id: str,
-    label: str | None = None,
-    menu_selection: str,
-    menu_prompt: str = "Opt>",
-    final_prompt: str | None = None,
-) -> dict[str, object]:
-    """Create a new jump-host entry by reusing a known bastion path and secrets."""
-
-    if not menu_selection.strip():
-        raise ValueError("menu selection must not be empty")
-    path = _resolve_hosts_config_path(config_path)
-    source = _find_raw_host_entry(path, source_host_id)
-    if source is None:
-        raise ValueError(f"source host '{source_host_id}' not found in {path}")
-
-    entry: dict[str, object] = {
-        "id": host_id.strip(),
-        "label": (label or host_id).strip() or host_id.strip(),
-    }
-    if not HOST_ID_PATTERN.fullmatch(entry["id"]):
-        raise ValueError("host id may contain only letters, numbers, '_', '-', and '.'")
-
-    styles = [name for name in ("script", "ssh", "command") if name in source]
-    if len(styles) != 1:
-        raise ValueError(f"source host '{source_host_id}' must define exactly one connection style")
-    style = styles[0]
-    entry[style] = copy.deepcopy(source[style])
-    if style == "command" and "args" in source:
-        entry["args"] = copy.deepcopy(source["args"])
-    if isinstance(source.get("secrets"), dict):
-        entry["secrets"] = copy.deepcopy(source["secrets"])
-
-    steps: list[dict[str, str]] = []
-    raw_steps = source.get("login_steps", [])
-    if isinstance(raw_steps, list):
-        for raw_step in raw_steps:
-            if isinstance(raw_step, dict) and "send_secret" in raw_step:
-                steps.append(copy.deepcopy(raw_step))
-    steps.append({"expect": menu_prompt.strip() or "Opt>", "send": menu_selection.strip()})
-    if final_prompt and final_prompt.strip():
-        steps.append({"expect": final_prompt, "send": ""})
-    entry["login_steps"] = steps
-    return entry
-
-
-def _spawn_entry(entry: dict[str, object], timeout: int) -> object:
-    command, args = _entry_to_command(entry)
-    return pexpect.spawn(command, args, encoding="utf-8", codec_errors="replace", timeout=timeout, echo=False)
-
-
-def _prompt_regex_from_output(output: str) -> str:
-    lines = [line.strip() for line in output.replace("\r", "\n").split("\n") if line.strip()]
-    prompt = lines[-1] if lines else output.strip()
-    if not prompt:
-        prompt = ".+"
-    if _looks_shell_prompt(prompt) and _contains_terminal_control(prompt):
-        return r"(?m)[^\r\n]*[#$]\s*$"
-    return re.escape(prompt) + r"\s*$"
-
-
-def _looks_secret_prompt(output: str) -> bool:
-    return re.search(r"(?i)(password|passphrase|token|otp|verification code|验证码|密码)", output) is not None
-
-
-def _contains_terminal_control(text: str) -> bool:
-    return "\x1b" in text or "\x07" in text or "\\x1b" in text or "\\u001b" in text
-
-
-def _looks_shell_prompt(text: str) -> bool:
-    return re.search(r"[#$](?:\\s\*)?$", text.strip()) is not None
-
-
-def _runtime_expect_pattern(pattern: str) -> str:
-    if _contains_terminal_control(pattern) and _looks_shell_prompt(pattern):
-        return r"(?m)[^\r\n]*[#$]\s*$"
-    return pattern
-
-
-def _read_setup_output(child: object, timeout: int) -> str:
-    try:
-        return str(child.read_nonblocking(4096, timeout=timeout))  # type: ignore[attr-defined]
-    except pexpect.TIMEOUT:
-        pass
-
-    try:
-        child.expect(r"(?s).+", timeout=timeout)  # type: ignore[attr-defined]
-    except pexpect.TIMEOUT:
-        return str(getattr(child, "before", "") or "")
-    after = getattr(child, "after", "")
-    before = getattr(child, "before", "")
-    chunks = [str(after or before or "")]
-    while True:
-        try:
-            chunk = str(child.read_nonblocking(4096, timeout=0.2))  # type: ignore[attr-defined]
-            if chunk:
-                chunks.append(chunk)
-        except pexpect.TIMEOUT:
-            break
-    return "".join(chunks)
-
-
-def terminal_setup_probe(
-    entry: dict[str, object],
-    timeout: int = DEFAULT_VERIFY_TIMEOUT,
-    *,
-    spawn: SpawnFunc = _spawn_entry,
-    stdin: object = sys.stdin,
-    stdout: object = sys.stdout,
-    terminal_io: object | None = None,
-) -> VerificationResult:
-    """Proxy a real terminal login while recording replayable login steps."""
-
-    marker = "__HOSTBRIDGE_READY_SETUP__"
-    child = spawn(entry, timeout)
-    recorder = InteractiveLoginRecorder(entry)
-    child_fd = child.child_fd  # type: ignore[attr-defined]
-    input_buffer = bytearray()
-    secret_input = False
-    io = terminal_io or RealTerminalIO(stdin, stdout, child_fd)
-
-    print("\nRecording interactive login. Type /ready when the final shell is ready.", file=stdout)
-    print("Type /abort to cancel. Your input is forwarded to the setup session.\n", file=stdout)
+    fd, name = tempfile.mkstemp(prefix=f".{path.name}.", dir=path.parent)
+    temporary = Path(name)
     try:
-        if hasattr(io, "start"):
-            io.start()  # type: ignore[attr-defined]
-        while True:
-            source, data = io.read_event()  # type: ignore[attr-defined]
-            if source == "child":
-                if not data:
-                    return VerificationResult(False, "connection closed during setup")
-                io.write_stdout(data)  # type: ignore[attr-defined]
-                recorder.observe(data.decode("utf-8", errors="replace"))
-
-            if source == "stdin":
-                for byte in data:
-                    if not input_buffer:
-                        secret_input = recorder.current_prompt_is_secret()
-                    if byte == 3:
-                        return VerificationResult(False, "setup aborted")
-                    if byte in (8, 127):
-                        if input_buffer:
-                            input_buffer.pop()
-                            if not secret_input:
-                                io.write_stdout(b"\b \b")  # type: ignore[attr-defined]
-                        continue
-                    if byte in (10, 13):
-                        line = input_buffer.decode("utf-8", errors="replace")
-                        input_buffer.clear()
-                        if not secret_input:
-                            io.write_stdout(b"\n")  # type: ignore[attr-defined]
-                        action = recorder.finish_line(line)
-                        if action.kind == "abort":
-                            return VerificationResult(False, "setup aborted")
-                        if action.kind == "ready":
-                            child.send(f"printf '\\n{marker}\\n'\r")  # type: ignore[attr-defined]
-                            child.expect(marker, timeout=timeout)  # type: ignore[attr-defined]
-                            recorder.apply_to_entry()
-                            return VerificationResult(True, "remote shell accepted a readiness probe")
-                        child.send(f"{action.text}\r")  # type: ignore[attr-defined]
-                        continue
-                    input_buffer.append(byte)
-                    if not secret_input:
-                        io.write_stdout(bytes([byte]))  # type: ignore[attr-defined]
-    except Exception as exc:
-        return VerificationResult(False, str(exc))
-    finally:
-        if hasattr(io, "close"):
-            io.close()  # type: ignore[attr-defined]
-        child.close(force=True)  # type: ignore[attr-defined]
-
-
-def live_setup_probe(
-    entry: dict[str, object],
-    timeout: int = DEFAULT_VERIFY_TIMEOUT,
-    *,
-    ask: AskFunc = input,
-    secret_ask: SecretAskFunc = getpass.getpass,
-    spawn: SpawnFunc = _spawn_entry,
-) -> VerificationResult:
-    """Drive the real connection once and record replayable login steps from observed prompts."""
-
-    marker = "__HOSTBRIDGE_READY_SETUP__"
-    child = spawn(entry, timeout)
-    steps: list[dict[str, str]] = []
-    secrets: dict[str, object] = {}
-    secret_index = 1
-
-    print("\nStarting a hidden setup session.")
-    print("Respond to the prompts shown below exactly as you normally would.")
-    print("Type /ready when the remote shell prompt is ready, or /abort to cancel.\n")
-
+        os.fchmod(fd, 0o600)
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            json.dump(validated, handle, ensure_ascii=False, indent=2)
+            handle.write("\n")
+            handle.flush()
+            os.fsync(handle.fileno())
+        temporary.replace(path)
+        path.chmod(0o600)
+    except Exception:
+        temporary.unlink(missing_ok=True)
+        raise
+
+
+def _add_config_argument(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--config", help=f"schema-v1 config path (default: {DEFAULT_HOSTS_FILE})")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="hostbridge")
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    setup = commands.add_parser("setup", help="create an empty schema-v1 configuration")
+    _add_config_argument(setup)
+    setup.add_argument("--force", action="store_true")
+
+    migrate = commands.add_parser("migrate", help="migrate a legacy hosts file to schema v1")
+    migrate.add_argument("source")
+    migrate.add_argument("destination")
+
+    doctor = commands.add_parser("doctor", help="run deterministic installation diagnostics")
+    _add_config_argument(doctor)
+    doctor.add_argument("--json", action="store_true", dest="as_json")
+
+    hosts = commands.add_parser("hosts", help="manage allowlisted hosts")
+    _add_config_argument(hosts)
+    host_commands = hosts.add_subparsers(dest="hosts_command", required=True)
+    host_commands.add_parser("list")
+    add = host_commands.add_parser("add")
+    add.add_argument("host_json", help="one schema-v1 host object as JSON")
+    remove = host_commands.add_parser("remove")
+    remove.add_argument("host_id")
+    check = host_commands.add_parser("check")
+    check.add_argument("host_id")
+    check.add_argument("--timeout", type=int, default=30)
+
+    daemon = commands.add_parser("daemon", help="manage the protocol-v1 daemon")
+    _add_config_argument(daemon)
+    daemon_commands = daemon.add_subparsers(dest="daemon_command", required=True)
+    start = daemon_commands.add_parser("start")
+    start.add_argument("--foreground", action="store_true")
+    start.add_argument("--socket")
+    stop = daemon_commands.add_parser("stop")
+    stop.add_argument("--socket")
+    status = daemon_commands.add_parser("status")
+    status.add_argument("--socket")
+    logs = daemon_commands.add_parser("logs")
+    logs.add_argument("--lines", type=int, default=100)
+
+    mock = commands.add_parser("mock-ssh", help="expose a host through local SSH/SFTP/SCP")
+    mock_commands = mock.add_subparsers(dest="mock_command", required=True)
+    mock_start = mock_commands.add_parser("start")
+    mock_start.add_argument("host_id")
+    mock_start.add_argument("--listen-host", default="127.0.0.1")
+    mock_start.add_argument("--port", type=int)
+    mock_start.add_argument("--key-dir")
+    mock_start.add_argument("--ssh-host-alias")
+    mock_start.add_argument("--ssh-config")
+    mock_start.add_argument("--no-ssh-config", action="store_true")
+    mock_start.add_argument("--connect-timeout", type=int, default=60)
+    mock_start.add_argument("--command-timeout", type=int, default=60)
+    mock_start.add_argument("--output-limit", type=int, default=1024 * 1024 * 1024)
+    mock_stop = mock_commands.add_parser("stop")
+    mock_stop.add_argument("host_id")
+    mock_status = mock_commands.add_parser("status")
+    mock_status.add_argument("host_id")
+    mock_remove = mock_commands.add_parser("remove")
+    mock_remove.add_argument("host_id")
+    mock_remove.add_argument("--ssh-host-alias")
+    mock_remove.add_argument("--ssh-config")
+
+    commands.add_parser("version", help="print the HostBridge version")
+    return parser
+
+
+def _run_setup(args: argparse.Namespace) -> int:
+    path = _config_path(args.config)
+    if path.exists() and not args.force:
+        raise FileExistsError(f"{path} already exists; use --force to replace it")
+    _write_config(path, {"schema_version": SCHEMA_VERSION, "hosts": []})
+    print(path)
+    return EXIT_OK
+
+
+def _run_hosts(args: argparse.Namespace) -> int:
+    path = _config_path(args.config)
+    document = load_v1_config(path)
+    if args.hosts_command == "list":
+        print(json.dumps(document.hosts, ensure_ascii=False, indent=2))
+        return EXIT_OK
+    if args.hosts_command == "add":
+        host = json.loads(args.host_json)
+        payload = dict(document.data)
+        payload["hosts"] = [item for item in document.hosts if item.get("id") != host.get("id")] + [host]
+        _write_config(path, payload)
+        print(f"added {host.get('id')}")
+        return EXIT_OK
+    if args.hosts_command == "remove":
+        hosts = [item for item in document.hosts if item.get("id") != args.host_id]
+        if len(hosts) == len(document.hosts):
+            raise ValueError(f"unknown host {args.host_id!r}")
+        payload = dict(document.data)
+        payload["hosts"] = hosts
+        _write_config(path, payload)
+        print(f"removed {args.host_id}")
+        return EXIT_OK
+    client = HostBridgeClient(default_timeout=max(1, args.timeout))
+    session = client.open_session(args.host_id, owner="cli-check")
     try:
-        while True:
-            observed = _read_setup_output(child, timeout)
-            if observed:
-                print(observed, end="" if observed.endswith("\n") else "\n")
-            if not observed.strip():
-                return VerificationResult(
-                    False,
-                    "no output observed from the connection before setup input; "
-                    "check the command or retry with a larger --timeout",
-                )
-
-            expect = _prompt_regex_from_output(observed)
-            if _looks_secret_prompt(observed):
-                secret_name = f"password_{secret_index}"
-                secret_index += 1
-                secret_value = secret_ask("Secret response: ")
-                secrets[secret_name] = encrypt_secret(secret_value)
-                steps.append({"expect": expect, "send_secret": secret_name})
-                child.sendline(secret_value)  # type: ignore[attr-defined]
-            else:
-                response = ask("Send input (/ready when shell is ready): ").strip()
-                if response == "/abort":
-                    return VerificationResult(False, "setup aborted")
-                if response == "/ready":
-                    child.sendline(f"printf '\\n{marker}\\n'")  # type: ignore[attr-defined]
-                    child.expect(marker, timeout=timeout)  # type: ignore[attr-defined]
-                    if steps:
-                        entry["login_steps"] = steps
-                    if secrets:
-                        entry["secrets"] = secrets
-                    return VerificationResult(True, "remote shell accepted a readiness probe")
-                steps.append({"expect": expect, "send": response})
-                child.sendline(response)  # type: ignore[attr-defined]
-    except Exception as exc:
-        return VerificationResult(False, str(exc))
+        result = client.exec(session.session_id, "printf hostbridge-ok", timeout=args.timeout, owner="cli-check")
     finally:
-        child.close(force=True)  # type: ignore[attr-defined]
-
-
-def run_setup(
-    *,
-    host_id: str | None = None,
-    label: str | None = None,
-    command_text: str | None = None,
-    from_host: str | None = None,
-    menu_selection: str | None = None,
-    menu_prompt: str = "Opt>",
-    final_prompt: str | None = None,
-    config_path: Path | str | None = None,
-    ask: AskFunc = input,
-    secret_ask: SecretAskFunc = getpass.getpass,
-    verify: VerifyFunc | None = None,
-    probe: SetupProbeFunc | None = None,
-    timeout: int = DEFAULT_VERIFY_TIMEOUT,
-) -> int:
-    verify = verify or verify_connection
-    probe = probe or (lambda entry, probe_timeout, probe_ask, probe_secret_ask: terminal_setup_probe(entry, probe_timeout))
-    print("HostBridge Setup")
-    print("This wizard opens a terminal-style setup session and records the real login path.")
-    print("Secret-looking prompts do not echo locally and are encrypted before saving.\n")
-
-    try:
-        resolved_host_id = (host_id or ask("Host id: ")).strip()
-        if from_host:
-            if menu_selection is None:
-                menu_selection = ask("Menu selection to send (host/IP/name): ").strip()
-            entry = clone_jump_host_entry(
-                config_path,
-                source_host_id=from_host,
-                host_id=resolved_host_id,
-                label=label,
-                menu_selection=menu_selection,
-                menu_prompt=menu_prompt,
-                final_prompt=final_prompt,
-            )
-        else:
-            resolved_label = label if label is not None else ask("Display label: ").strip()
-            resolved_label = resolved_label or resolved_host_id
-            if command_text is None:
-                print("\nPaste the command you normally use to connect.")
-                print("Examples: ssh user@host | ssh -J bastion user@host | bash ~/.ssh/connect.sh")
-                command_text = ask("Connection command: ")
-            entry = build_host_entry(resolved_host_id, resolved_label, command_text)
-            result = probe(entry, timeout, ask, secret_ask)
-            if not result.ok:
-                print(f"Connection verification failed: {result.message}")
-                return 1
-            print(f"Connection verified: {result.message}")
-            if entry.get("login_steps"):
-                print("\nVerifying recorded login steps with a fresh connection...")
-                result = verify(entry, timeout)
-                if not result.ok:
-                    print(f"Recorded login verification failed: {result.message}")
-                    return 1
-                print(f"Recorded login verified: {result.message}")
-    except Exception as exc:
-        print(f"Setup failed: {exc}")
-        return 1
-
-    if from_host:
-        print("\nTesting connection now with the saved runtime entry...")
-        result = verify(entry, timeout)
-        if not result.ok:
-            print(f"Connection verification failed: {result.message}")
-            return 1
-        print(f"Connection verified: {result.message}")
-
-    replace = False
-    try:
-        status = upsert_host_entry(config_path, entry, replace=False)
-    except ValueError as exc:
-        if "already exists" not in str(exc):
-            print(f"Save failed: {exc}")
-            return 1
-        answer = ask(f"Host '{entry['id']}' already exists. Replace it? [y/N]: ").strip().lower()
-        if answer not in ("y", "yes"):
-            print("Cancelled; no changes written.")
-            return 1
-        replace = True
-        status = upsert_host_entry(config_path, entry, replace=True)
-
-    saved_path = _resolve_hosts_config_path(config_path)
-    _secure_config_permissions(saved_path)
-    print(f"Saved host '{entry['id']}' ({status}) to {saved_path}")
-    if entry.get("login_steps"):
-        print(f"Configured {len(entry['login_steps'])} encrypted/automated login step(s).")
-    print("Next: MCP hosts_list/session_open will reload this config automatically.")
-    if replace:
-        print("Restart your MCP client if it is already running.")
-    return 0
-
-
-def run_check(
-    host_id: str,
-    *,
-    config_path: Path | str | None = None,
-    verify: VerifyFunc | None = None,
-    timeout: int = DEFAULT_VERIFY_TIMEOUT,
-) -> int:
-    verify = verify or verify_connection
-    entry = _find_raw_host_entry(config_path, host_id)
-    if entry is None:
-        print(f"Host '{host_id}' not found in {_resolve_hosts_config_path(config_path)}")
-        return 1
-    result = verify(entry, timeout)
-    if result.ok:
-        print(f"Connection verified: {result.message}")
-        return 0
-    print(f"Connection verification failed: {result.message}")
-    return 1
-
-
-def run_list(*, config_path: Path | str | None = None) -> int:
-    resolved_path = _resolve_hosts_config_path(config_path)
-    hosts = load_hosts(resolved_path)
-    if not hosts:
-        print(f"No hosts configured in {resolved_path}")
-        return 0
-    for host in hosts:
-        print(f"{host.id}\t{host.label}\t{host.connection_type}\t{host.command} {' '.join(host.args)}".rstrip())
-    return 0
-
-
-def run_remove(host_id: str, *, config_path: Path | str | None = None) -> int:
-    if remove_host_entry(config_path, host_id):
-        print(f"Removed host '{host_id}' from {_resolve_hosts_config_path(config_path)}")
-        return 0
-    print(f"Host '{host_id}' not found in {_resolve_hosts_config_path(config_path)}")
-    return 1
-
-
-def run_reload() -> int:
-    print("No manual CLI reload is required: the MCP server automatically reloads hosts.json during hosts_list and session_open.")
-    print("If your current MCP process predates this feature, restart it once to load the updated server code.")
-    return 0
+        client.close_session(session.session_id, owner="cli-check", force=True)
+    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")
+    return EXIT_OK
+
+
+def _run_doctor(args: argparse.Namespace) -> int:
+    executable = shutil.which("hostbridge")
+    report = collect_diagnostics(
+        _config_path(args.config),
+        client=HostBridgeClient(default_timeout=2),
+        executable_paths=[executable] if executable else [],
+    )
+    rows = [asdict(result) for result in report.results]
+    if args.as_json:
+        print(json.dumps({"ok": report.ok, "results": rows}, ensure_ascii=False, indent=2))
+    else:
+        for result in report.results:
+            print(f"{result.status.upper():4} {result.name}: {result.message}")
+    return EXIT_OK if report.ok else EXIT_UNAVAILABLE
 
 
-def run_daemon_command(command: str, *, foreground: bool = False, socket_file: Path | str | None = None) -> int:
+def _run_daemon(args: argparse.Namespace) -> int:
     from . import daemon
 
-    if command == "start":
-        if foreground:
-            return daemon.run_daemon(socket_file=socket_file)
-        return daemon.start_background(socket_file=socket_file)
-    if command == "stop":
-        return daemon.stop_background(socket_file=socket_file)
-    if command == "status":
-        if daemon.is_running(socket_file=socket_file):
-            print(f"hostbridge daemon running at unix://{daemon.socket_path(socket_file)}")
-            return 0
+    if args.daemon_command == "start":
+        if args.foreground:
+            return daemon.run_daemon(socket_file=args.socket, config_path=_config_path(args.config))
+        return daemon.start_background(socket_file=args.socket, config_path=_config_path(args.config))
+    if args.daemon_command == "stop":
+        return daemon.stop_background(socket_file=args.socket)
+    if args.daemon_command == "status":
+        if daemon.is_running(socket_file=args.socket):
+            print(f"hostbridge daemon running at unix://{daemon.socket_path(args.socket)}")
+            return EXIT_OK
         print("hostbridge daemon is not running")
-        return 1
-    raise ValueError(f"unknown daemon command: {command}")
-
-
-
-def run_entry_login_steps(child: object, entry: dict[str, object], timeout: int) -> None:
-    raw_steps = entry.get("login_steps", [])
-    if not isinstance(raw_steps, list):
-        raise ValueError("login_steps must be a list")
-    raw_secrets = entry.get("secrets", {})
-    if not isinstance(raw_secrets, dict):
-        raise ValueError("secrets must be an object")
-    for index, raw_step in enumerate(raw_steps):
-        if not isinstance(raw_step, dict):
-            raise ValueError(f"login_steps[{index}] must be an object")
-        expect = str(raw_step.get("expect", ""))
-        if not expect.strip():
-            raise ValueError(f"login_steps[{index}].expect must not be empty")
-        child.expect(_runtime_expect_pattern(expect), timeout=timeout)
-        if "send_secret" in raw_step:
-            secret_name = str(raw_step["send_secret"])
-            if secret_name not in raw_secrets:
-                raise ValueError(f"login step references missing secret '{secret_name}'")
-            text = decrypt_secret(raw_secrets[secret_name])
-        elif "send" in raw_step:
-            text = str(raw_step["send"])
-        else:
-            raise ValueError(f"login_steps[{index}] must define send or send_secret")
-        child.send(f"{text}\r")
-
-
-def wait_for_ready_prompt(child: object, entry: dict[str, object], timeout: int) -> None:
-    ready_expect = entry.get("ready_expect")
-    pattern = str(ready_expect) if isinstance(ready_expect, str) and ready_expect.strip() else r"(?m)[^\r\n]*[#$]\s*$"
-    pattern = _runtime_expect_pattern(pattern)
-    child.expect(pattern, timeout=timeout)
-
-
-def verify_connection(entry: dict[str, object], timeout: int = DEFAULT_VERIFY_TIMEOUT) -> VerificationResult:
-    command, args = _entry_to_command(entry)
-    marker = "__SCM_READY_SETUP__"
-    if entry.get("login_steps"):
-        print("\nRunning configured login automation before the readiness probe.\n")
-    else:
-        print("\nThe connection process is now attached to your terminal.")
-        print("Complete any password, passphrase, host-key, or 2FA prompts normally.")
-        print("When you see the remote shell prompt, press Ctrl-] to return to this wizard.\n")
-    child = pexpect.spawn(command, args, encoding="utf-8", codec_errors="replace", timeout=timeout, echo=False)
-    try:
-        if entry.get("login_steps"):
-            run_entry_login_steps(child, entry, timeout)
-            wait_for_ready_prompt(child, entry, timeout)
-        else:
-            child.interact(escape_character=chr(29))
-        child.send(f"printf '\\n{marker}\\n'\r")
-        child.expect(marker, timeout=timeout)
-        child.send("pwd\r")
-        child.expect(r"\r?\n", timeout=5)
-        return VerificationResult(True, "remote shell accepted a readiness probe")
-    except Exception as exc:
-        return VerificationResult(False, str(exc))
-    finally:
-        child.close(force=True)
-
-
-def _entry_to_command(entry: dict[str, object]) -> tuple[str, list[str]]:
-    if "script" in entry:
-        return "/bin/sh", [str(entry["script"])]
-    if "ssh" in entry:
-        ssh = entry["ssh"]
-        if not isinstance(ssh, dict):
-            raise ValueError("ssh entry must be an object")
-        args: list[str] = []
-        if ssh.get("port") not in (None, ""):
-            args.extend(["-p", str(ssh["port"])])
-        if ssh.get("identity_file"):
-            args.extend(["-i", str(ssh["identity_file"])])
-        if ssh.get("proxy_jump"):
-            args.extend(["-J", str(ssh["proxy_jump"])])
-        extra_args = ssh.get("extra_args", [])
-        if isinstance(extra_args, Iterable) and not isinstance(extra_args, (str, bytes)):
-            args.extend(str(arg) for arg in extra_args)
-        args.append(str(ssh["host"]))
-        return "ssh", args
-    return str(entry["command"]), [str(arg) for arg in entry.get("args", [])]
-
-
-def _find_raw_host_entry(config_path: Path | str, host_id: str) -> dict[str, object] | None:
-    config = _read_config(_resolve_hosts_config_path(config_path))
-    hosts = config.get("hosts", [])
-    if not isinstance(hosts, list):
-        raise ValueError(f"{config_path} must contain a top-level 'hosts' list")
-    for host in hosts:
-        if isinstance(host, dict) and host.get("id") == host_id:
-            return host
-    return None
-
-
-def _read_config(path: Path) -> dict[str, object]:
+        return EXIT_UNAVAILABLE
+    path = daemon.log_file()
     if not path.exists():
-        return {"hosts": []}
-    data = json.loads(path.read_text(encoding="utf-8"))
-    if not isinstance(data, dict):
-        raise ValueError(f"{path} must contain a JSON object")
-    data.setdefault("hosts", [])
-    return data
-
-
-def _write_config(path: Path, config: dict[str, object]) -> None:
-    path.parent.mkdir(parents=True, exist_ok=True)
-    path.write_text(json.dumps(config, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
-    _secure_config_permissions(path)
-
-
-def _secure_config_permissions(path: Path) -> None:
-    with suppress(OSError):
-        path.chmod(0o600)
-
-
-def main(argv: list[str] | None = None) -> int:
-    parser = argparse.ArgumentParser(prog=PUBLIC_NAME)
-    parser.add_argument("--config", help=f"Path to hosts.json (default: {DEFAULT_HOSTS_FILE})")
-    config_parent = argparse.ArgumentParser(add_help=False)
-    config_parent.add_argument("--config", help=argparse.SUPPRESS)
-    subparsers = parser.add_subparsers(dest="command", required=True)
-
-    install_parser = subparsers.add_parser("install", help="Register this MCP server with an agent client")
-    install_parser.add_argument("--target", choices=list(SUPPORTED_INSTALL_TARGETS), default="all")
-    install_parser.add_argument("--config", help="Override target config path for a single target")
-    install_parser.add_argument("--home", help="Home directory to scan for agent configs")
-    install_parser.add_argument("--command", dest="install_command", help="MCP server command to register")
-    install_parser.add_argument("--arg", dest="install_args", action="append", default=[], help="Argument for --command; repeatable")
-
-    setup_parser = subparsers.add_parser("setup", parents=[config_parent], help="Add and verify an allowlisted host")
-    setup_parser.add_argument("host_id", nargs="?", help="Stable host id to create")
-    setup_parser.add_argument("--label", help="Display label; defaults to host id")
-    setup_parser.add_argument("--command", dest="command_text", help="Connection command, e.g. 'ssh bastion'")
-    setup_parser.add_argument("--from-host", help="Clone connection style and encrypted secrets from an existing host")
-    setup_parser.add_argument("--menu-selection", help="JumpServer/menu selection to send for the cloned host")
-    setup_parser.add_argument("--menu-prompt", default="Opt>", help="Prompt regex before sending --menu-selection")
-    setup_parser.add_argument("--final-prompt", help="Remote shell prompt regex before readiness probe")
-    setup_parser.add_argument("--timeout", type=int, default=DEFAULT_VERIFY_TIMEOUT)
-
-    check_parser = subparsers.add_parser("check", parents=[config_parent], help="Verify a configured host")
-    check_parser.add_argument("host_id")
-    check_parser.add_argument("--timeout", type=int, default=DEFAULT_VERIFY_TIMEOUT)
+        print(f"no daemon log at {path}")
+        return EXIT_UNAVAILABLE
+    lines = path.read_text(encoding="utf-8", errors="replace").splitlines()
+    print("\n".join(lines[-max(1, min(args.lines, 10000)) :]))
+    return EXIT_OK
 
-    subparsers.add_parser("list", parents=[config_parent], help="List configured hosts")
-    subparsers.add_parser("reload", help="Explain runtime host reload behavior")
 
-    daemon_parser = subparsers.add_parser("daemon", help="Manage the HostBridge daemon")
-    daemon_subparsers = daemon_parser.add_subparsers(dest="daemon_command", required=True)
-    daemon_start = daemon_subparsers.add_parser("start", help="Start the HostBridge daemon")
-    daemon_start.add_argument("--foreground", action="store_true", help="Run daemon in the foreground")
-    daemon_start.add_argument("--socket", dest="socket_file", default=None, help="Unix socket path; default comes from HOSTBRIDGE_DAEMON_SOCKET or HOSTBRIDGE_DAEMON_DIR")
-    daemon_stop = daemon_subparsers.add_parser("stop", help="Stop the HostBridge daemon")
-    daemon_stop.add_argument("--socket", dest="socket_file", default=None, help="Unix socket path; default comes from HOSTBRIDGE_DAEMON_SOCKET or HOSTBRIDGE_DAEMON_DIR")
-    daemon_status = daemon_subparsers.add_parser("status", help="Show daemon status")
-    daemon_status.add_argument("--socket", dest="socket_file", default=None, help="Unix socket path; default comes from HOSTBRIDGE_DAEMON_SOCKET or HOSTBRIDGE_DAEMON_DIR")
-
-    mock_ssh_parser = subparsers.add_parser("mock-ssh", parents=[config_parent], help="Expose a HostBridge host as a local SSH server")
-    mock_ssh_parser.add_argument("host_id")
-    mock_ssh_parser.add_argument("--listen-host", default="127.0.0.1")
-    mock_ssh_parser.add_argument("--port", type=int, default=None, help="Local SSH port; default auto-selects a free port from 2222-2299")
-    mock_ssh_parser.add_argument("--key-dir", help="Directory for generated mock SSH host/client keys")
-    mock_ssh_parser.add_argument("--ssh-host-alias", help="Host alias to manage in ~/.ssh/config; default hostbridge-<host_id>")
-    mock_ssh_parser.add_argument("--ssh-config", help="SSH config path; default ~/.ssh/config")
-    mock_ssh_parser.add_argument("--no-ssh-config", action="store_true", help="Do not write a managed Host block to SSH config")
-    mock_ssh_parser.add_argument("--remove", action="store_true", help="Remove the managed SSH config block and exit")
-    mock_ssh_parser.add_argument("--connect-timeout", type=int, default=60)
-    mock_ssh_parser.add_argument("--command-timeout", type=int, default=DEFAULT_VERIFY_TIMEOUT)
-    mock_ssh_parser.add_argument("--output-limit", type=int, default=DEFAULT_MAX_TRANSFER_BYTES)
-
-    remove_parser = subparsers.add_parser("remove", parents=[config_parent], help="Remove a configured host")
-    remove_parser.add_argument("host_id")
-
-    secret_parser = subparsers.add_parser("secret", parents=[config_parent], help="Manage encrypted host secrets")
-    secret_subparsers = secret_parser.add_subparsers(dest="secret_command", required=True)
-    secret_set = secret_subparsers.add_parser("set", help="Encrypt and save a host secret")
-    secret_set.add_argument("host_id")
-    secret_set.add_argument("name")
-
-    step_parser = subparsers.add_parser("step", parents=[config_parent], help="Manage pre-login automation steps")
-    step_subparsers = step_parser.add_subparsers(dest="step_command", required=True)
-    step_add = step_subparsers.add_parser("add", help="Append an expect/send login step")
-    step_add.add_argument("host_id")
-    step_add.add_argument("--expect", required=True)
-    action = step_add.add_mutually_exclusive_group(required=True)
-    action.add_argument("--send")
-    action.add_argument("--send-secret")
-
-    args = parser.parse_args(argv)
-    if args.command == "install":
-        return run_install(
-            target=args.target,
-            config_path=Path(args.config).expanduser() if args.config else None,
-            command=args.install_command,
-            args=args.install_args,
-            home_path=Path(args.home).expanduser() if args.home else None,
-        )
-    config_path = Path(args.config).expanduser() if getattr(args, "config", None) else None
-    if args.command == "setup":
-        return run_setup(
-            host_id=args.host_id,
-            label=args.label,
-            command_text=args.command_text,
-            from_host=args.from_host,
-            menu_selection=args.menu_selection,
-            menu_prompt=args.menu_prompt,
-            final_prompt=args.final_prompt,
-            config_path=config_path,
-            timeout=args.timeout,
-        )
-    if args.command == "check":
-        return run_check(args.host_id, config_path=config_path, timeout=args.timeout)
-    if args.command == "list":
-        return run_list(config_path=config_path)
-    if args.command == "remove":
-        return run_remove(args.host_id, config_path=config_path)
-    if args.command == "reload":
-        return run_reload()
-    if args.command == "daemon":
-        return run_daemon_command(
-            args.daemon_command,
-            foreground=getattr(args, "foreground", False),
-            socket_file=getattr(args, "socket_file", None),
-        )
-    if args.command == "mock-ssh":
-        from .mock_ssh import run_mock_ssh, uninstall_mock_ssh
-
-        ssh_config_path = Path(args.ssh_config).expanduser() if args.ssh_config else None
-        if args.remove:
-            return uninstall_mock_ssh(
-                args.host_id,
-                ssh_host_alias=args.ssh_host_alias,
-                ssh_config_path=ssh_config_path,
-            )
+def _run_mock_ssh(args: argparse.Namespace) -> int:
+    from .mock_ssh import run_mock_ssh, uninstall_mock_ssh
 
+    if args.mock_command == "start":
         return run_mock_ssh(
             host_id=args.host_id,
-            config_path=config_path,
             listen_host=args.listen_host,
             port=args.port,
             key_dir=Path(args.key_dir).expanduser() if args.key_dir else None,
             ssh_host_alias=args.ssh_host_alias,
-            ssh_config_path=ssh_config_path,
+            ssh_config_path=Path(args.ssh_config).expanduser() if args.ssh_config else None,
             install_ssh_config=not args.no_ssh_config,
             connect_timeout=args.connect_timeout,
             command_timeout=args.command_timeout,
             output_limit=args.output_limit,
         )
-    if args.command == "secret" and args.secret_command == "set":
-        value = getpass.getpass(f"Secret value for {args.host_id}/{args.name}: ")
-        set_host_secret(config_path, args.host_id, args.name, value)
-        print(f"Saved encrypted secret '{args.name}' for host '{args.host_id}'")
-        return 0
-    if args.command == "step" and args.step_command == "add":
-        add_login_step(config_path, args.host_id, expect=args.expect, send=args.send, send_secret=args.send_secret)
-        print(f"Added login step for host '{args.host_id}'")
-        return 0
-    parser.error("unknown command")
-    return 2
+    if args.mock_command == "remove":
+        return uninstall_mock_ssh(
+            args.host_id,
+            ssh_host_alias=args.ssh_host_alias,
+            ssh_config_path=Path(args.ssh_config).expanduser() if args.ssh_config else None,
+        )
+    print("mock-ssh runs in the foreground; stop it with Ctrl-C and inspect it with your process supervisor")
+    return EXIT_USAGE
+
+
+def _exit_for(exc: Exception) -> int:
+    if isinstance(exc, HostBridgeError):
+        if exc.code in {"connection_lost", "timeout"}:
+            return EXIT_UNAVAILABLE
+        if exc.code == "denied":
+            return EXIT_DENIED
+        return EXIT_REMOTE
+    return EXIT_USAGE
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        if args.command == "version":
+            print(f"hostbridge {__version__}")
+            return EXIT_OK
+        if args.command == "setup":
+            return _run_setup(args)
+        if args.command == "migrate":
+            migrated = migrate_config(args.source, args.destination)
+            print(migrated.path)
+            return EXIT_OK
+        if args.command == "doctor":
+            return _run_doctor(args)
+        if args.command == "hosts":
+            return _run_hosts(args)
+        if args.command == "daemon":
+            return _run_daemon(args)
+        if args.command == "mock-ssh":
+            return _run_mock_ssh(args)
+    except (HostBridgeError, OSError, ValueError, json.JSONDecodeError) as exc:
+        print(f"hostbridge: {exc}", file=sys.stderr)
+        return _exit_for(exc)
+    return EXIT_USAGE
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())