feat(orchestrator): slice 4 — consolidated per-host sidecar (#352)

The core consolidation win: one persistent sidecar per host, shared by
every bottle, instead of a sidecar bundle per bottle. Safe to share
because the attribution invariant (source IP + identity token) lets the
sidecar map each request to the right bottle.

  * orchestrator/sidecar.py — a backend-neutral `Sidecar` lifecycle
    contract (mirrors LaunchBroker) + a `DockerSidecar` impl. The defining
    behaviour is idempotent singleton: `ensure_running` starts the instance
    if absent and is a no-op if it's already up, so N launches never spawn
    N sidecars; `stop` is idempotent.
  * orchestrator/dockerutil.py — a shared `run_docker` helper; DockerBroker
    now uses it too (DRY with slice 3).
  * service.py — the Orchestrator holds an optional `Sidecar`, exposes
    `ensure_sidecar()` + `sidecar_status()`.
  * control_plane.py — `GET /sidecar` reports it; __main__ gains
    `--sidecar-image` and ensures the single sidecar on startup.

Tests: unit (docker mocked) — is_running, ensure idempotent (no-op when up,
starts when absent), failure raises, stop idempotent; Orchestrator sidecar
wiring/status; control-plane /sidecar; integration (gated) — ensure is a
real idempotent singleton (one container after two ensures), stop removes.
Full suite green (only pre-existing /bin/sleep errors); integration
verified locally against real docker.

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

bot_bottle/orchestrator/service.py

@@ -19,17 +19,25 @@ from __future__ import annotations
 
 from .broker import LaunchBroker, LaunchRequest, sign_request
 from .registry import BottleRecord, RegistryStore
+from .sidecar import Sidecar
 
 
 class Orchestrator:
-    """Owns the registry + brokers launches. Backend-neutral."""
+    """Owns the registry + brokers launches, and manages the single
+    consolidated per-host sidecar. Backend-neutral (broker and sidecar
+    abstract the backend-native pieces)."""
 
     def __init__(
-        self, registry: RegistryStore, broker: LaunchBroker, sign_secret: bytes
+        self,
+        registry: RegistryStore,
+        broker: LaunchBroker,
+        sign_secret: bytes,
+        sidecar: Sidecar | None = None,
     ) -> None:
         self.registry = registry
         self._broker = broker
         self._secret = sign_secret
+        self._sidecar = sidecar
 
     def launch_bottle(
         self,
@@ -72,5 +80,23 @@ class Orchestrator:
         """Fail-closed attribution (delegates to the registry)."""
         return self.registry.attribute(source_ip, identity_token)
 
+    # --- consolidated sidecar ----------------------------------------------
+
+    def ensure_sidecar(self) -> None:
+        """Bring the single per-host sidecar up (idempotent). No-op when no
+        sidecar is configured."""
+        if self._sidecar is not None:
+            self._sidecar.ensure_running()
+
+    def sidecar_status(self) -> dict[str, object]:
+        """Report the shared sidecar for the control plane / console."""
+        if self._sidecar is None:
+            return {"configured": False}
+        return {
+            "configured": True,
+            "name": self._sidecar.name,
+            "running": self._sidecar.is_running(),
+        }
+
 
 __all__ = ["Orchestrator"]