feat(orchestrator): slice 5 — build the consolidated sidecar bundle image (#352)

Answers "where do we build the consolidated sidecar": nowhere, until now.

  * sidecar.py — `Sidecar.ensure_built()` (default no-op) + `DockerSidecar`
    now defaults its image to the real bundle (`bot-bottle-sidecars`) and
    `ensure_built()` builds it from `Dockerfile.sidecars` when
    `docker image inspect` shows it's missing (no-op when present or when no
    dockerfile is configured, e.g. a pre-pulled image). `image_exists()`
    added.
  * service.py — `ensure_sidecar()` now builds then runs.
  * __main__.py — `--sidecar` runs the consolidated bundle (build-if-missing).

Scope note: this builds + launches the bundle *container*; making the
running instance functional across bottles needs the per-bottle,
source-IP-keyed multi-tenant config + registration/reload, and routing
agent bottles to it — the next slices (added to PRD 0070's roadmap).

Tests: unit (docker mocked) — image_exists, ensure_built builds when
missing / no-op when present / no-op without a dockerfile / raises on build
failure; ensure_sidecar builds-then-runs; integration (gated, no heavy
build) — image_exists reflects real docker state. Full suite green (only
pre-existing /bin/sleep errors).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WBMWTEtQdJ4W5UrWuLHCck

bot_bottle/orchestrator/sidecar.py

@@ -18,15 +18,25 @@ launches never spawn N sidecars.
 from __future__ import annotations
 
 import abc
+import os
+from pathlib import Path
 
 from ..docker_cmd import run_docker
 
 SIDECAR_NAME = "bot-bottle-orch-sidecar"
 SIDECAR_LABEL = "bot-bottle-orch-sidecar=1"
 
+# The real sidecar-bundle image + its Dockerfile. Kept as a local constant
+# rather than imported from backend.docker.sidecar_bundle, which would drag
+# the whole backend layer into the lean orchestrator (see #359); unify when
+# that lands. Env override matches the backend's BOT_BOTTLE_SIDECAR_IMAGE.
+SIDECAR_BUNDLE_IMAGE = os.environ.get("BOT_BOTTLE_SIDECAR_IMAGE", "bot-bottle-sidecars:latest")
+SIDECAR_DOCKERFILE = "Dockerfile.sidecars"
+_REPO_ROOT = Path(__file__).resolve().parents[2]
+
 
 class SidecarError(Exception):
-    """The shared sidecar failed to start/stop (non-zero `docker` exit)."""
+    """The shared sidecar failed to build/start/stop (non-zero `docker` exit)."""
 
 
 class Sidecar(abc.ABC):
@@ -34,10 +44,16 @@ class Sidecar(abc.ABC):
 
     name: str
 
+    def ensure_built(self) -> None:
+        """Ensure the sidecar's image / rootfs exists, building it if needed.
+        Default: nothing to build (e.g. a stub or a pre-pulled image)."""
+        return
+
     @abc.abstractmethod
     def ensure_running(self) -> None:
         """Start the sidecar if it isn't already up. Idempotent: a no-op
-        when it's already running (that's the whole point — one per host)."""
+        when it's already running (that's the whole point — one per host).
+        Assumes the image exists — call `ensure_built()` first."""
 
     @abc.abstractmethod
     def is_running(self) -> bool:
@@ -49,11 +65,43 @@ class Sidecar(abc.ABC):
 
 
 class DockerSidecar(Sidecar):
-    """The consolidated sidecar as a single, fixed-name Docker container."""
+    """The consolidated sidecar as a single, fixed-name Docker container.
 
-    def __init__(self, image_ref: str, *, name: str = SIDECAR_NAME) -> None:
+    `image_ref` defaults to the real sidecar-bundle image; `ensure_built`
+    builds it from `Dockerfile.sidecars` when it's missing. (Note: slice 5
+    builds + launches the bundle container; wiring its per-bottle,
+    source-IP-keyed config is a later slice — see PRD 0070.)"""
+
+    def __init__(
+        self,
+        image_ref: str = SIDECAR_BUNDLE_IMAGE,
+        *,
+        name: str = SIDECAR_NAME,
+        build_context: Path | None = None,
+        dockerfile: str | None = SIDECAR_DOCKERFILE,
+    ) -> None:
         self.image_ref = image_ref
         self.name = name
+        self._build_context = build_context or _REPO_ROOT
+        self._dockerfile = dockerfile
+
+    def image_exists(self) -> bool:
+        return run_docker(["docker", "image", "inspect", self.image_ref]).returncode == 0
+
+    def ensure_built(self) -> None:
+        """Build the bundle image from its Dockerfile when it's missing.
+        No-op when the image is already present, or when no dockerfile is
+        configured (e.g. a pre-pulled image)."""
+        if self._dockerfile is None or self.image_exists():
+            return
+        proc = run_docker([
+            "docker", "build",
+            "-t", self.image_ref,
+            "-f", str(self._build_context / self._dockerfile),
+            str(self._build_context),
+        ])
+        if proc.returncode != 0:
+            raise SidecarError(f"sidecar image build failed: {proc.stderr.strip()}")
 
     def is_running(self) -> bool:
         proc = run_docker([
@@ -85,4 +133,7 @@ class DockerSidecar(Sidecar):
             raise SidecarError(f"sidecar failed to stop: {proc.stderr.strip()}")
 
 
-__all__ = ["Sidecar", "DockerSidecar", "SidecarError", "SIDECAR_NAME", "SIDECAR_LABEL"]
+__all__ = [
+    "Sidecar", "DockerSidecar", "SidecarError",
+    "SIDECAR_NAME", "SIDECAR_LABEL", "SIDECAR_BUNDLE_IMAGE",
+]