vmware-aiops 2.3.0__tar.gz → 2.3.1__tar.gz

{vmware_aiops-2.3.0 → vmware_aiops-2.3.1}/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "vmware-aiops",
   "displayName": "VMware AIops",
-  "version": "2.3.0",
+  "version": "2.3.1",
   "description": "AI-powered VMware vCenter/ESXi VM lifecycle and deployment with 61 MCP tools.",
   "author": {
     "name": "Wei Zhou",

{vmware_aiops-2.3.0 → vmware_aiops-2.3.1}/.mcp.json

@@ -5,7 +5,7 @@
       "command": "uvx",
       "args": [
         "--from",
-        "vmware-aiops==2.3.0",
+        "vmware-aiops==2.3.1",
         "vmware-aiops-mcp"
       ]
     }

vmware_aiops-2.3.0/README.md → vmware_aiops-2.3.1/PKG-INFO

@@ -1,3 +1,27 @@
+Metadata-Version: 2.5
+Name: vmware-aiops
+Version: 2.3.1
+Summary: VMware vCenter/ESXi AI-powered VM lifecycle and deployment tool
+Project-URL: Homepage, https://github.com/vmware-skills/VMware-AIops
+Project-URL: Repository, https://github.com/vmware-skills/VMware-AIops
+Project-URL: Issues, https://github.com/vmware-skills/VMware-AIops/issues
+Project-URL: Changelog, https://github.com/vmware-skills/VMware-AIops/blob/main/RELEASE_NOTES.md
+Author-email: Wei Zhou <wei-wz.zhou@broadcom.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: apscheduler<4.0,>=3.10
+Requires-Dist: httpx<1.0,>=0.27
+Requires-Dist: mcp[cli]<2.0,>=1.28
+Requires-Dist: pyaml<27.0,>=24.0
+Requires-Dist: python-dotenv<2.0,>=1.0
+Requires-Dist: pyvmomi<10.0,>=8.0.3.0
+Requires-Dist: rich<16.0,>=13.0
+Requires-Dist: typer<1.0,>=0.12
+Requires-Dist: vmware-monitor<3.0,>=2.3.1
+Requires-Dist: vmware-policy<2.0,>=1.23.0
+Description-Content-Type: text/markdown
+
 <!-- mcp-name: io.github.vmware-skills/vmware-aiops -->
 # VMware AIops
 
@@ -436,6 +460,9 @@ Run `vmware-aiops plan list` to see failed plan status. Ask user if they want to
 1. Verify target is reachable: `vmware-aiops doctor`
 2. For self-signed certs: set `verify_ssl: false` in config.yaml (lab environments only)
 
+### `doctor` reports "no vSphere role", or every command fails with "session is not authenticated"
+The account logs in but has no vSphere role, so vCenter gives it no session (AIops#47). Assign it a role (Read-Only or higher) on the vCenter root folder: Administration > Access Control > Global Permissions. Changing the password will not help. `vmware-aiops doctor` reports this case by name, and `attention` counts such a target as unread (overall at least WARN).
+
 ---
 
 ## Supported AI Platforms
@@ -1164,6 +1191,12 @@ claude mcp add --transport http vmware-aiops https://mcp.example.com:8443/mcp \
   before it binds that unauthenticated requests get 401. Use a certificate your clients trust for those names.
 - Behind a TLS-terminating reverse proxy on the same machine use `--transport http --host 127.0.0.1
   --public-name mcp.example.com` and pass the `Authorization` header through.
+- Behind a load balancer or gateway on another machine, keep `--transport https` (a self-signed certificate is
+  fine), list in `--public-name` the host name the balancer sends as `Host`, and have it forward `Authorization`.
+  Its health probe can use `GET /healthz`, which needs no token and returns only `{"status": "ok"}`
+  (vmware-policy ≥ 1.23.0).
+- Send `traceparent` or `X-Request-ID` with each request to have it stored on the audit row;
+  `vmware-audit log --correlation-id ID` then finds the calls behind one platform request.
 - The audit log records each caller as `token:<name>`. Calls run side by side, with up to `VMWARE_MCP_POOL_SIZE`
   (default 2) sessions per target; each session is a login on the target, and a call waits at most 300 s for one.
 - **Everyone who can reach the endpoint acts with this server's account.** Tokens identify callers; they grant

{vmware_aiops-2.3.0 → vmware_aiops-2.3.1}/README-CN.md

@@ -379,6 +379,9 @@ vSphere 中 VM 名称区分大小写。请使用 `vmware-monitor inventory vms`
 1. 验证目标可达：`vmware-aiops doctor`
 2. 自签名证书：在 config.yaml 中设置 `verify_ssl: false`（仅限实验环境）
 
+### `doctor` 报 "no vSphere role"，或所有命令都报 "session is not authenticated"
+账号能登录，但没有任何 vSphere 角色，所以 vCenter 不给它会话（AIops#47）。在 vCenter 根文件夹上给它分配角色（Read-Only 或更高）：Administration > Access Control > Global Permissions。改密码没有用。`vmware-aiops doctor` 会直接报出这种情况，`attention` 也会把这样的目标算作未读取（总体状态至少为 WARN）。
+
 ---
 
 ## 支持的 AI 平台
@@ -829,6 +832,11 @@ claude mcp add --transport http vmware-aiops https://mcp.example.com:8443/mcp \
   证书要用客户端信任、且覆盖这些名字的证书。
 - 在同一台机器上由反向代理终结 TLS 时，用 `--transport http --host 127.0.0.1 --public-name mcp.example.com`，
   并让代理透传 `Authorization` 头。
+- 负载均衡或网关在另一台机器上时，保持 `--transport https`（自签证书也可以），在 `--public-name` 里写上负载均衡
+  转发时带的 `Host` 名，并让它透传 `Authorization`。健康检查可以用 `GET /healthz`：不需要 token，只返回
+  `{"status": "ok"}`（需 vmware-policy ≥ 1.23.0）。
+- 每个请求带上 `traceparent` 或 `X-Request-ID`，它会记进审计记录；用 `vmware-audit log --correlation-id ID`
+  就能查到平台上某一次请求对应的调用。
 - 审计日志把每个调用者记为 `token:<名字>`。调用并行执行，每个 target 最多 `VMWARE_MCP_POOL_SIZE`（默认 2）
   个会话；每个会话都是在该 target 上的一次登录，一个调用最多等待 300 秒拿到会话。
 - **能连到这个端点的人，都以该 server 配置的账号操作。** token 只用来识别调用者，不在平台上授予任何权限。

vmware_aiops-2.3.0/PKG-INFO → vmware_aiops-2.3.1/README.md

@@ -1,27 +1,3 @@
-Metadata-Version: 2.5
-Name: vmware-aiops
-Version: 2.3.0
-Summary: VMware vCenter/ESXi AI-powered VM lifecycle and deployment tool
-Project-URL: Homepage, https://github.com/vmware-skills/VMware-AIops
-Project-URL: Repository, https://github.com/vmware-skills/VMware-AIops
-Project-URL: Issues, https://github.com/vmware-skills/VMware-AIops/issues
-Project-URL: Changelog, https://github.com/vmware-skills/VMware-AIops/blob/main/RELEASE_NOTES.md
-Author-email: Wei Zhou <wei-wz.zhou@broadcom.com>
-License-Expression: MIT
-License-File: LICENSE
-Requires-Python: >=3.10
-Requires-Dist: apscheduler<4.0,>=3.10
-Requires-Dist: httpx<1.0,>=0.27
-Requires-Dist: mcp[cli]<2.0,>=1.28
-Requires-Dist: pyaml<27.0,>=24.0
-Requires-Dist: python-dotenv<2.0,>=1.0
-Requires-Dist: pyvmomi<10.0,>=8.0.3.0
-Requires-Dist: rich<16.0,>=13.0
-Requires-Dist: typer<1.0,>=0.12
-Requires-Dist: vmware-monitor<3.0,>=2.0.0
-Requires-Dist: vmware-policy<2.0,>=1.22.0
-Description-Content-Type: text/markdown
-
 <!-- mcp-name: io.github.vmware-skills/vmware-aiops -->
 # VMware AIops
 
@@ -460,6 +436,9 @@ Run `vmware-aiops plan list` to see failed plan status. Ask user if they want to
 1. Verify target is reachable: `vmware-aiops doctor`
 2. For self-signed certs: set `verify_ssl: false` in config.yaml (lab environments only)
 
+### `doctor` reports "no vSphere role", or every command fails with "session is not authenticated"
+The account logs in but has no vSphere role, so vCenter gives it no session (AIops#47). Assign it a role (Read-Only or higher) on the vCenter root folder: Administration > Access Control > Global Permissions. Changing the password will not help. `vmware-aiops doctor` reports this case by name, and `attention` counts such a target as unread (overall at least WARN).
+
 ---
 
 ## Supported AI Platforms
@@ -1188,6 +1167,12 @@ claude mcp add --transport http vmware-aiops https://mcp.example.com:8443/mcp \
   before it binds that unauthenticated requests get 401. Use a certificate your clients trust for those names.
 - Behind a TLS-terminating reverse proxy on the same machine use `--transport http --host 127.0.0.1
   --public-name mcp.example.com` and pass the `Authorization` header through.
+- Behind a load balancer or gateway on another machine, keep `--transport https` (a self-signed certificate is
+  fine), list in `--public-name` the host name the balancer sends as `Host`, and have it forward `Authorization`.
+  Its health probe can use `GET /healthz`, which needs no token and returns only `{"status": "ok"}`
+  (vmware-policy ≥ 1.23.0).
+- Send `traceparent` or `X-Request-ID` with each request to have it stored on the audit row;
+  `vmware-audit log --correlation-id ID` then finds the calls behind one platform request.
 - The audit log records each caller as `token:<name>`. Calls run side by side, with up to `VMWARE_MCP_POOL_SIZE`
   (default 2) sessions per target; each session is a login on the target, and a call waits at most 300 s for one.
 - **Everyone who can reach the endpoint acts with this server's account.** Tokens identify callers; they grant

{vmware_aiops-2.3.0 → vmware_aiops-2.3.1}/RELEASE_NOTES.md

@@ -1,3 +1,31 @@
+## v2.3.1 — an account with no vSphere role is named, not passed (AIops#47)
+
+Needs vmware-policy 1.23.0, and the vmware-monitor release with the same fix for the `attention` part.
+
+* **A login with no vSphere role fails at connect time with the reason.** vCenter accepts the login but shows no
+  session for it, and every call then fails with `NotAuthenticated`. The connection is now closed at once and
+  `doctor`, the CLI and MCP tools say the account most likely has no vSphere role and to assign one (Read-Only or
+  higher). Reported on vCenter 8.0.3; not yet reproduced on our own hardware.
+* Refused only when two signals agree: no session, **and** vCenter refuses a view of the root folder
+  (`NotAuthenticated` / `NoPermission`). An account scoped to one folder can also show no session, and still
+  connects; anything the check cannot read lets the login through.
+* **`NotAuthenticated` later on names both causes**: the session expired (retry), or the account's role was
+  removed. It no longer says "verify connectivity and credentials".
+* **Every CLI command prints one line for a vSphere fault.** `summary` (and any other command) printed a raw
+  traceback for faults other than a failed login; they now print the fault's message and what to check.
+* **`attention` never reports OK for targets it could not read** (computed by vmware-monitor): any unread target
+  makes the overall status at least WARN, none read makes it CRITICAL, and the console and HTML say how many were
+  not read. A role-less target is listed as unreachable with reason `NoVSphereRoleError`.
+
+## Unreleased — OVA deploy honours `network_name`
+
+* **`deploy_vm_from_ova` / `deploy ova --network` now attach the NICs to the network you name.** The import spec
+  carried no network mapping, so the argument had no effect and each NIC landed on whatever network the OVF
+  descriptor named. Every network the OVF declares is now mapped to the named port group (standard or distributed).
+  A name that matches no network, or more than one (a standard and a distributed port group can share a name), is
+  refused before anything is imported, with the available names in the error. An OVF descriptor the server cannot
+  parse is refused the same way. Found in the 2026-10-16 pre-release review.
+
 ## v2.3.0 — calls on one target run side by side; `get_access_info`
 
 Needs vmware-policy 1.22.0.

{vmware_aiops-2.3.0 → vmware_aiops-2.3.1}/openclaw.plugin.json

@@ -11,7 +11,7 @@
       "command": "uvx",
       "args": [
         "--from",
-        "vmware-aiops==2.3.0",
+        "vmware-aiops==2.3.1",
         "vmware-aiops-mcp"
       ]
     }

{vmware_aiops-2.3.0 → vmware_aiops-2.3.1}/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zw008/vmware-aiops",
-  "version": "2.3.0",
+  "version": "2.3.1",
   "description": "AI-powered VMware vCenter/ESXi VM lifecycle and deployment with 61 MCP tools.",
   "private": true,
   "license": "MIT",

{vmware_aiops-2.3.0 → vmware_aiops-2.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "vmware-aiops"
-version = "2.3.0"
+version = "2.3.1"
 description = "VMware vCenter/ESXi AI-powered VM lifecycle and deployment tool"
 readme = "README.md"
 license = "MIT"
@@ -19,11 +19,11 @@ dependencies = [
     "httpx>=0.27,<1.0",
     "python-dotenv>=1.0,<2.0",
     "mcp[cli]>=1.28,<2.0",
-    "vmware-policy>=1.22.0,<2.0",
+    "vmware-policy>=1.23.0,<2.0",
     # Read-only cluster-health triage (summary + HTML snapshot) is owned by
     # vmware-monitor; AIops delegates to it so a conversation with the AIops
     # entry point can produce the same report without duplicating the code.
-    "vmware-monitor>=2.0.0,<3.0",
+    "vmware-monitor>=2.3.1,<3.0",  # attention status floor + role-less login (AIops#47)
 ]
 
 

{vmware_aiops-2.3.0 → vmware_aiops-2.3.1}/server.json

@@ -7,12 +7,12 @@
     "url": "https://github.com/vmware-skills/VMware-AIops",
     "source": "github"
   },
-  "version": "2.3.0",
+  "version": "2.3.1",
   "packages": [
     {
       "registryType": "pypi",
       "identifier": "vmware-aiops",
-      "version": "2.3.0",
+      "version": "2.3.1",
       "runtimeHint": "uvx",
       "packageArguments": [
         {

{vmware_aiops-2.3.0 → vmware_aiops-2.3.1}/skills/vmware-aiops/SKILL.md

@@ -63,7 +63,7 @@ Read before connecting an agent. Per-tool inventory: `references/capabilities.md
 ## Quick Install
 
 ```bash
-uv tool install vmware-aiops==2.3.0
+uv tool install vmware-aiops==2.3.1
 vmware-aiops doctor
 vmware-aiops hub status   # see which family members are installed
 ```
@@ -285,11 +285,10 @@ Use `run_vm_guest_command_with_output` instead of `run_vm_guest_command` — it
 Large OVA files (>10GB) may exceed the default 120s timeout. The upload happens via HTTP NFC lease — ensure network between the machine running vmware-aiops and ESXi is stable.
 
 ### Snapshot delete is slow / "still running after Ns"
-Deleting an old or large snapshot consolidates its delta disk into the parent — the slowest write
-operation, often several minutes. `vm snapshot-delete` waits up to 30 min by default; if it still
-returns a "still running, NOT failed" message with a task id, the delete did **not** fail — poll it with
-`vm task-status <task-id>`. Do not re-issue the delete or hand-roll polling. For very large snapshots,
-prefer `vm snapshot-delete <name> --name <snap> --no-wait` to get the task id immediately and poll.
+Deleting a large snapshot consolidates its delta disk, often for minutes. `vm snapshot-delete` waits
+up to 30 min; a "still running, NOT failed" message with a task id means the delete did **not** fail —
+poll `vm task-status <task-id>`; do not re-issue it. For large ones, use
+`vm snapshot-delete <name> --name <snap> --no-wait` and poll.
 
 ### Plan apply fails mid-way
 Run `vmware-aiops plan list` to see failed plan status. Ask user if they want to rollback with `rollback_vm_plan`. Irreversible steps (delete_vm) are skipped during rollback.
@@ -298,10 +297,13 @@ Run `vmware-aiops plan list` to see failed plan status. Ask user if they want to
 1. Verify target is reachable: `vmware-aiops doctor`
 2. For self-signed certs: set `verify_ssl: false` in config.yaml (lab environments only)
 
+### Every command fails with "session is not authenticated"
+The account has no vSphere role. Assign one (Read-Only or higher) on the vCenter root folder; `vmware-aiops doctor` reports this case by name.
+
 ## Setup
 
 ```bash
-uv tool install vmware-aiops==2.3.0
+uv tool install vmware-aiops==2.3.1
 mkdir -p ~/.vmware-aiops
 vmware-aiops init  # generates config.yaml and .env templates
 chmod 600 ~/.vmware-aiops/.env

{vmware_aiops-2.3.0 → vmware_aiops-2.3.1}/skills/vmware-aiops/references/setup-guide.md

@@ -6,13 +6,13 @@ All install methods fetch from the same source: [github.com/vmware-skills/VMware
 
 ```bash
 # Via PyPI (recommended for version pinning)
-uv tool install vmware-aiops==2.3.0
+uv tool install vmware-aiops==2.3.1
 
 # Via Skills.sh (fetches from GitHub)
-npx skills add vmware-skills/VMware-AIops#v2.3.0
+npx skills add vmware-skills/VMware-AIops#v2.3.1
 
 # Via ClawHub (fetches from ClawHub registry snapshot of GitHub)
-clawhub install @zw008/vmware-aiops --version 2.3.0
+clawhub install @zw008/vmware-aiops --version 2.3.1
 ```
 
 ### Claude Code
@@ -35,7 +35,7 @@ claude mcp add vmware-aiops -- vmware-aiops mcp
 
 ```bash
 # 1. Install from PyPI (source: github.com/vmware-skills/VMware-AIops)
-uv tool install vmware-aiops==2.3.0
+uv tool install vmware-aiops==2.3.1
 
 # 2. Verify installation source
 vmware-aiops --version  # confirms installed version
@@ -73,7 +73,7 @@ The `vmware-aiops` package installs a Python CLI binary and its dependencies (py
 ## Development Install
 
 ```bash
-git clone --branch v2.3.0 https://github.com/vmware-skills/VMware-AIops.git
+git clone --branch v2.3.1 https://github.com/vmware-skills/VMware-AIops.git
 cd VMware-AIops
 uv venv && source .venv/bin/activate
 # --no-sources: pyproject's [tool.uv.sources] points vmware-monitor at a sibling
@@ -226,6 +226,13 @@ vmware-aiops mcp --transport https --host 0.0.0.0 --port 8443 \
 - Behind a reverse proxy that terminates TLS (Nginx, HAProxy) on the same machine, use
   `--transport http --host 127.0.0.1 --public-name mcp.example.com` (the names the proxy forwards in `Host`), and
   have the proxy pass the `Authorization` header through.
+- Behind a load balancer or gateway on another machine, keep `--transport https` (a self-signed certificate is
+  fine: the balancer is the client that has to trust it), list in `--public-name` the host name the balancer sends
+  as `Host`, and have it forward `Authorization`. Point its health probe at `GET /healthz`: it needs no token, returns
+  only `{"status": "ok"}` and accepts any `Host` (vmware-policy ≥ 1.23.0). Every other path still needs the token.
+- Correlation: each audit row stores the caller's `traceparent` trace-id, else its `X-Request-ID` /
+  `X-Correlation-ID`. Have the agent platform send one, and `vmware-audit log --correlation-id ID` lists the calls
+  behind one platform request.
 - `vmware-audit token list` / `token revoke NAME` manage callers; a revoked token is refused from its next request.
   Replace a leaked token under a new name.
 - The server will not start without at least one token, and checks before it binds that unauthenticated requests

{vmware_aiops-2.3.0 → vmware_aiops-2.3.1}/tests/eval/regression/test_atexit_handlers_do_not_accumulate.py

@@ -20,8 +20,9 @@ that registered its own handler would pass with the production one deleted.
 from __future__ import annotations
 
 import gc
+import itertools
 import weakref
-from unittest.mock import MagicMock, patch
+from unittest.mock import MagicMock, PropertyMock, patch
 
 import pytest
 
@@ -44,9 +45,13 @@ def _target(name: str = "vcenter-prod") -> TargetConfig:
 
 
 def _dead_si(*_a, **_kw):
-    """An SI whose liveness probe says dead, so the next connect() evicts it."""
+    """An SI that is alive at login and dead from then on, so the next connect()
+    evicts it. Dead from the start would be refused at login as a role-less
+    account (AIops#47), which is a different path."""
     si = MagicMock()
-    si.content.sessionManager.currentSession = None
+    type(si.content.sessionManager).currentSession = PropertyMock(
+        side_effect=itertools.chain([object()], itertools.repeat(None))
+    )
     return si
 
 

{vmware_aiops-2.3.0 → vmware_aiops-2.3.1}/tests/eval/regression/test_deploy_correctness.py

@@ -235,6 +235,11 @@ def test_deploy_ova_maps_device_urls_by_importkey_out_of_order() -> None:
 
     content = MagicMock()
     content.ovfManager.CreateImportSpec.return_value = import_spec_result
+    # A descriptor that parses cleanly and declares no networks (mapping is
+    # covered in test_ova_network_mapping.py).
+    content.ovfManager.ParseDescriptor.return_value = SimpleNamespace(
+        error=None, warning=None, network=[]
+    )
     si = MagicMock()
     si.RetrieveContent.return_value = content
 

vmware_aiops-2.3.1/tests/eval/regression/test_login_without_vsphere_role.py

@@ -0,0 +1,225 @@
+"""A login that works but has no vSphere role must say so (AIops#47).
+
+Reported against vCenter 8.0.3, not reproduced here (the lab is down): an SSO
+account with no vSphere role logs in, ``sessionManager.currentSession`` reads
+``None``, and every inventory call then fails with ``vim.fault.NotAuthenticated``.
+``doctor`` passed, the CLI said "verify connectivity and credentials", and
+``vmware-aiops summary`` printed a raw traceback for the fault.
+
+Driven through the real ``ConnectionManager`` with only ``SmartConnect`` and
+``Disconnect`` replaced, so the production factory, pool and cleanup all run.
+The attention roll-up is vmware-monitor's code and is tested there.
+"""
+
+from __future__ import annotations
+
+import io
+from unittest.mock import MagicMock, PropertyMock, patch
+
+import pytest
+import typer
+from pyVmomi import vim
+from rich.console import Console
+
+from vmware_aiops import connection as conn_mod
+from vmware_aiops.config import AppConfig, TargetConfig
+from vmware_aiops.connection import ConnectionManager, NoVSphereRoleError
+
+pytestmark = pytest.mark.unit
+
+ROLE = "no vSphere role"
+
+
+@pytest.fixture(autouse=True)
+def _password(monkeypatch: pytest.MonkeyPatch) -> None:
+    for name in ("VC1", "VC2"):
+        monkeypatch.setenv(f"VMWARE_{name}_PASSWORD", "test-only")
+        monkeypatch.setenv(f"VMWARE_AIOPS_{name}_PASSWORD", "test-only")
+
+
+def _config(*names: str) -> AppConfig:
+    return AppConfig(
+        targets=tuple(
+            TargetConfig(name=n, host=f"{n}.example.com", config_username="svc") for n in names
+        )
+    )
+
+
+def _si(has_session: bool, *, root_readable: bool = False) -> MagicMock:
+    """A login as vCenter answers it.
+
+    No role (AIops#47) takes both signals: ``currentSession`` reads ``None`` and
+    a container view on the root folder is refused with NotAuthenticated.
+    ``root_readable`` is the scoped account (one folder, or Supervisor namespace
+    permissions only): no session either, but the root view opens.
+    """
+    si = MagicMock()
+    si.content.sessionManager.currentSession = object() if has_session else None
+    if not has_session and not root_readable:
+        si.content.viewManager.CreateContainerView.side_effect = vim.fault.NotAuthenticated()
+    return si
+
+
+def test_role_less_login_is_refused_closed_and_not_cached() -> None:
+    mgr = ConnectionManager(_config("vc1"))
+    si = _si(False)
+    with (
+        patch("pyVim.connect.SmartConnect", return_value=si),
+        patch("pyVim.connect.Disconnect") as disconnect,
+        pytest.raises(NoVSphereRoleError) as err,
+    ):
+        mgr.connect("vc1")
+
+    msg = str(err.value)
+    assert ROLE in msg and "Read-Only" in msg and "'vc1'" in msg
+    assert "vmware-aiops doctor" in msg
+    disconnect.assert_called_once_with(si)  # the login is logged out
+    assert id(si) not in conn_mod._SI_ATEXIT  # its atexit cleanup taken back
+    assert id(si) not in conn_mod._SI_VERIFY_SSL  # its side store cleared
+    assert mgr.list_connected() == []  # and the pool kept nothing
+
+
+def test_a_normal_login_is_unaffected() -> None:
+    mgr = ConnectionManager(_config("vc1"))
+    si = _si(True)
+    with (
+        patch("pyVim.connect.SmartConnect", return_value=si),
+        patch("pyVim.connect.Disconnect") as disconnect,
+    ):
+        assert mgr.connect("vc1") is si
+        disconnect.assert_not_called()
+        assert mgr.list_connected() == ["vc1"]
+        mgr.disconnect_all()
+
+
+def test_a_scoped_account_without_a_session_still_connects() -> None:
+    """``currentSession`` alone is not a verdict: a readable root view lets it through."""
+    mgr = ConnectionManager(_config("vc1"))
+    si = _si(False, root_readable=True)
+    with (
+        patch("pyVim.connect.SmartConnect", return_value=si),
+        patch("pyVim.connect.Disconnect") as disconnect,
+    ):
+        assert mgr.connect("vc1") is si  # no NoVSphereRoleError
+        disconnect.assert_not_called()
+        assert mgr.list_connected() == ["vc1"]  # cached like any session
+        view = si.content.viewManager.CreateContainerView.return_value
+        view.Destroy.assert_called_once_with()  # the probe leaves no view behind
+        mgr.disconnect_all()
+
+
+def test_an_unreadable_session_is_not_a_verdict() -> None:
+    """Unknown is not "no role": a probe that raises lets the login through."""
+    mgr = ConnectionManager(_config("vc1"))
+    si = MagicMock()
+    type(si.content.sessionManager).currentSession = PropertyMock(side_effect=RuntimeError)
+    with patch("pyVim.connect.SmartConnect", return_value=si), patch("pyVim.connect.Disconnect"):
+        assert ConnectionManager._create_connection(mgr._config.get_target("vc1")) is si
+    conn_mod._close_session(si)
+
+
+def test_connect_all_names_the_role_case() -> None:
+    mgr = ConnectionManager(_config("vc1", "vc2"))
+    sis = {"vc1.example.com": _si(True), "vc2.example.com": _si(False)}
+    with (
+        patch("pyVim.connect.SmartConnect", side_effect=lambda host, **_: sis[host]),
+        patch("pyVim.connect.Disconnect"),
+    ):
+        sessions, unreachable = mgr.connect_all()
+        mgr.disconnect_all()
+    assert [n for n, _ in sessions] == ["vc1"]
+    assert unreachable == [("vc2", "NoVSphereRoleError")]
+
+
+def test_doctor_auth_row_fails_with_the_role_message(monkeypatch: pytest.MonkeyPatch) -> None:
+    from vmware_aiops import doctor as doc
+
+    monkeypatch.setattr(type(doc.resolve_config_path()), "exists", lambda self: True)
+    monkeypatch.setattr("vmware_aiops.config.load_config", lambda: _config("vc1"))
+    with (
+        patch("pyVim.connect.SmartConnect", return_value=_si(False)),
+        patch("pyVim.connect.Disconnect"),
+    ):
+        ok, row = doc._check_auth()
+    assert ok is False
+    assert ROLE in row and "vc1 ✗" in row
+
+
+def _cli_output(monkeypatch: pytest.MonkeyPatch, exc: Exception) -> str:
+    from vmware_aiops.cli import _common
+
+    buf = io.StringIO()
+    monkeypatch.setattr(_common, "console", Console(file=buf, width=2000))
+
+    @_common.cli_errors
+    def cmd() -> None:
+        raise exc
+
+    with pytest.raises(typer.Exit):
+        cmd()
+    return buf.getvalue()
+
+
+def test_cli_prints_the_role_message_intact(monkeypatch: pytest.MonkeyPatch) -> None:
+    msg = conn_mod.no_role_message("vc1", "vmware-aiops")
+    out = _cli_output(monkeypatch, NoVSphereRoleError(msg))
+    assert msg in out
+
+
+def test_cli_not_authenticated_names_both_causes(monkeypatch: pytest.MonkeyPatch) -> None:
+    fault = vim.fault.NotAuthenticated(msg="The session is not authenticated.")
+    out = _cli_output(monkeypatch, fault)
+    assert "expired" in out and "vSphere role" in out
+    assert "verify connectivity and credentials" not in out
+
+
+def test_cli_any_other_fault_is_one_line_not_a_traceback(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Issue item 5: `summary` printed a traceback for a vSphere fault."""
+    out = _cli_output(monkeypatch, vim.fault.NoPermission(msg="Permission to perform this"))
+    assert "vSphere API fault: Permission to perform this" in out
+    assert "vSphere role" in out
+
+
+def test_summary_goes_through_cli_errors(monkeypatch: pytest.MonkeyPatch) -> None:
+    """The command the issue named, end to end through its real decorators."""
+    from vmware_aiops.cli import _common, summary
+
+    buf = io.StringIO()
+    monkeypatch.setattr(_common, "console", Console(file=buf, width=2000))
+
+    def _raise(*_a, **_kw):
+        raise vim.fault.NotAuthenticated(msg="The session is not authenticated.")
+
+    monkeypatch.setattr(summary, "_get_connection", _raise)
+    with pytest.raises(typer.Exit):
+        summary.cluster_summary_cmd(
+            cluster=None, no_vms=False, top=10, html=False, html_path=None, target=None, config=None
+        )
+    assert "vSphere role" in buf.getvalue()
+
+
+def _mcp_payload(exc: Exception, shape: str = "dict"):
+    from vmware_aiops.mcp_server._shared import tool_errors
+
+    @tool_errors(shape)
+    def tool():
+        raise exc
+
+    return tool()
+
+
+def test_mcp_passes_the_whole_role_message() -> None:
+    msg = conn_mod.no_role_message("a-rather-long-target-name-in-config", "vmware-aiops")
+    payload = _mcp_payload(NoVSphereRoleError(msg))
+    assert payload["error"] == msg  # not cut, not reduced to a class name
+    assert "credentials" not in payload["hint"]
+
+
+def test_mcp_not_authenticated_names_both_causes() -> None:
+    payload = _mcp_payload(vim.fault.NotAuthenticated(msg="The session is not authenticated."))
+    assert "expired" in payload["error"] and "vSphere role" in payload["error"]
+    assert "credentials" not in payload["hint"]
+    text = _mcp_payload(vim.fault.NotAuthenticated(), shape="str")
+    assert "vSphere role" in text and "verify connectivity and credentials" not in text