refactor(image_gen): delegate cache-path mapping to shared helper

Follow-up on the backend-visible artifact-path fix.

- Extract the cache-mount iteration loop into a reusable, backend-agnostic
  credential_files.map_cache_path_to_container(host_path, container_base) that
  returns the POSIX container path or None. to_agent_visible_cache_path() now
  delegates to it (keeping its Docker-only gate), and image_generation_tool's
  _agent_visible_cache_path() delegates to it too — eliminating the duplicated
  loop and the divergent path-join (posixpath vs Path) between the two.
- Drop the now-unused posixpath/Path imports from image_generation_tool.py.
- Document the agent_visible_cache_base getattr probe as a forward-looking
  optional hook (no producer yet) so it doesn't read as a typo'd attribute.
- Add unit tests for map_cache_path_to_container.

tests/tools/test_credential_files.py

@@ -13,6 +13,7 @@ from tools.credential_files import (
     get_skills_directory_mount,
     iter_cache_files,
     iter_skills_files,
+    map_cache_path_to_container,
     register_credential_file,
     register_credential_files,
 )
@@ -423,6 +424,48 @@ class TestCacheDirectoryMounts:
         assert get_cache_directory_mounts() == []
 
 
+class TestMapCachePathToContainer:
+    """Tests for map_cache_path_to_container() — the backend-agnostic mapper."""
+
+    def test_maps_path_under_cache_dir(self, tmp_path, monkeypatch):
+        hermes_home = tmp_path / ".hermes"
+        img_dir = hermes_home / "cache" / "images"
+        img_dir.mkdir(parents=True)
+        host_path = str(img_dir / "generated.png")
+        monkeypatch.setenv("HERMES_HOME", str(hermes_home))
+
+        assert (
+            map_cache_path_to_container(host_path)
+            == "/root/.hermes/cache/images/generated.png"
+        )
+
+    def test_custom_container_base_for_remote_home(self, tmp_path, monkeypatch):
+        hermes_home = tmp_path / ".hermes"
+        img_dir = hermes_home / "cache" / "images"
+        img_dir.mkdir(parents=True)
+        host_path = str(img_dir / "remote.png")
+        monkeypatch.setenv("HERMES_HOME", str(hermes_home))
+
+        assert (
+            map_cache_path_to_container(host_path, container_base="/home/agent/.hermes")
+            == "/home/agent/.hermes/cache/images/remote.png"
+        )
+
+    def test_returns_none_when_outside_cache_dirs(self, tmp_path, monkeypatch):
+        hermes_home = tmp_path / ".hermes"
+        (hermes_home / "cache" / "images").mkdir(parents=True)
+        monkeypatch.setenv("HERMES_HOME", str(hermes_home))
+
+        assert map_cache_path_to_container(str(tmp_path / "elsewhere.png")) is None
+
+    def test_returns_none_when_no_cache_dirs_exist(self, tmp_path, monkeypatch):
+        hermes_home = tmp_path / ".hermes"
+        hermes_home.mkdir()
+        monkeypatch.setenv("HERMES_HOME", str(hermes_home))
+
+        assert map_cache_path_to_container(str(hermes_home / "cache" / "images" / "x.png")) is None
+
+
 class TestIterCacheFiles:
     """Tests for iter_cache_files()."""