Add AdminConsoleClient.fetch_thumbnails for cross-host dashboard

Headless side of Phase 6.5: a per-host base64 PNG screenshot fetched
in parallel via the existing /screenshot REST endpoint. Returns
{label: png_bytes} (None for hosts that errored), driven by the same
ThreadPoolExecutor as poll_all and broadcast_execute.

The GUI grid that consumes this is the next step — left as a
follow-up so the headless probe + tests can land independently.

6 new headless tests covering happy path, HTTP errors, malformed
responses, bad base64, label filtering, and the no-hosts case.

Author: JE-Chen

je_auto_control/utils/admin/admin_client.py

@@ -103,6 +103,41 @@ def poll_all(self, *, labels: Optional[List[str]] = None) -> List[HostStatus]:
         with ThreadPoolExecutor(max_workers=self._max_parallel) as pool:
             return list(pool.map(self._poll_one, targets))
 
+    def fetch_thumbnails(self, *, labels: Optional[List[str]] = None,
+                         ) -> Dict[str, Optional[bytes]]:
+        """Phase 6.5: pull a base64 PNG screenshot from every targeted host.
+
+        Returns ``label → png_bytes`` (or ``None`` on a host that
+        errored). The Cross-host Dashboard polls this on a timer and
+        scales the resulting image down to a thumbnail tile.
+        """
+        import base64
+        targets = self._resolve_targets(labels)
+        if not targets:
+            return {}
+
+        def grab(host: AdminHost) -> tuple:
+            try:
+                body = self._http_get(host, "/screenshot")
+            except (OSError, ValueError, TimeoutError) as error:
+                autocontrol_logger.info(
+                    "admin: thumbnail %s failed: %r", host.label, error,
+                )
+                return host.label, None
+            if not isinstance(body, dict) or body.get("encoding") != "base64":
+                return host.label, None
+            data = body.get("data")
+            if not isinstance(data, str):
+                return host.label, None
+            try:
+                return host.label, base64.b64decode(data)
+            except (ValueError, base64.binascii.Error):
+                return host.label, None
+
+        with ThreadPoolExecutor(max_workers=self._max_parallel) as pool:
+            results = list(pool.map(grab, targets))
+        return dict(results)
+
     def broadcast_execute(self, actions: List[Any],
                           *, labels: Optional[List[str]] = None,
                           ) -> List[Dict[str, Any]]:

test/unit_test/headless/test_admin_thumbnails.py

@@ -0,0 +1,80 @@
+"""Phase 6.5: tests for AdminConsoleClient.fetch_thumbnails."""
+import base64
+import json
+from unittest.mock import patch
+
+import pytest
+
+from je_auto_control.utils.admin.admin_client import AdminConsoleClient
+
+
+_FAKE_PNG = b"\x89PNG\r\n\x1a\nFAKE-PAYLOAD-BYTES"
+
+
+@pytest.fixture
+def client(tmp_path):
+    c = AdminConsoleClient(persist_path=tmp_path / "hosts.json", timeout_s=1.0)
+    c.add_host("alpha", "http://a.example", "tok-a")
+    c.add_host("beta", "http://b.example", "tok-b")
+    return c
+
+
+def test_fetch_thumbnails_returns_png_bytes_per_host(client):
+    encoded = base64.b64encode(_FAKE_PNG).decode("ascii")
+    body = {"format": "png", "encoding": "base64", "data": encoded}
+
+    def fake_get(self, host, path):
+        return body
+
+    with patch.object(AdminConsoleClient, "_http_get", new=fake_get):
+        out = client.fetch_thumbnails()
+    assert set(out.keys()) == {"alpha", "beta"}
+    assert out["alpha"] == _FAKE_PNG
+    assert out["beta"] == _FAKE_PNG
+
+
+def test_fetch_thumbnails_returns_none_on_http_error(client):
+    def fake_get(self, host, path):
+        raise OSError("connection refused")
+
+    with patch.object(AdminConsoleClient, "_http_get", new=fake_get):
+        out = client.fetch_thumbnails()
+    assert out == {"alpha": None, "beta": None}
+
+
+def test_fetch_thumbnails_returns_none_on_malformed_response(client):
+    def fake_get(self, host, path):
+        # Missing the expected "encoding": "base64".
+        return {"format": "png", "data": "Zm9v"}
+
+    with patch.object(AdminConsoleClient, "_http_get", new=fake_get):
+        out = client.fetch_thumbnails()
+    assert out == {"alpha": None, "beta": None}
+
+
+def test_fetch_thumbnails_returns_none_for_bad_base64(client):
+    def fake_get(self, host, path):
+        return {"format": "png", "encoding": "base64", "data": "%%not-b64%%"}
+
+    with patch.object(AdminConsoleClient, "_http_get", new=fake_get):
+        out = client.fetch_thumbnails()
+    # Both hosts produce None on decode failure (clean degradation).
+    assert all(v is None for v in out.values())
+
+
+def test_fetch_thumbnails_filters_by_label(client):
+    encoded = base64.b64encode(_FAKE_PNG).decode("ascii")
+    body = {"format": "png", "encoding": "base64", "data": encoded}
+
+    def fake_get(self, host, path):
+        return body
+
+    with patch.object(AdminConsoleClient, "_http_get", new=fake_get):
+        out = client.fetch_thumbnails(labels=["beta"])
+    assert set(out.keys()) == {"beta"}
+
+
+def test_fetch_thumbnails_returns_empty_when_no_hosts(tmp_path):
+    client = AdminConsoleClient(persist_path=tmp_path / "hosts.json")
+    assert client.fetch_thumbnails() == {}
+    assert client.fetch_thumbnails(labels=["nope"]) == {}