refactor(backend): type enumeration failures

bot_bottle/backend/__init__.py

@@ -30,6 +30,7 @@ if TYPE_CHECKING:
         BottleImages,
         BottlePlan,
         BottleSpec,
+        EnumerationError,
         ExecResult,
     )
     from .selection import (
@@ -59,6 +60,7 @@ _LAZY_MODULES: dict[str, str] = {
     "BottleImages": "base",
     "BottleBackend": "base",
     "BackendStatus": "base",
+    "EnumerationError": "base",
     "get_bottle_backend": "selection",
     "known_backend_names": "selection",
     "has_backend": "selection",
@@ -100,6 +102,7 @@ __all__ = [
     "BottlePlan",
     "BottleSpec",
     "ExecResult",
+    "EnumerationError",
     "CommitCancelled",
     "Freezer",
     "get_freezer",

bot_bottle/backend/base.py

@@ -42,6 +42,10 @@ class BackendStatus(enum.IntEnum):
     READY = 0
 
 
+class EnumerationError(RuntimeError):
+    """A backend could not produce an authoritative live-resource snapshot."""
+
+
 @dataclass(frozen=True)
 class BottleSpec:
     """CLI-supplied intent. Backend-agnostic — each backend's prepare

bot_bottle/backend/docker/compose.py

@@ -16,6 +16,7 @@ from pathlib import Path
 from typing import Any
 
 from ...log import die, warn
+from ..base import EnumerationError
 
 
 # --- Lifecycle helpers (PRD 0018 chunk 3) ----------------------------------
@@ -75,12 +76,14 @@ def list_compose_projects(
         )
     except FileNotFoundError as exc:
         if raise_on_error:
-            raise RuntimeError("docker compose ls failed: docker not found") from exc
+            raise EnumerationError(
+                "docker compose ls failed: docker not found"
+            ) from exc
         return []
     if result.returncode != 0:
         message = f"docker compose ls failed: {result.stderr.strip()}"
         if raise_on_error:
-            raise RuntimeError(message)
+            raise EnumerationError(message)
         if warn_on_error:
             warn(message)
         return []
@@ -89,7 +92,7 @@ def list_compose_projects(
     except json.JSONDecodeError as e:
         message = f"docker compose ls returned malformed JSON: {e}"
         if raise_on_error:
-            raise RuntimeError(message) from e
+            raise EnumerationError(message) from e
         if warn_on_error:
             warn(message)
         return []

bot_bottle/backend/docker/enumerate.py

@@ -12,7 +12,7 @@ from __future__ import annotations
 
 import subprocess
 
-from .. import ActiveAgent
+from .. import ActiveAgent, EnumerationError
 from ...bottle_state import read_metadata
 from .compose import compose_project_name, list_active_slugs
 
@@ -75,7 +75,7 @@ def _query_services_by_project() -> dict[str, set[str]]:
             capture_output=True, text=True, check=False,
         )
     except FileNotFoundError as exc:
-        raise RuntimeError("docker ps failed: docker not found") from exc
+        raise EnumerationError("docker ps failed: docker not found") from exc
     if r.returncode != 0:
-        raise RuntimeError(f"docker ps failed: {r.stderr.strip()}")
+        raise EnumerationError(f"docker ps failed: {r.stderr.strip()}")
     return _parse_services_by_project(r.stdout or "")

bot_bottle/backend/macos_container/enumerate.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 import subprocess
 
 from ...bottle_state import read_metadata
-from .. import ActiveAgent
+from .. import ActiveAgent, EnumerationError
 from .infra import INFRA_NAME, ORCHESTRATOR_NAME
 
 # The name every agent container carries: `bot-bottle-<slug>`. Exported
@@ -20,17 +20,18 @@ CONTAINER_NAME_PREFIX = "bot-bottle-"
 _INFRA_NAMES = frozenset({INFRA_NAME, ORCHESTRATOR_NAME})
 
 
-class EnumerationError(RuntimeError):
-    """container list failed; the resulting live set is not authoritative."""
-
-
 def enumerate_active() -> list[ActiveAgent]:
-    result = subprocess.run(
-        ["container", "list", "--quiet"],
-        capture_output=True,
-        text=True,
-        check=False,
-    )
+    try:
+        result = subprocess.run(
+            ["container", "list", "--quiet"],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+    except FileNotFoundError as exc:
+        raise EnumerationError(
+            "container list failed: container CLI not found"
+        ) from exc
     if result.returncode != 0:
         raise EnumerationError(
             f"container list failed: "