feat(cleanup): walk every backend, reap smolmachines orphans too

`./cli.py cleanup` previously called only the env-var-selected
backend's `prepare_cleanup` / `cleanup` — so a leftover smolvm
machine + bundle container + bundle network from a crashed
smolmachines bottle would survive a default `docker`-mode cleanup
indefinitely.

Smolmachines now has a real `cleanup` module (alongside
`enumerate.py` from issue #77) that walks:

  - smolvm machines named `claude-bottle-*` (via
    `smolvm machine ls --json`)
  - bundle containers `claude-bottle-sidecars-*`
  - bundle networks `claude-bottle-bundle-*`

Cleanup runs stop+delete on the machines, force-rm on the
containers, network rm on the networks. Each step is best-effort
so a failed rm doesn't block the rest.

`cli.py cleanup` walks every backend in `known_backend_names()`
and runs each backend's `cleanup` after a single y/N prompt that
shows a combined plan.

State dirs (`~/.claude-bottle/state/<slug>/`) are shared layout
with the docker backend, which still owns the orphan-state-dir
bucket. It now consults `enumerate_active_bottles()` for the
cross-backend live identity set so a running smolmachines
bottle's state dir isn't reaped during a cleanup.

Tests: smolmachines cleanup (prepare + cleanup ordering + failure
handling); cross-backend orphan protection on the docker
state-dir check; CLI cmd_cleanup walks both backends, short-
circuits on all-empty, aborts on N. 617 unit tests pass.

End-to-end verified on this host:
  $ smolvm machine ls --json | jq '.[].name'
  "claude-bottle-researcher-m3hxd"
  $ ./cli.py cleanup
  --- smolmachines backend ---
  smolvm machine:  claude-bottle-researcher-m3hxd
  remove all of the above? [y/N]

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]:
@@ -89,11 +83,18 @@ def _list_prefixed_networks() -> list[str]:
     return sorted(set(out))
 
 
-def _list_orphan_state_dirs(live_projects: set[str]) -> list[str]:
+def _list_orphan_state_dirs(
+    live_projects: set[str], protected_identities: set[str],
+) -> list[str]:
     """State identities whose compose project isn't running and
     that don't have a `.preserve` marker. `.preserve` means the
     user (or an auto-preserve-on-crash) wants the state kept for
-    `resume`."""
+    `resume`.
+
+    `protected_identities` is the set of slugs that are live in
+    ANY backend — used so this docker-side check doesn't reap a
+    running smolmachines bottle's state dir (the layout is shared
+    across both backends)."""
     state_root = _supervise.claude_bottle_root() / "state"
     if not state_root.is_dir():
         return []
@@ -105,6 +106,8 @@ def _list_orphan_state_dirs(live_projects: set[str]) -> list[str]:
         project = f"{COMPOSE_PROJECT_PREFIX}{identity}"
         if project in live_projects:
             continue
+        if identity in protected_identities:
+            continue
         if is_preserved(identity):
             continue
         orphans.append(identity)
@@ -112,15 +115,25 @@ def _list_orphan_state_dirs(live_projects: set[str]) -> list[str]:
 
 
 def prepare_cleanup() -> DockerBottleCleanupPlan:
-    """Enumerate everything cleanup will touch. No removals."""
+    """Enumerate everything cleanup will touch. No removals.
+
+    Pulls the union of live identities across backends via
+    `enumerate_active_agents()` so the orphan-state-dir bucket
+    doesn't include slugs whose smolmachines VM is still up."""
     docker_mod.require_docker()
     projects = list_compose_projects()
     project_set = set(projects)
+    # Late import to avoid a circular at module-load time —
+    # the backend package's __init__ imports this module.
+    from .. import enumerate_active_agents
+    protected = {a.slug for a in enumerate_active_agents()}
     return DockerBottleCleanupPlan(
         projects=tuple(projects),
         stray_containers=tuple(_list_prefixed_containers()),
         stray_networks=tuple(_list_prefixed_networks()),
-        orphan_state_dirs=tuple(_list_orphan_state_dirs(project_set)),
+        orphan_state_dirs=tuple(
+            _list_orphan_state_dirs(project_set, protected),
+        ),
     )
 
 
@@ -165,69 +178,3 @@ def cleanup(plan: DockerBottleCleanupPlan) -> None:
             shutil.rmtree(path, ignore_errors=True)
         except OSError as e:
             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 "")

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,12 @@ 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 . import smolvm as _smolvm
 from .bottle import SmolmachinesBottle
 from .bottle_cleanup_plan import SmolmachinesBottleCleanupPlan
 from .bottle_plan import SmolmachinesBottlePlan
@@ -29,6 +31,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:
@@ -67,12 +77,10 @@ class SmolmachinesBottleBackend(
         _supervise.provision_supervise(plan, target)
 
     def prepare_cleanup(self) -> SmolmachinesBottleCleanupPlan:
-        return SmolmachinesBottleCleanupPlan()
+        return _cleanup.prepare_cleanup()
 
     def cleanup(self, plan: SmolmachinesBottleCleanupPlan) -> None:
-        del plan
-        # Nothing to clean in chunks 1-3 — see
-        # SmolmachinesBottleCleanupPlan docstring.
+        _cleanup.cleanup(plan)
 
-    def enumerate_active(self) -> Sequence[ActiveBottle]:
+    def enumerate_active(self) -> Sequence[ActiveAgent]:
         return _enumerate.enumerate_active()

claude_bottle/backend/smolmachines/bottle_cleanup_plan.py

@@ -1,13 +1,29 @@
-"""SmolmachinesBottleCleanupPlan — concrete BottleCleanupPlan stub
-(PRD 0023 chunk 1).
+"""SmolmachinesBottleCleanupPlan — concrete BottleCleanupPlan (issue #77).
 
-Chunk 1 always reports nothing-to-clean. Real enumeration —
-orphaned smolvm machines, stranded gvproxy sockets, leftover
-sidecar bundle containers — lands in chunk 4 alongside the
-integration-test sweep that exercises teardown."""
+Tracks the resources `SmolmachinesBottleBackend.cleanup` will
+remove:
+
+  - machines:  smolvm machines whose name starts with
+               `claude-bottle-` (running or stopped). Stopped +
+               deleted via `smolvm machine stop` + `machine delete -f`.
+  - bundles:   docker containers `claude-bottle-sidecars-<slug>`
+               left over from a smolmachines bottle (the bundle's
+               port-forwards stay published on lo0 aliases until
+               the container is gone). Removed via `docker rm -f`.
+  - networks:  docker networks `claude-bottle-bundle-<slug>`
+               attached to the bundles. Removed via
+               `docker network rm`.
+
+Smolmachines state dirs live under the same `~/.claude-bottle/state/`
+path the docker backend uses; the docker backend's
+`prepare_cleanup` already enumerates orphan state dirs and is the
+single source of truth for that bucket (consults
+`enumerate_active_bottles()` so it doesn't reap a live
+smolmachines bottle's dir)."""
 
 from __future__ import annotations
 
+import sys
 from dataclasses import dataclass
 
 from ...log import info
@@ -16,10 +32,24 @@ from .. import BottleCleanupPlan
 
 @dataclass(frozen=True)
 class SmolmachinesBottleCleanupPlan(BottleCleanupPlan):
-    def print(self) -> None:
-        info("smolmachines cleanup: nothing to remove (chunk 4 will "
-             "enumerate orphan machines + gvproxy sockets)")
+    """Resources SmolmachinesBottleBackend.cleanup will remove.
+    Produced by `prepare_cleanup`; sorted so the y/N output is
+    stable."""
+
+    machines: tuple[str, ...] = ()
+    bundles: tuple[str, ...] = ()
+    networks: tuple[str, ...] = ()
 
     @property
     def empty(self) -> bool:
-        return True
+        return not self.machines and not self.bundles and not self.networks
+
+    def print(self) -> None:
+        print(file=sys.stderr)
+        for name in self.machines:
+            info(f"smolvm machine:  {name}")
+        for name in self.bundles:
+            info(f"bundle container:{name}")
+        for name in self.networks:
+            info(f"bundle network:  {name}")
+        print(file=sys.stderr)

claude_bottle/backend/smolmachines/cleanup.py

@@ -0,0 +1,159 @@
+"""Cleanup + active-listing for the smolmachines backend (issue #77).
+
+`prepare_cleanup` enumerates leftover smolmachines resources:
+
+  - smolvm machines (`smolvm machine ls --json`) whose name starts
+    with `claude-bottle-`.
+  - bundle docker containers (`claude-bottle-sidecars-<slug>`).
+  - bundle docker networks (`claude-bottle-bundle-<slug>`).
+
+State dirs live under `~/.claude-bottle/state/<identity>/` —
+shared layout with the docker backend, which has the single
+orphan-state-dir enumerator (it already consults
+`enumerate_active_agents()` so a live smolmachines bottle's dir
+is preserved).
+
+`cleanup` removes everything in the plan: stop + delete each VM,
+force-rm each container, rm each network. Each step is
+best-effort — a failure on one resource doesn't block the others."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+
+from ...log import info, warn
+from . import sidecar_bundle as _bundle
+from . import smolvm as _smolvm
+from .bottle_cleanup_plan import SmolmachinesBottleCleanupPlan
+
+
+# Both names start with the same prefix the launcher uses.
+_VM_PREFIX = "claude-bottle-"
+_BUNDLE_PREFIX = _bundle.bundle_container_name("")          # `claude-bottle-sidecars-`
+_NETWORK_PREFIX = _bundle.bundle_network_name("")           # `claude-bottle-bundle-`
+
+
+def prepare_cleanup() -> SmolmachinesBottleCleanupPlan:
+    """Enumerate every smolmachines-owned resource on the host.
+    No side effects. Returns an empty plan when smolvm isn't on
+    PATH (no machines to reap) — `cleanup` is a no-op in that
+    case too."""
+    machines = _list_claude_bottle_machines()
+    bundles = _list_bundle_containers()
+    networks = _list_bundle_networks()
+    return SmolmachinesBottleCleanupPlan(
+        machines=tuple(sorted(machines)),
+        bundles=tuple(sorted(bundles)),
+        networks=tuple(sorted(networks)),
+    )
+
+
+def cleanup(plan: SmolmachinesBottleCleanupPlan) -> None:
+    """Remove everything in the plan. Order matters: stop VMs
+    first (they hold ports on lo0 aliases via libkrun), then the
+    bundle containers (which hold the host port-forwards), then
+    the networks (which docker won't reap until the containers
+    are gone)."""
+    for name in plan.machines:
+        info(f"stopping smolvm machine {name}")
+        subprocess.run(
+            ["smolvm", "machine", "stop", "--name", name],
+            stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
+            check=False,
+        )
+        info(f"deleting smolvm machine {name}")
+        r = subprocess.run(
+            ["smolvm", "machine", "delete", "-f", name],
+            capture_output=True, text=True, check=False,
+        )
+        if r.returncode != 0:
+            warn(
+                f"smolvm machine delete -f {name} failed: "
+                f"{(r.stderr or '').strip()}"
+            )
+
+    for name in plan.bundles:
+        info(f"removing bundle container {name}")
+        subprocess.run(
+            ["docker", "rm", "-f", name],
+            stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
+            check=False,
+        )
+
+    for name in plan.networks:
+        info(f"removing bundle network {name}")
+        r = subprocess.run(
+            ["docker", "network", "rm", name],
+            capture_output=True, text=True, check=False,
+        )
+        if r.returncode != 0 and "no such network" not in (r.stderr or "").lower():
+            warn(
+                f"docker network rm {name} failed: "
+                f"{(r.stderr or '').strip()}"
+            )
+
+
+def _list_claude_bottle_machines() -> list[str]:
+    """All smolvm machines named `claude-bottle-*`, regardless of
+    state (running / stopped / created). Empty when smolvm isn't
+    installed."""
+    if not _smolvm.is_available():
+        return []
+    r = subprocess.run(
+        ["smolvm", "machine", "ls", "--json"],
+        capture_output=True, text=True, check=False,
+    )
+    if r.returncode != 0:
+        return []
+    try:
+        machines = json.loads(r.stdout or "[]")
+    except json.JSONDecodeError:
+        return []
+    return [
+        m["name"] for m in machines
+        if isinstance(m, dict)
+        and m.get("name", "").startswith(_VM_PREFIX)
+    ]
+
+
+def _list_bundle_containers() -> list[str]:
+    """All docker containers named `claude-bottle-sidecars-*`,
+    running or stopped. Empty when docker isn't installed."""
+    # Late import: `backend/__init__` imports this module
+    # transitively via the smolmachines backend.
+    from .. import has_backend
+    if not has_backend("docker"):
+        return []
+    r = subprocess.run(
+        ["docker", "ps", "-a",
+         "--filter", f"name=^{_BUNDLE_PREFIX}",
+         "--format", "{{.Names}}"],
+        capture_output=True, text=True, check=False,
+    )
+    if r.returncode != 0:
+        return []
+    return [
+        line for line in (r.stdout or "").splitlines()
+        if line and line.startswith(_BUNDLE_PREFIX)
+    ]
+
+
+def _list_bundle_networks() -> list[str]:
+    """All docker networks named `claude-bottle-bundle-*`. Empty
+    when docker isn't installed."""
+    from .. import has_backend
+    if not has_backend("docker"):
+        return []
+    r = subprocess.run(
+        ["docker", "network", "ls",
+         "--filter", f"name={_NETWORK_PREFIX}",
+         "--format", "{{.Name}}"],
+        capture_output=True, text=True, check=False,
+    )
+    if r.returncode != 0:
+        return []
+    return [
+        line for line in (r.stdout or "").splitlines()
+        if line and line.startswith(_NETWORK_PREFIX)
+    ]

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",

claude_bottle/cli/cleanup.py

@@ -1,11 +1,16 @@
 """cleanup: stop and remove all orphaned claude-bottle resources.
 
-PRD 0018 chunk 4: backend's prepare_cleanup carries everything in
-one plan — live compose projects (whose `compose down` removes
-containers + networks atomically), legacy stray containers/networks
-that aren't in any project, and orphan state dirs (per-bottle
-state with no live project AND no `.preserve` marker). One prompt,
-one cleanup call.
+Walks every registered backend (docker + smolmachines) so a single
+`./cli.py cleanup` reaps both backends' leftovers — orphaned
+smolvm machines won't survive a docker-only cleanup pass (issue
+addressed alongside #77).
+
+Each backend's `prepare_cleanup` enumerates its own resources;
+docker's `_list_orphan_state_dirs` consults
+`enumerate_active_agents()` for the union of live identities so
+state dirs of running smolmachines bottles aren't reaped. State
+dirs are shared layout, so docker is the single owner of that
+bucket.
 
 State dirs with `.preserve` are intentionally never touched — they
 hold capability-block rebuilds or crash snapshots the operator may
@@ -17,25 +22,37 @@ from __future__ import annotations
 
 import sys
 
-from ..backend import get_bottle_backend
+from ..backend import get_bottle_backend, known_backend_names
 from ..log import info
 from ._common import read_tty_line
 
 
 def cmd_cleanup(_argv: list[str]) -> int:
-    backend = get_bottle_backend()
-    plan = backend.prepare_cleanup()
+    # Order: stable backend iteration so the y/N output is
+    # deterministic across runs.
+    plans = [
+        (name, get_bottle_backend(name)) for name in known_backend_names()
+    ]
+    prepared = [(name, b, b.prepare_cleanup()) for name, b in plans]
 
-    if plan.empty:
+    if all(p.empty for _, _, p in prepared):
         info("no claude-bottle resources to clean up")
         return 0
 
-    plan.print()
+    for name, _, plan in prepared:
+        if plan.empty:
+            continue
+        info(f"--- {name} backend ---")
+        plan.print()
+
     if not _prompt_yes("remove all of the above?"):
         info("cleanup: skipped")
         return 0
 
-    backend.cleanup(plan)
+    for name, backend, plan in prepared:
+        if plan.empty:
+            continue
+        backend.cleanup(plan)
     info("cleanup: done")
     return 0
 

claude_bottle/cli/dashboard.py

@@ -27,9 +27,9 @@ from pathlib import Path
 
 from .. import supervise as _supervise
 from ..backend import (
-    ActiveBottle,
+    ActiveAgent,
     BottleSpec,
-    enumerate_active_bottles,
+    enumerate_active_agents,
     get_bottle_backend,
     known_backend_names,
 )
@@ -97,22 +97,13 @@ class QueuedProposal:
     queue_dir: Path
 
 
-# `ActiveAgent` was PRD-0019's docker-specific row type. It now
-# aliases the shared `ActiveBottle` dataclass so the dashboard
-# and the CLI `list active` both render the same source of truth.
-# Field surface stays compatible (slug / agent_name / started_at
-# / services) plus a new `backend_name` so dashboard rows can
-# show which backend a bottle came from.
-ActiveAgent = ActiveBottle
-
-
-def discover_active_agents() -> list[ActiveBottle]:
-    """All currently-running bottles across every backend with
+def discover_active_agents() -> list[ActiveAgent]:
+    """All currently-running agents across every backend with
     their metadata + service set. Returns [] when neither
     backend is reachable. Backed by the shared
-    `enumerate_active_bottles` helper so the CLI's
+    `enumerate_active_agents` helper so the CLI's
     `./cli.py list active` and this dashboard show the same data."""
-    return enumerate_active_bottles()
+    return enumerate_active_agents()
 
 
 

claude_bottle/cli/list.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 import argparse
 import sys
 
-from ..backend import enumerate_active_bottles
+from ..backend import enumerate_active_agents
 from ..manifest import Manifest
 from ._common import PROG, USER_CWD
 
@@ -23,7 +23,7 @@ def cmd_list(argv: list[str]) -> int:
 
     # `active` enumerates every backend (docker + smolmachines)
     # so smolmachines bottles aren't hidden behind the env var.
-    active = enumerate_active_bottles()
+    active = enumerate_active_agents()
     if not active:
         print("no active claude-bottle bottles", file=sys.stderr)
         return 0

tests/unit/test_backend_selection.py

@@ -1,8 +1,8 @@
 """Unit: backend selection + cross-backend enumeration (issue #77).
 
 `get_bottle_backend(name)` resolves a backend by explicit name,
-env var, or default. `enumerate_active_bottles()` walks every
-registered backend and concatenates their `ActiveBottle`
+env var, or default. `enumerate_active_agents()` walks every
+registered backend and concatenates their `ActiveAgent`
 listings — the CLI and dashboard both go through this so adding
 a backend lights it up in both places."""
 
@@ -14,8 +14,8 @@ from unittest.mock import patch
 
 from claude_bottle import backend as backend_mod
 from claude_bottle.backend import (
-    ActiveBottle,
-    enumerate_active_bottles,
+    ActiveAgent,
+    enumerate_active_agents,
     get_bottle_backend,
     known_backend_names,
 )
@@ -48,25 +48,29 @@ class TestKnownBackendNames(unittest.TestCase):
         self.assertEqual(("docker", "smolmachines"), known_backend_names())
 
 
-class TestEnumerateActiveBottles(unittest.TestCase):
+class TestEnumerateActiveAgents(unittest.TestCase):
     """Combines each backend's `enumerate_active`. Each backend's
     implementation has its own tests (`test_docker_enumerate_active`,
     `test_smolmachines_*`); this just asserts the aggregator stitches
     them together."""
 
     def test_concatenates_per_backend(self):
-        a = ActiveBottle(
+        a = ActiveAgent(
             backend_name="docker", slug="a-1", agent_name="impl",
             started_at="", services=("pipelock",),
         )
-        b = ActiveBottle(
+        b = ActiveAgent(
             backend_name="smolmachines", slug="b-2", agent_name="research",
             started_at="", services=(),
         )
 
         class _FakeBackend:
-            def __init__(self, items):
+            def __init__(self, items, available=True):
                 self._items = items
+                self._available = available
+
+            def is_available(self):
+                return self._available
 
             def enumerate_active(self):
                 return self._items
@@ -75,10 +79,13 @@ class TestEnumerateActiveBottles(unittest.TestCase):
             backend_mod, "_BACKENDS",
             {"docker": _FakeBackend([a]), "smolmachines": _FakeBackend([b])},
         ):
-            self.assertEqual([a, b], enumerate_active_bottles())
+            self.assertEqual([a, b], enumerate_active_agents())
 
     def test_empty_when_no_backends_have_active(self):
         class _FakeBackend:
+            def is_available(self):
+                return True
+
             def enumerate_active(self):
                 return []
 
@@ -86,7 +93,58 @@ class TestEnumerateActiveBottles(unittest.TestCase):
             backend_mod, "_BACKENDS",
             {"docker": _FakeBackend(), "smolmachines": _FakeBackend()},
         ):
-            self.assertEqual([], enumerate_active_bottles())
+            self.assertEqual([], enumerate_active_agents())
+
+    def test_skips_unavailable_backends(self):
+        # If a backend's runtime isn't installed (smolvm missing on
+        # a docker-only host, or docker missing on a smolmachines-
+        # only host), the cross-backend enumerator skips it rather
+        # than dying — `has_backend` gates the iteration.
+        present = ActiveAgent(
+            backend_name="docker", slug="a-1", agent_name="impl",
+            started_at="", services=(),
+        )
+        hidden = ActiveAgent(
+            backend_name="smolmachines", slug="x", agent_name="x",
+            started_at="", services=(),
+        )
+
+        class _FakeBackend:
+            def __init__(self, items, available):
+                self._items = items
+                self._available = available
+
+            def is_available(self):
+                return self._available
+
+            def enumerate_active(self):
+                return self._items
+
+        with patch.object(
+            backend_mod, "_BACKENDS",
+            {
+                "docker": _FakeBackend([present], available=True),
+                "smolmachines": _FakeBackend([hidden], available=False),
+            },
+        ):
+            self.assertEqual([present], enumerate_active_agents())
+
+
+class TestHasBackend(unittest.TestCase):
+    def test_known_backend_consults_is_available(self):
+        class _FakeBackend:
+            def is_available(self):
+                return False
+
+        with patch.object(
+            backend_mod, "_BACKENDS", {"docker": _FakeBackend()},
+        ):
+            from claude_bottle.backend import has_backend
+            self.assertFalse(has_backend("docker"))
+
+    def test_unknown_backend_returns_false(self):
+        from claude_bottle.backend import has_backend
+        self.assertFalse(has_backend("nonexistent"))
 
 
 if __name__ == "__main__":

tests/unit/test_cli_cleanup_cross_backend.py

@@ -0,0 +1,105 @@
+"""Unit: `cli.py cleanup` walks every backend (issue follow-up).
+
+Asserts cmd_cleanup queries each backend's `prepare_cleanup`,
+combines the y/N output, and runs each backend's `cleanup` when
+the operator confirms.  Mocks the backends and stdin."""
+
+from __future__ import annotations
+
+import sys
+import unittest
+from unittest.mock import patch, MagicMock
+
+from claude_bottle.cli import cleanup as cmd
+
+
+def _make_backend(empty: bool = True):
+    backend = MagicMock()
+    plan = MagicMock(empty=empty)
+    backend.prepare_cleanup.return_value = plan
+    backend.cleanup = MagicMock()
+    return backend, plan
+
+
+class TestCmdCleanup(unittest.TestCase):
+    def test_iterates_every_backend(self):
+        docker, docker_plan = _make_backend(empty=False)
+        smol, smol_plan = _make_backend(empty=False)
+        backends_by_name = {"docker": docker, "smolmachines": smol}
+
+        with patch.object(
+            cmd, "known_backend_names",
+            return_value=("docker", "smolmachines"),
+        ), patch.object(
+            cmd, "get_bottle_backend",
+            side_effect=lambda name: backends_by_name[name],
+        ), patch.object(
+            cmd, "_prompt_yes", return_value=True,
+        ):
+            self.assertEqual(0, cmd.cmd_cleanup([]))
+
+        docker.prepare_cleanup.assert_called_once()
+        smol.prepare_cleanup.assert_called_once()
+        docker.cleanup.assert_called_once_with(docker_plan)
+        smol.cleanup.assert_called_once_with(smol_plan)
+
+    def test_short_circuits_when_all_empty(self):
+        docker, _ = _make_backend(empty=True)
+        smol, _ = _make_backend(empty=True)
+        backends_by_name = {"docker": docker, "smolmachines": smol}
+
+        with patch.object(
+            cmd, "known_backend_names",
+            return_value=("docker", "smolmachines"),
+        ), patch.object(
+            cmd, "get_bottle_backend",
+            side_effect=lambda name: backends_by_name[name],
+        ), patch.object(
+            cmd, "_prompt_yes",
+        ) as prompt:
+            self.assertEqual(0, cmd.cmd_cleanup([]))
+        prompt.assert_not_called()
+        docker.cleanup.assert_not_called()
+        smol.cleanup.assert_not_called()
+
+    def test_abort_at_prompt_runs_nothing(self):
+        docker, _ = _make_backend(empty=False)
+        smol, _ = _make_backend(empty=True)
+        backends_by_name = {"docker": docker, "smolmachines": smol}
+
+        with patch.object(
+            cmd, "known_backend_names",
+            return_value=("docker", "smolmachines"),
+        ), patch.object(
+            cmd, "get_bottle_backend",
+            side_effect=lambda name: backends_by_name[name],
+        ), patch.object(
+            cmd, "_prompt_yes", return_value=False,
+        ):
+            self.assertEqual(0, cmd.cmd_cleanup([]))
+        docker.cleanup.assert_not_called()
+        smol.cleanup.assert_not_called()
+
+    def test_skips_empty_plans_when_others_have_work(self):
+        # docker has work, smolmachines doesn't — only docker.cleanup
+        # is called.
+        docker, docker_plan = _make_backend(empty=False)
+        smol, _ = _make_backend(empty=True)
+        backends_by_name = {"docker": docker, "smolmachines": smol}
+
+        with patch.object(
+            cmd, "known_backend_names",
+            return_value=("docker", "smolmachines"),
+        ), patch.object(
+            cmd, "get_bottle_backend",
+            side_effect=lambda name: backends_by_name[name],
+        ), patch.object(
+            cmd, "_prompt_yes", return_value=True,
+        ):
+            cmd.cmd_cleanup([])
+        docker.cleanup.assert_called_once_with(docker_plan)
+        smol.cleanup.assert_not_called()
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/unit/test_dashboard_active_agents.py

@@ -1,11 +1,4 @@
-"""Unit: dashboard's row-formatting + selection helpers (PRD 0019).
-
-The active-bottle enumeration tests moved to
-`test_docker_enumerate_active.py` (issue #77) — dashboard now
-delegates listing to `enumerate_active_bottles` so the parser
-and assembly tests live next to the docker backend's
-implementation.
-"""
+"""Unit: dashboard's row-formatting + selection helpers (PRD 0019)."""
 
 from __future__ import annotations
 

tests/unit/test_docker_cleanup.py

@@ -44,7 +44,7 @@ class TestOrphanStateDirs(_FakeHomeMixin, unittest.TestCase):
         self._teardown_fake_home()
 
     def test_no_state_root_returns_empty(self):
-        self.assertEqual([], _list_orphan_state_dirs(set()))
+        self.assertEqual([], _list_orphan_state_dirs(set(), set()))
 
     def test_state_dir_with_no_live_no_preserve_is_orphan(self):
         # Just touch the dir; no metadata, no preserve marker — the
@@ -52,7 +52,7 @@ class TestOrphanStateDirs(_FakeHomeMixin, unittest.TestCase):
         bottle_state.write_per_bottle_dockerfile("solo-aaa", "FROM x\n")
         self.assertEqual(
             ["solo-aaa"],
-            _list_orphan_state_dirs(set()),
+            _list_orphan_state_dirs(set(), set()),
         )
 
     def test_live_project_skips_dir(self):
@@ -61,7 +61,7 @@ class TestOrphanStateDirs(_FakeHomeMixin, unittest.TestCase):
         bottle_state.write_per_bottle_dockerfile("live-bbb", "FROM x\n")
         self.assertEqual(
             [],
-            _list_orphan_state_dirs({"claude-bottle-live-bbb"}),
+            _list_orphan_state_dirs({"claude-bottle-live-bbb"}, set()),
         )
 
     def test_preserve_marker_skips_dir(self):
@@ -71,14 +71,14 @@ class TestOrphanStateDirs(_FakeHomeMixin, unittest.TestCase):
         bottle_state.mark_preserved("kept-ccc")
         self.assertEqual(
             [],
-            _list_orphan_state_dirs(set()),
+            _list_orphan_state_dirs(set(), set()),
         )
 
     def test_preserve_overrides_no_live_project(self):
         # Even without a live project, a preserve marker keeps it.
         bottle_state.write_per_bottle_dockerfile("kept-ddd", "FROM x\n")
         bottle_state.mark_preserved("kept-ddd")
-        self.assertEqual([], _list_orphan_state_dirs(set()))
+        self.assertEqual([], _list_orphan_state_dirs(set(), set()))
 
     def test_mixed_set_categorized_correctly(self):
         bottle_state.write_per_bottle_dockerfile("orphan-eee", "FROM x\n")
@@ -86,7 +86,7 @@ class TestOrphanStateDirs(_FakeHomeMixin, unittest.TestCase):
         bottle_state.write_per_bottle_dockerfile("kept-ggg", "FROM z\n")
         bottle_state.mark_preserved("kept-ggg")
 
-        result = _list_orphan_state_dirs({"claude-bottle-live-fff"})
+        result = _list_orphan_state_dirs({"claude-bottle-live-fff"}, set())
         self.assertEqual(["orphan-eee"], result)
 
     def test_sorted_output(self):
@@ -94,7 +94,31 @@ class TestOrphanStateDirs(_FakeHomeMixin, unittest.TestCase):
             bottle_state.write_per_bottle_dockerfile(name, "FROM x\n")
         self.assertEqual(
             ["aaa-1", "mmm-1", "zzz-1"],
-            _list_orphan_state_dirs(set()),
+            _list_orphan_state_dirs(set(), set()),
+        )
+
+    def test_protected_identity_skips_dir(self):
+        # `protected_identities` carries slugs that are live in
+        # any backend (smolmachines included). docker's orphan
+        # detection respects them so a running smolmachines
+        # bottle's state dir isn't reaped while the VM is up.
+        bottle_state.write_per_bottle_dockerfile("smol-hhh", "FROM x\n")
+        self.assertEqual(
+            [],
+            _list_orphan_state_dirs(set(), {"smol-hhh"}),
+        )
+
+    def test_protected_overrides_no_live_project(self):
+        # A smolmachines bottle has no docker compose project but
+        # IS in the protected set; the absence of a project
+        # shouldn't cause a reap.
+        bottle_state.write_per_bottle_dockerfile("smol-iii", "FROM x\n")
+        self.assertEqual(
+            [],
+            _list_orphan_state_dirs(
+                {"claude-bottle-something-else"},  # different project up
+                {"smol-iii"},                       # but smol-iii is live
+            ),
         )
 
 

tests/unit/test_docker_enumerate_active.py

@@ -8,7 +8,7 @@ unit test. Tests split into:
     no I/O, deterministic on its input string.
   - Integration-shaped tests that monkeypatch the slug list +
     services map and read metadata from a fake home, then assert
-    the assembled `ActiveBottle` shape.
+    the assembled `ActiveAgent` shape.
 
 The actual `docker ps` invocation is exercised by manual probing
 during development and the (real-docker) integration tests; here
@@ -24,21 +24,21 @@ import unittest
 from pathlib import Path
 
 from claude_bottle import supervise
-from claude_bottle.backend.docker import bottle_state, cleanup
+from claude_bottle.backend.docker import bottle_state, enumerate as _enumerate
 
 
 class TestParseServicesByProject(unittest.TestCase):
     def test_empty_input(self):
-        self.assertEqual({}, cleanup._parse_services_by_project(""))
+        self.assertEqual({}, _enumerate._parse_services_by_project(""))
 
     def test_one_container(self):
-        out = cleanup._parse_services_by_project(
+        out = _enumerate._parse_services_by_project(
             "claude-bottle-dev-abc\tegress\n"
         )
         self.assertEqual({"claude-bottle-dev-abc": {"egress"}}, out)
 
     def test_multiple_services_per_project(self):
-        out = cleanup._parse_services_by_project(
+        out = _enumerate._parse_services_by_project(
             "claude-bottle-dev-abc\tegress\n"
             "claude-bottle-dev-abc\tpipelock\n"
             "claude-bottle-dev-abc\tsupervise\n"
@@ -49,7 +49,7 @@ class TestParseServicesByProject(unittest.TestCase):
         )
 
     def test_multiple_projects(self):
-        out = cleanup._parse_services_by_project(
+        out = _enumerate._parse_services_by_project(
             "proj-a\tegress\n"
             "proj-b\tpipelock\n"
             "proj-a\tsupervise\n"
@@ -62,7 +62,7 @@ class TestParseServicesByProject(unittest.TestCase):
     def test_skips_lines_missing_either_field(self):
         # Defends against unlabeled containers slipping into the
         # output (the filter should prevent it, but be robust).
-        out = cleanup._parse_services_by_project(
+        out = _enumerate._parse_services_by_project(
             "claude-bottle-dev-abc\tegress\n"
             "no-tab-here\n"
             "\tmissing-project\n"
@@ -90,28 +90,21 @@ class _FakeHomeMixin:
 class TestEnumerateActive(_FakeHomeMixin, unittest.TestCase):
     def setUp(self) -> None:
         self._setup_fake_home()
-        self._orig_slugs = cleanup.list_active_slugs
-        self._orig_services = cleanup._query_services_by_project
-        # Skip the docker-availability gate so tests don't need a
-        # real docker on PATH.
-        import shutil
-        self._orig_which = shutil.which
-        shutil.which = lambda name: "/usr/bin/" + name if name == "docker" else None
+        self._orig_slugs = _enumerate.list_active_slugs
+        self._orig_services = _enumerate._query_services_by_project
 
     def tearDown(self) -> None:
-        cleanup.list_active_slugs = self._orig_slugs
-        cleanup._query_services_by_project = self._orig_services
-        import shutil
-        shutil.which = self._orig_which
+        _enumerate.list_active_slugs = self._orig_slugs
+        _enumerate._query_services_by_project = self._orig_services
         self._teardown_fake_home()
 
     def _stub(self, slugs: list[str], services_by_project: dict[str, set[str]]) -> None:
-        cleanup.list_active_slugs = lambda **_: slugs
-        cleanup._query_services_by_project = lambda: services_by_project
+        _enumerate.list_active_slugs = lambda **_: slugs
+        _enumerate._query_services_by_project = lambda: services_by_project
 
     def test_no_active_slugs_returns_empty(self):
         self._stub([], {})
-        self.assertEqual([], cleanup.enumerate_active())
+        self.assertEqual([], _enumerate.enumerate_active())
 
     def test_assembles_from_metadata_and_services(self):
         bottle_state.write_metadata(bottle_state.BottleMetadata(
@@ -126,7 +119,7 @@ class TestEnumerateActive(_FakeHomeMixin, unittest.TestCase):
             ["dev-abc"],
             {"claude-bottle-dev-abc": {"pipelock", "egress", "supervise"}},
         )
-        active = cleanup.enumerate_active()
+        active = _enumerate.enumerate_active()
         self.assertEqual(1, len(active))
         a = active[0]
         self.assertEqual("docker", a.backend_name)
@@ -139,7 +132,7 @@ class TestEnumerateActive(_FakeHomeMixin, unittest.TestCase):
         # State dir doesn't exist for this slug — agent_name falls
         # back to "?" rather than dropping the row.
         self._stub(["mystery-zzz"], {"claude-bottle-mystery-zzz": {"pipelock"}})
-        active = cleanup.enumerate_active()
+        active = _enumerate.enumerate_active()
         self.assertEqual(1, len(active))
         self.assertEqual("?", active[0].agent_name)
         self.assertEqual("", active[0].started_at)
@@ -158,7 +151,7 @@ class TestEnumerateActive(_FakeHomeMixin, unittest.TestCase):
             compose_project="claude-bottle-warming-up",
         ))
         self._stub(["warming-up"], {})
-        active = cleanup.enumerate_active()
+        active = _enumerate.enumerate_active()
         self.assertEqual((), active[0].services)
 
     def test_preserves_slug_order(self):
@@ -174,21 +167,12 @@ class TestEnumerateActive(_FakeHomeMixin, unittest.TestCase):
         # list_active_slugs returns sorted; preserve that order in
         # the output.
         self._stub(["a-1", "m-1", "z-1"], {})
-        active = cleanup.enumerate_active()
+        active = _enumerate.enumerate_active()
         self.assertEqual(
             ["a-1", "m-1", "z-1"],
             [a.slug for a in active],
         )
 
-    def test_noop_when_docker_missing(self):
-        # Defensive: list active shouldn't die just because docker
-        # isn't on PATH (smolmachines bottles are still discoverable
-        # via the other backend's enumerate).
-        import shutil
-        shutil.which = lambda _name: None
-        self._stub(["some-slug"], {})
-        self.assertEqual([], cleanup.enumerate_active())
-
 
 if __name__ == "__main__":
     unittest.main()

tests/unit/test_smolmachines_cleanup.py

@@ -0,0 +1,148 @@
+"""Unit: smolmachines backend cleanup (`cleanup.py` +
+`bottle_cleanup_plan.py`).
+
+Tests mock `subprocess.run` + `has_backend` so they execute
+without docker / smolvm on PATH. Each cleanup step verifies argv
+shape; teardown verifies order (machines → bundles → networks)."""
+
+from __future__ import annotations
+
+import subprocess
+import unittest
+from unittest.mock import patch
+
+from claude_bottle import backend as backend_mod
+from claude_bottle.backend.smolmachines import cleanup
+from claude_bottle.backend.smolmachines.bottle_cleanup_plan import (
+    SmolmachinesBottleCleanupPlan,
+)
+
+
+def _ok(stdout: str = "", stderr: str = "") -> subprocess.CompletedProcess:
+    return subprocess.CompletedProcess(
+        args=[], returncode=0, stdout=stdout, stderr=stderr,
+    )
+
+
+class TestPrepareCleanup(unittest.TestCase):
+    def test_empty_when_nothing_running(self):
+        with patch.object(cleanup, "_smolvm") as smolvm, \
+             patch.object(cleanup.subprocess, "run") as run, \
+             patch.object(backend_mod, "has_backend", return_value=True):
+            smolvm.is_available.return_value = True
+            run.return_value = _ok(stdout="[]")
+            plan = cleanup.prepare_cleanup()
+        self.assertTrue(plan.empty)
+
+    def test_lists_machines_bundles_networks(self):
+        def fake_run(argv, *a, **kw):
+            if argv[:3] == ["smolvm", "machine", "ls"]:
+                return _ok(stdout=(
+                    '[{"name":"claude-bottle-a-1","state":"running"},'
+                    ' {"name":"claude-bottle-b-2","state":"created"},'
+                    ' {"name":"unrelated","state":"running"}]'
+                ))
+            if argv[:2] == ["docker", "ps"]:
+                return _ok(stdout=(
+                    "claude-bottle-sidecars-a-1\n"
+                    "claude-bottle-sidecars-b-2\n"
+                ))
+            if argv[:3] == ["docker", "network", "ls"]:
+                return _ok(stdout=(
+                    "claude-bottle-bundle-a-1\n"
+                    "claude-bottle-bundle-b-2\n"
+                ))
+            return _ok()
+
+        with patch.object(cleanup, "_smolvm") as smolvm, \
+             patch.object(cleanup.subprocess, "run", side_effect=fake_run), \
+             patch.object(backend_mod, "has_backend", return_value=True):
+            smolvm.is_available.return_value = True
+            plan = cleanup.prepare_cleanup()
+
+        # `unrelated` filtered out (no claude-bottle- prefix).
+        self.assertEqual(
+            ("claude-bottle-a-1", "claude-bottle-b-2"),
+            plan.machines,
+        )
+        self.assertEqual(
+            ("claude-bottle-sidecars-a-1", "claude-bottle-sidecars-b-2"),
+            plan.bundles,
+        )
+        self.assertEqual(
+            ("claude-bottle-bundle-a-1", "claude-bottle-bundle-b-2"),
+            plan.networks,
+        )
+
+    def test_no_smolvm_means_no_machines(self):
+        with patch.object(cleanup, "_smolvm") as smolvm, \
+             patch.object(cleanup.subprocess, "run", return_value=_ok()), \
+             patch.object(backend_mod, "has_backend", return_value=True):
+            smolvm.is_available.return_value = False
+            plan = cleanup.prepare_cleanup()
+        self.assertEqual((), plan.machines)
+
+
+class TestCleanup(unittest.TestCase):
+    def test_machines_stopped_then_deleted_then_bundles_then_networks(self):
+        plan = SmolmachinesBottleCleanupPlan(
+            machines=("claude-bottle-a-1",),
+            bundles=("claude-bottle-sidecars-a-1",),
+            networks=("claude-bottle-bundle-a-1",),
+        )
+        calls: list[list[str]] = []
+
+        def fake_run(argv, *a, **kw):
+            calls.append(list(argv[:4]))
+            return _ok()
+
+        with patch.object(cleanup.subprocess, "run", side_effect=fake_run):
+            cleanup.cleanup(plan)
+
+        # Stop precedes delete precedes bundle rm precedes network rm.
+        self.assertEqual(
+            ["smolvm", "machine", "stop", "--name"], calls[0],
+        )
+        self.assertEqual(
+            ["smolvm", "machine", "delete", "-f"], calls[1],
+        )
+        self.assertEqual(
+            ["docker", "rm", "-f", "claude-bottle-sidecars-a-1"], calls[2],
+        )
+        self.assertEqual(
+            ["docker", "network", "rm", "claude-bottle-bundle-a-1"], calls[3],
+        )
+
+    def test_failures_are_warnings_not_fatal(self):
+        # smolvm machine delete -f returning non-zero should warn
+        # but continue with bundles + networks. The cleanup is
+        # idempotent on success and tries to remove every resource.
+        plan = SmolmachinesBottleCleanupPlan(
+            machines=("claude-bottle-a-1",),
+            bundles=("claude-bottle-sidecars-a-1",),
+            networks=(),
+        )
+        results = iter([
+            _ok(),  # stop succeeds
+            subprocess.CompletedProcess(args=[], returncode=1, stdout="", stderr="boom"),  # delete fails
+            _ok(),  # bundle rm succeeds
+        ])
+
+        def fake_run(argv, *a, **kw):
+            return next(results)
+
+        with patch.object(cleanup.subprocess, "run", side_effect=fake_run), \
+             patch.object(cleanup, "warn") as warn:
+            cleanup.cleanup(plan)
+        # warn called once for the delete failure.
+        warn.assert_called_once()
+
+    def test_empty_plan_is_noop(self):
+        plan = SmolmachinesBottleCleanupPlan()
+        with patch.object(cleanup.subprocess, "run") as run:
+            cleanup.cleanup(plan)
+        run.assert_not_called()
+
+
+if __name__ == "__main__":
+    unittest.main()