vmware-storage 2.4.0__tar.gz → 2.4.2__tar.gz

{vmware_storage-2.4.0 → vmware_storage-2.4.2}/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "vmware-storage",
   "displayName": "VMware Storage",
-  "version": "2.4.0",
+  "version": "2.4.2",
   "description": "VMware vSphere storage with 15 MCP tools: datastores, iSCSI, vSAN, FC multipath.",
   "author": {
     "name": "Wei Zhou",

{vmware_storage-2.4.0 → vmware_storage-2.4.2}/.mcp.json

@@ -5,7 +5,7 @@
       "command": "uvx",
       "args": [
         "--from",
-        "vmware-storage==2.4.0",
+        "vmware-storage==2.4.2",
         "vmware-storage-mcp"
       ]
     }

{vmware_storage-2.4.0 → vmware_storage-2.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: vmware-storage
-Version: 2.4.0
+Version: 2.4.2
 Summary: VMware vSphere storage management: datastores, iSCSI, vSAN. Domain-focused MCP skill.
 Project-URL: Homepage, https://github.com/vmware-skills/VMware-Storage
 Project-URL: Repository, https://github.com/vmware-skills/VMware-Storage
@@ -10,7 +10,7 @@ Author-email: Wei Zhou <wei-wz.zhou@broadcom.com>
 License-Expression: MIT
 License-File: LICENSE
 Requires-Python: >=3.10
-Requires-Dist: mcp[cli]<2.0,>=1.28
+Requires-Dist: mcp[cli]<2.0,>=1.30
 Requires-Dist: pyaml<27.0,>=24.0
 Requires-Dist: python-dotenv<2.0,>=1.0
 Requires-Dist: pyvmomi<10.0,>=8.0.3.0

{vmware_storage-2.4.0 → vmware_storage-2.4.2}/README-CN.md

@@ -115,7 +115,7 @@ targets:
 - `list_all_datastores` — 列出所有数据存储，含容量、使用率、可达性
 - `browse_datastore` — 浏览数据存储目录下的文件（支持 glob 过滤）
 - `scan_datastore_images` — 扫描可部署镜像（OVA、ISO、OVF、VMDK）
-- `list_cached_images` — 查询本地镜像注册表（支持按类型/数据存储过滤）
+- `list_cached_images` — 查询本地镜像注册表（支持按类型/数据存储/target 过滤）
 
 **iSCSI**
 - `enable_iscsi` — 在 ESXi 主机上启用软件 iSCSI 适配器

{vmware_storage-2.4.0 → vmware_storage-2.4.2}/RELEASE_NOTES.md

@@ -1,3 +1,31 @@
+## v2.4.2 — a login refused for lack of a vSphere role says so (2026-10-19)
+
+* **A login vCenter refuses with `NoPermission` gets the role error, not the raw fault.** Found on a vCenter 8.0.3
+  lab (follow-up to AIops#47): for an SSO account with no permission anywhere, vCenter refuses the login itself
+  (`System.View` on the root folder), so the post-login no-role check never ran and `doctor` and every tool showed
+  the raw fault with a connectivity hint. It now raises the no-role error: the "no vSphere role / Global
+  Permissions" remedy only for a vCenter target and `System.View`; an ESXi target or another privilege gets a
+  neutral text naming the (sanitized) privilege. A wrong password (`InvalidLogin`) is unchanged. Same text as
+  vmware-monitor.
+
+## Unreleased — follow-ups to the 2.4.1 review
+
+* **`list_cached_images(target=...)`** returns one target's cached images; without it, nothing changes.
+* The cache write takes a lock across processes, so a CLI and an MCP scan at the same time keep both sides' rows; a
+  lock held for more than 10 s is reported in `cache_note` with the lock file's path.
+
+## v2.4.1 — fixes from real-hardware testing (2026-10-17)
+
+* **`list_cached_images` returns what was scanned.** Nothing ever wrote the cache it reads, so it was always empty.
+  `scan_datastore_images` now replaces that target's entries for the scanned datastore folder; entries carry
+  `target`, so `datastore1` on two hosts stays apart. The cache file is written atomically under a lock; a cache that
+  cannot be read or written is reported in `cache_note` and does not fail the scan.
+* **`browse_datastore` / `scan_datastore_images` return well-formed `ds_path`s** for both ESXi and vCenter folder
+  paths (an ESXi browse produced `[datastore1] backupX.iso`). A leading `/` is still refused; the error now names the
+  corrected path, and vmware-aiops follows the same rule.
+* Error hints: `doctor` is suggested for connection and credential problems, not for an invalid path or an unknown
+  target; the unknown-target error names `target=` with the CLI flag in brackets.
+
 ## v2.4.0 — roles for network callers (HLD §18)
 
 * Declares the role metadata vmware-policy ≥ 1.24.0 needs to apply **roles** to this server over HTTPS

{vmware_storage-2.4.0 → vmware_storage-2.4.2}/openclaw.plugin.json

@@ -11,7 +11,7 @@
       "command": "uvx",
       "args": [
         "--from",
-        "vmware-storage==2.4.0",
+        "vmware-storage==2.4.2",
         "vmware-storage-mcp"
       ]
     }

{vmware_storage-2.4.0 → vmware_storage-2.4.2}/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zw008/vmware-storage",
-  "version": "2.4.0",
+  "version": "2.4.2",
   "description": "VMware vSphere storage with 15 MCP tools: datastores, iSCSI, vSAN, FC multipath.",
   "private": true,
   "license": "MIT",

{vmware_storage-2.4.0 → vmware_storage-2.4.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "vmware-storage"
-version = "2.4.0"
+version = "2.4.2"
 description = "VMware vSphere storage management: datastores, iSCSI, vSAN. Domain-focused MCP skill."
 readme = "README.md"
 license = "MIT"
@@ -16,7 +16,7 @@ dependencies = [
     "typer>=0.12,<1.0",
     "rich>=13.0,<15.0",
     "python-dotenv>=1.0,<2.0",
-    "mcp[cli]>=1.28,<2.0",
+    "mcp[cli]>=1.30,<2.0",
     "vmware-policy>=1.23.0,<2.0",
 ]
 

{vmware_storage-2.4.0 → vmware_storage-2.4.2}/server.json

@@ -7,12 +7,12 @@
     "url": "https://github.com/vmware-skills/VMware-Storage",
     "source": "github"
   },
-  "version": "2.4.0",
+  "version": "2.4.2",
   "packages": [
     {
       "registryType": "pypi",
       "identifier": "vmware-storage",
-      "version": "2.4.0",
+      "version": "2.4.2",
       "runtimeHint": "uvx",
       "packageArguments": [
         {

{vmware_storage-2.4.0 → vmware_storage-2.4.2}/skills/vmware-storage/SKILL.md

@@ -40,7 +40,7 @@ VMware vSphere storage management — 15 MCP tools for datastores, iSCSI, vSAN,
 ## Quick Install
 
 ```bash
-uv tool install vmware-storage==2.4.0
+uv tool install vmware-storage==2.4.2
 vmware-storage init      # guided setup: writes config + .env (chmod 600, password grep-safe), then verifies
 vmware-storage doctor
 ```
@@ -103,7 +103,7 @@ vmware-storage doctor
 4. `datastore browse <ds> --pattern "*.iso"` for ad-hoc searches; pattern is glob, not regex
 5. **If datastore not found**: name is case-sensitive. `datastore list --target <vc>` to verify exact spelling.
 
-For filtered queries against the cache: use `list_cached_images` MCP tool with `image_type` and `datastore` parameters — avoids re-scanning.
+For filtered queries against the cache: use `list_cached_images` MCP tool with `image_type`, `datastore` and `target` parameters — avoids re-scanning.
 
 ### vSAN Health Assessment
 
@@ -158,7 +158,7 @@ The four Datastore read tools return the family list envelope — `{items, retur
 | Datastore | `list_all_datastores` | Read | List datastores with capacity, usage %, VM count |
 | | `browse_datastore` | Read | Browse files with optional path and glob pattern |
 | | `scan_datastore_images` | Read | Find OVA/ISO/OVF/VMDK in a datastore |
-| | `list_cached_images` | Read | Query local image registry with type/datastore filters |
+| | `list_cached_images` | Read | Query local image registry with type/datastore/target filters |
 | iSCSI | `get_iscsi_status` | Read | Show adapter status, HBA device, IQN, send targets |
 | | `enable_iscsi` | Write | Enable software iSCSI adapter on a host |
 | | `add_iscsi_target` | Write | Add iSCSI send target (IP + port) and rescan |
@@ -271,7 +271,7 @@ Corporate TLS proxies inject certificates that uv's bundled CA store doesn't tru
 ## Setup
 
 ```bash
-uv tool install vmware-storage==2.4.0
+uv tool install vmware-storage==2.4.2
 mkdir -p ~/.vmware-storage
 cp config.example.yaml ~/.vmware-storage/config.yaml
 # Edit config.yaml with your vCenter/ESXi targets

{vmware_storage-2.4.0 → vmware_storage-2.4.2}/skills/vmware-storage/references/capabilities.md

@@ -26,7 +26,7 @@ Each operation is classified by autonomy level per the Enterprise Harness Engine
 | `list_all_datastores` | List datastores with capacity, usage %, VM count | `target` (string, optional), `limit` (int, optional; omit for all) | Low | No |
 | `browse_datastore` | Browse files with optional path and glob pattern | `datastore_name` (string, **required**), `path` (string, optional), `pattern` (string, optional), `target` (string, optional) | Low | No |
 | `scan_datastore_images` | Find OVA/ISO/OVF/VMDK deployable images in a datastore | `datastore_name` (string, **required**), `target` (string, optional) | Low | No |
-| `list_cached_images` | Query local image registry with type/datastore filters | `image_type` (string, optional), `datastore` (string, optional) | Low | No |
+| `list_cached_images` | Query local image registry with type/datastore/target filters | `image_type` (string, optional), `datastore` (string, optional), `target` (string, optional) | Low | No |
 
 **List envelope**: all four return `{items, returned, limit, total, truncated, hint}` instead of a bare array, so an agent can tell a complete answer from a first page rather than inferring it (VMware-AIops issue #31). Each enumerates its collection in full — a PropertyCollector walk, a datastore browse task, or the on-disk registry — so `total` is the real count and `truncated` is always `false`. On error the tools return `{error, hint}` (a dict, not a one-element list).
 

{vmware_storage-2.4.0 → vmware_storage-2.4.2}/skills/vmware-storage/references/setup-guide.md

@@ -13,19 +13,19 @@ Complete setup and security guide for `vmware-storage`.
 ### Via uv (recommended)
 
 ```bash
-uv tool install vmware-storage==2.4.0
+uv tool install vmware-storage==2.4.2
 ```
 
 ### Via pip
 
 ```bash
-pip install vmware-storage==2.4.0
+pip install vmware-storage==2.4.2
 ```
 
 ### From source
 
 ```bash
-git clone --branch v2.4.0 https://github.com/vmware-skills/VMware-Storage.git
+git clone --branch v2.4.2 https://github.com/vmware-skills/VMware-Storage.git
 cd VMware-Storage
 pip install -e .
 ```

vmware_storage-2.4.2/tests/eval/regression/test_browse_ds_path_join.py

@@ -0,0 +1,79 @@
+"""browse_datastore must return a ds_path that deploy/attach tools can use.
+
+Regression source: real ESXi 8 host (home-esxi, 2026-10-17). The browse task
+reports each folder's ``folderPath`` with no trailing separator —
+``"[datastore1]"`` for the root, ``"[datastore1] backup"`` for a folder —
+and the old code glued the file name straight on, producing
+``"[datastore1] backupVMware-VCSA.iso"`` and ``"[datastore1]Hermers - TT"``.
+Agents pass that string into deploy_vm_from_ova / attach_iso_to_vm, so a
+malformed path breaks the very flow the browse exists for. The earlier tests
+mocked ``"[ds1] images/"`` (trailing slash), the one shape that hid the bug.
+"""
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+import pytest
+from pyVmomi import vim
+
+from vmware_storage.ops import datastore_browser as dsb
+
+
+@pytest.mark.unit
+@pytest.mark.parametrize(
+    ("folder", "name", "expected"),
+    [
+        # Root, as ESXi reports it: no space after the bracket.
+        ("[datastore1]", "Hermers - TT", "[datastore1] Hermers - TT"),
+        ("[datastore1]", "x.iso", "[datastore1] x.iso"),
+        # Root, as vCenter reports it: trailing space.
+        ("[datastore1] ", "x.iso", "[datastore1] x.iso"),
+        # Folder without a trailing slash (ESXi).
+        ("[datastore1] backup", "x.iso", "[datastore1] backup/x.iso"),
+        (
+            "[datastore1] Hermers - TT",
+            "Hermers - TT.vmdk",
+            "[datastore1] Hermers - TT/Hermers - TT.vmdk",
+        ),
+        ("[datastore1] a/b", "x.iso", "[datastore1] a/b/x.iso"),
+        # Folder with a trailing slash (vCenter) — must not double it.
+        ("[datastore1] backup/", "x.iso", "[datastore1] backup/x.iso"),
+    ],
+)
+def test_join_ds_path(folder, name, expected):
+    assert dsb._join_ds_path(folder, name) == expected
+
+
+@pytest.mark.unit
+def test_browse_root_returns_well_formed_paths_for_every_folder(monkeypatch):
+    """Root browse is recursive: subfolder rows come back too, each well formed."""
+    def _file(path):
+        return SimpleNamespace(path=path, fileSize=1024 * 1024, modification="2026-10-17")
+
+    results = [
+        SimpleNamespace(folderPath="[datastore1]", file=[_file("backup")]),
+        SimpleNamespace(folderPath="[datastore1] backup", file=[_file("x.iso")]),
+    ]
+    seen = {}
+
+    def fake_search(datastorePath, searchSpec):  # noqa: N803 — pyVmomi API names
+        seen["path"] = datastorePath
+        return SimpleNamespace(
+            info=SimpleNamespace(state=vim.TaskInfo.State.success, result=results, error=None)
+        )
+
+    monkeypatch.setattr(
+        dsb,
+        "find_datastore_by_name",
+        lambda si, name: SimpleNamespace(
+            browser=SimpleNamespace(SearchDatastoreSubFolders_Task=fake_search)
+        ),
+    )
+
+    rows = dsb.browse_datastore(object(), "datastore1")["items"]
+
+    assert seen["path"] == "[datastore1]"
+    assert {r["name"]: r["ds_path"] for r in rows} == {
+        "backup": "[datastore1] backup",
+        "x.iso": "[datastore1] backup/x.iso",
+    }

vmware_storage-2.4.2/tests/eval/regression/test_browse_sees_every_file.py

@@ -0,0 +1,70 @@
+"""browse_datastore must see every file, and treat a leading '/' one way.
+
+Real hardware, 2026-10-17: vmware-aiops' search spec listed only IsoImageQuery,
+VmDiskQuery and FolderQuery under a comment saying "include all file types".
+A DatastoreBrowser query is a filter, not a hint -- with those three, .ova /
+.ovf / .vmx / .log files are never returned. On the lab vCenter it found 0 of
+the 2 OVAs on 'datastore1 (1)' that vmware-storage (which also passes the
+generic Query) found, so scan_all_datastore_images could not do the one job its
+description gives it: finding an OVA for deploy_vm_from_ova.
+
+The twin also drifted on a leading slash: vmware-aiops passed '/vcsa8' through,
+vmware-storage refused it as "absolute" (its 1.5.35 hardening). Both now refuse
+it, and the error names the corrected path.
+"""
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+import pytest
+from pyVmomi import vim
+
+from vmware_storage.ops import datastore_browser as dsb
+
+
+def _browse(monkeypatch, path=""):
+    seen: dict = {}
+
+    def fake_search(datastorePath, searchSpec):  # noqa: N803 -- pyVmomi API names
+        seen["path"] = datastorePath
+        seen["spec"] = searchSpec
+        return SimpleNamespace(
+            info=SimpleNamespace(state=vim.TaskInfo.State.success, result=[], error=None)
+        )
+
+    monkeypatch.setattr(
+        dsb,
+        "find_datastore_by_name",
+        lambda si, name: SimpleNamespace(
+            browser=SimpleNamespace(SearchDatastoreSubFolders_Task=fake_search)
+        ),
+    )
+    dsb.browse_datastore(object(), "datastore1", path=path, pattern="*.ova")
+    return seen
+
+
+@pytest.mark.unit
+def test_search_spec_includes_the_generic_file_query(monkeypatch) -> None:
+    spec = _browse(monkeypatch)["spec"]
+    # Exact type: every specific query subclasses Query, so isinstance would pass
+    # for the three that hid the OVAs.
+    assert any(type(q) is vim.host.DatastoreBrowser.Query for q in spec.query)
+
+
+@pytest.mark.unit
+def test_relative_path_is_joined_under_the_datastore(monkeypatch) -> None:
+    assert _browse(monkeypatch, "vcsa8")["path"] == "[datastore1] vcsa8"
+
+
+@pytest.mark.unit
+@pytest.mark.parametrize("path", ["/vcsa8", "//vcsa8"])
+def test_leading_slash_is_refused_with_the_fix(monkeypatch, path) -> None:
+    with pytest.raises(ValueError, match="path='vcsa8'"):
+        _browse(monkeypatch, path)
+
+
+@pytest.mark.unit
+@pytest.mark.parametrize("path", ["../other", "a/../../b", "x\x00y", "\\\\server\\share", "/"])
+def test_traversal_and_odd_paths_are_refused(monkeypatch, path) -> None:
+    with pytest.raises(ValueError, match="datastore-relative"):
+        _browse(monkeypatch, path)

vmware_storage-2.4.2/tests/eval/regression/test_error_hints_fit_the_surface.py

@@ -0,0 +1,60 @@
+"""Error hints must fit the error, and the surface that shows them.
+
+Real hardware, 2026-10-17: every MCP error carried "Run 'vmware-storage doctor'
+to verify connectivity." -- also for an invalid path or a datastore name that
+does not resolve, where the message already says what to change. And the
+unknown-target error said "Pass --target", a CLI flag; the MCP name is the
+``target`` parameter.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from vmware_storage.config import AppConfig
+from vmware_storage.mcp_server import server
+
+
+def _unknown_target():
+    from vmware_storage.config import UnknownTargetError
+
+    return UnknownTargetError("Target 'x' not found.")
+
+
+@pytest.mark.unit
+@pytest.mark.parametrize("exc", [ValueError("bad"), _unknown_target()])
+def test_an_authored_request_error_does_not_send_the_agent_to_doctor(exc) -> None:
+    assert "doctor" not in server._hint_for(exc)
+
+
+@pytest.mark.unit
+@pytest.mark.parametrize("exc", [ConnectionError("x"), TimeoutError("x"), RuntimeError("x")])
+def test_connectivity_and_unplanned_errors_keep_the_doctor_hint(exc) -> None:
+    assert server._hint_for(exc) == server._DOCTOR_HINT
+
+
+@pytest.mark.unit
+def test_unknown_target_names_the_mcp_parameter() -> None:
+    with pytest.raises(KeyError) as info:
+        AppConfig(targets=()).get_target("nope")
+    assert "target=" in str(info.value)
+
+
+
+@pytest.mark.unit
+@pytest.mark.parametrize("exc", [
+    __import__("json").JSONDecodeError("Expecting value", "<html>", 0),
+    KeyError("summary.capacity"),
+    UnicodeDecodeError("utf-8", b"\xff", 0, 1, "invalid start byte"),
+])
+def test_parse_errors_and_bare_key_errors_keep_the_doctor_hint(exc) -> None:
+    """Independent review 2026-10-17: a reverse proxy answering HTML raises
+    JSONDecodeError (a ValueError), and a programming slip raises a bare KeyError;
+    neither message says what to change, so they must not be told it does."""
+    assert server._hint_for(exc) == server._DOCTOR_HINT
+
+
+@pytest.mark.unit
+def test_an_unknown_target_is_still_a_key_error() -> None:
+    """Callers catch KeyError from get_target; the subclass must not break them."""
+    assert issubclass(type(_unknown_target()), KeyError)

vmware_storage-2.4.2/tests/eval/regression/test_image_registry_cross_process.py

@@ -0,0 +1,149 @@
+"""Two processes scanning at once must not drop each other's cached images.
+
+Review 2026-10-18: the registry's read-modify-write was guarded by a
+``threading.Lock``, which only serialises one process. A CLI scan and an MCP
+server scan running side by side each read the old file, and the last
+``os.replace`` wrote the other's rows away. The atomic replace stops a reader
+seeing half a file; it does nothing for a lost update.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+import textwrap
+import time
+from pathlib import Path
+
+import pytest
+
+from vmware_storage.ops import datastore_browser as dsb
+
+_WRITERS = 4
+
+_CHILD = textwrap.dedent(
+    """
+    import sys, time
+    from pathlib import Path
+    from vmware_storage.ops import datastore_browser as dsb
+
+    reg, target = Path(sys.argv[1]), sys.argv[2]
+    dsb.IMAGE_REGISTRY_FILE = reg
+    dsb.CONFIG_DIR = reg.parent
+    real_load = dsb._load_registry
+
+    def slow_load():
+        # Widen the read-modify-write window so the race is not left to luck.
+        data = real_load()
+        time.sleep(0.3)
+        return data
+
+    dsb._load_registry = slow_load
+    (reg.parent / f"ready-{target}").touch()
+    go = reg.parent / "go"
+    deadline = time.monotonic() + 60
+    while not go.exists():
+        if time.monotonic() > deadline:
+            sys.exit("parent never said go")
+        time.sleep(0.01)
+    img = {"name": f"{target}.iso", "ds_path": f"[datastore1] {target}.iso",
+           "size_mb": 1.0, "type": "File", "modified": ""}
+    dsb._record_scan("datastore1", "", [img], target)
+    """
+)
+
+
+def _child_env() -> dict[str, str]:
+    env = dict(os.environ)
+    # The children must import exactly the code this test process imported.
+    env["PYTHONPATH"] = os.pathsep.join(p for p in sys.path if p)
+    return env
+
+
+def _run_writers(reg: Path, script: str, targets: list[str]) -> None:
+    procs = [
+        subprocess.Popen([sys.executable, "-c", script, str(reg), t], env=_child_env())
+        for t in targets
+    ]
+    try:
+        deadline = time.monotonic() + 60
+        while not all((reg.parent / f"ready-{t}").exists() for t in targets):
+            assert time.monotonic() < deadline, "writers never became ready"
+            assert all(p.poll() is None for p in procs), "a writer exited early"
+            time.sleep(0.02)
+        (reg.parent / "go").touch()
+        for p in procs:
+            assert p.wait(timeout=60) == 0
+    finally:
+        for p in procs:
+            if p.poll() is None:
+                p.kill()
+
+
+@pytest.mark.unit
+def test_concurrent_scans_in_separate_processes_keep_every_row(tmp_path) -> None:
+    reg = tmp_path / "image_registry.json"
+    targets = [f"t{i}" for i in range(_WRITERS)]
+
+    _run_writers(reg, _CHILD, targets)
+
+    rows = json.loads(reg.read_text(encoding="utf-8"))["images"]
+    assert sorted(r["target"] for r in rows) == targets
+
+
+@pytest.fixture
+def registry(tmp_path, monkeypatch):
+    path = tmp_path / "image_registry.json"
+    monkeypatch.setattr(dsb, "IMAGE_REGISTRY_FILE", path)
+    monkeypatch.setattr(dsb, "CONFIG_DIR", tmp_path)
+    return path
+
+
+def _hold_lock(reg: Path):
+    fcntl = pytest.importorskip("fcntl")
+    fh = open(reg.with_name(reg.name + ".lock"), "a+b")  # noqa: SIM115
+    fcntl.flock(fh.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
+    return fh
+
+
+_IMG = {"name": "x.iso", "ds_path": "[ds1] x.iso", "size_mb": 1.0,
+        "type": "File", "modified": ""}
+
+
+@pytest.mark.unit
+def test_a_held_lock_is_a_bounded_wait_that_names_the_lock_file(registry, monkeypatch) -> None:
+    monkeypatch.setattr(dsb, "REGISTRY_LOCK_TIMEOUT_S", 0.3, raising=False)
+    holder = _hold_lock(registry)
+    try:
+        started = time.monotonic()
+        with pytest.raises(dsb.DatastoreBrowseError, match=r"image_registry\.json\.lock"):
+            dsb._record_scan("ds1", "", [_IMG], "vc")
+        assert time.monotonic() - started < 5
+    finally:
+        holder.close()
+    assert not registry.exists(), "nothing may be written without the lock"
+
+
+@pytest.mark.unit
+def test_scan_reports_the_held_lock_in_cache_note(registry, monkeypatch) -> None:
+    monkeypatch.setattr(dsb, "REGISTRY_LOCK_TIMEOUT_S", 0.3, raising=False)
+    monkeypatch.setattr(
+        dsb, "browse_datastore",
+        lambda si, ds, path="", pattern="*": {"items": [_IMG] if pattern == "*.iso" else []},
+    )
+    holder = _hold_lock(registry)
+    try:
+        result = dsb.scan_images(object(), "ds1", target="vc")
+    finally:
+        holder.close()
+    assert [i["name"] for i in result["items"]] == ["x.iso"]
+    assert "image_registry.json.lock" in result.get("cache_note", "")
+
+
+@pytest.mark.unit
+def test_the_lock_is_released_after_a_write(registry) -> None:
+    dsb._record_scan("ds1", "", [_IMG], "vc")
+    holder = _hold_lock(registry)  # would raise BlockingIOError if still held
+    holder.close()

vmware_storage-2.4.2/tests/eval/regression/test_list_cached_images_target.py

@@ -0,0 +1,82 @@
+"""list_cached_images can answer for one target (review 2026-10-18).
+
+Rows carry ``target`` since 2026-10-17 so two hosts' "datastore1" stay apart,
+but the tool had no way to ask for one target's rows: a caller saw every
+target's images mixed together and had to filter by hand.
+"""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+
+from vmware_storage.config import AppConfig, TargetConfig
+from vmware_storage.connection import ConnectionManager
+from vmware_storage.mcp_server import server
+from vmware_storage.ops import datastore_browser as dsb
+
+_ROWS = [
+    {"target": "vc", "datastore": "datastore1", "name": "a.iso",
+     "ds_path": "[datastore1] a.iso", "size_mb": 1.0, "type": "File", "modified": ""},
+    {"target": "esx", "datastore": "datastore1", "name": "b.ova",
+     "ds_path": "[datastore1] b.ova", "size_mb": 1.0, "type": "File", "modified": ""},
+    # Written before targets were recorded: it cannot be attributed to either.
+    {"datastore": "datastore1", "name": "old.iso", "ds_path": "[datastore1] old.iso",
+     "size_mb": 1.0, "type": "File", "modified": ""},
+]
+
+
+@pytest.fixture
+def registry(tmp_path, monkeypatch):
+    path = tmp_path / "image_registry.json"
+    path.write_text(json.dumps({"images": _ROWS, "last_scan": None}), encoding="utf-8")
+    monkeypatch.setattr(dsb, "IMAGE_REGISTRY_FILE", path)
+    monkeypatch.setattr(dsb, "CONFIG_DIR", tmp_path)
+    return path
+
+
+def _with_targets(monkeypatch, *names: str) -> None:
+    cfg = AppConfig(targets=tuple(
+        TargetConfig(name=n, host=f"{n}.example.com", config_username="u") for n in names))
+    mgr = ConnectionManager(cfg)
+    monkeypatch.setattr(server, "_get_conn_mgr", lambda: mgr)
+
+
+@pytest.mark.unit
+def test_ops_filter_returns_only_that_targets_rows(registry) -> None:
+    out = dsb.list_images(target="esx")
+    assert [i["name"] for i in out["items"]] == ["b.ova"]
+    assert out["total"] == 1
+
+
+@pytest.mark.unit
+def test_ops_filter_combines_with_the_other_filters(registry) -> None:
+    assert dsb.list_images(target="vc", image_type="ova")["items"] == []
+    assert [i["name"] for i in dsb.list_images(target="vc", datastore="datastore1")["items"]] == [
+        "a.iso"]
+
+
+@pytest.mark.unit
+def test_tool_with_target_returns_only_that_target(registry, monkeypatch) -> None:
+    _with_targets(monkeypatch, "vc", "esx")
+    out = server.list_cached_images(target="vc")
+    assert [i["name"] for i in out["items"]] == ["a.iso"]
+
+
+@pytest.mark.unit
+def test_tool_without_target_is_unchanged_and_needs_no_config(registry, monkeypatch) -> None:
+    def no_config():
+        raise AssertionError("an unfiltered cache read must not load config.yaml")
+
+    monkeypatch.setattr(server, "_get_conn_mgr", no_config)
+    out = server.list_cached_images()
+    assert sorted(i["name"] for i in out["items"]) == ["a.iso", "b.ova", "old.iso"]
+
+
+@pytest.mark.unit
+def test_tool_with_an_unknown_target_names_the_configured_ones(registry, monkeypatch) -> None:
+    _with_targets(monkeypatch, "vc", "esx")
+    out = server.list_cached_images(target="nope")
+    assert "error" in out
+    assert "nope" in out["error"] and "vc" in out["error"]