compshare-cli 0.3.0__tar.gz → 0.3.2__tar.gz

{compshare_cli-0.3.0 → compshare_cli-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: compshare-cli
-Version: 0.3.0
+Version: 0.3.2
 Summary: Command-line client for CompShare GPU compute
 Author: CompShare
 License-Expression: Apache-2.0
@@ -35,7 +35,7 @@ Dynamic: license-file
 - 可通过 `compshare feedback` 反馈 CLI 问题和建议
 - 基于官方 [`ucloud-sdk-python3`](https://github.com/ucloud/ucloud-sdk-python3)
 
-当前版本：`0.3.0`，要求 Python 3.9 或更高版本。
+当前版本：`0.3.1`，要求 Python 3.9 或更高版本。
 
 ## 安装
 
@@ -54,12 +54,23 @@ source .venv/bin/activate
 python -m pip install -e '.[dev]'
 ```
 
-Windows 激活虚拟环境时使用：
+Windows PowerShell 中可先激活虚拟环境，再直接调用 `compshare`：
 
 ```powershell
 .\.venv\Scripts\Activate.ps1
+compshare -h
+compshare config --name default
 ```
 
+不激活虚拟环境时，使用 PowerShell 调用运算符 `&` 直接执行虚拟环境内的入口：
+
+```powershell
+& '.\.venv\Scripts\compshare.exe' -h
+& '.\.venv\Scripts\compshare.exe' config --name default
+```
+
+PowerShell 会把单引号中的路径解析为字符串，所以带参数执行时不能省略 `&`。路径包含空格时必须保留引号；从当前目录运行可执行文件时要使用 `.\` 前缀。若 `Activate.ps1` 被本机执行策略拦截，可直接使用上述不激活的写法，无需修改系统策略。
+
 ## 配置
 
 ```bash
@@ -105,6 +116,11 @@ compshare instance ssh INSTANCE_ID --no-auto-password
 # 自动登录后执行远程命令；远程参数用 -- 与 CLI 选项分隔
 compshare instance ssh INSTANCE_ID -- nvidia-smi --query-gpu=name
 compshare instance ssh INSTANCE_ID -- 'cd /workspace && python train.py'
+# Agent/脚本：执行并返回 ok、phase、exit_code、stdout、stderr、error
+compshare --json instance ssh INSTANCE_ID -- nvidia-smi
+# 强制刷新或禁用本地 SSH 连接缓存
+compshare instance ssh INSTANCE_ID --refresh
+compshare instance ssh INSTANCE_ID --no-cache
 # 上传本地文件或目录，目录会自动递归复制
 compshare instance scp INSTANCE_ID ./model.bin /workspace/model.bin
 compshare instance scp INSTANCE_ID ./dataset /workspace/dataset
@@ -219,6 +235,10 @@ compshare lang       # 查看当前语言
 - `instance ssh` 在支持的交互式终端中通过伪终端自动填写登录密码，不会打印密码或将其放入进程参数。
 - 自动登录会接受首次出现的 SSH 主机密钥；已记录主机的密钥发生变化时仍会拒绝连接。
 - `instance ssh INSTANCE_ID -- COMMAND` 可非交互执行远程命令，透传命令输出和退出码。
+- `--json instance ssh INSTANCE_ID -- COMMAND` 会真实执行命令，并结构化返回退出码、标准输出、标准错误及连接/认证错误阶段。
+- `--json` 始终以 UTF-8 字节输出，不依赖 Windows 活动代码页或终端编码。
+- `instance ssh` 默认将 API 返回的 SSH 命令和密码按 profile/实例缓存 1 小时；Windows 使用当前用户的 DPAPI 加密密码，其他平台将缓存文件权限限制为当前用户。可用 `--refresh` 强制更新、`--no-cache` 禁用；重置密码和重装实例会清除对应缓存。
+- 实例创建是异步操作；`instance create` 默认等待到 `Running`，显式使用 `--no-wait` 才会在创建接口返回后立即退出。`instance ssh` 也会默认等待实例运行后再连接。
 - `instance scp INSTANCE_ID LOCAL_PATH REMOTE_PATH` 可自动认证并上传本地文件或目录。
 - `--show-sensitive` 会恢复这些字段的原始值；请勿在共享终端、CI 日志或 Agent 会话中使用。
 - 删除、关机、重启、重装和改配等操作默认要求确认。

{compshare_cli-0.3.0 → compshare_cli-0.3.2}/README.md

@@ -10,7 +10,7 @@
 - 可通过 `compshare feedback` 反馈 CLI 问题和建议
 - 基于官方 [`ucloud-sdk-python3`](https://github.com/ucloud/ucloud-sdk-python3)
 
-当前版本：`0.3.0`，要求 Python 3.9 或更高版本。
+当前版本：`0.3.1`，要求 Python 3.9 或更高版本。
 
 ## 安装
 
@@ -29,12 +29,23 @@ source .venv/bin/activate
 python -m pip install -e '.[dev]'
 ```
 
-Windows 激活虚拟环境时使用：
+Windows PowerShell 中可先激活虚拟环境，再直接调用 `compshare`：
 
 ```powershell
 .\.venv\Scripts\Activate.ps1
+compshare -h
+compshare config --name default
 ```
 
+不激活虚拟环境时，使用 PowerShell 调用运算符 `&` 直接执行虚拟环境内的入口：
+
+```powershell
+& '.\.venv\Scripts\compshare.exe' -h
+& '.\.venv\Scripts\compshare.exe' config --name default
+```
+
+PowerShell 会把单引号中的路径解析为字符串，所以带参数执行时不能省略 `&`。路径包含空格时必须保留引号；从当前目录运行可执行文件时要使用 `.\` 前缀。若 `Activate.ps1` 被本机执行策略拦截，可直接使用上述不激活的写法，无需修改系统策略。
+
 ## 配置
 
 ```bash
@@ -80,6 +91,11 @@ compshare instance ssh INSTANCE_ID --no-auto-password
 # 自动登录后执行远程命令；远程参数用 -- 与 CLI 选项分隔
 compshare instance ssh INSTANCE_ID -- nvidia-smi --query-gpu=name
 compshare instance ssh INSTANCE_ID -- 'cd /workspace && python train.py'
+# Agent/脚本：执行并返回 ok、phase、exit_code、stdout、stderr、error
+compshare --json instance ssh INSTANCE_ID -- nvidia-smi
+# 强制刷新或禁用本地 SSH 连接缓存
+compshare instance ssh INSTANCE_ID --refresh
+compshare instance ssh INSTANCE_ID --no-cache
 # 上传本地文件或目录，目录会自动递归复制
 compshare instance scp INSTANCE_ID ./model.bin /workspace/model.bin
 compshare instance scp INSTANCE_ID ./dataset /workspace/dataset
@@ -194,6 +210,10 @@ compshare lang       # 查看当前语言
 - `instance ssh` 在支持的交互式终端中通过伪终端自动填写登录密码，不会打印密码或将其放入进程参数。
 - 自动登录会接受首次出现的 SSH 主机密钥；已记录主机的密钥发生变化时仍会拒绝连接。
 - `instance ssh INSTANCE_ID -- COMMAND` 可非交互执行远程命令，透传命令输出和退出码。
+- `--json instance ssh INSTANCE_ID -- COMMAND` 会真实执行命令，并结构化返回退出码、标准输出、标准错误及连接/认证错误阶段。
+- `--json` 始终以 UTF-8 字节输出，不依赖 Windows 活动代码页或终端编码。
+- `instance ssh` 默认将 API 返回的 SSH 命令和密码按 profile/实例缓存 1 小时；Windows 使用当前用户的 DPAPI 加密密码，其他平台将缓存文件权限限制为当前用户。可用 `--refresh` 强制更新、`--no-cache` 禁用；重置密码和重装实例会清除对应缓存。
+- 实例创建是异步操作；`instance create` 默认等待到 `Running`，显式使用 `--no-wait` 才会在创建接口返回后立即退出。`instance ssh` 也会默认等待实例运行后再连接。
 - `instance scp INSTANCE_ID LOCAL_PATH REMOTE_PATH` 可自动认证并上传本地文件或目录。
 - `--show-sensitive` 会恢复这些字段的原始值；请勿在共享终端、CI 日志或 Agent 会话中使用。
 - 删除、关机、重启、重装和改配等操作默认要求确认。

{compshare_cli-0.3.0 → compshare_cli-0.3.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "compshare-cli"
-version = "0.3.0"
+version = "0.3.2"
 description = "Command-line client for CompShare GPU compute"
 readme = "README.md"
 requires-python = ">=3.9"

{compshare_cli-0.3.0 → compshare_cli-0.3.2}/src/compshare_cli/__init__.py

@@ -1,3 +1,3 @@
 """CompShare command-line client."""
 
-__version__ = "0.3.0"
+__version__ = "0.3.2"

{compshare_cli-0.3.0 → compshare_cli-0.3.2}/src/compshare_cli/commands/doctor.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import os
+import platform
 import shutil
 import stat
 import sys
@@ -61,7 +62,18 @@ def run(state: Runtime) -> None:
         )
     )
 
-    if store.path.exists():
+    if store.path.exists() and platform.system() == "Windows":
+        checks.append(
+            _check(
+                "Permissions",
+                "Warning",
+                tr(
+                    "Config {path}: Windows ACLs apply; POSIX permission check skipped.",
+                    path=store.path,
+                ),
+            )
+        )
+    elif store.path.exists():
         file_mode = stat.S_IMODE(store.path.stat().st_mode)
         directory_mode = stat.S_IMODE(store.path.parent.stat().st_mode)
         permissions_ok = file_mode & 0o077 == 0 and directory_mode & 0o077 == 0

{compshare_cli-0.3.0 → compshare_cli-0.3.2}/src/compshare_cli/commands/instance.py

@@ -1,10 +1,12 @@
 from __future__ import annotations
 
+import os
 import shlex
 import subprocess
 import sys
 import time
 from decimal import Decimal, InvalidOperation
+from hashlib import sha256
 from pathlib import Path
 from typing import Any, Callable, Dict, Iterable, List, Optional, Sequence, Tuple, TypeVar
 
@@ -12,6 +14,7 @@ import typer
 
 from compshare_cli.api import call, call_captured, collect_pages, invoke
 from compshare_cli.commands.common import confirm, confirm_details, request, runtime
+from compshare_cli.config import ConfigStore
 from compshare_cli.errors import UsageError
 from compshare_cli.i18n import tr
 from compshare_cli.location import instance_location, locate_instance, supported_locations
@@ -30,9 +33,12 @@ from compshare_cli.ssh import (
     PasswordAutomationUnavailable,
     connect_with_password,
     copy_with_password,
+    execute_captured,
+    execute_captured_with_password,
     execute_with_password,
     scp_upload_command,
 )
+from compshare_cli.ssh_cache import DEFAULT_TTL, SSHCredentialCache
 
 app = typer.Typer(help="Manage GPU instances.", no_args_is_help=True)
 ports_app = typer.Typer(help="Manage container port mappings.", no_args_is_help=True)
@@ -203,6 +209,41 @@ def _wait_enabled(state: Runtime, value: Optional[bool]) -> bool:
     return not state.json_output and sys.stdout.isatty()
 
 
+def _create_wait_enabled(value: Optional[bool]) -> bool:
+    """Creation is asynchronous, so wait by default in both human and Agent modes."""
+    return True if value is None else value
+
+
+def _ssh_cache_profile(state: Runtime) -> str:
+    name = (
+        state.profile_name or os.environ.get("COMPSHARE_PROFILE") or ConfigStore().current_profile()
+    )
+    credential = sha256(state.profile.public_key.encode("utf-8")).hexdigest()[:16]
+    return f"{name}:{credential}"
+
+
+def _locate_ssh_instance(
+    state: Runtime,
+    instance: str,
+    *,
+    use_cache: bool,
+    refresh: bool,
+    cache_ttl: int,
+) -> Tuple[str, str, Dict[str, Any], str]:
+    cache = SSHCredentialCache()
+    profile = _ssh_cache_profile(state)
+    if use_cache and not refresh:
+        host = cache.get(profile, instance, ttl=cache_ttl)
+        if host is not None:
+            region, zone = instance_location(host, instance)
+            return region, zone, host, "cache"
+
+    region, zone, host = locate_instance(state, instance)
+    if use_cache:
+        cache.put(profile, instance, host)
+    return region, zone, host, "api"
+
+
 def _wait_for_instance(
     state: Runtime,
     instance: str,
@@ -937,9 +978,16 @@ def create(
     ids = created.get("UHostIds") or created.get("UHostId") or []
     if isinstance(ids, str):
         ids = [ids]
-    if _wait_enabled(state, wait):
+    if _create_wait_enabled(wait):
         result["final"] = [
-            _wait_for_instance(state, item, region=region, timeout=timeout) for item in ids
+            _wait_for_instance(
+                state,
+                item,
+                region=region,
+                desired={"Running"},
+                timeout=timeout,
+            )
+            for item in ids
         ]
     Renderer(state.json_output, state.show_sensitive).details(
         "Operation completed",
@@ -1286,6 +1334,7 @@ def password(
         yes=yes,
         extra={"Password": encode_password(secret)},
     )
+    SSHCredentialCache().delete(_ssh_cache_profile(runtime(ctx)), instance)
 
 
 @app.command("reinstall", help="Reinstall an instance from an image.")
@@ -1318,6 +1367,7 @@ def reinstall(
         wait=wait,
         timeout=timeout,
     )
+    SSHCredentialCache().delete(_ssh_cache_profile(runtime(ctx)), instance)
 
 
 @app.command("resize", help="Change instance CPU, memory, GPU or disk size.")
@@ -1758,16 +1808,65 @@ def ssh(
         "--auto-password/--no-auto-password",
         help="Automatically enter the password returned by the API.",
     ),
+    wait: bool = typer.Option(
+        True,
+        "--wait/--no-wait",
+        help="Wait for the instance to be running before connecting.",
+    ),
+    timeout: int = typer.Option(600, "--timeout", min=1, help="Maximum wait time in seconds."),
+    connect_timeout: int = typer.Option(
+        30,
+        "--connect-timeout",
+        min=1,
+        help="Maximum SSH connection time in seconds.",
+    ),
+    use_cache: bool = typer.Option(
+        True,
+        "--cache/--no-cache",
+        help="Cache SSH connection data to avoid repeated instance queries.",
+    ),
+    cache_ttl: int = typer.Option(
+        DEFAULT_TTL,
+        "--cache-ttl",
+        min=1,
+        help="SSH connection cache lifetime in seconds.",
+    ),
+    refresh: bool = typer.Option(
+        False,
+        "--refresh",
+        help="Refresh SSH connection data from the API before connecting.",
+    ),
 ) -> None:
     state = runtime(ctx)
-    region, zone, host = locate_instance(state, instance)
+    region, zone, host, credential_source = _locate_ssh_instance(
+        state,
+        instance,
+        use_cache=use_cache,
+        refresh=refresh,
+        cache_ttl=cache_ttl,
+    )
+    if wait and host.get("State") and str(host.get("State")) != "Running":
+        ready = _wait_for_instance(
+            state,
+            instance,
+            region=region,
+            desired={"Running"},
+            timeout=timeout,
+        )
+        hosts = ready.get("UHostSet") or []
+        if hosts:
+            host = hosts[0]
+            if use_cache:
+                SSHCredentialCache().put(_ssh_cache_profile(state), instance, host)
     command = host.get("SshLoginCommand")
     raw_password = host.get("Password")
     password = decode_password(str(raw_password)) if raw_password is not None else None
     if not command:
         raise UsageError(tr("Instance {instance} has no SSH login command.", instance=instance))
     argv = [*shlex.split(command), *(remote_command or [])]
-    if print_only or state.json_output:
+    if remote_command:
+        argv[1:1] = ["-o", f"ConnectTimeout={connect_timeout}"]
+    if print_only or (state.json_output and not remote_command):
         Renderer(state.json_output, state.show_sensitive).data(
             {
                 "instance": instance,
@@ -1775,9 +1874,43 @@ def ssh(
                 if not remote_command
                 else f"{command} {shlex.join(remote_command)}",
                 "password": password,
+                "credential_source": credential_source,
             }
         )
         return
+    if remote_command and state.json_output:
+        execution = (
+            execute_captured_with_password(argv, str(password))
+            if password and auto_password
+            else execute_captured(argv)
+        )
+        error = None
+        if not execution.ok:
+            message = execution.stderr.strip() or f"SSH exited with status {execution.exit_code}."
+            error = {
+                "phase": execution.phase,
+                "code": execution.error_code,
+                "message": message,
+            }
+            if credential_source == "cache" and execution.phase in {
+                "authentication",
+                "connection",
+                "ssh",
+            }:
+                SSHCredentialCache().delete(_ssh_cache_profile(state), instance)
+        Renderer(True, state.show_sensitive).data(
+            {
+                "instance": instance,
+                "ok": execution.ok,
+                "phase": execution.phase,
+                "exit_code": execution.exit_code,
+                "stdout": execution.stdout,
+                "stderr": execution.stderr,
+                "error": error,
+                "credential_source": credential_source,
+            }
+        )
+        raise typer.Exit(execution.exit_code)
     if password and state.show_sensitive:
         typer.echo(f"Password: {password}")
     if password and auto_password:
@@ -1795,6 +1928,8 @@ def ssh(
                 err=True,
             )
         else:
+            if exit_code == 255 and credential_source == "cache":
+                SSHCredentialCache().delete(_ssh_cache_profile(state), instance)
             raise typer.Exit(exit_code)
     if password and not state.show_sensitive:
         typer.echo(tr("Password hidden; rerun with --show-sensitive to display it."))
@@ -1806,7 +1941,10 @@ def ssh(
                 instance=instance,
             )
         )
-    raise typer.Exit(subprocess.call(argv))
+    exit_code = subprocess.call(argv)
+    if exit_code == 255 and credential_source == "cache":
+        SSHCredentialCache().delete(_ssh_cache_profile(state), instance)
+    raise typer.Exit(exit_code)
 
 
 @app.command("scp", help="Copy a local file or directory to an instance.")

{compshare_cli-0.3.0 → compshare_cli-0.3.2}/src/compshare_cli/i18n.py

@@ -93,6 +93,15 @@ ZH_TRANSLATIONS: Dict[str, str] = {
     "Month, Day, Dynamic or Postpay.": "目标计费方式：Month、Day、Dynamic 或 Postpay。",
     "Print instead of executing SSH.": "只显示 SSH 命令，不执行连接。",
     "Automatically enter the password returned by the API.": "自动填写 API 返回的登录密码。",
+    "Wait for the instance to be running before connecting.": "连接前等待实例进入运行状态。",
+    "Maximum SSH connection time in seconds.": "SSH 建立连接的最长时间（秒）。",
+    "Cache SSH connection data to avoid repeated instance queries.": (
+        "缓存 SSH 连接信息，避免重复查询实例。"
+    ),
+    "SSH connection cache lifetime in seconds.": "SSH 连接缓存的有效期（秒）。",
+    "Refresh SSH connection data from the API before connecting.": (
+        "连接前从 API 强制刷新 SSH 连接信息。"
+    ),
     "Remote command and arguments; use -- before command options.": (
         "要在实例中执行的命令及参数；命令包含选项时请先使用 -- 分隔。"
     ),
@@ -618,6 +627,9 @@ ZH_TRANSLATIONS: Dict[str, str] = {
     "Config {path}: file {file_mode}, directory {directory_mode}": (
         "配置 {path}：文件权限 {file_mode}，目录权限 {directory_mode}"
     ),
+    "Config {path}: Windows ACLs apply; POSIX permission check skipped.": (
+        "配置 {path}：由 Windows ACL 管理访问权限，已跳过 POSIX 权限位检查"
+    ),
     "Using environment credentials": "正在使用环境变量凭证",
     "Config file does not exist: {path}": "配置文件不存在：{path}",
     "Connected; {count} availability zones returned.": "连接成功，返回 {count} 个可用区。",

{compshare_cli-0.3.0 → compshare_cli-0.3.2}/src/compshare_cli/output.py

@@ -65,6 +65,22 @@ def sanitized(value: Any, *, show_sensitive: bool = False) -> Any:
     return value
 
 
+def _write_json(payload: Dict[str, Any]) -> None:
+    """Write one UTF-8 JSON document independently of the console code page."""
+    document = json.dumps(payload, ensure_ascii=False, separators=(",", ":")) + "\n"
+    stream = sys.stdout
+    binary = getattr(stream, "buffer", None)
+    if binary is not None:
+        stream.flush()
+        binary.write(document.encode("utf-8"))
+        binary.flush()
+        return
+    # String-only test/application streams have no byte encoding contract. Escaping
+    # non-ASCII keeps this fallback valid UTF-8 under every ASCII-compatible encoding.
+    stream.write(json.dumps(payload, ensure_ascii=True, separators=(",", ":")) + "\n")
+    stream.flush()
+
+
 class Renderer:
     def __init__(self, json_output: bool, show_sensitive: bool = False) -> None:
         self.json_output = json_output
@@ -80,7 +96,7 @@ class Renderer:
     ) -> None:
         safe = sanitized(response, show_sensitive=self.show_sensitive)
         if self.json_output:
-            sys.stdout.write(json.dumps(safe, ensure_ascii=False, separators=(",", ":")) + "\n")
+            _write_json(safe)
             return
         if rows is not None and columns:
             self.table(rows, columns)
@@ -139,7 +155,7 @@ class Renderer:
                     details,
                     show_sensitive=self.show_sensitive,
                 )
-            sys.stdout.write(json.dumps(payload, ensure_ascii=False, separators=(",", ":")) + "\n")
+            _write_json(payload)
         else:
             Console(stderr=True).print(f"[red]{tr('Error')}:[/red] {message}")
 

{compshare_cli-0.3.0 → compshare_cli-0.3.2}/src/compshare_cli/ssh.py

@@ -7,6 +7,7 @@ import signal
 import subprocess
 import sys
 import tempfile
+from dataclasses import dataclass
 from typing import Any, List, Optional
 
 _ASKPASS_PASSWORD_FILE_ENV = "COMPSHARE_INTERNAL_SSH_PASSWORD_FILE"
@@ -40,6 +41,25 @@ class PasswordAutomationUnavailable(RuntimeError):
     """Raised when the current terminal cannot safely automate an SSH password."""
 
 
+@dataclass(frozen=True)
+class RemoteExecutionResult:
+    """Captured output and an Agent-friendly classification of an SSH execution."""
+
+    exit_code: int
+    stdout: str
+    stderr: str
+    phase: str
+    error_code: Optional[str] = None
+
+    @property
+    def ok(self) -> bool:
+        return self.exit_code == 0
+
+
+def _is_windows() -> bool:
+    return os.name == "nt"
+
+
 def _password_authentication(argv: List[str], *, command_mode: bool = False) -> List[str]:
     executable = os.path.basename(argv[0]).casefold()
     if executable not in {"ssh", "ssh.exe"}:
@@ -133,7 +153,7 @@ def scp_upload_command(
 
 
 def _askpass_executable() -> str:
-    name = "compshare-ssh-askpass.exe" if os.name == "nt" else "compshare-ssh-askpass"
+    name = "compshare-ssh-askpass.exe" if _is_windows() else "compshare-ssh-askpass"
     sibling = os.path.join(os.path.dirname(os.path.abspath(sys.argv[0])), name)
     if os.path.isfile(sibling) and os.access(sibling, os.X_OK):
         return sibling
@@ -167,13 +187,70 @@ def execute_with_password(argv: List[str], password: str) -> int:
     return _run_with_askpass(command, password)
 
 
+def execute_captured_with_password(argv: List[str], password: str) -> RemoteExecutionResult:
+    """Run and capture a non-interactive SSH command without exposing its password."""
+    command = _password_authentication(argv, command_mode=True)
+    completed = _run_with_askpass(command, password, capture=True)
+    assert isinstance(completed, subprocess.CompletedProcess)
+    return remote_execution_result(completed.returncode, completed.stdout, completed.stderr)
+
+
+def execute_captured(argv: List[str]) -> RemoteExecutionResult:
+    """Run and capture a non-interactive SSH command using normal OpenSSH auth."""
+    executable = os.path.basename(argv[0]).casefold()
+    if executable not in {"ssh", "ssh.exe"}:
+        raise PasswordAutomationUnavailable
+    command = [
+        argv[0],
+        "-o",
+        "StrictHostKeyChecking=accept-new",
+        "-n",
+        "-T",
+        *argv[1:],
+    ]
+    completed = subprocess.run(command, capture_output=True, text=True, check=False)
+    return remote_execution_result(completed.returncode, completed.stdout, completed.stderr)
+
+
+def remote_execution_result(exit_code: int, stdout: str, stderr: str) -> RemoteExecutionResult:
+    """Classify common OpenSSH failures while preserving the original diagnostics."""
+    if exit_code == 0:
+        return RemoteExecutionResult(exit_code, stdout, stderr, "completed")
+
+    diagnostic = stderr.casefold()
+    patterns = (
+        ("could not resolve hostname", "connection", "dns_resolution_failed"),
+        ("name or service not known", "connection", "dns_resolution_failed"),
+        ("connection timed out", "connection", "connection_timeout"),
+        ("operation timed out", "connection", "connection_timeout"),
+        ("no route to host", "connection", "network_unreachable"),
+        ("network is unreachable", "connection", "network_unreachable"),
+        ("connection refused", "connection", "connection_refused"),
+        ("host key verification failed", "connection", "host_key_verification_failed"),
+        ("permission denied", "authentication", "authentication_failed"),
+        ("authentication failed", "authentication", "authentication_failed"),
+        ("too many authentication failures", "authentication", "authentication_failed"),
+    )
+    for marker, phase, error_code in patterns:
+        if marker in diagnostic:
+            return RemoteExecutionResult(exit_code, stdout, stderr, phase, error_code)
+    if exit_code == 255:
+        return RemoteExecutionResult(exit_code, stdout, stderr, "ssh", "ssh_failed")
+    return RemoteExecutionResult(exit_code, stdout, stderr, "remote_command", "remote_exit_nonzero")
+
+
 def copy_with_password(argv: List[str], password: str) -> int:
     """Run an SCP upload using the API-provided password."""
     command = _scp_password_authentication(argv)
     return _run_with_askpass(command, password)
 
 
-def _run_with_askpass(command: List[str], password: str) -> int:
+def _run_with_askpass(
+    command: List[str],
+    password: str,
+    *,
+    capture: bool = False,
+) -> Any:
     with tempfile.TemporaryDirectory(prefix="compshare-ssh-") as temporary_directory:
         password_file = os.path.join(temporary_directory, "password")
         descriptor = os.open(password_file, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
@@ -188,12 +265,22 @@ def _run_with_askpass(command: List[str], password: str) -> int:
             }
         )
         environment.setdefault("DISPLAY", "compshare-ssh")
+        if capture:
+            return subprocess.run(
+                command,
+                env=environment,
+                capture_output=True,
+                text=True,
+                check=False,
+            )
         return subprocess.call(command, env=environment)
 
 
 def connect_with_password(argv: List[str], password: str) -> int:
     """Run SSH interactively and answer its first password prompt."""
-    if os.name == "nt" or not sys.stdin.isatty() or not sys.stdout.isatty():
+    if _is_windows():
+        return _run_with_askpass(_password_authentication(argv), password)
+    if not sys.stdin.isatty() or not sys.stdout.isatty():
         raise PasswordAutomationUnavailable
 
     try: