refactor(backend): has_backend() helper + docker/enumerate split + ActiveAgent rename

Addresses PR #78 review feedback:

- New `has_backend(name)` on the backend package + abstract
  `BottleBackend.is_available()` on each concrete subclass.
  Replaces inline `shutil.which("docker") is None` checks in
  docker/cleanup.py:178 and smolmachines/enumerate.py:73.
  Docker → `shutil.which("docker") is not None`; smolmachines
  → `smolvm.is_available()`. Cross-backend `enumerate_active_
  agents()` skips backends whose `is_available()` is False so a
  docker-only host doesn't fail when iterating past
  smolmachines (and vice versa).
- Move docker `enumerate_active` + parser helpers out of
  cleanup.py into a new `backend/docker/enumerate.py`, mirroring
  the smolmachines/enumerate.py layout. cleanup.py is now
  purely about prepare_cleanup / cleanup; the active-listing
  concern owns its own file.
- Drop the `ActiveAgent = ActiveBottle` alias in dashboard.py.
  The canonical name is `ActiveAgent` (the thing running inside
  a bottle is always called "agent" in this codebase; the bottle
  is the container). Renamed `enumerate_active_bottles` →
  `enumerate_active_agents` to match.

Tests:
- `test_backend_selection.TestEnumerateActiveAgents
  .test_skips_unavailable_backends` locks down the
  `is_available()`-gated iteration.
- New `TestHasBackend` covers `has_backend("docker")` consulting
  the backend's `is_available`, and unknown-name → False.
- Existing tests follow the rename; the docker-availability-
  side-effect test in `test_docker_enumerate_active` moves up
  to the cross-backend layer (where the gate lives now).

607 unit tests pass.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

claude_bottle/backend/__init__.py

@@ -19,7 +19,7 @@ backend exposes five methods:
   cleanup(plan) -> None
       Actually removes everything described by the cleanup plan.
 
-  enumerate_active() -> Sequence[ActiveBottle]
+  enumerate_active() -> Sequence[ActiveAgent]
       Return every currently-running bottle on this backend, with
       enough metadata for callers (CLI `list active`, dashboard
       agents pane) to render a row.
@@ -106,9 +106,11 @@ class ExecResult:
 
 
 @dataclass(frozen=True)
-class ActiveBottle:
-    """One currently-running bottle, as the CLI `list active` and
-    dashboard agents pane render it.
+class ActiveAgent:
+    """One currently-running agent, as the CLI `list active` and
+    dashboard agents pane render it. ("Agent" is the project's
+    consistent name for the thing running inside a bottle — the
+    bottle is the container, the agent is what runs in it.)
 
     Fields are deliberately backend-neutral. `services` is the set
     of sidecar daemons currently up for this bottle (`pipelock`,
@@ -302,12 +304,23 @@ class BottleBackend(ABC, Generic[PlanT, CleanupT]):
         """Remove everything described by the cleanup plan."""
 
     @abstractmethod
-    def enumerate_active(self) -> Sequence[ActiveBottle]:
-        """Return every currently-running bottle on this backend.
+    def enumerate_active(self) -> Sequence[ActiveAgent]:
+        """Return every currently-running agent on this backend.
         Empty when none. Backend-specific: docker queries `docker
         compose ls`; smolmachines queries `smolvm machine ls --json`
         + cross-references its bundle container."""
 
+    @classmethod
+    @abstractmethod
+    def is_available(cls) -> bool:
+        """Whether this backend's runtime prerequisites are satisfied
+        on the current host. Docker → `docker` on PATH; smolmachines
+        → `smolvm` on PATH. Used by the cross-backend
+        `enumerate_active_agents` / `cmd_cleanup` to skip backends
+        the operator hasn't installed, so a docker-only host
+        doesn't fail when `cli.py list active` walks past
+        smolmachines."""
+
 
 # Import concrete backend classes AFTER the base types are defined, so
 # each backend module can pull BottleSpec / BottlePlan / BottleBackend
@@ -352,26 +365,45 @@ def known_backend_names() -> tuple[str, ...]:
     return tuple(sorted(_BACKENDS))
 
 
-def enumerate_active_bottles() -> list[ActiveBottle]:
-    """All currently-running bottles, across every backend. Used by
-    CLI `list active` and the dashboard's agents pane so neither
-    has to know which backends exist. Ordered by backend name,
-    then slug."""
-    out: list[ActiveBottle] = []
+def has_backend(name: str) -> bool:
+    """Whether the named backend's runtime prerequisites are
+    available on the current host. Cross-backend callers (list,
+    cleanup) skip unavailable backends so a docker-only host
+    doesn't fail when the smolmachines backend isn't installed,
+    and vice versa.
+
+    Returns False for unknown names so callers can pass
+    arbitrary input without separate validation."""
+    if name not in _BACKENDS:
+        return False
+    return _BACKENDS[name].is_available()
+
+
+def enumerate_active_agents() -> list[ActiveAgent]:
+    """All currently-running agents, across every available
+    backend. Used by CLI `list active` and the dashboard's agents
+    pane so neither has to know which backends exist. Skips
+    backends whose `is_available()` reports False. Ordered by
+    backend name, then by whatever each backend's
+    `enumerate_active` returns."""
+    out: list[ActiveAgent] = []
     for name in known_backend_names():
+        if not has_backend(name):
+            continue
         out.extend(_BACKENDS[name].enumerate_active())
     return out
 
 
 __all__ = [
-    "ActiveBottle",
+    "ActiveAgent",
     "Bottle",
     "BottleBackend",
     "BottleCleanupPlan",
     "BottlePlan",
     "BottleSpec",
     "ExecResult",
-    "enumerate_active_bottles",
+    "enumerate_active_agents",
     "get_bottle_backend",
+    "has_backend",
     "known_backend_names",
 ]

claude_bottle/backend/docker/backend.py

@@ -1,10 +1,11 @@
 """DockerBottleBackend — the Docker implementation of BottleBackend.
 
-This module is a thin façade. The real work lives in three siblings:
+This module is a thin façade. The real work lives in four siblings:
 
-  - prepare.py  — host-side resolution into a DockerBottlePlan
-  - launch.py   — bring-up + teardown context manager
-  - cleanup.py  — orphan enumeration, removal, and active listing
+  - prepare.py    — host-side resolution into a DockerBottlePlan
+  - launch.py     — bring-up + teardown context manager
+  - cleanup.py    — orphan enumeration + removal
+  - enumerate.py  — active-agent listing
 
 The base class's `prepare` template runs cross-backend host-side
 validation before calling `_resolve_plan` here.
@@ -12,12 +13,14 @@ validation before calling `_resolve_plan` here.
 
 from __future__ import annotations
 
+import shutil
 from contextlib import contextmanager
 from pathlib import Path
 from typing import Generator, Sequence
 
-from .. import ActiveBottle, BottleBackend, BottleSpec
+from .. import ActiveAgent, BottleBackend, BottleSpec
 from . import cleanup as _cleanup
+from . import enumerate as _enumerate
 from . import launch as _launch
 from . import prepare as _prepare
 from .bottle import DockerBottle
@@ -36,6 +39,15 @@ class DockerBottleBackend(BottleBackend["DockerBottlePlan", "DockerBottleCleanup
 
     name = "docker"
 
+    @classmethod
+    def is_available(cls) -> bool:
+        """`docker` on PATH is sufficient; we don't probe `docker info`
+        eagerly because the cross-backend enumerator runs this on
+        every `list active` and we'd pay a subprocess per call. A
+        broken daemon will surface its own error during prepare /
+        launch."""
+        return shutil.which("docker") is not None
+
     def _resolve_plan(self, spec: BottleSpec, *, stage_dir: Path) -> DockerBottlePlan:
         return _prepare.resolve_plan(spec, stage_dir=stage_dir)
 
@@ -65,5 +77,5 @@ class DockerBottleBackend(BottleBackend["DockerBottlePlan", "DockerBottleCleanup
     def cleanup(self, plan: DockerBottleCleanupPlan) -> None:
         _cleanup.cleanup(plan)
 
-    def enumerate_active(self) -> Sequence[ActiveBottle]:
-        return _cleanup.enumerate_active()
+    def enumerate_active(self) -> Sequence[ActiveAgent]:
+        return _enumerate.enumerate_active()

claude_bottle/backend/docker/cleanup.py

@@ -1,4 +1,4 @@
-"""Cleanup + active-listing for the Docker bottle backend.
+"""Cleanup for the Docker bottle backend.
 
 PRD 0018 chunk 4: cleanup is centered on `docker compose ls`.
 Pre-compose code paths could leave bare containers / networks
@@ -18,8 +18,8 @@ scan, just as a fallback bucket alongside the project list.
 
 `cleanup` removes everything in the plan.
 
-`list_active` queries the same compose project namespace and prints
-each project's services for ad-hoc inspection.
+Active-agent enumeration lives in `backend/docker/enumerate.py`
+(mirror of `backend/smolmachines/enumerate.py`).
 """
 
 from __future__ import annotations
@@ -29,16 +29,10 @@ import subprocess
 
 from ... import supervise as _supervise
 from ...log import info, warn
-from .. import ActiveBottle
 from . import util as docker_mod
 from .bottle_cleanup_plan import DockerBottleCleanupPlan
-from .bottle_state import bottle_state_dir, is_preserved, read_metadata
-from .compose import (
-    COMPOSE_PROJECT_PREFIX,
-    compose_project_name,
-    list_active_slugs,
-    list_compose_projects,
-)
+from .bottle_state import bottle_state_dir, is_preserved
+from .compose import COMPOSE_PROJECT_PREFIX, list_compose_projects
 
 
 def _list_prefixed_containers() -> list[str]:
@@ -167,67 +161,6 @@ def cleanup(plan: DockerBottleCleanupPlan) -> None:
             warn(f"failed to remove {path}: {e}")
 
 
-def enumerate_active() -> list[ActiveBottle]:
-    """All currently-running docker-backed bottles as
-    `ActiveBottle` records. Backend-agnostic shape — the CLI
-    `list active` command and the dashboard agents pane both
-    consume this. Empty list when docker is unreachable or
-    nothing's running."""
-    # docker on PATH? Defensive — `list active` shouldn't die
-    # just because the docker backend isn't usable on this host.
-    if shutil.which("docker") is None:
-        return []
-    slugs = list_active_slugs(include_stopped=False)
-    if not slugs:
-        return []
-    services_by_project = _query_services_by_project()
-    out: list[ActiveBottle] = []
-    for slug in slugs:
-        project = compose_project_name(slug)
-        services = services_by_project.get(project, set())
-        metadata = read_metadata(slug)
-        out.append(ActiveBottle(
-            backend_name="docker",
-            slug=slug,
-            agent_name=metadata.agent_name if metadata else "?",
-            started_at=metadata.started_at if metadata else "",
-            services=tuple(sorted(services)),
-        ))
-    return out
-
-
-def _parse_services_by_project(stdout: str) -> dict[str, set[str]]:
-    """Parse `docker ps` output formatted as
-    `<project-label>\\t<service-label>` (one line per container)
-    into a `{project: {service, ...}}` mapping. Pure function for
-    testing — the docker invocation is in `_query_services_by_project`."""
-    out: dict[str, set[str]] = {}
-    for line in stdout.splitlines():
-        project, _, service = line.partition("\t")
-        if not project or not service:
-            continue
-        out.setdefault(project, set()).add(service)
-    return out
-
-
-def _query_services_by_project() -> dict[str, set[str]]:
-    """One `docker ps` call → `{project: {service, ...}}`. Moved
-    here from the dashboard so the same query backs the CLI's
-    `list active` and the dashboard's agents pane."""
-    try:
-        r = subprocess.run(
-            [
-                "docker", "ps",
-                "--filter", "label=com.docker.compose.project",
-                "--format",
-                '{{.Label "com.docker.compose.project"}}'
-                "\t"
-                '{{.Label "com.docker.compose.service"}}',
-            ],
-            capture_output=True, text=True, check=False,
-        )
-    except FileNotFoundError:
-        return {}
-    if r.returncode != 0:
-        return {}
-    return _parse_services_by_project(r.stdout or "")
+# `enumerate_active` moved to `backend/docker/enumerate.py` to
+# mirror the smolmachines layout. Cleanup keeps the orphan
+# enumeration; enumeration of live agents is its own concern.

claude_bottle/backend/docker/enumerate.py

@@ -0,0 +1,80 @@
+"""Active-agent enumeration for the docker backend.
+
+Mirrors `backend/smolmachines/enumerate.py`: returns
+`ActiveAgent` records the CLI `list active` command and the
+dashboard agents pane consume. Empty when docker isn't reachable
+— gated by `has_backend('docker')` at the cross-backend caller
+so this module trusts that docker is available when called.
+
+The parser (`_parse_services_by_project`) is exposed for direct
+unit testing; the docker `docker ps` invocation is in
+`_query_services_by_project`."""
+
+from __future__ import annotations
+
+import subprocess
+
+from .. import ActiveAgent
+from .bottle_state import read_metadata
+from .compose import compose_project_name, list_active_slugs
+
+
+def enumerate_active() -> list[ActiveAgent]:
+    """All currently-running docker-backed agents. Caller is
+    responsible for gating on `has_backend('docker')` if it
+    matters; if docker is missing the `docker ps` call below
+    returns an empty list silently."""
+    slugs = list_active_slugs(include_stopped=False)
+    if not slugs:
+        return []
+    services_by_project = _query_services_by_project()
+    out: list[ActiveAgent] = []
+    for slug in slugs:
+        project = compose_project_name(slug)
+        services = services_by_project.get(project, set())
+        metadata = read_metadata(slug)
+        out.append(ActiveAgent(
+            backend_name="docker",
+            slug=slug,
+            agent_name=metadata.agent_name if metadata else "?",
+            started_at=metadata.started_at if metadata else "",
+            services=tuple(sorted(services)),
+        ))
+    return out
+
+
+def _parse_services_by_project(stdout: str) -> dict[str, set[str]]:
+    """Parse `docker ps` output formatted as
+    `<project-label>\\t<service-label>` (one line per container)
+    into a `{project: {service, ...}}` mapping. Pure function for
+    testing — the docker invocation is in `_query_services_by_project`."""
+    out: dict[str, set[str]] = {}
+    for line in stdout.splitlines():
+        project, _, service = line.partition("\t")
+        if not project or not service:
+            continue
+        out.setdefault(project, set()).add(service)
+    return out
+
+
+def _query_services_by_project() -> dict[str, set[str]]:
+    """One `docker ps` call → `{project: {service, ...}}`. Used
+    by the CLI's `list active` and the dashboard's agents pane —
+    one subprocess per refresh tick, not one per bottle."""
+    try:
+        r = subprocess.run(
+            [
+                "docker", "ps",
+                "--filter", "label=com.docker.compose.project",
+                "--format",
+                '{{.Label "com.docker.compose.project"}}'
+                "\t"
+                '{{.Label "com.docker.compose.service"}}',
+            ],
+            capture_output=True, text=True, check=False,
+        )
+    except FileNotFoundError:
+        return {}
+    if r.returncode != 0:
+        return {}
+    return _parse_services_by_project(r.stdout or "")

claude_bottle/backend/smolmachines/backend.py

@@ -7,10 +7,11 @@ from contextlib import contextmanager
 from pathlib import Path
 from typing import Generator, Sequence
 
-from .. import ActiveBottle, BottleBackend, BottleSpec
+from .. import ActiveAgent, BottleBackend, BottleSpec
 from . import enumerate as _enumerate
 from . import launch as _launch
 from . import prepare as _prepare
+from . import smolvm as _smolvm
 from .bottle import SmolmachinesBottle
 from .bottle_cleanup_plan import SmolmachinesBottleCleanupPlan
 from .bottle_plan import SmolmachinesBottlePlan
@@ -29,6 +30,14 @@ class SmolmachinesBottleBackend(
 
     name = "smolmachines"
 
+    @classmethod
+    def is_available(cls) -> bool:
+        """`smolvm` on PATH. The backend additionally needs macOS
+        for libkrun + TSI, but `enumerate_active` / `cleanup` are
+        host-shell ops that gracefully no-op on Linux too — the
+        runtime check happens at `prepare`."""
+        return _smolvm.is_available()
+
     def _resolve_plan(
         self, spec: BottleSpec, *, stage_dir: Path
     ) -> SmolmachinesBottlePlan:
@@ -74,5 +83,5 @@ class SmolmachinesBottleBackend(
         # Nothing to clean in chunks 1-3 — see
         # SmolmachinesBottleCleanupPlan docstring.
 
-    def enumerate_active(self) -> Sequence[ActiveBottle]:
+    def enumerate_active(self) -> Sequence[ActiveAgent]:
         return _enumerate.enumerate_active()

claude_bottle/backend/smolmachines/enumerate.py

@@ -1,26 +1,30 @@
-"""Active-bottle enumeration for the smolmachines backend (PRD
+"""Active-agent enumeration for the smolmachines backend (PRD
 0023 chunk 4 follow-up + issue #77).
 
-Returns a list of `ActiveBottle` records — same shape the docker
+Returns a list of `ActiveAgent` records — same shape the docker
 backend produces — so CLI `list active` and the dashboard agents
 pane render both backends through one code path.
 
-A smolmachines bottle is "active" when its smolvm guest is
+A smolmachines agent is "active" when its smolvm guest is
 running. We cross-reference against the per-bottle sidecar
 bundle container to populate the `services` field (which daemons
 are up in the bundle); without a bundle we still surface the VM
-so the operator can see + clean it up."""
+so the operator can see + clean it up.
+
+The cross-backend caller gates on `has_backend("smolmachines")`
+and `has_backend("docker")`, so this module assumes both are
+available when called. Both subprocess calls below still
+tolerate "command not on PATH" defensively, but the gate is the
+intended access pattern."""
 
 from __future__ import annotations
 
 import json
-import shutil
 import subprocess
 
-from .. import ActiveBottle
+from .. import ActiveAgent
 from ..docker.bottle_state import read_metadata
 from . import sidecar_bundle as _bundle
-from . import smolvm as _smolvm
 
 
 # Smolvm VM names produced by prepare are `claude-bottle-<slug>`,
@@ -29,12 +33,12 @@ from . import smolvm as _smolvm
 _VM_NAME_PREFIX = "claude-bottle-"
 
 
-def enumerate_active() -> list[ActiveBottle]:
-    """All currently-running smolmachines-backed bottles. Empty
-    list when smolvm isn't on PATH or no matching VMs are
-    running."""
-    if not _smolvm.is_available():
-        return []
+def enumerate_active() -> list[ActiveAgent]:
+    """All currently-running smolmachines-backed agents. Empty
+    list when no matching VMs are running. Caller is responsible
+    for gating on `has_backend('smolmachines')` if needed; if
+    smolvm is missing the `smolvm machine ls` call below returns
+    nothing silently."""
     result = subprocess.run(
         ["smolvm", "machine", "ls", "--json"],
         capture_output=True, text=True, check=False,
@@ -46,7 +50,7 @@ def enumerate_active() -> list[ActiveBottle]:
     except json.JSONDecodeError:
         return []
     services_by_slug = _query_bundle_services()
-    out: list[ActiveBottle] = []
+    out: list[ActiveAgent] = []
     for m in machines:
         name = m.get("name") or ""
         state = m.get("state") or ""
@@ -54,7 +58,7 @@ def enumerate_active() -> list[ActiveBottle]:
             continue
         slug = name[len(_VM_NAME_PREFIX):]
         metadata = read_metadata(slug)
-        out.append(ActiveBottle(
+        out.append(ActiveAgent(
             backend_name="smolmachines",
             slug=slug,
             agent_name=metadata.agent_name if metadata else "?",
@@ -69,8 +73,17 @@ def _query_bundle_services() -> dict[str, tuple[str, ...]]:
     bundle container's `CLAUDE_BOTTLE_SIDECAR_DAEMONS` env var.
     Smolmachines bundles all run the PRD-0024 image with the
     same daemon set declared via env, so one inspect per bundle
-    gets us the picture without exec'ing into the container."""
-    if shutil.which("docker") is None:
+    gets us the picture without exec'ing into the container.
+
+    Returns an empty mapping when the docker backend isn't
+    available — the bundle services field on each ActiveAgent
+    just shows up empty, matching the docker backend's "starting"
+    state."""
+    # Late import: `has_backend` lives on the backend package's
+    # __init__, which imports this module transitively. Pulling
+    # the name in at call time sidesteps the cycle.
+    from .. import has_backend
+    if not has_backend("docker"):
         return {}
     ps = subprocess.run(
         ["docker", "ps",