docs(research): update landscape doc — SuperHQ, multi-backend, multi-provider, in-flight directions

- Broaden scope from "Claude Code in Docker" to "AI coding agents in isolated sandboxes" - Add SuperHQ (superhq.ai, v0.4.4) as a new adjacent-competitor entry: macOS-only microVM desktop app, overlaps on isolation/credential-proxy/multi-provider but has no manifest layer and no audit logging - Note SuperHQ's user-voiced audit gap (Brian Cheong, Dunialabs.io) and that bot-bottle already covers it - Update differentiation list to reflect three backends (Docker, Apple container, smolmachines) and three built-in providers (Claude Code, Codex, Pi) plus plugin system - Add in-flight directions for forge-native dispatch (#317) and paid web control plane (#327) with honest framing: lifecycle concept is not novel vs. cloud services (Devin, Copilot Workspace); differentiation is self-hosted + manifest-driven + stronger isolation
2026-07-09 18:55:15 +00:00
44 changed files with 750 additions and 2687 deletions
@@ -36,10 +36,10 @@ import os
 import shlex
 import sys
 from abc import ABC, abstractmethod
-from contextlib import AbstractContextManager, contextmanager
+from contextlib import AbstractContextManager
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Any, Generator, Generic, Sequence, TypeVar
+from typing import Any, Generic, Sequence, TypeVar
 from ..agent_provider import AgentProvisionPlan, get_provider, build_agent_provision_plan
 from ..egress import EgressPlan
@@ -78,9 +78,6 @@ class BottleSpec:
    # True when launched via --headless (no TTY, no interactive prompts).
    # The git-gate host-key preflight uses this to error rather than prompt.
    headless: bool = False
    # Image startup policy. "fresh" preserves the normal build path;
    # "cached" reuses the current local image/artifact without rebuilding.
    image_policy: str = "fresh"
@dataclass(frozen=True)
@@ -276,18 +273,6 @@ PlanT = TypeVar("PlanT", bound=BottlePlan)
 CleanupT = TypeVar("CleanupT", bound=BottleCleanupPlan)
@dataclass(frozen=True)
 class BottleImages:
    """Resolved image references (or artifact paths) for a bottle launch.
    For Docker/macOS-container backends, `agent` and `sidecar` are string
    image refs. For the smolmachines backend they are Path objects pointing
    to pre-built `.smolmachine` artifacts."""
    agent: str | Path
    sidecar: str | Path
 class BottleBackend(ABC, Generic[PlanT, CleanupT]):
    """Abstract base for selectable bottle backends. Concrete subclasses
    (e.g. DockerBottleBackend) own their own prepare/launch impls.
@@ -447,27 +432,9 @@ class BottleBackend(ABC, Generic[PlanT, CleanupT]):
        prompt file, Dockerfile path, and guest home all live on
        `agent_provision_plan` — the source of truth."""
    def prelaunch_checks(self, plan: PlanT) -> None:
        """Raise StaleImageError if any cached image used by this plan is stale.
        No-op default; backends override to call the shared check_stale*
        helpers on their image/artifact timestamps. Called by the CLI before
        launch so the operator can be prompted outside the launch context."""
    @contextmanager
    def launch(self, plan: PlanT) -> Generator[Bottle, None, None]:
        """Template: build or load images, then delegate to _launch_impl."""
        images = self._build_or_load_images(plan)
        with self._launch_impl(plan, images) as bottle:
            yield bottle
    @abstractmethod
-    def _build_or_load_images(self, plan: PlanT) -> BottleImages:
+    def launch(self, plan: PlanT) -> AbstractContextManager[Bottle]:
-        """Return the agent and sidecar image references (or artifact paths)
+        """Build/run the bottle and yield a handle; tear down on exit."""
        for this plan, building fresh images when the policy requires it."""
    @abstractmethod
    def _launch_impl(self, plan: PlanT, images: BottleImages) -> AbstractContextManager[Bottle]:
        """Bring up the bottle using pre-resolved images; yield a handle; tear down on exit."""
    def provision(self, plan: PlanT, bottle: "Bottle") -> str | None:
        """Copy host-side files (CA cert, prompt, skills, .git) into
@@ -31,7 +31,7 @@ from ...env import ResolvedEnv
 from ...git_gate import GitGatePlan
 from ...supervise import SupervisePlan
 from ...manifest import Manifest
-from .. import ActiveAgent, BottleBackend, BottleImages, BottleSpec
+from .. import ActiveAgent, BottleBackend, BottleSpec
 from . import cleanup as _cleanup
 from . import enumerate as _enumerate
 from . import launch as _launch
@@ -85,15 +85,9 @@ class DockerBottleBackend(BottleBackend["DockerBottlePlan", "DockerBottleCleanup
            stage_dir=stage_dir,
        )
    def prelaunch_checks(self, plan: DockerBottlePlan) -> None:
        _launch.stale_checks(plan)
    def _build_or_load_images(self, plan: DockerBottlePlan) -> BottleImages:
        return _launch.build_or_load_images(plan)
    @contextmanager
-    def _launch_impl(self, plan: DockerBottlePlan, images: BottleImages) -> Generator[DockerBottle, None, None]:
+    def launch(self, plan: DockerBottlePlan) -> Generator[DockerBottle, None, None]:
-        with _launch.launch(plan, images, provision=self.provision) as bottle:
+        with _launch.launch(plan, provision=self.provision) as bottle:
            yield bottle
    def supervise_mcp_url(self, plan: DockerBottlePlan) -> str:
@@ -180,6 +180,10 @@ def _sidecar_bundle_service(plan: DockerBottlePlan) -> dict[str, Any]:
    service: dict[str, Any] = {
        "image": SIDECAR_BUNDLE_IMAGE,
        "build": {
            "context": _REPO_DIR,
            "dockerfile": SIDECAR_BUNDLE_DOCKERFILE,
        },
        "container_name": sidecar_bundle_container_name(plan.slug),
        "networks": {
            "internal": {"aliases": internal_aliases},
@@ -188,11 +192,6 @@ def _sidecar_bundle_service(plan: DockerBottlePlan) -> dict[str, Any]:
        "environment": env,
        "volumes": volumes,
    }
    if plan.spec.image_policy != "cached":
        service["build"] = {
            "context": _REPO_DIR,
            "dockerfile": SIDECAR_BUNDLE_DOCKERFILE,
        }
    return service
@@ -41,9 +41,7 @@ from ...git_gate import (
    provision_git_gate_dynamic_keys,
    revoke_git_gate_provisioned_keys,
 )
-from ...image_cache import check_stale
+from ...log import info, warn
 from ...log import die, info, warn
 from .. import BottleImages
 from . import network as network_mod
 from . import util as docker_mod
 from .bottle import DockerBottle
@@ -65,57 +63,22 @@ from .compose import (
    write_compose_file,
 )
 from .egress import egress_tls_init
 from .sidecar_bundle import SIDECAR_BUNDLE_IMAGE
 # Where the repo root lives, for `docker build` context. Computed once.
 _REPO_DIR = str(Path(__file__).resolve().parent.parent.parent.parent)
 def build_or_load_images(plan: DockerBottlePlan) -> BottleImages:
    """Resolve the agent and sidecar image refs for this plan.
    Returns the committed snapshot if one exists, the local cached images
    when the policy is 'cached', or builds fresh images and returns those."""
    committed = read_committed_image(plan.slug)
    if committed and docker_mod.image_exists(committed):
        info(f"using committed image {committed!r}")
        return BottleImages(agent=committed, sidecar=SIDECAR_BUNDLE_IMAGE)
    if plan.spec.image_policy == "cached":
        if not docker_mod.image_exists(plan.image):
            die(
                f"cached agent image {plan.image!r} not found; "
                "run without --cached-images to build it"
            )
        if not docker_mod.image_exists(SIDECAR_BUNDLE_IMAGE):
            die(
                f"cached sidecar image {SIDECAR_BUNDLE_IMAGE!r} not found; "
                "run without --cached-images to build it"
            )
        info(f"using cached agent image {plan.image!r}")
        info(f"using cached sidecar image {SIDECAR_BUNDLE_IMAGE!r}")
        return BottleImages(agent=plan.image, sidecar=SIDECAR_BUNDLE_IMAGE)
    docker_mod.build_image(plan.image, _REPO_DIR, dockerfile=plan.dockerfile_path)
    return BottleImages(agent=plan.image, sidecar=SIDECAR_BUNDLE_IMAGE)
@contextmanager
 def launch(
    plan: DockerBottlePlan,
    images: BottleImages,
    *,
    provision: Callable[[DockerBottlePlan, "DockerBottle"], str | None],
 ) -> Generator[DockerBottle, None, None]:
-    """Launch and provision a Docker bottle via compose. Teardown on exit."""
+    """Build, launch, and provision a Docker bottle via compose.
    Teardown on exit."""
    stack = ExitStack()
    # Stamp the resolved agent image ref into the plan so compose rendering
    # picks up the right image (may be a committed snapshot or cached ref).
    plan = dataclasses.replace(
        plan,
        agent_provision=dataclasses.replace(plan.agent_provision, image=str(images.agent)),
    )
    _bottle_for_revoke = plan.manifest.bottle
    _git_gate_dir_for_revoke = git_gate_state_dir(plan.slug)
@@ -132,6 +95,22 @@ def launch(
        )
    try:
        # Step 1: agent image. Use a committed snapshot when one exists
        # and is present in the local daemon; otherwise build from the
        # Dockerfile. Sidecar images get built lazily by `docker compose
        # up` via the renderer's `build:` directives.
        committed = read_committed_image(plan.slug)
        if committed and docker_mod.image_exists(committed):
            info(f"using committed image {committed!r}")
            plan = dataclasses.replace(
                plan,
                agent_provision=dataclasses.replace(plan.agent_provision, image=committed),
            )
        else:
            docker_mod.build_image(
                plan.image, _REPO_DIR,
                dockerfile=plan.dockerfile_path,
            )
        internal_network = network_mod.network_name_for_slug(plan.slug)
        egress_network = network_mod.network_egress_name_for_slug(plan.slug)
@@ -228,21 +207,3 @@ def launch(
        yield bottle
    finally:
        teardown()
 def stale_checks(plan: DockerBottlePlan) -> None:
    """Raise StaleImageError if a cached image is older than the configured
    threshold. Only runs when image_policy is 'cached'. Called by the backend
    class's _image_stale_checks before _launch_impl starts any resources."""
    if plan.spec.image_policy != "cached":
        return
    committed = read_committed_image(plan.slug)
    if committed and docker_mod.image_exists(committed):
        check_stale(f"agent image {committed!r}", docker_mod.image_created_at(committed))
        return
    for label, ref in [
        ("agent image", plan.image),
        ("sidecar image", SIDECAR_BUNDLE_IMAGE),
    ]:
        if docker_mod.image_exists(ref):
            check_stale(f"{label} {ref!r}", docker_mod.image_created_at(ref))
@@ -4,7 +4,6 @@ existence, and building images."""
 from __future__ import annotations
 from datetime import datetime, timezone
 import re
 import shutil
 import subprocess
@@ -187,45 +186,6 @@ def image_id(ref: str) -> str:
    return r.stdout.strip()
 def image_created_at(ref: str) -> datetime:
    """Return Docker's image Created timestamp as an aware UTC datetime."""
    r = subprocess.run(
        ["docker", "image", "inspect", "--format", "{{.Created}}", ref],
        capture_output=True,
        text=True,
        check=False,
    )
    if r.returncode != 0:
        die(
            f"docker image inspect for {ref!r} failed: "
            f"{(r.stderr or '').strip() or '<no stderr>'}"
        )
    raw = r.stdout.strip()
    try:
        return _parse_docker_timestamp(raw)
    except ValueError:
        die(f"docker image inspect for {ref!r} returned invalid Created timestamp: {raw!r}")
 def _parse_docker_timestamp(raw: str) -> datetime:
    text = raw.strip()
    if text.endswith("Z"):
        text = text[:-1] + "+00:00"
    dot = text.find(".")
    if dot != -1:
        tz_plus = text.find("+", dot)
        tz_minus = text.find("-", dot)
        tz_candidates = [pos for pos in (tz_plus, tz_minus) if pos != -1]
        if tz_candidates:
            tz_pos = min(tz_candidates)
            frac = text[dot + 1:tz_pos]
            text = text[:dot + 1] + frac[:6].ljust(6, "0") + text[tz_pos:]
    dt = datetime.fromisoformat(text)
    if dt.tzinfo is None:
        dt = dt.replace(tzinfo=timezone.utc)
    return dt.astimezone(timezone.utc)
 def save(ref: str, output: str) -> None:
    """`docker save REF -o OUTPUT`. Writes a tarball of the image
    layers + manifest to the host path. Used by smolmachines
@@ -12,7 +12,7 @@ from ...env import ResolvedEnv
 from ...git_gate import GitGatePlan
 from ...supervise import SupervisePlan
 from ...manifest import Manifest
-from .. import ActiveAgent, BottleBackend, BottleImages, BottleSpec
+from .. import ActiveAgent, BottleBackend, BottleSpec
 from . import cleanup as _cleanup
 from . import enumerate as _enumerate
 from . import launch as _launch
@@ -67,17 +67,11 @@ class MacosContainerBottleBackend(
            stage_dir=stage_dir,
        )
    def prelaunch_checks(self, plan: MacosContainerBottlePlan) -> None:
        _launch.stale_checks(plan)
    def _build_or_load_images(self, plan: MacosContainerBottlePlan) -> BottleImages:
        return _launch.build_or_load_images(plan)
    @contextmanager
-    def _launch_impl(
+    def launch(
-        self, plan: MacosContainerBottlePlan, images: BottleImages
+        self, plan: MacosContainerBottlePlan
    ) -> Generator[MacosContainerBottle, None, None]:
-        with _launch.launch(plan, images, provision=self.provision) as bottle:
+        with _launch.launch(plan, provision=self.provision) as bottle:
            yield bottle
    def prepare_cleanup(self) -> MacosContainerBottleCleanupPlan:
@@ -32,9 +32,7 @@ from ...git_gate import (
    provision_git_gate_dynamic_keys,
    revoke_git_gate_provisioned_keys,
 )
 from ...image_cache import check_stale
 from ...log import die, info, warn
 from .. import BottleImages
 from ...supervise import DB_PATH_IN_CONTAINER, SUPERVISE_PORT
 from ...util import expand_tilde
 from ..docker.egress import EGRESS_CA_IN_CONTAINER, EGRESS_PORT
@@ -73,51 +71,17 @@ def sidecar_container_name(slug: str) -> str:
    return f"bot-bottle-sidecars-{slug}"
 def build_or_load_images(plan: MacosContainerBottlePlan) -> BottleImages:
    """Resolve agent and sidecar image refs. Builds the sidecar when needed,
    but never builds the agent when policy is 'cached'."""
    committed = read_committed_image(plan.slug)
    if committed and container_mod.image_exists(committed):
        info(f"using committed image {committed!r}")
        if plan.spec.image_policy != "cached":
            container_mod.build_image(SIDECAR_BUNDLE_IMAGE, _REPO_DIR, dockerfile=SIDECAR_BUNDLE_DOCKERFILE)
        return BottleImages(agent=committed, sidecar=SIDECAR_BUNDLE_IMAGE)
    if plan.spec.image_policy == "cached":
        if not container_mod.image_exists(plan.image):
            die(
                f"cached agent image {plan.image!r} not found; "
                "run without --cached-images to build it"
            )
        if not container_mod.image_exists(SIDECAR_BUNDLE_IMAGE):
            die(
                f"cached sidecar image {SIDECAR_BUNDLE_IMAGE!r} not found; "
                "run without --cached-images to build it"
            )
        info(f"using cached agent image {plan.image!r}")
        info(f"using cached sidecar image {SIDECAR_BUNDLE_IMAGE!r}")
        return BottleImages(agent=plan.image, sidecar=SIDECAR_BUNDLE_IMAGE)
    container_mod.build_image(SIDECAR_BUNDLE_IMAGE, _REPO_DIR, dockerfile=SIDECAR_BUNDLE_DOCKERFILE)
    container_mod.build_image(plan.image, _REPO_DIR, dockerfile=plan.dockerfile_path)
    return BottleImages(agent=plan.image, sidecar=SIDECAR_BUNDLE_IMAGE)
@contextmanager
 def launch(
    plan: MacosContainerBottlePlan,
    images: BottleImages,
    *,
    provision: Callable[[MacosContainerBottlePlan, "MacosContainerBottle"], str | None],
 ) -> Generator[MacosContainerBottle, None, None]:
-    """Run, provision, and yield an Apple Container bottle."""
+    """Build, run, provision, and yield an Apple Container bottle."""
    stack = ExitStack()
    bottle_for_revoke = plan.manifest.bottle
    git_gate_dir_for_revoke = git_gate_state_dir(plan.slug)
    plan = dataclasses.replace(
        plan,
        agent_provision=dataclasses.replace(plan.agent_provision, image=str(images.agent)),
    )
    def teardown() -> None:
        teardown_exc: BaseException | None = None
        try:
@@ -131,6 +95,7 @@ def launch(
    try:
        plan = _mint_certs(plan)
        plan = _build_images(plan)
        internal_network = internal_network_name(plan.slug)
        egress_network = egress_network_name(plan.slug)
@@ -183,23 +148,28 @@ def _mint_certs(plan: MacosContainerBottlePlan) -> MacosContainerBottlePlan:
    return dataclasses.replace(plan, egress_plan=egress_plan)
-
+def _build_images(plan: MacosContainerBottlePlan) -> MacosContainerBottlePlan:
-def stale_checks(plan: MacosContainerBottlePlan) -> None:
+    container_mod.build_image(
-    """Raise StaleImageError if a cached image is older than the configured
+        SIDECAR_BUNDLE_IMAGE,
-    threshold. Only runs when image_policy is 'cached'. Called by the backend
+        _REPO_DIR,
-    class's _image_stale_checks before _launch_impl starts any resources."""
+        dockerfile=SIDECAR_BUNDLE_DOCKERFILE,
-    if plan.spec.image_policy != "cached":
+    )
        return
    committed = read_committed_image(plan.slug)
    if committed and container_mod.image_exists(committed):
-        check_stale(f"agent image {committed!r}", container_mod.image_created_at(committed))
+        info(f"using committed image {committed!r}")
-        return
+        return dataclasses.replace(
-    for label, ref in [
+            plan,
-        ("agent image", plan.image),
+            agent_provision=dataclasses.replace(
-        ("sidecar image", SIDECAR_BUNDLE_IMAGE),
+                plan.agent_provision,
-    ]:
+                image=committed,
-        if container_mod.image_exists(ref):
+            ),
-            check_stale(f"{label} {ref!r}", container_mod.image_created_at(ref))
+        )
    container_mod.build_image(
        plan.image,
        _REPO_DIR,
        dockerfile=plan.dockerfile_path,
    )
    return plan
 def _create_networks(
@@ -10,7 +10,6 @@ import shutil
 import subprocess
 import tempfile
 import time
 from datetime import datetime, timezone
 from typing import Iterable
 from ...log import die, info
@@ -459,39 +458,6 @@ def image_id(ref: str) -> str:
    raise AssertionError("unreachable")
 def image_created_at(ref: str) -> datetime:
    """Return the image creation timestamp as an aware UTC datetime.
    Parses the `created` field from `container image inspect` JSON output."""
    result = subprocess.run(
        [_CONTAINER, "image", "inspect", ref],
        capture_output=True,
        text=True,
        check=False,
    )
    if result.returncode != 0:
        die(
            f"container image inspect for {ref!r} failed: "
            f"{(result.stderr or '').strip() or '<no stderr>'}"
        )
    try:
        data = json.loads(result.stdout or "{}")
    except json.JSONDecodeError as exc:
        die(f"container image inspect for {ref!r} returned malformed JSON: {exc}")
    if isinstance(data, list) and data:
        data = data[0]
    if isinstance(data, dict):
        value = data.get("created") or data.get("Created")
        if isinstance(value, str) and value:
            try:
                ts = value.rstrip("Z")
                return datetime.fromisoformat(ts).replace(tzinfo=timezone.utc)
            except ValueError:
                pass
    die(f"container image inspect for {ref!r} did not include a creation timestamp")
    raise AssertionError("unreachable")
 def save(ref: str, output: str) -> None:
    subprocess.run([_CONTAINER, "image", "save", ref, "-o", output], check=True)
@@ -19,7 +19,7 @@ from ...env import ResolvedEnv
 from ...git_gate import GitGatePlan
 from ...supervise import SupervisePlan
 from ...manifest import Manifest
-from .. import ActiveAgent, BottleBackend, BottleImages, BottleSpec
+from .. import ActiveAgent, BottleBackend, BottleSpec
 from . import cleanup as _cleanup
 from . import enumerate as _enumerate
 from . import launch as _launch
@@ -77,17 +77,11 @@ class SmolmachinesBottleBackend(
            stage_dir=stage_dir,
        )
    def prelaunch_checks(self, plan: SmolmachinesBottlePlan) -> None:
        _launch.stale_checks(plan)
    def _build_or_load_images(self, plan: SmolmachinesBottlePlan) -> BottleImages:
        return _launch.build_or_load_images(plan)
    @contextmanager
-    def _launch_impl(
+    def launch(
-        self, plan: SmolmachinesBottlePlan, images: BottleImages
+        self, plan: SmolmachinesBottlePlan
    ) -> Generator[SmolmachinesBottle, None, None]:
-        with _launch.launch(plan, images, provision=self.provision) as bottle:
+        with _launch.launch(plan, provision=self.provision) as bottle:
            yield bottle
    def supervise_mcp_url(self, plan: SmolmachinesBottlePlan) -> str:
@@ -1,8 +1,10 @@
 """SmolmachinesBottlePlan — concrete BottlePlan for the smolmachines
 backend (PRD 0023).
-Slug + legacy bundle network coordinates + smolvm machine name +
+Slug + bundle docker subnet / gateway / pinned IP + smolvm
-agent `.smolmachine` artifact + per-bottle guest env."""
+machine name + agent `.smolmachine` artifact + per-bottle guest
 env. Provisioning fields (CA cert path, prompt path, etc.) land
 in chunk 4."""
 from __future__ import annotations
@@ -21,10 +23,9 @@ class SmolmachinesBottlePlan(BottlePlan):
    `supervise_plan`, and `agent_provision` from BottlePlan."""
    slug: str
-    # Legacy per-bottle bundle network coordinates. These remain on
+    # Per-bottle docker subnet for the sidecar bundle container.
-    # the plan while BundleLaunchSpec still carries the original shape,
+    # The bundle runs at `bundle_ip` (always `.2`); the gateway is
-    # but the smolmachines launch path exposes the sidecar VM through
+    # at `.1`. smolvm's TSI allowlist is set to `bundle_ip/32`.
    # host-loopback forwarders instead of a Docker bridge IP.
    bundle_subnet: str
    bundle_gateway: str
    bundle_ip: str
@@ -35,10 +36,22 @@ class SmolmachinesBottlePlan(BottlePlan):
    # `--smolfile` is mutually exclusive with `--from`, and
    # `--from` is the path that avoids the registry-pull race).
    guest_env: dict[str, str]
-    # Agent-side endpoints. Empty at prepare time; launch populates
+    # Inner Plans for the sidecar bundle daemons. The same shape the
-    # these after sidecar VM bringup via `dataclasses.replace`.
+    # docker backend uses — same `.prepare()` calls produced
-    # Format: a `host:port` for git-gate (insteadOf URL prefix) +
+    # them — but our launch step doesn't populate the
-    # full URLs for proxy / supervise.
+    # docker-specific network fields (internal_network,
    # egress_network) because the smolmachines bundle isn't on
    # docker's `--internal` + egress bridge topology; it's on a
    # per-bottle bridge with a pinned IP. The unused fields stay
    # at their dataclass defaults.
    # Agent-side endpoints. On Docker Desktop the docker bridge
    # IPs aren't reachable from the smolvm guest (TSI uses macOS
    # networking; docker container IPs live in the daemon's VM),
    # so the agent dials the bundle via host loopback +
    # docker-published random ports. Empty at prepare time;
    # launch populates these after bundle bringup via
    # `dataclasses.replace`. Format: a `host:port` for git-gate
    # (insteadOf URL prefix) + full URLs for proxy / supervise.
    agent_proxy_url: str = ""
    agent_git_gate_host: str = ""
    agent_supervise_url: str = ""
@@ -1,51 +1,20 @@
 """Egress apply for the smolmachines backend.
-The smolmachines sidecar bundle runs as a sidecar smolVM. Route-file
+The smolmachines sidecar bundle runs as a host-side Docker container,
-inspection and reload signalling therefore go through ``smolvm machine
+so egress signalling is identical to the docker backend.
 exec`` instead of Docker.
 """
 from __future__ import annotations
-from ...egress import EGRESS_ROUTES_IN_CONTAINER
+from ..docker.egress_apply import (  # noqa: F401
-from ...log import warn
+    DockerEgressApplicator,
-from ..egress_apply import EgressApplicator, EgressApplyError
+    EgressApplyError,
-from . import sidecar_bundle as _bundle
+    applicator,
-from . import smolvm as _smolvm
+    fetch_current_routes,
-
+)
 def fetch_current_routes(slug: str) -> str:
    machine = _bundle.bundle_machine_name(slug)
    result = _smolvm.machine_exec(machine, ["cat", EGRESS_ROUTES_IN_CONTAINER])
    if result.returncode != 0:
        raise EgressApplyError(
            f"could not read routes.yaml from {machine}: "
            f"{(result.stderr or '').strip() or 'sidecar VM not running?'}"
        )
    return result.stdout
 class SmolmachinesEgressApplicator(EgressApplicator):
    def _signal_bundle_reload(self, slug: str) -> None:
        machine = _bundle.bundle_machine_name(slug)
        result = _smolvm.machine_exec(machine, ["sh", "-c", "kill -HUP 1"])
        if result.returncode != 0:
            last_error = (result.stderr or "").strip() or (result.stdout or "").strip()
            warn(
                f"egress: routes updated on disk for {slug}, but bundle reload failed: "
                f"{last_error or 'smolvm exec failed'}"
            )
            raise EgressApplyError(
                f"could not reload egress bundle {machine}: "
                f"{last_error or 'smolvm exec failed'}"
            )
 applicator = SmolmachinesEgressApplicator()
 __all__ = [
-    "SmolmachinesEgressApplicator",
+    "DockerEgressApplicator",
    "EgressApplyError",
    "applicator",
    "fetch_current_routes",
@@ -31,7 +31,6 @@ from . import sidecar_bundle as _bundle
 # matching the bundle container name pattern. We use the prefix
 # both as a filter and to strip back to the slug.
 _VM_NAME_PREFIX = "bot-bottle-"
 _SIDECAR_VM_PREFIX = _bundle.bundle_machine_name("")
 def enumerate_active() -> list[ActiveAgent]:
@@ -55,11 +54,7 @@ def enumerate_active() -> list[ActiveAgent]:
    for m in machines:
        name = m.get("name") or ""
        state = m.get("state") or ""
-        if (
+        if state != "running" or not name.startswith(_VM_NAME_PREFIX):
            state != "running"
            or not name.startswith(_VM_NAME_PREFIX)
            or name.startswith(_SIDECAR_VM_PREFIX)
        ):
            continue
        slug = name[len(_VM_NAME_PREFIX):]
        metadata = read_metadata(slug)
@@ -1,9 +1,12 @@
-"""End-to-end launch flow for the smolmachines backend.
+"""End-to-end launch flow for the smolmachines backend
 (PRD 0023 chunks 2d + 4b).
-Builds the sidecar bundle smolmachine, starts it as a sidecar VM
+Brings up the per-bottle docker bridge + sidecar bundle (with
-with real daemons + their config files, creates + starts the agent
+real daemons + their config files), creates + starts the smolvm
-smolVM, yields a `SmolmachinesBottle` handle, and tears everything
+guest pointed at the bundle's pinned IP via TSI's
-down on context exit.
+`--allow-cidr <bundle-ip>/32` allowlist, yields a
 `SmolmachinesBottle` handle, tears everything down on context
 exit.
 The bundle's daemons consume the inner Plans the docker backend
 already produces: egress reads routes + CAs from the EgressPlan.
@@ -14,6 +17,7 @@ from __future__ import annotations
 import dataclasses
 import os
 import platform
 from contextlib import ExitStack, contextmanager
 from pathlib import Path
 from typing import Callable, Generator
@@ -42,16 +46,13 @@ from ...git_gate import (
    provision_git_gate_dynamic_keys,
    revoke_git_gate_provisioned_keys,
 )
-from ...image_cache import check_stale_path
+from ...log import info, warn
 from ...log import die, info, warn
 from ...bottle_state import (
    egress_state_dir,
    git_gate_state_dir,
    read_committed_image,
 )
 from .. import BottleImages
 from . import loopback_alias as _loopback
 from . import port_forward as _forward
 from . import sidecar_bundle as _bundle
 from . import smolvm as _smolvm
 from .bottle import SmolmachinesBottle
@@ -71,48 +72,33 @@ _SMOLMACHINE_CACHE_DIR = Path.home() / ".cache" / "bot-bottle" / "smolmachines"
 # Container-internal listening ports for each bundle daemon. The
-# sidecar VM publishes each one on a random host loopback port, and
+# bundle publishes each one on a random host loopback port (see
-# the launch flow wraps those raw ports with per-bottle forwarders.
+# `_bundle.start_bundle`), and `_bundle.bundle_host_port` looks
 # them up post-start.
 _GIT_HTTP_PORT = 9420
 _SUPERVISE_PORT = SUPERVISE_PORT
 def build_or_load_images(plan: SmolmachinesBottlePlan) -> BottleImages:
    """Return pre-built or freshly built smolmachine artifact paths."""
    return BottleImages(
        agent=_agent_from_path(plan),
        sidecar=_sidecar_from_path(plan),
    )
 def _sidecar_from_path(plan: SmolmachinesBottlePlan) -> Path:
    """Return the sidecar bundle artifact path, building it if needed."""
    if _image_policy(plan) == "cached":
        return _cached_smolmachine(_bundle.SIDECAR_BUNDLE_IMAGE, label="sidecar")
    return _ensure_smolmachine(
        _bundle.SIDECAR_BUNDLE_IMAGE,
        dockerfile=_bundle.SIDECAR_BUNDLE_DOCKERFILE,
    )
@contextmanager
 def launch(
    plan: SmolmachinesBottlePlan,
    images: BottleImages,
    *,
    provision: Callable[[SmolmachinesBottlePlan, "SmolmachinesBottle"], str | None],
 ) -> Generator[SmolmachinesBottle, None, None]:
-    """Run the bottle from pre-built images and yield a handle; tear everything
+    """Build + run the bottle and yield a handle; tear everything
    down on exit. Errors during bringup unwind any partial state
    via the ExitStack."""
    stack = ExitStack()
    try:
        loopback_ip, network = _allocate_resources(plan, stack)
        plan = _mint_certs(plan)
-        proxy_host = loopback_ip
+        proxy_host = _proxy_host(plan, loopback_ip)
-        plan = _start_bundle(plan, network, proxy_host, Path(images.sidecar), stack)
+        plan = _start_bundle(plan, network, proxy_host, stack)
        plan = _discover_urls(plan, proxy_host)
-        _launch_vm(plan, Path(images.agent), proxy_host, stack)
+        agent_from_path = _agent_from_path(plan)
        _launch_vm(plan, agent_from_path, proxy_host, stack)
        _init_vm(plan)
        bottle = SmolmachinesBottle(
@@ -158,17 +144,19 @@ def _allocate_resources(
    plan: SmolmachinesBottlePlan,
    stack: ExitStack,
 ) -> tuple[str, str]:
-    """Reserve a per-bottle host address.
+    """Reserve a loopback alias and create the per-bottle docker bridge.
-    The per-bottle address scopes TSI's allowlist to this bottle's
+    The per-bottle alias scopes TSI's allowlist to this bottle's
-    forwarder-published ports so the agent can't reach other bottles'
+    published ports so the agent can't reach other bottles' or host
-    or host services. The returned network name remains in the bundle
+    services' ports on loopback. On macOS `ensure_pool` first
-    spec for compatibility with older helper tests; no Docker sidecar
+    sudo-aliases the pool on `lo0`; on Linux that's a no-op since
-    container is launched."""
+    all of 127.0.0.0/8 is already loopback, but the per-bottle
-    del stack
+    allocation runs on both."""
    _loopback.ensure_pool()
    loopback_ip = _loopback.allocate(plan.slug)
    network = _bundle.bundle_network_name(plan.slug)
    _bundle.create_bundle_network(network, plan.bundle_subnet, plan.bundle_gateway)
    stack.callback(_bundle.remove_bundle_network, network)
    return loopback_ip, network
@@ -189,39 +177,17 @@ def _start_bundle(
    plan: SmolmachinesBottlePlan,
    network: str,
    proxy_host: str,
    sidecar_artifact: Path,
    stack: ExitStack,
 ) -> SmolmachinesBottlePlan:
-    """Build the BundleLaunchSpec, start the sidecar VM from the pre-resolved
+    """Build the BundleLaunchSpec, resolve token env, start the
-    artifact, wrap its raw smolVM-published loopback ports with per-bottle
+    sidecar bundle container, and register teardown."""
    forwarders, stamp agent URLs from those forwarder ports, and register teardown."""
    plan = _provision_git_gate_keys(plan)
    bundle_spec = _bundle_launch_spec(plan, network, proxy_host)
    token_env = _resolve_token_env(plan, dict(os.environ))
-    launch = _bundle.start_bundle_vm(
+    _bundle.ensure_bundle_image(bundle_spec.image)
-        bundle_spec,
+    _bundle.start_bundle(bundle_spec, env={**os.environ, **token_env})
-        from_path=sidecar_artifact,
+    stack.callback(_bundle.stop_bundle, plan.slug)
-        host_env={**os.environ, **token_env},
+    return plan
    )
    stack.callback(_bundle.stop_bundle_vm, plan.slug)
    forward_specs = tuple(
        _forward.ForwardSpec(
            label=_label_for_port(container_port),
            listen_host=proxy_host,
            listen_port=0,
            target_host="127.0.0.1",
            target_port=host_port,
        )
        for container_port, host_port in launch.raw_ports.items()
    )
    handle = _forward.start_forwarder(forward_specs)
    stack.callback(_forward.stop_forwarder, handle)
    published_ports = {
        _port_for_label(spec.label): spec.listen_port
        for spec in handle.forwards
    }
    return _discover_urls(plan, proxy_host, published_ports)
 def _provision_git_gate_keys(
@@ -240,27 +206,35 @@ def _provision_git_gate_keys(
 def _discover_urls(
    plan: SmolmachinesBottlePlan,
    proxy_host: str,
    published_ports: dict[int, int],
 ) -> SmolmachinesBottlePlan:
-    """Stamp URLs + guest_env from per-bottle forwarder ports.
+    """Discover host-side ports for published container ports and
    return the plan with URLs + guest_env stamped in.
-    `proxy_host` is the host IP that both TSI's allowlist and the
+    `proxy_host` is the host IP that both TSI's allowlist and
-    forwarder listeners are keyed to. The raw smolVM-published ports
+    docker's port-forward bindings are keyed to. On macOS it is the
-    are intentionally not advertised to the agent.
+    per-bottle loopback alias; on Linux it is the per-bottle bridge
    gateway (see `_proxy_host`). The agent dials the published port
    on this IP for all bundle-hosted services.
    NO_PROXY includes `proxy_host` so supervise + git-gate URLs
    bypass HTTPS_PROXY."""
-    agent_facing_host_port = published_ports[_EGRESS_PORT]
+    agent_facing_host_port = _bundle.bundle_host_port(
        plan.slug, _EGRESS_PORT, host_ip=proxy_host,
    )
    agent_proxy_url = f"http://{proxy_host}:{agent_facing_host_port}"
    agent_git_gate_host = ""
    if plan.git_gate_plan.upstreams:
-        git_gate_host_port = published_ports[_GIT_HTTP_PORT]
+        git_gate_host_port = _bundle.bundle_host_port(
            plan.slug, _GIT_HTTP_PORT, host_ip=proxy_host,
        )
        agent_git_gate_host = f"{proxy_host}:{git_gate_host_port}"
    agent_supervise_url = ""
    if plan.supervise_plan is not None:
-        supervise_host_port = published_ports[_SUPERVISE_PORT]
+        supervise_host_port = _bundle.bundle_host_port(
            plan.slug, _SUPERVISE_PORT, host_ip=proxy_host,
        )
        agent_supervise_url = f"http://{proxy_host}:{supervise_host_port}/"
    existing_no_proxy = plan.guest_env.get("NO_PROXY", "localhost,127.0.0.1")
@@ -299,13 +273,14 @@ def _launch_vm(
 ) -> None:
    """Create, patch, and start the smolvm VM; register teardown.
-    --allow-cidr is `proxy_host/32` — the per-bottle loopback alias.
+    --allow-cidr is `proxy_host/32` — the per-bottle loopback alias
-    This ensures the guest can only reach sidecar forwarders published
+    on macOS or the bridge gateway on Linux (see `_proxy_host`). This
-    on that IP, not host localhost or another bottle's alias.
+    ensures the guest can only reach bundle ports published on that IP,
-    force_allowlist confirms the allowlist persisted (patching smolvm
+    not the container IP directly. force_allowlist confirms the
-    0.8.0's silent-drop of --allow-cidr when combined with --from) and
+    allowlist persisted (patching smolvm 0.8.0's silent-drop of
-    fails closed if it can't. Smolfile isn't usable here — smolvm 0.8.0
+    --allow-cidr when combined with --from) and fails closed if it
-    makes --from and --smolfile mutually exclusive."""
+    can't. Smolfile isn't usable here — smolvm 0.8.0 makes --from
    and --smolfile mutually exclusive."""
    tsi_cidr = f"{proxy_host}/32"
    _smolvm.machine_create(
        plan.machine_name,
@@ -352,26 +327,25 @@ def _init_vm(plan: SmolmachinesBottlePlan) -> None:
    _smolvm.wait_exec_ready(plan.machine_name)
-def _label_for_port(port: int) -> str:
+def _proxy_host(plan: SmolmachinesBottlePlan, loopback_ip: str) -> str:
-    if port == _EGRESS_PORT:
+    """Return the host IP for TSI's allowlist and docker port-forward bindings.
        return "egress"
    if port == _GIT_HTTP_PORT:
        return "git-http"
    if port == _SUPERVISE_PORT:
        return "supervise"
    return f"port-{port}"
    On macOS, the per-bottle loopback alias (e.g. ``127.0.0.16``) works
    because macOS's network stack lets TSI intercept 127.x.x.x connects
    from the guest before they reach the host's own loopback.
-def _port_for_label(label: str) -> int:
+    On Linux, the guest kernel's LOCAL routing table routes all
-    if label == "egress":
+    ``127.0.0.0/8`` to the guest's own loopback — those packets never
-        return _EGRESS_PORT
+    reach eth0 and TSI never sees them. Using the per-bottle bridge
-    if label == "git-http":
+    gateway (e.g. ``192.168.N.1``) instead sidesteps the problem: it
-        return _GIT_HTTP_PORT
+    is not a loopback address, so the guest routes it via eth0 and TSI
-    if label == "supervise":
+    intercepts it normally. The TSI allowlist is ``gateway/32``, which
-        return _SUPERVISE_PORT
+    is distinct from the container IP (``192.168.N.2``), so the agent
-    if label.startswith("port-"):
+    still can't reach the egress daemon directly — TSI blocks any
-        return int(label.removeprefix("port-"))
+    connection to the container IP that isn't via the published port."""
-    raise ValueError(f"unknown sidecar forward label: {label}")
+    if platform.system() == "Linux":
        return plan.bundle_gateway
    return loopback_ip
 def _bundle_launch_spec(
@@ -481,9 +455,6 @@ def _agent_from_path(plan: SmolmachinesBottlePlan) -> Path:
            info(f"using committed smolmachine {str(committed_path)!r}")
            return committed_path
    if _image_policy(plan) == "cached":
        return _cached_smolmachine(plan.agent_image, label="agent")
    # Build the agent image and pack it into a `.smolmachine`
    # artifact (or hit the per-Dockerfile-digest cache). Runs here,
    # not in prepare, so the docker-build output doesn't garble the
@@ -494,60 +465,6 @@ def _agent_from_path(plan: SmolmachinesBottlePlan) -> Path:
    )
 def stale_checks(plan: SmolmachinesBottlePlan) -> None:
    """Raise StaleImageError if a cached smolmachine artifact is older than the
    configured threshold. Only runs when image_policy is 'cached'. Checks the
    committed agent artifact first, then the cache-keyed agent and sidecar
    artifacts. Called by the backend class's _image_stale_checks before any
    resources are allocated."""
    if _image_policy(plan) != "cached":
        return
    committed = read_committed_image(plan.slug)
    if committed:
        committed_path = Path(committed)
        if committed_path.is_file():
            check_stale_path("agent smolmachine artifact", committed_path)
    elif docker_mod.image_exists(plan.agent_image):
        digest = docker_mod.image_id(plan.agent_image).split(":", 1)[-1][:16]
        artifact = _SMOLMACHINE_CACHE_DIR / f"{digest}.smolmachine.smolmachine"
        if artifact.is_file():
            check_stale_path("agent smolmachine artifact", artifact)
    sidecar_image = _bundle.SIDECAR_BUNDLE_IMAGE
    if docker_mod.image_exists(sidecar_image):
        digest = docker_mod.image_id(sidecar_image).split(":", 1)[-1][:16]
        sidecar_artifact = _SMOLMACHINE_CACHE_DIR / f"{digest}.smolmachine.smolmachine"
        if sidecar_artifact.is_file():
            check_stale_path("sidecar smolmachine artifact", sidecar_artifact)
 def _image_policy(plan: object) -> str:
    spec = getattr(plan, "spec", None)
    return str(getattr(spec, "image_policy", "fresh"))
 def _cached_smolmachine(image_ref: str, *, label: str) -> Path:
    """Return the cached smolmachine artifact for the current local image.
    This is intentionally buildless: it inspects the existing local Docker
    image ID and looks for the artifact keyed by that ID. If either side is
    missing, the caller must use the fresh path to build/pack it.
    """
    if not docker_mod.image_exists(image_ref):
        die(
            f"cached {label} image {image_ref!r} not found; "
            "run without --cached-images to build it"
        )
    digest = docker_mod.image_id(image_ref).split(":", 1)[-1][:16]
    sidecar = _SMOLMACHINE_CACHE_DIR / f"{digest}.smolmachine.smolmachine"
    if not sidecar.is_file():
        die(
            f"cached {label} smolmachine artifact for {image_ref!r} not found; "
            "run without --cached-images to build it"
        )
    info(f"using cached {label} smolmachine {str(sidecar)!r}")
    return sidecar
 def _ensure_smolmachine(image_ref: str, *, dockerfile: str = "") -> Path:
    """Build the agent docker image and convert it into a
    `.smolmachine` artifact, caching the result under
@@ -1,245 +0,0 @@
 """Per-bottle TCP forwarder for smolmachines sidecar VMs.
 smolVM currently publishes guest ports on host loopback as
 ``HOST:GUEST`` port pairs, without an address-scoped bind. The agent
 VM's TSI allowlist is IP-only, so bot-bottle exposes a second, stricter
 surface: listeners bound only to the bottle's allocated host address,
 forwarding to the raw smolVM-published loopback ports.
 """
 from __future__ import annotations
 import argparse
 import json
 import os
 import selectors
 import signal
 import socket
 import subprocess
 import sys
 import threading
 from dataclasses import asdict, dataclass
 from typing import Any, Iterable, Sequence
 from ...log import die, warn
 _BUFFER_SIZE = 64 * 1024
 _LOOPBACK_TARGETS = {"127.0.0.1", "::1"}
 _FORBIDDEN_LISTEN_HOSTS = {"", "0.0.0.0", "::", "127.0.0.1", "::1"}
@dataclass(frozen=True)
 class ForwardSpec:
    label: str
    listen_host: str
    listen_port: int
    target_host: str
    target_port: int
@dataclass(frozen=True)
 class ForwarderHandle:
    process: Any
    forwards: tuple[ForwardSpec, ...]
 def start_forwarder(specs: Sequence[ForwardSpec]) -> ForwarderHandle:
    """Start one helper process for a bottle and wait until all
    listeners are bound. ``listen_port`` may be 0; the returned specs
    contain the kernel-assigned ports printed by the helper."""
    if not specs:
        return ForwarderHandle(process=_CompletedProcess(), forwards=())
    _validate_specs(specs)
    argv = [
        sys.executable,
        "-c",
        "from bot_bottle.backend.smolmachines.port_forward import main; "
        "raise SystemExit(main())",
        "--spec-json",
        json.dumps([asdict(s) for s in specs], separators=(",", ":")),
    ]
    proc = subprocess.Popen(
        argv,
        stdin=subprocess.DEVNULL,
        stdout=subprocess.PIPE,
        stderr=None,
        text=True,
        env=os.environ,
    )
    assert proc.stdout is not None
    line = proc.stdout.readline()
    proc.stdout.close()
    if not line:
        proc.terminate()
        proc.wait(timeout=5)
        die("smolmachines forwarder failed before reporting readiness")
    try:
        payload = json.loads(line)
        bound = tuple(ForwardSpec(**item) for item in payload["forwards"])
    except (KeyError, TypeError, ValueError, json.JSONDecodeError) as exc:
        proc.terminate()
        proc.wait(timeout=5)
        die(f"smolmachines forwarder returned invalid readiness payload: {exc}")
    return ForwarderHandle(process=proc, forwards=bound)
 def stop_forwarder(handle: ForwarderHandle) -> None:
    proc = handle.process
    if proc.poll() is not None:
        return
    proc.terminate()
    try:
        proc.wait(timeout=5)
    except subprocess.TimeoutExpired:
        proc.kill()
        proc.wait(timeout=5)
 def _validate_specs(specs: Iterable[ForwardSpec]) -> None:
    for spec in specs:
        if spec.listen_host in _FORBIDDEN_LISTEN_HOSTS:
            die(f"refusing unsafe smolmachines forwarder bind: {spec.listen_host!r}")
        if spec.target_host not in _LOOPBACK_TARGETS:
            die(f"refusing non-loopback smolmachines forwarder target: {spec.target_host!r}")
        if not 0 <= spec.listen_port <= 65535:
            die(f"invalid smolmachines forwarder listen port: {spec.listen_port}")
        if not 1 <= spec.target_port <= 65535:
            die(f"invalid smolmachines forwarder target port: {spec.target_port}")
 class _CompletedProcess:
    """Popen-like no-op used when a bottle has no forwards."""
    def poll(self) -> int:
        return 0
    def terminate(self) -> None:
        return None
    def kill(self) -> None:
        return None
    def wait(self, timeout: float | None = None) -> int:
        del timeout
        return 0
 class _Forwarder:
    def __init__(self, specs: Sequence[ForwardSpec]):
        _validate_specs(specs)
        self.specs = tuple(specs)
        self.selector = selectors.DefaultSelector()
        self.stop_event = threading.Event()
        self.listeners: list[tuple[socket.socket, ForwardSpec]] = []
        self.bound: list[ForwardSpec] = []
    def start(self) -> None:
        for spec in self.specs:
            listener = socket.create_server(
                (spec.listen_host, spec.listen_port),
                reuse_port=False,
                backlog=64,
            )
            listener.setblocking(False)
            host, port = listener.getsockname()[:2]
            bound = ForwardSpec(
                label=spec.label,
                listen_host=str(host),
                listen_port=int(port),
                target_host=spec.target_host,
                target_port=spec.target_port,
            )
            self.listeners.append((listener, bound))
            self.bound.append(bound)
            self.selector.register(listener, selectors.EVENT_READ, bound)
    def serve(self) -> None:
        while not self.stop_event.is_set():
            try:
                events = self.selector.select(timeout=0.25)
            except OSError:
                return
            for key, _ in events:
                listener = key.fileobj
                if not isinstance(listener, socket.socket):
                    continue
                spec = key.data
                try:
                    client, _ = listener.accept()
                except OSError:
                    continue
                threading.Thread(
                    target=self._handle_client,
                    args=(client, spec),
                    daemon=True,
                ).start()
    def stop(self) -> None:
        self.stop_event.set()
        for listener, _ in self.listeners:
            try:
                self.selector.unregister(listener)
            except Exception:  # noqa: BLE001 - best effort shutdown
                pass
            listener.close()
        self.selector.close()
    def _handle_client(self, client: socket.socket, spec: ForwardSpec) -> None:
        with client:
            try:
                target = socket.create_connection((spec.target_host, spec.target_port))
            except OSError as exc:
                warn(f"smolmachines forwarder {spec.label}: target connect failed: {exc}")
                return
            with target:
                left = threading.Thread(target=_pipe, args=(client, target), daemon=True)
                right = threading.Thread(target=_pipe, args=(target, client), daemon=True)
                left.start()
                right.start()
                left.join()
                right.join()
 def _pipe(src: socket.socket, dst: socket.socket) -> None:
    while True:
        try:
            data = src.recv(_BUFFER_SIZE)
        except OSError:
            break
        if not data:
            break
        try:
            dst.sendall(data)
        except OSError:
            break
    try:
        dst.shutdown(socket.SHUT_WR)
    except OSError:
        pass
 def main(argv: Sequence[str] | None = None) -> int:
    parser = argparse.ArgumentParser()
    parser.add_argument("--spec-json", required=True)
    ns = parser.parse_args(argv)
    specs = tuple(ForwardSpec(**item) for item in json.loads(ns.spec_json))
    forwarder = _Forwarder(specs)
    def request_stop(signum: int, _frame: object) -> None:
        del signum
        forwarder.stop()
    signal.signal(signal.SIGTERM, request_stop)
    signal.signal(signal.SIGINT, request_stop)
    forwarder.start()
    print(json.dumps({"forwards": [asdict(s) for s in forwarder.bound]}), flush=True)
    try:
        forwarder.serve()
    finally:
        forwarder.stop()
    return 0
 if __name__ == "__main__":
    raise SystemExit(main())
@@ -56,11 +56,13 @@ def resolve_plan(
    git_gate_plan: GitGatePlan,
    stage_dir: Path,
 ) -> SmolmachinesBottlePlan:
-    """Materialize the smolmachines plan. The agent `.smolmachine`
+    """Materialize the smolmachines plan. The bundle's docker
-    artifact is built (or cache-hit) here so launch's
+    subnet + pinned IP are derived from the slug; the agent's
-    `machine create --from` boots without a registry pull. Per-bottle
+    `.smolmachine` artifact is built (or cache-hit) here so
-    guest env lands on the plan for launch to pass straight through
+    launch's `machine create --from` boots without a registry
-    to `machine create` flags."""
+    pull. Per-bottle guest env + the TSI allow_cidrs land on the
    plan for launch to pass straight through to
    `machine create` flags."""
    # ==== smolmachines specific setup ====
    subnet, gateway, bundle_ip = smolmachines_bundle_subnet(slug)
@@ -1,24 +1,39 @@
-"""Per-bottle sidecar bundle bringup for the smolmachines backend.
+"""Per-bottle sidecar bundle bringup for the smolmachines backend
 (PRD 0023).
-The sidecar bundle runs as its own smolVM. The agent VM reaches
+Two docker resources per bottle live here:
-bundle daemons through host-loopback ports published by that sidecar
+
-VM and wrapped by per-bottle address-bound forwarders."""
+  - **A dedicated bridge network**, subnet derived from the slug.
    The bundle container gets a pinned IP at `<subnet>.2` so the
    smolvm guest's TSI allowlist (`<bundle-ip>/32`) has a stable
    target. Without pinning, we'd have to inspect the container's
    assigned IP after start and feed it back into the Smolfile
    — a race we can sidestep with `--ip`.
  - **The bundle container itself**, running the PRD 0024 bundle
    image (`bot-bottle-sidecars:latest` by default). Same
    image, same daemons, same daemon-private env / bind-mounts
    as the docker backend.
 This module ships the lifecycle primitives only — create
 network, start bundle, stop bundle, remove network — wrapped
 around `subprocess.run(["docker", ...])`. Wiring them into the
 launch flow + populating the `BundleLaunchSpec` from the inner
 Plans (EgressPlan, …) lands in chunk 2d."""
 from __future__ import annotations
-import os
+import subprocess
 import socket
 from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Sequence
-from ...log import warn
+from ...log import die, warn
 from ..docker import util as docker_mod
 from ..docker.sidecar_bundle import (
    SIDECAR_BUNDLE_DOCKERFILE,
    SIDECAR_BUNDLE_IMAGE,
 )
 from . import smolvm as _smolvm
 _REPO_DIR = str(Path(__file__).resolve().parent.parent.parent.parent)
@@ -39,11 +54,6 @@ def bundle_container_name(slug: str) -> str:
    return f"bot-bottle-sidecars-{slug}"
 def bundle_machine_name(slug: str) -> str:
    """Sidecar smolVM machine name."""
    return bundle_container_name(slug)
@dataclass(frozen=True)
 class BundleLaunchSpec:
    """Everything `start_bundle` needs to bring up one bundle
@@ -60,8 +70,10 @@ class BundleLaunchSpec:
    # supervisor inside the bundle reads it to skip
    # bottle-irrelevant daemons (e.g. supervise=False bottles).
    daemons_csv: str = "egress"
-    # Plain "KEY=VALUE" strings + "KEY" bare names. Bare names inherit
+    # Plain "KEY=VALUE" strings + "KEY" bare names (the bare-name
-    # from the host env passed to the sidecar VM launch.
+    # form inherits the value from the docker-run subprocess env,
    # matching the docker backend's compose-up secret-forwarding
    # pattern).
    environment: Sequence[str] = field(default_factory=tuple)
    # (host_path, container_path, read_only) bind mounts.
    volumes: Sequence[tuple[str, str, bool]] = field(default_factory=tuple)
@@ -80,11 +92,6 @@ class BundleLaunchSpec:
    publish_host_ip: str = "127.0.0.1"
@dataclass(frozen=True)
 class BundleVmLaunch:
    raw_ports: dict[int, int]
 def ensure_bundle_image(image: str = SIDECAR_BUNDLE_IMAGE) -> None:
    """Build the sidecar bundle image before `docker run`.
@@ -100,65 +107,136 @@ def ensure_bundle_image(image: str = SIDECAR_BUNDLE_IMAGE) -> None:
    )
-def allocate_raw_host_ports(container_ports: Sequence[int]) -> dict[int, int]:
+def create_bundle_network(network_name: str, subnet: str, gateway: str) -> None:
-    """Reserve candidate host loopback ports for smolVM `-p HOST:GUEST`.
+    """`docker network create` with an explicit subnet + gateway
-
+    so the bundle's `--ip` lands on the address the Smolfile's
-    The sockets are closed before smolVM binds them, so this remains
+    TSI allowlist points at. Idempotent on the caller's side —
-    best-effort. smolVM failing to bind a selected port is fatal in
+    `start_bundle` catches the "network exists" error and treats
-    the caller's launch path."""
+    it as success (chunk-2d teardown is paired with each create).
-    out: dict[int, int] = {}
+    """
-    for container_port in container_ports:
+    result = subprocess.run(
-        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+        ["docker", "network", "create",
-            sock.bind(("127.0.0.1", 0))
+         "--subnet", subnet, "--gateway", gateway,
-            out[container_port] = int(sock.getsockname()[1])
+         network_name],
-    return out
+        capture_output=True, text=True, check=False,
 def start_bundle_vm(
    spec: BundleLaunchSpec,
    *,
    from_path: Path,
    host_env: dict[str, str] | None = None,
 ) -> BundleVmLaunch:
    """Create and start the sidecar bundle as a smolVM.
    smolVM's own published ports are raw host-loopback ports. The
    launch flow wraps them with per-bottle address-bound forwarders
    before exposing anything to the agent VM."""
    raw_ports = allocate_raw_host_ports(spec.ports_to_publish)
    effective_host_env = host_env if host_env is not None else os.environ
    env: dict[str, str] = {"BOT_BOTTLE_SIDECAR_DAEMONS": spec.daemons_csv}
    for entry in spec.environment:
        name, sep, value = entry.partition("=")
        if sep:
            env[name] = value
        elif entry in effective_host_env:
            env[entry] = effective_host_env[entry]
    name = bundle_machine_name(spec.slug)
    _smolvm.machine_create(
        name,
        from_path=from_path,
        net=True,
        env=env,
        volumes=spec.volumes,
        ports=tuple(
            (host_port, guest_port)
            for guest_port, host_port in raw_ports.items()
        ),
    )
-    _smolvm.machine_start(name)
+    if result.returncode != 0:
-    _smolvm.wait_exec_ready(name)
+        # Already-exists is fine on a resume path; everything else
-    return BundleVmLaunch(raw_ports=raw_ports)
+        # is fatal — the bundle won't have an addressable network.
        if "already exists" in (result.stderr or "").lower():
            return
        die(
            f"docker network create {network_name} failed: "
            f"{(result.stderr or '').strip()}"
        )
-def stop_bundle_vm(slug: str) -> None:
+def remove_bundle_network(network_name: str) -> None:
-    """Best-effort sidecar VM teardown."""
+    """Idempotent: a missing network returns success."""
-    name = bundle_machine_name(slug)
+    result = subprocess.run(
-    try:
+        ["docker", "network", "rm", network_name],
-        _smolvm.machine_stop(name)
+        capture_output=True, text=True, check=False,
-    except _smolvm.SmolvmError as exc:
+    )
-        warn(f"smolvm machine stop {name} failed: {exc}")
+    if result.returncode == 0:
-    try:
+        return
-        _smolvm.machine_delete(name)
+    if "no such network" in (result.stderr or "").lower():
-    except _smolvm.SmolvmError as exc:
+        return
-        warn(f"smolvm machine delete {name} failed: {exc}")
+    # Network with attached containers is the common non-fatal
    # case during a partial teardown — warn but don't die.
    warn(
        f"docker network rm {network_name} failed: "
        f"{(result.stderr or '').strip()}"
    )
 def start_bundle(spec: BundleLaunchSpec, *,
                 env: dict[str, str] | None = None) -> None:
    """Bring the bundle container up on the per-bottle bridge with
    the pinned IP. Argv is built deterministically from `spec`;
    `env` is the host subprocess env (forwarded values for any
    bare-name entries in `spec.environment`)."""
    container = bundle_container_name(spec.slug)
    argv = [
        "docker", "run",
        "--name", container,
        "--detach",
        "--rm",
        "--network", spec.network_name,
        "--ip", spec.bundle_ip,
        "-e", f"BOT_BOTTLE_SIDECAR_DAEMONS={spec.daemons_csv}",
    ]
    for entry in spec.environment:
        argv += ["-e", entry]
    for host_path, container_path, read_only in spec.volumes:
        suffix = ":ro" if read_only else ""
        argv += ["-v", f"{host_path}:{container_path}{suffix}"]
    # Loopback-only host port-forwards — the smolvm guest's TSI
    # uses macOS networking, and macOS loopback is the only host
    # surface that round-trips into Docker Desktop's daemon VM.
    # Binds to the per-bottle alias so TSI's IP-only allowlist
    # narrows reachability to this bottle's bundle only.
    for port in spec.ports_to_publish:
        argv += ["-p", f"{spec.publish_host_ip}::{port}"]
    argv.append(spec.image)
    result = subprocess.run(
        argv, capture_output=True, text=True,
        env=dict(env) if env is not None else None, check=False,
    )
    if result.returncode != 0:
        die(
            f"docker run for bundle {container} failed: "
            f"{(result.stderr or '').strip()}"
        )
 def bundle_host_port(
    slug: str, container_port: int, *, host_ip: str = "127.0.0.1",
 ) -> int:
    """`docker port <bundle> <container_port>/tcp` → the random
    host-side port docker assigned for the binding on `host_ip`.
    Called after `start_bundle` on each container port listed in
    `BundleLaunchSpec.ports_to_publish` so the launch step can
    build the agent's HTTPS_PROXY / GIT_GATE / SUPERVISE URLs in
    `<host_ip>:<host port>` form."""
    container = bundle_container_name(slug)
    result = subprocess.run(
        ["docker", "port", container, f"{container_port}/tcp"],
        capture_output=True, text=True, check=False,
    )
    if result.returncode != 0:
        die(
            f"docker port {container} {container_port}/tcp failed: "
            f"{(result.stderr or '').strip() or '<no stderr>'}"
        )
    # Each line looks like `127.0.0.16:54321` — one per address
    # family / host IP. Match on the expected host_ip prefix so
    # bottles bound to per-bottle aliases pick the right line.
    for raw in (result.stdout or "").splitlines():
        line = raw.strip()
        if line.startswith(f"{host_ip}:"):
            _, _, port_str = line.rpartition(":")
            try:
                return int(port_str)
            except ValueError:
                die(f"unexpected `docker port` output: {line!r}")
    die(
        f"no port mapping on {host_ip} for {container} "
        f"{container_port}/tcp; got: {(result.stdout or '').strip()!r}"
    )
 def stop_bundle(slug: str) -> None:
    """Idempotent: a missing container returns success."""
    container = bundle_container_name(slug)
    result = subprocess.run(
        ["docker", "rm", "-f", container],
        capture_output=True, text=True, check=False,
    )
    if result.returncode == 0:
        return
    if "no such container" in (result.stderr or "").lower():
        return
    warn(
        f"docker rm -f {container} failed: "
        f"{(result.stderr or '').strip()}"
    )
@@ -113,11 +113,8 @@ def machine_create(
    *,
    image: str | None = None,
    from_path: Path | None = None,
    net: bool = False,
    allow_cidrs: Sequence[str] = (),
    env: Mapping[str, str] | None = None,
    ports: Sequence[tuple[int, int]] = (),
    volumes: Sequence[tuple[str, str, bool]] = (),
 ) -> None:
    """`smolvm machine create --name NAME [--image IMG | --from PATH]
    [--allow-cidr CIDR ...] [-e K=V ...]`. NAME is passed as
@@ -134,24 +131,19 @@ def machine_create(
    no-pull-at-start property. The flag form gives the same
    result without the Smolfile complication.
-    `--net` is sent explicitly when `net=True` or `allow_cidrs` is
+    `--net` is sent explicitly when `allow_cidrs` is non-empty.
-    non-empty. `--allow-cidr` implies `--net` per the CLI help, but
+    `--allow-cidr` implies `--net` per the CLI help, but sending
-    sending `--net` explicitly is harmless and ensures the guest has
+    `--net` explicitly is harmless and ensures the guest has
    network access even if that implication changes across versions."""
    args: list[str] = ["machine", "create", "--name", name]
    if image is not None:
        args += ["--image", image]
    if from_path is not None:
        args += ["--from", str(from_path)]
-    if net or allow_cidrs:
+    if allow_cidrs:
        args.append("--net")
    for cidr in allow_cidrs:
        args += ["--allow-cidr", cidr]
    for host_port, guest_port in ports:
        args += ["-p", f"{host_port}:{guest_port}"]
    for host_path, guest_path, read_only in volumes:
        suffix = ":ro" if read_only else ""
        args += ["-v", f"{host_path}:{guest_path}{suffix}"]
    if env:
        for k, v in env.items():
            args += ["-e", f"{k}={v}"]
@@ -36,7 +36,6 @@ from ..bottle_state import (
    is_preserved,
    mark_preserved,
 )
 from ..image_cache import StaleImageError
 from ..log import info, die
 from ..manifest import Manifest, ManifestIndex
 from ._common import PROG, USER_CWD, read_tty_line
@@ -64,14 +63,6 @@ def cmd_start(argv: list[str]) -> int:
            "skip all prompts. For orchestrators, CI, and webhooks."
        ),
    )
    parser.add_argument(
        "--cached-images",
        action="store_true",
        help=(
            "quickstart with existing local agent and sidecar images; "
            "only valid with --headless"
        ),
    )
    parser.add_argument(
        "--bottle",
        action="append",
@@ -104,8 +95,6 @@ def cmd_start(argv: list[str]) -> int:
        help="agent name defined in bot-bottle.json (omit to pick interactively)",
    )
    args = parser.parse_args(argv)
    if args.cached_images and not args.headless:
        die("--cached-images is only supported with --headless")
    dry_run = args.dry_run or os.environ.get("BOT_BOTTLE_DRY_RUN") == "1"
@@ -153,10 +142,6 @@ def cmd_start(argv: list[str]) -> int:
    label, color = tui.name_color_modal(default_label=agent_name)
    label, color = _resolve_unique_label(label, color)
    image_policy = _select_image_policy()
    if image_policy is None:
        return 0
    spec = BottleSpec(
        manifest=manifest,
        agent_name=agent_name,
@@ -165,7 +150,6 @@ def cmd_start(argv: list[str]) -> int:
        label=label,
        color=color,
        bottle_names=bottle_names,
        image_policy=image_policy,
    )
    return _launch_bottle(
        spec,
@@ -226,7 +210,6 @@ def _start_headless(
        color=args.color or "",
        bottle_names=bottle_names,
        headless=True,
        image_policy="cached" if args.cached_images else "fresh",
    )
    return _launch_bottle(
        spec,
@@ -407,13 +390,6 @@ def _text_prompt_yes() -> bool:
    return reply in ("y", "Y", "yes", "YES")
 def _select_image_policy() -> str | None:
    return tui.filter_select(
        ["fresh", "cached"],
        title="Select image startup mode",
    )
 def _text_render_preflight():
    def _render(plan: DockerBottlePlan, backend_name: str) -> None:
        print(file=sys.stderr)
@@ -556,15 +532,6 @@ def _launch_bottle(
            return 0
        backend = get_bottle_backend(backend_name)
        try:
            backend.prelaunch_checks(plan)
        except StaleImageError as exc:
            if assume_yes:
                die(str(exc))
            sys.stderr.write(f"bot-bottle: {exc}\nLaunch anyway? [y/N] ")
            sys.stderr.flush()
            if read_tty_line() not in ("y", "Y", "yes", "YES"):
                return 0
        with backend.launch(plan) as bottle:
            agent_provider_template = getattr(plan, "agent_provider_template", "claude")
            extra_args: tuple[str, ...] = ()
@@ -583,6 +550,10 @@ def _launch_bottle(
                f"session ended (exit {exit_code}); "
                f"container {bottle.name} will be removed"
            )
            # While the container is still alive: always snapshot the
            # transcript and — if the agent exited non-zero — mark
            # the state for preservation. This picks up crashes /
            # Ctrl-Cs / OOM kills before cleanup removes the state dir.
            if agent_provider_template == "claude":
                capture_claude_session_state(identity, exit_code)
        return 0
@@ -1,71 +0,0 @@
 """SQLite-backed bot-bottle configuration store."""
 from __future__ import annotations
 from pathlib import Path
 try:
    from .db_store import DbStore
    from .migrations import TableMigrations
    from .supervise_types import host_db_path
 except ImportError:
    from db_store import DbStore  # type: ignore[import-not-found]  # pylint: disable=import-error,no-name-in-module
    from migrations import TableMigrations  # type: ignore[import-not-found]  # pylint: disable=import-error,no-name-in-module
    from supervise_types import host_db_path  # type: ignore[import-not-found]  # pylint: disable=import-error,no-name-in-module
 DEFAULT_CACHED_IMAGE_STALE_WARNING_DAYS = 1
 class ConfigStore(DbStore):
    """SQLite configuration for host-side bot-bottle settings."""
    def __init__(self, db_path: Path | None = None) -> None:
        migrations = TableMigrations("config_store", [
            # v1 — host-side bot-bottle settings
            """
            CREATE TABLE IF NOT EXISTS bot_bottle_config (
                id INTEGER PRIMARY KEY CHECK (id = 1),
                cached_image_stale_warning_days INTEGER NOT NULL DEFAULT 1
            )
            """,
        ])
        super().__init__(db_path or host_db_path(), migrations)
    def cached_image_stale_warning_days(self) -> int:
        if not self.db_path.is_file():
            return DEFAULT_CACHED_IMAGE_STALE_WARNING_DAYS
        with self._connect() as conn:
            row = conn.execute(
                """
                SELECT cached_image_stale_warning_days
                FROM bot_bottle_config
                WHERE id = 1
                """,
            ).fetchone()
        if row is None:
            return DEFAULT_CACHED_IMAGE_STALE_WARNING_DAYS
        try:
            return int(row["cached_image_stale_warning_days"])
        except (TypeError, ValueError):
            return DEFAULT_CACHED_IMAGE_STALE_WARNING_DAYS
    def set_cached_image_stale_warning_days(self, days: int) -> Path:
        with self._connect() as conn:
            conn.execute(
                """
                INSERT INTO bot_bottle_config (id, cached_image_stale_warning_days)
                VALUES (1, ?)
                ON CONFLICT(id) DO UPDATE SET
                    cached_image_stale_warning_days = excluded.cached_image_stale_warning_days
                """,
                (days,),
            )
        self._chmod()
        return self.db_path
 __all__ = [
    "DEFAULT_CACHED_IMAGE_STALE_WARNING_DAYS",
    "ConfigStore",
 ]
@@ -1,42 +0,0 @@
 """Shared helpers for cached-image quickstart stale checks."""
 from __future__ import annotations
 from datetime import datetime, timezone
 from pathlib import Path
 try:
    from .config_store import ConfigStore
 except ImportError:
    from config_store import ConfigStore  # type: ignore[import-not-found]  # pylint: disable=import-error,no-name-in-module
 class StaleImageError(Exception):
    """Raised when a cached image or artifact exceeds the configured staleness
    threshold. Callers can catch this to prompt interactively; headless paths
    let it propagate as a fatal error."""
 def check_stale(label: str, created_at: datetime) -> None:
    """Raise StaleImageError if `created_at` is older than the configured
    stale-warning threshold. Negative threshold disables the check."""
    threshold_days = ConfigStore().cached_image_stale_warning_days()
    if threshold_days < 0:
        return
    now = datetime.now(timezone.utc)
    created = created_at.astimezone(timezone.utc)
    age = now - created
    if age.total_seconds() <= threshold_days * 86400:
        return
    raise StaleImageError(
        f"cached {label} is {age.days} day(s) old; "
        "quickstart does not verify it matches the current Dockerfile/context"
    )
 def check_stale_path(label: str, path: Path) -> None:
    """Raise StaleImageError if `path`'s mtime exceeds the staleness threshold."""
    check_stale(label, datetime.fromtimestamp(path.stat().st_mtime, tz=timezone.utc))
 __all__ = ["StaleImageError", "check_stale", "check_stale_path"]
@@ -6,11 +6,9 @@ from pathlib import Path
 try:
    from .audit_store import AuditStore
    from .config_store import ConfigStore
    from .queue_store import QueueStore
 except ImportError:
    from audit_store import AuditStore  # type: ignore[import-not-found]  # pylint: disable=import-error,no-name-in-module
    from config_store import ConfigStore  # type: ignore[import-not-found]  # pylint: disable=import-error,no-name-in-module
    from queue_store import QueueStore  # type: ignore[import-not-found]  # pylint: disable=import-error,no-name-in-module
 _instance: StoreManager | None = None
@@ -52,13 +50,11 @@ class StoreManager:
        return (
            QueueStore("", self.db_path).is_migrated()
            and AuditStore(self.db_path).is_migrated()
            and ConfigStore(self.db_path).is_migrated()
        )
    def migrate(self) -> None:
        QueueStore("", self.db_path).migrate()
        AuditStore(self.db_path).migrate()
        ConfigStore(self.db_path).migrate()
 __all__ = ["StoreManager"]
@@ -1,115 +0,0 @@
 # PRD prd-new: smolmachines sidecar VM
 - **Status:** Active
 - **Author:** codex
 - **Created:** 2026-07-09
 - **Issue:** #332
 ## Summary
 Run the smolmachines backend's trusted sidecar bundle as its own smolVM instead
 of a Docker container. A bottle then consists of an agent VM plus a sidecar VM,
 with the agent VM's TSI allowlist limited to the per-bottle agent-facing
 sidecar surface.
 ## Problem
 The smolmachines backend currently runs the agent in smolVM but keeps
 egress/git-gate/supervise in a Docker sidecar bundle. That hybrid launch path
 keeps Docker in the trusted runtime path and leaves smolmachines with a
 different isolation boundary than its agent VM design suggests.
 The existing Docker sidecar path also uses Docker port publishing to bind only
 agent-facing services to the per-bottle host address. TSI is IP-only, so the
 smolVM replacement must preserve that scoping: publishing sidecar services on
 generic host localhost would let the agent reach unrelated host services or
 other bottle sidecars if those services share the allowed address.
 ## Goals / Success Criteria
 1. `BOT_BOTTLE_BACKEND=smolmachines ./cli.py start <agent>` runs with both the
   agent and sidecar as smolVMs.
 2. The smolmachines launch path no longer uses `docker run` for the sidecar
   bundle.
 3. Agent-facing egress, git-gate, and supervise endpoints are exposed only
   through the bottle's own published sidecar surface.
 4. Internal sidecar-only ports are not reachable from the agent VM.
 5. The agent VM TSI allowlist remains fail-closed and limited to the per-bottle
   address.
 6. Sidecar config, secrets, and state are delivered to the sidecar VM without
   exposing provider or forge credentials to the agent VM.
 7. Teardown removes both VMs and any host-side published port state.
 ## Non-goals
 - Rewriting the egress, git-gate, or supervise daemons.
 - Changing the Docker backend's sidecar bundle behavior.
 - Replacing the existing agent image build and pack pipeline except where shared
  helper extraction is needed for sidecar image packing.
 - Weakening the current smolmachines TSI allowlist checks.
 ## Design
 The sidecar VM continues to use the existing sidecar bundle image and
 `/app/sidecar_init.py` supervisor. The launch flow builds the sidecar image,
 packs it into a `.smolmachine` artifact, creates a per-bottle sidecar VM from
 that artifact, passes the same daemon-selection environment the Docker bundle
 uses today, mounts or copies the same daemon-private config/state inputs, starts
 the sidecar VM, wraps the sidecar VM's raw smolVM-published ports with a local
 per-bottle forwarder, then starts the agent VM with
 `--allow-cidr <per-bottle-address>/32`.
 smolVM currently exposes guest ports as `HOST:GUEST` port pairs bound on host
 loopback. It does not expose an address-scoped bind like
 `127.0.0.16:<port>:9099`. Because TSI is IP-only, bot-bottle must not advertise
 those raw loopback ports directly to the agent. Instead, bot-bottle runs one
 small stdlib Python TCP forwarder process per bottle:
 ```text
 agent VM
  -> TSI allows only <bottle-address>/32
  -> bot-bottle forwarder bound to <bottle-address>:<random-port>
  -> raw smolVM-published sidecar port on 127.0.0.1:<raw-port>
  -> sidecar VM service
 ```
 Agent-facing URLs are stamped from the forwarder ports, never the raw smolVM
 ports:
 - `HTTP_PROXY` / `HTTPS_PROXY` point at the published egress proxy port.
 - `GIT_GATE_URL` points at the published git HTTP port when git-gate is enabled.
 - `MCP_SUPERVISE_URL` points at the published supervise port when supervise is
  enabled.
 Internal sidecar-only services stay bound inside the sidecar VM and are not
 published.
 ### Forwarder constraints
 - Reject wildcard listener binds (`0.0.0.0`, `::`) and generic localhost
  listener binds (`127.0.0.1`, `::1`) for agent-facing forwards.
 - Accept only fixed loopback targets selected by launch; the client cannot
  choose or influence the forwarding target.
 - Forward bytes transparently without parsing HTTP, CONNECT, TLS, Git, or MCP.
 - Log lifecycle and endpoint metadata only; never log payload bytes.
 - Create forwards only for egress, git HTTP when enabled, and supervise when
  enabled.
 - Fail closed if any listener cannot bind exactly the requested per-bottle
  address.
 ## Implementation chunks
 1. Extract the existing image-to-smolmachine pack helper so agent and sidecar
   artifacts share the same cache and registry path.
 2. Add a strict stdlib host TCP forwarder for per-bottle address-bound
   forwarding to raw smolVM-published sidecar ports.
 3. Add a sidecar VM launch spec and lifecycle helpers: pack, create, start,
   publish/discover ports, stop, delete.
 4. Switch smolmachines launch from Docker sidecar bundle lifecycle to sidecar VM
   plus forwarder lifecycle.
 5. Update egress apply / reload paths for the sidecar VM supervisor.
 6. Add unit tests for argv shape, URL stamping, teardown, and fail-closed
   behavior.
 7. Add or update integration coverage for agent-to-sidecar reachability, host
   localhost denial, other-bottle alias denial, internal port denial, and
   teardown cleanup.
@@ -1,14 +1,20 @@
-# Landscape: containerized Claude Code agent tools
+# Landscape: containerized AI coding agent tools
 Research into whether bot-bottle is redundant with existing projects, and
 whether it's worth publishing.
 ## Summary
-The "Claude Code in Docker" space is active but not saturated. bot-bottle
+The "AI coding agents in isolated sandboxes" space is active but not saturated.
-occupies a distinct position: no surveyed project combines all five of its
+bot-bottle occupies a distinct position: no surveyed project combines all five
-defining features. Publishing is likely worthwhile, with the main risk being
+of its defining features. Publishing is likely worthwhile, with the main risk
-claudebox expanding to absorb the same niche.
+being claudebox expanding to absorb the same niche.
 **Updated 2026-07-09:** bot-bottle now supports three isolation backends
 (Docker, Apple `container`, smolmachines/libkrun microVMs) and three built-in
 agent providers (Claude Code, OpenAI Codex, Pi) with an open plugin system for
 arbitrary providers. This meaningfully strengthens the differentiation against
 all surveyed competitors.
 ## Closest competitor: claudebox
@@ -43,28 +49,78 @@ manifest merge.
  Still marked early-development.
 - **E2B, Northflank, Cloudflare Sandbox SDK** — cloud-hosted SaaS sandbox
  runtimes; fundamentally different architecture.
 - **superhq.ai / SuperHQ** (v0.4.4, April 2026) — macOS desktop app (Rust/GPUI)
  that runs Claude Code, Codex, and Pi inside microVMs via Apple's
  Virtualization.framework (their own shuru-sdk / libkrun). Auth gateway
  injects API keys on the wire so the sandbox never sees them; tmpfs overlay
  stages agent writes for diff-and-accept review; mobile remote access via
  remote.superhq.ai. Early alpha, free on launch, Apple Silicon only.
  Overlap: both projects cover agent isolation, credential proxying, and
  multi-provider support (Claude Code / Codex / Pi). Differences: SuperHQ is a
  GUI desktop app with no manifest layer; bot-bottle is a CLI fleet manager with
  named agents, skills injection, per-agent system prompts, and cross-platform
  backends (Docker, Apple `container`, smolmachines). SuperHQ's microVM
  isolation story is now partially matched by bot-bottle's `macos_container` and
  smolmachines backends. Worth watching — it targets the same security-minded
  power-user audience and moves fast.
  **Known gap in SuperHQ (user-requested, as of 2026-07-09):** A named user
  (Brian Cheong, Founder, Dunialabs.io) explicitly called out the absence of
  per-run audit logging: tool calls and network egress. Bot-bottle covers both:
  network egress is logged by pipelock/mitmproxy, and per-run op-log/audit state
  is persisted to SQLite.
 ## What no found project does
 None combine:
-1. Named-agent JSON manifest with per-agent env resolution (prompt / host-forward / literal)
+1. Named-agent manifest with per-agent env resolution (prompt / host-forward / literal), supporting multiple providers (Claude Code, Codex, Pi, arbitrary plugins)
-2. Claude Code skills directory injection
+2. Skills directory injection
 3. Per-agent system prompts
 4. SSH-agent key forwarding without copying private keys into the container
 5. Home + project manifest merge
 6. Pluggable isolation backends: Docker (Linux/macOS), Apple `container` (macOS microVMs), smolmachines/libkrun microVMs
 7. Per-run audit log: network egress via pipelock/mitmproxy + op-log persisted to SQLite
 **In-flight directions (not yet shipped):**
 - **Forge-native dispatch (issue #317):** Gitea webhook → orchestrator spins up a bottle
  with the issue body as prompt → agent works → bottle freezes awaiting review comment →
  rehydrates on comment → tears down on PR close. The issue-to-PR lifecycle concept is not
  novel (Devin, Copilot Workspace, SWE-agent all do this as cloud services); what's
  distinct is doing it self-hosted, manifest-driven, inside bot-bottle's isolation
  primitives.
 - **Paid web control plane (issue #327):** Browser-based multi-host agent launch and
  monitoring; account-scoped bottle and agent definitions; secret custody (encrypted at
  rest, injected into the sidecar at launch, never exposed to the agent or returned by any
  read API). Monetization model: OSS runtime free, control plane paid — a standard split
  (HashiCorp, Grafana) applied to a self-hosted agent sandbox. The principled secret
  custody model (agent never sees real credentials, even via printenv) is more rigorous
  than most surveyed tools but not unprecedented.
 ## Publishing verdict
 Worth publishing. Differentiators that matter to the target audience (power
-users running parallel Claude Code sessions with distinct personas/tooling):
+users running parallel AI coding agent sessions with distinct personas/tooling):
- The Python-stdlib-first, low-dependency design — competitors are npm-based or
+- The Python-stdlib-first, low-dependency design — competitors are npm-based,
-  Kubernetes-native.
+  Rust/GUI, or Kubernetes-native.
 - Named agents with distinct skills and system prompts, not just language profiles.
 - Multi-backend isolation: Docker, Apple `container` microVMs, and
  smolmachines/libkrun — single manifest works across all three.
 - Multi-provider: Claude Code, Codex, Pi, plus an open plugin system for
  arbitrary providers.
 - SSH forwarding without key copying.
 - Per-run audit log (tool calls + network egress) — an explicitly requested gap
  in SuperHQ as of 2026-07-09.
 - Forge-native dispatch and a paid control plane (in flight) bring bot-bottle
  into the same product category as cloud services like Devin and Copilot
  Workspace — but self-hosted, with stronger isolation guarantees and a
  manifest-driven fleet model those services don't have.
-Main risk: claudebox adds manifest/agent config. The space is moving fast
+Main risk: claudebox adds manifest/agent config; SuperHQ is moving fast on the
-enough that publishing sooner is better if establishing prior art matters.
+GUI / microVM side. The space is moving fast enough that publishing sooner is
 better if establishing prior art matters.
 Discovery will be slow without active promotion; an Anthropic Discord post or
 HN "Show HN" would do most of the work.
@@ -73,4 +129,4 @@ HN "Show HN" would do most of the work.
 - GitHub search cannot surface private or very new repos comprehensively.
 - Counts (stars, forks) were not confirmed for every project.
- Research conducted 2026-05-07; the space moves fast.
+- Initial research conducted 2026-05-07; SuperHQ entry added 2026-07-09; the space moves fast.
@@ -0,0 +1,111 @@
 """Integration: PRD 0023 chunk 2c — bundle bringup on a per-bottle
 docker bridge with the pinned IP.
 End-to-end against the real docker daemon. Brings up just the
 sidecar bundle on its own bridge, confirms the container lands at
 the pinned IP, then tears down. Skipped under act_runner (docker
 socket mount topology breaks bridge visibility) and when the
 bundle image isn't available.
 Full launch flow (smolvm + bundle + provisioning + the
 localhost-reach / egress-port-bypass probes) lives in chunk 2d."""
 from __future__ import annotations
 import os
 import subprocess
 import time
 import unittest
 from bot_bottle.backend.smolmachines.sidecar_bundle import (
    BundleLaunchSpec,
    bundle_container_name,
    bundle_network_name,
    create_bundle_network,
    remove_bundle_network,
    start_bundle,
    stop_bundle,
 )
 from tests._docker import skip_unless_docker
@skip_unless_docker()
@unittest.skipIf(
    os.environ.get("GITEA_ACTIONS") == "true",
    "skipped under act_runner: docker socket mount topology breaks "
    "in-process visibility of networks created on the host daemon",
 )
 class TestBundleBringup(unittest.TestCase):
    def setUp(self):
        self.slug = f"cb-test-bundle-{os.getpid()}-{int(time.time())}"
        self.network = bundle_network_name(self.slug)
        self.container = bundle_container_name(self.slug)
    def tearDown(self):
        stop_bundle(self.slug)
        remove_bundle_network(self.network)
    def _bundle_image_built(self) -> bool:
        """The bundle image (`bot-bottle-sidecars:latest`) is
        built lazily by the docker backend's compose. If a
        smolmachines-only operator hasn't run the docker backend
        first, the image won't exist locally. Skip rather than
        fail."""
        r = subprocess.run(
            ["docker", "image", "inspect", "bot-bottle-sidecars:latest"],
            stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
            check=False,
        )
        return r.returncode == 0
    def test_create_network_then_start_bundle_pins_ip(self):
        if not self._bundle_image_built():
            self.skipTest(
                "bot-bottle-sidecars:latest not built; run a docker "
                "bottle first or `docker build -f Dockerfile.sidecars .`"
            )
        # Pick a subnet unlikely to collide on the host. Last
        # octet of the slug hash isn't deterministic across runs;
        # we hardcode a high octet (.211) that the docker default
        # bridges almost never use.
        subnet = "192.168.211.0/24"
        gateway = "192.168.211.1"
        bundle_ip = "192.168.211.2"
        create_bundle_network(self.network, subnet, gateway)
        spec = BundleLaunchSpec(
            slug=self.slug,
            network_name=self.network,
            subnet=subnet,
            gateway=gateway,
            bundle_ip=bundle_ip,
            # Empty daemons_csv → init exits "no daemons selected"
            # immediately. We just need the container to land on
            # the network at the right IP before it exits.
            daemons_csv="",  # empty → init exits "no daemons selected"
        )
        start_bundle(spec)
        # Inspect the container's IP on the per-bottle network.
        r = subprocess.run(
            ["docker", "inspect",
             "--format",
             "{{(index .NetworkSettings.Networks \"" + self.network + "\").IPAddress}}",
             self.container],
            capture_output=True, text=True, check=False,
        )
        # Container may have exited (no daemons selected → exit 0).
        # The inspect still works on exited containers as long as
        # `--rm` hasn't fired yet, which is a race. Even if it has,
        # the launch succeeded — the container existed, on the
        # right network, at the right IP. We don't fail here on
        # missing inspect.
        if r.returncode == 0 and r.stdout.strip():
            self.assertEqual(bundle_ip, r.stdout.strip(),
                             f"bundle landed at wrong IP: {r.stdout!r}")
 if __name__ == "__main__":
    unittest.main()
@@ -1,9 +1,10 @@
-"""Integration: end-to-end smolmachines launch + exec round trip.
+"""Integration: PRD 0023 chunk 2d — end-to-end launch + exec
 round trip + the acceptance probes.
-The smoke confirms the launch flow (sidecar bundle smolVM →
+The smoke confirms the launch flow (per-bottle docker bridge →
-host-loopback forwarders → agent smolVM with TSI allowlist → exec)
+sidecar bundle with host-loopback published ports → smolvm guest
-plumbs together end to end. The probes confirm the security
+with TSI allowlist → exec) plumbs together end to end. The probes confirm the
-properties the design pivot was about:
+security properties the design pivot was about:
  - **localhost-reach probe** — guest tries to dial a service
    bound on the host's `127.0.0.1`. TSI's per-bottle loopback
@@ -13,6 +14,13 @@ properties the design pivot was about:
    the injected `HTTPS_PROXY`/`HTTP_PROXY` URL on the per-bottle
    loopback alias, while direct egress with proxy vars unset fails.
  - **egress-port-bypass probe** — guest tries to dial
    `<bundle-ip>:9099` (egress's port). TSI permits the IP but
    the bundle's egress daemon binds `127.0.0.1` inside its
    container, so the connect refuses at the socket level. The
    bind-address mitigation is what closes TSI's port-granularity
    gap.
 Gated on macOS/Linux + smolvm + docker + not GITEA_ACTIONS — the
 runner can't host libkrun-backed VMs."""
@@ -106,8 +114,8 @@ class TestSmolmachinesLaunch(unittest.TestCase):
    def test_localhost_reach_probe(self):
        # Agent dials a 127.0.0.1 service on the host. TSI's
-        # allowlist contains only the per-bottle loopback alias, so
+        # allowlist contains only <bundle-ip>/32, so this must
-        # this must refuse. We use a port unlikely to be bound on the host
+        # refuse. We use a port unlikely to be bound on the host
        # (high-numbered) so we're confirming TSI refusal, not
        # just "no service listening."
        r = self.bottle.exec(
@@ -188,6 +196,28 @@ class TestSmolmachinesLaunch(unittest.TestCase):
        self.assertEqual(0, r.returncode, msg=r.stderr)
        self.assertEqual(_AGENT_PROMPT, r.stdout.rstrip("\n"))
    def test_egress_port_bypass_probe(self):
        # Agent dials <bundle-ip>:9099 (egress's port). TSI
        # permits the IP, but egress will bind 127.0.0.1:9099
        # inside the bundle in chunk 3, so the connect refuses
        # at the socket level. NOTE: in chunk 2d the bundle's
        # daemons aren't running (daemons_csv=""), so nothing
        # is listening on :9099 anyway — this test asserts the
        # connect fails, which is the property chunk 3 will
        # preserve once egress is actually running.
        r = self.bottle.exec(
            "env -u HTTPS_PROXY -u HTTP_PROXY -u https_proxy -u http_proxy "
            f"curl -s --show-error --max-time 3 http://{self.plan.bundle_ip}:9099 "
            "2>&1 || true"
        )
        self.assertTrue(
            "refused" in r.stdout.lower()
            or "timed out" in r.stdout.lower()
            or "unreachable" in r.stdout.lower()
            or "failed" in r.stdout.lower(),
            f"expected egress port refusal; got: {r.stdout!r}",
        )
 if __name__ == "__main__":
    unittest.main()
@@ -184,18 +184,6 @@ class TestCmdStartHeadless(unittest.TestCase):
        )
        self.assertEqual("docker", self._launch_mock.call_args[1]["backend_name"])
    def test_cached_images_sets_cached_policy(self):
        start_mod.cmd_start(
            ["--headless", "--cached-images", "researcher", "--bottle", "claude",
             "--prompt", "Do it"]
        )
        self.assertEqual("cached", self._spec().image_policy)
    def test_cached_images_requires_headless(self):
        with self.assertRaises(Die):
            start_mod.cmd_start(["--cached-images", "researcher"])
        self._launch_mock.assert_not_called()
 class TestPrepareWithPreflight(unittest.TestCase):
    """prepare_with_preflight calls render_preflight with the plan and backend name."""
@@ -57,12 +57,6 @@ class TestCmdStartSelector(unittest.TestCase):
        self._bottle_picker_mock = self._bottle_picker_patch.start()
        self._bottle_picker_mock.return_value = ["claude"]  # default: one bottle selected
        self._image_policy_patch = patch(
            "bot_bottle.cli.start._select_image_policy",
            return_value="fresh",
        )
        self._image_policy_patch.start()
        self._env_patch = patch.dict(os.environ, {}, clear=False)
        self._env_patch.start()
        os.environ.pop("BOT_BOTTLE_BACKEND", None)
@@ -72,7 +66,6 @@ class TestCmdStartSelector(unittest.TestCase):
        self._launch_patch.stop()
        self._agent_picker_patch.stop()
        self._bottle_picker_patch.stop()
        self._image_policy_patch.stop()
        self._env_patch.stop()
    # ------------------------------------------------------------------
@@ -131,19 +124,6 @@ class TestCmdStartSelector(unittest.TestCase):
        spec = self._launch_mock.call_args[0][0]
        self.assertEqual(("claude", "dev"), spec.bottle_names)
    def test_image_policy_forwarded_to_spec(self):
        with patch("bot_bottle.cli.start._select_image_policy", return_value="cached"):
            start_mod.cmd_start(["researcher"])
        self._launch_mock.assert_called_once()
        spec = self._launch_mock.call_args[0][0]
        self.assertEqual("cached", spec.image_policy)
    def test_image_policy_cancel_returns_0(self):
        with patch("bot_bottle.cli.start._select_image_policy", return_value=None):
            rc = start_mod.cmd_start(["researcher"])
        self.assertEqual(0, rc)
        self._launch_mock.assert_not_called()
    def test_empty_bottle_selection_forwarded(self):
        self._bottle_picker_mock.return_value = []
        start_mod.cmd_start(["researcher"])
@@ -235,7 +215,6 @@ class TestCmdStartLabelCollision(unittest.TestCase):
        ).start()
        # Stub the bottle picker to always return a selection.
        patch.object(tui_mod, "filter_multiselect", return_value=["claude"]).start()
        patch("bot_bottle.cli.start._select_image_policy", return_value="fresh").start()
        self.addCleanup(patch.stopall)
    def test_no_collision_proceeds_without_reprompt(self):
@@ -1,146 +0,0 @@
 """Unit: _launch_bottle StaleImageError handling.
 Exercises prelaunch_checks / backend.launch flow:
  - headless mode → die on stale
  - interactive mode, user declines → stop without launching
  - interactive mode, user confirms → skip stale check and launch once
 """
 from __future__ import annotations
 import io
 import tempfile
 import unittest
 from types import SimpleNamespace
 from typing import Any, cast
 from unittest.mock import MagicMock, patch
 from bot_bottle.image_cache import StaleImageError
 from bot_bottle.log import Die
 def _fake_plan() -> Any:
    provision = SimpleNamespace(startup_args=())
    return cast(Any, SimpleNamespace(
        agent_provision=provision,
        agent_provider_template="claude",
        slug="dev-abc",
    ))
 def _ok_cm(bottle: Any) -> MagicMock:
    """Return a context-manager mock that yields `bottle`."""
    cm = MagicMock()
    cm.__enter__ = MagicMock(return_value=bottle)
    cm.__exit__ = MagicMock(return_value=False)
    return cm
 class TestLaunchBottleStaleHandling(unittest.TestCase):
    def setUp(self) -> None:
        self._tmp = tempfile.mkdtemp(prefix="cli-stale-test.")
    def _spec(self) -> Any:
        from bot_bottle.backend import BottleSpec
        from bot_bottle.manifest import ManifestIndex
        idx = ManifestIndex.from_json_obj({
            "bottles": {"dev": {}},
            "agents": {"demo": {"skills": [], "prompt": "", "bottle": "dev"}},
        })
        return BottleSpec(
            manifest=idx,
            agent_name="demo",
            copy_cwd=False,
            user_cwd=self._tmp,
            identity="dev-abc",
        )
    def _run_launch(self, **patch_kwargs: Any) -> int:
        import bot_bottle.cli.start as start_mod
        spec = self._spec()
        with patch.object(start_mod, "prepare_with_preflight",
                          return_value=(_fake_plan(), "dev-abc")), \
             patch.object(start_mod, "settle_state"), \
             patch.object(start_mod, "info"):
            return start_mod._launch_bottle(
                spec,
                dry_run=False,
                backend_name="docker",
                **patch_kwargs,
            )
    def test_headless_stale_calls_die(self) -> None:
        """In headless mode (assume_yes=True), a StaleImageError from prelaunch_checks must call die()."""
        import bot_bottle.cli.start as start_mod
        backend_mock = MagicMock()
        backend_mock.prelaunch_checks.side_effect = StaleImageError("image is 5 day(s) old")
        with patch.object(start_mod, "get_bottle_backend", return_value=backend_mock), \
             patch.object(start_mod, "die", side_effect=Die()):
            with self.assertRaises(Die):
                self._run_launch(assume_yes=True)
        backend_mock.launch.assert_not_called()
    def test_interactive_user_declines_stops_before_launch(self) -> None:
        """Interactive user answering 'n' → launch is never called."""
        import bot_bottle.cli.start as start_mod
        backend_mock = MagicMock()
        backend_mock.prelaunch_checks.side_effect = StaleImageError("image is 5 day(s) old")
        with patch.object(start_mod, "get_bottle_backend", return_value=backend_mock), \
             patch.object(start_mod, "read_tty_line", return_value="n"), \
             patch("sys.stderr", new_callable=io.StringIO):
            rc = self._run_launch(assume_yes=False)
        self.assertEqual(0, rc)
        backend_mock.launch.assert_not_called()
    def test_interactive_user_confirms_launches_once(self) -> None:
        """Interactive user answering 'y' → prelaunch stale error is bypassed; launch called once."""
        import bot_bottle.cli.start as start_mod
        bottle_mock = MagicMock()
        bottle_mock.name = "dev-abc"
        backend_mock = MagicMock()
        backend_mock.prelaunch_checks.side_effect = StaleImageError("image is 5 day(s) old")
        backend_mock.launch.return_value = _ok_cm(bottle_mock)
        with patch.object(start_mod, "get_bottle_backend", return_value=backend_mock), \
             patch.object(start_mod, "read_tty_line", return_value="y"), \
             patch.object(start_mod, "attach_agent", return_value=0), \
             patch.object(start_mod, "capture_claude_session_state"), \
             patch("sys.stderr", new_callable=io.StringIO):
            rc = self._run_launch(assume_yes=False)
        self.assertEqual(0, rc)
        backend_mock.prelaunch_checks.assert_called_once()
        backend_mock.launch.assert_called_once()
    def test_interactive_yes_uppercase_also_accepted(self) -> None:
        """'Y' or 'YES' should also be accepted as confirmation."""
        import bot_bottle.cli.start as start_mod
        bottle_mock = MagicMock()
        bottle_mock.name = "dev-abc"
        backend_mock = MagicMock()
        backend_mock.prelaunch_checks.side_effect = StaleImageError("image is 5 day(s) old")
        backend_mock.launch.return_value = _ok_cm(bottle_mock)
        with patch.object(start_mod, "get_bottle_backend", return_value=backend_mock), \
             patch.object(start_mod, "read_tty_line", return_value="YES"), \
             patch.object(start_mod, "attach_agent", return_value=0), \
             patch.object(start_mod, "capture_claude_session_state"), \
             patch("sys.stderr", new_callable=io.StringIO):
            rc = self._run_launch(assume_yes=False)
        self.assertEqual(0, rc)
        backend_mock.launch.assert_called_once()
 if __name__ == "__main__":
    unittest.main()
@@ -118,7 +118,6 @@ def _plan(
    with_egress: bool = False,
    supervise: bool = False,
    canary: bool = False,
    image_policy: str = "fresh",
 ) -> DockerBottlePlan:
    """Build a fully-resolved DockerBottlePlan. Toggles cover the
    matrix the renderer's conditional-service logic branches on."""
@@ -149,7 +148,6 @@ def _plan(
        agent_name="demo",
        copy_cwd=False,
        user_cwd="/tmp/x",
        image_policy=image_policy,
    )
    return DockerBottlePlan(
        spec=spec,
@@ -267,8 +265,7 @@ class TestAgentAlwaysPresent(unittest.TestCase):
    def test_agent_depends_only_on_sidecars(self):
        # Bundle shape: the init supervisor owns intra-bundle daemon
        # ordering, so the agent waits on the bundle container alone.
-        cases: list[dict[str, Any]] = [{}, {"with_git": True, "with_egress": True, "supervise": True}]
+        for kwargs in [{}, {"with_git": True, "with_egress": True, "supervise": True}]:
        for kwargs in cases:
            with self.subTest(**kwargs):
                s = bottle_plan_to_compose(_plan(**kwargs))["services"]["agent"]
                self.assertEqual(["sidecars"], s["depends_on"])
@@ -303,11 +300,6 @@ class TestSidecarBundleShape(unittest.TestCase):
        self.assertEqual("bot-bottle-sidecars:latest", sc["image"])
        self.assertEqual("Dockerfile.sidecars", sc["build"]["dockerfile"])
    def test_cached_policy_omits_bundle_build(self):
        sc = self._render(image_policy="cached")["services"]["sidecars"]
        self.assertEqual("bot-bottle-sidecars:latest", sc["image"])
        self.assertNotIn("build", sc)
    def test_bundle_container_name_uses_sidecars_prefix(self):
        sc = self._render()["services"]["sidecars"]
        self.assertEqual(f"bot-bottle-sidecars-{SLUG}", sc["container_name"])
@@ -1,86 +0,0 @@
 """Unit tests for the host-side configuration store."""
 from __future__ import annotations
 import sqlite3
 import tempfile
 import unittest
 from pathlib import Path
 from bot_bottle.config_store import (
    DEFAULT_CACHED_IMAGE_STALE_WARNING_DAYS,
    ConfigStore,
 )
 from bot_bottle.store_manager import StoreManager
 class TestConfigStore(unittest.TestCase):
    def test_cached_image_warning_days_defaults_to_one(self) -> None:
        with tempfile.TemporaryDirectory(prefix="config-store.") as tmp:
            store = ConfigStore(Path(tmp) / "bot-bottle.db")
            store.migrate()
            self.assertEqual(
                DEFAULT_CACHED_IMAGE_STALE_WARNING_DAYS,
                store.cached_image_stale_warning_days(),
            )
    def test_cached_image_warning_days_reads_value(self) -> None:
        with tempfile.TemporaryDirectory(prefix="config-store.") as tmp:
            store = ConfigStore(Path(tmp) / "bot-bottle.db")
            store.migrate()
            store.set_cached_image_stale_warning_days(7)
            self.assertEqual(7, store.cached_image_stale_warning_days())
    def test_config_schema_uses_explicit_settings_columns(self) -> None:
        with tempfile.TemporaryDirectory(prefix="config-store.") as tmp:
            store = ConfigStore(Path(tmp) / "bot-bottle.db")
            store.migrate()
            with sqlite3.connect(store.db_path) as conn:
                conn.row_factory = sqlite3.Row
                columns = [
                    row["name"]
                    for row in conn.execute("PRAGMA table_info(bot_bottle_config)")
                ]
            self.assertEqual([
                "id",
                "cached_image_stale_warning_days",
            ], columns)
    def test_store_manager_includes_config_store(self) -> None:
        with tempfile.TemporaryDirectory(prefix="config-store.") as tmp:
            db = Path(tmp) / "bot-bottle.db"
            manager = StoreManager(db)
            self.assertFalse(manager.is_migrated())
            manager.migrate()
            self.assertTrue(manager.is_migrated())
    def test_cached_image_warning_days_returns_default_when_db_missing(self) -> None:
        # When the db file doesn't exist yet (parent exists, file doesn't),
        # the store returns the default without touching the file.
        with tempfile.TemporaryDirectory(prefix="config-store.") as tmp:
            store = ConfigStore(Path(tmp) / "missing.db")
            self.assertEqual(
                DEFAULT_CACHED_IMAGE_STALE_WARNING_DAYS,
                store.cached_image_stale_warning_days(),
            )
    def test_cached_image_warning_days_returns_default_on_null_value(self) -> None:
        # If the row exists but the value is NULL (or not castable to int),
        # the store falls back to the default.
        with tempfile.TemporaryDirectory(prefix="config-store.") as tmp:
            db_path = Path(tmp) / "bot-bottle.db"
            store = ConfigStore(db_path)
            store.migrate()
            # Write a NULL value directly.
            with sqlite3.connect(db_path) as conn:
                conn.execute(
                    "UPDATE bot_bottle_config SET cached_image_stale_warning_days = NULL WHERE id = 1"
                )
            self.assertEqual(
                DEFAULT_CACHED_IMAGE_STALE_WARNING_DAYS,
                store.cached_image_stale_warning_days(),
            )
 if __name__ == "__main__":
    unittest.main()
@@ -3,7 +3,6 @@
 from __future__ import annotations
 import contextlib
 import dataclasses
 import io
 import tempfile
 import unittest
@@ -17,7 +16,6 @@ from bot_bottle.backend.docker import launch as launch_mod
 from bot_bottle.backend.docker.bottle_plan import DockerBottlePlan
 from bot_bottle.egress import EgressPlan
 from bot_bottle.git_gate import GitGatePlan
 from bot_bottle.log import Die
 from bot_bottle.manifest import ManifestIndex
@@ -90,7 +88,7 @@ class TestLaunchCommittedImage(unittest.TestCase):
        committed_tag: str | None = None,
        image_present: bool = True,
    ) -> list[str]:
-        """Drive build_or_load_images() + launch() with the committed-image
+        """Drive launch() through its full sequence with the committed-image
        behaviour controlled by the arguments. Returns the images that were
        passed to `build_image` (empty list if it was never called)."""
        built: list[str] = []
@@ -124,9 +122,8 @@ class TestLaunchCommittedImage(unittest.TestCase):
           mock.patch.object(launch_mod, "compose_dump_logs"), \
           mock.patch.object(launch_mod, "compose_down"), \
           contextlib.redirect_stderr(io.StringIO()):
            images = launch_mod.build_or_load_images(plan)
            provision = mock.Mock(return_value=None)
-            with launch_mod.launch(plan, images, provision=provision):
+            with launch_mod.launch(plan, provision=provision):
                pass
        return built
@@ -171,9 +168,8 @@ class TestLaunchCommittedImage(unittest.TestCase):
           mock.patch.object(launch_mod, "compose_dump_logs"), \
           mock.patch.object(launch_mod, "compose_down"), \
           contextlib.redirect_stderr(io.StringIO()):
            images = launch_mod.build_or_load_images(plan)
            provision = mock.Mock(return_value=None)
-            with launch_mod.launch(plan, images, provision=provision):
+            with launch_mod.launch(plan, provision=provision):
                pass
        self.assertEqual(1, len(captured_plans))
@@ -184,24 +180,6 @@ class TestLaunchCommittedImage(unittest.TestCase):
        built = self._run_launch(plan, committed_tag=None)
        self.assertEqual([_DEFAULT_IMAGE], built)
    def test_cached_images_skip_build_when_present(self) -> None:
        base = _plan(self._tmp)
        plan = dataclasses.replace(
            base,
            spec=dataclasses.replace(base.spec, image_policy="cached"),
        )
        built = self._run_launch(plan, committed_tag=None, image_present=True)
        self.assertEqual([], built)
    def test_cached_images_die_when_agent_missing(self) -> None:
        base = _plan(self._tmp)
        plan = dataclasses.replace(
            base,
            spec=dataclasses.replace(base.spec, image_policy="cached"),
        )
        with self.assertRaises(Die):
            self._run_launch(plan, committed_tag=None, image_present=False)
    def test_falls_back_to_build_when_committed_image_missing_from_daemon(self) -> None:
        plan = _plan(self._tmp)
        built = self._run_launch(
@@ -16,7 +16,7 @@ from pathlib import Path
 from unittest import mock
 from bot_bottle.agent_provider import AgentProvisionPlan
-from bot_bottle.backend import BottleImages, BottleSpec
+from bot_bottle.backend import BottleSpec
 from bot_bottle.backend.docker import launch as launch_mod
 from bot_bottle.backend.docker.bottle_plan import DockerBottlePlan
 from bot_bottle.egress import EgressPlan
@@ -86,8 +86,6 @@ class TestTeardownWarning(unittest.TestCase):
        plan = _plan(self._tmp)
        buf = io.StringIO()
        images = BottleImages(agent="bot-bottle-claude:latest", sidecar="bot-bottle-sidecars:latest")
        with mock.patch.object(launch_mod.docker_mod, "build_image"), \
             mock.patch.object(
                 launch_mod, "egress_tls_init",
@@ -117,7 +115,7 @@ class TestTeardownWarning(unittest.TestCase):
             ), \
             contextlib.redirect_stderr(buf):
            provision = mock.Mock(return_value=None)
-            with launch_mod.launch(plan, images, provision=provision):
+            with launch_mod.launch(plan, provision=provision):
                pass
        output = buf.getvalue()
@@ -9,7 +9,6 @@ from __future__ import annotations
 import subprocess
 import unittest
 from datetime import timezone
 from unittest.mock import patch
 from bot_bottle.backend.docker import util as docker_mod
@@ -55,51 +54,6 @@ class TestImageId(unittest.TestCase):
            self.assertIn("missing:tag", die.call_args.args[0])
 class TestImageCreatedAt(unittest.TestCase):
    def test_parses_docker_timestamp_with_nanoseconds(self):
        with patch.object(
            docker_mod.subprocess, "run",
            return_value=_ok(stdout="2026-07-06T15:33:47.123456789Z\n"),
        ) as run:
            created = docker_mod.image_created_at("bot-bottle-claude:latest")
        self.assertEqual(2026, created.year)
        self.assertEqual(123456, created.microsecond)
        self.assertEqual(timezone.utc, created.tzinfo)
        self.assertEqual(
            ["docker", "image", "inspect", "--format", "{{.Created}}", "bot-bottle-claude:latest"],
            run.call_args.args[0],
        )
    def test_dies_on_inspect_failure(self):
        with patch.object(
            docker_mod.subprocess, "run", return_value=_fail("No such image"),
        ), patch.object(
            docker_mod, "die", side_effect=SystemExit("die"),
        ) as die:
            with self.assertRaises(SystemExit):
                docker_mod.image_created_at("missing:tag")
        die.assert_called_once()
        self.assertIn("missing:tag", die.call_args.args[0])
    def test_dies_on_invalid_timestamp(self):
        with patch.object(
            docker_mod.subprocess, "run",
            return_value=_ok(stdout="not-a-timestamp\n"),
        ), patch.object(
            docker_mod, "die", side_effect=SystemExit("die"),
        ) as die:
            with self.assertRaises(SystemExit):
                docker_mod.image_created_at("some:tag")
        die.assert_called_once()
        self.assertIn("some:tag", die.call_args.args[0])
    def test_parse_docker_timestamp_no_tzinfo_defaults_to_utc(self):
        # A bare datetime with no tz offset should be treated as UTC.
        dt = docker_mod._parse_docker_timestamp("2024-05-01T10:00:00.000000")
        self.assertIsNotNone(dt.tzinfo)
        self.assertEqual(timezone.utc, dt.tzinfo)
 class TestSave(unittest.TestCase):
    def test_save_runs_docker_save(self):
        with patch.object(
@@ -1,81 +0,0 @@
 """Unit: image_cache.py — check_stale / check_stale_path."""
 from __future__ import annotations
 import tempfile
 import unittest
 from datetime import datetime, timedelta, timezone
 from pathlib import Path
 from unittest.mock import patch
 from bot_bottle.image_cache import StaleImageError, check_stale, check_stale_path
 class TestCheckStale(unittest.TestCase):
    def _run(self, threshold: int, age_days: float) -> None:
        created = datetime.now(tz=timezone.utc) - timedelta(days=age_days)
        with patch("bot_bottle.image_cache.ConfigStore") as cs:
            cs.return_value.cached_image_stale_warning_days.return_value = threshold
            check_stale("test image", created)
    def test_negative_threshold_never_raises(self):
        # Threshold < 0 means the check is disabled — always passes.
        self._run(threshold=-1, age_days=9999)
    def test_zero_threshold_raises_immediately(self):
        # threshold=0 means any image is stale the moment it exists.
        with self.assertRaises(StaleImageError):
            self._run(threshold=0, age_days=0.1)
    def test_within_threshold_does_not_raise(self):
        # Age well under threshold — should pass silently.
        self._run(threshold=7, age_days=2)
    def test_at_threshold_does_not_raise(self):
        # Exactly at the boundary is fine (<=, not <).
        self._run(threshold=1, age_days=0.9999)
    def test_exceeds_threshold_raises(self):
        created = datetime.now(tz=timezone.utc) - timedelta(days=3)
        with patch("bot_bottle.image_cache.ConfigStore") as cs:
            cs.return_value.cached_image_stale_warning_days.return_value = 1
            with self.assertRaises(StaleImageError) as ctx:
                check_stale("agent image 'bot-bottle:latest'", created)
        self.assertIn("agent image", str(ctx.exception))
        self.assertIn("day(s) old", str(ctx.exception))
    def test_naive_datetime_treated_as_utc(self):
        # check_stale calls .astimezone(utc) on the input; naive datetimes
        # that would be interpreted as local time should still work.
        # We can't control the local tz in a unit test, so just ensure
        # no exception is thrown for a very recent naive datetime.
        naive_now = datetime(2099, 1, 1)  # far future, always "fresh"
        with patch("bot_bottle.image_cache.ConfigStore") as cs:
            cs.return_value.cached_image_stale_warning_days.return_value = 1
            # Should not raise — the image is brand new.
            check_stale("test image", naive_now)
 class TestCheckStalePath(unittest.TestCase):
    def test_delegates_to_check_stale_with_mtime(self):
        with tempfile.NamedTemporaryFile() as f:
            path = Path(f.name)
            with patch("bot_bottle.image_cache.check_stale") as mock_check:
                check_stale_path("some artifact", path)
            mock_check.assert_called_once()
            label, dt = mock_check.call_args.args
            self.assertEqual("some artifact", label)
            self.assertIsInstance(dt, datetime)
            self.assertIsNotNone(dt.tzinfo)
    def test_raises_stale_for_old_file(self):
        with tempfile.NamedTemporaryFile() as f:
            path = Path(f.name)
            with patch("bot_bottle.image_cache.ConfigStore") as cs:
                cs.return_value.cached_image_stale_warning_days.return_value = 0
                with self.assertRaises(StaleImageError):
                    check_stale_path("cached artifact", path)
 if __name__ == "__main__":
    unittest.main()
@@ -2,7 +2,6 @@
 from __future__ import annotations
 import dataclasses
 import unittest
 import tempfile
 from pathlib import Path
@@ -16,7 +15,6 @@ from bot_bottle.backend.macos_container import launch
 from bot_bottle.backend.macos_container.bottle_plan import MacosContainerBottlePlan
 from bot_bottle.egress import EgressPlan
 from bot_bottle.git_gate import GitGatePlan
 from bot_bottle.log import Die
 from bot_bottle.manifest import ManifestIndex
 _MANIFEST = ManifestIndex.from_json_obj({
@@ -83,7 +81,7 @@ def _plan(
        provisioned_env={"CODEX_HOME": "/run/codex-home"},
    )
    return cast(MacosContainerBottlePlan, SimpleNamespace(
-        spec=SimpleNamespace(image_policy="fresh"),
+        spec=SimpleNamespace(),
        manifest=_MANIFEST,
        stage_dir=stage_dir,
        slug="dev-abc",
@@ -294,7 +292,7 @@ class TestMacosContainerLaunchArgv(unittest.TestCase):
 def _build_plan(stage_dir: Path) -> MacosContainerBottlePlan:
    return MacosContainerBottlePlan(
-        spec=cast(BottleSpec, SimpleNamespace(image_policy="fresh")),
+        spec=cast(BottleSpec, SimpleNamespace()),
        manifest=_MANIFEST,
        stage_dir=stage_dir,
        git_gate_plan=cast(GitGatePlan, SimpleNamespace(upstreams=())),
@@ -339,9 +337,9 @@ class TestMacosContainerLaunchCommittedImage(unittest.TestCase):
        ), patch.object(
            launch.container_mod, "build_image", side_effect=fake_build,
        ), patch.object(launch, "info"):
-            images = launch.build_or_load_images(plan)
+            updated = launch._build_images(plan)
-        self.assertEqual("bot-bottle-committed-dev-abc:latest", images.agent)
+        self.assertEqual("bot-bottle-committed-dev-abc:latest", updated.image)
        self.assertEqual(1, len(calls))
        self.assertEqual(launch.SIDECAR_BUNDLE_IMAGE, calls[0][0])
@@ -360,89 +358,12 @@ class TestMacosContainerLaunchCommittedImage(unittest.TestCase):
        ), patch.object(
            launch.container_mod, "build_image", side_effect=fake_build,
        ):
-            images = launch.build_or_load_images(plan)
+            updated = launch._build_images(plan)
-        self.assertEqual("bot-bottle-agent:latest", images.agent)
+        self.assertEqual("bot-bottle-agent:latest", updated.image)
        self.assertEqual(2, len(calls))
        self.assertEqual("bot-bottle-agent:latest", calls[1][0])
 class TestMacosContainerLaunchCachedImages(unittest.TestCase):
    def setUp(self):
        self._tmp = tempfile.TemporaryDirectory()
        self.stage_dir = Path(self._tmp.name)
    def tearDown(self):
        self._tmp.cleanup()
    def _cached_plan(self) -> MacosContainerBottlePlan:
        return dataclasses.replace(
            _build_plan(self.stage_dir),
            spec=cast(BottleSpec, SimpleNamespace(image_policy="cached")),
        )
    def test_cached_mode_dies_when_agent_image_missing(self) -> None:
        plan = self._cached_plan()
        def image_exists(ref: str) -> bool:  # pylint: disable=unused-argument
            return False  # Nothing cached.
        with patch.object(
            launch, "read_committed_image", return_value="",
        ), patch.object(
            launch.container_mod, "image_exists", side_effect=image_exists,
        ), patch.object(
            launch, "die", side_effect=Die(),
        ):
            with self.assertRaises(Die):
                launch.build_or_load_images(plan)
    def test_cached_mode_dies_when_sidecar_image_missing(self) -> None:
        plan = self._cached_plan()
        def image_exists(ref: str) -> bool:
            return ref == plan.image  # Agent present; sidecar missing.
        with patch.object(
            launch, "read_committed_image", return_value="",
        ), patch.object(
            launch.container_mod, "image_exists", side_effect=image_exists,
        ), patch.object(
            launch, "die", side_effect=Die(),
        ):
            with self.assertRaises(Die):
                launch.build_or_load_images(plan)
    def test_cached_mode_both_present_returns_unchanged_plan(self) -> None:
        plan = self._cached_plan()
        with patch.object(
            launch, "read_committed_image", return_value="",
        ), patch.object(
            launch.container_mod, "image_exists", return_value=True,
        ), patch.object(
            launch.container_mod, "build_image",
        ) as build, patch.object(launch, "info"):
            images = launch.build_or_load_images(plan)
        build.assert_not_called()
        self.assertEqual(plan.image, images.agent)
    def test_committed_image_plus_cached_skips_sidecar_build(self) -> None:
        plan = self._cached_plan()
        with patch.object(
            launch, "read_committed_image",
            return_value="bot-bottle-committed-dev-abc:latest",
        ), patch.object(
            launch.container_mod, "image_exists", return_value=True,
        ), patch.object(
            launch.container_mod, "build_image",
        ) as build, patch.object(launch, "info"):
            images = launch.build_or_load_images(plan)
        # In cached mode with a committed image, no builds should fire.
        build.assert_not_called()
        self.assertEqual("bot-bottle-committed-dev-abc:latest", images.agent)
 if __name__ == "__main__":
    unittest.main()
@@ -273,71 +273,5 @@ resolver #2
            )
 class TestMacosContainerImageCreatedAt(unittest.TestCase):
    def _ok(self, stdout: str) -> "util.subprocess.CompletedProcess":  # type: ignore
        return util.subprocess.CompletedProcess(
            args=[], returncode=0, stdout=stdout, stderr="",
        )
    def _fail(self, stderr: str = "no such image") -> "util.subprocess.CompletedProcess":  # type: ignore
        return util.subprocess.CompletedProcess(
            args=[], returncode=1, stdout="", stderr=stderr,
        )
    def test_parses_iso_timestamp_from_dict(self):
        payload = '[{"created": "2025-06-01T12:00:00"}]'
        with patch.object(util.subprocess, "run", return_value=self._ok(payload)):
            dt = util.image_created_at("bot-bottle-agent:latest")
        self.assertEqual(2025, dt.year)
        self.assertEqual(6, dt.month)
        self.assertEqual(1, dt.day)
    def test_accepts_list_or_dict_input(self):
        # Container CLI may return a list; we take the first element.
        payload = '[{"created": "2024-01-15T08:30:00"}]'
        with patch.object(util.subprocess, "run", return_value=self._ok(payload)):
            dt = util.image_created_at("some-image:latest")
        self.assertEqual(2024, dt.year)
    def test_accepts_uppercase_Created_field(self):
        payload = '[{"Created": "2024-03-20T10:00:00"}]'
        with patch.object(util.subprocess, "run", return_value=self._ok(payload)):
            dt = util.image_created_at("some-image:latest")
        self.assertEqual(2024, dt.year)
        self.assertEqual(3, dt.month)
    def test_dies_on_nonzero_returncode(self):
        with patch.object(util.subprocess, "run", return_value=self._fail("not found")), \
             patch.object(util, "die", side_effect=SystemExit("die")) as die:
            with self.assertRaises(SystemExit):
                util.image_created_at("missing:tag")
        die.assert_called_once()
        self.assertIn("missing:tag", die.call_args.args[0])
    def test_dies_on_malformed_json(self):
        with patch.object(util.subprocess, "run", return_value=self._ok("not-json {")), \
             patch.object(util, "die", side_effect=SystemExit("die")) as die:
            with self.assertRaises(SystemExit):
                util.image_created_at("some:tag")
        die.assert_called_once()
    def test_dies_when_no_created_field(self):
        payload = '[{"id": "sha256:abc123"}]'
        with patch.object(util.subprocess, "run", return_value=self._ok(payload)), \
             patch.object(util, "die", side_effect=SystemExit("die")) as die:
            with self.assertRaises(SystemExit):
                util.image_created_at("some:tag")
        die.assert_called_once()
        self.assertIn("creation timestamp", die.call_args.args[0])
    def test_dies_on_invalid_timestamp_format(self):
        payload = '[{"created": "not-a-date"}]'
        with patch.object(util.subprocess, "run", return_value=self._ok(payload)), \
             patch.object(util, "die", side_effect=SystemExit("die")) as die:
            with self.assertRaises(SystemExit):
                util.image_created_at("some:tag")
        die.assert_called_once()
 if __name__ == "__main__":
    unittest.main()
@@ -1,58 +0,0 @@
 from __future__ import annotations
 import unittest
 from unittest.mock import patch
 from bot_bottle.backend.egress_apply import EgressApplyError
 from bot_bottle.backend.smolmachines import egress_apply
 from bot_bottle.backend.smolmachines.smolvm import SmolvmRunResult
 class TestFetchCurrentRoutes(unittest.TestCase):
    def test_reads_routes_from_sidecar_vm(self):
        with patch.object(
            egress_apply._smolvm,
            "machine_exec",
            return_value=SmolvmRunResult(0, "routes", ""),
        ) as exec_:
            self.assertEqual("routes", egress_apply.fetch_current_routes("dev-abc"))
        exec_.assert_called_once_with(
            "bot-bottle-sidecars-dev-abc",
            ["cat", "/etc/egress/routes.yaml"],
        )
    def test_read_failure_raises_apply_error(self):
        with patch.object(
            egress_apply._smolvm,
            "machine_exec",
            return_value=SmolvmRunResult(1, "", "nope"),
        ):
            with self.assertRaises(EgressApplyError):
                egress_apply.fetch_current_routes("dev-abc")
 class TestReload(unittest.TestCase):
    def test_sends_hup_to_sidecar_init(self):
        with patch.object(
            egress_apply._smolvm,
            "machine_exec",
            return_value=SmolvmRunResult(0, "", ""),
        ) as exec_:
            egress_apply.SmolmachinesEgressApplicator()._signal_bundle_reload("dev-abc")
        exec_.assert_called_once_with(
            "bot-bottle-sidecars-dev-abc",
            ["sh", "-c", "kill -HUP 1"],
        )
    def test_reload_failure_raises_apply_error(self):
        with patch.object(
            egress_apply._smolvm,
            "machine_exec",
            return_value=SmolvmRunResult(1, "", "nope"),
        ):
            with self.assertRaises(EgressApplyError):
                egress_apply.SmolmachinesEgressApplicator()._signal_bundle_reload("dev-abc")
 if __name__ == "__main__":
    unittest.main()
@@ -1,66 +0,0 @@
 """Unit: smolmachines active-agent enumeration."""
 from __future__ import annotations
 import json
 import subprocess
 import unittest
 from unittest.mock import patch
 from bot_bottle.backend.smolmachines import enumerate as _enumerate
 def _completed(
    stdout: str,
    returncode: int = 0,
 ) -> subprocess.CompletedProcess:  # type: ignore[type-arg]
    return subprocess.CompletedProcess(
        args=[],
        returncode=returncode,
        stdout=stdout,
        stderr="",
    )
 class TestEnumerateActive(unittest.TestCase):
    def test_skips_sidecar_vms(self):
        machines = [
            {"name": "bot-bottle-demo-abc12", "state": "running"},
            {"name": "bot-bottle-sidecars-demo-abc12", "state": "running"},
            {"name": "bot-bottle-stopped-xyz", "state": "stopped"},
            {"name": "other", "state": "running"},
        ]
        class _Metadata:
            agent_name = "demo"
            started_at = "2026-07-09T00:00:00Z"
            label = "Demo"
            color = "green"
        with patch(
            "bot_bottle.backend.smolmachines.enumerate.subprocess.run",
            return_value=_completed(json.dumps(machines)),
        ), patch(
            "bot_bottle.backend.smolmachines.enumerate._query_bundle_services",
            return_value={"demo-abc12": ("egress",)},
        ), patch(
            "bot_bottle.backend.smolmachines.enumerate.read_metadata",
            return_value=_Metadata(),
        ) as read_metadata:
            active = _enumerate.enumerate_active()
        self.assertEqual(1, len(active))
        self.assertEqual("demo-abc12", active[0].slug)
        self.assertEqual(("egress",), active[0].services)
        read_metadata.assert_called_once_with("demo-abc12")
    def test_invalid_smolvm_output_returns_empty(self):
        with patch(
            "bot_bottle.backend.smolmachines.enumerate.subprocess.run",
            return_value=_completed("not json"),
        ):
            self.assertEqual([], _enumerate.enumerate_active())
 if __name__ == "__main__":
    unittest.main()
@@ -187,54 +187,6 @@ class TestAgentFromPath(unittest.TestCase):
            dockerfile="/repo/Dockerfile",
        )
    def test_cached_policy_uses_existing_artifact_without_build(self):
        with tempfile.TemporaryDirectory(prefix="cached-smolmachine.") as tmp:
            digest = "abcdef0123456789"
            artifact = Path(tmp) / f"{digest}.smolmachine.smolmachine"
            artifact.write_text("")
            plan = SimpleNamespace(
                slug="dev-abc12",
                agent_image="bot-bottle-claude:latest",
                spec=SimpleNamespace(image_policy="cached"),
            )
            with patch.object(
                _launch_mod, "_SMOLMACHINE_CACHE_DIR", Path(tmp),
            ), patch.object(
                _launch_mod, "read_committed_image", return_value="",
            ), patch.object(
                _launch_mod.docker_mod, "image_exists", return_value=True,
            ), patch.object(
                _launch_mod.docker_mod, "image_id",
                return_value=f"sha256:{digest}fffffffffffffffff",
            ), patch.object(
                _launch_mod, "_ensure_smolmachine",
            ) as ensure:
                result = _launch_mod._agent_from_path(cast(Any, plan))
        self.assertEqual(artifact, result)
        ensure.assert_not_called()
    def test_cached_policy_dies_when_artifact_missing(self):
        with tempfile.TemporaryDirectory(prefix="cached-smolmachine.") as tmp:
            plan = SimpleNamespace(
                slug="dev-abc12",
                agent_image="bot-bottle-claude:latest",
                spec=SimpleNamespace(image_policy="cached"),
            )
            with patch.object(
                _launch_mod, "_SMOLMACHINE_CACHE_DIR", Path(tmp),
            ), patch.object(
                _launch_mod, "read_committed_image", return_value="",
            ), patch.object(
                _launch_mod.docker_mod, "image_exists", return_value=True,
            ), patch.object(
                _launch_mod.docker_mod, "image_id",
                return_value="sha256:abcdef0123456789fffffffffffffffff",
            ):
                from bot_bottle.log import Die
                with self.assertRaises(Die):
                    _launch_mod._agent_from_path(cast(Any, plan))
 if __name__ == "__main__":
    unittest.main()
@@ -1,325 +0,0 @@
 from __future__ import annotations
 import json
 import socket
 import subprocess
 import threading
 import unittest
 from unittest.mock import MagicMock, patch
 from bot_bottle.backend.smolmachines.port_forward import (
    ForwardSpec,
    ForwarderHandle,
    _CompletedProcess,
    _Forwarder,
    _pipe,
    main,
    start_forwarder,
    stop_forwarder,
 )
 def _echo_server() -> tuple[socket.socket, int]:
    listener = socket.create_server(("127.0.0.1", 0))
    port = int(listener.getsockname()[1])
    def run() -> None:
        with listener:
            conn, _ = listener.accept()
            with conn:
                while True:
                    data = conn.recv(65536)
                    if not data:
                        return
                    conn.sendall(data)
    threading.Thread(target=run, daemon=True).start()
    return listener, port
 class TestForwarderValidation(unittest.TestCase):
    def test_empty_specs_returns_noop_handle(self):
        handle = start_forwarder(())
        self.assertEqual((), handle.forwards)
        self.assertEqual(0, handle.process.poll())
        stop_forwarder(handle)
    def test_rejects_generic_localhost_listener(self):
        with self.assertRaises(SystemExit):
            start_forwarder((
                ForwardSpec(
                    label="egress",
                    listen_host="127.0.0.1",
                    listen_port=0,
                    target_host="127.0.0.1",
                    target_port=9099,
                ),
            ))
    def test_rejects_wildcard_listener(self):
        with self.assertRaises(SystemExit):
            start_forwarder((
                ForwardSpec(
                    label="egress",
                    listen_host="0.0.0.0",
                    listen_port=0,
                    target_host="127.0.0.1",
                    target_port=9099,
                ),
            ))
    def test_rejects_non_loopback_target(self):
        with self.assertRaises(SystemExit):
            start_forwarder((
                ForwardSpec(
                    label="egress",
                    listen_host="127.0.0.16",
                    listen_port=0,
                    target_host="192.0.2.10",
                    target_port=9099,
                ),
            ))
    def test_rejects_invalid_ports(self):
        with self.assertRaises(SystemExit):
            start_forwarder((
                ForwardSpec("bad-listen", "127.0.0.2", 70000, "127.0.0.1", 9099),
            ))
        with self.assertRaises(SystemExit):
            start_forwarder((
                ForwardSpec("bad-target", "127.0.0.2", 0, "127.0.0.1", 0),
            ))
    def test_completed_process_methods_are_noops(self):
        proc = _CompletedProcess()
        proc.terminate()
        proc.kill()
        self.assertEqual(0, proc.poll())
        self.assertEqual(0, proc.wait(timeout=1))
 class _FakeStdout:
    def __init__(self, line: str):
        self.line = line
        self.closed = False
    def readline(self) -> str:
        return self.line
    def close(self) -> None:
        self.closed = True
 class TestForwarderProcess(unittest.TestCase):
    def test_start_parses_ready_payload(self):
        payload = {
            "forwards": [{
                "label": "egress",
                "listen_host": "127.0.0.2",
                "listen_port": 61000,
                "target_host": "127.0.0.1",
                "target_port": 55000,
            }],
        }
        proc = MagicMock()
        proc.stdout = _FakeStdout(json.dumps(payload) + "\n")
        with patch(
            "bot_bottle.backend.smolmachines.port_forward.subprocess.Popen",
            return_value=proc,
        ) as popen:
            handle = start_forwarder((
                ForwardSpec("egress", "127.0.0.2", 0, "127.0.0.1", 55000),
            ))
        self.assertIs(proc, handle.process)
        self.assertEqual(61000, handle.forwards[0].listen_port)
        self.assertTrue(proc.stdout.closed)
        argv = popen.call_args.args[0]
        self.assertIn("--spec-json", argv)
    def test_start_dies_when_helper_exits_before_ready(self):
        proc = MagicMock()
        proc.stdout = _FakeStdout("")
        with patch(
            "bot_bottle.backend.smolmachines.port_forward.subprocess.Popen",
            return_value=proc,
        ):
            with self.assertRaises(SystemExit):
                start_forwarder((
                    ForwardSpec("egress", "127.0.0.2", 0, "127.0.0.1", 55000),
                ))
        proc.terminate.assert_called_once()
        proc.wait.assert_called_once_with(timeout=5)
    def test_start_dies_on_invalid_ready_payload(self):
        proc = MagicMock()
        proc.stdout = _FakeStdout('{"wrong": []}\n')
        with patch(
            "bot_bottle.backend.smolmachines.port_forward.subprocess.Popen",
            return_value=proc,
        ):
            with self.assertRaises(SystemExit):
                start_forwarder((
                    ForwardSpec("egress", "127.0.0.2", 0, "127.0.0.1", 55000),
                ))
        proc.terminate.assert_called_once()
        proc.wait.assert_called_once_with(timeout=5)
    def test_stop_kills_process_after_timeout(self):
        proc = MagicMock()
        proc.poll.return_value = None
        proc.wait.side_effect = [subprocess.TimeoutExpired("cmd", 5), 0]
        stop_forwarder(ForwarderHandle(process=proc, forwards=()))
        proc.terminate.assert_called_once()
        proc.kill.assert_called_once()
        self.assertEqual(2, proc.wait.call_count)
 class TestForwarding(unittest.TestCase):
    def test_forwards_bytes_both_directions(self):
        try:
            probe = socket.create_server(("127.0.0.2", 0))
        except OSError:
            self.skipTest("127.0.0.2 is not bindable on this host")
        else:
            probe.close()
        _listener, target_port = _echo_server()
        handle = start_forwarder((
            ForwardSpec(
                label="egress",
                listen_host="127.0.0.2",
                listen_port=0,
                target_host="127.0.0.1",
                target_port=target_port,
            ),
        ))
        try:
            bound = handle.forwards[0]
            with socket.create_connection((bound.listen_host, bound.listen_port)) as sock:
                sock.sendall(b"hello")
                self.assertEqual(b"hello", sock.recv(5))
        finally:
            stop_forwarder(handle)
 class TestForwarderInProcess(unittest.TestCase):
    def test_forwarder_serves_and_stops_in_process(self):
        _listener, target_port = _echo_server()
        forwarder = _Forwarder((
            ForwardSpec("egress", "127.0.0.2", 0, "127.0.0.1", target_port),
        ))
        forwarder.start()
        thread = threading.Thread(target=forwarder.serve, daemon=True)
        thread.start()
        try:
            bound = forwarder.bound[0]
            with socket.create_connection((bound.listen_host, bound.listen_port)) as sock:
                sock.sendall(b"ping")
                self.assertEqual(b"ping", sock.recv(4))
        finally:
            forwarder.stop()
            thread.join(timeout=2)
        self.assertFalse(thread.is_alive())
    def test_forwarder_logs_target_connect_failure(self):
        forwarder = _Forwarder((
            ForwardSpec("egress", "127.0.0.2", 0, "127.0.0.1", 1),
        ))
        forwarder.start()
        thread = threading.Thread(target=forwarder.serve, daemon=True)
        thread.start()
        try:
            bound = forwarder.bound[0]
            with patch("bot_bottle.backend.smolmachines.port_forward.warn") as warn:
                with socket.create_connection((bound.listen_host, bound.listen_port)):
                    pass
                for _ in range(100):
                    if warn.called:
                        break
                    threading.Event().wait(0.01)
            self.assertTrue(warn.called)
        finally:
            forwarder.stop()
            thread.join(timeout=2)
    def test_pipe_stops_when_recv_fails(self):
        src, dst = socket.socketpair()
        src.close()
        try:
            _pipe(src, dst)
        finally:
            dst.close()
    def test_pipe_stops_when_send_fails(self):
        src, src_peer = socket.socketpair()
        _dst_peer, dst = socket.socketpair()
        dst.close()
        try:
            src_peer.sendall(b"hello")
            src_peer.shutdown(socket.SHUT_WR)
            _pipe(src, dst)
        finally:
            src.close()
            src_peer.close()
            _dst_peer.close()
 class TestMain(unittest.TestCase):
    def test_main_starts_serves_and_stops_forwarder(self):
        calls: list[str] = []
        handlers = []
        class FakeForwarder:
            def __init__(self, specs):  # type: ignore[no-untyped-def]
                self.specs = specs
                self.bound = specs
            def start(self) -> None:
                calls.append("start")
            def serve(self) -> None:
                calls.append("serve")
            def stop(self) -> None:
                calls.append("stop")
        def record_signal(_signum, handler):  # type: ignore[no-untyped-def]
            handlers.append(handler)
        spec = ForwardSpec("egress", "127.0.0.2", 0, "127.0.0.1", 9099)
        with patch(
            "bot_bottle.backend.smolmachines.port_forward._Forwarder",
            FakeForwarder,
        ), patch(
            "bot_bottle.backend.smolmachines.port_forward.signal.signal",
            side_effect=record_signal,
        ), patch("builtins.print") as print_mock:
            self.assertEqual(
                0,
                main(("--spec-json", json.dumps([{
                    "label": spec.label,
                    "listen_host": spec.listen_host,
                    "listen_port": spec.listen_port,
                    "target_host": spec.target_host,
                    "target_port": spec.target_port,
                }]))),
            )
            handlers[0](15, None)
        self.assertEqual(["start", "serve", "stop", "stop"], calls)
        self.assertIn("forwards", print_mock.call_args.args[0])
 if __name__ == "__main__":
    unittest.main()
@@ -9,7 +9,6 @@ from __future__ import annotations
 import subprocess
 import tempfile
 import unittest
 from contextlib import ExitStack
 from dataclasses import replace
 from pathlib import Path
 from unittest.mock import MagicMock, patch
@@ -28,7 +27,6 @@ from bot_bottle.backend.smolmachines.bottle_plan import (
    SmolmachinesBottlePlan,
 )
 from bot_bottle.backend.smolmachines import launch as _launch
 from bot_bottle.backend.smolmachines import port_forward as _forward
 from bot_bottle.backend.smolmachines.launch import _bundle_launch_spec
 from bot_bottle.backend.util import AGENT_CA_PATH
 from bot_bottle.egress import EgressPlan, EgressRoute
@@ -434,7 +432,12 @@ class TestBundleLaunchSpec(unittest.TestCase):
    def test_canary_env_visible_to_smolvm_guest(self):
        plan = _plan(canary=True)
-        stamped = _launch._discover_urls(plan, "127.0.0.16", {9099: 65000})
+        with patch.object(
            _launch._bundle,
            "bundle_host_port",
            return_value="65000",
        ):
            stamped = _launch._discover_urls(plan, "127.0.0.16")
        self.assertEqual(
            "fake-canary-value",
@@ -503,109 +506,23 @@ class TestProvisionGitUser(unittest.TestCase):
        self.assertIn("bot@example.com", calls[0][0])
-class TestLaunchResourceWiring(unittest.TestCase):
+class TestProxyHost(unittest.TestCase):
-    def test_allocate_resources_uses_loopback_alias_and_bundle_name(self):
+    """_proxy_host returns the bridge gateway on Linux and the loopback
    alias on other platforms."""
    def test_linux_returns_bundle_gateway(self):
        plan = _plan()
-        with patch(
+        with patch("bot_bottle.backend.smolmachines.launch.platform.system",
-            "bot_bottle.backend.smolmachines.launch._loopback.ensure_pool",
+                   return_value="Linux"):
-        ) as ensure_pool, patch(
+            result = _launch._proxy_host(plan, "127.0.0.16")
-            "bot_bottle.backend.smolmachines.launch._loopback.allocate",
+        self.assertEqual(plan.bundle_gateway, result)
            return_value="127.0.0.16",
        ) as allocate:
            loopback_ip, network = _launch._allocate_resources(plan, ExitStack())
-        ensure_pool.assert_called_once_with()
+    def test_non_linux_returns_loopback(self):
        allocate.assert_called_once_with("demo-abc12")
        self.assertEqual("127.0.0.16", loopback_ip)
        self.assertEqual("bot-bottle-bundle-demo-abc12", network)
    def test_start_bundle_wraps_raw_vm_ports_with_forwarder_ports(self):
        plan = _plan(supervise=True)
        plan = replace(
            plan,
            git_gate_plan=replace(
                plan.git_gate_plan,
                upstreams=(GitGateUpstream(
                    name="bot-bottle",
                    upstream_url="ssh://git@host/repo.git",
                    upstream_host="host",
                    upstream_port="22",
                    identity_file="/tmp/key",
                    known_host_key="",
                ),),
            ),
        )
        stack = MagicMock(spec=ExitStack)
        raw_launch = MagicMock(raw_ports={9099: 55001, 9420: 55002, 9100: 55003})
        handle = _forward.ForwarderHandle(
            process=MagicMock(),
            forwards=(
                _forward.ForwardSpec("egress", "127.0.0.16", 65001, "127.0.0.1", 55001),
                _forward.ForwardSpec("git-http", "127.0.0.16", 65002, "127.0.0.1", 55002),
                _forward.ForwardSpec("supervise", "127.0.0.16", 65003, "127.0.0.1", 55003),
            ),
        )
        sidecar_artifact = Path("/cache/sidecar.smolmachine")
        with patch(
            "bot_bottle.backend.smolmachines.launch._provision_git_gate_keys",
            return_value=plan,
        ), patch(
            "bot_bottle.backend.smolmachines.launch._bundle.start_bundle_vm",
            return_value=raw_launch,
        ) as start_vm, patch(
            "bot_bottle.backend.smolmachines.launch._forward.start_forwarder",
            return_value=handle,
        ) as start_forwarder:
            stamped = _launch._start_bundle(plan, "net", "127.0.0.16", sidecar_artifact, stack)
        start_vm.assert_called_once()
        self.assertEqual(sidecar_artifact, start_vm.call_args.kwargs["from_path"])
        specs = start_forwarder.call_args.args[0]
        self.assertEqual(
            (
                _forward.ForwardSpec("egress", "127.0.0.16", 0, "127.0.0.1", 55001),
                _forward.ForwardSpec("git-http", "127.0.0.16", 0, "127.0.0.1", 55002),
                _forward.ForwardSpec("supervise", "127.0.0.16", 0, "127.0.0.1", 55003),
            ),
            specs,
        )
        self.assertEqual("http://127.0.0.16:65001", stamped.agent_proxy_url)
        self.assertEqual("127.0.0.16:65002", stamped.agent_git_gate_host)
        self.assertEqual("http://127.0.0.16:65003/", stamped.agent_supervise_url)
        self.assertEqual(2, stack.callback.call_count)
    def test_init_vm_repairs_ownership_then_waits_for_exec(self):
        plan = _plan()
-        with patch(
+        with patch("bot_bottle.backend.smolmachines.launch.platform.system",
-            "bot_bottle.backend.smolmachines.launch._smolvm.machine_exec",
+                   return_value="Darwin"):
-        ) as machine_exec, patch(
+            result = _launch._proxy_host(plan, "127.0.0.16")
-            "bot_bottle.backend.smolmachines.launch._smolvm.wait_exec_ready",
+        self.assertEqual("127.0.0.16", result)
        ) as wait_exec_ready:
            _launch._init_vm(plan)
        machine_exec.assert_called_once()
        argv = machine_exec.call_args.args[1]
        self.assertEqual(["sh", "-c"], argv[:2])
        self.assertIn("chown -R node:node /home/node", argv[2])
        wait_exec_ready.assert_called_once_with(plan.machine_name)
 class TestPortLabels(unittest.TestCase):
    def test_known_and_dynamic_port_labels_round_trip(self):
        for port, label in (
            (9099, "egress"),
            (9420, "git-http"),
            (9100, "supervise"),
            (12345, "port-12345"),
        ):
            self.assertEqual(label, _launch._label_for_port(port))
            self.assertEqual(port, _launch._port_for_label(label))
    def test_unknown_label_is_rejected(self):
        with self.assertRaises(ValueError):
            _launch._port_for_label("sidecar")
 class TestDiscoverUrls(unittest.TestCase):
@@ -627,20 +544,14 @@ class TestDiscoverUrls(unittest.TestCase):
                ),),
            ),
        )
-        stamped = _launch._discover_urls(
+        with patch.object(_launch._bundle, "bundle_host_port", return_value="9420"):
-            plan,
+            stamped = _launch._discover_urls(plan, "127.0.0.16")
-            "127.0.0.16",
+        self.assertEqual("127.0.0.16:9420", stamped.agent_git_gate_host)
            {9099: 65000, 9420: 65001},
        )
        self.assertEqual("127.0.0.16:65001", stamped.agent_git_gate_host)
    def test_supervise_url_set_when_supervise_present(self):
        plan = _plan(supervise=True)
-        stamped = _launch._discover_urls(
+        with patch.object(_launch._bundle, "bundle_host_port", return_value="55556"):
-            plan,
+            stamped = _launch._discover_urls(plan, "127.0.0.16")
            "127.0.0.16",
            {9099: 65000, 9100: 55556},
        )
        self.assertEqual("http://127.0.0.16:55556/", stamped.agent_supervise_url)
@@ -1,4 +1,9 @@
-"""Unit: bundle bringup primitives for the smolmachines backend."""
+"""Unit: bundle bringup primitives for the smolmachines backend
 (PRD 0023 chunk 2c).
 Tests mock `subprocess.run` and assert on the docker argv shape.
 The end-to-end integration smoke (real docker daemon, real
 bundle image) lands in chunk 2d."""
 from __future__ import annotations
@@ -9,15 +14,28 @@ from unittest.mock import patch
 from bot_bottle.backend.smolmachines.sidecar_bundle import (
    BundleLaunchSpec,
    allocate_raw_host_ports,
    bundle_container_name,
    bundle_network_name,
    create_bundle_network,
    ensure_bundle_image,
-    start_bundle_vm,
+    remove_bundle_network,
-    stop_bundle_vm,
+    start_bundle,
    stop_bundle,
 )
 def _ok(stdout: str = "", stderr: str = "") -> subprocess.CompletedProcess:  # type: ignore
    return subprocess.CompletedProcess(
        args=[], returncode=0, stdout=stdout, stderr=stderr,
    )
 def _fail(stderr: str = "boom") -> subprocess.CompletedProcess:  # type: ignore
    return subprocess.CompletedProcess(
        args=[], returncode=1, stdout="", stderr=stderr,
    )
 def _spec(**kwargs) -> BundleLaunchSpec:  # type: ignore
    defaults = dict(
        slug="demo-abc12",
@@ -50,6 +68,123 @@ class TestNamingHelpers(unittest.TestCase):
        )
 class TestNetworkLifecycle(unittest.TestCase):
    def _patch_run(self, **kwargs):  # type: ignore
        return patch(
            "bot_bottle.backend.smolmachines.sidecar_bundle.subprocess.run",
            **kwargs,
        )
    def test_create_argv_explicit_subnet_and_gateway(self):
        with self._patch_run(return_value=_ok()) as m:
            create_bundle_network("nn", "192.168.50.0/24", "192.168.50.1")
        self.assertEqual(
            ["docker", "network", "create",
             "--subnet", "192.168.50.0/24",
             "--gateway", "192.168.50.1",
             "nn"],
            m.call_args.args[0],
        )
    def test_create_treats_existing_network_as_success(self):
        with self._patch_run(return_value=_fail("network nn already exists")):
            # No SystemExit.
            create_bundle_network("nn", "192.168.50.0/24", "192.168.50.1")
    def test_create_other_failure_is_fatal(self):
        with self._patch_run(return_value=_fail("invalid subnet")):
            with self.assertRaises(SystemExit):
                create_bundle_network("nn", "bogus", "bogus")
    def test_remove_missing_network_is_idempotent(self):
        # No SystemExit / no warn-and-continue noise; missing
        # network is the expected case during a partial teardown.
        with self._patch_run(return_value=_fail("Error: No such network: nn")):
            remove_bundle_network("nn")
    def test_remove_clean_returns_success(self):
        with self._patch_run(return_value=_ok()):
            remove_bundle_network("nn")
 class TestStartBundle(unittest.TestCase):
    def _patch_run(self):
        return patch(
            "bot_bottle.backend.smolmachines.sidecar_bundle.subprocess.run",
            return_value=_ok(),
        )
    def test_argv_pins_ip_on_network(self):
        with self._patch_run() as m:
            start_bundle(_spec())
        argv = m.call_args.args[0]
        # --network NETNAME --ip <bundle-ip> on the docker run.
        self.assertIn("--network", argv)
        self.assertIn("bot-bottle-bundle-demo-abc12", argv)
        self.assertIn("--ip", argv)
        self.assertIn("192.168.50.2", argv)
        # Detached and auto-removed.
        self.assertIn("--detach", argv)
        self.assertIn("--rm", argv)
        # Container name uses the per-slug bundle prefix.
        i = argv.index("--name")
        self.assertEqual("bot-bottle-sidecars-demo-abc12", argv[i + 1])
        # Image at the end.
        self.assertEqual("bot-bottle-sidecars:latest", argv[-1])
    def test_daemons_env_passed_in(self):
        with self._patch_run() as m:
            start_bundle(_spec(daemons_csv="egress,supervise"))
        argv = m.call_args.args[0]
        self.assertIn("-e", argv)
        self.assertIn(
            "BOT_BOTTLE_SIDECAR_DAEMONS=egress,supervise",
            argv,
        )
    def test_environment_entries_pass_through(self):
        with self._patch_run() as m:
            start_bundle(_spec(environment=(
                "SUPERVISE_BOTTLE_SLUG=demo-abc12",
                "EGRESS_TOKEN_0",  # bare-name → host env inherit
            )))
        argv = m.call_args.args[0]
        self.assertIn("SUPERVISE_BOTTLE_SLUG=demo-abc12", argv)
        self.assertIn("EGRESS_TOKEN_0", argv)
    def test_volumes_render_with_ro_flag(self):
        with self._patch_run() as m:
            start_bundle(_spec(volumes=(
                ("/host/egress-ca.pem", "/home/mitmproxy/.mitmproxy/mitmproxy-ca.pem", True),
                ("/host/queue", "/run/supervise/queue", False),
            )))
        argv = m.call_args.args[0]
        self.assertIn(
            "/host/egress-ca.pem:/home/mitmproxy/.mitmproxy/mitmproxy-ca.pem:ro",
            argv,
        )
        self.assertIn("/host/queue:/run/supervise/queue", argv)
    def test_failure_dies(self):
        with patch(
            "bot_bottle.backend.smolmachines.sidecar_bundle.subprocess.run",
            return_value=_fail("invalid mount"),
        ):
            with self.assertRaises(SystemExit):
                start_bundle(_spec())
    def test_host_env_inherited_to_subprocess(self):
        # Bare-name entries in spec.environment rely on the docker
        # subprocess being run with the host env. Confirm `env=`
        # threads through.
        with patch(
            "bot_bottle.backend.smolmachines.sidecar_bundle.subprocess.run",
            return_value=_ok(),
        ) as m:
            start_bundle(_spec(), env={"FOO": "bar"})
        self.assertEqual({"FOO": "bar"}, m.call_args.kwargs["env"])
 class TestEnsureBundleImage(unittest.TestCase):
    def test_builds_sidecar_dockerfile_before_plain_docker_run(self):
        with patch(
@@ -65,97 +200,26 @@ class TestEnsureBundleImage(unittest.TestCase):
        self.assertEqual("Dockerfile.sidecars", kwargs["dockerfile"])
-class TestStartBundleVm(unittest.TestCase):
+class TestStopBundle(unittest.TestCase):
-    def test_allocate_raw_host_ports_returns_bindable_ports(self):
+    def _patch_run(self, **kwargs):  # type: ignore
-        raw_ports = allocate_raw_host_ports((9099, 9420))
+        return patch(
            "bot_bottle.backend.smolmachines.sidecar_bundle.subprocess.run",
            **kwargs,
        )
-        self.assertEqual({9099, 9420}, set(raw_ports))
+    def test_argv_force_removes(self):
-        for host_port in raw_ports.values():
+        with self._patch_run(return_value=_ok()) as m:
-            self.assertIsInstance(host_port, int)
+            stop_bundle("demo-abc12")
            self.assertGreater(host_port, 0)
        self.assertNotEqual(raw_ports[9099], raw_ports[9420])
    def test_creates_sidecar_vm_with_ports_volumes_and_env(self):
        calls: list[tuple[str, tuple[object, ...], dict[str, object]]] = []
        def record(name):  # type: ignore
            def inner(*args, **kwargs):  # type: ignore
                calls.append((name, args, kwargs))
            return inner
        with patch(
            "bot_bottle.backend.smolmachines.sidecar_bundle.allocate_raw_host_ports",
            return_value={9099: 55001, 9420: 55002},
        ), patch(
            "bot_bottle.backend.smolmachines.sidecar_bundle._smolvm.machine_create",
            side_effect=record("create"),
        ), patch(
            "bot_bottle.backend.smolmachines.sidecar_bundle._smolvm.machine_start",
            side_effect=record("start"),
        ), patch(
            "bot_bottle.backend.smolmachines.sidecar_bundle._smolvm.wait_exec_ready",
            side_effect=record("wait"),
        ):
            launch = start_bundle_vm(
                _spec(
                    daemons_csv="egress,git-http",
                    environment=("FOO=bar", "TOKEN"),
                    volumes=(("/host/routes", "/etc/egress", True),),
                    ports_to_publish=(9099, 9420),
                ),
                from_path=Path("/cache/sidecar.smolmachine"),
                host_env={"TOKEN": "secret"},
            )
        self.assertEqual({9099: 55001, 9420: 55002}, launch.raw_ports)
        create = calls[0]
        self.assertEqual("create", create[0])
        self.assertEqual(("bot-bottle-sidecars-demo-abc12",), create[1])
        self.assertEqual(Path("/cache/sidecar.smolmachine"), create[2]["from_path"])
        self.assertTrue(create[2]["net"])
        self.assertEqual(((55001, 9099), (55002, 9420)), create[2]["ports"])
        self.assertEqual((("/host/routes", "/etc/egress", True),), create[2]["volumes"])
        self.assertEqual(
-            {
+            ["docker", "rm", "-f", "bot-bottle-sidecars-demo-abc12"],
-                "BOT_BOTTLE_SIDECAR_DAEMONS": "egress,git-http",
+            m.call_args.args[0],
                "FOO": "bar",
                "TOKEN": "secret",
            },
            create[2]["env"],
        )
-
+    def test_missing_container_is_idempotent(self):
-class TestStopBundleVm(unittest.TestCase):
+        with self._patch_run(return_value=_fail(
-    def test_stops_then_deletes_sidecar_vm(self):
+            "Error: No such container: bot-bottle-sidecars-demo-abc12"
-        with patch(
+        )):
-            "bot_bottle.backend.smolmachines.sidecar_bundle._smolvm.machine_stop",
+            stop_bundle("demo-abc12")  # no raise
        ) as stop, patch(
            "bot_bottle.backend.smolmachines.sidecar_bundle._smolvm.machine_delete",
        ) as delete:
            stop_bundle_vm("demo-abc12")
        stop.assert_called_once_with("bot-bottle-sidecars-demo-abc12")
        delete.assert_called_once_with("bot-bottle-sidecars-demo-abc12")
    def test_stop_and_delete_errors_are_warnings(self):
        from bot_bottle.backend.smolmachines.smolvm import SmolvmError
        result = subprocess.CompletedProcess(
            args=[],
            returncode=1,
            stdout="",
            stderr="failed",
        )
        with patch(
            "bot_bottle.backend.smolmachines.sidecar_bundle._smolvm.machine_stop",
            side_effect=SmolvmError(["smolvm", "machine", "stop"], result),
        ), patch(
            "bot_bottle.backend.smolmachines.sidecar_bundle._smolvm.machine_delete",
            side_effect=SmolvmError(["smolvm", "machine", "delete"], result),
        ), patch(
            "bot_bottle.backend.smolmachines.sidecar_bundle.warn",
        ) as warn:
            stop_bundle_vm("demo-abc12")
        self.assertEqual(2, warn.call_count)
 if __name__ == "__main__":
@@ -106,22 +106,6 @@ class TestArgvShapes(unittest.TestCase):
        self.assertIn("--name", argv)
        self.assertIn("agent-xyz", argv)
    def test_machine_create_with_net_ports_and_volumes(self):
        with self._patch_run() as m:
            machine_create(
                "sidecar-xyz",
                from_path=Path("/stage/sidecar.smolmachine"),
                net=True,
                ports=((55000, 9099),),
                volumes=(("/host/routes", "/etc/egress", True),),
            )
        argv = m.call_args.args[0]
        self.assertIn("--net", argv)
        self.assertIn("-p", argv)
        self.assertIn("55000:9099", argv)
        self.assertIn("-v", argv)
        self.assertIn("/host/routes:/etc/egress:ro", argv)
    def test_machine_create_omits_net_when_no_allow_cidrs(self):
        with self._patch_run() as m:
            machine_create("agent-xyz", from_path=Path("/x.smolmachine"))
@@ -1,292 +0,0 @@
 """Unit: stale-image check functions across backends, and the
 BottleBackend.launch template method (prelaunch_checks + build_or_load_images).
 No real images or containers are used — all Docker/container/smolmachine
 calls are mocked at the module boundary."""
 from __future__ import annotations
 import tempfile
 import unittest
 from pathlib import Path
 from types import SimpleNamespace
 from typing import Any, cast
 from unittest.mock import MagicMock, patch
 def _bottle_cm(bottle: Any) -> MagicMock:
    """Return a mock context manager that yields `bottle`."""
    cm = MagicMock()
    cm.__enter__ = MagicMock(return_value=bottle)
    cm.__exit__ = MagicMock(return_value=False)
    return cm
 # ---------------------------------------------------------------------------
 # BottleBackend.launch template — prelaunch_checks + _build_or_load_images
 # ---------------------------------------------------------------------------
 class TestBottleBackendLaunchTemplate(unittest.TestCase):
    """Verify the concrete launch() method on BottleBackend calls
    _build_or_load_images and _launch_impl, and that prelaunch_checks is a no-op
    on the base class."""
    def _make_backend(self) -> Any:
        from bot_bottle.backend.docker.backend import DockerBottleBackend
        return DockerBottleBackend()
    def test_launch_delegates_to_build_or_load_and_launch_impl(self) -> None:
        from bot_bottle.backend import BottleImages
        backend = self._make_backend()
        plan = cast(Any, SimpleNamespace())
        bottle = MagicMock()
        images = BottleImages(agent="agent:latest", sidecar="sidecar:latest")
        with patch.object(
            backend, "_build_or_load_images", return_value=images,
        ) as build_mock, patch.object(
            backend, "_launch_impl",
            return_value=_bottle_cm(bottle),
        ) as impl_mock:
            with backend.launch(plan):
                pass
        build_mock.assert_called_once_with(plan)
        impl_mock.assert_called_once_with(plan, images)
    def test_noop_default_prelaunch_checks(self) -> None:
        from bot_bottle.backend.docker.backend import DockerBottleBackend
        from bot_bottle.backend import BottleBackend
        backend = DockerBottleBackend()
        # Base-class prelaunch_checks is a no-op — must not raise.
        BottleBackend.prelaunch_checks(backend, cast(Any, SimpleNamespace()))  # type: ignore[arg-type]
 # ---------------------------------------------------------------------------
 # Docker backend stale_checks
 # ---------------------------------------------------------------------------
 class TestDockerStaleChecks(unittest.TestCase):
    def _plan(self, policy: str = "cached", slug: str = "dev-abc") -> Any:
        spec = SimpleNamespace(image_policy=policy)
        provision = SimpleNamespace(image="bot-bottle-agent:latest")
        return cast(Any, SimpleNamespace(
            spec=spec,
            slug=slug,
            image="bot-bottle-agent:latest",
            agent_provision=provision,
        ))
    def test_fresh_policy_is_noop(self) -> None:
        from bot_bottle.backend.docker import launch as mod
        with patch.object(mod, "read_committed_image") as rci, \
             patch.object(mod, "check_stale") as cs:
            mod.stale_checks(self._plan("fresh"))
        rci.assert_not_called()
        cs.assert_not_called()
    def test_committed_image_present_checks_only_committed(self) -> None:
        from bot_bottle.backend.docker import launch as mod
        from datetime import datetime, timezone
        ts = datetime(2025, 1, 1, tzinfo=timezone.utc)
        with patch.object(mod, "read_committed_image", return_value="committed:latest"), \
             patch.object(mod.docker_mod, "image_exists", return_value=True), \
             patch.object(mod.docker_mod, "image_created_at", return_value=ts), \
             patch.object(mod, "check_stale") as cs:
            mod.stale_checks(self._plan())
        cs.assert_called_once()
        self.assertIn("committed:latest", cs.call_args.args[0])
    def test_no_committed_image_checks_agent_and_sidecar(self) -> None:
        from bot_bottle.backend.docker import launch as mod
        from datetime import datetime, timezone
        ts = datetime(2025, 1, 1, tzinfo=timezone.utc)
        with patch.object(mod, "read_committed_image", return_value=""), \
             patch.object(mod.docker_mod, "image_exists", return_value=True), \
             patch.object(mod.docker_mod, "image_created_at", return_value=ts), \
             patch.object(mod, "check_stale") as cs:
            mod.stale_checks(self._plan())
        # Should have been called for both agent and sidecar images.
        self.assertEqual(2, cs.call_count)
    def test_image_not_present_skips_check(self) -> None:
        from bot_bottle.backend.docker import launch as mod
        with patch.object(mod, "read_committed_image", return_value=""), \
             patch.object(mod.docker_mod, "image_exists", return_value=False), \
             patch.object(mod, "check_stale") as cs:
            mod.stale_checks(self._plan())
        cs.assert_not_called()
    def test_only_sidecar_missing_checks_only_agent(self) -> None:
        from bot_bottle.backend.docker import launch as mod
        from datetime import datetime, timezone
        ts = datetime(2025, 1, 1, tzinfo=timezone.utc)
        plan = self._plan()
        def image_exists(ref: str) -> bool:
            return ref == plan.image  # Only agent present; sidecar missing.
        with patch.object(mod, "read_committed_image", return_value=""), \
             patch.object(mod.docker_mod, "image_exists", side_effect=image_exists), \
             patch.object(mod.docker_mod, "image_created_at", return_value=ts), \
             patch.object(mod, "check_stale") as cs:
            mod.stale_checks(plan)
        self.assertEqual(1, cs.call_count)
        self.assertIn(plan.image, cs.call_args.args[0])
    def test_backend_prelaunch_checks_delegates(self) -> None:
        from bot_bottle.backend.docker.backend import DockerBottleBackend
        from bot_bottle.backend.docker import launch as mod
        backend = DockerBottleBackend()
        plan = self._plan()
        with patch.object(mod, "stale_checks") as sc:
            backend.prelaunch_checks(plan)  # type: ignore[arg-type]
        sc.assert_called_once_with(plan)
 # ---------------------------------------------------------------------------
 # smolmachines backend stale_checks
 # ---------------------------------------------------------------------------
 class TestSmolmachinesStaleChecks(unittest.TestCase):
    def _plan(self, policy: str = "cached") -> Any:
        return cast(Any, SimpleNamespace(
            spec=SimpleNamespace(image_policy=policy),
            slug="dev-abc",
            agent_image="bot-bottle-claude:latest",
        ))
    def test_fresh_policy_is_noop(self) -> None:
        from bot_bottle.backend.smolmachines import launch as mod
        with patch.object(mod, "read_committed_image") as rci, \
             patch.object(mod, "check_stale_path") as csp:
            mod.stale_checks(self._plan("fresh"))
        rci.assert_not_called()
        csp.assert_not_called()
    def test_committed_artifact_found_checks_it(self) -> None:
        from bot_bottle.backend.smolmachines import launch as mod
        with tempfile.NamedTemporaryFile(suffix=".smolmachine") as f:
            committed_path = f.name
            with patch.object(mod, "read_committed_image", return_value=committed_path), \
                 patch.object(mod.docker_mod, "image_exists", return_value=False), \
                 patch.object(mod, "check_stale_path") as csp:
                mod.stale_checks(self._plan())
        csp.assert_called_once()
        self.assertIn("agent smolmachine", csp.call_args.args[0])
    def test_no_committed_agent_artifact_in_cache_is_checked(self) -> None:
        from bot_bottle.backend.smolmachines import launch as mod
        digest = "abcdef0123456789"
        with tempfile.TemporaryDirectory() as tmp:
            artifact = Path(tmp) / f"{digest}.smolmachine.smolmachine"
            artifact.write_text("")
            with patch.object(mod, "_SMOLMACHINE_CACHE_DIR", Path(tmp)), \
                 patch.object(mod, "read_committed_image", return_value=""), \
                 patch.object(mod.docker_mod, "image_exists", return_value=True), \
                 patch.object(
                     mod.docker_mod, "image_id",
                     return_value=f"sha256:{digest}ffffffffffffffff",
                 ), \
                 patch.object(mod, "check_stale_path") as csp:
                mod.stale_checks(self._plan())
        # At least the agent artifact check ran.
        self.assertGreaterEqual(csp.call_count, 1)
    def test_sidecar_artifact_in_cache_is_checked(self) -> None:
        from bot_bottle.backend.smolmachines import launch as mod
        sidecar_digest = "fedcba9876543210"
        with tempfile.TemporaryDirectory() as tmp:
            sidecar_artifact = (
                Path(tmp) / f"{sidecar_digest}.smolmachine.smolmachine"
            )
            sidecar_artifact.write_text("")
            def image_exists(ref: str) -> bool:  # pylint: disable=unused-argument
                return True
            def image_id(ref: str) -> str:
                if ref == mod._bundle.SIDECAR_BUNDLE_IMAGE:  # type: ignore[attr-defined]
                    return f"sha256:{sidecar_digest}ffffffff"
                return "sha256:0000000000000000ffffffff"
            with patch.object(mod, "_SMOLMACHINE_CACHE_DIR", Path(tmp)), \
                 patch.object(mod, "read_committed_image", return_value=""), \
                 patch.object(mod.docker_mod, "image_exists", side_effect=image_exists), \
                 patch.object(mod.docker_mod, "image_id", side_effect=image_id), \
                 patch.object(mod, "check_stale_path") as csp:
                mod.stale_checks(self._plan())
        sidecar_calls = [c for c in csp.call_args_list if "sidecar" in c.args[0]]
        self.assertGreaterEqual(len(sidecar_calls), 1)
    def test_backend_prelaunch_checks_delegates(self) -> None:
        from bot_bottle.backend.smolmachines.backend import SmolmachinesBottleBackend
        from bot_bottle.backend.smolmachines import launch as mod
        backend = SmolmachinesBottleBackend()
        plan = self._plan()
        with patch.object(mod, "stale_checks") as sc:
            backend.prelaunch_checks(plan)  # type: ignore[arg-type]
        sc.assert_called_once_with(plan)
 # ---------------------------------------------------------------------------
 # macOS container backend stale_checks
 # ---------------------------------------------------------------------------
 class TestMacosContainerStaleChecks(unittest.TestCase):
    def _plan(self, policy: str = "cached", slug: str = "dev-abc") -> Any:
        return cast(Any, SimpleNamespace(
            spec=SimpleNamespace(image_policy=policy),
            slug=slug,
            image="bot-bottle-agent:latest",
        ))
    def test_fresh_policy_is_noop(self) -> None:
        from bot_bottle.backend.macos_container import launch as mod
        with patch.object(mod, "read_committed_image") as rci, \
             patch.object(mod, "check_stale") as cs:
            mod.stale_checks(self._plan("fresh"))
        rci.assert_not_called()
        cs.assert_not_called()
    def test_committed_image_present_checks_only_committed(self) -> None:
        from bot_bottle.backend.macos_container import launch as mod
        from datetime import datetime, timezone
        ts = datetime(2025, 1, 1, tzinfo=timezone.utc)
        with patch.object(mod, "read_committed_image", return_value="committed:latest"), \
             patch.object(mod.container_mod, "image_exists", return_value=True), \
             patch.object(mod.container_mod, "image_created_at", return_value=ts), \
             patch.object(mod, "check_stale") as cs:
            mod.stale_checks(self._plan())
        cs.assert_called_once()
        self.assertIn("committed:latest", cs.call_args.args[0])
    def test_no_committed_image_checks_agent_and_sidecar(self) -> None:
        from bot_bottle.backend.macos_container import launch as mod
        from datetime import datetime, timezone
        ts = datetime(2025, 1, 1, tzinfo=timezone.utc)
        with patch.object(mod, "read_committed_image", return_value=""), \
             patch.object(mod.container_mod, "image_exists", return_value=True), \
             patch.object(mod.container_mod, "image_created_at", return_value=ts), \
             patch.object(mod, "check_stale") as cs:
            mod.stale_checks(self._plan())
        self.assertEqual(2, cs.call_count)
    def test_image_not_present_skips_check(self) -> None:
        from bot_bottle.backend.macos_container import launch as mod
        with patch.object(mod, "read_committed_image", return_value=""), \
             patch.object(mod.container_mod, "image_exists", return_value=False), \
             patch.object(mod, "check_stale") as cs:
            mod.stale_checks(self._plan())
        cs.assert_not_called()
    def test_backend_prelaunch_checks_delegates(self) -> None:
        from bot_bottle.backend.macos_container.backend import MacosContainerBottleBackend
        from bot_bottle.backend.macos_container import launch as mod
        backend = MacosContainerBottleBackend()
        plan = self._plan()
        with patch.object(mod, "stale_checks") as sc:
            backend.prelaunch_checks(plan)  # type: ignore[arg-type]
        sc.assert_called_once_with(plan)
 if __name__ == "__main__":
    unittest.main()